From 55637ecb95520c477a2790d74ab30e1b9e12a066 Mon Sep 17 00:00:00 2001
From: jochen <jschoubben@novox.be>
Date: Wed, 7 Oct 2026 23:38:34 +0200
Subject: [PATCH 1/2] ADR 0248: the decision index is generated when it is
 read, so two open decisions no longer conflict

---
 .claude/skills/hq-status/SKILL.md             |  12 +-
 00-META/checks/README.md                      |   8 +-
 00-META/checks/index.py                       | 101 ++++---
 00-META/checks/records.py                     |  11 +-
 00-META/process/00-overview.md                |   7 +-
 .../0019-how-this-repository-works.md         |   7 +
 ...erated-when-it-is-read-and-never-stored.md |  82 +++++
 02-DECISIONS/README.md                        | 283 ++----------------
 .../00-report.md                              |   2 +-
 .../01-diagnosis.md                           |  13 +
 10 files changed, 203 insertions(+), 323 deletions(-)
 create mode 100644 02-DECISIONS/0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md

diff --git a/.claude/skills/hq-status/SKILL.md b/.claude/skills/hq-status/SKILL.md
index d02e877a..af231f84 100644
--- a/.claude/skills/hq-status/SKILL.md
+++ b/.claude/skills/hq-status/SKILL.md
@@ -23,8 +23,12 @@ generated on demand and never written back to disk.
 1. Read the frontmatter block from every file above — a grep across each tree is enough, no
    need to load bodies.
 2. Render what was asked as Markdown tables. Group and sort sensibly. The **ADR index** is one
-   of these views: records ordered by number, with title, date and status, and reconstructed
-   ones marked.
+   of these views, and it is the only place the list of records is shown
+   ([ADR 0248](../../../02-DECISIONS/0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md)):
+   run `python3 00-META/checks/index.py --print` for the records grouped by topic in the reading
+   order `02-DECISIONS/README.md` writes, each with its status when not `accepted`. Asked for it by
+   number instead, render records ordered by number, with title, date and status, and reconstructed
+   ones marked. Off this checkout, the records module's `records_decisions` answers the same list.
 3. Flag anything inconsistent at the end, as flags — do not silently correct the render:
    - a `graduated` or `abandoned` effort with an empty `became:`
    - an `implemented` design with an empty `code:`
@@ -37,5 +41,7 @@ generated on demand and never written back to disk.
 
 - **Do not write a status file.** Central status files are explicitly rejected. The view is
   always generated, always ephemeral. This includes the ADR index — the hand-written one had
-  already drifted after a single addition, which is why it was removed.
+  already drifted after a single addition, which is why it was removed, and the generated one
+  written into `02-DECISIONS/README.md` made every two open decisions conflict (issue 297), which
+  is why that went too. `index.py` fails if the list is stored there again.
 - Do not infer status from prose. Trust only the frontmatter; if it is wrong, flag it.
diff --git a/00-META/checks/README.md b/00-META/checks/README.md
index e0562f7d..d10dde39 100644
--- a/00-META/checks/README.md
+++ b/00-META/checks/README.md
@@ -2,8 +2,8 @@
 
 ```
 python3 00-META/checks/records.py      structure: links, citations, supersession, topics
-python3 00-META/checks/index.py        the reading order in 02-DECISIONS/README.md is current
-python3 00-META/checks/index.py --write  regenerate it
+python3 00-META/checks/index.py        every record's topic is in the reading order, and no list of records is stored
+python3 00-META/checks/index.py --print  the records, by topic, in reading order (generated, never written)
 python3 00-META/checks/words.py        the glossary's retired words are not used, and no word is defined twice
 python3 00-META/checks/words.py --list tools   the words the catalogue's copy must list
 ```
@@ -26,8 +26,8 @@ indistinguishable from one that cannot.
 | `live-citation` | a governing document citing a **superseded** record names its replacement in the same paragraph | `01-to-be/README.md` citing ADR 0022 as live guidance |
 | `supersession` | if A says it was superseded by B, B says it supersedes A | ADR 0012 never declared that it superseded 0011 |
 | `numbering` | the number in the filename is the number in the heading | — |
-| `topics` | every record names a topic the index knows | — |
-| *(index.py)* | the written reading order matches what the records say | — |
+| `topics` | every record names a topic of the reading order in `02-DECISIONS/README.md` | — |
+| *(index.py)* | the reading order is written, every record's topic is one of it, and the README stores no list of records ([ADR 0248](../../02-DECISIONS/0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md)) | a stored list made every two open decisions conflict ([issue 297](../../04-ISSUES/297-two-open-decisions-always-conflict/00-report.md)); it failed on the README of `main` before the list was removed |
 | `status-vs-code` | a to-be document naming specific code is not still `designed` | **ten documents**, several with a *What was built* section, describing lab-proven code |
 
 ## What is deliberately not checked
diff --git a/00-META/checks/index.py b/00-META/checks/index.py
index 22a2f808..2b7bb586 100644
--- a/00-META/checks/index.py
+++ b/00-META/checks/index.py
@@ -1,16 +1,18 @@
 #!/usr/bin/env python3
-"""Generate the decision index, and check the written one still matches.
+"""The reading order of the decision records: its topics are written, its list is generated.
 
 A number identifies a record and never changes, so the folder listing is creation order rather
-than reading order. The index is what carries the path — and it is written rather than only
-generated on demand, because a reader on a forge sees the folder and not a command.
+than reading order. The reading order is the six topics `02-DECISIONS/README.md` writes down, in
+order, and each record's own `topic:`. The list of records under each topic is generated from
+that frontmatter when somebody reads it, and never stored (ADR 0248, hq issue 297): a stored
+list was a line every decision pull request added to one file, so any two open at once conflicted.
 
-The objection to a written index is that it drifts. That objection is answered by checking it
-rather than by refusing to write one, which is `how-we-build` §5: a rule states how it is
-checked.
+    python3 00-META/checks/index.py            check
+    python3 00-META/checks/index.py --print    print the list, by topic, in reading order
 
