gswd 0.1.0

package/lib/compile.ts

@@ -0,0 +1,940 @@
+/**
+ * GSWD Compile Module — Deterministic contract doc generation
+ *
+ * Reads spec artifacts (IMAGINE.md, DECISIONS.md, SPEC.md, NFR.md, JOURNEYS.md, INTEGRATIONS.md),
+ * parses into a SpecBundle, and generates 4 GSD contract docs deterministically.
+ * Zero LLM calls, no randomness, no ordering variance.
+ *
+ * Schema: GSWD_SPEC.md Section 8.5, 9.2, 11.3
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { extractIds, extractHeadingContent, normalizeId, validateHeadings } from './parse.js';
+import {
+  readState,
+  writeState,
+  safeWriteFile,
+  updateStageStatus,
+  writeCheckpoint,
+} from './state.js';
+import { checkAuditGate } from './audit.js';
+
+// ─── Types (all exported) ─────────────────────────────────────────────────────
+
+export interface ParsedFR {
+  id: string;
+  description: string;
+  scope: 'v1' | 'v2' | 'out';
+  priority: 'P0' | 'P1' | 'P2';
+  sourceJourneys: string[];
+}
+
+export interface ParsedNFR {
+  id: string;
+  description: string;
+  category: string;
+  threshold: string;
+}
+
+export interface ParsedJourney {
+  id: string;
+  name: string;
+  type: string;
+  linkedFRs: string[];
+  linkedIntegrations: string[];
+}
+
+export interface ParsedIntegration {
+  id: string;
+  name: string;
+  status: string;
+  fallback: string;
+}
+
+export interface SpecBundle {
+  vision: string;
+  targetUser: string;
+  productDirection: string;
+  wedge: string;
+  frozenDecisions: string[];
+  successMetrics: string[];
+  outOfScope: string[];
+  risks: string[];
+  openQuestions: string[];
+  approvals: Record<string, string>;
+  frs: ParsedFR[];
+  roles: string;
+  nfrs: ParsedNFR[];
+  journeys: ParsedJourney[];
+  integrations: ParsedIntegration[];
+  projectSlug: string;
+}
+
+// ─── Constants (all exported) ─────────────────────────────────────────────────
+
+export const SCOPE_ORDER: Record<string, number> = { v1: 0, v2: 1, out: 2 };
+export const PRIORITY_ORDER: Record<string, number> = { P0: 0, P1: 1, P2: 2 };
+export const NFR_CATEGORY_ORDER = ['security', 'privacy', 'performance', 'observability'];
+export const JOURNEY_TYPE_TO_PHASE: Record<string, number> = {
+  onboarding: 1,
+  core_action: 1,
+  view_results: 2,
+  error_states: 3,
+  empty_states: 3,
+  settings: 3,
+};
+export const PHASE_NAMES: Record<number, string> = {
+  1: 'Skeleton & Core Loop',
+  2: 'Persistence & History',
+  3: 'Polish: errors, empty states, settings',
+  4: 'Observability & Hardening',
+};
+
+// ─── Sort Helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Sort FRs by scope (v1 first), then priority (P0 first), then numeric ID ascending.
+ */
+export function sortFRs(frs: ParsedFR[]): ParsedFR[] {
+  return [...frs].sort((a, b) => {
+    const scopeDiff = (SCOPE_ORDER[a.scope] ?? 99) - (SCOPE_ORDER[b.scope] ?? 99);
+    if (scopeDiff !== 0) return scopeDiff;
+    const priorityDiff = (PRIORITY_ORDER[a.priority] ?? 99) - (PRIORITY_ORDER[b.priority] ?? 99);
+    if (priorityDiff !== 0) return priorityDiff;
+    // Numeric ID sort: FR-001 < FR-002 < FR-010
+    return parseInt(a.id.split('-')[1], 10) - parseInt(b.id.split('-')[1], 10);
+  });
+}
+
+// ─── Spec Artifact Parsers ────────────────────────────────────────────────────
+
+/**
+ * Parse FR entries from SPEC.md content.
+ * Uses ### FR-NNN heading pattern, extracts description, scope, and priority.
+ * Accepts a frToJourneys map to populate sourceJourneys.
+ */
+export function parseFRsFromSpec(
+  specContent: string,
+  frToJourneys: Map<string, Set<string>>
+): ParsedFR[] {
+  if (!specContent) return [];
+
+  const frRegex = /^###?\s+(FR-\d{1,4})[:.]?\s*/gm;
+  const positions: { id: string; start: number }[] = [];
+
+  let match: RegExpExecArray | null;
+  while ((match = frRegex.exec(specContent)) !== null) {
+    positions.push({ id: normalizeId(match[1]), start: match.index });
+  }
+
+  const frs: ParsedFR[] = positions.map((pos, i) => {
+    const end = i + 1 < positions.length ? positions[i + 1].start : specContent.length;
+    const section = specContent.slice(pos.start, end);
+
+    const scopeMatch = section.match(/\*{0,2}Scope:?\*{0,2}:?\s*(v1|v2|out)/i);
+    const priorityMatch = section.match(/\*{0,2}Priority:?\*{0,2}:?\s*(P0|P1|P2)/i);
+
+    // Get description: first non-empty line after the heading line
+    const lines = section.split('\n');
+    const headingLine = lines[0]; // e.g., "### FR-001: User can register"
+    // Extract description from heading line if present (after the ID)
+    const headingDescMatch = headingLine.match(/^###?\s+FR-\d{1,4}:?\s+(.*)/);
+    let description = '';
+    if (headingDescMatch && headingDescMatch[1].trim().length > 0) {
+      description = headingDescMatch[1].trim();
+    } else {
+      // Fall back to first non-empty line after heading
+      const descLine = lines.slice(1).find((l) => l.trim().length > 0 && !l.startsWith('**'));
+      description = descLine?.trim() ?? '';
+    }
+
+    const sourceJourneys = Array.from(frToJourneys.get(pos.id) ?? new Set<string>()).sort();
+
+    return {
+      id: pos.id,
+      description,
+      scope: (scopeMatch?.[1]?.toLowerCase() as 'v1' | 'v2' | 'out') ?? 'v1',
+      priority: (priorityMatch?.[1] as 'P0' | 'P1' | 'P2') ?? 'P1',
+      sourceJourneys,
+    };
+  });
+
+  return sortFRs(frs);
+}
+
+/**
+ * Parse NFR entries from NFR.md content.
+ * Extracts id, description, category (from **Category:** field), threshold (from **Threshold:** field).
+ * Sorts by NFR_CATEGORY_ORDER then numeric ID.
+ */
+export function parseNFRsFromContent(nfrContent: string): ParsedNFR[] {
+  if (!nfrContent) return [];
+
+  const nfrRegex = /^###?\s+(NFR-\d{1,4})[:.]?\s*/gm;
+  const positions: { id: string; start: number }[] = [];
+
+  let match: RegExpExecArray | null;
+  while ((match = nfrRegex.exec(nfrContent)) !== null) {
+    positions.push({ id: normalizeId(match[1]), start: match.index });
+  }
+
+  const nfrs: ParsedNFR[] = positions.map((pos, i) => {
+    const end = i + 1 < positions.length ? positions[i + 1].start : nfrContent.length;
+    const section = nfrContent.slice(pos.start, end);
+
+    const categoryMatch = section.match(/\*{0,2}Category:?\*{0,2}:?\s*(\w+)/i);
+    const thresholdMatch = section.match(/\*{0,2}Threshold:?\*{0,2}:?\s*(.+)/i);
+
+    // Extract description from heading line
+    const headingLine = section.split('\n')[0];
+    const headingDescMatch = headingLine.match(/^###?\s+NFR-\d{1,4}:?\s+(.*)/);
+    const description = headingDescMatch?.[1]?.trim() ?? '';
+
+    return {
+      id: pos.id,
+      description,
+      category: categoryMatch?.[1]?.toLowerCase() ?? 'observability',
+      threshold: thresholdMatch?.[1]?.trim() ?? '',
+    };
+  });
+
+  // Sort by category order then numeric ID
+  return nfrs.sort((a, b) => {
+    const aOrder = NFR_CATEGORY_ORDER.indexOf(a.category);
+    const bOrder = NFR_CATEGORY_ORDER.indexOf(b.category);
+    const aCatOrder = aOrder === -1 ? 99 : aOrder;
+    const bCatOrder = bOrder === -1 ? 99 : bOrder;
+    if (aCatOrder !== bCatOrder) return aCatOrder - bCatOrder;
+    return parseInt(a.id.split('-')[1], 10) - parseInt(b.id.split('-')[1], 10);
+  });
+}
+
+/**
+ * Parse journey entries from JOURNEYS.md content.
+ * Extracts id, name, type, linkedFRs, linkedIntegrations.
+ * Sorts by numeric ID.
+ */
+export function parseJourneysFromContent(journeysContent: string): ParsedJourney[] {
+  if (!journeysContent) return [];
+
+  const journeyRegex = /^###?\s+(J-\d{1,4})[:.]?\s*/gm;
+  const positions: { id: string; start: number }[] = [];
+
+  let match: RegExpExecArray | null;
+  while ((match = journeyRegex.exec(journeysContent)) !== null) {
+    positions.push({ id: normalizeId(match[1]), start: match.index });
+  }
+
+  const journeys: ParsedJourney[] = positions.map((pos, i) => {
+    const end = i + 1 < positions.length ? positions[i + 1].start : journeysContent.length;
+    const section = journeysContent.slice(pos.start, end);
+
+    // Extract name from heading line
+    const headingLine = section.split('\n')[0];
+    const headingNameMatch = headingLine.match(/^###?\s+J-\d{1,4}:?\s+(.*)/);
+    const name = headingNameMatch?.[1]?.trim() ?? '';
+
+    // Extract type
+    const typeMatch = section.match(/\*{0,2}Type:?\*{0,2}:?\s*(\w+)/i);
+    const type = typeMatch?.[1]?.toLowerCase() ?? '';
+
+    // Extract linked FRs
+    const frLine = section.match(/\*{0,2}Linked FRs:?\*{0,2}:?\s*(.+)/i);
+    const linkedFRs = frLine
+      ? extractIds(frLine[1], 'FR').map((e) => e.id)
+      : [];
+
+    // Extract linked integrations
+    const intLine = section.match(/\*{0,2}Linked Integrations:?\*{0,2}:?\s*(.+)/i);
+    const linkedIntegrations =
+      intLine && intLine[1].trim().toLowerCase() !== 'none'
+        ? extractIds(intLine[1], 'I').map((e) => e.id)
+        : [];
+
+    return {
+      id: pos.id,
+      name,
+      type,
+      linkedFRs,
+      linkedIntegrations,
+    };
+  });
+
+  // Sort by numeric ID
+  return journeys.sort(
+    (a, b) => parseInt(a.id.split('-')[1], 10) - parseInt(b.id.split('-')[1], 10)
+  );
+}
+
+/**
+ * Parse integration entries from INTEGRATIONS.md content.
+ * Extracts id, name, status, fallback.
+ * Sorts by numeric ID.
+ */
+export function parseIntegrationsFromContent(intContent: string): ParsedIntegration[] {
+  if (!intContent) return [];
+
+  const intRegex = /^###?\s+(I-\d{1,4})[:.]?\s*/gm;
+  const positions: { id: string; start: number }[] = [];
+
+  let match: RegExpExecArray | null;
+  while ((match = intRegex.exec(intContent)) !== null) {
+    positions.push({ id: normalizeId(match[1]), start: match.index });
+  }
+
+  const integrations: ParsedIntegration[] = positions.map((pos, i) => {
+    const end = i + 1 < positions.length ? positions[i + 1].start : intContent.length;
+    const section = intContent.slice(pos.start, end);
+
+    // Extract name from heading
+    const headingLine = section.split('\n')[0];
+    const headingNameMatch = headingLine.match(/^###?\s+I-\d{1,4}:?\s+(.*)/);
+    const name = headingNameMatch?.[1]?.trim() ?? '';
+
+    const statusMatch = section.match(/\*{0,2}Status:?\*{0,2}:?\s*(\w+)/i);
+    const fallbackMatch = section.match(/\*{0,2}Fallback:?\*{0,2}:?\s*(.+)/i);
+
+    return {
+      id: pos.id,
+      name,
+      status: statusMatch?.[1]?.toLowerCase() ?? 'unknown',
+      fallback: fallbackMatch?.[1]?.trim() ?? '',
+    };
+  });
+
+  return integrations.sort(
+    (a, b) => parseInt(a.id.split('-')[1], 10) - parseInt(b.id.split('-')[1], 10)
+  );
+}
+
+/**
+ * Parse a list of bullet/numbered items from a section content string.
+ * Handles: "1. Text", "- Text", "* Text" patterns.
+ */
+function parseListItems(content: string): string[] {
+  if (!content) return [];
+  const lines = content.split('\n');
+  const items: string[] = [];
+
+  for (const line of lines) {
+    const bulletMatch = line.match(/^[-*]\s+(.+)/);
+    const numberedMatch = line.match(/^\d+[.)]\s+(.+)/);
+    if (bulletMatch) {
+      items.push(bulletMatch[1].trim());
+    } else if (numberedMatch) {
+      items.push(numberedMatch[1].trim());
+    }
+  }
+
+  return items;
+}
+
+/**
+ * Build SpecBundle from file contents.
+ *
+ * Uses extractHeadingContent() for IMAGINE.md and DECISIONS.md sections.
+ * Populates frToJourneys mapping from journey parsing.
+ * If statePath provided, reads STATE.json for approvals and projectSlug.
+ * If no statePath provided, projectSlug defaults to '' and approvals defaults to {}.
+ */
+export function parseSpecBundle(
+  files: {
+    imagine: string;
+    decisions: string;
+    spec: string;
+    nfr: string;
+    journeys: string;
+    integrations: string;
+  },
+  statePath?: string
+): SpecBundle {
+  // Parse IMAGINE.md sections
+  const vision = extractHeadingContent(files.imagine, '## Vision') ?? '';
+  const targetUser = extractHeadingContent(files.imagine, '## Target User') ?? '';
+  const productDirection = extractHeadingContent(files.imagine, '## Product Direction') ?? '';
+  const wedge = extractHeadingContent(files.imagine, '## Wedge') ?? '';
+
+  // Parse DECISIONS.md sections
+  const frozenDecisionsContent = extractHeadingContent(files.decisions, '## Frozen Decisions') ?? '';
+  const frozenDecisions = parseListItems(frozenDecisionsContent);
+
+  const successMetricsContent = extractHeadingContent(files.decisions, '## Success Metrics') ?? '';
+  const successMetrics = parseListItems(successMetricsContent);
+
+  const outOfScopeContent = extractHeadingContent(files.decisions, '## Out of Scope') ?? '';
+  const outOfScope = parseListItems(outOfScopeContent);
+
+  const risksContent = extractHeadingContent(files.decisions, '## Risks & Mitigations') ?? '';
+  const risks = parseListItems(risksContent);
+
+  const openQuestionsContent = extractHeadingContent(files.decisions, '## Open Questions') ?? '';
+  const openQuestions = parseListItems(openQuestionsContent);
+
+  // Parse journeys first to build frToJourneys map
+  const journeys = parseJourneysFromContent(files.journeys);
+
+  // Build frToJourneys reverse map
+  const frToJourneys = new Map<string, Set<string>>();
+  for (const journey of journeys) {
+    for (const frId of journey.linkedFRs) {
+      if (!frToJourneys.has(frId)) {
+        frToJourneys.set(frId, new Set<string>());
+      }
+      frToJourneys.get(frId)!.add(journey.id);
+    }
+  }
+
+  // Parse FRs from SPEC.md (with frToJourneys for sourceJourneys population)
+  const frs = parseFRsFromSpec(files.spec, frToJourneys);
+
+  // Parse roles from SPEC.md
+  const roles = extractHeadingContent(files.spec, '## Roles & Permissions') ?? '';
+
+  // Parse NFRs
+  const nfrs = parseNFRsFromContent(files.nfr);
+
+  // Parse integrations
+  const integrations = parseIntegrationsFromContent(files.integrations);
+
+  // Load state for approvals and projectSlug
+  let approvals: Record<string, string> = {};
+  let projectSlug = '';
+
+  if (statePath) {
+    const state = readState(statePath);
+    if (state) {
+      projectSlug = state.project_slug ?? '';
+      approvals = {
+        auth_model: state.approvals?.auth_model ?? '',
+        data_store: state.approvals?.data_store ?? '',
+      };
+    }
+  }
+
+  return {
+    vision,
+    targetUser,
+    productDirection,
+    wedge,
+    frozenDecisions,
+    successMetrics,
+    outOfScope,
+    risks,
+    openQuestions,
+    approvals,
+    frs,
+    roles,
+    nfrs,
+    journeys,
+    integrations,
+    projectSlug,
+  };
+}
+
+// ─── Document Generators ──────────────────────────────────────────────────────
+
+/**
+ * Generate PROJECT.md content from SpecBundle.
+ *
+ * Headings: # projectSlug, ## What This Is, ## Target User, ## Problem Statement,
+ * ## Wedge / MVP Boundary, ## Success Metrics (bulleted), ## Out of Scope (bulleted).
+ * CRITICAL: No Date, Date.now(), or any time-dependent call.
+ * CRITICAL: Ends with exactly one trailing newline.
+ */
+export function generateProjectDoc(bundle: SpecBundle): string {
+  const lines: string[] = [];
+
+  lines.push(`# ${bundle.projectSlug}`);
+  lines.push('');
+  lines.push('## What This Is');
+  lines.push('');
+  lines.push(bundle.vision);
+  lines.push('');
+  lines.push('## Target User');
+  lines.push('');
+  lines.push(bundle.targetUser);
+  lines.push('');
+  lines.push('## Problem Statement');
+  lines.push('');
+  lines.push(bundle.productDirection);
+  lines.push('');
+  lines.push('## Wedge / MVP Boundary');
+  lines.push('');
+  lines.push(bundle.wedge);
+  lines.push('');
+  lines.push('## Success Metrics');
+  lines.push('');
+  for (const metric of bundle.successMetrics) {
+    lines.push(`- ${metric}`);
+  }
+  lines.push('');
+  lines.push('## Out of Scope');
+  lines.push('');
+  for (const item of bundle.outOfScope) {
+    lines.push(`- ${item}`);
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate REQUIREMENTS.md content from SpecBundle.
+ *
+ * Structure:
+ * - # Requirements
+ * - ## Functional Requirements
+ *   - ### v1 (In Scope) — FRs sorted by priority then ID
+ *   - ### v2 (Future) — FRs sorted by priority then ID
+ * - ## Non-Functional Requirements — grouped by NFR_CATEGORY_ORDER
+ * - ## Traceability — FR to journey mapping table (v1 FRs only)
+ *
+ * CRITICAL: No Date, Date.now(), or any time-dependent call.
+ * CRITICAL: Ends with exactly one trailing newline.
+ */
+export function generateRequirementsDoc(bundle: SpecBundle): string {
+  const lines: string[] = [];
+
+  lines.push('# Requirements');
+  lines.push('');
+  lines.push('## Functional Requirements');
+  lines.push('');
+
+  // Sort all FRs deterministically
+  const sortedFRs = sortFRs(bundle.frs);
+  const v1FRs = sortedFRs.filter((fr) => fr.scope === 'v1');
+  const v2FRs = sortedFRs.filter((fr) => fr.scope === 'v2');
+
+  lines.push('### v1 (In Scope)');
+  lines.push('');
+  for (const fr of v1FRs) {
+    lines.push(`#### ${fr.id}: ${fr.description}`);
+    lines.push(`**Scope:** ${fr.scope}  **Priority:** ${fr.priority}`);
+    lines.push('');
+  }
+  if (v1FRs.length === 0) {
+    lines.push('*(none)*');
+    lines.push('');
+  }
+
+  if (v2FRs.length > 0) {
+    lines.push('### v2 (Future)');
+    lines.push('');
+    for (const fr of v2FRs) {
+      lines.push(`#### ${fr.id}: ${fr.description}`);
+      lines.push(`**Scope:** ${fr.scope}  **Priority:** ${fr.priority}`);
+      lines.push('');
+    }
+  }
+
+  // NFRs grouped by category in fixed order
+  lines.push('## Non-Functional Requirements');
+  lines.push('');
+
+  for (const category of NFR_CATEGORY_ORDER) {
+    const categoryNFRs = bundle.nfrs
+      .filter((nfr) => nfr.category === category)
+      .sort((a, b) => parseInt(a.id.split('-')[1], 10) - parseInt(b.id.split('-')[1], 10));
+    if (categoryNFRs.length === 0) continue;
+
+    const categoryTitle = category.charAt(0).toUpperCase() + category.slice(1);
+    lines.push(`### ${categoryTitle}`);
+    lines.push('');
+    for (const nfr of categoryNFRs) {
+      lines.push(`#### ${nfr.id}: ${nfr.description}`);
+      lines.push(`**Threshold:** ${nfr.threshold}`);
+      lines.push('');
+    }
+  }
+
+  // Traceability table — v1 FRs only, journey refs sorted
+  lines.push('## Traceability');
+  lines.push('');
+  lines.push('| FR | Description | Journeys |');
+  lines.push('|----|-------------|----------|');
+  for (const fr of v1FRs) {
+    const journeyRefs = [...fr.sourceJourneys].sort().join(', ') || '(none)';
+    lines.push(`| ${fr.id} | ${fr.description} | ${journeyRefs} |`);
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate ROADMAP.md content from SpecBundle.
+ *
+ * Structure:
+ * - # Roadmap
+ * - ## Overview
+ * - ## Phases
+ *   - ### Phase 1-3: journeys grouped by JOURNEY_TYPE_TO_PHASE, sorted by ID
+ *   - ### Phase 4: observability+security NFRs sorted by ID
+ *
+ * CRITICAL: Always emit all 4 phases.
+ * CRITICAL: No Date, Date.now(), or any time-dependent call.
+ * CRITICAL: Ends with exactly one trailing newline.
+ */
+export function generateRoadmapDoc(bundle: SpecBundle): string {
+  const lines: string[] = [];
+
+  lines.push('# Roadmap');
+  lines.push('');
+  lines.push('## Overview');
+  lines.push('');
+  lines.push('v1 journeys assigned to 4 phases following deterministic rules.');
+  lines.push('');
+  lines.push('## Phases');
+  lines.push('');
+
+  // Group journeys by phase (sorted by ID within each phase)
+  const phaseJourneys = new Map<number, ParsedJourney[]>();
+  for (let i = 1; i <= 4; i++) {
+    phaseJourneys.set(i, []);
+  }
+
+  // Sort journeys by numeric ID before grouping for determinism
+  const sortedJourneys = [...bundle.journeys].sort(
+    (a, b) => parseInt(a.id.split('-')[1], 10) - parseInt(b.id.split('-')[1], 10)
+  );
+
+  for (const journey of sortedJourneys) {
+    const phase = JOURNEY_TYPE_TO_PHASE[journey.type] ?? 3;
+    phaseJourneys.get(phase)!.push(journey);
+  }
+
+  // Always emit all 4 phases
+  for (let phaseNum = 1; phaseNum <= 4; phaseNum++) {
+    lines.push(`### Phase ${phaseNum}: ${PHASE_NAMES[phaseNum]}`);
+    lines.push('');
+
+    if (phaseNum < 4) {
+      const journeys = phaseJourneys.get(phaseNum)!;
+      if (journeys.length === 0) {
+        lines.push('*(no journeys assigned)*');
+      } else {
+        for (const j of journeys) {
+          lines.push(`- **${j.id}**: ${j.name}`);
+          const frRefs = [...j.linkedFRs].sort().join(', ');
+          if (frRefs) {
+            lines.push(`  FRs: ${frRefs}`);
+          }
+        }
+      }
+    } else {
+      // Phase 4: observability + security NFRs sorted by ID
+      const obsSecNFRs = bundle.nfrs
+        .filter((nfr) => nfr.category === 'observability' || nfr.category === 'security')
+        .sort((a, b) => parseInt(a.id.split('-')[1], 10) - parseInt(b.id.split('-')[1], 10));
+
+      if (obsSecNFRs.length === 0) {
+        lines.push('*(no NFRs assigned)*');
+      } else {
+        for (const nfr of obsSecNFRs) {
+          lines.push(`- **${nfr.id}**: ${nfr.description}`);
+        }
+      }
+    }
+
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Validator Types ──────────────────────────────────────────────────────────
+
+export interface ValidatorFinding {
+  check: 'v1_coverage' | 'orphan_requirement' | 'integration_sanity' | 'required_headings';
+  id: string;
+  issue: string;
+}
+
+export interface ValidatorResult {
+  passed: boolean;
+  findings: ValidatorFinding[];
+}
+
+// ─── Contract Validator ───────────────────────────────────────────────────────
+
+/**
+ * Validate generated contract docs against the spec bundle.
+ *
+ * 4 checks:
+ * 1. v1_coverage: Every v1 FR ID appears in the generated roadmap content
+ * 2. orphan_requirement: Every v1 FR has at least 1 source journey (sourceJourneys.length > 0)
+ * 3. integration_sanity: Every integration referenced by any journey is approved or deferred-with-fallback
+ * 4. required_headings: All 4 generated docs contain their REQUIRED_HEADINGS entries
+ */
+export function validateContracts(
+  generatedDocs: { project: string; requirements: string; roadmap: string; state: string },
+  bundle: SpecBundle
+): ValidatorResult {
+  const findings: ValidatorFinding[] = [];
+
+  // Check 1: v1_coverage — all v1 FR IDs appear in roadmap content
+  for (const fr of bundle.frs) {
+    if (fr.scope !== 'v1') continue;
+    if (!generatedDocs.roadmap.includes(fr.id)) {
+      findings.push({
+        check: 'v1_coverage',
+        id: fr.id,
+        issue: `v1 FR ${fr.id} is not referenced in the generated roadmap`,
+      });
+    }
+  }
+
+  // Check 2: orphan_requirement — all v1 FRs have at least 1 source journey
+  for (const fr of bundle.frs) {
+    if (fr.scope !== 'v1') continue;
+    if (fr.sourceJourneys.length === 0) {
+      findings.push({
+        check: 'orphan_requirement',
+        id: fr.id,
+        issue: `v1 FR ${fr.id} is not referenced by any journey`,
+      });
+    }
+  }
+
+  // Check 3: integration_sanity — integrations referenced by journeys must be approved or deferred-with-fallback
+  // Build set of integration IDs referenced by journeys
+  const referencedIntegrationIds = new Set<string>();
+  for (const journey of bundle.journeys) {
+    for (const intId of journey.linkedIntegrations) {
+      referencedIntegrationIds.add(intId);
+    }
+  }
+
+  for (const integration of bundle.integrations) {
+    if (!referencedIntegrationIds.has(integration.id)) continue;
+
+    const isApproved = integration.status === 'approved';
+    const isDeferredWithFallback = integration.status === 'deferred' && integration.fallback.trim().length > 0;
+
+    if (!isApproved && !isDeferredWithFallback) {
+      findings.push({
+        check: 'integration_sanity',
+        id: integration.id,
+        issue: `Integration ${integration.id} (status: ${integration.status}) is referenced by a journey but is not approved or deferred-with-fallback`,
+      });
+    }
+  }
+
+  // Check 4: required_headings — validate each generated doc with its file type key
+  const docMap: Array<[string, string]> = [
+    ['PROJECT.md', generatedDocs.project],
+    ['REQUIREMENTS.md', generatedDocs.requirements],
+    ['ROADMAP.md', generatedDocs.roadmap],
+    ['STATE.md', generatedDocs.state],
+  ];
+
+  for (const [fileType, content] of docMap) {
+    const validation = validateHeadings(content, fileType);
+    for (const missing of validation.missing) {
+      findings.push({
+        check: 'required_headings',
+        id: fileType,
+        issue: `Generated ${fileType} is missing required heading: ${missing}`,
+      });
+    }
+  }
+
+  return { passed: findings.length === 0, findings };
+}
+
+/**
+ * Generate STATE.md content from SpecBundle.
+ *
+ * Structure:
+ * - # Project State
+ * - ## Frozen Decisions (numbered list)
+ * - ## Approvals (key-value list from bundle.approvals)
+ * - ## Open Questions (bulleted)
+ * - ## Risks (bulleted)
+ *
+ * CRITICAL: No Date, Date.now(), or any time-dependent call.
+ * CRITICAL: Ends with exactly one trailing newline.
+ */
+export function generateStateDoc(bundle: SpecBundle): string {
+  const lines: string[] = [];
+
+  lines.push('# Project State');
+  lines.push('');
+  lines.push('## Frozen Decisions');
+  lines.push('');
+  for (let i = 0; i < bundle.frozenDecisions.length; i++) {
+    lines.push(`${i + 1}. ${bundle.frozenDecisions[i]}`);
+  }
+  if (bundle.frozenDecisions.length === 0) {
+    lines.push('*(none)*');
+  }
+  lines.push('');
+
+  lines.push('## Approvals');
+  lines.push('');
+  const approvalKeys = Object.keys(bundle.approvals).sort();
+  for (const key of approvalKeys) {
+    lines.push(`- **${key}:** ${bundle.approvals[key]}`);
+  }
+  if (approvalKeys.length === 0) {
+    lines.push('*(none)*');
+  }
+  lines.push('');
+
+  lines.push('## Open Questions');
+  lines.push('');
+  for (const question of bundle.openQuestions) {
+    lines.push(`- ${question}`);
+  }
+  if (bundle.openQuestions.length === 0) {
+    lines.push('*(none)*');
+  }
+  lines.push('');
+
+  lines.push('## Risks');
+  lines.push('');
+  for (const risk of bundle.risks) {
+    lines.push(`- ${risk}`);
+  }
+  if (bundle.risks.length === 0) {
+    lines.push('*(none)*');
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+// ─── Spec Artifact File Reader ────────────────────────────────────────────────
+
+/**
+ * Read all 6 spec artifact files from a planning directory.
+ * Returns a content map keyed by artifact type.
+ * Missing files return empty string (does not throw).
+ */
+export function readSpecArtifacts(planningDir: string): Record<string, string> {
+  const fileMap: Array<[string, string]> = [
+    ['IMAGINE.md', 'imagine'],
+    ['DECISIONS.md', 'decisions'],
+    ['SPEC.md', 'spec'],
+    ['NFR.md', 'nfr'],
+    ['JOURNEYS.md', 'journeys'],
+    ['INTEGRATIONS.md', 'integrations'],
+  ];
+
+  const result: Record<string, string> = {};
+  for (const [filename, key] of fileMap) {
+    try {
+      result[key] = fs.readFileSync(path.join(planningDir, filename), 'utf-8');
+    } catch {
+      result[key] = '';
+    }
+  }
+
+  return result;
+}
+
+// ─── Workflow Result Type ─────────────────────────────────────────────────────
+
+export interface CompileWorkflowResult {
+  passed: boolean;
+  error?: string;
+  validatorResult?: ValidatorResult;
+  filesWritten: string[];
+  generated?: { project: string; requirements: string; roadmap: string; state: string };
+}
+
+// ─── Workflow Orchestrator ────────────────────────────────────────────────────
+
+/**
+ * Full compile workflow orchestrator.
+ *
+ * Steps:
+ *   1. Check audit gate via checkAuditGate(). If false, return early with error.
+ *   2. Update stage status: compile -> in_progress.
+ *   3. Read spec artifacts from planningDir.
+ *   4. Parse into SpecBundle.
+ *   5. Generate all 4 contract docs (pure functions, no I/O).
+ *   6. Run validator: validateContracts().
+ *   7. If validator FAIL: update state -> fail. Return without writing files.
+ *   8. Write all 4 docs atomically via safeWriteFile().
+ *   9. Update state: stage_status.compile = 'done', stage = 'compile'.
+ *  10. Write checkpoint.
+ *  11. Return result with passed=true and filesWritten list.
+ */
+export function runCompileWorkflow(options: {
+  planningDir: string;
+  statePath: string;
+}): CompileWorkflowResult {
+  const { planningDir, statePath } = options;
+
+  // Step 1: Check audit gate
+  if (!checkAuditGate(statePath)) {
+    return { passed: false, error: 'Audit gate not passed', filesWritten: [] };
+  }
+
+  // Step 2: Update stage status -> in_progress
+  updateStageStatus(statePath, 'compile', 'in_progress');
+
+  // Step 3: Read spec artifacts
+  const files = readSpecArtifacts(planningDir);
+
+  // Step 4: Parse into SpecBundle
+  const bundle = parseSpecBundle(
+    {
+      imagine: files['imagine'] ?? '',
+      decisions: files['decisions'] ?? '',
+      spec: files['spec'] ?? '',
+      nfr: files['nfr'] ?? '',
+      journeys: files['journeys'] ?? '',
+      integrations: files['integrations'] ?? '',
+    },
+    statePath
+  );
+
+  // Step 5: Generate all 4 docs (pure functions)
+  const generated = {
+    project: generateProjectDoc(bundle),
+    requirements: generateRequirementsDoc(bundle),
+    roadmap: generateRoadmapDoc(bundle),
+    state: generateStateDoc(bundle),
+  };
+
+  // Step 6: Run validator
+  const validatorResult = validateContracts(generated, bundle);
+
+  // Step 7: If validator FAIL, update state -> fail and return early
+  if (!validatorResult.passed) {
+    updateStageStatus(statePath, 'compile', 'fail');
+    return { passed: false, validatorResult, filesWritten: [] };
+  }
+
+  // Step 8: Write all 4 docs atomically
+  const fileOutputMap: Array<[string, string]> = [
+    ['PROJECT.md', generated.project],
+    ['REQUIREMENTS.md', generated.requirements],
+    ['ROADMAP.md', generated.roadmap],
+    ['STATE.md', generated.state],
+  ];
+
+  const filesWritten: string[] = [];
+  for (const [filename, content] of fileOutputMap) {
+    const filePath = path.join(planningDir, filename);
+    safeWriteFile(filePath, content);
+    filesWritten.push(filePath);
+  }
+
+  // Step 9: Update state: stage_status.compile = 'done', stage = 'compile'
+  updateStageStatus(statePath, 'compile', 'done');
+  const state = readState(statePath);
+  if (state) {
+    state.stage = 'compile';
+    writeState(statePath, state);
+  }
+
+  // Step 10: Write checkpoint
+  writeCheckpoint(statePath, 'gswd/compile', 'compile-done');
+
+  // Step 11: Return result
+  return { passed: true, validatorResult, filesWritten, generated };
+}