Decision ledger

One file holds every confirmed decision: memory/DECISIONS.md (run brain-init if it doesn't exist yet). The ledger is append-only — nothing is ever edited or deleted. Changed minds are recorded as new entries that supersede old ones.

Entry format

## D-021 · <short title> — <YYYY-MM-DD> (<source: who confirmed, in what context>)

<What was decided, in the decider's own terms. Include the reason if one was given.>

Rules

1. Append-only. Never rewrite, reorder, or remove an existing entry. The ledger is trustworthy precisely because it cannot be quietly rewritten.
2. User-confirmed only. Record what the user actually decided, not what you proposed. If your proposal was adopted, say so: (AI-proposed, user-confirmed). Never promote your own suggestion to a decision — and never promote your reading of a non-answer (see Provisional readings below).
3. Supersede, don't edit. When a decision changes: write a new entry stating what changed and supersedes D-xxx, then add exactly one line to the old entry: → superseded by D-yyy (YYYY-MM-DD). That backlink is the only permitted touch to an old entry.
4. Record in-session. The moment a decision is confirmed, write it — not at the end of the conversation. Topic changes destroy unwritten decisions.
5. Sequential ids. D-001, D-002, … Never reuse a number, even after supersede.
6. Surface conflicts. If a new decision contradicts a standing entry and the user hasn't acknowledged that, point it out before recording — then record whichever the user confirms, with the supersede link.
7. No compression tool rewrites this file. Tools that shrink memory files for token savings (caveman-compress and the like) drop the load-bearing words first — negations, numbers, who-confirmed, supersede links — and the loss is silent. The ledger shrinks only by hand, with the original kept beside it and a part-by-part comparison before the short version is accepted. The memory-compress-guard rule in the example catalog says this to the model on the prompt where it matters.
8. A supersede ends with a sweep. The old decision's wording usually lives in more places than the ledger — docs, copy, configs, skill files. Search the project for it, fix each surface or register the stragglers in memory/OPEN-QUESTIONS.md, then add one sweep line to the new entry: sweep: <what was fixed> (YYYY-MM-DD), appending → Q-xx for anything left open. Like the supersede backlink, that one line is a permitted touch to an already-written entry — until it's there, the dead decision keeps working: the ledger says B while the README still says A.

Provisional readings — what is not a decision

The user goes quiet, changes the subject, or answers with a token that could mean anything — "ok", "sure", "fine, whatever works" — and the work has to go somewhere. The failure mode this prevents: your reading of that moment getting written down as their decision, then being relied on for days.

• Silence and short tokens are not confirmations for one-way doors. Anything hard to reverse, anything that leaves the repo (publishing, sending, spending, deleting), and anything that would become a standing rule waits for words that actually say yes. Two-way-door work — cheap to undo, internal — may read a repeated go-ahead inside an established pattern as delegation. Read the context, not the token: the same "ok" is an acknowledgement in one place and a go-ahead in another, and no form classifies itself. (Most calls are two-way doors; treating them all as one-way is how work stalls.)
• Quote them, label yourself. When you proceed on a reading the user did not confirm, it goes in memory/OPEN-QUESTIONS.md under Readings in force — never here: the user's words verbatim, your reading marked assumed, what breaks if the reading is wrong, what ends it (their confirmation, a date, or the next time the subject comes up), and where it is being relied on. A reading never gets a D- number.
• Proceed only through two-way doors while it is provisional. One-way doors wait. When you cannot tell which door it is, treat it as one-way.
• Ask at the break, once, bundled. Do not re-ask on every message and do not stop the work to ask — over-asking is its own failure, and the user is usually mid-flow. The open readings go to the checkpoint's Waiting on the user; ask when the thread pauses. A reading relied on a second time since the last checkpoint is due its question now.
• Three exits. The user confirms → a real entry here, with their words quoted. The user contradicts → drop the reading and sweep whatever was built on it. The condition expires or the subject returns → ask, then one of the first two.

A wrong entry and a pile of unconfirmed readings are both failures, and ballast does not rank them; it keeps them apart. Readings live in open questions, where they stay visible; the ledger holds only what was said.

Reading the ledger

At session start (or when context resets), read the ledger before substantive work. Standing decisions are followed without relitigating — if you believe a decision is wrong, say so once, with reasons, and let the user decide whether to supersede it.

Why this works

An LLM session forgets; a file does not. But a file that can be silently edited is worse than no file — it feels authoritative while drifting. Append-only + supersede gives you both: current truth at a glance, and the full history of how you got there.

Part of ballast — foundations first, every solved path kept, done means checks pass.