ADR 0290 and 0291: the operator's confirmations, no folder rule before issue 427, the verb return, the documents' row in to-be 53, and both senses of knowledge base

2026-10-11 01:25:11 +02:00
parent 4c4d96874f
commit b174269ec1
6 changed files with 24 additions and 19 deletions
@@ -575,8 +575,8 @@ Not a domain of the mesh but of the way it is built, listed because its words me
 - **decision record** — one numbered file in `02-DECISIONS/`, never rewritten: **superseded** by a later
  record, or corrected by a marked **progressive insight**. Always qualified in this repository: bare
  *record* has other meanings (see [Homonyms](#homonyms)).
- **clause** — one numbered statement a decision record makes, with its own status (`in force`, `changed`,
-  `superseded`): a later record may change one clause and leave the rest
+- **clause** — one numbered statement a decision record makes, with its own status (`proposed`, `in force`,
+  `changed`, `superseded`): a later record may change one clause and leave the rest
  ([ADR 0290](../02-DECISIONS/0290-the-knowledge-base-holds-each-records-structure-and-clauses-and-hq-keeps-its-reasoning.md)). Not a *rule*, which is a line of
  `00-META/how-we-build.md`.
 - **knowledge base** — the role that holds the structure of the decision records and research efforts (number,
@@ -643,6 +643,8 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical.
 | | a node's own copy of its last declaration | **last declaration** | Placement |
 | record | a numbered decision | **decision record** | The record |
 | | the literal reader of this repository, searched first for a symptom | **the record** (the `records` module) | Operator and conversation |
+| knowledge base | the module holding records' structure and clauses | **knowledge base** | The record |
+| | the predecessor's operational memory, in older playbooks (issue 430) | none: it no longer exists | — |
 | | the upgrade policy that sends nowhere | `record` | Module |
 | check | a pull request's two statuses | **merge check**, **merge gate**, **repository check** | Change and delivery |
 | | a delivery group's verdict | **composed check** | Change and delivery |
@@ -57,7 +57,7 @@ rule 8 already decided that the issue tracker hands out decision and research nu
   comments, history and diff for prose, which git and the forge already give, for records that are edited after they
   are written as often as these are.
 3. **Divided by layer: the store holds each record's structure and its clauses; hq keeps its reasoning.** Adopted.
-   It is what the operator chose on 2026-10-11 when asked what a clean start would pick, and the division ADR 0275
+   It is what the research recommended when the operator asked on 2026-10-11 what a clean start would pick, and the operator chose it, and the division ADR 0275
   already made for issues, carried down to the statement a decision makes.

 ### The unit
@@ -74,7 +74,7 @@ rule 8 already decided that the issue tracker hands out decision and research nu
 2. **Nobody: drafted clauses are served as they are.** Rejected: a summary nobody checked would speak as the record's
   word, which is the work-that-reports-success-and-did-nothing fault.
 3. **A second judgement, independent of the one that drafted them, confirms each record's clauses against its text;
-   the operator is told per topic and may send any record back.** Adopted. A clause keeps its source, so an answer says
+   the operator is told per topic and may send any record back.** Adopted, and confirmed by the operator on 2026-10-11. A clause keeps its source, so an answer says
   whether a clause was written by the record's author or drafted and confirmed.

 ## Decision
@@ -105,7 +105,7 @@ rule 8 already decided that the issue tracker hands out decision and research nu
 6. **An answer is the shape agents need, bounded.** The verbs are `ask` (records and clauses bearing on a question,
   ranked, each saying whether it holds or what changed it), `get` (one record: clauses, links both ways, what changed
   it since, its reasoning only when asked), `holds` (the clauses in force for a topic or a record), `links`,
-   `reserve`, `propose`, `import` and `confirm` (send a record's drafted clauses back). Every answer names the commit of this repository it was read at and stays under
+   `reserve`, `propose`, `import` and `return` (send a record's drafted clauses back to be drafted again). Every answer names the commit of this repository it was read at and stays under
   a size bound that `ask`, `get` and `holds` state; the default is 4 KiB.
 7. **State is in a database in the store**, provided to the module, not in buckets: `ask` needs ranked full-text
   search, which the store's server does and a bucket does not. This narrows nothing in
@@ -53,15 +53,17 @@ the public repository loses is the story of how a question was found, not the an
 2. **Everything in the tracker; hq keeps no issue content.** Adopted.
 3. **Everything in the tracker, and hq keeps a generated public copy of every resolved design or governance issue.**
   Rejected for now: it keeps a second copy, and the public reader who needs the outcome has the decision record. This
-   was the research's open question 2; an export, if it is wanted later, is a decision of its own.
+   was the research's open question 2; the operator confirmed no export on 2026-10-11. An export, if it is wanted
+   later, is a decision of its own.

 ## Decision

 1. **The issue tracker is the truth for an issue whole**: its number, status, links, notes, and its **documents**,
   the report, a diagnosis and a resolution. A document is kept with its author and date, revised in place with its
   history kept; a note stays appended and never edited.
-2. **This repository keeps no issue content.** No new folder is opened under `04-ISSUES/`. `issue-tracker.open` loses
-   its `record` argument once the documents are built.
+2. **This repository keeps no issue content.** Once the tracker holds an issue's documents (issue 427), no new folder
+   is opened under `04-ISSUES/`, `issue-tracker.open` loses its `record` argument, and playbook 03 and `AGENTS.md`
+   say so; until then playbook 03 stands as it is written.
 3. **The 361 folders are imported into the tracker, and then removed.** The import reads every folder through the
   records module at a commit and writes each document onto the issue of the same number, creating what is absent and
   never overwriting; a second run changes nothing and says so. The folders are removed in one pull request only
@@ -72,8 +74,8 @@ the public repository loses is the story of how a question was found, not the an
 5. **No issue content is exported to this repository.** The public record of a design question is the decision
   record it led to.
 6. **The work is tracked by issue 427**: the documents in the tracker, the import, the mentions rewritten, the folders
-   removed, and playbook 03 changed to match. Until it lands, an issue that already has a folder keeps it, and a new
-   design or governance issue is opened in the tracker without one.
+   removed, and playbook 03 changed to match. Until it lands, every folder stays and playbook 03 is followed as it is
+   written.

 ## Consequences

@@ -89,13 +91,13 @@ the public repository loses is the story of how a question was found, not the an

 ## How it is checked

- **No new folder under `04-ISSUES/`** (rule 2): from the pull request that removes the folders, `records.py`
-  refuses a new path into `04-ISSUES/` (rule 4), and `cycle.py` refuses a folder. Until then, a reviewer refuses a
-  pull request that adds one, and the issue tracker's `open` no longer offers `record` once the documents are built.
+- **No new folder under `04-ISSUES/`** (rule 2): from the pull request that removes the folders (issue 427),
+  `records.py` refuses a new path into `04-ISSUES/` (rule 4), and the issue tracker's `open` no longer offers
+  `record`.
 - **The import loses nothing** (rule 3): before the folders are removed, every issue's documents are compared with its
  folder at the import's commit, and the comparison's result is written on issue 427.
- **An issue read whole** (rule 1): the issue tracker's tests of its documents, built under issue 427, listed in
-  [to-be 53](../03-DESIGN/01-to-be/53-the-issue-tracker.md) §7.
+- **An issue read whole** (rule 1): the issue tracker's tests of its documents, built under issue 427, as the row
+  for them in [to-be 53](../03-DESIGN/01-to-be/53-the-issue-tracker.md) §7 says.

 ## References

@@ -199,6 +199,7 @@ worker; one that stops moves the issue on, or is stale a day later.
 | An issue's delivery line follows the delivery; ready to verify once; a stuck fix said once and cleared | the rows of [ADR 0281](../../02-DECISIONS/0281-an-issue-knows-whether-its-fix-is-delivered-and-a-fix-stuck-after-its-merge-is-loud.md)'s "How it is checked" |
 | The triage fills only what is empty, links no cycle, and an issue is ready only when its dependencies' fixes are delivered | the rows of [ADR 0279](../../02-DECISIONS/0279-the-issue-tracker-triages-every-new-issue-and-an-issue-is-ready-when-what-it-depends-on-is-delivered.md)'s "How it is checked" |
 | The duplicate check acts only on a clear duplicate, never on an older or a resolved issue, once per issue, loudly when it cannot judge | the rows of [ADR 0278](../../02-DECISIONS/0278-the-issue-tracker-checks-every-new-issue-for-a-duplicate-through-a-judgement-the-agent-makes-without-tools.md)'s "How it is checked" |
+| An issue's documents are kept whole, with author, date and history, and the import of hq's folders loses nothing ([ADR 0291](../../02-DECISIONS/0291-an-issue-lives-whole-in-the-issue-tracker.md)) | the module's tests of `documents` and of the import, one case per document kind; the comparison of every issue with its folder before the folders are removed, written on issue 427. Tracked by issue 427 |
 | Live | on the mesh, an agent calls `issue-tracker.open` and gets the next number; two sessions on two nodes open at the same moment and get two different numbers; `list` shows both |

 ## 8. The slices after the first
@@ -35,7 +35,7 @@ This document designs the first slice in detail, tracked by issue 425. The slice
  mesh-knowledge  (seat knowledge-base, held once for the mesh)
   ├ its process, launched by the node runtime
   ├ a database in the store    records, clauses, links, sources; ranked full-text search
-   ├ verbs       ask, get, holds, links, reserve, propose, import, confirm
+   ├ verbs       ask, get, holds, links, reserve, propose, import, return
   │             served by the control-node's tool runner
   ├ events      imported, proposed, accepted, changed, drafted, confirmed, returned
   └ consumes    the forge's merge event for hq: read the merged records (§ 4)
@@ -127,7 +127,7 @@ the section does not say. They are stored `drafted`.
 A second judgement, made in a separate call that sees only the record's text and the drafts, answers per clause
 whether the record says exactly that. A clause it accepts becomes `confirmed`; one it rejects stays `drafted` with
 the reason. When every record of a topic has been through both, the operator is told once per topic, with the count
-confirmed and the count still drafted, through the router. `confirm` with a record's number and `return` sends a
+confirmed and the count still drafted, through the router. `return` with a record's number and a reason sends a
 record back to be drafted again.

 ## 7. Answers
@@ -141,7 +141,7 @@ record back to be drafted again.
 | `reserve` | a kind | the next number (§ 5) |
 | `propose` | a kind, a number from `reserve`, a title, a topic, and its links | the structure written as `proposed` |
 | `import` | optionally `dry-run`, a commit | every decision and research effort at that commit, as § 4 reads one, with prose decisions drafted (§ 6); create-if-absent, never an overwrite; run again, changes nothing and says so |
-| `confirm` | a number; `return` with a reason | sends a record's drafted clauses back |
+| `return` | a number and a reason | sends a record's drafted or confirmed clauses back to be drafted again |

 Every answer names the commit it was read at. `ask`, `get` and `holds` answer at most 4 KiB unless a larger bound is
 given, and say when they cut and how to ask for the rest. A clause that is `drafted` is marked so in every answer and
@@ -52,7 +52,7 @@ document is written and this one's status becomes `implemented`.
 | [`50-split-dns-on-a-machine-with-a-vpn-client.md`](50-split-dns-on-a-machine-with-a-vpn-client.md) | **In progress.** A machine whose VPN client pushes servers of its own runs a resolver of its own, on a node seat, that routes the VPN's domains over its link and every other name to the mesh's resolvers; the VPN client's module carries the adapter | [ADR 0247](../../02-DECISIONS/0247-a-machine-with-a-vpn-client-routes-names-by-domain-through-a-resolver-of-its-own.md), [ADR 0223](../../02-DECISIONS/0223-the-mesh-has-two-resolvers-and-a-machine-lists-only-them.md) |
 | [`51-the-registries-keep-what-is-named.md`](51-the-registries-keep-what-is-named.md) | **In progress.** The artifact store, the package registry and each machine's container runtime get tools that say what they hold, what names each thing and what could go; every removal is a dry run unless a person asks and says why, and what decides is always a record | [ADR 0251](../../02-DECISIONS/0251-the-registries-say-what-they-hold-and-keep-what-is-named-and-a-machine-keeps-the-image-it-runs-and-the-one-before.md), [ADR 0189](../../02-DECISIONS/0189-the-store-keeps-what-the-records-name.md) |
 | [`52-shares-and-mounts.md`](52-shares-and-mounts.md) | **In progress.** A node shares one folder at a time through `nfs-server`, which provides it as a provision to the private network only, mapping every client to the folder's owner; a node that asks mounts it through `mounts`, a mount unit and an automount per share, so nothing mounts or fails at boot; a device that comes and goes is an occasional source whose absence is a state | [ADR 0263](../../02-DECISIONS/0263-a-share-is-a-provision-a-node-mounts-it-on-demand-and-only-nodes-that-ask-get-it.md), [ADR 0051](../../02-DECISIONS/0051-shared-data-is-the-operators.md), [ADR 0092](../../02-DECISIONS/0092-an-operator-delivers-a-pair-credential.md) |
-| [`53-the-issue-tracker.md`](53-the-issue-tracker.md) | **Designed.** The mesh keeps its issues in one module, `issues`, on the control-node: every number from one counter advanced by compare-and-set, the cycle's issue rules refused at the write, an event per change; an issue lives whole in the tracker, hq keeping no issue content ([ADR 0291](../../02-DECISIONS/0291-an-issue-lives-whole-in-the-issue-tracker.md)) | [ADR 0275](../../02-DECISIONS/0275-the-mesh-numbers-and-tracks-its-issues-in-a-module-of-its-own-and-hq-keeps-only-the-narrative-of-a-design-or-governance-issue.md) |
+| [`53-the-issue-tracker.md`](53-the-issue-tracker.md) | **Designed.** The mesh keeps its issues in one module, `issues`, on the control-node: every number from one counter advanced by compare-and-set, the cycle's issue rules refused at the write, an event per change; an issue lives whole in the tracker, hq keeping no issue content ([ADR 0291](../../02-DECISIONS/0291-an-issue-lives-whole-in-the-issue-tracker.md)) | [ADR 0275](../../02-DECISIONS/0275-the-mesh-numbers-and-tracks-its-issues-in-a-module-of-its-own-and-hq-keeps-only-the-narrative-of-a-design-or-governance-issue.md), [ADR 0291](../../02-DECISIONS/0291-an-issue-lives-whole-in-the-issue-tracker.md) |
 | [`54-the-controllers-records-on-the-bus.md`](54-the-controllers-records-on-the-bus.md) | **Designed.** The controller keeps five record mirrors on the bus (nodes, assignments, walks, builds, settings): each a bucket written from its store only when the record changed, with one event per write, and audited against the store every self-check run, a difference raised as `mirror-drifted` before the healer H6 repairs it | [ADR 0289](../../02-DECISIONS/0289-the-controller-mirrors-its-records-into-buckets-written-only-on-a-change-and-audited-against-its-store.md) |
 | [`55-the-knowledge-base.md`](55-the-knowledge-base.md) | **Designed.** The mesh keeps its decision records' and research efforts' structure in one module, `mesh-knowledge`, on the control-node: number, status, topic, typed links both ways, and each decision's clauses with their own status; a record is accepted when its pull request merges; agents ask what holds in one bounded call, and hq keeps the reasoning | [ADR 0290](../../02-DECISIONS/0290-the-knowledge-base-holds-each-records-structure-and-clauses-and-hq-keeps-its-reasoning.md) |