agentic-sdlc-wizard 1.83.0 → 1.84.0

package/README.md

@@ -142,11 +142,11 @@ 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: Opus 4.6 at max effort** (`[f] Flagship` in the setup wizard). This is the wizard's recommendation as of v1.80.0 — a stronger statement than "this might work." Here's why.
+**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.
 
-### Why Opus 4.6 max, not Anthropic's latest
+### Why Opus 4.6 was the flagship, and why that changed
 
-Two weeks of in-the-wild data after Opus 4.8's launch (2026-05-28) showed a clear pattern:
+Two weeks of in-the-wild data after Opus 4.8's launch (2026-05-28) showed a clear pattern that first made Opus 4.6 the wizard's flagship over Anthropic's own "latest" model:
 
 - **[Andon Labs Vending-Bench](https://andonlabs.com/blog/opus-4-8-vending-bench)** — 4.8 finished last vs 4.7 and GPT-5.5; documented "Max reasoning is not the best reasoning effort"; falls for scam suppliers 30× more frequently
 - **[AI Weekly: 900K cache tokens per turn](https://aiweekly.co/alerts/claude-opus-48-thinking-burns-900k-tokens-per-turn)** — 40-60× jump vs 4.7 at HIGH effort. Burns Max 5-hour limits 2-3× faster
@@ -156,51 +156,41 @@ 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"
 
-Six independent sources converging on the same conclusion: **4.6 is the only Opus where `max` effort tolerates without overthinking, and 4.7/4.8's "improvements" come with structural token-burn tradeoffs.** When you're running SDLC discipline workflows that span hours and tens of thousands of tokens, reliability beats benchmarks.
+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.
 
-4.6 is Anthropic-supported until **≥ Feb 5, 2027** per the [official deprecation page](https://platform.claude.com/docs/en/about-claude/model-deprecations) — 8 months minimum runway. The Feb-Apr 2026 quality bugs are fully fixed per Anthropic's [April 23 postmortem](https://www.anthropic.com/engineering/april-23-postmortem) — the wizard picks up the post-fix model, not the regression window.
-
-### What 4.6 max gives up
-
-- 4.8's SWE-Bench Pro (69.2% vs 4.7's 64.3%) and Terminal-Bench 2.1 (74.6% vs 66.1%) gains
-- Dynamic-workflows and parallel-subagent-swarm features introduced in 4.8
-- Anthropic's "latest = best" convention. The wizard is explicitly betting against that convention here.
-
-### Latest tier — Opus 4.8 (opt-in)
-
-If you want the newest benchmarks and you're comfortable with the token-burn tradeoff, pick `[l] Latest` in the setup wizard. Always `max` effort on all Claude models (#395). The [`Latest tier — Opus 4.8`](CLAUDE_CODE_SDLC_WIZARD.md) section has the full opt-in instructions.
+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.
 
 ### Switch any time
 
 ```bash
-/model claude-opus-4-6   # wizard's recommended flagship (default in v1.80.0+)
-/model opusplan          # Opus plans (Shift+Tab), Sonnet executes — both Max-bundled
-/model claude-opus-4-8   # Anthropic's latest, opt-in via Latest tier
+/model sonnet             # wizard's recommended default (Setup A) — native 1M context
+/model claude-opus-4-6    # Stability lane (Setup B) — proven consistency
+/model opusplan           # Opus plans (Shift+Tab), Sonnet executes — both Max-bundled (Setup C)
+/model claude-opus-4-8    # escalation only — don't run as daily driver, burns quota 2-3x faster
 ```
 
 Or pin in `.claude/settings.json`:
 
 ```json
-{ "model": "claude-opus-4-6", "env": { "CLAUDE_CODE_EFFORT_LEVEL": "max" } }
+{ "model": "sonnet", "advisorModel": "fable", "effortLevel": "xhigh" }
 ```
 
-Or sweep all your projects by setting `ANTHROPIC_DEFAULT_OPUS_MODEL=claude-opus-4-6` in `~/.claude/settings.json`.
-
-Effort: **always `max`** on all Claude models. Persist it: set `CLAUDE_CODE_EFFORT_LEVEL=max` in your settings env block (CC docs: `effortLevel: "max"` in settings.json is session-only and silently ignored). OpenAI/Codex: `xhigh` (their highest).
+**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).
 
-### Three Setup Lanes
+### Four Setup Lanes
 
-The wizard defines three AI coding setups in [`AI_SETUP_LANES.md`](AI_SETUP_LANES.md):
+The wizard defines four AI coding setups in [`AI_SETUP_LANES.md`](AI_SETUP_LANES.md):
 
 | Lane | Advisor | Driver | Reviewer | Escalation |
 |------|---------|--------|----------|------------|
-| **A — Premium** | Fable 5 (advisorModel) | Opus 4.6 max | GPT-5.5 xhigh | + Fable review (security/release/architecture) |
-| **B — Saver** | Opus 4.6 (advisorModel) | Sonnet | GPT-5.5 xhigh | None |
-| **C — Lite** | None | Sonnet | None | None |
+| **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 |
+| **D — Lite** | None | Sonnet 5, `medium` | None | None |
 
-Setup C'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.
+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.
 
-**A note on `[1m]` and billing.** 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; whether you set `claude-opus-4-6` or `claude-opus-4-6[1m]`, you're billed against the same per-token Max budget at $5/$25 per million tokens. (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).
+**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

@@ -26,6 +26,9 @@ const FILES = [
   { 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 },
   // #254 Bug 1: shared helper sourced by all hooks above. Must ship — without
   // it, hooks emit "_find-sdlc-root.sh: No such file or directory" + the
   // SDLC root walk-up logic is silently dead.

package/cli/lib/repo-complexity.js

@@ -1,10 +1,10 @@
-// Roadmap #233: repo complexity heuristic for mixed-mode tier selection.
+// Roadmap #233: repo complexity heuristic for setup-lane suggestion.
 //
 // Output: { tier: 'simple' | 'complex', score: <number>, signals: [...] }
-//   - 'simple' → setup wizard suggests mixed-mode (Sonnet 4.6 coder + Opus 4.6 max reviewer)
-//   - 'complex' → setup wizard suggests full flagship (Opus 4.6 max everywhere)
-// Cross-model review (Codex / external) always stays at the flagship tier
-// regardless of coder selection — see CLAUDE_CODE_SDLC_WIZARD.md.
+//   - 'simple' → setup wizard suggests Setup A (Sonnet 5 + Fable) or no pin
+//   - 'complex' → setup wizard suggests Setup B (Opus 4.6 Stability) or escalating to Opus 4.8
+// Cross-model review (Codex xhigh) always runs regardless of driver
+// selection — see CLAUDE_CODE_SDLC_WIZARD.md.
 //
 // Classification (matches CLAUDE_CODE_SDLC_WIZARD.md → "Mixed-Mode Tier"):
 //   simple = LOC < 10K AND tests < 30 AND hooks < 5 AND workflows < 5 AND no stakes

package/cli/templates/settings.json

@@ -25,6 +25,15 @@
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/tdd-pretool-check.sh"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/codex-gate-check.sh"
+          }
+        ]
       }
     ],
     "InstructionsLoaded": [
@@ -43,6 +52,10 @@
           {
             "type": "command",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/model-effort-check.sh"
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/token-spike-check.sh"
           }
         ]
       }
