karajan-code 4.70.4 → 5.0.0

package/src/commands/identity.js

@@ -21,91 +21,115 @@ 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, kjVersion = "unknown", flags = {}, deps = {} }) {
-  const projectDir = config?.projectDir || process.cwd();
-  const log = deps.log || console.log;
-  const tty = deps.isTTY || isTTY;
-  const detectOpts = { hostsPath: deps.hostsPath, gitFn: deps.gitFn };
-  const effective = {
-    gh_user: activeGhUser(detectOpts.hostsPath ? { hostsPath: detectOpts.hostsPath } : {}),
-    git_email: effectiveGitEmail(projectDir, detectOpts.gitFn ? { gitFn: detectOpts.gitFn } : {}),
-  };
+const SIGNERS_FILE = ".karajan/supervisor-signers.json";
 
-  // 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-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;
+// Reading the effective identity never throws: both readers answer null when unknown.
+const effectiveIdentity = (projectDir, deps) => ({
+  gh_user: activeGhUser(deps.hostsPath ? { hostsPath: deps.hostsPath } : {}),
+  git_email: effectiveGitEmail(projectDir, deps.gitFn ? { gitFn: deps.gitFn } : {}),
+});
+
+// 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.
+// The lost phone is REVOKED by the same code: the one named with --replaces, or the one this machine had enrolled.
+function recoveryOf({ projectDir, log, flags, deps }) {
+  const recovered = flags.recovery ? redeemRecoveryCode(flags.recovery, { projectDir }) : null;
+  if (!recovered) return { recovered: null, lost: null };
+  const lost = flags.replaces ?? (isPhoneEnrolled({ home: deps.home }) ? readEnrolledKey({ home: deps.home }) : null);
+  if (!lost) throw new Error("di qué móvil se pierde: --replaces <su clave pública> (esta máquina no tiene ninguno enrolado)");
+  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`);
+  return { recovered, lost };
+}
+
+// Returns the recovery code the roster issues for the new key.
+async function admitPhone(ctx) {
+  const { projectDir, log, kjVersion, flags, deps } = ctx;
+  // 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 { recovered, lost } = recoveryOf(ctx);
+  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_FILE, sha256: createHash("sha256").update(key).digest("hex") }],
+    changes: [{ file: SIGNERS_FILE, 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.
+  const { recoveryCode } = admitSigner({ projectDir, publicKey: key, label: flags.label ?? null, admission: recovered ?? signature, replaces: lost });
+  enrollPhone(key, { home: deps.home });
+  return recoveryCode;
+}
+
+// KJC-TSK-0822: enrola la clave PÚBLICA del móvil (la privada nunca toca esta máquina).
+async function enrollPhoneAction(ctx) {
+  const { log } = ctx;
+  let recoveryCode;
+  try {
+    recoveryCode = await admitPhone(ctx);
+  } 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;
+}
 
-  // KJC-TSK-0986 (HUM-F): the once-per-version invitation to enroll the phone,
-  // printed for the SessionStart hook (which cannot import kj) and for scripts.
-  if (action === "phone-invite") {
-    // KJC-BUG-0360: the text depends on the level; at max (the default) the acts are refused.
-    const { level } = readSecurityLevel({ projectDir: deps.projectDir ?? process.cwd(), home: deps.home });
-    const text = phoneInvite({ home: deps.home, version: flags.version, level });
-    if (text) log(text);
-    return 0;
+// KJC-TSK-0986 (HUM-F): the once-per-version invitation to enroll the phone,
+// printed for the SessionStart hook (which cannot import kj) and for scripts.
+function phoneInviteAction({ log, flags, deps }) {
+  // KJC-BUG-0360: the text depends on the level; at max (the default) the acts are refused.
+  const { level } = readSecurityLevel({ projectDir: deps.projectDir ?? process.cwd(), home: deps.home });
+  const text = phoneInvite({ home: deps.home, version: flags.version, level });
+  if (text) log(text);
+  return 0;
+}
+
+// Resolves true when the binding may go ahead.
+async function confirmBinding(candidate, { log, flags, deps }) {
+  const tty = deps.isTTY || isTTY;
+  if (tty() && !flags.yes) {
+    const wizard = (deps.makeWizard || createWizard)();
+    try {
+      const ok = await wizard.confirm(`Bind this clone to gh ${candidate.gh_user} / git ${candidate.git_email}?`, true);
+      if (!ok) log("kj identity: not declared.");
+      return ok;
+    } finally { wizard.close(); }
   }
+  if (!flags.gh || !flags.email) {
+    // Proven live on day one: the active gh session had been flipped by
+    // ANOTHER session, and --yes bound the clone to the wrong account.
+    // Binding without confirmation is allowed, but never silent.
+    log("kj identity: WARNING — binding the ACTIVE session as-is without confirmation (another session may have switched it); prefer --gh/--email explicitly and verify with `kj identity show`.");
+  }
+  return true;
+}
 
-  if (action === "set") {
-    const candidate = { gh_user: flags.gh || effective.gh_user, git_email: flags.email || effective.git_email };
-    if (!candidate.gh_user || !candidate.git_email) {
-      log(`kj identity: cannot declare — gh account: ${candidate.gh_user ?? "no session"}, git email: ${candidate.git_email ?? "none"}. Log in / set git config, or pass --gh <user> --email <email>.`);
-      return 1;
-    }
-    if (tty() && !flags.yes) {
-      const wizard = (deps.makeWizard || createWizard)();
-      try {
-        const ok = await wizard.confirm(`Bind this clone to gh ${candidate.gh_user} / git ${candidate.git_email}?`, true);
-        if (!ok) { log("kj identity: not declared."); return 1; }
-      } finally { wizard.close(); }
-    } else if (!flags.gh || !flags.email) {
-      // Proven live on day one: the active gh session had been flipped by
-      // ANOTHER session, and --yes bound the clone to the wrong account.
-      // Binding without confirmation is allowed, but never silent.
-      log("kj identity: WARNING — binding the ACTIVE session as-is without confirmation (another session may have switched it); prefer --gh/--email explicitly and verify with `kj identity show`.");
-    }
-    writeIdentity(projectDir, candidate);
-    log(`kj identity: declared gh ${candidate.gh_user} / git ${candidate.git_email} → .karajan/identity.local.yml (ignored by git).`);
-    return 0;
+async function setAction(ctx) {
+  const { projectDir, log, flags, deps } = ctx;
+  const effective = effectiveIdentity(projectDir, deps);
+  const candidate = { gh_user: flags.gh || effective.gh_user, git_email: flags.email || effective.git_email };
+  if (!candidate.gh_user || !candidate.git_email) {
+    log(`kj identity: cannot declare — gh account: ${candidate.gh_user ?? "no session"}, git email: ${candidate.git_email ?? "none"}. Log in / set git config, or pass --gh <user> --email <email>.`);
+    return 1;
   }
+  if (!(await confirmBinding(candidate, ctx))) return 1;
+  writeIdentity(projectDir, candidate);
+  log(`kj identity: declared gh ${candidate.gh_user} / git ${candidate.git_email} → .karajan/identity.local.yml (ignored by git).`);
+  return 0;
+}
 
+function showAction({ projectDir, log, deps }) {
+  const effective = effectiveIdentity(projectDir, deps);
   const declared = readIdentity(projectDir);
   const result = compareIdentity(declared, effective);
   if (!declared) {
@@ -118,3 +142,12 @@ export async function identityCommand({ action = "show", config, kjVersion = "un
   for (const m of result.mismatches) log(`  → ${m.remedy}`);
   return result.ok ? 0 : 2;
 }
+
+// Any other action shows the identity, as before.
+const ACTIONS = { "enroll-phone": enrollPhoneAction, "phone-invite": phoneInviteAction, set: setAction };
+
+export async function identityCommand({ action = "show", config, kjVersion = "unknown", flags = {}, deps = {} }) {
+  const ctx = { projectDir: config?.projectDir || process.cwd(), log: deps.log || console.log, kjVersion, flags, deps };
+  const run = Object.hasOwn(ACTIONS, action) ? ACTIONS[action] : showAction;
+  return run(ctx);
+}

package/src/commands/init-atril.js

@@ -0,0 +1,47 @@
+/**
+ * KJC-TSK-1219 (ADR 0021, step 15d): kj init installs Karajan's kj-* commands into atril's
+ * store under `.karajan/`, on demand (ADR 0021's default answer), instead of copying them into
+ * `.claude/commands/`. With rulesync, `atril sync` takes the bridge and the router rule to every
+ * CLI; without it nothing persistent is installed, and kj says how to get there.
+ */
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { generate, install, sync } from "@karajan-family/atril";
+import { ATRIL_ROOT } from "../skills/atril-skills.js";
+import { detectRulesync } from "../utils/rulesync.js";
+import { getTemplatesRoot } from "../utils/templates-root.js";
+
+/**
+ * @param {{ projectDir: string, logger: { info: Function, warn: Function }, env?: object, offerRulesync?: boolean }} opts
+ *   offerRulesync false: the user declined rulesync (--no-rulesync), so kj does not suggest it again
+ * @returns {{ installed: number, synced: boolean }}
+ */
+export function installKarajanCommands({ projectDir, logger, env = process.env, offerRulesync = true }) {
+  const catalog = join(getTemplatesRoot(), "atril", "commands");
+  const atril = { root: ATRIL_ROOT, projectDir, env };
+  let installed = 0;
+  let unchanged = 0;
+  for (const file of readdirSync(catalog).filter((name) => name.endsWith(".md")).toSorted()) {
+    try {
+      // install() answers "installed" or "unchanged" (same content already there) and throws on a refusal.
+      const { status } = install(join(catalog, file), { ...atril, kind: "command" });
+      if (status === "installed") installed += 1;
+      else unchanged += 1;
+    } catch (err) {
+      logger.warn(`kj: ${file} was not installed in ${ATRIL_ROOT}: ${err.message}`);
+    }
+  }
+  logger.info(`kj: ${installed} Karajan command(s) installed in ${ATRIL_ROOT}/commands, on demand (${unchanged} already there)`);
+  if (!detectRulesync(projectDir)) {
+    if (offerRulesync) logger.info(`kj: to reach every CLI through /atril, run rulesync init and then atril sync --root ${ATRIL_ROOT}`);
+    return { installed, synced: false };
+  }
+  try {
+    for (const { action, path } of sync(atril).filter((step) => step.action !== "unchanged")) logger.info(`kj: atril ${action} .rulesync/${path}`);
+    if (!generate(atril)) logger.info("kj: run rulesync generate to reach your agents, or declare rulesync.generate: true in .karajan/atril.json");
+  } catch (err) {
+    logger.warn(`kj: atril sync failed (${err.message}); fix it and run atril sync --root ${ATRIL_ROOT}`);
+    return { installed, synced: false };
+  }
+  return { installed, synced: true };
+}

package/src/commands/init.js

@@ -7,7 +7,7 @@ import { sonarUp, checkVmMaxMapCount } from "../sonar/manager.js";
 import { ollamaUp, waitForOllamaReady, normalizeOllamaConfig } from "../rag/ollama-manager.js";
 import { checkOllamaCapability, pullOllamaModel } from "../rag/ollama-capability.js";
 import { exists, ensureDir } from "../utils/fs.js";
-import { ensureContractBlockPresent } from "../review/gate-gitignore.js";
+import { ensureContractBlockPresent, ensureGateTrackable } from "../review/gate-gitignore.js";
 import { getKarajanHome } from "../utils/paths.js";
 import { getTemplatesRoot } from "../utils/templates-root.js";
 import { detectAvailableAgents } from "../utils/agent-detect.js";
@@ -28,6 +28,7 @@ import { registerQmdCollections } from "../utils/qmd-collection.js";
 import { isGitRepo } from "../harden/harden-engine.js";
 import { isPhoneEnrolled } from "../harden/phone-sign.js";
 import { identityCommand } from "./identity.js";
+import { installKarajanCommands } from "./init-atril.js";
 import { hardenCommand } from "./harden.js";
 import { contractChanges } from "../environment/contract-commit.js";
 import { detectProjectStack } from "../utils/stack-detect.js";
@@ -680,54 +681,22 @@ async function bootstrapOllama({ flags, config, logger, interactive }) {
   }
 }
 
-async function installSkills(logger, interactive) {
-  const projectDir = process.cwd();
-  const commandsDir = path.join(projectDir, ".claude", "commands");
-  const skillsTemplateDir = path.join(getTemplatesRoot(), "skills");
-
+// KJC-TSK-1219 (ADR 0021, step 15d): Karajan's commands go to atril's store, not .claude/commands.
+async function installSkills(logger, interactive, offerRulesync) {
   let doInstall = true;
   if (interactive) {
     const wizard = createWizard();
     try {
-      doInstall = await wizard.confirm("Install Karajan skills as slash commands (/kj-code, /kj-review, etc.)?", true);
+      doInstall = await wizard.confirm("Install Karajan's commands (kj-code, kj-review, kj-audit...) into atril's store, on demand?", true);
     } finally {
       wizard.close();
     }
   }
-
   if (!doInstall) {
-    logger.info("Skills installation skipped.");
-    return;
-  }
-
-  await ensureDir(commandsDir);
-
-  let installed = 0;
-  try {
-    const files = await fs.readdir(skillsTemplateDir);
-    for (const file of files) {
-      if (!file.endsWith(".md")) continue;
-      const src = path.join(skillsTemplateDir, file);
-      const dest = path.join(commandsDir, file);
-      if (await exists(dest)) {
-        logger.info(`  ${file} already exists — skipping`);
-        continue;
-      }
-      const content = await fs.readFile(src, "utf8");
-      await fs.writeFile(dest, content, "utf8");
-      installed += 1;
-    }
-  } catch (err) {
-    logger.warn(`Could not install skills: ${err.message}`);
+    logger.info("Karajan's commands skipped.");
     return;
   }
-
-  if (installed > 0) {
-    logger.info(`Installed ${installed} Karajan skill(s) in .claude/commands/`);
-    logger.info("Available as slash commands: /kj-run, /kj-code, /kj-review, /kj-test, /kj-security, /kj-discover, /kj-architect, /kj-sonar, /kj-rag-query");
-  } else {
-    logger.info("All skills already installed.");
-  }
+  installKarajanCommands({ projectDir: process.cwd(), logger, offerRulesync });
 }
 
 const GITIGNORE_ENTRIES = [
@@ -764,6 +733,8 @@ async function ensureGitignoreEntries(projectDir, logger) {
   // review-gate/hooks/adrs the whole team inherits (KJC-TSK-0646).
   const res = await ensureContractBlockPresent(projectDir);
   if (res.changed) logger.info("Added the .karajan contract block to .gitignore (verdicts stay local; gate/hooks/adrs tracked)");
+  // ADR 0032: an existing project gets the block completed with what the team now shares.
+  else if ((await ensureGateTrackable(projectDir)).changed) logger.info("Completed the .karajan contract block in .gitignore with the team's shared state (ADR 0032)");
 }
 
 /**
@@ -876,7 +847,7 @@ export async function initCommand({ logger, flags = {} }) {
   await ensureReviewRules(reviewRulesPath, logger);
   await ensureCoderRules(coderRulesPath, logger);
   await ensureGitignoreEntries(process.cwd(), logger);
-  await installSkills(logger, interactive);
+  await installSkills(logger, interactive, flags.rulesync !== false);
   await bootstrapOllama({ flags, config, logger, interactive });
 
   // Auto-detect project stack and preconfigure
@@ -1046,7 +1017,7 @@ export async function initCommand({ logger, flags = {} }) {
   logger.info(hardened || skipHarden
     ? "✓ Karajan is set up in this project."
     : "⚠ Karajan is set up EXCEPT the quality harness — without it there are no gates.");
-  logger.info('  Next:  kj run "describe what to build or fix"');
+  logger.info("  Next:  ask your agent for the work; it follows the method kj installed");
   logger.info("  More:  kj --help   ·   kj doctor (check your setup)");
 }
 

package/src/commands/install-tools.js

@@ -294,6 +294,74 @@ async function handleStandalone({ tool, standalone, manualUrl, dryRun, yes, logg
   return { tool, action: "failed", via: "binary", error: r.error };
 }
 
+// Sonar: plan the container, then start it on a yes.
+async function startSonar({ available, dryRun, yes, logger }) {
+  const result = await handleSonar({ available, dryRun });
+  if (result.action === "manual") logger.warn?.(`✗ sonar: ${result.reason}`);
+  else logger.info?.(`▸ sonar: ${result.command}`);
+  if (dryRun || result.action !== "ready") return result;
+  const proceed = yes || await promptYesNo(`Start SonarQube with: ${result.command}?`);
+  if (!proceed) return result;
+  const r = await runInstall(result.command);
+  result.action = r.ok ? "installed" : "failed";
+  if (!r.ok) result.error = r.error;
+  return result;
+}
+
+async function handleOptimizer({ tool, dryRun, yes, logger }) {
+  if (dryRun) {
+    logger.info?.(`▸ ${tool}: would install (init installer)`);
+    return { tool, action: "planned", command: `kj install-tools --only ${tool}` };
+  }
+  const proceed = yes || await promptYesNo(`Install ${tool}?`);
+  if (!proceed) return { tool, action: "declined" };
+  const install = await OPTIMIZER_INSTALLERS[tool]();
+  const r = await install(logger);
+  return r.ok ? { tool, action: "installed", version: r.version } : { tool, action: "failed", error: r.error };
+}
+
+// No package manager matched: try a standalone route (static binary for
+// osv-scanner, a concrete command for semgrep) before giving up.
+async function handleNoManager({ tool, hint, available, dryRun, yes, logger }) {
+  const standalone = resolveStandalone(tool, available);
+  if (standalone) return handleStandalone({ tool, standalone, manualUrl: hint.manualUrl, dryRun, yes, logger });
+  logger.warn?.(`✗ ${tool}: no automatic install route here. Run \`kj doctor\` for options, or install manually: ${hint.manualUrl}`);
+  return { tool, action: "manual", reason: "no compatible package manager found", manualUrl: hint.manualUrl, suggested: hint.command };
+}
+
+// semgrep / osv-scanner / lighthouse — package-manager driven.
+async function handlePackageManaged(ctx) {
+  const { tool, available, dryRun, yes, logger } = ctx;
+  const hint = await getInstallHint(tool, available);
+  if (!hint.command || !hint.manager) return handleNoManager({ ...ctx, hint });
+  if (dryRun) {
+    logger.info?.(`▸ ${tool}: would run \`${hint.command}\` (manager: ${hint.manager})`);
+    return { tool, action: "dry-run", command: hint.command, manager: hint.manager };
+  }
+  const proceed = yes || await promptYesNo(`Install ${tool} with: ${hint.command}?`);
+  if (!proceed) {
+    logger.info?.(`⊘ ${tool}: declined`);
+    return { tool, action: "declined", command: hint.command };
+  }
+  logger.info?.(`▸ ${tool}: running \`${hint.command}\`...`);
+  const r = await runInstall(hint.command);
+  if (r.ok) {
+    logger.info?.(`✓ ${tool}: installed via ${hint.manager}`);
+    return { tool, action: "installed", command: hint.command, manager: hint.manager };
+  }
+  logger.warn?.(`✗ ${tool}: install failed (${r.error})`);
+  return { tool, action: "failed", command: hint.command, error: r.error };
+}
+
+// Tools with their own route; any other one goes through the package manager.
+const TOOL_HANDLERS = {
+  sonar: startSonar,
+  git: handleGit,
+  "agent-cli": handleAgentCli,
+  docker: handleDocker,
+  ...Object.fromEntries(Object.keys(OPTIMIZER_INSTALLERS).map((tool) => [tool, handleOptimizer])),
+};
+
 /**
  * Plan + (optionally execute) the install of every requested tool.
  *
@@ -330,91 +398,8 @@ export async function installToolsCommand(opts = {}) {
       continue;
     }
 
-    if (tool === "sonar") {
-      const result = await handleSonar({ available, dryRun });
-      results.push(result);
-      if (result.action === "manual") logger.warn?.(`✗ sonar: ${result.reason}`);
-      else logger.info?.(`▸ sonar: ${result.command}`);
-      if (!dryRun && result.action === "ready") {
-        const proceed = yes || await promptYesNo(`Start SonarQube with: ${result.command}?`);
-        if (proceed) {
-          const r = await runInstall(result.command);
-          result.action = r.ok ? "installed" : "failed";
-          if (!r.ok) result.error = r.error;
-        }
-      }
-      continue;
-    }
-
-    if (OPTIMIZER_INSTALLERS[tool]) {
-      if (dryRun) {
-        results.push({ tool, action: "planned", command: `kj install-tools --only ${tool}` });
-        logger.info?.(`▸ ${tool}: would install (init installer)`);
-        continue;
-      }
-      const proceed = yes || await promptYesNo(`Install ${tool}?`);
-      if (!proceed) { results.push({ tool, action: "declined" }); continue; }
-      const install = await OPTIMIZER_INSTALLERS[tool]();
-      const r = await install(logger);
-      results.push(r.ok
-        ? { tool, action: "installed", version: r.version }
-        : { tool, action: "failed", error: r.error });
-      continue;
-    }
-
-    if (tool === "git") {
-      const result = await handleGit({ available, dryRun, yes, logger });
-      results.push(result);
-      continue;
-    }
-
-    if (tool === "agent-cli") {
-      const result = await handleAgentCli({ available, dryRun, yes, logger });
-      results.push(result);
-      continue;
-    }
-
-    if (tool === "docker") {
-      const result = await handleDocker({ available, dryRun, yes, logger });
-      results.push(result);
-      continue;
-    }
-
-    // semgrep / osv-scanner / lighthouse — package-manager driven.
-    const hint = await getInstallHint(tool, available);
-    if (!hint.command || !hint.manager) {
-      // No package manager matched — try a standalone route (static binary
-      // for osv-scanner, a concrete command for semgrep) before giving up.
-      const standalone = resolveStandalone(tool, available);
-      if (standalone) {
-        const result = await handleStandalone({ tool, standalone, manualUrl: hint.manualUrl, dryRun, yes, logger });
-        results.push(result);
-        continue;
-      }
-      results.push({ tool, action: "manual", reason: "no compatible package manager found", manualUrl: hint.manualUrl, suggested: hint.command });
-      logger.warn?.(`✗ ${tool}: no automatic install route here. Run \`kj doctor\` for options, or install manually: ${hint.manualUrl}`);
-      continue;
-    }
-    if (dryRun) {
-      results.push({ tool, action: "dry-run", command: hint.command, manager: hint.manager });
-      logger.info?.(`▸ ${tool}: would run \`${hint.command}\` (manager: ${hint.manager})`);
-      continue;
-    }
-    const proceed = yes || await promptYesNo(`Install ${tool} with: ${hint.command}?`);
-    if (!proceed) {
-      results.push({ tool, action: "declined", command: hint.command });
-      logger.info?.(`⊘ ${tool}: declined`);
-      continue;
-    }
-    logger.info?.(`▸ ${tool}: running \`${hint.command}\`...`);
-    const r = await runInstall(hint.command);
-    if (r.ok) {
-      results.push({ tool, action: "installed", command: hint.command, manager: hint.manager });
-      logger.info?.(`✓ ${tool}: installed via ${hint.manager}`);
-    } else {
-      results.push({ tool, action: "failed", command: hint.command, error: r.error });
-      logger.warn?.(`✗ ${tool}: install failed (${r.error})`);
-    }
+    const install = Object.hasOwn(TOOL_HANDLERS, tool) ? TOOL_HANDLERS[tool] : handlePackageManaged;
+    results.push(await install({ tool, available, dryRun, yes, logger }));
   }
 
   // KJC-TSK-0659 stop-on-sudo: anything that still needs the user's hands

package/src/commands/main-guard.js

@@ -0,0 +1,78 @@
+/**
+ * `kj main-guard` (KJC-TSK-1369, ADR 0037 layer 2): audits a push to the protected branch
+ * against GitHub and exits 1 with a markdown report when a merge skipped its required checks
+ * or the protection no longer enforces them on admins. The sealed workflow runs it on every
+ * push to main and posts the report as the alarm.
+ *
+ * Pull requests and check results are read with the token gh has (the workflow's GITHUB_TOKEN).
+ * Reading the branch protection needs Administration, so it uses MAIN_GUARD_PROTECTION_TOKEN,
+ * a read-only secret (the maintainer's choice, 2026-11-01).
+ */
+import { execFileSync } from "node:child_process";
+
+import { auditMain } from "../guards/main-guard.js";
+
+const NEW_BRANCH = /^0+$/;
+
+const gitIn = (projectDir) => (args) => execFileSync("git", ["-C", projectDir, ...args], { encoding: "utf8" });
+
+/** The commits the push put on the branch, newest first: its first-parent line. */
+export function pushedCommits({ before, after, git }) {
+  if (!before || NEW_BRANCH.test(before)) return [after];
+  return git(["rev-list", "--first-parent", `${before}..${after}`]).split("\n").filter(Boolean);
+}
+
+/** `gh api` as JSON; a token, when given, replaces gh's own for that call only. */
+function ghJson(path, token) {
+  const env = token ? { ...process.env, GH_TOKEN: token } : process.env;
+  return JSON.parse(execFileSync("gh", ["api", path], { encoding: "utf8", env, stdio: ["ignore", "pipe", "pipe"] }));
+}
+
+/** GitHub as main-guard's api. */
+export function githubApi({ repo, branch, protectionToken }) {
+  return {
+    // The commit's pull list leaves merged_by out; a merged one is read in full to name who merged it.
+    pullsOf: async (sha) => ghJson(`repos/${repo}/commits/${sha}/pulls`).map((p) => (p.merged_at ? ghJson(`repos/${repo}/pulls/${p.number}`) : p)),
+    async checksOf(sha) {
+      const runs = ghJson(`repos/${repo}/commits/${sha}/check-runs?per_page=100`).check_runs ?? [];
+      const statuses = ghJson(`repos/${repo}/commits/${sha}/status`).statuses ?? [];
+      return [...runs.map((r) => ({ name: r.name, conclusion: r.conclusion })), ...statuses.map((s) => ({ name: s.context, conclusion: s.state }))];
+    },
+    async protection() {
+      if (!protectionToken) throw new Error("main-guard: MAIN_GUARD_PROTECTION_TOKEN is not set; the protection cannot be read");
+      try {
+        return ghJson(`repos/${repo}/branches/${encodeURIComponent(branch)}/protection`, protectionToken);
+      } catch (err) {
+        if (/Branch not protected/i.test(`${err.stdout ?? ""}${err.stderr ?? ""}`)) return null;
+        throw err;
+      }
+    },
+  };
+}
+
+/** The alarm as markdown. */
+export function renderReport(result, { repo, branch }) {
+  if (result.ok) return `main-guard: nothing reached ${branch} without its checks, and the protection of ${repo} is as declared.`;
+  const lines = [`## main-guard: ${repo}@${branch} needs a look`, ""];
+  for (const m of result.merges) {
+    lines.push(m.kind === "direct-push"
+      ? `- \`${m.sha.slice(0, 7)}\`: direct push, ${m.detail}`
+      : `- \`${m.sha.slice(0, 7)}\`: PR #${m.pr} merged by @${m.mergedBy} without ${m.missing.join(", ")}`);
+  }
+  for (const change of result.protection) lines.push(`- protection: ${change}`);
+  return lines.join("\n");
+}
+
+/** @returns {Promise<number>} the exit code */
+export async function runMainGuard({ repo, branch, before, after, require, git, audit = auditMain, api, print = console.log }) {
+  const commits = pushedCommits({ before, after, git });
+  const result = await audit({ branch, commits, requiredChecks: require, api });
+  print(renderReport(result, { repo, branch }));
+  return result.ok ? 0 : 1;
+}
+
+export async function mainGuardCommand({ flags, projectDir = process.cwd() }) {
+  const { repo, branch, before, after } = flags;
+  const api = githubApi({ repo, branch, protectionToken: process.env.MAIN_GUARD_PROTECTION_TOKEN });
+  process.exitCode = await runMainGuard({ repo, branch, before, after, require: flags.require, git: gitIn(projectDir), api });
+}