karajan-code 4.35.1 → 4.37.0

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

@@ -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) => {
@@ -188,6 +219,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
@@ -278,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}`);
@@ -357,6 +397,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 +412,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));
     }
@@ -387,7 +428,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
       if (!warnIds.includes(RAG_RULE_ID)) warnIds.push(RAG_RULE_ID);
     } else if (res.ok) {
       const { harness, verified, mismatched, drift } = readRagLedger(projectDir);
-      const rreq = checkRagVerdict({ config, stagedFiles: changedFiles, rag: res.verdict.rag, harness, verified, mismatched, drift, standingExceptions: std.standing });
+      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 +455,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 +500,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 +517,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/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/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);