@karajan-family/code 4.21.0

package/src/spec-review/run-spec-review.js

@@ -0,0 +1,119 @@
+// Pre-pipeline orchestrator for the spec-reviewer (KJC-PCS-0048 PR 2).
+// Called from src/commands/run.js and src/commands/plan/generate.js
+// BEFORE the actual pipeline. Decides whether to proceed based on the
+// role's findings + the user's answer to the interactive prompt.
+// PR 2 only supports [c]ontinue / [x]cancel; refine loop lands in PR 3.
+
+import { SpecReviewerRole } from "../roles/spec-reviewer-role.js";
+import { printFindings } from "../utils/display/spec-findings.js";
+import { runRefinePass } from "./refine-loop.js";
+import { RISK } from "../autonomy/policy.js";
+
+const MAX_REFINE_ITERATIONS = 5;
+
+// KJC-BUG-0125 (issue #1275): the prompt used to carry only counts and
+// categories — the dashboard modal showed "4 findings at severity fail"
+// with nothing to act on. The full findings travel with the prompt now
+// (capped: a runaway reviewer must not blow up the prompt payload).
+const MAX_FINDINGS_IN_PROMPT = 20;
+const findingsForPrompt = (findings) => findings.slice(0, MAX_FINDINGS_IN_PROMPT).map((f) => ({
+  id: f.id, severity: f.severity, category: f.category,
+  message: f.message, suggestion: f.suggestion || null,
+}));
+
+/**
+ * Decide the gate action (`continue` | `refine`) autonomously: the Arbiter
+ * picks PROCEED (proceed with the best reading) or RETRY_DIFFERENT_APPROACH
+ * (auto-refine). It is never offered `cancel`, so an autonomous run never
+ * aborts on spec ambiguity (KJC-TSK-0572, closes gap G1).
+ */
+async function decideGateAutonomously(resolve, { severity, findings }) {
+  const { choice } = await resolve({
+    question: `Spec has ${findings.length} finding(s) at severity ${severity}: proceed with the best reading, or auto-refine?`,
+    options: [
+      { value: "PROCEED", label: "proceed with the best reading", conservative: true },
+      { value: "RETRY_DIFFERENT_APPROACH", label: "auto-refine the spec" },
+    ],
+    context: { severity, findingCount: findings.length, categories: [...new Set(findings.map((f) => f.category))], findings: findingsForPrompt(findings) },
+    risk: severity === "fail" ? RISK.HIGH : RISK.LOW,
+  });
+  return choice === "RETRY_DIFFERENT_APPROACH" ? "refine" : "continue";
+}
+
+export async function runSpecReview({ spec, config, logger, askQuestion, flags = {}, resolve = null, autonomy = "interactive" }) {
+  // VITEST guard — pre-existing test suites (e.g. tests/commands/command-run.test.js)
+  // mock `runFlow` + `assertAgentsAvailable` but predate this role and have
+  // no need to exercise it. Auto-skip in vitest unless the test passes
+  // `flags.forceSpecReview: true` (the spec-review's own tests bypass via
+  // their vi.doMock of SpecReviewerRole and never reach this guard).
+  if (process.env.VITEST && !flags.forceSpecReview) return { proceed: true, skipped: true };
+  if (flags.skipSpecReview || config?.spec_reviewer?.enabled === false) {
+    return { proceed: true, skipped: true };
+  }
+  if (!spec || !String(spec).trim()) return { proceed: true, skipped: true };
+
+  const role = new SpecReviewerRole({ config, logger });
+  await role.init({ task: spec });
+
+  // Outer loop: review → prompt → optional refine → re-review (the
+  // refine path replaces `currentSpec` and we go around again).
+  let currentSpec = spec;
+  for (let iter = 0; iter < MAX_REFINE_ITERATIONS; iter += 1) {
+    const res = await role.execute({ spec: currentSpec });
+    if (!res.ok) {
+      logger?.warn?.(`[spec] reviewer failed: ${res.summary} — continuing without review`);
+      return { proceed: true, error: res.result?.error, finalSpec: currentSpec };
+    }
+    const { severity, findings } = res.result || {};
+    if (!findings || findings.length === 0 || severity === "ok") {
+      logger?.info?.(iter === 0 ? "✓ spec OK" : "✓ refined spec OK");
+      return { proceed: true, severity: "ok", findings: [], finalSpec: currentSpec, refined: iter > 0 };
+    }
+    printFindings(findings, severity);
+
+    // Autonomous/assisted: the Arbiter decides (continue|refine), never cancels.
+    // Interactive (no resolver): the human answers [c]/[r]/[x] as before.
+    let action;
+    if (resolve && autonomy !== "interactive") {
+      action = await decideGateAutonomously(resolve, { severity, findings });
+    } else {
+      if (!askQuestion) return { proceed: true, severity, findings, finalSpec: currentSpec };
+      // KJC-TSK-0674 (issue #1289): at severity FAIL the default flips to
+      // cancel — continuing past fails requires an explicit answer, both
+      // interactively (Enter cancels) and unattended (no declared default,
+      // so --yes / KJ_NON_INTERACTIVE stops with exit ≠ 0). warn/info keep
+      // the KJC-BUG-0109 contract: --yes presses Enter → continue.
+      const fallback = severity === "fail" ? "cancel" : "continue";
+      const answer = await askQuestion(
+        `Spec review: ${findings.length} finding${findings.length === 1 ? "" : "s"} at severity ${severity}. [c]ontinue / [r]efine / [x]cancel? (default: ${fallback})`,
+        {
+          detail: { severity, findingCount: findings.length, categories: [...new Set(findings.map((f) => f.category))], iteration: iter + 1, findings: findingsForPrompt(findings) },
+          defaultAnswer: severity === "fail" ? undefined : "continue",
+        },
+      );
+      if (answer === null) return { proceed: false, cancelled: true, severity, findings };
+      const n = String(answer).trim().toLowerCase() || fallback;
+      if (n.startsWith("x") || n === "cancel") action = "cancel";
+      else if (n.startsWith("r") || n === "refine") action = "refine";
+      else action = "continue";
+    }
+    if (action === "cancel") return { proceed: false, cancelled: true, severity, findings };
+    if (action === "refine") {
+      const refine = await runRefinePass({
+        spec: currentSpec, findings, role,
+        projectDir: config?.projectDir, taskFile: flags.taskFile, logger,
+      });
+      if (!refine.ok) {
+        logger?.warn?.(`[spec] refine failed: ${refine.error} — proceeding with original spec`);
+        return { proceed: true, severity, findings, finalSpec: currentSpec };
+      }
+      currentSpec = refine.refinedSpec;
+      if (refine.hashChanged) continue; // user tweaked v2 → re-review
+      logger?.info?.("✓ refined spec accepted by user (no edits)");
+      return { proceed: true, severity: "ok", findings: [], finalSpec: currentSpec, refined: true };
+    }
+    return { proceed: true, severity, findings, finalSpec: currentSpec }; // continue
+  }
+  logger?.warn?.(`[spec] max refine iterations (${MAX_REFINE_ITERATIONS}) reached — proceeding with last spec`);
+  return { proceed: true, finalSpec: currentSpec, refined: true };
+}

