karajan-code 4.22.0 → 4.24.0

package/src/audit/dead-exports.js

@@ -16,6 +16,7 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { createRequire } from "node:module";
+import os from "node:os";
 import path from "node:path";
 import fs from "node:fs/promises";
 import { filterFalsePositives } from "./issue-filter.js";
@@ -26,6 +27,42 @@ const SCAN_TIMEOUT_MS = 120_000;
 const MAX_DEAD_EXPORTS_REPORTED = 100;
 const MAX_UNUSED_FILES_REPORTED = 50;
 
+// KJC-TSK-0794 AC7: a Firebase callable or a declared global-setup reported as
+// dead is the false positive that gets the inventory switched off. When the
+// project declares nothing itself, kj declares FOR it what it can read.
+const KNIP_OWN_CONFIGS = ["knip.json", "knip.jsonc", ".knip.json", "knip.js", "knip.ts", "knip.config.js", "knip.config.ts"];
+// knip's default root entry patterns, restated because an explicit `entry`
+// REPLACES them (package.json main/bin/exports always count on their own).
+const KNIP_DEFAULT_ENTRY = ["{index,cli,main}.{js,mjs,cjs,jsx,ts,mts,cts,tsx}", "src/{index,cli,main}.{js,mjs,cjs,jsx,ts,mts,cts,tsx}"];
+
+async function hasOwnKnipConfig(projectDir) {
+  for (const f of KNIP_OWN_CONFIGS) {
+    try { await fs.access(path.join(projectDir, f)); return true; } catch { /* keep looking */ }
+  }
+  try { return Boolean(JSON.parse(await fs.readFile(path.join(projectDir, "package.json"), "utf8")).knip); } catch { return false; }
+}
+
+/** Entrypoints kj can vouch for: config.audit.entrypoints (the user's word) and
+ * firebase.json's functions.source (the platform's word). Null when nothing. */
+async function resolveProjectEntrypoints(projectDir, config) {
+  const declared = (config?.audit?.entrypoints || []).filter((e) => typeof e === "string");
+  const firebase = [];
+  try {
+    const fb = JSON.parse(await fs.readFile(path.join(projectDir, "firebase.json"), "utf8"));
+    const fns = Array.isArray(fb.functions) ? fb.functions : fb.functions ? [fb.functions] : [];
+    for (const f of fns) if (typeof f?.source === "string") firebase.push(f.source);
+  } catch { /* no firebase.json — nothing to declare */ }
+  return declared.length || firebase.length ? { declared, firebase } : null;
+}
+
+function buildEphemeralKnipConfig({ declared, firebase }) {
+  const root = { entry: [...KNIP_DEFAULT_ENTRY, ...declared] };
+  if (!firebase.length) return root;
+  const workspaces = { ".": root };
+  for (const src of firebase) workspaces[src] = { entry: ["index.{js,ts}", "src/index.{js,ts}"] };
+  return { workspaces };
+}
+
 function hasJsTsStack(stack) {
   if (!stack) return false;
   const lang = (stack.language || "").toLowerCase();
@@ -78,11 +115,24 @@ export async function collectDeadExports(projectDir, stack, config = {}, logger
     return { available: false, reason: `knip binary not resolvable (${err?.message || err}). In the SEA binary install karajan-code via npm to enable.` };
   }
 
+  const args = [knipBin, "--reporter", "json", "--no-progress", "--no-exit-code"];
+  let declaredEntrypoints = null;
+  try {
+    const eps = await resolveProjectEntrypoints(projectDir, config);
+    // a project with its OWN knip config already decided — it is respected
+    if (eps && !(await hasOwnKnipConfig(projectDir))) {
+      const cfgPath = path.join(await fs.mkdtemp(path.join(os.tmpdir(), "kj-knip-")), "knip.json");
+      await fs.writeFile(cfgPath, JSON.stringify(buildEphemeralKnipConfig(eps)));
+      args.push("--config", cfgPath);
+      declaredEntrypoints = eps;
+    }
+  } catch { /* declaring is best-effort; the default scan still runs */ }
+
   let raw;
   try {
     const { stdout } = await execFileAsync(
       process.execPath,
-      [knipBin, "--reporter", "json", "--no-progress", "--no-exit-code"],
+      args,
       { cwd: projectDir, timeout: SCAN_TIMEOUT_MS, maxBuffer: 16 * 1024 * 1024 },
     );
     raw = stdout;
@@ -163,6 +213,7 @@ export async function collectDeadExports(projectDir, stack, config = {}, logger
     available: true,
     total: kept.length,
     suppressedCount: suppressed.length,
+    declaredEntrypoints,
     exports: keptExports,
     files: keptFiles,
     suppressed,

package/src/audit/deterministic-summary.js

@@ -185,9 +185,20 @@ function formatDeadExportsBlock(deadExports) {
   const lines = ["### Dead Code (knip)"];
   const exportsTotal = (deadExports.exports || []).length;
   const filesTotal = (deadExports.files || []).length;
+  const reported = exportsTotal + filesTotal;
+  const suppressed = deadExports.suppressedCount || 0;
+  // AC8 (KJC-TSK-0794): derivative first; then how many ENTERED and how many
+  // were FILTERED — a shrinking number must never hide a shrinking scan.
+  const prev = deadExports.previous;
+  if (prev && typeof prev.exports === "number") {
+    const d = reported - (prev.exports + (prev.files || 0));
+    lines.push(`- Δ dead code: ${d >= 0 ? "+" : ""}${d} since ${prev.timestamp || "last audit"} (now ${reported})`);
+  }
+  lines.push(`- ${reported + suppressed} entered the scan, ${suppressed} filtered as declared false positives, ${reported} reported`);
+  const eps = deadExports.declaredEntrypoints;
+  if (eps) lines.push(`- Declared entrypoints honored: ${[...eps.declared, ...eps.firebase.map((s) => `${s} (firebase functions)`)].join(", ")}`);
   lines.push(`- Unused exports/types: ${exportsTotal}`);
   lines.push(`- Unused files: ${filesTotal}`);
-  if (deadExports.suppressedCount) lines.push(`- Suppressed (FP filter): ${deadExports.suppressedCount}`);
   const allItems = [...(deadExports.exports || []), ...(deadExports.files || [])];
   if (allItems.length > 0) {
     const groups = groupDeadExportsBySeverity(allItems);
@@ -234,8 +245,12 @@ function formatBasalCostBlock(basalCost, growthDelta) {
   }
 
   const dead = Array.isArray(basalCost.deadExports) ? basalCost.deadExports : [];
+  // AC8 (KJC-TSK-0794): the DERIVATIVE leads — "went from N to M" is what a
+  // reader acts on; the absolute is the secondary datum.
+  const dDelta = growthDelta?.deadExports;
+  const lead = typeof dDelta === "number" ? `${dDelta >= 0 ? "+" : ""}${dDelta} since last audit — ` : "";
   if (dead.length > 0) {
-    lines.push(`- Dead exports: ${dead.length}`);
+    lines.push(`- Dead exports: ${lead}${dead.length} total`);
     for (const de of dead.slice(0, MAX_SAMPLE_DEAD_EXPORTS)) {
       lines.push(`  - \`${de.name}\` in ${de.file}`);
     }
@@ -243,7 +258,7 @@ function formatBasalCostBlock(basalCost, growthDelta) {
       lines.push(`  - ... and ${dead.length - MAX_SAMPLE_DEAD_EXPORTS} more`);
     }
   } else {
-    lines.push("- Dead exports: 0");
+    lines.push(`- Dead exports: ${lead}0`);
   }
 
   if (growthDelta) {

package/src/audit/member-reachability.js

@@ -0,0 +1,158 @@
+/**
+ * Member reachability (KJC-TSK-0794, epic KJC-PCS-0082) — which class members
+ * no entrypoint can reach, said ONLY inside the perimeter validated with known
+ * truth (GREBLA: 31/139 unreachable at dd5a91a checked by hand, 0/108 on their
+ * cleaned main): one file, a recognized framework contract, no dynamic dispatch.
+ * Everything outside comes out NOT OBSERVABLE with its reason, never as clean —
+ * an inflated inventory gets switched off, and then nobody reads the real one.
+ */
+import { parse } from "@babel/parser";
+const plugins = (file) => [
+  ...(/\.(ts|tsx|mts|cts)$/.test(file) ? ["typescript"] : []),
+  ...(/\.(tsx|jsx)$/.test(file) || !/\.(ts|mts|cts)$/.test(file) ? ["jsx"] : []),
+  "decorators",
+];
+// Entrypoints are what the FRAMEWORK calls — declared per framework, VERSIONED
+// (bump on any list change), never a hand-kept list in a run. v1 covers Lit;
+// other frameworks stay NOT OBSERVABLE until their contract is declared here.
+export const ENTRYPOINT_CATALOG = {
+  version: 2, // v2: each list says WHICH slot the framework touches — static and instance are different worlds
+  lit: {
+    instance: ["constructor", "render", "connectedCallback", "disconnectedCallback", "attributeChangedCallback", "adoptedCallback", "firstUpdated", "updated", "willUpdate", "shouldUpdate", "performUpdate", "getUpdateComplete", "createRenderRoot"],
+    static: ["properties", "styles", "observedAttributes"],
+  },
+};
+const BASES = new Map([["LitElement", "lit"]]);
+function walk(node, visit) {
+  if (!node || typeof node.type !== "string") return;
+  visit(node);
+  for (const key of Object.keys(node)) {
+    const child = node[key];
+    if (Array.isArray(child)) child.forEach((c) => walk(c, visit));
+    else if (child && typeof child.type === "string") walk(child, visit);
+  }
+}
+const keyName = (m) => {
+  if (m.key?.type === "PrivateName") return `#${m.key.id.name}`;
+  if (!m.computed && m.key?.type === "Identifier") return m.key.name;
+  return m.key?.type === "StringLiteral" || m.key?.type === "NumericLiteral" ? String(m.key.value) : null;
+};
+const ACCESSOR_KINDS = new Map([["get", "getter"], ["set", "setter"]]);
+const kindOf = (m) => ACCESSOR_KINDS.get(m.kind) ?? (/Method/.test(m.type) ? "method" : "field");
+/** `this.x` / `this['x']` / `this.#x` inside a node, prefixed with the slot the
+ * context can actually reach ("static " inside static members, "" otherwise).
+ * Over-collecting through functions that rebind `this` only makes members MORE
+ * alive — never dead. */
+const thisRefs = (node, prefix = "") => {
+  const refs = new Set();
+  walk(node, (n) => {
+    if (n.type !== "MemberExpression" || n.object?.type !== "ThisExpression") return;
+    if (n.property.type === "PrivateName") refs.add(`${prefix}#${n.property.id.name}`);
+    else if (!n.computed && n.property.type === "Identifier") refs.add(prefix + n.property.name);
+    else if (n.property.type === "StringLiteral" || n.property.type === "NumericLiteral") refs.add(prefix + String(n.property.value));
+  });
+  return refs;
+};
+const notObs = (name, line, reason) => ({ name, line, observable: false, reason, unreachable: [] });
+
+function analyzeClass(node, { staticUses, thisPropCount }) {
+  const name = node.id?.name ?? "(anonymous)";
+  const line = node.loc.start.line;
+  const sup = node.superClass;
+  if (!sup) return notObs(name, line, "no framework contract — members may be called from outside the file");
+  if (sup.type !== "Identifier") return notObs(name, line, "mixin or computed base class — inherited entrypoints cannot be resolved");
+  const framework = BASES.get(sup.name);
+  if (!framework) return notObs(name, line, `unknown base class ${sup.name} — its contract is not in the entrypoint catalog (v${ENTRYPOINT_CATALOG.version})`);
+
+  const cat = ENTRYPOINT_CATALOG[framework];
+  const entries = new Set([...cat.instance, ...cat.static.map((s) => `static ${s}`)]);
+  const members = new Map(); // slot → { refs, spots, entry }
+  // reached at class-definition time (static blocks, static field initializers)
+  // or by ClassName.X anywhere in the file — a use is a use, wherever it sits
+  const roots = new Set([...(staticUses.get(name) ?? [])].map((s) => `static ${s}`));
+  const ctorFields = new Map(); // this._x = v in the constructor: no AST member exists
+  for (const m of node.body.body) {
+    if (m.type === "StaticBlock") { thisRefs(m, "static ").forEach((r) => roots.add(r)); continue; }
+    if (m.type === "TSDeclareMethod" || m.type === "TSIndexSignature") continue;
+    if (m.static && /Property/.test(m.type) && m.value) thisRefs(m.value, "static ").forEach((r) => roots.add(r));
+    const n = keyName(m);
+    if (n === null) return notObs(name, line, `a member name is computed at line ${m.loc.start.line} — the inventory cannot name what it cannot see`);
+    const slot = m.static ? `static ${n}` : n;
+    const refs = thisRefs(m, m.static ? "static " : "");
+    refs.delete(slot); // recursion does not keep itself alive
+    const rec = members.get(slot) ?? { refs: new Set(), spots: [], entry: false };
+    refs.forEach((r) => rec.refs.add(r));
+    rec.spots.push({ line: m.loc.start.line, endLine: m.loc.end.line, kind: kindOf(m) });
+    // a decorated member is registered by the framework: it may call or expose it
+    if (entries.has(slot) || (m.decorators?.length ?? 0) > 0) rec.entry = true;
+    members.set(slot, rec);
+    if (n === "constructor" && !m.static) collectCtorAssignments(m, ctorFields);
+  }
+
+  const alive = new Set();
+  const queue = [...members.keys()].filter((k) => members.get(k).entry || roots.has(k));
+  while (queue.length) {
+    const k = queue.pop();
+    if (alive.has(k) || !members.has(k)) continue;
+    alive.add(k);
+    members.get(k).refs.forEach((r) => { if (members.has(r) && !alive.has(r)) queue.push(r); });
+  }
+  const unreachable = [...members.entries()]
+    .filter(([k]) => !alive.has(k))
+    .flatMap(([k, rec]) => rec.spots.map((s) => ({ name: k, ...s })))
+    .sort((a, b) => a.line - b.line);
+  // HEURISTIC, reported apart (AC5): a constructor field whose name appears in
+  // `this.X` form exactly ONCE in the whole file exists only to be initialized.
+  const constructorFields = [...ctorFields.entries()]
+    .filter(([n]) => !members.has(n) && thisPropCount.get(n) === 1)
+    .map(([n, l]) => ({ name: n, line: l, heuristic: "single this-appearance in file" }));
+  // memberNames: the class's member slots — phantom-coverage (KJC-TSK-0800)
+  // needs to tell "a call to a member of THIS class" from any other call.
+  return { name, line, observable: true, reason: null, framework, catalogVersion: ENTRYPOINT_CATALOG.version, total: members.size, memberNames: [...members.keys()], unreachable, constructorFields };
+}
+
+/** `this.x = …` statements inside the constructor body (first line wins). */
+function collectCtorAssignments(ctor, out) {
+  walk(ctor.body, (n) => {
+    if (n.type !== "AssignmentExpression" || n.left?.type !== "MemberExpression") return;
+    const l = n.left;
+    if (l.object?.type !== "ThisExpression" || l.computed || l.property.type !== "Identifier") return;
+    if (!out.has(l.property.name)) out.set(l.property.name, n.loc.start.line);
+  });
+}
+
+/**
+ * @param {string} source
+ * @param {{file?: string}} [where]
+ * @returns {{file: string, observable: boolean, reason: string|null, classes: Array<object>}}
+ */
+export function analyzeMemberReachability(source, { file = "<source>" } = {}) {
+  let tree;
+  try {
+    tree = parse(source, { sourceType: "unambiguous", allowReturnOutsideFunction: true, plugins: plugins(file) });
+  } catch (err) {
+    return { file, observable: false, reason: `could not be parsed (${err.message}) — not read as clean`, classes: [] };
+  }
+  // String dispatch is the most dangerous false positive: ONE computed access
+  // on `this` that is not a literal makes the whole file not observable — a
+  // list with garbage is worth less than an honest "I do not know".
+  let dynamic = null;
+  const staticUses = new Map(); // ClassName → Set of properties used as ClassName.X
+  const thisPropCount = new Map(); // property → how many `this.X` appearances in the file
+  walk(tree, (n) => {
+    if (n.type !== "MemberExpression") return;
+    if (n.object?.type === "Identifier" && !n.computed && n.property.type === "Identifier") {
+      (staticUses.get(n.object.name) ?? staticUses.set(n.object.name, new Set()).get(n.object.name)).add(n.property.name);
+    }
+    if (n.object?.type !== "ThisExpression") return;
+    if (n.computed && n.property.type !== "StringLiteral" && n.property.type !== "NumericLiteral") { dynamic ??= n.loc.start.line; return; }
+    if (!n.computed && n.property.type === "Identifier") thisPropCount.set(n.property.name, (thisPropCount.get(n.property.name) ?? 0) + 1);
+  });
+  if (dynamic !== null) return { file, observable: false, reason: `computed access on this at line ${dynamic} — string dispatch cannot be followed`, classes: [] };
+
+  const classes = [];
+  walk(tree, (node) => {
+    if (node.type === "ClassDeclaration" || node.type === "ClassExpression") classes.push(analyzeClass(node, { staticUses, thisPropCount }));
+  });
+  return { file, observable: true, reason: null, classes };
+}

package/src/audit/osv-findings.js

@@ -104,6 +104,7 @@ export function parseOsvOutput(raw) {
           aliases: vuln.aliases || [],
           severity: extractSeverity(vuln, groups),
           summary: vuln.summary || vuln.details?.split("\n")[0] || "",
+          publishedAt: vuln.published || null, // the ADVISORY's date — the Steward ages by it (KJC-TSK-0789 AC6)
           package: name,
           version,
           ecosystem,

package/src/claims/cross-check.js

@@ -41,8 +41,13 @@ const SAYS_EMPTY = /(^|\W)(\[\]|\bnone\b|\bno results?\b|\bempty\b|\b0 (results?
  * @returns {{claims: Array<object>, denied: Array<object>, unbacked: Array<object>}}
  */
 export function crossCheck({ text, outputs = [], userSaid = "" }) {
-  const haystack = [...outputs.map(norm), norm(userSaid)];
-  const claims = extractClaims(text).map((claim) => ({ ...claim, status: verdictFor(claim, haystack) }));
+  // Backing can come from an output OR from the user (repeating their datum is not
+  // inventing). The DENIED analysis reads only the OUTPUTS: the user asking "how
+  // many cards are left?" mentions the noun without saying anything about emptiness,
+  // and must not veto a denial — found by the stop-gate wiring test.
+  const sources = outputs.map(norm);
+  const haystack = [...sources, norm(userSaid)];
+  const claims = extractClaims(text).map((claim) => ({ ...claim, status: verdictFor(claim, haystack, sources) }));
   return {
     claims,
     denied: claims.filter((c) => c.status === DENIED),
@@ -50,15 +55,15 @@ export function crossCheck({ text, outputs = [], userSaid = "" }) {
   };
 }
 
-function verdictFor(claim, haystack) {
+function verdictFor(claim, haystack, sources) {
   if (haystack.some((h) => appearsIn(h, claim))) return BACKED;
 
-  // A count stated as non-zero while every source that mentions the same noun says empty:
+  // A count stated as non-zero while every OUTPUT that mentions the same noun says empty:
   // that is the "four cards are waiting" case, and it is the one that blocks.
   if (claim.kind === "count" && Number(claim.value) > 0) {
     const noun = nounAfterCount(claim.sentence, claim.value);
     if (noun) {
-      const mentions = haystack.filter((h) => h.includes(norm(noun)));
+      const mentions = sources.filter((h) => h.includes(norm(noun)));
       if (mentions.length && mentions.every((h) => SAYS_EMPTY.test(h))) return DENIED;
     }
     // Small numbers are prose as often as data ("las dos capas", "3 reglas"): not worth accusing.

package/src/cli/advanced-commands.js

@@ -7,6 +7,7 @@
 
 /** The few commands a newcomer needs. Shown in `kj --help`. */
 export const CORE_COMMANDS = [
+  "go",
   "start",
   "init",
   "run",
@@ -30,7 +31,7 @@ export const ADVANCED_GROUPS = [
   { title: "Pipeline (piezas sueltas)", commands: ["autorun", "code", "review", "solomon", "agent", "scan", "tournament"] },
   { 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", "claims"] },
+  { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar", "privacy", "release", "policy", "claims", "steward"] },
   { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "worktree", "undo", "standby", "sentinel", "identity"] },
   { 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

@@ -4,9 +4,11 @@ import { researcherCommand } from "../commands/researcher.js";
 import { architectCommand } from "../commands/architect.js";
 import { onboardCommand } from "../commands/onboard.js";
 import { startCommand } from "../commands/start.js";
+import { goCommand } from "../commands/go.js";
 import { identityCommand } from "../commands/identity.js";
 import { policyCommand } from "../commands/policy.js";
-import { claimsCommand } from "../commands/claims.js";
+import { claimsCommand, claimsGateCommand } from "../commands/claims.js";
+import { stewardSweepCommand } from "../commands/steward.js";
 import { ragIndexCommand, ragQueryCommand, ragInstallHooksCommand, ragEvalCommand } from "../commands/rag.js";
 import { qmdQueryCommand } from "../commands/qmd.js";
 import { ragMcpCommand } from "../commands/rag-mcp.js";
@@ -147,6 +149,17 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // MGL-A (KJC-TSK-0808): the muggle launcher — one command, at most one
+  // question, and the person lands inside a governed conversation.
+  program
+    .command("go")
+    .description("Arranca Karajan sin saber nada: detecta tu agente, prepara el proyecto, abre el tablero y te deja en la conversación")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "go", flags, async ({ config, logger }) => {
+        await goCommand({ config, logger, flags });
+      });
+    });
+
   program
     .command("start")
     .description("Single entry point: assess the project and recommend the next step")
@@ -314,12 +327,32 @@ export function registerMeta(program, { pkgVersion }) {
 
   // KJC-TSK-0733 PL-A — policy as code: motor determinista en modo warn.
   // CLM-B (KJC-TSK-0802): the data the AI states, checked against what actually ran.
-  program.command("claims").description("Afirmaciones con fuente: comprueba los datos que la IA afirma en un turno contra las salidas de ese turno (ADR claims-with-evidence)")
-    .command("check")
+  const stewardCmd = program.command("steward").description("El Steward: gobierna el ESTADO del proyecto — invariantes con caducidad y cuatro veredictos (épica claims/steward)");
+  stewardCmd.command("sweep")
+    .description("Barrido read-only de los invariantes: deja el informe versionado en .karajan/steward/ (md + json) y sale con 1 solo si algo está ROTO — unknown y not-observable informan con su remedio")
+    .option("--if-stale <days>", "Solo barre si el informe tiene más de N días — retomar trabajo con informe fresco no re-barre")
+    .option("--json", "Machine-readable")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "steward-sweep", flags, async ({ config }) => {
+        process.exitCode = await stewardSweepCommand({ flags, config });
+      });
+    });
+  const claimsCmd = program.command("claims").description("Afirmaciones con fuente: comprueba los datos que la IA afirma en un turno contra las salidas de ese turno (ADR claims-with-evidence)");
+  claimsCmd.command("check")
     .description("Cruza el mensaje final del turno con sus salidas — exit 2 solo si un dato está DESMENTIDO por su propia fuente; falla abierto si no puede leer el transcript")
     .requiredOption("--transcript <path>", "Ruta del transcript de la sesión (la que pasa el hook)")
+    .option("--file <path>", "Cruza el contenido de este fichero (cuerpo de PR, card) en vez del mensaje final del turno")
     .option("--json", "Machine-readable")
     .action(async (flags) => { process.exitCode = await claimsCommand({ flags }); });
+  claimsCmd.command("gate")
+    .description("El mismo cruce, gobernado por method_gates.claims del proyecto (off|warn|block) — lo invocan los hooks; off = silencio, block = exit 2 solo con un dato desmentido")
+    .requiredOption("--transcript <path>", "Ruta del transcript de la sesión")
+    .option("--file <path>", "Cruza el contenido de este fichero (cuerpo de PR, card) en vez del mensaje final del turno")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "claims-gate", flags, async ({ config }) => {
+        process.exitCode = await claimsGateCommand({ flags, config });
+      });
+    });
 
   const policyCmd = program.command("policy").description("Policy as code (.karajan/policy.yml, vocabulario cerrado): eval/check deterministas, grant con caducidad, anchor del decision log — deny en commit y CI");
   policyCmd.command("eval")

package/src/commands/board.js

@@ -87,8 +87,23 @@ async function findAvailablePort(desiredPort, maxTries = 10) {
  * @returns {string}
  */
 export function buildBoardUrl(port, projectSlug) {
-  const base = `http://localhost:${port}`;
-  return projectSlug ? `${base}/#board/${projectSlug}` : base;
+  return projectSlug ? boardUrl(port, `/#board/${projectSlug}`) : boardUrl(port);
+}
+
+/**
+ * Base board URL plus an optional absolute path (query and/or hash) —
+ * `kj go` opens `/?maggle=1` so the frontend renders in plain language
+ * (KJC-TSK-0810). A relative path is a caller bug, not something to fix
+ * up silently.
+ * @param {number} port
+ * @param {string} [path]
+ * @returns {string}
+ */
+export function boardUrl(port, path = "") {
+  if (path && !path.startsWith("/")) {
+    throw new Error(`board path must start with "/": ${path}`);
+  }
+  return `http://localhost:${port}${path}`;
 }
 
 /**
@@ -368,7 +383,7 @@ export function renderBoardBanner({ url, status, projectName }) {
   return ["", rule, ...content, rule, ""].join("\n");
 }
 
-export async function boardCommand({ action = "start", port = 4000, bind = "127.0.0.1", logger }) {
+export async function boardCommand({ action = "start", port = 4000, bind = "127.0.0.1", logger, path }) {
   switch (action) {
     case "start": {
       let result;
@@ -422,7 +437,7 @@ export async function boardCommand({ action = "start", port = 4000, bind = "127.
         logger.info("HU Board is not running. Starting it first...");
         await startBoard(port);
       }
-      const url = `http://localhost:${port}`;
+      const url = boardUrl(port, path);
       // eslint-disable-next-line import-x/no-unresolved -- optional peer; the .catch handles its absence
       const { default: open } = await import("open").catch(() => ({ default: null }));
       if (open) {

package/src/commands/claims.js

@@ -9,10 +9,41 @@
  * It fails OPEN. A verifier that cannot read the transcript says so and gets out
  * of the way: a broken check must never hold a session hostage.
  */
+import { readFileSync } from "node:fs";
 import { readTurn } from "../claims/turn.js";
 import { crossCheck, formatClaimReport } from "../claims/cross-check.js";
 
-export async function claimsCommand({ flags = {}, logger = console, readTurnFn = readTurn } = {}) {
+/**
+ * `kj claims gate` — the same check, run by the Stop hook with the PROJECT's
+ * say-so. The hook stays policy-free: kj reads `method_gates.claims` and
+ * decides. "off" (default: adoption is explicit) exits 0 in silence; "warn"
+ * reports and never blocks; "block" refuses only a datum DENIED by its own
+ * source — unbacked data is reported either way, per the accepted ADR:
+ * inform always, block almost never.
+ */
+export async function claimsGateCommand({ flags = {}, config = {}, logger = console, readTurnFn = readTurn, readFileFn = readFileSync } = {}) {
+  const mode = config?.method_gates?.claims ?? "off";
+  if (mode !== "warn" && mode !== "block") return 0;
+  let turn;
+  try {
+    turn = readTurnFn(flags.transcript);
+    // CLM-C: with --file the ARTIFACT is what gets checked — a PR body, a card, a
+    // note — against the same turn's outputs. The final message is what outlives
+    // the turn least; the artifact is what outlives it most.
+    if (flags.file) turn = { ...turn, text: String(readFileFn(flags.file, "utf8")) };
+  } catch {
+    return 0; // not observable: a gate that cannot read its inputs gets out of the way
+  }
+  const result = crossCheck(turn);
+  if (result.denied.length && mode === "block") {
+    logger.error(formatClaimReport(result));
+    return 2;
+  }
+  if (result.denied.length || result.unbacked.length) logger.error(formatClaimReport(result));
+  return 0;
+}
+
+export async function claimsCommand({ flags = {}, logger = console, readTurnFn = readTurn, readFileFn = readFileSync } = {}) {
   const path = flags.transcript;
   if (!path) {
     logger.error("kj claims check: --transcript <path> is required");
@@ -21,6 +52,7 @@ export async function claimsCommand({ flags = {}, logger = console, readTurnFn =
   let turn;
   try {
     turn = readTurnFn(path);
+    if (flags.file) turn = { ...turn, text: String(readFileFn(flags.file, "utf8")) };
   } catch (err) {
     // Not observable: the transcript could not be read. Never reported as clean.
     const note = `kj claims: transcript not readable (${err.message}) — nothing checked`;

package/src/commands/go.js

@@ -0,0 +1,110 @@
+/**
+ * `kj go` (MGL-A, KJC-TSK-0808, epic KJC-PCS-0084) — the muggle launcher.
+ * One command for a person with no computing background: detect their agents,
+ * ask AT MOST one question, prepare the project silently, open the board, and
+ * leave them inside a conversation that already knows the method. What cannot
+ * be hidden is said honestly: the agent's account and login are THEIRS — kj
+ * never touches credentials. Everything is injectable so tests spawn nothing.
+ */
+import { existsSync } from "node:fs";
+import os from "node:os";
+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 { 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
+// uses: menu signal, never a spawned process.
+export const MAGGLE_AGENTS = [
+  { name: "claude", label: "Claude Code (Anthropic)", authPaths: [".claude.json", ".claude"], install: "npm install -g @anthropic-ai/claude-code", login: "claude   (sigue el enlace de inicio de sesión que te muestre)" },
+  { name: "codex", label: "Codex (OpenAI)", authPaths: [".codex/auth.json"], install: "npm install -g @openai/codex", login: "codex login" },
+];
+export async function detectMaggleAgents({ home = os.homedir(), checkBin = checkBinary } = {}) {
+  return Promise.all(
+    MAGGLE_AGENTS.map(async (a) => {
+      let installed = false;
+      try { installed = (await checkBin(a.name)).ok; } catch { /* not installed */ }
+      const authenticated = installed && a.authPaths.some((p) => existsSync(path.join(home, p)));
+      return { ...a, installed, authenticated };
+    }),
+  );
+}
+/** The session's opening prompt — SHORT and in plain language. The full
+ * playbook already lives in the agent files env-install wrote; duplicating it
+ * here would dilute it. This prompt sets the tone for a muggle. */
+export function buildGoPrompt() {
+  return [
+    "Arrancas dentro de un proyecto gobernado por Karajan (las reglas del método ya están en los ficheros de agente de este proyecto: síguelas siempre).",
+    "La persona que te habla puede no saber programar. Habla en lenguaje llano: sin jerga, sin siglas sin explicar, y resume cada resultado en una o dos frases antes del detalle.",
+    "Antes de cambios importantes, di en llano qué vas a hacer y qué pasará. Si algo falla, explica qué pasó y cuál es el siguiente paso — nunca un volcado de error a secas.",
+    "El tablero del proyecto está abierto en su navegador: cuando termines algo, recuérdale que puede verlo ahí.",
+    "Empieza presentándote en dos frases y preguntando qué quiere construir o cambiar hoy.",
+  ].join("\n");
+}
+async function defaultPrepare({ config, logger }) {
+  await envInstallCommand({ config, logger, flags: { yes: true } });
+}
+export async function defaultBoard({ config, logger, runBoard = boardCommand }) {
+  const port = config.hu_board?.port || 4000;
+  await runBoard({ action: "start", port, bind: "127.0.0.1", logger });
+  // /?maggle=1 switches the frontend to plain language (KJC-TSK-0810) —
+  // the muggle's window opens already speaking their language.
+  await runBoard({ action: "open", port, bind: "127.0.0.1", path: "/?maggle=1", logger });
+}
+function defaultLaunch(agent, prompt) {
+  // Interactive session: the muggle LIVES here. CLAUDECODE is stripped so a
+  // nested Claude does not refuse to start (the known subprocess quirk).
+  const { CLAUDECODE: _omit, ...env } = process.env;
+  return new Promise((resolvePromise) => {
+    const child = spawn(agent.name, [prompt], { stdio: "inherit", env });
+    child.on("exit", (code) => resolvePromise(code ?? 0));
+    child.on("error", (err) => {
+      console.error(`No se pudo arrancar ${agent.label}: ${err.message}`);
+      resolvePromise(1);
+    });
+  });
+}
+export async function goCommand({ config = {}, logger = console, flags = {}, deps = {} } = {}) {
+  const projectDir = config.projectDir || process.cwd();
+  const agents = await (deps.detect ?? detectMaggleAgents)();
+  const ready = agents.filter((a) => a.installed && a.authenticated);
+  const needLogin = agents.filter((a) => a.installed && !a.authenticated);
+  if (ready.length === 0) {
+    if (needLogin.length > 0) {
+      logger.error?.("Tienes el agente instalado pero falta iniciar sesión — eso solo puedes hacerlo tú (la cuenta es tuya; Karajan nunca toca tus credenciales):");
+      for (const a of needLogin) logger.error?.(`  ${a.label}:  ${a.login}`);
+      logger.error?.("Cuando hayas iniciado sesión, vuelve a escribir: kj go");
+    } else {
+      logger.error?.("Karajan trabaja con un agente de IA que aún no tienes instalado. Elige uno, instálalo con su comando, e inicia sesión con TU cuenta (la cuenta es tuya):");
+      for (const a of agents) logger.error?.(`  ${a.label}:  ${a.install}`);
+      logger.error?.("Después, vuelve a escribir: kj go");
+    }
+    process.exitCode = 1;
+    return 1;
+  }
+  let chosen = ready[0];
+  if (ready.length > 1) {
+    const ask = deps.ask ?? createCliAskQuestion({ flags });
+    const answer = await ask("¿Con cuál de tus agentes quieres trabajar?", { options: ready.map((a) => a.name), default: ready[0].name });
+    chosen = ready.find((a) => a.name === String(answer).trim()) ?? ready[0];
+  }
+  logger.info?.(`Trabajarás con ${chosen.label}.`);
+  // 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)…");
+    await (deps.prepare ?? defaultPrepare)({ config, logger });
+  }
+  // The board is the muggle's window — unless the project turned it off
+  // (hu_board.enabled false is respected: KJC-BUG-0152). A board failure is
+  // said and never stops the conversation from starting.
+  if (config.hu_board?.enabled !== false) {
+    try { await (deps.board ?? defaultBoard)({ config, logger }); } catch (err) { logger.warn?.(`El tablero no pudo abrirse (${err.message}) — la conversación arranca igual.`); }
+  }
+  const prompt = (deps.prompt ?? buildGoPrompt)();
+  logger.info?.("Abriendo tu conversación… (escribe ahí lo que necesites, en tu idioma)");
+  const code = await (deps.launch ?? defaultLaunch)(chosen, prompt);
+  process.exitCode = code;
+  return code;
+}

package/src/commands/hu.js

@@ -43,7 +43,9 @@ export function findTitleMatches(title, allHus) {
   return { identical, similar };
 }
 
-async function backlogPlan(projectDir) {
+// Exported for the Steward's proposed-work sync (KJC-TSK-0792): broken
+// invariants land in the same backlog the brain already consumes.
+export async function backlogPlan(projectDir) {
   const plans = await listPlans(projectDir);
   const existing = plans.find((p) => p.alias === BACKLOG_NAME || p.name === BACKLOG_NAME);
   if (existing) return loadPlan(projectDir, existing.planId);