@karajan-family/code 4.52.0 → 4.53.1

package/src/harden/sentinel/sentinel-shell.mjs

@@ -155,6 +155,65 @@ export const stripTextOptionValues = (cmd) => cmd
   .replace(KJ_TITLE, (m, pre, head, val) => `${pre}${head}${val[0]}${val[0]}`)
   .replace(QUOTED_OPTION_VALUE, (m, pre, opt, sep, val) => (TEXT_OPTIONS.has(opt) ? `${pre}${opt}${sep}${val[0]}${val[0]}` : m));
 
+// KJC-BUG-0354: commands that only STORE their text: there, a quoted text value
+// is never run. Anywhere else it may be (flock --command '...'), so it stays.
+// git's global options that only pick where and how it runs may precede commit.
+const GIT_GLOBAL_WITH_VALUE = new Set(["-c", "-C", "--git-dir", "--work-tree", "--namespace"]);
+const GIT_GLOBAL_FLAG = /^(?:--no-pager|--(?:git-dir|work-tree|namespace)=\S+)$/;
+
+const isGitCommit = (words) => {
+  let i = 1;
+  while (i < words.length) {
+    if (GIT_GLOBAL_WITH_VALUE.has(words[i])) i += 2;
+    else if (GIT_GLOBAL_FLAG.test(words[i])) i += 1;
+    else break;
+  }
+  return words[0] === "git" && words[i] === "commit";
+};
+
+const isTextOnlyHead = (seg) => /^kj\s+(?:hu|adr)\s+add\b/.test(seg) || isGitCommit(seg.split(/\s+/));
+
+/**
+ * KJC-BUG-0354: blank the quoted text values (stripTextOptionValues) only when the
+ * whole input is a text-only command, so the human-act guards stop reading a
+ * title or a commit message that merely mentions a guarded command.
+ * @param {string} cmd
+ */
+export const stripTextOnlyCommandValues = (cmd) => {
+  // Only a whole input that is ONE simple text-storage command: a chained
+  // segment could follow a shell function that turns the stored text into code.
+  const bare = stripInertQuotes(cmd);
+  if (splitOutsideQuotes(cmd).length !== 1 || /[(){}<>`$\n]/.test(bare) || !isTextOnlyHead(cmd.trim())) return cmd;
+  return stripTextOptionValues(cmd);
+};
+
+/** Segments and the ; && || | between them, cut only outside quotes (the pieces join back to cmd). */
+function splitOutsideQuotes(cmd) {
+  const parts = [];
+  let start = 0;
+  let quote = null;
+  let i = 0;
+  while (i < cmd.length) {
+    const c = cmd[i];
+    const op = quote ? null : /^(?:&&|\|\||;|\|)/.exec(cmd.slice(i))?.[0];
+    if (quote) {
+      // inside double quotes a backslash escapes the next character
+      if (c === "\\" && quote === '"') i += 1;
+      else if (c === quote) quote = null;
+    } else if (c === "'" || c === '"') {
+      quote = c;
+    } else if (op) {
+      parts.push(cmd.slice(start, i), op);
+      start = i + op.length;
+      i = start;
+      continue;
+    }
+    i += 1;
+  }
+  parts.push(cmd.slice(start));
+  return parts;
+}
+
 /**
  * KJC-BUG-0245: the values of the named options, read by the shell reader, so a
  * `;`, `&&` or `|` right after a path ends the word instead of joining it.

package/src/harden/sentinel-hooks.js

@@ -88,7 +88,7 @@ export const boardGate = (sid, pend) => {
   if (!pend.length) return { blocking: [], carried: [] };
   const bg = spawnSync("kj", ["sentinel", "board-gate", "--session", sid, "--json"], { cwd: ROOT, encoding: "utf8" });
   if (!bg.error && (bg.status === 0 || bg.status === 2)) {
-    try { const d = JSON.parse(bg.stdout); return { blocking: d.blocking || [], carried: d.carried || [] }; } catch { /* unreadable: as always */ }
+    try { const d = JSON.parse(bg.stdout); return { blocking: d.blocking || [], carried: d.carried || [], reason: d.reason || "" }; } catch { /* unreadable: as always */ }
   }
   return { blocking: pend, carried: [] };
 };
@@ -473,7 +473,7 @@ import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { doc, CODE, TESTS, ROOT, BASE_BRANCHES, CARD, STATE, branchOf, foreignLane, load, save, session, violations, boardGate, pendingMoves, pendingText } from "./sentinel-lib.mjs";
 // KJC-TSK-0915 (ADR 0014): the shell reader is a real, unit-tested module copied here as is.
-import { isGhIssueCreate, isPublishCommand, optionValues, shellSegments, stripInertQuotes, stripTextOptionValues } from "./sentinel-shell.mjs";
+import { isGhIssueCreate, isPublishCommand, optionValues, shellSegments, stripInertQuotes, stripTextOptionValues, stripTextOnlyCommandValues } from "./sentinel-shell.mjs";
 import { DISCARD_VERBS, discardOf, foreignLost, removedFiles } from "./sentinel-discard.mjs";
 import { shellWrites, writesRepo } from "./sentinel-bash-write.mjs";
 const EDIT_TOOLS = ["Write", "Edit", "MultiEdit", "NotebookEdit"];
@@ -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);
       }
@@ -605,7 +606,8 @@ process.stdin.on("end", () => {
     // — si un agente pudiera enrolar una clave SUYA, contestaria la capa 5 el
     // solo. Ni el comando ni el fichero de enrolamiento desde la sesion.
     {
-      const enrollCmd = String(input.command || "");
+      // KJC-BUG-0354: un titulo o un mensaje de commit que solo lo MENCIONA no es enrolar.
+      const enrollCmd = stripTextOnlyCommandValues(String(input.command || ""));
       const namesEnroll = (enrollCmd.includes("identity") && enrollCmd.includes("enroll-phone")) || enrollCmd.includes("supervisor-phone.json");
       const writesEnroll = EDIT_TOOLS.includes(tool) && String(input.file_path || "").includes("supervisor-phone.json");
       if ((tool === "Bash" && namesEnroll) || writesEnroll) {
@@ -617,11 +619,13 @@ process.stdin.on("end", () => {
     // sesion ni lo intenta. Sin escape (superficie de supervisor). includes()
     // a proposito: cero ambiguedad de escapes en plantilla, y fail-closed
     // (mencionarlo en un argumento tambien bloquea: preferible a un hueco).
+    // KJC-BUG-0354: salvo en el texto entrecomillado de kj hu add, kj adr add y
+    // git commit, que solo guardan texto (decision del usuario, 16-oct).
     // ANTES de KJ_SENTINEL_OFF a proposito, como el guard PROTECTED de
     // arriba: un env var lo pone tambien un agente — el supervisor no se
     // apaga con interruptores al alcance del supervisado.
     {
-      const kjCmd = String(input.command || "");
+      const kjCmd = stripTextOnlyCommandValues(String(input.command || ""));
       if (tool === "Bash" && kjCmd.includes("harden") && kjCmd.includes("--commit")) {
         console.error("karajan sentinel: kj harden --commit es un acto humano (ADR 0009) — pideselo a tu usuario; ninguna sesion de agente lo ejecuta." + doc("supervisor"));
         process.exit(2);
@@ -1170,15 +1174,20 @@ process.stdin.on("end", () => {
       const ADVANCE = /\\bgit\\s+commit\\b|\\bgit\\s+push\\b|\\bgh\\s+pr\\s+create\\b/; // push also falls under violations() — explicit here too (review catch)
       const mergeM = cmd.match(MERGE);
       const pend = pendingMoves(load().sessions?.[sid]);
+      // KJC-BUG-0364: one board-gate decision per command; the push gate below
+      // reuses it, so a second slow gh cannot contradict the first answer.
+      let boardDecision = null;
       if (pend.length > 0 && (mergeM || ADVANCE.test(cmd))) {
         // KJC-BUG-0198: una card partida en varias PRs no puede quedar bloqueada
         // por su primera mitad (boardGate, en la lib).
-        const { blocking, carried } = boardGate(sid, pend);
+        boardDecision = boardGate(sid, pend);
+        const { blocking, carried, reason } = boardDecision;
         for (const c of carried) console.error("karajan sentinel: board-sync arrastra " + c.card + " — " + c.why + ", se movera al cerrarla");
         // ADR 0015 (KJC-TSK-0925): no escape; an epic and a card split across PRs
         // are already decided above (KJC-BUG-0230, 0198).
+        // KJC-BUG-0363: when kj could not check, its reason travels with the block.
         if (blocking.length > 0) {
-          console.error("karajan sentinel: board-sync — el metodo no avanza con cards mergeadas sin mover:\\n" + blocking.map((p) => "- " + pendingText(p)).join("\\n") + doc("board-sync"));
+          console.error("karajan sentinel: board-sync — el metodo no avanza con cards mergeadas sin mover:\\n" + blocking.map((p) => "- " + pendingText(p)).join("\\n") + (reason ? "\\n(" + reason + ")" : "") + doc("board-sync"));
           process.exit(2);
         }
       }
@@ -1224,9 +1233,10 @@ process.stdin.on("end", () => {
         // ADR 0015 (KJC-TSK-0925): with no escape.
         // KJC-BUG-0262: a carried card does not block the push the commit let through.
         const sess = load().sessions?.[sid];
-        const v = violations(sess, branchOf(), boardGate(sid, pendingMoves(sess)).blocking);
+        const decision = boardDecision || boardGate(sid, pendingMoves(sess));
+        const v = violations(sess, branchOf(), decision.blocking);
         if (v.length) {
-          console.error("karajan sentinel: git push con el metodo en rojo:\\n" + v.map((x) => "- " + x).join("\\n") + "\\nResuelve antes de empujar. Estado: kj sentinel status" + doc("push-gate"));
+          console.error("karajan sentinel: git push con el metodo en rojo:\\n" + v.map((x) => "- " + x).join("\\n") + (decision.reason ? "\\n(" + decision.reason + ")" : "") + "\\nResuelve antes de empujar. Estado: kj sentinel status" + doc("push-gate"));
           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");
+}