@karajan-family/code 4.31.1 → 4.33.0

package/src/checks/action-pins.js

@@ -0,0 +1,131 @@
+/**
+ * KJC-TSK-0870 — the maintenance that pinning moved onto kj.
+ *
+ * Issue #1374 was right: `kj harden` generated workflows with moving tags
+ * (`actions/checkout@v4`), and kj's own `kj audit --security` flagged them, so
+ * five of the project's seven warnings came from files kj had just written.
+ * They are pinned to commit SHAs now.
+ *
+ * Pinning trades one risk for another: nobody can move the tag under you, and
+ * nobody delivers the upstream patch either. A pin that nobody revisits is a
+ * vulnerability with a long shelf life, and since kj writes those lines, kj is
+ * the one that has to notice. That is this check.
+ *
+ * It lives in `kj doctor` (a person asking about their environment) and NOT in
+ * `kj check` (a gate that CI runs): a gate that needs the network is a gate
+ * that fails on a plane, and turning red over an unreachable API is how a gate
+ * loses its credibility.
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+import { PINNED_ACTIONS } from "../harden/workflow-templates.js";
+
+const execFileAsync = promisify(execFile);
+// Nobody waits for a diagnostic. Both clients are capped, and the pins are
+// asked in parallel, so an unreachable GitHub costs one timeout and not one
+// per action.
+const CALL_TIMEOUT_MS = 5_000;
+
+const STRATEGY_MANUAL = "manual";
+const API = "https://api.github.com/repos";
+
+/** `owner/repo@sha # tag` as written in the templates. */
+export function parsePin(pin) {
+  const m = /^([^@\s]+)@([0-9a-f]{40})\s*#\s*(\S+)$/i.exec(String(pin || "").trim());
+  return m ? { action: m[1], sha: m[2].toLowerCase(), tag: m[3] } : null;
+}
+
+const SHA_RE = /^[0-9a-f]{40}$/;
+const clean = (s) => String(s || "").trim().toLowerCase();
+
+/**
+ * The SHA a tag points at today, asked through `gh` when it is there.
+ *
+ * Measured, not assumed: plain unauthenticated `fetch` answered 403 on the
+ * first real run, because GitHub allows 60 calls an hour PER IP and any shared
+ * or NAT-ed address burns that between everyone behind it. A check that
+ * answers "could not check" almost always is decorative. `gh` carries the
+ * user's own credentials (5000/hour) and kj already relies on it elsewhere;
+ * `fetch` stays as the fallback for whoever has no gh.
+ *
+ * @returns {Promise<string|null>} null when the answer cannot be trusted.
+ */
+export async function currentSha(action, tag, { fetchFn = fetch, ghFn = ghSha } = {}) {
+  const viaGh = await ghFn(action, tag);
+  if (viaGh) return viaGh;
+  const res = await fetchFn(`${API}/${action}/commits/${encodeURIComponent(tag)}`, {
+    headers: { Accept: "application/vnd.github.sha", "User-Agent": "karajan-code" },
+    signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+  });
+  if (!res?.ok) return null;
+  const body = clean(await res.text());
+  return SHA_RE.test(body) ? body : null;
+}
+
+/** @returns {Promise<string|null>} null when gh is absent, unauthenticated or unhappy. */
+async function ghSha(action, tag) {
+  try {
+    const { stdout } = await execFileAsync("gh", ["api", `repos/${action}/commits/${tag}`, "--jq", ".sha"], {
+      encoding: "utf8",
+      timeout: CALL_TIMEOUT_MS,
+    });
+    const sha = clean(stdout);
+    return SHA_RE.test(sha) ? sha : null;
+  } catch {
+    return null;
+  }
+}
+
+/** @internal Exported for dynamic import from tests. */
+export function createActionPinsCheck({ pins = PINNED_ACTIONS, deps = {} } = {}) {
+  return {
+    name: "action-pins",
+    label: "actions fijadas por SHA",
+    strategy: STRATEGY_MANUAL,
+    describe: "Detect a pinned GitHub Action whose tag has moved on without it",
+    async detect() {
+      const entries = Object.entries(pins).map(([key, pin]) => ({ key, ...(parsePin(pin) || {}) }));
+      const malformed = entries.filter((e) => !e.sha);
+      const asked = await Promise.all(
+        entries.filter((x) => x.sha).map(async (e) => {
+          // offline, rate limited, DNS down, gh missing: not an answer
+          const latest = await currentSha(e.action, e.tag, deps).catch(() => null);
+          return { ...e, latest };
+        }),
+      );
+      const stale = asked.filter((e) => e.latest && e.latest !== e.sha);
+      const unchecked = asked.filter((e) => !e.latest).length;
+
+      if (malformed.length > 0) {
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `pin mal formado: ${malformed.map((m) => m.key).join(", ")} — un pin que no se puede leer no se puede comprobar`,
+          fix: "revisa PINNED_ACTIONS en src/harden/workflow-templates.js: owner/repo@<sha de 40> # <tag>",
+        };
+      }
+      if (stale.length > 0) {
+        return {
+          ok: false,
+          severity: "warn",
+          detail: stale.map((s) => `${s.action} ${s.tag} apunta hoy a ${s.latest.slice(0, 12)} y kj fija ${s.sha.slice(0, 12)}`).join(" · "),
+          fix: stale.map((s) => `${s.action}@${s.latest} # ${s.tag}`).join("  ·  "),
+        };
+      }
+      // Never claim what was not looked at (the card's own acceptance
+      // criterion): an unreachable API is said, not passed off as green.
+      if (unchecked > 0) {
+        return {
+          ok: true,
+          severity: "info",
+          detail: unchecked === entries.length
+            ? "no se pudo comprobar ninguna action (¿sin red o con la API de GitHub limitando?)"
+            : `${unchecked} action(s) sin comprobar (¿sin red o con la API de GitHub limitando?)`,
+        };
+      }
+      return { ok: true, severity: "info", detail: `${entries.length} action(s) fijadas y al día` };
+    },
+  };
+}

