create-sdd-project 0.16.10 → 0.17.1

package/lib/upgrade-generator.js

@@ -12,6 +12,8 @@ const {
 const {
   adaptAgentContentForProjectType,
   adaptAgentContentString,
+  adaptWorkflowCoreContentForProjectType,
+  adaptBaseStandardsContentForProjectType,
 } = require('./adapt-agents');
 const {
   adaptBaseStandards,
@@ -24,6 +26,23 @@ const {
   updateAutonomy,
   regexReplaceInFile,
 } = require('./init-generator');
+// v0.17.0: hash-based smart-diff + shared stack adaptations
+// v0.17.1: + normalizedContentEquals (replaces isStandardModified)
+const {
+  readMeta,
+  writeMeta,
+  computeHash,
+  hashFileOnDisk,
+  toPosix,
+  pruneExpectedAbsent,
+  expectedSmartDiffTrackedPaths,
+  normalizeForCompare: metaNormalizeForCompare,
+  normalizedContentEquals,
+} = require('./meta');
+const {
+  applyStackAdaptations,
+  applyStackAdaptationsToContent,
+} = require('./stack-adaptations');
 
 // --- v0.16.10: backup-before-replace helpers ---
 //
@@ -57,22 +76,16 @@ function buildBackupTimestamp() {
 }
 
 /**
- * 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.
+ * 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.
  */
-function normalizeForCompare(text) {
-  return text
-    .replace(/\r\n/g, '\n')
-    .replace(/\r/g, '\n')
-    .split('\n')
-    .map((l) => l.replace(/[ \t]+$/, ''))
-    .join('\n')
-    .trim();
-}
+const normalizeForCompare = metaNormalizeForCompare;
 
 /**
  * Copy a user file to .sdd-backup/<timestamp>/<relativePath> before it is
@@ -214,14 +227,6 @@ function collectCustomCommands(dest) {
   return customs;
 }
 
-/**
- * Check if a standard file has been modified by the user.
- * Compares existing file against freshly generated version.
- */
-function isStandardModified(existingContent, freshContent) {
-  return existingContent.trim() !== freshContent.trim();
-}
-
 /**
  * Build the upgrade summary for display.
  */
@@ -289,6 +294,48 @@ function generateUpgrade(config) {
   // 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();
+
+  // 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
+  // us they were customized. Map keyed by absolute path, value = string or
+  // null (null = file didn't exist before upgrade).
+  const workflowCoreBackup = new Map();
+  const workflowCorePosixPaths = [];
+  {
+    const dirsForBackup = [];
+    if (aiTools !== 'gemini') dirsForBackup.push('.claude');
+    if (aiTools !== 'claude') dirsForBackup.push('.gemini');
+    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',
+      ]) {
+        const posix = `${dir}/${relSub}`;
+        const abs = path.join(dest, ...posix.split('/'));
+        workflowCorePosixPaths.push({ posix, abs });
+        if (fs.existsSync(abs)) {
+          try {
+            workflowCoreBackup.set(abs, fs.readFileSync(abs, 'utf8'));
+          } catch {
+            workflowCoreBackup.set(abs, null);
+          }
+        } else {
+          workflowCoreBackup.set(abs, null);
+        }
+      }
+    }
+  }
+
   console.log(`\nUpgrading SDD DevFlow in ${config.projectName}...\n`);
   console.log(`  Backup directory: .sdd-backup/${backupTimestamp}/\n`);
 
@@ -359,43 +406,118 @@ function generateUpgrade(config) {
             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 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`
+            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;
+            }
+
+            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}`
                 );
-                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++;
+              }
+              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;
               }
-              // 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
+              // 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;
             }
-            fs.writeFileSync(existingAgentPath, adaptedTarget, 'utf8');
-            replaced++;
+
+            // Content mismatch → preserve. Same rule: no hash update.
+            preserveFile(adaptedFullTargetFallback);
           }
           continue;
         }
@@ -473,67 +595,266 @@ function generateUpgrade(config) {
     preserved++;
   }
 
