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.
61 lines
2.7 KiB
Markdown
61 lines
2.7 KiB
Markdown
---
|
|
status: accepted
|
|
date: 2026-08-23
|
|
deciders: jochen
|
|
reconstructed: false
|
|
---
|
|
|
|
# 23. Issues have a front door, separate from the operational memory
|
|
|
|
## Context
|
|
|
|
Findings that were nobody's task accumulated in a table inside the decision ledger — a package
|
|
install reporting success while installing nothing, a manifest key read by no code, an
|
|
end-to-end harness dead for months. They were measured, true, and unowned: a table row cannot
|
|
be assigned, diagnosed or closed.
|
|
|
|
The mesh already has an operational memory holding roughly a hundred and thirty entries,
|
|
indexed on symptoms. The obvious move — put these there — is wrong, and the reason is the
|
|
distinction worth recording.
|
|
|
|
## Considered options
|
|
|
|
1. **Leave them in the ledger.** Rejected: a ledger records decisions taken, and these are
|
|
the opposite — questions nobody has answered.
|
|
2. **Put them in the operational memory.** Rejected. That store answers *how do I fix this
|
|
occurrence*; these are *why does the design allow this at all*. Filing them there makes
|
|
them findable by symptom and unfindable as open questions, and nothing there has a state
|
|
that can be closed.
|
|
3. **A numbered issue folder in HQ, deliberately narrow.** Chosen.
|
|
|
|
## Decision
|
|
|
|
`04-ISSUES` is the front door for something wrong at the level of **design or governance**:
|
|
a rule enforced by nothing, a stated invariant that is false, a failure the design permits to
|
|
be silent, or a symptom whose owner cannot be found without the whole mesh in view.
|
|
|
|
One numbered folder per issue: the report with the symptom as observed and the evidence, and
|
|
a diagnosis document carrying the trail, dated, including what was ruled out.
|
|
|
|
**This is not a second copy of the operational memory.** An issue here is a question HQ must
|
|
*answer*; an entry there is an incident someone must *clear*. An issue whose answer is a
|
|
general lesson belongs in both — and the operational memory is searched first, because if the
|
|
answer is already there this was never an issue.
|
|
|
|
## Consequences
|
|
|
|
- A finding gets a number, a state and an owner, and closing it is a visible act.
|
|
- The symptom-to-component trail accumulates in a place where the whole mesh is visible, which
|
|
is where cross-component diagnosis has to happen.
|
|
- The boundary needs judgement on every report, and will sometimes be got wrong. Filing too
|
|
narrowly loses a finding; filing too widely rebuilds the operational memory here, which is
|
|
the outcome HQ's separation was argued against
|
|
([ADR 0019](0019-hq-is-its-own-repository.md)).
|
|
- Six issues opened on creation, all previously unowned observations.
|
|
|
|
## References
|
|
|
|
- [`04-ISSUES/README.md`](../04-ISSUES/README.md) — the boundary table and the frontmatter
|
|
schema.
|
|
- [`00-META/process/03-issues.md`](../00-META/process/03-issues.md) — the playbook.
|