Prove the tool is fast, not assume it, and refuse a regression

setup: installed-wired
given:
  - 'installed and wired, nothing measured yet'
steps:
  - id: the-targets
    run: ['bench', '--list']
    note: 'every public command of the registry is a target; nothing is listed by hand'
    expect:
      exit: 0
      stdout_contains: ['^doctor +read-only', '^start +state-mutating']
  - id: measure-one
    run: ['bench', 'version', '--samples', '1', '--warmup', '0', '--mode', 'cold', '--no-save']
    note: 'one cold run, not saved'
    expect:
      exit: 0
      stdout_contains: ['^version +cold +ok +1 ']
  - id: within-budget
    run: ['doctor']
    note: 'doctor reports its own wall time against the policy budget'
    expect:
      exit: 0
      stdout_contains: ['budget', 'doctor: 0 failure']
then:
  - 'a latency figure comes from a recorded run, never from prose'

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, 3 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 bench --list exit 0

   every public command of the registry is a target; nothing is listed by hand

   command      class                      scenario
   init         generated-output-mutating  fixture fresh
   update       generated-output-mutating  fixture first-run
   doctor       read-only                  fixture not-wired
   watch        read-only                  fixture clean
   start        state-mutating             fixture begins
   context      read-only                  fixture with-task
   checkpoint   state-mutating             fixture records
   handover     state-mutating             fixture writes
   check        read-only                  fixture consistent
   finish       state-mutating             fixture all-unmet
   history      read-only                  fixture reads
   decision     state-mutating             fixture records
   question     state-mutating             fixture opens
   prompt       read-only                  fixture lists
   evidence     state-mutating             fixture records
   skills       read-only                  fixture lists
   capture      generated-output-mutating  fixture unconfigured
   search       read-only                  fixture matches
   doctrine     read-only                  fixture status
   plan         state-mutating             fixture validate
   version      read-only                  fixture prints
   session      state-mutating             fixture opens
   knowledge    state-mutating             fixture sources
   adr          state-mutating             fixture lists
   usecase      state-mutating             fixture lists-none
   rules        generated-output-mutating  fixture lists
   migrate      generated-output-mutating  fixture plans
   recover      state-mutating             fixture check
   archive      generated-output-mutating  fixture profiles

   • exit 0
   • stdout_contains /^doctor +read-only/
   • stdout_contains /^start +state-mutating/
2. 2$ majordomus bench version --samples 1 --warmup 0 --mode cold --no-save exit 0

   one cold run, not saved

   command      mode  status       n     p50     p95     p99     max  scenario
   version      cold  ok           1  <ms>  <ms>  <ms>  <ms>  fixture prints
   
   slowest by warm p95 (cold where warm does not apply):
     version      p95 <n> ms

   • exit 0
   • stdout_contains /^version +cold +ok +1 /
3. 3$ majordomus doctor exit 0

   doctor reports its own wall time against the policy budget

   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 /budget/
   • stdout_contains /doctor: 0 failure/

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 benchTime every public command of the registry, cold and warm, and compare with the baseline.
• majordomus doctorIt checks governance only: is Majordomus itself healthy, and is every enforcement it declares actually wired here?

The rules that make it hold

• ✕blocking Verification integrityCompletion requires a verification command that actually ran and exited 0 over a tree that did not change under it; its exit code, duration and tree are recorded.
• ✕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.
• ✕blocking Policy completenessEvery policy value the code reads is declared in the skeleton policy, and no reader carries its own default for one.

Guarantees exercised

• ○guaranteed Every gate the Rust executable must pass is one script, scripts/rust-check, and CI runs that script on every change that can reach the crate
• ○guaranteed The paths of the Rust executable that scale with the repository carry criterion benchmarks that build on every push, and every executable capability declares its benchmark policy, required or waived for a typed reason
• ○guaranteed Every externally callable operation of the Rust executable is a benchmark target with a denominator generated from the registry, and a missing case fails the structural check
• ○guaranteed After startup, no MCP or HTTP request of the Rust executable scans the repository, builds the index or the registry, derives a schema or builds a projection, and perf.counters proves it

Related use cases

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

• Trust the policy and the profiles only after they are validatedProve that the canonical policy parses with every key it needs declared, that every profile parses and the default exists, and that what the policy declares as enforced is what actually runs.
• 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.
• Decide what belongs in the AI context, as dataRead the repository’s declared scope policy, see which paths are in and out of the index, and let doctor and the knowledge index apply it rather than a hardcoded list.

The moments this answers

• → could not reproduce a result because nothing recorded the state it came from The result is recorded and the conditions that produced it are not, so it is an anecdote rather than a measurement.