karajan-code 4.1.1 → 4.1.3

package/package.json

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

package/scripts/install-binary.sh

@@ -1,31 +1,36 @@
 #!/bin/sh
-# Karajan Code — standalone binary installer (no Node required).
+# Karajan Code installer — guarantees a COMPLETE install (KJC-TSK-0658).
 #
 #   curl -fsSL https://karajancode.com/install.sh | sh
 #
-# Downloads the prebuilt `kj` binary for your OS/arch from the GitHub
-# release, verifies its SHA256 checksum, and installs it to ~/.local/bin.
-# Override with env vars: KJ_VERSION (e.g. v3.7.2), KJ_INSTALL_DIR.
+# Default route: npm — the full product (CLI + RAG + HU Board + MCP).
+#   1. Node >= 22.12 present  → npm install -g karajan-code
+#   2. No usable Node         → auto-provision official Node LTS into
+#      ~/.karajan/node (checksum-verified, nothing system-wide touched),
+#      install karajan-code with it, symlink kj into ~/.local/bin.
+# Standalone route (CLI only, no native-module features — RAG/board/MCP
+# unavailable): opt-in with `--standalone` or KJ_STANDALONE=1.
 #
-# POSIX sh only — no bashisms, no Node. KJC-TSK-0593.
+# POSIX sh only. Env overrides: KJ_VERSION, KJ_INSTALL_DIR.
 set -eu
 
 REPO="manufosela/karajan-code"
 VERSION="${KJ_VERSION:-latest}"
 INSTALL_DIR="${KJ_INSTALL_DIR:-$HOME/.local/bin}"
+NODE_MAJOR="22"
+NODE_MIN_MINOR="12"
+MODE="full"
+[ "${1:-}" = "--standalone" ] && MODE="standalone"
+[ "${KJ_STANDALONE:-0}" = "1" ] && MODE="standalone"
 
-die() {
-  echo "kj-install: $1" >&2
-  exit 1
-}
+die() { echo "kj-install: $1" >&2; exit 1; }
 
-# --- Detect OS/arch, map to the release asset names we actually build. ---
-os="$(uname -s)"
-arch="$(uname -m)"
+# --- Detect OS/arch (shared by both routes). ---
+os="$(uname -s)"; arch="$(uname -m)"
 case "$os" in
   Linux) os="linux" ;;
   Darwin) os="darwin" ;;
-  *) die "unsupported OS '$os'. Supported: Linux, macOS. Use npm instead: npm install -g karajan-code" ;;
+  *) die "unsupported OS '$os'. Supported: Linux, macOS." ;;
 esac
 case "$arch" in
   x86_64 | amd64) arch="x64" ;;
@@ -33,80 +38,122 @@ case "$arch" in
   *) die "unsupported architecture '$arch'" ;;
 esac
 
-target="${os}-${arch}"
-case "$target" in
-  linux-x64) ;;
-  darwin-arm64) ;;
-  *) die "no prebuilt binary for '$target'. Available: linux-x64, darwin-arm64. Use npm instead: npm install -g karajan-code" ;;
-esac
+# --- Downloader + checksum tool. ---
+if command -v curl >/dev/null 2>&1; then fetch() { curl -fsSL "$1" -o "$2"; }
+elif command -v wget >/dev/null 2>&1; then fetch() { wget -qO "$2" "$1"; }
+else die "need curl or wget"; fi
+if command -v sha256sum >/dev/null 2>&1; then sha256() { sha256sum "$1" | cut -d' ' -f1; }
+elif command -v shasum >/dev/null 2>&1; then sha256() { shasum -a 256 "$1" | cut -d' ' -f1; }
+else die "need sha256sum or shasum to verify downloads"; fi
 
-# --- Resolve the download URL for the requested version (or latest). ---
-asset="kj-${target}"
-if [ "$VERSION" = "latest" ]; then
-  base="https://github.com/${REPO}/releases/latest/download"
-else
-  base="https://github.com/${REPO}/releases/download/${VERSION}"
-fi
+tmp="$(mktemp -d "${TMPDIR:-/tmp}/kj-install.XXXXXX")"
+trap 'rm -rf "$tmp"' EXIT INT TERM
 
-# --- Pick a downloader. ---
-if command -v curl >/dev/null 2>&1; then
-  fetch() { curl -fsSL "$1" -o "$2"; }
-elif command -v wget >/dev/null 2>&1; then
-  fetch() { wget -qO "$2" "$1"; }
-else
-  die "need curl or wget to download the binary"
-fi
+path_hint() {
+  case ":${PATH}:" in
+    *":$1:"*) ;;
+    *) echo "kj-install: add '$1' to your PATH:  export PATH=\"$1:\$PATH\"  (persist it in ~/.bashrc / ~/.zshrc)" ;;
+  esac
+}
+
+# --- Is there a usable Node (>= NODE_MAJOR.NODE_MIN_MINOR)? ---
+node_ok() {
+  command -v node >/dev/null 2>&1 || return 1
+  v="$(node --version 2>/dev/null | sed 's/^v//')"
+  major="${v%%.*}"; rest="${v#*.}"; minor="${rest%%.*}"
+  [ "$major" -gt "$NODE_MAJOR" ] 2>/dev/null && return 0
+  [ "$major" -eq "$NODE_MAJOR" ] 2>/dev/null && [ "$minor" -ge "$NODE_MIN_MINOR" ] 2>/dev/null
+}
+
+npm_pkg() { if [ "$VERSION" = "latest" ]; then echo "karajan-code"; else echo "karajan-code@${VERSION#v}"; fi; }
+
+if [ "$MODE" = "full" ]; then
+  if node_ok; then
+    echo "kj-install: Node $(node --version) found — installing via npm (full product)..."
+    npm install -g "$(npm_pkg)" || die "npm install failed. If it was a permissions error, set a user prefix (npm config set prefix ~/.local) and re-run."
+    echo "kj-install: installed $(kj --version 2>/dev/null || echo karajan-code). Run 'kj doctor' next."
+    exit 0
+  fi
 
