Record a decision so the next worker can find it

setup: active-task
given:
  - 'an active task scoped to lib'
steps:
  - id: decide
    run: ['decision', 'add', 'refuse tabs in the parser', '--why', 'two encodings for one token']
    note: 'what was decided, why, and which task decided it; superseded by a later entry, never edited'
    expect:
      exit: 0
      stdout_contains: ['recorded: refuse tabs in the parser']
  - id: read-back
    run: ['decision', 'list']
    note: 'the decisions of this branch, newest first'
    expect:
      exit: 0
      stdout_contains: ['refuse tabs in the parser', 'Why: two encodings']
  - id: find-it
    run: ['search', 'tabs']
    note: 'a literal scan over the durable records, no index'
    expect:
      exit: 0
      stdout_contains: ['decision', 'match']
  - id: what-happened
    run: ['history']
    note: 'the ledger names the event and the task'
    expect:
      exit: 0
      stdout_contains: ['decision.recorded', 'task.started']
then:
  - 'a decision is one line of state with an author, a task and a reason'
  - 'nothing has to be re-explained to the next session'

The scenario

Executed against the real tool, in a repository prepared by active-task, 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 decision add 'refuse tabs in the parser' --why 'two encodings for one token' exit 0

   what was decided, why, and which task decided it; superseded by a later entry, never edited

   recorded: refuse tabs in the parser

   • exit 0
   • stdout_contains /recorded: refuse tabs in the parser/
2. 2$ majordomus decision list exit 0

   the decisions of this branch, newest first

   ## <date> — refuse tabs in the parser
   Task: t-<id>
   Head: <sha>
   Why: two encodings for one token
   Rejected: -
   Evidence: -
   Supersedes: -

   • exit 0
   • stdout_contains /refuse tabs in the parser/
   • stdout_contains /Why: two encodings/
3. 3$ majordomus search tabs exit 0

   a literal scan over the durable records, no index

   decision    .ai/local/state/decisions.md:13  ## <date> — refuse tabs in the parser
   history     .ai/local/state/ledger.jsonl:3  {"ts":"<time>","event":"decision.recorded","head":"<sha>","branch":"mai
   search: 2 match(es)

   • exit 0
   • stdout_contains /decision/
   • stdout_contains /match/
4. 4$ majordomus history exit 0

   the ledger names the event and the task

   <time>  projections.updated -                      <head>  targets=3
   <time>  task.started        t-<id>  <head>  profile=implementation scope=lib
   <time>  decision.recorded   t-<id>  <head>  refuse tabs in the parser

   • exit 0
   • stdout_contains /decision.recorded/
   • stdout_contains /task.started/

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 decisionRecord a decision that was made between real alternatives, with its reason, and read them back.
• majordomus searchFind a durable record without reading all of them, in authority order.
• majordomus historyRead the append-only ledger back, filtered by task, event or time.

The rules that make it hold

• !advisory Decision recordsEvery entry in decisions.md carries the task, the head and the reason, so a decision can be found by the worker who needs it.
• ✕blocking Ledger integrityEvery line of the append-only ledger is a well-formed event; the one durable record nothing else can reconstruct stays readable.

Guarantees exercised

• ○guaranteed The ledger is readable back as operational history, filtered by task, event and time
• ○guaranteed A decision is recorded with its reason and its task, and is superseded by a later entry rather than edited
• ○guaranteed Durable records are searchable literally, across kinds, without an index
• ○guaranteed The ledger's event vocabulary is closed, on the way in and on the way out

Related use cases

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

• 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.
• 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.
• Find out what has drifted since anyone last lookedAsk what has moved, rather than whether anything is wrong.
• 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.
• Find an object of the layer without reading everythingSearch durable records literally across kinds from the shell, and ask the shared server the same question over MCP with majordomus_search and majordomus_get.

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.
• → 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.
• → 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.
• → 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.
• → was asked who made a change and under what policy, and had only a commit Attribution stops at the commit, so what authorised a change, what verified it and what governed it are unrecoverable.