karajan-code 4.70.4 → 5.0.0

package/src/prompts/card-context.js

@@ -12,7 +12,7 @@
  * and says so: the coder learns the card exists and where to ask for it,
  * instead of receiving a silently empty context.
  */
-import { getHu } from "../hu/store.js";
+import { findBoardHu } from "../hu/board-lookup.js";
 
 /** Ids minted by the HU Board; anything else belongs to an external board. */
 const LOCAL_HU = /^HU-/i;
@@ -25,9 +25,14 @@ const externalSection = (ref) =>
     "Treat the task below as the card's statement, and if something the card should answer is missing, ASK instead of guessing.",
   ].join("\n");
 
+// KJC-BUG-0454: a board card keeps its criteria as a list; older HUs as one string.
+const criteriaOf = (hu) => (Array.isArray(hu.acceptance_criteria) ? hu.acceptance_criteria.join("\n") : hu.acceptanceCriteria ?? "").trim();
+const idOf = (hu) => hu.short_id || hu.id;
+
 const localSection = (hu) => {
-  const lines = [`## Card ${hu.id} — ${hu.title}`, ""];
+  const lines = [`## Card ${idOf(hu)} — ${hu.title}`, ""];
   if (hu.description?.trim()) lines.push(hu.description.trim(), "");
+  if (hu.scope?.trim()) lines.push(`Scope: ${hu.scope.trim()}`, "");
   lines.push(`Status on the board: ${hu.status}. The card is the contract: done means its statement is literally true.`);
   return lines.join("\n");
 };
@@ -45,10 +50,10 @@ export async function resolveCardContext({ projectDir, ref, deps = {} }) {
   }
   // A missing local HU is an error, never an empty context: the caller asked
   // for a card by id and kj either delivers it or says it does not exist.
