Bound parallel shards to one verifier pass (policy-rev 5, v3.1.1)

.github/workflows/validate.yml

@@ -47,7 +47,7 @@ jobs:
           grep -qE '^[[:space:]]*author:' "$S" || { echo "::error::frontmatter author missing"; exit 1; }
           [ "$(grep -cx -- '<!-- stackwich:v1 -->' "$S")" -eq 1 ] || { echo "::error::SKILL.md must contain exactly one whole-line opening marker"; exit 1; }
           [ "$(grep -cx -- '<!-- /stackwich:v1 -->' "$S")" -eq 1 ] || { echo "::error::SKILL.md must contain exactly one whole-line closing marker"; exit 1; }
-          [ "$(grep -cx -- '<!-- policy-rev: 4 -->' "$S")" -eq 1 ] || { echo "::error::SKILL.md must contain exactly one whole-line policy-rev: 4 comment"; exit 1; }
+          [ "$(grep -cx -- '<!-- policy-rev: 5 -->' "$S")" -eq 1 ] || { echo "::error::SKILL.md must contain exactly one whole-line policy-rev: 5 comment"; exit 1; }
           for h in Prompt Context Harness Loop Graph; do
             awk '/^<!-- stackwich:v1 -->$/,/^<!-- \/stackwich:v1 -->$/' "$S" | grep -q "^### $h" || { echo "::error::policy block missing the $h layer"; exit 1; }
           done

CHANGELOG.md

@@ -3,6 +3,43 @@
 Headings are `## <repo version> — <what moved>`. Ports are named in the body with their own rev
 counters: a port tracks the parent's layer structure, not its revision number.
 
+## 3.1.1 — policy-rev 5: parallel shards fit one verifier pass
+
+The policy block changes, so `policy-rev` moves from 4 to 5 and existing installs should
+re-apply it. The `<!-- stackwich:v1 -->` marker is unchanged.
+
+### What was wrong
+3.1.0 sized each delegation to what `verifier` and the reviewer can check in one pass, but the
+Graph rule still fanned every parallel shard into a single `verifier` pass. Each shard could fit
+one pass while the combined diff needed several — the review overload 3.1.0 set out to prevent.
+Codex's automated review of the 3.1.0 pull request found it.
+
+### Policy block
+- **Graph:** "Before launching, state the shard count and why that many." becomes "Launch only as
+  many shards as that pass and the reviewer can check; state the count and why." The shards
+  launched together now fit the one `verifier` pass they fan into, and remaining work runs as
+  sequential gated batches, as the Harness rule already required. There is still no numeric cap.
+- No other bullet changed; the block is the same length.
+
+### Why not gate each shard separately
+Parallel shards write to the same working tree, so a `verifier` run on one shard would test and
+scope-check a tree still holding the other shards' unfinished edits. One pass over the combined
+result avoids that and is also the check that sees breaks between shards.
+
+### Upgrading
+Update the plugin, then re-run `/stackwich:stackwich`. It shows your installed `policy-rev: 4`
+and replaces the block in place once you confirm. The agents are unchanged — nothing to
+re-scaffold.
+
+### Ports
+Unchanged at `stackwich-grok-rev 2` and `stackwich-codex-rev 2`. Neither port fans parallel work
+into a single verification pass, so neither had this conflict.
+
+### Repo
+- CI asserts `policy-rev: 5`.
+- `evals/evals.json`: cases 1 and 2 expect `policy-rev 5`; case 7 now checks that the shards
+  launched together fit one `verifier` pass.
+
 ## 3.1.0 — policy-rev 4: every efficiency gets a ceiling
 
 The policy block changes, so this is a real upgrade: `policy-rev` moves from 3 to 4. The

README.md

@@ -58,7 +58,7 @@ The skill does the rest interactively: asks for scope, writes the policy, offers
 
 ### Upgrading from 2.x
 
-**The move itself changes nothing about your policy.** 3.0 left your `CLAUDE.md` block at `policy-rev 3` and your `advisor`, `executor` and `verifier` untouched — only the delivery mechanism moved. 3.1.0 is a separate policy upgrade to `policy-rev 4`; see [CHANGELOG](CHANGELOG.md), and re-run `/stackwich:stackwich` to apply it in place.
+**The move itself changes nothing about your policy.** 3.0 left your `CLAUDE.md` block at `policy-rev 3` and your `advisor`, `executor` and `verifier` untouched — only the delivery mechanism moved. Releases from 3.1.0 on do change the policy; see [CHANGELOG](CHANGELOG.md), and re-run `/stackwich:stackwich` to apply the current revision in place.
 
 Before 3.0, Stackwich was installed by cloning this repo into a skills directory. Install the plugin above, then remove the old clone — leaving it in place gives you two skills both named `stackwich`:
 

evals/evals.json

@@ -5,7 +5,7 @@
       "id": 1,
       "name": "fresh-user-level-install",
       "prompt": "Set up the Stackwich architecture on this machine at the user level, including the subagents.",