@@ -57,6 +70,16 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/codex-review-stop-check.sh"
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/codex-gate-check.sh

@@ -0,0 +1,60 @@
+#!/bin/bash
+# PreToolUse hook — blocks git commit without cross-model review artifact
+# Fires on Bash tool; only acts when the command contains "git commit"
+#
+# #436 fix: exit 2 + stderr is what actually denies the tool call in Claude
+# Code. The original version exited 0 on every path (including the two
+# "CROSS-MODEL REVIEW REQUIRED" branches below), so it printed a warning but
+# never blocked anything — the exact bug class this gate exists to prevent.
+# Matches the proven blocking pattern in precompact-seam-check.sh.
+
+set -e
+
+# Skip gate if explicitly overridden (emergency bypass with logged justification)
+[ "${CODEX_GATE_SKIP:-}" = "1" ] && exit 0
+
+TOOL_INPUT=$(cat)
+
+# Codex review findings (hook-enforcement-436):
+# Round 1: extracting the "command" field's value via grep/sed with
+# `[^"]*` broke when an earlier quote appeared in the command (e.g. `cd
+# "$dir" && git commit ...`) — the class stops at the first literal `"`
+# regardless of JSON escaping, truncating the capture before it ever
+# reached "git commit" (false negative — review-less commit slipped
+# through).
+# Round 2: matching "git commit" against the WHOLE raw TOOL_INPUT (the
+# round-1 fix) over-corrected — a non-commit command got blocked if any
+# OTHER field (e.g. the Bash tool's own "description") happened to mention
+# "git commit" in prose (false positive).
+# Fix: extract just the "command" field's value with an escape-aware
+# pattern — `([^"\\]|\\.)*` consumes an escaped quote (`\"`) as one unit
+# instead of treating it as a terminator, so it can't stop early, and it
+# 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.
+COMMAND_FIELD=$(printf '%s' "$TOOL_INPUT" \
+    | grep -oE '"command"[[:space:]]*:[[:space:]]*"([^"\\]|\\.)*"')
+
+case "$COMMAND_FIELD" in
+    *"git commit"*) ;;
+    *) exit 0 ;;
+esac
+
+REVIEW_FILE=".reviews/handoff.json"
+
+if [ ! -f "$REVIEW_FILE" ]; then
+    echo "CROSS-MODEL REVIEW REQUIRED: No .reviews/handoff.json found. Run Codex cross-model review before committing. Set CODEX_GATE_SKIP=1 to bypass with justification." >&2
+    exit 2
+fi
+
+STATUS=$(grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' "$REVIEW_FILE" \
+    | head -1 \
+    | sed 's/.*"status"[[:space:]]*:[[:space:]]*"//; s/"$//')
+
+case "$STATUS" in
+    CERTIFIED|REVIEWED) 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
+        ;;
+esac

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

