karajan-code 3.0.0 → 3.2.0

package/src/plan/plan-hu-ops.js

@@ -1,338 +1,16 @@
-/**
- * HU CRUD operations on a v2 plan.
- * All functions mutate the plan in-place and return it.
- */
-
-import { generateHuId } from "./plan-id.js";
-
-/**
- * Get the next sequential HU number for this plan.
- */
-function nextSeq(plan) {
-  if (!plan.hus || plan.hus.length === 0) return 1;
-  const nums = plan.hus
-    .map(h => {
-      const m = h.id.match(/_(\d+)$/);
-      return m ? Number(m[1]) : 0;
-    })
-    .filter(n => n > 0);
-  return nums.length > 0 ? Math.max(...nums) + 1 : plan.hus.length + 1;
-}
-
-/**
- * Add an HU to the plan. Auto-generates a globally unique ID.
- * @param {object} plan - v2 plan
- * @param {object} huData - { title, task_type?, scope?, acceptance_criteria?, acceptance_tests?, blocked_by?, reuse? }
- * @returns {object} the created HU (with id assigned)
- */
-export function addHu(plan, huData) {
-  const seq = nextSeq(plan);
-  const id = generateHuId(plan.planId, seq);
-  const hu = {
-    id,
-    title: huData.title,
-    task_type: huData.task_type || "sw",
-    status: "pending",
-    // KJC-TSK-0394: result ortogonal al status (último resultado conocido
-    // de la ejecución; null = nunca ejecutada). Se actualiza cuando el
-    // pipeline termina con pass / fail / partial. Nombre `result` (no
-    // `outcome`) porque `outcome` ya está en uso como blob JSON con
-    // iterations/duration/commits del run.
-    result: huData.result ?? null,
-    // Humanización IDs: short_id es el id legible que el planner asignó
-    // al step (ej "INFRA-001", "AUTH-SIGNUP"). El `id` largo
-    // (`hu_<planId>_<NNN>`) sigue siendo la clave canónica, pero el
-    // CLI / board prefieren short_id para mostrar y aceptarlo como
-    // referencia en `--hu`. Null cuando el planner no lo emitió.
-    short_id: huData.short_id || null,
-    blocked_by: huData.blocked_by || [],
-    // KJC-BUG-0044 / P3: ids of OTHER HUs whose implementation this HU
-    // piggy-backs on instead of reimplementing the same logic. Set by
-    // the planner; consumed by the coder prompt + plan-reviewer to
-    // avoid duplicate code generation.
-    reuse: huData.reuse || [],
-    scope: huData.scope || null,
-    acceptance_criteria: huData.acceptance_criteria || [],
-    acceptance_tests: huData.acceptance_tests || [],
-    // Spec mapping (v2.7.5 PR C): the SPEC.md section / heading this
-    // HU implements. Lets the coder cite "this implements SPEC §5.3"
-    // in PRs and the reviewer trace coverage gaps when the SPEC is
-    // re-read. Free-form string — typically "5.3", "§5.3 Initial
-    // Scope", or whatever the planner extracted from the source spec.
-    spec_section: huData.spec_section || null,
-    // KJC-TSK-0405: coder_model y reviewer_model asignados por el
-    // triage según complexity. null = usar el del config global / role
-    // resolver. Independientes — el usuario puede overridearlos por HU
-    // desde el board sin tocar el resto del plan.
-    coder_model: huData.coder_model ?? null,
-    coder_provider: huData.coder_provider ?? null,
-    reviewer_model: huData.reviewer_model ?? null,
-    reviewer_provider: huData.reviewer_provider ?? null,
-    // KJC-PRP-0002 PR6: optional handle of the human (or AI dev_XXX) who
-    // owns this HU in a team-shared board. null = unassigned. Free-form
-    // string — the board prints it as-is; no entity table is enforced
-    // because team rosters are out of scope (and would force every solo
-    // dev to register themselves).
-    assignee: huData.assignee ?? null,
-    createdAt: new Date().toISOString(),
-    updatedAt: new Date().toISOString()
-  };
-  plan.hus.push(hu);
-  plan.updatedAt = new Date().toISOString();
-  return hu;
-}
-
-/**
- * Remove an HU from the plan. Also cleans blocked_by references.
- * @returns {boolean} true if removed
- */
-export function removeHu(plan, huId) {
-  const idx = plan.hus.findIndex(h => h.id === huId);
-  if (idx === -1) return false;
-  plan.hus.splice(idx, 1);
-  // Clean up blocked_by + reuse refs
-  for (const hu of plan.hus) {
-    hu.blocked_by = (hu.blocked_by || []).filter(dep => dep !== huId);
-    hu.reuse = (hu.reuse || []).filter(dep => dep !== huId);
-  }
-  plan.updatedAt = new Date().toISOString();
-  return true;
-}
-
-/**
- * Partial update of an HU.
- * @param {object} plan
- * @param {string} huId
- * @param {object} patch - fields to update (title, scope, task_type, acceptance_criteria, acceptance_tests, blocked_by)
- * @returns {object|null} updated HU or null if not found
- */
-export function updateHu(plan, huId, patch) {
-  const hu = plan.hus.find(h => h.id === huId);
-  if (!hu) return null;
-  // KJC-TSK-0405: coder_model y reviewer_model son override per-HU del
-  // routing automático del triage. Independientes — el usuario puede
-  // subir el reviewer sin tocar el coder, o viceversa.
-  const allowed = ["title", "task_type", "scope", "acceptance_criteria", "acceptance_tests", "blocked_by", "reuse", "spec_section", "result", "short_id", "coder_model", "reviewer_model", "coder_provider", "reviewer_provider", "assignee"];
-  for (const key of allowed) {
-    if (patch[key] !== undefined) hu[key] = patch[key];
-  }
-  hu.updatedAt = new Date().toISOString();
-  plan.updatedAt = new Date().toISOString();
-  return hu;
-}
-
-/**
- * Update HU status.
- * @returns {boolean} true if updated
- */
-export function updateHuStatus(plan, huId, status) {
-  const hu = plan.hus.find(h => h.id === huId);
-  if (!hu) return false;
-  hu.status = status;
-  hu.updatedAt = new Date().toISOString();
-  plan.updatedAt = new Date().toISOString();
-  return true;
-}
-
-/**
- * Stamp the per-HU outcome — what actually happened during execution.
- * Written ONCE per HU, at the end of runSingleHu in hu-sub-pipeline.
- * Consumed by the board to render the per-HU summary indicator and
- * by `kj report` for retrospective inspection.
- *
- * Shape (every field optional except status + finishedAt):
- *   {
- *     status:       "done" | "failed" | "blocked",
- *     iterations:   number,        // how many coder→reviewer rounds
- *     duration_ms:  number,        // wall-clock for this HU
- *     branch:       string|null,   // git branch the coder used
- *     commits:      string[],      // SHA list captured during the run
- *     pr_url:       string|null,
- *     blockers:     string[],      // why it failed/was blocked, plain
- *     summary:      string,        // 1-2 sentence human summary
- *     finishedAt:   ISO timestamp
- *   }
- *
- * @returns {boolean} true if the HU was found and the outcome stored
- */
-export function setHuOutcome(plan, huId, outcome) {
-  const hu = plan.hus.find(h => h.id === huId);
-  if (!hu) return false;
-  hu.outcome = {
-    status: outcome.status || hu.status || null,
-    iterations: outcome.iterations ?? null,
-    duration_ms: outcome.duration_ms ?? null,
-    branch: outcome.branch ?? null,
-    commits: Array.isArray(outcome.commits) ? outcome.commits : [],
-    pr_url: outcome.pr_url ?? null,
-    blockers: Array.isArray(outcome.blockers) ? outcome.blockers : [],
-    summary: outcome.summary || "",
-    finishedAt: outcome.finishedAt || new Date().toISOString(),
-  };
-  hu.updatedAt = new Date().toISOString();
-  plan.updatedAt = new Date().toISOString();
-  return true;
-}
-
-/**
- * Stamp the plan-level rollup once every HU has finished. Built from
- * the per-HU outcomes so the board can show "Plan finished · 8 done
- * · 2 failed · 1 blocked · 15 min" in one banner.
- *
- *   {
- *     status:       "done" | "partial" | "failed",
- *     total:        number,
- *     counts:       { done, failed, blocked, pending },
- *     duration_ms:  number,
- *     prs:          string[],            // unique pr_url across HUs
- *     blockers:     string[],            // dedup'd blockers
- *     finishedAt:   ISO timestamp,
- *   }
- */
-export function setPlanOutcome(plan, outcome) {
-  plan.outcome = {
-    status: outcome.status || "partial",
-    total: outcome.total ?? (plan.hus?.length || 0),
-    counts: outcome.counts || { done: 0, failed: 0, blocked: 0, pending: 0 },
-    duration_ms: outcome.duration_ms ?? null,
-    prs: Array.isArray(outcome.prs) ? [...new Set(outcome.prs.filter(Boolean))] : [],
-    blockers: Array.isArray(outcome.blockers) ? [...new Set(outcome.blockers.filter(Boolean))] : [],
-    finishedAt: outcome.finishedAt || new Date().toISOString(),
-  };
-  plan.updatedAt = new Date().toISOString();
-}
-
-/**
- * PR-E: auto-promote every pending HU with at least one acceptance
- * test to "certified". The intermediate "certified" state was an
- * invisible wall — there's no UI button for it and the user had no
- * way to discover `kj plan ready`. Treating pending-with-tests as
- * runnable removes the wall while keeping the test contract gate.
- *
- * Mutates plan in place. HUs in done / failed / blocked are left
- * alone so re-runs stay explicit (use --hu <id>).
- *
- * @returns {number} how many HUs were promoted (0 if nothing changed).
- */
-export function autoCertifyPendingHus(plan) {
-  if (!plan?.hus?.length) return 0;
-  let promoted = 0;
-  const now = new Date().toISOString();
-  for (const hu of plan.hus) {
-    if (hu.status === "pending" && Array.isArray(hu.acceptance_tests) && hu.acceptance_tests.length > 0) {
-      hu.status = "certified";
-      hu.updatedAt = now;
-      promoted += 1;
-    }
-  }
-  if (promoted > 0) plan.updatedAt = now;
-  return promoted;
-}
-
-/**
- * PR-E: assert that the plan has at least one HU that's actually
- * going to run. Throws with a plain-Spanish message otherwise so
- * `kj run --plan` can never silently fall back to single-task mode
- * and burn tokens for nothing.
- *
- * The set of "runnable" statuses matches the sub-pipeline filter
- * (today: certified). The caller should run autoCertifyPendingHus()
- * BEFORE this so pending-with-tests get a chance.
- *
- * @throws {Error} when no HU is runnable.
- */
-export function assertPlanRunnable(plan, planId) {
-  if (!plan?.hus?.length) {
-    throw new Error(
-      `El plan ${planId} no contiene ninguna HU. `
-      + `Edita el plan o vuelve a generarlo con \`kj plan\`. `
-      + `Aborto para no malgastar tokens en un fallback de "single task".`
-    );
-  }
-  const certified = plan.hus.filter((h) => h.status === "certified").length;
-  if (certified > 0) return;
-  const counts = plan.hus.reduce((acc, h) => {
-    const k = h.status || "pending";
-    acc[k] = (acc[k] || 0) + 1;
-    return acc;
-  }, {});
-  const summary = Object.entries(counts).map(([k, v]) => `${v} ${k}`).join(", ");
-  throw new Error(
-    `Plan ${planId}: 0 HU(s) listas para ejecutar (estados: ${summary}). `
-    + `Si las HU(s) están en done/failed/blocked y quieres relanzarlas, usa --hu <id>. `
-    + `Aborto para no malgastar tokens en un fallback de "single task".`
-  );
-}
-
-/**
- * Compute the rollup from the per-HU outcomes already stamped on the
- * plan. Invoked by syncResultsToPlan in plan-executor when the run
- * ends so the caller doesn't have to assemble the counts by hand.
- */
-export function computePlanOutcome(plan, { duration_ms = null } = {}) {
-  const hus = plan.hus || [];
-  const counts = { done: 0, failed: 0, blocked: 0, pending: 0 };
-  const prs = [];
-  const blockers = [];
-  for (const hu of hus) {
-    const status = hu.outcome?.status || hu.status || "pending";
-    if (counts[status] !== undefined) counts[status] += 1;
-    else counts.pending += 1;
-    if (hu.outcome?.pr_url) prs.push(hu.outcome.pr_url);
-    if (Array.isArray(hu.outcome?.blockers)) blockers.push(...hu.outcome.blockers);
-  }
-  let status = "done";
-  if (counts.failed > 0 || counts.blocked > 0) status = counts.done > 0 ? "partial" : "failed";
-  if (counts.done === 0 && counts.failed === 0 && counts.blocked === 0) status = "pending";
-  return {
-    status,
-    total: hus.length,
-    counts,
-    duration_ms,
-    // Dedupe at the rollup boundary — same PR / blocker reported by
-    // multiple HUs is noise in the banner.
-    prs: [...new Set(prs.filter(Boolean))],
-    blockers: [...new Set(blockers.filter(Boolean))],
-    finishedAt: new Date().toISOString(),
-  };
-}
-
-/**
- * Mark all pending HUs as certified (ready to execute).
- * Sets plan status to "ready".
- * @returns {number} count of certified HUs
- */
-export function certifyAllHus(plan) {
-  let count = 0;
-  for (const hu of plan.hus) {
-    if (hu.status === "pending") {
-      hu.status = "certified";
-      hu.updatedAt = new Date().toISOString();
-      count++;
-    }
-  }
-  plan.status = "ready";
-  plan.updatedAt = new Date().toISOString();
-  return count;
-}
-
-/**
- * Reorder HUs by providing an ordered list of IDs.
- * Updates blocked_by to reflect the linear order.
- * @param {object} plan
- * @param {string[]} orderedIds
- */
-export function reorderHus(plan, orderedIds) {
-  const map = new Map(plan.hus.map(h => [h.id, h]));
-  const reordered = [];
-  for (const id of orderedIds) {
-    const hu = map.get(id);
-    if (hu) reordered.push(hu);
-  }
-  // Add any HUs not in the ordered list at the end
-  for (const hu of plan.hus) {
-    if (!orderedIds.includes(hu.id)) reordered.push(hu);
-  }
-  plan.hus = reordered;
-  plan.updatedAt = new Date().toISOString();
-}
+// Shim: plan-hu-ops now lives in @karajan/core/plan-hu-ops so the
+// hu-board workspace can consume it without a relative dep on the CLI
+// src tree. KJC-TSK-0511 PR5.
+export {
+  addHu,
+  removeHu,
+  updateHu,
+  updateHuStatus,
+  setHuOutcome,
+  setPlanOutcome,
+  autoCertifyPendingHus,
+  assertPlanRunnable,
+  computePlanOutcome,
+  certifyAllHus,
+  reorderHus,
+} from "@karajan/core/plan-hu-ops";

