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.
55 lines
2.3 KiB
Markdown
55 lines
2.3 KiB
Markdown
---
|
|
status: accepted
|
|
date: 2026-08-23
|
|
deciders: jochen
|
|
reconstructed: false
|
|
---
|
|
|
|
# 22. Status lives in frontmatter; cross-cutting views are generated
|
|
|
|
## Context
|
|
|
|
Status was carried in prose — a bold line near the top of a document saying what state it was
|
|
in — and indexes were maintained by hand. The decision-record index had already drifted from
|
|
the folder it described **after a single addition**, which is about as short a demonstration
|
|
as the failure mode offers.
|
|
|
|
A hand-maintained index is a copy of something the filesystem already knows. It is correct
|
|
only for as long as everyone remembers it exists, and its being wrong is silent.
|
|
|
|
## Considered options
|
|
|
|
1. **Prose status plus hand-maintained indexes.** Rejected — the status quo, already
|
|
demonstrably broken.
|
|
2. **A central status file.** Rejected. It centralises the drift rather than removing it: the
|
|
file and the documents disagree, and the file is the one people read.
|
|
3. **Machine-readable frontmatter per document; every cross-cutting view generated on
|
|
demand.** Chosen.
|
|
|
|
## Decision
|
|
|
|
Every document carries its state in YAML frontmatter — research overviews, design documents,
|
|
decision records, issue reports — with a schema stated in the section README.
|
|
|
|
**There are no central status files.** Every cross-cutting view — a status matrix, the
|
|
decision-record index, the open-issue list — is generated from frontmatter when asked for, and
|
|
never written to disk.
|
|
|
|
Prose does not restate status. One place, and two is one too many.
|
|
|
|
## Consequences
|
|
|
|
- A view cannot drift from what it describes, because it does not persist.
|
|
- Status becomes queryable. Inconsistencies — a closed effort with nothing in `became:`, an
|
|
`implemented` design with no owning repository — are findable mechanically, and the
|
|
generator reports them as flags rather than silently rendering around them.
|
|
- Frontmatter must be valid and paths in it must resolve, which is now something to check.
|
|
- A reader browsing the repository on a forge sees no index. That is the trade: the index is
|
|
correct and absent rather than present and wrong.
|
|
|
|
## References
|
|
|
|
- [`.claude/skills/hal-status/SKILL.md`](../.claude/skills/hal-status/SKILL.md) — the
|
|
generator, including the inconsistencies it flags.
|
|
- [`02-DECISIONS/README.md`](README.md) — the hand-written index that drifted, and its removal.
|