karajan-code 4.70.4 → 5.0.1

package/src/mcp/tools.js

@@ -48,91 +48,6 @@ export const tools = [
       }
     }
   },
-  {
-    name: "kj_run",
-    description:
-      "Run the full Karajan pipeline. IMPORTANT: Pass the user's task description exactly as they wrote it. Do NOT group, split, reorder, or modify tasks yourself. Karajan handles decomposition, role activation, iteration, and quality gates internally. Do NOT override pipeline parameters (enableHuReviewer, mode, methodology) unless the user explicitly requested it. If you have observations about the task, use kj_suggest instead.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        task: { type: "string", description: "Task description for the coder (can include a Planning Game card ID like KJC-TSK-0042). Either `task` or `taskFile` is required." },
-        taskFile: { type: "string", description: "Alternative to `task`: path to a .md (or any text file) whose contents become the task description. Relative paths resolve against projectDir." },
-        plan: { type: "string", description: "Plan ID from kj_plan. Loads persisted plan context and skips researcher/architect/planner stages." },
-        projectDir: { type: "string", description: "Absolute path to the project directory. Required when KJ MCP server runs from a different directory than the target project." },
-        pgTask: { type: "string", description: "Planning Game card ID (e.g., KJC-TSK-0042). If provided, fetches full card details as task context and updates card status on completion." },
-        pgProject: { type: "string", description: "Planning Game project ID (e.g., 'Karajan Code'). Required when pgTask is used." },
-        planner: { type: "string" },
-        coder: { type: "string" },
-        reviewer: { type: "string" },
-        refactorer: { type: "string" },
-        plannerModel: { type: "string" },
-        coderModel: { type: "string" },
-        reviewerModel: { type: "string" },
-        refactorerModel: { type: "string" },
-        enablePlanner: { type: "boolean" },
-        enableReviewer: { type: "boolean" },
-        enableRefactorer: { type: "boolean" },
-        enableResearcher: { type: "boolean" },
-        enableTester: { type: "boolean" },
-        enableSecurity: { type: "boolean" },
-        enableImpeccable: { type: "boolean" },
-        enablePerf: { type: "boolean" },
-        enableTriage: { type: "boolean" },
-        enableDiscover: { type: "boolean" },
-        enableArchitect: { type: "boolean" },
-        enableHuReviewer: { type: "boolean" },
-        architectModel: { type: "string" },
-        huFile: { type: "string", description: "Path to YAML file with HU stories to certify before coding" },
-        enableSerena: { type: "boolean" },
-        enableCi: { type: "boolean", description: "Enable Karajan CI (early PR + dispatch comments/reviews)" },
-        reviewerFallback: { type: "string" },
-        reviewerRetries: { type: "number" },
-        mode: { type: "string" },
-        maxIterations: { type: "number" },
-        maxIterationMinutes: { type: "number" },
-        maxTotalMinutes: { type: "number" },
-        baseBranch: { type: "string" },
-        baseRef: { type: "string" },
-        methodology: { type: "string", enum: ["tdd", "standard"] },
-        autoCommit: { type: "boolean" },
-        autoPush: { type: "boolean" },
-        autoPr: { type: "boolean" },
-        autoRebase: { type: "boolean" },
-        branchPrefix: { type: "string" },
-        autoSimplify: { type: "boolean", description: "Auto-simplify pipeline for simple tasks (level trivial/simple). Disable with false to force full pipeline." },
-        smartModels: { type: "boolean", description: "Enable/disable smart model selection based on triage complexity" },
-        checkpointInterval: { type: "number", description: "Minutes between interactive checkpoints (default: 5). Set 0 to disable." },
-        taskType: { type: "string", enum: ["sw", "infra", "doc", "add-tests", "refactor"], description: "Explicit task type for policy resolution. Overrides triage classification." },
-        quiet: { type: "boolean", description: "Suppress raw agent output lines, show only stage status (default: true). Set false for verbose output." },
-        noSonar: { type: "boolean" },
-        design: { type: "boolean", description: "Activate design refactoring mode. Impeccable role applies design changes instead of just auditing." },
-        enableSonarcloud: { type: "boolean", description: "Enable SonarCloud scan (complementary to SonarQube)" },
-        kjHome: { type: "string" },
-        sonarToken: { type: "string" },
-        timeoutMs: { type: "number" },
-        domain: { type: "string", description: "Domain knowledge: inline text describing the project domain, or absolute path to a .md file. Auto-saved to .karajan/domains/ for the curator." },
-        brain: { type: "string", enum: ["on", "off"], description: "Brain decisor: on|off. Controls whether intent-driven routing overrides pipeline flags." },
-        forceRole: { type: "array", items: { type: "string" }, description: "Force roles ON regardless of triage (e.g. [\"security\"])" },
-        skipRole: { type: "array", items: { type: "string" }, description: "Force roles OFF regardless of triage (e.g. [\"tester\"])" },
-        specReviewMode: { type: "string", enum: ["auto", "skip"], description: "Pre-pipeline spec-reviewer behaviour (KJC-PCS-0048). `auto` (default): the role runs, findings stream to the client via progress events; the pipeline continues regardless. `skip`: bypass the reviewer entirely (mirrors the --skip-spec-review CLI flag)." }
-      }
-    }
-  },
-  {
-    name: "kj_resume",
-    description:
-      "Resume a paused, stopped, or failed session by ID. For paused sessions, provide an answer. For stopped/failed sessions, re-runs the flow from scratch. Sends real-time progress notifications via MCP logging.",
-    inputSchema: {
-      type: "object",
-      required: ["sessionId"],
-      properties: {
-        sessionId: { type: "string", description: "Session ID to resume" },
-        answer: { type: "string", description: "Answer to the question that caused the pause" },
-        projectDir: { type: "string", description: "Absolute path to the project directory" },
-        kjHome: { type: "string" }
-      }
-    }
-  },
   {
     name: "kj_report",
     description: "Read latest or list session reports. Use trace=true for chronological stage-by-stage breakdown with timing and token usage.",
@@ -176,7 +91,7 @@ export const tools = [
   },
   {
     name: "kj_preflight",
-    description: "Confirm or adjust agent configuration before first kj_run/kj_code. REQUIRED before running any task via MCP. Show the config to the human, get their confirmation or adjustments, then call this tool with their response.",
+    description: "Confirm or adjust agent configuration before first kj_code. REQUIRED before running any task via MCP. Show the config to the human, get their confirmation or adjustments, then call this tool with their response.",
     inputSchema: {
       type: "object",
       required: ["humanResponse"],
@@ -207,50 +122,6 @@ export const tools = [
       }
     }
   },
-  {
-    name: "kj_review",
-    description: "Run reviewer-only mode against current diff. Do NOT filter or pre-process the diff before passing it.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        task: { type: "string", description: "Task description. Either `task` or `taskFile` is required." },
-        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
-        reviewer: { type: "string" },
-        reviewerModel: { type: "string" },
-        baseRef: { type: "string" },
-        projectDir: { type: "string", description: "Absolute path to the project directory" },
-        kjHome: { type: "string" }
-      }
-    }
-  },
-  {
-    name: "kj_status",
-    description: "Show real-time status and log of the current or last Karajan run. Returns a parsed status (current stage, agent, iteration, errors) plus recent log lines. Use this to monitor progress while kj_run/kj_plan/kj_code is executing.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        lines: { type: "number", description: "Number of log lines to show (default 50)" }
-      }
-    }
-  },
-  {
-    name: "kj_plan",
-    description: "Generate implementation plan for a task. Pass the task as the user described it. Karajan's planner decides the approach.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        task: { type: "string", description: "Task description. Either `task` or `taskFile` is required." },
-        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
-        planner: { type: "string" },
-        plannerModel: { type: "string" },
-        coder: { type: "string", description: "Legacy alias for planner" },
-        coderModel: { type: "string", description: "Legacy alias for plannerModel" },
-        projectDir: { type: "string", description: "Absolute path to the project directory" },
-        kjHome: { type: "string" },
-        specReviewMode: { type: "string", enum: ["auto", "skip"], description: "Pre-planner spec-reviewer behaviour (KJC-PCS-0048). `auto` (default): runs the reviewer, findings stream as progress, planner continues. `skip`: bypass entirely." }
-      }
-    }
-  },
   {
     name: "kj_discover",
     description: "Analyze a task for gaps, ambiguities, and missing information before execution. Returns a verdict (ready/needs_validation) with structured gap list. Can read task details from Planning Game if pgTask is provided.",
@@ -268,46 +139,6 @@ export const tools = [
       }
     }
   },
