karajan-code 1.37.0 → 1.38.1

package/src/hu/store.js

@@ -4,6 +4,21 @@ import { getKarajanHome } from "../utils/paths.js";
 
 // FUTURE: hu-storage adapter for PG/Trello/etc — currently local files only
 
+/**
+ * Valid HU story status values.
+ * @type {Readonly<{PENDING: "pending", CODING: "coding", REVIEWING: "reviewing", DONE: "done", FAILED: "failed", BLOCKED: "blocked", CERTIFIED: "certified", NEEDS_CONTEXT: "needs_context"}>}
+ */
+export const HU_STATUS = Object.freeze({
+  PENDING: "pending",
+  CODING: "coding",
+  REVIEWING: "reviewing",
+  DONE: "done",
+  FAILED: "failed",
+  BLOCKED: "blocked",
+  CERTIFIED: "certified",
+  NEEDS_CONTEXT: "needs_context"
+});
+
 /** @returns {string} Path to the hu-stories directory (evaluated at call time). */
 function getHuDir() {
   return path.join(getKarajanHome(), "hu-stories");
@@ -151,3 +166,45 @@ export function answerContextRequest(batch, storyId, answer) {
   story.updated_at = new Date().toISOString();
   return story;
 }
+
+/**
+ * Create a lightweight history record for a pipeline run.
+ * Stores a minimal single-HU batch in the same hu-stories directory
+ * so the HU Board can pick it up alongside full batches.
+ * @param {string} sessionId - The session identifier.
+ * @param {{task: string, result: string, approved: boolean, summary?: string, timestamp?: string}} data
+ * @returns {Promise<object>} The created batch object.
+ */
+export async function createHistoryRecord(sessionId, { task, result, approved, summary, timestamp }) {
+  const ts = timestamp || new Date().toISOString();
+  const dir = path.join(getHuDir(), sessionId);
+  await fs.mkdir(dir, { recursive: true });
+
+  const batch = {
+    session_id: sessionId,
+    created_at: ts,
+    stories: [
+      {
+        id: `HU-hist-${sessionId}`,
+        status: approved ? "certified" : "failed",
+        original: { text: task },
+        blocked_by: [],
+        certified: approved ? { summary: summary || result } : null,
+        quality: null,
+        context_requests: [],
+        created_at: ts,
+        updated_at: ts
+      }
+    ],
+    history: {
+      task,
+      result,
+      approved,
+      summary: summary || null,
+      timestamp: ts
+    }
+  };
+
+  await fs.writeFile(path.join(dir, "batch.json"), JSON.stringify(batch, null, 2));
+  return batch;
+}

package/src/mcp/server-handlers.js

@@ -482,7 +482,9 @@ export async function handleCodeDirect(a, server, extra) {
   if (config.coder_rules) {
     try {
       coderRules = await fs.readFile(config.coder_rules, "utf8");
-    } catch { /* no coder rules file */ }
+    } catch {
+      try { coderRules = await fs.readFile("coder-rules.md", "utf8"); } catch { /* no coder rules file */ }
+    }
   }
   const prompt = buildCoderPrompt({ task: a.task, coderRules, methodology: config.development?.methodology || "tdd" });
   sendTrackerLog(server, "coder", "running", coderRole.provider);

package/src/orchestrator/hu-sub-pipeline.js

@@ -0,0 +1,166 @@
+/**
+ * HU Sub-Pipeline — executes each certified HU as an independent sub-pipeline
+ * with per-HU state tracking, topological ordering, and dependency-aware blocking.
+ */
+import { topologicalSort } from "../hu/graph.js";
+import { updateStoryStatus, loadHuBatch, saveHuBatch, HU_STATUS } from "../hu/store.js";
+import { emitProgress, makeEvent } from "../utils/events.js";
+
+/**
+ * Determine whether the HU reviewer result requires a sub-pipeline
+ * (more than one certified story).
+ * @param {object|null} huReviewerResult - stageResults.huReviewer
+ * @returns {boolean}
+ */
+export function needsSubPipeline(huReviewerResult) {
+  if (!huReviewerResult?.ok) return false;
+  const certified = (huReviewerResult.stories || []).filter(
+    s => s.status === "certified"
+  );
+  return certified.length > 1;
+}
+
+/**
+ * Mark all stories that depend (directly or transitively) on a failed story as "blocked".
+ * @param {object} batch - The HU batch object.
+ * @param {string} failedId - The ID of the failed story.
+ * @returns {string[]} IDs of newly blocked stories.
+ */
+export function blockDependents(batch, failedId) {
+  const blocked = [];
+  const failedSet = new Set([failedId]);
+  // Iterate until no new blocked stories are found (handles transitive deps)
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const story of batch.stories) {
+      if (failedSet.has(story.id)) continue;
+      if (story.status === HU_STATUS.BLOCKED) continue;
+      const deps = story.blocked_by || [];
+      if (deps.some(dep => failedSet.has(dep))) {
+        updateStoryStatus(batch, story.id, HU_STATUS.BLOCKED);
+        failedSet.add(story.id);
+        blocked.push(story.id);
+        changed = true;
+      }
+    }
+  }
+  return blocked;
+}
+
+/**
+ * Build task description for the coder from a certified HU story.
+ * @param {object} story - A story object from the batch.
+ * @returns {string}
+ */
+function buildHuTask(story) {
+  if (story.certified?.text) return story.certified.text;
+  if (story.original?.text) return story.original.text;
+  return `Implement HU ${story.id}`;
+}
+
+/**
+ * Run all certified HUs as sub-pipelines in topological order.
+ *
+ * @param {object} params
+ * @param {object} params.huReviewerResult - stageResults.huReviewer (from pre-loop)
+ * @param {Function} params.runIterationFn - async (task) => { approved, result, ... }
+ *   Callback that runs the full coder→sonar→reviewer iteration loop for a given task.
+ *   Returns an object with at least { approved: boolean }.
+ * @param {object} params.emitter - Event emitter
+ * @param {object} params.eventBase - Base event fields
+ * @param {object} params.logger - Logger instance
+ * @returns {Promise<{approved: boolean, results: object[], blockedIds: string[]}>}
+ */
+export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitter, eventBase, logger }) {
+  const batchSessionId = huReviewerResult.batchSessionId;
+  let batch;
+  try {
+    batch = await loadHuBatch(batchSessionId);
+  } catch {
+    logger.warn("HU sub-pipeline: could not load batch, falling back to in-memory stories");
+    // Build a minimal batch from the stage result
+    batch = {
+      session_id: batchSessionId,
+      stories: huReviewerResult.stories || []
+    };
+  }
+
+  const certifiedStories = batch.stories.filter(s => s.status === HU_STATUS.CERTIFIED);
+  let orderedIds;
+  try {
+    orderedIds = topologicalSort(certifiedStories);
+  } catch {
+    orderedIds = certifiedStories.map(s => s.id);
+  }
+
+  const results = [];
+  const blockedIds = [];
+  let allApproved = true;
+
+  for (const storyId of orderedIds) {
+    const story = batch.stories.find(s => s.id === storyId);
+    if (!story) continue;
+
+    // Skip if already blocked by a failed dependency
+    if (story.status === HU_STATUS.BLOCKED) {
+      blockedIds.push(story.id);
+      continue;
+    }
+
+    const huTask = buildHuTask(story);
+
+    // --- hu:start ---
+    emitProgress(emitter, makeEvent("hu:start", { ...eventBase, stage: "hu-sub-pipeline" }, {
+      message: `Starting HU ${story.id}`,
+      detail: { huId: story.id, title: story.certified?.title || story.id }
+    }));
+
+    // Update status to coding
+    updateStoryStatus(batch, story.id, HU_STATUS.CODING);
+    await saveHuBatch(batchSessionId, batch);
+
+    try {
+      const iterResult = await runIterationFn(huTask);
+      const approved = Boolean(iterResult?.approved);
+
+      if (approved) {
+        updateStoryStatus(batch, story.id, HU_STATUS.DONE);
+        emitProgress(emitter, makeEvent("hu:end", { ...eventBase, stage: "hu-sub-pipeline" }, {
+          status: "ok",
+          message: `HU ${story.id} completed successfully`,
+          detail: { huId: story.id, approved: true }
+        }));
+        results.push({ huId: story.id, approved: true, result: iterResult });
+      } else {
+        updateStoryStatus(batch, story.id, HU_STATUS.FAILED);
+        const newlyBlocked = blockDependents(batch, story.id);
+        blockedIds.push(...newlyBlocked);
+        allApproved = false;
+
+        emitProgress(emitter, makeEvent("hu:end", { ...eventBase, stage: "hu-sub-pipeline" }, {
+          status: "fail",
+          message: `HU ${story.id} failed — ${newlyBlocked.length} dependent(s) blocked`,
+          detail: { huId: story.id, approved: false, blockedDependents: newlyBlocked, reason: iterResult?.reason }
+        }));
+        results.push({ huId: story.id, approved: false, result: iterResult, blockedDependents: newlyBlocked });
+      }
+    } catch (err) {
+      updateStoryStatus(batch, story.id, HU_STATUS.FAILED);
+      const newlyBlocked = blockDependents(batch, story.id);
+      blockedIds.push(...newlyBlocked);
+      allApproved = false;
+
+      emitProgress(emitter, makeEvent("hu:end", { ...eventBase, stage: "hu-sub-pipeline" }, {
+        status: "fail",
+        message: `HU ${story.id} threw: ${err.message}`,
+        detail: { huId: story.id, approved: false, error: err.message, blockedDependents: newlyBlocked }
+      }));
+      results.push({ huId: story.id, approved: false, error: err.message, blockedDependents: newlyBlocked });
+    }
+
+    await saveHuBatch(batchSessionId, batch);
+  }
+
+  return { approved: allApproved, results, blockedIds };
+}

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

