karajan-code 1.36.1 → 1.38.0

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";
@@ -48,14 +49,16 @@ function applyModelSelection(triageOutput, config, emitter, eventBase) {
 
 export async function runTriageStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget }) {
   logger.setContext({ iteration: 0, stage: "triage" });
+
+  const triageProvider = config?.roles?.triage?.provider || coderRole.provider;
   emitProgress(
     emitter,
     makeEvent("triage:start", { ...eventBase, stage: "triage" }, {
-      message: "Triage classifying task complexity"
+      message: "Triage classifying task complexity",
+      detail: { provider: triageProvider, executorType: "agent" }
     })
   );
 
-  const triageProvider = config?.roles?.triage?.provider || coderRole.provider;
   const triageOnOutput = ({ stream, line }) => {
     emitProgress(emitter, makeEvent("agent:output", { ...eventBase, stage: "triage" }, {
       message: line,
@@ -132,7 +135,7 @@ export async function runTriageStage({ config, logger, emitter, eventBase, sessi
     makeEvent("triage:end", { ...eventBase, stage: "triage" }, {
       status: triageOutput.ok ? "ok" : "fail",
       message: triageOutput.ok ? "Triage completed" : `Triage failed: ${triageOutput.summary}`,
-      detail: stageResult
+      detail: { ...stageResult, provider: triageProvider, executorType: "agent" }
     })
   );
 
@@ -141,14 +144,16 @@ export async function runTriageStage({ config, logger, emitter, eventBase, sessi
 
 export async function runResearcherStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget }) {
   logger.setContext({ iteration: 0, stage: "researcher" });
+
+  const researcherProvider = config?.roles?.researcher?.provider || coderRole.provider;
   emitProgress(
     emitter,
     makeEvent("researcher:start", { ...eventBase, stage: "researcher" }, {
-      message: "Researcher investigating codebase"
+      message: "Researcher investigating codebase",
+      detail: { researcher: researcherProvider, provider: researcherProvider, executorType: "agent" }
     })
   );
 
-  const researcherProvider = config?.roles?.researcher?.provider || coderRole.provider;
   const researcherOnOutput = ({ stream, line }) => {
     emitProgress(emitter, makeEvent("agent:output", { ...eventBase, stage: "researcher" }, {
       message: line,
@@ -191,7 +196,8 @@ export async function runResearcherStage({ config, logger, emitter, eventBase, s
     emitter,
     makeEvent("researcher:end", { ...eventBase, stage: "researcher" }, {
       status: researchOutput.ok ? "ok" : "fail",
-      message: researchOutput.ok ? "Research completed" : `Research failed: ${researchOutput.summary}`
+      message: researchOutput.ok ? "Research completed" : `Research failed: ${researchOutput.summary}`,
+      detail: { provider: researcherProvider, executorType: "agent" }
     })
   );
 
@@ -260,14 +266,14 @@ async function handleArchitectClarification({ architectOutput, askQuestion, conf
 
 export async function runArchitectStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget, researchContext = null, discoverResult = null, triageLevel = null, askQuestion = null }) {
   logger.setContext({ iteration: 0, stage: "architect" });
+  const architectProvider = config?.roles?.architect?.provider || coderRole.provider;
   emitProgress(
     emitter,
     makeEvent("architect:start", { ...eventBase, stage: "architect" }, {
-      message: "Architect designing solution architecture"
+      message: "Architect designing solution architecture",
+      detail: { architect: architectProvider, provider: architectProvider, executorType: "agent" }
     })
   );
-
-  const architectProvider = config?.roles?.architect?.provider || coderRole.provider;
   const architectOnOutput = ({ stream, line }) => {
     emitProgress(emitter, makeEvent("agent:output", { ...eventBase, stage: "architect" }, {
       message: line,
@@ -330,7 +336,7 @@ export async function runArchitectStage({ config, logger, emitter, eventBase, se
     makeEvent("architect:end", { ...eventBase, stage: "architect" }, {
       status: architectOutput.ok ? "ok" : "fail",
       message: architectOutput.ok ? "Architecture completed" : `Architecture failed: ${architectOutput.summary}`,
-      detail: stageResult
+      detail: { ...stageResult, provider: architectProvider, executorType: "agent" }
     })
   );
 
@@ -373,7 +379,7 @@ export async function runPlannerStage({ config, logger, emitter, eventBase, sess
     emitter,
     makeEvent("planner:start", { ...eventBase, stage: "planner" }, {
       message: `Planner (${plannerRole.provider}) running`,
-      detail: { planner: plannerRole.provider }
+      detail: { planner: plannerRole.provider, provider: plannerRole.provider, executorType: "agent" }
     })
   );
 
@@ -416,7 +422,8 @@ export async function runPlannerStage({ config, logger, emitter, eventBase, sess
       emitter,
       makeEvent("planner:end", { ...eventBase, stage: "planner" }, {
         status: "fail",
-        message: `Planner failed: ${details}`
+        message: `Planner failed: ${details}`,
+        detail: { provider: plannerRole.provider, executorType: "agent" }
       })
     );
     throw new Error(`Planner failed: ${details}`);
@@ -436,7 +443,8 @@ export async function runPlannerStage({ config, logger, emitter, eventBase, sess
   emitProgress(
     emitter,
     makeEvent("planner:end", { ...eventBase, stage: "planner" }, {
-      message: "Planner completed"
+      message: "Planner completed",
+      detail: { provider: plannerRole.provider, executorType: "agent" }
     })
   );
 
@@ -445,14 +453,14 @@ export async function runPlannerStage({ config, logger, emitter, eventBase, sess
 
 export async function runDiscoverStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget }) {
   logger.setContext({ iteration: 0, stage: "discover" });
+  const discoverProvider = config?.roles?.discover?.provider || coderRole.provider;
   emitProgress(
     emitter,
     makeEvent("discover:start", { ...eventBase, stage: "discover" }, {
-      message: "Discover analyzing task for gaps"
+      message: "Discover analyzing task for gaps",
+      detail: { discover: discoverProvider, provider: discoverProvider, executorType: "agent" }
     })
   );
-
-  const discoverProvider = config?.roles?.discover?.provider || coderRole.provider;
   const discoverOnOutput = ({ stream, line }) => {
     emitProgress(emitter, makeEvent("agent:output", { ...eventBase, stage: "discover" }, {
       message: line,
@@ -504,7 +512,7 @@ export async function runDiscoverStage({ config, logger, emitter, eventBase, ses
     makeEvent("discover:end", { ...eventBase, stage: "discover" }, {
       status: discoverOutput.ok ? "ok" : "fail",
       message: discoverOutput.ok ? "Discovery completed" : `Discovery failed: ${discoverOutput.summary}`,
-      detail: stageResult
+      detail: { ...stageResult, provider: discoverProvider, executorType: "agent" }
     })
   );
 
@@ -512,43 +520,140 @@ 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<{stageResult: object}>}
+ * @returns {Promise<Array|null>} Array of decomposed HUs or null.
  */
-export async function runHuReviewerStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget, huFile, askQuestion }) {
-  logger.setContext({ iteration: 0, stage: "hu-reviewer" });
+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:start", { ...eventBase, stage: "hu-reviewer" }, {
-      message: "HU Reviewer certifying user stories"
+    makeEvent("hu-reviewer:decompose-start", { ...eventBase, stage: "hu-reviewer" }, {
+      message: "Decomposing complex task into formal HUs",
+      detail: { provider }
     })
   );
 
-  // --- Load YAML file ---
-  const yaml = await import("js-yaml");
-  const fs = await import("node:fs/promises");
-  let rawYaml;
+  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 {
-    rawYaml = await fs.readFile(huFile, "utf8");
+    result = await agent.runTask({ prompt, role: "hu-reviewer", onOutput: stall.onOutput });
   } 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 };
+    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, pgStories = null }) {
+  logger.setContext({ iteration: 0, stage: "hu-reviewer" });
+  const huReviewerProvider = config?.roles?.hu_reviewer?.provider || coderRole.provider;
+  emitProgress(
+    emitter,
+    makeEvent("hu-reviewer:start", { ...eventBase, stage: "hu-reviewer" }, {
+      message: "HU Reviewer certifying user stories",
+      detail: { provider: huReviewerProvider, executorType: "agent" }
+    })
+  );
+
   let stories;
-  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) {
@@ -569,7 +674,6 @@ export async function runHuReviewerStage({ config, logger, emitter, eventBase, s
   }
 
   // --- 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,
@@ -711,7 +815,7 @@ export async function runHuReviewerStage({ config, logger, emitter, eventBase, s
     makeEvent("hu-reviewer:end", { ...eventBase, stage: "hu-reviewer" }, {
       status: "ok",
       message: `HU Review complete: ${certifiedStories.length}/${batch.stories.length} certified`,
-      detail: stageResult
+      detail: { ...stageResult, provider: huReviewerProvider, executorType: "agent" }
     })
   );
 

package/src/orchestrator/preflight-checks.js

@@ -167,14 +167,14 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
     logger.info("Preflight: skipped (no sonar, no security)");
     emitProgress(emitter, makeEvent("preflight:end", { ...eventBase, stage: "preflight" }, {
       message: "Preflight skipped (no checks needed)",
-      detail: result
+      detail: { ...result, executorType: "local" }
     }));
     return result;
   }
 
   emitProgress(emitter, makeEvent("preflight:start", { ...eventBase, stage: "preflight" }, {
     message: "Running preflight environment checks",
-    detail: { sonarEnabled, securityEnabled }
+    detail: { sonarEnabled, securityEnabled, executorType: "local" }
   }));
 
   // --- 1. Docker (only if sonar enabled and not external) ---
@@ -286,7 +286,7 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
       : hasWarnings
         ? `Preflight completed with ${result.warnings.length} warning(s)`
         : "Preflight passed — all checks OK",
-    detail: result
+    detail: { ...result, executorType: "local" }
   }));
 
   return result;

package/src/orchestrator/solomon-escalation.js

@@ -9,11 +9,12 @@ export async function invokeSolomon({ config, logger, emitter, eventBase, stage,
     return escalateToHuman({ askQuestion, session, emitter, eventBase, stage, conflict, iteration });
   }
 
+  const solomonProvider = config?.roles?.solomon?.provider || "gemini";
   emitProgress(
     emitter,
     makeEvent("solomon:start", { ...eventBase, stage: "solomon" }, {
       message: `Solomon arbitrating ${stage} conflict`,
-      detail: { conflictStage: stage }
+      detail: { conflictStage: stage, provider: solomonProvider, executorType: "agent" }
     })
   );
 
@@ -41,7 +42,7 @@ export async function invokeSolomon({ config, logger, emitter, eventBase, stage,
       message: ruling.ok
         ? `Solomon ruling: ${ruling.result?.ruling || "unknown"}`
         : `Solomon failed: ${(solomonError || ruling.summary || "unknown error").slice(0, 200)}`,
-      detail: ruling.result
+      detail: { ...ruling.result, provider: solomonProvider, executorType: "agent" }
     })
   );
 

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";
@@ -177,7 +178,8 @@ function createBudgetManager({ config, emitter, eventBase }) {
           max_budget_usd: budgetLimit,
           warn_threshold_pct: warnThresholdPct,
           pct_used: Number(pctUsed.toFixed(2)),
-          remaining_usd: budgetTracker.remaining(budgetLimit)
+          remaining_usd: budgetTracker.remaining(budgetLimit),
+          executorType: "system"
         }
       })
     );
@@ -379,7 +381,7 @@ async function handleCheckpoint({ checkpointDisabled, askQuestion, lastCheckpoin
       emitter,
       makeEvent("session:checkpoint", { ...eventBase, iteration: i, stage: "checkpoint" }, {
         message: `Checkpoint: progress detected, continuing (${elapsedStr} min elapsed)`,
-        detail: { elapsed_minutes: Number(elapsedStr), iterations_done: i - 1, stages: stagesCompleted, auto_continued: true }
+        detail: { elapsed_minutes: Number(elapsedStr), iterations_done: i - 1, stages: stagesCompleted, auto_continued: true, executorType: "system" }
       })
     );
     return { action: "continue_loop", checkpointDisabled, lastCheckpointAt: Date.now(), lastCheckpointSnapshot: newSnapshot };
@@ -815,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;
   }
 
@@ -843,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,
@@ -956,7 +972,7 @@ async function runGuardStages({ config, logger, emitter, eventBase, session, ite
       const warnings = outputResult.violations.filter(v => v.severity === "warning");
       emitProgress(emitter, makeEvent("guard:output", { ...eventBase, stage: "guard" }, {
         message: `Output guard: ${critical.length} critical, ${warnings.length} warnings`,
-        detail: { violations: outputResult.violations }
+        detail: { violations: outputResult.violations, executorType: "local" }
       }));
       logger.info(`Output guard: ${outputResult.violations.length} violation(s) found`);
       for (const v of outputResult.violations) {
@@ -983,7 +999,7 @@ async function runGuardStages({ config, logger, emitter, eventBase, session, ite
     if (!perfResult.skipped && perfResult.violations.length > 0) {
       emitProgress(emitter, makeEvent("guard:perf", { ...eventBase, stage: "guard" }, {
         message: `Perf guard: ${perfResult.violations.length} issue(s)`,
-        detail: { violations: perfResult.violations }
+        detail: { violations: perfResult.violations, executorType: "local" }
       }));
       logger.info(`Perf guard: ${perfResult.violations.length} issue(s) found`);
       for (const v of perfResult.violations) {
@@ -1165,7 +1181,7 @@ async function initFlowContext({ task, config, logger, emitter, askQuestion, pgT
     logger.info(`RTK detected (${rtkResult.version}) — instructing agents to prefix Bash commands with rtk`);
     emitProgress(emitter, makeEvent("rtk:detected", ctx.eventBase, {
       message: "RTK detected — agent commands will use token optimization",
-      detail: { version: rtkResult.version }
+      detail: { version: rtkResult.version, executorType: "local" }
     }));
   }
 
@@ -1300,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();
@@ -1323,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;
@@ -1335,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 }) {