agentic-sdlc-wizard 1.85.0 → 1.87.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.85.0",
+      "version": "1.87.0",
       "author": {
         "name": "Stefan Ayala"
       },

package/.claude-plugin/plugin.json

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

package/AI_SETUP_LANES.md

@@ -9,13 +9,17 @@ This is **guidance, not a hard rule**. Maintainer override is always allowed.
 | 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 |
+| **Driver** | Sonnet 5 (`claude-sonnet-5`) | `medium` default, escalate `high` → `xhigh` for hard tasks |
+| **Reviewer** | Codex (GPT-5.6 Sol) xhigh | — |
+| **Escalation** | Opus 4.8 xhigh takes over as driver (or run a Fable 5 review pass) | When stuck (2 failed attempts / LOW confidence) or high-stakes |
 
-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).
+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%) and generally uses less Max quota — but the savings are not a fixed ratio: Sonnet 5's newer tokenizer produces ~30% more tokens for the same text than Opus 4.6's (per Anthropic's pricing docs), and community cost reports suggest the advantage narrows at `high`/`xhigh`. No controlled Sonnet-5-vs-Opus-4.6 quota measurement exists — check your own burn with `/usage`. Fable 5 advises at key decision points via native `advisorModel` (v2.1.170+). GPT-5.6 Sol 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.
 
-**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.
+**Effort escalation ladder:** Start at `medium` — CodeRabbit's testing found it captures most of Sonnet 5's upside at the lowest cost. Raise to `high` when medium struggles, `xhigh` for hard debugging, multi-file migrations, or long agent runs. `max` is rarely worth it — doubles cost for marginal gains per the same CodeRabbit testing.
+
+**Two escalation axes — don't conflate them.** The effort ladder above raises reasoning *within* the Sonnet 5 driver. Model escalation is a different move: it *swaps the driver* — after 2 failed attempts, LOW confidence, or on a high-stakes change, Opus 4.8 xhigh takes over as driver (or run a Fable 5 review pass on the diff). Cranking Sonnet's effort past `xhigh` is not the escalation path.
+
+**Advisor failure has a fallback, not a shrug.** `advisor()` is a server-side tool and does fail during API incidents. When it errors, spawn a Fable subagent as the fallback reviewer — the same rule the `/sdlc` skill carries ("if down, spawn Fable subagent"). The advisor check is never skipped; only its transport changes.
 
 **Requires:** Claude Code v2.1.197+ (Sonnet 5 alias resolution), Fable 5 access for advisor.
 
@@ -25,7 +29,7 @@ The new standard. Sonnet 5 beats Opus 4.6 on every coding benchmark (SWE-bench V
 |------|-------|--------|
 | **Advisor** | Fable 5 (via `advisorModel: "fable"`) | `high` (server-side) |
 | **Driver** | Opus 4.6 (`claude-opus-4-6`) | `max` |
-| **Reviewer** | Codex (GPT-5.5) xhigh | — |
+| **Reviewer** | Codex (GPT-5.6 Sol) 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.
 
@@ -37,10 +41,10 @@ The consistency-first lane. Opus 4.6 is the only model where `max` effort works
 |------|-------|--------|
 | **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 | — |
+| **Driver** | Sonnet 5 (auto execute mode) | `medium`, escalate `high` for hard runs |
+| **Reviewer** | Codex (GPT-5.6 Sol) 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.
+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.6 Sol 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.
 
@@ -56,7 +60,7 @@ The "just do the thing" lane. No TDD enforcement, no cross-model review, no plan
 
 ## When to Use Setup A
 
-The default choice for most SDLC work — full discipline (TDD, cross-model review) at a fraction of Setup B's quota cost:
+The default choice for most SDLC work — full discipline (TDD, cross-model review) at generally lower quota cost than Setup B (see Credit-Spend Warning below):
 
 - Feature implementation and routine development
 - Documentation and examples
@@ -116,11 +120,13 @@ Setup D is for work where SDLC discipline overhead exceeds the value:
 
 ## Final Review Policy
 
-**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.
+**Setups A, B, and C end at GPT-5.6 Sol 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 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.
+If GPT-5.6 Sol isn't available on your OpenAI account, Codex auto-falls back to Terra — still keep `model_reasoning_effort="xhigh"`. Lower reasoning misses subtle bugs that the reviewer is the last gate to catch.
+
+**Escalation for unusually risky PRs:** `xhigh` is the evidence-based default — OpenAI's own migration guidance is to preserve the prior effort baseline, and no published data shows `max` or Pro mode catching meaningfully more real bugs than `xhigh` on ordinary PR review. For a PR you'd genuinely lose sleep over (security-sensitive, high blast radius, touches the installer or a consumer-facing template), escalate the reviewer to `max` or Pro mode — a once-per-PR gate is exactly the kind of low-frequency, high-stakes call site where the extra cost is easiest to justify. Don't make it the default.
 
 ## Version Requirement
 
@@ -140,10 +146,10 @@ If the advisor returns "Advisor unavailable," the server-side harness failed to
 
 **Step 1 — restart the session.** Exit and run `claude` (not `--resume`). A fresh process re-initializes the server handshake. This resolves most advisor failures.
 
-**Step 2 — if the API incident persists:**
+**Step 2 — if the API incident persists, swap the transport, not the check:**
 
-- 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.
+- Spawn a Fable subagent as the fallback reviewer — the `/sdlc` skill's standing rule ("if down, spawn Fable subagent"). Batch your plan or open questions into one subagent consult at each point where you'd have called `advisor()`. Runs interactively on your Max subscription like any other agent.
+- Keep driving with your lane's model (`/model sonnet` for Setup A, `/model claude-opus-4-6` for Setup B). The subagent replaces the advisor's transport; the Codex xhigh PR gate remains the separate final backstop, not a substitute for the advisor check.
 
 **Last resort (scripted/CI only):**
 
@@ -155,15 +161,15 @@ Whichever path you use, the cross-model PR review gate still applies.
 
 ## Credit-Spend Warning
 
-**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:
+**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 at `medium`/`high` generally uses less quota for comparable benchmark results (the advantage narrows at `xhigh` — more turns per task plus tokenizer overhead). If you're hitting the cap mid-session on Setup B:
 
-- Drop to Setup A (Sonnet 5) for the remainder of the day — same discipline, far less quota burn
+- Drop to Setup A (Sonnet 5) for the remainder of the day — same discipline, typically lower quota burn (widest advantage at `medium`)
 - 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
+- Or use Sonnet directly for the final mechanical edits, then run the GPT-5.6 Sol reviewer over the whole diff at the end
 
 **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.
+The reviewer (GPT-5.6 Sol xhigh) is billed against your OpenAI account, separately. Watch both bills.
 
 ## Autocompact Thresholds
 
@@ -201,11 +207,11 @@ Credit allocations: Pro $20/mo, Max 5x $100/mo, Max 20x $200/mo. **No rollover.*
 
 ### What this means for the lanes
 
-- **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 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.6 Sol xhigh reviewer on ChatGPT subscription. Generally lower Max quota consumption than Setup B at the `medium` default (savings shrink at higher effort).
+- **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.6 Sol 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.
+- **Reviewer (GPT-5.6 Sol 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.
 
 ### Bottom line

package/CHANGELOG.md

@@ -4,6 +4,34 @@ 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.87.0] - 2026-07-14
+
+### Added
+- **🏆 First external contribution in this repo's history: [@thejesh23](https://github.com/thejesh23)** (#444, PR #445 — merged under his authorship). GitHub Copilot CLI ≥ 1.0.65 tightened `argument-hint` frontmatter validation to string-only and silently dropped all 7 wizard skills from its command menu. Bare brackets (`argument-hint: [task description]`) parse as a YAML flow sequence, not a string — the feedback skill's hint even parsed as an array wrapping a *mapping* — and Claude Code's lenient rendering had hidden it since the fields were introduced. His report pinned the exact breaking version with primary-source links and listed every affected file (it matched our own repo-wide sweep exactly); his fix updated the live skills and the `cowork/` copies together. Out of 300+ merged PRs, contributor #1. Maintainer's words, on the record: *"he deserves it and I am forever grateful."*
+- **#444 regression test** (PR #447): `test_argument_hint_frontmatter_is_string` parses every live + cowork SKILL.md frontmatter with real YAML and fails on any non-string `argument-hint`; also guards the wizard doc's copy-source examples (the frontmatter reference-table cell was #445's one untouched straggler — consumers copy these blocks, so an unquoted example re-inherits the bug into generated repos). Hardened per Codex round-1 finding: the grep uses `argument-hint:[[:space:]]*\[` because an exactly-one-space pattern false-greened on zero/two-space variants (mutation-verified both directions). Anti-vacuity guards prevent the test from passing on zero files or unparsed frontmatter. Cross-vendor SKILL.md compatibility is now tracked as ROADMAP #448.
+
+### Changed
+- **GPT-5.6 Sol replaces GPT-5.5 as the cross-model reviewer** across all live guidance (#439, PR #441): `AI_SETUP_LANES.md`, `README.md`, `CLAUDE_CODE_SDLC_WIZARD.md`, both sdlc SKILL.md copies, `AGENTS.md`, repo `CLAUDE.md`. The unpinned auto-detect design is deliberately preserved (Codex CLI resolves your account's best model — proven live when it picked up Sol with zero config change); fallback chain documented as Sol → Terra. Reviewer effort stays `xhigh` per OpenAI's own migration guidance; Pro/`max` documented as escalation for unusually risky PRs. Historical citations (vending-bench, E2E audit, CHANGELOG) explicitly untouched and regression-guarded — rewriting them would falsify what actually ran.
+- **Sonnet 5's documented default effort is now `medium`** (was `high`), and the "~5x less Max quota" claim is gone (#440, PR #443). Codex traced the 5x figure to commit `ab6fc9c` with zero supporting measurement anywhere; all 8 instances across 6 live-guidance files replaced with qualified language sourced to Anthropic's tokenizer note (Sonnet 5's newer tokenizer produces ~30% more tokens than Opus 4.6's for the same text; community cost reports suggest the advantage narrows at `high`/`xhigh`; no controlled measurement exists — check `/usage`). CodeRabbit — the source the wizard already cited — actually recommends `medium`. Escalation ladder is now `medium` → `high` → `xhigh`; fresh Fable and Codex opinions independently converged on this. `hooks/model-effort-check.sh` floor updated to match so the hook doesn't nag users following the wizard's own default (`medium` now silent; explicit `low` and the settings-only-`max` quirk still warn; worst-case warning output re-fitted under the 500-char cap after Codex caught the cap test had gone vacuous). 4 new mutation-verified doc-consistency tests plus a repo-wide guard banning the unqualified-multiplier phrasing class.
+- **Setup A semantics made explicit** (PR #446, README "Reading Setup A precisely" + `AI_SETUP_LANES.md`): effort escalation happens *inside* the Sonnet 5 driver; model escalation *swaps the driver* to Opus 4.8 xhigh (2 failed attempts / LOW confidence / high-stakes); `advisor()` failure falls back to spawning a Fable subagent — never to skipping the check. The advisor-outage procedure's "continue with no advisor" path (which directly contradicted the new rule two sections above it — Codex round-1 catch) now routes to the subagent fallback: swap the transport, not the check. Section-scoped negative test assertions keep the skip-path from returning.
+
+### Fixed
+- ROADMAP #236 bloat-hunt follow-through (PR #440): hook/test cleanups, ROADMAP archive split.
+- ROADMAP #434 sub-item statuses corrected against git history instead of re-asserted (PR #442).
+
+### Why
+Seven consumer-affecting commits had accumulated on main since v1.86.0 (July 5) with no npm release — discovered when the repo's first external bug report (#444) revealed that `npx agentic-sdlc-wizard@latest init` was still installing skills Copilot CLI silently drops even after the fix was merged and celebrated, with nothing in the process that would ever have prompted a release. Merge-to-main does not publish; only a `v*` tag does. Release-drift detection (own-package npm-vs-main watcher, in the style of `cc-version-drift.yml`) is tracked as ROADMAP #449 so this class of stranding is machine-caught, not memory-caught.
+
+## [1.86.0] - 2026-07-05
+
+### Fixed
+- **#437: `codex-gate-check.sh` stale-certification loophole.** A CERTIFIED/REVIEWED `handoff.json` status was checked as a literal string with no freshness check — any number of commits made after certification would sail through the gate on the same stale status forever. Proven live during the v1.84.0 release: 2 real post-certification commits both passed the gate on a round-11 CERTIFIED handoff that was never re-issued. Fixed: certification now records `commit_sha` (HEAD at cert time) in `handoff.json`; the gate compares it to current HEAD and treats a mismatch — or a missing field, e.g. an old-format handoff.json predating this fix — as stale (exit 2, same as an uncertified commit). This allows exactly one commit after certification and blocks the next one until re-cert. `CODEX_GATE_SKIP=1` remains the logged-justification escape hatch. TDD: 2 new tests (`test_codex_gate_blocks_stale_certification_after_new_commit`, `test_codex_gate_blocks_missing_commit_sha_as_stale`) proven RED against the unmodified hook, GREEN after; 2 existing tests updated to real git-repo fixtures with a matching `commit_sha` (191/191 hook tests green, up from 189).
+- **The protocol docs needed updating in 3 separate places, not 1 — Codex cross-model review caught 2 of them.** `CLAUDE_CODE_SDLC_WIZARD.md` documents the cross-model review protocol twice (a condensed summary section and a fuller tutorial section), each with its own prose instruction *and* its own ASCII flow diagram — 7 total "reached CERTIFIED, now what" decision points. Round 1 caught a missed prose instruction in the tutorial section; round 2's mutation testing proved my first regression test (a whole-file count comparison) had real slack and, while investigating that, surfaced a 3rd, entirely separate miss: the condensed section's own flow diagram, never touched by anything. All 7 decision points (3 prose instructions + 4 diagram exits across both sections) now write `"commit_sha"` on the same line. `skills/sdlc/SKILL.md` updated too. Replaced the count-based regression test with a per-line proximity check (`test_wizard_doc_certified_paths_all_mention_commit_sha` in `tests/test-doc-consistency.sh`) that can't be fooled by aggregate slack — proved it independently by mutating each of the 3 known-fragile spots one at a time and confirming each is individually caught (53/53 at baseline).
+- **Latent bug in `tests/test-self-update.sh`'s multi-reviewer checks**, exposed (not caused) while trimming `skills/sdlc/SKILL.md` back under its 20K-char cap: 3 test functions used an unescaped `?` as a quantifier (`multi.?review`) inside plain `grep -qi`, which runs basic regex where a bare `?` is a literal character, not "0 or 1 of the preceding." The check had only ever passed via an incidental phrase collision elsewhere in the file ("parallel tasks... `sdlc-reviewer`" in an unrelated Context Management bullet, not actual multi-reviewer guidance) — trimming that unrelated bullet removed the accidental match and surfaced the real bug. Fixed by adding `-E` (extended regex) so `?` behaves as intended; verified it now matches the genuine `**Multi-reviewer:**` guidance directly (153/153 tests green).
+
+### Why
+Post-ship retrospective on v1.84.0 (2026-07-05) independently re-confirmed a gap already tracked as ROADMAP #437 (filed 2026-07-04 while shipping #436). Design settled with Fable's input in the same retrospective, implemented as a standalone TDD PR per that plan — kept separate from the doc-only v1.85.0 release since this one changes actual hook behavior on a security-relevant gate.
+
 ## [1.85.0] - 2026-07-05
 
 ### Fixed

package/CLAUDE_CODE_SDLC_WIZARD.md

@@ -253,11 +253,11 @@ Claude Code's **effort level** controls how much thinking the model does before
 
 | Model | Recommended Effort | Why |
 |-------|--------------------|-----|
-| Sonnet 5 (recommended default) | `high`, escalate to `xhigh` for hard tasks | `xhigh` as a blanket default doubles cost for marginal gains per CodeRabbit testing; `high` is the tested sweet spot |
+| Sonnet 5 (recommended default) | `medium`, escalate to `high`/`xhigh` for hard tasks | CodeRabbit testing: `medium` captures most of the upside at the lowest cost; blanket `xhigh`/`max` defaults add cost for marginal gains |
 | Opus 4.8 (escalation only) | `xhigh` | `max` triggers excessive reasoning on 4.7/4.8 — documented 40-60x cache-token jump vs `high` (see "Opus 4.6 Stability" tier below) |
 | Fable 5 (advisor) | `high` (its own designed default) | Adaptive thinking always on; `xhigh`/`max` mainly move the thinking-token budget with small marginal gain for review work |
 | Opus 4.6 (Stability lane) | `max` | The one model where `max` doesn't overthink — no `xhigh` support at all (only low/medium/high/max) |
-| OpenAI/Codex (cross-model reviewer) | `xhigh` (their highest) | Always — lower reasoning misses subtle bugs the reviewer exists to catch |
+| OpenAI/Codex (cross-model reviewer) | `xhigh` default, escalate to `max`/Pro for unusually risky PRs | Lower reasoning misses subtle bugs the reviewer exists to catch; see `AI_SETUP_LANES.md`'s Final Review Policy for when to escalate |
 
 **Strict effort behavior (Opus 4.7+, carried forward in 4.8):**
 - **`xhigh` was introduced in 4.7** — sits between `high` and `max`, designed for coding and agentic work (30+ minute tasks with token budgets in the millions)
@@ -341,7 +341,7 @@ CC 2.1.117 expanded the `cleanupPeriodDays` setting to also cover `~/.claude/tas
 ---
 name: sdlc
 description: Full SDLC workflow for implementing features, fixing bugs, refactoring code
-argument-hint: [task description]
+argument-hint: "[task description]"
 ---
 
 ## Task
@@ -433,7 +433,7 @@ Skills support these frontmatter fields:
 | `effort` | Set reasoning effort level | `effort: high` |
 | `paths` | Restrict skill to specific file patterns | `paths: ["src/**/*.ts", "tests/**"]` |
 | `context` | Context mode (`fork` = isolated subagent) | `context: fork` |
-| `argument-hint` | Hint for `$ARGUMENTS` placeholder | `argument-hint: [task description]` |
+| `argument-hint` | Hint for `$ARGUMENTS` placeholder (quote it — bare brackets parse as a YAML array and break strict loaders like Copilot CLI, #444) | `argument-hint: "[task description]"` |
 | `disable-model-invocation` | Prevent skill from being auto-invoked by model | `disable-model-invocation: true` |
 
 **Key fields explained:**
@@ -526,7 +526,7 @@ See the dedicated subsection under [Tasks System](#tasks-system-v2116) (above, i
 
 ### MCP-tool hooks audit (ROADMAP #218, CC 2.1.118)
 
-CC 2.1.118 introduced `type: "mcp_tool"` for hooks — a hook can now directly invoke an MCP tool instead of running a bash script. **Audit (2026-04-26) of the 5 wizard hooks that existed at the time concluded: none migrate, all stay bash.** This subsection documents the per-hook reasoning so future audits don't redo the work; if a future PR migrates a hook to MCP, update this entry with the new rationale rather than deleting it. **Not yet re-audited**: 4 hooks shipped since 2026-04-26 (`goal-confidence-check.sh`, `codex-gate-check.sh`, `token-spike-check.sh`, `codex-review-stop-check.sh`) — the project now registers 9 hooks total (see `.claude/settings.json`), but this table only covers the original 5.
+CC 2.1.118 introduced `type: "mcp_tool"` for hooks — a hook can now directly invoke an MCP tool instead of running a bash script. **Audit (2026-04-26) of the 5 wizard hooks that existed at the time concluded: none migrate, all stay bash.** This subsection documents the per-hook reasoning so future audits don't redo the work; if a future PR migrates a hook to MCP, update this entry with the new rationale rather than deleting it. **Not yet re-audited**: 3 hooks shipped since 2026-04-26 (`codex-gate-check.sh`, `token-spike-check.sh`, `codex-review-stop-check.sh`) — the project now registers 8 hooks total (see `.claude/settings.json`), but this table only covers the original 5.
 
 **Decision criteria applied** (any one rules out MCP):
 
@@ -536,11 +536,11 @@ CC 2.1.118 introduced `type: "mcp_tool"` for hooks — a hook can now directly i
 
 **Per-hook decision** (each row applies at least one criterion explicitly):
 
-- **`sdlc-prompt-check.sh`** (UserPromptSubmit, ~132 lines) — emits the SDLC BASELINE text on every prompt; writes effort-bump signals to `~/.cache/sdlc-wizard/effort-signals.log` for self-consumption on next invocation. Decision: **Stay bash.** Portability criterion: same script ships to Codex sibling unchanged. Local-state criterion: signal log is local-only.
-- **`instructions-loaded-check.sh`** (~202 lines) — InstructionsLoaded event; validates SDLC files exist, fetches npm `latest` with daily file cache (`~/.cache/sdlc-wizard/npm-latest.json`), emits staleness warnings. Decision: **Stay bash.** Portability criterion: Codex sibling has its own equivalent of session-start validation; bash port is direct. Local-state criterion: cache file is local.
-- **`tdd-pretool-check.sh`** (~115 lines) — PreToolUse on Write/Edit/MultiEdit; emits a TDD reminder, and (since #436) **blocks** with `exit 2` when a `src/**` write happens before any test file was touched this session (an edit-ordering proxy for TDD RED, session-scoped via a cache-dir sentinel). Decision: **Stay bash.** Fail-closed gating criterion applies now that this hook blocks: bash `exit 2` fails closed by definition, whereas an `mcp_tool` hook's block decision is lost if the MCP server errors — wrong default for a gate. Portability criterion: still trivially portable.
-- **`model-effort-check.sh`** (~80 lines) — SessionStart event; reads `CLAUDE_CODE_EFFORT_LEVEL` env var (falling back to `effortLevel` in the settings cascade), emits nothing when effort is `high`/`xhigh`/`max`, otherwise a loud warning. Decision: **Stay bash.** Portability criterion: env-var read maps 1:1 to any agent runtime. Local-state criterion: not applicable, hook is stateless.
-- **`precompact-seam-check.sh`** (~125 lines) — PreCompact event (matcher: `manual`); reads `.reviews/handoff.json` via jq, blocks manual `/compact` with exit 2 + stderr message when status is `PENDING_*` and the linked PR (if any) isn't merged. Decision: **Stay bash.** Fail-closed gating criterion: bash exit 2 fails closed by definition; an MCP `mcp_tool` hook returning `decision: "block"` works on the happy path, but if the MCP server crashes/times out the action proceeds — that flips the safety property from fail-closed to fail-open. For a hook whose entire job is to prevent context loss at bad seams, fail-open is the wrong default.
+- **`sdlc-prompt-check.sh`** (UserPromptSubmit, ~137 lines) — emits the SDLC BASELINE text on every prompt (fires-once-per-session sentinel), plus a setup-wizard redirect when SDLC.md/TESTING.md are missing. Decision: **Stay bash.** Portability criterion: same script ships to Codex sibling unchanged. Local-state criterion: sentinel cache is local-only. **#236(b) 2026-07-06:** the ROADMAP #195 effort-bump signal log described here previously was removed — never fired in ~2 months of live use.
+- **`instructions-loaded-check.sh`** (~291 lines) — InstructionsLoaded event; wizard-version + CC-version staleness nudges (both npm-cached daily), cross-model-review staleness check, autocompact compound-misconfig check, dual-channel-install check. Decision: **Stay bash.** Portability criterion: Codex sibling has its own equivalent of session-start validation; bash port is direct. Local-state criterion: cache files are local. **#236(b) 2026-07-06:** the SDLC.md/TESTING.md missing-file warning previously described here was removed (redundant with `sdlc-prompt-check.sh`'s louder version).
+- **`tdd-pretool-check.sh`** (~129 lines) — PreToolUse on Write/Edit/MultiEdit; emits a TDD reminder, and (since #436) **blocks** with `exit 2` when a `src/**` write (or `SDLC_TDD_SRC_PATTERN`-overridden path, added #236(b) for this repo's own `src/`-less dogfooding) happens before any test file was touched this session (an edit-ordering proxy for TDD RED, session-scoped via a cache-dir sentinel). Decision: **Stay bash.** Fail-closed gating criterion applies now that this hook blocks: bash `exit 2` fails closed by definition, whereas an `mcp_tool` hook's block decision is lost if the MCP server errors — wrong default for a gate. Portability criterion: still trivially portable.
+- **`model-effort-check.sh`** (~87 lines) — SessionStart event; reads `CLAUDE_CODE_EFFORT_LEVEL` env var (falling back to `effortLevel` in the settings cascade), emits nothing when effort is `high`/`xhigh`/`max`/unset, otherwise a loud warning. Decision: **Stay bash.** Portability criterion: env-var read maps 1:1 to any agent runtime. Local-state criterion: not applicable, hook is stateless. **#236(b) 2026-07-06:** unset used to loud-warn too (CC's own default state) — now silent; only an explicit low-effort value or the settings-only-`max` quirk warns.
+- **`precompact-seam-check.sh`** (~101 lines) — PreCompact event (matcher: `manual`); blocks manual `/compact` with exit 2 + stderr message when a git rebase/merge/cherry-pick is in progress. Decision: **Stay bash.** Fail-closed gating criterion: bash exit 2 fails closed by definition; an MCP `mcp_tool` hook returning `decision: "block"` works on the happy path, but if the MCP server crashes/times out the action proceeds — that flips the safety property from fail-closed to fail-open. For a hook whose entire job is to prevent context loss at bad seams, fail-open is the wrong default. **#236(b) 2026-07-06:** this hook used to also block on `.reviews/handoff.json` being `PENDING_*` (mid cross-model-review-round), with 3 self-heal paths mitigating that branch's false-positive rate — removed; every real firing on record was a false positive, never a true positive.
 
 **When to revisit this audit:**
 
@@ -1085,9 +1085,9 @@ This is **Setup C (OpusPlan Hybrid/Saver)** in `AI_SETUP_LANES.md`. CC's native
 
 | Layer | Setup C (OpusPlan) | Setup A (default) | Setup B (Stability) |
 |-------|--------------------|--------------------|----------------------|
-| Planner | Opus 4.8 `xhigh` (Plan Mode) | Sonnet 5 `high`→`xhigh` | Opus 4.6 `max` |
-| Driver | Sonnet 5 `high` (execute mode) | Sonnet 5 `high`→`xhigh` | Opus 4.6 `max` |
-| Reviewer | GPT-5.5 xhigh | GPT-5.5 xhigh | GPT-5.5 xhigh |
+| Planner | Opus 4.8 `xhigh` (Plan Mode) | Sonnet 5 `medium`→`high`→`xhigh` | Opus 4.6 `max` |
+| Driver | Sonnet 5 `medium` (execute mode) | Sonnet 5 `medium`→`high`→`xhigh` | Opus 4.6 `max` |
+| Reviewer | GPT-5.6 Sol xhigh | GPT-5.6 Sol xhigh | GPT-5.6 Sol xhigh |
 
 **How to opt in:**
 ```json
@@ -1110,7 +1110,7 @@ Set effort per-session with `/effort` (planner `xhigh`, driver `high`) rather th
 **Prove-It Gate (#233 acceptance criterion):** mixed-mode ships only if pair-tested on 3+ simple repos shows Sonnet-coder + Opus-reviewer produces ≥ same SDLC scores as full-Opus baseline. The first version of the heuristic ships v1.38.0; pair-test results land in CHANGELOG before recommending mixed-mode as the default for any tier.
 
 **Tradeoffs (be honest):**
-- The Sonnet driver will drop some fine-grained self-review moves compared to an Opus-coder run — it's fast, less deliberate. The Opus planner and GPT-5.5 reviewer catch them, but expect more "fix in round 2" cycles.
+- The Sonnet driver will drop some fine-grained self-review moves compared to an Opus-coder run — it's fast, less deliberate. The Opus planner and GPT-5.6 Sol reviewer catch them, but expect more "fix in round 2" cycles.
 - Mixed-mode disables auto-mode (same as any pinned model). The pin is per-session — to switch back, remove the `model` line.
 
 ### Latest tier — Opus 4.8 (escalation model, #395)
@@ -2213,7 +2213,7 @@ chmod +x .claude/hooks/sdlc-prompt-check.sh
 
 ## Step 5: Create the TDD Hook
 
-**Illustrative, not exhaustive:** this teaches the PreToolUse/exit-2 blocking mechanic with one hook. The wizard ships **9 production hooks total** — only this one and Step 4's light hook have hand-typed templates in this doc; the other 7 (`codex-gate-check.sh`, `goal-confidence-check.sh`, `instructions-loaded-check.sh`, `model-effort-check.sh`, `precompact-seam-check.sh`, `codex-review-stop-check.sh`, `token-spike-check.sh`) don't, because there's no substitute for the real files. **For the complete, always-in-sync set, run `npx agentic-sdlc-wizard@latest init`** instead of hand-building hooks 3-9 from prose descriptions elsewhere in this doc.
+**Illustrative, not exhaustive:** this teaches the PreToolUse/exit-2 blocking mechanic with one hook. The wizard ships **8 production hooks total** — only this one and Step 4's light hook have hand-typed templates in this doc; the other 6 (`codex-gate-check.sh`, `instructions-loaded-check.sh`, `model-effort-check.sh`, `precompact-seam-check.sh`, `codex-review-stop-check.sh`, `token-spike-check.sh`) don't, because there's no substitute for the real files. **For the complete, always-in-sync set, run `npx agentic-sdlc-wizard@latest init`** instead of hand-building hooks 3-8 from prose descriptions elsewhere in this doc.
 
 Create `.claude/hooks/tdd-pretool-check.sh`:
 
@@ -2274,7 +2274,7 @@ Create `.claude/skills/sdlc/SKILL.md`:
 ---
 name: sdlc
 description: Full SDLC workflow for implementing features, fixing bugs, refactoring code, testing, releasing, publishing, and deploying. Use this skill when implementing, fixing, refactoring, testing, adding features, building new code, or releasing/publishing/deploying.
-argument-hint: [task description]
+argument-hint: "[task description]"
 ---
 # SDLC Skill - Full Development Workflow
 
@@ -2385,7 +2385,7 @@ Before presenting approach, STATE your confidence:
 | FAILED 2x | Something's wrong | STOP. ASK USER immediately | **Escalate effort now** — you're burning cycles at lower effort |
 | CONFUSED | Can't diagnose why something is failing | STOP. Describe what you tried, ask for help | **Escalate effort now** — stop spinning |
 
-"Model default" and "escalate" are model-aware, not a blanket `max` — see "Recommended Effort Level" above for the per-model table (Sonnet 5: `high`→`xhigh`; Opus 4.8: `xhigh`; Opus 4.6: `max`; Fable: `high`).
+"Model default" and "escalate" are model-aware, not a blanket `max` — see "Recommended Effort Level" above for the per-model table (Sonnet 5: `medium`→`high`→`xhigh`; Opus 4.8: `xhigh`; Opus 4.6: `max`; Fable: `high`).
 
 **Dynamic bumping is NOT optional.** "Consider higher effort" is the same as "ignore this" in practice. If your confidence drops or tests fail twice, bump effort BEFORE the next attempt — spinning at low effort is an SDLC failure mode.
 
@@ -2453,7 +2453,7 @@ PLANNING → DOCS → TDD RED → TDD GREEN → Tests Pass → Self-Review
 
    > **Always launch codex via `run_in_background: true` on the Bash tool.** The Bash tool clamps `timeout` to 600000 ms (10 min) regardless of the value passed, and force-kills the foreground process at that wall. Multi-artifact bundle reviews (release reviews per the checklist below, multi-finding rechecks, etc.) routinely run 6–30 minutes — they need background mode to complete. The wrapper `scripts/codex-review.sh` already has a 30-min stall watchdog (`STALL_SECONDS=1800`) as the real timeout control. A foreground call killed mid-review plus the Stop-hook re-invocation loop can burn 60+ minutes of session compute on what should be a single 7-minute run (issue #364, 2026-05-27 incident). The general rule: **any long-running wrapper invoked through the CC Bash tool — codex, slow builds, long test suites — should use `run_in_background: true` unconditionally and let the wrapper's own stall watchdog be the timeout authority.**
 
-3. If CERTIFIED → proceed to CI. If NOT CERTIFIED → go to Round 2.
+3. If CERTIFIED → **write `"commit_sha": "<git rev-parse HEAD>"` into `handoff.json` before proceeding to CI.** `hooks/codex-gate-check.sh` compares this SHA to current HEAD at commit time and treats a mismatch (or a missing field) as a stale certification (ROADMAP #437) — a CERTIFIED status string alone doesn't prove the certification still covers what's about to be committed. If NOT CERTIFIED → go to Round 2.
 
 ### Round 2+: Dialogue Loop
 
@@ -2497,7 +2497,7 @@ When the reviewer finds issues, respond per-finding instead of silently fixing e
      < /dev/null
    ```
 
-4. If CERTIFIED → done. If NOT CERTIFIED (rejected disputes or failed fixes) → fix rejected items and repeat.
+4. If CERTIFIED → **write/update `"commit_sha"` in `handoff.json` to current HEAD** (same reason as Round 1 step 3 — the gate hook checks it). If NOT CERTIFIED (rejected disputes or failed fixes) → fix rejected items and repeat.
 
 ### Convergence
 
@@ -2512,7 +2512,7 @@ Self-review passes → handoff.json (round 1, PENDING_REVIEW)
                             |
                    Reviewer: FULL REVIEW (structured findings)
                             |
-                   CERTIFIED? → YES → CI feedback loop
+                   CERTIFIED? → YES → write commit_sha → CI feedback loop
                             |
                             NO (findings with IDs + certify conditions)
                             |
@@ -2523,7 +2523,7 @@ Self-review passes → handoff.json (round 1, PENDING_REVIEW)
                             |
                    Reviewer: TARGETED RECHECK (previous findings only)
                             |
-                   All resolved? → YES → CERTIFIED
+                   All resolved? → YES → CERTIFIED (write commit_sha)
                             |
                             NO → fix rejected items, repeat
                             (max 3 rechecks, then escalate to user)
@@ -3075,7 +3075,7 @@ If deployment fails or post-deploy verification catches issues:
 
 **SDLC.md:**
 ```markdown
-<!-- SDLC Wizard Version: 1.85.0 -->
+<!-- SDLC Wizard Version: 1.87.0 -->
 <!-- Setup Date: [DATE] -->
 <!-- Completed Steps: step-0.1, step-0.2, step-0.4, step-1, step-2, step-3, step-4, step-5, step-6, step-7, step-8, step-9 -->
 <!-- Git Workflow: [PRs or Solo] -->
@@ -3852,12 +3852,12 @@ Use an independent AI model from a different company as a code reviewer. The aut
 
 **Why this works:** Two AI systems from different companies (e.g., Claude writes, GPT reviews) provide adversarial diversity. They have fundamentally different training, different failure modes, and different strengths. What one misses, the other catches.
 
-**Use the best model at the deepest reasoning.** This is your quality gate — don't economize on it. Always use the latest, most capable model available (**GPT-5.5 if you have access**, otherwise GPT-5.4) at maximum reasoning effort (`xhigh` — this is non-negotiable, lower settings miss subtle errors). Cheaper/faster models miss things. The whole point is catching what the authoring model couldn't.
+**Use the best model at the deepest reasoning.** This is your quality gate — don't economize on it. Always use the latest, most capable model available (**GPT-5.6 Sol if you have access**, otherwise Terra) at `xhigh` reasoning effort (non-negotiable — lower settings miss subtle errors; preserve this baseline rather than downgrading it on a model bump). Cheaper/faster models miss things. The whole point is catching what the authoring model couldn't. For unusually risky PRs, escalating to `max` or Pro mode is defensible — see `AI_SETUP_LANES.md`'s Final Review Policy — but `xhigh` is the default; no published data shows the higher tiers catching meaningfully more real bugs on ordinary PR review.
 
 **Prerequisites:**
 - Codex CLI installed: `npm i -g @openai/codex`
 - OpenAI API key configured: `export OPENAI_API_KEY=...`
-- Codex CLI picks up your OpenAI account's best available model automatically. If you have GPT-5.5 access, `codex exec` uses it; otherwise it falls back to GPT-5.4. No config change needed on your side.
+- Codex CLI picks up your OpenAI account's best available model automatically. If you have GPT-5.6 Sol access, `codex exec` uses it; otherwise it falls back to Terra. No config change needed on your side.
 - This is a local workflow tool — not required for CI/CD
 
 **The Protocol:**
@@ -3909,7 +3909,7 @@ codex exec \
 
 > **Always launch via `run_in_background: true` on the Bash tool.** Same reason as the parallel callout in the Cross-Model Review Loop section above — Bash tool clamps `timeout` to 600000 ms (10 min) regardless of the value passed and force-kills foreground at the wall. Multi-artifact bundle reviews need background mode to complete. See issue #364 (2026-05-27 incident: 70 min session compute on a 7-min review).
 
-4. If CERTIFIED → done. If NOT CERTIFIED → enter the dialogue loop.
+4. If CERTIFIED → **write `"commit_sha": "<git rev-parse HEAD>"` into `handoff.json`** — `hooks/codex-gate-check.sh` (ROADMAP #437) blocks a commit if this is missing or doesn't match current HEAD, so a bare `CERTIFIED` status isn't enough. Then done. If NOT CERTIFIED → enter the dialogue loop.
 
 **The Dialogue Loop (Round 2+):**
 
@@ -3979,7 +3979,7 @@ Claude writes code → self-review passes → handoff.json (round 1)
     |                              Reviewer: FULL REVIEW
     |                              (structured findings with IDs)
     |                                          |
-    |                              CERTIFIED? -+→ YES → Done
+    |                              CERTIFIED? -+→ YES → write commit_sha → Done
     |                                          |
     |                                          +→ NO (findings)
     |                                          |
@@ -3989,12 +3989,14 @@ Claude writes code → self-review passes → handoff.json (round 1)
     |                              Reviewer: TARGETED RECHECK
     |                              (previous findings only, no new P1/P2)
     |                                          |
-    |                              All resolved? → YES → CERTIFIED
+    |                              All resolved? → YES → CERTIFIED (write commit_sha)
     |                                          |
     └────────── Fix rejected items ←───────────┘
                     (max 3 rechecks, then escalate to user)
 ```
 
+**Every CERTIFIED path above writes `"commit_sha": "<git rev-parse HEAD>"` into `handoff.json`** — `hooks/codex-gate-check.sh` (ROADMAP #437) treats a missing or mismatched SHA as a stale certification, so a bare `CERTIFIED` status string is never enough on its own.
+
 **Key flags:**
 - `-c 'model_reasoning_effort="xhigh"'` — Maximum reasoning depth. This is where you get the most value. Testing showed `xhigh` caught 3 findings that `high` missed on the same content.
 - `-s danger-full-access` — Full filesystem read/write so the reviewer can read your actual code.

package/README.md

@@ -123,7 +123,7 @@ export OPENAI_API_KEY=sk-...
 codex --version   # confirm ready
 ```
 
-That's it. Codex picks up your OpenAI account's best available model automatically — **if you have GPT-5.5, it uses GPT-5.5; otherwise GPT-5.4**. No model config needed.
+That's it. Codex picks up your OpenAI account's best available model automatically — **if you have GPT-5.6 Sol, it uses Sol; otherwise it falls back to Terra**. No model config needed.
 
 **How to use it:** after Claude's self-review passes, write a one-file mission brief and run:
 
@@ -142,7 +142,7 @@ codex exec -c 'model_reasoning_effort="xhigh"' -s danger-full-access \
 
 The wizard ships a **default recommendation**, not a mandate. You can swap to any Claude model — newer, older, or sibling tier — at any time. `/model` per session, or pin in `.claude/settings.json`.
 
-**Default: Sonnet 5 at `high` effort, escalating to `xhigh`** (Setup A in `AI_SETUP_LANES.md`). Sonnet 5 (launched 2026-06-30) beats Opus 4.6 on every coding benchmark (SWE-bench Verified 85.2% vs 80.8%, Terminal-Bench 2.1 80.4% vs 65.4%) while using ~5x less Max quota per turn. Opus 4.6 remains available as **Setup B — Stability** for proven-consistency workflows; here's why it's no longer the default.
+**Default: Sonnet 5 at `medium` effort, escalating to `high`/`xhigh`** (Setup A in `AI_SETUP_LANES.md`). Sonnet 5 (launched 2026-06-30) beats Opus 4.6 on every coding benchmark (SWE-bench Verified 85.2% vs 80.8%, Terminal-Bench 2.1 80.4% vs 65.4%) while generally using less Max quota — savings vary by effort level and narrow at `high`/`xhigh` (newer tokenizer, more agentic turns per task). Opus 4.6 remains available as **Setup B — Stability** for proven-consistency workflows; here's why it's no longer the default.
 
 ### Why Opus 4.6 was the flagship, and why that changed
 
@@ -156,7 +156,7 @@ Two weeks of in-the-wild data after Opus 4.8's launch (2026-05-28) showed a clea
 - **[BSWEN effort decision guide](https://docs.bswen.com/blog/2026-04-19-claude-code-effort-level-decision-guide/)** — "Max on Opus causes overthinking on routine stuff. xHigh is the sweet spot for autonomous work"
 - **r/Claudeopus field reports** — one maintainer's literal A/B: "12 hours with 4.8 zero deliverables; plugged in 4.6, spec written + 133 tests green in one session." Top comment: "4.6 had the best overall balance at max"
 
-That research still stands — it's why **Opus 4.6 remains Setup B (Stability)** rather than being dropped entirely, and why the wizard escalates to Opus **4.8** (not a blanket "latest") only when Sonnet 5 gets stuck. But Sonnet 5's June 30 launch changed the calculus for the *default*: it beats Opus 4.6 on every benchmark above at a fraction of the quota cost, so it's no longer a tradeoff between "reliable but weaker" and "strong but overthinks" — Sonnet 5 doesn't have Opus 4.8's overthinking problem in the first place.
+That research still stands — it's why **Opus 4.6 remains Setup B (Stability)** rather than being dropped entirely, and why the wizard escalates to Opus **4.8** (not a blanket "latest") only when Sonnet 5 gets stuck. But Sonnet 5's June 30 launch changed the calculus for the *default*: it beats Opus 4.6 on every benchmark above at generally lower quota cost, so it's no longer a tradeoff between "reliable but weaker" and "strong but overthinks" — Sonnet 5 doesn't have Opus 4.8's overthinking problem in the first place.
 
 4.6 remains Anthropic-supported until **≥ Feb 5, 2027** per the [official deprecation page](https://platform.claude.com/docs/en/about-claude/model-deprecations), so Setup B stays a safe long-term choice if you've tuned a workflow to its behavior specifically.
 
@@ -172,10 +172,10 @@ That research still stands — it's why **Opus 4.6 remains Setup B (Stability)**
 Or pin in `.claude/settings.json`:
 
 ```json
-{ "model": "sonnet", "advisorModel": "fable", "effortLevel": "xhigh" }
+{ "model": "sonnet", "advisorModel": "fable", "effortLevel": "medium" }
 ```
 
-**Effort is model-aware, not blanket `max`.** Sonnet 5: `high` default, `/effort xhigh` for hard tasks. Opus 4.8: `xhigh` (its own `max` overthinks). Opus 4.6: `max` (its one `xhigh`-less sweet spot). Set per-session with `/effort`, not a shell-rc or settings env var — persisting effort that way silently overrides a later `/effort` change after you switch models (see `SDLC.md`'s Lessons Learned for a real incident this caused). OpenAI/Codex reviewer: `xhigh` (its highest).
+**Effort is model-aware, not blanket `max`.** Sonnet 5: `medium` default (CodeRabbit-tested), escalate `/effort high` → `xhigh` for hard tasks. Opus 4.8: `xhigh` (its own `max` overthinks). Opus 4.6: `max` (its one `xhigh`-less sweet spot). Set per-session with `/effort`, not a shell-rc or settings env var — persisting effort that way silently overrides a later `/effort` change after you switch models (see `SDLC.md`'s Lessons Learned for a real incident this caused). OpenAI/Codex reviewer: `xhigh` default — escalate to `max`/Pro mode only for unusually risky PRs (see `AI_SETUP_LANES.md`'s Final Review Policy).
 
 ### Four Setup Lanes
 
@@ -183,13 +183,21 @@ The wizard defines four AI coding setups in [`AI_SETUP_LANES.md`](AI_SETUP_LANES
 
 | Lane | Advisor | Driver | Reviewer | Escalation |
 |------|---------|--------|----------|------------|
-| **A — Recommended** | Fable 5 (advisorModel) | Sonnet 5, `high`→`xhigh` | GPT-5.5 xhigh | Opus 4.8 xhigh or Fable review |
-| **B — Stability** | Fable 5 (advisorModel) | Opus 4.6 max | GPT-5.5 xhigh | None |
-| **C — Saver** | Fable 5 or Opus 4.8 (advisorModel) | Opus 4.8 plans, Sonnet 5 executes | GPT-5.5 xhigh | None |
+| **A — Recommended** | Fable 5 (advisorModel) | Sonnet 5, `medium`→`high`→`xhigh` | GPT-5.6 Sol xhigh | Opus 4.8 xhigh or Fable review |
+| **B — Stability** | Fable 5 (advisorModel) | Opus 4.6 max | GPT-5.6 Sol xhigh | None |
+| **C — Saver** | Fable 5 or Opus 4.8 (advisorModel) | Opus 4.8 plans, Sonnet 5 executes | GPT-5.6 Sol xhigh | None |
 | **D — Lite** | None | Sonnet 5, `medium` | None | None |
 
 Setup D's whole point: **the discipline of knowing when NOT to use discipline.** When blast radius is low and you just need fast cheap hands, skip the SDLC overhead.
 
+### Reading Setup A precisely
+
+Clarified 2026-07-13 after these exact points kept getting re-confused; each rule states its why:
+
+- **Effort escalation stays inside the driver.** Sonnet 5 starts at `medium`; `/effort high` when it struggles, `xhigh` for hard debugging or long agent runs. Why `medium` and not `high`: the old "start at `high`" guidance was removed in ROADMAP #440 — it had no measurement behind it, and CodeRabbit's testing (the source this repo already cites) found `medium` captures most of Sonnet 5's upside without paying for the top effort tiers, while community cost reports suggest the quota advantage erodes at `high`/`xhigh`.
+- **Model escalation swaps the driver.** After 2 failed attempts, LOW confidence, or on high-stakes changes, Opus 4.8 xhigh takes over as driver (or run a Fable 5 review pass on the diff). Why a swap and not more effort: the lane's policy treats repeated failure as a sign the *approach* needs different eyes, not deeper reasoning on the same track — so once the effort ladder is exhausted, the next rung is a different model, not a bigger bill.
+- **Advisor failure has a fallback, not a shrug.** Fable 5 advises via `advisorModel: "fable"`; when `advisor()` errors (it's a server-side tool — API incidents happen), spawn a Fable subagent as the fallback reviewer, exactly as the `/sdlc` skill prescribes. Why: the advisor's job is catching wrong approaches *before* they're built, so a transport failure changes how the advice is obtained — not whether the check happens.
+
 **A note on `[1m]` and billing.** Sonnet 5 always runs at its native 1M context — no `[1m]` suffix needed, no separate billing tier. For Opus, the `[1m]` suffix is the 1M-context alias; as of [March 2026](https://claude.com/blog/1m-context-ga), 1M context is GA at standard pricing — **no long-context surcharge, no premium tier, no API-only restriction.** Interactive Claude Code sessions on Max / Team / Enterprise plans include 1M context automatically. (Pro users need "Enable usage credits" turned on once.) The [June 15, 2026 billing split](https://codersera.com/blog/anthropic-june-2026-billing-change-claude-code/) moved *headless* surfaces — `claude -p`, Agent SDK, GitHub Actions, third-party apps — off the Max subscription onto a separate metered credit pool. Interactive Claude Code in your terminal stays on Max. Full details in [`AI_SETUP_LANES.md` § How Billing Works](AI_SETUP_LANES.md#how-billing-works--1m-context-max-plan-and-the-june-15-split).
 
 ## How It Works

package/cli/init.js

@@ -25,7 +25,6 @@ const FILES = [
   { src: 'hooks/instructions-loaded-check.sh', dest: '.claude/hooks/instructions-loaded-check.sh', executable: true, base: REPO_ROOT },
   { src: 'hooks/model-effort-check.sh', dest: '.claude/hooks/model-effort-check.sh', executable: true, base: REPO_ROOT },
   { src: 'hooks/precompact-seam-check.sh', dest: '.claude/hooks/precompact-seam-check.sh', executable: true, base: REPO_ROOT },
-  { src: 'hooks/goal-confidence-check.sh', dest: '.claude/hooks/goal-confidence-check.sh', executable: true, base: REPO_ROOT },
   { src: 'hooks/codex-gate-check.sh', dest: '.claude/hooks/codex-gate-check.sh', executable: true, base: REPO_ROOT },
   { src: 'hooks/token-spike-check.sh', dest: '.claude/hooks/token-spike-check.sh', executable: true, base: REPO_ROOT },
   { src: 'hooks/codex-review-stop-check.sh', dest: '.claude/hooks/codex-review-stop-check.sh', executable: true, base: REPO_ROOT },

package/cli/templates/settings.json

@@ -7,10 +7,6 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/sdlc-prompt-check.sh"
-          },
-          {
-            "type": "command",
-            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/goal-confidence-check.sh"
           }
         ]
       }

package/hooks/codex-gate-check.sh

@@ -32,13 +32,37 @@ TOOL_INPUT=$(cat)
 # still can't run past the field's true (unescaped) closing quote because
 # neither alternative in the group can match a bare `"`. Scoped to just
 # this field, so unrelated fields containing the phrase can't false-trigger.
+# #236(b): under `set -e`, a grep with no match exits 1 and kills the whole
+# script with an undefined exit code (a "command" field can be absent, e.g.
+# an old-format payload) — `|| true` makes "no match" a clean, deliberate
+# empty COMMAND_FIELD instead of a crash.
 COMMAND_FIELD=$(printf '%s' "$TOOL_INPUT" \
-    | grep -oE '"command"[[:space:]]*:[[:space:]]*"([^"\\]|\\.)*"')
+    | grep -oE '"command"[[:space:]]*:[[:space:]]*"([^"\\]|\\.)*"' || true)
 
-case "$COMMAND_FIELD" in
-    *"git commit"*) ;;
-    *) exit 0 ;;
-esac
+# Codex cross-model review finding (#236(b) round 1, 2026-07-06): a `-c`/`-C`
+# value containing a space inside quotes is a real, valid git invocation
+# (e.g. `git -c user.name="A B" commit`) but broke the structural match below
+# — `\S+` stops at the embedded space, so the flag-value alternative never
+# matches and the whole "git ... commit" pattern silently fails, letting the
+# commit through unreviewed. Fix: strip COMMAND_FIELD down to just the raw
+# value content (COMMAND_VALUE, still JSON-escaped), then collapse every
+# quoted sub-span — both JSON-escaped `\"..\"` and plain `'..'` — to a single
+# placeholder token before the structural match runs, so a quoted value can
+# never look like more than one word to it.
+COMMAND_VALUE=$(printf '%s' "$COMMAND_FIELD" \
+    | sed -E 's/^"command"[[:space:]]*:[[:space:]]*"(.*)"$/\1/')
+MASKED_COMMAND=$(printf '%s' "$COMMAND_VALUE" \
+    | sed -E -e 's/\\"[^\\]*\\"/Q/g' -e "s/'[^']*'/Q/g")
+
+# #236(b): literal substring "git commit" misses git's own global-flag forms
+# — `git -C <dir> commit` and `git -c k=v commit` are valid invocations that
+# never contain that exact two-word substring, and previously sailed through
+# unreviewed. Regex allows any number of -C/-c (with their required value),
+# --long-flag, or single-letter-flag tokens between "git" and "commit".
+if ! printf '%s' "$MASKED_COMMAND" \
+    | grep -qE '\bgit(\s+(-C\s+\S+|-c\s+\S+|--\S+|-[A-Za-z]))*\s+commit\b'; then
+    exit 0
+fi
 
 REVIEW_FILE=".reviews/handoff.json"
 
@@ -52,7 +76,26 @@ STATUS=$(grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' "$REVIEW_FILE" \
     | sed 's/.*"status"[[:space:]]*:[[:space:]]*"//; s/"$//')
 
 case "$STATUS" in
-    CERTIFIED|REVIEWED) exit 0 ;;
+    CERTIFIED|REVIEWED)
+        # #437: a CERTIFIED/REVIEWED status string alone doesn't mean the
+        # certification is still current — commits made after it was issued
+        # would otherwise sail through on the same stale status forever.
+        # commit_sha records HEAD at cert time; a mismatch (or a missing
+        # field, e.g. an old-format handoff.json predating this fix) means
+        # new commits landed since certification, so treat it as stale. This
+        # allows exactly one commit after certification (HEAD still equals
+        # the recorded SHA at that commit's PreToolUse check) and blocks the
+        # next one until re-cert. No legacy-compat fallback for missing SHA.
+        COMMIT_SHA=$(grep -o '"commit_sha"[[:space:]]*:[[:space:]]*"[^"]*"' "$REVIEW_FILE" \
+            | head -1 \
+            | sed 's/.*"commit_sha"[[:space:]]*:[[:space:]]*"//; s/"$//')
+        CURRENT_HEAD=$(git rev-parse HEAD 2>/dev/null) || CURRENT_HEAD=""
+        if [ -z "$COMMIT_SHA" ] || [ "$COMMIT_SHA" != "$CURRENT_HEAD" ]; then
+            echo "CROSS-MODEL REVIEW REQUIRED: .reviews/handoff.json certification is stale (commit_sha does not match current HEAD — new commits landed since certification). Re-run Codex cross-model review. Set CODEX_GATE_SKIP=1 to bypass with justification." >&2
+            exit 2
+        fi
+        exit 0
+        ;;
     *)
         echo "CROSS-MODEL REVIEW REQUIRED: .reviews/handoff.json status is '$STATUS' (need REVIEWED or CERTIFIED). Run Codex cross-model review before committing. Set CODEX_GATE_SKIP=1 to bypass with justification." >&2
         exit 2

package/hooks/codex-review-stop-check.sh

@@ -62,6 +62,11 @@ if [ -n "$SESSION_ID" ]; then
     fi
 fi
 
-echo "NOTE: uncommitted changes with no REVIEWED/CERTIFIED cross-model review artifact. If this work is heading to a commit, run Codex review before committing." >&2
+# #236(b): on exit 0, stderr is never surfaced (to the user or to Claude) —
+# only stdout JSON is. An earlier stderr+exit-0 version of this line was
+# silently discarded since the day this hook shipped (#436).
+cat << 'EOF'
+{"hookSpecificOutput": {"hookEventName": "Stop", "additionalContext": "NOTE: uncommitted changes with no REVIEWED/CERTIFIED cross-model review artifact. If this work is heading to a commit, run Codex review before committing."}}
+EOF
 
 exit 0

package/hooks/hooks.json

@@ -7,10 +7,6 @@
           {
             "type": "command",
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/sdlc-prompt-check.sh"
-          },
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/goal-confidence-check.sh"
           }
         ]
       }