create-sdd-project 0.18.1 → 0.18.2

package/lib/adapt-agents.js

@@ -91,6 +91,13 @@ const WORKFLOW_CORE_PROJECT_TYPE_RULES = {
       [/### UI Changes \(if applicable\)\n\n\[Components to add\/modify\. Reference `docs\/specs\/ui-components\.md`\.\]\n\n/, ''],
       [' / `ui-components.md`', ''],
     ],
+    // v0.18.2 (Codex R1 finding C4): pr-template.md is project-type adapted —
+    // moved from inline replaceInFileFn to this table so smart-diff fallback
+    // compare via adaptWorkflowCoreContentForProjectType produces a matching
+    // pristine target on backend/frontend installs (no false-preserve).
+    'skills/development-workflow/references/pr-template.md': [
+      [' / ui-components.md', ''],
+    ],
   },
   frontend: {
     'skills/development-workflow/SKILL.md': [
@@ -101,6 +108,9 @@ const WORKFLOW_CORE_PROJECT_TYPE_RULES = {
       [/### API Changes \(if applicable\)\n\n\[Endpoints to add\/modify\. Reference[^\]]*\]\n\n/, ''],
       ['`api-spec.yaml` / ', ''],
     ],
+    'skills/development-workflow/references/pr-template.md': [
+      ['api-spec.yaml / ', ''],
+    ],
   },
 };
 
@@ -243,25 +253,16 @@ function adaptAgentContentForProjectType(dest, config, replaceInFileFn) {
     replaceInFileFn(path.join(dest, 'AGENTS.md'), [
       [', `ui-ux-designer`', ''],
     ]);
-    for (const dir of toolDirs) {
-      // pr-template: remove ui-components from checklist (out of scope for
-      // v0.17.1 — see dev/ROADMAP.md "Known follow-ups" item 2)
-      replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'pr-template.md'), [
-        [' / ui-components.md', ''],
-      ]);
-    }
+    // v0.18.2 (Codex R1 C4): pr-template.md rules moved to WORKFLOW_CORE_PROJECT_TYPE_RULES
+    // (handled by the wfRules loop above) so smart-diff fallback compare can
+    // produce a pristine adapted target via adaptWorkflowCoreContentForProjectType.
     // base-standards.mdc: remove ui-ux-designer table row (shared table above)
     replaceInFileFn(
       path.join(dest, 'ai-specs', 'specs', 'base-standards.mdc'),
       BASE_STANDARDS_PROJECT_TYPE_RULES.backend
     );
-  } else if (config.projectType === 'frontend') {
-    for (const dir of toolDirs) {
-      replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'pr-template.md'), [
-        ['api-spec.yaml / ', ''],
-      ]);
-    }
   }
