jschoubben
3ab11c96ef
The design described what the host does and never what it is at runtime. The words daemon, long-running, interval, poll and heartbeat appeared nowhere in it or in the relevant decisions. What exists is a command that runs and exits; what the design needs is a process holding a link. Nobody had written down that those differ, so several questions had no answer. 0057 settles them. It runs on every node -- the host is what makes a machine managed, so a machine without one is not a node. Root, because no useful subset of the job is unprivileged. A systemd unit, because something must survive a reboot to hold the link. It never manages its own unit. The temptation is obvious and it ends with a host stopping itself half way through an apply, leaving a machine with nothing running to fix it. The installation owns the host; the host owns everything else. Installed as a package, with a tarball as the floor. The package carries the unit file, the state directory and an upgrade path, which a bare binary does not. But the mesh's package repository is hosted on the mesh, so any route that needs the mesh to install the thing that joins the mesh is a circle -- the tarball is the path that must never acquire a dependency. Reconciles on start, on a declaration, on a timer and on reconnect. The timer is the one easy to leave out, and without it `owned` reports what the host applied rather than what is there -- ADR 0035 violated by omission. The records checker caught this commit on its first attempt: 05 listed 0057 in its frontmatter while 0057 is still proposed, and a to-be document may not rest on an unaccepted record. The section now says so in the body instead.
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.