karajan-code 4.4.0 → 4.5.0

package/package.json

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

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/env.js

@@ -6,12 +6,18 @@
  */
 import { installPlaybook } from "../environment/playbook.js";
 import { renderBrief, listBriefs } from "../environment/briefs.js";
-import { openVecStore, projectSlug, getLastIndexedCommit } from "../rag/vec-store.js";
+import { existsSync } from "node:fs";
+import { openVecStore, projectSlug, getLastIndexedCommit, dbPath } from "../rag/vec-store.js";
 import { ragIndexCommand } from "./rag.js";
 import { renderPendingBlock, PENDING_EXIT_CODE } from "../utils/pending-user-action.js";
-import { onnxConfig, persistOnnxChoice } from "../rag/onnx-fallback.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
+  // the DDL, and a table born at the default dim (768) breaks the ONNX
+  // fallback (384) later. No file → no index, without side effects.
+  if (!existsSync(dbPath())) return false;
   const db = openVecStore({ dim: config?.rag?.embedder?.dim || 768 });
   try { return Boolean(getLastIndexedCommit(db, projectSlug(projectDir))); }
   finally { db.close(); }
@@ -40,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 —
@@ -69,11 +92,19 @@ export async function envInstallCommand({ config = null, logger = null, flags =
       if (explicitProvider) return false;
       console.log(`⚠ default embedder unavailable (${why}) — trying the built-in ONNX embedder (no install needed)…`);
       try {
+        // KJC-BUG-0128: an empty store may carry a vec table at the wrong
+        // dim (the old probe created it at 768) — reset it so ONNX (384)
+        // can index. A store with data is never touched.
+        if (!resetEmptyStore()) {
+          console.log("  the vector store already has data at another dimension — not switching automatically");
+          return false;
+        }
         const totals = await ragIndexCommand({ config: onnxConfig(config), logger, flags: { withSources: true } });
         if ((totals?.indexed ?? 0) > 0) {
           const p = await persistOnnxChoice(projectDir);
           console.log(`✓ RAG indexed with the built-in ONNX embedder — persisted in ${p}`);
-          console.log("  For higher-quality embeddings later: install Ollama and run `kj rag index --rebuild`.");
+          console.log("  To move to Ollama later: install it, remove the rag.embedder block from .karajan/kj.config.yml,");
+          console.log("  delete the store (~/.karajan/rag.db) and run: kj rag index --with-sources");
           return true;
         }
       } catch (fallbackErr) {

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 = [];

package/src/config/defaults.js

@@ -60,8 +60,13 @@ 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 },
   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/rag/onnx-fallback.js

@@ -7,12 +7,39 @@
  * an index can never be written by one and queried by the other.
  */
 import fs from "node:fs/promises";
+import { existsSync, rmSync } from "node:fs";
 import path from "node:path";
+import Database from "better-sqlite3";
 import { parseDocument } from "yaml";
 import { getProjectConfigPath } from "../config/loader.js";
+import { dbPath } from "./vec-store.js";
 
 const ONNX_EMBEDDER = { provider: "onnx", dim: 384 };
 
+/**
+ * KJC-BUG-0128: the hasRagIndex probe could leave behind an EMPTY store
+ * whose vec table was created at the default dim (768) — ONNX inserts (384)
+ * then failed on every chunk. Before the fallback indexes, delete an empty
+ * store (plus WAL siblings) so it is recreated at the right dim. A store
+ * that already HAS chunks is never touched — switching dims there would
+ * destroy other projects' indexes.
+ */
+export function resetEmptyStore() {
+  const storePath = dbPath();
+  if (!existsSync(storePath)) return true;
+  // Read-only, schema-agnostic inspection: no DDL, no vec extension, no
+  // dimension assumptions — the store is only ever OPENED to be counted.
+  const db = new Database(storePath, { readonly: true });
+  try {
+    const hasChunksTable = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='chunks'").get();
+    if (hasChunksTable && db.prepare("SELECT COUNT(*) AS n FROM chunks").get().n > 0) return false;
+  } finally {
+    db.close();
+  }
+  for (const suffix of ["", "-wal", "-shm"]) rmSync(storePath + suffix, { force: true });
+  return true;
+}
+
 /** The same config, with the embedder swapped to the built-in ONNX. */
 export function onnxConfig(config) {
   return {