karajan-code 2.33.0 → 3.0.0

package/README.md

@@ -13,7 +13,7 @@
   <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%3D18-brightgreen.svg" alt="Node.js"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg" alt="Node.js"></a>
   <a href="https://github.com/manufosela/homebrew-tap"><img src="https://img.shields.io/badge/homebrew-tap-orange.svg" alt="Homebrew"></a>
 </p>
 
@@ -23,6 +23,8 @@
 
 ---
 
+> **⚠ v3.0.0 — BREAKING:** Node 22+ required. Karajan v3 drops Node 20 (EOL 2026-04-30) and aligns with the Active LTS line. Three deps forced the bump: `lint-staged 17`, `commander 15`, and `better-sqlite3 12.10+` (Node 20 prebuilds gone). Migration: `nvm install 22 && nvm use 22`. No public API changes if you were already on Node 22. Full notes in [CHANGELOG.md](CHANGELOG.md).
+
 You describe what you want to build. Karajan orchestrates multiple AI agents to plan it, implement it, test it, review it with SonarQube, and iterate. No babysitting required.
 
 ## What is Karajan?
@@ -60,7 +62,6 @@ While Genkit, Mastra, LangChain and Vercel AI SDK call `/v1/messages`, Karajan o
 | Calls provider HTTP API (`/v1/messages`, etc.) | ❌ Delegates to CLIs | ✅ |
 | Orchestrates existing AI CLIs (claude, codex, gemini, aider, opencode) as subprocesses | ✅ | ❌ |
 | Depends on cloud infrastructure | ❌ Fully local | ⚠️ Varies |
-| Vanilla JS (no TypeScript required) | ✅ | ⚠️ TS-first |
 | Token billing | **Uses your existing CLI subscriptions** | Pay per API call |
 
 Two technical facts worth keeping straight:
@@ -105,28 +106,79 @@ docker run --rm -v $(pwd):/workspace karajan-code kj --version
 ```
 
 **Python**:
+
+The Python wrapper is a thin shim over the `kj` binary, useful when your stack lives in `pyproject.toml` / `requirements.txt` and you want to invoke Karajan from a venv.
+
 ```bash