-# --- Pick a checksum tool. ---
-if command -v sha256sum >/dev/null 2>&1; then
-  sha256() { sha256sum "$1" | cut -d' ' -f1; }
-elif command -v shasum >/dev/null 2>&1; then
-  sha256() { shasum -a 256 "$1" | cut -d' ' -f1; }
-else
-  die "need sha256sum or shasum to verify the download"
+  echo "kj-install: no usable Node (need >= ${NODE_MAJOR}.${NODE_MIN_MINOR}) — provisioning official Node LTS into ~/.karajan/node (nothing system-wide)..."
+  dist="https://nodejs.org/dist/latest-v${NODE_MAJOR}.x"
+  fetch "${dist}/SHASUMS256.txt" "${tmp}/SHASUMS256.txt" || die "could not fetch the Node checksum list"
+  node_asset="$(grep -o "node-v[0-9.]*-${os}-${arch}\.tar\.gz" "${tmp}/SHASUMS256.txt" | head -1)"
+  [ -n "$node_asset" ] || die "no official Node build for ${os}-${arch}"
+  echo "kj-install: downloading ${node_asset}..."
+  fetch "${dist}/${node_asset}" "${tmp}/${node_asset}" || die "could not download Node"
+  expected="$(grep "${node_asset}\$" "${tmp}/SHASUMS256.txt" | head -1 | cut -d' ' -f1)"
+  actual="$(sha256 "${tmp}/${node_asset}")"
+  [ "$expected" = "$actual" ] || die "Node checksum mismatch — aborting, nothing installed"
+
+  # Stage the whole install (extract + npm install) in a sibling dir and only
+  # swap it into place once EVERYTHING succeeded — a failed download/extract/
+  # install must never destroy a previous working ~/.karajan/node.
+  node_home="$HOME/.karajan/node"
+  staging="${node_home}.staging.$$"
+  rm -rf "$staging"; mkdir -p "$staging"
+  trap 'rm -rf "$tmp" "$staging"' EXIT INT TERM
+  tar -xzf "${tmp}/${node_asset}" -C "$staging" --strip-components=1 || die "could not extract Node"
+
+  echo "kj-install: installing karajan-code with the provisioned Node..."
+  PATH="${staging}/bin:$PATH" "${staging}/bin/npm" install -g "$(npm_pkg)" || die "npm install failed with the provisioned Node"
+
+  # Swap keeping the previous install recoverable at EVERY instant: park it
+  # as a backup, arm a trap that restores it on any exit (signal included),
+  # move the staged one in, and only then disarm the trap and drop the
+  # backup — the user can never end up without a working install.
+  backup="${node_home}.old.$$"
+  if [ -e "$node_home" ]; then
+    mv "$node_home" "$backup" || die "could not park the previous install"
+    trap '[ -e "$node_home" ] || mv "$backup" "$node_home" 2>/dev/null; rm -rf "$tmp" "$staging"' EXIT INT TERM
+  fi
+  mv "$staging" "$node_home" || die "could not move the staged install into place (previous install restored)"
+  trap 'rm -rf "$tmp"' EXIT INT TERM
+  rm -rf "$backup"
+  mkdir -p "$INSTALL_DIR"
+  # Wrappers, not symlinks: the shebang (#!/usr/bin/env node) must find the
+  # provisioned Node even though it is not on the user's PATH.
+  for bin in kj karajan-mcp; do
+    [ -e "${node_home}/bin/${bin}" ] || continue
+    {
+      echo '#!/bin/sh'
+      echo "export PATH=\"${node_home}/bin:\$PATH\""
+      echo "exec \"${node_home}/bin/${bin}\" \"\$@\""
+    } >"${INSTALL_DIR}/${bin}"
+    chmod +x "${INSTALL_DIR}/${bin}"
+  done
+  installed="$("${INSTALL_DIR}/kj" --version 2>/dev/null || echo '?')"
+  echo "kj-install: installed kj ${installed} (full product) — kj at ${INSTALL_DIR}/kj"
+  path_hint "$INSTALL_DIR"
+  echo "kj-install: next — run 'kj doctor', then 'kj install-tools' to complete the whole stack."
+  exit 0
 fi
 
-# --- Download to a temp dir; only install after the checksum matches. ---
-tmp="$(mktemp -d "${TMPDIR:-/tmp}/kj-install.XXXXXX")"
-trap 'rm -rf "$tmp"' EXIT INT TERM
+# --- Standalone route: prebuilt single binary (CLI only). ---
+echo "kj-install: standalone mode — single binary, NO native-module features (RAG, HU Board and MCP need the npm install)."
+target="${os}-${arch}"
+case "$target" in
+  linux-x64 | darwin-arm64) ;;
+  *) die "no prebuilt binary for '$target' (available: linux-x64, darwin-arm64) — run without --standalone for the npm route" ;;
+esac
+asset="kj-${target}"
+if [ "$VERSION" = "latest" ]; then base="https://github.com/${REPO}/releases/latest/download"
+else base="https://github.com/${REPO}/releases/download/${VERSION}"; fi
 
 echo "kj-install: downloading ${asset} (${VERSION})..."