@@ -9,6 +9,7 @@ import { createArchitectADRs } from "../planning-game/architect-adrs.js";
 import { addCheckpoint, markSessionStatus } from "../session-store.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { parsePlannerOutput } from "../prompts/planner.js";
+import { buildDecompositionPrompt, parseDecompositionOutput } from "../prompts/hu-reviewer.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";
@@ -519,11 +520,81 @@ export async function runDiscoverStage({ config, logger, emitter, eventBase, ses
 }
 
 /**
- * Run the HU Reviewer stage: load stories from YAML, evaluate, certify, and return in topological order.
+ * Use an AI agent to decompose a complex task into multiple formal HUs.
+ * Returns null if decomposition fails or the task is too simple.
+ * @param {object} params
+ * @returns {Promise<Array|null>} Array of decomposed HUs or null.
+ */
+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;
+}
+
+/**
+ * Run the HU Reviewer stage: load stories from YAML or generate from task, 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 }) {
+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(
@@ -534,30 +605,55 @@ export async function runHuReviewerStage({ config, logger, emitter, eventBase, s
     })
   );
 
-  // --- 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
+
+  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) }
     }));
-    return { stageResult };
+  } 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 => ({
+        id: hu.id,
+        text: `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")}`,
+        blocked_by: hu.dependsOn || []
+      }));
+    } else {
+      stories = [{ id: "HU-AUTO-001", text: session.task }];
+    }
   }
 
   if (stories.length === 0) {

package/src/orchestrator.js

@@ -35,6 +35,7 @@ import { PipelineContext } from "./orchestrator/pipeline-context.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, runFinalAuditStage } from "./orchestrator/post-loop-stages.js";
+import { needsSubPipeline, runHuSubPipeline } from "./orchestrator/hu-sub-pipeline.js";
 import { waitForCooldown, MAX_STANDBY_RETRIES } from "./orchestrator/standby.js";
 import { detectTestFramework } from "./utils/project-detect.js";
 import { runPreflightChecks } from "./orchestrator/preflight-checks.js";
@@ -816,7 +817,7 @@ async function runPreLoopStages({ config, logger, emitter, eventBase, session, f
   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 });
+    const huResult = await runHuReviewerStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget, huFile, askQuestion, pgStories: null });
     stageResults.huReviewer = huResult.stageResult;
   }
 
@@ -844,6 +845,20 @@ async function runPreLoopStages({ config, logger, emitter, eventBase, session, f
   applyTriageOverrides(pipelineFlags, triageResult.roleOverrides);
   stageResults.triage = triageResult.stageResult;
 
+  // --- HU Reviewer auto-activation from triage (post-triage, no huFile needed) ---
+  const triageRoles = new Set(triageResult.stageResult?.roles || []);
+  if (triageRoles.has("hu-reviewer") && !stageResults.huReviewer) {
+    pipelineFlags.huReviewerEnabled = true;
+    // Feed PG card structured data to hu-reviewer when available
+    let pgStories = null;
+    if (pgTaskId && pgProject && session.pg_card) {
+      const { buildHuStoriesFromPgCard } = await import("./planning-game/pipeline-adapter.js");
+      pgStories = buildHuStoriesFromPgCard(session.pg_card);
+    }
+    const huResult = await runHuReviewerStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget, huFile: null, askQuestion, pgStories });
+    stageResults.huReviewer = huResult.stageResult;
+  }
+
   // --- Auto-simplify pipeline for simple tasks (before explicit flag overrides) ---
   const simplified = applyAutoSimplify({
     pipelineFlags,
@@ -1301,14 +1316,29 @@ async function runSingleIteration(ctx) {
   return { action: "next" };
 }
 
-export async function runFlow({ task, config, logger, flags = {}, emitter = null, askQuestion = null, pgTaskId = null, pgProject = null }) {
-  const pipelineFlags = resolvePipelineFlags(config);
-
-  if (flags.dryRun) {
-    return handleDryRun({ task, config, flags, emitter, pipelineFlags });
+async function writeHistoryRecord({ sessionId, task, result, logger }) {
+  try {
+    const { createHistoryRecord } = await import("./hu/store.js");
+    const approved = Boolean(result?.approved);
+    const summary = result?.review?.summary || result?.reason || null;
+    await createHistoryRecord(sessionId, {
+      task,
+      result: JSON.stringify(result),
+      approved,
+      summary
+    });
+  } catch (err) {
+    logger.warn(`HU history record failed (non-blocking): ${err.message}`);
   }
+}
 
-  const ctx = await initFlowContext({ task, config, logger, emitter, askQuestion, pgTaskId, pgProject, flags });
+/**
+ * Run the standard iteration loop for a given task using the pipeline context.
+ * Returns a result object with at least { approved: boolean }.
+ * Used both as the main loop and as the per-HU callback in sub-pipeline mode.
+ */
+async function runIterationLoop(ctx, { task: loopTask, askQuestion, emitter, logger }) {
+  ctx.plannedTask = loopTask;
 
   const checkpointIntervalMs = (ctx.config.session.checkpoint_interval_minutes ?? 5) * 60 * 1000;
   let lastCheckpointAt = Date.now();
@@ -1324,7 +1354,9 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
       checkpointDisabled, askQuestion, lastCheckpointAt, checkpointIntervalMs, elapsedMinutes,
       i, config: ctx.config, budgetTracker: ctx.budgetTracker, stageResults: ctx.stageResults, emitter, eventBase: ctx.eventBase, session: ctx.session, budgetSummary: ctx.budgetSummary, lastCheckpointSnapshot
     });
