code-as-plan 2.0.0

package/cap/bin/lib/manifest-generator.cjs

@@ -0,0 +1,381 @@
+// @gsd-context Manifest generator for monorepo shared packages -- extracts public API surface and produces markdown summaries
+// @gsd-decision Scans index/barrel files and TypeScript .d.ts files rather than full AST parsing -- regex is sufficient for export extraction
+// @gsd-constraint Zero external dependencies -- uses only Node.js built-ins (fs, path)
+// @gsd-ref(ref:AC-5) Shared packages get auto-generated API manifests stored in root .planning/manifests/
+// @gsd-pattern Manifest output is markdown so it can be injected directly into agent context as lightweight reference
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// @gsd-api generateManifest(packagePath, options) -- returns ManifestData object with exports, types, and description
+
+/**
+ * @typedef {Object} ExportEntry
+ * @property {string} name - Exported symbol name
+ * @property {'function'|'class'|'const'|'type'|'interface'|'enum'|'default'|'unknown'} kind - Export kind
+ * @property {string|null} description - One-line description if available from JSDoc/comment
+ */
+
+/**
+ * @typedef {Object} ManifestData
+ * @property {string} packageName - Package name from package.json
+ * @property {string} packagePath - Relative path in monorepo
+ * @property {string|null} description - Package description from package.json
+ * @property {string|null} version - Package version
+ * @property {ExportEntry[]} exports - Public API exports
+ * @property {string[]} dependencies - Internal monorepo dependencies (workspace:*)
+ * @property {string} generatedAt - ISO timestamp
+ */
+
+/**
+ * Generate a manifest for a single shared package.
+ *
+ * @param {string} packageAbsPath - Absolute path to the package directory
+ * @param {Object} [options]
+ * @param {string} [options.rootPath] - Monorepo root for computing relative paths
+ * @returns {ManifestData}
+ */
+function generateManifest(packageAbsPath, options) {
+  options = options || {};
+  const rootPath = options.rootPath || path.dirname(path.dirname(packageAbsPath));
+
+  const pkgJsonPath = path.join(packageAbsPath, 'package.json');
+  const pkg = safeReadJson(pkgJsonPath) || {};
+
+  const manifest = {
+    packageName: pkg.name || path.basename(packageAbsPath),
+    packagePath: path.relative(rootPath, packageAbsPath),
+    description: pkg.description || null,
+    version: pkg.version || null,
+    exports: [],
+    dependencies: [],
+    generatedAt: new Date().toISOString(),
+  };
+
+  // @gsd-decision Extract workspace:* dependencies to identify internal monorepo links
+  manifest.dependencies = extractWorkspaceDeps(pkg);
+
+  // @gsd-context Find and scan the main entry point / barrel file for exports
+  const entryFile = resolveEntryFile(packageAbsPath, pkg);
+  if (entryFile) {
+    manifest.exports = scanExports(entryFile);
+  } else {
+    // Fallback: scan .d.ts files for TypeScript type exports when no barrel file is found
+    const dtsExports = scanDtsFiles(packageAbsPath);
+    manifest.exports = dtsExports;
+  }
+
+  return manifest;
+}
+
+/**
+ * Resolve the main entry/barrel file for a package.
+ *
+ * @param {string} packageAbsPath
+ * @param {Object} pkg - Parsed package.json
+ * @returns {string|null} Absolute path to entry file, or null
+ */
+function resolveEntryFile(packageAbsPath, pkg) {
+  // @gsd-decision Check package.json exports/main/module fields, then fall back to index.ts/index.js convention
+  const candidates = [];
+
+  // From package.json fields
+  if (pkg.exports && typeof pkg.exports === 'string') {
+    candidates.push(pkg.exports);
+  } else if (pkg.exports && pkg.exports['.']) {
+    const dotExport = pkg.exports['.'];
+    if (typeof dotExport === 'string') candidates.push(dotExport);
+    else if (dotExport.import) candidates.push(dotExport.import);
+    else if (dotExport.require) candidates.push(dotExport.require);
+    else if (dotExport.default) candidates.push(dotExport.default);
+  }
+  if (pkg.main) candidates.push(pkg.main);
+  if (pkg.module) candidates.push(pkg.module);
+
+  // Convention-based fallbacks
+  candidates.push('src/index.ts', 'src/index.tsx', 'src/index.js', 'index.ts', 'index.js', 'lib/index.ts', 'lib/index.js');
+
+  for (const candidate of candidates) {
+    const absCandidate = path.join(packageAbsPath, candidate);
+    if (fs.existsSync(absCandidate)) {
+      return absCandidate;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Scan a file for export statements and extract public API entries.
+ *
+ * @param {string} filePath - Absolute path to the file
+ * @returns {ExportEntry[]}
+ */
+function scanExports(filePath) {
+  // @gsd-decision Use regex to extract exports rather than AST parsing -- language-agnostic and zero-dep
+  // @gsd-risk Regex export extraction may miss complex re-export patterns like `export * from './module'` chains
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return [];
+  }
+
+  const exports = [];
+
+  // Named exports: export function foo, export class Bar, export const baz, export type Qux
+  const namedExportRe = /^[ \t]*export\s+(function|class|const|let|var|type|interface|enum|abstract\s+class)\s+(\w+)/gm;
+  for (const match of content.matchAll(namedExportRe)) {
+    let kind = match[1].trim();
+    if (kind === 'let' || kind === 'var') kind = 'const';
+    if (kind.startsWith('abstract')) kind = 'class';
+
+    const name = match[2];
+    const description = extractPrecedingComment(content, match.index);
+
+    exports.push({ name, kind, description });
+  }
+
+  // Default export: export default function/class
+  const defaultExportRe = /^[ \t]*export\s+default\s+(function|class)\s+(\w+)?/gm;
+  for (const match of content.matchAll(defaultExportRe)) {
+    exports.push({
+      name: match[2] || 'default',
+      kind: 'default',
+      description: extractPrecedingComment(content, match.index),
+    });
+  }
+
+  // Re-exports: export { Foo, Bar } from './module'
+  const reExportRe = /^[ \t]*export\s*\{([^}]+)\}\s*from\s*['"][^'"]+['"]/gm;
+  for (const match of content.matchAll(reExportRe)) {
+    const names = match[1].split(',').map(n => n.trim().split(/\s+as\s+/).pop().trim()).filter(Boolean);
+    for (const name of names) {
+      exports.push({ name, kind: 'unknown', description: null });
+    }
+  }
+
+  return exports;
+}
+
+/**
+ * Extract the first line of a comment block immediately preceding a given position.
+ *
+ * @param {string} content - Full file content
+ * @param {number} position - Character position of the export statement
+ * @returns {string|null}
+ */
+function extractPrecedingComment(content, position) {
+  // Look at lines immediately above the export
+  const before = content.slice(0, position);
+  const lines = before.split('\n');
+  const lastLine = lines[lines.length - 1];
+
+  // Check the line above (lines.length - 2 because last element is partial line)
+  if (lines.length < 2) return null;
+  const prevLine = lines[lines.length - 2].trim();
+
+  // Single-line comment
+  if (prevLine.startsWith('//')) {
+    return prevLine.replace(/^\/\/\s*/, '').trim() || null;
+  }
+  // Block comment end
+  if (prevLine.endsWith('*/')) {
+    const commentText = prevLine.replace(/^\*\/?\s*|\s*\*\/$/g, '').replace(/^\*\s*/, '').trim();
+    return commentText || null;
+  }
+  // JSDoc @description or first line
+  if (prevLine.startsWith('*')) {
+    return prevLine.replace(/^\*\s*/, '').replace(/@\w+\s*/, '').trim() || null;
+  }
+
+  return null;
+}
+
+/**
+ * Extract workspace:* dependencies from package.json.
+ *
+ * @param {Object} pkg - Parsed package.json
+ * @returns {string[]} List of internal package names
+ */
+function extractWorkspaceDeps(pkg) {
+  const deps = [];
+  const allDeps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}), ...(pkg.peerDependencies || {}) };
+
+  for (const [name, version] of Object.entries(allDeps)) {
+    if (typeof version === 'string' && version.startsWith('workspace:')) {
+      deps.push(name);
+    }
+  }
+
+  return deps;
+}
+
+/**
+ * Format a ManifestData object as a markdown document.
+ *
+ * @param {ManifestData} manifest
+ * @returns {string}
+ */
+function formatManifestMarkdown(manifest) {
+  const lines = [
+    `# ${manifest.packageName}`,
+    ``,
+    `**Path:** ${manifest.packagePath}`,
+    `**Version:** ${manifest.version || 'n/a'}`,
+    `**Generated:** ${manifest.generatedAt}`,
+    ``,
+  ];
+
+  if (manifest.description) {
+    lines.push(`> ${manifest.description}`, ``);
+  }
+
+  // Exports table
+  if (manifest.exports.length > 0) {
+    lines.push(`## Exports`, ``);
+    lines.push(`| Name | Kind | Description |`);
+    lines.push(`|------|------|-------------|`);
+    for (const exp of manifest.exports) {
+      lines.push(`| ${exp.name} | ${exp.kind} | ${exp.description || '--'} |`);
+    }
+    lines.push(``);
+  } else {
+    lines.push(`## Exports`, ``, `No exports detected.`, ``);
+  }
+
+  // Internal dependencies
+  if (manifest.dependencies.length > 0) {
+    lines.push(`## Internal Dependencies`, ``);
+    for (const dep of manifest.dependencies) {
+      lines.push(`- ${dep}`);
+    }
+    lines.push(``);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate manifests for all packages in a workspace and write them to .planning/manifests/.
+ *
+ * @param {string} rootPath - Monorepo root
+ * @param {Array<{name: string, path: string, absolutePath: string}>} packages - Workspace packages
+ * @param {Object} [options]
+ * @param {string} [options.outputDir] - Override manifest output directory
+ * @returns {string[]} Paths to generated manifest files
+ */
+// @gsd-api generateAllManifests(rootPath, packages, options) -- writes markdown manifests to .planning/manifests/ and returns file paths
+function generateAllManifests(rootPath, packages, options) {
+  options = options || {};
+  const outputDir = options.outputDir || path.join(rootPath, '.planning', 'manifests');
+
+  fs.mkdirSync(outputDir, { recursive: true });
+
+  const writtenFiles = [];
+
+  for (const pkg of packages) {
+    const manifest = generateManifest(pkg.absolutePath, { rootPath });
+    const markdown = formatManifestMarkdown(manifest);
+    const safeName = manifest.packageName.replace(/^@/, '').replace(/\//g, '__');
+    const outFile = path.join(outputDir, `${safeName}.md`);
+
+    fs.writeFileSync(outFile, markdown, 'utf-8');
+    writtenFiles.push(outFile);
+  }
+
+  return writtenFiles;
+}
+
+/**
+ * CLI entry point for generate-manifest subcommand.
+ *
+ * @param {string} cwd - Current working directory
+ * @param {string} packagePath - Relative path to the package
+ * @param {boolean} raw - Whether to output raw JSON
+ */
+function cmdGenerateManifest(cwd, packagePath, raw) {
+  if (!packagePath) {
+    process.stderr.write('Usage: generate-manifest <package-path>\n');
+    process.exitCode = 1;
+    return;
+  }
+
+  const absPath = path.resolve(cwd, packagePath);
+  const manifest = generateManifest(absPath, { rootPath: cwd });
+
+  if (raw) {
+    process.stdout.write(JSON.stringify(manifest, null, 2) + '\n');
+  } else {
+    process.stdout.write(formatManifestMarkdown(manifest) + '\n');
+  }
+}
+
+/**
+ * Scan .d.ts files in a package root and src/ for type exports.
+ * Limited to first 5 .d.ts files to bound scan time.
+ *
+ * @param {string} packageAbsPath - Absolute path to package directory
+ * @returns {ExportEntry[]}
+ */
+function scanDtsFiles(packageAbsPath) {
+  const dtsFiles = [];
+
+  // Collect .d.ts files from package root and src/
+  const dirsToScan = [packageAbsPath, path.join(packageAbsPath, 'src')];
+  for (const dir of dirsToScan) {
+    try {
+      const entries = fs.readdirSync(dir);
+      for (const entry of entries) {
+        if (entry.endsWith('.d.ts') && entry !== 'node_modules') {
+          dtsFiles.push(path.join(dir, entry));
+        }
+        if (dtsFiles.length >= 5) break;
+      }
+    } catch {
+      // Directory does not exist or not readable
+    }
+    if (dtsFiles.length >= 5) break;
+  }
+
+  // Scan each .d.ts file and merge exports, deduplicate by name
+  const allExports = [];
+  const seenNames = new Set();
+  for (const dtsFile of dtsFiles) {
+    const exports = scanExports(dtsFile);
+    for (const exp of exports) {
+      if (!seenNames.has(exp.name)) {
+        seenNames.add(exp.name);
+        allExports.push(exp);
+      }
+    }
+  }
+
+  return allExports;
+}
+
+/**
+ * Safely read and parse a JSON file.
+ * @param {string} filePath
+ * @returns {Object|null}
+ */
+function safeReadJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  generateManifest,
+  generateAllManifests,
+  formatManifestMarkdown,
+  scanExports,
+  scanDtsFiles,
+  resolveEntryFile,
+  extractWorkspaceDeps,
+  cmdGenerateManifest,
+};

package/cap/bin/lib/milestone.cjs

@@ -0,0 +1,252 @@
+/**
+ * Milestone — Milestone and requirements lifecycle operations
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { escapeRegex, getMilestonePhaseFilter, extractOneLinerFromBody, normalizeMd, planningPaths, output, error } = require('./core.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { writeStateMd, stateReplaceFieldWithFallback } = require('./state.cjs');
+
+function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
+  if (!reqIdsRaw || reqIdsRaw.length === 0) {
+    error('requirement IDs required. Usage: requirements mark-complete REQ-01,REQ-02 or REQ-01 REQ-02');
+  }
+
+  // Accept comma-separated, space-separated, or bracket-wrapped: [REQ-01, REQ-02]
+  const reqIds = reqIdsRaw
+    .join(' ')
+    .replace(/[\[\]]/g, '')
+    .split(/[,\s]+/)
+    .map(r => r.trim())
+    .filter(Boolean);
+
+  if (reqIds.length === 0) {
+    error('no valid requirement IDs found');
+  }
+
+  const reqPath = planningPaths(cwd).requirements;
+  if (!fs.existsSync(reqPath)) {
+    output({ updated: false, reason: 'REQUIREMENTS.md not found', ids: reqIds }, raw, 'no requirements file');
+    return;
+  }
+
+  let reqContent = fs.readFileSync(reqPath, 'utf-8');
+  const updated = [];
+  const alreadyComplete = [];
+  const notFound = [];
+
+  for (const reqId of reqIds) {
+    let found = false;
+    const reqEscaped = escapeRegex(reqId);
+
+    // Update checkbox: - [ ] **REQ-ID** → - [x] **REQ-ID**
+    const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi');
+    if (checkboxPattern.test(reqContent)) {
+      reqContent = reqContent.replace(checkboxPattern, '$1x$2');
+      found = true;
+    }
+
+    // Update traceability table: | REQ-ID | Phase N | Pending | → | REQ-ID | Phase N | Complete |
+    const tablePattern = new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*Pending\\s*(\\|)`, 'gi');
+    if (tablePattern.test(reqContent)) {
+      // Re-read since test() advances lastIndex for global regex
+      reqContent = reqContent.replace(
+        new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*Pending\\s*(\\|)`, 'gi'),
+        '$1 Complete $2'
+      );
+      found = true;
+    }
+
+    if (found) {
+      updated.push(reqId);
+    } else {
+      // Check if already complete before declaring not_found
+      const doneCheckbox = new RegExp(`-\\s*\\[x\\]\\s*\\*\\*${reqEscaped}\\*\\*`, 'gi');
+      const doneTable = new RegExp(`\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|\\s*Complete\\s*\\|`, 'gi');
+      if (doneCheckbox.test(reqContent) || doneTable.test(reqContent)) {
+        alreadyComplete.push(reqId);
+      } else {
+        notFound.push(reqId);
+      }
+    }
+  }
+
+  if (updated.length > 0) {
+    fs.writeFileSync(reqPath, reqContent, 'utf-8');
+  }
+
+  output({
+    updated: updated.length > 0,
+    marked_complete: updated,
+    already_complete: alreadyComplete,
+    not_found: notFound,
+    total: reqIds.length,
+  }, raw, `${updated.length}/${reqIds.length} requirements marked complete`);
+}
+
+function cmdMilestoneComplete(cwd, version, options, raw) {
+  if (!version) {
+    error('version required for milestone complete (e.g., v1.0)');
+  }
+
+  const roadmapPath = planningPaths(cwd).roadmap;
+  const reqPath = planningPaths(cwd).requirements;
+  const statePath = planningPaths(cwd).state;
+  const milestonesPath = path.join(cwd, '.planning', 'MILESTONES.md');
+  const archiveDir = path.join(cwd, '.planning', 'milestones');
+  const phasesDir = planningPaths(cwd).phases;
+  const today = new Date().toISOString().split('T')[0];
+  const milestoneName = options.name || version;
+
+  // Ensure archive directory exists
+  fs.mkdirSync(archiveDir, { recursive: true });
+
+  // Scope stats and accomplishments to only the phases belonging to the
+  // current milestone's ROADMAP.  Uses the shared filter from core.cjs
+  // (same logic used by cmdPhasesList and other callers).
+  const isDirInMilestone = getMilestonePhaseFilter(cwd);
+
+  // Gather stats from phases (scoped to current milestone only)
+  let phaseCount = 0;
+  let totalPlans = 0;
+  let totalTasks = 0;
+  const accomplishments = [];
+
+  try {
+    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort();
+
+    for (const dir of dirs) {
+      if (!isDirInMilestone(dir)) continue;
+
+      phaseCount++;
+      const phaseFiles = fs.readdirSync(path.join(phasesDir, dir));
+      const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');
+      const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
+      totalPlans += plans.length;
+
+      // Extract one-liners from summaries
+      for (const s of summaries) {
+        try {
+          const content = fs.readFileSync(path.join(phasesDir, dir, s), 'utf-8');
+          const fm = extractFrontmatter(content);
+          const oneLiner = fm['one-liner'] || extractOneLinerFromBody(content);
+          if (oneLiner) {
+            accomplishments.push(oneLiner);
+          }
+          // Count tasks: prefer **Tasks:** N from Performance section,
+          // then <task XML tags, then ## Task N markdown headers
+          const tasksFieldMatch = content.match(/\*\*Tasks:\*\*\s*(\d+)/);
+          if (tasksFieldMatch) {
+            totalTasks += parseInt(tasksFieldMatch[1], 10);
+          } else {
+            const xmlTaskMatches = content.match(/<task[\s>]/gi) || [];
+            const mdTaskMatches = content.match(/##\s*Task\s*\d+/gi) || [];
+            totalTasks += xmlTaskMatches.length || mdTaskMatches.length;
+          }
+        } catch { /* intentionally empty */ }
+      }
+    }
+  } catch { /* intentionally empty */ }
+
+  // Archive ROADMAP.md
+  if (fs.existsSync(roadmapPath)) {
+    const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
+    fs.writeFileSync(path.join(archiveDir, `${version}-ROADMAP.md`), roadmapContent, 'utf-8');
+  }
+
+  // Archive REQUIREMENTS.md
+  if (fs.existsSync(reqPath)) {
+    const reqContent = fs.readFileSync(reqPath, 'utf-8');
+    const archiveHeader = `# Requirements Archive: ${version} ${milestoneName}\n\n**Archived:** ${today}\n**Status:** SHIPPED\n\nFor current requirements, see \`.planning/REQUIREMENTS.md\`.\n\n---\n\n`;
+    fs.writeFileSync(path.join(archiveDir, `${version}-REQUIREMENTS.md`), archiveHeader + reqContent, 'utf-8');
+  }
+
+  // Archive audit file if exists
+  const auditFile = path.join(cwd, '.planning', `${version}-MILESTONE-AUDIT.md`);
+  if (fs.existsSync(auditFile)) {
+    fs.renameSync(auditFile, path.join(archiveDir, `${version}-MILESTONE-AUDIT.md`));
+  }
+
+  // Create/append MILESTONES.md entry
+  const accomplishmentsList = accomplishments.map(a => `- ${a}`).join('\n');
+  const milestoneEntry = `## ${version} ${milestoneName} (Shipped: ${today})\n\n**Phases completed:** ${phaseCount} phases, ${totalPlans} plans, ${totalTasks} tasks\n\n**Key accomplishments:**\n${accomplishmentsList || '- (none recorded)'}\n\n---\n\n`;
+
+  if (fs.existsSync(milestonesPath)) {
+    const existing = fs.readFileSync(milestonesPath, 'utf-8');
+    if (!existing.trim()) {
+      // Empty file — treat like new
+      fs.writeFileSync(milestonesPath, normalizeMd(`# Milestones\n\n${milestoneEntry}`), 'utf-8');
+    } else {
+      // Insert after the header line(s) for reverse chronological order (newest first)
+      const headerMatch = existing.match(/^(#{1,3}\s+[^\n]*\n\n?)/);
+      if (headerMatch) {
+        const header = headerMatch[1];
+        const rest = existing.slice(header.length);
+        fs.writeFileSync(milestonesPath, normalizeMd(header + milestoneEntry + rest), 'utf-8');
+      } else {
+        // No recognizable header — prepend the entry
+        fs.writeFileSync(milestonesPath, normalizeMd(milestoneEntry + existing), 'utf-8');
+      }
+    }
+  } else {
+    fs.writeFileSync(milestonesPath, normalizeMd(`# Milestones\n\n${milestoneEntry}`), 'utf-8');
+  }
+
+  // Update STATE.md — use shared helpers that handle both **bold:** and plain Field: formats
+  if (fs.existsSync(statePath)) {
+    let stateContent = fs.readFileSync(statePath, 'utf-8');
+
+    stateContent = stateReplaceFieldWithFallback(stateContent, 'Status', null, `${version} milestone complete`);
+    stateContent = stateReplaceFieldWithFallback(stateContent, 'Last Activity', 'Last activity', today);
+    stateContent = stateReplaceFieldWithFallback(stateContent, 'Last Activity Description', null,
+      `${version} milestone completed and archived`);
+
+    writeStateMd(statePath, stateContent, cwd);
+  }
+
+  // Archive phase directories if requested
+  let phasesArchived = false;
+  if (options.archivePhases) {
+    try {
+      const phaseArchiveDir = path.join(archiveDir, `${version}-phases`);
+      fs.mkdirSync(phaseArchiveDir, { recursive: true });
+
+      const phaseEntries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      const phaseDirNames = phaseEntries.filter(e => e.isDirectory()).map(e => e.name);
+      let archivedCount = 0;
+      for (const dir of phaseDirNames) {
+        if (!isDirInMilestone(dir)) continue;
+        fs.renameSync(path.join(phasesDir, dir), path.join(phaseArchiveDir, dir));
+        archivedCount++;
+      }
+      phasesArchived = archivedCount > 0;
+    } catch { /* intentionally empty */ }
+  }
+
+  const result = {
+    version,
+    name: milestoneName,
+    date: today,
+    phases: phaseCount,
+    plans: totalPlans,
+    tasks: totalTasks,
+    accomplishments,
+    archived: {
+      roadmap: fs.existsSync(path.join(archiveDir, `${version}-ROADMAP.md`)),
+      requirements: fs.existsSync(path.join(archiveDir, `${version}-REQUIREMENTS.md`)),
+      audit: fs.existsSync(path.join(archiveDir, `${version}-MILESTONE-AUDIT.md`)),
+      phases: phasesArchived,
+    },
+    milestones_updated: true,
+    state_updated: fs.existsSync(statePath),
+  };
+
+  output(result, raw);
+}
+
+module.exports = {
+  cmdRequirementsMarkComplete,
+  cmdMilestoneComplete,
+};

package/cap/bin/lib/model-profiles.cjs

@@ -0,0 +1,68 @@
+/**
+ * Mapping of GSD agent to model for each profile.
+ *
+ * Should be in sync with the profiles table in `cap/references/model-profiles.md`. But
+ * possibly worth making this the single source of truth at some point, and removing the markdown
+ * reference table in favor of programmatically determining the model to use for an agent (which
+ * would be faster, use fewer tokens, and be less error-prone).
+ */
+const MODEL_PROFILES = {
+  'gsd-planner': { quality: 'opus', balanced: 'opus', budget: 'sonnet' },
+  'gsd-roadmapper': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' },
+  'gsd-executor': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' },
+  'gsd-phase-researcher': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-project-researcher': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-research-synthesizer': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-debugger': { quality: 'opus', balanced: 'sonnet', budget: 'sonnet' },
+  'gsd-codebase-mapper': { quality: 'sonnet', balanced: 'haiku', budget: 'haiku' },
+  'gsd-verifier': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-plan-checker': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-integration-checker': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-nyquist-auditor': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-ui-researcher': { quality: 'opus', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-ui-checker': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+  'gsd-ui-auditor': { quality: 'sonnet', balanced: 'sonnet', budget: 'haiku' },
+};
+const VALID_PROFILES = Object.keys(MODEL_PROFILES['gsd-planner']);
+
+/**
+ * Formats the agent-to-model mapping as a human-readable table (in string format).
+ *
+ * @param {Object<string, string>} agentToModelMap - A mapping from agent to model
+ * @returns {string} A formatted table string
+ */
+function formatAgentToModelMapAsTable(agentToModelMap) {
+  const agentWidth = Math.max('Agent'.length, ...Object.keys(agentToModelMap).map((a) => a.length));
+  const modelWidth = Math.max(
+    'Model'.length,
+    ...Object.values(agentToModelMap).map((m) => m.length)
+  );
+  const sep = '─'.repeat(agentWidth + 2) + '┼' + '─'.repeat(modelWidth + 2);
+  const header = ' ' + 'Agent'.padEnd(agentWidth) + ' │ ' + 'Model'.padEnd(modelWidth);
+  let agentToModelTable = header + '\n' + sep + '\n';
+  for (const [agent, model] of Object.entries(agentToModelMap)) {
+    agentToModelTable += ' ' + agent.padEnd(agentWidth) + ' │ ' + model.padEnd(modelWidth) + '\n';
+  }
+  return agentToModelTable;
+}
+
+/**
+ * Returns a mapping from agent to model for the given model profile.
+ *
+ * @param {string} normalizedProfile - The normalized (lowercase and trimmed) profile name
+ * @returns {Object<string, string>} A mapping from agent to model for the given profile
+ */
+function getAgentToModelMapForProfile(normalizedProfile) {
+  const agentToModelMap = {};
+  for (const [agent, profileToModelMap] of Object.entries(MODEL_PROFILES)) {
+    agentToModelMap[agent] = profileToModelMap[normalizedProfile];
+  }
+  return agentToModelMap;
+}
+
+module.exports = {
+  MODEL_PROFILES,
+  VALID_PROFILES,
+  formatAgentToModelMapAsTable,
+  getAgentToModelMapForProfile,
+};