-cd wrappers/python && pip install .
+# Option A — once published to PyPI (recommended)
+pip install karajan-code
+
+# Option B — install from the cloned repo (dev)
+git clone https://github.com/manufosela/karajan-code.git
+cd karajan-code/wrappers/python
+pip install .
 ```
 
+Both options expect the `kj` binary to be on your `PATH` (via one of the methods above) — the Python wrapper does not vendor it.
+
 That's it. `kj init` auto-detects your installed agents and installs RTK for token optimization.
 
 ### Optional scanners for `kj audit` + `kj webperf`
 
-Karajan auto-skips any scanner that isn't installed. Add the ones that match your projects:
+None of these are required. Karajan auto-skips any scanner that isn't installed, so the pipeline runs fine with zero of them. Add the ones that match your projects to get more signal:
 
-| Tool | Install | What you get |
-|------|---------|--------------|
-| **SonarQube** | `docker compose -f ~/sonarqube/docker-compose.yml up -d` | Code quality + security rules with line-precision in `kj audit` |
-| **OSV-Scanner** | `go install github.com/google/osv-scanner@latest` | Dependency CVE coverage broader than `npm audit` |
-| **Semgrep** | `pipx install semgrep` | SAST: XSS, SQLi, taint flow, secrets — equivalent to `snyk code`, free for OSS |
-| **Lighthouse** | `npm install -g lighthouse` | Core Web Vitals + opportunities for `kj webperf` (auto-feeds `kj audit`) |
+| Tool | Scope | Install | Installable from `kj init`? | What you get |
+|------|-------|---------|-----------------------------|--------------|
+| **SonarQube** | Any stack | `docker compose -f ~/sonarqube/docker-compose.yml up -d` | ✅ Yes (wizard configures Docker container + token) | Code quality + security rules with line-precision in `kj audit` |
+| **OSV-Scanner** | Any stack | `go install github.com/google/osv-scanner@latest` | ❌ No (install manually) | Dependency CVE coverage broader than `npm audit` |
+| **Semgrep** | Any stack | `pipx install semgrep` | ❌ No (install manually) | SAST: XSS, SQLi, taint flow, secrets — equivalent to `snyk code`, free for OSS |
+| **Lighthouse** | **Frontend only** | `npm install -g lighthouse` | ❌ No (install manually) | Core Web Vitals + opportunities for `kj webperf` (auto-feeds `kj audit`) |
 
 Skip any per-run with `--no-sonar`, `--no-osv`, `--no-semgrep`. See [docs/GETTING-STARTED.md](docs/GETTING-STARTED.md#optional-scanners--kj-audit--kj-webperf) for full table.
 
-## Three ways to use Karajan
+## Footprint & hardware requirements
+
+Karajan ships as **layers you opt into**. The base CLI is tiny (~5 MB). Heavier pieces — Ollama for local RAG, SonarQube for static analysis, the `qmd` model cache for global semantic search — are only pulled if you ask for them. None of them are pulled during `npm install`.
+
+### What lives where
+
+| Layer | Size | When you pay it | Notes |
+| --- | --- | --- | --- |
+| `karajan-code` npm tarball | 5.2 MB / 555 files | Always | The CLI itself |
+| `node_modules/` (global) | ~208 MB | After `npm install -g karajan-code` | Standard for any Node global; SEA binary skips it |
+| `~/.karajan/` (state) | ~40 MB typical | After first `kj run` | Sessions, plans, audit history, HU board DB. `kj clean` prunes it |
+| Ollama Docker image | 6.55 GB | If you use the **local** RAG embedder (default since v2.26) | Auto-pulled in the background on first `kj rag index` (~5 min) |
+| Ollama embedding model | ~260 MB | First `kj rag index` | `nomic-embed-text` by default; lives inside the Ollama container |
+| SonarQube Docker image | 1.47 GB | If you enable Sonar in `kj init` | Optional; `kj audit` runs fine without it |
+| `qmd` model cache | ~2.2 GB | If you use `qmd query` for global semantic search | Local LLMs for query expansion + rerank; entirely off-box otherwise |
+
+### Three install profiles
+
+| Profile | Disk | What's enabled | Trade-off |
+| --- | --- | --- | --- |
+| **Minimum** | ~250 MB | `kj`, audits, reviews, RAG with **cloud embedder** (OpenAI / Voyage / Cohere / Mistral) | Needs an API key; no offline RAG |
+| **Recommended** | ~8.5 GB | + Ollama (local RAG, no API key) + SonarQube | Offline-capable; needs Docker running |
+| **Full house** | ~11 GB | + `qmd` (semantic search across personal docs/memory) | All features local; biggest footprint |
+
+### Hardware
+
+| Profile | CPU | RAM | Free disk | Notes |
+| --- | --- | --- | --- | --- |
+| **Minimum** | 2 cores | 4 GB | 1 GB | Cloud embedder only; pipeline peaks ~1 GB RAM |
+| **Recommended** | 4–8 cores | 8–12 GB | 10–15 GB | Docker + Ollama running in background |
+| **Ideal** | 16+ cores | 32+ GB | 50+ GB | Multiple Docker stacks, large repos, big audit history |
+
+### Operational notes
+
+- **No GPU required.** Embeddings are CPU-only by default; cloud embedders push the compute off-box entirely.
+- **Pipeline RAM peak**: 1–2 GB per `kj run` (one orchestrator + one coder + one reviewer subprocess at a time).
+- **SQLite is in-process.** No separate DB daemon. `~/.karajan/` is a folder, not a service.
+- **First-run Ollama pull**: ~5 min in the background; you can keep working — `kj` falls back to a cloud embedder if Ollama isn't ready yet.
+- **Runtime**: Node.js ≥ 22.22.1 (Active LTS). v3.0.0 dropped Node 20 support. Use `kj doctor` to verify your environment.
+
+## Two ways to use Karajan
 
-Karajan installs **three commands**: `kj`, `kj-tail`, and `karajan-mcp`.
+Karajan installs **three commands**: `kj` (the CLI), `karajan-mcp` (the MCP server) and `kj-tail` (a monitoring companion). There are two *ways to use it* — CLI or MCP — and `kj-tail` is the monitor you keep open in a second terminal while either mode is running.
 
 ### 1. CLI: direct from terminal
 
@@ -164,13 +216,13 @@ This is the primary use case. Karajan runs as an MCP server inside Claude Code,
 You → Claude Code → kj_run (via MCP) → triage → coder → sonar → reviewer → tester → security
 ```
 
-The MCP server auto-registers during `npm install`. Your AI agent sees 23 tools (`kj_run`, `kj_code`, `kj_review`, etc.) and uses them as needed.
+The MCP server auto-registers during `npm install`. Your AI agent sees 27 tools (`kj_run`, `kj_code`, `kj_review`, etc.) and uses them as needed.
 
 **The problem**: when Karajan runs inside an AI agent, you lose visibility. The agent shows you the final result, but not the pipeline stages, iterations, or Solomon decisions happening in real time.
 
-### 3. kj-tail: monitor from a separate terminal
+### Companion: `kj-tail` (monitor from a separate terminal)
 
-**This is the companion tool.** Open a second terminal in the **same project directory** where your AI agent is working, and run:
+`kj-tail` is **not a third way to run Karajan** — it's a read-only monitor for whichever of the two ways above you're using. Open a second terminal in the **same project directory** where the pipeline is running, and run:
 
 ```bash
 kj-tail
@@ -221,7 +273,13 @@ iteration: coder → refactorer? → guard(output) → guard(perf) → sonar?
 post-loop: tester? → security? → perf? → impeccable? → audit?
 ```
 