-fetch "${base}/${asset}" "${tmp}/kj" || die "could not download ${base}/${asset} — does that version/asset exist?"
+fetch "${base}/${asset}" "${tmp}/kj" || die "could not download ${base}/${asset}"
 fetch "${base}/${asset}.sha256" "${tmp}/kj.sha256" || die "could not download the checksum for ${asset}"
-
 expected="$(cut -d' ' -f1 <"${tmp}/kj.sha256")"
 actual="$(sha256 "${tmp}/kj")"
-[ "$expected" = "$actual" ] || die "checksum mismatch (expected ${expected}, got ${actual}). Aborting, nothing installed."
+[ "$expected" = "$actual" ] || die "checksum mismatch — aborting, nothing installed"
 
-# --- Install atomically: chmod on the temp file, then move into place. ---
 chmod +x "${tmp}/kj"
 mkdir -p "$INSTALL_DIR"
 mv -f "${tmp}/kj" "${INSTALL_DIR}/kj"
-
-# On macOS the binary is ad-hoc signed, not notarized with a paid Apple
-# certificate, so Gatekeeper can quarantine it. Clear the flag on the copy
-# we just checksummed ourselves (no-op on Linux / if the flag is absent).
 if [ "$os" = "darwin" ] && command -v xattr >/dev/null 2>&1; then
   xattr -d com.apple.quarantine "${INSTALL_DIR}/kj" 2>/dev/null || true
 fi
-
 installed="$("${INSTALL_DIR}/kj" --version 2>/dev/null || echo '?')"
-echo "kj-install: installed kj ${installed} to ${INSTALL_DIR}/kj"
-
-# --- Tell the user how to reach it if the dir is not on PATH. ---
-case ":${PATH}:" in
-  *":${INSTALL_DIR}:"*) echo "kj-install: '${INSTALL_DIR}' is on your PATH — run 'kj --help' to get started." ;;
-  *)
-    echo "kj-install: '${INSTALL_DIR}' is not on your PATH. Add it with:"
-    echo "  export PATH=\"${INSTALL_DIR}:\$PATH\""
-    echo "  (add that line to ~/.bashrc, ~/.zshrc or ~/.profile to make it permanent)"
-    ;;
-esac
-
-# --- Prerequisites: the binary bundles no toolchain. kj orchestrates ---
-# --- external tools, so name the hard requirements and let `kj doctor` ---
-# --- check them precisely for this machine.
-echo ""
-echo "kj-install: next step — run 'kj doctor' to check prerequisites."
-echo "  Required: git, plus at least one agent CLI (Claude Code, Codex or Gemini)."
-echo "  Optional: Docker (local models, SonarQube) and Node/npm (helper tools: Squeezr, qmd)."
+echo "kj-install: installed standalone kj ${installed} to ${INSTALL_DIR}/kj"
+path_hint "$INSTALL_DIR"
+echo "kj-install: next — run 'kj doctor'. For the full product later: re-run this installer without --standalone."

package/src/cli/advanced-commands.js

@@ -31,7 +31,7 @@ export const ADVANCED_GROUPS = [
   { title: "Análisis pre-run", commands: ["discover", "triage", "researcher", "architect", "onboard", "brief"] },
   { title: "Búsqueda / RAG", commands: ["rag", "qmd", "watch"] },
   { title: "Calidad / auditoría", commands: ["audit", "check", "mutate", "webperf", "sonar"] },
-  { title: "Sesión / board", commands: ["resume", "report", "board", "undo", "standby"] },
+  { title: "Sesión / board", commands: ["resume", "report", "board", "hu", "adr", "undo", "standby"] },
   { title: "Infra / setup", commands: ["install-tools", "ollama", "skills", "roles", "agents", "env"] },
   { title: "Mantenimiento", commands: ["clean", "sync", "telemetry", "report-issue"] },
 ];

package/src/cli/register-meta.js

@@ -22,6 +22,8 @@ import { telemetryPreviewCommand, telemetryStatusCommand } from "../commands/tel
 import { envInstallCommand, briefCommand } from "../commands/env.js";
 import { agentRunCommand } from "../commands/agent-run.js";
 import { reportIssueCommand } from "../commands/report-issue.js";
+import { huCommand } from "../commands/hu.js";
+import { addAdr, listAdrs } from "../environment/adr.js";
 import { formatAdvancedIndex } from "../commands/advanced.js";
 import { withConfig } from "./_shared.js";
 
@@ -133,7 +135,10 @@ export function registerMeta(program, { pkgVersion }) {
     .option("--no-rag", "Skip building the RAG index when the project has none (ENV-E1)")
     .action(async (flags) => {
       await withConfig(pkgVersion, "env-install", flags, async ({ config, logger }) => {
-        await envInstallCommand({ config, logger, flags });
+        const r = await envInstallCommand({ config, logger, flags });
+        // KJC-TSK-0659: exit 3 = pending user action (RAG cannot index) —
+        // a driving agent must stop and wait, never continue degraded.
+        if (Number.isInteger(r?.exitCode) && r.exitCode !== 0) process.exit(r.exitCode);
       });
     });
 
@@ -149,6 +154,55 @@ export function registerMeta(program, { pkgVersion }) {
       });
     });
 
