gsdd-cli 0.3.1 → 0.18.0

package/bin/lib/phase.mjs

@@ -6,10 +6,82 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from 'fs';
 import { join, basename } from 'path';
 import { output } from './cli-utils.mjs';
+import { writeFingerprint } from './session-fingerprint.mjs';
+
+const PHASE_STATUS_MARKERS = {
+  not_started: '[ ]',
+  todo: '[ ]',
+  in_progress: '[-]',
+  done: '[x]',
+};
+
+const PHASE_MARKER_RE = '(\\[[ x]\\]|\\[-\\]|⬜|ðŸ"„|✅|⬜|🔄|✅)';
+const PHASE_TOKEN_RE = '(\\d+(?:\\.\\d+)*[a-z]?)';
+const PHASE_LINE_RE = new RegExp(
+  `^[-*]\\s*${PHASE_MARKER_RE}\\s*\\*\\*Phase\\s+${PHASE_TOKEN_RE}:\\s*(.+?)\\*\\*`,
+  'i'
+);
+const ROADMAP_PHASE_STATUS_RE = new RegExp(
+  `^(\\s*[-*]\\s*)${PHASE_MARKER_RE}(\\s*\\*\\*Phase\\s+${PHASE_TOKEN_RE}:.*)$`,
+  'i'
+);
 
 function findFiles(dir, prefix) {
   if (!existsSync(dir)) return [];
-  return readdirSync(dir).filter((f) => f.startsWith(prefix) || f.startsWith(prefix.replace(/^0+/, '')));
+
+  const phaseArtifactPrefix = String(prefix).match(/^(\d+(?:\.\d+)*[a-z]?)-(PLAN|SUMMARY)$/i);
+  if (!phaseArtifactPrefix) {
+    return readdirSync(dir).filter((f) => f.startsWith(prefix) || f.startsWith(prefix.replace(/^0+/, '')));
+  }
+
+  const targetPhase = normalizePhaseToken(phaseArtifactPrefix[1]);
+  const targetKind = phaseArtifactPrefix[2].toUpperCase();
+
+  return listPhaseArtifacts(dir)
+    .filter((artifact) => artifact.phaseToken === targetPhase && artifact.kind === targetKind)
+    .map((artifact) => artifact.displayPath);
+}
+
+function listPhaseArtifacts(dir) {
+  if (!existsSync(dir)) return [];
+
+  const artifacts = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isFile()) {
+      const artifact = classifyPhaseArtifact('', entry.name);
+      if (artifact) artifacts.push(artifact);
+      continue;
+    }
+
+    if (!entry.isDirectory()) continue;
+
+    const entryPath = join(dir, entry.name);
+    for (const child of readdirSync(entryPath, { withFileTypes: true })) {
+      if (!child.isFile()) continue;
+      const artifact = classifyPhaseArtifact(entry.name, child.name);
+      if (artifact) artifacts.push(artifact);
+    }
+  }
+
+  return artifacts;
+}
+
+function classifyPhaseArtifact(dir, name) {
+  const dirMatch = dir ? dir.match(/^(\d+(?:\.\d+)*[a-z]?)-/i) : null;
+  const nameMatch = name.match(/^(\d+(?:\.\d+)*[a-z]?)/i);
+  const phaseToken = normalizePhaseToken((dirMatch || nameMatch)?.[1] || '');
+
+  let kind = 'OTHER';
+  if (name.includes('PLAN')) kind = 'PLAN';
+  else if (name.includes('SUMMARY')) kind = 'SUMMARY';
+
+  return {
+    dir,
+    name,
+    displayPath: dir ? `${dir}/${name}` : name,
+    phaseToken,
+    kind,
+  };
 }
 
 function padPhase(n) {
@@ -20,13 +92,7 @@ function parsePhaseStatuses(roadmap) {
   const phases = [];
   const lines = roadmap.split('\n');
   for (const line of lines) {
-    // Supports:
-    // - checkbox statuses: [ ] / [x]
-    // - legacy emoji markers in ROADMAP templates: not started / in progress / done
-    // - mojibake-encoded variants that exist in some files
-    const match = line.match(
-      /^[-*]\s*(\[[ x]\]|\[-\]|⬜|ðŸ"„|✅|⬜|🔄|✅)\s*\*\*Phase\s+(\d+):\s*(.+?)\*\*/i
-    );
+    const match = line.match(PHASE_LINE_RE);
     if (match) {
       const rawStatus = match[1].toLowerCase();
       let status = 'not_started';
@@ -34,7 +100,7 @@ function parsePhaseStatuses(roadmap) {
       else if (rawStatus === '[-]') status = 'in_progress';
       else if (rawStatus === 'ðÿ"„' || rawStatus === '🔄') status = 'in_progress';
       phases.push({
-        number: parseInt(match[2], 10),
+        number: match[2],
         name: match[3].replace(/\*\*/g, '').split('-')[0].trim(),
         status,
       });
@@ -43,6 +109,81 @@ function parsePhaseStatuses(roadmap) {
   return phases;
 }
 
+function normalizePhaseToken(value) {
+  const raw = String(value).trim().toLowerCase();
+  const match = raw.match(/^(\d+(?:\.\d+)*)([a-z]?)$/i);
+  if (!match) return raw;
+
+  const numericSegments = match[1]
+    .split('.')
+    .map((segment) => String(parseInt(segment, 10)));
+  return `${numericSegments.join('.')}${match[2] || ''}`;
+}
+
+export function updateRoadmapPhaseStatus(roadmap, phaseNumber, status) {
+  const marker = PHASE_STATUS_MARKERS[status];
+  if (!marker) {
+    throw new Error(`Unsupported phase status: ${status}`);
+  }
+
+  const normalizedTarget = normalizePhaseToken(phaseNumber);
+  let matchCount = 0;
+
+  const updated = roadmap
+    .split('\n')
+    .map((line) => {
+      const match = line.match(ROADMAP_PHASE_STATUS_RE);
+      if (!match) return line;
+      if (normalizePhaseToken(match[4]) !== normalizedTarget) return line;
+      matchCount += 1;
+      return `${match[1]}${marker}${match[3]}`;
+    })
+    .join('\n');
+
+  if (matchCount === 0) {
+    throw new Error(`Phase ${phaseNumber} was not found in ROADMAP.md`);
+  }
+
+  if (matchCount > 1) {
+    throw new Error(`Phase ${phaseNumber} matched multiple ROADMAP.md entries`);
+  }
+
+  return updated;
+}
+
+export function cmdPhaseStatus(...args) {
+  const cwd = process.cwd();
+  const planningDir = join(cwd, '.planning');
+  const roadmapPath = join(planningDir, 'ROADMAP.md');
+  const [phaseNumber, status] = args;
+
+  if (!phaseNumber || !status) {
+    console.error('Usage: gsdd phase-status <phase-number> <not_started|todo|in_progress|done>');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (!existsSync(roadmapPath)) {
+    console.error('No ROADMAP.md found. Run the new-project workflow first.');
+    process.exitCode = 1;
+    return;
+  }
+
+  try {
+    const roadmap = readFileSync(roadmapPath, 'utf-8');
+    const updated = updateRoadmapPhaseStatus(roadmap, phaseNumber, status);
+    const changed = updated !== roadmap;
+    if (changed) {
+      writeFileSync(roadmapPath, updated);
+      try { writeFingerprint(planningDir); } catch { /* best-effort */ }
+    }
+    output({ phase: phaseNumber, status, roadmap: '.planning/ROADMAP.md', changed });
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+
 export function cmdFindPhase(...args) {
   const cwd = process.cwd();
   const planningDir = join(cwd, '.planning');
@@ -67,7 +208,7 @@ export function cmdFindPhase(...args) {
     const summaries = findFiles(phasesDir, `${padPhase(phaseNum)}-SUMMARY`);
 
     output({
-      phase: parseInt(phaseNum, 10),
+      phase: normalizePhaseToken(phaseNum),
       directory: phasesDir,
       plans,
       summaries,
@@ -77,9 +218,9 @@ export function cmdFindPhase(...args) {
     return;
   }
 
-  const allFiles = existsSync(phasesDir) ? readdirSync(phasesDir) : [];
-  const plans = allFiles.filter((f) => f.includes('PLAN'));
-  const summaries = allFiles.filter((f) => f.includes('SUMMARY'));
+  const allArtifacts = listPhaseArtifacts(phasesDir);
+  const plans = allArtifacts.filter((artifact) => artifact.kind === 'PLAN');
+  const summaries = allArtifacts.filter((artifact) => artifact.kind === 'SUMMARY');
 
   const roadmap = readFileSync(roadmapPath, 'utf-8');
   const phases = parsePhaseStatuses(roadmap);
@@ -99,18 +240,18 @@ export function cmdVerify(...args) {
   const phaseNum = args[0];
   if (!phaseNum) {
     console.error('Usage: gsdd verify <phase-number>');
-    process.exit(1);
+    process.exitCode = 1; return;
   }
 
   if (!existsSync(planningDir)) {
     console.error('No .planning/ directory found.');
-    process.exit(1);
+    process.exitCode = 1; return;
   }
 
   const planFile = findFiles(join(planningDir, 'phases'), `${padPhase(phaseNum)}-PLAN`)[0];
   if (!planFile) {
     console.error(`No plan found for phase ${phaseNum}`);
-    process.exit(1);
+    process.exitCode = 1; return;
   }
 
   const planPath = join(planningDir, 'phases', planFile);
@@ -183,14 +324,14 @@ export function cmdScaffold(...args) {
 
   if (type !== 'phase') {
     console.error('Usage: gsdd scaffold phase <number> [name]');
-    process.exit(1);
+    process.exitCode = 1; return;
   }
 
   const phaseNum = rest[0];
   const phaseName = rest.slice(1).join(' ');
   if (!phaseNum) {
     console.error('Usage: gsdd scaffold phase <number> [name]');
-    process.exit(1);
+    process.exitCode = 1; return;
   }
 
   const phasesDir = join(planningDir, 'phases');

package/bin/lib/plan-constants.mjs

@@ -0,0 +1,30 @@
+export const PLAN_CHECK_DIMENSIONS = [
+  'requirement_coverage',
+  'task_completeness',
+  'dependency_correctness',
+  'key_link_completeness',
+  'scope_sanity',
+  'must_have_quality',
+  'context_compliance',
+  'goal_achievement',
+  'approach_alignment',
+];
+
+export const MAX_CHECKER_CYCLES = 3;
+
+export const CHECKER_STATUSES = ['passed', 'issues_found'];
+
+export const CHECKER_JSON_SCHEMA = {
+  status: 'passed | issues_found',
+  summary: 'string',
+  issues: [
+    {
+      dimension: 'string',
+      severity: 'blocker | warning',
+      description: 'string',
+      plan: 'string',
+      task: 'string',
+      fix_hint: 'string',
+    },
+  ],
+};

package/bin/lib/provenance.mjs

@@ -0,0 +1,165 @@
+function normalizePrState(prState) {
+  if (!prState) return 'none';
+  return String(prState).trim().toLowerCase();
+}
+
+function normalizeCount(value) {
+  if (value === 'unknown' || value === null || value === undefined) return 'unknown';
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : 'unknown';
+}
+
+function normalizeCheckpointWorkflow(workflow) {
+  const normalized = String(workflow || 'generic').trim().toLowerCase();
+  return ['phase', 'quick', 'generic'].includes(normalized) ? normalized : 'generic';
+}
+
+export function classifyCheckpointRouting(workflow) {
+  const normalizedWorkflow = normalizeCheckpointWorkflow(workflow);
+  const progressBlocks = normalizedWorkflow === 'phase' || normalizedWorkflow === 'quick';
+
+  return {
+    workflow: normalizedWorkflow,
+    routingClass: progressBlocks ? 'blocking' : 'informational',
+    progressBlocks,
+    resumeOwnsCleanup: true,
+  };
+}
+
+export function parseGitStatusShort(statusText = '') {
+  const lines = statusText
+    .replace(/\r\n/g, '\n')
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter(Boolean);
+
+  const files = [];
+  for (const line of lines) {
+    const match = line.match(/^(.)(.)\s+(.+)$/);
+    if (!match) continue;
+
+    const indexStatus = match[1];
+    const worktreeStatus = match[2];
+    if (indexStatus === '!' && worktreeStatus === '!') continue;
+
+    const filePath = match[3].replace(/\\/g, '/');
+    files.push({
+      path: filePath,
+      staged: indexStatus !== ' ' && indexStatus !== '?' && indexStatus !== '!',
+      unstaged: worktreeStatus !== ' ' && worktreeStatus !== '?' && worktreeStatus !== '!',
+      untracked: indexStatus === '?' || worktreeStatus === '?',
+    });
+  }
+
+  return {
+    files,
+    stagedCount: files.filter((file) => file.staged).length,
+    unstagedCount: files.filter((file) => file.unstaged).length,
+    untrackedCount: files.filter((file) => file.untracked).length,
+    dirty: files.length > 0,
+  };
+}
+
+export function buildProvenanceSnapshot({
+  checkpoint = {},
+  planning = {},
+  git = {},
+} = {}) {
+  const checkpointRouting = classifyCheckpointRouting(checkpoint.workflow);
+  const status = parseGitStatusShort(git.statusShort || '');
+  const commitsAheadOfMain = normalizeCount(git.commitsAheadOfMain);
+  const commitsAheadOfRemote = normalizeCount(git.commitsAheadOfRemote);
+  const prState = normalizePrState(git.prState);
+
+  const warnings = [];
+
+  if (status.dirty) {
+    warnings.push({
+      id: 'dirty_worktree',
+      severity: 'warning',
+      summary: 'Local worktree contains staged, unstaged, or untracked changes.',
+    });
+  }
+
+  if (commitsAheadOfMain !== 'unknown' && commitsAheadOfMain > 0) {
+    warnings.push({
+      id: 'ahead_of_main',
+      severity: 'warning',
+      summary: `${commitsAheadOfMain} commit(s) are ahead of main on the current branch.`,
+    });
+  }
+
+  if (commitsAheadOfRemote !== 'unknown' && commitsAheadOfRemote > 0) {
+    warnings.push({
+      id: 'unpushed_commits',
+      severity: 'warning',
+      summary: `${commitsAheadOfRemote} commit(s) are ahead of the tracked remote branch.`,
+    });
+  }
+
+  if (prState === 'none') {
+    warnings.push({
+      id: 'missing_pr',
+      severity: 'warning',
+      summary: 'No pull request is associated with the current branch.',
+    });
+  }
+
+  if (git.staleBranch) {
+    warnings.push({
+      id: 'stale_branch',
+      severity: 'warning',
+      summary: 'The current branch is stale or spent relative to the intended integration surface.',
+    });
+  }
+
+  if (git.mixedScope) {
+    warnings.push({
+      id: 'mixed_scope',
+      severity: 'warning',
+      summary: 'The current worktree appears to mix multiple write scopes or phases.',
+    });
+  }
+
+  if (git.materialCheckpointMismatch) {
+    warnings.push({
+      id: 'checkpoint_mismatch',
+      severity: 'acknowledgement_required',
+      summary: 'Checkpoint narrative truth materially understates or conflicts with the live branch/worktree truth.',
+    });
+  }
+
+  return {
+    checkpoint: {
+      workflow: checkpointRouting.workflow,
+      phase: checkpoint.phase ?? null,
+      runtime: checkpoint.runtime || 'unknown',
+      hasNarrative: Boolean(checkpoint.hasNarrative),
+      routing: checkpointRouting,
+    },
+    planning: {
+      currentPhase: planning.currentPhase || null,
+      nextPhase: planning.nextPhase || null,
+      completedPhaseCount: Number.isFinite(Number(planning.completedPhaseCount))
+        ? Number(planning.completedPhaseCount)
+        : 0,
+    },
+    git: {
+      branch: git.branch || 'unknown',
+      prState,
+      commitsAheadOfMain,
+      commitsAheadOfRemote,
+      stagedCount: status.stagedCount,
+      unstagedCount: status.unstagedCount,
+      untrackedCount: status.untrackedCount,
+      dirty: status.dirty,
+    },
+    integrationSurface: {
+      staleBranch: Boolean(git.staleBranch),
+      mixedScope: Boolean(git.mixedScope),
+      materialCheckpointMismatch: Boolean(git.materialCheckpointMismatch),
+    },
+    warnings,
+    requiresAcknowledgement: warnings.some((warning) => warning.severity === 'acknowledgement_required'),
+  };
+}

package/bin/lib/rendering.mjs

@@ -30,6 +30,13 @@ agent: ${workflow.agent}
 ${workflowContent}`;
 }
 
+function buildPortableSkillEntries(workflows) {
+  return workflows.map((workflow) => ({
+    relativePath: `.agents/skills/${workflow.name}/SKILL.md`,
+    content: renderSkillContent(workflow),
+  }));
+}
+
 function renderOpenCodeCommandContent(workflow) {
   const workflowContent = getWorkflowContent(workflow.workflow);
   return `---
@@ -85,6 +92,7 @@ function upsertBoundedBlock(existing, blockContent) {
 }
 
 export {
+  buildPortableSkillEntries,
   getDelegateContent,
   getWorkflowContent,
   renderAgentsBoundedBlock,

package/bin/lib/runtime-freshness.mjs

@@ -0,0 +1,239 @@
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import {
+  buildPortableSkillEntries,
+  getDelegateContent,
+  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 {
+  getRuntimeModelOverride,
+  loadProjectModelConfig,
+  resolveRuntimeAgentModel,
+} from './models.mjs';
+
+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),
+    },
+  ];
+}
+
+export function collectExpectedRuntimeSurfaceGroups({ cwd = process.cwd(), workflows }) {
+  return [
+    {
+      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 }),
+    },
+  ];
+}
+
+export function evaluateRuntimeFreshness({ cwd = process.cwd(), workflows = [] }) {
+  const groups = collectExpectedRuntimeSurfaceGroups({ cwd, workflows }).map((group) => {
+    const installed = 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(', ')}.`;
+}