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
2.7 KiB
topic, status, date, deciders, reconstructed, extends
| topic | status | date | deciders | reconstructed | extends |
|---|---|---|---|---|---|
| how we work | accepted | 2026-09-17 | jochen | false | 0019-how-this-repository-works.md |
80. The development cycle is checked, not trusted
Context
ADR 0019 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-progressorimplementeddesign names its owning code incode:. - No owner-less diagnosis, no fix-less fix — an issue marked
locatedorfixednameslocated-in:; one markedfixedorresolvedsaysfixed-by:(prose counts — "nothing, the capability existed" is an answer). - No silent graduation — a
graduatedresearch overview says what itbecame:, and the targets exist.
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 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— the flow, and its new "The cycle is checked" section.- ADR 0019 — the repository this disciplines.