Add run ceilings and demand check (policy-rev 4, v3.1.0)

.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: 3 -->' "$S")" -eq 1 ] || { echo "::error::SKILL.md must contain exactly one whole-line policy-rev: 3 comment"; 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; }
           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,55 @@
 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.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
+`<!-- stackwich:v1 -->` marker is unchanged, so existing installs upgrade in place.
+
+### Why
+Stackwich lowers the unit cost of agent work — cheap executors, warm forks, loops instead of
+re-running by hand, parallel shards. Cheaper units invite more of them (the rebound effect, or
+Jevons paradox), so total spend and review load can rise even as each step gets cheaper. Each of
+those efficiencies now comes paired with a limit or a count. The reasoning lives in
+`assets/rebound.md`, read only when a user asks about cost, loops, or fan-out; the policy block
+carries only the imperatives.
+
+### Policy block
+- **Loop:** every loop, fixed-cadence or self-paced, states its stop condition and a maximum run
+  count before it starts, and asks the user when either is missing. A loop with no change for 3
+  consecutive runs stops and reports. The ceiling is a run count, not a spend figure, because run
+  count is observable and spend usually is not.
+- **Graph:** sharding across parallel executors now states the shard count and the reason for
+  it. There is no numeric cap — the right number depends on the work.
+- **Harness:** delegations are sized to what `verifier` and the reviewer can check in one pass,
+  and a done report counts delegations, forks, and loop runs. Token or cost figures appear only
+  where the environment shows them, so a report never states a number nobody observed.
+
+### Agents
+- `advisor`'s plan template gains a `Demand check:` line, and its blast-radius review item now
+  asks whether making something cheaper or automatic raises load, spend, or review volume
+  elsewhere. Re-scaffold `advisor` to pick this up; `executor` and `verifier` are unchanged.
+
+### Upgrading
+Update the plugin, then re-run `/stackwich:stackwich`. It finds the existing block by its marker,
+shows you the installed `policy-rev: 3`, and replaces the block in place once you confirm.
+
+If a pre-3.0 clone is still at `~/.claude/skills/stackwich` or `./.claude/skills/stackwich`,
+remove it first (see 3.0.0 below) — from this release on, it would install the stale
+`policy-rev: 3` block.
+
+### Ports
+- Grok — `stackwich-grok-rev 2`: the same three limits for a single agent. Standing tasks carry
+  a stop condition and run ceiling, the batch count is stated, and each pass is sized for VERIFY
+  and REVIEW.
+- Codex — `stackwich-codex-rev 2`: the same three limits, applied to scheduled automations and
+  parallel subagents.
+
+### Repo
+- CI asserts `policy-rev: 4`.
+- `evals/evals.json`: case 1 expects `policy-rev 4`, case 2 asserts no older revision remains,
+  and two new cases cover an unbounded loop request and a large parallel batch.
+
 ## 3.0.0 — installs as a plugin
 
 Stackwich is now a Claude Code plugin marketplace rather than a repo you clone into your skills

README.md

@@ -58,7 +58,7 @@ The skill does the rest interactively: asks for scope, writes the policy, offers
 
 ### Upgrading from 2.x
 
-**Nothing about your policy changes.** Your `CLAUDE.md` block stays at `policy-rev 3`, your `advisor`, `executor` and `verifier` keep their existing names and contents, and there is nothing to re-run. Only the delivery mechanism moved.
+**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.
 
 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`:
 
@@ -102,11 +102,12 @@ stackwich/
 │   ├── LICENSE
 │   └── skills/stackwich/
 │       ├── SKILL.md              # the skill: install workflow + policy block
-│       └── assets/               # agent definitions, read only when scaffolding is accepted
-│           ├── advisor.md
+│       └── assets/               # read on demand, never on every trigger
+│           ├── advisor.md        # agent definitions, read only when scaffolding is accepted
 │           ├── executor.md
-│           └── verifier.md
-├── evals/evals.json              # test cases for the five install paths
+│           ├── verifier.md
+│           └── rebound.md        # cost/rebound playbook, read only for cost or loop questions
+├── evals/evals.json              # five install paths + two policy-behavior cases
 ├── docs/sandwich.jpg
 ├── grok/                         # Grok port (stackwich-grok) — not a Claude Code skill
 ├── codex/                        # Codex port (stackwich-codex) — not a Claude Code skill

codex/README.md

@@ -63,7 +63,7 @@ scaffold `advisor`, `executor`, and `verifier` as TOML agents.
 > insert a duplicate block.
 
 > **Port status:** at parity with the Claude Code parent's five-layer policy, as
-> `stackwich-codex-rev 1`. The port tracks the parent's layer structure, not its revision
+> `stackwich-codex-rev 2`. The port tracks the parent's layer structure, not its revision
 > number — a parent bump does not automatically oblige a port bump.
 
 ---

codex/references/templates.md

@@ -7,7 +7,7 @@ credit in every custom-agent file.
 
 ```markdown
 <!-- stackwich-codex:v1 -->
-<!-- stackwich-codex-rev: 1 -->
+<!-- stackwich-codex-rev: 2 -->
 ## Working Architecture (Stackwich Codex)
 
 ### Prompt
@@ -42,10 +42,17 @@ credit in every custom-agent file.
 - Match cost and reasoning to the role: favor a faster, lower-cost configuration for
   `executor`; reserve higher reasoning for `advisor` planning and review. Do not select a more
   expensive model or larger agent workflow than the task requires.
