policy-rev 8: a leaner policy block with one failure ladder (3.5.0)

.github/workflows/validate.yml

@@ -194,6 +194,14 @@ jobs:
           cd measured && python3 -m unittest -v test_measured
           python3 approve.py --self-check
 
+      - name: Policy block within its word budget
+        run: |
+          BUDGET=735
+          W=$(awk '/^<!-- stackwich:v1 -->$/,/^<!-- \/stackwich:v1 -->$/' plugins/stackwich/skills/stackwich/SKILL.md | wc -w)
+          [ "$W" -gt 0 ] || { echo "::error::no policy block found to measure"; exit 1; }
+          [ "$W" -le "$BUDGET" ] || { echo "::error::policy block is $W words, over its $BUDGET-word budget — it is read on every turn, so cut before adding"; exit 1; }
+          echo "policy block: $W of $BUDGET words OK"
+
   recipes:
     name: Acceptance-check recipes
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -3,6 +3,31 @@
 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.5.0 — policy-rev 8: a leaner policy with one failure ladder
+
+The Claude Code policy changes, so `policy-rev` moves from 7 to 8: re-run `/stackwich:stackwich`
+to apply it in place. The `<!-- stackwich:v1 -->` marker is unchanged. `executor.md` changed too:
+agents scaffolded before this release keep the older file, so accept the scaffolding again to
+pick it up.
+
+### Policy
+- One failure ladder replaces the 2-cycle cap and the two-strike rule, which overlapped. A first
+  `GATE: FAIL` or `REVISE:` goes back to `executor`; a second goes to `advisor` to re-plan; a
+  third stops and goes to the user. The count never resets. (#39)
+- Read-heavy scans go to a fork, never to `executor`, which only writes. `executor.md`'s
+  description no longer offers scans. (#40)
+- The block is 700 words, down from 952, and is read on every turn. Removed: the
+  memory/plans/tasks bullet and "don't re-read a file you just wrote", which restate Claude Code's
+  own behavior; the separate "consult `advisor` before" bullet, merged into the mandatory-sandwich
+  rule with the same triggers. The handoff rule now keeps `.stackwich/` out of git. (#41)
+- CI fails if the block grows past a 735-word budget.
+
+### Ports
+- Codex moves to `stackwich-codex-rev 6` (failure ladder; scans never go to `executor`) and Grok
+  to `stackwich-grok-rev 5` (failure ladder as EXECUTE, then PLAN, then the user). Their other
+  bullets are unchanged: the cuts above rely on Claude Code's own behavior, which the ports'
+  runtimes may not share.
+
 ## 3.4.0 — policy-rev 7: resume interrupted work safely
 
 The Claude Code policy changes, so `policy-rev` moves from 6 to 7: re-run `/stackwich:stackwich`

README.md

@@ -19,9 +19,9 @@ Stackwich is 15 years of delivery coaching — plan → build → test → revie
 | Layer | Habit |
 |---|---|
 | **Prompt** | Meta-prompt every delegation. Context-full, with a stated done condition. Understanding never gets delegated. |
-| **Context** | Fork research and read-heavy scans off the main thread. Memory, plans, and tasks each do their own job. |
+| **Context** | Fork research and read-heavy scans off the main thread, never to the writer. Interrupted work resumes from a handoff. |
 | **Harness** | One writer. Read-only roles stay read-only in practice, not just in the tool list. Nothing "done" until observed. |
-| **Loop** | Recurring work runs on `/loop`. Failure loops are capped at 2 cycles and never silent. |
+| **Loop** | Recurring work runs on `/loop`. Failures climb one ladder — retry, re-plan, then stop — and are never silent. |
 | **Graph** | `advisor` plans → `executor` implements → `verifier` gates → `advisor` reviews, with explicit hand-off contracts. |
 
 Cost discipline isn't a sixth layer — it's how the five are practiced: cheap models grind, expensive models only plan and review, and nothing already established gets re-derived.
@@ -83,12 +83,12 @@ Four numbers move independently. Only the policy revisions change what an instal
 
 | Number | Current | Where it lives | When you act |
 |---|---|---|---|
-| Repository and plugin version | 3.4.0 | `plugin.json`, git tags `vX.Y.Z`, [CHANGELOG](CHANGELOG.md) headings | Update the plugin. |
-| Claude Code policy revision | `policy-rev 7` | The comment inside the `<!-- stackwich:v1 -->` block in your `CLAUDE.md` | Re-run `/stackwich:stackwich` when it changes. |
-| Grok port revision | `stackwich-grok-rev 4` | Inside the block the Grok port writes | Re-apply the Grok port when it changes. |
-| Codex port revision | `stackwich-codex-rev 5` | Inside the `<!-- stackwich-codex:v1 -->` block in `AGENTS.md` | Re-apply the Codex port when it changes. |
+| Repository and plugin version | 3.5.0 | `plugin.json`, git tags `vX.Y.Z`, [CHANGELOG](CHANGELOG.md) headings | Update the plugin. |
+| Claude Code policy revision | `policy-rev 8` | The comment inside the `<!-- stackwich:v1 -->` block in your `CLAUDE.md` | Re-run `/stackwich:stackwich` when it changes. |
+| Grok port revision | `stackwich-grok-rev 5` | Inside the block the Grok port writes | Re-apply the Grok port when it changes. |
+| Codex port revision | `stackwich-codex-rev 6` | Inside the `<!-- stackwich-codex:v1 -->` block in `AGENTS.md` | Re-apply the Codex port when it changes. |
 
-A repository release can leave every policy revision unchanged; 3.2.0 did, while 3.3.0 and 3.4.0 each moved all three. Each CHANGELOG entry says whether there is anything to re-run. The markers themselves never change.
+A repository release can leave every policy revision unchanged; 3.2.0 did, while 3.3.0, 3.4.0 and 3.5.0 each moved all three. Each CHANGELOG entry says whether there is anything to re-run. The markers themselves never change.
 
 ### Older copies
 
@@ -111,7 +111,7 @@ A repository release can leave every policy revision unchanged; 3.2.0 did, while
 
 **Single writer.** Only `executor` mutates the filesystem. `advisor` and `verifier` have no edit tools, and their `Bash` is for inspection and verification, scoped away from writes by instruction — a fix from a reviewer is an unreviewed change nobody knows exists. The tool list is enforced by Claude Code; the `Bash` boundary depends on the model following it. Tests and builds the verifier runs can still create caches and build output; what read-only protects is product source and external state. See [docs/enforcement.md](docs/enforcement.md).
 
-**Loops are capped.** `GATE: FAIL` and `REVISE:` both route back to `executor` with the original plan attached, for at most 2 cycles. On the third, it stops and surfaces everything to the human. Verdict lines are fixed strings so routing doesn't depend on interpreting prose; the main session still does the routing, and the cap is instructed, not counted by a tool.
+**Loops are capped.** A first `GATE: FAIL` or `REVISE:` goes back to `executor` with the original plan attached; a second goes to `advisor` to re-plan from what was tried; a third stops and surfaces everything to the human. The count never resets. Verdict lines are fixed strings so routing doesn't depend on interpreting prose; the main session still does the routing, and the cap is instructed, not counted by a tool.
 
 **Input contracts are explicit.** Each agent states what it must receive and is instructed to stop when a piece is missing rather than reconstruct it — a reviewer that rebuilds the plan from the diff reviews the change against itself and approves anything self-consistent.
 

codex/README.md

@@ -17,7 +17,8 @@ Stackwich installs five layers into Codex sessions:
 4. **Loop** — schedule recurring work; failure cycles are capped, never silent
 5. **Graph** — PLAN → EXECUTE → VERIFY → REVIEW for anything risky
 
-It also instructs the two-strike rule (same failure twice → stop and escalate), verification
+It also instructs a failure ladder (first failure → retry, second → `advisor` re-plans, third →
+stop and ask you), verification
 by behavior rather than re-reading a just-written file, and no suffixed file copies as a
 debugging strategy.
 
@@ -68,7 +69,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 5`. The port tracks the parent's layer structure, not its revision
+> `stackwich-codex-rev 6`. The port tracks the parent's layer structure, not its revision
 > number — a parent bump does not automatically oblige a port bump.
 
 ---

codex/SKILL.md

@@ -70,9 +70,8 @@ accounts and future model catalogs.
 - Verify behavior or structure rather than re-reading a just-written file solely to confirm
   that the write occurred.
 
-Fix validation failures before reporting success. Apply the two-strike rule to repeated
-verification failures: after the same failure occurs twice, stop blind retries and report the
-evidence.
+Fix validation failures before reporting success. If the same validation failure occurs twice,
+stop blind retries and report the evidence.
 
 ## 6. Report the result
 

codex/references/templates.md

@@ -7,7 +7,7 @@ credit in every custom-agent file.
 
 ```markdown
 <!-- stackwich-codex:v1 -->
-<!-- stackwich-codex-rev: 5 -->
+<!-- stackwich-codex-rev: 6 -->
 ## Working Architecture (Stackwich Codex)
 
 ### Prompt
@@ -59,21 +59,22 @@ credit in every custom-agent file.
 - 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.
-  - Either path is capped at 2 cycles. On the third, stop and bring the user the plan, what was
-    tried, and the outstanding gate or review output. Never loop silently.
+- Failure ladder for `GATE: FAIL` or `REVISE: ...` on the same change; the count never resets:
+  1. First failure -> return the failure output or numbered list to `executor` together with
+     the original plan.
+  2. Second -> `advisor` re-plans from the plan, the commands, outputs, and attempted fixes;
+     `executor` applies the new plan.
+  3. Third -> stop and bring the user the plan, what was tried, and the outstanding gate or
+     review output.
+  Never loop silently, and never create a suffixed copy of a real file to debug around a
+  failure.
 - Distinguish an infrastructure failure, such as a missing dependency or an unavailable
   service, from a failed change, so cycles are not burned on environment problems.
-- Two-strike rule: if the same verification fails twice, stop blind iteration and escalate to
-  `advisor` with the commands, outputs, and attempted fixes. Never create a suffixed copy of a
-  real file merely to debug around the failure.
 
 ### Graph
 - Work alone for small, reversible changes. Delegate to `executor` for a fully specified
-  mechanical batch of roughly five or more files, or for a read-heavy scan that would pollute
-  the main context. Batch related mechanical work into one delegation.
+  mechanical batch of roughly five or more files; read-heavy scans go to a context-carrying
+  subagent, never `executor`. Batch related mechanical work into one delegation.
 - Consult `advisor` before any change that is hard to reverse, touches shared or production
   systems, or spans repositories or services. Obtain user confirmation before any action that
   needs new authority or mutates shared or production state.
@@ -142,7 +143,7 @@ Every item in a REVISE list must be independently actionable. The executor gets
 ```toml
 # Created by Abhirup Banerjee (@ovhirup) as part of the Stackwich Codex architecture.
 name = "executor"
-description = "Low-reasoning executor for fully specified mechanical edits, large batches, and read-heavy scans."
+description = "Low-reasoning executor for fully specified mechanical edits and large batches."
 model_reasoning_effort = "low"
 developer_instructions = """
 Carry out the provided instructions exactly. Do not redesign, extend, or opportunistically refactor.
@@ -152,7 +153,7 @@ Inputs you require: the plan's exact steps, its declared file scope, and the ver
 - Follow every applicable AGENTS.md file and existing conventions for touched files.
 - Never create suffixed copies such as name2.ts or fix-v2.py to work around a problem.
 - If an instruction is ambiguous, stop and report the ambiguity instead of guessing.
-- If the same verification fails twice, stop and return both attempts, outputs, and relevant diff.
+- If the same verification fails twice, stop and return both attempts, outputs, and relevant diff; a second failure goes to `advisor` to re-plan, not to another blind retry.
 - Report changed paths, the diff or edits made, commands run, exit codes, and material raw output.
 - Never mutate shared or production state, deploy, push, publish, or call a live write API unless the parent task explicitly authorizes that exact action.
 """

docs/enforcement.md

@@ -23,7 +23,8 @@ Three kinds of claim:
 | Each agent's model tier | Mechanical, as configuration | Set by `model:` in each agent's frontmatter. Which agent gets used for a task is instructed. |
 | Plan → execute → verify → review for risky changes | Instructed | The main session decides when a change is risky and whether to run the sandwich. |
 | Verdict lines (`GATE: PASS`, `APPROVE`, `REVISE:`) | Instructed | They are fixed strings so routing does not depend on reading prose, but the main session does the routing. |
-| Failure loops capped at 2 cycles | Instructed | No counter exists outside the conversation. |
+| Failure ladder: retry, then `advisor` re-plans, then stop at the third failure | Instructed | No counter exists outside the conversation. |
+| Read-heavy scans go to a fork, not `executor` | Instructed | The main session chooses where to send a scan. |
 | Nothing "done" until verified | Instructed | The policy requires reporting the command and its output. No tool checks that a claim matches a run. |
 
 ## Codex port
@@ -32,7 +33,7 @@ Three kinds of claim:
 |---|---|---|
 | `advisor` and `verifier` cannot write files | Mechanical, where Codex honors the setting | Their templates set `sandbox_mode = "read-only"`, so Codex runs their commands in its read-only sandbox. |
 | `executor` stays in scope and does not push, deploy, or publish | Instructed | `executor` has no `sandbox_mode` in its template and inherits the session's sandbox and approval settings. |
-| Sandwich, verdict routing, 2-cycle cap, two-strike rule | Instructed | Same as the Claude Code plugin. |
+| Sandwich, verdict routing, failure ladder, scan routing | Instructed | Same as the Claude Code plugin. |
 | Model choice | Not pinned | The templates set reasoning effort and sandbox only, so they stay portable across accounts. |
 
 A read-only sandbox also blocks legitimate writes. A test, build, or coverage run that needs to
@@ -44,7 +45,7 @@ verifier's instructions say to label environment problems as such.
 | Behavior | Kind | Detail |
 |---|---|---|
 | Single writer, PLAN/VERIFY/REVIEW never edit | Instructed | The port runs the sandwich as phases inside one agent. There is no separate role with fewer tools. |
-| Sandwich, 2-cycle cap, verification before "done" | Instructed | Same policy as the parent, carried by `grok/SKILL.md`. |
+| Sandwich, failure ladder (EXECUTE, then PLAN, then the user), verification before "done" | Instructed | Same policy as the parent, carried by `grok/SKILL.md`. |
 
 ## Measured approval gate (`measured/approve.py`)
 

docs/first-task.md

@@ -26,7 +26,7 @@ cd ~/my-project
 python3 ~/stackwich-tools/tools/diagnose.py
 ```
 
-A healthy user-level install reports `policy-rev 7`, three Stackwich agents, and
+A healthy user-level install reports the checkout's current `policy-rev`, three Stackwich agents, and
 `Problems: none found`. Here is a setup with a real conflict: the project has its own agent
 called `executor`, which shadows Stackwich's.
 

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 7; 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 8; 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 7 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 8 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 7 and no older policy-rev line remains"
+        "final block declares policy-rev 8 and no older policy-rev line remains"
       ],
       "files": []
     },

grok/README.md

@@ -17,12 +17,12 @@ Stackwich installs five layers into Grok coding sessions:
 1. **Prompt** — meta-prompt every non-trivial sub-task; never hand off understanding
 2. **Context** — keep research and raw tool output out of the main reasoning thread
 3. **Harness** — one writer, and nothing is "done" without observed output
-4. **Loop** — deliberate iteration, capped at two cycles before you're brought in
+4. **Loop** — deliberate iteration: retry, then re-plan, then you're brought in
 5. **Graph** — PLAN → EXECUTE → VERIFY → REVIEW for anything risky
 
 It also instructs:
 - A verification gate with fixed verdicts (`GATE: PASS` / `GATE: FAIL`)
-- Two-strike rule (same failure twice → stop and escalate)
+- A failure ladder (first failure → retry, second → re-plan, third → stop and ask you)
 - No suffixed file copies as a debugging strategy
 - Concrete plans with verification commands before non-trivial edits
 
@@ -60,7 +60,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 4`. The port tracks the parent's layer structure, not its revision
+> `stackwich-grok-rev 5`. 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.