karajan-code 3.0.0 → 3.1.0

package/src/checks/runner.js

@@ -249,8 +249,15 @@ function summarize(reports) {
  *
  * @example setDotPath({}, "git.auto_pr", false) // → { git: { auto_pr: false } }
  */
+// KJC-BUG-0076: prototype-pollution guard. dot-paths come from check
+// remediation outputs (internal but LLM-generated), so a malformed
+// `__proto__.x` would mutate Object.prototype. Skip the whole write
+// when any segment matches a forbidden key.
+const UNSAFE_DOT_KEY_RE = /^(?:__proto__|constructor|prototype)$/;
+
 function setDotPath(target, dotPath, value) {
   const parts = String(dotPath).split(".");
+  if (parts.some((p) => UNSAFE_DOT_KEY_RE.test(p))) return;
   let cursor = target;
   for (let i = 0; i < parts.length - 1; i++) {
     const k = parts[i];
@@ -314,3 +321,6 @@ export function toLegacyShape(runReport) {
     fix: c.fix ?? null,
   }));
 }
+
+// Exposed for prototype-pollution regression tests (KJC-BUG-0076).
+export const __pollutionInternals = { setDotPath };

package/src/cli/register-meta.js

@@ -313,12 +313,13 @@ export function registerMeta(program, { pkgVersion }) {
 
   program
     .command("sync")
-    .description("Detect drift between code and the latest plan. Read-only report (issue #540 MVP).")
+    .description("Detect drift between code and the latest plan. Read-only by default; --apply writes a patch back to the Canvas.")
     .option("--plan <planId>", "Sync against a specific plan instead of the latest")
     .option("--json", "Emit machine-readable JSON instead of human output")
+    .option("--apply", "Write the drift report into the source Canvas (creates a .bak backup)")
     .action(async (flags) => {
       await withConfig(pkgVersion, "sync", flags, async ({ config, logger }) => {
-        await syncCommand({ config, logger, planId: flags.plan, json: flags.json });
+        await syncCommand({ config, logger, planId: flags.plan, json: flags.json, apply: Boolean(flags.apply) });
       });
     });
 
@@ -352,10 +353,22 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--draft-days <n>", "Keep draft plans for N days (default: 60)")
     .option("--session-days <n>", "Keep finalised sessions for N days (default: 7)")
     .option("--hu-days <n>", "Keep HU story batches for N days (default: 14)")
+    .option("--repo", "Also report repo-level candidates (merged branches, dist/, coverage/, *.tmp, *.bak)")
+    .option("--repo-days <n>", "Age threshold for repo artifacts in days (default: 7)")
+    .option("--repo-base <ref>", "Base ref to detect merged branches (default: origin/main)")
+    .option("--vector-stores", "Also report orphan RAG vector-store entries in ~/.karajan/rag.db")
+    .option("--project-roots <list>", "Colon-separated directories to scan for live projects (default: ~/ws_*, ~/projects, ~/code)")
+    .option("--all", "Shortcut for --repo --vector-stores (full read-only cleanup audit)")
     .action(async (flags) => {
+      const allOn = Boolean(flags.all);
       await cleanCommand({
         yes: Boolean(flags.yes),
         nuke: Boolean(flags.nuke),
+        repo: Boolean(flags.repo) || allOn,
+        repoDays: flags.repoDays ? Number(flags.repoDays) : undefined,
+        repoBase: flags.repoBase || undefined,
+        vectorStores: Boolean(flags.vectorStores) || allOn,
+        projectRoots: flags.projectRoots ? flags.projectRoots.split(":").filter(Boolean) : undefined,
         planDays: flags.planDays ? Number(flags.planDays) : undefined,
         draftDays: flags.draftDays ? Number(flags.draftDays) : undefined,
         sessionDays: flags.sessionDays ? Number(flags.sessionDays) : undefined,

package/src/cli/register-plan.js

@@ -93,7 +93,16 @@ export function registerPlan(program, { pkgVersion }) {
           // Norms + Safeguards ride along under explicit headings the
           // coder prompt can grep for.
           const taskFromCanvas = canvasToTask(validation.canvas);
-          await planGenerateCommand({ task: taskFromCanvas, config, logger, flags });
+          // KJC-TSK-0348: remember WHERE the Canvas lived on disk so
+          // `kj sync --apply` later knows which file to patch.
+          let sourceCanvasPath = null;
+          if (typeof flags?.taskFile === "string" && flags.taskFile.length > 0) {
+            const path = await import("node:path");
+            sourceCanvasPath = path.isAbsolute(flags.taskFile)
+              ? flags.taskFile
+              : path.resolve(config.projectDir || process.cwd(), flags.taskFile);
+          }
+          await planGenerateCommand({ task: taskFromCanvas, config, logger, flags, sourceCanvasPath });
           return;
         }
         await planGenerateCommand({

package/src/commands/clean.js

@@ -19,11 +19,18 @@
  */
 
 import { runManualGC, summarizeGC, nukeBoardDb } from "../utils/garbage-collector.js";
+import { collectRepoCandidates } from "../utils/repo-cleaner.js";
+import { collectVectorStoreOrphans } from "../utils/vector-store-orphans.js";
 
 /**
  * @param {Object} opts
  * @param {boolean} [opts.yes=false]           - when false, dry-run only
  * @param {boolean} [opts.nuke=false]          - retention=0 for every bucket + wipe board DB
+ * @param {boolean} [opts.repo=false]          - also report repo-level candidates (branches, dist, *.tmp, *.bak)
+ * @param {number}  [opts.repoDays=7]          - age threshold for repo artifacts (default 7d)
+ * @param {string}  [opts.repoBase="origin/main"]
+ * @param {boolean} [opts.vectorStores=false]  - also report orphan RAG vector-store entries
+ * @param {string[]} [opts.projectRoots]       - directories scanned to resolve slugs (default: ~/ws_*, ~/projects, ~/code)
  * @param {number}  [opts.planDays=30]
  * @param {number}  [opts.draftDays=60]
  * @param {number}  [opts.sessionDays=7]
@@ -79,5 +86,60 @@ export async function cleanCommand(opts = {}) {
     console.log(summarizeGC(result));
   }
 
+  if (opts.repo) await printRepoReport(opts);
+  if (opts.vectorStores) await printVectorStoreReport(opts);
+
   return { ok: true, removed: result.removed.length, bytesFreed: result.bytesFreed };
 }
+
+async function printRepoReport(opts) {
+  const { candidates, errors } = await collectRepoCandidates({
+    maxAgeDays: opts.repoDays ?? 7,
+    mergedTo: opts.repoBase ?? "origin/main",
+  });
+  console.log("");
+  if (!candidates.length) {
+    console.log("[clean:repo] no repo-level candidates — branches/dist/tmp are tidy.");
+    return;
+  }
+  console.log(`[clean:repo] ${candidates.length} candidate(s) — review and run the command to remove:`);
+  for (const c of candidates) {
+    console.log(`  - ${c.kind.padEnd(11)} ${c.target}`);
+    console.log(`                ${c.reason}`);
+    console.log(`                $ ${c.command}`);
+  }
+  if (errors.length) {
+    console.log(`[clean:repo] ${errors.length} non-blocking error(s):`);
+    for (const e of errors) console.log(`  - ${e.stage}: ${e.error}`);
+  }
+  console.log("[clean:repo] read-only — commands are printed, never executed.");
+}
+
+async function printVectorStoreReport(opts) {
+  const { rows, orphans, errors } = await collectVectorStoreOrphans({
+    projectRoots: opts.projectRoots,
+  });
+  console.log("");
+  if (errors.length && !rows.length) {
+    console.log("[clean:rag] could not read rag.db — RAG may not be initialised yet.");
+    for (const e of errors) console.log(`  - ${e.stage}: ${e.error}`);
+    return;
+  }
+  console.log(`[clean:rag] ${rows.length} project_slug(s) indexed in rag.db:`);
+  for (const r of rows) {
+    const tag = r.orphan ? " ORPHAN" : "";
+    const when = r.lastAt || "n/a";
+    console.log(`  - ${r.slug.padEnd(28)} chunks=${String(r.chunkCount).padStart(5)}  last=${when}${tag}`);
+  }
+  if (!orphans.length) {
+    console.log("[clean:rag] no orphans — every indexed slug resolves to a live project directory.");
+    return;
+  }
+  console.log("");
+  console.log(`[clean:rag] ${orphans.length} orphan(s) — review and run to purge:`);
+  for (const o of orphans) {
+    console.log(`  - ${o.slug}`);
+    console.log(`                $ ${o.command}`);
+  }
+  console.log("[clean:rag] read-only — commands are printed, never executed.");
+}

package/src/commands/plan/generate.js

@@ -21,14 +21,14 @@ import { formatPlan, formatHuTable } from "./_shared.js";
 /**
  * kj plan "task" — generate plan + HUs
  */
-export async function planGenerateCommand({ task, config, logger, json, context, flags = {} }) {
+export async function planGenerateCommand({ task, config, logger, json, context, flags = {}, sourceCanvasPath = null }) {
   const { withCliRunLog } = await import("../../utils/cli-run-log.js");
   return withCliRunLog("plan", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
-    return planGenerateImpl({ task, config, logger, json, context, runLog, flags });
+    return planGenerateImpl({ task, config, logger, json, context, runLog, flags, sourceCanvasPath });
   });
 }
 
-async function planGenerateImpl({ task, config, logger, json, context, runLog, flags = {} }) {
+async function planGenerateImpl({ task, config, logger, json, context, runLog, flags = {}, sourceCanvasPath = null }) {
   // Auto-GC: prune orphan plans (project dir gone) + old finalised plans/
   // sessions/HU batches before we start. Silent unless something was
   // removed; one-liner summary on stderr in that case so --json stays
@@ -164,6 +164,12 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
   plan.approach = parsed?.approach || (typeof parsed === "string" ? parsed : (typeof result.output === "string" ? result.output : null));
   plan.risks = parsed?.risks || [];
   plan.outOfScope = parsed?.outOfScope || [];
+  // KJC-TSK-0348: persist the SPEC.canvas.md path so `kj sync --apply`
+  // can later locate it and append drift notes. Only set when the plan
+  // actually came from a Canvas SPEC; flat-task plans stay unstamped.
+  if (typeof sourceCanvasPath === "string" && sourceCanvasPath.length > 0) {
+    plan.sourceCanvasPath = sourceCanvasPath;
+  }
 
   // Convert planner steps → HUs, carrying the structured acceptance_tests
   // the LLM was asked to emit. If the LLM fell back to legacy behaviour

package/src/commands/sync.js

@@ -1,12 +1,15 @@
 /**
  * `kj sync` — closed-loop drift detection between code and Canvas/plan.
- * Issue #540 MVP: detection + report only. No --apply yet.
+ * Issue #540 MVP: detection + report.
+ * KJC-TSK-0348: `--apply` writes drift notes back into the source Canvas
+ * markdown (with `.bak` backup) so the user can review + commit.
  */
 
 import fs from "node:fs";
 import path from "node:path";
 import { listPlans, loadPlan } from "../plan/plan-store.js";
 import { classifyDrift, formatDriftReport } from "../sync/detect-drift.js";
+import { applyCanvasPatch } from "../sync/apply-canvas-patch.js";
 
 const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "coverage", ".karajan", ".kj", "tmp", ".cache", ".astro", ".next"]);
 
@@ -36,8 +39,11 @@ function listSourceFiles(rootDir, out = []) {
  * @param {object} args.logger
  * @param {string} [args.planId] — when set, sync against this plan; else use the latest
  * @param {boolean} [args.json]
+ * @param {boolean} [args.apply] — when true, write a drift patch back into
+ *                                 the Canvas markdown the plan came from
+ *                                 (with `.bak` backup).
  */
-export async function syncCommand({ config, logger, planId, json }) {
+export async function syncCommand({ config, logger, planId, json, apply }) {
   const projectDir = config?.projectDir || process.cwd();
 
   // Resolve which plan to sync against.
@@ -60,14 +66,36 @@ export async function syncCommand({ config, logger, planId, json }) {
   const files = listSourceFiles(projectDir);
   const report = classifyDrift(plan, files);
 
+  let applyResult = null;
+  if (apply) {
+    if (!plan.sourceCanvasPath) {
+      throw new Error(
+        "kj sync --apply: this plan has no sourceCanvasPath — it was not generated from a SPEC.canvas.md. "
+        + "Re-run `kj plan generate --task-file SPEC.canvas.md` so the plan remembers the Canvas it came from."
+      );
+    }
+    applyResult = await applyCanvasPatch({ canvasPath: plan.sourceCanvasPath, report });
+  }
+
   if (json) {
     console.log(JSON.stringify({
       planId: plan.planId,
       projectDir,
       ...report,
+      apply: applyResult,
     }, null, 2));
   } else {
     console.log(formatDriftReport(report, plan));
+    if (applyResult) {
+      if (applyResult.skipped) {
+        console.log("\nkj sync --apply: no actionable drift, Canvas left untouched.");
+      } else {
+        console.log(
+          `\nkj sync --apply: wrote ${applyResult.mutations} drift note(s) to ${applyResult.patchedPath} `
+          + `(backup at ${applyResult.backupPath}).`
+        );
+      }
+    }
   }
 
   // Exit 0 always — drift is informational, not an error. CI users

package/src/config/defaults.js

@@ -70,6 +70,11 @@ const DEFAULTS = {
   development: {
     methodology: "tdd",
     require_test_changes: true,
+    // KJC-TSK-0398: opt-in red-then-green gate. When true, the pipeline
+    // stashes source files and re-runs the test suite to confirm the new
+    // tests actually fail without the implementation. Off by default to
+    // preserve current iteration latency.
+    require_red_then_green: false,
     test_file_patterns: ["/tests/", "/__tests__/", ".test.", ".spec."],
     source_file_extensions: [".js", ".jsx", ".ts", ".tsx", ".py", ".go", ".java", ".rb", ".php", ".cs"]
   },

package/src/config/schema.js

@@ -115,6 +115,8 @@ const PipelineMap = v.optional(v.looseObject({
 const Development = v.optional(v.looseObject({
   methodology: v.optional(Methodology),
   require_test_changes: v.optional(v.boolean()),
+  // KJC-TSK-0398: opt-in flag; module lands in PR1, integration in PR3.
+  require_red_then_green: v.optional(v.boolean()),
   test_file_patterns: v.optional(v.array(v.string())),
   source_file_extensions: v.optional(v.array(v.string())),
 }));

package/src/orchestrator/config-init.js

@@ -229,6 +229,7 @@ export function resolvePipelineFlags(config) {
     securityEnabled: Boolean(config.pipeline?.security?.enabled),
     impeccableEnabled: Boolean(config.pipeline?.impeccable?.enabled),
     perfEnabled: Boolean(config.pipeline?.perf?.enabled),
+    toolJudgeEnabled: Boolean(config.pipeline?.tool_judge?.enabled),
     reviewerEnabled: config.pipeline?.reviewer?.enabled !== false,
     discoverEnabled: Boolean(config.pipeline?.discover?.enabled),
     architectEnabled: Boolean(config.pipeline?.architect?.enabled),

package/src/orchestrator/drivers/iteration-phases/quality-gates.js

@@ -19,6 +19,8 @@ import {
 } from "../../iteration-stages.js";
 import { runImpeccableStage } from "../../post-loop-stages.js";
 import { runPerfStage } from "../../stages/perf-stage.js";
+import { runTddDisciplineStage } from "../../stages/tdd-discipline-stage.js";
+import { runToolJudgeStage } from "../../stages/tool-judge-stage.js";
 import { tryCiComment } from "../../ci-integration.js";
 
 export async function runQualityGateStages({ config, logger, emitter, eventBase, session, trackBudget, i, askQuestion, repeatDetector, budgetSummary, sonarState, task, stageResults, coderRole, pipelineFlags, brainCtx }) {
@@ -26,6 +28,16 @@ export async function runQualityGateStages({ config, logger, emitter, eventBase,
   if (tddResult.action === "pause") return { action: "return", result: tddResult.result };
   if (tddResult.action === "continue") return { action: "continue" };
 
+  // KJC-TSK-0398 PR3: opt-in red-then-green check.
+  if (config.development?.require_red_then_green) {
+    const disc = await runTddDisciplineStage({
+      config, logger, emitter, eventBase,
+      sourceFiles: tddResult.sourceFiles || [],
+      testFiles: tddResult.testFiles || [],
+    });
+    if (disc.action === "continue") return { action: "continue" };
+  }
+
   // Sonar runs for code tasks per policy. Since v2.7.4 it is NOT
   // toggleable via config — that's intrinsic to Karajan. The taskType
   // policy (resolved_policies.sonar) is the single source of truth.
@@ -84,5 +96,16 @@ export async function runQualityGateStages({ config, logger, emitter, eventBase,
     if (perfResult.action === "continue") return { action: "continue" };
   }
 
+  // KJC-TSK-0375 PR3: opt-in tool-call quality judge. Non-blocking.
+  if (pipelineFlags?.toolJudgeEnabled) {
+    const judgeResult = await runToolJudgeStage({
+      config, logger, emitter, eventBase, session, coderRole, trackBudget,
+      iteration: i, task,
+    });
+    if (judgeResult.stageResult) {
+      stageResults.toolJudge = judgeResult.stageResult;
+    }
+  }
+
   return { action: "ok" };
 }

package/src/orchestrator/stages/coder-stage.js

@@ -8,7 +8,7 @@ import { CoderRole } from "../../roles/coder-role.js";
 import { RefactorerRole } from "../../roles/refactorer-role.js";
 import { addCheckpoint, markSessionStatus, saveSession } from "../../session/store.js";
 import {
-  setReviewerFeedback, incrementRetryCount, resetRetryCount,
+  setReviewerFeedback, setCoderTranscript, incrementRetryCount, resetRetryCount,
 } from "../../session/mutators.js";
 import { generateDiff, getUntrackedFiles } from "../../review/diff-generator.js";
 import { evaluateTddPolicy } from "../../review/tdd-policy.js";
@@ -223,6 +223,12 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
     logger?.warn?.(`[verification-gate] Skipped: ${err?.message || err}`);
   }
 
+  // KJC-TSK-0375 PR3: stash the coder's raw transcript on the session so
+  // the optional tool-judge stage can extract structured tool calls later
+  // without re-invoking the coder. Cleared between iterations by the coder
+  // overwriting it; ignored when the tool-judge flag is off.
+  setCoderTranscript(session, coderTranscript);
+
   await addCheckpoint(session, { stage: "coder", iteration, note: "Coder applied changes", provider: coderRole.provider, model: coderRole.model || null, filesChanged });
   emitProgress(
     emitter,
@@ -459,5 +465,5 @@ export async function runTddCheckStage({ config, logger, emitter, eventBase, ses
     return handleTddFailure({ tddEval, config, logger, emitter, eventBase, session, iteration, askQuestion, task, brainCtx });
   }
 
-  return { action: "ok" };
+  return { action: "ok", sourceFiles: tddEval.sourceFiles, testFiles: tddEval.testFiles };
 }

package/src/orchestrator/stages/tdd-discipline-stage.js

@@ -0,0 +1,56 @@
+// TDD discipline stage (KJC-TSK-0398 PR3).
+// Runs the red-then-green check when `development.require_red_then_green`
+// is true. Wraps `verifyTddDiscipline` with the surgical stash helper and
+// the project's detected test framework. Gate is opt-in; an unsupported
+// framework reports a warning and does not block the iteration.
+
+import { detectTestFramework } from "../../utils/project-detect.js";
+import { verifyTddDiscipline } from "../../review/tdd-discipline.js";
+import { stashFilesAside, restoreFiles } from "../../review/git-stash-helper.js";
+import { runCommand } from "../../utils/process.js";
+import { emitProgress, makeEvent } from "../../utils/events.js";
+
+const TDD_DISCIPLINE_COMMANDS = {
+  vitest: ["npx", ["vitest", "run", "--reporter=verbose"]],
+  jest: ["npx", ["jest", "--verbose"]],
+  pytest: ["pytest", ["--tb=short"]],
+};
+
+export async function runTddDisciplineStage({
+  config, logger, emitter, eventBase, sourceFiles = [], testFiles = [],
+  detectFramework = detectTestFramework,
+  runTestsImpl,
+  stashImpl = stashFilesAside,
+  restoreImpl = restoreFiles,
+} = {}) {
+  const projectDir = config?.projectDir || process.cwd();
+  const detection = await detectFramework(projectDir);
+  const framework = detection?.framework || null;
+
+  const runTests = runTestsImpl || (async () => {
+    const cmd = TDD_DISCIPLINE_COMMANDS[framework];
+    if (!cmd) return { exitCode: 0, output: "" };
+    const res = await runCommand(cmd[0], cmd[1], { cwd: projectDir, reject: false });
+    return { exitCode: res.exitCode ?? 0, output: `${res.stdout || ""}\n${res.stderr || ""}` };
+  });
+
+  const result = await verifyTddDiscipline({
+    projectDir, sourceFiles, testFiles, framework,
+    runTests,
+    stashFiles: (files) => stashImpl(files, { projectDir }),
+    restoreFiles: (token) => restoreImpl(token, { projectDir }),
+  });
+
+  emitProgress(emitter, makeEvent("tdd:discipline", { ...eventBase, stage: "tdd" }, {
+    status: result.ok ? "ok" : "fail",
+    message: result.message || `TDD discipline: ${result.reason}`,
+    detail: { reason: result.reason, framework },
+  }));
+
+  if (result.warning) logger?.warn?.(result.warning);
+  if (!result.ok) {
+    logger?.warn?.(`TDD discipline violation: ${result.reason}`);
+    return { action: "continue", result };
+  }
+  return { action: "ok", result };
+}

package/src/orchestrator/stages/tool-judge-stage.js

@@ -0,0 +1,53 @@
+// KJC-TSK-0375 PR3 — ToolJudgeStage.
+// Opt-in (`pipeline.tool_judge.enabled`). Scores the coder's tool calls
+// extracted from `session.last_coder_transcript`. Non-blocking: a low
+// score emits a warn event and surfaces in summary but never gates the
+// iteration loop. Wiring lives in `quality-gates.js`.
+
+import { ToolCorrectnessJudgeRole } from "../../roles/tool-correctness-judge-role.js";
+import { extractToolCalls } from "../../utils/tool-call-extractor.js";
+import { emitProgress, makeEvent } from "../../utils/events.js";
+
+export async function runToolJudgeStage({
+  config, logger, emitter, eventBase, session, coderRole, trackBudget,
+  iteration, task,
+  extractFn = extractToolCalls,
+  RoleClass = ToolCorrectnessJudgeRole,
+} = {}) {
+  logger?.setContext?.({ iteration, stage: "tool-judge" });
+  emitProgress(emitter, makeEvent("toolJudge:start", { ...eventBase, stage: "tool-judge" }, {
+    message: "Tool-judge scoring coder tool calls",
+  }));
+
+  const transcript = session?.last_coder_transcript || "";
+  const provider = coderRole?.provider || "claude";
+  const toolCalls = extractFn({ transcript, provider });
+
+  const role = new RoleClass({ config, logger, emitter });
+  const roleResult = await role.execute({ task, toolCalls });
+
+  try { trackBudget?.("tool-judge", roleResult.usage || { tokens_in: 0, tokens_out: 0, cost_usd: 0 }); } catch { /* best-effort */ }
+
+  const r = roleResult.result;
+  const status = r?.skipped ? "skip" : r?.lowQuality ? "warn" : roleResult.ok ? "ok" : "fail";
+
+  emitProgress(emitter, makeEvent("toolJudge:end", { ...eventBase, stage: "tool-judge" }, {
+    status,
+    message: roleResult.summary || "tool-judge done",
+    detail: { score: r?.score ?? null, threshold: r?.threshold ?? null, skipped: Boolean(r?.skipped), callCount: toolCalls.length },
+  }));
+
+  return {
+    action: "ok",
+    stageResult: {
+      ok: roleResult.ok !== false,
+      score: r?.score ?? null,
+      lowQuality: Boolean(r?.lowQuality),
+      skipped: Boolean(r?.skipped),
+      threshold: r?.threshold ?? null,
+      summary: roleResult.summary || "",
+      breakdown: r?.breakdown || [],
+      callCount: toolCalls.length,
+    },
+  };
+}

package/src/prompts/tool-correctness-judge.js

@@ -0,0 +1,31 @@
+// KJC-TSK-0375 — Prompt builder for the ToolCorrectnessJudge role.
+// Inspired by deepeval's tool-correctness metric.
+
+const PREAMBLE = "IMPORTANT: You are running as a Karajan sub-agent. "
+  + "Do NOT use any MCP tools, do NOT mention Karajan. "
+  + "Your job is to judge another agent's tool choices.";
+
+export function buildToolCorrectnessJudgePrompt({ task, toolCalls, instructions }) {
+  const calls = toolCalls
+    .map((c, i) => `${i + 1}. **${c.tool}** — args: ${JSON.stringify(c.args)}`)
+    .join("\n");
+  const body = [
+    "You are the ToolCorrectnessJudge for Karajan Code.",
+    "Input: (a) a task description and (b) the ordered tool calls an LLM coder",
+    "made (Read/Edit/Write/Bash/Glob/Grep/MultiEdit). Judge each call on:",
+    "  - tool choice: right tool for the intent?",
+    "  - argument quality: paths plausible, commands valid, no garbage placeholders?",
+    "Per-call verdict: `correct=true|false` + one-sentence `reason`.",
+    "Aggregate into a single 0-100 score:",
+    "  - 100 = every call right with clean args",
+    "  - 70-99 = mostly right, minor missteps",
+    "  - 40-69 = several wrong choices, budget wasted",
+    "  - 0-39 = predominantly bad, retry advised",
+    "Return a single valid JSON object and nothing else.",
+    'Schema: {"score":0-100,"summary":string,"breakdown":[{"tool":string,"args":object,"correct":boolean,"reason":string}]}',
+  ].join("\n");
+  const sections = [PREAMBLE];
+  if (instructions) sections.push(instructions);
+  sections.push(body, `## Task\n${task}`, `## Tool calls (${toolCalls.length})\n${calls || "(no tool calls captured)"}`);
+  return sections.join("\n\n");
+}

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 */ });
+  }
+}