Order the records the way the system is learned

Jochen asked whether the order made sense. It did not -- it followed when things happened to be decided, which after consolidation is fictional anyway since record 5 alone folds decisions taken across a week. Concretely wrong before: the domain statement sat at 8, after five engineering rules; the constitution was scattered across 5, 12 and 17; the tiers landed at 15, 16, 21 and 22 with process records in between. Now it walks: what the mesh is (1-3), its tiers from the bottom up (4-8), what runs on them and how it gets there (9-10), how it is built (11-16), how it is checked (17-18), how we work (19-23). Two things made this safe rather than free. It is a permutation, not a compaction, so the renames go through temporary names -- otherwise two files want one slot and one is lost. And the reference rewrite is a single simultaneous pass, because almost every number moved into a slot another number was vacating; replacing one at a time would have cascaded and pointed things at the wrong record while still resolving. Verified: 284 [ADR NNNN](path) links across the repository, all with matching text and target. The ordering principle is now stated in 19 rather than left implicit -- the repository already said "the numbering is the flow" about its folders, and there was no reason for the records to be the exception.
2026-08-28 23:30:42 +02:00
parent e1febe8e0f
commit 333356cff3
85 changed files with 471 additions and 465 deletions
@@ -31,14 +31,14 @@ exists to catch — a step that failed, reported success, and left the next step
 state that was never produced.

 It is also a direct violation of a decision already taken and recorded:
-[ADR 0023](../../02-DECISIONS/0023-delivery.md) says a step that fails must fail the
+[ADR 0010](../../02-DECISIONS/0010-delivery.md) says a step that fails must fail the
 job. That record notes the rule is applied instance by instance and enforced by no mechanism.
 This is an instance where it was never applied.

 ## Evidence

 - Observed 2026-08-22 while declaring the virtualisation package required by
-  [ADR 0009](../../02-DECISIONS/0009-the-lab.md).
+  [ADR 0016](../../02-DECISIONS/0016-the-lab.md).
 - A fix is written and open as a pull request, unmerged since 2026-08-20.

 ## Open questions
@@ -21,7 +21,7 @@ recoverable by retrying — it removes the ability to issue a certificate anyone

 The consequence lands hardest on exactly the work most likely to iterate: standing up a new
 node, changing how names resolve, or testing the lab's certificate authority split
-([ADR 0009](../../02-DECISIONS/0009-the-lab.md)).
+([ADR 0016](../../02-DECISIONS/0016-the-lab.md)).

 ## Evidence

@@ -29,7 +29,7 @@ coverage was assumed, not checked.
 ## Evidence

 - The workspace was removed by pull request #240 on 2026-06-04
-  ([ADR 0004](../../02-DECISIONS/0004-no-npm-workspace.md)).
+  ([ADR 0014](../../02-DECISIONS/0014-no-npm-workspace.md)).
 - The harness has not built since that date.
 - Recorded in the knowledge base as a standing entry, not as a fixed incident.

@@ -59,7 +59,7 @@ checked it — including in the same commit that wrote the rule.
 ## Proposed direction — Nox is the search

 *Added 2026-08-23.* Rather than syncing these documents into the knowledge base, **Nox
-([ADR 0011](../../02-DECISIONS/0011-how-this-repository-works.md)) works from within this
+([ADR 0019](../../02-DECISIONS/0019-how-this-repository-works.md)) works from within this
 repository and holds its knowledge directly.** Retrieval becomes an agent reading the source,
 not a copy living in a second store.

@@ -71,7 +71,7 @@ This is a better answer than the one the README originally promised, on three co
  was that it adds a fourth knowledge *system*. An agent with read access adds no store at all.
 - **It is always current**, including for uncommitted work in progress.

