karajan-code 2.14.3 → 2.15.0

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

@@ -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")
+    .replace(/[̀-ͯ]/g, "")        // strip diacritics
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")            // non-alphanum → guion
+    .replace(/^-+|-+$/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.

package/src/plan/plan-store.js

@@ -7,7 +7,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
-import { generatePlanId } from "./plan-id.js";
+import { generatePlanId, normaliseAlias } from "./plan-id.js";
 import { isPlanV2, migratePlanV1toV2 } from "./plan-schema.js";
 
 // Per-process tmp dir for VITEST runs that forget to set KJ_HOME. We
@@ -77,6 +77,12 @@ export async function savePlan(projectDir, planResult) {
     // 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;
+    // 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.
+    if (!planResult.alias && planResult.name) {
+      planResult.alias = await resolveUniqueAlias(dir, planResult.planId, normaliseAlias(planResult.name));
+    }
     await fs.writeFile(filePath, JSON.stringify(planResult, null, 2), "utf8");
     return planResult.planId;
   }
@@ -99,19 +105,67 @@ export async function savePlan(projectDir, planResult) {
 }
 
 /**
- * Load a plan by ID. Auto-migrates v1 to v2 on read (lazy).
- * @returns {Promise<object|null>} v2 plan or null
+ * Resuelve un alias único en `dir`. Si `base` ya está en uso por otro
+ * plan, intenta `base-2`, `base-3`… hasta encontrar libre.
+ * @param {string} dir
+ * @param {string} ownPlanId - planId del plan que se está guardando (su propio archivo se ignora en el lookup).
+ * @param {string|null} base
+ * @returns {Promise<string|null>}
  */
-export async function loadPlan(projectDir, planId) {
-  const filePath = path.join(plansDir(projectDir), `${planId}.json`);
+async function resolveUniqueAlias(dir, ownPlanId, base) {
+  if (!base) return null;
+  let files;
+  try { files = await fs.readdir(dir); } catch { return base; }
+  const taken = new Set();
+  for (const f of files) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      const record = JSON.parse(await fs.readFile(path.join(dir, f), "utf8"));
+      if (record.planId === ownPlanId) continue;
+      if (record.alias) taken.add(record.alias);
+    } catch { /* skip corrupt */ }
+  }
+  if (!taken.has(base)) return base;
+  for (let i = 2; i < 1000; i += 1) {
+    const candidate = `${base}-${i}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+  return `${base}-${ownPlanId.slice(-4)}`;  // fallback improbable
+}
+
+/**
+ * Load a plan by ID or alias. Auto-migrates v1 to v2 on read (lazy).
+ * Acepta tanto el planId canónico (plan-XXX-XX) como el alias humano
+ * (greta-app). Primero busca por filename exacto (planId.json), luego
+ * escanea el dir y matchea por alias.
+ *
+ * @returns {Promise<object|null>} v2 plan o null
+ */
+export async function loadPlan(projectDir, ref) {
+  if (!ref) return null;
+  const dir = plansDir(projectDir);
+  // 1. Match exacto por planId.json (camino caliente).
+  const direct = path.join(dir, `${ref}.json`);
   try {
-    const data = await fs.readFile(filePath, "utf8");
+    const data = await fs.readFile(direct, "utf8");
     const plan = JSON.parse(data);
     if (!isPlanV2(plan)) return migratePlanV1toV2(plan);
     return plan;
-  } catch {
-    return null;
+  } catch { /* fall through to alias scan */ }
+  // 2. Escaneo del dir por alias. Coste O(N) pero N suele ser <10.
+  let files;
+  try { files = await fs.readdir(dir); } catch { return null; }
+  for (const f of files) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      const record = JSON.parse(await fs.readFile(path.join(dir, f), "utf8"));
+      if (record.alias === ref || record.planId === ref) {
+        if (!isPlanV2(record)) return migratePlanV1toV2(record);
+        return record;
+      }
+    } catch { /* skip corrupt */ }
   }
+  return null;
 }
 
 /**
@@ -148,6 +202,7 @@ export async function listPlans(projectDir) {
       const record = JSON.parse(data);
       plans.push({
         planId: record.planId,
+        alias: record.alias || null,
         task: record.task,
         name: record.name || null,
         status: record.status || "draft",

package/src/plan/plan-structural-pass.js

@@ -0,0 +1,122 @@
+// KJC-TSK-0399: deterministic post-review pass — cycles, orphan refs,
+// missing short_id. No LLM. Fix shape: { kind, huId?, ...details };
+// stored in plan.review.structural_fixes.
+
+export function runStructuralPass(plan) {
+  const fixes = [];
+  if (!plan || !Array.isArray(plan.hus) || plan.hus.length === 0) {
+    return { fixes, modified: false };
+  }
+  fixes.push(...removeOrphanRefs(plan));
+  fixes.push(...breakCycles(plan));
+  fixes.push(...assignMissingShortIds(plan));
+  const modified = fixes.length > 0;
+  if (modified) plan.updatedAt = new Date().toISOString();
+  return { fixes, modified };
+}
+
+export function removeOrphanRefs(plan) {
+  const fixes = [];
+  const known = new Set(plan.hus.map((h) => h.id));
+  for (const hu of plan.hus) {
+    const removed = [];
+    if (Array.isArray(hu.blocked_by) && hu.blocked_by.length > 0) {
+      hu.blocked_by = hu.blocked_by.filter((d) => {
+        if (known.has(d)) return true;
+        removed.push(d); return false;
+      });
+    }
+    if (removed.length > 0) fixes.push({ kind: "orphan_ref_removed", huId: hu.id, removed });
+  }
+  return fixes;
+}
+
+export function breakCycles(plan) {
+  const fixes = [];
+  let cycles = findCycles(plan.hus);
+  let budget = plan.hus.length;
+  while (cycles.length > 0 && budget-- > 0) {
+    const cycle = cycles[0];
+    const dropped = breakCycle(plan, cycle);
+    if (!dropped) break;
+    fixes.push({ kind: "cycle_break", cycle: [...cycle], droppedEdge: dropped });
+    cycles = findCycles(plan.hus);
+  }
+  return fixes;
+}
+
+export function findCycles(hus) {
+  const graph = new Map();
+  for (const hu of hus) graph.set(hu.id, Array.isArray(hu.blocked_by) ? hu.blocked_by : []);
+  const cycles = [];
+  const seen = new Set();
+  const onStack = new Set();
+  const stack = [];
+  function dfs(node) {
+    onStack.add(node); stack.push(node); seen.add(node);
+    for (const dep of graph.get(node) || []) {
+      if (!graph.has(dep)) continue;
+      if (onStack.has(dep)) {
+        const idx = stack.indexOf(dep);
+        if (idx >= 0) {
+          const cycle = stack.slice(idx);
+          if (!cycles.some((c) => sameCycle(c, cycle))) cycles.push(cycle);
+        }
+      } else if (!seen.has(dep)) dfs(dep);
+    }
+    stack.pop(); onStack.delete(node);
+  }
+  for (const id of graph.keys()) if (!seen.has(id)) dfs(id);
+  return cycles;
+}
+
+function sameCycle(a, b) {
+  if (a.length !== b.length) return false;
+  return [...a].sort().join("|") === [...b].sort().join("|");
+}
+
+// Heurística: dropea arista cuyo origen tiene menos incoming. Tiebreak edge.to.
+export function breakCycle(plan, cycle) {
+  const incoming = new Map();
+  for (const hu of plan.hus) {
+    for (const dep of hu.blocked_by || []) incoming.set(dep, (incoming.get(dep) || 0) + 1);
+  }
+  const edges = [];
+  for (let i = 0; i < cycle.length; i++) {
+    const from = cycle[i];
+    const to = cycle[(i + 1) % cycle.length];
+    const hu = plan.hus.find((h) => h.id === from);
+    if (hu && Array.isArray(hu.blocked_by) && hu.blocked_by.includes(to)) edges.push({ from, to });
+  }
+  if (edges.length === 0) return null;
+  edges.sort((a, b) => {
+    const d = (incoming.get(a.from) || 0) - (incoming.get(b.from) || 0);
+    return d !== 0 ? d : a.to.localeCompare(b.to);
+  });
+  const drop = edges[0];
+  const hu = plan.hus.find((h) => h.id === drop.from);
+  hu.blocked_by = hu.blocked_by.filter((d) => d !== drop.to);
+  return drop;
+}
+
+export function assignMissingShortIds(plan) {
+  const fixes = [];
+  const used = new Set();
+  let maxAuto = 0;
+  for (const hu of plan.hus) {
+    if (!hu.short_id) continue;
+    used.add(hu.short_id);
+    const m = String(hu.short_id).match(/^AUTOFIX-(\d+)$/);
+    if (m) maxAuto = Math.max(maxAuto, Number(m[1]));
+  }
+  for (const hu of plan.hus) {
+    if (hu.short_id) continue;
+    maxAuto += 1;
+    const candidate = `AUTOFIX-${String(maxAuto).padStart(3, "0")}`;
+    if (used.has(candidate)) continue;
+    hu.short_id = candidate;
+    used.add(candidate);
+    fixes.push({ kind: "short_id_assigned", huId: hu.id, assigned: candidate });
+  }
+  return fixes;
+}