gswd 1.0.0 → 1.1.0

package/dist/lib/specify.js

@@ -0,0 +1,676 @@
+"use strict";
+/**
+ * GSWD Specify Workflow Orchestrator
+ *
+ * Full pipeline: roles checkpoint -> journey mapping -> FR extraction ->
+ * NFR generation -> architecture + integrations -> write artifacts -> state
+ * Implements GSWD_SPEC Section 8.3 end-to-end.
+ *
+ * Both interactive and auto modes are supported:
+ * - Interactive: presents checkpoints for roles, journey review, FR confirmation
+ * - Auto: uses defaults, skips reviews, auto-defers paid integrations
+ *
+ * Schema: GSWD_SPEC.md Section 8.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.runSpecify = runSpecify;
+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 parse_js_1 = require("./parse.js");
+const specify_roles_js_1 = require("./specify-roles.js");
+const specify_journeys_js_1 = require("./specify-journeys.js");
+const specify_nfr_js_1 = require("./specify-nfr.js");
+const specify_agents_js_1 = require("./specify-agents.js");
+// ─── Default Journey Content (for auto/skipAgents mode) ─────────────────────
+/**
+ * Build default journeys from DECISIONS.md context.
+ * Used when skipAgents=true or as fallback.
+ */
+function buildDefaultJourneys(decisionsContent) {
+    const journeys = [];
+    let counter = 1;
+    // Onboarding journey
+    const onboarding = (0, specify_journeys_js_1.generateJourneyStructure)('onboarding', counter++);
+    onboarding.name = 'New User Onboarding';
+    onboarding.preconditions = ['User has not previously used the application'];
+    onboarding.steps = [
+        { number: 1, action: 'User navigates to application landing page', frIds: [] },
+        { number: 2, action: 'User clicks sign up / get started button', frIds: [] },
+        { number: 3, action: 'User provides account details', frIds: [] },
+        { number: 4, action: 'User confirms account creation', frIds: [] },
+        { number: 5, action: 'User completes onboarding walkthrough', frIds: [] },
+    ];
+    onboarding.success = 'User has an active account and sees the main dashboard';
+    onboarding.failureModes = [
+        { scenario: 'Invalid email format provided during sign up', handling: 'Show inline validation error, prevent form submission' },
+        { scenario: 'Network timeout during account creation', handling: 'Show retry button with "Connection lost" message' },
+    ];
+    onboarding.acceptanceTests = ['User can create an account and reach the dashboard within 3 steps after landing'];
+    journeys.push(onboarding);
+    // Core action journey
+    const coreAction = (0, specify_journeys_js_1.generateJourneyStructure)('core_action', counter++);
+    coreAction.name = 'Core Action';
+    coreAction.preconditions = ['User is authenticated', 'User has completed onboarding'];
+    coreAction.steps = [
+        { number: 1, action: 'User opens main dashboard', frIds: [] },
+        { number: 2, action: 'User clicks create new item button', frIds: [] },
+        { number: 3, action: 'User fills in required fields in creation form', frIds: [] },
+        { number: 4, action: 'User reviews item details before submission', frIds: [] },
+        { number: 5, action: 'User submits the new item', frIds: [] },
+        { number: 6, action: 'User sees confirmation and item appears in list', frIds: [] },
+    ];
+    coreAction.success = 'New item is created and visible in the user list';
+    coreAction.failureModes = [
+        { scenario: 'Required fields left empty on submission', handling: 'Highlight missing fields with error messages' },
+        { scenario: 'Server error during item creation', handling: 'Show error toast, preserve form data for retry' },
+    ];
+    coreAction.acceptanceTests = ['User can create a new item and see it in the list immediately after creation'];
+    journeys.push(coreAction);
+    // View results journey
+    const viewResults = (0, specify_journeys_js_1.generateJourneyStructure)('view_results', counter++);
+    viewResults.name = 'View Results and History';
+    viewResults.preconditions = ['User is authenticated', 'User has created at least one item'];
+    viewResults.steps = [
+        { number: 1, action: 'User navigates to history or results view', frIds: [] },
+        { number: 2, action: 'User sees list of previously created items', frIds: [] },
+        { number: 3, action: 'User clicks on a specific item to view details', frIds: [] },
+        { number: 4, action: 'User reviews item details and status', frIds: [] },
+        { number: 5, action: 'User returns to the list view', frIds: [] },
+    ];
+    viewResults.success = 'User can browse and view details of all their items';
+    viewResults.failureModes = [
+        { scenario: 'Item details fail to load', handling: 'Show error state with retry option' },
+        { scenario: 'List takes too long to load', handling: 'Show skeleton loading state, load in batches' },
+    ];
+    viewResults.acceptanceTests = ['User can view a list of items and navigate to any item detail page'];
+    journeys.push(viewResults);
+    // Settings journey
+    const settings = (0, specify_journeys_js_1.generateJourneyStructure)('settings', counter++);
+    settings.name = 'Settings and Preferences';
+    settings.preconditions = ['User is authenticated'];
+    settings.steps = [
+        { number: 1, action: 'User navigates to settings page', frIds: [] },
+        { number: 2, action: 'User views current account settings', frIds: [] },
+        { number: 3, action: 'User modifies a setting value', frIds: [] },
+        { number: 4, action: 'User saves updated settings', frIds: [] },
+        { number: 5, action: 'User sees confirmation of saved changes', frIds: [] },
+    ];
+    settings.success = 'User settings are updated and persisted';
+    settings.failureModes = [
+        { scenario: 'Settings save fails due to validation error', handling: 'Show specific validation error next to the field' },
+        { scenario: 'Network error during save', handling: 'Show error toast, keep unsaved changes in form' },
+    ];
+    settings.acceptanceTests = ['User can modify settings and see them persisted after page reload'];
+    journeys.push(settings);
+    // Error states journey
+    const errorStates = (0, specify_journeys_js_1.generateJourneyStructure)('error_states', counter++);
+    errorStates.name = 'Error States';
+    errorStates.preconditions = ['User is authenticated'];
+    errorStates.steps = [
+        { number: 1, action: 'User performs an action that triggers an error', frIds: [] },
+        { number: 2, action: 'System displays contextual error message', frIds: [] },
+        { number: 3, action: 'User follows recovery action suggested in error message', frIds: [] },
+    ];
+    errorStates.success = 'User understands the error and can recover or retry';
+    errorStates.failureModes = [
+        { scenario: 'Error message is too vague to act on', handling: 'Include specific error code and link to help' },
+        { scenario: 'Recovery action fails repeatedly', handling: 'Escalate to support contact with error context attached' },
+    ];
+    errorStates.acceptanceTests = ['Every error state shows a message with a clear recovery action'];
+    journeys.push(errorStates);
+    // Empty states journey
+    const emptyStates = (0, specify_journeys_js_1.generateJourneyStructure)('empty_states', counter++);
+    emptyStates.name = 'Empty States';
+    emptyStates.preconditions = ['User is authenticated', 'User has no items yet'];
+    emptyStates.steps = [
+        { number: 1, action: 'User navigates to a section with no content', frIds: [] },
+        { number: 2, action: 'System shows empty state with call-to-action', frIds: [] },
+        { number: 3, action: 'User clicks the call-to-action to create first item', frIds: [] },
+    ];
+    emptyStates.success = 'User is guided from empty state to creating their first item';
+    emptyStates.failureModes = [
+        { scenario: 'Call-to-action button not visible on small screens', handling: 'Make CTA responsive and always visible' },
+        { scenario: 'Empty state appears even when items exist', handling: 'Show loading indicator before checking data' },
+    ];
+    emptyStates.acceptanceTests = ['Empty state shows a clear call-to-action that leads to item creation'];
+    journeys.push(emptyStates);
+    return journeys;
+}
+// ─── Artifact Formatting ────────────────────────────────────────────────────
+/**
+ * Format journeys for JOURNEYS.md content.
+ */
+function formatJourneysContent(journeys) {
+    return journeys.map((j) => {
+        const stepsContent = j.steps
+            .map((s) => `${s.number}. ${s.action}`)
+            .join('\n');
+        const fmContent = j.failureModes
+            .map((fm) => `- **${fm.scenario}:** ${fm.handling}`)
+            .join('\n');
+        const atContent = j.acceptanceTests
+            .map((at) => `- ${at}`)
+            .join('\n');
+        const frRefs = j.linkedFRs.length > 0 ? j.linkedFRs.join(', ') : 'None yet';
+        const nfrRefs = j.linkedNFRs.length > 0 ? j.linkedNFRs.join(', ') : 'None yet';
+        return `### ${j.id}: ${j.name}
+
+**Type:** ${j.type}
+
+**Preconditions:**
+${j.preconditions.map((p) => `- ${p}`).join('\n')}
+
+**Steps:**
+${stepsContent}
+
+**Success:** ${j.success}
+
+**Failure Modes:**
+${fmContent}
+
+**Acceptance Tests:**
+${atContent}
+
+**Linked FRs:** ${frRefs}
+**Linked NFRs:** ${nfrRefs}`;
+    }).join('\n\n---\n\n');
+}
+/**
+ * Format FRs for SPEC.md content.
+ */
+function formatFRsContent(frs) {
+    return frs.map((fr) => {
+        const journeyRefs = fr.sourceSteps.join(', ');
+        return `### ${fr.id}: ${fr.description}
+**Scope:** ${fr.scope}
+**Priority:** ${fr.priority}
+**Source:** ${journeyRefs}`;
+    }).join('\n\n');
+}
+/**
+ * Format acceptance criteria from journeys for SPEC.md.
+ */
+function formatAcceptanceCriteria(journeys) {
+    const criteria = [];
+    for (const j of journeys) {
+        for (const at of j.acceptanceTests) {
+            criteria.push(`- **${j.id}:** ${at}`);
+        }
+    }
+    return criteria.join('\n');
+}
+/**
+ * Format traceability table for SPEC.md.
+ */
+function formatTraceabilityTable(frs) {
+    const map = (0, specify_journeys_js_1.buildTraceabilityMap)(frs);
+    const lines = [
+        '| FR | Description | Source Journeys |',
+        '|----|-------------|----------------|',
+    ];
+    for (const entry of map) {
+        lines.push(`| ${entry.frId} | ${entry.description} | ${entry.journeyRefs.join(', ')} |`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Format NFRs for NFR.md content, grouped by category.
+ */
+function formatNFRsContent(nfrs) {
+    const categories = ['security', 'privacy', 'performance', 'observability'];
+    return categories.map((cat) => {
+        const catNfrs = nfrs.filter((n) => n.category === cat);
+        const catContent = catNfrs.map((n) => {
+            const frRefs = n.linkedFRs.length > 0 ? n.linkedFRs.join(', ') : 'All';
+            return `#### ${n.id}: ${n.description}
+**Threshold:** ${n.threshold}
+**Linked FRs:** ${frRefs}`;
+        }).join('\n\n');
+        return `### ${cat.charAt(0).toUpperCase() + cat.slice(1)}\n\n${catContent}`;
+    }).join('\n\n');
+}
+/**
+ * Format default architecture content (used when skipAgents=true).
+ */
+function buildDefaultArchitectureContent(frs) {
+    const components = [];
+    components.push(`#### C-001: Application Core
+
+**Responsibility:** Handles main application logic and user workflows
+**Dependencies:** None
+**Linked FRs:** ${frs.filter(f => f.priority === 'P0').map(f => f.id).join(', ') || 'All P0 FRs'}`);
+    components.push(`#### C-002: Data Layer
+
+**Responsibility:** Manages data persistence and retrieval
+**Dependencies:** C-001
+**Linked FRs:** ${frs.filter(f => f.scope === 'v1').map(f => f.id).slice(0, 5).join(', ') || 'All v1 FRs'}`);
+    components.push(`#### C-003: User Interface
+
+**Responsibility:** Renders views and handles user input
+**Dependencies:** C-001
+**Linked FRs:** ${frs.filter(f => f.scope === 'v1').map(f => f.id).slice(0, 5).join(', ') || 'All v1 FRs'}`);
+    const componentsContent = components.join('\n\n');
+    const dataModel = `#### Item
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | string | Primary key |
+| title | string | Required |
+| created_at | timestamp | Auto-set |
+| updated_at | timestamp | Auto-set |
+
+#### User
+
+| Field | Type | Notes |
+|-------|------|-------|
+| id | string | Primary key |
+| email | string | Unique |
+| created_at | timestamp | Auto-set |
+
+**Relationships:**
+- User has many Items
+- Item belongs to User`;
+    const ownership = `| Component | Owns | Operations |
+|-----------|------|------------|
+| C-001: Application Core | Business logic | Workflow orchestration |
+| C-002: Data Layer | Item, User entities | CRUD operations |
+| C-003: User Interface | Views, Forms | Render, Input handling |`;
+    return `${componentsContent}\n\n---\n\n${dataModel}\n\n---\n\n${ownership}`;
+}
+/**
+ * Format default integrations content (no external integrations for v1).
+ */
+function buildDefaultIntegrationsContent() {
+    return 'No external integrations required for v1 MVP. All functionality is self-contained.';
+}
+// ─── Template Injection ─────────────────────────────────────────────────────
+/**
+ * Inject content into a template at a GSWD:CONTENT marker.
+ */
+function injectContent(template, marker, content) {
+    const markerComment = `<!-- GSWD:CONTENT:${marker} -->`;
+    return template.replace(markerComment, content);
+}
+// ─── Main Workflow ──────────────────────────────────────────────────────────
+/**
+ * Run the Specify workflow end-to-end.
+ *
+ * Implements GSWD_SPEC Section 8.3:
+ * 1. Roles & Permissions checkpoint
+ * 2. Journey mapping
+ * 3. FR extraction
+ * 4. NFR generation
+ * 5. Architecture + Integrations (parallel agents)
+ * 6. Write 5 artifacts
+ * 7. Update state
+ */
+async function runSpecify(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 templatesDir = options.templatesDir || path.join(path.dirname(planningDir), 'templates', 'gswd');
+    const errors = [];
+    try {
+        // ── Step 1: Load state and config ──────────────────────────────────
+        const state = (0, state_js_1.readState)(statePath);
+        if (!state) {
+            return {
+                status: 'failed',
+                artifacts: [],
+                journeyCount: 0,
+                frCount: 0,
+                nfrCount: 0,
+                integrationCount: 0,
+                componentCount: 0,
+                errors: ['No STATE.json found. Run init first.'],
+            };
+        }
+        const config = (0, config_js_1.getGswdConfig)(configPath);
+        // Mark specify as in_progress
+        state.stage = 'specify';
+        state.stage_status.specify = 'in_progress';
+        (0, state_js_1.writeState)(statePath, state);
+        // Load DECISIONS.md
+        const decisionsPath = path.join(planningDir, 'DECISIONS.md');
+        let decisionsContent = '';
+        try {
+            decisionsContent = fs.readFileSync(decisionsPath, 'utf-8');
+        }
+        catch {
+            return {
+                status: 'failed',
+                artifacts: [],
+                journeyCount: 0,
+                frCount: 0,
+                nfrCount: 0,
+                integrationCount: 0,
+                componentCount: 0,
+                errors: ['DECISIONS.md not found. Run imagine stage first.'],
+            };
+        }
+        // Load IMAGINE.md (optional)
+        let imagineContent = '';
+        try {
+            imagineContent = fs.readFileSync(path.join(planningDir, 'IMAGINE.md'), 'utf-8');
+        }
+        catch {
+            // Optional — continue without it
+        }
+        // ── Step 2: Roles checkpoint ───────────────────────────────────────
+        const rolesConfig = await (0, specify_roles_js_1.collectRoles)({ auto: options.auto });
+        const rolesContent = (0, specify_roles_js_1.formatRolesForSpec)(rolesConfig);
+        // ── Step 3: Journey mapping ────────────────────────────────────────
+        let journeys;
+        if (options.providedJourneys) {
+            journeys = options.providedJourneys;
+        }
+        else if (options.skipAgents) {
+            journeys = buildDefaultJourneys(decisionsContent);
+        }
+        else {
+            // Use agent orchestration for journey-mapper
+            const agentContext = {
+                decisionsContent,
+                imagineContent,
+            };
+            const sequentialAgents = specify_agents_js_1.SPECIFY_AGENTS.filter((a) => a.phase === 'sequential');
+            const spawnFn = options.spawnFn;
+            if (spawnFn) {
+                // Allocate ID ranges for specify agents before spawning (FNDN-05)
+                if (options.spawnFn && !options.skipAgents) {
+                    try {
+                        (0, state_js_1.allocateIdRange)(statePath, 'J', 'journey-mapper', 50);
+                        (0, state_js_1.allocateIdRange)(statePath, 'FR', 'architecture-drafter', 50);
+                        (0, state_js_1.allocateIdRange)(statePath, 'NFR', 'architecture-drafter', 50);
+                        (0, state_js_1.allocateIdRange)(statePath, 'I', 'integrations-checker', 50);
+                        (0, state_js_1.allocateIdRange)(statePath, 'C', 'architecture-drafter', 50);
+                    }
+                    catch {
+                        // Non-fatal — ID allocation failure should not block specify
+                        errors.push('Warning: ID range allocation failed');
+                    }
+                }
+                const jmResults = await (0, specify_agents_js_1.orchestrateSpecifyAgents)(sequentialAgents, agentContext, spawnFn);
+                const jmResult = jmResults.find((r) => r.agent === 'journey-mapper');
+                if (jmResult && jmResult.status === 'complete' && jmResult.content.trim()) {
+                    // Use agent's raw journey content for template injection
+                    // Store raw content for JOURNEYS.md, but still need Journey[] for FR extraction
+                    journeys = buildDefaultJourneys(decisionsContent);
+                    // Override: if agent content contains J-XXX patterns, use it as journeys source
+                    const jPattern = /###\s+J-\d{3}/;
+                    if (jPattern.test(jmResult.content)) {
+                        // Agent produced structured journey content — store for template injection
+                        options._agentJourneyContent = jmResult.content;
+                    }
+                }
+                else {
+                    // Fallback to default journeys
+                    journeys = buildDefaultJourneys(decisionsContent);
+                    errors.push('Journey mapper agent failed, using default journeys');
+                }
+            }
+            else {
+                journeys = buildDefaultJourneys(decisionsContent);
+            }
+        }
+        // Mid-stage checkpoint: journeys complete (RESM-02)
+        (0, state_js_1.writeCheckpoint)(statePath, 'gswd/specify', 'journeys-complete');
+        // Validate journeys
+        for (const journey of journeys) {
+            const validation = (0, specify_journeys_js_1.validateJourney)(journey);
+            if (!validation.valid) {
+                errors.push(...validation.errors);
+            }
+        }
+        // ── Step 4: FR extraction ──────────────────────────────────────────
+        const frs = (0, specify_journeys_js_1.extractFRsFromJourneys)(journeys);
+        // Validate FR coverage
+        const coverageResult = (0, specify_journeys_js_1.validateFRCoverage)(journeys, frs);
+        if (!coverageResult.valid) {
+            errors.push(...coverageResult.errors);
+        }
+        // Mid-stage checkpoint: FRs complete (RESM-02)
+        (0, state_js_1.writeCheckpoint)(statePath, 'gswd/specify', 'frs-complete');
+        // ── Step 5: NFR generation ─────────────────────────────────────────
+        const nfrs = (0, specify_nfr_js_1.generateNFRs)(frs, decisionsContent);
+        // Validate NFRs
+        const nfrValidation = (0, specify_nfr_js_1.validateNFRs)(nfrs);
+        if (!nfrValidation.valid) {
+            errors.push(...nfrValidation.errors);
+        }
+        // ── Step 6: Architecture + Integrations ────────────────────────────
+        let architectureContent;
+        let integrationsContent = buildDefaultIntegrationsContent();
+        if (options.providedArchitecture) {
+            architectureContent = options.providedArchitecture;
+        }
+        else if (options.skipAgents) {
+            architectureContent = buildDefaultArchitectureContent(frs);
+        }
+        else if (options.spawnFn) {
+            // Run parallel agents
+            const agentContext = {
+                decisionsContent,
+                imagineContent,
+                journeys,
+                frs,
+                autoPolicy: JSON.stringify(config.auto),
+            };
+            const parallelAgents = specify_agents_js_1.SPECIFY_AGENTS.filter((a) => a.phase === 'parallel');
+            const parallelResults = await (0, specify_agents_js_1.orchestrateSpecifyAgents)(parallelAgents, agentContext, options.spawnFn);
+            const archResult = parallelResults.find((r) => r.agent === 'architecture-drafter');
+            architectureContent = archResult && archResult.status === 'complete'
+                ? archResult.content
+                : buildDefaultArchitectureContent(frs);
+            const intResult = parallelResults.find((r) => r.agent === 'integrations-checker');
+            integrationsContent = intResult && intResult.status === 'complete'
+                ? intResult.content
+                : buildDefaultIntegrationsContent();
+        }
+        else {
+            architectureContent = buildDefaultArchitectureContent(frs);
+            integrationsContent = buildDefaultIntegrationsContent();
+        }
+        if (!options.providedIntegrations && !integrationsContent) {
+            integrationsContent = buildDefaultIntegrationsContent();
+        }
+        if (options.providedIntegrations) {
+            integrationsContent = options.providedIntegrations;
+        }
+        // ── Step 6b: Validate integrations and components ──────────────────
+        // Extract I-XXX IDs from integrationsContent; for each found, validate
+        const integrationIdPattern = /###\s+(I-\d{3}):\s*(.+)/g;
+        let iMatch;
+        while ((iMatch = integrationIdPattern.exec(integrationsContent)) !== null) {
+            const integrationData = {
+                id: iMatch[1],
+                name: iMatch[2].trim(),
+                setupSteps: [],
+                authMethod: '',
+                costQuota: '',
+                fallback: '',
+                status: 'approved', // default — will be overridden by actual status parsing
+            };
+            // Try to extract actual status from content following the ID
+            const statusMatch = integrationsContent
+                .slice(iMatch.index)
+                .match(/\*\*Status:\*\*\s*(approved|deferred[^\n]*|rejected)/i);
+            if (statusMatch) {
+                integrationData.status = statusMatch[1].toLowerCase().startsWith('approved')
+                    ? 'approved'
+                    : statusMatch[1].toLowerCase().startsWith('rejected')
+                        ? 'rejected'
+                        : 'deferred with fallback';
+            }
+            // Try to extract fallback from content following the ID
+            const fallbackMatch = integrationsContent
+                .slice(iMatch.index)
+                .match(/\*\*Fallback:\*\*\s*(.+)/i);
+            if (fallbackMatch) {
+                integrationData.fallback = fallbackMatch[1].trim();
+            }
+            const intValidation = (0, specify_agents_js_1.validateIntegration)(integrationData);
+            if (!intValidation.valid) {
+                errors.push(...intValidation.errors);
+            }
+        }
+        // Validate architecture components — parse C-XXX IDs from architectureContent
+        const componentIdPattern = /###\s+(C-\d{3}):\s*(.+)/g;
+        let cMatch;
+        while ((cMatch = componentIdPattern.exec(architectureContent)) !== null) {
+            const componentData = {
+                id: cMatch[1],
+                name: cMatch[2].trim(),
+                responsibility: '',
+                dependencies: [],
+                linkedFRs: [],
+            };
+            // Extract responsibility
+            const respMatch = architectureContent
+                .slice(cMatch.index)
+                .match(/\*\*Responsibility:\*\*\s*(.+)/i);
+            if (respMatch) {
+                componentData.responsibility = respMatch[1].trim();
+            }
+            const compValidation = (0, specify_agents_js_1.validateComponent)(componentData);
+            if (!compValidation.valid) {
+                errors.push(...compValidation.errors);
+            }
+        }
+        // ── Step 7: Build and write artifacts ──────────────────────────────
+        // Load templates
+        const specTemplate = loadTemplate(templatesDir, 'SPEC.template.md');
+        const journeysTemplate = loadTemplate(templatesDir, 'JOURNEYS.template.md');
+        const nfrTemplate = loadTemplate(templatesDir, 'NFR.template.md');
+        const archTemplate = loadTemplate(templatesDir, 'ARCHITECTURE.template.md');
+        const intTemplate = loadTemplate(templatesDir, 'INTEGRATIONS.template.md');
+        // Build artifact content by injecting into templates
+        let specContent = specTemplate;
+        specContent = injectContent(specContent, 'ROLES', rolesContent);
+        specContent = injectContent(specContent, 'FRS', formatFRsContent(frs));
+        specContent = injectContent(specContent, 'ACCEPTANCE', formatAcceptanceCriteria(journeys));
+        specContent = injectContent(specContent, 'TRACEABILITY', formatTraceabilityTable(frs));
+        let journeysContent = journeysTemplate;
+        const agentJourneyContent = options._agentJourneyContent;
+        if (agentJourneyContent) {
+            journeysContent = injectContent(journeysContent, 'JOURNEYS', agentJourneyContent);
+        }
+        else {
+            journeysContent = injectContent(journeysContent, 'JOURNEYS', formatJourneysContent(journeys));
+        }
+        let nfrContent = nfrTemplate;
+        nfrContent = injectContent(nfrContent, 'NFRS', formatNFRsContent(nfrs));
+        // For architecture — parse components/data model/ownership from agent content or defaults
+        let archContent = archTemplate;
+        archContent = injectContent(archContent, 'COMPONENTS', architectureContent.split('---')[0]?.trim() || architectureContent);
+        archContent = injectContent(archContent, 'DATA_MODEL', architectureContent.split('---')[1]?.trim() || '');
+        archContent = injectContent(archContent, 'OWNERSHIP', architectureContent.split('---')[2]?.trim() || '');
+        let intContent = intTemplate;
+        intContent = injectContent(intContent, 'INTEGRATIONS', integrationsContent);
+        // Write all 5 artifacts
+        const artifacts = [
+            { name: 'SPEC.md', content: specContent, fileType: 'SPEC.md' },
+            { name: 'JOURNEYS.md', content: journeysContent, fileType: 'JOURNEYS.md' },
+            { name: 'NFR.md', content: nfrContent, fileType: 'NFR.md' },
+            { name: 'ARCHITECTURE.md', content: archContent, fileType: 'ARCHITECTURE.md' },
+            { name: 'INTEGRATIONS.md', content: intContent, fileType: 'INTEGRATIONS.md' },
+        ];
+        const artifactsWritten = [];
+        for (const artifact of artifacts) {
+            const artifactPath = path.join(planningDir, artifact.name);
+            (0, state_js_1.safeWriteFile)(artifactPath, artifact.content);
+            artifactsWritten.push(artifactPath);
+            // Validate headings
+            const headingValidation = (0, parse_js_1.validateHeadings)(artifact.content, artifact.fileType);
+            if (!headingValidation.valid) {
+                errors.push(`${artifact.name} missing headings: ${headingValidation.missing.join(', ')}`);
+            }
+        }
+        // ── Step 8: Update state ───────────────────────────────────────────
+        const finalState = (0, state_js_1.readState)(statePath);
+        if (finalState) {
+            finalState.stage_status.specify = 'done';
+            finalState.stage = 'specify';
+            finalState.last_checkpoint = {
+                workflow: 'gswd/specify',
+                checkpoint_id: 'complete',
+                timestamp: new Date().toISOString(),
+            };
+            (0, state_js_1.writeState)(statePath, finalState);
+        }
+        // ── Step 9: Return result ──────────────────────────────────────────
+        return {
+            status: errors.length > 0 ? 'complete' : 'complete', // Non-fatal errors don't block
+            artifacts: artifactsWritten,
+            journeyCount: journeys.length,
+            frCount: frs.length,
+            nfrCount: nfrs.length,
+            integrationCount: 0, // Would be populated from parsed integrations
+            componentCount: 3, // Default component count
+            errors: errors.length > 0 ? errors : undefined,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            status: 'failed',
+            artifacts: [],
+            journeyCount: 0,
+            frCount: 0,
+            nfrCount: 0,
+            integrationCount: 0,
+            componentCount: 0,
+            errors: [message],
+        };
+    }
+}
+// ─── Helpers ────────────────────────────────────────────────────────────────
+/**
+ * Load a template file. Returns a minimal template if not found.
+ */
+function loadTemplate(templatesDir, filename) {
+    try {
+        return fs.readFileSync(path.join(templatesDir, filename), 'utf-8');
+    }
+    catch {
+        // Fallback: return a minimal template
+        const name = filename.replace('.template.md', '');
+        return `# ${name}\n\n<!-- GSWD:COMPLETE -->\n`;
+    }
+}