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.
This commit is contained in:
@@ -12,7 +12,6 @@ why. Implementation lives in `modules/`; the reasoning behind it lives here.
|
||||
| [`02-DECISIONS`](02-DECISIONS/) | Numbered decision records, in the order the decisions were taken — what was chosen, and what was rejected. |
|
||||
| [`03-DESIGN`](03-DESIGN/) | The authoritative specification, in two layers: [`00-as-is`](03-DESIGN/00-as-is/) — the mesh that exists — and [`01-to-be`](03-DESIGN/01-to-be/) — the one being built toward. |
|
||||
| [`04-ISSUES`](04-ISSUES/) | The front door for "something is wrong" at the level of design or governance. |
|
||||
| [`DECISIONS.md`](DECISIONS.md) | The ledger: every decision as it was taken, indexing the records and holding the ones too small to warrant one. |
|
||||
|
||||
**The numbering is the flow.** Research produces a decision; the decision authorises a design.
|
||||
That is why decisions are `02` and design is `03` — a reader following the numbers walks the
|
||||
@@ -25,7 +24,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
|
||||
|
||||
@@ -107,7 +106,8 @@ Answered separately, a repository of its own is the better home:
|
||||
|
||||
The trade is real and worth naming: a change to a document and the change to the code it
|
||||
describes can no longer land in one commit. Keeping them honest is a discipline now rather
|
||||
than a mechanism — which is why [`DECISIONS.md`](DECISIONS.md) records decisions as they are
|
||||
taken, and why a document that states a rule should say how the rule is checked.
|
||||
than a mechanism — which is why every decision is recorded in
|
||||
[`02-DECISIONS`](02-DECISIONS/) as it is taken, and why a document that states a rule should
|
||||
say how the rule is checked.
|
||||
|
||||
Recorded as decision 27 in [`DECISIONS.md`](DECISIONS.md).
|
||||
Recorded as [ADR 0019](02-DECISIONS/0019-hq-is-its-own-repository.md).
|
||||
|
||||
Reference in New Issue
Block a user