karajan-code 2.0.2 → 2.1.0

package/package.json

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

package/src/config.js

@@ -45,6 +45,7 @@ const DEFAULTS = {
   },
   review_mode: "standard",
   max_iterations: 5,
+  hu_max_iterations: 3,
   max_budget_usd: null,
   review_rules: "./.karajan/review-rules.md",
   coder_rules: "./.karajan/coder-rules.md",

package/src/git/hu-automation.js

@@ -0,0 +1,138 @@
+/**
+ * Per-HU git automation: branch, commit, push, PR per HU story.
+ * Called from the HU sub-pipeline wrapper in orchestrator.js.
+ */
+import { commitAll, pushBranch, createPullRequest, hasChanges } from "../utils/git.js";
+import { runCommand } from "../utils/process.js";
+
+/**
+ * Build a git-safe branch name for an HU story.
+ * @param {string} prefix - e.g. "feat/"
+ * @param {object} story - HU story {id, title}
+ * @returns {string}
+ */
+export function buildHuBranchName(prefix, story) {
+  const baseSlug = String(story.title || story.id || "hu")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+  return `${prefix}${story.id}-${baseSlug}`;
+}
+
+/**
+ * Resolve the base branch for a given HU based on its dependencies.
+ * If it has no blocked_by, uses config.base_branch.
+ * If it has parents, uses the last-created parent branch (assumes parents ran first).
+ *
+ * @param {object} story - the HU story
+ * @param {Map<string,string>} huBranches - map of huId → branchName (already created)
+ * @param {string} baseBranch - config.base_branch fallback
+ * @returns {string} base branch name
+ */
+export function resolveHuBase(story, huBranches, baseBranch) {
+  const parents = story.blocked_by || [];
+  if (parents.length === 0) return baseBranch;
+  // Walk parents in reverse order of declaration to find the most recent one
+  for (let i = parents.length - 1; i >= 0; i--) {
+    const parentBranch = huBranches.get(parents[i]);
+    if (parentBranch) return parentBranch;
+  }
+  return baseBranch;
+}
+
+/**
+ * Create a branch for an HU starting from its resolved base.
+ * Returns the branch name created (or null if git automation is disabled).
+ *
+ * @param {object} params
+ * @param {object} params.story
+ * @param {Map} params.huBranches
+ * @param {object} params.config
+ * @param {object} params.logger
+ * @returns {Promise<string|null>}
+ */
+export async function prepareHuBranch({ story, huBranches, config, logger }) {
+  if (!config.git?.auto_commit && !config.git?.auto_push && !config.git?.auto_pr) {
+    return null;
+  }
+  const baseBranch = resolveHuBase(story, huBranches, config.base_branch || "main");
+  const prefix = config.git?.branch_prefix || "feat/";
+  const branchName = buildHuBranchName(prefix, story);
+
+  // Checkout from the resolved base. Use `git checkout -B` to overwrite if rerun.
+  const res = await runCommand("git", ["checkout", "-B", branchName, baseBranch], {});
+  if (res.exitCode !== 0) {
+    logger.warn(`HU git: failed to create branch ${branchName} from ${baseBranch}: ${res.stderr}`);
+    return null;
+  }
+  huBranches.set(story.id, branchName);
+  logger.info(`HU ${story.id}: branch '${branchName}' from '${baseBranch}'`);
+  return branchName;
+}
+
+/**
+ * After an HU is approved, commit its changes and optionally push + create PR.
+ *
+ * @param {object} params
+ * @param {object} params.story
+ * @param {string} params.branchName
+ * @param {object} params.config
+ * @param {object} params.logger
+ * @returns {Promise<{committed: boolean, pushed: boolean, prUrl: string|null}>}
+ */
+export async function finalizeHuCommit({ story, branchName, config, logger }) {
+  const result = { committed: false, pushed: false, prUrl: null };
+  if (!branchName) return result;
+
+  const changed = await hasChanges();
+  if (!changed) {
+    logger.info(`HU ${story.id}: no changes to commit`);
+    return result;
+  }
+
+  const title = story.title || story.id;
+  const commitMsg = `feat(${story.id}): ${title}`;
+  if (config.git?.auto_commit) {
+    const commitRes = await commitAll(commitMsg);
+    if (commitRes) {
+      result.committed = true;
+      logger.info(`HU ${story.id}: committed on '${branchName}'`);
+    }
+  }
+
+  if (config.git?.auto_push && result.committed) {
+    try {
+      await pushBranch(branchName);
+      result.pushed = true;
+      logger.info(`HU ${story.id}: pushed '${branchName}'`);
+    } catch (err) {
+      logger.warn(`HU ${story.id}: push failed: ${err.message}`);
+    }
+  }
+
+  if (config.git?.auto_pr && result.pushed) {
+    try {
+      const prBody = [
+        `## HU ${story.id}: ${title}`,
+        "",
+        story.certified?.text || "",
+        "",
+        "### Acceptance criteria",
+        ...(story.acceptance_criteria || []).map(c => `- ${c}`)
+      ].join("\n");
+      const url = await createPullRequest({
+        baseBranch: config.base_branch || "main",
+        branch: branchName,
+        title: commitMsg,
+        body: prBody
+      });
+      result.prUrl = url;
+      logger.info(`HU ${story.id}: PR created ${url}`);
+    } catch (err) {
+      logger.warn(`HU ${story.id}: PR creation failed: ${err.message}`);
+    }
+  }
+
+  return result;
+}

