karajan-code 4.53.0 → 4.54.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.53.0",
+  "version": "4.54.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/checks/qmd.js

@@ -22,14 +22,15 @@ function createQmdCheck() {
       try {
         const res = await runCommand("qmd", ["--version"]);
         if (res.exitCode === 0) {
-          return { ok: true, severity: "info", detail: `${res.stdout.trim()} — semantic wiki active` };
+          // KJC-TSK-1067: say what it is for, not only that it is there.
+          return { ok: true, severity: "info", detail: `${res.stdout.trim()} — answers about the project's docs, notes, ADRs and plans from the documents, with fewer tokens (kj env install wires its MCP)` };
         }
       } catch { /* not installed */ }
       const installCmd = getInstallCommand("qmd");
       return {
         ok: false,
         severity: "warn",
-        detail: "Not found — semantic wiki via QMD available",
+        detail: "Not found — qmd answers questions about the project's docs, notes, ADRs and plans from the documents, with fewer tokens and a source",
         fix: withDocLink(`Install: ${installCmd}`, "qmd_install"),
       };
     },

package/src/cli/register-meta.js

@@ -197,12 +197,17 @@ export function registerMeta(program, { pkgVersion }) {
   // KJC-TSK-0968 (HUM-E, ADR 0018): the agent's handoff to the human goes through kj.
   const handoffCmd = program.command("handoff").description("Handoffs: what a gate denied the agent, registered with the gate's why, for the human to read and run by id");
   const handoff = (action, flags) => withConfig(pkgVersion, `handoff-${action}`, flags, async ({ config }) => { process.exitCode = await handoffCommand({ action, config, flags }); });
-  handoffCmd.command("add").description("Register the EXACT command a gate denied (the why comes from the Sentinel's record, not from you)")
+  handoffCmd.command("add").description("Register the EXACT command a gate denied (the why comes from the Sentinel's record, not from you), or with --why an action only the human can take")
     .argument("<command...>", "the denied command, as it was run").option("--cwd <dir>", "Directory the command runs in (default: the project)")
+    .option("--why <text>", "KJC-TSK-1066: what an action only the human can take is for (publish, seal); marked as the agent's")
     .action((parts, flags) => handoff("add", { ...flags, command: parts.join(" ") }));
   handoffCmd.command("list", { isDefault: true }).description("The handoffs registered in this project").action((flags) => handoff("list", flags));
   handoffCmd.command("show").description("A handoff: the exact command, its sha256 and why the gate denied it")
     .argument("<id>", "handoff id (8 hex)").option("--json", "Output the record as JSON").action((id, flags) => handoff("show", { ...flags, id }));
+  handoffCmd.command("done").description("The human did it: it leaves the pending handoffs and stays in the history")
+    .argument("<id>", "handoff id (8 hex)").action((id, flags) => handoff("done", { ...flags, id }));
+  handoffCmd.command("watch").description("Your task window: the pending handoffs, then each new one as it lands, with date and why (Ctrl+C to leave)")
+    .action((flags) => handoff("watch", flags));
 
   // KJC-TSK-0986 (HUM-F): the invitation to enroll the phone, once per version.
   identityCmd

package/src/commands/handoff.js

@@ -2,18 +2,22 @@
  * kj handoff add|list|show (KJC-TSK-0968, HUM-E, ADR 0018): the agent registers
  * what a gate denied it, with the gate's why; the human reads it by id.
  */
-import { addHandoff, listHandoffs, readHandoff } from "../harden/handoff.js";
+import { addHandoff, listHandoffs, markHandoffDone, readHandoff, watchHandoffs } from "../harden/handoff.js";
 
-const line = (h) => `${h.id}  ${h.status.padEnd(8)}  ${h.createdAt}  ${h.command}`;
+const line = (h) => {
+  const why = h.kind === "task" ? "  (" + h.why + ")" : "";
+  return `${h.id}  ${h.status.padEnd(8)}  ${h.createdAt}  ${h.command}${why}`;
+};
 
 /** @returns {Promise<0|1>} */
 export async function handoffCommand({ action = "list", config, flags = {}, log = console.log }) {
   const projectDir = config?.projectDir || process.cwd();
   try {
     if (action === "add") {
-      const record = addHandoff({ projectDir, command: flags.command, cwd: flags.cwd ?? projectDir });
+      const record = addHandoff({ projectDir, command: flags.command, cwd: flags.cwd ?? projectDir, why: flags.why ?? null });
       log(`encargo ${record.id} registrado: ${record.command}`);
-      log(`por qué lo negó el gate (${record.denial.at}):\n${record.denial.why}`);
+      if (record.kind === "task") log(`para qué (propuesto por el agente): ${record.why}`);
+      else log(`por qué lo negó el gate (${record.denial.at}):\n${record.denial.why}`);
       log(`tu usuario lo revisa con kj handoff show ${record.id}; nadie copia y pega el comando.`);
       return 0;
     }
@@ -24,7 +28,21 @@ export async function handoffCommand({ action = "list", config, flags = {}, log
       log(`comando   ${h.command}`);
       log(`sha256    ${h.sha256}`);
       log(`cwd       ${h.cwd}`);
-      log(`gate      ${h.denial.tool} negó el ${h.denial.at}:\n${h.denial.why}`);
+      if (h.kind === "task") log(`para qué   ${h.why}\n          (propuesto por el agente, no lo negó ningún gate)`);
+      else log(`gate      ${h.denial.tool} negó el ${h.denial.at}:\n${h.denial.why}`);
+      if (h.doneAt) log(`hecho     ${h.doneAt}`);
+      return 0;
+    }
+    if (action === "done") {
+      const h = markHandoffDone({ projectDir, id: flags.id });
+      log(`encargo ${h.id} hecho: ${h.command}`);
+      return 0;
+    }
+    if (action === "watch") {
+      log("kj handoff watch: lo que te toca hacer a ti, según llega (Ctrl+C para salir)");
+      const ctl = new AbortController();
+      process.once("SIGINT", () => ctl.abort());
+      await watchHandoffs({ projectDir, log, signal: ctl.signal });
       return 0;
     }
     const all = listHandoffs({ projectDir });

package/src/commands/hu.js

@@ -11,6 +11,7 @@ import { savePlan, listPlans, loadPlan } from "../plan/plan-store.js";
 import { detectHostAgent } from "../utils/agent-detect.js";
 import { readIdentity } from "../identity/store.js";
 import { effectiveGitEmail } from "../identity/detect.js";
+import { roleSkills } from "../skills/role-skills.js";
 
 // KJC-TSK-0661 (Jorge's friction): every HU records WHO created it — the
 // board must never show work nobody can trace. Host agent env → that agent;
@@ -238,6 +239,13 @@ export async function huCommand({ config = null, action, args = [], flags = {},
     if (starting || takenOver || unclaimedRunning) Object.assign(hu, { claimed_by: who ?? null, claimed_at: who ? new Date().toISOString() : null });
     if (starting && !who) console.warn(`⚠ ${label} is not reserved: kj cannot tell who works this clone — declare it with kj identity set`);
     await savePlan(projectDir, plan);
+    // KJC-TSK-1065: the host session starts the card here; it learns which skills apply and where to read them.
+    if (starting && !flags.json) {
+      const text = [hu.title, hu.scope, ...(Array.isArray(hu.acceptance_criteria) ? hu.acceptance_criteria : [])].filter(Boolean).join(" ");
+      const { skills } = await (deps.skills ?? roleSkills)({ role: "coder", task: text, projectDir });
+      const where = (s) => (s.path ? ": read " + s.path : " (native)");
+      if (skills.length) console.log([`skills for ${label} (read them before you start):`, ...skills.map((s) => "- " + s.name + where(s))].join("\n"));
+    }
     return emit({ id: hu.id, status, claimed_by: hu.claimed_by ?? null }, `✓ ${label} → ${status}`);
   }
 

package/src/environment/mcp-wiring.js

@@ -8,10 +8,28 @@
  * entries; invalid JSON is left untouched (preserve, never clobber).
  */
 
+import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { join } from "node:path";
 
-export function installProjectMcp({ projectDir = process.cwd(), logger = console } = {}) {
+// KJC-TSK-1067: a server spec that launches `qmd mcp` (command or args, any path).
+const launchesQmd = (s) => Boolean(s) && typeof s === "object"
+  && [s.command, ...(Array.isArray(s.args) ? s.args : [])].some((a) => typeof a === "string" && /(^|\/)qmd$/.test(a))
+  && Array.isArray(s.args) && s.args.includes("mcp");
+
+const defaultQmd = {
+  installed: () => spawnSync("qmd", ["--version"], { stdio: "ignore" }).status === 0,
+  // The user's own Claude Code config: global servers and every project's.
+  wiredGlobally: () => {
+    try {
+      const c = JSON.parse(readFileSync(join(homedir(), ".claude.json"), "utf8"));
+      return [c.mcpServers, ...Object.values(c.projects || {}).map((p) => p?.mcpServers)].some((m) => Object.values(m || {}).some(launchesQmd));
+    } catch { return false; }
+  },
+};
+
+export function installProjectMcp({ projectDir = process.cwd(), logger = console, qmd = defaultQmd } = {}) {
   const mcpPath = join(projectDir, ".mcp.json");
   let cfg = {};
   if (existsSync(mcpPath)) {
@@ -37,8 +55,17 @@ export function installProjectMcp({ projectDir = process.cwd(), logger = console
   const present = Object.values(cfg.mcpServers).some(launchesRagMcp);
   if (!present) {
     cfg.mcpServers["kj-rag"] = { command: "kj-rag-mcp", args: [] };
-    writeFileSync(mcpPath, `${JSON.stringify(cfg, null, 2)}\n`);
     logger.info?.("✓ kj_rag_query wired as a NATIVE tool (.mcp.json → kj-rag-mcp): querying the RAG is now the agent's cheapest path");
   }
-  return { wired: true, added: !present };
+  // KJC-TSK-1067: qmd answers about the project's documents with fewer tokens and a source.
+  let qmdState = "absent";
+  if (Object.values(cfg.mcpServers).some(launchesQmd)) qmdState = "present";
+  else if (qmd.installed() && qmd.wiredGlobally()) qmdState = "global";
+  else if (qmd.installed()) {
+    cfg.mcpServers.qmd = { command: "qmd", args: ["mcp"] };
+    qmdState = "added";
+    logger.info?.("✓ qmd wired as a NATIVE tool (.mcp.json → qmd mcp): questions about docs, notes, ADRs and plans answer from the documents, with fewer tokens");
+  }
+  if (!present || qmdState === "added") writeFileSync(mcpPath, `${JSON.stringify(cfg, null, 2)}\n`);
+  return { wired: true, added: !present, qmd: qmdState };
 }

package/src/environment/playbook.js

@@ -61,7 +61,8 @@ Invariants (the git gates enforce these — they are not suggestions):
 
 - The project RAG answers before you assume: \`kj rag query\` — never guess
   what the codebase does. In MCP hosts the same index is the native
-  \`kj_rag_query\` tool: reach for it before grepping by hand.
+  \`kj_rag_query\` tool: reach for it before grepping by hand. Questions about
+  the project's docs, notes, ADRs or plans: ask qmd (its MCP) first.
 - ${trackingLine(stateBackend, boardName)}
 - Tests prove behavior: the failing test exists first (TDD), and the suite
   is never left red. Green is not proof: with \`method_gates.mutation\`
@@ -103,6 +104,8 @@ Hit a kj bug or friction? Diagnose it and file it upstream with
 \`kj report-issue\` (sanitized; ask your user before \`--publish\`).
 kj announces a newer version? Tell your user what it brings and ask —
 never run \`kj update\` on your own.
+Something only your user can do (publish, seal, run a script)? Register it:
+\`kj handoff add <command> --why "<what for>"\`; they follow \`kj handoff watch\`.
 `;
 
 export function renderPlaybook({ stateBackend = "hu-board", boardName = null, config = null } = {}) {

package/src/harden/handoff.js

@@ -30,19 +30,69 @@ export function findDenial({ projectDir, command }) {
  * exact bytes there is nothing to hand off: the agent does not write the why.
  * @returns {{id: string, command: string, sha256: string, why: string}}
  */
-export function addHandoff({ projectDir, command, cwd = projectDir }) {
+export function addHandoff({ projectDir, command, cwd = projectDir, why = null }) {
   if (typeof command !== "string" || !command.trim()) throw new Error("kj handoff add: falta el comando exacto que el gate negó");
   const denial = findDenial({ projectDir, command });
-  if (!denial) throw new Error("kj handoff add: kj no tiene registrado ningún deny para ese comando exacto; el porqué de un encargo lo escribe el gate, no el agente (ADR 0018)");
+  // KJC-TSK-1066: an action only the human can take (publish, seal) is a TASK, with
+  // the agent's why marked as the agent's. A command a gate denied keeps the gate's.
+  const task = !denial && typeof why === "string" && why.trim();
+  if (!denial && !task) throw new Error("kj handoff add: kj no tiene registrado ningún deny para ese comando exacto; el porqué de un encargo lo escribe el gate, no el agente (ADR 0018). Para una acción que solo puede hacer el humano, di para qué con --why");
   const createdAt = new Date().toISOString();
   const digest = sha256(command);
   const id = sha256(`${digest}:${createdAt}`).slice(0, 8);
-  const record = { id, command, sha256: digest, cwd, createdAt, status: "pending", denial: { at: denial.at, tool: denial.tool, why: denial.why } };
+  const base = { id, command, sha256: digest, cwd, createdAt, status: "pending" };
+  const record = task ? { ...base, kind: "task", why: why.trim(), denial: null } : { ...base, kind: "denial", denial: { at: denial.at, tool: denial.tool, why: denial.why } };
+  writeRecord(projectDir, record);
+  return record;
+}
+
+const writeRecord = (projectDir, record) => {
   mkdirSync(join(projectDir, HANDOFFS_DIR), { recursive: true });
-  writeFileSync(join(projectDir, HANDOFFS_DIR, `${id}.json`), `${JSON.stringify(record, null, 2)}\n`, "utf8");
+  writeFileSync(join(projectDir, HANDOFFS_DIR, `${record.id}.json`), `${JSON.stringify(record, null, 2)}\n`, "utf8");
+};
+
+/** KJC-TSK-1066: the human did it; it leaves the pending ones and stays in the history. */
+export function markHandoffDone({ projectDir, id }) {
+  const record = { ...readHandoff({ projectDir, id }), status: "done", doneAt: new Date().toISOString() };
+  writeRecord(projectDir, record);
   return record;
 }
 
+/** The handoff as the watch window shows it: local date and time, the command, and why. */
+export function formatHandoff(h) {
+  const at = new Date(h.createdAt);
+  const pad = (n) => String(n).padStart(2, "0");
+  const when = `${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())} ${pad(at.getHours())}:${pad(at.getMinutes())}`;
+  const why = h.kind === "task" ? `${h.why} (propuesto por el agente)` : `lo negó el gate: ${String(h.denial?.why ?? "").split("\n")[0]}`;
+  return `[${when}] ${h.id}  ${h.command}\n    ${why}`;
+}
+
+/**
+ * KJC-TSK-1066: kj handoff watch. Shows the pending handoffs, then each new or
+ * changed one as it lands, until the signal aborts (Ctrl+C in the CLI).
+ */
+export async function watchHandoffs({ projectDir, log, intervalMs = 2000, signal }) {
+  const seen = new Map();
+  const tick = () => {
+    for (const h of listHandoffs({ projectDir })) {
+      if (seen.get(h.id) === h.status) continue;
+      const first = !seen.has(h.id);
+      seen.set(h.id, h.status);
+      if (h.status === "pending") log(formatHandoff(h));
+      else if (!first) log(`[hecho] ${h.id}  ${h.command}`);
+    }
+  };
+  tick();
+  // One abort promise for the whole watch, raced against each pause: no listener per tick.
+  const aborted = new Promise((resolve) => signal?.addEventListener("abort", resolve, { once: true }));
+  while (!signal?.aborted) {
+    let timer;
+    await Promise.race([aborted, new Promise((resolve) => { timer = setTimeout(resolve, intervalMs); })]);
+    clearTimeout(timer);
+    if (!signal?.aborted) tick();
+  }
+}
+
 export function readHandoff({ projectDir, id }) {
   if (!/^[0-9a-f]{8}$/.test(id ?? "")) throw new Error(`kj handoff: "${id}" no es un identificador de encargo (8 hex)`);
   const path = join(projectDir, HANDOFFS_DIR, `${id}.json`);

package/src/harden/sentinel/sentinel-shell.mjs

@@ -155,6 +155,65 @@ export const stripTextOptionValues = (cmd) => cmd
   .replace(KJ_TITLE, (m, pre, head, val) => `${pre}${head}${val[0]}${val[0]}`)
   .replace(QUOTED_OPTION_VALUE, (m, pre, opt, sep, val) => (TEXT_OPTIONS.has(opt) ? `${pre}${opt}${sep}${val[0]}${val[0]}` : m));
 
+// KJC-BUG-0354: commands that only STORE their text: there, a quoted text value
+// is never run. Anywhere else it may be (flock --command '...'), so it stays.
+// git's global options that only pick where and how it runs may precede commit.
+const GIT_GLOBAL_WITH_VALUE = new Set(["-c", "-C", "--git-dir", "--work-tree", "--namespace"]);
+const GIT_GLOBAL_FLAG = /^(?:--no-pager|--(?:git-dir|work-tree|namespace)=\S+)$/;
+
+const isGitCommit = (words) => {
+  let i = 1;
+  while (i < words.length) {
+    if (GIT_GLOBAL_WITH_VALUE.has(words[i])) i += 2;
+    else if (GIT_GLOBAL_FLAG.test(words[i])) i += 1;
+    else break;
+  }
+  return words[0] === "git" && words[i] === "commit";
+};
+
+const isTextOnlyHead = (seg) => /^kj\s+(?:hu|adr)\s+add\b/.test(seg) || isGitCommit(seg.split(/\s+/));
+
+/**
+ * KJC-BUG-0354: blank the quoted text values (stripTextOptionValues) only when the
+ * whole input is a text-only command, so the human-act guards stop reading a
+ * title or a commit message that merely mentions a guarded command.
+ * @param {string} cmd
+ */
+export const stripTextOnlyCommandValues = (cmd) => {
+  // Only a whole input that is ONE simple text-storage command: a chained
+  // segment could follow a shell function that turns the stored text into code.
+  const bare = stripInertQuotes(cmd);
+  if (splitOutsideQuotes(cmd).length !== 1 || /[(){}<>`$\n]/.test(bare) || !isTextOnlyHead(cmd.trim())) return cmd;
+  return stripTextOptionValues(cmd);
+};
+
+/** Segments and the ; && || | between them, cut only outside quotes (the pieces join back to cmd). */
+function splitOutsideQuotes(cmd) {
+  const parts = [];
+  let start = 0;
+  let quote = null;
+  let i = 0;
+  while (i < cmd.length) {
+    const c = cmd[i];
+    const op = quote ? null : /^(?:&&|\|\||;|\|)/.exec(cmd.slice(i))?.[0];
+    if (quote) {
+      // inside double quotes a backslash escapes the next character
+      if (c === "\\" && quote === '"') i += 1;
+      else if (c === quote) quote = null;
+    } else if (c === "'" || c === '"') {
+      quote = c;
+    } else if (op) {
+      parts.push(cmd.slice(start, i), op);
+      start = i + op.length;
+      i = start;
+      continue;
+    }
+    i += 1;
+  }
+  parts.push(cmd.slice(start));
+  return parts;
+}
+
 /**
  * KJC-BUG-0245: the values of the named options, read by the shell reader, so a
  * `;`, `&&` or `|` right after a path ends the word instead of joining it.

package/src/harden/sentinel-hooks.js

@@ -88,7 +88,7 @@ export const boardGate = (sid, pend) => {
   if (!pend.length) return { blocking: [], carried: [] };
   const bg = spawnSync("kj", ["sentinel", "board-gate", "--session", sid, "--json"], { cwd: ROOT, encoding: "utf8" });
   if (!bg.error && (bg.status === 0 || bg.status === 2)) {
-    try { const d = JSON.parse(bg.stdout); return { blocking: d.blocking || [], carried: d.carried || [] }; } catch { /* unreadable: as always */ }
+    try { const d = JSON.parse(bg.stdout); return { blocking: d.blocking || [], carried: d.carried || [], reason: d.reason || "" }; } catch { /* unreadable: as always */ }
   }
   return { blocking: pend, carried: [] };
 };
@@ -216,7 +216,11 @@ process.stdin.on("end", () => {
       // KJC-BUG-0293: the host may hand the answer as {content:[parts]}, as the
       // bare array of parts, or as the text itself; all three are the same answer.
       const parts = Array.isArray(response?.content) ? response.content : Array.isArray(response) ? response : [{ text: typeof response === "string" ? response : "" }];
-      recordRag(input.text, parts.flatMap((p) => sourcesOf(parseJson(String(p?.text || "")))), parts.map((p) => String(p?.text || "")).join(String.fromCharCode(10)));
+      let found = parts.flatMap((p) => sourcesOf(parseJson(String(p?.text || ""))));
+      // KJC-BUG-0365 (#2208): an answer cut short (whole code chunks) is no
+      // longer valid JSON, but every "source" it carries still names a hit.
+      if (found.length === 0) found = [...text.matchAll(/\\\\?"source\\\\?"\\s*:\\s*\\\\?"([^"\\\\]+)\\\\?"/g)].map((m) => m[1]);
+      recordRag(input.text, found, parts.map((p) => String(p?.text || "")).join(String.fromCharCode(10)));
       process.exit(0);
     }
     if (/__update_card$/.test(String(tool)) && /^mcp__/.test(String(tool))) {
@@ -473,7 +477,7 @@ import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { doc, CODE, TESTS, ROOT, BASE_BRANCHES, CARD, STATE, branchOf, foreignLane, load, save, session, violations, boardGate, pendingMoves, pendingText } from "./sentinel-lib.mjs";
 // KJC-TSK-0915 (ADR 0014): the shell reader is a real, unit-tested module copied here as is.
-import { isGhIssueCreate, isPublishCommand, optionValues, shellSegments, stripInertQuotes, stripTextOptionValues } from "./sentinel-shell.mjs";
+import { isGhIssueCreate, isPublishCommand, optionValues, shellSegments, stripInertQuotes, stripTextOptionValues, stripTextOnlyCommandValues } from "./sentinel-shell.mjs";
 import { DISCARD_VERBS, discardOf, foreignLost, removedFiles } from "./sentinel-discard.mjs";
 import { shellWrites, writesRepo } from "./sentinel-bash-write.mjs";
 const EDIT_TOOLS = ["Write", "Edit", "MultiEdit", "NotebookEdit"];
@@ -606,7 +610,8 @@ process.stdin.on("end", () => {
     // — si un agente pudiera enrolar una clave SUYA, contestaria la capa 5 el
     // solo. Ni el comando ni el fichero de enrolamiento desde la sesion.
     {
-      const enrollCmd = String(input.command || "");
+      // KJC-BUG-0354: un titulo o un mensaje de commit que solo lo MENCIONA no es enrolar.
+      const enrollCmd = stripTextOnlyCommandValues(String(input.command || ""));
       const namesEnroll = (enrollCmd.includes("identity") && enrollCmd.includes("enroll-phone")) || enrollCmd.includes("supervisor-phone.json");
       const writesEnroll = EDIT_TOOLS.includes(tool) && String(input.file_path || "").includes("supervisor-phone.json");
       if ((tool === "Bash" && namesEnroll) || writesEnroll) {
@@ -618,11 +623,13 @@ process.stdin.on("end", () => {
     // sesion ni lo intenta. Sin escape (superficie de supervisor). includes()
     // a proposito: cero ambiguedad de escapes en plantilla, y fail-closed
     // (mencionarlo en un argumento tambien bloquea: preferible a un hueco).
+    // KJC-BUG-0354: salvo en el texto entrecomillado de kj hu add, kj adr add y
+    // git commit, que solo guardan texto (decision del usuario, 16-oct).
     // ANTES de KJ_SENTINEL_OFF a proposito, como el guard PROTECTED de
     // arriba: un env var lo pone tambien un agente — el supervisor no se
     // apaga con interruptores al alcance del supervisado.
     {
-      const kjCmd = String(input.command || "");
+      const kjCmd = stripTextOnlyCommandValues(String(input.command || ""));
       if (tool === "Bash" && kjCmd.includes("harden") && kjCmd.includes("--commit")) {
         console.error("karajan sentinel: kj harden --commit es un acto humano (ADR 0009) — pideselo a tu usuario; ninguna sesion de agente lo ejecuta." + doc("supervisor"));
         process.exit(2);
@@ -809,7 +816,9 @@ process.stdin.on("end", () => {
       // it need no verifying when nothing after it writes. One mutating segment
       // and the whole command is judged below, as before.
       const CD_LITERAL = /^[ \\t]*(cd|pushd)([ \\t]+[^ \\t;|&<>$\`(){}\\n\\r]*)?[ \\t]*$/;
-      const readsOnly = (s) => s.split(/&&|\\|\\||[;|]/).every((seg) => READONLY.test(seg) || CD_LITERAL.test(seg));
+      // KJC-BUG-0365: 2>&1 and 2>/dev/null only fold stderr, they write nothing.
+      const QUIET = /[ \\t]2>(?:&1|\\/dev\\/null)(?=[ \\t]|$)/g;
+      const readsOnly = (s) => s.split(/&&|\\|\\||[;|]/).every((seg) => READONLY.test(seg.replace(QUIET, "")) || CD_LITERAL.test(seg.replace(QUIET, "")));
       // KJC-BUG-0243: operators inside inert quotes (grep -e "a|b") do not chain anything.
       if (!readsOnly(stripInertQuotes(cmd))) {
         // cd/pushd invalida TODO razonamiento textual de rutas posteriores
@@ -1171,15 +1180,20 @@ process.stdin.on("end", () => {
       const ADVANCE = /\\bgit\\s+commit\\b|\\bgit\\s+push\\b|\\bgh\\s+pr\\s+create\\b/; // push also falls under violations() — explicit here too (review catch)
       const mergeM = cmd.match(MERGE);
       const pend = pendingMoves(load().sessions?.[sid]);
+      // KJC-BUG-0364: one board-gate decision per command; the push gate below
+      // reuses it, so a second slow gh cannot contradict the first answer.
+      let boardDecision = null;
       if (pend.length > 0 && (mergeM || ADVANCE.test(cmd))) {
         // KJC-BUG-0198: una card partida en varias PRs no puede quedar bloqueada
         // por su primera mitad (boardGate, en la lib).
-        const { blocking, carried } = boardGate(sid, pend);
+        boardDecision = boardGate(sid, pend);
+        const { blocking, carried, reason } = boardDecision;
         for (const c of carried) console.error("karajan sentinel: board-sync arrastra " + c.card + " — " + c.why + ", se movera al cerrarla");
         // ADR 0015 (KJC-TSK-0925): no escape; an epic and a card split across PRs
         // are already decided above (KJC-BUG-0230, 0198).
+        // KJC-BUG-0363: when kj could not check, its reason travels with the block.
         if (blocking.length > 0) {
-          console.error("karajan sentinel: board-sync — el metodo no avanza con cards mergeadas sin mover:\\n" + blocking.map((p) => "- " + pendingText(p)).join("\\n") + doc("board-sync"));
+          console.error("karajan sentinel: board-sync — el metodo no avanza con cards mergeadas sin mover:\\n" + blocking.map((p) => "- " + pendingText(p)).join("\\n") + (reason ? "\\n(" + reason + ")" : "") + doc("board-sync"));
           process.exit(2);
         }
       }
@@ -1225,9 +1239,10 @@ process.stdin.on("end", () => {
         // ADR 0015 (KJC-TSK-0925): with no escape.
         // KJC-BUG-0262: a carried card does not block the push the commit let through.
         const sess = load().sessions?.[sid];
-        const v = violations(sess, branchOf(), boardGate(sid, pendingMoves(sess)).blocking);
+        const decision = boardDecision || boardGate(sid, pendingMoves(sess));
+        const v = violations(sess, branchOf(), decision.blocking);
         if (v.length) {
-          console.error("karajan sentinel: git push con el metodo en rojo:\\n" + v.map((x) => "- " + x).join("\\n") + "\\nResuelve antes de empujar. Estado: kj sentinel status" + doc("push-gate"));
+          console.error("karajan sentinel: git push con el metodo en rojo:\\n" + v.map((x) => "- " + x).join("\\n") + (decision.reason ? "\\n(" + decision.reason + ")" : "") + "\\nResuelve antes de empujar. Estado: kj sentinel status" + doc("push-gate"));
           process.exit(2);
         }
       }

package/src/prompts/coder.js

@@ -1,5 +1,5 @@
 import { buildRtkInstructions } from "./rtk-snippet.js";
-import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
+import { roleSkills, buildRoleSkillSection } from "../skills/role-skills.js";
 import { getLanguageInstruction } from "../utils/locale.js";
 import { section, buildPromptLayout, joinLayout, STABLE, VOLATILE } from "./prompt-layout.js";
 
@@ -215,10 +215,10 @@ export async function buildCoderPromptLayout({ task, reviewerFeedback = null, so
 
   const stackRule = buildStackSection({ stack, testFramework });
   const rtkSnippet = buildRtkInstructions({ rtkAvailable });
+  // KJC-TSK-1065: the project's skills and the catalog's for this task, up to 3.
   let skillSection = null;
   if (projectDir) {
-    const skills = await loadAvailableSkills(projectDir);
-    skillSection = buildSkillSection(skills, { provider });
+    skillSection = buildRoleSkillSection(await roleSkills({ role: "coder", task, projectDir }), { provider }) || null;
   }
 
   // Volatile sections keep the legacy relative order — order matters:

package/src/prompts/reviewer.js

@@ -1,5 +1,5 @@
 import { buildRtkInstructions } from "./rtk-snippet.js";
-import { loadAvailableSkills, buildSkillSection } from "../skills/skill-loader.js";
+import { roleSkills, buildRoleSkillSection } from "../skills/role-skills.js";
 import { getLanguageInstruction } from "../utils/locale.js";
 import { section, buildPromptLayout, joinLayout, STABLE, VOLATILE } from "./prompt-layout.js";
 import { clipDiff } from "./diff-clip.js";
@@ -42,10 +42,10 @@ export async function buildReviewerPromptLayout({ task, diff, reviewRules, mode,
 
   const langInstruction = getLanguageInstruction(language);
   const rtkSnippet = buildRtkInstructions({ rtkAvailable });
+  // KJC-TSK-1065: the reviewer gets the skills of its role and of the task, up to 3.
   let skillSection = null;
   if (projectDir) {
-    const skills = await loadAvailableSkills(projectDir);
-    skillSection = buildSkillSection(skills, { provider, role: "reviewer" });
+    skillSection = buildRoleSkillSection(await roleSkills({ role: "reviewer", task, projectDir }), { provider }) || null;
   }
 
   return buildPromptLayout([

package/src/review/board-pending.js

@@ -11,7 +11,9 @@
  * One verifiable fact carries a pending, never a promise in prose: the same card
  * has another OPEN pull request. A branch named after the card is not enough,
  * because the merged branch carries that name too, so accepting it would forgive
- * every merge made from its own lane.
+ * every merge made from its own lane. KJC-BUG-0362 narrows that, never widens
+ * it: the current branch carries only with unmerged commits and when it is not
+ * the merged PR's head.
  */
 
 import { execFileSync } from "node:child_process";
@@ -31,9 +33,24 @@ const cardOf = (text) => {
  *
  * @returns {{blocking: Array<object>, carried: Array<{card: string, why: string}>, reason?: string}}
  */
-export function blockingMoves({ pendings = [], openPrHeads = null, openPrNumbers = [] }) {
+/**
+ * KJC-BUG-0362 (#2199): the next PR of a split card may not exist yet (committed,
+ * not pushed). The branch the session stands on carries the card when it names
+ * that card, holds commits the base does not have, and is NOT the merged PR's
+ * head: the merged lane stays unforgiven, as above.
+ */
+function carriedByLocalBranch(pending, card, localBranch, mergedHeads) {
+  if (!localBranch?.name || !(localBranch.unique > 0)) return null;
+  const mergedHead = mergedHeads[Number(pending.pr)];
+  if (!mergedHead || mergedHead === localBranch.name || cardOf(localBranch.name) !== card) return null;
+  return { card, why: `sigue entregándose en la rama ${localBranch.name}, con ${localBranch.unique} commit(s) sin mergear` };
+}
+
+export function blockingMoves({ pendings = [], openPrHeads = null, openPrNumbers = [], localBranch = null, mergedHeads = {} }) {
   if (pendings.length === 0) return { blocking: [], carried: [] };
-  if (openPrHeads === null) return { blocking: [...pendings], carried: [], reason: "no se pudo comprobar si la card sigue viva en otra PR abierta (gh no respondió) — se bloquea" };
+  // KJC-BUG-0363 (#2201): the guard runs BEFORE the command, so a gh auth switch
+  // inside it has not happened yet, and other sessions move the active account.
+  if (openPrHeads === null) return { blocking: [...pendings], carried: [], reason: "no se pudo comprobar si la card sigue viva en otra PR abierta: gh no pudo listar las PR con la cuenta activa. Si el repo es de otra cuenta, cambiala en un comando aparte (gh auth switch --user <cuenta>) y repite: el guard corre antes que el comando" };
   const openCards = new Set();
   for (const [i, head] of openPrHeads.entries()) {
     // A pending must never forgive itself: the PR it came from is merged, and if
@@ -46,7 +63,9 @@ export function blockingMoves({ pendings = [], openPrHeads = null, openPrNumbers
   for (const p of pendings) {
     const card = p.card ? String(p.card).toUpperCase() : null;
     if (!card) { blocking.push(p); continue; } // nothing to check against
-    if (openCards.has(card)) carried.push({ card, why: "sigue entregándose en una PR abierta" });
+    if (openCards.has(card)) { carried.push({ card, why: "sigue entregándose en una PR abierta" }); continue; }
+    const byBranch = carriedByLocalBranch(p, card, localBranch, mergedHeads);
+    if (byBranch) carried.push(byBranch);
     else blocking.push(p);
   }
   return { blocking, carried };
@@ -60,9 +79,26 @@ export function boardGate({ projectDir = process.cwd(), sessionId = "default", d
   const state = deps.readState?.() ?? readJson(join(projectDir, ".karajan", "harness", "sentinel-state.json"));
   const pendings = state?.sessions?.[sessionId]?.pending_moves;
   if (!Array.isArray(pendings) || pendings.length === 0) return { blocking: [], carried: [] };
-  const run = deps.run ?? ((cmd, args) => execFileSync(cmd, args, { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 }));
+  // KJC-BUG-0364: gh can take several seconds; a timeout reads as "could not check" and blocks.
+  const run = deps.run ?? ((cmd, args) => execFileSync(cmd, args, { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 15000 }));
   let open = null;
   try { open = JSON.parse(run("gh", ["pr", "list", "--state", "open", "--limit", "100", "--json", "number,headRefName"])); } catch { /* fail closed */ }
   const listed = Array.isArray(open) ? open : null;
-  return blockingMoves({ pendings, openPrHeads: listed?.map((p) => p.headRefName) ?? null, openPrNumbers: listed?.map((p) => Number(p.number)) ?? [] });
+  return blockingMoves({ pendings, openPrHeads: listed?.map((p) => p.headRefName) ?? null, openPrNumbers: listed?.map((p) => Number(p.number)) ?? [], ...localFacts(run, pendings) });
+}
+
+/** The current branch, its commits outside the base, and each merged PR's head; unreadable facts forgive nothing. */
+function localFacts(run, pendings) {
+  const facts = { localBranch: null, mergedHeads: {} };
+  try {
+    const name = run("git", ["rev-parse", "--abbrev-ref", "HEAD"]).trim();
+    let base = "origin/main"; // a clone without origin/HEAD measures against origin/main
+    try { base = run("git", ["symbolic-ref", "--short", "refs/remotes/origin/HEAD"]).trim() || base; } catch { /* keep origin/main */ }
+    const unique = Number(run("git", ["rev-list", "--count", `${base}..HEAD`]).trim());
+    if (name && name !== "HEAD" && Number.isInteger(unique)) facts.localBranch = { name, unique };
+  } catch { return facts; }
+  for (const p of pendings) {
+    try { facts.mergedHeads[Number(p.pr)] = JSON.parse(run("gh", ["pr", "view", String(p.pr), "--json", "headRefName"])).headRefName; } catch { /* unknown head: not forgiven */ }
+  }
+  return facts;
 }

package/src/skills/role-skills.js

@@ -0,0 +1,53 @@
+/**
+ * KJC-TSK-1065: the skills kj picks for a role and a task reach the prompt.
+ * Before, the addyosmani catalog was resolved and only written to the journal.
+ * Order: the project's own skills (.agent/skills and friends), then the local
+ * catalog by TASK (a UI task gets frontend-ui-engineering) and by ROLE, up to
+ * MAX_SKILLS; the rest are named, never silently lost. The maintainer's
+ * choices (2026-10-17): local catalog + project skills, 3 per role.
+ */
+import { loadAvailableSkills, filterSkillsForRole } from "./skill-loader.js";
+import { listAvailableSlugs, loadSkillsBySlugs } from "./addyosmani-catalog.js";
+import { resolveAddyosmaniSlugs } from "./addyosmani-role-map.js";
+
+export const MAX_SKILLS = 3;
+
+const defaultDeps = {
+  loadLocal: async (projectDir, role) => {
+    const all = projectDir ? await loadAvailableSkills(projectDir) : [];
+    return role === "coder" ? all : filterSkillsForRole(all, role);
+  },
+  listCatalog: () => listAvailableSlugs(),
+  loadCatalog: (slugs) => loadSkillsBySlugs(slugs),
+};
+
+/** @returns {Promise<{skills: Array<{name: string, content: string, path?: string, catalog?: true}>, dropped: string[]}>} */
+export async function roleSkills({ role, task, projectDir, max = MAX_SKILLS, deps = defaultDeps }) {
+  const local = await deps.loadLocal(projectDir, role);
+  const available = new Set(await deps.listCatalog());
+  const ordered = [...new Set([...resolveAddyosmaniSlugs({ task }), ...resolveAddyosmaniSlugs({ role })])].filter((s) => available.has(s));
+  const room = Math.max(0, max - local.length);
+  const catalog = (await deps.loadCatalog(ordered.slice(0, room))).map((s) => ({ name: s.name, content: s.content, path: s.path, catalog: true }));
+  const dropped = [...local.slice(max).map((s) => s.name), ...ordered.slice(room)];
+  return { skills: [...local.slice(0, max), ...catalog], dropped };
+}
+
+/**
+ * The prompt section. For claude, the project's skills are native to its
+ * runtime, but a catalog skill is not: it is named with the path to read.
+ * Other providers get the content inline.
+ */
+export function buildRoleSkillSection({ skills, dropped }, { provider } = {}) {
+  if (skills.length === 0) return "";
+  const lines = ["## Domain Skills", ""];
+  if (["claude", "anthropic"].includes(String(provider).toLowerCase())) {
+    const native = skills.filter((s) => !s.catalog).map((s) => s.name);
+    if (native.length) lines.push(`Skills available natively via your Agent Skills capability: ${native.join(", ")}.`);
+    const toRead = skills.filter((s) => s.catalog);
+    if (toRead.length) lines.push("Read these skills before you start, and follow them:", ...toRead.map((s) => `- ${s.name}: read ${s.path}`));
+  } else {
+    lines.push("The following domain-specific knowledge is available for this task:", ...skills.map((s) => `### ${s.name}\n${s.content}`));
+  }
+  if (dropped.length) lines.push("", `Left out (limit ${MAX_SKILLS}): ${dropped.join(", ")}`);
+  return lines.join("\n");
+}