agentic-sdlc-wizard 1.81.0 → 1.83.0

package/.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
       "name": "sdlc-wizard",
       "source": ".",
       "description": "SDLC enforcement for AI agents — TDD, planning, self-review, CI shepherd",
-      "version": "1.81.0",
+      "version": "1.83.0",
       "author": {
         "name": "Stefan Ayala"
       },

package/.claude-plugin/plugin.json

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

package/AI_SETUP_LANES.md

@@ -15,6 +15,8 @@ This is **guidance, not a hard rule**. Maintainer override is always allowed.
 
 Quality-first lane. Fable 5 advises automatically at key decision points (architecture, complexity, blast-radius) via native `advisorModel` (v2.1.170+), Opus 4.6 max implements (stable, Max-bundled), GPT-5.5 xhigh reviews (cross-family, free on ChatGPT sub, catches blind spots Fable can't see in its own work). Escalate to Fable review for the ~5% of PRs where stakes justify it.
 
+**Effort levels:** Opus driver at `max` (standing default). Fable advisor runs at its own effort level server-side. If switching driver to Fable temporarily (fallback), use `/effort high` — Fable `high` already exceeds prior models at `max`. Unset `CLAUDE_CODE_EFFORT_LEVEL` env var if it forces `max`.
+
 ## Setup B — Claude Saver (OpusPlan)
 
 | Role | Model |
@@ -105,6 +107,25 @@ The `!` prefix runs shell commands inside your CC session — no need to exit an
 
 Fable 5 as advisor also requires Fable 5 access for your organization/plan (free on Max through June 22, 2026).
 
+## When the Advisor Is Unavailable
+
+If the advisor returns "Advisor unavailable," the server-side harness failed to initialize. No in-session action (`/model`, `/clear`) can recover it.
+
+**Step 1 — restart the session.** Exit and run `claude` (not `--resume`). A fresh process re-initializes the server handshake. This resolves most advisor failures.
+
+**Step 2 — if the API incident persists:**
+
+- `/model fable` + `/effort high` for the planning phase, then `/model claude-opus-4-6` for implementation. Interactive — stays on your Max subscription.
+- Or proceed with Opus only and let the Codex xhigh PR gate catch issues.
+
+**Last resort (scripted/CI only):**
+
+- `claude --model fable --effort high -p "$(cat <file>)"` — headless mode bills API credits, not your Max subscription.
+
+Check [status.claude.com](https://status.claude.com) if the advisor fails across multiple fresh sessions.
+
+Whichever path you use, the cross-model PR review gate still applies.
+
 ## Credit-Spend Warning
 
 Setups A and B use Opus 4.6 max for at least the planner — that's the expensive half. On Max-plan subscriptions, **Premium can burn the 5-hour cap faster than Saver** because Opus 4.6 max drives implementation too. If you're hitting the cap mid-session:
@@ -117,6 +138,10 @@ Setups A and B use Opus 4.6 max for at least the planner — that's the expensiv
 
 The reviewer (GPT-5.5 xhigh) is billed against your OpenAI account, separately. Watch both bills.
 
+## Autocompact Thresholds
+
+For recommended `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` values per context window and task shape, see [CLAUDE_CODE_SDLC_WIZARD.md → Autocompact Tuning](CLAUDE_CODE_SDLC_WIZARD.md#autocompact-tuning).
+
 ## How Billing Works — 1M Context, Max Plan, and the June 15 Split
 
 A common question: **"does the `[1m]` model alias get billed differently? Does it pull from my Max plan or from API credits?"**

package/CHANGELOG.md

@@ -4,6 +4,39 @@ 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.83.0] - 2026-06-11
+
+### Fixed
+- **#403**: Hook lists multiple wizard-blessed models (claude-opus-4-6, opusplan, fable) instead of hardcoded single-model nudge
+- **#391**: Setup Step 9.5 detects global `[1m]` model pin and warns about billing implications
+- **#405**: Update Step 3 uses `min(npm, CHANGELOG)` as "latest installable" — prevents version race during publish window
+- **#384**: Update Step 7.9 checks effort configuration regardless of version match
+
+### Why
+Model config batch — first trial of the confidence ramp pattern (Opus research → Fable batch review → 95% → TDD → Codex safety check). All 4 issues reached 95% confidence before implementation.
+
+## [1.82.0] - 2026-06-11
+
+### Added
+
+- **"Reading Usage Signals" subsection** in Token Efficiency section. Maps community-observed session signals (subagent-heavy, >150K context, 8+ hour sessions) to SDLC actions per setup lane. Marked as community-observed, not official CC docs.
+
+- **Advisor fallback procedure** in AI_SETUP_LANES.md. Escalation ladder: restart session → Fable driver fallback → `-p` last resort (with billing caveat). Documented after advisor was unavailable for a full session during API incident (2026-06-11).
+
+- **Fable effort guidance** in Setup A description. Opus stays at `max`; Fable at `high` (exceeds prior models at `max`). Unset `CLAUDE_CODE_EFFORT_LEVEL` env var if switching driver to Fable temporarily.
+
+- **Autocompact Thresholds cross-reference** in AI_SETUP_LANES.md. Numbers-free pointer to wizard doc to prevent dual-source drift.
+
+### Fixed
+
+- **Stale `/usage` row** in Monitor Costs table. Was "Session total: USD, API time, code changes" — now accurately describes plan usage limits and per-category breakdown (skill, subagent, plugin, MCP server). Added `/status` row (settings panel) to prevent future confusion.
+
+- **`/usage` mention in SKILL.md** Context Management section. Folded into existing auto-compact bullet within 20K char budget.
+
+### Why
+
+- Token-burn spike (1.36M costly tokens vs ~86K median) in session 98d6c7b0 surfaced that the wizard's usage guidance was stale and didn't help diagnose the cause. The Monitor Costs table described `/usage` incorrectly, and no wizard prose mapped usage signals to SDLC actions. The advisor fallback procedure is a direct lesson from the same session where the Fable advisor was unavailable for the entire duration.
+
 ## [1.81.0] - 2026-06-10
 
 ### Changed

package/CLAUDE_CODE_SDLC_WIZARD.md

@@ -3041,7 +3041,7 @@ If deployment fails or post-deploy verification catches issues:
 
 **SDLC.md:**
 ```markdown
-<!-- SDLC Wizard Version: 1.81.0 -->
+<!-- SDLC Wizard Version: 1.83.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] -->
@@ -3691,10 +3691,21 @@ Practical techniques to reduce token consumption without sacrificing quality.
 
 | Tool | What It Shows | When to Use |
 |------|---------------|-------------|
-| `/usage` | Session total: USD, API time, code changes (aliases: `/cost`, `/stats`) | After a session to review spend |
+| `/usage` | Session cost, plan usage limits, and per-category breakdown (skill, subagent, plugin, MCP server). Aliases: `/cost`, `/stats` | After heavy subagent work, before/after workflow runs, when approaching rate limits |
+| `/status` | Settings panel — version, model, account, connectivity | Confirm setup before starting work |
 | `/context` | What's consuming context window space | When hitting context limits |
 | Status line | Real-time `cost.total_cost_usd` + token counts | Continuous monitoring |
 
+### Reading Usage Signals
+
+These signals are community-observed behavior on paid plans (Max/Team) — not in official CC docs. They are independent dimensions, not a single breakdown. A single session can contribute to all three. Run `/usage` to see the per-category breakdown.
+
+| Signal | What It Means | SDLC Action |
+|--------|---------------|-------------|
+| **Subagent-heavy** | Each subagent runs its own context. The advisor is a separate server-side consultation (full transcript forwarded, different token profile). Explore agents, full Agent delegates, and workflow agents each spawn separate contexts. | Expected in Setup A (Fable advisor fires per-decision). If unexpectedly high: use `subagent_type: "Explore"` for search (lighter), reserve full agents for implementation. |
+| **>150K context** | Sessions staying large between compactions. | **Context-window dependent.** On 1M (Setup A): >150K is expected at 30% compact threshold — the real question is whether the task needed 1M headroom. On 200K (Setup B/C): lower `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` toward 75%. `/compact` between planning and implementation. |
+| **8+ hour sessions** | Long-running sessions accumulate stale context. | `/clear` between unrelated tasks. Split multi-feature work into separate sessions. After committing a PR, start fresh. Background `/loop` sessions count toward this — audit which are still needed. |
+
 ### Reduce Consumption
 
 | Technique | Savings | How |

package/hooks/model-effort-check.sh

@@ -11,7 +11,8 @@
 #
 # Non-blocking: always exits 0.
 
-RECOMMENDED_MODEL="claude-opus-4-6"
+# Multiple wizard-blessed models — don't nudge to a single one (#403)
+RECOMMENDED_MODELS="claude-opus-4-6, opusplan, or fable (run: /model)"
 
 HOOK_DIR="${BASH_SOURCE[0]%/*}"
 [ "$HOOK_DIR" = "${BASH_SOURCE[0]}" ] && HOOK_DIR="."
@@ -63,7 +64,7 @@ echo ""
 echo " Run: /effort max"
 echo " Persist: set CLAUDE_CODE_EFFORT_LEVEL=max in settings env block"
 echo ""
-echo " recommended model: $RECOMMENDED_MODEL (run: /model $RECOMMENDED_MODEL)"
+echo " recommended models: $RECOMMENDED_MODELS"
 echo "=============================================================================="
 
 exit 0

package/package.json

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

package/skills/sdlc/SKILL.md

@@ -267,7 +267,7 @@ Don't fix only the symptom. Add a gate so it can't happen again. Example: PR #14
 
 - `/compact` between planning and implementation (plan preserved in summary)
 - `/clear` between unrelated tasks; after 2+ failed corrections (context polluted)
-- Auto-compact fires at ~95% capacity
+- Auto-compact fires at ~95%; `/usage` shows what's driving token spend
 - After committing a PR, `/clear` before next feature
 - `--bare` mode (v2.1.81+) skips ALL hooks/skills/LSP/plugins. Scripted headless only — never normal development.
 - Custom subagents (`.claude/agents/`) run autonomously and return results. Skills guide behavior; agents do work. Use for parallel tasks or fresh context. Examples: `sdlc-reviewer`, `ci-debug`, `test-writer`.

package/skills/setup/SKILL.md

@@ -232,6 +232,8 @@ The CLI ships `cli/templates/settings.json` with **no** `model` or `env` pin by
 
 **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.
 
+**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):**
 
 ```bash

package/skills/update/SKILL.md

@@ -89,13 +89,17 @@ 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.81.0
+Latest:    1.83.0
 
 What changed:
+- [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).
@@ -125,8 +129,8 @@ Read the actual entries from the fetched CHANGELOG; don't paraphrase. The user w
 
 **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.
 
@@ -235,6 +239,15 @@ If CC < v2.1.170: show "Run `! claude update` to upgrade" and skip. If `.claude/
 
 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.
 
+### Step 7.9: Effort Configuration Check (#384)
+
+Runs regardless of version match (like Step 7.7). In `check-only` mode: report only, no mutations.
+
+1. Check `CLAUDE_CODE_EFFORT_LEVEL` env var. If set to `max`: **pass** (silent — this is the correct persistence path).
+2. If env var is unset, check `effortLevel` in settings cascade (`.claude/settings.local.json` → `.claude/settings.json` → `~/.claude/settings.json`).
+3. If `effortLevel` is `max` but `CLAUDE_CODE_EFFORT_LEVEL` env var is unset: warn that CC ignores session-only max in settings — only the env var persists it. Suggest adding to the `env` block in `.claude/settings.json`.
+4. If effort is unset or below `max`: warn "SDLC requires max effort" and suggest `/effort max` + env var persistence.
+
 ### Step 8: Apply Selected Changes
 
 For each approved file: Edit (existing) or Write (MISSING). For settings.json, apply the merge from Step 7.