agentic-sdlc-wizard 1.71.0 → 1.73.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.71.0",
+      "version": "1.73.0",
       "author": {
         "name": "Stefan Ayala"
       },

package/.claude-plugin/plugin.json

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

package/CHANGELOG.md

@@ -4,6 +4,91 @@ 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.73.0] - 2026-05-06
+
+### Fix: PreCompact hook no longer false-positives on stale `.git/REBASE_HEAD`
+
+`hooks/precompact-seam-check.sh` was treating any presence of `.git/REBASE_HEAD` as "rebase in progress" and blocking manual `/compact`. But `REBASE_HEAD` is just a rebase-related ref (the stopped/replayed commit) that git can leave behind after a clean rebase finishes — the authoritative "rebase in progress" signal is the `rebase-merge/` or `rebase-apply/` directory (which is what `git status` keys on too). Hit live in this repo 2026-05-05 — yesterday's clean rebase left `REBASE_HEAD` behind, the user's manual `/compact` was blocked, and clearing it required `rm .git/REBASE_HEAD` by hand.
+
+The OR-chain at line 227 now drops the `REBASE_HEAD` predicate; only the `rebase-{merge,apply}/` dir checks remain. Two new tests cover the fix:
+
+- `test_precompact_silent_on_stale_rebase_head_alone` — positive: `rc=0` + empty stderr when only `REBASE_HEAD` exists
+- `test_precompact_blocks_on_rebase_head_with_rebase_merge_dir` — negative control: still blocks on real in-flight rebase (REBASE_HEAD + rebase-merge dir together)
+
+156/156 hook tests green. Codex round 1 CERTIFIED 9/10 (one P2 comment-accuracy nit caught — fixed: `REBASE_HEAD` is the stopped/replayed commit, not the original branch tip, which is `ORIG_HEAD`).
+
+PR #330.
+
+### GC: -460 LOC of stale review/plan artifacts (#236 bloat hunt)
+
+`.reviews/` is gitignored, but 14 handoff/preflight/round-N review files for now-merged PRs were committed before that gitignore line landed. They held no ongoing reference value. `plans/CATCHUP.md` captured the v2.1.15 → v2.1.81 catch-up (March 2026) — historical context lives in CHANGELOG (v1.8.0 entry); the plan doc was dead weight.
+
+Deleted (15 files):
+
+- `.reviews/baseline-fires-once-001/{round-1,round-2}-review.md`
+- `.reviews/skill-cross-model-trim-001/{round-1,round-2,round-3}-review.md`
+- `.reviews/tdd-pretool-fires-once-001/{round-1,round-2}-review.md`
+- `.reviews/preflight-{allowed-tools-permissions,baseline-fires-once,model-pin-opt-in,precompact-seam,skill-cross-model-trim,staleness-nudge,tdd-pretool-fires-once}-001.md`
+- `plans/CATCHUP.md`
+
+Kept (still load-bearing):
+
+- `.reviews/research-95/97/99/206/235.md` (cited from ROADMAP rows)
+- `.reviews/experiment-tracking.md` (asserted by `tests/test-workflow-triggers.sh:2189`)
+- `plans/AUTO_SELF_UPDATE.md` (still annotated with #231 phase notes)
+
+Hooks 156/156, cli 88/88, workflow 176/176, docs 35/35 — all green post-deletion.
+
+PR #331.
+
+---
+
+## [1.72.0] - 2026-05-05
+
+### Closes #323: `init --force` no longer silently overwrites CUSTOMIZED files
+
+User report 2026-05-05 — `npx agentic-sdlc-wizard check` flags 6 files as CUSTOMIZED then recommends `init --force`, which silently clobbers all 6. Reporter: "the wizard correctly **detected** 6 CUSTOMIZED files and then **recommended a command that would overwrite all 6**." Fully closed in two parts:
+
+#### Part 1 — customization-aware recommendation in `check` (PR #325)
+
+When `check` finds CUSTOMIZED files alongside an available update, the suggested command now warns and points at `init --dry-run` first instead of silently recommending `init --force`. Pure function `buildUpdateRecommendation(updateInfo, customizedCount)` exported from `cli/init.js`. Backward compat: zero-customized recommendation byte-for-byte unchanged.
+
+#### Part 2 — new `init --preserve-customized` flag (PR #328)
+
+Composes existing `--force` semantics — when both flags are set:
+
+- **CUSTOMIZED** files (sha256 mismatch with template) → action `PRESERVE`, skipped during write, reported in summary footer
+- **MATCH** files → `OVERWRITE` (refresh; effectively no-op since hashes already match)
+- **MISSING** files → `CREATE` (new files added in latest version still get installed)
+
+Without `--force`, the flag is a no-op (all existing files SKIP regardless). Updated `check` recommendation now suggests `init --force --preserve-customized` as the "upgrade safely" path when CUSTOMIZED files exist.
+
+#### Sample output
+
+```
+PRESERVE  .claude/hooks/sdlc-prompt-check.sh
+PRESERVE  .claude/skills/sdlc/SKILL.md
+OVERWRITE .claude/hooks/tdd-pretool-check.sh
+CREATE    .claude/skills/feedback/SKILL.md
+
+PRESERVED 2 customized file(s) — review with `init --dry-run` to see what differs from the latest template.
+```
+
+#### Test coverage
+
+10 new tests in `tests/test-cli.sh` across 3 PRs (78 → 88 green): customization-aware recommendation (2 from #325), null/undefined edge cases (2 from #326 P2 follow-up), preserve-customized core behavior (3 from #328 round 1), no-force-no-op + settings.json MERGE precedence + WIZARD_DOC parity (3 from #328 round-2).
+
+#### Deferred
+
+Option 3 from #323 (real `update` subcommand with backup directory + per-file diff prompt) — options 1 + 2 close the immediate footgun without a new subcommand and backup-storage convention.
+
+#### Files
+
+- `cli/init.js` — `buildUpdateRecommendation()` exported; `--preserve-customized` threaded through `init()` → `planOperations()`; `isCustomized()` hash helper; `PRESERVE` action skipped in `executeOperations()`; `printOps()` adds yellow `PRESERVE` color + summary footer
+- `cli/bin/sdlc-wizard.js` — `--preserve-customized` flag + help text
+- `tests/test-cli.sh` — 10 new tests across 3 PRs (78 → 88 green)
+- `package.json`, `.claude-plugin/plugin.json` + `marketplace.json`, `SDLC.md`, `skills/update/SKILL.md`, `CLAUDE_CODE_SDLC_WIZARD.md`, `CHANGELOG.md` (1.71.0 → 1.72.0)
+
 ## [1.71.0] - 2026-05-05
 
 ### Token-bloat fix: SDLC skill Cross-Model Review section trimmed

package/CLAUDE_CODE_SDLC_WIZARD.md

@@ -2976,7 +2976,7 @@ If deployment fails or post-deploy verification catches issues:
 
 **SDLC.md:**
 ```markdown
-<!-- SDLC Wizard Version: 1.71.0 -->
+<!-- SDLC Wizard Version: 1.73.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] -->
@@ -4070,7 +4070,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.71.0 -->
+<!-- SDLC Wizard Version: 1.73.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/bin/sdlc-wizard.js

@@ -11,6 +11,7 @@ const flags = {
   force: args.includes('--force'),
   dryRun: args.includes('--dry-run'),
   json: args.includes('--json'),
+  preserveCustomized: args.includes('--preserve-customized'),
 };
 
 const positional = args.filter((a) => !a.startsWith('--'));
@@ -31,11 +32,12 @@ if (args.includes('--help') || args.includes('-h') || !command) {
     sdlc-wizard complexity [path]            Print mixed-mode tier heuristic (roadmap #233)
 
   Options:
-    --force       Overwrite existing files (init only)
-    --dry-run     Preview changes without writing (init only)
-    --json        Output as JSON (check / complexity)
-    --version     Show version
-    --help        Show this help
+    --force                  Overwrite existing files (init only)
+    --preserve-customized    With --force, skip files that have local edits (init only)
+    --dry-run                Preview changes without writing (init only)
+    --json                   Output as JSON (check / complexity)
+    --version                Show version
+    --help                   Show this help
   `.trim());
   process.exit(0);
 }

