karajan-code 1.29.1 → 1.31.0

package/src/commands/resume.js

@@ -1,10 +1,32 @@
 import { EventEmitter } from "node:events";
+import readline from "node:readline";
 import { resumeFlow } from "../orchestrator.js";
 import { createActivityLog } from "../activity-log.js";
 import { printEvent } from "../utils/display.js";
 
+function createCliAskQuestion() {
+  return async (question, context) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+      console.log(`\n\u2753 ${question}`);
+      if (context?.detail) {
+        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
+      }
+      rl.question("\n> Your response (or 'stop' to exit): ", (answer) => {
+        rl.close();
+        if (answer.trim().toLowerCase() === "stop") {
+          resolve(null);
+        } else {
+          resolve(answer.trim());
+        }
+      });
+    });
+  };
+}
+
 export async function resumeCommand({ sessionId, answer, config, logger, flags }) {
   const jsonMode = flags?.json;
+  const quietMode = config.output?.quiet !== false;
 
   const emitter = new EventEmitter();
   let activityLog = null;
@@ -20,17 +42,19 @@ export async function resumeCommand({ sessionId, answer, config, logger, flags }
     }
 
     if (!jsonMode) {
-      printEvent(event);
+      printEvent(event, { quiet: quietMode });
     }
   });
 
