Every decision is a record; the ledger is gone

papa-hq has no ledger. Its root is AGENTS.md, CLAUDE.md, README.md, every decision is a numbered record, and its graduation playbook has no path for an unrecorded decision. hal-hq now matches. The ledger's 41 entries classified as: 10 restating a record, 11 restating design docs, 15 describing how this repository works with the reasoning sitting in a README rather than anywhere citable, 3 small rules with no home, 2 superseded stubs. Mostly a copy — and a hand-maintained index, the exact pattern ADR 0022 had just rejected for the decision index on the grounds it drifted after one addition. Keeping one copy of that while removing another is not a position. It also collided by name with 02-DECISIONS/ in any directory listing. Nothing was dropped. Records 0019-0025 give the repository decisions the reasoning they never had: HQ is its own repository and is public, design has two layers, work moves through playbooks, status lives in frontmatter, issues have a front door, the numbering is the flow, HQ is the source of the constitution. 0026 records the ledger's own removal. The three orphan rules went to how-we-build, where a rule is enforced and keeps the incident that earned it — the package rule was genuinely unwritten anywhere. Two lab decisions stated only in the ledger went into the lab design. "Deliberately not decided" went to the research effort and design document each question actually belongs to. The chronological view the ledger provided is now generated from record frontmatter, which is what it was for. The cost, stated in 0026 rather than glossed: a record is more work than a table row, so the risk is a small decision going unrecorded because nobody wanted to write a document. how-we-build takes rules cheaply, which is the mitigation, not a solution.
2026-08-23 18:17:59 +02:00
parent c0b35652d0
commit 3f6d939930
21 changed files with 599 additions and 134 deletions
@@ -19,7 +19,7 @@ idea ──► 01-RESEARCH ──► decision (02-DECISIONS/) ──► 03-DESIG
 │            │                                      │
 │            │                                      └─► 03-DESIGN/00-as-is once shipped
 │            └────► abandoned (recorded, kept)
- └─(small/obvious, decision recorded in DECISIONS.md)────► 03-DESIGN directly
+ └─(small/obvious, still recorded in 02-DECISIONS)──────────► 03-DESIGN directly

 symptom ──► 04-ISSUES ──► diagnosis ──► code-repo fix and/or design amendment

@@ -54,6 +54,7 @@ the expensive half.

 Research overviews, design docs, issue reports and decision records each carry their status as
 YAML frontmatter (schemas in the section READMEs and playbooks). There are **no central status
-files**. `DECISIONS.md` is a ledger of decisions as they were taken — an index and a home for
-decisions too small to warrant a record — and is explicitly *not* a status board. Cross-cutting
-views are generated on demand by the `hal-status` skill and never written to disk.
+files** and no decision ledger. **Every decision is a record in
+[`02-DECISIONS`](../../02-DECISIONS/)** — if it is worth recording it is worth a record, and if
+it is not worth a record it is not recorded. Cross-cutting views, the decision index included,
+are generated on demand by the `hal-status` skill and never written to disk.
@@ -27,8 +27,6 @@

 4. **Close the effort.** Set the effort's `00-overview.md` frontmatter to `status: graduated` and
   `became:` pointing at the design document and the decision record.
-5. **Add a ledger line.** Append the decision to [`DECISIONS.md`](../../DECISIONS.md) under
-   today's heading, pointing at the record.

 ## Amending an existing design

@@ -39,7 +37,6 @@ A design changes only through a decision.
 2. Edit the to-be design document and set `updated:` to today.
 3. If the amendment came from an issue, set that issue's `amended-design:` to the document
   path.
-4. Add the ledger line.

 ## When something ships

@@ -26,12 +26,12 @@ and, per the repository's own rule, it is how the rule "HQ is the source" is che
   cite sections by number.
 4. Verify the derived page reads back with the change present. A publish that reported success
   and did nothing is exactly the failure class this repository exists to name.
-5. Note the sync in the ledger line for the decision.
+5. Note the sync in the decision record's Consequences.

 ## Rules

 - **Never edit the derived page directly.** An edit there survives until the next sync and
  then vanishes, taking its reasoning with it.
 - The derived page may only be **tightened** by per-team override pages, never relaxed.
- If the sync cannot be performed, say so in the ledger line. An unsynced rule is a rule the
+- If the sync cannot be performed, say so in the record. An unsynced rule is a rule the
  mesh does not enforce, whatever `how-we-build.md` says.