karajan-code 4.51.1 → 4.53.0

package/src/harden/phone-texts.js

@@ -0,0 +1,17 @@
+/**
+ * What kj says about the phone (ADR 0018). Apart from phone-invite.js so that
+ * security-level.js and act-sign.js can use the texts while phone-invite.js
+ * reads the security level, with no import cycle.
+ */
+export const PHONE_ENROLL =
+  "Enrólalo con kj identity enroll-phone <clave pública de la app>: cada acto queda atado a tu clave privada, que nunca sale del móvil (ADR 0018).";
+
+/** Normal level: without a phone the acts are signed with a typed code. */
+export const PHONE_INVITE =
+  `El móvil no está enrolado: los sellos (kj harden --commit), las aprobaciones y los comandos del catálogo se firman hoy con un código tecleado, con menos garantía. ${PHONE_ENROLL}`;
+
+/** KJC-BUG-0360: max level, the default: without a phone the acts are REFUSED, not signed with a code. */
+export const PHONE_REFUSED_AT_MAX =
+  `El móvil no está enrolado y la seguridad es máxima (la de por defecto): kj harden --commit, kj rules approve y enrolar otro móvil se rechazan hasta enrolarlo. ${PHONE_ENROLL}`;
+
+export const phoneTextFor = (level) => (level === "normal" ? PHONE_INVITE : PHONE_REFUSED_AT_MAX);

package/src/harden/security-level.js

@@ -12,7 +12,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 
 import { humanActOf } from "./human-act.js";
-import { PHONE_INVITE } from "./phone-invite.js";
+import { PHONE_ENROLL } from "./phone-texts.js";
 import { isPhoneEnrolled, readEnrolledKeys, requestPhoneSignature, verifySignedFiles } from "./phone-sign.js";
 
 export const SECURITY_LEVEL_FILE = ".karajan/security-level.json";
@@ -22,6 +22,7 @@ export const SECURITY_LEVEL_FILE = ".karajan/security-level.json";
 export const DEFAULT_LEVEL = "max";
 
 const levelPath = (projectDir) => join(projectDir, SECURITY_LEVEL_FILE);
+const NO_PHONE = "no-phone-enrolled";
 const recordBytes = (record) => `${JSON.stringify(record, null, 2)}\n`;
 const unsigned = ({ level, since }) => ({ level, since });
 