+  const askQuestion = createCliAskQuestion();
   const result = await resumeFlow({
     sessionId,
     answer: answer || null,
     config,
     logger,
     flags: flags || {},
-    emitter
+    emitter,
+    askQuestion
   });
 
   if (jsonMode || !answer) {

package/src/commands/run.js

@@ -1,4 +1,5 @@
 import { EventEmitter } from "node:events";
+import readline from "node:readline";
 import { runFlow } from "../orchestrator.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { createActivityLog } from "../activity-log.js";
@@ -6,6 +7,26 @@ import { printHeader, printEvent } from "../utils/display.js";
 import { resolveRole } from "../config.js";
 import { parseCardId } from "../planning-game/adapter.js";
 
+function createCliAskQuestion() {
+  return async (question, context) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+      console.log(`\n\u2753 ${question}`);
+      if (context?.detail) {
+        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
+      }
+      rl.question("\n> Your response (or 'stop' to exit): ", (answer) => {
+        rl.close();
+        if (answer.trim().toLowerCase() === "stop") {
+          resolve(null);
+        } else {
+          resolve(answer.trim());
+        }
+      });
+    });
+  };
+}
+
 export async function runCommandHandler({ task, config, logger, flags }) {
   // Best-effort session cleanup before starting
   try {
@@ -33,6 +54,8 @@ export async function runCommandHandler({ task, config, logger, flags }) {
   const pgProject = flags?.pgProject || config.planning_game?.project_id || null;
 
   const jsonMode = flags?.json;
+  // Quiet mode is the default; --verbose disables it
+  const quietMode = config.output?.quiet !== false;
 
   const emitter = new EventEmitter();
   let activityLog = null;
@@ -48,7 +71,7 @@ export async function runCommandHandler({ task, config, logger, flags }) {
     }
 
     if (!jsonMode) {
-      printEvent(event);
+      printEvent(event, { quiet: quietMode });
     }
   });
 
@@ -56,7 +79,8 @@ export async function runCommandHandler({ task, config, logger, flags }) {
     printHeader({ task: task, config });
   }
 
-  const result = await runFlow({ task: task, config, logger, flags, emitter, pgTaskId: pgCardId || null, pgProject: pgProject || null });
+  const askQuestion = createCliAskQuestion();
+  const result = await runFlow({ task: task, config, logger, flags, emitter, askQuestion, pgTaskId: pgCardId || null, pgProject: pgProject || null });
 
   if (jsonMode) {
     console.log(JSON.stringify(result, null, 2));

package/src/config.js

@@ -19,7 +19,8 @@ const DEFAULTS = {
     impeccable: { provider: null, model: null },
     triage: { provider: null, model: null },
     discover: { provider: null, model: null },
-    architect: { provider: null, model: null }
+    architect: { provider: null, model: null },
+    hu_reviewer: { provider: null, model: null }
   },
   pipeline: {
     planner: { enabled: false },
@@ -32,6 +33,7 @@ const DEFAULTS = {
     triage: { enabled: true },
     discover: { enabled: false },
     architect: { enabled: false },
+    hu_reviewer: { enabled: false },
     auto_simplify: true
   },
   review_mode: "standard",
@@ -121,7 +123,7 @@ const DEFAULTS = {
   planning_game: { enabled: false, project_id: null, codeveloper: null },
   becaria: { enabled: false, review_event: "becaria-review", comment_event: "becaria-comment", comment_prefix: true },
   git: { auto_commit: false, auto_push: false, auto_pr: false, auto_rebase: true, branch_prefix: "feat/" },
-  output: { report_dir: "./.reviews", log_level: "info" },
+  output: { report_dir: "./.reviews", log_level: "info", quiet: true },
   budget: {
     warn_threshold_pct: 80,
     currency: "usd",
@@ -281,7 +283,8 @@ const PIPELINE_ENABLE_FLAGS = [
   ["enableSolomon", "solomon"], ["enableResearcher", "researcher"],
   ["enableTester", "tester"], ["enableSecurity", "security"], ["enableImpeccable", "impeccable"],
   ["enableTriage", "triage"], ["enableDiscover", "discover"],
-  ["enableArchitect", "architect"]
+  ["enableArchitect", "architect"],
+  ["enableHuReviewer", "hu_reviewer"]
 ];
 
 const AUTO_SIMPLIFY_FLAG = "autoSimplify";
@@ -363,6 +366,17 @@ function applyBecariaOverride(out, flags) {
   }
 }
 
+function applyOutputModeOverrides(out, flags) {
+  out.output = out.output || {};
+  // --verbose explicitly overrides quiet
+  if (flags.verbose === true) {
+    out.output.quiet = false;
+  } else if (flags.quiet === true) {
+    out.output.quiet = true;
+  }
+  // quiet defaults to true (set in DEFAULTS)
+}
+
 function applyMiscOverrides(out, flags) {
   if (flags[AUTO_SIMPLIFY_FLAG] !== undefined) out.pipeline.auto_simplify = Boolean(flags[AUTO_SIMPLIFY_FLAG]);
   if (flags.noSonar || flags.sonar === false) out.sonarqube.enabled = false;
@@ -401,6 +415,7 @@ export function applyRunOverrides(config, flags) {
   applyMethodologyOverride(out, flags);
   applyBecariaOverride(out, flags);
   applyMiscOverrides(out, flags);
+  applyOutputModeOverrides(out, flags);
 
   return out;
 }
@@ -414,14 +429,14 @@ export function resolveRole(config, role) {
   let provider = roleConfig.provider ?? null;
   if (!provider && role === "coder") provider = legacyCoder;
   if (!provider && role === "reviewer") provider = legacyReviewer;
-  if (!provider && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "impeccable" || role === "triage" || role === "discover" || role === "architect" || role === "audit")) {
+  if (!provider && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "impeccable" || role === "triage" || role === "discover" || role === "architect" || role === "audit" || role === "hu_reviewer" || role === "hu-reviewer")) {
     provider = roles.coder?.provider || legacyCoder;
   }
 
   let model = roleConfig.model ?? null;
   if (!model && role === "coder") model = config?.coder_options?.model ?? null;
   if (!model && role === "reviewer") model = config?.reviewer_options?.model ?? null;
-  if (!model && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "impeccable" || role === "triage" || role === "discover" || role === "architect")) {
+  if (!model && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "impeccable" || role === "triage" || role === "discover" || role === "architect" || role === "hu_reviewer" || role === "hu-reviewer")) {
     model = config?.coder_options?.model ?? null;
   }
 

package/src/hu/graph.js

@@ -0,0 +1,71 @@
+/**
+ * Topological sort of HU stories respecting blocked_by dependencies.
+ * Returns ordered array of story IDs (dependencies first).
+ * Throws if circular dependency detected.
+ * @param {Array<{id: string, blocked_by?: string[]}>} stories
+ * @returns {string[]} Sorted story IDs.
+ */
+export function topologicalSort(stories) {
+  const ids = new Set(stories.map(s => s.id));
+  const adj = new Map(); // id -> [dependents]
+  const inDegree = new Map();
+
+  for (const s of stories) {
+    adj.set(s.id, []);
+    inDegree.set(s.id, 0);
+  }
+
+  for (const s of stories) {
+    for (const dep of (s.blocked_by || [])) {
+      if (!ids.has(dep)) throw new Error(`Dependency ${dep} not found in batch`);
+      adj.get(dep).push(s.id);
+      inDegree.set(s.id, (inDegree.get(s.id) || 0) + 1);
+    }
+  }
+
+  const queue = [];
+  for (const [id, degree] of inDegree) {
+    if (degree === 0) queue.push(id);
+  }
+
+  const sorted = [];
+  while (queue.length > 0) {
+    const id = queue.shift();
+    sorted.push(id);
+    for (const dependent of adj.get(id)) {
+      inDegree.set(dependent, inDegree.get(dependent) - 1);
+      if (inDegree.get(dependent) === 0) queue.push(dependent);
+    }
+  }
+
+  if (sorted.length !== stories.length) {
+    throw new Error("Circular dependency detected in HU batch");
+  }
+
+  return sorted;
+}
+
+/**
+ * Check if a story is ready to execute (all its dependencies are done).
+ * @param {{blocked_by?: string[]}} story
+ * @param {{stories: Array<{id: string, status: string}>}} batch
+ * @returns {boolean}
+ */
+export function isStoryReady(story, batch) {
+  if (!story.blocked_by || story.blocked_by.length === 0) return true;
+  return story.blocked_by.every(depId => {
+    const dep = batch.stories.find(s => s.id === depId);
+    return dep && dep.status === "done";
+  });
+}
+
+/**
+ * Get next stories ready for execution (certified + all deps done).
+ * @param {{stories: Array<{id: string, status: string, blocked_by?: string[]}>}} batch
+ * @returns {Array<object>} Stories that are certified and whose deps are all done.
+ */
+export function getNextReadyStories(batch) {
+  return batch.stories.filter(s =>
+    s.status === "certified" && isStoryReady(s, batch)
+  );
+}

package/src/hu/store.js

@@ -0,0 +1,153 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getKarajanHome } from "../utils/paths.js";
+
+// FUTURE: hu-storage adapter for PG/Trello/etc — currently local files only
+
+/** @returns {string} Path to the hu-stories directory (evaluated at call time). */
+function getHuDir() {
+  return path.join(getKarajanHome(), "hu-stories");
+}
+
+/**
+ * Create a new HU batch from an array of story definitions.
+ * @param {string} sessionId - The session identifier.
+ * @param {Array<{id?: string, text: string, blocked_by?: string[]}>} stories - Raw story inputs.
+ * @returns {Promise<object>} The created batch object.
+ */
+export async function createHuBatch(sessionId, stories) {
+  const dir = path.join(getHuDir(), sessionId);
+  await fs.mkdir(dir, { recursive: true });
+
+  const batch = {
+    session_id: sessionId,
+    created_at: new Date().toISOString(),
+    stories: stories.map((s, i) => ({
+      id: s.id || `HU-${Date.now()}-${i}`,
+      status: "pending",
+      original: { text: s.text },
+      blocked_by: s.blocked_by || [],
+      certified: null,
+      quality: null,
+      context_requests: [],
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString()
+    }))
+  };
+
+  await fs.writeFile(path.join(dir, "batch.json"), JSON.stringify(batch, null, 2));
+  return batch;
+}
+
+/**
+ * Load an existing HU batch from disk.
+ * @param {string} sessionId - The session identifier.
+ * @returns {Promise<object>} The loaded batch object.
+ */
+export async function loadHuBatch(sessionId) {
+  const file = path.join(getHuDir(), sessionId, "batch.json");
+  const raw = await fs.readFile(file, "utf8");
+  return JSON.parse(raw);
+}
+
+/**
+ * Save a batch back to disk.
+ * @param {string} sessionId - The session identifier.
+ * @param {object} batch - The batch object to persist.
+ * @returns {Promise<void>}
+ */
+export async function saveHuBatch(sessionId, batch) {
+  const dir = path.join(getHuDir(), sessionId);
+  batch.updated_at = new Date().toISOString();
+  await fs.writeFile(path.join(dir, "batch.json"), JSON.stringify(batch, null, 2));
+}
+
+/**
+ * Update the status of a single story within a batch.
+ * @param {object} batch - The batch object.
+ * @param {string} storyId - Story ID to update.
+ * @param {string} status - New status value.
+ * @param {object} [extra={}] - Additional fields to merge.
+ * @returns {object} The updated story.
+ */
+export function updateStoryStatus(batch, storyId, status, extra = {}) {
+  const story = batch.stories.find(s => s.id === storyId);
+  if (!story) throw new Error(`Story ${storyId} not found`);
+  story.status = status;
+  story.updated_at = new Date().toISOString();
+  Object.assign(story, extra);
+  return story;
+}
+
+/**
+ * Store quality scores on a story.
+ * @param {object} batch - The batch object.
+ * @param {string} storyId - Story ID.
+ * @param {object} quality - Quality scores object.
+ * @returns {object} The updated story.
+ */
+export function updateStoryQuality(batch, storyId, quality) {
+  const story = batch.stories.find(s => s.id === storyId);
+  if (!story) throw new Error(`Story ${storyId} not found`);
+  story.quality = { ...quality, evaluated_at: new Date().toISOString() };
+  story.updated_at = new Date().toISOString();
+  return story;
+}
+
+/**
+ * Mark a story as certified with the provided certified data.
+ * @param {object} batch - The batch object.
+ * @param {string} storyId - Story ID.
+ * @param {object} certified - Certified HU data.
+ * @returns {object} The updated story.
+ */
+export function updateStoryCertified(batch, storyId, certified) {
+  const story = batch.stories.find(s => s.id === storyId);
+  if (!story) throw new Error(`Story ${storyId} not found`);
+  story.certified = certified;
+  story.status = "certified";
+  story.updated_at = new Date().toISOString();
+  return story;
+}
+
+/**
+ * Add a context request to a story and set its status to needs_context.
+ * @param {object} batch - The batch object.
+ * @param {string} storyId - Story ID.
+ * @param {{fields_needed: string[], question: string}} request - Context request.
+ * @returns {object} The updated story.
+ */
+export function addContextRequest(batch, storyId, request) {
+  const story = batch.stories.find(s => s.id === storyId);
+  if (!story) throw new Error(`Story ${storyId} not found`);
+  story.context_requests.push({
+    requested_at: new Date().toISOString(),
+    fields_needed: request.fields_needed,
+    question_to_fde: request.question,
+    answered_at: null,
+    answer: null
+  });
+  story.status = "needs_context";
+  story.updated_at = new Date().toISOString();
+  return story;
+}
+
+/**
+ * Answer the most recent pending context request and reset status to pending.
+ * @param {object} batch - The batch object.
+ * @param {string} storyId - Story ID.
+ * @param {string} answer - The FDE's answer.
+ * @returns {object} The updated story.
+ */
+export function answerContextRequest(batch, storyId, answer) {
+  const story = batch.stories.find(s => s.id === storyId);
+  if (!story) throw new Error(`Story ${storyId} not found`);
+  const pending = story.context_requests.find(r => !r.answered_at);
+  if (pending) {
+    pending.answered_at = new Date().toISOString();
+    pending.answer = answer;
+  }
+  story.status = "pending"; // back to pending for re-evaluation
+  story.updated_at = new Date().toISOString();
+  return story;
+}

package/src/mcp/run-kj.js

@@ -46,6 +46,8 @@ export async function runKjCommand({ command, commandArgs = [], options = {}, en
   normalizeBoolFlag(options.enableTriage, "--enable-triage", args);
   normalizeBoolFlag(options.enableDiscover, "--enable-discover", args);
   normalizeBoolFlag(options.enableArchitect, "--enable-architect", args);
+  normalizeBoolFlag(options.enableHuReviewer, "--enable-hu-reviewer", args);
+  addOptionalValue(args, "--hu-file", options.huFile);
   normalizeBoolFlag(options.enableSerena, "--enable-serena", args);
   normalizeBoolFlag(options.autoCommit, "--auto-commit", args);
   normalizeBoolFlag(options.autoPush, "--auto-push", args);
@@ -60,6 +62,8 @@ export async function runKjCommand({ command, commandArgs = [], options = {}, en
   addOptionalValue(args, "--checkpoint-interval", options.checkpointInterval);
   addOptionalValue(args, "--pg-task", options.pgTask);
   addOptionalValue(args, "--pg-project", options.pgProject);
+  if (options.quiet === true) args.push("--quiet");
+  if (options.quiet === false) args.push("--verbose");
 
   const runEnv = {
     ...process.env,

package/src/mcp/tools.js

@@ -74,7 +74,9 @@ export const tools = [
         enableTriage: { type: "boolean" },
         enableDiscover: { type: "boolean" },
         enableArchitect: { type: "boolean" },
+        enableHuReviewer: { type: "boolean" },
         architectModel: { type: "string" },
+        huFile: { type: "string", description: "Path to YAML file with HU stories to certify before coding" },
         enableSerena: { type: "boolean" },
         enableBecaria: { type: "boolean", description: "Enable BecarIA Gateway (early PR + dispatch comments/reviews)" },
         reviewerFallback: { type: "string" },
@@ -95,6 +97,7 @@ export const tools = [
         smartModels: { type: "boolean", description: "Enable/disable smart model selection based on triage complexity" },
         checkpointInterval: { type: "number", description: "Minutes between interactive checkpoints (default: 5). Set 0 to disable." },
         taskType: { type: "string", enum: ["sw", "infra", "doc", "add-tests", "refactor"], description: "Explicit task type for policy resolution. Overrides triage classification." },
+        quiet: { type: "boolean", description: "Suppress raw agent output lines, show only stage status (default: true). Set false for verbose output." },
         noSonar: { type: "boolean" },
         enableSonarcloud: { type: "boolean", description: "Enable SonarCloud scan (complementary to SonarQube)" },
         kjHome: { type: "string" },

package/src/orchestrator/pre-loop-stages.js

@@ -3,6 +3,7 @@ import { ResearcherRole } from "../roles/researcher-role.js";
 import { PlannerRole } from "../roles/planner-role.js";
 import { DiscoverRole } from "../roles/discover-role.js";
 import { ArchitectRole } from "../roles/architect-role.js";
+import { HuReviewerRole } from "../roles/hu-reviewer-role.js";
 import { createAgent } from "../agents/index.js";
 import { createArchitectADRs } from "../planning-game/architect-adrs.js";
 import { addCheckpoint, markSessionStatus } from "../session-store.js";
@@ -10,6 +11,8 @@ import { emitProgress, makeEvent } from "../utils/events.js";
 import { parsePlannerOutput } from "../prompts/planner.js";
 import { selectModelsForRoles } from "../utils/model-selector.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";
 
 const ROLE_NAMES = ["planner", "researcher", "architect", "refactorer", "reviewer", "tester", "security", "impeccable"];
 
@@ -507,3 +510,210 @@ export async function runDiscoverStage({ config, logger, emitter, eventBase, ses
 
   return { stageResult };
 }
+
+/**
+ * Run the HU Reviewer stage: load stories from YAML, evaluate, certify, and return in topological order.
+ * @param {object} params
+ * @returns {Promise<{stageResult: object}>}
+ */
+export async function runHuReviewerStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget, huFile, askQuestion }) {
+  logger.setContext({ iteration: 0, stage: "hu-reviewer" });
+  emitProgress(
+    emitter,
+    makeEvent("hu-reviewer:start", { ...eventBase, stage: "hu-reviewer" }, {
+      message: "HU Reviewer certifying user stories"
+    })
+  );
+
+  // --- 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 };
+  }
+
+  let stories;
+  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 };
+  }
+
+  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 {
+    batch = await createHuBatch(batchSessionId, stories);
+  }
+
+  // --- Evaluate loop (re-evaluate entire batch until all certified or needs_context with no askQuestion) ---
+  const huReviewerProvider = config?.roles?.hu_reviewer?.provider || coderRole.provider;
+  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 {
+    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
+    })
+  );
+
+  return { stageResult };
+}