agentic-sdlc-wizard 1.82.0 → 1.84.0

package/skills/setup/SKILL.md

@@ -130,11 +130,7 @@ Default if no response: **A** (dual-maintain). Document the user's choice as a o
 
 **If NO `AGENTS.md` exists**: skip this step silently. Phase (b) of #205 (offer to ALSO generate AGENTS.md alongside CLAUDE.md) is deferred — not in v1.42.0 scope.
 
-**Phase scope honest summary**:
-- Phase (a) — DONE in v1.42.0: detection + decision surfacing only.
-- Phase (b) — deferred: write/symlink AGENTS.md when generating CLAUDE.md fresh.
-- Phase (c) — partial: this step IS the setup-skill update.
-- Phase (d) — deferred: cross-document-consistency drift test.
+**Scope**: phase (a) only — detection + surfacing (v1.42.0). Phases (b) symlink-write, (c) partial (this step), (d) drift test are deferred.
 
 ### Step 5: Generate SDLC.md
 
@@ -228,9 +224,11 @@ Present suggestions and let the user confirm.
 
 ### Step 9.5: Context Window + Mixed-Mode Configuration (Opt-In)
 
-The CLI ships `cli/templates/settings.json` with **no** `model` or `env` pin by default. This preserves Claude Code's built-in model auto-selection. Power users can opt into a pin during setup — `opusplan` for cost-conscious SDLC, or `claude-opus-4-6` for full flagship.
+The CLI ships `cli/templates/settings.json` with **no** `model` or `env` pin by default. This preserves Claude Code's built-in model auto-selection. Power users can opt into a pin during setup — see `AI_SETUP_LANES.md` for the full lane comparison (Setup A: Sonnet 5 + Fable, recommended if pinning at all; Setup B: Opus 4.6 Stability, legacy flagship; Setup C: OpusPlan Hybrid).
 
