Record a decision as data, and prove the tool cannot accept it for you

setup: adr-related
given:
  - 'Majordomus installed, with one decision proposed and committed'
  - 'discovery is over the tracked tree, so a decision git does not hold is not yet part of the layer'
steps:
  - id: what-was-decided
    run: ['adr', 'list']
    note: 'one line per decision: identity, status, date, title'
    expect:
      exit: 0
      stdout_contains: ['adr-0001', 'proposed']
  - id: the-record-itself
    run: ['adr', 'show', 'adr-0001']
    note: 'the path, then the file as written: the provenance says the tool derived it'
    expect:
      exit: 0
      stdout_contains: ['schema: adr/v1', 'origin: extracted', 'file:docs/d']
  - id: the-set-is-sound
    run: ['adr', 'check']
    note: 'identities, statuses, supersession and every reference, in one pass'
    expect:
      exit: 0
      stdout_contains: ['every identity unique']
  - id: what-it-put-in-force
    run: ['adr', 'show', 'adr-0001']
    note: 'related is the forward edge: the rule the decision declares, the file it reaches'
    expect:
      exit: 0
      stdout_contains: ['related:', 'rule:majordomus.adr-integrity']
  - id: the-graph-reads-it-backwards
    run: ['knowledge', 'edges', '--type', 'declares']
    note: 'the same fact as an edge, with the front-matter key that stated it as provenance; nothing wrote the reverse direction down'
    expect:
      exit: 0
      stdout_contains: ['adr:adr-0001', 'rule:majordomus.adr-integrity', 'related.0']
  - id: what-a-change-reaches
    run: ['adr', 'affected']
    note: 'the same edges read from a change set: which decisions this work touches. A clean tree reaches nothing, and the exit code never says a decision stopped holding'
    expect:
      exit: 0
      stdout_contains: ['no decision names anything this change set touches']
  - id: not-yours-to-choose
    run: ['adr', 'propose', 'A decision that accepts itself', '--status', 'accepted']
    note: 'the refusal that matters: a tool that can write accepted turns its inference into repository truth'
    expect:
      exit: 15
      stdout_contains: ['not yours to choose']
  - id: evidence-must-resolve
    run: ['adr', 'propose', 'A decision derived from a file nobody has', '--from', 'file:docs/nosuch']
    note: 'an extracted record without evidence is an assertion, and is refused as one'
    expect:
      exit: 2
      stdout_contains: ['names a path that does not exist']
then:
  - 'a reference a decision makes is validated where its type says the target lives'
  - 'the reverse direction is the graph read backwards, never a second list'
  - 'a change set names the decisions it reaches; whether they still hold is a person to read, not an exit code'
  - 'a decision is one validated file under .ai/repo/adrs/, discovered as data'
  - 'no invocation of the tool writes status accepted'

The scenario

Executed against the real tool, in a repository prepared by adr-related, 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, 8 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 adr list exit 0

   one line per decision: identity, status, date, title

   adr-0001   proposed    <date>  The registry is the one canonical declaration

   • exit 0
   • stdout_contains /adr-0001/
   • stdout_contains /proposed/
2. 2$ majordomus adr show adr-0001 exit 0

   the path, then the file as written: the provenance says the tool derived it

   .ai/repo/adrs/0001-the-registry-is-the-one-canonical-declaration.md
   
   ---
   schema: adr/v1
   id: adr-0001
   kind: adr
   title: The registry is the one canonical declaration
   status: proposed
   related:
     - rule:majordomus.adr-integrity
     - file:docs/d
   date: <date>
   tags:
     - architecture
   provenance:
     origin: extracted
     derived_from:
       - file:docs/d
   ---
   
   # 1. The registry is the one canonical declaration
   
   ## Context
   
   What forced the decision. Derived from:  file:docs/d.
   
   ## Decision
   
   The registry is the one canonical declaration
   
   ## Alternatives rejected
   
   What else was considered, and why it was not taken.
   
   ## Consequences
   
   What this costs, what it forecloses, and what now has to be true.

   • exit 0
   • stdout_contains /schema: adr/v1/
   • stdout_contains /origin: extracted/
   • stdout_contains /file:docs/d/
3. 3$ majordomus adr check exit 0

   identities, statuses, supersession and every reference, in one pass

   examined 1 decision(s) in .ai/repo/adrs/
   every identity unique, every status known, every reference resolves
   0 identities added here, measured against main and every other ref

   • exit 0
   • stdout_contains /every identity unique/
