Read back what happened, and keep the ledger within its cap

setup: active-task-records
given:
  - 'an active task that has already produced a checkpoint, a decision and an open question'
steps:
  - id: history
    run: ['history']
    note: 'the ledger read back oldest first, one event per line, from a closed vocabulary'
    expect:
      exit: 0
      stdout_contains: ['task.started', 'task.checkpoint', 'decision.recorded']
  - id: by-event
    run: ['history', '--event', 'task.checkpoint']
    note: 'only the events of one kind'
    expect:
      exit: 0
      stdout_contains: ['task.checkpoint']
      stdout_not_contains: ['decision.recorded']
  - id: valid
    run: ['history', '--validate']
    note: 'every line is a well-formed event; a malformed line would be a failure, not a skipped record'
    expect:
      exit: 0
      stdout_contains: ['every event is registered', 'history --validate: ok']
  - id: find
    run: ['search', 'parser']
    note: 'a durable record found literally, across kinds, without an index'
    expect:
      exit: 0
      stdout_contains: ['^decision ', '^checkpoint ', 'match']
  - id: caps
    run: ['watch']
    note: 'the ledger, the handovers and the checkpoints are under their retention caps'
    expect:
      exit: 0
      stdout_contains: ['^OK   retention   ledger', '^OK   retention   checkpoints', '0 drift finding']
then:
  - 'every event has a name from the closed vocabulary'
  - 'the ledger is never silently repaired or truncated'
  - 'rotation archives, it does not delete'

The scenario

Executed against the real tool, in a repository prepared by active-task-records, 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 history exit 0

   the ledger read back oldest first, one event per line, from a closed vocabulary

   <time>  projections.updated -                      <head>  targets=3
   <time>  task.started        t-<id>  <head>  profile=implementation scope=lib
   <time>  task.checkpoint     t-<id>  <head>  <time>--main--<head>--<hash>.md
   <time>  decision.recorded   t-<id>  <head>  refuse tabs in the parser
   <time>  question.opened     t-<id>  <head>  should tabs be an error or a warning?

   • exit 0
   • stdout_contains /task.started/
   • stdout_contains /task.checkpoint/
   • stdout_contains /decision.recorded/
2. 2$ majordomus history --event task.checkpoint exit 0

   only the events of one kind

   <time>  task.checkpoint     t-<id>  <head>  <time>--main--<head>--<hash>.md

   • exit 0
   • stdout_contains /task.checkpoint/
   • stdout_not_contains /decision.recorded/
3. 3$ majordomus history --validate exit 0

   every line is a well-formed event; a malformed line would be a failure, not a skipped record

   OK   ledger      5 lines — every line carries ts and event, and every event is registered
   history --validate: ok

   • exit 0
   • stdout_contains /every event is registered/
   • stdout_contains /history --validate: ok/
4. 4$ majordomus search parser exit 0

   a durable record found literally, across kinds, without an index

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

   • exit 0
   • stdout_contains /^decision /
   • stdout_contains /^checkpoint /
   • stdout_contains /match/
