novox/hq
6
0
Fork 0
Code Issues Pull Requests 5 Releases Wiki Activity

Research 045: the store holds each record's structure and rules, hq its reasoning, and issues live whole in the tracker
mesh/merge-gate pass: the change touches no module of the mesh's graph
Details
mesh/repo-check pass: its merge-check.sh passed
Details
mesh/delivery superseded: a newer head of the same pull request
Details

Browse Source
This commit is contained in:
jschoubben
2026-10-11 00:41:59 +02:00
parent fcf2fd0b46
commit 91ae2ddb0f
2 changed files with 224 additions and 215 deletions
Download Patch File Download Diff File Expand all files Collapse all files
01-RESEARCH/045-a-knowledge-base-the-mesh-writes/00-overview.md
+5 -3
View File
@@ -27,7 +27,8 @@ should hold light content beside them: meeting notes, architectural drawings and
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.
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](../../02-DECISIONS/0153-the-record-is-read-by-a-module-and-the-console-lists-it.md)).
@@ -103,5 +104,6 @@ counters (ADR 0275, to-be 53), approval on a proving channel (ADR 0274), the pla
## Documents
- [01 — Findings](01-findings.md): what exists, measured on 2026-10-11; an answer to each of the eight
questions; a first slice; and what needs the operator.
- [01 — Findings](01-findings.md): 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.
01-RESEARCH/045-a-knowledge-base-the-mesh-writes/01-findings.md
+219 -212
View File
@@ -1,17 +1,19 @@
# 01 — Findings
Measured on 2026-10-11 against `main` of this repository, the records module and the issue tracker as they
answer through the mesh MCP server, and the hq checks in `00-META/checks/`. Section 0 is what exists; sections 1 to 8
answer the overview's eight questions in order; section 9 is the first slice this effort recommends; section 10
lists what needs the operator.
answer through the mesh MCP server, and the hq checks in `00-META/checks/`. Section 0 is what exists; section 1 is where the truth lives, which
decides the rest; sections 2 to 9 answer the overview's questions and the operator's additions; section 10 is
the order of work, and section 11 what is still open.
## The purpose, in the operator's words
The operator gave the purpose on 2026-10-11: the decisions and the rest of the record should become **shared
knowledge that agents reach through tools**, instead of reading markdown files, and a session should no longer
have to start in this repository's folder to know what was decided. A session still starts here for other work,
such as writing a record. On the same day the operator widened the scope: the knowledge base also holds **light
content**, such as meeting notes, architectural drawings and blog posts.
such as writing a record. Later that day the operator widened the scope to **light records**
(meeting notes, architectural drawings, blog posts) and then put them last; asked for a structured store of
the decisions and research efforts; and decided that an issue's content belongs in the issue tracker, not in
this repository.
That purpose moves the weight of the overview's questions. Where the truth is stored (option A or B) matters
less than **what an answer looks like**: an agent needs the rule that holds now, with the records it rests on,
@@ -40,7 +42,7 @@ come from, what changed them since, and the commit it was read at.*
| A decision's rules | 263 records have a `Decision` section; only 37 of them write it as numbered rules with a bold lead (198 rules in all); the rest write prose |
| Drawings | no file but markdown in the repository; no diagram source; 22 designs carry diagrams drawn in text characters |
| Knowledge with no home | the repository is public, and its README says what only makes sense to someone who knows this installation "is either a note in the wrong place or a disclosure"; one agent's private notes hold 89 files for one repository on one node, and issue 367 (a session's memory stays on the node where it was learned) is open |
| The hq checks | 33 rules: 25 judge one record, 4 the whole record, 4 the prose (section 6) |
| The hq checks | 33 rules: 25 judge one record, 4 the whole record, 4 the prose (section 7) |
Three things follow.
@@ -55,231 +57,236 @@ Three things follow.
edited after creation, every edit through a pull request with a human approval. Whatever is built must keep
that review for what governs the mesh.
## 1. Kinds and their lifecycles
## 1. Where the truth lives: what a clean start would choose
Two families, which the operator's addition makes plain.
The operator asked on 2026-10-11 which option this effort would choose with no prior setup. The answer
decides the rest, so it comes first.
**Governing kinds** change how the mesh is built or run, and are reviewed before they hold:
**The unit the mesh reasons about is a rule, not a file.** A decision is a handful of rules. A later decision
changes one of them: ADR 0282 replaces one rule of ADR 0276 and leaves the others standing. Git and markdown
know files only, so that change can be written only as prose. The earlier record keeps `accepted`, and every
reader must read both records to learn what holds. Section 0's loose links all have this one cause: 21 partial
supersessions with no reverse, 6 said only in prose, 6 markers no field agrees with.
| Kind | Lifecycle | Notes |
|---|---|---|
| decision | proposed → accepted → superseded; accepted records can be changed in part, and carry dated progressive insights | the 274 records |
| design | proposed → designed → in-progress → implemented, in one of two layers (to-be, as-is) | 71 documents |
| research | active → graduated or abandoned | 44 efforts |
| playbook | in force, or retired | 8, with no frontmatter today |
| glossary entry | in force, or retired with its replacement | one file today; an entry is the natural unit |
**A store can hold what a repository cannot.** In a store, each rule is an entry with its own status and links
("in force", "changed by rule 2 of 0282"). A write that leaves the record inconsistent is refused when it is
made, not found by a check afterwards. Numbers come from one counter. "What holds now" is one query.
A **guideline** and a **policy**, which the overview named, have no record of their own today. What the
operator calls a policy is written as a decision; what an agent should do is a shared instruction section
(ADR 0274) or a personal rule ([ADR 0273](../../02-DECISIONS/0273-the-agents-home-is-the-modules-and-the-operators-personal-rules-and-lessons-are-registered-through-it.md)).
This effort recommends no new governing kind: rules for agents stay with the agent module's register, and the
knowledge base links to them instead of holding a second copy.
**What git does best is review of prose.** The reasoning behind a decision (its context, the options weighed,
its consequences) is read and commented on by people. Agents rarely ask for it. They ask what holds.
**Light kinds** are written, read and kept, but govern nothing:
So a clean start divides **by layer, not by kind**:
| Kind | Lifecycle | Notes |
|---|---|---|
| note | written, then kept or archived | meeting notes, a brainstorm with one or more agents, a hand-over |
| post | draft → published, or withdrawn | a blog post, an explanation for readers outside the mesh |
| drawing | current, or replaced by a newer version | an architectural drawing: a file plus a text description |
- **the store is the truth for the structure** of every governing record: its number, title, kind, topic,
status, its rules one by one, and its typed links, at the level of the rule where a link is about a rule;
- **this repository keeps the reasoning** as markdown under the store's number, reviewed in pull requests.
A light record needs no review to exist, since nothing obeys it. It can link to the governing records it
discusses. A meeting's outcome that should hold becomes a proposed decision, which goes the governing way. The
operator's brief for the meshboard asks for a knowledge base with meetings where the operator brainstorms with
agents; a note is that meeting's record.
## 2. Numbering from one counter
The issue tracker already hands out numbers by compare-and-set on a counter key, and its design plans a
decision counter and a research counter as a later slice
([to-be 53](../../03-DESIGN/01-to-be/53-the-issue-tracker.md) §4). The 16 concurrent collisions all come from
reading the next number off a repository that many branches write at once; one counter removes them.
- **One sequence per governing kind**: decision, research, design. Numbers keep their meaning in conversation
("ADR 0276"), so they stay per kind.
- **A light record needs no number.** It gets a key, its date and its title; nobody says "note 1432".
- **A reserved number is spent.** A draft that is abandoned leaves its number as withdrawn, with who reserved
it and when. Gaps already exist (15 on `main`) and harm nothing; reusing a number would.
- **The counter starts above the highest number on `main` and on every open branch**, as the tracker's did.
Whether the counter lives in the tracker's `counters` bucket or in the knowledge base's own state is a design
choice. This effort recommends the knowledge base's own: a number is the knowledge base's to hand out, and the
tracker's design planned the extra counters only because nothing else would hold them.
## 3. Typed links
What frontmatter expresses today, and how reliably:
| Link | Today | Reliable |
|---|---|---|
| extends | `extends`, one target, two spellings | yes, after normalising the spelling |
| supersedes / superseded-by | both fields, mirrored | yes, 9 of 9 mirror |
| supersedes in part | one direction only; the target still reads `accepted` | no: 21 links have no reverse, and 6 more exist only in prose |
| rests on, amended | 2 and 1 records | too rare to trust |
| research became | `became` | yes |
| design names its decisions | `decisions` | yes |
| design names its code | `code`, free text | no |
| cites | prose links: 1,785 decision to decision, 716 to-be to decision, 469 decision to issue | readable, untyped |
The links an answer needs are **supersedes**, **changes in part**, **extends**, **became**, **decided by**
(design to decision), **cites**, and for light records **discusses**. The knowledge base stores each link in
both directions, so "what changed this record since" is one lookup. That is the question the merge window
example needs answered, and today it needs reading five records.
## 4. Approval
The overview asked whether accepting a decision should need the operator's warrant on a proving channel, as a
shared instruction section does.
- **Governing kinds already have an approval**: a pull request merged only with a human approval and both
required checks green. That is the warrant for a decision, and building a second one beside it would split
the evidence. A write verb for a governing kind therefore ends in a pull request (option A).
- **Light kinds need none to be written.** An agent may write a note or a draft post on its own; it is the
agent's record of what happened, and nothing obeys it.
- **Publishing needs the operator.** A post going out, or a light record exported into this public repository,
cannot be taken back once read. That act goes through an ask the operator answers on a proving channel
([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)).
## 5. Public and private knowledge
This repository is public and must stay so. Knowledge about this installation has no shared home: it lives in
one agent's notes on one node (89 files), which no other session reads.
The knowledge base gives it one. **Every record carries a visibility, `public` or `private`.** Governing kinds
that come from this repository are public. A light record is private by default. A private record is served to
the mesh's own sessions through the mesh MCP server and never written into this repository; a record becomes public
only through the publishing act of section 4.
The check that nothing private leaks has to run where the export runs: the existing `words.py` rules for
identifiers, plus a list of the installation's own names held privately by the knowledge base and checked
against every record before it is exported. The words check cannot carry that list itself, since the list
would then be public.
Agents' notes to themselves are not this. A lesson or a personal rule belongs to the agent module's register
(ADR 0273), and carrying memory between nodes is issue 367's question. The knowledge base is for what the
operator and every agent should be able to look up, not for what an agent tells itself.
## 6. Checks as refusals at write
Of the 33 rules the hq checks enforce:
- **25 judge one record** and can become refusals of a write verb, given read access to the others: a link
resolves, a cited decision is accepted, supersession is symmetric, a design's layer matches its place, a
to-be design names a decision, a number is not taken twice, and the like. Two of them (a cited record that
becomes superseded later) can break without the citing record changing, so a write that supersedes must
check who cites the record it supersedes.
- **4 judge the whole record** (an accepted decision cited by nothing, an allowance nobody uses, two copies of
the retired words agreeing) and stay checks over the whole, run on every merge.
- **4 judge prose** (retired words, a daemon command line, the progressive-insight marker, a deferral naming its
issue) and stay checks on the text.
For governing kinds, the pull request keeps all 33 as they are. The write verb refuses early what 25 of them
would fail later, which saves a round trip but adds no new rule. For light kinds, the verb is the only gate:
it refuses a link to a record that does not exist, and an export with a private name in it.
## 7. Import
For governing kinds, **nothing is imported once**. The knowledge base reads this repository at every merge,
as the records module already does at the commit it names
([ADR 0153](../../02-DECISIONS/0153-the-record-is-read-by-a-module-and-the-console-lists-it.md)), and rebuilds
its index from it: kinds, numbers, statuses, typed links in both directions, sections, and each decision's
rules. That is repeatable by construction, and the index can always be thrown away and rebuilt.
Two things a reading cannot recover alone:
- **Loose links.** The 6 supersessions said only in prose, the 7 body markers without a field, the 47 bare
`extends` targets and the 21 one-way partial supersessions are repaired in this repository by one pull
request, through progressive insights where a record's meaning is touched. The knowledge base does not guess
them.
- **What a decision decided, short.** 226 of 263 decision sections are prose. An answer needs each record's
rules as short statements. This effort recommends a `summary` per record: the rules it decides, one line
each, in the record's own frontmatter. For the 274 existing records, a first draft can be written by the
agent's judgement ([ADR 0278](../../02-DECISIONS/0278-the-issue-tracker-checks-every-new-issue-for-a-duplicate-through-a-judgement-the-agent-makes-without-tools.md))
and is reviewed in pull requests, a topic at a time. From then on, `records.py` refuses a decision without
one. A summary nobody reviewed is never served as the record's word.
For light kinds the knowledge base is the truth, so there is nothing to import, except the meeting notes and
other light material that exist today outside the mesh, if the operator wants them in.
## 8. What git gives, and what each option keeps
| What git and the forge give today | A: git stays the store | B: a store is the truth, hq its export |
|---|---|---|
| review on a pull request, line comments | kept | rebuilt or lost |
| history of every change with its author | kept | rebuilt per record |
| diff and revert | kept | rebuilt |
| the required checks on every change | kept | rebuilt as refusals, and the 4 whole-record rules need a new home |
| one number per record | the counter of section 2 | the counter of section 2 |
| an answer in one call | the index of section 7 | the store |
| a home for private and light records | no: the repository is public | yes |
Option A keeps everything review gives, for the kinds that need review. It cannot hold private or light
records. Option B holds those, but would rebuild review, history and the checks, for 189 records out of 271
that are edited after they are written.
**The recommendation is both, divided by kind**, the way the issue tracker already divided issues
That is the division the issue tracker already made for issues
([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)):
the tracker holds number, status and links, and hq held the narrative. Section 9 takes issues one step further,
on the operator's word: their narrative leaves this repository too.
- **Governing kinds**: this repository stays the truth for their text and frontmatter. The knowledge base
hands out their numbers, indexes them at every merge, and serves them as answers. Writing one stays a pull
request, which a write verb can open.
- **Light kinds**: the knowledge base is the truth. It stores them, private by default, and exports one to
this repository only on the operator's word.
Option A (git stays the truth, a module indexes it) was weighed and is not chosen. It keeps review, but it
keeps the rule-level links in prose and the refusals after the fact, which is the cause of section 0's mess.
Option B in full (the reasoning moves into the store too) is not chosen either: it would rebuild review, line
comments, history and diff for prose, which git already gives.
## 9. The first slice
## 2. Kinds and their lifecycles
**A Go module serving one seat held once for the mesh, on the control-node, beside the issue tracker.** The
working name of the seat is `knowledge-base`; the glossary has no word for it yet (see *Words* below).
| Kind | Lifecycle | Notes |
|---|---|---|
| decision | proposed → accepted → superseded; a rule can be changed or superseded on its own; a dated progressive insight corrects a fact | 274 records |
| research | active → graduated or abandoned | 44 efforts |
| design | proposed → designed → in-progress → implemented, in one of two layers (to-be, as-is) | 71 documents; a later slice (section 10) |
| playbook | in force, or retired | 8, with no frontmatter today; a later slice |
| glossary entry | in force, or retired with its replacement | one file today; a later slice |
**Storage.** Light records and the index of governing records live in a database in the store, provided to
the module. The bus's key-value buckets are the wrong place here: the limits of
[ADR 0201](../../02-DECISIONS/0201-a-module-keeps-its-current-state-in-key-value-buckets-it-declares-and-reaches-through-the-runtime.md)
§6 (256 KiB a value, 64 MiB a bucket) are below the 6.9 MB the index holds, and an answer needs full-text
search ranked by relevance, which the store's server does and a bucket does not. The numbers' counter can
stay a bucket key with compare-and-set, as the tracker's is. A drawing's file goes into an object-store
bucket ([ADR 0288](../../02-DECISIONS/0288-the-object-store-stays-on-the-maintained-fork-and-garage-is-chosen-only-after-the-consumers-s3-features-are-counted.md));
its record holds the description an agent reads, and the link to the file.
The first slice holds decisions and research, the two the operator named.
**Verbs, shaped as answers.** Each answer is bounded in size and names the commit of this repository it was
read at.
A **guideline** or a **policy**, which the overview named, has no record of its own today. What the operator
calls a policy is written as a decision; what an agent should do is a shared instruction section (ADR 0274) or
a personal rule ([ADR 0273](../../02-DECISIONS/0273-the-agents-home-is-the-modules-and-the-operators-personal-rules-and-lessons-are-registered-through-it.md)).
No new kind is proposed for either.
| Verb | Answers |
|---|---|
| `ask` | the records that bear on a question, ranked: for each, its number, kind, status, title and summary, and whether it still holds or what changed it |
| `get` | one record: its summary, its rules, its links both ways, what changed it since; the full text only when asked for |
| `holds` | for a topic or a record, the rules in force now, after every supersession, partial change and progressive insight, each with the record it comes from |
| `links` | a record's typed links, both directions |
| `reserve` | the next number of a kind, spent whether or not the record lands |
| `write` | a light record (note, post, drawing): written, private unless said otherwise |
| `publish` | ask the operator to make a light record public, and export it on a yes |
**Light records** (meeting notes, drawings, blog posts) were added to the scope by the operator on 2026-10-11
and put last by the operator the same day. They govern nothing, need no review to exist, and are private by
default; a drawing's file belongs in an object-store bucket
([ADR 0288](../../02-DECISIONS/0288-the-object-store-stays-on-the-maintained-fork-and-garage-is-chosen-only-after-the-consumers-s3-features-are-counted.md))
with a text description an agent reads. They are a later slice (section 10) and shape nothing in the first.
The records module stays as it is: it is the literal reader of the repository, and `ask` and `get` do not
replace a search for a symptom's literal text.
## 3. Numbering from one counter
**How a session reaches it.** The knowledge base's tools reach every session through the mesh MCP server, like every
module's. One shared instruction section, proposed and approved by ADR 0274's route, tells every session to ask
the knowledge base about decisions and designs before reading files. A session then needs this repository's
folder only to write a governing record.
The 16 concurrent collisions all come from reading the next number off a repository that many branches write
at once. The issue tracker hands out numbers by compare-and-set on a counter key
([to-be 53](../../03-DESIGN/01-to-be/53-the-issue-tracker.md) §4); the knowledge base does the same.
**Proved by the acceptance sentence above**: the merge window question, asked from a session outside this
repository, answered in one call under 4 KiB, naming ADR 0276, the partial change ADR 0282 made to it, and the
commit.
- **One sequence per kind**: decision, research, and later design. Numbers keep their meaning in conversation
("ADR 0276").
- **A reserved number is spent.** A proposal that is abandoned keeps its number with status `withdrawn`, who
reserved it and when. Gaps already exist (15 on `main`) and harm nothing; a reused number would.
- **The counter starts above the highest number on `main` and on every open branch**, as the tracker's did.
- **The counters live in the knowledge base.** To-be 53 planned decision and research counters in the tracker
only because nothing else would hold them; the tracker keeps the issue counter alone.
## 10. What needs the operator
## 4. Rules and typed links
1. **Divided by kind (section 8)**: this repository stays the truth for decisions, designs, research and
playbooks, and the knowledge base is the truth only for light records. The alternative is option B for
everything.
2. **A summary per decision record (section 7)**, drafted by the agent's judgement for the existing 274 and
reviewed in pull requests, then required of every new record.
3. **Private by default for light records (section 5)**, with publishing on the operator's word.
4. **The store's database for the module (section 9)**, instead of the bus's buckets alone.
**A rule** is one short statement a decision makes, numbered within its record ("0276 rule 1"), with its own
status: `in force`, `changed by` a rule of a later record, or `superseded`. 37 of 263 decision sections already
write numbered rules with a bold lead (198 rules); the other 226 write prose, from which the import drafts the
rules (section 7).
The links the first slice holds, each stored in both directions:
| Link | From → to | Today |
|---|---|---|
| supersedes | record → record | `supersedes` / `superseded-by`, 9 of 9 mirrored |
| changes | rule or record → rule | `supersedes-in-part` on 15 records, one direction; 6 more only in prose |
| extends | record → record | `extends` on 229, two spellings |
| became | research → decision or design | `became` |
| decided by | design → decision | `decisions` |
| corrects | progressive insight → record | the dated marker, 55 in 39 records |
| cites | any → any | prose links: 1,785 decision to decision, 469 decision to issue |
"What holds about X" is then: the rules matching X whose status is `in force`, each with its record and the
changes that brought it to its present wording.
## 5. Approval
A decision governs how the mesh is built and run, so it needs a human approval before it holds.
- **Proposing** reserves a number and writes the structure with status `proposed`. Any agent may propose.
- **Accepting** happens when the pull request carrying the record's reasoning merges with its human approval
and both required checks. The knowledge base sees the merge on the bus and moves the record and its rules to
`accepted` and `in force`, and every rule it changes to `changed by`. The merge is the warrant; a second
approval beside it would split the evidence.
- **A progressive insight** is a correction of fact and goes the same way: a pull request on the reasoning,
and the structure recorded on merge.
- A **structural write without a pull request** (a link added, a rule's wording fixed) is refused for an
accepted record. Changing what an accepted record says is a new decision, as it is today.
## 6. Public and private
This repository is public and stays so. The reasoning of a decision or research effort stays here, public.
The structure in the store is derived from public records and may be exported here as generated pages, like
the decision index of [ADR 0248](../../02-DECISIONS/0248-the-decision-index-is-generated-when-it-is-read-and-never-stored.md),
generated when read and never stored.
What changes is the issues' narrative (section 9): it moves into the tracker, which is the mesh's own and not
public. The public repository loses those narratives. ADR 0275 kept them public on purpose, citing *the mesh
remembers*; the tracker remembers them as well, but only for the mesh. Whether a resolved issue's narrative is
ever exported publicly is a question for the decision that supersedes that part of ADR 0275.
Knowledge about this installation (one agent's 89 private notes, issue 367) stays out of scope. Agents' lessons
and rules belong to the agent module's register (ADR 0273).
## 7. Checks as refusals at write, and the import
Of the 33 rules the hq checks enforce, **25 judge one record** and become refusals of the knowledge base's
write verbs: a number taken twice, a supersession not mirrored, a cited record not accepted, a record without a
topic, a research effort graduated without `became`. Two need a look beyond the record: a write that
supersedes must check who cites what it supersedes. **4 judge the whole record** and **4 judge the prose**;
those stay checks on this repository, run on every pull request. As frontmatter leaves this repository
(section 8), the 25 leave `records.py` and `cycle.py` with it, and a check is added that a record's reasoning
names a number the knowledge base holds.
**The import** reads this repository at a commit through the records module and writes each decision and
research effort at its own number: status, topic, date, deciders, links, and its rules. Like the tracker's, it
creates what is absent, never overwrites, never advances a counter, and a second run changes nothing and says
so. Two things a reading cannot recover alone:
- **Loose links.** The 6 supersessions said only in prose, the 6 markers no field agrees with, the 47 bare
`extends` targets and the 21 one-way partial supersessions are repaired in this repository first, by one
pull request, so the import reads clean input.
- **The rules of 226 decisions written as prose.** The import drafts them through the agent's judgement
([ADR 0278](../../02-DECISIONS/0278-the-issue-tracker-checks-every-new-issue-for-a-duplicate-through-a-judgement-the-agent-makes-without-tools.md))
and stores them as `drafted`, not `in force`. A topic's drafts are confirmed by the operator or a reviewer in
one pass. An answer marks a drafted rule as drafted, and never presents it as the record's word.
## 8. What leaves this repository, and what stays
| | Today, in this repository | After |
|---|---|---|
| a decision's number, status, topic, links | frontmatter | the knowledge base; the file keeps the number in its name and heading |
| a decision's rules | prose in the `Decision` section | the knowledge base; the section stays as prose for the reasoning |
| a decision's context, options, consequences | markdown | unchanged |
| a research effort's status and `became` | frontmatter | the knowledge base |
| a research effort's documents | markdown | unchanged |
| the decision index | generated from frontmatter when read | generated from the knowledge base when read |
| an issue's report, diagnosis, resolution | `04-ISSUES/NNN-slug/` for 361 issues | the issue tracker (section 9) |
Frontmatter leaves a file only after the import has proven it holds the same values, one kind at a time, as
ADR 0275 did for issues' status.
## 9. Issues live in the issue tracker, whole
The operator decided on 2026-10-11 that an issue's content belongs in the issue tracker, not in this
repository. Measured on `main`: 361 issue folders, 1.9 MB; a folder's median is 4.4 KB and the largest
25.9 KB, well under a tracker value's 256 KiB. Every folder has `00-report.md`; 107 have a diagnosis, 9 a
resolution, 1 a progress file. Since ADR 0275, new issues live in the tracker already; the highest issue folder
is 364.
What the tracker needs to hold it:
- **an issue's documents**: the report it already holds, plus a diagnosis and a resolution as named documents
of the issue, each with its author and date, revised in place with history (notes stay append-only);
- **an import** of the 361 folders, repeatable, keeping each issue's number and dates;
- **links** from records: 250 files in this repository link into `04-ISSUES/` 765 times. Those links become
plain "issue N" references that the knowledge base and the tracker resolve, rewritten in one pull request
once the import is proven; the link check in `records.py` then refuses a new link into `04-ISSUES/`.
This supersedes part of ADR 0275 (hq keeps the narrative of a design or governance issue), so it needs its own
decision record.
## 10. Slices
1. **Clean the input** (this repository, one pull request): repair the loose links of section 7, so the import
reads clean records. Beside it, a shared instruction section proposed for every session: take a decision
or research number from the counter once it exists, name a partial supersession in a field, never only in
prose.
2. **The knowledge base, decisions and research**: a Go module serving one seat held once for the mesh, on
the control-node beside the issue tracker. The counters, the import, the rules and links, and the answers:
| Verb | Answers |
|---|---|
| `ask` | the records and rules that bear on a question, ranked: number, kind, status, title, and whether each rule still holds or what changed it |
| `get` | one record: its rules, its links both ways, what changed it since; its reasoning's text only when asked |
| `holds` | for a topic or a record, the rules in force now, each with the record it comes from |
| `reserve` | the next number of a kind, spent whether or not the record lands |
| `propose` | a new record's structure, status `proposed` |
| `import` | this repository's decisions and research at a commit, repeatable |
Storage is a database in the store, provided to the module: the structure is small, but `ask` needs ranked
full-text search, which the store's server does and a bucket does not. The counters stay bucket keys with
compare-and-set, as the tracker's. Every answer is bounded in size.
3. **Frontmatter leaves this repository**, kind by kind, once the import is proven equal.
4. **Issues whole in the tracker** (section 9): documents, import, links rewritten, folders removed.
5. **Designs, playbooks and glossary entries** into the knowledge base the same way.
6. **Light records**: notes, posts and drawings.
How a session reaches it: the knowledge base's tools reach every session through the mesh MCP server, and one
shared instruction section, approved by ADR 0274's route, tells every session to ask the knowledge base what
holds before reading files. A session needs this repository's folder only to write a record's reasoning.
Proved by the acceptance sentence at the top: the merge window question, asked from a session outside this
repository, answered in one call under 4 KiB, naming ADR 0276's rules in force and the one ADR 0282 changed.
## 11. What needs the operator
Decided by the operator on 2026-10-11: the store is the truth for structure and this repository for reasoning
(section 1); light records come last; issues live whole in the tracker (section 9).
Still open:
1. **Drafted rules (section 7)**: the 226 prose decisions get their rules drafted by the agent's judgement and
confirmed a topic at a time. Who confirms: the operator, or an independent reviewing agent with the operator
seeing a summary?
2. **Issues' public narrative (section 6)**: once issues leave this repository, is a resolved design or
governance issue ever exported here publicly, or does it stay the mesh's alone?
## Words
The glossary has **decision record**, **design**, **playbook** and **the record** (the records module). It has
no word for the whole this effort describes, for its seat, or for the light kinds. This effort proposes, for a
decision to settle through the glossary's own rules: **knowledge base** for the whole and its seat,
**governing record** for a kind that is reviewed before it holds, and **note**, **post** and **drawing** for
the light kinds. *Policy* stays the word for a module's upgrade policy, and *guideline* is not proposed, since
section 1 finds no record of that kind.
The glossary has **decision record**, **design**, **playbook** and **the record** (the records module). This
effort proposes, for a decision to settle through the glossary's own rules: **knowledge base** for the module
and its seat; **rule** for one statement a decision makes, with its own status; **governing record** for a kind
reviewed before it holds; and **note**, **post** and **drawing** for the light kinds. *Policy* stays the word
for a module's upgrade policy, and *guideline* is not proposed, since section 2 finds no record of that kind.