+- Size each delegation to what `verifier` and `advisor` can check in one pass; split a larger
+  batch into sequential gated batches. When reporting done, state how many delegations,
+  subagents, and automation runs the task used — add token or cost figures only where the
+  environment shows them.
 
 ### Loop
 - Recurring or repeated work defaults to a scheduled automation when the active ChatGPT or
   Codex surface supports it. Do not create a manual re-run habit for stable recurring work.
+- Before creating a scheduled automation or any repeating run, state its stop condition and a
+  maximum run count; if either is missing, ask the user instead of starting. A repeating run
+  with no change for 3 consecutive runs stops and reports (unless the user set another number).
 - Failure routing, with hard stops:
   - `GATE: FAIL` -> return the failure output to `executor` together with the original plan.
   - `REVISE: ...` -> return the numbered list to `executor` together with the original plan.
@@ -68,8 +75,8 @@ credit in every custom-agent file.
   implements, `verifier` gates, then `advisor` reviews. Otherwise, use `verifier` after
   substantive edits when independent verification adds value.
 - Use custom roles when installed. Otherwise spawn bounded subagents with the same advisor,
-  executor, and verifier responsibilities. Parallelize only independent work, and avoid
-  concurrent edits to overlapping files.
+  executor, and verifier responsibilities. Parallelize only independent work, state how many
+  parallel runs and why that many, and avoid concurrent edits to overlapping files.
 - You are the orchestrator: artifacts travel through you, so forward them intact. `executor`
   receives the plan's exact steps plus its verification command and expected output.
   `verifier` receives that same verification spec plus the executor's reported diff and the

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 3; 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 4; 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,11 +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. 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 4 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 file contains exactly one marker pair",
+        "final block declares policy-rev 4 and no older policy-rev line remains"
       ],
       "files": []
     },
@@ -63,6 +64,32 @@
         "unrelated CLAUDE.md content is preserved"
       ],
       "files": []
+    },
+    {
+      "id": 6,
+      "name": "unbounded-loop-request",
+      "prompt": "Put a /loop on refactoring the whole codebase — pace it yourself, no fixed schedule.",
+      "expected_output": "Before any loop starts, the agent states or asks for a stop condition and a maximum run count, and says the loop stops and reports after 3 consecutive runs with no change. The requirement holds even though there is no fixed cadence. No loop is started without both.",
+      "assertions": [
+        "a stop condition is stated or requested before the loop starts",
+        "a maximum run count is stated or requested before the loop starts",
+        "the no-change stop (3 consecutive runs, or a user-set number) is stated",
+        "no loop is started while the stop condition or the run ceiling is missing"
+      ],
+      "files": []
+    },
+    {
+      "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.",
+      "assertions": [
+        "the number of parallel executor runs is stated with a reason before launch",
+        "each batch is sized for a single verifier pass",
+        "the done report counts delegations, forks, and loop runs",
+        "no token or cost figure is reported that the environment did not show"
+      ],
+      "files": []
     }
   ]
 }

grok/README.md

@@ -56,7 +56,7 @@ cp SKILL.md LICENSE ~/.grok/skills/stackwich-grok/
 ```
 
 > **Port status:** at parity with the Claude Code parent's five-layer policy, as
-> `stackwich-grok-rev 1`. The port tracks the parent's layer structure, not its revision
+> `stackwich-grok-rev 2`. The port tracks the parent's layer structure, not its revision
 > number — a parent bump does not automatically oblige a port bump. The Graph layer is
 > expressed as explicit phases inside one agent rather than three subagents: a deliberate
 > design choice for this runtime, not a shortfall.

grok/SKILL.md

@@ -102,7 +102,7 @@ When the user asks to install or activate Stackwich:
 
 ```markdown
 <!-- stackwich:v1 -->
-<!-- stackwich-grok-rev: 1 -->
+<!-- stackwich-grok-rev: 2 -->
 ## Working Architecture (Stackwich)
 
 ### Prompt
@@ -128,12 +128,18 @@ When the user asks to install or activate Stackwich:
   its actual output. If it wasn't verified, say so instead of implying it was.
 - Match effort to the change. Don't escalate a small reversible edit into the full cycle, and
   don't spend a heavier reasoning budget than the work actually requires.
+- Size each pass to what VERIFY and REVIEW can check at once; split larger work into sequential
+  gated passes. When reporting done, state how many passes and iterations the task used — add
+  token or cost figures only where the environment shows them.
 
 ### Loop
 - Recurring or repeated work runs as a standing, written task with its own trigger and done
   condition — not a manual re-run-by-hand habit. Grok has no `/loop` command, so this is a
   discipline rather than a feature: write the repeating work down and run it from that, not
   from memory.
+- A standing task states its stop condition and a maximum run count before its first run; if
+  either is missing, ask the user instead of starting. One that produces no change for 3
+  consecutive runs stops and reports (unless the user set a different number).
 - Recurring work runs as explicit iteration that tracks what was attempted and what failed,
   not as repeated one-shot "try again" prompts.
 - Failure routing, with a hard stop:
@@ -156,8 +162,9 @@ When the user asks to install or activate Stackwich:
   expected output. VERIFY receives that same verification spec plus the actual diff. REVIEW
   receives the original plan alongside the diff and the gate result. A phase missing its input
   says which one and stops.
-- Batch independent mechanical work into a single pass. Never interleave edits to the same file
-  across passes — concurrent writers corrupt diffs.
+- Batch independent mechanical work into a single pass; when splitting into several batches,
+  state how many and why that many. Never interleave edits to the same file across passes —
+  concurrent writers corrupt diffs.
 <!-- /stackwich:v1 -->
 ```
 

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

@@ -1,6 +1,6 @@
 {
   "name": "stackwich",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "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",