-    python3 00-META/checks/index.py --write     regenerate it
-    python3 00-META/checks/index.py             fail if it is stale
+It fails when the README's reading order is missing, when a record's topic is not one of its
+topics, and when the README stores a list of records again — the index markers, or a line of
+the generated list. The last one is what keeps the conflict from coming back.
 """
 
 import glob
@@ -20,20 +22,26 @@ import re
 import sys
 
 README = "02-DECISIONS/README.md"
-START = "<!-- index:start -->"
-END = "<!-- index:end -->"
 
-# The reading order. Topics a record may belong to, in the order somebody would learn the system.
-TOPICS = [
-    ("the mesh", "What the mesh is"),
-    ("the tiers", "Its tiers, from the bottom up"),
-    ("what runs on it", "What runs on them, and how it gets there"),
-    ("building it", "How it is built"),
-    ("checking it", "How it is checked"),
-    ("how we work", "How we work"),
+# A topic in the README's reading order, e.g.
+#   1. **What the mesh is** — `topic: the mesh`. What it is for, ...
+# The records module's `records_decisions` reads the same line, so the form is a contract.
+TOPIC_LINE = re.compile(r"^\d+\.\s+\*\*(?P<label>[^*]+)\*\*\s+—\s+`topic:\s*(?P<topic>[^`]+)`", re.M)
+
+# What a stored list looks like: the old markers, or a line of the list this script prints.
+STORED = [
+    (re.compile(r"<!--\s*index:(start|end)\s*-->"), "an index marker"),
+    (re.compile(r"^- \*\*\d{4}\*\* — \[", re.M), "a line of the generated list"),
 ]
 
 
+def reading_order(text=None):
+    """The topics, in order, as (topic, label) pairs, from the README."""
+    if text is None:
+        text = io.open(README, encoding='utf-8').read()
+    return [(m.group("topic").strip(), m.group("label").strip()) for m in TOPIC_LINE.finditer(text)]
+
+
 def field(text, name):
     m = re.search(r'^%s:\s*(.+)$' % name, text, re.M)
     return m.group(1).strip() if m else None
@@ -54,10 +62,9 @@ def records():
     return out
 
 
-def render(rs):
-    known = {t for t, _ in TOPICS}
-    lines = [START, ""]
-    for topic, label in TOPICS:
+def render(topics, rs):
+    lines = []
+    for topic, label in topics:
         rows = [r for r in rs if r["topic"] == topic]
         if not rows:
             continue
@@ -67,40 +74,40 @@ def render(rs):
             mark = "" if r["status"] == "accepted" else "  *(%s)*" % r["status"]
             lines.append("- **%s** — [%s](%s)%s" % (r["number"], r["title"], r["file"], mark))
         lines.append("")
-    stray = [r for r in rs if r["topic"] not in known]
-    if stray:
-        lines.append("### Unfiled")
-        lines.append("")
-        for r in stray:
-            lines.append("- **%s** — [%s](%s) — `topic:` is %r, which is not one of %s" % (
-                r["number"], r["title"], r["file"], r["topic"], ", ".join(sorted(known))))
-        lines.append("")
-    lines.append(END)
     return "\n".join(lines)
 
 
 def main():
     text = io.open(README, encoding='utf-8').read()
-    wanted = render(records())
+    topics = reading_order(text)
+    rs = records()
 
-    if START not in text or END not in text:
-        print("index: %s has no index markers (%s / %s)" % (README, START, END))
-        return 1
-
-    current = text[text.index(START):text.index(END) + len(END)]
-    if "--write" in sys.argv:
-        if current == wanted:
-            print("index: already current")
-            return 0
-        io.open(README, 'w', encoding='utf-8').write(text.replace(current, wanted, 1))
-        print("index: written")
+    if "--print" in sys.argv:
+        print(render(topics, rs))
         return 0
 
-    if current != wanted:
-        print("index: %s is stale. Regenerate it:\n"
-              "    python3 00-META/checks/index.py --write" % README)
+    problems = []
+    if not topics:
+        problems.append("%s writes no reading order: no line of the form "
+                        "'1. **Label** — `topic: name`. ...'" % README)
+    names = [t for t, _ in topics]
+    if len(set(names)) != len(names):
+        problems.append("%s names a topic twice in its reading order" % README)
+    for pattern, what in STORED:
+        if pattern.search(text):
+            problems.append("%s stores the list of records (%s). The list is generated when read "
+                            "(ADR 0248): `python3 00-META/checks/index.py --print`" % (README, what))
+    known = set(names)
+    for r in rs if known else []:  # with no reading order, every record would be named; one line says why
+        if r["topic"] not in known:
+            problems.append("%s: topic %r is not one of the reading order's: %s"
+                            % (r["file"], r["topic"], ", ".join(names)))
+
+    for p in problems:
+        print("index: " + p)
+    if problems:
         return 1
-    print("index: current")
+    print("index: %d topics, %d records, no stored list" % (len(topics), len(rs)))
     return 0
 
 
diff --git a/00-META/checks/records.py b/00-META/checks/records.py
index 9c235eb8..0c1ea1d2 100644
--- a/00-META/checks/records.py
+++ b/00-META/checks/records.py
@@ -265,14 +265,15 @@ def check_supersession_symmetry(failures, records):
 
 
 def check_topics(failures, records):
-    """Every record names a topic the index knows.
+    """Every record names a topic of the reading order.
 
     The topic is what puts a record in the reading order, so a record without one — or with one
-    nobody defined — disappears from the index rather than appearing in the wrong place. That is
-    the quiet failure, so it is the one checked.
+    nobody defined — disappears from the generated list rather than appearing in the wrong place.
+    That is the quiet failure, so it is the one checked. The topics are the ones
+    `02-DECISIONS/README.md` writes down, read the way `index.py` reads them, so there is one list.
     """
-    known = {"the mesh", "the tiers", "what runs on it", "building it", "checking it",
-             "how we work"}
+    from index import reading_order
+    known = {topic for topic, _ in reading_order()}
     for number, record in sorted(records.items()):
         topic = record["front"].get("topic")
         if not topic:
diff --git a/00-META/process/00-overview.md b/00-META/process/00-overview.md
index 50707c6f..63a5042c 100644
--- a/00-META/process/00-overview.md
+++ b/00-META/process/00-overview.md
@@ -62,8 +62,8 @@ The flow above is a rule, and a rule states how it is checked:
 [`00-META/checks/cycle.py`](../checks/cycle.py) refuses a to-be design that names no
 decision, an `in-progress`/`implemented` design that names no owning code, an issue marked
 `located`/`fixed` with no owner or `fixed`/`resolved` with no fix, and a `graduated`
-research overview that does not say what it became. Run it with `records.py` and `index.py`
-before any HQ merge. What the checks cannot see — that code work actually started from a
+research overview that does not say what it became. Run it with `records.py`, `index.py` and
+`words.py` before any HQ merge (`sh merge-check.sh` runs all four). What the checks cannot see — that code work actually started from a
 handoff — is held by playbooks [04](04-build-handoff.md) and [07](07-feature-branches.md):
 a feature branch exists because a design or an issue sent it.
 
@@ -74,4 +74,5 @@ YAML frontmatter (schemas in the section READMEs and playbooks). There are **no
 files** and no decision ledger. **Every decision is a record in
 [`02-DECISIONS`](../../02-DECISIONS/)** — if it is worth recording it is worth a record, and if
 it is not worth a record it is not recorded. Cross-cutting views, the decision index included,
-are generated on demand by the `hq-status` skill and never written to disk.
+are generated on demand by the `hq-status` skill and never written to disk
+([ADR 0248](../../02-DECISIONS/0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md)).
diff --git a/02-DECISIONS/0019-how-this-repository-works.md b/02-DECISIONS/0019-how-this-repository-works.md
index 56cf26ce..d10fb9c8 100644
--- a/02-DECISIONS/0019-how-this-repository-works.md
+++ b/02-DECISIONS/0019-how-this-repository-works.md
@@ -8,6 +8,13 @@ reconstructed: false
 
 # 19. How this repository works
 
+> **Superseded in part — 2026-10-07, by [ADR 0248](0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md).**
+> The paragraph "the index is written, not only generated on demand" no longer holds: a stored list was
+> a line every decision pull request added to one file, so two open at once always conflicted (issue
+> 297). The list of records is generated when it is read, and `02-DECISIONS/README.md` writes only the
+> topics in their reading order. Everything else here stands, including the reading order and the check
+> that every record has a topic one of the README's.
+
 *Consolidated 2026-08-28 from ten records that were one decision seen from ten angles. The
 reasoning is kept; the fragmentation is not.*
 
