karajan-code 1.46.0 → 1.48.0

package/package.json

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

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

@@ -90,7 +90,9 @@ export function updateStoryStatus(batch, storyId, status, extra = {}) {
   const story = batch.stories.find(s => s.id === storyId);
   if (!story) throw new Error(`Story ${storyId} not found`);
   story.status = status;
-  story.updated_at = new Date().toISOString();
+  const now = new Date().toISOString();
+  story.statusChangedAt = now;
+  story.updated_at = now;
   Object.assign(story, extra);
   return story;
 }
@@ -210,6 +212,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

@@ -114,13 +114,30 @@ async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emi
 
   updateStoryStatus(batch, story.id, HU_STATUS.CODING);
   await saveHuBatch(batchSessionId, batch);
+  emitProgress(emitter, makeEvent("hu:status-change", { ...eventBase, stage: "hu-sub-pipeline" }, {
+    message: `HU ${story.id} status → coding`,
+    detail: { huId: story.id, status: HU_STATUS.CODING, timestamp: new Date().toISOString() }
+  }));
 
   try {
     const iterResult = await runIterationFn(huTask);
     const approved = Boolean(iterResult?.approved);
 
+    // --- Transition to reviewing (post-coder, pre-reviewer evaluation) ---
+    updateStoryStatus(batch, story.id, HU_STATUS.REVIEWING);
+    await saveHuBatch(batchSessionId, batch);
+    emitProgress(emitter, makeEvent("hu:status-change", { ...eventBase, stage: "hu-sub-pipeline" }, {
+      message: `HU ${story.id} status → reviewing`,
+      detail: { huId: story.id, status: HU_STATUS.REVIEWING, timestamp: new Date().toISOString() }
+    }));
+
     if (approved) {
       updateStoryStatus(batch, story.id, HU_STATUS.DONE);
+      await saveHuBatch(batchSessionId, batch);
+      emitProgress(emitter, makeEvent("hu:status-change", { ...eventBase, stage: "hu-sub-pipeline" }, {
+        message: `HU ${story.id} status → done`,
+        detail: { huId: story.id, status: HU_STATUS.DONE, timestamp: new Date().toISOString() }
+      }));
       emitProgress(emitter, makeEvent("hu:end", { ...eventBase, stage: "hu-sub-pipeline" }, {
         status: "ok",
         message: `HU ${story.id} completed successfully`,
@@ -129,6 +146,11 @@ async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emi
       return { huId: story.id, approved: true, result: iterResult };
     } else {
       updateStoryStatus(batch, story.id, HU_STATUS.FAILED);
+      await saveHuBatch(batchSessionId, batch);
+      emitProgress(emitter, makeEvent("hu:status-change", { ...eventBase, stage: "hu-sub-pipeline" }, {
+        message: `HU ${story.id} status → failed`,
+        detail: { huId: story.id, status: HU_STATUS.FAILED, timestamp: new Date().toISOString() }
+      }));
       emitProgress(emitter, makeEvent("hu:end", { ...eventBase, stage: "hu-sub-pipeline" }, {
         status: "fail",
         message: `HU ${story.id} failed`,
@@ -138,6 +160,11 @@ async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emi
     }
   } catch (err) {
     updateStoryStatus(batch, story.id, HU_STATUS.FAILED);
+    await saveHuBatch(batchSessionId, batch);
+    emitProgress(emitter, makeEvent("hu:status-change", { ...eventBase, stage: "hu-sub-pipeline" }, {
+      message: `HU ${story.id} status → failed`,
+      detail: { huId: story.id, status: HU_STATUS.FAILED, timestamp: new Date().toISOString() }
+    }));
     emitProgress(emitter, makeEvent("hu:end", { ...eventBase, stage: "hu-sub-pipeline" }, {
       status: "fail",
       message: `HU ${story.id} threw: ${err.message}`,

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

package/src/orchestrator.js

@@ -523,6 +523,10 @@ async function becariaIncrementalPush({ config, session, gitCtx, task, logger, r
   const pushResult = await incrementalPush({ gitCtx, task, logger, session });
   if (!pushResult) return;
 
+  // Accumulate commits for PG card lifecycle tracking
+  const { accumulateCommit } = await import("./planning-game/pipeline-adapter.js");
+  for (const c of pushResult.commits) accumulateCommit(session, c);
+
   session.becaria_commits = [...(session.becaria_commits ?? []), ...pushResult.commits];
   await saveSession(session);
 
@@ -539,6 +543,10 @@ async function becariaCreateEarlyPr({ config, session, emitter, eventBase, gitCt
   const earlyPr = await earlyPrCreation({ gitCtx, task, logger, session, stageResults });
   if (!earlyPr) return;
 
+  // Accumulate commits for PG card lifecycle tracking
+  const { accumulateCommit } = await import("./planning-game/pipeline-adapter.js");
+  for (const c of earlyPr.commits) accumulateCommit(session, c);
+
   session.becaria_pr_number = earlyPr.prNumber;
   session.becaria_pr_url = earlyPr.prUrl;
   session.becaria_commits = earlyPr.commits;
@@ -740,6 +748,13 @@ async function handlePostLoopStages({ config, session, emitter, eventBase, coder
 
 async function finalizeApprovedSession({ config, gitCtx, task, logger, session, stageResults, emitter, eventBase, budgetSummary, pgCard, pgProject, review, i }) {
   const gitResult = await finalizeGitAutomation({ config, gitCtx, task, logger, session, stageResults });
+
+  // Accumulate final commits for PG card lifecycle tracking
+  if (gitResult?.commits?.length) {
+    const { accumulateCommit } = await import("./planning-game/pipeline-adapter.js");
+    for (const c of gitResult.commits) accumulateCommit(session, c);
+  }
+
   if (stageResults.planner?.ok) {
     stageResults.planner.completedSteps = [...(stageResults.planner.steps ?? [])];
   }

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

@@ -94,6 +94,7 @@ export async function handlePgDecomposition({ triageResult, pgTaskId, pgProject,
 
 /**
  * Mark PG card as "To Validate" on approved session completion.
+ * Merges commits from gitResult and session.pg_commits (accumulated during pipeline).
  */
 export async function markPgCardToValidate({ pgCard, pgProject, config, session, gitResult, logger }) {
   if (!pgCard || !pgProject) return;
@@ -101,9 +102,21 @@ export async function markPgCardToValidate({ pgCard, pgProject, config, session,
   try {
     const { updateCard } = await import("./client.js");
     const { buildCompletionUpdates } = await import("./adapter.js");
+
+    // Merge commits: session.pg_commits (accumulated) + gitResult.commits (final)
+    const accumulatedCommits = session.pg_commits || [];
+    const finalCommits = gitResult?.commits || [];
+    const seenHashes = new Set(accumulatedCommits.map(c => c.hash));
+    const mergedCommits = [...accumulatedCommits];
+    for (const c of finalCommits) {
+      if (!seenHashes.has(c.hash)) {
+        mergedCommits.push(c);
+      }
+    }
+
     const pgUpdates = buildCompletionUpdates({
       approved: true,
-      commits: gitResult?.commits || [],
+      commits: mergedCommits,
       startDate: session.pg_card?.startDate || session.created_at,
       codeveloper: config.planning_game?.codeveloper || null
     });
@@ -156,6 +169,25 @@ export function buildHuStoriesFromPgCard(pgCard) {
   return [{ id: storyId, text: storyText }];
 }
 
+/**
+ * Accumulate a commit into the session's pg_commits array.
+ * Called after each successful commitAll during the iteration loop.
+ * Best-effort: never throws.
+ *
+ * @param {object} session - Pipeline session (mutated)
+ * @param {{ hash: string, message: string, date?: string, author?: string }} commitInfo
+ */
+export function accumulateCommit(session, commitInfo) {
+  if (!session || !commitInfo?.hash) return;
+  if (!session.pg_commits) session.pg_commits = [];
+  session.pg_commits.push({
+    hash: commitInfo.hash,
+    message: commitInfo.message || "",
+    date: commitInfo.date || new Date().toISOString(),
+    author: commitInfo.author || "BecarIA"
+  });
+}
+
 // --- Internal helpers ---
 
 async function markPgCardInProgress({ pgTaskId, pgProject, config, logger }) {