create-sdd-project 0.16.10 → 0.17.1

package/lib/init-generator.js

@@ -8,6 +8,8 @@ const {
   BACKEND_AGENTS,
 } = require('./config');
 const { adaptAgentContentForProjectType } = require('./adapt-agents');
+const { applyStackAdaptations } = require('./stack-adaptations');
+const { writeMeta, computeInstallHashes } = require('./meta');
 
 /**
  * Install SDD DevFlow into an existing project.
@@ -252,6 +254,24 @@ function generateInit(config) {
   const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
   fs.writeFileSync(path.join(dest, '.sdd-version'), pkg.version + '\n', 'utf8');
 
+  // v0.17.0: write provenance hashes. Computed AFTER all adaptations
+  // so the hashes reflect the exact post-install content on disk. The
+  // next `--upgrade` uses these hashes to answer "did the user edit
+  // this file?" precisely, avoiding cross-version false-positive
+  // preserve warnings (Codex P1 from v0.16.10 plan review).
+  //
+  // Codex round 2 P1 fix: exclude pre-existing files that --init skipped.
+  // Those belong to the user, not to SDD DevFlow, and must NOT be marked
+  // as tool-canonical — otherwise the next upgrade would hash-match the
+  // user's content and silently overwrite it. `skipped` already contains
+  // the relative paths of files that were skipped due to pre-existence;
+  // convert them to POSIX form and pass as the exclude set.
+  const skippedPosix = new Set(skipped.map((p) => p.split('\\').join('/')));
+  writeMeta(
+    dest,
+    computeInstallHashes(dest, config.aiTools, config.projectType, skippedPosix)
+  );
+
   // Done
   console.log(`\nDone! Next steps:`);
   console.log(`  git add -A && git commit -m "chore: add SDD DevFlow to existing project"`);
@@ -343,163 +363,22 @@ function regexReplaceInFile(filePath, replacements) {
 }
 
 function adaptCopiedFiles(dest, scan, config) {
-  const orm = scan.backend.orm || 'your ORM';
-  const db = scan.backend.db || 'your database';
-
-  // Common Zod → generic validation replacements (all agents + skills)
-  // Phase 1: Replace "Zod" with "validation" (most specific first)
-  const zodReplacements = [
-    ['Zod data schemas', 'validation schemas'],
-    ['Zod schemas', 'validation schemas'],
-  ];
-  // Phase 2: Clean up shared/src/schemas/ path (Zod-specific convention)
-  // Applied AFTER phase 1, so these match the post-replacement text
-  const schemaPathReplacements = [
-    ['validation schemas in `shared/src/schemas/` if applicable', 'validation schemas if applicable'],
-    ['validation schemas in `shared/src/schemas/` (if shared workspace exists)', 'validation schemas (if shared workspace exists)'],
-    ['validation schemas in `shared/src/schemas/`', 'validation schemas'],
-    ['validation schemas (`shared/src/schemas/`)', 'validation schemas'],
-    ['`shared/src/schemas/` (if exists) for current validation schemas', 'project validation schemas'],
-    // Gemini spec-creator: no "Zod" prefix, standalone path reference
-    ['and `shared/src/schemas/` (if exists)', ''],
-    ['schemas vs `shared/src/schemas/`', 'validation schemas up to date'],
-  ];
-
-  // ORM/DB replacements for backend agents
-  let ormReplacements = [];
-  if (scan.backend.orm && scan.backend.orm !== 'Prisma') {
-    ormReplacements = [
-      ['Prisma ORM, and PostgreSQL', `${orm}${db !== 'your database' ? `, and ${db}` : ''}`],
-      ['Repository implementations (Prisma)', `Repository implementations (${orm})`],
-    ];
-  } else if (!scan.backend.orm) {
-    // No ORM detected — remove Prisma references with generic text
-    const dbLabel = db !== 'your database' ? `, and ${db}` : '';
-    ormReplacements = [
-      ['Prisma ORM, and PostgreSQL', dbLabel ? dbLabel.slice(6) : 'your database'],
-      ['Repository implementations (Prisma)', 'Repository implementations'],
-    ];
-  }
-
-  // Apply to all AI tool directories
-  const toolDirs = [];
-  if (config.aiTools !== 'gemini') toolDirs.push('.claude');
-  if (config.aiTools !== 'claude') toolDirs.push('.gemini');
-
-  for (const dir of toolDirs) {
-    // Backend agents: Zod + ORM replacements
-    if (scan.backend.validation !== 'Zod') {
-      const backendAgentReplacements = [...zodReplacements, ...ormReplacements];
-      replaceInCopiedFile(dest, `${dir}/agents/backend-developer.md`, backendAgentReplacements);
-      replaceInCopiedFile(dest, `${dir}/agents/backend-planner.md`, backendAgentReplacements);
-      // Phase 2: clean up shared/src/schemas/ paths
-      replaceInCopiedFile(dest, `${dir}/agents/backend-developer.md`, schemaPathReplacements);
-      replaceInCopiedFile(dest, `${dir}/agents/backend-planner.md`, schemaPathReplacements);
-    } else if (ormReplacements.length > 0) {
-      // Zod detected but different ORM — only ORM replacements
-      replaceInCopiedFile(dest, `${dir}/agents/backend-developer.md`, ormReplacements);
-      replaceInCopiedFile(dest, `${dir}/agents/backend-planner.md`, ormReplacements);
-    }
-
-    // Multi-purpose agents: Zod replacements only
-    if (scan.backend.validation !== 'Zod') {
-      const allZodReplacements = [...zodReplacements, ...schemaPathReplacements];
-      replaceInCopiedFile(dest, `${dir}/agents/spec-creator.md`, allZodReplacements);
-      replaceInCopiedFile(dest, `${dir}/agents/production-code-validator.md`, allZodReplacements);
-      replaceInCopiedFile(dest, `${dir}/agents/database-architect.md`, allZodReplacements);
-    }
-
-    // Skills: Zod + schema path replacements
-    if (scan.backend.validation !== 'Zod') {
-      const allZodReplacements = [...zodReplacements, ...schemaPathReplacements];
-      replaceInCopiedFile(dest, `${dir}/skills/development-workflow/SKILL.md`, allZodReplacements);
-      replaceInCopiedFile(dest, `${dir}/skills/development-workflow/references/ticket-template.md`, allZodReplacements);
-    }
-  }
-
-  // Architecture adaptation: DDD-specific content in backend agents
-  const arch = scan.srcStructure ? scan.srcStructure.pattern : 'ddd';
-  if (arch !== 'ddd') {
-    for (const dir of toolDirs) {
-      // backend-planner: adapt header, exploration paths, implementation order, rules
-      regexReplaceInFile(path.join(dest, dir, 'agents', 'backend-planner.md'), [
-        // Header: remove DDD reference (Claude verbose format)
-        ['specializing in Domain-Driven Design (DDD) layered architecture with deep knowledge of',
-          'specializing in layered architecture with deep knowledge of'],
-        // Header: remove DDD reference (Gemini condensed format)
-        ['(DDD architecture)', '(layered architecture)'],
-        // Exploration: replace DDD-specific paths with generic (number-agnostic)
-        [/\d+\. Read `shared\/src\/schemas\/` \(if exists\) for current .* (?:data )?schemas\n/, ''],
-        [/\d+\. Explore existing domain entities, services, validators, repositories\n/,
-          '5. Explore the codebase for existing patterns, layer structure, and reusable code\n'],
-        [/\d+\. Explore `backend\/src\/infrastructure\/` for existing repositories\n/, ''],
-        // Implementation Order (Claude format)
-        ['following DDD layer order: Domain > Application > Infrastructure > Presentation > Tests',
-          'following the layer order defined in backend-standards.mdc'],
-        // Implementation Order (Gemini format)
-        ['Implementation Order (Domain > Application > Infrastructure > Presentation > Tests)',
-          'Implementation Order (see backend-standards.mdc for layer order)'],
-        // Rules (Claude format)
-        ['Follow DDD layer separation: Domain > Application > Infrastructure > Presentation',
-          'Follow the layer separation defined in backend-standards.mdc'],
-      ]);
-      // backend-developer: adapt frontmatter, header, exploration, implementation order, rules
-      regexReplaceInFile(path.join(dest, dir, 'agents', 'backend-developer.md'), [
-        // Frontmatter (Claude format)
-        ['follows DDD layered architecture',
-          'follows layered architecture'],
-        // Header (Claude format)
-        ['specializing in Domain-Driven Design (DDD) with',
-          'specializing in layered architecture with'],
-        // Header (Gemini condensed format)
-        ['(DDD architecture)', '(layered architecture)'],
-        // Exploration: remove shared/src/schemas reference (number-agnostic)
-        [/\d+\. Read `shared\/src\/schemas\/` \(if exists\) for current .* (?:data )?schemas\n/, ''],
-        // Implementation Order (Claude format): replace DDD layers
-        ['Follow the DDD layer order from the plan:',
-          'Follow the layer order from the plan (see backend-standards.mdc for project layers):'],
-        [/\d+\. \*\*Domain Layer\*\*: Entities, value objects, repository interfaces, domain errors\n/,
-          '1. **Data Layer**: Models, database operations, data access\n'],
-        [/\d+\. \*\*Application Layer\*\*: Services, validators, DTOs\n/,
-          '2. **Business Logic Layer**: Controllers, services, external integrations\n'],
-        [/\d+\. \*\*Infrastructure Layer\*\*: Repository implementations \([^)]*\), external integrations\n/,
-          '3. **Presentation Layer**: Routes, handlers, middleware\n'],
-        [/\d+\. \*\*Presentation Layer\*\*: Controllers, routes, middleware\n/,
-          '4. **Integration Layer**: Wiring, configuration, server registration\n'],
-        // Implementation Order (Gemini format)
-        ['Follow DDD layer order: Domain > Application > Infrastructure > Presentation.',
-          'Follow the layer order defined in backend-standards.mdc.'],
-        // Rules (Claude format)
-        ['**ALWAYS** follow DDD layer separation',
-          '**ALWAYS** follow the layer separation defined in backend-standards.mdc'],
-        ['**ALWAYS** handle errors with custom domain error classes',
-          '**ALWAYS** handle errors following the patterns in backend-standards.mdc'],
-        // Rules (Gemini format)
-        ['ALWAYS handle errors with domain error classes',
-          'ALWAYS handle errors following the patterns in backend-standards.mdc'],
-        // Documentation: remove shared/src/schemas mandatory update
-        [/- (?:\*\*MANDATORY\*\*: )?If modifying a DB schema → update .* schemas in `shared\/src\/schemas\/` BEFORE continuing\n/, ''],
-      ]);
-    }
-  }
-
-  // Agent/skill content: remove frontend/backend-specific references for single-stack projects
+  // v0.17.0: delegate stack-specific adaptations (Zod → validation,
+  // ORM swap, DDD → layered, documentation-standards.mdc project-type
+  // pruning) to the shared module in lib/stack-adaptations.js. This
+  // makes the exact same transformation available to upgrade-generator.js
+  // for the hash-based smart-diff replacement path.
+  //
+  // The in-memory variant (applyStackAdaptationsToContent) is also used
+  // by the upgrade fallback path to construct the "what init would have
+  // written" comparison target when .sdd-meta.json is missing (Gemini M1
+  // fix from plan v1.0 cross-model review).
+  applyStackAdaptations(dest, scan, config, null);
+
+  // Remove frontend/backend-specific references for single-stack
+  // projects. Separate from stack adaptations — this is project-type
+  // pruning, not stack substitution.
   adaptAgentContentForProjectType(dest, config, regexReplaceInFile);
-
-  // documentation-standards.mdc: remove irrelevant rows based on project type
-  const docStdPath = path.join(dest, 'ai-specs', 'specs', 'documentation-standards.mdc');
-  if (fs.existsSync(docStdPath)) {
-    let content = fs.readFileSync(docStdPath, 'utf8');
-    if (config.projectType === 'backend') {
-      content = content.replace(/\| `ai-specs\/specs\/frontend-standards\.mdc` \|[^\n]*\n/, '');
-      content = content.replace(/\| `docs\/specs\/ui-components\.md` \|[^\n]*\n/, '');
-      content = content.replace(/   - UI component changes → `docs\/specs\/ui-components\.md`\n/, '');
-    } else if (config.projectType === 'frontend') {
-      content = content.replace(/\| `ai-specs\/specs\/backend-standards\.mdc` \|[^\n]*\n/, '');
-      content = content.replace(/\| `docs\/specs\/api-spec\.yaml` \|[^\n]*\n/, '');
-    }
-    fs.writeFileSync(docStdPath, content, 'utf8');
-  }
 }
 
 // --- Standards Adaptation ---
@@ -697,10 +576,15 @@ function adaptFrontendStandards(template, scan) {
   );
 
   // Update Project Structure
+  // v0.17.1: the regex consumes the optional trailing TODO line so idempotent
+  // reapplication doesn't duplicate the marker. Before: on second call the
+  // regex only matched up to the closing ``` and the replacement re-inserted
+  // the TODO, producing two copies. After: the (\n\n<!-- TODO: ... -->)? group
+  // is included in the match so the replacement overwrites it.
   const rootDirs = scan.rootDirs.filter((d) => !['docs/', 'ai-specs/', 'node_modules/'].includes(d));
   const tree = rootDirs.map((d) => `├── ${d.replace(/\/$/, '/')}`).join('\n');
   content = content.replace(
-    /## Project Structure\n\n```\n[\s\S]*?```/,
+    /## Project Structure\n\n```\n[\s\S]*?```(\n\n<!-- TODO: Expand the structure above[^\n]*-->)?/,
     `## Project Structure\n\n\`\`\`\nproject/\n${tree}\n\`\`\`\n\n<!-- TODO: Expand the structure above with your key subdirectories. -->`
   );
 
@@ -762,7 +646,14 @@ function adaptAgentsMd(template, config, scan) {
     return norm !== 'docs' && norm !== 'ai-specs';
   });
   if (meaningfulDirs.length > 0) {
-    const tree = rootDirs.map((d) => `├── ${d.replace(/\/$/, '/')}   `).join('\n');
+    // v0.17.0: use meaningfulDirs (not rootDirs) to build the tree. The
+    // SDD-infrastructure dirs (ai-specs/, docs/) get installed BY init
+    // itself, so at install time they're absent from the scan but at
+    // upgrade time they're present. Using rootDirs would produce
+    // different content in each scan → hash drift → false-positive
+    // preserve warnings on every upgrade. Using meaningfulDirs stabilizes
+    // the output across install and upgrade for the same project.
+    const tree = meaningfulDirs.map((d) => `├── ${d.replace(/\/$/, '/')}   `).join('\n');
     const treeBlock = `\`\`\`\nproject/\n${tree}\n└── docs/        ← Documentation\n\`\`\``;
     content = content.replace(
       /<!-- CONFIG: Adjust directories[^>]*-->\n+```\nproject\/\n[\s\S]*?```/,
@@ -1069,9 +960,25 @@ function appendGitignore(dest, skipped) {
   const sddEntries = '\n# SDD DevFlow\ndocs/tickets/*.md\n!docs/tickets/.gitkeep\n';
 
   if (fs.existsSync(gitignorePath)) {
-    const content = fs.readFileSync(gitignorePath, 'utf8');
+    let content = fs.readFileSync(gitignorePath, 'utf8');
+    let appended = false;
     if (!content.includes('SDD DevFlow')) {
-      fs.appendFileSync(gitignorePath, sddEntries, 'utf8');
+      content = content.trimEnd() + sddEntries;
+      appended = true;
+    }
+    // v0.17.0: ensure .sdd-meta.json + .sdd-backup/ are ignored (local-only
+    // metadata). Codex round 2 P2 fix — --init must also append these
+    // entries idempotently, matching the upgrade path.
+    if (!/^\s*\/?\.sdd-backup\/?\s*$/m.test(content)) {
+      content = content.trimEnd() + '\n\n# sdd-devflow upgrade backups (ignored — kept locally for recovery only)\n.sdd-backup/\n';
+      appended = true;
+    }
+    if (!/^\s*\/?\.sdd-meta\.json\s*$/m.test(content)) {
+      content = content.trimEnd() + '\n\n# sdd-devflow provenance tracking (local-only, content-addressable hashes)\n.sdd-meta.json\n';
+      appended = true;
+    }
+    if (appended) {
+      fs.writeFileSync(gitignorePath, content, 'utf8');
       step('Appended SDD entries to .gitignore');
     }
   } else {

package/lib/meta.js

@@ -0,0 +1,344 @@
+'use strict';
+
+/**
+ * SDD DevFlow provenance tracking — v0.17.0+
+ *
+ * The `.sdd-meta.json` file stores content-addressable hashes of files the
+ * tool considers "canonically tool-owned" (template agents + AGENTS.md in
+ * v0.17.0). The upgrade path uses these hashes to answer the question
+ * "has the user edited this file since the last time the tool wrote it?"
+ * precisely, without comparing against the new template's adapted output
+ * (which drifts across versions and causes false-positive preserve
+ * warnings on cross-version upgrades — the Codex P1 finding from the
+ * v0.16.10 cross-model review).
+ *
+ * Core invariant (Codex M1 from plan v1.0 review): a hash in this file
+ * represents "the last time the tool wrote this file, the content hashed
+ * to X". Hashes are ONLY written/updated when the tool actually wrote
+ * canonical output to a file in the current run (replaced, new, or
+ * --force-template paths). Preserved files leave their hash entry
+ * untouched — otherwise the user's customized content would be hashed and
+ * silently overwritten on the next upgrade.
+ *
+ * File format (schemaVersion: 1):
+ *   {
+ *     "schemaVersion": 1,
+ *     "hashes": {
+ *       ".claude/agents/backend-planner.md": "sha256:abc...",
+ *       "AGENTS.md": "sha256:def...",
+ *       ...
+ *     }
+ *   }
+ *
+ * Path keys are POSIX-normalized (forward slashes) on ALL platforms so
+ * lookups work consistently on Windows where path.join would otherwise
+ * produce backslashes (Gemini M2 fix).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { createHash } = require('node:crypto');
+
+const { FRONTEND_AGENTS, BACKEND_AGENTS, TEMPLATE_AGENTS } = require('./config');
+
+const META_FILE = '.sdd-meta.json';
+const CURRENT_SCHEMA_VERSION = 1;
+
+/**
+ * Normalize text for content-addressable hashing.
+ *
+ * v0.17.0: only strip CR / CRLF line endings (Windows git core.autocrlf
+ * compatibility). Do NOT strip trailing whitespace per line — that would
+ * destroy markdown hard-breaks (two trailing spaces render as <br>) and
+ * silently wipe user customizations that only touched whitespace
+ * (Gemini M2 fix).
+ *
+ * Trade-off: editors configured to "trim trailing whitespace on save"
+ * (e.g. VSCode files.trimTrailingWhitespace=true) will produce a hash
+ * mismatch even without semantic edits. This is a conservative false
+ * positive — the upgrade preserves the file and the user can re-run
+ * with --force-template to accept the new template content. The
+ * alternative (silent wipe of markdown hard-breaks) is strictly worse.
+ */
+function normalizeForCompare(text) {
+  return text.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+}
+
+/**
+ * v0.17.1: file-agnostic content equality helper. Returns true when two
+ * strings are equal after CR/CRLF normalization. Replaces the v0.17.0
+ * `isStandardModified` function, which was standards-specific in name but
+ * identical in logic after the Gemini M2 normalization fix.
+ *
+ * Rename rationale (round-2 review consolidated): Codex round-1 Q9 wanted
+ * `isStandardModified` deleted; Gemini round-1 Q9 wanted a named helper
+ * for fallback-path readability; Codex round-2 Q11 pointed out that the
+ * kept-name-as-wrapper compromise was vestigial because the name still
+ * implied standards-specific policy. This rename makes the helper's
+ * file-agnostic nature explicit and its location (next to its dependency
+ * `normalizeForCompare`) structural.
+ *
+ * Scope of normalization (important, often misstated in earlier plan
+ * drafts): this helper ONLY normalizes CR/CRLF line endings. It does NOT
+ * strip trailing whitespace per line nor leading/trailing blank lines —
+ * that would destroy markdown hard-breaks (two trailing spaces render as
+ * `<br>`) and silently wipe user customizations that only touched
+ * whitespace. The conservative behavior is intentional; the alternative
+ * is strictly worse.
+ */
+function normalizedContentEquals(a, b) {
+  return normalizeForCompare(a) === normalizeForCompare(b);
+}
+
+/**
+ * Compute the content-addressable hash of a string.
+ *
+ * Returns 'sha256:<hex>'. The prefix is mandatory so v0.17.x can
+ * introduce additional algorithms (e.g. 'blake3:...') without breaking
+ * old readers — equality comparison on the full string handles upgrades
+ * naturally.
+ */
+function computeHash(content) {
+  const digest = createHash('sha256').update(normalizeForCompare(content), 'utf8').digest('hex');
+  return `sha256:${digest}`;
+}
+
+/**
+ * Compute the hash of a file on disk, or null if it doesn't exist.
+ * Reads as UTF-8 (all tracked files are text).
+ */
+function hashFileOnDisk(absPath) {
+  if (!fs.existsSync(absPath)) return null;
+  try {
+    return computeHash(fs.readFileSync(absPath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Normalize a platform-relative path to POSIX form for use as a hash map
+ * key. On Windows this converts backslashes to forward slashes; on POSIX
+ * it's a no-op.
+ */
+function toPosix(relativePath) {
+  return relativePath.split(path.sep).join('/');
+}
+
+/**
+ * Read and validate .sdd-meta.json. Returns null on ANY read/parse/shape
+ * failure so callers can fall back to v0.16.10 content-compare behavior.
+ * Never throws.
+ *
+ * Returns { schemaVersion, hashes } on success.
+ */
+function readMeta(dest) {
+  const p = path.join(dest, META_FILE);
+  if (!fs.existsSync(p)) return null;
+
+  let raw;
+  try {
+    raw = fs.readFileSync(p, 'utf8');
+  } catch (e) {
+    console.warn(`    ⚠ .sdd-meta.json unreadable (${e.code || e.message}). Falling back to content compare.`);
+    return null;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    console.warn(`    ⚠ .sdd-meta.json is not valid JSON (${e.message}). Falling back to content compare.`);
+    return null;
+  }
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    console.warn(`    ⚠ .sdd-meta.json root is not an object. Falling back.`);
+    return null;
+  }
+
+  // Schema version: absent → assume v1 (forward-compat with writers that
+  // might omit the field). Greater than current → log a warning and fall
+  // back (don't try to interpret future schemas).
+  const schemaVersion = parsed.schemaVersion ?? 1;
+  if (typeof schemaVersion !== 'number' || schemaVersion < 1) {
+    console.warn(`    ⚠ .sdd-meta.json has invalid schemaVersion ${schemaVersion}. Falling back.`);
+    return null;
+  }
+  if (schemaVersion > CURRENT_SCHEMA_VERSION) {
+    console.warn(
+      `    ⚠ .sdd-meta.json schemaVersion ${schemaVersion} is newer than supported ${CURRENT_SCHEMA_VERSION}. ` +
+      `Falling back to content compare. Upgrade the sdd-devflow CLI to a newer version.`
+    );
+    return null;
+  }
+
+  const hashes = parsed.hashes;
+  if (typeof hashes !== 'object' || hashes === null || Array.isArray(hashes)) {
+    console.warn(`    ⚠ .sdd-meta.json hashes field is not an object. Falling back.`);
+    return null;
+  }
+
+  // Shallow-validate each entry: key is a string, value matches the
+  // sha256:<hex> shape. Malformed entries are dropped silently (they'll
+  // be recomputed on the next upgrade).
+  const cleaned = {};
+  const HASH_RE = /^sha256:[0-9a-f]{64}$/;
+  for (const [k, v] of Object.entries(hashes)) {
+    if (typeof k !== 'string' || typeof v !== 'string') continue;
+    if (!HASH_RE.test(v)) continue;
+    // Normalize keys to POSIX in case an older writer produced
+    // backslashed paths on Windows.
+    cleaned[k.split('\\').join('/')] = v;
+  }
+
+  return { schemaVersion, hashes: cleaned };
+}
+
+/**
+ * Write .sdd-meta.json with the given hashes map. Non-fatal on failure —
+ * logs a warning but does NOT throw. The next upgrade will recompute and
+ * try again.
+ */
+function writeMeta(dest, hashes) {
+  const p = path.join(dest, META_FILE);
+  const payload = {
+    schemaVersion: CURRENT_SCHEMA_VERSION,
+    hashes,
+  };
+  try {
+    fs.writeFileSync(p, JSON.stringify(payload, null, 2) + '\n', 'utf8');
+  } catch (e) {
+    console.warn(
+      `    ⚠ Failed to write .sdd-meta.json: ${e.code || e.message}. ` +
+      `Next upgrade will fall back to content compare.`
+    );
+  }
+}
+
+/**
+ * Compute the full set of POSIX paths that SHOULD have a hash entry for
+ * the given (aiTools, projectType) combination. Used for two purposes:
+ *
+ * 1. Pruning: remove hash entries for files that are expected-absent
+ *    (e.g., single-stack project removed frontend agents) — but NOT for
+ *    files the user temporarily deleted manually (those get recreated
+ *    on the next upgrade, so their hash should persist).
+ *
+ * 2. Install-time hashing: iterate this set, compute each file's hash
+ *    if the file exists on disk.
+ *
+ * v0.17.0 scope: template agents (.claude/agents/*, .gemini/agents/*)
+ * + AGENTS.md.
+ *
+ * v0.17.1 scope extension (Codex M1 option 2 deferred from v0.17.0):
+ * - 4 standards files (ai-specs/specs/*.mdc) — always tracked
+ * - 6 workflow-core files (development-workflow SKILL.md + ticket-template.md
+ *   + merge-checklist.md, × 2 tools) — filtered by aiTools
+ *
+ * Out of scope for v0.17.1 (deferred to v0.17.2): bug-workflow/SKILL.md,
+ * health-check/SKILL.md, pm-orchestrator/SKILL.md, project-memory/SKILL.md,
+ * and all references/ files except the 3 development-workflow ones above.
+ */
+function expectedSmartDiffTrackedPaths(aiTools, projectType) {
+  const paths = new Set();
+
+  const toolDirs = [];
+  if (aiTools !== 'gemini') toolDirs.push('.claude');
+  if (aiTools !== 'claude') toolDirs.push('.gemini');
+
+  const agents = TEMPLATE_AGENTS.filter((a) => {
+    if (projectType === 'backend' && FRONTEND_AGENTS.includes(a)) return false;
+    if (projectType === 'frontend' && BACKEND_AGENTS.includes(a)) return false;
+    return true;
+  });
+
+  for (const dir of toolDirs) {
+    for (const agent of agents) {
+      paths.add(`${dir}/agents/${agent}`);
+    }
+  }
+
+  paths.add('AGENTS.md');
+
+  // v0.17.1: standards — always tracked (independent of aiTools/projectType).
+  // Project-type filtering (backend-only skips frontend-standards.mdc) is
+  // enforced by the existing install/upgrade pipeline that only writes the
+  // relevant standards for the project type; their hash entries are simply
+  // absent for the non-applicable side.
+  paths.add('ai-specs/specs/base-standards.mdc');
+  if (projectType !== 'frontend') paths.add('ai-specs/specs/backend-standards.mdc');
+  if (projectType !== 'backend') paths.add('ai-specs/specs/frontend-standards.mdc');
+  paths.add('ai-specs/specs/documentation-standards.mdc');
+
+  // v0.17.1: development-workflow skill core files — filtered by aiTools.
+  // bug-workflow, health-check, pm-orchestrator, project-memory are OUT OF
+  // SCOPE for v0.17.1 (deferred to v0.17.2).
+  for (const dir of toolDirs) {
+    paths.add(`${dir}/skills/development-workflow/SKILL.md`);
+    paths.add(`${dir}/skills/development-workflow/references/ticket-template.md`);
+    paths.add(`${dir}/skills/development-workflow/references/merge-checklist.md`);
+  }
+
+  return paths;
+}
+
+/**
+ * Remove hash entries from `hashes` that are NOT in the expected set
+ * for the current (aiTools, projectType). Returns a new object.
+ *
+ * This does NOT prune based on on-disk presence — a user who temporarily
+ * deletes an agent file keeps its hash so the next upgrade can recreate
+ * the file from the template and restore the hash map cleanly
+ * (Gemini M3 fix).
+ */
+function pruneExpectedAbsent(hashes, aiTools, projectType) {
+  const expected = expectedSmartDiffTrackedPaths(aiTools, projectType);
+  const pruned = {};
+  for (const [k, v] of Object.entries(hashes)) {
+    if (expected.has(k)) pruned[k] = v;
+  }
+  return pruned;
+}
+
+/**
+ * Compute install-time hashes for a newly-populated project. Walks the
+ * expected set and hashes any file that exists on disk, EXCLUDING any
+ * path that's in `excludeSet` (e.g., `--init` encountered a pre-existing
+ * file and skipped it — the user owns that content, we must NOT mark it
+ * as tool-canonical or the next upgrade would overwrite user content.
+ * Codex round 2 P1 fix).
+ *
+ * @param {string} dest - Project root
+ * @param {string} aiTools - 'claude' | 'gemini' | 'both'
+ * @param {string} projectType - 'backend' | 'frontend' | 'fullstack'
+ * @param {Set<string>|Iterable<string>|null} excludeSet - POSIX paths to exclude. Null → no exclusion.
+ */
+function computeInstallHashes(dest, aiTools, projectType, excludeSet = null) {
+  const excluded = excludeSet ? new Set(excludeSet) : null;
+  const hashes = {};
+  for (const posixPath of expectedSmartDiffTrackedPaths(aiTools, projectType)) {
+    if (excluded && excluded.has(posixPath)) continue;
+    const absPath = path.join(dest, ...posixPath.split('/'));
+    const hash = hashFileOnDisk(absPath);
+    if (hash !== null) {
+      hashes[posixPath] = hash;
+    }
+  }
+  return hashes;
+}
+
+module.exports = {
+  META_FILE,
+  CURRENT_SCHEMA_VERSION,
+  computeHash,
+  hashFileOnDisk,
+  toPosix,
+  normalizeForCompare,
+  normalizedContentEquals,
+  readMeta,
+  writeMeta,
+  expectedSmartDiffTrackedPaths,
+  pruneExpectedAbsent,
+  computeInstallHashes,
+};