gswd 1.0.0 → 1.1.0

package/dist/lib/render.js

@@ -0,0 +1,624 @@
+"use strict";
+/**
+ * GSWD Render Module — Terminal UI rendering functions
+ *
+ * All functions return strings (not print to stdout).
+ * Zero external dependencies. Uses only string operations.
+ *
+ * Schema: GSWD_SPEC.md Section 7.1-7.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.SPECIFY_AGENT_BRIEFINGS = exports.IMAGINE_AGENT_BRIEFINGS = exports.STAGE_CONTEXT_TEMPLATES = exports.COLORS = exports.SYMBOLS = void 0;
+exports.colorize = colorize;
+exports.renderLogo = renderLogo;
+exports.renderFirstRunGuide = renderFirstRunGuide;
+exports.padRight = padRight;
+exports.renderBanner = renderBanner;
+exports.renderCheckpoint = renderCheckpoint;
+exports.renderNextUp = renderNextUp;
+exports.renderStatusLine = renderStatusLine;
+exports.renderProgressBar = renderProgressBar;
+exports.renderResearchSummary = renderResearchSummary;
+exports.renderDirectionCard = renderDirectionCard;
+exports.renderStageSummary = renderStageSummary;
+exports.extractProductContext = extractProductContext;
+exports.renderContextBanner = renderContextBanner;
+exports.renderAgentBriefing = renderAgentBriefing;
+exports.renderAgentCompletion = renderAgentCompletion;
+exports.renderAgentProgress = renderAgentProgress;
+exports.renderFileInventory = renderFileInventory;
+exports.extractHeadline = extractHeadline;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+// ─── Status Symbols ──────────────────────────────────────────────────────────
+exports.SYMBOLS = {
+    complete: '\u2713', // ✓
+    failed: '\u2717', // ✗
+    inProgress: '\u25C6', // ◆
+    pending: '\u25CB', // ○
+    autoApproved: '\u26A1', // ⚡
+    warning: '\u26A0', // ⚠
+};
+// ─── Colors ──────────────────────────────────────────────────────────────────
+/**
+ * ANSI color codes for GSWD branding.
+ * Electric orange/amber is the brand color (per CONTEXT.md locked decision).
+ * 256-color code \x1b[38;5;208m; dim uses \x1b[2m.
+ */
+exports.COLORS = {
+    orange: '\x1b[38;5;208m',
+    dim: '\x1b[2m',
+    reset: '\x1b[0m',
+};
+/**
+ * Wrap text in ANSI color. No-op when stdout is not a TTY (CI/Docker/pipe safety).
+ * Respects FORCE_COLOR env var to override TTY detection.
+ */
+function colorize(text, color) {
+    if (!process.stdout.isTTY && !process.env.FORCE_COLOR) {
+        return text;
+    }
+    return `${exports.COLORS[color]}${text}${exports.COLORS.reset}`;
+}
+// ─── Logo ────────────────────────────────────────────────────────────────────
+/**
+ * Render the GSWD ASCII logo with catchphrase.
+ * Logo shape matches GSD's block-letter style from install.js.
+ * Static string — no figlet (STATE.md architectural decision).
+ *
+ * @param version - Optional version string (e.g., "1.0.1")
+ */
+function renderLogo(version) {
+    const lines = [
+        '   \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557    \u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2557 ',
+        '  \u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D \u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2551    \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557',
+        '  \u2588\u2588\u2551  \u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551 \u2588\u2557 \u2588\u2588\u2551\u2588\u2588\u2551  \u2588\u2588\u2551',
+        '  \u2588\u2588\u2551   \u2588\u2588\u2551\u255A\u2550\u2550\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2551\u2588\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2551  \u2588\u2588\u2551',
+        '  \u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u255A\u2588\u2588\u2588\u2554\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D',
+        '   \u255A\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u2550\u255D\u255A\u2550\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u255D ',
+    ].join('\n');
+    const coloredLogo = colorize(lines, 'orange');
+    const tagline = '  Spec clarity before code.';
+    const versionStr = version ? colorize(`  v${version}`, 'dim') : '';
+    return [coloredLogo, '', tagline, versionStr].filter(Boolean).join('\n');
+}
+// ─── First Run Guide ─────────────────────────────────────────────────────────
+/**
+ * Render the condensed first-run command guide.
+ * Per CONTEXT.md: primary commands only, no descriptions.
+ * Followed by automatic /gswd:start proposal for zero-friction onboarding.
+ */
+function renderFirstRunGuide() {
+    const commands = [
+        '/gswd:start',
+        '/gswd:imagine',
+        '/gswd:specify',
+        '/gswd:compile',
+    ];
+    const lines = [
+        'Commands:',
+        '',
+        ...commands.map(cmd => `  ${colorize(cmd, 'orange')}`),
+        '',
+        'Run /gswd:start to begin.',
+    ];
+    return lines.join('\n');
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * Pad or truncate a string to exact width.
+ * If str exceeds width, truncate and append '...' (total = width).
+ */
+function padRight(str, width) {
+    if (str.length > width) {
+        return str.slice(0, width - 3) + '...';
+    }
+    return str + ' '.repeat(width - str.length);
+}
+// ─── Banner ──────────────────────────────────────────────────────────────────
+/**
+ * Render a stage banner matching GSWD_SPEC Section 7.1.
+ *
+ * ```
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ *  GSWD ► {STAGE NAME}
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ```
+ *
+ * Banner width = 55 characters. Stage name is uppercased.
+ */
+function renderBanner(stageName) {
+    const BANNER_WIDTH = 55;
+    const border = colorize('\u2501'.repeat(BANNER_WIDTH), 'orange');
+    const title = ` GSWD \u25B6 ${stageName.toUpperCase()}`;
+    return `${border}\n${title}\n${border}`;
+}
+// ─── Checkpoint Box ──────────────────────────────────────────────────────────
+/**
+ * Render a checkpoint box matching GSWD_SPEC Section 7.2.
+ *
+ * Box total width: 56 characters (54 inner + 2 border characters).
+ * Uses single-line box-drawing characters.
+ *
+ * @param type - Header text (e.g., "Decision Required")
+ * @param context - Context paragraph
+ * @param options - Numbered options list
+ * @param actionPrompt - Action prompt (appears after → )
+ */
+function renderCheckpoint(type, context, options, actionPrompt) {
+    const BOX_WIDTH = 56;
+    const INNER_WIDTH = BOX_WIDTH - 4; // 52 (accounting for "│ " and " │")
+    const topBorder = colorize(`\u250C${'\u2500'.repeat(BOX_WIDTH - 2)}\u2510`, 'orange');
+    const midBorder = colorize(`\u251C${'\u2500'.repeat(BOX_WIDTH - 2)}\u2524`, 'orange');
+    const bottomBorder = colorize(`\u2514${'\u2500'.repeat(BOX_WIDTH - 2)}\u2518`, 'orange');
+    const line = (text) => {
+        const padded = padRight(text, INNER_WIDTH);
+        return `${colorize('\u2502', 'orange')} ${padded} ${colorize('\u2502', 'orange')}`;
+    };
+    const blankLine = line('');
+    const lines = [];
+    lines.push(topBorder);
+    lines.push(line(type));
+    lines.push(midBorder);
+    lines.push(line(context));
+    lines.push(blankLine);
+    for (let i = 0; i < options.length; i++) {
+        lines.push(line(`${i + 1}) ${options[i]}`));
+    }
+    lines.push(blankLine);
+    lines.push(line(`\u2192 ${actionPrompt}`));
+    lines.push(bottomBorder);
+    return lines.join('\n');
+}
+// ─── Next Up ─────────────────────────────────────────────────────────────────
+/**
+ * Render a Next Up block matching GSWD_SPEC Section 7.3.
+ *
+ * ```
+ * ✓ Wrote: file1, file2, ...
+ *
+ * Next up:
+ *   {nextCommand}
+ *
+ * Tip:
+ *   If context is getting crowded, run /clear.
+ * ```
+ */
+function renderNextUp(files, nextCommand, alsoAvailable) {
+    const parts = [];
+    parts.push(`${exports.SYMBOLS.complete} Wrote: ${files.join(', ')}`);
+    parts.push('');
+    parts.push('Next up:');
+    parts.push(`  ${nextCommand}`);
+    parts.push('');
+    parts.push('Tip:');
+    parts.push('  If context is getting crowded, run /clear.');
+    if (alsoAvailable && alsoAvailable.length > 0) {
+        parts.push('');
+        parts.push('Also available:');
+        for (const item of alsoAvailable) {
+            parts.push(`  - ${item}`);
+        }
+    }
+    return parts.join('\n');
+}
+// ─── Status Line ─────────────────────────────────────────────────────────────
+/**
+ * Render a single status line with the appropriate symbol.
+ *
+ * Maps: done/pass -> ✓, fail -> ✗, in_progress -> ◆, not_started -> ○
+ */
+function renderStatusLine(stage, status) {
+    let symbol;
+    switch (status) {
+        case 'done':
+        case 'pass':
+            symbol = exports.SYMBOLS.complete;
+            break;
+        case 'fail':
+            symbol = exports.SYMBOLS.failed;
+            break;
+        case 'in_progress':
+            symbol = exports.SYMBOLS.inProgress;
+            break;
+        case 'not_started':
+            symbol = exports.SYMBOLS.pending;
+            break;
+        default:
+            symbol = exports.SYMBOLS.pending;
+    }
+    return `${symbol}  ${stage}: ${status}`;
+}
+// ─── Progress Bar ────────────────────────────────────────────────────────────
+/**
+ * Render an ASCII progress bar.
+ *
+ * ```
+ * Progress: ████████░░ 80%
+ * ```
+ *
+ * @param current - Current value
+ * @param total - Total value
+ * @param width - Bar width in characters (default 10)
+ */
+function renderProgressBar(current, total, width = 10) {
+    const ratio = total === 0 ? 0 : Math.min(current / total, 1);
+    const filled = Math.round(ratio * width);
+    const empty = width - filled;
+    const percent = Math.round(ratio * 100);
+    const bar = '\u2588'.repeat(filled) + '\u2591'.repeat(empty);
+    return `Progress: ${bar} ${percent}%`;
+}
+/**
+ * Render structured research summary after agent completion.
+ * Product-contextualized: section intros reference user's product.
+ * Per CONTEXT.md: 3-5 takeaway bullets per section, bridging paragraph per section.
+ *
+ * @param sections - Research summary sections from buildResearchSummary
+ * @param productContext - Brief description of the product (from brief.vision)
+ * @param targetUser - Who the product is for (from brief.target_user)
+ */
+function renderResearchSummary(sections, productContext, targetUser) {
+    const parts = [];
+    parts.push('## Research Summary');
+    parts.push('');
+    for (const section of sections) {
+        // Product-contextualized intro
+        parts.push(`### ${section.displayName}`);
+        parts.push(`*For a product helping ${targetUser}:*`);
+        parts.push('');
+        // Takeaway bullets (3-5)
+        for (const takeaway of section.takeaways) {
+            parts.push(`- ${takeaway}`);
+        }
+        parts.push('');
+        // Bridging paragraph
+        parts.push(section.bridge);
+        parts.push('');
+    }
+    return parts.join('\n');
+}
+/**
+ * Render a direction card with "Why this makes sense" rationale section.
+ * Per CONTEXT.md: rationale section comes FIRST, before existing fields.
+ * Recommended direction gets a visual marker.
+ *
+ * @param direction - Direction data
+ * @param index - 0-based index for display numbering
+ * @param isRecommended - Whether this is the proposed/recommended direction
+ */
+function renderDirectionCard(direction, index, isRecommended) {
+    const marker = isRecommended ? ' **(Recommended)**' : '';
+    const parts = [];
+    parts.push(`### ${direction.label}${marker}`);
+    parts.push('');
+    // Rationale section FIRST per CONTEXT.md locked decision
+    if (direction.rationale.length > 0) {
+        parts.push('**Why this makes sense:**');
+        for (const r of direction.rationale) {
+            parts.push(`- ${r}`);
+        }
+        parts.push('');
+    }
+    // Existing fields
+    parts.push(`**ICP:** ${direction.icp_summary}`);
+    parts.push(`**Problem:** ${direction.problem_framing}`);
+    parts.push(`**Wedge:** ${direction.wedge}`);
+    parts.push(`**Differentiator:** ${direction.differentiator}`);
+    parts.push(`**Risks:** ${direction.risks.join('; ')}`);
+    return parts.join('\n');
+}
+// ─── Stage Summary ───────────────────────────────────────────────────────────
+function renderStageSummary(input) {
+    const parts = [];
+    // Headline
+    parts.push(`## ${input.stageName} Complete`);
+    parts.push('');
+    parts.push(input.headline);
+    parts.push('');
+    // Key outputs (section summaries)
+    if (input.sections.length > 0) {
+        parts.push('**Key outputs:**');
+        for (const section of input.sections) {
+            parts.push(`- **${section.name}:** ${section.summary}`);
+        }
+        parts.push('');
+    }
+    // Files created
+    if (input.filesCreated.length > 0) {
+        parts.push(`**Created:** ${input.filesCreated.join(', ')}`);
+    }
+    return parts.join('\n');
+}
+/**
+ * Extract product context from DECISIONS.md and INTAKE.json.
+ * DECISIONS.md is preferred (more precise, available after Imagine).
+ * INTAKE.json is fallback (available from pipeline start).
+ * Returns safe defaults if neither file exists.
+ *
+ * @param planningDir - Path to .planning/ directory
+ * @param isRerun - Whether this is a re-run
+ */
+function extractProductContext(planningDir, isRerun = false) {
+    let domain = 'your product';
+    let targetUser = 'your users';
+    // Try DECISIONS.md first (more precise, available after Imagine)
+    try {
+        const decisionsPath = path.join(planningDir, 'DECISIONS.md');
+        const decisions = fs.readFileSync(decisionsPath, 'utf-8');
+        const targetMatch = decisions.match(/\*\*Target User:\*\*\s*(?:Auto-chosen:\s*)?(.+)/);
+        if (targetMatch)
+            targetUser = targetMatch[1].trim();
+        const directionMatch = decisions.match(/\*\*Product Direction:\*\*\s*(?:Auto-chosen:\s*)?(.+)/);
+        if (directionMatch)
+            domain = directionMatch[1].trim();
+    }
+    catch {
+        // Fall through to INTAKE.json
+    }
+    // Fallback to INTAKE.json (available from pipeline start)
+    if (domain === 'your product') {
+        try {
+            const gswdDir = path.join(planningDir, 'gswd');
+            const intakePath = path.join(gswdDir, 'INTAKE.json');
+            const intake = JSON.parse(fs.readFileSync(intakePath, 'utf-8'));
+            if (intake.product_description) {
+                // Use first sentence as domain
+                const firstSentence = intake.product_description.split('.')[0];
+                if (firstSentence && firstSentence.trim().length > 0) {
+                    domain = firstSentence.trim();
+                }
+            }
+        }
+        catch {
+            // Use defaults
+        }
+    }
+    return { domain, targetUser, stageContext: '', isRerun, rerunContext: undefined };
+}
+// ─── Stage Context Templates ────────────────────────────────────────────────
+/**
+ * Stage-specific context line generators for contextual banners.
+ * Each returns a product-contextualized one-liner for the banner.
+ * Compile is deliberately excluded (per CONTEXT.md: deterministic, no banner needed).
+ */
+exports.STAGE_CONTEXT_TEMPLATES = {
+    imagine: (ctx) => ctx.isRerun
+        ? `Refining directions based on your feedback${ctx.rerunContext ? ` about ${ctx.rerunContext}` : ''}`
+        : `Validating product direction for ${ctx.domain} targeting ${ctx.targetUser}`,
+    specify: (ctx) => `Building the execution-grade spec: journeys, requirements, and architecture for ${ctx.domain}`,
+    audit: (ctx) => `Verifying spec completeness \u2014 every journey, requirement, and edge case for ${ctx.domain} must trace`,
+};
+// ─── Agent Briefing Templates ───────────────────────────────────────────────
+/**
+ * Product-contextualized one-liner descriptions for Imagine research agents.
+ * Each function receives ProductContext and returns a purpose string.
+ */
+exports.IMAGINE_AGENT_BRIEFINGS = {
+    'market-researcher': (ctx) => `mapping the ${ctx.domain} landscape to find gaps`,
+    'icp-persona': (ctx) => `profiling ${ctx.targetUser} who need ${ctx.domain}`,
+    'positioning': (ctx) => `finding the angle that makes ${ctx.domain} obviously necessary`,
+    'brainstorm-alternatives': (ctx) => `exploring 3 distinct product directions for ${ctx.domain}`,
+    'devils-advocate': (ctx) => `stress-testing assumptions before you commit to a direction`,
+};
+/**
+ * Product-contextualized one-liner descriptions for Specify agents.
+ */
+exports.SPECIFY_AGENT_BRIEFINGS = {
+    'journey-mapper': (ctx) => `mapping user journeys for ${ctx.targetUser} through ${ctx.domain}`,
+    'architecture-drafter': (ctx) => `designing the system architecture for ${ctx.domain}`,
+    'integrations-checker': (ctx) => `evaluating external services ${ctx.domain} needs to connect with`,
+};
+// ─── Contextual Banner ──────────────────────────────────────────────────────
+/**
+ * Render a stage banner with a product-contextualized line below the title.
+ * Extension of renderBanner() for consultant-style messaging (Phase 16).
+ *
+ * ```
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ *  GSWD ► IMAGINE
+ *  Validating product direction for a spec-writing tool targeting founders
+ * ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ * ```
+ *
+ * @param stageName - Stage name (will be uppercased)
+ * @param contextLine - Product-contextualized one-liner
+ */
+function renderContextBanner(stageName, contextLine) {
+    const BANNER_WIDTH = 55;
+    const border = colorize('\u2501'.repeat(BANNER_WIDTH), 'orange');
+    const title = ` GSWD \u25B6 ${stageName.toUpperCase()}`;
+    const context = ` ${contextLine}`;
+    return `${border}\n${title}\n${context}\n${border}`;
+}
+/**
+ * Render agent pre-briefing block before spawning.
+ * Technical transparency: name each agent explicitly with product-specific purpose.
+ *
+ * ```
+ * ◆ Spawning 5 research agents:
+ *   → market-researcher: mapping the spec-tooling landscape to find gaps
+ *   → icp-persona: profiling founders who struggle with product specification
+ * ```
+ *
+ * @param agents - Array of agent names with product-contextualized purposes
+ * @param stageContext - Optional stage context description
+ */
+function renderAgentBriefing(agents, stageContext) {
+    const parts = [];
+    parts.push(`${exports.SYMBOLS.inProgress} Spawning ${agents.length} research agents:`);
+    for (const agent of agents) {
+        parts.push(`  \u2192 ${agent.name}: ${agent.productPurpose}`);
+    }
+    if (stageContext) {
+        parts.push('');
+        parts.push(stageContext);
+    }
+    return parts.join('\n');
+}
+// ─── Agent Completion ───────────────────────────────────────────────────────
+/**
+ * Render a single agent completion line with its key finding headline.
+ *
+ * ✓ market-researcher: 3 direct competitors in the spec-tooling space
+ * ✗ icp-persona: Agent failed — timeout
+ *
+ * @param agentName - Agent name
+ * @param headline - Key finding or error message
+ * @param status - Agent completion status
+ */
+function renderAgentCompletion(agentName, headline, status) {
+    const symbol = status === 'complete' ? exports.SYMBOLS.complete : exports.SYMBOLS.failed;
+    return `${symbol} ${agentName}: ${headline}`;
+}
+// ─── Agent Progress ─────────────────────────────────────────────────────────
+/**
+ * Render full agent progress block showing pending and completed agents.
+ * Pending agents show ○, completed show ✓ with headline, failed show ✗.
+ *
+ * ✓ market-researcher: 3 direct competitors found
+ * ✓ icp-persona: primary persona is technical founder
+ * ○ positioning (pending)
+ * ○ brainstorm-alternatives (pending)
+ * ○ devils-advocate (pending)
+ */
+function renderAgentProgress(agents) {
+    const lines = [];
+    for (const agent of agents) {
+        switch (agent.status) {
+            case 'complete':
+                lines.push(`${exports.SYMBOLS.complete} ${agent.name}: ${agent.headline || 'complete'}`);
+                break;
+            case 'failed':
+                lines.push(`${exports.SYMBOLS.failed} ${agent.name}: ${agent.headline || 'failed'}`);
+                break;
+            case 'pending':
+                lines.push(`${exports.SYMBOLS.pending} ${agent.name} (pending)`);
+                break;
+        }
+    }
+    return lines.join('\n');
+}
+// ─── File Inventory ──────────────────────────────────────────────────────────
+/**
+ * Render a file inventory table listing all generated files with descriptions.
+ * Used at pipeline end to give users a deliverable checklist.
+ *
+ * @param files - Array of { path, description } objects
+ * @returns Markdown table string
+ */
+function renderFileInventory(files) {
+    if (files.length === 0)
+        return '';
+    const lines = [];
+    lines.push('| File | Description |');
+    lines.push('|------|-------------|');
+    for (const file of files) {
+        lines.push(`| \`${file.path}\` | ${file.description} |`);
+    }
+    return lines.join('\n');
+}
+// ─── Headline Extraction ────────────────────────────────────────────────────
+/**
+ * Extract a one-line headline from agent output for completion display.
+ * Multi-strategy extraction with robust fallback.
+ *
+ * Strategy priority:
+ * 1. First sentence after "## Summary" heading
+ * 2. Text after "Key finding:" prefix
+ * 3. First non-heading, non-empty line
+ * 4. Fallback: "{agentName} analysis complete"
+ *
+ * Truncates to 80 chars. Never returns empty string.
+ *
+ * @param agentOutput - Raw agent output content
+ * @param agentName - Agent name (for fallback)
+ */
+function extractHeadline(agentOutput, agentName) {
+    const MAX_LENGTH = 80;
+    if (!agentOutput || agentOutput.trim().length === 0) {
+        return `${agentName} analysis complete`;
+    }
+    const lines = agentOutput.split('\n');
+    // Strategy 1: First sentence after "## Summary" heading
+    for (let i = 0; i < lines.length; i++) {
+        if (/^##\s+Summary\s*$/i.test(lines[i].trim())) {
+            // Look at next non-empty lines for the first sentence
+            for (let j = i + 1; j < lines.length; j++) {
+                const line = lines[j].trim();
+                if (line.length === 0)
+                    continue;
+                if (line.startsWith('#'))
+                    break; // next heading, stop
+                // Take up to first period
+                const periodIdx = line.indexOf('.');
+                const sentence = periodIdx > 0 ? line.slice(0, periodIdx + 1) : line;
+                return truncateHeadline(sentence, MAX_LENGTH);
+            }
+        }
+    }
+    // Strategy 2: "Key finding:" prefix
+    for (const line of lines) {
+        const match = line.match(/Key finding:\s*(.+)/i);
+        if (match) {
+            return truncateHeadline(match[1].trim(), MAX_LENGTH);
+        }
+    }
+    // Strategy 3: First non-heading, non-empty line
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        if (trimmed.startsWith('#'))
+            continue;
+        if (trimmed.startsWith('---'))
+            continue;
+        if (trimmed.startsWith('```'))
+            continue;
+        return truncateHeadline(trimmed, MAX_LENGTH);
+    }
+    // Strategy 4: Fallback
+    return `${agentName} analysis complete`;
+}
+/**
+ * Truncate a string to maxLength, adding "..." if truncated.
+ */
+function truncateHeadline(text, maxLength) {
+    const cleaned = text.trim();
+    if (cleaned.length <= maxLength)
+        return cleaned;
+    return cleaned.slice(0, maxLength - 3) + '...';
+}