karajan-code 4.41.0 → 4.42.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.41.0",
+  "version": "4.42.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/commands/harden.js

@@ -26,6 +26,7 @@ import { detectStackRoots } from "../harden/stack-roots.js";
 import { installWorkflows } from "../harden/workflow-engine.js";
 import { detectTestFramework } from "../utils/project-detect.js";
 import { ensureIdentity } from "../identity/bootstrap.js";
+import { commitContract, contractChanges } from "../environment/contract-commit.js";
 
 const JS_TEST_CMD = {
   vitest: "npx vitest run",
@@ -104,8 +105,12 @@ export async function hardenCommand({
   exclude = [],
   commitSupervisor = false,
   kjVersion = null,
+  // KJC-BUG-0289: the contract files already dirty before anything was generated
+  // (kj init captures them before writing its own). What is dirty NOW is the person's.
+  contractBefore = null,
   logger = console,
 } = {}) {
+  const dirtyBefore = contractBefore ?? contractChanges(projectDir);
   const repoCfg = readHardenConfig(projectDir);
   const onlyDirs = [...(repoCfg.only ?? []), ...only];
   const excludeDirs = [...(repoCfg.exclude ?? []), ...exclude];
@@ -200,6 +205,15 @@ export async function hardenCommand({
     workflows: wf?.workflows ?? [],
     guidelines: gl?.guidelines ?? [],
   };
+  // KJC-BUG-0289 (#1984): what kj harden generates, kj commits (KJC-BUG-0273's
+  // path): only that, never on the base branch. Left to the agent, 3.2k generated
+  // lines exceeded its own PR size and stayed untracked. The seal (--commit, ADR
+  // 0009) stays a human act over the supervisor alone.
+  if (!dryRun) {
+    out.contract = commitContract({ projectDir, before: dirtyBefore, baseBranch });
+    if (out.contract.committed) logger.info?.(`kj harden: contract committed by kj, ${out.contract.files.length} generated file(s)`);
+    else if (!out.contract.reason.startsWith("nothing")) logger.warn?.(`kj harden: the contract kj generated is NOT committed (${out.contract.reason})`);
+  }
 
   if (json) {
     logger.info?.(JSON.stringify(out));

package/src/commands/init.js

@@ -26,6 +26,7 @@ import { installQmd } from "../utils/qmd-install.js";
 import { registerQmdCollections } from "../utils/qmd-collection.js";
 import { isGitRepo } from "../harden/harden-engine.js";
 import { hardenCommand } from "./harden.js";
+import { contractChanges } from "../environment/contract-commit.js";
 import { detectProjectStack } from "../utils/stack-detect.js";
 import { bootstrapSonarToken } from "../sonar/token-bootstrap.js";
 
@@ -771,6 +772,11 @@ export async function initCommand({ logger, flags = {} }) {
     const toStderr = (...args) => console.error(...args);
     logger = { ...logger, info: toStderr, warn: toStderr, error: toStderr };
   }
+  // KJC-BUG-0289: what is dirty NOW is the person's; kj harden commits only what
+  // init and harden generate below (skills, settings, hooks, configs, guidelines).
+  // Outside a repository (ensureGitRepo runs later) git cannot answer and the
+  // baseline is empty: everything generated afterwards is kj's.
+  const contractBefore = contractChanges(process.cwd());
   const karajanHome = getKarajanHome();
   await ensureDir(karajanHome);
   logger.info(`Ensured ${karajanHome} exists`);
@@ -928,7 +934,7 @@ export async function initCommand({ logger, flags = {} }) {
     logger.info("Quality harness skipped (--no-harden).");
   } else if (ensureGitRepo({ projectDir: process.cwd(), logger })) {
     logger.info("Installing quality harness (kj harden)...");
-    await hardenCommand({ projectDir: process.cwd(), logger });
+    await hardenCommand({ projectDir: process.cwd(), logger, contractBefore });
     hardened = true;
   } else {
     logger.warn("Quality harness NOT installed: this is not a git repository and `git init` failed — Karajan's guarantees live in git hooks. Fix git, then run `kj harden`.");

package/src/environment/contract-commit.js

@@ -8,6 +8,9 @@
  * seal (ADR 0009), which stays a human act.
  */
 import { execFileSync } from "node:child_process";
+import { basename } from "node:path";
+
+import { GENERATED_CONFIG_FILES } from "../harden/config-templates.js";
 
 /** What kj generates and the whole team must inherit by cloning (prefixes). */
 export const CONTRACT_PATHS = [
@@ -23,13 +26,20 @@ export const CONTRACT_PATHS = [
   "GEMINI.md",
   // KJC-TSK-0879: in a Rulesync repo kj's rules live in .rulesync/rules/karajan.md.
   ".rulesync/",
+  // KJC-BUG-0289 (#1984): the governance the whole team inherits (ADR 0016, KJC-BUG-0269).
+  ".karajan/rules.yml",
+  ".karajan/policy-anchor.json",
+  ".karajan/supervisor-signers.json",
 ];
 
 const FRESH_MESSAGE = "chore(bootstrap): el contrato del método, para que quien clone lo herede";
 const REGEN_MESSAGE = "chore(kj): el contrato del método, generado por kj";
 
 const runner = (projectDir, env) => (args) => execFileSync("git", ["-C", projectDir, ...args], { encoding: "utf8", env, stdio: ["ignore", "pipe", "pipe"] });
-const isContract = (file) => CONTRACT_PATHS.some((p) => (p.endsWith("/") || p.endsWith("-") ? file.startsWith(p) : file === p));
+// KJC-BUG-0289: the lint/format/commit configs harden generates sit at the root
+// or under a stack root (a fullstack monorepo is hardened on every side).
+const isContract = (file) =>
+  CONTRACT_PATHS.some((p) => (p.endsWith("/") || p.endsWith("-") ? file.startsWith(p) : file === p)) || GENERATED_CONFIG_FILES.has(basename(file));
 
 /** The contract files git sees as changed, with their porcelain code (`??` untracked). */
 function contractStatus(git) {

package/src/git/coder-commit-guard.js

@@ -0,0 +1,40 @@
+/**
+ * KJC-BUG-0285 (#1982): the coder commits nothing; the pipeline does, once the
+ * review approves. With --auto-commit the coder ran git commit inside its
+ * iteration, before the reviewer, and the rejected commit stayed on the branch.
+ * The stage reads HEAD before the coder runs and, when HEAD moved on top of it,
+ * undoes those commits SOFTLY: the changes stay in the tree and the index for
+ * the review. A rewritten branch (HEAD no longer descends from the start) is
+ * left alone. Plain git, no injected runner: it never throws, it says.
+ */
+import { spawnSync } from "node:child_process";
+
+const git = (args, cwd) => spawnSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+
+/** @returns {string|null} the sha HEAD points at, or null outside a repo with commits */
+export function headSha(cwd = process.cwd()) {
+  try {
+    const res = git(["rev-parse", "HEAD"], cwd);
+    return res.status === 0 ? res.stdout.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** @returns {{undone: number, reason?: string}} */
+export function undoCommitsSince(sha, cwd = process.cwd()) {
+  if (!sha) return { undone: 0, reason: "no starting commit" };
+  try {
+    const head = headSha(cwd);
+    if (!head || head === sha) return { undone: 0 };
+    if (git(["merge-base", "--is-ancestor", sha, "HEAD"], cwd).status !== 0) {
+      return { undone: 0, reason: "HEAD no longer descends from the iteration's start" };
+    }
+    const undone = Number(git(["rev-list", "--count", `${sha}..HEAD`], cwd).stdout.trim());
+    const reset = git(["reset", "--soft", sha], cwd);
+    if (reset.status !== 0) return { undone: 0, reason: `git reset --soft failed: ${reset.stderr.trim()}` };
+    return { undone };
+  } catch (err) {
+    return { undone: 0, reason: err.message };
+  }
+}

package/src/harden/sentinel/sentinel-shell.mjs

@@ -64,10 +64,14 @@ export const headIndex = (words, heads) => {
   return k < 0 ? words.length : i + k;
 };
 
+// KJC-BUG-0286: a $ expands only when something expandable follows it ($x, ${x},
+// $(cmd), $1, $@...). A lone "$ " in a grep pattern is a literal dollar sign.
+const LIVE_EXPANSION = /\$(?=[A-Za-z0-9_{(@*#?$!-])|`/;
+
 /**
  * KJC-BUG-0243: blank the quoted text that cannot run: single-quoted spans, and
- * double-quoted spans with no $ or backtick. What remains is what the shell can
- * still expand or execute, so operator and substitution checks read only that.
+ * double-quoted spans with no live $ or backtick. What remains is what the shell
+ * can still expand or execute, so operator and substitution checks read only that.
  * @param {string} cmd
  */
 export const stripInertQuotes = (cmd) => {
@@ -79,7 +83,7 @@ export const stripInertQuotes = (cmd) => {
     while (j < cmd.length && cmd[j] !== q) j += q === '"' && cmd[j] === "\\" ? 2 : 1;
     if (j >= cmd.length) return out + cmd.slice(i); // unclosed: left as is, for the caller to deny
     const body = cmd.slice(i + 1, j);
-    out += q === "'" || !/[$`]/.test(body) ? q + q : q + body + q;
+    out += q === "'" || !LIVE_EXPANSION.test(body) ? q + q : q + body + q;
     i = j;
   }
   return out;

package/src/harden/sentinel-hooks.js

@@ -135,7 +135,8 @@ const POST_BODY = `#!/usr/bin/env node
 // a tool call (PostToolUse, always exit 0).
 import console from "node:console";
 import process from "node:process";
-import { relative } from "node:path";
+import { realpathSync } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
 import { spawnSync } from "node:child_process";
 import { CODE, TESTS, ROOT, CARD, branchOf, load, save, session } from "./sentinel-lib.mjs";
 import { remindersFor } from "./sentinel-reminders.mjs";
@@ -170,20 +171,37 @@ process.stdin.on("end", () => {
     // every question with silence, so the gate would demand what no query can
     // deliver. kj says so explicitly, in both its human and json forms.
     const EMPTY_INDEX = /No chunks indexed yet|"empty"\\s*:\\s*true/;
+    // KJC-BUG-0293 (#1996, #1995): the index names its sources through whatever
+    // spelling of the project directory indexed them (a symlinked workspace, an
+    // alias). Compared as TEXT against the harness root, every hit fell outside
+    // the tree and was dropped in silence: rag_hits stayed empty and only new
+    // files passed. Both sides are compared by REAL path, and what still falls
+    // outside is written down for the gate to name.
+    // A path whose file is gone (or not yet there) resolves through its deepest
+    // existing ancestor, so an alias of the directory still lands in the tree.
+    const realOf = (p) => {
+      try { return realpathSync(p); } catch { /* resolve the parent instead */ }
+      const d = dirname(p);
+      return !d || d === p ? p : join(realOf(d), basename(p));
+    };
+    const ROOT_REAL = realOf(ROOT);
     const recordRag = (query, sources, answer = "") => {
       const state = load();
       const s = session(state, sid);
       s.at = Date.now();
       if (EMPTY_INDEX.test(String(answer))) s.rag_index_empty = true;
       const hits = [];
+      const dropped = [];
       for (const src of sources) {
-        const rel = relative(ROOT, String(src)).split(String.fromCharCode(92)).join("/");
-        if (!rel || rel.startsWith("..") || rel.startsWith("/") || hits.includes(rel)) continue;
-        hits.push(rel);
+        const rel = relative(ROOT_REAL, realOf(String(src))).split(String.fromCharCode(92)).join("/");
+        if (!rel || rel === ".." || rel.startsWith("../") || rel.startsWith("/")) { dropped.push(String(src)); continue; }
+        if (!hits.includes(rel)) hits.push(rel);
       }
       (s.rag_queries ||= []).push({ ts: Date.now(), text: String(query || "").slice(0, 200), hits });
       const all = (s.rag_hits ||= []);
       for (const h of hits) if (!all.includes(h)) all.push(h);
+      if (hits.length === 0 && dropped.length > 0) s.rag_dropped = { root: ROOT_REAL, count: dropped.length, sample: dropped.slice(0, 3) };
+      else if (hits.length > 0) delete s.rag_dropped; // an answer inside the tree ends the diagnosis
       save(state);
     };
     // Sources are read STRUCTURALLY, never through the stringified response:
@@ -195,7 +213,9 @@ process.stdin.on("end", () => {
     };
     const parseJson = (t) => { try { return JSON.parse(t); } catch { return null; } };
     if (/__kj_rag_query$/.test(String(tool)) && /^mcp__/.test(String(tool))) {
-      const parts = Array.isArray(response?.content) ? response.content : [];
+      // KJC-BUG-0293: the host may hand the answer as {content:[parts]}, as the
+      // bare array of parts, or as the text itself; all three are the same answer.
+      const parts = Array.isArray(response?.content) ? response.content : Array.isArray(response) ? response : [{ text: typeof response === "string" ? response : "" }];
       recordRag(input.text, parts.flatMap((p) => sourcesOf(parseJson(String(p?.text || "")))), parts.map((p) => String(p?.text || "")).join(String.fromCharCode(10)));
       process.exit(0);
     }
@@ -292,7 +312,9 @@ process.stdin.on("end", () => {
     const s = session(state, sid);
     s.at = Date.now();
     const rel = relative(ROOT, file).replaceAll("\\\\", "/");
-    const bucket = TESTS.test(rel) ? s.edited_tests : CODE.test(rel) ? s.edited_sources : null;
+    // KJC-BUG-0279 (#1981): a file outside the repository is not one of its sources.
+    const inside = rel && rel !== ".." && !rel.startsWith("../") && !rel.startsWith("/");
+    const bucket = !inside ? null : TESTS.test(rel) ? s.edited_tests : CODE.test(rel) ? s.edited_sources : null;
     if (bucket && !bucket.includes(rel)) bucket.push(rel);
     // KJC-TSK-0910: the branch size while it is written, with the CI budget
     // (kj pr-size), said once per threshold crossed. Context, never a block.
@@ -747,8 +769,15 @@ process.stdin.on("end", () => {
       // (find fuera: -delete/-exec mutan — reviewer catch; sus tokens de
       // carril los caza el escaner de abajo.)
       const READONLY = /^[ \\t]*(grep|rg|cat|head|tail|less|ls|wc|diff|stat|file|du|tree|git (log|show|diff|status|blame))\\b[^;|&<>$\`(){}\\n\\r]*$/;
+      // KJC-BUG-0286 (#1982): a command whose EVERY segment only reads mutates
+      // nothing, however it is chained (grep | grep, git show | grep, cd && git
+      // status). A cd with a literal target is one such segment: the paths after
+      // it need no verifying when nothing after it writes. One mutating segment
+      // and the whole command is judged below, as before.
+      const CD_LITERAL = /^[ \\t]*(cd|pushd)([ \\t]+[^ \\t;|&<>$\`(){}\\n\\r]*)?[ \\t]*$/;
+      const readsOnly = (s) => s.split(/&&|\\|\\||[;|]/).every((seg) => READONLY.test(seg) || CD_LITERAL.test(seg));
       // KJC-BUG-0243: operators inside inert quotes (grep -e "a|b") do not chain anything.
-      if (!READONLY.test(stripInertQuotes(cmd))) {
+      if (!readsOnly(stripInertQuotes(cmd))) {
         // cd/pushd invalida TODO razonamiento textual de rutas posteriores
         // (carrera de bypasses confirmada en review: destino bare, con $,
         // relativas post-cd...): en un comando NO-read-only, cambiar de
@@ -960,7 +989,8 @@ process.stdin.on("end", () => {
       } catch { /* no report or unreadable — the Steward is not adopted here */ }
       const file = input.file_path || input.notebook_path;
       const rel = file ? relative(ROOT, String(file)).replaceAll("\\\\", "/") : "";
-      if (rel && CODE.test(rel) && !TESTS.test(rel)) {
+      // KJC-BUG-0279 (#1981): outside the repository there is no source to govern.
+      if (rel && rel !== ".." && !rel.startsWith("../") && !rel.startsWith("/") && CODE.test(rel) && !TESTS.test(rel)) {
         const branch = branchOf();
         const why = !branch ? null : BASE_BRANCHES.has(branch) ? "base" : !CARD.test(branch) ? "nocard" : null;
         // ADR 0015 (KJC-TSK-0925): no escape. Without a card there is no work.
@@ -1017,7 +1047,13 @@ process.stdin.on("end", () => {
               console.error("karajan sentinel: rag-first — el indice aun no tiene " + rel + " (" + absent + "); indexalo y consulta despues: kj_rag_query / kj rag query <que hace " + rel + ">" + doc("rag-first"));
               process.exit(2);
             } else {
-              console.error("karajan sentinel: rag-first — el RAG no ha respondido sobre " + rel + " en esta sesion; consulta antes de tocarlo: kj_rag_query / kj rag query <que hace " + rel + " y donde mas vive ese concepto>." + doc("rag-first"));
+              // KJC-BUG-0293 (#1996): hits that fell outside the tree are named, so the
+              // person learns the index was built from another path instead of querying again.
+              const dropped = rs.rag_dropped;
+              const outside = dropped?.count
+                ? " La ultima consulta devolvio " + dropped.count + " hit(s) fuera de este arbol (" + dropped.root + "): " + (dropped.sample || []).join(", ") + " — el indice se construyo desde otra ruta; reindexa desde esta: kj rag index --with-sources."
+                : "";
+              console.error("karajan sentinel: rag-first — el RAG no ha respondido sobre " + rel + " en esta sesion; consulta antes de tocarlo: kj_rag_query / kj rag query <que hace " + rel + " y donde mas vive ese concepto>." + outside + doc("rag-first"));
               process.exit(2);
             }
           }
@@ -1034,7 +1070,10 @@ process.stdin.on("end", () => {
       // bandera no puede apagar el gate de commit, y mover core.hooksPath lo
       // apaga entero. El --no-verify que kj harden --commit usa por dentro no
       // pasa por aqui: no es una tool call. Escape humano, sellado como el resto.
-      const words = wordsOf(cmd);
+      // KJC-BUG-0286 (#1982): judged on the git commit SEGMENT alone, read by the
+      // shell reader: a "commit" inside a grep pattern piped after git show, or
+      // the -n of a grep in the same pipeline, is not a skipped hook.
+      const commitSegments = shellSegments(cmd).map((ws) => ws.map((w) => w.slice(w.lastIndexOf("/") + 1))).filter((ws) => inOrder(["git", "commit"], ws));
       // git acepta abreviaturas no ambiguas de las opciones largas, asi que
       // --no-ver salta el hook igual que --no-verify (catch de la review).
       const shortWithN = (w) => w.length > 1 && w[0] === "-" && w[1] !== "-" && w.includes("n");
@@ -1051,7 +1090,7 @@ process.stdin.on("end", () => {
       // --config-env=core.hooksPath=VAR) y una propiedad de seguridad no puede
       // depender de como parta las palabras el separador (catch de la review).
       const movesHooks = cmd.toLowerCase().includes("core.hookspath");
-      if ((inOrder(["git", "commit"], words) && words.some(skipsVerify)) || movesHooks) {
+      if (commitSegments.some((ws) => ws.some(skipsVerify)) || movesHooks) {
         // ADR 0015 (KJC-TSK-0926): no escape. A broken hook is fixed; skipping it,
         // if it ever must happen, is the user's act in their own terminal.
         console.error("karajan sentinel: el gate de commit no se apaga con una bandera — el review cruzado y la policy corren en el hook, y saltarselos deja el diff sin veredicto. Si el hook esta roto, arreglalo; si de verdad hace falta saltarlo, lo hace tu usuario en su terminal." + doc("escapes"));

package/src/orchestrator/preflight-checks.js

@@ -409,8 +409,8 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
 /**
  * Run the doctor-style complementary checks and merge their outcomes into
  * the existing preflight result shape. Runs with yes:true (non-interactive)
- * and auto-remediation enabled. FAIL/TIMEOUT are appended to errors (blocking),
- * WARN are appended to warnings (non-blocking), FIXED status is recorded as a
+ * and auto-remediation enabled. FAIL is appended to errors (blocking), WARN and
+ * TIMEOUT to warnings (non-blocking: a timeout is "not checked"), FIXED status is recorded as a
  * remediation, and runtime overrides from auto-fixes are merged into
  * configOverrides.
  */
@@ -437,11 +437,12 @@ async function runExtendedPreflight({ config, result, emitter, eventBase, logger
 
   for (const c of report.checks) {
     result.checks.push({ name: c.name, ok: c.status === STATUS.OK || c.status === STATUS.FIXED || c.status === STATUS.SKIPPED, detail: c.detail });
-    const eventStatus = c.status === STATUS.FAIL || c.status === STATUS.TIMEOUT
-      ? "fail"
-      : c.status === STATUS.WARN
-        ? "warn"
-        : "ok";
+    // KJC-BUG-0287 (#1982): a timeout is "not checked", never "broken". GitHub
+    // unreachable for the SHA-pinned actions blocked a docs-only run that needed
+    // no network at all; the runner itself calls TIMEOUT warn-level.
+    let eventStatus = "ok";
+    if (c.status === STATUS.FAIL) eventStatus = "fail";
+    else if (c.status === STATUS.WARN || c.status === STATUS.TIMEOUT) eventStatus = "warn";
     emitProgress(emitter, makeEvent("preflight:check", { ...eventBase, stage: "preflight" }, {
       status: eventStatus,
       message: `${c.label}: ${c.detail}`,
@@ -449,9 +450,11 @@ async function runExtendedPreflight({ config, result, emitter, eventBase, logger
     }));
     if (c.status === STATUS.FIXED) {
       result.remediations.push(`${c.label}: ${c.detail}`);
-    } else if (c.status === STATUS.FAIL || c.status === STATUS.TIMEOUT) {
+    } else if (c.status === STATUS.FAIL) {
       result.ok = false;
       result.errors.push({ check: c.name, message: `${c.label}: ${c.detail}`, fix: c.fix });
+    } else if (c.status === STATUS.TIMEOUT) {
+      result.warnings.push(`${c.label}: not checked, it did not answer in time (${c.detail}); the run goes on`);
     } else if (c.status === STATUS.WARN) {
       result.warnings.push(`${c.label}: ${c.detail}`);
     }

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

@@ -17,6 +17,7 @@ import { emitProgress, makeEvent, emitAgentOutput } from "../../utils/events.js"
 import { runCoderWithFallback } from "../agent-fallback.js";
 import { invokeSolomon } from "../solomon-escalation.js";
 import { detectRateLimit } from "../../utils/rate-limit-detector.js";
+import { headSha, undoCommitsSince } from "../../git/coder-commit-guard.js";
 import { createStallDetector } from "../../utils/stall-detector.js";
 import { buildStandbyState } from "../../brain/standby-store.js";
 import { applyQuotaSimulation } from "../../utils/quota-simulator.js";
@@ -54,6 +55,10 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
   // Claude run `cd /home/manu/assistant && pnpm init …` and 36 MB
   // of code landed outside projectDir, outside any git repo.
   const homeSnapshotBeforeCoder = snapshotHomeTopLevel();
+  // KJC-BUG-0285 (#1982): where HEAD stands before the coder runs. The coder
+  // commits nothing; the pipeline does, once the review approves.
+  const stageDir = config?.projectDir || process.cwd();
+  const headBefore = headSha(stageDir);
   let coderExecResult;
   try {
     coderExecResult = await coderRoleInstance.execute({
@@ -84,6 +89,17 @@ export async function runCoderStage({ coderRoleInstance, coderRole, config, logg
   }
   trackBudget({ role: "coder", provider: coderRole.provider, model: coderRole.model, result: coderExecResult.result, duration_ms: Date.now() - coderStart });
   applyQuotaSimulation(coderExecResult, { iteration, agent: coderRole.provider });
+  // KJC-BUG-0285 (#1982): a commit the coder made on its own carried the error the
+  // reviewer then rejected, and stayed on the branch. Undone softly: the changes
+  // stay in the tree for the review; the pipeline commits what it approves.
+  if (headBefore) {
+    const undone = undoCommitsSince(headBefore, stageDir);
+    if (undone.undone > 0) {
+      const message = `Coder committed on its own (${undone.undone} commit(s)); undone softly, the changes stay in the tree: the pipeline commits once the review approves`;
+      logger.warn(message);
+      emitProgress(emitter, makeEvent("coder:commit-undone", { ...eventBase, stage: "coder" }, { message, detail: { commits: undone.undone, headBefore } }));
+    }
+  }
 
   if (!coderExecResult.ok) {
     const details = coderExecResult.result?.error || coderExecResult.summary || "unknown error";

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

@@ -335,18 +335,20 @@ export async function runReviewerStage({ reviewerRole, config, logger, emitter,
       confidence: reviewResult.confidence ?? 0
     });
   } catch (error_) {
+    // KJC-BUG-0284 (#1982): a verdict kj cannot read is the reviewer's failure,
+    // never a PARSE_ERROR defect handed to the coder (it sent one run in circles).
+    const details = `the verdict could not be read: ${error_.message}`;
     logger.warn(`Reviewer output validation failed: ${error_.message}`);
-    review = {
-      approved: false,
-      blocking_issues: [{
-        id: "PARSE_ERROR",
-        severity: "high",
-        description: `Reviewer output could not be parsed: ${error_.message}`
-      }],
-      non_blocking_suggestions: [],
-      summary: `Parse error: ${error_.message}`,
-      confidence: 0
-    };
+    await markSessionStatus(session, "failed");
+    emitProgress(
+      emitter,
+      makeEvent("reviewer:end", { ...eventBase, stage: "reviewer" }, {
+        status: "fail",
+        message: `Reviewer failed: ${details}`,
+        detail: { provider: reviewerRole.provider, executorType: "agent" }
+      })
+    );
+    throw new Error(`Reviewer failed: ${details}`, { cause: error_ });
   }
   // --- Scope filter: auto-defer out-of-scope blocking issues ---
   const { review: filteredReview, demoted, deferred, allDemoted } = filterReviewScope(review, diff);

package/src/prompts/coder.js

@@ -251,7 +251,9 @@ export async function buildCoderPromptLayout({ task, reviewerFeedback = null, so
     // .gitignore, a rogue verify worktree). Anchor the scope hard.
     section("SCOPE: this is an EXISTING project. Implement ONLY the current HU against the code already here. NEVER scaffold, bootstrap or initialize project structure, never add a generic multi-stack .gitignore, and never create git worktrees (`git worktree add`) — your workspace is already prepared. If a step ever reads like 'set up the project', treat it as a misread of an existing repo: re-read the HU and make the real change.", STABLE),
     section("Follow SOLID principles. Write small, focused functions (< 30 lines).", STABLE),
-    section("Make atomic commits: 1 logical change = 1 commit. Keep PRs small and reviewable.", STABLE),
+    // KJC-BUG-0285 (#1982): "atomic commits" read as "commit": the coder committed
+    // before the review and the rejected commit stayed on the branch.
+    section("One logical change per task; keep it small and reviewable. NEVER run git commit, git push or open a PR: the pipeline commits once the cross-AI review approves.", STABLE),
     section("Security: validate all input, parameterize queries, never expose secrets. Use the auth pattern that matches the stack (e.g. httpOnly cookies for web sessions).", STABLE),
     section("Use the project's standard logger and type system (no console.log when a structured logger exists; use the project's type idiom — TS types, JSDoc, Python type hints, Go interfaces…).", STABLE),
     section(SUBPROCESS_CONSTRAINTS, STABLE),

package/src/rag/indexer.js

@@ -11,7 +11,7 @@ import { createHash } from "node:crypto";
 import { execa } from "execa";
 
 import { chunkMarkdown, chunkPlan, chunkSource } from "./chunker.js";
-import { insertChunk, deleteChunksBySource, findChunkByHash } from "./vec-store.js";
+import { insertChunk, deleteChunksBySource, findChunkByHash, getEmbeddingsByIds } from "./vec-store.js";
 import { detectAdaptersForProject, getAllCodeExtensions } from "../lang/registry.js";
 import { indexableReason, listProjectFiles } from "./indexable.js";
 
@@ -71,15 +71,17 @@ export async function indexFile(path, { db, embedder, logger = console, project
   let skipped = 0;
   for (const ch of chunks) {
     // KJC-TSK-0484 — Skip re-embedding identical bodies for the same project.
-    // The chunks row is still rewritten under the new source so deletions of
-    // an alias don't orphan a row whose owner was the dedup target.
+    // KJC-BUG-0281 (#1980): the row is STILL written under the new source, with
+    // the stored vector: a file whose every chunk duplicates another (CLAUDE.md
+    // next to the AGENTS.md kj harden writes) was left with no rows at all, and
+    // the coverage check reported it missing after every reindex.
     const contentHash = createHash("sha256").update(ch.text).digest("hex");
     try {
       const dup = findChunkByHash(db, contentHash, project);
-      if (dup) { skipped += 1; continue; }
-      const embedding = await embedder.embed(ch.text);
+      const stored = dup ? getEmbeddingsByIds(db, [dup.id]).get(Number(dup.id)) : null;
+      const embedding = stored ?? await embedder.embed(ch.text);
       insertChunk(db, { source: path, kind: ch.metadata.kind || kind, text: ch.text, metadata: ch.metadata, embedding, project, contentHash });
-      indexed += 1;
+      if (stored) skipped += 1; else indexed += 1;
     } catch (err) {
       failed += 1;
       logger.warn?.(`[rag-indexer] embed failed for ${path} (${chunkLabel(ch)}): ${err.message}`);

package/src/roles/reviewer-role.js

@@ -1,6 +1,9 @@
+import { createHash } from "node:crypto";
+
 import { AgentRole } from "./agent-role.js";
 import { buildRtkInstructions } from "../prompts/rtk-snippet.js";
 import { extractFirstJson } from "../utils/json-extract.js";
+import { reportUnparseableVerdict } from "../review/unparseable-verdict.js";
 import { section, buildPromptLayout, joinLayout, STABLE, VOLATILE } from "../prompts/prompt-layout.js";
 import { clipDiff } from "../prompts/diff-clip.js";
 import { buildSplitSignal } from "../prompts/split-signal.js";
@@ -66,7 +69,13 @@ export class ReviewerRole extends AgentRole {
   parseOutput(raw) {
     const parsed = extractFirstJson(raw);
     if (!parsed) throw new Error("Failed to parse reviewer output: no JSON found");
-    return parsed;
+    // KJC-BUG-0284 (#1982): a reviewer wrapped its verdict in the role envelope
+    // {ok, result: {approved…}, summary}; the envelope is not the verdict.
+    const verdict = typeof parsed.approved !== "boolean" && typeof parsed.result?.approved === "boolean"
+      ? { ...parsed.result, summary: parsed.result.summary ?? parsed.summary }
+      : parsed;
+    if (typeof verdict.approved !== "boolean") throw new Error("Failed to parse reviewer output: no boolean approved");
+    return verdict;
   }
 
   buildSuccessResult(parsed, provider, agentResult) {
@@ -87,18 +96,20 @@ export class ReviewerRole extends AgentRole {
       : `Rejected: ${blockingIssues.length} blocking issue(s) — ${parsed.summary || ""}`;
   }
 
-  handleParseError(err, agentResult, _provider) {
+  // KJC-BUG-0284 (#1982): an unreadable answer is the reviewer's failure, not
+  // the coder's. Returned as ok=false so the retry and the fallback reviewer
+  // engage (reviewer-fallback.js); the raw answer is saved for inspection.
+  // Before, it came back as a PARSE_ERROR rejection: the coder read it as a
+  // defect of its code and one run went in circles for twenty minutes.
+  async handleParseError(err, agentResult, provider) {
+    const output = agentResult?.output;
+    const hash = createHash("sha256").update(String(output ?? "")).digest("hex").slice(0, 12);
+    const error = await reportUnparseableVerdict({ projectDir: this.config?.projectDir ?? process.cwd(), reviewer: provider, output, hash });
     return {
-      ok: true,
-      result: {
-        ...agentResult,
-        approved: false,
-        blocking_issues: [{ id: "PARSE_ERROR", severity: "high", description: `Reviewer output could not be parsed: ${err.message}` }],
-        non_blocking_suggestions: [],
-        confidence: 0,
-        raw_summary: `Parse error: ${err.message}`
-      },
-      summary: `Reviewer output parse error: ${err.message}`
+      ok: false,
+      result: { ...agentResult, error: `${err.message}\n${error}`, provider },
+      summary: `Reviewer output parse error: ${err.message}`,
+      usage: agentResult?.usage
     };
   }
 }

package/src/sonar/scanner.js

@@ -240,7 +240,12 @@ export function respectRepoProperties(scanner = {}, props = {}) {
   return kept;
 }
 
-/** @returns {Promise<{existed: boolean, declaredKey: string|null}>} */
+// KJC-BUG-0280 (#1979): the scanner aborts, with a stack trace, on a declared
+// folder that does not exist. Only the folders the repo HAS are declared.
+const SOURCE_DIRS = ["src", "lib", "app"];
+const TEST_DIRS = ["tests", "test"];
+
+/** @returns {Promise<{existed: boolean, declaredKey: string|null, written?: boolean, note?: string, nothingToScan?: string}>} */
 export async function ensureSonarProjectProperties(cwd = process.cwd()) {
   const propsPath = path.join(cwd, "sonar-project.properties");
   try {
@@ -257,17 +262,26 @@ export async function ensureSonarProjectProperties(cwd = process.cwd()) {
     } catch {
       // no package.json or invalid JSON — use defaults
     }
+    const existing = (dirs) => dirs.filter((d) => fs.existsSync(path.join(cwd, d)));
+    const sources = existing(SOURCE_DIRS);
+    const tests = existing(TEST_DIRS);
+    if (sources.length === 0) {
+      const wanted = SOURCE_DIRS.map((d) => `${d}/`).join(", ");
+      return { existed: false, declaredKey: null, written: false, nothingToScan: `no ${wanted} folder to analyse: write a sonar-project.properties declaring sonar.sources when the code arrives` };
+    }
     const projectKey = (pkg.name || path.basename(cwd)).replaceAll(/[^a-zA-Z0-9_.-]/g, "_");
+    const layout = [`sonar.sources=${sources.join(",")}`, ...(tests.length ? [`sonar.tests=${tests.join(",")}`] : [])];
     const props = [
       `sonar.projectKey=${projectKey}`,
       `sonar.projectName=${pkg.name || path.basename(cwd)}`,
-      `sonar.sources=src`,
-      `sonar.tests=tests`,
+      ...layout,
       `sonar.javascript.lcov.reportPaths=coverage/lcov.info`,
       `sonar.exclusions=**/node_modules/**,**/dist/**,**/build/**,**/coverage/**`,
     ].join("\n");
     await fsPromises.writeFile(propsPath, props + "\n", "utf8");
-    return { existed: false, declaredKey: null };
+    // Said out loud: the file is new in the working tree and the team should see it.
+    const note = `sonar: wrote sonar-project.properties (${layout.join(", ")}): review it and commit it`;
+    return { existed: false, declaredKey: null, written: true, note };
   }
 }
 
@@ -277,6 +291,9 @@ export async function runSonarScan(config, projectKey = null, { verbose = false,
   // directory under the key its properties declare — so the proof of
   // coverage is about that package, not the root's `sonar.sources`.
   const repoProps = await ensureSonarProjectProperties(scanCwd);
+  if (repoProps.nothingToScan) {
+    return { ok: false, skipped: true, projectKey: null, stdout: "", stderr: `sonar: ${repoProps.nothingToScan}`, exitCode: 0 };
+  }
   let effectiveProjectKey;
   if (cwd && !projectKey && repoProps.declaredKey) {
     effectiveProjectKey = repoProps.declaredKey;
@@ -403,7 +420,7 @@ export async function runSonarScan(config, projectKey = null, { verbose = false,
     projectKey: effectiveProjectKey,
     cwd: scanCwd,
     scanner: pick.type,
-    note: [note, analysisNote].filter(Boolean).join("; ") || null,
+    note: [repoProps.note, note, analysisNote].filter(Boolean).join("; ") || null,
     stdout: result.stdout,
     // A scan that failed on the server's side says so, not with the scanner's own log.
     stderr: !ok && result.exitCode === 0 ? analysisNote : result.stderr,

package/src/utils/run-log.js

@@ -267,6 +267,14 @@ export function readRunLog(projectDir, maxLines = 50) {
     const total = lines.length;
     const shown = lines.slice(-maxLines);
     const status = parseRunStatus(lines);
+    // KJC-BUG-0288 (#1982): a run that died with its host session never logs
+    // "finished", so the log said "running" forever. The lock names the run's
+    // process (KJC-BUG-0250): no live holder, no run.
+    if (status.isRunning && !isPidAlive(readLock(path.join(resolveLogDir(projectDir), LOCK_FILENAME))?.pid)) {
+      status.isRunning = false;
+      status.died = true;
+      status.note = "the run's process is gone (it died with its host session, or was killed): kj resume continues it";
+    }
     const MAX_LINE_CHARS = 2000;
     const truncated = shown.map(l => l.length > MAX_LINE_CHARS ? l.slice(0, MAX_LINE_CHARS) + "… [truncated]" : l);
     return {

package/templates/coder-rules.md

@@ -5,7 +5,7 @@
 - NEVER overwrite existing files entirely. Always make targeted, minimal edits.
 - When adding new code to an existing file, insert only the new lines at the correct location.
 - After each edit, verify with `git diff` that ONLY the intended lines changed.
-- If unintended changes are detected, revert immediately with `git checkout -- <file>`.
+- If unintended changes are detected, undo ONLY those hunks with a targeted edit. Never revert the whole file: it may hold edits that are not yours.
 - Pay special attention to CSS, HTML, and config files where full rewrites destroy prior work (brand colors, layouts, styles).
 
 ## Multi-agent / multi-developer environment

package/templates/roles/coder/anthropic.md

@@ -44,13 +44,13 @@ An incomplete implementation is worse than an error — never report success if
 <file_safety>
 - NEVER overwrite a file wholesale. Make targeted edits only.
 - After each edit, inspect `git diff` to confirm only the intended lines changed.
-- If unintended changes appear, revert immediately with `git checkout -- <file>`.
+- If unintended changes appear, undo ONLY those hunks with a targeted edit. Never revert the whole file: it may hold edits that are not yours.
 - CSS, HTML, config files are especially high-risk for full-rewrite damage.
 </file_safety>
 
 <quality>
 - SOLID principles. Functions < 30 lines, single responsibility.
-- Atomic commits: 1 logical change = 1 commit.
+- One logical change per task. NEVER run git commit or git push: the pipeline commits once the review approves.
 - No `console.log` in production — use a structured logger.
 - No `any` types — use JSDoc `@typedef` / `@param` / `@returns`.
 </quality>

package/templates/roles/coder/default.md

@@ -42,13 +42,13 @@ Before reporting done, verify that ALL parts of the task are addressed:
 - NEVER overwrite existing files entirely. Always make targeted, minimal edits.
 - When adding new code to an existing file, insert only the new lines at the correct location.
 - After each edit, verify with `git diff` that ONLY the intended lines changed.
-- If unintended changes are detected, revert immediately with `git checkout -- <file>`.
+- If unintended changes are detected, undo ONLY those hunks with a targeted edit. Never revert the whole file: it may hold edits that are not yours.
 - Pay special attention to CSS, HTML, and config files where full rewrites destroy prior work.
 
 ## Code Quality Rules
 
 - Follow SOLID principles. Write small, focused functions (< 30 lines).
-- Make atomic commits: 1 logical change = 1 commit. Keep PRs small and reviewable.
+- One logical change per task; keep it small and reviewable. NEVER run git commit or git push: the pipeline commits once the review approves.
 - Security: use httpOnly cookies for auth tokens, validate all input, parameterize queries, never expose secrets.
 - No console.log in production code -- use a structured logger. No 'any' types -- use JSDoc annotations.
 

package/templates/roles/coder/google.md

@@ -56,11 +56,11 @@ An incomplete implementation is worse than an error — don't claim success if p
 ## File safety
 
 - NEVER overwrite a file entirely. Targeted edits only.
-- Verify each edit with `git diff`. Unintended lines → revert with `git checkout -- <file>`.
+- Verify each edit with `git diff`. Unintended lines → undo only those hunks, never the whole file (it may hold edits that are not yours).
 
 ## Quality
 
-- SOLID. Small functions (< 30 lines). Atomic commits. No `console.log` in production, no `any` types (JSDoc instead).
+- SOLID. Small functions (< 30 lines). Never commit or push (the pipeline commits after review). No `console.log` in production, no `any` types (JSDoc instead).
 
 ## Output
 

package/templates/roles/coder/openai.md

@@ -32,13 +32,13 @@ An incomplete implementation is worse than an error. Do NOT claim success if any
 
 - NEVER overwrite a file wholesale. Make targeted edits.
 - Verify after each edit with `git diff` that ONLY intended lines changed.
-- If unintended changes appear, revert with `git checkout -- <file>`.
+- If unintended changes appear, undo ONLY those hunks with a targeted edit. Never revert the whole file: it may hold edits that are not yours.
 - CSS/HTML/config files are high-risk for destructive rewrites.
 
 ## QUALITY
 
 - SOLID. Small focused functions (< 30 lines).
-- Atomic commits (1 logical change = 1 commit).
+- One logical change per task. NEVER run git commit or git push: the pipeline commits once the review approves.
 - No `console.log` in production. Use a structured logger.
 - No `any` types. Use JSDoc annotations.
 

package/templates/roles/coder/opencode.md

@@ -12,7 +12,7 @@ Role: write code and tests for the given task.
 6. Code must compile. Tests must pass.
 7. Never hardcode secrets. Use environment variables (`process.env` in Node, `os.environ` in Python).
 8. Never overwrite a file entirely. Make targeted edits only.
-9. Small functions (< 30 lines). Atomic commits. No `console.log` in production. No `any` types.
+9. Small functions (< 30 lines). Never commit or push (the pipeline commits after review). No `console.log` in production. No `any` types.
 
 ## Before reporting done
 

package/templates/roles/coder.md

@@ -119,13 +119,13 @@ When modifying an existing project:
 - NEVER overwrite existing files entirely. Always make targeted, minimal edits.
 - When adding new code to an existing file, insert only the new lines at the correct location.
 - After each edit, verify with `git diff` that ONLY the intended lines changed.
-- If unintended changes are detected, revert immediately with `git checkout -- <file>`.
+- If unintended changes are detected, undo ONLY those hunks with a targeted edit. Never revert the whole file: it may hold edits that are not yours.
 - Pay special attention to CSS, HTML, and config files where full rewrites destroy prior work.
 
 ## Code Quality Rules
 
 - Follow SOLID principles. Write small, focused functions (< 30 lines).
-- Make atomic commits: 1 logical change = 1 commit. Keep PRs small and reviewable.
+- One logical change per task; keep it small and reviewable. NEVER run git commit or git push: the pipeline commits once the review approves.
 - Security: use httpOnly cookies for auth tokens, validate all input, parameterize queries, never expose secrets.
 - No console.log in production code -- use a structured logger. No 'any' types -- use JSDoc annotations.
 

package/templates/roles/refactorer.md

@@ -22,7 +22,7 @@ You are the **Refactorer** in a multi-role AI pipeline. Your job is to improve c
 
 - NEVER overwrite existing files entirely. Always make targeted, minimal edits.
 - After each edit, verify with `git diff` that ONLY the intended lines changed.
-- If unintended changes are detected, revert immediately with `git checkout -- <file>`.
+- If unintended changes are detected, undo ONLY those hunks with a targeted edit. Never revert the whole file: it may hold edits that are not yours.
 
 ## Output format
 

package/templates/skills/kj-code.md

@@ -40,7 +40,7 @@ After writing code, verify ALL of these before reporting done:
 
 - NEVER overwrite existing files entirely — make targeted edits
 - After each edit, verify with `git diff` that ONLY intended lines changed
-- If unintended changes detected, revert immediately with `git checkout -- <file>`
+- If unintended changes are detected, undo ONLY those hunks with a targeted edit. Never revert the whole file: it may hold edits you did not make, and an agent never discards changes that are not its own
 
 ## Completeness check
 

package/templates/skills/kj-review.md

@@ -8,7 +8,7 @@ Review the changes in the current branch: $ARGUMENTS
 
 ## Steps
 
-1. Run `git diff main...HEAD` (or appropriate base branch) to see all changes
+1. See ALL the work: `git diff --cached` (staged), `git diff` (unstaged) and `git diff main...HEAD` (or the appropriate base branch) for what is already committed
 2. Review each changed file against the priorities below
 3. Report findings clearly
 

package/templates/skills/kj-sonar.md

@@ -13,14 +13,15 @@ $ARGUMENTS
    ```bash
    npx @sonar/scan -Dsonar.host.url=http://localhost:9000 -Dsonar.projectKey=<project-key>
    ```
-3. Check quality gate status:
+3. Check quality gate status (the token comes from `KJ_SONAR_TOKEN`, set by `kj init`; a token authenticates as `token:` with an empty password):
    ```bash
-   curl -s -u admin:admin "http://localhost:9000/api/qualitygates/project_status?projectKey=<project-key>"
+   curl -s -u "$KJ_SONAR_TOKEN:" "http://localhost:9000/api/qualitygates/project_status?projectKey=<project-key>"
    ```
 4. List issues:
    ```bash
-   curl -s -u admin:admin "http://localhost:9000/api/issues/search?projectKeys=<project-key>&statuses=OPEN&ps=50"
+   curl -s -u "$KJ_SONAR_TOKEN:" "http://localhost:9000/api/issues/search?projectKeys=<project-key>&statuses=OPEN&ps=50"
    ```
+   Never authenticate with the default `admin` account: if the server still accepts its default password, tell the user to change it.
 
 ## If SonarQube is not available