package/src/plan/plan-id.js

@@ -1,45 +1,4 @@
-/**
- * Plan + HU ID generation.
- * Globally unique IDs that never collide across plans.
- */
-
-/**
- * Generate a unique plan ID: plan-<YYYYMMDDHHMMSS>-<4-char random>
- */
-export function generatePlanId() {
-  const now = new Date();
-  const ts = now.toISOString().replaceAll(/[-:T]/g, "").replace(/\.\d+Z$/, "");
-  const rand = Math.random().toString(36).slice(2, 6);
-  return `plan-${ts}-${rand}`;
-}
-
-/**
- * Generate a globally unique HU ID scoped to a plan.
- * Format: hu_<planId>_<3-digit sequence>
- * @param {string} planId
- * @param {number} seq - 1-based sequence number
- * @returns {string}
- */
-export function generateHuId(planId, seq) {
-  return `hu_${planId}_${String(seq).padStart(3, "0")}`;
-}
-
-/**
- * Normalise a human-friendly name into a CLI-typeable alias.
- * "Greta App" → "greta-app", "Linux Assistant Orchestrator" → "linux-assistant-orchestrator".
- * Acotado a 60 chars para que no se vuelva tan ilegible como el planId.
- *
- * @param {string|null|undefined} name
- * @returns {string|null} alias o null si name está vacío.
- */
-export function normaliseAlias(name) {
-  if (!name || typeof name !== "string") return null;
-  const slug = name
-    .normalize("NFKD")
-    .replaceAll(/[̀-ͯ]/g, "")        // strip diacritics
-    .toLowerCase()
-    .replaceAll(/[^a-z0-9]+/g, "-")            // non-alphanum → guion
-    .replaceAll(/^-+|-+$/g, "")                // trim guiones extremos
-    .slice(0, 60);
-  return slug || null;
-}
+// Shim: plan-id primitives now live in @karajan/core/plan-id so the
+// hu-board workspace can consume them without a relative dep on the
+// CLI src tree. KJC-TSK-0511 PR5.
+export { generatePlanId, generateHuId, normaliseAlias } from "@karajan/core/plan-id";

