ai-spec-dev 0.31.0 → 0.35.0

package/cli/utils.ts

@@ -0,0 +1,83 @@
+import * as path from "path";
+import * as fs from "fs-extra";
+import chalk from "chalk";
+import { input, select } from "@inquirer/prompts";
+import { CodeGenMode } from "../core/code-generator";
+import { ENV_KEY_MAP } from "../core/spec-generator";
+import { getSavedKey, saveKey, KEY_STORE_FILE } from "../core/key-store";
+
+// ─── Config ───────────────────────────────────────────────────────────────────
+
+export interface AiSpecConfig {
+  provider?: string;
+  model?: string;
+  codegen?: CodeGenMode;
+  codegenProvider?: string;
+  codegenModel?: string;
+  /** Minimum overall spec score (1-10) required to pass Approval Gate. 0 = disabled (default). */
+  minSpecScore?: number;
+}
+
+export const CONFIG_FILE = ".ai-spec.json";
+
+export async function loadConfig(dir: string): Promise<AiSpecConfig> {
+  const p = path.join(dir, CONFIG_FILE);
+  if (await fs.pathExists(p)) {
+    return fs.readJson(p);
+  }
+  return {};
+}
+
+// ─── API Key Resolution ───────────────────────────────────────────────────────
+
+export async function resolveApiKey(
+  providerName: string,
+  cliKey?: string
+): Promise<string> {
+  if (cliKey) return cliKey;
+
+  const envVar = ENV_KEY_MAP[providerName];
+  if (envVar && process.env[envVar]) return process.env[envVar]!;
+
+  const savedKey = await getSavedKey(providerName);
+  if (savedKey) {
+    const masked = savedKey.slice(0, 6) + "..." + savedKey.slice(-4);
+    const choice = await select({
+      message: `${providerName} API key (saved: ${masked}):`,
+      choices: [
+        { name: "Use saved key", value: "reuse" },
+        { name: "Enter a new key", value: "new" },
+      ],
+    });
+    if (choice === "reuse") return savedKey;
+  }
+
+  const newKey = await input({
+    message: `Enter your ${providerName} API key${envVar ? ` (or set ${envVar} env var)` : ""}:`,
+    validate: (v) => v.trim().length > 0 || "API key cannot be empty",
+  });
+  await saveKey(providerName, newKey.trim());
+  console.log(chalk.gray(`  Key saved to ${KEY_STORE_FILE}`));
+  return newKey.trim();
+}
+
+// ─── Banner ───────────────────────────────────────────────────────────────────
+
+export function printBanner(opts: {
+  specProvider: string;
+  specModel: string;
+  codegenMode: string;
+  codegenProvider: string;
+  codegenModel: string;
+}) {
+  console.log(chalk.blue("\n" + "─".repeat(52)));
+  console.log(chalk.bold("  ai-spec — AI-driven Development Orchestrator"));
+  console.log(chalk.blue("─".repeat(52)));
+  console.log(chalk.gray(`  Spec    : ${opts.specProvider} / ${opts.specModel}`));
+  console.log(
+    chalk.gray(
+      `  Codegen : ${opts.codegenMode} (${opts.codegenProvider} / ${opts.codegenModel})`
+    )
+  );
+  console.log(chalk.blue("─".repeat(52) + "\n"));
+}

package/core/combined-generator.ts

