karajan-code 2.33.0 → 3.0.0

package/src/audit/injection-findings.js

@@ -0,0 +1,105 @@
+/**
+ * Prompt-injection findings collector for `kj audit` (KJC-TSK-0498).
+ * Scans `.karajan/specs/**`, `.karajan/domain.md` and
+ * `.karajan/onboarding/**` reusing `src/utils/injection-guard.js`.
+ * Best-effort: missing folders return `scanned: 0`.
+ */
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { scanForInjection } from "../utils/injection-guard.js";
+
+const MAX_FILE_BYTES = 256 * 1024;
+const MAX_DEPTH = 6;
+const SEVERITY_BY_TYPE = { directive: "HIGH", unicode: "MEDIUM", comment_block: "LOW" };
+
+const SCAN_TARGETS = [
+  { rel: ".karajan/specs", kind: "dir" },
+  { rel: ".karajan/onboarding", kind: "dir" },
+  { rel: ".karajan/domain.md", kind: "file" },
+];
+
+export async function collectInjectionFindings(rootDir, logger = null) {
+  if (!rootDir) return { available: false, reason: "rootDir not provided" };
+  const findings = [];
+  let scanned = 0;
+  try {
+    for (const target of SCAN_TARGETS) {
+      const abs = path.join(rootDir, target.rel);
+      const files = target.kind === "dir"
+        ? await listFiles(abs, 0)
+        : (await fileExists(abs)) ? [abs] : [];
+      for (const file of files) {
+        scanned += 1;
+        const content = await safeRead(file);
+        if (!content) continue;
+        const result = scanForInjection(content);
+        if (result.clean) continue;
+        for (const f of result.findings) {
+          findings.push({
+            file: path.relative(rootDir, file),
+            type: f.type,
+            pattern: f.pattern,
+            snippet: f.snippet,
+            line: f.line,
+            severity: SEVERITY_BY_TYPE[f.type] || "LOW",
+          });
+        }
+      }
+    }
+  } catch (err) {
+    if (logger?.warn) logger.warn(`injection-findings collector failed: ${err.message}`);
+    return { available: false, reason: `collector failed: ${err.message}` };
+  }
+  return { available: true, scanned, total: findings.length, findings };
+}
+
+export function groupInjectionBySeverity(findings) {
+  const groups = { HIGH: [], MEDIUM: [], LOW: [] };
+  for (const f of findings || []) {
+    const sev = (f.severity || "LOW").toUpperCase();
+    if (groups[sev]) groups[sev].push(f);
+    else groups.LOW.push(f);
+  }
+  return groups;
+}
+
+async function listFiles(dir, depth) {
+  if (depth > MAX_DEPTH) return [];
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const entry of entries) {
+    const abs = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const nested = await listFiles(abs, depth + 1);
+      out.push(...nested);
+    } else if (entry.isFile()) {
+      out.push(abs);
+    }
+  }
+  return out;
+}
+
+async function fileExists(file) {
+  try {
+    const s = await stat(file);
+    return s.isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function safeRead(file) {
+  try {
+    const s = await stat(file);
+    if (s.size > MAX_FILE_BYTES) return null;
+    return await readFile(file, "utf8");
+  } catch {
+    return null;
+  }
+}

package/src/checks/hardware.js

@@ -0,0 +1,150 @@
+// Advisory hardware checks: warn (not fail) so the pipeline keeps running.
+// RAM < 4 GB silently OOM-kills the RAG embedder; disk < 5 GB corrupts
+// Ollama model shards. GPU detection is best-effort and never throws.
+
+import os from "node:os";
+import { statfs } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { STRATEGY } from "./types.js";
+
+const RAM_WARN_GB = 4;
+const RAM_RECOMMENDED_GB = 8;
+const DISK_WARN_GB = 5;
+const DISK_RECOMMENDED_GB = 20;
+const GPU_DETECT_TIMEOUT_MS = 1500;
+
+const bytesToGb = (bytes) => Math.round((bytes / 1024 ** 3) * 10) / 10;
+const info = (detail, extra) => ({ ok: true, severity: "info", detail, extra });
+const warn = (detail, fix, extra) => ({ ok: false, severity: "warn", detail, fix, extra });
+
+function createRamCheck() {
+  return {
+    name: "hw-ram",
+    label: "System RAM",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      const totalGb = bytesToGb(os.totalmem());
+      const freeGb = bytesToGb(os.freemem());
+      const base = `${totalGb} GB total, ${freeGb} GB free`;
+      if (totalGb < RAM_WARN_GB) {
+        return warn(
+          `${base} (RAG embedder needs >=${RAM_WARN_GB} GB)`,
+          "Disable local RAG (kj init --no-rag) or switch rag.embedder.provider to openai/voyage/cohere.",
+          { totalGb, freeGb, threshold: RAM_WARN_GB }
+        );
+      }
+      if (totalGb < RAM_RECOMMENDED_GB) {
+        return info(`${base} (>=${RAM_RECOMMENDED_GB} GB recommended for parallel runs)`, { totalGb, freeGb });
+      }
+      return info(base, { totalGb, freeGb });
+    },
+  };
+}
+
+function createCpuCheck() {
+  return {
+    name: "hw-cpu",
+    label: "CPU",
+    strategy: STRATEGY.NONE,
+    async detect() {
+      const cpus = os.cpus();
+      const model = cpus[0]?.model?.trim() || "unknown";
+      const cores = cpus.length;
+      const arch = os.arch();
+      return info(`${cores} cores, ${arch} (${model})`, { cores, arch, model });
+    },
+  };
+}
+
+function createDiskCheck() {
+  return {
+    name: "hw-disk",
+    label: "Disk space (cwd)",
+    strategy: STRATEGY.MANUAL,
+    async detect() {
+      try {
+        const stat = await statfs(process.cwd());
+        const freeGb = bytesToGb(stat.bsize * stat.bavail);
+        if (freeGb < DISK_WARN_GB) {
+          return warn(
+            `${freeGb} GB free (>=${DISK_WARN_GB} GB recommended)`,
+            "Free disk space. Ollama models alone take 3-5 GB; the RAG store grows ~50 MB per 1k LOC indexed.",
+            { freeGb, threshold: DISK_WARN_GB }
+          );
+        }
+        const note = freeGb < DISK_RECOMMENDED_GB ? ` (>=${DISK_RECOMMENDED_GB} GB recommended)` : "";
+        return info(`${freeGb} GB free${note}`, { freeGb });
+      } catch (err) {
+        return info(`Cannot read free disk space: ${err.message}`);
+      }
+    },
+  };
+}
+
+function runGpuCommand(cmd, args) {
+  return new Promise((resolve) => {
+    let stdout = "";
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+    try {
+      const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "ignore"] });
+      const timer = setTimeout(() => {
+        try { child.kill("SIGKILL"); } catch { /* noop */ }
+        finish(null);
+      }, GPU_DETECT_TIMEOUT_MS);
+      child.stdout.on("data", (chunk) => { stdout += chunk.toString(); });
+      child.on("error", () => { clearTimeout(timer); finish(null); });
+      child.on("close", (code) => {
+        clearTimeout(timer);
+        finish(code === 0 ? stdout : null);
+      });
+    } catch {
+      finish(null);
+    }
+  });
+}
+
+async function detectGpu() {
+  const platform = process.platform;
+  if (platform === "linux" || platform === "win32") {
+    const out = await runGpuCommand("nvidia-smi", ["--query-gpu=name", "--format=csv,noheader"]);
+    const model = out?.split("\n").map((l) => l.trim()).find(Boolean);
+    if (model) return { vendor: "NVIDIA", model };
+    return null;
+  }
+  if (platform === "darwin") {
+    const out = await runGpuCommand("system_profiler", ["SPDisplaysDataType"]);
+    if (!out) return null;
+    const match = out.match(/Chipset Model:\s*(.+)/);
+    if (!match) return null;
+    const model = match[1].trim();
+    const vendor = /Apple/i.test(model) ? "Apple" : /AMD|Radeon/i.test(model) ? "AMD" : /Intel/i.test(model) ? "Intel" : "GPU";
+    return { vendor, model };
+  }
+  return null;
+}
+
+function createGpuCheck() {
+  return {
+    name: "hw-gpu",
+    label: "GPU",
+    strategy: STRATEGY.NONE,
+    async detect() {
+      const gpu = await detectGpu();
+      if (!gpu) {
+        return info("No discrete GPU detected (CPU-only)", { detected: false });
+      }
+      return info(`${gpu.vendor} ${gpu.model}`, { detected: true, vendor: gpu.vendor, model: gpu.model });
+    },
+  };
+}
+
+export function getHardwareChecks() {
+  return [createRamCheck(), createCpuCheck(), createDiskCheck(), createGpuCheck()];
+}
+
+export const __test = { RAM_WARN_GB, RAM_RECOMMENDED_GB, DISK_WARN_GB, DISK_RECOMMENDED_GB, GPU_DETECT_TIMEOUT_MS, bytesToGb, detectGpu };

