gswd 1.0.0 → 1.1.0

package/dist/tests/compile.test.js

@@ -0,0 +1,862 @@
+"use strict";
+/**
+ * Compile module tests — spec bundle parsing, sort helpers, and 4 document generators
+ */
+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 });
+const node_test_1 = require("node:test");
+const assert = __importStar(require("node:assert"));
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
+const compile_js_1 = require("../lib/compile.js");
+// ─── Test Fixture ────────────────────────────────────────────────────────────
+/**
+ * Build a minimal SpecBundle for testing.
+ *
+ * - 2 journey types: onboarding J-001 (Phase 1) and error_states J-002 (Phase 3)
+ * - J-001 has linkedIntegrations: ['I-001'] to exercise integration_sanity path
+ * - 3 FRs with different scope/priority: FR-001 (v1/P0), FR-002 (v1/P1), FR-003 (v2/P1)
+ * - 2 NFRs in different categories: NFR-001 (security), NFR-002 (performance)
+ * - 1 integration (I-001 approved)
+ * - Basic vision/targetUser/productDirection/wedge strings
+ * - 2 frozen decisions, 1 metric, 1 out-of-scope, 1 risk, 1 open question
+ */
+function makeTestBundle() {
+    const frs = [
+        { id: 'FR-001', description: 'User can register', scope: 'v1', priority: 'P0', sourceJourneys: ['J-001'] },
+        { id: 'FR-002', description: 'User can set profile', scope: 'v1', priority: 'P1', sourceJourneys: ['J-001'] },
+        { id: 'FR-003', description: 'Advanced reporting', scope: 'v2', priority: 'P1', sourceJourneys: [] },
+    ];
+    const nfrs = [
+        { id: 'NFR-001', description: 'Data encrypted at rest', category: 'security', threshold: 'AES-256' },
+        { id: 'NFR-002', description: 'API response under 200ms', category: 'performance', threshold: 'p95 < 200ms' },
+    ];
+    const journeys = [
+        { id: 'J-001', name: 'User Onboarding', type: 'onboarding', linkedFRs: ['FR-001', 'FR-002'], linkedIntegrations: ['I-001'] },
+        { id: 'J-002', name: 'Error Handling', type: 'error_states', linkedFRs: ['FR-001'], linkedIntegrations: [] },
+    ];
+    const integrations = [
+        { id: 'I-001', name: 'Email Provider', status: 'approved', fallback: 'Manual email' },
+    ];
+    return {
+        vision: 'A tool that helps developers ship faster',
+        targetUser: 'Solo developers and small teams',
+        productDirection: 'Eliminate boilerplate and reduce setup friction',
+        wedge: 'One-click project scaffolding',
+        frozenDecisions: [
+            'Use TypeScript throughout',
+            'Prefer zero external dependencies',
+        ],
+        successMetrics: ['10 projects scaffolded in first month'],
+        outOfScope: ['Multi-tenant support in v1'],
+        risks: ['Dependency on external CLI tools'],
+        openQuestions: ['Should we support Windows?'],
+        approvals: {
+            auth_model: 'passwordless_email',
+            data_store: 'sqlite',
+        },
+        frs,
+        roles: 'Admin role only',
+        nfrs,
+        journeys,
+        integrations,
+        projectSlug: 'test-project',
+    };
+}
+// ─── sortFRs ─────────────────────────────────────────────────────────────────
+(0, node_test_1.describe)('sortFRs', () => {
+    (0, node_test_1.it)('sorts v1 before v2 before out', () => {
+        const frs = [
+            { id: 'FR-003', description: 'Out of scope thing', scope: 'out', priority: 'P0', sourceJourneys: [] },
+            { id: 'FR-002', description: 'Future feature', scope: 'v2', priority: 'P0', sourceJourneys: [] },
+            { id: 'FR-001', description: 'Core feature', scope: 'v1', priority: 'P0', sourceJourneys: [] },
+        ];
+        const sorted = (0, compile_js_1.sortFRs)(frs);
+        assert.strictEqual(sorted[0].scope, 'v1');
+        assert.strictEqual(sorted[1].scope, 'v2');
+        assert.strictEqual(sorted[2].scope, 'out');
+    });
+    (0, node_test_1.it)('within same scope, sorts P0 before P1 before P2', () => {
+        const frs = [
+            { id: 'FR-003', description: 'Low priority', scope: 'v1', priority: 'P2', sourceJourneys: [] },
+            { id: 'FR-002', description: 'Medium priority', scope: 'v1', priority: 'P1', sourceJourneys: [] },
+            { id: 'FR-001', description: 'High priority', scope: 'v1', priority: 'P0', sourceJourneys: [] },
+        ];
+        const sorted = (0, compile_js_1.sortFRs)(frs);
+        assert.strictEqual(sorted[0].priority, 'P0');
+        assert.strictEqual(sorted[1].priority, 'P1');
+        assert.strictEqual(sorted[2].priority, 'P2');
+    });
+    (0, node_test_1.it)('within same scope+priority, sorts by numeric ID ascending (FR-001 before FR-010)', () => {
+        const frs = [
+            { id: 'FR-010', description: 'Later FR', scope: 'v1', priority: 'P0', sourceJourneys: [] },
+            { id: 'FR-001', description: 'First FR', scope: 'v1', priority: 'P0', sourceJourneys: [] },
+            { id: 'FR-005', description: 'Middle FR', scope: 'v1', priority: 'P0', sourceJourneys: [] },
+        ];
+        const sorted = (0, compile_js_1.sortFRs)(frs);
+        assert.strictEqual(sorted[0].id, 'FR-001');
+        assert.strictEqual(sorted[1].id, 'FR-005');
+        assert.strictEqual(sorted[2].id, 'FR-010');
+    });
+});
+// ─── parseSpecBundle ─────────────────────────────────────────────────────────
+(0, node_test_1.describe)('parseSpecBundle', () => {
+    const MINIMAL_IMAGINE = `## Vision
+A tool that helps developers ship faster
+
+## Target User
+Solo developers and small teams
+
+## Product Direction
+Eliminate boilerplate and reduce setup friction
+
+## Wedge
+One-click project scaffolding
+`;
+    const MINIMAL_DECISIONS = `## Frozen Decisions
+
+1. Use TypeScript throughout
+2. Prefer zero external dependencies
+
+## Success Metrics
+
+- 10 projects scaffolded in first month
+
+## Out of Scope
+
+- Multi-tenant support in v1
+
+## Risks & Mitigations
+
+- Dependency on external CLI tools
+
+## Open Questions
+
+- Should we support Windows?
+`;
+    const MINIMAL_SPEC = `## Roles & Permissions
+Admin role only.
+
+## Functional Requirements
+
+### FR-001: User can register
+**Scope:** v1
+**Priority:** P0
+
+### FR-002: User can set profile
+**Scope:** v1
+**Priority:** P1
+
+### FR-003: Advanced reporting
+**Scope:** v2
+**Priority:** P1
+
+## Acceptance Criteria
+TBD
+`;
+    const MINIMAL_NFR = `## Non-Functional Requirements
+
+### NFR-001: Data encrypted at rest
+**Category:** security
+**Threshold:** AES-256
+
+### NFR-002: API response under 200ms
+**Category:** performance
+**Threshold:** p95 < 200ms
+`;
+    const MINIMAL_JOURNEYS = `## Journeys
+
+### J-001: User Onboarding
+**Type:** onboarding
+**Linked FRs:** FR-001, FR-002
+**Linked Integrations:** I-001
+
+#### Acceptance Tests
+- User completes onboarding
+
+### J-002: Error Handling
+**Type:** error_states
+**Linked FRs:** FR-001
+**Linked Integrations:** none
+`;
+    const MINIMAL_INTEGRATIONS = `## Integrations
+
+### I-001: Email Provider
+**Status:** approved
+**Fallback:** Manual email
+`;
+    (0, node_test_1.it)('parses minimal valid spec bundle (all 6 files present) into SpecBundle with correct field population', () => {
+        const bundle = (0, compile_js_1.parseSpecBundle)({
+            imagine: MINIMAL_IMAGINE,
+            decisions: MINIMAL_DECISIONS,
+            spec: MINIMAL_SPEC,
+            nfr: MINIMAL_NFR,
+            journeys: MINIMAL_JOURNEYS,
+            integrations: MINIMAL_INTEGRATIONS,
+        });
+        assert.ok(bundle.vision.length > 0, 'vision should be populated');
+        assert.ok(bundle.targetUser.length > 0, 'targetUser should be populated');
+        assert.ok(bundle.frozenDecisions.length >= 1, 'frozenDecisions should have entries');
+        assert.ok(bundle.frs.length === 3, 'should parse 3 FRs');
+        assert.ok(bundle.nfrs.length === 2, 'should parse 2 NFRs');
+        assert.ok(bundle.journeys.length === 2, 'should parse 2 journeys');
+        assert.ok(bundle.integrations.length === 1, 'should parse 1 integration');
+        // Verify FR fields
+        const fr001 = bundle.frs.find(fr => fr.id === 'FR-001');
+        assert.ok(fr001, 'FR-001 should be parsed');
+        assert.strictEqual(fr001.scope, 'v1');
+        assert.strictEqual(fr001.priority, 'P0');
+    });
+    (0, node_test_1.it)('handles missing optional fields gracefully (empty arrays, empty strings)', () => {
+        const bundle = (0, compile_js_1.parseSpecBundle)({
+            imagine: '',
+            decisions: '',
+            spec: '',
+            nfr: '',
+            journeys: '',
+            integrations: '',
+        });
+        assert.strictEqual(bundle.frs.length, 0, 'empty spec -> no FRs');
+        assert.strictEqual(bundle.nfrs.length, 0, 'empty nfr -> no NFRs');
+        assert.strictEqual(bundle.journeys.length, 0, 'empty journeys -> no journeys');
+        assert.strictEqual(bundle.integrations.length, 0, 'empty integrations -> no integrations');
+        assert.strictEqual(bundle.frozenDecisions.length, 0, 'empty decisions -> no frozen decisions');
+        assert.strictEqual(bundle.vision, '', 'empty imagine -> empty vision');
+    });
+});
+// ─── generateProjectDoc ───────────────────────────────────────────────────────
+(0, node_test_1.describe)('generateProjectDoc', () => {
+    (0, node_test_1.it)('produces markdown containing all required headings', () => {
+        const bundle = makeTestBundle();
+        const doc = (0, compile_js_1.generateProjectDoc)(bundle);
+        assert.ok(doc.includes('## What This Is'), 'should have What This Is section');
+        assert.ok(doc.includes('## Target User'), 'should have Target User section');
+        assert.ok(doc.includes('## Problem Statement'), 'should have Problem Statement section');
+        assert.ok(doc.includes('## Wedge / MVP Boundary'), 'should have Wedge section');
+        assert.ok(doc.includes('## Success Metrics'), 'should have Success Metrics section');
+        assert.ok(doc.includes('## Out of Scope'), 'should have Out of Scope section');
+    });
+    (0, node_test_1.it)('content from bundle appears in correct sections', () => {
+        const bundle = makeTestBundle();
+        const doc = (0, compile_js_1.generateProjectDoc)(bundle);
+        assert.ok(doc.includes(bundle.vision), 'vision should appear in doc');
+        assert.ok(doc.includes(bundle.targetUser), 'targetUser should appear in doc');
+        assert.ok(doc.includes(bundle.productDirection), 'productDirection should appear in doc');
+        assert.ok(doc.includes(bundle.wedge), 'wedge should appear in doc');
+        assert.ok(doc.includes(bundle.successMetrics[0]), 'success metric should appear in doc');
+        assert.ok(doc.includes(bundle.outOfScope[0]), 'out-of-scope item should appear in doc');
+    });
+});
+// ─── generateRequirementsDoc ──────────────────────────────────────────────────
+(0, node_test_1.describe)('generateRequirementsDoc', () => {
+    (0, node_test_1.it)('FRs are grouped by scope (v1 section before v2 section), sorted by priority within scope', () => {
+        const bundle = makeTestBundle();
+        const doc = (0, compile_js_1.generateRequirementsDoc)(bundle);
+        // v1 section should appear before v2 section
+        const v1Pos = doc.indexOf('### v1 (In Scope)');
+        const v2Pos = doc.indexOf('### v2 (Future)');
+        assert.ok(v1Pos !== -1, 'v1 section should be present');
+        assert.ok(v2Pos !== -1, 'v2 section should be present');
+        assert.ok(v1Pos < v2Pos, 'v1 section should appear before v2 section');
+        // Within v1, P0 (FR-001) should appear before P1 (FR-002)
+        const fr001Pos = doc.indexOf('FR-001');
+        const fr002Pos = doc.indexOf('FR-002');
+        assert.ok(fr001Pos < fr002Pos, 'FR-001 (P0) should appear before FR-002 (P1)');
+    });
+    (0, node_test_1.it)('NFRs grouped by category in fixed order (security, privacy, performance, observability)', () => {
+        const bundle = makeTestBundle();
+        const doc = (0, compile_js_1.generateRequirementsDoc)(bundle);
+        // Security should appear before performance (no privacy or observability in test bundle)
+        const secPos = doc.indexOf('### Security');
+        const perfPos = doc.indexOf('### Performance');
+        assert.ok(secPos !== -1, 'Security section should be present');
+        assert.ok(perfPos !== -1, 'Performance section should be present');
+        assert.ok(secPos < perfPos, 'Security should appear before Performance');
+        // NFR content should be present
+        assert.ok(doc.includes('NFR-001'), 'NFR-001 should be in doc');
+        assert.ok(doc.includes('NFR-002'), 'NFR-002 should be in doc');
+    });
+    (0, node_test_1.it)('traceability table present with FR-to-journey mapping', () => {
+        const bundle = makeTestBundle();
+        const doc = (0, compile_js_1.generateRequirementsDoc)(bundle);
+        assert.ok(doc.includes('## Traceability'), 'should have Traceability section');
+        assert.ok(doc.includes('| FR |'), 'should have table header with FR column');
+        assert.ok(doc.includes('| Description |'), 'should have table header with Description column');
+        assert.ok(doc.includes('| Journeys |'), 'should have table header with Journeys column');
+        // FR-001 (v1) should appear in traceability table with journey reference
+        const tracePos = doc.indexOf('## Traceability');
+        const fr001TracePos = doc.indexOf('FR-001', tracePos);
+        assert.ok(fr001TracePos !== -1, 'FR-001 should be in traceability table');
+    });
+});
+// ─── generateRoadmapDoc ───────────────────────────────────────────────────────
+(0, node_test_1.describe)('generateRoadmapDoc', () => {
+    (0, node_test_1.it)('all 4 phases always present in output', () => {
+        const bundle = makeTestBundle();
+        const doc = (0, compile_js_1.generateRoadmapDoc)(bundle);
+        assert.ok(doc.includes('### Phase 1'), 'Phase 1 should always be present');
+        assert.ok(doc.includes('### Phase 2'), 'Phase 2 should always be present');
+        assert.ok(doc.includes('### Phase 3'), 'Phase 3 should always be present');
+        assert.ok(doc.includes('### Phase 4'), 'Phase 4 should always be present');
+    });
+    (0, node_test_1.it)('journeys assigned to correct phases by type (onboarding->Phase1, error_states->Phase3)', () => {
+        const bundle = makeTestBundle();
+        const doc = (0, compile_js_1.generateRoadmapDoc)(bundle);
+        // J-001 (onboarding) -> Phase 1
+        const phase1Start = doc.indexOf('### Phase 1');
+        const phase2Start = doc.indexOf('### Phase 2');
+        const j001InPhase1 = doc.indexOf('J-001', phase1Start) < phase2Start;
+        assert.ok(j001InPhase1, 'J-001 (onboarding) should be in Phase 1');
+        // J-002 (error_states) -> Phase 3
+        const phase3Start = doc.indexOf('### Phase 3');
+        const phase4Start = doc.indexOf('### Phase 4');
+        const j002InPhase3 = doc.indexOf('J-002', phase3Start) < phase4Start;
+        assert.ok(j002InPhase3, 'J-002 (error_states) should be in Phase 3');
+    });
+    (0, node_test_1.it)('Phase 4 contains observability+security NFRs, not journeys', () => {
+        const bundle = makeTestBundle();
+        const doc = (0, compile_js_1.generateRoadmapDoc)(bundle);
+        const phase4Start = doc.indexOf('### Phase 4');
+        const phase4Content = doc.slice(phase4Start);
+        // NFR-001 (security) should be in Phase 4
+        assert.ok(phase4Content.includes('NFR-001'), 'NFR-001 (security) should be in Phase 4');
+        // Phase 4 should NOT contain journey IDs (J-001, J-002)
+        assert.ok(!phase4Content.includes('J-001'), 'journeys should not appear in Phase 4');
+        assert.ok(!phase4Content.includes('J-002'), 'journeys should not appear in Phase 4');
+    });
+});
+// ─── generateStateDoc ─────────────────────────────────────────────────────────
+(0, node_test_1.describe)('generateStateDoc', () => {
+    (0, node_test_1.it)('contains frozen decisions, approvals, open questions, risks sections', () => {
+        const bundle = makeTestBundle();
+        const doc = (0, compile_js_1.generateStateDoc)(bundle);
+        assert.ok(doc.includes('## Frozen Decisions'), 'should have Frozen Decisions section');
+        assert.ok(doc.includes('## Approvals'), 'should have Approvals section');
+        assert.ok(doc.includes('## Open Questions'), 'should have Open Questions section');
+        assert.ok(doc.includes('## Risks'), 'should have Risks section');
+    });
+    (0, node_test_1.it)('all required headings present and content populated from bundle', () => {
+        const bundle = makeTestBundle();
+        const doc = (0, compile_js_1.generateStateDoc)(bundle);
+        // Frozen decisions content
+        assert.ok(doc.includes(bundle.frozenDecisions[0]), 'first frozen decision should appear in doc');
+        assert.ok(doc.includes(bundle.frozenDecisions[1]), 'second frozen decision should appear in doc');
+        // Open questions content
+        assert.ok(doc.includes(bundle.openQuestions[0]), 'open question should appear in doc');
+        // Risks content
+        assert.ok(doc.includes(bundle.risks[0]), 'risk should appear in doc');
+    });
+});
+// ─── Determinism ─────────────────────────────────────────────────────────────
+(0, node_test_1.describe)('determinism', () => {
+    (0, node_test_1.it)('running all 4 generators twice with same bundle produces byte-identical strings', () => {
+        const bundle1 = makeTestBundle();
+        const bundle2 = makeTestBundle();
+        // Run generators twice
+        const project1 = (0, compile_js_1.generateProjectDoc)(bundle1);
+        const project2 = (0, compile_js_1.generateProjectDoc)(bundle2);
+        const requirements1 = (0, compile_js_1.generateRequirementsDoc)(bundle1);
+        const requirements2 = (0, compile_js_1.generateRequirementsDoc)(bundle2);
+        const roadmap1 = (0, compile_js_1.generateRoadmapDoc)(bundle1);
+        const roadmap2 = (0, compile_js_1.generateRoadmapDoc)(bundle2);
+        const state1 = (0, compile_js_1.generateStateDoc)(bundle1);
+        const state2 = (0, compile_js_1.generateStateDoc)(bundle2);
+        assert.strictEqual(project1, project2, 'generateProjectDoc must be deterministic');
+        assert.strictEqual(requirements1, requirements2, 'generateRequirementsDoc must be deterministic');
+        assert.strictEqual(roadmap1, roadmap2, 'generateRoadmapDoc must be deterministic');
+        assert.strictEqual(state1, state2, 'generateStateDoc must be deterministic');
+    });
+});
+// ─── validateContracts ────────────────────────────────────────────────────────
+/**
+ * Generate all 4 docs from the test bundle for use in validator tests.
+ */
+function makeTestDocs(bundle) {
+    return {
+        project: (0, compile_js_1.generateProjectDoc)(bundle),
+        requirements: (0, compile_js_1.generateRequirementsDoc)(bundle),
+        roadmap: (0, compile_js_1.generateRoadmapDoc)(bundle),
+        state: (0, compile_js_1.generateStateDoc)(bundle),
+    };
+}
+(0, node_test_1.describe)('validateContracts() — v1 coverage check', () => {
+    (0, node_test_1.it)('PASS when all v1 FRs appear in generated roadmap content', () => {
+        const bundle = makeTestBundle();
+        const docs = makeTestDocs(bundle);
+        const result = (0, compile_js_1.validateContracts)(docs, bundle);
+        // No v1_coverage findings (FR-001 and FR-002 should appear in the roadmap via journeys)
+        const coverageFindings = result.findings.filter(f => f.check === 'v1_coverage');
+        assert.strictEqual(coverageFindings.length, 0, 'should have no v1_coverage findings when all v1 FRs are covered');
+    });
+    (0, node_test_1.it)('FAIL with finding when a v1 FR is missing from roadmap content', () => {
+        const bundle = makeTestBundle();
+        // Add a v1 FR with a unique ID that will not appear in the generated roadmap
+        const missingFR = {
+            id: 'FR-099',
+            description: 'A feature not covered by any journey',
+            scope: 'v1',
+            priority: 'P1',
+            sourceJourneys: ['J-001'], // Has a journey so orphan check passes
+        };
+        const bundleWithMissingFR = { ...bundle, frs: [...bundle.frs, missingFR] };
+        const docs = makeTestDocs(bundle); // Roadmap generated without FR-099
+        const result = (0, compile_js_1.validateContracts)(docs, bundleWithMissingFR);
+        const coverageFindings = result.findings.filter(f => f.check === 'v1_coverage');
+        assert.ok(coverageFindings.length > 0, 'should have v1_coverage finding when FR is missing from roadmap');
+        assert.ok(coverageFindings.some(f => f.id === 'FR-099'), 'finding should reference the missing FR-099');
+    });
+});
+(0, node_test_1.describe)('validateContracts() — orphan requirements check', () => {
+    (0, node_test_1.it)('PASS when all v1 FRs are referenced by at least 1 journey', () => {
+        const bundle = makeTestBundle();
+        // In makeTestBundle: FR-001 -> J-001, FR-002 -> J-001
+        const docs = makeTestDocs(bundle);
+        const result = (0, compile_js_1.validateContracts)(docs, bundle);
+        const orphanFindings = result.findings.filter(f => f.check === 'orphan_requirement');
+        assert.strictEqual(orphanFindings.length, 0, 'should have no orphan_requirement findings when all v1 FRs have journey refs');
+    });
+    (0, node_test_1.it)('FAIL with finding for v1 FR not referenced by any journey', () => {
+        const bundle = makeTestBundle();
+        // Add an orphan v1 FR with no sourceJourneys
+        const orphanFR = { id: 'FR-004', description: 'Orphan FR', scope: 'v1', priority: 'P1', sourceJourneys: [] };
+        const modifiedBundle = { ...bundle, frs: [...bundle.frs, orphanFR] };
+        const docs = makeTestDocs(modifiedBundle);
+        // Also inject FR-004 into roadmap so v1_coverage check passes for it
+        const modifiedDocs = { ...docs, roadmap: docs.roadmap + '\nFR-004\n' };
+        const result = (0, compile_js_1.validateContracts)(modifiedDocs, modifiedBundle);
+        const orphanFindings = result.findings.filter(f => f.check === 'orphan_requirement');
+        assert.ok(orphanFindings.length > 0, 'should have orphan_requirement finding for FR-004');
+        assert.ok(orphanFindings.some(f => f.id === 'FR-004'), 'finding should reference the orphan FR-004');
+    });
+});
+(0, node_test_1.describe)('validateContracts() — integration sanity check', () => {
+    (0, node_test_1.it)('PASS when all integrations referenced by journeys are approved or deferred-with-fallback', () => {
+        const bundle = makeTestBundle();
+        // In makeTestBundle: I-001 is 'approved' and referenced by J-001
+        const docs = makeTestDocs(bundle);
+        const result = (0, compile_js_1.validateContracts)(docs, bundle);
+        const integrationFindings = result.findings.filter(f => f.check === 'integration_sanity');
+        assert.strictEqual(integrationFindings.length, 0, 'should have no integration_sanity findings for approved integrations');
+    });
+    (0, node_test_1.it)('FAIL when a journey linkedIntegrations references an integration with unapproved status', () => {
+        const bundle = makeTestBundle();
+        // Change I-001 to an unapproved status without fallback
+        const badIntegration = { id: 'I-001', name: 'Email Provider', status: 'rejected', fallback: '' };
+        const modifiedBundle = { ...bundle, integrations: [badIntegration] };
+        const docs = makeTestDocs(bundle); // Use original docs
+        const result = (0, compile_js_1.validateContracts)(docs, modifiedBundle);
+        const integrationFindings = result.findings.filter(f => f.check === 'integration_sanity');
+        assert.ok(integrationFindings.length > 0, 'should have integration_sanity finding for rejected integration');
+        assert.ok(integrationFindings.some(f => f.id === 'I-001'), 'finding should reference the unapproved I-001');
+    });
+});
+(0, node_test_1.describe)('validateContracts() — required headings check', () => {
+    (0, node_test_1.it)('PASS when all 4 generated docs contain their required headings', () => {
+        const bundle = makeTestBundle();
+        const docs = makeTestDocs(bundle);
+        const result = (0, compile_js_1.validateContracts)(docs, bundle);
+        const headingFindings = result.findings.filter(f => f.check === 'required_headings');
+        assert.strictEqual(headingFindings.length, 0, 'should have no required_headings findings for complete generated docs');
+    });
+    (0, node_test_1.it)('FAIL when a generated doc is missing a required heading', () => {
+        const bundle = makeTestBundle();
+        const docs = makeTestDocs(bundle);
+        // Remove a required heading from the project doc
+        const modifiedDocs = { ...docs, project: docs.project.replace('## What This Is', '## REMOVED') };
+        const result = (0, compile_js_1.validateContracts)(modifiedDocs, bundle);
+        const headingFindings = result.findings.filter(f => f.check === 'required_headings');
+        assert.ok(headingFindings.length > 0, 'should have required_headings finding when heading is missing');
+        assert.ok(headingFindings.some(f => f.id === 'PROJECT.md'), 'finding should reference the file with missing heading');
+    });
+});
+(0, node_test_1.describe)('validateContracts() — combined', () => {
+    (0, node_test_1.it)('returns { passed: true, findings: [] } when all 4 checks pass', () => {
+        const bundle = makeTestBundle();
+        const docs = makeTestDocs(bundle);
+        const result = (0, compile_js_1.validateContracts)(docs, bundle);
+        assert.strictEqual(result.passed, true, 'should pass when all checks pass');
+        assert.strictEqual(result.findings.length, 0, 'should have no findings when all checks pass');
+    });
+    (0, node_test_1.it)('returns { passed: false, findings: [...] } with multiple findings when multiple checks fail', () => {
+        const bundle = makeTestBundle();
+        // Add a v1 FR with unique ID not in roadmap (v1_coverage failure)
+        const missingFR = {
+            id: 'FR-099',
+            description: 'A feature not covered by any journey',
+            scope: 'v1',
+            priority: 'P1',
+            sourceJourneys: ['J-001'], // Has a journey so orphan check passes
+        };
+        const bundleWithMissingFR = { ...bundle, frs: [...bundle.frs, missingFR] };
+        const baseDocs = makeTestDocs(bundle); // Roadmap generated without FR-099
+        // Also remove a required heading from project doc (required_headings failure)
+        const modifiedDocs = {
+            ...baseDocs,
+            project: baseDocs.project.replace('## What This Is', '## REMOVED'),
+        };
+        const result = (0, compile_js_1.validateContracts)(modifiedDocs, bundleWithMissingFR);
+        assert.strictEqual(result.passed, false, 'should fail when any check fails');
+        assert.ok(result.findings.length >= 2, 'should have multiple findings when multiple checks fail');
+        const checkTypes = new Set(result.findings.map(f => f.check));
+        assert.ok(checkTypes.has('v1_coverage'), 'should have v1_coverage finding');
+        assert.ok(checkTypes.has('required_headings'), 'should have required_headings finding');
+    });
+});
+// ─── Workflow Orchestrator ────────────────────────────────────────────────────
+// Minimal spec artifact content strings for workflow tests
+const WORKFLOW_IMAGINE = `## Vision
+A tool that helps developers ship faster
+
+## Target User
+Solo developers and small teams
+
+## Product Direction
+Eliminate boilerplate and reduce setup friction
+
+## Wedge
+One-click project scaffolding
+`;
+const WORKFLOW_DECISIONS = `## Frozen Decisions
+
+1. Use TypeScript throughout
+2. Prefer zero external dependencies
+
+## Success Metrics
+
+- 10 projects scaffolded in first month
+
+## Out of Scope
+
+- Multi-tenant support in v1
+
+## Risks & Mitigations
+
+- Dependency on external CLI tools
+
+## Open Questions
+
+- Should we support Windows?
+`;
+const WORKFLOW_SPEC = `## Roles & Permissions
+Admin role only.
+
+## Functional Requirements
+
+### FR-001: User can register
+**Scope:** v1
+**Priority:** P0
+
+### FR-002: User can set profile
+**Scope:** v1
+**Priority:** P1
+
+## Acceptance Criteria
+TBD
+`;
+const WORKFLOW_NFR = `## Non-Functional Requirements
+
+### NFR-001: Data encrypted at rest
+**Category:** security
+**Threshold:** AES-256
+`;
+const WORKFLOW_JOURNEYS = `## Journeys
+
+### J-001: User Onboarding
+**Type:** onboarding
+**Linked FRs:** FR-001, FR-002
+**Linked Integrations:** none
+
+#### Acceptance Tests
+- User completes onboarding
+`;
+const WORKFLOW_INTEGRATIONS = `## Integrations
+
+`;
+// Helper to create a temp directory with spec artifact files
+function makeTempPlanningDir(options = {}) {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gswd-test-'));
+    // Create STATE.json
+    const state = {
+        version: 1,
+        project_slug: 'test-project',
+        created_at: '2026-01-01T00:00:00.000Z',
+        updated_at: '2026-01-01T00:00:00.000Z',
+        stage: 'audit',
+        stage_status: {
+            imagine: 'done',
+            specify: 'done',
+            audit: options.includeAuditPass ? 'pass' : 'fail',
+            compile: 'not_started',
+        },
+        last_checkpoint: null,
+        auto: { enabled: false, policy: 'balanced', interrupt_reasons: [] },
+        approvals: {
+            auth_model: 'passwordless_email',
+            data_store: 'sqlite',
+            paid_integrations: [],
+        },
+    };
+    const statePath = path.join(tmpDir, 'STATE.json');
+    fs.writeFileSync(statePath, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+    // Write spec artifact files
+    fs.writeFileSync(path.join(tmpDir, 'IMAGINE.md'), WORKFLOW_IMAGINE, 'utf-8');
+    fs.writeFileSync(path.join(tmpDir, 'DECISIONS.md'), WORKFLOW_DECISIONS, 'utf-8');
+    fs.writeFileSync(path.join(tmpDir, 'SPEC.md'), options.customSpec ?? WORKFLOW_SPEC, 'utf-8');
+    fs.writeFileSync(path.join(tmpDir, 'NFR.md'), WORKFLOW_NFR, 'utf-8');
+    fs.writeFileSync(path.join(tmpDir, 'JOURNEYS.md'), options.customJourneys ?? WORKFLOW_JOURNEYS, 'utf-8');
+    fs.writeFileSync(path.join(tmpDir, 'INTEGRATIONS.md'), WORKFLOW_INTEGRATIONS, 'utf-8');
+    return {
+        planningDir: tmpDir,
+        statePath,
+        cleanup: () => {
+            try {
+                fs.rmSync(tmpDir, { recursive: true, force: true });
+            }
+            catch { /* ignore */ }
+        },
+    };
+}
+(0, node_test_1.describe)('readSpecArtifacts()', () => {
+    (0, node_test_1.it)('reads all 6 artifact files from a temp planning directory', () => {
+        const { planningDir, cleanup } = makeTempPlanningDir({ includeAuditPass: true });
+        try {
+            const artifacts = (0, compile_js_1.readSpecArtifacts)(planningDir);
+            assert.ok(typeof artifacts['imagine'] === 'string', 'should have imagine key');
+            assert.ok(typeof artifacts['decisions'] === 'string', 'should have decisions key');
+            assert.ok(typeof artifacts['spec'] === 'string', 'should have spec key');
+            assert.ok(typeof artifacts['nfr'] === 'string', 'should have nfr key');
+            assert.ok(typeof artifacts['journeys'] === 'string', 'should have journeys key');
+            assert.ok(typeof artifacts['integrations'] === 'string', 'should have integrations key');
+            assert.ok(artifacts['imagine'].length > 0, 'imagine content should be non-empty');
+            assert.ok(artifacts['spec'].length > 0, 'spec content should be non-empty');
+        }
+        finally {
+            cleanup();
+        }
+    });
+    (0, node_test_1.it)('returns empty strings for missing files (does not throw)', () => {
+        const emptyDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gswd-empty-'));
+        try {
+            const artifacts = (0, compile_js_1.readSpecArtifacts)(emptyDir);
+            assert.strictEqual(artifacts['imagine'], '', 'missing IMAGINE.md -> empty string');
+            assert.strictEqual(artifacts['spec'], '', 'missing SPEC.md -> empty string');
+            assert.strictEqual(artifacts['journeys'], '', 'missing JOURNEYS.md -> empty string');
+        }
+        finally {
+            try {
+                fs.rmSync(emptyDir, { recursive: true, force: true });
+            }
+            catch { /* ignore */ }
+        }
+    });
+});
+(0, node_test_1.describe)('runCompileWorkflow() — audit gate', () => {
+    (0, node_test_1.it)('returns { passed: false, error: "Audit gate not passed" } when audit status is not pass', () => {
+        const { planningDir, statePath, cleanup } = makeTempPlanningDir({ includeAuditPass: false });
+        try {
+            const result = (0, compile_js_1.runCompileWorkflow)({ planningDir, statePath });
+            assert.strictEqual(result.passed, false, 'should fail when audit gate not passed');
+            assert.ok(result.error?.includes('Audit gate not passed'), 'error should mention audit gate');
+            assert.deepStrictEqual(result.filesWritten, [], 'no files should be written');
+        }
+        finally {
+            cleanup();
+        }
+    });
+});
+(0, node_test_1.describe)('runCompileWorkflow() — happy path', () => {
+    (0, node_test_1.it)('given valid spec artifacts and audit gate passing, produces all 4 contract files and updates state', () => {
+        const { planningDir, statePath, cleanup } = makeTempPlanningDir({ includeAuditPass: true });
+        try {
+            const result = (0, compile_js_1.runCompileWorkflow)({ planningDir, statePath });
+            assert.strictEqual(result.passed, true, 'workflow should pass');
+            assert.ok(!result.error, 'no error should be set');
+            // 4 files should be written
+            assert.ok(result.filesWritten.length === 4, 'should write exactly 4 contract files');
+            // All 4 contract files should exist on disk
+            const expectedFiles = ['PROJECT.md', 'REQUIREMENTS.md', 'ROADMAP.md', 'STATE.md'];
+            for (const filename of expectedFiles) {
+                const filepath = path.join(planningDir, filename);
+                assert.ok(fs.existsSync(filepath), `${filename} should exist on disk`);
+            }
+            // STATE.json should be updated: stage_status.compile = 'done', stage = 'compile'
+            const updatedState = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+            assert.strictEqual(updatedState.stage_status.compile, 'done', 'compile status should be done');
+            assert.strictEqual(updatedState.stage, 'compile', 'stage should be compile');
+            // validator should have passed
+            assert.ok(result.validatorResult?.passed, 'validator should pass');
+        }
+        finally {
+            cleanup();
+        }
+    });
+});
+(0, node_test_1.describe)('runCompileWorkflow() — validator FAIL', () => {
+    (0, node_test_1.it)('when validator fails, no contract files written and state updated to fail', () => {
+        // Create a spec where FR-001 is v1 but no journey references it (orphan)
+        // Additionally, no journey at all means v1 FRs won't appear in roadmap
+        const orphanSpec = `## Roles & Permissions
+Admin role only.
+
+## Functional Requirements
+
+### FR-001: User can register
+**Scope:** v1
+**Priority:** P0
+
+## Acceptance Criteria
+TBD
+`;
+        // No journeys means FR-001 won't appear in roadmap -> v1_coverage FAIL
+        // Also FR-001 has no sourceJourneys -> orphan_requirement FAIL
+        const emptyJourneys = `## Journeys
+
+`;
+        const { planningDir, statePath, cleanup } = makeTempPlanningDir({
+            includeAuditPass: true,
+            customSpec: orphanSpec,
+            customJourneys: emptyJourneys,
+        });
+        try {
+            const result = (0, compile_js_1.runCompileWorkflow)({ planningDir, statePath });
+            assert.strictEqual(result.passed, false, 'workflow should fail when validator fails');
+            assert.ok(!result.error, 'error field should not be set for validator failure (use validatorResult instead)');
+            // No contract files should be on disk
+            const contractFiles = ['PROJECT.md', 'REQUIREMENTS.md', 'ROADMAP.md', 'STATE.md'];
+            for (const filename of contractFiles) {
+                const filepath = path.join(planningDir, filename);
+                assert.ok(!fs.existsSync(filepath), `${filename} should NOT exist on disk when validator fails`);
+            }
+            // STATE.json compile status should be 'fail'
+            const updatedState = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+            assert.strictEqual(updatedState.stage_status.compile, 'fail', 'compile status should be fail');
+            // filesWritten should be empty
+            assert.deepStrictEqual(result.filesWritten, [], 'no files should be written when validator fails');
+        }
+        finally {
+            cleanup();
+        }
+    });
+});
+// ─── Golden-File Tests (TEST-04) ──────────────────────────────────────────────
+const FIXTURE_SPEC_BUNDLE_DIR = path.join(__dirname, 'fixtures/compile/spec_bundle');
+const FIXTURE_EXPECTED_CONTRACT_DIR = path.join(__dirname, 'fixtures/compile/expected_contract');
+/**
+ * Read fixture spec bundle files and parse into SpecBundle with projectSlug = 'taskflow'.
+ * Used by golden-file tests to ensure consistent input parsing.
+ */
+function loadFixtureBundle() {
+    const files = {
+        imagine: fs.readFileSync(path.join(FIXTURE_SPEC_BUNDLE_DIR, 'IMAGINE.md'), 'utf-8'),
+        decisions: fs.readFileSync(path.join(FIXTURE_SPEC_BUNDLE_DIR, 'DECISIONS.md'), 'utf-8'),
+        spec: fs.readFileSync(path.join(FIXTURE_SPEC_BUNDLE_DIR, 'SPEC.md'), 'utf-8'),
+        nfr: fs.readFileSync(path.join(FIXTURE_SPEC_BUNDLE_DIR, 'NFR.md'), 'utf-8'),
+        journeys: fs.readFileSync(path.join(FIXTURE_SPEC_BUNDLE_DIR, 'JOURNEYS.md'), 'utf-8'),
+        integrations: fs.readFileSync(path.join(FIXTURE_SPEC_BUNDLE_DIR, 'INTEGRATIONS.md'), 'utf-8'),
+    };
+    // No statePath — projectSlug defaults to ''. Explicitly set to 'taskflow' per plan spec.
+    const bundle = (0, compile_js_1.parseSpecBundle)(files);
+    bundle.projectSlug = 'taskflow';
+    return bundle;
+}
+(0, node_test_1.describe)('golden-file tests (TEST-04)', () => {
+    (0, node_test_1.describe)('compile(spec_bundle) matches expected_contract', () => {
+        (0, node_test_1.it)('generateProjectDoc output matches expected_contract/PROJECT.md byte-for-byte', () => {
+            const bundle = loadFixtureBundle();
+            const generated = (0, compile_js_1.generateProjectDoc)(bundle);
+            const expected = fs.readFileSync(path.join(FIXTURE_EXPECTED_CONTRACT_DIR, 'PROJECT.md'), 'utf-8');
+            assert.strictEqual(generated, expected, 'generateProjectDoc must be byte-identical to golden PROJECT.md');
+        });
+        (0, node_test_1.it)('generateRequirementsDoc output matches expected_contract/REQUIREMENTS.md byte-for-byte', () => {
+            const bundle = loadFixtureBundle();
+            const generated = (0, compile_js_1.generateRequirementsDoc)(bundle);
+            const expected = fs.readFileSync(path.join(FIXTURE_EXPECTED_CONTRACT_DIR, 'REQUIREMENTS.md'), 'utf-8');
+            assert.strictEqual(generated, expected, 'generateRequirementsDoc must be byte-identical to golden REQUIREMENTS.md');
+        });
+        (0, node_test_1.it)('generateRoadmapDoc output matches expected_contract/ROADMAP.md byte-for-byte', () => {
+            const bundle = loadFixtureBundle();
+            const generated = (0, compile_js_1.generateRoadmapDoc)(bundle);
+            const expected = fs.readFileSync(path.join(FIXTURE_EXPECTED_CONTRACT_DIR, 'ROADMAP.md'), 'utf-8');
+            assert.strictEqual(generated, expected, 'generateRoadmapDoc must be byte-identical to golden ROADMAP.md');
+        });
+        (0, node_test_1.it)('generateStateDoc output matches expected_contract/STATE.md byte-for-byte', () => {
+            const bundle = loadFixtureBundle();
+            const generated = (0, compile_js_1.generateStateDoc)(bundle);
+            const expected = fs.readFileSync(path.join(FIXTURE_EXPECTED_CONTRACT_DIR, 'STATE.md'), 'utf-8');
+            assert.strictEqual(generated, expected, 'generateStateDoc must be byte-identical to golden STATE.md');
+        });
+    });
+    (0, node_test_1.describe)('compile is deterministic across runs (CMPL-07)', () => {
+        (0, node_test_1.it)('running all 4 generators twice on same fixture produces byte-identical output', () => {
+            // Parse fixture bundle twice independently
+            const bundle1 = loadFixtureBundle();
+            const bundle2 = loadFixtureBundle();
+            // Generate all 4 docs from each bundle
+            const result1 = {
+                project: (0, compile_js_1.generateProjectDoc)(bundle1),
+                requirements: (0, compile_js_1.generateRequirementsDoc)(bundle1),
+                roadmap: (0, compile_js_1.generateRoadmapDoc)(bundle1),
+                state: (0, compile_js_1.generateStateDoc)(bundle1),
+            };
+            const result2 = {
+                project: (0, compile_js_1.generateProjectDoc)(bundle2),
+                requirements: (0, compile_js_1.generateRequirementsDoc)(bundle2),
+                roadmap: (0, compile_js_1.generateRoadmapDoc)(bundle2),
+                state: (0, compile_js_1.generateStateDoc)(bundle2),
+            };
+            assert.strictEqual(result1.project, result2.project, 'generateProjectDoc must be deterministic across runs');
+            assert.strictEqual(result1.requirements, result2.requirements, 'generateRequirementsDoc must be deterministic across runs');
+            assert.strictEqual(result1.roadmap, result2.roadmap, 'generateRoadmapDoc must be deterministic across runs');
+            assert.strictEqual(result1.state, result2.state, 'generateStateDoc must be deterministic across runs');
+        });
+    });
+    (0, node_test_1.describe)('golden files have correct structure', () => {
+        (0, node_test_1.it)('all 4 golden files pass validateHeadings() for their file types', () => {
+            const { validateHeadings } = require('../lib/parse.js');
+            const goldenFiles = [
+                ['PROJECT.md', path.join(FIXTURE_EXPECTED_CONTRACT_DIR, 'PROJECT.md')],
+                ['REQUIREMENTS.md', path.join(FIXTURE_EXPECTED_CONTRACT_DIR, 'REQUIREMENTS.md')],
+                ['ROADMAP.md', path.join(FIXTURE_EXPECTED_CONTRACT_DIR, 'ROADMAP.md')],
+                ['STATE.md', path.join(FIXTURE_EXPECTED_CONTRACT_DIR, 'STATE.md')],
+            ];
+            for (const [fileType, filePath] of goldenFiles) {
+                const content = fs.readFileSync(filePath, 'utf-8');
+                const validation = validateHeadings(content, fileType);
+                assert.ok(validation.valid, `Golden file ${fileType} failed heading validation. Missing: ${validation.missing.join(', ')}`);
+            }
+        });
+    });
+});