Trace a change to the context documents it affects

setup: installed
given:
  - 'a repository with Majordomus installed and projections generated, and one commit of work'
steps:
  - id: list
    run: ['context', 'list']
    note: 'every scoped document: id, path, scope, composition, providers, status'
    expect:
      exit: 0
      stdout_contains: ['ai.layer']
  - id: resolve
    run: ['context', 'resolve', 'lib']
    note: 'the documents that apply to a path, root to target, in effective order with provenance'
    expect:
      exit: 0
      stdout_contains: ['^01  ai.layer']
  - id: explain
    run: ['context', 'explain', 'lib']
    note: 'the same, with why each applies and why each candidate was left out'
    expect:
      exit: 0
      stdout_contains: ['ai.layer']
  - id: affected
    run: ['context', 'affected']
    note: 'which documents the working tree’s changes touch; nothing is changed here, so nothing is affected'
    expect:
      exit: 0
      tree_unchanged: true
  - id: sync
    run: ['context', 'check-sync']
    note: 'the tree validates, every projection matches its stamp, and nothing is affected'
    expect:
      exit: 0
      stdout_contains: ['in sync']
then:
  - 'resolution is deterministic: the same path gives the same ordered list'
  - 'a change under a scope names the document that governs it'
  - 'the projections are checked against the documents they were rendered from'

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, 5 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 context list exit 0

   every scoped document: id, path, scope, composition, providers, status

   ai.layer                     .ai/README.md                                subtree   final   *              active
   ai.repo                      .ai/repo/README.md                           subtree   extend  *              active
   ai.repo.adrs                 .ai/repo/adrs/README.md                      subtree   extend  *              active
   ai.repo.applications         .ai/repo/applications/README.md              subtree   extend  *              active
   ai.repo.deployments          .ai/repo/deployments/README.md               subtree   extend  *              active
   ai.repo.features             .ai/repo/features/README.md                  subtree   extend  *              active
   ai.repo.knowledge            .ai/repo/knowledge/README.md                 subtree   extend  *              active
   ai.repo.mesh                 .ai/repo/mesh/README.md                      subtree   extend  *              active
   ai.repo.profiles             .ai/repo/profiles/README.md                  subtree   extend  *              active
   ai.repo.project              .ai/repo/project/README.md                   subtree   extend  *              active
   ai.repo.prompts              .ai/repo/prompts/README.md                   subtree   extend  *              active
   ai.repo.rules                .ai/repo/rules/README.md                     subtree   extend  *              active
   ai.repo.sessions             .ai/repo/sessions/README.md                  subtree   extend  *              active
   ai.repo.skills               .ai/repo/skills/README.md                    subtree   extend  *              active
   ai.repo.use-cases            .ai/repo/use-cases/README.md                 subtree   extend  *              active
   ai.repo.why                  .ai/repo/why/README.md                       subtree   extend  *              active
   ai.repo.workflows            .ai/repo/workflows/README.md                 subtree   extend  *              active
   ai.repo.knowledge.candidates .ai/repo/knowledge/candidates/README.md      subtree   extend  *              active
   ai.repo.knowledge.curated    .ai/repo/knowledge/curated/README.md         subtree   extend  *              active
   ai.repo.rules.project        .ai/repo/rules/project/README.md             subtree   extend  *              active

   • exit 0
   • stdout_contains /ai.layer/
2. 2$ majordomus context resolve lib exit 0

   the documents that apply to a path, root to target, in effective order with provenance

   # effective context for lib
   01  ai.layer                   .ai/README.md                              subtree   final   *

   • exit 0
   • stdout_contains /^01 ai.layer/
3. 3$ majordomus context explain lib exit 0

   the same, with why each applies and why each candidate was left out

   # effective context for lib
   01  ai.layer                   .ai/README.md                              subtree   final   *
       applies: the tree root; the target is outside .ai/
   
   # left out
   (nothing: every candidate applies)
   
   # order
   depth (tree root first), then order, then path; never the order the filesystem lists files in
   fingerprint <sha><hash16>ef77ca97

   • exit 0
   • stdout_contains /ai.layer/
4. 4$ majordomus context affected exit 0

   which documents the working tree’s changes touch; nothing is changed here, so nothing is affected

   • exit 0
5. 5$ majordomus context check-sync exit 0

   the tree validates, every projection matches its stamp, and nothing is affected

   OK   context     .ai/ — 20 document(s) validate
   OK   context     AGENTS.md — projection for agents matches its stamp and the policy as it is
   OK   context     CLAUDE.md — projection for claude-code matches its stamp and the policy as it is
   OK   context     GEMINI.md — projection for gemini matches its stamp and the policy as it is
   context check-sync: in sync (20 document(s), 3 projection(s), 0 affected)

   • exit 0
   • stdout_contains /in sync/

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 contextWhat the next worker needs to know now, in authority order and within a budget.
• majordomus doctorIt checks governance only: is Majordomus itself healthy, and is every enforcement it declares actually wired here?

The rules that make it hold

• ✕blocking Context integrityEvery directory of the AI layer carries a context document, each one carries the contract, they compose into one deterministic chain for every path, and a tree that does not validate resolves nothing.
• ✕blocking AI layer integrityThe repository's AI layer is real: the manifest declares a format this executable reads and every section it names exists, the checkout-local half is ignored by git and nothing under it is tracked, and no project data remains under the pre-.ai .majordomus/ path.

Guarantees exercised

• ○guaranteed The context that applies to a path is composed from the layer's scoped documents, root to target, in one deterministic order with provenance, and a tree that does not validate resolves nothing
• ○guaranteed The impact of a change set on the scoped context is reported from git — the documents, the scopes below them, moves with their ancestry, tracked sources to review, and stale projections — and an unrelated change reports nothing
• ○guaranteed The repository's AI layer is one directory whose manifest names every section, readable without the tool

Related use cases

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

• Say what your work is for, once, and have every surface say itRecord an operational failure mode as one file and have the command line, the API, MCP and the website answer it without registering it anywhere.
• 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.
• 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.
• Move a repository from the pre-.ai layout to the layerSee what a migration would move, move it with a backup, and prove the result is a layer the tool reads.
• Read only the context that fits the budget, and know what was droppedAssemble the context a worker needs now in authority order, cut it to a line budget, and see every dropped section named with its reason.

The moments this answers

• → found the rule for that directory in a README no session ever loaded A local rule is either in the always-loaded file, where every session pays for it, or beside the code, where nothing relates it to the path being edited.
• → found code that contradicted a decision the repository had written down The decision was recorded and the implementation went the other way, because nothing relates a decision to the paths it governs.
• → found the same thing explained three times, slightly differently Every hand-maintained copy of a fact drifts on its own schedule, and a reader cannot tell which copy is the current one.