-  const hu = await (deps.getHu || getHu)(projectDir, id);
-  const criteria = hu.acceptanceCriteria?.trim();
+  const hu = await (deps.getHu || findBoardHu)(projectDir, id);
+  const criteria = criteriaOf(hu);
   return {
-    huId: hu.id,
+    huId: idOf(hu),
     title: hu.title,
     section: localSection(hu),
     acceptanceTests: criteria ? [{ type: "gherkin", content: criteria }] : null,

package/src/prompts/reviewer.js

@@ -35,7 +35,7 @@ const SERENA_INSTRUCTIONS = [
  * on it; the per-review content (task context + git diff, up to 12 KB
  * and always different) goes last.
  */
-export async function buildReviewerPromptLayout({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null }) {
+export async function buildReviewerPromptLayout({ task, diff, reviewRules, mode, serenaEnabled = false, rtkAvailable = false, productContext = null, domainContext = null, projectDir = null, language = "en", provider = null, roleSkillBlock = null }) {
   const { body: clippedDiff, note: clipNote } = clipDiff(diff);
   // KJC-BUG-0138: full diff on purpose — the moved-to side survives clipping.
   const splitSignal = buildSplitSignal(diff);
@@ -44,7 +44,10 @@ export async function buildReviewerPromptLayout({ task, diff, reviewRules, mode,
   const rtkSnippet = buildRtkInstructions({ rtkAvailable });
   // KJC-TSK-1065: the reviewer gets the skills of its role and of the task, up to 3.
   let skillSection = null;
-  if (projectDir) {
+  // KJC-TSK-1272: a block the caller resolved (a third-party repo's stack) wins over the project's.
+  if (roleSkillBlock) {
+    skillSection = buildRoleSkillSection(roleSkillBlock, { provider }) || null;
+  } else if (projectDir) {
     skillSection = buildRoleSkillSection(await roleSkills({ role: "reviewer", task, projectDir }), { provider }) || null;
   }
 

package/src/rag/auto-update.js

@@ -31,6 +31,57 @@ const countSources = (db, slug, projectDir) => {
 export const DEFAULT_MAX_DRIFT_FILES = 25;
 const HOOK_SRC = resolve(fileURLToPath(import.meta.url), "../../../scripts/git-hooks/post-merge");
 
+// KJC-TSK-1174 (RAG-A2): no index yet. It is built in the background, once; the session
+// does not wait. A recent attempt that died (no Ollama) is not retried blindly.
+function bootstrapInBackground({ projectDir, slug, head, logger }) {
+  const boot = startBootstrap(projectDir);
+  if (boot.busy) {
+    warnOnce(logger, `bootstrap-busy:${projectDir}`, `[rag] ${slug} has no index yet: another background index is running (${boot.busy.slug ?? "?"}, pid ${boot.busy.pid ?? "?"}); it is tried again on the next command`);
+    return { skipped: true, reason: "bootstrap-queued", holder: boot.busy, head };
+  }
+  if (boot.recent) {
+    warnOnce(logger, `bootstrap:${projectDir}`, `[rag] ${slug} has no index and the background indexing did not finish: run kj rag index --with-sources`);
+    return { skipped: true, reason: "bootstrap-failed", head };
+  }
+  warnOnce(logger, `bootstrap:${projectDir}`, `[rag] ${slug} has no index yet: indexing it in the background (pid ${boot.pid}); queries answer from it once it is done`);
+  return { skipped: true, reason: "bootstrapping", pid: boot.pid, head };
+}
+
+// KJC-TSK-1171 (RAG-B): an index built before the embedded header holds vectors a
+// query by file or symbol name cannot reach. Small, it is rebuilt here; large, the
+// query answers from it and says once how to rebuild.
+async function rebuildOldSchema({ db, slug, projectDir, config, logger, head, maxFiles }, schema) {
+  const sources = countSources(db, slug, projectDir);
+  if (sources > maxFiles) {
+    warnOnce(logger, projectDir, `[rag] the index of ${slug} predates the embedded header (schema ${schema} < ${EMBED_SCHEMA}): answering from it as it is; rebuild it with kj rag index --with-sources`);
+    return { skipped: true, reason: "embed-schema-old", sources, head };
+  }
+  logger.info?.(`[rag] the index of ${slug} predates the embedded header (schema ${schema} < ${EMBED_SCHEMA}); rebuilding ${sources} source(s)`);
+  const totals = await indexProject(projectDir, { db, embedder: makeGovernedEmbedder(config), karajanHome: getKarajanHome(), logger, withSources: true, exclude: ragExclude(config) });
+  if (totals.head) setLastIndexedCommit(db, slug, totals.head);
+  return { ran: true, rebuilt: true, totals };
+}
+
+// KJC-TSK-1174 (RAG-A1): the drift is measured up to the files on disk, untracked ones
+// included, so a query sees what the session is writing before it is committed.
+// The dirty paths of the last refresh count too: reverted or deleted since, they hold stale chunks.
+async function deltaUpdate({ db, slug, projectDir, config, logger, head, maxFiles }, since) {
+  const { stdout } = await execa("git", ["-C", projectDir, "diff", "--name-only", "-z", since]);
+  const dirty = [...stdout.split("\0").filter(Boolean), ...(await untrackedFiles(projectDir))];
+  const reconcile = readRefreshedPaths(projectDir).filter((p) => !dirty.includes(p));
+  const changed = dirty.length + reconcile.length;
+  if (changed === 0) return { skipped: true, head };
+  if (changed > maxFiles) {
+    logger.warn?.(`[rag] ${changed} file(s) changed since the last index (more than ${maxFiles}): answering from the index as it is; bring it up to date with kj rag index --since auto`);
+    return { skipped: true, reason: "drift-too-large", changed, head };
+  }
+  logger.info?.(`[rag] drift detected (${since.slice(0, 7)} → ${head.slice(0, 7)}, ${changed} file(s)); running delta update`);
+  const totals = await indexProjectDelta(projectDir, { db, embedder: makeGovernedEmbedder(config), since, logger, exclude: ragExclude(config), worktree: true, reconcile });
+  if (totals.head) setLastIndexedCommit(db, slug, totals.head);
+  writeRefreshedPaths(projectDir, dirty);
+  return { ran: true, totals };
+}
+
 export async function maybeAutoUpdate({ projectDir, config, logger = console, flags = {} } = {}) {
   // commander turns `--no-rag-update` into flags.ragUpdate === false.
   if (flags?.ragUpdate === false || config?.rag?.autoUpdate?.onRun === false) return { skipped: true };
@@ -42,53 +93,15 @@ export async function maybeAutoUpdate({ projectDir, config, logger = console, fl
   const db = openProjectStore({ projectDir, dim: config?.rag?.embedder?.dim || 768 });
   try {
     const since = getLastIndexedCommit(db, slug);
-    if (!since) {
-      // KJC-TSK-1174 (RAG-A2): no index yet. It is built in the background, once; the session
-      // does not wait. A recent attempt that died (no Ollama) is not retried blindly.
-      const boot = startBootstrap(projectDir);
-      if (boot.recent) {
-        warnOnce(logger, `bootstrap:${projectDir}`, `[rag] ${slug} has no index and the background indexing did not finish: run kj rag index --with-sources`);
-        return { skipped: true, reason: "bootstrap-failed", head };
-      }
-      warnOnce(logger, `bootstrap:${projectDir}`, `[rag] ${slug} has no index yet: indexing it in the background (pid ${boot.pid}); queries answer from it once it is done`);
-      return { skipped: true, reason: "bootstrapping", pid: boot.pid, head };
-    }
+    if (!since) return bootstrapInBackground({ projectDir, slug, head, logger });
     // KJC-BUG-0304: a drift of hundreds of files (an index weeks old) reindexed the
     // repo for half an hour before the query answered. Past the bound the query
     // answers from the index as it is, and says how to bring it up to date.
-    const maxFiles = config?.rag?.autoUpdate?.maxFiles ?? DEFAULT_MAX_DRIFT_FILES;
-    // KJC-TSK-1171 (RAG-B): an index built before the embedded header holds vectors a
-    // query by file or symbol name cannot reach. Small, it is rebuilt here; large, the
-    // query answers from it and says once how to rebuild.
+    const ctx = { db, slug, projectDir, config, logger, head, maxFiles: config?.rag?.autoUpdate?.maxFiles ?? DEFAULT_MAX_DRIFT_FILES };
     const schema = readEmbedSchema(projectDir);
-    if (schema < EMBED_SCHEMA) {
-      const sources = countSources(db, slug, projectDir);
-      if (sources > maxFiles) {
-        warnOnce(logger, projectDir, `[rag] the index of ${slug} predates the embedded header (schema ${schema} < ${EMBED_SCHEMA}): answering from it as it is; rebuild it with kj rag index --with-sources`);
-        return { skipped: true, reason: "embed-schema-old", sources, head };
-      }
-      logger.info?.(`[rag] the index of ${slug} predates the embedded header (schema ${schema} < ${EMBED_SCHEMA}); rebuilding ${sources} source(s)`);
-      const totals = await indexProject(projectDir, { db, embedder: makeGovernedEmbedder(config), karajanHome: getKarajanHome(), logger, withSources: true, exclude: ragExclude(config) });
-      if (totals.head) setLastIndexedCommit(db, slug, totals.head);
-      return { ran: true, rebuilt: true, totals };
-    }
-    // KJC-TSK-1174 (RAG-A1): the drift is measured up to the files on disk, untracked ones
-    // included, so a query sees what the session is writing before it is committed.
-    // The dirty paths of the last refresh count too: reverted or deleted since, they hold stale chunks.
-    const { stdout } = await execa("git", ["-C", projectDir, "diff", "--name-only", "-z", since]);
-    const dirty = [...stdout.split("\0").filter(Boolean), ...(await untrackedFiles(projectDir))];
-    const reconcile = readRefreshedPaths(projectDir).filter((p) => !dirty.includes(p));
-    const changed = dirty.length + reconcile.length;
-    if (changed === 0) return { skipped: true, head };
-    if (changed > maxFiles) {
-      logger.warn?.(`[rag] ${changed} file(s) changed since the last index (more than ${maxFiles}): answering from the index as it is; bring it up to date with kj rag index --since auto`);
-      return { skipped: true, reason: "drift-too-large", changed, head };
-    }
-    logger.info?.(`[rag] drift detected (${since.slice(0, 7)} → ${head.slice(0, 7)}, ${changed} file(s)); running delta update`);
-    const totals = await indexProjectDelta(projectDir, { db, embedder: makeGovernedEmbedder(config), since, logger, exclude: ragExclude(config), worktree: true, reconcile });
-    if (totals.head) setLastIndexedCommit(db, slug, totals.head);
-    writeRefreshedPaths(projectDir, dirty);
-    return { ran: true, totals };
+    // Awaited here, inside the try: the catch must see their errors and the finally must not close the store under them.
+    if (schema < EMBED_SCHEMA) return await rebuildOldSchema(ctx, schema);
+    return await deltaUpdate(ctx, since);
   } catch (err) {
     // Said once per process: an embedder that is down would repeat it on every query otherwise.
     warnOnce(logger, `failed:${projectDir}`, `[rag] auto-update failed (${err.message}); continuing without refresh`);

package/src/rag/bootstrap-index.js

@@ -1,52 +1,28 @@
 // KJC-TSK-1174 (RAG-A2): a project with no index gets one in the background, once, at the first
 // command that needs it. The session goes on; queries answer from the index when it is done.
 import { spawn } from "node:child_process";
-import { mkdirSync, readFileSync, renameSync, rmdirSync, statSync, writeFileSync } from "node:fs";
+import { mkdirSync, rmdirSync, unlinkSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { projectDbPath } from "./project-store.js";
+import { projectSlug } from "./vec-store.js";
+import { GRACE_MS, MAX_RUN_MS, indexLeasePath, readLease, takeLock, unlessGone, withMutex, writeLease } from "./pid-lease.js";
 
 const KJ_BIN = resolve(fileURLToPath(import.meta.url), "../../../bin/kj.js");
 // An attempt that died (no Ollama, no model) is not repeated on every command: this long apart.
 export const RETRY_MS = 10 * 60 * 1000;
-// A marker that does not parse, or a lock, older than this was left by a crashed command: taken over.
-export const GRACE_MS = 30 * 1000;
-// An indexer is not trusted to run longer than this: past it, its pid may belong to someone else.
-export const MAX_RUN_MS = 60 * 60 * 1000;
+export { GRACE_MS, MAX_RUN_MS };
 const markerPath = (projectDir) => `${projectDbPath(projectDir)}.bootstrap`;
 
-const alive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };
-
 /** What the marker says of the last attempt: `{ pid, at, running }`, or null when none was ever made. */
-const unlessGone = (fn) => {
-  try { return fn(); }
-  catch (err) {
-    if (err.code === "ENOENT") { return null; }
-    throw err;
-  }
-};
-
-export function readBootstrap(projectDir, { now = Date.now() } = {}) {
-  const file = markerPath(projectDir);
-  // Read first, never check-then-read: another command may set the marker aside in between.
-  const raw = unlessGone(() => readFileSync(file, "utf8"));
-  if (raw === null) return null;
-  try {
-    const note = JSON.parse(raw);
-    return { ...note, running: alive(note.pid) && now - note.at < MAX_RUN_MS };
-  } catch {
-    // Another command is writing it this very moment: running for a moment; past the grace, a crash.
-    const stat = unlessGone(() => statSync(file));
-    return stat === null ? null : { pid: null, at: 0, running: now - stat.mtimeMs < GRACE_MS };
-  }
-}
+export const readBootstrap = (projectDir, o) => readLease(markerPath(projectDir), o);
 
 /**
  * Starts `kj rag index --with-sources` detached, or reuses the one running. Returns
  * `{ started, pid }`, or `{ started: false, recent: true }` when the last attempt died less
  * than RETRY_MS ago: the index is then asked for by hand instead of being retried blindly.
  */
-export function startBootstrap(projectDir, { spawnFn = spawn, bin = KJ_BIN, now = Date.now() } = {}) {
+export function startBootstrap(projectDir, { spawnFn = spawn, bin = KJ_BIN, now = Date.now(), lease = indexLeasePath() } = {}) {
   const file = markerPath(projectDir);
   mkdirSync(dirname(file), { recursive: true });
   // One claimant at a time: the lock directory is created atomically, so of two commands arriving
@@ -58,29 +34,27 @@ export function startBootstrap(projectDir, { spawnFn = spawn, bin = KJ_BIN, now
     const last = readBootstrap(projectDir, { now });
     if (last?.running) return { started: false, pid: last.pid };
     if (last && now - last.at < RETRY_MS) return { started: false, recent: true, pid: null };
-    // The marker lands whole each time (written apart, then renamed): first with the claimant's
-    // pid, so it reads as running meanwhile, then with the indexer's.
-    const note = (pid) => { const tmp = `${file}.${process.pid}.tmp`; writeFileSync(tmp, JSON.stringify({ pid, at: now }), "utf8"); renameSync(tmp, file); };
-    note(process.pid);
-    const child = spawnFn(process.execPath, [bin, "rag", "index", "--with-sources"], { cwd: projectDir, detached: true, stdio: "ignore" });
-    child.unref?.();
-    note(child.pid);
-    return { started: true, pid: child.pid };
+    // One indexer per machine: the lease is taken inside the project mutex, before the marker is
+    // written, so a queued project does not spend its RETRY_MS. Both mutexes yield, never wait.
+    const slug = projectSlug(projectDir);
+    const res = withMutex(lease, now, () => {
+      const holder = readLease(lease, { now });
+      if (holder?.running && holder.pid !== process.pid) return { started: false, busy: { projectDir: holder.projectDir, slug: holder.slug, pid: holder.pid } };
+      // Marker and lease land whole each time: first with the claimant's pid, so they read as
+      // running meanwhile, then with the indexer's.
+      const note = (pid) => { writeLease(file, { pid, at: now }); writeLease(lease, { pid, at: now, projectDir, slug }); };
+      note(process.pid);
+      try {
+        const child = spawnFn(process.execPath, [bin, "rag", "index", "--with-sources"], { cwd: projectDir, detached: true, stdio: "ignore" });
+        child.unref?.();
+        note(child.pid);
+        return { started: true, pid: child.pid };
+      } catch (err) {
+        // No indexer exists: neither the marker nor the lease may keep naming this (maybe long-lived) process.
+        unlessGone(() => unlinkSync(file)); unlessGone(() => unlinkSync(lease));
+        throw err;
+      }
+    });
+    return res.busy === true ? { started: false, busy: {} } : res;
   } finally { unlessGone(() => rmdirSync(lock)); }
 }
-
-const takeLock = (lock, now) => {
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    try { mkdirSync(lock); return true; }
-    catch (err) {
-      if (err.code !== "EEXIST") throw err;
-      const held = unlessGone(() => statSync(lock));
-      if (held && now - held.mtimeMs < GRACE_MS) return false;
-      // The holder crashed. The lock is set aside under a unique name first: only the one caller
-      // whose rename succeeds removes it, so nobody removes a lock another caller has just taken.
-      const aside = `${lock}.${process.pid}.${now}.stale`;
-      if (unlessGone(() => renameSync(lock, aside)) !== null) rmdirSync(aside);
-    }
-  }
-  return false;
-};

package/src/rag/migrate.js

@@ -10,7 +10,7 @@ import { existsSync } from "node:fs";
 import { sep } from "node:path";
 
 import { insertChunk, getLastIndexedCommit, setLastIndexedCommit } from "./vec-store.js";
-import { openVecStoreExplained as openVecStore } from "./project-store.js";
+import { openVecStore } from "./vec-store.js";
 
 export const countProjectChunks = (db, slug) => db.prepare("SELECT COUNT(*) AS n FROM chunks WHERE project_slug = ?").get(slug).n;
 

package/src/rag/onnx-fallback.js

@@ -9,7 +9,7 @@
 import fs from "node:fs/promises";
 import { existsSync, rmSync } from "node:fs";
 import path from "node:path";
-import Database from "better-sqlite3";
+import { openDatabase } from "karajan-core/db";
 import { parseDocument } from "yaml";
 import { getProjectConfigPath } from "../config/loader.js";
 import { projectDbPath } from "./project-store.js";
@@ -31,7 +31,7 @@ export function resetEmptyStore(projectDir = process.cwd()) {
   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.
-  const db = new Database(storePath, { readonly: true });
+  const db = openDatabase(storePath, { readOnly: true });
   try {
     const hasChunksTable = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='chunks'").get();
     if (hasChunksTable && db.prepare("SELECT COUNT(*) AS n FROM chunks").get().n > 0) return false;

package/src/rag/pid-lease.js

@@ -0,0 +1,70 @@
+// HU-2757: a lease names the pid that holds a resource and when it took it. Nobody releases it:
+// a dead pid, or an age of MAX_RUN_MS, means free. A mkdir mutex makes the decision atomic.
+import { mkdirSync, readFileSync, renameSync, rmdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { getKarajanHome } from "../utils/paths.js";
+
+// A lease that does not parse, or a lock, older than this was left by a crashed command: taken over.
+export const GRACE_MS = 30 * 1000;
+// An indexer is not trusted to run longer than this: past it, its pid may belong to someone else.
+export const MAX_RUN_MS = 60 * 60 * 1000;
+
+export const indexLeasePath = () => join(getKarajanHome(), "locks", "rag-index.json");
+
+// EPERM (a pid of another user) counts as dead: a single-user machine has no such indexer.
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch { return false; } };
+
+export const unlessGone = (fn) => {
+  try { return fn(); }
+  catch (err) {
+    if (err.code === "ENOENT") { return null; }
+    throw err;
+  }
+};
+
+/** What the lease says: `{ pid, at, running, ... }`, or null when none was ever written. */
+export function readLease(file, { now = Date.now() } = {}) {
+  // Read first, never check-then-read: another command may set the file aside in between.
+  const raw = unlessGone(() => readFileSync(file, "utf8"));
+  if (raw === null) return null;
+  try {
+    const note = JSON.parse(raw);
+    return { ...note, running: alive(note.pid) && now - note.at < MAX_RUN_MS };
+  } catch {
+    // Another command is writing it this very moment: running for a moment; past the grace, a crash.
+    const stat = unlessGone(() => statSync(file));
+    return stat === null ? null : { pid: null, at: 0, running: now - stat.mtimeMs < GRACE_MS };
+  }
+}
+
+/** The lease lands whole: written apart, then renamed. */
+export function writeLease(file, record) {
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(record), "utf8");
+  renameSync(tmp, file);
+}
+
+export const takeLock = (lock, now) => {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try { mkdirSync(lock); return true; }
+    catch (err) {
+      if (err.code !== "EEXIST") throw err;
+      const held = unlessGone(() => statSync(lock));
+      if (held && now - held.mtimeMs < GRACE_MS) return false;
+      // The holder crashed. The lock is set aside under a unique name first: only the one caller
+      // whose rename succeeds removes it, so nobody removes a lock another caller has just taken.
+      const aside = `${lock}.${process.pid}.${now}.stale`;
+      if (unlessGone(() => renameSync(lock, aside)) !== null) rmdirSync(aside);
+    }
+  }
+  return false;
+};
+
+/** Runs `fn` under the mutex `${file}.lock`, or returns `{ busy: true }` when another command holds it. */
+export function withMutex(file, now, fn) {
+  const lock = `${file}.lock`;
+  mkdirSync(dirname(lock), { recursive: true });
+  if (!takeLock(lock, now)) return { busy: true };
+  try { return fn(); } finally { unlessGone(() => rmdirSync(lock)); }
+}

package/src/rag/project-store.js

@@ -17,7 +17,6 @@ import { execFileSync } from "node:child_process";
 import path from "node:path";
 
 import { openVecStore } from "./vec-store.js";
-import { explainNativeLoadError } from "../checks/native-build.js";
 import { getKarajanHome } from "../utils/paths.js";
 
 function projectRoot(dir) {
@@ -40,20 +39,11 @@ export function libraryDbPath() {
   return process.env.KJ_LIBRARY_DB || path.join(getKarajanHome(), "library.db");
 }
 
-// KJC-BUG-0426: an unbuilt better-sqlite3 addon says how to build it, not "bindings file".
-// Every opening of a RAG store goes through here.
-export function openVecStoreExplained(opts) {
-  try {
-    return openVecStore(opts);
-  } catch (err) {
-    throw explainNativeLoadError(err);
-  }
-}
 
 export function openLibraryStore({ dim = 768 } = {}) {
-  return openVecStoreExplained({ dim, path: libraryDbPath() });
+  return openVecStore({ dim, path: libraryDbPath() });
 }
 
 export function openProjectStore({ projectDir = process.cwd(), dim = 768 } = {}) {
-  return openVecStoreExplained({ dim, path: projectDbPath(projectDir) });
+  return openVecStore({ dim, path: projectDbPath(projectDir) });
 }

package/src/review/card-first.js

@@ -41,7 +41,8 @@ async function findLiveCardInBranch(projectDir, branch) {
     const plan = await loadPlan(projectDir, meta.planId);
     for (const h of plan.hus || []) {
       // KJC-BUG-0353: an HU is also named by the id of its replica in an external tracker.
-      for (const ref of [h.short_id, h.id, h.external_ref]) {
+      // KJC-BUG-0443: a shared-board HU carries "repo#n · ref"; each part names it.
+      for (const ref of [h.short_id, h.id, ...String(h.external_ref ?? "").split(" · ")]) {
         if (ref && refInBranch(ref, needle)) {
           if (LIVE_STATUSES.has(h.status)) return { ref, live: true, status: h.status };
           closedHit = { ref, live: false, status: h.status };
@@ -52,7 +53,12 @@ async function findLiveCardInBranch(projectDir, branch) {
   return closedHit;
 }
 
-export async function checkCardFirst({ config = {}, projectDir = process.cwd(), branch, deps = {} }) {
+// A failed check under the effective policy: blocks, or passes with a warning.
+const failedCheck = (effective, reason, extra = {}) => (effective === "block"
+  ? { ok: false, mode: "block", reason, ...extra }
+  : { ok: true, mode: "warn", reason, ...extra });
+
+function exemption(config, branch) {
   const exempt = config.method_gates?.card_first_exempt_branches || DEFAULT_EXEMPT_PREFIXES;
   if (exempt.some((p) => branch.startsWith(p))) {
     return { ok: true, mode: "exempt", reason: `branch prefix exempt (${branch.split("/")[0]}/…)` };
@@ -62,59 +68,64 @@ export async function checkCardFirst({ config = {}, projectDir = process.cwd(),
   if ([config.base_branch || "main", "main", "master", "HEAD"].includes(branch)) {
     return { ok: true, mode: "exempt", reason: "base branch — the branch-first gate owns this case" };
   }
+  return null;
+}
 
-  const backend = config.state_backend || "hu-board";
-  const policy = config.method_gates?.card_first || "auto";
+async function huBoardCheck({ projectDir, branch, policy }) {
+  const hit = await findLiveCardInBranch(projectDir, branch);
+  if (hit?.live) return { ok: true, mode: "pass", ref: hit.ref };
+  const reason = hit
+    ? `branch references ${hit.ref} but its card is "${hit.status}" — card-first needs a live card (reopen it or create one: kj hu add)`
+    : `no live card referenced in branch "${branch}" — create it first (kj hu add "…" --id <REF>) and name the branch after it`;
+  return failedCheck(policy === "auto" ? "block" : policy, reason);
+}
 
-  if (backend === "hu-board") {
-    const hit = await findLiveCardInBranch(projectDir, branch);
-    if (hit?.live) return { ok: true, mode: "pass", ref: hit.ref };
-    const effective = policy === "auto" ? "block" : policy;
-    const reason = hit
-      ? `branch references ${hit.ref} but its card is "${hit.status}" — card-first needs a live card (reopen it or create one: kj hu add)`
-      : `no live card referenced in branch "${branch}" — create it first (kj hu add "…" --id <REF>) and name the branch after it`;
-    return effective === "block"
-      ? { ok: false, mode: "block", reason }
-      : { ok: true, mode: "warn", reason };
+// A card-shaped reference in the branch, verified against the tracker when an adapter is declared.
+async function trackerRefCheck({ config, projectDir, branch, deps, boardName, effective }) {
+  const ref = branch.match(CARD_REF_RE)[0];
+  const { verifyFn = verifyCardAlive } = deps;
+  const v = await verifyFn({ ref, verifyCmd: config.board?.verify_cmd, projectDir });
+  if (v.verified === false) {
+    const reason = `branch references ${ref} but ${boardName} reports it "${v.status}" — card-first needs a live card in the tracker (create/reopen it there)`;
+    return failedCheck(effective, reason, { level: v.level });
   }
+  // KJC-TSK-0878 (issue #1371): "no he podido verificar" y "he verificado y
+  // esta mal" no son lo mismo, y ambas pueden merecer una parada. El proyecto
+  // decide si la primera para, y el mensaje dice cual de las dos es: un gate
+  // que aprueba lo que no ha comprobado da una confianza que no ha ganado.
+  // Sin adaptador declarado no hay nada que bloquear: la opcion no castiga a
+  // quien aun no tiene verify_cmd.
+  if (v.verified === null && config.board?.unverifiable === "block" && config.board?.verify_cmd) {
+    return {
+      ok: false, mode: "block", level: v.level,
+      reason: `branch references ${ref} but the card could not be verified against ${boardName} — ${v.note} (board.unverifiable: block refuses to approve a check kj did not make)`,
+    };
+  }
+  const huNote = `no live HU on the HU Board links ${ref}: kj hu add "…" --ref ${ref}`;
+  return { ok: true, mode: "pass", ref, level: v.level, note: v.note ? `${v.note}; ${huNote}` : huNote };
+}
 
-  // planning-game / external: presence check, upgraded to LIVENESS against
-  // the real tracker when board.verify_cmd declares an adapter
-  // (KJC-TSK-0732, issue #1371). Unverifiable degrades honestly — the
-  // result names its level so nobody mistakes branch-ref for tracker.
+// planning-game / external: presence check, upgraded to LIVENESS against
+// the real tracker when board.verify_cmd declares an adapter
+// (KJC-TSK-0732, issue #1371). Unverifiable degrades honestly — the
+// result names its level so nobody mistakes branch-ref for tracker.
+async function externalBoardCheck({ config, projectDir, branch, deps, backend, policy }) {
   const boardName = config.board?.name || backend;
   const effective = policy === "auto" ? "warn" : policy;
   // KJC-BUG-0353: the HU Board is always kj's board (KJC-BUG-0305) — a live HU
   // the branch names, or whose replica it names, is checked here, not guessed.
   const huHit = await findLiveCardInBranch(projectDir, branch);
   if (huHit?.live) return { ok: true, mode: "pass", ref: huHit.ref, level: "hu-board" };
-  if (CARD_REF_RE.test(branch)) {
-    const ref = branch.match(CARD_REF_RE)[0];
-    const { verifyFn = verifyCardAlive } = deps;
-    const v = await verifyFn({ ref, verifyCmd: config.board?.verify_cmd, projectDir });
-    if (v.verified === false) {
-      const reason = `branch references ${ref} but ${boardName} reports it "${v.status}" — card-first needs a live card in the tracker (create/reopen it there)`;
-      return effective === "block"
-        ? { ok: false, mode: "block", reason, level: v.level }
-        : { ok: true, mode: "warn", reason, level: v.level };
-    }
-    // KJC-TSK-0878 (issue #1371): "no he podido verificar" y "he verificado y
-    // esta mal" no son lo mismo, y ambas pueden merecer una parada. El proyecto
-    // decide si la primera para, y el mensaje dice cual de las dos es: un gate
-    // que aprueba lo que no ha comprobado da una confianza que no ha ganado.
-    // Sin adaptador declarado no hay nada que bloquear: la opcion no castiga a
-    // quien aun no tiene verify_cmd.
-    if (v.verified === null && config.board?.unverifiable === "block" && config.board?.verify_cmd) {
-      return {
-        ok: false, mode: "block", level: v.level,
-        reason: `branch references ${ref} but the card could not be verified against ${boardName} — ${v.note} (board.unverifiable: block refuses to approve a check kj did not make)`,
-      };
-    }
-    const huNote = `no live HU on the HU Board links ${ref}: kj hu add "…" --ref ${ref}`;
-    return { ok: true, mode: "pass", ref, level: v.level, note: v.note ? `${v.note}; ${huNote}` : huNote };
-  }
+  if (CARD_REF_RE.test(branch)) return trackerRefCheck({ config, projectDir, branch, deps, boardName, effective });
   const reason = `no card reference in branch "${branch}" — card-first on ${boardName}: create the card there and name the branch after it (e.g. feat/ABC-123-summary)`;
-  return effective === "block"
-    ? { ok: false, mode: "block", reason }
-    : { ok: true, mode: "warn", reason };
+  return failedCheck(effective, reason);
+}
+
+export async function checkCardFirst({ config = {}, projectDir = process.cwd(), branch, deps = {} }) {
+  const exempt = exemption(config, branch);
+  if (exempt) return exempt;
+  const backend = config.state_backend || "hu-board";
+  const policy = config.method_gates?.card_first || "auto";
+  if (backend === "hu-board") return huBoardCheck({ projectDir, branch, policy });
+  return externalBoardCheck({ config, projectDir, branch, deps, backend, policy });
 }

package/src/review/gate-gitignore.js

@@ -46,6 +46,14 @@ export const CONTRACT_BLOCK = [
   "!.karajan/security-level.json",
   // KJC-TSK-1163 (ADR 0025): which HU Board the repo uses; the team shares it.
   "!.karajan/board.yml",
+  // ADR 0032 (KJC-TSK-1231): the team's own state, as the board: the rules the roles
+  // apply and atril's config with its lockfile. Shared plans travel in .karajan-shared/.
+  "!.karajan/coder-rules.md",
+  "!.karajan/review-rules.md",
+  // KJC-TSK-1234: the project config, once the pre-commit refuses it with a secret in it.
+  "!.karajan/kj.config.yml",
+  "!.karajan/atril.json",
+  "!.karajan/atril.lock.json",
 ];
 
 /**
@@ -117,6 +125,8 @@ export async function excludeLocalArtifacts(projectDir, run = runCommand) {
   }
 }
 
+const SHADOWING = new Set(["review-rules.md", "coder-rules.md"]);
+
 export async function ensureGateTrackable(projectDir) {
   const file = path.join(projectDir, ".gitignore");
   let text;
@@ -126,14 +136,22 @@ export async function ensureGateTrackable(projectDir) {
   // a partial state (e.g. a hand-written marker re-include without the hook
   // ones) must still be completed, not silently accepted.
   const reIncludes = CONTRACT_BLOCK.filter((l) => l.startsWith("!"));
-  if (reIncludes.every((l) => text.includes(l))) return { changed: false };
-
   const isRootExclude = (l) => {
     const t = l.trim();
     return t === ".karajan/" || t === ".karajan" || t === ".karajan/*";
   };
   const lines = text.split("\n");
   const idx = lines.findIndex(isRootExclude);
+  // ADR 0032: a bare rules line an older kj wrote after its re-include (or with none) undoes
+  // it, since the last match wins: it goes. One after the root exclude but before its own
+  // re-include was already overridden, so it is kept and moved ahead of the block, where it
+  // stays overridden. Lines before the root exclude are never touched.
+  const placed = (l, i) => {
+    if (idx === -1 || i <= idx || !SHADOWING.has(l.trim())) return "keep";
+    const reInclude = lines.findLastIndex((x) => x.trim() === `!.karajan/${l.trim()}`);
+    return reInclude === -1 || i > reInclude ? "drop" : "move";
+  };
+  if (reIncludes.every((l) => text.includes(l)) && lines.every((l, i) => placed(l, i) === "keep")) return { changed: false };
   if (idx === -1) return { changed: false };
 
   // Drop EVERY .karajan root exclude (a later duplicate would override the
@@ -142,9 +160,10 @@ export async function ensureGateTrackable(projectDir) {
   // position of the first exclude. Exactly one coherent block, idempotent.
   const partials = new Set(CONTRACT_BLOCK);
   const marker = "@@kj-contract-block@@";
+  const moved = lines.filter((l, i) => placed(l, i) === "move");
   const cleaned = lines.map((l, i) => (i === idx ? marker : l))
-    .filter((l) => l === marker || (!isRootExclude(l) && !partials.has(l.trim())));
-  const result = cleaned.flatMap((l) => (l === marker ? CONTRACT_BLOCK : [l]));
+    .filter((l, i) => l === marker || (!isRootExclude(l) && !partials.has(l.trim()) && placed(l, i) === "keep"));
+  const result = cleaned.flatMap((l) => (l === marker ? [...moved, ...CONTRACT_BLOCK] : [l]));
   await fs.writeFile(file, result.join("\n"));
   return { changed: true };
 }