+  // v0.18.2: frontend pr-template rule also moved to WORKFLOW_CORE_PROJECT_TYPE_RULES.
 }
 
 module.exports = {

package/lib/meta.js

@@ -273,14 +273,41 @@ function expectedSmartDiffTrackedPaths(aiTools, projectType) {
   paths.add('ai-specs/specs/documentation-standards.mdc');
 
   // v0.17.1: development-workflow skill core files — filtered by aiTools.
-  // bug-workflow, health-check, pm-orchestrator, project-memory are OUT OF
-  // SCOPE for v0.17.1 (deferred — see dev/ROADMAP.md "Known follow-ups" item 2).
   for (const dir of toolDirs) {
     paths.add(`${dir}/skills/development-workflow/SKILL.md`);
     paths.add(`${dir}/skills/development-workflow/references/ticket-template.md`);
     paths.add(`${dir}/skills/development-workflow/references/merge-checklist.md`);
   }
 
+  // v0.18.2: extend smart-diff coverage to remaining SKILL.md entry points +
+  // 11 reference files (closes ROADMAP "Known follow-ups" item 1 — long-deferred
+  // since v0.17.1). Universal per aiTools (no project-type filtering — skills
+  // and reference templates are stack-agnostic except pr-template.md, which
+  // has project-type rules in WORKFLOW_CORE_PROJECT_TYPE_RULES so the
+  // fallback compare in upgrade-generator.js produces a pristine adapted
+  // target).
+  for (const dir of toolDirs) {
+    // 4 SKILL.md entry points
+    paths.add(`${dir}/skills/bug-workflow/SKILL.md`);
+    paths.add(`${dir}/skills/health-check/SKILL.md`);
+    paths.add(`${dir}/skills/pm-orchestrator/SKILL.md`);
+    paths.add(`${dir}/skills/project-memory/SKILL.md`);
+    // 7 development-workflow references
+    paths.add(`${dir}/skills/development-workflow/references/pr-template.md`);
+    paths.add(`${dir}/skills/development-workflow/references/branching-strategy.md`);
+    paths.add(`${dir}/skills/development-workflow/references/failure-handling.md`);
+    paths.add(`${dir}/skills/development-workflow/references/workflow-example.md`);
+    paths.add(`${dir}/skills/development-workflow/references/complexity-guide.md`);
+    paths.add(`${dir}/skills/development-workflow/references/add-feature-template.md`);
+    paths.add(`${dir}/skills/development-workflow/references/cross-model-review.md`);
+    // 1 pm-orchestrator reference
+    paths.add(`${dir}/skills/pm-orchestrator/references/pm-session-template.md`);
+    // 3 project-memory references
+    paths.add(`${dir}/skills/project-memory/references/bugs_template.md`);
+    paths.add(`${dir}/skills/project-memory/references/decisions_template.md`);
+    paths.add(`${dir}/skills/project-memory/references/key_facts_template.md`);
+  }
+
   // v0.18.1: shipped slash-commands — preserve user customizations across
   // upgrades. Closes v0.18.0 known limitation where audit-merge.md was
   // wholesale-overwritten (notable since teams may tune drift recipes for

package/lib/upgrade-generator.js

@@ -305,21 +305,45 @@ function generateUpgrade(config) {
   const filesToAdapt = new Set();
 
   // v0.17.1: before the skills/ wholesale delete-and-copy, save the content
-  // of the 6 workflow-core files so we can restore them if their hash tells
+  // of the workflow-core files so we can restore them if their hash tells
   // us they were customized. Map keyed by absolute path, value = string or
   // null (null = file didn't exist before upgrade).
+  // v0.18.2: extended from 6 paths to 21 paths × tool dirs (max 42 for
+  // fullstack-both). Adds 4 SKILL.md entry points + 11 reference files,
+  // closing ROADMAP "Known follow-ups" item 1.
   const workflowCoreBackup = new Map();
   const workflowCorePosixPaths = [];
   {
     const dirsForBackup = [];
     if (aiTools !== 'gemini') dirsForBackup.push('.claude');
     if (aiTools !== 'claude') dirsForBackup.push('.gemini');
+    const WORKFLOW_CORE_RELATIVE_PATHS = [
+      // v0.17.1 (3 files)
+      'skills/development-workflow/SKILL.md',
+      'skills/development-workflow/references/ticket-template.md',
+      'skills/development-workflow/references/merge-checklist.md',
+      // v0.18.2: 4 SKILL.md entry points
+      'skills/bug-workflow/SKILL.md',
+      'skills/health-check/SKILL.md',
+      'skills/pm-orchestrator/SKILL.md',
+      'skills/project-memory/SKILL.md',
+      // v0.18.2: 7 development-workflow references
+      'skills/development-workflow/references/pr-template.md',
+      'skills/development-workflow/references/branching-strategy.md',
+      'skills/development-workflow/references/failure-handling.md',
+      'skills/development-workflow/references/workflow-example.md',
+      'skills/development-workflow/references/complexity-guide.md',
+      'skills/development-workflow/references/add-feature-template.md',
+      'skills/development-workflow/references/cross-model-review.md',
+      // v0.18.2: 1 pm-orchestrator reference
+      'skills/pm-orchestrator/references/pm-session-template.md',
+      // v0.18.2: 3 project-memory references
+      'skills/project-memory/references/bugs_template.md',
+      'skills/project-memory/references/decisions_template.md',
+      'skills/project-memory/references/key_facts_template.md',
+    ];
     for (const dir of dirsForBackup) {
-      for (const relSub of [
-        'skills/development-workflow/SKILL.md',
-        'skills/development-workflow/references/ticket-template.md',
-        'skills/development-workflow/references/merge-checklist.md',
-      ]) {
+      for (const relSub of WORKFLOW_CORE_RELATIVE_PATHS) {
         const posix = `${dir}/${relSub}`;
         const abs = path.join(dest, ...posix.split('/'));
         workflowCorePosixPaths.push({ posix, abs });
@@ -370,13 +394,13 @@ function generateUpgrade(config) {
         fs.rmSync(subDir, { recursive: true, force: true });
       }
     }
-    // For .gemini, also remove commands (SDD-owned — Gemini TOML commands)
-    if (dir === '.gemini') {
-      const cmdDir = path.join(base, 'commands');
-      if (fs.existsSync(cmdDir)) {
-        fs.rmSync(cmdDir, { recursive: true, force: true });
-      }
-    }
+    // v0.18.2: do NOT wholesale-delete .gemini/commands. The smart-diff loop
+    // below iterates template command files individually and preserves user
+    // customizations of tracked paths (e.g. audit-merge.toml) — closing the
+    // v0.18.1 plumbing gap where these files were silently overwritten on
+    // every upgrade despite being tracked in expectedSmartDiffTrackedPaths.
+    // Custom Gemini commands (files NOT in the template) are left in place,
+    // mirroring the agent strategy from v0.16.10.
 
     // Copy fresh from template
     const templateToolDir = path.join(templateDir, dir);
@@ -522,16 +546,117 @@ function generateUpgrade(config) {
           continue;
         }
 
-        // For .claude/commands, merge: overwrite SDD template commands, preserve user's custom commands
-        if (dir === '.claude' && sub === 'commands') {
+        // v0.18.2: smart-diff loop for commands (closes v0.18.1 plumbing gap).
+        //
+        // Pre-v0.18.2: .claude/commands wholesale cpSync'd every file (line 525-531)
+        // and .gemini/commands wholesale rmSync'd + recursive cpSync'd (lines 374-378
+        // and the fallback at 532-533). Both branches overwrote user customizations
+        // silently despite the paths being added to expectedSmartDiffTrackedPaths in
+        // v0.18.1 (lib/meta.js:284-320).
+        //
+        // Now: iterate template command files individually. For each file:
+        //   - If posix path is tracked → smart-diff decision tree (preserve customizations)
+        //   - Else → unconditional overwrite (SDD-owned wrappers, e.g. add-feature.toml)
+        // Custom commands (files NOT in template) are NOT touched, mirroring the
+        // agent strategy from v0.16.10.
+        //
+        // Commands have NO project-type or stack adaptations — adapted target == raw template.
+        if (sub === 'commands') {
           fs.mkdirSync(destSub, { recursive: true });
-          for (const file of fs.readdirSync(srcSub)) {
-            // Always overwrite template-owned files (they may have been updated)
-            fs.cpSync(path.join(srcSub, file), path.join(destSub, file));
+          const trackedSet = expectedSmartDiffTrackedPaths(aiTools, projectType);
+          const templateCmdFiles = fs
+            .readdirSync(srcSub, { withFileTypes: true })
+            .filter((e) => e.isFile())
+            .map((e) => e.name);
+
+          for (const file of templateCmdFiles) {
+            const templateCmdPath = path.join(srcSub, file);
+            const existingCmdPath = path.join(destSub, file);
+            const relativePath = path.relative(dest, existingCmdPath);
+            const posixPath = toPosix(relativePath);
+            const rawTemplate = fs.readFileSync(templateCmdPath, 'utf8');
+
+            if (!trackedSet.has(posixPath)) {
+              // SDD-owned (e.g. add-feature.toml, fix-bug.toml, next-task.toml,
+              // show-progress.toml, start-task.toml) — unconditional overwrite.
+              if (fs.existsSync(existingCmdPath)) {
+                backupBeforeReplace(dest, relativePath, backupTimestamp);
+              }
+              fs.writeFileSync(existingCmdPath, rawTemplate, 'utf8');
+              replaced++;
+              continue;
+            }
+
+            // --- v0.18.2 commands smart-diff decision tree (mirror of agents) ---
+            if (!fs.existsSync(existingCmdPath)) {
+              fs.writeFileSync(existingCmdPath, rawTemplate, 'utf8');
+              filesToAdapt.add(posixPath);
+              replaced++;
+              continue;
+            }
+
+            if (config.forceTemplate) {
+              backupBeforeReplace(dest, relativePath, backupTimestamp);
+              fs.writeFileSync(existingCmdPath, rawTemplate, 'utf8');
+              filesToAdapt.add(posixPath);
+              replaced++;
+              continue;
+            }
+
+            const existingContent = fs.readFileSync(existingCmdPath, 'utf8');
+            const storedHash = meta && meta.hashes[posixPath];
+
+            const preserveCmd = () => {
+              backupBeforeReplace(dest, relativePath, backupTimestamp);
+              const newBackupPath = path.join(
+                dest,
+                '.sdd-backup',
+                backupTimestamp,
+                `${relativePath}.new`
+              );
+              try {
+                fs.mkdirSync(path.dirname(newBackupPath), { recursive: true });
+                fs.writeFileSync(newBackupPath, rawTemplate, 'utf8');
+              } catch (e) {
+                console.warn(
+                  `    ⚠ Failed to write .new backup for ${relativePath}: ${e.code || e.message}`
+                );
+              }
+              modifiedAgentsResults.push({ name: relativePath, modified: true });
+              preserved++;
+              // Codex M1 invariant: preserved files do NOT update newHashes.
+            };
+
+            if (storedHash) {
+              const currentHash = computeHash(existingContent);
+              if (currentHash === storedHash) {
+                // Pristine — replace + record new hash.
+                backupBeforeReplace(dest, relativePath, backupTimestamp);
+                fs.writeFileSync(existingCmdPath, rawTemplate, 'utf8');
+                filesToAdapt.add(posixPath);
+                replaced++;
+                continue;
+              }
+              // Hash mismatch → user customized → preserve.
+              preserveCmd();
+              continue;
+            }
+
+            // Fallback — no hash (e.g. pre-v0.18.1 install). Compare against
+            // raw template (commands have no adapters).
+            if (normalizedContentEquals(existingContent, rawTemplate)) {
+              backupBeforeReplace(dest, relativePath, backupTimestamp);
+              fs.writeFileSync(existingCmdPath, rawTemplate, 'utf8');
+              filesToAdapt.add(posixPath);
+              replaced++;
+              continue;
+            }
+            preserveCmd();
           }
-        } else {
-          fs.cpSync(srcSub, destSub, { recursive: true });
+          continue;
         }
+
+        fs.cpSync(srcSub, destSub, { recursive: true });
         replaced++;
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-sdd-project",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "description": "Create a new SDD DevFlow project with AI-assisted development workflow",
   "bin": {
     "create-sdd-project": "bin/cli.js"

package/template/.claude/commands/audit-merge.md

@@ -169,9 +169,29 @@ esac
   && flag "P11 drift: ticket Status='$TICKET_STATUS' expects tracker='$EXPECTED' but tracker='$TRACKER_STATUS'"
 ```
 
+**23. P12 — Tracker HEAD references stale (added v0.18.2).** The `**Last Updated:**` and `**Active Feature:**` lines may embed `HEAD <sha>` or `HEAD: <sha>` references that were correct when written but went stale as further commits landed (empirically observed in fx F-WEB-MENU-VISION-001 audit cycle 2026-05-06: tracker said `HEAD: fd752e4` while `git rev-parse HEAD` was `6fa801e` after the agent's own self-edit commit). Compare each extracted SHA against the active branch HEAD. Bidirectional prefix tolerance: a 7-char tracker SHA matches the full 40-char actual HEAD if it's a prefix; a full 40-char tracker SHA matches if its first 7 chars equal the actual short form. Scoped strictly to the two header lines so narrative SHAs in "Last Completed" prose never false-positive-fire.
+```bash
+TRACKER=docs/project_notes/product-tracker.md
+if [ -f "$TRACKER" ]; then
+  ACTUAL_HEAD=$(git rev-parse HEAD 2>/dev/null || true)
+  if [ -n "$ACTUAL_HEAD" ]; then
+    ACTUAL_SHORT=$(printf '%s' "$ACTUAL_HEAD" | cut -c1-7)
+    TRACKER_HEADS=$(grep -E '^\*\*(Last Updated|Active Feature):\*\*' "$TRACKER" 2>/dev/null \
+      | grep -oE 'HEAD[[:space:]:]+`?[a-f0-9]{7,40}`?' \
+      | grep -oE '[a-f0-9]{7,40}' \
+      | sort -u || true)
+    for sha in $TRACKER_HEADS; do
+      case "$ACTUAL_HEAD" in "$sha"*) continue ;; esac
+      case "$sha" in "$ACTUAL_SHORT"*) continue ;; esac
+      flag "P12 drift: tracker HEAD reference $sha does not match git rev-parse HEAD ($ACTUAL_HEAD); refresh tracker"
+    done
+  fi
+fi
+```
+
 ### Execution discipline (added v0.18.1)
 
-For each of the 11 drift checks (P1–P11), if you declare PASS, **include the literal command output** (or its absence — explicit "no rows matched", "extracted: feature/foo", "FROZEN_COUNT=0") as evidence in your report. A bare "PASS" without supporting output is treated as **NOT EXECUTED** by the auditor — re-run with output captured.
+For each of the 12 drift checks (P1–P12), if you declare PASS, **include the literal command output** (or its absence — explicit "no rows matched", "extracted: feature/foo", "FROZEN_COUNT=0") as evidence in your report. A bare "PASS" without supporting output is treated as **NOT EXECUTED** by the auditor — re-run with output captured.
 
 Recommended pattern:
 
@@ -208,7 +228,7 @@ Report two tables — one for **structural (blocking)** compliance, one for **dr
 
 **STRUCTURAL: READY FOR MERGE** (or **STRUCTURAL: NEEDS FIX — N blockers**)
 
-### Drift (12-22) — advisory, refresh before user authorization
+### Drift (12-23) — advisory, refresh before user authorization
 
 | # | Pattern | Status | Detail |
 |---|---------|:------:|--------|
@@ -223,6 +243,7 @@ Report two tables — one for **structural (blocking)** compliance, one for **dr
 | 20 | P9 Tracker header stale | PASS | header = detail |
 | 21 | P10 Duplicate log rows | PASS | no duplicates |
 | 22 | P11 Tracker status mismatch | PASS | in-progress for Ready for Merge |
+| 23 | P12 Tracker HEAD reference | PASS | tracker HEAD = git HEAD |
 
 **DRIFT: CLEAN** (or **DRIFT: N advisories — refresh before merge**)
 
@@ -254,6 +275,7 @@ Fix them directly:
 - **P9 (Tracker header stale)** → update `**Last Updated:**` line step reference to match Active Feature detail
 - **P10 (Duplicate log rows)** → remove duplicate rows
 - **P11 (Tracker status mismatch)** → sync tracker Features row status to ticket header Status
+- **P12 (Tracker HEAD reference stale)** → update `**Last Updated:**` and `**Active Feature:**` `HEAD: <sha>` tokens to match `git rev-parse HEAD`. Use `git rev-parse --short HEAD` for the 7-char form.
 
 After fixing, re-run the audit to confirm all checks pass.
 

package/template/.gemini/commands/audit-merge-instructions.md

@@ -169,9 +169,29 @@ esac
   && flag "P11 drift: ticket Status='$TICKET_STATUS' expects tracker='$EXPECTED' but tracker='$TRACKER_STATUS'"
 ```
 
+**23. P12 — Tracker HEAD references stale (added v0.18.2).** The `**Last Updated:**` and `**Active Feature:**` lines may embed `HEAD <sha>` or `HEAD: <sha>` references that were correct when written but went stale as further commits landed (empirically observed in fx F-WEB-MENU-VISION-001 audit cycle 2026-05-06: tracker said `HEAD: fd752e4` while `git rev-parse HEAD` was `6fa801e` after the agent's own self-edit commit). Compare each extracted SHA against the active branch HEAD. Bidirectional prefix tolerance: a 7-char tracker SHA matches the full 40-char actual HEAD if it's a prefix; a full 40-char tracker SHA matches if its first 7 chars equal the actual short form. Scoped strictly to the two header lines so narrative SHAs in "Last Completed" prose never false-positive-fire.
+```bash
+TRACKER=docs/project_notes/product-tracker.md
+if [ -f "$TRACKER" ]; then
+  ACTUAL_HEAD=$(git rev-parse HEAD 2>/dev/null || true)
+  if [ -n "$ACTUAL_HEAD" ]; then
+    ACTUAL_SHORT=$(printf '%s' "$ACTUAL_HEAD" | cut -c1-7)
+    TRACKER_HEADS=$(grep -E '^\*\*(Last Updated|Active Feature):\*\*' "$TRACKER" 2>/dev/null \
+      | grep -oE 'HEAD[[:space:]:]+`?[a-f0-9]{7,40}`?' \
+      | grep -oE '[a-f0-9]{7,40}' \
+      | sort -u || true)
+    for sha in $TRACKER_HEADS; do
+      case "$ACTUAL_HEAD" in "$sha"*) continue ;; esac
+      case "$sha" in "$ACTUAL_SHORT"*) continue ;; esac
+      flag "P12 drift: tracker HEAD reference $sha does not match git rev-parse HEAD ($ACTUAL_HEAD); refresh tracker"
+    done
+  fi
+fi
+```
+
 ### Execution discipline (added v0.18.1)
 
-For each of the 11 drift checks (P1–P11), if you declare PASS, **include the literal command output** (or its absence — explicit "no rows matched", "extracted: feature/foo", "FROZEN_COUNT=0") as evidence in your report. A bare "PASS" without supporting output is treated as **NOT EXECUTED** by the auditor — re-run with output captured.
+For each of the 12 drift checks (P1–P12), if you declare PASS, **include the literal command output** (or its absence — explicit "no rows matched", "extracted: feature/foo", "FROZEN_COUNT=0") as evidence in your report. A bare "PASS" without supporting output is treated as **NOT EXECUTED** by the auditor — re-run with output captured.
 
 Recommended pattern:
 
@@ -208,7 +228,7 @@ Report two tables — one for **structural (blocking)** compliance, one for **dr
 
 **STRUCTURAL: READY FOR MERGE** (or **STRUCTURAL: NEEDS FIX — N blockers**)
 
-### Drift (12-22) — advisory, refresh before user authorization
+### Drift (12-23) — advisory, refresh before user authorization
 
 | # | Pattern | Status | Detail |
 |---|---------|:------:|--------|
@@ -223,6 +243,7 @@ Report two tables — one for **structural (blocking)** compliance, one for **dr
 | 20 | P9 Tracker header stale | PASS | header = detail |
 | 21 | P10 Duplicate log rows | PASS | no duplicates |
 | 22 | P11 Tracker status mismatch | PASS | status consistent |
+| 23 | P12 Tracker HEAD reference | PASS | tracker HEAD = git HEAD |
 
 **DRIFT: CLEAN** (or **DRIFT: N advisories — refresh before merge**)
 
@@ -254,6 +275,7 @@ Fix them directly:
 - **P9** → refresh `**Last Updated:**` step reference
 - **P10** → remove duplicate rows
 - **P11** → sync tracker Features row status to ticket header Status
+- **P12 (Tracker HEAD reference stale)** → update `**Last Updated:**` and `**Active Feature:**` `HEAD: <sha>` tokens to match `git rev-parse HEAD`. Use `git rev-parse --short HEAD` for the 7-char form.
 
 After fixing, re-run the audit to confirm all checks pass.