Agents work from hq's definitions and start from the knowledge base; every prepare and record gets the seams review (the operator, 2026-11-03)

2026-11-03 12:14:12 +01:00
parent 9a2d398070
commit 8420c6f236
11 changed files with 170 additions and 1 deletions
@@ -66,6 +66,15 @@ about an hour, and said to the operator if it runs past.

 ## Writing a decision record

+**Before a number: what holds, and the mesh path, reviewed.** Ask the knowledge base what is already decided in
+the record's area (`knowledge-base.ask`, `holds`), and name in the draft, for every interaction between modules the
+record decides, the seat and verb, event, provision, state on the bus or manifest field that carries it. Then
+`review-seams-and-tools` reviews the draft before it is proposed: a clause that has one module name another, read its
+internals or be special-cased in another part, or puts a module's name into shared code, is a finding (the operator,
+2026-11-03, after ADR 0594 and ADR 0598 named the bus in the shared contract and both were dropped the same morning).
+How it is checked: the record's References name the seams review's verdict; a record proposed without it is a breach
+the lead names.
+
 1. **Take a number.** `knowledge-base.reserve` with `kind: decision` and `for`: the record's title. The
   number comes from the issue tracker's counter and is spent whether or not the record is accepted; one
   never proposed is withdrawn after a week. Never pick a number by hand.
@@ -102,6 +102,24 @@ issue whether it is being fixed in between, after the delivery, or waits, and on

 ## Step 0 — Prepare (the lead, larger model)

+**Agents work from hq's definitions, never from a prompt written by hand.** Every agent the lead starts is one of
+`.claude/agents/`: `mesh-preparer` for this step, `mesh-developer` for step 1, `mesh-code-reviewer` for step 2,
+`mesh-watcher` for every wait, and the four reviewers by architectural domain and `research-reader` of playbook 01.
+The lead writes only the handover: what the agent works on (issue, records, branch, worktrees, commits) and where it
+reports. How it works, what it reads first and what it judges come from its definition; a lesson about how an agent
+works goes into its definition by an hq pull request (the operator, 2026-11-03: "please don't write prompts by hand,
+only the handover prompt"). How it is checked: the lead's report names each agent by its definition; an agent started
+from a prompt written by hand is a breach the lead names at the next report.
+
+**Every prepare starts from the knowledge base and maps every interaction onto a mesh path, and the seams review
+judges it before code starts.** The preparer lists the decisions in force for the change and the seat, verb, event,
+provision, state on the bus or manifest field that carries each interaction the change adds; then
+`review-seams-and-tools` reviews the prepare (and any decision record written for the change) before step 1. A module
+that names another, reads its internals or is special-cased in another part, or a module's name in shared code, is a
+finding of that review (the operator, 2026-11-03: "you never follow the mesh paths for inter-module communication").
+How it is checked: the milestone file carries the seams review's verdict on the prepare; a step 1 started without it
+is a breach the lead names.
+
 1. **Name the feature once:** `feat/<slug>`, the same branch name in every repository it touches (but see the
   exception for a new manifest word in phase 3: a release that must merge first has a name of its own). The
   branch is never protected. **One milestone is one branch per repository** (the operator, 2026-10-17), with one