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.
3.0 KiB
status, date, deciders, reconstructed
| status | date | deciders | reconstructed |
|---|---|---|---|
| accepted | 2026-08-23 | jochen | false |
20. Design is written in two layers: what is, and what is intended
Context
HQ held only the intended mesh. Every reader had to already know the running system in order to understand what the decisions were about, and a statement about current behaviour had nowhere to live except inside a document describing an intention.
The consequence was invisible until looked for: an as-is claim inside a to-be document is indistinguishable from the intention around it, so the document silently stops being true as the system moves — and nobody can tell which half went stale.
The mesh also has a large body of shipped behaviour that nobody would choose again. It is not design in the sense of "what we decided"; it is design in the sense of "what is there", and it is exactly the part a person changing the system most needs.
Considered options
- One layer, describing the target. Rejected — the status quo. The running system goes undocumented and the target document accumulates unmarked claims about it.
- One layer, describing what runs, with intentions only in decision records. Rejected: a decision record is an argument, not a specification, and a multi-part intention has nowhere coherent to live.
- Two layers, declared per document, never mixed. Chosen.
Decision
03-DESIGN holds two layers, and every document declares which it is:
| Layer | Describes | Written from |
|---|---|---|
00-as-is/ |
The mesh that exists | The implementation and the operational record |
01-to-be/ |
The mesh being built toward | Decision records |
An as-is document records what is, not what should be — including behaviour nobody would choose again. A layer that keeps only the good decisions is a brochure.
When a to-be design ships it does not move. Its as-is counterpart is written or updated,
the to-be document's status becomes implemented, and both stand: one describing what runs,
the other recording what was intended. Deleting the intention loses the reasoning.
Where implementation and intention disagree, the as-is document records the implementation and says they disagree.
Consequences
- A reader can tell, from the folder and from one frontmatter field, whether they are reading a description or a plan. That distinction was previously unavailable at any price.
- Correcting an as-is document requires evidence from the implementation, not agreement — and needs no decision record, because nothing was decided.
- Two documents must be kept current per subsystem instead of one. This is the cost, and it is paid on every ship.
- Something that shipped differently from its design becomes a visible divergence rather than a silently wrong document, and may deserve an issue.
References
03-DESIGN/README.md— the layer contract and frontmatter schema.03-DESIGN/00-as-is/— the first eleven as-is documents, written 2026-08-23 from the monorepo and the operational memory.