karajan-code 3.0.0 → 3.2.0

package/src/rag/vec-store.js

@@ -1,253 +1,17 @@
-// KJC-PCS-0049 Step 1 — Vector store sobre better-sqlite3 + sqlite-vec.
-// El RAG indexer (Step 4) escribe; el retriever (Step 5) lee. Una sola
-// DB en `~/.karajan/rag.db` por instalación.
-import { mkdirSync, existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import Database from "better-sqlite3";
-import * as sqliteVec from "sqlite-vec";
-
-import { getKarajanHome } from "../utils/paths.js";
-
-const DEFAULT_DIM = 768;
-
-export function dbPath() {
-  return process.env.KJ_RAG_DB || join(getKarajanHome(), "rag.db");
-}
-
-/**
- * Open the rag.db, load the sqlite-vec extension, and ensure the
- * chunks + vec_chunks tables exist. Idempotent: a second call against
- * the same file is a no-op past the schema creation.
- *
- * Returns the open Database handle. Caller owns close().
- *
- * @param {Object} [opts]
- * @param {number} [opts.dim=768] — embedding dimension. Must match
- *   the embedder configured for the project (Step 2). Changing it
- *   later requires a fresh DB; the constant is captured in the
- *   virtual table DDL.
- */
-export function openVecStore({ dim = DEFAULT_DIM, path = dbPath() } = {}) {
-  if (!existsSync(dirname(path))) mkdirSync(dirname(path), { recursive: true });
-  const db = new Database(path);
-  sqliteVec.load(db);
-  db.pragma("journal_mode = WAL");
-  db.pragma("foreign_keys = ON");
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS chunks (
-      id INTEGER PRIMARY KEY AUTOINCREMENT,
-      source TEXT NOT NULL,
-      kind TEXT NOT NULL CHECK (kind IN ('plan', 'code', 'onboarding')),
-      text TEXT NOT NULL,
-      metadata TEXT,
-      created_at TEXT NOT NULL DEFAULT (datetime('now'))
-    );
-    CREATE INDEX IF NOT EXISTS chunks_by_source ON chunks(source);
-    CREATE INDEX IF NOT EXISTS chunks_by_kind ON chunks(kind);
-  `);
-  // KJC-TSK-0438 — Project isolation. project_slug = basename of projectDir
-  // normalized; chunks indexed before the migration carry NULL and remain
-  // queryable when `--project all` (or no slug detected at query time).
-  const cols = db.prepare("PRAGMA table_info(chunks)").all().map((c) => c.name);
-  if (!cols.includes("project_slug")) {
-    db.exec("ALTER TABLE chunks ADD COLUMN project_slug TEXT;");
-    db.exec("CREATE INDEX IF NOT EXISTS chunks_by_project ON chunks(project_slug);");
-  }
-  // KJC-TSK-0484 — Content-hash dedup. SHA-256 of the chunk text lets the
-  // indexer skip embedding bodies it has already seen for the same project.
-  // Older rows keep NULL; the lookup ignores NULLs so they neither dedup
-  // nor get deduped until they are re-indexed and stamped.
-  if (!cols.includes("content_hash")) {
-    db.exec("ALTER TABLE chunks ADD COLUMN content_hash TEXT;");
-    db.exec("CREATE INDEX IF NOT EXISTS chunks_by_hash ON chunks(content_hash, project_slug);");
-  }
-  // KJC-TSK-0455 — Auto-update by commit diff. Per-project metadata tracks
-  // the last commit whose changes were reflected in the index, so subsequent
-  // `kj rag index --since auto` invocations (and the post-merge hook / pre-run
-  // drift check landed in PR2) only re-embed the actual delta instead of the
-  // whole project.
-  db.exec(`
-    CREATE TABLE IF NOT EXISTS vec_store_meta (
-      project_slug TEXT PRIMARY KEY,
-      last_indexed_commit TEXT,
-      last_indexed_at TEXT NOT NULL DEFAULT (datetime('now'))
-    );
-  `);
-  db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS vec_chunks USING vec0(embedding float[${dim}]);`);
-  // KJC-TSK-0443 — FTS5 keyword index for BM25 hybrid scoring. content='chunks'
-  // makes it a contentless mirror linked by id (no double storage); triggers
-  // sync the FTS5 rows on insert/update/delete. Rebuilds idempotently when
-  // the FTS5 table exists but is empty (e.g. created post-migration on a
-  // DB with pre-v2.28 chunks).
-  db.exec(`
-    CREATE VIRTUAL TABLE IF NOT EXISTS chunks_fts USING fts5(text, content='chunks', content_rowid='id');
-    CREATE TRIGGER IF NOT EXISTS chunks_ai AFTER INSERT ON chunks BEGIN
-      INSERT INTO chunks_fts(rowid, text) VALUES (new.id, new.text);
-    END;
-    CREATE TRIGGER IF NOT EXISTS chunks_ad AFTER DELETE ON chunks BEGIN
-      INSERT INTO chunks_fts(chunks_fts, rowid, text) VALUES ('delete', old.id, old.text);
-    END;
-    CREATE TRIGGER IF NOT EXISTS chunks_au AFTER UPDATE ON chunks BEGIN
-      INSERT INTO chunks_fts(chunks_fts, rowid, text) VALUES ('delete', old.id, old.text);
-      INSERT INTO chunks_fts(rowid, text) VALUES (new.id, new.text);
-    END;
-  `);
-  const ftsCount = db.prepare("SELECT COUNT(*) AS n FROM chunks_fts").get().n;
-  const chunksCount = db.prepare("SELECT COUNT(*) AS n FROM chunks").get().n;
-  if (ftsCount === 0 && chunksCount > 0) {
-    db.exec("INSERT INTO chunks_fts(chunks_fts) VALUES('rebuild');");
-  }
-  return db;
-}
-
-/**
- * Persist one chunk. The chunks.id and vec_chunks.rowid stay in sync
- * because the virtual table rowid is set explicitly to the freshly
- * minted chunks.id. Returns that id.
- */
-export function insertChunk(db, { source, kind, text, metadata = null, embedding, project = null, contentHash = null }) {
-  if (!Array.isArray(embedding) && !ArrayBuffer.isView(embedding)) {
-    throw new Error("insertChunk: embedding must be an array or typed array of floats");
-  }
-  const meta = metadata == null ? null : (typeof metadata === "string" ? metadata : JSON.stringify(metadata));
-  const ins = db.prepare("INSERT INTO chunks (source, kind, text, metadata, project_slug, content_hash) VALUES (?, ?, ?, ?, ?, ?)");
-  const info = ins.run(source, kind, text, meta, project, contentHash);
-  // sqlite-vec's vec0 virtual table requires the rowid to arrive as a BigInt
-  // even for values that comfortably fit in a Number. Better-sqlite3 returns
-  // lastInsertRowid as BigInt only when safeIntegers mode is on; force it.
-  const id = typeof info.lastInsertRowid === "bigint" ? info.lastInsertRowid : BigInt(info.lastInsertRowid);
-  const buf = embedding instanceof Float32Array ? embedding : Float32Array.from(embedding);
-  db.prepare("INSERT INTO vec_chunks(rowid, embedding) VALUES (?, ?)").run(id, Buffer.from(buf.buffer));
-  return Number(id);
-}
-
-/**
- * Cosine-ordered nearest-neighbour search. Returns `[{ id, source, kind,
- * text, metadata, distance }]` for the topK best matches; lower
- * distance = closer. Returns `[]` when the store is empty.
- */
-export function searchSimilar(db, embedding, topK = 5, { kind = null, project = null, whereSql = "", whereParams = [] } = {}) {
-  const buf = embedding instanceof Float32Array ? embedding : Float32Array.from(embedding);
-  const kindClause = kind ? "AND c.kind = ?" : "";
-  const projectClause = project ? "AND c.project_slug = ?" : "";
-  const sql = `
-    SELECT c.id, c.source, c.kind, c.text, c.metadata, c.project_slug, v.distance
-    FROM vec_chunks v
-    JOIN chunks c ON c.id = v.rowid
-    WHERE v.embedding MATCH ? AND k = ? ${kindClause} ${projectClause}${whereSql}
-    ORDER BY v.distance
-  `;
-  const params = [Buffer.from(buf.buffer), topK];
-  if (kind) params.push(kind);
-  if (project) params.push(project);
-  if (whereParams.length) params.push(...whereParams);
-  const rows = db.prepare(sql).all(...params);
-  return rows.map((r) => ({ ...r, metadata: r.metadata ? safeParse(r.metadata) : null }));
-}
-
-/**
- * Normalize a projectDir into a stable slug used for project isolation.
- * Basename → lowercased → non-alphanumeric stripped to dashes.
- * KJC-TSK-0438.
- */
-export function projectSlug(projectDir) {
-  if (!projectDir) return null;
-  const base = String(projectDir).replace(/\/+$/, "").split("/").pop();
-  if (!base) return null;
-  return base.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
-}
-
-function safeParse(s) { try { return JSON.parse(s); } catch { return s; } }
-
-/**
- * Remove every chunk that came from a given source path. Both tables
- * are touched explicitly because vec0 virtual tables do not honour
- * SQLite foreign-key cascades.
- */
-export function deleteChunksBySource(db, source) {
-  const ids = db.prepare("SELECT id FROM chunks WHERE source = ?").all(source).map((r) => r.id);
-  if (ids.length === 0) return 0;
-  const placeholders = ids.map(() => "?").join(",");
-  db.prepare(`DELETE FROM vec_chunks WHERE rowid IN (${placeholders})`).run(...ids);
-  db.prepare(`DELETE FROM chunks WHERE id IN (${placeholders})`).run(...ids);
-  return ids.length;
-}
-
-// KJC-TSK-0455 — Per-project commit watermark for `kj rag index --since auto`
-// and the post-merge / pre-run drift hooks landing in PR2.
-export function getLastIndexedCommit(db, projectSlug) {
-  if (!projectSlug) return null;
-  const row = db.prepare("SELECT last_indexed_commit FROM vec_store_meta WHERE project_slug = ?").get(projectSlug);
-  return row?.last_indexed_commit ?? null;
-}
-
-export function setLastIndexedCommit(db, projectSlug, commit) {
-  if (!projectSlug || !commit) return;
-  db.prepare(`
-    INSERT INTO vec_store_meta (project_slug, last_indexed_commit, last_indexed_at)
-    VALUES (?, ?, datetime('now'))
-    ON CONFLICT(project_slug) DO UPDATE SET
-      last_indexed_commit = excluded.last_indexed_commit,
-      last_indexed_at = excluded.last_indexed_at
-  `).run(projectSlug, commit);
-}
-
-// KJC-TSK-0484 PR-B — Bulk fetch embeddings for an explicit set of chunk ids.
-// Returns Map<id, Float32Array>. Used by MMR diversification in retriever.js.
-export function getEmbeddingsByIds(db, ids) {
-  const out = new Map();
-  if (!ids?.length) return out;
-  const placeholders = ids.map(() => "?").join(",");
-  const rows = db.prepare(`SELECT rowid AS id, embedding FROM vec_chunks WHERE rowid IN (${placeholders})`).all(...ids);
-  for (const row of rows) {
-    if (!row.embedding) continue;
-    const buf = Buffer.isBuffer(row.embedding) ? row.embedding : Buffer.from(row.embedding);
-    out.set(Number(row.id), new Float32Array(buf.buffer, buf.byteOffset, buf.byteLength / 4));
-  }
-  return out;
-}
-
-// KJC-TSK-0484 — Lookup an already-indexed chunk by content_hash. Scoped to a
-// project so two repos with the same boilerplate file don't cross-pollute.
-// Returns `{ id, source }` or null. Pass `project=null` to match NULL slugs.
-export function findChunkByHash(db, hash, project = null) {
-  if (!hash) return null;
-  const sql = project
-    ? "SELECT id, source FROM chunks WHERE content_hash = ? AND project_slug = ? LIMIT 1"
-    : "SELECT id, source FROM chunks WHERE content_hash = ? AND project_slug IS NULL LIMIT 1";
-  const row = project ? db.prepare(sql).get(hash, project) : db.prepare(sql).get(hash);
-  return row || null;
-}
-
-export function countChunks(db, { kind = null } = {}) {
-  if (kind) return db.prepare("SELECT COUNT(*) AS n FROM chunks WHERE kind = ?").get(kind).n;
-  return db.prepare("SELECT COUNT(*) AS n FROM chunks").get().n;
-}
-
-/**
- * KJC-TSK-0443 — BM25 keyword search over chunks_fts. Returns
- * [{ id, source, kind, text, metadata, project_slug, bm25 }] ordered by
- * relevance (lower bm25 = better in SQLite FTS5). `query` is sanitized for
- * the FTS5 grammar: special chars are stripped, words split on whitespace.
- */
-export function searchBM25(db, queryText, topK = 10, { kind = null, project = null, whereSql = "", whereParams = [] } = {}) {
-  const cleaned = String(queryText || "").replace(/["'()]/g, " ").split(/\s+/).filter(Boolean).join(" OR ");
-  if (!cleaned) return [];
-  const kindClause = kind ? "AND c.kind = ?" : "";
-  const projectClause = project ? "AND c.project_slug = ?" : "";
-  const sql = `
-    SELECT c.id, c.source, c.kind, c.text, c.metadata, c.project_slug, bm25(chunks_fts) AS bm25
-    FROM chunks_fts JOIN chunks c ON c.id = chunks_fts.rowid
-    WHERE chunks_fts MATCH ? ${kindClause} ${projectClause}${whereSql}
-    ORDER BY bm25 LIMIT ?
-  `;
-  const params = [cleaned];
-  if (kind) params.push(kind);
-  if (project) params.push(project);
-  if (whereParams.length) params.push(...whereParams);
-  params.push(topK);
-  try {
-    const rows = db.prepare(sql).all(...params);
-    return rows.map((r) => ({ ...r, metadata: r.metadata ? safeParse(r.metadata) : null }));
-  } catch { return []; }
-}
+// 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/review/git-stash-helper.js

@@ -0,0 +1,104 @@
+// Surgical stash helper for the TDD discipline gate (KJC-TSK-0398 PR2).
+// Stashes only the source files we want to hide for the "red" run and
+// restores them afterwards. Tracked files use `git stash push -- <paths>`;
+// untracked files (not yet known to git) are moved aside to a private
+// `.karajan/tmp/stash-<id>/` tree because `git stash` would ignore them.
+
+import { mkdir, rename, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { runCommand } from "../utils/process.js";
+
+function defaultRunner(cmd, args, opts) {
+  return runCommand(cmd, args, opts);
+}
+
+async function isTracked(runner, projectDir, file) {
+  const res = await runner("git", ["ls-files", "--error-unmatch", "--", file], { cwd: projectDir });
+  return res.exitCode === 0;
+}
+
+async function stashRefForToken(runner, projectDir, marker) {
+  const res = await runner("git", ["stash", "list"], { cwd: projectDir });
+  if (res.exitCode !== 0) return null;
+  for (const line of String(res.stdout || "").split("\n")) {
+    if (line.includes(marker)) {
+      const m = line.match(/^(stash@\{\d+\})/);
+      if (m) return m[1];
+    }
+  }
+  return null;
+}
+
+// Move `files` aside so a test run sees them as missing. Returns a token to
+// pass to `restoreFiles()`. Throws on failure with the partial token attached.
+export async function stashFilesAside(files, { projectDir = process.cwd(), runner = defaultRunner, tmpRoot } = {}) {
+  if (!Array.isArray(files) || files.length === 0) {
+    return { trackedStashRef: null, untrackedMoves: [], marker: null };
+  }
+  const tracked = [];
+  const untracked = [];
+  for (const f of files) {
+    if (await isTracked(runner, projectDir, f)) tracked.push(f);
+    else if (existsSync(resolve(projectDir, f))) untracked.push(f);
+  }
+
+  const marker = `kj-tdd-discipline-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+  const stashRoot = tmpRoot || join(projectDir, ".karajan", "tmp", marker);
+  const untrackedMoves = [];
+  let trackedStashRef = null;
+
+  if (tracked.length > 0) {
+    const args = ["stash", "push", "--keep-index", "-m", marker, "--", ...tracked];
+    const res = await runner("git", args, { cwd: projectDir });
+    if (res.exitCode !== 0) {
+      throw new Error(`git stash push failed: ${res.stderr || res.stdout}`);
+    }
+    trackedStashRef = await stashRefForToken(runner, projectDir, marker);
+  }
+
+  for (const f of untracked) {
+    const src = resolve(projectDir, f);
+    const dst = join(stashRoot, f);
+    await mkdir(dirname(dst), { recursive: true });
+    await rename(src, dst);
+    untrackedMoves.push({ src, dst });
+  }
+
+  return { trackedStashRef, untrackedMoves, marker, stashRoot };
+}
+
+// Reverse a `stashFilesAside` token. Idempotent: a restored token becomes a no-op.
+export async function restoreFiles(token, { projectDir = process.cwd(), runner = defaultRunner } = {}) {
+  if (!token || (token.trackedStashRef == null && token.untrackedMoves.length === 0)) return;
+
+  for (const { src, dst } of token.untrackedMoves) {
+    if (existsSync(dst)) {
+      await mkdir(dirname(src), { recursive: true });
+      await rename(dst, src);
+    }
+  }
+  if (token.stashRoot && existsSync(token.stashRoot)) {
+    await rm(token.stashRoot, { recursive: true, force: true });
+  }
+
+  if (token.trackedStashRef) {
+    const res = await runner("git", ["stash", "pop", token.trackedStashRef], { cwd: projectDir });
+    if (res.exitCode !== 0) {
+      throw new Error(`git stash pop failed: ${res.stderr || res.stdout}`);
+    }
+  }
+  token.trackedStashRef = null;
+  token.untrackedMoves = [];
+}
+
+// Run `body` with `files` stashed aside, always restoring them — even when
+// `body` throws. The TDD discipline stage wraps its "red" run with this.
+export async function withStashedFiles(files, body, opts = {}) {
+  const token = await stashFilesAside(files, opts);
+  try {
+    return await body(token);
+  } finally {
+    await restoreFiles(token, opts).catch(() => { /* swallow: surface body error */ });
+  }
+}

package/src/review/tdd-discipline.js

@@ -0,0 +1,90 @@
+// TDD discipline gate (KJC-TSK-0398 PR1).
+// PR1 ships the pure decision logic with injected runTests/stashFiles
+// helpers. PR2 ships the real surgical stash. PR3 wires the gate into
+// the pipeline behind `development.require_red_then_green`.
+
+const PARSERS = {
+  vitest: parseVitestFailures,
+  jest: parseVitestFailures,
+  pytest: parsePytestFailures,
+};
+
+function parseVitestFailures(output) {
+  const failures = new Set();
+  for (const line of String(output || "").split("\n")) {
+    const m = line.match(/^\s*(?:FAIL|×|✖)\s+(\S+)/);
+    if (m) failures.add(m[1].trim());
+  }
+  return failures;
+}
+
+function parsePytestFailures(output) {
+  const failures = new Set();
+  for (const line of String(output || "").split("\n")) {
+    const m = line.match(/^FAILED\s+(\S+)/);
+    if (m) failures.add(m[1].trim());
+  }
+  return failures;
+}
+
+function anyNewTestIn(failures, testFiles) {
+  return [...failures].some((f) => testFiles.some((t) => f.includes(t) || t.includes(f)));
+}
+
+export async function verifyTddDiscipline({
+  projectDir,
+  sourceFiles = [],
+  testFiles = [],
+  framework = null,
+  runTests,
+  stashFiles,
+  restoreFiles,
+} = {}) {
+  if (sourceFiles.length === 0) {
+    return { ok: true, reason: "no_source_changes", sourceFiles, testFiles };
+  }
+  if (testFiles.length === 0) {
+    return { ok: true, reason: "no_test_changes", sourceFiles, testFiles };
+  }
+
+  const parser = framework ? PARSERS[framework] : null;
+  if (!parser) {
+    return {
+      ok: true,
+      reason: "framework_unsupported",
+      sourceFiles,
+      testFiles,
+      warning: `tdd-discipline: framework "${framework || "unknown"}" has no failure parser; gate skipped`,
+    };
+  }
+
+  let stashToken = null;
+  try {
+    stashToken = await stashFiles(sourceFiles);
+    const before = await runTests(projectDir);
+    if (!anyNewTestIn(parser(before.output), testFiles)) {
+      return {
+        ok: false,
+        reason: "tests_pass_without_impl",
+        sourceFiles,
+        testFiles,
+        message:
+          "TDD discipline violation: new tests pass without the implementation. Tests must fail first (red), then pass (green).",
+      };
+    }
+  } finally {
+    if (stashToken) await restoreFiles(stashToken);
+  }
+
+  const after = await runTests(projectDir);
+  if (anyNewTestIn(parser(after.output), testFiles)) {
+    return {
+      ok: false,
+      reason: "tests_fail_with_impl",
+      sourceFiles,
+      testFiles,
+      message: "TDD discipline violation: new tests still fail with the implementation present.",
+    };
+  }
+  return { ok: true, reason: "red_then_green_verified", sourceFiles, testFiles };
+}

package/src/roles/audit-role.js

@@ -9,6 +9,7 @@ import { collectSemgrepFindings } from "../audit/semgrep-findings.js";
 import { collectCircularDeps } from "../audit/circular-deps.js";
 import { collectDeadExports } from "../audit/dead-exports.js";
 import { collectInjectionFindings } from "../audit/injection-findings.js";
+import { collectAiSlop } from "../audit/ai-slop-findings.js";
 
 function parseDimensions(dimensionsStr) {
   if (!dimensionsStr || dimensionsStr === "all") return null;
@@ -53,6 +54,7 @@ export class AuditRole extends AgentRole {
     const noMadge = typeof input === "object" ? Boolean(input?.noMadge) : false;
     const noKnip = typeof input === "object" ? Boolean(input?.noKnip) : false;
     const noInjectionScan = typeof input === "object" ? Boolean(input?.noInjectionScan) : false;
+    const noAiSlop = typeof input === "object" ? Boolean(input?.noAiSlop) : false;
     const projectDir = this.config?.projectDir || process.cwd();
     let basalCost = null;
     let growthDelta = null;
@@ -64,6 +66,7 @@ export class AuditRole extends AgentRole {
     let circularDeps = null;
     let deadExports = null;
     let injectionFindings = null;
+    let aiSlop = null;
     try {
       basalCost = await measureBasalCost(projectDir);
       const previous = await loadPreviousAudit(projectDir);
@@ -116,7 +119,14 @@ export class AuditRole extends AgentRole {
         injectionFindings = await collectInjectionFindings(projectDir, this.logger);
       } catch { /* injection scan is best-effort (KJC-TSK-0498) */ }
     }
-    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, injectionFindings };
+    // AI-slop tells (KJC-TSK-0503). Deterministic, offline, regex-based.
+    // Local equivalent of Deslopify-style review. Best-effort.
+    if (!noAiSlop) {
+      try {
+        aiSlop = await collectAiSlop(projectDir);
+      } catch { /* ai-slop scan is best-effort */ }
+    }
+    return { projectDir, basalCost, growthDelta, stack, sonarFindings, webperf, osvFindings, semgrepFindings, circularDeps, deadExports, injectionFindings, aiSlop };
   }
 
   /**

package/src/roles/tool-correctness-judge-role.js

@@ -0,0 +1,78 @@
+// KJC-TSK-0375 — ToolCorrectnessJudgeRole.
+// Post-iteration LLM judge scoring how well a coder picked its tool calls.
+// PR1 ships role + tests; wiring lives in PR3.
+
+import { AgentRole } from "./agent-role.js";
+import { buildToolCorrectnessJudgePrompt } from "../prompts/tool-correctness-judge.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+
+const DEFAULT_THRESHOLD = 70;
+
+const clampScore = (n) => Number.isFinite(n) ? Math.max(0, Math.min(100, Math.round(n))) : null;
+
+const normalizeBreakdown = (b) => Array.isArray(b) ? b.map((x) => ({
+  tool: typeof x?.tool === "string" ? x.tool : "unknown",
+  args: x?.args && typeof x.args === "object" ? x.args : {},
+  correct: Boolean(x?.correct),
+  reason: typeof x?.reason === "string" ? x.reason.trim() : "",
+})) : [];
+
+export class ToolCorrectnessJudgeRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "tool-correctness-judge" });
+    this.threshold = opts?.threshold ?? this.config?.pipeline?.tool_judge?.threshold ?? DEFAULT_THRESHOLD;
+  }
+
+  resolveProvider() {
+    return this.config?.roles?.["tool-correctness-judge"]?.provider
+      || this.config?.roles?.reviewer?.provider
+      || this.config?.roles?.coder?.provider
+      || "claude";
+  }
+
+  extractInput(input) {
+    return { ...super.extractInput(input), toolCalls: Array.isArray(input?.toolCalls) ? input.toolCalls : [] };
+  }
+
+  async buildPrompt({ task, toolCalls }) {
+    return { prompt: buildToolCorrectnessJudgePrompt({ task, toolCalls, instructions: this.instructions }) };
+  }
+
+  parseOutput(raw) { return extractFirstJson(raw); }
+
+  buildSuccessResult(parsed, provider) {
+    const score = clampScore(parsed?.score);
+    return {
+      score,
+      summary: typeof parsed?.summary === "string" ? parsed.summary.trim() : "",
+      breakdown: normalizeBreakdown(parsed?.breakdown),
+      threshold: this.threshold,
+      lowQuality: score !== null && score < this.threshold,
+      provider,
+    };
+  }
+
+  buildSummary(parsed) {
+    const score = clampScore(parsed?.score);
+    if (score === null) return "Tool-judge: unparseable score";
+    return `Tool-judge: ${score}/100 (${score < this.threshold ? "LOW" : "OK"})`;
+  }
+
+  // Empty tool-call list = nothing to judge. Skip the LLM and report a
+  // neutral score so an absent transcript is never read as a failure.
+  async execute(input) {
+    const extracted = this.extractInput(input);
+    if (extracted.toolCalls.length === 0) {
+      return {
+        ok: true,
+        result: {
+          score: null, summary: "no tool calls captured (skipped)", breakdown: [],
+          threshold: this.threshold, lowQuality: false, provider: this.resolveProvider(), skipped: true,
+        },
+        summary: "Tool-judge: skipped (no calls)",
+        usage: null,
+      };
+    }
+    return super.execute(extracted);
+  }
+}

package/src/session/mutators.js

@@ -109,6 +109,10 @@ export function setSonarSummary(session, text) {
   session.last_sonar_summary = text;
 }
 
+export function setCoderTranscript(session, text) {
+  session.last_coder_transcript = text;
+}
+
 export function setSonarIssueSignature(session, sig) {
   session.last_sonar_issue_signature = sig;
 }

package/src/sync/apply-canvas-patch.js

@@ -0,0 +1,55 @@
+/**
+ * kj sync --apply — append a drift patch to the Canvas markdown.
+ *
+ * KJC-TSK-0348. Pure data + I/O: reads the Canvas at `canvasPath`, drops a
+ * `.bak` snapshot alongside it, appends an HTML-comment block describing
+ * untracked / missing / covered files, and atomically renames a `.tmp`
+ * over the target. Comments are inert for the Canvas parser, so the
+ * patched file stays structurally valid — the user converts the TODOs
+ * into Operations by hand.
+ */
+
+import { promises as fs } from "node:fs";
+
+function tempPath(target) {
+  return `${target}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
+}
+
+export function renderDriftComment(report) {
+  const lines = ["", `<!-- kj sync --apply (${new Date().toISOString()}) — review and convert into Operations as needed. -->`];
+  let mutations = 0;
+  if (report.untracked?.length) {
+    lines.push("<!-- Untracked files (modified, no Operation references them — add one): -->");
+    for (const u of report.untracked) { lines.push(`<!-- + ${u.path} -->`); mutations += 1; }
+  }
+  if (report.missing?.length) {
+    lines.push("<!-- Missing files (Operation file_hint points at a file that does not exist): -->");
+    for (const m of report.missing) { lines.push(`<!-- ! ${m.path}  [op #${(m.operationIndex ?? 0) + 1}] -->`); mutations += 1; }
+  }
+  if (report.covered?.length) {
+    lines.push("<!-- Covered (referenced and modified — consider extending the Approach): -->");
+    for (const c of report.covered) lines.push(`<!-- ~ ${c.path}  [op #${(c.operationIndex ?? 0) + 1}] -->`);
+  }
+  lines.push("<!-- /kj sync -->", "");
+  return { block: lines.join("\n"), mutations };
+}
+
+export async function applyCanvasPatch({ canvasPath, report }) {
+  if (!canvasPath || typeof canvasPath !== "string") throw new Error("applyCanvasPatch: canvasPath is required");
+  if (!report || typeof report !== "object") throw new Error("applyCanvasPatch: report is required");
+  const hasDrift = (report.untracked?.length || 0) + (report.missing?.length || 0) > 0;
+  if (!hasDrift) return { patchedPath: canvasPath, backupPath: null, mutations: 0, skipped: true };
+
+  let original;
+  try { original = await fs.readFile(canvasPath, "utf-8"); }
+  catch (err) { throw new Error(`applyCanvasPatch: cannot read canvas ${canvasPath}: ${err.message}`, { cause: err }); }
+
+  const backupPath = `${canvasPath}.bak`;
+  await fs.writeFile(backupPath, original, "utf-8");
+  const { block, mutations } = renderDriftComment(report);
+  const trimmed = original.endsWith("\n") ? original : `${original}\n`;
+  const tmp = tempPath(canvasPath);
+  await fs.writeFile(tmp, `${trimmed}${block}\n`, "utf-8");
+  await fs.rename(tmp, canvasPath);
+  return { patchedPath: canvasPath, backupPath, mutations };
+}