Files
hq/01-RESEARCH
jochen 478a198e9a
mesh/merge-gate pass: the change touches no module of the mesh's graph
mesh/repo-check pass: its merge-check.sh passed
mesh/delivery superseded: a newer head of the same pull request
ADR 0247: a machine with a VPN client routes names by domain, through a resolver of its own
Research 033 measured the laptop's VPN client and the mesh overwriting each
other's resolver file in nine of nine sessions, each time cutting off one
kind of name. The operator chose a resolver module on a node seat of its
own, installed only where something requires split-dns, with the VPN
client's module carrying the adapter. Graduates research 033 into to-be 50,
and amends connectivity §2, to-be 48 §10, the seats and the glossary.
2026-10-07 21:33:48 +02:00
..

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.