jschoubben
00b8398d07
Agent is a first-class concept here — a participant, some of whom are human, holding identity and memory. Using it for the tier-0 node binary put both meanings in one document: hal-agent at tier 0, agents at tier 2. That is the anatomy-naming failure again, an evocative domain word pointing at infrastructure, and how-we-build 4 exists to catch it. ADR 0015's own title supplies the fix: the mesh brokers, nodes host, agents think. So the control plane brokers (hal-mesh), the tier-0 binary hosts (hal-host), the participant thinks (agents, untouched). hal-node was rejected — Node is the inventory aggregate, the binary is what runs on it. Recorded in the document as a near-miss rather than quietly corrected. Tiers now explained before the tree, as a boot narrative, with the point they were carrying made explicit: dependencies point only downward, that is the whole bootstrap answer, and the current mesh violates it — the database is a module, modules come from the pipeline, the pipeline needs the database. Connectivity gains the part that was missing. Naming a context says who decides, not who runs it: overlay membership is tier 0 in the host, policy is tier 2, machinery is tier 4 modules. And the host's link to the control plane deliberately does not run over the overlay, or the overlay would have to exist before a node could be told how to join it. 'tier' is this document's coinage and did not land on first reading; that is now an open question rather than settled vocabulary.
01-RESEARCH
Investigations that have not yet hardened into design.
Structure
Each effort lives in NNN-descriptive-name/ and must contain 00-overview.md, carrying its
state in YAML frontmatter and a prose summary below it:
---
status: active | graduated | abandoned
initiated: YYYY-MM-DD
touches: [] # design docs, subsystems or areas the effort bears on
became: [] # required when status is terminal — what it turned into
---
The prose says what is being investigated, why, and what it touches. It does not restate the status — status lives in one place, and two places is one too many.
Further documents in the same folder hold the work itself: notes, evidence, option analyses, draft designs.
Lifecycle
| status | Meaning |
|---|---|
active |
Investigation in progress. |
graduated |
Checked against 00-META, decided in 02-DECISIONS/, and specified in 03-DESIGN — see became:. |
abandoned |
Stopped or superseded. Nothing is deleted. |
An effort graduates by producing a decision record and a 03-DESIGN entry. It is abandoned
in place — never deleted. What was rejected, and why, is the more expensive half to
rediscover.
Starting and closing efforts is playbook territory:
00-META/process/01-research.md and
02-graduation.md.
Rules
- Markdown only. Do not skip or reuse a sequence number.
- Evidence, not assertion. An effort that measured nothing has not finished.
- Research describes real observations but never identifies the mesh it observed. The shape of a finding survives anonymisation intact.