package/src/hu/auto-generator.js

@@ -0,0 +1,163 @@
+/**
+ * HU Auto-Generator — converts triage subtasks (+ researcher/architect context)
+ * into a certified HU batch ready for hu-sub-pipeline execution.
+ *
+ * Input: original task, triage subtasks, detected stack, researcher/architect context.
+ * Output: HU batch with setup HU (when needed), task HUs with per-HU task_type,
+ *         and a dependency graph (setup blocks everything; remaining linear by default).
+ */
+
+/**
+ * Classify a subtask into a Karajan task_type.
+ * Maps free-text subtask descriptions to {infra|sw|add-tests|doc|refactor|nocode}.
+ */
+export function classifyTaskType(text) {
+  if (!text || typeof text !== "string") return "sw";
+  const t = text.toLowerCase();
+  // Order matters: no-code beats infra (Zapier/Notion setups are no-code, not infra)
+  if (/\b(no-code|nocode|zapier|make\.com|airtable|notion)\b/.test(t)) return "nocode";
+  if (/\b(setup|install|init(?:ialize|iate)?|configure|scaffold|bootstrap)\b/.test(t)) return "infra";
+  if (/\b(docker|ci\/cd|pipeline|deploy|workflow\.yml|github actions?)\b/.test(t)) return "infra";
+  if (/\b(tests?|coverage|spec|vitest|jest|mocha|playwright)\b/.test(t) && !/\b(component|feature|endpoint)\b/.test(t)) return "add-tests";
+  if (/\b(readme|docs?|documentation|guide|tutorial)\b/.test(t)) return "doc";
+  if (/\b(refactor|cleanup|reorganiz|restructure|extract)\b/.test(t)) return "refactor";
+  return "sw";
+}
+
+/**
+ * Decide whether a setup HU is needed.
+ * Needed when: project is new OR stack hints suggest new dependencies.
+ */
+export function needsSetupHu({ isNewProject = false, stackHints = [], subtasks = [] }) {
+  if (isNewProject) return true;
+  if (stackHints.length > 0) return true;
+  // Subtasks mentioning a framework/tool suggest fresh setup
+  const setupKeywords = /\b(npm init|package\.json|workspace|monorepo|vite|vitest|express|astro|next\.js|nestjs)\b/i;
+  return subtasks.some(s => setupKeywords.test(s));
+}
+
+/**
+ * Build the setup HU story from stack hints + subtasks.
+ */
+function buildSetupHu({ stackHints, subtasks, originalTask }) {
+  const hintList = stackHints.length > 0
+    ? stackHints.map(h => `- ${h}`).join("\n")
+    : "- Detect required dependencies from task and install them";
+  const certifiedText = [
+    `**Setup project infrastructure and dependencies.**`,
+    ``,
+    `Original goal: ${originalTask}`,
+    ``,
+    `**Scope:**`,
+    `- Initialize project structure (package.json, workspaces if monorepo)`,
+    `- Install all dependencies required by the task`,
+    `- Configure tooling (test framework, linter, build tool)`,
+    `- Create .env.example with all required env vars`,
+    `- Verify install works (npm install, npm run test --run)`,
+    ``,
+    `**Stack hints:**`,
+    hintList
+  ].join("\n");
+  return {
+    id: "HU-01",
+    title: "Setup project infrastructure",
+    task_type: "infra",
+    status: "certified",
+    blocked_by: [],
+    certified: { text: certifiedText },
+    acceptance_criteria: [
+      "Project builds without errors (npm install succeeds)",
+      "Test framework is installed and 'npm test' runs (even with 0 tests)",
+      "All declared dependencies match what the task requires",
+      ".env.example exists with documented variables"
+    ]
+  };
+}
+
+/**
+ * Build a task HU story from a subtask description.
+ */
+function buildTaskHu({ id, subtask, originalTask, blockedBy }) {
+  const taskType = classifyTaskType(subtask);
+  const certifiedText = [
+    `**${subtask}**`,
+    ``,
+    `Part of: ${originalTask}`,
+    ``,
+    `**Scope:** implement this subtask only. Do not touch unrelated subtasks.`
+  ].join("\n");
+  return {
+    id,
+    title: subtask.length > 80 ? subtask.slice(0, 77) + "..." : subtask,
+    task_type: taskType,
+    status: "certified",
+    blocked_by: blockedBy,
+    certified: { text: certifiedText },
+    acceptance_criteria: [
+      `Subtask '${subtask}' is implemented`,
+      `Unit tests cover the new code (where applicable)`,
+      `No regressions in existing functionality`
+    ]
+  };
+}
+
+/**
+ * Main entry point: generate a certified HU batch from triage output.
+ *
+ * @param {object} input
+ * @param {string} input.originalTask - the user's raw task
+ * @param {string[]} input.subtasks - triage.subtasks array
+ * @param {string[]} [input.stackHints] - detected stack keywords (e.g. ["nodejs", "vitest"])
+ * @param {boolean} [input.isNewProject] - true when projectDir is empty/fresh
+ * @param {string} [input.researcherContext] - researcher output (optional, used for better HU text)
+ * @param {string} [input.architectContext] - architect output (optional, used for dep graph)
+ * @returns {{ stories: object[], total: number, certified: number, generated: true }}
+ */
+export function generateHuBatch({
+  originalTask,
+  subtasks = [],
+  stackHints = [],
+  isNewProject = false,
+  researcherContext = null,
+  architectContext = null
+}) {
+  if (!originalTask || typeof originalTask !== "string") {
+    throw new Error("generateHuBatch: originalTask is required");
+  }
+  if (!Array.isArray(subtasks) || subtasks.length === 0) {
+    throw new Error("generateHuBatch: subtasks array is required");
+  }
+
+  const stories = [];
+  const needsSetup = needsSetupHu({ isNewProject, stackHints, subtasks });
+  let nextId = 1;
+
+  if (needsSetup) {
+    stories.push(buildSetupHu({ stackHints, subtasks, originalTask }));
+    nextId = 2;
+  }
+
+  // Task HUs: linear dependency chain after setup (conservative default).
+  // Architect context could later inform parallel-safe groupings.
+  const setupId = needsSetup ? "HU-01" : null;
+  let previousId = setupId;
+  for (const subtask of subtasks) {
+    const id = `HU-${String(nextId).padStart(2, "0")}`;
+    const blockedBy = [];
+    if (setupId) blockedBy.push(setupId);
+    // Conservative: also depend on previous task HU to enforce linear execution.
+    // Later phases can relax this with architect-informed graph.
+    if (previousId && previousId !== setupId) blockedBy.push(previousId);
+    stories.push(buildTaskHu({ id, subtask, originalTask, blockedBy }));
+    previousId = id;
+    nextId += 1;
+  }
+
+  return {
+    stories,
+    total: stories.length,
+    certified: stories.length,
+    generated: true,
+    source: { triage_subtasks: subtasks.length, researcher: Boolean(researcherContext), architect: Boolean(architectContext) }
+  };
+}

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

