Find out what has drifted since anyone last looked

setup: policy-drifted
given:
  - 'installed and generated, then the policy was edited without regenerating'
steps:
  - id: detect
    run: ['watch']
    note: 'the projection no longer matches the policy it was rendered from'
    expect:
      exit: 11
      stdout_contains: ['DRIFT']
  - id: regenerate
    run: ['update']
    note: 'the projections are rendered again from the edited policy'
    expect:
      exit: 0
      stdout_contains: ['CLAUDE.md']
  - id: clean
    run: ['watch']
    note: 'nothing disagrees any more'
    expect:
      exit: 0
      stdout_contains: ['watch: 0 drift']
  - id: what-happened
    run: ['history']
    note: 'the ledger says what changed and when'
    expect:
      exit: 0
      stdout_contains: ['projections.updated']
then:
  - 'drift is a deterministic disagreement between policy, projection and git, reported by name'

The scenario

Executed against the real tool, in a repository prepared by policy-drifted, every time this site is generated. What follows is not a description of what should happen; it is what happened.

What the tool did

Evidence of the run this page was generated from: pass, 4 step(s). Output is normalised: the repository's path, timestamps, ids and durations are placeholders; nothing else is edited.

Tested by test/cases/94_use_cases.sh, which runs every scenario and refuses a step whose recorded output is not what it produced.

1. 1$ majordomus watch exit 11

   the projection no longer matches the policy it was rendered from

   OK   knowledge   graph — buildable here: 100 node(s), 58 edge(s), compiled into a temporary file and removed; no stored index to go stale
   OK   layout      .ai/manifest.yaml — schema ai-repository/v1
   OK   layout      .ai/repo/scope.yaml — version 1; 14 in pathspec(s); every key is one the schema declares
   OK   layout      .ai/local/ — ignored, and nothing under it is tracked
   OK   layout      .ai/ — every section the manifest names exists; the layer is readable without the tool
   INFO checkpoint  - — no active task
   OK   records     ledger.jsonl — every line is a well-formed event
   OK   policy      39 key(s) — every policy value the code reads is declared, with no reader-side default
   OK   bootstrap   3 projection(s) — each points at .ai/README.md, carries no rule of its own and names only rules in force
   OK   catalogue   0 use case(s), 0 application(s) — every command, doctrine, claim, responsibility, category, setup and cross-reference resolves, both directions
   OK   context     .ai/ — 20 context document(s) carry the contract; ids unique, references resolve, no final document superseded, no cycle  [reproduce: majordomus context validate]
   DRIFT policy      .ai/repo/policy.yaml — policy or profiles changed after the last update of AGENTS.md CLAUDE.md GEMINI.md  [reproduce: majordomus update --dry-run]
   INFO adr         .ai/repo/adrs/ — no decisions; nothing to validate
   OK   records     decisions.md — every entry is attributable
   INFO project     .ai/repo/project — no canonical project model here; nothing to validate
   OK   command     surface — 30 public command(s), reconciled against the dispatch table  [reproduce: majordomus doctor]
   OK   command     coverage — every public command is exercised and refuted  [reproduce: bash test/run.sh 31_command_coverage]
   OK   resolver    handovers — no record for this worktree and branch (absence, not a stale match)  [reproduce: majordomus handover --resolve]
   OK   lifecycle   activity — 0 episode(s) opened here; too few to judge whether the writers stopped
   OK   knowledge   wiring — the close path and the compaction adapter call the deriver
   OK   knowledge   deriver — no episode has closed here; nothing to judge
   INFO project     .ai/repo/project — no canonical project model here; nothing to validate
   OK   projection  AGENTS.md — content matches its stamp
   OK   projection  CLAUDE.md — content matches its stamp
   OK   projection  GEMINI.md — content matches its stamp
   OK   context     builder — 21 lines, budget 300  [reproduce: majordomus context]
   OK   capture     share/schemas/majordomus/capture/capture.v1 — 2 file(s) describe majordomus.capture/v1 at the path the identifier derives: the record as JSON Schema, the document as protobuf
   OK   capture     .ai/local/prompts — ignored and untracked
   OK   capture     .ai/local/prompts — no records yet; the archive is empty
   OK   capture     .ai/local/prompts — every prompt is present as all three: the record, the Markdown and the YAML
   OK   prompts     .ai/local/prompts — the archive and every record in it are readable by their owner only
   OK   prompts     .ai/local/prompts — no records yet; the archive is empty
   OK   prompt      4 asset(s) — front matter valid, every token known
   OK   records     open-questions.md — every entry parses
   OK   retention   ledger — 1 lines, cap 5000
   OK   retention   handovers — 0 files, cap 200
   OK   retention   checkpoints — 0 files, cap 500
   OK   retention   sessions — 0 records, cap 500
   INFO project     .ai/repo/project — no canonical project model here; nothing to validate
   OK   rules       .ai/repo/rules/vendor/majordomus — every file matches the manifest (1 (1.0.0-alpha.8))
   OK   rules       61 rule(s) — resolve in one deterministic order; vendored baseline plus project rules, no override — 51 carry a validator, 10 are normative text this tool does not check
   OK   rules       blocking — all 44 blocking rule(s) carry a validator
   OK   schema      rules — 61 rule(s) resolve in one order: the vendored baseline in manifest order, then the project's, as a dependency graph
   OK   schema      share/kinds.yaml — 37 kind(s); every one that carries metadata declares a schema
   OK   schema      share/schemas — 54 schema(s), each valid JSON and each applied — by a kind, through an allow-list the tool reads, by a validator that names it, or as a generated document's contract (15)
   INFO scope       - — no active task
   OK   session     .ai/local/session-contexts — ignored and untracked
   OK   session     .ai/local/session-contexts — no working contexts yet; the store is empty
   INFO skill       .ai/repo/skills/ — no skills; nothing to validate
   OK   skill       reachable — no personal command or skill shares a name with a projected skill  [reproduce: majordomus run editors.status]
   INFO state       - — no active task
   ·    budget      watch — <timed against the policy budget>
   INFO state       - — no active task
   watch: 1 drift finding(s)

   • exit 11
   • stdout_contains /DRIFT/
