hq/01-RESEARCH/045-a-knowledge-base-the-mesh-writes/00-overview.md

status, initiated, touches, became

status	initiated	touches	became
active	2026-10-10	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

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). 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).

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 §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)? 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.