package/src/checks/project-checks.js

@@ -23,6 +23,8 @@ import { runCommand } from "../utils/process.js";
 import { checkBinary } from "../utils/agent-detect.js";
 import { getInstallCommand } from "../utils/os-detect.js";
 import { STRATEGY } from "./types.js";
+import { createRepoStateCheck } from "./repo-state.js";
+import { createActionPinsCheck } from "./action-pins.js";
 
 /**
  * Detect signals del proyecto. Devuelve un set de tags con qué hay en el
@@ -241,5 +243,14 @@ export function getProjectChecks({ projectDir }) {
     createToolCheck({ signal: "terraform", tool: "terraform", label: "Terraform (project signal)", signals }),
     createEnvConsistencyCheck({ projectDir, signals }),
     createGhRemoteCheck({ projectDir }),
+    // BOOT-B (KJC-TSK-0858): the state of the repo itself, which no other
+    // check looks at — the order it was set up in, whether the contract
+    // travels, whether this clone declares who works it.
+    createRepoStateCheck({ projectDir }),
+    // KJC-TSK-0870: pinning the actions by SHA (issue #1374) moved their
+    // maintenance onto kj. Doctor asks upstream whether a tag has moved on
+    // without its pin; `kj check` deliberately does not, because a gate that
+    // needs the network is a gate that fails on a plane.
+    createActionPinsCheck(),
   ];
 }

package/src/checks/repo-state.js

@@ -0,0 +1,89 @@
+/**
+ * BOOT-B (KJC-TSK-0858, epic KJC-PCS-0088) — the state of the REPOSITORY.
+ *
+ * The cold-start map of 20-sep found projects raised outside the method, and
+ * nobody noticed until a gate blocked with no explanation: the harness
+ * installed before git, the gate marker never committed (so a clone inherits
+ * nothing), no identity declared (so the Sentinel later denies every git and
+ * gh call). None of the other checks looks at this: they check tools, ports,
+ * index coverage, the method's own report — never whether the repo itself was
+ * set up in the right order.
+ *
+ * Two rules, both learned the hard way in this codebase:
+ *  - The bootstrap phase is NOT a defect. A repo with no commit yet is
+ *    starting, and saying otherwise is the false alarm that teaches people to
+ *    ignore the output.
+ *  - Every symptom carries the literal command that repairs it. A diagnosis
+ *    nobody can act on is a complaint.
+ */
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+const STRATEGY_MANUAL = "manual";
+
+const git = (projectDir, args) => execFileSync("git", ["-C", projectDir, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+const gitOk = (projectDir, args) => { try { git(projectDir, args); return true; } catch { return false; } };
+
+/** @internal Exported for dynamic import from tests. */
+export function createRepoStateCheck({ projectDir }) {
+  return {
+    name: "repo-state",
+    label: "estado del repositorio",
+    strategy: STRATEGY_MANUAL,
+    describe: "Detect a project raised or carried outside the method (order, contract, identity)",
+    async detect() {
+      const dir = projectDir;
+      const has = (rel) => existsSync(join(dir, rel));
+      const hardened = has(".karajan/hooks/pre-commit") || has(".karajan/review-gate");
+
+      // 1. No repository. The gates live in git hooks, so there is nothing to
+      //    govern yet — and if the harness is already there, it governs nothing.
+      if (!has(".git")) {
+        return {
+          ok: false,
+          severity: "warn",
+          detail: hardened
+            ? "el proyecto está sin repositorio y el harness ya está escrito: no gobierna nada"
+            : "el proyecto está sin repositorio, así que ningún gate del método puede actuar",
+          fix: "kj bootstrap (crea el repositorio y deja el método en orden), o git init si prefieres hacerlo a mano",
+        };
+      }
+
+      // 2. The harness written before git existed: nothing tracks the contract,
+      //    so cloning inherits nothing even though this clone looks hardened.
+      const hasCommits = gitOk(dir, ["rev-parse", "--verify", "HEAD"]);
+      if (!hasCommits) {
+        return hardened
+          ? { ok: true, severity: "info", detail: "fase de arranque: el método está escrito y falta el primer commit" }
+          : { ok: true, severity: "info", detail: "fase de arranque: repositorio recién creado, sin método todavía" };
+      }
+
+      const symptoms = [];
+      // Against HEAD, not the index (catch de codex): a file merely STAGED is
+      // not inherited by a clone, which is the whole point of this symptom.
+      const committed = (rel) => gitOk(dir, ["cat-file", "-e", `HEAD:${rel}`]);
+      if (hardened && !committed(".karajan/review-gate") && !committed(".karajan/hooks/pre-commit")) {
+        symptoms.push({
+          detail: "el harness está instalado pero su contrato no está en git: quien clone no hereda ningún gate",
+          fix: "git add .karajan/review-gate .karajan/hooks && git commit -m \"chore: el contrato del método\"",
+        });
+      }
+      if (hardened && !has(".karajan/identity.local.yml")) {
+        symptoms.push({
+          detail: "este clon no declara identidad, y el Sentinel denegará cada git y cada gh hasta que la declares",
+          fix: "kj identity set --gh <usuario> --email <correo>",
+        });
+      }
+
+      if (symptoms.length === 0) return { ok: true, severity: "info", detail: "el repositorio está en orden" };
+      return {
+        ok: false,
+        severity: "warn",
+        detail: symptoms.map((s) => s.detail).join(" · "),
+        fix: symptoms.map((s) => s.fix).join("  ·  "),
+      };
+    },
+  };
+}

package/src/cli/register-pipeline.js

@@ -179,11 +179,21 @@ export function registerPipeline(program, { pkgVersion }) {
     .argument("[task]", "Task description (REQUIRED — provide as argument or via --task-file)")
     .option("--task-file <path>", "Read the task from a file (e.g. .md)")
     .option("--coder <name>")
+    // KJC-TSK-0864: --coder is the pipeline's word for it, --agent is the
+    // session's. Same knob, two vocabularies; naming both and disagreeing is
+    // an error, never a silent precedence.
+    .option("--agent <name>", "The agent that writes (alias of --coder)")
+    .option("--card <ref>", "Card/HU the work belongs to — its statement and criteria reach the coder")
     .option("--coder-model <name>")
     .action(async (task, flags) => {
+      if (flags.agent && flags.coder && flags.agent !== flags.coder) {
+        console.error(`kj code: --agent ${flags.agent} and --coder ${flags.coder} name different agents — pick one`);
+        process.exit(2);
+      }
+      if (flags.agent) flags.coder = flags.agent;
       await withConfig(pkgVersion, "code", flags, async ({ config, logger }) => {
         const resolvedTask = await resolveTaskInput({ task, taskFile: flags.taskFile, projectDir: config.projectDir, logger });
-        await codeCommand({ task: resolvedTask, config, logger });
+        await codeCommand({ task: resolvedTask, config, logger, flags });
       });
     });
 
@@ -239,6 +249,10 @@ export function registerPipeline(program, { pkgVersion }) {
     .option("--prune-days <n>", "TTL in days for --prune (default: 14)")
     .option("--dry-run", "With --prune: report what would be removed without deleting")
     .option("--no-sonar", "Skip the deterministic Sonar pre-gate that runs before the cross-AI verdict")
+    // BOOT-D (KJC-TSK-0863): how the walkthrough gets INTO the verdict. Without
+    // this the rule could only complain, which is the gate with no exit.
+    .option("--walked <route>", "Recorrido comprobado como lo haría una persona (repetible) — queda en el veredicto", (v, prev) => [...(prev || []), v], [])
+    .option("--walked-with <tool>", "Con qué se comprobó el recorrido (por ejemplo chrome-devtools)")
     .action(async (task, flags) => {
       await withConfig(pkgVersion, "review", flags, async ({ config, logger }) => {
         // ENV-B1 (KJC-TSK-0637): the gate mode records a verdict tied to

package/src/commands/bootstrap.js

@@ -15,16 +15,38 @@
  *    first and a git that cannot run is the end of the line, not a warning.
  */
 
+import { execFileSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { ensureGitRepo } from "./init.js";
 import { initCommand } from "./init.js";
 import { envInstallCommand } from "./env.js";
+import { runStartScript, START_SCRIPT_CONTRACT } from "../start/project-script.js";
 
 const STEP_LABEL = {
   git: "repositorio",
   config: "configuración del proyecto",
   method: "método activo (harness, gate y RAG)",
+  contract: "commit del contrato",
+  start: "arranque del proyecto",
+};
+
+/** What kj generates and the whole team must inherit by cloning. */
+const CONTRACT_PATHS = [
+  ".gitignore",
+  ".karajan/hooks",
+  ".karajan/review-gate",
+  ".karajan/adrs",
+  ".karajan/policy.yml",
+  ".claude",
+  "CLAUDE.md",
+  "AGENTS.md",
+  "GEMINI.md",
+];
+const CONTRACT_MESSAGE = "chore(bootstrap): el contrato del método, para que quien clone lo herede";
+
+const hasCommits = (projectDir, git) => {
+  try { git(["rev-parse", "--verify", "HEAD"]); return true; } catch { return false; }
 };
 
 /**
@@ -71,5 +93,39 @@ export async function bootstrapCommand({ config = {}, logger = console, flags =
     say("method", "done");
   }
 
+  // 4. The contract commit. project-new.md asked the USER for it, and it was
+  //    the commit their own freshly installed gates rejected: the review gate
+  //    (KJC-BUG-0165) and the branch guard (KJC-BUG-0186) both exempt it now,
+  //    so kj can make it itself instead of leaving the person to fight it.
+  //    Only what kj generated, only while the repo has no commit, never the
+  //    person's own code. This is NOT the supervisor seal, which stays a human
+  //    act with its own four layers (ADR 0009).
+  const git = deps.gitRun ?? ((args) => execFileSync("git", args, { cwd: projectDir, encoding: "utf8" }));
+  if (hasCommits(projectDir, git)) say("contract", "already", "el repositorio ya tiene historia");
+  else {
+    const present = CONTRACT_PATHS.filter((p) => existsSync(join(projectDir, p)));
+    if (present.length === 0) say("contract", "already", "no hay contrato que commitear");
+    else {
+      try {
+        git(["add", "--", ...present]);
+        git(["commit", "-m", CONTRACT_MESSAGE]);
+      } catch (err) {
+        // Nunca explotar aquí: lo más probable es que falte la identidad del
+        // clon, y ese cauce ya lo pide el paso anterior (KJC-BUG-0188).
+        return stop("contract", `git no pudo commitear el contrato: ${String(err.message).split("\n")[0]}`);
+      }
+      say("contract", "done", `${present.length} ruta(s) del contrato`);
+    }
+  }
+
+  // 5. Does the project actually run? kj verified the method; nobody verified
+  //    the application (BOOT-C, KJC-TSK-0862). It REPORTS, never blocks: a
+  //    start script written badly must not stop work over something unrelated,
+  //    and a tree that was already broken has to be said BEFORE implementing.
+  const start = await (deps.start ?? runStartScript)({ projectDir, config });
+  if (start.status === "absent") say("start", "already", `sin guion de arranque — ${START_SCRIPT_CONTRACT}`);
+  else if (start.status === "ok") say("start", "done", "el proyecto arranca y su humo pasa");
+  else say("start", "already", `el árbol YA venía roto (${start.status}) — no lo ha causado este trabajo`);
+
   return { ok: true, pending: null, steps };
 }

package/src/commands/check.js

@@ -9,6 +9,7 @@ import { collectMethodStats, formatMethodStats } from "../checks/method.js";
 import { createRagCoverageCheck } from "../checks/rag-coverage.js";
 import { checkAiSurface, formatAiSurface } from "../checks/ai-surface.js";
 import { detectObservedAgents } from "../utils/agent-detect.js";
+import { panelSummary } from "../environment/panel.js";
 import { loadConfig } from "../config.js";
 
 export async function checkCommand({ projectDir = process.cwd(), profile = "standard", json = false, logger = console } = {}) {
@@ -44,6 +45,10 @@ export async function checkCommand({ projectDir = process.cwd(), profile = "stan
   if (method) logger.info?.(`  method: ${formatMethodStats(method)}`);
   logger.info?.(`  ${ragCoverage.ok ? "✓" : "✗"} rag-coverage: ${ragCoverage.detail}`);
   if (aiSurface) logger.info?.(`  ${formatAiSurface(aiSurface)}`);
+  // KJC-TSK-0865: who writes and who reviews is the user's choice, so it is
+  // said out loud next to everything else that describes the project. Never
+  // a check: it has no ok/fail, it informs.
+  logger.info?.(`  ${panelSummary(config)}`);
   if (ok) logger.info?.("Harness OK.");
   else if (result.ok) logger.info?.("RAG index drift detected — a gate cannot protect what it cannot see.");
   else logger.info?.("Harness drift detected — run `kj harden` to repair.");

package/src/commands/code.js

@@ -2,13 +2,35 @@ import fs from "node:fs/promises";
 import { createAgent } from "../agents/index.js";
 import { assertAgentsAvailable } from "../agents/availability.js";
 import { buildCoderPrompt } from "../prompts/coder.js";
+import { resolveCardContext } from "../prompts/card-context.js";
+import { composeTask, resolveRagContext } from "../prompts/session-context.js";
 import { resolveRole } from "../config.js";
+import { withBrainRecovery, DEFAULT_RECOVERY_POLICY } from "../brain/with-brain-recovery.js";
+import { buildRoleFallbackChain } from "../brain/role-fallback-chain.js";
+import { ERROR_CLASS } from "../brain/agent-error-classifier.js";
+
+// KJC-TSK-0859: the agents no longer substitute a dead model behind your back,
+// so the command needs the declared chain. A one-shot CLI must not inherit the
+// pipeline's standby either: sleeping five hours inside `kj code` would be
+// worse than the failure. A quota wall takes the next candidate at once, and
+// with none left it stops and says what it tried.
+const ONE_SHOT_POLICY = Object.freeze({
+  ...DEFAULT_RECOVERY_POLICY,
+  classes: {
+    ...DEFAULT_RECOVERY_POLICY.classes,
+    [ERROR_CLASS.QUOTA_EXHAUSTED_DAILY]: { mode: "abort", maxRetries: 0, fallbackEligible: true, fallbackImmediate: true },
+    [ERROR_CLASS.QUOTA_EXHAUSTED_MONTHLY]: { mode: "abort", maxRetries: 0, fallbackEligible: true, fallbackImmediate: true },
+  },
+});
 import { withCliRunLog } from "../utils/cli-run-log.js";
 import { createCliProgressReporter } from "../utils/cli-progress.js";
 
-export async function codeCommand({ task, config, logger }) {
+export async function codeCommand({ task, config, logger, flags = {} }) {
   return withCliRunLog("code", { projectDir: config?.projectDir, logger }, async ({ runLog }) => {
     const coderRole = resolveRole(config, "coder");
+    // KJC-TSK-0864: no quota, not authenticated or simply absent? This THROWS
+    // with the agent named. The one thing it never does is quietly fall back
+    // to whoever happens to be reachable.
     await assertAgentsAvailable([coderRole.provider]);
     logger.info(`Coder (${coderRole.provider}) starting...`);
     runLog.logText(`[coder] provider=${coderRole.provider}`);
@@ -21,11 +43,39 @@ export async function codeCommand({ task, config, logger }) {
         try { coderRules = await fs.readFile("coder-rules.md", "utf8"); } catch { /* no coder rules file */ }
       }
     }
-    const prompt = await buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology || "tdd" });
+    const card = await resolveCardContext({ projectDir: config.projectDir, ref: flags.card || null });
+    if (card?.external) logger.warn(`card ${card.huId} lives on a board kj cannot read — passing the reference, not its text`);
+    else if (card) logger.info(`Card ${card.huId}: ${card.title}`);
+    // The method's first invariant is that the RAG answers before you assume.
+    // The session asks on the coder's behalf: a subprocess coder cannot run
+    // `kj rag query` itself, so it used to guess the codebase instead.
+    const rag = await resolveRagContext({ task, config, logger });
+    // The pipeline always passed projectDir (it arms the directory-boundary
+    // rule and the skills section) and the provider. `kj code` did not, so the
+    // declared coder got a weaker prompt from the session than from `kj run`.
+    const prompt = await buildCoderPrompt({
+      task: composeTask(task, [card?.section, rag?.section]),
+      coderRules,
+      methodology: config.development?.methodology || "tdd",
+      projectDir: config.projectDir,
+      provider: coderRole.provider,
+      huId: card?.huId ?? null,
+      acceptanceTests: card?.acceptanceTests ?? null,
+      serenaEnabled: Boolean(config.serena?.enabled),
+      rtkAvailable: Boolean(config.rtk?.available),
+    });
     const progress = createCliProgressReporter({ role: "coder" });
     let result;
     try {
-      result = await coder.runTask({ prompt, onOutput: progress.onOutput, role: "coder" });
+      result = await withBrainRecovery({
+        agent: { runTask: (args) => coder.runTask(args), provider: coderRole.provider, model: coderRole.model },
+        taskArgs: { prompt, onOutput: progress.onOutput, role: "coder" },
+        role: "coder",
+        provider: coderRole.provider,
+        logger,
+        policy: ONE_SHOT_POLICY,
+        fallback: buildRoleFallbackChain({ config, role: "coder", logger }),
+      });
       progress.finish(result.ok ? "done" : "failed");
     } catch (err) { progress.finish("failed"); throw err; }
     if (!result.ok) {
@@ -39,7 +89,10 @@ export async function codeCommand({ task, config, logger }) {
       logger.warn(result.error);
     }
     logger.info(`Coder completed (exit ${result.exitCode})`);
+    // The work is in the tree, not committed: the gate is the next step and a
+    // DIFFERENT AI runs it. Saying so here is what keeps the panel honest.
+    logger.info(`The work is in the tree. Review it before committing: kj review --staged (a different AI than ${coderRole.provider}).`);
     runLog.logText(`[coder] finished (exit=${result.exitCode})`);
-    return { ok: true };
+    return { ok: true, provider: coderRole.provider, card: card?.huId ?? null, ragSources: rag?.sources ?? [] };
   });
 }

package/src/commands/env.js

@@ -71,6 +71,7 @@ export async function envInstallCommand({ config = null, logger = null, flags =
     projectDir, target: flags.target || "all",
     stateBackend: config?.state_backend || "hu-board",
     boardName: config?.board?.name || null,
+    config, // KJC-TSK-0865: the panel travels with the method
   });
   console.log(`✓ Karajan playbook installed in: ${result.files.join(", ")}`);
 
@@ -213,7 +214,7 @@ export async function envInstallCommand({ config = null, logger = null, flags =
     // CLAUDE.md, but the running session loaded its context BEFORE — nobody
     // re-reads it. Print the method so it enters THIS conversation now.
     console.log("\n— The Karajan method below is IN EFFECT from this very message. If your session started before this install, apply it from now on:\n");
-    console.log(renderPlaybook({ stateBackend: config?.state_backend || "hu-board", boardName: config?.board?.name || null }));
+    console.log(renderPlaybook({ stateBackend: config?.state_backend || "hu-board", boardName: config?.board?.name || null, config }));
   }
   return result;
 }

package/src/commands/go.js

@@ -12,8 +12,7 @@ import path from "node:path";
 import { spawn } from "node:child_process";
 import { checkBinary } from "../utils/agent-detect.js";
 import { createCliAskQuestion } from "../utils/cli-ask-question.js";
-import { envInstallCommand } from "./env.js";
-import { ensureGitRepo } from "./init.js";
+import { bootstrapCommand } from "./bootstrap.js";
 import { boardCommand } from "./board.js";
 // The interactive launchers a muggle can live inside (v1: the two the epic
 // names). Auth heuristics are the same cheap file checks reviewer-fallback
@@ -44,9 +43,6 @@ export function buildGoPrompt() {
     "Empieza presentándote en dos frases y preguntando qué quiere construir o cambiar hoy.",
   ].join("\n");
 }
-async function defaultPrepare({ config, logger }) {
-  return envInstallCommand({ config, logger, flags: { yes: true } });
-}
 export async function defaultBoard({ config, logger, runBoard = boardCommand, openPath = "/?maggle=1" }) {
   const port = config.hu_board?.port || 4000;
   await runBoard({ action: "start", port, bind: "127.0.0.1", logger });
@@ -96,14 +92,17 @@ export async function goCommand({ config = {}, logger = console, flags = {}, dep
   // Prepare ONCE: decisions already taken are never re-asked.
   if (!existsSync(path.join(projectDir, ".karajan", "review-gate"))) {
     logger.info?.("Preparando tu proyecto (solo la primera vez)…");
-    // KJC-BUG-0191: empezar en una carpeta vacía es lo natural, y kj env
-    // install se niega a correr sin repositorio. Lo creamos nosotros.
-    if (!ensureGitRepo({ projectDir, logger })) {
-      logger.error?.("No he podido preparar el control de versiones de tu proyecto (git). Instálalo y vuelve a escribir: kj go");
+    // BOOT-A paso 3 (KJC-TSK-0857): el orden vive en UN sitio, kj bootstrap.
+    // Antes esta puerta cableaba su propia secuencia (git init y env install),
+    // así que la puerta del maggle y la técnica podían separarse sin que nadie
+    // se diera cuenta. Ahora las dos hacen lo mismo.
+    const booted = await (deps.bootstrap ?? bootstrapCommand)({ config, logger, flags: {}, deps: {} });
+    if (!booted.ok) {
+      logger.error?.(`Falta una cosa que solo puedes hacer tú, la tienes justo arriba (${booted.pending}). Cuando la hagas, vuelve a escribir: kj go`);
       process.exitCode = 1;
       return 1;
     }
-    const prepared = await (deps.prepare ?? defaultPrepare)({ config, logger });
+    const prepared = deps.prepare ? await deps.prepare({ config, logger }) : null;
     // Algo depende de tus manos (arriba tienes el detalle). Sin eso el
     // proyecto quedaría a medias, así que paramos aquí en vez de seguir.
     if (prepared?.exitCode) {

package/src/commands/harden.js

@@ -171,7 +171,9 @@ export async function hardenCommand({
     ? installWorkflows({ projectDir, language: roots[0]?.language ?? null, profile, mutation, dryRun })
     : null;
   const withGuidelines = guidelines && profile !== "minimal";
-  const gl = withGuidelines ? installGuidelines({ projectDir, dryRun }) : null;
+  // KJC-BUG-0199 (issue #1773): the same detected language the workflows and
+  // the configs already use — a Python project must not be told to use `const`.
+  const gl = withGuidelines ? installGuidelines({ projectDir, language: roots[0]?.language ?? null, dryRun }) : null;
   const out = {
     ok: true,
     ...result,

package/src/commands/review-gate.js

@@ -15,12 +15,14 @@ import { ensureGateTrackable } from "../review/gate-gitignore.js";
 import { runSonarPregate, formatSonarFinding, addedLinesByFile } from "../review/sonar-pregate.js";
 import { checkSonarRequirement, SONAR_RULE_ID } from "../review/sonar-requirement.js";
 import { checkRagRequirement, checkRagVerdict, ragBlock, RAG_RULE_ID } from "../review/rag-requirement.js";
+import { checkUiEvidence, uiBlock } from "../review/ui-evidence.js";
 import { readRagLedger } from "../review/rag-ledger.js";
 import { runMutationPregate, formatSurvivor } from "../review/mutation-pregate.js";
 import { checkCardFirst } from "../review/card-first.js";
 import { liftSealedSupervisorViolations } from "../policy/supervisor-verify.js";
 import { checkTestsWithCode } from "../review/tests-with-code.js";
 import { loadPrivacyList, scanText } from "../privacy/scan.js";
+import { isGeneratedPath, splitAddedByFile } from "../privacy/diff-scope.js";
 import { checkStagedDiff, loadPolicy } from "../policy/engine.js";
 import { loadStandingExceptions, recordPolicyException } from "../policy/exceptions.js";
 import { policyFileHash, recordGateDecision } from "../policy/decisions.js";
@@ -229,17 +231,24 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   // don't publish. In the SEA binary the privacy module is stubbed and
   // throws: the gate degrades with a note instead of crashing.
   try {
-    const added = diff.split("\n").filter((l) => l.startsWith("+") && !l.startsWith("+++")).map((l) => l.slice(1)).join("\n");
-    const findings = scanText(added, { list: loadPrivacyList(), source: "<staged diff>" });
+    // KJC-BUG-0203: per file, so a finding can name where it lives and so
+    // build output is judged as what it is. Generic heuristics are silenced
+    // there (nobody typed a minified bundle); a denylist hit is not, because
+    // the incident behind this scanner was personal data inside a build.
+    const list = loadPrivacyList();
+    const findings = splitAddedByFile(diff).flatMap(({ file, added }) => {
+      const found = scanText(added, { list, source: file });
+      return isGeneratedPath(file) ? found.filter((f) => f.severity === "block") : found;
+    });
     const blocks = findings.filter((f) => f.severity === "block");
     const warns = findings.filter((f) => f.severity === "warn");
-    for (const f of warns) console.log(`⚠ privacy: [${f.type}] added line ${f.line} → ${f.masked} — personal data? move it out before it ships`);
+    for (const f of warns) console.log(`⚠ privacy: [${f.type}] ${f.source}:${f.line} → ${f.masked} — personal data? move it out before it ships`);
     const hardened = config?.privacy?.generic === "block" && warns.length > 0;
     if (blocks.length > 0 || hardened) {
       if (process.env.KJ_ALLOW_PII === "1") {
         console.log(`⚠ privacy exempt: ${blocks.length} denylist hit(s) — KJ_ALLOW_PII=1 (explicit escape hatch)`);
       } else {
-        for (const f of blocks) console.log(`✗ privacy: [${f.type}] on added line ${f.line} → ${f.masked}`);
+        for (const f of blocks) console.log(`✗ privacy: [${f.type}] ${f.source}:${f.line} → ${f.masked}`);
         const reason = `${blocks.length || warns.length} personal-data finding(s) in the staged diff — this must not reach the repo (KJ_ALLOW_PII=1 to override consciously)`;
         console.log(`✗ privacy gate: ${reason}`);
         process.exitCode = 1;
@@ -482,6 +491,20 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
       + twins.map((t) => `- ${t}`).join("\n");
   }
 
+  // BOOT-D (KJC-TSK-0863): green is not proof for what a person SEES. kj does
+  // not drive the browser (the host has it); it demands the walkthrough and
+  // records it in the verdict, bound to the diff like sonar and rag. It WARNS:
+  // the last proof, never the only one, and a gate that fires often teaches
+  // people to skip gates.
+  const walked = Array.isArray(flags.walked) ? flags.walked : [];
+  const uiReq = checkUiEvidence({
+    stagedFiles: changedFiles,
+    evidence: walked.length > 0 ? { walked, tool: flags.walkedWith ?? null } : null,
+    standingExceptions: std.standing,
+  });
+  if (uiReq.warn) console.log(`⚠ ${uiReq.reason}`);
+  const uiRecord = uiBlock(uiReq);
+
   // MUT-A (KJC-TSK-0716): mutation pre-gate — opt-in (method_gates.mutation),
   // SOLO en --staged (jamás en pre-commit: cuesta minutos; y jamás en --range:
   // el scope es el ÍNDICE y anotaría trabajo ajeno — catch de codex). block
@@ -504,7 +527,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
     }
   }
 
-  const record = await runOneShotReview({ diff, task, config, logger, projectDir, sonar: sonarRecord, rag: ragRecord });
+  const record = await runOneShotReview({ diff, task, config, logger, projectDir, sonar: sonarRecord, rag: ragRecord, ui: uiRecord });
   printVerdict(record);
   process.exitCode = record.verdict === "approved" ? 0 : 1;
   return record;