karajan-code 4.35.1 → 4.36.0

package/src/commands/rag.js

@@ -1,19 +1,49 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
 // KJC-PCS-0049 Step 6 — `kj rag` command group. Two subcommands:
 //   kj rag index [--project <slug>] [--with-sources]
 //   kj rag query <text>   [--scope plans|code|onboarding|all] [--top-k N] [--json]
 // Closes the v2.22.0 RAG MVP end-to-end from the terminal.
-import { openVecStore, countChunks, projectSlug, getLastIndexedCommit, setLastIndexedCommit } from "../rag/vec-store.js";
+import { countChunks, deleteChunksBySource, projectSlug, getLastIndexedCommit, setLastIndexedCommit } from "../rag/vec-store.js";
 import { makeGovernedEmbedder } from "../rag/governed-embedder.js";
-import { indexProject, indexProjectDelta } from "../rag/indexer.js";
+import { indexFile, indexProject, indexProjectDelta, sourceKind } from "../rag/indexer.js";
+import { indexableReason, ragExclude } from "../rag/indexable.js";
 import { fileIndexState } from "../rag/coverage.js";
 import { query } from "../rag/retriever.js";
 import { installPostMergeHook, maybeAutoUpdate } from "../rag/auto-update.js";
 import { indexLibrary, LIBRARY_PROJECT } from "../rag/library.js";
 import { loadGoldenQueries, runEval } from "../rag/eval.js";
 import { getKarajanHome } from "../utils/paths.js";
+import { countProjectChunks, emptyIndexRemedy, migrateProjectIndex } from "../rag/migrate.js";
+import { openLibraryStore, openProjectStore, projectDbPath } from "../rag/project-store.js";
 
