karajan-code 2.14.2 → 2.15.0

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.

package/src/orchestrator/preflight-checks.js

@@ -29,6 +29,7 @@ import { getPortChecks } from "../checks/ports.js";
 import { getTokenChecks } from "../checks/tokens.js";
 import { getMcpHealthChecks } from "../checks/mcp-health.js";
 import { getSkillsChecks } from "../checks/skills.js";
+import { getProjectChecks } from "../checks/project-checks.js";
 import { resolveTestHarness } from "../config/test-harness.js";
 
 function parseJsonSafe(text) {
@@ -369,6 +370,10 @@ async function runExtendedPreflight({ config, result, emitter, eventBase, logger
     ...getTokenChecks(config),
     ...getMcpHealthChecks(),
     ...getSkillsChecks(),
+    // KJC-TSK-0393: project-aware checks (signal detection, write perms,
+    // tools per signal, .env consistency, gh remote access). Saltables con
+    // flag --no-project-checks en kj run.
+    ...(config?.flags?.noProjectChecks ? [] : getProjectChecks({ projectDir: config?.projectDir || process.cwd() })),
   ];
   let report;
   try {

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;