karajan-code 4.52.0 → 4.53.0

package/src/harden/sentinel-hooks.js

@@ -530,7 +530,8 @@ process.stdin.on("end", () => {
       // like the supervisor: a session does not loosen the rules that govern it.
       // .karajan/rules.yml (KJC-TSK-0947, ADR 0016): the compiled rules are the user's to approve.
       // .karajan/rules.local.yml (KJC-TSK-0954, ADR 0017): the same rules, the ones from private sources.
-      if ([".karajan/policy.yml", ".karajan/kj.config.yml", ".karajan/rules.yml", ".karajan/rules.local.yml", ".ragignore"].includes(relT) || relT.endsWith("/.ragignore")) {
+      // .karajan/security-level.json (KJC-TSK-1054, ADR 0020): only kj security writes it, after the human layers.
+      if ([".karajan/policy.yml", ".karajan/kj.config.yml", ".karajan/rules.yml", ".karajan/rules.local.yml", ".karajan/security-level.json", ".ragignore"].includes(relT) || relT.endsWith("/.ragignore")) {
         console.error("karajan sentinel: " + relT + " es configuracion de gobierno (politicas, gates, exclusiones): la cambia tu usuario, no la sesion. Si un gate te parece injusto, proponselo a tu usuario o usa kj report-issue." + doc("governance"));
         process.exit(2);
       }

package/src/hu/complexity-tier.js

@@ -0,0 +1,32 @@
+/**
+ * KJC-TSK-0698 (MR-A): the tier (trivial, standard, deep) each HU leaves the
+ * decomposition with, so the coder model can be chosen per HU on an auditable
+ * trail. Two sources: the judgement of the model that already decomposes (same
+ * answer, no extra call) and a deterministic signal. The higher one wins, and
+ * a sensitive zone is always deep: underestimating there is the costly mistake.
+ */
+export const TIERS = ["trivial", "standard", "deep"];
+
+const SENSITIVE = /\b(?<zone>auth|secret|token|password|credential|crypt|security|seguridad|migrat|migraci|supervisor|sentinel|polic(?:y|ies)|permission)\w*/i;
+const STANDARD_MIN_CRITERIA = 3;
+
+/** The tier the HU's own text implies, with no model involved. */
+export function deterministicTier({ title = "", goal = "", acceptanceCriteria = [] }) {
+  const zone = SENSITIVE.exec([title, goal, ...acceptanceCriteria].join("\n"))?.groups.zone;
+  if (zone) return { tier: "deep", reason: `sensitive zone: ${zone.toLowerCase()}` };
+  if (acceptanceCriteria.length >= STANDARD_MIN_CRITERIA) return { tier: "standard", reason: `${acceptanceCriteria.length} acceptance criteria` };
+  return { tier: "trivial", reason: `${acceptanceCriteria.length} acceptance criteria, no sensitive zone` };
+}
+
+/** The HU's tier: judged against signal, the higher wins, and the record says why. */
+export function huComplexity(hu) {
+  const signal = deterministicTier(hu);
+  const judged = TIERS.includes(hu.tier) ? hu.tier : null;
+  if (!judged) return { tier: signal.tier, judged: null, signal: signal.tier, reason: `no judged tier from the decomposition; signal ${signal.tier} (${signal.reason})` };
+  const judgedText = `judged ${judged} (${hu.tierReason || "no reason given"})`;
+  const signalText = `signal ${signal.tier} (${signal.reason})`;
+  const rank = (t) => TIERS.indexOf(t);
+  if (rank(judged) === rank(signal.tier)) return { tier: judged, judged, signal: signal.tier, reason: `${judgedText}, ${signalText}` };
+  const reason = rank(signal.tier) > rank(judged) ? `${signalText} over ${judgedText}` : `${judgedText} over ${signalText}`;
+  return { tier: TIERS[Math.max(rank(judged), rank(signal.tier))], judged, signal: signal.tier, reason };
+}

package/src/hu/lane-prune.js

@@ -72,3 +72,27 @@ export async function classifyLanes({ git, laneRoot, base, processes, now = Date
     return { slug: path.basename(lane.path), path: lane.path, branch: lane.branch, reasons };
   }));
 }
+
+/** KJC-TSK-1037: the base a lane is measured against: origin/<base> when it exists (a local base can lag far behind). */
+export async function resolveBase({ git, base }) {
+  try {
+    await git(["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${base}`]);
+    return `origin/${base}`;
+  } catch {
+    return base;
+  }
+}
+
+/** KJC-TSK-1037: loose kj-hu-* branches (no worktree): the empty ones, and the ones with work and how much. */
+export async function looseLaneBranches({ git, base }) {
+  const { stdout: listed } = await git(["for-each-ref", "--format=%(refname:short) %(worktreepath)", "refs/heads/kj-hu-*"]);
+  const loose = listed.split("\n").map((l) => l.trim()).filter((l) => l && !l.includes(" "));
+  const empty = [];
+  const withWork = [];
+  for (const branch of loose) {
+    const { stdout: ahead } = await git(["rev-list", "--count", `${base}..${branch}`]);
+    if (Number(ahead) === 0) empty.push(branch);
+    else withWork.push({ branch, reason: `${Number(ahead)} commit(s) not in ${base}` });
+  }
+  return { empty, withWork };
+}

package/src/hu/model-router.js

@@ -1,3 +1,5 @@
+import { getDefaultModelTiers } from "../utils/model-selector.js";
+
 // KJC-TSK-0405: dado un HU con complexity score, recomienda coder_model y
 // reviewer_model. El reviewer por defecto usa el provider alternativo al
 // coder (cross-provider review) para que dos cabezas distintas miren el
@@ -15,22 +17,11 @@ const SCORE_TO_LEVEL = {
   5: "complex",
 };
 
-// Defaults por provider — alineados con utils/model-selector.js DEFAULTS.
-// opencode: usa "coder" como alias razonable; el usuario suele definir
-// gemma-local/coder, ollama/coder o similar en opencode.json. Override
-// per-tier vía config.model_routing.by_provider.opencode si quieres
-// rutear distinto por complexity (ej. fast para trivial, coder para
-// complex). aider: null porque aider envuelve a otros providers — no
-// tiene "modelos propios". Si el usuario lo elige, debe configurarlo
-// explícito en config.model_routing.by_provider.aider o vía override
-// del modal por HU.
-const DEFAULT_TIERS = {
-  claude: { trivial: "haiku", simple: "haiku", medium: "sonnet", complex: "opus" },
-  codex: { trivial: "o4-mini", simple: "o4-mini", medium: "o4-mini", complex: "o3" },
-  gemini: { trivial: "gemini-2.0-flash", simple: "gemini-2.0-flash", medium: "gemini-2.5-pro", complex: "gemini-2.5-pro" },
-  opencode: { trivial: "coder", simple: "coder", medium: "coder", complex: "coder" },
-  aider: { trivial: null, simple: null, medium: null, complex: null },
-};
+// KJC-TSK-0699: los defaults por provider viven en UNA tabla, la de
+// utils/model-selector.js. Quien quiera otros modelos (opencode con sus
+// proveedores, aider) los pone en config.model_routing.by_provider o en el
+// override del modal por HU.
+const DEFAULT_TIERS = getDefaultModelTiers();
 
 // Cross-provider reviewer default: para cada coder provider, qué provider
 // usa el reviewer por defecto. Dos cabezas distintas miran el código.

package/src/hu/routing-metrics.js

@@ -0,0 +1,16 @@
+/**
+ * KJC-TSK-0702 (MR-E): the per-HU measurement model routing is judged by. The
+ * sub-pipeline puts it on the HU outcome; karajan-core's setHuOutcome keeps a
+ * fixed set of fields, so the measured ones are kept here, in the plan, where
+ * kj report reads them. Unmeasured fields stay out rather than written as null.
+ */
+export const ROUTING_FIELDS = ["cost_usd", "tokens_in", "tokens_out", "cached_tokens", "coder", "reviewer_rejections"];
+
+export function keepRoutingMetrics(plan, huId, outcome) {
+  const hu = plan?.hus?.find((h) => h.id === huId);
+  if (!hu?.outcome) return false;
+  for (const field of ROUTING_FIELDS) {
+    if (outcome?.[field] !== null && outcome?.[field] !== undefined) hu.outcome[field] = outcome[field];
+  }
+  return true;
+}

package/src/hu/store.js

@@ -55,6 +55,8 @@ export async function createHuBatch(sessionId, stories) {
       status: "pending",
       original: { text: s.text },
       blocked_by: s.blocked_by || [],
+      // KJC-TSK-0698: the tier travels with the HU; a story without one (single auto-story) carries none.
+      ...(s.complexity ? { complexity: s.complexity } : {}),
       certified: null,
       quality: null,
       context_requests: [],

package/src/orchestrator/drivers/pre-loop-phases/inject-loaded-plan.js

@@ -33,6 +33,7 @@ import {
 } from "#session/mutators.js";
 import { emitProgress, makeEvent } from "#utils/events.js";
 import { listActiveRuns } from "../../../utils/run-registry.js";
+import { keepRoutingMetrics } from "../../../hu/routing-metrics.js";
 
 /**
  * @param {object} args
@@ -313,6 +314,7 @@ function wirePlanCallbacks({ session, loadedPlan, projectDir, syncResultsToPlan,
   setLiveOutcomeUpdater(session, async (huId, outcome) => {
     try {
       if (!setHuOutcomeFn(loadedPlan, huId, outcome)) return;
+      keepRoutingMetrics(loadedPlan, huId, outcome); // KJC-TSK-0702: the measured fields core does not keep
       await savePlanToDisk(projectDir, loadedPlan);
       if (outcome && Number.isFinite(outcome.cost_usd)) {
         try {

package/src/orchestrator/hu-sub-pipeline.js

@@ -195,10 +195,29 @@ function buildHuOutcome({ story: _story, iterResult, status, startedAt, huBudget
     // can hide the chip on cold runs or providers without cache.
     cached_tokens: sumTokenField(huBudgetEntries, 'cached_tokens'),
     tokens_in: sumTokenField(huBudgetEntries, 'tokens_in'),
+    // KJC-TSK-0702 (MR-E): the baseline model routing is measured against.
+    tokens_out: sumTokenField(huBudgetEntries, 'tokens_out'),
+    ...routingBaseline(huBudgetEntries, status),
     finishedAt: new Date().toISOString(),
   };
 }
 
+/**
+ * KJC-TSK-0702 (MR-E): which model the coder used and how many times the
+ * reviewer sent the HU back: its rounds, minus the approval that closed a done HU.
+ * Null when nothing was recorded, as "unmeasured".
+ */
+function routingBaseline(entries, status) {
+  const list = Array.isArray(entries) ? entries : [];
+  const coder = list.findLast((e) => e?.role === "coder");
+  const reviewerRounds = list.filter((e) => e?.role === "reviewer").length;
+  const approvalRound = status === "done" ? 1 : 0;
+  return {
+    coder: coder ? { provider: coder.provider ?? null, model: coder.model ?? null } : null,
+    reviewer_rejections: reviewerRounds === 0 ? null : reviewerRounds - approvalRound,
+  };
+}
+
 /**
  * Execute a single HU through the coder→sonar→reviewer sub-pipeline.
  * Extracted to support both sequential and parallel execution paths.

package/src/orchestrator/stages/hu-reviewer-stage.js

@@ -10,6 +10,7 @@ import { addCheckpoint } from "../../session/store.js";
 import { emitProgress, makeEvent } from "../../utils/events.js";
 import { buildDecompositionPrompt, parseDecompositionOutput, uncoveredCriteria } from "../../prompts/hu-reviewer.js";
 import { criteriaOfCard } from "../../roles/acceptance-coverage-role.js";
+import { huComplexity } from "../../hu/complexity-tier.js";
 import { createStallDetector } from "../../utils/stall-detector.js";
 import { createHuBatch, loadHuBatch, saveHuBatch, updateStoryStatus, updateStoryQuality, updateStoryCertified, addContextRequest, answerContextRequest } from "../../hu/store.js";
 import { topologicalSort } from "../../hu/graph.js";
@@ -88,11 +89,17 @@ async function decomposeTaskIntoHUs({ config, logger, emitter, eventBase, sessio
     }));
   }
 
+  // KJC-TSK-0698 (MR-A): each HU's tier and why, from this same answer plus the deterministic signal.
+  for (const story of stories) {
+    story.complexity = huComplexity(story);
+    logger.info(`${story.id} tier ${story.complexity.tier}: ${story.complexity.reason}`);
+  }
+
   emitProgress(
     emitter,
     makeEvent("hu-reviewer:decompose-end", { ...eventBase, stage: "hu-reviewer" }, {
       message: `Task decomposed into ${stories.length} HUs`,
-      detail: { count: stories.length, ids: stories.map(s => s.id) }
+      detail: { count: stories.length, ids: stories.map(s => s.id), tiers: Object.fromEntries(stories.map((s) => [s.id, s.complexity])) }
     })
   );
 
@@ -230,7 +237,8 @@ export async function runHuReviewerStage({ config, logger, emitter, eventBase, s
           id: hu.id,
           text: isFirst ? fullText : skeletonText,
           blocked_by: hu.dependsOn || [],
-          needsRefinement: !isFirst
+          needsRefinement: !isFirst,
+          complexity: hu.complexity
         };
       });
     } else {

package/src/orchestrator/stages/sonar-stage.js

@@ -124,6 +124,21 @@ async function handleSonarRetryLimit({ config, logger, emitter, eventBase, sessi
   return null;
 }
 
+// KJC-BUG-0359 (#2158): with only the severity counts the coder guessed and
+// tripped sonar_repeat. Each issue travels in the feedback, its path without
+// the project key; past the cap, the rest is counted, never silently dropped.
+const MAX_ISSUES_FOR_CODER = 25;
+export function formatIssuesForCoder(issues) {
+  if (!Array.isArray(issues) || issues.length === 0) return "";
+  const lines = issues.slice(0, MAX_ISSUES_FOR_CODER).map((i) => {
+    const file = String(i.file ?? "").replace(/^[^:]*:/, "");
+    return `- [${i.severity}] ${i.rule} ${file}:${i.line} ${i.message}`;
+  });
+  const rest = issues.length - lines.length;
+  if (rest > 0) lines.push(`…and ${rest} more`);
+  return `\nIssues to fix:\n${lines.join("\n")}`;
+}
+
 async function handleSonarBlocking({ sonarResult, config, logger, emitter, eventBase, session, iteration, repeatDetector, budgetSummary, askQuestion, task, brainCtx }) {
   // If the ONLY quality gate failure is coverage, treat as non-blocking warning
   if (sonarResult.conditions) {
@@ -148,7 +163,7 @@ async function handleSonarBlocking({ sonarResult, config, logger, emitter, event
     return handleSonarStalled({ repeatDetector, logger, emitter, eventBase, session, budgetSummary });
   }
 
-  const summary = `Sonar gate blocking (${sonarResult.gateStatus}). Resolve critical findings first.`;
+  const summary = `Sonar gate blocking (${sonarResult.gateStatus}). Resolve critical findings first.${formatIssuesForCoder(sonarResult.issues)}`;
   setReviewerFeedback(session, summary);
   // Brain: push sonar feedback into queue when enabled
   if (brainCtx?.enabled) {
@@ -363,6 +378,9 @@ export async function runSonarStage({ config, logger, emitter, eventBase, sessio
   const issuesFinal = sonarState.issuesFinal ?? sonarResult.openIssuesTotal ?? 0;
   const stageResult = {
     gateStatus: sonarResult.gateStatus,
+    // KJC-TSK-0839: the key and the files the scan indexed, for the verdict's per-source proof.
+    projectKey: sonarResult.projectKey,
+    indexedFiles: sonarResult.indexedFiles ?? [],
     openIssues: sonarResult.openIssuesTotal,
     issuesInitial,
     issuesFinal,

package/src/plan/plan-schema.js

@@ -6,6 +6,7 @@
 
 import { generatePlanId } from "./plan-id.js";
 import { findCycle } from "../hu/graph.js";
+import { changeClassErrors } from "./rework-license.js";
 
 const VALID_PLAN_STATUSES = new Set(["draft", "ready", "running", "done", "failed"]);
 // KJC-TSK-0394 step 5: el modelo CANONICAL del lifecycle es
@@ -255,7 +256,7 @@ export function migratePlanV1toV2(v1plan) {
 /**
  * Validate a v2 plan. Returns { valid: true } or { valid: false, errors: string[] }.
  */
-export function validatePlan(plan) {
+export function validatePlan(plan, { reworkMin } = {}) {
   const errors = [];
 
   if (!plan.planId) errors.push("Missing planId");
@@ -297,6 +298,8 @@ export function validatePlan(plan) {
         });
       }
     }
+    // KJC-TSK-0717 (SPD-A): EXTEND/REWORK/REBUILD with its criterion, and REWORK only with a licence.
+    errors.push(...changeClassErrors(hu, plan.hus || [], { reworkMin }));
     // Check blocked_by references exist
     for (const dep of hu.blocked_by || []) {
       if (!huIds.has(dep) && !(plan.hus || []).some(h => h.id === dep)) {

package/src/plan/rework-license.js

@@ -0,0 +1,38 @@
+/**
+ * KJC-TSK-0717 (SPD-A): a plan that changes code already written classifies
+ * each HU: EXTEND (edit it), REWORK (regenerate the module with its tests as
+ * the contract) or REBUILD (the subsystem), with the criterion written down.
+ * REWORK needs a licence: the module's mutation score (kj mutate <path>) at or
+ * over the threshold. Under it the plan goes in two phases, an HU that hardens
+ * the module first: regenerating against a thin contract is a roulette.
+ */
+export const CHANGE_CLASSES = ["extend", "rework", "rebuild"];
+// The maintainer's choice (2026-10-16): method_gates.rework_mutation_min overrides it.
+export const DEFAULT_REWORK_MIN = 0.8;
+
+/** The licence for a module, from its mutation score in percent. */
+export function licenseFor({ module, score, threshold = DEFAULT_REWORK_MIN }) {
+  return { module, mutation_score: score, threshold, granted: score / 100 >= threshold };
+}
+
+/**
+ * What is wrong with one HU's classification; empty when nothing is. The
+ * licence is judged again from its score against the threshold in force: a
+ * stored `granted` (or threshold) is a record, never the authority.
+ */
+export function changeClassErrors(hu, hus, { reworkMin = DEFAULT_REWORK_MIN } = {}) {
+  if (hu.change_class === undefined) return [];
+  if (!CHANGE_CLASSES.includes(hu.change_class)) return [`HU ${hu.id}: change_class must be ${CHANGE_CLASSES.join("|")}, got ${hu.change_class}`];
+  if (typeof hu.change_criterion !== "string" || !hu.change_criterion.trim()) return [`HU ${hu.id}: change_criterion is required with change_class (why this class, written down)`];
+  if (hu.change_class !== "rework") return [];
+  const licence = hu.rework_license;
+  if (!licence) return [`HU ${hu.id}: REWORK needs a licence: kj plan license <plan> ${hu.id} --module <path>`];
+  const score = licence.mutation_score;
+  if (typeof licence.module !== "string" || !licence.module || !Number.isFinite(score) || score < 0 || score > 100) {
+    return [`HU ${hu.id}: rework_license must carry a module and a mutation_score between 0 and 100: kj plan license <plan> ${hu.id} --module <path>`];
+  }
+  if (score / 100 >= reworkMin) return [];
+  const hardened = (hu.blocked_by ?? []).some((id) => hus.find((h) => h.id === id)?.hardens === licence.module);
+  if (hardened) return [];
+  return [`HU ${hu.id}: REWORK licence denied for ${licence.module}: mutation score ${score}% under ${Math.round(reworkMin * 100)}%. Plan two phases: an HU with hardens: ${licence.module} in this HU's blocked_by, then the REWORK`];
+}

package/src/prompts/hu-reviewer.js

@@ -156,12 +156,13 @@ export function buildDecompositionPrompt(task, { criteria = [] } = {}) {
 
   sections.push(
     "Return a single valid JSON object and nothing else.",
-    `JSON schema: {"stories":[{"id":string,"title":string,"role":string,"goal":string,"benefit":string,"acceptanceCriteria":[string],"dependsOn":[string],"covers":[number]}]}`,
+    `JSON schema: {"stories":[{"id":string,"title":string,"role":string,"goal":string,"benefit":string,"acceptanceCriteria":[string],"dependsOn":[string],"covers":[number],"tier":"trivial"|"standard"|"deep","tierReason":string}]}`,
     "Rules:",
     "- Generate between 2 and 5 HUs",
     "- Each id must be unique, formatted as HU-DECOMP-NNN (e.g. HU-DECOMP-001)",
     "- dependsOn is an array of other HU ids from this decomposition that must be completed first (empty array if no dependencies)",
     "- acceptanceCriteria should be concrete, testable statements",
+    "- tier is how hard the HU is to implement right (trivial: a local change; standard: several files or one module; deep: design decisions, many modules, or security/migrations), and tierReason says why in one line",
     "- Order stories so that dependencies are respected (a story should only depend on stories with lower ids)",
     ...(criteria.length > 0 ? [
       "- covers lists the numbers of the card's acceptance criteria this HU implements; EVERY card criterion must appear in the covers of at least one HU, and an HU's acceptanceCriteria must include each criterion it covers, verbatim",
@@ -201,7 +202,9 @@ export function parseDecompositionOutput(raw) {
       benefit: s.benefit || "",
       acceptanceCriteria: Array.isArray(s.acceptanceCriteria) ? s.acceptanceCriteria : [],
       dependsOn: Array.isArray(s.dependsOn) ? s.dependsOn : [],
-      covers: Array.isArray(s.covers) ? s.covers.map(Number).filter(Number.isInteger) : []
+      covers: Array.isArray(s.covers) ? s.covers.map(Number).filter(Number.isInteger) : [],
+      tier: s.tier ?? null,
+      tierReason: s.tierReason ?? null
     }));
 
   return stories.length > 0 ? stories : null;

package/src/prompts/planner.js

@@ -257,10 +257,18 @@ export function buildPlannerPrompt({ task, context, architectContext, productCon
     '  "spec_section": "<see rules below>",',
     '  "acceptance_tests": [ /* see rules below */ ],',
     '  "dependencies": [ "<symbolic ids of OTHER steps this one waits for>" ],',
-    '  "reuse": [ "<symbolic ids of OTHER steps whose functionality this one piggy-backs on instead of reimplementing>" ]',
+    '  "reuse": [ "<symbolic ids of OTHER steps whose functionality this one piggy-backs on instead of reimplementing>" ],',
+    '  "change_class": "<extend | rework | rebuild: only when the step changes code already written>",',
+    '  "change_criterion": "<one line: why this class>",',
+    '  "hardens": "<module path, only on a step that strengthens a module\'s tests so it can be reworked>"',
     "}",
     "```",
     "",
+    "### `change_class` (KJC-TSK-0717: only for steps that change code already written; omit it for new code)",
+    "- `extend`: edit the module in place. `rework`: regenerate the module with its tests as the contract. `rebuild`: replace the subsystem.",
+    "- `change_criterion` says why, in one line. A `rework` is the greenfield alternative (what you would build if this code did not exist) winning on price and criterion: say that, do not restate the whole alternatives clause.",
+    "- A `rework` needs a licence, the module's mutation score: it is computed after planning with `kj plan license <plan> <hu> --module <path>`. When the module's tests look thin, add a step first with `hardens: <module>` and list it in the rework step's `dependencies`.",
+    "",
     "### `description` (REQUIRED — MUST start with `[EPICA] ` prefix)",
     "- The first 80 chars of `description` become the HU's title on the board, so the prefix is the user's only at-a-glance signal of \"which area of the plan does this card belong to\".",
     "- Identify the EPICA from the task text — typically a heading like `### Épica PROFILE`, `## Auth`, `# Layer N — name`, or a categorical noun the user uses repeatedly (e.g. `INFRA`, `SHARED`, `UI`, `API`).",

package/src/report/model-tally.js

@@ -0,0 +1,39 @@
+/**
+ * KJC-TSK-1057 (MR-E2): what each coder model cost across the plan's HUs and
+ * how often its HUs failed first time (rejected by the reviewer, or failed),
+ * from the per-HU measurement of KJC-TSK-0702. HUs run before it are the
+ * baseline: counted apart, never as zeros.
+ */
+const sum = (rows, field) => rows.reduce((acc, r) => acc + (Number.isFinite(r.outcome[field]) ? r.outcome[field] : 0), 0);
+const round = (n, digits) => Math.round(n * 10 ** digits) / 10 ** digits;
+
+export function modelTally(hus) {
+  const measured = (hus ?? []).filter((h) => h?.outcome?.coder?.model);
+  const byModel = Object.groupBy(measured, (h) => h.outcome.coder.model);
+  const models = Object.entries(byModel).map(([model, rows]) => {
+    const withIterations = rows.filter((r) => Number.isFinite(r.outcome.iterations));
+    const failed = rows.filter((r) => r.outcome.status !== "done" || r.outcome.reviewer_rejections > 0).length;
+    return {
+      model,
+      hus: rows.length,
+      cost_usd: round(sum(rows, "cost_usd"), 6),
+      tokens_in: sum(rows, "tokens_in"),
+      tokens_out: sum(rows, "tokens_out"),
+      mean_iterations: withIterations.length ? round(sum(withIterations, "iterations") / withIterations.length, 2) : null,
+      failure_rate: round(failed / rows.length, 4),
+    };
+  });
+  return { models, unmeasured: (hus ?? []).length - measured.length };
+}
+
+/** The kj report block, or null when no HU was run at all. */
+export function formatModelTally({ models, unmeasured }) {
+  if (models.length === 0 && unmeasured === 0) return null;
+  const lines = ["Coder models (per HU, from the plans):"];
+  for (const m of models) {
+    const iterations = m.mean_iterations === null ? "-" : m.mean_iterations.toFixed(1);
+    lines.push(`  ${m.model.padEnd(24)} ${m.hus} HU · $${m.cost_usd.toFixed(4)} · ${m.tokens_in} in / ${m.tokens_out} out · ${iterations} iter · ${Math.round(m.failure_rate * 100)}% failed first time`);
+  }
+  if (unmeasured > 0) lines.push(`  ${unmeasured} HU(s) before the measurement (baseline, unmeasured)`);
+  return lines.join("\n");
+}

package/src/review/branch-overlap.js

@@ -0,0 +1,40 @@
+/**
+ * KJC-TSK-1052 (TEAM-F): a team on one repo collides in the merge when two
+ * branches change the same files. kj warns at review time: the remote branches
+ * still in progress (commits outside origin/<base>, active in the last days)
+ * whose changes share files with what the commit stages. A warning, never a block.
+ */
+import { runCommand } from "../utils/process.js";
+
+const MAX_AGE_DAYS = 14;
+const MAX_BRANCHES = 20;
+
+/**
+ * @returns {Promise<{branch: string, author: string, files: string[]}[]>}
+ */
+export async function branchOverlaps({ projectDir, stagedFiles, base = "main", now = Date.now(), run = runCommand }) {
+  const git = async (args) => {
+    const res = await run("git", ["-C", projectDir, ...args]);
+    return res.exitCode === 0 ? res.stdout.trim() : null;
+  };
+  const baseRef = `origin/${base}`;
+  if (stagedFiles.length === 0 || (await git(["rev-parse", "--verify", "--quiet", baseRef])) === null) return [];
+  const current = await git(["rev-parse", "--abbrev-ref", "HEAD"]);
+  const refs = (await git(["for-each-ref", "--sort=-committerdate", "--format=%(refname:short)|%(committerdate:unix)|%(authorname)", "refs/remotes/origin"])) ?? "";
+  const staged = new Set(stagedFiles);
+  const candidates = refs.split("\n").filter(Boolean)
+    .map((line) => { const [branch, when, author] = line.split("|"); return { branch, when: Number(when) * 1000, author }; })
+    .filter((r) => r.branch !== baseRef && r.branch !== "origin/HEAD" && r.branch !== `origin/${current}`)
+    .filter((r) => now - r.when < MAX_AGE_DAYS * 86_400_000)
+    .slice(0, MAX_BRANCHES);
+  const overlaps = [];
+  for (const { branch, author } of candidates) {
+    if (Number(await git(["rev-list", "--count", `${baseRef}..${branch}`])) === 0) continue;
+    const files = ((await git(["diff", "--name-only", `${baseRef}...${branch}`])) ?? "").split("\n").filter((f) => staged.has(f));
+    if (files.length > 0) overlaps.push({ branch, author, files });
+  }
+  return overlaps;
+}
+
+/** The kj review warning, one line per branch. */
+export const formatOverlaps = (overlaps) => overlaps.map((o) => `⚠ ${o.branch} (${o.author}) also changes ${o.files.join(", ")}: coordinate before the merge collides`);

package/src/review/dep-cooldown.js

@@ -0,0 +1,87 @@
+/**
+ * KJC-TSK-0722 (step 1): supply-chain campaigns (Shai-Hulud, CanisterWorm) are
+ * caught in their first hours, so a dependency published minutes ago is the
+ * riskiest one to take. kj reads what a package-lock.json diff installs and
+ * asks npm how old each version is. A signal, never a crash: without the
+ * registry, the package is listed as unverified with the reason.
+ */
+import { runCommand } from "../utils/process.js";
+
+export const DEFAULT_COOLDOWN_HOURS = 72;
+// npm view per package: a lockfile refresh of hundreds is said, not queried one by one.
+const MAX_QUERIES = 40;
+
+const KEY = /^[ +]\s*"(?:[^"]*\/)?node_modules\/((?:@[^/"]+\/)?[^/"]+)":\s*\{/;
+const VERSION = /^\+\s*"version":\s*"([^"]+)"/;
+
+/** The packages a diff of package-lock.json adds or moves to another version. */
+export function lockfileChanges(diff) {
+  const changes = [];
+  for (const chunk of String(diff ?? "").split(/^diff --git /m)) {
+    if (!/^a\/(?:\S*\/)?package-lock\.json /.test(chunk)) continue;
+    let current = null;
+    for (const line of chunk.split("\n")) {
+      const key = KEY.exec(line);
+      if (key) { current = key[1]; continue; }
+      const version = VERSION.exec(line);
+      if (version && current) { changes.push({ name: current, version: version[1] }); current = null; }
+    }
+  }
+  return changes;
+}
+
+async function publishedAt({ name, version }, run) {
+  const res = await run("npm", ["view", `${name}@${version}`, "time", "--json"]);
+  if (res.exitCode !== 0) throw new Error((res.stderr || res.stdout || "npm view failed").trim());
+  const when = Date.parse(JSON.parse(res.stdout || "{}")[version]);
+  if (Number.isNaN(when)) throw new Error(`npm gives no publish time for ${version}`);
+  return when;
+}
+
+export const COOLDOWN_RULE_ID = "method.dep_cooldown";
+
+/**
+ * KJC-TSK-1056: with method_gates.dep_cooldown: block, a young dependency stops
+ * the review; only a live human grant on method.dep_cooldown lifts it. What
+ * could not be verified (no registry) never blocks: a false positive would
+ * stop legitimate work for a network blip.
+ */
+export function cooldownGate({ result, mode, standingExceptions = [], now = new Date() }) {
+  if (mode !== "block" || result.young.length === 0) return { block: false };
+  const grant = standingExceptions.find((e) => e.rule_id === COOLDOWN_RULE_ID && new Date(e.expiresAt).getTime() > now.getTime());
+  if (grant) return { block: false, grant };
+  const list = result.young.map((p) => `${p.name}@${p.version} (${p.hours} h)`).join(", ");
+  return { block: true, reason: `${result.young.length} dependency(ies) under the cooldown: ${list} (method_gates.dep_cooldown: block). Wait it out, pin an older version, or a human lifts it: kj policy grant --rule ${COOLDOWN_RULE_ID} --until <iso> --reason "<why>"` };
+}
+
+/** What kj review prints, and the note the reviewer gets; empty when there is nothing to say. */
+export function formatCooldown({ young, unverified, skipped = 0 }, thresholdHours = DEFAULT_COOLDOWN_HOURS) {
+  const lines = [
+    ...young.map((p) => `⚠ supply-chain cooldown: ${p.name}@${p.version} was published ${p.hours} h ago (under ${thresholdHours} h): campaigns are caught in their first hours`),
+    ...unverified.map((p) => `⚠ supply-chain cooldown: ${p.name}@${p.version} unverified (${p.reason})`),
+    ...(skipped > 0 ? [`⚠ supply-chain cooldown: ${skipped} packages changed (a regenerated lockfile?), too many to check one by one: none was checked`] : []),
+  ];
+  const note = young.length === 0 ? "" : `Dependencies published under ${thresholdHours} h ago (weigh them as a supply-chain risk): ${young.map((p) => `${p.name}@${p.version} (${p.hours} h)`).join(", ")}`;
+  return { lines, note };
+}
+
+/**
+ * Over MAX_QUERIES changed packages (a regenerated lockfile) none is queried:
+ * one line says so, instead of a line per package and a call per package.
+ * @returns {Promise<{young: {name, version, hours}[], unverified: {name, version, reason}[], skipped?: number}>}
+ */
+export async function cooldownAdvisories(diff, { thresholdHours = DEFAULT_COOLDOWN_HOURS, run = runCommand, now = Date.now() } = {}) {
+  const changes = lockfileChanges(diff);
+  if (changes.length > MAX_QUERIES) return { young: [], unverified: [], skipped: changes.length };
+  const young = [];
+  const unverified = [];
+  for (const pkg of changes) {
+    try {
+      const hours = Math.floor((now - await publishedAt(pkg, run)) / 3_600_000);
+      if (hours < thresholdHours) young.push({ ...pkg, hours });
+    } catch (err) {
+      unverified.push({ ...pkg, reason: err.message });
+    }
+  }
+  return { young, unverified };
+}

package/src/review/one-shot-review.js

@@ -12,7 +12,7 @@ import { createAgent } from "../agents/index.js";
 import { resolveRole } from "../config/role-resolver.js";
 import { buildReviewerPrompt } from "../prompts/reviewer.js";
 import { resolveReviewProfile } from "./profiles.js";
-import { parseMaybeJsonString, normalizeReviewPayload, agentAnswerText } from "./parser.js";
+import { parseReviewVerdict } from "./parser.js";
 import { detectAvailableAgents, detectHostAgent } from "../utils/agent-detect.js";
 import { saveVerdict, diffHash } from "./verdict-store.js";
 import { summarizeGeneratedFiles } from "./prompt-diff.js";
@@ -117,7 +117,7 @@ export async function runOneShotReview({
   // back, wrapper and all. Yesterday's fix taught normalizeReviewPayload to unwrap {ok, result},
   // but this path never called it, so the bug survived with a green test on the wrong function.
   // A test can only prove the code it actually exercises.
-  const parsed = normalizeReviewPayload(parseMaybeJsonString(agentAnswerText(result.output)));
+  const parsed = parseReviewVerdict(result.output);
   if (!parsed || typeof parsed.approved !== "boolean") {
     // KJC-BUG-0146: keep the answer. Throwing it away is what left eight occurrences undiagnosed.
     throw new Error(await reportUnparseableVerdict({ projectDir, reviewer: activeReviewer, output: result.output, hash: diffHash(diff) }));

package/src/review/parser.js

@@ -26,6 +26,11 @@ export function agentAnswerText(raw) {
   return raw;
 }
 
+/** The review verdict in an agent's answer, or null: the one path kj review reads it by. */
+export function parseReviewVerdict(output) {
+  return normalizeReviewPayload(parseMaybeJsonString(agentAnswerText(output)));
+}
+
 function isReviewPayload(obj) {
   return obj?.approved !== undefined && obj?.blocking_issues !== undefined;
 }

package/src/review/publish-pr.js

@@ -0,0 +1,54 @@
+/**
+ * KJC-TSK-0913: the cross-AI verdict kj holds for each commit of a PR, published
+ * on the PR as ONE GitHub review (event COMMENT), so the review that already
+ * happened counts in reviews.totalCount instead of looking like a blind merge.
+ * A loose conversation comment does not count, so it is never used.
+ */
+import { runCommand } from "../utils/process.js";
+import { diffHash, loadVerdict } from "./verdict-store.js";
+
+const MARKER = (head) => `<!-- kj-review head=${head} -->`;
+
+// gh runs in the project's own directory, so it reads and writes the same repo the verdicts belong to.
+async function json(run, cmd, args, cwd) {
+  const res = await run(cmd, args, { cwd });
+  if (res.exitCode !== 0) throw new Error(`${cmd} ${args.slice(0, 3).join(" ")} failed: ${(res.stderr || res.stdout || "").trim()}`);
+  return JSON.parse(res.stdout || "null");
+}
+
+/** The verdict of a commit: the one recorded for the diff it brought, staged byte for byte. */
+async function verdictOf(projectDir, sha, run) {
+  const res = await run("git", ["-C", projectDir, "diff", `${sha}^`, sha]);
+  return res.exitCode === 0 && res.stdout ? loadVerdict(projectDir, diffHash(res.stdout)) : null;
+}
+
+/**
+ * @returns {Promise<{published: boolean, commits?: number, reason?: string}>}
+ */
+export async function publishPrReview({ projectDir, pr, run = runCommand }) {
+  const info = await json(run, "gh", ["pr", "view", String(pr), "--json", "headRefOid,commits"], projectDir);
+  const rows = [];
+  const uncovered = [];
+  for (const c of info.commits ?? []) {
+    const v = await verdictOf(projectDir, c.oid, run);
+    if (v?.verdict === "approved") rows.push({ ...c, v });
+    else uncovered.push(`${c.oid.slice(0, 7)} (${c.messageHeadline})`);
+  }
+  if (uncovered.length > 0) throw new Error(`PR #${pr}: ${uncovered.length} commit(s) without an approved verdict of their exact diff, nothing published: ${uncovered.join(", ")}`);
+  const reviews = await json(run, "gh", ["api", `repos/{owner}/{repo}/pulls/${pr}/reviews`], projectDir);
+  if ((reviews ?? []).some((r) => String(r.body ?? "").includes(MARKER(info.headRefOid)))) {
+    return { published: false, reason: `a kj review for head ${info.headRefOid.slice(0, 7)} is already published` };
+  }
+  const body = [
+    `Cross-AI review by Karajan, one verdict per commit, each bound to the exact diff it brought.`,
+    "",
+    ...rows.map((r) => {
+      const summary = r.v.summary ? ". " + r.v.summary : "";
+      return `- \`${r.oid.slice(0, 7)}\` ${r.messageHeadline}: approved by ${r.v.reviewer} (diff ${r.v.diffHash.slice(0, 12)})${summary}`;
+    }),
+    "",
+    MARKER(info.headRefOid),
+  ].join("\n");
+  await json(run, "gh", ["api", "-X", "POST", `repos/{owner}/{repo}/pulls/${pr}/reviews`, "-f", "event=COMMENT", "-f", `commit_id=${info.headRefOid}`, "-f", `body=${body}`], projectDir);
+  return { published: true, commits: rows.length };
+}