4. 4$ majordomus adr show adr-0001 exit 0

   related is the forward edge: the rule the decision declares, the file it reaches

   .ai/repo/adrs/0001-the-registry-is-the-one-canonical-declaration.md
   
   ---
   schema: adr/v1
   id: adr-0001
   kind: adr
   title: The registry is the one canonical declaration
   status: proposed
   related:
     - rule:majordomus.adr-integrity
     - file:docs/d
   date: <date>
   tags:
     - architecture
   provenance:
     origin: extracted
     derived_from:
       - file:docs/d
   ---
   
   # 1. The registry is the one canonical declaration
   
   ## Context
   
   What forced the decision. Derived from:  file:docs/d.
   
   ## Decision
   
   The registry is the one canonical declaration
   
   ## Alternatives rejected
   
   What else was considered, and why it was not taken.
   
   ## Consequences
   
   What this costs, what it forecloses, and what now has to be true.

   • exit 0
   • stdout_contains /related:/
   • stdout_contains /rule:majordomus.adr-integrity/
5. 5$ majordomus knowledge edges --type declares exit 0

   the same fact as an edge, with the front-matter key that stated it as provenance; nothing wrote the reverse direction down

   declares        adr:adr-0001                                   rule:majordomus.adr-integrity                  .ai/repo/adrs/0001-the-registry-is-the-one-canonical-declaration.md:related.0
   knowledge edges: 1 in scope all, type declares
   INFO knowledge   . — the schema check was not asked for (MAJORDOMUS_KNOWLEDGE_SCHEMA=unasked), so no file was checked against the schema of its kind

   • exit 0
   • stdout_contains /adr:adr-0001/
   • stdout_contains /rule:majordomus.adr-integrity/
   • stdout_contains /related.0/
6. 6$ majordomus adr affected exit 0

   the same edges read from a change set: which decisions this work touches. A clean tree reaches nothing, and the exit code never says a decision stopped holding

   adr affected: no decision names anything this change set touches

   • exit 0
   • stdout_contains /no decision names anything this change set touches/
7. 7$ majordomus adr propose 'A decision that accepts itself' --status accepted exit 15

   the refusal that matters: a tool that can write accepted turns its inference into repository truth

   majordomus: adr propose: the status is not yours to choose; a proposed decision is accepted by a person editing the record

   • exit 15
   • stdout_contains /not yours to choose/
8. 8$ majordomus adr propose 'A decision derived from a file nobody has' --from file:docs/nosuch exit 2

   an extracted record without evidence is an assertion, and is refused as one

   majordomus: adr propose: reference "file:docs/nosuch" names a path that does not exist

   • exit 2
   • stdout_contains /names a path that does not exist/

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 adrThe repository's architecture decisions as objects: list, show, ask for the next free identity, propose one with provenance, and validate the whole set against this tree and every other ref.
• majordomus knowledgeThe compiled index over what this repository states, and the candidate records it derives from what an episode did.

The rules that make it hold

• ✕blocking Architecture decision integrityEvery architecture decision the repository holds parses against the decision contract, claims an identity nothing else claims, and every relation and reference it makes resolves.

Guarantees exercised

• ○guaranteed An architecture decision is one file under the layer's adrs section, validated against the decision contract, with an identity nothing else claims, reciprocal supersession, and every reference it makes resolving
• ○guaranteed A decision states what it put in force as typed references, each one validated, and the reverse direction — what a rule, a document, an implementation or a case was decided by — is read from the knowledge graph rather than written down a second time
• ○guaranteed majordomus adr propose writes a decision with status proposed and refuses to write any other status, allocates its identity under a lock so concurrent workers never collide, and records what the decision was derived from

Related use cases

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

• 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.
• 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.
• Record what one worker did in one sittingOpen a session, do the work under whatever tasks it touches, and close it into an envelope that references what it produced and copies 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.
• Read back what happened, and keep the ledger within its capRead the append-only ledger as operational history, filtered by task and event, validate every line, and rotate the oldest lines into an archive rather than deleting them.

The moments this answers

• → watched a session undo last week's decision, for the reason it was made A decision whose reason lived in a conversation cannot be reviewed, only re-argued — by a worker with less information than the first one had.
• → spent an hour discovering something the repository already knew, twice A worker learns something expensive about the codebase, uses it once, and it dies with the session because nothing turned it into a durable record.
• → watched one worker revert another worker's change, on purpose A worker sees an unexplained change in its path, judges it wrong, and removes it — correctly, on the evidence it had.
• → went looking for why we chose this and found a chat log A decision that was reached in a session is stored where only that session can read it, so it is neither reviewable nor discoverable.
• → let a fast, cheap session make a decision the whole codebase now lives with Capability is dialled down for cost and nothing distinguishes the tasks where that is prudent from the ones where it is expensive.
• → watched a worker spend a day on an approach that had already been ruled out Negative results are the majority of experimental output and the part nobody records, so the search space is re-explored.