Merge pull request 'ADR 0290: the knowledge base reviews a proposal itself' (#311) from decisions/0290-the-knowledge-base-reviews-itself into main
This commit was merged in pull request #311.
This commit is contained in:
+24
-9
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user