2. 2$ majordomus update exit 0

   the projections are rendered again from the edited policy

   update AGENTS.md
   update CLAUDE.md
   update GEMINI.md
   generated 3 target(s) from policy a161e8624c17; each carries its own stamp

   • exit 0
   • stdout_contains /CLAUDE.md/
3. 3$ majordomus watch exit 0

   nothing disagrees any more

   OK   knowledge   graph — buildable here: 100 node(s), 58 edge(s), compiled into a temporary file and removed; no stored index to go stale
   OK   layout      .ai/manifest.yaml — schema ai-repository/v1
   OK   layout      .ai/repo/scope.yaml — version 1; 14 in pathspec(s); every key is one the schema declares
   OK   layout      .ai/local/ — ignored, and nothing under it is tracked
   OK   layout      .ai/ — every section the manifest names exists; the layer is readable without the tool
   INFO checkpoint  - — no active task
   OK   records     ledger.jsonl — every line is a well-formed event
   OK   policy      39 key(s) — every policy value the code reads is declared, with no reader-side default
   OK   bootstrap   3 projection(s) — each points at .ai/README.md, carries no rule of its own and names only rules in force
   OK   catalogue   0 use case(s), 0 application(s) — every command, doctrine, claim, responsibility, category, setup and cross-reference resolves, both directions
   OK   context     .ai/ — 20 context document(s) carry the contract; ids unique, references resolve, no final document superseded, no cycle  [reproduce: majordomus context validate]
   OK   policy      policy+profiles — match the last update (<hash12>)
   INFO adr         .ai/repo/adrs/ — no decisions; nothing to validate
   OK   records     decisions.md — every entry is attributable
   INFO project     .ai/repo/project — no canonical project model here; nothing to validate
   OK   command     surface — 30 public command(s), reconciled against the dispatch table  [reproduce: majordomus doctor]
   OK   command     coverage — every public command is exercised and refuted  [reproduce: bash test/run.sh 31_command_coverage]
   OK   resolver    handovers — no record for this worktree and branch (absence, not a stale match)  [reproduce: majordomus handover --resolve]
   OK   lifecycle   activity — 0 episode(s) opened here; too few to judge whether the writers stopped
   OK   knowledge   wiring — the close path and the compaction adapter call the deriver
   OK   knowledge   deriver — no episode has closed here; nothing to judge
   INFO project     .ai/repo/project — no canonical project model here; nothing to validate
   OK   projection  AGENTS.md — content matches its stamp
   OK   projection  CLAUDE.md — content matches its stamp
   OK   projection  GEMINI.md — content matches its stamp
   OK   context     builder — 21 lines, budget 300  [reproduce: majordomus context]
   OK   capture     share/schemas/majordomus/capture/capture.v1 — 2 file(s) describe majordomus.capture/v1 at the path the identifier derives: the record as JSON Schema, the document as protobuf
   OK   capture     .ai/local/prompts — ignored and untracked
   OK   capture     .ai/local/prompts — no records yet; the archive is empty
   OK   capture     .ai/local/prompts — every prompt is present as all three: the record, the Markdown and the YAML
   OK   prompts     .ai/local/prompts — the archive and every record in it are readable by their owner only
   OK   prompts     .ai/local/prompts — no records yet; the archive is empty
   OK   prompt      4 asset(s) — front matter valid, every token known
   OK   records     open-questions.md — every entry parses
   OK   retention   ledger — 2 lines, cap 5000
   OK   retention   handovers — 0 files, cap 200
   OK   retention   checkpoints — 0 files, cap 500
   OK   retention   sessions — 0 records, cap 500
   INFO project     .ai/repo/project — no canonical project model here; nothing to validate
   OK   rules       .ai/repo/rules/vendor/majordomus — every file matches the manifest (1 (1.0.0-alpha.8))
   OK   rules       61 rule(s) — resolve in one deterministic order; vendored baseline plus project rules, no override — 51 carry a validator, 10 are normative text this tool does not check
   OK   rules       blocking — all 44 blocking rule(s) carry a validator
   OK   schema      rules — 61 rule(s) resolve in one order: the vendored baseline in manifest order, then the project's, as a dependency graph
   OK   schema      share/kinds.yaml — 37 kind(s); every one that carries metadata declares a schema
   OK   schema      share/schemas — 54 schema(s), each valid JSON and each applied — by a kind, through an allow-list the tool reads, by a validator that names it, or as a generated document's contract (15)
   INFO scope       - — no active task
   OK   session     .ai/local/session-contexts — ignored and untracked
   OK   session     .ai/local/session-contexts — no working contexts yet; the store is empty
   INFO skill       .ai/repo/skills/ — no skills; nothing to validate
   OK   skill       reachable — no personal command or skill shares a name with a projected skill  [reproduce: majordomus run editors.status]
   INFO state       - — no active task
   ·    budget      watch — <timed against the policy budget>
   INFO state       - — no active task
   watch: 0 drift finding(s)

   • exit 0
   • stdout_contains /watch: 0 drift/
