karajan-code 4.4.1 → 4.6.0

package/README.md

@@ -24,12 +24,12 @@
 
 Your AI agent (Claude Code, Codex, Gemini CLI, Cursor…) writes the code. **Karajan governs how it happens**: it installs a method your agent follows on every task, and enforces it with git gates that make a false green structurally impossible.
 
-- **RAG before assuming** — `kj rag query` answers what your codebase does; no agent guesses.
-- **Card first** — every piece of work is tracked (`kj hu add|move|list`) before it starts; architecture decisions live as git-tracked ADRs (`kj adr add|list`).
+- **RAG before assuming** — `kj rag query` answers what your codebase does; no agent guesses. Works out of the box: local Ollama, or the built-in ONNX embedder when nothing can be installed; cloud embedders require an explicit sensitivity declaration and PII-redact every chunk.
+- **Card first, on YOUR board** — every piece of work is tracked before it starts: kj's HU Board (`kj hu add|move|list`), the Planning Game, or the board the project already uses (Linear, Trello, Jira, GitHub Issues) via your agent's own MCP/tools. Declared, verified at install, never optional — Karajan does not run without a board. ADRs live in git (`kj adr add|list`).
 - **Tests prove behavior** — the failing test exists first; the suite is never left red.
-- **Cross-AI review on every commit** — `kj review --staged` binds a verdict from a *different* AI to the sha256 of the exact diff. Change the code and it must be reviewed again. Without an approved verdict, **the commit does not enter** (pre-commit gate).
+- **Deterministic first, then cross-AI review** — `kj review --staged` runs SonarQube on the changed files before any AI opinion (BLOCKER/CRITICAL reject on the spot), then binds a verdict from a *different* AI to the sha256 of the exact diff — stamped with the workspace it ran from. Without an approved verdict, **the commit does not enter** (pre-commit gate).
 - **A third AI arbitrates disputes** — `kj solomon` rules when brain and reviewer disagree. Security findings are never overridable — not even by arbitration.
-- **Branch first** — the base branch only moves through atomic PRs.
+- **Branch first, lanes for parallel work** — the base branch only moves through atomic PRs; `kj worktree start|list|done` gives each concurrent task its own isolated lane.
 
 This repo runs under its own environment: every commit to karajan-code carries a cross-AI verdict.
 
