From c77378fa19cc61d3f7da06a05126d59ddd00348e Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 11 Oct 2026 20:54:15 +0200 Subject: [PATCH 1/2] Say what the old 'knowledge base' meant, now that the word names the module (issue 430) The record and the records module for symptom search, the constitution page by its own name. --- 00-META/how-we-build.md | 6 +++--- 00-META/process/03-issues.md | 10 +++++----- 00-META/process/05-constitution-sync.md | 4 ++-- AGENTS.md | 4 ++-- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/00-META/how-we-build.md b/00-META/how-we-build.md index 6c105466..5224bfa7 100644 --- a/00-META/how-we-build.md +++ b/00-META/how-we-build.md @@ -1,7 +1,7 @@ --- status: canonical updated: 2026-08-23 -derives: knowledge-base constitution page +derives: the constitution page decisions: - "ADR 0020" --- @@ -198,8 +198,8 @@ declaration was never wrong. Nothing ever asked the system. ### Search the record before forming a hypothesis The first action on any error message, failing service or unexpected behaviour is to search the -operational memory for the literal error text — before a hypothesis, not after one fails. The -knowledge base is indexed on symptoms. +record for the literal error text (`records.records_search`) — before a hypothesis, not after one fails. +The record is indexed on symptoms. This fires hardest on *familiar* ground, where a confident trail feels like progress. Two entries were each rediscovered from scratch over several hours in a single session because the diff --git a/00-META/process/03-issues.md b/00-META/process/03-issues.md index 4760dcc3..d440628a 100644 --- a/00-META/process/03-issues.md +++ b/00-META/process/03-issues.md @@ -8,15 +8,15 @@ design permits. ## What belongs here, and what does not -| Belongs in `04-ISSUES` | Belongs in the knowledge base | +| Belongs in `04-ISSUES` | Belongs in the operational lessons | |---|---| | The design permits a failure to be silent | How to fix one occurrence of it | | A documented rule is enforced by nothing | A command that works around it | | A stated invariant is false in practice | A node-specific quirk | | The owning component is unknown and finding it needs the whole mesh in view | Symptom → fix, once the answer is known | -The knowledge base already holds the operational record and is indexed on symptoms. This -folder is not a second copy of it. An issue here is a question HQ must **answer**, not an +The operational lessons (symptom → fix) are found by their literal symptom text through the records +module (`records.records_search`). This folder is not a second copy of them. An issue here is a question HQ must **answer**, not an incident someone must **clear**. ## The issue tracker holds the number and the status @@ -109,8 +109,8 @@ import read, which every imported issue names (`imported.commit` in `issue-track - A number never moves. A folder carries the number the tracker gave; a folder whose number collides with another (one numbered before the tracker, or by hand) is a fault, and `cycle.py` refuses two records sharing a number. -- An issue whose answer is a general lesson should also be written to the knowledge base, so - the next person searching a symptom finds it. Both, not either. +- An issue whose answer is a general lesson also says that lesson in its resolution, in the symptom's + own words, so the next person searching that symptom finds it. Both, not either. - `wontfix` is legitimate and requires a sentence saying why; the tracker refuses it without one. - **An agent says when it starts work on an issue**, by moving it to `diagnosing` or `fixing` with `by`. Two agents never start the same work without knowing: the second is refused, naming the first. diff --git a/00-META/process/05-constitution-sync.md b/00-META/process/05-constitution-sync.md index cfa6a1e2..b28c33c3 100644 --- a/00-META/process/05-constitution-sync.md +++ b/00-META/process/05-constitution-sync.md @@ -1,7 +1,7 @@ # Playbook 05 — Constitution sync Implements ADR 0021: HQ is -the source of the constitution, and the knowledge-base page is derived, never edited. +the source of the constitution, and the constitution page is derived, never edited. **Trigger.** [`how-we-build.md`](../how-we-build.md) changed a rule that the mesh enforces at runtime. @@ -24,7 +24,7 @@ and, per the repository's own rule, it is how the rule "HQ is the source" is che the derived page carries the rule alone. 2. Record the change as a decision — a rule the mesh enforces is architecturally significant. Playbook [02](02-graduation.md). -3. Publish the derived page to the knowledge base under the constitution slug, replacing its +3. Publish the derived page where the mesh keeps the constitution page, under its slug, replacing its body. Keep the section numbering stable: the meeting orchestrator and the review fragments cite sections by number. 4. Verify the derived page reads back with the change present. A publish that reported success diff --git a/AGENTS.md b/AGENTS.md index 77615664..02174abb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -77,8 +77,8 @@ in running prose; a quotation keeps its words. that exists; [`03-DESIGN/01-to-be/`](03-DESIGN/01-to-be/) describes the one being built toward. Every design doc says which it is in `layer:`. A statement about the future does not belong in an as-is document, and an as-is document is never edited to describe an intention. -- **`00-META/how-we-build.md` is the source of the mesh constitution.** The knowledge-base - constitution page is derived from it — see playbook +- **`00-META/how-we-build.md` is the source of the mesh constitution.** The constitution page + is derived from it — see playbook [`05-constitution-sync.md`](00-META/process/05-constitution-sync.md). Never edit the derived page directly. From c9d7d03ab8d6d05d46a341dbb46f2ee5a9ee9754 Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 11 Oct 2026 21:07:32 +0200 Subject: [PATCH 2/2] Keep playbook 03's rule as it was, in plain words, and say how the record is searched (review of #318) --- 00-META/how-we-build.md | 4 ++-- 00-META/process/03-issues.md | 10 +++++----- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/00-META/how-we-build.md b/00-META/how-we-build.md index 5224bfa7..465b692c 100644 --- a/00-META/how-we-build.md +++ b/00-META/how-we-build.md @@ -1,6 +1,6 @@ --- status: canonical -updated: 2026-08-23 +updated: 2026-10-11 derives: the constitution page decisions: - "ADR 0020" @@ -199,7 +199,7 @@ declaration was never wrong. Nothing ever asked the system. The first action on any error message, failing service or unexpected behaviour is to search the record for the literal error text (`records.records_search`) — before a hypothesis, not after one fails. -The record is indexed on symptoms. +The search matches the words as written, so search with the error's own words. This fires hardest on *familiar* ground, where a confident trail feels like progress. Two entries were each rediscovered from scratch over several hours in a single session because the diff --git a/00-META/process/03-issues.md b/00-META/process/03-issues.md index d440628a..1802dc39 100644 --- a/00-META/process/03-issues.md +++ b/00-META/process/03-issues.md @@ -8,15 +8,15 @@ design permits. ## What belongs here, and what does not -| Belongs in `04-ISSUES` | Belongs in the operational lessons | +| Belongs in `04-ISSUES` | Belongs with the fix's own lesson, not here | |---|---| | The design permits a failure to be silent | How to fix one occurrence of it | | A documented rule is enforced by nothing | A command that works around it | | A stated invariant is false in practice | A node-specific quirk | | The owning component is unknown and finding it needs the whole mesh in view | Symptom → fix, once the answer is known | -The operational lessons (symptom → fix) are found by their literal symptom text through the records -module (`records.records_search`). This folder is not a second copy of them. An issue here is a question HQ must **answer**, not an +A fix's lesson (symptom → fix) is written where a search by the symptom's literal words finds it +(`records.records_search`). This folder is not a second copy of it. An issue here is a question HQ must **answer**, not an incident someone must **clear**. ## The issue tracker holds the number and the status @@ -109,8 +109,8 @@ import read, which every imported issue names (`imported.commit` in `issue-track - A number never moves. A folder carries the number the tracker gave; a folder whose number collides with another (one numbered before the tracker, or by hand) is a fault, and `cycle.py` refuses two records sharing a number. -- An issue whose answer is a general lesson also says that lesson in its resolution, in the symptom's - own words, so the next person searching that symptom finds it. Both, not either. +- An issue whose answer is a general lesson should also have that lesson written where a search by + the symptom's literal words finds it, so the next person searching it finds it. Both, not either. - `wontfix` is legitimate and requires a sentence saying why; the tracker refuses it without one. - **An agent says when it starts work on an issue**, by moving it to `diagnosing` or `fixing` with `by`. Two agents never start the same work without knowing: the second is refused, naming the first.