7.1 KiB
status, initiated, touches, became
| status | initiated | touches | became | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| graduated | 2026-10-10 |
|
|
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, and whether it should hold light content beside them: meeting notes, architectural drawings and blog posts.
The operator's purpose, given on 2026-10-11: the record becomes shared knowledge that agents reach through tools, so that an agent gets what was decided as an answer instead of reading markdown files, and a session no longer has to start in this repository's folder to know it. A session still starts here for other work, such as writing a record. The operator later put the light content last, and decided that an issue's content belongs in the issue tracker rather than in this repository.
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.
Reading is costly too. Answering one question about what holds today means reading several records whole, and the generated decision index is larger than one tool answer may be.
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
recordsmodule 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 besideissue(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
- 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?
- 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?
- 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? - 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?
- 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?
- Checks as refusals at write.
records.py,cycle.py,words.pyandindex.pyjudge 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? - Import. How are the decision records (274 on
mainon 2026-10-11, numbered up to 0289), 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? - 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.
Documents
- 01 — Findings: what exists, measured on 2026-10-11; where the truth lives (the store for each record's structure and rules, this repository for its reasoning); issues whole in the issue tracker; the order of work; and what is still open.