@@ -66,7 +66,7 @@ Full method: [Work with your agent](https://karajancode.com/docs/v4/working-with
 
 ## Headless mode
 
-The classic multiagent pipeline lives on for CI and automation: `kj run "<task>"` orchestrates coder/reviewer/tester subprocess roles unattended, with the same gates. `kj advanced` lists the full surface. [Headless mode docs](https://karajancode.com/docs/v4/headless/).
+The classic multiagent pipeline lives on for CI and automation: `kj run "<task>"` orchestrates coder/reviewer/tester subprocess roles unattended, with the same gates. Agents and CI pass `--non-interactive` (or `KJ_NON_INTERACTIVE=1`): safe gates auto-answer, FAIL findings stop the run with a real exit code. `kj advanced` lists the full surface. [Headless mode docs](https://karajancode.com/docs/v4/headless/).
 
 ## v3 (historical)
 

package/docs/README.es.md

@@ -16,12 +16,12 @@
 
 Tu agente de IA (Claude Code, Codex, Gemini CLI, Cursor…) escribe el código. **Karajan gobierna cómo ocurre**: instala un método que tu agente sigue en cada tarea y lo hace cumplir con gates de git que hacen el falso verde estructuralmente imposible.
 
-- **RAG antes de suponer** — `kj rag query` responde qué hace tu código; ningún agente adivina.
-- **Card primero** — todo trabajo se registra (`kj hu add|move|list`) antes de empezar; las decisiones de arquitectura viven como ADRs en git (`kj adr add|list`).
+- **RAG antes de suponer** — `kj rag query` responde qué hace tu código; ningún agente adivina. Funciona de serie: Ollama local, o el embedder ONNX integrado cuando no se puede instalar nada; los embedders cloud exigen declarar la sensibilidad y redactan PII de cada chunk.
+- **Card primero, en TU board** — todo trabajo se registra antes de empezar: el HU Board de kj (`kj hu add|move|list`), el Planning Game, o el board que el proyecto ya use (Linear, Trello, Jira, GitHub Issues) vía los MCP/tools de tu agente. Declarado, verificado en la instalación, jamás opcional — Karajan no funciona sin board. Los ADRs viven en git (`kj adr add|list`).
 - **Los tests prueban el comportamiento** — el test que falla existe primero; la suite nunca se queda en rojo.
-- **Revisión IA-cruzada en cada commit** — `kj review --staged` liga el veredicto de una IA *distinta* al sha256 del diff exacto. Cambia el código y hay que revisarlo de nuevo. Sin veredicto aprobado, **el commit no entra** (gate pre-commit).
+- **Determinista primero, luego revisión IA-cruzada** — `kj review --staged` pasa SonarQube sobre los ficheros cambiados antes de cualquier opinión de IA (BLOCKER/CRITICAL rechazan en el acto), y después liga el veredicto de una IA *distinta* al sha256 del diff exacto — estampado con el workspace desde el que corrió. Sin veredicto aprobado, **el commit no entra** (gate pre-commit).
 - **Una tercera IA arbitra las disputas** — `kj solomon` decide cuando brain y reviewer discrepan. Los hallazgos de seguridad no los anula nadie — ni siquiera el arbitraje.
-- **Rama primero** — la rama base solo se mueve por PRs atómicas.
+- **Rama primero, carriles para el paralelo** — la rama base solo se mueve por PRs atómicas; `kj worktree start|list|done` da a cada tarea concurrente su carril aislado.
 
 Este repo corre bajo su propio entorno: cada commit de karajan-code lleva un veredicto de IA cruzada.
 
@@ -58,7 +58,7 @@ Método completo: [Trabaja con tu agente](https://karajancode.com/docs/es/v4/wor
 
 ## Modo headless
 
-El pipeline multiagente clásico sigue vivo para CI y automatización: `kj run "<tarea>"` orquesta roles coder/reviewer/tester en subprocesos sin humano delante, con los mismos gates. `kj advanced` lista la superficie completa. [Doc del modo headless](https://karajancode.com/docs/es/v4/headless/).
+El pipeline multiagente clásico sigue vivo para CI y automatización: `kj run "<tarea>"` orquesta roles coder/reviewer/tester en subprocesos sin humano delante, con los mismos gates. Agentes y CI pasan `--non-interactive` (o `KJ_NON_INTERACTIVE=1`): los gates seguros se auto-responden y los findings FAIL paran el run con exit code de verdad. `kj advanced` lista la superficie completa. [Doc del modo headless](https://karajancode.com/docs/es/v4/headless/).
 
 ## v3 (histórico)
 

package/package.json

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

package/src/checks/method.js

@@ -0,0 +1,73 @@
+/**
+ * Method report (KJC-TSK-0689, MG-D of épica KJC-PCS-0068). Individual
+ * deviations can each be legitimate — the AGGREGATE trail is the drift
+ * detector. Three measurable signals over the recent history: commit
+ * subjects without a card reference, review verdicts by workspace
+ * ([root] vs lanes), and source commits without a single test change.
+ * Informative by design; only a card-ref drought turns it into a warn.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { runCommand } from "../utils/process.js";
+import { checkTestsWithCode } from "../review/tests-with-code.js";
+import { CARD_REF_RE } from "../review/card-first.js";
+import { STRATEGY } from "./types.js";
+
+function recentVerdicts(projectDir, sample) {
+  try {
+    const dir = path.join(projectDir, ".karajan", "reviews");
+    return readdirSync(dir).filter((f) => f.endsWith(".json"))
+      .map((f) => JSON.parse(readFileSync(path.join(dir, f), "utf8")))
+      .sort((a, b) => String(b.timestamp).localeCompare(String(a.timestamp)))
+      .slice(0, sample);
+  } catch {
+    return [];
+  }
+}
+
+export async function collectMethodStats({ projectDir, run = runCommand, sample = 20 } = {}) {
+  const subjectsRes = await run("git", ["log", `-${sample}`, "--no-merges", "--format=%s"], { cwd: projectDir });
+  const subjects = subjectsRes.exitCode === 0 ? subjectsRes.stdout.split("\n").filter(Boolean) : [];
+
+  // "@%h" carries a % so git treats it as a literal format string — a bare
+  // "@" is rejected as an unknown pretty alias (caught in a live smoke).
+  const blocksRes = await run("git", ["log", `-${Math.min(sample, 10)}`, "--no-merges", "--name-only", "--format=@%h"], { cwd: projectDir });
+  const blocks = blocksRes.exitCode === 0
+    ? blocksRes.stdout.split(/^@.*$/m).map((b) => b.split("\n").map((l) => l.trim()).filter(Boolean)).filter((b) => b.length > 0)
+    : [];
+  const offenders = blocks.filter((files) => checkTestsWithCode({ config: {}, stagedFiles: files, env: {} }).mode !== "pass").length;
+
+  const verdicts = recentVerdicts(projectDir, sample);
+  const stamped = verdicts.filter((v) => v.workspace);
+
+  return {
+    commits: { total: subjects.length, withCard: subjects.filter((s) => CARD_REF_RE.test(s)).length },
+    verdicts: { total: verdicts.length, stamped: stamped.length, root: stamped.filter((v) => v.workspace === "root").length },
+    testless: { sampled: blocks.length, offenders },
+  };
+}
+
+export function formatMethodStats(s) {
+  return `commits with card ref ${s.commits.withCard}/${s.commits.total} · verdict workspaces root ${s.verdicts.root}/${s.verdicts.stamped || 0} stamped (${s.verdicts.total} total) · source commits without tests ${s.testless.offenders}/${s.testless.sampled}`;
+}
+
+function createMethodCheck() {
+  return {
+    name: "method",
+    label: "Method adherence (recent history)",
+    strategy: STRATEGY.NONE,
+    async detect({ config = {}, projectDir = process.cwd(), run = runCommand } = {}) {
+      const stats = await collectMethodStats({ projectDir, run, sample: config.method_gates?.report_sample || 20 });
+      const detail = formatMethodStats(stats);
+      const drought = stats.commits.total >= 5 && stats.commits.withCard / stats.commits.total < 0.5;
+      if (drought) {
+        return { ok: false, severity: "warn", detail: `most recent commits carry no card reference — ${detail}` };
+      }
+      return { ok: true, severity: "info", detail };
+    },
+  };
+}
+
+export function getMethodChecks() {
+  return [createMethodCheck()];
+}

package/src/cli/register-meta.js

@@ -463,6 +463,14 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--bind <host>", "Bind host (default: 127.0.0.1; use 0.0.0.0 to expose on LAN — token auth auto-enforced)")
     .action(async (action = "start", opts) => {
       await withConfig(pkgVersion, "board", opts, async ({ config, logger }) => {
+        // KJC-TSK-0684 (issue #1287): an external board is the source of
+        // truth — don't start (or advertise) a parallel HU Board. "stop"
+        // stays allowed so a leftover daemon can be cleaned up.
+        if (config?.state_backend === "external" && action !== "stop") {
+          const name = config?.board?.name || "an external board";
+          console.log(`⚠ this project's board lives in ${name} (state_backend: external) — kj does not run a parallel HU Board here.`);
+          return;
+        }
         const port = Number(opts.port) || config.hu_board?.port || 4000;
         const bind = opts.bind || config.hu_board?.bind || "127.0.0.1";
         await boardCommand({ action, port, bind, logger });

package/src/commands/check.js

@@ -5,17 +5,22 @@
  */
 
 import { checkHarden } from "../harden/check.js";
+import { collectMethodStats, formatMethodStats } from "../checks/method.js";
 
 export async function checkCommand({ projectDir = process.cwd(), profile = "standard", json = false, logger = console } = {}) {
   const result = await checkHarden({ projectDir, profile });
+  // KJC-TSK-0689 (MG-D): method adherence is VISIBILITY, not a gate — it
+  // rides along in check output but never affects the exit code.
+  const method = await collectMethodStats({ projectDir }).catch(() => null);
 
   if (json) {
-    logger.info?.(JSON.stringify(result));
+    logger.info?.(JSON.stringify({ ...result, method }));
     return result.ok ? 0 : 1;
   }
 
   logger.info?.(`kj check (${profile})`);
   for (const c of result.checks) logger.info?.(`  ${c.ok ? "✓" : "✗"} ${c.id}: ${c.detail}`);
+  if (method) logger.info?.(`  method: ${formatMethodStats(method)}`);
   if (!result.ok) logger.info?.("Harness drift detected — run `kj harden` to repair.");
   else logger.info?.("Harness OK.");
   return result.ok ? 0 : 1;

package/src/commands/doctor.js

@@ -36,6 +36,7 @@ import { getDirSetupChecks } from "../checks/dir-setup.js";
 import { getProjectChecks } from "../checks/project-checks.js";
 import { getHardwareChecks } from "../checks/hardware.js";
 import { getOrphanChecks } from "../checks/orphans.js";
+import { getMethodChecks } from "../checks/method.js";
 
 /**
  * Build the list of Check objects applicable to the current config.
@@ -74,6 +75,7 @@ function buildChecks(config, { projectOnly = false } = {}) {
     ...getSqueezrChecks(),
     ...getAiTrashChecks(),
     ...getOrphanChecks(),
+    ...getMethodChecks(),
     ...getQmdChecks(),
     ...getRagHooksChecks({ projectDir }),
     ...getProjectChecks({ projectDir }),

package/src/commands/env.js

@@ -11,6 +11,7 @@ import { openVecStore, projectSlug, getLastIndexedCommit, dbPath } from "../rag/
 import { ragIndexCommand } from "./rag.js";
 import { renderPendingBlock, PENDING_EXIT_CODE } from "../utils/pending-user-action.js";
 import { onnxConfig, persistOnnxChoice, resetEmptyStore } from "../rag/onnx-fallback.js";
+import { verifyBoardAccess } from "../environment/board-access.js";
 
 function hasRagIndex(config, projectDir) {
   // KJC-BUG-0128: probing must never CREATE the store — openVecStore runs
@@ -45,9 +46,26 @@ export async function envInstallCommand({ config = null, logger = null, flags =
   const result = await installPlaybook({
     projectDir, target: flags.target || "all",
     stateBackend: config?.state_backend || "hu-board",
+    boardName: config?.board?.name || null,
   });
   console.log(`✓ Karajan playbook installed in: ${result.files.join(", ")}`);
 
+  // KJC-TSK-0685 (user rule): Karajan does not run without a board — it is
+  // what guarantees ordered, card-first work. Verify an OPERATIONAL access
+  // path to the declared backend BEFORE anything else; no path → block
+  // (exit 3) with the exact steps. The playbook stays installed.
+  const access = verifyBoardAccess({ config, projectDir });
+  if (!access.ok) {
+    result.boardError = access.needed.join(" | ");
+    result.exitCode = PENDING_EXIT_CODE;
+    console.log(renderPendingBlock(
+      [{ tool: `${access.name || access.backend} board`, action: "needs-user", reason: `Karajan does not run without a board. To use ${access.name || access.backend}: ${access.needed.join(" ")}` }],
+      { retry: "kj env install" },
+    ));
+    return result;
+  }
+  if (access.backend !== "hu-board") console.log(`✓ board access verified: ${access.via}`);
+
   // ENV-E1: RAG-first — the playbook orders "query the RAG before coding",
   // so installing the environment guarantees the index exists. KJC-TSK-0659
   // stop-on-sudo: an index that cannot be built is a BLOCKING condition —

package/src/commands/hu.js

@@ -60,6 +60,16 @@ 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.`
+    );
+  }
+
   if (action === "list") {
     const plans = await listPlans(projectDir);
     const rows = [];
@@ -165,11 +175,13 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
     // silently moving the first hit could move the wrong card.
     const byId = [];
     const byShort = [];
+    const running = [];
     for (const meta of await listPlans(projectDir)) {
       const plan = await loadPlan(projectDir, meta.planId);
       for (const hu of plan.hus || []) {
         if (hu.id === ref) byId.push({ plan, hu });
         else if (hu.short_id === ref) byShort.push({ plan, hu });
+        if (hu.status === "running") running.push(hu);
       }
     }
     const matches = byId.length > 0 ? byId : byShort;
@@ -179,6 +191,16 @@ export async function huCommand({ config = null, action, args = [], flags = {} }
       throw new Error(`"${ref}" is ambiguous (${matches.length} matches: ${ids}) — use the full id`);
     }
     const { plan, hu } = matches[0];
+    // KJC-TSK-0688 (MG-C): the nudge fires AT the deviation — a second
+    // concurrent task belongs in its own lane, not in the shared tree.
+    const others = running.filter((r) => r.id !== hu.id);
+    if (status === "running" && hu.status !== "running" && others.length > 0) {
+      const slug = String(hu.short_id || hu.id).toLowerCase();
+      console.warn(
+        `⚠ ${others.map((r) => r.short_id || r.id).join(", ")} ${others.length === 1 ? "is" : "are"} already running — `
+        + `a second concurrent task should live in its own lane: kj worktree start ${slug}`
+      );
+    }
     updateHuStatus(plan, hu.id, status);
     await savePlan(projectDir, plan);
     return emit({ id: hu.id, status }, `✓ ${hu.short_id || hu.id} → ${status}`);

package/src/commands/review-gate.js

@@ -11,6 +11,25 @@ import { runOneShotReview } from "../review/one-shot-review.js";
 import { runSolomonArbitration } from "../review/solomon-arbitration.js";
 import { ensureGateTrackable } from "../review/gate-gitignore.js";
 import { runSonarPregate, formatSonarFinding } from "../review/sonar-pregate.js";
+import { checkCardFirst } from "../review/card-first.js";
+import { checkTestsWithCode } from "../review/tests-with-code.js";
+
+// KJC-TSK-0686 (MG-A): card-first is a gate, not a habit. Runs on --staged
+// (before spending sonar/reviewer effort) AND on --check — the pre-commit
+// hook already calls --check, so existing projects gain the gate with a
+// simple package update, no hook regeneration.
+async function enforceCardFirst({ config, projectDir }) {
+  const branchRes = await runCommand("git", ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const branch = branchRes.stdout?.trim() || "HEAD";
+  const card = await checkCardFirst({ config, projectDir, branch });
+  if (card.mode === "warn") console.log(`⚠ card-first: ${card.reason}`);
+  if (card.mode === "exempt" && card.reason.includes("KJ_ALLOW_NO_CARD")) console.log(`⚠ card-first exempt: ${card.reason}`);
+  if (!card.ok) {
+    console.log(`✗ card-first gate: ${card.reason}`);
+    process.exitCode = 1;
+  }
+  return card;
+}
 
 // Raw git always — never a wrapped/compressing runner (KJC-BUG-0115).
 async function rawDiff(range, extraArgs = []) {
@@ -87,6 +106,32 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
 
   const diff = await rawDiff(flags.range);
 
+  const card = await enforceCardFirst({ config, projectDir });
+  if (!card.ok) return { verdict: "rejected", reviewer: "card-first", issues: [{ severity: "high", description: card.reason }] };
+
+  // KJC-TSK-0687 (MG-B): the verifiable half of TDD — sources without a
+  // single test change warn (block via method_gates.tests_with_code).
+  const changedFiles = (await rawDiff(flags.range, ["--name-only"])).split("\n").map((f) => f.trim()).filter(Boolean);
+
+  // KJC-TSK-0688 (MG-C): oversized-diff nudge — informative only; the
+  // project's CI owns any hard budget. Sums additions from --numstat.
+  const sizeWarn = config?.method_gates?.pr_size_warn ?? 150;
+  if (sizeWarn > 0) {
+    const numstat = await rawDiff(flags.range, ["--numstat"]);
+    const added = numstat.split("\n").reduce((acc, l) => acc + (Number(l.split("\t")[0]) || 0), 0);
+    if (added > sizeWarn) {
+      console.log(`⚠ pr-size: ${added} lines added (guideline ~${sizeWarn}) — atomic PRs review better; consider splitting (method_gates.pr_size_warn to tune)`);
+    }
+  }
+  const tests = checkTestsWithCode({ config, stagedFiles: changedFiles });
+  if (tests.mode === "warn") console.log(`⚠ tests-with-code: ${tests.reason}`);
+  if (tests.mode === "exempt") console.log(`⚠ tests-with-code exempt: ${tests.reason}`);
+  if (!tests.ok) {
+    console.log(`✗ tests-with-code gate: ${tests.reason}`);
+    process.exitCode = 1;
+    return { verdict: "rejected", reviewer: "tests-with-code", issues: [{ severity: "high", description: tests.reason }] };
+  }
+
   if (flags.check) {
     const res = await checkVerdict(projectDir, diff);
     console.log(res.ok
@@ -102,8 +147,7 @@ export async function reviewGateCommand({ config, logger = null, flags = {} }) {
   // the cross-AI reviewer weighs them. Unavailable sonar degrades loudly.
   let task = flags.task;
   if (flags.sonar !== false) {
-    const files = (await rawDiff(flags.range, ["--name-only"])).split("\n").map((f) => f.trim()).filter(Boolean);
-    const pre = await runSonarPregate({ config, stagedFiles: files, logger });
+    const pre = await runSonarPregate({ config, stagedFiles: changedFiles, logger });
     if (!pre.available) {
       console.log(`⚠ sonar pre-gate skipped: ${pre.reason}`);
     } else {

package/src/config/defaults.js

@@ -60,8 +60,26 @@ const DEFAULTS = {
   // null in the user's config opts out (no cap).
   max_budget_usd: 5,
   // ENV-D1 (KJC-TSK-0642): where work items live. The HU Board ships with
-  // kj; "planning-game" routes the v4 playbook to the user's PG MCP.
+  // kj; "planning-game" routes the v4 playbook to the user's PG MCP;
+  // "external" (KJC-TSK-0684) points card-first at the project's own board
+  // (Linear, Trello, Jira, GitHub Issues…) named in board.name — worked
+  // through the host agent's MCP/tools, never mirrored by kj. There is NO
+  // "none": Karajan does not run without a board.
   state_backend: "hu-board",
+  board: { name: null },
+  // Method gates (KJC-PCS-0068): rules climb from playbook text to
+  // deterministic enforcement. card_first: "auto" = block with hu-board
+  // (fully verifiable), warn with planning-game/external (presence only);
+  // explicit "warn" | "block" override. Release branches are exempt.
+  method_gates: {
+    card_first: "auto",
+    card_first_exempt_branches: ["chore/release-"],
+    // MG-B: source changes without a test change — "warn" | "block".
+    tests_with_code: "warn",
+    // MG-C: informative nudge when the staged diff exceeds this many
+    // added lines (0 disables). The project's CI owns any hard budget.
+    pr_size_warn: 150
+  },
   review_rules: "./.karajan/review-rules.md",
   coder_rules: "./.karajan/coder-rules.md",
   base_branch: "main",

package/src/environment/board-access.js

@@ -0,0 +1,78 @@
+/**
+ * Board access verification (KJC-TSK-0685). User rule: Karajan does not
+ * run without a board — it is what guarantees ordered, card-first work and
+ * meaningful lanes. There is NO "none". init/env-install verify an
+ * OPERATIONAL access path to the declared backend:
+ *   - hu-board       → always ok (ships inside the kj tarball).
+ *   - planning-game  → its MCP appears in a host agent config.
+ *   - external       → the named board's MCP appears in a host agent
+ *                      config, OR an API token is exported (conventional
+ *                      env var, or the one declared in board.token_env).
+ * Detection is presence-based and format-agnostic (the MCP config files
+ * are scanned as text) — v1 verifies a path exists, not connectivity.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const TOKEN_CONVENTIONS = {
+  linear: ["LINEAR_API_KEY"],
+  trello: ["TRELLO_TOKEN", "TRELLO_API_KEY"],
+  jira: ["JIRA_API_TOKEN"],
+  github: ["GITHUB_TOKEN", "GH_TOKEN"],
+  asana: ["ASANA_ACCESS_TOKEN"],
+};
+
+function mcpConfigPaths(projectDir, home) {
+  return [
+    path.join(projectDir, ".mcp.json"),
+    path.join(home, ".claude.json"),
+    path.join(home, ".codex", "config.toml"),
+    path.join(home, ".gemini", "settings.json"),
+  ];
+}
+
+function mcpConfigsMention(slug, projectDir, home) {
+  const needle = slug.toLowerCase();
+  for (const p of mcpConfigPaths(projectDir, home)) {
+    try {
+      if (existsSync(p) && readFileSync(p, "utf8").toLowerCase().includes(needle)) return p;
+    } catch { /* unreadable config — keep looking */ }
+  }
+  return null;
+}
+
+export function verifyBoardAccess({ config = {}, projectDir = process.cwd(), env = process.env, home = os.homedir() } = {}) {
+  const backend = config.state_backend || "hu-board";
+
+  if (backend === "planning-game") {
+    const hit = mcpConfigsMention("planning-game", projectDir, home);
+    if (hit) return { ok: true, backend, via: `planning-game MCP (${hit})` };
+    return {
+      ok: false, backend,
+      needed: ["configure the planning-game MCP in your host agent (project .mcp.json or the agent's global config)"],
+    };
+  }
+
+  if (backend === "external") {
+    const name = String(config.board?.name || "").trim();
+    if (!name) return { ok: false, backend, needed: ["declare board.name in kj.config.yml (e.g. Linear, Trello, Jira, GitHub Issues)"] };
+    const slug = name.toLowerCase().split(/\s+/)[0];
+    const hit = mcpConfigsMention(slug, projectDir, home);
+    if (hit) return { ok: true, backend, via: `${name} MCP detected (${hit})` };
+    const tokenEnvs = config.board?.token_env ? [config.board.token_env] : (TOKEN_CONVENTIONS[slug] || []);
+    const found = tokenEnvs.find((k) => env[k]);
+    if (found) return { ok: true, backend, via: `API token ${found}` };
+    return {
+      ok: false, backend, name,
+      needed: [
+        `configure the ${name} MCP in your host agent (project .mcp.json or the agent's global config), or`,
+        tokenEnvs.length > 0
+          ? `export an API token: ${tokenEnvs.join(" or ")}`
+          : "declare board.token_env in kj.config.yml and export that variable",
+      ],
+    };
+  }
+
+  return { ok: true, backend: "hu-board", via: "bundled HU Board" };
+}

package/src/environment/playbook.js

@@ -28,15 +28,27 @@ 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.
 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.`;
+
+function trackingLine(stateBackend, boardName) {
+  if (stateBackend === "external") return externalTracking(boardName || "the project's external board");
+  return BACKEND_TRACKING[stateBackend] || BACKEND_TRACKING["hu-board"];
+}
+
 // AB-C2 (KJC-TSK-0653): outcome-first — invariants over step scripts.
 // Frontier models choose their own path best; what they need explicit are
 // the limits. The git gates enforce these regardless of what any brain does.
-const playbookBody = (stateBackend) => `# Karajan method (v4)
+const playbookBody = (stateBackend, boardName) => `# Karajan method (v4)
 
 You are the orchestrator; Karajan governs. A task is DONE when its
 done-statement is literally true, the full suite is green, and every commit
@@ -46,7 +58,7 @@ Invariants (the git gates enforce these — they are not suggestions):
 
 - The project RAG answers before you assume: \`kj rag query\` — never guess
   what the codebase does.
-- ${BACKEND_TRACKING[stateBackend] || BACKEND_TRACKING["hu-board"]}
+- ${trackingLine(stateBackend, boardName)}
 - Tests prove behavior: the failing test exists first (TDD), and the suite
   is never left red.
 - Every diff is reviewed by a DIFFERENT AI before it is committed
@@ -71,15 +83,15 @@ Hit a kj bug or friction? Diagnose it and file it upstream with
 \`kj report-issue\` (sanitized; ask your user before \`--publish\`).
 `;
 
-export function renderPlaybook({ stateBackend = "hu-board" } = {}) {
-  return playbookBody(stateBackend);
+export function renderPlaybook({ stateBackend = "hu-board", boardName = null } = {}) {
+  return playbookBody(stateBackend, boardName);
 }
 
 /**
  * Install/refresh the playbook block in the target agent files.
  * User content outside the managed block is never touched.
  */
-export async function installPlaybook({ projectDir, target = "all", version = "1", stateBackend = "hu-board" }) {
+export async function installPlaybook({ projectDir, target = "all", version = "1", stateBackend = "hu-board", boardName = null }) {
   if (!PLAYBOOK_TARGETS.includes(target)) {
     throw new Error(`unknown target "${target}" — use one of: ${PLAYBOOK_TARGETS.join(", ")}`);
   }
@@ -89,7 +101,7 @@ export async function installPlaybook({ projectDir, target = "all", version = "1
     let source = "";
     try { source = await fs.readFile(fullPath, "utf8"); } catch { /* new file */ }
     const { content, action } = upsertManagedBlock({
-      source, blockId: "playbook", version, body: renderPlaybook({ stateBackend }), style: "html",
+      source, blockId: "playbook", version, body: renderPlaybook({ stateBackend, boardName }), style: "html",
       note: "do not edit: regenerated by kj env install",
     });
     if (action !== "unchanged") await fs.writeFile(fullPath, content);

package/src/review/card-first.js

@@ -0,0 +1,85 @@
+/**
+ * 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:
+ * base branch, configured prefixes (releases), KJ_ALLOW_NO_CARD=1.
+ */
+import { listPlans, loadPlan } from "../plan/plan-store.js";
+import { escapeRegExp } from "../utils/escape-regexp.js";
+
+const LIVE_STATUSES = new Set(["pending", "running", "failed"]);
+// Card-shaped reference: LIN-123, bb-002 and multi-segment ids like
+// KJC-TSK-0684 (optional middle segments) — tight enough to skip slugs.
+// Shared with the method report (MG-D): one pattern, one truth.
+export const CARD_REF_RE = /\b[a-z][a-z0-9]{1,9}(?:-[a-z][a-z0-9]{1,9})*-\d{1,6}\b/i;
+const DEFAULT_EXEMPT_PREFIXES = ["chore/release-"];
+
+// Token-boundary match: BB-002 must not satisfy a branch that actually
+// references BB-0022 (reviewer catch — substring matching allowed work
+// onto the wrong card).
+function refInBranch(ref, branchLower) {
+  return new RegExp(`(^|[^a-z0-9])${escapeRegExp(String(ref).toLowerCase())}([^a-z0-9]|$)`).test(branchLower);
+}
+
+async function findLiveCardInBranch(projectDir, branch) {
+  const needle = branch.toLowerCase();
+  // Scan EVERY match before deciding: any live reference satisfies the
+  // gate; a closed one is only reported when no live match exists
+  // (reviewer catch — first-match could reject a branch that also
+  // references a live card, depending on plan iteration order).
+  let closedHit = null;
+  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]) {
+        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 };
+        }
+      }
+    }
+  }
+  return closedHit;
+}
+
+export async function checkCardFirst({ config = {}, projectDir = process.cwd(), branch, env = process.env }) {
+  if (env.KJ_ALLOW_NO_CARD === "1") {
+    return { ok: true, mode: "exempt", reason: "KJ_ALLOW_NO_CARD=1 (explicit escape hatch)" };
+  }
+  const exempt = config.method_gates?.card_first_exempt_branches || DEFAULT_EXEMPT_PREFIXES;
+  if (exempt.some((p) => branch.startsWith(p))) {
+    return { ok: true, mode: "exempt", reason: `branch prefix exempt (${branch.split("/")[0]}/…)` };
+  }
+  // The base branch belongs to the branch-first gate — card-first here
+  // would only double-report (and HEAD covers detached checkouts in CI).
+  if ([config.base_branch || "main", "main", "master", "HEAD"].includes(branch)) {
+    return { ok: true, mode: "exempt", reason: "base branch — the branch-first gate owns this case" };
+  }
+
+  const backend = config.state_backend || "hu-board";
+  const policy = config.method_gates?.card_first || "auto";
+
+  if (backend === "hu-board") {
+    const hit = await findLiveCardInBranch(projectDir, branch);
+    if (hit?.live) return { ok: true, mode: "pass", ref: hit.ref };
+    const effective = policy === "auto" ? "block" : policy;
+    const reason = hit
+      ? `branch references ${hit.ref} but its card is "${hit.status}" — card-first needs a live card (reopen it or create one: kj hu add)`
+      : `no live card referenced in branch "${branch}" — create it first (kj hu add "…" --id <REF>) and name the branch after it`;
+    return effective === "block"
+      ? { ok: false, mode: "block", reason }
+      : { ok: true, mode: "warn", reason };
+  }
+
+  // planning-game / external: presence check only — liveness lives in the
+  // project's own board, out of local reach.
+  if (CARD_REF_RE.test(branch)) return { ok: true, mode: "pass", ref: branch.match(CARD_REF_RE)[0] };
+  const effective = policy === "auto" ? "warn" : policy;
+  const boardName = config.board?.name || backend;
+  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"
+    ? { ok: false, mode: "block", reason }
+    : { ok: true, mode: "warn", reason };
+}

package/src/review/tests-with-code.js

@@ -0,0 +1,33 @@
+/**
+ * Tests-with-code gate (KJC-TSK-0687, MG-B of épica KJC-PCS-0068). The
+ * verifiable half of TDD is deterministic: a staged diff that touches
+ * source files without touching a single test warns — or blocks, via
+ * `method_gates.tests_with_code`. Test-FIRST remains the reviewer's
+ * judgment; test-PRESENT belongs to the gate. Patterns come from the
+ * project's own `development.*` config (same ones headless enforces).
+ * KJ_ALLOW_NO_TESTS=1 is the explicit escape hatch.
+ */
+
+const DEFAULT_TEST_PATTERNS = ["/tests/", "/__tests__/", ".test.", ".spec."];
+const DEFAULT_SOURCE_EXTS = [".js", ".jsx", ".ts", ".tsx", ".py", ".go", ".java", ".rb", ".php", ".cs"];
+
+export function checkTestsWithCode({ config = {}, stagedFiles = [], env = process.env }) {
+  if (env.KJ_ALLOW_NO_TESTS === "1") {
+    return { ok: true, mode: "exempt", reason: "KJ_ALLOW_NO_TESTS=1 (explicit escape hatch)" };
+  }
+  const patterns = config.development?.test_file_patterns || DEFAULT_TEST_PATTERNS;
+  const exts = config.development?.source_file_extensions || DEFAULT_SOURCE_EXTS;
+  // Staged paths are repo-relative (no leading slash) — normalize so the
+  // "/tests/" style patterns also match the top-level tests directory.
+  const isTest = (f) => patterns.some((p) => `/${f}`.includes(p));
+  const sources = stagedFiles.filter((f) => !isTest(f) && exts.some((e) => f.endsWith(e)));
+  const hasTests = stagedFiles.some(isTest);
+
+  if (sources.length === 0 || hasTests) return { ok: true, mode: "pass" };
+
+  const policy = config.method_gates?.tests_with_code || "warn";
+  const reason = `source changes without any test change (${sources.slice(0, 5).join(", ")}${sources.length > 5 ? "…" : ""}) — the failing test comes first; add one or KJ_ALLOW_NO_TESTS=1 for a deliberate exception`;
+  return policy === "block"
+    ? { ok: false, mode: "block", sources, reason }
+    : { ok: true, mode: "warn", sources, reason };
+}