+  // AB-H (KJC-TSK-0658): board writes + repo ADRs for the brain.
+  const hu = program.command("hu").description("Track work in the HU Board from any host agent (card first)");
+  hu.command("add <title>")
+    .option("--id <shortId>", "Human-readable short id")
+    .option("--criteria <text>", "Acceptance criteria")
+    .option("--json", "Machine-readable output")
+    .action(async (title, flags) => {
+      await withConfig(pkgVersion, "hu", flags, async ({ config }) => {
+        await huCommand({ config, action: "add", args: [title], flags });
+      });
+    });
+  hu.command("move <id> <status>")
+    .option("--json", "Machine-readable output")
+    .action(async (id, status, flags) => {
+      await withConfig(pkgVersion, "hu", flags, async ({ config }) => {
+        await huCommand({ config, action: "move", args: [id, status], flags });
+      });
+    });
+  hu.command("list")
+    .option("--json", "Machine-readable output")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "hu", flags, async ({ config }) => {
+        await huCommand({ config, action: "list", flags });
+      });
+    });
+
+  const adr = program.command("adr").description("Architecture decision records in .karajan/adrs/ (git-tracked)");
+  adr.command("add <title>")
+    .requiredOption("--decision <text>", "The decision itself")
+    .option("--context <text>", "Why this came up")
+    .option("--consequences <text>", "Trade-offs accepted")
+    .option("--json", "Machine-readable output")
+    .action(async (title, flags) => {
+      await withConfig(pkgVersion, "adr", flags, async ({ config }) => {
+        const res = await addAdr(config?.projectDir || process.cwd(), { title, ...flags });
+        console.log(flags.json ? JSON.stringify(res) : `✓ ADR ${res.number} created: ${res.file} — commit it`);
+      });
+    });
+  adr.command("list")
+    .option("--json", "Machine-readable output")
+    .action(async (flags) => {
+      await withConfig(pkgVersion, "adr", flags, async ({ config }) => {
+        const adrs = await listAdrs(config?.projectDir || process.cwd());
+        if (flags.json) { console.log(JSON.stringify(adrs)); return; }
+        for (const a of adrs) console.log(`${String(a.number).padStart(4, "0")}  ${a.status.padEnd(10)} ${a.title}`);
+        if (adrs.length === 0) console.log("no ADRs yet — create one with: kj adr add \"<title>\" --decision \"...\"");
+      });
+    });
+
   // AB-F (KJC-TSK-0655): self-healing — the brain files kj frictions upstream.
   program
     .command("report-issue")

package/src/commands/env.js

@@ -8,6 +8,7 @@ import { installPlaybook } from "../environment/playbook.js";
 import { renderBrief, listBriefs } from "../environment/briefs.js";
 import { openVecStore, projectSlug, getLastIndexedCommit } from "../rag/vec-store.js";
 import { ragIndexCommand } from "./rag.js";