4. 4$ majordomus history exit 0

   the ledger says what changed and when

   <time>  projections.updated -                      <head>  targets=3
   <time>  projections.updated -                      <head>  targets=3

   • exit 0
   • stdout_contains /projections.updated/

Why the tool knows this

The chain from this page to the code: the use case names commands, rules and claims; each rule is dispatched from the registry and each claim names the test that proves it; the scenario above executed the commands. Nothing in this chain is prose about intent.

• majordomus watchWhat has drifted since the last update — policy, projections, state, retention.
• majordomus updateRegenerate every provider instruction file from the one policy, deterministically.
• majordomus historyRead the append-only ledger back, filtered by task, event or time.

The rules that make it hold

• ✕blocking Projection integrityEvery generated instruction file exists, matches the stamp it carries, and is never silently overwritten after a hand edit.
• ✕blocking Policy integrityThe policy and every profile parse, declare version 1, and carry no key the schema does not define.
• ✕blocking Ledger integrityEvery line of the append-only ledger is a well-formed event; the one durable record nothing else can reconstruct stays readable.
• ✕blocking Retention capsThe ledger, the handovers, the checkpoints and the session records stay under the caps the policy sets, so durable state does not grow without bound.

Guarantees exercised

• ○guaranteed Every generated instruction file carries its own stamp, and a hand edit is detected
• ○guaranteed Every finding carries the command that reproduces it
• ○guaranteed watch reports policy, projection, state, scope, handover, verification, staleness and retention drift

Related use cases

Computed from what they share: claims, rules, commands, category, applications. Nobody maintains this list.

• Keep every provider bootstrap thin, generated and within budgetRegenerate AGENTS.md, CLAUDE.md and the other provider files from one policy and prove they are stamped, point at the layer, stay under the line budget and resolve every reference.
• Adopt a repository that already has its own rulesInstall the supervisory layer into a repository with a hand-written CLAUDE.md, without the tool taking ownership of a file somebody else wrote.
• Read back what happened, and keep the ledger within its capRead the append-only ledger as operational history, filtered by task and event, validate every line, and rotate the oldest lines into an archive rather than deleting them.
• Extend what the executable serves by adding a file, never by rebuilding itAdd a rule, a prompt or a knowledge node to .ai/ and have it appear as an MCP resource, an HTTP route and a reference entry, with the same binary.
• Record a decision so the next worker can find itWrite down what was decided and why as state, then find it again without reading a conversation.

The moments this answers

• → opened CLAUDE.md and AGENTS.md and found two different rulebooks for one repository Each provider reads its own hand-edited file, nothing relates them, and which contract applies depends on which tool is open.
• → found a task "in progress" that nobody had touched for three weeks A status that was authored rather than computed is true at the moment of writing and decays silently from then on.
• → found five worktrees and could not say which of them still mattered Isolation is cheap to create and expensive to reason about: nothing records what a worktree was for or whether its work landed.
• → changed a policy in one place and found the old one still in force in three others A decision is updated at its source and the generated copies keep serving the previous version, with nothing reporting the difference.
• → had a green pipeline over generated files that no longer matched their sources Tests exercise the code and say nothing about the committed outputs derived from it, so the build is green and the artifacts are wrong.