agentic-sdlc-wizard 1.23.0 → 1.25.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,24 @@
+{
+  "name": "sdlc-wizard-marketplace",
+  "owner": {
+    "name": "Stefan Ayala",
+    "email": "stefan@baseinfinity.dev"
+  },
+  "metadata": {
+    "description": "SDLC enforcement plugins for AI-assisted development",
+    "version": "1.0.0"
+  },
+  "plugins": [
+    {
+      "name": "sdlc-wizard",
+      "source": ".",
+      "description": "SDLC enforcement for AI agents — TDD, planning, self-review, CI shepherd",
+      "version": "1.25.0",
+      "author": {
+        "name": "Stefan Ayala"
+      },
+      "category": "productivity",
+      "tags": ["sdlc", "tdd", "code-quality", "testing"]
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,12 @@
+{
+  "name": "sdlc-wizard",
+  "version": "1.25.0",
+  "description": "SDLC enforcement for AI agents — TDD, planning, self-review, CI shepherd",
+  "author": {
+    "name": "Stefan Ayala",
+    "url": "https://github.com/BaseInfinity"
+  },
+  "repository": "https://github.com/BaseInfinity/agentic-ai-sdlc-wizard",
+  "license": "MIT",
+  "keywords": ["sdlc", "tdd", "code-quality", "ai-agent", "developer-tools"]
+}

package/CHANGELOG.md

@@ -4,6 +4,37 @@ 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.25.0] - 2026-04-04
+
+### Added
+- Claude Code plugin format — single source of truth: `skills/` and `hooks/` at repo root serve plugin + CLI. `.claude-plugin/plugin.json` manifest, `hooks/hooks.json` with `${CLAUDE_PLUGIN_ROOT}`, `.claude-plugin/marketplace.json` for self-hosted marketplace. Absorbs #66 + #87 (#89)
+- 6 distribution channels — npm, plugin, curl install script, Homebrew tap, gh CLI extension, GitHub Releases (#90)
+- `install.sh` curl-pipeable installer — download guard, strict mode, Node.js >= 18 check, `--global` flag, terminal-aware colors. 20 tests (structural + integration)
+- `.github/workflows/release.yml` — tag-push automation with npm publish --provenance (SLSA), GitHub Release via softprops/action-gh-release@v2. 14 tests
+- External repos: `BaseInfinity/homebrew-sdlc-wizard` (Homebrew tap), `BaseInfinity/gh-sdlc-wizard` (gh CLI extension)
+- 25 plugin format tests, 34 distribution tests (20 install + 14 release workflow)
+
+### Fixed
+- CI shepherd: enforce reading CI logs on pass AND fail (not just failures). Pre-release CI audit across merged PRs added to release planning gate
+
+### Changed
+- CLI `init.js` reads skills/hooks from repo root (single source, no duplication)
+- Dogfood `.claude/` uses symlinks to root skills/hooks
+- README: added curl, Homebrew, gh extension, GitHub install methods
+- CI_CD.md: added release.yml documentation + NPM_TOKEN secret
+
+## [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

package/CLAUDE_CODE_SDLC_WIZARD.md

@@ -338,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:
@@ -693,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)
@@ -1059,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."
 
@@ -1127,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):
@@ -1544,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"
           }
         ]
@@ -1595,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
 
@@ -1646,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
 ```
 
@@ -1729,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" },
@@ -1786,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?"
@@ -2286,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
 
@@ -2417,7 +2497,7 @@ If deployment fails or post-deploy verification catches issues:
 
 **SDLC.md:**
 ```markdown
