karajan-code 4.45.0 → 4.47.0

package/package.json

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

package/src/cli/advanced-commands.js

@@ -35,7 +35,7 @@ export const ADVANCED_GROUPS = [
   { title: "Análisis pre-run", commands: ["discover", "triage", "researcher", "architect", "onboard", "brief"] },
   { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch"] },
   { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy", "release", "policy", "rules", "claims", "steward", "pr-size"] },
-  { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby", "sentinel", "identity"] },
+  { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby", "sentinel", "identity", "security"] },
   { title: "Infra / setup", commands: ["install-tools", "ollama", "skills", "roles", "agents", "env"] },
   { title: "Mantenimiento", commands: ["clean", "sync", "telemetry", "report-issue"] },
 ];

package/src/cli/register-meta.js

@@ -8,6 +8,7 @@ import { goCommand } from "../commands/go.js";
 import { bootstrapCommand } from "../commands/bootstrap.js";
 import { PENDING_EXIT_CODE } from "../utils/pending-user-action.js";
 import { identityCommand } from "../commands/identity.js";
+import { securityCommand } from "../commands/security.js";
 import { policyCommand } from "../commands/policy.js";
 import { claimsCommand, claimsGateCommand } from "../commands/claims.js";
 import { stewardSweepCommand } from "../commands/steward.js";
@@ -163,12 +164,35 @@ export function registerMeta(program, { pkgVersion }) {
     .command("enroll-phone")
     .description("Enroll the phone's PUBLIC signing key (base64 of the raw 32-byte ed25519 key) for the supervisor seal")
     .argument("<publicKeyBase64>", "raw ed25519 public key, base64 (shown by the phone app)")
+    .option("--label <name>", "A name for this phone in the roster")
+    .option("--recovery <code>", "Replace a lost phone with the recovery code shown at enrollment (spent on use, a new one is issued)")
+    .option("--replaces <publicKeyBase64>", "With --recovery: the lost phone to revoke (default: the one enrolled on this machine)")
     .action(async (publicKeyBase64, flags) => {
       await withConfig(pkgVersion, "identity-enroll-phone", flags, async ({ config }) => {
-        process.exitCode = await identityCommand({ action: "enroll-phone", config, flags: { ...flags, publicKeyBase64 } });
+        process.exitCode = await identityCommand({ action: "enroll-phone", config, kjVersion: pkgVersion, flags: { ...flags, publicKeyBase64 } });
       });
     });
 
+  // KJC-TSK-0995 (HUM-D, ADR 0018): the project's security level; going down is a signed act.
+  const securityCmd = program
+    .command("security")
+    .description("Security level of this project: max (every catalog act signed by the phone) or normal (four layers, lesser guarantee)");
+  const SECURITY_ACTIONS = {
+    show: "The level in force, where it comes from and whether a phone is enrolled (exit 2 on a record that cannot be trusted)",
+    max: "Raise to max: no signature needed",
+    normal: "Lower to normal: a human act signed by the enrolled phone (refused without one)",
+  };
+  for (const [action, description] of Object.entries(SECURITY_ACTIONS)) {
+    securityCmd
+      .command(action, action === "show" ? { isDefault: true } : {})
+      .description(description)
+      .action(async (flags) => {
+        await withConfig(pkgVersion, `security-${action}`, flags, async ({ config }) => {
+          process.exitCode = await securityCommand({ action, config, kjVersion: pkgVersion, flags });
+        });
+      });
+  }
+
   // KJC-TSK-0986 (HUM-F): the invitation to enroll the phone, once per version.
   identityCmd
     .command("phone-invite")
@@ -412,7 +436,7 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--file <path>", "The proposal", PROPOSAL_FILE)
     .action(async (flags) => {
       await withConfig(pkgVersion, "rules-approve", flags, async ({ config }) => {
-        const res = await rulesApprove({ projectDir: config?.projectDir || process.cwd(), file: flags.file });
+        const res = await rulesApprove({ projectDir: config?.projectDir || process.cwd(), file: flags.file, kjVersion: pkgVersion });
         for (const line of res.lines) console.log(line);
         process.exitCode = res.code;
       });

package/src/commands/identity.js

@@ -8,14 +8,19 @@
  *           no session and no flags → exit 1.
  */
 
-import { addSigner, enrollPhone } from "../harden/phone-sign.js";
+import { createHash } from "node:crypto";
+
+import { signAct } from "../harden/act-sign.js";
+import { enrollPhone, isPhoneEnrolled, readEnrolledKey, readEnrolledKeys, validatePhonePublicKey } from "../harden/phone-sign.js";
+import { admitSigner, redeemRecoveryCode } from "../harden/roster.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";
 import { createWizard, isTTY } from "../utils/wizard.js";
 
-export async function identityCommand({ action = "show", config, flags = {}, deps = {} }) {
+export async function identityCommand({ action = "show", config, kjVersion = "unknown", flags = {}, deps = {} }) {
   const projectDir = config?.projectDir || process.cwd();
   const log = deps.log || console.log;
   const tty = deps.isTTY || isTTY;
@@ -27,16 +32,43 @@ 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") {
+    let recoveryCode;
     try {
-      // 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 });
-      enrollPhone(flags.publicKeyBase64, { home: deps.home });
+      // 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-0998 (HUM-D, ADR 0018): a phone of the roster signs the key that
+      // enters; the FIRST one has nobody to sign it (bootstrap) and runs on the four layers.
+      const key = validatePhonePublicKey(flags.publicKeyBase64);
+      const signers = ".karajan/supervisor-signers.json";
+      // KJC-TSK-0999 (HUM-B2, ADR 0018): a lost phone is replaced with the recovery
+      // code, never by reinstalling: its proof is the admission and the lost phone
+      // is not asked to sign. The code is checked BEFORE anything else happens.
+      const recovered = flags.recovery ? redeemRecoveryCode(flags.recovery, { projectDir }) : null;
+      // The lost phone is REVOKED by the same code: the one named with --replaces, or the one this machine had enrolled.
+      const lost = recovered ? (flags.replaces ?? (isPhoneEnrolled({ home: deps.home }) ? readEnrolledKey({ home: deps.home }) : null)) : null;
+      if (recovered && !lost) throw new Error("di qué móvil se pierde: --replaces <su clave pública> (esta máquina no tiene ninguno enrolado)");
+      if (recovered) log(`recuperación con el código: el móvil perdido (${lost.slice(0, 8)}…) queda revocado y no firma; el código gastado es la admisión del nuevo`);
+      const { signature } = await signAct("phone-enroll", {
+        projectDir, home: deps.home, kjVersion, logger: { warn: log, info: log },
+        deps: recovered ? { ...deps, phone: { enrolled: () => false } } : deps,
+        bootstrap: recovered !== null || readEnrolledKeys({ projectDir, home: deps.home }).size === 0,
+        files: [{ file: signers, sha256: createHash("sha256").update(key).digest("hex") }],
+        changes: [{ file: signers, status: "modified", added: 1, removed: 0, summary: `Entra la clave ${flags.label ?? "(sin etiqueta)"}`, diff: `+ ${key}`, truncated: false }],
+      });
+      // KJC-TSK-0831 (ADR 0010): the versioned roster, now with the admission CI
+      // verifies (HUM-B); the legacy key in ~/.karajan stays.
+      recoveryCode = admitSigner({ projectDir, publicKey: key, label: flags.label ?? null, admission: recovered ?? signature, replaces: lost }).recoveryCode;
+      enrollPhone(key, { home: deps.home });
     } catch (err) {
       log(`kj identity enroll-phone: ${err.message}`);
       return 1;
     }
     log("Móvil enrolado: la clave pública se añadió al padrón .karajan/supervisor-signers.json (commítealo) y a ~/.karajan/supervisor-phone.json. Sellar el supervisor pedirá la firma de un móvil del padrón.");
+    if (recoveryCode) {
+      log(`\nCÓDIGO DE RECUPERACIÓN, se enseña UNA sola vez. Guárdalo fuera de esta máquina:\n\n    ${recoveryCode}\n`);
+      log("Sirve para enrolar un móvil nuevo si pierdes este: kj identity enroll-phone <clave nueva> --recovery <código>. Es de un solo uso: al usarlo se emite otro. Sin móvil y sin código no hay recuperación: el padrón se rehace por fuera de CI, a la vista de todos (ADR 0018).");
+    }
     return 0;
   }
 

package/src/commands/init.js

@@ -25,6 +25,7 @@ import { detectQmd } from "../utils/qmd-detect.js";
 import { installQmd } from "../utils/qmd-install.js";
 import { registerQmdCollections } from "../utils/qmd-collection.js";
 import { isGitRepo } from "../harden/harden-engine.js";
+import { isPhoneEnrolled } from "../harden/phone-sign.js";
 import { hardenCommand } from "./harden.js";
 import { contractChanges } from "../environment/contract-commit.js";
 import { detectProjectStack } from "../utils/stack-detect.js";
@@ -281,6 +282,27 @@ async function askBoardSecurity(wizard, config, logger) {
   logger.info(`  -> HU Board port: ${config.hu_board.port}`);
 }
 
+/**
+ * KJC-TSK-0997 (HUM-D4, ADR 0018): the level is max by default, so the dangerous
+ * acts are signed from the phone and refused without one. Enrolling is a human
+ * act of the catalog, never done from a wizard: init says what the phone
+ * protects, how to enroll it and how one goes on without it.
+ */
+export function tellPhoneStep(logger, { enrolled = isPhoneEnrolled() } = {}) {
+  logger.info("Security: the phone");
+  if (enrolled) {
+    logger.info("  A phone is enrolled on this machine. The level is max by default: sealing the supervisor, approving rules, enrolling");
+    logger.info("  another phone and lowering the level are signed from it. `kj security show` tells the level of this project.");
+    return;
+  }
+  logger.info("  No phone is enrolled. The level is max by default: sealing the supervisor (kj harden --commit), approving rules");
+  logger.info("  and enrolling another phone are signed from your phone over the exact bytes, and refused until one is enrolled.");
+  logger.info("  1. Open https://karajancode.com/sign on the phone: it creates a key pair and shows the PUBLIC key (the private one never leaves it).");
+  logger.info("  2. From YOUR terminal, never from an agent session: kj identity enroll-phone <public key> --label <name>");
+  logger.info("  3. Keep the recovery code it prints, off this machine: it replaces a lost phone (--recovery <code>).");
+  logger.info("  Prefer the four layers alone? kj security normal lowers the level, signed from the phone too (ADR 0018).");
+}
+
 /**
  * Explicit, opt-in telemetry consent. We do NOT inherit a "Karajan-installed
  * users want to help" assumption — silence and missing config keys both mean
@@ -395,6 +417,8 @@ async function runWizard(config, logger) {
     await askTelemetry(wizard, config, logger);
 
     logger.info("");
+    tellPhoneStep(logger);
+    logger.info("");
   } finally {
     wizard.close();
   }

package/src/commands/policy.js

@@ -13,6 +13,7 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { checkStagedDiff, evalToolCall, loadPolicy } from "../policy/engine.js";
 import { liftSealedSupervisorViolations } from "../policy/supervisor-verify.js";
+import { rosterViolation } from "../policy/roster-check.js";
 import { loadExceptionRecords, loadGlobalExceptionRecords, loadStandingExceptions, recordPolicyException } from "../policy/exceptions.js";
 import { buildPolicyReport } from "../policy/report.js";
 import { budgetedNet } from "../review/loc-budget.js";
@@ -23,10 +24,11 @@ import { verifyDecisionChain } from "@karajan-family/governance";
 
 const execFileAsync = promisify(execFile);
 
+const gitRunner = (projectDir, gitFn) =>
+  gitFn || (async (args) => (await execFileAsync("git", args, { cwd: projectDir, maxBuffer: 16 * 1024 * 1024 })).stdout);
+
 async function stagedFacts(projectDir, gitFn, range = null) {
-  const run =
-    gitFn ||
-    (async (args) => (await execFileAsync("git", args, { cwd: projectDir, maxBuffer: 16 * 1024 * 1024 })).stdout);
+  const run = gitRunner(projectDir, gitFn);
   // PL-C (KJC-TSK-0735): en CI no hay staged — con --range se evalúa
   // base...head, el MISMO motor sobre el diff del PR (tier C del ADR 0001).
   const base = range ? ["diff", range] : ["diff", "--cached"];
@@ -247,6 +249,10 @@ export async function policyCommand({ action, config = {}, flags = {}, logger =
     if (sup.note) logger.info?.(`ℓ policy: ${sup.note}`);
     violations = sup.violations;
   }
+  // KJC-TSK-1000 (HUM-B3, ADR 0018): a change of the roster of phones is judged
+  // against the base's roster: admitted by a present phone or by the recovery code.
+  const roster = await rosterViolation({ projectDir, files: facts.files, range: flags.range || null, run: gitRunner(projectDir, deps.gitFn) });
+  if (roster) violations = [...violations, roster];
   const hard = flags.strict ? violations.filter((v) => v.enforcement === "deny") : [];
   if (flags.json) {
     logger.info?.(JSON.stringify({ mode: flags.strict ? "strict" : "warn", violations }));

package/src/commands/rules-approve.js

@@ -7,25 +7,30 @@
  * The proposal is read ONCE: what is checked, what is shown and what is
  * installed are the same rules, whatever happens to the file meanwhile.
  */
+import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 
 import yaml from "js-yaml";
 
-import { confirmHuman, refuseAgentSession } from "../harden/human-act.js";
+import { signAct } from "../harden/act-sign.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,
  *   deps?: {confirm?: Function, ancestry?: object}, log?: (line: string) => void}} opts
  * @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 sha256 = (text) => createHash("sha256").update(text).digest("hex");
+const lines = (text) => (text ? text.split("\n").length - 1 : 0);
+
+export async function rulesApprove({ projectDir, file = PROPOSAL_FILE, home, kjVersion = "unknown", env, tty, deps = {}, log = console.log }) {
+  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,13 +53,25 @@ 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))]];
-  for (const [name, part] of parts) {
+  const dumps = parts.map(([name, part]) => [name, part.length ? yaml.dump({ version: 1, rules: part }, { lineWidth: -1 }) : null]);
+  // KJC-TSK-0998 (HUM-D, ADR 0018): the phone signs the exact YAML that lands, and
+  // sees the rules as the approval view showed them. At max with no phone: no approval.
+  const before = (name) => { try { return fs.readFileSync(path.join(projectDir, name), "utf8"); } catch { return null; } };
+  await signAct("rules-approve", {
+    projectDir, home, kjVersion, deps, logger: { warn: log, info: log },
+    files: dumps.map(([name, text]) => ({ file: name, sha256: text ? sha256(text) : "" })),
+    changes: dumps.map(([name, text]) => ({
+      file: name, status: text ? (before(name) ? "modified" : "new") : "deleted", added: lines(text), removed: lines(before(name)),
+      summary: `${parts.find(([n]) => n === name)[1].length} rule(s)`, diff: view.join("\n"), truncated: false,
+    })),
+  });
+  for (const [name, text] of dumps) {
     const target = path.join(projectDir, name);
-    if (part.length) fs.writeFileSync(target, yaml.dump({ version: 1, rules: part }, { lineWidth: -1 }));
+    if (text) fs.writeFileSync(target, text);
     else fs.rmSync(target, { force: true }); // no rule left for this file: none stays behind
   }
   fs.rmSync(proposal, { force: true });

package/src/commands/security.js

@@ -0,0 +1,45 @@
+/**
+ * kj security show|normal|max (KJC-TSK-0995, HUM-D, ADR 0018): the project's
+ * security level. `show` says the level in force and where it comes from;
+ * `max` is free; `normal` is the catalog act security-level-down, signed by
+ * the phone (src/harden/security-level.js).
+ */
+import { isPhoneEnrolled } from "../harden/phone-sign.js";
+import { lowerSecurityLevel, raiseSecurityLevel, readSecurityLevel, SECURITY_LEVEL_FILE } from "../harden/security-level.js";
+
+const MEANING = {
+  max: "máxima: todo acto del catálogo (sello, reglas, enrolar un móvil) se firma con el móvil",
+  normal: "normal: las cuatro capas de ADR 0009 y un código tecleado; la garantía es menor",
+};
+const sourceLine = (level) => {
+  if (level.source === "default") return "por defecto (sin registro)";
+  if (level.source === "invalid") return `REGISTRO NO FIABLE: ${level.reason}`;
+  return `registrado en ${SECURITY_LEVEL_FILE} desde ${level.since ?? "?"}${level.signer ? ", firmado por un móvil del padrón" : ""}`;
+};
+
+/** @returns {Promise<0|1|2>} 2 when the record cannot be trusted */
+export async function securityCommand({ action = "show", config, kjVersion, flags = {}, deps = {}, log = console.log }) {
+  const projectDir = config?.projectDir || process.cwd();
+  const home = deps.home;
+  if (action === "max") {
+    const res = raiseSecurityLevel({ projectDir, home });
+    log(res.changed ? `kj security: nivel máxima registrado en ${SECURITY_LEVEL_FILE} (commítealo: viaja con el repo)` : "kj security: el nivel ya es máxima");
+    return 0;
+  }
+  if (action === "normal") {
+    try {
+      const res = await lowerSecurityLevel({ projectDir, home, kjVersion, env: deps.env ?? process.env, tty: deps.ttyHuman ?? process.stdout.isTTY, deps, logger: deps.logger ?? console });
+      log(res.changed ? `kj security: nivel normal firmado y registrado en ${SECURITY_LEVEL_FILE} (commítealo). Desde ahora kj avisará en cada acto de que la garantía es menor; kj security max lo sube.` : "kj security: el nivel ya es normal");
+      return 0;
+    } catch (err) {
+      log(`kj security normal: ${err.message}`);
+      return 1;
+    }
+  }
+  const level = readSecurityLevel({ projectDir, home });
+  log(`nivel   ${MEANING[level.level]}`);
+  log(`origen  ${sourceLine(level)}`);
+  log(`móvil   ${isPhoneEnrolled({ home }) ? "enrolado" : "no enrolado (kj identity enroll-phone <clave pública de la app>)"}`);
+  if (flags.json) log(JSON.stringify(level));
+  return level.source === "invalid" ? 2 : 0;
+}

package/src/environment/contract-commit.js

@@ -30,6 +30,8 @@ export const CONTRACT_PATHS = [
   ".karajan/rules.yml",
   ".karajan/policy-anchor.json",
   ".karajan/supervisor-signers.json",
+  // KJC-TSK-0995 (HUM-D, ADR 0018): the security level the whole team inherits.
+  ".karajan/security-level.json",
 ];
 
 const FRESH_MESSAGE = "chore(bootstrap): el contrato del método, para que quien clone lo herede";

package/src/harden/act-sign.js

@@ -0,0 +1,69 @@
+/**
+ * KJC-TSK-0996 (HUM-D, ADR 0018): the security level applied to every act of
+ * the catalog, in one place. With a phone enrolled the act is signed by it over
+ * the exact bytes of what it does, and the request says what is done, why the
+ * signature is asked and what would happen if another did it. Without a phone:
+ * at `max` the act is refused and told how to enroll (never a typed code
+ * instead), except the first enrollment, which nobody could sign; at `normal`
+ * the four layers stand and the act says the guarantee is lesser.
+ */
+import { basename } from "node:path";
+
+import { humanActOf } from "./human-act.js";
+import { PHONE_INVITE } from "./phone-invite.js";
+import { isPhoneEnrolled, requestPhoneSignature } from "./phone-sign.js";
+import { readSecurityLevel } from "./security-level.js";
+
+const EXPLAIN = {
+  "supervisor-seal": [
+    "Se sella el supervisor regenerado por kj harden: los hooks y guardias listados quedan como los bytes que firmas.",
+    "Sin tu firma el CI no acepta la procedencia: nadie, ni el agente, da por bueno un supervisor que tú no viste.",
+    "Quien altere un hook sin este sello deja la procedencia incompleta y CI lo rechaza.",
+  ],
+  "rules-approve": [
+    "Se instalan las reglas compiladas de tus MD como gates del proyecto (.karajan/rules.yml).",
+    "El agente propone cómo se compilan las reglas que le vigilan; solo tú las apruebas.",
+    "Reglas instaladas sin tu firma no son tuyas: el agente podría aflojar las que le frenan.",
+  ],
+  "phone-enroll": [
+    "Entra una clave pública nueva en el padrón de móviles que pueden firmar en este proyecto.",
+    "Quien está en el padrón sella, aprueba reglas y baja el nivel: solo un móvil ya enrolado admite a otro.",
+    "Una clave añadida sin la firma de un móvil del padrón daría a otro tu poder de firma.",
+  ],
+};
+
+/** What the phone shows beside the files: what, why, and if another did it. */
+export function explainAct(id) {
+  const [what, why, other] = EXPLAIN[id] ?? [];
+  if (!what) throw new Error(`"${id}" has no explanation for the phone (src/harden/act-sign.js, ADR 0018)`);
+  return `Qué se va a hacer: ${what}\nPor qué se pide tu firma: ${why}\nSi lo hiciera otro: ${other}`;
+}
+
+/**
+ * @param {string} id catalog id (src/harden/human-act.js)
+ * @param {{projectDir: string, home?: string, kjVersion: string, files: {file: string, sha256: string}[],
+ *   changes?: object[], branch?: string|null, bootstrap?: boolean, logger?: object, deps?: {phone?: object}}} opts
+ *   `bootstrap`: the act may run with no phone enrolled even at max (the first enrollment).
+ * @returns {Promise<{level: object, signature: object|null}>} the block to record, or null when no phone signed
+ */
+export async function signAct(id, { projectDir, home, kjVersion, files, changes = [], branch = null, bootstrap = false, logger = console, deps = {} }) {
+  const act = humanActOf(id);
+  const level = readSecurityLevel({ projectDir, home });
+  if (level.source === "invalid") logger.warn?.(`${act.label}: ${level.reason}`);
+  const phone = deps.phone ?? { enrolled: isPhoneEnrolled, request: requestPhoneSignature };
+  if (!phone.enrolled({ home })) {
+    if (level.level === "max" && !bootstrap) {
+      throw new Error(`${act.label}: con seguridad máxima este acto se firma con el móvil y no hay ninguno enrolado. ${PHONE_INVITE}`);
+    }
+    logger.warn?.(`${act.label}: sin móvil enrolado solo valen las cuatro capas y la garantía es menor (ADR 0018). ${PHONE_INVITE}`);
+    return { level, signature: null };
+  }
+  if (level.level === "normal") logger.warn?.(`${act.label}: seguridad normal, la garantía es menor que con la máxima; kj security max la sube`);
+  const signed = await phone.request({
+    project: basename(projectDir), files, kjVersion, changes, branch, why: explainAct(id),
+    origin: `${act.label} (kj ${kjVersion})`, logger, deps: { projectDir, home },
+  });
+  if (!signed.ok) throw new Error(`${act.label}: firma del móvil rechazada (${signed.reason}); con móvil enrolado el acto exige su firma (ADR 0018)`);
+  const signature = signed.challenge && signed.signer && signed.signature ? { ...signed.challenge, signer: signed.signer, signature: signed.signature } : null;
+  return { level, signature };
+}

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: "src/harden/security-level.js" },
+});
+
+/**
+ * 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

@@ -74,7 +74,8 @@ export const readEnrolledKey = ({ home } = {}) =>
 export function readSigners({ projectDir } = {}) {
   try {
     const doc = JSON.parse(readFileSync(signersPath(projectDir), "utf8"));
-    return Array.isArray(doc?.signers) ? doc.signers.map((s) => s.publicKey).filter(Boolean) : [];
+    // KJC-TSK-0999 (HUM-B2): a phone replaced with the recovery code is revoked and signs no more.
+    return Array.isArray(doc?.signers) ? doc.signers.filter((s) => !s?.revoked).map((s) => s.publicKey).filter(Boolean) : [];
   } catch {
     return [];
   }
@@ -142,20 +143,29 @@ export function verifyPhoneSignature({ payload, signature, publicKey }) {
 export function provenanceSignature({ projectDir, provenance }) {
   const roster = readSigners({ projectDir });
   if (roster.length === 0) return { required: false, ok: true };
-  const fail = (reason) => ({ required: true, ok: false, reason });
-  const sig = provenance?.signature;
-  if (typeof sig?.signature !== "string" || typeof sig?.signer !== "string") return fail("el padrón tiene firmantes y la procedencia no lleva firma");
-  if (!roster.includes(sig.signer)) return fail("la clave que firma la procedencia no está en el padrón");
   // The files as the phone signed them: {file, sha256}, a deletion with no hash.
   // A provenance is read from the project: a malformed one is rejected, it does not crash.
-  const entries = Array.isArray(provenance.files) ? provenance.files : [];
-  if (entries.some((entry) => typeof entry?.file !== "string")) return fail("la procedencia declara ficheros mal formados");
+  const entries = Array.isArray(provenance?.files) ? provenance.files : [];
+  if (entries.some((entry) => typeof entry?.file !== "string")) return { required: true, ok: false, reason: "la procedencia declara ficheros mal formados" };
   const files = entries.map(({ file, sha256 }) => ({ file, sha256: sha256 ?? "" }));
+  const check = verifySignedFiles({ sig: provenance?.signature, files, keys: new Set(roster) });
+  return check.ok ? { required: true, ok: true } : { required: true, ok: false, reason: `el padrón tiene firmantes y la procedencia ${check.reason}` };
+}
+
+/**
+ * KJC-TSK-0967 (HUM-D): a signature block (challenge + signer + signature, as
+ * the seal and the security level record it) over `files`, against `keys`.
+ * The reason reads after a subject: "la procedencia no lleva firma".
+ * @returns {{ok: boolean, reason?: string}}
+ */
+export function verifySignedFiles({ sig, files, keys }) {
+  if (typeof sig?.signature !== "string" || typeof sig?.signer !== "string") return { ok: false, reason: "no lleva firma" };
+  if (!keys.has(sig.signer)) return { ok: false, reason: "está firmada por una clave que no está en el padrón" };
   let good = false;
   try {
     good = verifyPhoneSignature({ payload: canonicalPayload({ ...sig, files }), signature: sig.signature, publicKey: sig.signer });
   } catch { /* a malformed key or signature is a signature that does not verify */ }
-  return good ? { required: true, ok: true } : fail("la firma no corresponde a los ficheros que la procedencia declara");
+  return good ? { ok: true } : { ok: false, reason: "lleva una firma que no corresponde a los ficheros que declara" };
 }
 
 /**
@@ -164,7 +174,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, why = 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 +201,12 @@ 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) } : {}),
+      // KJC-TSK-0996 (HUM-D): what is done, why the signature is asked, what if another did it.
+      ...(why ? { why: str(why) } : {}),
     },
   };
   const created = await fetchFn(`${relay.url}?documentId=${cid}&key=${relay.apiKey}`, {

package/src/harden/roster.js

@@ -0,0 +1,116 @@
+/**
+ * KJC-TSK-0965 (HUM-B, ADR 0018): the roster of signing phones and its recovery
+ * code. A phone enters with an ADMISSION: a present phone's signature over the
+ * sha256 of its key, or the recovery code, spent. The code is shown once and NEVER
+ * stored: the roster keeps sha256(sha256(code)), and spending it reveals sha256(code),
+ * which only the holder can produce. CI judges a change with `verifyRosterChange`.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { validatePhonePublicKey, verifySignedFiles } from "./phone-sign.js";
+
+export const SIGNERS_FILE = ".karajan/supervisor-signers.json";
+const CODE_RE = /^kjrc(-[a-z2-7]{5}){4}$/;
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+const short = (key) => `${String(key).slice(0, 8)}…`;
+const validKey = (key) => { try { validatePhonePublicKey(key); return true; } catch { return false; } };
+
+/** 100 random bits as kjrc-xxxxx-xxxxx-xxxxx-xxxxx; the roster keeps the fingerprint only. */
+export function issueRecoveryCode(random = randomBytes) {
+  const chars = [...random(20)].map((b) => "abcdefghijklmnopqrstuvwxyz234567"[b & 31]);
+  const code = `kjrc-${[0, 5, 10, 15].map((i) => chars.slice(i, i + 5).join("")).join("-")}`;
+  return { code, fingerprint: sha256(sha256(code)) };
+}
+
+/** What a present phone signs to admit a key: the roster file and the key's sha256. */
+export const admissionFiles = (publicKey) => [{ file: SIGNERS_FILE, sha256: sha256(publicKey) }];
+
+const normalize = (doc) => ({ signers: Array.isArray(doc?.signers) ? doc.signers.filter((s) => typeof s?.publicKey === "string") : [], recovery: doc?.recovery ?? null });
+
+export function readRoster({ projectDir }) {
+  try { return normalize(JSON.parse(readFileSync(join(projectDir, SIGNERS_FILE), "utf8"))); } catch { return normalize(null); }
+}
+
+/** The code must match the roster's fingerprint; returns the admission (its proof, not the code). Writes nothing. */
+export function redeemRecoveryCode(code, { projectDir }) {
+  if (!CODE_RE.test(code ?? "")) throw new Error("el código de recuperación no tiene el formato kjrc-xxxxx-xxxxx-xxxxx-xxxxx");
+  const { recovery } = readRoster({ projectDir });
+  if (!recovery?.fingerprint) throw new Error("este padrón no tiene código de recuperación: se emite al enrolar el primer móvil");
+  const proof = sha256(code);
+  if (sha256(proof) !== recovery.fingerprint) throw new Error("el código de recuperación no es el de este padrón");
+  return { recoveryProof: proof };
+}
+
+/**
+ * Adds a signer with its admission and writes the roster. The first signer, a spent
+ * code and a roster with no code yet issue a NEW code, returned once and never stored.
+ */
+export function admitSigner({ projectDir, publicKey, label = null, admission = null, replaces = null, random }) {
+  validatePhonePublicKey(publicKey);
+  const roster = readRoster({ projectDir });
+  if (roster.signers.some((s) => s.publicKey === publicKey)) return { roster, recoveryCode: null };
+  const first = roster.signers.length === 0;
+  if (!first && !admission) throw new Error("un móvil nuevo entra firmado por uno del padrón o con el código de recuperación (ADR 0018)");
+  const enrolledAt = new Date().toISOString();
+  // KJC-TSK-0999 (HUM-B2): the lost phone the code replaces is REVOKED by the same
+  // spent code; its entry stays, marked, so CI can see the revocation is backed.
+  if (replaces && !admission?.recoveryProof) throw new Error("sustituir un móvil se hace con el código de recuperación");
+  if (replaces && !roster.signers.some((s) => s.publicKey === replaces && !s.revoked)) throw new Error(`el móvil a sustituir (${short(replaces)}) no está en el padrón`);
+  const kept = roster.signers.map((s) => (s.publicKey === replaces ? { ...s, revoked: { at: enrolledAt, recoveryProof: admission.recoveryProof } } : s));
+  const next = { signers: [...kept, { publicKey, label, enrolledAt, ...(admission ? { admission } : {}) }], recovery: roster.recovery };
+  let recoveryCode = null;
+  if (first || admission?.recoveryProof || !roster.recovery) {
+    const issued = issueRecoveryCode(random);
+    recoveryCode = issued.code;
+    next.recovery = { fingerprint: issued.fingerprint, issuedAt: enrolledAt };
+  }
+  const path = join(projectDir, SIGNERS_FILE);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+  return { roster: next, recoveryCode };
+}
+
+/**
+ * CI's judgment of a roster change: every key that enters carries a valid admission,
+ * no key leaves, and the code's sha256 rotates only when one is spent (once).
+ * @returns {{ok: boolean, reason?: string, bootstrap?: boolean, added?: number, spent?: boolean}}
+ */
+export function verifyRosterChange({ before, after }) {
+  const fail = (reason) => ({ ok: false, reason });
+  const prev = normalize(before);
+  const next = normalize(after);
+  // `known`: every key the previous roster had, revoked or not (a revoked one is not new);
+  // `present`: the ones still allowed to sign, the only ones that can admit a key.
+  const known = new Set(prev.signers.map((s) => s.publicKey));
+  const present = new Set(prev.signers.filter((s) => !s.revoked).map((s) => s.publicKey));
+  const fresh = /^[0-9a-f]{64}$/.test(next.recovery?.fingerprint ?? "") ? next.recovery.fingerprint : null;
+  const gone = prev.signers.find((s) => !next.signers.some((n) => n.publicKey === s.publicKey));
+  if (gone) return fail(`el padrón pierde la clave ${short(gone.publicKey)}: una baja no tiene mecanismo en kj y solo se hace por fuera de CI, a la vista`);
+  const back = prev.signers.find((s) => s.revoked && !next.signers.find((n) => n.publicKey === s.publicKey)?.revoked);
+  if (back) return fail(`la clave ${short(back.publicKey)} estaba revocada y una revocación no se deshace`);
+  // KJC-TSK-0999: a key is revoked only by the recovery code spent in this same change.
+  const backed = (proof) => sha256(String(proof ?? "")) === prev.recovery?.fingerprint;
+  const revoked = next.signers.filter((n) => n.revoked && !prev.signers.find((s) => s.publicKey === n.publicKey)?.revoked);
+  if (revoked.length > 1) return fail("un código de recuperación revoca UN móvil, y este cambio revoca varios");
+  if (revoked.length === 1 && !backed(revoked[0].revoked.recoveryProof)) return fail(`la clave ${short(revoked[0].publicKey)} se revoca sin el código de recuperación de este padrón`);
+  if (known.size === 0) return next.signers.length === 1 && fresh && validKey(next.signers[0].publicKey) ? { ok: true, bootstrap: true } : fail("el primer padrón lleva UN móvil (clave ed25519 válida) y la huella de su código de recuperación; los demás entran admitidos");
+  const added = next.signers.filter((n) => !known.has(n.publicKey));
+  let spent = false;
+  for (const entry of added) {
+    if (!validKey(entry.publicKey)) return fail(`la clave ${short(entry.publicKey)} no es una clave ed25519 válida (base64 de 32 bytes)`);
+    const admission = entry.admission ?? null;
+    if (admission?.recoveryProof) {
+      if (spent) return fail("un código de recuperación admite UNA clave, y este cambio mete dos con él");
+      if (!backed(admission.recoveryProof)) return fail(`la clave ${short(entry.publicKey)} entra con un código de recuperación que no es el del padrón anterior`);
+      spent = true;
+      continue;
+    }
+    const check = verifySignedFiles({ sig: admission, files: admissionFiles(entry.publicKey), keys: present });
+    if (!check.ok) return fail(`la clave ${short(entry.publicKey)} entra sin admisión válida: ${check.reason}`);
+  }
+  if (spent && (!fresh || fresh === prev.recovery?.fingerprint)) return fail("el código de recuperación se gastó y el padrón no trae la huella de uno nuevo");
+  if (!spent && (prev.recovery ? fresh !== prev.recovery.fingerprint : added.length > 0 && !fresh)) return fail("la huella del código de recuperación cambia sin que se haya gastado ninguno, o falta cuando entra un móvil en un padrón sin código");
+  return { ok: true, added: added.length, spent };
+}

package/src/harden/security-level.js

@@ -0,0 +1,94 @@
+/**
+ * KJC-TSK-0967 (HUM-D, ADR 0018): the project's security level, versioned in
+ * .karajan/security-level.json: `max` (every catalog act signed by the phone
+ * over the exact bytes) or `normal` (the four layers of ADR 0009, a lesser
+ * guarantee said at every act). Going DOWN is itself a catalog act signed by an
+ * enrolled phone over the record's bytes; a `normal` record without that
+ * signature reads as `max`. Going up is free.
+ */
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+import { humanActOf } from "./human-act.js";
+import { PHONE_INVITE } from "./phone-invite.js";
+import { isPhoneEnrolled, readEnrolledKeys, requestPhoneSignature, verifySignedFiles } from "./phone-sign.js";
+
+export const SECURITY_LEVEL_FILE = ".karajan/security-level.json";
+// ADR 0018 (KJC-TSK-0997): `max` is the default now that CI verifies the signature
+// (HUM-A) and the recovery code exists (HUM-B). The level that protects whoever
+// does not know the risk exists; `kj security normal` lowers it, signed.
+export const DEFAULT_LEVEL = "max";
+
+const levelPath = (projectDir) => join(projectDir, SECURITY_LEVEL_FILE);
+const recordBytes = (record) => `${JSON.stringify(record, null, 2)}\n`;
+const unsigned = ({ level, since }) => ({ level, since });
+
+/** What the phone signs when the level goes down: the record without its signature. */
+export const signedFilesOf = (record) => [
+  { file: SECURITY_LEVEL_FILE, sha256: createHash("sha256").update(recordBytes(unsigned(record))).digest("hex") },
+];
+
+/**
+ * The level in force. A record that cannot be trusted reads as `max` and says why.
+ * @returns {{level: "max"|"normal", source: "default"|"file"|"invalid", since?: string, signer?: string, reason?: string}}
+ */
+export function readSecurityLevel({ projectDir, home } = {}) {
+  const invalid = (reason) => ({ level: "max", source: "invalid", reason: `${SECURITY_LEVEL_FILE}: ${reason}` });
+  const path = levelPath(projectDir);
+  if (!existsSync(path)) return { level: DEFAULT_LEVEL, source: "default" };
+  let record;
+  try { record = JSON.parse(readFileSync(path, "utf8")); } catch (err) { return invalid(`no es JSON (${err.message})`); }
+  if (record?.level === "max") return { level: "max", source: "file", since: record.since };
+  if (record?.level !== "normal") return invalid("declara un nivel que no existe");
+  const keys = readEnrolledKeys({ projectDir, home });
+  const check = verifySignedFiles({ sig: record.signature, files: signedFilesOf(record), keys });
+  if (!check.ok) return invalid(`el nivel normal ${check.reason}; vale como máxima`);
+  return { level: "normal", source: "file", since: record.since, signer: record.signature.signer };
+}
+
+/** Up to `max`: no act, no signature; it also replaces a record that cannot be trusted. */
+export function raiseSecurityLevel({ projectDir, home } = {}) {
+  const current = readSecurityLevel({ projectDir, home });
+  if (current.level === "max" && current.source !== "invalid") return { changed: false, level: current };
+  mkdirSync(dirname(levelPath(projectDir)), { recursive: true });
+  writeFileSync(levelPath(projectDir), recordBytes({ level: "max", since: new Date().toISOString() }), "utf8");
+  return { changed: true, level: readSecurityLevel({ projectDir, home }) };
+}
+
+const explain = (status) => ({
+  file: SECURITY_LEVEL_FILE, status, added: 3, removed: status === "modified" ? 3 : 0, truncated: false,
+  summary: "El nivel de seguridad de este proyecto baja de máxima a normal.",
+  diff: [
+    "Qué se va a hacer: los actos del catálogo (sellar el supervisor, aprobar reglas, enrolar un móvil) pasan a confirmarse",
+    "con las cuatro capas de ADR 0009 y un código tecleado; el móvil deja de firmarlos.",
+    "Por qué se pide tu firma: bajar el nivel es un acto del catálogo (ADR 0018); si no se firmara, el primero en bajarlo sería el agente.",
+    "Si lo hiciera otro: un registro de nivel normal sin la firma de un móvil del padrón no vale, y kj aplica la máxima.",
+  ].join("\n"),
+});
+
+/** Down to `normal`: the catalog act, four layers and the phone's signature; without a phone it refuses. */
+export async function lowerSecurityLevel({ projectDir, home, kjVersion, env, tty, deps = {}, logger = console }) {
+  const act = humanActOf("security-level-down");
+  act.refuse({ env, tty, ancestry: deps.ancestry ?? {} });
+  const current = readSecurityLevel({ projectDir, home });
+  if (current.level === "normal") return { changed: false, level: current };
+  const phone = deps.phone ?? { enrolled: isPhoneEnrolled, request: requestPhoneSignature };
+  if (!phone.enrolled({ home })) throw new Error(`${act.label}: bajar el nivel se firma con el móvil y no hay ninguno enrolado. ${PHONE_INVITE}`);
+  act.confirm(deps.confirm);
+  const record = { level: "normal", since: new Date().toISOString() };
+  let branch = null;
+  try { branch = execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], { cwd: projectDir, encoding: "utf8" }).trim(); } catch { /* no repo */ }
+  const signed = await phone.request({
+    project: basename(projectDir), files: signedFilesOf(record), kjVersion, branch, logger,
+    changes: [explain(existsSync(levelPath(projectDir)) ? "modified" : "new")],
+    origin: `kj security normal (kj ${kjVersion})`, deps: { projectDir, home },
+  });
+  if (!signed.ok) throw new Error(`${act.label}: firma del móvil rechazada (${signed.reason}); el nivel no cambia`);
+  if (!signed.challenge || !signed.signer || !signed.signature) throw new Error(`${act.label}: el relé no devolvió un desafío firmado que kj pueda grabar; el nivel no cambia`);
+  const signature = { ...signed.challenge, signer: signed.signer, signature: signed.signature };
+  mkdirSync(dirname(levelPath(projectDir)), { recursive: true });
+  writeFileSync(levelPath(projectDir), recordBytes({ ...record, signature }), "utf8");
+  return { changed: true, level: readSecurityLevel({ projectDir, home }) };
+}

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

