jschoubben
b4904fec7e
The lab was designed around a module under test, with a scenario being a complete mesh — forge, coordinator, cascade, verify. That is unusable for building the new mesh, because all four are tier 2 and do not exist yet. And research 009 had the sequence backwards. It placed the lab at phase B as verification of tiers already built, but tier 0 is the component that takes over a machine's packages, services and network. It cannot be developed against a machine anyone needs. The lab has to exist before the thing it will test. ADR 0029 splits scenarios into two classes. The bootstrap scenario is virtual machines, the host binary and a pinned bundle, with the verdict coming from what the host reports about the state it reconciled. The full scenario is the designed one. The first is a strict subset of the second — same virtualisation, same networking, same lifecycle, stopping before a control plane exists — so the second is reached by addition rather than rework. The consequence worth having: raising a node from nothing stops being the least-exercised path in the system and becomes the inner development loop. It also settles the runner's two jobs. Scenario lifecycle is needed immediately, because something must materialise and reset a mesh before anything can be written against it. Assertion execution waits for the full scenario. Corrects a stale claim in the design while amending it: it argued scenarios were affordable with system containers and would not be with virtual machines. ADR 0016 superseded that reasoning and the text had not followed. Issue 007: the lab's first requirement is installed and unusable. The virtualisation package is present and explicitly installed; both units are disabled, the operator is in no group, and the client reports the server unreachable. Not issue 001 again — that is an install failing while reporting success. This is an install succeeding when success was not the point. A package is files; a capability is a running service and an identity permitted to reach it, and the module model has no vocabulary for the second.
03-DESIGN
The authoritative specification. Implementation is built against what is written here.
Two layers
| Folder | What it is |
|---|---|
00-as-is/ |
The mesh that exists today. Shipped behaviour, described as it is — including behaviour nobody would choose again. |
01-to-be/ |
The mesh being built toward. Every statement traceable to a record in 02-DECISIONS/. |
They are never mixed. A statement about the future does not belong in an as-is document, and an as-is document is never edited to describe an intention.
When a to-be design ships, it does not move. Its as-is counterpart is written or updated,
the to-be document's status becomes implemented, and both stand — one describing what runs,
the other recording what was intended. Deleting the intention loses the reasoning, which is
the expensive half.
Frontmatter
Every design document (not the READMEs) carries:
---
layer: as-is | to-be
status: designed | in-progress | implemented | abandoned
code: [] # owning code repo(s), from 00-META/repos.md
updated: YYYY-MM-DD # date of the last status change, not of text edits
decisions: [] # 02-DECISIONS/ records this document rests on
---
For an as-is document, status: implemented is the normal state — it describes something that
runs — and code: names where that implementation lives.
Status changes when implementation state changes, never because design text was edited. An
implemented claim must be defensible from the owning repository's main branch, not from
intent. If it cannot be checked, it is in-progress.
Cross-cutting views are generated from this frontmatter by the hq-status skill and never
written to disk.
What belongs here
Functional analysis, architectural description, and specification — prose and diagrams
only, no code. A manifest field may be named; a manifest may not be pasted. A document
enters the to-be layer only after the decision behind it is recorded in 02-DECISIONS/
and the research that produced it is closed.
Subfolders are encouraged where a layer grows enough to need them.