-<!-- SDLC Wizard Version: 1.23.0 -->
+<!-- SDLC Wizard Version: 1.25.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] -->
@@ -2741,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`) |
@@ -2760,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
@@ -2806,12 +2888,14 @@ 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
@@ -3158,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.
 
@@ -3329,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.23.0 -->
+<!-- SDLC Wizard Version: 1.25.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).
@@ -15,11 +17,34 @@ Then start (or restart) Claude Code — type `/exit` then `claude` to reload hoo
 <details>
 <summary>Alternative install methods</summary>
 
-**From GitHub (no npm needed):**
+**curl (no npm install needed):**
+```bash
+curl -fsSL https://raw.githubusercontent.com/BaseInfinity/agentic-ai-sdlc-wizard/main/install.sh | bash
+```
+
+**Homebrew:**
+```bash
+brew install BaseInfinity/sdlc-wizard/sdlc-wizard
+sdlc-wizard init
+```
+
+**GitHub CLI extension:**
+```bash
+gh extension install BaseInfinity/gh-sdlc-wizard
+gh sdlc-wizard init
+```
+
+**From GitHub (no npm registry needed):**
 ```bash
 npx github:BaseInfinity/agentic-ai-sdlc-wizard init
 ```
 
+**Install CLI globally:**
+```bash
+npm install -g agentic-sdlc-wizard
+sdlc-wizard init
+```
+
 **Manual:** Download `CLAUDE_CODE_SDLC_WIZARD.md` to your project and tell Claude `Run the SDLC wizard setup`.
 </details>
 
@@ -204,7 +229,7 @@ This isn't the only Claude Code SDLC tool. Here's an honest comparison:
 | Document | What It Covers |
 |----------|---------------|
 | [ARCHITECTURE.md](ARCHITECTURE.md) | System design, 5-layer diagram, data flows, file structure |
-| [CI_CD.md](CI_CD.md) | All 4 workflows, E2E scoring, tier system, SDP, integrity checks |
+| [CI_CD.md](CI_CD.md) | All 5 workflows, E2E scoring, tier system, SDP, integrity checks |
 | [SDLC.md](SDLC.md) | Version tracking, enforcement rules, SDLC configuration |
 | [TESTING.md](TESTING.md) | Testing philosophy, test diamond, TDD approach |
 | [CHANGELOG.md](CHANGELOG.md) | Version history, what changed and when |

package/cli/init.js

@@ -11,18 +11,21 @@ const YELLOW = '\x1b[33m';
 const MAGENTA = '\x1b[35m';
 const CYAN = '\x1b[36m';
 
+const REPO_ROOT = path.join(__dirname, '..');
 const TEMPLATES_DIR = path.join(__dirname, 'templates');
-const WIZARD_DOC = path.join(__dirname, '..', 'CLAUDE_CODE_SDLC_WIZARD.md');
+const WIZARD_DOC = path.join(REPO_ROOT, 'CLAUDE_CODE_SDLC_WIZARD.md');
 
+// Skills and hooks live at repo root (single source of truth for both plugin and CLI)
+// Only settings.json remains in cli/templates/ (CLI-specific hook config)
 const FILES = [
-  { src: 'settings.json', dest: '.claude/settings.json' },
-  { src: 'hooks/sdlc-prompt-check.sh', dest: '.claude/hooks/sdlc-prompt-check.sh', executable: true },
-  { src: 'hooks/tdd-pretool-check.sh', dest: '.claude/hooks/tdd-pretool-check.sh', executable: true },
-  { src: 'hooks/instructions-loaded-check.sh', dest: '.claude/hooks/instructions-loaded-check.sh', executable: true },
-  { src: 'skills/sdlc/SKILL.md', dest: '.claude/skills/sdlc/SKILL.md' },
-  { src: 'skills/setup/SKILL.md', dest: '.claude/skills/setup/SKILL.md' },
-  { src: 'skills/update/SKILL.md', dest: '.claude/skills/update/SKILL.md' },
-  { src: 'skills/feedback/SKILL.md', dest: '.claude/skills/feedback/SKILL.md' },
+  { src: 'settings.json', dest: '.claude/settings.json', base: TEMPLATES_DIR },
+  { src: 'hooks/sdlc-prompt-check.sh', dest: '.claude/hooks/sdlc-prompt-check.sh', executable: true, base: REPO_ROOT },
+  { src: 'hooks/tdd-pretool-check.sh', dest: '.claude/hooks/tdd-pretool-check.sh', executable: true, base: REPO_ROOT },
+  { src: 'hooks/instructions-loaded-check.sh', dest: '.claude/hooks/instructions-loaded-check.sh', executable: true, base: REPO_ROOT },
+  { src: 'skills/sdlc/SKILL.md', dest: '.claude/skills/sdlc/SKILL.md', base: REPO_ROOT },
+  { src: 'skills/setup/SKILL.md', dest: '.claude/skills/setup/SKILL.md', base: REPO_ROOT },
+  { src: 'skills/update/SKILL.md', dest: '.claude/skills/update/SKILL.md', base: REPO_ROOT },
+  { src: 'skills/feedback/SKILL.md', dest: '.claude/skills/feedback/SKILL.md', base: REPO_ROOT },
 ];
 
 const WIZARD_HOOK_MARKERS = FILES
@@ -80,7 +83,7 @@ function planOperations(targetDir, { force }) {
 
   for (const file of FILES) {
     const destPath = path.join(targetDir, file.dest);
-    const srcPath = path.join(TEMPLATES_DIR, file.src);
+    const srcPath = path.join(file.base || TEMPLATES_DIR, file.src);
     const exists = fs.existsSync(destPath);
 
     if (exists && file.dest === '.claude/settings.json') {
@@ -245,7 +248,7 @@ function check(targetDir, { json = false } = {}) {
 
   for (const file of FILES) {
     const destPath = path.join(targetDir, file.dest);
-    const srcPath = path.join(TEMPLATES_DIR, file.src);
+    const srcPath = path.join(file.base || TEMPLATES_DIR, file.src);
     results.push(checkFile(srcPath, destPath, file.dest, file.executable || false));
   }
 

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/hooks/hooks.json

@@ -0,0 +1,37 @@
+{
+  "description": "SDLC Wizard enforcement hooks",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/sdlc-prompt-check.sh"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "if": "Write(src/**) Edit(src/**) MultiEdit(src/**)",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/tdd-pretool-check.sh"
+          }
+        ]
+      }
+    ],
+    "InstructionsLoaded": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/instructions-loaded-check.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/instructions-loaded-check.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# InstructionsLoaded hook - validates SDLC files exist at session start
+# Fires when Claude loads instructions (session start/resume)
+# Available since Claude Code v2.1.69
+# Note: no set -e — this hook must always exit 0 to not block session start
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
+MISSING=""
+
+if [ ! -f "$PROJECT_DIR/SDLC.md" ]; then
+    MISSING="${MISSING:+${MISSING}, }SDLC.md"
+fi
+
+if [ ! -f "$PROJECT_DIR/TESTING.md" ]; then
+    MISSING="${MISSING:+${MISSING}, }TESTING.md"
+fi
+
+if [ -n "$MISSING" ]; then
+    echo "WARNING: Missing SDLC wizard files: ${MISSING}"
+    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 → 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/package.json

@@ -1,12 +1,15 @@
 {
   "name": "agentic-sdlc-wizard",
-  "version": "1.23.0",
+  "version": "1.25.0",
   "description": "SDLC enforcement for Claude Code — hooks, skills, and wizard setup in one command",
   "bin": {
     "sdlc-wizard": "./cli/bin/sdlc-wizard.js"
   },
   "files": [
     "cli/",
+    "skills/",
+    "hooks/",
+    ".claude-plugin/",
     "CLAUDE_CODE_SDLC_WIZARD.md",
     "CHANGELOG.md"
   ],

package/{cli/templates/skills → 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" },
@@ -269,6 +269,8 @@ codex exec \
 
 **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
@@ -518,13 +520,16 @@ Local tests pass -> Commit -> Push -> Watch CI
 **The full shepherd sequence — every step is mandatory:**
 1. Push changes to remote
 2. Watch CI: `gh pr checks --watch`
-3. If CI fails → read logs (`gh run view <RUN_ID> --log-failed`), fix, push again (max 2 attempts)
-4. If CI passes → read ALL review comments: `gh api repos/OWNER/REPO/pulls/PR/comments`
-5. Fix valid suggestions, push, iterate until clean
-6. Only then: explicit merge with `gh pr merge --squash`
+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`
 
 **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.
 
