Extend what the executable serves by adding a file, never by rebuilding it

setup: installed-wired
given:
  - 'the layer installed; the distribution declares the kinds it reads'
steps:
  - id: what-is-declared
    run: ['knowledge', 'sources']
    note: 'every source class the repository declares, with what it discovered'
    expect:
      exit: 0
      stdout_contains: ['^policy +shared +policy', '^knowledge sources: [0-9]+ file']
  - id: nothing-to-add
    run: ['init', '--extend']
    note: 'a new kind is a declaration under .ai/repo/knowledge, not a change to the tool'
    expect:
      exit: 0
      stdout_contains: ['nothing to add']
  - id: still-healthy
    run: ['doctor']
    note: 'the layer is real after the extension'
    expect:
      exit: 0
      stdout_contains: ['doctor: 0 failure']
then:
  - 'a kind added with its schema under .ai/repo/knowledge is served by the executable without a code change'

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 knowledge sources exit 0

   every source class the repository declares, with what it discovered

   context     shared      context    77afef342ab6  .ai/README.md
   context     shared      context    1aa0cfc9a98b  .ai/repo/README.md
   context     shared      context    210fe3243d2c  .ai/repo/adrs/README.md
   context     shared      context    6dc507447b9f  .ai/repo/applications/README.md
   context     shared      context    06b0af6581a4  .ai/repo/deployments/README.md
   context     shared      context    18111b83801f  .ai/repo/features/README.md
   context     shared      context    c1ae02e4d03c  .ai/repo/knowledge/README.md
   context     shared      context    9939471c0d0a  .ai/repo/knowledge/candidates/README.md
   context     shared      context    3be0a8483464  .ai/repo/knowledge/curated/README.md
   context     shared      context    53695b36fc07  .ai/repo/mesh/README.md
   context     shared      context    cb11ba2b8aeb  .ai/repo/profiles/README.md
   context     shared      context    b09939447728  .ai/repo/project/README.md
   context     shared      context    aaade142a03c  .ai/repo/prompts/README.md
   context     shared      context    fa27e74a38c5  .ai/repo/rules/README.md
   context     shared      context    39f8246be04e  .ai/repo/rules/project/README.md
   context     shared      context    07e9f6f77e38  .ai/repo/sessions/README.md
   context     shared      context    c08c8f28ce3d  .ai/repo/skills/README.md
   context     shared      context    99905d2cd5a9  .ai/repo/use-cases/README.md
   context     shared      context    95d10752d6ae  .ai/repo/why/README.md
   context     shared      context    124141e223e4  .ai/repo/workflows/README.md
   policy      shared      policy     663ed6512fa1  .ai/repo/policy.yaml
   scope       shared      scope      264ce22ddc67  .ai/repo/scope.yaml
   profile     shared      profile    2bbbd4d3b45b  .ai/repo/profiles/debugging.yaml
   profile     shared      profile    4e0b1ed0bb8c  .ai/repo/profiles/deep-work.yaml
   profile     shared      profile    4e4fe1af1c3d  .ai/repo/profiles/implementation.yaml
   profile     shared      profile    c3f4f310c328  .ai/repo/profiles/routine.yaml
   rule        shared      rule       fa27e74a38c5  .ai/repo/rules/README.md
   rule        shared      rule       39f8246be04e  .ai/repo/rules/project/README.md
   rule        shared      rule       8513b44dfe15  .ai/repo/rules/vendor/majordomus/rules/adr-integrity.v1.md
   rule        shared      rule       1c35b4925c67  .ai/repo/rules/vendor/majordomus/rules/ai-layout-integrity.v1.md
   rule        shared      rule       6b737b2767d6  .ai/repo/rules/vendor/majordomus/rules/blocker-resolution.v1.md
   rule        shared      rule       d6a33fc1b28c  .ai/repo/rules/vendor/majordomus/rules/bootstrap-integrity.v1.md
   rule        shared      rule       f8137aa6fcd4  .ai/repo/rules/vendor/majordomus/rules/candidates-reviewed.v1.md
   rule        shared      rule       826525b6e3a9  .ai/repo/rules/vendor/majordomus/rules/catalogue-integrity.v1.md
   rule        shared      rule       a56642f78cc5  .ai/repo/rules/vendor/majordomus/rules/checkpoint-freshness.v1.md
   rule        shared      rule       78f8269d371d  .ai/repo/rules/vendor/majordomus/rules/command-coverage.v1.md
   rule        shared      rule       e468040ac890  .ai/repo/rules/vendor/majordomus/rules/command-surface.v1.md
   rule        shared      rule       adf88f652092  .ai/repo/rules/vendor/majordomus/rules/completion-gates.v1.md
   rule        shared      rule       523fbb99c024  .ai/repo/rules/vendor/majordomus/rules/context-budget.v1.md
   rule        shared      rule       018f8d63e837  .ai/repo/rules/vendor/majordomus/rules/context-integrity.v1.md
   rule        shared      rule       f5336d1b0b06  .ai/repo/rules/vendor/majordomus/rules/dag-integrity.v1.md
   rule        shared      rule       d804fedbbf1a  .ai/repo/rules/vendor/majordomus/rules/decision-records.v1.md
   rule        shared      rule       072a8155ad66  .ai/repo/rules/vendor/majordomus/rules/decision-threshold.v1.md
   rule        shared      rule       78db07930224  .ai/repo/rules/vendor/majordomus/rules/deployment-contract.v2.md
   rule        shared      rule       2033490a50b9  .ai/repo/rules/vendor/majordomus/rules/doctrine-wiring-integrity.v1.md
   rule        shared      rule       afc294593532  .ai/repo/rules/vendor/majordomus/rules/enforcement-wiring.v1.md
   rule        shared      rule       db680840291e  .ai/repo/rules/vendor/majordomus/rules/handover-integrity.v1.md
   rule        shared      rule       3427bfc92e29  .ai/repo/rules/vendor/majordomus/rules/knowledge-graph.v1.md
   rule        shared      rule       eec2b2184f6c  .ai/repo/rules/vendor/majordomus/rules/knowledge-integrity.v1.md
   rule        shared      rule       33fc8bac42c8  .ai/repo/rules/vendor/majordomus/rules/knowledge-observed.v1.md
   rule        shared      rule       ebe4eb49d09c  .ai/repo/rules/vendor/majordomus/rules/layout-integrity.v1.md
   rule        shared      rule       d3c88435f42d  .ai/repo/rules/vendor/majordomus/rules/ledger-integrity.v1.md
   rule        shared      rule       628f11b96703  .ai/repo/rules/vendor/majordomus/rules/lifecycle-observed.v1.md
   rule        shared      rule       d1bb01668123  .ai/repo/rules/vendor/majordomus/rules/note-integrity.v1.md
   rule        shared      rule       88f7f9322b00  .ai/repo/rules/vendor/majordomus/rules/obligation-closure.v1.md
   rule        shared      rule       51e122071249  .ai/repo/rules/vendor/majordomus/rules/policy-completeness.v1.md
   rule        shared      rule       ae11a7b983a5  .ai/repo/rules/vendor/majordomus/rules/policy-integrity.v1.md
   rule        shared      rule       84f5b9f70992  .ai/repo/rules/vendor/majordomus/rules/principle-01-sessions-are-workers.v1.md
   rule        shared      rule       cbd041431c84  .ai/repo/rules/vendor/majordomus/rules/principle-02-minimum-sufficient-context.v1.md
   rule        shared      rule       c02aa47f226c  .ai/repo/rules/vendor/majordomus/rules/principle-03-externalise-decisions.v1.md
   rule        shared      rule       fb8aff3c3984  .ai/repo/rules/vendor/majordomus/rules/principle-04-one-worker-one-scope.v1.md
   rule        shared      rule       7fa1a1c5c27e  .ai/repo/rules/vendor/majordomus/rules/principle-05-justified-escalation.v1.md
   rule        shared      rule       87de78333726  .ai/repo/rules/vendor/majordomus/rules/principle-06-depth-is-not-verbosity.v1.md
   rule        shared      rule       a843319fda37  .ai/repo/rules/vendor/majordomus/rules/principle-07-define-done-first.v1.md
   rule        shared      rule       1b01d93b42fa  .ai/repo/rules/vendor/majordomus/rules/principle-08-verify-outcomes.v1.md
   rule        shared      rule       5eae52cc5589  .ai/repo/rules/vendor/majordomus/rules/principle-09-isolated-parallelism.v1.md
   rule        shared      rule       c7307cc9d919  .ai/repo/rules/vendor/majordomus/rules/principle-10-handovers-carry-state.v1.md
   rule        shared      rule       abbd45d5b53e  .ai/repo/rules/vendor/majordomus/rules/profile-requirements.v1.md
   rule        shared      rule       f2fd82b09aaa  .ai/repo/rules/vendor/majordomus/rules/project-integrity.v1.md
   rule        shared      rule       bc3eadf4f9f5  .ai/repo/rules/vendor/majordomus/rules/projection-integrity.v1.md
   rule        shared      rule       6a768205d5ed  .ai/repo/rules/vendor/majordomus/rules/prompt-capture.v1.md
   rule        shared      rule       5d4230b7c618  .ai/repo/rules/vendor/majordomus/rules/prompt-continuity.v1.md
   rule        shared      rule       c820246fbdc1  .ai/repo/rules/vendor/majordomus/rules/prompt-integrity.v1.md
   rule        shared      rule       9b68dbd49ac6  .ai/repo/rules/vendor/majordomus/rules/publication-currency.v1.md
   rule        shared      rule       58fca43f73a9  .ai/repo/rules/vendor/majordomus/rules/questions-store-integrity.v1.md
   rule        shared      rule       4043b457e438  .ai/repo/rules/vendor/majordomus/rules/record-changed-files.v1.md
   rule        shared      rule       6ac34a128a32  .ai/repo/rules/vendor/majordomus/rules/retention-caps.v1.md
   rule        shared      rule       959aad5152d0  .ai/repo/rules/vendor/majordomus/rules/roadmap-integrity.v1.md
   rule        shared      rule       e254bad15ecd  .ai/repo/rules/vendor/majordomus/rules/rule-package-integrity.v1.md
   rule        shared      rule       d73fb1b2f702  .ai/repo/rules/vendor/majordomus/rules/schema-integrity.v1.md
   rule        shared      rule       5bae41c80fda  .ai/repo/rules/vendor/majordomus/rules/scope-integrity.v1.md
   rule        shared      rule       2e5b9f5ad9c7  .ai/repo/rules/vendor/majordomus/rules/session-lifecycle.v1.md
   rule        shared      rule       8f779c44c5c2  .ai/repo/rules/vendor/majordomus/rules/session-records.v1.md
   rule        shared      rule       5beb962c3c18  .ai/repo/rules/vendor/majordomus/rules/skill-integrity.v1.md
   rule        shared      rule       70a6e878886b  .ai/repo/rules/vendor/majordomus/rules/state-consistency.v1.md
   rule        shared      rule       7e381d15f9f3  .ai/repo/rules/vendor/majordomus/rules/task-continuity.v1.md
   rule        shared      rule       2a25cd588cea  .ai/repo/rules/vendor/majordomus/rules/task-on-the-mesh.v1.md
   rule        shared      rule       1955176df430  .ai/repo/rules/vendor/majordomus/rules/use-case-coverage.v1.md
   rule        shared      rule       1a2e830a8912  .ai/repo/rules/vendor/majordomus/rules/verification-integrity.v1.md
   prompt      shared      prompt     aaade142a03c  .ai/repo/prompts/README.md
   prompt      shared      prompt     cd5ec861eb54  .ai/repo/prompts/continue.md
   prompt      shared      prompt     8a5e3920d4a3  .ai/repo/prompts/debug.md
   prompt      shared      prompt     17dba8771fc4  .ai/repo/prompts/handover.md
   prompt      shared      prompt     16d69f71530d  .ai/repo/prompts/review.md
   workflow    shared      document   124141e223e4  .ai/repo/workflows/README.md
   workflow    shared      document   a43c0936e7e3  .ai/repo/workflows/continuity.md
   workflow    shared      document   726b52e6993e  .ai/repo/workflows/plan.md
   workflow    shared      document   39db3723e051  .ai/repo/workflows/task-lifecycle.md
   workflow    shared      document   09ea91004f94  .ai/repo/workflows/use-cases.md
   session     shared      session    07e9f6f77e38  .ai/repo/sessions/README.md
   curated     shared      knowledge  3be0a8483464  .ai/repo/knowledge/curated/README.md
   candidates  shared      knowledge  9939471c0d0a  .ai/repo/knowledge/candidates/README.md
   use_case    shared      use-case   99905d2cd5a9  .ai/repo/use-cases/README.md
   taxonomy    shared      taxonomy   207a79579af9  .ai/repo/use-cases/taxonomy.yaml
   feature     shared      feature    18111b83801f  .ai/repo/features/README.md
   application shared      application 6dc507447b9f  .ai/repo/applications/README.md
   mesh-declaration shared      mesh-declaration 00e82f259df7  .ai/repo/mesh/mesh.yaml
   readme      shared      document   776e4d79cd72  AGENTS.md
   readme      shared      document   0c98332bdeb6  CLAUDE.md
   readme      shared      document   4cd27b17330c  GEMINI.md
   decisions   operational decision   0885fc07773e  .ai/local/state/decisions.md
   questions   operational question   ebeb154be99d  .ai/local/state/open-questions.md
   knowledge sources: 112 file(s) in scope all

   • exit 0
   • stdout_contains /^policy +shared +policy/
   • stdout_contains /^knowledge sources: [0-9]+ file/
