@karajan-family/code 4.31.1 → 4.32.0

package/package.json

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

package/src/checks/project-checks.js

@@ -23,6 +23,7 @@ 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";
 
 /**
  * Detect signals del proyecto. Devuelve un set de tags con qué hay en el
@@ -241,5 +242,9 @@ 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 }),
   ];
 }

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

@@ -239,6 +239,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/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/review-gate.js

@@ -15,6 +15,7 @@ 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";
@@ -482,6 +483,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 +519,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;

package/src/review/one-shot-review.js

@@ -47,6 +47,8 @@ export async function runOneShotReview({
   sonar = null,
   // KJC-TSK-0849 (ADR 0010): what the session's RAG ledger proved, same place.
   rag = null,
+  // BOOT-D (KJC-TSK-0863): the walkthrough of what a person sees, same place.
+  ui = null,
   hostAgent = detectHostAgent(),
   createAgentFn = createAgent,
   detectAgents = detectAvailableAgents,
@@ -129,6 +131,9 @@ export async function runOneShotReview({
     summary: parsed.summary || parsed.raw_summary || "",
     ...(sonar ? { sonar } : {}),
     ...(rag ? { rag } : {}),
+    // BOOT-D (KJC-TSK-0863): the walkthrough of what a person sees travels with
+    // the verdict, bound to this diff, like the other two proofs.
+    ...(ui ? { ui } : {}),
     confidence: parsed.confidence ?? null,
   });
 }

package/src/review/ui-evidence.js

@@ -0,0 +1,65 @@
+/**
+ * BOOT-D (KJC-TSK-0863) — the done-statement of something a person SEES is not
+ * proved by a green suite.
+ *
+ * The Anthropic write-up on long-running agents reports it as an observed
+ * failure: the agent marked features complete without checking them. This
+ * codebase has the same hole. `impeccable` gives an AI OPINION about the diff,
+ * which is precisely what KJC-TSK-0726 rejects; what is missing is the proof
+ * that the route works when a person walks it.
+ *
+ * kj does not drive the browser: the host already has Chrome DevTools, and
+ * duplicating that would tie kj to one runner. kj DEMANDS the evidence and
+ * records it in the verdict, bound to the diff, exactly as it does with sonar
+ * and rag.
+ *
+ * It WARNS, it does not block. The article itself admits the browser misses
+ * native modals, so this is the last proof, never the only one — and a gate
+ * that fails often teaches people to skip gates, which is the doctrine behind
+ * every other rule here.
+ */
+
+export const UI_RULE_ID = "method.ui.evidence";
+
+// What a person can actually see. Deliberately narrow: a false demand costs
+// more than a missed one while this only warns.
+const VISIBLE = /\.(jsx|tsx|vue|svelte|astro|css|scss|sass|less|html)$/i;
+
+const liveGrant = (standingExceptions, now) => (standingExceptions || []).find((e) => {
+  if (e?.rule_id !== UI_RULE_ID) return false;
+  const until = Date.parse(e?.expiresAt ?? "");
+  return Number.isFinite(until) && until > now.getTime();
+});
+
+/**
+ * @returns {{ok: boolean, mode: "not-visible"|"walked"|"granted"|"missing", visible: string[], warn?: boolean, reason?: string, evidence?: object, grant?: object}}
+ */
+export function checkUiEvidence({ stagedFiles = [], evidence = null, standingExceptions = [], now = new Date() } = {}) {
+  const visible = stagedFiles.filter((f) => VISIBLE.test(String(f)));
+  if (visible.length === 0) return { ok: true, mode: "not-visible", visible };
+
+  const walked = Array.isArray(evidence?.walked) ? evidence.walked.filter(Boolean) : [];
+  if (walked.length > 0) return { ok: true, mode: "walked", visible, evidence: { walked, tool: evidence.tool ?? null } };
+
+  const grant = liveGrant(standingExceptions, now);
+  if (grant) return { ok: true, mode: "granted", visible, grant };
+
+  return {
+    ok: true,
+    warn: true,
+    mode: "missing",
+    visible,
+    reason: `verde no es prueba: ${visible.length} fichero(s) que una persona VE (${visible.join(", ")}) sin recorrido comprobado — recórrelo como lo haría ella y deja constancia`,
+  };
+}
+
+/** The block that travels inside the verdict, bound to the diff like sonar's. */
+export function uiBlock(req) {
+  if (!req || req.mode === "not-visible") return null;
+  return {
+    mode: req.mode,
+    walked: req.evidence?.walked ?? [],
+    tool: req.evidence?.tool ?? null,
+    visible: req.visible ?? [],
+  };
+}