@@ -43,6 +44,12 @@ export function readSecurityLevel({ projectDir, home } = {}) {
   if (record?.level === "max") return { level: "max", source: "file", since: record.since };
   if (record?.level !== "normal") return invalid("declara un nivel que no existe");
   const keys = readEnrolledKeys({ projectDir, home });
+  // KJC-TSK-1045 (ADR 0020): lowered at the terminal while no phone existed; it
+  // lasts only while none does, since every act at normal still asks for the human layers.
+  if (record.unsigned === NO_PHONE && !record.signature) {
+    if (keys.size === 0) return { level: "normal", source: "file", since: record.since, unsigned: true };
+    return invalid("el nivel normal se bajó sin móvil y ya hay uno enrolado; vale como máxima hasta bajarlo firmado");
+  }
   const check = verifySignedFiles({ sig: record.signature, files: signedFilesOf(record), keys });
   if (!check.ok) return invalid(`el nivel normal ${check.reason}; vale como máxima`);
   return { level: "normal", source: "file", since: record.since, signer: record.signature.signer };
@@ -74,8 +81,17 @@ export async function lowerSecurityLevel({ projectDir, home, kjVersion, env, tty
   act.refuse({ env, tty, ancestry: deps.ancestry ?? {} });
   const current = readSecurityLevel({ projectDir, home });
   if (current.level === "normal") return { changed: false, level: current };
+  // KJC-TSK-1045 (ADR 0020): with no phone anywhere, max only blocks; the human
+  // layers and the typed code are the proof, and the record says it is unsigned.
+  if (readEnrolledKeys({ projectDir, home }).size === 0) {
+    act.confirm(deps.confirm);
+    mkdirSync(dirname(levelPath(projectDir)), { recursive: true });
+    writeFileSync(levelPath(projectDir), recordBytes({ level: "normal", since: new Date().toISOString(), unsigned: NO_PHONE }), "utf8");
+    logger.info?.(`${act.label}: nivel normal sin firma (no hay ningún móvil enrolado); en cuanto enroles uno vuelve a valer la máxima. ${PHONE_ENROLL}`);
+    return { changed: true, level: readSecurityLevel({ projectDir, home }) };
+  }
   const phone = deps.phone ?? { enrolled: isPhoneEnrolled, request: requestPhoneSignature };
-  if (!phone.enrolled({ home })) throw new Error(`${act.label}: bajar el nivel se firma con el móvil y no hay ninguno enrolado. ${PHONE_INVITE}`);
+  if (!phone.enrolled({ home })) throw new Error(`${act.label}: bajar el nivel se firma con el móvil y no hay ninguno enrolado. ${PHONE_ENROLL}`);
   act.confirm(deps.confirm);
   const record = { level: "normal", since: new Date().toISOString() };
   let branch = null;

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

@@ -0,0 +1,98 @@
+/**
+ * KJC-TSK-1036 (owner's decision, 14-oct): a lane kj created is retired only when
+ * it is provably abandoned: clean tree, no commits beyond the base, and no live
+ * process working inside it. Anything else is listed with its reason, never
+ * touched, so a session may run this without risking anyone's work.
+ */
+import fs from "node:fs";
+import path from "node:path";
+
+const IDLE_HOURS = 24;
+const REGENERABLE = new Set(["node_modules", "dist", "build", "coverage", ".venv", "venv", "__pycache__", ".cache", "target"]);
+
+/**
+ * This user's live processes (another user's cannot write in our worktrees): the
+ * cwds that can be read and how many cannot (non-dumpable ones: ssh-agent, systemd,
+ * some JVMs). null when the platform has no /proc.
+ */
+export function liveProcesses() {
+  let pids;
+  try { pids = fs.readdirSync("/proc").filter((p) => /^\d+$/.test(p)); } catch { return null; }
+  const cwds = new Set();
+  let unseen = 0;
+  for (const pid of pids) {
+    try {
+      if (fs.statSync(`/proc/${pid}`).uid !== process.getuid()) continue;
+      cwds.add(fs.readlinkSync(`/proc/${pid}/cwd`));
+    } catch (err) {
+      if (err.code !== "ENOENT" && err.code !== "ESRCH") unseen += 1;
+    }
+  }
+  return { cwds, unseen };
+}
+
+/** Hours since anything in the lane moved: its dir, and its git index and HEAD. */
+async function idleHours(git, lanePath, now) {
+  const { stdout } = await git(["rev-parse", "--absolute-git-dir"], lanePath);
+  const gitDir = stdout.trim();
+  const times = [lanePath, path.join(gitDir, "index"), path.join(gitDir, "HEAD")]
+    .map((f) => { try { return fs.statSync(f).mtimeMs; } catch { return 0; } });
+  return (now - Math.max(...times)) / 3_600_000;
+}
+
+const inside = (cwd, dir) => cwd === dir || cwd.startsWith(dir + path.sep);
+
+/** @returns {Promise<{slug: string, path: string, branch: string|null, reasons: string[]}[]>} */
+export async function classifyLanes({ git, laneRoot, base, processes, now = Date.now() }) {
+  const { stdout } = await git(["worktree", "list", "--porcelain"]);
+  const lanes = [];
+  let current = null;
+  for (const line of stdout.split("\n")) {
+    if (line.startsWith("worktree ")) {
+      current = { path: line.slice(9).trim(), branch: null };
+      if (current.path.startsWith(laneRoot + path.sep)) lanes.push(current);
+    } else if (line.startsWith("branch ") && current) current.branch = line.slice(7).trim().replace("refs/heads/", "");
+  }
+  return Promise.all(lanes.map(async (lane) => {
+    const reasons = [];
+    const { stdout: status } = await git(["status", "--porcelain", "--ignored=matching"], lane.path);
+    const entries = status.split("\n").filter(Boolean);
+    if (entries.some((e) => !e.startsWith("!! "))) reasons.push("uncommitted changes");
+    // Ignored files can be valuable (.env, local artifacts); only regenerable dirs are not.
+    const precious = entries.filter((e) => e.startsWith("!! ") && !REGENERABLE.has(e.slice(3).split("/")[0]));
+    if (precious.length > 0) reasons.push(`ignored files that are not regenerable (${precious[0].slice(3)}${precious.length > 1 ? ", …" : ""})`);
+    // The lane's HEAD, branch or detached: a detached lane's commits have no other name.
+    const { stdout: ahead } = await git(["rev-list", "--count", `${base}..HEAD`], lane.path);
+    if (Number(ahead) > 0) reasons.push(`${Number(ahead)} commit(s) not in ${base}`);
+    if (processes === null) reasons.push("cannot check for live processes on this platform");
+    else if ([...processes.cwds].some((cwd) => inside(cwd, lane.path))) reasons.push("a live process works in it");
+    else if (processes.unseen > 0 && (await idleHours(git, lane.path, now)) < IDLE_HOURS) {
+      reasons.push(`${processes.unseen} process(es) of yours cannot be inspected and the lane changed in the last ${IDLE_HOURS} h`);
+    }
+    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/mcp/handlers/direct-handlers.js

@@ -11,7 +11,7 @@ import { createAgent } from "../../agents/index.js";
 import { buildPlannerPrompt } from "../../prompts/planner.js";
 import { buildCoderPrompt } from "../../prompts/coder.js";
 import { buildReviewerPrompt } from "../../prompts/reviewer.js";
-import { parseMaybeJsonString } from "../../review/parser.js";
+import { parseMaybeJsonString, agentAnswerText } from "../../review/parser.js";
 import { computeBaseRef, generateDiff } from "../../review/diff-generator.js";
 import { resolveReviewProfile } from "../../review/profiles.js";
 import { createRunLog } from "../../utils/run-log.js";
@@ -322,7 +322,7 @@ export async function handleReviewDirect(a, server, extra) {
   }
 
   sendTrackerLog(server, "reviewer", "done");
-  const parsed = parseMaybeJsonString(result.output);
+  const parsed = parseMaybeJsonString(agentAnswerText(result.output));
   return { ok: true, review: parsed || result.output, raw: result.output };
 }
 

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/reviewer-stage.js

@@ -15,6 +15,7 @@ import { invokeSolomon } from "../solomon-escalation.js";
 import { detectRateLimit } from "../../utils/rate-limit-detector.js";
 import { createStallDetector } from "../../utils/stall-detector.js";
 import { applyQuotaSimulation } from "../../utils/quota-simulator.js";
+import { correctionNote } from "../../review/correction-rounds.js";
 
 function categorizeIssues(issues) {
   const categories = { security: 0, correctness: 0, tests: 0, style: 0, other: 0 };
@@ -33,6 +34,12 @@ function categorizeIssues(issues) {
   return categories;
 }
 
+// KJC-TSK-1017: the rejections before an approval are review corrections.
+export function approvedMessage(session) {
+  const rejections = (session.checkpoints || []).filter((cp) => cp.stage === "reviewer" && cp.approved === false).length;
+  return ["Review approved", correctionNote(rejections)].filter(Boolean).join(" — ");
+}
+
 function buildReviewHistory(session) {
   return (session.checkpoints || [])
     .filter(cp => cp.stage === "reviewer")
@@ -402,7 +409,7 @@ export async function runReviewerStage({ reviewerRole, config, logger, emitter,
     emitter,
     makeEvent("reviewer:end", { ...eventBase, stage: "reviewer" }, {
       status: review.approved ? "ok" : "fail",
-      message: review.approved ? "Review approved" : `Review rejected (${review.blocking_issues.length} blocking)`,
+      message: review.approved ? approvedMessage(session) : `Review rejected (${review.blocking_issues.length} blocking)`,
       detail: {
         approved: review.approved,
         blockingCount: review.blocking_issues.length,

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");
+}