+import { renderPendingBlock, PENDING_EXIT_CODE } from "../utils/pending-user-action.js";
 
 function hasRagIndex(config, projectDir) {
   const db = openVecStore({ dim: config?.rag?.embedder?.dim || 768 });
@@ -42,21 +43,38 @@ export async function envInstallCommand({ config = null, logger = null, flags =
   console.log(`✓ Karajan playbook installed in: ${result.files.join(", ")}`);
 
   // ENV-E1: RAG-first — the playbook orders "query the RAG before coding",
-  // so installing the environment guarantees the index exists. An indexing
-  // failure is reported but never blocks the playbook install.
+  // so installing the environment guarantees the index exists. KJC-TSK-0659
+  // stop-on-sudo: an index that cannot be built is a BLOCKING condition —
+  // "success" with 0 chunks would leave every future session running the
+  // method against an empty RAG (field-reproduced: 0/727 without Ollama).
+  // The playbook stays installed; the command exits 3 so the driving agent
+  // stops, shows the block, and waits for the user.
   if (flags.rag !== false) {
+    const provider = config?.rag?.embedder?.provider || "ollama";
+    const blockRag = (why) => {
+      result.ragError = why;
+      result.exitCode = PENDING_EXIT_CODE;
+      const item = provider === "ollama"
+        ? { tool: "ollama", action: "needs-user", reason: `the RAG cannot index: ${why}` }
+        : { tool: `${provider} embedder`, action: "needs-user", reason: `the RAG cannot index: ${why} — check rag.embedder in kj config`, manualUrl: "kj config" };
+      console.log(renderPendingBlock([item], { retry: "kj rag index --with-sources   (then re-run: kj env install)" }));
+    };
     try {
       if (hasRagIndex(config, projectDir)) {
         console.log("✓ RAG index present");
       } else {
         console.log("⏳ no RAG index for this project — building it (first time only)…");
-        await ragIndexCommand({ config, logger, flags: { withSources: true } });
+        const totals = await ragIndexCommand({ config, logger, flags: { withSources: true } });
+        if ((totals?.indexed ?? 0) === 0 && (totals?.files ?? 0) > 0) {
+          blockRag(`0 of ${totals.files} files indexed — is the embedder running?`);
+        }
       }
     } catch (err) {
-      result.ragError = err.message;
-      console.log(`⚠ RAG index could not be built (${err.message}) — run \`kj rag index --with-sources\` later`);
+      blockRag(err.message);
     }
   }
-  console.log("  The host agent now follows the method: RAG first, TDD, cross-AI review before commit.");
+  if (result.exitCode !== PENDING_EXIT_CODE) {
+    console.log("  The host agent now follows the method: RAG first, TDD, cross-AI review before commit.");
+  }
   return result;
 }

package/src/commands/hu.js

@@ -0,0 +1,92 @@
+/**
+ * `kj hu add|move|list` (AB-H, KJC-TSK-0658) — board writes for the brain.
+ * The v4 playbook orders "card first", but until now only the headless
+ * planner could create HUs. These commands operate on a per-project
+ * "brain-backlog" plan (created on first use) so any host agent can track
+ * work in the HU Board without the subprocess pipeline.
+ */
+import { addHu, updateHuStatus } from "../plan/plan-hu-ops.js";
+import { generatePlanId } from "../plan/plan-id.js";
+import { savePlan, listPlans, loadPlan } from "../plan/plan-store.js";
+
+export const HU_STATUSES = ["pending", "running", "done", "failed", "skipped"];
+const BACKLOG_NAME = "brain-backlog";
+
+async function backlogPlan(projectDir) {
+  const plans = await listPlans(projectDir);
+  const existing = plans.find((p) => p.alias === BACKLOG_NAME || p.name === BACKLOG_NAME);
+  if (existing) return loadPlan(projectDir, existing.planId);
+  const plan = {
+    version: 2, planId: generatePlanId(), name: BACKLOG_NAME,
+    task: "Host-agent tracked work (v4 environment)",
+    status: "ready", hus: [], createdAt: new Date().toISOString(),
+  };
+  const planId = await savePlan(projectDir, plan);
+  return loadPlan(projectDir, planId);
+}
+
+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; };
+
+  if (action === "list") {
+    const plans = await listPlans(projectDir);
+    const rows = [];
+    for (const meta of plans) {
+      const plan = await loadPlan(projectDir, meta.planId);
+      for (const h of plan.hus || []) {
+        rows.push({ id: h.id, short_id: h.short_id, title: h.title, status: h.status, plan: plan.alias || plan.planId });
+      }
+    }
+    if (flags.json) { console.log(JSON.stringify(rows)); return rows; }
+    for (const r of rows) console.log(`${(r.short_id || r.id).padEnd(28)} ${r.status.padEnd(8)} ${r.title}`);
+    if (rows.length === 0) console.log("no HUs yet — create one with: kj hu add \"<story>\"");
+    return rows;
+  }
+
+  if (action === "add") {
+    const title = args[0];
+    if (!title || !title.trim()) throw new Error("kj hu add requires a title: kj hu add \"<story>\"");
+    const plan = await backlogPlan(projectDir);
+    const hu = addHu(plan, {
+      title,
+      short_id: flags.id || null,
+      acceptance_criteria: flags.criteria ? [flags.criteria] : [],
+    });
+    await savePlan(projectDir, plan);
+    return emit({ id: hu.id, short_id: hu.short_id, status: hu.status },
+      `✓ HU created: ${hu.short_id || hu.id} (pending) — it shows up in \`kj board\``);
+  }
+
+  if (action === "move") {
+    const [ref, status] = args;
+    if (!ref || !status) throw new Error("usage: kj hu move <id> <status>");
+    if (!HU_STATUSES.includes(status)) {
+      throw new Error(`invalid status "${status}" — valid: ${HU_STATUSES.join(", ")}`);
+    }
+    // Exact canonical id wins outright (it IS the disambiguator); only then
+    // fall back to short_id matches — which can repeat between plans, so
+    // silently moving the first hit could move the wrong card.
+    const byId = [];
+    const byShort = [];
+    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 });
+      }
+    }
+    const matches = byId.length > 0 ? byId : byShort;
+    if (matches.length === 0) throw new Error(`HU "${ref}" not found — see kj hu list`);
+    if (matches.length > 1) {
+      const ids = matches.map((m) => m.hu.id).join(", ");
+      throw new Error(`"${ref}" is ambiguous (${matches.length} matches: ${ids}) — use the full id`);
+    }
+    const { plan, hu } = matches[0];
+    updateHuStatus(plan, hu.id, status);
+    await savePlan(projectDir, plan);
+    return emit({ id: hu.id, status }, `✓ ${hu.short_id || hu.id} → ${status}`);
+  }
+
+  throw new Error(`unknown action "${action}" — use: add | move | list`);
+}

package/src/commands/install-tools.js

@@ -23,12 +23,23 @@ import { detectProjectStack } from "../utils/stack-detect.js";
 import { resolveStandalone } from "../utils/binary-sources.js";
 import { downloadBinary, binDir, runInstallCommand } from "../utils/tool-installer.js";
 import { dockerInstallPlan } from "../utils/docker-install.js";
+import { collectPending, renderPendingBlock, PENDING_EXIT_CODE } from "../utils/pending-user-action.js";
 
 const execFileAsync = promisify(execFile);
 
 // git and the agent CLI lead the list: both are `kj doctor` *required* tools,
 // so a blank machine wants them before the optional audit tools.
