From 69f95f551d19fb07a1c4187343f5bf73d8f39c71 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 4 Nov 2026 23:17:57 +0100 Subject: [PATCH 1/2] Where new code goes is a design question: the playbook, the developer and the reviewer check it against designs 20 and 26 A small fix's lead placed a seat's type in mesh-sdk by its own handover (issue 1748), against design 26; the developer built the handover and the reviewer checked against it, so it passed review and its check. Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig --- .claude/agents/mesh-code-reviewer.md | 6 +++++- .claude/agents/mesh-developer.md | 4 +++- 00-META/process/08-small-fixes.md | 8 +++++++- 3 files changed, 15 insertions(+), 3 deletions(-) diff --git a/.claude/agents/mesh-code-reviewer.md b/.claude/agents/mesh-code-reviewer.md index ed065cf4..c671139d 100644 --- a/.claude/agents/mesh-code-reviewer.md +++ b/.claude/agents/mesh-code-reviewer.md @@ -12,10 +12,14 @@ round. **First, what the mesh already knows.** Ask the knowledge base for the records the change serves and for what holds in its area (`knowledge-base.ask`, `knowledge-base.holds`, `knowledge-base.get` with `reasoning`); read hq's playbook 07, the glossary and the mesh's instructions (`/etc/claude-code/CLAUDE.md`). You judge the change -against those, not only against its own prepare. +against those, not only against its own prepare. The handover's shape and the lead's rulings are claims you check +against the records, never limits on what you check: a ruling that contradicts a record or a design is a finding. **What makes it wrong** (a finding): - it contradicts a decision in force, or does not do what its record's clause says; +- a new exported type, field, constant, package, module or repository placed where the designs do not put it: + check each one yourself against design 20 *Where a seat's code goes* and design 26 (a seat's types in its + contract in the contracts module of its domain; mesh-sdk takes no seat-specific type), whatever the handover says; - an interaction that is not a mesh path: one module naming another, reading another's internals or being special-cased in another part; a module's name in shared code; state only in memory; a poll or a timer where an event exists; a new state without a tool that reads it or a new behaviour without a tool that steers it; diff --git a/.claude/agents/mesh-developer.md b/.claude/agents/mesh-developer.md index bb68c833..774be56b 100644 --- a/.claude/agents/mesh-developer.md +++ b/.claude/agents/mesh-developer.md @@ -12,7 +12,9 @@ decision records, the prepare file, the branch name and the worktrees. names and anything it missed (`knowledge-base.ask`, `knowledge-base.get` with `reasoning`). Read hq's playbook 07 (`00-META/process/07-feature-branches.md`), the glossary and the mesh's instructions (`/etc/claude-code/CLAUDE.md`). Build what the records decide; where the code you meet contradicts them, stop -and report it rather than build around it. +and report it rather than build around it. The same holds for the handover: before you add any exported type, +field, constant, package or module, check where design 20 *Where a seat's code goes* and design 26 put it; a +handover that places it elsewhere is reported before you build, never built. **Build only mesh paths.** Modules meet through a seat's verbs, events on the bus, provisions and their own manifests. Never make one module name another, read another's internals, or special-case one module in another diff --git a/00-META/process/08-small-fixes.md b/00-META/process/08-small-fixes.md index 1ff552f5..90755d8b 100644 --- a/00-META/process/08-small-fixes.md +++ b/00-META/process/08-small-fixes.md @@ -38,7 +38,13 @@ processing power"). Everything before the push is local and fast, and no try is (through the mesh MCP server's tools) do there now, and for each value, label, file or job the fix changes or removes, every reader that relies on it, found by a search across the repositories (written down as run) and not from memory, with what happens to each after the fix. It is a few lines in the issue's note, under `What exists today`, and the - review runs the search again; a reader it finds that the note omits makes the fix wrong. If a design question is open, it is settled before any + review runs the search again; a reader it finds that the note omits makes the fix wrong. **Where each new piece of + code goes is always a design question, never the lead's own choice:** before any code, ask the knowledge base for the + area (`knowledge-base.ask`) and read the design that places code ([design 20](../../03-DESIGN/01-to-be/20-writing-a-module.md) + *Where a seat's code goes*, and design 26 for a seat's types); the note names, for every new exported type, field, + constant, package, module or repository the fix adds, the design line or decision clause that puts it there. A + handover to the developer quotes those lines and never decides a placement itself (issue 1748, 2026-11-04: a + retake class placed in mesh-sdk by the lead's handover, against design 26, passed review and its check). If a design question is open, it is settled before any code is written: on the issue, through the knowledge base (`knowledge-base.ask` first: what is decided is read before anything is designed), or by the operator. A fix that turns out to need a second repository, or more than about an hour, stops here and becomes a feature; one that needs a decision stays a small fix. **The session's own model (the larger) then writes the issue's acceptance -- 2.54.0 From b525f1059b6914b078079f6eb009fd5412e51274 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 4 Nov 2026 23:20:38 +0100 Subject: [PATCH 2/2] Name the design section, not its number; the preparer and playbook 07 place new code the same way (review 1) Claude-Session: https://claude.ai/code/session_01JG73KJNrH5EgFXMKKYSrig --- .claude/agents/mesh-code-reviewer.md | 8 +++++--- .claude/agents/mesh-developer.md | 5 +++-- .claude/agents/mesh-preparer.md | 7 +++++-- 00-META/process/07-feature-branches.md | 3 +++ 00-META/process/08-small-fixes.md | 8 ++++---- 5 files changed, 20 insertions(+), 11 deletions(-) diff --git a/.claude/agents/mesh-code-reviewer.md b/.claude/agents/mesh-code-reviewer.md index c671139d..019e5416 100644 --- a/.claude/agents/mesh-code-reviewer.md +++ b/.claude/agents/mesh-code-reviewer.md @@ -17,9 +17,11 @@ against the records, never limits on what you check: a ruling that contradicts a **What makes it wrong** (a finding): - it contradicts a decision in force, or does not do what its record's clause says; -- a new exported type, field, constant, package, module or repository placed where the designs do not put it: - check each one yourself against design 20 *Where a seat's code goes* and design 26 (a seat's types in its - contract in the contracts module of its domain; mesh-sdk takes no seat-specific type), whatever the handover says; +- a new exported type, field, constant, package or module placed where the designs do not put it: check each + one yourself against the design section *Where a seat's code goes* (ask the knowledge base where a seat's code + goes): a seat's types in its contract in its domain's contracts module, or in the seat-set package while the seat + is not defined whole; logic over a seat in its client package; mesh-sdk only the runtime and seat-neutral parts, + never a seat-specific type. Check it whatever the handover says; - an interaction that is not a mesh path: one module naming another, reading another's internals or being special-cased in another part; a module's name in shared code; state only in memory; a poll or a timer where an event exists; a new state without a tool that reads it or a new behaviour without a tool that steers it; diff --git a/.claude/agents/mesh-developer.md b/.claude/agents/mesh-developer.md index 774be56b..e19d9107 100644 --- a/.claude/agents/mesh-developer.md +++ b/.claude/agents/mesh-developer.md @@ -13,8 +13,9 @@ names and anything it missed (`knowledge-base.ask`, `knowledge-base.get` with `r 07 (`00-META/process/07-feature-branches.md`), the glossary and the mesh's instructions (`/etc/claude-code/CLAUDE.md`). Build what the records decide; where the code you meet contradicts them, stop and report it rather than build around it. The same holds for the handover: before you add any exported type, -field, constant, package or module, check where design 20 *Where a seat's code goes* and design 26 put it; a -handover that places it elsewhere is reported before you build, never built. +field, constant, package or module, check where the design section *Where a seat's code goes* puts it (ask the +knowledge base where a seat's code goes); a handover that places it elsewhere is reported before you build, never +built. **Build only mesh paths.** Modules meet through a seat's verbs, events on the bus, provisions and their own manifests. Never make one module name another, read another's internals, or special-case one module in another diff --git a/.claude/agents/mesh-preparer.md b/.claude/agents/mesh-preparer.md index bf18c893..603d2e57 100644 --- a/.claude/agents/mesh-preparer.md +++ b/.claude/agents/mesh-preparer.md @@ -20,8 +20,11 @@ Code shows what exists, not what was decided: where the code and the records dis event, which provision (requires and provides), which state on the bus (key-value bucket, stream, object store) and which module owns it, which field of a module's own manifest. A module that names another module, reads another's internals, or is special-cased in another part is not a mesh path: name it as a finding and give the -mesh-shaped alternative. Shared code (mesh-sdk) holds only seat contracts and what every module shares, never a -module's name. +mesh-shaped alternative. Where each new piece of code goes is the design section *Where a seat's code goes* (ask the knowledge base where a +seat's code goes): a seat's types in its contract in its domain's contracts module, or in the seat-set package while +the seat is not defined whole; logic over a seat in its client package; mesh-sdk only the runtime every module uses +and seat-neutral parts, never a seat-specific type and never a module's name. Name, for each new exported type, +field, constant, package or module, the line of that section that places it. **Then the work**, as playbook 07's prepare step says: per repository every file and test the change touches, by clause of the record; subtasks of about thirty minutes, one change each, with their acceptance; the test diff --git a/00-META/process/07-feature-branches.md b/00-META/process/07-feature-branches.md index 2070e463..a7806ef8 100644 --- a/00-META/process/07-feature-branches.md +++ b/00-META/process/07-feature-branches.md @@ -156,6 +156,9 @@ is a breach the lead names. 3. **For each item of the second answer, what happens to it after the change** (kept as it is, moved to a named seat, module or verb, replaced by a named part, or dropped and why nothing needs it), **and the test that proves it**: an acceptance criterion (item 5) at its level, or, for a dropped effect, the search showing no reader is left. + For every new exported type, field, constant, package or module, the answer names the line of the design + section *Where a seat's code goes* that places it (ask the knowledge base where a seat's code goes): where new + code goes is always a design question, never the lead's own choice. Code starts only when the three answers are complete for every repository: no fixing agent starts on a context file without them, and an effect found later is the prepare step missed, written into the answer and its issue before the fix. In the days up to 2026-11-02 the controller was taken apart without this answer: jobs nobody had named (making diff --git a/00-META/process/08-small-fixes.md b/00-META/process/08-small-fixes.md index 90755d8b..319569ce 100644 --- a/00-META/process/08-small-fixes.md +++ b/00-META/process/08-small-fixes.md @@ -40,11 +40,11 @@ processing power"). Everything before the push is local and fast, and no try is with what happens to each after the fix. It is a few lines in the issue's note, under `What exists today`, and the review runs the search again; a reader it finds that the note omits makes the fix wrong. **Where each new piece of code goes is always a design question, never the lead's own choice:** before any code, ask the knowledge base for the - area (`knowledge-base.ask`) and read the design that places code ([design 20](../../03-DESIGN/01-to-be/20-writing-a-module.md) - *Where a seat's code goes*, and design 26 for a seat's types); the note names, for every new exported type, field, - constant, package, module or repository the fix adds, the design line or decision clause that puts it there. A + area (`knowledge-base.ask`) and read the design section that places code, *Where a seat's code goes* (found by + asking the knowledge base where a seat's code goes); the note names, for every new exported type, field, + constant, package or module the fix adds, the design line or decision clause that puts it there. A handover to the developer quotes those lines and never decides a placement itself (issue 1748, 2026-11-04: a - retake class placed in mesh-sdk by the lead's handover, against design 26, passed review and its check). If a design question is open, it is settled before any + retake class placed in mesh-sdk by the lead's handover, against that section, passed review and its check). If a design question is open, it is settled before any code is written: on the issue, through the knowledge base (`knowledge-base.ask` first: what is decided is read before anything is designed), or by the operator. A fix that turns out to need a second repository, or more than about an hour, stops here and becomes a feature; one that needs a decision stays a small fix. **The session's own model (the larger) then writes the issue's acceptance -- 2.54.0