@karajan-family/code 4.21.0

package/README.md

@@ -0,0 +1,98 @@
+<p align="center">
+  <img src="docs/karajan-orbit.svg" alt="Karajan Code" width="220">
+</p>
+
+<h1 align="center">Karajan Code</h1>
+
+<p align="center">
+  The environment that governs AI-driven development — your agent orchestrates, Karajan governs.
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/karajan-code"><img src="https://img.shields.io/npm/v/karajan-code.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/karajan-code"><img src="https://img.shields.io/npm/dw/karajan-code.svg" alt="npm downloads"></a>
+  <a href="https://github.com/manufosela/karajan-code/actions"><img src="https://github.com/manufosela/karajan-code/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.gnu.org/licenses/agpl-3.0"><img src="https://img.shields.io/badge/license-AGPL--3.0-blue.svg" alt="License"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg" alt="Node.js"></a>
+</p>
+
+<p align="center">
+  <a href="docs/README.es.md">Leer en Español</a> · <a href="https://karajancode.com">Documentation</a> · <a href="https://planning-game-xp.web.app/public/?project=Karajan%20Code">Public roadmap</a>
+</p>
+
+---
+
+Your AI agent (Claude Code, Codex, Copilot, Antigravity, 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. The install wires it as a native MCP tool (`kj_rag_query`) so querying the index is the agent's cheapest path. 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. A distilled engineering canon rides along: `kj rag query --library` serves pattern cards (when it applies, when it does NOT, the canonical citation) so plans name a greenfield alternative instead of following the legacy line by inertia.
+- **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.
+- **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, 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.
+- **Least privilege for agents** — spawned agent subprocesses receive an env allowlist (their own CLI's auth, never your cloud keys or registry tokens), and `kj check` inventories every MCP the project can reach, flagging what appeared since the last check. Sensitive-surface tasks self-invoke `kj audit --security` — a zero-token pass (prompt-injection over the agent-context files + OSV + Semgrep + Sonar) — and remediate before review.
+- **Nothing personal ships** — every outbound boundary audits before it leaves the machine: the pre-commit rejects a staged diff carrying your denylisted personal data, hardcoded platform tokens (`ghp_`, `sk-`, `AKIA`…) block outright, `verify-pack`-style tarball scans guard the publish, and `kj privacy scan <dir>` audits any build output. Your denylist lives in `~/.karajan/privacy.yml` — the install asks and writes it for you.
+- **Installing IS activating** — `kj env install` performs the enforcement itself (git hooks, verdict gate, tool gate) instead of trusting the agent to run setup steps, and ends by printing the method into the very conversation that installed it. A commit outside the method is rejected, not narrated.
+- **The turn cannot end red — the Sentinel** — a deterministic supervisor (zero LLM) wired into the harness's synchronous hooks records the method state of the session as tools run, and a Stop hook blocks the agent from ending its turn while method violations are open. The program rules, the agent thinks. See [guarantee levels](#guarantee-levels-governed-vs-supervised).
+- **The review panel never runs dry** — nine built-in agents (Claude Code, Codex, GitHub Copilot, Antigravity `agy` — the gemini successor —, Kimi Code, Qwen, OpenCode, Aider, Gemini legacy), and when the configured reviewer exhausts its quota, `kj review` switches to an authenticated candidate with a LOUD notice — or hands you the menu of candidates with their tier (free / subscription / local) and the exact login command. Never a silent failure, never the brain reviewing itself.
+
+This repo runs under its own environment: every commit to karajan-code carries a cross-AI verdict.
+
+## Install
+
+Tell your agent — in the directory where you want to work:
+
+```text
+I want to use Karajan in this project: read https://karajancode.com/start.md
+and do what it says.
+```
+
+The router prompt installs the full stack if needed, detects new vs existing project, activates the environment, and **stops to wait for you** whenever a step needs sudo or an account (`kj` exit code 3 = pending user action — a partial install is a failed install).
+
+Manual equivalent:
+
+```sh
+curl -fsSL https://karajancode.com/install.sh | sh   # full product (npm-first; --standalone for CLI-only)
+kj doctor && kj install-tools                        # complete the stack
+kj init && kj env install && kj harden && kj review --install-gate
+git config core.hooksPath .karajan/hooks
+```
+
+Requires git and at least one AI agent CLI — two enables cross-AI review; three enables arbitration. All install routes (npm, binaries, brew, Python wrapper) in the [install docs](https://karajancode.com/docs/v4/install/).
+
+## The daily loop
+
+1. You describe what you want. Your agent creates the card (`kj hu add`), queries the RAG, writes the failing test, then the code.
+2. `kj review --staged` — a different AI reviews the exact diff. Approved → commit enters. Rejected → fix, or escalate to `kj solomon`.
+3. Atomic PR to the base branch. `kj report` shows the trail; the HU Board (`kj board`) shows the work.
+4. Your agent hits a kj bug? `kj report-issue` files it upstream — sanitized, deduped, and only with your approval. The ecosystem repairs itself.
+
+Full method: [Work with your agent](https://karajancode.com/docs/v4/working-with-your-agent/) · [The gates](https://karajancode.com/docs/v4/gates/) · [Command reference](https://karajancode.com/docs/v4/commands/).
+
+## Guarantee levels: governed vs supervised
+
+Karajan **governs** any agent with git gates — the false green is structurally impossible no matter who writes, because the gates live in the repository, not in the agent's goodwill. On top of that, the **Karajan Sentinel** adds **supervision inside the turn**: `kj harden` wires deterministic hooks into the harness — one records the method state of the session as tools run (sources edited vs tests touched, escapes used), and a Stop hook blocks the agent from ending its turn while violations are open: sources edited on the base branch, a branch without a card, code without a single test touched. Every block states the exact violation and its remediation; `kj sentinel status` shows what the supervisor sees. It fails open — and says so — rather than ever hanging a session, and every `KJ_ALLOW_*` escape is recorded.
+
+Synchronous blocking hooks exist today only in Claude Code. That makes the supported setup explicit: **to guarantee a harness that controls the LLM, use Claude Code as the host** — Claude writes, Codex reviews (a review subprocess needs no hooks), and a third CLI arbitrates when available. On any other host Karajan still governs at the full git-gate level and tells you which level is active — it never pretends a supervision it cannot enforce.
+
+With a declared `.karajan/policy.yml`, the policy layer enforces at three tiers, and which tier applies depends on the host:
+
+| Tier | Where | Requires | What it guarantees |
+|---|---|---|---|
+| **A — tool time** | Sentinel PreToolUse → `kj policy eval --strict` | Claude Code as host (synchronous hooks) | The rule fires BEFORE the damage; the acting agent's role travels in `KJ_POLICY_ROLE` |
+| **B — commit time** | `kj review --staged` / pre-commit → deny + evidentiary exceptions | Any host (the gate lives in git) | The violating diff never enters, no matter who wrote it or what host ran it |
+| **C — merge time** | `kj-policy.yml` CI workflow → `kj policy check --range --strict` | GitHub Actions (seeded by `kj harden`) | Covers a tampered local hook: the PR diff is re-checked against the same policy, merge-blocking |
+
+Tier B is the guarantee floor — hosts without hooks lose A, never B; C re-verifies both. Security-class rules and consumer defaults are non-exemptable at every tier: no escape, no arbitration, no grant.
+
+## 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. 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)
+
+Karajan v1–v3 was a headless multiagent pipeline driven entirely by subprocess orchestration. Its full story — pipeline, 24 roles, MCP server, step mode, parallel lanes — is preserved in the **[v3 README (historical archive)](docs/README.v3.md)** and the [v3 docs archive](https://karajancode.com/docs/getting-started/introduction/).
+
+## Contributing & license
+
+Issues and PRs welcome — friction reports via `kj report-issue` are especially valuable. Licensed under [AGPL-3.0](LICENSE).

package/bin/karajan-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../src/mcp/server.js";

package/bin/kj-rag-mcp.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * kj-rag-mcp — standalone MCP server exposing only RAG tools.
+ *
+ * For external IDEs (Cursor, Windsurf, Continue, Zed) that want semantic
+ * search over a Karajan-indexed project without pulling in the full 27-tool
+ * orchestrator surface. Re-uses handleRagQuery / handleRagIndex from the
+ * main server, so behavior stays in sync with `karajan-mcp`.
+ */
+import path from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { handleRagQuery, handleRagIndex } from "../src/mcp/handlers/rag-handler.js";
+import { responseText, enrichedFailPayload } from "../src/mcp/shared-helpers.js";
+import { setupOrphanGuard } from "../src/mcp/orphan-guard.js";
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PKG_PATH = path.resolve(MODULE_DIR, "../package.json");
+const VERSION = JSON.parse(readFileSync(PKG_PATH, "utf8")).version;
+
+const RAG_TOOLS = [
+  {
+    name: "kj_rag_query",
+    description: "Semantic search across the indexed Karajan plans, onboarding briefs and (optionally) project source code. Returns the top-K nearest chunks with metadata so the agent can quote prior decisions or locate where a concept was last implemented. Empty until `kj_rag_index` has run at least once.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "Natural-language query." },
+        topK: { type: "number", description: "Max hits to return. Default 5." },
+        scope: { type: "string", description: "'plans' | 'code' | 'onboarding' | 'all' (default)." },
+        projectDir: { type: "string", description: "Absolute path to the project directory." }
+      },
+      required: ["text"]
+    }
+  },
+  {
+    name: "kj_rag_index",
+    description: "(Re)index this project's Karajan-managed assets into the local vector store. Idempotent. Pass `withSources: true` to also index project source files. Required as a one-time bootstrap before `kj_rag_query` returns anything.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        withSources: { type: "boolean", description: "Also index source files under projectDir. Default false." },
+        projectDir: { type: "string", description: "Absolute path to the project directory." }
+      }
+    }
+  }
+];
+
+const mcpServer = new McpServer(
+  { name: "kj-rag-mcp", version: VERSION },
+  { capabilities: { tools: {}, logging: {} } }
+);
+const server = mcpServer.server;
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: RAG_TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const name = request.params?.name;
+  const args = request.params?.arguments || {};
+  try {
+    if (name === "kj_rag_query") return responseText(await handleRagQuery(args, server));
+    if (name === "kj_rag_index") return responseText(await handleRagIndex(args, server));
+    return responseText({ ok: false, error: `Unknown tool: ${name}` });
+  } catch (error) {
+    return responseText(enrichedFailPayload(error, name));
+  }
+});
+
+setupOrphanGuard();
+
+const transport = new StdioServerTransport();
+await mcpServer.connect(transport);