diff --git a/02-DECISIONS/0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md b/02-DECISIONS/0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md
new file mode 100644
index 00000000..47d70b56
--- /dev/null
+++ b/02-DECISIONS/0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md
@@ -0,0 +1,82 @@
+---
+topic: how we work
+status: accepted
+date: 2026-10-07
+deciders: jochen
+reconstructed: false
+supersedes-in-part:
+  - 0019-how-this-repository-works.md
+---
+
+# 248. The decision index is generated when it is read, and never stored
+
+## Context
+
+[ADR 0019](0019-how-this-repository-works.md) says two things about the decision index. Every
+cross-cutting view, "a decision index" by name, "is generated from frontmatter when asked for, never
+written to disk". And this one index "is written, not only generated on demand", because "a reader
+looking at the folder on a forge sees the folder, not a command", with `index.py` checking that the
+written copy is current.
+
+The written copy was a list in `02-DECISIONS/README.md`, grouped by `topic:` and sorted by number. Every
+pull request that adds a record adds a line to it, at or near the end of its topic's group, so two open
+decisions on one topic edit the same lines. On 2026-10-07 four decision pull requests were open at
+once, and each merge made the next one unmergeable: three rebases of one, two of another and four of a
+third in about two hours, each followed by a full check on the build seat. Replayed with
+`git merge-tree`, three of those forced rebases conflicted in the index alone
+([issue 297](../04-ISSUES/297-two-open-decisions-always-conflict/00-report.md)). The conflicting lines
+were copies of `topic:` and `status:`, which each record already states. The conflict was never between
+two decisions.
+
+## Considered Options
+
+From the [diagnosis](../04-ISSUES/297-two-open-decisions-always-conflict/01-diagnosis.md):
+
+1. **Generate the list when it is read, and stop storing it.** Chosen.
+2. **One index file per decision.** Nothing conflicts, but it is a third copy of `topic:` to check
+   against the record, and a folder of one-line files reads no better on a forge than the folder of
+   records. Rejected.
+3. **Write the index after each merge on `main`.** `main` takes a pull request and a person's approval
+   for every merge, so each decision would cost two approvals, and the index on `main` would be stale
+   in between, failing every other pull request's check or no longer checked. Rejected.
+4. **A union merge for the README.** The forge's merge may not read the attribute, and where it does,
+   a union keeps both lines in the order the merge sees them, not in number order: `main` would fail
+   `index.py` after the merge rather than a branch before it. Rejected.
+
+## Decision
+
+1. **`02-DECISIONS/README.md` writes the reading order and nothing generated.** Its six topics, in
+   order, each with its `topic:` value and a sentence. That is the part a person wrote and decides.
+2. **The list of records under each topic is generated when it is read**, from each record's `topic:`,
+   `status:` and heading: by `python3 00-META/checks/index.py --print`, by the `hq-status` skill, and by
+   the records module's `records_decisions` for a reader on the mesh. The README is the one place the
+   topics are written; all three read them from it.
+3. **This replaces ADR 0019's paragraph "the index is written, not only generated on demand"**, and
+   its reason, a forge reader seeing the folder and not a command. The rest of ADR 0019 stands,
+   including its reading order and its rule that a record with no topic, or one nobody defined, fails a
+   check.
+
+## Consequences
+
+- No decision pull request edits a file every other decision pull request edits. Two branches that each
+  add a record on one topic merge in either order without a rebase.
+- A reader on the forge no longer sees every record on one page. They see the six topics and the
+  folder, and each record names its topic. The full list is one command, one skill or one tool call
+  away.
+- ADR 0019 no longer disagrees with itself: the decision index is the kind of view it says is never
+  written to disk.
+
+**How it is checked.** `00-META/checks/index.py`, run by `merge-check.sh` as part of `mesh/repo-check`,
+fails when the README stores the list again (the old index markers, or a line in the form the generated
+list prints), when the README writes no reading order, and when a record's `topic:` is not one of the
+README's topics. `records.py` reads its topics from the same lines. The replay of issue 297, two
+branches off one `main` each adding a record on the same topic, merges without a conflict and passes
+`sh merge-check.sh` on both and on the merge.
+
+## References
+
+- [Issue 297](../04-ISSUES/297-two-open-decisions-always-conflict/00-report.md), its report and
+  diagnosis.
+- [ADR 0019](0019-how-this-repository-works.md), the paragraph this replaces.
+- [ADR 0025](0025-the-design-record-is-read-not-copied.md), the record read where it is written, which
+  the records module serves.
diff --git a/02-DECISIONS/README.md b/02-DECISIONS/README.md
index 6cab312b..9535486c 100644
--- a/02-DECISIONS/README.md
+++ b/02-DECISIONS/README.md
@@ -122,273 +122,36 @@ options section states what the alternatives were and why the chosen one won on
 available — not a discussion that did not happen. Where a date is not establishable it says so
 rather than guessing.
 
-## Index
+## Reading order
 
 **A number identifies a record and never changes.** Records are referenced from outside this
 repository — code comments, commit messages — so a number that moves invalidates them silently.
 Renumbering once cost 96 references across two code repositories, and that is why the numbers
 are now fixed.
 
-So the folder is in creation order, and **the reading order lives here.** It is generated from
-each record's `topic:` and written, because a reader looking at the folder on a forge sees the
-folder rather than a command. The objection to a written index is that it drifts — which is
-answered by checking it rather than by refusing to write one:
+So the folder is in creation order, and **the reading order lives here**: six topics, in the
+order somebody would learn the system. Each record names its own in `topic:`.
+
+1. **What the mesh is** — `topic: the mesh`. What it is for, and the parts it is made of.
+2. **Its tiers, from the bottom up** — `topic: the tiers`. The foundation, the node and the controller, and
+   what each one provides to the one above.
+3. **What runs on them, and how it gets there** — `topic: what runs on it`. Modules, seats and
+   provisions, and how they reach a node.
+4. **How it is built** — `topic: building it`. The code, its repositories, and what is made from
+   it for a node.
+5. **How it is checked** — `topic: checking it`. What judges a change, and what proves a decision holds.
+6. **How we work** — `topic: how we work`. This repository, its playbooks, and how decisions and
+   designs are made.
+
+**The list of records under each topic is generated when it is read, and never stored here**
+([ADR 0248](0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md)). A stored list
+was one more line in this file for every decision, so two decisions open at once always conflicted
+([issue 297](../04-ISSUES/297-two-open-decisions-always-conflict/00-report.md)). Read it with:
 
 ```
-python3 00-META/checks/index.py --write    regenerate
-python3 00-META/checks/index.py            fail if stale
+python3 00-META/checks/index.py --print    the records, by topic, in reading order
 ```
 