package/src/start/assessment.js

@@ -0,0 +1,74 @@
+// KJC-TSK-0569 (Onboard B) — deterministic synthesis of the read-only sweep.
+//
+// Turns the sweep bundle (Onboard A, 0568) into one coherent digest: a
+// human-readable report plus a machine summary the decider (StartDecidorRole)
+// consumes to pick an intent. No LLM here — the costly call is the haiku
+// decider, not a redundant strong-model narration. Reuses the harden advisory
+// formatter so the improvements section reads exactly like `kj harden --report`.
+import { formatAdvisoryReport } from "../harden/advisory.js";
+
+const EMPTY_TALLY = { install: 0, update: 0, review: 0, keep: 0 };
+
+/** Tally harden advisory artifacts by recommendation. */
+function tallyImprovements(improvements) {
+  const tally = { ...EMPTY_TALLY };
+  for (const a of improvements?.artifacts ?? []) {
+    if (a?.recommendation in tally) tally[a.recommendation] += 1;
+  }
+  return tally;
+}
+
+/** Quality/maintenance gaps as short phrases, derived from signals + drift. */
+function collectGaps(signals = {}, drift) {
+  const gaps = [];
+  if (!signals.hasTests) gaps.push("no tests");
+  if (!signals.hasCI) gaps.push("no CI");
+  if (typeof signals.staleDays === "number" && signals.staleDays > 365) {
+    gaps.push(`last commit ${signals.staleDays}d old`);
+  }
+  if (drift && drift.ok === false) {
+    const failed = (drift.checks ?? []).filter((c) => c?.ok === false).length;
+    if (failed > 0) gaps.push(`${failed} harden check(s) drifting`);
+  }
+  return gaps;
+}
+
+/**
+ * @param {object} bundle output of runReadOnlySweep (0568)
+ * @returns {{text: string, summary: object}}
+ */
+export function buildAssessment(bundle) {
+  if (!bundle || typeof bundle !== "object") {
+    throw new TypeError("buildAssessment: bundle must be an object");
+  }
+  const { maturity = {}, signals = {}, drift, improvements, rag, qmd } = bundle;
+  const gaps = collectGaps(signals, drift);
+  const improvementCounts = tallyImprovements(improvements);
+
+  const summary = {
+    maturity: maturity.maturity ?? "unknown",
+    declared: Boolean(maturity.declared),
+    deepHealthRecommended: Boolean(maturity.deepHealthRecommended),
+    gaps,
+    driftOk: drift ? drift.ok !== false : null,
+    improvementCounts,
+    indexed: rag ? Boolean(rag.indexed) : null,
+    qmdAvailable: qmd ? Boolean(qmd.available) : null,
+  };
+
+  const lines = [
+    `Project maturity: ${summary.maturity}${summary.declared ? " (declared)" : " (inferred)"}`,
+    ...(maturity.reasons ?? []).map((r) => `  - ${r}`),
+    "",
+    `Tests: ${signals.hasTests ? "yes" : "no"} · CI: ${signals.hasCI ? "yes" : "no"} · commits: ${signals.commitCount ?? 0}`,
+    `Quality gaps: ${gaps.length ? gaps.join(", ") : "none detected"}`,
+    `Knowledge index: ${summary.indexed === null ? "n/a" : summary.indexed ? "present" : "missing"}` +
+      ` · qmd: ${summary.qmdAvailable === null ? "n/a" : summary.qmdAvailable ? "available" : "absent"}`,
+  ];
+
+  if (improvements) {
+    lines.push("", ...formatAdvisoryReport(improvements));
+  }
+
+  return { text: lines.join("\n"), summary };
+}

