ADR 0081: a decision nothing cites is not yet in the chain

Decisions were the one link the cycle checks skipped, and measuring found 19 of 70 records
orphaned — the credential flow and the module-runtime cluster among them, which is how a
stale premise about a settled decision survived in working memory. cycle.py now refuses an
accepted record nothing cites; the 19 got true homes (design frontmatter, the playbook that
implements 0021, META for the process records). The overview names the practice: spec-driven
development with provenance.

https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
This commit is contained in:
2026-09-17 22:36:33 +02:00
parent 1162f7fe25
commit 90e4a368dc
12 changed files with 107 additions and 1 deletions
@@ -0,0 +1,51 @@
---
topic: how we work
status: accepted
date: 2026-09-17
deciders: jochen
reconstructed: false
extends: 0080-the-development-cycle-is-checked.md
---
# 81. A decision nothing cites is not yet in the chain
## Context
[ADR 0080](0080-the-development-cycle-is-checked.md) made the development cycle checked — but its
checks covered designs, issues and research, not the decisions themselves. Measuring showed why
that matters: 19 of 70 records were cited by nothing — no design doc's `decisions:`, no research
`became:`, no issue, no other record. Among them sat load-bearing decisions (the credential flow,
the module-runtime cluster), and the cost had already been paid once in practice: a stale premise
about an orphaned decision survived in working memory precisely because no pointer led to the
record that had settled it.
## Decision
Every **accepted** decision must be reachable from the cycle: cited by a design doc's frontmatter
(`decisions:` — a governing citation, not a prose mention), a research overview, an issue report,
a `00-META` document, or another record's `extends`/`supersedes` chain.
[`cycle.py`](../00-META/checks/cycle.py) refuses orphans. Proposed records are exempt — a record
under consideration has no home yet — and superseded records are reachable through their
supersession chain by construction.
The 19 orphans were given true homes in the same change: the module-runtime cluster
(0044–0049, 0053–0055) into the connectivity, controller, protocol, writing and model-access
designs; the build decisions (0072, 0076) into the building design; 0021 into the playbook that
implements it; the process records were already reachable once `00-META` counted as a source.
Taken together with 0080, the practice has a name the industry will recognise:
**spec-driven development, with provenance** — a decision is the *why*, the design doc is the
spec, `code:` names the implementation, and the lab beds are the conformance tests. What the
common form leaves implicit, the cycle makes checked: the spec itself must trace to a decision,
and the decision must be findable from the work it governs.
## Consequences
Following pointers now reaches every accepted decision, so a cleared session (or a person) can
trust the frontmatter graph as the whole map. The check is reachability, not truth: a citation
placed wrongly still lies, and reading remains the job.
## References
- [ADR 0080](0080-the-development-cycle-is-checked.md) — the cycle this completes.
- [`00-META/process/00-overview.md`](../00-META/process/00-overview.md) — the flow.
+1
View File
@@ -166,5 +166,6 @@ python3 00-META/checks/index.py fail if stale
- **0032** — [The local account owns the mesh; a surface delegates to a module](0032-the-local-account-owns-the-mesh.md) *(superseded)*
- **0034** — [The local account owns the mesh, and a web application's login is not that](0034-the-local-account-owns-the-mesh.md)
- **0080** — [The development cycle is checked, not trusted](0080-the-development-cycle-is-checked.md)
- **0081** — [A decision nothing cites is not yet in the chain](0081-a-decision-nothing-cites-is-not-yet-in-the-chain.md)
<!-- index:end -->