-<!-- index:start -->
-
-### What the mesh is
-
-- **0001** — [The mesh brokers capabilities; nodes host; agents think](0001-mesh-brokers-nodes-host-agents-think.md)
-- **0002** — [Nodes communicate over a message broker, not over HTTP](0002-nodes-communicate-over-a-broker.md)
-- **0003** — [An agent is a persistent employee, not an instance of a pool](0003-agents-are-persistent-employees.md)
-- **0077** — [The parts are named controller, foundation, node — not control plane, substrate, master](0077-the-controller-and-the-foundation.md)
-- **0083** — [One push leaves the mesh consistent](0083-one-push-leaves-the-mesh-consistent.md)
-- **0088** — [The foundation filters before anything listens](0088-the-foundation-filters-before-anything-listens.md)
-- **0090** — [A failure that repeats is said to be stuck](0090-a-failure-that-repeats-is-said-to-be-stuck.md)
-- **0100** — [A node in use is adopted before it is converged](0100-a-node-in-use-is-adopted-before-it-is-converged.md)
-- **0101** — [A machine's own resolver does not make it in use](0101-a-machines-own-resolver-does-not-make-it-in-use.md)
-- **0102** — [The mesh writes into a shared file, never over it](0102-the-mesh-writes-into-a-shared-file-never-over-it.md)
-- **0103** — [What an adopted node holds, and what its guard refuses](0103-what-an-adopted-node-holds-and-what-its-guard-refuses.md)
-- **0104** — [A provision may be answered by an adapter to the predecessor](0104-a-provision-may-be-answered-by-an-adapter-to-the-predecessor.md)
-- **0105** — [The mesh adopts the predecessor's tunnel in place](0105-the-mesh-adopts-the-predecessors-tunnel-in-place.md)
-- **0106** — [The bus is NATS](0106-the-bus-is-nats.md)
-- **0116** — [The bus is built in five steps, and the protocol moves with it](0116-the-bus-is-built-in-five-steps.md)
-- **0119** — [A taken tunnel's predecessor is retired once the take is proven](0119-a-taken-tunnels-predecessor-is-retired.md)
-- **0125** — [The bus is the only broker](0125-the-bus-is-the-only-broker.md)  *(superseded)*
-- **0127** — [AMQP is a provision, not the bus](0127-amqp-is-a-provision-not-the-bus.md)  *(superseded)*
-- **0128** — [The mesh bus is required, not ambient](0128-the-mesh-bus-is-required-not-ambient.md)
-- **0129** — [A seat carries the protocol of its role](0129-a-seat-carries-the-protocol-of-its-role.md)
-- **0130** — [The predecessor is ending, and its broker goes with it](0130-the-predecessor-is-ending-and-its-broker-goes-with-it.md)
-- **0131** — [Everything on the mesh speaks to the broker seat, and AMQP is not a provision](0131-everything-on-the-mesh-speaks-to-the-broker-seat.md)
-- **0132** — [A seat carries the tools its holder must serve](0132-a-seat-carries-the-tools-its-holder-must-serve.md)
-- **0134** — [The mesh says what it applied](0134-the-mesh-says-what-it-applied.md)
-- **0142** — [The mesh delivers its own components as binaries, not as container images](0142-the-mesh-delivers-its-own-components-as-binaries.md)
-- **0154** — [The mesh's own verbs are the mesh-controller seat's tools, and which verbs those are](0154-the-meshs-own-verbs-are-the-controller-seats-tools.md)
-- **0156** — [An artifact is what a build produces, the artifact store serves every kind, and its seat is named for its scope](0156-an-artifact-is-what-a-build-produces-and-the-store-is-named-for-its-scope.md)
-- **0157** — [A build says what it does on the bus, as it happens](0157-a-build-says-what-it-does-on-the-bus-as-it-happens.md)
-- **0158** — [A provider with one credential shares it with every consumer, and the vault remakes it for all of them at once](0158-a-provider-with-one-credential-shares-it-with-every-consumer.md)
-- **0159** — [A tool call names the machine it is for, every answer says which machine answered, and a holder's runtime serves its seat's verbs](0159-a-tool-call-names-the-machine-and-a-holder-serves-its-seats-verbs.md)
-- **0160** — [The mesh issues an assignment's subjects, and a runtime serves what it is issued](0160-the-mesh-issues-an-assignments-subjects-and-a-runtime-serves-what-it-is-issued.md)
-- **0161** — [What deserves a seat: a role of a module is a seat, a singular fact about machines is a placement with a capacity of one, and a holder's software is the machine's](0161-what-deserves-a-seat.md)
-- **0162** — [A merge produces a tiered plan the mesh keeps, and a module's dependencies are one relation in the catalogue](0162-a-merge-produces-a-tiered-plan-the-mesh-keeps.md)
-- **0163** — [Taking a module over is a comparison: what it compares, what it refuses, and what it carries](0163-taking-a-module-over-is-a-comparison.md)
-- **0167** — [A membership carries what its module receives, and who the mesh is](0167-a-membership-carries-what-its-module-receives-and-who-the-mesh-is.md)
-- **0168** — [A converged machine is filtered by the mesh alone, and the host says what else refuses](0168-a-converged-machine-is-filtered-by-the-mesh-alone.md)
-- **0169** — [A machine joins through the tunnel, and the bus is never public](0169-a-machine-joins-through-the-tunnel-and-the-bus-is-never-public.md)
-- **0170** — [The firewall seat serves its verbs, and a foreign rule set is removed through one of them](0170-the-firewall-seat-serves-its-verbs.md)
-- **0172** — [The lab is a module, and runs a bed when the mesh asks](0172-the-lab-is-a-module-and-runs-a-bed-when-the-mesh-asks.md)
-- **0179** — [The intrusion seat serves its verbs, a container may log to the journal, and every door declares its jail](0179-the-intrusion-seat-serves-its-verbs-and-every-door-declares-its-jail.md)
-- **0180** — [The found front end is uninstalled once a machine is converged](0180-the-found-front-end-is-uninstalled-once-a-machine-is-converged.md)
-- **0184** — [A service the mesh asked to run is still running a moment later](0184-a-service-the-mesh-asked-to-run-is-still-running-a-moment-later.md)
-- **0185** — [A control plane behind its seat's row serves what it can](0185-a-control-plane-behind-its-seats-row-serves-what-it-can.md)
-- **0186** — [A ban list never holds a neighbour, and the mesh's own bans are its own wherever they hang](0186-a-ban-list-never-holds-a-neighbour.md)
-- **0187** — [A dead tracker is not the machine's failure](0187-a-dead-tracker-is-not-the-machines-failure.md)
-- **0189** — [The store keeps what the records name, and a maintenance step holds its writers still](0189-the-store-keeps-what-the-records-name.md)
-- **0190** — [A seat's work is shared by its holders, and building is the first such role](0190-a-seats-work-is-shared-by-its-holders-and-building-is-the-first-such-role.md)
-- **0202** — [A provider declares what it derives for each consumer, and the mesh tells both ends](0202-a-provider-declares-what-it-derives-for-each-consumer.md)
-- **0207** — [A module depends on the node seats that apply its resources](0207-a-module-depends-on-the-node-seats-that-apply-its-resources.md)
-- **0210** — [A tool's configuration is its seat holder's, and every other module extends it through the seat](0210-a-tools-configuration-is-its-seat-holders-and-every-other-module-extends-it-through-the-seat.md)
-- **0212** — [A seat says what it receives, and the machine's hotkeys are a seat](0212-a-seat-says-what-it-receives-and-the-machines-hotkeys-are-a-seat.md)
-- **0218** — [A plan sends grants before code, rolls a module out one machine first, and a newer merge takes over an older plan](0218-a-plan-sends-grants-before-code-rolls-out-one-machine-first-and-a-newer-merge-takes-over-an-older-plan.md)
-- **0219** — [The build queue is controlled through the controller and the build seat](0219-the-build-queue-is-controlled-through-the-controller-and-the-build-seat.md)
-- **0221** — [A push sends no build a policy or a plan holds back, except to the machine it names](0221-a-push-sends-no-build-a-policy-or-a-plan-holds-back-except-to-the-machine-it-names.md)
-- **0222** — [A module is told where a mesh seat's holder is reached, and the controller writes no file a seat's holder owns](0222-a-module-is-told-where-a-mesh-seats-holder-is-reached-and-the-controller-writes-no-file-a-seats-holder-owns.md)
-- **0224** — [A provider that keeps failing a consumer is a problem the controller reports](0224-a-provider-that-keeps-failing-a-consumer-is-a-problem-the-controller-reports.md)
-- **0227** — [The core holds nine rules, each checked, and is built to them in six phases](0227-the-core-holds-nine-rules-each-checked-and-is-built-to-them-in-six-phases.md)
-- **0229** — [The core's order is a lease the store remembers, and an epoch a machine is sent once it reads one](0229-the-cores-order-is-a-lease-the-store-remembers-and-an-epoch-a-machine-is-sent-once-it-reads-one.md)
-- **0230** — [A consumer the mesh stops asking for is retired, and deleted only by a person](0230-a-consumer-the-mesh-stops-asking-for-is-retired-and-deleted-only-by-a-person.md)
-- **0231** — [A healer acts on what observation raised, and only observation says it worked](0231-a-healer-acts-on-what-observation-raised-and-only-observation-says-it-worked.md)
-- **0234** — [The mesh holds a conversation with its operator, over channels that are seats, and an answer that performs an action is authorised by the controller](0234-the-mesh-holds-a-conversation-with-its-operator.md)
-- **0236** — [A build is judged on its first machine and put back by something other than itself, and so it rolls out unattended](0236-a-build-is-judged-on-its-first-machine-and-put-back-by-something-other-than-itself-and-so-it-rolls-out-unattended.md)
-- **0237** — [A change is judged against the mesh that runs, before it merges, on the build seat](0237-a-change-is-judged-against-the-mesh-that-runs-before-it-merges-on-the-build-seat.md)
-- **0238** — [A commit is the build at hand: one commit, one change plan, checked off the trunk and published only on it](0238-a-commit-is-the-build-at-hand-one-commit-one-change-plan-checked-off-the-trunk-and-published-only-on-it.md)
-- **0239** — [A delivery is owned by the mesh-delivery module and runs from commit to delivered](0239-a-delivery-is-owned-by-the-mesh-delivery-module-and-runs-from-commit-to-delivered.md)
-- **0246** — [A seat's new verb is promised before it is required](0246-a-seats-new-verb-is-promised-before-it-is-required.md)
-
-### Its tiers, from the bottom up
-
-- **0004** — [A node, and how it joins](0004-a-node-and-how-it-joins.md)
-- **0005** — [The node host](0005-the-node-host.md)
-- **0006** — [The substrate and the control plane](0006-the-substrate-and-the-control-plane.md)
-- **0007** — [Connectivity](0007-connectivity.md)
-- **0008** — [A context owns its store, exclusively](0008-a-context-owns-its-store.md)
-- **0028** — [The substrate supplies the control plane and nothing else](0028-the-substrate-supplies-the-control-plane-and-nothing-else.md)
-- **0029** — [A network is a shape, because an action cannot be undone](0029-a-network-is-a-shape-because-an-action-cannot-be-undone.md)
-- **0030** — [Data outlives the mesh that declared it](0030-data-outlives-the-mesh-that-declared-it.md)
-- **0031** — [The control plane authenticates nobody, so identity is a module](0031-the-control-plane-authenticates-nobody.md)
-- **0033** — [The substrate is a store and a broker](0033-the-substrate-is-a-store-and-a-broker.md)
-- **0036** — [Bootstrap ends at a usable mesh, and the first credential comes from a person](0036-bootstrap-ends-at-a-usable-mesh.md)
-- **0066** — [Public routing is name-agnostic, its names are resolved inside the mesh, and an internal authority can certify them](0066-public-routing-is-name-agnostic.md)
-- **0067** — [Genesis is a pivot: a temporary control plane installs the registry that makes it permanent](0067-genesis-is-a-pivot.md)
-- **0070** — [The catalogue owns the module graph, and genesis builds rather than carries](0070-the-catalogue-owns-the-module-graph.md)
-- **0071** — [Genesis clones from a mesh, and checks what it got](0071-where-genesis-gets-its-source.md)
-- **0072** — [Two graphs, and a build chain that orders itself](0072-two-graphs-and-the-build-chain.md)
-- **0073** — [The installer carries a builder, and the registry stays where it is](0073-the-installer-carries-a-builder.md)
-- **0074** — [The mesh defines a module protocol; an SDK is an implementation of it](0074-the-wire-is-specified-not-the-types.md)
-- **0075** — [An artifact store is a provision; a package registry is a different one](0075-two-stores-and-which-provides-what.md)
-- **0078** — [The store and the broker are ordinary modules](0078-the-store-and-broker-are-modules.md)
-- **0079** — [The foundation seats are named after their servers](0079-the-foundation-seats-are-named-after-their-servers.md)
-- **0092** — [An operator delivers a pair credential, and the mesh never replaces it](0092-an-operator-delivers-a-pair-credential.md)
-- **0094** — [A module may hold several secrets from one provider, each a pair of its own](0094-a-module-may-hold-several-secrets-from-one-provider.md)
-- **0095** — [The control plane is the way to ask a module](0095-the-control-plane-is-the-way-to-ask-a-module.md)
-- **0098** — [A fact a provider makes at first start is fetched from it, not carried in its manifest](0098-a-fact-a-provider-makes-at-first-start-is-fetched-from-it.md)
-- **0108** — [A route carries the policy applied to a request, and names a secret rather than holding one](0108-a-route-carries-the-policy-applied-to-a-request.md)
-- **0109** — [A package registry seat is one per ecosystem, not one for all of them](0109-a-package-registry-seat-is-one-per-ecosystem.md)
-- **0126** — [A module declares its own seats; the mesh reserves its own](0126-a-module-declares-its-own-seats.md)
-- **0148** — [The mesh's names are resolved, not copied into every container](0148-the-meshs-names-are-resolved-not-copied-into-containers.md)
-- **0151** — [A route's internal name is composed under the node that serves it](0151-a-routes-internal-name-is-composed-under-the-node-that-serves-it.md)
-- **0191** — [The mesh's resolver holds only the mesh's own names; a public name resolves publicly](0191-the-meshs-resolver-holds-only-the-meshs-own-names.md)
-- **0194** — [The mesh has one resolver, and every node asks it for the mesh's names](0194-the-mesh-has-one-resolver-and-every-node-asks-it-for-the-meshs-names.md)
-- **0196** — [A node asks the mesh's resolver first, and a public one only when it is silent](0196-a-node-asks-the-meshs-resolver-first-and-a-public-one-only-when-it-is-silent.md)
-- **0199** — [A module that answers names declares its zone, and a node's hosts file is one module's](0199-a-module-that-answers-names-declares-its-zone-and-a-nodes-hosts-file-is-one-modules.md)
-- **0223** — [The mesh has two resolvers, and a machine lists only them](0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md)
-- **0226** — [The private network is assigned by its own name, and the proxy names its public issuer](0226-the-private-network-is-assigned-by-its-own-name-and-the-proxy-names-its-public-issuer.md)
-- **0247** — [A machine with a VPN client routes names by domain, through a resolver of its own](0247-a-machine-with-a-vpn-client-routes-names-by-domain-through-a-resolver-of-its-own.md)
-
-### What runs on them, and how it gets there
-
-- **0009** — [Modules and the graph](0009-modules-and-the-graph.md)
-- **0010** — [Delivery](0010-delivery.md)
-- **0024** — [Model access is a provision, and a licence is a thing with a name](0024-model-access-is-a-provision.md)
-- **0026** — [The mesh has a session of its own, and it is the node session's mechanism](0026-the-mesh-has-a-session-of-its-own.md)
-- **0027** — [A provision names what the consumer is coupled to, not the role it plays](0027-a-provision-names-what-the-consumer-is-coupled-to.md)
-- **0035** — [One implementation, several surfaces, and what that costs](0035-one-implementation-several-surfaces.md)
-- **0038** — [The mesh assigns the port, and a module does not care](0038-the-mesh-assigns-the-port.md)
-- **0040** — [What a module is](0040-what-a-module-is.md)
-- **0041** — [Events are a relationship, the lighter sibling of provisioning](0041-events-are-a-relationship.md)
-- **0042** — [The shape of an event on the wire](0042-the-shape-of-an-event-on-the-wire.md)
-- **0043** — [A module's broker account is scoped by what it emits and consumes](0043-a-module-broker-account-is-scoped-by-emits-and-consumes.md)
-- **0044** — [A public name is provisioned, not registered by hand](0044-a-public-name-is-provisioned-like-any-capability.md)
-- **0045** — [A machine's firewall is the sum of what its modules listen on](0045-a-machine-firewall-is-the-sum-of-what-it-listens-on.md)
-- **0046** — [A module's configuration is its assignment's, not its manifest's](0046-a-module-configuration-is-its-assignments-not-its-manifest.md)
-- **0047** — [A module runs its code as its own process, with its own account](0047-a-module-runs-its-code-as-its-own-process-with-its-own-account.md)
-- **0048** — [A provider creates the credential the mesh minted, and seals nothing](0048-a-provider-creates-the-credential-the-mesh-minted.md)
-- **0049** — [A consumer's identity is bounded by the tightest backend that must accept it](0049-a-consumers-identity-fits-the-tightest-backend.md)
-- **0050** — [Model access is vendor-agnostic, and a vendor is an adapter](0050-model-access-is-vendor-agnostic.md)
-- **0051** — [Shared data is the operator's, and a module is granted access to it](0051-shared-data-is-the-operators.md)
-- **0052** — [An init step is a container run once to completion, gating what follows](0052-a-step-that-runs-once-before-a-container.md)
-- **0053** — [A scheduled step is a container run on a recurring schedule](0053-a-step-that-runs-on-a-schedule.md)
-- **0054** — [Model usage is a vendor-neutral record, produced by the adapter, at two grains](0054-model-usage-is-recorded-at-two-grains.md)
-- **0055** — [Model access is answered by a licence, or by a node that hosts the model](0055-model-access-is-answered-by-a-licence-or-a-node.md)
-- **0084** — [Which provider serves a consumer, when the mesh runs more than one](0084-which-provider-serves-a-consumer.md)
-- **0085** — [A secret is a provision, and the vault is the module that provides it](0085-a-secret-is-a-provision.md)
-- **0087** — [A seeded file is created once, and what grows in it is not the mesh's](0087-a-seeded-file-is-created-once.md)
-- **0091** — [A mount is declared, and there are three things it can be](0091-a-mount-is-declared-three-ways.md)
-- **0099** — [A step that runs once names what it reads, and runs again when it changed](0099-a-step-that-runs-once-names-what-it-reads.md)
-- **0110** — [A seat is held by one assignment, from a closed set, and it may deliver a provision](0110-a-seat-is-a-module-assignment-from-a-closed-set.md)
-- **0112** — [A module definition names no node, no mesh and no path: everything it needs is a requirement the mesh resolves](0112-a-module-definition-names-no-node-mesh-or-path.md)
-- **0113** — [The vault makes every shared secret, a provider makes resources and data, and the mesh carries both](0113-the-vault-makes-every-secret.md)
-- **0114** — [A credential two parties hold rotates over two credentials; one a single party holds rotates in place, staged; and retiring a credential never removes what it reached](0114-a-shared-credential-rotates-over-two-credentials.md)
-- **0115** — [One assignment of a module per node: the module's name is the assignment's identity](0115-one-assignment-of-a-module-per-node.md)
-- **0117** — [A machine's uplink is a seat: the mesh configures the manager, never the link](0117-a-machines-uplink-is-a-seat.md)
-- **0118** — [Undeclaring removes what the mesh made, and gives a unit back the state it was found in](0118-undeclaring-gives-a-unit-back-the-state-it-was-found-in.md)
-- **0120** — [A roster fact carries its format as a template: the mesh owns the data, the module owns the format](0120-a-roster-fact-carries-its-format-as-a-template.md)
-- **0121** — [A system seat is named for its scope, and a module may define its own](0121-a-system-seat-is-named-for-its-scope-and-modules-define-their-own.md)
-- **0122** — [A seat is data the controller owns, and a rename is a database update](0122-a-seat-is-data-a-rename-is-a-database-update.md)
-- **0133** — [A module owns its migrations, and the mesh owns when they run](0133-a-module-owns-its-migrations-and-the-mesh-owns-when-they-run.md)  *(superseded)*
-- **0135** — [A module version prepares its state before it runs](0135-a-module-version-prepares-its-state-before-it-runs.md)
-- **0136** — [A step gates its module, not the machine](0136-a-step-gates-its-module-not-the-machine.md)
-- **0137** — [A machine says which networks it routes](0137-a-machine-says-which-networks-it-routes.md)  *(superseded)*
-- **0138** — [An assignment binds an endpoint and says how far it reaches](0138-an-assignment-binds-an-endpoint-and-says-how-far-it-reaches.md)
-- **0139** — [A network is forwarded because a module declared it](0139-a-network-is-forwarded-because-a-module-declared-it.md)  *(superseded)*
-- **0140** — [The filter constrains what arrives from outside, and says nothing about a machine's own guests](0140-the-filter-constrains-what-arrives-from-outside.md)
-- **0141** — [The host delivers its own successor, and versions live side by side](0141-the-host-delivers-its-own-successor.md)
-- **0143** — [A consumer verifies the grant it is given](0143-a-consumer-verifies-the-grant-it-is-given.md)  *(superseded)*
-- **0144** — [Anything on a machine may call anything on it, and that is the whole of "local"](0144-anything-on-a-machine-may-call-anything-on-it.md)
-- **0145** — [A module checks what the mesh claims is reachable, and it checks itself](0145-a-module-checks-what-the-mesh-claims-is-reachable.md)  *(superseded)*
-- **0146** — [Connectivity is checked by name, per hosting form, with a valid certificate](0146-connectivity-is-checked-by-name-per-hosting-form.md)
-- **0147** — [A module anchors the mesh's authority on a machine, and takes it away again](0147-a-module-anchors-the-meshs-authority.md)
-- **0150** — [A module's own code runs as supervised processes under the module's one account](0150-a-modules-own-code-runs-as-supervised-processes-under-one-account.md)
-- **0152** — [The operator's surface is a module the mesh assigns: the console](0152-the-operators-surface-is-a-module-the-console.md)
-- **0155** — [A definition names no installation: how that is checked, and the three ways a value that did gets out](0155-a-definition-names-no-installation-and-how-that-is-checked.md)
-- **0164** — [A setting is declared with its default, its meaning and what changing it costs](0164-a-setting-is-declared-with-its-default-its-meaning-and-what-changing-it-costs.md)  *(proposed)*
-- **0165** — [`container-runtime` is what a machine can run; that a runtime is running is its holder's health](0165-container-runtime-is-what-a-machine-can-run-and-a-running-runtime-is-its-holders-health.md)  *(proposed)*
-- **0166** — [The container runtime is a node seat, and the host creates containers through its holder](0166-the-container-runtime-is-a-node-seat-and-the-host-creates-containers-through-its-holder.md)  *(proposed)*
-- **0173** — [The operator's machine is the mesh's, and a module is whatever it declares](0173-the-operators-machine-is-the-meshs-and-a-module-is-what-it-declares.md)
-- **0175** — [One tool runtime per node serves every module's tools, on the host side](0175-one-tool-runtime-per-node-serves-every-modules-tools-on-the-host-side.md)
-- **0176** — [The login shell is a node seat held by one shell module, and `execute` is its contract](0176-the-login-shell-is-a-node-seat-and-execute-is-its-contract.md)
-- **0177** — [A unit may be user-scoped, and the service manager is a node seat whose holder answers for the units](0177-a-unit-may-be-user-scoped-and-the-service-manager-is-a-node-seat.md)
-- **0181** — [The operator account is a node fact, and a home is a placement root](0181-the-operator-account-is-a-node-fact-and-a-home-is-a-placement-root.md)
-- **0182** — [Inside a home, the mesh owns the directory and the files it places, writes into the tool's own files, and holds everything else as found](0182-inside-a-home-the-mesh-owns-what-it-places-and-holds-the-rest-as-found.md)
-- **0183** — [The Anthropic licence manager is a module holding a seat; it hands each node's agent its token over the bus, sealed; the controller and the host have no part](0183-the-anthropic-licence-manager-is-a-module-and-hands-tokens-to-the-agent-over-the-bus.md)
-- **0188** — [A module's own code is bundles in any language, and a tools bundle speaks MCP to the runtime](0188-a-modules-own-code-is-bundles-in-any-language-and-a-tools-bundle-speaks-mcp-to-the-runtime.md)
-- **0192** — [A tools bundle declares what it is given, and the runtime hands it to that bundle alone](0192-a-tools-bundle-declares-what-it-is-given-and-the-runtime-hands-it-to-that-bundle-alone.md)
-- **0193** — [Every bundle the runtime serves is launched, and the runtime knows no language](0193-every-bundle-the-runtime-serves-is-launched-and-the-runtime-knows-no-language.md)
-- **0195** — [The mesh's tools are found by address, not announced whole](0195-the-meshs-tools-are-found-by-address-not-announced-whole.md)
-- **0197** — [Every tool announces itself on the bus, in the NATS services protocol](0197-every-tool-announces-itself-on-the-bus-in-the-nats-services-protocol.md)
-- **0198** — [A module's long-running code is launched by the node's runtime, and reaches the bus through it](0198-a-modules-long-running-code-is-launched-by-the-node-runtime-and-reaches-the-bus-through-it.md)
-- **0201** — [A module keeps its current state in key-value buckets it declares, and reaches them through the runtime](0201-a-module-keeps-its-current-state-in-key-value-buckets-it-declares-and-reaches-through-the-runtime.md)
-- **0203** — [The account's environment is one module's, and every module contributes to it](0203-the-accounts-environment-is-one-modules-and-every-module-contributes-to-it.md)
-- **0204** — [A module contributes shell code to the login shell in named slots, and the login shell is the mesh's seat](0204-a-module-contributes-shell-code-to-the-login-shell-in-named-slots.md)
-- **0205** — [Software the distribution does not package ships as a pinned archive of the module's own](0205-software-the-distribution-does-not-package-ships-as-a-pinned-archive-of-the-module.md)
-- **0206** — [A node reports the Anthropic grant it holds; the licence manager adopts a licence by refreshing it, and what each node should hold is the manager's state](0206-a-node-reports-the-anthropic-grant-it-holds-and-the-licence-manager-adopts-a-licence-by-refreshing-it.md)
-- **0208** — [The graphical session is one module per piece, on the mesh's seats](0208-the-graphical-session-is-one-module-per-piece-on-the-meshs-seats.md)
-- **0209** — [A login on a node moves that node to the account it logged in to; an API key is added from any node, sealed](0209-a-login-on-a-node-moves-that-node-to-its-account-and-an-api-key-is-added-from-any-node-sealed.md)
-- **0211** — [A machine's power is a node seat, its moments take contributions, and its states are events](0211-a-machines-power-is-a-node-seat-its-moments-take-contributions-and-its-states-are-events.md)
-- **0213** — [The operator sets the agent's managed settings through the agent module, under the mesh's own keys](0213-the-operator-sets-the-agents-managed-settings-through-the-agent-module.md)
-- **0214** — [Backups guard against mistakes, stay on the machine, and are declared by the module that owns the data](0214-backups-guard-against-mistakes-and-stay-on-the-machine.md)
-- **0215** — [The machine's message bus is a node seat, and it is never restarted live](0215-the-machines-message-bus-is-a-node-seat-and-is-never-restarted-live.md)
-- **0216** — [The agent's configuration is registered through its module, at three scopes, and served as one plugin](0216-the-agents-configuration-is-registered-through-its-module-at-three-scopes-and-served-as-one-plugin.md)
-- **0220** — [What a machine asks needs its uplink held, and the retired resolver pieces go](0220-what-a-machine-asks-needs-its-uplink-held-and-the-retired-resolver-pieces-go.md)
-- **0225** — [A consumer's identity is bounded by the provision it requires, judged before merge, and never refuses its provider](0225-a-consumers-identity-is-bounded-by-the-provision-it-requires.md)
-- **0228** — [A value given by hand lives only until its module's first good start](0228-a-value-given-by-hand-lives-only-until-its-modules-first-good-start.md)
-- **0232** — [A binding to a consumer's data moves only by a person](0232-a-binding-to-a-consumers-data-moves-only-by-a-person.md)
-- **0233** — [A module declares the data it holds, and the mesh protects and watches it from that declaration](0233-a-module-declares-the-data-it-holds-and-the-mesh-protects-and-watches-it-from-that.md)
-- **0235** — [The bus is backed up by its own snapshot of each stream, taken under the bus module's account](0235-the-bus-is-backed-up-by-its-own-snapshot-of-each-stream.md)
-- **0240** — [A module says how it is healthy, and the node-engine judges it](0240-a-module-says-how-it-is-healthy-and-the-node-engine-judges-it.md)
-- **0241** — [A machine says how its network is, and an outside writer of a mesh file is a finding](0241-a-machine-says-how-its-network-is-and-an-outside-writer-of-a-mesh-file-is-a-finding.md)
-- **0242** — [A recorded build moves only by a person's push, and a send says what it recreates](0242-a-recorded-build-moves-only-by-a-persons-push-and-a-send-says-what-it-recreates.md)  *(proposed)*
-- **0243** — [The agent module removes a home item it did not place only on the person's word, and keeps a copy](0243-the-agent-module-removes-a-home-item-it-did-not-place-only-on-the-persons-word-and-keeps-a-copy.md)
-- **0245** — [A verb says what it replaces, and the agent is guarded from working round the mesh](0245-a-verb-says-what-it-replaces-and-the-agent-is-guarded-from-working-round-the-mesh.md)
-
-### How it is built
-
-- **0011** — [Managed files are generated onto nodes and never edited there](0011-managed-files-are-generated-never-edited.md)
-- **0012** — [The mesh creates no symlinks — a derived file is a copy](0012-the-mesh-creates-no-symlinks.md)
-- **0013** — [Schema and state changes are numbered migrations, in the same language as the code](0013-schema-changes-are-numbered-migrations.md)
-- **0014** — [No workspace — each module is a standalone package consuming published dependencies](0014-no-npm-workspace.md)
-- **0015** — [Applications live in their own repository; the monorepo is for the mesh](0015-applications-live-in-their-own-repository.md)
-- **0016** — [The lab](0016-the-lab.md)
-- **0037** — [Where a module lives](0037-where-a-module-lives.md)
-- **0039** — [What the SDK holds, and what it refuses](0039-what-the-sdk-holds-and-refuses.md)
-- **0068** — [The lab takes requests, one at a time, and runs each from its own copy](0068-the-lab-takes-requests.md)  *(superseded)*
-- **0069** — [A module is a repository and a path within it](0069-a-module-is-a-repository-and-a-path.md)
-- **0076** — [The SDK is a published package, and the toolchain resolves it by version](0076-the-sdk-is-a-published-package.md)
-- **0082** — [The registry is reached by name, and the overlay is its security](0082-the-registry-is-reached-by-name-and-trusted-by-the-overlay.md)
-- **0086** — [A secret reaches a process as a file, and an exception is declared](0086-a-secret-reaches-a-process-as-a-file.md)
-- **0096** — [An upstream image is copied between registries, never through a machine's image store](0096-an-upstream-image-is-copied-between-registries.md)
-- **0097** — [A vendor image is a declared build input, and a recipe fetches nothing undeclared](0097-a-vendor-image-is-a-declared-build-input.md)
-- **0107** — [Persistent data is a directory bind, never a named volume](0107-persistent-data-is-a-directory-bind-never-a-named-volume.md)
-- **0111** — [A build source is on the mesh's git seat, or it is an external repository](0111-a-build-source-is-on-the-git-seat-or-external.md)
-- **0149** — [The live mesh is the test bed](0149-the-live-mesh-is-the-test-bed.md)
-- **0174** — [A node varies a module through settings and kept regions, never through an edit](0174-a-node-varies-a-module-through-settings-and-kept-regions-never-an-edit.md)
-- **0200** — [Genesis pivots to the controller as a container, and the first push hands it to a process](0200-genesis-pivots-to-the-controller-as-a-container-and-the-first-push-hands-it-to-a-process.md)
-
-### How it is checked
-
-- **0017** — [A test defends a decision](0017-a-test-defends-a-decision.md)
-- **0018** — [A picture of a system is read from the system, never from what asked for it](0018-a-picture-is-read-from-what-runs.md)
-- **0089** — [A bed reads the catalogue it proves](0089-a-bed-reads-the-catalogue-it-proves.md)
-- **0093** — [A fixture that runs a module's runtime carries the module's name](0093-a-fixture-that-runs-a-modules-runtime-carries-its-name.md)
-
-### How we work
-
-- **0019** — [How this repository works](0019-how-this-repository-works.md)
-- **0020** — [The mesh is governed by a constitution, injected where work is decided](0020-the-mesh-is-governed-by-a-constitution.md)
-- **0021** — [HQ is the source of the mesh constitution](0021-hq-is-the-source-of-the-constitution.md)
-- **0022** — [The constitution absorbs what is already enforced](0022-the-constitution-absorbs-what-is-enforced.md)
-- **0023** — [The approval is the checkpoint, not the second pair of hands](0023-approval-is-the-checkpoint.md)
-- **0025** — [The design record is read where it is written, never copied to be found](0025-the-design-record-is-read-not-copied.md)
-- **0032** — [The local account owns the mesh; a surface delegates to a module](0032-the-local-account-owns-the-mesh.md)  *(superseded)*
-- **0034** — [The local account owns the mesh, and a web application's login is not that](0034-the-local-account-owns-the-mesh.md)
-- **0080** — [The development cycle is checked, not trusted](0080-the-development-cycle-is-checked.md)
-- **0081** — [A decision nothing cites is not yet in the chain](0081-a-decision-nothing-cites-is-not-yet-in-the-chain.md)
-- **0153** — [The record is read by a module the mesh assigns, and the console lists it](0153-the-record-is-read-by-a-module-and-the-console-lists-it.md)
-- **0244** — [The mesh is described in domains, and one word names one thing](0244-the-mesh-is-described-in-domains-and-one-word-names-one-thing.md)
-
-<!-- index:end -->
+or the `hq-status` skill, or the records module's `records_decisions` from anywhere on the mesh.
+`index.py` checks that every record's topic is one of the six above, and fails if this file stores the
+list again.
diff --git a/04-ISSUES/297-two-open-decisions-always-conflict/00-report.md b/04-ISSUES/297-two-open-decisions-always-conflict/00-report.md
index 145b66f1..86c91e3b 100644
--- a/04-ISSUES/297-two-open-decisions-always-conflict/00-report.md
+++ b/04-ISSUES/297-two-open-decisions-always-conflict/00-report.md
@@ -1,5 +1,5 @@
 ---
-status: located
+status: resolved
 opened: 2026-10-07
 located-in: [hq (02-DECISIONS/README.md, 00-META/checks/index.py)]
 fixed-by:
diff --git a/04-ISSUES/297-two-open-decisions-always-conflict/01-diagnosis.md b/04-ISSUES/297-two-open-decisions-always-conflict/01-diagnosis.md
index 5ca32943..ec320ee0 100644
--- a/04-ISSUES/297-two-open-decisions-always-conflict/01-diagnosis.md
+++ b/04-ISSUES/297-two-open-decisions-always-conflict/01-diagnosis.md
@@ -70,3 +70,16 @@ After that, the work is a change to `index.py` and `02-DECISIONS/README.md` in t
 `hq-status` skill's index view as the place the list is read. If the records module should serve the
 list, that is a separate change in the catalogue. Until the decision is taken, the cost of rebasing stays
 with whoever lands decisions in parallel.
+
+## 2026-10-07: resolved by A
+
+The operator chose A. [ADR 0248](../../02-DECISIONS/0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md)
+supersedes ADR 0019's paragraph on the written index. `02-DECISIONS/README.md` now writes only the six
+topics in their reading order, one line each, and stores no list. `index.py` checks the topics and fails
+on a stored list (it failed on the README of `main` before the list was removed); `index.py --print`,
+the `hq-status` skill and the records module's new `records_decisions` generate the list when it is read.
+`records.py` reads its topics from the same README lines, so there is one list of topics, not two.
+
+The replay the report asks for: two branches off one `main`, each adding a decision record on the same
+topic and nothing else, merged one after the other with `git merge-tree`. Both merge with no conflict,
+and `sh merge-check.sh` passes on each branch and on the merge of both.

From f4a76ca29195de7ac14b6fbc480e354b50ba1a58 Mon Sep 17 00:00:00 2001
From: jochen <jschoubben@novox.be>
Date: Wed, 7 Oct 2026 23:39:30 +0200
Subject: [PATCH 2/2] Issue 297: resolved by hq PR #182 and mesh-catalog PR
 #115

---
 04-ISSUES/297-two-open-decisions-always-conflict/00-report.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/04-ISSUES/297-two-open-decisions-always-conflict/00-report.md b/04-ISSUES/297-two-open-decisions-always-conflict/00-report.md
index 86c91e3b..7361177e 100644
--- a/04-ISSUES/297-two-open-decisions-always-conflict/00-report.md
+++ b/04-ISSUES/297-two-open-decisions-always-conflict/00-report.md
@@ -2,7 +2,7 @@
 status: resolved
 opened: 2026-10-07
 located-in: [hq (02-DECISIONS/README.md, 00-META/checks/index.py)]
-fixed-by:
+fixed-by: [hq PR #182, mesh-catalog PR #115]
 amended-design:
 ---