jschoubben
f49d177a31
0054 -- things that change together share an authority, not a package. The constitution instructs agents to group "how a node is reachable" into one module, citing superseded ADR 0017; ADR 0044 says there is no networking thing to install. Since the constitution is injected where work is decided, the superseded rule is the one actually steering work. The observation behind it was right -- research 005 measured that reachability is the only place modules genuinely change together -- but the conclusion was wrong: tight coupling means a shared authority, not one artifact. wireguard and traefik deploy to different node sets, so the merged module would be assigned where half is unwanted. Requires amending how-we-build and republishing the derived page. 0055 -- the control plane is the node-coordinating contexts. Three context lists were in circulation (0015 says nine, 06 says ten, the README said eight) and none was decided. Research 006 said explicitly that the change "belongs in a new record -- not written here", and the design used the list anyway. Reconciling them shows `stream` and `ai` were dropped with no reasoning at all. Applying 06's own test -- needs to know about more than one node -- gives seven contexts plus the api, with work, knowledge and stream as hosted applications and `ai` folded into config as an ordinary grant. The record defers rather than lists. The cost is stated rather than reassured away: a board composing across the boundary reads more than one interface. That was raised before as "only moves the problem up a layer", and the answer is that 0045 already requires surfaces to read interfaces rather than stores -- what changes is the count, not the kind of work. 0056 -- the authority is the control plane, not a database. Every clause of 0003 has been decided against in four separate records and it is still accepted and cited as live. The error underneath is the same category error 0054 corrects: "source of truth" named a storage location when it meant an authority, and once the store is the answer, shared schemas follow. The half that was right -- the repository defines what exists, the mesh defines what runs where -- survives untouched. Best consequence: the cache mode disappears, so a node that has not heard from the mesh is no longer indistinguishable from one that has. 0003 is left accepted until 0056 is.
02-DECISIONS
Architecture decision records — the "why" trail behind the rules in
00-META and the specifications in 03-DESIGN.
Numbered 02 because a decision precedes the design it authorises. Research concludes,
the decision is recorded here, and only then is the design written. Following the folder
numbers walks the process in the order it happens.
One file per decision, numbered, never deleted. A superseded record has its status: changed
and gains a pointer to what replaced it — its text is never edited. The reasoning that was
rejected is the expensive half to rediscover.
The records run in the order the decisions were taken, oldest first.
Every decision is a record. There is no ledger and no index file — if a decision is worth
recording it is worth a record, and if it is not worth a record it is not recorded
(ADR 0026). A "decision" small enough to be one line is
almost always a rule, and a rule belongs in
00-META/how-we-build.md, where it is enforced and keeps the
incident that earned it.
Frontmatter
---
status: proposed | accepted | superseded
date: YYYY-MM-DD # when the decision was taken, not when it was written down
deciders: name
reconstructed: true|false # true when the record was written after the fact from evidence
superseded-by: # 02-DECISIONS/NNNN-....md, when status is superseded
extends: # 02-DECISIONS/NNNN-....md, when this record widens an earlier one
---
Body
# N. Title in plain language
## Context what was true, with evidence
## Considered Options numbered, each with why it was rejected
## Decision what was decided
## Consequences what follows, including what got harder
## References commits, pull requests, knowledge-base entries, prior art
State evidence, not assertion. "Zero of 124 modules declare brain as a dependency"
outranks "the dependency rule is not followed".
Reconstructed records
Records 0001–0014 were written on 2026-08-23, after the decisions they describe. Records 0015 onward were taken as records. Those
decisions were taken in implementation rather than in a document; the records state what was
decided and the evidence it was decided from, and each carries reconstructed: true and says
so in its first lines.
A reconstructed record is not a transcript. Where the deliberation is not recoverable, the options section states what the alternatives were and why the chosen one won on the evidence available — not a discussion that did not happen. Where a date is not establishable it says so rather than guessing.
Index
The index is generated, not maintained — run the hq-status skill, which reads the
frontmatter of every record. A hand-written index drifts from the folder it describes, and
this one had already done so after a single addition.