package/src/start/maturity.js

@@ -0,0 +1,73 @@
+// KJC-TSK-0568 (Onboard A) — maturity classifier for the Brain (`kj start`).
+//
+// Pure and deterministic: given a bundle of read-only signals it labels the
+// project new | existing | legacy. No LLM, no I/O — the sweep (sweep.js) does
+// the reading; this only decides. The label drives which read-only subset the
+// orchestrator runs and, downstream (0570), whether a deep health pass is worth
+// the cost. A user-declared maturity always wins over inference.
+//
+// Acceptance criteria (KJC-TSK-0568):
+//   - empty repo / scaffolding only       -> new
+//   - code + config + tests/CI            -> existing
+//   - code but missing tests/CI, or very stale -> legacy
+
+/** Last-commit age (days) beyond which a repo counts as stalled/neglected. */
+export const STALE_DAYS_THRESHOLD = 365;
+
+const VALID = new Set(["new", "existing", "legacy"]);
+
+/**
+ * @param {object} signals
+ * @param {("new"|"existing"|"legacy"|null)} [signals.declared] user override
+ * @param {boolean} signals.hasSourceCode  real source files present
+ * @param {boolean} signals.scaffoldingOnly only generator boilerplate, no real code
+ * @param {boolean} signals.hasTests        a test suite is present
+ * @param {boolean} signals.hasCI           CI workflows are present
+ * @param {number}  [signals.commitCount]   number of commits (capped upstream)
+ * @param {number|null} [signals.staleDays] age of the last commit in days
+ * @returns {{maturity: "new"|"existing"|"legacy", reasons: string[], deepHealthRecommended: boolean, declared: boolean}}
+ */
+export function classifyMaturity(signals) {
+  if (!signals || typeof signals !== "object") {
+    throw new TypeError("classifyMaturity: signals must be an object");
+  }
+
+  if (VALID.has(signals.declared)) {
+    const maturity = signals.declared;
+    return {
+      maturity,
+      reasons: [`maturity declared by user as "${maturity}"`],
+      deepHealthRecommended: maturity === "legacy",
+      declared: true,
+    };
+  }
+
+  const reasons = [];
+  let maturity;
+
+  if (!signals.hasSourceCode || signals.scaffoldingOnly) {
+    maturity = "new";
+    reasons.push(signals.scaffoldingOnly ? "only scaffolding present, no real code yet" : "no source code found");
+  } else {
+    const stalled = typeof signals.staleDays === "number" && signals.staleDays > STALE_DAYS_THRESHOLD;
+    const gaps = [];
+    if (!signals.hasTests) gaps.push("no tests");
+    if (!signals.hasCI) gaps.push("no CI");
+    if (stalled) gaps.push(`last commit ${signals.staleDays}d old (stalled)`);
+
+    if (gaps.length > 0) {
+      maturity = "legacy";
+      reasons.push(`code present but neglected: ${gaps.join(", ")}`);
+    } else {
+      maturity = "existing";
+      reasons.push("code with tests and CI, actively maintained");
+    }
+  }
+
+  return {
+    maturity,
+    reasons,
+    deepHealthRecommended: maturity === "legacy",
+    declared: false,
+  };
+}

