gswd 0.1.0

package/lib/imagine.ts

@@ -0,0 +1,433 @@
+/**
+ * GSWD Imagine Workflow Orchestrator
+ *
+ * Full pipeline: input -> agents -> synthesis -> gate -> artifacts -> state
+ * Implements GSWD_SPEC Section 8.2 end-to-end.
+ *
+ * Both interactive and auto modes are supported:
+ * - Interactive: presents direction checkpoint, awaits selection
+ * - Auto: scores directions via pain x WTP x reachability, selects highest
+ *
+ * Schema: GSWD_SPEC.md Section 8.2
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { safeWriteFile, readState, writeState, writeCheckpoint, allocateIdRange } from './state.js';
+import { getGswdConfig } from './config.js';
+import { parseIdeaFile, buildFromIntake, validateBrief } from './imagine-input.js';
+import type { StarterBrief, IntakeAnswers } from './imagine-input.js';
+import { IMAGINE_AGENTS, orchestrateAgents } from './imagine-agents.js';
+import type { AgentResult, SpawnFn } from './imagine-agents.js';
+import { synthesizeDirections, autoSelectDirection, scoreIcpOptions } from './imagine-synthesis.js';
+import type { Direction, AutoDecision, SynthesisResult } from './imagine-synthesis.js';
+import { validateDecisionGate } from './imagine-gate.js';
+import type { GateResult } from './imagine-gate.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface ImagineOptions {
+  ideaFilePath?: string;       // Path to @idea.md (optional)
+  intakeAnswers?: IntakeAnswers; // 3-question answers (optional)
+  autoMode?: boolean;          // Use auto policy for decisions
+  skipResearch?: boolean;      // Skip agent spawning
+  planningDir?: string;        // Override .planning/ path (for testing)
+  configPath?: string;         // Override config.json path (for testing)
+  spawnFn?: SpawnFn;           // Task() wrapper (injectable for testing)
+  selectedDirectionIndex?: number; // Manual direction selection (0-based)
+}
+
+export interface ImagineResult {
+  status: 'complete' | 'gate_failed' | 'error';
+  artifacts_written: string[];
+  gate_result?: GateResult;
+  auto_decisions?: AutoDecision[];
+  selected_direction?: Direction;
+  error?: string;
+}
+
+// ─── Artifact Building ──────────────────────────────────────────────────────
+
+/**
+ * Build IMAGINE.md content from selected direction and synthesis data.
+ */
+function buildImagineContent(
+  brief: StarterBrief,
+  selected: Direction,
+  synthesis: SynthesisResult,
+  autoDecisions?: AutoDecision[],
+): string {
+  const alternatives = synthesis.alternatives
+    .map((alt, i) => `### Alternative ${i + 1}: ${alt.label}\n- **ICP:** ${alt.icp_summary}\n- **Problem:** ${alt.problem_framing}\n- **Wedge:** ${alt.wedge}\n- **Differentiator:** ${alt.differentiator}`)
+    .join('\n\n');
+
+  const metrics = autoDecisions
+    ? autoDecisions.filter(d => d.type === 'metric').map(d => `- ${d.chosen}`).join('\n')
+    : '- To be defined during decision gate';
+
+  return `# Imagine
+
+## Vision
+${brief.vision}
+
+## Target User
+${brief.target_user}
+
+## Problem Statement
+${selected.problem_framing}
+
+## Product Direction
+### ${selected.label}
+- **ICP:** ${selected.icp_summary}
+- **Problem:** ${selected.problem_framing}
+- **Wedge:** ${selected.wedge}
+- **Differentiator:** ${selected.differentiator}
+- **Risks:** ${selected.risks.join('; ')}
+
+## Alternatives
+${alternatives}
+
+## Wedge / MVP Boundary
+${selected.wedge}
+
+## Success Metrics
+${metrics}
+`;
+}
+
+/**
+ * Sanitize a value for use in a single-line markdown bullet.
+ * Collapses newlines, strips heading markers, and trims to prevent
+ * multi-line content from breaking section boundaries in DECISIONS.md.
+ */
+function sanitizeBulletValue(value: string): string {
+  return value
+    .replace(/\n+/g, ' ')       // collapse newlines to spaces
+    .replace(/#+\s*/g, '')       // strip markdown heading markers
+    .replace(/\s{2,}/g, ' ')    // collapse multiple spaces
+    .trim();
+}
+
+/**
+ * Build DECISIONS.md content from selected direction, auto decisions, and risks.
+ */
+function buildDecisionsContent(
+  selected: Direction,
+  synthesis: SynthesisResult,
+  brief: StarterBrief,
+  autoDecisions?: AutoDecision[],
+): string {
+  // Build frozen decisions (need >= 8)
+  // Sanitize all interpolated values to prevent multi-line content from breaking section structure
+  const decisionPrefix = autoDecisions ? 'Auto-chosen: ' : '';
+  const frozenDecisions = [
+    `- ${decisionPrefix}**ICP:** ${sanitizeBulletValue(selected.icp_summary)}`,
+    `- ${decisionPrefix}**Problem Statement:** ${sanitizeBulletValue(selected.problem_framing)}`,
+    `- ${decisionPrefix}**Product Direction:** ${sanitizeBulletValue(selected.label)}`,
+    `- ${decisionPrefix}**Wedge / Entry Point:** ${sanitizeBulletValue(selected.wedge)}`,
+    `- ${decisionPrefix}**Differentiator:** ${sanitizeBulletValue(selected.differentiator)}`,
+    `- ${decisionPrefix}**Target User:** ${sanitizeBulletValue(brief.target_user)}`,
+    `- ${decisionPrefix}**Timing Rationale:** ${sanitizeBulletValue(brief.why_now)}`,
+    `- ${decisionPrefix}**MVP Boundary:** ${sanitizeBulletValue(selected.wedge)} (full product expansion deferred to post-validation)`,
+  ];
+
+  // Success metrics
+  const metricDecision = autoDecisions?.find(d => d.type === 'metric');
+  const metricsItems = metricDecision
+    ? metricDecision.chosen.split(',').map(m => `- ${m.trim()}`)
+    : ['- Activation rate', '- Week-1 retention'];
+
+  // Out of scope
+  const outOfScope = [
+    '- Features beyond MVP wedge scope',
+    '- Paid integrations (unless pre-approved)',
+    '- Multi-user / team collaboration (v1 is single-user)',
+  ];
+
+  // Risks from devils-advocate agent and direction risks
+  const risksContent = synthesis.raw_agent_outputs['devils-advocate'] || '';
+  const riskLines = extractRiskItems(risksContent, selected.risks);
+
+  // Open questions
+  const openQuestions = synthesis.agent_warnings.length > 0
+    ? synthesis.agent_warnings.map(w => `- ${w}`)
+    : ['- None at this time'];
+
+  return `# Decisions
+
+## Frozen Decisions
+${frozenDecisions.join('\n')}
+
+## Success Metrics
+${metricsItems.join('\n')}
+
+## Out of Scope
+${outOfScope.join('\n')}
+
+## Risks & Mitigations
+${riskLines.join('\n')}
+
+## Open Questions
+${openQuestions.join('\n')}
+`;
+}
+
+/**
+ * Extract risk items from devils-advocate output, ensuring >= 5 items.
+ */
+function extractRiskItems(risksContent: string, directionRisks: string[]): string[] {
+  const items: string[] = [];
+
+  if (risksContent) {
+    // Extract from ## Risks section
+    const risksMatch = risksContent.match(/##\s*Risks\s*\n([\s\S]*?)(?=\n##|$)/);
+    if (risksMatch) {
+      const lines = risksMatch[1].split('\n')
+        .filter(l => l.trim().startsWith('-'))
+        .map(l => l.trim())
+        .slice(0, 8);
+      items.push(...lines);
+    }
+
+    // Extract from ## Mitigations section
+    const mitigationsMatch = risksContent.match(/##\s*Mitigations\s*\n([\s\S]*?)(?=\n##|$)/);
+    if (mitigationsMatch && items.length < 5) {
+      const lines = mitigationsMatch[1].split('\n')
+        .filter(l => l.trim().startsWith('-'))
+        .map(l => l.trim())
+        .slice(0, 5 - items.length);
+      items.push(...lines);
+    }
+  }
+
+  // Add direction risks if we need more
+  for (const risk of directionRisks) {
+    if (items.length >= 5) break;
+    items.push(`- **Direction risk:** ${risk}`);
+  }
+
+  // Ensure minimum 5
+  while (items.length < 5) {
+    items.push(`- Risk ${items.length + 1}: To be identified during Specify stage`);
+  }
+
+  return items;
+}
+
+/**
+ * Build artifact content from agent raw output, falling back to a message.
+ */
+function buildAgentArtifact(agentName: string, rawOutputs: Record<string, string>, fallback: string): string {
+  const content = rawOutputs[agentName];
+  return content || fallback;
+}
+
+// ─── Main Workflow ──────────────────────────────────────────────────────────
+
+/**
+ * Run the Imagine workflow end-to-end.
+ *
+ * Implements GSWD_SPEC Section 8.2 Steps 1-6:
+ * 1. Load state and config
+ * 2. Collect founder input (file or intake)
+ * 3. Spawn parallel agents
+ * 4. Synthesize into proposed direction + 2 alternatives
+ * 5. Decision gate (must freeze)
+ * 6. Write docs and update state
+ */
+export async function runImagine(options: ImagineOptions): Promise<ImagineResult> {
+  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');
+
+  try {
+    // ── Step 1: Load state and config ──────────────────────────────────
+    const state = readState(statePath);
+    if (!state) {
+      return { status: 'error', artifacts_written: [], error: 'No STATE.json found. Run init first.' };
+    }
+
+    const config = getGswdConfig(configPath);
+
+    // Mark imagine as in_progress
+    state.stage = 'imagine';
+    state.stage_status.imagine = 'in_progress';
+    writeState(statePath, state);
+
+    // ── Step 2: Collect input ──────────────────────────────────────────
+    let brief: StarterBrief;
+
+    if (options.ideaFilePath) {
+      brief = parseIdeaFile(options.ideaFilePath);
+    } else if (options.intakeAnswers) {
+      brief = buildFromIntake(options.intakeAnswers);
+    } else {
+      return {
+        status: 'error',
+        artifacts_written: [],
+        error: 'No input: provide ideaFilePath or intakeAnswers',
+      };
+    }
+
+    const validation = validateBrief(brief);
+    if (!validation.valid) {
+      return {
+        status: 'error',
+        artifacts_written: [],
+        error: `Invalid brief: missing fields [${validation.missing.join(', ')}]`,
+      };
+    }
+
+    // ── Step 3: Spawn agents ──────────────────────────────────────────
+    let agentResults: AgentResult[];
+
+    if (options.skipResearch) {
+      // Create minimal results from brief content
+      agentResults = IMAGINE_AGENTS.map(agent => ({
+        agent: agent.name,
+        content: `## ${agent.requiredHeadings[0]?.replace('## ', '') || 'Output'}\nGenerated from starter brief.\n\n${brief.vision}\n${brief.target_user}\n${brief.why_now}`,
+        status: 'complete' as const,
+        duration_ms: 0,
+      }));
+    } else {
+      const spawnFn = options.spawnFn;
+      if (!spawnFn) {
+        return {
+          status: 'error',
+          artifacts_written: [],
+          error: 'No spawnFn provided for agent orchestration',
+        };
+      }
+      // Allocate ID ranges for imagine agents before spawning (FNDN-05)
+      if (spawnFn) {
+        try {
+          allocateIdRange(statePath, 'J', 'journey-mapper', 50);
+          allocateIdRange(statePath, 'FR', 'market-researcher', 50);
+        } catch {
+          // Non-fatal — ID allocation failure should not block imagine
+        }
+      }
+      agentResults = await orchestrateAgents(
+        IMAGINE_AGENTS,
+        config.max_parallel_agents,
+        brief,
+        spawnFn,
+      );
+    }
+
+    // Mid-stage checkpoint: agents complete (RESM-02)
+    writeCheckpoint(statePath, 'gswd/imagine', 'agents-complete');
+
+    // ── Step 4: Synthesize directions ─────────────────────────────────
+    const synthesis = synthesizeDirections(agentResults);
+
+    // ── Step 5: Direction selection ───────────────────────────────────
+    let selected: Direction;
+    let autoDecisions: AutoDecision[] | undefined;
+
+    if (options.autoMode) {
+      const autoResult = autoSelectDirection(synthesis);
+      selected = autoResult.selected;
+      autoDecisions = autoResult.decisions;
+    } else if (options.selectedDirectionIndex !== undefined) {
+      const allDirections = [synthesis.proposed, ...synthesis.alternatives];
+      const idx = Math.max(0, Math.min(options.selectedDirectionIndex, allDirections.length - 1));
+      selected = allDirections[idx];
+    } else {
+      // Default to proposed direction
+      selected = synthesis.proposed;
+    }
+
+    // Mid-stage checkpoint: direction selected (RESM-02)
+    writeCheckpoint(statePath, 'gswd/imagine', 'direction-selected');
+
+    // ── Step 6: Build artifacts ──────────────────────────────────────
+    const imagineContent = buildImagineContent(brief, selected, synthesis, autoDecisions);
+    const decisionsContent = buildDecisionsContent(selected, synthesis, brief, autoDecisions);
+
+    const icpContent = buildAgentArtifact(
+      'icp-persona',
+      synthesis.raw_agent_outputs,
+      `# Ideal Customer Profile\n\n## ICP Profile\n${selected.icp_summary}\n\n## Pain Points\nDerived from direction analysis.\n`,
+    );
+
+    const gtmContent = buildAgentArtifact(
+      'positioning',
+      synthesis.raw_agent_outputs,
+      `# Go-to-Market\n\n## Value Proposition\n${selected.differentiator}\n\n## Go-to-Market Angle\nTo be defined in Specify stage.\n`,
+    );
+
+    const competitionContent = buildAgentArtifact(
+      'market-researcher',
+      synthesis.raw_agent_outputs,
+      `# Competition\n\n## Market Overview\nMarket research data unavailable.\n\n## Competitors\nTo be researched.\n`,
+    );
+
+    // ── Step 7: Validate decision gate ───────────────────────────────
+    const gateResult = validateDecisionGate(decisionsContent);
+
+    if (!gateResult.passed) {
+      // Do NOT update state to done
+      return {
+        status: 'gate_failed',
+        artifacts_written: [],
+        gate_result: gateResult,
+        selected_direction: selected,
+        error: `Decision gate failed: ${gateResult.summary}`,
+      };
+    }
+
+    // ── Step 8: Write artifacts ──────────────────────────────────────
+    const artifacts: { name: string; content: string }[] = [
+      { name: 'IMAGINE.md', content: imagineContent },
+      { name: 'ICP.md', content: icpContent },
+      { name: 'GTM.md', content: gtmContent },
+      { name: 'COMPETITION.md', content: competitionContent },
+      { name: 'DECISIONS.md', content: decisionsContent },
+    ];
+
+    const artifactsWritten: string[] = [];
+
+    for (const artifact of artifacts) {
+      const artifactPath = path.join(planningDir, artifact.name);
+      safeWriteFile(artifactPath, artifact.content);
+      artifactsWritten.push(artifactPath);
+    }
+
+    // ── Step 9: Update state ─────────────────────────────────────────
+    const finalState = readState(statePath);
+    if (finalState) {
+      finalState.stage_status.imagine = 'done';
+      finalState.last_checkpoint = {
+        workflow: 'gswd/imagine',
+        checkpoint_id: 'complete',
+        timestamp: new Date().toISOString(),
+      };
+
+      // Record auto decisions in state
+      if (autoDecisions) {
+        (finalState.auto as Record<string, unknown>).decisions = autoDecisions;
+      }
+
+      writeState(statePath, finalState);
+    }
+
+    // ── Step 10: Return result ───────────────────────────────────────
+    return {
+      status: 'complete',
+      artifacts_written: artifactsWritten,
+      gate_result: gateResult,
+      auto_decisions: autoDecisions,
+      selected_direction: selected,
+    };
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      status: 'error',
+      artifacts_written: [],
+      error: message,
+    };
+  }
+}

package/lib/parse.ts

@@ -0,0 +1,196 @@
+/**
+ * GSWD Parse Module — ID extraction, heading validation, normalization
+ *
+ * Parses GSWD artifact files for IDs (J-NNN, FR-NNN, NFR-NNN, I-NNN, C-NNN),
+ * validates required heading structure, and normalizes malformed IDs.
+ *
+ * Schema: GSWD_SPEC.md Section 6.1-6.3
+ */
+
+// ─── Required Headings ──────────────────────────────────────────────────────
+
+/**
+ * Required headings per artifact file type, from GSWD_SPEC Section 6.3.
+ * These are the stable anchors used by audit/compile parsers.
+ */
+export const REQUIRED_HEADINGS: Record<string, string[]> = {
+  'JOURNEYS.md': ['## Journeys'],
+  'SPEC.md': ['## Roles & Permissions', '## Functional Requirements', '## Acceptance Criteria'],
+  'NFR.md': ['## Non-Functional Requirements'],
+  'INTEGRATIONS.md': ['## Integrations'],
+  'ARCHITECTURE.md': ['## Architecture', '### Components', '### Data Model'],
+  'DECISIONS.md': [
+    '## Frozen Decisions',
+    '## Success Metrics',
+    '## Out of Scope',
+    '## Risks & Mitigations',
+    '## Open Questions',
+  ],
+  'AUDIT.md': ['## Coverage Matrix', '## Check Results'],
+  'PROJECT.md': ['## What This Is', '## Target User', '## Problem Statement', '## Wedge / MVP Boundary', '## Success Metrics', '## Out of Scope'],
+  'REQUIREMENTS.md': ['## Functional Requirements', '## Non-Functional Requirements', '## Traceability'],
+  'ROADMAP.md': ['## Overview', '## Phases'],
+  'STATE.md': ['## Frozen Decisions', '## Approvals', '## Open Questions', '## Risks'],
+};
+
+// ─── ID Normalization ────────────────────────────────────────────────────────
+
+/** Valid ID prefixes */
+const ID_PREFIXES = ['J', 'FR', 'NFR', 'I', 'C'] as const;
+
+/**
+ * Normalize an ID to canonical format: PREFIX-NNN (3-digit minimum, zero-padded).
+ *
+ * - FR-1    -> FR-001
+ * - FR-01   -> FR-001
+ * - FR-001  -> FR-001 (no change)
+ * - FR-1000 -> FR-1000 (4+ digits kept as-is)
+ * - INVALID -> INVALID (unrecognized format returned as-is)
+ */
+export function normalizeId(rawId: string): string {
+  if (!rawId) return rawId;
+
+  const match = rawId.match(/^(J|FR|NFR|I|C)-(\d+)$/);
+  if (!match) return rawId;
+
+  const prefix = match[1];
+  const num = parseInt(match[2], 10);
+  const padded = num.toString().padStart(3, '0');
+  return `${prefix}-${padded}`;
+}
+
+// ─── ID Extraction ───────────────────────────────────────────────────────────
+
+export interface ExtractedId {
+  id: string;        // Normalized ID
+  raw: string;       // Original text as found
+  normalized: boolean; // Whether normalization changed the ID
+}
+
+/**
+ * Extract IDs from content using regex.
+ *
+ * Regex: /\b(J|FR|NFR|I|C)-(\d{1,4})\b/g
+ * - Word boundary prevents partial matches (e.g., INFRASTRUCTURE-001)
+ * - Returns deduplicated array sorted by normalized ID ascending
+ * - Optional filter by idType (e.g., 'FR')
+ */
+export function extractIds(content: string, idType?: string): ExtractedId[] {
+  const regex = /\b(J|FR|NFR|I|C)-(\d{1,4})\b/g;
+  const seen = new Map<string, ExtractedId>();
+
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(content)) !== null) {
+    const raw = match[0];
+    const prefix = match[1];
+
+    // Filter by ID type if specified
+    if (idType && prefix !== idType) continue;
+
+    const normalized = normalizeId(raw);
+    if (!seen.has(normalized)) {
+      seen.set(normalized, {
+        id: normalized,
+        raw,
+        normalized: raw !== normalized,
+      });
+    }
+  }
+
+  // Sort by normalized ID ascending
+  return Array.from(seen.values()).sort((a, b) => {
+    // Split into prefix and number for proper sorting
+    const aParts = a.id.match(/^(.+)-(\d+)$/);
+    const bParts = b.id.match(/^(.+)-(\d+)$/);
+    if (!aParts || !bParts) return a.id.localeCompare(b.id);
+
+    // Sort by prefix first, then by number
+    if (aParts[1] !== bParts[1]) return aParts[1].localeCompare(bParts[1]);
+    return parseInt(aParts[2], 10) - parseInt(bParts[2], 10);
+  });
+}
+
+// ─── Heading Validation ──────────────────────────────────────────────────────
+
+export interface HeadingValidation {
+  valid: boolean;
+  missing: string[];
+  present: string[];
+}
+
+/**
+ * Validate that a file contains all required headings for its type.
+ *
+ * - Looks up required headings from REQUIRED_HEADINGS[fileType]
+ * - Case-insensitive search as safety layer
+ * - Returns which headings are present and which are missing
+ * - Unknown file types are always valid (no required headings)
+ */
+export function validateHeadings(content: string, fileType: string): HeadingValidation {
+  const required = REQUIRED_HEADINGS[fileType];
+
+  // Unknown file type — no required headings, always valid
+  if (!required) {
+    return { valid: true, missing: [], present: [] };
+  }
+
+  const contentLower = content.toLowerCase();
+  const missing: string[] = [];
+  const present: string[] = [];
+
+  for (const heading of required) {
+    if (contentLower.includes(heading.toLowerCase())) {
+      present.push(heading);
+    } else {
+      missing.push(heading);
+    }
+  }
+
+  return {
+    valid: missing.length === 0,
+    missing,
+    present,
+  };
+}
+
+// ─── Heading Content Extraction ──────────────────────────────────────────────
+
+/**
+ * Extract content between a heading and the next heading of same or higher level.
+ *
+ * @param content - Full file content
+ * @param heading - The heading to extract content from (e.g., "## Section A")
+ * @returns Content string (trimmed) or null if heading not found
+ */
+export function extractHeadingContent(content: string, heading: string): string | null {
+  const lines = content.split('\n');
+  const headingLevel = (heading.match(/^#+/) || [''])[0].length;
+
+  let capturing = false;
+  let startIdx = -1;
+  let endIdx = lines.length;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+
+    if (!capturing) {
+      // Look for the target heading
+      if (line.trim().toLowerCase() === heading.toLowerCase()) {
+        capturing = true;
+        startIdx = i + 1;
+      }
+    } else {
+      // Check if we hit another heading of same or higher level
+      const lineHeadingMatch = line.match(/^(#+)\s/);
+      if (lineHeadingMatch && lineHeadingMatch[1].length <= headingLevel) {
+        endIdx = i;
+        break;
+      }
+    }
+  }
+
+  if (startIdx === -1) return null;
+
+  const extracted = lines.slice(startIdx, endIdx).join('\n').trim();
+  return extracted;
+}