-    if (cpResult.action === "stop") return cpResult.result;
+    if (cpResult.action === "stop") {
+      return cpResult.result;
+    }
     checkpointDisabled = cpResult.checkpointDisabled;
     lastCheckpointAt = cpResult.lastCheckpointAt;
     if (cpResult.lastCheckpointSnapshot !== undefined) lastCheckpointSnapshot = cpResult.lastCheckpointSnapshot;
@@ -1336,11 +1368,63 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
     ctx.iteration = i;
 
     const iterResult = await runSingleIteration(ctx);
-    if (iterResult.action === "return") return iterResult.result;
+    if (iterResult.action === "return") {
+      return iterResult.result;
+    }
     if (iterResult.action === "retry") { i -= 1; }
   }
 
-  return handleMaxIterationsReached({ session: ctx.session, budgetSummary: ctx.budgetSummary, emitter, eventBase: ctx.eventBase, config: ctx.config, stageResults: ctx.stageResults, logger, askQuestion, task });
+  const maxIterResult = await handleMaxIterationsReached({ session: ctx.session, budgetSummary: ctx.budgetSummary, emitter, eventBase: ctx.eventBase, config: ctx.config, stageResults: ctx.stageResults, logger, askQuestion, task: loopTask });
+  return maxIterResult;
+}
+
+export async function runFlow({ task, config, logger, flags = {}, emitter = null, askQuestion = null, pgTaskId = null, pgProject = null }) {
+  const pipelineFlags = resolvePipelineFlags(config);
+
+  if (flags.dryRun) {
+    return handleDryRun({ task, config, flags, emitter, pipelineFlags });
+  }
+
+  const ctx = await initFlowContext({ task, config, logger, emitter, askQuestion, pgTaskId, pgProject, flags });
+
+  // --- HU Sub-Pipeline: run each certified HU as an independent iteration loop ---
+  if (needsSubPipeline(ctx.stageResults.huReviewer)) {
+    logger.info(`HU sub-pipeline: ${ctx.stageResults.huReviewer.certified} certified stories — running each as a sub-pipeline`);
+    emitProgress(emitter, makeEvent("hu:sub-pipeline:start", { ...ctx.eventBase, stage: "hu-sub-pipeline" }, {
+      message: `Running ${ctx.stageResults.huReviewer.certified} HUs as sub-pipelines`,
+      detail: { total: ctx.stageResults.huReviewer.total, certified: ctx.stageResults.huReviewer.certified }
+    }));
+
+    const subPipelineResult = await runHuSubPipeline({
+      huReviewerResult: ctx.stageResults.huReviewer,
+      runIterationFn: async (huTask) => runIterationLoop(ctx, { task: huTask, askQuestion, emitter, logger }),
+      emitter,
+      eventBase: ctx.eventBase,
+      logger
+    });
+
+    emitProgress(emitter, makeEvent("hu:sub-pipeline:end", { ...ctx.eventBase, stage: "hu-sub-pipeline" }, {
+      status: subPipelineResult.approved ? "ok" : "fail",
+      message: subPipelineResult.approved
+        ? "All HUs completed successfully"
+        : `Sub-pipeline finished with failures (${subPipelineResult.blockedIds.length} blocked)`,
+      detail: { results: subPipelineResult.results, blockedIds: subPipelineResult.blockedIds }
+    }));
+
+    const finalResult = {
+      approved: subPipelineResult.approved,
+      sessionId: ctx.session.id,
+      huResults: subPipelineResult.results,
+      blockedIds: subPipelineResult.blockedIds
+    };
+    await writeHistoryRecord({ sessionId: ctx.session.id, task, result: finalResult, logger });
+    return finalResult;
+  }
+
+  // --- Standard single-task pipeline (1 HU or no HU reviewer) ---
+  const result = await runIterationLoop(ctx, { task: ctx.plannedTask, askQuestion, emitter, logger });
+  await writeHistoryRecord({ sessionId: ctx.session.id, task, result, logger });
+  return result;
 }
 
 export async function resumeFlow({ sessionId, answer, config, logger, flags = {}, emitter = null, askQuestion = null }) {

package/src/planning-game/pipeline-adapter.js

@@ -119,6 +119,43 @@ export async function markPgCardToValidate({ pgCard, pgProject, config, session,
   }
 }
 
+/**
+ * Convert a PG card's structured data into HU stories for the hu-reviewer stage.
+ * Returns an array of story objects ({id, text}) or null if the card lacks structured data.
+ *
+ * @param {object} pgCard - The PG card object (from fetchCard)
+ * @returns {Array<{id: string, text: string}>|null}
+ */
+export function buildHuStoriesFromPgCard(pgCard) {
+  if (!pgCard?.descriptionStructured?.length) return null;
+
+  const parts = [];
+
+  // User stories (Como/Quiero/Para → As/I want/So that)
+  for (const s of pgCard.descriptionStructured) {
+    parts.push(`As ${s.role}, I want ${s.goal}, so that ${s.benefit}.`);
+  }
+
+  // Acceptance criteria
+  if (pgCard.acceptanceCriteriaStructured?.length) {
+    parts.push("", "Acceptance Criteria:");
+    for (const ac of pgCard.acceptanceCriteriaStructured) {
+      if (ac.given && ac.when && ac.then) {
+        parts.push(`- Given ${ac.given}, When ${ac.when}, Then ${ac.then}`);
+      } else if (ac.raw) {
+        parts.push(`- ${ac.raw}`);
+      }
+    }
+  } else if (pgCard.acceptanceCriteria) {
+    parts.push("", "Acceptance Criteria:", pgCard.acceptanceCriteria);
+  }
+
+  const storyId = pgCard.cardId || "HU-PG-001";
+  const storyText = parts.join("\n");
+
+  return [{ id: storyId, text: storyText }];
+}
+
 // --- Internal helpers ---
 
 async function markPgCardInProgress({ pgTaskId, pgProject, config, logger }) {

package/src/prompts/hu-reviewer.js

@@ -131,6 +131,61 @@ export function normalizeAcceptanceCriteria(criteria) {
   return criteria.map(detectAcFormat);
 }
 
+/**
+ * Build a prompt that asks the AI to decompose a complex task into 2-5 formal HUs.
+ * Each HU follows the role/goal/benefit format with acceptance criteria and optional dependencies.
+ * @param {string} task - The complex task description to decompose.
+ * @returns {string} The assembled decomposition prompt.
+ */
+export function buildDecompositionPrompt(task) {
+  const sections = [SUBAGENT_PREAMBLE];
+
+  sections.push("## Task Decomposition");
+  sections.push(
+    "You are a senior product owner. Decompose the following complex task into 2-5 independent, implementable user stories (HUs).",
+    "Each HU must be small enough to implement in a single iteration and must follow the role/goal/benefit format."
+  );
+
+  sections.push(`## Task to Decompose\n${task}`);
+
+  sections.push(
+    "Return a single valid JSON object and nothing else.",
+    `JSON schema: {"stories":[{"id":string,"title":string,"role":string,"goal":string,"benefit":string,"acceptanceCriteria":[string],"dependsOn":[string]}]}`,
+    "Rules:",
+    "- Generate between 2 and 5 HUs",
+    "- Each id must be unique, formatted as HU-DECOMP-NNN (e.g. HU-DECOMP-001)",
+    "- dependsOn is an array of other HU ids from this decomposition that must be completed first (empty array if no dependencies)",
+    "- acceptanceCriteria should be concrete, testable statements",
+    "- Order stories so that dependencies are respected (a story should only depend on stories with lower ids)"
+  );
+
+  return sections.join("\n\n");
+}
+
+/**
+ * Parse the output from a decomposition prompt.
+ * @param {string} raw - Raw text output from the agent.
+ * @returns {Array<{id: string, title: string, role: string, goal: string, benefit: string, acceptanceCriteria: string[], dependsOn: string[]}>|null}
+ */
+export function parseDecompositionOutput(raw) {
+  const parsed = extractFirstJson(raw);
+  if (!parsed || !Array.isArray(parsed.stories)) return null;
+
+  const stories = parsed.stories
+    .filter(s => s && s.id && s.title)
+    .map(s => ({
+      id: s.id,
+      title: s.title,
+      role: s.role || "developer",
+      goal: s.goal || s.title,
+      benefit: s.benefit || "",
+      acceptanceCriteria: Array.isArray(s.acceptanceCriteria) ? s.acceptanceCriteria : [],
+      dependsOn: Array.isArray(s.dependsOn) ? s.dependsOn : []
+    }));
+
+  return stories.length > 0 ? stories : null;
+}
+
 /**
  * Parse the raw output from the HU reviewer agent.
  * @param {string} raw - Raw text output from the agent.