karajan-code 4.35.1 → 4.36.0

package/src/orchestrator/stages/rag-context-stage.js

@@ -5,9 +5,10 @@
 // Failures degrade gracefully (warn + continue); the rest of the pipeline
 // never sees an exception from this stage.
 import { emitProgress, makeEvent } from "../../utils/events.js";
-import { openVecStore, countChunks } from "../../rag/vec-store.js";
+import { countChunks } from "../../rag/vec-store.js";
 import { makeGovernedEmbedder } from "../../rag/governed-embedder.js";
 import { query } from "../../rag/retriever.js";
+import { openProjectStore } from "../../rag/project-store.js";
 
 const DEFAULT_TOP_K = 5;
 const DEFAULT_SCOPE = "all";
@@ -44,7 +45,9 @@ export async function runRagContextStage({ config, logger, emitter, eventBase, t
   if (typeof task !== "string" || task.length === 0) return { skipped: true, reason: "no-task" };
   try {
     const dim = config?.rag?.embedder?.dim || 768;
-    const db = openVecStore({ dim });
+    // KJC-TSK-0882: el preload que entra en el prompt del coder solo puede traer
+    // codigo de ESTE proyecto: antes abria el indice de la maquina sin filtrar.
+    const db = openProjectStore({ projectDir: config?.projectDir || process.cwd(), dim });
     try {
       if (countChunks(db) === 0) {
         logger?.info?.("[rag-preload] corpus is empty, skipping (run `kj rag index` to seed)");

package/src/rag/auto-update.js

@@ -6,9 +6,11 @@ import { isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { execa } from "execa";
 
-import { openVecStore, projectSlug, getLastIndexedCommit, setLastIndexedCommit } from "./vec-store.js";
+import { projectSlug, getLastIndexedCommit, setLastIndexedCommit } from "./vec-store.js";
 import { indexProjectDelta } from "./indexer.js";
+import { ragExclude } from "./indexable.js";
 import { makeGovernedEmbedder } from "./governed-embedder.js";
+import { openProjectStore } from "./project-store.js";
 
 const HOOK_SRC = resolve(fileURLToPath(import.meta.url), "../../../scripts/git-hooks/post-merge");
 
@@ -20,12 +22,12 @@ export async function maybeAutoUpdate({ projectDir, config, logger = console, fl
   try { const r = await execa("git", ["-C", projectDir, "rev-parse", "HEAD"]); head = r.stdout.trim(); }
   catch { return { skipped: true }; }
   const slug = projectSlug(projectDir);
-  const db = openVecStore({ dim: config?.rag?.embedder?.dim || 768 });
+  const db = openProjectStore({ projectDir, dim: config?.rag?.embedder?.dim || 768 });
   try {
     const since = getLastIndexedCommit(db, slug);
     if (!since || since === head) return { skipped: true, head };
     logger.info?.(`[rag] drift detected (${since.slice(0, 7)} → ${head.slice(0, 7)}); running delta update`);
-    const totals = await indexProjectDelta(projectDir, { db, embedder: makeGovernedEmbedder(config), since, logger });
+    const totals = await indexProjectDelta(projectDir, { db, embedder: makeGovernedEmbedder(config), since, logger, exclude: ragExclude(config) });
     if (totals.head) setLastIndexedCommit(db, slug, totals.head);
     return { ran: true, totals };
   } catch (err) {

package/src/rag/coverage.js

@@ -8,8 +8,8 @@
  * matchers are the single truth, here and in the indexer.
  */
 import { execa } from "execa";
-import { extname, isAbsolute, normalize, relative } from "node:path";
-import { detectAdaptersForProject, buildMatchers } from "../lang/registry.js";
+import { isAbsolute, join, normalize, relative } from "node:path";
+import { indexableReason } from "./indexable.js";
 import { GENERATED_CONFIG_FILES } from "../harden/config-templates.js";
 import { getLastIndexedCommit, projectSlug } from "./vec-store.js";
 
@@ -36,11 +36,11 @@ export function isGeneratedByHarden(rel) {
  * @param {{db: object}} deps - an open vec store
  * @returns {Promise<{project: string, total: number, indexed: number, missing: string[], stale: string[], lastIndexedCommit: string|null, absent: boolean}>}
  */
-export async function ragIndexCoverage(projectDir, { db }) {
+export async function ragIndexCoverage(projectDir, { db, exclude = [] }) {
   const project = projectSlug(projectDir);
-  const matchers = buildMatchers(detectAdaptersForProject(projectDir));
   const { stdout } = await execa("git", ["-C", projectDir, "ls-files", "-z"]);
-  const all = stdout.split("\0").filter((p) => p && matchers.isCodeFile(p) && !matchers.shouldSkip(p));
+  // KJC-TSK-0891: the indexer's own criterion, not a list of extensions.
+  const all = stdout.split("\0").filter((p) => p && indexableReason(p, join(projectDir, p), { exclude, projectDir }) === null);
   // 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));
@@ -82,20 +82,21 @@ export async function ragIndexCoverage(projectDir, { db }) {
  *
  * @returns {{state: "indexed"|"stale"|"not-indexable"|"index-empty", rel: string, canAnswer: boolean, reason: string}}
  */
-export function fileIndexState(projectDir, file, { db }) {
+export function fileIndexState(projectDir, file, { db, exclude = [] }) {
   const project = projectSlug(projectDir);
   // `./src/a.js` y `src/a.js` son el mismo fichero: sin normalizar, el segundo
   // salia "stale" estando indexado (catch de la review).
   const rel = normalize(isAbsolute(file) ? relative(projectDir, file) : file);
-  const matchers = buildMatchers(detectAdaptersForProject(projectDir));
   const rows = db.prepare("SELECT DISTINCT source FROM chunks WHERE project_slug = ?").all(project);
   const indexed = new Set(rows.map((r) => normalize(isAbsolute(r.source) ? relative(projectDir, r.source) : r.source)));
 
   if (indexed.has(rel)) return { state: "indexed", rel, canAnswer: true, reason: `the index holds chunks for ${rel}` };
   if (indexed.size === 0) return { state: "index-empty", rel, canAnswer: false, reason: `nothing of this project is indexed yet: kj rag index` };
-  if (matchers.shouldSkip(rel)) return { state: "not-indexable", rel, canAnswer: false, reason: `${rel} lives under a path the indexer always skips` };
-  if (!matchers.isCodeFile(rel) && extname(rel).toLowerCase() !== ".md") {
-    return { state: "not-indexable", rel, canAnswer: false, reason: `no language adapter covers ${extname(rel) || "a file with no extension"}, so the indexer never takes ${rel}` };
-  }
-  return { state: "stale", rel, canAnswer: false, reason: `${rel} is indexable but absent from the index: kj rag index --since auto` };
+  // KJC-TSK-0891: not-indexable only for the file's NATURE (binary, generated,
+  // huge, excluded, skipped path), never for its language.
+  const out = indexableReason(rel, join(projectDir, rel), { exclude, projectDir });
+  if (out) return { state: "not-indexable", rel, canAnswer: false, reason: out };
+  // KJC-TSK-0891: `--since auto` only reaches what changed, so it cannot fix an
+  // unchanged file the index never held; indexing THIS file does.
+  return { state: "stale", rel, canAnswer: false, reason: `${rel} is indexable but absent from the index: kj rag index --file ${rel}` };
 }

package/src/rag/indexable.js

@@ -0,0 +1,97 @@
+/**
+ * KJC-TSK-0891 (#1807 point 4) — what the index takes, decided without a list
+ * of extensions: there are countless languages, and a list always falls short.
+ * Any text file the project versions is indexable. What stays out stays out for
+ * its NATURE, never its language: binary, generated, too large, excluded by the
+ * project, or under a path the indexer always skips. Where a language adapter
+ * exists the chunker splits by symbol; elsewhere it falls back to overlapping
+ * text windows (chunkSource already does).
+ */
+import { execFileSync } from "node:child_process";
+import { closeSync, lstatSync, openSync, readSync } from "node:fs";
+
+import { matchesAny } from "@karajan-family/governance";
+
+import { buildMatchers, detectAdaptersForProject } from "../lang/registry.js";
+
+const MAX_BYTES = 512 * 1024;
+const SNIFF_BYTES = 8192;
+// Generated by tools, not written by the team: noise in any language.
+const GENERATED = [
+  /(^|\/)(package-lock\.json|npm-shrinkwrap\.json|yarn\.lock|pnpm-lock\.yaml|bun\.lockb?|Cargo\.lock|poetry\.lock|Pipfile\.lock|uv\.lock|composer\.lock|Gemfile\.lock|go\.sum)$/,
+  /\.min\.(js|css)$/,
+  /\.map$/,
+  /\.snap$/,
+];
+
+// May hold secrets: never sent to an embedder, which can be a remote service.
+const SENSITIVE = [
+  /(^|\/)\.env(\.[^/]*)?$/,
+  /\.(pem|key|p12|pfx|jks|keystore)$/i,
+  /(^|\/)id_(rsa|dsa|ecdsa|ed25519)(\.pub)?$/,
+];
+
+// The skipped paths are the ones of THIS project's languages: Java's `bin/`
+// is build output, a JS project's `bin/` is source. Cached per project.
+const skipCache = new Map();
+const skipsFor = (projectDir) => {
+  const key = projectDir ?? "";
+  if (!skipCache.has(key)) skipCache.set(key, buildMatchers(detectAdaptersForProject(projectDir ?? process.cwd())).shouldSkip);
+  return skipCache.get(key);
+};
+
+/** What the project keeps out of its index: `rag.exclude`, repo-relative globs. */
+export const ragExclude = (config) => (Array.isArray(config?.rag?.exclude) ? config.rag.exclude : []);
+
+function looksBinary(abs) {
+  const fd = openSync(abs, "r");
+  try {
+    const buf = Buffer.alloc(SNIFF_BYTES);
+    const n = readSync(fd, buf, 0, SNIFF_BYTES, 0);
+    return buf.subarray(0, n).includes(0);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/**
+ * @param {string} rel path relative to the project root
+ * @param {string} abs absolute path
+ * @param {{exclude?: string[], skip?: (rel: string) => boolean}} [opts]
+ * @returns {string|null} why it stays out of the index, or null if it goes in
+ */
+export function indexableReason(rel, abs, { exclude = [], projectDir = null, skip = skipsFor(projectDir) } = {}) {
+  if (skip(rel)) return `${rel} lives under a path the indexer always skips`;
+  if (matchesAny(rel, exclude)) return `${rel} is excluded by the project's rag.exclude`;
+  if (SENSITIVE.some((re) => re.test(rel))) return `${rel} may hold secrets, and the embedder can be a remote service`;
+  if (GENERATED.some((re) => re.test(rel))) return `${rel} is a generated file (lockfile, minified, sourcemap or snapshot)`;
+  let st;
+  try { st = lstatSync(abs); } catch { return `${rel} does not exist`; }
+  // Never followed: a versioned symlink could point the embedder at any
+  // readable file outside the project, secrets included.
+  if (st.isSymbolicLink()) return `${rel} is a symbolic link`;
+  if (!st.isFile()) return `${rel} is not a regular file`;
+  if (st.size > MAX_BYTES) return `${rel} is larger than ${MAX_BYTES / 1024} KB`;
+  try {
+    if (looksBinary(abs)) return `${rel} is binary`;
+  } catch {
+    return `${rel} could not be read`;
+  }
+  return null;
+}
+
+/**
+ * The project's files as git sees them: versioned, plus new ones git does not
+ * ignore. Null outside a git repo, so the caller can fall back to a walk.
+ * @returns {string[]|null} paths relative to projectDir
+ */
+export function listProjectFiles(projectDir) {
+  try {
+    const out = execFileSync("git", ["-C", projectDir, "ls-files", "-z", "--cached", "--others", "--exclude-standard"], {
+      encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], maxBuffer: 64 * 1024 * 1024,
+    });
+    return [...new Set(out.split("\0").filter(Boolean))];
+  } catch {
+    return null;
+  }
+}

package/src/rag/indexer.js

@@ -12,7 +12,8 @@ import { execa } from "execa";
 
 import { chunkMarkdown, chunkPlan, chunkSource } from "./chunker.js";
 import { insertChunk, deleteChunksBySource, findChunkByHash } from "./vec-store.js";
-import { detectAdaptersForProject, buildMatchers, getAllCodeExtensions } from "../lang/registry.js";
+import { detectAdaptersForProject, getAllCodeExtensions } from "../lang/registry.js";
+import { indexableReason, listProjectFiles } from "./indexable.js";
 
 // KJC-PCS-0052 PR-A — antes vivían dos consts hard-coded para JS aquí
 // (CODE_EXT_RE + SKIP_SEGMENTS). Ahora vienen del registry de adapters,
@@ -39,19 +40,28 @@ function chunksFor(path, kind) {
   if (kind === "plan" || kind === "onboarding") {
     return chunkMarkdown(text, { path, kind });
   }
+  // KJC-TSK-0891: a project's own prose is still a project source ("code":
+  // the store's schema allows no other kind), split by headings.
+  if (kind === "code" && /\.mdx?$/i.test(path)) return chunkMarkdown(text, { path, kind });
   if (kind === "code") return chunkSource(text, { path });
   return [];
 }
 
+/**
+ * KJC-TSK-0891: every project source is indexed as "code". Where an adapter
+ * exists it splits by symbol; any other text falls back to overlapping windows.
+ */
+export const sourceKind = () => "code";
+
 /**
  * Index a single file. Returns `{ indexed, failed }`. Idempotent —
  * pre-existing chunks for this `source` path are deleted before the
  * fresh batch is written, so a second call against the same file
  * leaves the store with exactly the latest chunks (no duplicates).
  */
-export async function indexFile(path, { db, embedder, logger = console, project = null } = {}) {
+export async function indexFile(path, { db, embedder, logger = console, project = null, kind: declaredKind = null } = {}) {
   if (!existsSync(path)) { logger.warn?.(`[rag-indexer] file not found: ${path}`); return { indexed: 0, failed: 0 }; }
-  const kind = detectKind(path);
+  const kind = declaredKind ?? detectKind(path);
   if (!kind) { logger.warn?.(`[rag-indexer] unknown kind: ${path}`); return { indexed: 0, failed: 0 }; }
   const chunks = chunksFor(path, kind);
   if (!chunks.length) return { indexed: 0, failed: 0, skipped: 0 };
@@ -118,7 +128,7 @@ async function listFiles(dir, predicate) {
  * indexing tens of thousands of files is expensive — the CLI exposes
  * it as `--with-sources`.
  */
-export async function indexProject(projectDir, { db, embedder, karajanHome, logger = console, withSources = false } = {}) {
+export async function indexProject(projectDir, { db, embedder, karajanHome, logger = console, withSources = false, exclude = [] } = {}) {
   // KJC-TSK-0640: a full index must stamp HEAD too — without it,
   // last_indexed_commit stayed null after the FIRST index, so the drift
   // delta-update (maybeAutoUpdate) never engaged until a manual --since.
@@ -148,10 +158,20 @@ export async function indexProject(projectDir, { db, embedder, karajanHome, logg
     // duplicate every chunk and contaminate retrieval scores. `_diet` is the
     // tests/_diet/ sandbox used by the test-diet audit harness — never user
     // code. Both viven en COMMON_SKIP_SEGMENTS dentro del registry.
-    const matchers = buildMatchers(detectAdaptersForProject(projectDir));
-    const sources = await listFiles(projectDir, (p) => matchers.isCodeFile(p) && !matchers.shouldSkip(p));
+    // KJC-BUG-0231: las exclusiones se juzgan DENTRO del proyecto (ruta relativa).
+    // KJC-TSK-0891: sin lista de extensiones: cualquier texto que el proyecto
+    // versiona, fuera lo binario, generado, enorme o excluido (indexable.js).
+    const outOf = (abs) => indexableReason(relative(projectDir, abs), abs, { exclude, projectDir });
+    const listed = listProjectFiles(projectDir);
+    const candidates = listed ? listed.map((rel) => join(projectDir, rel)) : await listFiles(projectDir, () => true);
+    const sources = candidates.filter((abs) => outOf(abs) === null);
+    // Lo que un indice anterior guardo y hoy ya no entra (excluido o borrado), fuera.
+    const prefix = `${projectDir}/`;
+    for (const { source } of db.prepare("SELECT DISTINCT source FROM chunks WHERE project_slug = ?").all(slug)) {
+      if (source.startsWith(prefix) && outOf(source) !== null) deleteChunksBySource(db, source);
+    }
     for (const s of sources) {
-      const r = await indexFile(s, { db, embedder, logger, project: slug });
+      const r = await indexFile(s, { db, embedder, logger, project: slug, kind: sourceKind(s) });
       totals.indexed += r.indexed; totals.failed += r.failed; totals.files += 1;
     }
   }
@@ -165,7 +185,7 @@ export async function indexProject(projectDir, { db, embedder, karajanHome, logg
  * `head` lets callers persist via setLastIndexedCommit. Throws on diff failure
  * (shallow clone, unknown ref) so the CLI can fall back to a full reindex.
  */
-export async function indexProjectDelta(projectDir, { db, embedder, since, logger = console } = {}) {
+export async function indexProjectDelta(projectDir, { db, embedder, since, logger = console, exclude = [] } = {}) {
   const totals = { indexed: 0, failed: 0, files: 0, deleted: 0, head: null };
   const slug = projectDir.split("/").pop()?.replace(/[^a-zA-Z0-9._-]/g, "-").toLowerCase() || "project";
   const { stdout: head } = await execa("git", ["-C", projectDir, "rev-parse", "HEAD"]);
@@ -182,16 +202,14 @@ export async function indexProjectDelta(projectDir, { db, embedder, since, logge
   }
   const adapters = detectAdaptersForProject(projectDir);
   await prepareAdapters(adapters, { logger });
-  const matchers = buildMatchers(adapters);
   for (const { kind, p } of ops) {
-    if (matchers.shouldSkip(p)) continue;
-    if (!matchers.isCodeFile(p)) continue;
     const abs = isAbsolute(p) ? p : join(projectDir, p);
     if (kind === "del") {
       totals.deleted += deleteChunksBySource(db, abs);
       logger.info?.(`[rag-indexer] delta delete ${relative(process.cwd(), abs)}`);
-    } else if (existsSync(abs)) {
-      const r = await indexFile(abs, { db, embedder, logger, project: slug });
+    } else if (indexableReason(relative(projectDir, abs), abs, { exclude, projectDir }) === null) {
+      // KJC-TSK-0891: the same criterion as the full walk, not a list of extensions.
+      const r = await indexFile(abs, { db, embedder, logger, project: slug, kind: sourceKind(abs) });
       totals.indexed += r.indexed; totals.failed += r.failed; totals.files += 1;
     }
   }

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/kj-provenance.js

@@ -11,6 +11,7 @@
  * 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";
@@ -40,3 +41,28 @@ export function kjProvenance(moduleDir = here) {
     : `${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}`;
+}