jschoubben
93a1231e00
Skills take the hq- prefix: they are HQ process workflows, not mesh workflows, and HQ is company-scoped now. hq-new-research, hq-graduate, hq-new-issue, hq-diagnose, hq-amend-design, hq-handoff, hq-sync-constitution, hq-status. Forward-looking prose becomes Novox Mesh or simply the mesh — the root README, AGENTS.md, the 00-META README, the mission's module example, and one to-be document that addressed 'someone working on HAL'. Three categories deliberately keep HAL, per ADR 0027: The monorepo is still called hal on the forge. repos.md, every code: field and every located-in: field name a repository that exists under that name, and renaming them in prose would make them false. The as-is layer and the research that measured it describe the system that runs, and that system is called HAL. 124 modules, 9 daemons, a dead containerised node — those are observations, not intentions. Records 0001-0026 are immutable. A record says what was decided when it was decided, and no record is edited for a name. Also repoints ADR 0022's link at the renamed skill — a path fix, which the immutability rule permits, not a change of meaning.
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/hq-status/SKILL.md`](../.claude/skills/hq-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.
|