agentic-sdlc-wizard 1.83.0 → 1.84.0

package/.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
       "name": "sdlc-wizard",
       "source": ".",
       "description": "SDLC enforcement for AI agents — TDD, planning, self-review, CI shepherd",
-      "version": "1.83.0",
+      "version": "1.84.0",
       "author": {
         "name": "Stefan Ayala"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "sdlc-wizard",
-  "version": "1.83.0",
+  "version": "1.84.0",
   "description": "SDLC enforcement for AI agents — TDD, planning, self-review, CI shepherd",
   "author": {
     "name": "Stefan Ayala",

package/AI_SETUP_LANES.md

@@ -1,36 +1,73 @@
 # AI Setup Lanes
 
-Three recommended AI coding setups for this repo. Setups A and B are complete triads: **planner → driver → reviewer**. Setup C is a lightweight driver-only lane for operational grunt work.
+Four recommended AI coding setups for this repo. Setups A, B, and C are complete triads: **planner → driver → reviewer**. Setup D is a lightweight driver-only lane for operational grunt work.
 
 This is **guidance, not a hard rule**. Maintainer override is always allowed.
 
-## Setup A — Claude Premium
+## Setup A — Sonnet 5 + Fable Advisor (Recommended)
 
-| Role | Model |
-|------|-------|
-| **Advisor** | Fable 5 (via `advisorModel: "fable"` in project settings — auto-consults at key decisions) |
-| **Driver** | Opus 4.6 max |
-| **Reviewer** | Codex (GPT-5.5) xhigh |
-| **Escalation** | + Fable 5 review (security, releases, wide-blast architecture only) |
+| Role | Model | Effort |
+|------|-------|--------|
+| **Advisor** | Fable 5 (via `advisorModel: "fable"`) | `high` (server-side) |
+| **Driver** | Sonnet 5 (`claude-sonnet-5`) | `high` default, `/effort xhigh` for hard tasks |
+| **Reviewer** | Codex (GPT-5.5) xhigh | — |
+| **Escalation** | Opus 4.8 xhigh or Fable 5 review | When stuck or high-stakes |
 
-Quality-first lane. Fable 5 advises automatically at key decision points (architecture, complexity, blast-radius) via native `advisorModel` (v2.1.170+), Opus 4.6 max implements (stable, Max-bundled), GPT-5.5 xhigh reviews (cross-family, free on ChatGPT sub, catches blind spots Fable can't see in its own work). Escalate to Fable review for the ~5% of PRs where stakes justify it.
+The new standard. Sonnet 5 beats Opus 4.6 on every coding benchmark (SWE-bench Verified 85.2% vs 80.8%, Terminal-Bench 80.4% vs 65.4%) while using ~5x less Max quota per turn. Fable 5 advises at key decision points via native `advisorModel` (v2.1.170+). GPT-5.5 xhigh reviews cross-family. Escalate to Opus 4.8 xhigh for the hardest debugging or architecture decisions — don't run Opus as the daily driver (burns Max limits 2-3x faster).
 
-**Effort levels:** Opus driver at `max` (standing default). Fable advisor runs at its own effort level server-side. If switching driver to Fable temporarily (fallback), use `/effort high` — Fable `high` already exceeds prior models at `max`. Unset `CLAUDE_CODE_EFFORT_LEVEL` env var if it forces `max`.
+**Effort escalation ladder:** Start at `high` (Sonnet 5's default and sweet spot). Raise to `xhigh` when doing hard debugging, multi-file migrations, or long agent runs. `max` is rarely worth it — doubles cost for marginal gains per CodeRabbit testing.
 
-## Setup B — Claude Saver (OpusPlan)
+**Requires:** Claude Code v2.1.197+ (Sonnet 5 alias resolution), Fable 5 access for advisor.
 
-| Role | Model |
-|------|-------|
-| **Planner** | Opus 4.6 max (via Plan Mode — Shift+Tab) |
-| **Advisor** | Opus 4.6 (via `advisorModel: "claude-opus-4-6"` — compensates for Sonnet driver) |
-| **Driver** | Sonnet (latest, auto execute mode) |
-| **Reviewer** | Codex (GPT-5.5) xhigh |
+## Setup B — Opus 4.6 Stability (Legacy Flagship)
 
-Cost-efficient lane using CC's native `opusplan` alias. Opus reasons during Plan Mode (Shift+Tab), Sonnet executes. Both 200K context, Max-bundled — no API credit drain. Pin `model: "opusplan"` + `advisorModel: "claude-opus-4-6"` + `CLAUDE_CODE_EFFORT_LEVEL=max` in project settings. The Opus advisor auto-compensates for Sonnet's lighter reasoning at key decision points. GPT-5.5 xhigh is the cross-model reviewer.
+| Role | Model | Effort |
+|------|-------|--------|
+| **Advisor** | Fable 5 (via `advisorModel: "fable"`) | `high` (server-side) |
+| **Driver** | Opus 4.6 (`claude-opus-4-6`) | `max` |
+| **Reviewer** | Codex (GPT-5.5) xhigh | — |
+
+The consistency-first lane. Opus 4.6 is the only model where `max` effort works without overthinking — months of field data, Active through at least Feb 2027, proven predictable. Lower benchmark scores than Sonnet 5 but higher consistency. Choose this when you've tuned prompts to Opus 4.6 behavior and reliability matters more than peak capability.
+
+**Effort:** Opus 4.6 at `max` (no xhigh support — only low/medium/high/max). This is the sweet spot; community reports confirm 4.6 is the only Opus where `max` doesn't over-engineer.
+
+## Setup C — OpusPlan Hybrid (Saver)
+
+| Role | Model | Effort |
+|------|-------|--------|
+| **Planner** | Opus 4.8 (via Plan Mode — Shift+Tab) | `xhigh` |
+| **Advisor** | Fable 5 or Opus 4.8 (via `advisorModel`) | — |
+| **Driver** | Sonnet 5 (auto execute mode) | `high` |
+| **Reviewer** | Codex (GPT-5.5) xhigh | — |
+
+Cost-efficient hybrid using CC's native `opusplan` alias. Opus 4.8 reasons during Plan Mode, Sonnet 5 executes. Max-bundled — no API credit drain. Pin `model: "opusplan"` + `advisorModel: "fable"` in project settings. Sonnet 5 now uses 1M context natively (no `[1m]` suffix needed). GPT-5.5 xhigh is the cross-model reviewer.
+
+**Note:** Opus 4.6 cannot advise Sonnet 5 (rejected in the advisor pairing table). Use Fable 5 or Opus 4.8 as advisor for this lane.
+
+## Setup D — Claude Lite
+
+| Role | Model | Effort | Notes |
+|------|-------|--------|-------|
+| **Planner** | You (the user) | — | Task is pre-planned, no model reasoning needed |
+| **Driver** | Sonnet 5 | `medium` | Max-bundled, ≈ Sonnet 4.6 at high quality |
+| **Reviewer** | None | — | Blast radius too low for cross-model overhead |
+
+The "just do the thing" lane. No TDD enforcement, no cross-model review, no planning phase. You already know what to do — you just need a fast, cheap pair of hands.
 
 ## When to Use Setup A
 
-Reach for Premium when the change can damage a consumer repo or has high blast radius:
+The default choice for most SDLC work — full discipline (TDD, cross-model review) at a fraction of Setup B's quota cost:
+
+- Feature implementation and routine development
+- Documentation and examples
+- Test writing
+- Normal CLI changes
+- Mechanical refactors
+- Anything where you'd reach for Setup B out of habit rather than a specific need for Opus 4.6's proven consistency
+
+## When to Use Setup B
+
+Reach for Setup B when the change can damage a consumer repo, has high blast radius, or you've specifically tuned your workflow to Opus 4.6's behavior:
 
 - Architecture or methodology changes
 - Tagged release prep
@@ -42,9 +79,9 @@ Reach for Premium when the change can damage a consumer repo or has high blast r
 - Security-sensitive behavior
 - Anything that could damage a consumer repo
 
-## When to Use Setup B
+## When to Use Setup C
 
-Setup B is sufficient for routine work where a Sonnet driver can ship with a strong reviewer:
+Setup C is sufficient for routine work where a Sonnet driver can ship with a strong reviewer and you want the Max-bundled cost profile of `opusplan`:
 
 - Routine implementation
 - Documentation
@@ -54,22 +91,12 @@ Setup B is sufficient for routine work where a Sonnet driver can ship with a str
 - Low-risk methodology edits
 - Mechanical refactors
 
-## Setup C — Claude Lite
-
-| Role | Model | Notes |
-|------|-------|-------|
-| **Planner** | You (the user) | Task is pre-planned, no model reasoning needed |
-| **Driver** | Sonnet 4.6 | Same model as Setup B driver — Max-bundled, no extra model to manage |
-| **Reviewer** | None | Blast radius too low for cross-model overhead |
-
-The "just do the thing" lane. No TDD enforcement, no cross-model review, no planning phase. You already know what to do — you just need a fast, cheap pair of hands.
-
-## When to Use Setup C
+## When to Use Setup D
 
-Setup C is for work where SDLC discipline overhead exceeds the value:
+Setup D is for work where SDLC discipline overhead exceeds the value:
 
 - Run a script with basic intelligence
-- Deploy to staging (prod deploys need Setup A's discipline — human gate + rollback plan)
+- Deploy to staging (prod deploys need Setup A's or B's discipline — human gate + rollback plan)
 - Config updates, env var changes
 - File moves, renames, bulk operations
 - Repo maintenance (dependency bumps, lockfile refreshes)
@@ -78,20 +105,20 @@ Setup C is for work where SDLC discipline overhead exceeds the value:
 
 **Not Lite — escalate to A or B:** env vars that touch secrets or credentials, dependency bumps with security advisories, destructive bulk ops (rm -rf, drop table), migrations, prod-like shared staging, anything security-sensitive. If you're unsure, it's not Lite.
 
-## What Setup C explicitly skips
+## What Setup D explicitly skips
 
 - No TDD (no test-first for running a deploy script)
 - No cross-model review (not worth the cost or time for grunt work)
 - No planning phase (you are the planner)
 - No effort escalation (Sonnet standard is plenty)
 
-**The discipline of knowing when NOT to use discipline.** Documenting this lane tells users "here's when to switch off the heavy methodology" rather than silently tempting them to skip it. If the task turns out to be harder than expected, escalate to Setup B or A.
+**The discipline of knowing when NOT to use discipline.** Documenting this lane tells users "here's when to switch off the heavy methodology" rather than silently tempting them to skip it. If the task turns out to be harder than expected, escalate to Setup A or B.
 
 ## Final Review Policy
 
-**Setups A and B end at GPT-5.5 xhigh as the cross-model reviewer.** Claude can't grade its own homework — the reviewer always belongs to a different lab with different blind spots. See [CLAUDE_CODE_SDLC_WIZARD.md → "Cross-Model Review (Codex)"](CLAUDE_CODE_SDLC_WIZARD.md) for the handoff protocol.
+**Setups A, B, and C end at GPT-5.5 xhigh as the cross-model reviewer.** Claude can't grade its own homework — the reviewer always belongs to a different lab with different blind spots. See [CLAUDE_CODE_SDLC_WIZARD.md → "Cross-Model Review (Codex)"](CLAUDE_CODE_SDLC_WIZARD.md) for the handoff protocol.
 
-**Setup C has no reviewer** — the blast radius doesn't justify it. If you're unsure whether a task is truly Lite, it probably isn't. Escalate.
+**Setup D has no reviewer** — the blast radius doesn't justify it. If you're unsure whether a task is truly Lite, it probably isn't. Escalate.
 
 If GPT-5.5 isn't available on your OpenAI account, Codex auto-falls back to GPT-5.4 — still keep `model_reasoning_effort="xhigh"`. Lower reasoning misses subtle bugs that the reviewer is the last gate to catch.
 
@@ -105,7 +132,7 @@ If GPT-5.5 isn't available on your OpenAI account, Codex auto-falls back to GPT-
 
 The `!` prefix runs shell commands inside your CC session — no need to exit and re-enter. After updating, restart the session for the advisor to activate.
 
-Fable 5 as advisor also requires Fable 5 access for your organization/plan (free on Max through June 22, 2026).
+Fable 5 as advisor also requires Fable 5 access for your organization/plan. Fable's inclusion in subscriptions has run in separate windows rather than continuously — free through June 22, 2026, then a second window July 1-7, 2026 (up to 50% of weekly usage limits), then usage-credit metered. Check [anthropic.com/claude/fable](https://www.anthropic.com/claude/fable) for current status rather than assuming either window is still open.
 
 ## When the Advisor Is Unavailable
 
@@ -115,8 +142,8 @@ If the advisor returns "Advisor unavailable," the server-side harness failed to
 
 **Step 2 — if the API incident persists:**
 
-- `/model fable` + `/effort high` for the planning phase, then `/model claude-opus-4-6` for implementation. Interactive — stays on your Max subscription.
-- Or proceed with Opus only and let the Codex xhigh PR gate catch issues.
+- Continue with your driver model and no advisor — `/model sonnet` for Setup A, `/model claude-opus-4-6` for Setup B. Interactive — stays on your Max subscription.
+- Or proceed without the advisor and let the Codex xhigh PR gate catch issues.
 
 **Last resort (scripted/CI only):**
 
@@ -128,31 +155,31 @@ Whichever path you use, the cross-model PR review gate still applies.
 
 ## Credit-Spend Warning
 
-Setups A and B use Opus 4.6 max for at least the planner — that's the expensive half. On Max-plan subscriptions, **Premium can burn the 5-hour cap faster than Saver** because Opus 4.6 max drives implementation too. If you're hitting the cap mid-session:
+**Setup B (Opus 4.6 max as both planner and driver) burns the 5-hour cap faster than Setup A** — Opus 4.6 max driving implementation is the expensive path; Sonnet 5 uses roughly 5x less quota per turn for comparable benchmark results. If you're hitting the cap mid-session on Setup B:
 
-- Drop to Setup B for the remainder of the day
-- Or drop to Setup C for grunt work that doesn't need Opus reasoning
+- Drop to Setup A (Sonnet 5) for the remainder of the day — same discipline, far less quota burn
+- Or drop to Setup D for grunt work that doesn't need deep reasoning
 - Or use Sonnet directly for the final mechanical edits, then run the GPT-5.5 reviewer over the whole diff at the end
 
-**Setup C uses Sonnet** — same model as Setup B's driver, Max-bundled. One less model to manage.
+**Setup D uses Sonnet** — same model as Setup A's driver, Max-bundled. One less model to manage if you're already on Setup A.
 
 The reviewer (GPT-5.5 xhigh) is billed against your OpenAI account, separately. Watch both bills.
 
 ## Autocompact Thresholds
 
-For recommended `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` values per context window and task shape, see [CLAUDE_CODE_SDLC_WIZARD.md → Autocompact Tuning](CLAUDE_CODE_SDLC_WIZARD.md#autocompact-tuning).
+For recommended `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` values per context window and task shape, see [CLAUDE_CODE_SDLC_WIZARD.md → Autocompact Tuning](CLAUDE_CODE_SDLC_WIZARD.md#autocompact-tuning). Sonnet 5 (Setup A, D) has its own native ~967K-token proactive-compaction default at 1M context — don't carry over Opus-era 1M threshold guidance unexamined.
 
 ## How Billing Works — 1M Context, Max Plan, and the June 15 Split
 
 A common question: **"does the `[1m]` model alias get billed differently? Does it pull from my Max plan or from API credits?"**
 
-The short answer: **Setup A uses Fable advisor + Opus driver (both Max-bundled in interactive sessions). Setup B is fully Max-bundled via opusplan + Opus advisor.** Here's the detail.
+The short answer: **Setup A (Sonnet 5, native 1M) and Setup C (opusplan, Opus plan-mode + Sonnet execute) are both fully Max-bundled in interactive sessions. Setup B (Opus 4.6 max) is also Max-bundled, including its 1M context.** Here's the detail.
 
 ### 1M context is free on Max — no API premium
 
-[Anthropic 2026-03-13](https://claude.com/blog/1m-context-ga): 1M context is GA at standard $5/$25 per million tokens for Opus 4.6 (also 4.7, 4.8). No long-context multiplier. **No beta header required**, requests over 200K tokens just work.
+[Anthropic 2026-03-13](https://claude.com/blog/1m-context-ga): 1M context is GA at standard $5/$25 per million tokens for Opus 4.6 (also 4.7, 4.8). No long-context multiplier. **No beta header required**, requests over 200K tokens just work. Sonnet 5 always runs at 1M natively (see [`code.claude.com/docs/en/model-config#sonnet-5-context-window`](https://code.claude.com/docs/en/model-config#sonnet-5-context-window)) — no `[1m]` suffix, no separate billing tier.
 
-For Claude Code on Max / Team / Enterprise plans, **1M context is included automatically** with no extra usage allocation. Whether you set `claude-opus-4-6` or `claude-opus-4-6[1m]` doesn't change *what* you're billed — both pull from the same per-token budget on your subscription. The `[1m]` suffix just makes the alias explicit so it sticks across alias-resolution changes; functionally Opus 4.6 in Claude Code today *is* the 1M-context model on a Max plan.
+For Claude Code on Max / Team / Enterprise plans, **1M context is included automatically** with no extra usage allocation for supported models. Whether you set `claude-opus-4-6` or `claude-opus-4-6[1m]` doesn't change *what* you're billed — both pull from the same per-token budget on your subscription. The `[1m]` suffix just makes the alias explicit so it sticks across alias-resolution changes; functionally Opus 4.6 in Claude Code today *is* the 1M-context model on a Max plan.
 
 (Pro plan is the exception: Pro users need "Enable usage credits" turned on in their Claude account settings to use 1M context. Max / Team / Enterprise have it on by default.)
 
@@ -174,39 +201,22 @@ Credit allocations: Pro $20/mo, Max 5x $100/mo, Max 20x $200/mo. **No rollover.*
 
 ### What this means for the lanes
 
-- **Setup A — Premium (Fable advisor + Opus driver):** Fable 5 advisor via `advisorModel: "fable"` in project settings — interactive session, Max-bundled. Opus 4.6 max driver on Max. GPT-5.5 xhigh reviewer on ChatGPT subscription.
-- **Setup B — Saver (OpusPlan):** **fully Max-bundled.** `opusplan` uses Opus (plan mode) + Sonnet (execute mode), both at 200K context — no `[1m]` variants, no credit drain. This is why Setup B now recommends `opusplan` instead of the old `sonnet[1m]` pin (#390).
-  - **⚠️ Avoid `sonnet[1m]`:** Sonnet with 1M context draws from your usage credits pool ($3/$15 per Mtok), NOT your Max subscription. The `/model` picker shows this explicitly. Plain `sonnet` (200K) or `opusplan` stays on Max.
-- **Reviewer (GPT-5.5 xhigh) in both lanes:** billed against your OpenAI account, completely separate from Anthropic.
+- **Setup A — Sonnet 5 + Fable advisor:** Sonnet 5's native 1M context — interactive session, Max-bundled, no `[1m]` suffix needed. Fable 5 advisor via `advisorModel: "fable"` — also Max-bundled. GPT-5.5 xhigh reviewer on ChatGPT subscription. Roughly 5x less Max quota consumed per turn than Setup B.
+- **Setup B — Opus 4.6 Stability:** Opus 4.6 max driver on Max, 1M context included at standard rates (see above). Fable 5 advisor, Max-bundled. GPT-5.5 xhigh reviewer, separate.
+- **Setup C — OpusPlan Hybrid:** **fully Max-bundled.** `opusplan` uses Opus (plan mode) + Sonnet (execute mode), both at their native context windows — no credit drain.
+  - **⚠️ Avoid `sonnet[1m]` as a manual pin outside Setup A/C:** if your provider or gateway doesn't resolve Sonnet 5 to its native 1M automatically, forcing a `[1m]`-suffixed pin on an older Sonnet can draw from your usage credits pool ($3/$15 per Mtok) instead of your Max subscription. The `/model` picker shows this explicitly — watch for "Draws from usage credits."
+- **Reviewer (GPT-5.5 xhigh) in all three triads:** billed against your OpenAI account, completely separate from Anthropic.
 - **CI loops that use `claude -p` post-June-15:** these now bill against the separate Anthropic credit pool, not your Max subscription. The wizard's CI shepherd loops (E2E scoring, weekly-update jobs) are local-only on the maintainer's machine and stay on Max; consumer-repo CI integrations may need to budget the new credit pool.
 
-### Caveat: Setup B's cost-saving has conditions
-
-The savings argument for Setup B is "Sonnet driver is cheaper than Opus driver per turn." **That's true at standard 200K context.** If your Sonnet driver needs to load >200K tokens (large diff, multi-file refactor, monorepo audit), the bill quietly flips:
-
-| Mode | Per-token rate | Pool |
-|---|---|---|
-| Setup A — Opus 4.6 1M | $5/$25 per Mtok | **Max subscription** |
-| Setup B — Sonnet 4.6 standard | $3/$15 per Mtok | **Max subscription** |
-| Setup B — Sonnet 4.6 1M | $3/$15 per Mtok | **Credits pool** |
-
-So **for context-heavy work that crosses 200K, Setup A on Max is actually cheaper than Setup B on credits** — because Setup A's Opus stays on the Max pool while Setup B's Sonnet 1M draws down a separately-metered $100/mo (Max 5x) or $200/mo (Max 20x) credit budget.
-
-**Practical guidance:**
-
-- **Subscription-first mindset (recommended):** Use Setup A unless you're confident the Sonnet driver in Setup B stays under 200K context. The Opus 4.6 max planner+driver combo lives entirely on Max — no credit-pool drawdown.
-- **Setup B is a real cost win only when:** the driver task fits in ≤ 200K (routine implementation, single-file work, small refactors, docs). Use B specifically for those, not as a blanket choice.
-- **Watch the picker.** When you swap to Sonnet 1M, Claude Code shows "Draws from usage credits" explicitly. That's your billing flip signal — choose Opus 1M instead if you want to stay on Max.
-
 ### Bottom line
 
-If you're using Claude Code interactively (you, in your terminal, doing `/sdlc` work), **both lanes ride your existing Max subscription**, and the `[1m]` alias is the same billable budget as plain `claude-opus-4-6`. No extra charges for the 1M context. The June 15 split only affects programmatic / headless / CI use of Claude Code.
+If you're using Claude Code interactively (you, in your terminal, doing `/sdlc` work), **all three full-discipline lanes ride your existing Max subscription**, and 1M context (whether Sonnet 5's native window or an explicit `[1m]` alias) doesn't add extra charges on Max/Team/Enterprise. The June 15 split only affects programmatic / headless / CI use of Claude Code.
 
 Watch the headless surface if you've automated `claude -p` calls in your project — those now bill differently as of June 15, 2026.
 
 ## Maintainer Override
 
-**Override at any time.** A blanket setup choice doesn't replace judgment per change. If you're touching CI but the change is a one-line typo, Setup B is fine. If you're touching docs but the section is the wizard's safety-critical hook ordering, Setup A is the call.
+**Override at any time.** A blanket setup choice doesn't replace judgment per change. If you're touching CI but the change is a one-line typo, Setup C is fine. If you're touching docs but the section is the wizard's safety-critical hook ordering, Setup A or B is the call.
 
 The wizard does not enforce setup lane selection — it documents the recommended default per change shape. Whatever ships is your call.
 
@@ -214,4 +224,4 @@ The wizard does not enforce setup lane selection — it documents the recommende
 
 - [`CLAUDE_CODE_SDLC_WIZARD.md`](CLAUDE_CODE_SDLC_WIZARD.md) — Full wizard doc, including Stability tier opt-in for the wider model choice
 - [`README.md` § Choosing Your Model](README.md#choosing-your-model) — Model selection philosophy
-- [`AGENTS.md`](AGENTS.md) — Codex/reviewer guidelines used in both lanes
+- [`AGENTS.md`](AGENTS.md) — Codex/reviewer guidelines used in all three full-discipline lanes

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to the SDLC Wizard.
 
 > **Note:** This changelog is for humans to read. Don't manually apply these changes - just run the wizard ("Check for SDLC wizard updates") and it handles everything automatically.
 
+## [1.84.0] - 2026-07-04
+
+### Fixed
+- **#436**: `codex-gate-check.sh` (cross-model review gate) and `tdd-pretool-check.sh` (TDD RED gate) printed the correct blocking warning text but always exited 0 — the exact condition Claude Code requires to actually deny a tool call is exit 2 + stderr, so neither hook ever blocked anything. Fixed both. `codex-gate-check.sh`'s commit-detection also went through 3 rounds of Codex cross-model review: an escaped-quote false negative (round 1), an over-broad fix that created a sibling-field false positive (round 2), and a field-scoped escape-aware fix that certified clean (round 3).
+- **#436**: `tdd-pretool-check.sh`'s `src/` gate only matched paths containing `/src/` (nested/absolute) — relative paths like `src/app.js` silently bypassed the gate entirely. Now matches both forms.
+- Distribution-parity gaps found via a new stronger test (`test_hooks_json_script_parity`, compares actual registered scripts per hook event, not just event-name presence): `codex-gate-check.sh` was never wired into the plugin's `hooks/hooks.json` (plugin users had zero cross-model gate); `goal-confidence-check.sh` was missing from the project's own `.claude/settings.json`; `token-spike-check.sh` was missing from the CLI template and from `cli/init.js`'s FILES array entirely (never actually copied to consumer repos by `npx ... init`).
+- `SDLC.md`'s own Recommended Model/Effort table and `CLAUDE_CODE_SDLC_WIZARD.md`'s Autocompact Tuning table still recommended `claude-opus-4-6` + blanket `max` via shell-rc env var — the exact anti-pattern that bit a real user (see [1.80.0] entry below). Both updated to model-aware guidance; SDLC.md's table no longer contradicts its own Lessons Learned entry on the same page.
+- **AI Setup Lanes v3 migration was incomplete** (Codex cross-model review caught this before release): the lane rewrite only updated the top lane tables in `AI_SETUP_LANES.md` — everything below (When-to-Use sections, Final Review Policy, Credit-Spend Warning, the entire Billing section) still described the old 3-lane structure with mismatched letters and stale model assignments (e.g. "Setups A and B use Opus 4.6 max" when the new Setup A is Sonnet 5). Fully reconciled to the 4-lane structure throughout. `README.md`'s "Choosing Your Model" section and `AGENTS.md`'s lane summary had the same staleness (README still told users to pin `claude-opus-4-6` + `CLAUDE_CODE_EFFORT_LEVEL=max` — the exact incident this release is about) and were rewritten to match. `skills/sdlc/SKILL.md` and `SDLC.md` said Sonnet 5's default effort is flat `xhigh`; corrected to match `AI_SETUP_LANES.md`'s tested position (`high` default, escalate to `xhigh` for hard tasks).
+- **Round 2/3 of the same Codex cross-model review** found the migration was still incomplete beyond what round 1 sampled: `skills/sdlc/SKILL.md`'s own frontmatter still hardcoded `effort: max`, directly contradicting its own model-aware guidance 20 lines below — removed the field (driver effort now comes from the session/lane, not the skill). `CLAUDE_CODE_SDLC_WIZARD.md` had far more embedded "Opus 4.6 flagship / blanket max" doctrine than the two sections already fixed: the "Recommended Effort Level" section, its skill-frontmatter-field example table, the "1M vs 200K Context Window" opening paragraph, the "OpusPlan Tier" and "Latest tier — Opus 4.8" sections (both said "the wizard's flagship recommendation is Opus 4.6 max" and "wizard standard is max on all Claude models"), the Advisor Model "Recommended pairings" table (still used the old "Setup A — Premium / Setup B — Saver" labels), the "Reading Usage Signals" table (said Setup A's autocompact override is 30% — that's the old Opus-era number; Setup A is now Sonnet 5, whose tested default is 75%), and the "Confidence Check" table (still said `max (default)` / `Run /effort max now` for every confidence level). Rewritten to the model-aware framing; a round-3 Codex recheck caught one more instance (an unqualified "flagship Opus 4.6" in the Setup 9.5 opt-in paragraph, now labeled "legacy flagship" to match `AI_SETUP_LANES.md`'s own terminology for Setup B) — treat any remaining bare "flagship"/"blanket max" reference anywhere in this file as a bug, not an intentional carryover. Two existing tests (`test_skill_frontmatter` in `test-cli.sh`, `test_skills_have_effort` in `test-self-update.sh`, `test_wizard_confidence_effort_max`/`test_skill_confidence_effort_max` in `test-hooks.sh`) still asserted the old blanket-`max`/frontmatter-`effort` policy as correct — updated to assert the new intentional design instead of silently masking it.
+- **Round 4 of the same review** found stale doctrine had spread well beyond the wizard doc into the actual setup/update flow users run: `skills/setup/SKILL.md`'s Step 9.5 menu never offered Sonnet 5 as a pinnable choice at all (only No pin / OpusPlan / "Flagship full" (Opus 4.6) / "Latest" (Opus 4.8, "effort: always max")) — rewritten to a 4-choice menu matching the current lanes (`[N]` no pin, `[s]` Sonnet 5 + Fable / Setup A, `[o]` OpusPlan Hybrid / Setup C now paired with an Opus 4.8 advisor, `[b]` Opus 4.6 Stability / Setup B). `skills/update/SKILL.md`'s Step 7.8 recommended `claude-opus-4-6` as the opusplan advisor (now `claude-opus-4-8`, matching the corrected wizard-doc guidance) and its Step 7.9 unconditionally pushed every user toward a persistent `CLAUDE_CODE_EFFORT_LEVEL=max` — rewritten to be driver-aware (only recommends the persistent `max` env pin for an Opus 4.6 driver; warns and recommends removal for a Sonnet 5 or Opus 4.8 driver, since that's the literal anti-pattern that caused this release's motivating incident). `CI_CD.md`, `tests/e2e/local-shepherd.sh`, `cli/lib/repo-complexity.js`, and `tests/test-repo-complexity.sh` had stale "wizard recommends Opus 4.6 max" comments/prose, corrected to Sonnet 5 / Setup A. `skills/setup/SKILL.md` and `skills/update/SKILL.md` both grew past their 20000-char audit threshold from these fixes — trimmed (condensed "Tell the user" prose in setup, trimmed 2 more of the oldest CHANGELOG-example bullets in update).
+- **Round 5 of the same review** found the most consequential gap yet: `hooks/model-effort-check.sh` (a live SessionStart hook, not just documentation) still only accepted `xhigh` or `max` as silent and warned "SDLC requires xhigh or max" on any other value — meaning it would actively nudge a Sonnet-5-at-`high` session (the wizard's own new recommended default) to bump to `xhigh` unnecessarily. Fixed: `high` is now also a silent floor, since it's Sonnet 5's and Fable's tested default; warning text and comments updated to match. Five existing hook tests baked in the old high-triggers-warning assumption (`test_model_effort_check_stale_effort` used `effortLevel:"high"` as its "should warn" fixture; the below-floor loop test iterated `high medium low` expecting all three to warn; two more fixtures used `"high"` incidentally while testing unrelated nested-CWD/size-cap behavior) — all four repointed to `medium`/`low` fixtures, plus one new test (`test_model_effort_check_high_silent`) added to lock in the new behavior. Also fixed a genuine remaining mismatch Codex's grep caught in `CLAUDE_CODE_SDLC_WIZARD.md`'s Step 9.5 opt-in paragraph: it described a 4th "Opus 4.8 escalation + Fable advisor" Step 9.5 menu choice that doesn't actually exist in the round-4-rewritten `skills/setup/SKILL.md` (that skill's menu is now N/s/o/b only — Opus 4.8 is session-level escalation via `/model`, not a persistent Step 9.5 pin) — corrected to describe the actual 4 choices.
+- **Round 6 of the same review** found the "Anti-Laziness Guidance for CLAUDE.md" section of `CLAUDE_CODE_SDLC_WIZARD.md` still told users to rely on `effort: max` "via SDLC skill frontmatter" — including a copy-paste CLAUDE.md snippet literally asserting "This project uses effort: max via SDLC skill frontmatter" — even though that frontmatter field was removed back in round 2, and this whole release's premise is that effort is model-aware, not blanket `max`. Rewrote the section's intro, snippet, and closing explanation to point at the actual current mechanism: per-session `/effort` matched to the active model (`AI_SETUP_LANES.md`), backstopped by `hooks/model-effort-check.sh`'s SessionStart nudge. Repo-wide grep confirmed no other `effort: max`/"SDLC skill frontmatter" references survive anywhere in the release diff.
+- **Round 7 of the same review** found 3 more real inconsistencies missed by prior sweeps: `CLAUDE_CODE_SDLC_WIZARD.md`'s Cache Poisoning "Detection signal" note and `SDLC.md`'s Effort warning callout still said the hook loud-warns below `xhigh`/`max` — stale after round 5 made `high` a silent floor too, and directly contradicting SDLC.md's own Recommended Effort table 2 lines above it. Both corrected to reference the model's actual floor. Separately, `CLAUDE_CODE_SDLC_WIZARD.md`'s "1M vs 200K" opt-in rationale and `skills/update/SKILL.md`'s Step 7.5 migration prompt both claimed `opus[1m]` "guarantees Opus 4.6 max" — but that alias auto-resolves to whichever Opus Claude Code currently considers latest (now Opus 4.8, not 4.6), directly conflicting with Setup B's explicit `claude-opus-4-6` pin (which exists specifically to avoid that ambiguity). Both reworded to clarify the alias isn't guaranteed to mean 4.6 and to point users who want 4.6 specifically at the explicit pin. Also fixed 3 stale implementation details in the wizard doc's MCP-vs-bash hook audit table for `model-effort-check.sh` (wrong env var name, a nonexistent 3-tier silent/soft/loud description, stale line count) — left as a separate, out-of-scope note: the same table has similarly stale line counts for 4 other hooks that predate this release entirely.
+- **Round 8** found the most impactful documentation bug in this whole review: `CLAUDE_CODE_SDLC_WIZARD.md`'s "Step 5: Create the TDD Hook" is a literal, mandatory-reading template — `skills/setup/SKILL.md` instructs Claude to read this file first because "it contains all templates... you CANNOT do this setup correctly without reading it first" — and that template was still the OLD advisory-only hook with no `exit 2`, even though the actual `hooks/tdd-pretool-check.sh` (fixed by #436, the headline fix of this very release) now blocks. Anyone running `/setup-wizard` manually (as opposed to `npx agentic-sdlc-wizard init`, which correctly copies the real file per `cli/init.js`) would have generated a broken, non-blocking TDD hook, missing #436's fix entirely. Fixed: added a minimal but real `exit 2` gate to the tutorial code block, with a note pointing at the actual shipped hook for the production-hardened (session-scoped) version. Also fixed the same false "does not block" claim in the MCP-vs-bash hook-audit table's `tdd-pretool-check.sh` row, and softened an "all 5 wizard hooks" framing that implied completeness when the project now registers 9.
+- **Round 9** found the manual tutorial path was still worse than round 8's fix addressed: (a) that very fix had reintroduced the `#436`-round-1 relative-path bug into the tutorial's `src/` pattern (matched `*"/src/"* ` only, no `"src/"*` clause) — fixed, and now locked in by a dedicated regression check; (b) Step 4's light-hook auto-invoke line and Step 6's SDLC skill description omitted `release/publish/deploy` coverage present in the real shipped `hooks/sdlc-prompt-check.sh` and `skills/sdlc/SKILL.md` — added, matching the real files exactly; (c) the manual walkthrough only ever templates 2 of the wizard's 9 production hooks, with no path to the other 7 (`codex-gate-check.sh` among them — this release's own headline fix). Rather than hand-writing 7 more tutorials that would just recreate the same drift class, Step 5 now explicitly marks itself illustrative-only and points at `npx agentic-sdlc-wizard@latest init` for the complete, always-in-sync set; `skills/setup/SKILL.md`'s Step 10 gained a guardrail (fewer than 9 files in `.claude/hooks/` → tell the user to run the CLI install first, not hand-type the rest). New test `tests/test-wizard-doc-hook-templates.sh` mechanically checks every doc-templated hook against its real file for `exit 2` parity and specifically guards the relative-path regression — the shipped version of the post-mortem commitment already recorded in `SDLC.md`'s Lessons Learned; TDD-verified RED (failed against the pre-round-8 doc and against the round-9-buggy doc) before GREEN.
+- **Round 10** found the new test itself wasn't wired up: `tests/test-workflow-triggers.sh`'s orphaned-script check failed because `test-wizard-doc-hook-templates.sh` was never added to `.github/workflows/ci.yml`, meaning it would pass locally but never actually run in CI. Added the missing step, which then surfaced a second, cascading gap the same check independently catches: `CONTRIBUTING.md`'s test-script list (used as the "how to run tests locally" reference) was now missing the same file relative to `ci.yml`. Added it there too. Full sweep re-run clean, including `test-workflow-triggers.sh` itself (169/169, up from 168 — the orphan check now has one more script to track).
+- **Round 11: CERTIFIED** (11 rounds total). Codex verified round 10's CI-wiring fix and found nothing new. Actual CI on the opened PR then caught three things the local sweep and 11 rounds of review both missed: (1) `skills/update/SKILL.md`'s round-4 driver-aware rewrite of Step 7.9 had silently dropped a distinct, pre-existing warning — that CC ignores an `effortLevel: "max"` set only in `settings.json` (not the env var) since it's session-only and doesn't persist — while restructuring around Opus-4.6-vs-Sonnet-5/Opus-4.8 driver awareness; `tests/test-model-config-batch.sh`'s `test_update_effort_step_warns_settings_only_max` caught the regression. Fixed by merging both concerns back into the Opus 4.6 branch of Step 7.9. (2) `.github/workflows/release-dry-run.yml`'s path-assertion step asserted on `.files[]?.path` at the JSON top level, but a newer npm CLI (11.16.0) wraps `npm publish --dry-run --json` output under the package-name key — pre-existing drift unrelated to this branch's content (confirmed: not part of this PR's diff, and main's last green run predates the npm version bump), but blocking regardless. Fixed the jq path to `.[] | .files[]?.path`, which doesn't need to hardcode the package name. (3) `tests/test-wizard-doc-hook-templates.sh` (new in round 9) was committed without the executable bit — `bash tests/foo.sh` doesn't need it, but `ci.yml` invokes it as `./tests/foo.sh`, which does; CI failed with "Permission denied", exit 126. Fixed with `chmod +x`, plus a new `test_all_test_scripts_executable` check in `tests/test-workflow-triggers.sh` (170/170, up from 169) so any future test script missing the bit fails locally, not just in CI. All three verified locally before pushing; full sweep re-run clean.
+
+### Added
+- New `Stop` hook (`codex-review-stop-check.sh`) — non-blocking backstop for sessions that end with significant uncommitted changes and no REVIEWED/CERTIFIED cross-model review artifact, closing the gap where `codex-gate-check.sh` (which only fires on `git commit`) never gets a chance to trigger because a session simply never attempts a commit.
+- **AI Setup Lanes v3**: `AI_SETUP_LANES.md` rewritten to a 4-lane structure (Sonnet 5 `high`→`xhigh` + Fable recommended, Opus 4.6 max for proven stability, opusplan, Lite) reflecting Sonnet 5's June 30 launch. `model-effort-check.sh` now recommends effort per model instead of a blanket `max`.
+- **Cowork section** added to `CLAUDE_CODE_SDLC_WIZARD.md` — the `cowork/` plugin (prompt-based hooks for Claude Cowork, shipped in a prior release) had zero cross-reference from the main wizard doc until now.
+
+### Why
+Maintainer pain event (2026-07-04): "I hate having to remind 'don't forget to cross-model review with codex.'" Root-cause audit found the enforcement mechanisms this wizard exists to provide were mechanically non-functional — hooks that looked right but never blocked anything. Fixed via TDD with 188 hook tests (up from 185), all verified against actual exit codes, not just warning text. Separately, a real Sonnet 5 migration incident (blanket `CLAUDE_CODE_EFFORT_LEVEL=max` silently overriding `/effort xhigh` after a model switch) exposed that the wizard's own docs still recommended the exact env-var pattern that caused it — fixed at the source instead of just noting the gotcha.
+
 ## [1.83.0] - 2026-06-11
 
 ### Fixed