karajan-code 4.53.1 → 4.55.0

package/package.json

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

package/src/agents/claude-agent.js

@@ -366,6 +366,9 @@ export class ClaudeAgent extends BaseAgent {
   async _runTaskExec(task, model, _role) {
     const { args, input } = buildPromptArgs(task);
     if (model) args.push("--model", model);
+    // KJC-TSK-1070 (MR-D2): the effort the HU's route gives the coder.
+    const effort = this.config?.roles?.[_role]?.effort;
+    if (effort) args.push("--effort", effort);
     // PL-C (KJC-TSK-0735): el rol del subproceso viaja en KJ_POLICY_ROLE —
     // si su harness corre hooks (claude -p), el tier A evalúa la policy con
     // el rol que ACTÚA. El rol del ORQUESTADOR es autoritativo: task.env no

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/commands/plan/generate.js

@@ -9,7 +9,7 @@ import { promptProjectName } from "../../utils/prompt-project-name.js";
 import { deriveProjectNameFromCwd } from "../../utils/derive-project-name-from-cwd.js";
 import { applyReviewerFeedback, applyFixerPatch, patchChanged } from "../../plan/plan-fixer.js";
 import { runStructuralPass } from "../../plan/plan-structural-pass.js";
-import { recommendModelsForHu, complexityFromTaskType } from "../../hu/model-router.js";
+import { planHuModels } from "../../hu/model-router.js";
 import { withBrainRecovery } from "../../brain/with-brain-recovery.js";
 import { buildStandbyState } from "../../brain/standby-store.js";
 import { printResumeHint } from "../../utils/display/resume-hint.js";
@@ -206,16 +206,15 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
     const symbolicId = typeof step === "object" && typeof step.id === "string" && step.id.trim()
       ? step.id.trim() : null;
     const taskType = classifyTaskType(desc);
-    // KJC-TSK-0405 step 2: asigna coder_model + reviewer_model
-    // automáticamente según complexity inferido del task_type. El
-    // planner puede emitir `step.complexity` (trivial/simple/medium/complex
-    // o score 1-5) para override más fino. Cross-provider reviewer
-    // (claude↔codex) por defecto.
-    const coderProvider = config?.roles?.coder?.provider || config?.coder || "claude";
-    const complexity = (typeof step === "object" && step.complexity)
-      ? step.complexity
-      : complexityFromTaskType(taskType);
-    const models = recommendModelsForHu({ complexity, coderProvider, config });
+    // KJC-TSK-1072 (MR-D4): coder_model comes from the HU's tier (MR-A), the
+    // criterion the run uses; the board can change it. Cross-provider reviewer.
+    const models = planHuModels({
+      title: desc, goal: desc,
+      acceptanceCriteria: tests.map((t) => (typeof t === "object" ? String(t.content ?? "") : String(t))),
+      tier: typeof step === "object" ? step.tier ?? null : null,
+      tierReason: typeof step === "object" ? step.tierReason ?? null : null,
+      config: config ?? {},
+    });
     const hu = addHu(plan, {
       title: desc.slice(0, 80),
       task_type: taskType,
@@ -232,6 +231,8 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
     // KJC-TSK-0661: provenance stamp (addHu builds its object explicitly,
     // so this goes on the returned reference, not in huData).
     hu.created_by = "planner";
+    // KJC-TSK-1072: the tier rides on the HU, so the run gives its coder the tier's effort.
+    hu.complexity = models.complexity;
     // KJC-TSK-1061: the classification travels to the HU; validatePlan judges it (KJC-TSK-0717).
     for (const key of ["change_class", "change_criterion", "hardens"]) {
       const value = typeof step === "object" ? step[key] : null;

package/src/config/defaults.js

@@ -134,6 +134,8 @@ const DEFAULTS = {
   },
   sonarqube: {
     enabled: true,
+    // KJC-BUG-0368 (#2216): sonar-scanner runs this many reviews at once per machine.
+    max_parallel_scans: 2,
     host: "http://localhost:9000",
     external: false,
     container_name: "karajan-sonarqube",

package/src/config/schema.js

@@ -208,6 +208,8 @@ const Skills = v.optional(v.looseObject({
  *     forzar Sonnet en todo el proyecto, por ejemplo.
  */
 const ModelRouting = v.optional(v.looseObject({
+  // KJC-TSK-0701 (MR-D): the coder of each HU runs on its tier's model; false turns it off.
+  enabled: v.optional(v.boolean("model_routing.enabled must be true or false")),
   by_provider: v.optional(v.record(
     v.string(),
     v.looseObject({
@@ -257,6 +259,10 @@ export const ConfigSchema = v.looseObject({
     every_commits: v.optional(PositiveInt),
   })),
   coder_rules: v.optional(v.string()),
+  // KJC-BUG-0368 (#2216): how many sonar-scanner reviews run at once per machine.
+  sonarqube: v.optional(v.looseObject({
+    max_parallel_scans: v.optional(PositiveInt),
+  })),
   base_branch: v.optional(v.string()),
   coder_options: CoderOptions,
   reviewer_options: ReviewerOptions,

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

@@ -145,10 +145,12 @@ export const stripInertQuotes = (cmd) => {
 
 // Options whose value is prose, never a path (gh, git, kj).
 // KJC-BUG-0306: --error and --command of kj report-issue, --scope and --tests of kj hu add.
-const TEXT_OPTIONS = new Set(["--title", "--body", "--message", "-m", "--notes", "--description", "--ac", "--criteria", "--reason", "--decision", "--context", "--consequences", "--position", "--error", "--command", "--scope", "--tests"]);
+// KJC-BUG-0366: --why of kj handoff add.
+const TEXT_OPTIONS = new Set(["--title", "--body", "--message", "-m", "--notes", "--description", "--ac", "--criteria", "--reason", "--decision", "--context", "--consequences", "--position", "--error", "--command", "--scope", "--tests", "--why"]);
 const QUOTED_OPTION_VALUE = /(^|\s)(--?[a-z]+)(=|\s+)("[^"$`\\]*"|'[^']*')/g;
 // KJC-BUG-0306: the title kj hu add and kj adr add take as their first argument, at the start of a segment.
-const KJ_TITLE = /(^|[;&|]\s*)(kj\s+(?:hu|adr)\s+add\s+)("[^"$`\\]*"|'[^']*')/g;
+// KJC-BUG-0366: and the command kj handoff add stores for the human.
+const KJ_TITLE = /(^|[;&|]\s*)(kj\s+(?:hu|adr|handoff)\s+add\s+)("[^"$`\\]*"|'[^']*')/g;
 
 /** KJC-BUG-0243: blank the inert quoted value of a text option (--title "a/b c"): prose, not a path. */
 export const stripTextOptionValues = (cmd) => cmd
@@ -171,7 +173,7 @@ const isGitCommit = (words) => {
   return words[0] === "git" && words[i] === "commit";
 };
 
-const isTextOnlyHead = (seg) => /^kj\s+(?:hu|adr)\s+add\b/.test(seg) || isGitCommit(seg.split(/\s+/));
+const isTextOnlyHead = (seg) => /^kj\s+(?:hu|adr|handoff)\s+add\b/.test(seg) || isGitCommit(seg.split(/\s+/));
 
 /**
  * KJC-BUG-0354: blank the quoted text values (stripTextOptionValues) only when the

package/src/harden/sentinel-hooks.js

@@ -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))) {
@@ -812,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

package/src/hu/coder-routing.js

@@ -0,0 +1,66 @@
+/**
+ * KJC-TSK-0701 (MR-D): the model and effort the coder of an HU runs on. Its
+ * tier (MR-A) picks them on the first iteration; after a failed one the coder
+ * climbs to the most capable model. A model the user chose always wins, the
+ * reviewer and Solomon are never routed, and model_routing.enabled: false turns
+ * it off; model_routing.by_provider picks other models per level.
+ */
+import { getDefaultModelTiers, resolveModelForRole } from "../utils/model-selector.js";
+
+const TIER_ROUTE = { trivial: { level: "trivial", effort: "low" }, standard: { level: "medium", effort: "medium" } };
+const ESCALATED = { level: "complex", effort: "max" };
+// Only claude's CLI takes --effort.
+const EFFORT_PROVIDERS = new Set(["claude"]);
+
+const userChoice = (config) => {
+  if (config.model_routing?.enabled === false) return "model_routing.enabled is false";
+  if (config.model_routing?.fixed?.coder) return `model_routing.fixed.coder is ${config.model_routing.fixed.coder}`;
+  if (config.roles?.coder?.model) return `the coder model was chosen (${config.roles.coder.model})`;
+  if (config.coder_options?.model) return `the coder model was chosen (${config.coder_options.model})`;
+  if (config.model_profile) return `the model profile ${config.model_profile} was chosen`;
+  return null;
+};
+
+const routed = ({ model, effort, escalated, why }) => ({ skip: false, model, effort, escalated, reason: `${why} -> ${model}${effort ? ` (effort ${effort})` : ""}` });
+
+/**
+ * KJC-TSK-1070: huModel is the HU's coder_model (kj plan fills it from the
+ * tier, the user may change it on the board); it drives the first iteration.
+ * @param {{ tier?: string, huModel?: string|null, attempt: number, config: object }} args
+ * @returns {{ skip: true, reason: string } | { skip: false, model: string, effort: string|null, escalated: boolean, reason: string }}
+ */
+export function routeCoder({ tier, huModel = null, attempt, config }) {
+  const chosen = userChoice(config);
+  if (chosen) return { skip: true, reason: chosen };
+  const provider = config.roles?.coder?.provider || config.coder;
+  const effortOf = (route) => (EFFORT_PROVIDERS.has(provider) ? route?.effort ?? null : null);
+  const escalated = attempt > 1;
+  if (!escalated && huModel) return routed({ model: huModel, effort: effortOf(TIER_ROUTE[tier]), escalated, why: "the HU's coder_model" });
+  const route = escalated ? ESCALATED : TIER_ROUTE[tier];
+  if (!route) return { skip: true, reason: tier === "deep" ? "deep HU: the usual model and effort" : `no tier to route by (${tier ?? "none"})` };
+  const tierMap = getDefaultModelTiers();
+  for (const [name, levels] of Object.entries(config.model_routing?.by_provider ?? {})) tierMap[name] = { ...tierMap[name], ...levels };
+  const model = resolveModelForRole({ role: "coder", provider, level: route.level, tierMap });
+  if (!model) return { skip: true, reason: `${provider} has no known model for the ${route.level} level` };
+  const why = escalated ? `iteration ${attempt} after a failed one: the most capable model` : `${tier} HU`;
+  return routed({ model, effort: effortOf(route), escalated, why });
+}
+
+/**
+ * KJC-TSK-1070: the route of an HU's coder for this attempt, on its lane
+ * config (coder_route, read by the coder stage); a skipped route clears it.
+ */
+export function applyCoderRoute({ laneConfig, story, attempt, config, logger }) {
+  const route = routeCoder({ tier: story.complexity?.tier, huModel: story.coder_model || null, attempt, config });
+  laneConfig.coder_route = route.skip ? null : { model: route.model, effort: route.effort };
+  // KJC-TSK-1071 (MR-D3): the HU keeps its last decision, and whether it ever climbed.
+  story.coder_routing = {
+    tier: story.complexity?.tier ?? null,
+    model: route.skip ? null : route.model,
+    effort: route.skip ? null : route.effort,
+    escalated: Boolean(story.coder_routing?.escalated || route.escalated),
+    reason: route.reason,
+  };
+  logger.info(`HU ${story.id}: coder ${route.skip ? "not routed" : "routed"}: ${route.reason}`);
+  return route;
+}

package/src/hu/model-router.js

@@ -1,4 +1,6 @@
 import { getDefaultModelTiers } from "../utils/model-selector.js";
+import { huComplexity } from "./complexity-tier.js";
+import { routeCoder } from "./coder-routing.js";
 
 // KJC-TSK-0405: dado un HU con complexity score, recomienda coder_model y
 // reviewer_model. El reviewer por defecto usa el provider alternativo al
@@ -35,26 +37,6 @@ const CROSS_PROVIDER_REVIEWER = {
   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];
@@ -97,3 +79,19 @@ export function recommendModelsForHu({ complexity, coderProvider, config = {} })
     reviewer_provider,
   };
 }
+
+const TIER_LEVEL = { trivial: "trivial", standard: "medium", deep: "complex" };
+
+/**
+ * KJC-TSK-1072 (MR-D4): the models kj plan writes on an HU. coder_model comes
+ * from the HU's tier (MR-A) through routeCoder, the criterion the run uses;
+ * empty for a deep HU or a model the config already chose. The reviewer keeps
+ * its cross-provider recommendation. The tier travels as `complexity`.
+ */
+export function planHuModels({ title = "", goal = "", acceptanceCriteria = [], tier = null, tierReason = null, config = {} }) {
+  const complexity = huComplexity({ title, goal, acceptanceCriteria, tier, tierReason });
+  const coderProvider = config.roles?.coder?.provider || config.coder || "claude";
+  const route = routeCoder({ tier: complexity.tier, attempt: 1, config });
+  const reviewer = recommendModelsForHu({ complexity: TIER_LEVEL[complexity.tier], coderProvider, config });
+  return { ...reviewer, coder_model: route.skip ? null : route.model, complexity };
+}

package/src/hu/routing-metrics.js

@@ -4,7 +4,8 @@
  * fixed set of fields, so the measured ones are kept here, in the plan, where
  * kj report reads them. Unmeasured fields stay out rather than written as null.
  */
-export const ROUTING_FIELDS = ["cost_usd", "tokens_in", "tokens_out", "cached_tokens", "coder", "reviewer_rejections"];
+// KJC-TSK-1071 (MR-D3): coder_routing is the coder's routing decision for the HU.
+export const ROUTING_FIELDS = ["cost_usd", "tokens_in", "tokens_out", "cached_tokens", "coder", "reviewer_rejections", "coder_routing"];
 
 export function keepRoutingMetrics(plan, huId, outcome) {
   const hu = plan?.hus?.find((h) => h.id === huId);

package/src/orchestrator/drivers/iteration-loop.js

@@ -210,6 +210,8 @@ export async function runIterationLoop(ctx, { task: loopTask, askQuestion, emitt
 
     ctx.eventBase.iteration = i;
     ctx.iteration = i;
+    // KJC-TSK-1070 (MR-D2): an HU lane picks its coder's route per iteration.
+    ctx.beforeIteration?.(i);
 
     let iterResult;
     try {

package/src/orchestrator/drivers/run-hu-batch.js

@@ -36,6 +36,7 @@ import { createHuSnapshot } from "../../git/hu-snapshot.js";
 import { generateDiff } from "../../review/diff-generator.js";
 import { runAcceptanceCoverageStage } from "../stages/acceptance-coverage-stage.js";
 import { criteriaOfCard } from "../../roles/acceptance-coverage-role.js";
+import { applyCoderRoute } from "../../hu/coder-routing.js";
 
 /**
  * @param {object} args
@@ -180,6 +181,7 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
 
         for (let attempt = 1; attempt <= laneConfig.max_iterations; attempt++) {
           logger.info(`HU ${story.id}: coder iteration ${attempt}/${laneConfig.max_iterations}`);
+          applyCoderRoute({ laneConfig, story, attempt, config: ctx.config, logger });
           emitProgress(emitter, makeEvent("iteration:start", { ...ctx.eventBase, stage: "iteration" }, {
             message: `Iteration ${attempt}/${laneConfig.max_iterations}`,
             detail: { iteration: attempt, maxIterations: laneConfig.max_iterations }
@@ -386,7 +388,8 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
       // Fallback: no acceptance_tests → standard pipeline (reviewer/tester).
       // The loop reads everything through ctx.* — handing it a lane view
       // keeps the shared ctx untouched (no more mutate-and-restore dance).
-      const laneCtx = { ...ctx, config: laneConfig, pipelineFlags: laneFlags, session: laneSession, brainCtx: laneBrain, plannedTask: lanePlannedTask };
+      const laneCtx = { ...ctx, config: laneConfig, pipelineFlags: laneFlags, session: laneSession, brainCtx: laneBrain, plannedTask: lanePlannedTask,
+        beforeIteration: (attempt) => applyCoderRoute({ laneConfig, story, attempt, config: ctx.config, logger }) };
       const result = await runIterationLoop(laneCtx, { task: huTask, askQuestion, emitter, logger });
       if (result?.approved) {
         // KJC-BUG-0248: what the HU's push or PR said joins what the loop recorded.

package/src/orchestrator/hu-sub-pipeline.js

@@ -156,7 +156,7 @@ function sumTokenField(entries, field) {
  *   entries recorded during this HU. Cost D (KJC-TSK-0515).
  * @returns {object}
  */
-function buildHuOutcome({ story: _story, iterResult, status, startedAt, huBudgetEntries }) {
+function buildHuOutcome({ story, iterResult, status, startedAt, huBudgetEntries }) {
   const r = iterResult || {};
   const git = r.git || {};
   // Iterations are tracked in the standard pipeline as
@@ -198,6 +198,8 @@ function buildHuOutcome({ story: _story, iterResult, status, startedAt, huBudget
     // KJC-TSK-0702 (MR-E): the baseline model routing is measured against.
     tokens_out: sumTokenField(huBudgetEntries, 'tokens_out'),
     ...routingBaseline(huBudgetEntries, status),
+    // KJC-TSK-1071 (MR-D3): the routing decision applyCoderRoute left on the HU.
+    coder_routing: story?.coder_routing ?? null,
     finishedAt: new Date().toISOString(),
   };
 }

package/src/orchestrator/stages/coder-stage.js

@@ -79,6 +79,8 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
       // PAR-H (KJC-TSK-0631): lane env (KJ_LANE_SLOT / KJ_PORT_OFFSET)
       // reaches the coder subprocess so services it starts don't collide.
       env: config?.lane_env || null,
+      // KJC-TSK-1070 (MR-D2): the model and effort of this HU's coder.
+      route: config?.coder_route || null,
       onOutput: coderStall.onOutput,
       // Lets Brain Recovery persist a standby snapshot if the coder's
       // provider hits a quota cap mid-run (KJC hibernation wiring).
@@ -87,7 +89,8 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
   } finally {
     coderStall.stop();
   }
-  trackBudget({ role: "coder", provider: coderRole.provider, model: coderRole.model, result: coderExecResult.result, duration_ms: Date.now() - coderStart });
+  // KJC-TSK-1071 (MR-D3): the model the HU's route ran the coder on, so kj report measures the real one.
+  trackBudget({ role: "coder", provider: coderRole.provider, model: config?.coder_route?.model ?? coderRole.model, result: coderExecResult.result, duration_ms: Date.now() - coderStart });
   applyQuotaSimulation(coderExecResult, { iteration, agent: coderRole.provider });
   // KJC-BUG-0285 (#1982): a commit the coder made on its own carried the error the
   // reviewer then rejected, and stayed on the branch. Undone softly: the changes

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([
@@ -54,6 +54,8 @@ export async function buildReviewerPromptLayout({ task, diff, reviewRules, mode,
     section(`You are a code reviewer in ${mode} mode.`, STABLE),
     section("CRITICAL SCOPE RULE: Only review changes that are part of the diff below. Do NOT flag issues in unchanged code, missing features planned for future tasks, or improvements outside the scope of this task. If the diff is correct for what the task asks, approve it — even if the broader codebase has other issues.", STABLE),
     section("Only block approval for issues IN THE DIFF that are bugs, security vulnerabilities, or clear violations of the review rules.", STABLE),
+    // KJC-BUG-0369 (#2196): a reviewer blocked GitHub's on.schedule timezone, which exists.
+    section("A claim that a tool, platform or API does not support something the diff uses is not a blocking issue on its own: your training data may predate the feature. Block only when the diff or the task context shows it fails; otherwise put it in non_blocking_suggestions.", STABLE),
     section("Return only one valid JSON object and nothing else.", STABLE),
     section("JSON schema:", STABLE),
     section('{"approved":boolean,"blocking_issues":[{"id":string,"severity":"critical|high|medium|low","category":"security|correctness|performance|style|other","file":string,"line":number,"description":string,"suggested_fix":string}],"non_blocking_suggestions":[string],"summary":string,"confidence":number}', STABLE),

package/src/report/model-tally.js

@@ -23,11 +23,14 @@ export function modelTally(hus) {
       failure_rate: round(failed / rows.length, 4),
     };
   });
-  return { models, unmeasured: (hus ?? []).length - measured.length };
+  // KJC-TSK-1071 (MR-D3): how many HUs routing moved off the usual model, and how many climbed.
+  const routed = (hus ?? []).filter((h) => h?.outcome?.coder_routing?.model);
+  const routing = { routed: routed.length, escalated: routed.filter((h) => h.outcome.coder_routing.escalated).length };
+  return { models, unmeasured: (hus ?? []).length - measured.length, routing };
 }
 
 /** The kj report block, or null when no HU was run at all. */
-export function formatModelTally({ models, unmeasured }) {
+export function formatModelTally({ models, unmeasured, routing = null }) {
   if (models.length === 0 && unmeasured === 0) return null;
   const lines = ["Coder models (per HU, from the plans):"];
   for (const m of models) {
@@ -35,5 +38,6 @@ export function formatModelTally({ models, unmeasured }) {
     lines.push(`  ${m.model.padEnd(24)} ${m.hus} HU · $${m.cost_usd.toFixed(4)} · ${m.tokens_in} in / ${m.tokens_out} out · ${iterations} iter · ${Math.round(m.failure_rate * 100)}% failed first time`);
   }
   if (unmeasured > 0) lines.push(`  ${unmeasured} HU(s) before the measurement (baseline, unmeasured)`);
+  if (routing?.routed) lines.push(`  Routing: ${routing.routed} HU routed, ${routing.escalated} climbed to the top model (model_routing.enabled: false turns it off)`);
   return lines.join("\n");
 }

package/src/review/sonar-pregate.js

@@ -14,6 +14,8 @@ import { dirname, join } from "node:path";
 import { indexedFilesFrom, runSonarScan } from "../sonar/scanner.js";
 import { getOpenIssues } from "../sonar/api.js";
 import { acquireToolLock } from "../utils/tool-governor.js";
+
+const DEFAULT_SCAN_SLOTS = 2;
 import { sourceFilesOf } from "./tests-with-code.js";
 
 const BLOCKING_SEVERITIES = new Set(["BLOCKER", "CRITICAL"]);
@@ -84,9 +86,14 @@ export async function runSonarPregate({ config, stagedFiles = [], touchedLines =
   if (config?.review_gate?.sonar === false) {
     return { available: false, reason: "disabled in config (review_gate.sonar: false)" };
   }
+  // KJC-BUG-0368 (#2216): concurrent reviews on one machine share the scanner slots.
+  const slots = config?.sonarqube?.max_parallel_scans ?? DEFAULT_SCAN_SLOTS;
+  if (!Number.isInteger(slots) || slots < 1) {
+    return { available: false, reason: `sonarqube.max_parallel_scans must be a positive integer (got ${JSON.stringify(slots)})` };
+  }
   let lock = null;
   try {
-    lock = await acquireToolLock("sonar-scanner", { timeoutMs: 300_000 });
+    lock = await acquireToolLock("sonar-scanner", { timeoutMs: 300_000, slots });
     const groups = groupByScanRoot(stagedFiles, { exists });
     if (groups.size === 0) groups.set("", []);
     const indexed = new Set();

package/src/roles/agent-role.js

@@ -121,7 +121,7 @@ export class AgentRole extends BaseRole {
   async execute(input) {
     const extracted = this.extractInput(input);
     const provider = this.resolveProvider();
-    const agent = this.createAgentInstance(provider);
+    const agent = this.createAgentInstance(provider, extracted);
 
     const promptResult = await this.buildPrompt(extracted);
     const { prompt, onOutput, stablePrompt, volatilePrompt } = typeof promptResult === "string"

package/src/roles/coder-role.js

@@ -16,7 +16,11 @@ export class CoderRole extends AgentRole {
     return this.config?.roles?.coder?.provider || this.config?.coder || "claude";
   }
 
-  createAgentInstance(provider) {
+  createAgentInstance(provider, input = {}) {
+    // KJC-TSK-1070 (MR-D2): the HU's route rides on this call only; the shared
+    // role keeps its own config (lanes run in parallel).
+    const route = input?.route;
+    const config = route ? { ...this.config, roles: { ...this.config?.roles, coder: { ...this.config?.roles?.coder, model: route.model, effort: route.effort } } } : this.config;
     // KJC-BUG-0129 (issues #1301/#1303): running INSIDE an agent does not
     // make it "the host executor" — delegating sent the full instruction
     // prompt through elicitInput as a hanging board "question". A CLI
@@ -29,7 +33,7 @@ export class CoderRole extends AgentRole {
       }
       this.logger.info(`Running inside ${provider} — spawning it as a subprocess anyway (set roles.coder.host_delegation: true to delegate to the host)`);
     }
-    return this._createAgent(provider, this.config, this.logger);
+    return this._createAgent(provider, config, this.logger);
   }
 
   extractInput(input) {
@@ -66,6 +70,8 @@ export class CoderRole extends AgentRole {
       projectDir: input?.projectDir || null,
       // PAR-H (KJC-TSK-0631): per-call subprocess env (lane slot vars).
       env: input?.env || null,
+      // KJC-TSK-1070: the model and effort this HU's coder runs on.
+      route: input?.route || null,
       onOutput: input?.onOutput || null
     };
   }

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");
+}

package/src/utils/tool-governor.js

@@ -28,35 +28,50 @@ function isPidAlive(pid) {
   }
 }
 
-/** Machine-wide lock for `tool` → {release}; ELOCKTIMEOUT if the live holder outlasts `timeoutMs`. */
-export async function acquireToolLock(tool, { locksDir = DEFAULT_LOCKS_DIR, timeoutMs = 180_000, pollMs = 500 } = {}) {
-  fs.mkdirSync(locksDir, { recursive: true });
-  const lockPath = path.join(locksDir, `${tool}.lock`);
-  const deadline = Date.now() + timeoutMs;
+/** One slot: {release} when taken, else the live holder; a dead or unreadable holder is stolen. */
+function tryTakeSlot(lockPath) {
   for (;;) {
     try {
       // wx = atomic create-or-fail: the filesystem is the arbiter.
       const fd = fs.openSync(lockPath, "wx");
       fs.writeSync(fd, JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }));
       fs.closeSync(fd);
-      return { release: () => fs.rmSync(lockPath, { force: true }) };
+      return { lock: { release: () => fs.rmSync(lockPath, { force: true }) } };
     } catch (err) {
       if (err.code !== "EEXIST") throw err;
       let holder = null;
       try {
         holder = JSON.parse(fs.readFileSync(lockPath, "utf8"));
       } catch { /* unreadable → stale */ }
-      if (!holder || !Number.isInteger(holder.pid) || !isPidAlive(holder.pid)) {
-        fs.rmSync(lockPath, { force: true });
-        continue;
-      }
-      if (Date.now() >= deadline) {
-        const e = new Error(`${tool} is already running (pid ${holder.pid}, since ${holder.startedAt}) — gave up waiting after ${timeoutMs}ms`);
-        e.code = "ELOCKTIMEOUT";
-        throw e;
-      }
-      await new Promise((r) => setTimeout(r, pollMs));
+      if (holder && Number.isInteger(holder.pid) && isPidAlive(holder.pid)) return { holder };
+      fs.rmSync(lockPath, { force: true });
+    }
+  }
+}
+
+/**
+ * Machine-wide lock for `tool` → {release}; ELOCKTIMEOUT if every live holder
+ * outlasts `timeoutMs`. KJC-BUG-0368 (#2216): `slots` lets that many run at
+ * once (slot 0 keeps the single-lock path `<tool>.lock`).
+ */
+export async function acquireToolLock(tool, { locksDir = DEFAULT_LOCKS_DIR, timeoutMs = 180_000, pollMs = 500, slots = 1 } = {}) {
+  fs.mkdirSync(locksDir, { recursive: true });
+  const paths = Array.from({ length: Math.max(1, slots) }, (_, n) => path.join(locksDir, n === 0 ? `${tool}.lock` : `${tool}.${n}.lock`));
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    let holder = null;
+    for (const lockPath of paths) {
+      const slot = tryTakeSlot(lockPath);
+      if (slot.lock) return slot.lock;
+      holder ??= slot.holder;
+    }
+    if (Date.now() >= deadline) {
+      const busy = paths.length > 1 ? `, all ${paths.length} slots busy` : "";
+      const e = new Error(`${tool} is already running (pid ${holder.pid}, since ${holder.startedAt}${busy}) — gave up waiting after ${timeoutMs}ms`);
+      e.code = "ELOCKTIMEOUT";
+      throw e;
     }
+    await new Promise((r) => setTimeout(r, pollMs));
   }
 }