karajan-code 4.28.1 → 4.29.0

package/README.md

@@ -41,7 +41,29 @@ This repo runs under its own environment: every commit to karajan-code carries a
 
 ## Install
 
-Tell your agent — in the directory where you want to work:
+Two ways in — pick your comfort level.
+
+### Maggle mode — you never touch the terminal
+
+Not a developer, or you just want it running? Paste this into your AI assistant (Claude Code, Codex, Cursor, VS Code):
+
+```text
+Set up Karajan in this project and start it for me: read
+https://karajancode.com/go.md and do everything it says. I'm not a developer —
+don't ask me technical questions, just get it running and tell me when it's ready.
+```
+
+It installs Karajan, prepares the project, and opens a single window with the board and your agent inside — stopping only if a step truly needs you (sudo or an account). Already installed? One command:
+
+```sh
+kj go            # or: kj go --window  (the agent's terminal embedded in the board)
+```
+
+`kj go` detects your agent (asks which only if you have several), prepares the project silently the first time, and drops you into a conversation that already follows the method. Your agent account and login stay yours — kj never touches credentials.
+
+### Developer mode — you stay in control
+
+Want your agent to walk each step and stop at every permission? Paste:
 
 ```text
 I want to use Karajan in this project: read https://karajancode.com/start.md
@@ -59,14 +81,6 @@ kj init && kj env install && kj harden && kj review --install-gate
 git config core.hooksPath .karajan/hooks
 ```
 
