Trust the policy and the profiles only after they are validated

setup: installed-wired
given:
  - 'installed, and the two enforcements the policy declares are actually in place as hooks'
steps:
  - id: policy
    run: ['doctor']
    note: 'the policy parses, every value the code reads is declared with no reader-side default, every profile parses and the default profile exists, and every declared enforcement is reconciled against a hook that calls the tool'
    expect:
      exit: 0
      stdout_contains: ['^OK   policy      .ai/repo/policy.yaml — parsed', 'no reader-side default', '^OK   profiles', "default 'implementation' exists", '^OK   wiring      doctor-on-commit', '^OK   wiring      finish-on-push', 'doctor: 0 failure']
  - id: no-task
    run: ['check']
    note: 'outside a task the same contract answers with a precondition code, not a green run that checked nothing'
    expect:
      exit: 12
      stdout_contains: ['no active task']
then:
  - 'an unknown key in the policy or a profile is a parse failure, not an ignored line'
  - 'a policy value the code reads without a declaration is a failure'
  - 'exit 12 means a precondition is missing; it is never confused with a clean run'

The scenario

Executed against the real tool, in a repository prepared by installed-wired, 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, 2 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 doctor exit 0

   the policy parses, every value the code reads is declared with no reader-side default, every profile parses and the default profile exists, and every declared enforcement is reconciled against a hook that calls the tool

   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   knowledge   records — 0 record(s) valid against knowledge/v1; every reference resolves  [reproduce: majordomus knowledge check]
   OK   knowledge   candidates — 0 await review, cap 40
   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
   OK   layout      .ai/repo/prompts — present
   OK   layout      .ai/local/state/handovers — present, 0 record(s)
   OK   layout      .ai/local/state/checkpoints — present, 0 record(s)
   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      .ai/repo/policy.yaml — parsed, version 1
   OK   profiles    4 files — parsed; default 'implementation' exists
   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   doctrine    50 of 61 rule(s) carry a validator — validator, dispatch, propagation, test and CI resolve for every one of the 50; the remaining 11 declare no validator and this check does not examine them
   OK   wiring      doctor-on-commit — wired via .githooks/pre-commit
   OK   wiring      finish-on-push — wired via .githooks/pre-push
   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   budget      AGENTS.md — 42 lines, budget 150
   OK   links       AGENTS.md — all references resolve
   OK   counts      AGENTS.md — no hardcoded counts
   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)
   OK   records     0 record(s) — every changed_files names work, not generated or local state
   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 use-case    30 advisory gap(s) — not covered by an active use case, and the policy does not require it: command:init command:update command:doctor command:watch command:start command:context command:checkpoint command:handover command:check command:finish command:history command:decision command:question command:prompt command:evidence command:skills command:capture command:search command:doctrine command:plan command:version command:session command:knowledge command:adr command:usecase command:rules command:migrate command:recover command:bench command:archive  [reproduce: majordomus usecase coverage]
   OK   use-case    0 of 30 target(s) covered — every public command the policy requires is named and run by an active use case (policy use_cases.coverage)
   INFO env         - — bash <version>, git <version>, jq <version>, shellcheck present
   WARN clone       unpushed — commits on no remote: main(2) — work on one disk is invisible to every other session and cannot be integrated  [reproduce: git push -u origin <branch>]
   OK   clone       uncommitted — no linked worktree, so no uncommitted work can sit in one
   INFO clone       trunk — no remote-tracking branch, so this checkout's distance from the remote trunk cannot be measured
   INFO clone       release — no remote-tracking branch, so whether the trunk's landed work is released cannot be measured
   ·    reasoning   <decided by the advisors and the executable of the recording machine>
   ·    layout      - — <judged when the recording machine has built the executable>
   ·    budget      doctor — <timed against the policy budget>
   doctor: 0 failure(s)

   • exit 0
   • stdout_contains /^OK policy .ai/repo/policy.yaml — parsed/
   • stdout_contains /no reader-side default/
   • stdout_contains /^OK profiles/
   • stdout_contains /default 'implementation' exists/
   • stdout_contains /^OK wiring doctor-on-commit/
   • stdout_contains /^OK wiring finish-on-push/
   • stdout_contains /doctor: 0 failure/
2. 2$ majordomus check exit 12

   outside a task the same contract answers with a precondition code, not a green run that checked nothing

   majordomus: no active task (.ai/local/state/current.yaml); run: majordomus start

   • exit 12
   • stdout_contains /no active task/

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 doctorIt checks governance only: is Majordomus itself healthy, and is every enforcement it declares actually wired here?
• majordomus checkIs the current task still consistent with its policy, its scope and this checkout?

The rules that make it hold

• ✕blocking Policy integrityThe policy and every profile parse, declare version 1, and carry no key the schema does not define.
• ✕blocking Policy completenessEvery policy value the code reads is declared in the skeleton policy, and no reader carries its own default for one.
• ✕blocking Profile requirementsA profile may demand more than the shared contract — a regression test, a decision record — and finish refuses without it.
• ✕blocking Enforcement wiringEvery enforcement the policy declares is invoked by the hook it names, from a file the dispatcher will actually execute, without swallowing the exit code.

Guarantees exercised

• ○guaranteed The canonical policy is parsed and rejected if it contains an unknown key
• ○guaranteed Every profile is parsed, its unknown keys rejected, and the default profile proven to exist
• ○guaranteed Every enforcement the policy declares is reconciled against what actually runs
• ○guaranteed Exit codes are a contract, and no code means "warn and continue"

Related use cases

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

• Gate CI on the tool itself, with an exit code that is a contractRun the checks CI runs, read every finding with the command that reproduces it, and rely on exit codes that mean one thing each: no code means warn and continue.
• Prove a rule is actually enforced, not merely written downAnswer "is this rule real?" with a command rather than a reading of the source.
• 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.
• Prove the tool is fast, not assume it, and refuse a regressionMeasure every public command and every capability of the executable against a committed baseline, and let the check fail on a regression rather than a reviewer noticing later.
• Decide whether finished work is actually finishedEvaluate a contract line by line instead of accepting a sentence that says the work is done.

The moments this answers

• → watched the strongest model, at maximum effort, rename a variable Capability, reasoning depth, context size and verbosity collapse into one habit — everything on — because nothing ever named them separately.
• → 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.
• → 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.
• → let a fast, cheap session make a decision the whole codebase now lives with Capability is dialled down for cost and nothing distinguishes the tasks where that is prudent from the ones where it is expensive.