Add a use case and let the tool prove it

setup: installed
given:
  - 'Majordomus installed; the skeleton seeds the use-case section with no use case yet'
steps:
  - id: nothing-yet
    run: ['usecase', 'list']
    note: 'the section exists and is empty'
    expect:
      exit: 0
      stdout_contains: ['use cases: 0 in']
  - id: the-gaps
    run: ['usecase', 'coverage']
    note: 'every public command is a target; a fresh policy reports gaps and fails on none'
    expect:
      exit: 0
      stdout_contains: ['^command +doctor +0 +0 +0 +gap +advisory']
  - id: scaffold
    run: ['usecase', 'scaffold', '--for', 'command:doctor']
    note: 'a draft from what the registry, the fixture and the claims already know; nothing in it is verified'
    expect:
      exit: 0
      stdout_contains: ['wrote: \.ai/repo/use-cases/doctor-draft\.md']
  - id: validate
    run: ['usecase', 'validate']
    note: 'the draft resolves: its command, setup and category exist'
    expect:
      exit: 0
      stdout_contains: ['usecase validate: 0 failure']
  - id: run-it
    run: ['usecase', 'run', 'doctor-draft']
    note: 'the scaffolded scenario executes the real command in a disposable repository'
    expect:
      exit: 0
      stdout_contains: ['doctor-draft +pass']
  - id: still-a-gap
    run: ['usecase', 'coverage']
    note: 'a draft never counts; coverage moves when the use case is active'
    expect:
      exit: 0
      stdout_contains: ['^command +doctor +0 +0 +0 +gap']
then:
  - 'a use case is a file; everything else (the page, the links, the tally) follows'
  - 'a draft can run but cannot cover: status is authored, maturity is observed'

The scenario

Executed against the real tool, in a repository prepared by installed, 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, 6 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 usecase list exit 0

   the section exists and is empty

   use cases: 0 in .ai/repo/use-cases

   • exit 0
   • stdout_contains /use cases: 0 in/
2. 2$ majordomus usecase coverage exit 0

   every public command is a target; a fresh policy reports gaps and fails on none

   command   init                                         0   0   0  gap      advisory
   command   update                                       0   0   0  gap      advisory
   command   doctor                                       0   0   0  gap      advisory
   command   watch                                        0   0   0  gap      advisory
   command   start                                        0   0   0  gap      advisory
   command   context                                      0   0   0  gap      advisory
   command   checkpoint                                   0   0   0  gap      advisory
   command   handover                                     0   0   0  gap      advisory
   command   check                                        0   0   0  gap      advisory
   command   finish                                       0   0   0  gap      advisory
   command   history                                      0   0   0  gap      advisory
   command   decision                                     0   0   0  gap      advisory
   command   question                                     0   0   0  gap      advisory
   command   prompt                                       0   0   0  gap      advisory
   command   evidence                                     0   0   0  gap      advisory
   command   skills                                       0   0   0  gap      advisory
   command   capture                                      0   0   0  gap      advisory
   command   search                                       0   0   0  gap      advisory
   command   doctrine                                     0   0   0  gap      advisory
   command   plan                                         0   0   0  gap      advisory
   command   version                                      0   0   0  gap      advisory
   command   session                                      0   0   0  gap      advisory
   command   knowledge                                    0   0   0  gap      advisory
   command   adr                                          0   0   0  gap      advisory
   command   usecase                                      0   0   0  gap      advisory
   command   rules                                        0   0   0  gap      advisory
   command   migrate                                      0   0   0  gap      advisory
   command   recover                                      0   0   0  gap      advisory
   command   bench                                        0   0   0  gap      advisory
   command   archive                                      0   0   0  gap      advisory
   usecase coverage: 30 target(s), 0 covered, 0 partial, 0 required gap(s)  (columns: use cases, executable, evidence)

   • exit 0
   • stdout_contains /^command +doctor +0 +0 +0 +gap +advisory/
3. 3$ majordomus usecase scaffold --for command:doctor exit 0

   a draft from what the registry, the fixture and the claims already know; nothing in it is verified

   wrote: .ai/repo/use-cases/doctor-draft.md (draft; complete the narrative and the assertions, then set status: active)
   usecase scaffold: 1 draft(s) written

   • exit 0
   • stdout_contains /wrote: \.ai/repo/use-cases/doctor-draft\.md/
