---
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.