create-sdd-project 0.16.9 → 0.17.0

package/lib/upgrade-generator.js

@@ -9,7 +9,10 @@ const {
   TEMPLATE_AGENTS,
   TEMPLATE_COMMANDS,
 } = require('./config');
-const { adaptAgentContentForProjectType } = require('./adapt-agents');
+const {
+  adaptAgentContentForProjectType,
+  adaptAgentContentString,
+} = require('./adapt-agents');
 const {
   adaptBaseStandards,
   adaptBackendStandards,
@@ -21,6 +24,96 @@ const {
   updateAutonomy,
   regexReplaceInFile,
 } = require('./init-generator');
+// v0.17.0: hash-based smart-diff + shared stack adaptations
+const {
+  readMeta,
+  writeMeta,
+  computeHash,
+  hashFileOnDisk,
+  toPosix,
+  pruneExpectedAbsent,
+  expectedSmartDiffTrackedPaths,
+  normalizeForCompare: metaNormalizeForCompare,
+} = require('./meta');
+const {
+  applyStackAdaptations,
+  applyStackAdaptationsToContent,
+} = require('./stack-adaptations');
+
+// --- v0.16.10: backup-before-replace helpers ---
+//
+// Nuclear safety net for smart-diff protection (Changes #1 + #2 + #3).
+// Ensures no user file is overwritten during upgrade without a recoverable
+// backup. Idempotent per run — each path is backed up at most once even if
+// touched by multiple stages of the upgrade pipeline.
+
+const backedUpPaths = new Set(); // reset at the start of every generateUpgrade call
+
+/**
+ * Build a collision-safe backup directory name.
+ *
+ * Format: YYYYMMDD-HHMMSS-NNNN where NNNN is the last 4 digits of the
+ * current epoch millisecond count. Two upgrades within the same second get
+ * distinct directory names because the millisecond suffix differs.
+ *
+ * Examples:
+ *   20260413-150000-1234
+ *   20260413-150000-5678 (one millisecond later)
+ */
+function buildBackupTimestamp() {
+  const now = new Date();
+  const iso = now
+    .toISOString()
+    .replace(/[-:]/g, '')
+    .replace(/\..+$/, '')
+    .replace('T', '-');
+  const msSuffix = Date.now().toString().slice(-4);
+  return `${iso}-${msSuffix}`;
+}
+
+/**
+ * Normalize text for smart-diff comparison.
+ *
+ * v0.17.0: delegates to `lib/meta.js` which only strips CR/CRLF (Windows
+ * git core.autocrlf compatibility). Trailing whitespace is NO LONGER
+ * stripped — that would destroy markdown hard-breaks (two trailing
+ * spaces = <br>) and silently wipe legitimate customizations (Gemini M2
+ * fix from plan v1.0 review). A local re-export here keeps the old
+ * symbol available for any pre-v0.17.0 code paths that still call it.
+ */
+const normalizeForCompare = metaNormalizeForCompare;
+
+/**
+ * Copy a user file to .sdd-backup/<timestamp>/<relativePath> before it is
+ * modified or replaced. Returns the absolute backup path, or null if the
+ * source doesn't exist, was already backed up this run, or the copy failed
+ * (non-fatal — warning printed).
+ *
+ * Contract:
+ *   - Idempotent per run: calling twice for the same path is a no-op
+ *   - Non-fatal on failure: upgrade continues even if backup can't be written
+ *   - Does NOT mkdir the backup parent directory until we know the source
+ *     file exists, to avoid leaving empty directories on failure
+ */
+function backupBeforeReplace(dest, relativePath, backupTimestamp) {
+  const key = `${backupTimestamp}::${relativePath}`;
+  if (backedUpPaths.has(key)) return null;
+
+  const sourcePath = path.join(dest, relativePath);
+  if (!fs.existsSync(sourcePath)) return null;
+
+  const backupRoot = path.join(dest, '.sdd-backup', backupTimestamp);
+  const backupPath = path.join(backupRoot, relativePath);
+  try {
+    fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+    fs.copyFileSync(sourcePath, backupPath);
+    backedUpPaths.add(key);
+    return backupPath;
+  } catch (e) {
+    console.warn(`    ⚠ Backup of ${relativePath} failed: ${e.code || e.message}`);
+    return null;
+  }
+}
 
 /**
  * Read the installed SDD version from .sdd-version file.
@@ -195,7 +288,28 @@ function generateUpgrade(config) {
   const aiTools = config.aiTools;
   const projectType = config.projectType;
 
+  // v0.16.10: Reset per-run backup tracking and build a collision-safe timestamp.
+  // Every file replaced by this upgrade will be backed up to .sdd-backup/<ts>/
+  // before modification, so the user can always recover.
+  backedUpPaths.clear();
+  const backupTimestamp = buildBackupTimestamp();
+
+  // Track which template agents and AGENTS.md were preserved due to customization,
+  // so we can surface the list in the upgrade result summary.
+  const modifiedAgentsResults = [];
+
+  // v0.17.0: provenance tracking. Read existing hashes at the start; track
+  // new/updated hashes as we go. Preserved files leave their entry untouched
+  // (Codex M1 invariant: only write canonical hashes for tool-written content).
+  // `filesToAdapt` collects POSIX paths of files that were replaced or newly
+  // written in this run; applyStackAdaptations will be called with this
+  // allowlist after the write loop so only these files get re-adapted.
+  const meta = readMeta(dest);
+  const newHashes = { ...(meta?.hashes ?? {}) };
+  const filesToAdapt = new Set();
+
   console.log(`\nUpgrading SDD DevFlow in ${config.projectName}...\n`);
+  console.log(`  Backup directory: .sdd-backup/${backupTimestamp}/\n`);
 
   // --- a) Preserve user items ---
   const autonomy = readAutonomyLevel(dest);
@@ -219,8 +333,10 @@ function generateUpgrade(config) {
 
   for (const dir of toolDirs) {
     const base = path.join(dest, dir);
-    // Delete specific SDD-owned subdirectories (NOT commands for .claude)
-    for (const sub of ['agents', 'skills', 'hooks', 'styles']) {
+    // v0.16.10: we NO LONGER wholesale-delete agents/. The smart-diff loop below
+    // iterates TEMPLATE_AGENTS and preserves customized files individually.
+    // skills/hooks/styles remain SDD-owned with wholesale delete-and-replace.
+    for (const sub of ['skills', 'hooks', 'styles']) {
       const subDir = path.join(base, sub);
       if (fs.existsSync(subDir)) {
         fs.rmSync(subDir, { recursive: true, force: true });
@@ -240,19 +356,155 @@ function generateUpgrade(config) {
       for (const sub of ['agents', 'skills', 'hooks', 'styles', 'commands']) {
         const srcSub = path.join(templateToolDir, sub);
         const destSub = path.join(base, sub);
-        if (fs.existsSync(srcSub)) {
-          // For .claude/commands, merge: overwrite SDD template commands, preserve user's custom commands
-          if (dir === '.claude' && 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));
+        if (!fs.existsSync(srcSub)) continue;
+
+        // v0.16.10: smart-diff per template agent file (see Change #2 in
+        // /Users/pb/.claude/plans/validated-wobbling-blum.md).
+        //
+        // Invariant: this loop only processes files listed in TEMPLATE_AGENTS.
+        // Custom agents (files NOT in TEMPLATE_AGENTS) are left untouched on
+        // disk — they're also captured by collectCustomAgents earlier, so the
+        // existing restore loop at step (c) below will rewrite them from memory
+        // (redundant but harmless, same content).
+        if (sub === 'agents') {
+          fs.mkdirSync(destSub, { recursive: true });
+
+          const templateAgentFiles = fs
+            .readdirSync(srcSub, { withFileTypes: true })
+            .filter((e) => e.isFile() && TEMPLATE_AGENTS.includes(e.name))
+            .map((e) => e.name);
+
+          for (const file of templateAgentFiles) {
+            const templateAgentPath = path.join(srcSub, file);
+            const existingAgentPath = path.join(destSub, file);
+            const relativePath = path.relative(dest, existingAgentPath);
+            const posixPath = toPosix(relativePath);
+
+            const rawTemplate = fs.readFileSync(templateAgentPath, 'utf8');
+            const adaptedCoreTarget = adaptAgentContentString(rawTemplate, file, projectType);
+
+            // --- v0.17.0 decision tree ---
+            //
+            // Case 1: file missing or --force-template → unconditional write.
+            // Case 2: meta has a hash for this path → hash-based path.
+            //   2a. hash matches → pristine, replace with adaptedCoreTarget.
+            //   2b. hash mismatches → customized, preserve + .new backup.
+            //       IMPORTANT (Codex M1): do NOT update newHashes here.
+            // Case 3: no meta or no hash for this path → fallback path.
+            //   3a. Compute adaptedFullTarget by applying stack adaptations
+            //       in-memory so init-adapted files don't false-positive
+            //       (Gemini M1 fix).
+            //   3b. Content match → replace.
+            //   3c. Content mismatch → preserve + .new backup. Same Codex M1
+            //       rule: preserved files do NOT get a new hash.
+
+            if (!fs.existsSync(existingAgentPath)) {
+              // Missing — write fresh and track for stack adaptations.
+              fs.writeFileSync(existingAgentPath, adaptedCoreTarget, 'utf8');
+              filesToAdapt.add(posixPath);
+              replaced++;
+              continue;
             }
-          } else {
-            fs.cpSync(srcSub, destSub, { recursive: true });
+
+            if (config.forceTemplate) {
+              backupBeforeReplace(dest, relativePath, backupTimestamp);
+              fs.writeFileSync(existingAgentPath, adaptedCoreTarget, 'utf8');
+              filesToAdapt.add(posixPath);
+              replaced++;
+              continue;
+            }
+
+            const existingContent = fs.readFileSync(existingAgentPath, 'utf8');
+            const storedHash = meta && meta.hashes[posixPath];
+
+            const preserveFile = (target) => {
+              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, target, '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: do NOT update newHashes[posixPath]
+              // for preserved files. The existing hash (if any) persists.
+            };
+
+            if (storedHash) {
+              // Case 2: primary hash path.
+              const currentHash = computeHash(existingContent);
+              if (currentHash === storedHash) {
+                // Pristine — replace with core-adapted target. Stack
+                // adaptations will be applied via filesToAdapt after the
+                // smart-diff loop.
+                backupBeforeReplace(dest, relativePath, backupTimestamp);
+                fs.writeFileSync(existingAgentPath, adaptedCoreTarget, 'utf8');
+                filesToAdapt.add(posixPath);
+                replaced++;
+                continue;
+              }
+              // Hash mismatch → preserve. The .new backup target is the
+              // FULL adapted target (core + stack) so the user can diff
+              // apples to apples against their customized file.
+              const adaptedFullTarget = applyStackAdaptationsToContent(
+                adaptedCoreTarget,
+                posixPath,
+                scan,
+                config
+              );
+              preserveFile(adaptedFullTarget);
+              continue;
+            }
+
+            // Case 3: fallback path — no hash available. Compare against
+            // the FULL adapted target (core + stack) so init-adapted files
+            // from pre-v0.17.0 projects don't false-positive (Gemini M1).
+            const adaptedFullTargetFallback = applyStackAdaptationsToContent(
+              adaptedCoreTarget,
+              posixPath,
+              scan,
+              config
+            );
+
+            if (
+              normalizeForCompare(existingContent) ===
+              normalizeForCompare(adaptedFullTargetFallback)
+            ) {
+              // Pristine per content compare — replace with core target.
+              // Stack adaptations run after the loop to finalize the file.
+              backupBeforeReplace(dest, relativePath, backupTimestamp);
+              fs.writeFileSync(existingAgentPath, adaptedCoreTarget, 'utf8');
+              filesToAdapt.add(posixPath);
+              replaced++;
+              continue;
+            }
+
+            // Content mismatch → preserve. Same rule: no hash update.
+            preserveFile(adaptedFullTargetFallback);
+          }
+          continue;
+        }
+
+        // For .claude/commands, merge: overwrite SDD template commands, preserve user's custom commands
+        if (dir === '.claude' && 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));
           }
-          replaced++;
+        } else {
+          fs.cpSync(srcSub, destSub, { recursive: true });
         }
+        replaced++;
       }
 
       // Merge settings.json — strategy depends on the tool:
@@ -387,18 +639,82 @@ function generateUpgrade(config) {
   }
 
   // --- e) Replace top-level configs ---
-  // AGENTS.md
+  // AGENTS.md — hash-based smart-diff (v0.17.0 upgrade of v0.16.10 Change #3).
+  //
+  // Decision tree identical to the template-agent loop above:
+  //   1. Missing or --force-template → unconditional write.
+  //   2. meta has a hash for AGENTS.md → hash-based path:
+  //      2a. hash match → pristine, replace.
+  //      2b. hash mismatch → preserve + .new backup. Codex M1 invariant:
+  //          do NOT update newHashes['AGENTS.md'].
+  //   3. No hash → fallback content compare against the full adapted
+  //      target. AGENTS.md has no stack adaptations (adaptAgentsMd already
+  //      includes project-type pruning), so the comparison target is the
+  //      adaptAgentsMd output itself.
   const agentsMdTemplate = fs.readFileSync(path.join(templateDir, 'AGENTS.md'), 'utf8');
   const adaptedAgentsMd = adaptAgentsMd(agentsMdTemplate, config, scan);
-  fs.writeFileSync(path.join(dest, 'AGENTS.md'), adaptedAgentsMd, 'utf8');
-  replaced++;
+  const agentsMdDestPath = path.join(dest, 'AGENTS.md');
+  const AGENTS_MD_POSIX = 'AGENTS.md';
+
+  const preserveAgentsMd = () => {
+    backupBeforeReplace(dest, 'AGENTS.md', backupTimestamp);
+    const newBackupPath = path.join(dest, '.sdd-backup', backupTimestamp, 'AGENTS.md.new');
+    try {
+      fs.mkdirSync(path.dirname(newBackupPath), { recursive: true });
+      fs.writeFileSync(newBackupPath, adaptedAgentsMd, 'utf8');
+    } catch (e) {
+      console.warn(`    ⚠ Failed to write .new backup for AGENTS.md: ${e.code || e.message}`);
+    }
+    modifiedAgentsResults.push({ name: 'AGENTS.md', modified: true });
+    preserved++;
+    // Codex M1 invariant: do NOT update newHashes[AGENTS_MD_POSIX].
+  };
+
+  if (!fs.existsSync(agentsMdDestPath)) {
+    // Missing — write and hash fresh.
+    fs.writeFileSync(agentsMdDestPath, adaptedAgentsMd, 'utf8');
+    newHashes[AGENTS_MD_POSIX] = computeHash(adaptedAgentsMd);
+    replaced++;
+  } else if (config.forceTemplate) {
+    backupBeforeReplace(dest, 'AGENTS.md', backupTimestamp);
+    fs.writeFileSync(agentsMdDestPath, adaptedAgentsMd, 'utf8');
+    newHashes[AGENTS_MD_POSIX] = computeHash(adaptedAgentsMd);
+    replaced++;
+  } else {
+    const existingAgentsMd = fs.readFileSync(agentsMdDestPath, 'utf8');
+    const storedAgentsMdHash = meta && meta.hashes[AGENTS_MD_POSIX];
+
+    if (storedAgentsMdHash) {
+      const currentHash = computeHash(existingAgentsMd);
+      if (currentHash === storedAgentsMdHash) {
+        backupBeforeReplace(dest, 'AGENTS.md', backupTimestamp);
+        fs.writeFileSync(agentsMdDestPath, adaptedAgentsMd, 'utf8');
+        newHashes[AGENTS_MD_POSIX] = computeHash(adaptedAgentsMd);
+        replaced++;
+      } else {
+        preserveAgentsMd();
+      }
+    } else if (
+      normalizeForCompare(existingAgentsMd) === normalizeForCompare(adaptedAgentsMd)
+    ) {
+      // Fallback content-compare.
+      backupBeforeReplace(dest, 'AGENTS.md', backupTimestamp);
+      fs.writeFileSync(agentsMdDestPath, adaptedAgentsMd, 'utf8');
+      newHashes[AGENTS_MD_POSIX] = computeHash(adaptedAgentsMd);
+      replaced++;
+    } else {
+      preserveAgentsMd();
+    }
+  }
 
-  // CLAUDE.md / GEMINI.md
+  // CLAUDE.md / GEMINI.md (back up before replace, not smart-diff'd)
   if (aiTools !== 'gemini') {
+    backupBeforeReplace(dest, 'CLAUDE.md', backupTimestamp);
     fs.copyFileSync(path.join(templateDir, 'CLAUDE.md'), path.join(dest, 'CLAUDE.md'));
     replaced++;
   }
   if (aiTools !== 'claude') {
+    backupBeforeReplace(dest, 'GEMINI.md', backupTimestamp);
     fs.copyFileSync(path.join(templateDir, 'GEMINI.md'), path.join(dest, 'GEMINI.md'));
     replaced++;
   }
@@ -448,6 +764,35 @@ function generateUpgrade(config) {
     replaced++;
   }
 
+  // --- e3) .gitignore — idempotent append of .sdd-backup/ (v0.16.10)
+  //          and .sdd-meta.json (v0.17.0) ---
+  // Existing projects created before these versions don't have the
+  // entries in their .gitignore. Append them once so the files aren't
+  // accidentally committed.
+  const userGitignorePath = path.join(dest, '.gitignore');
+  if (fs.existsSync(userGitignorePath)) {
+    let existingGitignore = fs.readFileSync(userGitignorePath, 'utf8');
+    let updatedGitignore = false;
+
+    if (!/^\s*\/?\.sdd-backup\/?\s*$/m.test(existingGitignore)) {
+      const appendBlock = '\n\n# sdd-devflow upgrade backups (ignored — kept locally for recovery only)\n.sdd-backup/\n';
+      existingGitignore = existingGitignore.trimEnd() + appendBlock;
+      updatedGitignore = true;
+      step('Updated .gitignore with .sdd-backup/ entry');
+    }
+
+    if (!/^\s*\/?\.sdd-meta\.json\s*$/m.test(existingGitignore)) {
+      const appendBlock = '\n\n# sdd-devflow provenance tracking (local-only, content-addressable hashes)\n.sdd-meta.json\n';
+      existingGitignore = existingGitignore.trimEnd() + appendBlock;
+      updatedGitignore = true;
+      step('Updated .gitignore with .sdd-meta.json entry');
+    }
+
+    if (updatedGitignore) {
+      fs.writeFileSync(userGitignorePath, existingGitignore, 'utf8');
+    }
+  }
+
   // --- f) Adapt for project type ---
   // Remove agents for single-stack projects
   if (projectType === 'backend') {
@@ -468,30 +813,33 @@ function generateUpgrade(config) {
     }
   }
 
-  // Adapt agent/skill content for project type
+  // Adapt agent/skill content for project type (single-stack pruning —
+  // removes frontend/backend refs). Separate from stack substitutions
+  // (Zod/ORM/DDD). Safe to run on all files because the pruning rules
+  // use literal template strings that only appear in raw template.
   if (projectType !== 'fullstack') {
     adaptAgentContentForProjectType(dest, config, regexReplaceInFile);
   }
 
-  // Adapt copied files for detected stack (Zod, Prisma, DDD, etc.)
-  adaptCopiedFiles(dest, scan, config);
-
-  // Adapt documentation-standards for project type
-  const docStdPath2 = path.join(dest, 'ai-specs', 'specs', 'documentation-standards.mdc');
-  if (fs.existsSync(docStdPath2)) {
-    if (projectType === 'backend') {
-      regexReplaceInFile(docStdPath2, [
-        [/\| `ai-specs\/specs\/frontend-standards\.mdc` \|[^\n]*\n/, ''],
-        [/\| `docs\/specs\/ui-components\.md` \|[^\n]*\n/, ''],
-        [/   - UI component changes → `docs\/specs\/ui-components\.md`\n/, ''],
-      ]);
-    } else if (projectType === 'frontend') {
-      regexReplaceInFile(docStdPath2, [
-        [/\| `ai-specs\/specs\/backend-standards\.mdc` \|[^\n]*\n/, ''],
-        [/\| `docs\/specs\/api-spec\.yaml` \|[^\n]*\n/, ''],
-      ]);
-    }
+  // v0.17.0: Stack adaptations run ONLY on files that were replaced or
+  // newly written in this run. Preserved (customized) files MUST NOT be
+  // touched by stack adaptations, otherwise their user edits could be
+  // mangled by the rule replacements (Codex M1 + plan v1.1 § Allowlist
+  // semantics).
+  //
+  // SKILL.md, ticket-template.md, and documentation-standards.mdc were
+  // wholesale-recopied earlier in the upgrade (via fs.cpSync and the
+  // standards pipeline), so they are always in the "replaced" state and
+  // must be in the allowlist.
+  for (const dir of toolDirs) {
+    filesToAdapt.add(toPosix(`${dir}/skills/development-workflow/SKILL.md`));
+    filesToAdapt.add(
+      toPosix(`${dir}/skills/development-workflow/references/ticket-template.md`)
+    );
   }
+  filesToAdapt.add(toPosix('ai-specs/specs/documentation-standards.mdc'));
+
+  applyStackAdaptations(dest, scan, config, filesToAdapt);
 
   step('Adapted files for project type and stack');
 
@@ -527,6 +875,32 @@ function generateUpgrade(config) {
   fs.writeFileSync(path.join(dest, '.sdd-version'), newVersion + '\n', 'utf8');
   step(`Updated .sdd-version to ${newVersion}`);
 
+  // --- g1) v0.17.0: update .sdd-meta.json ---
+  //
+  // For every smart-diff-tracked file that was replaced or newly written
+  // in this run (i.e. in filesToAdapt AND in the expected tracked set),
+  // recompute its hash from the post-adaptation on-disk content and merge
+  // into newHashes. Preserved files are NOT in filesToAdapt, so their old
+  // hash (if any) is left alone — Codex M1 invariant.
+  //
+  // Then prune hashes for paths that are no longer expected for this
+  // (aiTools, projectType) combination (e.g. single-stack removed a
+  // frontend agent). User-deleted files that ARE expected keep their
+  // hash, since the next upgrade will recreate the file from template.
+  {
+    const trackedSet = expectedSmartDiffTrackedPaths(aiTools, projectType);
+    for (const posixPath of filesToAdapt) {
+      if (!trackedSet.has(posixPath)) continue;
+      const absPath = path.join(dest, ...posixPath.split('/'));
+      const h = hashFileOnDisk(absPath);
+      if (h !== null) {
+        newHashes[posixPath] = h;
+      }
+    }
+    const prunedHashes = pruneExpectedAbsent(newHashes, aiTools, projectType);
+    writeMeta(dest, prunedHashes);
+  }
+
   // --- Show result ---
   const updatedCount = standardsResults.filter((s) => !s.modified).length;
   const preservedCount = modifiedStandards.length;
@@ -551,6 +925,37 @@ function generateUpgrade(config) {
     }
   }
 
+  if (modifiedAgentsResults.length > 0) {
+    console.log(
+      `\n  ⚠ Review preserved customizations (backups in .sdd-backup/${backupTimestamp}/):`
+    );
+    for (const r of modifiedAgentsResults) {
+      console.log(
+        `    - ${r.name} (not updated; new adapted version saved as ${r.name}.new)`
+      );
+    }
+    console.log(
+      `\n    Note: this is EXPECTED on cross-version upgrades (e.g. ${config.installedVersion} → ${newVersion}).`
+    );
+    console.log(
+      `    v0.16.10 uses conservative preserve semantics — any file that does not exactly`
+    );
+    console.log(
+      `    match the new template's adapted output is preserved, even if you never edited it.`
+    );
+    console.log(
+      `    Provenance tracking (v0.17.0) will eliminate these false positives.`
+    );
+    console.log(`\n    If you have NOT customized these files:`);
+    console.log(
+      `      → re-run with --force-template to accept the new template content in bulk`
+    );
+    console.log(`\n    If you HAVE customized these files:`);
+    console.log(
+      `      → diff .sdd-backup/${backupTimestamp}/<path>.new against your file and merge manually`
+    );
+  }
+
   console.log(`\nNext: git add -A && git commit -m "chore: upgrade SDD DevFlow to ${newVersion}"\n`);
 }
 

package/package.json

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

package/template/.claude/agents/backend-planner.md

@@ -78,9 +78,9 @@ List every empirical check you executed using this format: `<command> → <obser
 
 Example format:
 
-- `Grep: "PortionContext" in packages/` → 2 hits: `shared/src/schemas/enums.ts:18`, `shared/src/schemas/standardPortion.ts:4` → both must be deleted in the migration commit, listed under "Files to Modify"
-- `Read: packages/api/prisma/schema.prisma:318-330` → confirmed `dishId String @db.Uuid` (not int) → Seed CSV validator must use `z.string().uuid()`, NOT `z.number().int()`
-- `Grep: "formatPortionTermLabel" in packages/shared/` → helper does not yet exist → list under "Files to Create" for commit 1 of the TDD order
+- `Grep: "Status" in src/` → 2 hits: `src/domain/order.ts:14`, `src/schemas/enums.ts:8` → both must be updated in the same commit as the migration, listed under "Files to Modify"
+- `Read: prisma/schema.prisma:45-60` → confirmed `id String @id @default(cuid())` → validator uses `z.string().cuid()`, NOT `z.string().uuid()` or `z.number().int()`
+- `Grep: "formatStatusLabel" in src/` → helper does not yet exist → list under "Files to Create" before commits that depend on it
 - (continue with every empirical check)
 
 **If this subsection is empty or missing**, prepend the plan with a warning: `⚠ This plan is text-only and has not been empirically verified against the code. Cross-model reviewers MUST run empirical checks before approving.`

package/template/.claude/agents/frontend-planner.md

@@ -78,9 +78,9 @@ List every empirical check using this format: `<command> → <observed fact> →
 
 Example format:
 
-- `Grep: "formatPortionTermLabel" in packages/` → helper exists in `packages/shared/src/portion/portionLabel.ts:32` → do not duplicate inline, import from `@foodxplorer/shared`, list under "Existing Code to Reuse"
-- `Read: packages/shared/src/schemas/estimate.ts:180-205` → confirmed `portionAssumption` field is optional with `source: "per_dish" | "generic"` → NutritionCard must handle both branches, listed under "Key Patterns"
-- `Grep: "aria-labelledby" in packages/web/src/components/` → existing pattern uses `useId()` for hook-generated IDs → reuse same pattern in new component, not hardcoded strings
+- `Grep: "formatStatusLabel" in src/` → helper exists in `src/shared/format.ts:32` → do not duplicate inline, import from shared, list under "Existing Code to Reuse"
+- `Read: src/schemas/order.ts:40-60` → confirmed `status` field is `z.enum([...])` with 4 variants → UI must handle all branches, listed under "Key Patterns"
+- `Grep: "aria-labelledby" in src/components/` → existing pattern uses `useId()` for hook-generated IDs → reuse same pattern in new component, not hardcoded strings
 - (continue with every empirical check)
 
 **If this subsection is empty or missing**, prepend the plan with a warning: `⚠ This plan is text-only and has not been empirically verified against the code. Cross-model reviewers MUST run empirical checks before approving.`

package/template/.gemini/agents/backend-planner.md

@@ -45,8 +45,8 @@ Required checks:
 
 Append to the ticket a final subsection `### Verification commands run`. Use this exact 3-field format per entry: `<command> → <observed fact> → <impact on plan>`. Every entry must have all three fields — a bare command without an observed fact is not verification. Example:
 
-- `Grep: "PortionContext" in packages/` → 2 hits (`enums.ts:18`, `standardPortion.ts:4`) → both must be deleted in the migration commit
-- `Read: packages/api/prisma/schema.prisma:323` → `dishId String @db.Uuid` (not int) → validator uses `z.string().uuid()`
+- `Grep: "Status" in src/` → 2 hits (`src/domain/order.ts:14`, `src/schemas/enums.ts:8`) → both must be updated in the same commit as the migration
+- `Read: prisma/schema.prisma:45-60` → `id String @id @default(cuid())` → validator uses `z.string().cuid()`, NOT `z.string().uuid()` or `z.number().int()`
 
 If the subsection is empty or missing, prepend the plan with `⚠ This plan is text-only and has not been empirically verified. Cross-model reviewers MUST run empirical checks.`
 

package/template/.gemini/agents/frontend-planner.md

@@ -40,15 +40,15 @@ Before emitting the final plan, verify every structural claim empirically agains
 Required checks:
 
 1. Grep or read every file you cite — confirm path exists
-2. Before proposing an inline helper, grep `packages/shared/` for an existing equivalent. Helpers used by BOTH web and bot MUST live in `shared/` and be imported; do NOT duplicate inline per package
+2. Before proposing an inline helper, grep shared/utility directories for an existing equivalent. Helpers used across features MUST live in a shared location and be imported; do NOT duplicate inline
 3. Read the shared validation schema for any API response the frontend renders. Frontend MUST match the backend contract, not invent fields
 4. Verify CSS tokens and component primitives exist before proposing new classes. Design tokens live in `tailwind.config.ts` or `globals.css`, not in component files
 5. Verify accessibility semantics (`aria-*`, role, labelled-by) against existing accessible components in the codebase
 
 Append to the ticket a final subsection `### Verification commands run`. Use this exact 3-field format per entry: `<command> → <observed fact> → <impact on plan>`. Every entry must have all three fields. Example:
 
-- `Grep: "formatPortionTermLabel" in packages/` → helper exists in `packages/shared/src/portion/portionLabel.ts:32` → import from `@foodxplorer/shared`, do not duplicate
-- `Read: packages/shared/src/schemas/estimate.ts:180-205` → `portionAssumption` is optional with `source: "per_dish" | "generic"` → component handles both branches
+- `Grep: "formatStatusLabel" in src/` → helper exists in `src/shared/format.ts:32` → import from shared, do not duplicate
+- `Read: src/schemas/order.ts:40-60` → `status` field is `z.enum([...])` with 4 variants → component handles all branches
 
 If empty or missing, prepend plan with `⚠ This plan is text-only and has not been empirically verified. Cross-model reviewers MUST run empirical checks.`
 

package/template/gitignore

@@ -50,3 +50,9 @@ npm-debug.log*
 # SDD PM Orchestrator (ephemeral session control files)
 docs/project_notes/pm-session.lock
 docs/project_notes/pm-stop.md
+
+# sdd-devflow upgrade backups (ignored — kept locally for recovery only)
+.sdd-backup/
+
+# sdd-devflow provenance tracking (local-only, content-addressable hashes)
+.sdd-meta.json