@@ -0,0 +1,67 @@
+#!/bin/bash
+# Stop hook — warns (non-blocking) when the session is about to end with
+# significant uncommitted changes and no REVIEWED/CERTIFIED cross-model
+# review artifact.
+#
+# Gap this closes (Fable self-enforcement audit, #436): a full SDLC workflow
+# can complete — Claude presents "done, here's what I changed" — without
+# ever running `git commit`. codex-gate-check.sh only fires on that one
+# Bash command, so it never triggers and cross-model review is silently
+# skippable. This hook catches the "never committed, walked away" case.
+#
+# Non-blocking by design: Stop fires at the end of every turn, not just at
+# true session end, and it must never prevent the user from getting their
+# response. Fires once per session (sentinel-gated) to avoid nagging on
+# every iterative turn while a feature is still in progress.
+
+HOOK_DIR="${BASH_SOURCE[0]%/*}"
+[ "$HOOK_DIR" = "${BASH_SOURCE[0]}" ] && HOOK_DIR="."
+# shellcheck disable=SC1091
+source "$HOOK_DIR/_find-sdlc-root.sh"
+dedupe_plugin_or_project "${BASH_SOURCE[0]}" || { cat > /dev/null; exit 0; }
+
+STDIN_JSON=$(cat)
+
+git rev-parse --is-inside-work-tree > /dev/null 2>&1 || exit 0
+
+# Changed files: staged + unstaged + untracked, excluding review metadata
+# itself (.reviews/ changes describe the review, they aren't the work).
+CHANGED=$(git status --porcelain 2>/dev/null | awk '{print $2}' | grep -v '^\.reviews/')
+[ -z "$CHANGED" ] && exit 0
+
+# Doc-only changes don't need cross-model review.
+SIGNIFICANT=$(printf '%s\n' "$CHANGED" | grep -vE '\.md$|\.txt$|^LICENSE|^CHANGELOG|\.gitignore$|\.gitattributes$')
+[ -z "$SIGNIFICANT" ] && exit 0
+
+REVIEW_FILE=".reviews/handoff.json"
+if [ -f "$REVIEW_FILE" ]; then
+    STATUS=$(grep -o '"status"[[:space:]]*:[[:space:]]*"[^"]*"' "$REVIEW_FILE" \
+        | head -1 \
+        | sed 's/.*"status"[[:space:]]*:[[:space:]]*"//; s/"$//')
+    case "$STATUS" in
+        CERTIFIED|REVIEWED) exit 0 ;;
+    esac
+fi
+
+# Once-per-session sentinel — avoid nagging on every Stop event while a
+# feature is still in progress within the same session.
+SESSION_ID=$(printf '%s' "$STDIN_JSON" \
+    | grep -o '"session_id"[[:space:]]*:[[:space:]]*"[^"]*"' \
+    | head -1 \
+    | sed 's/.*"\([^"]*\)"$/\1/')
+if [ -n "$SESSION_ID" ]; then
+    CACHE_DIR="${SDLC_WIZARD_CACHE_DIR:-$HOME/.cache/sdlc-wizard}"
+    SAFE_SID=$(printf '%s' "$SESSION_ID" | tr -cd 'A-Za-z0-9._-')
+    if [ -n "$SAFE_SID" ]; then
+        SENTINEL="$CACHE_DIR/stop-review-warned-${SAFE_SID}"
+        mkdir -p "$CACHE_DIR" 2>/dev/null || true
+        if [ -f "$SENTINEL" ]; then
+            exit 0
+        fi
+        : > "$SENTINEL" 2>/dev/null || true
+    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
+
+exit 0

