jochen
daa9f171ae
The import of slice 3 (ADR 0275) was checked against every folder: no report changed since the commit it read, and the tracker holds each report's status, owner, fix, design amendment, replay and closing day. The keys are removed from all 361 reports, cycle.py refuses them in any report, and the playbooks, skills and READMEs that still pointed at them name the tracker instead.
4.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. - No two records answering to one number — added 2026-09-30; see the insight below.
Progressive insight — 2026-09-30. The list above named four things
cycle.pyenforces, and now names five. Nothing enforced that two issue records hold different numbers: two machines filing issues within one hour both readmain, both took "the next free number", and collided twice — the second collision reachingmainwithrecords.py,cycle.pyandindex.pyall reporting success (04-ISSUES/155). A number is how every other record cites one, so two records answering to it is a citation that resolves to whichever folder the reader opened.cycle.pyrefuses it now. The decision here stands exactly as written: this is one more thing frontmatter and file names can carry, found by its absence rather than by reasoning.
Progressive insight — 2026-10-10. The third rule above, no owner-less diagnosis and no fix-less fix, and the replay rule
cycle.pytook on under ADR 0237, moved out ofcycle.pythe day slice 3 of ADR 0275 landed: an issue's status lives in the issue tracker, whosemoverefuses at the write what the check refused at merge —locatedwithout an owner,resolvedwithout a fix, a core issue without its replay,wontfixwithout a reason. Enforced mechanically still, one step earlier, in the one place the status is.cycle.pykeeps the fifth rule, no two records answering to one number, and refuses a status key in a report opened after the import. The decision stands: the cycle is checked, not trusted; which program checks each rule is a fact that moved.
Progressive insight — 2026-10-10, later.
cycle.pyrefuses a status key in any report, not only one opened after the import: the keys the older reports carried were removed once the import was checked against every folder (ADR 0275's last note).
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.