create-sdd-project 0.16.10 → 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

@@ -79,6 +79,9 @@ function runDoctor(cwd) {
   // 14. AGENTS.md Standards References (v0.16.10)
   results.push(checkAgentsMdStandardsRefs(cwd));
 
+  // 15. .sdd-meta.json structural integrity (v0.17.0)
+  results.push(checkMetaJson(cwd, aiTools, projectType));
+
   return results;
 }
 
@@ -976,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
@@ -1013,6 +1034,151 @@ function checkAgentsMdStandardsRefs(cwd) {
   };
 }
 
+/**
+ * Check #15 (v0.17.0): .sdd-meta.json structural integrity.
+ *
+ * v0.17.0 introduces content-addressable hashing via .sdd-meta.json to
+ * track "the last time the tool wrote this file". The upgrade path uses
+ * the hashes to answer "did the user edit since last tool-write" without
+ * comparing against the new template's adapted output (which would drift
+ * across versions — the Codex P1 from v0.16.10 cross-model review).
+ *
+ * This doctor check validates the METADATA STRUCTURE ONLY:
+ *   - Valid JSON
+ *   - schemaVersion ≤ current
+ *   - hashes is a sensible object shape
+ *   - Every hash value matches sha256:<64 hex>
+ *   - Every key that's NOT in the expected set is flagged as orphan
+ *
+ * It does NOT validate hashes against current on-disk content (Codex M3
+ * from plan v1.0 review). Hash mismatches are the EXPECTED result of
+ * legitimate user customization; reporting them here would generate
+ * permanent noise and bury real integrity issues.
+ *
+ * Severity:
+ *   - File absent → PASS with informational message (pre-v0.17.0 project)
+ *   - Present and valid → PASS
+ *   - Parse/shape errors → WARN (not FAIL — upgrade still falls back safely)
+ *   - Orphan entries → WARN (non-fatal, upgrade prunes them next run)
+ */
+function checkMetaJson(cwd, aiTools, projectType) {
+  const metaPath = path.join(cwd, '.sdd-meta.json');
+  if (!fs.existsSync(metaPath)) {
+    return {
+      status: PASS,
+      message: 'Provenance metadata: not present (pre-v0.17.0 project or fresh install)',
+      details: [],
+    };
+  }
+
+  let raw;
+  try {
+    raw = fs.readFileSync(metaPath, 'utf8');
+  } catch (e) {
+    return {
+      status: WARN,
+      message: '.sdd-meta.json: unreadable',
+      details: [e.code || e.message],
+    };
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    return {
+      status: WARN,
+      message: '.sdd-meta.json: invalid JSON',
+      details: [e.message, 'Next upgrade will regenerate it via the fallback path.'],
+    };
+  }
+
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return {
+      status: WARN,
+      message: '.sdd-meta.json: root is not an object',
+      details: ['Next upgrade will regenerate it.'],
+    };
+  }
+
+  // Validate schemaVersion. Absent = v1 (forward-compat). Newer than
+  // supported = still WARN (fallback path handles it).
+  const {
+    CURRENT_SCHEMA_VERSION,
+    expectedSmartDiffTrackedPaths,
+  } = require('./meta');
+  const schemaVersion = parsed.schemaVersion ?? 1;
+  if (typeof schemaVersion !== 'number' || schemaVersion < 1) {
+    return {
+      status: WARN,
+      message: `.sdd-meta.json: invalid schemaVersion ${schemaVersion}`,
+      details: [],
+    };
+  }
+  if (schemaVersion > CURRENT_SCHEMA_VERSION) {
+    return {
+      status: WARN,
+      message: `.sdd-meta.json: schemaVersion ${schemaVersion} newer than supported ${CURRENT_SCHEMA_VERSION}`,
+      details: ['Upgrade the sdd-devflow CLI to the latest version.'],
+    };
+  }
+
+  const hashes = parsed.hashes;
+  if (typeof hashes !== 'object' || hashes === null || Array.isArray(hashes)) {
+    return {
+      status: WARN,
+      message: '.sdd-meta.json: hashes field is not an object',
+      details: ['Next upgrade will regenerate it.'],
+    };
+  }
+
+  // Validate each entry's shape.
+  const HASH_RE = /^sha256:[0-9a-f]{64}$/;
+  const issues = [];
+  for (const [k, v] of Object.entries(hashes)) {
+    if (typeof k !== 'string') {
+      issues.push(`invalid key: ${typeof k}`);
+      continue;
+    }
+    // Reject absolute paths and `..` traversal.
+    if (k.startsWith('/') || k.includes('..')) {
+      issues.push(`suspicious key: ${k}`);
+      continue;
+    }
+    if (typeof v !== 'string' || !HASH_RE.test(v)) {
+      issues.push(`invalid hash for ${k}`);
+    }
+  }
+
+  if (issues.length > 0) {
+    return {
+      status: WARN,
+      message: `.sdd-meta.json: ${issues.length} shape issue${issues.length > 1 ? 's' : ''}`,
+      details: [...issues.slice(0, 5), 'Next upgrade will regenerate affected entries.'],
+    };
+  }
+
+  // Detect orphan entries (keys not expected for the current tool/type).
+  const expected = expectedSmartDiffTrackedPaths(aiTools, projectType);
+  const orphans = Object.keys(hashes).filter((k) => !expected.has(k));
+  if (orphans.length > 0) {
+    return {
+      status: WARN,
+      message: `.sdd-meta.json: ${orphans.length} orphan entr${orphans.length > 1 ? 'ies' : 'y'}`,
+      details: [
+        ...orphans.slice(0, 5).map((o) => `Orphan: ${o}`),
+        'Non-fatal — next upgrade will prune these automatically.',
+      ],
+    };
+  }
+
+  return {
+    status: PASS,
+    message: `Provenance metadata: valid (${Object.keys(hashes).length} tracked files)`,
+    details: [],
+  };
+}
+
 module.exports = {
   runDoctor,
   printResults,

package/lib/generator.js

@@ -10,6 +10,7 @@ const {
   BACKEND_AGENTS,
 } = require('./config');
 const { adaptAgentContentForProjectType } = require('./adapt-agents');
+const { writeMeta, computeInstallHashes } = require('./meta');
 
 function generate(config) {
   const templateDir = path.join(__dirname, '..', 'template');
@@ -95,6 +96,13 @@ function generate(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. Captures whatever generator.js's
+  // pipeline produced (lighter than init-generator — adaptAgentsForStack
+  // only, no stack-adaptations module). First upgrade re-adapts via the
+  // scanner-driven pipeline; the hash answers "did the user edit since
+  // install" precisely regardless of which pipeline wrote the content.
+  writeMeta(dest, computeInstallHashes(dest, config.aiTools, config.projectType));
+
   // Show notes
   const notes = collectNotes(config);
   if (notes.length > 0) {