gswd 1.0.1 → 1.1.0

package/dist/lib/bootstrap.d.ts

@@ -0,0 +1,103 @@
+/**
+ * GSWD Bootstrap Module — Pipeline orchestrator, policy engine, resume gate
+ *
+ * Contains:
+ * - runBootstrap(): async orchestrator that wires imagine -> specify -> audit -> compile
+ * - Types: BootstrapOptions, BootstrapResult, BootstrapStage, PolicyCheckInput, PolicyCheckResult
+ * - Policy engine: checkPolicy() with 4 detection functions
+ * - Resume gate: validateStageArtifacts(), shouldSkipStage()
+ * - Interrupt handler: handleInterrupt()
+ * - Auto decision display: renderAutoDecisionSummary()
+ * - Stage artifacts map: STAGE_ARTIFACTS
+ *
+ * Schema: GSWD_SPEC.md Section 8.1, 10.1-10.4
+ */
+import type { StageStatus } from './state.js';
+import type { GswdConfig } from './config.js';
+import type { AutoDecision } from './imagine-synthesis.js';
+export interface BootstrapOptions {
+    ideaFilePath?: string;
+    auto: boolean;
+    resume?: boolean;
+    skipResearch?: boolean;
+    policy?: 'strict' | 'balanced' | 'aggressive';
+    planningDir?: string;
+    configPath?: string;
+    spawnFn?: unknown;
+}
+export type BootstrapStage = 'imagine' | 'specify' | 'audit' | 'compile';
+export interface BootstrapResult {
+    status: 'done' | 'failed' | 'interrupted';
+    stagesCompleted: BootstrapStage[];
+    artifactsWritten: string[];
+    autoDecisions: AutoDecision[];
+    interruptReasons: string[];
+    autoFixCycles: number;
+    error?: string;
+}
+export interface PolicyCheckInput {
+    config: GswdConfig;
+    integrationsContent?: string;
+    decisionsContent?: string;
+    nfrContent?: string;
+}
+export interface PolicyCheckResult {
+    shouldInterrupt: boolean;
+    reasons: string[];
+}
+/**
+ * Required artifact filenames per stage.
+ * Used by validateStageArtifacts() and shouldSkipStage().
+ */
+export declare const STAGE_ARTIFACTS: Record<BootstrapStage, string[]>;
+/**
+ * Check policy violations. Returns whether auto mode should be interrupted
+ * and the specific reasons.
+ *
+ * Checks:
+ * 1. Paid integrations not pre-approved
+ * 2. Credential requirements
+ * 3. Conflicting requirements (decisions vs integrations)
+ * 4. Security posture mismatches (NFR vs config)
+ */
+export declare function checkPolicy(input: PolicyCheckInput): PolicyCheckResult;
+/**
+ * Validate that all expected artifacts for a stage exist on disk and are non-empty.
+ * Returns { complete, missing } where missing lists filenames not found or empty.
+ */
+export declare function validateStageArtifacts(planningDir: string, stage: BootstrapStage): {
+    complete: boolean;
+    missing: string[];
+};
+/**
+ * Determine if a stage can be skipped during resume.
+ * Only skips if: resume=true AND stage is done/pass AND all artifacts are present.
+ */
+export declare function shouldSkipStage(stage: BootstrapStage, state: {
+    stage_status: StageStatus | Record<string, string>;
+}, planningDir: string, resume: boolean): boolean;
+/**
+ * Handle a policy interrupt: write reasons to STATE.json, render checkpoint, return result.
+ * MUST write to STATE.json BEFORE rendering (Pitfall 6).
+ */
+export declare function handleInterrupt(reasons: string[], statePath: string, stagesCompleted: BootstrapStage[], allArtifacts: string[], allAutoDecisions: AutoDecision[], autoFixCycles: number): BootstrapResult;
+/**
+ * Render a human-readable summary of auto-mode decisions.
+ * Returns empty string if no decisions.
+ */
+export declare function renderAutoDecisionSummary(decisions: AutoDecision[]): string;
+/**
+ * Run the full bootstrap pipeline: init -> imagine -> specify -> audit -> compile.
+ *
+ * Implements GSWD_SPEC Section 8.1:
+ * - Auto mode threads autoMode/auto/autoFix to each stage
+ * - Resume mode skips completed stages with valid artifacts
+ * - Policy checks fire after imagine and after specify
+ * - Audit FAIL blocks compile (BOOT-03)
+ * - Auto-fix enabled with max 2 cycles when policy allows (BOOT-04)
+ * - state.stage = 'done' after successful compile (Pitfall 8)
+ *
+ * IMPORTANT: runImagine() and runSpecify() are ASYNC — use await.
+ *            runAuditWorkflow() and runCompileWorkflow() are SYNC — no await.
+ */
+export declare function runBootstrap(options: BootstrapOptions): Promise<BootstrapResult>;

