karajan-code 3.0.0 → 3.2.0

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/doctor.js

@@ -22,6 +22,9 @@ import { getOllamaChecks } from "../checks/ollama.js";
 import { getHarnessScorecardChecks } from "../checks/harness-scorecard.js";
 import { getCiChecks } from "../checks/ci.js";
 import { getRtkChecks } from "../checks/rtk.js";
+import { getSqueezrChecks } from "../checks/squeezr.js";
+import { getAiTrashChecks } from "../checks/ai-trash.js";
+import { getQmdChecks } from "../checks/qmd.js";
 import { getNodeChecks } from "../checks/node.js";
 import { getPortChecks } from "../checks/ports.js";
 import { getTokenChecks } from "../checks/tokens.js";
@@ -64,6 +67,9 @@ function buildChecks(config, { projectOnly = false } = {}) {
     ...getSkillsChecks(),
     ...getCiChecks(),
     ...getRtkChecks(),
+    ...getSqueezrChecks(),
+    ...getAiTrashChecks(),
+    ...getQmdChecks(),
     ...getProjectChecks({ projectDir }),
   ];
 }

package/src/commands/init.js

@@ -15,6 +15,12 @@ import { detectOsLocale, SUPPORTED_LANGUAGES } from "../utils/locale.js";
 import { buildTelemetryPayload, sendTelemetryEvent } from "../utils/telemetry.js";
 import { detectRtk } from "../utils/rtk-detect.js";
 import { installRtk } from "../utils/rtk-install.js";
+import { detectSqueezr } from "../utils/squeezr-detect.js";
+import { installSqueezr } from "../utils/squeezr-install.js";
+import { detectAiTrash, installAiTrashHook } from "../utils/ai-trash.js";
+import { detectQmd } from "../utils/qmd-detect.js";
+import { installQmd } from "../utils/qmd-install.js";
+import { registerQmdCollections } from "../utils/qmd-collection.js";
 import { detectProjectStack } from "../utils/stack-detect.js";
 import { bootstrapSonarToken } from "../sonar/token-bootstrap.js";
 
@@ -754,15 +760,74 @@ export async function initCommand({ logger, flags = {} }) {
     logger.info("No project stack detected — using default configuration.");
   }
 