package/bin/kj-tail

@@ -0,0 +1,361 @@
+#!/usr/bin/env bash
+# kj-tail — Real-time pipeline monitor for Karajan Code
+# Follows the run log and displays colorized, filtered output.
+
+set -euo pipefail
+
+VERSION="1.38.0"
+
+# ── Colors ──────────────────────────────────────────────
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[0;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+MAGENTA='\033[0;35m'
+GRAY='\033[0;90m'
+BOLD='\033[1m'
+DIM='\033[2m'
+RESET='\033[0m'
+
+# ── Defaults ────────────────────────────────────────────
+VERBOSE=false
+SHOW_AGENT_OUTPUT=false
+SHOW_TIMESTAMPS=false
+FOLLOW=true
+NUM_LINES=0
+PROJECT_DIR=""
+
+# ── Help ────────────────────────────────────────────────
+show_help() {
+  cat <<EOF
+${BOLD}kj-tail${RESET} — Real-time pipeline monitor for Karajan Code
+
+${BOLD}USAGE${RESET}
+  kj-tail [options] [project-dir]
+
+${BOLD}DESCRIPTION${RESET}
+  Follows the Karajan run log (<project>/.kj/run.log) and displays
+  colorized, filtered output. By default shows the same pipeline
+  progress view as 'kj run': stages, results, iterations, and errors.
+
+  Run this in a separate terminal while kj executes via MCP/CLI.
+
+${BOLD}OPTIONS${RESET}
+  -v, --verbose       Show agent heartbeats, budget, and metadata
+  -a, --agent-output  Show raw agent output lines (very noisy)
+  -t, --timestamps    Show timestamps on each line
+  -n, --lines <N>     Show last N lines then follow (default: follow only new)
+  -s, --snapshot      Show current log (no follow) — like 'cat' with colors
+  -h, --help          Show this help
+  --version           Show version
+
+${BOLD}EXAMPLES${RESET}
+  kj-tail                  # Follow current directory's run log
+  kj-tail /path/to/project # Follow a specific project's log
+  kj-tail -v               # Verbose: include heartbeats and budget
+  kj-tail -a               # Show everything including agent output
+  kj-tail -n 50            # Show last 50 lines then follow
+  kj-tail -s               # Snapshot: show full log and exit
+  kj-tail -t               # Show timestamps
+
+${BOLD}LOG LOCATION${RESET}
+  <project-dir>/.kj/run.log
+  Created automatically when kj_run, kj_code, or kj_review starts.
+
+EOF
+  exit 0
+}
+
+# ── Parse args ──────────────────────────────────────────
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help) show_help ;;
+    --version) echo "kj-tail $VERSION"; exit 0 ;;
+    -v|--verbose) VERBOSE=true; shift ;;
+    -a|--agent-output) SHOW_AGENT_OUTPUT=true; VERBOSE=true; shift ;;
+    -t|--timestamps) SHOW_TIMESTAMPS=true; shift ;;
+    -s|--snapshot) FOLLOW=false; shift ;;
+    -n|--lines)
+      shift
+      NUM_LINES="${1:-50}"
+      shift
+      ;;
+    -*)
+      echo -e "${RED}Unknown option: $1${RESET}" >&2
+      echo "Run 'kj-tail --help' for usage." >&2
+      exit 1
+      ;;
+    *) PROJECT_DIR="$1"; shift ;;
+  esac
+done
+
+PROJECT_DIR="${PROJECT_DIR:-$(pwd)}"
+LOG_FILE="${PROJECT_DIR}/.kj/run.log"
+
+# ── Locate log ──────────────────────────────────────────
+# When the log does not exist yet, kj-tail stays open and polls until any
+# `kj` / `kj_*` invocation creates it. Exit with Ctrl-C. This used to be a
+# hard exit, which forced the user to time `kj-tail` start vs. the command;
+# too easy to miss early lines. Follow-mode and snapshot mode both get this.
+if [[ ! -f "$LOG_FILE" ]]; then
+  if [[ "$FOLLOW" == "false" ]]; then
+    # Snapshot mode (-s): nothing to print, say so and exit cleanly.
+    echo -e "${YELLOW}No run log at ${LOG_FILE} yet.${RESET}"
+    echo ""
+    echo "The log is created when Karajan starts a pipeline — run any of:"
+    echo "  kj run \"...\"    kj audit    kj code    kj review    kj plan"
+    echo "  mcp__karajan-mcp__kj_run / kj_audit / kj_code / kj_review / kj_plan ..."
+    echo ""
+    exit 0
+  fi
+
+  echo -e "${YELLOW}Waiting for run log to appear at ${LOG_FILE}${RESET}"
+  echo -e "${DIM}(It is created the moment you run any kj command that invokes the orchestrator or a role.${RESET}"
+  echo -e "${DIM} Ctrl-C to stop waiting. Triggers: kj run/audit/code/review/plan/discover/triage/researcher/architect, or the same via MCP.)${RESET}"
+  echo ""
+  # Ensure parent dir exists so we can poll even on a fresh project
+  mkdir -p "$(dirname "$LOG_FILE")" 2>/dev/null || true
+  # Poll every 500ms until the file shows up (low CPU, visible responsiveness).
+  # Cap at 4h (28800 ticks) to avoid infinite stuck monitors; after the cap we
+  # exit 0 so tmux/screen panes don't linger as errors.
+  tick=0
+  while [[ ! -f "$LOG_FILE" ]]; do
+    sleep 0.5
+    tick=$((tick + 1))
+    if (( tick >= 28800 )); then
+      echo -e "${YELLOW}Still no run log after 4h — exiting. Re-run kj-tail when ready.${RESET}"
+      exit 0
+    fi
+  done
+  echo -e "${GREEN}Log appeared — streaming...${RESET}"
+  echo ""
+fi
+
+# ── Filter & colorize ──────────────────────────────────
+filter_line() {
+  local line="$1"
+  local ts=""
+  local clean="$line"
+
+  # Extract and optionally strip timestamp (HH:MM:SS.mmm)
+  if [[ "$clean" =~ ^([0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3})\ (.*) ]]; then
+    ts="${BASH_REMATCH[1]}"
+    clean="${BASH_REMATCH[2]}"
+  fi
+
+  # Skip noise in default mode
+  if [[ "$VERBOSE" == "false" ]]; then
+    # Skip agent heartbeats
+    [[ "$clean" == *"[agent:heartbeat]"* ]] && return
+    [[ "$clean" == *"heartbeat"* ]] && return
+    # Skip budget lines
+    [[ "$clean" == *"Budget:"* ]] && return
+    # Skip agent raw output
+    [[ "$clean" == *"[agent:output]"* ]] && return
+    # Skip internal metadata
+    [[ "$clean" == *"[agent:start]"* ]] && return
+    [[ "$clean" == *"[agent:end]"* ]] && return
+    # Skip noisy JSON dumps (system init, tool lists, etc.)
+    [[ "${#clean}" -gt 500 ]] && return
+  fi
+
+  if [[ "$SHOW_AGENT_OUTPUT" == "false" ]]; then
+    # Skip raw agent output (often JSON/stream data)
+    [[ "$clean" == "{"* ]] && [[ "$clean" == *"}" ]] && return
+    [[ "$clean" == *'"type":'* ]] && [[ "${#clean}" -gt 200 ]] && return
+  fi
+
+  # Build prefix
+  local prefix=""
+  if [[ "$SHOW_TIMESTAMPS" == "true" ]] && [[ -n "$ts" ]]; then
+    prefix="${DIM}${ts}${RESET} "
+  fi
+
+  # ── Colorize by content ──────────────────────────────
+  # Session markers
+  if [[ "$clean" == "---"* ]]; then
+    echo -e "${prefix}${BOLD}${CYAN}${clean}${RESET}"
+    return
+  fi
+
+  # Stage: started/finished
+  if [[ "$clean" == *"started"* ]] && [[ "$clean" == *"[kj_"* ]]; then
+    echo -e "${prefix}${BOLD}${CYAN}▶ ${clean}${RESET}"
+    return
+  fi
+  if [[ "$clean" == *"finished"* ]] && [[ "$clean" == *"[kj_"* ]]; then
+    echo -e "${prefix}${BOLD}${GREEN}✓ ${clean}${RESET}"
+    return
+  fi
+
+  # Iterations
+  if [[ "$clean" == *"[iteration]"* ]] || [[ "$clean" == *"Iteration "* ]]; then
+    echo -e "${prefix}${BOLD}${clean}${RESET}"
+    return
+  fi
+
+  # Coder
+  if [[ "$clean" == *"[coder"* ]] || [[ "$clean" == *"Coder"* ]]; then
+    echo -e "${prefix}${GREEN}  ├─ 🔨 ${clean}${RESET}"
+    return
+  fi
+
+  # Reviewer
+  if [[ "$clean" == *"APPROVED"* ]]; then
+    echo -e "${prefix}${GREEN}  ├─ ✅ ${clean}${RESET}"
+    return
+  fi
+  if [[ "$clean" == *"REJECTED"* ]]; then
+    echo -e "${prefix}${RED}  ├─ ❌ ${clean}${RESET}"
+    return
+  fi
+  if [[ "$clean" == *"[reviewer"* ]]; then
+    echo -e "${prefix}${YELLOW}  ├─ 👁️  ${clean}${RESET}"
+    return
+  fi
+
+  # Solomon
+  if [[ "$clean" == *"[solomon"* ]] || [[ "$clean" == *"Solomon"* ]]; then
+    echo -e "${prefix}${MAGENTA}  ├─ ⚖️  ${clean}${RESET}"
+    return
+  fi
+
+  # Sonar
+  if [[ "$clean" == *"[sonar"* ]] || [[ "$clean" == *"SonarQube"* ]] || [[ "$clean" == *"Quality gate"* ]]; then
+    echo -e "${prefix}${BLUE}  ├─ 🔍 ${clean}${RESET}"
+    return
+  fi
+
+  # Tester
+  if [[ "$clean" == *"[tester"* ]] || [[ "$clean" == *"Tester"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🧪 ${clean}${RESET}"
+    return
+  fi
+
+  # Security
+  if [[ "$clean" == *"[security"* ]] || [[ "$clean" == *"Security"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🔒 ${clean}${RESET}"
+    return
+  fi
+
+  # Researcher
+  if [[ "$clean" == *"[researcher"* ]] || [[ "$clean" == *"Researcher"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🔬 ${clean}${RESET}"
+    return
+  fi
+
+  # Architect
+  if [[ "$clean" == *"[architect"* ]] || [[ "$clean" == *"Architect"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🏗️  ${clean}${RESET}"
+    return
+  fi
+
+  # Planner
+  if [[ "$clean" == *"[planner"* ]] || [[ "$clean" == *"Planner"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 🧠 ${clean}${RESET}"
+    return
+  fi
+
+  # Triage
+  if [[ "$clean" == *"[triage"* ]] || [[ "$clean" == *"Triage"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 📋 ${clean}${RESET}"
+    return
+  fi
+
+  # Audit
+  if [[ "$clean" == *"[audit"* ]] || [[ "$clean" == *"Audit"* ]]; then
+    echo -e "${prefix}${CYAN}  ├─ 📊 ${clean}${RESET}"
+    return
+  fi
+
+  # Preflight
+  if [[ "$clean" == *"[preflight"* ]] || [[ "$clean" == *"Preflight"* ]]; then
+    echo -e "${prefix}${GRAY}  ├─ ⚙️  ${clean}${RESET}"
+    return
+  fi
+
+  # Skills (addyosmani catalog + OpenSkills marketplace)
+  if [[ "$clean" == *"[skills:"* ]] || [[ "$clean" == *"[skills]"* ]]; then
+    # Highlight failures/unavailability in yellow, successes in magenta
+    if [[ "$clean" == *"unavailable"* ]] || [[ "$clean" == *"would have used"* ]]; then
+      echo -e "${prefix}${YELLOW}  ├─ 🎯 ${clean}${RESET}"
+    else
+      echo -e "${prefix}${MAGENTA}  ├─ 🎯 ${clean}${RESET}"
+    fi
+    return
+  fi
+
+  # TDD
+  if [[ "$clean" == *"TDD"* ]] || [[ "$clean" == *"tdd"* ]]; then
+    echo -e "${prefix}${GREEN}  ├─ 📋 ${clean}${RESET}"
+    return
+  fi
+
+  # Errors / failures
+  if [[ "$clean" == *"fail"*  || "$clean" == *"FAIL"* || "$clean" == *"error"* || "$clean" == *"ERROR"* ]]; then
+    echo -e "${prefix}${RED}  ├─ ⚠️  ${clean}${RESET}"
+    return
+  fi
+
+  # Standby / rate limit
+  if [[ "$clean" == *"[standby]"* ]] || [[ "$clean" == *"standby"* ]] || [[ "$clean" == *"rate limit"* ]]; then
+    echo -e "${prefix}${YELLOW}  ├─ ⏸️  ${clean}${RESET}"
+    return
+  fi
+
+  # Model fallback
+  if [[ "$clean" == *"not supported"* ]] || [[ "$clean" == *"retrying with"* ]]; then
+    echo -e "${prefix}${YELLOW}  ├─ 🔄 ${clean}${RESET}"
+    return
+  fi
+
+  # Result line
+  if [[ "$clean" == *"Result:"* ]]; then
+    echo -e "${prefix}${BOLD}${GREEN}🏁 ${clean}${RESET}"
+    return
+  fi
+
+  # Budget (verbose only — already filtered above)
+  if [[ "$clean" == *"Budget:"* ]]; then
+    echo -e "${prefix}${GRAY}  ├─ 💰 ${clean}${RESET}"
+    return
+  fi
+
+  # Agent heartbeat (verbose only)
+  if [[ "$clean" == *"heartbeat"* ]] || [[ "$clean" == *"active —"* ]] || [[ "$clean" == *"elapsed"* ]]; then
+    echo -e "${prefix}${GRAY}  ├─ • ${clean}${RESET}"
+    return
+  fi
+
+  # Default
+  echo -e "${prefix}  ├─ ${clean}"
+}
+
+# ── Header ──────────────────────────────────────────────
+echo -e "${BOLD}${CYAN}kj-tail${RESET} ${DIM}v${VERSION} — ${LOG_FILE}${RESET}"
+if [[ "$FOLLOW" == "true" ]]; then
+  echo -e "${GRAY}Ctrl+C to stop${RESET}${VERBOSE:+ ${DIM}(verbose)${RESET}}"
+fi
+echo ""
+
+# ── Run ─────────────────────────────────────────────────
+if [[ "$FOLLOW" == "false" ]]; then
+  # Snapshot mode: show full log and exit
+  while IFS= read -r line; do
+    filter_line "$line"
+  done < "$LOG_FILE"
+  exit 0
+fi
+
+if [[ "$NUM_LINES" -gt 0 ]]; then
+  # Show last N lines then follow
+  tail -n "$NUM_LINES" -F "$LOG_FILE" 2>/dev/null | while IFS= read -r line; do
+    filter_line "$line"
+  done
+else
+  # Follow only new lines
+  tail -n 0 -F "$LOG_FILE" 2>/dev/null | while IFS= read -r line; do
+    filter_line "$line"
+  done
+fi

package/bin/kj.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../src/cli.js";

package/docs/README.es.md

@@ -0,0 +1,80 @@
+<p align="center">
+  <img src="karajan-orbit.svg" alt="Karajan Code" width="220">
+</p>
+
+<h1 align="center">Karajan Code</h1>
+
+<p align="center">
+  El entorno que gobierna el desarrollo con IA — tu agente orquesta, Karajan gobierna.
+</p>
+
+<p align="center">
+  <a href="../README.md">Read in English</a> · <a href="https://karajancode.com">Documentación</a> · <a href="https://planning-game-xp.web.app/public/?project=Karajan%20Code">Roadmap público</a>
+</p>
+
+---
+
+Tu agente de IA (Claude Code, Codex, Copilot, Antigravity, 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. La instalación lo cablea como herramienta MCP nativa (`kj_rag_query`), de modo que consultar el índice sea el camino más barato del agente. 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. Y viaja con un canon de ingeniería destilado: `kj rag query --library` sirve fichas de patrón (cuándo aplica, cuándo NO, la cita canónica) para que los planes nombren una alternativa greenfield en vez de seguir la línea del legacy por inercia.
+- **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.
+- **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, 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.
+- **Mínimo privilegio para agentes** — los subprocesos de agente reciben un allowlist de entorno (la auth de su propio CLI, jamás tus claves cloud ni tokens de registro), y `kj check` inventaría cada MCP alcanzable del proyecto marcando lo aparecido desde el último check. Las tareas con superficie sensible se auto-invocan `kj audit --security` — pasada de cero tokens (prompt-injection sobre los ficheros de contexto del agente + OSV + Semgrep + Sonar) — y remedian antes del review.
+- **Nada personal se publica** — cada boundary de salida se audita antes de dejar la máquina: el pre-commit rechaza un diff con tus datos vetados, los tokens de plataforma hardcodeados (`ghp_`, `sk-`, `AKIA`…) bloquean directamente, el scan del tarball guarda el publish, y `kj privacy scan <dir>` audita cualquier build. Tu denylist vive en `~/.karajan/privacy.yml` — la instalación pregunta y la escribe por ti.
+- **Instalar ES activar** — `kj env install` ejecuta él mismo el enforcement (hooks de git, gate de veredicto, tool gate) en vez de confiar en que el agente corra pasos de setup, y termina imprimiendo el método en la propia conversación que instaló. Un commit fuera del método se rechaza, no se narra.
+- **El turno no puede terminar en rojo — el Sentinel** — un supervisor determinista (cero LLM) cableado a los hooks síncronos del harness registra el estado del método de la sesión según corren las herramientas, y un hook Stop bloquea que el agente termine su turno mientras haya violaciones abiertas. El programa manda, el agente piensa. Ver [niveles de garantía](#niveles-de-garantía-gobernado-vs-supervisado).
+- **El panel de revisión nunca se seca** — nueve agentes integrados (Claude Code, Codex, GitHub Copilot, Antigravity `agy` — el sucesor de gemini —, Kimi Code, Qwen, OpenCode, Aider, Gemini legacy), y cuando al reviewer configurado se le agota la cuota, `kj review` cambia a un candidato autenticado AVISANDO en alto — o te entrega el menú de candidatos con su tier (gratis / suscripción / local) y el comando de login exacto. Jamás un fallo mudo, jamás el brain revisándose a sí mismo.
+
+Este repo corre bajo su propio entorno: cada commit de karajan-code lleva un veredicto de IA cruzada.
+
+## Instalación
+
+Dile a tu agente — en el directorio donde quieras trabajar:
+
+```text
+Quiero usar Karajan en este proyecto: lee https://karajancode.com/start.md
+y haz lo que dice.
+```
+
+El prompt enrutador instala el stack completo si hace falta, detecta si el proyecto es nuevo o existente, activa el entorno, y **para a esperarte** cuando un paso necesita sudo o una cuenta (código de salida 3 de `kj` = pendiente de ti — una instalación parcial es una instalación fallida).
+
+Equivalente manual:
+
+```sh
+curl -fsSL https://karajancode.com/install.sh | sh   # producto completo (npm-first; --standalone para solo-CLI)
+kj doctor && kj install-tools                        # completa el stack
+kj init && kj env install && kj harden && kj review --install-gate
+git config core.hooksPath .karajan/hooks
+```
+
+Requiere git y al menos un CLI de agente de IA — con dos hay revisión cruzada; con tres, arbitraje. Todas las rutas de instalación (npm, binarios, brew, wrapper Python) en la [doc de instalación](https://karajancode.com/docs/es/v4/install/).
+
+## El bucle diario
+
+1. Describes lo que quieres. Tu agente crea la card (`kj hu add`), consulta el RAG, escribe el test que falla y después el código.
+2. `kj review --staged` — una IA distinta revisa el diff exacto. Aprobado → el commit entra. Rechazado → se corrige, o se escala a `kj solomon`.
+3. PR atómica a la rama base. `kj report` muestra el rastro; el HU Board (`kj board`) muestra el trabajo.
+4. ¿Tu agente choca con un bug de kj? `kj report-issue` lo sube — sanitizado, deduplicado y solo con tu aprobación. El ecosistema se repara solo.
+
+Método completo: [Trabaja con tu agente](https://karajancode.com/docs/es/v4/working-with-your-agent/) · [Los gates](https://karajancode.com/docs/es/v4/gates/) · [Referencia de comandos](https://karajancode.com/docs/es/v4/commands/).
+
+## Niveles de garantía: gobernado vs supervisado
+
+Karajan **gobierna** a cualquier agente con gates de git — el falso verde es estructuralmente imposible escriba quien escriba, porque los gates viven en el repositorio, no en la buena voluntad del agente. Encima de eso, el **Karajan Sentinel** añade **supervisión dentro del turno**: `kj harden` cablea hooks deterministas al harness — uno registra el estado del método de la sesión según corren las herramientas (fuentes editadas vs tests tocados, escapes usados), y un hook Stop bloquea que el agente termine su turno mientras haya violaciones abiertas: fuentes editadas en la rama base, rama sin card, código sin tocar un solo test. Cada bloqueo dice la violación exacta y su remediación; `kj sentinel status` muestra lo que ve el supervisor. Ante cualquier duda falla en abierto — y lo dice — antes que colgar una sesión, y cada escape `KJ_ALLOW_*` queda registrado.
+
+Los hooks síncronos con capacidad de bloqueo hoy solo existen en Claude Code. Eso hace explícito el montaje soportado: **para garantizar un harness que controle al LLM, usa Claude Code como anfitrión** — Claude escribe, Codex revisa (un subproceso de revisión no necesita hooks), y un tercer CLI arbitra cuando está disponible. Con cualquier otro anfitrión Karajan sigue gobernando al nivel completo de gates de git y te dice qué nivel está activo — jamás finge una supervisión que no puede imponer.
+
+## 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. 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)
+
+Karajan v1–v3 fue un pipeline multiagente headless dirigido por completo mediante orquestación de subprocesos. Su historia íntegra — pipeline, 24 roles, servidor MCP, step mode, carriles paralelos — se conserva en el **[README de v3 (archivo histórico)](README.v3.es.md)** y en el [archivo de docs v3](https://karajancode.com/docs/es/getting-started/introduction/).
+
+## Contribuir y licencia
+
+Issues y PRs bienvenidas — los informes de fricción vía `kj report-issue` valen oro. Licencia [AGPL-3.0](../LICENSE).