package/hooks/hooks.json

@@ -25,6 +25,15 @@
             "command": "${CLAUDE_PLUGIN_ROOT}/hooks/tdd-pretool-check.sh"
           }
         ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/codex-gate-check.sh"
+          }
+        ]
       }
     ],
     "InstructionsLoaded": [
@@ -61,6 +70,16 @@
           }
         ]
       }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/codex-review-stop-check.sh"
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/model-effort-check.sh

@@ -1,18 +1,23 @@
 #!/bin/bash
 # SessionStart hook — effort/model nudge.
 #
-# Behavior (#395 update):
+# Behavior (v1.84.0 update — model-aware floor):
 #   CLAUDE_CODE_EFFORT_LEVEL env var takes precedence over effortLevel in settings.
 #   CC docs: max is session-only in settings.json — only the env var persists it.
-#   Opus 4.6 supports: low, medium, high, max (NO xhigh — falls back to high).
+#   This hook cannot detect the active model (SessionStart payload has no model
+#   field, per ROADMAP #180), so it uses a floor that's correct across models:
+#   `high` is Sonnet 5's and Fable's tested default (escalate to xhigh for hard
+#   tasks); xhigh is Opus 4.8's floor; max remains the sweet spot on Opus 4.6
+#   (no xhigh support). Blanket max is WRONG for Sonnet 5/Opus 4.8 (wastes
+#   tokens for no quality gain — see AI_SETUP_LANES.md per-model table).
 #
-#   effort=max   -> silent (only acceptable level)
-#   anything else -> LOUD WARNING
+#   effort=high, xhigh, or max -> silent (all acceptable — model-dependent)
+#   anything else               -> LOUD WARNING
 #
 # Non-blocking: always exits 0.
 
-# Multiple wizard-blessed models — don't nudge to a single one (#403)
-RECOMMENDED_MODELS="claude-opus-4-6, opusplan, or fable (run: /model)"
+# Multiple wizard-blessed models — don't nudge to a single one (#403, #434)
+RECOMMENDED_MODELS="sonnet, opus, opusplan, or fable (run: /model)"
 
 HOOK_DIR="${BASH_SOURCE[0]%/*}"
 [ "$HOOK_DIR" = "${BASH_SOURCE[0]}" ] && HOOK_DIR="."
@@ -44,7 +49,12 @@ if [ -z "$effort" ]; then
     done
 fi
 
-# Only env-var max is truly silent.
+# high/xhigh are always silent (persist fine via settings.json, no CC quirk).
+# max is silent EXCEPT when it's settings-only — CC docs: max is session-only
+# in settings.json, only the env var actually persists it.
+if [ "$effort" = "high" ] || [ "$effort" = "xhigh" ]; then
+    exit 0
+fi
 if [ "$effort" = "max" ] && [ "$settings_max" -eq 0 ]; then
     exit 0
 fi
@@ -58,11 +68,11 @@ else
 fi
 
 echo "=============================================================================="
-echo " WARNING: effort '$effort_display' — SDLC requires max."
-echo " Below max = degraded reasoning, shallow TDD, weak self-review."
+echo " WARNING: effort '$effort_display' — SDLC requires high, xhigh, or max."
+echo " Below high = degraded reasoning, shallow TDD, weak self-review."
 echo ""
-echo " Run: /effort max"
-echo " Persist: set CLAUDE_CODE_EFFORT_LEVEL=max in settings env block"
+echo " Run: /effort xhigh (or /effort high — see AI_SETUP_LANES.md)"
+echo " Avoid shell-rc env var persistence — silently overrides model switches."
 echo ""
 echo " recommended models: $RECOMMENDED_MODELS"
 echo "=============================================================================="