4. 4$ majordomus usecase validate exit 0

   the draft resolves: its command, setup and category exist

   OK   use-case    1 use case(s), 0 application(s) — every command, doctrine, claim, responsibility, application, category, setup and stdin resolves; every scenario step names a listed command
   usecase validate: 0 failure(s)

   • exit 0
   • stdout_contains /usecase validate: 0 failure/
5. 5$ majordomus usecase run doctor-draft exit 0

   the scaffolded scenario executes the real command in a disposable repository

   doctor-draft                           pass  1 step(s)
   usecase run: 1 scenario(s), 0 failed, 0 unmet, 0 not run; evidence under .ai/local/evidence/use-cases/

   • exit 0
   • stdout_contains /doctor-draft +pass/
6. 6$ majordomus usecase coverage exit 0

   a draft never counts; coverage moves when the use case is active

   command   init                                         0   0   0  gap      advisory
   command   update                                       0   0   0  gap      advisory
   command   doctor                                       0   0   0  gap      advisory
   command   watch                                        0   0   0  gap      advisory
   command   start                                        0   0   0  gap      advisory
   command   context                                      0   0   0  gap      advisory
   command   checkpoint                                   0   0   0  gap      advisory
   command   handover                                     0   0   0  gap      advisory
   command   check                                        0   0   0  gap      advisory
   command   finish                                       0   0   0  gap      advisory
   command   history                                      0   0   0  gap      advisory
   command   decision                                     0   0   0  gap      advisory
   command   question                                     0   0   0  gap      advisory
   command   prompt                                       0   0   0  gap      advisory
   command   evidence                                     0   0   0  gap      advisory
   command   skills                                       0   0   0  gap      advisory
   command   capture                                      0   0   0  gap      advisory
   command   search                                       0   0   0  gap      advisory
   command   doctrine                                     0   0   0  gap      advisory
   command   plan                                         0   0   0  gap      advisory
   command   version                                      0   0   0  gap      advisory
   command   session                                      0   0   0  gap      advisory
   command   knowledge                                    0   0   0  gap      advisory
   command   adr                                          0   0   0  gap      advisory
   command   usecase                                      0   0   0  gap      advisory
   command   rules                                        0   0   0  gap      advisory
   command   migrate                                      0   0   0  gap      advisory
   command   recover                                      0   0   0  gap      advisory
   command   bench                                        0   0   0  gap      advisory
   command   archive                                      0   0   0  gap      advisory
   usecase coverage: 30 target(s), 0 covered, 0 partial, 0 required gap(s)  (columns: use cases, executable, evidence)

   • exit 0
   • stdout_contains /^command +doctor +0 +0 +0 +gap/

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 usecaseThe executable use cases: list, show, validate, run against the real tool, coverage, impact, scaffold.
• 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 Use-case coverageEvery public command, and every guaranteed claim and MCP tool the policy asks for, is named and run by at least one active use case whose scenario executes against the real tool; a gap is a failure or a report according to the policy, never silence.
• ✕blocking Catalogue integrityEvery use case and application describes the tool in terms the tool has — each command, doctrine and claim it names exists, and the two catalogues reference each other in both directions.

Guarantees exercised

• ○guaranteed A use case or application cannot name a command, doctrine or claim that does not exist, and the two catalogues cannot disagree about which applies to which
• ○guaranteed Every public command is named and run by an active use case, a guaranteed claim or an MCP tool without one is a named gap, and the policy says which gaps fail doctor, check and finish

Related use cases

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

• 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.
• Prove a rule is actually enforced, not merely written downAnswer "is this rule real?" with a command rather than a reading of the source.
• 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.
• 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.
• 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.

The moments this answers

• → read a promise in the README that no test stood behind A sentence describing what the software does is written once and never connected to anything that would fail if it stopped being true.
• → pasted a command from the documentation and watched it fail Examples are written once, in prose, and nothing ever executes them again.
• → published a page that promised more than any test could support Public material is written by a different act from the code, so it drifts ahead of the behaviour and nothing brings it back.