gswd 1.0.0 → 1.1.0

package/lib/imagine-synthesis.ts

@@ -9,6 +9,7 @@
  */
 
 import type { AgentResult } from './imagine-agents.js';
+import type { StarterBrief } from './imagine-input.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -19,8 +20,31 @@ export interface Direction {
   wedge: string;           // MVP boundary / entry point
   differentiator: string;  // What makes this unique
   risks: string[];         // Top 2-3 risks for this direction
+  rationale?: string[];    // Evidence-based rationale bullets (optional for backward compat)
 }
 
+/**
+ * Research summary section for post-agent display.
+ * Produced by buildResearchSummary(), consumed by renderResearchSummary().
+ */
+export interface ResearchSummarySection {
+  agentName: string;       // Internal agent name (e.g., 'market-researcher')
+  displayName: string;     // User-friendly name (e.g., 'Market Landscape')
+  takeaways: string[];     // 3-5 key bullet takeaways
+  bridge: string;          // Bridging paragraph: "These findings shaped..."
+}
+
+/**
+ * User-friendly display names for imagine agents.
+ */
+export const AGENT_DISPLAY_NAMES: Record<string, string> = {
+  'market-researcher': 'Market Landscape',
+  'icp-persona': 'Ideal Customer',
+  'positioning': 'Positioning and GTM',
+  'brainstorm-alternatives': 'Product Directions',
+  'devils-advocate': 'Risks and Challenges',
+};
+
 export interface AutoDecision {
   type: string;        // 'icp' | 'wedge' | 'direction' | 'metric'
   chosen: string;      // What was selected
@@ -135,6 +159,71 @@ function extractField(body: string, fieldName: string): string {
   return match ? match[1].trim() : '';
 }
 
+/**
+ * Build evidence-based rationale bullets by cross-referencing agent content.
+ * Returns 2-4 bullets traceable to specific agent findings.
+ */
+function buildRationale(
+  directionBody: string,
+  marketContent: string,
+  icpContent: string,
+  positioningContent: string,
+): string[] {
+  const rationale: string[] = [];
+
+  // Extract market evidence
+  if (marketContent) {
+    const marketMatch = marketContent.match(/##\s*Market (?:Overview|Gaps?)\s*\n+([\s\S]*?)(?=\n##|$)/);
+    if (marketMatch) {
+      const firstBullet = marketMatch[1].trim().split('\n')
+        .filter(l => l.trim().startsWith('-') || l.trim().startsWith('*'))
+        .map(l => l.replace(/^[-*]\s*/, '').trim())
+        .find(l => l.length > 10);
+      if (firstBullet) {
+        rationale.push(`Market evidence: ${firstBullet}`);
+      }
+    }
+  }
+
+  // Extract ICP evidence
+  if (icpContent) {
+    const painMatch = icpContent.match(/##\s*Pain Points?\s*\n+([\s\S]*?)(?=\n##|$)/);
+    if (painMatch) {
+      const firstPain = painMatch[1].trim().split('\n')
+        .filter(l => l.trim().startsWith('-') || l.trim().startsWith('*'))
+        .map(l => l.replace(/^[-*]\s*/, '').trim())
+        .find(l => l.length > 10);
+      if (firstPain) {
+        rationale.push(`ICP insight: ${firstPain}`);
+      }
+    }
+  }
+
+  // Extract positioning evidence
+  if (positioningContent) {
+    const vpMatch = positioningContent.match(/##\s*Value Proposition\s*\n+([\s\S]*?)(?=\n##|$)/);
+    if (vpMatch) {
+      const firstLine = vpMatch[1].trim().split('\n')[0];
+      if (firstLine && firstLine.length > 10) {
+        rationale.push(`Competitive advantage: ${firstLine}`);
+      }
+    }
+  }
+
+  // Extract direction-specific evidence from the body itself
+  const diffField = extractField(directionBody, 'Differentiator');
+  if (diffField && diffField.length > 10 && rationale.length < 4) {
+    rationale.push(`Direction differentiator: ${diffField}`);
+  }
+
+  // Ensure at least one rationale bullet
+  if (rationale.length === 0) {
+    rationale.push('Rationale unavailable — agent data incomplete');
+  }
+
+  return rationale;
+}
+
 /**
  * Build a Direction from parsed section data, enriched with ICP and risk data.
  */
@@ -143,6 +232,8 @@ function buildDirection(
   body: string,
   icpContent: string,
   risksContent: string,
+  marketContent?: string,
+  positioningContent?: string,
 ): Direction {
   const icp = extractField(body, 'ICP') || extractIcpSummary(icpContent);
   const problem = extractField(body, 'Problem') || 'See agent research outputs';
@@ -150,8 +241,9 @@ function buildDirection(
   const differentiator = extractField(body, 'Differentiator') || 'To be refined';
   const riskField = extractField(body, 'Risk');
   const risks = riskField ? [riskField] : extractRiskList(risksContent);
+  const rationale = buildRationale(body, marketContent || '', icpContent, positioningContent || '');
 
-  return { label, icp_summary: icp, problem_framing: problem, wedge, differentiator, risks };
+  return { label, icp_summary: icp, problem_framing: problem, wedge, differentiator, risks, rationale };
 }
 
 /**
@@ -220,15 +312,15 @@ export function synthesizeDirections(agentResults: AgentResult[]): SynthesisResu
     const sections = parseDirectionSections(brainstormContent);
 
     if (sections.length >= 3) {
-      proposed = buildDirection(sections[0].label, sections[0].body, icpContent, risksContent);
+      proposed = buildDirection(sections[0].label, sections[0].body, icpContent, risksContent, marketContent, positioningContent);
       alternatives = [
-        buildDirection(sections[1].label, sections[1].body, icpContent, risksContent),
-        buildDirection(sections[2].label, sections[2].body, icpContent, risksContent),
+        buildDirection(sections[1].label, sections[1].body, icpContent, risksContent, marketContent, positioningContent),
+        buildDirection(sections[2].label, sections[2].body, icpContent, risksContent, marketContent, positioningContent),
       ];
     } else if (sections.length >= 1) {
       // Partial parse — use what we have
-      proposed = buildDirection(sections[0].label, sections[0].body, icpContent, risksContent);
-      alternatives = sections.slice(1).map(s => buildDirection(s.label, s.body, icpContent, risksContent));
+      proposed = buildDirection(sections[0].label, sections[0].body, icpContent, risksContent, marketContent, positioningContent);
+      alternatives = sections.slice(1).map(s => buildDirection(s.label, s.body, icpContent, risksContent, marketContent, positioningContent));
       // Fill missing alternatives with degraded entries
       while (alternatives.length < 2) {
         alternatives.push(buildDegradedDirection(alternatives.length + 2, icpContent, positioningContent, risksContent));
@@ -289,6 +381,7 @@ function buildDegradedDirection(
     wedge: 'To be defined',
     differentiator,
     risks,
+    rationale: ['Rationale unavailable — insufficient agent data'],
   };
 }
 
@@ -350,6 +443,77 @@ export function scoreIcpOptions(directions: Direction[]): ScoreResult {
   return { index: index >= 0 ? index : 0, scores };
 }
 
+// ─── Research Summary ────────────────────────────────────────────────────────
+
+/**
+ * Extract takeaway bullets from agent content.
+ * Looks for bullet items under headings, returns up to maxItems.
+ */
+function extractTakeaways(content: string, maxItems: number = 5): string[] {
+  if (!content) return [];
+  const bullets: string[] = [];
+  const lines = content.split('\n');
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (/^[-*]\s+/.test(trimmed) && trimmed.length > 10) {
+      bullets.push(trimmed.replace(/^[-*]\s+/, ''));
+      if (bullets.length >= maxItems) break;
+    }
+  }
+  return bullets;
+}
+
+/**
+ * Build structured research summary from agent results.
+ * Each section: agent display name, 3-5 takeaway bullets, bridging paragraph.
+ * Product-contextualized using brief.vision and brief.target_user.
+ */
+export function buildResearchSummary(
+  agentResults: AgentResult[],
+  brief: StarterBrief,
+): ResearchSummarySection[] {
+  const sections: ResearchSummarySection[] = [];
+
+  for (const result of agentResults) {
+    const displayName = AGENT_DISPLAY_NAMES[result.agent] || result.agent;
+
+    if (result.status === 'failed' || !result.content) {
+      sections.push({
+        agentName: result.agent,
+        displayName,
+        takeaways: ['Agent failed — no findings available'],
+        bridge: `These findings could not shape the directions below due to agent failure.`,
+      });
+      continue;
+    }
+
+    const takeaways = extractTakeaways(result.content);
+    // Ensure at least 3 takeaways; pad with content excerpts if needed
+    if (takeaways.length < 3) {
+      const lines = result.content.split('\n')
+        .filter(l => l.trim().length > 20 && !l.trim().startsWith('#'))
+        .slice(0, 3 - takeaways.length);
+      for (const line of lines) {
+        takeaways.push(line.trim().slice(0, 150));
+      }
+    }
+
+    // Build product-contextualized bridge paragraph
+    const userCtx = brief.target_user || 'target users';
+    const visionCtx = brief.vision || 'the product';
+    const bridge = `These findings shaped the directions below by revealing how ${visionCtx} can best serve ${userCtx} in this domain.`;
+
+    sections.push({
+      agentName: result.agent,
+      displayName,
+      takeaways: takeaways.slice(0, 5),
+      bridge,
+    });
+  }
+
+  return sections;
+}
+
 // ─── Auto Selection ─────────────────────────────────────────────────────────
 
 /**

package/lib/imagine.ts

@@ -20,8 +20,8 @@ import { parseIdeaFile, buildFromIntake, validateBrief } from './imagine-input.j
 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 { synthesizeDirections, autoSelectDirection, scoreIcpOptions, buildResearchSummary } from './imagine-synthesis.js';
+import type { Direction, AutoDecision, SynthesisResult, ResearchSummarySection } from './imagine-synthesis.js';
 import { validateDecisionGate } from './imagine-gate.js';
 import type { GateResult } from './imagine-gate.js';
 
@@ -36,6 +36,9 @@ export interface ImagineOptions {
   configPath?: string;         // Override config.json path (for testing)
   spawnFn?: SpawnFn;           // Task() wrapper (injectable for testing)
   selectedDirectionIndex?: number; // Manual direction selection (0-based)
+  previousAgentOutputs?: Record<string, string>;  // For re-run augmentation (IMAGINE-03)
+  userFeedback?: string;                           // For re-run augmentation (IMAGINE-03)
+  visionStatement?: string;                        // Pre-approved vision (from Accept/Edit flow)
 }
 
 export interface ImagineResult {
@@ -44,6 +47,9 @@ export interface ImagineResult {
   gate_result?: GateResult;
   auto_decisions?: AutoDecision[];
   selected_direction?: Direction;
+  research_summary?: ResearchSummarySection[];  // Structured per-agent summary (IMAGINE-01)
+  vision_statement?: string;                     // Frozen vision statement (IMAGINE-05)
+  agent_headlines?: Array<{ agent: string; headline: string; status: 'complete' | 'failed' }>;  // Per-agent completion headlines (COMM-03)
   error?: string;
 }
 
@@ -56,6 +62,7 @@ function buildImagineContent(
   brief: StarterBrief,
   selected: Direction,
   synthesis: SynthesisResult,
+  visionStatement: string,
   autoDecisions?: AutoDecision[],
 ): string {
   const alternatives = synthesis.alternatives
@@ -69,7 +76,7 @@ function buildImagineContent(
   return `# Imagine
 
 ## Vision
-${brief.vision}
+${visionStatement}
 
 ## Target User
 ${brief.target_user}
@@ -116,6 +123,7 @@ function buildDecisionsContent(
   selected: Direction,
   synthesis: SynthesisResult,
   brief: StarterBrief,
+  visionStatement: string,
   autoDecisions?: AutoDecision[],
 ): string {
   // Build frozen decisions (need >= 8)
@@ -156,6 +164,9 @@ function buildDecisionsContent(
 
   return `# Decisions
 
+## Vision
+${visionStatement}
+
 ## Frozen Decisions
 ${frozenDecisions.join('\n')}
 
@@ -223,6 +234,23 @@ function buildAgentArtifact(agentName: string, rawOutputs: Record<string, string
   return content || fallback;
 }
 
+// ─── Vision Synthesis ───────────────────────────────────────────────────────
+
+/**
+ * Synthesize an aspirational vision statement from brief and selected direction.
+ * Vision = future state the product enables, NOT product description.
+ * Example: "A world where solo founders never build the wrong thing because
+ * their specification process is as rigorous as their code."
+ *
+ * This is a template-based synthesis; in manual mode, the LLM in start.md
+ * will generate a richer vision and pass it via options.visionStatement.
+ */
+function synthesizeVisionStatement(brief: StarterBrief, selected: Direction): string {
+  const userContext = brief.target_user || 'users';
+  const problemContext = selected.problem_framing || brief.vision;
+  return `A world where ${userContext} achieve ${problemContext} effortlessly — because the right tools make clarity the default, not the exception.`;
+}
+
 // ─── Main Workflow ──────────────────────────────────────────────────────────
 
 /**
@@ -282,6 +310,7 @@ export async function runImagine(options: ImagineOptions): Promise<ImagineResult
 
     // ── Step 3: Spawn agents ──────────────────────────────────────────
     let agentResults: AgentResult[];
+    const agentHeadlines: Array<{ agent: string; headline: string; status: 'complete' | 'failed' }> = [];
 
     if (options.skipResearch) {
       // Create minimal results from brief content
@@ -312,9 +341,15 @@ export async function runImagine(options: ImagineOptions): Promise<ImagineResult
         config.max_parallel_agents,
         brief,
         spawnFn,
+        options.previousAgentOutputs,
+        options.userFeedback,
+        (result) => { agentHeadlines.push(result); },
       );
     }
 
+    // Build research summary (IMAGINE-01)
+    const researchSummary = buildResearchSummary(agentResults, brief);
+
     // Mid-stage checkpoint: agents complete (RESM-02)
     writeCheckpoint(statePath, 'gswd/imagine', 'agents-complete');
 
@@ -341,9 +376,19 @@ export async function runImagine(options: ImagineOptions): Promise<ImagineResult
     // Mid-stage checkpoint: direction selected (RESM-02)
     writeCheckpoint(statePath, 'gswd/imagine', 'direction-selected');
 
+    // ── Step 5.5: Synthesize vision statement (IMAGINE-05) ───────────
+    let visionStatement: string;
+    if (options.visionStatement) {
+      // User already approved/edited a vision statement (manual mode)
+      visionStatement = options.visionStatement;
+    } else {
+      // Auto-generate from brief + selected direction
+      visionStatement = synthesizeVisionStatement(brief, selected);
+    }
+
     // ── Step 6: Build artifacts ──────────────────────────────────────
-    const imagineContent = buildImagineContent(brief, selected, synthesis, autoDecisions);
-    const decisionsContent = buildDecisionsContent(selected, synthesis, brief, autoDecisions);
+    const imagineContent = buildImagineContent(brief, selected, synthesis, visionStatement, autoDecisions);
+    const decisionsContent = buildDecisionsContent(selected, synthesis, brief, visionStatement, autoDecisions);
 
     const icpContent = buildAgentArtifact(
       'icp-persona',
@@ -378,6 +423,9 @@ export async function runImagine(options: ImagineOptions): Promise<ImagineResult
     }
 
     // ── Step 8: Write artifacts ──────────────────────────────────────
+    const directionsContent = synthesis.raw_agent_outputs['brainstorm-alternatives'] || '';
+    const risksRawContent = synthesis.raw_agent_outputs['devils-advocate'] || '';
+
     const artifacts: { name: string; content: string }[] = [
       { name: 'IMAGINE.md', content: imagineContent },
       { name: 'ICP.md', content: icpContent },
@@ -386,6 +434,9 @@ export async function runImagine(options: ImagineOptions): Promise<ImagineResult
       { name: 'DECISIONS.md', content: decisionsContent },
     ];
 
+    if (directionsContent) artifacts.push({ name: 'DIRECTIONS.md', content: directionsContent });
+    if (risksRawContent) artifacts.push({ name: 'RISKS.md', content: risksRawContent });
+
     const artifactsWritten: string[] = [];
 
     for (const artifact of artifacts) {
@@ -419,6 +470,9 @@ export async function runImagine(options: ImagineOptions): Promise<ImagineResult
       gate_result: gateResult,
       auto_decisions: autoDecisions,
       selected_direction: selected,
+      research_summary: researchSummary,
+      vision_statement: visionStatement,
+      agent_headlines: agentHeadlines.length > 0 ? agentHeadlines : undefined,
     };
   } catch (err: unknown) {
     const message = err instanceof Error ? err.message : String(err);

package/lib/intake.ts

@@ -0,0 +1,60 @@
+/**
+ * GSWD Intake Module — INTAKE.json persistence for idempotent resume
+ *
+ * Writes/reads the user's confirmed product description to .planning/gswd/INTAKE.json.
+ * Uses atomic write pattern from state.ts (safeWriteJson).
+ *
+ * INTAKE.json is separate from intake.md:
+ * - intake.md: text file passed to bootstrap CLI (imagine agents)
+ * - INTAKE.json: machine-readable state for resume
+ */
+
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { safeWriteJson } from './state.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface IntakeData {
+  version: 1;
+  recorded_at: string;
+  product_description: string;
+  source: 'interactive' | 'file';
+  idea_file?: string;
+}
+
+// ─── CRUD ────────────────────────────────────────────────────────────────────
+
+/**
+ * Write INTAKE.json atomically to the given GSWD directory.
+ * Persistence timing: called once after user confirms their product description
+ * (the "Did I get that right?" moment in start.md).
+ */
+export function writeIntake(
+  gswdDir: string,
+  data: Omit<IntakeData, 'version' | 'recorded_at'>
+): IntakeData {
+  const intake: IntakeData = {
+    version: 1,
+    recorded_at: new Date().toISOString(),
+    ...data,
+  };
+  const intakePath = path.join(gswdDir, 'INTAKE.json');
+  safeWriteJson(intakePath, intake);
+  return intake;
+}
+
+/**
+ * Read INTAKE.json. Returns null if missing or corrupt.
+ */
+export function readIntake(gswdDir: string): IntakeData | null {
+  const intakePath = path.join(gswdDir, 'INTAKE.json');
+  try {
+    const content = fs.readFileSync(intakePath, 'utf-8');
+    const parsed = JSON.parse(content);
+    if (typeof parsed.product_description !== 'string') return null;
+    return parsed as IntakeData;
+  } catch {
+    return null;
+  }
+}

package/lib/parse.ts

@@ -20,6 +20,7 @@ export const REQUIRED_HEADINGS: Record<string, string[]> = {
   'INTEGRATIONS.md': ['## Integrations'],
   'ARCHITECTURE.md': ['## Architecture', '### Components', '### Data Model'],
   'DECISIONS.md': [
+    '## Vision',
     '## Frozen Decisions',
     '## Success Metrics',
     '## Out of Scope',
@@ -27,7 +28,7 @@ export const REQUIRED_HEADINGS: Record<string, string[]> = {
     '## 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'],
+  'PROJECT.md': ['## What This Is', '## Target User', '## Problem Statement', '## Wedge / MVP Boundary', '## Success Metrics', '## Out of Scope', '## Context'],
   'REQUIREMENTS.md': ['## Functional Requirements', '## Non-Functional Requirements', '## Traceability'],
   'ROADMAP.md': ['## Overview', '## Phases'],
   'STATE.md': ['## Frozen Decisions', '## Approvals', '## Open Questions', '## Risks'],