karajan-code 4.49.0 → 4.49.1

package/package.json

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

package/src/commands/review-gate.js

@@ -246,7 +246,11 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   const locInv = pol.errors.length === 0
     ? (pol.policy.invariants || []).find((i) => i.kind === "diff-threshold" && i.metric === "net_lines_added")
     : null;
-  const sizeWarn = locInv?.max ?? config?.method_gates?.pr_size_warn ?? 150;
+  // KJC-BUG-0326 (#2085): two tiers. ~150 is the ideal (method_gates.pr_size_warn);
+  // up to the limit (the policy's net_lines_added max, else method_gates.pr_size_max,
+  // 200) is allowed without asking; above the limit, partition.
+  const sizeIdeal = config?.method_gates?.pr_size_warn ?? 150;
+  const sizeWarn = locInv?.max ?? config?.method_gates?.pr_size_max ?? 200;
   const sizeSource = locInv ? `policy [${locInv.id}]` : "method_gates";
   if (sizeWarn > 0) {
     const numstat = await rawDiff(flags.range, ["--numstat"]);
@@ -258,6 +262,9 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     // 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 (added > 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.
@@ -265,12 +272,12 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
       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} exceeds the ${sizeWarn}-line budget (${sizeSource}; method_gates.pr_size: block) — partition the work; an exception is your user's large-pr-justified label on the PR`;
+        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`;
         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} (guideline ~${sizeWarn}, source: ${sizeSource}) — an oversized warning is not an opinion: partition, or ask your user (method_gates.pr_size: block to harden)`);