package/src/plan/plan-validation.js

@@ -1,82 +1,4 @@
-// KJC-TSK-0401: validación estructural de cambios en blocked_by desde
-// el board. Se usa antes de persistir un PATCH /api/stories/:id para
-// que el usuario no pueda crear ciclos ni referencias huérfanas. La UI
-// preview la usa para deshabilitar las opciones que romperían el plan.
-
-/**
- * Verifica que `newBlockedBy` para `huId` no rompa la estructura del plan.
- *
- * Reglas:
- *   1. Cada ref en newBlockedBy debe existir como hu.id en el plan.
- *   2. No se permite auto-dependencia (huId ∈ newBlockedBy).
- *   3. Aplicar el cambio NO debe crear un ciclo en el grafo blocked_by.
- *
- * @param {object} plan
- * @param {string} huId
- * @param {string[]} newBlockedBy
- * @returns {{ ok: true } | { ok: false, error: string, cycle?: string[] }}
- */
-export function validateBlockedByChange(plan, huId, newBlockedBy) {
-  if (!plan || !Array.isArray(plan.hus)) {
-    return { ok: false, error: "plan inválido" };
-  }
-  const hu = plan.hus.find((h) => h.id === huId);
-  if (!hu) return { ok: false, error: `HU no encontrada: ${huId}` };
-  if (!Array.isArray(newBlockedBy)) {
-    return { ok: false, error: "blocked_by debe ser un array" };
-  }
-  const ids = new Set(plan.hus.map((h) => h.id));
-  for (const ref of newBlockedBy) {
-    if (typeof ref !== "string") {
-      return { ok: false, error: "blocked_by contiene un valor no-string" };
-    }
-    if (ref === huId) {
-      return { ok: false, error: `auto-dependencia no permitida: ${huId}` };
-    }
-    if (!ids.has(ref)) {
-      return { ok: false, error: `HU referenciada inexistente: ${ref}` };
-    }
-  }
-  // Simular el cambio sobre una copia del grafo y buscar ciclos.
-  const graph = new Map();
-  for (const h of plan.hus) {
-    graph.set(h.id, h.id === huId ? [...newBlockedBy] : (Array.isArray(h.blocked_by) ? [...h.blocked_by] : []));
-  }
-  const cycle = findCycleContaining(graph, huId);
-  if (cycle) {
-    return { ok: false, error: `Ciclo detectado: ${cycle.join(" → ")} → ${cycle[0]}`, cycle };
-  }
-  return { ok: true };
-}
-
-/**
- * DFS desde `start` siguiendo aristas blocked_by. Devuelve el primer
- * ciclo encontrado que pase por `start`, o null. La búsqueda no es
- * exhaustiva — basta con detectar UN ciclo para rechazar el cambio.
- *
- * @param {Map<string,string[]>} graph
- * @param {string} start
- * @returns {string[]|null}
- */
-function findCycleContaining(graph, start) {
-  const onStack = new Set();
-  const visited = new Set();
-  const stack = [];
-  function dfs(node) {
-    if (onStack.has(node)) {
-      const idx = stack.indexOf(node);
-      if (idx >= 0) return stack.slice(idx);
-      return [node];
-    }
-    if (visited.has(node)) return null;
-    onStack.add(node); stack.push(node); visited.add(node);
-    for (const dep of graph.get(node) || []) {
-      if (!graph.has(dep)) continue;
-      const found = dfs(dep);
-      if (found) return found;
-    }
-    stack.pop(); onStack.delete(node);
-    return null;
-  }
-  return dfs(start);
-}
+// Shim: plan-validation now lives in @karajan/core/plan-validation so
+// the hu-board workspace can consume it without a relative dep on the
+// CLI src tree. KJC-TSK-0511 PR6.
+export { validateBlockedByChange } from "@karajan/core/plan-validation";

