karajan-code 2.14.2 → 2.15.0

package/src/checks/project-checks.js

@@ -0,0 +1,245 @@
+/**
+ * Project-aware preflight checks (KJC-TSK-0393).
+ *
+ * `kj doctor` (global) y el preflight estándar verifican el ENTORNO de Karajan
+ * (CLIs instaladas, node, dirs ~/.karajan/, sonar). Pero **nada** validaba que
+ * el PROYECTO actual tuviera lo que necesita: tools detectables por signals
+ * (docker si hay Dockerfile, firebase si hay firebase.json, etc.), permisos
+ * write sobre projectDir, configuración inicializada, .env consistente con
+ * .env.example.
+ *
+ * Este módulo registra checks dinámicos basados en signals del proyecto. Se
+ * integra en preflight-checks.js como "fase project-aware" tras la fase global.
+ * También expone `kj doctor --project` para ejecutar solo esta fase manualmente.
+ *
+ * Filosofía: si un check falla, el mensaje incluye el comando EJECUTABLE para
+ * resolverlo (no "Run X or Y"), y siempre que sea posible se marca como
+ * `degradable` (KJC-BUG-0049) para no abortar runs por features opcionales.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { runCommand } from "../utils/process.js";
+import { checkBinary } from "../utils/agent-detect.js";
+import { getInstallCommand } from "../utils/os-detect.js";
+import { STRATEGY } from "./types.js";
+
+/**
+ * Detect signals del proyecto. Devuelve un set de tags con qué hay en el
+ * projectDir. Pure-function, solo I/O de filesystem síncrono (rápido).
+ *
+ * @param {string} projectDir
+ * @returns {Set<string>}
+ */
+export function detectProjectSignals(projectDir) {
+  const signals = new Set();
+  if (!projectDir || !fs.existsSync(projectDir)) return signals;
+  const has = (rel) => fs.existsSync(path.join(projectDir, rel));
+  if (has("package.json")) signals.add("node");
+  if (has("Dockerfile") || has("docker-compose.yml") || has("compose.yml")) signals.add("docker");
+  if (has("firebase.json") || has(".firebaserc")) signals.add("firebase");
+  if (has("pyproject.toml") || has("requirements.txt") || has("setup.py")) signals.add("python");
+  if (has("Cargo.toml")) signals.add("rust");
+  if (has("go.mod")) signals.add("go");
+  if (has(".env.example") || has(".env.sample") || has(".env.template")) signals.add("env-example");
+  if (has(".env")) signals.add("env");
+  // Terraform / OpenTofu
+  try {
+    const entries = fs.readdirSync(projectDir);
+    if (entries.some((e) => e.endsWith(".tf") || e.endsWith(".tofu"))) signals.add("terraform");
+  } catch { /* unreadable dir */ }
+  return signals;
+}
+
+/**
+ * Check de tool específico del signal. Si el signal está presente pero la tool
+ * no, emite WARN con install command ejecutable.
+ */
+function createToolCheck({ signal, tool, label, signals }) {
+  return {
+    name: `project:tool:${tool}`,
+    label,
+    strategy: STRATEGY.MANUAL,
+    applies: () => signals.has(signal),
+    async detect() {
+      const res = await checkBinary(tool);
+      if (res.ok) {
+        return { ok: true, severity: "info", detail: `${tool} ${res.version} — required by ${signal} signal` };
+      }
+      const installCmd = getInstallCommand(tool) || `<install ${tool} for your OS>`;
+      return {
+        ok: false,
+        severity: "warn",
+        detail: `${tool} no instalada pero el proyecto tiene signal '${signal}' (puede no necesitarla para esta HU, pero la mayoría sí)`,
+        fix: installCmd,
+      };
+    },
+  };
+}
+
+/**
+ * Permisos write check. Critical: si projectDir, .kj/ o .karajan/ no son
+ * escribibles, el pipeline va a fallar muy tarde con errores oscuros.
+ */
+function createWritePermsCheck({ projectDir }) {
+  return {
+    name: "project:write-perms",
+    label: "Write permissions (projectDir + .kj/ + .karajan/)",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const targets = [
+        projectDir,
+        path.join(projectDir, ".kj"),
+        path.join(projectDir, ".karajan"),
+      ];
+      const failed = [];
+      for (const target of targets) {
+        try {
+          if (!fs.existsSync(target)) continue;
+          fs.accessSync(target, fs.constants.W_OK);
+        } catch {
+          failed.push(target);
+        }
+      }
+      if (failed.length === 0) {
+        return { ok: true, severity: "info", detail: "Karajan puede escribir en projectDir, .kj/ y .karajan/" };
+      }
+      return {
+        ok: false,
+        severity: "fail",
+        detail: `Sin permisos de escritura en: ${failed.join(", ")}`,
+        fix: `chmod -R u+w ${failed.join(" ")}`,
+      };
+    },
+  };
+}
+
+/**
+ * .env consistency check: si existe .env.example pero NO .env, o si las vars
+ * que .env.example declara faltan en .env, emite WARN con la lista.
+ */
+function createEnvConsistencyCheck({ projectDir, signals }) {
+  return {
+    name: "project:env-consistency",
+    label: ".env consistency (vs .env.example)",
+    strategy: STRATEGY.MANUAL,
+    applies: () => signals.has("env-example"),
+    async detect() {
+      const exampleFile = ["env.example", ".env.sample", ".env.template"]
+        .map((n) => path.join(projectDir, n.startsWith(".") ? n : `.${n}`))
+        .find((p) => fs.existsSync(p));
+      const realFile = path.join(projectDir, ".env");
+      const declaredVars = parseEnvKeys(exampleFile);
+      if (declaredVars.length === 0) {
+        return { ok: true, severity: "info", detail: ".env.example sin variables declaradas" };
+      }
+      const realVars = fs.existsSync(realFile) ? new Set(parseEnvKeys(realFile)) : new Set();
+      const missing = declaredVars.filter((k) => !realVars.has(k));
+      if (missing.length === 0) {
+        return { ok: true, severity: "info", detail: `.env tiene las ${declaredVars.length} variables declaradas en .env.example` };
+      }
+      return {
+        ok: false,
+        severity: "warn",
+        detail: `.env no declara ${missing.length} variable(s) que sí están en .env.example: ${missing.slice(0, 5).join(", ")}${missing.length > 5 ? "..." : ""}`,
+        fix: `cp ${path.basename(exampleFile)} .env && edit it`,
+      };
+    },
+  };
+}
+
+function parseEnvKeys(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, "utf8");
+    return content
+      .split("\n")
+      .map((l) => l.trim())
+      .filter((l) => l && !l.startsWith("#") && l.includes("="))
+      .map((l) => l.split("=")[0].trim())
+      .filter(Boolean);
+  } catch { return []; }
+}
+
+/**
+ * gh remote-specific check: cuando auto_pr está activo, no basta con que `gh`
+ * esté autenticado en general (eso lo cubre token:gh ya). Hay que verificar
+ * que el usuario tiene push access AL REMOTE de este proyecto.
+ */
+function createGhRemoteCheck({ projectDir }) {
+  return {
+    name: "project:gh-remote-access",
+    label: "GitHub push access (current remote)",
+    strategy: STRATEGY.MANUAL,
+    applies: (config) => config?.git?.auto_pr === true,
+    degradable: {
+      disables: ["git.auto_pr"],
+      warn: "auto_pr DESACTIVADO — no se pueden crear PRs al remote actual. Verifica permisos con `gh repo view`",
+    },
+    async detect() {
+      // Verifica que el remote responde a ls-remote (read access mínimo,
+      // proxy para push access — el push real solo se valida al pushear).
+      try {
+        const res = await runCommand("git", ["-C", projectDir, "ls-remote", "--heads", "origin"], { reject: false });
+        if (res.exitCode === 0) {
+          return { ok: true, severity: "info", detail: "Remote origin accesible vía git ls-remote" };
+        }
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `git ls-remote origin falló (exit ${res.exitCode}): ${(res.stderr || "").slice(0, 120)}`,
+          fix: "Verifica el remote con `git remote -v` y la auth con `gh repo view`",
+        };
+      } catch (err) {
+        return { ok: false, severity: "warn", detail: `git ls-remote error: ${err.message}`, fix: "Verifica git remote y auth gh" };
+      }
+    },
+  };
+}
+
+/**
+ * `kj init` ran check: si no existe ~/.karajan/kj.config.yml NI .karajan/coder-rules.md,
+ * el usuario probablemente no ejecutó `kj init`. WARN con instrucción ejecutable.
+ */
+function createKjInitCheck({ projectDir }) {
+  return {
+    name: "project:kj-init-ran",
+    label: "Karajan project initialized",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const projectKjFile = path.join(projectDir, ".karajan", "coder-rules.md");
+      const globalKjFile = path.join(process.env.HOME || "", ".karajan", "kj.config.yml");
+      if (fs.existsSync(projectKjFile) || fs.existsSync(globalKjFile)) {
+        return { ok: true, severity: "info", detail: "Karajan config presente (global o local del proyecto)" };
+      }
+      return {
+        ok: false,
+        severity: "warn",
+        detail: "No se encontró kj.config.yml global ni .karajan/coder-rules.md local — probablemente falta `kj init`",
+        fix: "kj init",
+      };
+    },
+  };
+}
+
+/**
+ * Construye el set completo de project-aware checks basado en projectDir.
+ *
+ * @param {{ projectDir: string }} ctx
+ * @returns {Check[]}
+ */
+export function getProjectChecks({ projectDir }) {
+  if (!projectDir) return [];
+  const signals = detectProjectSignals(projectDir);
+  return [
+    createKjInitCheck({ projectDir }),
+    createWritePermsCheck({ projectDir }),
+    createToolCheck({ signal: "docker", tool: "docker", label: "Docker (project signal)", signals }),
+    createToolCheck({ signal: "firebase", tool: "firebase", label: "firebase-cli (project signal)", signals }),
+    createToolCheck({ signal: "python", tool: "python3", label: "Python 3 (project signal)", signals }),
+    createToolCheck({ signal: "rust", tool: "cargo", label: "Cargo / Rust (project signal)", signals }),
+    createToolCheck({ signal: "go", tool: "go", label: "Go (project signal)", signals }),
+    createToolCheck({ signal: "terraform", tool: "terraform", label: "Terraform (project signal)", signals }),
+    createEnvConsistencyCheck({ projectDir, signals }),
+    createGhRemoteCheck({ projectDir }),
+  ];
+}

