jschoubben
3f6d939930
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.
4.7 KiB
status, date, deciders, reconstructed
| status | date | deciders | reconstructed |
|---|---|---|---|
| accepted | 2026-08-23 | jochen | false |
26. Every decision is a record; there is no ledger
Context
HQ carried a decision ledger at its root: a chronological table of forty-one numbered decisions, each with who decided and a pointer to where the reasoning lived. It was created deliberately, to make decisions findable and to give a home to decisions too small to warrant a document.
By the time the decision records were back-filled (ADR 0024) the ledger had become three things at once, and only one of them was still needed.
Classified, its forty-one entries were: ten restating a record, eleven restating design documents, fifteen describing how this repository works — with the reasoning in a README rather than anywhere citable — three small rules with no home at all, and two superseded stubs.
So the ledger was mostly a copy. Worse, it was a hand-maintained index, which ADR 0022 had just finished rejecting for the decision-record index on the grounds that it had drifted after a single addition. Keeping one copy of that pattern while removing another is not a position.
It had also produced a naming collision that a directory listing makes plain: DECISIONS.md
beside 02-DECISIONS/, holding different things.
Considered options
- Keep the ledger. Rejected. It duplicates the records, restates status, and is the exact hand-maintained index this repository decided against elsewhere.
- Keep it, renamed, for small decisions only. Rejected, and this is the option worth
arguing with — it is genuinely useful to record a decision without writing a document. But a
decision small enough to be one table row is almost always a rule rather than a
decision, and a rule belongs in
how-we-build.mdwhere it is enforced and where its reasoning is kept. That is where the three orphans went. - Every decision is a record; nothing else. Chosen. This is how the sibling HQ repository for the PAPA platform works, and it has no ledger of any kind.
Decision
If a decision is worth recording, it is worth a record. If it is not worth a record, it is not recorded.
02-DECISIONS holds every decision. There is no ledger, no index file, and no central status
of any kind. The chronological view — decisions in the order they were taken — is generated
from record frontmatter, which is what the ledger was actually for.
Content that was only in the ledger was rehomed rather than dropped:
| Was | Went to |
|---|---|
| Decisions about how this repository works | Records 0019–0025 |
| Small rules with no record | how-we-build.md — the package rule, and two already there |
| Lab decisions not stated in the design | 03-DESIGN/01-to-be/01-end-to-end-testing.md |
| "Deliberately not decided" | The research effort and design document each question belongs to |
| Unowned observations | 04-ISSUES (ADR 0023) |
Consequences
- One place to look, and nothing to keep in sync. The collision between the ledger and the record folder is gone.
- Structural parity with the sibling repository on decisions, which ADR 0024 deliberately broke on folder numbering. The divergence is now exactly one thing, and it is the one thing that was argued for.
- Writing a record is now the only way to record a decision, and a record is more work than
a table row. The real risk is that a small decision goes unrecorded because nobody wanted
to write a document. The mitigation is that a small decision is usually a rule, and
how-we-build.mdtakes rules cheaply — but this is a cost, not a solved problem, and it is the thing to watch. - The chronological view now depends on the generator existing and being run. It did not before.
- Two superseded ledger stubs had no record of their own. The position that documentation lives inside the code repository is now recorded only as superseded context in ADR 0019; the system-container position is explained in ADR 0016. Neither is lost.
References
- The sibling PAPA HQ repository: root holds only agent instructions and a README; every decision is a numbered record, and its graduation playbook has no path for an unrecorded decision.
- ADR 0022 — the hand-maintained-index argument this applies consistently.