2. 2$ majordomus init --extend exit 0

   a new kind is a declaration under .ai/repo/knowledge, not a change to the tool

   nothing to add; .ai/ already carries every file the skeleton seeds
   local state: .ai/local/state/ (ignored by git; this checkout's own)
   next: majordomus update      # generate the provider instruction files named in the policy
   next: majordomus doctor      # verify nothing is declared that is not wired
   hooks are not installed by init; add these two lines yourself, doctor verifies them:
     pre-commit: majordomus doctor || exit $?
     pre-push:   majordomus finish --check || exit $?

   • exit 0
   • stdout_contains /nothing to add/
3. 3$ majordomus doctor exit 0

   the layer is real after the extension

   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.9))
   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 /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 initCreate the .ai/ layer in this repository, and refuse to overwrite an existing one.
• majordomus updateRegenerate every provider instruction file from the one policy, deterministically.
• majordomus doctorIt checks governance only: is Majordomus itself healthy, and is every enforcement it declares actually wired here?
• majordomus knowledgeThe compiled index over what this repository states, and the candidate records it derives from what an episode did.

Over MCP the same layer is reached through majordomus_capabilities, majordomus_capability (the MCP surface).

The rules that make it hold

• ✕blocking AI layer integrityThe repository's AI layer is real: the manifest declares a format this executable reads and every section it names exists, the checkout-local half is ignored by git and nothing under it is tracked, and no project data remains under the pre-.ai .majordomus/ path.
• ✕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.