package/src/checks/runner.js

@@ -98,6 +98,17 @@ export async function runChecks(checks, ctx, options = {}) {
         entry.runMs = Date.now() - start;
         entry.status = resolveStatusFromDetect(entry.check, result);
         entry.detail = result.detail;
+        // KJC-BUG-0049: si el check es degradable y falló (status FAIL/WARN tras
+        // resolveStatusFromDetect), aplicar disables al overrides y degradar a WARN.
+        // Así el preflight no aborta — la feature opcional se desactiva con aviso.
+        if (!result.ok && entry.check.degradable && (entry.status === STATUS.FAIL || entry.status === STATUS.WARN)) {
+          for (const dotPath of entry.check.degradable.disables || []) {
+            setDotPath(overrides, dotPath, false);
+          }
+          entry.status = STATUS.WARN;
+          entry.detail = `${result.detail} → ${entry.check.degradable.warn}`;
+          entry.degraded = true;
+        }
       } catch (err) {
         entry.runMs = Date.now() - start;
         if (err instanceof TimeoutError) {
@@ -227,6 +238,24 @@ function summarize(reports) {
   return summary;
 }
 
+/**
+ * Set a dot-path on a target object, creating intermediate objects as needed.
+ * Used by the `degradable` check support (KJC-BUG-0049) to disable feature
+ * flags like `git.auto_pr` when their preflight check fails.
+ *
+ * @example setDotPath({}, "git.auto_pr", false) // → { git: { auto_pr: false } }
+ */
+function setDotPath(target, dotPath, value) {
+  const parts = String(dotPath).split(".");
+  let cursor = target;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const k = parts[i];
+    if (cursor[k] == null || typeof cursor[k] !== "object") cursor[k] = {};
+    cursor = cursor[k];
+  }
+  cursor[parts.at(-1)] = value;
+}
+
 /**
  * Deep-merge (shallow for now, one level deep) remediation changes into overrides.
  * Remediation outputs like { hu_board: { port: 4007 } } should not overwrite a

package/src/checks/tokens.js

@@ -21,6 +21,7 @@
 
 import { checkBinary } from "../utils/agent-detect.js";
 import { getRequiredProviderEnvs, normalizeProvider } from "../utils/provider-env.js";
+import { runCommand } from "../utils/process.js";
 import { STRATEGY } from "./types.js";
 
 /**
@@ -95,6 +96,13 @@ function createGhTokenCheck() {
     strategy: STRATEGY.PROMPT,
     applies: (config) => config?.git?.auto_pr === true,
     describe: "Run 'gh auth login' to authenticate with GitHub",
+    // KJC-BUG-0049: auto_pr es feature opcional. Si falta el token, no abortar
+    // el run — desactivar auto_pr y auto_push (sin push no hay PR posible) y
+    // continuar. El usuario verá WARN y el commit local sigue funcionando.
+    degradable: {
+      disables: ["git.auto_pr", "git.auto_push"],
+      warn: "auto_pr y auto_push DESACTIVADOS para este run (commit local sí funciona). Ejecuta `gh auth login` para reactivar.",
+    },
     async detect() {
       const envOk = !!process.env.GH_TOKEN || !!process.env.GITHUB_TOKEN;
       if (envOk) {
@@ -111,10 +119,25 @@ function createGhTokenCheck() {
           extra: { hasGh: false },
         };
       }
+      // KJC-BUG-0049 — el check anterior asumía que un usuario sin env var no
+      // tiene auth válida y abortaba el run. Pero `gh` puede estar autenticado
+      // por keyring/OAuth (caso default tras `gh auth login --web`) y operar
+      // sin env var. Si `gh auth status` devuelve exit 0 (logged in), el flujo
+      // de `auto_pr` funciona — Karajan ya no necesita `GH_TOKEN` en env.
+      try {
+        const auth = await runCommand("gh", ["auth", "status"], { reject: false });
+        if (auth.exitCode === 0) {
+          return {
+            ok: true,
+            severity: "info",
+            detail: "`gh` authenticated via keyring/OAuth (no env var needed)",
+          };
+        }
+      } catch { /* fall through to FAIL */ }
       return {
         ok: false,
         severity: "fail",
-        detail: "No GH_TOKEN/GITHUB_TOKEN; `gh` is installed but auth status unknown",
+        detail: "No GH_TOKEN/GITHUB_TOKEN and `gh auth status` reports not logged in",
         fix: "Run 'gh auth login' or export GH_TOKEN=...",
         extra: { hasGh: true },
       };

