create-sdd-project 0.16.10 → 0.17.0

package/lib/upgrade-generator.js

@@ -24,6 +24,21 @@ 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 ---
 //
@@ -57,22 +72,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
@@ -289,6 +298,16 @@ 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();
+
   console.log(`\nUpgrading SDD DevFlow in ${config.projectName}...\n`);
   console.log(`  Backup directory: .sdd-backup/${backupTimestamp}/\n`);
 
@@ -359,43 +378,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;
         }
@@ -545,42 +639,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 +764,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 +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');
 
@@ -732,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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-sdd-project",
-  "version": "0.16.10",
+  "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/gitignore

@@ -53,3 +53,6 @@ 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