-Already installed and just want to work — even with no computing background? One command:
-
-```sh
-kj go
-```
-
-It detects your agent (Claude Code or Codex; asks which one only if you have both), prepares the project silently the first time, opens the board in your browser, and drops you into a conversation that already follows the method. Your agent account and login stay yours — kj never touches credentials. Prefer everything in ONE browser window? `kj go --window` embeds the agent's real terminal inside the board (loopback-only, single-session token).
-
 Requires git and at least one AI agent CLI — two enables cross-AI review; three enables arbitration. The npm route is `npm install -g @karajan-family/code` (published as `karajan-code` before joining the scope; the legacy name still installs the same versions). All install routes (npm, binaries, brew, Python wrapper) in the [install docs](https://karajancode.com/docs/v4/install/).
 
 ## The daily loop

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.28.1",
+  "version": "4.29.0",
   "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/verify-pack.mjs

@@ -33,8 +33,25 @@ const pkgName = pkg.name;
 
 // Subprocess env: strip CLAUDECODE (Claude Code blocks nested non-interactive
 // runs otherwise) and force a non-interactive, quiet npm.
+// KJC-BUG-0171: the tarball's postinstall registers karajan-mcp in
+// ~/.claude.json / ~/.codex / ~/.karajan pointing at THIS install's path. Every
+// verify install lives in a throwaway prefix, so those paths go stale the moment
+// the temp dir is cleaned — a CONNECTION_CLOSED MCP left in the real user config.
+// Redirect HOME so every global-config write lands in an isolated dir removed
+// with the rest; seed a git identity so any commit still works without ~/.gitconfig.
+const homeTmp = fs.mkdtempSync(path.join(os.tmpdir(), "kj-verify-home-"));
 const { CLAUDECODE: _omit, ...cleanEnv } = process.env;
-const childEnv = { ...cleanEnv, npm_config_yes: "true", CI: "1" };
+const childEnv = {
+  ...cleanEnv,
+  npm_config_yes: "true",
+  CI: "1",
+  HOME: homeTmp,
+  USERPROFILE: homeTmp,
+  GIT_AUTHOR_NAME: "kj verify",
+  GIT_AUTHOR_EMAIL: "verify@kj.local",
+  GIT_COMMITTER_NAME: "kj verify",
+  GIT_COMMITTER_EMAIL: "verify@kj.local",
+};
 
 function run(cmd, args, opts = {}) {
   return execFileSync(cmd, args, {
@@ -271,6 +288,7 @@ try {
   console.log(`\n✓ verify-pack: ${pkgName}@${expectedVersion} installs clean and runs.`);
 } finally {
   if (tgzPath && fs.existsSync(tgzPath)) fs.rmSync(tgzPath, { force: true });
+  if (homeTmp && fs.existsSync(homeTmp)) fs.rmSync(homeTmp, { recursive: true, force: true });
   if (tmpDir && fs.existsSync(tmpDir)) fs.rmSync(tmpDir, { recursive: true, force: true });
   if (gTmp && fs.existsSync(gTmp)) fs.rmSync(gTmp, { recursive: true, force: true });
   if (pnpmTmp && fs.existsSync(pnpmTmp)) fs.rmSync(pnpmTmp, { recursive: true, force: true });

package/src/checks/config-files.js

@@ -8,9 +8,11 @@
  *     ~/.karajan/kj.config.yml (strategy: manual — structural fixes needed)
  */
 
+import { existsSync } from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { exists } from "../utils/fs.js";
 import { getConfigPath } from "../config.js";
 import { resolveRoleMdPath, loadFirstExisting } from "../roles/base-role.js";
@@ -132,6 +134,89 @@ function createClaudeConfigCheck() {
   };
 }
 
+/**
+ * KJC-BUG-0171: the karajan-mcp server path registered in ~/.claude.json.
+ * Returns the args entry that points at the MCP server (…/mcp/server.js), or
+ * null when karajan-mcp is not registered.
+ */
+export function karajanMcpServerPath(config) {
+  const server = config?.mcpServers?.["karajan-mcp"];
+  const args = Array.isArray(server?.args) ? server.args : [];
+  return args.find((a) => typeof a === "string" && /[\\/]mcp[\\/]server\.js$/.test(a)) ?? null;
+}
+
+/**
+ * Repair a stale karajan-mcp registration in place: re-point it to this
+ * install's server when that server exists, or drop the dead entry when this
+ * install has no bundled server (the standalone binary). `serverExists` is
+ * injectable for tests. Mutates `config`; returns "repointed" | "removed" | null.
+ */
+export function repairKarajanMcpPath(config, correctServerPath, serverExists) {
+  const server = config?.mcpServers?.["karajan-mcp"];
+  if (!server) return null;
+  if (correctServerPath && serverExists(correctServerPath)) {
+    server.args = [correctServerPath];
+    server.cwd = path.resolve(path.dirname(correctServerPath), "..", "..");
+    return "repointed";
+  }
+  delete config.mcpServers["karajan-mcp"];
+  return "removed";
+}
+
+/**
+ * karajan-mcp registration path validity (~/.claude.json) — KJC-BUG-0171.
+ * A verify/temp install used to register the MCP at a throwaway prefix; once
+ * cleaned, the path 404s and every session's MCP fails with CONNECTION_CLOSED,
+ * and the health check never caught it (it spawns its OWN bundled server).
+ */
+function createStaleMcpPathCheck() {
+  return {
+    name: "agent-config:karajan-mcp-path",
+    label: "MCP registration path (~/.claude.json)",
+    // KJC-BUG-0172: AUTO, not PROMPT — the runner never remediates a WARN
+    // check whose strategy is PROMPT, so the repair was inert under `kj doctor
+    // -y`. Re-pointing a dead entry to the current server (or dropping it) is
+    // deterministic and reversible on an already-broken entry; `--check-only`
+    // stays available to detect without touching the config.
+    strategy: STRATEGY.AUTO,
+    describe: "Re-point karajan-mcp in ~/.claude.json to this install's server (or drop a dead entry)",
+    async detect() {
+      const claudeJsonPath = path.join(os.homedir(), ".claude.json");
+      let config;
+      try {
+        config = JSON.parse(await fs.readFile(claudeJsonPath, "utf8"));
+      } catch {
+        return { ok: true, severity: "info", detail: "Not present or unparseable (skipped)" };
+      }
+      const registered = karajanMcpServerPath(config);
+      if (!registered) return { ok: true, severity: "info", detail: "karajan-mcp not registered (skipped)" };
+      if (await exists(registered)) return { ok: true, severity: "info", detail: "karajan-mcp path valid" };
+      const correct = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "mcp", "server.js");
+      return {
+        ok: false,
+        severity: "warn",
+        detail: `karajan-mcp points at a path that no longer exists: ${registered} — this is the CONNECTION_CLOSED cause`,
+        fix: `Re-point karajan-mcp to ${correct} (or remove the entry) in ~/.claude.json`,
+        extra: { claudeJsonPath, correct },
+      };
+    },
+    async remediate({ extra }) {
+      try {
+        const config = JSON.parse(await fs.readFile(extra.claudeJsonPath, "utf8"));
+        const action = repairKarajanMcpPath(config, extra.correct, existsSync);
+        if (!action) return { fixed: false, detail: "karajan-mcp entry vanished before repair" };
+        await fs.writeFile(extra.claudeJsonPath, `${JSON.stringify(config, null, 2)}\n`);
+        return {
+          fixed: true,
+          detail: action === "repointed" ? `Re-pointed karajan-mcp to ${extra.correct}` : "Removed the dead karajan-mcp entry",
+        };
+      } catch (err) {
+        return { fixed: false, detail: `Failed to repair ~/.claude.json: ${err.message}` };
+      }
+    },
+  };
+}
+
 /**
  * Codex config (~/.codex/config.toml) validity.
  */
@@ -211,6 +296,7 @@ export function getConfigFileChecks() {
     createReviewRulesCheck(),
     createCoderRulesCheck(),
     createClaudeConfigCheck(),
+    createStaleMcpPathCheck(),
     createCodexConfigCheck(),
     createKjConfigYamlCheck(),
   ];

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/cli/register-pipeline.js

@@ -234,12 +234,15 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--check", "Verify the recorded verdict matches the staged diff (exit 0/1, hook-friendly)")
     .option("--range <range>", "Review a git range (e.g. main..HEAD) instead of the staged diff")
     .option("--install-gate", "Enable the pre-commit review gate for this project (creates .karajan/review-gate)")
+    .option("--prune", "Garbage-collect verdicts in .karajan/reviews older than the TTL (they age out as diffs change)")
+    .option("--prune-days <n>", "TTL in days for --prune (default: 14)")
+    .option("--dry-run", "With --prune: report what would be removed without deleting")
     .option("--no-sonar", "Skip the deterministic Sonar pre-gate that runs before the cross-AI verdict")
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "review", flags, async ({ config, logger }) => {
         // ENV-B1 (KJC-TSK-0637): the gate mode records a verdict tied to
         // the exact diff so the pre-commit hook can enforce cross-AI review.
-        if (flags.staged || flags.check || flags.range || flags.installGate) {
+        if (flags.staged || flags.check || flags.range || flags.installGate || flags.prune) {
           await reviewGateCommand({ config, logger, flags: { ...flags, task } });
           return;
         }

package/src/commands/identity.js

@@ -8,7 +8,7 @@
  *           no session and no flags → exit 1.
  */
 
-import { enrollPhone } from "../harden/phone-sign.js";
+import { addSigner, enrollPhone } from "../harden/phone-sign.js";
 import { readIdentity, writeIdentity } from "../identity/store.js";
 import { activeGhUser, effectiveGitEmail } from "../identity/detect.js";
 import { compareIdentity } from "../identity/compare.js";
@@ -27,12 +27,15 @@ export async function identityCommand({ action = "show", config, flags = {}, dep
   // KJC-TSK-0822: enrola la clave PÚBLICA del móvil (la privada nunca toca esta máquina).
   if (action === "enroll-phone") {
     try {
+      // KJC-TSK-0831 (ADR 0010): añade al PADRÓN versionado del repo (compartible,
+      // base para la verificación en CI) y mantiene la clave legacy en ~/.karajan.
+      addSigner(flags.publicKeyBase64, { projectDir, label: flags.label });
       enrollPhone(flags.publicKeyBase64, { home: deps.home });
     } catch (err) {
       log(`kj identity enroll-phone: ${err.message}`);
       return 1;
     }
-    log("Móvil enrolado: la clave pública quedó en ~/.karajan/supervisor-phone.json. A partir de ahora, sellar el supervisor pedirá la firma de tu móvil.");
+    log("Móvil enrolado: la clave pública se añadió al padrón .karajan/supervisor-signers.json (commítealo) y a ~/.karajan/supervisor-phone.json. Sellar el supervisor pedirá la firma de un móvil del padrón.");
     return 0;
   }
 

package/src/commands/review-gate.js

@@ -8,11 +8,12 @@
 import { existsSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { runCommand } from "../utils/process.js";
-import { checkVerdict, diffHash } from "../review/verdict-store.js";
+import { checkVerdict, diffHash, pruneVerdicts } from "../review/verdict-store.js";
 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.
@@ -144,6 +153,21 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     return { installed: true };
   }
 
+  // KJC-BUG-0173: manual GC of the verdict store. Opportunistic pruning runs
+  // on every saved verdict; this lets a human sweep on demand, with --dry-run
+  // to see what would go without deleting.
+  if (flags.prune) {
+    const dryRun = Boolean(flags.dryRun || flags.checkOnly);
+    const days = Number(flags.pruneDays);
+    const res = await pruneVerdicts({ projectDir, dryRun, ...(Number.isFinite(days) && days > 0 ? { maxAgeDays: days } : {}) });
+    console.log(
+      dryRun
+        ? `kj review --prune (dry run): ${res.expired.length} of ${res.scanned} verdict(s) older than ${res.maxAgeDays}d would be removed`
+        : `kj review --prune: removed ${res.removed} verdict(s) older than ${res.maxAgeDays}d (${res.scanned - res.removed} kept)`,
+    );
+    return { pruned: res.removed, dryRun };
+  }
+
   const diff = await rawDiff(flags.range);
 
   const card = await enforceCardFirst({ config, projectDir });
@@ -312,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}`);
@@ -329,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"]));
@@ -341,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}):`);
@@ -366,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
@@ -388,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/harden/harden-engine.js

@@ -12,7 +12,7 @@ import { join } from "node:path";
 
 import { upsertManagedBlock } from "../utils/managed-markers.js";
 import { runCommand } from "../utils/process.js";
-import { hookBody, PROFILE_HOOKS, SHEBANG } from "./hook-templates.js";
+import { hookBody, PROFILE_HOOKS, SHEBANG, toPortableHooksDir } from "./hook-templates.js";
 
 const BLOCK_VERSION = 1;
 const HOOKS_DIR = join(".karajan", "hooks");
@@ -67,7 +67,10 @@ export async function installHooks({
   const globalCfg = await runCommand("git", ["config", "--global", "core.hooksPath"], { cwd: projectDir });
   const rawGlobal = globalCfg.exitCode === 0 ? globalCfg.stdout.trim() : "";
   if (rawGlobal && rawGlobal !== HOOKS_DIR) {
-    globalHooksDir = rawGlobal.startsWith("~") ? `$HOME${rawGlobal.slice(1)}` : rawGlobal;
+    // KJC-BUG-0169: normalize to a machine-independent form HERE (generation,
+    // on the human's machine) so the provenance stores the portable dir and CI
+    // recomputes the SAME bytes — an absolute home path is not verifiable there.
+    globalHooksDir = toPortableHooksDir(rawGlobal);
   }
 
   const absHooksDir = join(projectDir, HOOKS_DIR);

package/src/harden/hook-templates.js

@@ -27,16 +27,24 @@ export const PROFILE_HOOKS = {
 // hooks dir, silently disabling personal guards. When a previous global dir
 // is known, every generated hook ends by chaining its namesake there —
 // guarded, so machines without it are unaffected.
+// KJC-BUG-0161 / 0169 (ADR 0009): a committed hook must not bake a machine's
+// absolute home path — a dir under the home resolves through $HOME so the same
+// generated content is valid on every machine and its provenance stays
+// verifiable IN CI (a different home), with no local filesystem layout leaking
+// into a public repo. Normalization happens ONCE, at generation, on the human's
+// machine; the stored/rendered value is already portable, so a render on any
+// other home (CI) reproduces identical bytes. `home` is injectable for tests.
+export function toPortableHooksDir(dir, home = homedir()) {
+  if (!dir) return dir;
+  if (dir.startsWith("$HOME")) return dir;
+  if (dir.startsWith("~")) return `$HOME${dir.slice(1)}`;
+  if (dir === home || dir.startsWith(`${home}/`)) return `$HOME${dir.slice(home.length)}`;
+  return dir;
+}
+
 function chainToGlobal(hook, globalHooksDir) {
   if (!globalHooksDir) return [];
-  // KJC-BUG-0161 (ADR 0009): a committed hook must not bake a machine's
-  // absolute home path — resolve through $HOME at runtime so the same
-  // generated content is valid on every machine and its provenance stays
-  // verifiable (and no local filesystem layout leaks into a public repo).
-  const home = homedir();
-  const dir = globalHooksDir === home || globalHooksDir.startsWith(`${home}/`)
-    ? `$HOME${globalHooksDir.slice(home.length)}`
-    : globalHooksDir;
+  const dir = toPortableHooksDir(globalHooksDir);
   return [
     "# Chain the machine's previous global hook (kj harden keeps it active).",
     `if [ -x "${dir}/${hook}" ]; then`,
@@ -114,12 +122,19 @@ export function hookBody(hook, cmds = {}, { globalHooksDir = null, baseBranch =
         "# the same precise pattern (tool MENTIONS stay legal; attribution not).",
         "# The guard's own definition files are excluded by literal path — they",
         "# CONTAIN the pattern; excluding a path that does not exist is harmless.",
-        `if git diff --cached -- . ':(exclude).github/workflows/kj-no-ai-attribution.yml' ':(exclude)src/harden/hook-templates.js' ':(exclude)src/harden/workflow-templates.js' ':(exclude)src/harden/sentinel-hooks.js' ':(exclude)scripts/ai-attribution-guard.yml' ':(exclude)tests/harden/attribution-guard.test.js' ':(exclude)tests/harden/sentinel-hooks.test.js' | grep '^+' | grep -qiE '${AI_ATTRIBUTION}|generated with \\[?claude'; then`,
+        "# KJC-BUG-0170: the generated supervisor hooks (.karajan/hooks/pre-commit,",
+        "# commit-msg) also CONTAIN the pattern by design — the bootstrap commit",
+        "# that versions them must not self-detect in the consumer repo.",
+        `if git diff --cached -- . ':(exclude).github/workflows/kj-no-ai-attribution.yml' ':(exclude)src/harden/hook-templates.js' ':(exclude)src/harden/workflow-templates.js' ':(exclude)src/harden/sentinel-hooks.js' ':(exclude)scripts/ai-attribution-guard.yml' ':(exclude)tests/harden/attribution-guard.test.js' ':(exclude)tests/harden/sentinel-hooks.test.js' ':(exclude).karajan/hooks/pre-commit' ':(exclude).karajan/hooks/commit-msg' | grep '^+' | grep -qiE '${AI_ATTRIBUTION}|generated with \\[?claude'; then`,
         "  echo 'kj harden: AI attribution is not allowed in committed content'; exit 1",
         "fi",
         "# v4 review gate (ENV-C1, opt-in via `kj review --install-gate`):",
         "# a staged diff only enters with a recorded cross-AI approved verdict.",
-        "if [ -f .karajan/review-gate ]; then",
+        "# KJC-BUG-0165: the gate is active once the marker is COMMITTED (HEAD),",
+        "# not merely present — so the bootstrap commit that INTRODUCES it is",
+        "# exempt (no gate can exist before it does), and it cannot be bypassed",
+        "# by deleting the working-tree file.",
+        "if git cat-file -e HEAD:.karajan/review-gate 2>/dev/null; then",
         "  if ! command -v kj >/dev/null 2>&1; then",
         "    echo 'kj: review gate is enabled but kj is not installed — see karajancode.com/docs/getting-started/installation'; exit 1",
         "  fi",