-  {
-    name: "kj_triage",
-    description: "Classify task complexity and recommend which pipeline roles to activate. Returns level (trivial/simple/medium/complex), taskType, recommended roles, and optional decomposition.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        task: { type: "string", description: "Task description to classify. Either `task` or `taskFile` is required." },
-        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
-        projectDir: { type: "string", description: "Absolute path to the project directory" },
-        kjHome: { type: "string" }
-      }
-    }
-  },
-  {
-    name: "kj_researcher",
-    description: "Research the codebase for a task. Identifies affected files, patterns, constraints, prior decisions, risks, and test coverage.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        task: { type: "string", description: "Task description to research. Either `task` or `taskFile` is required." },
-        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
-        projectDir: { type: "string", description: "Absolute path to the project directory" },
-        kjHome: { type: "string" }
-      }
-    }
-  },
-  {
-    name: "kj_architect",
-    description: "Design solution architecture for a task. Returns layers, patterns, data model, API contracts, tradeoffs, and a verdict (ready/needs_clarification).",
-    inputSchema: {
-      type: "object",
-      properties: {
-        task: { type: "string", description: "Task description to architect. Either `task` or `taskFile` is required." },
-        taskFile: { type: "string", description: "Alternative to `task`: path to a .md/text file." },
-        context: { type: "string", description: "Additional context (e.g., researcher output)" },
-        projectDir: { type: "string", description: "Absolute path to the project directory" },
-        kjHome: { type: "string" }
-      }
-    }
-  },
   {
     name: "kj_audit",
     description: "Analyze codebase health without modifying files. Returns findings across security, code quality, performance, architecture, and testing dimensions.",
@@ -363,32 +194,6 @@ export const tools = [
       }
     }
   },
