create-sdd-project 0.16.9 → 0.17.0

package/bin/cli.js

@@ -11,6 +11,7 @@ const isInit = args.includes('--init');
 const isUpgrade = args.includes('--upgrade');
 const isDoctor = args.includes('--doctor');
 const isForce = args.includes('--force');
+const isForceTemplate = args.includes('--force-template');
 const isEject = args.includes('--eject');
 const isDiff = args.includes('--diff');
 
@@ -185,6 +186,7 @@ async function runUpgrade() {
   config.autonomyLevel = autonomy.level;
   config.autonomyName = autonomy.name;
   config.installedVersion = installedVersion;
+  config.forceTemplate = isForceTemplate;
 
   // Build and show summary
   const state = {

package/lib/adapt-agents.js

@@ -2,10 +2,114 @@
 
 const path = require('path');
 
+/**
+ * Per-agent-file adaptation rules for single-stack projects.
+ *
+ * For each projectType ('backend' or 'frontend'), maps filename to a list of
+ * [search, replace] tuples applied in order. When `search` is a RegExp, uses
+ * .replace(); when it's a string, uses split/join to replace all occurrences.
+ *
+ * These rules ONLY apply to files under .claude/agents/ or .gemini/agents/.
+ * Skill and template file adaptations live in the I/O wrapper below because
+ * they don't need the pure function (they're not used by upgrade smart-diff).
+ *
+ * fullstack projectType has no rules — templates ship in fullstack-ready form.
+ */
+const AGENT_ADAPTATION_RULES = {
+  backend: {
+    'spec-creator.md': [
+      [/### Frontend Specifications\n(?:- [^\n]*\n)+\n/, ''],
+      [/### For UI Changes\n```markdown\n(?:[^\n]*\n)*?```\n\n/, ''],
+      ['Data Model Changes, UI Changes, Edge Cases', 'Data Model Changes, Edge Cases'],
+      ['(`api-spec.yaml`, `ui-components.md`)', '(`api-spec.yaml`)'],
+      // Gemini agents have different text patterns (also applied to Claude; no-op if no match):
+      [/\(api-spec\.yaml, ui-components\.md\)/, '(api-spec.yaml)'],
+    ],
+    'production-code-validator.md': [
+      [/- Components exported\/used that are NOT listed in `docs\/specs\/ui-components\.md`\n/, ''],
+      [/,? components not in ui-components\.md/, ''],
+      [/\.? ?Check components vs `ui-components\.md`/, ''],
+    ],
+    'code-review-specialist.md': [
+      ['(`backend-standards.mdc` / `frontend-standards.mdc`)', '(`backend-standards.mdc`)'],
+      ['(`api-spec.yaml`, `ui-components.md`)', '(`api-spec.yaml`)'],
+    ],
+    'qa-engineer.md': [
+      ['(`api-spec.yaml`, `ui-components.md`)', '(`api-spec.yaml`)'],
+      [/- Frontend: `cd frontend && npm test`\n/, ''],
+      [/- \*\*Frontend\*\*: Write tests for error states[^\n]*\n/, ''],
+      ['`backend-standards.mdc` / `frontend-standards.mdc`', '`backend-standards.mdc`'],
+      ['`backend-standards.mdc` and/or `frontend-standards.mdc`', '`backend-standards.mdc`'],
+      [/ and\/or `(?:ai-specs\/specs\/)?frontend-standards\.mdc`/, ''],
+    ],
+  },
+  frontend: {
+    'spec-creator.md': [
+      [/### Backend Specifications\n(?:- [^\n]*\n)+\n/, ''],
+      [/### For API Changes\n```yaml\n(?:[^\n]*\n)*?```\n\n/, ''],
+      ['(`api-spec.yaml`, `ui-components.md`)', '(`ui-components.md`)'],
+      [/\(api-spec\.yaml, ui-components\.md\)/, '(ui-components.md)'],
+    ],
+    'code-review-specialist.md': [
+      ['(`backend-standards.mdc` / `frontend-standards.mdc`)', '(`frontend-standards.mdc`)'],
+      ['(`api-spec.yaml`, `ui-components.md`)', '(`ui-components.md`)'],
+    ],
+    'qa-engineer.md': [
+      ['(`api-spec.yaml`, `ui-components.md`)', '(`ui-components.md`)'],
+      [/- Backend: `cd backend && npm test`\n/, ''],
+      [/- \*\*Backend\*\*: Write tests for error paths[^\n]*\n/, ''],
+      ['`backend-standards.mdc` / `frontend-standards.mdc`', '`frontend-standards.mdc`'],
+      ['`backend-standards.mdc` and/or `frontend-standards.mdc`', '`frontend-standards.mdc`'],
+      [/`(?:ai-specs\/specs\/)?backend-standards\.mdc` and\/or /, ''],
+    ],
+  },
+};
+
+/**
+ * Pure function — apply single-stack adaptation rules to an agent file's content.
+ *
+ * Used by both the I/O wrapper below AND by upgrade-generator.js smart-diff
+ * (v0.16.10+) to compute what the "pristine adapted target" should be for a
+ * given (rawTemplate, filename, projectType) tuple. The smart-diff compares
+ * the user's current file against this value — if they match, the user hasn't
+ * customized and the upgrade can safely replace.
+ *
+ * @param {string} content - Raw template content
+ * @param {string} filename - Agent file basename (e.g. 'spec-creator.md')
+ * @param {string} projectType - 'fullstack' | 'backend' | 'frontend'
+ * @returns {string} - Adapted content (or unchanged if no rules apply)
+ */
+function adaptAgentContentString(content, filename, projectType) {
+  if (projectType === 'fullstack') return content;
+
+  const rulesForType = AGENT_ADAPTATION_RULES[projectType];
+  if (!rulesForType) return content;
+
+  const rules = rulesForType[filename];
+  if (!rules) return content;
+
+  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;
+}
+
 /**
  * Shared agent/skill content adaptation for single-stack projects.
  * Used by both generator.js (new projects) and init-generator.js (--init).
  *
+ * As of v0.16.10, delegates per-agent-file transformations to the pure
+ * adaptAgentContentString() function so upgrade-generator.js smart-diff can
+ * share the same rules. Skill and template file adaptations (SKILL.md,
+ * ticket-template.md, pr-template.md, AGENTS.md ui-ux-designer removal,
+ * base-standards.mdc cleanup) remain inline because they're not needed by
+ * smart-diff.
+ *
  * @param {string} dest - Destination directory
  * @param {object} config - Config with projectType and aiTools
  * @param {function} replaceInFileFn - Function(filePath, replacements) to perform replacements
@@ -15,71 +119,20 @@ function adaptAgentContentForProjectType(dest, config, replaceInFileFn) {
   if (config.aiTools !== 'gemini') toolDirs.push('.claude');
   if (config.aiTools !== 'claude') toolDirs.push('.gemini');
 
-  if (config.projectType === 'backend') {
-    for (const dir of toolDirs) {
-      // spec-creator: remove Frontend Specifications section, UI output format, ui-components refs
-      replaceInFileFn(path.join(dest, dir, 'agents', 'spec-creator.md'), [
-        [/### Frontend Specifications\n(?:- [^\n]*\n)+\n/, ''],
-        [/### For UI Changes\n```markdown\n(?:[^\n]*\n)*?```\n\n/, ''],
-        ['Data Model Changes, UI Changes, Edge Cases', 'Data Model Changes, Edge Cases'],
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`api-spec.yaml`)'],
-      ]);
-      // production-code-validator: remove ui-components line from Spec Drift
-      replaceInFileFn(path.join(dest, dir, 'agents', 'production-code-validator.md'), [
-        [/- Components exported\/used that are NOT listed in `docs\/specs\/ui-components\.md`\n/, ''],
-      ]);
-      // code-review-specialist: backend-only standards ref, remove ui-components
-      replaceInFileFn(path.join(dest, dir, 'agents', 'code-review-specialist.md'), [
-        ['(`backend-standards.mdc` / `frontend-standards.mdc`)', '(`backend-standards.mdc`)'],
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`api-spec.yaml`)'],
-      ]);
-      // qa-engineer: remove frontend refs, adapt standards refs
-      replaceInFileFn(path.join(dest, dir, 'agents', 'qa-engineer.md'), [
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`api-spec.yaml`)'],
-        [/- Frontend: `cd frontend && npm test`\n/, ''],
-        [/- \*\*Frontend\*\*: Write tests for error states[^\n]*\n/, ''],
-        ['`backend-standards.mdc` / `frontend-standards.mdc`', '`backend-standards.mdc`'],
-        ['`backend-standards.mdc` and/or `frontend-standards.mdc`', '`backend-standards.mdc`'],
-        [/ and\/or `(?:ai-specs\/specs\/)?frontend-standards\.mdc`/, ''],
-      ]);
-    }
-  } else if (config.projectType === 'frontend') {
+  // --- Agent file adaptations (delegate to pure function) ---
+  const rulesForType = AGENT_ADAPTATION_RULES[config.projectType];
+  if (rulesForType) {
     for (const dir of toolDirs) {
-      // spec-creator: remove Backend Specifications section, api-spec refs
-      replaceInFileFn(path.join(dest, dir, 'agents', 'spec-creator.md'), [
-        [/### Backend Specifications\n(?:- [^\n]*\n)+\n/, ''],
-        [/### For API Changes\n```yaml\n(?:[^\n]*\n)*?```\n\n/, ''],
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`ui-components.md`)'],
-      ]);
-      // code-review-specialist: frontend-only standards ref
-      replaceInFileFn(path.join(dest, dir, 'agents', 'code-review-specialist.md'), [
-        ['(`backend-standards.mdc` / `frontend-standards.mdc`)', '(`frontend-standards.mdc`)'],
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`ui-components.md`)'],
-      ]);
-      // qa-engineer: remove backend refs, adapt standards refs
-      replaceInFileFn(path.join(dest, dir, 'agents', 'qa-engineer.md'), [
-        ['(`api-spec.yaml`, `ui-components.md`)', '(`ui-components.md`)'],
-        [/- Backend: `cd backend && npm test`\n/, ''],
-        [/- \*\*Backend\*\*: Write tests for error paths[^\n]*\n/, ''],
-        ['`backend-standards.mdc` / `frontend-standards.mdc`', '`frontend-standards.mdc`'],
-        ['`backend-standards.mdc` and/or `frontend-standards.mdc`', '`frontend-standards.mdc`'],
-        [/`(?:ai-specs\/specs\/)?backend-standards\.mdc` and\/or /, ''],
-      ]);
+      for (const [filename, rules] of Object.entries(rulesForType)) {
+        replaceInFileFn(path.join(dest, dir, 'agents', filename), rules);
+      }
     }
   }
 
-  // Skills and templates: remove frontend/backend-specific references
+  // --- Skills and templates: remove frontend/backend-specific references ---
+  // These stay inline — they're not agent files, so not needed by upgrade smart-diff.
   if (config.projectType === 'backend') {
     for (const dir of toolDirs) {
-      // Gemini agents have different text patterns for spec-creator
-      replaceInFileFn(path.join(dest, dir, 'agents', 'spec-creator.md'), [
-        [/\(api-spec\.yaml, ui-components\.md\)/, '(api-spec.yaml)'],
-        ['Data Model Changes, UI Changes, Edge Cases', 'Data Model Changes, Edge Cases'],
-      ]);
-      replaceInFileFn(path.join(dest, dir, 'agents', 'production-code-validator.md'), [
-        [/,? components not in ui-components\.md/, ''],
-        [/\.? ?Check components vs `ui-components\.md`/, ''],
-      ]);
       // SKILL.md: remove ui-components references and design review step
       replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'SKILL.md'), [
         [/,? `ui-components\.md`\)/, ')'],
@@ -106,9 +159,6 @@ function adaptAgentContentForProjectType(dest, config, replaceInFileFn) {
     ]);
   } else if (config.projectType === 'frontend') {
     for (const dir of toolDirs) {
-      replaceInFileFn(path.join(dest, dir, 'agents', 'spec-creator.md'), [
-        [/\(api-spec\.yaml, ui-components\.md\)/, '(ui-components.md)'],
-      ]);
       replaceInFileFn(path.join(dest, dir, 'skills', 'development-workflow', 'SKILL.md'), [
         [/`api-spec\.yaml`,? /, ''],
         [/- API endpoints → `docs\/specs\/api-spec\.yaml` \(MANDATORY\)\n/, ''],
@@ -124,4 +174,8 @@ function adaptAgentContentForProjectType(dest, config, replaceInFileFn) {
   }
 }
 
-module.exports = { adaptAgentContentForProjectType };
+module.exports = {
+  adaptAgentContentForProjectType,
+  adaptAgentContentString,
+  AGENT_ADAPTATION_RULES,
+};

package/lib/doctor.js

@@ -76,6 +76,12 @@ function runDoctor(cwd) {
   // 13. Gemini TOML Commands Format
   results.push(checkGeminiCommands(cwd, aiTools));
 
+  // 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;
 }
 
@@ -940,6 +946,221 @@ function checkGeminiCommands(cwd, aiTools) {
   };
 }
 
+/**
+ * Check #14 (v0.16.10): detect adapter-failure artifacts in AGENTS.md.
+ *
+ * The specific broken state seen in foodXPlorer after the v0.16.9 upgrade
+ * was `Standards References` containing `"Backend patterns ()"` — empty
+ * parens left behind after the template substitution failed. This check
+ * looks for that pattern plus any unsubstituted placeholders of the shape
+ * `[Something]` that don't match a known-good markdown link.
+ *
+ * Severity: WARN — an empty-parens AGENTS.md doesn't break the project,
+ * it just leaves the agents without full stack context.
+ */
+function checkAgentsMdStandardsRefs(cwd) {
+  const agentsMdPath = path.join(cwd, 'AGENTS.md');
+  if (!fs.existsSync(agentsMdPath)) {
+    return {
+      status: WARN,
+      message: 'AGENTS.md: missing',
+      details: ['Run: npx create-sdd-project --upgrade to recreate'],
+    };
+  }
+
+  const content = fs.readFileSync(agentsMdPath, 'utf8');
+  const issues = [];
+
+  // Detect adapter failure: "Backend patterns ()" or "Frontend patterns ()"
+  const emptyParensMatch = content.match(/(?:Backend|Frontend) patterns \(\s*\)/g);
+  if (emptyParensMatch) {
+    issues.push(
+      `Adapter failure: ${emptyParensMatch.join(', ')} (empty parens after template substitution)`
+    );
+  }
+
+  // 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
+  // the target of a markdown link (no `(` or `:` immediately after the `]`).
+  //
+  // Gemini cross-model review (v0.16.10) caught the original broad regex
+  // /\[[A-Z][^\]]{5,60}\]/g catching legitimate user-added markdown links
+  // like `[Architecture Doc](./docs/arch.md)`. AGENTS.md is explicitly meant
+  // to be user-customized, so the doctor must not warn on every link.
+  //
+  // Match only placeholder-shaped strings that are followed by whitespace,
+  // end-of-line, or punctuation (not `(` for a link target or `:` for a
+  // footnote reference), AND contain either a comma or the word "your" or
+  // "example" to distinguish them from section headers.
+  const PLACEHOLDER_RE = /\[[A-Z][^\]]{3,60}[,\s](?:[^\]]{0,60})\](?!\(|:)/g;
+  const HINT_WORDS_RE = /\b(?:your|example|framework|runtime|version|name|path)\b/i;
+  const candidates = content.match(PLACEHOLDER_RE) || [];
+  const unsubstituted = candidates.filter((c) => HINT_WORDS_RE.test(c));
+  if (unsubstituted.length > 0) {
+    issues.push(`Unsubstituted placeholders: ${unsubstituted.slice(0, 3).join(', ')}`);
+  }
+
+  if (issues.length > 0) {
+    return {
+      status: WARN,
+      message: `AGENTS.md: ${issues.length} issue${issues.length > 1 ? 's' : ''}`,
+      details: [...issues, 'Run: npx create-sdd-project --upgrade --force to re-adapt'],
+    };
+  }
+
+  return {
+    status: PASS,
+    message: 'AGENTS.md: standards references valid',
+    details: [],
+  };
+}
+
+/**
+ * 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) {