novox/hq

Files

T

jschoubben 3f6d939930 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.

2026-08-23 18:17:59 +02:00

3.9 KiB

Raw Blame History

status, date, deciders, reconstructed

status	date	deciders	reconstructed
accepted	2026-08-23	jochen	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

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.
Leave the folder unnumbered. Rejected — the annex problem, and it leaves an unexplained gap for anyone arriving from the sibling repository.
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 — the format, and the note on reconstructed records.

3.9 KiB Raw Blame History Unescape Escape