jschoubben
90e4a368dc
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
2.5 KiB
topic, status, date, deciders, reconstructed, extends
| topic | status | date | deciders | reconstructed | extends |
|---|---|---|---|---|---|
| how we work | accepted | 2026-09-17 | jochen | false | 0080-the-development-cycle-is-checked.md |
81. A decision nothing cites is not yet in the chain
Context
ADR 0080 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 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 — the cycle this completes.
00-META/process/00-overview.md— the flow.