-const ALL_TOOLS = ["git", "agent-cli", "semgrep", "osv-scanner", "lighthouse", "docker", "sonar"];
+// KJC-TSK-0657: rtk/squeezr/qmd (token+context optimizers, previously
+// init-only) complete the list — one pass leaves the machine 100%
+// operational, per the quality-default-on product rule.
+const ALL_TOOLS = ["git", "agent-cli", "semgrep", "osv-scanner", "lighthouse", "docker", "sonar", "rtk", "squeezr", "qmd"];
+
+// Optimizer tools reuse the init installers (same {ok, version, error} contract).
+const OPTIMIZER_INSTALLERS = {
+  rtk: () => import("../utils/rtk-install.js").then((m) => m.installRtk),
+  squeezr: () => import("../utils/squeezr-install.js").then((m) => m.installSqueezr),
+  qmd: () => import("../utils/qmd-install.js").then((m) => m.installQmd),
+};
 
 // The default pipeline is coder=claude, reviewer=codex, so `agent-cli` installs
 // exactly those two. gemini stays out of the default: it is a supported
@@ -335,6 +346,22 @@ export async function installToolsCommand(opts = {}) {
       continue;
     }
 
+    if (OPTIMIZER_INSTALLERS[tool]) {
+      if (dryRun) {
+        results.push({ tool, action: "planned", command: `kj install-tools --only ${tool}` });
+        logger.info?.(`▸ ${tool}: would install (init installer)`);
+        continue;
+      }
+      const proceed = yes || await promptYesNo(`Install ${tool}?`);
+      if (!proceed) { results.push({ tool, action: "declined" }); continue; }
+      const install = await OPTIMIZER_INSTALLERS[tool]();
+      const r = await install(logger);
+      results.push(r.ok
+        ? { tool, action: "installed", version: r.version }
+        : { tool, action: "failed", error: r.error });
+      continue;
+    }
+
     if (tool === "git") {
       const result = await handleGit({ available, dryRun, yes, logger });
       results.push(result);
@@ -390,8 +417,16 @@ export async function installToolsCommand(opts = {}) {
     }
   }
 
+  // KJC-TSK-0659 stop-on-sudo: anything that still needs the user's hands
+  // becomes ONE block with the exact per-OS commands, and a distinctive exit
+  // code so a driving agent stops and waits instead of continuing degraded.
+  const pending = dryRun ? [] : collectPending(results, { yes });
+  if (pending.length > 0) {
+    logger.warn?.(renderPendingBlock(pending));
+    return { results, pending, exitCode: PENDING_EXIT_CODE };
+  }
   const failures = results.filter((r) => r.action === "failed").length;
-  return { results, exitCode: failures > 0 ? 1 : 0 };
+  return { results, pending, exitCode: failures > 0 ? 1 : 0 };
 }
 
 export const __test = { parseOnlyList, isInstalled, ALL_TOOLS };

package/src/environment/adr.js

