jschoubben
4ab8a0507f
Jochen: don't rebuild the current coordinator, use it as a pitfall list. That reframed the last open question rather than answering it. 0058 stopped deploy being a stage that pushes to nodes, and said plainly what it did not fix: detection. A merge that created no pipeline, and nothing said so. That is not a defect in the detector -- it is what happens when correctness depends on an event ARRIVING. 0063 applies 0058's move one level up. The control plane holds what source exists and what has been built from it, and builds the difference. A change becomes a build because source is ahead of artifacts, which is a comparison answerable at any moment. An event makes it fast; nothing makes it necessary, so a missed webhook costs latency and cannot cost correctness. The mesh becomes one idea at two layers: the control plane reconciles artifacts against source, the host reconciles machine state against declarations. The pipeline as a state machine disappears, and with it the stage list that a verify step was once omitted from. That reframing answered the three questions still open in 008, so it graduates with all six closed. A deployed state is two comparisons rather than an event. A verdict is about an ARTIFACT and gates whether it may be declared -- sharper than the question expected. And "before self-hosting" mostly dissolves, because a reconciler needs source and artifacts as bindings where a pipeline's stages name their targets. Four costs recorded, and one is a real risk rather than a trade: a reconciler that cannot reach its target retries forever, and without something noticing, the failure is silence -- the exact fault this removes, reintroduced elsewhere. Also named: the run identity people actually use is lost, and "did my change go out?" needs a replacement or this will be worse to live with than what it replaces, whatever its properties.
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.