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.