-**But it changes the promise, and that is worth stating rather than glossing.** ADR 0011's
+**But it changes the promise, and that is worth stating rather than glossing.** ADR 0019's
 answer was that these documents would be returned *beside everything else* in a symptom search.
 An agent that must be **asked** is reachable; it is not surfacing. The two differ in exactly
 the case the operational memory is designed for: someone debugging an error who has no reason
@@ -82,9 +82,9 @@ So the open question narrows to one thing:
 > When a symptom is searched and the answer happens to live in a design document or a decision
 > record here, does the searcher find it without already suspecting it exists?

-If Nox is the only path, the answer is no, and the reasoning in ADR 0011 needs amending rather
+If Nox is the only path, the answer is no, and the reasoning in ADR 0019 needs amending rather
 than satisfying. If Nox also contributes what it knows to a symptom search — or the search
 consults Nox — the answer is yes and the original promise holds.

 That is a design question for Nox, not a defect in this repository, and it should be settled
-before ADR 0011 is treated as answered.
+before ADR 0019 is treated as answered.
@@ -44,7 +44,7 @@ The distance between the two is the same one the delivery layer already has a na
 ## Why it matters now

 This is the first requirement of the lab
-([ADR 0009](../../02-DECISIONS/0009-the-lab.md)), which is
+([ADR 0016](../../02-DECISIONS/0016-the-lab.md)), which is
 phase 0 of the entire migration. The first capability the new work depends on is present,
 declared, and unusable — and would have stayed unusable silently.

@@ -35,7 +35,7 @@ node recovers itself.
 ## Scope

 **The as-is only.** The design being built has a different answer:
-[ADR 0016](../../02-DECISIONS/0016-the-node-host.md) puts recovery
+[ADR 0005](../../02-DECISIONS/0005-the-node-host.md) puts recovery
 in a launcher that supervises the host, and that recovery is tested — 32 assertions, each
 confirmed to fail when the behaviour is removed.

@@ -53,7 +53,7 @@ is, which is a scheduling question rather than a technical one.
 ## What it would take to be sure

 Read back rather than assumed
-([ADR 0014](../../02-DECISIONS/0014-a-picture-is-read-from-what-runs.md)): list every unit on a
+([ADR 0018](../../02-DECISIONS/0018-a-picture-is-read-from-what-runs.md)): list every unit on a
 node and grep for `OnFailure=`; list every timer and check what each one calls. The finding above
 came from reading the repository, and confirming it against a running node is the difference
 between *no unit declares this* and *no unit in the source declares this*.
@@ -12,7 +12,7 @@ amended-design:

 Two accepted decisions collide, and the collision makes one resource shape untestable.

- **[ADR 0021](../../02-DECISIONS/0021-the-substrate-and-the-control-plane.md)** pins images by
+- **[ADR 0006](../../02-DECISIONS/0006-the-substrate-and-the-control-plane.md)** pins images by
  digest, and the host **refuses** an image reference that is not pinned:

  ```
@@ -66,7 +66,7 @@ for.
 ## The shape of a resolution

 **A registry inside the scenario**, on its public segment, that machines pull from. That is not a
-workaround: it is what the real mesh does — [ADR 0021](../../02-DECISIONS/0021-the-substrate-and-the-control-plane.md)
+workaround: it is what the real mesh does — [ADR 0006](../../02-DECISIONS/0006-the-substrate-and-the-control-plane.md)
 names an OCI registry as substrate, and every node after the first pulls from the mesh's own.
 Testing against a registry is testing the real path rather than a stand-in for it.

@@ -74,7 +74,7 @@ It also removes the lab's export-and-push mechanism rather than fixing it, which
 outcome: pushing image tarballs over the hypervisor was always a lab-only invention.

 **Not decided here**, because it is design rather than repair: where the registry runs, whether
-it is scenery like the router ([ADR 0009](../../02-DECISIONS/0009-the-lab.md))
+it is scenery like the router ([ADR 0016](../../02-DECISIONS/0016-the-lab.md))
 or a placed artifact, and how images get into it.

 ## Incidental, and already fixed