karajan-code 4.35.0 → 4.36.0

package/src/rag/library.js

@@ -1,9 +1,9 @@
 /**
  * library — the distilled engineering canon as its own RAG collection
- * (KJC-TSK-0697). Markdown cards from `<pkg>/library/`, `~/.karajan/library/`
- * and `<project>/.karajan/library/` index into the SAME global rag.db,
- * isolated by project="library" + kind="library", so `kj rag query --library`
- * reaches the canon and normal project queries never see it. The architect
+ * (KJC-TSK-0697). KJC-TSK-0883 (ADR 0011): the machine canon (`<pkg>/library/`
+ * and `~/.karajan/library/`) indexes into its own ~/.karajan/library.db under
+ * project="library", reached by `kj rag query --library`; a project's own cards
+ * (`<project>/.karajan/library/`) go to that project's index under its slug. The architect
  * consults it to ground the greenfield alternative (KJC-TSK-0696).
  */
 
@@ -20,10 +20,16 @@ export const LIBRARY_PROJECT = "library";
 
 const SHIPPED_LIBRARY_DIR = fileURLToPath(new URL("../../library", import.meta.url));
 
-/** Existing library dirs, shipped canon first. */
-export function libraryDirs({ pkgLibraryDir = SHIPPED_LIBRARY_DIR, home = os.homedir(), projectDir = process.cwd() } = {}) {
-  const candidates = [pkgLibraryDir, join(home, ".karajan", "library"), join(projectDir, ".karajan", "library")];
-  return candidates.filter((d) => existsSync(d));
+/**
+ * Existing library dirs, shipped canon first. KJC-TSK-0883: `scope` "machine"
+ * is the common canon (kj's + the user's), "project" the project's own cards.
+ */
+export function libraryDirs({ pkgLibraryDir = SHIPPED_LIBRARY_DIR, home = os.homedir(), projectDir = process.cwd(), scope = "all" } = {}) {
+  const machine = [pkgLibraryDir, join(home, ".karajan", "library")];
+  const own = [join(projectDir, ".karajan", "library")];
+  const byScope = { machine, project: own, all: [...machine, ...own] };
+  if (!byScope[scope]) throw new Error(`libraryDirs: unknown scope "${scope}" (machine | project | all)`);
+  return byScope[scope].filter((d) => existsSync(d));
 }
 
 /**
@@ -31,9 +37,9 @@ export function libraryDirs({ pkgLibraryDir = SHIPPED_LIBRARY_DIR, home = os.hom
  * re-index per source and identical bodies skip the embedder (content-hash
  * dedup within the library project).
  */
-export async function indexLibrary({ db, embedder, logger = console, pkgLibraryDir, home, projectDir } = {}) {
+export async function indexLibrary({ db, embedder, logger = console, pkgLibraryDir, home, projectDir, scope = "all", project = LIBRARY_PROJECT } = {}) {
   let indexed = 0, failed = 0, files = 0;
-  for (const dir of libraryDirs({ pkgLibraryDir, home, projectDir })) {
+  for (const dir of libraryDirs({ pkgLibraryDir, home, projectDir, scope })) {
     for (const name of readdirSync(dir)) {
       if (extname(name).toLowerCase() !== ".md") continue;
       const path = join(dir, name);
@@ -42,13 +48,13 @@ export async function indexLibrary({ db, embedder, logger = console, pkgLibraryD
       const hashed = chunks.map((ch) => ({ ch, contentHash: createHash("sha256").update(ch.text).digest("hex") }));
       // Unchanged card (every chunk body already known) → skip before the
       // delete, so idempotent re-runs never touch the embedder.
-      if (hashed.length && hashed.every(({ contentHash }) => findChunkByHash(db, contentHash, LIBRARY_PROJECT))) continue;
+      if (hashed.length && hashed.every(({ contentHash }) => findChunkByHash(db, contentHash, project))) continue;
       deleteChunksBySource(db, path);
       for (const { ch, contentHash } of hashed) {
         try {
-          if (findChunkByHash(db, contentHash, LIBRARY_PROJECT)) continue;
+          if (findChunkByHash(db, contentHash, project)) continue;
           const embedding = await embedder.embed(ch.text);
-          insertChunk(db, { source: path, kind: "library", text: ch.text, metadata: ch.metadata, embedding, project: LIBRARY_PROJECT, contentHash });
+          insertChunk(db, { source: path, kind: "library", text: ch.text, metadata: ch.metadata, embedding, project, contentHash });
           indexed += 1;
         } catch (err) {
           failed += 1;

package/src/rag/migrate.js

@@ -0,0 +1,73 @@
+/**
+ * KJC-TSK-0888 (RAG-P1a, ADR 0011) — pasar al indice por proyecto sin volver a
+ * embeber. Los chunks de UN proyecto se copian de la base global de la maquina
+ * a <raiz>/.karajan/rag.db con sus embeddings tal cual, junto con su marca de
+ * last_indexed_commit para que el auto-update siga por delta. Cero recomputo
+ * (en esta maquina, karajan-code son 23.109 chunks), y la base global no se
+ * toca: borrarla es decision del usuario, no efecto de una migracion.
+ */
+import { existsSync } from "node:fs";
+
+import { openVecStore, insertChunk, getLastIndexedCommit, setLastIndexedCommit } from "./vec-store.js";
+
+export const countProjectChunks = (db, slug) => db.prepare("SELECT COUNT(*) AS n FROM chunks WHERE project_slug = ?").get(slug).n;
+
+/**
+ * KJC-TSK-0882: que decir cuando el indice del proyecto no tiene nada suyo.
+ * Si la base global tiene sus chunks, migrar (segundos); si no, indexar.
+ */
+export function emptyIndexRemedy({ slug, legacyPath, dim = 768 }) {
+  if (slug && existsSync(legacyPath)) {
+    const legacy = openVecStore({ dim, path: legacyPath });
+    try {
+      if (countProjectChunks(legacy, slug) > 0) return "kj rag migrate";
+    } finally {
+      legacy.close();
+    }
+  }
+  return "kj rag index --with-sources";
+}
+
+/**
+ * @returns {{state: "migrated"|"already"|"nothing", migrated: number, reason: string}}
+ */
+export function migrateProjectIndex({ slug, legacyPath, targetPath, dim = 768 }) {
+  const nothing = { state: "nothing", migrated: 0, reason: `the global index holds nothing for ${slug}: kj rag index --with-sources` };
+  if (!existsSync(legacyPath)) return nothing;
+
+  const target = openVecStore({ dim, path: targetPath });
+  try {
+    // Se cuentan los de ESTE proyecto, no el total: un rag.db viejo en
+    // .karajan/ puede traer chunks de otro (visto en esta maquina: 42 de otro
+    // repo), y contar el total diria "ya migrado" sin haber copiado nada.
+    const mine = countProjectChunks(target, slug);
+    if (mine > 0) {
+      return { state: "already", migrated: 0, reason: `the project index already holds ${mine} chunks of ${slug}: nothing to migrate` };
+    }
+    const legacy = openVecStore({ dim, path: legacyPath });
+    try {
+      const rows = legacy.prepare("SELECT id, source, kind, text, metadata, content_hash FROM chunks WHERE project_slug = ?").all(slug);
+      if (rows.length === 0) return nothing;
+      const vecOf = legacy.prepare("SELECT embedding FROM vec_chunks WHERE rowid = ?");
+      const copy = target.transaction(() => {
+        for (const r of rows) {
+          const raw = vecOf.get(BigInt(r.id))?.embedding;
+          if (!raw) continue; // un chunk sin vector no se puede buscar: no se inventa
+          const embedding = new Float32Array(raw.buffer.slice(raw.byteOffset, raw.byteOffset + raw.byteLength));
+          insertChunk(target, { source: r.source, kind: r.kind, text: r.text, metadata: r.metadata, embedding, project: slug, contentHash: r.content_hash });
+        }
+      });
+      copy();
+      const stamp = getLastIndexedCommit(legacy, slug);
+      if (stamp) setLastIndexedCommit(target, slug, stamp);
+      const migrated = countProjectChunks(target, slug);
+      const parts = [`${migrated} chunks of ${slug} copied with their embeddings`];
+      if (stamp) parts.push(`indexed at ${stamp.slice(0, 9)}`);
+      return { state: "migrated", migrated, reason: parts.join(", ") };
+    } finally {
+      legacy.close();
+    }
+  } finally {
+    target.close();
+  }
+}

package/src/rag/onnx-fallback.js

@@ -12,7 +12,7 @@ import path from "node:path";
 import Database from "better-sqlite3";
 import { parseDocument } from "yaml";
 import { getProjectConfigPath } from "../config/loader.js";
-import { dbPath } from "./vec-store.js";
+import { projectDbPath } from "./project-store.js";
 
 const ONNX_EMBEDDER = { provider: "onnx", dim: 384 };
 
@@ -24,8 +24,10 @@ const ONNX_EMBEDDER = { provider: "onnx", dim: 384 };
  * that already HAS chunks is never touched — switching dims there would
  * destroy other projects' indexes.
  */
-export function resetEmptyStore() {
-  const storePath = dbPath();
+// KJC-TSK-0882 (ADR 0011): el store es DEL PROYECTO, asi que el fallback a ONNX
+// decide mirando el indice de este proyecto y nunca el de otro.
+export function resetEmptyStore(projectDir = process.cwd()) {
+  const storePath = projectDbPath(projectDir);
   if (!existsSync(storePath)) return true;
   // Read-only, schema-agnostic inspection: no DDL, no vec extension, no
   // dimension assumptions — the store is only ever OPENED to be counted.

package/src/rag/project-store.js

@@ -0,0 +1,48 @@
+/**
+ * KJC-TSK-0882 (RAG-P1, ADR 0011) — el indice del RAG es DEL PROYECTO.
+ *
+ * Hasta aqui era una sola base por maquina (~/.karajan/rag.db): 427 MB, 19
+ * proyectos y 49.825 chunks en un indice vectorial sin particion. La KNN sacaba
+ * los vecinos mas cercanos de TODA la maquina y filtraba por proyecto despues,
+ * asi que un proyecto pequeno podia recibir cero resultados con el chunk
+ * perfecto indexado, y cinco consultas ni siquiera filtraban (una de ellas, el
+ * preload que entra en el prompt del coder).
+ *
+ * Ahora cada proyecto abre <raiz git>/.karajan/rag.db. La raiz se resuelve por
+ * git para que desde un subdirectorio se vea el mismo indice. KJ_RAG_DB sigue
+ * mandando cuando esta puesta. El store de karajan-core ya acepta `path`, asi
+ * que esto no toca core.
+ */
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+
+import { openVecStore } from "./vec-store.js";
+import { getKarajanHome } from "../utils/paths.js";
+
+function projectRoot(dir) {
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || dir;
+  } catch {
+    return dir;
+  }
+}
+
+/** Ruta del indice del proyecto. */
+export function projectDbPath(projectDir = process.cwd()) {
+  if (process.env.KJ_RAG_DB) return process.env.KJ_RAG_DB;
+  return path.join(projectRoot(projectDir), ".karajan", "rag.db");
+}
+
+/** Abre el indice del proyecto. El caller es dueno del close(). */
+/** KJC-TSK-0883: the machine canon has its own store, never a project's. */
+export function libraryDbPath() {
+  return process.env.KJ_LIBRARY_DB || path.join(getKarajanHome(), "library.db");
+}
+
+export function openLibraryStore({ dim = 768 } = {}) {
+  return openVecStore({ dim, path: libraryDbPath() });
+}
+
+export function openProjectStore({ projectDir = process.cwd(), dim = 768 } = {}) {
+  return openVecStore({ dim, path: projectDbPath(projectDir) });
+}

package/src/rag/watcher.js

@@ -1,18 +1,27 @@
 // KJC-TSK-0441 (RAG v2.28.0 PR1) — chokidar watcher. Live re-index of plans
 // + onboarding + (opt) sources, debounced. PID file arbitrates a single daemon.
 // KJC-TSK-0482 — source matcher derivado del registry (multi-lang: JS/Py/Rust/Go/Java).
-import { writeFileSync, readFileSync, existsSync, unlinkSync } from "node:fs";
-import { extname, join } from "node:path";
+import { writeFileSync, readFileSync, existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { dirname, extname, join } from "node:path";
 import chokidar from "chokidar";
-import { openVecStore, deleteChunksBySource, projectSlug } from "./vec-store.js";
+import { deleteChunksBySource, projectSlug } from "./vec-store.js";
+import { openProjectStore } from "./project-store.js";
 import { makeGovernedEmbedder } from "./governed-embedder.js";
 import { indexFile } from "./indexer.js";
 import { getKarajanHome } from "../utils/paths.js";
 import { getAllCodeExtensions } from "../lang/registry.js";
 
-const PIDFILE = () => join(getKarajanHome(), "watcher.pid");
+// KJC-TSK-0883 (ADR 0011): un watcher por proyecto, cada uno con su PID.
+export const pidFilePath = (projectDir = process.cwd()) => join(getKarajanHome(), "watchers", `${projectSlug(projectDir)}.pid`);
+
+/** Solo lo de ESTE proyecto: sus planes, su onboarding y (opt) sus fuentes. */
+export function watchedPaths(projectDir, { withSources = false } = {}) {
+  const slug = projectSlug(projectDir);
+  const paths = [join(getKarajanHome(), "onboarding", `${slug}.md`), join(getKarajanHome(), "plans", slug)];
+  return withSources ? [...paths, projectDir] : paths;
+}
 const DEFAULT_DEBOUNCE_MS = 1000;
-const SKIP_SEGMENTS = new Set(["node_modules", ".git", "dist", "build", "coverage", ".karajan", ".next", ".kj", "_diet"]);
+const SKIP_SEGMENTS = new Set(["node_modules", ".git", "dist", "build", "coverage", ".karajan", ".next", ".kj", "_diet", ".claude"]);
 const SOURCE_EXTS = new Set(getAllCodeExtensions().map((e) => e.toLowerCase()));
 
 export function isWatchable(path) {
@@ -26,11 +35,9 @@ export function startWatcher({ projectDir, config, logger = console, debounceMs
   if (!projectDir) throw new Error("startWatcher: projectDir is required");
   const slug = projectSlug(projectDir);
   const dim = config?.rag?.embedder?.dim || 768;
-  const db = openVecStore({ dim });
+  const db = openProjectStore({ projectDir, dim });
   const embedder = makeGovernedEmbedder(config);
-  const paths = [join(getKarajanHome(), "onboarding"), join(getKarajanHome(), "plans")];
-  if (withSources) paths.push(projectDir);
-  const watcher = chokidar.watch(paths, { ignoreInitial: true, persistent: true });
+  const watcher = chokidar.watch(watchedPaths(projectDir, { withSources }), { ignoreInitial: true, persistent: true });
   const pending = new Map();
   const flush = async (p) => {
     pending.delete(p);
@@ -49,11 +56,15 @@ export function startWatcher({ projectDir, config, logger = console, debounceMs
   };
 }
 
-export function writePidFile(pid = process.pid) { writeFileSync(PIDFILE(), String(pid), "utf8"); }
-export function clearPidFile() { if (existsSync(PIDFILE())) unlinkSync(PIDFILE()); }
-export function readPidFile() {
-  if (!existsSync(PIDFILE())) return null;
-  const pid = Number(readFileSync(PIDFILE(), "utf8").trim());
+export function writePidFile(projectDir, pid = process.pid) {
+  const file = pidFilePath(projectDir);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, String(pid), "utf8");
+}
+export function clearPidFile(projectDir) { if (existsSync(pidFilePath(projectDir))) unlinkSync(pidFilePath(projectDir)); }
+export function readPidFile(projectDir) {
+  if (!existsSync(pidFilePath(projectDir))) return null;
+  const pid = Number(readFileSync(pidFilePath(projectDir), "utf8").trim());
   return Number.isInteger(pid) && pid > 0 ? pid : null;
 }
 export function isPidAlive(pid) {

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,68 @@
+/**
+ * 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 { execFileSync } from "node:child_process";
+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 };
+}
+
+const gitIn = (root) => (args) => execFileSync("git", ["-C", root, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+
+/**
+ * KJC-TSK-0886: el sello de que kj emite un veredicto. En un arbol enlazado la
+ * version no basta (el mismo package.json vale para dos estados del disco), asi
+ * que lleva rama y commit del working tree. Nunca lanza: adorna, no decide.
+ */
+export function kjStamp({ provenance = kjProvenance(), git = gitIn(provenance.root) } = {}) {
+  const stamp = { version: provenance.version, linked: provenance.linked };
+  if (!provenance.linked) return stamp;
+  try {
+    return { ...stamp, branch: git(["rev-parse", "--abbrev-ref", "HEAD"]).trim(), commit: git(["rev-parse", "HEAD"]).trim() };
+  } catch {
+    return stamp;
+  }
+}
+
+const STAMP_KEYS = ["version", "linked", "branch", "commit"];
+export const stampDiffers = (a, b) => Boolean(a && b) && STAMP_KEYS.some((k) => a[k] !== b[k]);
+
+export function stampLabel(s) {
+  const where = s.branch ? ` (${s.branch}@${(s.commit || "").slice(0, 7)})` : "";
+  return `kj ${s.version ?? "unknown"}${where}`;
+}

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/review/verdict-store.js

@@ -13,6 +13,7 @@ import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { runCommand } from "../utils/process.js";
+import { kjStamp, stampDiffers, stampLabel } from "./kj-provenance.js";
 
 const STORE_DIR = path.join(".karajan", "reviews");
 
@@ -35,6 +36,7 @@ export async function saveVerdict(projectDir, diff, verdict) {
   const hash = diffHash(diff);
   const record = {
     ...verdict,
+    kj: kjStamp(), // KJC-TSK-0886: que kj lo emitio; nunca lo dicta quien llama
     diffHash: hash,
     timestamp: new Date().toISOString(),
   };
@@ -143,5 +145,8 @@ export async function checkVerdict(projectDir, diff) {
   if (verdict.verdict !== "approved") {
     return { ok: false, verdict, reason: `review was rejected by ${verdict.reviewer} — fix the issues and run \`kj review\` again` };
   }
-  return { ok: true, verdict };
+  // KJC-TSK-0886: otro kj comprobando no bloquea, pero deja rastro.
+  const now = kjStamp();
+  if (!stampDiffers(verdict.kj, now)) return { ok: true, verdict };
+  return { ok: true, verdict, note: `verdict from ${stampLabel(verdict.kj)}, checked by ${stampLabel(now)}` };
 }

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;