gsdd-cli 0.18.5 → 0.19.1

package/bin/lib/runtime-freshness.mjs

@@ -8,22 +8,22 @@ import {
   renderOpenCodeCommandContent,
   renderSkillContent,
 } from './rendering.mjs';
-import {
-  CLAUDE_MODEL_PROFILES,
-  renderClaudeApproachExplorer,
-  renderClaudePlanChecker,
-  renderClaudePlanCommand,
-  renderClaudePlanSkill,
-} from '../adapters/claude.mjs';
-import {
-  renderOpenCodeApproachExplorer,
-  renderOpenCodePlanChecker,
-  renderOpenCodePlanCommand,
-} from '../adapters/opencode.mjs';
-import {
-  renderCodexApproachExplorer,
-  renderCodexPlanChecker,
-} from '../adapters/codex.mjs';
+import {
+  CLAUDE_MODEL_PROFILES,
+  renderClaudeApproachExplorer,
+  renderClaudePlanChecker,
+  renderClaudePlanCommand,
+  renderClaudePlanSkill,
+} from '../adapters/claude.mjs';
+import {
+  renderOpenCodeApproachExplorer,
+  renderOpenCodePlanChecker,
+  renderOpenCodePlanCommand,
+} from '../adapters/opencode.mjs';
+import {
+  renderCodexApproachExplorer,
+  renderCodexPlanChecker,
+} from '../adapters/codex.mjs';
 import {
   getRuntimeModelOverride,
   loadProjectModelConfig,
@@ -33,121 +33,121 @@ import {
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const PACKAGE_JSON = JSON.parse(readFileSync(join(__dirname, '..', '..', 'package.json'), 'utf-8'));
-
-function normalizeContent(content) {
-  return String(content).replace(/\r\n/g, '\n');
-}
-
-function compareGeneratedFile({ cwd, runtime, relativePath, expectedContent, repairCommand }) {
-  const absolutePath = join(cwd, relativePath);
-  if (!existsSync(absolutePath)) {
-    return {
-      runtime,
-      relativePath,
-      status: 'missing',
-      repairCommand,
-    };
-  }
-
-  const actualContent = normalizeContent(readFileSync(absolutePath, 'utf-8'));
-  const expected = normalizeContent(expectedContent);
-  if (actualContent === expected) {
-    return {
-      runtime,
-      relativePath,
-      status: 'clean',
-      repairCommand,
-    };
-  }
-
-  return {
-    runtime,
-    relativePath,
-    status: 'stale',
-    repairCommand,
-  };
-}
-
-function buildClaudeEntries({ cwd, workflows }) {
-  const checkerModelAlias = resolveRuntimeAgentModel({
-    cwd,
-    runtime: 'claude',
-    agentId: 'plan-checker',
-    profileMap: CLAUDE_MODEL_PROFILES,
-  });
-  const explorerModelAlias = resolveRuntimeAgentModel({
-    cwd,
-    runtime: 'claude',
-    agentId: 'approach-explorer',
-    profileMap: CLAUDE_MODEL_PROFILES,
-  });
-
-  const entries = workflows.map((workflow) => ({
-    relativePath: `.claude/skills/${workflow.name}/SKILL.md`,
-    expectedContent: workflow.name === 'gsdd-plan'
-      ? renderClaudePlanSkill()
-      : renderSkillContent(workflow),
-  }));
-
-  entries.push(
-    {
-      relativePath: '.claude/commands/gsdd-plan.md',
-      expectedContent: renderClaudePlanCommand(),
-    },
-    {
-      relativePath: '.claude/agents/gsdd-plan-checker.md',
-      expectedContent: renderClaudePlanChecker(getDelegateContent('plan-checker.md'), checkerModelAlias),
-    },
-    {
-      relativePath: '.claude/agents/gsdd-approach-explorer.md',
-      expectedContent: renderClaudeApproachExplorer(getDelegateContent('approach-explorer.md'), explorerModelAlias),
-    }
-  );
-
-  return entries;
-}
-
-function buildOpenCodeEntries({ cwd, workflows }) {
-  const config = loadProjectModelConfig(cwd);
-  const checkerModelId = getRuntimeModelOverride(config, 'opencode', 'plan-checker');
-  const explorerModelId = getRuntimeModelOverride(config, 'opencode', 'approach-explorer');
-
-  const entries = workflows.map((workflow) => ({
-    relativePath: `.opencode/commands/${workflow.name}.md`,
-    expectedContent: workflow.name === 'gsdd-plan'
-      ? renderOpenCodePlanCommand()
-      : renderOpenCodeCommandContent(workflow),
-  }));
-
-  entries.push(
-    {
-      relativePath: '.opencode/agents/gsdd-plan-checker.md',
-      expectedContent: renderOpenCodePlanChecker(getDelegateContent('plan-checker.md'), checkerModelId),
-    },
-    {
-      relativePath: '.opencode/agents/gsdd-approach-explorer.md',
-      expectedContent: renderOpenCodeApproachExplorer(getDelegateContent('approach-explorer.md'), explorerModelId),
-    }
-  );
-
-  return entries;
-}
-
+
+function normalizeContent(content) {
+  return String(content).replace(/\r\n/g, '\n');
+}
+
+function compareGeneratedFile({ cwd, runtime, relativePath, expectedContent, repairCommand }) {
+  const absolutePath = join(cwd, relativePath);
+  if (!existsSync(absolutePath)) {
+    return {
+      runtime,
+      relativePath,
+      status: 'missing',
+      repairCommand,
+    };
+  }
+
+  const actualContent = normalizeContent(readFileSync(absolutePath, 'utf-8'));
+  const expected = normalizeContent(expectedContent);
+  if (actualContent === expected) {
+    return {
+      runtime,
+      relativePath,
+      status: 'clean',
+      repairCommand,
+    };
+  }
+
+  return {
+    runtime,
+    relativePath,
+    status: 'stale',
+    repairCommand,
+  };
+}
+
+function buildClaudeEntries({ cwd, workflows }) {
+  const checkerModelAlias = resolveRuntimeAgentModel({
+    cwd,
+    runtime: 'claude',
+    agentId: 'plan-checker',
+    profileMap: CLAUDE_MODEL_PROFILES,
+  });
+  const explorerModelAlias = resolveRuntimeAgentModel({
+    cwd,
+    runtime: 'claude',
+    agentId: 'approach-explorer',
+    profileMap: CLAUDE_MODEL_PROFILES,
+  });
+
+  const entries = workflows.map((workflow) => ({
+    relativePath: `.claude/skills/${workflow.name}/SKILL.md`,
+    expectedContent: workflow.name === 'gsdd-plan'
+      ? renderClaudePlanSkill()
+      : renderSkillContent(workflow),
+  }));
+
+  entries.push(
+    {
+      relativePath: '.claude/commands/gsdd-plan.md',
+      expectedContent: renderClaudePlanCommand(),
+    },
+    {
+      relativePath: '.claude/agents/gsdd-plan-checker.md',
+      expectedContent: renderClaudePlanChecker(getDelegateContent('plan-checker.md'), checkerModelAlias),
+    },
+    {
+      relativePath: '.claude/agents/gsdd-approach-explorer.md',
+      expectedContent: renderClaudeApproachExplorer(getDelegateContent('approach-explorer.md'), explorerModelAlias),
+    }
+  );
+
+  return entries;
+}
+
+function buildOpenCodeEntries({ cwd, workflows }) {
+  const config = loadProjectModelConfig(cwd);
+  const checkerModelId = getRuntimeModelOverride(config, 'opencode', 'plan-checker');
+  const explorerModelId = getRuntimeModelOverride(config, 'opencode', 'approach-explorer');
+
+  const entries = workflows.map((workflow) => ({
+    relativePath: `.opencode/commands/${workflow.name}.md`,
+    expectedContent: workflow.name === 'gsdd-plan'
+      ? renderOpenCodePlanCommand()
+      : renderOpenCodeCommandContent(workflow),
+  }));
+
+  entries.push(
+    {
+      relativePath: '.opencode/agents/gsdd-plan-checker.md',
+      expectedContent: renderOpenCodePlanChecker(getDelegateContent('plan-checker.md'), checkerModelId),
+    },
+    {
+      relativePath: '.opencode/agents/gsdd-approach-explorer.md',
+      expectedContent: renderOpenCodeApproachExplorer(getDelegateContent('approach-explorer.md'), explorerModelId),
+    }
+  );
+
+  return entries;
+}
+
 function buildCodexEntries({ cwd }) {
-  const config = loadProjectModelConfig(cwd);
-  const checkerModelId = getRuntimeModelOverride(config, 'codex', 'plan-checker');
-  const explorerModelId = getRuntimeModelOverride(config, 'codex', 'approach-explorer');
-
-  return [
-    {
-      relativePath: '.codex/agents/gsdd-plan-checker.toml',
-      expectedContent: renderCodexPlanChecker(getDelegateContent('plan-checker.md'), checkerModelId),
-    },
-    {
-      relativePath: '.codex/agents/gsdd-approach-explorer.toml',
-      expectedContent: renderCodexApproachExplorer(getDelegateContent('approach-explorer.md'), explorerModelId),
-    },
-  ];
+  const config = loadProjectModelConfig(cwd);
+  const checkerModelId = getRuntimeModelOverride(config, 'codex', 'plan-checker');
+  const explorerModelId = getRuntimeModelOverride(config, 'codex', 'approach-explorer');
+
+  return [
+    {
+      relativePath: '.codex/agents/gsdd-plan-checker.toml',
+      expectedContent: renderCodexPlanChecker(getDelegateContent('plan-checker.md'), checkerModelId),
+    },
+    {
+      relativePath: '.codex/agents/gsdd-approach-explorer.toml',
+      expectedContent: renderCodexApproachExplorer(getDelegateContent('approach-explorer.md'), explorerModelId),
+    },
+  ];
 }
 
 function buildWorkspaceHelperEntries() {
@@ -166,43 +166,43 @@ export function collectExpectedRuntimeSurfaceGroups({ cwd = process.cwd(), workf
       runtime: 'workspace-helper',
       label: 'workspace workflow helper',
       root: '.planning/bin',
-      repairCommand: 'gsdd update',
+      repairCommand: 'npx -y gsdd-cli update',
       entries: buildWorkspaceHelperEntries(),
     },
     {
       runtime: 'portable',
       label: 'portable skills',
-      root: '.agents/skills',
-      repairCommand: 'gsdd update',
-      entries: buildPortableSkillEntries(workflows).map((entry) => ({
-        relativePath: entry.relativePath,
-        expectedContent: entry.content,
-      })),
-    },
-    {
-      runtime: 'claude',
-      label: 'Claude Code native surfaces',
-      root: '.claude',
-      repairCommand: 'gsdd update --tools claude',
-      entries: buildClaudeEntries({ cwd, workflows }),
-    },
-    {
-      runtime: 'opencode',
-      label: 'OpenCode native surfaces',
-      root: '.opencode',
-      repairCommand: 'gsdd update --tools opencode',
-      entries: buildOpenCodeEntries({ cwd, workflows }),
-    },
-    {
-      runtime: 'codex',
-      label: 'Codex CLI native agents',
-      root: '.codex',
-      repairCommand: 'gsdd update --tools codex',
-      entries: buildCodexEntries({ cwd }),
-    },
-  ];
-}
-
+      root: '.agents/skills',
+      repairCommand: 'npx -y gsdd-cli update',
+      entries: buildPortableSkillEntries(workflows).map((entry) => ({
+        relativePath: entry.relativePath,
+        expectedContent: entry.content,
+      })),
+    },
+    {
+      runtime: 'claude',
+      label: 'Claude Code native surfaces',
+      root: '.claude',
+      repairCommand: 'npx -y gsdd-cli update --tools claude',
+      entries: buildClaudeEntries({ cwd, workflows }),
+    },
+    {
+      runtime: 'opencode',
+      label: 'OpenCode native surfaces',
+      root: '.opencode',
+      repairCommand: 'npx -y gsdd-cli update --tools opencode',
+      entries: buildOpenCodeEntries({ cwd, workflows }),
+    },
+    {
+      runtime: 'codex',
+      label: 'Codex CLI native agents',
+      root: '.codex',
+      repairCommand: 'npx -y gsdd-cli update --tools codex',
+      entries: buildCodexEntries({ cwd }),
+    },
+  ];
+}
+
 export function evaluateRuntimeFreshness({ cwd = process.cwd(), workflows = [] }) {
   const groups = collectExpectedRuntimeSurfaceGroups({ cwd, workflows }).map((group) => {
     const installed = group.runtime === 'workspace-helper'
@@ -210,55 +210,55 @@ export function evaluateRuntimeFreshness({ cwd = process.cwd(), workflows = [] }
       : existsSync(join(cwd, group.root));
     const comparisons = installed
       ? group.entries.map((entry) => compareGeneratedFile({
-        cwd,
-        runtime: group.runtime,
-        relativePath: entry.relativePath,
-        expectedContent: entry.expectedContent,
-        repairCommand: group.repairCommand,
-      }))
-      : [];
-
-    const stale = comparisons.filter((entry) => entry.status === 'stale');
-    const missing = comparisons.filter((entry) => entry.status === 'missing');
-
-    return {
-      ...group,
-      installed,
-      comparisons,
-      stale,
-      missing,
-      issueCount: stale.length + missing.length,
-    };
-  });
-
-  const checkedGroups = groups.filter((group) => group.installed);
-  const issues = checkedGroups.flatMap((group) => group.comparisons.filter((entry) => entry.status !== 'clean'));
-
-  return {
-    groups,
-    checkedGroups: checkedGroups.map((group) => group.runtime),
-    hasInstalledRuntimeSurfaces: checkedGroups.length > 0,
-    issueCount: issues.length,
-    staleCount: issues.filter((entry) => entry.status === 'stale').length,
-    missingCount: issues.filter((entry) => entry.status === 'missing').length,
-    issues,
-  };
-}
-
-export function summarizeRuntimeFreshnessIssues(report, limit = 4) {
-  if (!report || report.issueCount === 0) return '';
-  const listed = report.issues
-    .slice(0, limit)
-    .map((entry) => `${entry.relativePath} [${entry.status}]`);
-  const remainder = report.issueCount - listed.length;
-  return remainder > 0 ? `${listed.join(', ')} (+${remainder} more)` : listed.join(', ');
-}
-
-export function getRuntimeFreshnessRepairGuidance(report) {
-  if (!report || report.issueCount === 0) return 'Run `gsdd update` to regenerate installed runtime surfaces.';
-  const commands = [...new Set(report.issues.map((entry) => entry.repairCommand))];
-  if (commands.length === 1) {
-    return `Run \`${commands[0]}\` to regenerate the installed runtime surfaces.`;
-  }
-  return `Run \`gsdd update\` to regenerate all installed runtime surfaces, or target the affected adapters individually: ${commands.map((command) => `\`${command}\``).join(', ')}.`;
-}
+        cwd,
+        runtime: group.runtime,
+        relativePath: entry.relativePath,
+        expectedContent: entry.expectedContent,
+        repairCommand: group.repairCommand,
+      }))
+      : [];
+
+    const stale = comparisons.filter((entry) => entry.status === 'stale');
+    const missing = comparisons.filter((entry) => entry.status === 'missing');
+
+    return {
+      ...group,
+      installed,
+      comparisons,
+      stale,
+      missing,
+      issueCount: stale.length + missing.length,
+    };
+  });
+
+  const checkedGroups = groups.filter((group) => group.installed);
+  const issues = checkedGroups.flatMap((group) => group.comparisons.filter((entry) => entry.status !== 'clean'));
+
+  return {
+    groups,
+    checkedGroups: checkedGroups.map((group) => group.runtime),
+    hasInstalledRuntimeSurfaces: checkedGroups.length > 0,
+    issueCount: issues.length,
+    staleCount: issues.filter((entry) => entry.status === 'stale').length,
+    missingCount: issues.filter((entry) => entry.status === 'missing').length,
+    issues,
+  };
+}
+
+export function summarizeRuntimeFreshnessIssues(report, limit = 4) {
+  if (!report || report.issueCount === 0) return '';
+  const listed = report.issues
+    .slice(0, limit)
+    .map((entry) => `${entry.relativePath} [${entry.status}]`);
+  const remainder = report.issueCount - listed.length;
+  return remainder > 0 ? `${listed.join(', ')} (+${remainder} more)` : listed.join(', ');
+}
+
+export function getRuntimeFreshnessRepairGuidance(report) {
+  if (!report || report.issueCount === 0) return 'Run `npx -y gsdd-cli update` to regenerate installed runtime surfaces.';
+  const commands = [...new Set(report.issues.map((entry) => entry.repairCommand))];
+  if (commands.length === 1) {
+    return `Run \`${commands[0]}\` to regenerate the installed runtime surfaces.`;
+  }
+  return `Run \`npx -y gsdd-cli update\` to regenerate all installed runtime surfaces, or target the affected adapters individually: ${commands.map((command) => `\`${command}\``).join(', ')}.`;
+}

package/bin/lib/session-fingerprint.mjs

@@ -11,9 +11,13 @@
 import { createHash } from 'crypto';
 import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
+import { output } from './cli-utils.mjs';
+import { resolveWorkspaceContext } from './workspace-root.mjs';
 
 const FINGERPRINT_FILE = '.state-fingerprint.json';
 const FINGERPRINT_SOURCES = ['ROADMAP.md', 'SPEC.md', 'config.json'];
+const FINGERPRINT_SCHEMA_VERSION = 2;
+const FINGERPRINT_ALGORITHM = 'sha256:v2:exists-content';
 
 /**
  * Compute a SHA-256 fingerprint from the planning truth files.
@@ -23,15 +27,52 @@ const FINGERPRINT_SOURCES = ['ROADMAP.md', 'SPEC.md', 'config.json'];
 export function computeFingerprint(planningDir) {
   const hash = createHash('sha256');
   const sources = {};
+  const files = {};
   for (const file of FINGERPRINT_SOURCES) {
     const filePath = join(planningDir, file);
-    const content = existsSync(filePath) ? readFileSync(filePath, 'utf-8') : '';
+    const exists = existsSync(filePath);
+    const content = exists ? readFileSync(filePath, 'utf-8') : '';
+    hash.update(`${file}:${exists ? 'exists' : 'missing'}:${content}\n`);
+    sources[file] = exists;
+    files[file] = {
+      exists,
+      hash: createHash('sha256').update(content).digest('hex'),
+    };
+  }
+  return { hash: hash.digest('hex'), sources, files };
+}
+
+function computeLegacyFingerprint(planningDir) {
+  const hash = createHash('sha256');
+  const sources = {};
+  for (const file of FINGERPRINT_SOURCES) {
+    const filePath = join(planningDir, file);
+    const exists = existsSync(filePath);
+    const content = exists ? readFileSync(filePath, 'utf-8') : '';
     hash.update(`${file}:${content}\n`);
-    sources[file] = existsSync(filePath);
+    sources[file] = exists;
   }
   return { hash: hash.digest('hex'), sources };
 }
 
+export function cmdSessionFingerprint(...args) {
+  const { args: normalizedArgs, planningDir, invalid, error } = resolveWorkspaceContext(args);
+  if (invalid) {
+    console.error(error);
+    process.exitCode = 1;
+    return;
+  }
+
+  const [action] = normalizedArgs;
+  if (action !== 'write') {
+    console.error('Usage: node .planning/bin/gsdd.mjs session-fingerprint write');
+    process.exitCode = 1;
+    return;
+  }
+
+  output({ operation: 'session-fingerprint write', fingerprint: writeFingerprint(planningDir) });
+}
+
 /**
  * Read the stored fingerprint from .planning/.state-fingerprint.json.
  * Returns null if the file does not exist or is unparseable.
@@ -50,10 +91,13 @@ export function readStoredFingerprint(planningDir) {
  * Write the current fingerprint to .planning/.state-fingerprint.json.
  */
 export function writeFingerprint(planningDir) {
-  const { hash, sources } = computeFingerprint(planningDir);
+  const { hash, sources, files } = computeFingerprint(planningDir);
   const data = {
+    schemaVersion: FINGERPRINT_SCHEMA_VERSION,
+    algorithm: FINGERPRINT_ALGORITHM,
     hash,
     sources,
+    files,
     timestamp: new Date().toISOString(),
   };
   writeFileSync(join(planningDir, FINGERPRINT_FILE), JSON.stringify(data, null, 2) + '\n');
@@ -69,27 +113,33 @@ export function writeFingerprint(planningDir) {
  */
 export function checkDrift(planningDir) {
   const stored = readStoredFingerprint(planningDir);
-  const { hash: currentHash, sources: currentSources } = computeFingerprint(planningDir);
+  const { hash: currentHash, sources: currentSources, files: currentFiles } = computeFingerprint(planningDir);
 
   if (!stored) {
     return {
       drifted: false,
       noBaseline: true,
+      classification: 'no_baseline',
       details: ['No stored fingerprint found — first session or fingerprint was cleared.'],
       stored: null,
-      current: { hash: currentHash, sources: currentSources },
+      current: { hash: currentHash, sources: currentSources, files: currentFiles },
+      files: [],
     };
   }
 
-  const drifted = stored.hash !== currentHash;
+  const isLegacy = !stored.schemaVersion && !stored.files;
+  const comparison = isLegacy ? computeLegacyFingerprint(planningDir) : { hash: currentHash };
+  const drifted = stored.hash !== comparison.hash;
   const details = [];
+  const files = drifted
+    ? FINGERPRINT_SOURCES.map((file) => classifyFileDrift(file, stored, currentSources, currentFiles, { legacy: isLegacy }))
+    : FINGERPRINT_SOURCES.map((file) => ({ file, status: 'unchanged' }));
   if (drifted) {
-    for (const file of FINGERPRINT_SOURCES) {
-      const was = stored.sources?.[file] ?? false;
-      const now = currentSources[file];
-      if (was && !now) details.push(`${file} was removed`);
-      else if (!was && now) details.push(`${file} was created`);
-      else if (was && now) details.push(`${file} may have changed`);
+    for (const file of files) {
+      if (file.status === 'created') details.push(`${file.file} created`);
+      else if (file.status === 'removed') details.push(`${file.file} removed`);
+      else if (file.status === 'changed') details.push(`${file.file} changed`);
+      else if (file.status === 'unknown') details.push(`${file.file} may have changed`);
     }
     if (details.length === 0) {
       details.push('Planning state hash changed since last recorded session.');
@@ -99,8 +149,35 @@ export function checkDrift(planningDir) {
   return {
     drifted,
     noBaseline: false,
+    classification: drifted ? 'planning_state_drift' : 'clean',
+    compatibility: isLegacy ? 'legacy_v1' : null,
+    needsBaselineRefresh: isLegacy && !drifted,
     details,
-    stored: { hash: stored.hash, timestamp: stored.timestamp },
-    current: { hash: currentHash, sources: currentSources },
+    files,
+    stored: {
+      hash: stored.hash,
+      timestamp: stored.timestamp,
+      schemaVersion: stored.schemaVersion ?? null,
+      algorithm: stored.algorithm ?? null,
+      files: stored.files ?? null,
+    },
+    current: { hash: currentHash, sources: currentSources, files: currentFiles },
+  };
+}
+
+function classifyFileDrift(file, stored, currentSources, currentFiles, { legacy = false } = {}) {
+  const was = stored.sources?.[file] ?? false;
+  const now = currentSources[file];
+
+  if (was && !now) return { file, status: 'removed' };
+  if (!was && now) return { file, status: 'created' };
+  if (!was && !now) return { file, status: 'unchanged' };
+  if (legacy) return { file, status: 'unknown' };
+
+  const storedFile = stored.files?.[file];
+  if (!storedFile?.hash) return { file, status: 'unknown' };
+  return {
+    file,
+    status: storedFile.hash === currentFiles[file].hash ? 'unchanged' : 'changed',
   };
 }