diff --git a/01-RESEARCH/045-a-knowledge-base-the-mesh-writes/00-overview.md b/01-RESEARCH/045-a-knowledge-base-the-mesh-writes/00-overview.md new file mode 100644 index 00000000..dd6f6a96 --- /dev/null +++ b/01-RESEARCH/045-a-knowledge-base-the-mesh-writes/00-overview.md @@ -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.