jschoubben
becae7ba51
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
56 lines
2.7 KiB
Markdown
56 lines
2.7 KiB
Markdown
---
|
|
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.
|