karajan-code 2.14.3 → 2.15.0

package/src/commands/standby.js

@@ -0,0 +1,114 @@
+// KJC-TSK-0414 PR2: comandos kj standby list / kj resume.
+//
+// `kj resume <sessionId>` valida cooldownUntil y, si llegó la hora, re-spawn
+// el comando original capturado en argv. Si cooldown todavía está en el
+// futuro, muestra countdown y aborta. `kj standby list` solo enumera.
+//
+// Estrategia de resume: cada sessionState persiste su argv original (los
+// argumentos con los que se lanzó el `kj` que hibernó). El resume re-spawn
+// EXACTAMENTE ese mismo comando con env preservado. El run reanuda como si
+// fuera un retry — el state interno (HU pendiente, snapshot_sha, etc.) está
+// en el JSON persistido en disco por TSK-0408 + TSK-0414 PR1.
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadStandby, listPendingStandby, markStandbyDone, acquireStandbyLock } from "../brain/standby-store.js";
+
+const REPO_KJ_CLI = (() => {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.join(here, "..", "cli.js");
+  } catch {
+    return null;
+  }
+})();
+
+function formatCountdown(ms) {
+  if (ms <= 0) return "ahora";
+  const s = Math.round(ms / 1000);
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  const sec = s % 60;
+  return `${String(h).padStart(2, "0")}:${String(m).padStart(2, "0")}:${String(sec).padStart(2, "0")}`;
+}
+
+export async function standbyListCommand({ json } = {}) {
+  const sessions = listPendingStandby();
+  if (json) {
+    console.log(JSON.stringify(sessions, null, 2));
+    return;
+  }
+  if (sessions.length === 0) {
+    console.log("No hay sesiones hibernadas.");
+    return;
+  }
+  console.log(`Sesiones hibernadas (${sessions.length}):`);
+  const now = Date.now();
+  for (const s of sessions) {
+    const ms = new Date(s.cooldownUntil).getTime() - now;
+    const status = ms <= 0 ? "✓ lista para resume" : `⏳ resume en ${formatCountdown(ms)}`;
+    console.log(`  ${s.sessionId}  · ${s.reason || "?"}  · ${status}`);
+    if (s.planId) console.log(`    plan: ${s.planId}${s.huId ? `, HU: ${s.huId}` : ""}`);
+  }
+}
+
+/**
+ * Re-spawn el comando original capturado en sessionState.argv.
+ * Si cooldownUntil > now y force=false → aborta con mensaje.
+ */
+export async function resumeCommand({ sessionId, force } = {}) {
+  if (!sessionId) {
+    console.error("kj resume requiere <sessionId>. Usa `kj standby list` para ver pendientes.");
+    process.exitCode = 1;
+    return;
+  }
+  const state = loadStandby(sessionId);
+  if (!state) {
+    console.error(`Sesión no encontrada: ${sessionId}`);
+    process.exitCode = 1;
+    return;
+  }
+  const cooldownMs = new Date(state.cooldownUntil).getTime() - Date.now();
+  if (cooldownMs > 0 && !force) {
+    console.log(`Sesión ${sessionId} todavía en cooldown ${formatCountdown(cooldownMs)} (hasta ${state.cooldownUntil}).`);
+    console.log("Espera o usa `kj resume <sessionId> --force` (no recomendado — la API seguramente seguirá rechazando).");
+    process.exitCode = 0;
+    return;
+  }
+
+  const lock = acquireStandbyLock(sessionId);
+  if (!lock.acquired) {
+    console.log(`Sesión ${sessionId} ya está siendo reanudada por otro proceso.`);
+    process.exitCode = 0;
+    return;
+  }
+
+  try {
+    if (!Array.isArray(state.argv) || state.argv.length === 0) {
+      console.error(`Sesión ${sessionId} sin argv — no se puede re-spawn. Borra manual y relanza.`);
+      process.exitCode = 1;
+      return;
+    }
+    if (!REPO_KJ_CLI) {
+      console.error("No se pudo localizar cli.js. ¿Karajan instalado correctamente?");
+      process.exitCode = 1;
+      return;
+    }
+    console.log(`Reanudando ${sessionId}: kj ${state.argv.join(" ")}`);
+    const child = spawn(process.execPath, [REPO_KJ_CLI, ...state.argv], {
+      cwd: state.cwd || process.cwd(),
+      env: { ...process.env, ...(state.env || {}), KJ_RESUME_FROM: sessionId },
+      stdio: "inherit",
+    });
+    await new Promise((resolve) => {
+      child.on("exit", (code) => {
+        if (code === 0) markStandbyDone(sessionId);
+        process.exitCode = code ?? 0;
+        resolve();
+      });
+    });
+  } finally {
+    lock.release?.();
+  }
+}