5. 5$ majordomus watch exit 0

   the ledger, the handovers and the checkpoints are under their retention caps

   OK   knowledge   graph — buildable here: 103 node(s), 58 edge(s), compiled into a temporary file and removed; no stored index to go stale
   OK   layout      .ai/manifest.yaml — schema ai-repository/v1
   OK   layout      .ai/repo/scope.yaml — version 1; 14 in pathspec(s); every key is one the schema declares
   OK   layout      .ai/local/ — ignored, and nothing under it is tracked
   OK   layout      .ai/ — every section the manifest names exists; the layer is readable without the tool
   ·    checkpoint  t-<id> — <timed against the checkpoint interval>
   INFO checkpoint  .ai/local/state/checkpoints/<time>--main--<head>--<hash>.md — newest record, <age> ago  [reproduce: majordomus checkpoint --show]
   OK   records     ledger.jsonl — every line is a well-formed event
   OK   policy      39 key(s) — every policy value the code reads is declared, with no reader-side default
   OK   bootstrap   3 projection(s) — each points at .ai/README.md, carries no rule of its own and names only rules in force
   OK   catalogue   0 use case(s), 0 application(s) — every command, doctrine, claim, responsibility, category, setup and cross-reference resolves, both directions
   OK   context     .ai/ — 20 context document(s) carry the contract; ids unique, references resolve, no final document superseded, no cycle  [reproduce: majordomus context validate]
   OK   policy      policy+profiles — match the last update (<hash12>)
   INFO adr         .ai/repo/adrs/ — no decisions; nothing to validate
   OK   records     decisions.md — every entry is attributable
   INFO project     .ai/repo/project — no canonical project model here; nothing to validate
   OK   command     surface — 30 public command(s), reconciled against the dispatch table  [reproduce: majordomus doctor]
   OK   command     coverage — every public command is exercised and refuted  [reproduce: bash test/run.sh 31_command_coverage]
   OK   resolver    handovers — no record for this worktree and branch (absence, not a stale match)  [reproduce: majordomus handover --resolve]
   OK   lifecycle   activity — 0 episode(s) opened here; too few to judge whether the writers stopped
   OK   knowledge   wiring — the close path and the compaction adapter call the deriver
   OK   knowledge   deriver — no episode has closed here; nothing to judge
   INFO project     .ai/repo/project — no canonical project model here; nothing to validate
   OK   projection  AGENTS.md — content matches its stamp
   OK   projection  CLAUDE.md — content matches its stamp
   OK   projection  GEMINI.md — content matches its stamp
   OK   context     builder — 58 lines, budget 300  [reproduce: majordomus context]
   OK   capture     share/schemas/majordomus/capture/capture.v1 — 2 file(s) describe majordomus.capture/v1 at the path the identifier derives: the record as JSON Schema, the document as protobuf
   OK   capture     .ai/local/prompts — ignored and untracked
   OK   capture     .ai/local/prompts — no records yet; the archive is empty
   OK   capture     .ai/local/prompts — every prompt is present as all three: the record, the Markdown and the YAML
   OK   prompts     .ai/local/prompts — the archive and every record in it are readable by their owner only
   OK   prompts     .ai/local/prompts — no records yet; the archive is empty
   OK   prompt      4 asset(s) — front matter valid, every token known
   OK   records     open-questions.md — every entry parses
   OK   retention   ledger — 5 lines, cap 5000
   OK   retention   handovers — 0 files, cap 200
   OK   retention   checkpoints — 1 files, cap 500
   OK   retention   sessions — 0 records, cap 500
   INFO project     .ai/repo/project — no canonical project model here; nothing to validate
   OK   rules       .ai/repo/rules/vendor/majordomus — every file matches the manifest (1 (1.0.0-alpha.8))
   OK   rules       61 rule(s) — resolve in one deterministic order; vendored baseline plus project rules, no override — 51 carry a validator, 10 are normative text this tool does not check
   OK   rules       blocking — all 44 blocking rule(s) carry a validator
   OK   schema      rules — 61 rule(s) resolve in one order: the vendored baseline in manifest order, then the project's, as a dependency graph
   OK   schema      share/kinds.yaml — 37 kind(s); every one that carries metadata declares a schema
   OK   schema      share/schemas — 54 schema(s), each valid JSON and each applied — by a kind, through an allow-list the tool reads, by a validator that names it, or as a generated document's contract (15)
   OK   scope       t-<id> — 1 touched file(s), all within scope
   OK   session     .ai/local/session-contexts — ignored and untracked
   OK   session     .ai/local/session-contexts — no working contexts yet; the store is empty
   INFO skill       .ai/repo/skills/ — no skills; nothing to validate
   OK   skill       reachable — no personal command or skill shares a name with a projected skill  [reproduce: majordomus run editors.status]
   OK   state       t-<id> — exact (head <head>)
   ·    budget      watch — <timed against the policy budget>
   OK   state       t-<id> — active; scope, checkpoint, blockers and records reported above
   ·    checkpoint  <time>--main--<head>--<hash>.md — <timed against the checkpoint interval>
   watch: 0 drift finding(s)

   • exit 0
   • stdout_contains /^OK retention ledger/
   • stdout_contains /^OK retention checkpoints/
   • stdout_contains /0 drift finding/

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 historyRead the append-only ledger back, filtered by task, event or time.
• majordomus searchFind a durable record without reading all of them, in authority order.
• majordomus watchWhat has drifted since the last update — policy, projections, state, retention.

The rules that make it hold

• ✕blocking Ledger integrityEvery line of the append-only ledger is a well-formed event; the one durable record nothing else can reconstruct stays readable.
• ✕blocking Retention capsThe ledger, the handovers, the checkpoints and the session records stay under the caps the policy sets, so durable state does not grow without bound.

Guarantees exercised

• ○guaranteed Every line of the append-only ledger is a well-formed event, and a malformed line is a failure rather than a skipped record
• ○guaranteed The append-only ledger and handover store have retention caps that are checked
• ○guaranteed The ledger is readable back as operational history, filtered by task, event and time
• ○guaranteed Rotating the ledger archives the oldest lines and never deletes them
• ○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.

• Record a decision so the next worker can find itWrite down what was decided and why as state, then find it again without reading a conversation.
• 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.
• 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.
• 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.

The moments this answers

• → asked what the workers did last night and had only transcripts to grep A conversation log records what was said, not what happened, so the operational question has to be answered by a person reading prose.
• → found finished work on a branch that nobody ever merged Workers produce far more than integration absorbs, and nothing distinguishes work that is done from work that is done and landed.
• → 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.
• → was asked how far the milestone had got and had to go and ask four people Progress is an aggregate that exists only in people, because the parts it aggregates were never recorded in a form anything can add up.
• → 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.
• → looked at the bill and could not say which of it produced anything Consumption is measured per account and outcomes are recorded per person, so the two can never be joined.
• → lost a failure a worker had already reproduced, because the session ended A failure observed inside a session is described in that session and nowhere else, so the next one starts from the report rather than the evidence.
• → 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.