package/cli/init.js

@@ -130,9 +130,23 @@ function mergeSettings(existingPath, templatePath, force) {
   }
 }
 
-function planOperations(targetDir, { force }) {
+function planOperations(targetDir, { force, preserveCustomized = false }) {
   const ops = [];
 
+  // #323 option 2: preserve mode requires hashing each existing file to
+  // distinguish CUSTOMIZED from MATCH. Only meaningful with --force; without
+  // --force, existing files are SKIP regardless of hash.
+  const isCustomized = (srcPath, destPath) => {
+    if (!preserveCustomized || !force) return false;
+    try {
+      const srcHash = crypto.createHash('sha256').update(fs.readFileSync(srcPath)).digest('hex');
+      const destHash = crypto.createHash('sha256').update(fs.readFileSync(destPath)).digest('hex');
+      return srcHash !== destHash;
+    } catch (_) {
+      return false;
+    }
+  };
+
   for (const file of FILES) {
     const destPath = path.join(targetDir, file.dest);
     const srcPath = path.join(file.base || TEMPLATES_DIR, file.src);
@@ -154,11 +168,16 @@ function planOperations(targetDir, { force }) {
       // Invalid JSON — fall through to normal SKIP/OVERWRITE
     }
 
+    let action;
+    if (!exists) action = 'CREATE';
+    else if (isCustomized(srcPath, destPath)) action = 'PRESERVE';
+    else action = force ? 'OVERWRITE' : 'SKIP';
+
     ops.push({
       src: srcPath,
       dest: destPath,
       relativeDest: file.dest,
-      action: exists ? (force ? 'OVERWRITE' : 'SKIP') : 'CREATE',
+      action,
       executable: file.executable || false,
     });
   }
@@ -166,11 +185,15 @@ function planOperations(targetDir, { force }) {
   // Wizard doc
   const wizardDest = path.join(targetDir, 'CLAUDE_CODE_SDLC_WIZARD.md');
   const wizardExists = fs.existsSync(wizardDest);
+  let wizardAction;
+  if (!wizardExists) wizardAction = 'CREATE';
+  else if (isCustomized(WIZARD_DOC, wizardDest)) wizardAction = 'PRESERVE';
+  else wizardAction = force ? 'OVERWRITE' : 'SKIP';
   ops.push({
     src: WIZARD_DOC,
     dest: wizardDest,
     relativeDest: 'CLAUDE_CODE_SDLC_WIZARD.md',
-    action: wizardExists ? (force ? 'OVERWRITE' : 'SKIP') : 'CREATE',
+    action: wizardAction,
     executable: false,
   });
 
@@ -183,7 +206,7 @@ function ensureDir(filePath) {
 
 function executeOperations(ops) {
   for (const op of ops) {
-    if (op.action === 'SKIP') continue;
+    if (op.action === 'SKIP' || op.action === 'PRESERVE') continue;
     ensureDir(op.dest);
     if (op.action === 'MERGE') {
       fs.writeFileSync(op.dest, op.mergedContent);
@@ -230,12 +253,18 @@ function updateGitignore(targetDir, { dryRun }) {
 }
 
 function printOps(ops) {
+  let preserveCount = 0;
   for (const op of ops) {
     const color = op.action === 'CREATE' ? GREEN
       : op.action === 'SKIP' ? YELLOW
       : op.action === 'MERGE' ? MAGENTA
+      : op.action === 'PRESERVE' ? YELLOW
       : CYAN;
     console.log(`  ${color}${op.action}${RESET}  ${op.relativeDest}`);
+    if (op.action === 'PRESERVE') preserveCount++;
+  }
+  if (preserveCount > 0) {
+    console.log(`\n  ${YELLOW}PRESERVED ${preserveCount} customized file(s)${RESET} — review with \`init --dry-run\` to see what differs from the latest template.`);
   }
 }
 
@@ -254,7 +283,7 @@ function invalidateVersionCache({ dryRun }) {
   return true;
 }
 
-function init(targetDir, { force = false, dryRun = false } = {}) {
+function init(targetDir, { force = false, dryRun = false, preserveCustomized = false } = {}) {
   if (!dryRun && !force) {
     const pluginPaths = detectPluginInstall();
     if (pluginPaths.length > 0) {
@@ -273,7 +302,7 @@ function init(targetDir, { force = false, dryRun = false } = {}) {
     }
   }
 
-  const ops = planOperations(targetDir, { force });
+  const ops = planOperations(targetDir, { force, preserveCustomized });
 
   if (dryRun) {
     console.log('Dry run — no files will be written:\n');
@@ -396,14 +425,37 @@ function check(targetDir, { json = false } = {}) {
       }
     }
     if (updateInfo) {
-      console.log(`\n  ${YELLOW}UPDATE${RESET}  v${updateInfo.current} -> v${updateInfo.latest}`);
-      console.log('         Run: npx agentic-sdlc-wizard init --force');
+      const customizedCount = results.filter((r) => r.status === 'CUSTOMIZED').length;
+      for (const line of buildUpdateRecommendation(updateInfo, customizedCount)) {
+        console.log(line);
+      }
     }
   }
 
   return { results, updateInfo, hasDrift, marketplace };
 }
 
+// #323: when `check` finds CUSTOMIZED files alongside an available update,
+// the historical recommendation `init --force` would silently clobber them.
+// This builds an update-recommendation block that's customization-aware:
+// no-CUSTOMIZED → recommend --force as before. Has-CUSTOMIZED → warn and
+// recommend `--dry-run` first so the user can preview the diff.
+function buildUpdateRecommendation(updateInfo, customizedCount) {
+  if (!updateInfo) return [];
+  const lines = [
+    `\n  ${YELLOW}UPDATE${RESET}  v${updateInfo.current} -> v${updateInfo.latest}`,
+  ];
+  if (customizedCount > 0) {
+    lines.push(`         ${YELLOW}WARNING${RESET}: ${customizedCount} file(s) CUSTOMIZED — \`init --force\` will overwrite them`);
+    lines.push(`         Preview first:  npx agentic-sdlc-wizard init --dry-run`);
+    lines.push(`         Or upgrade safely: npx agentic-sdlc-wizard init --force --preserve-customized`);
+    lines.push(`         (\`--preserve-customized\` skips CUSTOMIZED files and updates only MATCH ones.)`);
+  } else {
+    lines.push('         Run: npx agentic-sdlc-wizard init --force');
+  }
+  return lines;
+}
+
 function checkFile(srcPath, destPath, relativeDest, shouldBeExecutable) {
   if (!fs.existsSync(destPath)) {
     return { file: relativeDest, status: 'MISSING' };
@@ -519,4 +571,4 @@ function checkMarketplacePaths() {
   return results;
 }
 
-module.exports = { init, check, planOperations, detectPluginInstall, GITIGNORE_ENTRIES };
+module.exports = { init, check, planOperations, detectPluginInstall, buildUpdateRecommendation, GITIGNORE_ENTRIES };

package/hooks/precompact-seam-check.sh

@@ -218,7 +218,14 @@ esac
 # Unknown value (e.g. typo "bogus") → also falls through to real check
 # rather than silently bypassing safety. The safer-than-the-typo path.
 if [ "$DRY_RUN_GIT_HANDLED" -eq 0 ] && [ -d "$GITDIR" ]; then
-    if [ -e "$GITDIR/REBASE_HEAD" ] || [ -d "$GITDIR/rebase-merge" ] || [ -d "$GITDIR/rebase-apply" ]; then
+    # Only the rebase-{merge,apply}/ dir is authoritative for "rebase in progress."
+    # .git/REBASE_HEAD is a rebase-related ref (the stopped/replayed commit) that
+    # is not authoritative on its own — it can persist as a stale marker after a
+    # rebase finishes cleanly: git removes the dir but leaves REBASE_HEAD around
+    # for diff/log lookups. Including it in the OR-chain caused false-positive
+    # HOLDs that blocked manual /compact for users whose previous rebase had
+    # completed (hit live 2026-05-05). `git status` keys on the dirs too.
+    if [ -d "$GITDIR/rebase-merge" ] || [ -d "$GITDIR/rebase-apply" ]; then
         HOLD_REASONS="${HOLD_REASONS}  - Git rebase in progress. Compacting mid-rebase loses the operation's context.
     Resolve: finish or abort the rebase before /compact."$'\n'
     fi

package/package.json

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

@@ -93,12 +93,12 @@ Parse CHANGELOG entries between the user's installed version and latest. Present
 
 ```
 Installed: 1.42.0
-Latest:    1.71.0
+Latest:    1.73.0
 
 What changed:
-- [1.71.0] token-bloat fix phase 3 — `skills/sdlc/SKILL.md` Cross-Model Review section trimmed from ~70 lines to ~20 (4995 → 4568 tokens). Decision-making + 4-step protocol summary + convergence rule kept; full JSON examples / codex commands moved to `CLAUDE_CODE_SDLC_WIZARD.md` "Cross-Model Review Loop" canonical section (which also gained Anti-patterns + Multi-reviewer + Non-code-domain subsections). Saves ~427 tokens per SDLC skill auto-invoke. Codex round 1 caught 3 test assertions broken by initial trim; round 2 fixes restored constraints in tighter prose.
-- [1.70.0] token-bloat fix phase 2 — `hooks/tdd-pretool-check.sh` TDD CHECK JSON nudge fires once per CC `session_id` instead of every src/ edit. Saves ~0.5-1.5K tokens/session.
-- [1.69.0] token-bloat fix phase 1 — `hooks/sdlc-prompt-check.sh` BASELINE block fires once per CC `session_id`. Saves ~12K tokens/session.
+- [1.73.0] precompact stale REBASE_HEAD fix + bloat sweep — `hooks/precompact-seam-check.sh` no longer false-positive HOLDs `/compact` when a finished rebase left REBASE_HEAD behind without `rebase-{merge,apply}/` dirs (hit live 2026-05-05). 15 tracked review/plan artifacts deleted (-460 LOC).
+- [1.72.0] #323 closed — customization-aware `check` recommendation + new `--preserve-customized` flag. `init --force --preserve-customized` skips CUSTOMIZED files (action `PRESERVE`), still OVERWRITEs MATCH and CREATEs MISSING. Default `init --force` unchanged. 10 tests.
+- [1.71.0–1.69.0] token-bloat sweep #236 — three phases: BASELINE block fires once per `session_id` (-12K/session), TDD CHECK fires once per `session_id` (-0.5-1.5K/session), `skills/sdlc/SKILL.md` Cross-Model Review trimmed (full protocol moved to canonical wizard doc).
 - [1.68.0–1.65.0] roadmap hygiene — five paperwork closes: #97 Anthropic Policy NO-GO + AAR-paper validating parallel; #99 AutoGPT NO-GO; #95 Nous NO-GO; #243 token-history liveness verified; #210 Node-24 false-green; #235 Thoughtworks AI Evals NO-GO. **6/6 external-product audits NO-GO** (continues #76, #77). Research write-ups in `.reviews/research-*.md`.
 - [1.64.0] XDLC ecosystem cross-references — README, wizard doc, and ROADMAP now cross-reference all three sibling packages (`agentic-sdlc-wizard`, `codex-sdlc-wizard`, `claude-gdlc-wizard`). New "Ecosystem (Sibling Projects)" section in README. 3 new doc-consistency tests prevent drift.
 - [1.63.0] cache-cost observability closeout (#204 absorbed by #220) — `tests/test-token-spike.sh` gains explicit cache-miss regression test + negative-control test. SDLC skill + wizard doc gain "Cache-Cost Surprises" sections covering 10-20× silent cost blowups (mid-session CLAUDE.md edits, idle pruning, upstream cache bugs) and detection via `hooks/token-spike-check.sh`'s `costly_tokens` metric.