From d5eaba1359880bcd3a86f660b76030660ac9927b Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 11 Oct 2026 11:20:55 +0200 Subject: [PATCH] ADR 0290: the knowledge base reviews a proposal itself, through a fresh judgement, since the mesh proves machines and not agents --- ...e-in-the-knowledge-base-made-of-clauses.md | 33 ++++++++++++++----- 03-DESIGN/01-to-be/55-the-knowledge-base.md | 27 ++++++++------- 03-DESIGN/01-to-be/README.md | 2 +- 3 files changed, 41 insertions(+), 21 deletions(-) diff --git a/02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md b/02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md index 11393a8b..32cf55a7 100644 --- a/02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md +++ b/02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md @@ -19,6 +19,12 @@ extends: 02-DECISIONS/0153-the-record-is-read-by-a-module-and-the-console-lists- > public copy of accepted decision records and research efforts (issue 435). The operator answered: no copy is needed. Rule 9 and the consequences > say so. +> **Updated — 2026-10-11, after the operator's direction.** Rule 4 had an independent agent review a proposal through the +> `review` verb. The mesh proves which machine called a module, not which agent on it (issue 365), so an agent on +> the author's machine looks like the author; and the operator put any design for agents after a vendor-neutral +> inference layer. Following that, the knowledge base now reviews a proposal itself, through a fresh judgement. Option 3 of +> *How a record is reviewed*, rule 4, rule 6 and the consequences say so. + ## Context [Research 045](../01-RESEARCH/045-a-knowledge-base-the-mesh-writes/00-overview.md) measured, on 2026-10-11, how an @@ -79,9 +85,14 @@ rule 8 already decided that the issue tracker hands out decision and research nu 1. **The operator approves every record.** Rejected: records are reviewed today by an independent agent, and the operator is asked only for real decisions; making every record wait for one person slows what works. -2. **An independent agent reviews it, the write-time checks pass, and a record that needs the operator waits for the - operator's Approve on a channel that proves who answered.** Adopted. It is how a pull request here is merged - today, and the operator's Approve already reaches the mesh that way +2. **An independent agent reviews it through a `review` verb.** Rejected on 2026-10-11: the mesh proves which machine + called, not which agent, so a reviewer on the author's machine is refused as the author; proving each agent needs a + design for agents, which the operator puts after a vendor-neutral inference layer. +3. **The knowledge base reviews a proposal itself, through a fresh judgement that sees only the record and the rules, + and a record that needs the operator waits for the operator's Approve on a channel that proves who answered.** + Adopted. It is how the issue tracker's triage judges an issue + ([ADR 0279](0279-the-issue-tracker-triages-every-new-issue-and-an-issue-is-ready-when-what-it-depends-on-is-delivered.md)), + it needs no identity for agents, and the operator's Approve already reaches the mesh that way ([ADR 0274](0274-an-agent-proposes-a-shared-instruction-section-and-every-node-takes-it-only-on-the-operators-warrant-which-it-proves-itself.md)). ### Who confirms the clauses drafted for the 226 prose decisions (the research's open question 1) @@ -110,9 +121,13 @@ rule 8 already decided that the issue tracker hands out decision and research nu takes writes, a record written in this repository from 2026-10-11 on writes its `Decision` section as numbered clauses with a bold lead, and `records.py` refuses an accepted one that does not. 4. **A record is proposed, reviewed and accepted in the knowledge base.** `propose` writes it with a number from - `reserve`, and refuses it outright when one of the 29 rules that judge one record or its prose fails. An - independent agent reviews it (`review`), and its approval moves the record and its clauses to `accepted` and - `in force`, and every clause it changes or supersedes accordingly. A record that says it needs the operator waits + `reserve`, and refuses it outright when one of the 29 rules that judge one record or its prose fails. The + knowledge base then reviews it itself: a judgement in a separate call, with no tools, that sees only the record, + the records it links and the rules, and answers approve or changes with its findings + ([ADR 0278](0278-the-issue-tracker-checks-every-new-issue-for-a-duplicate-through-a-judgement-the-agent-makes-without-tools.md)). + The judgement goes through the agent module's judge today and through the mesh's inference layer once one + exists. On changes the record stays proposed with the findings, and its author revises it. Its approval moves the + record and its clauses to `accepted` and `in force`, and every clause it changes or supersedes accordingly. A record that says it needs the operator waits for the operator's Approve, asked on a channel that proves who answered, and the warrant is kept with it ([ADR 0259](0259-an-ask-is-a-message-on-the-bus-any-channel-answers-it-and-the-asker-acts-on-a-warrant.md)). An accepted record changes only by a new record, or by a dated correction of a fact, written as a new version and marked as one; @@ -125,7 +140,7 @@ rule 8 already decided that the issue tracker hands out decision and research nu 6. **An answer is the shape agents need, bounded.** The verbs are `ask` (records and clauses bearing on a question, ranked, each saying whether it holds or what changed it), `get` (one record: clauses, links both ways, what changed it since; its reasoning only when asked), `holds` (the clauses in force for a topic or a record), `links`, - `history` (a record's versions and the difference between two), `reserve`, `propose`, `review`, `import` and + `history` (a record's versions and the difference between two), `reserve`, `propose`, `import` and `return` (send drafted clauses back to be drafted again). `ask`, `get` and `holds` stay under a size bound they state; the default is 4 KiB. 7. **State is in a database in the store**, provided to the module, not in buckets: `ask` needs ranked full-text @@ -159,8 +174,8 @@ rule 8 already decided that the issue tracker hands out decision and research nu read or write a decision. - A later record that changes one statement of an older one says which, and the older clause's status changes when the later record is accepted. -- Review moves from a pull request to the knowledge base's `review`, and the forge's line comments and diff are - replaced by the record's versions and `history`. A record is checked when it is written, not when it is merged. +- Review moves from a pull request to the knowledge base's own judgement, and the forge's line comments and diff are + replaced by the record's versions, the judgement's findings and `history`. A record is checked when it is written, not when it is merged. - Until the first slice takes writes, records are still written here as pull requests, with numbered clauses, and the import takes them in with the rest. - What got harder: one more module the mesh's own process depends on. Reading or writing a decision needs the mesh to diff --git a/03-DESIGN/01-to-be/55-the-knowledge-base.md b/03-DESIGN/01-to-be/55-the-knowledge-base.md index 85520f5f..283c4523 100644 --- a/03-DESIGN/01-to-be/55-the-knowledge-base.md +++ b/03-DESIGN/01-to-be/55-the-knowledge-base.md @@ -12,7 +12,7 @@ decisions: **The mesh keeps its decision records and research efforts whole in a module of its own, `mesh-knowledge`, one instance on the control-node, holding the seat `knowledge-base`: each record's number, status, topic, typed links, its clauses with their own status, and its reasoning, with every version kept. A record is proposed, checked when it -is written, reviewed by an independent agent and accepted there; the operator's Approve is asked when a record needs +is written, reviewed by the knowledge base's own judgement and accepted there; the operator's Approve is asked when a record needs it. Agents ask what holds, and why, in one bounded call.** ([ADR 0290](../../02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md), from [research 045](../../01-RESEARCH/045-a-knowledge-base-the-mesh-writes/00-overview.md).) @@ -35,13 +35,13 @@ This document designs the first slice in detail, tracked by issue 425. The slice mesh-knowledge (seat knowledge-base, held once for the mesh) ├ its process, launched by the node runtime ├ a database in the store records, versions, clauses, links; ranked full-text search - ├ verbs ask, get, holds, links, history, reserve, propose, review, import, return + ├ verbs ask, get, holds, links, history, reserve, propose, import, return │ served by the control-node's tool runner ├ events proposed, reviewed, accepted, changed, imported, drafted, confirmed, returned └ consumes the router's warrants: the operator's Approve for a record that needs it (§ 5) mesh-issues (control-node) the counters for decision and research numbers (§ 6) - claude-code (same node) claude_code_judge: draft and confirm clauses (§ 7) + claude-code (same node) claude_code_judge: review a proposal (§ 5), draft and confirm clauses (§ 7) records (any node) records_read at a commit: the import's source (§ 8) messenger (control-node) the router: the operator's ask and its warrant @@ -102,14 +102,19 @@ its links, and for each `changes` the clauses it changes. It is refused, with ev - a research effort graduates without naming what it became; - its text uses a retired word of the glossary, or a daemon's command line. -A proposed record can be revised by its author as new versions until it is reviewed. Nothing proposed is ever served +A proposed record can be revised by its author as new versions until it is accepted. Nothing proposed is ever served as in force. ## 5. Review and acceptance -`review` is called by an agent that did not write the record, with a verdict, `approve` or `changes`, and its -findings. The knowledge base refuses a review by the record's author. On `changes`, the record stays proposed and the -findings are kept with it. On `approve`: +When `propose` takes a record (or a new version of a proposed one), the knowledge base reviews it itself: it asks for +a judgement in a separate call, with no tools, that sees only the record, the records it links and the rules, and +answers `approve` or `changes` with its findings, the way the issue tracker's triage judges an issue. The judgement +goes through the agent module's judge (`claude_code_judge`) today, and through the mesh's inference layer once one +exists; nothing in this design depends on which. On `changes`, the record stays proposed, the findings are kept with +that version, and its author revises it with a new version, which is reviewed again. A judgement that cannot be had +(the judge unreachable, or its answer unreadable) leaves the record proposed and says so; it is never taken as an +approval. On `approve`: 1. a record that does not need the operator is accepted at once; 2. a record whose author marked it `needs operator` gets an ask on the router with Approve and Decline, shown on a @@ -122,7 +127,7 @@ rules that judge the whole record set run (an accepted decision cited by nothing condition naming the rule and the records, and does not undo the acceptance. An accepted record is changed only by a new record, or by a progressive insight: a new version marked as one, which -goes through `review` like a proposal. +is reviewed like a proposal. ## 6. Numbers @@ -155,7 +160,7 @@ field by field and section by section, and the result is written on issue 426. | Slice | Delivers | Done when the operator sees | Tracked by | |---|---|---|---| -| 1 | this document: the module, the import, clauses, answers, `propose`, `review` and acceptance | the acceptance sentence above, live, and a record proposed, reviewed and accepted without a pull request | issue 425 | +| 1 | this document: the module, the import, clauses, answers, `propose`, its own review and acceptance | the acceptance sentence above, live, and a record proposed, reviewed and accepted without a pull request | issue 425 | | 2 | the decision records and research efforts leave this repository; path mentions become "ADR NNNN" and "research NNN"; playbooks 01 and 02 changed | this repository holds no decision record, and `get` answers every one | issue 426 | | 3 | designs, playbooks and glossary entries as kinds | `holds` answers for a design's decisions and a glossary word | issue 428 | | 4 | meeting notes, drawings and blog posts | not decided; needs its own decision | issue 429 | @@ -168,7 +173,7 @@ repository keeps no copy of the records, generated or otherwise (issue 435, answ | Rule | Checked by | |---|---| | A proposal that breaks a per-record rule is refused, naming every reason | the module's table test, one case per rule of § 4 | -| A record is accepted only after a review by someone else, and, when it needs the operator, only on the warrant | the module's tests: a review by the author refused; a `needs operator` record unaccepted without the warrant, accepted with it | +| A record is accepted only after the knowledge base's own judgement approves it, and, when it needs the operator, only on the warrant | the module's tests: a proposal whose judgement answers changes, or cannot be had, stays proposed; a `needs operator` record unaccepted without the warrant, accepted with it | | A whole-set rule that fails is loud | the module's test: an acceptance that leaves a decision cited by nothing raises the condition | | Every version is kept and comparable | the module's test: three versions, `history` lists them, the difference of the first and third is exact | | The import changes nothing on a second run, and loses nothing | the module's test over a fixture repository; and the comparison of § 8 on issue 426 | @@ -179,5 +184,5 @@ repository keeps no copy of the records, generated or otherwise (issue 435, answ ## What it leaves out -Semantic or vector search; a browser view; line comments on a proposal (a review's findings name the section and +Semantic or vector search; a browser view; line comments on a proposal (the judgement's findings name the section and clause instead); and the rules of how-we-build, which are not decision records. Each needs a decision of its own. diff --git a/03-DESIGN/01-to-be/README.md b/03-DESIGN/01-to-be/README.md index 29e23d75..5a0e42e9 100644 --- a/03-DESIGN/01-to-be/README.md +++ b/03-DESIGN/01-to-be/README.md @@ -54,7 +54,7 @@ document is written and this one's status becomes `implemented`. | [`52-shares-and-mounts.md`](52-shares-and-mounts.md) | **In progress.** A node shares one folder at a time through `nfs-server`, which provides it as a provision to the private network only, mapping every client to the folder's owner; a node that asks mounts it through `mounts`, a mount unit and an automount per share, so nothing mounts or fails at boot; a device that comes and goes is an occasional source whose absence is a state | [ADR 0263](../../02-DECISIONS/0263-a-share-is-a-provision-a-node-mounts-it-on-demand-and-only-nodes-that-ask-get-it.md), [ADR 0051](../../02-DECISIONS/0051-shared-data-is-the-operators.md), [ADR 0092](../../02-DECISIONS/0092-an-operator-delivers-a-pair-credential.md) | | [`53-the-issue-tracker.md`](53-the-issue-tracker.md) | **Designed.** The mesh keeps its issues in one module, `issues`, on the control-node: every number from one counter advanced by compare-and-set, the cycle's issue rules refused at the write, an event per change; an issue lives whole in the tracker, hq keeping no issue content ([ADR 0291](../../02-DECISIONS/0291-an-issue-lives-whole-in-the-issue-tracker.md)) | [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), [ADR 0291](../../02-DECISIONS/0291-an-issue-lives-whole-in-the-issue-tracker.md) | | [`54-the-controllers-records-on-the-bus.md`](54-the-controllers-records-on-the-bus.md) | **Designed.** The controller keeps five record mirrors on the bus (nodes, assignments, walks, builds, settings): each a bucket written from its store only when the record changed, with one event per write, and audited against the store every self-check run, a difference raised as `mirror-drifted` before the healer H6 repairs it | [ADR 0289](../../02-DECISIONS/0289-the-controller-mirrors-its-records-into-buckets-written-only-on-a-change-and-audited-against-its-store.md) | -| [`55-the-knowledge-base.md`](55-the-knowledge-base.md) | **Designed.** The mesh keeps its decision records and research efforts whole in one module, `mesh-knowledge`, on the control-node: number, status, topic, typed links both ways, each decision's clauses with their own status, and the reasoning, with every version; a record is proposed, checked at the write, reviewed by an independent agent and accepted there, with the operator's Approve when it needs it; agents ask what holds in one bounded call | [ADR 0290](../../02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md) | +| [`55-the-knowledge-base.md`](55-the-knowledge-base.md) | **Designed.** The mesh keeps its decision records and research efforts whole in one module, `mesh-knowledge`, on the control-node: number, status, topic, typed links both ways, each decision's clauses with their own status, and the reasoning, with every version; a record is proposed, checked at the write, reviewed by the knowledge base's own judgement and accepted there, with the operator's Approve when it needs it; agents ask what holds in one bounded call | [ADR 0290](../../02-DECISIONS/0290-a-decision-record-lives-whole-in-the-knowledge-base-made-of-clauses.md) | ## Not yet written