karajan-code 1.45.0 → 1.47.0

package/README.md

@@ -90,7 +90,7 @@ This is the primary use case. Karajan runs as an MCP server inside Claude Code,
 You → Claude Code → kj_run (via MCP) → triage → coder → sonar → reviewer → tester → security
 ```
 
-The MCP server auto-registers during `npm install`. Your AI agent sees 21 tools (`kj_run`, `kj_code`, `kj_review`, etc.) and uses them as needed.
+The MCP server auto-registers during `npm install`. Your AI agent sees 23 tools (`kj_run`, `kj_code`, `kj_review`, etc.) and uses them as needed.
 
 **The problem**: when Karajan runs inside an AI agent, you lose visibility. The agent shows you the final result, but not the pipeline stages, iterations, or Solomon decisions happening in real time.
 
@@ -177,7 +177,7 @@ hu-reviewer? → triage → discover? → architect? → planner? → coder →
 
 Mix and match. Use Claude as coder and Codex as reviewer. Karajan auto-detects installed agents during `kj init`.
 
-## MCP server (21 tools)
+## MCP server (23 tools)
 
 After `npm install -g karajan-code`, the MCP server auto-registers in Claude and Codex. Manual config if needed:
 
@@ -189,7 +189,7 @@ After `npm install -g karajan-code`, the MCP server auto-registers in Claude and
 # command = "karajan-mcp"
 ```
 