package/src/checks/types.js

@@ -41,6 +41,12 @@
  * @property {Object} [changes]                  - runtime config overrides to merge into the active session
  */
 
+/**
+ * @typedef {Object} DegradableSpec
+ * @property {string[]} disables        - dot-paths del config a desactivar si el check falla (e.g. ["git.auto_pr", "git.auto_push"])
+ * @property {string} warn              - mensaje WARN que se muestra al usuario explicando qué se desactivó y por qué
+ */
+
 /**
  * @typedef {Object} Check
  * @property {string} name                       - slug, unique across all checks (e.g. "node-version")
@@ -50,6 +56,10 @@
  * @property {(ctx: RemediationContext) => Promise<RemediationResult>} [remediate]
  * @property {string} [describe]                 - shown to user when strategy is "prompt"
  * @property {(config: Object) => boolean} [applies]  - if false, check is SKIPPED (lazy evaluation). Default: always applies.
+ * @property {DegradableSpec} [degradable]       - KJC-BUG-0049: si está definido y el check falla, en lugar de abortar
+ *                                                  el preflight, se desactivan los flags listados en `disables` y se emite
+ *                                                  WARN con `warn`. Útil para features opcionales (auto_pr, auto_push,
+ *                                                  sonar advisory, etc.) que no son blockers absolutos.
  */
 
 /**

package/src/cli/register-pipeline.js

@@ -177,6 +177,7 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("-y, --yes", "Auto-confirm prompts for invasive remediations (CI mode)")
     .option("--json", "Emit machine-readable JSON instead of human output")
     .option("--verbose", "Include fix hints and timing for every check")
+    .option("--project", "Run ONLY project-aware checks (signals, tools per signal, write perms, .env consistency, gh remote access) — useful to validate a specific project before kj run")
     .action(async (flags) => {
       const exitCode = await withConfig(pkgVersion, "doctor", {}, (ctx) =>
         doctorCommand({
@@ -185,6 +186,7 @@ export function registerPipeline(program, { pkgVersion }) {
           yes: !!flags.yes,
           json: !!flags.json,
           verbose: !!flags.verbose,
+          projectOnly: !!flags.project,
         })
       );
       if (Number.isInteger(exitCode)) process.exit(exitCode);

package/src/cli/register-plan.js

@@ -7,6 +7,8 @@ import {
   planDeleteCommand,
   planAddHuCommand,
   planRemoveHuCommand,
+  planMigrateResultCommand,
+  planFixCommand,
 } from "../commands/plan.js";
 import { parseCanvasMarkdown } from "../canvas/parse-md.js";
 import { validateCanvas } from "../canvas/validate.js";
@@ -149,4 +151,31 @@ export function registerPlan(program, { pkgVersion }) {
       await planRemoveHuCommand({ config, planId, huId });
     });
   });
+
+  // KJC-TSK-0402: re-ejecuta reviewer + self-fix + structural pass sobre
+  // un plan existente. Acepta --prompt opcional con feedback humano que
+  // el reviewer inyecta como contexto extra antes de revisar.
+  plan.command("fix")
+    .description("Relanzar self-fix loop sobre plan existente (con --prompt opcional)")
+    .argument("<planId>")
+    .option("--prompt <text>", "Feedback del usuario para guiar al reviewer")
+    .option("--json", "Output JSON con before/after counts")
+    .action(async (planId, flags) => {
+      await withConfig(pkgVersion, "plan", flags, async ({ config, logger }) => {
+        await planFixCommand({ config, planId, prompt: flags.prompt, logger, json: flags.json });
+      });
+    });
+
+  // KJC-TSK-0394 step 4: migración one-shot que siembra `result` en las
+  // HUs de los plan files existentes (basado en su status legacy). Solo
+  // toca el campo result, NO el status — el cleanup del enum lo hará
+  // step 5. Idempotente.
+  plan.command("migrate-result")
+    .description("Backfill the `result` field on existing plan HUs (KJC-TSK-0394 step 4)")
+    .option("--dry-run", "Show what would change without writing")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "plan", flags, async ({ config }) => {
+        await planMigrateResultCommand({ config, flags: { dryRun: flags.dryRun } });
+      });
+    });
 }

package/src/cli/register-standby.js

@@ -0,0 +1,26 @@
+// KJC-TSK-0414 PR2: registra `kj standby list` + `kj standby resume <id>`.
+// `resume` es subcomando de standby para no colisionar con el `kj resume`
+// pre-existente (Solomon pauses con --answer). Modelos mentales distintos:
+//   - `kj resume <id> --answer X`  → Solomon pauseado (existente)
+//   - `kj standby resume <id>`     → run hibernada por quota
+import { resumeCommand, standbyListCommand } from "../commands/standby.js";
+
+export function registerStandby(program) {
+  const standby = program.command("standby").description("Sesiones hibernadas (QUOTA_EXHAUSTED_DAILY etc.)");
+  standby
+    .command("list", { isDefault: true })
+    .description("Lista sesiones pendientes de reanudar")
+    .option("--json", "Output JSON")
+    .action(async (flags) => {
+      await standbyListCommand({ json: flags.json });
+    });
+
+  standby
+    .command("resume")
+    .description("Reanuda una sesión hibernada (re-spawn comando original)")
+    .argument("<sessionId>")
+    .option("--force", "Reanudar aunque cooldownUntil todavía esté en el futuro (no recomendado)")
+    .action(async (sessionId, flags) => {
+      await resumeCommand({ sessionId, force: Boolean(flags.force) });
+    });
+}

package/src/cli.js

@@ -9,6 +9,7 @@ import { registerPlan } from "./cli/register-plan.js";
 import { registerRolesSkills } from "./cli/register-roles-skills.js";
 import { registerMeta } from "./cli/register-meta.js";
 import { registerSonar } from "./cli/register-sonar.js";
+import { registerStandby } from "./cli/register-standby.js";
 import { printUpdateNotice } from "./utils/update-check.js";
 import { printWelcomeScreen } from "./utils/welcome.js";
 
@@ -44,6 +45,7 @@ registerPlan(program, { pkgVersion: PKG_VERSION });
 registerRolesSkills(program, { pkgVersion: PKG_VERSION });
 registerMeta(program, { pkgVersion: PKG_VERSION });
 registerSonar(program);
+registerStandby(program);
 
 /**
  * Find subcommands whose name is "close enough" to a typo. Used by the

package/src/commands/architect.js

@@ -3,6 +3,7 @@ import { assertAgentsAvailable } from "../agents/availability.js";
 import { resolveRole } from "../config.js";
 import { buildArchitectPrompt, parseArchitectOutput } from "../prompts/architect.js";
 import { createCliProgressReporter } from "../utils/cli-progress.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
 
 function formatLayers(layers, lines) {
   lines.push("### Layers");
@@ -71,8 +72,11 @@ export async function architectCommand({ task, config, logger, context, json })
     const progress = createCliProgressReporter({ role: "architect" });
     let result;
     try {
-      result = await agent.runTask({ prompt, onOutput: progress.onOutput, role: "architect" });
-      progress.finish(result.ok ? "done" : "failed");
+      result = await withBrainRecovery({
+        agent, taskArgs: { prompt, onOutput: progress.onOutput, role: "architect" },
+        role: "architect", provider: architectRole.provider, logger,
+      });
+      progress.finish(result.ok ? "done" : (result.action || "failed"));
     } catch (err) { progress.finish("failed"); throw err; }
 
     if (!result.ok) {

package/src/commands/discover.js

@@ -1,6 +1,7 @@
 import { createAgent } from "../agents/index.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { resolveRole } from "../config.js";
+import { withBrainRecovery } from "../brain/with-brain-recovery.js";
 import { createCliProgressReporter } from "../utils/cli-progress.js";
 import { buildDiscoverPrompt, parseDiscoverOutput } from "../prompts/discover.js";
 
@@ -75,8 +76,11 @@ export async function discoverCommand({ task, config, logger, mode, json }) {
     const progress = createCliProgressReporter({ role: "discover" });
     let result;
     try {
-      result = await agent.runTask({ prompt, onOutput: progress.onOutput, role: "discover" });
-      progress.finish(result.ok ? "done" : "failed");
+      result = await withBrainRecovery({
+        agent, taskArgs: { prompt, onOutput: progress.onOutput, role: "discover" },
+        role: "discover", provider: discoverRole.provider, logger,
+      });
+      progress.finish(result.ok ? "done" : (result.action || "failed"));
     } catch (err) { progress.finish("failed"); throw err; }
 
     if (!result.ok) {

package/src/commands/doctor.js

@@ -26,13 +26,25 @@ import { getTokenChecks } from "../checks/tokens.js";
 import { getMcpHealthChecks } from "../checks/mcp-health.js";
 import { getSkillsChecks } from "../checks/skills.js";
 import { getDirSetupChecks } from "../checks/dir-setup.js";
+import { getProjectChecks } from "../checks/project-checks.js";
 
 /**
  * Build the list of Check objects applicable to the current config.
+ *
+ * KJC-TSK-0393: cuando `projectOnly === true`, devuelve SOLO los project-aware
+ * checks (signals, tools per signal, write perms, .env consistency, gh remote
+ * access). Útil para validar un proyecto específico sin re-correr todos los
+ * checks globales (CLIs, node, sonar, etc.).
+ *
  * @param {Object} config
+ * @param {{ projectOnly?: boolean }} [opts]
  * @returns {import("../checks/types.js").Check[]}
  */