package/src/commands/triage.js

@@ -4,6 +4,7 @@ import { resolveRole } from "../config.js";
 import { createCliProgressReporter } from "../utils/cli-progress.js";
 import { buildTriagePrompt } from "../prompts/triage.js";
 import { parseMaybeJsonString } from "../review/parser.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
 
 function formatTriage(result) {
   const lines = [];
@@ -47,8 +48,11 @@ export async function triageCommand({ task, config, logger, json }) {
     const progress = createCliProgressReporter({ role: "triage" });
     let result;
     try {
-      result = await agent.runTask({ prompt, onOutput: progress.onOutput, role: "triage" });
-      progress.finish(result.ok ? "done" : "failed");
+      result = await withBrainRecovery({
+        agent, taskArgs: { prompt, onOutput: progress.onOutput, role: "triage" },
+        role: "triage", provider: triageRole.provider, logger,
+      });
+      progress.finish(result.ok ? "done" : (result.action || "failed"));
     } catch (err) { progress.finish("failed"); throw err; }
 
     if (!result.ok) {

package/src/config/schema.js

@@ -53,12 +53,27 @@ const Methodology = v.picklist(
   "development.methodology must be one of: tdd | standard"
 );
 
+/**
+ * KJC-TSK-0415: fallback chain. Cuando provider primario hits
+ * QUOTA_EXHAUSTED_* con cooldown > max_wait_hours, switch a fallback.
+ * Recursivo — el fallback puede tener su propio fallback.
+ */
+const RoleFallback = v.looseObject({
+  provider: v.string("fallback.provider required (claude|codex|gemini|opencode|aider)"),
+  model: v.optional(v.nullable(v.string())),
+  max_wait_hours: v.optional(v.pipe(v.number(), v.minValue(0)), 12),
+  // Recursivo. Schema permite cualquier shape compatible con RoleFallback.
+  fallback: v.optional(v.lazy(() => RoleFallback)),
+});
+
 /**
  * Role entry — provider + model, both nullable. Extra keys allowed.
+ * KJC-TSK-0415: campo fallback opcional para Plan B en quota exhausted.
  */
 const RoleEntry = v.looseObject({
   provider: v.optional(v.nullable(v.string())),
   model: v.optional(v.nullable(v.string())),
+  fallback: v.optional(RoleFallback),
 });
 
 const RolesMap = v.optional(v.looseObject({
@@ -176,6 +191,30 @@ const Skills = v.optional(v.looseObject({
   addyosmani: v.optional(SkillsAddyosmani),
 }));
 
+/**
+ * KJC-TSK-0407: routing automático de modelos por HU según complexity.
+ *   - by_provider: override de tiers per provider (claude/codex/gemini).
+ *     Cada provider mapea level → modelo. Sobreescribe defaults del router.
+ *   - fixed.coder / fixed.reviewer: si presentes, override TOTAL — todas
+ *     las HUs usan esos modelos independientemente del score. Útil para
+ *     forzar Sonnet en todo el proyecto, por ejemplo.
+ */
+const ModelRouting = v.optional(v.looseObject({
+  by_provider: v.optional(v.record(
+    v.string(),
+    v.looseObject({
+      trivial: v.optional(v.string()),
+      simple: v.optional(v.string()),
+      medium: v.optional(v.string()),
+      complex: v.optional(v.string()),
+    })
+  )),
+  fixed: v.optional(v.looseObject({
+    coder: v.optional(v.nullable(v.string())),
+    reviewer: v.optional(v.nullable(v.string())),
+  })),
+}));
+
 /**
  * Main config schema. `looseObject` lets every consumer that reads an
  * undeclared key keep working while the schema catches the bugs we care
@@ -207,6 +246,7 @@ export const ConfigSchema = v.looseObject({
   policies: v.optional(v.record(v.string(), v.unknown())),
   telemetry: v.optional(v.boolean()),
   skills: Skills,
+  model_routing: ModelRouting,
 });
 
 /**

package/src/git/hu-snapshot.js

@@ -0,0 +1,105 @@
+// KJC-TSK-0408: snapshots de ficheros por HU para soportar Undo.
+//
+// Antes de ejecutar una HU, guardamos un ref git apuntando al HEAD
+// actual (`refs/kj-snapshots/<huId>`). Si el usuario hace Undo después,
+// hacemos `git reset --hard <ref>` para volver al estado pre-run.
+//
+// Por qué refs en lugar de stash/tarball:
+//   - Refs son objetos git nativos. No mueven blobs (todos compartidos
+//     con HEAD), así que crear el snapshot es O(1).
+//   - El snapshot persiste a través de checkouts y rebases.
+//   - Si el ref ya apunta al SHA correcto, restore es no-op.
+//
+// El runner es inyectable para que los tests no necesiten un repo git real.
+
+import { runCommand } from "../utils/process.js";
+
+const REF_PREFIX = "refs/kj-snapshots/";
+
+/**
+ * Sanitiza un huId para uso como nombre de ref. Git rechaza:
+ *   - `..`, `:`, `~`, `^`, `?`, `*`, `[`, `\`, espacios, control chars
+ *   - segmentos que empiecen por `.` o terminen en `.lock`
+ * Reemplazamos cualquier no [a-zA-Z0-9_-] por `_`.
+ */
+export function snapshotRefForHu(huId) {
+  if (!huId) throw new Error("huId requerido");
+  const safe = String(huId).replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 80);
+  return REF_PREFIX + safe;
+}
+
+async function defaultRunner(args, opts = {}) {
+  return runCommand("git", args, opts);
+}
+
+/**
+ * Crea (o actualiza) el ref del snapshot apuntando al HEAD actual.
+ *
+ * @param {object} args
+ * @param {string} args.projectDir
+ * @param {string} args.huId
+ * @param {Function} [args.runner] - sustituye git CLI en tests
+ * @returns {Promise<{ ok: boolean, ref?: string, sha?: string, error?: string }>}
+ */
+export async function createHuSnapshot({ projectDir, huId, runner }) {
+  const run = runner || defaultRunner;
+  const ref = snapshotRefForHu(huId);
+  const head = await run(["rev-parse", "HEAD"], { cwd: projectDir });
+  if (head.exitCode !== 0) {
+    return { ok: false, error: `rev-parse HEAD failed: ${(head.stderr || "").trim()}` };
+  }
+  const sha = (head.stdout || "").trim();
+  if (!sha) return { ok: false, error: "HEAD vacío" };
+  const update = await run(["update-ref", ref, sha], { cwd: projectDir });
+  if (update.exitCode !== 0) {
+    return { ok: false, error: `update-ref falló: ${(update.stderr || "").trim()}` };
+  }
+  return { ok: true, ref, sha };
+}
+
+/**
+ * @param {object} args
+ * @param {string} args.projectDir
+ * @param {string} args.huId
+ * @param {Function} [args.runner]
+ * @returns {Promise<{ ok: boolean, sha?: string }>}
+ */
+export async function hasHuSnapshot({ projectDir, huId, runner }) {
+  const run = runner || defaultRunner;
+  const ref = snapshotRefForHu(huId);
+  const r = await run(["rev-parse", "--verify", "--quiet", ref], { cwd: projectDir });
+  if (r.exitCode !== 0) return { ok: false };
+  return { ok: true, sha: (r.stdout || "").trim() };
+}
+
+/**
+ * Restaura el workspace al snapshot. DESTRUCTIVO: hace `git reset --hard`,
+ * lo que descarta cambios no committeados. Caller debe avisar al usuario.
+ *
+ * @returns {Promise<{ ok: boolean, sha?: string, error?: string }>}
+ */
+export async function restoreHuSnapshot({ projectDir, huId, runner }) {
+  const run = runner || defaultRunner;
+  const ref = snapshotRefForHu(huId);
+  const has = await hasHuSnapshot({ projectDir, huId, runner: run });
+  if (!has.ok) return { ok: false, error: `snapshot no encontrado para HU ${huId}` };
+  const r = await run(["reset", "--hard", ref], { cwd: projectDir });
+  if (r.exitCode !== 0) {
+    return { ok: false, error: `reset --hard falló: ${(r.stderr || "").trim()}` };
+  }
+  return { ok: true, sha: has.sha };
+}
+
+/**
+ * Borra el ref del snapshot. Idempotente: si no existe, devuelve ok:true.
+ */
+export async function removeHuSnapshot({ projectDir, huId, runner }) {
+  const run = runner || defaultRunner;
+  const ref = snapshotRefForHu(huId);
+  const r = await run(["update-ref", "-d", ref], { cwd: projectDir });
+  // git update-ref -d devuelve 0 incluso si el ref no existía.
+  if (r.exitCode !== 0) {
+    return { ok: false, error: `update-ref -d falló: ${(r.stderr || "").trim()}` };
+  }
+  return { ok: true };
+}

package/src/guards/policy-resolver.js

@@ -6,7 +6,14 @@
  * @typedef {import("../types/config.js").KarajanConfig} KarajanConfig
  */
 
-export const VALID_TASK_TYPES = new Set(["sw", "infra", "doc", "add-tests", "refactor", "audit", "analysis", "no-code"]);
+// KJC-TSK-0400: spike y research añadidos como tipos no-code. Comparten
+// las defaults restrictivas (tdd/sonar/testsRequired off) porque NO
+// producen código que medir: un SPIKE es un .md de decisión, un research
+// es una nota de investigación. Forzar Sonar les hace fallar siempre.
+export const VALID_TASK_TYPES = new Set([
+  "sw", "infra", "doc", "add-tests", "refactor",
+  "audit", "analysis", "no-code", "spike", "research",
+]);
 
 export const DEFAULT_POLICIES = {
   sw:        { tdd: true,  sonar: true,  reviewer: true, testsRequired: true  },
@@ -17,8 +24,38 @@ export const DEFAULT_POLICIES = {
   audit:     { tdd: false, sonar: false, reviewer: false, testsRequired: false, coderRequired: false },
   analysis:  { tdd: false, sonar: false, reviewer: false, testsRequired: false, coderRequired: false },
   "no-code": { tdd: false, sonar: false, reviewer: true, testsRequired: false, coderRequired: true },
+  spike:     { tdd: false, sonar: false, reviewer: true, testsRequired: false, coderRequired: true },
+  research:  { tdd: false, sonar: false, reviewer: true, testsRequired: false, coderRequired: true },
 };
 
+// KJC-TSK-0400: si el title arranca con [SPIKE] / [DOC] / [RESEARCH] /
+// [NOCODE], inferimos el task_type del prefijo. Pensado para casos donde
+// el planner emite task_type='sw' por defecto pero el title declara
+// claramente que la HU no produce código. Devuelve null si no hay match.
+const TITLE_PREFIX_TO_TYPE = {
+  SPIKE: "spike",
+  RESEARCH: "research",
+  DOC: "doc",
+  NOCODE: "no-code",
+  "NO-CODE": "no-code",
+};
+
+export function inferTaskTypeFromTitle(title) {
+  if (typeof title !== "string") return null;
+  const m = title.match(/^\s*\[([A-Z][A-Z-]+)\]/);
+  if (!m) return null;
+  return TITLE_PREFIX_TO_TYPE[m[1].toUpperCase()] || null;
+}
+
+// KJC-TSK-0400: dado un HU del plan, devuelve el task_type efectivo:
+// explícito en story.task_type si es válido, si no inferido del title.
+// Fallback 'sw' (conservador, mantiene gates activos cuando hay duda).
+export function effectiveTaskType(story) {
+  if (!story || typeof story !== "object") return "sw";
+  if (VALID_TASK_TYPES.has(story.task_type)) return story.task_type;
+  return inferTaskTypeFromTitle(story.title) || "sw";
+}
+
 const FALLBACK_TYPE = "sw";
 
 /**

package/src/hu/lazy-planner.js

@@ -7,6 +7,7 @@
  */
 import { createAgent } from "../agents/index.js";
 import { extractFirstJson } from "../utils/json-extract.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -72,7 +73,11 @@ export async function refineHuWithContext(hu, completedHus, config, logger) {
   const agent = createAgent(provider, config, logger);
   let result;
   try {
-    result = await agent.runTask({ prompt, role: "hu-reviewer" });
+    // KJC-TSK-0413 step C
+    result = await withBrainRecovery({
+      agent, taskArgs: { prompt, role: "hu-reviewer" },
+      role: "lazy-planner", provider, logger,
+    });
   } catch (err) {
     logger.warn(`Lazy planner: refinement failed for HU ${hu.id}: ${err.message}`);
     return hu;

package/src/hu/model-router.js

@@ -0,0 +1,108 @@
+// KJC-TSK-0405: dado un HU con complexity score, recomienda coder_model y
+// reviewer_model. El reviewer por defecto usa el provider alternativo al
+// coder (cross-provider review) para que dos cabezas distintas miren el
+// código y se detecten más patrones.
+
+const LEVELS = ["trivial", "simple", "medium", "complex"];
+
+// Mapping complexity score numérico → nivel categórico.
+// 1 → trivial, 2 → simple, 3/4 → medium, 5+ → complex.
+const SCORE_TO_LEVEL = {
+  1: "trivial",
+  2: "simple",
+  3: "medium",
+  4: "medium",
+  5: "complex",
+};
+
+// Defaults por provider — alineados con utils/model-selector.js DEFAULTS.
+// opencode: usa "coder" como alias razonable; el usuario suele definir
+// gemma-local/coder, ollama/coder o similar en opencode.json. Override
+// per-tier vía config.model_routing.by_provider.opencode si quieres
+// rutear distinto por complexity (ej. fast para trivial, coder para
+// complex). aider: null porque aider envuelve a otros providers — no
+// tiene "modelos propios". Si el usuario lo elige, debe configurarlo
+// explícito en config.model_routing.by_provider.aider o vía override
+// del modal por HU.
+const DEFAULT_TIERS = {
+  claude: { trivial: "haiku", simple: "haiku", medium: "sonnet", complex: "opus" },
+  codex: { trivial: "o4-mini", simple: "o4-mini", medium: "o4-mini", complex: "o3" },
+  gemini: { trivial: "gemini-2.0-flash", simple: "gemini-2.0-flash", medium: "gemini-2.5-pro", complex: "gemini-2.5-pro" },
+  opencode: { trivial: "coder", simple: "coder", medium: "coder", complex: "coder" },
+  aider: { trivial: null, simple: null, medium: null, complex: null },
+};
+
+// Cross-provider reviewer default: para cada coder provider, qué provider
+// usa el reviewer por defecto. Dos cabezas distintas miran el código.
+// opencode → claude: pattern "local barato escribe + cloud revisa".
+// aider → claude: aider suele correr en un model pequeño, claude verifica.
+const CROSS_PROVIDER_REVIEWER = {
+  claude: "codex",
+  codex: "claude",
+  gemini: "claude",
+  opencode: "claude",
+  aider: "claude",
+};
+
+// KJC-TSK-0405 step 2: heurística para inferir complexity desde
+// task_type cuando el planner no emite un score explícito. Permite
+// que el model-router asigne modelos razonables sin un triage explícito.
+const TASK_TYPE_COMPLEXITY = {
+  sw: "medium",
+  refactor: "medium",
+  "add-tests": "simple",
+  infra: "trivial",
+  doc: "trivial",
+  spike: "complex",
+  research: "complex",
+  audit: "complex",
+  analysis: "medium",
+  "no-code": "trivial",
+};
+
+export function complexityFromTaskType(taskType) {
+  return TASK_TYPE_COMPLEXITY[taskType] || "medium";
+}
+
+export function complexityToLevel(complexity) {
+  if (typeof complexity === "string" && LEVELS.includes(complexity)) return complexity;
+  if (typeof complexity === "number" && SCORE_TO_LEVEL[complexity]) return SCORE_TO_LEVEL[complexity];
+  return "medium";
+}
+
+/**
+ * @param {object} args
+ * @param {string|number} args.complexity - "trivial" | "simple" | "medium" | "complex" | score 1-5
+ * @param {string} args.coderProvider - "claude" | "codex" | "gemini"
+ * @param {object} args.config - karajan config (lee model_routing si existe)
+ * @returns {{ coder_model: string|null, coder_provider: string, reviewer_model: string|null, reviewer_provider: string }}
+ */
+export function recommendModelsForHu({ complexity, coderProvider, config = {} }) {
+  const level = complexityToLevel(complexity);
+  const routing = config.model_routing || {};
+  const fixed = routing.fixed || {};
+
+  // Merge tiers: defaults + user overrides per provider.
+  const tiers = { ...DEFAULT_TIERS };
+  if (routing.by_provider) {
+    for (const [prov, levels] of Object.entries(routing.by_provider)) {
+      tiers[prov] = { ...(tiers[prov] || {}), ...levels };
+    }
+  }
+
+  const coderTier = tiers[coderProvider];
+  const coderAuto = coderTier ? (coderTier[level] || null) : null;
+  const coder_model = fixed.coder || coderAuto;
+
+  const reviewer_provider = CROSS_PROVIDER_REVIEWER[coderProvider] || "claude";
+  const reviewerTier = tiers[reviewer_provider];
+  const reviewerAuto = reviewerTier ? (reviewerTier[level] || null) : null;
+  const reviewer_model = fixed.reviewer || reviewerAuto;
+
+  return {
+    coder_model,
+    coder_provider: coderProvider,
+    reviewer_model,
+    reviewer_provider,
+  };
+}

package/src/hu/splitting-generator.js

@@ -7,6 +7,7 @@
 import { createAgent } from "../agents/index.js";
 import { extractFirstJson } from "../utils/json-extract.js";
 import { HEURISTIC_DESCRIPTIONS } from "./splitting-detector.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -97,7 +98,11 @@ export async function generateSplitProposal(hu, heuristic, config, logger) {
 
   let result;
   try {
-    result = await agent.runTask({ prompt, role: "hu-splitter" });
+    // KJC-TSK-0413 step C
+    result = await withBrainRecovery({
+      agent, taskArgs: { prompt, role: "hu-splitter" },
+      role: "hu-splitter", provider, logger,
+    });
   } catch (err) {
     logger.warn(`HU split generation threw: ${err.message}`);
     return null;

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.