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.
2.0 KiB
2.0 KiB
name, description
| name | description |
|---|---|
| hal-amend-design | Use when a hal-hq design document must change, or when an as-is document is found to be wrong about what the mesh actually does. Triggers on "the design changed", "that's not how it works any more", "update the as-is", "this shipped differently". |
hal-amend-design
Changes a design document. Authoritative playbook:
00-META/process/02-graduation.md.
Which layer is being changed
Establish this first — the two amend for opposite reasons.
| Layer | Amend when | Requires |
|---|---|---|
01-to-be/ |
The intention changed | A decision record. Always. |
00-as-is/ |
The mesh changed, or the document was wrong about it | Evidence from the implementation. Never a decision. |
An as-is document is corrected against what the code does, not against what anyone meant. If the implementation and the intention disagree, the as-is document records the implementation and says they disagree.
Amending the to-be layer
- Write the decision record. If it reverses an earlier one, that record gets
status: supersededandsuperseded-by:— its text is never edited. - Edit the design; set
updated:to today. - If this came from an issue, set that issue's
amended-design:.
Amending the as-is layer
- Establish what is actually true — from the code, a pipeline log, a live query, the operational record. Not from a design document.
- Edit the document. Set
updated:only if the implementation state changed; a correction to text that was always wrong does not change it. - If the correction reveals that something shipped differently from its design, say so in the as-is document and leave the to-be document alone. That divergence is a finding, and may deserve an issue.
Do not
- Do not put a future intention in an as-is document.
- Do not quietly fix a wrong claim that held up a decision. Record that it was wrong and where it was relied on — that is the failure this repository exists to name.