karajan-code 3.1.0 → 3.3.0

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

@@ -74,6 +74,62 @@ function buildHuTask(story) {
   return `Implement HU ${story.id}`;
 }
 
+/**
+ * Sum the cost_usd of a slice of BudgetTracker entries. Returns null
+ * (not 0) when the slice is empty or contains no usable cost data —
+ * the board uses null as "unmeasured" and renders no badge, while 0
+ * means "really free run". Mixing the two would silently hide free
+ * runs and falsely show "$0.00" for runs with no telemetry.
+ *
+ * Cost D (KJC-TSK-0515): the orchestrator calls this once per HU at
+ * runSingleHu exit, passing the slice of entries recorded during that
+ * HU (snapshotted via the entries.length cursor before the iteration
+ * starts). The resulting number flows through buildHuOutcome →
+ * notifyOutcome → setStoryCost in inject-loaded-plan.js.
+ *
+ * @param {Array<{cost_usd?: number}>} entries
+ * @returns {number|null}
+ */
+function sumCostUsd(entries) {
+  if (!Array.isArray(entries) || entries.length === 0) return null;
+  let total = 0;
+  let hasAny = false;
+  for (const e of entries) {
+    const n = Number(e?.cost_usd);
+    if (Number.isFinite(n)) {
+      total += n;
+      hasAny = true;
+    }
+  }
+  if (!hasAny) return null;
+  return Math.round(total * 1e6) / 1e6;
+}
+
+/**
+ * Sum an integer token-counter field across a slice of BudgetTracker
+ * entries (Φ0-G, KJC-TSK-0525). Same null-vs-0 semantics as sumCostUsd:
+ * returns null when nothing measurable was recorded so the board can
+ * distinguish "unmeasured" from "really zero".
+ *
+ * @param {Array<object>} entries
+ * @param {string} field — entry key to sum, e.g. "cached_tokens"
+ * @returns {number|null}
+ */
+function sumTokenField(entries, field) {
+  if (!Array.isArray(entries) || entries.length === 0) return null;
+  let total = 0;
+  let hasAny = false;
+  for (const e of entries) {
+    const n = Number(e?.[field]);
+    if (Number.isFinite(n) && n >= 0) {
+      total += n;
+      hasAny = true;
+    }
+  }
+  if (!hasAny) return null;
+  return Math.round(total);
+}
+
 /**
  * Build the per-HU outcome blob from whatever metadata the iteration
  * loop returned. Tolerant by design — most fields are optional and we
@@ -90,9 +146,11 @@ function buildHuTask(story) {
  * @param {object} args.iterResult — whatever runIterationFn returned
  * @param {string} args.status — HU_STATUS.* terminal value
  * @param {number} args.startedAt — Date.now() when runSingleHu started
+ * @param {Array} [args.huBudgetEntries] — slice of BudgetTracker
+ *   entries recorded during this HU. Cost D (KJC-TSK-0515).
  * @returns {object}
  */