package/dist/lib/bootstrap.js

@@ -0,0 +1,563 @@
+"use strict";
+/**
+ * GSWD Bootstrap Module — Pipeline orchestrator, policy engine, resume gate
+ *
+ * Contains:
+ * - runBootstrap(): async orchestrator that wires imagine -> specify -> audit -> compile
+ * - Types: BootstrapOptions, BootstrapResult, BootstrapStage, PolicyCheckInput, PolicyCheckResult
+ * - Policy engine: checkPolicy() with 4 detection functions
+ * - Resume gate: validateStageArtifacts(), shouldSkipStage()
+ * - Interrupt handler: handleInterrupt()
+ * - Auto decision display: renderAutoDecisionSummary()
+ * - Stage artifacts map: STAGE_ARTIFACTS
+ *
+ * Schema: GSWD_SPEC.md Section 8.1, 10.1-10.4
+ */
+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.STAGE_ARTIFACTS = void 0;
+exports.checkPolicy = checkPolicy;
+exports.validateStageArtifacts = validateStageArtifacts;
+exports.shouldSkipStage = shouldSkipStage;
+exports.handleInterrupt = handleInterrupt;
+exports.renderAutoDecisionSummary = renderAutoDecisionSummary;
+exports.runBootstrap = runBootstrap;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const state_js_1 = require("./state.js");
+const config_js_1 = require("./config.js");
+const render_js_1 = require("./render.js");
+const imagine_js_1 = require("./imagine.js");
+const specify_js_1 = require("./specify.js");
+const audit_js_1 = require("./audit.js");
+const compile_js_1 = require("./compile.js");
+// ─── Stage Artifacts ─────────────────────────────────────────────────────────
+/**
+ * Required artifact filenames per stage.
+ * Used by validateStageArtifacts() and shouldSkipStage().
+ */
+exports.STAGE_ARTIFACTS = {
+    imagine: ['IMAGINE.md', 'ICP.md', 'GTM.md', 'COMPETITION.md', 'DECISIONS.md'],
+    specify: ['SPEC.md', 'JOURNEYS.md', 'NFR.md', 'ARCHITECTURE.md', 'INTEGRATIONS.md'],
+    audit: ['AUDIT.md'],
+    compile: ['PROJECT.md', 'REQUIREMENTS.md', 'ROADMAP.md', 'STATE.md'],
+};
+// ─── Policy Engine — Detection Functions ─────────────────────────────────────
+/**
+ * Detect integrations with a positive monthly cost.
+ * Parses dollar amounts from integration sections (### I-NNN headings).
+ * Returns array of integration IDs with cost > $0.
+ */
+function detectPaidIntegrations(integrationsContent) {
+    const paidIds = [];
+    // Match integration section headings: ### I-001: Name or ## I-001: Name
+    const intRegex = /^#{2,3}\s+(I-\d{1,4})[:\s]/gm;
+    const positions = [];
+    let match;
+    while ((match = intRegex.exec(integrationsContent)) !== null) {
+        positions.push({ id: match[1], start: match.index });
+    }
+    for (let i = 0; i < positions.length; i++) {
+        const end = i + 1 < positions.length ? positions[i + 1].start : integrationsContent.length;
+        const section = integrationsContent.slice(positions[i].start, end);
+        // Look for dollar amounts: $50, $25.99, 50 USD/month
+        const costMatch = section.match(/\$(\d+(?:\.\d+)?)|(\d+(?:\.\d+)?)\s*(?:USD|usd)\/month/);
+        if (costMatch) {
+            const amount = parseFloat(costMatch[1] ?? costMatch[2] ?? '0');
+            if (amount > 0) {
+                paidIds.push(positions[i].id);
+            }
+        }
+    }
+    return paidIds;
+}
+/**
+ * Detect integrations that require credentials (API keys, OAuth secrets, etc.).
+ * Returns array of { id, requirement } objects.
+ */
+function detectCredentialRequirements(integrationsContent) {
+    const credentials = [];
+    const intRegex = /^#{2,3}\s+(I-\d{1,4})[:\s]/gm;
+    const positions = [];
+    let match;
+    while ((match = intRegex.exec(integrationsContent)) !== null) {
+        positions.push({ id: match[1], start: match.index });
+    }
+    for (let i = 0; i < positions.length; i++) {
+        const end = i + 1 < positions.length ? positions[i + 1].start : integrationsContent.length;
+        const section = integrationsContent.slice(positions[i].start, end);
+        // Look for credential-related patterns
+        const credPatterns = [
+            /\b(?:API\s*key)\s*required\b/i,
+            /\bOAuth\s*(?:secret|token|key)\b/i,
+            /\bcredentials?\s*(?:required|needed)\b/i,
+            /\bsecret\s*(?:key|required)\b/i,
+        ];
+        for (const pattern of credPatterns) {
+            const credMatch = section.match(pattern);
+            if (credMatch) {
+                credentials.push({ id: positions[i].id, requirement: credMatch[0] });
+                break; // One match per integration is enough
+            }
+        }
+    }
+    return credentials;
+}
+/**
+ * Detect contradictions between decisions and integrations.
+ * E.g., "no accounts" decision + Stripe integration = conflict.
+ */
+function detectConflicts(decisionsContent, integrationsContent) {
+    const conflicts = [];
+    const noAccountsDecision = /\bno\s+accounts?\b/i.test(decisionsContent) ||
+        /\bno\s+auth\b/i.test(decisionsContent);
+    const hasStripe = /stripe/i.test(integrationsContent);
+    const hasPayments = /payment/i.test(integrationsContent);
+    if (noAccountsDecision && (hasStripe || hasPayments)) {
+        conflicts.push('Conflicting requirements: decision says "no accounts" but integrations include payment processing (requires accounts)');
+    }
+    return conflicts;
+}
+/**
+ * Detect security posture mismatches between NFR content and config.
+ * E.g., HIPAA/SOC2/PCI requirements without explicit config approval.
+ */
+function detectSecurityPosture(nfrContent, config) {
+    const flags = [];
+    const securityPatterns = [
+        { pattern: /\bHIPAA\b/i, label: 'HIPAA' },
+        { pattern: /\bSOC\s*2\b/i, label: 'SOC2' },
+        { pattern: /\bPCI[\s-]*DSS\b/i, label: 'PCI-DSS' },
+        { pattern: /\bGDPR\b/i, label: 'GDPR' },
+    ];
+    for (const { pattern, label } of securityPatterns) {
+        if (pattern.test(nfrContent)) {
+            // Check if config has explicit security approval
+            // For now, config has no explicit security_approvals field,
+            // so any compliance requirement triggers an interrupt
+            flags.push(`Security posture mismatch: ${label} compliance referenced in NFR but not explicitly approved in config — requires human review`);
+        }
+    }
+    return flags;
+}
+// ─── Policy Engine — Main Function ───────────────────────────────────────────
+/**
+ * Check policy violations. Returns whether auto mode should be interrupted
+ * and the specific reasons.
+ *
+ * Checks:
+ * 1. Paid integrations not pre-approved
+ * 2. Credential requirements
+ * 3. Conflicting requirements (decisions vs integrations)
+ * 4. Security posture mismatches (NFR vs config)
+ */
+function checkPolicy(input) {
+    const reasons = [];
+    const { config } = input;
+    // 1. Paid integrations not pre-approved
+    if (input.integrationsContent) {
+        const paidIntegrations = detectPaidIntegrations(input.integrationsContent);
+        const preapproved = new Set(config.auto.preapproved_integrations);
+        for (const intId of paidIntegrations) {
+            if (!preapproved.has(intId) && !config.auto.allow_paid_integrations_under_budget) {
+                reasons.push(`Paid integration ${intId} requires pre-approval (not in preapproved_integrations)`);
+            }
+        }
+    }
+    // 2. Credentials that cannot be inferred
+    if (input.integrationsContent) {
+        const credentialRequired = detectCredentialRequirements(input.integrationsContent);
+        for (const cred of credentialRequired) {
+            reasons.push(`Integration ${cred.id} requires credentials: ${cred.requirement}`);
+        }
+    }
+    // 3. Conflicting requirements
+    if (input.decisionsContent && input.integrationsContent) {
+        const conflicts = detectConflicts(input.decisionsContent, input.integrationsContent);
+        reasons.push(...conflicts);
+    }
+    // 4. Security posture mismatches
+    if (input.nfrContent) {
+        const securityFlags = detectSecurityPosture(input.nfrContent, config);
+        reasons.push(...securityFlags);
+    }
+    return { shouldInterrupt: reasons.length > 0, reasons };
+}
+// ─── Resume Gate ─────────────────────────────────────────────────────────────
+/**
+ * Validate that all expected artifacts for a stage exist on disk and are non-empty.
+ * Returns { complete, missing } where missing lists filenames not found or empty.
+ */
+function validateStageArtifacts(planningDir, stage) {
+    const required = exports.STAGE_ARTIFACTS[stage] ?? [];
+    const missing = [];
+    for (const filename of required) {
+        const filepath = path.join(planningDir, filename);
+        if (!fs.existsSync(filepath)) {
+            missing.push(filename);
+        }
+        else {
+            // Check non-zero bytes (Pitfall 2: empty files)
+            try {
+                const stat = fs.statSync(filepath);
+                if (stat.size === 0) {
+                    missing.push(filename);
+                }
+            }
+            catch {
+                missing.push(filename);
+            }
+        }
+    }
+    return { complete: missing.length === 0, missing };
+}
+/**
+ * Determine if a stage can be skipped during resume.
+ * Only skips if: resume=true AND stage is done/pass AND all artifacts are present.
+ */
+function shouldSkipStage(stage, state, planningDir, resume) {
+    if (!resume)
+        return false;
+    const stageStatus = state.stage_status[stage];
+    const isDone = stageStatus === 'done' || stageStatus === 'pass';
+    if (!isDone)
+        return false;
+    // Validate artifacts before trusting checkpoint (RESM-03)
+    const { complete } = validateStageArtifacts(planningDir, stage);
+    return complete;
+}
+// ─── Interrupt Handler ───────────────────────────────────────────────────────
+/**
+ * Handle a policy interrupt: write reasons to STATE.json, render checkpoint, return result.
+ * MUST write to STATE.json BEFORE rendering (Pitfall 6).
+ */
+function handleInterrupt(reasons, statePath, stagesCompleted, allArtifacts, allAutoDecisions, autoFixCycles) {
+    // Step 1: Write to STATE.json FIRST
+    const state = (0, state_js_1.readState)(statePath);
+    if (state) {
+        if (!state.auto.interrupt_reasons) {
+            state.auto.interrupt_reasons = [];
+        }
+        state.auto.interrupt_reasons = [...state.auto.interrupt_reasons, ...reasons];
+        (0, state_js_1.writeState)(statePath, state);
+    }
+    // Step 2: Render checkpoint box
+    const box = (0, render_js_1.renderCheckpoint)('Auto Mode Interrupted', 'Pipeline cannot continue automatically. Resolve:', reasons.map(r => r.length > 50 ? r.slice(0, 47) + '...' : r), 'Resolve issues above, then re-run /gswd:start');
+    console.log(box);
+    // Step 3: Return result
+    return {
+        status: 'interrupted',
+        stagesCompleted: [...stagesCompleted],
+        artifactsWritten: [...allArtifacts],
+        autoDecisions: [...allAutoDecisions],
+        interruptReasons: [...reasons],
+        autoFixCycles,
+    };
+}
+// ─── Auto Decision Summary ───────────────────────────────────────────────────
+/**
+ * Render a human-readable summary of auto-mode decisions.
+ * Returns empty string if no decisions.
+ */
+function renderAutoDecisionSummary(decisions) {
+    if (decisions.length === 0)
+        return '';
+    const lines = ['Auto-mode decisions:'];
+    for (const d of decisions) {
+        lines.push(`  \u26A1 ${d.type}: ${d.chosen}`);
+        lines.push(`     Why: ${d.rationale}`);
+        lines.push(`     Recorded in: DECISIONS.md + STATE.json auto.decisions[]`);
+    }
+    return lines.join('\n');
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Try to read a file, returning undefined if it doesn't exist.
+ */
+function tryReadFile(filePath) {
+    try {
+        return fs.readFileSync(filePath, 'utf-8');
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Derive a project slug from an idea file path or a fallback.
+ */
+function deriveProjectSlug(input) {
+    const base = path.basename(input, path.extname(input));
+    return base.replace(/[^a-z0-9-]/gi, '-').toLowerCase() || 'project';
+}
+// ─── Bootstrap Orchestrator ──────────────────────────────────────────────────
+/**
+ * Run the full bootstrap pipeline: init -> imagine -> specify -> audit -> compile.
+ *
+ * Implements GSWD_SPEC Section 8.1:
+ * - Auto mode threads autoMode/auto/autoFix to each stage
+ * - Resume mode skips completed stages with valid artifacts
+ * - Policy checks fire after imagine and after specify
+ * - Audit FAIL blocks compile (BOOT-03)
+ * - Auto-fix enabled with max 2 cycles when policy allows (BOOT-04)
+ * - state.stage = 'done' after successful compile (Pitfall 8)
+ *
+ * IMPORTANT: runImagine() and runSpecify() are ASYNC — use await.
+ *            runAuditWorkflow() and runCompileWorkflow() are SYNC — no await.
+ */
+async function runBootstrap(options) {
+    const planningDir = options.planningDir ?? path.join(process.cwd(), '.planning');
+    const gswdDir = path.join(planningDir, 'gswd');
+    const statePath = path.join(gswdDir, 'STATE.json');
+    const configPath = options.configPath ?? path.join(planningDir, 'config.json');
+    const stagesCompleted = [];
+    const allArtifacts = [];
+    let allAutoDecisions = [];
+    let autoFixCycles = 0;
+    // Early validation: auto mode requires @idea.md
+    if (options.auto && !options.ideaFilePath) {
+        return {
+            status: 'failed',
+            stagesCompleted,
+            artifactsWritten: allArtifacts,
+            autoDecisions: allAutoDecisions,
+            interruptReasons: [],
+            autoFixCycles,
+            error: 'Auto mode requires @idea.md — provide a file describing your idea',
+        };
+    }
+    // Step 1: Ensure STATE.json exists
+    if (!fs.existsSync(statePath)) {
+        fs.mkdirSync(gswdDir, { recursive: true });
+        (0, state_js_1.initState)(gswdDir, deriveProjectSlug(options.ideaFilePath ?? planningDir));
+    }
+    // Step 2: Load config
+    const config = (0, config_js_1.getGswdConfig)(configPath);
+    if (options.policy) {
+        config.auto.policy = options.policy;
+    }
+    // Step 3: Configure auto mode in state
+    const initStateObj = (0, state_js_1.readState)(statePath);
+    if (initStateObj) {
+        initStateObj.auto.enabled = options.auto;
+        initStateObj.auto.policy = config.auto.policy;
+        (0, state_js_1.writeState)(statePath, initStateObj);
+    }
+    console.log((0, render_js_1.renderBanner)('PIPELINE'));
+    // Extract product context for contextual banners
+    const productCtx = (0, render_js_1.extractProductContext)(planningDir);
+    // ── IMAGINE ──────────────────────────────────────────────────────────
+    const imagineState = (0, state_js_1.readState)(statePath);
+    if (!shouldSkipStage('imagine', imagineState, planningDir, options.resume ?? false)) {
+        (0, state_js_1.writeCheckpoint)(statePath, 'gswd/bootstrap', 'imagine-start');
+        const imagineCtxLine = render_js_1.STAGE_CONTEXT_TEMPLATES.imagine?.(productCtx) || '';
+        console.log((0, render_js_1.renderContextBanner)('IMAGINE', imagineCtxLine));
+        // runImagine is ASYNC — MUST await
+        const imagineResult = await (0, imagine_js_1.runImagine)({
+            ideaFilePath: options.ideaFilePath,
+            autoMode: options.auto,
+            skipResearch: options.skipResearch ?? false,
+            planningDir,
+            configPath,
+            spawnFn: options.spawnFn,
+        });
+        if (imagineResult.status !== 'complete') {
+            return {
+                status: 'failed',
+                stagesCompleted,
+                artifactsWritten: allArtifacts,
+                autoDecisions: allAutoDecisions,
+                interruptReasons: [],
+                autoFixCycles,
+                error: imagineResult.error ?? 'Imagine stage failed',
+            };
+        }
+        allArtifacts.push(...(imagineResult.artifacts_written ?? []));
+        if (imagineResult.auto_decisions) {
+            allAutoDecisions = [...allAutoDecisions, ...imagineResult.auto_decisions];
+        }
+        // Record auto decisions in STATE.json (AUTO-04)
+        if (options.auto && allAutoDecisions.length > 0) {
+            const stateAfterImagine = (0, state_js_1.readState)(statePath);
+            if (stateAfterImagine) {
+                stateAfterImagine.auto.decisions = allAutoDecisions;
+                (0, state_js_1.writeState)(statePath, stateAfterImagine);
+            }
+        }
+    }
+    stagesCompleted.push('imagine');
+    // Policy check after imagine (conflicting requirements check)
+    if (options.auto) {
+        const decisionsContent = tryReadFile(path.join(planningDir, 'DECISIONS.md'));
+        const check = checkPolicy({ config, decisionsContent });
+        if (check.shouldInterrupt) {
+            return handleInterrupt(check.reasons, statePath, stagesCompleted, allArtifacts, allAutoDecisions, autoFixCycles);
+        }
+    }
+    // ── SPECIFY ──────────────────────────────────────────────────────────
+    const specifyState = (0, state_js_1.readState)(statePath);
+    if (!shouldSkipStage('specify', specifyState, planningDir, options.resume ?? false)) {
+        (0, state_js_1.writeCheckpoint)(statePath, 'gswd/bootstrap', 'specify-start');
+        // Re-extract after imagine (DECISIONS.md now exists with precise data)
+        const specifyCtx = (0, render_js_1.extractProductContext)(planningDir);
+        const specifyCtxLine = render_js_1.STAGE_CONTEXT_TEMPLATES.specify?.(specifyCtx) || '';
+        console.log((0, render_js_1.renderContextBanner)('SPECIFY', specifyCtxLine));
+        // runSpecify is ASYNC — MUST await
+        // When no spawnFn provided, set skipAgents: true (Pitfall 1)
+        const specifyResult = await (0, specify_js_1.runSpecify)({
+            auto: options.auto,
+            skipAgents: !options.spawnFn,
+            planningDir,
+            configPath,
+            spawnFn: options.spawnFn,
+        });
+        if (specifyResult.status === 'failed') {
+            return {
+                status: 'failed',
+                stagesCompleted,
+                artifactsWritten: allArtifacts,
+                autoDecisions: allAutoDecisions,
+                interruptReasons: [],
+                autoFixCycles,
+                error: (specifyResult.errors ?? []).join('; ') || 'Specify stage failed',
+            };
+        }
+        allArtifacts.push(...specifyResult.artifacts);
+    }
+    stagesCompleted.push('specify');
+    // Policy check after specify (check integrations, NFRs, decisions)
+    if (options.auto) {
+        const intContent = tryReadFile(path.join(planningDir, 'INTEGRATIONS.md'));
+        const nfrContent = tryReadFile(path.join(planningDir, 'NFR.md'));
+        const decisionsContent = tryReadFile(path.join(planningDir, 'DECISIONS.md'));
+        const check = checkPolicy({ config, integrationsContent: intContent, nfrContent, decisionsContent });
+        if (check.shouldInterrupt) {
+            return handleInterrupt(check.reasons, statePath, stagesCompleted, allArtifacts, allAutoDecisions, autoFixCycles);
+        }
+    }
+    // ── AUDIT ────────────────────────────────────────────────────────────
+    const auditState = (0, state_js_1.readState)(statePath);
+    if (!shouldSkipStage('audit', auditState, planningDir, options.resume ?? false)) {
+        (0, state_js_1.writeCheckpoint)(statePath, 'gswd/bootstrap', 'audit-start');
+        const auditCtx = (0, render_js_1.extractProductContext)(planningDir);
+        const auditCtxLine = render_js_1.STAGE_CONTEXT_TEMPLATES.audit?.(auditCtx) || '';
+        console.log((0, render_js_1.renderContextBanner)('AUDIT', auditCtxLine));
+        // runAuditWorkflow is SYNC — no await (Pitfall 7)
+        const auditResult = (0, audit_js_1.runAuditWorkflow)({
+            planningDir,
+            statePath,
+            autoFix: options.auto && config.auto.policy !== 'strict',
+            maxCycles: 2,
+        });
+        autoFixCycles = auditResult.autoFixCycles;
+        if (!auditResult.passed) {
+            // BOOT-03: Cannot finish if audit is FAIL
+            return {
+                status: 'failed',
+                stagesCompleted,
+                artifactsWritten: allArtifacts,
+                autoDecisions: allAutoDecisions,
+                interruptReasons: [],
+                autoFixCycles,
+                error: 'Audit FAIL — cannot compile',
+            };
+        }
+    }
+    stagesCompleted.push('audit');
+    // ── COMPILE ──────────────────────────────────────────────────────────
+    const compileState = (0, state_js_1.readState)(statePath);
+    if (!shouldSkipStage('compile', compileState, planningDir, options.resume ?? false)) {
+        (0, state_js_1.writeCheckpoint)(statePath, 'gswd/bootstrap', 'compile-start');
+        console.log((0, render_js_1.renderBanner)('COMPILE'));
+        // runCompileWorkflow is SYNC — no await (Pitfall 7)
+        const compileResult = (0, compile_js_1.runCompileWorkflow)({
+            planningDir,
+            statePath,
+        });
+        if (!compileResult.passed) {
+            return {
+                status: 'failed',
+                stagesCompleted,
+                artifactsWritten: allArtifacts,
+                autoDecisions: allAutoDecisions,
+                interruptReasons: [],
+                autoFixCycles,
+                error: compileResult.error ?? 'Compile validator failed',
+            };
+        }
+        allArtifacts.push(...compileResult.filesWritten);
+    }
+    stagesCompleted.push('compile');
+    // Step final: Set stage = 'done' (Pitfall 8 — ONLY place 'done' is written)
+    const doneState = (0, state_js_1.readState)(statePath);
+    doneState.stage = 'done';
+    (0, state_js_1.writeState)(statePath, doneState);
+    (0, state_js_1.writeCheckpoint)(statePath, 'gswd/bootstrap', 'bootstrap-done');
+    // Auto decision summary (AUTO-06)
+    if (options.auto && allAutoDecisions.length > 0) {
+        console.log(renderAutoDecisionSummary(allAutoDecisions));
+    }
+    // Display dynamic file inventory (matches manual mode output)
+    const inventoryFiles = [
+        { path: '.planning/IMAGINE.md', description: 'Product vision, target user, and direction' },
+        { path: '.planning/DECISIONS.md', description: 'Frozen decisions, success metrics, risks' },
+        { path: '.planning/SPEC.md', description: 'Functional requirements with acceptance criteria' },
+        { path: '.planning/NFR.md', description: 'Non-functional requirements with thresholds' },
+        { path: '.planning/JOURNEYS.md', description: 'User journeys with FR and integration linkages' },
+        { path: '.planning/INTEGRATIONS.md', description: 'External integrations with status and fallbacks' },
+        { path: '.planning/PROJECT.md', description: 'GSD project context (compiled)' },
+        { path: '.planning/REQUIREMENTS.md', description: 'GSD requirements with traceability (compiled)' },
+        { path: '.planning/ROADMAP.md', description: 'GSD roadmap with phased journeys (compiled)' },
+        { path: '.planning/STATE.md', description: 'GSD project state and decisions (compiled)' },
+        { path: '.planning/research/gswd/SUMMARY.md', description: 'GSD-format research bridge (compiled)' },
+    ].filter(f => {
+        try {
+            fs.accessSync(path.join(process.cwd(), f.path));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    console.log((0, render_js_1.renderFileInventory)(inventoryFiles));
+    console.log('\nNext up:\n  /gsd:plan-phase 01\n\nTip:\n  If context is getting crowded, run /clear first.');
+    return {
+        status: 'done',
+        stagesCompleted,
+        artifactsWritten: allArtifacts,
+        autoDecisions: allAutoDecisions,
+        interruptReasons: [],
+        autoFixCycles,
+    };
+}