karajan-code 2.14.3 → 2.16.0

package/src/orchestrator/drivers/pre-loop-phases/inject-loaded-plan.js

@@ -189,23 +189,33 @@ function applyHuFilterIfRequested({ huBatch, flags, eventBase, emitter, logger }
     logger.warn(`--hu was empty after parsing — falling back to running every certified HU`);
     return;
   }
-  const requestedSet = new Set(requested);
-  const found = huBatch.stories.filter((s) => requestedSet.has(s.id));
-  const missing = requested.filter((id) => !huBatch.stories.some((s) => s.id === id));
-  if (missing.length > 0) {
-    logger.warn(`--hu: ignored ${missing.length} unknown HU id(s): ${missing.join(", ")}`);
+  // Humanización IDs: resolver cada ref a un hu.id largo aceptando 3 formas:
+  //  1. `hu_<planId>_<NNN>` (id largo, exacto)
+  //  2. `INFRA-001` (short_id que el planner asignó)
+  //  3. `001` (sufijo numérico — busca un hu.id que termine en `_001`)
+  // El resolver es case-insensitive para short_id y sufijo.
+  const resolvedIds = new Set();
+  const unresolved = [];
+  for (const ref of requested) {
+    const id = resolveHuRef(ref, huBatch.stories);
+    if (id) resolvedIds.add(id);
+    else unresolved.push(ref);
+  }
+  const found = huBatch.stories.filter((s) => resolvedIds.has(s.id));
+  if (unresolved.length > 0) {
+    logger.warn(`--hu: ignored ${unresolved.length} unknown HU ref(s): ${unresolved.join(", ")}`);
   }
   if (found.length === 0) {
-    throw new Error(`--hu: none of the requested HU id(s) exist in plan ${flags.plan}: ${requested.join(", ")}`);
+    throw new Error(`--hu: none of the requested HU ref(s) exist in plan ${flags.plan}: ${requested.join(", ")}`);
   }
   for (const story of huBatch.stories) {
-    if (!requestedSet.has(story.id)) story.status = "done";
+    if (!resolvedIds.has(story.id)) story.status = "done";
   }
   huBatch.certified = found.length;
   logger.info(`Plan ${flags.plan}: --hu filter active — ${found.length}/${huBatch.total} HU(s) will run (${found.map((s) => s.id).join(", ")})`);
   emitProgress(emitter, makeEvent("plan:hu-filter", { ...eventBase, stage: "plan" }, {
     message: `--hu filter: ${found.length} HU(s) selected, ${huBatch.total - found.length} skipped`,
-    detail: { planId: flags.plan, requested, ignored: missing, willRun: found.map((s) => s.id) }
+    detail: { planId: flags.plan, requested, ignored: unresolved, willRun: found.map((s) => s.id) }
   }));
 }
 
@@ -246,6 +256,35 @@ function wirePlanCallbacks({ session, loadedPlan, projectDir, syncResultsToPlan,
   });
 }
 
