jschoubben
e1f4c7d9e0
0003 is now superseded by 0056. Nothing is left proposed. Applied: - 06 corrected from ten contexts to seven plus the api, each row now stating why it passes the more-than-one-node test. work, knowledge and stream are named as mesh-hosted rather than dropped; `ai` folds into config; `record` is deferred explicitly rather than listed. Its frontmatter now cites 0055. - how-we-build §4 amended per 0054, and the derived page republished by playbook 05. The sync found the drift the playbook exists to catch: the published §4 and the source did not say the same thing. The source said "four accidents, not four boundaries"; the published page said "one intent expressed four times", and only the published page carried the scope caveat. Same rule, two texts, already diverging. Verified the republish by reading back -- the new rule is present and the old section's body returns nothing -- rather than trusting the success message. The two smaller findings: - 0051 separated the transport identity from the declaring authority. It said the token carries "an address" and "the identity to expect" without saying what the node dials. It dials the broker, so pinning only that would make the control plane's authority transitive and let a compromised broker forge declarations -- which, since the host applies whatever the link delivers, is the whole machine. The token now carries four things, and declarations are signed and verified per declaration. Cost recorded: rotating the signing identity is fleet-wide. - 0026 no longer restates 0022's rule about generated views. 0022's own words are "prose does not restate status; one place, and two is one too many", which is what 0026 was doing to it.
5.1 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, and there is no ledger — no separate document in which
a decision is also summarised, ranked or tracked. The chronological view — decisions in the order
they were taken — is generated from record frontmatter, which is what the ledger was actually
for.
That generation is not this record's rule. It is ADR 0022, which already decides repository-wide that status lives in frontmatter and every cross-cutting view is generated rather than written. This record does not restate it — 0022's own words are prose does not restate status; one place, and two is one too many, and an earlier version of this paragraph did exactly that.
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.