package/hooks/tdd-pretool-check.sh

@@ -1,6 +1,15 @@
 #!/bin/bash
 # PreToolUse hook - TDD enforcement before editing source files
 # Fires before Write/Edit/MultiEdit tools
+#
+# #436 fix: this hook printed a TDD reminder but never exited 2 — pure prose
+# despite tdd_red being CRITICAL in the SDLC scoring rubric. It now blocks
+# (exit 2) writes to src/** unless a test file was touched earlier this
+# session. This is an edit-ordering proxy, not full "does a failing test
+# exist" verification — a bash hook can't run the suite and confirm RED.
+# Session-scoped (degrades to allow when session_id is absent — no cross-call
+# state to track without it, matching the back-compat stance already taken
+# for the nudge below).
 
 # Token-bloat fix: when both project + plugin register this hook, plugin yields.
 # Parameter-expansion-safe (no `dirname` dep): `%/*` strips trailing `/file`.
@@ -25,9 +34,39 @@ SESSION_ID=$(printf '%s' "$TOOL_INPUT" \
     | head -1 \
     | sed 's/.*"\([^"]*\)"$/\1/')
 
+# Test-file detection: always allowed, and marks "a test was touched" for
+# this session so the src/ gate below can unlock. Priority over the src/
+# check since many conventions nest tests inside src/ (e.g. src/__tests__/).
+if [[ "$FILE_PATH" =~ (\.test\.|\.spec\.|/__tests__/|/tests?/|/test_|^test_) ]]; then
+  if [ -n "$SESSION_ID" ]; then
+    CACHE_DIR="${SDLC_WIZARD_CACHE_DIR:-$HOME/.cache/sdlc-wizard}"
+    SAFE_SID=$(printf '%s' "$SESSION_ID" | tr -cd 'A-Za-z0-9._-')
+    if [ -n "$SAFE_SID" ]; then
+      mkdir -p "$CACHE_DIR" 2>/dev/null || true
+      : > "$CACHE_DIR/tdd-test-touched-${SAFE_SID}" 2>/dev/null || true
+    fi
+  fi
+  exit 0
+fi
+
 # CUSTOMIZE: Change this pattern to match YOUR source directory
 # Examples: "/src/", "/app/", "/lib/", "/packages/", "/server/"
-if [[ "$FILE_PATH" == *"/src/"* ]]; then
+# Codex review finding (hook-enforcement-436, round 1): "*/src/*" requires a
+# slash BEFORE "src", so a cwd-relative file_path like "src/app.js" (no
+# leading slash) never matched and the whole gate silently no-op'd. Second
+# clause catches the relative form.
+if [[ "$FILE_PATH" == *"/src/"* || "$FILE_PATH" == "src/"* ]]; then
+  # #436 gate: block implementation-first edits when no test file has been
+  # touched yet this session. Degrades to allow without session_id.
+  if [ -n "$SESSION_ID" ]; then
+    CACHE_DIR="${SDLC_WIZARD_CACHE_DIR:-$HOME/.cache/sdlc-wizard}"
+    SAFE_SID=$(printf '%s' "$SESSION_ID" | tr -cd 'A-Za-z0-9._-')
+    if [ -n "$SAFE_SID" ] && [ ! -f "$CACHE_DIR/tdd-test-touched-${SAFE_SID}" ]; then
+      echo "TDD RED REQUIRED: no test file touched yet this session. Write or edit a failing test before implementing in src/." >&2
+      exit 2
+    fi
+  fi
+
   # Token-bloat fix (v1.70.0): nudge fires once per CC session. Once Claude
   # has the SDLC skill auto-invoked (covers TDD RED/GREEN), the per-Edit
   # nudge becomes duplicate context — typical session has 10-30 src Edits

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-wizard",
-  "version": "1.83.0",
+  "version": "1.84.0",
   "description": "SDLC enforcement for Claude Code — hooks, skills, and wizard setup in one command",
   "bin": {
     "sdlc-wizard": "cli/bin/sdlc-wizard.js"

package/skills/sdlc/SKILL.md

@@ -2,7 +2,6 @@
 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]
-effort: max
 ---
 # SDLC Skill - Full Development Workflow
 