package/src/start/project-script.js

@@ -0,0 +1,84 @@
+/**
+ * BOOT-C (KJC-TSK-0862) — the project's start script.
+ *
+ * From the Anthropic write-up on harnesses for long-running agents, and from
+ * the cold-start map: a session burns tokens working out how the project is
+ * launched, and worse, starts building on a tree that was already broken
+ * without knowing it. kj verifies the method; nobody verified that the
+ * application runs.
+ *
+ * kj declares the CONTRACT and checks it. The project writes the script,
+ * because kj cannot know how a project it has never seen is launched, and
+ * generating one from stack detection would produce the decorative artefact
+ * this codebase already rejects elsewhere (a config without its tool).
+ *
+ * It reports, it does not block: a badly written script must not stop work
+ * over something unrelated to the card. It earns the right to block when it
+ * proves reliable, the same path Sonar and the RAG took.
+ */
+
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export const DEFAULT_START_SCRIPT = ".karajan/start.sh";
+export const DEFAULT_TIMEOUT_MS = 120_000;
+export const MAX_OUTPUT_BYTES = 64 * 1024;
+
+export const START_SCRIPT_CONTRACT = [
+  "El guion de arranque levanta lo que haya que levantar y corre un humo de referencia.",
+  "Sale con 0 si el proyecto arranca y el humo pasa; con otro código si no.",
+  "No modifica el árbol ni depende de credenciales: solo responde si esto funciona ahora mismo.",
+].join(" ");
+
+/** Where the start script lives: the project's config decides, with a default. */
+export function startScriptPath(projectDir, config = {}) {
+  return join(projectDir, config.start_script || DEFAULT_START_SCRIPT);
+}
+
+/**
+ * @returns {Promise<{status: "absent"|"ok"|"broken"|"timeout", exitCode?: number, output?: string, contract?: string, path: string}>}
+ */
+export function runStartScript({ projectDir, config = {}, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const script = startScriptPath(projectDir, config);
+  if (!existsSync(script)) {
+    return Promise.resolve({ status: "absent", path: script, contract: START_SCRIPT_CONTRACT });
+  }
+  return new Promise((resolve) => {
+    const ownGroup = process.platform !== "win32";
+    const child = spawn("sh", [script], { cwd: projectDir, detached: ownGroup });
+    let output = "";
+    let truncated = false;
+    let timedOut = false;
+    // Bounded on purpose (catch de codex): a verbose or runaway script would
+    // otherwise eat the CLI's memory for the whole timeout. The LAST bytes are
+    // the ones worth keeping — that is where a failure explains itself.
+    const collect = (buf) => {
+      output += String(buf);
+      if (output.length > MAX_OUTPUT_BYTES) {
+        output = output.slice(-MAX_OUTPUT_BYTES);
+        truncated = true;
+      }
+    };
+    child.stdout?.on("data", collect);
+    child.stderr?.on("data", collect);
+    // Kill the GROUP, not just the shell (catch de codex): this script's whole
+    // job is to START things, so the dev server it launched would keep its port
+    // long after we reported a timeout.
+    const killTree = () => {
+      try {
+        if (ownGroup && child.pid) process.kill(-child.pid, "SIGKILL");
+        else child.kill("SIGKILL");
+      } catch { /* ya no está */ }
+    };
+    // A script that hangs is not a verdict: it is a script that hangs.
+    const timer = setTimeout(() => { timedOut = true; killTree(); }, timeoutMs);
+    child.on("error", (err) => { clearTimeout(timer); resolve({ status: "broken", path: script, exitCode: null, output: `${output}${err.message}`, truncated }); });
+    // Resolve on CLOSE, never before: the answer comes once the tree is down.
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (timedOut) resolve({ status: "timeout", path: script, output, truncated });
+      else resolve({ status: code === 0 ? "ok" : "broken", exitCode: code, path: script, output, truncated });
+    });
+  });
+}