agentic-sdlc-wizard 1.39.1 → 1.40.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.39.1",
+      "version": "1.40.0",
       "author": {
         "name": "Stefan Ayala"
       },

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,12 @@ 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.40.0] - 2026-04-25
+
+### Added
+
+- **CLI version detection in /update-wizard** (ROADMAP #232). New Step 1.5 detects the locally installed `agentic-sdlc-wizard` CLI version (via `npm ls -g` for global installs and `~/.npm/_npx` cache inspection for npx users), compares to the npm registry latest at `registry.npmjs.org/agentic-sdlc-wizard/latest`, and surfaces a one-shot `npx -y agentic-sdlc-wizard@latest init --force` upgrade BEFORE running drift detection or per-file updates. Closes the gap where `/update-wizard` patched in-session project files but the user's stale npx cache kept running an old CLI on `init`/`check`/`complexity` invocations. Mirrors `claude update` UX (one-shot CLI + skill sync). Honors the `check-only` flag in report-only mode (no auto-upgrade). Graceful fallback when the CLI is undetectable (custom install, offline). New `tests/test-update-skill-cli-version.sh` (8 quality tests) covers step structure, both detection paths, the registry endpoint, the upgrade command, ordering before per-file plan, `check-only` precedence, fallback wording, and the changelog entry itself.
+
 ## [1.39.1] - 2026-04-25
 
 ### Fixed

package/CLAUDE_CODE_SDLC_WIZARD.md

@@ -2832,7 +2832,7 @@ If deployment fails or post-deploy verification catches issues:
 
 **SDLC.md:**
 ```markdown
-<!-- SDLC Wizard Version: 1.39.1 -->
+<!-- SDLC Wizard Version: 1.40.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] -->
@@ -3894,7 +3894,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.39.1 -->
+<!-- SDLC Wizard Version: 1.40.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-wizard",
-  "version": "1.39.1",
+  "version": "1.40.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/update/SKILL.md

@@ -31,6 +31,91 @@ If no version comment exists, treat as `0.0.0` (first-time setup — suggest run
 
 Also note the completed steps from `<!-- Completed Steps: ... -->`.
 
+### Step 1.5: Check CLI Version (ROADMAP #232)
+
+The wizard files in the user's project (skills, hooks, settings.json) are one half of the install. The other half is the **npm CLI** (`agentic-sdlc-wizard`) — the binary that powers `npx agentic-sdlc-wizard init`, `check`, and `complexity`. If the user ran `npx agentic-sdlc-wizard init` months ago, their npx cache (or global install) can be stuck on an old version even after `/update-wizard` patches the project files in-session. This step closes that gap: detect the locally installed CLI version, compare to the npm registry latest, and surface a one-shot upgrade BEFORE running drift detection or per-file updates.
+
+**Detection — try both paths, in order:**
+
+1. **Global install** (rare but possible): `npm ls -g agentic-sdlc-wizard --json --depth=0 2>/dev/null | jq -r '.dependencies["agentic-sdlc-wizard"].version // empty'` — emits the version if globally installed, empty otherwise.
+
+2. **npx cache** (the common case): find every `package.json` in npx's cache layout, extract `.version`, then pick the largest by semver. Do NOT use `sort -u | tail -1` — that's lexicographic and treats `1.9.0 > 1.10.0`. Use Node's built-in semver-aware compare:
+
+   ```bash
+   find ~/.npm/_npx -maxdepth 4 -name 'package.json' -path '*agentic-sdlc-wizard*' 2>/dev/null \
+     | xargs -I{} jq -r '.version' {} 2>/dev/null \
+     | node -e "
+       let max = '';
+       require('readline').createInterface({input: process.stdin}).on('line', v => {
+         if (!v) return;
+         if (!max || cmp(v, max) > 0) max = v;
+       }).on('close', () => process.stdout.write(max));
+       function cmp(a, b) {
+         const [ab, ap] = a.split('-'), [bb, bp] = b.split('-');
+         const an = ab.split('.').map(Number), bn = bb.split('.').map(Number);
+         for (let i = 0; i < 3; i++) if (an[i] !== bn[i]) return an[i] - bn[i];
+         if (ap && !bp) return -1; if (!ap && bp) return 1;
+         if (ap && bp) return ap < bp ? -1 : ap > bp ? 1 : 0;
+         return 0;
+       }
+     "
+   ```
+
+   This reads each found version on its own line, compares pairwise with semver semantics (numeric major.minor.patch, plus prerelease tags ordered as `1.40.0-beta.1 < 1.40.0`), and prints the maximum. Empty input prints empty.
+
+If both paths return empty, the user may be running from a custom install or has never used `npx`. Treat as **undetectable** — note it in your update report but do not block the rest of the flow. Skip the CLI bump prompt, continue to Step 2.
+
+**Registry comparison:**
+
+```bash
+curl -fsS "https://registry.npmjs.org/agentic-sdlc-wizard/latest" | jq -r '.version'
+```
+
+This is the same endpoint the registry serves; the response is a single JSON object with `version` set to the published latest tag. Cache the result (it's also used in Step 3 for the wizard version comparison).
+
+**Compare with semver-aware logic** — `sort -V` does NOT correctly order prereleases (it places `1.40.0-beta.1` *after* `1.40.0`, but semver requires the opposite). Use the same Node `cmp()` helper from the npx-cache step:
+
+```bash
+node -e "
+  const a = process.argv[1], b = process.argv[2];
+  function cmp(a, b) { /* same body as above */ }
+  process.exit(cmp(a, b) < 0 ? 0 : cmp(a, b) > 0 ? 1 : 2);
+" "$INSTALLED" "$LATEST"
+# Exit 0 = installed < latest (behind); 1 = installed > latest; 2 = equal
+```
+
+**Surface based on the result:**
+
+- `installed == latest` → silent, continue to Step 2.
+- `installed < latest` → surface the gap with the upgrade options below.
+- `installed > latest` (rare — pre-release or local dev install) → silent, continue.
+
+**Upgrade options when behind:** be honest about what each does. Recommend the safer path by default.
+
+  > Your locally installed `agentic-sdlc-wizard` CLI is at **{installed}**, but npm has **{latest}**. The in-session `/update-wizard` will refresh this project's files via Step 6's per-file plan, but your `npx` cache will keep the old CLI on disk for `npx agentic-sdlc-wizard check`/`init`/`complexity` calls.
+  >
+  > Pick one:
+  >
+  > **A. Refresh just the CLI cache (recommended).** Doesn't touch your project files. Then `/update-wizard`'s per-file plan handles the rest with diffs:
+  > ```bash
+  > npx -y agentic-sdlc-wizard@latest --version
+  > ```
+  >
+  > **B. One-shot CLI + project re-init.** Refreshes the CLI AND overwrites *non-settings* managed files (skills, hooks, templates) with the latest versions. `settings.json` is smart-merged (custom hooks + permissions preserved); other managed files are NOT smart-merged — local edits to them are lost unless committed to git or backed up. Use this if you don't have local skill/hook customizations:
+  > ```bash
+  > npx -y agentic-sdlc-wizard@latest init --force
+  > ```
+  >
+  > **C. Skip the CLI bump entirely.** Keep the stale CLI; this session's file updates apply but `npx agentic-sdlc-wizard check` will keep using the old drift logic.
+  >
+  > Pick A, B, or C: `[A/B/C]`
+
+  If A: prompt the user to run the one-liner in their shell, then re-invoke `/update-wizard`. If B: same, with the warning about non-settings overwrite. If C: log the choice and continue with in-session file updates only. Default (no response) → A.
+
+**`check-only` precedence:** if the user passed `check-only`, Step 1.5 runs in report-only mode — print the gap if found, but do NOT prompt and do NOT run `init --force`. The check-only contract is "tell me what's drifted, don't change anything," and that supersedes the CLI bump path.
+
+**Why this lives at Step 1.5, not later:** subsequent steps shell out to `npx agentic-sdlc-wizard check` (Step 4) and rely on the CLI's drift heuristics. If the CLI is stale, Step 4 reports based on the OLD definition of "managed files" and may miss new templates entirely. Detecting + surfacing CLI staleness up front lets the user choose whether to refresh first.
+
 ### Step 2: Fetch Latest CHANGELOG
 
 Use WebFetch to fetch the CHANGELOG:
@@ -46,9 +131,10 @@ Parse all CHANGELOG entries between the user's installed version and the latest.
 
 ```
 Installed: 1.24.0
-Latest:    1.39.1
+Latest:    1.40.0
 
 What changed:
+- [1.40.0] CLI version detection in /update-wizard — ROADMAP #232. New Step 1.5 detects locally installed `agentic-sdlc-wizard` CLI version (npm ls + npx cache inspection, both with semver-aware ordering), compares to `registry.npmjs.org/agentic-sdlc-wizard/latest`, and surfaces a 3-way upgrade choice BEFORE drift detection: A) refresh CLI cache only (default, safest), B) `init --force` re-init with explicit non-settings overwrite warning, C) skip. Closes the gap where in-session file updates landed but the user's stale npx cache kept running an old CLI. Mirrors `claude update` UX. 8 quality tests, mutation-verified.
 - [1.39.1] Step 7.7 hoist — dead-plugin cleanup now runs even when wizard versions match. Previously `/update-wizard` exited at "you're up to date" before reaching Step 7.7, so users on the latest wizard with a stale `~/.claude/settings.json` plugin registration were never offered cleanup. New `tests/test-update-skill-step-7-7.sh` (8 quality tests) guards the ordering.
 - [1.39.0] Community feature-discovery scanner — ROADMAP #207. `tests/e2e/scan-community.sh` extracts unknown `/slash-command` mentions from transcript text (Reddit / HN / Discord exports), dedupes against `tests/e2e/known-slash-commands.txt` allowlist, emits JSON digest of candidates with count + sample. Replaces the deleted CI scan-community job (per #231 Phase 3) with a maintainer-runnable offline scan. 14 quality tests.
 - [1.38.0] Mixed-mode tier (Sonnet 4.6 coder + Opus 4.7 reviewer) for simple repos — ROADMAP #233. New `cli/lib/repo-complexity.js` heuristic + `npx agentic-sdlc-wizard complexity .` CLI command. Setup Step 9.5 expanded from binary y/N to 3-way (no-pin / mixed / flagship). Cross-model review always stays at flagship regardless of coder pin. Reconciles with #198: mixed-mode is opt-in per-project; no-pin remains the default. Plus ROADMAP #224 prompt-hook-fires-once instrumentation (opt-in `SDLC_HOOK_FIRE_LOG`).