@karajan-family/code 4.21.0

package/src/rag/ollama-manager.js

@@ -0,0 +1,98 @@
+// KJC-TSK-0435 (RAG Auto-Bootstrap PR1) — Ollama-in-Docker manager.
+// Mirrors src/sonar/manager.js: write docker-compose, start/stop the
+// container, discover a free port, wait for readiness. Next PR wires
+// it to `kj init`.
+import fs from "node:fs/promises";
+import net from "node:net";
+import { ensureDir } from "../utils/fs.js";
+import { runCommand } from "../utils/process.js";
+import { getKarajanHome, getOllamaComposePath } from "../utils/paths.js";
+
+const DEFAULTS = { port: 11434, hcS: 5, upMs: 300000, ctrlMs: 120000, readyMs: 90000 };
+const pos = (v, d) => (Number(v) > 0 ? Number(v) : d);
+
+export function normalizeOllamaConfig(ollama = {}) {
+  const t = ollama.timeouts || {};
+  const port = Number(ollama.port) || DEFAULTS.port;
+  return {
+    host: ollama.host || `http://localhost:${port}`,
+    port,
+    external: ollama.external === true,
+    containerName: ollama.container_name || "kj-ollama",
+    volume: ollama.volume || "kj_ollama_data",
+    timeouts: {
+      healthcheckSeconds: pos(t.healthcheck_seconds, DEFAULTS.hcS),
+      composeUpMs: pos(t.compose_up_ms, DEFAULTS.upMs),
+      composeControlMs: pos(t.compose_control_ms, DEFAULTS.ctrlMs),
+      readyMs: pos(t.ready_ms, DEFAULTS.readyMs),
+    },
+  };
+}
+
+export function buildComposeTemplate(cfg) {
+  return `services:
+  ollama:
+    image: ollama/ollama:latest
+    container_name: ${cfg.containerName}
+    ports:
+      - "${cfg.port}:11434"
+    volumes:
+      - ${cfg.volume}:/root/.ollama
+    restart: unless-stopped
+
+volumes:
+  ${cfg.volume}:
+`;
+}
+
+export async function ensureComposeFile(ollama = null) {
+  const cfg = normalizeOllamaConfig(ollama || {});
+  await ensureDir(getKarajanHome());
+  await fs.writeFile(getOllamaComposePath(), buildComposeTemplate(cfg), "utf8");
+  return getOllamaComposePath();
+}
+
+export async function isOllamaReachable(host, healthcheckSeconds = DEFAULTS.hcS) {
+  const t = String(pos(healthcheckSeconds, DEFAULTS.hcS));
+  const r = await runCommand("curl", ["-s", "-o", "/dev/null", "-w", "%{http_code}", "--max-time", t, `${host}/api/tags`]);
+  return r.exitCode === 0 && r.stdout.trim().startsWith("2");
+}
+
+export async function findAvailableOllamaPort(start = DEFAULTS.port, span = 10) {
+  for (let p = start; p < start + span; p++) {
+    const free = await new Promise((res) => {
+      const s = net.createServer();
+      s.once("error", () => res(false));
+      s.once("listening", () => s.close(() => res(true)));
+      s.listen(p, "127.0.0.1");
+    });
+    if (free) return p;
+  }
+  throw new Error(`No free port in [${start}, ${start + span})`);
+}
+
+export async function waitForOllamaReady(host, timeoutMs = DEFAULTS.readyMs) {
+  const dl = Date.now() + timeoutMs;
+  while (Date.now() < dl) {
+    if (await isOllamaReachable(host, 2)) return true;
+    await new Promise((r) => setTimeout(r, 1500));
+  }
+  return false;
+}
+
+export async function ollamaUp(ollama = null) {
+  const cfg = normalizeOllamaConfig(ollama || {});
+  if (await isOllamaReachable(cfg.host, cfg.timeouts.healthcheckSeconds)) {
+    return { exitCode: 0, stdout: `Ollama already reachable at ${cfg.host}, skipping container start.`, stderr: "", reusedHost: cfg.host };
+  }
+  if (cfg.external) return { exitCode: 1, stdout: "", stderr: `Configured external Ollama is not reachable at ${cfg.host}.` };
+  const compose = await ensureComposeFile(ollama);
+  return runCommand("docker", ["compose", "-f", compose, "up", "-d"], { timeout: cfg.timeouts.composeUpMs });
+}
+
+export async function ollamaDown(ollama = null) {
+  const cfg = normalizeOllamaConfig(ollama || {});
+  if (cfg.external) return { exitCode: 0, stdout: "ollama.external=true, skipping Docker stop.", stderr: "" };
+  const compose = await ensureComposeFile(ollama);
+  return runCommand("docker", ["compose", "-f", compose, "stop"], { timeout: cfg.timeouts.composeControlMs });
+}