@@ -8,13 +8,14 @@
 import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { basename, join } from "node:path";
+import { 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 { isPhoneEnrolled, requestPhoneSignature } from "./phone-sign.js";
+import { signAct } from "./act-sign.js";
+import { humanActOf } from "./human-act.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
@@ -119,27 +120,18 @@ export async function commitSupervisorRegeneration({
     logger.info?.("harden --commit: sin drift y provenance completa — nada que versionar");
     return { committed: false, reason: "sin drift" };
   }
-  // Capa 5 (KJC-TSK-0822 / PRP-0023): con móvil enrolado la firma asimétrica
-  // es OBLIGATORIA — jamás se degrada a solo-nonce. Firma los MISMOS
-  // files/hashes de la provenance (normalizados al par {file, sha256}).
-  const phone = deps.phone ?? { enrolled: isPhoneEnrolled, request: requestPhoneSignature };
-  let signatureBlock = null;
-  if (phone.enrolled({})) {
-    const signed = await phone.request({
-      project: basename(projectDir),
-      files: hashed.map(({ file, sha256: hash }) => ({ file, sha256: hash ?? "" })),
-      kjVersion,
-      logger,
-    });
-    if (!signed.ok) {
-      throw new Error(`capa 5: firma del móvil rechazada (${signed.reason}) — con móvil enrolado el sello exige su firma (PRP-0023)`);
-    }
-    // KJC-TSK-0823: graba el desafío + firma en la provenance para que CI
-    // re-verifique server-side que un humano (clave del padrón) aprobó.
-    if (signed.challenge && signed.signature) {
-      signatureBlock = { ...signed.challenge, signer: signed.signer, signature: signed.signature };
-    }
-  }
+  // Capa 5 (KJC-TSK-0822 / PRP-0023, KJC-TSK-0996 / ADR 0018): the level applied
+  // by the catalog's mechanism. With a phone enrolled its signature over the SAME
+  // files/hashes of the provenance is mandatory, never nonce-only; at max with no
+  // phone the seal is refused. KJC-TSK-0992: the page says what is signed, file by
+  // file; KJC-TSK-0823: the block is recorded so CI re-verifies server-side.
+  let branch = null;
+  try { branch = run(["rev-parse", "--abbrev-ref", "HEAD"]).trim(); } catch { /* unborn HEAD */ }
+  const { signature: signatureBlock } = await signAct("supervisor-seal", {
+    projectDir, kjVersion, branch, logger, deps,
+    files: hashed.map(({ file, sha256: hash }) => ({ file, sha256: hash ?? "" })),
+    changes: (deps.describeChanges ?? describeSupervisorChanges)({ projectDir, files: hashed }),
+  });
   const who = readIdentity(projectDir);
   const provenance = {
     kj_version: kjVersion,

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/policy/roster-check.js

@@ -0,0 +1,34 @@
+/**
+ * KJC-TSK-1000 (HUM-B3, ADR 0018): CI judges every change of the roster of
+ * signing phones. When the diff touches .karajan/supervisor-signers.json, the
+ * roster of the base (the range's start, or HEAD for a staged check) and the
+ * one that lands (the checkout, or the staged blob) go through
+ * `verifyRosterChange`; a refusal is a deny violation with its reason, so that
+ * reinstalling kj on a machine never changes what CI demands.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { SIGNERS_FILE, verifyRosterChange } from "../harden/roster.js";
+
+export const ROSTER_RULE = "defaults.roster.change";
+
+const parse = (text) => { try { return JSON.parse(text); } catch { return {}; } };
+// An object that is not a roster reads as an empty one: a base that is missing is
+// a first roster; a landing one that is missing or broken loses every key.
+const shown = async (run, spec) => { try { return parse(await run(["show", spec])); } catch { return null; } };
+const local = (projectDir) => { try { return parse(readFileSync(join(projectDir, SIGNERS_FILE), "utf8")); } catch { return null; } };
+
+/**
+ * @param {{projectDir: string, files: string[], range: string|null, run: (args: string[]) => Promise<string>}} opts
+ * @returns {Promise<object|null>} the violation, or null when the roster is untouched or the change is backed
+ */
+export async function rosterViolation({ projectDir, files, range, run }) {
+  if (!files.includes(SIGNERS_FILE)) return null;
+  const baseRef = range ? range.split(/\.{2,3}/)[0] : "HEAD";
+  const before = await shown(run, `${baseRef}:${SIGNERS_FILE}`);
+  const after = range ? local(projectDir) : await shown(run, `:${SIGNERS_FILE}`);
+  const verdict = verifyRosterChange({ before, after });
+  if (verdict.ok) return null;
+  return { rule_id: ROSTER_RULE, enforcement: "deny", file: SIGNERS_FILE, reason: `el padrón de móviles cambia sin respaldo (ADR 0018): ${verdict.reason}` };
+}

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/review/gate-gitignore.js

@@ -42,6 +42,8 @@ export const CONTRACT_BLOCK = [
   // ADR 0016 (KJC-TSK-0947): the rules of the MD files compiled into gates are
   // governance the whole team inherits, like the hooks.
   "!.karajan/rules.yml",
+  // KJC-TSK-0995 (HUM-D, ADR 0018): the security level, signed when lowered, is the team's.
+  "!.karajan/security-level.json",
 ];
 
 /**