jschoubben
47909c6b71
Three issues named the branch that fixed them, and a branch is deleted when it merges — so every `fixed-by:` was a pointer that resolved to nothing by the time anyone followed it. They name commits and pull requests now, and playbook 03 says to. Two records were missing the thing a reader arrives for. 146 did not say that one of its fixes crash-looped the control plane on a running mesh, which is the whole reason the delivery subject carries the stream and the raise path was the only one exercised. 151 did not say that 152 removed the false reasons its roster moved, or that it stays open for the real ones. ADR 0080 enumerates what cycle.py enforces and named four things; it enforces five. A progressive insight names the fifth — the decision stands, the list had gone stale. The checks README and playbook 03 gained the same rule, and 155 points at all three.
66 lines
3.5 KiB
Markdown
66 lines
3.5 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.
|
|
- **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.py` enforces, and
|
|
> now names five. Nothing enforced that two issue records hold different numbers: two machines
|
|
> filing issues within one hour both read `main`, both took "the next free number", and collided
|
|
> twice — the second collision reaching `main` with `records.py`, `cycle.py` and `index.py` all
|
|
> 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.py`
|
|
> refuses 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.
|
|
|
|
[`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.
|