package/src/rag/onnx-fallback.js

@@ -0,0 +1,69 @@
+/**
+ * ONNX embedder fallback (KJC-TSK-0683) — limited machines where installing
+ * Ollama/Docker is not viable still get a working RAG: the built-in ONNX
+ * embedder (all-MiniLM via @huggingface/transformers, in-process, CPU).
+ * The choice is PERSISTED in the project config: onnx (384) and ollama
+ * (768) have different vector dims, so the election must be sticky —
+ * an index can never be written by one and queried by the other.
+ */
+import fs from "node:fs/promises";
+import { existsSync, rmSync } from "node:fs";
+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";
+
+const ONNX_EMBEDDER = { provider: "onnx", dim: 384 };
+
+/**
+ * KJC-BUG-0128: the hasRagIndex probe could leave behind an EMPTY store
+ * whose vec table was created at the default dim (768) — ONNX inserts (384)
+ * then failed on every chunk. Before the fallback indexes, delete an empty
+ * store (plus WAL siblings) so it is recreated at the right dim. A store
+ * that already HAS chunks is never touched — switching dims there would
+ * destroy other projects' indexes.
+ */
+export function resetEmptyStore() {
+  const storePath = dbPath();
+  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 });
+  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;
+  } finally {
+    db.close();
+  }
+  for (const suffix of ["", "-wal", "-shm"]) rmSync(storePath + suffix, { force: true });
+  return true;
+}
+
+/** The same config, with the embedder swapped to the built-in ONNX. */
+export function onnxConfig(config) {
+  return {
+    ...config,
+    rag: { ...(config?.rag || {}), embedder: { ...(config?.rag?.embedder || {}), ...ONNX_EMBEDDER } },
+  };
+}
+
+/**
+ * Persist the ONNX election in the PROJECT config file. Surgical edit via
+ * the yaml Document API: only rag.embedder.{provider,dim} change — the
+ * user's comments, ordering and every other key survive untouched.
+ */
+export async function persistOnnxChoice(projectDir) {
+  const configPath = getProjectConfigPath(projectDir);
+  let source = "";
+  try {
+    source = await fs.readFile(configPath, "utf8");
+  } catch { /* no project config yet — create it */ }
+  const doc = parseDocument(source || "{}");
+  for (const [key, value] of Object.entries(ONNX_EMBEDDER)) {
+    doc.setIn(["rag", "embedder", key], value);
+  }
+  await fs.mkdir(path.dirname(configPath), { recursive: true });
+  await fs.writeFile(configPath, doc.toString(), "utf8");
+  return configPath;
+}

package/src/rag/rerank.js

@@ -0,0 +1,4 @@
+// Shim: rerank now lives in karajan-core/rag so the hu-board workspace
+// can consume it without a relative dep on the CLI src tree.
+// KJC-TSK-0632 PR2.
+export { RerankError, _resetPipeline, rerank } from "karajan-core/rag/rerank";

package/src/rag/retriever.js

@@ -0,0 +1,2 @@
+// Shim: retriever now lives in karajan-core/rag (KJC-TSK-0632 PR3).
+export * from "karajan-core/rag/retriever";

package/src/rag/vec-store.js

@@ -0,0 +1,17 @@
+// Shim: vec-store primitives now live in karajan-core/vec-store so
+// the hu-board workspace can consume them without a relative dep on the
+// CLI src tree. KJC-TSK-0511 PR4.
+export {
+  dbPath,
+  openVecStore,
+  insertChunk,
+  searchSimilar,
+  projectSlug,
+  deleteChunksBySource,
+  getLastIndexedCommit,
+  setLastIndexedCommit,
+  getEmbeddingsByIds,
+  findChunkByHash,
+  countChunks,
+  searchBM25,
+} from "karajan-core/vec-store";

package/src/rag/watcher.js

