Merge pull request 'Research 045: a knowledge base the mesh writes (decisions, guidelines, policies)' (#288) from research/045-a-knowledge-base-the-mesh-writes into main

2026-10-10 16:17:34 +00:00
parent 3c323370b7 72f940d2c7
commit 0cabe5d391
1 changed files with 94 additions and 0 deletions
@@ -0,0 +1,94 @@
+---
+status: active
+initiated: 2026-10-10
+touches:
+  - 02-DECISIONS/0019-how-this-repository-works.md
+  - 02-DECISIONS/0080-the-development-cycle-is-checked.md
+  - 02-DECISIONS/0153-the-record-is-read-by-a-module-and-the-console-lists-it.md
+  - 02-DECISIONS/0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md
+  - 02-DECISIONS/0274-an-agent-proposes-a-shared-instruction-section-and-every-node-takes-it-only-on-the-operators-warrant-which-it-proves-itself.md
+  - 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
+  - 03-DESIGN/01-to-be/53-the-issue-tracker.md
+  - 00-META/process/
+  - 00-META/checks/
+  - 00-META/glossary.md
+  - the records module's tools
+became: []
+---
+
+# 045 — A knowledge base the mesh writes: decisions, guidelines, policies
+
+## What
+
+Whether the mesh should **write** its own knowledge (decision records, guidelines, policies, designs and
+playbooks) through a module's verbs, instead of only **reading** hand-written markdown. The effort
+frames the questions below and answers none of them yet; the research itself is done separately.
+
+Today the record is read-only. The `records` module reads this repository and serves it to sessions
+([ADR 0153](../../02-DECISIONS/0153-the-record-is-read-by-a-module-and-the-console-lists-it.md)).
+Everything in it is written by hand as markdown and reaches `main` through a pull request; the hq checks
+in `00-META/checks/` judge it only after it is written. The issue tracker has already taken issues out
+of this path: it numbers and tracks them in a module of its own, and hq keeps only the narrative
+([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)).
+
+## Why
+
+Numbers collide, and the checks find a collision only after it happens. On 2026-10-10, research number
+043 was taken by one open pull request while a second session held an unpushed branch claiming the same
+number for a different effort. On 2026-10-07 three decision numbers collided in one evening. A
+record written by a verb could take its number from one counter, the way the issue tracker does.
+
+Some knowledge also has no home. This repository is public, so it may not name nodes or describe
+operations; the mesh's knowledge about its own installation lives in agents' private notes, in no
+shared and searchable place.
+
+## The two options to weigh
+
+- **A. Git stays the store.** The `records` module gains write verbs (propose, amend as a progressive
+  insight, supersede, retire), each of which makes a branch and a pull request through the forge. Numbers
+  come from the issue tracker's counters, as a further sequence beside `issue`
+  ([to-be 53](../../03-DESIGN/01-to-be/53-the-issue-tracker.md) §4).
+- **B. A store is the truth, and hq is its rendered public export**, as the issue tracker already is for
+  issues (ADR 0275).
+
+## The questions
+
+1. **Types and lifecycles.** Which kinds of knowledge exist: decision, guideline, policy, design,
+   playbook, and any others? What lifecycle does each have (proposed, accepted, superseded, retired;
+   to-be and as-is for a design), and which transitions does each kind allow?
+2. **Numbering from one counter.** One sequence per kind, or one for all? How is a number reserved for
+   a draft that is later abandoned, given that a number is never reused? How are today's collisions
+   (043 is the latest example) resolved on import?
+3. **Typed links.** Which links between records are needed: supersedes, amends, implements, cites,
+   decided-by, and others? Which of them does frontmatter express today (`became:`, `decisions:`,
+   `fixed-by:`), and which exist only as prose links that no check reads?
+4. **Approval.** A decision or a policy changes how the mesh is run. Should accepting one require the
+   operator's warrant on a channel that proves who answered, as a shared instruction section already
+   does ([ADR 0274](../../02-DECISIONS/0274-an-agent-proposes-a-shared-instruction-section-and-every-node-takes-it-only-on-the-operators-warrant-which-it-proves-itself.md))?
+   Which kinds need it, and which may an agent write on its own?
+5. **Public and private knowledge.** Node names and operational knowledge have no home today. Does the
+   knowledge base hold private records beside public ones, with a rule for which may be exported? How is
+   a record checked so that nothing private reaches the public repository?
+6. **Checks as refusals at write.** `records.py`, `cycle.py`, `words.py` and `index.py` judge a pull
+   request after it is written. Which of their rules can become refusals of the write verb itself, and
+   which only make sense across the whole record?
+7. **Import.** How are the decision records (265 files on `main` on 2026-10-10, numbered up to 0279), the designs and the playbooks imported without
+   losing their history, their numbers or their links? Is the import repeatable, as the issue tracker's
+   is?
+8. **What git gives today.** Review on a pull request, line comments, a history of every change with
+   its author, a diff, a revert, and the forge's required checks. What of that would a store have to
+   rebuild under option B, and what would option A lose by making every write a pull request?
+
+## Words
+
+The glossary has words for **decision record**, **design**, **playbook** and **the record** (the
+`records` module), but none for **guideline** or **policy** in this sense, and *policy* is already used
+for a module's **upgrade policy**. This effort uses "guideline" and "policy" as plain descriptions, and
+"knowledge base" for the whole, until a decision settles the words through the glossary's own rules.
+
+## What it touches
+
+How this repository works (ADR 0019) and how the development cycle is checked (ADR 0080), the
+`records` module (ADR 0153) and the generated decision index (ADR 0248), the issue tracker and its
+counters (ADR 0275, to-be 53), approval on a proving channel (ADR 0274), the playbooks in
+`00-META/process/`, the hq checks in `00-META/checks/`, and the glossary.