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.jsonWhat 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.