+// KJC-TSK-0882 (ADR 0011): el indice es del proyecto, no de la maquina.
 function openDb(config) {
-  return openVecStore({ dim: config?.rag?.embedder?.dim || 768 });
+  return openProjectStore({ projectDir: config?.projectDir || process.cwd(), dim: config?.rag?.embedder?.dim || 768 });
+}
+
+async function indexFiles({ files, projectDir, db, embedder, slug, logger, json, exclude }) {
+  const totals = { indexed: 0, failed: 0, files: 0, deleted: 0 };
+  for (const file of files) {
+    const abs = isAbsolute(file) ? file : join(projectDir, file);
+    if (!existsSync(abs)) {
+      totals.deleted += deleteChunksBySource(db, abs); // gone from disk: gone from the index
+      continue;
+    }
+    // KJC-TSK-0891: the same criterion and kind as the full walk, or the
+    // remedy rag-first names would index nothing for a .mdx or a .astro.
+    const out = indexableReason(relative(projectDir, abs), abs, { exclude, projectDir });
+    if (out) {
+      logger.warn?.(`[rag] ${out}: not indexed`);
+      continue;
+    }
+    const r = await indexFile(abs, { db, embedder, logger, project: slug, kind: sourceKind(abs) });
+    totals.indexed += r.indexed; totals.failed += r.failed; totals.files += 1;
+  }
+  const deleted = totals.deleted ? `, ${totals.deleted} chunks deleted` : "";
+  if (json) process.stdout.write(`${JSON.stringify(totals)}\n`);
+  else logger.info(`[rag] indexed ${totals.indexed} chunk(s) across ${totals.files} file(s) (${totals.failed} failed${deleted})`);
+  return totals;
 }
 
 export async function ragIndexCommand({ config, logger, flags = {} }) {
@@ -22,6 +52,9 @@ export async function ragIndexCommand({ config, logger, flags = {} }) {
   try {
     const slug = projectSlug(projectDir);
     const embedder = makeGovernedEmbedder(config);
+    // KJC-TSK-0891: exactly these files. The remedy rag-first names for a file
+    // missing from the index: `--since auto` only reaches what changed.
+    if (flags.file?.length) return await indexFiles({ files: flags.file, projectDir, db, embedder, slug, logger, json: flags.json, exclude: ragExclude(config) });
     const sinceFlag = flags.since;
     // KJC-TSK-0455 — `--since auto` resolves to the last commit we indexed;
     // an explicit ref is honoured as-is. Without a baseline (first-time
@@ -35,7 +68,7 @@ export async function ragIndexCommand({ config, logger, flags = {} }) {
     let totals;
     if (since) {
       try {
-        totals = await indexProjectDelta(projectDir, { db, embedder, since, logger });
+        totals = await indexProjectDelta(projectDir, { db, embedder, since, logger, exclude: ragExclude(config) });
       } catch (err) {
         logger.warn?.(`[rag] delta index failed (${err.message}); falling back to full index`);
         totals = null;
@@ -46,13 +79,17 @@ export async function ragIndexCommand({ config, logger, flags = {} }) {
         db, embedder,
         karajanHome: getKarajanHome(), logger,
         withSources: Boolean(flags.withSources),
+        exclude: ragExclude(config),
       });
     }
     if (totals.head) setLastIndexedCommit(db, slug, totals.head);
     // KJC-TSK-0697 — the library corpus refreshes on every index run.
     // Best-effort and cheap: a handful of cards, content-hash dedup.
+    // KJC-TSK-0883: el canon de la maquina a su base; las fichas del proyecto, a la suya.
     try {
-      await indexLibrary({ db, embedder, logger, projectDir });
+      const lib = openLibraryStore({ dim: config?.rag?.embedder?.dim || 768 });
+      try { await indexLibrary({ db: lib, embedder, logger, scope: "machine" }); } finally { lib.close(); }
+      await indexLibrary({ db, embedder, logger, projectDir, scope: "project", project: slug });
     } catch (err) {
       logger.warn?.(`[rag] library index failed: ${err.message}`);
     }
@@ -87,7 +124,8 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
   // (--no-rag-update / config.rag.autoUpdate); failures degrade to a warn
   // inside maybeAutoUpdate and the query proceeds with the current index.
   await maybeAutoUpdate({ projectDir: config?.projectDir || process.cwd(), config, logger, flags });
-  const db = openDb(config);
+  // KJC-TSK-0883: --library abre la base del canon, no la del proyecto.
+  const db = flags.library ? openLibraryStore({ dim: config?.rag?.embedder?.dim || 768 }) : openDb(config);
   try {
     const topK = Math.max(1, Number(flags.topK) || 5);
     const scope = flags.scope || "all";
@@ -107,9 +145,12 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
     // deterministic recovery signal. The CLI was emitting just `[]`, which
     // is indistinguishable from "query returned zero hits over a populated
     // store" and forced consumers to parse stderr.
-    if (countChunks(db) === 0) {
-      logger.warn("[rag] No chunks indexed yet. Run 'kj rag index' first.");
-      if (flags.json) process.stdout.write(`${JSON.stringify({ hits: [], empty: true, topK, scope })}\n`);
+    // KJC-TSK-0882: cuenta lo de ESTE proyecto; chunks ajenos no son respuesta.
+    if (countChunks(db) === 0 || (project && countProjectChunks(db, project) === 0)) {
+      // La library se rellena en cada `kj rag index`; migrar la llevaria al proyecto.
+      const remedy = library ? "kj rag index" : emptyIndexRemedy({ slug: project, legacyPath: join(getKarajanHome(), "rag.db"), dim: config?.rag?.embedder?.dim || 768 });
+      logger.warn(`[rag] ${library ? "the library index" : "this project's index"} holds no chunks of ${project || "any project"}: this is not an answer, run ${remedy}`);
+      if (flags.json) process.stdout.write(`${JSON.stringify({ hits: [], empty: true, topK, scope, remedy })}\n`);
       return [];
     }
     const mode = flags.mode || "hybrid";
@@ -183,7 +224,7 @@ export async function ragCoversCommand({ file, config, flags = {} }) {
   const projectDir = config?.projectDir || process.cwd();
   const db = openDb(config);
   try {
-    const state = fileIndexState(projectDir, file, { db });
+    const state = fileIndexState(projectDir, file, { db, exclude: ragExclude(config) });
     if (flags.json) process.stdout.write(`${JSON.stringify(state)}\n`);
     else process.stdout.write(`${state.state}: ${state.reason}\n`);
     if (!state.canAnswer) process.exitCode = 1;
@@ -192,3 +233,21 @@ export async function ragCoversCommand({ file, config, flags = {} }) {
     db.close();
   }
 }
+
+/**
+ * KJC-TSK-0888 (RAG-P1a, ADR 0011) — `kj rag migrate`: copia los chunks de este
+ * proyecto desde la base global a su propio indice, con sus embeddings, sin
+ * volver a embeber. La base global no se toca.
+ */
+export async function ragMigrateCommand({ config, flags = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const res = migrateProjectIndex({
+    slug: projectSlug(projectDir),
+    legacyPath: join(getKarajanHome(), "rag.db"),
+    targetPath: projectDbPath(projectDir),
+    dim: config?.rag?.embedder?.dim || 768,
+  });
+  if (flags.json) process.stdout.write(`${JSON.stringify(res)}\n`);
+  else process.stdout.write(`rag migrate: ${res.state} — ${res.reason}\n`);
+  return res;
+}

package/src/commands/review-gate.js

@@ -188,6 +188,14 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   // KJC-TSK-0687 (MG-B): the verifiable half of TDD — sources without a
   // single test change warn (block via method_gates.tests_with_code).
   const changedFiles = (await rawDiff(flags.range, ["--name-only"])).split("\n").map((f) => f.trim()).filter(Boolean);
+  // KJC-BUG-0229: un fichero BORRADO no es una fuente que el scan pueda indexar
+  // ni sobre la que el RAG pueda responder, asi que exigirlo era pedir lo
+  // imposible: una PR que retiraba 45 ficheros se paro dos veces y acumulo tres
+  // excepciones por la misma causa mecanica. Los requisitos de Sonar y de RAG
+  // se evaluan sobre lo que sigue VIVO tras el cambio (A, C, M, R); policy, LOC
+  // y tests-with-code siguen viendo el diff entero, porque ahi un borrado si
+  // cuenta. El borrado danino lo cubre la review cruzada, que lee todo el diff.
+  const liveFiles = (await rawDiff(flags.range, ["--name-only", "--diff-filter=ACMR"])).split("\n").map((f) => f.trim()).filter(Boolean);
 
   // KJC-TSK-0688 (MG-C) + KJC-TSK-0691 (MG-E): oversized-diff policy.
   // Field case: a 522-line PR sailed past the warning with a
@@ -357,6 +365,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
       }
     }
     let res = await checkVerdict(projectDir, diff);
+    if (res.note) console.log(`ℹ ${res.note}`);
     // KJC-TSK-0838: a reviewed diff with code enters only if the verdict's
     // sonar block proves the analysis ran and covered every staged source.
     // The headless pipeline stamps its verdict after its own sonar stage and
@@ -371,7 +380,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
         res = { ok: false, verdict: res.verdict, reason: `Sonar is mandatory for code — ${why}` };
       }
     } else if (res.ok) {
-      const req = checkSonarRequirement({ config, stagedFiles: changedFiles, sonar: res.verdict.sonar, standingExceptions: std.standing });
+      const req = checkSonarRequirement({ config, stagedFiles: liveFiles, sonar: res.verdict.sonar, standingExceptions: std.standing });
       if (!req.ok) res = { ok: false, verdict: res.verdict, reason: req.reason };
       else if (req.mode === "granted") console.log(formatSonarGrant(req.grant));
     }
@@ -387,7 +396,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
       if (!warnIds.includes(RAG_RULE_ID)) warnIds.push(RAG_RULE_ID);
     } else if (res.ok) {
       const { harness, verified, mismatched, drift } = readRagLedger(projectDir);
-      const rreq = checkRagVerdict({ config, stagedFiles: changedFiles, rag: res.verdict.rag, harness, verified, mismatched, drift, standingExceptions: std.standing });
+      const rreq = checkRagVerdict({ config, stagedFiles: liveFiles, rag: res.verdict.rag, harness, verified, mismatched, drift, standingExceptions: std.standing });
       if (!rreq.ok) res = { ok: false, verdict: res.verdict, reason: rreq.reason };
       else if (rreq.mode === "granted" && rreq.grant) console.log(formatRagGrant(rreq.grant));
     }
@@ -414,7 +423,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   if (flags.sonar !== false) {
     // KJC-TSK-0795 AC3: only issues on lines this diff ADDS may veto.
     const touchedLines = addedLinesByFile(await rawDiff(flags.range, ["--unified=0"]));
-    const pre = await runSonarPregate({ config, stagedFiles: changedFiles, touchedLines, logger });
+    const pre = await runSonarPregate({ config, stagedFiles: liveFiles, touchedLines, logger });
     if (!pre.available) {
       // KJC-BUG-0156 (issue #1543): a scan that FAILED must not read like one
       // more config warning — it hid a dead quality gate for 8 straight PRs.
@@ -459,7 +468,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   // KJC-TSK-0838: fail-CLOSED for code. Sonar disabled, down, skipped by
   // flag, or blind to a staged source — the diff does not reach the reviewer.
   // Docs-only diffs pass; a live human grant on the rule is the only escape.
-  const sonarReq = checkSonarRequirement({ config, stagedFiles: changedFiles, sonar: sonarRecord, standingExceptions: std.standing });
+  const sonarReq = checkSonarRequirement({ config, stagedFiles: liveFiles, sonar: sonarRecord, standingExceptions: std.standing });
   if (!sonarReq.ok) {
     console.log(`✗ ${sonarReq.reason}`);
     process.exitCode = 1;
@@ -476,7 +485,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   // the 16-sep bugs were exactly the twin nobody touched.
   const ledger = readRagLedger(projectDir);
   const newFiles = (await rawDiff(flags.range, ["--name-only", "--diff-filter=A"])).split("\n").map((f) => f.trim()).filter(Boolean);
-  const ragReq = checkRagRequirement({ config, stagedFiles: changedFiles, newFiles, ledger, standingExceptions: std.standing });
+  const ragReq = checkRagRequirement({ config, stagedFiles: liveFiles, newFiles, ledger, standingExceptions: std.standing });
   if (!ragReq.ok) {
     console.log(`✗ ${ragReq.reason}`);
     process.exitCode = 1;

package/src/commands/watch.js

@@ -8,13 +8,13 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 
 export async function watchStartCommand({ config, logger, flags = {} }) {
   const projectDir = config?.projectDir || process.cwd();
-  const existing = readPidFile();
+  const existing = readPidFile(projectDir);
   if (existing && isPidAlive(existing)) { logger.info(`Watcher already running (pid ${existing}).`); return { pid: existing, started: false }; }
-  if (existing) clearPidFile();
+  if (existing) clearPidFile(projectDir);
   if (flags.foreground) {
-    writePidFile();
+    writePidFile(projectDir);
     const stop = startWatcher({ projectDir, config, logger, withSources: !!flags.withSources });
-    const shutdown = async () => { await stop(); clearPidFile(); process.exit(0); };
+    const shutdown = async () => { await stop(); clearPidFile(projectDir); process.exit(0); };
     process.on("SIGINT", shutdown).on("SIGTERM", shutdown);
     logger.info(`Watcher started in foreground (pid ${process.pid}). Ctrl+C to stop.`);
     return { pid: process.pid, started: true };
@@ -26,18 +26,21 @@ export async function watchStartCommand({ config, logger, flags = {} }) {
   return { pid: child.pid, started: true };
 }
 
-export async function watchStopCommand({ logger }) {
-  const pid = readPidFile();
+// KJC-TSK-0883: stop/status son del watcher de ESTE proyecto, resuelto como en start.
+export async function watchStopCommand({ config, logger }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const pid = readPidFile(projectDir);
   if (!pid) { logger.info("No watcher running."); return { stopped: false }; }
-  if (!isPidAlive(pid)) { clearPidFile(); logger.info(`Stale PID file removed (process ${pid} was not alive).`); return { stopped: false, stale: true }; }
+  if (!isPidAlive(pid)) { clearPidFile(projectDir); logger.info(`Stale PID file removed (process ${pid} was not alive).`); return { stopped: false, stale: true }; }
   try { process.kill(pid, "SIGTERM"); } catch (err) { logger.warn(`Could not signal pid ${pid}: ${err.message}`); }
-  clearPidFile();
+  clearPidFile(projectDir);
   logger.info(`Watcher (pid ${pid}) stopped.`);
   return { stopped: true, pid };
 }
 
-export async function watchStatusCommand({ logger }) {
-  const pid = readPidFile();
+export async function watchStatusCommand({ config, logger }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const pid = readPidFile(projectDir);
   const alive = pid && isPidAlive(pid);
   if (alive) logger.info(`Watcher running (pid ${pid}).`);
   else if (pid) logger.warn(`Stale PID file (process ${pid} not alive). Run \`kj watch stop\` to clean up.`);

package/src/config/defaults.js

@@ -179,10 +179,11 @@ const DEFAULTS = {
       test_inclusions: "**/*.test.js,**/*.spec.js,**/tests/**,**/__tests__/**"
     }
   },
+  // KJC-TSK-0884 (ADR 0011): on by default, like Sonar; a declared false opts out.
   hu_board: {
-    enabled: false,
+    enabled: true,
     port: 4000,
-    auto_start: false
+    auto_start: true
   },
   language: "en",
   hu_language: "en",

package/src/environment/playbook.js

@@ -12,6 +12,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { upsertManagedBlock } from "../utils/managed-markers.js";
+import { detectRulesync, RULESYNC_RULE, rulesyncRuleSeed } from "../utils/rulesync.js";
 import { panelLine } from "./panel.js";
 
 // AB-A (KJC-TSK-0650): any agent can be the brain. AGENTS.md is the
@@ -114,15 +115,21 @@ export async function installPlaybook({ projectDir, target = "all", version = "1
     throw new Error(`unknown target "${target}" — use one of: ${PLAYBOOK_TARGETS.join(", ")}`);
   }
   const files = [];
-  for (const file of TARGET_FILES[target]) {
+  // KJC-TSK-0879: in a Rulesync repo its rule source is the only file of truth;
+  // `rulesync generate` would erase a block written into the agent files.
+  const rulesync = detectRulesync(projectDir);
+  for (const file of rulesync ? [RULESYNC_RULE] : TARGET_FILES[target]) {
     const fullPath = path.join(projectDir, file);
-    let source = "";
+    let source = rulesync ? rulesyncRuleSeed() : "";
     try { source = await fs.readFile(fullPath, "utf8"); } catch { /* new file */ }
     const { content, action } = upsertManagedBlock({
       source, blockId: "playbook", version, body: renderPlaybook({ stateBackend, boardName, config }), style: "html",
       note: "do not edit: regenerated by kj env install",
     });
-    if (action !== "unchanged") await fs.writeFile(fullPath, content);
+    if (action !== "unchanged") {
+      await fs.mkdir(path.dirname(fullPath), { recursive: true });
+      await fs.writeFile(fullPath, content);
+    }
     files.push(file);
   }
   return { files, target };

package/src/harden/guidelines-engine.js

@@ -5,10 +5,11 @@
  * content the user keeps outside the markers. Idempotent.
  */
 
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 
 import { upsertManagedBlock } from "../utils/managed-markers.js";
+import { detectRulesync, RULESYNC_RULE, rulesyncRuleSeed } from "../utils/rulesync.js";
 import { guidelinesBody } from "./guidelines-templates.js";
 
 const BLOCK_VERSION = 1;
@@ -28,7 +29,12 @@ export function stripDevHooksBlock(source) {
   return { content: `${before}${joiner}${after}`, migrated: true };
 }
 
-const countLines = (text) => String(text || "").split("\n").filter((l) => l.trim()).length;
+const nonEmpty = (text) => String(text || "").split("\n").map((l) => l.trim()).filter(Boolean);
+const countLines = (text) => nonEmpty(text).length;
+
+// KJC-BUG-0232: "do not edit" se leia como "no toques esto", no como "lo que
+// escribas aqui se borra". Solo este bloque: los hooks sellados no cambian.
+const GUIDELINES_NOTE = "regenerated by kj harden: anything written inside is lost; keep your own rules outside this block";
 
 export function installGuidelines({ projectDir = process.cwd(), dryRun = false, language = null } = {}) {
   // KJC-BUG-0199 (issue #1773): the rules that enter the agent's context must
@@ -36,9 +42,13 @@ export function installGuidelines({ projectDir = process.cwd(), dryRun = false,
   // the configs; the guidelines just never asked.
   const body = guidelinesBody(language);
   const results = [];
-  for (const file of TARGETS) {
+  // KJC-TSK-0879: with Rulesync, its source is the file of truth; writing into
+  // CLAUDE.md/AGENTS.md would be erased by the next `rulesync generate`.
+  const rulesync = detectRulesync(projectDir);
+  for (const file of rulesync ? [RULESYNC_RULE] : TARGETS) {
     const target = join(projectDir, file);
-    const raw = existsSync(target) ? readFileSync(target, "utf8") : "";
+    const seed = rulesync ? rulesyncRuleSeed() : "";
+    const raw = existsSync(target) ? readFileSync(target, "utf8") : seed;
     const { content: source, migrated } = stripDevHooksBlock(raw);
     const { content, action } = upsertManagedBlock({
       source,
@@ -46,13 +56,20 @@ export function installGuidelines({ projectDir = process.cwd(), dryRun = false,
       version: BLOCK_VERSION,
       body,
       style: "html",
+      note: GUIDELINES_NOTE,
     });
     // KJC-BUG-0206: harden removing rules is a fact worth saying. It silently
     // dropped six lines from this repo's own files because the detected language
     // had no block, and "updated" read like an improvement.
     const shrank = countLines(content) < countLines(raw);
-    if (!dryRun && (migrated || action !== "unchanged")) writeFileSync(target, content);
-    results.push({ file, action: migrated ? "migrated" : action, ...(shrank ? { shrank: true } : {}) });
+    // KJC-BUG-0232: decir CUALES se van, o el aviso obliga a salir a git diff.
+    const kept = new Set(nonEmpty(content));
+    const removed = shrank ? nonEmpty(raw).filter((l) => !kept.has(l) && !l.includes("kj:managed:")) : [];
+    if (!dryRun && (migrated || action !== "unchanged")) {
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, content);
+    }
+    results.push({ file, action: migrated ? "migrated" : action, ...(shrank ? { shrank: true, removed } : {}) });
   }
   return { dryRun, guidelines: results };
 }

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 || ""));
@@ -980,9 +990,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 +1179,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 +1231,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 +1303,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";