gsd-pi 2.33.1-dev.235d83a → 2.33.1-dev.29a8268

package/dist/resources/extensions/gsd/files.ts

@@ -0,0 +1,1058 @@
+// GSD Extension - File Parsing and I/O
+// Parsers for roadmap, plan, summary, and continue files.
+// Used by state derivation and the status widget.
+// Pure functions, zero Pi dependencies - uses only Node built-ins.
+
+import { promises as fs } from 'node:fs';
+import { resolve } from 'node:path';
+import { atomicWriteAsync } from './atomic-write.js';
+import { resolveMilestoneFile, relMilestoneFile, resolveGsdRootFile } from './paths.js';
+import { milestoneIdSort, findMilestoneIds } from './guided-flow.js';
+
+import type {
+  Roadmap, BoundaryMapEntry,
+  SlicePlan, TaskPlanEntry,
+  Summary, SummaryFrontmatter, SummaryRequires, FileModified,
+  Continue, ContinueFrontmatter, ContinueStatus,
+  RequirementCounts,
+  SecretsManifest, SecretsManifestEntry, SecretsManifestEntryStatus,
+  ManifestStatus,
+} from './types.js';
+
+import { checkExistingEnvKeys } from '../get-secrets-from-user.js';
+import { parseRoadmapSlices } from './roadmap-slices.js';
+import { nativeParseRoadmap, nativeExtractSection, nativeParsePlanFile, nativeParseSummaryFile, NATIVE_UNAVAILABLE } from './native-parser-bridge.js';
+import { debugTime, debugCount } from './debug-logger.js';
+import { CACHE_MAX } from './constants.js';
+import { splitFrontmatter, parseFrontmatterMap } from '../shared/frontmatter.js';
+
+// Re-export for downstream consumers
+export { splitFrontmatter, parseFrontmatterMap };
+
+// ─── Parse Cache ──────────────────────────────────────────────────────────
+
+/** Fast composite key: length + first/mid/last 100 chars. The middle sample
+ *  prevents collisions when only a few characters change in the interior of
+ *  a file (e.g., a checkbox [ ] → [x] that doesn't alter length or endpoints). */
+function cacheKey(content: string): string {
+  const len = content.length;
+  const head = content.slice(0, 100);
+  const midStart = Math.max(0, Math.floor(len / 2) - 50);
+  const mid = len > 200 ? content.slice(midStart, midStart + 100) : '';
+  const tail = len > 100 ? content.slice(-100) : '';
+  return `${len}:${head}:${mid}:${tail}`;
+}
+
+const _parseCache = new Map<string, unknown>();
+
+function cachedParse<T>(content: string, tag: string, parseFn: (c: string) => T): T {
+  const key = tag + '|' + cacheKey(content);
+  if (_parseCache.has(key)) return _parseCache.get(key) as T;
+  if (_parseCache.size >= CACHE_MAX) _parseCache.clear();
+  const result = parseFn(content);
+  _parseCache.set(key, result);
+  return result;
+}
+
+/** Clear the module-scoped parse cache. Call when files change on disk. */
+export function clearParseCache(): void {
+  _parseCache.clear();
+}
+
+// ─── Helpers ───────────────────────────────────────────────────────────────
+
+/** Extract the text after a heading at a given level, up to the next heading of same or higher level. */
+export function extractSection(body: string, heading: string, level: number = 2): string | null {
+  // Try native parser first for better performance on large files
+  const nativeResult = nativeExtractSection(body, heading, level);
+  if (nativeResult !== NATIVE_UNAVAILABLE) return nativeResult as string | null;
+
+  const prefix = '#'.repeat(level) + ' ';
+  const regex = new RegExp(`^${prefix}${escapeRegex(heading)}\\s*$`, 'm');
+  const match = regex.exec(body);
+  if (!match) return null;
+
+  const start = match.index + match[0].length;
+  const rest = body.slice(start);
+
+  const nextHeading = rest.match(new RegExp(`^#{1,${level}} `, 'm'));
+  const end = nextHeading ? nextHeading.index! : rest.length;
+
+  return rest.slice(0, end).trim();
+}
+
+/** Extract all sections at a given level, returning heading → content map. */
+export function extractAllSections(body: string, level: number = 2): Map<string, string> {
+  const prefix = '#'.repeat(level) + ' ';
+  const regex = new RegExp(`^${prefix}(.+)$`, 'gm');
+  const sections = new Map<string, string>();
+  const matches = [...body.matchAll(regex)];
+
+  for (let i = 0; i < matches.length; i++) {
+    const heading = matches[i][1].trim();
+    const start = matches[i].index! + matches[i][0].length;
+    const end = i + 1 < matches.length ? matches[i + 1].index! : body.length;
+    sections.set(heading, body.slice(start, end).trim());
+  }
+
+  return sections;
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Parse bullet list items from a text block. */
+export function parseBullets(text: string): string[] {
+  return text.split('\n')
+    .map(l => l.replace(/^\s*[-*]\s+/, '').trim())
+    .filter(l => l.length > 0 && !l.startsWith('#'));
+}
+
+/** Extract key: value from bold-prefixed lines like "**Key:** Value" */
+export function extractBoldField(text: string, key: string): string | null {
+  const regex = new RegExp(`^\\*\\*${escapeRegex(key)}:\\*\\*\\s*(.+)$`, 'm');
+  const match = regex.exec(text);
+  return match ? match[1].trim() : null;
+}
+
+// ─── Roadmap Parser ────────────────────────────────────────────────────────
+
+export function parseRoadmap(content: string): Roadmap {
+  return cachedParse(content, 'roadmap', _parseRoadmapImpl);
+}
+
+function _parseRoadmapImpl(content: string): Roadmap {
+  const stopTimer = debugTime("parse-roadmap");
+  // Try native parser first for better performance
+  const nativeResult = nativeParseRoadmap(content);
+  if (nativeResult) {
+    stopTimer({ native: true, slices: nativeResult.slices.length, boundaryEntries: nativeResult.boundaryMap.length });
+    debugCount("parseRoadmapCalls");
+    return nativeResult;
+  }
+
+  const lines = content.split('\n');
+
+  const h1 = lines.find(l => l.startsWith('# '));
+  const title = h1 ? h1.slice(2).trim() : '';
+  const vision = extractBoldField(content, 'Vision') || '';
+
+  const scSection = extractSection(content, 'Success Criteria', 2) ||
+    (() => {
+      const idx = content.indexOf('**Success Criteria:**');
+      if (idx === -1) return '';
+      const rest = content.slice(idx);
+      const nextSection = rest.indexOf('\n---');
+      const block = rest.slice(0, nextSection === -1 ? undefined : nextSection);
+      const firstNewline = block.indexOf('\n');
+      return firstNewline === -1 ? '' : block.slice(firstNewline + 1);
+    })();
+  const successCriteria = scSection ? parseBullets(scSection) : [];
+
+  // Slices
+  const slices = parseRoadmapSlices(content);
+
+  // Boundary map
+  const boundaryMap: BoundaryMapEntry[] = [];
+  const bmSection = extractSection(content, 'Boundary Map');
+
+  if (bmSection) {
+    const h3Sections = extractAllSections(bmSection, 3);
+    for (const [heading, sectionContent] of h3Sections) {
+      const arrowMatch = heading.match(/^(\S+)\s*→\s*(\S+)/);
+      if (!arrowMatch) continue;
+
+      const fromSlice = arrowMatch[1];
+      const toSlice = arrowMatch[2];
+
+      let produces = '';
+      let consumes = '';
+
+      // Use indexOf-based parsing instead of [\s\S]*? regex to avoid
+      // catastrophic backtracking on content with code fences (#468).
+      const prodIdx = sectionContent.search(/^Produces:\s*$/m);
+      if (prodIdx !== -1) {
+        const afterProd = sectionContent.indexOf('\n', prodIdx);
+        if (afterProd !== -1) {
+          const consIdx = sectionContent.search(/^Consumes/m);
+          const endIdx = consIdx !== -1 && consIdx > afterProd ? consIdx : sectionContent.length;
+          produces = sectionContent.slice(afterProd + 1, endIdx).trim();
+        }
+      }
+
+      const consLineMatch = sectionContent.match(/^Consumes[^:]*:\s*(.+)$/m);
+      if (consLineMatch) {
+        consumes = consLineMatch[1].trim();
+      }
+      if (!consumes) {
+        const consIdx = sectionContent.search(/^Consumes[^:]*:\s*$/m);
+        if (consIdx !== -1) {
+          const afterCons = sectionContent.indexOf('\n', consIdx);
+          if (afterCons !== -1) {
+            consumes = sectionContent.slice(afterCons + 1).trim();
+          }
+        }
+      }
+
+      boundaryMap.push({ fromSlice, toSlice, produces, consumes });
+    }
+  }
+
+  const result = { title, vision, successCriteria, slices, boundaryMap };
+  stopTimer({ native: false, slices: slices.length, boundaryEntries: boundaryMap.length });
+  debugCount("parseRoadmapCalls");
+  return result;
+}
+
+// ─── Secrets Manifest Parser ───────────────────────────────────────────────
+
+const VALID_STATUSES = new Set<SecretsManifestEntryStatus>(['pending', 'collected', 'skipped']);
+
+export function parseSecretsManifest(content: string): SecretsManifest {
+  const milestone = extractBoldField(content, 'Milestone') || '';
+  const generatedAt = extractBoldField(content, 'Generated') || '';
+
+  const h3Sections = extractAllSections(content, 3);
+  const entries: SecretsManifestEntry[] = [];
+
+  for (const [heading, sectionContent] of h3Sections) {
+    const key = heading.trim();
+    if (!key) continue;
+
+    const service = extractBoldField(sectionContent, 'Service') || '';
+    const dashboardUrl = extractBoldField(sectionContent, 'Dashboard') || '';
+    const formatHint = extractBoldField(sectionContent, 'Format hint') || '';
+    const rawStatus = (extractBoldField(sectionContent, 'Status') || 'pending').toLowerCase().trim() as SecretsManifestEntryStatus;
+    const status: SecretsManifestEntryStatus = VALID_STATUSES.has(rawStatus) ? rawStatus : 'pending';
+    const destination = extractBoldField(sectionContent, 'Destination') || 'dotenv';
+
+    // Extract numbered guidance list (lines matching "1. ...", "2. ...", etc.)
+    const guidance: string[] = [];
+    for (const line of sectionContent.split('\n')) {
+      const numMatch = line.match(/^\s*\d+\.\s+(.+)/);
+      if (numMatch) {
+        guidance.push(numMatch[1].trim());
+      }
+    }
+
+    entries.push({ key, service, dashboardUrl, guidance, formatHint, status, destination });
+  }
+
+  return { milestone, generatedAt, entries };
+}
+
+// ─── Secrets Manifest Formatter ───────────────────────────────────────────
+
+export function formatSecretsManifest(manifest: SecretsManifest): string {
+  const lines: string[] = [];
+
+  lines.push('# Secrets Manifest');
+  lines.push('');
+  lines.push(`**Milestone:** ${manifest.milestone}`);
+  lines.push(`**Generated:** ${manifest.generatedAt}`);
+
+  for (const entry of manifest.entries) {
+    lines.push('');
+    lines.push(`### ${entry.key}`);
+    lines.push('');
+    lines.push(`**Service:** ${entry.service}`);
+    if (entry.dashboardUrl) {
+      lines.push(`**Dashboard:** ${entry.dashboardUrl}`);
+    }
+    if (entry.formatHint) {
+      lines.push(`**Format hint:** ${entry.formatHint}`);
+    }
+    lines.push(`**Status:** ${entry.status}`);
+    lines.push(`**Destination:** ${entry.destination}`);
+    lines.push('');
+    for (let i = 0; i < entry.guidance.length; i++) {
+      lines.push(`${i + 1}. ${entry.guidance[i]}`);
+    }
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+// ─── Slice Plan Parser ─────────────────────────────────────────────────────
+
+export function parsePlan(content: string): SlicePlan {
+  return cachedParse(content, 'plan', _parsePlanImpl);
+}
+
+function _parsePlanImpl(content: string): SlicePlan {
+  const stopTimer = debugTime("parse-plan");
+  // Try native parser first for better performance
+  const nativeResult = nativeParsePlanFile(content);
+  if (nativeResult) {
+    stopTimer({ native: true });
+    return {
+      id: nativeResult.id,
+      title: nativeResult.title,
+      goal: nativeResult.goal,
+      demo: nativeResult.demo,
+      mustHaves: nativeResult.mustHaves,
+      tasks: nativeResult.tasks.map(t => ({
+        id: t.id,
+        title: t.title,
+        description: t.description,
+        done: t.done,
+        estimate: t.estimate,
+        ...(t.files.length > 0 ? { files: t.files } : {}),
+        ...(t.verify ? { verify: t.verify } : {}),
+      })),
+      filesLikelyTouched: nativeResult.filesLikelyTouched,
+    };
+  }
+
+  const lines = content.split('\n');
+
+  const h1 = lines.find(l => l.startsWith('# '));
+  let id = '';
+  let title = '';
+  if (h1) {
+    const match = h1.match(/^#\s+(\w+):\s+(.+)/);
+    if (match) {
+      id = match[1];
+      title = match[2].trim();
+    } else {
+      title = h1.slice(2).trim();
+    }
+  }
+
+  const goal = extractBoldField(content, 'Goal') || '';
+  const demo = extractBoldField(content, 'Demo') || '';
+
+  const mhSection = extractSection(content, 'Must-Haves');
+  const mustHaves = mhSection ? parseBullets(mhSection) : [];
+
+  const tasksSection = extractSection(content, 'Tasks');
+  const tasks: TaskPlanEntry[] = [];
+
+  if (tasksSection) {
+    const taskLines = tasksSection.split('\n');
+    let currentTask: TaskPlanEntry | null = null;
+
+    for (const line of taskLines) {
+      const cbMatch = line.match(/^-\s+\[([ xX])\]\s+\*\*([\w.]+):\s+(.+?)\*\*\s*(.*)/);
+      if (cbMatch) {
+        if (currentTask) tasks.push(currentTask);
+
+        const rest = cbMatch[4] || '';
+        const estMatch = rest.match(/`est:([^`]+)`/);
+        const estimate = estMatch ? estMatch[1] : '';
+
+        currentTask = {
+          id: cbMatch[2],
+          title: cbMatch[3],
+          description: '',
+          done: cbMatch[1].toLowerCase() === 'x',
+          estimate,
+        };
+      } else if (currentTask && line.match(/^\s*-\s+Files:\s*(.*)/)) {
+        const filesMatch = line.match(/^\s*-\s+Files:\s*(.*)/);
+        if (filesMatch) {
+          currentTask.files = filesMatch[1]
+            .split(',')
+            .map(f => f.replace(/`/g, '').trim())
+            .filter(f => f.length > 0);
+        }
+      } else if (currentTask && line.match(/^\s*-\s+Verify:\s*(.*)/)) {
+        const verifyMatch = line.match(/^\s*-\s+Verify:\s*(.*)/);
+        if (verifyMatch) {
+          currentTask.verify = verifyMatch[1].trim();
+        }
+      } else if (currentTask && line.trim() && !line.startsWith('#')) {
+        const desc = line.trim();
+        if (desc) {
+          currentTask.description = currentTask.description
+            ? currentTask.description + ' ' + desc
+            : desc;
+        }
+      }
+    }
+    if (currentTask) tasks.push(currentTask);
+  }
+
+  const filesSection = extractSection(content, 'Files Likely Touched');
+  const filesLikelyTouched = filesSection ? parseBullets(filesSection) : [];
+
+  const result = { id, title, goal, demo, mustHaves, tasks, filesLikelyTouched };
+  stopTimer({ tasks: tasks.length });
+  debugCount("parsePlanCalls");
+  return result;
+}
+
+// ─── Summary Parser ────────────────────────────────────────────────────────
+
+export function parseSummary(content: string): Summary {
+  return cachedParse(content, 'summary', _parseSummaryImpl);
+}
+
+function _parseSummaryImpl(content: string): Summary {
+  // Try native parser first for better performance
+  const nativeResult = nativeParseSummaryFile(content);
+  if (nativeResult) {
+    const nfm = nativeResult.frontmatter;
+    return {
+      frontmatter: {
+        id: nfm.id,
+        parent: nfm.parent,
+        milestone: nfm.milestone,
+        provides: nfm.provides,
+        requires: nfm.requires,
+        affects: nfm.affects,
+        key_files: nfm.keyFiles,
+        key_decisions: nfm.keyDecisions,
+        patterns_established: nfm.patternsEstablished,
+        drill_down_paths: nfm.drillDownPaths,
+        observability_surfaces: nfm.observabilitySurfaces,
+        duration: nfm.duration,
+        verification_result: nfm.verificationResult,
+        completed_at: nfm.completedAt,
+        blocker_discovered: nfm.blockerDiscovered,
+      },
+      title: nativeResult.title,
+      oneLiner: nativeResult.oneLiner,
+      whatHappened: nativeResult.whatHappened,
+      deviations: nativeResult.deviations,
+      filesModified: nativeResult.filesModified,
+    };
+  }
+
+  const [fmLines, body] = splitFrontmatter(content);
+
+  const fm = fmLines ? parseFrontmatterMap(fmLines) : {};
+  const asStringArray = (v: unknown): string[] =>
+    Array.isArray(v) ? v : (typeof v === 'string' && v ? [v] : []);
+  const frontmatter: SummaryFrontmatter = {
+    id: (fm.id as string) || '',
+    parent: (fm.parent as string) || '',
+    milestone: (fm.milestone as string) || '',
+    provides: asStringArray(fm.provides),
+    requires: ((fm.requires as Array<Record<string, string>>) || []).map(r => ({
+      slice: r.slice || '',
+      provides: r.provides || '',
+    })),
+    affects: asStringArray(fm.affects),
+    key_files: asStringArray(fm.key_files),
+    key_decisions: asStringArray(fm.key_decisions),
+    patterns_established: asStringArray(fm.patterns_established),
+    drill_down_paths: asStringArray(fm.drill_down_paths),
+    observability_surfaces: asStringArray(fm.observability_surfaces),
+    duration: (fm.duration as string) || '',
+    verification_result: (fm.verification_result as string) || 'untested',
+    completed_at: (fm.completed_at as string) || '',
+    blocker_discovered: fm.blocker_discovered === 'true' || fm.blocker_discovered === true,
+  };
+
+  const bodyLines = body.split('\n');
+  const h1 = bodyLines.find(l => l.startsWith('# '));
+  const title = h1 ? h1.slice(2).trim() : '';
+
+  const h1Idx = bodyLines.indexOf(h1 || '');
+  let oneLiner = '';
+  for (let i = h1Idx + 1; i < bodyLines.length; i++) {
+    const line = bodyLines[i].trim();
+    if (!line) continue;
+    if (line.startsWith('**') && line.endsWith('**')) {
+      oneLiner = line.slice(2, -2);
+    }
+    break;
+  }
+
+  const whatHappened = extractSection(body, 'What Happened') || '';
+  const deviations = extractSection(body, 'Deviations') || '';
+
+  const filesSection = extractSection(body, 'Files Created/Modified') || extractSection(body, 'Files Modified');
+  const filesModified: FileModified[] = [];
+  if (filesSection) {
+    for (const line of filesSection.split('\n')) {
+      const trimmed = line.replace(/^\s*[-*]\s+/, '').trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+
+      const fileMatch = trimmed.match(/^`([^`]+)`\s*[—–-]\s*(.+)/);
+      if (fileMatch) {
+        filesModified.push({ path: fileMatch[1], description: fileMatch[2].trim() });
+      }
+    }
+  }
+
+  return { frontmatter, title, oneLiner, whatHappened, deviations, filesModified };
+}
+
+// ─── Continue Parser ───────────────────────────────────────────────────────
+
+export function parseContinue(content: string): Continue {
+  return cachedParse(content, 'continue', _parseContinueImpl);
+}
+
+function _parseContinueImpl(content: string): Continue {
+  const [fmLines, body] = splitFrontmatter(content);
+
+  const fm = fmLines ? parseFrontmatterMap(fmLines) : {};
+  const frontmatter: ContinueFrontmatter = {
+    milestone: (fm.milestone as string) || '',
+    slice: (fm.slice as string) || '',
+    task: (fm.task as string) || '',
+    step: typeof fm.step === 'string' ? parseInt(fm.step) : (fm.step as number) || 0,
+    totalSteps: typeof fm.total_steps === 'string' ? parseInt(fm.total_steps) : (fm.total_steps as number) ||
+      (typeof fm.totalSteps === 'string' ? parseInt(fm.totalSteps) : (fm.totalSteps as number) || 0),
+    status: ((fm.status as string) || 'in_progress') as ContinueStatus,
+    savedAt: (fm.saved_at as string) || (fm.savedAt as string) || '',
+  };
+
+  const completedWork = extractSection(body, 'Completed Work') || '';
+  const remainingWork = extractSection(body, 'Remaining Work') || '';
+  const decisions = extractSection(body, 'Decisions Made') || '';
+  const context = extractSection(body, 'Context') || '';
+  const nextAction = extractSection(body, 'Next Action') || '';
+
+  return { frontmatter, completedWork, remainingWork, decisions, context, nextAction };
+}
+
+// ─── Continue Formatter ────────────────────────────────────────────────────
+
+function formatFrontmatter(data: Record<string, unknown>): string {
+  const lines: string[] = ['---'];
+
+  for (const [key, value] of Object.entries(data)) {
+    if (value === undefined || value === null) continue;
+
+    if (Array.isArray(value)) {
+      if (value.length === 0) {
+        lines.push(`${key}: []`);
+      } else if (typeof value[0] === 'object' && value[0] !== null) {
+        lines.push(`${key}:`);
+        for (const obj of value) {
+          const entries = Object.entries(obj as Record<string, unknown>);
+          if (entries.length > 0) {
+            lines.push(`  - ${entries[0][0]}: ${entries[0][1]}`);
+            for (let i = 1; i < entries.length; i++) {
+              lines.push(`    ${entries[i][0]}: ${entries[i][1]}`);
+            }
+          }
+        }
+      } else {
+        lines.push(`${key}:`);
+        for (const item of value) {
+          lines.push(`  - ${item}`);
+        }
+      }
+    } else {
+      lines.push(`${key}: ${value}`);
+    }
+  }
+
+  lines.push('---');
+  return lines.join('\n');
+}
+
+export function formatContinue(cont: Continue): string {
+  const fm = cont.frontmatter;
+  const fmData: Record<string, unknown> = {
+    milestone: fm.milestone,
+    slice: fm.slice,
+    task: fm.task,
+    step: fm.step,
+    total_steps: fm.totalSteps,
+    status: fm.status,
+    saved_at: fm.savedAt,
+  };
+
+  const lines: string[] = [];
+  lines.push(formatFrontmatter(fmData));
+  lines.push('');
+  lines.push('## Completed Work');
+  lines.push(cont.completedWork);
+  lines.push('');
+  lines.push('## Remaining Work');
+  lines.push(cont.remainingWork);
+  lines.push('');
+  lines.push('## Decisions Made');
+  lines.push(cont.decisions);
+  lines.push('');
+  lines.push('## Context');
+  lines.push(cont.context);
+  lines.push('');
+  lines.push('## Next Action');
+  lines.push(cont.nextAction);
+
+  return lines.join('\n');
+}
+
+// ─── File I/O ──────────────────────────────────────────────────────────────
+
+/**
+ * Load a file from disk. Returns content string or null if file doesn't exist.
+ */
+export async function loadFile(path: string): Promise<string | null> {
+  try {
+    return await fs.readFile(path, 'utf-8');
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+/**
+ * Save content to a file atomically (write to temp, then rename).
+ * Creates parent directories if needed.
+ */
+export async function saveFile(path: string, content: string): Promise<void> {
+  await atomicWriteAsync(path, content);
+}
+
+export function parseRequirementCounts(content: string | null): RequirementCounts {
+  const counts: RequirementCounts = {
+    active: 0,
+    validated: 0,
+    deferred: 0,
+    outOfScope: 0,
+    blocked: 0,
+    total: 0,
+  };
+
+  if (!content) return counts;
+
+  const sections = [
+    { key: 'active', heading: 'Active' },
+    { key: 'validated', heading: 'Validated' },
+    { key: 'deferred', heading: 'Deferred' },
+    { key: 'outOfScope', heading: 'Out of Scope' },
+  ] as const;
+
+  for (const section of sections) {
+    const text = extractSection(content, section.heading, 2);
+    if (!text) continue;
+    const matches = text.match(/^###\s+[A-Z][\w-]*\d+\s+—/gm);
+    counts[section.key] = matches ? matches.length : 0;
+  }
+
+  const blockedMatches = content.match(/^-\s+Status:\s+blocked\s*$/gim);
+  counts.blocked = blockedMatches ? blockedMatches.length : 0;
+  counts.total = counts.active + counts.validated + counts.deferred + counts.outOfScope;
+  return counts;
+}
+
+// ─── Task Plan Must-Haves Parser ───────────────────────────────────────────
+
+/**
+ * Parse must-have items from a task plan's `## Must-Haves` section.
+ * Returns structured items with checkbox state. Handles YAML frontmatter,
+ * all common checkbox variants (`[ ]`, `[x]`, `[X]`), plain bullets (no checkbox),
+ * and indented variants. Returns empty array when the section is missing or empty.
+ */
+export function parseTaskPlanMustHaves(content: string): Array<{ text: string; checked: boolean }> {
+  const [, body] = splitFrontmatter(content);
+  const sectionText = extractSection(body, 'Must-Haves');
+  if (!sectionText) return [];
+
+  const bullets = parseBullets(sectionText);
+  if (bullets.length === 0) return [];
+
+  return bullets.map(line => {
+    const cbMatch = line.match(/^\[([xX ])\]\s+(.+)/);
+    if (cbMatch) {
+      return {
+        text: cbMatch[2].trim(),
+        checked: cbMatch[1].toLowerCase() === 'x',
+      };
+    }
+    // No checkbox - treat as unchecked with full line as text
+    return { text: line.trim(), checked: false };
+  });
+}
+
+// ─── Must-Have Summary Matching ────────────────────────────────────────────
+
+/** Common short words to exclude from substring matching. */
+const COMMON_WORDS = new Set([
+  'the', 'and', 'for', 'are', 'but', 'not', 'you', 'all', 'can', 'had', 'her',
+  'was', 'one', 'our', 'out', 'has', 'its', 'let', 'say', 'she', 'too', 'use',
+  'with', 'have', 'from', 'this', 'that', 'they', 'been', 'each', 'when', 'will',
+  'does', 'into', 'also', 'than', 'them', 'then', 'some', 'what', 'only', 'just',
+  'more', 'make', 'like', 'made', 'over', 'such', 'take', 'most', 'very', 'must',
+  'file', 'test', 'tests', 'task', 'new', 'add', 'added', 'existing',
+]);
+
+/**
+ * Count how many must-have items are mentioned in a summary.
+ *
+ * Matching heuristic per must-have:
+ * 1. Extract all backtick-enclosed code tokens (e.g. `inspectFoo`).
+ *    If any code token appears case-insensitively in the summary, count as mentioned.
+ * 2. If no code tokens exist, check if any significant word (≥4 chars, not a common word)
+ *    from the must-have text appears in the summary (case-insensitive).
+ *
+ * Returns the count of must-haves that had at least one match.
+ */
+export function countMustHavesMentionedInSummary(
+  mustHaves: Array<{ text: string; checked: boolean }>,
+  summaryContent: string,
+): number {
+  if (!summaryContent || mustHaves.length === 0) return 0;
+
+  const summaryLower = summaryContent.toLowerCase();
+  let count = 0;
+
+  for (const mh of mustHaves) {
+    // Extract backtick-enclosed code tokens
+    const codeTokens: string[] = [];
+    const codeRegex = /`([^`]+)`/g;
+    let match: RegExpExecArray | null;
+    while ((match = codeRegex.exec(mh.text)) !== null) {
+      codeTokens.push(match[1]);
+    }
+
+    if (codeTokens.length > 0) {
+      // Strategy 1: any code token found in summary (case-insensitive)
+      const found = codeTokens.some(token => summaryLower.includes(token.toLowerCase()));
+      if (found) count++;
+    } else {
+      // Strategy 2: significant substring matching
+      // Split into words, keep words ≥4 chars that aren't common
+      const words = mh.text.replace(/[^\w\s]/g, ' ').split(/\s+/).filter(w =>
+        w.length >= 4 && !COMMON_WORDS.has(w.toLowerCase())
+      );
+      const found = words.some(word => summaryLower.includes(word.toLowerCase()));
+      if (found) count++;
+    }
+  }
+
+  return count;
+}
+
+// ─── UAT Type Extractor ────────────────────────────────────────────────────
+
+/**
+ * The four UAT classification types recognised by GSD auto-mode.
+ * `undefined` is returned (not this union) when no type can be determined.
+ */
+export type UatType = 'artifact-driven' | 'live-runtime' | 'human-experience' | 'mixed';
+
+/**
+ * Extract the UAT type from a UAT file's raw content.
+ *
+ * UAT files have no YAML frontmatter - pass raw file content directly.
+ * Classification is leading-keyword-only: e.g. `mixed (artifact-driven + live-runtime)` → `'mixed'`.
+ *
+ * Returns `undefined` when:
+ * - the `## UAT Type` section is absent
+ * - no `UAT mode:` bullet is found in the section
+ * - the value does not start with a recognised keyword
+ */
+export function extractUatType(content: string): UatType | undefined {
+  const sectionText = extractSection(content, 'UAT Type');
+  if (!sectionText) return undefined;
+
+  const bullets = parseBullets(sectionText);
+  const modeBullet = bullets.find(b => b.startsWith('UAT mode:'));
+  if (!modeBullet) return undefined;
+
+  const rawValue = modeBullet.slice('UAT mode:'.length).trim().toLowerCase();
+
+  if (rawValue.startsWith('artifact-driven')) return 'artifact-driven';
+  if (rawValue.startsWith('live-runtime')) return 'live-runtime';
+  if (rawValue.startsWith('human-experience')) return 'human-experience';
+  if (rawValue.startsWith('mixed')) return 'mixed';
+
+  return undefined;
+}
+
+/**
+ * Extract the `depends_on` list from M00x-CONTEXT.md YAML frontmatter.
+ * Returns [] when: content is null, no frontmatter block, field absent, or field is empty.
+ * Normalizes each dep ID to uppercase (e.g. 'm001' → 'M001').
+ */
+export function parseContextDependsOn(content: string | null): string[] {
+  if (!content) return [];
+  const [fmLines] = splitFrontmatter(content);
+  if (!fmLines) return [];
+  const fm = parseFrontmatterMap(fmLines);
+  const raw = fm['depends_on'];
+  if (!Array.isArray(raw) || raw.length === 0) return [];
+  return (raw as string[]).map(s => String(s).trim()).filter(Boolean);
+}
+
+/**
+ * Inline the prior milestone's SUMMARY.md as context for the current milestone's planning prompt.
+ * Returns null when: (1) `mid` is the first milestone, (2) prior milestone has no SUMMARY file.
+ *
+ * Uses the shared findMilestoneIds to scan the milestones directory.
+ */
+export async function inlinePriorMilestoneSummary(mid: string, base: string): Promise<string | null> {
+  const sorted = findMilestoneIds(base);
+  if (sorted.length === 0) return null;
+  const idx = sorted.indexOf(mid);
+  if (idx <= 0) return null;
+  const prevMid = sorted[idx - 1];
+  const absPath = resolveMilestoneFile(base, prevMid, "SUMMARY");
+  const relPath = relMilestoneFile(base, prevMid, "SUMMARY");
+  const content = absPath ? await loadFile(absPath) : null;
+  if (!content) return null;
+  return `### Prior Milestone Summary\nSource: \`${relPath}\`\n\n${content.trim()}`;
+}
+
+// ─── Manifest Status ──────────────────────────────────────────────────────
+
+/**
+ * Read a secrets manifest from disk and cross-reference each entry's status
+ * with the current environment (.env + process.env).
+ *
+ * Returns `null` when no manifest file exists (path resolution failure or
+ * file not on disk) - callers can distinguish "no manifest" from "empty manifest".
+ */
+export async function getManifestStatus(
+  base: string, milestoneId: string,
+): Promise<ManifestStatus | null> {
+  const resolvedPath = resolveMilestoneFile(base, milestoneId, 'SECRETS');
+  if (!resolvedPath) return null;
+
+  const content = await loadFile(resolvedPath);
+  if (!content) return null;
+
+  const manifest = parseSecretsManifest(content);
+  const keys = manifest.entries.map(e => e.key);
+  const existingKeys = await checkExistingEnvKeys(keys, resolve(base, '.env'));
+  const existingSet = new Set(existingKeys);
+
+  const result: ManifestStatus = {
+    pending: [],
+    collected: [],
+    skipped: [],
+    existing: [],
+  };
+
+  for (const entry of manifest.entries) {
+    if (existingSet.has(entry.key)) {
+      result.existing.push(entry.key);
+    } else {
+      result[entry.status].push(entry.key);
+    }
+  }
+
+  return result;
+}
+
+// ─── Overrides ──────────────────────────────────────────────────────────────
+
+export interface Override {
+  timestamp: string;
+  change: string;
+  scope: "active" | "resolved";
+  appliedAt: string;
+}
+
+export async function appendOverride(basePath: string, change: string, appliedAt: string): Promise<void> {
+  const overridesPath = resolveGsdRootFile(basePath, "OVERRIDES");
+  const timestamp = new Date().toISOString();
+  const entry = [
+    `## Override: ${timestamp}`,
+    "",
+    `**Change:** ${change}`,
+    `**Scope:** active`,
+    `**Applied-at:** ${appliedAt}`,
+    "",
+    "---",
+    "",
+  ].join("\n");
+
+  const existing = await loadFile(overridesPath);
+  if (existing) {
+    await saveFile(overridesPath, existing.trimEnd() + "\n\n" + entry);
+  } else {
+    const header = [
+      "# GSD Overrides",
+      "",
+      "User-issued overrides that supersede plan document content.",
+      "",
+      "---",
+      "",
+    ].join("\n");
+    await saveFile(overridesPath, header + entry);
+  }
+}
+
+export async function appendKnowledge(
+  basePath: string,
+  type: "rule" | "pattern" | "lesson",
+  entry: string,
+  scope: string,
+): Promise<void> {
+  const knowledgePath = resolveGsdRootFile(basePath, "KNOWLEDGE");
+  const existing = await loadFile(knowledgePath);
+
+  if (existing) {
+    // Find the next ID for this type
+    const prefix = type === "rule" ? "K" : type === "pattern" ? "P" : "L";
+    const idPattern = new RegExp(`^\\| ${prefix}(\\d+)`, "gm");
+    let maxId = 0;
+    let match;
+    while ((match = idPattern.exec(existing)) !== null) {
+      const num = parseInt(match[1], 10);
+      if (num > maxId) maxId = num;
+    }
+    const nextId = `${prefix}${String(maxId + 1).padStart(3, "0")}`;
+
+    // Build the table row
+    let row: string;
+    if (type === "rule") {
+      row = `| ${nextId} | ${scope} | ${entry} | — | manual |`;
+    } else if (type === "pattern") {
+      row = `| ${nextId} | ${entry} | — | ${scope} |`;
+    } else {
+      row = `| ${nextId} | ${entry} | — | — | ${scope} |`;
+    }
+
+    // Find the right section and append after the table header
+    const sectionHeading = type === "rule" ? "## Rules" : type === "pattern" ? "## Patterns" : "## Lessons Learned";
+    const sectionIdx = existing.indexOf(sectionHeading);
+    if (sectionIdx !== -1) {
+      // Find the end of the table header row (the |---|...| line)
+      const afterHeading = existing.indexOf("\n", sectionIdx);
+      // Find the next section or end
+      const nextSection = existing.indexOf("\n## ", afterHeading + 1);
+      const insertPoint = nextSection !== -1 ? nextSection : existing.length;
+
+      // Insert row before the next section (or at end)
+      const before = existing.slice(0, insertPoint).trimEnd();
+      const after = existing.slice(insertPoint);
+      await saveFile(knowledgePath, before + "\n" + row + "\n" + after);
+    } else {
+      // Section not found — append at end
+      await saveFile(knowledgePath, existing.trimEnd() + "\n\n" + row + "\n");
+    }
+  } else {
+    // Create file from scratch with template header
+    const header = [
+      "# Project Knowledge",
+      "",
+      "Append-only register of project-specific rules, patterns, and lessons learned.",
+      "Agents read this before every unit. Add entries when you discover something worth remembering.",
+      "",
+    ].join("\n");
+
+    let content: string;
+    if (type === "rule") {
+      content = header + [
+        "## Rules",
+        "",
+        "| # | Scope | Rule | Why | Added |",
+        "|---|-------|------|-----|-------|",
+        `| K001 | ${scope} | ${entry} | — | manual |`,
+        "",
+        "## Patterns",
+        "",
+        "| # | Pattern | Where | Notes |",
+        "|---|---------|-------|-------|",
+        "",
+        "## Lessons Learned",
+        "",
+        "| # | What Happened | Root Cause | Fix | Scope |",
+        "|---|--------------|------------|-----|-------|",
+        "",
+      ].join("\n");
+    } else if (type === "pattern") {
+      content = header + [
+        "## Rules",
+        "",
+        "| # | Scope | Rule | Why | Added |",
+        "|---|-------|------|-----|-------|",
+        "",
+        "## Patterns",
+        "",
+        "| # | Pattern | Where | Notes |",
+        "|---|---------|-------|-------|",
+        `| P001 | ${entry} | — | ${scope} |`,
+        "",
+        "## Lessons Learned",
+        "",
+        "| # | What Happened | Root Cause | Fix | Scope |",
+        "|---|--------------|------------|-----|-------|",
+        "",
+      ].join("\n");
+    } else {
+      content = header + [
+        "## Rules",
+        "",
+        "| # | Scope | Rule | Why | Added |",
+        "|---|-------|------|-----|-------|",
+        "",
+        "## Patterns",
+        "",
+        "| # | Pattern | Where | Notes |",
+        "|---|---------|-------|-------|",
+        "",
+        "## Lessons Learned",
+        "",
+        "| # | What Happened | Root Cause | Fix | Scope |",
+        "|---|--------------|------------|-----|-------|",
+        `| L001 | ${entry} | — | — | ${scope} |`,
+        "",
+      ].join("\n");
+    }
+    await saveFile(knowledgePath, content);
+  }
+}
+
+export async function loadActiveOverrides(basePath: string): Promise<Override[]> {
+  const overridesPath = resolveGsdRootFile(basePath, "OVERRIDES");
+  const content = await loadFile(overridesPath);
+  if (!content) return [];
+  return parseOverrides(content).filter(o => o.scope === "active");
+}
+
+export function parseOverrides(content: string): Override[] {
+  const overrides: Override[] = [];
+  const blocks = content.split(/^## Override: /m).slice(1);
+
+  for (const block of blocks) {
+    const lines = block.split("\n");
+    const timestamp = lines[0]?.trim() ?? "";
+    let change = "";
+    let scope: "active" | "resolved" = "active";
+    let appliedAt = "";
+
+    for (const line of lines) {
+      const changeMatch = line.match(/^\*\*Change:\*\*\s*(.+)$/);
+      if (changeMatch) change = changeMatch[1].trim();
+      const scopeMatch = line.match(/^\*\*Scope:\*\*\s*(.+)$/);
+      if (scopeMatch) scope = scopeMatch[1].trim() as "active" | "resolved";
+      const appliedMatch = line.match(/^\*\*Applied-at:\*\*\s*(.+)$/);
+      if (appliedMatch) appliedAt = appliedMatch[1].trim();
+    }
+
+    if (change) {
+      overrides.push({ timestamp, change, scope, appliedAt });
+    }
+  }
+
+  return overrides;
+}
+
+export function formatOverridesSection(overrides: Override[]): string {
+  if (overrides.length === 0) return "";
+
+  const entries = overrides.map((o, i) => [
+    `${i + 1}. **${o.change}**`,
+    `   _Issued: ${o.timestamp} during ${o.appliedAt}_`,
+  ].join("\n")).join("\n");
+
+  return [
+    "## Active Overrides (supersede plan content)",
+    "",
+    "The following overrides were issued by the user and supersede any conflicting content in plan documents below. Follow these overrides even if they contradict the inlined task plan.",
+    "",
+    entries,
+    "",
+  ].join("\n");
+}
+
+export async function resolveAllOverrides(basePath: string): Promise<void> {
+  const overridesPath = resolveGsdRootFile(basePath, "OVERRIDES");
+  const content = await loadFile(overridesPath);
+  if (!content) return;
+  const updated = content.replace(/\*\*Scope:\*\* active/g, "**Scope:** resolved");
+  await saveFile(overridesPath, updated);
+}