gswd 1.0.1 → 1.1.0

package/dist/lib/compile.js

@@ -0,0 +1,1152 @@
+"use strict";
+/**
+ * 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
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PHASE_NAMES = exports.JOURNEY_TYPE_TO_PHASE = exports.NFR_CATEGORY_ORDER = exports.PRIORITY_ORDER = exports.SCOPE_ORDER = void 0;
+exports.sortFRs = sortFRs;
+exports.parseFRsFromSpec = parseFRsFromSpec;
+exports.parseNFRsFromContent = parseNFRsFromContent;
+exports.parseJourneysFromContent = parseJourneysFromContent;
+exports.parseIntegrationsFromContent = parseIntegrationsFromContent;
+exports.parseSpecBundle = parseSpecBundle;
+exports.generateProjectDoc = generateProjectDoc;
+exports.generateRequirementsDoc = generateRequirementsDoc;
+exports.generateRoadmapDoc = generateRoadmapDoc;
+exports.generateResearchSummary = generateResearchSummary;
+exports.validateContracts = validateContracts;
+exports.generateStateDoc = generateStateDoc;
+exports.readSpecArtifacts = readSpecArtifacts;
+exports.runCompileWorkflow = runCompileWorkflow;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const parse_js_1 = require("./parse.js");
+const state_js_1 = require("./state.js");
+const audit_js_1 = require("./audit.js");
+// ─── Constants (all exported) ─────────────────────────────────────────────────
+exports.SCOPE_ORDER = { v1: 0, v2: 1, out: 2 };
+exports.PRIORITY_ORDER = { P0: 0, P1: 1, P2: 2 };
+exports.NFR_CATEGORY_ORDER = ['security', 'privacy', 'performance', 'observability'];
+exports.JOURNEY_TYPE_TO_PHASE = {
+    onboarding: 1,
+    core_action: 1,
+    view_results: 2,
+    error_states: 3,
+    empty_states: 3,
+    settings: 3,
+};
+exports.PHASE_NAMES = {
+    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.
+ */
+function sortFRs(frs) {
+    return [...frs].sort((a, b) => {
+        const scopeDiff = (exports.SCOPE_ORDER[a.scope] ?? 99) - (exports.SCOPE_ORDER[b.scope] ?? 99);
+        if (scopeDiff !== 0)
+            return scopeDiff;
+        const priorityDiff = (exports.PRIORITY_ORDER[a.priority] ?? 99) - (exports.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.
+ */
+function parseFRsFromSpec(specContent, frToJourneys) {
+    if (!specContent)
+        return [];
+    const frRegex = /^###?\s+(FR-\d{1,4})[:.]?\s*/gm;
+    const positions = [];
+    let match;
+    while ((match = frRegex.exec(specContent)) !== null) {
+        positions.push({ id: (0, parse_js_1.normalizeId)(match[1]), start: match.index });
+    }
+    const frs = 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()).sort();
+        // Extract acceptance criteria: lines after "**Acceptance Criteria:**" heading
+        const acceptanceCriteria = [];
+        const acMatch = section.match(/\*{0,2}Acceptance Criteria:?\*{0,2}:?\s*\n([\s\S]*?)(?=\*\*|###|$)/i);
+        if (acMatch) {
+            const acLines = acMatch[1].split('\n');
+            for (const acLine of acLines) {
+                const bulletMatch = acLine.match(/^[-*]\s+(.+)/);
+                if (bulletMatch) {
+                    acceptanceCriteria.push(bulletMatch[1].trim());
+                }
+            }
+        }
+        return {
+            id: pos.id,
+            description,
+            scope: scopeMatch?.[1]?.toLowerCase() ?? 'v1',
+            priority: priorityMatch?.[1] ?? 'P1',
+            sourceJourneys,
+            acceptanceCriteria,
+        };
+    });
+    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.
+ */
+function parseNFRsFromContent(nfrContent) {
+    if (!nfrContent)
+        return [];
+    const nfrRegex = /^###?\s+(NFR-\d{1,4})[:.]?\s*/gm;
+    const positions = [];
+    let match;
+    while ((match = nfrRegex.exec(nfrContent)) !== null) {
+        positions.push({ id: (0, parse_js_1.normalizeId)(match[1]), start: match.index });
+    }
+    const nfrs = 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 = exports.NFR_CATEGORY_ORDER.indexOf(a.category);
+        const bOrder = exports.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.
+ */
+function parseJourneysFromContent(journeysContent) {
+    if (!journeysContent)
+        return [];
+    const journeyRegex = /^###?\s+(J-\d{1,4})[:.]?\s*/gm;
+    const positions = [];
+    let match;
+    while ((match = journeyRegex.exec(journeysContent)) !== null) {
+        positions.push({ id: (0, parse_js_1.normalizeId)(match[1]), start: match.index });
+    }
+    const journeys = 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
+            ? (0, parse_js_1.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'
+            ? (0, parse_js_1.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.
+ */
+function parseIntegrationsFromContent(intContent) {
+    if (!intContent)
+        return [];
+    const intRegex = /^###?\s+(I-\d{1,4})[:.]?\s*/gm;
+    const positions = [];
+    let match;
+    while ((match = intRegex.exec(intContent)) !== null) {
+        positions.push({ id: (0, parse_js_1.normalizeId)(match[1]), start: match.index });
+    }
+    const integrations = 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) {
+    if (!content)
+        return [];
+    const lines = content.split('\n');
+    const items = [];
+    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 {}.
+ */
+function parseSpecBundle(files, statePath) {
+    // Parse IMAGINE.md sections
+    const vision = (0, parse_js_1.extractHeadingContent)(files.imagine, '## Vision') ?? '';
+    const targetUser = (0, parse_js_1.extractHeadingContent)(files.imagine, '## Target User') ?? '';
+    const productDirection = (0, parse_js_1.extractHeadingContent)(files.imagine, '## Product Direction') ?? '';
+    const wedge = (0, parse_js_1.extractHeadingContent)(files.imagine, '## Wedge') ?? '';
+    // Parse DECISIONS.md sections
+    const frozenDecisionsContent = (0, parse_js_1.extractHeadingContent)(files.decisions, '## Frozen Decisions') ?? '';
+    const frozenDecisions = parseListItems(frozenDecisionsContent);
+    const successMetricsContent = (0, parse_js_1.extractHeadingContent)(files.decisions, '## Success Metrics') ?? '';
+    const successMetrics = parseListItems(successMetricsContent);
+    const outOfScopeContent = (0, parse_js_1.extractHeadingContent)(files.decisions, '## Out of Scope') ?? '';
+    const outOfScope = parseListItems(outOfScopeContent);
+    const risksContent = (0, parse_js_1.extractHeadingContent)(files.decisions, '## Risks & Mitigations') ?? '';
+    const risks = parseListItems(risksContent);
+    const openQuestionsContent = (0, parse_js_1.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();
+    for (const journey of journeys) {
+        for (const frId of journey.linkedFRs) {
+            if (!frToJourneys.has(frId)) {
+                frToJourneys.set(frId, new Set());
+            }
+            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 = (0, parse_js_1.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 = {};
+    let projectSlug = '';
+    if (statePath) {
+        const state = (0, state_js_1.readState)(statePath);
+        if (state) {
+            projectSlug = state.project_slug ?? '';
+            approvals = {
+                auth_model: state.approvals?.auth_model ?? '',
+                data_store: state.approvals?.data_store ?? '',
+            };
+        }
+    }
+    // Populate new enrichment fields from research files
+    const architectureContent = files.architecture ?? '';
+    const icpContent = files.icp ?? '';
+    const competitionContent = files.competition ?? '';
+    const gtmContent = files.gtm ?? '';
+    const featuresContent = files.features ?? '';
+    const architectureSummary = (0, parse_js_1.extractHeadingContent)(architectureContent, '## Standard Architecture') ??
+        (0, parse_js_1.extractHeadingContent)(architectureContent, '## Executive Summary') ??
+        '';
+    const icpHighlights = (0, parse_js_1.extractHeadingContent)(icpContent, '## ICP Highlights') ??
+        (0, parse_js_1.extractHeadingContent)(icpContent, '## Target Users') ??
+        (0, parse_js_1.extractHeadingContent)(featuresContent, '### Expected Features') ??
+        (0, parse_js_1.extractHeadingContent)(featuresContent, '## Expected Features') ??
+        '';
+    const competitionLandscape = (0, parse_js_1.extractHeadingContent)(competitionContent, '## Competitor Analysis') ??
+        (0, parse_js_1.extractHeadingContent)(competitionContent, '## Landscape') ??
+        (0, parse_js_1.extractHeadingContent)(featuresContent, '## Competitor Feature Analysis') ??
+        '';
+    const gtmPositioning = (0, parse_js_1.extractHeadingContent)(gtmContent, '## GTM Positioning') ??
+        (0, parse_js_1.extractHeadingContent)(gtmContent, '## Positioning') ??
+        (0, parse_js_1.extractHeadingContent)(gtmContent, '## Executive Summary') ??
+        '';
+    // Synthesize journeyInsights from journeys array
+    const journeyTypeCounts = new Map();
+    for (const journey of journeys) {
+        const count = journeyTypeCounts.get(journey.type) ?? 0;
+        journeyTypeCounts.set(journey.type, count + 1);
+    }
+    const journeyInsightParts = [];
+    for (const journey of journeys) {
+        const frCount = journey.linkedFRs.length;
+        journeyInsightParts.push(`${journey.id} (${journey.name}, type: ${journey.type}, FRs: ${frCount})`);
+    }
+    const journeyInsights = journeyInsightParts.length > 0
+        ? journeyInsightParts.join('\n')
+        : '';
+    return {
+        vision,
+        targetUser,
+        productDirection,
+        wedge,
+        frozenDecisions,
+        successMetrics,
+        outOfScope,
+        risks,
+        openQuestions,
+        approvals,
+        frs,
+        roles,
+        nfrs,
+        journeys,
+        integrations,
+        projectSlug,
+        architectureSummary,
+        icpHighlights,
+        competitionLandscape,
+        gtmPositioning,
+        journeyInsights,
+    };
+}
+// ─── 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.
+ */
+function generateProjectDoc(bundle) {
+    const lines = [];
+    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('');
+    // ── ## Context section ──────────────────────────────────────────────────────
+    lines.push('## Context');
+    lines.push('');
+    lines.push('Product context synthesized from GSWD research pipeline. Each subsection summarizes key findings and references the source artifact.');
+    lines.push('');
+    // Architecture Summary
+    lines.push('### Architecture Summary');
+    lines.push('');
+    if (bundle.architectureSummary) {
+        lines.push(bundle.architectureSummary);
+    }
+    else {
+        lines.push('*(Architecture research not available — run /gswd:imagine to generate)*');
+    }
+    lines.push('');
+    lines.push('> See: .planning/research/ARCHITECTURE.md for full details');
+    lines.push('');
+    // ICP Highlights
+    lines.push('### ICP Highlights');
+    lines.push('');
+    if (bundle.icpHighlights) {
+        lines.push(bundle.icpHighlights);
+    }
+    else {
+        lines.push('*(ICP research not available)*');
+    }
+    lines.push('');
+    lines.push('> See: .planning/research/ICP.md for full details');
+    lines.push('');
+    // Competition Landscape
+    lines.push('### Competition Landscape');
+    lines.push('');
+    if (bundle.competitionLandscape) {
+        lines.push(bundle.competitionLandscape);
+    }
+    else {
+        lines.push('*(Competition research not available)*');
+    }
+    lines.push('');
+    lines.push('> See: .planning/research/COMPETITION.md for full details');
+    lines.push('');
+    // GTM Positioning
+    lines.push('### GTM Positioning');
+    lines.push('');
+    if (bundle.gtmPositioning) {
+        lines.push(bundle.gtmPositioning);
+    }
+    else {
+        lines.push('*(GTM research not available)*');
+    }
+    lines.push('');
+    lines.push('> See: .planning/research/GTM.md for full details');
+    lines.push('');
+    // Journey Insights
+    lines.push('### Journey Insights');
+    lines.push('');
+    if (bundle.journeyInsights) {
+        lines.push(bundle.journeyInsights);
+    }
+    else if (bundle.journeys.length > 0) {
+        // Synthesize from journeys array
+        for (const j of bundle.journeys) {
+            lines.push(`${j.id} (${j.name}, type: ${j.type}, FRs: ${j.linkedFRs.length})`);
+        }
+    }
+    else {
+        lines.push('*(No journeys defined)*');
+    }
+    lines.push('');
+    lines.push('> See: .planning/research/FEATURES.md for full details');
+    lines.push('');
+    // GSWD Artifacts table
+    lines.push('### GSWD Artifacts');
+    lines.push('');
+    lines.push('| File | Description |');
+    lines.push('|------|-------------|');
+    lines.push('| .planning/IMAGINE.md | Product vision, target user, and direction |');
+    lines.push('| .planning/DECISIONS.md | Frozen decisions, success metrics, risks |');
+    lines.push('| .planning/SPEC.md | Functional requirements with IDs |');
+    lines.push('| .planning/NFR.md | Non-functional requirements |');
+    lines.push('| .planning/JOURNEYS.md | User journeys with FR linkages |');
+    lines.push('| .planning/INTEGRATIONS.md | External integrations and fallbacks |');
+    lines.push('| .planning/research/ARCHITECTURE.md | Architecture research |');
+    lines.push('| .planning/research/FEATURES.md | Feature landscape research |');
+    lines.push('| .planning/research/PITFALLS.md | Common pitfalls research |');
+    lines.push('| .planning/research/STACK.md | Technology stack research |');
+    lines.push('| .planning/research/SUMMARY.md | Research executive summary |');
+    lines.push('| .planning/research/gswd/SUMMARY.md | GSD-format research bridge |');
+    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.
+ */
+function generateRequirementsDoc(bundle) {
+    const lines = [];
+    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');
+    // Build a journey map for quick lookup
+    const journeyMap = new Map();
+    for (const journey of bundle.journeys) {
+        journeyMap.set(journey.id, journey);
+    }
+    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}`);
+        // Journey origin
+        if (fr.sourceJourneys.length > 0) {
+            const journeyRefs = fr.sourceJourneys
+                .sort()
+                .map((jId) => {
+                const journey = journeyMap.get(jId);
+                return journey ? `${jId}: ${journey.name}` : jId;
+            })
+                .join(', ');
+            lines.push(`**Origin:** From ${journeyRefs}`);
+        }
+        // Acceptance criteria
+        if (fr.acceptanceCriteria && fr.acceptanceCriteria.length > 0) {
+            lines.push('**Acceptance Criteria:**');
+            for (const criterion of fr.acceptanceCriteria) {
+                lines.push(`- ${criterion}`);
+            }
+        }
+        // NFR constraints — apply heuristic based on NFR category
+        const applicableNFRs = [];
+        for (const nfr of bundle.nfrs) {
+            const cat = nfr.category.toLowerCase();
+            // Security and performance apply to all v1 FRs
+            if (cat === 'security' || cat === 'performance') {
+                applicableNFRs.push(`${nfr.id} (${nfr.category.charAt(0).toUpperCase() + nfr.category.slice(1)})`);
+                continue;
+            }
+            // Observability applies to all v1 FRs
+            if (cat === 'observability') {
+                applicableNFRs.push(`${nfr.id} (${nfr.category.charAt(0).toUpperCase() + nfr.category.slice(1)})`);
+                continue;
+            }
+            // Privacy applies if FR touches user/data/personal/profile/account keywords
+            if (cat === 'privacy') {
+                const desc = fr.description.toLowerCase();
+                if (desc.includes('user') || desc.includes('data') || desc.includes('personal') ||
+                    desc.includes('profile') || desc.includes('account')) {
+                    applicableNFRs.push(`${nfr.id} (${nfr.category.charAt(0).toUpperCase() + nfr.category.slice(1)})`);
+                }
+            }
+        }
+        if (applicableNFRs.length > 0) {
+            lines.push(`**Applicable NFR Constraints:** ${applicableNFRs.join(', ')}`);
+        }
+        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 exports.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.
+ */
+function generateRoadmapDoc(bundle) {
+    const lines = [];
+    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();
+    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 = exports.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}: ${exports.PHASE_NAMES[phaseNum]}`);
+        lines.push('');
+        if (phaseNum < 4) {
+            const journeys = phaseJourneys.get(phaseNum);
+            if (journeys.length === 0) {
+                lines.push('*(no journeys assigned)*');
+            }
+            else {
+                // Emit a Goal line with journey IDs
+                const goalJourneys = journeys
+                    .map((j) => `${j.id} (${j.name})`)
+                    .join(', ');
+                lines.push(`**Goal:** Implement ${goalJourneys}`);
+                lines.push('');
+                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 {
+                // Emit a Goal line for Phase 4
+                const nfrGoal = obsSecNFRs.map((nfr) => nfr.id).join(', ');
+                lines.push(`**Goal:** Enforce ${nfrGoal}`);
+                lines.push('');
+                for (const nfr of obsSecNFRs) {
+                    lines.push(`- **${nfr.id}**: ${nfr.description}`);
+                }
+            }
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/**
+ * Generate a GSD-format research SUMMARY.md from SpecBundle.
+ *
+ * Maps GSWD spec content to GSD research template headings.
+ * Pure function — no Date calls, no I/O.
+ * Versioned with <!-- gswd-schema-version: 1 --> header.
+ */
+function generateResearchSummary(bundle) {
+    const lines = [];
+    lines.push('<!-- gswd-schema-version: 1 -->');
+    lines.push('# Project Research Summary');
+    lines.push('');
+    lines.push(`**Project:** ${bundle.projectSlug}`);
+    lines.push('**Domain:** Product specification');
+    lines.push('**Confidence:** HIGH');
+    lines.push('');
+    // ## Executive Summary
+    lines.push('## Executive Summary');
+    lines.push('');
+    if (bundle.vision) {
+        lines.push(bundle.vision);
+        lines.push('');
+    }
+    if (bundle.productDirection) {
+        lines.push(bundle.productDirection);
+        lines.push('');
+    }
+    // ## Key Findings
+    lines.push('## Key Findings');
+    lines.push('');
+    // ### Recommended Stack
+    lines.push('### Recommended Stack');
+    lines.push('');
+    if (bundle.architectureSummary) {
+        lines.push(bundle.architectureSummary);
+    }
+    else {
+        lines.push('*(Stack research not available from GSWD — will be determined during GSD planning)*');
+    }
+    lines.push('');
+    // ### Expected Features
+    lines.push('### Expected Features');
+    lines.push('');
+    if (bundle.icpHighlights) {
+        lines.push(bundle.icpHighlights);
+    }
+    else {
+        // Synthesize from FRs
+        const p0FRs = bundle.frs.filter((f) => f.scope === 'v1' && f.priority === 'P0');
+        const p1FRs = bundle.frs.filter((f) => f.scope === 'v1' && f.priority === 'P1');
+        if (p0FRs.length > 0) {
+            lines.push('**Must have (table stakes):**');
+            for (const fr of p0FRs) {
+                lines.push(`- ${fr.description}`);
+            }
+            lines.push('');
+        }
+        if (p1FRs.length > 0) {
+            lines.push('**Should have:**');
+            for (const fr of p1FRs) {
+                lines.push(`- ${fr.description}`);
+            }
+        }
+    }
+    lines.push('');
+    // ### Architecture Approach
+    lines.push('### Architecture Approach');
+    lines.push('');
+    if (bundle.architectureSummary) {
+        lines.push(bundle.architectureSummary);
+    }
+    else {
+        lines.push('*(Architecture to be determined during GSD planning)*');
+    }
+    lines.push('');
+    // ### Critical Pitfalls
+    lines.push('### Critical Pitfalls');
+    lines.push('');
+    if (bundle.risks.length > 0) {
+        for (const risk of bundle.risks) {
+            lines.push(`- ${risk}`);
+        }
+    }
+    else {
+        lines.push('*(No risks identified)*');
+    }
+    lines.push('');
+    // ## Implications for Roadmap
+    lines.push('## Implications for Roadmap');
+    lines.push('');
+    // Group journeys by phase and describe implications
+    const phaseJourneyMap = new Map();
+    for (let i = 1; i <= 4; i++) {
+        phaseJourneyMap.set(i, []);
+    }
+    for (const journey of bundle.journeys) {
+        const phase = exports.JOURNEY_TYPE_TO_PHASE[journey.type] ?? 3;
+        phaseJourneyMap.get(phase).push(journey);
+    }
+    for (let phaseNum = 1; phaseNum <= 3; phaseNum++) {
+        const phaseJ = phaseJourneyMap.get(phaseNum);
+        if (phaseJ.length > 0) {
+            const journeyList = phaseJ.map((j) => `${j.id} (${j.name})`).join(', ');
+            lines.push(`- **Phase ${phaseNum}**: ${exports.PHASE_NAMES[phaseNum]} — ${journeyList}`);
+        }
+    }
+    const obsSecNFRs = bundle.nfrs.filter((nfr) => nfr.category === 'observability' || nfr.category === 'security');
+    if (obsSecNFRs.length > 0) {
+        const nfrList = obsSecNFRs.map((nfr) => nfr.id).join(', ');
+        lines.push(`- **Phase 4**: ${exports.PHASE_NAMES[4]} — enforce ${nfrList}`);
+    }
+    lines.push('');
+    // ## Confidence Assessment
+    lines.push('## Confidence Assessment');
+    lines.push('');
+    lines.push('| Area | Confidence | Notes |');
+    lines.push('|------|------------|-------|');
+    lines.push(`| Stack | ${bundle.architectureSummary ? 'HIGH' : 'LOW'} | ${bundle.architectureSummary ? 'From GSWD research' : 'Not researched in GSWD'} |`);
+    lines.push(`| Features | HIGH | ${bundle.frs.length} FRs defined with traceability |`);
+    lines.push(`| Architecture | ${bundle.architectureSummary ? 'HIGH' : 'MEDIUM'} | ${bundle.architectureSummary ? 'From GSWD research' : 'Inferred from requirements'} |`);
+    lines.push(`| Pitfalls | MEDIUM | ${bundle.risks.length} risks identified |`);
+    lines.push('');
+    // ## Sources
+    lines.push('## Sources');
+    lines.push('');
+    lines.push('### Primary (HIGH confidence)');
+    lines.push('- GSWD specification pipeline — full imagine/specify/audit/compile cycle');
+    lines.push('');
+    lines.push('---');
+    lines.push('*Research completed: via GSWD compile*');
+    lines.push('*Ready for roadmap: yes*');
+    lines.push('');
+    return lines.join('\n');
+}
+// ─── 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
+ */
+function validateContracts(generatedDocs, bundle) {
+    const findings = [];
+    // 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();
+    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 = [
+        ['PROJECT.md', generatedDocs.project],
+        ['REQUIREMENTS.md', generatedDocs.requirements],
+        ['ROADMAP.md', generatedDocs.roadmap],
+        ['STATE.md', generatedDocs.state],
+    ];
+    for (const [fileType, content] of docMap) {
+        const validation = (0, parse_js_1.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.
+ */
+function generateStateDoc(bundle) {
+    const lines = [];
+    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.
+ * Also reads research files from .planning/research/ directory.
+ * Returns a content map keyed by artifact type.
+ * Missing files return empty string (does not throw).
+ */
+function readSpecArtifacts(planningDir) {
+    const fileMap = [
+        ['IMAGINE.md', 'imagine'],
+        ['DECISIONS.md', 'decisions'],
+        ['SPEC.md', 'spec'],
+        ['NFR.md', 'nfr'],
+        ['JOURNEYS.md', 'journeys'],
+        ['INTEGRATIONS.md', 'integrations'],
+    ];
+    const result = {};
+    for (const [filename, key] of fileMap) {
+        try {
+            result[key] = fs.readFileSync(path.join(planningDir, filename), 'utf-8');
+        }
+        catch {
+            result[key] = '';
+        }
+    }
+    // Read research files from .planning/research/ subdirectory
+    const researchDir = path.join(planningDir, 'research');
+    const researchFileMap = [
+        ['ARCHITECTURE.md', 'architecture'],
+        ['ICP.md', 'icp'],
+        ['COMPETITION.md', 'competition'],
+        ['GTM.md', 'gtm'],
+        ['SUMMARY.md', 'researchSummary'],
+        ['FEATURES.md', 'features'],
+    ];
+    for (const [filename, key] of researchFileMap) {
+        try {
+            result[key] = fs.readFileSync(path.join(researchDir, filename), 'utf-8');
+        }
+        catch {
+            result[key] = '';
+        }
+    }
+    return result;
+}
+// ─── 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.
+ */
+function runCompileWorkflow(options) {
+    const { planningDir, statePath } = options;
+    // Step 1: Check audit gate
+    if (!(0, audit_js_1.checkAuditGate)(statePath)) {
+        return { passed: false, error: 'Audit gate not passed', filesWritten: [] };
+    }
+    // Step 2: Update stage status -> in_progress
+    (0, state_js_1.updateStageStatus)(statePath, 'compile', 'in_progress');
+    // Step 3: Read spec artifacts
+    const files = readSpecArtifacts(planningDir);
+    // Step 4: Parse into SpecBundle (includes research file enrichment)
+    const bundle = parseSpecBundle({
+        imagine: files['imagine'] ?? '',
+        decisions: files['decisions'] ?? '',
+        spec: files['spec'] ?? '',
+        nfr: files['nfr'] ?? '',
+        journeys: files['journeys'] ?? '',
+        integrations: files['integrations'] ?? '',
+        architecture: files['architecture'] ?? '',
+        icp: files['icp'] ?? '',
+        competition: files['competition'] ?? '',
+        gtm: files['gtm'] ?? '',
+        researchSummary: files['researchSummary'] ?? '',
+        features: files['features'] ?? '',
+    }, statePath);
+    // Step 5: Generate all 4 contract docs + GSD research bridge (pure functions)
+    const generated = {
+        project: generateProjectDoc(bundle),
+        requirements: generateRequirementsDoc(bundle),
+        roadmap: generateRoadmapDoc(bundle),
+        state: generateStateDoc(bundle),
+        researchSummary: generateResearchSummary(bundle),
+    };
+    // Step 6: Run validator
+    const validatorResult = validateContracts(generated, bundle);
+    // Step 7: If validator FAIL, update state -> fail and return early
+    if (!validatorResult.passed) {
+        (0, state_js_1.updateStageStatus)(statePath, 'compile', 'fail');
+        return { passed: false, validatorResult, filesWritten: [] };
+    }
+    // Step 8: Write all 4 contract docs atomically
+    const fileOutputMap = [
+        ['PROJECT.md', generated.project],
+        ['REQUIREMENTS.md', generated.requirements],
+        ['ROADMAP.md', generated.roadmap],
+        ['STATE.md', generated.state],
+    ];
+    const filesWritten = [];
+    for (const [filename, content] of fileOutputMap) {
+        const filePath = path.join(planningDir, filename);
+        (0, state_js_1.safeWriteFile)(filePath, content);
+        filesWritten.push(filePath);
+    }
+    // Step 8b: Write GSD research bridge SUMMARY.md to .planning/research/gswd/SUMMARY.md
+    // planningDir resolves to .planning/ in production; research/gswd/ is a subdirectory
+    const gsdResearchDir = path.join(planningDir, 'research', 'gswd');
+    if (!fs.existsSync(gsdResearchDir)) {
+        fs.mkdirSync(gsdResearchDir, { recursive: true });
+    }
+    const summaryPath = path.join(gsdResearchDir, 'SUMMARY.md');
+    (0, state_js_1.safeWriteFile)(summaryPath, generated.researchSummary);
+    filesWritten.push(summaryPath);
+    // Step 9: Update state: stage_status.compile = 'done', stage = 'compile'
+    (0, state_js_1.updateStageStatus)(statePath, 'compile', 'done');
+    const state = (0, state_js_1.readState)(statePath);
+    if (state) {
+        state.stage = 'compile';
+        (0, state_js_1.writeState)(statePath, state);
+    }
+    // Step 10: Write checkpoint
+    (0, state_js_1.writeCheckpoint)(statePath, 'gswd/compile', 'compile-done');
+    // Step 11: Return result
+    return { passed: true, validatorResult, filesWritten, generated };
+}