ADR 0080: the development cycle is checked, not trusted
The flow the process overview draws — idea/symptom -> decision -> to-be design -> code -> as-is — was enforced by nothing. cycle.py now refuses a to-be design naming no decision, an in-progress/implemented design naming no owning code, a located/fixed issue with no owner, a fixed/resolved issue with no fix, and a graduated research overview that does not say what it became. AGENTS.md carries the cycle and a where-to-look table so a fresh session (or a cleared context) finds the chain in frontmatter instead of assuming it. Grounding the check surfaced two real gaps, fixed here: the work-ahead design named no owning code, and research 003 listed one became target twice. https://claude.ai/code/session_01D6qtiYU3P9jk3pnAXyAFyx
This commit is contained in:
@@ -0,0 +1,55 @@
|
||||
---
|
||||
topic: how we work
|
||||
status: accepted
|
||||
date: 2026-09-17
|
||||
deciders: jochen
|
||||
reconstructed: false
|
||||
extends: 0019-how-this-repository-works.md
|
||||
---
|
||||
|
||||
# 80. The development cycle is checked, not trusted
|
||||
|
||||
## Context
|
||||
|
||||
[ADR 0019](0019-how-this-repository-works.md) made this repository the source of truth, and the
|
||||
process overview drew the flow work must follow: an idea or a symptom, a decision, a to-be design,
|
||||
a build in a code repository, an as-is update on shipping. The playbooks describe every step, and
|
||||
frontmatter carries every status.
|
||||
|
||||
But the flow itself was enforced by nothing. A design could appear citing no decision; a design
|
||||
could sit `in-progress` naming no code; an issue could be `fixed` by nobody knows what. Each is
|
||||
indistinguishable from correct work until somebody reads carefully — and the whole point of the
|
||||
playbooks is that nobody should have to hold this repository in their head. A session that starts
|
||||
cold (or an agent after a context clear) must be able to *find* the chain by following frontmatter
|
||||
pointers, which only works if the pointers are reliably there.
|
||||
|
||||
## Decision
|
||||
|
||||
The development cycle is enforced mechanically, to the extent frontmatter can carry it:
|
||||
|
||||
- **No design without a decision** — every to-be design names at least one record in `decisions:`.
|
||||
- **No development without a design that says where** — an `in-progress` or `implemented` design
|
||||
names its owning code in `code:`.
|
||||
- **No owner-less diagnosis, no fix-less fix** — an issue marked `located` or `fixed` names
|
||||
`located-in:`; one marked `fixed` or `resolved` says `fixed-by:` (prose counts — "nothing, the
|
||||
capability existed" is an answer).
|
||||
- **No silent graduation** — a `graduated` research overview says what it `became:`, and the
|
||||
targets exist.
|
||||
|
||||
[`00-META/checks/cycle.py`](../00-META/checks/cycle.py) refuses violations, beside `records.py`
|
||||
and `index.py`; all three run before any merge here. What frontmatter cannot see — that code work
|
||||
actually started from a handoff — remains held by playbooks 04 and 07: a feature branch exists
|
||||
because a design or an issue sent it, and a merge is a human checkpoint.
|
||||
|
||||
## Consequences
|
||||
|
||||
A `/clear` costs little: [`AGENTS.md`](../AGENTS.md) now carries the cycle and a where-to-look
|
||||
table, and the chain a fresh session needs is guaranteed present in frontmatter rather than
|
||||
reconstructed from memory. The checks are the floor, not the ceiling — they verify pointers exist,
|
||||
not that their content is true; reading remains the job.
|
||||
|
||||
## References
|
||||
|
||||
- [`00-META/process/00-overview.md`](../00-META/process/00-overview.md) — the flow, and its new
|
||||
"The cycle is checked" section.
|
||||
- [ADR 0019](0019-how-this-repository-works.md) — the repository this disciplines.
|
||||
Reference in New Issue
Block a user