@karajan-family/code 4.70.2 → 4.70.4

package/package.json

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

package/src/checks/ai-surface.js

@@ -11,11 +11,13 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { claudeConfigFile, codexHome } from "../utils/agent-home.js";
 
-const sources = (projectDir, home) => [
+// KJC-TSK-1344: claude and codex configs of the account CLAUDE_CONFIG_DIR / CODEX_HOME select.
+const sources = (projectDir, home, env = process.env) => [
   { file: path.join(projectDir, ".mcp.json"), format: "json" },
-  { file: path.join(home, ".claude.json"), format: "json" },
-  { file: path.join(home, ".codex", "config.toml"), format: "toml" },
+  { file: claudeConfigFile({ home, env }), format: "json" },
+  { file: path.join(codexHome({ home, env }), "config.toml"), format: "toml" },
   { file: path.join(home, ".gemini", "settings.json"), format: "json" },
 ];
 
@@ -34,9 +36,9 @@ const tomlServerNames = (text) =>
   new Set([...text.matchAll(/^\s*\[mcp_servers\.["']?([^\]"']+)["']?\]/gm)].map((m) => m[1]));
 
 /** Sorted `name (config-file)` entries for every MCP reachable in this project. */
-export function collectAiSurface({ projectDir = process.cwd(), home = os.homedir() } = {}) {
+export function collectAiSurface({ projectDir = process.cwd(), home = os.homedir(), env = process.env } = {}) {
   const surface = new Set();
-  for (const { file, format } of sources(projectDir, home)) {
+  for (const { file, format } of sources(projectDir, home, env)) {
     if (!existsSync(file)) continue;
     let text;
     try { text = readFileSync(file, "utf8"); } catch { continue; }
@@ -50,11 +52,11 @@ export function collectAiSurface({ projectDir = process.cwd(), home = os.homedir
  * Diff the current surface against the last-seen snapshot and persist the
  * new state. First run records the baseline silently.
  */
-export function checkAiSurface({ projectDir = process.cwd(), home = os.homedir(), statePath = path.join(os.homedir(), ".karajan", "ai-surface.json"), extraSurface = [] } = {}) {
+export function checkAiSurface({ projectDir = process.cwd(), home = os.homedir(), env = process.env, statePath = path.join(os.homedir(), ".karajan", "ai-surface.json"), extraSurface = [] } = {}) {
   // KJC-TSK-0728: extraSurface carries entries the (async) caller collected
   // outside config files — e.g. observed agent CLIs as "grok (cli)" — so
   // they ride the same snapshot and the same "NEW since last check" drift.
-  const surface = [...new Set([...collectAiSurface({ projectDir, home }), ...extraSurface])].sort();
+  const surface = [...new Set([...collectAiSurface({ projectDir, home, env }), ...extraSurface])].sort();
   let state = {};
   try { state = JSON.parse(readFileSync(statePath, "utf8")); } catch { /* first run or corrupt → baseline */ }
   const prev = Array.isArray(state[projectDir]) ? state[projectDir] : null;

package/src/checks/config-files.js

@@ -18,6 +18,7 @@ import { getConfigPath } from "../config.js";
 import { resolveRoleMdPath, loadFirstExisting } from "../roles/base-role.js";
 import { withDocLink } from "../utils/doc-links.js";
 import { STRATEGY } from "./types.js";
+import { codexHome } from "../utils/agent-home.js";
 
 /**
  * kj.config.yml presence check.
@@ -218,16 +219,16 @@ function createStaleMcpPathCheck() {
 }
 
 /**
- * Codex config (~/.codex/config.toml) validity.
+ * Codex config ($CODEX_HOME/config.toml, ~/.codex by default) validity.
+ * KJC-TSK-1344: the account CODEX_HOME selects is the one whose config counts.
  */
-function createCodexConfigCheck() {
+export function createCodexConfigCheck({ env = process.env, home = os.homedir() } = {}) {
+  const codexTomlPath = path.join(codexHome({ home, env }), "config.toml");
   return {
     name: "agent-config:codex",
-    label: "Agent config: codex (~/.codex/config.toml)",
+    label: `Agent config: codex (${codexTomlPath})`,
     strategy: STRATEGY.MANUAL,
     async detect() {
-      const home = os.homedir();
-      const codexTomlPath = path.join(home, ".codex", "config.toml");
       try {
         const raw = await fs.readFile(codexTomlPath, "utf8");
         const duplicates = findDuplicateTomlKeys(raw);
@@ -236,7 +237,7 @@ function createCodexConfigCheck() {
             ok: false,
             severity: "warn",
             detail: `Duplicate TOML keys: ${duplicates.join(", ")}`,
-            fix: `Remove duplicate entries in ~/.codex/config.toml: ${duplicates.join(", ")}`,
+            fix: `Remove duplicate entries in ${codexTomlPath}: ${duplicates.join(", ")}`,
           };
         }
         return { ok: true, severity: "info", detail: "Valid TOML (no duplicate keys)" };
@@ -248,7 +249,7 @@ function createCodexConfigCheck() {
           ok: false,
           severity: "warn",
           detail: `Cannot read: ${err.message.split("\n")[0]}`,
-          fix: "Check file permissions on ~/.codex/config.toml",
+          fix: `Check file permissions on ${codexTomlPath}`,
         };
       }
     },

package/src/cli/register-pipeline.js

@@ -136,6 +136,9 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("-q, --quiet", "Show only stage status lines, suppress raw agent output (default)")
     .option("-v, --verbose", "Show full agent output (stream-json, raw lines)")
     .action(async (task, flags) => {
+      // KJC-BUG-0448: run's --profile is the model profile; harden and check use
+      // --profile for the harness, so the config loader reads modelProfile.
+      if (flags.profile) flags.modelProfile = flags.profile;
       await withConfig(pkgVersion, "run", flags, async ({ config, logger }) => {
         // If `--plan <id>` was passed and the user didn't provide a task
         // argument or --task-file, fall back to the task embedded in the
@@ -292,6 +295,7 @@ export function registerPipeline(program, { pkgVersion }) {
           const r = await verifyPrReview({ projectDir: config.projectDir || process.cwd(), pr: flags.verifyPr });
           if (r.ok) logger.info(`✓ PR #${flags.verifyPr}: ${r.commits} commit(s), each with its cross-AI verdict`);
           else logger.error(`✗ PR #${flags.verifyPr}:\n  - ${r.problems.join("\n  - ")}`);
+          if (r.sealCommits) logger.info(`  seal commit(s) signed by the roster, a human act with no AI verdict: ${r.sealCommits.join(", ")}`);
           process.exitCode = r.ok ? 0 : 1;
           return;
         }

package/src/commands/env.js

@@ -135,7 +135,9 @@ export async function envInstallCommand({ config = null, logger = null, flags =
         console.log(result.pendingBlock);
         return result;
       }
-      await reviewGateCommand({ config, flags: { installGate: true } });
+      const gate = await reviewGateCommand({ config, flags: { installGate: true } });
+      // KJC-BUG-0447: a gate no hook runs is decorative; never call it active.
+      if (!gate?.enforced) throw new Error("the review gate is declared but no pre-commit hook runs it");
       console.log("✓ enforcement active: git hooks + cross-AI verdict gate — a commit outside the method is rejected, not narrated");
     } catch (err) {
       result.exitCode = PENDING_EXIT_CODE;

package/src/commands/go.js

@@ -11,6 +11,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { checkBinary } from "../utils/agent-detect.js";
+import { agentAuthFiles } from "../utils/agent-home.js";
 import { createCliAskQuestion } from "../utils/cli-ask-question.js";
 import { bootstrapCommand } from "./bootstrap.js";
 import { boardCommand } from "./board.js";
@@ -21,12 +22,14 @@ export const MAGGLE_AGENTS = [
   { name: "claude", label: "Claude Code (Anthropic)", authPaths: [".claude.json", ".claude"], install: "npm install -g @anthropic-ai/claude-code", login: "claude   (sigue el enlace de inicio de sesión que te muestre)" },
   { name: "codex", label: "Codex (OpenAI)", authPaths: [".codex/auth.json"], install: "npm install -g @openai/codex", login: "codex login" },
 ];
-export async function detectMaggleAgents({ home = os.homedir(), checkBin = checkBinary } = {}) {
+export async function detectMaggleAgents({ home = os.homedir(), env = process.env, checkBin = checkBinary } = {}) {
   return Promise.all(
     MAGGLE_AGENTS.map(async (a) => {
       let installed = false;
       try { installed = (await checkBin(a.name)).ok; } catch { /* not installed */ }
-      const authenticated = installed && a.authPaths.some((p) => existsSync(path.join(home, p)));
+      // KJC-TSK-1344: the session lives where CLAUDE_CONFIG_DIR / CODEX_HOME point.
+      const files = agentAuthFiles(a.name, { home, env }) ?? a.authPaths.map((p) => path.join(home, p));
+      const authenticated = installed && files.some((f) => existsSync(f));
       return { ...a, installed, authenticated };
     }),
   );

package/src/commands/harden.js

@@ -25,12 +25,20 @@ import { installHarnessHooks } from "../harden/harness-hooks.js";
 import { installSentinelHooks } from "../harden/sentinel-hooks.js";
 import { installSandbox } from "../harden/sandbox.js";
 import { detectStackRoots } from "../harden/stack-roots.js";
-import { installWorkflows } from "../harden/workflow-engine.js";
+import { detectPackageManager, installWorkflows, resolveKjPin } from "../harden/workflow-engine.js";
 import { adviseBranchProtection } from "../harden/branch-protection.js";
 import { detectTestFramework } from "../utils/project-detect.js";
 import { ensureIdentity } from "../identity/bootstrap.js";
 import { commitContract, contractChanges } from "../environment/contract-commit.js";
 
+// How each package manager runs a package.json script in a hook (`bun test` is bun's own runner, not the script).
+const HOOK_RUNNERS = {
+  npm: { run: (s) => `npm run -s ${s}`, test: "npm test" },
+  pnpm: { run: (s) => `pnpm run -s ${s}`, test: "pnpm test" },
+  yarn: { run: (s) => `yarn run ${s}`, test: "yarn test" },
+  bun: { run: (s) => `bun run ${s}`, test: "bun run test" },
+};
+
 const JS_TEST_CMD = {
   vitest: "npx vitest run",
   jest: "npx jest",
@@ -51,10 +59,12 @@ export async function resolveCmds(projectDir, language) {
   if (existsSync(pkgPath)) {
     try {
       const scripts = JSON.parse(readFileSync(pkgPath, "utf8")).scripts ?? {};
-      if (scripts.lint) cmds.lint = "npm run -s lint";
-      if (scripts["format:check"]) cmds.format = "npm run -s format:check";
-      else if (scripts.format) cmds.format = "npm run -s format";
-      if (scripts.test) cmds.test = "npm test";
+      // KJC-BUG-0450 (#2789): the project's own package manager, as the workflows use it.
+      const pm = HOOK_RUNNERS[detectPackageManager(projectDir)] ?? HOOK_RUNNERS.npm;
+      if (scripts.lint) cmds.lint = pm.run("lint");
+      if (scripts["format:check"]) cmds.format = pm.run("format:check");
+      else if (scripts.format) cmds.format = pm.run("format");
+      if (scripts.test) cmds.test = pm.test;
     } catch {
       /* unreadable package.json → fall back to framework detection */
     }
@@ -97,6 +107,7 @@ export async function hardenCommand({
   // KJC-BUG-0289: the contract files already dirty before anything was generated
   // (kj init captures them before writing its own). What is dirty NOW is the person's.
   contractBefore = null,
+  fetchFn = fetch,
   logger = console,
 } = {}) {
   const dirtyBefore = contractBefore ?? contractChanges(projectDir);
@@ -177,8 +188,11 @@ export async function hardenCommand({
   const withConfig = config && profile !== "minimal";
   const cfg = withConfig ? installConfigsForRoots({ projectDir, roots, dryRun }) : null;
   const withCi = ci && profile !== "minimal";
+  // KJC-BUG-0420: consumer CI installs kj from npm, so the workflows pin a published version.
+  const pin = withCi ? await resolveKjPin({ projectDir, fetchFn }) : null;
+  if (pin?.note) logger.warn?.(`⚠ ${pin.note}`);
   const wf = withCi
-    ? installWorkflows({ projectDir, language: roots[0]?.language ?? null, root: roots[0]?.dir ?? ".", profile, mutation, dryRun })
+    ? installWorkflows({ projectDir, language: roots[0]?.language ?? null, root: roots[0]?.dir ?? ".", profile, mutation, dryRun, kjVersion: pin?.version ?? null })
     : null;
   const withGuidelines = guidelines && profile !== "minimal";
   // KJC-BUG-0199 (issue #1773): the same detected language the workflows and

package/src/commands/pr-size.js

@@ -8,7 +8,7 @@ import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
-import { budgetedAdded } from "../review/loc-budget.js";
+import { budgetedAdded, budgetedNet } from "../review/loc-budget.js";
 
 const git = (projectDir, args) =>
   execFileSync("git", ["-C", projectDir, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
@@ -40,12 +40,13 @@ export async function branchSize({ projectDir = process.cwd(), base = "main", ex
     const n = text === "" ? 0 : text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
     numstat += `${n}\t0\t${file}\n`;
   }
-  return { ...budgetedAdded(numstat), base };
+  // KJC-BUG-0434: `net` is what the CI gate and the policy measure; `added` stays for its readers.
+  return { ...budgetedAdded(numstat), net: budgetedNet(numstat).net, 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)`);
+  else logger.info(`pr-size: ${s.net} net line(s) against ${s.base}, as the CI gate counts them (${s.added} added, ${s.testAdded} in tests, ${s.exempt} exempt)`);
   return s;
 }

package/src/commands/review-gate.js

@@ -34,6 +34,7 @@ import { evaluatePolicyGate } from "../review/policy-gate.js";
 import { correctionNote, reviewCorrectionRounds } from "../review/correction-rounds.js";
 import { cooldownAdvisories, cooldownGate, DEFAULT_COOLDOWN_HOURS, formatCooldown } from "../review/dep-cooldown.js";
 import { branchOverlaps, formatOverlaps } from "../review/branch-overlap.js";
+import { gateHookStatus } from "../review/gate-hook.js";
 
 // KJC-TSK-0686 (MG-A): card-first is a gate, not a habit. Runs on --staged
 // (before spending sonar/reviewer effort) AND on --check — the pre-commit
@@ -195,18 +196,20 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     const marker = join(projectDir, ".karajan", "review-gate");
     await fs.mkdir(join(projectDir, ".karajan"), { recursive: true });
     await fs.writeFile(marker, "# Cross-AI review gate enabled (ENV-C1). Commit this file so the whole team inherits the gate.\n");
-    console.log("✓ review gate enabled — commits now require an approved cross-AI verdict (kj review --staged)");
+    // KJC-BUG-0447 (#2655): the marker declares the gate; only a pre-commit that runs it enforces it.
+    const hook = gateHookStatus(projectDir);
+    if (hook.enforced) console.log("✓ review gate enabled — commits now require an approved cross-AI verdict (kj review --staged)");
+    else {
+      console.log(`✗ review gate declared (.karajan/review-gate) but NOT enforced: ${hook.reason} — run \`kj harden\` so the pre-commit hook runs it`);
+      process.exitCode = 1;
+    }
     // KJC-TSK-0646: a `.karajan/` dir-exclude would silently keep the
     // contract out of git — rewrite it so the team actually inherits it.
     const gi = await ensureGateTrackable(projectDir);
     if (gi.changed) {
       console.log("✓ .gitignore adjusted: the gate contract (.karajan/review-gate, hooks) is now trackable — commit it");
     }
-    const hookProbe = await runCommand("git", ["config", "core.hooksPath"]);
-    if (!hookProbe.stdout?.trim()) {
-      console.log("⚠ no core.hooksPath configured — run `kj harden` so the pre-commit hook enforces the gate");
-    }
-    return { installed: true };
+    return { installed: true, enforced: hook.enforced };
   }
 
   // KJC-BUG-0173: manual GC of the verdict store. Opportunistic pruning runs
@@ -268,26 +271,28 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     // documentation are exempt — the same rule CI applies. Counting everything
     // here warned 234 lines on a doc-only PR that CI counted at 104, and two
     // implementations of one rule that disagree teach people to trust neither.
-    const { added, exempt, testAdded } = budgetedAdded(numstat);
+    // KJC-BUG-0434: measured NET, as CI and the policy's net_lines_added do — a rewrite in place is not growth.
+    const { added, testAdded } = budgetedAdded(numstat);
+    const { net, exempt } = budgetedNet(numstat);
     // Said out loud: an exemption nobody sees is indistinguishable from a gate
     // that is not looking.
     if (exempt > 0) console.log(`ℓ pr-size: ${exempt} line(s) exempt from the budget (generated output and human docs; AI-rule files always count)`);
-    if (added > sizeIdeal && added <= sizeWarn) {
-      console.log(`ℓ pr-size: ${added} lines added, over the ~${sizeIdeal} ideal, within the ${sizeWarn} limit: allowed, nothing to ask`);
+    if (net > sizeIdeal && net <= sizeWarn) {
+      console.log(`ℓ pr-size: ${net} net lines, over the ~${sizeIdeal} ideal, within the ${sizeWarn} limit: allowed, nothing to ask`);
     }
-    if (added > sizeWarn) {
+    if (net > sizeWarn) {
       // KJC-TSK-0795 AC5: say how much of the weight is the module's OWN tests —
       // partitioning is a decision, and it must never split code from its tests.
-      const split = testAdded > 0 ? ` (${added - testAdded} source + ${testAdded} accompanying tests — partition by feature, never code from its tests)` : "";
+      const split = testAdded > 0 ? ` (${added - testAdded} source + ${testAdded} test lines added — partition by feature, never code from its tests)` : "";
       const sizePolicy = config?.method_gates?.pr_size || "warn";
       // ADR 0015: no env escape — an exception is the user's label on the PR, judged in CI.
       if (sizePolicy === "block") {
-        const reason = `${added} lines added${split} is over the ${sizeWarn}-line limit (${sizeSource}; method_gates.pr_size: block) — partition the work; an exception is your user's large-pr-justified label on the PR`;
+        const reason = `${net} net lines${split} is over the ${sizeWarn}-line limit (${sizeSource}; method_gates.pr_size: block) — partition the work; an exception is your user's large-pr-justified label on the PR`;
         console.log(`✗ pr-size gate: ${reason}`);
         process.exitCode = 1;
         return { verdict: "rejected", reviewer: "pr-size", issues: [{ severity: "high", description: reason }] };
       } else {
-        console.log(`⚠ pr-size: ${added} lines added${split}, over the ${sizeWarn}-line limit (ideal ~${sizeIdeal}, source: ${sizeSource}) — partition the work before committing (method_gates.pr_size: block to harden)`);
+        console.log(`⚠ pr-size: ${net} net lines${split}, over the ${sizeWarn}-line limit (ideal ~${sizeIdeal}, source: ${sizeSource}) — partition the work before committing (method_gates.pr_size: block to harden)`);
       }
     }
   }

package/src/config/overrides.js

@@ -102,7 +102,8 @@ function applyRoleOverrides(out, flags) {
   if (flags.reviewerModel) out.reviewer_options.model = String(flags.reviewerModel);
 
   // KJC-TSK-0699: a profile fills only the models nothing above has set.
-  const profile = flags.profile ?? out.model_profile;
+  // KJC-BUG-0448: its own key — `--profile` belongs to harden/check (the harness profile).
+  const profile = flags.modelProfile ?? out.model_profile;
   if (profile) {
     applyModelProfile(out, String(profile));
     out.model_profile = String(profile);

package/src/environment/board-access.js

@@ -14,6 +14,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { claudeConfigFile, codexHome } from "../utils/agent-home.js";
 
 const TOKEN_CONVENTIONS = {
   linear: ["LINEAR_API_KEY"],
@@ -23,18 +24,19 @@ const TOKEN_CONVENTIONS = {
   asana: ["ASANA_ACCESS_TOKEN"],
 };
 
-function mcpConfigPaths(projectDir, home) {
+// KJC-TSK-1344: claude and codex configs of the account CLAUDE_CONFIG_DIR / CODEX_HOME select.
+function mcpConfigPaths(projectDir, home, env = process.env) {
   return [
     path.join(projectDir, ".mcp.json"),
-    path.join(home, ".claude.json"),
-    path.join(home, ".codex", "config.toml"),
+    claudeConfigFile({ home, env }),
+    path.join(codexHome({ home, env }), "config.toml"),
     path.join(home, ".gemini", "settings.json"),
   ];
 }
 
-function mcpConfigsMention(slug, projectDir, home) {
+function mcpConfigsMention(slug, projectDir, home, env) {
   const needle = slug.toLowerCase();
-  for (const p of mcpConfigPaths(projectDir, home)) {
+  for (const p of mcpConfigPaths(projectDir, home, env)) {
     try {
       if (existsSync(p) && readFileSync(p, "utf8").toLowerCase().includes(needle)) return p;
     } catch { /* unreadable config — keep looking */ }
@@ -50,13 +52,13 @@ function mcpConfigsMention(slug, projectDir, home) {
  */
 export function detectAvailableBoards({ projectDir = process.cwd(), env = process.env, home = os.homedir() } = {}) {
   const boards = [{ value: "hu-board", label: "HU Board (bundled, zero setup)" }];
-  if (mcpConfigsMention("planning-game", projectDir, home)) {
+  if (mcpConfigsMention("planning-game", projectDir, home, env)) {
     boards.push({ value: "planning-game", label: "Planning Game (MCP detected)" });
   }
   for (const [slug, envs] of Object.entries(TOKEN_CONVENTIONS)) {
     const token = envs.find((k) => env[k]);
     if (token) boards.push({ value: `external:${slug}`, label: `${slug} (token ${token})` });
-    else if (mcpConfigsMention(slug, projectDir, home)) boards.push({ value: `external:${slug}`, label: `${slug} (MCP detected)` });
+    else if (mcpConfigsMention(slug, projectDir, home, env)) boards.push({ value: `external:${slug}`, label: `${slug} (MCP detected)` });
   }
   return boards;
 }
@@ -65,7 +67,7 @@ export function verifyBoardAccess({ config = {}, projectDir = process.cwd(), env
   const backend = config.state_backend || "hu-board";
 
   if (backend === "planning-game") {
-    const hit = mcpConfigsMention("planning-game", projectDir, home);
+    const hit = mcpConfigsMention("planning-game", projectDir, home, env);
     if (hit) return { ok: true, backend, via: `planning-game MCP (${hit})` };
     return {
       ok: false, backend,
@@ -77,7 +79,7 @@ export function verifyBoardAccess({ config = {}, projectDir = process.cwd(), env
     const name = String(config.board?.name || "").trim();
     if (!name) return { ok: false, backend, needed: ["declare board.name in kj.config.yml (e.g. Linear, Trello, Jira, GitHub Issues)"] };
     const slug = name.toLowerCase().split(/\s+/)[0];
-    const hit = mcpConfigsMention(slug, projectDir, home);
+    const hit = mcpConfigsMention(slug, projectDir, home, env);
     if (hit) return { ok: true, backend, via: `${name} MCP detected (${hit})` };
     const tokenEnvs = config.board?.token_env ? [config.board.token_env] : (TOKEN_CONVENTIONS[slug] || []);
     const found = tokenEnvs.find((k) => env[k]);

package/src/git/automation.js

@@ -348,10 +348,11 @@ export async function finalizeGitAutomation({ config, gitCtx, task, logger, sess
     } catch (err) {
       logger.warn(`pr-size: the branch could not be measured (${err.message}); the budget is not checked for this commit`);
     }
-    if (size && size.added > limit) {
-      logger.warn(`pr-size: ${size.added} line(s) added against ${gitCtx.baseBranch}, over the budget of ${limit}: nothing committed. Split the step (several commits, several HUs); the changes stay in the tree`);
-      await addCheckpoint(session, { stage: "git-commit", committed: false, skipped: "over-budget", added: size.added, limit });
-      return { committed: false, branch: gitCtx.branch, prUrl: null, pr: null, commits: [], overBudget: { added: size.added, limit } };
+    // KJC-BUG-0434: net, as the CI gate counts it.
+    if (size && size.net > limit) {
+      logger.warn(`pr-size: ${size.net} net line(s) against ${gitCtx.baseBranch}, over the budget of ${limit}: nothing committed. Split the step (several commits, several HUs); the changes stay in the tree`);
+      await addCheckpoint(session, { stage: "git-commit", committed: false, skipped: "over-budget", added: size.added, net: size.net, limit });
+      return { committed: false, branch: gitCtx.branch, prUrl: null, pr: null, commits: [], overBudget: { added: size.added, net: size.net, limit } };
     }
     // ENV-F1: this path only runs after the pipeline's reviewer approved,
     // so stamp that verdict for the staged diff — the v4 pre-commit gate

package/src/harden/branch-protection.js

@@ -43,6 +43,34 @@ const addCommand = ({ missing, ...target }) =>
   `gh api -X POST ${protectionPath(target)}/required_status_checks/contexts ${missing.map((c) => `-f ${shellQuote(`contexts[]=${c}`)}`).join(" ")}`;
 
 const settingsUrl = ({ owner, repo }) => `https://github.com/${owner}/${repo}/settings/branches`;
+const rulesUrl = ({ owner, repo }) => `https://github.com/${owner}/${repo}/settings/rules`;
+
+/**
+ * KJC-BUG-0449 (#2787): every rule that applies to the branch, rulesets included.
+ * [] when none applies (a 404 included); null when it cannot be read.
+ */
+async function branchRules({ owner, repo, branch }, run) {
+  let res;
+  try { res = await run("gh", ["api", `repos/${owner}/${repo}/rules/branches/${encodeURIComponent(branch)}`]); } catch { return null; }
+  if (res.exitCode !== 0) return /404/.test(`${res.stderr}${res.stdout}`) ? [] : null;
+  try {
+    const rules = JSON.parse(res.stdout || "[]");
+    return Array.isArray(rules) ? rules : null;
+  } catch { return null; }
+}
+
+const rulesetChecks = (rules) => rules
+  .filter((r) => r?.type === "required_status_checks")
+  .flatMap((r) => (r.parameters?.required_status_checks ?? []).map((c) => c.context));
+
+/** No classic protection: the rulesets decide, and they are fixed in their own page, never with a PUT. */
+function rulesetAdvice({ rules, checks, target }) {
+  if (rules === null) return { status: "unverified", reason: "the branch rules could not be read", settings: rulesUrl(target), missing: checks };
+  if (rules.length === 0) return { status: "unprotected", command: protectCommand({ ...target, checks }) };
+  const required = new Set(rulesetChecks(rules));
+  const missing = checks.filter((c) => !required.has(c));
+  return missing.length > 0 ? { status: "ruleset-missing", missing, settings: rulesUrl(target) } : { status: "ok", via: "ruleset" };
+}
 
 /**
  * What the base branch needs for the checks to be required, and how. A command
@@ -61,14 +89,18 @@ export async function protectionAdvice({ owner, repo, branch, checks, run = runC
     return { status: "unverified", reason: err.message, settings: settingsUrl(target), missing: checks };
   }
   if (res.exitCode !== 0) {
-    if (/404|not protected/i.test(`${res.stderr}${res.stdout}`)) return { status: "unprotected", command: protectCommand({ ...target, checks }) };
+    if (/404|not protected/i.test(`${res.stderr}${res.stdout}`)) return rulesetAdvice({ rules: await branchRules(target, run), checks, target });
     return { status: "unverified", reason: (res.stderr || res.stdout || "gh failed").trim(), settings: settingsUrl(target), missing: checks };
   }
   const protection = JSON.parse(res.stdout || "{}");
+  const rules = await branchRules(target, run);
+  const fromRules = rulesetChecks(rules ?? []);
   const statusChecks = protection.required_status_checks;
-  if (!statusChecks) return { status: "no-checks", settings: settingsUrl(target), missing: checks };
-  const existing = new Set(statusChecks.contexts ?? []);
+  const existing = new Set([...(statusChecks?.contexts ?? []), ...fromRules]);
   const missing = checks.filter((c) => !existing.has(c));
+  // Unreadable rules: a ruleset may require what the classic layer lacks, so nothing is "missing" for sure.
+  if (rules === null && missing.length > 0) return { status: "unverified", reason: "the branch rules could not be read", settings: rulesUrl(target), missing };
+  if (!statusChecks && fromRules.length === 0) return { status: "no-checks", settings: settingsUrl(target), missing: checks };
   // KJC-BUG-0401: required checks an admin skips are not required for an agent holding an admin's token.
   const bindAdmins = protection.enforce_admins?.enabled === false ? `gh api -X POST ${protectionPath(target)}/enforce_admins` : null;
   if (missing.length > 0) return { status: "missing", missing, command: [addCommand({ ...target, missing }), bindAdmins].filter(Boolean).join(" && ") };
@@ -105,6 +137,7 @@ export async function adviseBranchProtection({ projectDir, branch, logger, run =
     missing: `${branch} does not require ${advice.missing?.length} kj check(s) (${list}). An admin runs (kj never does):`,
     "no-checks": `${branch} is protected but requires no status checks. An admin enables "Require status checks" and adds ${list} in:`,
     unverified: `could not read the protection of ${branch} (${advice.reason}). An admin checks that ${list} are required in:`,
+    "ruleset-missing": `${branch} is protected by a ruleset that does not require ${advice.missing?.length} kj check(s) (${list}). An admin adds them to the ruleset (no second protection layer) in:`,
     "admins-exempt": `${branch} requires the kj checks, but admins can merge without them, and an agent working with an admin's token would. An admin runs (kj never does):`,
   }[advice.status];
   logger.warn?.(`  ⚠ branch protection: ${why}`);

package/src/harden/harden-engine.js

@@ -12,7 +12,7 @@ import { join } from "node:path";
 
 import { upsertManagedBlock } from "../utils/managed-markers.js";
 import { runCommand } from "../utils/process.js";
-import { hookBody, PROFILE_HOOKS, SHEBANG, toPortableHooksDir } from "./hook-templates.js";
+import { hookBody, PROFILE_HOOKS, SHEBANG } from "./hook-templates.js";
 
 const BLOCK_VERSION = 1;
 const HOOKS_DIR = join(".karajan", "hooks");
@@ -29,12 +29,12 @@ export function isGitRepo(projectDir) {
  * compara por hash: un fichero con una sola coma manual ya no coincide.
  */
 export function renderCanonicalHook(hook, generation = {}) {
-  const { cmds = {}, baseBranch = null, globalHooksDir = null } = generation;
+  const { cmds = {}, baseBranch = null } = generation;
   const { content } = upsertManagedBlock({
     source: HOOK_PREAMBLE,
     blockId: `hook:${hook}`,
     version: BLOCK_VERSION,
-    body: hookBody(hook, cmds, { globalHooksDir, baseBranch }),
+    body: hookBody(hook, cmds, { baseBranch }),
     style: "hash",
   });
   return content;
@@ -57,22 +57,6 @@ export async function installHooks({
   const hooks = PROFILE_HOOKS[profile];
   if (!hooks) throw new Error(`Unknown harden profile: ${profile}`);
 
-  // KJC-TSK-0645: setting a repo-local hooksPath ECLIPSES the machine's
-  // global hooks dir — personal guards (AI-attribution commit-msg, protected
-  // branch pre-push) would silently stop applying here. Detect the previous
-  // global dir and have every generated hook chain to it. `~` is emitted as
-  // `$HOME` so the committed hook stays portable across machines (the -x
-  // guard silences it where the dir doesn't exist).
-  let globalHooksDir = null;
-  const globalCfg = await runCommand("git", ["config", "--global", "core.hooksPath"], { cwd: projectDir });
-  const rawGlobal = globalCfg.exitCode === 0 ? globalCfg.stdout.trim() : "";
-  if (rawGlobal && rawGlobal !== HOOKS_DIR) {
-    // KJC-BUG-0169: normalize to a machine-independent form HERE (generation,
-    // on the human's machine) so the provenance stores the portable dir and CI
-    // recomputes the SAME bytes — an absolute home path is not verifiable there.
-    globalHooksDir = toPortableHooksDir(rawGlobal);
-  }
-
   const absHooksDir = join(projectDir, HOOKS_DIR);
   const results = [];
   for (const hook of hooks) {
@@ -82,7 +66,7 @@ export async function installHooks({
       source,
       blockId: `hook:${hook}`,
       version: BLOCK_VERSION,
-      body: hookBody(hook, cmds, { globalHooksDir, baseBranch }),
+      body: hookBody(hook, cmds, { baseBranch }),
       style: "hash",
     });
     results.push({ hook, target, action });
@@ -99,5 +83,5 @@ export async function installHooks({
 
   // KJC-BUG-0161: los parámetros con los que SE GENERÓ — lo que la
   // provenance necesita registrar para que CI pueda recomputar y comparar.
-  return { profile, hooksPath: HOOKS_DIR, dryRun, hooks: results, generation: { profile, cmds, baseBranch, globalHooksDir } };
+  return { profile, hooksPath: HOOKS_DIR, dryRun, hooks: results, generation: { profile, cmds, baseBranch } };
 }

package/src/harden/hook-templates.js

@@ -8,8 +8,6 @@
  * is imposed on non-JS repos. See docs/specs/quality-harness.md §5.
  */
 
-import { homedir } from "node:os";
-
 // KJC-TSK-1076: exported so the third-party PR checks apply the same rules.
 export const CONVENTIONAL_TYPES = "feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert";
 export const AI_ATTRIBUTION = "co-authored-by:.*(claude|gpt|copilot|gemini)|(generated|written) (by|with) .*(claude|gpt|copilot)";
@@ -25,32 +23,21 @@ export const PROFILE_HOOKS = {
 
 /** Build the managed body for a single hook. */
 // KJC-TSK-0645: `core.hooksPath .karajan/hooks` eclipses the user's global
-// hooks dir, silently disabling personal guards. When a previous global dir
-// is known, every generated hook ends by chaining its namesake there —
-// guarded, so machines without it are unaffected.
-// KJC-BUG-0161 / 0169 (ADR 0009): a committed hook must not bake a machine's
-// absolute home path — a dir under the home resolves through $HOME so the same
-// generated content is valid on every machine and its provenance stays
-// verifiable IN CI (a different home), with no local filesystem layout leaking
-// into a public repo. Normalization happens ONCE, at generation, on the human's
-// machine; the stored/rendered value is already portable, so a render on any
-// other home (CI) reproduces identical bytes. `home` is injectable for tests.
-export function toPortableHooksDir(dir, home = homedir()) {
-  if (!dir) return dir;
-  if (dir.startsWith("$HOME")) return dir;
-  if (dir.startsWith("~")) return `$HOME${dir.slice(1)}`;
-  if (dir === home || dir.startsWith(`${home}/`)) return `$HOME${dir.slice(home.length)}`;
-  return dir;
-}
-
-function chainToGlobal(hook, globalHooksDir) {
-  if (!globalHooksDir) return [];
-  const dir = toPortableHooksDir(globalHooksDir);
+// hooks dir, silently disabling personal guards. Every generated hook ends by
+// chaining its namesake in the machine's global dir.
+// KJC-BUG-0161 / 0169 (ADR 0009), HU-2762: the dir is looked up when the hook
+// RUNS, never when kj harden ran — so the generated bytes do not depend on the
+// machine (HOME, GIT_CONFIG_GLOBAL), the provenance verifies in CI, and no
+// local filesystem layout leaks into a public repo. `|| true`: the preamble
+// sets `set -e`. `--type=path` expands `~`; the pwd -P test stops a hook from
+// calling itself when the global setting is this repo's own hooks dir.
+function chainToGlobal(hook) {
   // KJC-TSK-1085: pre-push already read the refs from stdin; the chained hook gets them back.
-  const call = hook === "pre-push" ? `printf '%s\\n' "$kj_push_refs" | "${dir}/${hook}" "$@"; rc=$?` : `"${dir}/${hook}" "$@"; rc=$?`;
+  const call = hook === "pre-push" ? `printf '%s\\n' "$kj_push_refs" | "$kj_global/${hook}" "$@"; rc=$?` : `"$kj_global/${hook}" "$@"; rc=$?`;
   return [
-    "# Chain the machine's previous global hook (kj harden keeps it active).",
-    `if [ -x "${dir}/${hook}" ]; then`,
+    "# Chain the machine's global hook, looked up when the hook runs, not when kj harden ran (KJC-TSK-0645, HU-2762).",
+    "kj_global=$(git config --global --type=path --get core.hooksPath 2>/dev/null || true)",
+    `if [ -n "$kj_global" ] && [ -x "$kj_global/${hook}" ] && [ "$(cd "$kj_global" 2>/dev/null && pwd -P)" != "$(cd "$(dirname "$0")" && pwd -P)" ]; then`,
     `  ${call}`,
     '  [ "$rc" -eq 0 ] || exit "$rc"',
     "fi",
@@ -109,8 +96,9 @@ function identityGuard(hook) {
     '  if [ -n "$kj_declared_email" ]; then',
     '    printf "%s\\n" "$kj_push_refs" | while read -r kj_lref kj_lsha kj_rref kj_rsha; do',
     '      case "$kj_lsha" in *[!0]*) ;; *) continue ;; esac',
-    // A new ref: what the PUSH TARGET ($1, the remote git hands the hook) does not have yet.
-    '      case "$kj_rsha" in *[!0]*) kj_new=$(git rev-list "$kj_rsha..$kj_lsha") ;; *) kj_new=$(git rev-list "$kj_lsha" --not --remotes="${1:-origin}") ;; esac',
+    // What the PUSH TARGET ($1, the remote git hands the hook) does not have yet. KJC-BUG-0436:
+    // an existing ref too, or merging main into a pushed branch judges main's own merges.
+    '      case "$kj_rsha" in *[!0]*) kj_new=$(git rev-list "$kj_lsha" --not "$kj_rsha" --remotes="${1:-origin}") ;; *) kj_new=$(git rev-list "$kj_lsha" --not --remotes="${1:-origin}") ;; esac',
     "      for kj_c in $kj_new; do",
     '        kj_who=$(git log -1 --format="%ae %ce" "$kj_c")',
     '        if [ "$kj_who" != "$kj_declared_email $kj_declared_email" ]; then',
@@ -129,8 +117,8 @@ function identityGuard(hook) {
   ];
 }
 
-export function hookBody(hook, cmds = {}, { globalHooksDir = null, baseBranch = null } = {}) {
-  const chain = chainToGlobal(hook, globalHooksDir);
+export function hookBody(hook, cmds = {}, { baseBranch = null } = {}) {
+  const chain = chainToGlobal(hook);
   switch (hook) {
     case "pre-commit": {
       const lines = [...baseBranchGuard(baseBranch), ...identityGuard("pre-commit"), "# Lint + format the working tree with the project's native tools."];