karajan-code 1.29.1 → 1.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.29.1",
+  "version": "1.30.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/cli.js

@@ -80,6 +80,8 @@ program
   .option("--enable-triage")
   .option("--enable-discover")
   .option("--enable-architect")
+  .option("--enable-hu-reviewer")
+  .option("--hu-file <path>", "YAML file with HU stories to certify before coding")
   .option("--enable-serena")
   .option("--mode <name>")
   .option("--max-iterations <n>")

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",
@@ -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";
@@ -414,14 +417,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);

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" },

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 };
+}

package/src/orchestrator.js

@@ -30,7 +30,7 @@ import { resolveReviewProfile } from "./review/profiles.js";
 import { CoderRole } from "./roles/coder-role.js";
 import { invokeSolomon } from "./orchestrator/solomon-escalation.js";
 import { PipelineContext } from "./orchestrator/pipeline-context.js";
-import { runTriageStage, runResearcherStage, runArchitectStage, runPlannerStage, runDiscoverStage } from "./orchestrator/pre-loop-stages.js";
+import { runTriageStage, runResearcherStage, runArchitectStage, runPlannerStage, runDiscoverStage, runHuReviewerStage } from "./orchestrator/pre-loop-stages.js";
 import { runCoderStage, runRefactorerStage, runTddCheckStage, runSonarStage, runSonarCloudStage, runReviewerStage } from "./orchestrator/iteration-stages.js";
 import { runTesterStage, runSecurityStage, runImpeccableStage } from "./orchestrator/post-loop-stages.js";
 import { waitForCooldown, MAX_STANDBY_RETRIES } from "./orchestrator/standby.js";