+/**
+ * Resuelve una referencia humana a HU al `id` canónico largo. Acepta:
+ *   - id largo exacto: `hu_<planId>_<NNN>` → match directo.
+ *   - short_id: `INFRA-001`, `AUTH-SIGNUP` → match case-insensitive contra hu.short_id.
+ *   - sufijo numérico: `001` → match contra hu.id terminado en `_001`.
+ * Devuelve el hu.id largo o null si no resuelve.
+ *
+ * @param {string} ref
+ * @param {Array<{id: string, short_id?: string|null}>} hus
+ * @returns {string|null}
+ */
+function resolveHuRef(ref, hus) {
+  if (!ref || !Array.isArray(hus)) return null;
+  // Match exacto contra id largo (camino caliente).
+  const exact = hus.find((s) => s.id === ref);
+  if (exact) return exact.id;
+  // Match case-insensitive contra short_id.
+  const lower = ref.toLowerCase();
+  const byShort = hus.find((s) => s.short_id && String(s.short_id).toLowerCase() === lower);
+  if (byShort) return byShort.id;
+  // Match por sufijo numérico (`001` → cualquier hu cuyo id termine en `_001`).
+  if (/^\d+$/.test(ref)) {
+    const padded = ref.padStart(3, "0");
+    const bySuffix = hus.find((s) => s.id.endsWith(`_${padded}`));
+    if (bySuffix) return bySuffix.id;
+  }
+  return null;
+}
+
 /**
  * Build a single plannedTask string for the non-HU / fallback
  * iteration path. The HU sub-pipeline doesn't read this; only the

package/src/orchestrator/drivers/run-hu-batch.js

@@ -31,6 +31,7 @@ import { classifyFailure, createFailureTracker } from "../repair/repair-detector
 import { runRepair } from "../repair/repair-runner.js";
 import { writeHistoryRecord } from "./post-loop.js";
 import { setReviewerFeedback } from "../../session/mutators.js";
+import { createHuSnapshot } from "../../git/hu-snapshot.js";
 
 /**
  * @param {object} args
@@ -91,19 +92,44 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
         ctx.brainCtx.feedbackQueue = fresh.feedbackQueue;
         ctx.brainCtx.verificationTracker = fresh.verificationTracker;
       }
-      // Apply per-HU policies based on task_type (infra skips reviewer/sonar/tdd)
-      const { applyPolicies } = await import("../../guards/policy-resolver.js");
-      const huPolicies = applyPolicies({ taskType: story.task_type, policies: ctx.config.policies });
+      // Apply per-HU policies based on task_type (infra skips reviewer/sonar/tdd).
+      // KJC-TSK-0400: `effectiveTaskType` mira primero story.task_type y, si
+      // no es válido, infiere del prefijo del title ([SPIKE], [DOC]…). Así
+      // un HU con title "[SPIKE] Decidir auth" entra automáticamente a las
+      // policies de spike (sin Sonar/TDD/tests).
+      const { applyPolicies, effectiveTaskType } = await import("../../guards/policy-resolver.js");
+      const resolvedTaskType = effectiveTaskType(story);
+      if (resolvedTaskType !== story.task_type) {
+        logger.info(`HU ${story.id}: task_type inferido del title → ${resolvedTaskType} (era ${story.task_type || "null"})`);
+      }
+      const huPolicies = applyPolicies({ taskType: resolvedTaskType, policies: ctx.config.policies });
       const savedFlags = { ...ctx.pipelineFlags };
       if (!huPolicies.reviewer) ctx.pipelineFlags.reviewerEnabled = false;
       if (!huPolicies.tdd) ctx.config.development = { ...ctx.config.development, methodology: "standard", require_test_changes: false };
       if (!huPolicies.sonar) ctx.config.sonarqube = { ...ctx.config.sonarqube, enabled: false };
       if (!huPolicies.testsRequired) ctx.pipelineFlags.testerEnabled = false;
-      logger.info(`HU ${story.id} (${story.task_type}): policies → reviewer=${huPolicies.reviewer}, tdd=${huPolicies.tdd}, sonar=${huPolicies.sonar}, tests=${huPolicies.testsRequired}`);
+      logger.info(`HU ${story.id} (${resolvedTaskType}): policies → reviewer=${huPolicies.reviewer}, tdd=${huPolicies.tdd}, sonar=${huPolicies.sonar}, tests=${huPolicies.testsRequired}`);
 
       const branchName = await prepareHuBranch({ story, huBranches, config: ctx.config, logger });
       const projectDir = ctx.config.projectDir || process.cwd();
 
+      // KJC-TSK-0408 step 2: snapshot del workspace ANTES de invocar al
+      // coder. Si el usuario hace Undo después, restaura este SHA. El
+      // ref se crea sobre el HEAD ya checkouteado a la rama de la HU,
+      // así que apunta al estado limpio sobre el que el coder empieza.
+      // Idempotente — si la HU ya tenía snapshot, se sobreescribe.
+      try {
+        const snap = await createHuSnapshot({ projectDir, huId: story.id });
+        if (snap.ok) {
+          story.outcome = { ...(story.outcome || {}), snapshot_sha: snap.sha, snapshot_ref: snap.ref };
+          logger.info(`HU ${story.id}: snapshot ${snap.sha.slice(0, 7)} (ref ${snap.ref})`);
+        } else {
+          logger.warn(`HU ${story.id}: snapshot falló (non-blocking): ${snap.error}`);
+        }
+      } catch (err) {
+        logger.warn(`HU ${story.id}: snapshot threw (non-blocking): ${err.message}`);
+      }
+
       // If HU has acceptance_tests, Brain runs them as the gate instead of
       // the standard reviewer/tester pipeline. This is the radical fix:
       // concrete executable tests replace subjective reviewer opinions.

package/src/orchestrator/repair/repair-detector.js

@@ -50,9 +50,9 @@ const INFEASIBLE_SIGNATURES = [
 export function failureSignature(cmd, errorOutput) {
   const cmdNorm = String(cmd || "").trim().slice(0, 200);
   const errNorm = String(errorOutput || "")
-    .replace(/\s+/g, " ")        // collapse whitespace
-    .replace(/\d+/g, "N")          // numbers tend to drift; line numbers, counts
-    .replace(/\/[^\s]+/g, "/PATH") // absolute paths drift across runs
+    .replaceAll(/\s+/g, " ")        // collapse whitespace
+    .replaceAll(/\d+/g, "N")          // numbers tend to drift; line numbers, counts
+    .replaceAll(/\/[^\s]+/g, "/PATH") // absolute paths drift across runs
     .trim()
     .slice(0, 300);
   return `${cmdNorm}|||${errNorm}`;

package/src/plan/adr-generator.js

@@ -38,11 +38,11 @@ function slugifyTitle(title) {
     // Decompose accents (NFD) then strip combining marks so "versión"
     // → "version", keeping the ADR id ASCII-only and filesystem-safe.
     .normalize("NFD")
-    .replace(/[̀-ͯ]/g, "")
-    .replace(/[^a-z0-9\s-]/g, "")
-    .replace(/\s+/g, "-")
-    .replace(/-+/g, "-")
-    .replace(/^-|-$/g, "")
+    .replaceAll(/[̀-ͯ]/g, "")
+    .replaceAll(/[^a-z0-9\s-]/g, "")
+    .replaceAll(/\s+/g, "-")
+    .replaceAll(/-+/g, "-")
+    .replaceAll(/^-|-$/g, "")
     .slice(0, 80) || "untitled";
 }
 

package/src/plan/plan-executor.js

@@ -5,7 +5,7 @@
  */
 
 import { isPlanV2 } from "./plan-schema.js";
