create-sdd-project 0.17.0 → 0.17.1

package/lib/adapt-agents.js

@@ -65,6 +65,99 @@ const AGENT_ADAPTATION_RULES = {
   },
 };
 
+/**
+ * v0.17.1: project-type-specific pruning rules for workflow-core files
+ * (SKILL.md + ticket-template.md). Keys are POSIX suffixes relative to
+ * the tool dir (e.g. `skills/development-workflow/SKILL.md`) so the same
+ * rules apply to both `.claude/` and `.gemini/` trees.
+ *
+ * These rules are the pure/in-memory equivalent of the inline block in
+ * `adaptAgentContentForProjectType`. Exposed here so upgrade-generator.js
+ * can build an accurate "what init would have produced" comparison target
+ * for smart-diff fallback paths — previously this was masked by
+ * unconditional `filesToAdapt.add` calls (pre-v0.17.1) that re-applied
+ * stack rules to restored user content, violating Codex M1 (Gemini round-3
+ * finding 1). Source of truth now lives here; disk-writing code below
+ * calls these same tables.
+ */
+const WORKFLOW_CORE_PROJECT_TYPE_RULES = {
+  backend: {
+    'skills/development-workflow/SKILL.md': [
+      [/,? `ui-components\.md`\)/, ')'],
+      [/- UI components → `docs\/specs\/ui-components\.md` \(MANDATORY\)\n/, ''],
+      [/\d+\. \*\*Design Review \(optional\):\*\*[^\n]*\n/, ''],
+    ],
+    'skills/development-workflow/references/ticket-template.md': [
+      [/### UI Changes \(if applicable\)\n\n\[Components to add\/modify\. Reference `docs\/specs\/ui-components\.md`\.\]\n\n/, ''],
+      [' / `ui-components.md`', ''],
+    ],
+  },
+  frontend: {
+    'skills/development-workflow/SKILL.md': [
+      [/`api-spec\.yaml`,? /, ''],
+      [/- API endpoints → `docs\/specs\/api-spec\.yaml` \(MANDATORY\)\n/, ''],
+    ],
+    'skills/development-workflow/references/ticket-template.md': [
+      [/### API Changes \(if applicable\)\n\n\[Endpoints to add\/modify\. Reference[^\]]*\]\n\n/, ''],
+      ['`api-spec.yaml` / ', ''],
+    ],
+  },
+};
+
+const BASE_STANDARDS_PROJECT_TYPE_RULES = {
+  backend: [
+    [/\| `ui-ux-designer` \|[^\n]*\n/, ''],
+  ],
+  // frontend: no extra rules (base-standards template has no frontend-only refs to strip)
+};
+
+function applyProjectTypeRules(content, rules) {
+  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;
+}
+
+/**
+ * v0.17.1 pure helper — apply project-type rules to a workflow-core file
+ * content. Returns content unchanged if projectType is fullstack or if
+ * posixPath doesn't match a known workflow-core file.
+ *
+ * @param {string} content - Raw or stack-adapted content
+ * @param {string} posixPath - Full POSIX path (e.g. '.claude/skills/development-workflow/SKILL.md')
+ * @param {string} projectType - 'fullstack' | 'backend' | 'frontend'
+ * @returns {string}
+ */
+function adaptWorkflowCoreContentForProjectType(content, posixPath, projectType) {
+  if (projectType === 'fullstack') return content;
+  const rulesForType = WORKFLOW_CORE_PROJECT_TYPE_RULES[projectType];
+  if (!rulesForType) return content;
+
+  // Strip the tool prefix (.claude/ or .gemini/) to match the rule key.
+  const match = posixPath.match(/^\.(?:claude|gemini)\/(.+)$/);
+  if (!match) return content;
+  const rules = rulesForType[match[1]];
+  if (!rules) return content;
+
+  return applyProjectTypeRules(content, rules);
+}
+
+/**
+ * v0.17.1 pure helper — apply project-type rules to base-standards.mdc
+ * content. Called AFTER `adaptBaseStandards` to produce the full init
+ * equivalent for smart-diff comparison.
+ */
+function adaptBaseStandardsContentForProjectType(content, projectType) {
+  const rules = BASE_STANDARDS_PROJECT_TYPE_RULES[projectType];
+  if (!rules) return content;
+  return applyProjectTypeRules(content, rules);
+}
+
 /**
  * Pure function — apply single-stack adaptation rules to an agent file's content.
  *
@@ -130,43 +223,38 @@ function adaptAgentContentForProjectType(dest, config, replaceInFileFn) {
   }
 
   // --- Skills and templates: remove frontend/backend-specific references ---
-  // These stay inline — they're not agent files, so not needed by upgrade smart-diff.
+  // v0.17.1: SKILL.md + ticket-template.md rules now come from the
+  // WORKFLOW_CORE_PROJECT_TYPE_RULES table above so upgrade-generator.js
+  // can apply the same rules in-memory (smart-diff fallback comparison).
+  // pr-template.md + AGENTS.md + base-standards.mdc remain inline because
+  // they're not workflow-core files (pr-template is v0.17.2 scope).
+  const wfRules = WORKFLOW_CORE_PROJECT_TYPE_RULES[config.projectType];
+  if (wfRules) {
+    for (const dir of toolDirs) {
+      for (const [suffix, rules] of Object.entries(wfRules)) {
+        replaceInFileFn(path.join(dest, dir, ...suffix.split('/')), rules);
+      }
+    }
+  }
+
   if (config.projectType === 'backend') {
+    // AGENTS.md: remove ui-ux-designer from hook description
+    replaceInFileFn(path.join(dest, 'AGENTS.md'), [
+      [', `ui-ux-designer`', ''],
+    ]);
     for (const dir of toolDirs) {
-      // SKILL.md: remove ui-components references and design review step
-      replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'SKILL.md'), [
-        [/,? `ui-components\.md`\)/, ')'],
-        [/- UI components → `docs\/specs\/ui-components\.md` \(MANDATORY\)\n/, ''],
-        [/\d+\. \*\*Design Review \(optional\):\*\*[^\n]*\n/, ''],
-      ]);
-      // AGENTS.md: remove ui-ux-designer from hook description
-      replaceInFileFn(path.join(dest, 'AGENTS.md'), [
-        [', `ui-ux-designer`', ''],
-      ]);
-      // ticket-template: remove UI Changes section, ui-components from checklists
-      replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'ticket-template.md'), [
-        [/### UI Changes \(if applicable\)\n\n\[Components to add\/modify\. Reference `docs\/specs\/ui-components\.md`\.\]\n\n/, ''],
-        [' / `ui-components.md`', ''],
-      ]);
-      // pr-template: remove ui-components from checklist
+      // pr-template: remove ui-components from checklist (v0.17.2 scope)
       replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'pr-template.md'), [
         [' / ui-components.md', ''],
       ]);
     }
-    // Shared files (outside tool dirs): remove ui-ux-designer and design-guidelines refs
-    replaceInFileFn(path.join(dest, 'ai-specs', 'specs', 'base-standards.mdc'), [
-      [/\| `ui-ux-designer` \|[^\n]*\n/, ''],
-    ]);
+    // base-standards.mdc: remove ui-ux-designer table row (shared table above)
+    replaceInFileFn(
+      path.join(dest, 'ai-specs', 'specs', 'base-standards.mdc'),
+      BASE_STANDARDS_PROJECT_TYPE_RULES.backend
+    );
   } else if (config.projectType === 'frontend') {
     for (const dir of toolDirs) {
-      replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'SKILL.md'), [
-        [/`api-spec\.yaml`,? /, ''],
-        [/- API endpoints → `docs\/specs\/api-spec\.yaml` \(MANDATORY\)\n/, ''],
-      ]);
-      replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'ticket-template.md'), [
-        [/### API Changes \(if applicable\)\n\n\[Endpoints to add\/modify\. Reference[^\]]*\]\n\n/, ''],
-        ['`api-spec.yaml` / ', ''],
-      ]);
       replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'references', 'pr-template.md'), [
         ['api-spec.yaml / ', ''],
       ]);
@@ -177,5 +265,9 @@ function adaptAgentContentForProjectType(dest, config, replaceInFileFn) {
 module.exports = {
   adaptAgentContentForProjectType,
   adaptAgentContentString,
+  adaptWorkflowCoreContentForProjectType,
+  adaptBaseStandardsContentForProjectType,
   AGENT_ADAPTATION_RULES,
+  WORKFLOW_CORE_PROJECT_TYPE_RULES,
+  BASE_STANDARDS_PROJECT_TYPE_RULES,
 };

package/lib/diff-generator.js

@@ -13,11 +13,17 @@ const {
   adaptFrontendStandards,
 } = require('./init-generator');
 const {
-  isStandardModified,
   getPackageVersion,
 } = require('./upgrade-generator');
+const { normalizedContentEquals } = require('./meta');
 const { formatScanSummary } = require('./init-wizard');
 
+// v0.17.1: isStandardModified was removed. Replace callers with inverted
+// normalizedContentEquals — "modified" means "not equal after normalization".
+function isStandardModified(existing, fresh) {
+  return !normalizedContentEquals(existing, fresh);
+}
+
 const templateDir = path.join(__dirname, '..', 'template');
 
 /**

package/lib/doctor.js

@@ -979,6 +979,24 @@ function checkAgentsMdStandardsRefs(cwd) {
     );
   }
 
+  // v0.17.1 observability (Gemini Q10): warn on sparse Backend/Frontend patterns
+  // — exactly 1 entry — suggesting scanner detection missed framework or ORM.
+  // Permissive: non-failing, informational. Two+ entries are assumed OK because
+  // projects legitimately vary (ORM-only backends, component-less frontends).
+  const sparseRe = /(Backend|Frontend) patterns \(([^)]+)\)/g;
+  let sparseMatch;
+  while ((sparseMatch = sparseRe.exec(content)) !== null) {
+    const rawEntries = sparseMatch[2]
+      .split(',')
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0);
+    if (rawEntries.length === 1) {
+      issues.push(
+        `${sparseMatch[1]} patterns has only 1 entry (${rawEntries[0]}) — scanner detection may be incomplete; run \`npx create-sdd-project --upgrade\` after installing your stack deps to re-detect`
+      );
+    }
+  }
+
   // 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

package/lib/init-generator.js

@@ -576,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. -->`
   );
 

package/lib/meta.js

@@ -64,6 +64,32 @@ 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.
  *
@@ -203,9 +229,16 @@ function writeMeta(dest, hashes) {
  *    if the file exists on disk.
  *
  * v0.17.0 scope: template agents (.claude/agents/*, .gemini/agents/*)
- * + AGENTS.md. SKILL.md / ticket-template.md / documentation-standards.mdc
- * are tracked with wholesale-recopy + stack-adaptations on every upgrade
- * (v0.16.10 behavior); they are NOT in this set.
+ * + 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();
@@ -228,6 +261,25 @@ function expectedSmartDiffTrackedPaths(aiTools, projectType) {
 
   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;
 }
 
@@ -283,6 +335,7 @@ module.exports = {
   hashFileOnDisk,
   toPosix,
   normalizeForCompare,
+  normalizedContentEquals,
   readMeta,
   writeMeta,
   expectedSmartDiffTrackedPaths,

package/lib/scanner.js

@@ -7,17 +7,56 @@ const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', '.n
 
 /**
  * Scan an existing project directory and return detected configuration.
+ *
+ * v0.17.1: monorepo-aware. If the root `package.json` does not yield a
+ * backend/frontend detection AND the project is a monorepo with
+ * `package.json#workspaces`, enumerate workspace `package.json` files in
+ * declaration order (pattern outer, lexical inner, deduped by normalized
+ * path) and run `detectBackend` / `detectFrontend` per workspace. The
+ * FIRST workspace returning `detected: true` wins and its result is merged
+ * into `result.backend` / `result.frontend` with a `workspaceSource` field
+ * recording the detected workspace's relative path (for diagnostics).
+ *
+ * Scanner additive invariant (v0.17.1): for single-package projects, or
+ * monorepos where root detection already succeeded, the workspace
+ * enumeration never fires and the result is byte-identical to v0.17.0.
  */
 function scan(projectDir) {
   const pkg = readPackageJson(projectDir);
 
-  const result = {
+  const backend = detectBackend(projectDir, pkg);
+  const frontend = detectFrontend(projectDir, pkg);
+  const isMonorepo = detectMonorepo(projectDir, pkg);
+
+  // v0.17.1 monorepo fallback
+  if (isMonorepo && (!backend.detected || !frontend.detected)) {
+    const workspaces = enumerateWorkspaces(projectDir, pkg);
+    for (const wsRel of workspaces) {
+      const wsAbs = path.join(projectDir, ...wsRel.split('/'));
+      const wsPkg = readPackageJson(wsAbs);
+      if (!backend.detected) {
+        const wsBackend = detectBackend(wsAbs, wsPkg);
+        if (wsBackend.detected) {
+          Object.assign(backend, wsBackend, { workspaceSource: wsRel });
+        }
+      }
+      if (!frontend.detected) {
+        const wsFrontend = detectFrontend(wsAbs, wsPkg);
+        if (wsFrontend.detected) {
+          Object.assign(frontend, wsFrontend, { workspaceSource: wsRel });
+        }
+      }
+      if (backend.detected && frontend.detected) break;
+    }
+  }
+
+  return {
     projectName: pkg.name || path.basename(projectDir),
     description: pkg.description || '',
     language: detectLanguage(projectDir),
-    backend: detectBackend(projectDir, pkg),
-    frontend: detectFrontend(projectDir, pkg),
-    isMonorepo: detectMonorepo(projectDir, pkg),
+    backend,
+    frontend,
+    isMonorepo,
     rootDirs: listRootDirs(projectDir),
     srcStructure: detectArchitecture(projectDir, pkg),
     tests: detectTests(projectDir, pkg),
@@ -25,8 +64,90 @@ function scan(projectDir) {
     gitBranch: detectGitBranch(projectDir),
     hasGit: fs.existsSync(path.join(projectDir, '.git')),
   };
+}
 
-  return result;
+/**
+ * v0.17.1: enumerate workspace paths declared in `pkg.workspaces`.
+ *
+ * Supports:
+ *  - Array form: `"workspaces": ["packages/*", "apps/*"]`
+ *  - Object form: `"workspaces": { "packages": ["packages/*"] }`
+ *  - Literal paths: `"packages/api"` (no glob)
+ *  - Single-wildcard patterns: `"packages/*"` (expand immediate subdirs)
+ *
+ * Does NOT support: `**` recursive patterns, `!exclude` negation, or
+ * `pnpm-workspace.yaml` — all deferred to v0.17.2.
+ *
+ * Returns a deterministic, deduplicated array of POSIX-style relative
+ * workspace paths. Ordering: outer = declaration order of patterns; inner
+ * = lexical Unicode codepoint sort of expanded subdirs; dedupe = first
+ * occurrence wins after flattening (Codex + Gemini round-2 Q7).
+ */
+function enumerateWorkspaces(dir, pkg) {
+  let patterns = [];
+  if (Array.isArray(pkg.workspaces)) {
+    patterns = pkg.workspaces;
+  } else if (pkg.workspaces && Array.isArray(pkg.workspaces.packages)) {
+    patterns = pkg.workspaces.packages;
+  }
+  if (patterns.length === 0) return [];
+
+  const flat = [];
+  for (const pattern of patterns) {
+    flat.push(...expandWorkspacePattern(dir, pattern));
+  }
+
+  const seen = new Set();
+  const deduped = [];
+  for (const wsPath of flat) {
+    const normalized = wsPath.replace(/\\/g, '/').replace(/\/$/, '');
+    if (seen.has(normalized)) continue;
+    seen.add(normalized);
+    deduped.push(normalized);
+  }
+  return deduped;
+}
+
+function expandWorkspacePattern(dir, pattern) {
+  // npm/yarn workspace semantics: a workspace is a DIRECTORY CONTAINING
+  // package.json. Directories without package.json are not workspaces,
+  // even if they live under a matched glob (Codex round-3 finding 1).
+  // This prevents the scanner from wasting work on stray folders
+  // (docs/, shared assets, build outputs) and keeps first-match-wins
+  // deterministic against only declared workspace packages.
+  const hasPkgJson = (absDir) => {
+    try {
+      return fs.statSync(path.join(absDir, 'package.json')).isFile();
+    } catch {
+      return false;
+    }
+  };
+
+  if (!pattern.includes('*')) {
+    const absPath = path.join(dir, pattern);
+    try {
+      if (fs.statSync(absPath).isDirectory() && hasPkgJson(absPath)) {
+        return [pattern.replace(/\\/g, '/')];
+      }
+    } catch { /* not found or not a dir */ }
+    return [];
+  }
+  // Only support trailing single-wildcard: `foo/*` or `foo/bar/*`
+  const match = pattern.match(/^(.+)\/\*$/);
+  if (!match) return [];
+  const baseDir = match[1];
+  const baseDirAbs = path.join(dir, baseDir);
+  let entries;
+  try {
+    entries = fs.readdirSync(baseDirAbs, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isDirectory() && hasPkgJson(path.join(baseDirAbs, e.name)))
+    .map((e) => e.name)
+    .sort()
+    .map((name) => `${baseDir}/${name}`);
 }
 
 // --- Helpers ---
@@ -541,4 +662,4 @@ function detectGitBranch(dir) {
   return 'main';
 }
 
-module.exports = { scan };
+module.exports = { scan, enumerateWorkspaces, expandWorkspacePattern };

package/lib/upgrade-generator.js

@@ -12,6 +12,8 @@ const {
 const {
   adaptAgentContentForProjectType,
   adaptAgentContentString,
+  adaptWorkflowCoreContentForProjectType,
+  adaptBaseStandardsContentForProjectType,
 } = require('./adapt-agents');
 const {
   adaptBaseStandards,
@@ -25,6 +27,7 @@ const {
   regexReplaceInFile,
 } = require('./init-generator');
 // v0.17.0: hash-based smart-diff + shared stack adaptations
+// v0.17.1: + normalizedContentEquals (replaces isStandardModified)
 const {
   readMeta,
   writeMeta,
@@ -34,6 +37,7 @@ const {
   pruneExpectedAbsent,
   expectedSmartDiffTrackedPaths,
   normalizeForCompare: metaNormalizeForCompare,
+  normalizedContentEquals,
 } = require('./meta');
 const {
   applyStackAdaptations,
@@ -223,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.
  */
@@ -308,6 +304,38 @@ function generateUpgrade(config) {
   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`);
 
@@ -567,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');
@@ -827,18 +1054,15 @@ function generateUpgrade(config) {
   // 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'));
-
+  // 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');
@@ -935,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(
@@ -972,6 +1199,5 @@ module.exports = {
   readAutonomyLevel,
   collectCustomAgents,
   collectCustomCommands,
-  isStandardModified,
   buildSummary,
 };

package/package.json

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