karajan-code 4.35.1 → 4.37.0

package/src/rag/library.js

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

package/src/rag/migrate.js

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

package/src/rag/onnx-fallback.js

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

package/src/rag/project-store.js

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

package/src/rag/watcher.js

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

package/src/review/comment-only.js

@@ -0,0 +1,93 @@
+/**
+ * KJC-BUG-0235 — are the lines a diff ADDS only comments? A cleanup deletes
+ * code and corrects the comments that were left lying about it; those added
+ * lines carry no behavior to test. Decided by scanning the resulting file, not
+ * by a line's first characters: " * factor" can continue a product. Strings are
+ * kept as code, so a docstring or a `//` inside a string is never a comment.
+ * An unknown syntax is not judged: everything counts as code (conservative).
+ */
+import { extname } from "node:path";
+
+// JSX/TSX and PHP are out: a `//` in a JSX text child or outside `<?php` is
+// rendered content. JSX inside a .js/.ts file is detected below.
+const C_STYLE = new Set([".js", ".mjs", ".cjs", ".ts", ".java", ".cs", ".go", ".kt", ".swift", ".c", ".cc", ".cpp", ".h", ".hpp", ".rs", ".scala"]);
+// Shell and Ruby are left out on purpose: a `#` line inside a heredoc is
+// content, not a comment, and this scanner does not parse heredocs.
+const HASH_STYLE = new Set([".py"]);
+const OPENER_AFTER = new Set([";", "{", "}", "(", ")", ",", "=", ":", "?", "!", "&", "|"]);
+
+/** @returns {Set<number>|null} 1-based lines holding code, or null for an unknown syntax */
+export function codeLines(content, file) {
+  const ext = extname(file).toLowerCase();
+  const cStyle = C_STYLE.has(ext);
+  if (!cStyle && !HASH_STYLE.has(ext)) return null;
+  const lines = new Set();
+  let line = 1;
+  let state = "code"; // code | line | block | string
+  let quote = "";
+  const s = String(content);
+  let step; // characters consumed by the current iteration (set in the body)
+  let prev = ""; // last non-space character seen in code on this line
+  let word = ""; // identifier being read in code
+  let lastWord = ""; // last complete identifier in code
+  for (let i = 0; i < s.length; i += step) {
+    const c = s[i];
+    const next = s[i + 1];
+    step = 1;
+    if (c === "\n") prev = "";
+    if (c === "\n") {
+      line++;
+      if (state === "line") state = "code";
+      // A line inside a multi-line string is part of its value, even if blank.
+      if (state === "string") lines.add(line);
+    } else if (state === "block") {
+      if (c === "*" && next === "/") { state = "code"; step = 2; }
+    } else if (state === "string") {
+      lines.add(line);
+      if (c === "\\") {
+        // An escaped newline continues the string on the next physical line: count it.
+        if (next === "\n") { line++; lines.add(line); }
+        step = 2;
+      } else if (c === quote) {
+        state = "code";
+      }
+    } else if (state === "code") {
+      // A comment opens only where one can: line start or after a separator.
+      // After `\`, `[` or an identifier a slash may belong to a regex literal
+      // (/a\/*b/, /[/*]/), so it is taken as code: in doubt, code.
+      const canOpen = prev === "" || OPENER_AFTER.has(prev);
+      if (/[\w$]/.test(c)) word += c;
+      else if (word) { lastWord = word; word = ""; }
+      // A tag where an expression starts (`= <div>`, `return <App />`) is JSX:
+      // its text children are rendered, so this file is not judged.
+      if (cStyle && c === "<" && /[A-Za-z/>]/.test(next ?? "") && (canOpen || lastWord === "return")) return null;
+      if (cStyle && canOpen && c === "/" && next === "/") state = "line";
+      else if (cStyle && canOpen && c === "/" && next === "*") { state = "block"; step = 2; }
+      else if (!cStyle && c === "#") state = "line";
+      else if (c === '"' || c === "'" || c === "`") { state = "string"; quote = c; lines.add(line); }
+      else if (!/\s/.test(c)) lines.add(line);
+      if (state === "code" && !/\s/.test(c)) prev = c;
+    }
+  }
+  return lines;
+}
+
+const COMMENT_START = /^(\/\/|\/\*|\*|#)/;
+
+/**
+ * Every added line (1-based, in the resulting file) is a comment or blank.
+ * Two checks must agree: the scanner says no code on the line AND the line
+ * itself starts like a comment (or is blank). The second one is a net against
+ * a scanner mistake, and it costs a knowingly accepted false negative: a block
+ * comment continuation without a leading `*` counts as code. Agreed criterion
+ * (KJC-BUG-0235): better a cleanup that still asks for tests than code let through.
+ */
+export function addedAreCommentsOnly(content, addedLines, file) {
+  const code = codeLines(content, file);
+  if (!code) return false;
+  const text = String(content).split("\n");
+  return [...addedLines].every((n) => {
+    const t = (text[n - 1] ?? "").trim();
+    return !code.has(n) && (t === "" || COMMENT_START.test(t));
+  });
+}

package/src/review/kj-provenance.js

@@ -11,6 +11,7 @@
  * Saltarse un gate ritualmente es peor que no tenerlo, porque parece que se
  * cumple.
  */
+import { execFileSync } from "node:child_process";
 import { createRequire } from "node:module";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -40,3 +41,28 @@ export function kjProvenance(moduleDir = here) {
     : `${v} (${root})`;
   return { version, root, linked, label };
 }
+
+const gitIn = (root) => (args) => execFileSync("git", ["-C", root, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+
+/**
+ * KJC-TSK-0886: el sello de que kj emite un veredicto. En un arbol enlazado la
+ * version no basta (el mismo package.json vale para dos estados del disco), asi
+ * que lleva rama y commit del working tree. Nunca lanza: adorna, no decide.
+ */
+export function kjStamp({ provenance = kjProvenance(), git = gitIn(provenance.root) } = {}) {
+  const stamp = { version: provenance.version, linked: provenance.linked };
+  if (!provenance.linked) return stamp;
+  try {
+    return { ...stamp, branch: git(["rev-parse", "--abbrev-ref", "HEAD"]).trim(), commit: git(["rev-parse", "HEAD"]).trim() };
+  } catch {
+    return stamp;
+  }
+}
+
+const STAMP_KEYS = ["version", "linked", "branch", "commit"];
+export const stampDiffers = (a, b) => Boolean(a && b) && STAMP_KEYS.some((k) => a[k] !== b[k]);
+
+export function stampLabel(s) {
+  const where = s.branch ? ` (${s.branch}@${(s.commit || "").slice(0, 7)})` : "";
+  return `kj ${s.version ?? "unknown"}${where}`;
+}

package/src/review/tests-with-code.js

@@ -42,8 +42,11 @@ export function checkTestsWithCode({ config = {}, stagedFiles = [], numstat = nu
   // cleanup PRs). Callers that only know names keep the old behavior.
   if (Array.isArray(numstat)) {
     const bySource = numstat.filter((n) => sources.includes(n.file));
-    if (bySource.length === sources.length && bySource.every((n) => (n.added || 0) === 0)) {
-      return { ok: true, mode: "delete-only", sources, reason: "every touched source only removes lines — deleting is not new behavior" };
+    // KJC-BUG-0235: a cleanup also corrects the comments the deletion left
+    // lying; lines the caller PROVED to be comments carry no behavior either.
+    const cleanup = (n) => (n.added || 0) === 0 || n.commentOnly === true;
+    if (bySource.length === sources.length && bySource.every(cleanup)) {
+      return { ok: true, mode: "delete-only", sources, reason: "every touched source only removes lines or corrects comments — deleting is not new behavior" };
     }
   }
 

package/src/review/verdict-store.js

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

package/src/start/sweep.js

@@ -17,9 +17,10 @@ import { compareHarden } from "../harden/advisory.js";
 import { detectTestFramework } from "../utils/project-detect.js";
 import { detectQmd } from "../utils/qmd-detect.js";
 import {
-  dbPath, openVecStore, projectSlug, countChunks, getLastIndexedCommit,
+  projectSlug, countChunks, getLastIndexedCommit,
 } from "../rag/vec-store.js";
 import { classifyMaturity } from "./maturity.js";
+import { openProjectStore, projectDbPath } from "../rag/project-store.js";
 
 const CODE_EXT = new Set([
   ".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx", ".py", ".go",
@@ -96,8 +97,8 @@ function lastCommitAgeDays(projectDir) {
 /** Read-only RAG index status; null when no index file exists yet. */
 function readRagStatus(projectDir) {
   try {
-    if (!existsSync(dbPath())) return { indexed: false, chunks: 0, lastIndexedCommit: null };
-    const db = openVecStore();
+    if (!existsSync(projectDbPath(projectDir))) return { indexed: false, chunks: 0, lastIndexedCommit: null };
+    const db = openProjectStore({ projectDir });
     return {
       indexed: true,
       chunks: countChunks(db, { kind: "code" }),

package/src/utils/rulesync.js

@@ -0,0 +1,61 @@
+/**
+ * KJC-TSK-0879 (issue #1310) — Rulesync compatibility.
+ *
+ * A Rulesync-managed repo keeps its agent rules in `.rulesync/rules/` and
+ * `rulesync generate` compiles them into CLAUDE.md, AGENTS.md, .cursor/rules and
+ * the rest, overwriting those files. A block kj writes straight into CLAUDE.md
+ * is erased by the next generate, so in such a repo kj writes into Rulesync's
+ * source instead, with the same managed markers.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export const RULESYNC_RULE = join(".rulesync", "rules", "karajan.md");
+
+// Rulesync's own rule frontmatter: not the root overview, applies to every
+// target and every file.
+const FRONTMATTER = [
+  "---",
+  "root: false",
+  'targets: ["*"]',
+  'description: "Karajan Code: method, guidelines and playbook (managed by kj)"',
+  'globs: ["**/*"]',
+  "---",
+  "",
+].join("\n");
+
+/** The project uses Rulesync when it has `.rulesync/` or `rulesync.jsonc`. */
+export function detectRulesync(projectDir) {
+  return existsSync(join(projectDir, ".rulesync")) || existsSync(join(projectDir, "rulesync.jsonc"));
+}
+
+/** What a brand-new karajan.md starts with, before kj's managed blocks. */
+export const rulesyncRuleSeed = () => FRONTMATTER;
+
+const GENERATE_ARGS = ["generate", "--targets", "*", "--features", "*"];
+const defaultRun = (cmd, args, cwd) => execFileSync(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"], encoding: "utf8" });
+
+/**
+ * Compile kj's rules out to every agent, only when the project declared
+ * `rulesync.generate: true`: kj does not run someone else's compiler on its
+ * own. And never a package fetched on the fly: the local binary, or
+ * `npx --no-install`. A failure is said out loud and does not break the install.
+ */
+export function maybeRulesyncGenerate({ projectDir, config, logger = console, run = defaultRun }) {
+  if (!detectRulesync(projectDir)) return { ran: false, reason: "no-rulesync" };
+  if (config?.rulesync?.generate !== true) {
+    logger.info?.(`kj: its rules are in ${RULESYNC_RULE}; run rulesync generate to reach your agents, or declare rulesync.generate: true`);
+    return { ran: false, reason: "not-opted-in" };
+  }
+  const local = join(projectDir, "node_modules", ".bin", "rulesync");
+  const [cmd, args] = existsSync(local) ? [local, GENERATE_ARGS] : ["npx", ["--no-install", "rulesync", ...GENERATE_ARGS]];
+  try {
+    run(cmd, args, projectDir);
+    logger.info?.("kj: rulesync generate spread kj's rules to every agent");
+    return { ran: true };
+  } catch (err) {
+    logger.warn?.(`kj: rulesync generate failed (${err.message}); kj's rules are in ${RULESYNC_RULE}, run it yourself`);
+    return { ran: false, reason: "failed" };
+  }
+}