-import { updateHuStatus, computePlanOutcome, setPlanOutcome } from "./plan-hu-ops.js";
+import { updateHuStatus, updateHu, computePlanOutcome, setPlanOutcome } from "./plan-hu-ops.js";
 
 /**
  * Convert a v2 plan's HUs into the stageResults.huReviewer format
@@ -63,9 +63,18 @@ export function planToHuBatch(plan) {
 export function syncResultsToPlan(plan, subPipelineResult) {
   if (!isPlanV2(plan)) return;
 
+  // KJC-TSK-0403: status/result ortogonal. HU fallida queda en status=pending
+  // con result=fail (no status=failed) para que el usuario pueda relanzarla
+  // con el contexto del fallo previo. El plan se considera failed si CUALQUIER
+  // HU tiene result=fail.
   for (const r of subPipelineResult.results || []) {
-    const status = r.approved ? "done" : "failed";
-    updateHuStatus(plan, r.huId, status);
+    if (r.approved) {
+      updateHuStatus(plan, r.huId, "done");
+      updateHu(plan, r.huId, { result: "pass" });
+    } else {
+      updateHuStatus(plan, r.huId, "pending");
+      updateHu(plan, r.huId, { result: "fail" });
+    }
   }
 
   for (const blockedId of subPipelineResult.blockedIds || []) {
@@ -73,7 +82,7 @@ export function syncResultsToPlan(plan, subPipelineResult) {
   }
 
   const allDone = plan.hus.every(h => h.status === "done");
-  const anyFailed = plan.hus.some(h => h.status === "failed");
+  const anyFailed = plan.hus.some(h => h.result === "fail");
   plan.status = allDone ? "done" : anyFailed ? "failed" : "running";
   plan.updatedAt = new Date().toISOString();
 

package/src/plan/plan-fixer.js

@@ -12,6 +12,7 @@
 import { extractFirstJson } from "../utils/json-extract.js";
 import { addHu, removeHu } from "./plan-hu-ops.js";
 import { normaliseAcceptanceTests } from "./plan-schema.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
 
 export function buildFixerPrompt({ task, hus, findings }) {
   const huSummary = hus.map((h) => {
@@ -90,14 +91,18 @@ function normalisePatch(raw) {
   return out;
 }
 
-export async function applyReviewerFeedback({ agent, task, hus, findings, onOutput, silenceTimeoutMs, timeoutMs }) {
+export async function applyReviewerFeedback({ agent, task, hus, findings, onOutput, silenceTimeoutMs, timeoutMs, emitter, eventBase, logger }) {
   const prompt = buildFixerPrompt({ task, hus, findings });
   const runArgs = { prompt, role: "planner" };
   if (onOutput) runArgs.onOutput = onOutput;
   if (silenceTimeoutMs) runArgs.silenceTimeoutMs = silenceTimeoutMs;
   if (timeoutMs) runArgs.timeoutMs = timeoutMs;
-  const result = await agent.runTask(runArgs);
-  if (!result.ok) return { ok: false, error: result.error || "fixer agent failed" };
+  // KJC-TSK-0413: Brain Recovery — fix loop ya no muere silencioso.
+  const result = await withBrainRecovery({
+    agent, taskArgs: runArgs, role: "plan-fixer",
+    emitter, eventBase, logger,
+  });
+  if (!result.ok) return { ok: false, error: result.error || `fixer agent failed (${result.recovery?.class || "unknown"})`, recovery: result.recovery, action: result.action };
   const parsed = extractFirstJson(result.output || "");
   if (!parsed || typeof parsed !== "object") {
     return { ok: false, error: "fixer returned no JSON object" };
@@ -110,16 +115,43 @@ export function applyFixerPatch(plan, patch) {
   for (const huId of patch.deletions || []) {
     if (removeHu(plan, huId)) counts.deleted += 1;
   }
+  // KJC-BUG-0053: las HUs añadidas por el fixer dejaban `short_id` y
+  // `blocked_by` vacíos porque addHu no recibía esos campos. Resultado:
+  // HUs huérfanas con id largo críptico y sin orden de ejecución.
+  //
+  // Fix: (1) pasar `short_id: a.id` (el id simbólico que el fixer LLM
+  // asigna a cada addition). (2) resolver `a.dependencies` simbólicas
+  // → hu.id largos contra el plan ya existente + el mapa de símbolos
+  // recién añadidos. La resolución necesita 2 pasadas (primera crea
+  // las HUs y registra el mapping, segunda asigna deps) para que
+  // additions que se referencian entre sí funcionen.
+  const symbolicToHuId = new Map();
+  for (const hu of plan.hus) {
+    if (hu.short_id) symbolicToHuId.set(hu.short_id, hu.id);
+  }
+  const addedHus = []; // {hu, depsSymbolic}
   for (const a of patch.additions || []) {
-    addHu(plan, {
+    const symbolicId = typeof a.id === "string" && a.id.trim() ? a.id.trim() : null;
+    const hu = addHu(plan, {
       title: (a.description || "").slice(0, 80),
       scope: a.description,
+      short_id: symbolicId,
       spec_section: a.spec_section,
       acceptance_tests: a.acceptance_tests,
       reuse: a.reuse || [],
     });
+    if (symbolicId) symbolicToHuId.set(symbolicId, hu.id);
+    const depsSymbolic = Array.isArray(a.dependencies) ? a.dependencies : [];
+    addedHus.push({ hu, depsSymbolic });
     counts.added += 1;
   }
+  // Pasada 2: resolver deps simbólicas de las additions a ids largos.
+  for (const { hu, depsSymbolic } of addedHus) {
+    const resolved = depsSymbolic
+      .map((s) => typeof s === "string" ? symbolicToHuId.get(s.trim()) : null)
+      .filter(Boolean);
+    if (resolved.length > 0) hu.blocked_by = resolved;
+  }
   const knownIds = new Set(plan.hus.map(h => h.id));
   for (const { huId, on } of patch.deps_to_add || []) {
     if (!knownIds.has(huId) || !knownIds.has(on)) continue;

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

@@ -33,6 +33,18 @@ export function addHu(plan, huData) {
     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
@@ -48,6 +60,14 @@ export function addHu(plan, huData) {
     // 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,
     createdAt: new Date().toISOString(),
     updatedAt: new Date().toISOString()
   };
@@ -83,7 +103,10 @@ export function removeHu(plan, huId) {
 export function updateHu(plan, huId, patch) {
   const hu = plan.hus.find(h => h.id === huId);
   if (!hu) return null;
-  const allowed = ["title", "task_type", "scope", "acceptance_criteria", "acceptance_tests", "blocked_by", "reuse", "spec_section"];
+  // 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"];
   for (const key of allowed) {
     if (patch[key] !== undefined) hu[key] = patch[key];
   }

package/src/plan/plan-id.js

@@ -8,7 +8,7 @@
  */
 export function generatePlanId() {
   const now = new Date();
-  const ts = now.toISOString().replace(/[-:T]/g, "").replace(/\.\d+Z$/, "");
+  const ts = now.toISOString().replaceAll(/[-:T]/g, "").replace(/\.\d+Z$/, "");
   const rand = Math.random().toString(36).slice(2, 6);
   return `plan-${ts}-${rand}`;
 }
