gsd-pi 2.10.12 → 2.12.0

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

@@ -0,0 +1,857 @@
+// 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 { dirname, resolve } from 'node:path';
+import { resolveMilestoneFile, relMilestoneFile } 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, NATIVE_UNAVAILABLE } from './native-parser-bridge.js';
+
+// ─── Parse Cache ──────────────────────────────────────────────────────────
+
+const CACHE_MAX = 50;
+
+/** Fast composite key: length + first/last 100 chars. Unique enough for distinct markdown files. */
+function cacheKey(content: string): string {
+  const len = content.length;
+  const head = content.slice(0, 100);
+  const tail = len > 100 ? content.slice(-100) : '';
+  return `${len}:${head}:${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 ───────────────────────────────────────────────────────────────
+
+/**
+ * Split markdown content into frontmatter (YAML-like) and body.
+ * Returns [frontmatterLines, body] where frontmatterLines is null if no frontmatter.
+ */
+export function splitFrontmatter(content: string): [string[] | null, string] {
+  const trimmed = content.trimStart();
+  if (!trimmed.startsWith('---')) return [null, content];
+
+  const afterFirst = trimmed.indexOf('\n');
+  if (afterFirst === -1) return [null, content];
+
+  const rest = trimmed.slice(afterFirst + 1);
+  const endIdx = rest.indexOf('\n---');
+  if (endIdx === -1) return [null, content];
+
+  const fmLines = rest.slice(0, endIdx).split('\n');
+  const body = rest.slice(endIdx + 4).replace(/^\n+/, '');
+  return [fmLines, body];
+}
+
+/**
+ * Parse YAML-like frontmatter lines into a flat key-value map.
+ * Handles simple scalars and arrays (lines starting with "  - ").
+ * Handles nested objects like requires (lines with "    key: value").
+ */
+export function parseFrontmatterMap(lines: string[]): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  let currentKey: string | null = null;
+  let currentArray: unknown[] | null = null;
+  let currentObj: Record<string, string> | null = null;
+
+  for (const line of lines) {
+    // Nested object property (4-space indent with key: value)
+    const nestedMatch = line.match(/^    (\w[\w_]*)\s*:\s*(.*)$/);
+    if (nestedMatch && currentArray && currentObj) {
+      currentObj[nestedMatch[1]] = nestedMatch[2].trim();
+      continue;
+    }
+
+    // Array item (2-space indent)
+    const arrayMatch = line.match(/^  - (.*)$/);
+    if (arrayMatch && currentKey) {
+      // If there's a pending nested object, push it
+      if (currentObj && Object.keys(currentObj).length > 0) {
+        currentArray!.push(currentObj);
+      }
+      currentObj = null;
+
+      const val = arrayMatch[1].trim();
+      if (!currentArray) currentArray = [];
+
+      // Check if this array item starts a nested object (e.g. "- slice: S00")
+      const nestedStart = val.match(/^(\w[\w_]*)\s*:\s*(.*)$/);
+      if (nestedStart) {
+        currentObj = { [nestedStart[1]]: nestedStart[2].trim() };
+      } else {
+        currentArray.push(val);
+      }
+      continue;
+    }
+
+    // Flush previous key
+    if (currentKey) {
+      if (currentObj && Object.keys(currentObj).length > 0 && currentArray) {
+        currentArray.push(currentObj);
+        currentObj = null;
+      }
+      if (currentArray) {
+        result[currentKey] = currentArray;
+      }
+      currentArray = null;
+    }
+
+    // Top-level key: value
+    const kvMatch = line.match(/^(\w[\w_]*)\s*:\s*(.*)$/);
+    if (kvMatch) {
+      currentKey = kvMatch[1];
+      const val = kvMatch[2].trim();
+
+      if (val === '' || val === '[]') {
+        currentArray = [];
+      } else if (val.startsWith('[') && val.endsWith(']')) {
+        const inner = val.slice(1, -1).trim();
+        result[currentKey] = inner ? inner.split(',').map(s => s.trim()) : [];
+        currentKey = null;
+      } else {
+        result[currentKey] = val;
+        currentKey = null;
+      }
+    }
+  }
+
+  // Flush final key
+  if (currentKey) {
+    if (currentObj && Object.keys(currentObj).length > 0 && currentArray) {
+      currentArray.push(currentObj);
+      currentObj = null;
+    }
+    if (currentArray) {
+      result[currentKey] = currentArray;
+    }
+  }
+
+  return result;
+}
+
+/** 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 {
+  // Try native parser first for better performance
+  const nativeResult = nativeParseRoadmap(content);
+  if (nativeResult) 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 = '';
+
+      const prodMatch = sectionContent.match(/^Produces:\s*\n([\s\S]*?)(?=^Consumes|$)/m);
+      if (prodMatch) produces = prodMatch[1].trim();
+
+      const consMatch = sectionContent.match(/^Consumes[^:]*:\s*\n?([\s\S]*?)$/m);
+      if (consMatch) consumes = consMatch[1].trim();
+      if (!consumes) {
+        const singleCons = sectionContent.match(/^Consumes[^:]*:\s*(.+)$/m);
+        if (singleCons) consumes = singleCons[1].trim();
+      }
+
+      boundaryMap.push({ fromSlice, toSlice, produces, consumes });
+    }
+  }
+
+  return { title, vision, successCriteria, slices, boundaryMap };
+}
+
+// ─── 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 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) : [];
+
+  return { id, title, goal, demo, mustHaves, tasks, filesLikelyTouched };
+}
+
+// ─── Summary Parser ────────────────────────────────────────────────────────
+
+export function parseSummary(content: string): Summary {
+  return cachedParse(content, 'summary', _parseSummaryImpl);
+}
+
+function _parseSummaryImpl(content: string): Summary {
+  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> {
+  const dir = dirname(path);
+  await fs.mkdir(dir, { recursive: true });
+
+  const tmpPath = path + '.tmp';
+  await fs.writeFile(tmpPath, content, 'utf-8');
+  await fs.rename(tmpPath, path);
+}
+
+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).toUpperCase().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;
+}