-  {
-    name: "kj_skills",
-    description: "Manage OpenSkills for domain-specific agent knowledge. Install skills from the marketplace or GitHub repos to give coders domain expertise.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        action: { type: "string", enum: ["install", "remove", "list", "read"], description: "Action to perform" },
-        source: { type: "string", description: "Skill source: marketplace name, GitHub URL, or local path (for install)" },
-        name: { type: "string", description: "Skill name (for remove/read)" },
-        global: { type: "boolean", description: "Install globally (~/.agent/skills/) instead of project-local" },
-        projectDir: { type: "string", description: "Project directory" }
-      },
-      required: ["action"]
-    }
-  },
-  {
-    name: "kj_undo",
-    description: "Revert the last pipeline run by resetting to the pre-pipeline commit. Default: soft reset (keeps changes staged). Use hard=true to discard all changes.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        hard: { type: "boolean", description: "If true, discard all changes (git reset --hard). Default: false (soft reset, keeps changes staged)." },
-        projectDir: { type: "string", description: "Absolute path to the project directory" }
-      }
-    }
-  },
   {
     name: "kj_clean",
     description: "Garbage-collect stale Karajan state: orphan plans (project dir no longer exists), finalised plans/sessions past their retention window, and HU story batches. Dry-run by default; pass yes=true to actually delete. Use nuke=true to wipe everything (retention=0 on every bucket + drop the HU board SQLite DB).",

package/src/plan/lane-plans.js

@@ -0,0 +1,54 @@
+/**
+ * #2566: a lane (<main>/.kj/worktrees/<x>, <main>/.claude/worktrees/<x>) kept plans under its own
+ * slug; `kj hu list` moves them to the main checkout's. A taken name is kept and reported.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { plansDir } from "./plan-store.js";
+import { mainCheckout } from "../utils/main-checkout.js";
+import { MIRROR_PLAN_ID } from "../hu/team-board-mirror.js";
+
+const LANE_DIRS = [".kj_worktrees_", ".claude_worktrees_"];
+
+// Never overwrites: "wx" and errorOnExist fail with EEXIST if another session wrote dest first.
+async function moveEntry(from, dest, main) {
+  const plan = from.endsWith(".json") ? await fs.readFile(from, "utf8").then(JSON.parse, () => null) : null;
+  if (plan) {
+    // TSK-0341: the stamp must outlive the lane, or the GC sees the plan as orphan.
+    await fs.writeFile(dest, JSON.stringify({ ...plan, projectDir: main }, null, 2), { flag: "wx" });
+    return fs.unlink(from);
+  }
+  await fs.cp(from, dest, { recursive: true, force: false, errorOnExist: true });
+  return fs.rm(from, { recursive: true });
+}
+
+export async function migrateLanePlans(projectDir) {
+  const [target, main] = [plansDir(projectDir), mainCheckout(projectDir)];
+  const root = path.dirname(target);
+  const prefixes = LANE_DIRS.map((d) => `${path.basename(target)}_${d}`); // the main checkout's slug
+  const moved = [];
+  const kept = [];
+  let entries;
+  try { entries = await fs.readdir(root, { withFileTypes: true }); } catch (err) {
+    if (err.code === "ENOENT") return { moved, kept };
+    throw err;
+  }
+  const isLaneFolder = (e) => e.isDirectory() && prefixes.some((p) => e.name.startsWith(p));
+  for (const lane of entries.filter(isLaneFolder)) {
+    const from = path.join(root, lane.name);
+    await fs.mkdir(target, { recursive: true });
+    for (const file of await fs.readdir(from)) {
+      // The team board mirror is no plan: `kj hu list` rewrites it from GitHub, a lane's copy is stale.
+      if (file === `${MIRROR_PLAN_ID}.json`) { await fs.unlink(path.join(from, file)); continue; }
+      try {
+        await moveEntry(path.join(from, file), path.join(target, file), main);
+        moved.push(file);
+      } catch (err) {
+        if (err.code !== "EEXIST" && err.code !== "ERR_FS_CP_EEXIST") throw err;
+        kept.push(path.join(from, file));
+      }
+    }
+    await fs.rmdir(from).catch((err) => { if (err.code !== "ENOTEMPTY") throw err; }); // a collision stays
+  }
+  return { moved, kept };
+}

package/src/plan/plan-store.js

@@ -10,6 +10,7 @@ import { writeJsonAtomic } from "../utils/atomic-write.js";
 import { resolveHome } from "../utils/paths.js";
 import { getSharedPlansDir } from "../utils/shared-paths.js";
 import { generatePlanId, normaliseAlias } from "./plan-id.js";
+import { mainCheckout } from "../utils/main-checkout.js";
 
 /**
  * A plan JSON file failed to parse — typically an interrupted write
@@ -51,7 +52,7 @@ export function getKjHome() {
 /**
  * Deterministic slug for a project path — stable across plan-store writes,
  * HU-board syncs and board URL routing. Keep in lockstep with
- * `packages/hu-board/src/sync.js::deriveProjectIdFromDir`.
+ * `packages/hu-board/src/sync.js::deriveProjectIdFromDir` (kj slugs the main checkout, #2566).
  * @param {string} projectDir - absolute project path
  * @returns {string}
  */
@@ -64,12 +65,13 @@ export function projectSlug(projectDir) {
 }
 
 // KJC-TSK-1166: the board honours KJ_PLANS_DIR as its plans root; what kj writes must land
-// in the same root, or the board shows none of it.
+// in the same root, or the board shows none of it. #2566: one folder per main checkout, lanes included.
 export function plansDir(projectDir) {
   const root = process.env.KJ_PLANS_DIR || path.join(getKjHome(), "plans");
-  return path.join(root, projectSlug(projectDir));
+  return path.join(root, projectSlug(mainCheckout(projectDir)));
 }
 
+
 /**
  * Save a plan to disk. Accepts both v1 and v2 schemas.
  * @param {string} projectDir
@@ -88,7 +90,8 @@ export async function savePlan(projectDir, planResult) {
     // plan so the GC can check `fs.exists(projectDir)` reliably. Reverse-
     // engineering it from the slug is lossy (underscores in the original
     // name collide with underscores introduced by slash-substitution).
-    if (!planResult.projectDir && projectDir) planResult.projectDir = projectDir;
+    // #2566: the main checkout, never a lane that is deleted after merge.
+    if (!planResult.projectDir && projectDir) planResult.projectDir = mainCheckout(projectDir);
     // Humanización IDs: si el plan no tiene alias todavía, derívalo de
     // plan.name (lo que el planner pidió al usuario). Resuelve
     // colisiones con sufijo -2, -3… leyendo el dir antes.

package/src/policy/add.js

@@ -67,31 +67,29 @@ const naiveDiff = (oldText, newText) => {
   ].join("\n");
 };
 
-export async function policyAddCommand({ text, config = {}, flags = {}, logger = console, deps = {} }) {
-  const projectDir = config?.projectDir || process.cwd();
-  if (!text?.trim()) {
-    logger.error?.('policy add: falta la regla — kj policy add "el coder no toca los workflows"');
-    return 1;
-  }
-  const { translateFn = defaultTranslate } = deps;
-  const raw = await translateFn({ text, config, logger });
+// The agent's answer as a policy fragment, or null (said) when it is not one:
+// untranslatable, not YAML, or keys outside the closed vocabulary.
+function fragmentOf(raw, logger) {
   if (raw.includes("NO_TRADUCIBLE")) {
     logger.error?.("policy add: la regla no cabe en el vocabulario cerrado v1 — no se inventa nada; exprésala como write/shell/diff-threshold o queda como instrucción de prompt");
-    return 1;
+    return null;
   }
   let frag;
   try {
     frag = yaml.load(raw);
   } catch (err) {
     logger.error?.(`policy add: el agente no devolvió YAML válido (${err.message}) — nada que aplicar`);
-    return 1;
+    return null;
   }
   if (typeof frag !== "object" || frag === null || Object.keys(frag).some((k) => !["roles", "invariants"].includes(k))) {
     logger.error?.("policy add: el fragmento solo puede declarar roles y/o invariants — rechazado (vocabulario cerrado)");
-    return 1;
+    return null;
   }
+  return frag;
+}
 
-  const file = join(projectDir, ".karajan", "policy.yml");
+// The current policy merged with the fragment, or null (said) when the engine rejects it.
+function proposePolicy(file, frag, logger) {
   let current = "";
   try {
     current = readFileSync(file, "utf8");
@@ -102,8 +100,24 @@ export async function policyAddCommand({ text, config = {}, flags = {}, logger =
   if (errors.length > 0) {
     for (const e of errors) logger.error?.(`✗ ${e}`);
     logger.error?.("policy add: la regla traducida no valida contra el vocabulario del motor — rechazada, no se inventa");
+    return null;
+  }
+  return { current, proposed };
+}
+
+export async function policyAddCommand({ text, config = {}, flags = {}, logger = console, deps = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  if (!text?.trim()) {
+    logger.error?.('policy add: falta la regla — kj policy add "el coder no toca los workflows"');
     return 1;
   }
+  const { translateFn = defaultTranslate } = deps;
+  const frag = fragmentOf(await translateFn({ text, config, logger }), logger);
+  if (!frag) return 1;
+  const file = join(projectDir, ".karajan", "policy.yml");
+  const proposal = proposePolicy(file, frag, logger);
+  if (!proposal) return 1;
+  const { current, proposed } = proposal;
 
   logger.info?.(`policy add — diff propuesto para .karajan/policy.yml:\n${naiveDiff(current, proposed)}`);
   if (current.includes("#")) {

package/src/policy/adr-number-check.js

@@ -0,0 +1,31 @@
+/**
+ * HU-2792: two branches can add `.karajan/adrs/0037-a.md` and `0037-b.md` in
+ * parallel: the names differ, so git sees no conflict and both land with the
+ * same number. CI judges a PR that adds an ADR whose number the base already
+ * holds under another name (unless the same diff deletes that one: a rename).
+ */
+export const ADR_RULE = "defaults.adr.number";
+const ADR_DIR = ".karajan/adrs/";
+const ADR = /^\.karajan\/adrs\/(\d{4})-[^/]*\.md$/;
+const lines = (text) => text.split("\n").map((s) => s.trim()).filter(Boolean);
+const numberOf = (file) => Number(ADR.exec(file)[1]);
+
+/**
+ * @param {{files: string[], range: string|null, run: (args: string[]) => Promise<string>}} opts
+ * @returns {Promise<object|null>} the violation, or null when no added ADR collides with the base
+ */
+export async function adrNumberViolation({ files, range, run }) {
+  if (!files.some((f) => ADR.test(f))) return null;
+  const baseRef = range ? range.split(/\.{2,3}/)[0] : "HEAD";
+  const changes = lines(await run(["diff", "--no-renames", "--name-status", ...(range ? ["--end-of-options", range] : ["--cached"])])).map((l) => l.split("\t"));
+  const added = changes.filter(([status, file]) => status === "A" && ADR.test(file)).map(([, file]) => file);
+  const deleted = new Set(changes.filter(([status]) => status === "D").map(([, file]) => file));
+  const onBase = lines(await run(["ls-tree", "--name-only", "--end-of-options", baseRef, ADR_DIR])).filter((f) => ADR.test(f));
+  for (const file of added) {
+    const clash = onBase.find((f) => f !== file && numberOf(f) === numberOf(file) && !deleted.has(f));
+    if (!clash) continue;
+    const next = String(Math.max(...onBase.map(numberOf), ...added.map(numberOf)) + 1).padStart(4, "0");
+    return { rule_id: ADR_RULE, enforcement: "deny", file, reason: `${file} reuses the ADR number of ${clash}, which the base already has; the next free number is ${next}` };
+  }
+  return null;
+}