-**24 stages** across three phases: 18 AI-agent-backed roles (table below), 6 deterministic stages without an LLM call (`intent`, `skills`, `acceptance`, `guard(output)`, `guard(perf)`, `tdd`). Two extra classes (`commiter`, `repairer`) are post-approval / internal helpers, not standalone pipeline stages. Each AI role is executed by the agent you choose:
+**24 stages max** across three phases: 18 AI-agent-backed roles (table below), 6 deterministic stages without an LLM call (`intent`, `skills`, `acceptance`, `guard(output)`, `guard(perf)`, `tdd`). Two extra classes (`commiter`, `repairer`) are post-approval / internal helpers, not standalone pipeline stages.
+
+> **Karajan is multi-language.** The 24 figure is the upper bound for a frontend project. On a **backend / library / CLI** task, three stages are skipped automatically because they have nothing to assess: `impeccable` (UI/UX audit), `perf` (Core Web Vitals via Lighthouse) and `guard(perf)` (frontend anti-pattern check). That leaves a typical pipeline at **~21 stages** for backend / systems / CLI / data work, with the same triage rules trimming further on trivial tasks. Stage selection is auto-detected from the repo (presence of frontend frameworks, `index.html`, `package.json` browser fields, etc.) — no flag required.
+>
+> The **minimum useful pipeline** on a `trivial` task is roughly: `intent → triage → coder → guard(output) → tdd → reviewer → brain` (~7 stages). Triage decides.
+
+Each AI role is executed by the agent you choose:
 
 | Role | What it does | Default |
 |------|-------------|---------|
@@ -263,7 +321,7 @@ post-loop: tester? → security? → perf? → impeccable? → audit?
 
 Mix and match. Use Claude as coder and Codex as reviewer. Karajan auto-detects installed agents during `kj init`.
 
-## MCP server (23 tools)
+## MCP server (27 tools)
 
 After `npm install -g karajan-code`, the MCP server auto-registers in Claude and Codex. Manual config if needed:
 
@@ -275,7 +333,7 @@ After `npm install -g karajan-code`, the MCP server auto-registers in Claude and
 # command = "karajan-mcp"
 ```
 
-**24 tools** available: `kj_run`, `kj_code`, `kj_review`, `kj_plan`, `kj_board`, `kj_audit`, `kj_scan`, `kj_doctor`, `kj_config`, `kj_report`, `kj_resume`, `kj_roles`, `kj_agents`, `kj_preflight`, `kj_status`, `kj_init`, `kj_discover`, `kj_triage`, `kj_researcher`, `kj_architect`, `kj_impeccable`, `kj_hu`, `kj_skills`, `kj_suggest`.
+**27 tools** available: `kj_run`, `kj_code`, `kj_review`, `kj_plan`, `kj_board`, `kj_audit`, `kj_scan`, `kj_doctor`, `kj_config`, `kj_report`, `kj_resume`, `kj_roles`, `kj_agents`, `kj_preflight`, `kj_status`, `kj_init`, `kj_discover`, `kj_triage`, `kj_researcher`, `kj_architect`, `kj_hu`, `kj_skills`, `kj_suggest`, `kj_undo`, `kj_clean`, `kj_rag_query`, `kj_rag_index`.
 
 Use `kj-tail` in a separate terminal to see what the pipeline is doing in real time (see [Three ways to use Karajan](#three-ways-to-use-karajan)).
 
@@ -308,20 +366,20 @@ Karajan auto-detects and auto-configures everything it can:
 
 No per-project configuration required. If you want to customize, config is layered: session > project > global.
 
-## Why vanilla JavaScript?
+## Recommended companions
 
-Not nostalgia, not stubbornness. I've been using JavaScript since 1997, when Brendan Eich created it in a week and changed the lives of everyone building for the web. I know its guts, its bugs, its quirks. And I know that whoever truly understands JS turns those bugs into features. TypeScript exists so that developers used to strongly-typed languages don't panic when they see JS. I respect that. But I don't need it. Tests are my type safety. JSDoc and a good IDE are my intellisense. And not having a compiler between the code and me is what lets me ship 57 releases in 45 days without fear.
+None of these are required. Karajan runs fine on its own. They're tools that, when present, Karajan can take advantage of — or that help *you* work better around Karajan.
 
-[Why vanilla JavaScript: the long version](docs/why-vanilla-js.md)
+| Tool | Invoked by | Why |
+|------|-----------|-----|
+| [**RTK**](https://github.com/rtk-ai/rtk) | Karajan (auto, on Bash outputs) | Reduces token consumption by 60-90% on Bash command outputs |
+| [**QMD**](https://github.com/manufosela/qmd) | You (CLI / MCP), complementary to RAG | Semantic search engine over Markdown corpora — works alongside `kj rag query` when you want a richer index over your own docs |
+| [**GitHub MCP**](https://github.com/github/github-mcp-server) | Your AI agent (via MCP) | Create PRs, manage issues directly from the agent |
+| [**Chrome DevTools MCP**](https://github.com/ChromeDevTools/chrome-devtools-mcp) | Your AI agent (via MCP) | Verify UI changes visually after frontend modifications |
 
-## Recommended companions
+## Why vanilla JavaScript?
 
-| Tool | Why |
-|------|-----|
-| [**RTK**](https://github.com/rtk-ai/rtk) | Reduces token consumption by 60-90% on Bash command outputs |
-| [**Planning Game MCP**](https://github.com/manufosela/planning-game-xp-mcp) | Agile project management (tasks, sprints, estimation), XP-native |
-| [**GitHub MCP**](https://github.com/github/github-mcp-server) | Create PRs, manage issues directly from the agent |
-| [**Chrome DevTools MCP**](https://github.com/ChromeDevTools/chrome-devtools-mcp) | Verify UI changes visually after frontend modifications |
+Tests are the type safety; JSDoc + a good IDE are the intellisense; no compiler in the loop is what makes shipping fast. The long version is anecdotal and lives in [docs/why-vanilla-js.md](docs/why-vanilla-js.md).
 
 ## Contributing
 
@@ -329,22 +387,63 @@ Not nostalgia, not stubbornness. I've been using JavaScript since 1997, when Bre
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Run ~2599 tests with Vitest
+npm test              # Run ~5 368 tests across 482 files with Vitest
 npm run validate      # Lint + test
 ```
 
 Issues and pull requests welcome. If something doesn't work as documented, [open an issue](https://github.com/manufosela/karajan-code/issues). That's the most useful contribution at this stage.
 