package/src/start/start-decider-role.js

@@ -0,0 +1,79 @@
+// KJC-TSK-0569 (Onboard B) — the StartDecidor: the only LLM in the Brain's
+// onboarding. Reads the deterministic assessment + user goal, picks ONE intent
+// from a closed set, and never executes (0570 maps the intent to a safe command).
+// Provider falls back to the coder, model defaults to haiku. Unparseable/unknown
+// output degrades to ASK_USER so `kj start` always has a sane next step.
+import { AgentRole } from "../roles/agent-role.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+import { buildStartDecisionPrompt, INTENTS } from "../prompts/start-decision.js";
+
+const FALLBACK_QUESTION = "What would you like to do with this project?";
+
+export class StartDecidorRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "start" });
+  }
+
+  extractInput(input) {
+    const src = typeof input === "string" ? { userMessage: input } : input || {};
+    return {
+      userMessage: src.userMessage || "",
+      assessment: src.assessment || "",
+      onOutput: src.onOutput || null,
+      ...src,
+    };
+  }
+
+  async buildPrompt({ userMessage, assessment }) {
+    return {
+      prompt: buildStartDecisionPrompt({ userMessage, assessment, instructions: this.instructions }),
+    };
+  }
+
+  parseOutput(raw) {
+    return extractFirstJson(raw);
+  }
+
+  buildSuccessResult(parsed, provider) {
+    const intent = INTENTS.has(parsed.intent) ? parsed.intent : "ASK_USER";
+    const rationale = String(parsed.rationale || "").trim();
+    const questionToAsk = String(parsed.questionToAsk || "").trim();
+    const degraded = intent !== parsed.intent;
+    return {
+      intent,
+      rationale: rationale || (degraded ? "Unrecognized intent, asking the user." : "No rationale provided."),
+      questionToAsk: intent === "ASK_USER" ? questionToAsk || FALLBACK_QUESTION : "",
+      provider,
+    };
+  }
+
+  buildSummary(parsed) {
+    const intent = INTENTS.has(parsed.intent) ? parsed.intent : "ASK_USER";
+    return `Start decision: ${intent}`;
+  }
+
+  handleParseNull(agentResult, provider) {
+    return this.degradedDecision({ agentResult, provider, reason: "no JSON found" });
+  }
+
+  handleParseError(err, agentResult, provider) {
+    return this.degradedDecision({ agentResult, provider, reason: err?.message || "parse error" });
+  }
+
+  // Never block onboarding: garbage in → ask the user one open question.
+  degradedDecision({ agentResult, provider, reason }) {
+    this.logger?.warn?.(`[start] decider output unusable (${reason}) — asking the user.`);
+    return {
+      ok: true,
+      result: {
+        intent: "ASK_USER",
+        rationale: `Could not read a decision (${reason}).`,
+        questionToAsk: FALLBACK_QUESTION,
+        provider,
+        degraded: true,
+      },
+      summary: "Start decision: ASK_USER (fallback)",
+      usage: agentResult.usage,
+    };
+  }
+}

