karajan-code 4.28.1 → 4.29.0

package/src/harden/phone-sign.js

@@ -32,21 +32,78 @@ async function relayConfig(fetchFn) {
 }
 const SIGN_PAGE = "https://karajancode.com/sign";
 const POLL_INTERVAL_MS = 2000;
-const TTL_MS = 120000;
+const TTL_MS = 60000;
+
+/** Spinner en su sitio (una línea, con \r) solo en TTY; no-op fuera de TTY o en tests. */
+function makeSpinner() {
+  if (!process.stdout?.isTTY) return { tick() {}, stop() {} };
+  const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  let i = 0;
+  return {
+    tick() { process.stdout.write(`\r${frames[i++ % frames.length]} esperando la firma del móvil…`); },
+    stop() { process.stdout.write("\r\x1b[K"); },
+  };
+}
 
 const phoneKeyPath = (home) => join(home ?? homedir(), ".karajan", "supervisor-phone.json");
 
+// KJC-TSK-0831 (ADR 0010): el padrón de firmantes vive VERSIONADO en el repo,
+// no una única clave local — así un equipo comparte la confianza y el CI puede
+// verificar (0823) contra el mismo conjunto. La legacy ~/.karajan sigue valiendo.
+const signersPath = (projectDir) => join(projectDir ?? process.cwd(), ".karajan", "supervisor-signers.json");
+
+/** Valida una clave pública ed25519 raw en base64 canónico (32 bytes). */
+export function validatePhonePublicKey(publicKeyBase64) {
+  const raw = Buffer.from(publicKeyBase64 ?? "", "base64");
+  if (raw.length !== 32 || raw.toString("base64") !== publicKeyBase64) {
+    throw new Error("la clave debe ser base64 canónico de EXACTAMENTE 32 bytes (ed25519 raw)");
+  }
+  return publicKeyBase64;
+}
+
 export const isPhoneEnrolled = ({ home } = {}) => existsSync(phoneKeyPath(home));
 
 export const readEnrolledKey = ({ home } = {}) =>
   JSON.parse(readFileSync(phoneKeyPath(home), "utf8")).publicKey;
 