@@ -23,3 +23,23 @@ export function generatePlanId() {
 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;
+}

package/src/plan/plan-migrate-result.js

@@ -0,0 +1,24 @@
+/**
+ * KJC-TSK-0394 step 4: migration helper para plan files existentes.
+ * Siembra `result` en las HUs vía inferResultFromLegacyStatus.
+ * Idempotente. NO toca `status` (eso será step 5).
+ */
+import { inferResultFromLegacyStatus } from "./plan-schema.js";
+
+/** Pura. Devuelve {plan: nuevo, changes: [...]}, sin mutar el input. */
+export function migratePlanResult(plan) {
+  if (!plan || !Array.isArray(plan.hus)) return { plan, changes: [] };
+  const changes = [];
+  const hus = plan.hus.map((hu) => {
+    // Sembrar explícito (incluso null) marca el HU como migrado para
+    // pasadas posteriores. hasOwnProperty distingue "no migrado" de
+    // "migrado a null".
+    const already = Object.prototype.hasOwnProperty.call(hu, "result") && hu.result !== undefined;
+    if (already) return hu;
+    const inferred = inferResultFromLegacyStatus(hu);
+    changes.push({ huId: hu.id, result: inferred });
+    return { ...hu, result: inferred };
+  });
+  if (changes.length === 0) return { plan, changes };
+  return { plan: { ...plan, hus, updatedAt: new Date().toISOString() }, changes };
+}