@@ -0,0 +1,62 @@
+// 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 chokidar from "chokidar";
+import { openVecStore, deleteChunksBySource, projectSlug } from "./vec-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");
+const DEFAULT_DEBOUNCE_MS = 1000;
+const SKIP_SEGMENTS = new Set(["node_modules", ".git", "dist", "build", "coverage", ".karajan", ".next", ".kj", "_diet"]);
+const SOURCE_EXTS = new Set(getAllCodeExtensions().map((e) => e.toLowerCase()));
+
+export function isWatchable(path) {
+  if (path.includes("/.karajan/onboarding/")) return /\.md$/.test(path);
+  if (path.includes("/.karajan/plans/")) return /\.json$/.test(path);
+  if (path.split("/").some((seg) => SKIP_SEGMENTS.has(seg))) return false;
+  return SOURCE_EXTS.has(extname(path).toLowerCase());
+}
+
+export function startWatcher({ projectDir, config, logger = console, debounceMs = DEFAULT_DEBOUNCE_MS, withSources = false } = {}) {
+  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 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 pending = new Map();
+  const flush = async (p) => {
+    pending.delete(p);
+    if (!existsSync(p)) { deleteChunksBySource(db, p); logger.info?.(`[rag-watcher] removed → ${p}`); return; }
+    if (!isWatchable(p)) return;
+    try { const r = await indexFile(p, { db, embedder, logger, project: slug }); logger.info?.(`[rag-watcher] reindexed ${p} → ${r.indexed} chunk(s)`); }
+    catch (err) { logger.warn?.(`[rag-watcher] reindex failed for ${p}: ${err.message}`); }
+  };
+  const schedule = (p) => { if (pending.has(p)) clearTimeout(pending.get(p)); pending.set(p, setTimeout(() => flush(p), debounceMs)); };
+  watcher.on("add", schedule).on("change", schedule).on("unlink", schedule).on("error", (err) => logger.warn?.(`[rag-watcher] ${err.message}`));
+  return async function stop() {
+    for (const t of pending.values()) clearTimeout(t);
+    pending.clear();
+    await watcher.close();
+    try { db.close(); } catch { /* already closed */ }
+  };
+}
+
+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());
+  return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+export function isPidAlive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}

package/src/rag/where-parser.js

@@ -0,0 +1,4 @@
+// Shim: where-parser now lives in karajan-core/rag so the hu-board
+// workspace can consume it without a relative dep on the CLI src tree.
+// KJC-TSK-0632 PR2.
+export { parseWhere, buildWhereSql } from "karajan-core/rag/where-parser";

package/src/repeat-detector.js

@@ -0,0 +1,88 @@
+import { createHash } from "node:crypto";
+
+const DEFAULT_THRESHOLD = 2;
+
+function normalizeIssueKey(value) {
+  if (value === null || value === undefined) return "";
+  return String(value).trim();
+}
+
+function buildIssueSignature(issues, keySelector) {
+  const counts = new Map();
+  for (const issue of issues || []) {
+    const key = normalizeIssueKey(keySelector(issue));
+    if (!key) continue;
+    counts.set(key, (counts.get(key) || 0) + 1);
+  }
+  if (counts.size === 0) return "";
+  return Array.from(counts.entries())
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([key, count]) => `${key}:${count}`)
+    .join("|");
+}
+
+function hashSignature(signature) {
+  if (!signature) return "";
+  return createHash("sha256").update(signature).digest("hex");
+}
+
+function updateRepeatState(state, signatureHash) {
+  if (!signatureHash) {
+    return { lastHash: null, repeatCount: 0 };
+  }
+  const nextCount = signatureHash === state.lastHash ? state.repeatCount + 1 : 1;
+  return { lastHash: signatureHash, repeatCount: nextCount };
+}
+
+function parseThreshold(value) {
+  const parsed = Number(value);
+  if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  return DEFAULT_THRESHOLD;
+}
+
+export function getRepeatThreshold(config) {
+  const raw =
+    config?.failFast?.repeatThreshold ??
+    config?.session?.repeat_detection_threshold ??
+    config?.session?.fail_fast_repeats ??
+    2;
+  const value = Number(raw);
+  if (Number.isFinite(value) && value > 0) return value;
+  return 2;
+}
+
+export class RepeatDetector {
+  constructor({ threshold = DEFAULT_THRESHOLD } = {}) {
+    this.threshold = parseThreshold(threshold);
+    this.sonar = { lastHash: null, repeatCount: 0 };
+    this.reviewer = { lastHash: null, repeatCount: 0 };
+  }
+
+  addIteration(sonarIssues, reviewerIssues) {
+    const sonarSignature = buildIssueSignature(
+      sonarIssues || [],
+      (issue) => issue?.rule || issue?.message
+    );
+    const reviewerSignature = buildIssueSignature(
+      reviewerIssues || [],
+      (issue) => issue?.description || issue?.content || issue?.id
+    );
+
+    this.sonar = updateRepeatState(this.sonar, hashSignature(sonarSignature));
+    this.reviewer = updateRepeatState(this.reviewer, hashSignature(reviewerSignature));
+  }
+
+  isStalled() {
+    if (this.sonar.repeatCount >= this.threshold) {
+      return { stalled: true, reason: "sonar_repeat" };
+    }
+    if (this.reviewer.repeatCount >= this.threshold) {
+      return { stalled: true, reason: "reviewer_repeat" };
+    }
+    return { stalled: false, reason: "" };
+  }
+
+  getRepeatCounts() {
+    return { sonar: this.sonar.repeatCount, reviewer: this.reviewer.repeatCount };
+  }
+}