-  // Check RTK availability — auto-install if missing
-  const rtk = await detectRtk();
-  if (rtk.available) {
-    logger.info(`RTK ${rtk.version || ""} detected.`);
+  // Check RTK availability — auto-install if missing (opt-out: --no-rtk)
+  const skipRtk = flags?.noRtk === true || flags?.rtk === false;
+  if (skipRtk) {
+    logger.info("RTK setup skipped (--no-rtk). Bash outputs will not be token-optimized.");
   } else {
-    const installResult = await installRtk(logger);
-    if (!installResult.ok) {
-      logger.warn("RTK is optional but recommended for 60-90% token savings.");
-      logger.warn(`  Manual install: ${getInstallCommand("rtk")}`);
+    const rtk = await detectRtk();
+    if (rtk.available) {
+      logger.info(`RTK ${rtk.version || ""} detected.`);
+    } else {
+      const installResult = await installRtk(logger);
+      if (!installResult.ok) {
+        logger.warn("RTK install failed — Bash outputs will not be token-optimized.");
+        logger.warn(`  Manual install: ${getInstallCommand("rtk")}`);
+      }
+    }
+  }
+
+  // Check Squeezr availability — auto-install if missing (opt-out: --no-squeezr)
+  const skipSqueezr = flags?.noSqueezr === true || flags?.squeezr === false;
+  if (skipSqueezr) {
+    logger.info("Squeezr setup skipped (--no-squeezr). Tool outputs will not be compressed.");
+  } else {
+    const squeezr = await detectSqueezr();
+    if (squeezr.available) {
+      logger.info(`Squeezr ${squeezr.version || ""} detected.`);
+    } else {
+      const installResult = await installSqueezr(logger);
+      if (!installResult.ok) {
+        logger.warn("Squeezr install failed — tool outputs will not be compressed.");
+        logger.warn(`  Manual install: ${getInstallCommand("squeezr")}`);
+      }
+    }
+  }
+
+  // Check ai-trash availability — register PreToolUse hook if binary present
+  // (opt-out: --no-ai-trash). The binary itself ships with karajan-code.
+  const skipAiTrash = flags?.noAiTrash === true || flags?.aiTrash === false;
+  if (skipAiTrash) {
+    logger.info("ai-trash setup skipped (--no-ai-trash). Destructive ops will run unprotected.");
+  } else {
+    const aiTrash = await detectAiTrash();
+    if (aiTrash.available) {
+      await installAiTrashHook(logger);
+    } else {
+      logger.warn("ai-trash kj-trash binary not found — destructive ops unprotected.");
+      logger.warn("  Reinstall karajan-code so kj-trash is on PATH.");
+    }
+  }
+
+  // Check QMD availability — auto-install if missing and register project
+  // collections (docs/, .reviews/, .karajan/plans/). Opt-out: --no-qmd.
+  const skipQmd = flags?.noQmd === true || flags?.qmd === false;
+  if (skipQmd) {
+    logger.info("QMD setup skipped (--no-qmd). Semantic wiki indexing disabled.");
+  } else {
+    const qmd = await detectQmd();
+    if (qmd.available) {
+      logger.info(`QMD ${qmd.version || ""} detected.`);
+    } else {
+      const installResult = await installQmd(logger);
+      if (!installResult.ok) {
+        logger.warn("QMD install failed — semantic wiki unavailable.");
+        logger.warn(`  Manual install: ${getInstallCommand("qmd")}`);
+      }
+    }
+    const recheck = await detectQmd();
+    if (recheck.available) {
+      await registerQmdCollections(process.cwd(), logger);
     }
   }
 

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/qmd.js

@@ -0,0 +1,86 @@
+// KJC-TSK-0509 — `kj qmd query` CLI wrapper. Auto-resolves the project's QMD
+// collection (`<projectSlug>-<suffix>`) so users do not have to remember it.
+// Mirrors `kj rag query`'s friendly-error shape on missing binary/collection.
+// Distinction: rag = agent context (code+plans); qmd = human wiki (docs/*.md).
+import { runCommand } from "../utils/process.js";
+import { projectSlug } from "../utils/qmd-collection.js";
+
+const QMD_NOT_INSTALLED = /command not found|ENOENT|not recognized as/i;
+const COLLECTION_MISSING = /no such collection|collection .* not found|unknown collection/i;
+const INSTALL_HINT = "qmd not installed. Install it with: npm install -g @tobilu/qmd";
+const INIT_HINT = "Collection not registered for this project. Run `kj init` to register the wiki collection.";
+
+function suffixFor(scope) {
+  if (!scope || scope === "docs") return "docs";
+  if (scope === "reviews" || scope === ".reviews") return "reviews";
+  if (scope === "plans" || scope === ".karajan/plans" || scope === "karajan-plans") return "karajan-plans";
+  return scope;
+}
+
+function resolveCollection({ flags, projectDir }) {
+  if (flags.collection) return String(flags.collection).trim();
+  return `${projectSlug(projectDir)}-${suffixFor(flags.scope)}`;
+}
+
+function notInstalled(logger) {
+  logger.error?.(`[qmd] ${INSTALL_HINT}`);
+  process.exitCode = 127;
+  return { ok: false, error: "qmd not installed", installable: true };
+}
+
+export async function qmdQueryCommand({ text, config, logger, flags = {} }) {
+  if (!text || !String(text).trim()) throw new Error("kj qmd query: text argument required");
+  const projectDir = config?.projectDir || process.cwd();
+  const collection = resolveCollection({ flags, projectDir });
+  const limit = Math.min(Math.max(Number(flags.topK) || 10, 1), 50);
+  const args = ["query", String(text), "--format", "json", "-c", collection, "-n", String(limit)];
+  if (flags.fast) args.push("--no-rerank");
+
+  let out;
+  try {
+    out = await runCommand("qmd", args, { timeout: 120_000 });
+  } catch (err) {
+    if (err?.code === "ENOENT") return notInstalled(logger);
+    throw err;
+  }
+
+  const stderr = out.stderr || "";
+  if (out.exitCode === 127 || QMD_NOT_INSTALLED.test(stderr)) return notInstalled(logger);
+  if (COLLECTION_MISSING.test(stderr)) {
+    logger.error?.(`[qmd] ${INIT_HINT}`);
+    process.exitCode = 1;
+    return { ok: false, error: "collection not registered", collection };
+  }
+  if (out.exitCode !== 0) {
+    const msg = (stderr || out.stdout || `qmd exit ${out.exitCode}`).trim();
+    logger.error?.(`[qmd] ${msg}`);
+    process.exitCode = out.exitCode || 1;
+    return { ok: false, error: msg };
+  }
+
+  let results;
+  try { results = JSON.parse(out.stdout || "[]"); }
+  catch {
+    logger.error?.("[qmd] qmd output is not valid JSON");
+    process.exitCode = 1;
+    return { ok: false, error: "qmd output is not valid JSON" };
+  }
+
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify(results)}\n`);
+    return { ok: true, results };
+  }
+  if (!Array.isArray(results) || results.length === 0) {
+    logger.info(`[qmd] no hits for "${text}" in collection ${collection}`);
+    return { ok: true, results: [] };
+  }
+  logger.info(`[qmd] ${results.length} hit(s) in ${collection}:`);
+  for (const h of results) {
+    const src = h.source || h.path || h.file || "?";
+    const score = typeof h.score === "number" ? ` · score=${h.score.toFixed(4)}` : "";
+    const snippet = h.snippet || h.text || h.body || "";
+    logger.info(`  - ${src}${score}`);
+    if (snippet) logger.info(`    ${snippet.length > 200 ? `${snippet.slice(0, 200)}…` : snippet}`);
+  }
+  return { ok: true, results };
+}

package/src/commands/resume.js

@@ -1,53 +1,10 @@
 import { EventEmitter } from "node:events";
-import readline from "node:readline";
 import { resumeFlow } from "../orchestrator.js";
 import { createActivityLog } from "../activity-log.js";
 import { printEvent } from "../utils/display/event-handlers.js";
 import { withCliRunLog } from "../utils/cli-run-log.js";
 import { registerRun, unregisterRun } from "../utils/run-registry.js";
-
-function createCliAskQuestion(opts = {}) {
-  const { sessionId = null } = opts;
-  return async (question, context) => {
-    // Mirror the run.js logic: route to the board via the file-based
-    // bridge when there's no TTY; otherwise prompt the local terminal.
-    const stdinReadable = process.stdin && process.stdin.readable !== false;
-    const isInteractive = Boolean(process.stdin?.isTTY) && stdinReadable;
-    if (!isInteractive) {
-      const { askThroughBoard } = await import("../utils/board-prompt-bridge.js");
-      console.log(`\n\u2753 ${question}`);
-      if (context?.detail) {
-        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
-      }
-      console.log(
-        "\n[non-interactive] Routing the prompt to the HU Board.\n"
-        + "  Open http://localhost:4000 \u2014 a modal will appear asking for your answer."
-      );
-      try {
-        return await askThroughBoard({ sessionId, question, context });
-      } catch (err) {
-        console.log(`\n[prompt-bridge] ${err.message} \u2014 stopping the session.`);
-        return null;
-      }
-    }
-
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    return new Promise((resolve) => {
-      console.log(`\n\u2753 ${question}`);
-      if (context?.detail) {
-        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
-      }
-      rl.question("\n> Your response (or 'stop' to exit): ", (answer) => {
-        rl.close();
-        if (answer.trim().toLowerCase() === "stop") {
-          resolve(null);
-        } else {
-          resolve(answer.trim());
-        }
-      });
-    });
-  };
-}
+import { createCliAskQuestion } from "../utils/cli-ask-question.js";
 
 export async function resumeCommand({ sessionId, answer, config, logger, flags }) {
   const jsonMode = flags?.json;
@@ -88,7 +45,11 @@ export async function resumeCommand({ sessionId, answer, config, logger, flags }
       }
     });
 
-    const askQuestion = createCliAskQuestion();
+    // KJC-BUG-0081 round 2 — propagate `flags` so the helper honours
+    // `--yes` here too. Before this fix, `kj resume <id> --yes` in
+    // non-TTY mode still routed every prompt to the HU Board bridge
+    // and hung, exactly the bug the original PR #995 fixed for `kj run`.
+    const askQuestion = createCliAskQuestion({ sessionId, flags });
     const result = await resumeFlow({
       sessionId,
       answer: answer || null,

package/src/commands/run.js

@@ -1,5 +1,4 @@
 import { EventEmitter } from "node:events";
-import readline from "node:readline";
 import { runFlow } from "../orchestrator.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { createActivityLog } from "../activity-log.js";
@@ -14,54 +13,11 @@ import { confirmCwd } from "../utils/cwd-confirm.js";
 import { runSpecReview } from "../spec-review/run-spec-review.js";
 import { maybeAutoUpdate } from "../rag/auto-update.js";
 
-function createCliAskQuestion(opts = {}) {
-  const { sessionId = null } = opts;
-  return async (question, context) => {
-    // Two paths:
-    //   - Interactive TTY: prompt via readline (the developer's terminal).
-    //   - No TTY (board's \u25b6 Run plan with stdio=ignore, CI, etc.): publish
-    //     the prompt through the file-based bridge so the HU Board can
-    //     surface it as a modal. The runner blocks on the bridge until
-    //     the user answers (or times out / kills the run). Pre-v2.7.5
-    //     this path just bailed; now the question actually gets answered.
-    const stdinReadable = process.stdin && process.stdin.readable !== false;
-    const isInteractive = Boolean(process.stdin?.isTTY) && stdinReadable;
-    if (!isInteractive) {
-      const { askThroughBoard } = await import("../utils/board-prompt-bridge.js");
-      console.log(`\n\u2753 ${question}`);
-      if (context?.detail) {
-        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
-      }
-      console.log(
-        "\n[non-interactive] Routing the prompt to the HU Board.\n"
-        + "  Open http://localhost:4000 \u2014 a modal will appear asking for your answer.\n"
-        + "  This process is now waiting; closing the board does NOT cancel the run."
-      );
-      try {
-        return await askThroughBoard({ sessionId, question, context });
-      } catch (err) {
-        console.log(`\n[prompt-bridge] ${err.message} \u2014 stopping the session.`);
-        return null;
-      }
-    }
-
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    return new Promise((resolve) => {
-      console.log(`\n\u2753 ${question}`);
-      if (context?.detail) {
-        console.log(`   Context: ${JSON.stringify(context.detail, null, 2)}`);
-      }
-      rl.question("\n> Your response (or 'stop' to exit): ", (answer) => {
-        rl.close();
-        if (answer.trim().toLowerCase() === "stop") {
-          resolve(null);
-        } else {
-          resolve(answer.trim());
-        }
-      });
-    });
-  };
-}
+// Re-export the shared helper so existing imports (tests, MCP wrappers)
+// keep working. KJC-BUG-0081 round 2 split the body into utils/ because
+// resume.js also needs the same contract.
+import { createCliAskQuestion } from "../utils/cli-ask-question.js";
+export { createCliAskQuestion };
 
 export async function runCommandHandler({ task, config, logger, flags }) {
   // PR-F (cwd confirmation): when launching from an interactive
@@ -171,7 +127,7 @@ export async function runCommandHandler({ task, config, logger, flags }) {
       printHeader({ task: task, config });
     }
 
-    const askQuestion = createCliAskQuestion();
+    const askQuestion = createCliAskQuestion({ flags });
 
     // Spec-reviewer pre-pipeline audit (KJC-PCS-0048). Runs BEFORE
     // anything else — surfaces ambiguity / missing scope / missing AC

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/git/hu-snapshot.js

@@ -1,105 +1,10 @@
-// KJC-TSK-0408: snapshots de ficheros por HU para soportar Undo.
-//
-// Antes de ejecutar una HU, guardamos un ref git apuntando al HEAD
-// actual (`refs/kj-snapshots/<huId>`). Si el usuario hace Undo después,
-// hacemos `git reset --hard <ref>` para volver al estado pre-run.
-//
-// Por qué refs en lugar de stash/tarball:
-//   - Refs son objetos git nativos. No mueven blobs (todos compartidos
-//     con HEAD), así que crear el snapshot es O(1).
-//   - El snapshot persiste a través de checkouts y rebases.
-//   - Si el ref ya apunta al SHA correcto, restore es no-op.
-//
-// El runner es inyectable para que los tests no necesiten un repo git real.
-
-import { runCommand } from "../utils/process.js";
-
-const REF_PREFIX = "refs/kj-snapshots/";
-
-/**
- * Sanitiza un huId para uso como nombre de ref. Git rechaza:
- *   - `..`, `:`, `~`, `^`, `?`, `*`, `[`, `\`, espacios, control chars
- *   - segmentos que empiecen por `.` o terminen en `.lock`
- * Reemplazamos cualquier no [a-zA-Z0-9_-] por `_`.
- */
-export function snapshotRefForHu(huId) {
-  if (!huId) throw new Error("huId requerido");
-  const safe = String(huId).replaceAll(/[^a-zA-Z0-9_-]/g, "_").slice(0, 80);
-  return REF_PREFIX + safe;
-}
-
-async function defaultRunner(args, opts = {}) {
-  return runCommand("git", args, opts);
-}
-
-/**
- * Crea (o actualiza) el ref del snapshot apuntando al HEAD actual.
- *
- * @param {object} args
- * @param {string} args.projectDir
- * @param {string} args.huId
- * @param {Function} [args.runner] - sustituye git CLI en tests
- * @returns {Promise<{ ok: boolean, ref?: string, sha?: string, error?: string }>}
- */
-export async function createHuSnapshot({ projectDir, huId, runner }) {
-  const run = runner || defaultRunner;
-  const ref = snapshotRefForHu(huId);
-  const head = await run(["rev-parse", "HEAD"], { cwd: projectDir });
-  if (head.exitCode !== 0) {
-    return { ok: false, error: `rev-parse HEAD failed: ${(head.stderr || "").trim()}` };
-  }
-  const sha = (head.stdout || "").trim();
-  if (!sha) return { ok: false, error: "HEAD vacío" };
-  const update = await run(["update-ref", ref, sha], { cwd: projectDir });
-  if (update.exitCode !== 0) {
-    return { ok: false, error: `update-ref falló: ${(update.stderr || "").trim()}` };
-  }
-  return { ok: true, ref, sha };
-}
-
-/**
- * @param {object} args
- * @param {string} args.projectDir
- * @param {string} args.huId
- * @param {Function} [args.runner]
- * @returns {Promise<{ ok: boolean, sha?: string }>}
- */
-export async function hasHuSnapshot({ projectDir, huId, runner }) {
-  const run = runner || defaultRunner;
-  const ref = snapshotRefForHu(huId);
-  const r = await run(["rev-parse", "--verify", "--quiet", ref], { cwd: projectDir });
-  if (r.exitCode !== 0) return { ok: false };
-  return { ok: true, sha: (r.stdout || "").trim() };
-}
-
-/**
- * Restaura el workspace al snapshot. DESTRUCTIVO: hace `git reset --hard`,
- * lo que descarta cambios no committeados. Caller debe avisar al usuario.
- *
- * @returns {Promise<{ ok: boolean, sha?: string, error?: string }>}
- */
-export async function restoreHuSnapshot({ projectDir, huId, runner }) {
-  const run = runner || defaultRunner;
-  const ref = snapshotRefForHu(huId);
-  const has = await hasHuSnapshot({ projectDir, huId, runner: run });
-  if (!has.ok) return { ok: false, error: `snapshot no encontrado para HU ${huId}` };
-  const r = await run(["reset", "--hard", ref], { cwd: projectDir });
-  if (r.exitCode !== 0) {
-    return { ok: false, error: `reset --hard falló: ${(r.stderr || "").trim()}` };
-  }
-  return { ok: true, sha: has.sha };
-}
-
-/**
- * Borra el ref del snapshot. Idempotente: si no existe, devuelve ok:true.
- */
-export async function removeHuSnapshot({ projectDir, huId, runner }) {
-  const run = runner || defaultRunner;
-  const ref = snapshotRefForHu(huId);
-  const r = await run(["update-ref", "-d", ref], { cwd: projectDir });
-  // git update-ref -d devuelve 0 incluso si el ref no existía.
-  if (r.exitCode !== 0) {
-    return { ok: false, error: `update-ref -d falló: ${(r.stderr || "").trim()}` };
-  }
-  return { ok: true };
-}
+// Shim de compatibilidad: hu-snapshot vive ahora en @karajan/core.
+// Mantenemos esta ruta para que callers internos del CLI (orchestrator,
+// runners) sigan funcionando sin tocar imports.
+export {
+  snapshotRefForHu,
+  createHuSnapshot,
+  hasHuSnapshot,
+  restoreHuSnapshot,
+  removeHuSnapshot,
+} from "@karajan/core/hu-snapshot";