agentic-sdlc-wizard 1.39.1 → 1.40.1

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.1",
       "author": {
         "name": "Stefan Ayala"
       },

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,18 @@ 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.1] - 2026-04-26
+
+### Added
+
+- **`cleanupPeriodDays: 30` pinned in template settings** (ROADMAP #225). CC 2.1.117 expanded `cleanupPeriodDays` to also cover `~/.claude/tasks/` — the directory where the Tasks system persists in-progress TodoWrite state. With aggressive defaults (some CC versions defaulted to 7 days), SDLC checklists for paused long-running features could be silently pruned. `cli/templates/settings.json` now ships `"cleanupPeriodDays": 30` as a top-level field. `CLAUDE_CODE_SDLC_WIZARD.md` documents the gotcha + override path. New `tests/test-cleanup-period-guidance.sh` (7 tests) asserts template default + wizard rationale don't regress.
+
+## [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

@@ -311,6 +311,14 @@ If you notice Claude Code producing shallow outputs despite `effort: high`, add
 
 **Rollback if issues**: Set `CLAUDE_CODE_ENABLE_TASKS=false` environment variable.
 
+#### Known CC gotcha: `cleanupPeriodDays` and TodoWrite retention (CC 2.1.117+)
+
+CC 2.1.117 expanded the `cleanupPeriodDays` setting to also cover `~/.claude/tasks/` — the directory where the Tasks system persists in-progress TodoWrite state across sessions. If `cleanupPeriodDays` is too low (CC's default has been as aggressive as 7 days in some versions), an SDLC checklist for a paused long-running feature can be silently pruned out from under you.
+
+**Wizard pins a safe default**: `cli/templates/settings.json` ships `"cleanupPeriodDays": 30`. The wizard's SDLC skill makes TodoWrite step 1 of every task, so the floor matters. Recommendation: keep it at **30 or higher** if you ever pause work for more than a week. If a task list disappears mid-cycle, check this setting first.
+
+**To override**: set `cleanupPeriodDays` to a higher number in your project's `.claude/settings.json`. The CLI's smart-merge preserves user overrides on `init --force`.
+
 ### Skill Arguments with $ARGUMENTS (v2.1.19+)
 
 **What changed**: Skills can now accept parameters via `$ARGUMENTS` placeholder.
@@ -2832,7 +2840,7 @@ If deployment fails or post-deploy verification catches issues:
 
 **SDLC.md:**
 ```markdown
-<!-- SDLC Wizard Version: 1.39.1 -->
+<!-- SDLC Wizard Version: 1.40.1 -->
 <!-- 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 +3902,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.1 -->
 <!-- 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/cli/init.js

@@ -78,6 +78,15 @@ function mergeSettings(existingPath, templatePath, force) {
       existing.model = template.model;
     }
 
+    // Merge cleanupPeriodDays (ROADMAP #225): only set the template default when
+    // the user has not chosen a value. NEVER overwrite under --force — retention
+    // policy is a user preference (they may want >30 for long pauses, or <30 for
+    // disk-tight setups). The wizard's job is to provide a safe floor on fresh
+    // installs, not to clobber an explicit choice.
+    if ('cleanupPeriodDays' in template && !('cleanupPeriodDays' in existing)) {
+      existing.cleanupPeriodDays = template.cleanupPeriodDays;
+    }
+
     // Merge env field
     if (template.env) {
       if (!existing.env || typeof existing.env !== 'object' || Array.isArray(existing.env)) {

package/cli/templates/settings.json

@@ -1,4 +1,5 @@
 {
+  "cleanupPeriodDays": 30,
   "hooks": {
     "UserPromptSubmit": [
       {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-wizard",
-  "version": "1.39.1",
+  "version": "1.40.1",
   "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,11 @@ Parse all CHANGELOG entries between the user's installed version and the latest.
 
 ```
 Installed: 1.24.0
-Latest:    1.39.1
+Latest:    1.40.1
 
 What changed:
+- [1.40.1] cleanupPeriodDays: 30 pinned in template — ROADMAP #225. CC 2.1.117 expanded `cleanupPeriodDays` to also cover `~/.claude/tasks/`. Aggressive defaults could prune in-progress TodoWrite checklists for paused long-running features. Wizard now ships a 30-day floor + documented gotcha. 7 quality tests.
+- [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`).