-## Telemetry
+## Privacy & telemetry
+
+**Telemetry is OFF by default.** The `kj init` wizard asks once, in your OS
+language, with a plain-text "yes / no" prompt:
 
-Karajan collects anonymous usage statistics to improve the tool:
-version, OS, command used, pipeline duration and success rate.
-No code, task descriptions, or personal data is ever sent.
+> *Help improve Karajan by sending anonymous telemetry to the project?*
+> *(version, OS, commands, pipeline duration — no code, no tasks, no personal data)*
 
-Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
+Answer "yes" once and `telemetry: true` is persisted to `~/.karajan/kj.config.yml`.
+Anything else — undefined, missing key, `false`, fresh install with no wizard run —
+keeps it off. There is no hidden default-on path.
+
+### What gets sent (when enabled)
+
+Three event types, anonymous, no userID / email / IP collected by Karajan itself:
+
+| Event | When | Payload |
+|---|---|---|
+| `install` | first `kj init` | `version`, `os`, `node`, `ts` |
+| `cli_command` | each `kj <subcommand>` | `version`, `os`, `node`, `ts`, `command` |
+| `pipeline_complete` | end of `kj run` | `version`, `os`, `node`, `ts`, `mode`, `agent`, `duration_s`, `success`, `taskType` |
+
+Endpoint: `https://karajan-code.web.app/api/telemetry` (POST, 3 s timeout, fire-and-forget).
+Implementation: [`src/utils/telemetry.js`](src/utils/telemetry.js).
+
+### Flip it later
+
+Open `~/.karajan/kj.config.yml`, set `telemetry: true` (opt in) or `telemetry: false` (opt out),
+save. Or re-run `kj init` and answer the prompt again. Set `KJ_DEBUG=1` to see telemetry
+errors on stderr (otherwise failures are silent — telemetry never blocks the pipeline).
 
 ## Recent releases
 