package/src/start/sweep.js

@@ -0,0 +1,157 @@
+// KJC-TSK-0568 (Onboard A) — read-only sweep orchestrator for the Brain.
+//
+// Runs the READ-ONLY signals fitting the project's maturity and aggregates them
+// into one structured bundle for synthesis (Onboard B, 0569). Writes nothing.
+// No LLM: maturity is deterministic and the costly audit is deferred — legacy
+// only flags `deepHealthRecommended` (0570 decides). Subset by maturity: new =
+// brief+tests; existing/legacy = + drift, harden advisory, rag + qmd status.
+// Collaborators are injected (opts.deps) so it stays trivially testable.
+import { existsSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { join, relative } from "node:path";
+import { execFileSync } from "node:child_process";
+
+import { collectAll } from "../onboarder/collectors/index.js";
+import { checkHarden } from "../harden/check.js";
+import { compareHarden } from "../harden/advisory.js";
+import { detectTestFramework } from "../utils/project-detect.js";
+import { detectQmd } from "../utils/qmd-detect.js";
+import {
+  dbPath, openVecStore, projectSlug, countChunks, getLastIndexedCommit,
+} from "../rag/vec-store.js";
+import { classifyMaturity } from "./maturity.js";
+
+const CODE_EXT = new Set([
+  ".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx", ".py", ".go",
+  ".rs", ".java", ".php", ".rb", ".c", ".cc", ".cpp", ".cs",
+]);
+// KJC-BUG-0141 — infra projects (k8s/terraform/shell/Docker) ARE source code,
+// and code nested deeper than the display tree's maxDepth must still count.
+const INFRA_EXT = new Set([".yaml", ".yml", ".tf", ".hcl", ".sh"]);
+const INFRA_NAMES = new Set(["Dockerfile", "Makefile", "Vagrantfile"]);
+const SCAN_IGNORED = new Set([
+  "node_modules", "dist", "build", "out", "vendor", "coverage", "target", "__pycache__",
+]);
+const SCAN_MAX_DEPTH = 6;
+const SCAFFOLD_MAX_FILES = 3;
+const CI_MARKERS = [".github/workflows", ".gitlab-ci.yml"];
+
+const safe = async (fn) => { try { return await fn(); } catch { return null; } };
+
+const isTestPath = (p) => {
+  const posix = p.replaceAll("\\", "/");
+  return /\.(test|spec)\./.test(posix) || /(^|\/)(test|tests|__tests__)\//.test(posix);
+};
+
+/**
+ * Deep source counter with its own walk: the display tree stops at depth 2,
+ * which made backend/app/… projects look empty (KJC-BUG-0141).
+ * @returns {Promise<{code: number, infra: number}>}
+ */
+export async function deepSourceScan(projectDir, { maxDepth = SCAN_MAX_DEPTH } = {}) {
+  const counts = { code: 0, infra: 0 };
+  const walk = async (dir, depth) => {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const ent of entries) {
+      if (ent.name.startsWith(".") || SCAN_IGNORED.has(ent.name)) continue;
+      const full = join(dir, ent.name);
+      if (ent.isDirectory()) {
+        if (depth < maxDepth) await walk(full, depth + 1);
+        continue;
+      }
+      if (!ent.isFile() || isTestPath(relative(projectDir, full))) continue;
+      const ext = ent.name.slice(ent.name.lastIndexOf("."));
+      if (CODE_EXT.has(ext)) counts.code += 1;
+      else if (INFRA_EXT.has(ext) || INFRA_NAMES.has(ent.name)) counts.infra += 1;
+    }
+  };
+  await walk(projectDir, 0);
+  return counts;
+}
+
+/** Count real source files in a tree bundle, skipping tests. */
+export function countCodeFiles(tree = []) {
+  let n = 0;
+  for (const node of tree) {
+    if (node.kind === "dir") n += countCodeFiles(node.children);
+    else if (node.kind === "file") {
+      const ext = node.path.slice(node.path.lastIndexOf("."));
+      if (CODE_EXT.has(ext) && !isTestPath(node.path)) n += 1;
+    }
+  }
+  return n;
+}
+
+/** Age of the last commit in days, or null on non-git / no commits. */
+function lastCommitAgeDays(projectDir) {
+  try {
+    const out = execFileSync("git", ["log", "-1", "--format=%ct"], {
+      cwd: projectDir, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"],
+    }).trim();
+    if (!out) return null;
+    return Math.floor((Date.now() - Number(out) * 1000) / 86_400_000);
+  } catch { return null; }
+}
+
+/** Read-only RAG index status; null when no index file exists yet. */
+function readRagStatus(projectDir) {
+  try {
+    if (!existsSync(dbPath())) return { indexed: false, chunks: 0, lastIndexedCommit: null };
+    const db = openVecStore();
+    return {
+      indexed: true,
+      chunks: countChunks(db, { kind: "code" }),
+      lastIndexedCommit: getLastIndexedCommit(db, projectSlug(projectDir)),
+    };
+  } catch { return null; }
+}
+
+/**
+ * @param {string} projectDir
+ * @param {{declared?: ("new"|"existing"|"legacy"|null), profile?: string, deps?: object}} [opts]
+ *   declared = user-declared maturity; deps = injected collaborators (defaults = real collectors).
+ */
+export async function runReadOnlySweep(projectDir, { declared = null, profile = "standard", deps = {} } = {}) {
+  // KJC-BUG-0145: a missing projectDir must fail LOUD — every collector is
+  // wrapped in safe(), so an undefined root used to read as an empty project.
+  if (!projectDir) throw new Error("runReadOnlySweep: projectDir is required (got " + String(projectDir) + ")");
+  const d = {
+    collectAll, detectTestFramework, checkHarden, compareHarden, sourceScan: deepSourceScan,
+    detectQmd, ragStatus: readRagStatus, gitAgeDays: lastCommitAgeDays, ...deps,
+  };
+
+  const brief = await safe(() => d.collectAll(projectDir));
+  const tests = await safe(() => d.detectTestFramework(projectDir));
+  const scan = await safe(() => d.sourceScan(projectDir));
+
+  const tree = brief?.tree ?? [];
+  const present = brief?.configs?.present ?? [];
+  const codeFiles = scan ? scan.code + scan.infra : countCodeFiles(tree);
+  const commitCount = brief?.git?.commitCount ?? 0;
+
+  const signals = {
+    hasSourceCode: codeFiles > 0,
+    infraFiles: scan?.infra ?? 0,
+    scaffoldingOnly: codeFiles > 0 && codeFiles <= SCAFFOLD_MAX_FILES && commitCount <= 1,
+    hasTests: Boolean(tests?.hasTests),
+    hasCI: CI_MARKERS.some((m) => present.includes(m)),
+    commitCount,
+    staleDays: d.gitAgeDays(projectDir),
+  };
+
+  const maturity = classifyMaturity({ declared, ...signals });
+  const deep = maturity.maturity !== "new";
+
+  return {
+    projectDir,
+    maturity,
+    signals,
+    brief,
+    tests,
+    drift: deep ? await safe(() => d.checkHarden({ projectDir, profile })) : null,
+    improvements: deep ? await safe(() => d.compareHarden({ projectDir, profile })) : null,
+    rag: deep ? await safe(() => d.ragStatus(projectDir)) : null,
+    qmd: deep ? await safe(() => d.detectQmd()) : null,
+    collectedAt: new Date().toISOString(),
+  };
+}

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 };
+}

