karajan-code 4.70.3 → 5.0.0

package/src/hu/lazy-planner.js

@@ -1,109 +0,0 @@
-/**
- * Lazy HU Planner — refines HUs one at a time using context from completed HUs.
- *
- * Instead of fully planning all HUs upfront, only the first HU is decomposed
- * with full acceptance criteria. Subsequent HUs are refined lazily before
- * execution, incorporating learnings from previously completed HUs.
- */
-import { createAgent } from "../agents/index.js";
-import { extractFirstJson } from "../utils/json-extract.js";
-import { withBrainRecovery } from "../brain/with-brain-recovery.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 refining the user story."
-].join(" ");
-
-/**
- * Build a prompt asking the AI to refine an HU based on context from completed HUs.
- * @param {object} hu - The HU to refine (with at least id, original.text or certified.text).
- * @param {Array<object>} completedHus - Array of completed HU results with summaries.
- * @returns {string} The assembled refinement prompt.
- */
-export function buildRefinementPrompt(hu, completedHus) {
-  const sections = [SUBAGENT_PREAMBLE];
-
-  sections.push("## HU Refinement");
-  sections.push(
-    "You are a senior product owner. Refine the following user story by adding or updating its acceptance criteria.",
-    "Use the context from previously completed HUs to make the criteria more precise and avoid redundant work."
-  );
-
-  if (completedHus.length > 0) {
-    sections.push("## Previously Completed HUs");
-    for (const completed of completedHus) {
-      const title = completed.certified?.title || completed.id;
-      const summary = completed.resultSummary || completed.certified?.text || completed.original?.text || "No summary available";
-      sections.push(`### ${completed.id} — ${title}\nResult: ${summary}`);
-    }
-  }
-
-  const huText = hu.certified?.text || hu.original?.text || `Implement HU ${hu.id}`;
-  sections.push(`## HU to Refine\n### ${hu.id}\n${huText}`);
-
-  sections.push(
-    "Return a single valid JSON object and nothing else.",
-    `JSON schema: {"id":string,"title":string,"text":string,"acceptanceCriteria":[string]}`,
-    "Rules:",
-    "- Keep the same HU id",
-    "- Refine the description to be more specific based on what was learned",
-    "- Add concrete, testable acceptance criteria",
-    "- Avoid repeating work already done in completed HUs",
-    "- The text field should be the full story description ready for implementation"
-  );
-
-  return sections.join("\n\n");
-}
-
-/**
- * Refine an HU using AI, incorporating context from completed HUs.
- * @param {object} hu - The HU story object to refine.
- * @param {Array<object>} completedHus - Completed HU stories with results.
- * @param {object} config - Pipeline configuration.
- * @param {object} logger - Logger instance.
- * @returns {Promise<object>} Updated HU object with refined description and AC.
- */
-export async function refineHuWithContext(hu, completedHus, config, logger) {
-  const provider = config?.roles?.hu_reviewer?.provider || config?.roles?.coder?.provider || "claude";
-  const prompt = buildRefinementPrompt(hu, completedHus);
-
-  logger.info(`Lazy planner: refining HU ${hu.id} with context from ${completedHus.length} completed HU(s)`);
-
-  const agent = createAgent(provider, config, logger);
-  let result;
-  try {
-    // KJC-TSK-0413 step C
-    result = await withBrainRecovery({
-      agent, taskArgs: { prompt, role: "hu-reviewer" },
-      role: "lazy-planner", provider, logger,
-    });
-  } catch (err) {
-    logger.warn(`Lazy planner: refinement failed for HU ${hu.id}: ${err.message}`);
-    return hu;
-  }
-
-  if (!result.ok) {
-    logger.warn(`Lazy planner: refinement returned not-ok for HU ${hu.id}`);
-    return hu;
-  }
-
-  const parsed = extractFirstJson(result.output);
-  if (!parsed || !parsed.text) {
-    logger.warn(`Lazy planner: could not parse refinement output for HU ${hu.id}`);
-    return hu;
-  }
-
-  // Update the HU with refined content
-  const refined = { ...hu };
-  refined.certified = {
-    ...(hu.certified || {}),
-    text: parsed.text,
-    title: parsed.title || hu.certified?.title || hu.id,
-    acceptanceCriteria: parsed.acceptanceCriteria || []
-  };
-  refined.needsRefinement = false;
-
-  logger.info(`Lazy planner: HU ${hu.id} refined successfully`);
-  return refined;
-}

package/src/hu/parallel-executor.js

@@ -1,94 +0,0 @@
-/**
- * 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/routing-metrics.js

@@ -1,17 +0,0 @@
-/**
- * KJC-TSK-0702 (MR-E): the per-HU measurement model routing is judged by. The
- * sub-pipeline puts it on the HU outcome; karajan-core's setHuOutcome keeps a
- * fixed set of fields, so the measured ones are kept here, in the plan, where
- * kj report reads them. Unmeasured fields stay out rather than written as null.
- */
-// KJC-TSK-1071 (MR-D3): coder_routing is the coder's routing decision for the HU.
-export const ROUTING_FIELDS = ["cost_usd", "tokens_in", "tokens_out", "cached_tokens", "coder", "reviewer_rejections", "coder_routing"];
-
-export function keepRoutingMetrics(plan, huId, outcome) {
-  const hu = plan?.hus?.find((h) => h.id === huId);
-  if (!hu?.outcome) return false;
-  for (const field of ROUTING_FIELDS) {
-    if (outcome?.[field] !== null && outcome?.[field] !== undefined) hu.outcome[field] = outcome[field];
-  }
-  return true;
-}

package/src/hu/split-validator.js

@@ -1,143 +0,0 @@
-/**
- * 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

@@ -1,158 +0,0 @@
-/**
- * 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

@@ -1,175 +0,0 @@
-/**
- * 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";
-import { withBrainRecovery } from "../brain/with-brain-recovery.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 {
-    // KJC-TSK-0413 step C
-    result = await withBrainRecovery({
-      agent, taskArgs: { prompt, role: "hu-splitter" },
-      role: "hu-splitter", provider, logger,
-    });
-  } 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 };
-  });
-}