Hand the repository to someone who cannot clone it

setup: installed
given:
  - 'a repository with the layer installed and its files committed'
steps:
  - id: profiles
    run: ['archive', '--list']
    note: 'the snapshots are declarations in share/archive.yaml, not flags'
    expect:
      exit: 0
      stdout_contains: ['context', 'audit', 'governance']
  - id: what-would-travel
    run: ['archive', '--dry-run']
    note: 'the count archived is stated beside the count tracked, so a selection that matched nothing cannot look like one that matched everything'
    expect:
      exit: 0
      stdout_contains: ['profile context', 'tracked file', 'nothing written']
  - id: written-and-read-back
    run: ['archive', '--format', 'tar.gz']
    note: 'the archive is opened again before the command returns'
    expect:
      exit: 0
      stdout_contains: ['OK   archive', 'read back']
  - id: no-such-profile
    run: ['archive', 'nosuch']
    note: 'exit 12 is MISSING_ARTIFACT, and the message names the command that lists what exists'
    expect:
      exit: 12
      stdout_contains: ['no profile', 'archive --list']
then:
  - 'nothing untracked is in the archive, because the file set is the git index'
  - 'every entry carries the mode the index records, and the archive says so in its own manifest'
  - 'the archive was read back before the command returned, and an unreadable one is a failure rather than a delivery'

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, 4 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 archive --list exit 0

   the snapshots are declarations in share/archive.yaml, not flags

   context      Context for a language model  (default)
                Every tracked source, without the projections generated from it, under one orientation document.
   chatgpt      Sources for a ChatGPT project
                Every tracked source as token-bounded Markdown shards a ChatGPT project's file search indexes, without binaries, worktrees, links, build output, projections or recorded measurements.
   audit        A faithful copy the gates can run in
                Every tracked file, nothing dropped, with the modes and a local git index restored.
   governance   The operating contract alone
                The AI layer, the documentation and the provider bootstraps, without any code.
   archive: 4 profile(s)

   • exit 0
   • stdout_contains /context/
   • stdout_contains /audit/
   • stdout_contains /governance/
2. 2$ majordomus archive --dry-run exit 0

   the count archived is stated beside the count tracked, so a selection that matched nothing cannot look like one that matched everything

   archive: profile context — 106 of 106 tracked file(s), 255 KB of content
            nothing written (--dry-run)

   • exit 0
   • stdout_contains /profile context/
   • stdout_contains /tracked file/
   • stdout_contains /nothing written/
3. 3$ majordomus archive --format tar.gz exit 0

   the archive is opened again before the command returns

   OK   archive     repo-context-<date>.tar.gz — 110 entr(ies) read back, 1 of them executable
   archive: profile context — 106 of 106 tracked file(s), 255 KB of content
            wrote tmp/archives/repo-context-<date>.tar.gz (<size> KB)

   • exit 0
   • stdout_contains /OK archive/
   • stdout_contains /read back/
4. 4$ majordomus archive nosuch exit 12

   exit 12 is MISSING_ARTIFACT, and the message names the command that lists what exists

   majordomus: archive: no profile 'nosuch' (run: majordomus archive --list)

   • exit 12
   • stdout_contains /no profile/
   • stdout_contains /archive --list/

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 archiveTake a snapshot of the tracked tree that can be read, or checked, somewhere else.

Guarantees exercised

• ○guaranteed An archive that lost the file modes fails rather than travelling
• ○guaranteed The shell tool performs no network call, evaluates no generated text and deletes nothing recursively; its one declared request is the loopback peer probe

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.
• Decide what belongs in the AI context, as dataRead the repository’s declared scope policy, see which paths are in and out of the index, and let doctor and the knowledge index apply it rather than a hardcoded list.
• Refuse a directory of the layer that documents nothingA directory added under the layer without a context document fails validation by name, nothing resolves against the tree until it says what it is for, and the same hierarchy is readable over MCP and the API without running the gate.
• Keep what an episode learned, without a model and without a conversationRecord a decision inside an episode, derive it into a candidate knowledge record from the ledger, read the evidence that the derivation ran, and watch a second derivation change nothing.
• Keep the plan as milestones and issues the tool can validateDeclare milestones as outcomes and issues as execution contracts, and let the tool say what is ready and what is blocked.