-/** Valida y persiste la clave pública del móvil (base64 del raw de 32 bytes). */
-export function enrollPhone(publicKeyBase64, { home } = {}) {
-  const raw = Buffer.from(publicKeyBase64 ?? "", "base64");
-  if (raw.length !== 32 || raw.toString("base64") !== publicKeyBase64) {
-    throw new Error("la clave debe ser base64 canónico de EXACTAMENTE 32 bytes (ed25519 raw)");
+/** Claves públicas del padrón versionado del repo (o [] si no hay). */
+export function readSigners({ projectDir } = {}) {
+  try {
+    const doc = JSON.parse(readFileSync(signersPath(projectDir), "utf8"));
+    return Array.isArray(doc?.signers) ? doc.signers.map((s) => s.publicKey).filter(Boolean) : [];
+  } catch {
+    return [];
   }
+}
+
+/**
+ * Conjunto de claves AUTORIZADAS a sellar: el padrón del repo ∪ la clave legacy
+ * de ~/.karajan (compat). Sin fallbacks silenciosos: si no hay ninguna, el Set
+ * está vacío y la verificación fallará ruidosamente.
+ */
+export function readEnrolledKeys({ projectDir, home } = {}) {
+  const keys = new Set(readSigners({ projectDir }));
+  if (isPhoneEnrolled({ home })) keys.add(readEnrolledKey({ home }));
+  return keys;
+}
+
+/** Añade una clave pública al padrón versionado del repo (dedup). Acto humano. */
+export function addSigner(publicKeyBase64, { projectDir, label } = {}) {
+  validatePhonePublicKey(publicKeyBase64);
+  const path = signersPath(projectDir);
+  let doc = { signers: [] };
+  try { doc = JSON.parse(readFileSync(path, "utf8")); } catch { /* new file */ }
+  if (!Array.isArray(doc.signers)) doc.signers = [];
+  if (doc.signers.some((s) => s.publicKey === publicKeyBase64)) return doc;
+  doc.signers.push({ publicKey: publicKeyBase64, label: label ?? null, enrolledAt: new Date().toISOString() });
+  mkdirSync(join(path, ".."), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(doc, null, 2)}\n`, "utf8");
+  return doc;
+}
+
+/** Valida y persiste la clave pública del móvil (legacy: clave única ~/.karajan). */
+export function enrollPhone(publicKeyBase64, { home } = {}) {
+  validatePhonePublicKey(publicKeyBase64);
   mkdirSync(join(phoneKeyPath(home), ".."), { recursive: true });
   const record = { publicKey: publicKeyBase64, enrolledAt: new Date().toISOString() };
   writeFileSync(phoneKeyPath(home), `${JSON.stringify(record, null, 2)}\n`, "utf8");
@@ -98,22 +155,34 @@ export async function requestPhoneSignature({ project, files, kjVersion, logger
   const signUrl = `${SIGN_PAGE}?c=${cid}`;
   drawQr(signUrl);
   logger.info?.(`phone-sign: escanea el QR o abre ${signUrl} y firma en el móvil (caduca en ${TTL_MS / 1000}s)`);
+  logger.info?.("phone-sign: esperando la firma del móvil…");
+  const spinner = deps.spinner ?? makeSpinner();
   const deadline = now() + TTL_MS;
   while (now() < deadline) {
     const res = await fetchFn(`${relay.url}/${cid}?key=${relay.apiKey}`);
-    if (!res.ok) throw new Error(`phone-sign: fallo consultando la petición de firma (HTTP ${res.status})`);
+    if (!res.ok) { spinner.stop(); throw new Error(`phone-sign: fallo consultando la petición de firma (HTTP ${res.status})`); }
     const fields = (await res.json()).fields ?? {};
     if (fields.state?.stringValue === "signed") {
-      const enrolled = readEnrolledKey({ home: deps.home });
-      if (fields.publicKey?.stringValue !== enrolled) {
-        return { ok: false, reason: "la publicKey del doc no coincide con la enrolada — el doc es transporte, la verdad es la enrolada" };
+      spinner.stop();
+      // KJC-TSK-0831 (ADR 0010): la clave que firma debe estar en el PADRÓN
+      // autorizado (repo ∪ legacy). El doc es transporte; la verdad es el padrón.
+      const authorized = readEnrolledKeys({ projectDir: deps.projectDir, home: deps.home });
+      const signerKey = fields.publicKey?.stringValue;
+      if (!signerKey || !authorized.has(signerKey)) {
+        return { ok: false, reason: "la publicKey que firma no está en el padrón autorizado — el doc es transporte, la verdad es el padrón" };
       }
       const payload = canonicalPayload({ cid, nonce, project, files });
-      const good = verifyPhoneSignature({ payload, signature: fields.signature?.stringValue ?? "", publicKey: enrolled });
-      return good ? { ok: true } : { ok: false, reason: "firma ed25519 inválida para el payload canónico" };
+      const signature = fields.signature?.stringValue ?? "";
+      const good = verifyPhoneSignature({ payload, signature, publicKey: signerKey });
+      if (!good) return { ok: false, reason: "firma ed25519 inválida para el payload canónico" };
+      // KJC-TSK-0823: devuelve el desafío + firma para que el sello los GRABE en
+      // la provenance y CI pueda re-verificar server-side (clave del padrón).
+      const filesHash = createHash("sha256").update(JSON.stringify(files)).digest("hex");
+      return { ok: true, signer: signerKey, signature, challenge: { cid, nonce, project, filesHash } };
     }
-    logger.info?.("phone-sign: esperando la firma del móvil…");
+    spinner.tick();
     await sleep(POLL_INTERVAL_MS);
   }
+  spinner.stop();
   return { ok: false, reason: "caducado" };
 }

package/src/harden/supervisor-commit.js

@@ -123,6 +123,7 @@ export async function commitSupervisorRegeneration({
   // es OBLIGATORIA — jamás se degrada a solo-nonce. Firma los MISMOS
   // files/hashes de la provenance (normalizados al par {file, sha256}).
   const phone = deps.phone ?? { enrolled: isPhoneEnrolled, request: requestPhoneSignature };
+  let signatureBlock = null;
   if (phone.enrolled({})) {
     const signed = await phone.request({
       project: basename(projectDir),
@@ -133,6 +134,11 @@ export async function commitSupervisorRegeneration({
     if (!signed.ok) {
       throw new Error(`capa 5: firma del móvil rechazada (${signed.reason}) — con móvil enrolado el sello exige su firma (PRP-0023)`);
     }
+    // KJC-TSK-0823: graba el desafío + firma en la provenance para que CI
+    // re-verifique server-side que un humano (clave del padrón) aprobó.
+    if (signed.challenge && signed.signature) {
+      signatureBlock = { ...signed.challenge, signer: signed.signer, signature: signed.signature };
+    }
   }
   const who = readIdentity(projectDir);
   const provenance = {
@@ -141,6 +147,7 @@ export async function commitSupervisorRegeneration({
     generation,
     who: who ? { gh: who.gh_user ?? null, git: who.git_email ?? null, grade: "declarada" } : null,
     files: hashed,
+    ...(signatureBlock ? { signature: signatureBlock } : {}),
   };
   writeFileSync(join(projectDir, PROVENANCE_FILE), `${JSON.stringify(provenance, null, 2)}\n`, "utf8");
   recordGateDecision(projectDir, {

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

@@ -16,6 +16,11 @@ import { runCommand } from "../utils/process.js";
 
 const STORE_DIR = path.join(".karajan", "reviews");
 
+// KJC-BUG-0173: a verdict is keyed by one exact diff hash, so once that diff is
+// committed or changed its hash is never looked up again — anything older than
+// this TTL is dead weight and safe to shed. Nothing live stays staged for weeks.
+export const VERDICT_TTL_DAYS = 14;
+
 export function diffHash(diff) {
   // trimEnd: runners differ on the final newline (execa strips it, raw
   // git keeps it) — trailing whitespace must not void a verdict.
@@ -36,9 +41,44 @@ export async function saveVerdict(projectDir, diff, verdict) {
   const file = verdictPath(projectDir, hash);
   await fs.mkdir(path.dirname(file), { recursive: true });
   await fs.writeFile(file, `${JSON.stringify(record, null, 2)}\n`);
+  // KJC-BUG-0173: a review is the natural moment to shed dead verdicts.
+  // Best-effort — hygiene must never break a save.
+  try { await pruneVerdicts({ projectDir }); } catch { /* hygiene, not correctness */ }
   return record;
 }
 
+/**
+ * Opportunistic GC for the verdict store: removes verdict files whose mtime is
+ * older than `maxAgeDays`. A verdict only counts for a byte-identical diff, so
+ * an aged one can never be re-checked. `now`/`dryRun` injectable for tests.
+ * @returns {Promise<{scanned:number, removed:number, expired:string[], dryRun:boolean, maxAgeDays:number}>}
+ */
+export async function pruneVerdicts({ projectDir, maxAgeDays = VERDICT_TTL_DAYS, now = Date.now, dryRun = false } = {}) {
+  const dir = path.join(projectDir || process.cwd(), STORE_DIR);
+  const cutoff = now() - maxAgeDays * 86400000;
+  let names;
+  try {
+    names = await fs.readdir(dir);
+  } catch {
+    return { scanned: 0, removed: 0, expired: [], dryRun, maxAgeDays };
+  }
+  const jsons = names.filter((n) => n.endsWith(".json"));
+  const expired = [];
+  for (const name of jsons) {
+    try {
+      const st = await fs.stat(path.join(dir, name));
+      if (st.mtimeMs < cutoff) expired.push(name);
+    } catch { /* vanished mid-scan */ }
+  }
+  let removed = 0;
+  if (!dryRun) {
+    for (const name of expired) {
+      try { await fs.unlink(path.join(dir, name)); removed += 1; } catch { /* already gone */ }
+    }
+  }
+  return { scanned: jsons.length, removed, expired, dryRun, maxAgeDays };
+}
+
 export async function loadVerdict(projectDir, hash) {
   try {
     return JSON.parse(await fs.readFile(verdictPath(projectDir, hash), "utf8"));
@@ -56,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"));
@@ -67,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}>}