A use case's scenario executes against the real tool in a disposable repository, every step's exit code and output are asserted, and the normalised evidence is what the site shows

What it means

A use case carries a scenario: a prepared repository and real invocations of bin/majordomus with their expected exit codes and output. majordomus usecase run executes it, step by step, in a temporary repository the setup script prepared, and records every step's command, exit code, output and assertions as evidence under the local half. The site generator runs the same scenarios and embeds the evidence, so a page that shows what a command printed shows what the tool did when the page was made, and scripts/generate-site-data --check proves it again in CI.

How it works

mj_uc_run_one in lib/usecase.sh creates the repository, sources the setup script from the fixtures (shared with the command demonstrations), runs each step with argv from the file (never a shell string), captures the combined output, asserts the exit code and every stdout_contains, stdout_not_contains, files_exist and files_contain expectation, normalises the output (the repository's path, the tool's path, the home directory, timestamps, task and session ids, record hashes, durations) and writes .ai/local/evidence/use-cases/<id>.json. The generator drops the timings and embeds the rest in site/data/generated/catalogue.json; the page template renders it.

How to see it

majordomus usecase run                          # every scenario; exit 10 on a failed step
majordomus usecase run prove-a-rule-is-enforced --keep
majordomus usecase show prove-a-rule-is-enforced   # the file and its last evidence
jq '.steps[] | {command, exit, result}' .ai/local/evidence/use-cases/prove-a-rule-is-enforced.json

What it does not cover

Evidence proves the scenario's assertions, nothing more: a scenario that asserts little proves little. Normalisation replaces values that vary by machine and time; a behaviour that differs by machine is not hidden by it and fails the check.

Why it exists

A pasted transcript in documentation is fiction the day after it is pasted. Evidence generated by executing the scenario, and checked against a clean regeneration, cannot drift from the tool.