Guarantees exercised

• ○guaranteed What the MCP server serves is decided by the manifest, the declared source classes and each file's front matter, so an object added to the layer is served with no change to the executable
• ○guaranteed A file of the layer the MCP server cannot read is excluded with a diagnostic naming its path and the index says it is degraded, never silently smaller
• ○guaranteed Every capability of the Rust executable is defined once, and the registry refuses a duplicate id or a colliding projection name, naming both parties
• ○guaranteed MCP, HTTP, OpenAPI, Swagger UI, the capabilities commands and the generated reference are derived from the registry, and a change to one definition reaches every one of them
• ○guaranteed A capability of the Rust executable is declared once and composed into its module, the root composes modules, and the registry refuses a capability outside its module's namespace

Related use cases

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

• Say what your work is for, once, and have every surface say itRecord an operational failure mode as one file and have the command line, the API, MCP and the website answer it without registering it anywhere.
• See what the repository holds, and run one of its capabilities, without reading a fileOpen the shared server in a browser and get the whole layer as pages: what exists, where each thing came from, what depends on what, what is failing, and a form that runs any capability.
• Serve the repository's AI layer to every AI client through one shared serverOpen the repository in any client the tool declares a provider for (docs/generated/providers.md) and have each of them read the same rules, prompts and knowledge over MCP from one process, seeing each other.
• 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.
• Use the tool as your own in a shared repository, and propose it to the team when it has made its caseOne flag installs the same layer as yours alone: no tracked file changes, nothing is added to .gitignore, git status reads the same — the command checks it — and one more command hands the layer to the team.

The moments this answers

• → shipped an interface change whose contract document still described the old one A contract maintained by hand beside the code it describes goes stale on the first change that forgets it.
• → 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.