Skip to content

The policy changed and its four copies did not

A decision is updated at its source and the generated copies keep serving the previous version, with nothing reporting the difference.

→ changed a policy in one place and found the old one still in force in three others

cost when it happens
high
how often
common
area
governance
documentation
recognised by
platform-team
enterprise
ai-native-team
engineering-lead

The moment

The policy was updated in March. The four files generated from it still carry the February version, because regenerating them was a step somebody had to remember, and nothing said they were stale.

Why it happens

Generation without a staleness check is a one-shot copy. The moment the source changes, the copies become claims about a past state, and they look exactly like claims about the current one. Nothing in the file says which generation produced it or from what.

Why a better model does not fix it

The worker reads the file it is given and applies it faithfully. It has no way to know the file is a stale projection of something else, because staleness is a property of the pair, and the worker only ever sees one half.

What it costs

Workers follow a superseded policy, and the failure surfaces as behaviour nobody asked for, weeks after the change that caused it. Tracing it back means discovering that the source of truth was never the source anything read.

What Majordomus does

Every generated projection is stamped with the hash of the policy it came from and the hash of its own content. doctor and watch compare both: a source that moved on, or a file that was edited by hand, is a named failing check. update regenerates deterministically and refuses to overwrite a hand edit until the diff has been seen. The same discipline covers every derived artifact the repository commits, and CI refuses a tree in which any of them differs from what its source produces.

Before and after

before   policy.yaml  (March)      CLAUDE.md, AGENTS.md, ... (February)

after    $ majordomus doctor
         FAIL projection  CLAUDE.md — generated from policy 3b0d79b4, current is 9f21c0aa
                          [reproduce: majordomus update --diff CLAUDE.md]

What it does not do

It does not decide whether the change should propagate; regeneration is explicit and its diff is reviewable. It stamps and compares — it does not merge a hand edit back into the source.

What this looks like

Concrete situations, one per audience. Each is declared in the moment's front matter, so the before and the after are data rather than prose a page could drift from.

  1. The interval that changed in one file platform-team

    before
    The checkpoint interval is raised in the policy; the instruction files keep telling every worker the old number.
    after
    `doctor` compares each projection with the stamp of the policy it was generated from and fails on a mismatch.

  2. The control of record enterprise

    before
    The approved policy and the file the workers actually read have been different for two quarters and nobody could have known.
    after
    The projection carries the policy hash and its own content hash; a difference is a failing check, not a discovery.

  3. Caught by the pipeline instead of by a reader ai-native-team

    before
    A stale generated file is noticed when somebody reads it closely, which is rarely.
    after
    CI regenerates and refuses a tree in which any derived artifact differs from its source.

How you would know

The observable symptoms this moment declares. They are the questionnaire on the index and the input of majordomus why diagnose; nothing else defines them.

  • A rule or setting was changed in one place this month and a stale copy of it is still being used. updated-one-copy
  • Nothing reports when a generated file no longer matches what it was generated from. no-staleness-signal
  • Regenerating the derived files depends on somebody remembering to. regenerate-by-memory

Where this lives in the tool

Everything below is read out of this moment's own front matter and resolved against the repository. A name here that did not exist would fail validation.

the commands that answer it

the capabilities of the executable that answer it

what it supervises — derived from the claims below

the claims that back this page, and the evidence behind each

the rules that govern it

  • majordomus.projection-integrity
  • project.derived-files-regenerated
  • majordomus.policy-integrity
  • majordomus.policy-completeness

the use cases that show the way out

If this one is familiar, so is the next

What this moment names, what names it, and what shares its area, audience or tags. The second and third are derived; only the first is written down.

All 38, and how they connect to the tool →