Check the version before trusting a diagnosis

setup: bare
given:
  - 'an empty repository; nothing installed'
steps:
  - id: print
    run: ['version']
    note: 'the one string the projections, the ledger and the site derive their version from'
    expect:
      exit: 0
      stdout_contains: ['^majordomus [0-9]+\.[0-9]+\.[0-9]+(-(alpha|beta|rc)\.[0-9]+)?$']
  - id: refuse
    run: ['version', '--no-such-option']
    note: 'an argument the command does not know is a usage error, never ignored'
    expect:
      exit: 2
      stdout_contains: ['unknown option --no-such-option']
then:
  - 'the version needs no repository and no installation'
  - 'a usage error exits 2, as the exit-code contract says'

The scenario

Executed against the real tool, in a repository prepared by bare, 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, 2 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 version exit 0

   the one string the projections, the ledger and the site derive their version from

   majordomus 1.0.0-alpha.8

   • exit 0
   • stdout_contains /^majordomus [0-9]+\.[0-9]+\.[0-9]+(-(alpha|beta|rc)\.[0-9]+)?$/
2. 2$ majordomus version --no-such-option exit 2

   an argument the command does not know is a usage error, never ignored

   majordomus: version: unknown option --no-such-option

   • exit 2
   • stdout_contains /unknown option --no-such-option/

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 versionPrint the version, without needing a repository or an installation.

Guarantees exercised

• ○guaranteed Exit codes are a contract, and no code means "warn and continue"

Related use cases

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

• Gate CI on the tool itself, with an exit code that is a contractRun the checks CI runs, read every finding with the command that reproduces it, and rely on exit codes that mean one thing each: no code means warn and continue.
• 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.
• Install the tool in one command, on a machine with no toolchainPaste one line, get a verified binary for this machine, and run majordomus init — no git, no Rust, no Node, no Python, no root, and no way to install an archive whose digest does not match.
• Decide whether finished work is actually finishedEvaluate a contract line by line instead of accepting a sentence that says the work is done.
• Add a use case and let the tool prove itScaffold a draft for an uncovered command, validate it, run its scenario against the real tool, and see the coverage move.

The moments this answers

• → pasted a command from the documentation and watched it fail Examples are written once, in prose, and nothing ever executes them again.
• → could not say why one provider was used for that work and another for this Provider and model selection is made implicitly, per session, and recorded nowhere, so it cannot be reviewed or repeated.