@@ -17,6 +16,8 @@ $ARGUMENTS
 
 Operational checklist. Full protocol lives in `CLAUDE_CODE_SDLC_WIZARD.md` — read it for depth.
 
+**If the user requests /sdlc, ALWAYS run the full workflow — even for mechanical tasks.** Never silently skip; if overkill, say so and ask.
+
 ## Full SDLC Checklist
 
 Your FIRST action must be a TodoWrite covering every phase below. Compact form (omit `activeForm` to use the subject as the spinner label):
@@ -96,13 +97,17 @@ State your confidence before presenting an approach:
 
 | Level | Meaning | Action | Effort |
 |-------|---------|--------|--------|
-| HIGH (90%+) | Know exactly what to do | Present, proceed after approval | `max` (default) |
-| MEDIUM (60-89%) | Solid approach, some uncertainty | Present, highlight uncertainties | `max` (default) |
-| LOW (<60%) | Not sure | Research or try Codex; if still LOW, ASK USER | **`/effort max` now** |
-| FAILED 2x | Something's wrong | Codex for fresh perspective; if still stuck, STOP | **`/effort max` now** |
-| CONFUSED | Can't diagnose | Codex; if still confused, STOP and describe | **`/effort max` now** |
+| HIGH (90%+) | Know exactly what to do | Present, proceed after approval | Model default |
+| MEDIUM (60-89%) | Solid approach, some uncertainty | Present, highlight uncertainties | Model default |
+| LOW (<60%) | Not sure | Research or try Codex; if still LOW, ASK USER | **escalate now** (per model, see above) |
+| FAILED 2x | Something's wrong | Codex for fresh perspective; if still stuck, STOP | **escalate now** |
+| CONFUSED | Can't diagnose | Codex; if still confused, STOP and describe | **escalate now** |
+
+**Effort bumping is NOT optional.** Bump BEFORE the next attempt, not after a third failure.
+
+**Confidence ramp:** Opus researches → Fable batch review → 95% list → /goal TDD → Codex check.
 
-**Dynamic effort bumping is NOT optional.** "Consider max effort" is the same as "ignore this." Bump BEFORE the next attempt, not after a third failure.
+**Advisor:** `advisor()` before plans; if down, spawn Fable subagent.
 
 ## Plan Mode
 
@@ -114,11 +119,11 @@ Native `/goal <condition>` (**v2.1.143+**). Haiku evaluator re-checks transcript
 
 ## Recommended Model
 