-function buildChecks(config) {
+function buildChecks(config, { projectOnly = false } = {}) {
+  const projectDir = config?.projectDir || process.cwd();
+  if (projectOnly) {
+    return getProjectChecks({ projectDir });
+  }
   return [
     ...getSystemChecks(),
     ...getNodeChecks(),
@@ -46,6 +58,7 @@ function buildChecks(config) {
     ...getSkillsChecks(),
     ...getCiChecks(),
     ...getRtkChecks(),
+    ...getProjectChecks({ projectDir }),
   ];
 }
 
@@ -77,8 +90,8 @@ function confirmViaTty(describe) {
  * @param {{ config: Object, checkOnly?: boolean, yes?: boolean, onConfirm?: Function, logger?: Object }} args
  * @returns {Promise<import("../checks/types.js").RunReport>}
  */
-async function runDoctor({ config, checkOnly = false, yes = false, onConfirm, logger }) {
-  const checks = buildChecks(config);
+async function runDoctor({ config, checkOnly = false, yes = false, onConfirm, logger, projectOnly = false }) {
+  const checks = buildChecks(config, { projectOnly });
   return runCheckPipeline(checks, { config }, {
     mode: checkOnly ? "check-only" : "fix",
     yes,
@@ -105,8 +118,8 @@ export async function runChecks({ config }) {
  * @param {{ config: Object, checkOnly?: boolean, yes?: boolean, json?: boolean, verbose?: boolean }} args
  * @returns {Promise<number>}
  */
-export async function doctorCommand({ config, checkOnly = false, yes = false, json = false, verbose = false }) {
-  const report = await runDoctor({ config, checkOnly, yes });
+export async function doctorCommand({ config, checkOnly = false, yes = false, json = false, verbose = false, projectOnly = false }) {
+  const report = await runDoctor({ config, checkOnly, yes, projectOnly });
 
   if (json) {
     console.log(JSON.stringify(report, null, 2));

package/src/commands/init.js

@@ -127,6 +127,52 @@ async function askPerRoleProviders(wizard, available, config, { coder, reviewer
   }
 }
 
+/**
+ * KJC-TSK-0415: Plan B — fallback chain. Cuando el provider primario se
+ * queda sin créditos (QUOTA_EXHAUSTED_DAILY/MONTHLY) y el cooldown excede
+ * max_wait_hours, Brain switchea al fallback en vez de hibernar.
+ *
+ * Solo pregunta si hay >= 2 providers disponibles (sin alternativas reales
+ * no tiene sentido el fallback).
+ */
+async function askFallbackChain(wizard, available, config, { coder, reviewer }, logger) {
+  if (available.length < 2) return;
+
+  logger.info("");
+  logger.info("Plan B — fallback automático cuando un provider se queda sin créditos:");
+  const enable = await wizard.confirm(
+    "  ¿Configurar fallback? (default: 12h; si el cooldown supera ese tiempo, switch al provider alternativo)",
+    true
+  );
+  if (!enable) return;
+
+  const maxHoursRaw = await wizard.input("  Máximo tiempo de espera antes de fallback (horas):", "12");
+  const maxHours = Number.parseFloat(maxHoursRaw) || 12;
+
+  config.roles = config.roles || {};
+  const KEY_ROLES = [
+    { key: "coder", label: "coder", primary: coder },
+    { key: "reviewer", label: "reviewer", primary: reviewer },
+    { key: "planner", label: "planner", primary: coder },
+  ];
+  for (const role of KEY_ROLES) {
+    config.roles[role.key] = config.roles[role.key] || {};
+    const opts = [{ label: "Sin fallback (hibernar)", value: "__none__", available: true }];
+    for (const a of available) {
+      if (a.name === role.primary) continue;
+      opts.push({ label: a.name, value: a.name, available: true });
+    }
+    const choice = await wizard.select(`  Fallback de ${role.label} cuando ${role.primary} se quede sin créditos:`, opts);
+    if (choice === "__none__") {
+      delete config.roles[role.key].fallback;
+      logger.info(`    -> ${role.key}: sin fallback (hibernará)`);
+    } else {
+      config.roles[role.key].fallback = { provider: choice, max_wait_hours: maxHours };
+      logger.info(`    -> ${role.key}: ${role.primary} → ${choice} (tras ${maxHours}h)`);
+    }
+  }
+}
+
 async function askMethodology(wizard, config, logger) {
   const methodology = await wizard.select("Development methodology:", [
     { label: "TDD (test-driven development)", value: "tdd", available: true },
@@ -256,6 +302,7 @@ async function runWizard(config, logger) {
     logger.info(`  -> HU Board: ${enableHuBoard ? "enabled (auto-start on kj run)" : "disabled"}`);
 
     await askPerRoleProviders(wizard, available, config, { coder, reviewer }, logger);
+    await askFallbackChain(wizard, available, config, { coder, reviewer }, logger);
     await askMethodology(wizard, config, logger);
     await askLanguages(wizard, config, logger);
 

package/src/commands/plan/_shared.js

@@ -25,16 +25,31 @@ export function formatPlan(plan) {
   return lines.join("\n");
 }
 
+/**
+ * Convierte el id largo de una dep `hu_<planId>_<NNN>` al short_id de
+ * la HU correspondiente cuando lo conoce. Mantiene el id largo si la
+ * dep no tiene short_id (HU legacy pre-humanización).
+ */
+function displayDep(depId, hus) {
+  const hu = hus.find((h) => h.id === depId);
+  if (hu?.short_id) return hu.short_id;
+  return depId;
+}
+
 export function formatHuTable(hus) {
   if (!hus?.length) return "  (no HUs)";
+  // Humanización IDs: si la HU tiene short_id ("INFRA-001"), úsalo
+  // como columna ID; si no, fallback al id largo (HU legacy).
+  const idOf = (h) => h.short_id || h.id;
   const lines = [];
+  const maxId = Math.min(20, Math.max(...hus.map((h) => idOf(h).length || 0)));
   const maxTitle = Math.min(50, Math.max(...hus.map(h => h.title?.length || 0)));
-  lines.push(`  ${"ID".padEnd(30)} ${"Title".padEnd(maxTitle)} ${"Type".padEnd(10)} ${"Status".padEnd(10)} Deps`);
-  lines.push(`  ${"─".repeat(30)} ${"─".repeat(maxTitle)} ${"─".repeat(10)} ${"─".repeat(10)} ${"─".repeat(15)}`);
+  lines.push(`  ${"ID".padEnd(maxId)} ${"Title".padEnd(maxTitle)} ${"Type".padEnd(10)} ${"Status".padEnd(10)} Deps`);
+  lines.push(`  ${"─".repeat(maxId)} ${"─".repeat(maxTitle)} ${"─".repeat(10)} ${"─".repeat(10)} ${"─".repeat(15)}`);
   for (const hu of hus) {
     const title = (hu.title || "").slice(0, maxTitle).padEnd(maxTitle);
-    const deps = (hu.blocked_by || []).join(", ") || "—";
-    lines.push(`  ${hu.id.padEnd(30)} ${title} ${(hu.task_type || "sw").padEnd(10)} ${(hu.status || "?").padEnd(10)} ${deps}`);
+    const deps = (hu.blocked_by || []).map((d) => displayDep(d, hus)).join(", ") || "—";
+    lines.push(`  ${idOf(hu).padEnd(maxId)} ${title} ${(hu.task_type || "sw").padEnd(10)} ${(hu.status || "?").padEnd(10)} ${deps}`);
   }
   return lines.join("\n");
 }