karajan-code 4.28.2 → 4.29.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.28.2",
+  "version": "4.29.1",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -112,7 +112,7 @@
     "express-rate-limit": "^8.5.0",
     "helmet": "^8.1.0",
     "js-yaml": "^4.2.0",
-    "karajan-core": "^1.4.0",
+    "karajan-core": "^1.5.0",
     "karajan-rag": "^1.2.0",
     "knip": "^6.15.0",
     "madge": "^8.0.0",

package/scripts/postinstall.js

@@ -27,12 +27,28 @@ async function writeJson(file, obj) {
   await fs.writeFile(file, `${JSON.stringify(obj, null, 2)}\n`, "utf8");
 }
 
-function resolveKjHome() {
-  if (process.env.KJ_HOME) return process.env.KJ_HOME;
-  return path.join(ROOT_DIR, ".karajan");
+const CLAUDE_JSON_PATH = path.join(os.homedir(), ".claude.json");
+
+// KJC-BUG-0179 (#1730): a home INSIDE the npm package is the old default
+// this script wrote itself — wiped on every reinstall, never where `kj init`
+// stores kj.config.yml. Such a value is stale, not a user choice.
+const isPackageDirHome = (home) => /node_modules[\\/]karajan-code[\\/]\.karajan[\\/]?$/.test(home);
+
+/** The home a previous registration carried, if the user (not this script) set it. */
+function homeFromExistingEntry(entry) {
+  const previous = entry?.env?.KARAJAN_HOME || entry?.env?.KJ_HOME;
+  return previous && !isPackageDirHome(previous) ? previous : null;
 }
 
-async function resolveKjHomeFromRegistry() {
+/**
+ * Precedence: KARAJAN_HOME → KJ_HOME (deprecated) → the existing entry's home
+ * → the instances registry → `~/.karajan` (where the CLI defaults, KJC-BUG-0179).
+ */
+async function resolveKjHome(existingEntry) {
+  if (process.env.KARAJAN_HOME) return process.env.KARAJAN_HOME;
+  if (process.env.KJ_HOME) return process.env.KJ_HOME;
+  const previous = homeFromExistingEntry(existingEntry);
+  if (previous) return previous;
   try {
     const registry = await readJson(REGISTRY_PATH);
     const names = Object.keys(registry.instances || {});
@@ -43,28 +59,31 @@ async function resolveKjHomeFromRegistry() {
   } catch {
     // No registry yet — use default
   }
-  return resolveKjHome();
+  return path.join(os.homedir(), ".karajan");
 }
 
-async function setupClaudeMcp(kjHome) {
-  const claudeJsonPath = path.join(os.homedir(), ".claude.json");
-  let config = {};
+async function readClaudeConfig() {
   try {
-    config = await readJson(claudeJsonPath);
+    return await readJson(CLAUDE_JSON_PATH);
   } catch {
-    config = {};
+    return {};
   }
+}
 
+async function setupClaudeMcp(config, kjHome) {
   config.mcpServers = config.mcpServers || {};
+  // Keep every env key the user added to the entry; only the home is ours,
+  // and it is written under the current name (KJ_HOME is deprecated).
+  const { KJ_HOME: _stale, ...userEnv } = config.mcpServers["karajan-mcp"]?.env || {};
   config.mcpServers["karajan-mcp"] = {
     type: "stdio",
     command: "node",
     args: [path.join(ROOT_DIR, "src", "mcp", "server.js")],
     cwd: ROOT_DIR,
-    env: { KJ_HOME: kjHome }
+    env: { ...userEnv, KARAJAN_HOME: kjHome }
   };
 
-  await writeJson(claudeJsonPath, config);
+  await writeJson(CLAUDE_JSON_PATH, config);
 }
 
 function upsertCodexMcpBlock(toml, block) {
@@ -96,7 +115,7 @@ async function setupCodexMcp(kjHome) {
     `args = [${tomlPath(path.join(ROOT_DIR, "src", "mcp", "server.js"))}]`,
     `cwd = ${tomlPath(ROOT_DIR)}`,
     '[mcp_servers."karajan-mcp".env]',
-    `KJ_HOME = ${tomlPath(kjHome)}`
+    `KARAJAN_HOME = ${tomlPath(kjHome)}`
   ].join("\n");
 
   const updated = upsertCodexMcpBlock(toml, block);
@@ -105,9 +124,10 @@ async function setupCodexMcp(kjHome) {
 }
 
 async function main() {
-  const kjHome = await resolveKjHomeFromRegistry();
+  const claudeConfig = await readClaudeConfig();
+  const kjHome = await resolveKjHome(claudeConfig.mcpServers?.["karajan-mcp"]);
 
-  await setupClaudeMcp(kjHome);
+  await setupClaudeMcp(claudeConfig, kjHome);
   await setupCodexMcp(kjHome);
 
   console.log("karajan-mcp registered in Claude Code and Codex.");

package/src/checks/method.js

@@ -39,16 +39,44 @@ export async function collectMethodStats({ projectDir, run = runCommand, sample
 
   const verdicts = recentVerdicts(projectDir, sample);
   const stamped = verdicts.filter((v) => v.workspace);
+  const sonar = { proved: 0, docsOnly: 0, granted: 0, unproved: 0 };
+  for (const v of verdicts) {
+    const kind = sonarProof(v);
+    if (kind) sonar[kind] += 1;
+  }
 
   return {
     commits: { total: subjects.length, withCard: subjects.filter((s) => CARD_REF_RE.test(s)).length },
     verdicts: { total: verdicts.length, stamped: stamped.length, root: stamped.filter((v) => v.workspace === "root").length },
     testless: { sampled: blocks.length, offenders },
+    sonar,
   };
 }
 
+/**
+ * KJC-TSK-0838 (ADR 2026-09-13): what a verdict's sonar block proves —
+ * "proved" (ran and covered every source), "docsOnly", "granted" (a human
+ * lifted the rule) or "unproved" (an approved verdict for code with no
+ * analysis, a skipped pipeline stage, or a source the scan never saw).
+ * A verdict without a block predates the ADR and counts as nothing.
+ */
+export function sonarProof(v) {
+  const s = v?.sonar;
+  if (!s || v.verdict !== "approved") return null;
+  // A pipeline stamp has no mode: the stage ran, or it did not.
+  if (s.source === "pipeline") return s.ran ? "proved" : "unproved";
+  // A block without a mode was written before the requirement existed
+  // (the block landed one PR before fail-closed): not retroactive either.
+  if (!s.mode) return null;
+  if (s.mode === "docs-only") return "docsOnly";
+  if (s.mode === "granted") return "granted";
+  if (s.ran && (s.uncovered || []).length === 0) return "proved";
+  return "unproved";
+}
+
 export function formatMethodStats(s) {
-  return `commits with card ref ${s.commits.withCard}/${s.commits.total} · verdict workspaces root ${s.verdicts.root}/${s.verdicts.stamped || 0} stamped (${s.verdicts.total} total) · source commits without tests ${s.testless.offenders}/${s.testless.sampled}`;
+  const sonar = s.sonar ? ` · sonar proof: ${s.sonar.proved} proved, ${s.sonar.docsOnly} docs-only, ${s.sonar.granted} granted, ${s.sonar.unproved} unproved` : "";
+  return `commits with card ref ${s.commits.withCard}/${s.commits.total} · verdict workspaces root ${s.verdicts.root}/${s.verdicts.stamped || 0} stamped (${s.verdicts.total} total) · source commits without tests ${s.testless.offenders}/${s.testless.sampled}${sonar}`;
 }
 
 function createMethodCheck() {
@@ -59,6 +87,11 @@ function createMethodCheck() {
     async detect({ config = {}, projectDir = process.cwd(), run = runCommand } = {}) {
       const stats = await collectMethodStats({ projectDir, run, sample: config.method_gates?.report_sample || 20 });
       const detail = formatMethodStats(stats);
+      // KJC-TSK-0838: an approved verdict for code without sonar proof is the
+      // method in red, not a trend — the gate should have refused it.
+      if (stats.sonar.unproved > 0) {
+        return { ok: false, severity: "fail", detail: `${stats.sonar.unproved} approved verdict(s) without sonar proof — ${detail}` };
+      }
       const drought = stats.commits.total >= 5 && stats.commits.withCard / stats.commits.total < 0.5;
       if (drought) {
         return { ok: false, severity: "warn", detail: `most recent commits carry no card reference — ${detail}` };

package/src/checks/sonar.js

@@ -11,11 +11,11 @@ import { isSonarReachable } from "../sonar/manager.js";
 import { STRATEGY } from "./types.js";
 import { withDocLink } from "../utils/doc-links.js";
 
-/**
- * Whether Sonar is enabled in the active config.
- */
-function sonarEnabled(config) {
-  return config.sonarqube?.enabled !== false;
+/** Which config switch turns Sonar off, or null when none does. */
+function disabledSwitch(config) {
+  if (config.sonarqube?.enabled === false) return "sonarqube.enabled: false";
+  if (config.review_gate?.sonar === false) return "review_gate.sonar: false";
+  return null;
 }
 
 function sonarHost(config) {
@@ -33,8 +33,17 @@ function createSonarStatusCheck() {
     strategy: STRATEGY.NONE,
     async detect({ config }) {
       const host = sonarHost(config);
-      if (!sonarEnabled(config)) {
-        return { ok: true, severity: "info", detail: "Disabled in config" };
+      // KJC-TSK-0838 (ADR 2026-09-13): Sonar switched off is a DEFECT, not a
+      // preference — the commit gate rejects code diffs without a sonar
+      // proof, so this config only hurts. Only docs-only diffs are exempt.
+      const off = disabledSwitch(config);
+      if (off) {
+        return {
+          ok: false,
+          severity: "fail",
+          detail: `Disabled in config (${off}) — Sonar is mandatory for code; the commit gate rejects code diffs without a sonar proof`,
+          fix: withDocLink(`Set sonarqube.enabled: true and drop review_gate.sonar: false; a laptop without Docker runs 'kj sonar start'. Only a human grant (kj policy grant --rule method.sonar.code) lifts the gate.`, "sonar_docker"),
+        };
       }
       let reachable;
       try {

package/src/commands/review-gate.js

@@ -13,6 +13,7 @@ import { runOneShotReview } from "../review/one-shot-review.js";
 import { runSolomonArbitration } from "../review/solomon-arbitration.js";
 import { ensureGateTrackable } from "../review/gate-gitignore.js";
 import { runSonarPregate, formatSonarFinding, addedLinesByFile } from "../review/sonar-pregate.js";
+import { checkSonarRequirement, SONAR_RULE_ID } from "../review/sonar-requirement.js";
 import { runMutationPregate, formatSurvivor } from "../review/mutation-pregate.js";
 import { checkCardFirst } from "../review/card-first.js";
 import { liftSealedSupervisorViolations } from "../policy/supervisor-verify.js";
@@ -53,6 +54,14 @@ async function rawDiff(range, extraArgs = []) {
   return res.stdout;
 }
 
+// KJC-TSK-0838: a grant is the ONLY way past the sonar requirement, so it is
+// said with who gave it, its scope and until when.
+const formatSonarGrant = (g) => {
+  const scope = g.origin === "global" ? " GLOBAL" : "";
+  const who = g.who?.git ?? "?";
+  return `⚠ sonar requirement lifted by a HUMAN grant [${SONAR_RULE_ID}]${scope} until ${g.expiresAt} — ${who}: ${g.justification || "sin justificación"}`;
+};
+
 // KJC-TSK-0813 (AC3): la exención dice su PROCEDENCIA — un standing global
 // (concedido para toda la máquina) no pasa por uno del proyecto. El texto
 // de las de proyecto queda EXACTAMENTE como estaba.
@@ -327,7 +336,25 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
         return { ok: true, merge: true, reason: "pure merge commit (MERGE_HEAD, empty staged diff)" };
       }
     }
-    const res = await checkVerdict(projectDir, diff);
+    let res = await checkVerdict(projectDir, diff);
+    // KJC-TSK-0838: a reviewed diff with code enters only if the verdict's
+    // sonar block proves the analysis ran and covered every staged source.
+    // The headless pipeline stamps its verdict after its own sonar stage and
+    // carries no block yet (step 3 of the card) — said, never assumed silent.
+    if (res.ok && res.verdict.host === "kj-pipeline") {
+      // The pipeline scans the whole project (no per-file proof yet), so its
+      // stamp must at least show the stage RAN; no block or a skipped stage
+      // is refused like any other unanalysed code.
+      const stage = res.verdict.sonar;
+      if (!stage?.ran) {
+        const why = stage ? `the pipeline's sonar stage did not run: ${stage.reason || "unknown reason"}` : "the pipeline verdict carries no sonar block";
+        res = { ok: false, verdict: res.verdict, reason: `Sonar is mandatory for code — ${why}` };
+      }
+    } else if (res.ok) {
+      const req = checkSonarRequirement({ config, stagedFiles: changedFiles, sonar: res.verdict.sonar, standingExceptions: std.standing });
+      if (!req.ok) res = { ok: false, verdict: res.verdict, reason: req.reason };
+      else if (req.mode === "granted") console.log(formatSonarGrant(req.grant));
+    }
     console.log(res.ok
       ? `✓ verdict ok — approved by ${res.verdict.reviewer} (diff ${res.verdict.diffHash.slice(0, 12)})`
       : `✗ ${res.reason}`);
@@ -344,6 +371,10 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   // without spending reviewer tokens; the rest travel with the task so
   // the cross-AI reviewer weighs them. Unavailable sonar degrades loudly.
   let task = flags.task;
+  // KJC-TSK-0838: what sonar saw travels INSIDE the verdict, bound to the
+  // diff hash — a reviewed diff and a reviewed AND analysed diff must be
+  // distinguishable by --check and by the method report.
+  let sonarRecord = { ran: false, reason: "--no-sonar: the pre-gate was skipped by flag" };
   if (flags.sonar !== false) {
     // KJC-TSK-0795 AC3: only issues on lines this diff ADDS may veto.
     const touchedLines = addedLinesByFile(await rawDiff(flags.range, ["--unified=0"]));
@@ -356,7 +387,15 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
       console.log(chosen
         ? `⚠ sonar pre-gate skipped: ${pre.reason}`
         : `✗ sonar pre-gate UNAVAILABLE — the quality gate did NOT run on this diff: ${pre.reason}`);
+      sonarRecord = { ran: false, reason: pre.reason };
     } else {
+      sonarRecord = {
+        ran: true, projectKey: pre.projectKey, covered: pre.covered ?? [], uncovered: pre.uncovered ?? [],
+        blocking: pre.blocking.length, advisory: pre.advisory.length,
+      };
+      if (sonarRecord.uncovered.length > 0) {
+        console.log(`⚠ sonar coverage: ${sonarRecord.uncovered.length} staged source(s) were NOT in the analysis (${sonarRecord.uncovered.slice(0, 5).join(", ")}${sonarRecord.uncovered.length > 5 ? "…" : ""}) — the scan did not see them`);
+      }
       const found = [...pre.blocking, ...pre.advisory];
       if (found.length > 0) {
         console.log(`Sonar on the changed lines — ${pre.blocking.length} blocking, ${pre.advisory.length} advisory (project total: ${pre.totalProject}):`);
@@ -381,6 +420,20 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     }
   }
 
+  // KJC-TSK-0838: fail-CLOSED for code. Sonar disabled, down, skipped by
+  // flag, or blind to a staged source — the diff does not reach the reviewer.
+  // Docs-only diffs pass; a live human grant on the rule is the only escape.
+  const sonarReq = checkSonarRequirement({ config, stagedFiles: changedFiles, sonar: sonarRecord, standingExceptions: std.standing });
+  if (!sonarReq.ok) {
+    console.log(`✗ ${sonarReq.reason}`);
+    process.exitCode = 1;
+    return { verdict: "rejected", reviewer: "sonar", issues: [{ severity: "high", file: undefined, description: sonarReq.reason }] };
+  }
+  if (sonarReq.mode === "granted") console.log(formatSonarGrant(sonarReq.grant));
+  // The verdict says on what grounds the requirement was met (proof, docs-only,
+  // human grant) — the method report reads it back.
+  sonarRecord.mode = sonarReq.mode;
+
   // MUT-A (KJC-TSK-0716): mutation pre-gate — opt-in (method_gates.mutation),
   // SOLO en --staged (jamás en pre-commit: cuesta minutos; y jamás en --range:
   // el scope es el ÍNDICE y anotaría trabajo ajeno — catch de codex). block
@@ -403,7 +456,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     }
   }
 
-  const record = await runOneShotReview({ diff, task, config, logger, projectDir });
+  const record = await runOneShotReview({ diff, task, config, logger, projectDir, sonar: sonarRecord });
   printVerdict(record);
   process.exitCode = record.verdict === "approved" ? 0 : 1;
   return record;

package/src/git/automation.js

@@ -4,7 +4,7 @@
  */
 
 import { addCheckpoint } from "../session/store.js";
-import { stampStagedVerdict } from "../review/verdict-store.js";
+import { pipelineSonarBlock, stampStagedVerdict } from "../review/verdict-store.js";
 import {
   ensureGitRepo,
   currentBranch,
@@ -277,6 +277,8 @@ export async function finalizeGitAutomation({ config, gitCtx, task, logger, sess
         projectDir: config?.projectDir || process.cwd(),
         reviewer: config?.reviewer || "pipeline-reviewer",
         summary: `kj run session ${session?.id || ""}: reviewer approved`.trim(),
+        // KJC-TSK-0838: the sonar stage result travels with the stamp.
+        sonar: pipelineSonarBlock(stageResults?.sonar),
       }),
     });
     committed = commitResult.committed;

package/src/mcp/handlers/direct-handlers.js

@@ -39,6 +39,26 @@ async function runBootstrapGate(server, a) {
   await ensureBootstrap(projectDir, config);
 }
 
+/**
+ * KJC-BUG-0175 (#1723): the tool schemas promise "either `task` or
+ * `taskFile`", but only kj_run read the file — every direct handler
+ * answered "Missing required field: task" to a taskFile-only call. Same
+ * resolution as run-handler: read the file (relative to projectDir) into
+ * `a.task`, then require it.
+ * @returns {Promise<Object|null>} a failPayload when the task is missing or the file unreadable
+ */
+async function requireTask(a, server) {
+  try {
+    await ensureTaskFromFile(a, a.projectDir || (await resolveProjectDir(server, a.projectDir).catch(() => null)));
+  } catch (err) {
+    return failPayload(`taskFile read failed: ${err.message}`);
+  }
+  if (!a.task) {
+    return failPayload("Missing required field: task (or pass taskFile with a .md path)");
+  }
+  return null;
+}
+
 function applySessionOverrides(a, roleKeys) {
   const sessionOvr = getSessionOverrides();
   for (const key of roleKeys) {
@@ -389,9 +409,8 @@ export async function handleArchitectDirect(a, server, extra) {
 }
 
 export async function handleCode(a, server, extra) {
-  if (!a.task) {
-    return failPayload("Missing required field: task");
-  }
+  const missingTask = await requireTask(a, server);
+  if (missingTask) return missingTask;
   await runBootstrapGate(server, a);
   if (!isPreflightAcked()) {
     // Auto-acknowledge with defaults for autonomous operation
@@ -404,25 +423,22 @@ export async function handleCode(a, server, extra) {
 }
 
 export async function handleReview(a, server, extra) {
-  if (!a.task) {
-    return failPayload("Missing required field: task");
-  }
+  const missingTask = await requireTask(a, server);
+  if (missingTask) return missingTask;
   await runBootstrapGate(server, a);
   return handleReviewDirect(a, server, extra);
 }
 
 export async function handlePlan(a, server, extra) {
-  if (!a.task) {
-    return failPayload("Missing required field: task");
-  }
+  const missingTask = await requireTask(a, server);
+  if (missingTask) return missingTask;
   await runBootstrapGate(server, a);
   return handlePlanDirect(a, server, extra);
 }
 
 export async function handleDiscover(a, server, extra) {
-  if (!a.task) {
-    return failPayload("Missing required field: task");
-  }
+  const missingTask = await requireTask(a, server);
+  if (missingTask) return missingTask;
   const validModes = new Set(["gaps", "momtest", "wendel", "classify", "jtbd"]);
   if (a.mode && !validModes.has(a.mode)) {
     return failPayload(`Invalid mode "${a.mode}". Valid values: ${[...validModes].join(", ")}`);
@@ -432,25 +448,22 @@ export async function handleDiscover(a, server, extra) {
 }
 
 export async function handleTriage(a, server, extra) {
-  if (!a.task) {
-    return failPayload("Missing required field: task");
-  }
+  const missingTask = await requireTask(a, server);
+  if (missingTask) return missingTask;
   await runBootstrapGate(server, a);
   return handleTriageDirect(a, server, extra);
 }
 
 export async function handleResearcher(a, server, extra) {
-  if (!a.task) {
-    return failPayload("Missing required field: task");
-  }
+  const missingTask = await requireTask(a, server);
+  if (missingTask) return missingTask;
   await runBootstrapGate(server, a);
   return handleResearcherDirect(a, server, extra);
 }
 
 export async function handleArchitect(a, server, extra) {
-  if (!a.task) {
-    return failPayload("Missing required field: task");
-  }
+  const missingTask = await requireTask(a, server);
+  if (missingTask) return missingTask;
   await runBootstrapGate(server, a);
   return handleArchitectDirect(a, server, extra);
 }

package/src/mcp/handlers/rag-handler.js

@@ -1,7 +1,7 @@
 // KJC-PCS-0049 Step 7 — MCP handlers calling src/rag/* directly. Imports
 // from src/commands/* are forbidden by the layer-boundaries test
 // (MCP and CLI are peer layers); we hit the pure rag/* modules instead.
-import { countChunks, openVecStore } from "../../rag/vec-store.js";
+import { countChunks, openVecStore, projectSlug } from "../../rag/vec-store.js";
 import { makeGovernedEmbedder } from "../../rag/governed-embedder.js";
 import { indexProject } from "../../rag/indexer.js";
 import { query } from "../../rag/retriever.js";
@@ -22,11 +22,17 @@ export async function handleRagQuery(args, server) {
     const config = await buildConfig({ ...args, projectDir }, "rag-query");
     const topK = Number(args?.topK) || 5;
     const scope = args?.scope || "all";
+    // KJC-BUG-0177 (#1713): the store is shared by every indexed project,
+    // and the MCP tool searched it unfiltered while the CLI (KJC-TSK-0438)
+    // scoped to the project's slug. Same rule here: default = slug of
+    // projectDir, `project: "all"` disables the filter, `project: <slug>`
+    // overrides it.
+    const project = args?.project === "all" ? null : (args?.project || projectSlug(projectDir) || null);
     const db = openVecStore({ dim: config?.rag?.embedder?.dim || 768 });
     try {
-      if (countChunks(db) === 0) return responseText({ hits: [], empty: true, topK, scope });
-      const hits = await query(db, makeGovernedEmbedder(config), text, { topK, scope });
-      return responseText({ hits, empty: false, topK, scope });
+      if (countChunks(db) === 0) return responseText({ hits: [], empty: true, topK, scope, project });
+      const hits = await query(db, makeGovernedEmbedder(config), text, { topK, scope, project });
+      return responseText({ hits, empty: false, topK, scope, project });
     } finally { db.close(); }
   } catch (err) {
     return failPayload(`kj_rag_query failed: ${err.message}`);

package/src/mcp/server-handlers.js

@@ -40,6 +40,7 @@ import {
 } from "./handlers/management-handlers.js";
 import { handleHu, handleSkills, handleSuggest } from "./handlers/hu-handlers.js";
 import { handleRagQuery, handleRagIndex } from "./handlers/rag-handler.js";
+import { withKarajanHome } from "../utils/paths.js";
 
 export async function handleToolCall(name, args, server, extra) {
   const a = asObject(args);
@@ -73,7 +74,16 @@ export async function handleToolCall(name, args, server, extra) {
     kj_rag_index:   (a, server) => handleRagIndex(a, server),
   }[name];
   if (handler) {
-    return handler(a, server, extra);
+    // KJC-BUG-0176 (#1722): `kjHome` only reached the env of the `kj`
+    // subprocesses spawned by run-kj.js; the direct handlers resolve the
+    // home from THIS process (bootstrap gate, config load), so the
+    // argument was ignored and the gate failed with "Config file not
+    // found". Pin the home to this call's async context instead — no
+    // env mutation, so overlapping calls never see each other's home.
+    const kjHome = typeof a.kjHome === "string" && a.kjHome.trim() !== "" ? a.kjHome : null;
+    return kjHome
+      ? withKarajanHome(kjHome, () => handler(a, server, extra))
+      : handler(a, server, extra);
   }
   return failPayload(`Unknown tool: ${name}`);
 }

package/src/mcp/tools.js

@@ -413,6 +413,7 @@ export const tools = [
         text: { type: "string", description: "The natural-language query." },
         topK: { type: "number", description: "Max number of hits to return. Default: 5." },
         scope: { type: "string", description: "Filter by chunk kind: 'plans' | 'code' | 'onboarding' | 'all' (default)." },
+        project: { type: "string", description: "Project slug to search. Defaults to the basename of projectDir (same isolation as `kj rag query`); 'all' searches every indexed project." },
         projectDir: { type: "string", description: "Absolute path to the project directory" }
       },
       required: ["text"]

package/src/review/one-shot-review.js

@@ -43,6 +43,8 @@ export async function pickCrossReviewer({ config, hostAgent, detectAgents = dete
  */
 export async function runOneShotReview({
   diff, task, config, logger, projectDir,
+  // KJC-TSK-0838: what the sonar pre-gate saw, persisted with the verdict.
+  sonar = null,
   hostAgent = detectHostAgent(),
   createAgentFn = createAgent,
   detectAgents = detectAvailableAgents,
@@ -123,6 +125,7 @@ export async function runOneShotReview({
     issues: parsed.blocking_issues || [],
     suggestions: parsed.non_blocking_suggestions || [],
     summary: parsed.summary || parsed.raw_summary || "",
+    ...(sonar ? { sonar } : {}),
     confidence: parsed.confidence ?? null,
   });
 }

package/src/review/sonar-pregate.js

@@ -9,9 +9,12 @@
  * a laptop without Docker still commits.
  */
 
-import { runSonarScan } from "../sonar/scanner.js";
+import { existsSync } from "node:fs";
+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";
+import { sourceFilesOf } from "./tests-with-code.js";
 
 const BLOCKING_SEVERITIES = new Set(["BLOCKER", "CRITICAL"]);
 
@@ -59,35 +62,81 @@ export function addedLinesByFile(diffText) {
  * Every failure path degrades to {available:false, reason} — the pre-gate
  * never breaks the review, it only refuses to stay silent.
  */
-export async function runSonarPregate({ config, stagedFiles = [], touchedLines = null, logger = null }) {
+/**
+ * KJC-TSK-0838 step 3 (monorepo): each staged file belongs to the nearest
+ * directory up from it that owns a sonar-project.properties; the repo root
+ * ("") owns the rest. One scan per group, run from that directory.
+ * @returns {Map<string, string[]>} repo-relative dir → staged files
+ */
+export function groupByScanRoot(files, { root = process.cwd(), exists = existsSync } = {}) {
+  const groups = new Map();
+  for (const file of files) {
+    let owner = "";
+    for (let dir = dirname(file); dir && dir !== "."; dir = dirname(dir)) {
+      if (exists(join(root, dir, "sonar-project.properties"))) { owner = dir; break; }
+    }
+    (groups.get(owner) ?? groups.set(owner, []).get(owner)).push(file);
+  }
+  return groups;
+}
+
+export async function runSonarPregate({ config, stagedFiles = [], touchedLines = null, logger = null, exists = existsSync }) {
   if (config?.review_gate?.sonar === false) {
     return { available: false, reason: "disabled in config (review_gate.sonar: false)" };
   }
   let lock = null;
   try {
     lock = await acquireToolLock("sonar-scanner", { timeoutMs: 300_000 });
-    const scan = await runSonarScan(config);
-    if (scan.note) logger?.warn?.(scan.note); // KJC-BUG-0156: precedence is said, never silent
-    if (!scan.ok) {
-      return { available: false, reason: (scan.stderr || scan.stdout || "sonar scan failed").trim() };
+    const groups = groupByScanRoot(stagedFiles, { exists });
+    if (groups.size === 0) groups.set("", []);
+    const indexed = new Set();
+    const issues = [];
+    const keys = [];
+    let totalProject = 0;
+    for (const dir of groups.keys()) {
+      const prefix = dir ? `${dir}/` : "";
+      // KJC-TSK-0838: verbose, so the scanner names every file it indexed.
+      const scan = await runSonarScan(config, null, { verbose: true, ...(dir ? { cwd: join(process.cwd(), dir) } : {}) });
+      if (scan.note) logger?.warn?.(scan.note); // KJC-BUG-0156: precedence is said, never silent
+      if (!scan.ok) {
+        return { available: false, reason: (scan.stderr || scan.stdout || "sonar scan failed").trim() };
+      }
+      // Coverage is PROVED by the scanner's own index, never inferred from
+      // config — a root-scoped properties file let 4 PRs under packages/radar
+      // pass as "0 issues on staged files". No index in the log = no proof.
+      const own = indexedFilesFrom(scan.stdout);
+      if (own.size === 0) {
+        return { available: false, reason: `the scanner log names no indexed file (sonar.verbose) — coverage cannot be proved for ${dir || "the repo root"}` };
+      }
+      for (const f of own) indexed.add(`${prefix}${f}`);
+      keys.push(scan.projectKey);
+      // The scan above ALWAYS runs before issues are read (single-flight): the
+      // verdict is about the code as it is now, never a stale server analysis
+      // (KJC-TSK-0795 AC2 — that failure mode has no route here, by design).
+      const res = await getOpenIssues(config, scan.projectKey);
+      totalProject += res.total ?? (res.issues || []).length;
+      // Issue components are package-relative: made repo-relative here.
+      for (const i of res.issues || []) issues.push({ ...i, component: `${scan.projectKey}:${prefix}${issueFile(i)}` });
     }
-    // The scan above ALWAYS runs before issues are read (single-flight): the
-    // verdict is about the code as it is now, never a stale server analysis
-    // (KJC-TSK-0795 AC2 — that failure mode has no route here, by design).
-    const res = await getOpenIssues(config, scan.projectKey);
+    const { sources } = sourceFilesOf(config, stagedFiles);
+    const covered = sources.filter((f) => indexed.has(f));
+    const uncovered = sources.filter((f) => !indexed.has(f));
     const staged = new Set(stagedFiles);
-    const onStaged = (res.issues || []).filter((i) => staged.has(issueFile(i)));
+    const onStaged = issues.filter((i) => staged.has(issueFile(i)));
     // KJC-TSK-0795 AC3: with the diff's line map, only issues on lines the PR
     // ADDS can veto — a 3-line PR must not answer for 30 preexisting issues.
     // No line, or an untouched line, is the file's TREND: reported, never a block.
     const isTouched = (i) => !touchedLines || (i.line != null && touchedLines.get(issueFile(i))?.has(Number(i.line)));
-    const own = onStaged.filter(isTouched);
+    const mine = onStaged.filter(isTouched);
     return {
       available: true,
-      blocking: own.filter((i) => BLOCKING_SEVERITIES.has(String(i.severity).toUpperCase())),
-      advisory: own.filter((i) => !BLOCKING_SEVERITIES.has(String(i.severity).toUpperCase())),
+      projectKey: keys.join(","),
+      covered,
+      uncovered,
+      blocking: mine.filter((i) => BLOCKING_SEVERITIES.has(String(i.severity).toUpperCase())),
+      advisory: mine.filter((i) => !BLOCKING_SEVERITIES.has(String(i.severity).toUpperCase())),
       preexisting: touchedLines ? onStaged.filter((i) => !isTouched(i)) : [],
-      totalProject: res.total ?? (res.issues || []).length,
+      totalProject,
     };
   } catch (err) {
     logger?.warn?.(`[sonar-pregate] ${err.message}`);

package/src/review/sonar-requirement.js

@@ -0,0 +1,47 @@
+/**
+ * KJC-TSK-0838 (ADR "Sonar es un gate de commit no evadible", 2026-09-13) —
+ * a diff that touches source files enters only with a sonar block that RAN
+ * and COVERED every staged source; docs-only diffs are exempt. The only other
+ * way through is a live HUMAN grant on `method.sonar.code` (kj policy grant:
+ * identity, expiry, reason, anchored decision log). No env var is read here,
+ * on purpose: an escape an agent can set for itself is the hole this closes
+ * (KRD-TSK-0023 reached main in 4 code PRs with no real analysis).
+ */
+import { sourceFilesOf } from "./tests-with-code.js";
+
+export const SONAR_RULE_ID = "method.sonar.code";
+
+const GRANT_HINT = `Only a human grant lifts this: kj policy grant --rule ${SONAR_RULE_ID} --until <iso> --reason "<why>"`;
+
+function liveGrant(standingExceptions, now) {
+  return standingExceptions.find((e) => e.rule_id === SONAR_RULE_ID && new Date(e.expiresAt).getTime() > now.getTime()) || null;
+}
+
+/**
+ * @returns {{ok: boolean, mode: "docs-only"|"pass"|"granted"|"block", reason?: string, grant?: object, sources?: string[]}}
+ */
+export function checkSonarRequirement({ config = {}, stagedFiles = [], sonar, standingExceptions = [], now = new Date() }) {
+  const { sources } = sourceFilesOf(config, stagedFiles);
+  if (sources.length === 0) return { ok: true, mode: "docs-only" };
+
+  const grant = liveGrant(standingExceptions, now);
+  if (grant) return { ok: true, mode: "granted", grant, sources };
+
+  const head = `Sonar is mandatory for code (${sources.length} staged source${sources.length === 1 ? "" : "s"})`;
+  if (!sonar) {
+    return { ok: false, mode: "block", sources, reason: `${head} — the verdict carries no sonar block; run \`kj review --staged\` again. ${GRANT_HINT}` };
+  }
+  if (!sonar.ran) {
+    return { ok: false, mode: "block", sources, reason: `${head} — the analysis did not run: ${sonar.reason || "unknown reason"}. ${GRANT_HINT}` };
+  }
+  // Recomputed from `covered` against the CURRENT staged sources: the diff
+  // hash already pins the file set, so a source missing from the proof is a
+  // source the scan never indexed, whatever the block claims.
+  const coveredSet = new Set(sonar.covered || []);
+  const uncovered = sources.filter((f) => !coveredSet.has(f));
+  if (uncovered.length > 0) {
+    const list = `${uncovered.slice(0, 5).join(", ")}${uncovered.length > 5 ? "…" : ""}`;
+    return { ok: false, mode: "block", sources, reason: `${head} — the scan never indexed ${uncovered.length} of them (${list}): fix sonar-project.properties so they are analysed. ${GRANT_HINT}` };
+  }
+  return { ok: true, mode: "pass", sources };
+}

package/src/review/tests-with-code.js

@@ -11,17 +11,28 @@
 const DEFAULT_TEST_PATTERNS = ["/tests/", "/__tests__/", ".test.", ".spec."];
 const DEFAULT_SOURCE_EXTS = [".js", ".jsx", ".ts", ".tsx", ".py", ".go", ".java", ".rb", ".php", ".cs"];
 
-export function checkTestsWithCode({ config = {}, stagedFiles = [], numstat = null, env = process.env }) {
-  if (env.KJ_ALLOW_NO_TESTS === "1") {
-    return { ok: true, mode: "exempt", reason: "KJ_ALLOW_NO_TESTS=1 (explicit escape hatch)" };
-  }
+/**
+ * The staged files that are SOURCE by the project's own definition: source
+ * extension and not a test. Shared by every gate that must tell "code" from
+ * "docs" (tests-with-code, the sonar coverage proof of KJC-TSK-0838).
+ */
+export function sourceFilesOf(config = {}, files = []) {
   const patterns = config.development?.test_file_patterns || DEFAULT_TEST_PATTERNS;
   const exts = config.development?.source_file_extensions || DEFAULT_SOURCE_EXTS;
   // Staged paths are repo-relative (no leading slash) — normalize so the
   // "/tests/" style patterns also match the top-level tests directory.
   const isTest = (f) => patterns.some((p) => `/${f}`.includes(p));
-  const sources = stagedFiles.filter((f) => !isTest(f) && exts.some((e) => f.endsWith(e)));
-  const hasTests = stagedFiles.some(isTest);
+  return {
+    sources: files.filter((f) => !isTest(f) && exts.some((e) => f.endsWith(e))),
+    hasTests: files.some(isTest),
+  };
+}
+
+export function checkTestsWithCode({ config = {}, stagedFiles = [], numstat = null, env = process.env }) {
+  if (env.KJ_ALLOW_NO_TESTS === "1") {
+    return { ok: true, mode: "exempt", reason: "KJ_ALLOW_NO_TESTS=1 (explicit escape hatch)" };
+  }
+  const { sources, hasTests } = sourceFilesOf(config, stagedFiles);
 
   if (sources.length === 0 || hasTests) return { ok: true, mode: "pass" };
   // KJC-TSK-0795 AC1 (epic KJC-PCS-0082): deleting code adds no behavior to

package/src/review/verdict-store.js

@@ -96,7 +96,7 @@ export async function loadVerdict(projectDir, hash) {
  * (KJC-BUG-0115).
  * @returns {Promise<{stamped: boolean}>}
  */
-export async function stampStagedVerdict({ projectDir, reviewer, summary = "" }) {
+export async function stampStagedVerdict({ projectDir, reviewer, summary = "", sonar = null }) {
   const dir = projectDir || process.cwd();
   try {
     await fs.access(path.join(dir, ".karajan", "review-gate"));
@@ -107,10 +107,30 @@ export async function stampStagedVerdict({ projectDir, reviewer, summary = "" })
   if (res.exitCode !== 0 || !res.stdout?.trim()) return { stamped: false };
   await saveVerdict(dir, res.stdout, {
     verdict: "approved", reviewer, host: "kj-pipeline", issues: [], summary,
+    // KJC-TSK-0838: what the pipeline's sonar stage saw, so --check can tell
+    // a run whose gate ran from one that skipped it.
+    ...(sonar ? { sonar } : {}),
   });
   return { stamped: true };
 }
 
+/**
+ * KJC-TSK-0838: the pipeline sonar stage result as a verdict sonar block.
+ * SKIPPED (no remote, no key) or absent is `ran:false` WITH the reason — the
+ * pre-commit check then refuses code, as it would for any other diff.
+ * Coverage lists stay empty: the pipeline scans the whole project, and the
+ * per-file proof (verbose index) is not wired into SonarRole yet.
+ */
+export function pipelineSonarBlock(stageResult) {
+  if (!stageResult) return { ran: false, source: "pipeline", reason: "the pipeline recorded no sonar stage" };
+  if (!stageResult.gateStatus || stageResult.gateStatus === "SKIPPED") {
+    return { ran: false, source: "pipeline", reason: stageResult.reason || stageResult.error || "the sonar stage did not run" };
+  }
+  return {
+    ran: true, source: "pipeline", projectKey: stageResult.projectKey || null, gateStatus: stageResult.gateStatus, covered: [], uncovered: [],
+  };
+}
+
 /**
  * Is there an APPROVED verdict for exactly this diff?
  * @returns {Promise<{ok: boolean, verdict?: object, reason?: string}>}

package/src/roles/commiter-role.js

@@ -35,7 +35,9 @@ export class CommiterRole extends BaseRole {
   }
 
   async execute(input) {
-    const { task, commitMessage, push = false, createPr = false } = input || {};
+    // KJC-TSK-0838: the caller hands the sonar stage result (pipelineSonarBlock);
+    // without it the stamp carries no proof and the commit gate refuses code.
+    const { task, commitMessage, push = false, createPr = false, sonar = null } = input || {};
 
     const isRepo = await ensureGitRepo();
     if (!isRepo) {
@@ -65,6 +67,7 @@ export class CommiterRole extends BaseRole {
         projectDir: this.config?.projectDir || process.cwd(),
         reviewer: this.config?.reviewer || "pipeline-reviewer",
         summary: "kj pipeline (commiter role): review passed",
+        sonar,
       }),
     });
     const commitHash = await revParse("HEAD");

package/src/sonar/scanner.js

@@ -37,8 +37,23 @@ export async function pickSonarScanner(scannerConfig = {}, deps = {}) {
   return { type: "docker" };
 }
 
+/**
+ * KJC-TSK-0838: the files the scanner ITSELF reports having indexed
+ * (`'<path>' indexed with language '<lang>'`, emitted with sonar.verbose).
+ * Paths are relative to the scanned base dir. This is the proof of coverage:
+ * what the engine saw, not what the config claims it should see.
+ * @param {string} scanOutput @returns {Set<string>}
+ */
+export function indexedFilesFrom(scanOutput) {
+  const files = new Set();
+  for (const m of String(scanOutput || "").matchAll(/'([^']+)' indexed with language '/g)) files.add(m[1]);
+  return files;
+}
+
 export function buildScannerOpts(projectKey, scanner = {}) {
   const opts = [`-Dsonar.projectKey=${projectKey}`];
+  // KJC-TSK-0838: verbose is what makes the scanner name every indexed file.
+  if (scanner.verbose) opts.push("-Dsonar.verbose=true");
   if (scanner.sources) opts.push(`-Dsonar.sources=${scanner.sources}`);
   if (scanner.exclusions) opts.push(`-Dsonar.exclusions=${scanner.exclusions}`);
   if (scanner.test_inclusions) opts.push(`-Dsonar.test.inclusions=${scanner.test_inclusions}`);
@@ -225,18 +240,27 @@ export async function ensureSonarProjectProperties(cwd = process.cwd()) {
   }
 }
 
-export async function runSonarScan(config, projectKey = null) {
+export async function runSonarScan(config, projectKey = null, { verbose = false, cwd = null } = {}) {
+  const scanCwd = cwd || process.cwd();
+  // KJC-TSK-0838 step 3 (monorepo): a nested package scans from its own
+  // directory under the key its properties declare — so the proof of
+  // coverage is about that package, not the root's `sonar.sources`.
+  const repoProps = await ensureSonarProjectProperties(scanCwd);
   let effectiveProjectKey;
-  try {
-    effectiveProjectKey = await resolveSonarProjectKey(config, { projectKey });
-  } catch (error) {
-    return {
-      ok: false,
-      projectKey: null,
-      stdout: "",
-      stderr: error?.message || String(error),
-      exitCode: 1
-    };
+  if (cwd && !projectKey && repoProps.declaredKey) {
+    effectiveProjectKey = repoProps.declaredKey;
+  } else {
+    try {
+      effectiveProjectKey = await resolveSonarProjectKey(config, { projectKey });
+    } catch (error) {
+      return {
+        ok: false,
+        projectKey: null,
+        stdout: "",
+        stderr: error?.message || String(error),
+        exitCode: 1
+      };
+    }
   }
   const sonarConfig = config?.sonarqube || {};
   const rawHost = sonarConfig.host || "http://localhost:9000";
@@ -260,7 +284,6 @@ export async function runSonarScan(config, projectKey = null) {
   }
   // KJC-BUG-0156: kj's -Dsonar.projectKey stays (scan and query must use the
   // SAME key), but the repo's properties own the LAYOUT from here on.
-  const repoProps = await ensureSonarProjectProperties();
   const token = await resolveSonarTokenWithFallback(config, apiHost);
   if (!token) {
     return {
@@ -284,7 +307,8 @@ export async function runSonarScan(config, projectKey = null) {
   const scannerConfig = respectRepoProperties(
     normalizeScannerConfig({
       ...sonarConfig.scanner,
-      ...coverage.scannerPatch
+      ...coverage.scannerPatch,
+      ...(verbose ? { verbose: true } : {})
     }),
     repoProps
   );
@@ -310,7 +334,7 @@ export async function runSonarScan(config, projectKey = null) {
       "run",
       "--rm",
       "-v",
-      `${process.cwd()}:/usr/src`,
+      `${scanCwd}:/usr/src`,
       ...(isLocalHost ? ["--add-host", "host.docker.internal:host-gateway"] : []),
       ...(isLocalHost || isExternalSonar ? [] : ["--network", sonarNetwork]),
       "-e", "SONAR_HOST_URL",
@@ -320,10 +344,11 @@ export async function runSonarScan(config, projectKey = null) {
     ];
   }
 
-  const result = await runCommand(cmd, args, { timeout: scannerTimeout, env });
+  const result = await runCommand(cmd, args, { timeout: scannerTimeout, env, cwd: scanCwd });
   return {
     ok: result.exitCode === 0,
     projectKey: effectiveProjectKey,
+    cwd: scanCwd,
     scanner: pick.type,
     note,
     stdout: result.stdout,

package/src/utils/paths.js

@@ -4,6 +4,7 @@
 export {
   resolveHome,
   getKarajanHome,
+  withKarajanHome,
   __resetKjHomeWarningForTests,
   getSessionRoot,
   getSonarComposePath,