package/src/prompts/tool-correctness-judge.js

@@ -0,0 +1,31 @@
+// KJC-TSK-0375 — Prompt builder for the ToolCorrectnessJudge role.
+// Inspired by deepeval's tool-correctness metric.
+
+const PREAMBLE = "IMPORTANT: You are running as a Karajan sub-agent. "
+  + "Do NOT use any MCP tools, do NOT mention Karajan. "
+  + "Your job is to judge another agent's tool choices.";
+
+export function buildToolCorrectnessJudgePrompt({ task, toolCalls, instructions }) {
+  const calls = toolCalls
+    .map((c, i) => `${i + 1}. **${c.tool}** — args: ${JSON.stringify(c.args)}`)
+    .join("\n");
+  const body = [
+    "You are the ToolCorrectnessJudge for Karajan Code.",
+    "Input: (a) a task description and (b) the ordered tool calls an LLM coder",
+    "made (Read/Edit/Write/Bash/Glob/Grep/MultiEdit). Judge each call on:",
+    "  - tool choice: right tool for the intent?",
+    "  - argument quality: paths plausible, commands valid, no garbage placeholders?",
+    "Per-call verdict: `correct=true|false` + one-sentence `reason`.",
+    "Aggregate into a single 0-100 score:",
+    "  - 100 = every call right with clean args",
+    "  - 70-99 = mostly right, minor missteps",
+    "  - 40-69 = several wrong choices, budget wasted",
+    "  - 0-39 = predominantly bad, retry advised",
+    "Return a single valid JSON object and nothing else.",
+    'Schema: {"score":0-100,"summary":string,"breakdown":[{"tool":string,"args":object,"correct":boolean,"reason":string}]}',
+  ].join("\n");
+  const sections = [PREAMBLE];
+  if (instructions) sections.push(instructions);
+  sections.push(body, `## Task\n${task}`, `## Tool calls (${toolCalls.length})\n${calls || "(no tool calls captured)"}`);
+  return sections.join("\n\n");
+}