-**Recommended: `claude-opus-4-6` or `opusplan` (Opus 4.6 max — wizard's flagship).** Pin in settings or `/model claude-opus-4-6` at session start. `opusplan` uses Opus for Plan Mode (Shift+Tab) + Sonnet for execution — both Max-bundled. Persist effort: `CLAUDE_CODE_EFFORT_LEVEL=max` in settings env block.
+**Recommended: Sonnet 5 `high`→`xhigh`** — beats Opus 4.6, ~5x less quota. Escalate to **Opus 4.8 `xhigh`** when stuck. **Opus 4.6 `max`** valid for consistency. See `AI_SETUP_LANES.md`.
 
-**If pinning `claude-opus-4-6`:** pair with `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=30` — default compacts too early at ~76K on 1M. **Do not set this for `opusplan`** — 200K context, 30% = 60K too aggressive.
+**Effort is model-aware, not blanket `max`** — `max` overthinks on Sonnet 5/Opus 4.8. Set via `/effort` per session, not a shell-rc env var (overrides post-switch — see SDLC.md). `/model` persists; picker `s` does not.
 
-**Advisor (v2.1.170+):** Flagship → `advisorModel: "fable"`. OpusPlan → `advisorModel: "claude-opus-4-6"`. Set during `/setup-wizard` Step 9.5.
+**Pinning `claude-opus-4-6`:** pair with `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=30` (1M) — do not set this for `opusplan` (200K, too aggressive). **Advisor (v2.1.170+):** `advisorModel: "fable"` works with all drivers above; set in `/setup-wizard` Step 9.5.
 
 ## Self-Review Loop
 
@@ -132,20 +137,20 @@ The loop goes back to PLANNING, not TDD RED. Run `/code-review`; issues at confi
 
 ## Cross-Model Review (REQUIRED for High-Stakes)
 
-**When to run:** high-stakes changes (auth, payments, data), releases/publishes, complex refactors. **When to skip (log justification):** trivial, hotfixes, risk < review cost. **Prerequisites:** Codex CLI (`npm i -g @openai/codex`) + OpenAI API key. **Reviewer at flagship tier (#233):** even on `opusplan` (Sonnet driver), reviewer runs `gpt-5.5` xhigh — adversarial diversity is the point.
+**When to run:** high-stakes changes (auth, payments, data), releases/publishes, complex refactors. **When to skip (log justification):** trivial, hotfixes, risk < review cost. **Prerequisites:** Codex CLI + OpenAI API key. **Reviewer:** `gpt-5.5` xhigh — adversarial diversity.
 
 PROTOCOL is universal across domains; only `review_instructions` and `verification_checklist` change.
 
 1. **Preflight** (`.reviews/preflight-{review_id}.md`) — what you already checked: `/code-review` passed, tests passing, manual verifications, known limits. Reduces reviewer findings to 0-1/round.
-2. **Mission-first handoff** (`.reviews/handoff.json`) — required keys: `"review_id"`, `"status": "PENDING_REVIEW"`, `"round": 1`, `"mission"`/`"success"`/`"failure"` (without them you get "looks good"), `"files_changed"`, `"verification_checklist"` (verification checklist with file:line refs — NOT generic), `"review_instructions"`, `"preflight_path"`. Optional `"pr_number":` opts into PreCompact self-heal (#209: PR MERGED → implicit CERTIFIED).
-3. **Run reviewer:** `codex exec -c 'model_reasoning_effort="xhigh"' -s danger-full-access -o .reviews/latest-review.md "<prompt>" < /dev/null`. Always `xhigh`. Bash tool requires `run_in_background: true` + `dangerouslyDisableSandbox: true`; append `< /dev/null` always. **Why:** `< /dev/null` prevents codex stdin-hang at S/0% CPU; `run_in_background: true` avoids the Bash 10-min (`600000` ms) `timeout` cap that force-kills foreground codex (multi-artifact bundles take 5–30 min). xhigh 1–30 min; wrapper's `STALL_SECONDS=1800` is the real control. Heartbeat: `scripts/codex-review-with-progress.sh`. Foreground burned 70 min on a 7-min review (#364).
-4. **Dialogue loop:** per-finding response (`{"finding": "1", "action": "FIXED|DISPUTED|ACCEPTED", "summary": "..."}` in `.reviews/response.json`). Bump round, set status `PENDING_RECHECK`, add `fixes_applied` (numbered, file:line). Recheck prompt: "TARGETED RECHECK. FIXED → verify certify condition. DISPUTED → ACCEPT if sound, REJECT with reasoning. ACCEPTED → verify applied. No new findings unless P0."
+2. **Mission-first handoff** (`.reviews/handoff.json`) — required keys: `"review_id"`, `"status": "PENDING_REVIEW"`, `"round": 1`, `"mission"`/`"success"`/`"failure"` (without them you get "looks good"), `"files_changed"`, `"verification_checklist"` (verification checklist with file:line refs — NOT generic), `"review_instructions"`, `"preflight_path"`. Optional `"pr_number":` opts into PreCompact self-heal (#209: MERGED → implicit CERTIFIED).
+3. **Run reviewer:** `codex exec -c 'model_reasoning_effort="xhigh"' -s danger-full-access -o .reviews/latest-review.md "<prompt>" < /dev/null`. Always `xhigh`. Bash tool requires `run_in_background: true` + `dangerouslyDisableSandbox: true`; always append `< /dev/null`. **Why:** `< /dev/null` prevents codex stdin-hang at S/0% CPU; `run_in_background: true` avoids the Bash 10-min (`600000` ms) `timeout` cap that force-kills foreground codex (multi-artifact bundles take 5–30 min). xhigh 1–30 min; wrapper's `STALL_SECONDS=1800` controls it. Heartbeat: `scripts/codex-review-with-progress.sh`. Foreground burned 70 min on a 7-min review (#364).
+4. **Dialogue loop:** per-finding response (`{"finding": "1", "action": "FIXED|DISPUTED|ACCEPTED", "summary": "..."}` in `.reviews/response.json`). Bump round, set status `PENDING_RECHECK`, add `fixes_applied` (numbered, file:line). Recheck prompt: "TARGETED RECHECK. FIXED → verify certify condition. DISPUTED → ACCEPT if sound, REJECT with reasoning. ACCEPTED → verify applied. No new findings unless P0." **NEVER unilaterally dismiss** — always run the recheck. It's a conversation: the reviewer may accept your dispute or counter with evidence you missed.
 
-**Convergence:** 2 rounds sweet spot, 3 max. After 3 NOT CERTIFIED → escalate.
+**Convergence:** 2 rounds sweet spot, 3 max, escalate after — except large migrations: judge by finding trend, not count.
 
 **Enforcement:** `hooks/goal-confidence-check.sh` warns when `/goal` skips the 95%-confidence or DLC-binding gates (#360).
 
-**Multi-reviewer:** respond to each reviewer independently (no shared anchoring). **Non-code domains:** add `"audience"`/`"stakes"` keys to handoff.
+**Multi-reviewer:** respond to each independently (no shared anchoring). **Non-code domains:** add `"audience"`/`"stakes"` keys.
 
 ### Release Review Focus
 
@@ -165,7 +170,7 @@ Standard pattern: `*_DOCS.md` — living documents that grow with the feature (`
 4. No `*_DOCS.md` exists and feature touches 3+ files → create one
 5. Project has `ROADMAP.md` → mark items done, add new items (ROADMAP feeds CHANGELOG)
 
-`/claude-md-improver` audits CLAUDE.md structure. Run it periodically. It does NOT cover feature docs — the SDLC workflow handles those.
+`/claude-md-improver` audits CLAUDE.md structure periodically. Does NOT cover feature docs.
 
 ## CI Feedback Loop — Local Shepherd
 
@@ -175,7 +180,7 @@ Mandatory steps:
 1. Push to remote
 2. `gh pr checks --watch`
 3. **Read CI logs whether pass or fail** (`gh run view <RUN_ID> --log`, not just `--log-failed`). Passing CI hides warnings, skipped steps, degraded scores
-4. **Cross-model audit the CI logs** — pipe to a tmp file, run `codex exec -c 'model_reasoning_effort="xhigh"' -s danger-full-access "<audit prompt>" < /dev/null` (always append `< /dev/null` — stdin-hang fix) with *"Audit for silent failures, skipped tests, degraded metrics, warnings-that-should-be-errors."* Tier 1 + Tier 2 separately
+4. **Cross-model audit the CI logs** — same `codex exec` pattern (see Cross-Model Review §3). Prompt: *"Audit for silent failures, skipped tests, degraded metrics, warnings-that-should-be-errors."* Tier 1 + Tier 2 separately
 5. CI fails → diagnose, fix, push (max 2 attempts)
 6. CI passes → `gh api repos/OWNER/REPO/pulls/PR/comments` for review feedback
 7. Implement valid suggestions (bugs, perf, missing error handling, dedup, coverage). Skip opinions/style. Max 3 iterations
@@ -192,7 +197,7 @@ Mandatory steps:
 
 ## Debugging Workflow (Systematic)
 
-Reproduce → Isolate → Root Cause → Fix → Regression Test. This is the systematic debugging methodology — do not skip steps. Regressions: `git bisect`. Env-specific: check env vars/OS/deps/permissions, reproduce locally, log at the failure point. 2 failed attempts → STOP and ASK USER.
+Reproduce → Isolate → Root Cause → Fix → Regression Test. Do not skip steps. `git bisect` for regressions. 2 failed attempts → STOP and ASK USER.
 
 ## Release Planning (Task Ships a Release)
 
@@ -249,7 +254,7 @@ Per-user memory at `~/.claude/projects/<proj>/memory/` accumulates private learn
 - `type: project` → manual review (mixed state + portable lesson)
 - `type: feedback` → manual review (mixed personal preference + portable rule)
 
-**Destinations for promote entries** (no new files): tool/platform gotchas → `SDLC.md` `## Lessons Learned`. Testing → `TESTING.md`. Tool quirks tied to a skill → that `SKILL.md`. Process rules → `CLAUDE.md`.
+**Destinations** (no new files): gotchas → `SDLC.md`. Testing → `TESTING.md`. Skill quirks → that `SKILL.md`. Process rules → `/sdlc`. **Memory that's a process rule = /sdlc gap — use /feedback.**
 
 **Tracking:** `promoted_to: <path>` in the memory file's YAML frontmatter; later audits skip already-promoted entries.