karajan-code 4.35.0 → 4.36.0

package/src/commands/harden.js

@@ -17,6 +17,7 @@ import { createWizard, isTTY } from "../utils/wizard.js";
 import { commitSupervisorRegeneration } from "../harden/supervisor-commit.js";
 import { installConfigsForRoots } from "../harden/config-engine.js";
 import { installGuidelines } from "../harden/guidelines-engine.js";
+import { maybeRulesyncGenerate } from "../utils/rulesync.js";
 import { commandsForLanguage } from "../harden/hook-commands.js";
 import { installHooks } from "../harden/harden-engine.js";
 import { installHarnessHooks } from "../harden/harness-hooks.js";
@@ -76,6 +77,18 @@ export async function resolveCmds(projectDir, language) {
   return cmds;
 }
 
+/**
+ * KJC-BUG-0233: loadConfig returns `{ config, ... }`; reading `base_branch` off
+ * the result was always undefined, so the guard always protected "main".
+ */
+export async function resolveBaseBranch(projectDir, load = loadConfig) {
+  try {
+    return (await load(projectDir))?.config?.base_branch || "main";
+  } catch {
+    return "main"; // no kj config: the default stands
+  }
+}
+
 export async function hardenCommand({
   projectDir = process.cwd(),
   profile = "standard",
@@ -139,10 +152,7 @@ export async function hardenCommand({
   // KJC-TSK-0648: branch-first guard — the base branch only moves via PR.
   // Resolved from the project's kj config (default "main"); best-effort so
   // harden keeps working on repos that never ran kj init.
-  let baseBranch = "main";
-  try {
-    baseBranch = (await loadConfig(projectDir))?.base_branch || "main";
-  } catch { /* no kj config — default stands */ }
+  const baseBranch = await resolveBaseBranch(projectDir);
   let result;
   try {
     result = await installHooks({ projectDir, profile, cmds, dryRun, baseBranch });
@@ -177,6 +187,12 @@ export async function hardenCommand({
   // KJC-BUG-0199 (issue #1773): the same detected language the workflows and
   // the configs already use — a Python project must not be told to use `const`.
   const gl = withGuidelines ? installGuidelines({ projectDir, language: roots[0]?.language ?? null, dryRun }) : null;
+  // KJC-TSK-0879: in a Rulesync repo, spread the rules only if the project opted in.
+  if (withGuidelines && !dryRun) {
+    let kjConfig = null;
+    try { kjConfig = (await loadConfig(projectDir))?.config; } catch { /* no kj config: not opted in */ }
+    maybeRulesyncGenerate({ projectDir, config: kjConfig, logger });
+  }
   const out = {
     ok: true,
     ...result,
@@ -202,6 +218,12 @@ export async function hardenCommand({
     logger.info?.(`  • ${g.file}: ${g.action}`);
     // KJC-BUG-0206: quitar reglas no puede leerse como "updated" y nada más.
     if (g.shrank) logger.warn?.(`    ⚠ ${g.file} queda con MENOS reglas que antes — revisa si el lenguaje detectado es el que crees (kj check lo dice)`);
+    // KJC-BUG-0232: cuales. Si una es tuya, vivia dentro del bloque: va fuera.
+    if (g.removed?.length) {
+      for (const line of g.removed.slice(0, 10)) logger.warn?.(`      - ${line.length > 120 ? `${line.slice(0, 117)}...` : line}`);
+      if (g.removed.length > 10) logger.warn?.(`      (+${g.removed.length - 10} más)`);
+      logger.warn?.("      Si alguna es vuestra, estaba dentro del bloque gestionado: recuperadla de git y ponedla fuera de él.");
+    }
   }
   if (!dryRun) logger.info?.("core.hooksPath set. Verify later with `kj check`.");
   // IDN-A (KJC-TSK-0762): a hardened clone declares who works it. Captured

package/src/commands/init.js

@@ -344,7 +344,8 @@ async function runWizard(config, logger) {
     config.sonarqube.enabled = enableSonar;
     logger.info(`  -> SonarQube: ${enableSonar ? "enabled" : "disabled"}`);
 
-    const enableHuBoard = await wizard.confirm("Enable the HU Board — a local web UI to track user stories (HUs)?", false);
+    // KJC-TSK-0884: on by default, like Sonar; answering no is a declared opt-out.
+    const enableHuBoard = await wizard.confirm("Enable the HU Board — a local web UI to track user stories (HUs)?", true);
     config.hu_board = config.hu_board || {};
     config.hu_board.enabled = enableHuBoard;
     if (enableHuBoard) {

package/src/commands/plan/generate.js

@@ -512,13 +512,11 @@ async function planGenerateImpl({ task, config, logger, json, context, runLog, f
   // vitest / test mode, and never when `--json` is active.
   if (plan.hus.length > 0 && !process.env.VITEST && process.env.NODE_ENV !== "test") {
     try {
-      const { startBoard, renderBoardBanner } = await import("../board.js");
-      const { projectSlug: slugFor } = await import("../../plan/plan-store.js");
+      const { startBoard, renderBoardBanner, boardSlug } = await import("../board.js");
       const boardPort = config?.hu_board?.port ?? 4000;
-      // `projectSlug` scopes the board URL to this project's view
-      // (`#board/<slug>`) instead of the global "All projects" dashboard.
-      // The hash route opens the board pre-filtered to that project.
-      const boardResult = await startBoard(boardPort, { projectSlug: slugFor(projectDir) });
+      // KJC-TSK-0884: this project's scoped view (/p/<slug>), the parent
+      // repo's even from a worktree lane, never the global dashboard.
+      const boardResult = await startBoard(boardPort, { projectSlug: boardSlug(projectDir) });
       const status = boardResult.alreadyRunning ? "already running" : "started";
       console.log(renderBoardBanner({ url: boardResult.url, status, projectName: plan.name }));
     } catch (err) {

package/src/commands/rag.js

@@ -1,19 +1,49 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, join, relative } from "node:path";
 // KJC-PCS-0049 Step 6 — `kj rag` command group. Two subcommands:
 //   kj rag index [--project <slug>] [--with-sources]
 //   kj rag query <text>   [--scope plans|code|onboarding|all] [--top-k N] [--json]
 // Closes the v2.22.0 RAG MVP end-to-end from the terminal.
-import { openVecStore, countChunks, projectSlug, getLastIndexedCommit, setLastIndexedCommit } from "../rag/vec-store.js";
+import { countChunks, deleteChunksBySource, projectSlug, getLastIndexedCommit, setLastIndexedCommit } from "../rag/vec-store.js";
 import { makeGovernedEmbedder } from "../rag/governed-embedder.js";
-import { indexProject, indexProjectDelta } from "../rag/indexer.js";
+import { indexFile, indexProject, indexProjectDelta, sourceKind } from "../rag/indexer.js";
+import { indexableReason, ragExclude } from "../rag/indexable.js";
 import { fileIndexState } from "../rag/coverage.js";
 import { query } from "../rag/retriever.js";
 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 { openLibraryStore, openProjectStore, projectDbPath } from "../rag/project-store.js";
 
+// KJC-TSK-0882 (ADR 0011): el indice es del proyecto, no de la maquina.
 function openDb(config) {
-  return openVecStore({ dim: config?.rag?.embedder?.dim || 768 });
+  return openProjectStore({ projectDir: config?.projectDir || process.cwd(), dim: config?.rag?.embedder?.dim || 768 });
+}
+
+async function indexFiles({ files, projectDir, db, embedder, slug, logger, json, exclude }) {
+  const totals = { indexed: 0, failed: 0, files: 0, deleted: 0 };
+  for (const file of files) {
+    const abs = isAbsolute(file) ? file : join(projectDir, file);
+    if (!existsSync(abs)) {
+      totals.deleted += deleteChunksBySource(db, abs); // gone from disk: gone from the index
+      continue;
+    }
+    // KJC-TSK-0891: the same criterion and kind as the full walk, or the
+    // remedy rag-first names would index nothing for a .mdx or a .astro.
+    const out = indexableReason(relative(projectDir, abs), abs, { exclude, projectDir });
+    if (out) {
+      logger.warn?.(`[rag] ${out}: not indexed`);
+      continue;
+    }
+    const r = await indexFile(abs, { db, embedder, logger, project: slug, kind: sourceKind(abs) });
+    totals.indexed += r.indexed; totals.failed += r.failed; totals.files += 1;
+  }
+  const deleted = totals.deleted ? `, ${totals.deleted} chunks deleted` : "";
+  if (json) process.stdout.write(`${JSON.stringify(totals)}\n`);
+  else logger.info(`[rag] indexed ${totals.indexed} chunk(s) across ${totals.files} file(s) (${totals.failed} failed${deleted})`);
+  return totals;
 }
 
 export async function ragIndexCommand({ config, logger, flags = {} }) {
@@ -22,6 +52,9 @@ export async function ragIndexCommand({ config, logger, flags = {} }) {
   try {
     const slug = projectSlug(projectDir);
     const embedder = makeGovernedEmbedder(config);
+    // KJC-TSK-0891: exactly these files. The remedy rag-first names for a file
+    // missing from the index: `--since auto` only reaches what changed.
+    if (flags.file?.length) return await indexFiles({ files: flags.file, projectDir, db, embedder, slug, logger, json: flags.json, exclude: ragExclude(config) });
     const sinceFlag = flags.since;
     // KJC-TSK-0455 — `--since auto` resolves to the last commit we indexed;
     // an explicit ref is honoured as-is. Without a baseline (first-time
@@ -35,7 +68,7 @@ export async function ragIndexCommand({ config, logger, flags = {} }) {
     let totals;
     if (since) {
       try {
-        totals = await indexProjectDelta(projectDir, { db, embedder, since, logger });
+        totals = await indexProjectDelta(projectDir, { db, embedder, since, logger, exclude: ragExclude(config) });
       } catch (err) {
         logger.warn?.(`[rag] delta index failed (${err.message}); falling back to full index`);
         totals = null;
@@ -46,13 +79,17 @@ export async function ragIndexCommand({ config, logger, flags = {} }) {
         db, embedder,
         karajanHome: getKarajanHome(), logger,
         withSources: Boolean(flags.withSources),
+        exclude: ragExclude(config),
       });
     }
     if (totals.head) setLastIndexedCommit(db, slug, totals.head);
     // KJC-TSK-0697 — the library corpus refreshes on every index run.
     // Best-effort and cheap: a handful of cards, content-hash dedup.
+    // KJC-TSK-0883: el canon de la maquina a su base; las fichas del proyecto, a la suya.
     try {
-      await indexLibrary({ db, embedder, logger, projectDir });
+      const lib = openLibraryStore({ dim: config?.rag?.embedder?.dim || 768 });
+      try { await indexLibrary({ db: lib, embedder, logger, scope: "machine" }); } finally { lib.close(); }
+      await indexLibrary({ db, embedder, logger, projectDir, scope: "project", project: slug });
     } catch (err) {
       logger.warn?.(`[rag] library index failed: ${err.message}`);
     }
@@ -87,7 +124,8 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
   // (--no-rag-update / config.rag.autoUpdate); failures degrade to a warn
   // inside maybeAutoUpdate and the query proceeds with the current index.
   await maybeAutoUpdate({ projectDir: config?.projectDir || process.cwd(), config, logger, flags });
-  const db = openDb(config);
+  // KJC-TSK-0883: --library abre la base del canon, no la del proyecto.
+  const db = flags.library ? openLibraryStore({ dim: config?.rag?.embedder?.dim || 768 }) : openDb(config);
   try {
     const topK = Math.max(1, Number(flags.topK) || 5);
     const scope = flags.scope || "all";
@@ -107,9 +145,12 @@ export async function ragQueryCommand({ text, config, logger, flags = {} }) {
     // deterministic recovery signal. The CLI was emitting just `[]`, which
     // is indistinguishable from "query returned zero hits over a populated
     // store" and forced consumers to parse stderr.
-    if (countChunks(db) === 0) {
-      logger.warn("[rag] No chunks indexed yet. Run 'kj rag index' first.");
-      if (flags.json) process.stdout.write(`${JSON.stringify({ hits: [], empty: true, topK, scope })}\n`);
+    // KJC-TSK-0882: cuenta lo de ESTE proyecto; chunks ajenos no son respuesta.
+    if (countChunks(db) === 0 || (project && countProjectChunks(db, project) === 0)) {
+      // La library se rellena en cada `kj rag index`; migrar la llevaria al proyecto.
+      const remedy = library ? "kj rag index" : emptyIndexRemedy({ slug: project, legacyPath: join(getKarajanHome(), "rag.db"), dim: config?.rag?.embedder?.dim || 768 });
+      logger.warn(`[rag] ${library ? "the library index" : "this project's index"} holds no chunks of ${project || "any project"}: this is not an answer, run ${remedy}`);
+      if (flags.json) process.stdout.write(`${JSON.stringify({ hits: [], empty: true, topK, scope, remedy })}\n`);
       return [];
     }
     const mode = flags.mode || "hybrid";
@@ -183,7 +224,7 @@ export async function ragCoversCommand({ file, config, flags = {} }) {
   const projectDir = config?.projectDir || process.cwd();
   const db = openDb(config);
   try {
-    const state = fileIndexState(projectDir, file, { db });
+    const state = fileIndexState(projectDir, file, { db, exclude: ragExclude(config) });
     if (flags.json) process.stdout.write(`${JSON.stringify(state)}\n`);
     else process.stdout.write(`${state.state}: ${state.reason}\n`);
     if (!state.canAnswer) process.exitCode = 1;
@@ -192,3 +233,21 @@ export async function ragCoversCommand({ file, config, flags = {} }) {
     db.close();
   }
 }
+
+/**
+ * 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
+ * volver a embeber. La base global no se toca.
+ */
+export async function ragMigrateCommand({ config, flags = {} }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const res = migrateProjectIndex({
+    slug: projectSlug(projectDir),
+    legacyPath: join(getKarajanHome(), "rag.db"),
+    targetPath: projectDbPath(projectDir),
+    dim: config?.rag?.embedder?.dim || 768,
+  });
+  if (flags.json) process.stdout.write(`${JSON.stringify(res)}\n`);
+  else process.stdout.write(`rag migrate: ${res.state} — ${res.reason}\n`);
+  return res;
+}

package/src/commands/review-gate.js

@@ -188,6 +188,14 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   // KJC-TSK-0687 (MG-B): the verifiable half of TDD — sources without a
   // single test change warn (block via method_gates.tests_with_code).
   const changedFiles = (await rawDiff(flags.range, ["--name-only"])).split("\n").map((f) => f.trim()).filter(Boolean);
+  // KJC-BUG-0229: un fichero BORRADO no es una fuente que el scan pueda indexar
+  // ni sobre la que el RAG pueda responder, asi que exigirlo era pedir lo
+  // imposible: una PR que retiraba 45 ficheros se paro dos veces y acumulo tres
+  // excepciones por la misma causa mecanica. Los requisitos de Sonar y de RAG
+  // se evaluan sobre lo que sigue VIVO tras el cambio (A, C, M, R); policy, LOC
+  // y tests-with-code siguen viendo el diff entero, porque ahi un borrado si
+  // cuenta. El borrado danino lo cubre la review cruzada, que lee todo el diff.
+  const liveFiles = (await rawDiff(flags.range, ["--name-only", "--diff-filter=ACMR"])).split("\n").map((f) => f.trim()).filter(Boolean);
 
   // KJC-TSK-0688 (MG-C) + KJC-TSK-0691 (MG-E): oversized-diff policy.
   // Field case: a 522-line PR sailed past the warning with a
@@ -357,6 +365,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
       }
     }
     let res = await checkVerdict(projectDir, diff);
+    if (res.note) console.log(`ℹ ${res.note}`);
     // KJC-TSK-0838: a reviewed diff with code enters only if the verdict's
     // sonar block proves the analysis ran and covered every staged source.
     // The headless pipeline stamps its verdict after its own sonar stage and
@@ -371,7 +380,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
         res = { ok: false, verdict: res.verdict, reason: `Sonar is mandatory for code — ${why}` };
       }
     } else if (res.ok) {
-      const req = checkSonarRequirement({ config, stagedFiles: changedFiles, sonar: res.verdict.sonar, standingExceptions: std.standing });
+      const req = checkSonarRequirement({ config, stagedFiles: liveFiles, sonar: res.verdict.sonar, standingExceptions: std.standing });
       if (!req.ok) res = { ok: false, verdict: res.verdict, reason: req.reason };
       else if (req.mode === "granted") console.log(formatSonarGrant(req.grant));
     }
@@ -386,8 +395,8 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
       console.log(`⚠ rag [${RAG_RULE_ID}]: the pipeline verdict carries no session ledger — the headless pipeline does not consult the RAG yet; sealed as a warn`);
       if (!warnIds.includes(RAG_RULE_ID)) warnIds.push(RAG_RULE_ID);
     } else if (res.ok) {
-      const { harness, verified, mismatched } = readRagLedger(projectDir);
-      const rreq = checkRagVerdict({ config, stagedFiles: changedFiles, rag: res.verdict.rag, harness, verified, mismatched, standingExceptions: std.standing });
+      const { harness, verified, mismatched, drift } = readRagLedger(projectDir);
+      const rreq = checkRagVerdict({ config, stagedFiles: liveFiles, rag: res.verdict.rag, harness, verified, mismatched, drift, standingExceptions: std.standing });
       if (!rreq.ok) res = { ok: false, verdict: res.verdict, reason: rreq.reason };
       else if (rreq.mode === "granted" && rreq.grant) console.log(formatRagGrant(rreq.grant));
     }
@@ -414,7 +423,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   if (flags.sonar !== false) {
     // KJC-TSK-0795 AC3: only issues on lines this diff ADDS may veto.
     const touchedLines = addedLinesByFile(await rawDiff(flags.range, ["--unified=0"]));
-    const pre = await runSonarPregate({ config, stagedFiles: changedFiles, touchedLines, logger });
+    const pre = await runSonarPregate({ config, stagedFiles: liveFiles, touchedLines, logger });
     if (!pre.available) {
       // KJC-BUG-0156 (issue #1543): a scan that FAILED must not read like one
       // more config warning — it hid a dead quality gate for 8 straight PRs.
@@ -459,7 +468,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   // KJC-TSK-0838: fail-CLOSED for code. Sonar disabled, down, skipped by
   // flag, or blind to a staged source — the diff does not reach the reviewer.
   // Docs-only diffs pass; a live human grant on the rule is the only escape.
-  const sonarReq = checkSonarRequirement({ config, stagedFiles: changedFiles, sonar: sonarRecord, standingExceptions: std.standing });
+  const sonarReq = checkSonarRequirement({ config, stagedFiles: liveFiles, sonar: sonarRecord, standingExceptions: std.standing });
   if (!sonarReq.ok) {
     console.log(`✗ ${sonarReq.reason}`);
     process.exitCode = 1;
@@ -476,7 +485,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   // the 16-sep bugs were exactly the twin nobody touched.
   const ledger = readRagLedger(projectDir);
   const newFiles = (await rawDiff(flags.range, ["--name-only", "--diff-filter=A"])).split("\n").map((f) => f.trim()).filter(Boolean);
-  const ragReq = checkRagRequirement({ config, stagedFiles: changedFiles, newFiles, ledger, standingExceptions: std.standing });
+  const ragReq = checkRagRequirement({ config, stagedFiles: liveFiles, newFiles, ledger, standingExceptions: std.standing });
   if (!ragReq.ok) {
     console.log(`✗ ${ragReq.reason}`);
     process.exitCode = 1;

package/src/commands/watch.js

@@ -8,13 +8,13 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 
 export async function watchStartCommand({ config, logger, flags = {} }) {
   const projectDir = config?.projectDir || process.cwd();
-  const existing = readPidFile();
+  const existing = readPidFile(projectDir);
   if (existing && isPidAlive(existing)) { logger.info(`Watcher already running (pid ${existing}).`); return { pid: existing, started: false }; }
-  if (existing) clearPidFile();
+  if (existing) clearPidFile(projectDir);
   if (flags.foreground) {
-    writePidFile();
+    writePidFile(projectDir);
     const stop = startWatcher({ projectDir, config, logger, withSources: !!flags.withSources });
-    const shutdown = async () => { await stop(); clearPidFile(); process.exit(0); };
+    const shutdown = async () => { await stop(); clearPidFile(projectDir); process.exit(0); };
     process.on("SIGINT", shutdown).on("SIGTERM", shutdown);
     logger.info(`Watcher started in foreground (pid ${process.pid}). Ctrl+C to stop.`);
     return { pid: process.pid, started: true };
@@ -26,18 +26,21 @@ export async function watchStartCommand({ config, logger, flags = {} }) {
   return { pid: child.pid, started: true };
 }
 
-export async function watchStopCommand({ logger }) {
-  const pid = readPidFile();
+// KJC-TSK-0883: stop/status son del watcher de ESTE proyecto, resuelto como en start.
+export async function watchStopCommand({ config, logger }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const pid = readPidFile(projectDir);
   if (!pid) { logger.info("No watcher running."); return { stopped: false }; }
-  if (!isPidAlive(pid)) { clearPidFile(); logger.info(`Stale PID file removed (process ${pid} was not alive).`); return { stopped: false, stale: true }; }
+  if (!isPidAlive(pid)) { clearPidFile(projectDir); logger.info(`Stale PID file removed (process ${pid} was not alive).`); return { stopped: false, stale: true }; }
   try { process.kill(pid, "SIGTERM"); } catch (err) { logger.warn(`Could not signal pid ${pid}: ${err.message}`); }
-  clearPidFile();
+  clearPidFile(projectDir);
   logger.info(`Watcher (pid ${pid}) stopped.`);
   return { stopped: true, pid };
 }
 
-export async function watchStatusCommand({ logger }) {
-  const pid = readPidFile();
+export async function watchStatusCommand({ config, logger }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const pid = readPidFile(projectDir);
   const alive = pid && isPidAlive(pid);
   if (alive) logger.info(`Watcher running (pid ${pid}).`);
   else if (pid) logger.warn(`Stale PID file (process ${pid} not alive). Run \`kj watch stop\` to clean up.`);

package/src/config/defaults.js

@@ -179,10 +179,11 @@ const DEFAULTS = {
       test_inclusions: "**/*.test.js,**/*.spec.js,**/tests/**,**/__tests__/**"
     }
   },
+  // KJC-TSK-0884 (ADR 0011): on by default, like Sonar; a declared false opts out.
   hu_board: {
-    enabled: false,
+    enabled: true,
     port: 4000,
-    auto_start: false
+    auto_start: true
   },
   language: "en",
   hu_language: "en",

package/src/environment/playbook.js

@@ -12,6 +12,7 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import { upsertManagedBlock } from "../utils/managed-markers.js";
+import { detectRulesync, RULESYNC_RULE, rulesyncRuleSeed } from "../utils/rulesync.js";
 import { panelLine } from "./panel.js";
 
 // AB-A (KJC-TSK-0650): any agent can be the brain. AGENTS.md is the
@@ -114,15 +115,21 @@ export async function installPlaybook({ projectDir, target = "all", version = "1
     throw new Error(`unknown target "${target}" — use one of: ${PLAYBOOK_TARGETS.join(", ")}`);
   }
   const files = [];
-  for (const file of TARGET_FILES[target]) {
+  // KJC-TSK-0879: in a Rulesync repo its rule source is the only file of truth;
+  // `rulesync generate` would erase a block written into the agent files.
+  const rulesync = detectRulesync(projectDir);
+  for (const file of rulesync ? [RULESYNC_RULE] : TARGET_FILES[target]) {
     const fullPath = path.join(projectDir, file);
-    let source = "";
+    let source = rulesync ? rulesyncRuleSeed() : "";
     try { source = await fs.readFile(fullPath, "utf8"); } catch { /* new file */ }
     const { content, action } = upsertManagedBlock({
       source, blockId: "playbook", version, body: renderPlaybook({ stateBackend, boardName, config }), style: "html",
       note: "do not edit: regenerated by kj env install",
     });
-    if (action !== "unchanged") await fs.writeFile(fullPath, content);
+    if (action !== "unchanged") {
+      await fs.mkdir(path.dirname(fullPath), { recursive: true });
+      await fs.writeFile(fullPath, content);
+    }
     files.push(file);
   }
   return { files, target };

package/src/harden/config-templates.js

@@ -118,6 +118,17 @@ export const GO_CONFIGS = [{ file: ".golangci.yml", blockId: "golangci", style:
 export const PHPSTAN_BODY = ["parameters:", "  level: 6", "  paths:", "    - src", "    - tests"].join("\n");
 export const PHP_CONFIGS = [{ file: "phpstan.neon", blockId: "phpstan", style: "hash", body: PHPSTAN_BODY }];
 
+
+/**
+ * KJC-BUG-0221 — los nombres que kj ESCRIBE en el proyecto. Lo consume la
+ * cobertura del RAG para no denunciar como drift un fichero que kj acaba de
+ * generar. Se deriva de las tablas de arriba: anadir un config aqui no obliga
+ * a acordarse de una segunda lista en otro modulo.
+ */
+export const GENERATED_CONFIG_FILES = new Set(
+  [...UNIVERSAL_CONFIGS, ...JS_CONFIGS, ...PY_CONFIGS, ...GO_CONFIGS, ...PHP_CONFIGS].map((c) => c.file),
+);
+
 /** Lint/format configs by detected language. Unknown ⇒ universal only. */
 export const CONFIGS_BY_LANGUAGE = {
   javascript: JS_CONFIGS,

package/src/harden/guidelines-engine.js

@@ -5,10 +5,11 @@
  * content the user keeps outside the markers. Idempotent.
  */
 
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 
 import { upsertManagedBlock } from "../utils/managed-markers.js";
+import { detectRulesync, RULESYNC_RULE, rulesyncRuleSeed } from "../utils/rulesync.js";
 import { guidelinesBody } from "./guidelines-templates.js";
 
 const BLOCK_VERSION = 1;
@@ -28,7 +29,12 @@ export function stripDevHooksBlock(source) {
   return { content: `${before}${joiner}${after}`, migrated: true };
 }
 
-const countLines = (text) => String(text || "").split("\n").filter((l) => l.trim()).length;
+const nonEmpty = (text) => String(text || "").split("\n").map((l) => l.trim()).filter(Boolean);
+const countLines = (text) => nonEmpty(text).length;
+
+// KJC-BUG-0232: "do not edit" se leia como "no toques esto", no como "lo que
+// escribas aqui se borra". Solo este bloque: los hooks sellados no cambian.
+const GUIDELINES_NOTE = "regenerated by kj harden: anything written inside is lost; keep your own rules outside this block";
 
 export function installGuidelines({ projectDir = process.cwd(), dryRun = false, language = null } = {}) {
   // KJC-BUG-0199 (issue #1773): the rules that enter the agent's context must
@@ -36,9 +42,13 @@ export function installGuidelines({ projectDir = process.cwd(), dryRun = false,
   // the configs; the guidelines just never asked.
   const body = guidelinesBody(language);
   const results = [];
-  for (const file of TARGETS) {
+  // KJC-TSK-0879: with Rulesync, its source is the file of truth; writing into
+  // CLAUDE.md/AGENTS.md would be erased by the next `rulesync generate`.
+  const rulesync = detectRulesync(projectDir);
+  for (const file of rulesync ? [RULESYNC_RULE] : TARGETS) {
     const target = join(projectDir, file);
-    const raw = existsSync(target) ? readFileSync(target, "utf8") : "";
+    const seed = rulesync ? rulesyncRuleSeed() : "";
+    const raw = existsSync(target) ? readFileSync(target, "utf8") : seed;
     const { content: source, migrated } = stripDevHooksBlock(raw);
     const { content, action } = upsertManagedBlock({
       source,
@@ -46,13 +56,20 @@ export function installGuidelines({ projectDir = process.cwd(), dryRun = false,
       version: BLOCK_VERSION,
       body,
       style: "html",
+      note: GUIDELINES_NOTE,
     });
     // KJC-BUG-0206: harden removing rules is a fact worth saying. It silently
     // dropped six lines from this repo's own files because the detected language
     // had no block, and "updated" read like an improvement.
     const shrank = countLines(content) < countLines(raw);
-    if (!dryRun && (migrated || action !== "unchanged")) writeFileSync(target, content);
-    results.push({ file, action: migrated ? "migrated" : action, ...(shrank ? { shrank: true } : {}) });
+    // KJC-BUG-0232: decir CUALES se van, o el aviso obliga a salir a git diff.
+    const kept = new Set(nonEmpty(content));
+    const removed = shrank ? nonEmpty(raw).filter((l) => !kept.has(l) && !l.includes("kj:managed:")) : [];
+    if (!dryRun && (migrated || action !== "unchanged")) {
+      mkdirSync(dirname(target), { recursive: true });
+      writeFileSync(target, content);
+    }
+    results.push({ file, action: migrated ? "migrated" : action, ...(shrank ? { shrank: true, removed } : {}) });
   }
   return { dryRun, guidelines: results };
 }

package/src/harden/harness-hooks.js

@@ -9,6 +9,7 @@
  * supports tool hooks.
  */
 
+import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
@@ -18,7 +19,11 @@ const SCRIPT_BODY = `#!/usr/bin/env node
 // so a gate bug never bricks the session.
 import console from "node:console";
 import process from "node:process";
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+// El guard vive en <repo>/.karajan/harness/, asi que el arbol es dos arriba.
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 let raw = "";
 process.stdin.on("data", (d) => { raw += d; });
 process.stdin.on("end", () => {
@@ -30,10 +35,75 @@ process.stdin.on("end", () => {
         process.exit(2);
       }
     }
-    if (tool === "Bash" && process.env.KJ_ALLOW_REWRITE !== "1") {
+    if (tool === "Bash") {
       const cmd = String(input.command || "");
+      // KJC-BUG-0227: el escape tambien viaja en el PROPIO comando, como en el
+      // resto de guardias. Mirando solo process.env el agente no tenia salida:
+      // un export dentro del comando jamas llega a este proceso.
+      // Solo cuentan las asignaciones DEL PRINCIPIO, que son las que el shell
+      // aplica al comando. Buscarla en cualquier parte del texto dejaba pasar
+      // un "echo KJ_ALLOW_REWRITE=1; python3 ..." (catch de la review).
+      const toks = cmd.trim().split(/\\s+/);
+      let i = 0;
+      let named = false;
+      while (i < toks.length && /^[A-Z][A-Z0-9_]*=/.test(toks[i])) {
+        if (toks[i] === "KJ_ALLOW_REWRITE=1") named = true;
+        i += 1;
+      }
+      // Una asignacion delante solo alcanza a SU comando, asi que el escape del
+      // comando vale unicamente en un comando SIMPLE: en "VAR=1 true && python"
+      // o "VAR=1 && python" el python nunca la recibe (catch de la review). Lo
+      // que va entre comillas no encadena nada, asi que no cuenta.
+      // Tampoco es simple si hay sustitucion: el proceso de dentro de $( ) no
+      // hereda la asignacion (catch de la review). Mismo criterio que el resto
+      // de guardias del Sentinel.
+      // Dentro de comillas SIMPLES todo es literal; dentro de dobles, un ; no
+      // encadena pero $( ) si ejecuta. Por eso se miran dos cosas distintas.
+      const noSingle = cmd.replaceAll(/'[^']*'/g, "");
+      const substitutes = noSingle.includes("$(") || noSingle.includes("\\u0060");
+      const bare = noSingle.replaceAll(/"[^"]*"/g, "");
+      const simple = !substitutes && !/[;&|]/.test(bare) && !bare.includes("\\n");
+      const cmdEscape = named && simple && i < toks.length;
+      const escaped = process.env.KJ_ALLOW_REWRITE === "1" || cmdEscape;
+      // Un escape ignorado EN SILENCIO era el bug: si esta puesto y no vale, se dice.
+      if (named && !cmdEscape) console.error("kj tool gate: KJ_ALLOW_REWRITE=1 presente pero IGNORADO — solo vale delante del comando y en uno simple (sin ; | & fuera de comillas).");
       const writes = /open\\s*\\([^)]*["'][wa]["']|>\\s*\\S+\\.json\\b/.test(cmd);
-      if (/json\\.dumps?\\s*\\(/.test(cmd) && writes) {
+      // KJC-BUG-0227: y solo se vigila lo que esta DENTRO del arbol. Un fichero
+      // temporal del scratchpad no es asunto de este guard, y bloquearlo
+      // ensenaba a rodearlo. Sin ruta reconocible se vigila: el lado seguro.
+      const targets = cmd.match(/[\\w./-]+\\.json\\b/g) || [];
+      // Solo se exime lo que se puede establecer CON CERTEZA: una ruta absoluta
+      // fuera del arbol. Una relativa depende del cwd del shell, que este hook
+      // no conoce — "cd packages && ... open(\\"../package.json\\")" escribe
+      // dentro del repo (catch de la review), asi que se sigue vigilando.
+      // Un enlace puede apuntar dentro: /tmp/link.json escribiria en el repo
+      // (catch de la review). Se resuelve el padre real antes de clasificar, y
+      // si no se puede resolver, se vigila.
+      // Fuera del arbol es SALIR de el, no que el nombre empiece por dos puntos:
+      // <repo>/..config.json esta dentro (catch de la review).
+      const escapesRoot = (rel) => rel === ".." || rel.startsWith("../");
+      const outsideForSure = (t) => {
+        if (!t.startsWith("/")) return false;
+        const abs = resolve(t);
+        try {
+          const root = realpathSync(ROOT);
+          // El propio fichero puede SER el enlace (/tmp/link.json -> repo/cfg.json),
+          // asi que se resuelve entero cuando existe; si aun no existe, manda su
+          // directorio real.
+          if (existsSync(abs)) return escapesRoot(relative(root, realpathSync(abs)));
+          const parts = abs.split("/");
+          const name = parts.pop();
+          return escapesRoot(relative(root, realpathSync(parts.join("/") || "/") + "/" + name));
+        } catch {
+          return false;
+        }
+      };
+      // Con expansion del shell no se sabe a donde apunta nada: "$PWD/cfg.json"
+      // deja el trozo "/cfg.json", que parece absoluto y ajeno sin serlo (catch
+      // de la review). Ante la duda se vigila.
+      const expands = /[$~]/.test(cmd) || cmd.includes("\\u0060");
+      const mine = expands || targets.length === 0 || !targets.every(outsideForSure);
+      if (!escaped && mine && /json\\.dumps?\\s*\\(/.test(cmd) && writes) {
         console.error("kj tool gate: reserializing a whole JSON file makes the diff unreviewable — make targeted edits instead (KJ_ALLOW_REWRITE=1 to override consciously).");
         process.exit(2);
       }
@@ -100,8 +170,27 @@ export function mergeClaudeHooks({ projectDir, logger = console, entries }) {
   return { wired: true };
 }
 
+/**
+ * La raiz del proyecto: el toplevel de git, o el directorio dado si no hay git.
+ * Vive aqui y no se importa de sentinel-hooks porque ese modulo importa de
+ * este: el ciclo rompe la carga.
+ */
+function resolveProjectRoot(dir) {
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd: dir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || dir;
+  } catch {
+    return dir;
+  }
+}
+
 /** Write the script and merge the PreToolUse entries into .claude/settings.json. */
 export function installHarnessHooks({ projectDir = process.cwd(), logger = console } = {}) {
+  // KJC-BUG-0223: el harness es del proyecto y vive en su raiz. Instalado desde
+  // un subdirectorio sembraba ahi un segundo `.karajan/harness` que no gobierna
+  // nada, y el gate seguia mirando otro sitio.
+  const root = resolveProjectRoot(projectDir);
+  if (root !== projectDir) logger?.info?.(`kj harden: el harness es del proyecto, se instala en su raíz (${root})`);
+  projectDir = root;
   const scriptAbs = writeHarnessScript(projectDir, "pretooluse.mjs", SCRIPT_BODY);
   const { wired } = mergeClaudeHooks({
     projectDir,