@@ -120,7 +120,7 @@ async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emi
   }));
 
   try {
-    const iterResult = await runIterationFn(huTask);
+    const iterResult = await runIterationFn(huTask, story);
     const approved = Boolean(iterResult?.approved);
 
     // --- Transition to reviewing (post-coder, pre-reviewer evaluation) ---

package/src/orchestrator.js

@@ -687,6 +687,11 @@ async function runPreLoopStages({ config, logger, emitter, eventBase, session, f
   const projectDir = updatedConfig.projectDir || process.cwd();
   await updateGitignoreForStack(projectDir, { stageResults, task, logger });
 
+  // --- Auto-HU: when triage recommended decomposition and no manual huFile, generate HU batch ---
+  await maybeGenerateAutoHuBatch({
+    flags, stageResults, task, plannedTask, logger, emitter, eventBase, projectDir, session
+  });
+
   // --- Auto-install skills based on task + planner output + project detection ---
   // Runs AFTER triage and planner so that the planned task text (which includes
   // planner output like implementation steps) is available for keyword detection.
@@ -716,6 +721,87 @@ async function runPreLoopStages({ config, logger, emitter, eventBase, session, f
   return { plannedTask, updatedConfig };
 }
 
+/**
+ * Auto-generate HU batch from triage decomposition when no manual huFile is present.
+ * Runs after researcher/architect/planner so that context is available for better HUs.
+ * Sets stageResults.huReviewer so needsSubPipeline picks it up later.
+ */
+async function maybeGenerateAutoHuBatch({ flags, stageResults, task, plannedTask, logger, emitter, eventBase, projectDir, session }) {
+  // Skip if user passed a manual hu-file
+  if (flags?.huFile) return;
+  // Skip if hu-reviewer already produced a batch (manual enable + PG stories)
+  if (stageResults.huReviewer) return;
+  // Need triage decomposition recommendation
+  const shouldDecompose = stageResults.triage?.shouldDecompose;
+  const subtasks = stageResults.triage?.subtasks;
+  if (!shouldDecompose || !Array.isArray(subtasks) || subtasks.length < 2) return;
+
+  const { generateHuBatch } = await import("./hu/auto-generator.js");
+
+  // Detect if project is new: empty dir or only .git/.karajan/.gitignore
+  let isNewProject = false;
+  try {
+    const fs = await import("node:fs/promises");
+    const entries = await fs.readdir(projectDir);
+    const relevant = entries.filter(e => !e.startsWith(".git") && e !== ".karajan" && e !== ".gitignore");
+    isNewProject = relevant.length === 0;
+  } catch { /* ignore */ }
+
+  // Extract stack hints from planner + architect output
+  const stackHints = [];
+  const combined = `${stageResults.planner?.plan || ""} ${stageResults.architect?.architecture ? JSON.stringify(stageResults.architect.architecture) : ""} ${task}`.toLowerCase();
+  const stackKeywords = ["express", "vite", "vitest", "jest", "next", "astro", "react", "vue", "svelte", "fastapi", "django", "spring", "gin", "nestjs", "monorepo", "workspaces"];
+  for (const kw of stackKeywords) {
+    if (combined.includes(kw)) stackHints.push(kw);
+  }
+
+  const batch = generateHuBatch({
+    originalTask: task,
+    subtasks,
+    stackHints,
+    isNewProject,
+    researcherContext: stageResults.researcher?.summary || null,
+    architectContext: stageResults.architect?.architecture ? JSON.stringify(stageResults.architect.architecture) : null
+  });
+
+  // Persist batch to HU store so hu-sub-pipeline can update story status via saveHuBatch.
+  // Use session.id as batchSessionId.
+  const batchSessionId = `auto-${session.id}`;
+  try {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const { getKarajanHome } = await import("./utils/paths.js");
+    const huDir = path.join(getKarajanHome(), "hu", batchSessionId);
+    await fs.mkdir(huDir, { recursive: true });
+    const persistBatch = {
+      session_id: batchSessionId,
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+      stories: batch.stories
+    };
+    await fs.writeFile(path.join(huDir, "batch.json"), JSON.stringify(persistBatch, null, 2));
+  } catch (err) {
+    logger.warn(`Auto-HU: failed to persist batch (${err.message}) — sub-pipeline will use in-memory fallback`);
+  }
+
+  // Wrap in format compatible with needsSubPipeline + runHuSubPipeline
+  stageResults.huReviewer = {
+    ok: true,
+    stories: batch.stories,
+    total: batch.total,
+    certified: batch.certified,
+    batchSessionId,
+    auto_generated: true,
+    source: batch.source
+  };
+
+  logger.info(`Auto-HU: generated ${batch.total} stories (${batch.source.triage_subtasks} subtasks${isNewProject ? ", new project" : ""}${stackHints.length ? `, stack: ${stackHints.join(",")}` : ""})`);
+  emitProgress(emitter, makeEvent("hu:auto-generated", { ...eventBase, stage: "hu-auto-gen" }, {
+    message: `Auto-generated ${batch.total} HU(s) from triage decomposition`,
+    detail: { total: batch.total, subtasks: batch.source.triage_subtasks, isNewProject, stackHints }
+  }));
+}
+
 async function runCoderAndRefactorerStages({ coderRoleInstance, coderRole, refactorerRole, pipelineFlags, config, logger, emitter, eventBase, session, plannedTask, trackBudget, i, brainCtx }) {
   const coderResult = await runCoderStage({ coderRoleInstance, coderRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration: i, brainCtx });
   if (coderResult?.action === "pause") return { action: "return", result: coderResult.result };
@@ -1532,9 +1618,33 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
         detail: { total: ctx.stageResults.huReviewer.total, certified: ctx.stageResults.huReviewer.certified }
       }));
 
+      // Per-HU pipeline: focused max_iterations, fresh Brain state, own git branch.
+      const originalMaxIterations = ctx.config.max_iterations;
+      const huMaxIterations = ctx.config.hu_max_iterations ?? 3;
+      const huBranches = new Map();
+      const { prepareHuBranch, finalizeHuCommit } = await import("./git/hu-automation.js");
       const subPipelineResult = await runHuSubPipeline({
         huReviewerResult: ctx.stageResults.huReviewer,
-        runIterationFn: async (huTask) => runIterationLoop(ctx, { task: huTask, askQuestion, emitter, logger }),
+        runIterationFn: async (huTask, story) => {
+          ctx.config.max_iterations = huMaxIterations;
+          if (ctx.brainCtx?.enabled) {
+            ctx.brainCtx.extensionCount = 0;
+            const { createBrainContext } = await import("./orchestrator/brain-coordinator.js");
+            const fresh = createBrainContext({ enabled: true });
+            ctx.brainCtx.feedbackQueue = fresh.feedbackQueue;
+            ctx.brainCtx.verificationTracker = fresh.verificationTracker;
+          }
+          const branchName = await prepareHuBranch({ story, huBranches, config: ctx.config, logger });
+          try {
+            const result = await runIterationLoop(ctx, { task: huTask, askQuestion, emitter, logger });
+            if (result?.approved) {
+              await finalizeHuCommit({ story, branchName, config: ctx.config, logger });
+            }
+            return result;
+          } finally {
+            ctx.config.max_iterations = originalMaxIterations;
+          }
+        },
         emitter,
         eventBase: ctx.eventBase,
         logger,