@@ -51,11 +51,12 @@ function resolvePipelineFlags(config) {
     reviewerEnabled: config.pipeline?.reviewer?.enabled !== false,
     discoverEnabled: Boolean(config.pipeline?.discover?.enabled),
     architectEnabled: Boolean(config.pipeline?.architect?.enabled),
+    huReviewerEnabled: Boolean(config.pipeline?.hu_reviewer?.enabled),
   };
 }
 
 async function handleDryRun({ task, config, flags, emitter, pipelineFlags }) {
-  const { plannerEnabled, refactorerEnabled, researcherEnabled, testerEnabled, securityEnabled, impeccableEnabled, reviewerEnabled, discoverEnabled, architectEnabled } = pipelineFlags;
+  const { plannerEnabled, refactorerEnabled, researcherEnabled, testerEnabled, securityEnabled, impeccableEnabled, reviewerEnabled, discoverEnabled, architectEnabled, huReviewerEnabled } = pipelineFlags;
   const plannerRole = resolveRole(config, "planner");
   const coderRole = resolveRole(config, "coder");
   const reviewerRole = resolveRole(config, "reviewer");
@@ -89,7 +90,8 @@ async function handleDryRun({ task, config, flags, emitter, pipelineFlags }) {
       tester_enabled: testerEnabled,
       security_enabled: securityEnabled,
       impeccable_enabled: impeccableEnabled,
-      solomon_enabled: Boolean(config.pipeline?.solomon?.enabled)
+      solomon_enabled: Boolean(config.pipeline?.solomon?.enabled),
+      hu_reviewer_enabled: huReviewerEnabled
     },
     limits: {
       max_iterations: config.max_iterations,
@@ -707,6 +709,14 @@ async function handleReviewerRetryAndSolomon({ config, session, emitter, eventBa
 
 
 async function runPreLoopStages({ config, logger, emitter, eventBase, session, flags, pipelineFlags, coderRole, trackBudget, task, askQuestion, pgTaskId, pgProject, stageResults }) {
+  // --- HU Reviewer (first stage, before everything else, opt-in) ---
+  const huFile = flags.huFile || null;
+  if (flags.enableHuReviewer !== undefined) pipelineFlags.huReviewerEnabled = Boolean(flags.enableHuReviewer);
+  if (pipelineFlags.huReviewerEnabled && huFile) {
+    const huResult = await runHuReviewerStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget, huFile, askQuestion });
+    stageResults.huReviewer = huResult.stageResult;
+  }
+
   // --- Intent classifier (deterministic pre-triage, opt-in) ---
   if (config.guards?.intent?.enabled) {
     const intentResult = classifyIntent(task, config);

package/src/prompts/hu-reviewer.js

@@ -0,0 +1,130 @@
+const SUBAGENT_PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Do NOT use any MCP tools. Focus only on evaluating HUs."
+].join(" ");
+
+const VALID_VERDICTS = new Set(["certified", "needs_rewrite", "needs_context"]);
+const VALID_ANTIPATTERNS = new Set([
+  "ghost_user", "swiss_army_knife", "implementation_leak",
+  "moving_goalpost", "orphan_story", "invisible_dependency", "premature_optimization"
+]);
+const DIMENSION_KEYS = [
+  "D1_jtbd_context", "D2_user_specificity", "D3_behavior_change",
+  "D4_control_zone", "D5_time_constraints", "D6_survivable_experiment"
+];
+
+/**
+ * Build the prompt for the HU reviewer agent.
+ * @param {{stories: Array<{id: string, text: string}>, instructions: string|null, context?: string|null}} params
+ * @returns {string} The assembled prompt.
+ */
+export function buildHuReviewerPrompt({ stories, instructions, context = null }) {
+  const sections = [SUBAGENT_PREAMBLE];
+
+  if (instructions) {
+    sections.push(instructions);
+  }
+
+  sections.push("## Stories to Evaluate");
+
+  for (const story of stories) {
+    sections.push(`### ${story.id}\n${story.text}`);
+  }
+
+  sections.push(
+    "Return a single valid JSON object and nothing else.",
+    `JSON schema: {"evaluations":[{"story_id":string,"scores":{"D1_jtbd_context":number,"D2_user_specificity":number,"D3_behavior_change":number,"D4_control_zone":number,"D5_time_constraints":number,"D6_survivable_experiment":number},"total":number,"antipatterns_detected":[string],"verdict":"certified|needs_rewrite|needs_context","evaluation_notes":string,"rewritten":object|null,"certified_hu":object|null,"context_needed":object|null}],"batch_summary":{"total":number,"certified":number,"needs_rewrite":number,"needs_context":number,"consolidated_questions":string}}`
+  );
+
+  if (context) {
+    sections.push(`## Additional Context\n${context}`);
+  }
+
+  return sections.join("\n\n");
+}
+
+/**
+ * Clamp a score to 0-10 range.
+ * @param {*} value
+ * @returns {number}
+ */
+function clampScore(value) {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return 0;
+  return Math.max(0, Math.min(10, Math.round(n)));
+}
+
+/**
+ * Parse and validate a single evaluation object.
+ * @param {object} raw
+ * @returns {object|null}
+ */
+function parseEvaluation(raw) {
+  if (!raw || !raw.story_id || !raw.scores) return null;
+
+  const scores = {};
+  for (const key of DIMENSION_KEYS) {
+    scores[key] = clampScore(raw.scores[key]);
+  }
+
+  const total = Object.values(scores).reduce((sum, v) => sum + v, 0);
+  const antipatterns = (Array.isArray(raw.antipatterns_detected) ? raw.antipatterns_detected : [])
+    .filter(ap => VALID_ANTIPATTERNS.has(ap));
+
+  const rawVerdict = String(raw.verdict || "").toLowerCase();
+  const verdict = VALID_VERDICTS.has(rawVerdict) ? rawVerdict : "needs_context";
+
+  return {
+    story_id: raw.story_id,
+    scores,
+    total,
+    antipatterns_detected: antipatterns,
+    verdict,
+    evaluation_notes: raw.evaluation_notes || "",
+    rewritten: raw.rewritten || null,
+    certified_hu: raw.certified_hu || null,
+    context_needed: raw.context_needed || null
+  };
+}
+
+/**
+ * Parse the raw output from the HU reviewer agent.
+ * @param {string} raw - Raw text output from the agent.
+ * @returns {object|null} Parsed result with evaluations and batch_summary, or null.
+ */
+export function parseHuReviewerOutput(raw) {
+  const text = raw?.trim() || "";
+  const jsonMatch = /\{[\s\S]*\}/.exec(text);
+  if (!jsonMatch) return null;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonMatch[0]);
+  } catch {
+    return null;
+  }
+
+  if (!Array.isArray(parsed.evaluations)) return null;
+
+  const evaluations = parsed.evaluations
+    .map(parseEvaluation)
+    .filter(Boolean);
+
+  if (evaluations.length === 0) return null;
+
+  const certified = evaluations.filter(e => e.verdict === "certified").length;
+  const needsRewrite = evaluations.filter(e => e.verdict === "needs_rewrite").length;
+  const needsContext = evaluations.filter(e => e.verdict === "needs_context").length;
+
+  return {
+    evaluations,
+    batch_summary: {
+      total: evaluations.length,
+      certified,
+      needs_rewrite: needsRewrite,
+      needs_context: needsContext,
+      consolidated_questions: parsed.batch_summary?.consolidated_questions || ""
+    }
+  };
+}

package/src/roles/hu-reviewer-role.js

@@ -0,0 +1,112 @@
+import { BaseRole } from "./base-role.js";
+import { createAgent as defaultCreateAgent } from "../agents/index.js";
+import { buildHuReviewerPrompt, parseHuReviewerOutput } from "../prompts/hu-reviewer.js";
+
+/**
+ * Resolve the provider for the hu-reviewer role, falling back to coder.
+ * @param {object} config
+ * @returns {string}
+ */
+function resolveProvider(config) {
+  return (
+    config?.roles?.["hu-reviewer"]?.provider ||
+    config?.roles?.hu_reviewer?.provider ||
+    config?.roles?.coder?.provider ||
+    "claude"
+  );
+}
+
+/**
+ * Build a human-readable summary from parsed evaluations.
+ * @param {object} parsed - Parsed HU reviewer output.
+ * @returns {string}
+ */
+function buildSummary(parsed) {
+  const { batch_summary: bs } = parsed;
+  const parts = [`${bs.total} HU(s) evaluated`];
+  if (bs.certified > 0) parts.push(`${bs.certified} certified`);
+  if (bs.needs_rewrite > 0) parts.push(`${bs.needs_rewrite} need rewrite`);
+  if (bs.needs_context > 0) parts.push(`${bs.needs_context} need context`);
+  return `HU Review complete: ${parts.join(", ")}`;
+}
+
+export class HuReviewerRole extends BaseRole {
+  /**
+   * @param {{config: object, logger: object, emitter?: object|null, createAgentFn?: Function|null}} params
+   */
+  constructor({ config, logger, emitter = null, createAgentFn = null }) {
+    super({ name: "hu-reviewer", config, logger, emitter });
+    this._createAgent = createAgentFn || defaultCreateAgent;
+  }
+
+  /**
+   * Execute the HU review.
+   * @param {{stories: Array<{id: string, text: string}>, context?: string|null, onOutput?: Function|null}} input
+   * @returns {Promise<{ok: boolean, result: object, summary: string, usage?: object}>}
+   */
+  async execute(input) {
+    const stories = input?.stories || [];
+    const context = input?.context || null;
+    const onOutput = input?.onOutput || null;
+
+    const provider = resolveProvider(this.config);
+    const agent = this._createAgent(provider, this.config, this.logger);
+
+    const prompt = buildHuReviewerPrompt({ stories, instructions: this.instructions, context });
+    const runArgs = { prompt, role: "hu-reviewer" };
+    if (onOutput) runArgs.onOutput = onOutput;
+    const result = await agent.runTask(runArgs);
+
+    if (!result.ok) {
+      return {
+        ok: false,
+        result: {
+          error: result.error || result.output || "HU Review failed",
+          provider
+        },
+        summary: `HU Review failed: ${result.error || "unknown error"}`,
+        usage: result.usage
+      };
+    }
+
+    try {
+      const parsed = parseHuReviewerOutput(result.output);
+      if (!parsed) {
+        return {
+          ok: true,
+          result: {
+            evaluations: [],
+            batch_summary: { total: 0, certified: 0, needs_rewrite: 0, needs_context: 0, consolidated_questions: "" },
+            raw: result.output,
+            provider
+          },
+          summary: "HU Review complete (unstructured output)",
+          usage: result.usage
+        };
+      }
+
+      return {
+        ok: true,
+        result: {
+          evaluations: parsed.evaluations,
+          batch_summary: parsed.batch_summary,
+          provider
+        },
+        summary: buildSummary(parsed),
+        usage: result.usage
+      };
+    } catch {
+      return {
+        ok: true,
+        result: {
+          evaluations: [],
+          batch_summary: { total: 0, certified: 0, needs_rewrite: 0, needs_context: 0, consolidated_questions: "" },
+          raw: result.output,
+          provider
+        },
+        summary: "HU Review complete (unstructured output)",
+        usage: result.usage
+      };
+    }
+  }
+}

package/src/roles/index.js

@@ -13,3 +13,4 @@ export { SolomonRole } from "./solomon-role.js";
 export { DiscoverRole } from "./discover-role.js";
 export { ArchitectRole } from "./architect-role.js";
 export { AuditRole } from "./audit-role.js";
+export { HuReviewerRole } from "./hu-reviewer-role.js";

package/templates/roles/hu-reviewer.md

@@ -0,0 +1,192 @@
+# HU Reviewer Role
+
+You are the **HU Reviewer** in a multi-role AI pipeline. You are a **mandatory certification gate** for user stories (HUs). No HU may proceed to development without your explicit certification.
+
+Your job: evaluate raw or semi-structured HUs against 6 quality dimensions, detect antipatterns, attempt rewrites when possible, and certify stories that meet minimum quality thresholds.
+
+## The 6 Quality Dimensions
+
+Each dimension scores 0-10. Total possible: 60.
+
+### D1 — JTBD Context (0-10)
+Does the HU clearly state the Job-to-be-Done context?
+- **0**: No context at all. "Add a button."
+- **3**: Vague context. "Users need a better experience."
+- **5**: Some context but missing the WHY behind the job.
+- **7**: Clear context with functional job stated. "When a doctor creates a treatment plan, they need to see the patient's history to avoid errors."
+- **10**: Full JTBD with functional, emotional, and social dimensions.
+
+### D2 — User Specificity (0-10)
+Is the user clearly identified with a specific role/persona?
+
+**HARD RULE: Maximum score of 5 if the user is generic (e.g., "As a user", "As an admin") without further persona qualification.**
+
+- **0**: No user mentioned. Passive voice. "A report should be generated."
+- **3**: Generic user. "As a user, I want..."
+- **5**: Role-based but not specific. "As an admin..."
+- **7**: Specific persona. "As a clinic receptionist managing 20+ appointments daily..."
+- **10**: Named persona with behavioral context. "As Dr. Garcia, an orthodontist who treats 15 patients per day with 3D planning..."
+
+### D3 — Behavior Change Quantification (0-10)
+Is the expected behavior change measurable and quantified?
+
+**HARD RULE: Maximum score of 5 if no quantification is provided (no numbers, percentages, time savings, or measurable outcomes).**
+
+- **0**: No measurable outcome. "Improve the workflow."
+- **3**: Qualitative improvement only. "Make it faster."
+- **5**: Directional but not quantified. "Reduce the number of clicks."
+- **7**: Partially quantified. "Reduce treatment creation time by at least 30%."
+- **10**: Fully quantified with baseline and target. "Reduce treatment creation from 45 min to 15 min (current average measured in January 2026)."
+
+### D4 — Control Zone (0-10)
+Is the scope clearly bounded? Are boundaries and out-of-scope items explicit?
+- **0**: No boundaries. "Improve everything."
+- **3**: Implied boundaries but nothing explicit.
+- **5**: Some boundaries mentioned. "Only for the extranet."
+- **7**: Clear boundaries with explicit out-of-scope items.
+- **10**: Boundaries, out-of-scope, stack constraints, and integration points all documented.
+
+### D5 — Time Constraints (0-10)
+Are deadlines, dependencies, and temporal constraints documented?
+- **0**: No time reference at all.
+- **3**: Vague urgency. "ASAP."
+- **5**: Sprint/quarter mentioned. "Q2 2026."
+- **7**: Specific deadline with rationale. "Before March release because client X is waiting."
+- **10**: Full timeline with milestones, dependencies, and risk dates.
+
+### D6 — Survivable Experiment (0-10)
+Can this be safely deployed as an experiment? Is there a rollback plan?
+- **0**: No consideration of failure. No rollback.
+- **3**: Implicit safety. "It's a small change."
+- **5**: Feature flag mentioned but no rollback plan.
+- **7**: Feature flag + rollback plan + blast radius defined.
+- **10**: Full experiment design: hypothesis, success metrics, blast radius, rollback, kill criteria.
+
+## Minimum Certification Thresholds
+
+- **Certified**: Total >= 35 AND no dimension below 3 AND no HARD RULE violations (D2 > 5, D3 > 5)
+- **Needs Rewrite**: Total >= 20 OR any dimension can be improved with available information
+- **Needs Context**: Information is fundamentally missing and cannot be inferred
+
+## The 7 Antipatterns
+
+Detect and flag these antipatterns in every HU:
+
+### 1. ghost_user
+No real user identified. The HU uses passive voice or impersonal constructions.
+- Example: "A report should be generated weekly." (Who reads it? Who acts on it?)
+
+### 2. swiss_army_knife
+The HU tries to do too many things at once. Multiple "and" clauses in the want.
+- Example: "As a user, I want to create, edit, delete, and archive reports and also manage templates."
+
+### 3. implementation_leak
+The HU prescribes a specific technical solution instead of describing the need.
+- Example: "As a user, I want a React modal with a DataGrid component using AG Grid."
+
+### 4. moving_goalpost
+The acceptance criteria are vague or subjective, making it impossible to know when the HU is done.
+- Example: "The page should load fast." "The UI should be intuitive."
+
+### 5. orphan_story
+The HU has no clear connection to a business goal, epic, or user journey.
+- Example: "Refactor the database schema." (Why? What business outcome?)
+
+### 6. invisible_dependency
+The HU depends on other work, APIs, or decisions that are not documented.
+- Example: "Integrate with the new payment provider." (Which one? Is the contract ready?)
+
+### 7. premature_optimization
+The HU optimizes something without evidence that it is a real problem.
+- Example: "Cache all API responses to improve performance." (Is performance actually a problem? Where is the data?)
+
+## Rewrite Instructions
+
+When a HU scores below certification threshold but has enough information to improve:
+
+1. Attempt to rewrite it preserving the original intent
+2. Make the user more specific (D2)
+3. Add quantification where possible (D3)
+4. Clarify boundaries (D4)
+5. Add acceptance criteria in Given/When/Then format
+6. Flag what you assumed vs. what was in the original
+
+**Never invent business requirements.** If you don't have enough information, request context instead of guessing.
+
+## Certified HU Format
+
+When a HU is certified, produce it in this structured format:
+
+```json
+{
+  "as": "specific user persona with behavioral context",
+  "context": "JTBD context — the situation and the job being done",
+  "want": "single, focused behavior change",
+  "so_that": "measurable business outcome with quantification",
+  "acceptance_criteria": [
+    {"given": "...", "when": "...", "then": "..."},
+    {"given": "...", "when": "...", "then": "..."}
+  ],
+  "boundaries": {
+    "in_scope": ["..."],
+    "out_of_scope": ["..."]
+  },
+  "stack_constraints": ["..."],
+  "definition_of_done": ["..."],
+  "risk": "rollback plan and blast radius"
+}
+```
+
+## Output Format
+
+Return a single valid JSON object with this schema:
+
+```json
+{
+  "evaluations": [
+    {
+      "story_id": "HU-xxx",
+      "scores": {
+        "D1_jtbd_context": 0,
+        "D2_user_specificity": 0,
+        "D3_behavior_change": 0,
+        "D4_control_zone": 0,
+        "D5_time_constraints": 0,
+        "D6_survivable_experiment": 0
+      },
+      "total": 0,
+      "antipatterns_detected": [],
+      "verdict": "certified | needs_rewrite | needs_context",
+      "evaluation_notes": "explanation of scores and verdict",
+      "rewritten": null,
+      "certified_hu": null,
+      "context_needed": null
+    }
+  ],
+  "batch_summary": {
+    "total": 0,
+    "certified": 0,
+    "needs_rewrite": 0,
+    "needs_context": 0,
+    "consolidated_questions": ""
+  }
+}
+```
+
+### Field details:
+- **rewritten**: When verdict is "needs_rewrite" and you can improve it, provide the rewritten HU in certified format. Set to null otherwise.
+- **certified_hu**: When verdict is "certified", provide the HU in the certified format above. Set to null otherwise.
+- **context_needed**: When verdict is "needs_context", provide `{"fields_needed": ["D2", "D3", ...], "question_to_fde": "What specific question should be asked?"}`. Set to null otherwise.
+- **consolidated_questions**: In batch_summary, group all questions across stories for efficient FDE communication.
+
+## HARD RULES Summary
+
+1. **D2 cap**: If the user is "a user", "an admin", "a developer" without further qualification, D2 score MUST be <= 5.
+2. **D3 cap**: If there is no number, percentage, time metric, or measurable target anywhere in the HU, D3 score MUST be <= 5.
+3. **Certification gate**: A HU with D2 <= 5 OR D3 <= 5 due to HARD RULES can NEVER be certified without a rewrite that fixes the violation.
+4. **No business invention**: Never invent requirements. If information is missing, set verdict to "needs_context".
+5. **Batch integrity**: When re-evaluating after FDE answers, re-evaluate the ENTIRE batch, not just the stories that needed context.
+
+{{task}}
+
+{{context}}