karajan-code 4.36.0 → 4.38.0

package/package.json

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

package/scripts/esbuild-sea.config.mjs

@@ -26,6 +26,15 @@ const seaTransformPlugin = {
       let contents = await fs.readFile(args.path, "utf8");
       let modified = false;
 
+      // KJC-TSK-0915 (ADR 0014): the Sentinel's guard modules are read as TEXT at
+      // load time, to be copied into a project's harness. A single-file bundle has
+      // no sibling files, so the text is inlined here, before import.meta.url goes.
+      const SENTINEL_READ = /readFileSync\(new URL\("(\.\/sentinel\/[\w-]+\.mjs)", import\.meta\.url\), "utf8"\)/g;
+      if (SENTINEL_READ.test(contents)) {
+        contents = contents.replace(SENTINEL_READ, (_m, rel) => JSON.stringify(readFileSync(path.resolve(path.dirname(args.path), rel), "utf8")));
+        modified = true;
+      }
+
       // Replace import.meta.dirname with __dirname
       if (contents.includes("import.meta.dirname")) {
         contents = contents.replaceAll("import.meta.dirname", "__dirname");

package/src/cli/advanced-commands.js

@@ -34,7 +34,7 @@ export const ADVANCED_GROUPS = [
   { title: "Pipeline (piezas sueltas)", commands: ["autorun", "code", "review", "solomon", "agent", "scan", "tournament"] },
   { title: "Análisis pre-run", commands: ["discover", "triage", "researcher", "architect", "onboard", "brief"] },
   { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch"] },
-  { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy", "release", "policy", "claims", "steward"] },
+  { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy", "release", "policy", "claims", "steward", "pr-size"] },
   { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby", "sentinel", "identity"] },
   { title: "Infra / setup", commands: ["install-tools", "ollama", "skills", "roles", "agents", "env"] },
   { title: "Mantenimiento", commands: ["clean", "sync", "telemetry", "report-issue"] },

package/src/cli/register-meta.js

@@ -30,7 +30,7 @@ import { envInstallCommand, briefCommand } from "../commands/env.js";
 import { runReleaseCheck } from "../checks/release-check.js";
 import { agentRunCommand } from "../commands/agent-run.js";
 import { reportIssueCommand } from "../commands/report-issue.js";
-import { huCommand } from "../commands/hu.js";
+import { huCommand, HU_STATUSES } from "../commands/hu.js";
 import { worktreeCommand } from "../commands/worktree.js";
 import { addAdr, listAdrs } from "../environment/adr.js";
 import { formatAdvancedIndex } from "../commands/advanced.js";
@@ -271,6 +271,8 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
   hu.command("move <id> <status>")
+    // KJC-BUG-0257: the valid states, said before the call fails.
+    .description(`Move a card; <status> is one of: ${HU_STATUSES.join(", ")}`)
     .option("--json", "Machine-readable output")
     .action(async (id, status, flags) => {
       await withConfig(pkgVersion, "hu", flags, async ({ config }) => {
@@ -522,6 +524,17 @@ export function registerMeta(program, { pkgVersion }) {
       await privacyScanCommand({ paths, flags });
     });
 
+  // KJC-TSK-0910: the branch's size while it is written, same budget as CI.
+  program.command("pr-size")
+    .description("Lines this branch adds against its base, with the CI budget (committed, uncommitted and new files)")
+    .option("--json", "Machine-readable result")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "pr-size", flags, async ({ config, logger }) => {
+        const { prSizeCommand } = await import("../commands/pr-size.js");
+        await prSizeCommand({ config, logger, flags });
+      });
+    });
+
   const rag = program.command("rag").description("Retrieval-augmented search over Karajan plans, onboarding briefs and project code");
   rag.command("index")
     .description("Index plans + onboarding (and optionally project sources) into the local vector store")

package/src/commands/pr-size.js

@@ -0,0 +1,45 @@
+/**
+ * KJC-TSK-0910 — `kj pr-size`: the branch's size while it is being written,
+ * with the SAME budget the CI gate applies (loc-budget.js). It counts what is
+ * committed, what is not yet, and new files not yet added, against the merge
+ * base with the base branch, so the Sentinel can warn before the gate blocks.
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { budgetedAdded } from "../review/loc-budget.js";
+
+const git = (projectDir, args) =>
+  execFileSync("git", ["-C", projectDir, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+
+function mergeBase(projectDir, base) {
+  for (const ref of [`origin/${base}`, base]) {
+    try { return git(projectDir, ["merge-base", "HEAD", ref]).trim(); } catch { /* try the next ref */ }
+  }
+  throw new Error(`pr-size: no merge base with ${base} (nor origin/${base})`);
+}
+
+/** @returns {Promise<{added: number, exempt: number, testAdded: number, base: string}>} */
+export async function branchSize({ projectDir = process.cwd(), base = "main" } = {}) {
+  const from = mergeBase(projectDir, base);
+  // Working tree against the merge base: committed and uncommitted together.
+  let numstat = git(projectDir, ["diff", "--numstat", from]);
+  // New files not yet added are where a branch grows while it is written.
+  for (const file of git(projectDir, ["ls-files", "--others", "--exclude-standard"]).split("\n").filter(Boolean)) {
+    let text;
+    try { text = readFileSync(join(projectDir, file), "utf8"); } catch { continue; }
+    if (text.includes("\0")) continue; // binary
+    // Lines as git counts them: an empty file adds none.
+    const n = text === "" ? 0 : text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+    numstat += `${n}\t0\t${file}\n`;
+  }
+  return { ...budgetedAdded(numstat), base };
+}
+
+export async function prSizeCommand({ config, logger = console, flags = {} }) {
+  const s = await branchSize({ projectDir: config?.projectDir || process.cwd(), base: config?.base_branch || "main" });
+  if (flags.json) process.stdout.write(`${JSON.stringify(s)}\n`);
+  else logger.info(`pr-size: ${s.added} line(s) added against ${s.base} (${s.testAdded} in tests, ${s.exempt} exempt)`);
+  return s;
+}

package/src/commands/rag.js

@@ -14,7 +14,7 @@ import { installPostMergeHook, maybeAutoUpdate } from "../rag/auto-update.js";
 import { indexLibrary, LIBRARY_PROJECT } from "../rag/library.js";
 import { loadGoldenQueries, runEval } from "../rag/eval.js";
 import { getKarajanHome } from "../utils/paths.js";
-import { countProjectChunks, emptyIndexRemedy, migrateProjectIndex } from "../rag/migrate.js";
+import { countProjectChunks, countProjectSources, emptyIndexRemedy, migrateProjectIndex } from "../rag/migrate.js";
 import { openLibraryStore, openProjectStore, projectDbPath } from "../rag/project-store.js";
 
 // KJC-TSK-0882 (ADR 0011): el indice es del proyecto, no de la maquina.
@@ -153,6 +153,11 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
       if (flags.json) process.stdout.write(`${JSON.stringify({ hits: [], empty: true, topK, scope, remedy })}\n`);
       return [];
     }
+    // KJC-BUG-0258: chunks of plans and briefs but none of the project's own files
+    // answer nothing about the code; said now, not when kj review --staged blocks.
+    if (!library && project && countProjectSources(db, project, config?.projectDir || process.cwd()) === 0) {
+      logger.warn("[rag] this project's index holds none of its own files (only plans or briefs): run kj rag index --with-sources");
+    }
     const mode = flags.mode || "hybrid";
     const alpha = Math.max(0, Math.min(1, Number(flags.alpha) || 0.6));
     // Safe by grammar: parseWhere (core where-parser.js) accepts ONLY
@@ -234,6 +239,19 @@ export async function ragCoversCommand({ file, config, flags = {} }) {
   }
 }
 
+/**
+ * KJC-BUG-0255: what `kj rag migrate` keeps. The project's own files pass the
+ * indexer's criterion of today; sources outside the tree (plans, onboarding)
+ * are kept as they are.
+ */
+export function migrateKeep(projectDir, config) {
+  const exclude = ragExclude(config);
+  return (source) => {
+    const rel = relative(projectDir, source);
+    return rel.startsWith("..") || isAbsolute(rel) || indexableReason(rel, source, { exclude, projectDir }) === null;
+  };
+}
+
 /**
  * KJC-TSK-0888 (RAG-P1a, ADR 0011) — `kj rag migrate`: copia los chunks de este
  * proyecto desde la base global a su propio indice, con sus embeddings, sin
@@ -241,11 +259,13 @@ export async function ragCoversCommand({ file, config, flags = {} }) {
  */
 export async function ragMigrateCommand({ config, flags = {} }) {
   const projectDir = config?.projectDir || process.cwd();
+  const keep = migrateKeep(projectDir, config);
   const res = migrateProjectIndex({
     slug: projectSlug(projectDir),
     legacyPath: join(getKarajanHome(), "rag.db"),
     targetPath: projectDbPath(projectDir),
     dim: config?.rag?.embedder?.dim || 768,
+    keep,
   });
   if (flags.json) process.stdout.write(`${JSON.stringify(res)}\n`);
   else process.stdout.write(`rag migrate: ${res.state} — ${res.reason}\n`);

package/src/commands/review-gate.js

@@ -5,7 +5,7 @@
  * verdict tied to the exact diff (verdict-store), so the pre-commit hook
  * (ENV-C) can verify it. Exit code 0 = approved, 1 = rejected/stale.
  */
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 import { runCommand } from "../utils/process.js";
 import { checkVerdict, diffHash, pruneVerdicts } from "../review/verdict-store.js";
@@ -13,6 +13,7 @@ import { runOneShotReview } from "../review/one-shot-review.js";
 import { runSolomonArbitration } from "../review/solomon-arbitration.js";
 import { ensureGateTrackable } from "../review/gate-gitignore.js";
 import { runSonarPregate, formatSonarFinding, addedLinesByFile } from "../review/sonar-pregate.js";
+import { addedAreCommentsOnly } from "../review/comment-only.js";
 import { checkSonarRequirement, SONAR_RULE_ID } from "../review/sonar-requirement.js";
 import { checkRagRequirement, checkRagVerdict, ragBlock, RAG_RULE_ID } from "../review/rag-requirement.js";
 import { checkUiEvidence, uiBlock } from "../review/ui-evidence.js";
@@ -59,6 +60,36 @@ async function rawDiff(range, extraArgs = []) {
   return res.stdout;
 }
 
+/** The file as the reviewed diff leaves it. */
+async function resultingContent(range, file, projectDir) {
+  const show = async (spec) => {
+    const res = await runCommand("git", ["show", spec]);
+    return res.exitCode === 0 ? res.stdout : null;
+  };
+  // Staged review: the INDEX, never the working tree (unstaged edits are not reviewed).
+  if (!range) return show(`:${file}`);
+  // `a..b` / `a...b`: the right side (HEAD when omitted).
+  if (/\.\./.test(range)) return show(`${range.split(/\.\.\.?/)[1] || "HEAD"}:${file}`);
+  // `git diff <ref>` compares the ref with the working tree, so that is the result.
+  try { return readFileSync(join(projectDir, file), "utf8"); } catch { return null; }
+}
+
+/**
+ * KJC-BUG-0235: mark the files whose added lines are all comments, so a
+ * cleanup that corrects the comments it left lying is not taken for new code.
+ * Anything unreadable or of unknown syntax stays unmarked (counts as code).
+ */
+export async function markCommentOnlyAdditions(numstat, { range, projectDir }) {
+  const touched = numstat.filter((n) => n.added > 0);
+  if (touched.length === 0) return;
+  const added = addedLinesByFile(await rawDiff(range, ["--unified=0"]));
+  for (const n of touched) {
+    const lines = added.get(n.file);
+    const content = lines ? await resultingContent(range, n.file, projectDir) : null;
+    n.commentOnly = content !== null && addedAreCommentsOnly(content, lines, n.file);
+  }
+}
+
 // KJC-TSK-0838: a grant is the ONLY way past the sonar requirement, so it is
 // said with who gave it, its scope and until when.
 const formatSonarGrant = (g) => {
@@ -286,6 +317,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   // exempt — deleting code adds no behavior to test.
   const numstat = (await rawDiff(flags.range, ["--numstat"])).split("\n").map((l) => l.trim()).filter(Boolean)
     .map((l) => { const [a, r, ...f] = l.split(/\s+/); return { file: f.join(" "), added: a === "-" ? 1 : Number(a) || 0, removed: r === "-" ? 0 : Number(r) || 0 }; });
+  await markCommentOnlyAdditions(numstat, { range: flags.range, projectDir });
   const tests = checkTestsWithCode({ config, stagedFiles: changedFiles, numstat });
   if (tests.mode === "delete-only") console.log(`⚠ tests-with-code: exempt — ${tests.reason}`);
   if (tests.mode === "warn") console.log(`⚠ tests-with-code: ${tests.reason}`);

package/src/harden/hook-templates.js

@@ -156,6 +156,13 @@ export function hookBody(hook, cmds = {}, { globalHooksDir = null, baseBranch =
         "  echo 'kj harden: commit header must follow Conventional Commits (type: subject)'; exit 1",
         "fi",
         'if [ "${#header}" -gt 100 ]; then echo \'kj harden: commit header exceeds 100 chars\'; exit 1; fi',
+        "# KJC-TSK-0909: the rest of what CI's commitlint rejects, caught here.",
+        "if ! awk 'NR > 2 && !/^#/ && length($0) > 100 { exit 1 }' \"$msg_file\"; then",
+        "  echo 'kj harden: a commit body line exceeds 100 chars (CI commitlint rejects it)'; exit 1",
+        "fi",
+        'if [ -x node_modules/.bin/commitlint ]; then',
+        '  node_modules/.bin/commitlint --edit "$msg_file" || exit 1',
+        "fi",
         `if grep -qiE '${AI_ATTRIBUTION}' "$msg_file"; then`,
         "  echo 'kj harden: AI attribution is not allowed in commit messages'; exit 1",
         "fi",

package/src/harden/phone-sign.js

@@ -17,18 +17,22 @@ const SPKI_ED25519_PREFIX = Buffer.from("302a300506032b6570032100", "hex");
 // escáner de privacidad del pack deniega claves google con razón general, y
 // servirla desde la landing la hace además rotable sin release.
 const RELAY_CONFIG_URL = "https://karajancode.com/sign/relay.json";
-let relayCache = null;
+// Cacheada por fetch: en produccion es siempre la misma; en tests, cada relé falso es otro.
+const relayCache = new WeakMap();
 async function relayConfig(fetchFn) {
-  if (relayCache) return relayCache;
+  if (relayCache.has(fetchFn)) return relayCache.get(fetchFn);
   const res = await fetchFn(RELAY_CONFIG_URL);
   if (!res.ok) throw new Error(`phone-sign: no pude cargar la config del relé (${res.status}) — revisa la red`);
   const cfg = await res.json();
   if (!cfg?.apiKey || !cfg?.projectId || !cfg?.collection) throw new Error("phone-sign: config del relé incompleta");
-  relayCache = {
+  const relay = {
     apiKey: cfg.apiKey,
     url: `https://firestore.googleapis.com/v1/projects/${cfg.projectId}/databases/(default)/documents/${cfg.collection}`,
+    // KJC-TSK-0901: v2 solo cuando la landing (pagina + reglas) ya lo entiende.
+    payloadVersion: cfg.payloadVersion === 2 ? 2 : 1,
   };
-  return relayCache;
+  relayCache.set(fetchFn, relay);
+  return relay;
 }
 const SIGN_PAGE = "https://karajancode.com/sign";
 const POLL_INTERVAL_MS = 2000;
@@ -109,9 +113,15 @@ export function enrollPhone(publicKeyBase64, { home } = {}) {
   writeFileSync(phoneKeyPath(home), `${JSON.stringify(record, null, 2)}\n`, "utf8");
 }
 
-/** Payload canónico firmado: files EXACTAMENTE como se enviaron, JSON sin espacios. */
-export function canonicalPayload({ cid, nonce, project, files }) {
+/**
+ * Payload canónico firmado: files EXACTAMENTE como se enviaron, JSON sin espacios.
+ * KJC-TSK-0901/0902: v2 firma también lo demás que el móvil enseña (versión de
+ * kj) y la propia vigencia (emisión y caducidad, en ms), para que nada mostrado
+ * quede sin firmar y la caducidad sea de lo que el humano aprobó.
+ */
+export function canonicalPayload({ cid, nonce, project, files, v = 1, kjVersion, issuedMs, expiresMs }) {
   const filesHash = createHash("sha256").update(JSON.stringify(files)).digest("hex");
+  if (v === 2) return `kj-supervisor-sign:v2:${cid}:${nonce}:${project}:${kjVersion}:${issuedMs}:${expiresMs}:${filesHash}`;
   return `kj-supervisor-sign:v1:${cid}:${nonce}:${project}:${filesHash}`;
 }
 
@@ -135,17 +145,21 @@ export async function requestPhoneSignature({ project, files, kjVersion, logger
   const drawQr = deps.qr ?? ((url) => qrcode.generate(url, { small: true }));
   const cid = randomBytes(16).toString("hex");
   const nonce = randomBytes(16).toString("hex");
+  const relay = await relayConfig(fetchFn);
+  const v = relay.payloadVersion;
+  const issuedMs = now();
+  const expiresMs = issuedMs + TTL_MS;
   const body = {
     fields: {
       nonce: { stringValue: nonce },
       project: { stringValue: project },
       kj_version: { stringValue: kjVersion },
       state: { stringValue: "pending" },
-      createdAt: { timestampValue: new Date().toISOString() },
+      createdAt: { timestampValue: new Date(issuedMs).toISOString() },
       files: { arrayValue: { values: files.map((f) => ({ mapValue: { fields: { file: { stringValue: f.file }, sha256: { stringValue: f.sha256 ?? "" } } } })) } },
+      ...(v === 2 ? { v: { integerValue: "2" }, expires_at: { timestampValue: new Date(expiresMs).toISOString() } } : {}),
     },
   };
-  const relay = await relayConfig(fetchFn);
   const created = await fetchFn(`${relay.url}?documentId=${cid}&key=${relay.apiKey}`, {
     method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body),
   });
@@ -157,7 +171,7 @@ export async function requestPhoneSignature({ project, files, kjVersion, logger
   logger.info?.(`phone-sign: escanea el QR o abre ${signUrl} y firma en el móvil (caduca en ${TTL_MS / 1000}s)`);
   logger.info?.("phone-sign: esperando la firma del móvil…");
   const spinner = deps.spinner ?? makeSpinner();
-  const deadline = now() + TTL_MS;
+  const deadline = expiresMs;
   while (now() < deadline) {
     const res = await fetchFn(`${relay.url}/${cid}?key=${relay.apiKey}`);
     if (!res.ok) { spinner.stop(); throw new Error(`phone-sign: fallo consultando la petición de firma (HTTP ${res.status})`); }
@@ -171,14 +185,17 @@ export async function requestPhoneSignature({ project, files, kjVersion, logger
       if (!signerKey || !authorized.has(signerKey)) {
         return { ok: false, reason: "la publicKey que firma no está en el padrón autorizado — el doc es transporte, la verdad es el padrón" };
       }
-      const payload = canonicalPayload({ cid, nonce, project, files });
+      const signed2 = v === 2 ? { v, kjVersion, issuedMs, expiresMs } : {};
+      const payload = canonicalPayload({ cid, nonce, project, files, ...signed2 });
       const signature = fields.signature?.stringValue ?? "";
       const good = verifyPhoneSignature({ payload, signature, publicKey: signerKey });
       if (!good) return { ok: false, reason: "firma ed25519 inválida para el payload canónico" };
+      // KJC-TSK-0901: una firma válida fuera de la vigencia que ella misma firma no vale.
+      if (v === 2 && now() > expiresMs) return { ok: false, reason: "la firma llegó fuera de su vigencia firmada" };
       // KJC-TSK-0823: devuelve el desafío + firma para que el sello los GRABE en
       // la provenance y CI pueda re-verificar server-side (clave del padrón).
       const filesHash = createHash("sha256").update(JSON.stringify(files)).digest("hex");
-      return { ok: true, signer: signerKey, signature, challenge: { cid, nonce, project, filesHash } };
+      return { ok: true, signer: signerKey, signature, challenge: { cid, nonce, project, filesHash, ...signed2 } };
     }
     spinner.tick();
     await sleep(POLL_INTERVAL_MS);

package/src/harden/sentinel/sentinel-bash-write.mjs

@@ -0,0 +1,106 @@
+// The Sentinel's bash-write guard (KJC-BUG-0237, moved here by KJC-TSK-0919,
+// ADR 0014). Inside the repo, files are written through Edit/Write only, the path
+// every gate guards. Copied byte for byte into .karajan/harness; `root` injected.
+// The stated limit: a program you run can write files; only a sandbox stops that.
+import { existsSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { headIndex, shellSegments } from "./sentinel-shell.mjs";
+
+const WRITES = ["tee", "touch", "truncate", "cp", "mv", "install", "ln", "sed", "perl", "dd", "sh", "bash", "zsh", "dash", "eval"];
+const RUNNERS = ["xargs", "find", "node", "python3", "python", "ruby", "php", "deno", "bun"];
+// touch/truncate -s SIZE, -r REF, -d DATE, -t STAMP: the value is not a file it writes.
+const VALUED = ["-s", "--size", "-r", "--reference", "-d", "--date", "-t"];
+
+/** Redirection targets: >&N and >&- duplicate or close a descriptor; >& FILE and >&FILE write FILE. */
+const redirections = (words) => {
+  const out = [];
+  words.forEach((w, k) => {
+    const m = /^\d*(>>|>[|]|>)(.*)$/.exec(w);
+    if (!m) return;
+    const dup = m[2].startsWith("&") ? m[2].slice(1) : null;
+    if (dup === null) out.push(m[2] || words[k + 1]);
+    else if (dup === "") out.push(words[k + 1]);
+    else if (!/^\d*-?$/.test(dup)) out.push(dup);
+  });
+  return out;
+};
+
+/** Destination of cp/mv/install/ln: -t DIR / --target-directory[=]DIR, else the last plain word. */
+const destination = (rest, plain) => {
+  const t = rest.findIndex((w) => w === "-t" || w === "--target-directory");
+  const tEq = rest.find((w) => w.startsWith("--target-directory="));
+  if (t >= 0) return [rest[t + 1]];
+  if (tEq) return [tEq.slice(19)];
+  return plain.length >= 2 ? [plain.at(-1)] : [];
+};
+
+/** Files sed/perl -i edit: the script is the word after -e/-f, else the first plain word; a lone plain word is the file. */
+const inPlace = (rest, plain) => {
+  if (!rest.some((w) => w.startsWith("--in-place") || /^-[a-zA-Z0-9]*i/.test(w))) return [];
+  const script = rest.findIndex((w) => ["-e", "-f", "--expression"].includes(w));
+  if (script >= 0) return plain.filter((w) => w !== rest[script + 1]);
+  return plain.length === 1 ? plain : plain.slice(1);
+};
+
+/**
+ * The files a simple command (a word list) writes from the shell. "$(...)"
+ * marks a target that only exists at run time: unknowable, so writesRepo denies it.
+ * @param {string[]} words
+ * @returns {string[]}
+ */
+export const shellWrites = (words) => {
+  const out = redirections(words);
+  const i = headIndex(words, [...WRITES, ...RUNNERS]);
+  const head = (words[i] || "").split("/").at(-1);
+  // xargs / find -exec run a writer on targets that arrive at run time.
+  if (["xargs", "find"].includes(head) && words.slice(i + 1).some((w) => WRITES.includes(w.split("/").at(-1)))) out.push(`$(${head})`);
+  // Arguments without redirections (< << <<< > >> and a detached operand).
+  const rest = [];
+  for (let k = i + 1; k < words.length; k++) {
+    if (!/^\d*[<>]/.test(words[k])) rest.push(words[k]);
+    else if (/^\d*(<{1,3}|>>?|>[|&])$/.test(words[k])) k++;
+  }
+  // Operands: words that are not options, and EVERY word after "--" (touch -- -file).
+  const cut = rest.includes("--") ? rest.indexOf("--") : rest.length;
+  const plain = [...rest.slice(0, cut).filter((w) => !w.startsWith("-")), ...rest.slice(cut + 1)];
+  if (head === "tee") out.push(...plain);
+  if (head === "dd") out.push(...rest.filter((w) => w.startsWith("of=")).map((w) => w.slice(3)));
+  // By position, not value (touch -d today today writes "today").
+  if (head === "touch" || head === "truncate") out.push(...rest.filter((w, k) => k > cut || (k < cut && !w.startsWith("-") && !VALUED.includes(rest[k - 1]))));
+  // sh -c / eval run a script of their own: its writes are this command's writes.
+  if (["sh", "bash", "zsh", "dash"].includes(head) && rest.includes("-c")) for (const seg of shellSegments(rest[rest.indexOf("-c") + 1] || "")) out.push(...shellWrites(seg));
+  if (head === "eval") for (const seg of shellSegments(rest.join(" "))) out.push(...shellWrites(seg));
+  // An inline script (node -e, python -c...) that names a write API.
+  const inline = rest[rest.findIndex((w) => ["-e", "-c", "--eval", "-p", "-r"].includes(w)) + 1] || "";
+  if (/^(node|deno|bun|python[\d.]*|ruby|perl|php)$/.test(head) && /write|append|open|copy|rename|truncate|unlink|mkdir|symlink/i.test(inline)) out.push(`$(${head})`);
+  if (["cp", "mv", "install", "ln"].includes(head)) out.push(...destination(rest, plain));
+  if (head === "sed" || head === "perl") out.push(...inPlace(rest, plain));
+  return out.filter(Boolean);
+};
+
+/**
+ * Inside the repo, or unknowable ($VAR, backtick, ~user): both deny. /dev/* and
+ * descriptor duplication (&1) are outside; ~/ is the home, where the repo may live.
+ * Real paths: a link outside (/tmp/link -> repo) points in.
+ * @param {string} t
+ * @param {string} root
+ */
+export const writesRepo = (t, root) => {
+  if (t.includes("$") || t.includes("`")) return true;
+  if (t.startsWith("&") || t.startsWith("/dev/")) return false;
+  if (t.startsWith("~") && t !== "~" && !t.startsWith("~/")) return true;
+  let a = resolve(root, t.startsWith("~") ? homedir() + t.slice(1) : t);
+  let tail = "";
+  while (!existsSync(a) && dirname(a) !== a) {
+    tail = join(a.slice(dirname(a).length + 1), tail);
+    a = dirname(a);
+  }
+  let rel;
+  try {
+    rel = relative(realpathSync(root), join(realpathSync(a), tail));
+  } catch {
+    return true;
+  }
+  return !rel.startsWith("..") && !rel.startsWith("/");
+};

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

@@ -0,0 +1,98 @@
+// The Sentinel's discard guard (KJC-BUG-0238/0241/0242, moved here by KJC-TSK-0916,
+// ADR 0014). An agent does not discard changes it did not make. Copied byte for
+// byte into .karajan/harness; `root` is the project root, injected.
+import { spawnSync } from "node:child_process";
+import { relative, resolve } from "node:path";
+import process from "node:process";
+import { headIndex, shortOpts } from "./sentinel-shell.mjs";
+
+export const DISCARD_VERBS = ["checkout", "restore", "reset", "stash", "switch", "clean"];
+
+/**
+ * What a git command would discard, per simple command (a word list).
+ * null = discards nothing (or is not git); {stash} = drops saved work;
+ * {unknown} = cannot be read with certainty; {clean} = untracked files;
+ * {paths} = working-tree changes (":/" = the whole tree, whatever the cwd).
+ * @param {string[]} words
+ * @param {string} root
+ */
+export const discardOf = (words, root) => {
+  let i = headIndex(words, ["git"]); // /usr/bin/git is git
+  // A $variable in command position beside a discard verb ($g checkout) cannot be read.
+  if (words[i]?.startsWith("$") && words.some((w) => DISCARD_VERBS.includes(w))) return { unknown: true };
+  if (words[i]?.split("/").at(-1) !== "git") return null;
+  let cwd = root;
+  for (i++; i < words.length && words[i].startsWith("-"); i++) {
+    if (words[i] === "-C") cwd = resolve(cwd, words[++i] || ".");
+    else if (words[i] === "-c") i++;
+    else if (!["--no-pager", "-P", "--paginate", "-p", "--no-optional-locks"].includes(words[i])) return words.some((w) => DISCARD_VERBS.includes(w)) ? { unknown: true } : null;
+  }
+  const sub = words[i];
+  const args = [];
+  for (let j = i + 1; j < words.length; j++) {
+    // Options that take a value: the value is not a flag (-e -n excludes "-n").
+    // Dropping clean's excludes only makes its probe list MORE files.
+    if (["-s", "--source", "-e", "--exclude"].includes(words[j]) || (sub === "clean" && /^-[a-zA-Z]*e$/.test(words[j]))) j++;
+    else args.push(words[j]);
+  }
+  const has = (...f) => f.some((x) => args.includes(x));
+  const dd = args.indexOf("--");
+  const pos = (dd < 0 ? args : args.slice(0, dd)).filter((a) => !a.startsWith("-"));
+  const after = dd < 0 ? [] : args.slice(dd + 1);
+  const ALL = { cwd, paths: [":/"] };
+  if (sub === "stash") return has("drop", "clear") ? { cwd, stash: true } : null;
+  if (sub === "reset") return has("--hard") ? ALL : null;
+  // Every clean but a dry run (-n in a short cluster BEFORE "--"): clean.requireForce=false deletes without -f.
+  const opts = dd < 0 ? args : args.slice(0, dd);
+  // Interactive clean decides at the prompt: nothing to probe, fail-closed.
+  if (sub === "clean" && opts.some((a) => a === "--interactive" || shortOpts(a).includes("i"))) return { unknown: true };
+  if (sub === "clean") return opts.some((a) => a === "--dry-run" || shortOpts(a).includes("n")) ? null : { cwd, clean: [opts, args.slice(opts.length)] };
+  if (sub === "switch") return has("--discard-changes", "-f", "--force") ? ALL : null;
+  if (sub === "restore") return has("--staged", "-S") && !has("--worktree", "-W") ? null : { cwd, paths: [...pos, ...after] };
+  if (sub !== "checkout") return null;
+  if (has("-f", "--force")) return ALL;
+  if (has("-b", "-B", "--orphan") || !(pos.length || after.length)) return null;
+  if (after.length) return { cwd, paths: after };
+  const isRef = spawnSync("git", ["-C", cwd, "rev-parse", "--verify", "--quiet", `${pos[0]}^{commit}`]).status === 0;
+  if (!isRef) return { cwd, paths: pos };
+  return pos.length > 1 ? { cwd, paths: pos.slice(1) } : null;
+};
+
+/**
+ * Files the discard would lose that the session did not own: dirty now and not
+ * clean at first touch. Anything unreadable, or another repo, is foreign.
+ * @param {object} d what discardOf returned
+ * @param {Record<string, string>} touch the session's first_touch ledger
+ * @param {string} root
+ * @returns {string[]}
+ */
+export const foreignLost = (d, touch, root) => {
+  if (d.stash) return ["git stash"];
+  if (d.unknown) return ["(comando no verificable: ejecutalo como git simple)"];
+  const top = spawnSync("git", ["-C", d.cwd, "rev-parse", "--show-toplevel"], { encoding: "utf8" });
+  const sameRepo = top.status === 0 && resolve(String(top.stdout).trim()) === resolve(root);
+  const own = (f) => sameRepo && Object.hasOwn(touch, f) && touch[f] === "clean";
+  if (d.clean) {
+    // Ask git what it would remove: -n wins over -f, so the same flags (-ff included) are kept,
+    // minus -q (it silences the listing) and every exclude (dropping one only lists MORE).
+    // -n FIRST: after "--" it is a pathspec. LC_ALL=C: lines are parsed.
+    const [opts, rest] = d.clean;
+    const loud = opts.map((a) => (a.startsWith("--") ? a : `-${shortOpts(a).replaceAll("q", "")}`)).filter((a) => a !== "-" && a !== "--quiet" && !a.startsWith("--exclude"));
+    const r = spawnSync("git", ["-C", d.cwd, "clean", "-n", ...loud, ...rest], { encoding: "utf8", env: { ...process.env, LC_ALL: "C" } });
+    if (r.status !== 0) return ["(git clean -n fallo)"];
+    return String(r.stdout).split("\n").filter((l) => l.startsWith("Would remove ")).map((l) => relative(root, resolve(d.cwd, l.slice(13)))).filter((f) => !own(f));
+  }
+  // Fail-closed: a path git does not know (misparsed, $VAR, substitution) cannot
+  // be proven safe; git would refuse to check it out anyway.
+  if (spawnSync("git", ["-C", d.cwd, "ls-files", "--error-unmatch", "--", ...d.paths]).status !== 0) return [`(ruta no resoluble: ${d.paths.join(" ")})`];
+  const r = spawnSync("git", ["-C", d.cwd, "status", "--porcelain", "-z", "--untracked-files=no", "--", ...d.paths], { encoding: "utf8" });
+  if (r.status !== 0) return ["(git status fallo)"];
+  const files = [];
+  const parts = String(r.stdout).split("\0");
+  for (let k = 0; k < parts.length; k++) {
+    if (parts[k].length < 4) continue;
+    files.push(parts[k].slice(3));
+    if ("RC".includes(parts[k][0])) k++;
+  }
+  return files.filter((f) => !own(f));
+};

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

@@ -0,0 +1,57 @@
+// The method's reminders (KJC-TSK-0917, ADR 0014). An agent reads its rules at
+// the start and loses them when the context is compacted; a hook does not forget.
+// These are reminders, not gates: never a block. Each comes AFTER the action that
+// precedes the one its rule is about (git add before a commit, gh pr create before
+// a merge), from PostToolUse: a PreToolUse reminder would need permissionDecision
+// "allow", which skips the user's permission prompt. Copied byte for byte into
+// .karajan/harness.
+import { headIndex, shellSegments } from "./sentinel-shell.mjs";
+
+/** The git or gh subcommand of a simple command, or null: "git commit" -> ["git", "commit"]. */
+const verbOf = (words) => {
+  const i = headIndex(words, ["git", "gh"]);
+  const tool = (words[i] || "").split("/").at(-1);
+  if (tool !== "git" && tool !== "gh") return null;
+  let j = i + 1;
+  while (j < words.length && words[j].startsWith("-")) j += ["-C", "-c", "-R", "--repo"].includes(words[j]) ? 2 : 1;
+  return [tool, words[j] || "", words[j + 1] || ""];
+};
+
+const REMINDERS = [
+  {
+    id: "commit",
+    when: (verbs) => verbs.some(([t, a]) => t === "git" && a === "add"),
+    say: "kj, antes de commitear: cabecera de 100 caracteres como máximo con el sujeto en minúscula, líneas del cuerpo de 100 como máximo y sin atribución a IA. Valida el mensaje con npx commitlint --edit <fichero> y stagea por nombre (nunca git add -A).",
+  },
+  {
+    id: "gh-account",
+    when: (verbs) => verbs.some(([t]) => t === "gh") && !verbs.some(([t, a, b]) => t === "gh" && a === "auth" && b === "switch"),
+    say: "kj: gh sin cuenta explícita. La cuenta activa puede haberla cambiado otra sesión; antepón gh auth switch --user <cuenta-del-proyecto> && en el mismo comando.",
+  },
+  {
+    id: "merge",
+    when: (verbs) => verbs.some(([t, a, b]) => t === "gh" && a === "pr" && b === "create"),
+    say: "kj, PR abierta; antes de mergearla: si la card no está terminada, pártela ahora (lo hecho en su card, el resto en una nueva). Tras el merge, muévela con sus commits.",
+  },
+  {
+    id: "sync-main",
+    when: (verbs, segs) => segs.some((w) => w.includes("main")) && verbs.some(([t, a]) => t === "git" && ["checkout", "switch", "pull"].includes(a)),
+    say: "kj: tras sincronizar main, crea ya la rama de la siguiente tarea desde origin/main. En main nunca se commitea.",
+  },
+];
+
+/**
+ * The reminders due after a Bash command ran, minus those already shown within
+ * the last `every` actions.
+ * @param {string} cmd
+ * @param {{seen?: Record<string, number>, step?: number, every?: number}} [opts]
+ *   seen: action number at which each reminder was last shown; step: this action's number.
+ * @returns {{id: string, say: string}[]}
+ */
+export const remindersFor = (cmd, { seen = {}, step = 0, every = 25 } = {}) => {
+  const segs = shellSegments(cmd);
+  const verbs = segs.map(verbOf).filter(Boolean);
+  return REMINDERS.filter((r) => r.when(verbs, segs))
+    .filter((r) => !Object.hasOwn(seen, r.id) || step - seen[r.id] > every)
+    .map(({ id, say }) => ({ id, say }));
+};

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

@@ -0,0 +1,95 @@
+// The Sentinel's shell reader (KJC-TSK-0915, ADR 0014). A real module with no
+// dependencies: kj harden copies it byte for byte into .karajan/harness as
+// sentinel-shell.mjs, so the hooks stay autonomous and this code is unit-tested.
+// It reads command TEXT; whatever it cannot read with certainty, the guards that
+// use it treat as unknowable and deny.
+
+/**
+ * Simple commands as word lists, quote-aware: an operator or blank inside
+ * quotes belongs to the word ('user;work.txt' is one path).
+ * @param {string} cmd
+ * @returns {string[][]}
+ */
+export const shellSegments = (cmd) => {
+  const segs = [[]];
+  let word = null;
+  let quote = null;
+  let escaped = false;
+  const end = () => {
+    if (word !== null) segs.at(-1).push(word);
+    word = null;
+  };
+  for (const ch of String(cmd)) {
+    // A backslash keeps the next char literal (an escaped blank joins the word),
+    // except inside single quotes.
+    if (escaped) { word += ch; escaped = false; continue; }
+    if (ch === "\\" && quote !== "'") { escaped = true; word ??= ""; continue; }
+    if (quote) {
+      if (ch === quote) quote = null;
+      else word += ch;
+      continue;
+    }
+    if (ch === "'" || ch === '"') { quote = ch; word ??= ""; continue; }
+    // >| and >& are redirections, not a pipe or a fork.
+    if ((ch === "|" || ch === "&") && word?.endsWith(">")) { word += ch; continue; }
+    // x>file: end "x" and start the redirection word ">" (the target follows in it).
+    if (ch === ">" && word !== null && !/^\d*>?$/.test(word)) { end(); word = ">"; continue; }
+    // ( ) { } and backticks also cut: what runs inside $( ), a subshell or a group
+    // is a command of its own. A backtick leaves "$" in the word it interrupts, as
+    // $( does: that word is no longer readable.
+    if (ch === "`") word = (word ?? "") + "$";
+    if (";&|(){}\n`".includes(ch)) { end(); segs.push([]); continue; }
+    if (ch.trim() === "") { end(); continue; }
+    word = (word ?? "") + ch;
+  }
+  end();
+  return segs.filter((s) => s.length);
+};
+
+const WRAPPERS = new Set(["command", "exec", "sudo", "doas", "nice", "nohup", "time", "env"]);
+
+/**
+ * Index of the command word. Skips NAME=value assignments AND wrappers (env,
+ * sudo, command...) in any interleaving: env MODE=prod tee -> tee. After a
+ * wrapper with options (sudo -u root, env -i FOO=1) the command is the first of
+ * `heads`; none found means there is no command to read.
+ * @param {string[]} words
+ * @param {string[]} heads
+ */
+export const headIndex = (words, heads) => {
+  let i = 0;
+  while (i < words.length && (/^[A-Za-z_]\w*=/.test(words[i]) || WRAPPERS.has(words[i].split("/").at(-1)))) i++;
+  if (!words[i]?.startsWith("-")) return i;
+  const k = words.slice(i).findIndex((x) => heads.includes(x.split("/").at(-1)));
+  return k < 0 ? words.length : i + k;
+};
+
+/**
+ * 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.
+ * @param {string} cmd
+ */
+export const stripInertQuotes = (cmd) => {
+  let out = "";
+  for (let i = 0; i < cmd.length; i++) {
+    const q = cmd[i];
+    if (q !== "'" && q !== '"') { out += q; continue; }
+    let j = i + 1;
+    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;
+    i = j;
+  }
+  return out;
+};
+
+// Options whose value is prose, never a path (gh, git, kj).
+const TEXT_OPTION = /(^|\s)(--title|--body|--message|-m|--notes|--description|--ac|--criteria|--reason|--decision|--context|--consequences)(=|\s+)("[^"$`\\]*"|'[^']*')/g;
+
+/** KJC-BUG-0243: blank the inert quoted value of a text option (--title "a/b c"): prose, not a path. */
+export const stripTextOptionValues = (cmd) => cmd.replace(TEXT_OPTION, (_m, pre, opt, sep, val) => `${pre}${opt}${sep}${val[0]}${val[0]}`);
+
+/** Short flags of a cluster stop at "e": the rest is -e's value (-fen = -f -e n). */
+export const shortOpts = (a) => (/^-[a-zA-Z]/.test(a) ? a.slice(1).split("e")[0] : "");

package/src/harden/sentinel/sessionstart.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// kj sentinel SessionStart hook (KJC-TSK-0918, ADR 0014), managed by `kj harden`.
+// A compaction takes exactly what the agent needs most: the rules it read at the
+// start. After a compaction or a resume, this gives them back, short, with the
+// state of the session. A new session gets nothing: CLAUDE.md already brings them.
+// Copied byte for byte into .karajan/harness; never fails a session (exit 0).
+import process from "node:process";
+import { CARD, branchOf, load, pendingMoves } from "./sentinel-lib.mjs";
+
+const RULES = [
+  "1. Karajan gobierna y se le obedece: no cambies políticas, configuración de gates ni exclusiones para pasar un gate. Si uno parece injusto, díselo a tu usuario o usa kj report-issue.",
+  "2. Card antes de código; rama desde origin/main; nunca se commitea en main.",
+  "3. kj rag query antes de tocar código que no has consultado en esta sesión.",
+  "4. El test que falla va primero; la suite nunca se deja en rojo.",
+  "5. kj review --staged antes de cada commit: el veredicto va atado al diff exacto.",
+  "6. PR atómica: unas 150 líneas, 200 como máximo; mídela con kj pr-size y parte antes, no en el gate.",
+  "7. Conventional Commits, cabecera de 100 caracteres como máximo y sin atribución a IA.",
+  "8. Card sin terminar con PR mergeada: pártela antes de mergear; tras el merge, muévela con sus commits.",
+  "9. Dentro del repo se escribe solo con Edit/Write; los escapes KJ_ALLOW_* son de tu usuario, no tuyos.",
+];
+
+let raw = "";
+process.stdin.on("data", (d) => { raw += d; });
+process.stdin.on("end", () => {
+  try {
+    const { session_id: sid = "default", source } = JSON.parse(raw || "{}");
+    if (source !== "compact" && source !== "resume") process.exit(0);
+    const branch = branchOf() || "?";
+    const card = CARD.exec(branch)?.[0]?.toUpperCase() ?? "ninguna en la rama";
+    const pending = pendingMoves(load().sessions?.[sid]).map((p) => `${p.card ?? "?"} (PR #${p.pr})`);
+    const state = `Estado: rama ${branch}, card ${card}${pending.length ? `; cards mergeadas sin mover: ${pending.join(", ")}` : ""}.`;
+    const context = ["Karajan (reglas que la compactación se lleva):", ...RULES, state].join("\n");
+    process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: context } }));
+  } catch { /* never fails a session */ }
+  process.exit(0);
+});

package/src/harden/sentinel-hooks.js

@@ -8,7 +8,7 @@
  * hooks, which is why the guaranteed level requires Claude as host (ADR).
  */
 
-import { readFileSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { join } from "node:path";
@@ -136,6 +136,7 @@ import process from "node:process";
 import { 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";
 const ESCAPES = ["KJ_ALLOW_WRITE", "KJ_ALLOW_REWRITE", "KJ_ALLOW_NO_CARD", "KJ_ALLOW_NO_TESTS", "KJ_ALLOW_PII", "KJ_ALLOW_POLICY", "KJ_ALLOW_IDENTITY", "KJ_ALLOW_BOARD", "KJ_ALLOW_NO_RAG", "KJ_ALLOW_NO_VERIFY"];
 let raw = "";
 process.stdin.on("data", (d) => { raw += d; });
@@ -273,6 +274,15 @@ process.stdin.on("end", () => {
       // "not found" counts as failure (KJC-BUG-0154): a move that moved nothing must not
       // clear a pending — that would discard a LEGITIMATE one without touching the tracker.
       if (moved && CLOSING.includes(moved[2].toLowerCase()) && !/error|fail|not found/i.test(text)) clearPending(moved[1].toUpperCase());
+      // KJC-TSK-0917 (ADR 0014): the method's reminders, after the action that precedes
+      // the one each rule is about; at most once every 25 Bash actions each. Never a block.
+      const st = load();
+      const ss = session(st, sid);
+      ss.step = (ss.step || 0) + 1;
+      const due = remindersFor(cmdText, { seen: ss.reminded || {}, step: ss.step });
+      for (const r of due) (ss.reminded ||= {})[r.id] = ss.step;
+      save(st);
+      if (due.length) process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: due.map((r) => r.say).join(" ") } }));
       process.exit(0);
     }
     const file = input.file_path || input.notebook_path;
@@ -288,9 +298,23 @@ process.stdin.on("end", () => {
         s.escapes.push(e);
         (state.escape_events ||= []).push({ escape: e, tool, sid, ts: Date.now() });
       }
+    // 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.
+    let sizeNote = null;
+    if (bucket) {
+      const ps = spawnSync("kj", ["pr-size", "--json"], { cwd: ROOT, encoding: "utf8", timeout: 5000 });
+      let size = null;
+      try { size = JSON.parse(String(ps.stdout || "").trim().split(String.fromCharCode(10)).pop()); } catch { size = null; }
+      const crossed = size ? [200, 150].find((t) => size.added > t) : undefined;
+      if (crossed && (s.size_warned || 0) < crossed) {
+        s.size_warned = crossed;
+        sizeNote = "karajan sentinel: la rama ya suma " + size.added + " lineas contables (" + size.testAdded + " de tests); " + (crossed >= 200 ? "pasa el limite de 200 del CI: parte antes de seguir" : "pasa de 150: planea la particion ahora, no en el stage");
+      }
+    }
     const ids = Object.keys(state.sessions);
     if (ids.length > 5) delete state.sessions[ids.sort((a, b) => (state.sessions[a].at || 0) - (state.sessions[b].at || 0))[0]];
     save(state);
+    if (sizeNote) process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: "PostToolUse", additionalContext: sizeNote } }));
   } catch { /* fail open — the sentinel never breaks a tool call */ }
   process.exit(0);
 });
@@ -431,6 +455,10 @@ import { spawnSync } from "node:child_process";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { doc, CODE, TESTS, ROOT, BASE_BRANCHES, CARD, branchOf, foreignLane, load, save, session, violations, recordEscape, pendingMoves, pendingText } from "./sentinel-lib.mjs";
+// KJC-TSK-0915 (ADR 0014): the shell reader is a real, unit-tested module copied here as is.
+import { shellSegments, stripInertQuotes, stripTextOptionValues } from "./sentinel-shell.mjs";
+import { DISCARD_VERBS, discardOf, foreignLost } from "./sentinel-discard.mjs";
+import { shellWrites, writesRepo } from "./sentinel-bash-write.mjs";
 const EDIT_TOOLS = ["Write", "Edit", "MultiEdit", "NotebookEdit"];
 // KJC-BUG-0204: el comando real lleva flags EN MEDIO del verbo
 // (firebase --account a@b --project p deploy --only hosting:main), asi que la
@@ -449,6 +477,10 @@ process.stdin.on("data", (d) => { raw += d; });
 process.stdin.on("end", () => {
   try {
     const { session_id: sid = "default", tool_name: tool, tool_input: input = {}, transcript_path: transcript = null } = JSON.parse(raw);
+    // KJC-TSK-0920 (SNT-E): every deny ends with the same line, whatever gate it was.
+    process.on("exit", (code) => {
+      if (code === 2) console.error("karajan: Karajan gobierna y se le obedece. No rodees el gate ni cambies la politica para pasarlo; si te parece injusto, diselo a tu usuario o usa kj report-issue.");
+    });
     // Self-protection (KJC-TSK-0715) rules run BEFORE any escape, including
     // KJ_SENTINEL_OFF: the sentinel is not dismantled from inside a session —
     // only the human, editing outside it.
@@ -459,6 +491,28 @@ process.stdin.on("end", () => {
         console.error("karajan sentinel: ese fichero es parte del supervisor (" + relT + ") — solo el humano desmonta el sentinel, editalo fuera de la sesion." + doc("supervisor"));
         process.exit(2);
       }
+      // KJC-TSK-0920 (SNT-E): policies, gate settings and exclusions are the human's,
+      // like the supervisor: a session does not loosen the rules that govern it.
+      if ([".karajan/policy.yml", ".karajan/kj.config.yml", ".ragignore"].includes(relT) || relT.endsWith("/.ragignore")) {
+        console.error("karajan sentinel: " + relT + " es configuracion de gobierno (politicas, gates, exclusiones): la cambia tu usuario, no la sesion. Si un gate te parece injusto, proponselo a tu usuario o usa kj report-issue." + doc("governance"));
+        process.exit(2);
+      }
+      // KJC-BUG-0238 (#1886): de quien es cada cambio. La primera vez que la
+      // sesion toca un fichero se anota si estaba limpio: solo entonces un
+      // descarte posterior pierde nada mas que lo de la sesion. Antes de
+      // cualquier escape; git que falla cuenta como sucio (fail-closed).
+      if (relT && !relT.startsWith("..") && !relT.startsWith("/")) {
+        const st = load();
+        const touch = (session(st, sid).first_touch ||= {});
+        // hasOwn + defineProperty: a file named __proto__ or toString is a path, not a prototype key.
+        if (!Object.hasOwn(touch, relT)) {
+          // --ignored: a user's ignored .env is theirs too (git clean -x deletes it).
+          const gs = spawnSync("git", ["-C", ROOT, "status", "--porcelain", "--ignored", "--", relT], { encoding: "utf8" });
+          const value = gs.status === 0 && String(gs.stdout).trim() === "" ? "clean" : "dirty";
+          Object.defineProperty(touch, relT, { value, enumerable: true, writable: true, configurable: true });
+          save(st);
+        }
+      }
     }
     // Any Bash that NAMES the supervisor's files is denied — a write-verb
     // blocklist is bypassable (cp, dd, one-liners), and reading them is what
@@ -521,6 +575,28 @@ process.stdin.on("end", () => {
         process.exit(2);
       }
     }
+    // KJC-BUG-0238 (#1886): un agente no descarta cambios que no hizo. Sin
+    // escape y antes de KJ_SENTINEL_OFF: es perdida de datos del usuario, y
+    // guardarlo (git stash push) nunca pierde nada.
+    if (tool === "Bash") {
+      const cmdD = String(input.command || "");
+      // A git discard nested in $( ), <( ), backticks, eval, xargs or sh -c cannot be read: fail-closed.
+      const nested = ["$(", "<(", ">(", String.fromCharCode(96)].some((n) => cmdD.includes(n)) || /(^|[ ;&|])(eval|xargs|bash|sh|zsh|env)( |$)/.test(cmdD);
+      if (nested && /(^|[^a-z])git([^a-z]|$)/.test(cmdD) && DISCARD_VERBS.some((v) => cmdD.includes(v))) {
+        console.error("karajan sentinel: un descarte git dentro de $( ), backticks, eval, xargs o sh -c no es verificable — ejecutalo como comando simple." + doc("discard"));
+        process.exit(2);
+      }
+      const touch = load().sessions?.[sid]?.first_touch || {};
+      for (const words of shellSegments(cmdD)) {
+        const d = discardOf(words, ROOT);
+        const lost = d ? foreignLost(d, touch, ROOT) : [];
+        if (lost.length === 0) continue;
+        console.error(d.stash
+          ? "karajan sentinel: git stash drop/clear borra trabajo guardado que puede no ser de esta sesion — pideselo a tu usuario." + doc("discard")
+          : "karajan sentinel: ese comando descarta cambios que esta sesion no hizo (" + lost.slice(0, 5).join(", ") + (lost.length > 5 ? ", +" + (lost.length - 5) : "") + ") — pueden ser trabajo sin commitear de tu usuario. Si estorban, guardalos recuperables (git stash push -- <ficheros>) y avisale; si el cambio es tuyo sobre su trabajo, deshazlo con Edit. Sin escape: es perdida de datos." + doc("discard"));
+        process.exit(2);
+      }
+    }
     if (process.env.KJ_SENTINEL_OFF === "1") process.exit(0);
     // KJC-BUG-0142: cada deny anuncia su escape como prefijo del comando
     // (KJ_ALLOW_X=1 cmd), pero el hook corre con el env del HOST — el
@@ -733,7 +809,8 @@ 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]*$/;
-      if (!READONLY.test(cmd)) {
+      // KJC-BUG-0243: operators inside inert quotes (grep -e "a|b") do not chain anything.
+      if (!READONLY.test(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
@@ -824,7 +901,9 @@ process.stdin.on("end", () => {
           if (q !== null) return true; // comilla sin cerrar: no verificable
           return flush();
         };
-        if (/\\$\\(|\`/.test(cmd) || quotedPathWithSpaces(cmd)) {
+        // KJC-BUG-0243: inert quoted text is not a substitution, and the prose value
+        // of a text option (--title, -m...) is not a path.
+        if (/\\$\\(|\`/.test(stripInertQuotes(cmd)) || quotedPathWithSpaces(stripTextOptionValues(cmd))) {
           if (escOn("KJ_ALLOW_CROSS_LANE")) { recordEscape(sid, "KJ_ALLOW_CROSS_LANE", tool); }
           else {
             console.error("karajan sentinel: sustitucion de comandos o ruta entrecomillada con espacios en un comando mutador — no verificable por el guard de carriles (MONO-0); usa valores/rutas LITERALES sin sustitucion (o KJ_ALLOW_CROSS_LANE=1, queda registrado)." + doc("cross-lane"));
@@ -854,6 +933,21 @@ process.stdin.on("end", () => {
         }
       }
     }
+    // KJC-BUG-0237 (#1886): the repo is written through Edit/Write only, the path every gate
+    // guards. After the lane guard, whose message is the precise one for another lane.
+    if (tool === "Bash") {
+      let moved = false; // after cd/pushd/popd, a relative target cannot be placed: fail-closed
+      // $( ) and backticks run even inside double quotes: their bodies, read from the raw text, are commands too.
+      const raw = String(input.command || "");
+      const subs = [...[...raw.matchAll(/[$][(]([^()]*)[)]/g)].map((m) => m[1]), ...raw.split(String.fromCharCode(96)).filter((_, k) => k % 2 === 1)];
+      for (const words of [...shellSegments(raw), ...subs.flatMap((s) => shellSegments(s))]) {
+        if (["cd", "pushd", "popd"].includes(words[0])) moved = true;
+        const inRepo = shellWrites(words).filter((t) => writesRepo(t, ROOT) || (moved && !t.startsWith("/")));
+        if (inRepo.length === 0) continue;
+        console.error("karajan sentinel: escribir ficheros del repo desde Bash (" + inRepo.slice(0, 3).join(", ") + ") se salta los gates de Edit/Write — usa la tool Edit/Write; para renombrar, git mv; fuera del repo (/tmp, scratchpad) Bash es libre." + doc("bash-write"));
+        process.exit(2);
+      }
+    }
     // KJC-TSK-0734 (PL-B): con .karajan/policy.yml presente, la evaluacion
     // la hace el MOTOR via kj policy eval --strict (exit 2 = deny, contrato
     // PL-A); los defaults del supervisor viven en el motor y el check
@@ -1129,6 +1223,14 @@ const SCRIPT_BODIES = {
   "posttooluse.mjs": POST_BODY,
   "stop.mjs": STOP_BODY,
   "pretooluse-sentinel.mjs": PRETOOL_BODY,
+  // KJC-TSK-0915 (ADR 0014): real modules, copied byte for byte under the SAME name
+  // (so they can import each other in both places). Being here, the installed
+  // record, the tamper check and the human seal cover them as well.
+  "sentinel-shell.mjs": readFileSync(new URL("./sentinel/sentinel-shell.mjs", import.meta.url), "utf8"),
+  "sentinel-discard.mjs": readFileSync(new URL("./sentinel/sentinel-discard.mjs", import.meta.url), "utf8"),
+  "sentinel-bash-write.mjs": readFileSync(new URL("./sentinel/sentinel-bash-write.mjs", import.meta.url), "utf8"),
+  "sentinel-reminders.mjs": readFileSync(new URL("./sentinel/sentinel-reminders.mjs", import.meta.url), "utf8"),
+  "sessionstart.mjs": readFileSync(new URL("./sentinel/sessionstart.mjs", import.meta.url), "utf8"),
 };
 
 /**
@@ -1232,6 +1334,7 @@ export function verifySentinelScripts({ projectDir, readFileFn = readFileSync, g
   // first attempt at this fix, and the review was right to reject it.
   const sealed = sealedByPath(root, gitShowFn);
   const ownRecord = readInstalledRecord(dir);
+  const hasRecord = existsSync(join(dir, INSTALLED_RECORD));
   const drift = [];
   const tampered = [];
   const regenerated = [];
@@ -1240,6 +1343,10 @@ export function verifySentinelScripts({ projectDir, readFileFn = readFileSync, g
     const hash = text === undefined ? null : sha256(text);
     if (hash && sealed.get(`.karajan/harness/${name}`) === hash) drift.push(name);
     else if (hash && ownRecord[name] === hash) regenerated.push(name);
+    // KJC-TSK-0915: absent from an install kj RECORDED (installed.json exists), never
+    // recorded and never sealed = a guard newer than this install, not a deleted
+    // one. Writing it only adds. A dir with no record is not a kj install at all.
+    else if (!hash && hasRecord && !Object.hasOwn(ownRecord, name) && !sealed.has(`.karajan/harness/${name}`)) regenerated.push(name);
     else tampered.push(name);
   }
   // KJC-BUG-0224 caso 1: lo que kj escribio y nadie sello ni toco se pone al
@@ -1319,7 +1426,13 @@ export function installSentinelHooks({ projectDir = process.cwd(), logger = cons
       // edit matchers wired, the board-sync recorder never ran in production.
       { event: "PostToolUse", matcher: "Bash", script: "posttooluse.mjs" },
       { event: "PostToolUse", matcher: "mcp__.*__update_card", script: "posttooluse.mjs" },
+      // KJC-BUG-0236 (#1886): the rag-first ledger records MCP answers here;
+      // unwired, the official tool never satisfied the gate.
+      { event: "PostToolUse", matcher: "mcp__.*__kj_rag_query", script: "posttooluse.mjs" },
       { event: "Stop", script: "stop.mjs" },
+      // KJC-TSK-0918 (ADR 0014): the critical rules back after a compaction or a resume.
+      { event: "SessionStart", matcher: "compact", script: "sessionstart.mjs" },
+      { event: "SessionStart", matcher: "resume", script: "sessionstart.mjs" },
     ],
   });
   return { scripts: [lib, post, stop, pre], wired, deferred };

package/src/harden/supervisor-commit.js

@@ -117,6 +117,16 @@ export async function commitSupervisorRegeneration({
       `harden --commit es un acto humano y este proceso desciende de un agente (${anc.match}) — ni con pty falso ni con el entorno limpio (ADR 0009)`,
     );
   }
+  const run = gitFn || ((args) => execFileSync("git", args, { cwd: projectDir, encoding: "utf8" }));
+  // KJC-BUG-0244 (grebla #958): el commit sellado solo lleva el supervisor, pero
+  // un stage ajeno se quedaba en esta rama y el siguiente commit caía aquí con la
+  // card equivocada. Se para ANTES de pedir nada al humano y se nombra.
+  const foreign = run(["diff", "--cached", "--name-only"]).split("\n").filter((f) => f && !f.startsWith(HOOKS_PREFIX) && f !== PROVENANCE_FILE);
+  if (foreign.length > 0) {
+    throw new Error(
+      `harden --commit: hay cambios en el stage que no son del supervisor (${foreign.slice(0, 5).join(", ")}${foreign.length > 5 ? ", …" : ""}): commitéalos en su rama o sácalos del stage (git restore --staged <ficheros>) antes de sellar`,
+    );
+  }
   // Capa 4 (test adversarial 6-sep: un huérfano a init con pty falso y
   // prompts a ciegas llegó hasta aquí): nonce aleatorio tecleado de vuelta.
   // Un alimentador ciego no conoce el código; automatizar su lectura exige
@@ -126,7 +136,6 @@ export async function commitSupervisorRegeneration({
   if (answer !== nonce) {
     throw new Error(`harden --commit: confirmación humana fallida (esperaba "${nonce}") — ADR 0009`);
   }
-  const run = gitFn || ((args) => execFileSync("git", args, { cwd: projectDir, encoding: "utf8" }));
   const drift = supervisorDrift({ projectDir, gitFn: run });
   // La provenance describe SIEMPRE el estado COMPLETO del supervisor (cazado
   // en el primer estreno real: un sello parcial pisaba al anterior y dejaba

package/src/rag/indexable.js

@@ -8,7 +8,8 @@
  * text windows (chunkSource already does).
  */
 import { execFileSync } from "node:child_process";
-import { closeSync, lstatSync, openSync, readSync } from "node:fs";
+import { closeSync, lstatSync, openSync, readFileSync, readSync, statSync } from "node:fs";
+import { join } from "node:path";
 
 import { matchesAny } from "@karajan-family/governance";
 
@@ -40,6 +41,35 @@ const skipsFor = (projectDir) => {
   return skipCache.get(key);
 };
 
+/**
+ * KJC-TSK-0900: `.ragignore` at the project root, gitignore syntax, versioned so
+ * the whole team inherits it. `dir/` is a folder anywhere, `*.csv` an extension
+ * anywhere, `/data` anchored to the root, a path with a slash is from the root.
+ * `!` negation is not supported (said in the docs). Re-read when it changes.
+ */
+const ragignoreCache = new Map();
+export function ragignoreGlobs(projectDir) {
+  if (!projectDir) return [];
+  const file = join(projectDir, ".ragignore");
+  let mtime;
+  try { mtime = statSync(file).mtimeMs; } catch { return []; }
+  const hit = ragignoreCache.get(file);
+  if (hit?.mtime === mtime) return hit.globs;
+  const globs = [];
+  for (const raw of readFileSync(file, "utf8").split("\n")) {
+    let p = raw.trim();
+    if (!p || p.startsWith("#") || p.startsWith("!")) continue;
+    const dirOnly = p.endsWith("/");
+    p = p.replace(/^\/+|\/+$/g, "");
+    if (!p) continue;
+    const base = raw.trim().startsWith("/") || p.includes("/") ? p : `**/${p}`;
+    globs.push(`${base}/**`);
+    if (!dirOnly) globs.push(base);
+  }
+  ragignoreCache.set(file, { mtime, globs });
+  return globs;
+}
+
 /** What the project keeps out of its index: `rag.exclude`, repo-relative globs. */
 export const ragExclude = (config) => (Array.isArray(config?.rag?.exclude) ? config.rag.exclude : []);
 
@@ -63,6 +93,7 @@ function looksBinary(abs) {
 export function indexableReason(rel, abs, { exclude = [], projectDir = null, skip = skipsFor(projectDir) } = {}) {
   if (skip(rel)) return `${rel} lives under a path the indexer always skips`;
   if (matchesAny(rel, exclude)) return `${rel} is excluded by the project's rag.exclude`;
+  if (matchesAny(rel, ragignoreGlobs(projectDir))) return `${rel} is excluded by the project's .ragignore`;
   if (SENSITIVE.some((re) => re.test(rel))) return `${rel} may hold secrets, and the embedder can be a remote service`;
   if (GENERATED.some((re) => re.test(rel))) return `${rel} is a generated file (lockfile, minified, sourcemap or snapshot)`;
   let st;

package/src/rag/migrate.js

@@ -7,11 +7,22 @@
  * toca: borrarla es decision del usuario, no efecto de una migracion.
  */
 import { existsSync } from "node:fs";
+import { sep } from "node:path";
 
 import { openVecStore, insertChunk, getLastIndexedCommit, setLastIndexedCommit } from "./vec-store.js";
 
 export const countProjectChunks = (db, slug) => db.prepare("SELECT COUNT(*) AS n FROM chunks WHERE project_slug = ?").get(slug).n;
 
+/**
+ * KJC-BUG-0258: chunks of the project's OWN files (sources under projectDir), as
+ * opposed to its plans and briefs. A prefix compare, not LIKE: paths may hold % or _.
+ */
+export const countProjectSources = (db, slug, projectDir) => {
+  // path.sep: sources are stored as native paths (backslashes on Windows).
+  const prefix = projectDir.replace(/[\\/]+$/, "") + sep;
+  return db.prepare("SELECT COUNT(*) AS n FROM chunks WHERE project_slug = ? AND substr(source, 1, ?) = ?").get(slug, prefix.length, prefix).n;
+};
+
 /**
  * KJC-TSK-0882: que decir cuando el indice del proyecto no tiene nada suyo.
  * Si la base global tiene sus chunks, migrar (segundos); si no, indexar.
@@ -29,9 +40,12 @@ export function emptyIndexRemedy({ slug, legacyPath, dim = 768 }) {
 }
 
 /**
- * @returns {{state: "migrated"|"already"|"nothing", migrated: number, reason: string}}
+ * KJC-BUG-0255: `keep(source)` is the indexer's criterion today (generated,
+ * excluded, .ragignore, sensitive, gone). The global index was filled before
+ * those rules, so copying it blind brought vendor/*.min.js along as noise.
+ * @returns {{state: "migrated"|"already"|"nothing", migrated: number, skipped?: number, reason: string}}
  */
-export function migrateProjectIndex({ slug, legacyPath, targetPath, dim = 768 }) {
+export function migrateProjectIndex({ slug, legacyPath, targetPath, dim = 768, keep = () => true }) {
   const nothing = { state: "nothing", migrated: 0, reason: `the global index holds nothing for ${slug}: kj rag index --with-sources` };
   if (!existsSync(legacyPath)) return nothing;
 
@@ -49,8 +63,10 @@ export function migrateProjectIndex({ slug, legacyPath, targetPath, dim = 768 })
       const rows = legacy.prepare("SELECT id, source, kind, text, metadata, content_hash FROM chunks WHERE project_slug = ?").all(slug);
       if (rows.length === 0) return nothing;
       const vecOf = legacy.prepare("SELECT embedding FROM vec_chunks WHERE rowid = ?");
+      let skipped = 0;
       const copy = target.transaction(() => {
         for (const r of rows) {
+          if (!keep(r.source)) { skipped++; continue; }
           const raw = vecOf.get(BigInt(r.id))?.embedding;
           if (!raw) continue; // un chunk sin vector no se puede buscar: no se inventa
           const embedding = new Float32Array(raw.buffer.slice(raw.byteOffset, raw.byteOffset + raw.byteLength));
@@ -63,7 +79,8 @@ export function migrateProjectIndex({ slug, legacyPath, targetPath, dim = 768 })
       const migrated = countProjectChunks(target, slug);
       const parts = [`${migrated} chunks of ${slug} copied with their embeddings`];
       if (stamp) parts.push(`indexed at ${stamp.slice(0, 9)}`);
-      return { state: "migrated", migrated, reason: parts.join(", ") };
+      if (skipped) parts.push(`${skipped} left out (the indexer would not take them today: generated, excluded or gone)`);
+      return { state: "migrated", migrated, skipped, reason: parts.join(", ") };
     } finally {
       legacy.close();
     }

package/src/review/comment-only.js

@@ -0,0 +1,93 @@
+/**
+ * KJC-BUG-0235 — are the lines a diff ADDS only comments? A cleanup deletes
+ * code and corrects the comments that were left lying about it; those added
+ * lines carry no behavior to test. Decided by scanning the resulting file, not
+ * by a line's first characters: " * factor" can continue a product. Strings are
+ * kept as code, so a docstring or a `//` inside a string is never a comment.
+ * An unknown syntax is not judged: everything counts as code (conservative).
+ */
+import { extname } from "node:path";
+
+// JSX/TSX and PHP are out: a `//` in a JSX text child or outside `<?php` is
+// rendered content. JSX inside a .js/.ts file is detected below.
+const C_STYLE = new Set([".js", ".mjs", ".cjs", ".ts", ".java", ".cs", ".go", ".kt", ".swift", ".c", ".cc", ".cpp", ".h", ".hpp", ".rs", ".scala"]);
+// Shell and Ruby are left out on purpose: a `#` line inside a heredoc is
+// content, not a comment, and this scanner does not parse heredocs.
+const HASH_STYLE = new Set([".py"]);
+const OPENER_AFTER = new Set([";", "{", "}", "(", ")", ",", "=", ":", "?", "!", "&", "|"]);
+
+/** @returns {Set<number>|null} 1-based lines holding code, or null for an unknown syntax */
+export function codeLines(content, file) {
+  const ext = extname(file).toLowerCase();
+  const cStyle = C_STYLE.has(ext);
+  if (!cStyle && !HASH_STYLE.has(ext)) return null;
+  const lines = new Set();
+  let line = 1;
+  let state = "code"; // code | line | block | string
+  let quote = "";
+  const s = String(content);
+  let step; // characters consumed by the current iteration (set in the body)
+  let prev = ""; // last non-space character seen in code on this line
+  let word = ""; // identifier being read in code
+  let lastWord = ""; // last complete identifier in code
+  for (let i = 0; i < s.length; i += step) {
+    const c = s[i];
+    const next = s[i + 1];
+    step = 1;
+    if (c === "\n") prev = "";
+    if (c === "\n") {
+      line++;
+      if (state === "line") state = "code";
+      // A line inside a multi-line string is part of its value, even if blank.
+      if (state === "string") lines.add(line);
+    } else if (state === "block") {
+      if (c === "*" && next === "/") { state = "code"; step = 2; }
+    } else if (state === "string") {
+      lines.add(line);
+      if (c === "\\") {
+        // An escaped newline continues the string on the next physical line: count it.
+        if (next === "\n") { line++; lines.add(line); }
+        step = 2;
+      } else if (c === quote) {
+        state = "code";
+      }
+    } else if (state === "code") {
+      // A comment opens only where one can: line start or after a separator.
+      // After `\`, `[` or an identifier a slash may belong to a regex literal
+      // (/a\/*b/, /[/*]/), so it is taken as code: in doubt, code.
+      const canOpen = prev === "" || OPENER_AFTER.has(prev);
+      if (/[\w$]/.test(c)) word += c;
+      else if (word) { lastWord = word; word = ""; }
+      // A tag where an expression starts (`= <div>`, `return <App />`) is JSX:
+      // its text children are rendered, so this file is not judged.
+      if (cStyle && c === "<" && /[A-Za-z/>]/.test(next ?? "") && (canOpen || lastWord === "return")) return null;
+      if (cStyle && canOpen && c === "/" && next === "/") state = "line";
+      else if (cStyle && canOpen && c === "/" && next === "*") { state = "block"; step = 2; }
+      else if (!cStyle && c === "#") state = "line";
+      else if (c === '"' || c === "'" || c === "`") { state = "string"; quote = c; lines.add(line); }
+      else if (!/\s/.test(c)) lines.add(line);
+      if (state === "code" && !/\s/.test(c)) prev = c;
+    }
+  }
+  return lines;
+}
+
+const COMMENT_START = /^(\/\/|\/\*|\*|#)/;
+
+/**
+ * Every added line (1-based, in the resulting file) is a comment or blank.
+ * Two checks must agree: the scanner says no code on the line AND the line
+ * itself starts like a comment (or is blank). The second one is a net against
+ * a scanner mistake, and it costs a knowingly accepted false negative: a block
+ * comment continuation without a leading `*` counts as code. Agreed criterion
+ * (KJC-BUG-0235): better a cleanup that still asks for tests than code let through.
+ */
+export function addedAreCommentsOnly(content, addedLines, file) {
+  const code = codeLines(content, file);
+  if (!code) return false;
+  const text = String(content).split("\n");
+  return [...addedLines].every((n) => {
+    const t = (text[n - 1] ?? "").trim();
+    return !code.has(n) && (t === "" || COMMENT_START.test(t));
+  });
+}

package/src/review/tests-with-code.js

@@ -42,8 +42,11 @@ export function checkTestsWithCode({ config = {}, stagedFiles = [], numstat = nu
   // cleanup PRs). Callers that only know names keep the old behavior.
   if (Array.isArray(numstat)) {
     const bySource = numstat.filter((n) => sources.includes(n.file));
-    if (bySource.length === sources.length && bySource.every((n) => (n.added || 0) === 0)) {
-      return { ok: true, mode: "delete-only", sources, reason: "every touched source only removes lines — deleting is not new behavior" };
+    // KJC-BUG-0235: a cleanup also corrects the comments the deletion left
+    // lying; lines the caller PROVED to be comments carry no behavior either.
+    const cleanup = (n) => (n.added || 0) === 0 || n.commentOnly === true;
+    if (bySource.length === sources.length && bySource.every(cleanup)) {
+      return { ok: true, mode: "delete-only", sources, reason: "every touched source only removes lines or corrects comments — deleting is not new behavior" };
     }
   }