package/src/review/card-first.js

@@ -0,0 +1,99 @@
+/**
+ * Card-first gate (KJC-TSK-0686, MG-A of épica KJC-PCS-0068): the rule
+ * that work starts from a card moves from playbook text into the gate.
+ * hu-board → the branch must reference a LIVE card (block by default);
+ * planning-game/external → card-shaped reference required (warn default,
+ * block via method_gates.card_first). Exemptions explicit and visible:
+ * base branch, configured prefixes (releases), KJ_ALLOW_NO_CARD=1.
+ */
+import { listPlans, loadPlan } from "../plan/plan-store.js";
+import { escapeRegExp } from "../utils/escape-regexp.js";
+import { verifyCardAlive } from "./card-verify.js";
+
+const LIVE_STATUSES = new Set(["pending", "running", "failed"]);
+// Card-shaped reference: LIN-123, bb-002 and multi-segment ids like
+// KJC-TSK-0684 (optional middle segments) — tight enough to skip slugs.
+// Shared with the method report (MG-D): one pattern, one truth.
+export const CARD_REF_RE = /\b[a-z][a-z0-9]{1,9}(?:-[a-z][a-z0-9]{1,9})*-\d{1,6}\b/i;
+const DEFAULT_EXEMPT_PREFIXES = ["chore/release-"];
+
+// Token-boundary match: BB-002 must not satisfy a branch that actually
+// references BB-0022 (reviewer catch — substring matching allowed work
+// onto the wrong card).
+function refInBranch(ref, branchLower) {
+  return new RegExp(`(^|[^a-z0-9])${escapeRegExp(String(ref).toLowerCase())}([^a-z0-9]|$)`).test(branchLower);
+}
+
+async function findLiveCardInBranch(projectDir, branch) {
+  const needle = branch.toLowerCase();
+  // Scan EVERY match before deciding: any live reference satisfies the
+  // gate; a closed one is only reported when no live match exists
+  // (reviewer catch — first-match could reject a branch that also
+  // references a live card, depending on plan iteration order).
+  let closedHit = null;
+  for (const meta of await listPlans(projectDir)) {
+    const plan = await loadPlan(projectDir, meta.planId);
+    for (const h of plan.hus || []) {
+      for (const ref of [h.short_id, h.id]) {
+        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 };
+        }
+      }
+    }
+  }
+  return closedHit;
+}
+
+export async function checkCardFirst({ config = {}, projectDir = process.cwd(), branch, env = process.env, deps = {} }) {
+  if (env.KJ_ALLOW_NO_CARD === "1") {
+    return { ok: true, mode: "exempt", reason: "KJ_ALLOW_NO_CARD=1 (explicit escape hatch)" };
+  }
+  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]}/…)` };
+  }
+  // The base branch belongs to the branch-first gate — card-first here
+  // would only double-report (and HEAD covers detached checkouts in CI).
+  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" };
+  }
+
+  const backend = config.state_backend || "hu-board";
+  const policy = config.method_gates?.card_first || "auto";
+
+  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 };
+  }
+
+  // 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.
+  const boardName = config.board?.name || backend;
+  const effective = policy === "auto" ? "warn" : policy;
+  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 };
+    }
+    return { ok: true, mode: "pass", ref, level: v.level, ...(v.note ? { note: v.note } : {}) };
+  }
+  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 };
+}

package/src/review/card-verify.js

@@ -0,0 +1,83 @@
+/**
+ * card-verify — KJC-TSK-0732 (issue #1371). With a declared tracker,
+ * card-first upgrades "the branch names a card" to "the tracker says that
+ * card is ALIVE". Transport-agnostic: `board.verify_cmd` is the USER'S
+ * adapter (their CLI/MCP wrapper — credentials never enter kj) printing
+ * {exists, live, status?} JSON on stdout. Unverifiable NEVER blocks: it
+ * degrades to branch-ref level SAYING SO — a gate must not claim a check
+ * it didn't make, in either direction. Definitive verdicts are cached
+ * briefly; degradations never are, so recovery is immediate.
+ */
+import { exec } from "node:child_process";
+import { createHash } from "node:crypto";
+import { promisify } from "node:util";
+import fs from "node:fs";
+import path from "node:path";
+import { extractFirstJson } from "../utils/json-extract.js";
+
+const execAsync = promisify(exec);
+export const VERIFY_TIMEOUT_MS = 4000;
+const CACHE_TTL_MS = 10 * 60 * 1000;
+// The ref lands inside a shell command (the user's adapter template), so it
+// must be inert BY CONSTRUCTION — card-ref alphabet only, anchored (codex
+// catch: same injection class as the tournament coder names).
+const SAFE_REF_RE = /^[a-z0-9][a-z0-9-]{0,63}$/i;
+
+const defaultExec = async (cmd, { cwd }) =>
+  execAsync(cmd, { cwd, timeout: VERIFY_TIMEOUT_MS, maxBuffer: 1024 * 1024 });
+
+function cachePath(projectDir) {
+  return path.join(projectDir, ".kj", "cache", "card-verify.json");
+}
+
+/** @returns {Promise<{level: "tracker"|"branch-ref", verified: boolean|null, status?: string|null, note?: string}>}
+ *  verified: true = alive · false = definitively not · null = degraded. */
+export async function verifyCardAlive({ ref, verifyCmd, projectDir = process.cwd(), deps = {} }) {
+  const { execFn = defaultExec, now = Date.now } = deps;
+  if (!verifyCmd) {
+    return {
+      level: "branch-ref", verified: null,
+      note: "card-first checked the branch reference only — set board.verify_cmd to verify the card against your tracker",
+    };
+  }
+
+  if (!SAFE_REF_RE.test(String(ref))) {
+    return {
+      level: "branch-ref", verified: null,
+      note: `tracker verification skipped — ref "${String(ref).slice(0, 30)}" is outside the card-ref alphabet`,
+    };
+  }
+  let cache = {};
+  try {
+    cache = JSON.parse(fs.readFileSync(cachePath(projectDir), "utf8"));
+  } catch { /* no cache yet */ }
+  // Keyed by adapter AND ref (reviewer catch): a verdict from one
+  // verify_cmd must never answer for a different one.
+  const key = `${createHash("sha256").update(verifyCmd).digest("hex").slice(0, 12)}:${ref}`;
+  const hit = cache[key];
+  if (hit && now() - hit.at < CACHE_TTL_MS) return hit.result;
+
+  const cmd = verifyCmd.includes("{ref}") ? verifyCmd.replaceAll("{ref}", ref) : `${verifyCmd} ${ref}`;
+  try {
+    const { stdout } = await execFn(cmd, { cwd: projectDir });
+    const parsed = extractFirstJson(String(stdout));
+    if (!parsed || typeof parsed.exists !== "boolean") {
+      throw new Error("adapter must print JSON {exists, live, status} on stdout");
+    }
+    const alive = parsed.exists && parsed.live !== false;
+    const result = alive
+      ? { level: "tracker", verified: true, status: parsed.status ?? null }
+      : { level: "tracker", verified: false, status: parsed.status ?? (parsed.exists ? "not-live" : "not-found") };
+    try {
+      fs.mkdirSync(path.dirname(cachePath(projectDir)), { recursive: true });
+      fs.writeFileSync(cachePath(projectDir), JSON.stringify({ ...cache, [key]: { at: now(), result } }));
+    } catch { /* cache is best-effort — the verdict stands without it */ }
+    return result;
+  } catch (err) {
+    const why = String(err.message || err).split("\n")[0].slice(0, 120);
+    return {
+      level: "branch-ref", verified: null,
+      note: `tracker verification degraded to branch-ref (${why}) — fix board.verify_cmd or its credentials`,
+    };
+  }
+}

package/src/review/diff-generator.js

@@ -0,0 +1,112 @@
+import { runCommand } from "../utils/process.js";
+import { generateSnapshotDiff } from "./snapshot-diff.js";
+import { getRunContext } from "../utils/run-context.js";
+
+// Module-scope back-compat state for callers outside a `withRunContext`
+// scope. When inside a pipeline, `getRunContext()` provides per-run
+// isolation (TSK-0338) — the module-level values below are only consulted
+// as a last resort.
+
+/** @type {((command: string, args?: string[], options?: object) => Promise<object>)|null} */
+let _runner = null;
+
+/** @type {Map<string, string>|null} — pre-coder filesystem snapshot for git-free diff */
+let _snapshot = null;
+
+/** @type {string|null} — project directory scope for git diff (prevents leaking unrelated changes) */
+let _projectDir = null;
+
+/** Retained for back-compat; pipelines should use `withRunContext({ projectDir })` for isolation. */
+export function setProjectDir(dir) {
+  _projectDir = dir;
+}
+
+/** Retained for back-compat; pipelines should use `withRunContext({ snapshot })` for isolation. */
+export function setSnapshot(snapshot) {
+  _snapshot = snapshot;
+}
+
+/** Retained for back-compat; pipelines should use `withRunContext({ runner })` for isolation. */
+export function setRunner(runner) {
+  _runner = runner;
+}
+
+function resolveRunner() {
+  return getRunContext()?.runner || _runner || runCommand;
+}
+
+function resolveProjectDir() {
+  const ctx = getRunContext();
+  if (ctx && "projectDir" in ctx) return ctx.projectDir;
+  return _projectDir;
+}
+
+function resolveSnapshot() {
+  const ctx = getRunContext();
+  if (ctx && "snapshot" in ctx) return ctx.snapshot;
+  return _snapshot;
+}
+
+function run(command, args, ...rest) {
+  return resolveRunner()(command, args, ...rest);
+}
+
+export async function computeBaseRef({ baseBranch = "main", baseRef = null }) {
+  if (baseRef) return baseRef;
+
+  try {
+    const mergeBase = await run("git", ["merge-base", "HEAD", `origin/${baseBranch}`]);
+    if (mergeBase.exitCode === 0) return mergeBase.stdout.trim();
+
+    const fallback = await run("git", ["rev-parse", "HEAD~1"]);
+    if (fallback.exitCode === 0) return fallback.stdout.trim();
+
+    // Empty repo (zero commits): diff against the empty tree
+    const emptyTree = await run("git", ["hash-object", "-t", "tree", "/dev/null"]);
+    if (emptyTree.exitCode === 0) return emptyTree.stdout.trim();
+  } catch { /* git not available */ }
+
+  // No git or all strategies failed — return sentinel for snapshot-based diff
+  return "__snapshot__";
+}
+
+export async function generateDiff({ baseRef, stageNewFiles = false, projectDir = null }) {
+  // Auto-resolve projectDir from run context (TSK-0338) or module fallback
+  const scopeDir = projectDir || resolveProjectDir() || null;
+  const snapshot = resolveSnapshot();
+
+  // Try git diff first
+  try {
+    if (stageNewFiles) {
+      const addArgs = scopeDir ? ["-A", scopeDir] : ["-A"];
+      await run("git", ["add", ...addArgs]);
+    }
+    const diffArgs = ["diff", stageNewFiles ? "--cached" : "", `${baseRef}`].filter(Boolean);
+    // Scope diff to projectDir when it's a subdirectory (prevents leaking unrelated changes)
+    if (scopeDir) diffArgs.push("--", scopeDir);
+    const result = await run("git", diffArgs);
+    if (result.exitCode === 0) {
+      return result.stdout;
+    }
+  } catch { /* git not available or failed */ }
+
+  // Fallback: snapshot-based diff (no git needed)
+  if (snapshot) {
+    const dir = projectDir || process.cwd();
+    return generateSnapshotDiff(snapshot, null, dir);
+  }
+
+  // No git and no snapshot — generate diff of all files as new.
+  // TSK-0340: dropped a stray `const { takeSnapshot } = await import(...)`
+  // that was never used in this branch (we synthesize an empty Map and
+  // let generateSnapshotDiff do the file walk itself).
+  const dir = projectDir || process.cwd();
+  const emptySnapshot = new Map();
+  return generateSnapshotDiff(emptySnapshot, null, dir);
+}
+
+export async function getUntrackedFiles(cwd = null) {
+  const result = await run("git", ["ls-files", "--others", "--exclude-standard"], cwd ? { cwd } : {});
+  if (result.exitCode !== 0) return [];
+  return result.stdout.trim().split("\n").filter(Boolean);
+}