-  // --- d) Handle standards (smart diff) ---
-  const standardsResults = [];
+  // --- c2) v0.17.1: workflow-core smart-diff protection ---
+  //
+  // The 6 development-workflow files (SKILL.md + ticket-template.md +
+  // merge-checklist.md, × 2 tools) were just wholesale-copied by the
+  // skills/ delete-and-replace at step (b). Without this block, user
+  // customizations to the core workflow files (ticket templates, merge
+  // checklists, SKILL.md definitions) would be silently lost every
+  // upgrade. Check each against its pre-upgrade backup (captured before
+  // step (b)) via the hash decision tree; restore the backup if the user
+  // had customized it, otherwise leave the template version in place.
+  for (const { posix, abs } of workflowCorePosixPaths) {
+    const backup = workflowCoreBackup.get(abs);
+    const relativePath = path.relative(dest, abs);
+
+    if (backup === null || backup === undefined) {
+      // File did not exist pre-upgrade (first install or user deleted it)
+      // → leave the freshly-copied template version in place.
+      if (fs.existsSync(abs)) {
+        filesToAdapt.add(posix);
+        replaced++;
+      }
+      continue;
+    }
 
-  // base-standards.mdc
-  const baseStdPath = path.join(dest, 'ai-specs', 'specs', 'base-standards.mdc');
-  if (fs.existsSync(baseStdPath)) {
-    const existing = fs.readFileSync(baseStdPath, 'utf8');
-    const template = fs.readFileSync(path.join(templateDir, 'ai-specs', 'specs', 'base-standards.mdc'), 'utf8');
-    const fresh = adaptBaseStandards(template, scan, config);
-    if (isStandardModified(existing, fresh)) {
-      standardsResults.push({ name: 'ai-specs/specs/base-standards.mdc', modified: true });
-      preserved++;
-    } else {
-      fs.writeFileSync(baseStdPath, fresh, 'utf8');
-      standardsResults.push({ name: 'ai-specs/specs/base-standards.mdc', modified: false });
+    if (config.forceTemplate) {
+      // --force-template: keep the fresh template, back up the old content.
+      backupBeforeReplace(dest, relativePath, backupTimestamp);
+      filesToAdapt.add(posix);
       replaced++;
+      continue;
     }
-  }
 
-  // backend-standards.mdc
-  if (projectType !== 'frontend') {
-    const backendStdPath = path.join(dest, 'ai-specs', 'specs', 'backend-standards.mdc');
-    if (fs.existsSync(backendStdPath)) {
-      const existing = fs.readFileSync(backendStdPath, 'utf8');
-      const template = fs.readFileSync(path.join(templateDir, 'ai-specs', 'specs', 'backend-standards.mdc'), 'utf8');
-      const fresh = adaptBackendStandards(template, scan);
-      if (isStandardModified(existing, fresh)) {
-        standardsResults.push({ name: 'ai-specs/specs/backend-standards.mdc', modified: true });
-        preserved++;
-      } else {
-        fs.writeFileSync(backendStdPath, fresh, 'utf8');
-        standardsResults.push({ name: 'ai-specs/specs/backend-standards.mdc', modified: false });
+    const freshContent = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : null;
+    if (freshContent === null) {
+      // Template no longer ships this file (should not happen in v0.17.1)
+      continue;
+    }
+
+    const storedHash = meta && meta.hashes[posix];
+    const backupHash = computeHash(backup);
+
+    if (storedHash) {
+      // Case 2: hash-based path.
+      if (backupHash === storedHash) {
+        // Pristine → keep the fresh copy, back up the pre-upgrade version.
+        backupBeforeReplace(dest, relativePath, backupTimestamp);
+        filesToAdapt.add(posix);
         replaced++;
+        continue;
       }
+      // Hash mismatch → customized → restore backup + write .new with
+      // adapted target so user can diff against canonical v0.17.1 output.
+      // v0.17.1 round-3: the .new backup must mirror what init would have
+      // produced (stack rules + project-type rules), so the user can diff
+      // apples-to-apples against their customized file.
+      const stackTarget = applyStackAdaptationsToContent(freshContent, posix, scan, config);
+      const adaptedTarget = adaptWorkflowCoreContentForProjectType(stackTarget, posix, projectType);
+      backupBeforeReplace(dest, relativePath, backupTimestamp);
+      fs.writeFileSync(abs, backup, 'utf8');
+      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;
+    }
+
+    // Case 3: fallback path — no stored hash (pre-v0.17.1 project). Compare
+    // backup against the FULLY adapted template target (stack rules +
+    // project-type rules) OR the raw template content. Both are valid
+    // "pristine" states for a pre-v0.17.1 project:
+    //   (a) adapted: --init ran applyStackAdaptations AND
+    //       adaptAgentContentForProjectType at install time (full adapted)
+    //   (b) raw: generator.js scaffold copied template without running adapters
+    // v0.17.1 round-3: BOTH stack rules and project-type rules must be
+    // applied to the comparison target. Previously only stack rules were
+    // applied, which caused false-positive preserve on single-stack projects
+    // (scenario 55 regression guard).
+    const stackTarget = applyStackAdaptationsToContent(freshContent, posix, scan, config);
+    const adaptedTarget = adaptWorkflowCoreContentForProjectType(stackTarget, posix, projectType);
+    if (
+      normalizedContentEquals(backup, adaptedTarget) ||
+      normalizedContentEquals(backup, freshContent)
+    ) {
+      // Pristine per content compare → keep the fresh copy.
+      backupBeforeReplace(dest, relativePath, backupTimestamp);
+      filesToAdapt.add(posix);
+      replaced++;
+      continue;
+    }
+    // Customized → restore backup + write .new with adapted target.
+    backupBeforeReplace(dest, relativePath, backupTimestamp);
+    fs.writeFileSync(abs, backup, 'utf8');
+    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++;
   }
 
-  // frontend-standards.mdc
-  if (projectType !== 'backend') {
-    const frontendStdPath = path.join(dest, 'ai-specs', 'specs', 'frontend-standards.mdc');
-    if (fs.existsSync(frontendStdPath)) {
-      const existing = fs.readFileSync(frontendStdPath, 'utf8');
-      const template = fs.readFileSync(path.join(templateDir, 'ai-specs', 'specs', 'frontend-standards.mdc'), 'utf8');
-      const fresh = adaptFrontendStandards(template, scan);
-      if (isStandardModified(existing, fresh)) {
-        standardsResults.push({ name: 'ai-specs/specs/frontend-standards.mdc', modified: true });
-        preserved++;
-      } else {
-        fs.writeFileSync(frontendStdPath, fresh, 'utf8');
-        standardsResults.push({ name: 'ai-specs/specs/frontend-standards.mdc', modified: false });
+  // --- d) Handle standards (smart diff) ---
+  const standardsResults = [];
+
+  // v0.17.1: hash decision tree for all 4 standards.
+  //
+  // Each standard uses its own adapter (adaptBaseStandards, adaptBackendStandards,
+  // adaptFrontendStandards, or — for documentation-standards — the imperative
+  // branch in applyStackAdaptationsToContent). The decision tree is uniform:
+  //   1. Missing or --force-template → unconditional write + hash update
+  //   2. Stored hash match → pristine, replace + hash update
+  //   3. Stored hash mismatch → customized, preserve + .new backup, NO hash update
+  //   4. No stored hash → fallback compare against adapted target (normalizedContentEquals)
+  //
+  // Replaces v0.17.0's isStandardModified main-path compare (deleted in this commit).
+  // Standards are added to filesToAdapt when replaced, so their hashes get
+  // computed at the end of the upgrade via the filesToAdapt loop.
+  const standardsSpecs = [
+    {
+      posix: 'ai-specs/specs/base-standards.mdc',
+      relTemplate: ['ai-specs', 'specs', 'base-standards.mdc'],
+      // v0.17.1 round-3: init applies project-type rules via
+      // adaptAgentContentForProjectType AFTER adaptBaseStandards, so the
+      // comparison target must include both layers to avoid false-positive
+      // preserve on single-stack upgrades (scenario 55 regression guard).
+      adapter: (tpl) => adaptBaseStandardsContentForProjectType(
+        adaptBaseStandards(tpl, scan, config),
+        projectType
+      ),
+      include: true,
+    },
+    {
+      posix: 'ai-specs/specs/backend-standards.mdc',
+      relTemplate: ['ai-specs', 'specs', 'backend-standards.mdc'],
+      adapter: (tpl) => adaptBackendStandards(tpl, scan),
+      include: projectType !== 'frontend',
+    },
+    {
+      posix: 'ai-specs/specs/frontend-standards.mdc',
+      relTemplate: ['ai-specs', 'specs', 'frontend-standards.mdc'],
+      adapter: (tpl) => adaptFrontendStandards(tpl, scan),
+      include: projectType !== 'backend',
+    },
+    {
+      posix: 'ai-specs/specs/documentation-standards.mdc',
+      relTemplate: ['ai-specs', 'specs', 'documentation-standards.mdc'],
+      // documentation-standards has no dedicated adapter; stack-adaptations.js
+      // handles project-type pruning via its imperative branch at the end of
+      // applyStackAdaptations. For the adapted target used in fallback
+      // content-compare here, we apply it in-memory via
+      // applyStackAdaptationsToContent (same helper, different invocation).
+      adapter: (tpl) => applyStackAdaptationsToContent(tpl, 'ai-specs/specs/documentation-standards.mdc', scan, config),
+      include: true,
+    },
+  ];
+
+  for (const spec of standardsSpecs) {
+    if (!spec.include) continue;
+    const absPath = path.join(dest, ...spec.posix.split('/'));
+    const templatePath = path.join(templateDir, ...spec.relTemplate);
+    if (!fs.existsSync(templatePath)) continue;
+    const template = fs.readFileSync(templatePath, 'utf8');
+    const freshAdapted = spec.adapter(template);
+    const relativePath = path.relative(dest, absPath);
+
+    if (!fs.existsSync(absPath)) {
+      // Missing → unconditional write
+      fs.mkdirSync(path.dirname(absPath), { recursive: true });
+      fs.writeFileSync(absPath, freshAdapted, 'utf8');
+      filesToAdapt.add(spec.posix);
+      standardsResults.push({ name: spec.posix, modified: false });
+      replaced++;
+      continue;
+    }
+
+    if (config.forceTemplate) {
+      backupBeforeReplace(dest, relativePath, backupTimestamp);
+      fs.writeFileSync(absPath, freshAdapted, 'utf8');
+      filesToAdapt.add(spec.posix);
+      standardsResults.push({ name: spec.posix, modified: false });
+      replaced++;
+      continue;
+    }
+
+    const existing = fs.readFileSync(absPath, 'utf8');
+    const storedHash = meta && meta.hashes[spec.posix];
+
+    const preserveStandard = () => {
+      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, freshAdapted, 'utf8');
+      } catch (e) {
+        console.warn(`    ⚠ Failed to write .new backup for ${relativePath}: ${e.code || e.message}`);
+      }
+      standardsResults.push({ name: spec.posix, modified: true });
+      preserved++;
+      // Codex M1 invariant: do NOT update newHashes[spec.posix] — the
+      // inherited hash (if any) persists untouched for preserved files.
+    };
+
+    if (storedHash) {
+      // Case 2: hash-based path.
+      const currentHash = computeHash(existing);
+      if (currentHash === storedHash) {
+        // Pristine → replace with adapted target.
+        backupBeforeReplace(dest, relativePath, backupTimestamp);
+        fs.writeFileSync(absPath, freshAdapted, 'utf8');
+        filesToAdapt.add(spec.posix);
+        standardsResults.push({ name: spec.posix, modified: false });
         replaced++;
+        continue;
       }
+      // Hash mismatch → preserve.
+      preserveStandard();
+      continue;
     }
-  }
 
-  // documentation-standards.mdc — always replace (unlikely customized, no adaptation)
-  const docStdSrc = path.join(templateDir, 'ai-specs', 'specs', 'documentation-standards.mdc');
-  const docStdDest = path.join(dest, 'ai-specs', 'specs', 'documentation-standards.mdc');
-  if (fs.existsSync(docStdSrc)) {
-    fs.copyFileSync(docStdSrc, docStdDest);
-    replaced++;
+    // Case 3: fallback content-compare (no stored hash, pre-v0.17.1 project).
+    //
+    // Two acceptable "pristine" states for a pre-v0.17.1 project:
+    //   (a) existing matches the adapted target — the --init path ran the
+    //       adapter at install time (existing is adapted content)
+    //   (b) existing matches the RAW template content — the generator.js
+    //       scaffold path copied the template without running the adapter
+    //       (existing is raw content)
+    //
+    // Without case (b), every fresh-scaffolded v0.17.0 project upgrading to
+    // v0.17.1 would false-positive-preserve all 4 standards on first upgrade
+    // (the template content on disk would not match the adapter output).
+    if (
+      normalizedContentEquals(existing, freshAdapted) ||
+      normalizedContentEquals(existing, template)
+    ) {
+      backupBeforeReplace(dest, relativePath, backupTimestamp);
+      fs.writeFileSync(absPath, freshAdapted, 'utf8');
+      filesToAdapt.add(spec.posix);
+      standardsResults.push({ name: spec.posix, modified: false });
+      replaced++;
+      continue;
+    }
+    preserveStandard();
   }
 
   step('Updated standards files');
@@ -545,42 +866,72 @@ function generateUpgrade(config) {
   }
 
   // --- e) Replace top-level configs ---
-  // 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).
+  // 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);
   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) && !config.forceTemplate) {
+  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');
-    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}`);
+    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();
       }
-      modifiedAgentsResults.push({ name: 'AGENTS.md', modified: true });
-      preserved++;
-    } else {
-      // Pristine → back up and replace
+    } 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();
     }
-  } 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 (back up before replace, not smart-diff'd)
@@ -640,17 +991,33 @@ 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.
+  // --- 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)) {
-    const existingGitignore = fs.readFileSync(userGitignorePath, 'utf8');
+    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';
-      fs.writeFileSync(userGitignorePath, existingGitignore.trimEnd() + appendBlock, 'utf8');
+      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 ---
@@ -673,30 +1040,30 @@ 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).
+  //
+  // v0.17.1: SKILL.md, ticket-template.md, and documentation-standards.mdc
+  // are now smart-diff-protected (c2 block and standards block respectively)
+  // and ARE added to filesToAdapt conditionally on being replaced (NOT
+  // preserved). The pre-v0.17.1 unconditional adds that used to live here
+  // were removed because they violated the Codex M1 invariant when the
+  // new smart-diff blocks preserved a customized file (Gemini round-3
+  // finding 1): the unconditional add would re-apply stack adaptations
+  // to the restored user content, mangling it, and then the hash loop
+  // would overwrite the preserved hash.
+  applyStackAdaptations(dest, scan, config, filesToAdapt);
 
   step('Adapted files for project type and stack');
 
@@ -732,6 +1099,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;
@@ -766,16 +1159,19 @@ function generateUpgrade(config) {
       );
     }
     console.log(
-      `\n    Note: this is EXPECTED on cross-version upgrades (e.g. ${config.installedVersion} → ${newVersion}).`
+      `\n    Note: this is expected on the first v0.17.0+ upgrade from a pre-v0.17.0 project`
+    );
+    console.log(
+      `    for files the user had not touched — the fallback content-compare path is`
     );
     console.log(
-      `    v0.16.10 uses conservative preserve semantics — any file that does not exactly`
+      `    conservative by design. After this upgrade, .sdd-meta.json records the hash of`
     );
     console.log(
-      `    match the new template's adapted output is preserved, even if you never edited it.`
+      `    every SDD-managed file. Subsequent upgrades will use hash-based precision and`
     );
     console.log(
-      `    Provenance tracking (v0.17.0) will eliminate these false positives.`
+      `    will only warn on files the user actually edited.`
     );
     console.log(`\n    If you have NOT customized these files:`);
     console.log(
@@ -803,6 +1199,5 @@ module.exports = {
   readAutonomyLevel,
   collectCustomAgents,
   collectCustomCommands,
-  isStandardModified,
   buildSummary,
 };