karajan-code 4.49.5 → 4.51.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "4.49.5",
+  "version": "4.51.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -60,7 +60,6 @@
     "packages/ai-trash/src/",
     "packages/ai-trash/bin/",
     "packages/ai-trash/package.json",
-    "docs/karajan-code-logo-small.png",
     "docs/README.es.md",
     "LICENSE",
     "README.md"

package/src/checks/release-check.js

@@ -29,7 +29,7 @@ async function withoutSetupInstalls(projectDir, setup, violations) {
   const installed = new Set(added.exitCode === 0 ? added.stdout.split("\n").map((s) => s.trim()).filter(Boolean) : []);
   const kept = [];
   for (const v of violations) {
-    if (v.rule_id === "defaults.supervisor.write" && installed.has(v.file)) {
+    if ((v.rule_id === "defaults.supervisor.write" || v.rule_id === "defaults.governance.write") && installed.has(v.file)) {
       const changed = await runCommand("git", ["-C", projectDir, "diff", "--quiet", setup, "HEAD", "--", v.file]);
       if (changed.exitCode === 0) continue;
     }

package/src/cli/register-meta.js

@@ -315,6 +315,7 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--scope <text>", "Scope of the story (files/areas)")
     .option("--task-type <type>", "sw | infra | doc | add-tests | refactor")
     .option("--criteria <text>", "Legacy alias for a single acceptance criterion")
+    .option("--ref <id>", "Id of this card's replica in the external tracker (Planning Game, Jira, Linear...)")
     .option("--json", "Machine-readable output")
     .action(async (title, flags) => {
       await withConfig(pkgVersion, "hu", flags, async ({ config }) => {

package/src/commands/hu.js

@@ -62,15 +62,9 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
   const projectDir = config?.projectDir || process.cwd();
   const emit = (obj, human) => { console.log(flags.json ? JSON.stringify(obj) : human); return obj; };
 
-  // KJC-TSK-0684 (issue #1287): with an external board declared, kj never
-  // maintains a parallel HU Board — writes are refused with the pointer.
-  if (config?.state_backend === "external" && (action === "add" || action === "move")) {
-    const name = config?.board?.name || "an external board";
-    throw new Error(
-      `this project's board lives in ${name} (state_backend: external) — create and move cards there, `
-      + `through your agent's MCP/tools. kj does not mirror external boards.`
-    );
-  }
+  // KJC-BUG-0305 (issue #2042): the HU Board is always kj's board. An external
+  // tracker coexists with it: each HU points at its replica there (--ref).
+  const externalBoard = config?.state_backend === "external" ? (config?.board?.name || "the external board") : null;
 
   if (action === "list") {
     const plans = await listPlans(projectDir);
@@ -84,12 +78,14 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
           // KJC-TSK-0661: provenance — where a card came from is part of
           // the card. Older HUs predate the stamp: shown as "?".
           created_by: h.created_by || null, created_at: h.createdAt || null,
+          external_ref: h.external_ref || null,
         });
       }
     }
     if (flags.json) { console.log(JSON.stringify(rows)); return rows; }
     for (const r of rows) {
-      const origin = `${r.plan} · by ${r.created_by || "?"}${r.created_at ? ` · ${r.created_at.slice(0, 10)}` : ""}`;
+      const suffixes = [r.created_at?.slice(0, 10), r.external_ref].filter(Boolean).map((s) => ` · ${s}`).join("");
+      const origin = `${r.plan} · by ${r.created_by || "?"}${suffixes}`;
       console.log(`${(r.short_id || r.id).padEnd(28)} ${r.status.padEnd(8)} ${r.title}  [${origin}]`);
     }
     if (rows.length === 0) console.log("no HUs yet — create one with: kj hu add \"<story>\"");
@@ -164,7 +160,11 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
       task_type: flags.taskType || undefined,
     });
     hu.created_by = creatorLabel();
+    if (flags.ref) hu.external_ref = String(flags.ref).trim();
     await savePlan(projectDir, plan);
+    if (externalBoard && !hu.external_ref) {
+      console.log(`→ replicate it in ${externalBoard} through your agent's MCP/tools and link both: kj hu add ... --ref <id in ${externalBoard}>`);
+    }
     const missing = [];
     if (hu.acceptance_criteria.length === 0) missing.push("acceptance criteria (--ac \"...\")");
     if (hu.acceptance_tests.length === 0) missing.push("tests (--tests \"...\")");
@@ -174,7 +174,7 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
     return emit({
       id: hu.id, short_id: hu.short_id, status: hu.status, created_by: hu.created_by,
       acceptance_criteria: hu.acceptance_criteria, acceptance_tests: hu.acceptance_tests,
-      scope: hu.scope, task_type: hu.task_type,
+      scope: hu.scope, task_type: hu.task_type, external_ref: hu.external_ref || null,
     }, `✓ HU created: ${hu.short_id || hu.id} (pending, by ${hu.created_by}) — it shows up in \`kj board\``);
   }
 

package/src/commands/steward.js

@@ -113,7 +113,10 @@ export async function stewardSweepCommand({ flags = {}, config = {}, logger = co
   try {
     const sync = await syncProposedWork({ projectDir, config, results, sweptAt: report.sweptAt });
     if (!sync.synced) logger.warn?.(`⚠ steward: broken invariants not carded — ${sync.reason}`);
-    else if (sync.created || sync.updated || sync.resolved) logger.info?.(`steward board: ${sync.created} card(s) proposed, ${sync.updated} updated, ${sync.resolved} resolved`);
+    else if (sync.created || sync.updated || sync.resolved) {
+      logger.info?.(`steward board: ${sync.created} card(s) proposed, ${sync.updated} updated, ${sync.resolved} resolved`);
+      if (sync.replicateIn) logger.info?.(`→ replicate them in ${sync.replicateIn} through your agent's board tools (kj hu list shows them)`);
+    }
   } catch (err) { logger.warn?.(`⚠ steward: carding the broken invariants failed (${err.message}) — the report and the seal stand`); }
 
   // A report nobody can see is not shared state — say it, do not fix their tree.

package/src/environment/playbook.js

@@ -30,20 +30,20 @@ const TARGET_FILES = {
 
 // ENV-D1 (KJC-TSK-0642): the tracking invariant names the CHOSEN state
 // backend — a playbook that says "board or PG" makes the host guess.
-// KJC-TSK-0684 (issue #1287): external boards (Linear, Trello, Jira…) are
-// first-class — card-first points at THE project's board, worked through
-// the host agent's own MCP/tools. kj never mirrors it: a half-empty
-// parallel board is worse than none.
+// KJC-BUG-0305 (issue #2042, replaces KJC-TSK-0684): the HU Board is always
+// kj's board. An external board (Linear, Trello, Jira…) coexists with it: the
+// host agent replicates each card there through its own MCP/tools, and
+// `kj hu add --ref` links the two.
 const BACKEND_TRACKING = {
   "hu-board": "Every piece of work has a tracked story/bug in the HU Board (`kj hu add` / `kj board`) before it starts — and `kj hu list` BEFORE `kj hu add`: reuse the existing card if one covers the work. Cards are permanent — never delete or recreate one; discard with `kj hu move <id> skipped`. `kj brief board` explains the board.",
-  "planning-game": "Every piece of work has a tracked card in the Planning Game MCP before it starts (In Progress while you work it).",
 };
 
 const externalTracking = (boardName) =>
-  `Every piece of work has a tracked card in ${boardName} — the project's board — before it starts (use its MCP/tools; move the card as you work it). kj does not mirror it: never create a parallel HU Board.`;
+  `Every piece of work has a card in the HU Board before it starts (\`kj hu list\`, then \`kj hu add --ref <id>\`) and its replica in ${boardName}, created through its MCP/tools; move both as you work it.`;
 
 function trackingLine(stateBackend, boardName) {
   if (stateBackend === "external") return externalTracking(boardName || "the project's external board");
+  if (stateBackend === "planning-game") return externalTracking("the Planning Game");
   return BACKEND_TRACKING[stateBackend] || BACKEND_TRACKING["hu-board"];
 }
 

package/src/harden/supervisor-commit.js

@@ -26,6 +26,10 @@ const HOOKS_PREFIX = ".karajan/hooks/";
 // veredictos son locales por diseño); lo que viaja y se firma es su HUELLA,
 // dentro de una procedencia que sí está trackeada.
 const HARNESS_PREFIX = ".karajan/harness/";
+// KJC-TSK-1032 (owner's decision, 13-oct): the governance config that travels
+// with the repo is sealed with the supervisor, so a policy change enters only
+// with the human's signed act. kj.config.yml is machine-local: CI never sees it.
+export const GOVERNANCE_FILES = [".karajan/policy.yml", ".karajan/rules.yml"];
 
 const sha256 = (abs) => createHash("sha256").update(readFileSync(abs)).digest("hex");
 
@@ -79,7 +83,7 @@ export async function commitSupervisorRegeneration({
   // KJC-BUG-0244 (grebla #958): el commit sellado solo lleva el supervisor, pero
   // un stage ajeno se quedaba en esta rama y el siguiente commit caía aquí con la
   // card equivocada. Se para ANTES de pedir nada al humano y se nombra.
-  const foreign = run(["diff", "--cached", "--name-only"]).split("\n").filter((f) => f && !f.startsWith(HOOKS_PREFIX) && f !== PROVENANCE_FILE);
+  const foreign = run(["diff", "--cached", "--name-only"]).split("\n").filter((f) => f && !f.startsWith(HOOKS_PREFIX) && f !== PROVENANCE_FILE && !GOVERNANCE_FILES.includes(f));
   if (foreign.length > 0) {
     throw new Error(
       `harden --commit: hay cambios en el stage que no son del supervisor (${foreign.slice(0, 5).join(", ")}${foreign.length > 5 ? ", …" : ""}): commitéalos en su rama o sácalos del stage (git restore --staged <ficheros>) antes de sellar`,
@@ -88,13 +92,17 @@ export async function commitSupervisorRegeneration({
   // Capa 4 (test adversarial 6-sep: un huérfano a init con pty falso y
   // prompts a ciegas llegó hasta aquí): nonce aleatorio tecleado de vuelta.
   seal.confirm(deps.confirm);
-  const drift = supervisorDrift({ projectDir, gitFn: run });
+  const tracked = new Set(run(["ls-files", "--", ...GOVERNANCE_FILES]).split("\n").filter(Boolean));
+  const governance = GOVERNANCE_FILES.filter((f) => existsSync(join(projectDir, f)) || tracked.has(f));
+  const governanceDrift = governance.length === 0 ? [] : run(["status", "--porcelain", "--", ...governance]).split("\n").map((l) => l.slice(3).trim()).filter(Boolean);
+  const drift = [...supervisorDrift({ projectDir, gitFn: run }), ...governanceDrift];
   // La provenance describe SIEMPRE el estado COMPLETO del supervisor (cazado
   // en el primer estreno real: un sello parcial pisaba al anterior y dejaba
   // ficheros sin respaldo). Borrados del drift ⇒ deleted (catch de codex).
   const current = [
     ...readdirSync(join(projectDir, HOOKS_PREFIX)).map((f) => HOOKS_PREFIX + f),
     ...harnessGuards(projectDir),
+    ...governance.filter((f) => existsSync(join(projectDir, f))),
   ].sort();
   // KJC-BUG-0197: un guardia BORRADO se anota como borrado, igual que un hook.
   // No hacía falta para desencadenar el re-sello (la lista encoge, así que la
@@ -159,7 +167,7 @@ export async function commitSupervisorRegeneration({
   // Por DIRECTORIO, no por fichero: un rename ya staged deja la ruta vieja
   // sin existir y `git add -- <vieja>` falla; `-A` sobre el dir del
   // supervisor versiona altas, cambios, borrados y renombrados por igual.
-  run(["add", "-A", "--", PROVENANCE_FILE, ".karajan/hooks"]);
+  run(["add", "-A", "--", PROVENANCE_FILE, ".karajan/hooks", ...governance]);
   run([
     "commit",
     "--no-verify",
@@ -168,6 +176,7 @@ export async function commitSupervisorRegeneration({
     "--",
     PROVENANCE_FILE,
     ".karajan/hooks",
+    ...governance,
   ]);
   logger.info?.(`harden --commit: ${hashed.length} fichero(s) de supervisor versionados con procedencia sellada`);
   return { committed: true, files: hashed };

package/src/policy/engine.js

@@ -31,6 +31,13 @@ export const SUPERVISOR_DEFAULTS = [
     pattern: /\.claude\/settings\.json\b|\.karajan\/(hooks|harness)\/|\.karajan\/supervisor-provenance\.json\b/,
     message: "nombra ficheros del supervisor — solo el humano los modifica, fuera de la sesión",
   },
+  {
+    // KJC-TSK-1033 (owner's decision, 13-oct): a policy change is authorized where
+    // it is USED (commit, CI, release), whatever wrote it: only the human's seal lifts it.
+    id: "defaults.governance.write",
+    pattern: /(^|\/)\.karajan\/(policy|rules)\.yml\b/,
+    message: "es configuración de gobierno: solo entra sellada por la persona (kj harden --commit, firmado desde su móvil)",
+  },
 ];
 
 // Tools del harness: mapeo acción → capability del kernel. Registro cerrado

package/src/policy/supervisor-verify.js

@@ -11,7 +11,7 @@ import { resolve, sep } from "node:path";
 import { renderCanonicalHook } from "../harden/harden-engine.js";
 import { provenanceSignature } from "../harden/phone-sign.js";
 import { canonicalHarnessBody } from "../harden/sentinel-hooks.js";
-import { PROVENANCE_FILE } from "../harden/supervisor-commit.js";
+import { GOVERNANCE_FILES, PROVENANCE_FILE } from "../harden/supervisor-commit.js";
 
 const HOOKS_PREFIX = ".karajan/hooks/";
 const HARNESS_PREFIX = ".karajan/harness/";
@@ -67,6 +67,15 @@ export function verifiedSupervisorFiles({ projectDir, trackedOnly = false }) {
   const ROOTS = [HOOKS_PREFIX, HARNESS_PREFIX].map((p) => [p, resolve(projectDir, p)]);
   for (const entry of entries) {
     if (typeof entry?.file !== "string") continue;
+    // KJC-TSK-1032: the governance config has no canonical render; the sealed
+    // hash, signed by the roster where there is one, is the proof.
+    if (GOVERNANCE_FILES.includes(entry.file)) {
+      const abs = resolve(projectDir, entry.file);
+      let st = null;
+      try { st = lstatSync(abs); } catch { /* absent */ }
+      if (entry.deleted === true ? st === null : st?.isFile() && sha256(readFileSync(abs)) === entry.sha256) ok.add(entry.file);
+      continue;
+    }
     const kind = ROOTS.find(([prefix]) => entry.file.startsWith(prefix));
     if (!kind) continue;
     const [prefix, root] = kind;
@@ -130,13 +139,14 @@ export function verifiedSupervisorFiles({ projectDir, trackedOnly = false }) {
  * mas laxo de lo que parece no pase por silencio (KJC-BUG-0212).
  */
 export function liftSealedSupervisorViolations({ projectDir, violations, trackedOnly = false }) {
-  const RULE = "defaults.supervisor.write";
-  if (!violations.some((v) => v.rule_id === RULE && v.file)) return { violations, lifted: 0 };
+  // KJC-TSK-1033: the governance config is lifted by the same seal.
+  const RULES = new Set(["defaults.supervisor.write", "defaults.governance.write"]);
+  if (!violations.some((v) => RULES.has(v.rule_id) && v.file)) return { violations, lifted: 0 };
   const sealed = verifiedSupervisorFiles({ projectDir, trackedOnly });
   // La violación sobre la PROPIA provenance solo se alza si la provenance
   // entera verificó — a medias no describe la verdad y sigue denegada.
   const liftable = (v) =>
-    v.rule_id === RULE
+    RULES.has(v.rule_id)
     && v.file
     && (sealed.files.has(v.file) || (v.file === PROVENANCE_FILE && sealed.complete === true));
   const kept = violations.filter((v) => !liftable(v));

package/src/review/card-first.js

@@ -2,8 +2,8 @@
  * Card-first gate (KJC-TSK-0686, MG-A of épica KJC-PCS-0068): the rule
  * that work starts from a card moves from playbook text into the gate.
  * hu-board → the branch must reference a LIVE card (block by default);
- * planning-game/external → card-shaped reference required (warn default,
- * block via method_gates.card_first). Exemptions explicit and visible:
+ * planning-game/external → a live HU on the HU Board first, else a card-shaped
+ * reference (warn default, block via method_gates.card_first). Exemptions explicit and visible:
  * base branch and configured prefixes (releases). No escape (ADR 0015): a
  * gate an agent can switch off is a suggestion.
  */
@@ -40,7 +40,8 @@ async function findLiveCardInBranch(projectDir, branch) {
   for (const meta of await listPlans(projectDir)) {
     const plan = await loadPlan(projectDir, meta.planId);
     for (const h of plan.hus || []) {
-      for (const ref of [h.short_id, h.id]) {
+      // KJC-BUG-0353: an HU is also named by the id of its replica in an external tracker.
+      for (const ref of [h.short_id, h.id, h.external_ref]) {
         if (ref && refInBranch(ref, needle)) {
           if (LIVE_STATUSES.has(h.status)) return { ref, live: true, status: h.status };
           closedHit = { ref, live: false, status: h.status };
@@ -83,6 +84,10 @@ export async function checkCardFirst({ config = {}, projectDir = process.cwd(),
   // result names its level so nobody mistakes branch-ref for tracker.
   const boardName = config.board?.name || backend;
   const effective = policy === "auto" ? "warn" : policy;
+  // KJC-BUG-0353: the HU Board is always kj's board (KJC-BUG-0305) — a live HU
+  // the branch names, or whose replica it names, is checked here, not guessed.
+  const huHit = await findLiveCardInBranch(projectDir, branch);
+  if (huHit?.live) return { ok: true, mode: "pass", ref: huHit.ref, level: "hu-board" };
   if (CARD_REF_RE.test(branch)) {
     const ref = branch.match(CARD_REF_RE)[0];
     const { verifyFn = verifyCardAlive } = deps;
@@ -105,7 +110,8 @@ export async function checkCardFirst({ config = {}, projectDir = process.cwd(),
         reason: `branch references ${ref} but the card could not be verified against ${boardName} — ${v.note} (board.unverifiable: block refuses to approve a check kj did not make)`,
       };
     }
-    return { ok: true, mode: "pass", ref, level: v.level, ...(v.note ? { note: v.note } : {}) };
+    const huNote = `no live HU on the HU Board links ${ref}: kj hu add "…" --ref ${ref}`;
+    return { ok: true, mode: "pass", ref, level: v.level, note: v.note ? `${v.note}; ${huNote}` : huNote };
   }
   const reason = `no card reference in branch "${branch}" — card-first on ${boardName}: create the card there and name the branch after it (e.g. feat/ABC-123-summary)`;
   return effective === "block"

package/src/steward/proposed-work.js

@@ -7,11 +7,9 @@
  * a daily sweep must never flood the board with twins — and a green
  * invariant resolves it with the green evidence.
  *
- * kj only writes the board it owns (hu-board). planning-game and external
- * boards are never mirrored (KJC-TSK-0684: a half-empty parallel board is
- * worse than none): there the sweep reports synced:false LOUDLY, and the
- * Sentinel's inevitable notice (STW-C) pushes the host agent — who does
- * have the board's MCP — to card them.
+ * KJC-BUG-0305: the HU Board is always kj's board, so the cards land there on
+ * every backend. With planning-game or an external board the result names it
+ * (replicateIn): the host agent, who has that board's MCP, replicates them.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -34,13 +32,11 @@ const cardText = (r, brokenSince) => [
  */
 export async function syncProposedWork({ projectDir, config = {}, results = [], sweptAt }) {
   const backend = config.state_backend || "hu-board";
-  if (backend !== "hu-board") {
-    return { synced: false, reason: `the board lives in ${backend} — kj never mirrors a board it does not own; card the broken invariants through your agent's board tools` };
-  }
+  const replica = backend === "hu-board" ? {} : { replicateIn: backend };
   const map = readMap(projectDir);
   const broken = results.filter((r) => r.verdict === "broken");
   const okAgain = results.filter((r) => r.verdict === "ok" && map[r.id]);
-  if (broken.length === 0 && okAgain.length === 0) return { synced: true, created: 0, updated: 0, resolved: 0 };
+  if (broken.length === 0 && okAgain.length === 0) return { synced: true, created: 0, updated: 0, resolved: 0, ...replica };
 
   const plan = await backlogPlan(projectDir);
   let created = 0, updated = 0, resolved = 0;
@@ -64,5 +60,5 @@ export async function syncProposedWork({ projectDir, config = {}, results = [],
   await savePlan(projectDir, plan);
   fs.mkdirSync(path.dirname(mapPath(projectDir)), { recursive: true });
   fs.writeFileSync(mapPath(projectDir), `${JSON.stringify(map, null, 2)}\n`);
-  return { synced: true, created, updated, resolved };
+  return { synced: true, created, updated, resolved, ...replica };
 }