-      "expected_output": "~/.claude/CLAUDE.md created with exactly one stackwich:v1 marker pair and policy-rev 4; advisor.md, executor.md, verifier.md written to ~/.claude/agents/ with valid frontmatter; step 4 verification results reported explicitly.",
+      "expected_output": "~/.claude/CLAUDE.md created with exactly one stackwich:v1 marker pair and policy-rev 5; advisor.md, executor.md, verifier.md written to ~/.claude/agents/ with valid frontmatter; step 4 verification results reported explicitly.",
       "assertions": [
         "CLAUDE.md contains exactly one opening and one closing marker",
         "policy-rev line is present inside the block",
@@ -19,12 +19,12 @@
       "id": 2,
       "name": "update-existing-v1-install",
       "prompt": "I already have Stackwich installed from a while back — can you bring it up to date?",
-      "expected_output": "Existing block located via the opening marker, shown to the user with its declared policy-rev, replaced in place after confirmation with the policy-rev 4 block. No duplicate section appended.",
+      "expected_output": "Existing block located via the opening marker, shown to the user with its declared policy-rev, replaced in place after confirmation with the policy-rev 5 block. No duplicate section appended.",
       "assertions": [
         "existing block is shown to the user before modification",
         "user is asked before replacing",
         "final file contains exactly one marker pair",
-        "final block declares policy-rev 4 and no older policy-rev line remains"
+        "final block declares policy-rev 5 and no older policy-rev line remains"
       ],
       "files": []
     },
@@ -82,10 +82,10 @@
       "id": 7,
       "name": "large-parallel-batch",
       "prompt": "Migrate these 40 independent modules to the new logger as fast as possible.",
-      "expected_output": "The agent states how many parallel executor runs it will launch and why that many, sizes each batch so the verifier can check it in one pass, and when reporting done gives the number of delegations and runs used, with token or cost figures only if the environment showed them.",
+      "expected_output": "The agent states how many parallel executor runs it will launch and why that many, launches only as many shards as one verifier pass can check together, runs any remainder as a later gated batch, and when reporting done gives the number of delegations and runs used, with token or cost figures only if the environment showed them.",
       "assertions": [
         "the number of parallel executor runs is stated with a reason before launch",
-        "each batch is sized for a single verifier pass",
+        "the shards launched together fit one verifier pass; any remainder runs as a later gated batch",
         "the done report counts delegations, forks, and loop runs",
         "no token or cost figure is reported that the environment did not show"
       ],

plugins/stackwich/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "stackwich",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "Delivery discipline for AI coding agents. Writes the five-layer Stackwich policy (Prompt / Context / Harness / Loop / Graph) into CLAUDE.md and scaffolds advisor, executor and verifier subagents.",
   "author": { "name": "Abhirup Banerjee" },
   "homepage": "https://github.com/ovhirup/stackwich",

plugins/stackwich/skills/stackwich/SKILL.md

@@ -3,8 +3,8 @@ name: stackwich
 description: Installs the Stackwich architecture — meta-prompt delegation, a plan/execute/verify/review sandwich, loop-by-default for recurring work, and fork-based context engineering — into any Claude Code setup. Writes the operating policy into CLAUDE.md and optionally scaffolds three companion subagents (advisor/executor/verifier). Use this whenever the user wants to adopt, install, bootstrap, upgrade, or re-apply this delegation architecture on a new machine, project, or someone else's setup — and also when they ask more loosely for help making their Claude Code setup more disciplined, setting up planner/executor/reviewer subagents, adding a review gate before risky changes, enforcing cheap-model tiering, or fixing agents that make sloppy or out-of-scope edits. Also use it when the user asks why agent usage or cost keeps climbing despite cheaper models, or whether a loop or more parallel agents will actually save effort.
 metadata:
   author: Abhirup Banerjee (@ovhirup)
-  version: 3.1.0
-  policy-rev: 4
+  version: 3.1.1
+  policy-rev: 5
 ---
 
 # Stackwich — install the Stackwich architecture
@@ -59,7 +59,7 @@ substitute consistently everywhere they appear.
 
 ```markdown
 <!-- stackwich:v1 -->
-<!-- policy-rev: 4 -->
+<!-- policy-rev: 5 -->
 ## Working Architecture (Stackwich)
 
 ### Prompt
@@ -116,7 +116,7 @@ substitute consistently everywhere they appear.
   mechanical work into one delegation instead of many small round-trips.
 - If a batch is large AND the items are independent (no shared file, no ordering dependency),
   shard it across parallel `executor` runs and fan the results into a single `verifier` pass.
-  Before launching, state the shard count and why that many.
+  Launch only as many shards as that pass and the reviewer can check; state the count and why.
   If items touch the same files or must land in order, keep it serial — concurrent writers
   corrupt diffs.
 - Consult `advisor` BEFORE any change that's hard to reverse, touches shared/production
@@ -183,7 +183,7 @@ This skill installs a verify-before-done policy, so it holds itself to it. After
 confirm and report actual observed results — not intentions:
 
 1. Both markers present in `<scope>/CLAUDE.md`, exactly once each.
-2. `policy-rev: 4` is present inside the block (an upgrade from an older revision must
+2. `policy-rev: 5` is present inside the block (an upgrade from an older revision must
    leave no trace of the previous one).
 3. If agents were scaffolded: all three files exist in `<scope>/agents/`, each starts with
    valid YAML frontmatter containing `name`, `description`, `model`, and `tools`.