From 91ae2ddb0fcac61d258e87a46309e14851ca3ff5 Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 11 Oct 2026 00:41:59 +0200 Subject: [PATCH] Research 045: the store holds each record's structure and rules, hq its reasoning, and issues live whole in the tracker --- .../00-overview.md | 8 +- .../01-findings.md | 431 +++++++++--------- 2 files changed, 224 insertions(+), 215 deletions(-) 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 index 7e389819..41f7e46f 100644 --- 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 @@ -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. diff --git a/01-RESEARCH/045-a-knowledge-base-the-mesh-writes/01-findings.md b/01-RESEARCH/045-a-knowledge-base-the-mesh-writes/01-findings.md index 4ccd8d6f..a54e75e7 100644 --- a/01-RESEARCH/045-a-knowledge-base-the-mesh-writes/01-findings.md +++ b/01-RESEARCH/045-a-knowledge-base-the-mesh-writes/01-findings.md @@ -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.