From 69f95f551d19fb07a1c4187343f5bf73d8f39c71 Mon Sep 17 00:00:00 2001 From: jochen Date: Wed, 4 Nov 2026 23:17:57 +0100 Subject: [PATCH] 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