@karajan-family/code 4.21.0

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,175 @@
+/**
+ * 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 };
+  });
+}