package/src/checks/node.js

@@ -1,18 +1,17 @@
 /**
- * Node.js runtime version check. Requires Node >= 18 — the LTS baseline that
- * ships every runtime feature Karajan needs: ESM support, `fetch` (built-in),
- * `structuredClone` (17+), `AbortSignal.timeout` (17.3+), and
- * `Array.prototype.findLast` / `findLastIndex` (18+). Nothing in the runtime
- * code path uses Node 20+ APIs (no `Promise.withResolvers`, no
- * `Object.groupBy`, no `Set.prototype.union/intersection`, no
- * `Array.prototype.toSorted`). Strategy: manual — we cannot auto-upgrade the
- * runtime. Users on older Node get a clear upgrade instruction with nvm + brew
- * hints instead of a silent runtime crash.
+ * Node.js runtime version check. Requires Node >= 22 — the Active LTS
+ * baseline since Karajan v3.0.0 (KJC-TSK-0500, 2026-06-03). Node 20 was
+ * dropped because (a) Node 20 reaches EOL on 2026-04-30 and (b) three
+ * dependencies forced the bump: lint-staged 17 needs ≥22.22.1, commander
+ * 15 needs ≥22.12.0, and better-sqlite3 v12.10+ dropped Node 20 prebuilds.
+ * Strategy: manual — we cannot auto-upgrade the runtime. Users on older
+ * Node get a clear upgrade instruction with nvm + brew hints instead of a
+ * silent runtime crash.
  */
 
 import { STRATEGY } from "./types.js";
 
