@karajan-family/code 4.21.0

package/src/orchestrator/stages/hu-reviewer-stage.js

@@ -0,0 +1,394 @@
+/**
+ * HU Reviewer stage logic + splitting logic.
+ * Extracted from pre-loop-stages.js for maintainability.
+ */
+
+import { DiscoverRole } from "../../roles/discover-role.js";
+import { HuReviewerRole } from "../../roles/hu-reviewer-role.js";
+import { createAgent } from "../../agents/index.js";
+import { addCheckpoint } from "../../session/store.js";
+import { emitProgress, makeEvent } from "../../utils/events.js";
+import { buildDecompositionPrompt, parseDecompositionOutput } from "../../prompts/hu-reviewer.js";
+import { createStallDetector } from "../../utils/stall-detector.js";
+import { createHuBatch, loadHuBatch, saveHuBatch, updateStoryStatus, updateStoryQuality, updateStoryCertified, addContextRequest, answerContextRequest } from "../../hu/store.js";
+import { topologicalSort } from "../../hu/graph.js";
+import { detectAndApplySplits } from "./hu-reviewer-phases/detect-and-apply-splits.js";
+
+/**
+ * Use an AI agent to decompose a complex task into multiple formal HUs.
+ * Returns null if decomposition fails or the task is too simple.
+ */
+async function decomposeTaskIntoHUs({ config, logger, emitter, eventBase, session, coderRole, trackBudget }) {
+  const provider = config?.roles?.hu_reviewer?.provider || coderRole.provider;
+  const prompt = buildDecompositionPrompt(session.task);
+
+  emitProgress(
+    emitter,
+    makeEvent("hu-reviewer:decompose-start", { ...eventBase, stage: "hu-reviewer" }, {
+      message: "Decomposing complex task into formal HUs",
+      detail: { provider }
+    })
+  );
+
+  const onOutput = ({ stream, line }) => {
+    emitProgress(emitter, makeEvent("agent:output", { ...eventBase, stage: "hu-reviewer" }, {
+      message: line,
+      detail: { stream, agent: provider }
+    }));
+  };
+  const stall = createStallDetector({
+    onOutput, emitter, eventBase, stage: "hu-reviewer", provider
+  });
+
+  const agent = createAgent(provider, config, logger);
+  const decompStart = Date.now();
+  let result;
+  try {
+    result = await agent.runTask({ prompt, role: "hu-reviewer", onOutput: stall.onOutput });
+  } catch (err) {
+    logger.warn(`HU decomposition threw: ${err.message}`);
+    return null;
+  } finally {
+    stall.stop();
+  }
+
+  trackBudget({
+    role: "hu-reviewer-decompose",
+    provider,
+    model: config?.roles?.hu_reviewer?.model || coderRole.model,
+    result,
+    duration_ms: Date.now() - decompStart
+  });
+
+  if (!result.ok) {
+    logger.warn(`HU decomposition failed: ${result.error || "unknown"}`);
+    return null;
+  }
+
+  const stories = parseDecompositionOutput(result.output);
+  if (!stories || stories.length < 2) {
+    logger.info("HU decomposition returned < 2 stories, falling back to single auto-story");
+    return null;
+  }
+
+  emitProgress(
+    emitter,
+    makeEvent("hu-reviewer:decompose-end", { ...eventBase, stage: "hu-reviewer" }, {
+      message: `Task decomposed into ${stories.length} HUs`,
+      detail: { count: stories.length, ids: stories.map(s => s.id) }
+    })
+  );
+
+  return stories;
+}
+
+export async function runDiscoverStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget }) {
+  logger.setContext({ iteration: 0, stage: "discover" });
+  const discoverProvider = config?.roles?.discover?.provider || coderRole.provider;
+  emitProgress(
+    emitter,
+    makeEvent("discover:start", { ...eventBase, stage: "discover" }, {
+      message: "Discover analyzing task for gaps",
+      detail: { discover: discoverProvider, provider: discoverProvider, executorType: "agent" }
+    })
+  );
+  const discoverOnOutput = ({ stream, line }) => {
+    emitProgress(emitter, makeEvent("agent:output", { ...eventBase, stage: "discover" }, {
+      message: line,
+      detail: { stream, agent: discoverProvider }
+    }));
+  };
+  const discoverStall = createStallDetector({
+    onOutput: discoverOnOutput, emitter, eventBase, stage: "discover", provider: discoverProvider
+  });
+
+  const mode = config?.pipeline?.discover?.mode || "gaps";
+  const discover = new DiscoverRole({ config, logger, emitter });
+  await discover.init({ task: session.task, sessionId: session.id, iteration: 0 });
+  const discoverStart = Date.now();
+  let discoverOutput;
+  try {
+    discoverOutput = await discover.run({ task: session.task, mode, onOutput: discoverStall.onOutput });
+  } catch (err) {
+    logger.warn(`Discover threw: ${err.message}`);
+    discoverOutput = { ok: false, summary: `Discover error: ${err.message}`, result: { error: err.message } };
+  } finally {
+    discoverStall.stop();
+  }
+  trackBudget({
+    role: "discover",
+    provider: discoverProvider,
+    model: config?.roles?.discover?.model || coderRole.model,
+    result: discoverOutput,
+    duration_ms: Date.now() - discoverStart
+  });
+
+  await addCheckpoint(session, {
+    stage: "discover",
+    iteration: 0,
+    ok: discoverOutput.ok,
+    provider: discoverProvider,
+    model: config?.roles?.discover?.model || coderRole.model || null
+  });
+
+  const stageResult = {
+    ok: discoverOutput.ok,
+    verdict: discoverOutput.result?.verdict || null,
+    gaps: discoverOutput.result?.gaps || [],
+    mode
+  };
+
+  emitProgress(
+    emitter,
+    makeEvent("discover:end", { ...eventBase, stage: "discover" }, {
+      status: discoverOutput.ok ? "ok" : "fail",
+      message: discoverOutput.ok ? "Discovery completed" : `Discovery failed: ${discoverOutput.summary}`,
+      detail: { ...stageResult, provider: discoverProvider, executorType: "agent" }
+    })
+  );
+
+  return { stageResult };
+}
+
+/**
+ * Run the HU Reviewer stage: load stories from YAML or generate from task, evaluate, certify, and return in topological order.
+ */
+export async function runHuReviewerStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget, huFile, askQuestion, pgStories = null }) {
+  logger.setContext({ iteration: 0, stage: "hu-reviewer" });
+  const huReviewerProvider = config?.roles?.hu_reviewer?.provider || coderRole.provider;
+  emitProgress(
+    emitter,
+    makeEvent("hu-reviewer:start", { ...eventBase, stage: "hu-reviewer" }, {
+      message: "HU Reviewer certifying user stories",
+      detail: { provider: huReviewerProvider, executorType: "agent" }
+    })
+  );
+
+  let stories;
+
+  if (huFile) {
+    // --- Load YAML file ---
+    const yaml = await import("js-yaml");
+    const fs = await import("node:fs/promises");
+    let rawYaml;
+    try {
+      rawYaml = await fs.readFile(huFile, "utf8");
+    } catch (err) {
+      const stageResult = { ok: false, error: `Could not read HU file: ${err.message}` };
+      emitProgress(emitter, makeEvent("hu-reviewer:end", { ...eventBase, stage: "hu-reviewer" }, {
+        status: "fail", message: stageResult.error
+      }));
+      return { stageResult };
+    }
+
+    try {
+      const parsed = yaml.load(rawYaml);
+      stories = Array.isArray(parsed) ? parsed : (parsed?.stories || []);
+    } catch (err) {
+      const stageResult = { ok: false, error: `Invalid YAML in HU file: ${err.message}` };
+      emitProgress(emitter, makeEvent("hu-reviewer:end", { ...eventBase, stage: "hu-reviewer" }, {
+        status: "fail", message: stageResult.error
+      }));
+      return { stageResult };
+    }
+  } else if (pgStories && pgStories.length > 0) {
+    // --- Use pre-built stories from Planning Game card structured data ---
+    stories = pgStories;
+    logger.info(`HU Reviewer: using ${pgStories.length} story(ies) from PG card`);
+    emitProgress(emitter, makeEvent("hu-reviewer:pg-feed", { ...eventBase, stage: "hu-reviewer" }, {
+      message: `Using ${pgStories.length} story(ies) from Planning Game card`,
+      detail: { source: "pg-card", storyIds: pgStories.map(s => s.id) }
+    }));
+  } else {
+    // --- Decompose task into formal HUs via AI, or fall back to single auto-story ---
+    const decomposed = await decomposeTaskIntoHUs({
+      config, logger, emitter, eventBase, session, coderRole, trackBudget
+    });
+    if (decomposed && decomposed.length > 1) {
+      stories = decomposed.map((hu, idx) => {
+        const isFirst = idx === 0;
+        const fullText = `As a ${hu.role}, I want to ${hu.goal}, so that ${hu.benefit}\n\nTitle: ${hu.title}\nAcceptance Criteria:\n${hu.acceptanceCriteria.map(ac => `- ${ac}`).join("\n")}`;
+        const skeletonText = `As a ${hu.role}, I want to ${hu.goal}, so that ${hu.benefit}\n\nTitle: ${hu.title}`;
+        return {
+          id: hu.id,
+          text: isFirst ? fullText : skeletonText,
+          blocked_by: hu.dependsOn || [],
+          needsRefinement: !isFirst
+        };
+      });
+    } else {
+      stories = [{ id: "HU-AUTO-001", text: session.task }];
+    }
+  }
+
+  if (stories.length === 0) {
+    const stageResult = { ok: true, certified: 0, stories: [] };
+    emitProgress(emitter, makeEvent("hu-reviewer:end", { ...eventBase, stage: "hu-reviewer" }, {
+      status: "ok", message: "No stories to evaluate"
+    }));
+    return { stageResult };
+  }
+
+  // --- Create or load batch ---
+  const batchSessionId = `hu-${session.id}`;
+  let batch;
+  try {
+    batch = await loadHuBatch(batchSessionId);
+  } catch { /* no existing batch */
+    batch = await createHuBatch(batchSessionId, stories);
+  }
+
+  // --- Splitting detection: extracted to hu-reviewer-phases/detect-and-apply-splits.js (PR-M) ---
+  await detectAndApplySplits({
+    batch, batchSessionId, askQuestion, config, logger, emitter, eventBase,
+  });
+
+
+  // --- Evaluate loop (re-evaluate entire batch until all certified or needs_context with no askQuestion) ---
+  const huReviewerOnOutput = ({ stream, line }) => {
+    emitProgress(emitter, makeEvent("agent:output", { ...eventBase, stage: "hu-reviewer" }, {
+      message: line,
+      detail: { stream, agent: huReviewerProvider }
+    }));
+  };
+
+  let maxRounds = 5;
+  let round = 0;
+
+  while (round < maxRounds) {
+    round += 1;
+
+    const pendingStories = batch.stories.filter(s => s.status === "pending" || s.status === "needs_context");
+    if (pendingStories.length === 0) break;
+
+    const storiesToEvaluate = pendingStories.map(s => ({ id: s.id, text: s.original.text }));
+
+    const stall = createStallDetector({
+      onOutput: huReviewerOnOutput, emitter, eventBase, stage: "hu-reviewer", provider: huReviewerProvider
+    });
+
+    const huReviewer = new HuReviewerRole({ config, logger, emitter, createAgentFn: createAgent });
+    await huReviewer.init({ task: session.task, sessionId: session.id, iteration: 0 });
+    const reviewStart = Date.now();
+    let reviewOutput;
+    try {
+      reviewOutput = await huReviewer.run({ stories: storiesToEvaluate, onOutput: stall.onOutput });
+    } catch (err) {
+      logger.warn(`HU Reviewer threw: ${err.message}`);
+      reviewOutput = { ok: false, summary: `HU Reviewer error: ${err.message}`, result: { error: err.message } };
+    } finally {
+      stall.stop();
+    }
+
+    trackBudget({
+      role: "hu-reviewer",
+      provider: huReviewerProvider,
+      model: config?.roles?.hu_reviewer?.model || coderRole.model,
+      result: reviewOutput,
+      duration_ms: Date.now() - reviewStart
+    });
+
+    if (!reviewOutput.ok || !reviewOutput.result?.evaluations) {
+      break;
+    }
+
+    // --- Process evaluations ---
+    for (const evaluation of reviewOutput.result.evaluations) {
+      const storyId = evaluation.story_id;
+      try {
+        updateStoryQuality(batch, storyId, evaluation.scores);
+      } catch {
+        continue; // story not found in batch, skip
+      }
+
+      if (evaluation.verdict === "certified") {
+        updateStoryCertified(batch, storyId, evaluation.certified_hu);
+      } else if (evaluation.verdict === "needs_context" && evaluation.context_needed) {
+        addContextRequest(batch, storyId, {
+          fields_needed: evaluation.context_needed.fields_needed || [],
+          question: evaluation.context_needed.question_to_fde || ""
+        });
+      } else if (evaluation.verdict === "needs_rewrite" && evaluation.rewritten) {
+        // Accept the rewrite and re-certify
+        updateStoryCertified(batch, storyId, evaluation.rewritten);
+      } else {
+        updateStoryStatus(batch, storyId, "pending");
+      }
+    }
+
+    await saveHuBatch(batchSessionId, batch);
+
+    // --- Check if any need context ---
+    const needsContext = batch.stories.filter(s => s.status === "needs_context");
+    if (needsContext.length > 0) {
+      const consolidatedQuestions = reviewOutput.result.batch_summary?.consolidated_questions
+        || needsContext.map(s => {
+          const pending = s.context_requests.find(r => !r.answered_at);
+          return pending ? `[${s.id}] ${pending.question_to_fde}` : null;
+        }).filter(Boolean).join("\n");
+
+      if (!askQuestion) {
+        // No interactive input — pause session
+        break;
+      }
+
+      emitProgress(emitter, makeEvent("hu-reviewer:needs-context", { ...eventBase, stage: "hu-reviewer" }, {
+        message: `${needsContext.length} story(ies) need context from FDE`,
+        detail: { questions: consolidatedQuestions }
+      }));
+
+      const answer = await askQuestion(
+        `The HU Reviewer needs additional context:\n\n${consolidatedQuestions}\n\nPlease provide your answers:`,
+        { iteration: 0, stage: "hu-reviewer" }
+      );
+
+      if (!answer) break;
+
+      // --- Incorporate FDE answers and re-evaluate ---
+      for (const s of needsContext) {
+        answerContextRequest(batch, s.id, answer);
+      }
+      await saveHuBatch(batchSessionId, batch);
+      // Loop will re-evaluate entire batch
+    }
+  }
+
+  await addCheckpoint(session, {
+    stage: "hu-reviewer",
+    iteration: 0,
+    ok: true,
+    certified: batch.stories.filter(s => s.status === "certified").length,
+    total: batch.stories.length
+  });
+
+  // --- Return certified stories in topological order ---
+  const certifiedStories = batch.stories.filter(s => s.status === "certified");
+  let orderedIds;
+  try {
+    orderedIds = topologicalSort(certifiedStories);
+  } catch { /* cyclic dependency */
+    orderedIds = certifiedStories.map(s => s.id);
+  }
+
+  const orderedStories = orderedIds.map(id => batch.stories.find(s => s.id === id)).filter(Boolean);
+
+  const stageResult = {
+    ok: true,
+    certified: certifiedStories.length,
+    total: batch.stories.length,
+    needsContext: batch.stories.filter(s => s.status === "needs_context").length,
+    stories: orderedStories,
+    batchSessionId
+  };
+
+  emitProgress(
+    emitter,
+    makeEvent("hu-reviewer:end", { ...eventBase, stage: "hu-reviewer" }, {
+      status: "ok",
+      message: `HU Review complete: ${certifiedStories.length}/${batch.stories.length} certified`,
+      detail: { ...stageResult, provider: huReviewerProvider, executorType: "agent" }
+    })
+  );
+
+  return { stageResult };
+}

