karajan-code 4.44.1 → 4.46.0

package/package.json

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

package/src/commands/identity.js

@@ -10,6 +10,7 @@
 
 import { addSigner, enrollPhone } from "../harden/phone-sign.js";
 import { phoneInvite } from "../harden/phone-invite.js";
+import { humanAct } from "../harden/human-act.js";
 import { readIdentity, writeIdentity } from "../identity/store.js";
 import { activeGhUser, effectiveGitEmail } from "../identity/detect.js";
 import { compareIdentity } from "../identity/compare.js";
@@ -28,6 +29,9 @@ export async function identityCommand({ action = "show", config, flags = {}, dep
   // KJC-TSK-0822: enrola la clave PÚBLICA del móvil (la privada nunca toca esta máquina).
   if (action === "enroll-phone") {
     try {
+      // KJC-TSK-0966 (HUM-C, ADR 0018): enrolar es un acto del catálogo; hasta hoy
+      // solo lo frenaba el Sentinel, y un kj fuera de Claude no tiene Sentinel.
+      humanAct("phone-enroll", { env: deps.env ?? process.env, tty: deps.ttyHuman ?? process.stdout.isTTY, ancestry: deps.ancestry ?? {}, confirm: deps.confirm });
       // KJC-TSK-0831 (ADR 0010): añade al PADRÓN versionado del repo (compartible,
       // base para la verificación en CI) y mantiene la clave legacy en ~/.karajan.
       addSigner(flags.publicKeyBase64, { projectDir, label: flags.label });

package/src/commands/rules-approve.js

@@ -12,12 +12,11 @@ import path from "node:path";
 
 import yaml from "js-yaml";
 
-import { confirmHuman, refuseAgentSession } from "../harden/human-act.js";
+import { humanActOf } from "../harden/human-act.js";
 import { checkVerdict } from "../review/verdict-store.js";
 import { approvalView } from "../rules/approval-view.js";
 import { loadRules, LOCAL_RULES_FILE, PROPOSAL_FILE, RULES_FILE, rulesCheck } from "./rules.js";
 
-const ACT = "kj rules approve";
 
 /**
  * @param {{projectDir: string, file?: string, home?: string, env?: object, tty?: boolean,
@@ -25,7 +24,8 @@ const ACT = "kj rules approve";
  * @returns {Promise<{code: 0|1, lines: string[]}>}
  */
 export async function rulesApprove({ projectDir, file = PROPOSAL_FILE, home, env, tty, deps = {}, log = console.log }) {
-  refuseAgentSession(ACT, { env, tty, ancestry: deps.ancestry ?? {} });
+  const act = humanActOf("rules-approve");
+  act.refuse({ env, tty, ancestry: deps.ancestry ?? {} });
   const proposal = path.resolve(projectDir, file);
   let text;
   try { text = fs.readFileSync(proposal, "utf8"); } catch { return { code: 1, lines: [`✗ no ${file}: nothing to approve`] }; }
@@ -48,7 +48,7 @@ export async function rulesApprove({ projectDir, file = PROPOSAL_FILE, home, env
   // KJC-TSK-0962: read in the order of what can hurt, weakened rules first.
   const view = approvalView(rules, loadRules(projectDir).rules, local, { versioned: RULES_FILE, unversioned: LOCAL_RULES_FILE });
   for (const line of view) log(line);
-  confirmHuman(ACT, deps.confirm);
+  act.confirm(deps.confirm);
   // KJC-TSK-0961 (ADR 0017): a rule written only in the user's private MD files
   // is not versioned. Where it goes is the inventory's word, not the proposal's.
   const parts = [[RULES_FILE, rules.filter((rule) => !local.has(rule.id))], [LOCAL_RULES_FILE, rules.filter((rule) => local.has(rule.id))]];

package/src/environment/contract-commit.js

@@ -40,6 +40,8 @@ const runner = (projectDir, env) => (args) => execFileSync("git", ["-C", project
 // or under a stack root (a fullstack monorepo is hardened on every side).
 const isContract = (file) =>
   CONTRACT_PATHS.some((p) => (p.endsWith("/") || p.endsWith("-") ? file.startsWith(p) : file === p)) || GENERATED_CONFIG_FILES.has(basename(file));
+/** The supervisor's files: the hooks and their provenance, sealed by the human (ADR 0009). */
+const isSupervisor = (file) => file.startsWith(".karajan/hooks/") || file === ".karajan/supervisor-provenance.json";
 
 /** The contract files git sees as changed, with their porcelain code (`??` untracked). */
 function contractStatus(git) {
@@ -70,9 +72,14 @@ const branchOf = (git) => { try { return git(["symbolic-ref", "--short", "HEAD"]
  */
 export function commitContract({ projectDir, before = new Set(), baseBranch = "main", env = process.env }) {
   const git = runner(projectDir, env);
-  const files = contractStatus(git).map(([file]) => file).filter((file) => !before.has(file)).sort();
-  if (files.length === 0) return { committed: false, reason: "nothing of the contract to commit" };
   const history = hasCommits(git);
+  // KJC-BUG-0302: a sealed supervisor regenerated (tracked hooks or provenance
+  // that changed) is the seal's, a human act (ADR 0009), never the contract
+  // commit's: regenerated together after a version bump, the gate refused the one
+  // and the seal the other, and the person had to unstage the hook by hand. The
+  // first install (untracked hooks) still rides in the contract commit.
+  const files = contractStatus(git).filter(([file, code]) => !before.has(file) && !(history && code !== "??" && isSupervisor(file))).map(([file]) => file).sort();
+  if (files.length === 0) return { committed: false, reason: "nothing of the contract to commit" };
   if (history && branchOf(git) === baseBranch) {
     // kj never commits on the base branch, and will not switch the person's branch
     // for them: the files are named so the commit can be made where it belongs.
@@ -83,7 +90,10 @@ export function commitContract({ projectDir, before = new Set(), baseBranch = "m
     // --only: these paths and nothing else. What the person had staged stays staged.
     git(["commit", "--only", "-m", history ? REGEN_MESSAGE : FRESH_MESSAGE, "--", ...files]);
   } catch (err) {
-    return { committed: false, files, reason: `git could not commit the contract: ${String(err.stderr || err.message).trim().split("\n")[0]}` };
+    // KJC-BUG-0302: the files stay staged, and the reason names the way to commit them.
+    const why = String(err.stderr || err.message).trim().split("\n")[0];
+    const quoted = files.map((f) => "'" + f.replaceAll("'", String.raw`'\''`) + "'").join(" ");
+    return { committed: false, files, reason: `git could not commit the contract: ${why}. Commit these generated files on a branch yourself: git add -- ${quoted} && kj review --staged && git commit -m "chore(kj): el contrato del método, generado por kj"` };
   }
   return { committed: true, files };
 }

package/src/harden/human-act.js

@@ -68,3 +68,41 @@ export function confirmHuman(what, confirm = null) {
   const answer = confirm ? confirm(nonce) : readTty(what, nonce);
   if (answer !== nonce) throw new Error(`${what}: confirmación humana fallida (esperaba "${nonce}") — ADR 0009`);
 }
+
+/**
+ * KJC-TSK-0966 (HUM-C, ADR 0018): the CLOSED catalog of human acts. Every
+ * command that changes who governs, or that destroys work, is listed here and
+ * runs through this module; an architecture test fails on a module of the
+ * catalog that skips it and on a writer of governance files that is not here.
+ * `module` names the file that implements the act; `pending` names the card
+ * that will, for acts the ADR declares and kj does not have yet.
+ */
+export const HUMAN_ACTS = Object.freeze({
+  "supervisor-seal": { label: "harden --commit", module: "src/harden/supervisor-commit.js" },
+  "rules-approve": { label: "kj rules approve", module: "src/commands/rules-approve.js" },
+  "phone-enroll": { label: "kj identity enroll-phone", module: "src/commands/identity.js" },
+  "handoff-run": { label: "kj handoff run", module: null, pending: "KJC-TSK-0968" },
+  "security-level-down": { label: "kj security normal", module: null, pending: "KJC-TSK-0967" },
+});
+
+/**
+ * The one mechanism, by catalog id: `refuse` (layers 1 to 3) and `confirm`
+ * (layer 4), apart because an act may check things in between (the seal looks
+ * at the stage before asking for the nonce). `humanAct` runs both.
+ * @param {keyof typeof HUMAN_ACTS} id
+ */
+export function humanActOf(id) {
+  const act = HUMAN_ACTS[id];
+  if (!act) throw new Error(`"${id}" is not in the catalog of human acts (src/harden/human-act.js, ADR 0018)`);
+  return {
+    label: act.label,
+    refuse: (opts = {}) => refuseAgentSession(act.label, opts),
+    confirm: (confirm = null) => confirmHuman(act.label, confirm),
+  };
+}
+
+export function humanAct(id, { env, tty, ancestry, confirm } = {}) {
+  const act = humanActOf(id);
+  act.refuse({ env, tty, ancestry });
+  act.confirm(confirm);
+}

package/src/harden/phone-sign.js

@@ -164,7 +164,14 @@ export function provenanceSignature({ projectDir, provenance }) {
  * mala / clave ajena / TTL vencido ⇒ {ok:false, reason}.
  * @returns {Promise<{ok: boolean, reason?: string}>}
  */
-export async function requestPhoneSignature({ project, files, kjVersion, logger = console, deps = {} }) {
+// KJC-TSK-0992 (HUM-G): what the page shows beside the sha256, as Firestore values.
+const str = (s) => ({ stringValue: String(s ?? "") });
+const changesValue = (changes) => ({ arrayValue: { values: changes.map((c) => ({ mapValue: { fields: {
+  file: str(c.file), status: str(c.status), added: { integerValue: String(c.added ?? 0) }, removed: { integerValue: String(c.removed ?? 0) },
+  summary: str(c.summary), diff: str(c.diff), truncated: { booleanValue: Boolean(c.truncated) },
+} } })) } });
+
+export async function requestPhoneSignature({ project, files, kjVersion, changes = null, branch = null, origin = null, logger = console, deps = {} }) {
   const fetchFn = deps.fetch ?? fetch;
   const now = deps.now ?? Date.now;
   const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
@@ -184,6 +191,10 @@ export async function requestPhoneSignature({ project, files, kjVersion, logger
       createdAt: { timestampValue: new Date(issuedMs).toISOString() },
       files: { arrayValue: { values: files.map((f) => ({ mapValue: { fields: { file: { stringValue: f.file }, sha256: { stringValue: f.sha256 ?? "" } } } })) } },
       ...(v === 2 ? { v: { integerValue: "2" }, expires_at: { timestampValue: new Date(expiresMs).toISOString() } } : {}),
+      // KJC-TSK-0992: informative, outside the signed payload; the page says so.
+      ...(Array.isArray(changes) ? { changes: changesValue(changes) } : {}),
+      ...(branch ? { branch: str(branch) } : {}),
+      ...(origin ? { origin: str(origin) } : {}),
     },
   };
   const created = await fetchFn(`${relay.url}?documentId=${cid}&key=${relay.apiKey}`, {

package/src/harden/sign-changes.js

@@ -0,0 +1,81 @@
+/**
+ * KJC-TSK-0992 (HUM-G, ADR 0018): what the phone is asked to sign, said.
+ *
+ * The signing page used to show a project name and a list of files with their
+ * sha256: nothing a person can read as "this is what changes". The signature
+ * still covers exactly the sha256 (payload v2); this module describes, file by
+ * file, what kj regenerated so the page can show it: new, modified or deleted,
+ * lines added and removed, a one-line summary and the unified diff, cut to a
+ * size the request can carry and scanned for personal data before it leaves.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { scanText } from "../privacy/scan.js";
+
+export const DIFF_LIMIT_PER_FILE = 12_000;
+export const DIFF_LIMIT_TOTAL = 400_000;
+
+const defaultGit = (projectDir) => (args) => {
+  try {
+    return execFileSync("git", args, { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  } catch (err) {
+    // `git diff --no-index` exits 1 when the files differ: the diff is still on stdout.
+    if (args.includes("--no-index") && typeof err?.stdout === "string") return err.stdout;
+    throw err;
+  }
+};
+
+const inHead = (git, file) => { try { git(["cat-file", "-e", `HEAD:${file}`]); return true; } catch { return false; } };
+
+/** The first comment kj added, which in a generated hook says why it changed. */
+const summaryOf = (diff) => {
+  const comment = diff.split("\n").find((l) => /^\+\s*(#|\/\/)\s*\S/.test(l) && !l.startsWith("+++"));
+  return comment ? comment.replace(/^\+\s*(#|\/\/)\s*/, "").trim().slice(0, 160) : "";
+};
+
+/** A file git does not know yet: the whole file is the addition. */
+const newFile = (git, projectDir, file) => ({
+  raw: git(["diff", "--no-index", "--", "/dev/null", join(projectDir, file)]),
+  added: readFileSync(join(projectDir, file), "utf8").split("\n").filter(Boolean).length,
+  removed: 0,
+});
+/** A tracked file, changed or deleted: the diff against HEAD and its numstat. */
+const trackedFile = (git, file) => {
+  const stat = git(["diff", "--numstat", "HEAD", "--", file]).trim().split("\t");
+  return { raw: git(["diff", "HEAD", "--", file]), added: Number.parseInt(stat[0], 10) || 0, removed: Number.parseInt(stat[1], 10) || 0 };
+};
+
+const MARKER_ROOM = 60;
+/** Cut `text` so the result, marker included, never exceeds `limit`; no room left is one bounded marker. */
+const cut = (text, limit) => {
+  if (text.length <= limit) return { diff: text, truncated: false };
+  const keep = Math.max(0, limit - MARKER_ROOM);
+  return { diff: `${text.slice(0, keep)}\n… [cut: ${text.length - keep} more characters]`.slice(0, limit), truncated: true };
+};
+
+/**
+ * @param {{projectDir: string, files: Array<{file: string, deleted?: boolean}>, gitFn?: Function, scan?: Function}} opts
+ * @returns {Array<{file: string, status: "new"|"modified"|"deleted", added: number, removed: number, summary: string, diff: string, truncated: boolean}>}
+ */
+export function describeSupervisorChanges({ projectDir, files, gitFn = defaultGit(projectDir), scan = scanText }) {
+  let budget = DIFF_LIMIT_TOTAL;
+  return files.map(({ file, deleted }) => {
+    const tracked = inHead(gitFn, file);
+    const present = !deleted && existsSync(join(projectDir, file));
+    let status = "modified";
+    if (deleted || !present) status = "deleted";
+    else if (!tracked) status = "new";
+    const measured = status === "new" ? newFile(gitFn, projectDir, file) : trackedFile(gitFn, file);
+    const { added, removed } = measured;
+    // What leaves the machine is scanned like anything kj publishes: a hit
+    // replaces the diff, never travels.
+    const hits = scan(measured.raw, { source: file }).filter((h) => h.severity === "block");
+    const raw = hits.length > 0 ? `[diff withheld: the privacy scan found ${hits.length} sensitive item(s) in ${file}]` : measured.raw;
+    // Per file and in total: what the request carries never exceeds the limits.
+    const { diff, truncated } = cut(raw, Math.min(DIFF_LIMIT_PER_FILE, Math.max(0, budget)));
+    budget = Math.max(0, budget - diff.length);
+    return { file, status, added, removed, summary: summaryOf(raw), diff, truncated };
+  });
+}

package/src/harden/supervisor-commit.js

@@ -13,8 +13,9 @@ import { basename, join } from "node:path";
 import { recordGateDecision } from "../policy/decisions.js";
 import { readIdentity } from "../identity/store.js";
 import { ensureGateTrackable } from "../review/gate-gitignore.js";
-import { confirmHuman, refuseAgentSession } from "./human-act.js";
+import { humanActOf } from "./human-act.js";
 import { isPhoneEnrolled, requestPhoneSignature } from "./phone-sign.js";
+import { describeSupervisorChanges } from "./sign-changes.js";
 
 export const PROVENANCE_FILE = ".karajan/supervisor-provenance.json";
 const HOOKS_PREFIX = ".karajan/hooks/";
@@ -28,7 +29,6 @@ const HARNESS_PREFIX = ".karajan/harness/";
 
 const sha256 = (abs) => createHash("sha256").update(readFileSync(abs)).digest("hex");
 
-const ACT = "harden --commit";
 
 /** Ficheros de supervisor TRACKEADOS con cambios (staged o no). */
 /**
@@ -73,7 +73,8 @@ export async function commitSupervisorRegeneration({
 }) {
   // El cauce es humano por diseño (ADR 0009): una sesión de agente no lo usa.
   // Capas 1 a 3 (entorno, tty y ascendencia de procesos): src/harden/human-act.js.
-  refuseAgentSession(ACT, { env, tty, ancestry: deps.ancestry ?? {} });
+  const seal = humanActOf("supervisor-seal");
+  seal.refuse({ env, tty, ancestry: deps.ancestry ?? {} });
   const run = gitFn || ((args) => execFileSync("git", args, { cwd: projectDir, encoding: "utf8" }));
   // KJC-BUG-0244 (grebla #958): el commit sellado solo lleva el supervisor, pero
   // un stage ajeno se quedaba en esta rama y el siguiente commit caía aquí con la
@@ -86,7 +87,7 @@ export async function commitSupervisorRegeneration({
   }
   // Capa 4 (test adversarial 6-sep: un huérfano a init con pty falso y
   // prompts a ciegas llegó hasta aquí): nonce aleatorio tecleado de vuelta.
-  confirmHuman(ACT, deps.confirm);
+  seal.confirm(deps.confirm);
   const drift = supervisorDrift({ projectDir, gitFn: run });
   // La provenance describe SIEMPRE el estado COMPLETO del supervisor (cazado
   // en el primer estreno real: un sello parcial pisaba al anterior y dejaba
@@ -125,10 +126,16 @@ export async function commitSupervisorRegeneration({
   const phone = deps.phone ?? { enrolled: isPhoneEnrolled, request: requestPhoneSignature };
   let signatureBlock = null;
   if (phone.enrolled({})) {
+    // KJC-TSK-0992 (HUM-G): the page says what is signed, file by file.
+    let branch = null;
+    try { branch = run(["rev-parse", "--abbrev-ref", "HEAD"]).trim(); } catch { /* unborn HEAD */ }
     const signed = await phone.request({
       project: basename(projectDir),
       files: hashed.map(({ file, sha256: hash }) => ({ file, sha256: hash ?? "" })),
       kjVersion,
+      changes: (deps.describeChanges ?? describeSupervisorChanges)({ projectDir, files: hashed }),
+      branch,
+      origin: `kj harden ${kjVersion}`,
       logger,
     });
     if (!signed.ok) {

package/src/orchestrator/drivers/post-loop.js

@@ -32,6 +32,8 @@ import {
 } from "../../session/mutators.js";
 import { emitProgress, makeEvent } from "../../utils/events.js";
 import { runTesterStage, runSecurityStage, runFinalAuditStage } from "../post-loop-stages.js";
+import { runAcceptanceCoverageStage } from "../stages/acceptance-coverage-stage.js";
+import { criteriaOfCard } from "../../roles/acceptance-coverage-role.js";
 import { invokeSolomon } from "../solomon-escalation.js";
 import { tryCiComment } from "../ci-integration.js";
 import { getIntegration } from "../integrations.js";
@@ -103,6 +105,23 @@ export async function handlePostLoopStages({ config, session, emitter, eventBase
     return { action: "continue" };
   }
 
+  // KJC-TSK-0987 (#1894): with a card, each acceptance criterion is read against
+  // the diff by a different AI before the run is approved. An uncovered one goes
+  // back to the coder; a judge with no verdict stops the approval, never grants it.
+  const coverage = await runAcceptanceCoverageStage({
+    config, logger, emitter, eventBase, trackBudget, iteration: i, task,
+    criteria: criteriaOfCard(session.pg_card), diff: postLoopDiff,
+  });
+  if (coverage.stageResult) stageResults.acceptanceCoverage = coverage.stageResult;
+  if (coverage.action === "retry") {
+    setReviewerFeedback(session, coverage.feedback);
+    await saveSession(session);
+    return { action: "continue" };
+  }
+  if (coverage.action === "fail") {
+    return { action: "return", result: { approved: false, sessionId: session.id, reason: "acceptance_coverage_unavailable", error: coverage.stageResult.summary } };
+  }
+
   return { action: "proceed" };
 }
 

package/src/orchestrator/drivers/run-hu-batch.js

@@ -32,6 +32,9 @@ import { runRepair } from "../repair/repair-runner.js";
 import { writeHistoryRecord } from "./post-loop.js";
 import { setReviewerFeedback } from "../../session/mutators.js";
 import { createHuSnapshot } from "../../git/hu-snapshot.js";
+import { generateDiff } from "../../review/diff-generator.js";
+import { runAcceptanceCoverageStage } from "../stages/acceptance-coverage-stage.js";
+import { criteriaOfCard } from "../../roles/acceptance-coverage-role.js";
 
 /**
  * @param {object} args
@@ -422,12 +425,28 @@ export async function runHuBatch({ ctx, task, askQuestion, emitter, logger }) {
   // the host reads, not only in a warn line of the log.
   const warnings = collectGitWarnings(subPipelineResult.results);
   for (const w of warnings) logger.warn(`git automation: ${w}`);
+  // KJC-TSK-0987 (#1894): the HUs approved themselves against their own stories;
+  // the card's criteria are read against the diff of the whole run before the
+  // run says approved. Uncovered: approved:false with the list, for the host.
+  let coverage = { action: "skip" };
+  if (subPipelineResult.approved) {
+    const diff = await generateDiff({ baseRef: ctx.session.head_at_start || ctx.session.session_start_sha });
+    coverage = await runAcceptanceCoverageStage({
+      config: ctx.config, logger, emitter, eventBase: ctx.eventBase, trackBudget: ctx.trackBudget,
+      iteration: 0, task, criteria: criteriaOfCard(ctx.session.pg_card), diff,
+    });
+    if (coverage.stageResult) ctx.stageResults.acceptanceCoverage = coverage.stageResult;
+  }
+  const uncovered = coverage.action === "retry" ? { reason: "acceptance_criteria_uncovered", uncovered: coverage.stageResult.uncovered } : {};
+  const unavailable = coverage.action === "fail" ? { reason: "acceptance_coverage_unavailable", error: coverage.stageResult.summary } : {};
   const finalResult = {
-    approved: subPipelineResult.approved,
+    approved: subPipelineResult.approved && coverage.action !== "retry" && coverage.action !== "fail",
     sessionId: ctx.session.id,
     huResults: subPipelineResult.results,
     blockedIds: subPipelineResult.blockedIds,
     planId: ctx.session._planRef?.planId || null,
+    ...uncovered,
+    ...unavailable,
     ...(warnings.length > 0 ? { warnings } : {})
   };
   await writeHistoryRecord({ sessionId: ctx.session.id, task, result: finalResult, logger });

package/src/orchestrator/stages/acceptance-coverage-stage.js

@@ -0,0 +1,47 @@
+// KJC-TSK-0987 (issue #1894): the acceptance-coverage stage. With a card whose
+// criteria the run was meant to implement, a different AI reads each criterion
+// against the diff before the run is approved. No card or no criteria: the
+// stage does not run and costs nothing. An unreadable verdict is the judge's
+// failure, never an approval.
+import { AcceptanceCoverageRole } from "../../roles/acceptance-coverage-role.js";
+import { emitProgress, makeEvent } from "../../utils/events.js";
+
+const STAGE = "acceptance-coverage";
+
+/** The feedback the coder gets: the criteria with no evidence in the diff. */
+export const uncoveredFeedback = (uncovered) => {
+  const lines = uncovered.map((c) => "- [" + c.index + "] " + c.text + (c.evidence ? " (judge: " + c.evidence + ")" : ""));
+  return "Acceptance criteria NOT covered by the diff (implement them, with tests that exercise them):\n" + lines.join("\n");
+};
+
+/**
+ * @returns {Promise<{action: "skip"|"ok"|"retry"|"fail", stageResult?: object, feedback?: string}>}
+ */
+export async function runAcceptanceCoverageStage({ config, logger, emitter, eventBase, trackBudget, iteration, task, criteria, diff, RoleClass = AcceptanceCoverageRole }) {
+  if (!Array.isArray(criteria) || criteria.length === 0) return { action: "skip" };
+  logger.setContext?.({ iteration, stage: STAGE });
+  emitProgress(emitter, makeEvent(`${STAGE}:start`, { ...eventBase, stage: STAGE }, {
+    message: `Acceptance coverage: ${criteria.length} criteria against the diff`,
+    detail: { criteria: criteria.length, executorType: "agent" },
+  }));
+  const role = new RoleClass({ config, logger, emitter });
+  await role.init({ task, iteration });
+  const started = Date.now();
+  const output = await role.run({ task, criteria, diff });
+  const provider = output.result?.provider || role.resolveProvider();
+  trackBudget?.({ role: STAGE, provider, model: config?.roles?.[STAGE]?.model || null, result: output, duration_ms: Date.now() - started });
+
+  if (!output.ok) {
+    const stageResult = { ok: false, summary: output.summary || "acceptance-coverage: the judge gave no verdict", provider, error: output.result?.error || null };
+    emitProgress(emitter, makeEvent(`${STAGE}:end`, { ...eventBase, stage: STAGE }, { status: "fail", message: stageResult.summary, detail: stageResult }));
+    return { action: "fail", stageResult };
+  }
+  const { criteria: verdicts, uncovered } = output.result;
+  const stageResult = { ok: uncovered.length === 0, summary: output.summary, provider, criteria: verdicts, uncovered };
+  emitProgress(emitter, makeEvent(`${STAGE}:end`, { ...eventBase, stage: STAGE }, {
+    status: stageResult.ok ? "ok" : "fail", message: output.summary, detail: stageResult,
+  }));
+  if (stageResult.ok) return { action: "ok", stageResult };
+  logger.warn(`${output.summary} — sending them back to the coder`);
+  return { action: "retry", stageResult, feedback: uncoveredFeedback(uncovered) };
+}

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

@@ -8,7 +8,8 @@ import { HuReviewerRole } from "../../roles/hu-reviewer-role.js";
 import { createAgent } from "../../agents/index.js";
 import { addCheckpoint } from "../../session/store.js";
 import { emitProgress, makeEvent } from "../../utils/events.js";
-import { buildDecompositionPrompt, parseDecompositionOutput } from "../../prompts/hu-reviewer.js";
+import { buildDecompositionPrompt, parseDecompositionOutput, uncoveredCriteria } from "../../prompts/hu-reviewer.js";
+import { criteriaOfCard } from "../../roles/acceptance-coverage-role.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";
@@ -20,7 +21,10 @@ import { detectAndApplySplits } from "./hu-reviewer-phases/detect-and-apply-spli
  */
 async function decomposeTaskIntoHUs({ config, logger, emitter, eventBase, session, coderRole, trackBudget }) {
   const provider = config?.roles?.hu_reviewer?.provider || coderRole.provider;
-  const prompt = buildDecompositionPrompt(session.task);
+  // KJC-TSK-0989 (#1894): the card's criteria go into the decomposition, numbered,
+  // so each one lands in an HU; the ones no HU covers are said and kept, never lost.
+  const criteria = criteriaOfCard(session.pg_card);
+  const prompt = buildDecompositionPrompt(session.task, { criteria });
 
   emitProgress(
     emitter,
@@ -70,6 +74,19 @@ async function decomposeTaskIntoHUs({ config, logger, emitter, eventBase, sessio
     logger.info("HU decomposition returned < 2 stories, falling back to single auto-story");
     return null;
   }
+  const uncovered = uncoveredCriteria(stories, criteria);
+  if (uncovered.length > 0) {
+    const last = stories.at(-1);
+    const tags = uncovered.map((c) => `[AC-${c.index}]`);
+    last.acceptanceCriteria.push(...uncovered.map((c, i) => `${tags[i]} ${c.text}`));
+    last.covers.push(...uncovered.map((c) => c.index));
+    logger.warn(`HU decomposition left ${uncovered.length} card criteria with no HU; added to ${last.id}: ${tags.join(" ")}`);
+    emitProgress(emitter, makeEvent("hu-reviewer:criteria-uncovered", { ...eventBase, stage: "hu-reviewer" }, {
+      status: "warn",
+      message: `${uncovered.length} card criteria had no HU and were added to ${last.id}`,
+      detail: { uncovered, addedTo: last.id }
+    }));
+  }
 
   emitProgress(
     emitter,

package/src/prompts/acceptance-coverage.js

@@ -0,0 +1,32 @@
+// KJC-TSK-0987 (issue #1894): the prompt of the acceptance-coverage judge. A run
+// ended approved with none of the card's three criteria implemented; this judge
+// reads each criterion against the diff and says, one by one, whether it is
+// covered and where.
+
+const PREAMBLE = "IMPORTANT: You are running as a Karajan sub-agent. "
+  + "Do NOT use any MCP tools, do NOT mention Karajan. "
+  + "Your job is to judge whether a diff covers a card's acceptance criteria.";
+
+/**
+ * @param {{criteria: string[], diff: string, task?: string, instructions?: string|null}} opts
+ * @returns {string}
+ */
+export function buildAcceptanceCoveragePrompt({ criteria, diff, task = "", instructions = null }) {
+  const list = criteria.map((c, i) => `${i + 1}. ${c}`).join("\n");
+  const body = [
+    "You are the AcceptanceCoverage judge for Karajan Code.",
+    "Input: (a) the acceptance criteria of the task's card, numbered, and (b) the diff the run produced.",
+    "For EACH criterion decide whether the diff implements it. Covered means the behavior the",
+    "criterion describes exists in the diff (code, config or tests that exercise it), not that",
+    "something related was touched. Point to the evidence: file and what it does. A criterion",
+    "with no evidence in the diff is NOT covered, whatever the task description says.",
+    "Return a single valid JSON object and nothing else.",
+    'Schema: {"criteria":[{"index":number,"covered":boolean,"evidence":string}]}',
+    "One entry per criterion, in order, index starting at 1. Do not add or drop criteria.",
+  ].join("\n");
+  const sections = [PREAMBLE];
+  if (instructions) sections.push(instructions);
+  if (task) sections.push(`## Task\n${task}`);
+  sections.push(body, `## Acceptance criteria (${criteria.length})\n${list}`, `## Diff\n${diff || "(empty diff)"}`);
+  return sections.join("\n\n");
+}

package/src/prompts/hu-reviewer.js

@@ -136,7 +136,7 @@ export function normalizeAcceptanceCriteria(criteria) {
  * @param {string} task - The complex task description to decompose.
  * @returns {string} The assembled decomposition prompt.
  */
-export function buildDecompositionPrompt(task) {
+export function buildDecompositionPrompt(task, { criteria = [] } = {}) {
   const sections = [SUBAGENT_PREAMBLE];
 
   sections.push("## Task Decomposition");
@@ -147,20 +147,41 @@ export function buildDecompositionPrompt(task) {
 
   sections.push(`## Task to Decompose\n${task}`);
 
+  // KJC-TSK-0989 (#1894): the card's criteria are the contract; each one must
+  // land in an HU, by number, or the run implements stories of its own invention.
+  if (criteria.length > 0) {
+    const numbered = criteria.map((c, i) => `${i + 1}. ${c}`).join("\n");
+    sections.push(`## Acceptance criteria of the card (the contract)\n${numbered}`);
+  }
+
   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]}]}`,
+    `JSON schema: {"stories":[{"id":string,"title":string,"role":string,"goal":string,"benefit":string,"acceptanceCriteria":[string],"dependsOn":[string],"covers":[number]}]}`,
     "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",
-    "- Order stories so that dependencies are respected (a story should only depend on stories with lower ids)"
+    "- 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",
+    ] : ["- covers is an empty array"])
   );
 
   return sections.join("\n\n");
 }
 
+/**
+ * KJC-TSK-0989: the card's criteria no HU covers, by number and text.
+ * @param {Array<{covers?: number[]}>} stories
+ * @param {string[]} criteria
+ * @returns {Array<{index: number, text: string}>}
+ */
+export function uncoveredCriteria(stories, criteria) {
+  const covered = new Set(stories.flatMap((s) => s.covers ?? []));
+  return criteria.map((text, i) => ({ index: i + 1, text })).filter((c) => !covered.has(c.index));
+}
+
 /**
  * Parse the output from a decomposition prompt.
  * @param {string} raw - Raw text output from the agent.
@@ -179,7 +200,8 @@ export function parseDecompositionOutput(raw) {
       goal: s.goal || s.title,
       benefit: s.benefit || "",
       acceptanceCriteria: Array.isArray(s.acceptanceCriteria) ? s.acceptanceCriteria : [],
-      dependsOn: Array.isArray(s.dependsOn) ? s.dependsOn : []
+      dependsOn: Array.isArray(s.dependsOn) ? s.dependsOn : [],
+      covers: Array.isArray(s.covers) ? s.covers.map(Number).filter(Number.isInteger) : []
     }));
 
   return stories.length > 0 ? stories : null;

package/src/roles/acceptance-coverage-role.js

@@ -0,0 +1,78 @@
+// KJC-TSK-0987 (issue #1894): AcceptanceCoverageRole, the judge that reads each
+// acceptance criterion of the card against the diff before the run is approved.
+// Judged by a different AI than the coder (the reviewer's provider by default).
+// Role + helpers ship here; the stage wires it (same PR), the loops next.
+
+import { AgentRole } from "./agent-role.js";
+import { buildAcceptanceCoveragePrompt } from "../prompts/acceptance-coverage.js";
+import { extractFirstJson } from "../utils/json-extract.js";
+
+/**
+ * The card's acceptance criteria as plain sentences, one per criterion.
+ * Structured Given/When/Then first; else the free text, one per line or bullet.
+ * @param {object|null} card
+ * @returns {string[]}
+ */
+export function criteriaOfCard(card) {
+  const structured = Array.isArray(card?.acceptanceCriteriaStructured) ? card.acceptanceCriteriaStructured : [];
+  const fromStructured = structured
+    .map((ac) => (ac?.given && ac?.when && ac?.then ? `Given ${ac.given}, when ${ac.when}, then ${ac.then}` : String(ac?.raw || "").trim()))
+    .filter(Boolean);
+  if (fromStructured.length > 0) return fromStructured;
+  return String(card?.acceptanceCriteria || "")
+    .split("\n")
+    .map((line) => line.replace(/^\s*(?:[-*•]|\d+[.)])\s*/, "").trim())
+    .filter(Boolean);
+}
+
+const normalizeVerdicts = (parsed, criteria) => criteria.map((text, i) => {
+  const v = Array.isArray(parsed?.criteria) ? parsed.criteria.find((c) => Number(c?.index) === i + 1) : null;
+  return {
+    index: i + 1,
+    text,
+    // No entry for a criterion is no evidence for it: not covered, never assumed.
+    covered: v ? Boolean(v.covered) : false,
+    evidence: typeof v?.evidence === "string" ? v.evidence.trim() : "",
+  };
+});
+
+export class AcceptanceCoverageRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "acceptance-coverage" });
+  }
+
+  // A different AI than the coder: the reviewer's, unless the role has its own.
+  resolveProvider() {
+    return this.config?.roles?.["acceptance-coverage"]?.provider
+      || this.config?.roles?.reviewer?.provider
+      || this.config?.reviewer
+      || "codex";
+  }
+
+  extractInput(input) {
+    return { ...super.extractInput(input), criteria: Array.isArray(input?.criteria) ? input.criteria : [], diff: String(input?.diff || "") };
+  }
+
+  async buildPrompt({ task, criteria, diff }) {
+    this._criteria = criteria;
+    return { prompt: buildAcceptanceCoveragePrompt({ criteria, diff, task, instructions: this.instructions }) };
+  }
+
+  parseOutput(raw) { return extractFirstJson(raw); }
+
+  // A verdict with no `criteria` array is not a verdict: the reviewer's failure.
+  isSuccessful(parsed) { return Array.isArray(parsed?.criteria); }
+
+  buildSuccessResult(parsed, provider) {
+    const criteria = normalizeVerdicts(parsed, this._criteria || []);
+    const uncovered = criteria.filter((c) => !c.covered);
+    return { criteria, uncovered, provider, error: Array.isArray(parsed?.criteria) ? undefined : "no criteria array in the verdict" };
+  }
+
+  buildSummary(parsed) {
+    if (!Array.isArray(parsed?.criteria)) return "acceptance-coverage: unreadable verdict (no criteria array)";
+    const total = (this._criteria || []).length;
+    const uncovered = normalizeVerdicts(parsed, this._criteria || []).filter((c) => !c.covered).length;
+    return uncovered === 0 ? `acceptance-coverage: ${total}/${total} criteria covered` : `acceptance-coverage: ${uncovered} of ${total} criteria NOT covered`;
+  }
+}

package/src/utils/update-check.js

@@ -3,8 +3,22 @@ import { readFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { isSea } from "node:sea";
+import { fileURLToPath } from "node:url";
 import { getKarajanHome } from "./paths.js";
 
+// KJC-BUG-0301: `kj update` on a kj linked from a source tree (npm link) said
+// "Updating 4.44.0 → 4.43.0", installed the registry's older version globally
+// and replaced the development link. Two facts decide now, before any install.
+/** Whether this kj runs from a source tree (npm link), not from a node_modules install. */
+export const isSourceTree = (selfPath = fileURLToPath(import.meta.url)) => !selfPath.split(path.sep).includes("node_modules");
+const numeric = (v) => String(v).split(/[.-]/, 3).map((n) => Number.parseInt(n, 10) || 0);
+/** Whether version `a` is strictly newer than `b` (major.minor.patch; a prerelease tag is ignored). */
+export const isNewerVersion = (a, b) => {
+  const [x, y] = [numeric(a), numeric(b)];
+  for (let i = 0; i < 3; i++) if (x[i] !== y[i]) return x[i] > y[i];
+  return false;
+};
+
 const CACHE_FILE = "update-check.json";
 // KJC-TSK-0690: 6h — kj can ship several releases a day; a session should
 // not work a full day blind. KJ_NO_UPDATE_CHECK=1 opts out (CI).
@@ -183,7 +197,7 @@ export async function printUpdateNotice(currentVersion) {
  * @param {typeof fetch} [opts.fetchFn] - injectable fetch (registry lookup + installer download)
  * @returns {Promise<{ ok: boolean, alreadyLatest?: boolean, latest?: string, manual?: boolean }>}
  */
-export async function performSelfUpdate({ currentVersion, exec, logger = console, channel, fetchFn = fetch } = {}) {
+export async function performSelfUpdate({ currentVersion, exec, logger = console, channel, fetchFn = fetch, sourceTree = isSourceTree() } = {}) {
   const run = exec || (async (cmd, args) => (await import("execa")).execa(cmd, args));
   const ch = channel || detectInstallChannel();
   logger.log(`Current version: ${currentVersion}`);
@@ -207,6 +221,15 @@ export async function performSelfUpdate({ currentVersion, exec, logger = console
     logger.log(`Already on the latest version (${currentVersion}).`);
     return { ok: true, alreadyLatest: true, latest };
   }
+  // KJC-BUG-0301: never a downgrade, and never over a development link.
+  if (isNewerVersion(currentVersion, latest)) {
+    logger.log(`This kj (${currentVersion}) is newer than the registry's latest (${latest}): nothing to update.`);
+    return { ok: true, newerThanRegistry: true, latest };
+  }
+  if (ch === "npm" && sourceTree) {
+    logger.log(`Update available: ${currentVersion} → ${latest}, but this kj runs from a source tree (npm link) and kj update will not replace it. Pull or rebuild that tree, or unlink it first: npm unlink -g ${packageName()}`);
+    return { ok: true, latest, manual: true };
+  }
 
   if (ch === "sea" && process.platform === "win32") {
     // Executing a downloaded .ps1 from inside the binary is not supported