package/src/sync/detect-drift.js

@@ -0,0 +1,113 @@
+/**
+ * kj sync — drift detection between code and the Canvas / plan
+ * (issue #540, MVP).
+ *
+ * Scope of THIS module: pure data transformation. Given a plan
+ * (with Operations and their file_hints) plus a list of currently
+ * tracked source files (mtime + path), classify each file:
+ *
+ *   - covered      — file IS referenced by some Operation's file_hint
+ *                    AND was modified since the plan was created.
+ *                    (Expected drift; plan still authoritative.)
+ *   - untracked    — file exists, modified, but no Operation references
+ *                    it. The user added it manually after the run; the
+ *                    Canvas needs a new Operation to reflect it.
+ *   - missing      — Operation references a file that no longer exists
+ *                    on disk. Either the file was deleted or the plan
+ *                    is wrong about its location.
+ *   - clean        — file is referenced by an Operation AND has not
+ *                    been modified since the plan. No action needed.
+ *
+ * The classifier is pure: caller does the I/O (walking the tree,
+ * stating files, parsing plan JSON). Easy to unit-test.
+ */
+
+/**
+ * @param {object} plan — plan JSON with `operations` (or `hus`) carrying
+ *                        optional `file_hint` strings, and `createdAt` ISO
+ * @param {Array<{path: string, mtime: Date}>} files — files in the project
+ * @returns {{ covered: object[], untracked: object[], missing: object[], clean: object[] }}
+ */
+export function classifyDrift(plan, files) {
+  const planMtime = new Date(plan?.createdAt || plan?.updatedAt || 0);
+
+  // Collect every file_hint declared by any operation/HU. Both keys
+  // are accepted for back-compat with v2 plans (HUs) and Canvas
+  // (Operations).
+  const ops = Array.isArray(plan?.operations) ? plan.operations
+    : Array.isArray(plan?.hus) ? plan.hus
+    : [];
+  const hinted = new Map(); // file → operation index
+  ops.forEach((op, idx) => {
+    const hint = op.file_hint || op.fileHint;
+    if (typeof hint === "string" && hint.length > 0) {
+      hinted.set(hint, idx);
+    }
+  });
+
+  const out = { covered: [], untracked: [], missing: [], clean: [] };
+  const seenInFs = new Set();
+
+  for (const f of files) {
+    if (!f?.path) continue;
+    seenInFs.add(f.path);
+    const opIdx = hinted.get(f.path);
+    const modified = f.mtime instanceof Date && f.mtime > planMtime;
+
+    if (opIdx === undefined) {
+      // Not referenced by any operation. Two sub-cases:
+      //  - modified: real drift, propose new operation.
+      //  - not modified: probably a pre-existing file from before the
+      //    plan; ignore (no action).
+      if (modified) {
+        out.untracked.push({ path: f.path, mtime: f.mtime, suggestion: "new operation" });
+      }
+      continue;
+    }
+    if (modified) {
+      out.covered.push({ path: f.path, mtime: f.mtime, operationIndex: opIdx });
+    } else {
+      out.clean.push({ path: f.path, operationIndex: opIdx });
+    }
+  }
+
+  // Missing: operation says a file should exist, but we never saw it.
+  for (const [hint, opIdx] of hinted.entries()) {
+    if (!seenInFs.has(hint)) {
+      out.missing.push({ path: hint, operationIndex: opIdx, suggestion: "remove operation OR fix the file_hint" });
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Render a drift report as plain-text for the terminal.
+ */
+export function formatDriftReport(report, plan) {
+  const lines = [`Drift report — plan ${plan?.planId || "(unknown)"}`, ""];
+  if (report.untracked.length === 0 && report.missing.length === 0 && report.covered.length === 0) {
+    lines.push("  No drift detected.");
+    return lines.join("\n");
+  }
+  if (report.covered.length > 0) {
+    lines.push(`Covered (${report.covered.length}) — modified, an Operation references it; consider extending its Approach:`);
+    for (const c of report.covered) lines.push(`  ~ ${c.path}  [op #${c.operationIndex + 1}]`);
+    lines.push("");
+  }
+  if (report.untracked.length > 0) {
+    lines.push(`Untracked (${report.untracked.length}) — modified, NO Operation references it; propose new Operation:`);
+    for (const u of report.untracked) lines.push(`  + ${u.path}`);
+    lines.push("");
+  }
+  if (report.missing.length > 0) {
+    lines.push(`Missing (${report.missing.length}) — Operation file_hint points at a file that doesn't exist:`);
+    for (const m of report.missing) lines.push(`  ! ${m.path}  [op #${m.operationIndex + 1}] — ${m.suggestion}`);
+    lines.push("");
+  }
+  if (report.clean.length > 0) {
+    lines.push(`Clean (${report.clean.length}) — covered, unchanged.`);
+  }
+  lines.push("", "Run with --json for machine-readable output. Future: --apply to propose Canvas patches (issue #540 follow-ups).");
+  return lines.join("\n");
+}