agentic-sdlc-wizard 1.22.0 → 1.24.0

package/CHANGELOG.md

@@ -4,6 +4,43 @@ 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.24.0] - 2026-04-04
+
+### Added
+- Hook `if` conditionals — CC v2.1.85+ `if` field on PreToolUse hook. TDD check only spawns for source files (repo: `.github/workflows/*`, template: `src/**`). Documented in wizard CC features section with matcher-vs-if comparison table (#68)
+- Autocompact tuning guidance — `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` and `CLAUDE_CODE_AUTO_COMPACT_WINDOW` env vars with community-recommended thresholds (75% for 200K, 30% for 1M). 1M vs 200K context window comparison table. Setup wizard Step 9.5 for context window configuration (#88)
+- 6 hook tests for `if` field (52 total hook tests)
+- 5 autocompact/context tests (70 total self-update tests)
+
+### Fixed
+- E2E tdd_red detection — three bugs since inception: test-only scenarios scored 0 (missing elif branch), golden outputs were .txt not JSON, golden-scores.json encoded the bug it was meant to catch. Codex cross-model review caught regex false-positive + missing JSON pairing (#86)
+- 29 deterministic + 9 regression tests for tdd_red fix
+
+## [1.23.0] - 2026-04-01
+
+### Added
+- Update notification hook — `instructions-loaded-check.sh` checks npm for newer wizard version each session. Non-blocking, graceful on network failure. One-liner: "SDLC Wizard update available: X → Y (run /update-wizard)" (#64)
+- Cross-model review standardization — mission-first handoff (mission/success/failure fields), preflight self-review doc, verification checklist, adversarial framing, domain template guidance, convergence reduced to 2-3 rounds. Audited 4 repos + 14 external repos + 7 papers (#72, #56)
+- Release Planning Gate — section in SDLC skill. Before implementing release items: list all, plan each at 95% confidence, identify blocks, present plans as batch. Prove It Gate strengthened with absorption check (#73)
+- 6 quality tests for update notification (fake npm in PATH, version comparison, failure modes)
+- 12 quality tests for cross-model review, context position, release planning
+- Testing Diamond boundary table — explicit E2E (UI/browser ~5%) vs Integration (API/no UI ~90%) vs Unit (pure logic ~5%) in SKILL.md and wizard doc (#65)
+- Skill frontmatter docs — expanded to full table covering `paths:`, `context: fork`, `effort:`, `disable-model-invocation:`, `argument-hint:` (#69)
+- `--bare` mode documentation in SKILL.md — complete wizard bypass warning for scripted headless calls (#70)
+- 6 quality tests for #65/#69/#70
+- "NEVER AUTO-MERGE" enforcement gate in CI Shepherd section — same weight as "ALL TESTS MUST PASS." Full shepherd sequence documented as mandatory (post-mortem from PR #145 incident)
+- Post-Mortem pattern — when process fails, feed it back: Incident → Root Cause → New Rule → Test → Ship. "Every mistake becomes a rule"
+- 4 quality tests for enforcement gate + post-mortem
+
+### Fixed
+- Dead-code pipe in `test_prove_it_absorption()` — `grep -qi | grep -qi` was a no-op (P1 from PR #145 CI review)
+
+### Changed
+- Moved "ALL TESTS MUST PASS" from 61% depth to 11% depth in SDLC skill (Lost in the Middle fix) (#57)
+- Prove It Gate now requires absorption check — "can this be a section in an existing skill?" — before proposing new skills/components
+- Wizard "E2E vs Manual Testing" section replaced with "E2E vs Integration — The Critical Boundary" (#65)
+- Wizard "Skill Effort Frontmatter" section expanded to "Skill Frontmatter Fields" with full field reference (#69)
+
 ## [1.22.0] - 2026-04-01
 
 ### Added

package/CLAUDE_CODE_SDLC_WIZARD.md

@@ -307,9 +307,24 @@ New built-in commands available to use alongside the wizard:
 
 **Tip**: `/simplify` pairs well with the self-review phase. Run it after implementation as an additional quality check.
 
-### Skill Effort Frontmatter (v2.1.80+)
+### Skill Frontmatter Fields (v2.1.80+)
 
-Skills can now set an `effort` level in frontmatter. The wizard's `/sdlc` skill uses `effort: high` to ensure Claude gives full attention to SDLC tasks.
+Skills support these frontmatter fields:
+
+| Field | Purpose | Example |
+|-------|---------|---------|
+| `name` | Skill name (matches `/command`) | `name: sdlc` |
+| `description` | Trigger description for auto-invocation | `description: Full SDLC workflow...` |
+| `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]` |
+| `disable-model-invocation` | Prevent skill from being auto-invoked by model | `disable-model-invocation: true` |
+
+**Key fields explained:**
+- **`effort: high`** — The wizard's `/sdlc` skill uses this to ensure Claude gives full attention. `max` is available but costs significantly more tokens.
+- **`paths:`** — Limits when a skill activates based on files being worked on. Useful for language-specific or directory-specific skills.
+- **`context: fork`** — Runs the skill in an isolated subagent context. The subagent gets its own context window, so it won't pollute the main conversation. Useful for review skills or analysis that should run independently.
 
 ### InstructionsLoaded Hook (v2.1.69+)
 
@@ -323,6 +338,29 @@ Skills can now reference companion files using `${CLAUDE_SKILL_DIR}`. Useful if
 
 Hook events now include `agent_id` and `agent_type` fields. Hooks can behave differently for subagents vs the main agent if needed.
 
+### Hook `if` Conditionals (v2.1.85+)
+
+The `if` field on individual hook handlers filters by tool name AND arguments using permission rule syntax. The hook process only spawns when the condition matches — reducing unnecessary process spawns.
+
+```json
+{
+  "type": "command",
+  "if": "Write(src/**) Edit(src/**) MultiEdit(src/**)",
+  "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/tdd-pretool-check.sh"
+}
+```
+
+| Field | Level | Matches On | Syntax |
+|-------|-------|------------|--------|
+| `matcher` | Group (all hooks in array) | Tool name only | Regex (`Write\|Edit`) |
+| `if` | Individual handler | Tool name + arguments | Permission rule (`Edit(src/**)`) |
+
+**Pattern examples:** `Edit(*.ts)`, `Write(src/**)`, `Bash(git *)`. Same syntax as `allowedTools` in settings.json.
+
+**Only works on tool-use events:** `PreToolUse`, `PostToolUse`, `PostToolUseFailure`. Adding `if` to non-tool events prevents the hook from running.
+
+**CUSTOMIZE:** Replace `src/**` with your source directory pattern. The wizard generates this based on your project structure detected in Step 0.4.
+
 ### Security Hardening (v2.1.49-v2.1.78)
 
 Several fixes that strengthen wizard enforcement:
@@ -475,10 +513,11 @@ Here's the "Testing Diamond" approach (recommended for AI agents):
 - **Confidence**: If integration tests pass, production usually works
 - **AI-friendly**: Give Claude concrete pass/fail feedback on real behavior
 
-**E2E vs Manual Testing:**
-- **E2E (automated)**: Playwright, Cypress - runs without human
-- **Manual testing**: Human sign-off at the very end
-- **Goal**: Zero manual testing. Only for final verification when 100% confident.
+**E2E vs Integration — The Critical Boundary:**
+- **E2E**: Tests that go through the user's actual UI/browser (Playwright, Cypress). ~5% of suite.
+- **Integration**: Tests that hit real systems via API without UI — real DB, real cache, real services. ~90% of suite.
+- **Unit**: Pure logic only — no DB, no API, no filesystem. ~5% of suite.
+- **The rule**: If your test doesn't open a browser or render a UI, it's not E2E — it's integration. Mislabeling leads to overinvestment in slow browser tests.
 
 **But your team decides:**
 
@@ -677,12 +716,66 @@ Two tools for managing context — use the right one:
 - `/clear` after 2+ failed corrections on the same issue (context is polluted with bad approaches — start fresh with a better prompt)
 - After committing a PR, `/clear` before starting the next feature
 
-**Auto-compact** fires automatically at ~95% context capacity. You don't need to manage this manually — Claude Code handles it. The SDLC skill suggests `/compact` during CI idle time as a "context GC" opportunity.
+**Auto-compact** fires automatically at ~95% context capacity. Claude Code handles this by default — but the default threshold may not be ideal for all use cases (see "Autocompact Tuning" below). The SDLC skill suggests `/compact` during CI idle time as a "context GC" opportunity.
 
 **What survives `/compact`:** Key decisions, code changes, task state (as a summary). What can be lost: detailed early-conversation instructions not in CLAUDE.md, specific file contents read long ago.
 
 **Best practice:** Put persistent instructions in CLAUDE.md (survives both `/compact` and `/clear`), not in conversation.
 
+### Autocompact Tuning
+
+Override the default auto-compact threshold with environment variables. These are community-discovered settings referenced in upstream issues ([#34332](https://github.com/anthropics/claude-code/issues/34332), [#42375](https://github.com/anthropics/claude-code/issues/42375)) — not yet officially documented by Anthropic:
+
+| Variable | What It Does | Default |
+|----------|-------------|---------|
+| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | Trigger compaction at this % of context capacity (1-100) | ~95% |
+| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | Override context capacity in tokens (useful for 1M models) | Model default |
+
+Set these in your shell profile (`~/.bashrc`, `~/.zshrc`) or per-project `.envrc`:
+
+```bash
+# Example: compact earlier on a 200K model
+export CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=75
+```
+
+**Community-recommended thresholds by use case:**
+
+| Use Case | AUTOCOMPACT % | Why |
+|----------|--------------|-----|
+| General development (200K) | 75% | Leaves room for implementation after planning |
+| Complex refactors (200K) | 80% | Slightly more context before compaction |
+| CI pipelines | 60% | Short tasks, compact early to stay fast |
+| 1M context model | 30% | See "1M vs 200K" below — 95% on 1M wastes budget |
+| Short tasks | 60-70% | Less context needed, compact early |
+
+**Important:** Values above the default ~95% threshold have no effect — you can only trigger compaction *earlier*, not later. Noise (progress ticks, thinking blocks, stale reads) makes up 50-70% of session tokens, so threshold tuning matters less than noise reduction (scoped reads, subagents, `/compact` between phases).
+
+**Note:** These env vars may change as Claude Code evolves. Check [Claude Code settings docs](https://docs.anthropic.com/en/docs/claude-code/settings) for the latest supported configuration.
+
+### 1M vs 200K Context Window
+
+Claude Code supports both 200K and 1M context windows. Choose based on your task:
+
+| | 200K Context | 1M Context |
+|---|---|---|
+| **Best for** | Normal SDLC cycles (plan → TDD → review) | Multi-feature releases, deep codebase exploration |
+| **Typical usage** | 50-80K tokens per task | 200K+ tokens for complex workflows |
+| **Cost** | Lower total cost per session | ~5x more tokens consumed (cost scales linearly) |
+| **Auto-compact** | Default 95% works well | Reported to fire at ~76K ([issue #34332](https://github.com/anthropics/claude-code/issues/34332)) |
+| **Suggested override** | `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=75` | `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=30` or `CLAUDE_CODE_AUTO_COMPACT_WINDOW=400000` |
+
+**Default to 200K.** Normal SDLC tasks (single feature, bug fix, refactor) rarely exceed 80K tokens. The 200K window handles this with room to spare.
+
+**Switch to 1M when:**
+- Implementing multiple related features in one session
+- Deep research across a large codebase (reading 20+ files)
+- Multi-agent workflows that accumulate context
+- Complex debugging sessions that need full history
+
+**Cost awareness:** No per-token premium since March 2026, but total cost scales linearly with context consumed. A 900K-token session costs ~$4.50 in input alone. Use `/cost` to monitor.
+
+**1M autocompact workaround:** On 1M models, the default auto-compact has been reported to fire too early (~76K, per [issue #34332](https://github.com/anthropics/claude-code/issues/34332)). Community workaround: set `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=30` or `CLAUDE_CODE_AUTO_COMPACT_WINDOW=400000` to use more of the window.
+
 ---
 
 ## Example Workflow (End-to-End)
@@ -1043,8 +1136,10 @@ Feature branches still recommended for solo devs (keeps main clean, easy rollbac
 - **No** → Skip CI shepherd entirely (Claude still runs local tests, just doesn't interact with CI after pushing)
 
 **What the CI shepherd does:**
-1. **CI fix loop:** After pushing, Claude watches CI via `gh pr checks`, reads failure logs, diagnoses and fixes, pushes again (max 2 attempts)
-2. **Review feedback loop:** After CI passes, Claude reads automated review comments, implements valid suggestions, pushes and re-reviews (max 3 iterations)
+1. **CI fix loop:** After pushing, Claude watches CI via `gh pr checks`, reads logs on **pass and fail** (`gh run view <RUN_ID> --log`, not just `--log-failed`), diagnoses and fixes failures, pushes again (max 2 attempts)
+2. **Log review on pass:** Passing CI can still hide warnings, skipped steps, degraded scores, or silent test exclusions. A green checkmark is necessary but not sufficient — always read the logs
+3. **Review feedback loop:** After CI passes and logs look clean, Claude reads automated review comments, implements valid suggestions, pushes and re-reviews (max 3 iterations)
+4. **Pre-release CI audit:** Before cutting any release, review CI runs across ALL PRs merged since last release. Look for warnings in passing runs, degraded scores, skipped suites. Use `gh run list` + `gh run view <ID> --log`
 
 **Recommendation:** Yes if you have CI configured. The shepherd closes the loop between "local tests pass" and "PR is actually ready to merge."
 
@@ -1111,7 +1206,7 @@ Claude scans for:
 ├── Test frameworks: detected from config files and test patterns
 ├── Lint/format tools: from config files
 ├── CI/CD: .github/workflows/, .gitlab-ci.yml, etc.
-├── Feature docs: *_PLAN.md, *_DOCS.md, *_SPEC.md, docs/
+├── Feature docs: *_DOCS.md, docs/features/, docs/decisions/
 ├── README, CLAUDE.md, ARCHITECTURE.md
 │
 ├── Deployment targets (for ARCHITECTURE.md environments):
@@ -1528,6 +1623,7 @@ Create `.claude/settings.json`:
         "hooks": [
           {
             "type": "command",
+            "if": "Write(src/**) Edit(src/**) MultiEdit(src/**)",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/tdd-pretool-check.sh"
           }
         ]
@@ -1579,7 +1675,7 @@ The `allowedTools` array is auto-generated based on your stack detected in Step
 | Hook | When It Fires | Purpose |
 |------|---------------|---------|
 | `UserPromptSubmit` | Every message you send | Baseline SDLC reminder, skill auto-invoke |
-| `PreToolUse` | Before Claude edits files | TDD check: "Did you write the test first?" |
+| `PreToolUse` | Before Claude edits files | TDD check: "Did you write the test first?" Uses `if` field to only fire on source files |
 
 ### How Skill Auto-Invoke Works
 
@@ -1630,7 +1726,7 @@ Workflow phases:
 3. Implementation (TDD after compact)
 4. SELF-REVIEW (/code-review) → BEFORE presenting to user
 
-Quick refs: SDLC.md | TESTING.md | *_PLAN.md for feature
+Quick refs: SDLC.md | TESTING.md | *_DOCS.md for feature
 EOF
 ```
 
@@ -1713,7 +1809,7 @@ TodoWrite([
   { content: "Present approach + STATE CONFIDENCE LEVEL", status: "pending", activeForm: "Presenting approach" },
   { content: "Signal ready - user exits plan mode", status: "pending", activeForm: "Awaiting plan approval" },
   // TRANSITION PHASE (After plan mode, before compact)
-  { content: "Doc sync: update feature docs if code change contradicts or extends documented behavior", status: "pending", activeForm: "Syncing feature docs" },
+  { content: "Doc sync: update or create feature docs — MUST be current before commit", status: "pending", activeForm: "Syncing feature docs" },
   { content: "Request /compact before TDD", status: "pending", activeForm: "Requesting compact" },
   // IMPLEMENTATION PHASE (After compact)
   { content: "TDD RED: Write failing test FIRST", status: "pending", activeForm: "Writing failing test" },
@@ -1770,7 +1866,7 @@ TodoWrite([
 
 **Workflow:**
 1. **Plan Mode** (editing blocked): Research → Write plan file → Present approach + confidence
-2. **Transition** (after approval): Doc sync (update feature docs if code contradicts/extends them) → Request /compact
+2. **Transition** (after approval): Doc sync (update or create feature docs — MUST be current before commit) → Request /compact
 3. **Implementation** (after compact): TDD RED → GREEN → PASS
 
 **Before TDD, MUST ask:** "Docs updated. Run `/compact` before implementation?"
@@ -2270,10 +2366,10 @@ Create `CLAUDE.md` in your project root. This is your project-specific configura
 - Follow conventional commits: `type(scope): description`
 - NEVER commit with failing tests
 
-## Plan Docs
+## Feature Docs
 
-- Before coding a feature: READ its `*_PLAN.md` file
-- After completing work: UPDATE the plan doc
+- Before coding a feature: READ its `*_DOCS.md` file
+- After completing work: UPDATE the feature doc (or create one if 3+ files touched)
 
 ## Testing Notes
 
@@ -2401,7 +2497,7 @@ If deployment fails or post-deploy verification catches issues:
 
 **SDLC.md:**
 ```markdown
-<!-- SDLC Wizard Version: 1.22.0 -->
+<!-- SDLC Wizard Version: 1.24.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] -->
@@ -2725,7 +2821,7 @@ Want me to file these? (yes/no/not now)
 
 | Learning Type | Update Where |
 |---------------|--------------|
-| Feature-specific gotchas, decisions | Feature docs (`*_PLAN.md`, `*_DOCS.md`) |
+| Feature-specific gotchas, decisions | Feature docs (`*_DOCS.md`, e.g., `AUTH_DOCS.md`) |
 | Testing patterns, gotchas | `TESTING.md` |
 | Architecture decisions | `ARCHITECTURE.md` |
 | Commands, general project context | `CLAUDE.md` (or `/revise-claude-md`) |
@@ -2744,14 +2840,16 @@ Want me to file these? (yes/no/not now)
 
 ### Feature Documentation
 
-Keep feature docs alongside code. Three patterns, use what fits:
+Feature docs are living documents — the single source of truth for each feature, kept current just like `TESTING.md` and `ARCHITECTURE.md`. Use `*_DOCS.md` as the standard pattern:
 
 | Pattern | When to Use | Example |
 |---------|-------------|---------|
-| `*_PLAN.md` / `*_DOCS.md` | Per-feature living docs | `AUTH_DOCS.md`, `PAYMENTS_PLAN.md` |
+| `*_DOCS.md` | Per-feature living docs (primary) | `AUTH_DOCS.md`, `PAYMENTS_DOCS.md`, `SEARCH_DOCS.md` |
 | `docs/decisions/NNN-title.md` (ADR) | Architecture decisions that need rationale | `docs/decisions/001-use-postgres.md` |
 | `docs/features/name.md` | Feature docs in a `docs/` directory | `docs/features/auth.md` |
 
+**When to create a feature doc:** If a feature touches 3+ files and no `*_DOCS.md` exists, create one. Keep it simple — what the feature does, key decisions, gotchas. The doc grows with the feature over time.
+
 **Feature doc template:**
 
 ```markdown
@@ -2790,13 +2888,16 @@ What are the trade-offs? What becomes easier/harder?
 
 Store ADRs in `docs/decisions/`. Number sequentially. Claude reads these during planning to understand why things are built the way they are.
 
-**Keeping docs in sync with code:**
+**Keeping docs in sync with code (REQUIRED):**
 
-Docs drift when code changes but docs don't. The SDLC skill's planning phase detects this:
+Docs MUST be current before commit. Stale docs mislead future sessions, waste tokens, and cause wrong implementations. The SDLC skill enforces this:
 
 - During planning, Claude reads feature docs for the area being changed
-- If the code change contradicts what the doc says, Claude updates the doc
+- If the code change contradicts what the doc says → MUST update the doc
+- If the code change extends documented behavior → MUST add to the doc
+- If a `ROADMAP.md` exists → update it (mark items done, add new items). ROADMAP feeds CHANGELOG — keeping it current means releases write themselves
 - The "After Session" step routes learnings to the right doc
+- Plan files get closed out — if the session's work came from a plan, it gets deleted or marked complete so future sessions aren't misled
 - Stale docs cause low confidence — if Claude struggles, the doc may need updating
 
 **CLAUDE.md health:** Run `/claude-md-improver` periodically (quarterly or after major changes). It audits CLAUDE.md specifically — structure, clarity, completeness (6 criteria, 100-point rubric). It does NOT cover feature docs, TESTING.md, or ADRs — the SDLC workflow handles those.
@@ -3014,7 +3115,7 @@ Use an independent AI model from a different company as a code reviewer. The aut
 **The Protocol:**
 
 1. Create a `.reviews/` directory in your project
-2. After Claude completes its SDLC loop (self-review passes), write a handoff file:
+2. After Claude completes its SDLC loop (self-review passes), write a preflight doc (what you already checked) then a mission-first handoff file:
 
 ```jsonc
 // .reviews/handoff.json
@@ -3022,12 +3123,22 @@ Use an independent AI model from a different company as a code reviewer. The aut
   "review_id": "feature-xyz-001",
   "status": "PENDING_REVIEW",
   "round": 1,
+  "mission": "What changed and why — context for the reviewer",
+  "success": "What 'correctly reviewed' looks like",
+  "failure": "What gets missed if the reviewer is superficial",
   "files_changed": ["src/auth.ts", "tests/auth.test.ts"],
-  "review_instructions": "Review for security, edge cases, and correctness",
+  "verification_checklist": [
+    "(a) Verify input validation at auth.ts:45",
+    "(b) Verify test covers null-token edge case"
+  ],
+  "review_instructions": "Focus on security and edge cases. Assume bugs may be present until proven otherwise.",
+  "preflight_path": ".reviews/preflight-feature-xyz-001.md",
   "artifact_path": ".reviews/feature-xyz-001/"
 }
 ```
 
+The `mission/success/failure` fields give the reviewer context. Without them, you get generic "looks good" feedback. With them, reviewers dig into source files and verify specific claims. The `verification_checklist` tells the reviewer exactly what to verify — not "review this" but specific items with file:line references.
+
 3. Run the independent reviewer (Round 1 — full review). These commands use your Codex default model — configure it to the latest, most capable model available:
 
 ```bash
@@ -3131,6 +3242,7 @@ Claude writes code → self-review passes → handoff.json (round 1)
 - `-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.
 - `-o .reviews/latest-review.md` — Save the review output for Claude to read back.
+- **Claude Code sandbox bypass required:** Codex's Rust binary needs access to macOS system configuration APIs (`SCDynamicStore`) during initialization. Claude Code's sandbox blocks this, causing `codex exec` to crash with `panicked: Attempted to create a NULL object`. When running from within Claude Code, use `dangerouslyDisableSandbox: true` on the Bash tool call. This only bypasses CC's sandbox for the Codex process — Codex's own sandbox (`-s danger-full-access`) still applies. Known issue: [openai/codex#15640](https://github.com/openai/codex/issues/5914).
 
 **Tool-agnostic principle:** The core idea is "use a different model as an independent reviewer." Codex CLI is the concrete example today, but any competing AI tool that can read files and produce structured feedback works. The value comes from the independence and different training, not the specific tool.
 
@@ -3302,7 +3414,7 @@ Walk through updates? (y/n)
 Store wizard state in `SDLC.md` as metadata comments (invisible to readers, parseable by Claude):
 
 ```markdown
-<!-- SDLC Wizard Version: 1.22.0 -->
+<!-- SDLC Wizard Version: 1.24.0 -->
 <!-- Setup Date: 2026-01-24 -->
 <!-- Completed Steps: step-0.1, step-0.2, step-1, step-2, step-3, step-4, step-5, step-6, step-7, step-8, step-9 -->
 <!-- Git Workflow: PRs -->

package/README.md

@@ -2,6 +2,8 @@
 
 A **self-evolving Software Development Life Cycle (SDLC) enforcement system for AI coding agents**. Makes Claude plan before coding, test before shipping, and ask when uncertain. Measures itself getting better over time.
 
+**Built on 15+ years of SDET and QA engineering experience** — battle-tested patterns from real production systems, baked into an AI agent that follows tried-and-true software quality practices so you don't have to enforce them manually.
+
 ## Install
 
 **Requires [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)** (Anthropic's CLI for Claude).

package/cli/templates/hooks/instructions-loaded-check.sh

@@ -20,4 +20,47 @@ if [ -n "$MISSING" ]; then
     echo "Invoke Skill tool, skill=\"setup-wizard\" to generate them."
 fi
 
+# Version update check (non-blocking, best-effort)
+SDLC_MD="$PROJECT_DIR/SDLC.md"
+if [ -f "$SDLC_MD" ]; then
+    INSTALLED_VERSION=$(grep -o 'SDLC Wizard Version: [0-9.]*' "$SDLC_MD" | head -1 | sed 's/SDLC Wizard Version: //')
+    if [ -n "$INSTALLED_VERSION" ] && command -v npm > /dev/null 2>&1; then
+        LATEST_VERSION=$(npm view agentic-sdlc-wizard version 2>/dev/null) || true
+        if [ -n "$LATEST_VERSION" ] && [ "$LATEST_VERSION" != "$INSTALLED_VERSION" ]; then
+            echo "SDLC Wizard update available: ${INSTALLED_VERSION} → ${LATEST_VERSION} (run /update-wizard)"
+        fi
+    fi
+fi
+
+# Cross-model review staleness check (non-blocking, best-effort)
+if command -v codex > /dev/null 2>&1 && [ -d "$PROJECT_DIR/.reviews" ]; then
+    REVIEW_FILE="$PROJECT_DIR/.reviews/latest-review.md"
+    if [ -f "$REVIEW_FILE" ]; then
+        # Get file modification time (macOS stat -f %m, Linux stat -c %Y)
+        if stat -f %m "$REVIEW_FILE" > /dev/null 2>&1; then
+            REVIEW_MTIME=$(stat -f %m "$REVIEW_FILE")
+        else
+            REVIEW_MTIME=$(stat -c %Y "$REVIEW_FILE" 2>/dev/null || echo "0")
+        fi
+        NOW=$(date +%s)
+        REVIEW_AGE=$(( (NOW - REVIEW_MTIME) / 86400 ))
+        # Count commits since last review
+        COMMITS_SINCE=$(git -C "$PROJECT_DIR" log --oneline --after="@${REVIEW_MTIME}" 2>/dev/null | wc -l | tr -d ' ') || true
+        if [ "$REVIEW_AGE" -gt 3 ] && [ "${COMMITS_SINCE:-0}" -gt 5 ]; then
+            echo "WARNING: ${COMMITS_SINCE} commits over ${REVIEW_AGE}d since last cross-model review — reviews may not be running. Verify: codex exec \"echo test\""
+        fi
+    fi
+fi
+
+# Claude Code version check (non-blocking, best-effort)
+if command -v claude > /dev/null 2>&1 && command -v npm > /dev/null 2>&1; then
+    CC_LOCAL=$(claude --version 2>/dev/null | grep -o '[0-9][0-9.]*' | head -1) || true
+    if [ -n "$CC_LOCAL" ]; then
+        CC_LATEST=$(npm view @anthropic-ai/claude-code version 2>/dev/null) || true
+        if [ -n "$CC_LATEST" ] && [ "$CC_LATEST" != "$CC_LOCAL" ]; then
+            echo "Claude Code update available: ${CC_LOCAL} → ${CC_LATEST} (run: npm install -g @anthropic-ai/claude-code)"
+        fi
+    fi
+fi
+
 exit 0

package/cli/templates/hooks/sdlc-prompt-check.sh

@@ -24,7 +24,7 @@ SDLC BASELINE:
 5. ALL TESTS MUST PASS BEFORE COMMIT - NO EXCEPTIONS
 
 AUTO-INVOKE SKILL (Claude MUST do this FIRST):
-- implement/fix/refactor/feature/bug/build/test/TDD → Invoke: Skill tool, skill="sdlc"
+- implement/fix/refactor/feature/bug/build/test/TDD/release/publish/deploy → Invoke: Skill tool, skill="sdlc"
 - DON'T invoke for: questions, explanations, reading/exploring code, simple queries
 - DON'T wait for user to type /sdlc - AUTO-INVOKE based on task type
 

package/cli/templates/settings.json

@@ -16,6 +16,7 @@
         "hooks": [
           {
             "type": "command",
+            "if": "Write(src/**) Edit(src/**) MultiEdit(src/**)",
             "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/tdd-pretool-check.sh"
           }
         ]

package/cli/templates/skills/sdlc/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sdlc
-description: Full SDLC workflow for implementing features, fixing bugs, refactoring code, testing, and creating new functionality. Use this skill when implementing, fixing, refactoring, testing, adding features, or building new code.
+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: high
 ---
@@ -27,7 +27,7 @@ TodoWrite([
   { content: "Present approach + STATE CONFIDENCE LEVEL", status: "pending", activeForm: "Presenting approach" },
   { content: "Signal ready - user exits plan mode", status: "pending", activeForm: "Awaiting plan approval" },
   // TRANSITION PHASE (After plan mode)
-  { content: "Doc sync: update feature docs if code change contradicts or extends documented behavior", status: "pending", activeForm: "Syncing feature docs" },
+  { content: "Doc sync: update or create feature docs — MUST be current before commit", status: "pending", activeForm: "Syncing feature docs" },
   // IMPLEMENTATION PHASE
   { content: "TDD RED: Write failing test FIRST", status: "pending", activeForm: "Writing failing test" },
   { content: "TDD GREEN: Implement, verify test passes", status: "pending", activeForm: "Implementing feature" },
@@ -48,7 +48,8 @@ TodoWrite([
   { content: "Post-deploy verification (if deploy task — see Deployment Tasks)", status: "pending", activeForm: "Verifying deployment" },
   // FINAL
   { content: "Present summary: changes, tests, CI status", status: "pending", activeForm: "Presenting final summary" },
-  { content: "Capture learnings (if any — update TESTING.md, CLAUDE.md, or feature docs)", status: "pending", activeForm: "Capturing session learnings" }
+  { content: "Capture learnings (if any — update TESTING.md, CLAUDE.md, or feature docs)", status: "pending", activeForm: "Capturing session learnings" },
+  { content: "Close out plan files: if task came from a plan, mark complete or delete", status: "pending", activeForm: "Closing plan artifacts" }
 ])
 ```
 
@@ -72,6 +73,42 @@ Your work is scored on these criteria. **Critical** criteria are must-pass.
 
 Critical miss on `tdd_red` or `self_review` = process failure regardless of total score.
 
+## Test Failure Recovery (SDET Philosophy)
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  ALL TESTS MUST PASS. NO EXCEPTIONS.                                │
+│                                                                     │
+│  This is not negotiable. This is not flexible. This is absolute.   │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+**Not acceptable:**
+- "Those were already failing" → Fix them first
+- "Not related to my changes" → Doesn't matter, fix it
+- "It's flaky" → Flaky = bug, investigate
+
+**Treat test code like app code.** Test failures are bugs. Investigate them the way a 15-year SDET would - with thought and care, not by brushing them aside.
+
+If tests fail:
+1. Identify which test(s) failed
+2. Diagnose WHY - this is the important part:
+   - Your code broke it? Fix your code (regression)
+   - Test is for deleted code? Delete the test
+   - Test has wrong assertions? Fix the test
+   - Test is "flaky"? Investigate - flakiness is just another word for bug
+3. Fix appropriately (fix code, fix test, or delete dead test)
+4. Run specific test individually first
+5. Then run ALL tests
+6. Still failing? ASK USER - don't spin your wheels
+
+**Flaky tests are bugs, not mysteries:**
+- Sometimes the bug is in app code (race condition, timing issue)
+- Sometimes the bug is in test code (shared state, not parallel-safe)
+- Sometimes the bug is in test environment (cleanup not proper)
+
+Debug it. Find root cause. Fix it properly. Tests ARE code.
+
 ## New Pattern & Test Design Scrutiny (PLANNING)
 
 **New design patterns require human approval:**
@@ -89,11 +126,12 @@ Critical miss on `tdd_red` or `self_review` = process failure regardless of tota
 
 **Adding a new skill, hook, workflow, or component? PROVE IT FIRST:**
 
-1. **Research:** Does something equivalent already exist (native CC, third-party plugin, existing skill)?
-2. **If YES:** Why is yours better? Show evidence (A/B test, quality comparison, gap analysis)
-3. **If NO:** What gap does this fill? Is the gap real or theoretical?
-4. **Quality tests:** New additions MUST have tests that prove OUTPUT QUALITY, not just existence
-5. **Less is more:** Every addition is maintenance burden. Default answer is NO unless proven YES
+1. **Absorption check:** Can this be added as a section in an existing skill instead of a new component? Default is YES — new skills/hooks need strong justification. Releasing is SDLC, not a separate skill. Debugging is SDLC, not a separate skill. Keep it lean
+2. **Research:** Does something equivalent already exist (native CC, third-party plugin, existing skill)?
+3. **If YES:** Why is yours better? Show evidence (A/B test, quality comparison, gap analysis)
+4. **If NO:** What gap does this fill? Is the gap real or theoretical?
+5. **Quality tests:** New additions MUST have tests that prove OUTPUT QUALITY, not just existence
+6. **Less is more:** Every addition is maintenance burden. Default answer is NO unless proven YES
 
 **Existence tests are NOT quality tests:**
 - BAD: "ci-analyzer skill file exists" — proves nothing about quality
@@ -131,9 +169,9 @@ Before presenting approach, STATE your confidence:
 |-------|---------|--------|--------|
 | HIGH (90%+) | Know exactly what to do | Present approach, proceed after approval | `high` (default) |
 | MEDIUM (60-89%) | Solid approach, some uncertainty | Present approach, highlight uncertainties | `high` (default) |
-| LOW (<60%) | Not sure | ASK USER before proceeding | Consider `/effort max` |
-| FAILED 2x | Something's wrong | STOP. ASK USER immediately | Try `/effort max` |
-| CONFUSED | Can't diagnose why something is failing | STOP. Describe what you tried, ask for help | Try `/effort max` |
+| LOW (<60%) | Not sure | Do more research or try cross-model research (Codex) to get to 95%. If still LOW after research, ASK USER | Consider `/effort max` |
+| FAILED 2x | Something's wrong | Try cross-model research (Codex) for a fresh perspective. If still stuck, STOP and ASK USER | Try `/effort max` |
+| CONFUSED | Can't diagnose why something is failing | Try cross-model research (Codex). If still confused, STOP. Describe what you tried, ask for help | Try `/effort max` |
 
 ## Self-Review Loop (CRITICAL)
 
@@ -166,36 +204,78 @@ PLANNING -> DOCS -> TDD RED -> TDD GREEN -> Tests Pass -> Self-Review
 
 **Prerequisites:** Codex CLI installed (`npm i -g @openai/codex`), OpenAI API key set.
 
-### Round 1: Initial Review
+**The core insight:** The review PROTOCOL is universal across domains. Only the review INSTRUCTIONS change. Code review is the default template below. For non-code domains (research, persuasion, medical content), adapt the `review_instructions` and `verification_checklist` fields while keeping the same handoff/dialogue/convergence loop.
 
-1. After self-review passes, write `.reviews/handoff.json`:
-   ```jsonc
-   {
-     "review_id": "feature-xyz-001",
-     "status": "PENDING_REVIEW",
-     "round": 1,
-     "files_changed": ["src/auth.ts", "tests/auth.test.ts"],
-     "review_instructions": "Review for security, edge cases, and correctness",
-     "artifact_path": ".reviews/feature-xyz-001/"
-   }
-   ```
-2. Run the independent reviewer:
-   ```bash
-   codex exec \
-     -c 'model_reasoning_effort="xhigh"' \
-     -s danger-full-access \
-     -o .reviews/latest-review.md \
-     "You are an independent code reviewer. Read .reviews/handoff.json, \
-      review the listed files. Output each finding with: an ID (1, 2, ...), \
-      severity (P0/P1/P2), description, and a 'certify condition' stating \
-      what specific change would resolve it. \
-      End with CERTIFIED or NOT CERTIFIED."
-   ```
-3. If CERTIFIED → proceed to CI. If NOT CERTIFIED → go to Round 2.
+### Step 0: Write Preflight Self-Review Doc
 
-### Round 2+: Dialogue Loop
+Before submitting to an external reviewer, document what YOU already checked. This is proven to reduce reviewer findings to 0-1 per round (evidence: anticheat repo preflight discipline).
 
-When the reviewer finds issues, respond per-finding instead of silently fixing everything:
+Write `.reviews/preflight-{review_id}.md`:
+```markdown
+## Preflight Self-Review: {feature}
+- [ ] Self-review via /code-review passed
+- [ ] All tests passing
+- [ ] Checked for: [specific concerns for this change]
+- [ ] Verified: [what you manually confirmed]
+- [ ] Known limitations: [what you couldn't verify]
+```
+
+### Step 1: Write Mission-First Handoff
+
+After self-review and preflight pass, write `.reviews/handoff.json`:
+```jsonc
+{
+  "review_id": "feature-xyz-001",
+  "status": "PENDING_REVIEW",
+  "round": 1,
+  "mission": "What changed and why — 2-3 sentences of context",
+  "success": "What 'correctly reviewed' looks like — the reviewer's goal",
+  "failure": "What gets missed if the reviewer is superficial",
+  "files_changed": ["src/auth.ts", "tests/auth.test.ts"],
+  "fixes_applied": [],
+  "previous_score": null,
+  "verification_checklist": [
+    "(a) Verify input validation at auth.ts:45 handles empty strings",
+    "(b) Verify test covers the null-token edge case",
+    "(c) Check no hardcoded secrets in diff"
+  ],
+  "review_instructions": "Focus on security and edge cases. Be strict — assume bugs may be present until proven otherwise.",
+  "preflight_path": ".reviews/preflight-feature-xyz-001.md",
+  "artifact_path": ".reviews/feature-xyz-001/"
+}
+```
+
+**Key fields explained:**
+- `mission/success/failure` — Gives the reviewer context. Without this, you get generic "looks good" feedback. With it, reviewers read raw source files and verify specific claims (proven across 4 repos)
+- `verification_checklist` — Specific things to verify with file:line references. NOT "review for correctness" — that's too vague. Each item is independently verifiable
+- `preflight_path` — Shows the reviewer what you already checked, so they focus on what you might have missed
+
+### Step 2: Run the Independent Reviewer
+
+```bash
+codex exec \
+  -c 'model_reasoning_effort="xhigh"' \
+  -s danger-full-access \
+  -o .reviews/latest-review.md \
+  "You are an independent code reviewer performing a certification audit. \
+   Read .reviews/handoff.json for full context — mission, success/failure \
+   conditions, and verification checklist. \
+   Verify each checklist item with evidence (file:line, grep results, test output). \
+   Output each finding with: ID (1, 2, ...), severity (P0/P1/P2), evidence, \
+   and a 'certify condition' (what specific change resolves it). \
+   Re-verify any prior-round passes still hold. \
+   End with: score (1-10), CERTIFIED or NOT CERTIFIED."
+```
+
+**Always use `xhigh` reasoning effort.** Lower settings miss subtle errors (wrong-generation references, stale pricing, cross-file inconsistencies).
+
+**Sandbox note:** Codex's Rust binary requires access to macOS system configuration APIs (`SCDynamicStore`) during sandbox initialization. Claude Code's sandbox blocks this access, causing `codex exec` to crash with `system-configuration panicked: Attempted to create a NULL object`. When running `codex exec` from within Claude Code, you MUST use `dangerouslyDisableSandbox: true` on the Bash tool call. This is safe — Codex has its own sandbox (`-s danger-full-access` is already specified), and the CC sandbox bypass only affects the Codex process. This is a known Codex issue ([#15640](https://github.com/openai/codex/issues/15640)).
+
+If CERTIFIED → proceed to CI. If NOT CERTIFIED → go to dialogue loop.
+
+### Step 3: Dialogue Loop
+
+Respond per-finding — don't silently fix everything:
 
 1. Write `.reviews/response.json`:
    ```jsonc
@@ -205,16 +285,16 @@ When the reviewer finds issues, respond per-finding instead of silently fixing e
      "responding_to": ".reviews/latest-review.md",
      "responses": [
        { "finding": "1", "action": "FIXED", "summary": "Added missing validation" },
-       { "finding": "2", "action": "DISPUTED", "justification": "This is intentional — see CODE_REVIEW_EXCEPTIONS.md" },
+       { "finding": "2", "action": "DISPUTED", "justification": "Intentional — see CODE_REVIEW_EXCEPTIONS.md" },
        { "finding": "3", "action": "ACCEPTED", "summary": "Will add test coverage" }
      ]
    }
    ```
-   - **FIXED**: "I fixed this. Here is what changed." Reviewer verifies.
-   - **DISPUTED**: "This is intentional/incorrect. Here is why." Reviewer accepts or rejects.
-   - **ACCEPTED**: "You are right. Fixing now." (Same as FIXED, batched.)
+   - **FIXED**: "I fixed this. Here's what changed." Reviewer verifies against certify condition.
+   - **DISPUTED**: "This is intentional/incorrect. Here's why." Reviewer accepts or rejects with reasoning.
+   - **ACCEPTED**: "You're right. Fixing now." (Same as FIXED, batched.)
 
-2. Update `handoff.json` with `"status": "PENDING_RECHECK"`, increment `round`, add `"response_path"` and `"previous_review"` fields.
+2. Update `handoff.json`: increment `round`, set `"status": "PENDING_RECHECK"`, add `fixes_applied` list with numbered items and file:line references, update `previous_score`.
 
 3. Run targeted recheck (NOT a full re-review):
    ```bash
@@ -222,86 +302,88 @@ When the reviewer finds issues, respond per-finding instead of silently fixing e
      -c 'model_reasoning_effort="xhigh"' \
      -s danger-full-access \
      -o .reviews/latest-review.md \
-     "You are doing a TARGETED RECHECK. First read .reviews/handoff.json \
-      to find the previous_review path — read that file for the original \
-      findings and certify conditions. Then read .reviews/response.json \
-      for the author's responses. For each: \
-      FIXED → verify the fix against the original certify condition. \
-      DISPUTED → evaluate the justification (ACCEPT if sound, REJECT if not). \
+     "TARGETED RECHECK — not a full re-review. Read .reviews/handoff.json \
+      for previous_review path and response.json for the author's responses. \
+      For each finding: FIXED → verify against original certify condition. \
+      DISPUTED → evaluate justification (ACCEPT if sound, REJECT with reasoning). \
       ACCEPTED → verify it was applied. \
       Do NOT raise new findings unless P0 (critical/security). \
       New observations go in 'Notes for next review' (non-blocking). \
-      End with CERTIFIED or NOT CERTIFIED."
+      Re-verify all prior passes still hold. \
+      End with: score (1-10), CERTIFIED or NOT CERTIFIED."
    ```
 
-4. If CERTIFIED → done. If NOT CERTIFIED (rejected disputes or failed fixes) → fix rejected items and repeat.
-
 ### Convergence
 
-Max 3 recheck rounds (4 total including initial review). If still NOT CERTIFIED after round 4, escalate to the user with a summary of open findings. Don't spin indefinitely.
+**2 rounds is the sweet spot. 3 max.** Research across 14 repos and 7 papers confirms additional rounds beyond 3 produce <5% position shift.
+
+Max 2 recheck rounds (3 total including initial review). If still NOT CERTIFIED after round 3, escalate to the user with a summary of open findings.
 
 ```
-Self-review passes → handoff.json (round 1, PENDING_REVIEW)
-                            |
-                   Reviewer: FULL REVIEW (structured findings)
-                            |
-                   CERTIFIED? → YES → CI feedback loop
-                            |
-                            NO (findings with IDs + certify conditions)
-                            |
-                   Claude writes response.json:
-                     FIXED / DISPUTED / ACCEPTED per finding
-                            |
-                   handoff.json (round 2+, PENDING_RECHECK)
-                            |
-                   Reviewer: TARGETED RECHECK (previous findings only)
-                            |
-                   All resolved? → YES → CERTIFIED
-                            |
-                            NO → fix rejected items, repeat
-                            (max 3 rechecks, then escalate to user)
+Preflight → handoff.json (round 1) → FULL REVIEW
+                                          |
+                               CERTIFIED? → YES → CI
+                                          |
+                                          NO (scored findings)
+                                          |
+                               response.json (FIXED/DISPUTED/ACCEPTED)
+                                          |
+                               handoff.json (round 2+) → TARGETED RECHECK
+                                          |
+                               CERTIFIED? → YES → CI
+                                          |
+                                          NO → one more round, then escalate
 ```
 
 **Tool-agnostic:** The value is adversarial diversity (different model, different blind spots), not the specific tool. Any competing AI reviewer works.
 
-**Full protocol:** See the wizard's "Cross-Model Review Loop (Optional)" section for key flags and reasoning effort guidance.
+### Anti-Patterns to Avoid
+
+- **"Find at least N problems"** — Incentivizes false positives. Use adversarial framing ("assume bugs may be present") instead
+- **"Review this"** — Too vague, gets generic feedback. Use mission + verification checklist
+- **Numeric 1-10 scales without criteria** — Unreliable. Decompose into specific checklist items
+- **Letting reviewer see author's reasoning** — Causes anchoring bias. Let them form independent opinion from code
 
 ### Release Review Focus
 
-Before any release/publish, add these to `review_instructions`:
+Before any release/publish, add these to `verification_checklist`:
 - **CHANGELOG consistency** — all sections present, no lost entries during consolidation
 - **Version parity** — package.json, SDLC.md, CHANGELOG, wizard metadata all match
 - **Stale examples** — hardcoded version strings in docs match current release
 - **Docs accuracy** — README, ARCHITECTURE.md reflect current feature set
 - **CLI-distributed file parity** — live skills, hooks, settings match CLI templates
 
-Evidence: v1.20.0 cross-model review caught CHANGELOG section loss and stale wizard version examples that passed all tests and self-review. Tests catch version mismatches; cross-model review catches semantic issues tests cannot.
-
 ### Multiple Reviewers (N-Reviewer Pipeline)
 
 When multiple reviewers comment on a PR (Claude PR review, Codex, human reviewers), address each reviewer independently:
 
 1. **Read all reviews** — `gh api repos/OWNER/REPO/pulls/PR/comments` to get every reviewer's feedback
 2. **Respond per-reviewer** — Each reviewer has different blind spots and priorities. Address each one's findings separately
-3. **Resolve conflicts** — If reviewers disagree, use your judgment: pick the stronger argument, note why you chose it
-4. **Iterate until all approve** — Don't merge until every active reviewer is satisfied or their concerns are explicitly addressed
-5. **Max 3 iterations per reviewer** — If a reviewer keeps finding new things after 3 rounds, escalate to the user
+3. **Resolve conflicts** — If reviewers disagree, pick the stronger argument, note why
+4. **Iterate until all approve** — Don't merge until every active reviewer is satisfied
+5. **Max 3 iterations per reviewer** — If a reviewer keeps finding new things, escalate to the user
 
-**The value of multiple reviewers:** Different models/humans catch different issues. Claude excels at SDLC/process compliance. Codex catches logic bugs. Humans catch "does this make sense for the product?" None alone is sufficient for high-stakes changes.
+### Adapting for Non-Code Domains
 
-### Custom Subagents (`.claude/agents/`)
+The handoff format and dialogue loop work for ANY domain. Only `review_instructions` and `verification_checklist` change:
+
+| Domain | Instructions Focus | Checklist Example |
+|--------|-------------------|-------------------|
+| **Code (default)** | Security, logic bugs, test coverage | "Verify input validation at file:line" |
+| **Research/Docs** | Factual accuracy, source verification, overclaims | "Verify $736-$804 appears in both docs, no stale $695-$723 remains" |
+| **Persuasion** | Audience psychology, tone, trust | "If you were [audience], what's the moment you'd stop reading?" |
 
-Claude Code supports custom subagents in `.claude/agents/`. These are specialized agents you can invoke for focused tasks:
+For non-code: add `"audience"` and `"stakes"` fields to handoff.json. For code, these are implied (audience = other developers, stakes = production impact).
 
-- **`sdlc-reviewer`** — An agent focused purely on SDLC compliance review (planning, TDD, self-review checks)
-- **`ci-debug`** — An agent specialized in diagnosing CI failures (reads logs, identifies root cause, suggests fix)
-- **`test-writer`** — An agent focused on writing quality tests following TESTING.md philosophies
+### Custom Subagents (`.claude/agents/`)
+
+Claude Code supports custom subagents in `.claude/agents/`:
 
-**When to use agents vs skills:**
-- **Skills** (`.claude/skills/`) — Prompts that guide Claude's behavior for a task type. Claude reads and follows them
-- **Agents** (`.claude/agents/`) — Independent subprocesses that run autonomously on a focused task and return results
+- **`sdlc-reviewer`** — SDLC compliance review (planning, TDD, self-review checks)
+- **`ci-debug`** — CI failure diagnosis (reads logs, identifies root cause, suggests fix)
+- **`test-writer`** — Quality tests following TESTING.md philosophies
 
-Agents are useful when you want parallel work (e.g., run `sdlc-reviewer` while you continue implementing) or when a task benefits from a fresh context window focused on one thing.
+**Skills** guide Claude's behavior. **Agents** run autonomously and return results. Use agents for parallel work or fresh context windows.
 
 ## Test Review (Harder Than Implementation)
 
@@ -315,6 +397,16 @@ During self-review, critique tests HARDER than app code:
 
 **Tests are the foundation.** Bad tests = false confidence = production bugs.
 
+### Testing Diamond — Know Your Layers
+
+| Layer | What It Tests | % of Suite | Key Trait |
+|-------|--------------|------------|-----------|
+| **E2E** | Full user flow through UI/browser (Playwright, Cypress) | ~5% | Slow, brittle, but proves the real thing works |
+| **Integration** | Real systems via API without UI — real DB, real cache, real services | ~90% | **Best bang for buck.** Fast, stable, high confidence |
+| **Unit** | Pure logic only — no DB, no API, no filesystem | ~5% | Fast but limited scope |
+
+**The critical boundary:** E2E tests go through the user's actual UI/browser. Integration tests hit real systems via API but without UI. If your test doesn't open a browser or render a UI, it's not E2E — it's integration. This distinction matters because mislabeling integration tests as E2E leads to overinvestment in slow browser tests when fast API-level tests would suffice.
+
 ### Minimal Mocking Philosophy
 
 | What | Mock? | Why |
@@ -366,42 +458,6 @@ If you notice something else that should be fixed:
 
 **Why this matters:** AI agents can drift into "helpful" changes that weren't requested. This creates unexpected diffs, breaks unrelated things, and makes code review harder.
 
-## Test Failure Recovery (SDET Philosophy)
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│  ALL TESTS MUST PASS. NO EXCEPTIONS.                                │
-│                                                                     │
-│  This is not negotiable. This is not flexible. This is absolute.   │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-**Not acceptable:**
-- "Those were already failing" → Fix them first
-- "Not related to my changes" → Doesn't matter, fix it
-- "It's flaky" → Flaky = bug, investigate
-
-**Treat test code like app code.** Test failures are bugs. Investigate them the way a 15-year SDET would - with thought and care, not by brushing them aside.
-
-If tests fail:
-1. Identify which test(s) failed
-2. Diagnose WHY - this is the important part:
-   - Your code broke it? Fix your code (regression)
-   - Test is for deleted code? Delete the test
-   - Test has wrong assertions? Fix the test
-   - Test is "flaky"? Investigate - flakiness is just another word for bug
-3. Fix appropriately (fix code, fix test, or delete dead test)
-4. Run specific test individually first
-5. Then run ALL tests
-6. Still failing? ASK USER - don't spin your wheels
-
-**Flaky tests are bugs, not mysteries:**
-- Sometimes the bug is in app code (race condition, timing issue)
-- Sometimes the bug is in test code (shared state, not parallel-safe)
-- Sometimes the bug is in test environment (cleanup not proper)
-
-Debug it. Find root cause. Fix it properly. Tests ARE code.
-
 ## Debugging Workflow (Systematic Investigation)
 
 When something breaks and the cause isn't obvious, follow this systematic debugging workflow:
@@ -451,25 +507,28 @@ Local tests pass -> Commit -> Push -> Watch CI
                                                    STOP and ASK USER
 ```
 
-**How to watch CI:**
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  NEVER AUTO-MERGE. NO EXCEPTIONS.                                   │
+│                                                                     │
+│  Do NOT run `gh pr merge --auto`. Ever.                            │
+│  Auto-merge fires before you can read review feedback.             │
+│  The shepherd loop IS the process. Skipping it = shipping bugs.    │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+**The full shepherd sequence — every step is mandatory:**
 1. Push changes to remote
-2. Check CI status:
-   ```bash
-   # Watch checks in real-time (blocks until complete)
-   gh pr checks --watch
+2. Watch CI: `gh pr checks --watch`
+3. Read CI logs — **pass or fail**: `gh run view <RUN_ID> --log` (not just `--log-failed`). Passing CI can still hide warnings, skipped steps, or degraded scores. Don't just check the green checkmark
+4. If CI fails → diagnose from logs, fix, push again (max 2 attempts)
+5. If CI passes → read ALL review comments: `gh api repos/OWNER/REPO/pulls/PR/comments`
+6. Fix valid suggestions, push, iterate until clean
+7. Only then: explicit merge with `gh pr merge --squash`
 
-   # Or check status without blocking
-   gh pr checks
+**Why this is non-negotiable:** PR #145 auto-merged a release before review feedback was read. CI reviewer found a P1 dead-code bug that shipped to main. The fix required a follow-up commit. Auto-merge cost more time than the shepherd loop would have taken.
 
-   # View specific failed run logs
-   gh run view <RUN_ID> --log-failed
-   ```
-3. If CI fails:
-   - Read failure logs: `gh run view <RUN_ID> --log-failed`
-   - Diagnose root cause (same philosophy as local test failures)
-   - Fix and push again
-4. Max 2 fix attempts - if still failing, ASK USER
-5. If CI passes - proceed to present final summary
+**Why read passing logs:** v1.24.0 release only read logs on failure (round 1), then just checked the green checkmark on round 2. Passing CI can hide warnings, skipped steps, degraded E2E scores, or silent test exclusions. A green checkmark is necessary but not sufficient.
 
 **Context GC (compact during idle):** While waiting for CI (typically 3-5 min), suggest `/compact` if the conversation is long. Think of it like a time-based garbage collector — idle time + high memory pressure = good time to collect. Don't suggest on short conversations.
 
@@ -518,6 +577,9 @@ CI passes -> Read review suggestions
 - `/clear` after 2+ failed corrections (context polluted — start fresh with better prompt)
 - Auto-compact fires at ~95% capacity — no manual management needed
 - After committing a PR, `/clear` before starting the next feature
+- **Autocompact tuning:** Set `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` to trigger compaction earlier (75% for 200K, 30% for 1M). On 1M models, the default fires at ~76K — set 30% or `CLAUDE_CODE_AUTO_COMPACT_WINDOW=400000` to use the full context window. See wizard doc "Autocompact Tuning" for full details
+
+**`--bare` mode (v2.1.81+):** `claude -p "prompt" --bare` skips ALL hooks, skills, LSP, and plugins. This is a complete wizard bypass — no SDLC enforcement, no TDD checks, no planning hooks. Use only for scripted headless calls (CI pipelines, automation) where you explicitly don't want wizard enforcement. Never use `--bare` for normal development work.
 
 ## DRY Principle
 
@@ -543,6 +605,24 @@ CI passes -> Read review suggestions
 
 **If no DESIGN_SYSTEM.md exists:** Skip these checks (project has no documented design system).
 
+## Release Planning (If Task Involves a Release)
+
+**When to check:** Task mentions "release", "publish", "version bump", "npm publish", or multiple items being shipped together.
+**When to skip:** Single feature implementation, bug fix, or anything that isn't a release.
+
+Before implementing any release items:
+
+1. **List all items** — Read ROADMAP.md (or equivalent), identify every item planned for this release
+2. **Plan each at 95% confidence** — For each item: what files change, what tests prove it works, what's the blast radius. If confidence < 95% on any item, flag it
+3. **Identify blocks** — Which items depend on others? What must go first?
+4. **Present all plans together** — User reviews the complete batch, not one at a time. This catches conflicts, sequencing issues, and scope creep before any code is written
+5. **Pre-release CI audit** — Before cutting the release, review CI runs across ALL PRs merged since last release. Look for: warnings in passing runs, degraded E2E scores, skipped test suites, silent failures masked by `continue-on-error`. Use `gh run list` + `gh run view <ID> --log` to audit. A green checkmark is necessary but not sufficient
+6. **User approves, then implement** — Full SDLC per item (TDD RED → GREEN → self-review), in the prioritized order
+
+**Why batch planning works:** Ad-hoc one-at-a-time implementation leads to unvalidated additions and scope creep. Batch planning catches problems early — if you can't plan it at 95%, you're not ready to ship it.
+
+**Why pre-release CI audit:** v1.24.0 shipped without auditing CI logs across merged PRs #150-#152. Passing CI doesn't mean nothing fishy got through — warnings, degraded scores, and skipped steps can hide in green runs.
+
 ## Deployment Tasks (If Task Involves Deploy)
 
 **When to check:** Task mentions "deploy", "release", "push to prod", "staging", etc.
@@ -588,14 +668,26 @@ CI passes -> Read review suggestions
 
 **THE RULE:** Delete old code first. If it breaks, fix it properly.
 
-## Documentation Sync (During Planning)
+## Documentation Sync (REQUIRED — During Planning)
+
+Feature docs MUST be current before commit. Docs are code — stale docs mislead future sessions, waste tokens, and cause wrong implementations.
 
-When a code change affects a documented feature, update the doc in the same PR:
+**Standard pattern:** `*_DOCS.md` — living documents that grow with the feature (e.g., `AUTH_DOCS.md`, `PAYMENTS_DOCS.md`, `SEARCH_DOCS.md`). Same philosophy as `TESTING.md` and `ARCHITECTURE.md` — one source of truth per topic, kept current.
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  DOCS MUST BE CURRENT BEFORE COMMIT.                                │
+│                                                                     │
+│  Stale docs = wrong implementations = wasted sessions.             │
+│  If you changed the feature, update its doc. No exceptions.        │
+└─────────────────────────────────────────────────────────────────────┘
+```
 
-1. **During planning**, read feature docs for the area being changed (`*_PLAN.md`, `*_DOCS.md`, `docs/features/`, `docs/decisions/`)
-2. If your code change contradicts what the doc says → update the doc
-3. If your code change extends behavior the doc describes → add to the doc
-4. If no feature doc exists and the change is substantial → note it in the summary (don't create one unprompted)
+1. **During planning**, read feature docs for the area being changed (`*_DOCS.md`, `docs/features/`, `docs/decisions/`)
+2. If your code change contradicts what the doc says → MUST update the doc
+3. If your code change extends behavior the doc describes → MUST add to the doc
+4. If no `*_DOCS.md` exists and the feature touches 3+ files → create one. Keep it simple: what the feature does, key decisions, gotchas. Same structure as TESTING.md (topic-focused, not exhaustive)
+5. If the project has a `ROADMAP.md` → update it (mark items done, add new items). ROADMAP feeds CHANGELOG — keeping it current means releases write themselves
 
 **Doc staleness signals:** Low confidence in an area often means the docs are stale, missing, or misleading. If you struggle during planning, check whether the docs match the actual code.
 
@@ -605,9 +697,29 @@ When a code change affects a documented feature, update the doc in the same PR:
 
 If this session revealed insights, update the right place:
 - **Testing patterns, gotchas** → `TESTING.md`
-- **Feature-specific quirks** → Feature docs (`*_PLAN.md`, `*_DOCS.md`)
+- **Feature-specific quirks** → Feature docs (`*_DOCS.md`, e.g., `AUTH_DOCS.md`)
 - **Architecture decisions** → `docs/decisions/` (ADR format) or `ARCHITECTURE.md`
 - **General project context** → `CLAUDE.md` (or `/revise-claude-md`)
+- **Plan files** → If this session's work came from a plan file, delete it or mark it complete. Stale plans mislead future sessions into thinking work is still pending
+
+## Post-Mortem: When Process Fails, Feed It Back
+
+**Every process failure becomes an enforcement rule.** When you skip a step and it causes a problem, don't just fix the symptom — add a gate so it can't happen again.
+
+```
+Incident → Root Cause → New Rule → Test That Proves the Rule → Ship
+```
+
+**How to post-mortem a process failure:**
+1. **What happened?** — Describe the incident (what went wrong, what was the impact)
+2. **Root cause** — Not "I forgot" — what structurally allowed the skip? Was it guidance (easy to ignore) instead of a gate (impossible to skip)?
+3. **New rule** — Turn the failure into an enforcement rule in the SDLC skill
+4. **Test** — Write a test that proves the rule exists (TDD — the rule is code too)
+5. **Evidence** — Reference the incident so future readers understand WHY the rule exists
+
+**Example (real incident):** PR #145 auto-merged before CI review was read. Root cause: auto-merge was enabled by default, no enforcement gate existed. New rule: "NEVER AUTO-MERGE" block added to CI Shepherd section with the same weight as "ALL TESTS MUST PASS." Test: `test_never_auto_merge_gate` verifies the block exists.
+
+**Industry pattern:** "Every mistake becomes a rule" — the best SDLC systems are built from accumulated incident learnings, not theoretical best practices.
 
 ---
 

package/cli/templates/skills/setup/SKILL.md

@@ -171,6 +171,16 @@ Based on detected stack, suggest `allowedTools` entries for `.claude/settings.js
 
 Present suggestions and let the user confirm.
 
+### Step 9.5: Context Window Configuration
+
+Recommend autocompact settings based on the user's context window:
+
+- **200K models (default):** Suggest `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=75` — leaves room for implementation after planning
+- **1M models:** Suggest `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=30` or `CLAUDE_CODE_AUTO_COMPACT_WINDOW=400000` — the default fires at ~76K on 1M, wasting 92% of the window
+- **CI pipelines:** Suggest 60% — short tasks, compact early
+
+Tell the user to add the export to their shell profile (`~/.bashrc`, `~/.zshrc`) or project `.envrc`. This is guidance, not enforcement — the wizard doesn't write shell profiles.
+
 ### Step 10: Customize Hooks
 
 Update `tdd-pretool-check.sh` with the actual source directory (replace generic `/src/` pattern).

package/cli/templates/skills/update/SKILL.md

@@ -45,13 +45,14 @@ Extract the latest version from the first `## [X.X.X]` line.
 Parse all CHANGELOG entries between the user's installed version and the latest. Present a clear summary:
 
 ```
-Installed: 1.20.0
-Latest:    1.22.0
+Installed: 1.22.0
+Latest:    1.24.0
 
 What changed:
+- [1.24.0] Hook if conditionals, autocompact tuning + 1M/200K guidance, tdd_red fix, ...
+- [1.23.0] Update notification hook, cross-model review standardization, ...
 - [1.22.0] Plan auto-approval, debugging workflow, /feedback skill, BRANDING.md detection, ...
 - [1.21.0] Confidence-driven setup, prove-it gate, cross-model release review, ...
-- [1.20.0] Version-pinned CC update gate, Tier 1 flakiness fix, flaky test guidance, ...
 ```
 
 **If versions match:** Say "You're up to date! (version X.X.X)" and stop.

package/package.json

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