create-sdd-project 0.16.9 → 0.16.10

package/bin/cli.js

@@ -11,6 +11,7 @@ const isInit = args.includes('--init');
 const isUpgrade = args.includes('--upgrade');
 const isDoctor = args.includes('--doctor');
 const isForce = args.includes('--force');
+const isForceTemplate = args.includes('--force-template');
 const isEject = args.includes('--eject');
 const isDiff = args.includes('--diff');
 
@@ -185,6 +186,7 @@ async function runUpgrade() {
   config.autonomyLevel = autonomy.level;
   config.autonomyName = autonomy.name;
   config.installedVersion = installedVersion;
+  config.forceTemplate = isForceTemplate;
 
   // Build and show summary
   const state = {

package/lib/adapt-agents.js

@@ -2,10 +2,114 @@
 
 const path = require('path');
 
+/**
+ * Per-agent-file adaptation rules for single-stack projects.
+ *
+ * For each projectType ('backend' or 'frontend'), maps filename to a list of
+ * [search, replace] tuples applied in order. When `search` is a RegExp, uses
+ * .replace(); when it's a string, uses split/join to replace all occurrences.
+ *
+ * These rules ONLY apply to files under .claude/agents/ or .gemini/agents/.
+ * Skill and template file adaptations live in the I/O wrapper below because
+ * they don't need the pure function (they're not used by upgrade smart-diff).
+ *
+ * fullstack projectType has no rules — templates ship in fullstack-ready form.
+ */
+const AGENT_ADAPTATION_RULES = {
+  backend: {
+    'spec-creator.md': [
+      [/### Frontend Specifications\n(?:- [^\n]*\n)+\n/, ''],
+      [/### For UI Changes\n```markdown\n(?:[^\n]*\n)*?```\n\n/, ''],
+      ['Data Model Changes, UI Changes, Edge Cases', 'Data Model Changes, Edge Cases'],
+      ['(`api-spec.yaml`, `ui-components.md`)', '(`api-spec.yaml`)'],
+      // Gemini agents have different text patterns (also applied to Claude; no-op if no match):
+      [/\(api-spec\.yaml, ui-components\.md\)/, '(api-spec.yaml)'],
+    ],
+    'production-code-validator.md': [
+      [/- Components exported\/used that are NOT listed in `docs\/specs\/ui-components\.md`\n/, ''],
+      [/,? components not in ui-components\.md/, ''],
+      [/\.? ?Check components vs `ui-components\.md`/, ''],
+    ],
+    'code-review-specialist.md': [
+      ['(`backend-standards.mdc` / `frontend-standards.mdc`)', '(`backend-standards.mdc`)'],
+      ['(`api-spec.yaml`, `ui-components.md`)', '(`api-spec.yaml`)'],
+    ],
+    'qa-engineer.md': [
+      ['(`api-spec.yaml`, `ui-components.md`)', '(`api-spec.yaml`)'],
+      [/- Frontend: `cd frontend && npm test`\n/, ''],
+      [/- \*\*Frontend\*\*: Write tests for error states[^\n]*\n/, ''],
+      ['`backend-standards.mdc` / `frontend-standards.mdc`', '`backend-standards.mdc`'],
+      ['`backend-standards.mdc` and/or `frontend-standards.mdc`', '`backend-standards.mdc`'],
+      [/ and\/or `(?:ai-specs\/specs\/)?frontend-standards\.mdc`/, ''],
+    ],
+  },
+  frontend: {
+    'spec-creator.md': [
+      [/### Backend Specifications\n(?:- [^\n]*\n)+\n/, ''],
+      [/### For API Changes\n```yaml\n(?:[^\n]*\n)*?```\n\n/, ''],
+      ['(`api-spec.yaml`, `ui-components.md`)', '(`ui-components.md`)'],
+      [/\(api-spec\.yaml, ui-components\.md\)/, '(ui-components.md)'],
+    ],
+    'code-review-specialist.md': [
+      ['(`backend-standards.mdc` / `frontend-standards.mdc`)', '(`frontend-standards.mdc`)'],
+      ['(`api-spec.yaml`, `ui-components.md`)', '(`ui-components.md`)'],
+    ],
+    'qa-engineer.md': [
+      ['(`api-spec.yaml`, `ui-components.md`)', '(`ui-components.md`)'],
+      [/- Backend: `cd backend && npm test`\n/, ''],
+      [/- \*\*Backend\*\*: Write tests for error paths[^\n]*\n/, ''],
+      ['`backend-standards.mdc` / `frontend-standards.mdc`', '`frontend-standards.mdc`'],
+      ['`backend-standards.mdc` and/or `frontend-standards.mdc`', '`frontend-standards.mdc`'],
+      [/`(?:ai-specs\/specs\/)?backend-standards\.mdc` and\/or /, ''],
+    ],
+  },
+};
+
+/**
+ * Pure function — apply single-stack adaptation rules to an agent file's content.
+ *
+ * Used by both the I/O wrapper below AND by upgrade-generator.js smart-diff
+ * (v0.16.10+) to compute what the "pristine adapted target" should be for a
+ * given (rawTemplate, filename, projectType) tuple. The smart-diff compares
+ * the user's current file against this value — if they match, the user hasn't
+ * customized and the upgrade can safely replace.
+ *
+ * @param {string} content - Raw template content
+ * @param {string} filename - Agent file basename (e.g. 'spec-creator.md')
+ * @param {string} projectType - 'fullstack' | 'backend' | 'frontend'
+ * @returns {string} - Adapted content (or unchanged if no rules apply)
+ */
+function adaptAgentContentString(content, filename, projectType) {
+  if (projectType === 'fullstack') return content;
+
+  const rulesForType = AGENT_ADAPTATION_RULES[projectType];
+  if (!rulesForType) return content;
+
+  const rules = rulesForType[filename];
+  if (!rules) return content;
+
+  let result = content;
+  for (const [search, replace] of rules) {
+    if (search instanceof RegExp) {
+      result = result.replace(search, replace);
+    } else {
+      result = result.split(search).join(replace);
+    }
+  }
+  return result;
+}
+
 /**
  * Shared agent/skill content adaptation for single-stack projects.
  * Used by both generator.js (new projects) and init-generator.js (--init).
  *
+ * As of v0.16.10, delegates per-agent-file transformations to the pure
+ * adaptAgentContentString() function so upgrade-generator.js smart-diff can
+ * share the same rules. Skill and template file adaptations (SKILL.md,
+ * ticket-template.md, pr-template.md, AGENTS.md ui-ux-designer removal,
+ * base-standards.mdc cleanup) remain inline because they're not needed by
+ * smart-diff.
+ *
  * @param {string} dest - Destination directory
  * @param {object} config - Config with projectType and aiTools
  * @param {function} replaceInFileFn - Function(filePath, replacements) to perform replacements
@@ -15,71 +119,20 @@ function adaptAgentContentForProjectType(dest, config, replaceInFileFn) {
   if (config.aiTools !== 'gemini') toolDirs.push('.claude');
   if (config.aiTools !== 'claude') toolDirs.push('.gemini');
 
-  if (config.projectType === 'backend') {
-    for (const dir of toolDirs) {
-      // spec-creator: remove Frontend Specifications section, UI output format, ui-components refs
-      replaceInFileFn(path.join(dest, dir, 'agents', 'spec-creator.md'), [
-        [/### Frontend Specifications\n(?:- [^\n]*\n)+\n/, ''],
-        [/### For UI Changes\n```markdown\n(?:[^\n]*\n)*?```\n\n/, ''],
-        ['Data Model Changes, UI Changes, Edge Cases', 'Data Model Changes, Edge Cases'],
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`api-spec.yaml`)'],
-      ]);
-      // production-code-validator: remove ui-components line from Spec Drift
-      replaceInFileFn(path.join(dest, dir, 'agents', 'production-code-validator.md'), [
-        [/- Components exported\/used that are NOT listed in `docs\/specs\/ui-components\.md`\n/, ''],
-      ]);
-      // code-review-specialist: backend-only standards ref, remove ui-components
-      replaceInFileFn(path.join(dest, dir, 'agents', 'code-review-specialist.md'), [
-        ['(`backend-standards.mdc` / `frontend-standards.mdc`)', '(`backend-standards.mdc`)'],
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`api-spec.yaml`)'],
-      ]);
-      // qa-engineer: remove frontend refs, adapt standards refs
-      replaceInFileFn(path.join(dest, dir, 'agents', 'qa-engineer.md'), [
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`api-spec.yaml`)'],
-        [/- Frontend: `cd frontend && npm test`\n/, ''],
-        [/- \*\*Frontend\*\*: Write tests for error states[^\n]*\n/, ''],
-        ['`backend-standards.mdc` / `frontend-standards.mdc`', '`backend-standards.mdc`'],
-        ['`backend-standards.mdc` and/or `frontend-standards.mdc`', '`backend-standards.mdc`'],
-        [/ and\/or `(?:ai-specs\/specs\/)?frontend-standards\.mdc`/, ''],
-      ]);
-    }
-  } else if (config.projectType === 'frontend') {
+  // --- Agent file adaptations (delegate to pure function) ---
+  const rulesForType = AGENT_ADAPTATION_RULES[config.projectType];
+  if (rulesForType) {
     for (const dir of toolDirs) {
-      // spec-creator: remove Backend Specifications section, api-spec refs
-      replaceInFileFn(path.join(dest, dir, 'agents', 'spec-creator.md'), [
-        [/### Backend Specifications\n(?:- [^\n]*\n)+\n/, ''],
-        [/### For API Changes\n```yaml\n(?:[^\n]*\n)*?```\n\n/, ''],
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`ui-components.md`)'],
-      ]);
-      // code-review-specialist: frontend-only standards ref
-      replaceInFileFn(path.join(dest, dir, 'agents', 'code-review-specialist.md'), [
-        ['(`backend-standards.mdc` / `frontend-standards.mdc`)', '(`frontend-standards.mdc`)'],
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`ui-components.md`)'],
-      ]);
-      // qa-engineer: remove backend refs, adapt standards refs
-      replaceInFileFn(path.join(dest, dir, 'agents', 'qa-engineer.md'), [
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`ui-components.md`)'],
-        [/- Backend: `cd backend && npm test`\n/, ''],
-        [/- \*\*Backend\*\*: Write tests for error paths[^\n]*\n/, ''],
-        ['`backend-standards.mdc` / `frontend-standards.mdc`', '`frontend-standards.mdc`'],
-        ['`backend-standards.mdc` and/or `frontend-standards.mdc`', '`frontend-standards.mdc`'],
-        [/`(?:ai-specs\/specs\/)?backend-standards\.mdc` and\/or /, ''],
-      ]);
+      for (const [filename, rules] of Object.entries(rulesForType)) {
+        replaceInFileFn(path.join(dest, dir, 'agents', filename), rules);
+      }
     }
   }
 
-  // Skills and templates: remove frontend/backend-specific references
+  // --- Skills and templates: remove frontend/backend-specific references ---
+  // These stay inline — they're not agent files, so not needed by upgrade smart-diff.
   if (config.projectType === 'backend') {
     for (const dir of toolDirs) {
-      // Gemini agents have different text patterns for spec-creator
-      replaceInFileFn(path.join(dest, dir, 'agents', 'spec-creator.md'), [
-        [/\(api-spec\.yaml, ui-components\.md\)/, '(api-spec.yaml)'],
-        ['Data Model Changes, UI Changes, Edge Cases', 'Data Model Changes, Edge Cases'],
-      ]);
-      replaceInFileFn(path.join(dest, dir, 'agents', 'production-code-validator.md'), [
-        [/,? components not in ui-components\.md/, ''],
-        [/\.? ?Check components vs `ui-components\.md`/, ''],
-      ]);
       // SKILL.md: remove ui-components references and design review step
       replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'SKILL.md'), [
         [/,? `ui-components\.md`\)/, ')'],
@@ -106,9 +159,6 @@ function adaptAgentContentForProjectType(dest, config, replaceInFileFn) {
     ]);
   } else if (config.projectType === 'frontend') {
     for (const dir of toolDirs) {
-      replaceInFileFn(path.join(dest, dir, 'agents', 'spec-creator.md'), [
-        [/\(api-spec\.yaml, ui-components\.md\)/, '(ui-components.md)'],
-      ]);
       replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'SKILL.md'), [
         [/`api-spec\.yaml`,? /, ''],
         [/- API endpoints → `docs\/specs\/api-spec\.yaml` \(MANDATORY\)\n/, ''],
@@ -124,4 +174,8 @@ function adaptAgentContentForProjectType(dest, config, replaceInFileFn) {
   }
 }
 
-module.exports = { adaptAgentContentForProjectType };
+module.exports = {
+  adaptAgentContentForProjectType,
+  adaptAgentContentString,
+  AGENT_ADAPTATION_RULES,
+};

package/lib/doctor.js

@@ -76,6 +76,9 @@ function runDoctor(cwd) {
   // 13. Gemini TOML Commands Format
   results.push(checkGeminiCommands(cwd, aiTools));
 
+  // 14. AGENTS.md Standards References (v0.16.10)
+  results.push(checkAgentsMdStandardsRefs(cwd));
+
   return results;
 }
 
@@ -940,6 +943,76 @@ function checkGeminiCommands(cwd, aiTools) {
   };
 }
 
+/**
+ * Check #14 (v0.16.10): detect adapter-failure artifacts in AGENTS.md.
+ *
+ * The specific broken state seen in foodXPlorer after the v0.16.9 upgrade
+ * was `Standards References` containing `"Backend patterns ()"` — empty
+ * parens left behind after the template substitution failed. This check
+ * looks for that pattern plus any unsubstituted placeholders of the shape
+ * `[Something]` that don't match a known-good markdown link.
+ *
+ * Severity: WARN — an empty-parens AGENTS.md doesn't break the project,
+ * it just leaves the agents without full stack context.
+ */
+function checkAgentsMdStandardsRefs(cwd) {
+  const agentsMdPath = path.join(cwd, 'AGENTS.md');
+  if (!fs.existsSync(agentsMdPath)) {
+    return {
+      status: WARN,
+      message: 'AGENTS.md: missing',
+      details: ['Run: npx create-sdd-project --upgrade to recreate'],
+    };
+  }
+
+  const content = fs.readFileSync(agentsMdPath, 'utf8');
+  const issues = [];
+
+  // Detect adapter failure: "Backend patterns ()" or "Frontend patterns ()"
+  const emptyParensMatch = content.match(/(?:Backend|Frontend) patterns \(\s*\)/g);
+  if (emptyParensMatch) {
+    issues.push(
+      `Adapter failure: ${emptyParensMatch.join(', ')} (empty parens after template substitution)`
+    );
+  }
+
+  // Detect unsubstituted placeholders that look like "[Framework, runtime, version]".
+  // Template placeholders are distinctive: (a) they contain at least one
+  // comma-separated descriptor or the literal word "your", (b) they are NOT
+  // the target of a markdown link (no `(` or `:` immediately after the `]`).
+  //
+  // Gemini cross-model review (v0.16.10) caught the original broad regex
+  // /\[[A-Z][^\]]{5,60}\]/g catching legitimate user-added markdown links
+  // like `[Architecture Doc](./docs/arch.md)`. AGENTS.md is explicitly meant
+  // to be user-customized, so the doctor must not warn on every link.
+  //
+  // Match only placeholder-shaped strings that are followed by whitespace,
+  // end-of-line, or punctuation (not `(` for a link target or `:` for a
+  // footnote reference), AND contain either a comma or the word "your" or
+  // "example" to distinguish them from section headers.
+  const PLACEHOLDER_RE = /\[[A-Z][^\]]{3,60}[,\s](?:[^\]]{0,60})\](?!\(|:)/g;
+  const HINT_WORDS_RE = /\b(?:your|example|framework|runtime|version|name|path)\b/i;
+  const candidates = content.match(PLACEHOLDER_RE) || [];
+  const unsubstituted = candidates.filter((c) => HINT_WORDS_RE.test(c));
+  if (unsubstituted.length > 0) {
+    issues.push(`Unsubstituted placeholders: ${unsubstituted.slice(0, 3).join(', ')}`);
+  }
+
+  if (issues.length > 0) {
+    return {
+      status: WARN,
+      message: `AGENTS.md: ${issues.length} issue${issues.length > 1 ? 's' : ''}`,
+      details: [...issues, 'Run: npx create-sdd-project --upgrade --force to re-adapt'],
+    };
+  }
+
+  return {
+    status: PASS,
+    message: 'AGENTS.md: standards references valid',
+    details: [],
+  };
+}
+
 module.exports = {
   runDoctor,
   printResults,

package/lib/init-generator.js

@@ -746,54 +746,75 @@ function findSrcRootName(scan) {
 function adaptAgentsMd(template, config, scan) {
   let content = template;
 
-  // Replace project structure with actual directories
-  const rootDirs = scan.rootDirs;
-  const tree = rootDirs.map((d) => `├── ${d.replace(/\/$/, '/')}   `).join('\n');
-  const treeBlock = `\`\`\`\nproject/\n${tree}\n└── docs/        ← Documentation\n\`\`\``;
-
-  // Robust: flexible whitespace between CONFIG comment and code block
-  content = content.replace(
-    /<!-- CONFIG: Adjust directories[^>]*-->\n+```\nproject\/\n[\s\S]*?```/,
-    treeBlock
-  );
-
-  // If not monorepo, simplify the install instructions
-  // Robust: match any number of table rows (not hardcoded count)
-  if (!scan.isMonorepo) {
+  // v0.16.10: guard every replacement against an empty/unhelpful scan.
+  // The previous version unconditionally rewrote the project tree and the
+  // Standards References line, which produced broken output like
+  // `Backend patterns ()` (empty parens) when the scanner couldn't detect a
+  // framework. That was the root cause of the foodXPlorer v0.16.9 regression.
+  // Now each replacement only runs when the scan produced enough information
+  // to improve on the template defaults; otherwise the template stays.
+
+  // Replace project structure with actual directories — only when the scanner
+  // detected at least one meaningful (non-SDD-infrastructure) directory.
+  const rootDirs = scan.rootDirs || [];
+  const meaningfulDirs = rootDirs.filter((d) => {
+    const norm = d.replace(/\/$/, '');
+    return norm !== 'docs' && norm !== 'ai-specs';
+  });
+  if (meaningfulDirs.length > 0) {
+    const tree = rootDirs.map((d) => `├── ${d.replace(/\/$/, '/')}   `).join('\n');
+    const treeBlock = `\`\`\`\nproject/\n${tree}\n└── docs/        ← Documentation\n\`\`\``;
     content = content.replace(
-      /\*\*Critical\*\*: NEVER install dependencies in the root directory\.\n\n(\|.*\n)+/,
-      ''
+      /<!-- CONFIG: Adjust directories[^>]*-->\n+```\nproject\/\n[\s\S]*?```/,
+      treeBlock
     );
+
+    // If not monorepo, simplify the install instructions (only when we
+    // actually rewrote the tree, otherwise leave the template alone).
+    if (!scan.isMonorepo) {
+      content = content.replace(
+        /\*\*Critical\*\*: NEVER install dependencies in the root directory\.\n\n(\|.*\n)+/,
+        ''
+      );
+    }
   }
 
-  // Adapt Standards References descriptions
-  if (scan.backend.detected) {
-    const parts = [scan.srcStructure.pattern ? patternLabelFor(scan.srcStructure.pattern) : null, scan.backend.framework, scan.backend.orm].filter(Boolean);
-    content = content.replace(
-      'Backend patterns (DDD, Express, Prisma)',
-      `Backend patterns (${parts.join(', ')})`
-    );
+  // Adapt Backend Standards description — only when we have enough stack info
+  // to build a non-empty parenthetical. Otherwise leave the template default.
+  if (scan.backend && scan.backend.detected) {
+    const parts = [
+      scan.srcStructure && scan.srcStructure.pattern ? patternLabelFor(scan.srcStructure.pattern) : null,
+      scan.backend.framework,
+      scan.backend.orm,
+    ].filter(Boolean);
+    if (parts.length > 0) {
+      content = content.replace(
+        'Backend patterns (DDD, Express, Prisma)',
+        `Backend patterns (${parts.join(', ')})`
+      );
+    }
   }
-  if (scan.frontend.detected) {
+
+  if (scan.frontend && scan.frontend.detected) {
     const parts = [scan.frontend.framework, scan.frontend.styling, scan.frontend.components].filter(Boolean);
-    content = content.replace(
-      'Frontend patterns (Next.js, Tailwind, Radix)',
-      `Frontend patterns (${parts.join(', ')})`
-    );
-  } else {
-    // Remove frontend-standards reference for backend-only projects
-    content = content.replace(
-      /- \[Frontend Standards\].*\n/,
-      ''
-    );
+    if (parts.length > 0) {
+      content = content.replace(
+        'Frontend patterns (Next.js, Tailwind, Radix)',
+        `Frontend patterns (${parts.join(', ')})`
+      );
+    }
   }
 
-  if (!scan.backend.detected) {
-    // Remove backend-standards reference for frontend-only projects
-    content = content.replace(
-      /- \[Backend Standards\].*\n/,
-      ''
-    );
+  // Standards-links pruning: use the authoritative `config.projectType`
+  // instead of scanner detection. Scanner is unreliable on freshly-scaffolded
+  // projects (no real source code yet) and would cause cross-path drift
+  // between scaffold and upgrade. config.projectType comes from user choice
+  // at scaffold time or detectProjectType() at upgrade time (which reads
+  // from existing files, not source patterns).
+  if (config && config.projectType === 'backend') {
+    content = content.replace(/- \[Frontend Standards\].*\n/, '');
+  } else if (config && config.projectType === 'frontend') {
+    content = content.replace(/- \[Backend Standards\].*\n/, '');
   }
 
   return content;

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,
@@ -22,6 +25,87 @@ const {
   regexReplaceInFile,
 } = require('./init-generator');
 
+// --- 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. Strips trailing whitespace
+ * from each line, normalizes CRLF/CR to LF, and trims leading/trailing
+ * blank lines. Prevents false-positive "customized" flags on Windows
+ * systems where git's `core.autocrlf=true` rewrites line endings to
+ * `\r\n` on checkout while our template reads as `\n`. Also tolerates
+ * editors that add/strip trailing whitespace.
+ */
+function normalizeForCompare(text) {
+  return text
+    .replace(/\r\n/g, '\n')
+    .replace(/\r/g, '\n')
+    .split('\n')
+    .map((l) => l.replace(/[ \t]+$/, ''))
+    .join('\n')
+    .trim();
+}
+
+/**
+ * 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 +279,18 @@ 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 = [];
+
   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 +314,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 +337,80 @@ 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 rawTemplate = fs.readFileSync(templateAgentPath, 'utf8');
+            const adaptedTarget = adaptAgentContentString(rawTemplate, file, projectType);
+
+            if (fs.existsSync(existingAgentPath) && !config.forceTemplate) {
+              const existingContent = fs.readFileSync(existingAgentPath, 'utf8');
+              if (normalizeForCompare(existingContent) !== normalizeForCompare(adaptedTarget)) {
+                // Customization detected OR template drift across versions.
+                // Preserve user's file + save adapted target as .new so they
+                // can manually re-merge.
+                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, adaptedTarget, 'utf8');
+                } catch (e) {
+                  console.warn(
+                    `    ⚠ Failed to write .new backup for ${relativePath}: ${e.code || e.message}`
+                  );
+                }
+                modifiedAgentsResults.push({ name: relativePath, modified: true });
+                preserved++;
+                continue;
+              }
+              // Pristine: back up before overwriting (cheap insurance)
+              backupBeforeReplace(dest, relativePath, backupTimestamp);
+            } else if (fs.existsSync(existingAgentPath) && config.forceTemplate) {
+              // --force-template: always back up and overwrite
+              backupBeforeReplace(dest, relativePath, backupTimestamp);
             }
-          } else {
-            fs.cpSync(srcSub, destSub, { recursive: true });
+            fs.writeFileSync(existingAgentPath, adaptedTarget, 'utf8');
+            replaced++;
           }
-          replaced++;
+          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));
+          }
+        } else {
+          fs.cpSync(srcSub, destSub, { recursive: true });
+        }
+        replaced++;
       }
 
       // Merge settings.json — strategy depends on the tool:
@@ -387,18 +545,52 @@ function generateUpgrade(config) {
   }
 
   // --- e) Replace top-level configs ---
-  // AGENTS.md
+  // AGENTS.md — v0.16.10 smart-diff (Change #3): mirror the standards pattern.
+  // Compare existing file against freshly-adapted template output. If they
+  // match, replace (safe pristine). If not, preserve + backup the new adapted
+  // version as .new so the user can manually re-merge. --force-template
+  // short-circuits and always replaces (with backup).
   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');
+
+  if (fs.existsSync(agentsMdDestPath) && !config.forceTemplate) {
+    const existingAgentsMd = fs.readFileSync(agentsMdDestPath, 'utf8');
+    if (normalizeForCompare(existingAgentsMd) !== normalizeForCompare(adaptedAgentsMd)) {
+      // Customization or template drift → preserve + .new backup
+      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++;
+    } else {
+      // Pristine → back up and replace
+      backupBeforeReplace(dest, 'AGENTS.md', backupTimestamp);
+      fs.writeFileSync(agentsMdDestPath, adaptedAgentsMd, 'utf8');
+      replaced++;
+    }
+  } else {
+    // Missing file, or --force-template: always back up (if exists) and overwrite
+    if (fs.existsSync(agentsMdDestPath)) {
+      backupBeforeReplace(dest, 'AGENTS.md', backupTimestamp);
+    }
+    fs.writeFileSync(agentsMdDestPath, adaptedAgentsMd, 'utf8');
+    replaced++;
+  }
 
-  // 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 +640,19 @@ function generateUpgrade(config) {
     replaced++;
   }
 
+  // --- e3) .gitignore — idempotent append of .sdd-backup/ (v0.16.10) ---
+  // Existing projects created before v0.16.10 don't have .sdd-backup/ in their
+  // .gitignore. Append it once so backup dirs aren't accidentally committed.
+  const userGitignorePath = path.join(dest, '.gitignore');
+  if (fs.existsSync(userGitignorePath)) {
+    const existingGitignore = fs.readFileSync(userGitignorePath, 'utf8');
+    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';
+      fs.writeFileSync(userGitignorePath, existingGitignore.trimEnd() + appendBlock, 'utf8');
+      step('Updated .gitignore with .sdd-backup/ entry');
+    }
+  }
+
   // --- f) Adapt for project type ---
   // Remove agents for single-stack projects
   if (projectType === 'backend') {
@@ -551,6 +756,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.16.10",
   "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,6 @@ 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/