+> **v2.34.0 released** — Minor. Two epics in one window. **KJC-PCS-0052 "Multi-language RAG"** — Python, Rust, Go and Java join JS/TS as first-class citizens of the local RAG index (AST chunkers via `web-tree-sitter` + multi-lang watcher + audit/onboarder multi-stack manifest sniffer), so a polyglot repo gets the same semantic retrieval surface as a single-language one. **KJC-PCS-0053 "RAG Quality & Observability"** — `kj rag eval` ships a frozen golden-query harness with `recall@k + MRR` (CI-gated via `--min-recall`), content-hash dedup skips redundant embeddings, optional MMR diversification returns *different* chunks instead of five near-duplicates, and `docs/RAG.md` gains a six-questions deep-dive documenting the system end-to-end. `kj rag index --since <ref>` + a post-merge git hook keep the index in sync with `git pull` / merge without manual intervention.
+>
+> - **`vec_store_meta` + `kj rag index --since`** (PR #882, KJC-TSK-0455 PR1): per-project last-indexed-commit stamp; `--since auto` resolves it; explicit refs honoured; missing baseline falls back to a full index with a friendly warning. Idempotent.
+> - **Post-merge hook + pre-run drift check** (PR #883, KJC-TSK-0455 PR2): new `kj rag install-hooks` writes `.git/hooks/post-merge` so `git pull` auto-triggers a delta re-index. Pre-run drift check emits a one-line hint when `HEAD` is ahead of the last indexed SHA by more than N files.
+> - **Language registry + Python canary** (PR #884, KJC-TSK-0474): new `src/lang/registry.js` with `adapterForPath(file)`; the indexer + watcher both route through it. Python lands as the first non-JS adapter to exercise the registry shape from day one.
+> - **Python AST chunker** (PR #886, KJC-TSK-0478) and **Rust AST chunker** (PR #888, KJC-TSK-0479): web-tree-sitter walkers + regex fallbacks, grammars vendored under `vendor/tree-sitter-grammars/*.wasm` so SEA binaries stay self-contained.
+> - **Indexer prepares Python / Rust grammars** (PR #889, KJC-TSK-0480): `prepareAdapters()` awaits the grammar loads before walking so the first file doesn't pay the cold-load tax mid-batch.
+> - **Go AST chunker** (PR #890, KJC-TSK-0481): tree-sitter walker + regex fallback. Method receivers rendered explicitly so retrieval surfaces method-vs-function disambiguation without re-parsing.
+> - **Multi-stack manifest sniffer for `basal-cost`** (PR #891, KJC-TSK-0476): `kj audit` now reads Python (`pyproject.toml`, `requirements*.txt`), Rust (`Cargo.toml`), Go (`go.mod`) and Java (`pom.xml`, `build.gradle*`) manifests alongside `package.json`. Cost estimates no longer assume JS/TS.
+> - **Multi-stack frameworks in audit bundle** (PR #892, KJC-TSK-0477): the audit bundle JSON gains a `stacks` field listing detected language stacks + framework hints (Django, Flask, Actix, Tokio, Gin, Echo, Spring, Quarkus...). Onboarder + audit role render polyglot reality.
+> - **Java AST chunker** (PR #893, KJC-TSK-0486): two-level walker (class / interface / enum / record → method / constructor) + regex fallback. Inner classes flattened with `Outer$Inner` symbols.
+> - **`docs/RAG.md` six-questions deep-dive** (PR #894, KJC-TSK-0485): per-language chunker table, six-provider embedder matrix, hybrid + rerank + metadata filter, update strategy table, validation tiers. Excluded from the shrink-budget gate.
+> - **Watcher derived from language registry** (PR #895, KJC-TSK-0482): `kj watch` matcher no longer hard-codes JS/TS. Python / Rust / Go / Java sources trigger live re-index.
+> - **Content-hash skip-on-match** (PR #896, KJC-TSK-0484 PR-A): each chunk gains a `sha256` column; identical bodies skip the Ollama call. Re-indexing identical files now costs zero embeddings.
+> - **MMR diversification in retriever** (PR #898, KJC-TSK-0484 PR-B): optional `rag.search.mmr` over the top-N candidates; lambda (`rag.search.mmrLambda`, default 0.5) trades pure cosine relevance for diversity. Off by default.
+> - **Retrieval-quality harness** (PR #899, KJC-TSK-0483 PR-A): pure `runEval(queries, runQuery, { topK, ks })` scoring recall@k (binary) + MRR. `tests/rag/golden-queries.json` ships 20 entries covering the public surface of `src/rag/`.
+> - **`kj rag eval` CLI + baseline docs** (PR #900, KJC-TSK-0483 PR-B): subcommand wires the harness to the indexed corpus, emits aggregate + per-query report (human or `--json`), and sets `process.exitCode = 1` when `--min-recall <n>` is set and aggregate falls below — drop-in CI gate after `kj rag index`.
+
 > **v2.33.0 released** — Minor. **AI Harness Scorecard golden metric (KJC-PCS-0051, Plan B)** — every `kj audit` now boots a Docker one-shot of `addyosmani/ai-harness-scorecard`, gets a deterministic 0–100 score + A–F grade, persists it to a per-project `audit-history.db`, and on the next run renders the delta vs the previous baseline plus an optional Unicode-bar trend sparkline. One golden number for "how AI-friendly is this repo today vs last week," zero LLM tokens spent.
 >
 > - **Harness Docker one-shot** (PR #877, KJC-TSK-0470): `src/audit/harness-runner.js` runs `docker run --rm -v <repo>:/repo addyosmani/ai-harness-scorecard analyze`, parses the verdict, auto-skips on missing Docker. `--no-harness` opts out.
@@ -515,7 +614,7 @@ Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 >
 > KJC-BUG-0058 (PR #798, reported by [@aitormf](https://github.com/aitormf)): a session that stopped during Sonar would re-run the full pre-loop on `kj resume <id>` — HU-reviewer, intent, discover, triage, domainCurator, **researcher, architect, planner** all from scratch — doubling token cost and breaking the value-prop of the command. Root cause: `resumeFlow` (flow-runner.js:280) called `runFlow` without rehydrating stage state, and the session never persisted stage outputs in the first place. **Fix**: two new mutators in `src/session/mutators.js` (`setStageResult` mirrors into `stage_results[name]` + `stages_completed[]`; `setStageBundle` adds `stage_bundles[name]` for cross-stage context like `researchContext`, `architectContext`, `plannedTask`). Two closures inside `runPreLoopStages` (`persistStage` + `resumeSkip`) wrap every cacheable stage. `init-context.js` rehydrates `ctx.stageResults` from the loaded session before invoking the pre-loop. Triage is *not* skipped on resume — it produces `roleOverrides` the Brain decisor depends on and is cheap to re-run.
 >
-> KJC-BUG-0060 (PR #797, reported by mjfosela during the v2.19.3 release): `git checkout main` reported `[ahead 27]` of origin/main. Every commit was titled `initial commit`, authored by `manufosela@gmail.com`, and had the **exact same tree as its parent** — completely empty. The reflog held **2 495 such SHAs** accumulated since April 2026. None ever reached origin/main (gh push / CI would have rejected them) so runtime impact was zero, but the local history was noisy and on every release it looked like a sync loss. Root cause: `src/orchestrator/config-init.js::autoInit()` guarded with `!(await exists(projectDir/.git))`, which fails two ways: (a) dogfooding kj on karajan-code itself from a subdir → `exists()` returns false → `git init` re-initializes the *parent's* `.git/` (idempotent, harmless) → `git commit --allow-empty` then resolves upward and lands an empty commit on the parent's main; (b) transient FS hicks (EACCES/ENOENT) flip `exists()` to a false negative. **Fix**: switch the static FS probe for `git rev-parse --is-inside-work-tree`, which performs the same upward search git would use for the commit itself — guard cannot disagree with the operation it guards. And drop the `git commit --allow-empty -m "initial commit"` step entirely: no downstream stage needs a root commit; the 2 495 zombies never broke anything, the seed was decorative and turned out to be the actual user-visible symptom.
+> KJC-BUG-0060 (PR #797, reported by @manufosela during the v2.19.3 release): `git checkout main` reported `[ahead 27]` of origin/main. Every commit was titled `initial commit`, authored by the local git identity, and had the **exact same tree as its parent** — completely empty. The reflog held **2 495 such SHAs** accumulated since April 2026. None ever reached origin/main (gh push / CI would have rejected them) so runtime impact was zero, but the local history was noisy and on every release it looked like a sync loss. Root cause: `src/orchestrator/config-init.js::autoInit()` guarded with `!(await exists(projectDir/.git))`, which fails two ways: (a) dogfooding kj on karajan-code itself from a subdir → `exists()` returns false → `git init` re-initializes the *parent's* `.git/` (idempotent, harmless) → `git commit --allow-empty` then resolves upward and lands an empty commit on the parent's main; (b) transient FS hicks (EACCES/ENOENT) flip `exists()` to a false negative. **Fix**: switch the static FS probe for `git rev-parse --is-inside-work-tree`, which performs the same upward search git would use for the commit itself — guard cannot disagree with the operation it guards. And drop the `git commit --allow-empty -m "initial commit"` step entirely: no downstream stage needs a root commit; the 2 495 zombies never broke anything, the seed was decorative and turned out to be the actual user-visible symptom.
 >
 > **If your `kj resume` re-runs researcher/architect, or your `git status` shows mysterious `[ahead N]` after dogfooding kj on a kj-linked source tree, upgrade to v2.19.4.**
 >
@@ -575,5 +674,6 @@ Built by [@manufosela](https://github.com/manufosela). Head of Engineering at Ge
 
 ### Contributors
 
-- [@aitormf](https://github.com/aitormf) — OpenCode agent (5th built-in agent)
+- [@aitormf](https://github.com/aitormf) — OpenCode agent (5th built-in agent), early-bug reporter on resume/standby flow
+- [@jorgecasar](https://github.com/jorgecasar) — Model registry, display refactor, valibot config proposals; multiple issue triages
 - [@reiaguilera](https://github.com/reiaguilera) — Beta testing, feature proposals, and quality feedback

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/docs/README.es.md

@@ -111,7 +111,7 @@ Este es el caso de uso principal. Karajan corre como servidor MCP dentro de Clau
 Tu → Claude Code → kj_run (via MCP) → triage → coder → sonar → reviewer → tester → security
 ```
 
-El servidor MCP se auto-registra durante `npm install`. Tu agente de IA ve 23 herramientas (`kj_run`, `kj_code`, `kj_review`, `kj_hu`, etc.) y las usa segun necesite.
+El servidor MCP se auto-registra durante `npm install`. Tu agente de IA ve 27 herramientas (`kj_run`, `kj_code`, `kj_review`, `kj_hu`, etc.) y las usa segun necesite.
 
 **El problema**: cuando Karajan corre dentro de un agente de IA, pierdes visibilidad. El agente te muestra el resultado final, pero no las etapas del pipeline, iteraciones o decisiones de Solomon en tiempo real.
 
@@ -188,7 +188,7 @@ post-loop: tester? → security? → perf? → impeccable? → audit?
 
 Mezcla y combina. Usa Claude como coder y Codex como reviewer. Karajan auto-detecta agentes instalados durante `kj init`.
 
-## Servidor MCP (23 herramientas)
+## Servidor MCP (27 herramientas)
 
 Tras `npm install -g karajan-code`, el servidor MCP se auto-registra en Claude y Codex. Config manual si es necesario:
 
@@ -200,7 +200,7 @@ Tras `npm install -g karajan-code`, el servidor MCP se auto-registra en Claude y
 # command = "karajan-mcp"
 ```
 
-**23 herramientas** disponibles: `kj_run`, `kj_code`, `kj_review`, `kj_plan`, `kj_audit`, `kj_scan`, `kj_doctor`, `kj_config`, `kj_report`, `kj_resume`, `kj_roles`, `kj_agents`, `kj_preflight`, `kj_status`, `kj_init`, `kj_discover`, `kj_triage`, `kj_researcher`, `kj_architect`, `kj_impeccable`, `kj_hu`, `kj_skills`, `kj_suggest`.
+**27 herramientas** disponibles: `kj_run`, `kj_code`, `kj_review`, `kj_plan`, `kj_board`, `kj_audit`, `kj_scan`, `kj_doctor`, `kj_config`, `kj_report`, `kj_resume`, `kj_roles`, `kj_agents`, `kj_preflight`, `kj_status`, `kj_init`, `kj_discover`, `kj_triage`, `kj_researcher`, `kj_architect`, `kj_hu`, `kj_skills`, `kj_suggest`, `kj_undo`, `kj_clean`, `kj_rag_query`, `kj_rag_index`.
 
 Usa `kj-tail` en un terminal separado para ver lo que el pipeline esta haciendo en tiempo real (ver [Tres formas de usar Karajan](#tres-formas-de-usar-karajan)).
 
@@ -254,7 +254,7 @@ No es nostalgia ni cabezoneria. Es que llevo usando JavaScript desde 1997, cuand
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Ejecutar ~2599 tests con Vitest
+npm test              # Ejecutar ~5 368 tests en 482 ficheros con Vitest
 npm run validate      # Lint + test
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "2.33.0",
+  "version": "3.0.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",
@@ -24,7 +24,7 @@
     "cli"
   ],
   "engines": {
-    "node": ">=20.19.0"
+    "node": ">=22.22.1"
   },
   "imports": {
     "#utils/*": "./src/utils/*",
@@ -37,6 +37,7 @@
     "bin/",
     "templates/",
     "scripts/",
+    "vendor/tree-sitter-grammars/",
     "packages/hu-board/src/",
     "packages/hu-board/public/",
     "packages/hu-board/package.json",
@@ -48,7 +49,8 @@
   "bin": {
     "kj": "bin/kj.js",
     "kj-tail": "bin/kj-tail",
-    "karajan-mcp": "bin/karajan-mcp.js"
+    "karajan-mcp": "bin/karajan-mcp.js",
+    "kj-rag-mcp": "bin/kj-rag-mcp.js"
   },
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
@@ -71,34 +73,38 @@
   "lint-staged": {
     "src/**/*.js": "eslint --max-warnings=999"
   },
+  "overrides": {
+    "fast-uri": "^3.1.2"
+  },
   "dependencies": {
-    "@babel/parser": "^7.29.3",
-    "@modelcontextprotocol/sdk": "^1.26.0",
-    "better-sqlite3": "^11.0.0",
-    "chokidar": "^4.0.0",
-    "commander": "^14.0.0",
+    "@babel/parser": "^7.29.7",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^12.10.0",
+    "chokidar": "^5.0.0",
+    "commander": "^15.0.0",
     "execa": "^9.6.0",
     "express": "^5.1.0",
     "express-rate-limit": "^8.5.0",
     "helmet": "^8.1.0",
-    "js-yaml": "^4.1.0",
-    "knip": "^6.14.1",
+    "js-yaml": "^4.2.0",
+    "knip": "^6.15.0",
     "madge": "^8.0.0",
     "sqlite-vec": "^0.1.9",
-    "valibot": "^1.3.1"
+    "valibot": "^1.4.1",
+    "web-tree-sitter": "^0.26.9"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@vitest/coverage-v8": "^4.0.18",
+    "@vitest/coverage-v8": "^4.1.8",
     "esbuild": "^0.28.0",
-    "eslint": "^10.2.1",
+    "eslint": "^10.4.1",
     "eslint-plugin-import-x": "^4.16.2",
     "eslint-plugin-security": "^4.0.0",
-    "globals": "^17.5.0",
-    "lint-staged": "^16.4.0",
+    "globals": "^17.6.0",
+    "lint-staged": "^17.0.7",
     "postject": "^1.0.0-alpha.6",
     "prettier": "^3.4.2",
     "simple-git-hooks": "^2.13.1",
-    "vitest": "^4.0.0"
+    "vitest": "^4.1.8"
   }
 }

package/packages/hu-board/package.json

@@ -4,14 +4,17 @@
   "description": "HU Story Board dashboard for Karajan Code",
   "type": "module",
   "private": true,
+  "engines": {
+    "node": ">=22.22.1"
+  },
   "scripts": {
     "start": "node src/server.js",
     "dev": "node --watch src/server.js",
     "test": "vitest run"
   },
   "dependencies": {
-    "better-sqlite3": "^11.0.0",
-    "chokidar": "^4.0.0",
+    "better-sqlite3": "^12.10.0",
+    "chokidar": "^5.0.0",
     "express": "^5.1.0",
     "express-rate-limit": "^8.5.0",
     "helmet": "^8.1.0"

package/scripts/git-hooks/post-merge

@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+# KJC-TSK-0455 — Auto-refresh the local RAG index after a merge so retrieval
+# never serves stale code. Installed by `kj rag install-hooks`. The marker
+# in this comment is how the installer tells kj-managed hooks from user hooks.
+set -euo pipefail
+if ! command -v kj >/dev/null 2>&1; then exit 0; fi
+kj rag index --since auto >/dev/null 2>&1 || true

package/src/audit/basal-cost.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { getKarajanHome } from "../utils/paths.js";
+import { sniffManifests, summariseStack } from "../utils/manifest-sniff.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -59,16 +60,16 @@ async function countLines(filePath) {
   }
 }
 
-async function countDependencies(projectDir) {
-  const pkgPath = path.join(projectDir, "package.json");
-  try {
-    const pkg = JSON.parse(await fs.readFile(pkgPath, "utf8"));
-    const deps = Object.keys(pkg.dependencies || {});
-    const devDeps = Object.keys(pkg.devDependencies || {});
-    return { dependencies: deps.length, devDependencies: devDeps.length, total: deps.length + devDeps.length };
-  } catch {
-    return { dependencies: 0, devDependencies: 0, total: 0 };
+function countDependenciesFromStack(stack) {
+  // Suma deps + devDeps de TODOS los manifests detectados (multi-stack).
+  // Si no hay manifests, devuelve ceros — coherente con repos sin paquete.
+  let deps = 0;
+  let devDeps = 0;
+  for (const m of stack.manifests) {
+    deps += m.deps;
+    devDeps += m.devDeps;
   }
+  return { dependencies: deps, devDependencies: devDeps, total: deps + devDeps };
 }
 
 function runDepcheck(projectDir) {
@@ -231,8 +232,11 @@ export async function measureBasalCost(projectDir) {
     totalLines += await countLines(f);
   }
 
-  const depInfo = await countDependencies(projectDir);
-  const depcheck = await runDepcheck(projectDir);
+  const stack = summariseStack(await sniffManifests(projectDir));
+  const depInfo = countDependenciesFromStack(stack);
+  // depcheck solo aplica a Node; en stacks puros no-Node lo saltamos.
+  const hasNode = stack.manifests.some((m) => m.stack === "node");
+  const depcheck = hasNode ? await runDepcheck(projectDir) : { unused: [], note: "depcheck skipped (no package.json)" };
   const deadExports = await findDeadExports(sourceFiles);
 
   return {
@@ -240,7 +244,8 @@ export async function measureBasalCost(projectDir) {
     totalFiles: sourceFiles.length,
     dependencies: depInfo,
     unusedDependencies: depcheck,
-    deadExports
+    deadExports,
+    stack
   };
 }
 

package/src/audit/deterministic-summary.js

@@ -14,6 +14,7 @@ import { groupVulnerabilitiesBySeverity } from "./osv-findings.js";
 import { groupFindingsBySeverity as groupSemgrepBySeverity } from "./semgrep-findings.js";
 import { groupCyclesBySeverity } from "./circular-deps.js";
 import { groupDeadExportsBySeverity } from "./dead-exports.js";
+import { groupInjectionBySeverity } from "./injection-findings.js";
 
 const MAX_SAMPLE_DEAD_EXPORTS = 10;
 const MAX_SAMPLE_SONAR_PER_SEVERITY = 5;
@@ -21,6 +22,7 @@ const MAX_SAMPLE_OSV_PER_SEVERITY = 5;
 const MAX_SAMPLE_SEMGREP_PER_SEVERITY = 5;
 const MAX_SAMPLE_CYCLES_PER_SEVERITY = 5;
 const MAX_SAMPLE_KNIP_PER_SEVERITY = 5;
+const MAX_SAMPLE_INJECTION_PER_SEVERITY = 5;
 
 /**
  * @param {{basalCost?: object, growthDelta?: object, stack?: object, sonarFindings?: object, webperf?: object, osvFindings?: object}} ctx
@@ -38,11 +40,29 @@ export function formatDeterministicSummary(ctx) {
   if (ctx.semgrepFindings) lines.push(...formatSemgrepBlock(ctx.semgrepFindings));
   if (ctx.circularDeps) lines.push(...formatCircularDepsBlock(ctx.circularDeps));
   if (ctx.deadExports) lines.push(...formatDeadExportsBlock(ctx.deadExports));
+  if (ctx.injectionFindings) lines.push(...formatInjectionBlock(ctx.injectionFindings));
   if (ctx.webperf) lines.push(...formatWebperfBlock(ctx.webperf));
 
   return lines.join("\n");
 }
 
+function formatInjectionBlock(inj) {
+  if (!inj.available) return ["### Prompt-injection scan", `- Status: not available — ${inj.reason || "scan failed"}`, ""];
+  const lines = ["### Prompt-injection scan (specs / domain / onboarding)", `- Files scanned: ${inj.scanned ?? 0}`, `- Findings: ${inj.total ?? 0}`];
+  if ((inj.total ?? 0) > 0) {
+    for (const [severity, items] of Object.entries(groupInjectionBySeverity(inj.findings || []))) {
+      if (items.length === 0) continue;
+      lines.push(`  - ${severity} (${items.length}):`);
+      for (const f of items.slice(0, MAX_SAMPLE_INJECTION_PER_SEVERITY)) {
+        lines.push(`    - ${f.file || "(unknown)"}${f.line ? `:${f.line}` : ""} [${f.type}] ${f.pattern}`);
+      }
+      if (items.length > MAX_SAMPLE_INJECTION_PER_SEVERITY) lines.push(`    - ... and ${items.length - MAX_SAMPLE_INJECTION_PER_SEVERITY} more in ${severity}`);
+    }
+  }
+  lines.push("");
+  return lines;
+}
+
 function formatCircularDepsBlock(circularDeps) {
   if (!circularDeps.available) {
     return ["### Circular Dependencies (architecture)", `- Status: not available — ${circularDeps.reason || "madge not available"}`, ""];