karajan-code 4.46.0 → 4.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.46.0",
+  "version": "4.48.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", "handoff"] },
   { 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,8 @@ 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 { handoffCommand } from "../commands/handoff.js";
 import { policyCommand } from "../commands/policy.js";
 import { claimsCommand, claimsGateCommand } from "../commands/claims.js";
 import { stewardSweepCommand } from "../commands/steward.js";
@@ -163,12 +165,45 @@ 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-0968 (HUM-E, ADR 0018): the agent's handoff to the human goes through kj.
+  const handoffCmd = program.command("handoff").description("Handoffs: what a gate denied the agent, registered with the gate's why, for the human to read and run by id");
+  const handoff = (action, flags) => withConfig(pkgVersion, `handoff-${action}`, flags, async ({ config }) => { process.exitCode = await handoffCommand({ action, config, flags }); });
+  handoffCmd.command("add").description("Register the EXACT command a gate denied (the why comes from the Sentinel's record, not from you)")
+    .argument("<command...>", "the denied command, as it was run").option("--cwd <dir>", "Directory the command runs in (default: the project)")
+    .action((parts, flags) => handoff("add", { ...flags, command: parts.join(" ") }));
+  handoffCmd.command("list", { isDefault: true }).description("The handoffs registered in this project").action((flags) => handoff("list", flags));
+  handoffCmd.command("show").description("A handoff: the exact command, its sha256 and why the gate denied it")
+    .argument("<id>", "handoff id (8 hex)").option("--json", "Output the record as JSON").action((id, flags) => handoff("show", { ...flags, id }));
+
   // KJC-TSK-0986 (HUM-F): the invitation to enroll the phone, once per version.
   identityCmd
     .command("phone-invite")
@@ -412,7 +447,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/handoff.js

@@ -0,0 +1,38 @@
+/**
+ * kj handoff add|list|show (KJC-TSK-0968, HUM-E, ADR 0018): the agent registers
+ * what a gate denied it, with the gate's why; the human reads it by id.
+ */
+import { addHandoff, listHandoffs, readHandoff } from "../harden/handoff.js";
+
+const line = (h) => `${h.id}  ${h.status.padEnd(8)}  ${h.createdAt}  ${h.command}`;
+
+/** @returns {Promise<0|1>} */
+export async function handoffCommand({ action = "list", config, flags = {}, log = console.log }) {
+  const projectDir = config?.projectDir || process.cwd();
+  try {
+    if (action === "add") {
+      const record = addHandoff({ projectDir, command: flags.command, cwd: flags.cwd ?? projectDir });
+      log(`encargo ${record.id} registrado: ${record.command}`);
+      log(`por qué lo negó el gate (${record.denial.at}):\n${record.denial.why}`);
+      log(`tu usuario lo revisa con kj handoff show ${record.id}; nadie copia y pega el comando.`);
+      return 0;
+    }
+    if (action === "show") {
+      const h = readHandoff({ projectDir, id: flags.id });
+      if (flags.json) { log(JSON.stringify(h)); return 0; }
+      log(`encargo   ${h.id} (${h.status}, ${h.createdAt})`);
+      log(`comando   ${h.command}`);
+      log(`sha256    ${h.sha256}`);
+      log(`cwd       ${h.cwd}`);
+      log(`gate      ${h.denial.tool} negó el ${h.denial.at}:\n${h.denial.why}`);
+      return 0;
+    }
+    const all = listHandoffs({ projectDir });
+    if (all.length === 0) log("kj handoff: ningún encargo registrado");
+    for (const h of all) log(line(h));
+    return 0;
+  } catch (err) {
+    log(err.message);
+    return 1;
+  }
+}

package/src/commands/identity.js

@@ -8,7 +8,11 @@
  *           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";
@@ -16,7 +20,7 @@ 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;
@@ -28,19 +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-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 });
-      enrollPhone(flags.publicKeyBase64, { home: deps.home });
+      // 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,11 +7,13 @@
  * 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 { 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";
@@ -23,7 +25,10 @@ import { loadRules, LOCAL_RULES_FILE, PROPOSAL_FILE, RULES_FILE, rulesCheck } fr
  *   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 }) {
+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);
@@ -52,9 +57,21 @@ export async function rulesApprove({ projectDir, file = PROPOSAL_FILE, home, env
   // 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/handoff.js

@@ -0,0 +1,60 @@
+/**
+ * KJC-TSK-0968 (HUM-E, ADR 0018): the agent's handoff to the human goes through
+ * kj. When a gate denies the agent a command, the agent registers a HANDOFF with
+ * the exact command; the why is what the gate said, read from the Sentinel's
+ * record of denials, never a text of the agent. The human later reads and runs
+ * it by id (E2, E3). Handoffs live in .karajan/handoffs/<id>.json, local.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const HANDOFFS_DIR = ".karajan/handoffs";
+export const DENIALS_FILE = ".karajan/harness/denials.jsonl";
+const sha256 = (text) => createHash("sha256").update(text).digest("hex");
+
+/** The Sentinel's denials, oldest first; a line that is not JSON is skipped. */
+export function readDenials({ projectDir }) {
+  let text;
+  try { text = readFileSync(join(projectDir, DENIALS_FILE), "utf8"); } catch { return []; }
+  return text.split("\n").filter(Boolean).flatMap((line) => { try { return [JSON.parse(line)]; } catch { return []; } });
+}
+
+/** The latest denial of this EXACT Bash command, or null. */
+export function findDenial({ projectDir, command }) {
+  return readDenials({ projectDir }).findLast((d) => d?.tool === "Bash" && d?.input?.command === command) ?? null;
+}
+
+/**
+ * Registers a handoff for a command a gate denied. Without a denial of those
+ * exact bytes there is nothing to hand off: the agent does not write the why.
+ * @returns {{id: string, command: string, sha256: string, why: string}}
+ */
+export function addHandoff({ projectDir, command, cwd = projectDir }) {
+  if (typeof command !== "string" || !command.trim()) throw new Error("kj handoff add: falta el comando exacto que el gate negó");
+  const denial = findDenial({ projectDir, command });
+  if (!denial) throw new Error("kj handoff add: kj no tiene registrado ningún deny para ese comando exacto; el porqué de un encargo lo escribe el gate, no el agente (ADR 0018)");
+  const createdAt = new Date().toISOString();
+  const digest = sha256(command);
+  const id = sha256(`${digest}:${createdAt}`).slice(0, 8);
+  const record = { id, command, sha256: digest, cwd, createdAt, status: "pending", denial: { at: denial.at, tool: denial.tool, why: denial.why } };
+  mkdirSync(join(projectDir, HANDOFFS_DIR), { recursive: true });
+  writeFileSync(join(projectDir, HANDOFFS_DIR, `${id}.json`), `${JSON.stringify(record, null, 2)}\n`, "utf8");
+  return record;
+}
+
+export function readHandoff({ projectDir, id }) {
+  if (!/^[0-9a-f]{8}$/.test(id ?? "")) throw new Error(`kj handoff: "${id}" no es un identificador de encargo (8 hex)`);
+  const path = join(projectDir, HANDOFFS_DIR, `${id}.json`);
+  if (!existsSync(path)) throw new Error(`kj handoff: no hay ningún encargo ${id}`);
+  const record = JSON.parse(readFileSync(path, "utf8"));
+  // The bytes the human will run are the bytes that were registered, or nothing.
+  if (sha256(record.command ?? "") !== record.sha256) throw new Error(`kj handoff: el encargo ${id} no coincide con su sha256: alguien lo tocó, no se ejecuta`);
+  return record;
+}
+
+export function listHandoffs({ projectDir }) {
+  let names;
+  try { names = readdirSync(join(projectDir, HANDOFFS_DIR)).filter((n) => /^[0-9a-f]{8}\.json$/.test(n)); } catch { return []; }
+  return names.map((n) => readHandoff({ projectDir, id: n.slice(0, 8) })).sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+}

package/src/harden/hook-templates.js

@@ -135,8 +135,9 @@ export function hookBody(hook, cmds = {}, { globalHooksDir = null, baseBranch =
         "fi",
         "# KJC-BUG-0296 (issue #1989): the host agent's runtime and local state never",
         "# enter a commit, however they were staged (a blanket `git add -A` put a",
-        "# Claude scheduler lock into main). Checked on the staged list itself.",
-        "if git diff --cached --name-only | grep -qE '^(\\.claude/[^/]*\\.lock|\\.claude/scheduled_tasks\\.lock|\\.kj/|\\.karajan/identity\\.local\\.yml|\\.karajan/harness/sentinel-state\\.json)'; then",
+        "# Claude scheduler lock into main). Checked on the staged list itself,",
+        "# deletions left out: untracking a runtime file is the fix (KJC-BUG-0307).",
+        "if git diff --cached --name-only --diff-filter=d | grep -qE '^(\\.claude/[^/]*\\.lock|\\.claude/scheduled_tasks\\.lock|\\.kj/|\\.karajan/identity\\.local\\.yml|\\.karajan/harness/sentinel-state\\.json)'; then",
         "  echo 'kj harden: agent runtime files are staged (.claude/*.lock, .kj/, identity.local.yml, sentinel-state.json) — unstage them: git restore --staged <path>'; exit 1",
         "fi",
         "# v4 review gate (ENV-C1, opt-in via `kj review --install-gate`):",

package/src/harden/human-act.js

@@ -82,7 +82,7 @@ export const HUMAN_ACTS = Object.freeze({
   "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" },
+  "security-level-down": { label: "kj security normal", module: "src/harden/security-level.js" },
 });
 
 /**

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" };
 }
 
 /**
@@ -171,7 +181,7 @@ const changesValue = (changes) => ({ arrayValue: { values: changes.map((c) => ({
   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 = {} }) {
+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)));
@@ -195,6 +205,8 @@ export async function requestPhoneSignature({ project, files, kjVersion, changes
       ...(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/sentinel/sentinel-shell.mjs

@@ -64,6 +64,28 @@ export const headIndex = (words, heads) => {
   return k < 0 ? words.length : i + k;
 };
 
+/**
+ * KJC-BUG-0306: a simple command that runs `gh ... issue create`, read by words
+ * (quotes, escapes and newlines as the shell reads them), not by words anywhere.
+ * @param {string} cmd
+ */
+export const isGhIssueCreate = (cmd) => shellSegments(cmd).some((words) => {
+  const i = headIndex(words, ["gh"]);
+  if (words[i]?.split("/").at(-1) !== "gh") return false;
+  // The subcommand words, with every flag skipped together with a value that may
+  // follow it (--repo x, --hostname y): what is left is "issue", then "create".
+  const subcommand = [];
+  let afterFlag = false;
+  for (const w of words.slice(i + 1)) {
+    if (w.startsWith("-")) { afterFlag = !w.includes("="); continue; }
+    if (afterFlag && !["issue", "create"].includes(w)) { afterFlag = false; continue; }
+    afterFlag = false;
+    subcommand.push(w);
+    if (subcommand.length === 2) break;
+  }
+  return subcommand[0] === "issue" && subcommand[1] === "create";
+});
+
 // KJC-BUG-0286: a $ expands only when something expandable follows it ($x, ${x},
 // $(cmd), $1, $@...). A lone "$ " in a grep pattern is a literal dollar sign.
 const LIVE_EXPANSION = /\$(?=[A-Za-z0-9_{(@*#?$!-])|`/;
@@ -90,11 +112,16 @@ export const stripInertQuotes = (cmd) => {
 };
 
 // Options whose value is prose, never a path (gh, git, kj).
-const TEXT_OPTIONS = new Set(["--title", "--body", "--message", "-m", "--notes", "--description", "--ac", "--criteria", "--reason", "--decision", "--context", "--consequences", "--position"]);
+// KJC-BUG-0306: --error and --command of kj report-issue, --scope and --tests of kj hu add.
+const TEXT_OPTIONS = new Set(["--title", "--body", "--message", "-m", "--notes", "--description", "--ac", "--criteria", "--reason", "--decision", "--context", "--consequences", "--position", "--error", "--command", "--scope", "--tests"]);
 const QUOTED_OPTION_VALUE = /(^|\s)(--?[a-z]+)(=|\s+)("[^"$`\\]*"|'[^']*')/g;
+// KJC-BUG-0306: the title kj hu add and kj adr add take as their first argument, at the start of a segment.
+const KJ_TITLE = /(^|[;&|]\s*)(kj\s+(?:hu|adr)\s+add\s+)("[^"$`\\]*"|'[^']*')/g;
 
 /** KJC-BUG-0243: blank the inert quoted value of a text option (--title "a/b c"): prose, not a path. */
-export const stripTextOptionValues = (cmd) => cmd.replace(QUOTED_OPTION_VALUE, (m, pre, opt, sep, val) => (TEXT_OPTIONS.has(opt) ? `${pre}${opt}${sep}${val[0]}${val[0]}` : m));
+export const stripTextOptionValues = (cmd) => cmd
+  .replace(KJ_TITLE, (m, pre, head, val) => `${pre}${head}${val[0]}${val[0]}`)
+  .replace(QUOTED_OPTION_VALUE, (m, pre, opt, sep, val) => (TEXT_OPTIONS.has(opt) ? `${pre}${opt}${sep}${val[0]}${val[0]}` : m));
 
 /**
  * KJC-BUG-0245: the values of the named options, read by the shell reader, so a

package/src/harden/sentinel-hooks.js

@@ -467,13 +467,13 @@ const PRETOOL_BODY = `#!/usr/bin/env node
 import console from "node:console";
 import process from "node:process";
 import { dirname, join, relative, resolve } from "node:path";
-import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { appendFileSync, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
-import { doc, CODE, TESTS, ROOT, BASE_BRANCHES, CARD, branchOf, foreignLane, load, save, session, violations, boardGate, pendingMoves, pendingText } from "./sentinel-lib.mjs";
+import { doc, CODE, TESTS, ROOT, BASE_BRANCHES, CARD, STATE, branchOf, foreignLane, load, save, session, violations, boardGate, pendingMoves, pendingText } from "./sentinel-lib.mjs";
 // KJC-TSK-0915 (ADR 0014): the shell reader is a real, unit-tested module copied here as is.
-import { optionValues, shellSegments, stripInertQuotes, stripTextOptionValues } from "./sentinel-shell.mjs";
+import { isGhIssueCreate, optionValues, shellSegments, stripInertQuotes, stripTextOptionValues } from "./sentinel-shell.mjs";
 import { DISCARD_VERBS, discardOf, foreignLost, removedFiles } from "./sentinel-discard.mjs";
 import { shellWrites, writesRepo } from "./sentinel-bash-write.mjs";
 const EDIT_TOOLS = ["Write", "Edit", "MultiEdit", "NotebookEdit"];
@@ -495,8 +495,17 @@ process.stdin.on("end", () => {
   try {
     const { session_id: sid = "default", tool_name: tool, tool_input: input = {}, transcript_path: transcript = null } = JSON.parse(raw);
     // KJC-TSK-0920 (SNT-E): every deny ends with the same line, whatever gate it was.
+    // KJC-TSK-0968 (HUM-E, ADR 0018): and leaves a record next to the state, with the
+    // gate's own words: kj handoff takes the why from here, never from the agent.
+    const said = [];
+    const errOrig = console.error.bind(console);
+    console.error = (m) => { said.push(String(m)); errOrig(m); };
     process.on("exit", (code) => {
-      if (code === 2) console.error("karajan: Karajan gobierna y se le obedece. No rodees el gate ni cambies la politica para pasarlo; si te parece injusto, diselo a tu usuario o usa kj report-issue.");
+      if (code !== 2) return;
+      errOrig("karajan: Karajan gobierna y se le obedece. No rodees el gate ni cambies la politica para pasarlo; si te parece injusto, diselo a tu usuario o usa kj report-issue.");
+      // Only what a handoff needs: the exact Bash command, or the path an edit aimed at; never file contents.
+      const what = tool === "Bash" ? { command: input.command } : { file_path: input.file_path || input.notebook_path || null };
+      try { appendFileSync(join(dirname(STATE), "denials.jsonl"), JSON.stringify({ at: new Date().toISOString(), sid, tool, input: what, why: said.join("\\n") }) + "\\n"); } catch { /* the deny stands without its record */ }
     });
     // KJC-BUG-0238 (#1886): de quien es cada cambio. La primera vez que la
     // sesion toca un fichero se anota si estaba limpio: solo entonces un
@@ -574,7 +583,9 @@ process.stdin.on("end", () => {
     // (sanitiza y busca duplicados), nunca por gh issue create a mano.
     {
       const ghIssue = String(input.command || "");
-      if (tool === "Bash" && /(^|[^a-zA-Z])gh([^a-zA-Z]|$)/.test(ghIssue) && /(^|[^a-z])issue([^a-z]|$)/.test(ghIssue) && /(^|[^a-z])create([^a-z]|$)/.test(ghIssue)) {
+      // KJC-BUG-0306: the subcommand itself (gh, its flags, issue create), not three words
+      // anywhere: "gh pr create --title 'kj report-issue ...'" is not an issue.
+      if (tool === "Bash" && isGhIssueCreate(ghIssue)) {
         // The target: --repo/-R, an inline or inherited GH_REPO, else the
         // checkout's own origin, which is what gh takes (review catches).
         const inlineRepo = /(^|[^A-Z_])GH_REPO=([^ ]+)/.exec(ghIssue);
@@ -884,7 +895,7 @@ process.stdin.on("end", () => {
         // KJC-BUG-0243: inert quoted text is not a substitution, and the prose value
         // of a text option (--title, -m...) is not a path.
         if (/\\$\\(|\`/.test(stripInertQuotes(cmd)) || quotedPathWithSpaces(stripTextOptionValues(cmd))) {
-          console.error("karajan sentinel: sustitucion de comandos o ruta entrecomillada con espacios en un comando mutador — no verificable por el guard de carriles (MONO-0); usa valores/rutas LITERALES sin sustitucion." + doc("cross-lane"));
+          console.error("karajan sentinel: sustitucion de comandos o ruta entrecomillada con espacios en un comando mutador — no verificable por el guard de carriles (MONO-0); usa valores/rutas LITERALES sin sustitucion. Si es texto (titulo, descripcion, error) con comillas de codigo o dolar, ponlo entre comillas SIMPLES: entre dobles la shell lo ejecuta." + doc("cross-lane"));
           process.exit(2);
         }
         const SAFE_EXP_SEG = /^([A-Za-z_][A-Za-z0-9_]*=[^ \\t]*[ \\t]*)*((npm|pnpm|yarn|vitest|jest|kj|gh|echo|printf|true|test)\\b|git[ \\t](?![^\\n]*(-C[ \\t]|--git-dir|--work-tree)))[^;|&\\n]*$|^[A-Za-z_][A-Za-z0-9_]*=[^;|&\\n]*$/;

package/src/harden/supervisor-commit.js

@@ -8,13 +8,13 @@
 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 { signAct } from "./act-sign.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";
@@ -120,33 +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({})) {
-    // 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) {
-      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/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/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",
 ];
 
 /**