-export const MIN_NODE_MAJOR = 18;
+export const MIN_NODE_MAJOR = 22;
 
 /**
  * Accepts a version string in the form "v20.12.1" or "20.12.1" and returns

package/src/cli/register-meta.js

@@ -3,7 +3,8 @@ import { triageCommand } from "../commands/triage.js";
 import { researcherCommand } from "../commands/researcher.js";
 import { architectCommand } from "../commands/architect.js";
 import { onboardCommand } from "../commands/onboard.js";
-import { ragIndexCommand, ragQueryCommand } from "../commands/rag.js";
+import { ragIndexCommand, ragQueryCommand, ragInstallHooksCommand, ragEvalCommand } from "../commands/rag.js";
+import { ragMcpCommand } from "../commands/rag-mcp.js";
 import { watchStartCommand, watchStopCommand, watchStatusCommand } from "../commands/watch.js";
 import { auditCommand } from "../commands/audit.js";
 import { resumeCommand } from "../commands/resume.js";
@@ -12,6 +13,7 @@ import { webperfCommand } from "../commands/webperf.js";
 import { undoCommand } from "../commands/undo.js";
 import { syncCommand } from "../commands/sync.js";
 import { cleanCommand } from "../commands/clean.js";
+import { telemetryPreviewCommand, telemetryStatusCommand } from "../commands/telemetry.js";
 import { withConfig } from "./_shared.js";
 
 /**
@@ -104,12 +106,21 @@ export function registerMeta(program, { pkgVersion }) {
   rag.command("index")
     .description("Index plans + onboarding (and optionally project sources) into the local vector store")
     .option("--with-sources", "Also index the projectDir's JS/TS files")
+    .option("--since <ref>", "Only re-index files changed since <ref> ('auto' uses the last indexed commit; falls back to full index if unset). KJC-TSK-0455.")
     .option("--json", "Output the totals as JSON")
     .action(async (flags) => {
       await withConfig(pkgVersion, "rag-index", flags, async ({ config, logger }) => {
         await ragIndexCommand({ config, logger, flags });
       });
     });
+  rag.command("install-hooks")
+    .description("Install the post-merge git hook so the RAG index auto-refreshes after pulls/merges (KJC-TSK-0455)")
+    .option("--json", "Output the result as JSON")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "rag-install-hooks", flags, async ({ config, logger }) => {
+        await ragInstallHooksCommand({ config, logger, flags });
+      });
+    });
   rag.command("query <text>")
     .description("Run a semantic query against the indexed RAG corpus")
     .option("--scope <scope>", "plans | code | onboarding | all (default: all)", "all")
@@ -136,6 +147,30 @@ export function registerMeta(program, { pkgVersion }) {
         await ragQueryCommand({ text, config, logger, flags: { ...flags, mode: ragMode } });
       });
     });
+  // KJC-TSK-0483 — `kj rag eval` runs the golden-query harness and reports
+  // recall@5/recall@10/MRR. `--min-recall` turns it into a CI gate.
+  rag.command("eval")
+    .description("Score the retriever against a golden query set (recall@k + MRR)")
+    .option("--golden <path>", "Path to golden queries JSON (default: tests/rag/golden-queries.json)")
+    .option("--top-k <n>", "Number of hits to retrieve per query (default: 10)", "10")
+    .option("--min-recall <n>", "Fail (exit 1) if aggregated recall@5 falls below this threshold")
+    .option("--project <slug>", "Filter by project slug. Pass 'all' to query across every indexed project.")
+    .option("--json", "Emit the full report as JSON")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "rag-eval", flags, async ({ config, logger }) => {
+        await ragEvalCommand({ config, logger, flags });
+      });
+    });
+
+  // KJC-TSK-0492 PR3 — `kj rag mcp` exposes the kj-rag-mcp binary under the
+  // familiar `kj rag <subcommand>` surface so users discover it without
+  // grepping bin/. The action dynamic-imports the binary, which takes over
+  // stdio for MCP transport; the CLI process never returns.
+  rag.command("mcp")
+    .description("Start the standalone RAG MCP server (kj_rag_query + kj_rag_index only). Same as running `kj-rag-mcp` directly")
+    .action(async () => {
+      await ragMcpCommand();
+    });
 
   // KJC-TSK-0441 — `kj watch [start|stop|status]` for live RAG re-index.
   const watch = program.command("watch").description("Live RAG re-index daemon");
@@ -287,6 +322,27 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // KJC-TSK-0496 — surface the exact telemetry payload without sending it,
+  // and report whether telemetry is currently enabled. Read-only inspection
+  // commands so users can audit the contract without grepping the source.
+  const telemetry = program.command("telemetry").description("Inspect what Karajan telemetry sends and whether it's enabled (never opens a socket)");
+  telemetry.command("preview")
+    .description("Print the exact JSON payload for every event type (install, cli_command, pipeline_complete) — no network call")
+    .option("--json", "Emit the full preview as JSON")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "telemetry:preview", flags, async ({ config, logger }) => {
+        await telemetryPreviewCommand({ config, logger, version: pkgVersion, json: Boolean(flags.json) });
+      });
+    });
+  telemetry.command("status")
+    .description("Report whether telemetry is enabled and where the endpoint lives")
+    .option("--json", "Emit the status as JSON")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "telemetry:status", flags, async ({ config, logger }) => {
+        await telemetryStatusCommand({ config, logger, json: Boolean(flags.json) });
+      });
+    });
+
   program
     .command("clean")
     .description("Garbage-collect stale plans, sessions and HU batches (dry-run by default)")

package/src/cli/register-pipeline.js

@@ -110,6 +110,7 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--skip-role <role...>", "Force one or more roles OFF regardless of triage (e.g. --skip-role tester security)")
     .option("--force-role <role...>", "Force one or more roles ON regardless of triage")
     .option("--skip-spec-review", "Bypass the spec-reviewer pre-pipeline audit")
+    .option("--no-rag-update", "Skip the pre-run RAG drift check (KJC-TSK-0455). Same as config.rag.autoUpdate.onRun=false.")
     .option("--dry-run", "Show what would be executed without running anything")
     .option("--json", "Output JSON only (no styled display)")
     .option("-q, --quiet", "Show only stage status lines, suppress raw agent output (default)")

package/src/commands/doctor.js

@@ -29,6 +29,7 @@ import { getMcpHealthChecks } from "../checks/mcp-health.js";
 import { getSkillsChecks } from "../checks/skills.js";
 import { getDirSetupChecks } from "../checks/dir-setup.js";
 import { getProjectChecks } from "../checks/project-checks.js";
+import { getHardwareChecks } from "../checks/hardware.js";
 
 /**
  * Build the list of Check objects applicable to the current config.
@@ -50,6 +51,7 @@ function buildChecks(config, { projectOnly = false } = {}) {
   return [
     ...getSystemChecks(),
     ...getNodeChecks(),
+    ...getHardwareChecks(),
     ...getDirSetupChecks(),
     ...getConfigFileChecks(),
     ...getBinaryChecks(),

package/src/commands/init.js

@@ -12,6 +12,7 @@ import { createWizard, isTTY } from "../utils/wizard.js";
 import { runCommand } from "../utils/process.js";
 import { getInstallCommand } from "../utils/os-detect.js";
 import { detectOsLocale, SUPPORTED_LANGUAGES } from "../utils/locale.js";
+import { buildTelemetryPayload, sendTelemetryEvent } from "../utils/telemetry.js";
 import { detectRtk } from "../utils/rtk-detect.js";
 import { installRtk } from "../utils/rtk-install.js";
 import { detectProjectStack } from "../utils/stack-detect.js";
@@ -256,6 +257,42 @@ async function askBoardSecurity(wizard, config, logger) {
   logger.info(`  -> HU Board port: ${config.hu_board.port}`);
 }
 
+/**
+ * Explicit, opt-in telemetry consent. We do NOT inherit a "Karajan-installed
+ * users want to help" assumption — silence and missing config keys both mean
+ * "no". The prompt is rendered in the OS locale (EN/ES today; falls back to
+ * EN for everything else) so users see it in their own language even before
+ * they've set `config.language`. See src/utils/telemetry.js and the
+ * "Privacy & Telemetry" section of README.md for what gets sent.
+ */
+async function askTelemetry(wizard, config, logger) {
+  const locale = detectOsLocale();
+  const prompts = {
+    es: {
+      question: "¿Quieres ayudar a mejorar Karajan enviando telemetría anónima al proyecto?",
+      detail: "  (versión, OS, comandos, duración del pipeline — sin código, sin tareas, sin datos personales)",
+      previewIntro: "  Ejemplo del payload exacto que se enviaría al ejecutar `kj run` (puedes inspeccionar más con `kj telemetry preview`):",
+      enabled: "  -> Telemetría: activada (¡gracias!)",
+      disabled: "  -> Telemetría: desactivada",
+    },
+    en: {
+      question: "Help improve Karajan by sending anonymous telemetry to the project?",
+      detail: "  (version, OS, commands, pipeline duration — no code, no tasks, no personal data)",
+      previewIntro: "  Example of the exact payload that would be sent when you run `kj run` (inspect more with `kj telemetry preview`):",
+      enabled: "  -> Telemetry: enabled (thank you!)",
+      disabled: "  -> Telemetry: disabled",
+    },
+  };
+  const t = prompts[locale] || prompts.en;
+  logger.info(t.detail);
+  const example = buildTelemetryPayload("cli_command", { version: "x.y.z", command: "run" });
+  logger.info(t.previewIntro);
+  logger.info(`    ${JSON.stringify(example)}`);
+  const enabled = await wizard.confirm(t.question, false);
+  config.telemetry = enabled;
+  logger.info(enabled ? t.enabled : t.disabled);
+}
+
 async function runWizard(config, logger) {
   const agents = await detectAvailableAgents();
   const available = agents.filter((a) => a.available);
@@ -318,6 +355,10 @@ async function runWizard(config, logger) {
       await askBoardSecurity(wizard, config, logger);
     }
 
+    logger.info("");
+    logger.info("Privacy:");
+    await askTelemetry(wizard, config, logger);
+
     logger.info("");
   } finally {
     wizard.close();
@@ -735,7 +776,6 @@ export async function initCommand({ logger, flags = {} }) {
   await writeInitConfig(configPath, config);
 
   // Telemetry: anonymous install event (non-blocking)
-  const { sendTelemetryEvent } = await import("../utils/telemetry.js");
   const { readFileSync } = await import("node:fs");
   const { fileURLToPath } = await import("node:url");
   try {

package/src/commands/rag-mcp.js

@@ -0,0 +1,18 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { pathToFileURL } from "node:url";
+
+/**
+ * `kj rag mcp` — spawn the standalone RAG MCP server inline.
+ *
+ * KJC-TSK-0492 PR3. Adds CLI discoverability for the `kj-rag-mcp` binary
+ * so external IDE users can find it via the same `kj rag <subcommand>`
+ * surface they already know. The implementation dynamic-imports the
+ * binary entry so behavior stays identical to running `kj-rag-mcp`
+ * directly — same handlers, same transport, same orphan guard.
+ */
+export async function ragMcpCommand() {
+  const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+  const binPath = path.resolve(moduleDir, "../../bin/kj-rag-mcp.js");
+  await import(pathToFileURL(binPath).href);
+}

package/src/commands/rag.js

@@ -2,10 +2,12 @@
 //   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 } from "../rag/vec-store.js";
+import { openVecStore, countChunks, projectSlug, getLastIndexedCommit, setLastIndexedCommit } from "../rag/vec-store.js";
 import { makeEmbedder } from "../rag/embedders/factory.js";
-import { indexProject } from "../rag/indexer.js";
+import { indexProject, indexProjectDelta } from "../rag/indexer.js";
 import { query } from "../rag/retriever.js";
+import { installPostMergeHook } from "../rag/auto-update.js";
+import { loadGoldenQueries, runEval } from "../rag/eval.js";
 import { getKarajanHome } from "../utils/paths.js";
 
 function openDb(config) {
@@ -16,15 +18,39 @@ export async function ragIndexCommand({ config, logger, flags = {} }) {
   const projectDir = config?.projectDir || process.cwd();
   const db = openDb(config);
   try {
-    const totals = await indexProject(projectDir, {
-      db, embedder: makeEmbedder(config),
-      karajanHome: getKarajanHome(), logger,
-      withSources: Boolean(flags.withSources),
-    });
+    const slug = projectSlug(projectDir);
+    const embedder = makeEmbedder(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
+    // index) we fall back to a full reindex with a friendly warning so the
+    // hook in PR2 stays a no-op-friendly entrypoint.
+    let since = null;
+    if (sinceFlag) {
+      since = sinceFlag === "auto" ? getLastIndexedCommit(db, slug) : sinceFlag;
+      if (!since) logger.warn?.("[rag] --since auto: no previous index recorded; running full index");
+    }
+    let totals;
+    if (since) {
+      try {
+        totals = await indexProjectDelta(projectDir, { db, embedder, since, logger });
+      } catch (err) {
+        logger.warn?.(`[rag] delta index failed (${err.message}); falling back to full index`);
+        totals = null;
+      }
+    }
+    if (!totals) {
+      totals = await indexProject(projectDir, {
+        db, embedder,
+        karajanHome: getKarajanHome(), logger,
+        withSources: Boolean(flags.withSources),
+      });
+    }
+    if (totals.head) setLastIndexedCommit(db, slug, totals.head);
     if (flags.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)`);
+      logger.info(`[rag] indexed ${totals.indexed} chunk(s) across ${totals.files} file(s) (${totals.failed} failed${totals.deleted ? `, ${totals.deleted} chunks deleted` : ""})`);
     }
     return totals;
   } finally {
@@ -32,6 +58,18 @@ export async function ragIndexCommand({ config, logger, flags = {} }) {
   }
 }
 
+// KJC-TSK-0455 — `kj rag install-hooks` wires the post-merge hook so the
+// local index keeps up after `git pull` / merges. Opt-in to keep us from
+// silently writing under `.git/hooks/`; pre-run drift check covers users
+// who never run it.
+export async function ragInstallHooksCommand({ config, logger, flags = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const res = installPostMergeHook({ projectDir, logger });
+  if (flags.json) process.stdout.write(`${JSON.stringify(res)}\n`);
+  else if (res.installed) logger.info(`[rag] installed post-merge hook at ${res.target}`);
+  return res;
+}
+
 export async function ragQueryCommand({ text, config, logger, flags = {} }) {
   if (!text) throw new Error("kj rag query: text argument required");
   const db = openDb(config);
@@ -75,3 +113,39 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
     db.close();
   }
 }
+
+// KJC-TSK-0483 — `kj rag eval`. Runs the retriever against a golden query
+// set and reports recall@5, recall@10 and MRR per query and aggregated.
+// Exit code != 0 when `--min-recall` is set and the aggregated recall@5
+// falls below the threshold — lets CI fail noisily on retrieval regressions.
+const DEFAULT_GOLDEN = "tests/rag/golden-queries.json";
+export async function ragEvalCommand({ config, logger, flags = {} }) {
+  const db = openDb(config);
+  try {
+    const goldenPath = flags.golden || DEFAULT_GOLDEN;
+    const queries = loadGoldenQueries(goldenPath);
+    const topK = Math.max(1, Number(flags.topK) || 10);
+    const detected = projectSlug(config?.projectDir || process.cwd());
+    const project = flags.project === "all" ? null : (flags.project || detected || null);
+    const embedder = makeEmbedder(config);
+    const runQuery = async (text, k) => query(db, embedder, text, { topK: k, scope: "all", project });
+    const report = await runEval(queries, runQuery, { topK, ks: [5, 10] });
+    if (flags.json) {
+      process.stdout.write(`${JSON.stringify(report)}\n`);
+    } else {
+      logger.info(`[rag-eval] ${report.aggregate.n} queries · recall@5=${report.aggregate.recall["@5"].toFixed(3)} · recall@10=${report.aggregate.recall["@10"].toFixed(3)} · MRR=${report.aggregate.mrr.toFixed(3)}`);
+      for (const r of report.results) {
+        const rank = r.firstRank == null ? "—" : `#${r.firstRank}`;
+        logger.info(`  [${rank}] ${r.query}`);
+      }
+    }
+    const minRecall = Number(flags.minRecall);
+    if (Number.isFinite(minRecall) && report.aggregate.recall["@5"] < minRecall) {
+      logger.error?.(`[rag-eval] recall@5=${report.aggregate.recall["@5"].toFixed(3)} below --min-recall=${minRecall}`);
+      process.exitCode = 1;
+    }
+    return report;
+  } finally {
+    db.close();
+  }
+}

package/src/commands/run.js

@@ -12,6 +12,7 @@ import { resolveRole } from "../config.js";
 import { parseCardId } from "../planning-game/adapter.js";
 import { confirmCwd } from "../utils/cwd-confirm.js";
 import { runSpecReview } from "../spec-review/run-spec-review.js";
+import { maybeAutoUpdate } from "../rag/auto-update.js";
 
 function createCliAskQuestion(opts = {}) {
   const { sessionId = null } = opts;
@@ -84,6 +85,13 @@ export async function runCommandHandler({ task, config, logger, flags }) {
     }
   }
 
+  // KJC-TSK-0455 — Pre-run drift check. Default ON; opt out with
+  // --no-rag-update (flag) or config.rag.autoUpdate.onRun=false. If the
+  // local index is behind HEAD we re-embed the delta before the agents
+  // start reading from the RAG store; on any failure we log and move on
+  // so a broken vector store never blocks a run.
+  await maybeAutoUpdate({ projectDir, config, logger, flags });
+
   // Best-effort session cleanup before starting
   try {
     const { cleanupExpiredSessions } = await import("../session-cleanup.js");