@@ -20,18 +20,28 @@ const tasksInstruction = `
 After outputting the complete spec above, append EXACTLY this line on its own (no extra text before or after it):
 ${TASKS_SEPARATOR}
 Then output a valid JSON array of implementation tasks. Each element must have these exact fields:
-{"id":"TASK-001","title":"...","description":"1-2 sentences, specific","layer":"data|infra|service|api|test","filesToTouch":["src/..."],"acceptanceCriteria":["verifiable condition"],"dependencies":[],"priority":"high|medium|low"}
+{"id":"TASK-001","title":"...","description":"1-2 sentences, specific","layer":"data|infra|service|api|test","filesToTouch":["src/..."],"acceptanceCriteria":["behavioral condition"],"verificationSteps":["concrete runnable check → expected result"],"dependencies":[],"priority":"high|medium|low"}
+verificationSteps rules: each step is a specific command or action with observable expected output (e.g. "POST /api/orders → 201 {id, status:'pending'}"). At least 2 per task, max 5. Never vague.
 Layer order: data → infra → service → api → test. 4-10 tasks total. filesToTouch must use real paths from the project context.`;
 
 export async function generateSpecWithTasks(
   provider: AIProvider,
   idea: string,
-  context?: ProjectContext
+  context?: ProjectContext,
+  architectureDecision?: string
 ): Promise<{ spec: string; tasks: SpecTask[] }> {
   // Use buildTaskPrompt to get the full verified-inventory context,
   // then prepend the idea so the spec generator also sees it.
   const contextBlock = buildTaskPrompt("", context).trim();
-  const fullPrompt = [idea, contextBlock].filter(Boolean).join("\n\n");
+
+  const parts: string[] = [idea];
+  if (architectureDecision) {
+    parts.push(
+      `\n=== Architecture Decision (MUST follow this approach in the spec) ===\n${architectureDecision}`
+    );
+  }
+  if (contextBlock) parts.push(contextBlock);
+  const fullPrompt = parts.join("\n\n");
 
   const combinedSystemPrompt = specPrompt + tasksInstruction;
   const raw = await provider.generate(fullPrompt, combinedSystemPrompt);

package/core/dashboard-generator.ts

@@ -0,0 +1,340 @@
+import { RunLog } from "./run-logger";
+import { buildTrendReport } from "./run-trend";
+import { computePromptHash } from "./prompt-hasher";
+
+// ─── SVG chart helpers ────────────────────────────────────────────────────────
+
+function scoreColor(score: number): string {
+  if (score >= 8) return "#22c55e"; // green
+  if (score >= 6) return "#f59e0b"; // amber
+  return "#ef4444";                  // red
+}
+
+function renderSparkline(scores: number[], width = 400, height = 60): string {
+  if (scores.length < 2) return `<svg width="${width}" height="${height}"></svg>`;
+  const pad = 6;
+  const w = width - pad * 2;
+  const h = height - pad * 2;
+  const max = Math.max(...scores, 10);
+  const min = Math.min(...scores, 0);
+  const range = max - min || 1;
+
+  const points = scores.map((s, i) => {
+    const x = pad + (i / (scores.length - 1)) * w;
+    const y = pad + h - ((s - min) / range) * h;
+    return `${x.toFixed(1)},${y.toFixed(1)}`;
+  });
+
+  const lastX = parseFloat(points[points.length - 1].split(",")[0]);
+  const lastY = parseFloat(points[points.length - 1].split(",")[1]);
+  const lastScore = scores[scores.length - 1];
+
+  return `<svg width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" xmlns="http://www.w3.org/2000/svg">
+    <polyline points="${points.join(" ")}" fill="none" stroke="${scoreColor(lastScore)}" stroke-width="2" stroke-linejoin="round"/>
+    <circle cx="${lastX}" cy="${lastY}" r="3" fill="${scoreColor(lastScore)}"/>
+  </svg>`;
+}
+
+function renderBarChart(
+  entries: { label: string; value: number; color?: string }[],
+  maxWidth = 280
+): string {
+  const maxVal = Math.max(...entries.map((e) => e.value), 1);
+  const rows = entries
+    .map((e) => {
+      const pct = (e.value / maxVal) * maxWidth;
+      const color = e.color ?? "#6366f1";
+      return `
+        <div style="display:flex;align-items:center;gap:8px;margin:4px 0">
+          <div style="width:110px;font-size:11px;color:#94a3b8;text-align:right;flex-shrink:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap" title="${e.label}">${e.label}</div>
+          <div style="height:14px;width:${pct.toFixed(0)}px;background:${color};border-radius:2px;min-width:2px"></div>
+          <div style="font-size:11px;color:#e2e8f0">${e.value.toFixed(1)}</div>
+        </div>`;
+    })
+    .join("");
+  return `<div style="margin:0">${rows}</div>`;
+}
+
+// ─── Data preparation ─────────────────────────────────────────────────────────
+
+interface DashboardData {
+  totalRuns: number;
+  scoredRuns: number;
+  avgScore: number | null;
+  compilePassRate: number | null;
+  currentPromptHash: string;
+  recentScores: { runId: string; date: string; score: number; hash: string }[];
+  promptGroups: { hash: string; runs: number; avg: number; best: number; worst: number; isCurrent: boolean }[];
+  stageDurations: { stage: string; avgMs: number }[];
+  topErrors: { message: string; count: number }[];
+  lastRunAt: string | null;
+}
+
+function prepareDashboardData(logs: RunLog[]): DashboardData {
+  const currentHash = computePromptHash();
+  const report = buildTrendReport(logs, { last: 50 });
+
+  // Recent scored runs (last 30)
+  const recentScores = logs
+    .filter((l) => l.harnessScore !== undefined)
+    .slice(0, 30)
+    .reverse()
+    .map((l) => ({
+      runId: l.runId,
+      date: l.startedAt.slice(0, 10),
+      score: l.harnessScore!,
+      hash: l.promptHash ?? "(no hash)",
+    }));
+
+  // Stage duration aggregation
+  const stageAccum: Record<string, { total: number; count: number }> = {};
+  for (const log of logs.slice(0, 20)) {
+    const stages: Record<string, number> = {};
+    for (const entry of log.entries ?? []) {
+      if (entry.event.endsWith(":done") || entry.event.endsWith(":failed")) {
+        const stageName = entry.event.replace(/:done$|:failed$/, "");
+        const ms = entry.data?.durationMs;
+        if (typeof ms === "number") stages[stageName] = ms;
+      }
+    }
+    for (const [stage, ms] of Object.entries(stages)) {
+      if (!stageAccum[stage]) stageAccum[stage] = { total: 0, count: 0 };
+      stageAccum[stage].total += ms;
+      stageAccum[stage].count++;
+    }
+  }
+  const stageDurations = Object.entries(stageAccum)
+    .map(([stage, { total, count }]) => ({ stage, avgMs: total / count }))
+    .sort((a, b) => b.avgMs - a.avgMs)
+    .slice(0, 8);
+
+  // Top errors
+  const errorCounts: Record<string, number> = {};
+  for (const log of logs) {
+    for (const err of log.errors ?? []) {
+      const key = err.slice(0, 80);
+      errorCounts[key] = (errorCounts[key] ?? 0) + 1;
+    }
+  }
+  const topErrors = Object.entries(errorCounts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 5)
+    .map(([message, count]) => ({ message, count }));
+
+  // Compile pass rate (from error_feedback stage)
+  let compilePassed = 0, compileTotal = 0;
+  for (const log of logs) {
+    const feedback = log.entries?.find((e) => e.event === "error_feedback:done" || e.event === "error_feedback:failed");
+    if (feedback) {
+      compileTotal++;
+      if (feedback.event.endsWith(":done")) compilePassed++;
+    }
+  }
+
+  const scoredLogs = logs.filter((l) => l.harnessScore !== undefined);
+  const avgScore = scoredLogs.length > 0
+    ? scoredLogs.reduce((s, l) => s + l.harnessScore!, 0) / scoredLogs.length
+    : null;
+
+  return {
+    totalRuns: logs.length,
+    scoredRuns: scoredLogs.length,
+    avgScore,
+    compilePassRate: compileTotal > 0 ? compilePassed / compileTotal : null,
+    currentPromptHash: currentHash,
+    recentScores,
+    promptGroups: report.promptGroups.map((g) => ({
+      hash: g.promptHash,
+      runs: g.runs,
+      avg: g.avg,
+      best: g.best,
+      worst: g.worst,
+      isCurrent: g.isCurrent,
+    })),
+    stageDurations,
+    topErrors,
+    lastRunAt: logs[0]?.startedAt ?? null,
+  };
+}
+
+// ─── HTML renderer ────────────────────────────────────────────────────────────
+
+function renderHtml(data: DashboardData, generatedAt: string, totalLogsAnalyzed: number): string {
+  const sparkline = renderSparkline(data.recentScores.map((r) => r.score));
+
+  const stageBar = renderBarChart(
+    data.stageDurations.map((s) => ({
+      label: s.stage.replace(/_/g, " "),
+      value: Math.round(s.avgMs / 100) / 10, // seconds
+      color: "#6366f1",
+    })),
+    240
+  );
+
+  const promptRows = data.promptGroups
+    .map((g) => {
+      const isCurrent = g.isCurrent;
+      const badge = isCurrent ? `<span style="background:#4f46e5;color:#fff;font-size:9px;padding:1px 6px;border-radius:9px;margin-left:6px">current</span>` : "";
+      const avgColor = scoreColor(g.avg);
+      return `<tr style="${isCurrent ? "background:#1e1b4b" : ""}">
+        <td style="font-family:monospace;font-size:12px;color:#a5b4fc">${g.hash}${badge}</td>
+        <td style="text-align:center;color:#94a3b8">${g.runs}</td>
+        <td style="text-align:center;color:${avgColor};font-weight:600">${g.avg.toFixed(1)}</td>
+        <td style="text-align:center;color:#22c55e">${g.best.toFixed(1)}</td>
+        <td style="text-align:center;color:#ef4444">${g.worst.toFixed(1)}</td>
+      </tr>`;
+    })
+    .join("");
+
+  const recentRows = data.recentScores
+    .slice()
+    .reverse()
+    .slice(-10)
+    .map((r) => {
+      const color = scoreColor(r.score);
+      const bar = "█".repeat(Math.round(r.score)) + "░".repeat(10 - Math.round(r.score));
+      return `<tr>
+        <td style="font-family:monospace;font-size:11px;color:#64748b">${r.date}</td>
+        <td style="font-family:monospace;font-size:11px;color:#94a3b8">${r.runId.slice(-12)}</td>
+        <td style="color:${color};font-size:12px;font-family:monospace">${bar}</td>
+        <td style="text-align:right;color:${color};font-weight:600">${r.score.toFixed(1)}</td>
+      </tr>`;
+    })
+    .join("");
+
+  const avgDisplay = data.avgScore !== null
+    ? `<span style="color:${scoreColor(data.avgScore)}">${data.avgScore.toFixed(1)}</span>`
+    : `<span style="color:#475569">—</span>`;
+
+  const compileDisplay = data.compilePassRate !== null
+    ? `<span style="color:${data.compilePassRate >= 0.8 ? "#22c55e" : "#f59e0b"}">${Math.round(data.compilePassRate * 100)}%</span>`
+    : `<span style="color:#475569">—</span>`;
+
+  const errorRows = data.topErrors.length > 0
+    ? data.topErrors.map((e) =>
+        `<div style="display:flex;gap:8px;align-items:flex-start;margin:4px 0">
+          <span style="color:#ef4444;font-weight:600;flex-shrink:0">${e.count}×</span>
+          <span style="color:#94a3b8;font-size:11px;font-family:monospace;word-break:break-all">${e.message.replace(/</g, "&lt;")}</span>
+        </div>`
+      ).join("")
+    : `<div style="color:#475569;font-size:12px">No errors recorded</div>`;
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>ai-spec Harness Dashboard</title>
+<style>
+  *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+  body { background: #0f172a; color: #e2e8f0; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif; font-size: 14px; line-height: 1.5; }
+  .header { background: #1e293b; border-bottom: 1px solid #334155; padding: 16px 24px; display: flex; align-items: center; justify-content: space-between; }
+  .header h1 { font-size: 16px; font-weight: 600; color: #f1f5f9; }
+  .header .meta { font-size: 11px; color: #475569; }
+  .grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 16px; padding: 20px 24px; }
+  .card { background: #1e293b; border: 1px solid #334155; border-radius: 8px; padding: 16px; }
+  .card h2 { font-size: 11px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.08em; color: #64748b; margin-bottom: 12px; }
+  .stat-row { display: flex; gap: 24px; flex-wrap: wrap; }
+  .stat { text-align: center; }
+  .stat .value { font-size: 28px; font-weight: 700; line-height: 1; }
+  .stat .label { font-size: 11px; color: #64748b; margin-top: 4px; }
+  table { width: 100%; border-collapse: collapse; }
+  th { font-size: 10px; text-transform: uppercase; letter-spacing: 0.05em; color: #475569; padding: 4px 8px; text-align: left; border-bottom: 1px solid #334155; }
+  td { padding: 6px 8px; border-bottom: 1px solid #1e293b; }
+  tr:last-child td { border-bottom: none; }
+  .sparkline-wrap { margin: 8px 0; }
+  .full { grid-column: 1 / -1; }
+</style>
+</head>
+<body>
+<div class="header">
+  <h1>ai-spec · Harness Dashboard</h1>
+  <div class="meta">Generated ${generatedAt} · Current prompt: <code style="color:#a5b4fc">${data.currentPromptHash}</code></div>
+</div>
+
+<div class="grid">
+
+  <!-- Overview stats -->
+  <div class="card">
+    <h2>Overview</h2>
+    <div class="stat-row">
+      <div class="stat">
+        <div class="value" style="color:#e2e8f0">${data.totalRuns}</div>
+        <div class="label">Total Runs</div>
+      </div>
+      <div class="stat">
+        <div class="value">${avgDisplay}</div>
+        <div class="label">Avg Score</div>
+      </div>
+      <div class="stat">
+        <div class="value">${compileDisplay}</div>
+        <div class="label">Compile Pass</div>
+      </div>
+      <div class="stat">
+        <div class="value" style="color:#e2e8f0">${data.scoredRuns}</div>
+        <div class="label">Scored Runs</div>
+      </div>
+    </div>
+  </div>
+
+  <!-- Score trend sparkline -->
+  <div class="card">
+    <h2>Score Trend (last ${data.recentScores.length} runs)</h2>
+    <div class="sparkline-wrap">${sparkline}</div>
+    ${data.recentScores.length === 0 ? '<div style="color:#475569;font-size:12px">No scored runs yet</div>' : ""}
+  </div>
+
+  <!-- Prompt version comparison -->
+  <div class="card full">
+    <h2>Prompt Version Performance</h2>
+    ${data.promptGroups.length === 0
+      ? '<div style="color:#475569;font-size:12px">No runs with prompt hash yet</div>'
+      : `<table>
+      <thead><tr>
+        <th>Prompt Hash</th>
+        <th style="text-align:center">Runs</th>
+        <th style="text-align:center">Avg</th>
+        <th style="text-align:center">Best</th>
+        <th style="text-align:center">Worst</th>
+      </tr></thead>
+      <tbody>${promptRows}</tbody>
+    </table>`}
+  </div>
+
+  <!-- Recent run history -->
+  <div class="card">
+    <h2>Recent Runs</h2>
+    ${data.recentScores.length === 0
+      ? '<div style="color:#475569;font-size:12px">No scored runs yet</div>'
+      : `<table>
+      <thead><tr><th>Date</th><th>Run ID</th><th>Score</th><th style="text-align:right">/10</th></tr></thead>
+      <tbody>${recentRows}</tbody>
+    </table>`}
+  </div>
+
+  <!-- Stage durations -->
+  <div class="card">
+    <h2>Avg Stage Duration (seconds)</h2>
+    ${data.stageDurations.length === 0
+      ? '<div style="color:#475569;font-size:12px">No stage data yet</div>'
+      : stageBar}
+  </div>
+
+  <!-- Top errors -->
+  <div class="card">
+    <h2>Top Errors (last ${Math.min(totalLogsAnalyzed, 20)} runs)</h2>
+    ${errorRows}
+  </div>
+
+</div>
+</body>
+</html>`;
+}
+
+// ─── Public API ───────────────────────────────────────────────────────────────
+
+export function generateDashboard(logs: RunLog[]): string {
+  const data = prepareDashboardData(logs);
+  const generatedAt = new Date().toISOString().replace("T", " ").slice(0, 19) + " UTC";
+  return renderHtml(data, generatedAt, logs.length);
+}

package/core/design-dialogue.ts

@@ -0,0 +1,124 @@
+/**
+ * design-dialogue.ts — Pre-spec architectural option proposal.
+ *
+ * Inspired by Superpowers' brainstorming phase: before writing a full spec,
+ * present 2-3 distinct architectural approaches with trade-offs and let the
+ * developer choose. The chosen approach is then injected into the spec prompt
+ * as a binding architectural decision, preventing mid-spec drift.
+ *
+ * Skipped in --fast and --auto modes.
+ */
+
+import { select } from "@inquirer/prompts";
+import chalk from "chalk";
+import { AIProvider } from "./spec-generator";
+import { buildDesignOptionsPrompt, designOptionsSystemPrompt } from "../prompts/design.prompt";
+
+export interface DesignChoice {
+  /** The full AI-generated options text, displayed to the user */
+  optionsText: string;
+  /**
+   * The selected approach label + description, injected into the spec prompt.
+   * e.g. "Option B — Event-driven approach: ..."
+   * null = user skipped the dialogue
+   */
+  selectedApproach: string | null;
+}
+
+export class DesignDialogue {
+  constructor(private provider: AIProvider) {}
+
+  async run(
+    idea: string,
+    contextHints: { techStack: string[]; repoType: string; constitution?: string }
+  ): Promise<DesignChoice> {
+    console.log(chalk.blue("\n[1.5/6] Design options..."));
+    console.log(
+      chalk.gray(`  Proposing architectural approaches with ${this.provider.providerName}/${this.provider.modelName}...`)
+    );
+
+    const prompt = buildDesignOptionsPrompt(idea, contextHints);
+    let optionsText: string;
+
+    try {
+      optionsText = await this.provider.generate(prompt, designOptionsSystemPrompt);
+    } catch (err) {
+      console.log(chalk.yellow(`  ⚠ Design options failed (${(err as Error).message}), skipping.`));
+      return { optionsText: "", selectedApproach: null };
+    }
+
+    // Display the options
+    console.log(chalk.cyan("\n" + "─".repeat(52)));
+    console.log(optionsText);
+    console.log(chalk.cyan("─".repeat(52) + "\n"));
+
+    // Parse option labels from the text (Option A / B / C)
+    const optionMatches = [...optionsText.matchAll(/###\s+(Option\s+[A-C][^:\n]*)/gi)];
+    const parsedOptions = optionMatches.map((m) => m[1].trim());
+
+    // Build choices for the select prompt
+    const choices: Array<{ name: string; value: string }> = parsedOptions.map((label) => ({
+      name: label,
+      value: label,
+    }));
+
+    choices.push(
+      { name: "🔀  Blend — let AI combine the best of all options", value: "__blend__" },
+      { name: "⏭️   Skip — proceed to spec without an architecture decision", value: "__skip__" }
+    );
+
+    const selected = await select({
+      message: "Which approach should the spec follow?",
+      choices,
+    });
+
+    if (selected === "__skip__") {
+      console.log(chalk.gray("  Architecture decision skipped — spec will be generated freely."));
+      return { optionsText, selectedApproach: null };
+    }
+
+    if (selected === "__blend__") {
+      console.log(chalk.blue("  Blending approaches..."));
+      try {
+        const blendPrompt = `The developer wants to blend the best aspects of all options below.
+Write a single-paragraph architectural decision that combines their strengths.
+Output ONLY the blended approach description (2-4 sentences, no headers).
+
+${optionsText}`;
+        const blended = await this.provider.generate(
+          blendPrompt,
+          "You are a Senior Architect. Output only the blended architectural approach, 2-4 sentences."
+        );
+        const blendedApproach = `Blended approach: ${blended.trim()}`;
+        console.log(chalk.cyan(`\n  Selected: ${blendedApproach.slice(0, 80)}...`));
+        return { optionsText, selectedApproach: blendedApproach };
+      } catch {
+        console.log(chalk.yellow("  Blend failed, proceeding without architecture decision."));
+        return { optionsText, selectedApproach: null };
+      }
+    }
+
+    // Find the full description of the selected option
+    const selectedIdx = parsedOptions.indexOf(selected);
+    let selectedApproach = selected;
+
+    if (selectedIdx !== -1 && selectedIdx < parsedOptions.length - 1) {
+      // Extract text between this option header and the next
+      const startMarker = `### ${parsedOptions[selectedIdx]}`;
+      const endMarker = selectedIdx + 1 < parsedOptions.length
+        ? `### ${parsedOptions[selectedIdx + 1]}`
+        : "---";
+      const start = optionsText.indexOf(startMarker);
+      const end = optionsText.indexOf(endMarker, start + 1);
+      if (start !== -1) {
+        const excerpt = end !== -1
+          ? optionsText.slice(start, end).trim()
+          : optionsText.slice(start).trim();
+        selectedApproach = excerpt.slice(0, 400); // cap to avoid bloating spec prompt
+      }
+    }
+
+    console.log(chalk.green(`  ✔ Architecture decision locked: ${selected}`));
+    return { optionsText, selectedApproach };
+  }
+}