package/src/orchestrator/stages/perf-stage.js

@@ -0,0 +1,140 @@
+/**
+ * PerfStage — webperf quality gate inside the iteration loop.
+ *
+ * KJC-TSK-0151. Wraps PerfRole and slots into the existing
+ * runQualityGateStages flow alongside Sonar and Impeccable. Designed
+ * to be the simplest possible quality gate:
+ *
+ *   - PASS verdict (cwv.pass === true) → return ok, iteration continues.
+ *   - FAIL verdict → set reviewer feedback with the blocking metrics
+ *     so the coder receives concrete guidance next iteration. Returns
+ *     `continue` to retry the iteration loop. No repeat-detector +
+ *     retry-limit machinery: rerunning Lighthouse on the same URL
+ *     gives the same result unless the coder changes something, and
+ *     the iteration limit (max_iterations) is the natural ceiling.
+ *   - Scanner unavailable (lighthouse missing, URL unreachable, timeout)
+ *     → log a warn and return ok-skipped. Best-effort, never blocks
+ *     the pipeline by itself.
+ *
+ * The role surface (PerfRole) is responsible for persisting the result
+ * to ~/.karajan/webperf/<slug>/last.json so subsequent `kj audit` runs
+ * pick it up via the auto-discovery added in #602.
+ */
+
+import { PerfRole } from "../../roles/perf-role.js";
+import { setReviewerFeedback } from "../../session/mutators.js";
+import { saveSession } from "../../session/store.js";
+import { emitProgress, makeEvent } from "../../utils/events.js";
+
+/**
+ * Build the human-readable feedback line that goes back to the coder
+ * on FAIL. Concrete enough that the LLM can act on it without re-reading
+ * the whole report.
+ */
+function buildFeedback(roleResult) {
+  const { result } = roleResult;
+  const score = typeof result.performanceScore === "number" ? result.performanceScore : null;
+  const blocking = (result.cwv?.blocking || []).map(b => `${b.metric.toUpperCase()}=${Math.round(b.value)} (poor>${b.threshold})`);
+  const top = (result.issues || []).slice(0, 3).map(i => `${i.id}${i.savingsMs ? ` (~${Math.round(i.savingsMs)}ms)` : ""}`);
+
+  const lines = [`Webperf gate FAILED${score !== null ? ` (score ${score}/100)` : ""}.`];
+  if (blocking.length > 0) lines.push(`Blocking metrics: ${blocking.join(", ")}.`);
+  if (top.length > 0) lines.push(`Top opportunities: ${top.join(", ")}.`);
+  lines.push("Address the blocking metric(s) before the next iteration; rerunning without code changes will produce the same verdict.");
+  return lines.join(" ");
+}
+
+/**
+ * Run the perf gate against config.webperf.url.
+ *
+ * @returns {Promise<{action: "ok"|"continue", stageResult?: object, summary?: string}>}
+ */
+export async function runPerfStage({ config, logger, emitter, eventBase, session, trackBudget, iteration, task: _task, brainCtx }) {
+  if (!session) {
+    throw new Error("runPerfStage: `session` is required.");
+  }
+  logger.setContext({ iteration, stage: "perf" });
+  emitProgress(
+    emitter,
+    makeEvent("perf:start", { ...eventBase, stage: "perf" }, {
+      message: "WebPerf gate scanning",
+      detail: { url: config?.webperf?.url || null, preset: config?.webperf?.preset || "desktop" },
+    })
+  );
+
+  const role = new PerfRole({ config, logger, emitter });
+  const roleResult = await role.execute();
+
+  // Track budget — the role doesn't spawn an LLM but it does consume wall
+  // time; surface that in the budget summary alongside the agent calls.
+  if (trackBudget) {
+    try { trackBudget("perf", { tokens_in: 0, tokens_out: 0, cost_usd: 0 }); } catch { /* best-effort */ }
+  }
+
+  // Scanner unavailable → skip with warn. PerfRole returns ok=false for
+  // both "verdict FAIL" and "scanner failed", so we differentiate on the
+  // result.error field (set only by the second case).
+  if (!roleResult.ok && roleResult.result?.error) {
+    logger.warn(`Perf gate skipped: ${roleResult.result.error}`);
+    emitProgress(emitter, makeEvent("perf:end", { ...eventBase, stage: "perf" }, {
+      status: "warn",
+      message: `Perf gate skipped — ${roleResult.result.error}`,
+    }));
+    return { action: "ok", stageResult: { skipped: true, reason: roleResult.result.error } };
+  }
+
+  // PASS verdict
+  if (roleResult.ok === true) {
+    emitProgress(emitter, makeEvent("perf:end", { ...eventBase, stage: "perf" }, {
+      status: "ok",
+      message: roleResult.summary,
+    }));
+    return {
+      action: "ok",
+      stageResult: {
+        verdict: "PASS",
+        url: roleResult.result?.url,
+        performanceScore: roleResult.result?.performanceScore,
+        cwv: roleResult.result?.cwv,
+        savedPath: roleResult.result?.savedPath,
+        summary: roleResult.summary,
+      },
+    };
+  }
+
+  // FAIL verdict → push concrete feedback to the coder for next iteration.
+  const feedback = buildFeedback(roleResult);
+  setReviewerFeedback(session, feedback);
+  await saveSession(session);
+
+  // Brain: when enabled, surface perf feedback on the queue too.
+  if (brainCtx?.enabled) {
+    try {
+      const { processRoleOutput } = await import("../brain-coordinator.js");
+      processRoleOutput(brainCtx, {
+        roleName: "perf",
+        output: { verdict: "fail", summary: feedback },
+        iteration,
+      });
+    } catch (err) {
+      logger.warn(`Perf gate: brain queue push failed (non-blocking): ${err.message}`);
+    }
+  }
+
+  emitProgress(emitter, makeEvent("perf:end", { ...eventBase, stage: "perf" }, {
+    status: "fail",
+    message: roleResult.summary,
+  }));
+
+  return {
+    action: "continue",
+    stageResult: {
+      verdict: "FAIL",
+      url: roleResult.result?.url,
+      performanceScore: roleResult.result?.performanceScore,
+      cwv: roleResult.result?.cwv,
+      issues: roleResult.result?.issues,
+      summary: feedback,
+    },
+  };
+}

