Where new code goes is a design question: playbook 08, the developer and the code reviewer check it against designs 20 and 26 #515

Merged
mesh-tools merged 2 commits from docs/placement-is-a-design-question into main 2026-11-04 22:23:45 +00:00
5 changed files with 26 additions and 5 deletions
+7 -1
View File
@@ -12,10 +12,16 @@ 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 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;
+4 -1
View File
@@ -12,7 +12,10 @@ 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 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
+5 -2
View File
@@ -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
+3
View File
@@ -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
+7 -1
View File
@@ -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 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 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