-**21 tools** available: `kj_run`, `kj_code`, `kj_review`, `kj_plan`, `kj_audit`, `kj_scan`, `kj_doctor`, `kj_config`, `kj_report`, `kj_resume`, `kj_roles`, `kj_agents`, `kj_preflight`, `kj_status`, `kj_init`, `kj_discover`, `kj_triage`, `kj_researcher`, `kj_architect`, `kj_impeccable`, `kj_hu`.
+**23 tools** available: `kj_run`, `kj_code`, `kj_review`, `kj_plan`, `kj_audit`, `kj_scan`, `kj_doctor`, `kj_config`, `kj_report`, `kj_resume`, `kj_roles`, `kj_agents`, `kj_preflight`, `kj_status`, `kj_init`, `kj_discover`, `kj_triage`, `kj_researcher`, `kj_architect`, `kj_impeccable`, `kj_hu`, `kj_skills`, `kj_suggest`.
 
 Use `kj-tail` in a separate terminal to see what the pipeline is doing in real time (see [Three ways to use Karajan](#three-ways-to-use-karajan)).
 
@@ -243,7 +243,7 @@ Not nostalgia, not stubbornness. I've been using JavaScript since 1997, when Bre
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Run 2142 tests with Vitest
+npm test              # Run 2318 tests with Vitest
 npm run validate      # Lint + test
 ```
 

package/docs/README.es.md

@@ -82,7 +82,7 @@ Este es el caso de uso principal. Karajan corre como servidor MCP dentro de Clau
 Tu → Claude Code → kj_run (via MCP) → triage → coder → sonar → reviewer → tester → security
 ```
 
-El servidor MCP se auto-registra durante `npm install`. Tu agente de IA ve 21 herramientas (`kj_run`, `kj_code`, `kj_review`, `kj_hu`, etc.) y las usa segun necesite.
+El servidor MCP se auto-registra durante `npm install`. Tu agente de IA ve 23 herramientas (`kj_run`, `kj_code`, `kj_review`, `kj_hu`, etc.) y las usa segun necesite.
 
 **El problema**: cuando Karajan corre dentro de un agente de IA, pierdes visibilidad. El agente te muestra el resultado final, pero no las etapas del pipeline, iteraciones o decisiones de Solomon en tiempo real.
 
@@ -147,7 +147,7 @@ hu-reviewer? → triage → discover? → architect? → planner? → coder →
 
 Mezcla y combina. Usa Claude como coder y Codex como reviewer. Karajan auto-detecta agentes instalados durante `kj init`.
 
-## Servidor MCP (21 herramientas)
+## Servidor MCP (23 herramientas)
 
 Tras `npm install -g karajan-code`, el servidor MCP se auto-registra en Claude y Codex. Config manual si es necesario:
 
@@ -159,7 +159,7 @@ Tras `npm install -g karajan-code`, el servidor MCP se auto-registra en Claude y
 # command = "karajan-mcp"
 ```
 
-**21 herramientas** disponibles: `kj_run`, `kj_code`, `kj_review`, `kj_plan`, `kj_audit`, `kj_scan`, `kj_doctor`, `kj_config`, `kj_report`, `kj_resume`, `kj_roles`, `kj_agents`, `kj_preflight`, `kj_status`, `kj_init`, `kj_discover`, `kj_triage`, `kj_researcher`, `kj_architect`, `kj_impeccable`, `kj_hu`.
+**23 herramientas** disponibles: `kj_run`, `kj_code`, `kj_review`, `kj_plan`, `kj_audit`, `kj_scan`, `kj_doctor`, `kj_config`, `kj_report`, `kj_resume`, `kj_roles`, `kj_agents`, `kj_preflight`, `kj_status`, `kj_init`, `kj_discover`, `kj_triage`, `kj_researcher`, `kj_architect`, `kj_impeccable`, `kj_hu`, `kj_skills`, `kj_suggest`.
 
 Usa `kj-tail` en un terminal separado para ver lo que el pipeline esta haciendo en tiempo real (ver [Tres formas de usar Karajan](#tres-formas-de-usar-karajan)).
 
@@ -213,7 +213,7 @@ No es nostalgia ni cabezoneria. Es que llevo usando JavaScript desde 1997, cuand
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Ejecutar 2142 tests con Vitest
+npm test              # Ejecutar 2318 tests con Vitest
 npm run validate      # Lint + test
 ```
 

package/package.json

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

package/scripts/build-sea.mjs

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+/**
+ * build-sea.mjs — Build a Node.js Single Executable Application (SEA) binary.
+ *
+ * Steps:
+ *   1. esbuild bundles src/cli.js -> dist/kj-bundle.cjs (CJS, all deps inlined)
+ *   2. Generate SEA preparation blob via node --experimental-sea-config
+ *   3. Copy the current node binary to dist/kj (or dist/kj.exe on Windows)
+ *   4. Inject the blob into the binary with postject
+ *   5. (macOS only) Re-sign the binary with ad-hoc signature
+ *
+ * Requirements (installed globally or via npx):
+ *   - esbuild
+ *   - postject
+ *
+ * Usage:
+ *   node scripts/build-sea.mjs
+ */
+
+import { execSync } from "node:child_process";
+import { cpSync, mkdirSync, writeFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const ROOT = path.resolve(__dirname, "..");
+const DIST = path.join(ROOT, "dist");
+
+const isWindows = process.platform === "win32";
+const isMac = process.platform === "darwin";
+const binaryName = isWindows ? "kj.exe" : "kj";
+const binaryPath = path.join(DIST, binaryName);
+
+function run(cmd, opts = {}) {
+  console.log(`  $ ${cmd}`);
+  execSync(cmd, { cwd: ROOT, stdio: "inherit", ...opts });
+}
+
+function formatBytes(bytes) {
+  const mb = bytes / (1024 * 1024);
+  return `${mb.toFixed(1)} MB`;
+}
+
+async function main() {
+  try {
+    console.log("\n=== Karajan Code — SEA Build ===\n");
+
+    // ── Step 0: Prepare dist directory ──────────────────────────────
+    mkdirSync(DIST, { recursive: true });
+
+    // ── Step 1: Bundle with esbuild ─────────────────────────────────
+    console.log("[1/5] Bundling with esbuild...");
+    const { seaBuildOptions } = await import("./esbuild-sea.config.mjs");
+    const esbuild = await import("esbuild");
+    await esbuild.build(seaBuildOptions);
+    console.log("      -> dist/kj-bundle.cjs created.\n");
+
+    // ── Step 2: Generate SEA blob ───────────────────────────────────
+    console.log("[2/5] Generating SEA preparation blob...");
+    const seaConfig = {
+      main: "dist/kj-bundle.cjs",
+      output: "dist/sea-prep.blob",
+      disableExperimentalSEAWarning: true,
+    };
+    writeFileSync(
+      path.join(DIST, "sea-config.json"),
+      JSON.stringify(seaConfig, null, 2),
+    );
+    run("node --experimental-sea-config dist/sea-config.json");
+    console.log("      -> dist/sea-prep.blob created.\n");
+
+    // ── Step 3: Copy node binary ────────────────────────────────────
+    console.log("[3/5] Copying node binary...");
+    cpSync(process.execPath, binaryPath);
+    console.log(`      -> ${binaryName} copied.\n`);
+
+    // ── Step 3.5: Remove signature on macOS (required before postject)
+    if (isMac) {
+      console.log("[3.5] Removing macOS code signature...");
+      run(`codesign --remove-signature ${binaryPath}`);
+      console.log("      -> Signature removed.\n");
+    }
+
+    // ── Step 4: Inject blob with postject ───────────────────────────
+    console.log("[4/5] Injecting SEA blob with postject...");
+    const postjectCmd = [
+      `npx postject ${binaryPath}`,
+      "NODE_SEA_BLOB dist/sea-prep.blob",
+      "--sentinel-fuse NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2",
+    ].join(" ");
+    run(postjectCmd);
+    console.log("      -> Blob injected.\n");
+
+    // ── Step 4.5: Re-sign on macOS ──────────────────────────────────
+    if (isMac) {
+      console.log("[4.5] Re-signing binary (ad-hoc)...");
+      run(`codesign --sign - ${binaryPath}`);
+      console.log("      -> Binary signed.\n");
+    }
+
+    // ── Done ────────────────────────────────────────────────────────
+    const stat = statSync(binaryPath);
+    console.log("[5/5] Done!");
+    console.log(`      Binary: ${binaryPath}`);
+    console.log(`      Size:   ${formatBytes(stat.size)}`);
+    console.log("");
+  } catch (err) {
+    console.error("\n=== SEA Build FAILED ===\n");
+    console.error(err.message || err);
+    console.error(
+      "\nNote: esbuild may fail to bundle certain ESM-only dependencies",
+    );
+    console.error(
+      "or native modules. Check the error above for details.\n",
+    );
+    process.exit(1);
+  }
+}
+
+main();

package/scripts/esbuild-sea.config.mjs

@@ -0,0 +1,33 @@
+/**
+ * esbuild configuration for Node.js SEA (Single Executable Application) bundle.
+ *
+ * Bundles the entire CLI into a single CJS file suitable for SEA injection.
+ * SEA requires CJS format — ESM entry points are transpiled by esbuild.
+ */
+
+/** @type {import('esbuild').BuildOptions} */
+export const seaBuildOptions = {
+  entryPoints: ["src/cli.js"],
+  outfile: "dist/kj-bundle.cjs",
+  format: "cjs",
+  platform: "node",
+  target: "node20",
+  bundle: true,
+  minify: false,
+  // Bundle everything — no externals. The binary must be fully self-contained.
+  external: [],
+  // Shim for CJS compatibility in the SEA context.
+  banner: {
+    js: [
+      "/* Karajan Code — SEA bundle */",
+      "/* eslint-disable */",
+      'const __importMetaUrl = require("node:url").pathToFileURL(__filename).href;',
+    ].join("\n"),
+  },
+  // Replace import.meta.url references with the CJS-compatible shim variable.
+  define: {
+    "import.meta.url": "__importMetaUrl",
+  },
+  // Log level for debugging build issues.
+  logLevel: "info",
+};

package/src/hu/parallel-executor.js

@@ -0,0 +1,94 @@
+/**
+ * Parallel HU execution using git worktrees.
+ *
+ * Analyses the dependency graph to find groups of HUs that can run
+ * concurrently, creates isolated git worktrees for each parallel HU,
+ * and merges results back sequentially.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import path from "node:path";
+
+const execFileAsync = promisify(execFile);
+
+/** Directory inside the project where worktrees are created. */
+const WORKTREE_DIR = ".kj/worktrees";
+
+/**
+ * Given stories and their topological order, return groups (batches) of HUs
+ * that can execute in parallel.  Two HUs can run in parallel when neither
+ * depends (directly or transitively) on the other.
+ *
+ * The algorithm walks the topological order and assigns each HU to the
+ * earliest batch where all its dependencies have already been placed in
+ * a previous batch.
+ *
+ * @param {Array<{id: string, blocked_by?: string[]}>} stories
+ * @param {string[]} order - topologically sorted story IDs
+ * @returns {string[][]} Array of batches; each batch is an array of story IDs.
+ */
+export function findParallelGroups(stories, order) {
+  if (!order.length) return [];
+
+  const storyMap = new Map(stories.map(s => [s.id, s]));
+  // batchIndex[id] = index of the batch the story was assigned to
+  const batchIndex = new Map();
+  const batches = [];
+
+  for (const id of order) {
+    const story = storyMap.get(id);
+    const deps = story?.blocked_by || [];
+    // This HU must go into the batch *after* the latest dependency batch
+    let earliest = 0;
+    for (const dep of deps) {
+      if (batchIndex.has(dep)) {
+        earliest = Math.max(earliest, batchIndex.get(dep) + 1);
+      }
+    }
+    if (!batches[earliest]) batches[earliest] = [];
+    batches[earliest].push(id);
+    batchIndex.set(id, earliest);
+  }
+
+  return batches;
+}
+
+/**
+ * Create a git worktree for a given HU.
+ *
+ * @param {string} projectDir - Root directory of the git repo.
+ * @param {string} huId - Story identifier (used for branch and directory name).
+ * @returns {Promise<string>} Absolute path to the created worktree.
+ */
+export async function createWorktree(projectDir, huId) {
+  const worktreePath = path.join(projectDir, WORKTREE_DIR, huId);
+  const branchName = `kj-hu-${huId}`;
+  await execFileAsync("git", ["worktree", "add", worktreePath, "-b", branchName], { cwd: projectDir });
+  return worktreePath;
+}
+
+/**
+ * Remove a git worktree (forcefully).
+ *
+ * @param {string} projectDir - Root directory of the git repo.
+ * @param {string} huId - Story identifier.
+ * @returns {Promise<void>}
+ */
+export async function removeWorktree(projectDir, huId) {
+  const worktreePath = path.join(projectDir, WORKTREE_DIR, huId);
+  await execFileAsync("git", ["worktree", "remove", worktreePath, "--force"], { cwd: projectDir });
+}
+
+/**
+ * Merge a worktree branch back into the current branch and clean up.
+ *
+ * @param {string} projectDir - Root directory of the git repo.
+ * @param {string} huId - Story identifier.
+ * @returns {Promise<void>}
+ */
+export async function mergeWorktree(projectDir, huId) {
+  const branchName = `kj-hu-${huId}`;
+  await execFileAsync("git", ["merge", branchName, "--no-edit"], { cwd: projectDir });
+  await removeWorktree(projectDir, huId);
+  await execFileAsync("git", ["branch", "-d", branchName], { cwd: projectDir });
+}

package/src/hu/split-validator.js

@@ -0,0 +1,143 @@
+/**
+ * Validates sub-HUs produced by the splitting generator against 4 mandatory criteria.
+ * Uses heuristic checks (no AI calls).
+ */
+
+/** Maximum devPoints for a sub-HU to be considered completable in 3 days. */
+const MAX_DEV_POINTS = 3;
+
+/** Text length threshold — stories longer than this are likely too big for 3 days. */
+const TEXT_LENGTH_THRESHOLD = 2000;
+
+/**
+ * Regex patterns that indicate a horizontal (layer-only) split — both EN and ES.
+ * @type {RegExp[]}
+ */
+export const HORIZONTAL_PATTERNS = [
+  /\bonly the (api|backend|frontend|database|ui)\b/i,
+  /\bjust the (endpoint|interface|model|schema)\b/i,
+  /\bsolo (el endpoint|la interfaz|el modelo|la base de datos|el backend|el frontend)\b/i,
+  /\bimplementar (el|la|los) \w+ sin\b/i
+];
+
+/**
+ * Patterns that indicate a sub-HU is not independently deployable.
+ * @type {RegExp[]}
+ */
+const DEPENDENCY_PATTERNS = [
+  /\bpart \d+ of \d+\b/i,
+  /\bdepends on .+ being deployed first\b/i,
+  /\brequires .+ to be completed before\b/i,
+  /\bparte \d+ de \d+\b/i
+];
+
+/**
+ * Check whether the text has a role/goal/benefit structure (independently valuable).
+ * Looks for patterns like "As a <role>, I want <goal> so that <benefit>".
+ * Also accepts structured objects with role/goal/benefit fields.
+ * @param {object} subHU
+ * @returns {boolean}
+ */
+function checkIndependentlyValuable(subHU) {
+  // Check structured fields first
+  const desc = subHU.descriptionStructured || subHU.description_structured;
+  if (Array.isArray(desc) && desc.length > 0) {
+    const entry = desc[0];
+    if (entry.role && entry.goal && entry.benefit) return true;
+  }
+  if (subHU.role && subHU.goal && subHU.benefit) return true;
+
+  // Check text for As a/I want/so that pattern
+  const text = extractText(subHU);
+  const hasRole = /\b(as an?|como)\b/i.test(text);
+  const hasGoal = /\b(i want|quiero|i need|necesito)\b/i.test(text);
+  const hasBenefit = /\b(so that|para que|in order to|de modo que)\b/i.test(text);
+  return hasRole && hasGoal && hasBenefit;
+}
+
+/**
+ * Check that the sub-HU does not reference sequential dependencies.
+ * @param {object} subHU
+ * @returns {boolean}
+ */
+function checkDeployableAlone(subHU) {
+  const text = extractText(subHU);
+  return !DEPENDENCY_PATTERNS.some(p => p.test(text));
+}
+
+/**
+ * Check whether the sub-HU is completable within 3 days.
+ * Uses devPoints if available, otherwise falls back to text length heuristic.
+ * @param {object} subHU
+ * @returns {boolean}
+ */
+function checkCompletableIn3Days(subHU) {
+  if (typeof subHU.devPoints === "number") {
+    return subHU.devPoints <= MAX_DEV_POINTS;
+  }
+  const text = extractText(subHU);
+  return text.length <= TEXT_LENGTH_THRESHOLD;
+}
+
+/**
+ * Check the sub-HU is a vertical slice (not a horizontal layer-only story).
+ * @param {object} subHU
+ * @returns {boolean}
+ */
+function checkIsVertical(subHU) {
+  const text = extractText(subHU);
+  return !HORIZONTAL_PATTERNS.some(p => p.test(text));
+}
+
+/**
+ * Extract all relevant text from a sub-HU for pattern matching.
+ * @param {object} subHU
+ * @returns {string}
+ */
+function extractText(subHU) {
+  const parts = [
+    subHU.title,
+    subHU.text,
+    subHU.description,
+    subHU.acceptanceCriteria
+  ].filter(Boolean);
+
+  // Include structured description text
+  const desc = subHU.descriptionStructured || subHU.description_structured;
+  if (Array.isArray(desc)) {
+    for (const entry of desc) {
+      if (entry.role) parts.push(entry.role);
+      if (entry.goal) parts.push(entry.goal);
+      if (entry.benefit) parts.push(entry.benefit);
+    }
+  }
+
+  return parts.join(" ");
+}
+
+/**
+ * Validate a sub-HU against 4 mandatory split criteria.
+ *
+ * @param {object} subHU - The sub-HU object to validate.
+ * @returns {{ valid: boolean, criteria: { independently_valuable: boolean, deployable_alone: boolean, completable_in_3_days: boolean, is_vertical: boolean }, failures: string[] }}
+ */
+export function validateSplitCriteria(subHU) {
+  const criteria = {
+    independently_valuable: checkIndependentlyValuable(subHU),
+    deployable_alone: checkDeployableAlone(subHU),
+    completable_in_3_days: checkCompletableIn3Days(subHU),
+    is_vertical: checkIsVertical(subHU)
+  };
+
+  const failures = [];
+  if (!criteria.independently_valuable) failures.push("Sub-HU does not describe independent user-facing value (missing role/goal/benefit)");
+  if (!criteria.deployable_alone) failures.push("Sub-HU references sequential deployment dependencies");
+  if (!criteria.completable_in_3_days) failures.push("Sub-HU appears too large to complete in 3 days");
+  if (!criteria.is_vertical) failures.push("Sub-HU describes a horizontal slice instead of a vertical one");
+
+  return {
+    valid: failures.length === 0,
+    criteria,
+    failures
+  };
+}

package/src/hu/splitting-detector.js

@@ -0,0 +1,158 @@
+/**
+ * Heuristic-based HU splitting detection.
+ * Analyzes user story text for indicators that suggest the HU should be split.
+ */
+
+/**
+ * @typedef {object} SplitIndicator
+ * @property {string} type - Indicator type (e.g. "multiple_and", "multiple_roles")
+ * @property {string} detail - Human-readable description of what was detected
+ * @property {number} weight - How strongly this indicator suggests splitting (1-3)
+ */
+
+/** @type {Record<string, string>} */
+export const HEURISTIC_DESCRIPTIONS = Object.freeze({
+  workflow_steps: "Split by workflow steps: each step of the user journey becomes its own HU.",
+  data_entity: "Split by data entity: each distinct entity (model, resource) gets its own HU.",
+  user_role: "Split by user role: each actor/persona gets their own HU.",
+  crud_operations: "Split by CRUD operations: separate create, read, update, delete into individual HUs.",
+  happy_sad_path: "Split by happy/sad path: main flow in one HU, error/edge cases in another.",
+  interface_boundary: "Split by interface boundary: frontend, backend, integration each get their own HU."
+});
+
+const HEURISTIC_KEYS = Object.keys(HEURISTIC_DESCRIPTIONS);
+
+/**
+ * Detect indicators in HU text that suggest the story should be split.
+ * @param {string} text - The HU text to analyze.
+ * @returns {SplitIndicator[]} Array of detected indicators (empty if no splitting needed).
+ */
+export function detectIndicators(text) {
+  if (!text || typeof text !== "string") return [];
+
+  const indicators = [];
+  const lower = text.toLowerCase();
+
+  // Multiple "and" connectors suggest compound story
+  const andMatches = lower.match(/\band\b/g);
+  if (andMatches && andMatches.length >= 2) {
+    indicators.push({
+      type: "multiple_and",
+      detail: `Found ${andMatches.length} "and" connectors suggesting compound story`,
+      weight: 2
+    });
+  }
+
+  // Multiple roles mentioned
+  const rolePatterns = /\bas (?:a |an )?(\w+)/gi;
+  const roles = [...text.matchAll(rolePatterns)].map(m => m[1].toLowerCase());
+  const uniqueRoles = new Set(roles);
+  if (uniqueRoles.size > 1) {
+    indicators.push({
+      type: "multiple_roles",
+      detail: `Multiple roles detected: ${[...uniqueRoles].join(", ")}`,
+      weight: 3
+    });
+  }
+
+  // Multiple acceptance criteria groups or numbered lists
+  const acCount = (text.match(/^[-*\d+.]\s/gm) || []).length;
+  if (acCount > 5) {
+    indicators.push({
+      type: "many_acceptance_criteria",
+      detail: `${acCount} acceptance criteria items detected`,
+      weight: 2
+    });
+  }
+
+  // CRUD keywords
+  const crudKeywords = ["create", "read", "update", "delete", "edit", "remove", "list", "view"];
+  const foundCrud = crudKeywords.filter(kw => lower.includes(kw));
+  if (foundCrud.length >= 3) {
+    indicators.push({
+      type: "crud_operations",
+      detail: `Multiple CRUD operations: ${foundCrud.join(", ")}`,
+      weight: 2
+    });
+  }
+
+  // Multiple "so that" / "in order to" benefits
+  const benefitMatches = lower.match(/\b(so that|in order to)\b/g);
+  if (benefitMatches && benefitMatches.length > 1) {
+    indicators.push({
+      type: "multiple_benefits",
+      detail: `${benefitMatches.length} benefit clauses detected`,
+      weight: 2
+    });
+  }
+
+  // Workflow/step keywords
+  const stepKeywords = ["first", "then", "after that", "finally", "next", "step"];
+  const foundSteps = stepKeywords.filter(kw => lower.includes(kw));
+  if (foundSteps.length >= 2) {
+    indicators.push({
+      type: "workflow_steps",
+      detail: `Sequential workflow indicators: ${foundSteps.join(", ")}`,
+      weight: 2
+    });
+  }
+
+  return indicators;
+}
+
+/**
+ * Select the best splitting heuristic based on detected indicators.
+ * @param {SplitIndicator[]} indicators - Detected split indicators.
+ * @param {string[]} [excludeHeuristics=[]] - Heuristics to skip (already tried).
+ * @returns {string|null} The selected heuristic key, or null if none applicable.
+ */
+export function selectHeuristic(indicators, excludeHeuristics = []) {
+  if (!indicators || indicators.length === 0) return null;
+
+  const excluded = new Set(excludeHeuristics);
+
+  // Map indicator types to preferred heuristics
+  const heuristicScores = {};
+  for (const key of HEURISTIC_KEYS) {
+    if (!excluded.has(key)) {
+      heuristicScores[key] = 0;
+    }
+  }
+
+  for (const ind of indicators) {
+    switch (ind.type) {
+      case "multiple_roles":
+        if (!excluded.has("user_role")) heuristicScores.user_role = (heuristicScores.user_role || 0) + ind.weight;
+        break;
+      case "crud_operations":
+        if (!excluded.has("crud_operations")) heuristicScores.crud_operations = (heuristicScores.crud_operations || 0) + ind.weight;
+        break;
+      case "workflow_steps":
+        if (!excluded.has("workflow_steps")) heuristicScores.workflow_steps = (heuristicScores.workflow_steps || 0) + ind.weight;
+        break;
+      case "multiple_and":
+      case "many_acceptance_criteria":
+        if (!excluded.has("workflow_steps")) heuristicScores.workflow_steps = (heuristicScores.workflow_steps || 0) + ind.weight;
+        if (!excluded.has("data_entity")) heuristicScores.data_entity = (heuristicScores.data_entity || 0) + ind.weight;
+        break;
+      case "multiple_benefits":
+        if (!excluded.has("happy_sad_path")) heuristicScores.happy_sad_path = (heuristicScores.happy_sad_path || 0) + ind.weight;
+        if (!excluded.has("interface_boundary")) heuristicScores.interface_boundary = (heuristicScores.interface_boundary || 0) + ind.weight;
+        break;
+      default:
+        break;
+    }
+  }
+
+  // Pick highest scoring non-excluded heuristic
+  let best = null;
+  let bestScore = 0;
+  for (const [key, score] of Object.entries(heuristicScores)) {
+    if (score > bestScore) {
+      bestScore = score;
+      best = key;
+    }
+  }
+
+  return best;
+}

package/src/hu/splitting-generator.js

@@ -0,0 +1,170 @@
+/**
+ * HU Splitting Generator.
+ * Uses an AI agent to split a HU based on a selected heuristic,
+ * then formats proposals for FDE confirmation.
+ */
+
+import { createAgent } from "../agents/index.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+import { HEURISTIC_DESCRIPTIONS } from "./splitting-detector.js";
+
+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 splitting this HU."
+].join(" ");
+
+/**
+ * Build the prompt for the AI agent that will split the HU.
+ * @param {{id: string, text: string}} hu - The HU to split.
+ * @param {string} heuristic - The heuristic key to apply.
+ * @returns {string} The assembled prompt.
+ */
+export function buildSplitPrompt(hu, heuristic) {
+  const heuristicDesc = HEURISTIC_DESCRIPTIONS[heuristic] || heuristic;
+  const baseId = hu.id || "HU-XXX";
+
+  const sections = [SUBAGENT_PREAMBLE];
+
+  sections.push("## Task: Split User Story");
+  sections.push(
+    "You are a senior product owner. Split the following user story into smaller, independent sub-HUs.",
+    `Apply this splitting heuristic: **${heuristicDesc}**`
+  );
+
+  sections.push(`## Original User Story (${baseId})\n${hu.text}`);
+
+  sections.push(
+    "## Output Requirements",
+    "Return a single valid JSON object and nothing else.",
+    `JSON schema: {"subHUs":[{"id":string,"title":string,"text":string,"acceptanceCriteria":[string],"blocked_by":[string]}],"heuristic":string,"reason":string}`,
+    "Rules:",
+    `- Each sub-HU id must follow the pattern: ${baseId}-A, ${baseId}-B, ${baseId}-C, etc.`,
+    "- text must follow role/goal/benefit format: 'As a [role], I want to [goal], so that [benefit]'",
+    "- acceptanceCriteria must be concrete, testable statements",
+    "- blocked_by: first sub-HU has empty array, each subsequent one is blocked by the previous (sequential chain)",
+    "- Generate between 2 and 5 sub-HUs",
+    `- heuristic must be "${heuristic}"`,
+    "- reason must explain why this heuristic was applied"
+  );
+
+  return sections.join("\n\n");
+}
+
+/**
+ * Parse the AI agent's split output into a structured proposal.
+ * @param {string} raw - Raw agent output text.
+ * @returns {{subHUs: Array, heuristic: string, reason: string}|null}
+ */
+export function parseSplitOutput(raw) {
+  const parsed = extractFirstJson(raw);
+  if (!parsed || !Array.isArray(parsed.subHUs) || parsed.subHUs.length < 2) return null;
+
+  const subHUs = parsed.subHUs
+    .filter(s => s && s.id && s.title && s.text)
+    .map(s => ({
+      id: s.id,
+      title: s.title,
+      text: s.text,
+      acceptanceCriteria: Array.isArray(s.acceptanceCriteria) ? s.acceptanceCriteria : [],
+      blocked_by: Array.isArray(s.blocked_by) ? s.blocked_by : []
+    }));
+
+  if (subHUs.length < 2) return null;
+
+  return {
+    subHUs,
+    heuristic: parsed.heuristic || "unknown",
+    reason: parsed.reason || ""
+  };
+}
+
+/**
+ * Use an AI agent to generate a split proposal for a HU based on a heuristic.
+ * @param {{id: string, text: string}} hu - The HU to split.
+ * @param {string} heuristic - The heuristic key to apply.
+ * @param {object} config - Karajan config object.
+ * @param {object} logger - Logger instance.
+ * @returns {Promise<{subHUs: Array, heuristic: string, reason: string}|null>}
+ */
+export async function generateSplitProposal(hu, heuristic, config, logger) {
+  const provider = config?.roles?.hu_reviewer?.provider
+    || config?.roles?.coder?.provider
+    || "claude";
+
+  const agent = createAgent(provider, config, logger);
+  const prompt = buildSplitPrompt(hu, heuristic);
+
+  let result;
+  try {
+    result = await agent.runTask({ prompt, role: "hu-splitter" });
+  } catch (err) {
+    logger.warn(`HU split generation threw: ${err.message}`);
+    return null;
+  }
+
+  if (!result.ok) {
+    logger.warn(`HU split generation failed: ${result.error || "unknown"}`);
+    return null;
+  }
+
+  const proposal = parseSplitOutput(result.output);
+  if (!proposal) {
+    logger.warn("HU split generation returned unparseable output");
+    return null;
+  }
+
+  return proposal;
+}
+
+/**
+ * Format a split proposal as human-readable text for the FDE to review.
+ * @param {{subHUs: Array<{id: string, title: string, text: string, acceptanceCriteria?: string[], blocked_by?: string[]}>, heuristic: string, reason: string}} proposal
+ * @returns {string}
+ */
+export function formatSplitProposalForFDE(proposal) {
+  const lines = [];
+  const heuristicDesc = HEURISTIC_DESCRIPTIONS[proposal.heuristic] || proposal.heuristic;
+
+  lines.push(`Heuristic: ${heuristicDesc}`);
+  lines.push(`Reason: ${proposal.reason}`);
+  lines.push("");
+
+  for (const sub of proposal.subHUs) {
+    lines.push(`--- ${sub.id}: ${sub.title} ---`);
+    lines.push(sub.text);
+    if (sub.acceptanceCriteria && sub.acceptanceCriteria.length > 0) {
+      lines.push("Acceptance Criteria:");
+      for (const ac of sub.acceptanceCriteria) {
+        lines.push(`  - ${ac}`);
+      }
+    }
+    if (sub.blocked_by && sub.blocked_by.length > 0) {
+      lines.push(`Depends on: ${sub.blocked_by.join(", ")}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Set blocked_by for each sub-HU: first inherits original's dependencies,
+ * each subsequent is blocked by its predecessor (sequential chain).
+ * @param {Array<{id: string, blocked_by?: string[]}>} subHUs - The sub-HUs to update.
+ * @param {{blocked_by?: string[]}} originalHu - The original HU with its dependencies.
+ * @returns {Array<{id: string, blocked_by: string[]}>} Updated sub-HUs with correct dependencies.
+ */
+export function buildSplitDependencies(subHUs, originalHu) {
+  if (!subHUs || subHUs.length === 0) return [];
+
+  const originalDeps = originalHu?.blocked_by || [];
+
+  return subHUs.map((sub, idx) => {
+    const blockedBy = idx === 0
+      ? [...originalDeps]
+      : [subHUs[idx - 1].id];
+
+    return { ...sub, blocked_by: blockedBy };
+  });
+}

package/src/hu/store.js

@@ -210,6 +210,26 @@ export async function createHistoryRecord(sessionId, { task, result, approved, s
   return batch;
 }
 
+/* ── Splitting metadata ──────────────────────────────────────────── */
+
+/**
+ * Add splitting metadata to a story within a batch.
+ * Used to track the relationship between an original HU and its sub-HUs
+ * after a split operation.
+ *
+ * @param {object} batch - The batch object.
+ * @param {string} huId - Story ID to annotate.
+ * @param {{ original_hu_id?: string, split_children?: string[], indicators_detected?: string[], heuristic_applied?: string, split_confirmed_by_fde?: boolean, validation?: object }} metadata - Splitting metadata.
+ * @returns {object} The updated story.
+ */
+export function addSplittingMetadata(batch, huId, metadata) {
+  const story = batch.stories.find(s => s.id === huId);
+  if (!story) throw new Error(`Story ${huId} not found`);
+  story.splitting = { ...(story.splitting || {}), ...metadata };
+  story.updated_at = new Date().toISOString();
+  return story;
+}
+
 /* ── Manual HU management ─────────────────────────────────────────── */
 
 /**

package/src/mcp/server-handlers.js

@@ -918,7 +918,32 @@ async function handleArchitect(a, server, extra) {
 
 async function handleAudit(a, server, extra) {
   await runBootstrapGate(server, a);
-  return handleAuditDirect(a, server, extra);
+  const result = await handleAuditDirect(a, server, extra);
+
+  // Return compact summary for MCP (full details in session log)
+  if (result?.ok && result?.summary) {
+    const compact = {
+      ok: true,
+      overallHealth: result.summary?.overallHealth || result.summary,
+      totalFindings: result.summary?.totalFindings,
+      critical: result.summary?.critical,
+      high: result.summary?.high,
+      topRecommendations: (result.topRecommendations || []).slice(0, 5).map(r => ({
+        priority: r.priority,
+        dimension: r.dimension,
+        action: r.action,
+        impact: r.impact
+      })),
+      textSummary: result.textSummary || result.summary,
+      basalCost: result.basalCost ? {
+        totalLines: result.basalCost.totalLines,
+        totalFiles: result.basalCost.totalFiles,
+        dependencies: result.basalCost.dependencies
+      } : undefined
+    };
+    return { content: [{ type: "text", text: JSON.stringify(compact, null, 2) }] };
+  }
+  return result;
 }
 
 async function handleHu(a, server) {

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

@@ -6,6 +6,7 @@ import { topologicalSort } from "../hu/graph.js";
 import { updateStoryStatus, loadHuBatch, saveHuBatch, HU_STATUS } from "../hu/store.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 import { refineHuWithContext } from "../hu/lazy-planner.js";
+import { findParallelGroups, createWorktree, mergeWorktree, removeWorktree } from "../hu/parallel-executor.js";
 
 /**
  * Determine whether the HU reviewer result requires a sub-pipeline
@@ -60,6 +61,92 @@ function buildHuTask(story) {
   return `Implement HU ${story.id}`;
 }
 
+/**
+ * Execute a single HU through the coder→sonar→reviewer sub-pipeline.
+ * Extracted to support both sequential and parallel execution paths.
+ *
+ * @param {object} params
+ * @returns {Promise<{huId: string, approved: boolean, result?: object, error?: string, blockedDependents?: string[]}>}
+ */
+async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emitter, eventBase, logger, config, results, worktreePath }) {
+  const story = batch.stories.find(s => s.id === storyId);
+
+  // --- Lazy refinement ---
+  if (story.needsRefinement && config) {
+    const completedHus = results
+      .filter(r => r.approved)
+      .map(r => {
+        const completedStory = batch.stories.find(s => s.id === r.huId);
+        return {
+          ...completedStory,
+          resultSummary: r.result?.summary || r.result?.reason || null
+        };
+      });
+
+    emitProgress(emitter, makeEvent("hu:refine-start", { ...eventBase, stage: "hu-sub-pipeline" }, {
+      message: `Refining HU ${story.id} with context from ${completedHus.length} completed HU(s)`,
+      detail: { huId: story.id, completedCount: completedHus.length }
+    }));
+
+    try {
+      const refined = await refineHuWithContext(story, completedHus, config, logger);
+      Object.assign(story, refined);
+      story.needsRefinement = false;
+      await saveHuBatch(batchSessionId, batch);
+
+      emitProgress(emitter, makeEvent("hu:refine-end", { ...eventBase, stage: "hu-sub-pipeline" }, {
+        message: `HU ${story.id} refined successfully`,
+        detail: { huId: story.id }
+      }));
+    } catch (err) {
+      logger.warn(`Lazy refinement failed for HU ${story.id}: ${err.message} — proceeding with original`);
+      story.needsRefinement = false;
+    }
+  }
+
+  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, worktreePath: worktreePath || null }
+  }));
+
+  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 }
+      }));
+      return { huId: story.id, approved: true, result: iterResult };
+    } else {
+      updateStoryStatus(batch, story.id, HU_STATUS.FAILED);
+      emitProgress(emitter, makeEvent("hu:end", { ...eventBase, stage: "hu-sub-pipeline" }, {
+        status: "fail",
+        message: `HU ${story.id} failed`,
+        detail: { huId: story.id, approved: false, reason: iterResult?.reason }
+      }));
+      return { huId: story.id, approved: false, result: iterResult };
+    }
+  } catch (err) {
+    updateStoryStatus(batch, story.id, HU_STATUS.FAILED);
+    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 }
+    }));
+    return { huId: story.id, approved: false, error: err.message };
+  }
+}
+
 /**
  * Run all certified HUs as sub-pipelines in topological order.
  *
@@ -99,102 +186,85 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
   const blockedIds = [];
   let allApproved = true;
 
-  for (const storyId of orderedIds) {
-    const story = batch.stories.find(s => s.id === storyId);
-    if (!story) continue;
+  // --- Group HUs into parallel batches ---
+  const parallelBatches = findParallelGroups(certifiedStories, orderedIds);
 
-    // Skip if already blocked by a failed dependency
-    if (story.status === HU_STATUS.BLOCKED) {
-      blockedIds.push(story.id);
-      continue;
-    }
+  for (const group of parallelBatches) {
+    // Filter out HUs that were blocked by a failed dependency in a previous batch
+    const runnableIds = group.filter(id => {
+      const story = batch.stories.find(s => s.id === id);
+      return story && story.status !== HU_STATUS.BLOCKED;
+    });
 
-    // --- Lazy refinement: refine HU if it needs it, using completed HU context ---
-    if (story.needsRefinement && config) {
-      const completedHus = results
-        .filter(r => r.approved)
-        .map(r => {
-          const completedStory = batch.stories.find(s => s.id === r.huId);
-          return {
-            ...completedStory,
-            resultSummary: r.result?.summary || r.result?.reason || null
-          };
-        });
+    if (runnableIds.length === 0) continue;
 
-      emitProgress(emitter, makeEvent("hu:refine-start", { ...eventBase, stage: "hu-sub-pipeline" }, {
-        message: `Refining HU ${story.id} with context from ${completedHus.length} completed HU(s)`,
-        detail: { huId: story.id, completedCount: completedHus.length }
-      }));
+    // Emit parallel batch start event
+    emitProgress(emitter, makeEvent("hu:parallel-start", { ...eventBase, stage: "hu-sub-pipeline" }, {
+      message: `Starting parallel batch of ${runnableIds.length} HU(s): ${runnableIds.join(", ")}`,
+      detail: { batchIds: runnableIds, parallel: runnableIds.length > 1 }
+    }));
 
-      try {
-        const refined = await refineHuWithContext(story, completedHus, config, logger);
-        // Apply refinement to the batch story in-place
-        Object.assign(story, refined);
-        story.needsRefinement = false;
-        await saveHuBatch(batchSessionId, batch);
-
-        emitProgress(emitter, makeEvent("hu:refine-end", { ...eventBase, stage: "hu-sub-pipeline" }, {
-          message: `HU ${story.id} refined successfully`,
-          detail: { huId: story.id }
-        }));
-      } catch (err) {
-        logger.warn(`Lazy refinement failed for HU ${story.id}: ${err.message} — proceeding with original`);
-        story.needsRefinement = false;
+    if (runnableIds.length === 1) {
+      // Single HU: run as before, no worktree needed
+      const singleResult = await runSingleHu({
+        storyId: runnableIds[0], batch, batchSessionId, runIterationFn,
+        emitter, eventBase, logger, config, results
+      });
+      results.push(singleResult);
+      if (!singleResult.approved) {
+        allApproved = false;
+        const newlyBlocked = blockDependents(batch, singleResult.huId);
+        blockedIds.push(...newlyBlocked);
       }
-    }
-
-    const huTask = buildHuTask(story);
+      await saveHuBatch(batchSessionId, batch);
+    } else {
+      // Multiple HUs: create worktrees, run in parallel
+      const projectDir = config?.projectDir || process.cwd();
+      const worktrees = new Map();
 
-    // --- 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 }
-    }));
+      // Create worktrees for each HU in the batch
+      for (const id of runnableIds) {
+        try {
+          const wtPath = await createWorktree(projectDir, id);
+          worktrees.set(id, wtPath);
+        } catch (err) {
+          logger.warn(`Failed to create worktree for HU ${id}: ${err.message} — will run sequentially`);
+        }
+      }
 
-    // Update status to coding
-    updateStoryStatus(batch, story.id, HU_STATUS.CODING);
-    await saveHuBatch(batchSessionId, batch);
+      // Run all HUs in the batch concurrently
+      const batchPromises = runnableIds.map(async (storyId) => {
+        return runSingleHu({
+          storyId, batch, batchSessionId, runIterationFn,
+          emitter, eventBase, logger, config, results,
+          worktreePath: worktrees.get(storyId)
+        });
+      });
 
-    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;
+      const batchResults = await Promise.all(batchPromises);
 
-        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 });
+      // Process results: merge successful worktrees sequentially, clean up failed ones
+      for (const res of batchResults) {
+        results.push(res);
+        if (res.approved && worktrees.has(res.huId)) {
+          try {
+            await mergeWorktree(projectDir, res.huId);
+          } catch (err) {
+            logger.warn(`Failed to merge worktree for HU ${res.huId}: ${err.message}`);
+          }
+        } else if (!res.approved) {
+          allApproved = false;
+          const newlyBlocked = blockDependents(batch, res.huId);
+          blockedIds.push(...newlyBlocked);
+          // Clean up failed worktree
+          if (worktrees.has(res.huId)) {
+            try { await removeWorktree(projectDir, res.huId); } catch { /* ignore */ }
+          }
+        }
       }
-    } 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);
     }
-
-    await saveHuBatch(batchSessionId, batch);
   }
 
   return { approved: allApproved, results, blockedIds };

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

@@ -14,6 +14,8 @@ 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";
+import { detectIndicators, selectHeuristic } from "../hu/splitting-detector.js";
+import { generateSplitProposal, formatSplitProposalForFDE, buildSplitDependencies } from "../hu/splitting-generator.js";
 
 const ROLE_NAMES = ["planner", "researcher", "architect", "refactorer", "reviewer", "tester", "security", "impeccable"];
 
@@ -679,6 +681,84 @@ export async function runHuReviewerStage({ config, logger, emitter, eventBase, s
     batch = await createHuBatch(batchSessionId, stories);
   }
 
+  // --- Splitting detection: check each pending HU for split indicators before 6D evaluation ---
+  const storiesToSplit = [...batch.stories].filter(s => s.status === "pending");
+  for (const story of storiesToSplit) {
+    const indicators = detectIndicators(story.original.text);
+    if (indicators.length === 0) continue;
+
+    let heuristic = selectHeuristic(indicators);
+    if (!heuristic) continue;
+
+    const triedHeuristics = [];
+    let splitAccepted = false;
+
+    while (heuristic && !splitAccepted) {
+      const proposal = await generateSplitProposal(
+        { id: story.id, text: story.original.text },
+        heuristic, config, logger
+      );
+
+      if (!proposal) {
+        triedHeuristics.push(heuristic);
+        heuristic = selectHeuristic(indicators, triedHeuristics);
+        continue;
+      }
+
+      if (!askQuestion) {
+        // Autonomous mode: auto-accept the split
+        const updatedSubHUs = buildSplitDependencies(proposal.subHUs, story);
+        const storyIndex = batch.stories.findIndex(s => s.id === story.id);
+        const newStories = updatedSubHUs.map(sub => ({
+          id: sub.id, status: "pending",
+          original: { text: `${sub.title}\n\n${sub.text}\n\nAcceptance Criteria:\n${(sub.acceptanceCriteria || []).map(ac => `- ${ac}`).join("\n")}` },
+          blocked_by: sub.blocked_by || [], certified: null, quality: null,
+          context_requests: [], created_at: new Date().toISOString(), updated_at: new Date().toISOString()
+        }));
+        batch.stories.splice(storyIndex, 1, ...newStories);
+        splitAccepted = true;
+        emitProgress(emitter, makeEvent("hu-reviewer:split-accepted", { ...eventBase, stage: "hu-reviewer" }, {
+          message: `Auto-accepted split of ${story.id} into ${updatedSubHUs.length} sub-HUs`,
+          detail: { originalId: story.id, subHUs: updatedSubHUs.map(s => s.id), heuristic }
+        }));
+      } else {
+        // Interactive mode: ask FDE for confirmation
+        const formatted = formatSplitProposalForFDE(proposal);
+        const question = `Split proposed for ${story.id}:\n${formatted}\nAccept? (yes/no/try another)`;
+        emitProgress(emitter, makeEvent("hu-reviewer:split-proposal", { ...eventBase, stage: "hu-reviewer" }, {
+          message: `Split proposal for ${story.id} using heuristic: ${heuristic}`,
+          detail: { originalId: story.id, heuristic, subHUCount: proposal.subHUs.length }
+        }));
+        const answer = await askQuestion(question, { iteration: 0, stage: "hu-reviewer" });
+        if (!answer || answer.toLowerCase().startsWith("yes")) {
+          const updatedSubHUs = buildSplitDependencies(proposal.subHUs, story);
+          const storyIndex = batch.stories.findIndex(s => s.id === story.id);
+          const newStories = updatedSubHUs.map(sub => ({
+            id: sub.id, status: "pending",
+            original: { text: `${sub.title}\n\n${sub.text}\n\nAcceptance Criteria:\n${(sub.acceptanceCriteria || []).map(ac => `- ${ac}`).join("\n")}` },
+            blocked_by: sub.blocked_by || [], certified: null, quality: null,
+            context_requests: [], created_at: new Date().toISOString(), updated_at: new Date().toISOString()
+          }));
+          batch.stories.splice(storyIndex, 1, ...newStories);
+          splitAccepted = true;
+          emitProgress(emitter, makeEvent("hu-reviewer:split-accepted", { ...eventBase, stage: "hu-reviewer" }, {
+            message: `FDE accepted split of ${story.id} into ${updatedSubHUs.length} sub-HUs`,
+            detail: { originalId: story.id, subHUs: updatedSubHUs.map(s => s.id), heuristic }
+          }));
+        } else if (answer.toLowerCase().includes("try") || answer.toLowerCase().startsWith("no")) {
+          triedHeuristics.push(heuristic);
+          heuristic = selectHeuristic(indicators, triedHeuristics);
+          if (!heuristic) {
+            updateStoryStatus(batch, story.id, "needs_context");
+          }
+          continue;
+        }
+      }
+      break;
+    }
+    await saveHuBatch(batchSessionId, batch);
+  }
+
   // --- Evaluate loop (re-evaluate entire batch until all certified or needs_context with no askQuestion) ---
   const huReviewerOnOutput = ({ stream, line }) => {
     emitProgress(emitter, makeEvent("agent:output", { ...eventBase, stage: "hu-reviewer" }, {