The executable use cases: list, show, validate, run against the real tool, coverage, impact, scaffold.
The executable use cases: list, show, validate, run against the real tool, coverage, impact, scaffold.
state-mutating
rules
--json
A use case is a Markdown object with a scenario; run executes it in a disposable repository against bin/majordomus and records normalised evidence under the local half. scaffold writes drafts only, never a guarantee; coverage and impact read, they never write.
Only the codes this command can produce. The full contract is on the commands index.
0ok
2usage
10contract unmet
12missing artifact
13internal error
The executable use cases: listed, tallied, refused
usecase reads the use cases under the manifest's use-cases section, one Markdown file each with a scenario; it lists them, tallies every public command against them, and refuses a subcommand it does not know.
A fresh repository has the section and no use case
installed
yes
Given this repository
# A repository with Majordomus installed and projections generated, and one commit of work.
"$MJ" init >/dev/null
"$MJ" update >/dev/null
mkdir -p lib docs
echo a > lib/a
echo d > docs/d
git add . && git commit -qm base
Run
$ majordomus usecase list
Output contains
^use cases: 0 in \.ai/repo/use-cases$
exit0
init seeds the section with its context document and the taxonomy; the first use case is one file added beside them, discovered without a registry.
Every public command is a target; a fresh policy reports the gaps
installed
yes
Given this repository
# A repository with Majordomus installed and projections generated, and one commit of work.
"$MJ" init >/dev/null
"$MJ" update >/dev/null
mkdir -p lib docs
echo a > lib/a
echo d > docs/d
git add . && git commit -qm base
Run
$ majordomus usecase coverage
Output contains
^command +doctor +0 +0 +0 +gap +advisory$
required gap\(s\)
exit0
The denominator is the command registry, never a list written by hand. The skeleton policy makes a gap advisory; a repository that wants a gap to fail doctor, check and finish says `required` under use_cases.coverage.
An unknown subcommand is a usage error
installed
yes
Given this repository
# A repository with Majordomus installed and projections generated, and one commit of work.
"$MJ" init >/dev/null
"$MJ" update >/dev/null
mkdir -p lib docs
echo a > lib/a
echo d > docs/d
git add . && git commit -qm base
Run
$ majordomus usecase explain
Output contains
unknown subcommand 'explain'
exit2
The subcommands are list, show, validate, run, coverage, impact and scaffold; anything else is refused with the usage, never guessed.
Reference
The executable use cases of the repository: the Markdown objects under the manifest's
use-cases section, each a task somebody performs with the tool, the commands, rules,
claims, responsibilities and applications it names, and a scenario that proves it against
bin/majordomus. docs/USE_CASES.md is the contract; this section is the command.
list prints every use case with its category, status, whether it has a scenario and the
commands it names; show prints one file and the result of its last run. validate
resolves every reference (a command against the dispatch table, a doctrine against the
registry, a claim against docs/CLAIMS.yaml, a responsibility against
docs/RESPONSIBILITIES.yaml, an application both ways, a category against
taxonomy.yaml, a setup script and a stdin body against the fixtures, an MCP tool
against the executable's registry), refuses a key the schema does not declare, an id that
is not the file name, a duplicate, a body without its sections, a scenario step running a
command the use case does not list, and an active use case targeting a guarantee with no
scenario. doctor applies the same validation under majordomus.catalogue-integrity.
run executes each scenario in a disposable repository prepared by its setup script:
every step is one real invocation with argv from the file, its exit code and output are
asserted, and the evidence, normalised (paths, timestamps, ids, hashes, durations), is
written to .ai/local/evidence/use-cases/<id>.json; --out copies it elsewhere,
--keep leaves the repository for inspection, and the event use_cases.ran is
appended to the ledger. A use case without a scenario is reported as described, not run.
coverage tallies every public command of the registry, every guaranteed claim with a
responsibility and every MCP tool the executable projects against the active use cases
that name it, run it, and have passing evidence; the policy's use_cases.coverage says,
per class, whether a gap is required, advisory or off; --check exits 10 on a
required gap, as doctor, check and finish do under majordomus.use-case-coverage.
impact maps the files changed since --base (the upstream by default) and in the work
tree to the commands, rules, use cases, scenarios and behavioural cases they reach, and
names the run to do next. scaffold writes a draft use case for a gap from what the
registry, the command's fixture and the claims already know; a draft validates and runs
and never counts.
Exit codes: 0; 2 for a usage error; 10 when validation, a scenario or a required coverage
gap fails; 12 when the section, a use case or the registry is absent; 13 when a scenario
repository cannot be created.
Evidence
Every case below runs in CI on Linux and macOS. The site refuses to build if a public command has no behavioural case, no negative case, or no demonstration.