jschoubben
b4365d8aa4
A skeleton laid out against the stated requirements rather than derived from the current shape: four tiers, repositories at the root, and a dependency rule that only points downward. Four moves the current shape does not have. The substrate is applied by the agent from a pinned bundle, not delivered by the pipeline. That is the bootstrap circularity removed rather than worked around — the first node is the ordinary path with no control plane on the other end, which also makes it the cheapest lab scenario instead of the one nobody exercises. One agent binary with a detected capability profile — managed, user, edge. A phone becomes a capability question rather than a platform question, so it needs no second implementation. Modules declare which profiles they can land on, and an impossible assignment fails at declaration. Connectivity becomes a context. ADR 0015 names nine and none owns the overlay, resolver, firewall or ingress, while research 005 measured reachability as the only cluster in the catalogue that genuinely changes together under one intent. Gap and evidence point the same way. That is an addition to an accepted record, so it needs its own record and is not written here. Feature splits into artifact (built once per version) and part (selected per node). The conflation of those two cardinalities under one word is what makes the delivery pipeline hard to reason about. Also makes explicit in how-we-build that the main-branch rule covers this repository too. The rule already said 'without exception'; nothing was amended, so nothing is recorded.
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.