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.
77 lines
3.9 KiB
Markdown
77 lines
3.9 KiB
Markdown
---
|
||
status: accepted
|
||
date: 2026-08-23
|
||
deciders: jochen
|
||
reconstructed: false
|
||
---
|
||
|
||
# 24. The folder numbering is the flow, and decision records run oldest first
|
||
|
||
## Context
|
||
|
||
Two orderings were wrong in ways that only show up when someone new reads the repository.
|
||
|
||
**The folders.** Decisions lived in an unnumbered folder that sorted after the numbered ones,
|
||
so the repository's most load-bearing content read as an annex.
|
||
|
||
The sibling HQ repository for the PAPA platform had already solved this and solved it
|
||
crookedly: its design folder existed from its initial commit, and when its decision folder was
|
||
finally promoted it took the **next free number** rather than its place in the sequence. That
|
||
repository now reads `01 research → 03 decision → 02 design`. A decision precedes the design
|
||
it authorises and is numbered after it. By the time this was visible, the design folder was too
|
||
settled to renumber.
|
||
|
||
**The records.** Fourteen decisions had been taken in implementation and never written down —
|
||
the broker, the module abstraction, the mesh database, the artifact, the three silos and the
|
||
rest. Meanwhile two records existed, holding numbers 0001 and 0002, for decisions taken last.
|
||
|
||
## Considered options
|
||
|
||
1. **Match the sibling repository exactly**, inheriting its ordering. Rejected: structural
|
||
parity is worth something, but not the cost of copying a scar the other repository would
|
||
not choose again.
|
||
2. **Leave the folder unnumbered.** Rejected — the annex problem, and it leaves an unexplained
|
||
gap for anyone arriving from the sibling repository.
|
||
3. **Number by position in the flow, and renumber the records chronologically.** Chosen, on
|
||
the grounds that this repository was four commits old and nothing outside it cited a
|
||
number. That is the only window in which either renumbering is free.
|
||
|
||
## Decision
|
||
|
||
**The numbering is the flow.** Research produces a decision; the decision authorises a design.
|
||
So `01-RESEARCH`, `02-DECISIONS`, `03-DESIGN`, `04-ISSUES`. Following the folder numbers walks
|
||
the process in the order it happens.
|
||
|
||
**Decision records are a chronological ledger.** They run oldest first. The fourteen decisions
|
||
already taken in implementation were back-filled as records 0001–0014, each dated from the
|
||
history, each carrying `reconstructed: true` and saying so in its first lines, and each citing
|
||
the commit, pull request or knowledge-base entry it was recovered from. The two existing
|
||
records moved to 0015 and 0016.
|
||
|
||
A reconstructed record is not a transcript. Where the deliberation is not recoverable it states
|
||
what the alternatives were and why the chosen one won on the evidence available — not a
|
||
discussion that did not happen. Where a date is not establishable it says so.
|
||
|
||
The foundational folder is `00-META`, matching the sibling repository.
|
||
|
||
## Consequences
|
||
|
||
- The repository reads in process order, and the gap at `03` that a reader coming from the
|
||
sibling repository would notice is explained by this record.
|
||
- The design documents can cite reasoning instead of asserting rules, because the reasoning now
|
||
exists.
|
||
- Structural divergence from the sibling repository, deliberately, in exactly one place. It is
|
||
recorded here so that the difference reads as a choice rather than an accident.
|
||
- **Record numbers are now stable and renumbering is over.** This decision spends the one
|
||
window that existed; a future record takes the next free number regardless of its date.
|
||
- Reconstructed records carry a standing risk: they are the most confident-sounding documents
|
||
in the repository and the least directly witnessed. The `reconstructed` flag exists so that
|
||
is never invisible.
|
||
|
||
## References
|
||
|
||
- The sibling repository's restructure of 2026-07-13 moved its decision folder in a single
|
||
commit of twelve renames with no content change, alongside the same status-into-frontmatter
|
||
and playbook changes made here.
|
||
- [`02-DECISIONS/README.md`](README.md) — the format, and the note on reconstructed records.
|