@@ -0,0 +1,45 @@
+/**
+ * ADRs in the repo (AB-H, KJC-TSK-0658) — `kj adr add|list`. Architecture
+ * decisions live as numbered markdown under .karajan/adrs/, git-tracked so
+ * the whole team (and every brain) inherits them. The architect brief's
+ * "check the ADRs before deciding" now has a target on every backend.
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const ADR_DIR = path.join(".karajan", "adrs");
+
+const slugify = (t) => t.toLowerCase().replaceAll(/[^a-z0-9]+/g, "-").replaceAll(/^-|-$/g, "").slice(0, 60);
+
+export async function listAdrs(projectDir) {
+  const dir = path.join(projectDir, ADR_DIR);
+  let files;
+  try { files = await fs.readdir(dir); } catch { return []; }
+  const adrs = [];
+  for (const f of files.filter((f) => /^\d{4}-.*\.md$/.test(f)).sort()) {
+    const text = await fs.readFile(path.join(dir, f), "utf8");
+    const title = text.match(/^# (.+)$/m)?.[1] || f;
+    const status = text.match(/^Status: (.+)$/m)?.[1] || "accepted";
+    adrs.push({ file: path.join(ADR_DIR, f), number: Number(f.slice(0, 4)), title, status });
+  }
+  return adrs;
+}
+
+export async function addAdr(projectDir, { title, decision, context = "", consequences = "" }) {
+  if (!title?.trim() || !decision?.trim()) {
+    throw new Error("kj adr add requires a title and --decision");
+  }
+  const existing = await listAdrs(projectDir);
+  const number = (existing.at(-1)?.number || 0) + 1;
+  const file = path.join(ADR_DIR, `${String(number).padStart(4, "0")}-${slugify(title)}.md`);
+  const body = [
+    `# ${title}`, "",
+    `Status: accepted`, `Date: ${new Date().toISOString().slice(0, 10)}`, "",
+    ...(context ? ["## Context", "", context, ""] : []),
+    "## Decision", "", decision, "",
+    ...(consequences ? ["## Consequences", "", consequences, ""] : []),
+  ].join("\n");
+  await fs.mkdir(path.join(projectDir, ADR_DIR), { recursive: true });
+  await fs.writeFile(path.join(projectDir, file), body);
+  return { number, file, title };
+}

package/src/environment/playbook.js

@@ -29,7 +29,7 @@ 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.
 const BACKEND_TRACKING = {
-  "hu-board": "Every piece of work has a tracked story/bug in the HU Board (`kj board`) before it starts.",
+  "hu-board": "Every piece of work has a tracked story/bug in the HU Board (`kj hu add` / `kj board`) before it starts.",
   "planning-game": "Every piece of work has a tracked card in the Planning Game MCP before it starts (In Progress while you work it).",
 };
 
@@ -58,8 +58,9 @@ Invariants (the git gates enforce these — they are not suggestions):
   through an atomic PR (~150 net lines, Conventional Commits).
 
 Commands: \`kj rag query\` · \`kj brief <role>\` (triage, planner, researcher,
-architect, tester, security, audit) · \`kj review --staged\` · \`kj review --check\` ·
-\`kj solomon --position\` · \`kj agent run <agent>\` · \`kj report\` · \`kj check\`
+architect, tester, security, audit) · \`kj hu add|move|list\` · \`kj adr add|list\` ·
+\`kj review --staged\` · \`kj review --check\` · \`kj solomon --position\` ·
+\`kj agent run <agent>\` · \`kj report\` · \`kj check\`
 
 Hit a kj bug or friction? Diagnose it and file it upstream with
 \`kj report-issue\` (sanitized; ask your user before \`--publish\`).

package/src/harden/advisory.js

@@ -21,11 +21,38 @@ const BLOCK_VERSION = 1; // current version every markered config ships at
 // Other filenames/formats for the same artifact, so kj never reports a false
 // "missing". `pkgKey` is a package.json field that can hold inline config.
 const EQUIVALENTS = {
-  commitlint: { files: [".commitlintrc", ".commitlintrc.js", ".commitlintrc.json", ".commitlintrc.yaml"], pkgKey: "commitlint" },
-  eslint: { files: ["eslint.config.mjs", ".eslintrc.js", ".eslintrc.cjs", ".eslintrc.json", ".eslintrc.yaml"], pkgKey: "eslintConfig" },
-  prettier: { files: [".prettierrc", ".prettierrc.js", ".prettierrc.yaml", "prettier.config.js"], pkgKey: "prettier" },
+  commitlint: { files: [".commitlintrc", ".commitlintrc.js", ".commitlintrc.cjs", ".commitlintrc.mjs", ".commitlintrc.json", ".commitlintrc.yaml", ".commitlintrc.yml", "commitlint.config.mjs", "commitlint.config.cjs", "commitlint.config.ts"], pkgKey: "commitlint" },
+  eslint: { files: ["eslint.config.mjs", "eslint.config.cjs", "eslint.config.ts", "eslint.config.mts", "eslint.config.cts", ".eslintrc.js", ".eslintrc.cjs", ".eslintrc.json", ".eslintrc.yaml", ".eslintrc.yml"], pkgKey: "eslintConfig" },
+  prettier: { files: [".prettierrc", ".prettierrc.js", ".prettierrc.yaml", ".prettierrc.yml", ".prettierrc.json5", ".prettierrc.toml", "prettier.config.js", "prettier.config.mjs", "prettier.config.cjs", "prettier.config.ts"], pkgKey: "prettier" },
 };
 
+/**
+ * KJC-BUG-0119 — same-tool filename variant for `artifactId` in any of
+ * `searchDirs` (file or inline package.json config); null when none exists.
+ * Seeding kj's default filename NEXT TO a variant eclipses the user's real
+ * config (eslint resolves eslint.config.js before .mjs), so config-engine
+ * must consult this before treating an artifact as absent.
+ */
+export function findEquivalentIn(searchDirs, artifactId) {
+  const spec = EQUIVALENTS[artifactId];
+  if (!spec) return null;
+  for (const dir of searchDirs) {
+    for (const rel of spec.files) {
+      if (existsSync(join(dir, rel))) return rel;
+    }
+    if (spec.pkgKey && existsSync(join(dir, "package.json"))) {
+      try {
+        if (JSON.parse(readFileSync(join(dir, "package.json"), "utf8"))[spec.pkgKey] != null) {
+          return `package.json#${spec.pkgKey}`;
+        }
+      } catch {
+        /* unreadable package.json → not a match */
+      }
+    }
+  }
+  return null;
+}
+
 // Concrete gains kj's standard would add to a USER_OWNED config, detected by
 // substring probes (no AST parse): each probe absent from the user's content
 // becomes one improvement. Heuristic by design — conservative, never a false
