We Had a Single Source of Truth—and Still Had Stale State

We had already chosen a Single Source of Truth.

The canonical state file was correct.

Later work updated that canonical state.

And yet another document still contained an obsolete view of the current work.

At first glance, this looks like a simple documentation mistake:

Someone forgot to update a file.

The Git history showed something more useful.

The stale copy was already inconsistent at the commit that introduced the Single Source of Truth rule.

Later updates did not create the inconsistency. They widened it.

That distinction changed how I thought about the fix.

The migration looked correct

The repository used several documents to manage an ongoing technical-writing workflow.

One of them, active/WORK_STATUS.md, was selected as the sole mutable authority for current state.

At the same time, a worker-instruction document, AGENTS.md, was changed so that it explicitly said current state should not be duplicated there.

Conceptually, the new rule was:

WORK_STATUS owns current state.

AGENTS contains durable worker rules.

AGENTS should not duplicate mutable current state.

That is a reasonable authority model.

But the migration was incomplete.

One section of AGENTS.md had been cleaned up.

Another section still contained state such as:

current target = TOP-04
current work boundary = early evidence construction
formal draft work should not proceed yet

The problem was not only that those values existed in two places.

They were already different.

The canonical WORK_STATUS.md had moved further ahead than the remaining state text in AGENTS.md.

So the repository contained this contradiction:

AGENTS:
Do not duplicate current state here.

AGENTS, another section:
Here is the current state.

Later updates followed the new authority model

After that migration, the workflow continued.

The formal draft moved forward and was Human Approved.

WORK_STATUS.md and related project documents were updated.

AGENTS.md was not part of that particular state-update commit.

That alone is not evidence of a problem.

If WORK_STATUS.md is the mutable state authority, updating the authority instead of every historical copy is exactly what the new model says to do.

But because the old copy had not been removed during migration, the difference became more visible.

The interesting part came later.

AGENTS.md itself was edited several more times for unrelated policy changes.

The obsolete state section still survived.

So the persistence cannot be explained only as:

AGENTS was outside the write scope.

The file was opened and changed later.

The stale section simply was not identified as part of the authority migration problem.

That made the detection gap more important than the individual write scope.

The Single Source of Truth was not the problem

This case did not show that SSOT is ineffective.

The canonical state did its job.

The problem was migration completeness.

Declaring:

WORK_STATUS is now authoritative

does not automatically remove every older mutable copy.

A migration has at least two sides:

1. Select the new authority.

2. Remove, convert, or explicitly retire the old mutable replicas.

If step 2 is incomplete, a stale copy can survive outside the canonical update path.

That is especially easy to miss when the old copy appears inside a document that otherwise contains durable rules.

A policy document can slowly become a mixed object:

durable rules
+
temporary current-state snapshot

Once that happens, it becomes unclear which parts should change when project state changes.

The tempting fix was not the structural fix

The easiest correction would have been:

TOP-04 → whatever the latest target is

That would make the document look correct again.

But it would preserve the same ownership problem.

The next state transition could make the copy stale again.

Instead, the relevant section was changed so that values such as:

current target
next gate
evidence authority
per-item state

were no longer duplicated there.

The durable document now points back to the mutable authority.

Conceptually:

Before:

WORK_STATUS:
current target = X

AGENTS:
current target = X


After:

WORK_STATUS:
current target = X

AGENTS:
read current target from WORK_STATUS

The fix was therefore not:

Update the old value.

It was:

Remove ownership of that value from the wrong document.

Bounded write scopes were not the villain

There was another tempting explanation:

Strict write scopes caused the stale state because nobody was allowed to touch the other file.

The Git history did not support that conclusion.

A bounded change scope does something useful: it limits the files changed by a particular operation.

What it does not do is discover every pre-existing inconsistency outside that scope.

Those are different properties.

So a safer conclusion is:

A bounded change scope can preserve a pre-existing inconsistency
without being the cause of that inconsistency.

That matters in tightly controlled Git workflows.

“Only change the authorized files” is still a useful rule.

It just should not be confused with a repository-wide semantic consistency check.

Syntax can be correct while document roles are wrong

Nothing about this failure required broken Markdown or an invalid Git state.

A document could be syntactically valid.

The diff could be clean.

The intended files could be the only files changed.

The canonical state could be correct.

And the repository could still contain a contradiction about which document owns current state.

That is a different type of invariant.

For example:

AGENTS must not retain duplicated mutable current-state values
when WORK_STATUS is the canonical mutable authority.

A normal diff or syntax check does not automatically establish that invariant.

This does not mean every repository needs another giant validation framework.

In this case, the useful lesson was much smaller:

When converting a project to a Single Source of Truth, explicitly look for the old mutable copies once.

Remove them, convert them into references, or mark them as historical.

Then go back to building the actual thing.

What I took from the case

My practical takeaway is:

An SSOT migration is not finished when the new authority is declared. It is finished when the old mutable replicas no longer compete with it.

A few narrower lessons followed:

• Durable policy documents should avoid owning ephemeral project state when another file is authoritative.
• Updating a copied value is sometimes legitimate, especially for an explicitly subordinate summary.
• A bounded write scope protects scope; it does not repair unrelated existing inconsistencies.
• Cross-document semantic invariants are different from syntax and diff correctness.
• Sometimes the better fix is to remove state ownership rather than keep synchronizing copies.

This is one repository case, not evidence that every SSOT migration fails this way.

It is also not an AI-specific failure.

The mechanism is fundamentally about document authority, mutable state, and incomplete migration.

The full case study includes the commit chronology, evidence boundaries, and what each commit does and does not establish:

https://osiix.com/en/library/single-source-of-truth-stale-state.html

---

AI disclosure: AI-assisted drafting and review tools were used during preparation. The underlying Git evidence, claim boundaries, corrections, and publication decision were reviewed by the author.