+        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)`);
       }
     }
   }

package/src/config/defaults.js

@@ -81,9 +81,11 @@ const DEFAULTS = {
     card_first_exempt_branches: ["chore/release-"],
     // MG-B: source changes without a test change — "warn" | "block".
     tests_with_code: "warn",
-    // MG-C: informative nudge when the staged diff exceeds this many
-    // added lines (0 disables). The project's CI owns any hard budget.
+    // MG-C + KJC-BUG-0326: ~pr_size_warn added lines is the ideal; up to
+    // pr_size_max is allowed without asking; above it, partition (warn, or
+    // block with pr_size: "block"). A policy net_lines_added max wins over pr_size_max.
     pr_size_warn: 150,
+    pr_size_max: 200,
     // CLM-B (claims-with-evidence ADR): the Stop gate crosses the hard data of
     // the turn's final message against that turn's tool outputs. "off" (adoption
     // is explicit) | "warn" (report only) | "block" (a datum DENIED by its own

package/src/environment/playbook.js

@@ -76,8 +76,8 @@ ${panel ? `${panel}\n` : ""}- Security findings are never overridable — not ev
   \`kj audit --security\` (zero tokens) and remediate BEFORE the review.
 - A design decision the card's AC don't cover belongs to the USER: record
   it as a proposed ADR (\`kj adr add\`) and ask — never bury it in a PR
-  bullet. An oversized-diff warning is not an opinion either: partition,
-  or get an explicit OK.
+  bullet. Diff size: ~150 net lines of code is the ideal, up to 200 is
+  allowed without asking, above 200 partition, always.
 - A non-trivial plan names at least two approaches — one as if the
   codebase didn't exist — and says why the winner won. Following the
   legacy line is a choice, never a default.

package/src/git/hu-automation.js

@@ -4,6 +4,7 @@
  */
 import { commitAll, pushBranch, createPullRequest, hasChanges } from "../utils/git.js";
 import { runCommand } from "../utils/process.js";
+import { stampStagedVerdict } from "../review/verdict-store.js";
 
 /**
  * Build a git-safe branch name for an HU story.
@@ -184,7 +185,16 @@ export async function finalizeHuCommit({ story, branchName, config, logger, cwd
   const title = story.title || story.id;
   const commitMsg = `feat(${story.id}): ${title}`;
   if (config.git?.auto_commit) {
-    const commitRes = await commitAll(commitMsg, cwd);
+    // KJC-BUG-0323: this commit runs after the HU's reviewer approved, so it
+    // records that verdict for the staged diff, as the other post-review commits do.
+    const commitRes = await commitAll(commitMsg, cwd, {
+      beforeCommit: ({ paths } = {}) => stampStagedVerdict({
+        projectDir: cwd || config.projectDir || process.cwd(),
+        paths,
+        reviewer: config.reviewer || "pipeline-reviewer",
+        summary: `kj run HU ${story.id}: reviewer approved`,
+      }),
+    });
     if (commitRes) {
       result.committed = true;
       logger.info(`HU ${story.id}: committed on '${branchName}'`);

package/src/harden/advisory.js

@@ -166,9 +166,28 @@ export function classifyArtifact(searchDir, artifact, altDirs = [searchDir]) {
  * own root (monorepo-aware, mirroring installConfigsForRoots). `minimal`
  * profile ships no config, so there is nothing to compare.
  */
+// KJC-BUG-0335 (#2094): the method's own pieces, not only the configs. Without
+// them the report said "0 missing" while the review gate demanded the Sentinel.
+const METHOD_PIECES = [
+  { id: "sentinel", what: "the Sentinel (it records the session, the RAG queries the review gate needs among them)",
+    files: [".karajan/harness/pretooluse-sentinel.mjs", ".karajan/harness/posttooluse.mjs", ".karajan/harness/stop.mjs"] },
+  { id: "git-hooks", what: "the git hooks", files: [".karajan/hooks/pre-commit", ".karajan/hooks/commit-msg", ".karajan/hooks/pre-push"] },
+];
+
+function methodPiece(projectDir, { id, what, files }) {
+  const head = { dir: ".", id, file: files[0], currentVersion: null, managedVersion: null, upToDate: null, improvements: [], mergeable: false };
+  const missing = files.filter((f) => !existsSync(join(projectDir, f)));
+  return missing.length === 0
+    ? { ...head, status: "KJ_MANAGED", foundAt: files[0], recommendation: "keep", rationale: `${what}: installed` }
+    : { ...head, status: "MISSING", foundAt: null, missing, recommendation: "install", rationale: `kj harden (without --report) installs ${what}; missing: ${missing.join(", ")}` };
+}
+
 export function compareHarden({ projectDir = process.cwd(), profile = "standard", only = [], exclude = [] } = {}) {
   if (profile === "minimal") return { artifacts: [] };
-  const artifacts = UNIVERSAL_CONFIGS.map((cfg) => ({ dir: ".", ...classifyArtifact(projectDir, toArtifact(cfg)) }));
+  const artifacts = [
+    ...METHOD_PIECES.map((piece) => methodPiece(projectDir, piece)),
+    ...UNIVERSAL_CONFIGS.map((cfg) => ({ dir: ".", ...classifyArtifact(projectDir, toArtifact(cfg)) })),
+  ];
   for (const { dir, language } of detectStackRoots(projectDir, { only, exclude })) {
     const searchDir = dir === "." ? projectDir : join(projectDir, dir);
     for (const cfg of CONFIGS_BY_LANGUAGE[language] ?? []) {

package/src/harden/sentinel-hooks.js

@@ -1423,8 +1423,11 @@ export function installSentinelHooks({ projectDir = process.cwd(), logger = cons
   };
   const [lib, post, stop, pre] = Object.entries(SCRIPT_BODIES).map(([name, body]) => {
     if (keepsItsSeal(name)) {
-      deferred.push(name);
-      return join(projectDir, ".karajan", "harness", name);
+      const abs = join(projectDir, ".karajan", "harness", name);
+      // KJC-BUG-0325: only a sealed guard the current template would change is
+      // waiting for the human; one identical to it has nothing to advance.
+      if (readFileSync(abs, "utf8") !== body) deferred.push(name);
+      return abs;
     }
     return writeHarnessScript(projectDir, name, body);
   });

package/src/orchestrator/drivers/init-context.js

@@ -36,6 +36,17 @@ import { getIntegration } from "../integrations.js";
 import { tryAutoStartBoard } from "./post-loop.js";
 import { runPreLoopStages } from "./pre-loop.js";
 
+/**
+ * KJC-BUG-0324: the coder is built before the pre-loop, with the run's first
+ * config, so what the pre-loop resolves (the Domain Curator's domainContext,
+ * the methodology) never reached its prompt. The run and the coder both take
+ * the resolved config; the coder is initialized after this.
+ */
+export function adoptPreLoopConfig(ctx, updatedConfig) {
+  ctx.config = updatedConfig;
+  ctx.coderRoleInstance.config = updatedConfig;
+}
+
 export async function initFlowContext({ task, config, logger, emitter, askQuestion, pgTaskId, pgProject, flags }) {
   // Auto-init .karajan/ if missing (copies coder-rules, review-rules, role templates)
   const initProjectDir = config.projectDir || process.cwd();
@@ -182,7 +193,7 @@ export async function initFlowContext({ task, config, logger, emitter, askQuesti
 
   const preLoopResult = await runPreLoopStages({ config, logger, emitter, eventBase: ctx.eventBase, session: ctx.session, flags, pipelineFlags: ctx.pipelineFlags, coderRole: ctx.coderRole, trackBudget: ctx.trackBudget, task, askQuestion, pgTaskId, pgProject, stageResults: ctx.stageResults, brainCtx: ctx.brainCtx });
   ctx.plannedTask = preLoopResult.plannedTask;
-  ctx.config = preLoopResult.updatedConfig;
+  adoptPreLoopConfig(ctx, preLoopResult.updatedConfig);
 
   // --- Session Journal: persist pre-loop outputs + display plan summary ---
   const reportDir = ctx.config.output?.report_dir || ".reviews";

package/src/planning-game/client.js

@@ -14,8 +14,22 @@ import { withRetry } from "../utils/retry.js";
 const DEFAULT_API_URL = "http://localhost:3000/api";
 const DEFAULT_TIMEOUT_MS = 10000;
 
-function getApiUrl() {
-  return process.env.PG_API_URL || DEFAULT_API_URL;
+// KJC-BUG-0322: PG_API_URL > planning_game.api_url (passed by the caller) > localhost.
+function getApiUrl(apiUrl) {
+  const fromEnv = process.env.PG_API_URL?.trim();
+  if (fromEnv) return fromEnv;
+  const fromConfig = typeof apiUrl === "string" ? apiUrl.trim() : "";
+  return fromConfig ? fromConfig : DEFAULT_API_URL;
+}
+
+// Origin and path only: credentials or a query token in a configured URL never reach a log.
+function urlForMessage(url) {
+  try {
+    const u = new URL(url);
+    return `${u.origin}${u.pathname}`;
+  } catch {
+    return "(invalid Planning Game URL)";
+  }
 }
 
 async function fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_TIMEOUT_MS) {
@@ -37,7 +51,7 @@ async function fetchWithTimeout(url, options = {}, timeoutMs = DEFAULT_TIMEOUT_M
       err.httpStatus = 408;
       throw err;
     }
-    throw new Error(`Planning Game network error: ${error?.message || "unknown error"}`, { cause: error });
+    throw new Error(`Planning Game network error at ${urlForMessage(url)}: ${error?.message ?? "unknown error"}`, { cause: error });
   } finally {
     clearTimeout(timeoutId);
   }
@@ -58,15 +72,15 @@ async function parseJsonResponse(response) {
   }
 }
 
-export async function fetchCard({ projectId, cardId, timeoutMs = DEFAULT_TIMEOUT_MS }) {
-  const url = `${getApiUrl()}/projects/${encodeURIComponent(projectId)}/cards/${encodeURIComponent(cardId)}`;
+export async function fetchCard({ projectId, cardId, apiUrl, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  const url = `${getApiUrl(apiUrl)}/projects/${encodeURIComponent(projectId)}/cards/${encodeURIComponent(cardId)}`;
   const response = await fetchWithRetry(url, {}, timeoutMs);
   const data = await parseJsonResponse(response);
   return data?.card || data;
 }
 
-export async function updateCard({ projectId, cardId: _cardId, firebaseId, updates, timeoutMs = DEFAULT_TIMEOUT_MS }) {
-  const url = `${getApiUrl()}/projects/${encodeURIComponent(projectId)}/cards/${encodeURIComponent(firebaseId)}`;
+export async function updateCard({ projectId, cardId: _cardId, firebaseId, updates, apiUrl, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  const url = `${getApiUrl(apiUrl)}/projects/${encodeURIComponent(projectId)}/cards/${encodeURIComponent(firebaseId)}`;
   const response = await fetchWithRetry(
     url,
     {
@@ -79,8 +93,8 @@ export async function updateCard({ projectId, cardId: _cardId, firebaseId, updat
   return parseJsonResponse(response);
 }
 
-export async function createCard({ projectId, card, timeoutMs = DEFAULT_TIMEOUT_MS }) {
-  const url = `${getApiUrl()}/projects/${encodeURIComponent(projectId)}/cards`;
+export async function createCard({ projectId, card, apiUrl, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  const url = `${getApiUrl(apiUrl)}/projects/${encodeURIComponent(projectId)}/cards`;
   const response = await fetchWithRetry(
     url,
     {
@@ -93,8 +107,8 @@ export async function createCard({ projectId, card, timeoutMs = DEFAULT_TIMEOUT_
   return parseJsonResponse(response);
 }
 
-export async function relateCards({ projectId, sourceCardId, targetCardId, relationType, timeoutMs = DEFAULT_TIMEOUT_MS }) {
-  const url = `${getApiUrl()}/projects/${encodeURIComponent(projectId)}/cards/relate`;
+export async function relateCards({ projectId, sourceCardId, targetCardId, relationType, apiUrl, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  const url = `${getApiUrl(apiUrl)}/projects/${encodeURIComponent(projectId)}/cards/relate`;
   const response = await fetchWithRetry(
     url,
     {

package/src/planning-game/pipeline-adapter.js

@@ -63,9 +63,10 @@ async function handlePgDecomposition({ triageResult, pgTaskId, pgProject, config
     const normalizedAnswer = (answer || "").trim().toLowerCase();
     const isAccept = normalizedAnswer === "1" || normalizedAnswer === "yes" || normalizedAnswer === "sí" || normalizedAnswer === "si";
     if (isAccept) {
-      const parentCard = await fetchCard({ projectId: pgProject, cardId: pgTaskId }).catch(() => null);
+      const apiUrl = config.planning_game?.api_url;
+      const parentCard = await fetchCard({ projectId: pgProject, cardId: pgTaskId, apiUrl }).catch(() => null);
       const createdSubtasks = await createDecompositionSubtasks({
-        client: { createCard, relateCards },
+        client: { createCard: (args) => createCard({ ...args, apiUrl }), relateCards: (args) => relateCards({ ...args, apiUrl }) },
         projectId: pgProject,
         parentCardId: pgTaskId,
         parentFirebaseId: parentCard?.firebaseId || null,
@@ -129,7 +130,8 @@ export async function markPgCardToValidate({ pgCard, pgProject, config, session,
       projectId: pgProject,
       cardId: session.pg_task_id,
       firebaseId: pgCard.firebaseId,
-      updates: pgUpdates
+      updates: pgUpdates,
+      apiUrl: config.planning_game?.api_url
     });
     logger.info(`Planning Game: ${session.pg_task_id} → To Validate`);
   } catch (err) {
@@ -201,9 +203,9 @@ async function markPgCardInProgress({ pgTaskId, pgProject, config, logger }) {
   // its own HUs and said approved. With a card named, no card is a loud stop.
   let pgCard;
   try {
-    pgCard = await fetchCard({ projectId: pgProject, cardId: pgTaskId });
+    pgCard = await fetchCard({ projectId: pgProject, cardId: pgTaskId, apiUrl: config.planning_game?.api_url });
   } catch (err) {
-    throw new Error(`Planning Game: card ${pgTaskId} could not be read (${err.message}): the run would implement without the card's acceptance criteria. Check PG_API_URL, or run without pgTask.`, { cause: err });
+    throw new Error(`Planning Game: card ${pgTaskId} could not be read (${err.message}): the run would implement without the card's acceptance criteria. Check planning_game.api_url in the config (PG_API_URL overrides it), or run without pgTask.`, { cause: err });
   }
   if (!pgCard) throw new Error(`Planning Game: card ${pgTaskId} not found in project ${pgProject}: the run would implement without the card's acceptance criteria. Check the id, or run without pgTask.`);
   try {
@@ -212,6 +214,7 @@ async function markPgCardInProgress({ pgTaskId, pgProject, config, logger }) {
         projectId: pgProject,
         cardId: pgTaskId,
         firebaseId: pgCard.firebaseId,
+        apiUrl: config.planning_game?.api_url,
         updates: {
           status: "In Progress",
           startDate: new Date().toISOString(),

package/src/policy/exceptions.js

@@ -6,7 +6,8 @@
  */
 import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { homedir, userInfo } from "node:os";
+import { userInfo } from "node:os";
+import { getKarajanHome } from "../utils/paths.js";
 import { spawnSync } from "node:child_process";
 import { recordPolicyException as kernelRecord } from "@karajan-family/governance";
 
@@ -36,7 +37,10 @@ export function loadStandingExceptions(projectDir, { home } = {}) {
  * Ruta del almacén GLOBAL (~/.karajan): excepciones de la máquina, no de un
  * proyecto. `home` es inyectable SOLO para tests.
  */
-export const globalExceptionsFile = ({ home } = {}) => join(home ?? homedir(), ".karajan", "policy-exceptions.jsonl");
+// KJC-BUG-0337: with no injected home it is the Karajan home (honours KARAJAN_HOME,
+// and the suite's temp home), not homedir(): the tests read the machine's real grants.
+const globalDir = (home) => (home ? join(home, ".karajan") : getKarajanHome());
+export const globalExceptionsFile = ({ home } = {}) => join(globalDir(home), "policy-exceptions.jsonl");
 
 function readRecordsAt(file, origin) {
   let raw;
@@ -85,7 +89,7 @@ function defaultAppend(projectDir, line) {
 }
 
 const globalAppend = (home) => (_projectDir, line) => {
-  const dir = join(home ?? homedir(), ".karajan");
+  const dir = globalDir(home);
   mkdirSync(dir, { recursive: true });
   appendFileSync(join(dir, "policy-exceptions.jsonl"), line, "utf8");
 };

package/src/review/card-first.js

@@ -11,7 +11,9 @@ import { listPlans, loadPlan } from "../plan/plan-store.js";
 import { escapeRegExp } from "../utils/escape-regexp.js";
 import { verifyCardAlive } from "./card-verify.js";
 
-const LIVE_STATUSES = new Set(["pending", "running", "failed"]);
+// KJC-BUG-0323: coding/reviewing are the run working the HU, certified is ready
+// to run; the gate blocked the pipeline's own commit on its own HU.
+const LIVE_STATUSES = new Set(["pending", "running", "failed", "certified", "coding", "reviewing"]);
 // Card-shaped reference: LIN-123, bb-002 and multi-segment ids like
 // KJC-TSK-0684 (optional middle segments) — tight enough to skip slugs.
 // Shared with the method report (MG-D): one pattern, one truth.

package/src/spec-review/run-spec-review.js

@@ -51,6 +51,13 @@ export async function runSpecReview({ spec, config, logger, askQuestion, flags =
     return { proceed: true, skipped: true };
   }
   if (!spec || !String(spec).trim()) return { proceed: true, skipped: true };
+  // KJC-BUG-0321 (#2074): with --plan the spec is the plan's original task, which
+  // `kj plan` reviewed when it generated the plan, and the HUs were certified since.
+  // Reviewing it again flags the plan, not the HUs being run.
+  if (flags.plan) {
+    logger?.info?.(`Spec review skipped: plan ${flags.plan} was reviewed when it was generated and its HUs certified.`);
+    return { proceed: true, skipped: true };
+  }
 
   const role = new SpecReviewerRole({ config, logger });
   await role.init({ task: spec });

package/templates/roles/coder.md

@@ -52,7 +52,7 @@ Karajan projects MAY enforce a CI gate that fails any PR whose net delta exceeds
 
 - Stay under **~150 LOC per iteration** (safety margin against the 200 hard limit).
 - The gate counts the SUM of every changed file, not per-file. Tests count too. 5 files × 40 LOC = 200 = on the limit.
-- If the task clearly requires >150 LOC, STOP and report the partition needed. Don't ship a 500-LOC PR — the gate rejects it and the work is redone, burning tokens twice.
+- Up to 200 LOC is allowed without asking. If the task clearly requires >200 LOC, STOP and report the partition needed. Don't ship a 500-LOC PR — the gate rejects it and the work is redone, burning tokens twice.
 - Excluded from the count: lockfiles, snapshots, `dist/`, `node_modules/`, generated `tests/_diet/`, `public/docs/`. Source + tests count.
 
 ## Task completeness