karajan-code 4.10.0 → 4.11.0

package/package.json

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

package/src/commands/env.js

@@ -12,7 +12,9 @@ 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";
+import { pickStateBackend } from "../environment/board-select.js";
 import { ensurePrivacyList } from "../privacy/onboarding.js";
+import { installProjectMcp } from "../environment/mcp-wiring.js";
 import { createWizard } from "../utils/wizard.js";
 import { hardenCommand } from "./harden.js";
 import { reviewGateCommand } from "./review-gate.js";
@@ -48,6 +50,23 @@ export function briefCommand({ config = null, flags = {}, role = null }) {
 
 export async function envInstallCommand({ config = null, logger = null, flags = {} }) {
   const projectDir = config?.projectDir || process.cwd();
+
+  // KJC-TSK-0709 — the board is chosen BEFORE the playbook renders (its
+  // tracking line depends on the backend): interactive installs ask when
+  // alternatives are reachable, headless installs name the default. The
+  // choice persists so it is only ever asked once.
+  try {
+    const wizard = process.stdin.isTTY && process.stdout.isTTY ? createWizard() : null;
+    const sel = await pickStateBackend({ projectDir, wizard, isTTY: Boolean(wizard), logger: console });
+    wizard?.close();
+    // The effective backend feeds the render on EVERY non-error path —
+    // chosen, declared-in-file or default — so the playbook never falls
+    // back to hu-board while the selection said otherwise.
+    config = { ...config, state_backend: sel.backend, board: sel.boardName ? { ...(config?.board || {}), name: sel.boardName } : config?.board };
+  } catch (err) {
+    console.log(`⚠ board selection failed (${err.message}) — continuing with the configured default`);
+  }
+
   const result = await installPlaybook({
     projectDir, target: flags.target || "all",
     stateBackend: config?.state_backend || "hu-board",
@@ -55,6 +74,14 @@ export async function envInstallCommand({ config = null, logger = null, flags =
   });
   console.log(`✓ Karajan playbook installed in: ${result.files.join(", ")}`);
 
+  // KJC-TSK-0711 — RAG as a native tool: agents use what is in their
+  // toolbox, so the official path must be cheaper than the grep shortcut.
+  try {
+    installProjectMcp({ projectDir, logger: console });
+  } catch (err) {
+    console.log(`⚠ could not wire kj-rag-mcp into .mcp.json: ${err.message}`);
+  }
+
   // 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

package/src/config/schema.js

@@ -238,8 +238,10 @@ export const ConfigSchema = v.looseObject({
   // ENV-D1 (KJC-TSK-0642): where work items live — the integrated HU Board
   // or the user's Planning Game. The v4 playbook renders per backend.
   state_backend: v.optional(v.picklist(
-    ["hu-board", "planning-game"],
-    "state_backend must be \"hu-board\" or \"planning-game\""
+    // KJC-TSK-0709 caught the drift: "external" shipped in v4.5.0 (any
+    // board via the agent's own MCP/tools) but this picklist never learned it.
+    ["hu-board", "planning-game", "external"],
+    "state_backend must be \"hu-board\", \"planning-game\" or \"external\""
   )),
   review_rules: v.optional(v.string()),
   coder_rules: v.optional(v.string()),

package/src/environment/board-access.js

@@ -42,6 +42,25 @@ function mcpConfigsMention(slug, projectDir, home) {
   return null;
 }
 
+/**
+ * Boards reachable from this machine (KJC-TSK-0709): the bundled HU Board
+ * always; planning-game / external candidates when their MCP appears in a
+ * host config or a conventional token is exported. Presence-based, like
+ * verifyBoardAccess — an OPTION list, not a connectivity check.
+ */
+export function detectAvailableBoards({ projectDir = process.cwd(), env = process.env, home = os.homedir() } = {}) {
+  const boards = [{ value: "hu-board", label: "HU Board (bundled, zero setup)" }];
+  if (mcpConfigsMention("planning-game", projectDir, home)) {
+    boards.push({ value: "planning-game", label: "Planning Game (MCP detected)" });
+  }
+  for (const [slug, envs] of Object.entries(TOKEN_CONVENTIONS)) {
+    const token = envs.find((k) => env[k]);
+    if (token) boards.push({ value: `external:${slug}`, label: `${slug} (token ${token})` });
+    else if (mcpConfigsMention(slug, projectDir, home)) boards.push({ value: `external:${slug}`, label: `${slug} (MCP detected)` });
+  }
+  return boards;
+}
+
 export function verifyBoardAccess({ config = {}, projectDir = process.cwd(), env = process.env, home = os.homedir() } = {}) {
   const backend = config.state_backend || "hu-board";
 

package/src/environment/board-select.js

@@ -0,0 +1,58 @@
+/**
+ * board-select (KJC-TSK-0709) — never hu-board silently when alternatives
+ * are reachable. Field case 2026-08-02: an install defaulted to hu-board
+ * with the user's Planning Game MCP sitting configured and detectable.
+ * Interactive installs ASK and persist the choice; headless installs name
+ * the default and the exact line to change it. Declared = never asked.
+ */
+
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { parse as parseYaml, parseDocument } from "yaml";
+import { detectAvailableBoards } from "./board-access.js";
+import { getConfigPath, getProjectConfigPath } from "../config.js";
+
+// "Declared" means the USER wrote state_backend in a config FILE — the
+// merged config object always carries the hu-board default (defaults.js),
+// so it can never tell a choice from a fallback.
+async function declaredStateBackend(projectDir) {
+  for (const p of [getProjectConfigPath(projectDir), getConfigPath()]) {
+    try {
+      const raw = parseYaml(await fs.readFile(p, "utf8")) || {};
+      if (raw.state_backend) return { backend: raw.state_backend, boardName: raw.board?.name || null };
+    } catch { /* missing or unreadable — keep looking */ }
+  }
+  return null;
+}
+
+async function persistStateBackend(projectDir, backend, boardName) {
+  const configPath = getProjectConfigPath(projectDir);
+  let source = "";
+  try { source = await fs.readFile(configPath, "utf8"); } catch { /* no config yet — create it */ }
+  const doc = parseDocument(source || "{}");
+  doc.setIn(["state_backend"], backend);
+  if (boardName) doc.setIn(["board", "name"], boardName);
+  await fs.mkdir(path.dirname(configPath), { recursive: true });
+  await fs.writeFile(configPath, doc.toString(), "utf8");
+  return configPath;
+}
+
+export async function pickStateBackend({ projectDir = process.cwd(), home = os.homedir(), env = process.env, wizard = null, isTTY = false, logger = console } = {}) {
+  const declared = await declaredStateBackend(projectDir);
+  if (declared) return { ...declared, source: "declared" };
+  const boards = detectAvailableBoards({ projectDir, home, env });
+  if (boards.length <= 1) return { backend: "hu-board", boardName: null, source: "default" };
+  if (!wizard || !isTTY) {
+    logger.info?.(`⚠ board: defaulting to the bundled HU Board, but this machine can reach: ${boards.slice(1).map((b) => b.label).join(", ")} — switch with \`state_backend: planning-game\` (or \`external\` + board.name) in .karajan/kj.config.yml and re-run kj env install`);
+    return { backend: "hu-board", boardName: null, source: "default-informed" };
+  }
+  logger.info?.("Karajan needs a board (there is no 'none') — pick where card-first work lives:");
+  const value = await wizard.select("Which board governs this project?", boards);
+  const external = value.startsWith("external:");
+  const backend = external ? "external" : value;
+  const boardName = external ? value.slice("external:".length) : null;
+  await persistStateBackend(projectDir, backend, boardName);
+  logger.info?.(`✓ board: ${backend}${boardName ? ` (${boardName})` : ""} — persisted in .karajan/kj.config.yml`);
+  return { backend, boardName, source: "chosen" };
+}

package/src/environment/mcp-wiring.js

@@ -0,0 +1,44 @@
+/**
+ * mcp-wiring — RAG as a NATIVE tool (KJC-TSK-0711). Field case 2026-08-03:
+ * agents in karajan projects grep code by hand because the RAG is only "a
+ * Bash command a text line told them about". Agents use the tools in their
+ * toolbox, so env install wires kj's RAG-only MCP server (`kj-rag-mcp`,
+ * ships with the package) into the project's `.mcp.json` — the official
+ * path must be cheaper than the shortcut. Merge preserves the user's
+ * entries; invalid JSON is left untouched (preserve, never clobber).
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export function installProjectMcp({ projectDir = process.cwd(), logger = console } = {}) {
+  const mcpPath = join(projectDir, ".mcp.json");
+  let cfg = {};
+  if (existsSync(mcpPath)) {
+    try {
+      cfg = JSON.parse(readFileSync(mcpPath, "utf8"));
+    } catch {
+      logger.warn?.(`kj env: ${mcpPath} is not valid JSON — leaving it untouched (wire kj-rag-mcp manually for native RAG queries)`);
+      return { wired: false, reason: "invalid-json" };
+    }
+  }
+  if (cfg.mcpServers && typeof cfg.mcpServers !== "object") {
+    logger.warn?.(`kj env: ${mcpPath} has a non-object mcpServers — leaving it untouched`);
+    return { wired: false, reason: "unexpected-shape" };
+  }
+  cfg.mcpServers = cfg.mcpServers || {};
+  // Wired = the LAUNCH SPEC runs kj-rag-mcp (command or an arg, so `npx
+  // kj-rag-mcp` and absolute paths count) — never env/description fields.
+  const launchesRagMcp = (s) =>
+    Boolean(s) && typeof s === "object" && (
+      (typeof s.command === "string" && s.command.includes("kj-rag-mcp")) ||
+      (Array.isArray(s.args) && s.args.some((a) => typeof a === "string" && a.includes("kj-rag-mcp")))
+    );
+  const present = Object.values(cfg.mcpServers).some(launchesRagMcp);
+  if (!present) {
+    cfg.mcpServers["kj-rag"] = { command: "kj-rag-mcp", args: [] };
+    writeFileSync(mcpPath, `${JSON.stringify(cfg, null, 2)}\n`);
+    logger.info?.("✓ kj_rag_query wired as a NATIVE tool (.mcp.json → kj-rag-mcp): querying the RAG is now the agent's cheapest path");
+  }
+  return { wired: true, added: !present };
+}

package/src/environment/playbook.js

@@ -57,7 +57,8 @@ carries a cross-AI verdict.
 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.
+  what the codebase does. In MCP hosts the same index is the native
+  \`kj_rag_query\` tool: reach for it before grepping by hand.
 - ${trackingLine(stateBackend, boardName)}
 - Tests prove behavior: the failing test exists first (TDD), and the suite
   is never left red.