Follow papa-hq's research convention; the mesh links nothing

Research efforts move from status.md to 00-overview.md with active /
graduated / abandoned, matching papa-hq so the two repositories read the
same way. Playbooks, skills, README and the ledger follow.

Reverses yesterday's withdrawal of the symlink note in GENESIS. The note
was right and the withdrawal was wrong: the intent is that the mesh
creates no symlinks at all, so a founding document listing "symlinks, not
copies" as a design principle does point the opposite way from where this
is going, and that is a contradiction rather than a stale detail.

ADR 0018 records the position, proposed. ADR 0011 stays as it is — it is
the historical decision and the incident behind it is why anyone believes
either record — and is superseded in intent, not edited. Its one
editorial line, which called the wider reading false, is corrected to
state what is actually true: centralising who may link narrowed the
incident class without closing it, because a link the installer makes
resolves exactly like one made by hand.

The argument that kept linking was staleness. ADR 0004 removed it: every
managed file is already derived and reconciled, so a copy is the natural
form and a pointer into source is the shape the mesh's own model forbids
everywhere else. What is not settled, and is marked open, is how
staleness gets detected — which is the decision that makes or breaks it.
This commit is contained in:
2026-08-23 09:29:09 +02:00
parent 702efca6bb
commit f05e4a0dce
17 changed files with 143 additions and 28 deletions
+13 -6
View File
@@ -38,9 +38,16 @@ comparing it against the code rather than by anyone noticing:
- It listed the mesh as spanning a fixed number of named machines, which is exactly the
content this repository cannot carry.
One earlier note in this file has been withdrawn as **wrong**, and is recorded here rather than
deleted. It claimed the overview's "symlinks, not copies" principle contradicted the mesh's
hard rule against symlinks. It does not. The rule forbids *creating* a symlink by hand; the
installer creates and reconciles every link the mesh needs, deliberately
([ADR 0011](../adr/0011-the-installer-owns-linking.md)). The rule is about who may link, not
about whether the mesh links — a misreading common enough that the ADR now says so explicitly.
It also lists **"symlinks, not copies" as a key design principle**, and that is a genuine
contradiction rather than a stale detail. The mesh's stated intent is that it creates no
symlinks at all — the rule is not merely "only the installer may link", and a founding document
elevating linking to a principle points the opposite way from where this is going.
What exists today is that the installer owns and reconciles every link
([ADR 0011](../adr/0011-the-installer-owns-linking.md)) — an as-is fact, recorded in
[`02-DESIGN/00-as-is/05-runtime-and-installation.md`](../02-DESIGN/00-as-is/05-runtime-and-installation.md).
Centralising who may link narrowed the incident class; it did not close it. The intent is to
remove the mechanism, recorded as [ADR 0018](../adr/0018-the-mesh-creates-no-symlinks.md).
A founding document contradicting the direction of travel is precisely the failure this folder
exists to prevent.
+1 -1
View File
@@ -39,7 +39,7 @@ incident behind it is not written down, and the fix is to write it down, not to
| **Never write to a production database directly** | No insert, update, delete or schema statement executed against production by hand. Schema changes go through numbered migrations; data changes go through application code or the module's own capabilities. Raw statements skip every side effect the proper path has — events, audit, cache invalidation, fan-out. |
| **Every schema change is a migration** | Numbered, in the module's own language, compiled with it. Both a baseline for a fresh installation *and* an incremental migration for installations that already exist. If code references a column, the migration creating it must exist. [ADR 0006](../adr/0006-schema-changes-are-numbered-migrations.md) |
| **Never bypass the pipeline** | No manual database edit, no manual restart as a workaround. Fix the cause and deploy. A workaround that works is a workaround that is never removed, and the next person cannot tell the node from its declaration. |
| **Never create a symlink** | The installer owns all linking and reconciles it. A hand-made link caused production data loss through container volume resolution — and the judgement needed to make a safe exception is exactly the judgement unavailable at the moment it matters. [ADR 0011](../adr/0011-the-installer-owns-linking.md) |
| **Never create a symlink** | A hand-made link caused production data loss through container volume resolution, and the judgement needed to make a safe exception is exactly the judgement unavailable at the moment it matters. Today the installer owns and reconciles the links the mesh still uses [ADR 0011](../adr/0011-the-installer-owns-linking.md); the intent is that the mesh creates none at all [ADR 0018](../adr/0018-the-mesh-creates-no-symlinks.md). Neither reading permits you to make one. |
| **Never push directly to the main branch** | Branch, push, review, merge. Every merge is a human checkpoint, without exception. |
| **One change per pull request, and never merge your own** | Unrelated improvements bundled together cannot be reviewed or reverted separately. Self-merging removes the checkpoint that is the entire point. |
| **Never open a pull request unprompted** | A permissions list saying it is allowed is not a request. |
+3 -3
View File
@@ -9,7 +9,7 @@ design. Also: an as-is document that raises a question nobody can answer.
1. Take the next free number: highest `01-RESEARCH/NNN-*` plus one, zero-padded to three
digits. Never skip or reuse a number.
2. Create `01-RESEARCH/NNN-descriptive-name/` and a `status.md` in it carrying:
2. Create `01-RESEARCH/NNN-descriptive-name/` and a `00-overview.md` in it carrying:
```yaml
---
@@ -22,7 +22,7 @@ design. Also: an as-is document that raises a question nobody can answer.
Then a short prose summary: **what** is being investigated, **why**, and **what it
touches**.
3. Do the research in further documents in the same folder — notes, option analyses, evidence,
draft designs. Anything goes. Keep the summary in `status.md` current as the effort changes
draft designs. Anything goes. Keep the summary in `00-overview.md` current as the effort changes
shape.
## What makes research worth reading
@@ -37,7 +37,7 @@ carries the whole lesson without naming anything.
## Do not
- Do not put status in prose. It lives in `status.md`'s frontmatter, and the prose must not restate it.
- Do not put status in prose. It lives in `00-overview.md`'s frontmatter, and the prose must not restate it.
- Do not set `became:` while the effort is open — playbook 02 sets it at closure.
- Do not write into `02-DESIGN` from an open effort.
+1 -1
View File
@@ -25,7 +25,7 @@
---
```
4. **Close the effort.** Set the effort's `status.md` frontmatter to `status: graduated` and
4. **Close the effort.** Set the effort's `00-overview.md` frontmatter to `status: graduated` and
`became:` pointing at the design document and the decision record.
5. **Add a ledger line.** Append the decision to [`DECISIONS.md`](../../DECISIONS.md) under
today's heading, pointing at the record.