-**Why this is opt-in (issue #198):** A top-level `"model"` in `settings.json` disables auto-mode for the session. Pinning is only worth it when you want consistent model behavior (opusplan or flagship) rather than per-turn auto-selection.
+**Why this is opt-in (issue #198):** A top-level `"model"` in `settings.json` disables auto-mode for the session. Pinning is only worth it when you want consistent model behavior rather than per-turn auto-selection.
+
+**Check for global `[1m]` model pin (#391):** Read `~/.claude/settings.json`. If `model` contains `[1m]`, warn: global pin forces 1M on every repo; headless surfaces bill against credits after June 15. Offer `[r] Remove / [k] Keep`. If `r`: delete the `model` key.
 
 **Run the complexity heuristic first (roadmap #233):**
 
@@ -246,67 +244,67 @@ The output is JSON: `{ tier: "simple" | "complex", score, signals }`. Use the re
 >
 > How do you want to configure the model for this repo?
 >
-> - **[N] No pin (default):** Auto-mode. CC picks model per turn. Simplest.
-> - **[o] OpusPlan** *(recommended for cost-conscious SDLC):* Pins `model: "opusplan"`. Opus plans (Shift+Tab), Sonnet executes. Both 200K, Max-bundled. No API credit drain (#390).
-> - **[f] Flagship full** *(recommended for complex / high-stakes):* Pins `model: "claude-opus-4-6"`. Opus 4.6 max everywhere. Max-bundled (auto-upgrades to 1M on Max plans).
-> - **[l] Latest** *(opt-in bleeding-edge):* Pins `model: "claude-opus-4-8"`. Effort: always max (#395).
+> - **[N] No pin (default):** Auto-mode. CC picks model per turn. Simplest, no advisor.
+> - **[s] Sonnet 5 + Fable** *(Setup A — recommended if you want a pin):* Pins `model: "sonnet"`, `advisorModel: "fable"`. Native 1M context, no `[1m]` suffix needed. Beats Opus 4.6 on every coding benchmark at ~5x less Max quota per turn. Effort: `high`, escalate to `xhigh` for hard tasks.
+> - **[o] OpusPlan Hybrid** *(Setup C — cost-conscious, still want Opus reasoning):* Pins `model: "opusplan"`. Opus 4.8 plans (Shift+Tab), Sonnet 5 executes. Max-bundled. No API credit drain (#390).
+> - **[b] Opus 4.6 Stability** *(Setup B — legacy flagship, proven consistency for high-stakes/complex repos):* Pins `model: "claude-opus-4-6"`. Opus 4.6 max everywhere. Max-bundled (auto-upgrades to 1M on Max plans).
 >
-> `[N/o/f/l]`
+> `[N/s/o/b]`
 
 **If the user answers `N` (default):** Make no edits to `.claude/settings.json`. Auto-mode stays on. Done.
 
-**If the user answers `o` (opusplan):** Edit `.claude/settings.json` and add:
+**If the user answers `s` (Sonnet 5 + Fable):** Edit `.claude/settings.json` and add:
 
 ```json
 {
-  "model": "opusplan",
-  "advisorModel": "claude-opus-4-6",
+  "model": "sonnet",
+  "advisorModel": "fable",
+  "effortLevel": "high",
   "env": {
-    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-6",
-    "CLAUDE_CODE_EFFORT_LEVEL": "max"
+    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "75"
   }
 }
 ```
 
-Tell the user: "Opus reasons during Plan Mode (Shift+Tab), Sonnet executes. Both Max-bundled at 200K — no API credit drain. The Opus advisor auto-compensates for Sonnet's lighter reasoning at key decision points. Cross-model reviews still run at GPT-5.5 xhigh. Requires CC v2.1.170+ — run `! claude update` if needed."
+Tell the user: "Sonnet 5 + Fable — the wizard's recommended pin (Setup A). Effort defaults to `high`, escalate via `/effort xhigh` for hard tasks. Requires CC v2.1.170+ — run `! claude update` if needed."
 
-**If the user answers `f` (flagship):** Edit `.claude/settings.json` and add:
+**If the user answers `o` (opusplan):** Edit `.claude/settings.json` and add:
 
 ```json
 {
-  "model": "claude-opus-4-6",
-  "advisorModel": "fable",
+  "model": "opusplan",
+  "advisorModel": "claude-opus-4-8",
   "env": {
-    "CLAUDE_CODE_EFFORT_LEVEL": "max",
-    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "30"
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "claude-opus-4-8"
   }
 }
 ```
 
-Tell the user: "Opus 4.6 max everywhere with Fable 5 advisor. Fable auto-consults at key decision points (architecture, complexity, blast-radius). On Max plans, Opus auto-upgrades to 1M context — the autocompact override prevents early compaction at ~76K. Requires CC v2.1.170+ — run `! claude update` if needed."
+Tell the user: "Opus 4.8 plans (Shift+Tab), Sonnet 5 executes — both Max-bundled, no API credit drain (Setup C). Set effort per-session with `/effort` rather than a shell-rc env var. Requires CC v2.1.170+ — run `! claude update` if needed."
 
-**If the user answers `l` (latest):** Edit `.claude/settings.json` and add:
+**If the user answers `b` (Opus 4.6 Stability):** Edit `.claude/settings.json` and add:
 
 ```json
 {
-  "model": "claude-opus-4-8",
+  "model": "claude-opus-4-6",
   "advisorModel": "fable",
   "env": {
-    "CLAUDE_CODE_EFFORT_LEVEL": "max"
+    "CLAUDE_CODE_EFFORT_LEVEL": "max",
+    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "30"
   }
 }
 ```
 
-Tell the user: "Always max effort on all Claude models (#395) with Fable 5 advisor. Fable auto-consults at key decision points. Requires CC v2.1.170+ — run `! claude update` if needed. Escape hatch: change `model` back to `claude-opus-4-6` or remove to fall back to auto-mode."
+Tell the user: "Opus 4.6 max everywhere with Fable advisor — legacy flagship (Setup B), still valid for proven consistency on high-stakes work. `max` is Opus 4.6's own sweet spot (no `xhigh` support), so a persistent env pin is fine here, unlike other models. Requires CC v2.1.170+ — run `! claude update` if needed."
 
 Mention the escape hatch in all four cases:
-- To opt out later: remove the `model` line (and optionally the `env` block) from `.claude/settings.json`, or run `/model` and pick "Default (recommended)".
+- To opt out later: remove the `model` line (and optionally the `env`/`effortLevel` keys) from `.claude/settings.json`, or run `/model` and pick "Default (recommended)".
 - To switch tiers later: edit `.claude/settings.json` and replace the `model` value, or re-run `/setup-wizard` Step 9.5.
-- For CI pipelines with short tasks (flagship only), consider `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=60` — compact early to stay fast.
+- For CI pipelines with short tasks (Setup B only), consider `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=60` — compact early to stay fast.
 
 This is project-scoped and shared with the team via git.
 
-**After writing project settings (for `[o]`, `[f]`, or `[l]`), ask once:**
+**After writing project settings (for `[s]`, `[o]`, or `[b]`), ask once:**
 
 > Also set `advisorModel` in your global `~/.claude/settings.json`?
 > (Applies advisor to ALL your projects. Project-level always overrides.)
@@ -314,10 +312,12 @@ This is project-scoped and shared with the team via git.
 
 Default No. If yes, read `~/.claude/settings.json`, add/update only the `advisorModel` key (do NOT touch other keys), write back. This is the only global settings mutation in setup besides Step 7.7's dead plugin cleanup.
 
-**Note:** Flagship, OpusPlan, and Latest choices include an advisor model that auto-consults at key decision points. Requires CC v2.1.170+ — run `! claude update` from inside a CC session if needed.
+**Note:** Sonnet 5, OpusPlan, and Opus 4.6 Stability choices include an advisor model that auto-consults at key decision points. Requires CC v2.1.170+ — run `! claude update` from inside a CC session if needed.
 
 ### Step 10: Customize Hooks
 
+If `.claude/hooks/` has fewer than 9 files, hooks were never installed — tell the user to run `npx agentic-sdlc-wizard@latest init` first (the wizard doc's hook code blocks are illustrative, not a full template set).
+
 Update `tdd-pretool-check.sh` with the actual source directory (replace generic `/src/` pattern).
 
 ### Step 11: Verify Setup

package/skills/update/SKILL.md

@@ -89,18 +89,20 @@ Extract latest version from the first `## [X.X.X]` line.
 
 ### Step 3: Compare Versions and Show What Changed
 
-Parse CHANGELOG entries between the user's installed version and latest. Present a clear summary:
+**Resolve "latest installable" from npm registry (#405):** Compare the npm registry version (Step 1.5 cache) to the CHANGELOG heading version (Step 2). Use the **lower** of the two as "latest installable" — this prevents showing a version that isn't yet published to npm during the publish window. If CHANGELOG is ahead of npm, note: "v{changelog} is on GitHub but not yet published to npm; showing v{npm} as latest installable."
+
+Parse CHANGELOG entries between the user's installed version and the resolved latest installable. Present a clear summary:
 
 ```
 Installed: 1.42.0
-Latest:    1.82.0
+Latest:    1.84.0
 
 What changed:
+- [1.84.0] Hook enforcement fix: cross-model review gate + TDD RED gate now actually block (#436); model-aware effort docs replace blanket max recommendation.
+- [1.83.0] Model config batch: multi-model hook recommendation (#403), global [1m] pin detection (#391), version race fix (#405), effort config check (#384).
 - [1.82.0] Usage diagnostics: fix /usage row, Reading Usage Signals guide, advisor fallback procedure, Fable effort guidance, autocompact cross-reference.
 - [1.81.0] Native `advisorModel` support: Setup A gets Fable advisor, Setup B gets Opus advisor. Replaces manual subagent spawning. Requires CC v2.1.170+.
 - [1.80.0] Flip default: Opus 4.6 max becomes recommended flagship; Opus 4.8 demoted to opt-in `[l] Latest` tier.
-- [1.79.0] Opus 4.6 Stability tier added as flagship alternative (now graduated to default in 1.80.0).
-- [1.78.0] Opus 4.7 → 4.8 model recommendation (#365) + min CC v2.1.154+.
 - [1.77.0] release-dry-run.yml + cc-version-drift.yml (#350) + /goal SDLC gates (95% + DLC binding).
 - [1.76.0] /goal /sdlc wrapper (#347) + CC v2.1.150 feature adoption + ROADMAP demand-signal gate (4 excise, 4 kill).
 - [1.75.1] release-workflow fix — Node 22 → 24 (ships npm 11.x), dropped flaky `npm install -g` self-upgrade (hit MODULE_NOT_FOUND on v1.75.0 publish). Explicit npm-version guard.
@@ -115,19 +117,15 @@ What changed:
 - [1.61.0] calibration scenarios for #96 Phase 3 PR 2 — `tests/e2e/scenarios/calibration-careful-read.md` (parsePrice with 5 edge-case formats) tests whether self-review catches missed requirements. Score delta between SDLC and naive agents on this scenario is a calibration signal for `lift-proof.sh`
 - [1.60.0] wizard-installation lift-proof harness (#96 Phase 3 PR 1) — `tests/e2e/lift-proof.sh` runs same scenario on bare vs wizard-installed fixture, emits score delta. Closes the "does the wizard work?" question. Honestly zero-API (sim + eval on Max)
 - [1.59.0] evaluator on Max via `claude --print` (#228) — `EVAL_USE_CLI=1` swaps `evaluate.sh`'s per-criterion judge transport from `curl` → API to `claude --print --output-format json`. local-shepherd.sh sets it by default, so the local path is honestly zero-API
-- [1.58.0] ground-truth gate for E2E benchmark (#96 Phase 2) — `tests/e2e/ground-truth.sh` runs `npm test` post-sim; final score capped at 5 if tests fail. Catches "agent followed protocol but produced broken code"
-- [1.57.0] de-coach E2E benchmark prompt (#96 Phase 1) — remove answer-key leakage that saturated benchmark scores at 10/10; new neutral task framing measures organic SDLC behavior
-- [1.56.0] community feature-discovery fetcher (#207) — `tests/e2e/fetch-community.sh` pulls Reddit + HN; pipe to `scan-community.sh` to surface candidate /slash-commands
-- [1.55.0–1.51.0] ROADMAP #231 weekly-update.yml dismantle (Phase 2 → Phase 4): five releases, each deleting a cron-API job in favor of manual local-Max replacements. End state: weekly-update.yml shrunk from ~1670 → 161 lines (-90%), zero API spend, only `check-updates` release detection survives.
-... (older entries omitted — read the full CHANGELOG.md for anything pre-1.51.0)
+... (older entries omitted — read the full CHANGELOG.md for anything pre-1.59.0)
 ```
 
 Read the actual entries from the fetched CHANGELOG; don't paraphrase. The user wants to see exactly what shipped.
 
 **If versions match:** Step 7.7 (global plugin-registration cleanup) is independent of wizard file versions — it must run even when the user is up-to-date. The `check-only` flag still gates whether cleanup is *applied*:
 
-- **Without `check-only`**: Run Step 7.7 in normal mode (detect, prompt, apply) before stopping. Then say "You're up to date! (version X.X.X)" and stop. Do not run Steps 4–10; only Step 7.7 fires on match.
-- **With `check-only`**: Run Step 7.7 in detection-only mode — report any dead plugin registrations, but do NOT prompt and do NOT mutate `~/.claude/settings.json`. Then say "You're up to date! (version X.X.X)" and stop.
+- **Without `check-only`**: Run Step 7.7 and Step 7.9 in normal mode (detect, prompt, apply) before stopping. Then say "You're up to date! (version X.X.X)" and stop. Do not run Steps 4–10; only Steps 7.7 and 7.9 fire on match.
+- **With `check-only`**: Run Step 7.7 and Step 7.9 in detection-only mode — report findings but do NOT prompt and do NOT mutate settings. Then say "You're up to date! (version X.X.X)" and stop.
 
 **If user passed `check-only` and versions don't match:** Stop after showing what changed. Do not apply anything.
 
@@ -174,7 +172,7 @@ Check user's `.claude/settings.json`:
 1. **`model: "opus[1m]"` AND `env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE: "30"`** — likely the old wizard-installed pair, not an intentional choice. Ask:
    > Your `.claude/settings.json` pins `model: "opus[1m]"` with `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=30`. This pair was the wizard default in 1.31.0–1.33.x, but it disables Claude Code's auto-mode (issue #198).
    > - **Remove the pin** (recommended) — keeps auto-mode enabled
-   > - **Keep the pin** — guaranteed Opus 4.6 max + 1M, OK with no auto-selection
+   > - **Keep the pin** — guaranteed 1M on whichever Opus `opus[1m]` currently resolves to (now Opus 4.8, not 4.6 — swap to `claude-opus-4-6` if you want 4.6 specifically), OK with no auto-selection
    > Remove, keep, or decide later? `[r/k/l]`
 
 2. **Only one of the two fields matches** — treat as intentional customization. Do not prompt.
@@ -234,7 +232,16 @@ If `cli/init.js` later adds wizard marketplace names, append verbatim.
 
 If CC < v2.1.170: show "Run `! claude update` to upgrade" and skip. If `.claude/settings.json` already has `advisorModel` or no `model` pin: skip.
 
-If `model` pin exists but no `advisorModel`, suggest: `claude-opus-4-6`/`claude-opus-4-8` → `advisorModel: "fable"`, `opusplan` → `advisorModel: "claude-opus-4-6"`. Ask `[a/S]`, write only `advisorModel` if accepted.
+If `model` pin exists but no `advisorModel`, suggest per driver: `sonnet`/`claude-opus-4-6`/`claude-opus-4-8` → `advisorModel: "fable"`, `opusplan` → `advisorModel: "claude-opus-4-8"`. Ask `[a/S]`, write only `advisorModel` if accepted.
+
+### Step 7.9: Effort Configuration Check (#384)
+
+Runs regardless of version match (like Step 7.7). `check-only`: report only. Effort is model-aware (v1.84.0+, see `AI_SETUP_LANES.md`), not blanket `max` — this step detects the anti-pattern, doesn't push everyone toward `max`.
+
+1. Read `model` from the settings cascade to find the driver. No pin / `sonnet` / `opusplan` = Sonnet 5; `claude-opus-4-6` = Opus 4.6; `claude-opus-4-8` = Opus 4.8.
+2. **Opus 4.6 driver:** `CLAUDE_CODE_EFFORT_LEVEL=max` in the project's `env` block → pass (silent; `max` is 4.6's actual sweet spot, no `xhigh`). If only `effortLevel: "max"` is set in `settings.json` (not the env var) → warn: CC ignores session-only `max` in settings, only the env var actually persists it — suggest moving it into the `env` block instead. Unset entirely or below `max` → suggest `/effort max` + that env entry.
+3. **Sonnet 5 or Opus 4.8 driver:** `CLAUDE_CODE_EFFORT_LEVEL=max` set anywhere → warn. This is the exact incident that motivated this check: a stale `max` env var silently overrides `/effort xhigh` after switching off Opus 4.6. Recommend removing it and using `/effort` per-session instead. Unset → pass (silent).
+4. Never suggest a shell-rc (`.zshrc`/`.bashrc`) export — only the project's `env` block, and only for Opus 4.6.
 
 ### Step 8: Apply Selected Changes