package/src/orchestrator/stages/planner-stage.js

@@ -0,0 +1,85 @@
+/**
+ * Planner stage logic.
+ * Extracted from pre-loop-stages.js for maintainability.
+ */
+
+import { PlannerRole } from "../../roles/planner-role.js";
+import { createAgent } from "../../agents/index.js";
+import { addCheckpoint, markSessionStatus } from "../../session/store.js";
+import { emitProgress, makeEvent, emitAgentOutput } from "../../utils/events.js";
+import { parsePlannerOutput } from "../../prompts/planner.js";
+import { createStallDetector } from "../../utils/stall-detector.js";
+
+export async function runPlannerStage({ config, logger, emitter, eventBase, session, plannerRole, researchContext, architectContext = null, triageDecomposition = null, trackBudget }) {
+  const task = session.task;
+  logger.setContext({ iteration: 0, stage: "planner" });
+  emitProgress(
+    emitter,
+    makeEvent("planner:start", { ...eventBase, stage: "planner" }, {
+      message: `Planner (${plannerRole.provider}) running`,
+      detail: { planner: plannerRole.provider, provider: plannerRole.provider, executorType: "agent" }
+    })
+  );
+
+  const plannerOnOutput = (payload) => emitAgentOutput(emitter, eventBase, "planner", plannerRole.provider, payload);
+  const plannerStall = createStallDetector({
+    onOutput: plannerOnOutput, emitter, eventBase, stage: "planner", provider: plannerRole.provider
+  });
+
+  const planRole = new PlannerRole({ config, logger, emitter, createAgentFn: createAgent });
+  planRole.context = { task, research: researchContext, architecture: architectContext, triageDecomposition };
+  await planRole.init();
+  const plannerStart = Date.now();
+  let planResult;
+  try {
+    planResult = await planRole.execute({ task, onOutput: plannerStall.onOutput });
+  } catch (err) {
+    logger.warn(`Planner threw: ${err.message}`);
+    planResult = { ok: false, result: { error: err.message }, summary: `Planner error: ${err.message}` };
+  } finally {
+    plannerStall.stop();
+  }
+  trackBudget({ role: "planner", provider: plannerRole.provider, model: plannerRole.model, result: planResult.result, duration_ms: Date.now() - plannerStart });
+  await addCheckpoint(session, {
+    stage: "planner",
+    iteration: 0,
+    ok: planResult.ok,
+    provider: plannerRole.provider,
+    model: plannerRole.model || null
+  });
+
+  if (!planResult.ok) {
+    await markSessionStatus(session, "failed");
+    const details = planResult.result?.error || planResult.summary || "unknown error";
+    emitProgress(
+      emitter,
+      makeEvent("planner:end", { ...eventBase, stage: "planner" }, {
+        status: "fail",
+        message: `Planner failed: ${details}`,
+        detail: { provider: plannerRole.provider, executorType: "agent" }
+      })
+    );
+    throw new Error(`Planner failed: ${details}`);
+  }
+
+  const planOutput = planResult.result?.plan || "";
+  const plannedTask = planOutput ? `${task}\n\nExecution plan:\n${planOutput}` : task;
+  const parsedPlan = parsePlannerOutput(planOutput);
+  const stageResult = {
+    ok: true,
+    title: parsedPlan?.title || null,
+    approach: parsedPlan?.approach || null,
+    steps: parsedPlan?.steps || [],
+    completedSteps: []
+  };
+
+  emitProgress(
+    emitter,
+    makeEvent("planner:end", { ...eventBase, stage: "planner" }, {
+      message: "Planner completed",
+      detail: { provider: plannerRole.provider, executorType: "agent" }
+    })
+  );
+
+  return { plannedTask, stageResult };
+}