@@ -70,19 +97,8 @@ function toArtifact(cfg) {
 
 /** Locate the user's file for an artifact under `searchDir`; null if absent. */
 function findArtifactFile(searchDir, artifact) {
-  for (const rel of [artifact.file, ...artifact.equivalents]) {
-    if (existsSync(join(searchDir, rel))) return rel;
-  }
-  if (artifact.pkgKey && existsSync(join(searchDir, "package.json"))) {
-    try {
-      if (JSON.parse(readFileSync(join(searchDir, "package.json"), "utf8"))[artifact.pkgKey] != null) {
-        return `package.json#${artifact.pkgKey}`;
-      }
-    } catch {
-      /* unreadable package.json → not a match */
-    }
-  }
-  return null;
+  if (existsSync(join(searchDir, artifact.file))) return artifact.file;
+  return findEquivalentIn([searchDir], artifact.id);
 }
 
 /** Read the artifact body, or the JSON of an inline package.json key. */

package/src/harden/config-engine.js

@@ -9,6 +9,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 
 import { upsertManagedBlock } from "../utils/managed-markers.js";
+import { findEquivalentIn } from "./advisory.js";
 import { artifactIdForConfig, findAlternative } from "./alternatives.js";
 import { CONFIGS_BY_LANGUAGE, UNIVERSAL_CONFIGS } from "./config-templates.js";
 
@@ -37,6 +38,15 @@ function seedInto(targetDir, configs, dryRun, prefix, results, altDirs = [target
         results.push({ file, action: "covered", by: alt.foundAt });
         continue;
       }
+      // KJC-BUG-0119: a same-tool variant (eslint.config.mjs, .eslintrc.json,
+      // package.json#eslintConfig…) means the config already EXISTS — seeding
+      // kj's default filename next to it would silently ECLIPSE the user's
+      // real config (eslint resolves eslint.config.js before .mjs).
+      const variant = findEquivalentIn(altDirs, artifactIdForConfig(cfg));
+      if (variant) {
+        results.push({ file, action: "covered", by: variant });
+        continue;
+      }
     }
 
     if (cfg.json) {

package/src/utils/pending-user-action.js

@@ -0,0 +1,92 @@
+/**
+ * Stop-on-sudo policy (KJC-TSK-0659). When a tool cannot be installed
+ * automatically (sudo needed, no package-manager route, or the attempt
+ * failed), kj must NOT continue degraded — a RAG with 0 chunks because
+ * Docker was missing helps nobody. Instead: emit ONE block with the exact
+ * commands for this machine's OS and exit with a distinctive code so a
+ * driving agent stops, shows the block, and waits for the user.
+ */
+
+export const PENDING_EXIT_CODE = 3;
+
+const PENDING = new Set(["manual", "failed", "needs-user"]);
+
+// Exact per-OS commands for the tools kj cannot install unattended.
+// Multiple lines when the route depends on the distro/package manager.
+const OS_COMMANDS = {
+  docker: {
+    linux: ["sudo apt-get install -y docker.io   # Debian/Ubuntu", "sudo dnf install -y docker          # Fedora/RHEL"],
+    darwin: ["brew install --cask docker   # Docker Desktop, then open it once"],
+    win32: ["winget install Docker.DockerDesktop", "wsl --install   # if WSL2 is not set up yet"],
+  },
+  git: {
+    linux: ["sudo apt-get install -y git   # Debian/Ubuntu", "sudo dnf install -y git        # Fedora/RHEL"],
+    darwin: ["brew install git   # or: xcode-select --install"],
+    win32: ["winget install Git.Git"],
+  },
+  semgrep: {
+    linux: ["python3 -m pip install --user semgrep   # or: pipx install semgrep"],
+    darwin: ["brew install semgrep"],
+    win32: ["python -m pip install --user semgrep"],
+  },
+  "osv-scanner": {
+    linux: ["go install github.com/google/osv-scanner/v2/cmd/osv-scanner@v2   # or download from GitHub releases"],
+    darwin: ["brew install osv-scanner"],
+    win32: ["winget install Google.OSVScanner   # or download from GitHub releases"],
+  },
+  lighthouse: {
+    linux: ["npm install -g lighthouse"],
+    darwin: ["npm install -g lighthouse"],
+    win32: ["npm install -g lighthouse"],
+  },
+  ollama: {
+    linux: ["curl -fsSL https://ollama.com/install.sh | sh   # official installer (uses sudo)", "ollama pull nomic-embed-text"],
+    darwin: ["brew install ollama && brew services start ollama", "ollama pull nomic-embed-text"],
+    win32: ["winget install Ollama.Ollama", "ollama pull nomic-embed-text"],
+  },
+};
+
+/** Exact commands to install `tool` on `platform` (empty when unknown). */
+export function osCommandsFor(tool, platform = process.platform) {
+  return OS_COMMANDS[tool]?.[platform] ?? [];
+}
+
+/**
+ * Results that require the USER's hands. `manual`/`failed`/`needs-user`
+ * always qualify; `declined` only when nobody actually declined — a non-TTY
+ * run without --yes auto-answers the default, which for sudo installs is
+ * "no". A real interactive decline stays the user's own decision.
+ */
+export function collectPending(results, { tty = Boolean(process.stdin.isTTY), yes = false } = {}) {
+  return results.filter((r) => PENDING.has(r.action) || (r.action === "declined" && !tty && !yes));
+}
+
+/** The PENDING USER ACTION block: exact commands for THIS OS, then wait. */
+export function renderPendingBlock(pending, { platform = process.platform, retry = "kj install-tools" } = {}) {
+  const lines = [
+    "════ PENDING USER ACTION ════════════════════════════════════════",
+    "kj could not finish this install by itself (sudo or a platform",
+    "installer is required). Karajan needs a COMPLETE environment —",
+    "do not continue degraded.",
+    "",
+    "Run in YOUR terminal:",
+    "",
+  ];
+  for (const r of pending) {
+    const why = r.error ? `install failed: ${r.error}` : r.reason || "no automatic route on this machine";
+    lines.push(`  ▸ ${r.tool}  (${why})`);
+    const commands = r.commands
+      ?? (r.command ? [r.command] : null)
+      ?? (r.suggested ? [r.suggested] : null)
+      ?? (osCommandsFor(r.tool, platform).length > 0 ? osCommandsFor(r.tool, platform) : null)
+      ?? [`see ${r.manualUrl || "the tool's install docs"}`];
+    for (const c of commands) lines.push(`      ${c}`);
+    lines.push("");
+  }
+  lines.push(
+    `When done, re-run: ${retry}`,
+    "Agents: STOP here, show this block to your user, and WAIT for their",
+    `go-ahead. Exit code ${PENDING_EXIT_CODE} means "pending user action" — never proceed past it.`,
+  );
+  return lines.join("\n");
+}