package/src/plan/plan-reviewer.js

@@ -30,6 +30,7 @@
  */
 
 import { extractFirstJson } from "../utils/json-extract.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
 
 /**
  * Build the focused review prompt. Exported for unit-testing the
@@ -113,7 +114,7 @@ export function buildReviewerPrompt({ task, hus }) {
  * @param {number} [args.timeoutMs]
  * @returns {Promise<{ ok: boolean, findings?: object, error?: string }>}
  */
-export async function reviewPlan({ agent, task, hus, onOutput, silenceTimeoutMs, timeoutMs }) {
+export async function reviewPlan({ agent, task, hus, onOutput, silenceTimeoutMs, timeoutMs, emitter, eventBase, logger }) {
   if (!Array.isArray(hus) || hus.length === 0) {
     return { ok: true, findings: emptyFindings("Plan has no HUs to review.") };
   }
@@ -123,9 +124,15 @@ export async function reviewPlan({ agent, task, hus, onOutput, silenceTimeoutMs,
   if (silenceTimeoutMs) runArgs.silenceTimeoutMs = silenceTimeoutMs;
   if (timeoutMs) runArgs.timeoutMs = timeoutMs;
 
-  const result = await agent.runTask(runArgs);
+  // KJC-TSK-0413: el caso real del 2026-05-16 (plan-fix iter 2 "failed
+  // 219.3s" sin clase) entraba aquí. Ahora Brain clasifica el fallo y
+  // decide retry/standby/hibernate/abort.
+  const result = await withBrainRecovery({
+    agent, taskArgs: runArgs, role: "plan-reviewer",
+    emitter, eventBase, logger,
+  });
   if (!result.ok) {
-    return { ok: false, error: result.error || "reviewer agent failed" };
+    return { ok: false, error: result.error || `reviewer agent failed (${result.recovery?.class || "unknown"})`, recovery: result.recovery, action: result.action };
   }
   const parsed = extractFirstJson(result.output || "");
   if (!parsed || typeof parsed !== "object") {
@@ -197,3 +204,33 @@ export function findingsCount(findings) {
     // parallelisable_groups is informational, not an issue.
   );
 }
+
+/**
+ * KJC-BUG-0054: count findings categorised por prioridad, para que
+ * el self-fix convergence guard pueda distinguir "regresión genuina"
+ * de "regresión por arreglar algo importante".
+ *
+ * Categorías:
+ *   - priority: ciclos (order_issues con issue=='circular') + missing_hus.
+ *     Estos NO pueden ignorarse — un ciclo deja el plan no ejecutable;
+ *     una HU faltante es feature missing.
+ *   - secondary: missing_dependencies + scope_overlaps + order_issues
+ *     no-circulares. Importantes pero recuperables.
+ *
+ * @param {object} findings
+ * @returns {{ priority: number, secondary: number, total: number, cycles: number }}
+ */
+export function findingsCountByType(findings) {
+  if (!findings) return { priority: 0, secondary: 0, total: 0, cycles: 0 };
+  const orderIssues = findings.order_issues || [];
+  const cycles = orderIssues.filter(
+    (i) => i && typeof i === "object" && i.issue === "circular"
+  ).length;
+  const orderNonCircular = orderIssues.length - cycles;
+  const missingHus = findings.missing_hus?.length || 0;
+  const missingDeps = findings.missing_dependencies?.length || 0;
+  const overlaps = findings.scope_overlaps?.length || 0;
+  const priority = cycles + missingHus;
+  const secondary = missingDeps + overlaps + orderNonCircular;
+  return { priority, secondary, total: priority + secondary, cycles };
+}

package/src/plan/plan-schema.js

@@ -7,10 +7,127 @@
 import { generatePlanId } from "./plan-id.js";
 
 const VALID_PLAN_STATUSES = new Set(["draft", "ready", "running", "done", "failed"]);
-const VALID_HU_STATUSES = new Set(["pending", "certified", "coding", "reviewing", "done", "failed", "blocked"]);
+// KJC-TSK-0394 step 5: el modelo CANONICAL del lifecycle es
+// {pending, running, done}. Los valores certified/coding/reviewing/
+// failed/blocked/needs_context se mantienen como LEGACY (siguen
+// aceptados por validatePlan para no romper plans existentes ni el
+// runtime actual). El cleanup definitivo del runtime queda como
+// follow-up; mientras tanto la UI puede usar canonicalStatus +
+// effectiveResult para presentar el modelo de 3 estados sin tocar
+// la persistencia.
+//
+// needs_context se PATCHeaba vía /api/stories/:id (dropdown libre del
+// modal) sin que el enum lo aceptara → `kj plan validate` daba
+// false-negative tras un set manual. Incluido aquí para alinear.
+const VALID_HU_STATUSES = new Set([
+  // Canonical
+  "pending", "running", "done",
+  // Legacy
+  "certified", "coding", "reviewing", "failed", "blocked", "needs_context",
+]);
+export const CANONICAL_HU_STATUSES = new Set(["pending", "running", "done"]);
+// KJC-TSK-0394: nuevo campo `result` ortogonal a status. Reemplaza la
+// sobrecarga semántica del status (certified=pass, failed=fail) por una
+// distinción explícita entre lifecycle (status) y último resultado (result).
+// Vacío `null` significa "nunca ejecutado". Migración no-breaking: status
+// legacy sigue válido durante el período de transición.
+// Nota: usamos `result` y NO `outcome` porque el campo `outcome` ya existe
+// con otra semántica (blob JSON con iterations/duration/commits del run).
+export const VALID_HU_RESULTS = new Set([null, "pass", "fail", "partial"]);
 const VALID_TASK_TYPES = new Set(["sw", "infra", "doc", "add-tests", "refactor", "nocode"]);
 const VALID_TEST_TYPES = new Set(["shell", "gherkin"]);
 
+/**
+ * KJC-TSK-0394 step 4: deduce `result` de un HU legacy. Idempotente.
+ * Heurística: done→pass (si hubiera fallado estaría en failed),
+ * failed→fail, resto→null. NO toca status (eso es step 5).
+ */
+export function inferResultFromLegacyStatus(hu) {
+  if (hu && hu.result != null) return hu.result;
+  if (hu?.status === "done") return "pass";
+  if (hu?.status === "failed") return "fail";
+  return null;
+}
+
+/**
+ * KJC-TSK-0394 step 5: mapea cualquier status (legacy o canonical) al
+ * modelo CANONICAL {pending, running, done}. Permite que la UI y los
+ * agregados (counts, kanban columns) trabajen contra un enum pequeño
+ * sin tener que conocer todas las variantes legacy.
+ *
+ *   certified | blocked | needs_context | pending → pending
+ *   coding | reviewing | running                  → running
+ *   done | failed                                 → done
+ *
+ * `failed` mapea a `done` porque conceptualmente es lifecycle terminal
+ * — el "falló" lo lleva el campo `result` ortogonal (step 1). Lo mismo
+ * para `certified`: no es un lifecycle, es "ready to run" que en el
+ * modelo canónico vive como `pending` + acceptance_tests no vacío.
+ */
+export function canonicalStatus(status) {
+  switch (status) {
+    case "running":
+    case "coding":
+    case "reviewing":
+      return "running";
+    case "done":
+    case "failed":
+      return "done";
+    default:
+      return "pending";
+  }
+}
+
+/**
+ * KJC-TSK-0394 step 5: result "efectivo" para la UI. Si el HU tiene
+ * `result` poblado (plans migrados), lo usa directamente. Si no
+ * (plans legacy pre-migración), lo deduce del status — equivalente a
+ * inferResultFromLegacyStatus pero llamable directamente sobre cada
+ * HU al renderizar.
+ *
+ * Permite a la UI mostrar badges ✓/✗ en plans antiguos sin esperar a
+ * que el usuario corra `kj plan migrate-result`.
+ */
+export function effectiveResult(hu) {
+  if (!hu) return null;
+  if (hu.result !== undefined && hu.result !== null) return hu.result;
+  return inferResultFromLegacyStatus(hu);
+}
+
+/**
+ * Map a legacy status to (newStatus, result) pair. Used by addHu() defaults
+ * and by the migration script in step 4. Idempotent: re-mapping a value that
+ * is already in the canonical {pending, running, done} set keeps it.
+ *
+ * @param {string|null|undefined} legacy
+ * @returns {{ status: string, result: string|null }}
+ */
+export function mapLegacyStatusToResult(legacy) {
+  switch (legacy) {
+    case "pending":
+    case "blocked":         // blocked es lifecycle no terminal → pending
+    case "needs_context":   // ídem
+    case undefined:
+    case null:
+      return { status: "pending", result: null };
+    case "coding":
+    case "reviewing":
+    case "running":
+      return { status: "running", result: null };
+    case "certified":
+      return { status: "done", result: "pass" };
+    case "failed":
+      // KJC-TSK-0403: HU fallida vuelve a Pending con result=fail
+      // (no a Done) para que el usuario pueda relanzarla con el
+      // contexto del fallo previo (KJC-TSK-0404).
+      return { status: "pending", result: "fail" };
+    case "done":
+      return { status: "done", result: null }; // sin result conocido (raro)
+    default:
+      return { status: "pending", result: null };
+  }
+}
+
 /**
  * Structured acceptance-test shape introduced in v2.7.5 (tests-first):
  *
@@ -74,6 +191,12 @@ export function createPlanV2(task, context = {}) {
   const planId = generatePlanId();
   return {
     planId,
+    // KJC-TSK humanización IDs: alias legible (ej "greta-app"). Se
+    // asigna en savePlan a partir de plan.name. El planId sigue
+    // siendo la ID canónica interna (timestamp+random), pero la CLI
+    // y el board prefieren el alias para mostrar y aceptan ambos
+    // como referencia (--plan greta-app o --plan plan-XXX-XX).
+    alias: null,
     version: 2,
     task,
     name: null, // set by caller via deriveProjectName or manually
@@ -144,6 +267,10 @@ export function validatePlan(plan) {
     huIds.add(hu.id);
     if (!hu.title) errors.push(`HU ${hu.id}: missing title`);
     if (!VALID_HU_STATUSES.has(hu.status)) errors.push(`HU ${hu.id}: invalid status ${hu.status}`);
+    // KJC-TSK-0394: result es opcional. Si está presente, debe ser pass/fail/partial.
+    if (hu.result !== undefined && hu.result !== null && !VALID_HU_RESULTS.has(hu.result)) {
+      errors.push(`HU ${hu.id}: invalid result ${hu.result} (expected pass|fail|partial|null)`);
+    }
     if (hu.task_type && !VALID_TASK_TYPES.has(hu.task_type)) errors.push(`HU ${hu.id}: invalid task_type ${hu.task_type}`);
     // acceptance_tests: may be absent (legacy) or an array of either
     // plain strings (legacy shell) or { type, content, file? } objects.