gsdd-cli 0.3.1 → 0.18.0

package/bin/adapters/opencode.mjs

@@ -1,6 +1,11 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import os from 'os';
 import { join } from 'path';
+import {
+  PLAN_CHECK_DIMENSIONS,
+  MAX_CHECKER_CYCLES,
+  CHECKER_STATUSES,
+} from '../lib/plan-constants.mjs';
 
 function expandHome(filePath) {
   if (!filePath) return filePath;
@@ -115,7 +120,7 @@ function renderOpenCodeApproachExplorer(delegateContent, modelId = null) {
   const modelLine = modelId ? `model: ${modelId}\n` : '';
   return `---
 description: Explores implementation approaches for a phase and aligns with the user through structured questioning before planning begins.
-mode: agent
+mode: subagent
 ${modelLine}tools:
   bash: false
 ---
@@ -183,7 +188,7 @@ Execution flow:
      "summary": "One sentence overall assessment",
      "issues": [
        {
-         "dimension": "requirement_coverage | task_completeness | dependency_correctness | key_link_completeness | scope_sanity | must_have_quality | context_compliance | goal_achievement | approach_alignment",
+         "dimension": "${PLAN_CHECK_DIMENSIONS.join(' | ')}",
          "severity": "blocker | warning",
          "description": "What is wrong",
          "plan": "01-PLAN",
@@ -192,10 +197,10 @@ Execution flow:
        }
      ]
    }
-   Status must be either "passed" or "issues_found".
+   Status must be either "${CHECKER_STATUSES[0]}" or "${CHECKER_STATUSES[1]}".
 9. If the checker returns \`passed\`, finish and summarize.
 10. If the checker returns \`issues_found\`, revise the existing plan files only where needed, then run the checker again.
-11. Maximum 3 checker cycles total. If blockers remain after cycle 3, stop and escalate to the user instead of pretending the plan is ready.
+11. Maximum ${MAX_CHECKER_CYCLES} checker cycles total. If blockers remain after cycle ${MAX_CHECKER_CYCLES}, stop and escalate to the user instead of pretending the plan is ready.
 
 Return a concise orchestration summary:
 - target phase
@@ -223,6 +228,10 @@ function createOpenCodeAdapter({
     id: 'opencode',
     name: 'opencode',
     kind: 'native_capable',
+    subagentFiles: [
+      '.opencode/agents/gsdd-plan-checker.md',
+      '.opencode/agents/gsdd-approach-explorer.md',
+    ],
     detect() {
       return existsSync(join(cwd, '.opencode'));
     },
@@ -260,4 +269,10 @@ function createOpenCodeAdapter({
   };
 }
 
-export { createOpenCodeAdapter, detectOpenCodeConfiguredModel };
+export {
+  createOpenCodeAdapter,
+  detectOpenCodeConfiguredModel,
+  renderOpenCodeApproachExplorer,
+  renderOpenCodePlanChecker,
+  renderOpenCodePlanCommand,
+};

package/bin/gsdd.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-// gsdd - GSD Distilled CLI
+// gsdd - Workspine CLI
 
 import { realpathSync } from 'fs';
 import { join, dirname } from 'path';
@@ -16,8 +16,10 @@ import {
 } from './lib/rendering.mjs';
 import { loadProjectModelConfig, getRuntimeModelOverride, resolveRuntimeAgentModel, cmdModels } from './lib/models.mjs';
 import { createCmdInit, createCmdUpdate, cmdHelp } from './lib/init.mjs';
-import { cmdFindPhase, cmdVerify, cmdScaffold } from './lib/phase.mjs';
+import { cmdFindPhase, cmdVerify, cmdScaffold, cmdPhaseStatus } from './lib/phase.mjs';
+import { cmdFileOp } from './lib/file-ops.mjs';
 import { createCmdHealth } from './lib/health.mjs';
+import { cmdLifecyclePreflight } from './lib/lifecycle-preflight.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -45,14 +47,18 @@ const WORKFLOWS = [
   defineWorkflow({ name: 'gsdd-plan', workflow: 'plan.md', description: 'Plan a phase - research check, backward planning, task creation' }),
   defineWorkflow({ name: 'gsdd-execute', workflow: 'execute.md', description: 'Execute a phase plan - implement tasks, verify changes, follow repo git conventions' }),
   defineWorkflow({ name: 'gsdd-verify', workflow: 'verify.md', description: 'Verify a completed phase - 3-level checks, anti-pattern scan' }),
+  defineWorkflow({ name: 'gsdd-verify-work', workflow: 'verify-work.md', description: 'Conversational UAT testing - validate user-facing behavior with structured gap tracking' }),
   defineWorkflow({ name: 'gsdd-audit-milestone', workflow: 'audit-milestone.md', description: 'Audit a completed milestone - cross-phase integration, requirements coverage, E2E flows' }),
+  defineWorkflow({ name: 'gsdd-complete-milestone', workflow: 'complete-milestone.md', description: 'Complete milestone - archive, evolve spec, collapse roadmap' }),
+  defineWorkflow({ name: 'gsdd-new-milestone', workflow: 'new-milestone.md', description: 'New milestone - gather goals, define requirements, create roadmap phases' }),
+  defineWorkflow({ name: 'gsdd-plan-milestone-gaps', workflow: 'plan-milestone-gaps.md', description: 'Plan gap closure phases from audit results' }),
   defineWorkflow({ name: 'gsdd-quick', workflow: 'quick.md', description: 'Quick task - plan and execute a sub-hour task outside the phase cycle' }),
   defineWorkflow({ name: 'gsdd-pause', workflow: 'pause.md', description: 'Pause work - save session context for seamless resumption' }),
   defineWorkflow({ name: 'gsdd-resume', workflow: 'resume.md', description: 'Resume work - restore context and route to next action' }),
   defineWorkflow({ name: 'gsdd-progress', workflow: 'progress.md', description: 'Check progress - show project status and route to next action', mutatesArtifacts: false }),
 ];
 
-const FRAMEWORK_VERSION = 'v1.2';
+const FRAMEWORK_VERSION = 'v1.4';
 
 function createCliContext(cwd = process.cwd()) {
   return {
@@ -82,31 +88,42 @@ const INIT_CONTEXT = createCliContext(CWD);
 
 const cmdInit = createCmdInit(INIT_CONTEXT);
 const cmdUpdate = createCmdUpdate(INIT_CONTEXT);
-const cmdHealth = createCmdHealth({ frameworkVersion: FRAMEWORK_VERSION });
+const cmdHealth = createCmdHealth(INIT_CONTEXT);
 
 const COMMANDS = {
   init: cmdInit,
   update: cmdUpdate,
   models: cmdModels,
   health: cmdHealth,
+  'file-op': cmdFileOp,
+  'lifecycle-preflight': cmdLifecyclePreflight,
   'find-phase': cmdFindPhase,
+  'phase-status': cmdPhaseStatus,
   verify: cmdVerify,
   scaffold: cmdScaffold,
   help: cmdHelp,
 };
 
-async function runCli(cliCommand = command, cliArgs = args) {
+async function runCli(cliCommand = command, ...cliArgs) {
+  const normalizedArgs = cliArgs.length === 0
+    ? args
+    : cliArgs.length === 1 && Array.isArray(cliArgs[0])
+      ? cliArgs[0]
+      : cliArgs;
+
+  process.exitCode = 0;
+
   if (!cliCommand || !COMMANDS[cliCommand]) {
     cmdHelp();
     if (cliCommand) process.exitCode = 1;
     return;
   }
 
-  await COMMANDS[cliCommand](...cliArgs);
+  await COMMANDS[cliCommand](...normalizedArgs);
 }
 
 if (IS_MAIN) {
   await runCli();
 }
 
-export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFindPhase, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };
+export { cmdHelp, cmdInit, cmdUpdate, cmdModels, cmdHealth, cmdFileOp, cmdLifecyclePreflight, cmdFindPhase, cmdPhaseStatus, cmdVerify, cmdScaffold, runCli, FRAMEWORK_VERSION, createCliContext };

package/bin/lib/cli-utils.mjs

@@ -15,7 +15,7 @@ export function parseFlagValue(flagArgs, flagName) {
 export function parseToolsFlag(flagArgs) {
   const { value } = parseFlagValue(flagArgs, '--tools');
   if (!value) return [];
-  if (value === 'all') return ['claude', 'opencode', 'codex', 'agents'];
+  if (value === 'all') return ['claude', 'opencode', 'codex', 'agents', 'cursor', 'copilot', 'gemini'];
   return value.split(',').map((v) => v.trim()).filter(Boolean);
 }
 

package/bin/lib/evidence-contract.mjs

@@ -0,0 +1,112 @@
+const EVIDENCE_KINDS = Object.freeze(['code', 'test', 'runtime', 'delivery', 'human']);
+const DELIVERY_POSTURES = Object.freeze(['repo_only', 'delivery_sensitive']);
+const CLOSURE_SURFACES = Object.freeze(['verify', 'audit-milestone', 'complete-milestone']);
+
+const LEGACY_EVIDENCE_ALIASES = Object.freeze({
+  code: 'code',
+  test: 'test',
+  runtime: 'runtime',
+  delivery: 'delivery',
+  human: 'human',
+  'code-evidence': 'code',
+  'repo-test': 'test',
+  'runtime-check': 'runtime',
+  'user-confirmation': 'human',
+});
+
+const EVIDENCE_MATRIX = Object.freeze({
+  verify: Object.freeze({
+    repo_only: Object.freeze({
+      requiredKinds: Object.freeze(['code']),
+      recommendedKinds: Object.freeze(['test']),
+      blockedSoloKinds: Object.freeze(['human', 'delivery']),
+    }),
+    delivery_sensitive: Object.freeze({
+      requiredKinds: Object.freeze(['code', 'runtime']),
+      recommendedKinds: Object.freeze(['test', 'delivery', 'human']),
+      blockedSoloKinds: Object.freeze(['code', 'human']),
+    }),
+  }),
+  'audit-milestone': Object.freeze({
+    repo_only: Object.freeze({
+      requiredKinds: Object.freeze(['code', 'test']),
+      recommendedKinds: Object.freeze(['runtime', 'human']),
+      blockedSoloKinds: Object.freeze(['human', 'delivery']),
+    }),
+    delivery_sensitive: Object.freeze({
+      requiredKinds: Object.freeze(['code', 'test', 'runtime', 'delivery']),
+      recommendedKinds: Object.freeze(['human']),
+      blockedSoloKinds: Object.freeze(['code', 'human']),
+    }),
+  }),
+  'complete-milestone': Object.freeze({
+    repo_only: Object.freeze({
+      requiredKinds: Object.freeze(['code', 'test']),
+      recommendedKinds: Object.freeze(['runtime']),
+      blockedSoloKinds: Object.freeze(['human', 'delivery']),
+    }),
+    delivery_sensitive: Object.freeze({
+      requiredKinds: Object.freeze(['code', 'test', 'runtime', 'delivery']),
+      recommendedKinds: Object.freeze(['human']),
+      blockedSoloKinds: Object.freeze(['code', 'human']),
+    }),
+  }),
+});
+
+export { CLOSURE_SURFACES, DELIVERY_POSTURES, EVIDENCE_KINDS };
+
+export function normalizeEvidenceKind(kind) {
+  if (!kind) {
+    return null;
+  }
+
+  return LEGACY_EVIDENCE_ALIASES[kind] ?? null;
+}
+
+export function normalizeEvidenceKinds(kinds = []) {
+  const normalized = [];
+  for (const kind of kinds) {
+    const resolved = normalizeEvidenceKind(kind);
+    if (resolved && !normalized.includes(resolved)) {
+      normalized.push(resolved);
+    }
+  }
+  return normalized;
+}
+
+export function isClosureSurface(surface) {
+  return CLOSURE_SURFACES.includes(surface);
+}
+
+export function getEvidenceContract(surface, deliveryPosture) {
+  const matrix = EVIDENCE_MATRIX[surface];
+  if (!matrix) {
+    throw new Error(`Unsupported closure evidence surface: ${surface}`);
+  }
+
+  const posture = matrix[deliveryPosture];
+  if (!posture) {
+    throw new Error(`Unsupported delivery posture for ${surface}: ${deliveryPosture}`);
+  }
+
+  return {
+    surface,
+    deliveryPosture,
+    supportedKinds: [...EVIDENCE_KINDS],
+    requiredKinds: [...posture.requiredKinds],
+    recommendedKinds: [...posture.recommendedKinds],
+    blockedSoloKinds: [...posture.blockedSoloKinds],
+  };
+}
+
+export function describeEvidenceSurface(surface) {
+  if (!isClosureSurface(surface)) {
+    return null;
+  }
+
+  return {
+    surface,
+    supportedKinds: [...EVIDENCE_KINDS],
+    deliveryPostures: DELIVERY_POSTURES.map((deliveryPosture) => getEvidenceContract(surface, deliveryPosture)),
+  };
+}

package/bin/lib/file-ops.mjs

@@ -0,0 +1,161 @@
+import { cpSync, existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'fs';
+import { dirname, isAbsolute, relative, resolve } from 'path';
+import { output, parseFlagValue } from './cli-utils.mjs';
+
+class FileOpError extends Error {}
+
+function fail(message) {
+  console.error(message);
+  throw new FileOpError(message);
+}
+
+function resolveWorkspacePath(cwd, target) {
+  const workspaceRoot = resolve(cwd);
+  const resolved = resolve(workspaceRoot, target);
+  const rel = relative(workspaceRoot, resolved);
+
+  if (rel === '' || (!rel.startsWith('..') && !isAbsolute(rel))) {
+    return resolved;
+  }
+
+  fail(`Path must stay inside the workspace: ${target}`);
+}
+
+function getMissingBehavior(args) {
+  const parsed = parseFlagValue(args, '--missing');
+  if (!parsed.present) return 'error';
+  if (parsed.invalid) fail('Usage: --missing <error|ok>');
+  if (!['error', 'ok'].includes(parsed.value)) fail('Usage: --missing <error|ok>');
+  return parsed.value;
+}
+
+function cmdCopy(cwd, args) {
+  const [sourceArg, destinationArg, ...flags] = args;
+  if (!sourceArg || !destinationArg) {
+    fail('Usage: gsdd file-op copy <source> <destination> [--missing <error|ok>]');
+  }
+
+  const missingBehavior = getMissingBehavior(flags);
+  const source = resolveWorkspacePath(cwd, sourceArg);
+  const destination = resolveWorkspacePath(cwd, destinationArg);
+
+  if (!existsSync(source)) {
+    if (missingBehavior === 'ok') {
+      output({ operation: 'copy', source: sourceArg, destination: destinationArg, changed: false, reason: 'missing_source' });
+      return;
+    }
+    fail(`Source file does not exist: ${sourceArg}`);
+  }
+
+  if (statSync(source).isDirectory()) {
+    fail(`Copy only supports files in this phase: ${sourceArg}`);
+  }
+
+  mkdirSync(dirname(destination), { recursive: true });
+  cpSync(source, destination, { force: true });
+  output({ operation: 'copy', source: sourceArg, destination: destinationArg, changed: true });
+}
+
+function cmdDelete(cwd, args) {
+  const [targetArg, ...flags] = args;
+  if (!targetArg) {
+    fail('Usage: gsdd file-op delete <target> [--missing <error|ok>]');
+  }
+
+  const missingBehavior = getMissingBehavior(flags);
+  const target = resolveWorkspacePath(cwd, targetArg);
+
+  if (!existsSync(target)) {
+    if (missingBehavior === 'ok') {
+      output({ operation: 'delete', target: targetArg, changed: false, reason: 'missing_target' });
+      return;
+    }
+    fail(`Target file does not exist: ${targetArg}`);
+  }
+
+  if (statSync(target).isDirectory()) {
+    fail(`Delete only supports files in this phase: ${targetArg}`);
+  }
+
+  unlinkSync(target);
+  output({ operation: 'delete', target: targetArg, changed: true });
+}
+
+function cmdRegexSub(cwd, args) {
+  const [targetArg, pattern, replacement, ...flags] = args;
+  if (!targetArg || pattern === undefined || replacement === undefined) {
+    fail('Usage: gsdd file-op regex-sub <target> <pattern> <replacement> [--flags <flags>] [--missing <error|ok>]');
+  }
+
+  const regexFlags = parseFlagValue(flags, '--flags');
+  if (regexFlags.present && regexFlags.invalid) {
+    fail('Usage: --flags <regex-flags>');
+  }
+
+  const missingBehavior = getMissingBehavior(flags);
+  const target = resolveWorkspacePath(cwd, targetArg);
+
+  if (!existsSync(target)) {
+    if (missingBehavior === 'ok') {
+      output({ operation: 'regex-sub', target: targetArg, changed: false, reason: 'missing_target' });
+      return;
+    }
+    fail(`Target file does not exist: ${targetArg}`);
+  }
+
+  if (statSync(target).isDirectory()) {
+    fail(`regex-sub only supports files in this phase: ${targetArg}`);
+  }
+
+  let regex;
+  try {
+    regex = new RegExp(pattern, regexFlags.value || 'g');
+  } catch (error) {
+    fail(`Invalid regex pattern: ${error.message}`);
+  }
+
+  const source = readFileSync(target, 'utf-8');
+  let replacementCount = 0;
+  if (regex.global) {
+    const matches = source.match(regex);
+    replacementCount = matches ? matches.length : 0;
+  } else {
+    replacementCount = regex.test(source) ? 1 : 0;
+  }
+
+  if (replacementCount === 0) {
+    fail(`Pattern did not match any text in ${targetArg}`);
+  }
+
+  const updated = source.replace(regex, replacement);
+  const changed = updated !== source;
+  writeFileSync(target, updated);
+  output({ operation: 'regex-sub', target: targetArg, changed, replacements: replacementCount });
+}
+
+export function cmdFileOp(...args) {
+  const cwd = process.cwd();
+  const [operation, ...rest] = args;
+
+  try {
+    switch (operation) {
+      case 'copy':
+        cmdCopy(cwd, rest);
+        return;
+      case 'delete':
+        cmdDelete(cwd, rest);
+        return;
+      case 'regex-sub':
+        cmdRegexSub(cwd, rest);
+        return;
+      default:
+        fail('Usage: gsdd file-op <copy|delete|regex-sub> ...');
+    }
+  } catch (error) {
+    if (error instanceof FileOpError) {
+      process.exitCode = 1;
+      return;
+    }
+    throw error;
+  }
+}

package/bin/lib/health-truth.mjs

@@ -0,0 +1,186 @@
+import { existsSync, readFileSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { evaluateLifecycleState } from './lifecycle-state.mjs';
+import {
+  getRuntimeFreshnessRepairGuidance,
+  summarizeRuntimeFreshnessIssues,
+} from './runtime-freshness.mjs';
+import { checkDrift } from './session-fingerprint.mjs';
+
+export const TRUTH_CHECK_IDS = ['W7', 'W8', 'W9', 'W10', 'W11', 'W12'];
+
+export function runTruthChecks(planningDir, frameworkDir, actualCheckIds, options = {}) {
+  const warnings = [];
+  const designPath = join(frameworkDir, 'distilled', 'DESIGN.md');
+  const readmePath = join(frameworkDir, 'distilled', 'README.md');
+  const workflowsDir = join(frameworkDir, 'distilled', 'workflows');
+  const gapsPath = join(frameworkDir, '.internal-research', 'gaps.md');
+  const specPath = join(planningDir, 'SPEC.md');
+  const roadmapPath = join(planningDir, 'ROADMAP.md');
+  const lifecycle = evaluateLifecycleState({ planningDir });
+
+  if (existsSync(designPath)) {
+    const documentedIds = extractHealthTableIds(readFileSync(designPath, 'utf-8'));
+    const missingFromDesign = actualCheckIds.filter((id) => !documentedIds.includes(id));
+    const extraInDesign = documentedIds.filter((id) => !actualCheckIds.includes(id));
+    if (missingFromDesign.length > 0 || extraInDesign.length > 0) {
+      const parts = [];
+      if (missingFromDesign.length > 0) parts.push(`missing in DESIGN.md: ${missingFromDesign.join(', ')}`);
+      if (extraInDesign.length > 0) parts.push(`extra in DESIGN.md: ${extraInDesign.join(', ')}`);
+      warnings.push({
+        id: 'W7',
+        severity: 'WARN',
+        message: `DESIGN.md health check table is out of sync (${parts.join('; ')})`,
+        fix: 'Update distilled/DESIGN.md section 20 to match the implemented health checks',
+      });
+    }
+  }
+
+  if (existsSync(readmePath) && existsSync(workflowsDir)) {
+    const readme = readFileSync(readmePath, 'utf-8');
+    const workflowFiles = readdirSync(workflowsDir).filter((entry) => entry.endsWith('.md')).sort();
+    const statusEntries = extractReadmeStatusEntries(readme);
+    const treeEntries = extractReadmeWorkflowTreeEntries(readme);
+    const issues = [];
+    if (statusEntries.length !== workflowFiles.length) {
+      issues.push(`status table ${statusEntries.length} != workflows dir ${workflowFiles.length}`);
+    }
+    if (treeEntries.length !== workflowFiles.length) {
+      issues.push(`framework tree ${treeEntries.length} != workflows dir ${workflowFiles.length}`);
+    }
+    const missingStatus = workflowFiles.filter((name) => !statusEntries.includes(name));
+    const missingTree = workflowFiles.filter((name) => !treeEntries.includes(name));
+    if (missingStatus.length > 0) issues.push(`missing from status table: ${missingStatus.join(', ')}`);
+    if (missingTree.length > 0) issues.push(`missing from framework tree: ${missingTree.join(', ')}`);
+    if (issues.length > 0) {
+      warnings.push({
+        id: 'W8',
+        severity: 'WARN',
+        message: `distilled/README.md workflow inventory is out of sync (${issues.join('; ')})`,
+        fix: 'Update distilled/README.md workflow status table and framework file tree to match distilled/workflows/',
+      });
+    }
+  }
+
+  if (existsSync(gapsPath)) {
+    const gapRefs = extractRepoLocalPaths(readFileSync(gapsPath, 'utf-8'));
+    const missingRefs = gapRefs.filter((ref) => !existsSync(join(frameworkDir, ref)));
+    if (missingRefs.length > 0) {
+      warnings.push({
+        id: 'W9',
+        severity: 'WARN',
+        message: `gaps.md references missing repo-local paths (${missingRefs.join(', ')})`,
+        fix: 'Annotate stale gap references as resolved or update them to current repo truth',
+      });
+    }
+  }
+
+  if (existsSync(specPath) && existsSync(roadmapPath)) {
+    const mismatches = lifecycle.requirementAlignment.mismatches;
+    if (mismatches.length > 0) {
+      warnings.push({
+        id: 'W10',
+        severity: 'WARN',
+        message: `ROADMAP/SPEC requirement status drift (${mismatches.join('; ')})`,
+        fix: 'Reconcile .planning/ROADMAP.md phase completion markers with .planning/SPEC.md requirement checkboxes',
+      });
+    }
+  }
+
+  if (options.runtimeFreshnessReport?.issueCount > 0) {
+    warnings.push({
+      id: 'W11',
+      severity: 'WARN',
+      message: `Installed generated runtime surfaces drift from current render output (${summarizeRuntimeFreshnessIssues(options.runtimeFreshnessReport)})`,
+      fix: getRuntimeFreshnessRepairGuidance(options.runtimeFreshnessReport),
+    });
+  }
+
+  const drift = checkDrift(planningDir);
+  if (drift.drifted) {
+    warnings.push({
+      id: 'W12',
+      severity: 'WARN',
+      message: `Planning state drifted since last recorded session (${drift.details.join('; ')})`,
+      fix: 'Review the changes, then run a lifecycle workflow to update the fingerprint',
+    });
+  }
+
+  return warnings;
+}
+
+function extractHealthTableIds(content) {
+  const section = extractSection(content, '## 20. Workspace Health Diagnostics', '## 21.');
+  if (!section) return [];
+  return [...normalizeContent(section).matchAll(/^\|\s*([EWI]\d+)\s*\|/gm)].map((result) => result[1]);
+}
+
+function extractReadmeStatusEntries(content) {
+  const section = extractSection(content, '## Current Status', 'Architecture notes:');
+  if (!section) return [];
+  return [...normalizeContent(section).matchAll(/\|\s*`([^`]+\.md)`\s*\|/g)].map((result) => result[1]);
+}
+
+function extractReadmeWorkflowTreeEntries(content) {
+  const section = extractSection(content, '## Files In This Framework', '## ');
+  const match = normalizeContent(section || '').match(/```[\s\S]*?workflows\/\n([\s\S]*?)\n\s*templates\//);
+  if (!match) return [];
+  return match[1]
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.endsWith('.md'));
+}
+
+function extractRepoLocalPaths(content) {
+  const allowedRoots = [
+    'AGENTS.md',
+    'README.md',
+    'CHANGELOG.md',
+    'SPEC.md',
+    'package.json',
+    '.planning/',
+    '.internal-research/',
+    '.agents/',
+    '.claude/',
+    '.opencode/',
+    '.codex/',
+    '.worktrees/',
+    'bin/',
+    'distilled/',
+    'tests/',
+    'fixtures/',
+    'agents/',
+  ];
+  const refs = new Set();
+  for (const result of content.matchAll(/`([^`]+)`/g)) {
+    const value = result[1].trim();
+    if (!looksLikeRepoLocalPath(value, allowedRoots)) continue;
+    refs.add(value.replace(/\\/g, '/').replace(/\/$/, ''));
+  }
+  return [...refs];
+}
+
+function looksLikeRepoLocalPath(value, allowedRoots) {
+  if (value.includes(' ')) return false;
+  if (value.startsWith('/')) return false;
+  if (value.startsWith('$')) return false;
+  if (value.startsWith('..')) return false;
+  if (value.includes('://')) return false;
+  if (value.startsWith('feat/') || value.startsWith('fix/') || value.startsWith('pr') || value.startsWith('origin/')) return false;
+  if (allowedRoots.some((root) => value === root || value.startsWith(root))) return true;
+  return false;
+}
+
+function extractSection(content, startMarker, endMarker) {
+  const normalized = normalizeContent(content);
+  const start = normalized.indexOf(startMarker);
+  if (start === -1) return '';
+  const rest = normalized.slice(start);
+  if (!endMarker) return rest;
+  const end = rest.indexOf(endMarker, startMarker.length);
+  return end === -1 ? rest : rest.slice(0, end);
+}
+
+function normalizeContent(content) {
+  return content.replace(/\r\n/g, '\n');
+}