agentic-sdlc-wizard 1.43.0 → 1.44.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.43.0",
+      "version": "1.44.0",
       "author": {
         "name": "Stefan Ayala"
       },

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,25 @@ 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.44.0] - 2026-04-27
+
+### Fixed
+
+- **Install-path & cache hygiene** — closes #254 (P1+P2), #239, #238 filed by consumer codeguesser after upgrading 1.32.0 → 1.42.1.
+  - **#254 Bug 1 (P1)**: `cli/init.js` FILES list now ships `hooks/_find-sdlc-root.sh`. The helper is sourced by all 5 wizard hooks and provides `find_sdlc_root` + `dedupe_plugin_or_project`, but `npx ... init --force` previously didn't copy it. Result on every consumer: stderr noise (`_find-sdlc-root.sh: No such file or directory`, `dedupe_plugin_or_project: command not found`) and the SDLC walk-up logic (#171), silent-exit-for-non-SDLC-dirs (#173), and plugin/project dedupe were all silently dead.
+  - **#254 Bug 2 (P2)**: `init --force` now invalidates `~/.cache/sdlc-wizard/latest-version` (or `$SDLC_WIZARD_CACHE_DIR/latest-version` when overridden). Previously the cache held the pre-upgrade "latest" for up to 24h, producing reverse staleness nudges like `update available 1.42.1 → 1.41.1`. Console now prints a `BUST` line so the cache eviction is visible.
+  - **#254 Bug 2 / #239 (semver-direction)**: `instructions-loaded-check.sh` introduces `semver_lt` for numeric major/minor/patch comparison. Nudge gate switched from `LATEST_VERSION != INSTALLED_VERSION` (which fired on equality AND reverse direction) to `semver_lt INSTALLED LATEST` — so the nudge only fires when an actual upgrade is available. Cache reads gain a sanity check: cached "latest" must be >= installed, otherwise force a refetch.
+  - **#239 (npm failure surface)**: When `npm view` fails (e.g. EPERM from root-owned `~/.npm/_cacache/`) AND no usable cache exists, the hook now prints `npm view failed — version check unavailable (run 'npm view agentic-sdlc-wizard version' to debug)`. Previously the version-check block produced no output at all and the user had no signal that the staleness nudge was broken.
+  - **#238 (dual-channel ack sentinel)**: The "CLI skills + Claude plugin both present" warning gains an opt-in silence mechanism. Once the user runs `mkdir -p $DUAL_CACHE_DIR && touch $DUAL_ACK_FILE` (the exact command is printed inside the nudge), the warning stops firing. Sentinel lives at `$SDLC_WIZARD_CACHE_DIR/dual-channel-acknowledged` (defaults to `~/.cache/sdlc-wizard/dual-channel-acknowledged`). Removes the every-session noise that was training users to ignore all hook output.
+- 8 new tests across `tests/test-cli.sh` (75 total, +3 for #254) and `tests/test-hooks.sh` (134 total, +5 for the four bugs + Codex round-1 cache-dir-absent regression test). Codex CERTIFIED 10/10 round 2.
+
+### Files
+
+- `cli/init.js` — `FILES` list adds `_find-sdlc-root.sh`; new `invalidateVersionCache()` helper; `--force` path calls bust + logs `BUST` line
+- `hooks/instructions-loaded-check.sh` — new `semver_lt()`; cache sanity check; npm-fail surface; semver-direction nudge gate; dual-channel ack sentinel
+- `tests/test-cli.sh` — file-count test bumped 11→12; 3 new tests
+- `tests/test-hooks.sh` — 5 new tests covering all 4 bugs + Codex cache-dir-absent regression
+
 ## [1.43.0] - 2026-04-27
 
 ### Added

package/CLAUDE_CODE_SDLC_WIZARD.md

@@ -2918,7 +2918,7 @@ If deployment fails or post-deploy verification catches issues:
 
 **SDLC.md:**
 ```markdown
-<!-- SDLC Wizard Version: 1.43.0 -->
+<!-- SDLC Wizard Version: 1.44.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] -->
@@ -3983,7 +3983,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.43.0 -->
+<!-- SDLC Wizard Version: 1.44.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/cli/init.js

@@ -25,6 +25,10 @@ const FILES = [
   { src: 'hooks/instructions-loaded-check.sh', dest: '.claude/hooks/instructions-loaded-check.sh', executable: true, base: REPO_ROOT },
   { src: 'hooks/model-effort-check.sh', dest: '.claude/hooks/model-effort-check.sh', executable: true, base: REPO_ROOT },
   { src: 'hooks/precompact-seam-check.sh', dest: '.claude/hooks/precompact-seam-check.sh', executable: true, base: REPO_ROOT },
+  // #254 Bug 1: shared helper sourced by all hooks above. Must ship — without
+  // it, hooks emit "_find-sdlc-root.sh: No such file or directory" + the
+  // SDLC root walk-up logic is silently dead.
+  { src: 'hooks/_find-sdlc-root.sh', dest: '.claude/hooks/_find-sdlc-root.sh', 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 },
@@ -235,6 +239,21 @@ function printOps(ops) {
   }
 }
 
+// #254 Bug 2: clear the version cache on `init --force` so the
+// instructions-loaded hook re-fetches latest from npm post-upgrade. Without
+// this, the cache holds the pre-upgrade "latest" for up to 24h and the hook
+// prints reverse nudges like "1.42.1 → 1.41.1".
+function invalidateVersionCache({ dryRun }) {
+  const cacheDir = process.env.SDLC_WIZARD_CACHE_DIR
+    || path.join(os.homedir(), '.cache', 'sdlc-wizard');
+  const cacheFile = path.join(cacheDir, 'latest-version');
+  if (!fs.existsSync(cacheFile)) return false;
+  if (!dryRun) {
+    try { fs.rmSync(cacheFile, { force: true }); } catch (_) { /* best-effort */ }
+  }
+  return true;
+}
+
 function init(targetDir, { force = false, dryRun = false } = {}) {
   if (!dryRun && !force) {
     const pluginPaths = detectPluginInstall();
@@ -291,6 +310,13 @@ function init(targetDir, { force = false, dryRun = false } = {}) {
     console.log(`  ${GREEN}APPEND${RESET}  .gitignore (${gitignoreAdds.join(', ')})`);
   }
 
+  // #254 Bug 2: bust the latest-version cache after an upgrade so the
+  // staleness nudge re-fetches a fresh value from npm. Only on --force,
+  // since that's the upgrade path.
+  if (force && invalidateVersionCache({ dryRun: false })) {
+    console.log(`  ${CYAN}BUST${RESET}    version cache (${path.join(process.env.SDLC_WIZARD_CACHE_DIR || path.join(os.homedir(), '.cache', 'sdlc-wizard'), 'latest-version')})`);
+  }
+
   console.log(`
 ${GREEN}SDLC Wizard installed successfully!${RESET}
 

package/hooks/instructions-loaded-check.sh

@@ -44,14 +44,38 @@ fi
 SDLC_MD="$PROJECT_DIR/SDLC.md"
 # Strict x.y.z semver — rejects whitespace, "junk", "1.alpha.0", etc.
 SEMVER_RE='^[0-9]+\.[0-9]+\.[0-9]+$'
+
+# semver_lt A B → exit 0 if A < B, exit 1 otherwise. Both args validated semver.
+# Used so a stale-but-fresh cache from before an upgrade ("latest" < installed)
+# doesn't fire a reverse-direction nudge (#254 Bug 2 / #239).
+semver_lt() {
+    local a_major a_minor a_patch b_major b_minor b_patch
+    a_major=$(echo "$1" | awk -F. '{print $1+0}')
+    a_minor=$(echo "$1" | awk -F. '{print $2+0}')
+    a_patch=$(echo "$1" | awk -F. '{print $3+0}')
+    b_major=$(echo "$2" | awk -F. '{print $1+0}')
+    b_minor=$(echo "$2" | awk -F. '{print $2+0}')
+    b_patch=$(echo "$2" | awk -F. '{print $3+0}')
+    if [ "$a_major" -lt "$b_major" ]; then return 0; fi
+    if [ "$a_major" -gt "$b_major" ]; then return 1; fi
+    if [ "$a_minor" -lt "$b_minor" ]; then return 0; fi
+    if [ "$a_minor" -gt "$b_minor" ]; then return 1; fi
+    if [ "$a_patch" -lt "$b_patch" ]; then return 0; fi
+    return 1
+}
+
 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" ] && [[ "$INSTALLED_VERSION" =~ $SEMVER_RE ]]; then
         VERSION_CACHE_DIR="${SDLC_WIZARD_CACHE_DIR:-$HOME/.cache/sdlc-wizard}"
         VERSION_CACHE_FILE="$VERSION_CACHE_DIR/latest-version"
         LATEST_VERSION=""
+        NPM_FAILED=0
 
-        # Use cache if present, <24h old, and contents are valid semver
+        # Use cache if present, <24h old, contents are valid semver, AND cached
+        # version is not strictly older than installed (#239: post-upgrade
+        # cache poison sanity check — if cache says "latest=1.41.1" but
+        # installed=1.43.0, the cache is poisoned, force a refetch).
         if [ -f "$VERSION_CACHE_FILE" ]; then
             if stat -f %m "$VERSION_CACHE_FILE" > /dev/null 2>&1; then
                 CACHE_MTIME=$(stat -f %m "$VERSION_CACHE_FILE")
@@ -62,22 +86,37 @@ if [ -f "$SDLC_MD" ]; then
             if [ "$CACHE_AGE" -lt 86400 ]; then
                 CACHE_CONTENT=$(cat "$VERSION_CACHE_FILE" 2>/dev/null) || CACHE_CONTENT=""
                 if [[ "$CACHE_CONTENT" =~ $SEMVER_RE ]]; then
-                    LATEST_VERSION="$CACHE_CONTENT"
+                    # Sanity check: cached "latest" must be >= installed.
+                    if ! semver_lt "$CACHE_CONTENT" "$INSTALLED_VERSION"; then
+                        LATEST_VERSION="$CACHE_CONTENT"
+                    fi
                 fi
             fi
         fi
 
-        # Fetch from npm if cache miss / stale / malformed
+        # Fetch from npm if cache miss / stale / malformed / poisoned
         if [ -z "$LATEST_VERSION" ] && command -v npm > /dev/null 2>&1; then
-            NPM_RESULT=$(npm view agentic-sdlc-wizard version 2>/dev/null) || NPM_RESULT=""
-            if [[ "$NPM_RESULT" =~ $SEMVER_RE ]]; then
+            NPM_RESULT=$(npm view agentic-sdlc-wizard version 2>/dev/null)
+            NPM_RC=$?
+            if [ "$NPM_RC" -ne 0 ] || ! [[ "$NPM_RESULT" =~ $SEMVER_RE ]]; then
+                NPM_FAILED=1
+            else
                 LATEST_VERSION="$NPM_RESULT"
                 mkdir -p "$VERSION_CACHE_DIR" 2>/dev/null || true
                 printf '%s' "$LATEST_VERSION" > "$VERSION_CACHE_FILE" 2>/dev/null || true
             fi
         fi
 
-        if [ -n "$LATEST_VERSION" ] && [ "$LATEST_VERSION" != "$INSTALLED_VERSION" ]; then
+        # #239: surface npm failure once when cache miss + npm fails. Without
+        # this, the version-check block produces no output and the user has
+        # no way to know the staleness nudge is broken.
+        if [ -z "$LATEST_VERSION" ] && [ "$NPM_FAILED" -eq 1 ]; then
+            echo "npm view failed — version check unavailable (run 'npm view agentic-sdlc-wizard version' to debug)"
+        fi
+
+        # #254 Bug 2: only nudge when installed < latest (semver direction).
+        # Equality `!=` previously fired reverse nudges post-upgrade.
+        if [ -n "$LATEST_VERSION" ] && semver_lt "$INSTALLED_VERSION" "$LATEST_VERSION"; then
             # Minor-version delta: 1.25.0 vs 1.34.0 → 9
             INSTALLED_MINOR=$(echo "$INSTALLED_VERSION" | awk -F. '{print $2+0}')
             LATEST_MINOR=$(echo "$LATEST_VERSION" | awk -F. '{print $2+0}')
@@ -131,8 +170,13 @@ fi
 # this hook and model-effort-check.sh both fire on SessionStart, so two checks
 # would double-print the nudge and risk drifting out of sync.
 
-# Dual-channel install check (#181) — nudge when CLI skills + Claude plugin both present
-if [ -d "$PROJECT_DIR/.claude/skills/update" ]; then
+# Dual-channel install check (#181) — nudge when CLI skills + Claude plugin both present.
+# #238: silenced once the user opts in via an ack sentinel. Sentinel is per-host
+# (lives under $SDLC_WIZARD_CACHE_DIR/dual-channel-acknowledged) since the dual
+# install is always a $HOME-scoped condition.
+DUAL_CACHE_DIR="${SDLC_WIZARD_CACHE_DIR:-$HOME/.cache/sdlc-wizard}"
+DUAL_ACK_FILE="$DUAL_CACHE_DIR/dual-channel-acknowledged"
+if [ -d "$PROJECT_DIR/.claude/skills/update" ] && [ ! -f "$DUAL_ACK_FILE" ]; then
     for plugin_path in "$HOME/.claude/plugins-local/sdlc-wizard-wrap" "$HOME/.claude/plugins/cache/sdlc-wizard-local"; do
         if [ -d "$plugin_path" ]; then
             echo "WARNING: dual-install detected — CLI skills in .claude/skills/ AND Claude plugin at:"
@@ -140,6 +184,7 @@ if [ -d "$PROJECT_DIR/.claude/skills/update" ]; then
             echo "  Duplicate /update-wizard commands come from running both channels. Pick one:"
             echo "    - Keep plugin: remove .claude/skills/ from this project"
             echo "    - Keep CLI:    /plugin uninstall sdlc-wizard (or remove plugin dir)"
+            echo "    - Keep both:   mkdir -p \"$DUAL_CACHE_DIR\" && touch \"$DUAL_ACK_FILE\"  (silences this nudge)"
             break
         fi
     done

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-wizard",
-  "version": "1.43.0",
+  "version": "1.44.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

@@ -131,9 +131,10 @@ Parse all CHANGELOG entries between the user's installed version and the latest.
 
 ```
 Installed: 1.24.0
-Latest:    1.43.0
+Latest:    1.44.0
 
 What changed:
+- [1.44.0] Install-path & cache hygiene — closes #254, #239, #238 filed by consumer codeguesser after upgrading 1.32.0 → 1.42.1. (1) `cli/init.js` FILES list now ships `hooks/_find-sdlc-root.sh` — the helper sourced by all 5 hooks was missing from npm install path, so every session emitted `_find-sdlc-root.sh: No such file or directory` + `dedupe_plugin_or_project: command not found` and the SDLC walk-up logic was silently dead. (2) `init --force` now invalidates `~/.cache/sdlc-wizard/latest-version` so post-upgrade hooks re-fetch fresh values from npm instead of serving the pre-upgrade cache for 24h (which produced reverse "1.42.1 → 1.41.1" nudges). (3) instructions-loaded-check.sh now uses semver-direction comparison via new `semver_lt` function: nudge only fires when installed < latest, equality is silent, reverse direction is silent. Cache sanity-check rejects poisoned values (cached "latest" < installed → force refetch). (4) When `npm view` fails AND cache empty, hook now surfaces a one-line warning instead of going silent. (5) Dual-channel install nudge gains an opt-in silence sentinel — set via `mkdir -p $SDLC_WIZARD_CACHE_DIR && touch $SDLC_WIZARD_CACHE_DIR/dual-channel-acknowledged` (printed inside the nudge itself for discoverability). 8 new tests across test-cli.sh + test-hooks.sh, Codex CERTIFIED 10/10 round 2.
 - [1.43.0] Token-spike anomaly detection — ROADMAP #220 closure. New `hooks/token-spike-check.sh` (SessionStart, opt-in via `.metrics/`) ingests CC transcript usage (`input_tokens` / `output_tokens` / `cache_creation_input_tokens` / `cache_read_input_tokens`) into `.metrics/token-history.jsonl`, then warns when the last session's `costly_tokens` (input + cache_creation + output, excluding the cheap cache_read tier) exceeds median + 2σ over a rolling baseline. Catches silent CC-side caching regressions (per Anthropic's 2026-04-23 post-mortem) before they surface on the invoice. Uses MAD-based spread for the median metric so a single baseline outlier doesn't mask the next spike. 14 quality tests in `tests/test-token-spike.sh` (incl. malicious-transcript privacy probe, flat-baseline floor, median-vs-mean contrast, concurrent-ingest mkdir lock).
 - [1.42.2] PreCompact self-heal documented — ROADMAP #209 closure. Added `pr_number` opt-in to all 3 handoff template schemas (skill Step 1; wizard Round 1 + cross-model section). Self-heal logic shipped earlier with #229 but was undocumented, leaving the dead-code path. New `test_handoff_template_documents_pr_number` enforces template/doc parity. Together with #229 (mtime auto-expire) closes the "stuck PENDING handoff blocks /compact forever" footgun from both directions.
 - [1.42.1] CI hygiene fix — skip Claude PR review on wizard self-PRs. 7 self-PRs (v1.39.0–v1.42.0) had shipped with red `review` job (API canary firing on dead credit balance). Treated as "expected" but red normalizes red. Workflow `if:` now skips review on `BaseInfinity/claude-sdlc-wizard` repo only; consumer projects unaffected. 7 quality tests, mutation-verified (== inversion fails).