-function buildHuOutcome({ story: _story, iterResult, status, startedAt }) {
+function buildHuOutcome({ story: _story, iterResult, status, startedAt, huBudgetEntries }) {
   const r = iterResult || {};
   const git = r.git || {};
   // Iterations are tracked in the standard pipeline as
@@ -123,6 +181,12 @@ function buildHuOutcome({ story: _story, iterResult, status, startedAt }) {
     pr_url: r.pr_url || r.prUrl || git.pr_url || null,
     blockers,
     summary,
+    cost_usd: sumCostUsd(huBudgetEntries),
+    // Φ0-G (KJC-TSK-0525): cached/input tokens drive the "🎯 N% cached"
+    // board badge. Null when nothing measurable was recorded so the UI
+    // can hide the chip on cold runs or providers without cache.
+    cached_tokens: sumTokenField(huBudgetEntries, 'cached_tokens'),
+    tokens_in: sumTokenField(huBudgetEntries, 'tokens_in'),
     finishedAt: new Date().toISOString(),
   };
 }
@@ -134,7 +198,7 @@ function buildHuOutcome({ story: _story, iterResult, status, startedAt }) {
  * @param {object} params
  * @returns {Promise<{huId: string, approved: boolean, result?: object, error?: string, blockedDependents?: string[]}>}
  */
-async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emitter, eventBase, logger, config, results, worktreePath, onStatusChange = null, onOutcome = null }) {
+async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emitter, eventBase, logger, config, results, worktreePath, onStatusChange = null, onOutcome = null, budgetTracker = null }) {
   // PR1 (live HU status): every saveHuBatch should also notify the
   // plan JSON so the board reflects state in real time. Defined as a
   // local helper so we don't repeat the try/null-check boilerplate.
@@ -157,6 +221,16 @@ async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emi
   // outcome (wall-clock per HU is what the user needs in the board,
   // not internal stage timings).
   const huStartedAt = Date.now();
+  // Cost D (KJC-TSK-0515): snapshot the budget cursor so we can slice
+  // out only the entries this HU produced. BudgetTracker is session-
+  // scoped (it accumulates across all HUs of the run), so without this
+  // cursor every HU after the first would inherit the previous ones'
+  // cost too. Null-safe — older callers without a tracker still work.
+  const huBudgetStartIdx = budgetTracker?.entries?.length ?? 0;
+  const sliceHuBudget = () => {
+    if (!budgetTracker?.entries) return [];
+    return budgetTracker.entries.slice(huBudgetStartIdx);
+  };
   const story = batch.stories.find(s => s.id === storyId);
 
   // --- Lazy refinement ---
@@ -226,7 +300,7 @@ async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emi
       await saveHuBatch(batchSessionId, batch);
       await notifyStatus(story.id, HU_STATUS.DONE);
       // PR3: build + persist the per-HU outcome.
-      const okOutcome = buildHuOutcome({ story, iterResult, status: HU_STATUS.DONE, startedAt: huStartedAt });
+      const okOutcome = buildHuOutcome({ story, iterResult, status: HU_STATUS.DONE, startedAt: huStartedAt, huBudgetEntries: sliceHuBudget() });
       await notifyOutcome(story.id, okOutcome);
       emitProgress(emitter, makeEvent("hu:status-change", { ...eventBase, stage: "hu-sub-pipeline" }, {
         message: `HU ${story.id} status → done`,
@@ -242,7 +316,7 @@ async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emi
       updateStoryStatus(batch, story.id, HU_STATUS.FAILED);
       await saveHuBatch(batchSessionId, batch);
       await notifyStatus(story.id, HU_STATUS.FAILED);
-      const failOutcome = buildHuOutcome({ story, iterResult, status: HU_STATUS.FAILED, startedAt: huStartedAt });
+      const failOutcome = buildHuOutcome({ story, iterResult, status: HU_STATUS.FAILED, startedAt: huStartedAt, huBudgetEntries: sliceHuBudget() });
       await notifyOutcome(story.id, failOutcome);
       emitProgress(emitter, makeEvent("hu:status-change", { ...eventBase, stage: "hu-sub-pipeline" }, {
         message: `HU ${story.id} status → failed`,
@@ -259,7 +333,7 @@ async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emi
     updateStoryStatus(batch, story.id, HU_STATUS.FAILED);
     await saveHuBatch(batchSessionId, batch);
     await notifyStatus(story.id, HU_STATUS.FAILED);
-    const errOutcome = buildHuOutcome({ story, iterResult: { error: err.message }, status: HU_STATUS.FAILED, startedAt: huStartedAt });
+    const errOutcome = buildHuOutcome({ story, iterResult: { error: err.message }, status: HU_STATUS.FAILED, startedAt: huStartedAt, huBudgetEntries: sliceHuBudget() });
     await notifyOutcome(story.id, errOutcome);
     emitProgress(emitter, makeEvent("hu:status-change", { ...eventBase, stage: "hu-sub-pipeline" }, {
       message: `HU ${story.id} status → failed`,
@@ -287,7 +361,7 @@ async function runSingleHu({ storyId, batch, batchSessionId, runIterationFn, emi
  * @param {object} params.logger - Logger instance
  * @returns {Promise<{approved: boolean, results: object[], blockedIds: string[]}>}
  */
-export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitter, eventBase, logger, config = null, onStatusChange = null, onOutcome = null }) {
+export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitter, eventBase, logger, config = null, onStatusChange = null, onOutcome = null, budgetTracker = null }) {
   const batchSessionId = huReviewerResult.batchSessionId;
   let batch;
   try {
@@ -404,7 +478,7 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
       // Single HU: run as before, no worktree needed
       const singleResult = await runSingleHu({
         storyId: runnableIds[0], batch, batchSessionId, runIterationFn,
-        emitter, eventBase, logger, config, results, onStatusChange, onOutcome
+        emitter, eventBase, logger, config, results, onStatusChange, onOutcome, budgetTracker
       });
       results.push(singleResult);
       if (!singleResult.approved) {
@@ -443,7 +517,7 @@ export async function runHuSubPipeline({ huReviewerResult, runIterationFn, emitt
           storyId, batch, batchSessionId, runIterationFn,
           emitter, eventBase, logger, config, results,
           worktreePath: worktrees.get(storyId),
-          onStatusChange, onOutcome
+          onStatusChange, onOutcome, budgetTracker
         });
       });
 

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";