Merge pull request 'Playbooks 07 and 08: every review asks where each piece of state lives and whether a repository holds mesh setup' (#493) from pb/state-and-seams into main

2026-10-28 16:46:35 +00:00
parent 02a18c9aa8 a9830f5110
commit 292232dad2
3 changed files with 15 additions and 2 deletions
@@ -289,6 +289,17 @@ issue whether it is being fixed in between, after the delivery, or waits, and on
   its shape, fixes every hit in one change and lists each file and line in the report. How it is checked: a
   report to the second round naming a kind and one place only, followed by a third round on the same kind, is
   this rule skipped.
+10. **The reviewer asks two questions of every change and every design, and answers both in its report** (the
+    operator, 2026-10-28: "design everything NATS-native"; "repositories are fully mesh agnostic"). The first:
+    *where does each piece of state live, and how does each seam (an integration, data, a part talking to
+    another) travel?* Anything that is not bus state, a stream or a seat's verb on the bus is a finding, even when
+    an accepted record put it there. The second: *does a repository hold anything about this mesh's setup, such as
+    node names, node-specific placement or settings?* That is a finding: repositories are mesh-agnostic. On
+    2026-10-28 a placement design kept placement in repository files with node names, because the accepted record
+    it followed said so and nobody checked it against these two principles. A finding from either question makes
+    the change wrong, whatever record it follows; the reviewer names the record so it can be superseded. How it is
+    checked: the review report has a line for each question with its answer, and the lead reads both before the
+    push; a report without them is not an approval.

 ## Step 3 — Check (no review)

@@ -60,7 +60,7 @@ processing power"). Everything before the push is local and fast, and no try is
 4. **One review of the local commit** (a reviewer that did not write it, larger
   model; at most 3 rounds, as playbook 07; from round 2 only what is wrong; it reads each acceptance criterion
   against its test, as playbook 07 step 2 item 6; a finding outside the issue's done-when and its acceptance
-   criteria is opened as an issue of its own, never asked as a change; it judges the integration tests by reading them against the code, as playbook 07 step 2 item 4 says). The reviewer's findings go back to the same agent that wrote the fix, continued by
+   criteria is opened as an issue of its own, never asked as a change; it judges the integration tests by reading them against the code, as playbook 07 step 2 item 4 says; it answers playbook 07 step 2 item 10's two questions, on state and seams and on mesh-agnostic repositories, in its report). The reviewer's findings go back to the same agent that wrote the fix, continued by
   its id, so the fix keeps its context. A playbook or design edit of a few lines may skip the reviewer: the
   operator's Approve of its merge is its review, and the review record says so.
 5. **Push the reviewed head once and open the pull request, only after the review approves.** The trunk is what runs and nothing holds merged work back
@@ -355,6 +355,8 @@ code{font:12.5px ui-monospace,monospace;background:var(--soft);padding:1px 5px;b
    <li>Every criterion against its test: a test at its level that would fail without the change.</li>
    <li>Every new integration test traced through the code by reading it: no run exists before the check.</li>
    <li>That each integration test enters by the path the live trigger takes.</li>
+    <li>Where each piece of state lives and how each seam travels: anything but bus state, a stream or a seat's verb is a finding, even if a record put it there.</li>
+    <li>That no repository holds this mesh's setup (node names, placement, settings): repositories are mesh-agnostic.</li>
  </ul>
  <div class="note" style="margin-top:10px">Why reviews took more than one round (R3b, 2026-10-19): a test that "failed" only by not compiling, a reader of the changed record the survey missed, and bus tests judged by reasoning before they ran. ADR 0548 and playbook 07 step 2 item 4 change the last: bus tests are judged by reading them against the code, and the one check runs them after the review.</div>
 </div>
@@ -461,7 +463,7 @@ const P = [
 {n:"07",name:"Features",kind:"build",c:"--build",
  trig:"Work that changes code across issues or repositories, too large for a small fix.",
  who:"A lead (larger model), one fixing agent per repository (smaller), one reviewer (larger).",
-  steps:["Prepare: name the branch, make the worktrees, settle every question.","Write one context file per repository.","Write the findings and acceptance criteria into each issue.","Survey every other reader and writer of each changed value. (new)","Answer three questions in the milestone file: who deletes each new key and stream, how the switch-over is tried on one node first, what the one check does not cover. The review checks them. (new)","List every part the change reaches; copy fixtures from the real writer.","Develop: one agent per repository, one commit per issue.","A test fails first on behaviour, not on compiling. (new)","Bring each branch up to the trunk; nothing is pushed, no try runs. (new)","Review all of it, reading the integration tests against the code; at most 3 rounds.","A group pins the group's own mesh-sdk head in every member. (new)","Push the reviewed heads once and read each forge head against the reviewed commit; no draft pull request, no fix round on an open one. (new)","Open one pull request per repository, together, with Reviewed-by and Pushed-by; the one check runs. A failed check is read, fixed, reviewed, pushed once more. (new)","The operator's Approve on Telegram; the group merges in one pass.","Follow the delivery in the status view (moving, settled, stuck, delivered) to done; resolve the issues; clean up. (new)","When the builder cannot deliver its own fix: revert, a build by a session's call, a registration at the terminal, copies kept outside the store; a broken controller is put back by a want the operator writes, a hand build by mesh-hand-compose and a want. (new)"],
+  steps:["Prepare: name the branch, make the worktrees, settle every question.","Write one context file per repository.","Write the findings and acceptance criteria into each issue.","Survey every other reader and writer of each changed value. (new)","Answer three questions in the milestone file: who deletes each new key and stream, how the switch-over is tried on one node first, what the one check does not cover. The review checks them. (new)","List every part the change reaches; copy fixtures from the real writer.","Develop: one agent per repository, one commit per issue.","A test fails first on behaviour, not on compiling. (new)","Bring each branch up to the trunk; nothing is pushed, no try runs. (new)","Review all of it, reading the integration tests against the code; at most 3 rounds; the report answers the state-and-seams and mesh-agnostic questions. (new)","A group pins the group's own mesh-sdk head in every member. (new)","Push the reviewed heads once and read each forge head against the reviewed commit; no draft pull request, no fix round on an open one. (new)","Open one pull request per repository, together, with Reviewed-by and Pushed-by; the one check runs. A failed check is read, fixed, reviewed, pushed once more. (new)","The operator's Approve on Telegram; the group merges in one pass.","Follow the delivery in the status view (moving, settled, stuck, delivered) to done; resolve the issues; clean up. (new)","When the builder cannot deliver its own fix: revert, a build by a session's call, a registration at the terminal, copies kept outside the store; a broken controller is put back by a want the operator writes, a hand build by mesh-hand-compose and a want. (new)"],
  prod:"One pull request per repository, one source revision delivered, resolved issues, no branch or worktree left.",
  next:"02 (when it ships)",bounds:"Prepare 15 min · 30 min per issue · review 15 min, ≤ 3 rounds · one check, pushed once",
  prev:["Pull requests as scratchpads","Context bought again and again","Review rounds spent on what a run would show","A node agent's bus reads, proven only by review"],