+**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.
 
 **CI failures follow same rules as test failures:**
@@ -572,6 +577,7 @@ 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.
 
@@ -610,10 +616,13 @@ Before implementing any release items:
 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. **User approves, then implement** — Full SDLC per item (TDD RED → GREEN → self-review), in the prioritized order
+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.
@@ -659,14 +668,26 @@ Before implementing any release items:
 
 **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.
+
+**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.
 
-When a code change affects a documented feature, update the doc in the same PR:
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│  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.
 
@@ -676,7 +697,7 @@ 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

package/{cli/templates/skills → 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 → skills}/update/SKILL.md

@@ -45,14 +45,13 @@ 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.21.0
-Latest:    1.23.0
+Installed: 1.23.0
+Latest:    1.25.0
 
 What changed:
-- [1.23.0] Update notification hook, ...
-- [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, ...
+- [1.25.0] Plugin format, 6 distribution channels (curl, Homebrew, gh, GitHub Releases), ...
+- [1.24.0] Hook if conditionals, autocompact tuning + 1M/200K guidance, tdd_red fix, ...
+- [1.23.0] Update notification hook, cross-model review standardization, ...
 ```
 
 **If versions match:** Say "You're up to date! (version X.X.X)" and stop.

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

@@ -1,35 +0,0 @@
-#!/bin/bash
-# InstructionsLoaded hook - validates SDLC files exist at session start
-# Fires when Claude loads instructions (session start/resume)
-# Available since Claude Code v2.1.69
-# Note: no set -e — this hook must always exit 0 to not block session start
-
-PROJECT_DIR="${CLAUDE_PROJECT_DIR:-.}"
-MISSING=""
-
-if [ ! -f "$PROJECT_DIR/SDLC.md" ]; then
-    MISSING="${MISSING:+${MISSING}, }SDLC.md"
-fi
-
-if [ ! -f "$PROJECT_DIR/TESTING.md" ]; then
-    MISSING="${MISSING:+${MISSING}, }TESTING.md"
-fi
-
-if [ -n "$MISSING" ]; then
-    echo "WARNING: Missing SDLC wizard files: ${MISSING}"
-    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
-
-exit 0