How I found a divergence between an AI development control system and the code it was supposed to manage — and why AI-assisted development needs continuous reconciliation with reality, not just task execution.

It is surprisingly easy to build an AI-assisted development system that looks extremely well organized.

You have a task queue. Generated prompts. Explicit states:

ready
prompt_generated
completed
blocked

You have a roadmap, completion reports, and commit history.

The problem starts when those sources begin describing different versions of reality.

I ran into exactly that in a system where one repository acted as the development control plane while another contained the actual implementation.

At one point, the control plane effectively said:

latest completed task = 006DWO
006DWP = prompt_generated

The implementation repository said something very different:

006DWP implemented
006DWP committed
006DWP pushed to master

This was not uncommitted local work. 006DWP had a real commit lineage:

50155d2...
aa7daef...
d13a01f...

The final commit was already present in system-v2/master.

Individually, both systems looked healthy.

Together, they were no longer describing the same system.

The role of the control plane

The architecture deliberately separated orchestration from implementation:

ai-dev-platform
      ↓
 task specification
 generated prompt
 task state
 completion metadata
 roadmap
      ↓
system-v2
 actual implementation
 tests
 reports
 commits

The control-plane agent was responsible for sequencing, task specifications, generated prompts, queue state, and governance.

It was explicitly not allowed to silently implement changes in the target repository. Target-repository modifications had to correspond to an explicit task or workflow record.

That separation was useful. An agent responsible for controlling the work should not also be able to change the system it controls without leaving a trace.

But the separation introduces another problem.

The control plane has state.

The repository has state.

And those states can diverge.

How the drift appeared

For several earlier tasks, everything matched:

006DWN → completed
006DWO → completed

The implementation existed, the commits were known, and the control plane contained completion metadata.

For 006DWP, that chain broke.

The control plane contained:

task spec: yes
generated prompt: yes
status: prompt_generated
completion metadata: no

The implementation repository contained:

implementation: yes
tests/report: yes
commits: yes
pushed master: yes

The roadmap still claimed that the latest verified synchronization ended at 006DWO.

Worse, the same roadmap contained older sections describing repository states that predated several later changes.

The result was a document in which multiple historical states of the system all appeared to be current.

Why this is more dangerous than stale documentation

A stale README is usually an inconvenience.

A stale control plane makes decisions from an incorrect model of the world.

For example, the orchestration layer could still treat this as the current blocker:

operator_gated_redacted_this_jwt_validation_artifact_required...

But the implementation had already moved past it.

The actual next blocker was elsewhere:

existing_corpus_replay_not_executed

So the problem was not just an incorrect status label.

It changed the sequencing of the next work.

An AI agent that trusted the control plane without verification could begin solving a problem that was no longer current.

Why the repository cannot simply become the only source of truth

The obvious response is:

If the documentation and the code disagree, trust the code.

That is not enough either.

A repository can prove that an implementation exists.

It does not necessarily prove:

  • that the task passed the required validation;
  • that a report corresponds to the same commit;
  • that the result went through the required workflow;
  • that the evidence supports the claim being made;
  • that governance permits the next task to start.

For 006DWP, the implementation was real, but the evidence had a deliberately limited scope:

evidence class = deterministic_fixture
real corpus replay executed = false
corpus rows replayed = 0

So the correct conclusion was not:

006DWP proves the mechanism in reality

It was:

006DWP implementation exists
fixture mechanism proof exists
real corpus replay is still missing

That distinction matters.

Code truth and evidence truth are not the same thing.

I stopped looking for a single source of truth

In practice, it became more useful to think in terms of several independent layers of truth rather than one authoritative file:

task ledger
    ↓
generated task specification
    ↓
repository state
    ↓
commit history
    ↓
test/report artifacts
    ↓
evidence classification

If they agree, the system can proceed.

If they do not, it needs to enter reconciliation.

Before selecting the next task, I now want answers to at least four questions:

What does the control plane believe is complete?

What is actually present in master?

Which artifacts support the result?

What do those artifacts really allow us to claim?

That is no longer task execution.

It is state reconciliation.

Reconciliation instead of guessing

In this case, the audit produced a fairly clean picture.

What was proven:

system-v2/master contains 006DWP
implementation is committed and pushed
both repositories are clean
fixture proof exists

What was not proven:

real corpus replay executed
functionality proven
execution readiness proven
real-life functionality proven

And separately:

control plane completion state is stale

Once those facts were separated, the next step became straightforward.

There was no reason to implement 006DWP again.

There was no reason to jump ahead to live execution.

The control-plane ledger first had to be reconciled with implementation reality. Only then should the system continue from the actual current blocker.

Why AI makes this problem more visible

A human engineer who has been working in the same repository for days often remembers what happened yesterday.

An AI coding agent does not have that kind of durable operational memory.

It reconstructs the system state from the context it can see:

tasks
roadmap
reports
git state
prompts
handoffs

If those sources disagree, a stronger language model does not solve the underlying problem.

In some ways, it can make the problem more dangerous.

The better the model is at producing a coherent explanation from the information it receives, the easier it becomes to produce a very convincing plan from an incorrect initial state.

That is why I now treat reconciliation as part of the control plane itself, not as housekeeping.

The pattern that worked

Before generating the next implementation task, the system needs a small reality check:

control-plane task state
        ↕
target repository master
        ↕
commit / report evidence
        ↕
current blocker

If those layers disagree:

STOP TASK GENERATION
        ↓
RECONCILE
        ↓
CLASSIFY WHAT IS PROVEN
        ↓
UPDATE CONTROL STATE
        ↓
ONLY THEN SELECT NEXT TASK

That is cheaper than allowing several AI agents to continue working from different versions of history.

Rules I kept from the incident

A control plane is not automatically the truth just because it is called a control plane.

Its state must be verified too.

Code presence does not equal completion.

You still need tests, reports, lineage, and the correct evidence classification.

Documentation drift in an agentic system is an operational defect.

If documentation drives task selection, stale documentation is no longer cosmetic.

Do not confuse implementation truth with evidence truth.

The code may exist while the available proof remains fixture-only.

Do not select the next task before reconciliation.

Otherwise an AI system can become extremely efficient at solving the wrong problem.

Stale state should reduce system authority, not increase confidence.

When sources disagree, the correct response is not to pick the most convenient one. The disagreement itself must become explicit state.

Takeaway

The main lesson was simple.

An AI-assisted development system cannot be only:

plan → prompt → code → test

It also needs another loop:

observe reality
      ↓
compare with control state
      ↓
reconcile disagreement
      ↓
update authoritative state
      ↓
continue

In my case, one repository said that 006DWP was still only prompt_generated.

Another already contained three related commits and the completed implementation.

At the same time, the evidence was still fixture-only, and the real corpus replay contained:

0 rows

None of those facts could be discarded.

The system had to preserve all of them and reconstruct a consistent picture of reality.

For agentic development, that is one of the core responsibilities of a control plane:

not just to coordinate work, but to keep checking that its own model of the system still matches the system itself.