karajan-code 4.35.0 → 4.35.1

package/package.json

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

package/src/audit/harness-scorecard.js

@@ -40,9 +40,16 @@ export function hintForReason(reason, image) {
   }
 }
 
+/**
+ * KJC-BUG-0228 (issue #1840) — OPT-IN. La imagen por defecto es de un tercero y
+ * dejo de existir en el registro publico, asi que el paso venia activo, fallaba
+ * con "pull access denied" y se saltaba en cada `kj audit`. kj no puede depender
+ * por defecto de algo que otro puede borrar: quien quiera el scorecard lo pide,
+ * y quien tenga su propia imagen la declara en `audit.harness.image`.
+ */
 export function normalizeHarnessConfig(h = {}) {
   return {
-    enabled: h.enabled !== false,
+    enabled: h?.enabled === true,
     image: h.image || D.image,
     pullTimeoutMs: pos(h.pull_timeout_ms, D.pullTimeoutMs),
     assessTimeoutMs: pos(h.assess_timeout_ms, D.assessTimeoutMs),

package/src/audit/harness-section.js

@@ -20,7 +20,12 @@ const ts = () => new Date().toISOString().replaceAll(/[:.]/g, "-");
 
 export async function runHarnessSection({ projectDir, harnessConfig = null, runAssess = runHarnessAssess } = {}) {
   const cfg = normalizeHarnessConfig(harnessConfig || {});
-  if (!cfg.enabled) return { ok: true, skipped: true, reason: "disabled" };
+  // KJC-BUG-0228: desactivado por defecto, y DICHO. Un paso que desaparece en
+  // silencio del informe se lee como un paso aprobado.
+  if (!cfg.enabled) {
+    const asked = harnessConfig?.enabled === false;
+    return { ok: true, skipped: true, reason: asked ? "disabled" : "opt-in" };
+  }
   const res = await runAssess(projectDir, cfg);
   if (!res.ok) return { ok: false, error: res.error, reason: res.reason, hint: res.hint, image: cfg.image };
   const outDir = path.join(projectDir, ".karajan", "audit-runs", ts());
@@ -38,7 +43,13 @@ export async function runHarnessSection({ projectDir, harnessConfig = null, runA
 }
 
 export function formatHarnessSection(summary) {
-  if (!summary || summary.skipped) return "";
+  if (!summary) return "";
+  // KJC-BUG-0228: cuando no corre porque nadie lo pidio, se dice como pedirlo.
+  // Callarlo dejaba un informe que parecia completo sin serlo.
+  if (summary.reason === "opt-in") {
+    return "## Harness Scorecard\n\n_not run: it is opt-in (`audit.harness.enabled: true`), and it needs a scorecard image you can pull — declare yours in `audit.harness.image`._\n";
+  }
+  if (summary.skipped) return "";
   if (!summary.ok) {
     const reason = summary.reason ? ` (${summary.reason})` : "";
     const hint = summary.hint ? `\n\n${summary.hint}\n` : "";

package/src/checks/rag-coverage.js

@@ -41,7 +41,10 @@ export function createRagCoverageCheck({ openStore = (dim) => openVecStore({ dim
           const sample = gaps.slice(0, 3).join(", ") + (gaps.length > 3 ? ", …" : "");
           return { ok: false, severity: "fail", detail: `${c.missing.length} source(s) outside the RAG index, ${c.stale.length} stale (${sample}) — ${fix}` };
         }
-        return { ok: true, severity: "info", detail: `${c.indexed}/${c.total} sources indexed at ${c.lastIndexedCommit.slice(0, 9)}` };
+        // KJC-BUG-0221: lo que kj genera no se exige indexado, pero se dice —
+        // una exencion que no se ve es indistinguible de un gate que dejo de mirar.
+        const generated = c.generated?.length ? `, ${c.generated.length} generated by kj (not required)` : "";
+        return { ok: true, severity: "info", detail: `${c.indexed}/${c.total} sources indexed at ${c.lastIndexedCommit.slice(0, 9)}${generated}` };
       } finally {
         db.close();
       }

package/src/checks/runner.js

@@ -92,8 +92,14 @@ export async function runChecks(checks, ctx, options = {}) {
     entries.map(async (entry) => {
       if (entry.status === STATUS.SKIPPED) return;
       const start = Date.now();
+      // Per-check override: checks that spawn slow tools (e.g. `npx <pkg>` cold
+      // start) declare detectTimeoutMs so the blanket pipeline timeout doesn't
+      // kill them. Falls back to the pipeline-wide timeoutMs.
+      const detectTimeoutMs = Number.isFinite(entry.check.detectTimeoutMs)
+        ? entry.check.detectTimeoutMs
+        : timeoutMs;
       try {
-        const result = await withTimeout(entry.check.detect({ config, signal }), timeoutMs, entry.check.name);
+        const result = await withTimeout(entry.check.detect({ config, signal }), detectTimeoutMs, entry.check.name);
         entry.detectResult = result;
         entry.runMs = Date.now() - start;
         entry.status = resolveStatusFromDetect(entry.check, result);
@@ -112,9 +118,21 @@ export async function runChecks(checks, ctx, options = {}) {
       } catch (err) {
         entry.runMs = Date.now() - start;
         if (err instanceof TimeoutError) {
-          entry.detectResult = { ok: false, severity: "warn", detail: `Timeout after ${timeoutMs}ms` };
-          entry.status = STATUS.TIMEOUT;
-          entry.detail = entry.detectResult.detail;
+          entry.detectResult = { ok: false, severity: "warn", detail: `Timeout after ${detectTimeoutMs}ms` };
+          // A timeout on a degradable (optional) check must not block the
+          // pipeline: degrade to WARN and disable its feature flags, same as
+          // a regular failure (KJC-BUG-0049 semantics).
+          if (entry.check.degradable) {
+            for (const dotPath of entry.check.degradable.disables || []) {
+              setDotPath(overrides, dotPath, false);
+            }
+            entry.status = STATUS.WARN;
+            entry.detail = `${entry.detectResult.detail} → ${entry.check.degradable.warn}`;
+            entry.degraded = true;
+          } else {
+            entry.status = STATUS.TIMEOUT;
+            entry.detail = entry.detectResult.detail;
+          }
         } else {
           entry.detectResult = { ok: false, severity: "fail", detail: `Detection error: ${err.message}` };
           entry.status = STATUS.FAIL;
@@ -172,7 +190,11 @@ export async function runChecks(checks, ctx, options = {}) {
       entries.filter((e) => e.remediated).map(async (entry) => {
         const start = Date.now();
         try {
-          const result = await withTimeout(entry.check.detect({ config: verifyConfig, signal }), timeoutMs, `${entry.check.name}:reverify`);
+          const result = await withTimeout(
+            entry.check.detect({ config: verifyConfig, signal }),
+            Number.isFinite(entry.check.detectTimeoutMs) ? entry.check.detectTimeoutMs : timeoutMs,
+            `${entry.check.name}:reverify`
+          );
           entry.runMs += Date.now() - start;
           if (!result.ok) {
             entry.status = STATUS.FAIL;

package/src/checks/skills.js

@@ -23,6 +23,16 @@ export function createOpenSkillsCheck() {
     strategy: STRATEGY.PROMPT,
     applies: skillsEnabled,
     describe: "Install OpenSkills globally: npm install -g openskills",
+    // Detection shells out to `npx openskills --version`; a cold npx cache
+    // downloads the package first (~8s observed), well above the pipeline's
+    // 3s blanket timeout. Must exceed openskills-client's internal 15s timeout.
+    detectTimeoutMs: 20_000,
+    // Optional feature: even if detection times out, degrade instead of
+    // blocking the whole preflight (skill injection is skipped for the run).
+    degradable: {
+      disables: ["skills.enabled"],
+      warn: "skill auto-install disabled for this run",
+    },
     async detect() {
       const available = await isOpenSkillsAvailable();
       if (available) {

package/src/checks/types.js

@@ -59,7 +59,11 @@
  * @property {DegradableSpec} [degradable]       - KJC-BUG-0049: si está definido y el check falla, en lugar de abortar
  *                                                  el preflight, se desactivan los flags listados en `disables` y se emite
  *                                                  WARN con `warn`. Útil para features opcionales (auto_pr, auto_push,
- *                                                  sonar advisory, etc.) que no son blockers absolutos.
+ *                                                  sonar advisory, etc.) que no son blockers absolutos. También aplica
+ *                                                  cuando el detect agota su timeout (timeout → WARN, no TIMEOUT).
+ * @property {number} [detectTimeoutMs]          - per-check detect timeout override. Use for checks that spawn slow
+ *                                                  tools (e.g. `npx <pkg>` cold start) where the pipeline-wide
+ *                                                  timeoutMs would kill an otherwise healthy detect.
  */
 
 /**

package/src/commands/review-gate.js

@@ -386,8 +386,8 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
       console.log(`⚠ rag [${RAG_RULE_ID}]: the pipeline verdict carries no session ledger — the headless pipeline does not consult the RAG yet; sealed as a warn`);
       if (!warnIds.includes(RAG_RULE_ID)) warnIds.push(RAG_RULE_ID);
     } else if (res.ok) {
-      const { harness, verified, mismatched } = readRagLedger(projectDir);
-      const rreq = checkRagVerdict({ config, stagedFiles: changedFiles, rag: res.verdict.rag, harness, verified, mismatched, standingExceptions: std.standing });
+      const { harness, verified, mismatched, drift } = readRagLedger(projectDir);
+      const rreq = checkRagVerdict({ config, stagedFiles: changedFiles, rag: res.verdict.rag, harness, verified, mismatched, drift, standingExceptions: std.standing });
       if (!rreq.ok) res = { ok: false, verdict: res.verdict, reason: rreq.reason };
       else if (rreq.mode === "granted" && rreq.grant) console.log(formatRagGrant(rreq.grant));
     }

package/src/harden/config-templates.js

@@ -118,6 +118,17 @@ export const GO_CONFIGS = [{ file: ".golangci.yml", blockId: "golangci", style:
 export const PHPSTAN_BODY = ["parameters:", "  level: 6", "  paths:", "    - src", "    - tests"].join("\n");
 export const PHP_CONFIGS = [{ file: "phpstan.neon", blockId: "phpstan", style: "hash", body: PHPSTAN_BODY }];
 
+
+/**
+ * KJC-BUG-0221 — los nombres que kj ESCRIBE en el proyecto. Lo consume la
+ * cobertura del RAG para no denunciar como drift un fichero que kj acaba de
+ * generar. Se deriva de las tablas de arriba: anadir un config aqui no obliga
+ * a acordarse de una segunda lista en otro modulo.
+ */
+export const GENERATED_CONFIG_FILES = new Set(
+  [...UNIVERSAL_CONFIGS, ...JS_CONFIGS, ...PY_CONFIGS, ...GO_CONFIGS, ...PHP_CONFIGS].map((c) => c.file),
+);
+
 /** Lint/format configs by detected language. Unknown ⇒ universal only. */
 export const CONFIGS_BY_LANGUAGE = {
   javascript: JS_CONFIGS,

package/src/harden/harness-hooks.js

@@ -9,6 +9,7 @@
  * supports tool hooks.
  */
 
+import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
@@ -18,7 +19,11 @@ const SCRIPT_BODY = `#!/usr/bin/env node
 // so a gate bug never bricks the session.
 import console from "node:console";
 import process from "node:process";
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+// El guard vive en <repo>/.karajan/harness/, asi que el arbol es dos arriba.
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 let raw = "";
 process.stdin.on("data", (d) => { raw += d; });
 process.stdin.on("end", () => {
@@ -30,10 +35,75 @@ process.stdin.on("end", () => {
         process.exit(2);
       }
     }
-    if (tool === "Bash" && process.env.KJ_ALLOW_REWRITE !== "1") {
+    if (tool === "Bash") {
       const cmd = String(input.command || "");
+      // KJC-BUG-0227: el escape tambien viaja en el PROPIO comando, como en el
+      // resto de guardias. Mirando solo process.env el agente no tenia salida:
+      // un export dentro del comando jamas llega a este proceso.
+      // Solo cuentan las asignaciones DEL PRINCIPIO, que son las que el shell
+      // aplica al comando. Buscarla en cualquier parte del texto dejaba pasar
+      // un "echo KJ_ALLOW_REWRITE=1; python3 ..." (catch de la review).
+      const toks = cmd.trim().split(/\\s+/);
+      let i = 0;
+      let named = false;
+      while (i < toks.length && /^[A-Z][A-Z0-9_]*=/.test(toks[i])) {
+        if (toks[i] === "KJ_ALLOW_REWRITE=1") named = true;
+        i += 1;
+      }
+      // Una asignacion delante solo alcanza a SU comando, asi que el escape del
+      // comando vale unicamente en un comando SIMPLE: en "VAR=1 true && python"
+      // o "VAR=1 && python" el python nunca la recibe (catch de la review). Lo
+      // que va entre comillas no encadena nada, asi que no cuenta.
+      // Tampoco es simple si hay sustitucion: el proceso de dentro de $( ) no
+      // hereda la asignacion (catch de la review). Mismo criterio que el resto
+      // de guardias del Sentinel.
+      // Dentro de comillas SIMPLES todo es literal; dentro de dobles, un ; no
+      // encadena pero $( ) si ejecuta. Por eso se miran dos cosas distintas.
+      const noSingle = cmd.replaceAll(/'[^']*'/g, "");
+      const substitutes = noSingle.includes("$(") || noSingle.includes("\\u0060");
+      const bare = noSingle.replaceAll(/"[^"]*"/g, "");
+      const simple = !substitutes && !/[;&|]/.test(bare) && !bare.includes("\\n");
+      const cmdEscape = named && simple && i < toks.length;
+      const escaped = process.env.KJ_ALLOW_REWRITE === "1" || cmdEscape;
+      // Un escape ignorado EN SILENCIO era el bug: si esta puesto y no vale, se dice.
+      if (named && !cmdEscape) console.error("kj tool gate: KJ_ALLOW_REWRITE=1 presente pero IGNORADO — solo vale delante del comando y en uno simple (sin ; | & fuera de comillas).");
       const writes = /open\\s*\\([^)]*["'][wa]["']|>\\s*\\S+\\.json\\b/.test(cmd);
-      if (/json\\.dumps?\\s*\\(/.test(cmd) && writes) {
+      // KJC-BUG-0227: y solo se vigila lo que esta DENTRO del arbol. Un fichero
+      // temporal del scratchpad no es asunto de este guard, y bloquearlo
+      // ensenaba a rodearlo. Sin ruta reconocible se vigila: el lado seguro.
+      const targets = cmd.match(/[\\w./-]+\\.json\\b/g) || [];
+      // Solo se exime lo que se puede establecer CON CERTEZA: una ruta absoluta
+      // fuera del arbol. Una relativa depende del cwd del shell, que este hook
+      // no conoce — "cd packages && ... open(\\"../package.json\\")" escribe
+      // dentro del repo (catch de la review), asi que se sigue vigilando.
+      // Un enlace puede apuntar dentro: /tmp/link.json escribiria en el repo
+      // (catch de la review). Se resuelve el padre real antes de clasificar, y
+      // si no se puede resolver, se vigila.
+      // Fuera del arbol es SALIR de el, no que el nombre empiece por dos puntos:
+      // <repo>/..config.json esta dentro (catch de la review).
+      const escapesRoot = (rel) => rel === ".." || rel.startsWith("../");
+      const outsideForSure = (t) => {
+        if (!t.startsWith("/")) return false;
+        const abs = resolve(t);
+        try {
+          const root = realpathSync(ROOT);
+          // El propio fichero puede SER el enlace (/tmp/link.json -> repo/cfg.json),
+          // asi que se resuelve entero cuando existe; si aun no existe, manda su
+          // directorio real.
+          if (existsSync(abs)) return escapesRoot(relative(root, realpathSync(abs)));
+          const parts = abs.split("/");
+          const name = parts.pop();
+          return escapesRoot(relative(root, realpathSync(parts.join("/") || "/") + "/" + name));
+        } catch {
+          return false;
+        }
+      };
+      // Con expansion del shell no se sabe a donde apunta nada: "$PWD/cfg.json"
+      // deja el trozo "/cfg.json", que parece absoluto y ajeno sin serlo (catch
+      // de la review). Ante la duda se vigila.
+      const expands = /[$~]/.test(cmd) || cmd.includes("\\u0060");
+      const mine = expands || targets.length === 0 || !targets.every(outsideForSure);
+      if (!escaped && mine && /json\\.dumps?\\s*\\(/.test(cmd) && writes) {
         console.error("kj tool gate: reserializing a whole JSON file makes the diff unreviewable — make targeted edits instead (KJ_ALLOW_REWRITE=1 to override consciously).");
         process.exit(2);
       }
@@ -100,8 +170,27 @@ export function mergeClaudeHooks({ projectDir, logger = console, entries }) {
   return { wired: true };
 }
 
+/**
+ * La raiz del proyecto: el toplevel de git, o el directorio dado si no hay git.
+ * Vive aqui y no se importa de sentinel-hooks porque ese modulo importa de
+ * este: el ciclo rompe la carga.
+ */
+function resolveProjectRoot(dir) {
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || dir;
+  } catch {
+    return dir;
+  }
+}
+
 /** Write the script and merge the PreToolUse entries into .claude/settings.json. */
 export function installHarnessHooks({ projectDir = process.cwd(), logger = console } = {}) {
+  // KJC-BUG-0223: el harness es del proyecto y vive en su raiz. Instalado desde
+  // un subdirectorio sembraba ahi un segundo `.karajan/harness` que no gobierna
+  // nada, y el gate seguia mirando otro sitio.
+  const root = resolveProjectRoot(projectDir);
+  if (root !== projectDir) logger?.info?.(`kj harden: el harness es del proyecto, se instala en su raíz (${root})`);
+  projectDir = root;
   const scriptAbs = writeHarnessScript(projectDir, "pretooluse.mjs", SCRIPT_BODY);
   const { wired } = mergeClaudeHooks({
     projectDir,

package/src/harden/sentinel-hooks.js

@@ -1198,7 +1198,11 @@ export function verifySentinelScripts({ projectDir, readFileFn = readFileSync, g
     ok: true,
     mismatched: [],
     drift,
-    reason: "el harness instalado está sellado y las plantillas de este árbol van por delante (kj harden lo pone al día) — no es manipulación",
+    // KJC-BUG-0222: `kj harden` NO pone al dia un guard sellado, lo deja en paz
+    // a proposito (KJC-BUG-0193), asi que mandarlo era un bucle: ejecutas,
+    // sale "unchanged" y el gate repite lo mismo. El que resuelve ESTE estado
+    // es `kj harden --commit`, y es acto del humano.
+    reason: "el harness instalado está sellado y las plantillas de este árbol van por delante — no es manipulación, y `kj harden` lo deja como está a propósito: quien lo avanza es el humano con `kj harden --commit`",
   };
 }
 
@@ -1214,6 +1218,13 @@ export function verifySentinelScripts({ projectDir, readFileFn = readFileSync, g
  * guard is still the right move.
  */
 export function installSentinelHooks({ projectDir = process.cwd(), logger = console, human = false, gitShowFn = null } = {}) {
+  // KJC-BUG-0223: instalado desde un subdirectorio, esto sembraba un segundo
+  // `.karajan/harness` ahi, y el gate (que mira otro sitio) pasaba a verlo. El
+  // ritual quedaba "arreglado" y el arbol se llenaba de arneses huerfanos que
+  // no gobiernan nada. El harness es del proyecto: va a su raiz.
+  const root = resolveSentinelRoot(projectDir);
+  if (root !== projectDir) logger?.info?.(`kj harden: el harness es del proyecto, se instala en su raíz (${root})`);
+  projectDir = root;
   const sealed = human ? new Map() : sealedByPath(projectDir, gitShowFn);
   const deferred = [];
   const keepsItsSeal = (name) => {

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

@@ -322,7 +322,7 @@ export async function runPreLoopStages({ config, logger, emitter, eventBase, ses
   // Hard fail if blocking checks failed (SonarQube enabled but not available)
   if (!preflightResult.ok) {
     const errorLines = (preflightResult.errors || [])
-      .map(e => `  - ${e.message}\n    Fix: ${e.fix}`)
+      .map(e => `  - ${e.message}${e.fix ? `\n    Fix: ${e.fix}` : ""}`)
       .join("\n");
     throw new Error(
       `Preflight FAILED — environment changed during session. Fix the issues and retry:\n${errorLines}`

package/src/rag/coverage.js

@@ -10,8 +10,27 @@
 import { execa } from "execa";
 import { extname, isAbsolute, normalize, relative } from "node:path";
 import { detectAdaptersForProject, buildMatchers } from "../lang/registry.js";
+import { GENERATED_CONFIG_FILES } from "../harden/config-templates.js";
 import { getLastIndexedCommit, projectSlug } from "./vec-store.js";
 
+
+/**
+ * KJC-BUG-0221 — `kj harden` instala commitlint.config.js y eslint.config.js, y
+ * la cobertura los exigia indexados, asi que `kj check` denunciaba como drift
+ * dos ficheros que kj mismo acababa de escribir: la herramienta creando el
+ * fichero y quejandose de el. El criterio es el que ya usa el presupuesto de
+ * LOC (src/review/loc-budget.js): lo generado no cuenta, porque nadie lo
+ * escribio, y el RAG existe para responder sobre el codigo del equipo.
+ *
+ * La lista sale de la propia tabla de plantillas de harden, para que anadir un
+ * config no obligue a acordarse de esta otra lista.
+ */
+export function isGeneratedByHarden(rel) {
+  if (!rel) return false;
+  const base = rel.split("/").pop();
+  return GENERATED_CONFIG_FILES.has(base);
+}
+
 /**
  * @param {string} projectDir
  * @param {{db: object}} deps - an open vec store
@@ -21,7 +40,10 @@ export async function ragIndexCoverage(projectDir, { db }) {
   const project = projectSlug(projectDir);
   const matchers = buildMatchers(detectAdaptersForProject(projectDir));
   const { stdout } = await execa("git", ["-C", projectDir, "ls-files", "-z"]);
-  const sources = stdout.split("\0").filter((p) => p && matchers.isCodeFile(p) && !matchers.shouldSkip(p));
+  const all = stdout.split("\0").filter((p) => p && matchers.isCodeFile(p) && !matchers.shouldSkip(p));
+  // Lo que kj genera se informa aparte: ni se exige indexado ni se esconde.
+  const generated = all.filter(isGeneratedByHarden);
+  const sources = all.filter((p) => !isGeneratedByHarden(p));
 
   const rows = db.prepare("SELECT DISTINCT source FROM chunks WHERE kind = 'code' AND project_slug = ?").all(project);
   const indexed = new Set(rows.map((r) => (isAbsolute(r.source) ? relative(projectDir, r.source) : r.source)));
@@ -44,7 +66,7 @@ export async function ragIndexCoverage(projectDir, { db }) {
     stale = sources.filter((p) => indexed.has(p) && changed.has(p));
   }
 
-  return { project, total: sources.length, indexed: sources.length - missing.length, missing, stale, lastIndexedCommit, absent: indexed.size === 0 };
+  return { project, total: sources.length, indexed: sources.length - missing.length, missing, stale, generated, lastIndexedCommit, absent: indexed.size === 0 };
 }
 
 /**

package/src/review/gate-gitignore.js

@@ -57,7 +57,29 @@ export async function ensureContractBlockPresent(projectDir) {
  * La ruta se pregunta a git para que funcione tambien en un worktree, donde
  * `.git` es un fichero y no un directorio.
  */
-const LOCAL_ARTIFACTS = [".reviews/", ".kj/", ".kj-ready.json"];
+const LOCAL_ARTIFACTS = [
+  ".reviews/", ".kj/", ".kj-ready.json",
+  // KJC-BUG-0220: lo que kj escribe DENTRO de .karajan/ y NO viaja. Sin esto
+  // se quedaba en tierra de nadie (ni versionado ni ignorado) y salia como `??`
+  // en cada git status del equipo. Se enumera en vez de ignorar .karajan/
+  // entero a proposito: kj.config.yml y las reglas del agente son del equipo, y
+  // esconderselas seria decidir por ellos. Los ficheros del supervisor viajan
+  // por su cauce sellado (ADR 0009) y tampoco entran aqui.
+  ".karajan/harness/",            // el arnes del anfitrion: cada maquina lo regenera
+  ".karajan/policy-decisions.jsonl",
+  ".karajan/policy-exceptions.jsonl",
+  ".karajan/identity.local.yml",  // identidad por clon (ADR 0005)
+  ".karajan/sentinel-state.json",
+  ".karajan/rag.db",
+  ".karajan/audit-history.db",
+  ".karajan/update-check.json",
+  ".karajan/karajan.env",
+  ".karajan/agent-skills/",
+  ".karajan/audits/",
+  ".karajan/reviews/",
+  ".karajan/steward/",
+  ".karajan/plans/",
+];
 
 export async function excludeLocalArtifacts(projectDir, run = runCommand) {
   let file = path.join(projectDir, ".git", "info", "exclude");

package/src/review/kj-provenance.js

@@ -0,0 +1,42 @@
+/**
+ * kj-provenance — KJC-BUG-0222. Un gate que dice QUE falla sin decir CONTRA QUE
+ * compara ensena a saltarselo. El aviso del harness decia "does not match the
+ * installed kj" y ahi acababa, asi que en campo se leyo como "kj se
+ * desincroniza solo": una sesion se monto el ritual de ejecutar `kj harden`
+ * antes de cada review y de cada commit, veinte veces en un dia, sin
+ * preguntarse por que. La causa estaba entera en el dato que faltaba: ese kj
+ * estaba npm-linkado a un arbol de desarrollo cuyas plantillas cambiaron seis
+ * veces en dos dias.
+ *
+ * Saltarse un gate ritualmente es peor que no tenerlo, porque parece que se
+ * cumple.
+ */
+import { createRequire } from "node:module";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Que kj esta juzgando: version, de donde sale y si es un paquete instalado o
+ * un arbol de desarrollo enlazado. Nunca lanza: esto SOLO adorna un mensaje, y
+ * un fallo aqui jamas puede cambiar el veredicto de un gate.
+ *
+ * @returns {{version: string|null, root: string, linked: boolean, label: string}}
+ */
+export function kjProvenance(moduleDir = here) {
+  const root = resolve(moduleDir, "..", "..");
+  let version = null;
+  try {
+    version = createRequire(import.meta.url)(resolve(root, "package.json")).version || null;
+  } catch { /* sin manifest legible: se dice lo que se sabe */ }
+  // Un kj instalado vive bajo node_modules. Cualquier otra ruta es un arbol de
+  // trabajo enlazado (npm link), y entonces sus plantillas se mueven con cada
+  // edicion de quien lo desarrolla, en TODOS los proyectos de la maquina.
+  const linked = !root.includes(`${"node_modules"}/karajan-code`) && !root.endsWith("node_modules");
+  const v = version ? `kj ${version}` : "an unknown kj";
+  const label = linked
+    ? `${v} LINKED from ${root} (a development tree: its templates move with every edit there, in every project on this machine)`
+    : `${v} (${root})`;
+  return { version, root, linked, label };
+}

package/src/review/rag-ledger.js

@@ -9,7 +9,7 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
-import { verifySentinelScripts } from "../harden/sentinel-hooks.js";
+import { resolveSentinelRoot, verifySentinelScripts } from "../harden/sentinel-hooks.js";
 
 /**
  * @param {string} projectDir
@@ -22,10 +22,18 @@ import { verifySentinelScripts } from "../harden/sentinel-hooks.js";
  *   the requirement fails closed until the human re-runs `kj harden`.
  */
 export function readRagLedger(projectDir) {
-  const harnessDir = path.join(projectDir, ".karajan", "harness");
+  // KJC-BUG-0223: el harness vive en la RAIZ del proyecto. Este modulo miraba
+  // el directorio recibido (en la practica, process.cwd()) mientras el
+  // verificador resolvia el toplevel de git, asi que desde un subdirectorio los
+  // dos juzgaban sobre arboles distintos y el gate bloqueaba siempre.
+  const root = resolveSentinelRoot(projectDir);
+  const harnessDir = path.join(root, ".karajan", "harness");
   const harness = existsSync(harnessDir);
-  const check = harness ? verifySentinelScripts({ projectDir }) : { ok: false, mismatched: [] };
-  const base = { harness, verified: harness && check.ok === true, mismatched: check.mismatched || [], queries: [], hits: [] };
+  const check = harness ? verifySentinelScripts({ projectDir: root }) : { ok: false, mismatched: [] };
+  // KJC-BUG-0222: `drift` viaja hasta el mensaje. Un guard sellado que se ha
+  // quedado atras NO lo arregla `kj harden` (lo deja en paz a proposito), asi
+  // que mandar ese comando para ese fichero es un bucle.
+  const base = { root, harness, verified: harness && check.ok === true, mismatched: check.mismatched || [], drift: check.drift || [], queries: [], hits: [] };
   let state;
   try {
     state = JSON.parse(readFileSync(path.join(harnessDir, "sentinel-state.json"), "utf8"));

package/src/review/rag-requirement.js

@@ -12,6 +12,7 @@
  * concepts that are not in the diff. That list travels to the reviewer,
  * because the bugs of 2026-09-16 were exactly the twin nobody touched.
  */
+import { kjProvenance } from "./kj-provenance.js";
 import { sourceFilesOf } from "./tests-with-code.js";
 
 export const RAG_RULE_ID = "method.rag.code";
@@ -30,6 +31,17 @@ function liveGrant(standingExceptions, now) {
  * @param {{available: boolean, reason?: string, queries: object[], hits: string[]}} [args.ledger]
  * @returns {{ok: boolean, mode: "docs-only"|"pass"|"granted"|"block", reason?: string, grant?: object, sources?: string[], queries?: number, covered?: string[], uncovered?: string[], twinsUntouched?: string[]}}
  */
+/**
+ * KJC-BUG-0222 — el comando que resuelve ESTE estado. `kj harden` repone lo que
+ * nadie sello; un guard sellado que se ha quedado atras lo deja en paz a
+ * proposito (KJC-BUG-0193), y avanzarlo es acto humano.
+ */
+function harnessRemedy(drift = []) {
+  return drift.length > 0
+    ? `the human runs \`kj harden\` to restore them, and \`kj harden --commit\` for the sealed ones (${drift.join(", ")}), which \`kj harden\` leaves untouched on purpose`
+    : "the human runs `kj harden` to regenerate it";
+}
+
 export function checkRagRequirement({ config = {}, stagedFiles = [], newFiles = [], ledger, standingExceptions = [], now = new Date(), env = {} }) {
   const { sources } = sourceFilesOf(config, stagedFiles);
   if (sources.length === 0) return { ok: true, mode: "docs-only" };
@@ -55,7 +67,9 @@ export function checkRagRequirement({ config = {}, stagedFiles = [], newFiles =
   // than the ledger) cannot vouch for anything: fail closed, like the tamper
   // check does, until the human regenerates it.
   if (ledger?.harness === true && ledger?.verified === false) {
-    return { ok: false, mode: "block", sources, reason: `${head} — the Sentinel harness does not match the installed kj (${(ledger.mismatched || []).join(", ") || "scripts missing"}): the human runs \`kj harden\` to regenerate it before code is reviewed. ${GRANT_HINT}` };
+    // KJC-BUG-0222: decir CONTRA QUE no coincide. Sin ese dato el aviso se lee
+    // como "kj se desincroniza solo" y se automatiza el sintoma.
+    return { ok: false, mode: "block", sources, reason: `${head} — the installed Sentinel harness does not match the templates of ${kjProvenance().label} (${(ledger.mismatched || []).join(", ") || "scripts missing"}): ${harnessRemedy(ledger.drift)} before code is reviewed. ${GRANT_HINT}` };
   }
   if (!ledger?.available) {
     return { ok: false, mode: "block", sources, reason: `${head} — ${ledger?.reason || "no session ledger"}: consult the RAG about the change (kj_rag_query / kj rag query) and run \`kj review --staged\` again. ${GRANT_HINT}` };
@@ -82,7 +96,7 @@ export function checkRagRequirement({ config = {}, stagedFiles = [], newFiles =
  * block — the diff hash pins the file set, so a source missing from
  * `covered` was never answered about, whatever the block claims.
  */
-export function checkRagVerdict({ config = {}, stagedFiles = [], rag, harness = true, verified = true, mismatched = [], standingExceptions = [], now = new Date() }) {
+export function checkRagVerdict({ config = {}, stagedFiles = [], rag, harness = true, verified = true, mismatched = [], drift = [], standingExceptions = [], now = new Date() }) {
   const { sources } = sourceFilesOf(config, stagedFiles);
   if (sources.length === 0) return { ok: true, mode: "docs-only" };
   const grant = liveGrant(standingExceptions, now);
@@ -94,7 +108,7 @@ export function checkRagVerdict({ config = {}, stagedFiles = [], rag, harness =
     return { ok: false, mode: "block", sources, reason: `${head} — no Sentinel harness in this tree, so no session ledger can exist: install it with \`kj harden\`. ${GRANT_HINT}` };
   }
   if (!verified) {
-    return { ok: false, mode: "block", sources, reason: `${head} — the Sentinel harness does not match the installed kj (${mismatched.join(", ") || "scripts missing"}): the human runs \`kj harden\` to regenerate it. ${GRANT_HINT}` };
+    return { ok: false, mode: "block", sources, reason: `${head} — the installed Sentinel harness does not match the templates of ${kjProvenance().label} (${mismatched.join(", ") || "scripts missing"}): ${harnessRemedy(drift)}. ${GRANT_HINT}` };
   }
   if (!rag) {
     return { ok: false, mode: "block", sources, reason: `${head} — the verdict carries no rag block; run \`kj review --staged\` again. ${GRANT_HINT}` };

package/src/sonar/api.js

@@ -82,8 +82,17 @@ async function sonarFetch(config, urlPath) {
   );
 }
 
+/**
+ * KJC-BUG-0226 (issue #1838) — de donde sale la clave que se CONSULTA. El
+ * scanner sube el analisis con la que el repo declara en su
+ * sonar-project.properties; preguntando por otra (la derivada del remote), el
+ * audit acababa listando issues de repos ajenos del mismo SonarQube. Pasando
+ * el directorio, la resolucion lee esa misma clave declarada.
+ */
+const queryCwd = (config) => config?.projectDir || process.cwd();
+
 export async function getQualityGateStatus(config, projectKey = null) {
-  const effectiveProjectKey = await resolveSonarProjectKey(config, { projectKey });
+  const effectiveProjectKey = await resolveSonarProjectKey(config, { projectKey, cwd: queryCwd(config) });
   const body = await sonarFetch(config, `/api/qualitygates/project_status?projectKey=${effectiveProjectKey}`);
 
   try {
@@ -95,7 +104,7 @@ export async function getQualityGateStatus(config, projectKey = null) {
 }
 
 export async function getOpenIssues(config, projectKey = null) {
-  const effectiveProjectKey = await resolveSonarProjectKey(config, { projectKey });
+  const effectiveProjectKey = await resolveSonarProjectKey(config, { projectKey, cwd: queryCwd(config) });
   const body = await sonarFetch(config, `/api/issues/search?projectKeys=${effectiveProjectKey}&statuses=OPEN`);
 
   let parsedIssues = [];

package/src/sonar/project-key.js

@@ -1,4 +1,7 @@
 import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
 import { runCommand } from "../utils/process.js";
 
 function slug(value) {
@@ -55,6 +58,27 @@ function canonicalRepoId(remoteUrl) {
   return `${host}/${segments.join("/")}`;
 }
 
+/**
+ * KJC-BUG-0226 (issue #1838) — la clave que el REPO declara en su
+ * sonar-project.properties es la que el servidor conoce, porque es con la que
+ * el scanner sube el analisis. Sin leerla aqui, kj escaneaba un proyecto y
+ * preguntaba por otro (una clave derivada del remote), y el audit acababa
+ * listando issues de repos ajenos del mismo SonarQube.
+ *
+ * Sincrono y tolerante: sin fichero, ilegible o sin la clave, se sigue por
+ * donde se iba.
+ */
+function declaredProjectKey(cwd) {
+  try {
+    const raw = fs.readFileSync(path.join(cwd, "sonar-project.properties"), "utf8");
+    for (const line of raw.split("\n")) {
+      const m = /^\s*sonar\.projectKey\s*=\s*(.+?)\s*$/.exec(line);
+      if (m) return m[1];
+    }
+  } catch { /* sin properties legible: se deriva como siempre */ }
+  return null;
+}
+
 export async function resolveSonarProjectKey(config, options = {}) {
   const explicit = String(
     options.projectKey || process.env.KJ_SONAR_PROJECT_KEY || config?.sonarqube?.project_key || ""
@@ -63,6 +87,15 @@ export async function resolveSonarProjectKey(config, options = {}) {
     return normalizeProjectKey(explicit);
   }
 
+  // KJC-BUG-0226: lo que el repo declara manda sobre lo que kj derivaria, que
+  // es justo lo que el scanner ya hace al subir el analisis. Solo con un `cwd`
+  // explicito: quien no dice que directorio le importa se queda como estaba, y
+  // asi esto no cambia el comportamiento de nadie mas que el de la consulta.
+  if (options.cwd) {
+    const declared = declaredProjectKey(options.cwd);
+    if (declared) return normalizeProjectKey(declared);
+  }
+
   const remote = await runCommand("git", ["config", "--get", "remote.origin.url"]);
   const remoteUrl = String(remote.stdout || "").trim();
   if (remote.exitCode !== 0 || !remoteUrl) {

package/src/sonar/scanner.js

@@ -50,8 +50,38 @@ export function indexedFilesFrom(scanOutput) {
   return files;
 }
 
-export function buildScannerOpts(projectKey, scanner = {}) {
+/**
+ * KJC-BUG-0225 — `.git` es un fichero (no un directorio) en un worktree
+ * enlazado y en un submodulo: exactamente los dos casos que JGit no sabe abrir.
+ * Sin proceso y sin depender de que git responda.
+ */
+export function isLinkedWorktree(dir) {
+  try {
+    return fs.statSync(path.join(dir, ".git")).isFile();
+  } catch {
+    return false; // sin .git no hay SCM que desactivar
+  }
+}
+
+/**
+ * KJC-BUG-0225 (issue #1839) — dentro de un carril de `kj worktree start`, el
+ * plugin SCM del scanner (JGit) no sabe abrir un worktree enlazado (`.git` es
+ * un fichero que apunta a `.git/worktrees/<carril>`) y revienta el analisis
+ * entero. El pre-gate lo reportaba como "UNAVAILABLE" y la ejecucion seguia:
+ * todo cambio hecho como el metodo manda, un carril por tarea, se quedaba sin
+ * quality gate y sin un rojo que lo dijera.
+ *
+ * Se desactiva SOLO el SCM, que en un carril no aporta nada (alimenta blame y
+ * asignacion de autoria); las reglas, la cobertura y el resto del analisis se
+ * quedan exactamente igual.
+ *
+ * @param {string} projectKey
+ * @param {object} scanner  config del scanner (scm_disabled lo fuerza siempre)
+ * @param {{linkedWorktree?: boolean}} [where]
+ */
+export function buildScannerOpts(projectKey, scanner = {}, where = {}) {
   const opts = [`-Dsonar.projectKey=${projectKey}`];
+  if (scanner.scm_disabled || where.linkedWorktree) opts.push("-Dsonar.scm.disabled=true");
   // 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}`);
@@ -317,11 +347,16 @@ export async function runSonarScan(config, projectKey = null, { verbose = false,
     : null;
 
   const pick = await pickSonarScanner(sonarConfig.scanner);
+  // KJC-BUG-0225: en un carril, el plugin SCM del scanner (JGit) no sabe abrir
+  // el worktree enlazado y tumba el analisis entero. La senal es la causa
+  // literal del error y no necesita proceso: en un worktree enlazado (y en un
+  // submodulo, que JGit trata igual) `.git` es un FICHERO, no un directorio.
+  const linkedWorktree = isLinkedWorktree(scanCwd);
   const env = {
     ...process.env,
     SONAR_HOST_URL: pick.type === "native" ? rawHost : host,
     SONAR_TOKEN: token || "",
-    SONAR_SCANNER_OPTS: buildScannerOpts(effectiveProjectKey, scannerConfig)
+    SONAR_SCANNER_OPTS: buildScannerOpts(effectiveProjectKey, scannerConfig, { linkedWorktree })
   };
 
   let cmd, args;