karajan-code 4.35.1 → 4.37.0

package/src/harden/sentinel-hooks.js

@@ -8,7 +8,7 @@
  * hooks, which is why the guaranteed level requires Claude as host (ADR).
  */
 
-import { readFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { join } from "node:path";
@@ -131,6 +131,7 @@ const POST_BODY = `#!/usr/bin/env node
 // kj sentinel state writer (KJC-TSK-0713) — managed by \`kj harden\`.
 // Records deterministic method facts per session; never blocks, never fails
 // a tool call (PostToolUse, always exit 0).
+import console from "node:console";
 import process from "node:process";
 import { relative } from "node:path";
 import { spawnSync } from "node:child_process";
@@ -256,7 +257,16 @@ process.stdin.on("end", () => {
         const state = load();
         const s = session(state, sid);
         const ref = CARD.exec(headRef || branchOf() || "");
-        (s.pending_moves ||= []).push({ card: ref ? ref[0].toUpperCase() : null, pr: mergedPr, at: Date.now(), ...(headRef ? {} : { head: "unknown" }) });
+        // KJC-BUG-0230: una EPICA (…-PCS-…) no tiene estado que mover: el PG
+        // la deja en To Do por mas status que reciba y kj hu move no la
+        // conoce. Registrarla como pendiente era un bloqueo sin cauce. Se dice
+        // en el momento, para que no parezca que el board dejo de mirar.
+        const epic = ref && /-PCS-/i.test(ref[0]);
+        if (epic) {
+          console.error("karajan sentinel: board-sync — la PR #" + mergedPr + " pertenece a la epica " + ref[0].toUpperCase() + ", que no tiene estado que mover: no queda pendiente (su cierre va en la descripcion de la epica)");
+        } else {
+          (s.pending_moves ||= []).push({ card: ref ? ref[0].toUpperCase() : null, pr: mergedPr, at: Date.now(), ...(headRef ? {} : { head: "unknown" }) });
+        }
         save(state);
       }
       const moved = /kj\\s+hu\\s+move\\s+([A-Za-z0-9-]+)\\s+([a-z&-]+)/i.exec(String(input.command || ""));
@@ -278,9 +288,23 @@ process.stdin.on("end", () => {
         s.escapes.push(e);
         (state.escape_events ||= []).push({ escape: e, tool, sid, ts: Date.now() });
       }
+    // KJC-TSK-0910: the branch size while it is written, with the CI budget
+    // (kj pr-size), said once per threshold crossed. Context, never a block.
+    let sizeNote = null;
+    if (bucket) {
+      const ps = spawnSync("kj", ["pr-size", "--json"], { cwd: ROOT, encoding: "utf8", timeout: 5000 });
+      let size = null;
+      try { size = JSON.parse(String(ps.stdout || "").trim().split(String.fromCharCode(10)).pop()); } catch { size = null; }
+      const crossed = size ? [200, 150].find((t) => size.added > t) : undefined;
+      if (crossed && (s.size_warned || 0) < crossed) {
+        s.size_warned = crossed;
+        sizeNote = "karajan sentinel: la rama ya suma " + size.added + " lineas contables (" + size.testAdded + " de tests); " + (crossed >= 200 ? "pasa el limite de 200 del CI: parte antes de seguir" : "pasa de 150: planea la particion ahora, no en el stage");
+      }
+    }
     const ids = Object.keys(state.sessions);
     if (ids.length > 5) delete state.sessions[ids.sort((a, b) => (state.sessions[a].at || 0) - (state.sessions[b].at || 0))[0]];
     save(state);
+    if (sizeNote) process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: sizeNote } }));
   } catch { /* fail open — the sentinel never breaks a tool call */ }
   process.exit(0);
 });
@@ -980,9 +1004,19 @@ process.stdin.on("end", () => {
             // cualquier proyecto sin indexar. Nada legible = se bloquea.
             const cov = spawnSync("kj", ["rag", "covers", rel, "--json"], { cwd: ROOT, encoding: "utf8" });
             let blind = null;
-            try { const c = JSON.parse(String(cov.stdout || "")); if (c.state === "not-indexable") blind = c.reason; } catch { blind = null; }
+            let absent = null;
+            try {
+              const c = JSON.parse(String(cov.stdout || ""));
+              if (c.state === "not-indexable") blind = c.reason;
+              // KJC-TSK-0891: si el indice no tiene el fichero, consultar no puede
+              // devolverlo; el remedio es indexarlo, y se nombra.
+              if (c.state === "stale" || c.state === "index-empty") absent = c.reason;
+            } catch { blind = null; }
             if (blind) {
               console.error("karajan sentinel: rag-first — " + blind + " — no se te exige consultar lo que el indice no puede tener; el gate lo anota y sigue" + doc("rag-first"));
+            } else if (absent) {
+              console.error("karajan sentinel: rag-first — el indice aun no tiene " + rel + " (" + absent + "); indexalo y consulta despues: kj_rag_query / kj rag query <que hace " + rel + ">" + doc("rag-first"));
+              process.exit(2);
             } else {
               console.error("karajan sentinel: rag-first — el RAG no ha respondido sobre " + rel + " en esta sesion; consulta antes de tocarlo: kj_rag_query / kj rag query <que hace " + rel + " y donde mas vive ese concepto>. (KJ_ALLOW_NO_RAG=1 = excepcion consciente, queda registrada)" + doc("rag-first"));
               process.exit(2);
@@ -1159,7 +1193,33 @@ function sealedByPath(projectDir, gitShowFn) {
 }
 
 /**
- * @returns {{ok: boolean, mismatched: string[], drift?: string[], reason?: string}}
+ * KJC-BUG-0224: la procedencia PROPIA del harness, lo que `kj harden` escribio
+ * (sha256 por guardia). Distinto del sello humano: no concede nada, solo dice
+ * "esto lo puso kj", y lo unico que habilita es regenerar desde el kj
+ * instalado. Forjarlo, por tanto, solo consigue que el guardia se restaure.
+ */
+const INSTALLED_RECORD = "installed.json";
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+
+function readInstalledRecord(dir) {
+  try {
+    const files = JSON.parse(readFileSync(join(dir, INSTALLED_RECORD), "utf8"))?.files;
+    return files && typeof files === "object" ? files : {};
+  } catch {
+    return {};
+  }
+}
+
+function writeInstalledRecord(dir) {
+  const files = {};
+  for (const name of Object.keys(SCRIPT_BODIES)) {
+    try { files[name] = sha256(readFileSync(join(dir, name), "utf8")); } catch { /* sin fichero no hay nada que registrar */ }
+  }
+  writeFileSync(join(dir, INSTALLED_RECORD), `${JSON.stringify({ files }, null, 2)}\n`);
+}
+
+/**
+ * @returns {{ok: boolean, mismatched: string[], drift?: string[], regenerated?: string[], reason?: string}}
  *   `mismatched` is TAMPERING: a guard holds content nobody sealed, and that is
  *   what the hooks block on. `drift` is a sealed guard whose templates have
  *   moved on, which `kj harden` applies and which is not a defect.
@@ -1185,16 +1245,30 @@ export function verifySentinelScripts({ projectDir, readFileFn = readFileSync, g
   // cannot be borrowed by also editing a template: that was the hole in the
   // first attempt at this fix, and the review was right to reject it.
   const sealed = sealedByPath(root, gitShowFn);
+  const ownRecord = readInstalledRecord(dir);
   const drift = [];
   const tampered = [];
+  const regenerated = [];
   for (const name of mismatched) {
     const text = installed.get(name);
-    const sealedHash = sealed.get(`.karajan/harness/${name}`);
-    if (text !== undefined && sealedHash && sealedHash === createHash("sha256").update(text).digest("hex")) drift.push(name);
+    const hash = text === undefined ? null : sha256(text);
+    if (hash && sealed.get(`.karajan/harness/${name}`) === hash) drift.push(name);
+    else if (hash && ownRecord[name] === hash) regenerated.push(name);
     else tampered.push(name);
   }
-  if (tampered.length > 0) return { ok: false, mismatched: tampered, ...(drift.length ? { drift } : {}) };
+  // KJC-BUG-0224 caso 1: lo que kj escribio y nadie sello ni toco se pone al
+  // dia solo. Es lo que hacia el ritual de `kj harden`, hecho por la maquina.
+  if (regenerated.length > 0) {
+    for (const name of regenerated) writeHarnessScript(root, name, SCRIPT_BODIES[name]);
+    writeInstalledRecord(dir);
+  }
+  const done = regenerated.length ? { regenerated } : {};
+  if (tampered.length > 0) return { ok: false, mismatched: tampered, ...(drift.length ? { drift } : {}), ...done };
+  if (drift.length === 0) {
+    return { ok: true, mismatched: [], ...done, reason: `kj avanzó y estos guardias eran los que kj escribió: regenerados (${regenerated.join(", ")})` };
+  }
   return {
+    ...done,
     ok: true,
     mismatched: [],
     drift,
@@ -1243,6 +1317,7 @@ export function installSentinelHooks({ projectDir = process.cwd(), logger = cons
     }
     return writeHarnessScript(projectDir, name, body);
   });
+  writeInstalledRecord(join(projectDir, ".karajan", "harness"));
   if (deferred.length > 0) {
     logger?.info?.(`kj harden: ${deferred.join(", ")} se queda como está — es lo que un humano selló, y avanzarlo es suyo: kj harden --commit`);
   }

package/src/lang/registry.js

@@ -14,7 +14,8 @@ import { RUST_ADAPTER } from "./rust.js";
 // Segmentos siempre excluidos del walk, independientes de stack: VCS,
 // outputs de build, scratch de Karajan, sandbox del audit. Lo que viva
 // aquí jamás se indexa.
-const COMMON_SKIP_SEGMENTS = [".git", "dist", "build", "coverage", ".karajan", ".kj", "_diet"];
+// KJC-BUG-0231: `.claude` guarda worktrees de subagentes, copias enteras del repo.
+const COMMON_SKIP_SEGMENTS = [".git", "dist", "build", "coverage", ".karajan", ".kj", "_diet", ".claude"];
 
 const REGISTRY = [JS_ADAPTER, PYTHON_ADAPTER, RUST_ADAPTER, GO_ADAPTER, JAVA_ADAPTER];
 

package/src/mcp/handlers/rag-handler.js

@@ -1,9 +1,13 @@
 // KJC-PCS-0049 Step 7 — MCP handlers calling src/rag/* directly. Imports
 // from src/commands/* are forbidden by the layer-boundaries test
 // (MCP and CLI are peer layers); we hit the pure rag/* modules instead.
-import { countChunks, openVecStore, projectSlug } from "../../rag/vec-store.js";
+import { join } from "node:path";
+import { countChunks, projectSlug } from "../../rag/vec-store.js";
+import { openProjectStore } from "../../rag/project-store.js";
+import { countProjectChunks, emptyIndexRemedy } from "../../rag/migrate.js";
 import { makeGovernedEmbedder } from "../../rag/governed-embedder.js";
 import { indexProject } from "../../rag/indexer.js";
+import { ragExclude } from "../../rag/indexable.js";
 import { query } from "../../rag/retriever.js";
 import { getKarajanHome } from "../../utils/paths.js";
 import { resolveProjectDir, buildConfig, responseText, failPayload } from "../shared-helpers.js";
@@ -28,9 +32,14 @@ export async function handleRagQuery(args, server) {
     // projectDir, `project: "all"` disables the filter, `project: <slug>`
     // overrides it.
     const project = args?.project === "all" ? null : (args?.project || projectSlug(projectDir) || null);
-    const db = openVecStore({ dim: config?.rag?.embedder?.dim || 768 });
+    const dim = config?.rag?.embedder?.dim || 768;
+    // KJC-TSK-0883 (ADR 0011): el indice del proyecto, como la CLI (0882).
+    const db = openProjectStore({ projectDir, dim });
     try {
-      if (countChunks(db) === 0) return responseText({ hits: [], empty: true, topK, scope, project });
+      if (countChunks(db) === 0 || (project && countProjectChunks(db, project) === 0)) {
+        const remedy = emptyIndexRemedy({ slug: project, legacyPath: join(getKarajanHome(), "rag.db"), dim });
+        return responseText({ hits: [], empty: true, topK, scope, project, remedy });
+      }
       const hits = await query(db, makeGovernedEmbedder(config), text, { topK, scope, project });
       return responseText({ hits, empty: false, topK, scope, project });
     } finally { db.close(); }
@@ -43,12 +52,13 @@ export async function handleRagIndex(args, server) {
   try {
     const projectDir = await resolveProjectDir(server, args?.projectDir);
     const config = await buildConfig({ ...args, projectDir }, "rag-index");
-    const db = openVecStore({ dim: config?.rag?.embedder?.dim || 768 });
+    const db = openProjectStore({ projectDir, dim: config?.rag?.embedder?.dim || 768 });
     try {
       const totals = await indexProject(projectDir, {
         db, embedder: makeGovernedEmbedder(config),
         karajanHome: getKarajanHome(), logger: silentLogger,
         withSources: Boolean(args?.withSources),
+        exclude: ragExclude(config), // KJC-TSK-0891
       });
       return responseText(totals);
     } finally { db.close(); }

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

@@ -24,7 +24,7 @@
 import { generateDiff } from "../../review/diff-generator.js";
 import { finalizeGitAutomation } from "../../git/automation.js";
 import { listCommitsBetween, listFilesChangedSince } from "../../utils/git.js";
-import { loadPlan, projectSlug as slugFor } from "../../plan/plan-store.js";
+import { loadPlan } from "../../plan/plan-store.js";
 import { computePlanAdherenceScore } from "../../audit/plan-adherence.js";
 import { saveSession, markSessionStatus } from "../../session/store.js";
 import {
@@ -334,22 +334,24 @@ export async function handleMaxIterationsReached({ session, budgetSummary, emitt
   return { approved: false, sessionId: session.id, reason: "max_iterations" };
 }
 
+/**
+ * KJC-TSK-0884 (ADR 0011): the board starts by itself, like Sonar. Only a
+ * declared false on either switch opts out; nothing declared means on.
+ */
+export const boardAutoStartWanted = (config) => config?.hu_board?.auto_start !== false && config?.hu_board?.enabled !== false;
+
 export async function tryAutoStartBoard(config, logger, emitter, eventBase) {
-  // TSK-0273: gate on hu_board.auto_start alone. The previous double-gate
-  // (enabled && auto_start) was confusing because `enabled` was never the
-  // user-facing switch — only auto_start was. This matches the AC: "kj run
-  // auto-inicia el board server si hu_board.auto_start es true".
-  if (!config.hu_board?.auto_start) return;
+  if (!boardAutoStartWanted(config)) return;
   // Never auto-start during vitest: races the PID file and starts a detached
   // process that outlives the test run.
   if (process.env.VITEST || process.env.NODE_ENV === "test") return;
 
   try {
-    const { startBoard, renderBoardBanner } = await import("../../commands/board.js");
-    const boardPort = config.hu_board.port || 4000;
-    // Scope the board URL to the current run's project (`#board/<slug>`)
-    // so the user lands on a filtered view, not the global dashboard.
-    const slug = config.projectDir ? slugFor(config.projectDir) : null;
+    const { startBoard, renderBoardBanner, boardSlug } = await import("../../commands/board.js");
+    const boardPort = config.hu_board?.port || 4000;
+    // KJC-TSK-0884: the project's scoped view (/p/<slug>), the parent repo's
+    // even from a worktree lane.
+    const slug = config.projectDir ? boardSlug(config.projectDir) : null;
     const boardResult = await startBoard(boardPort, { projectSlug: slug });
     const status = boardResult.alreadyRunning ? "already running" : "started";
     // Highlighted URL box — visible regardless of log level (matches the

package/src/orchestrator/drivers/pre-loop-phases/auto-hu-batch.js

@@ -122,9 +122,10 @@ export async function maybeGenerateAutoHuBatch({
   // node process around after the suite (TSK-0273).
   if (process.env.VITEST || process.env.NODE_ENV === "test") return;
   try {
-    const { startBoard, renderBoardBanner } = await import("../../../commands/board.js");
+    const { startBoard, renderBoardBanner, boardSlug } = await import("../../../commands/board.js");
     const desiredPort = session.config_snapshot?.hu_board?.port ?? 4000;
-    const boardResult = await startBoard(desiredPort);
+    // KJC-TSK-0884: its project's scoped view, not the global dashboard.
+    const boardResult = await startBoard(desiredPort, { projectSlug: projectDir ? boardSlug(projectDir) : null });
     const url = boardResult.url;
     const status = boardResult.alreadyRunning ? "already running" : "started";
     const projectName = batch.projectName || "Auto-generated HUs";

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,128 @@
+/**
+ * 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, readFileSync, readSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+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);
+};
+
+/**
+ * KJC-TSK-0900: `.ragignore` at the project root, gitignore syntax, versioned so
+ * the whole team inherits it. `dir/` is a folder anywhere, `*.csv` an extension
+ * anywhere, `/data` anchored to the root, a path with a slash is from the root.
+ * `!` negation is not supported (said in the docs). Re-read when it changes.
+ */
+const ragignoreCache = new Map();
+export function ragignoreGlobs(projectDir) {
+  if (!projectDir) return [];
+  const file = join(projectDir, ".ragignore");
+  let mtime;
+  try { mtime = statSync(file).mtimeMs; } catch { return []; }
+  const hit = ragignoreCache.get(file);
+  if (hit?.mtime === mtime) return hit.globs;
+  const globs = [];
+  for (const raw of readFileSync(file, "utf8").split("\n")) {
+    let p = raw.trim();
+    if (!p || p.startsWith("#") || p.startsWith("!")) continue;
+    const dirOnly = p.endsWith("/");
+    p = p.replace(/^\/+|\/+$/g, "");
+    if (!p) continue;
+    const base = raw.trim().startsWith("/") || p.includes("/") ? p : `**/${p}`;
+    globs.push(`${base}/**`);
+    if (!dirOnly) globs.push(base);
+  }
+  ragignoreCache.set(file, { mtime, globs });
+  return globs;
+}
+
+/** 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 (matchesAny(rel, ragignoreGlobs(projectDir))) return `${rel} is excluded by the project's .ragignore`;
+  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;
     }
   }