karajan-code 4.45.0 → 4.46.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.45.0",
+  "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/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/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/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;