novox/hq

Files

T

jschoubben 47909c6b71 The records pointed at branches that no longer exist, and two fixes had no sequel

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.

2026-09-30 00:28:35 +02:00

3.5 KiB

Raw Blame History

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-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 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.

3.5 KiB Raw Blame History