karajan-code 2.18.0 → 2.19.0

package/README.md

@@ -23,36 +23,6 @@
 
 ---
 
-> **v2.18.0 released** — Minor. Closes the **resilience audit** triggered by the public launch: 15 PRs across 5 phases hardening Karajan against the silent-failure family of bugs — *the problem is not that something fails, the problem is failing without telling the user why.* **Phase 1 — hibernation end to end** (#756–#759): a quota cap is classified as a recoverable quota class (incl. Claude Code's `"You've hit your session limit · resets 10:10pm"`); `withBrainRecovery` persists a standby JSON; the orchestrator consumes `action:"hibernate"`, seals the session `hibernated` (resumable) instead of `failed`; the last line printed is the exact resume command (`kj standby resume <id>`). **Phase 2 — don't lie** (#761–#763): `runCommand` surfaces ENOENT so a missing agent CLI gets an actionable error (not an empty one); `silenceTimeoutMs` is forwarded to every role so a hung agent is killed, not waited on forever; all 6 state-file writers go through `writeJsonAtomic` (write-temp + rename) — interrupted writes can no longer truncate plans, sessions, standby snapshots. **Phase 3 — don't lose or block** (#764–#767): a corrupt plan JSON is renamed aside with a loud warn (was silently dropped from `kj plan list`); `kj.config.yml` parse errors throw `Invalid YAML in <path>` (used to brick every kj command including `kj doctor`); `injectLoadedPlan` reconciles HUs left in `coding`/`reviewing`/`running` by a killed `kj run` (cross-checked against the run-registry); board SQLite gets `busy_timeout`, a `user_version` schema gate and corruption recovery. **Phase 4 — don't degrade silently** (#768–#769): `TriageRole` warns loudly when LLM output is unparseable (used to skip researcher/architect/security/tester with a chirpy "fallback defaults" summary); `verifyCoderOutput` distinguishes a git failure from "the coder did nothing" (`gitError` + `retryStrategy: null`) — no more iterations blaming the agent for infra. **Phase 5 — safety net** (#770): a `tests/resilience/` suite indexes every silent-failure mode and pins each one with a test, plus an end-to-end tripwire for the whole quota → hibernate → resume flow. Plus CI runs the `packages/hu-board` suite on every PR (#755). 4 959/4 959 tests passing across 416 files. Safe upgrade from 2.17.2.
->
-> **v2.17.2** — Patch. Wires quota-exhaustion **hibernation end to end**. A `kj run` / `kj plan` that hits a provider session or usage cap used to abort the task with an opaque `UNKNOWN_FATAL`; now it suspends and tells you how to resume. **Session-limit classification (#756)**: `"You've hit your session limit · resets 10:10pm"` matched no rate-limit pattern → `session limit`/`weekly limit` added, and `parseCooldown` learns the 12-hour `resets 10:10pm` clock. **Hibernation persists (#757)**: `withBrainRecovery` only wrote `~/.kj/standby/<id>.json` with a `sessionState`, which no caller passed — new `buildStandbyState()` assembles it with an allowlisted env subset (never the full `process.env`). **Orchestrator consumes `action:"hibernate"` (#758)**: no code checked for it, so a hibernation sealed the HU `failed`; the coder/refactorer stages now stop cleanly and the session is sealed `hibernated` (resumable). **Resume hint (#759)**: a stopped run's last line is now the exact command — `kj standby resume <id>` for a hibernation, `kj resume <id>` otherwise. Plus CI now runs the `packages/hu-board` suite (#755). 4 931/4 931 tests passing across 410 files. Safe upgrade from 2.17.1.
->
-> **v2.17.1** — Patch. Fixes **KJC-BUG-0055**: a project deleted from the HU Board (🗑️) no longer resurrects on the next `kj plan` or board restart. Four independent leaks closed: (1) **`sync.js` temporal gate** — the unconditional `removeTombstone` from KJC-BUG-0050 becomes a `plan.updatedAt > tombstone.deleted_at` comparison, so a tombstoned project revives only when the plan is genuinely newer than the delete; (2) **`ephemeral-cleaner.js`** now writes a tombstone and `rm -rf`'s `hu-stories/`, `sessions/` and `~/.kj/plans/` dirs when wiping ephemeral projects at boot — previously the orphan directories revived the project on the next scan; (3) **`fullScan` boot GC** sweeps orphan tombstoned dirs (the manual DB-wipe case); (4) **`DELETE /api/projects/:id`** honours `KJ_PLANS_DIR` instead of the hardcoded path. New `getTombstone()` helper in `db.js`. **Also fixes a silent `kj board start` failure (#753)**: the daemon's entry-point guard compared `import.meta.url` to a hand-built `file://` path, which wrongly returned false on Windows, symlinked/global installs and paths with spaces — the board exited 0 with an empty log. `server.js` now trusts a `KJ_BOARD_DAEMON` launcher flag, adds `uncaughtException`/`unhandledRejection` handlers and an actionable `better-sqlite3` load error; `board.js` detects an early daemon exit instead of reporting a phantom PID. 4 909/4 909 tests passing across 408 files. Safe upgrade from 2.17.0.
->
-> **v2.17.0** — Minor. `kj audit` gains two new deterministic structural collectors and the v2.16 Sonar false-positive filter is generalised to apply across every collector. **Knip dead-exports collector** (codeQuality dim): reports unused exports/types (MINOR) and unused files (MAJOR), stack-aware (JS/TS only, needs package.json), subprocess via `--reporter json`, 120s timeout. **Madge circular-import collector** (architecture dim): detects import cycles, severity by chain length (≥4 files = MAJOR), honours tsconfig.json path aliases, 60s timeout. **Generalised FP filter**: every collector (sonar, knip, madge, osv, semgrep) now uses the same `config.audit.false_positives` shape with `tool` field plus inline marker `// karajan-audit-ignore: <tool>:<ruleId>`; legacy `config.sonar.false_positives` and `// karajan-sonar-ignore:` keep working. **Built-in catalogue** ships 4 entries by default (knip:unused-files in tests/fixtures + examples, knip:unused-exports on barrel files, madge cycles in node_modules). **BREAKING(engines)**: Node `>=20.10` → `>=20.19` (knip 6.x requirement; same flavour as the v2.8 18→20.10 bump). 4 872/4 872 tests passing across 402 files. Safe upgrade from 2.16.0 if you're on Node ≥ 20.19.
->
-> **v2.16.0** — Minor. Quality-focused release: **deterministic Sonar false-positive filter** (KJC-TSK-0416), wire universal de Brain Recovery completado en `semantic-detector` (TSK-0413 step D), codemod `replace(/regex/g, …)` → `replaceAll(/regex/g, …)` en 41 sitios, y limpieza de hallazgos del propio `kj audit` v2.15.0. The Sonar filter combines two mechanisms: (1) **static rules** `{ rule, filePattern, reason }` from a built-in catalog (covering common false positives like `javascript:S2699` on `tests/architecture/`) plus extensible via `config.sonar.false_positives`; (2) **inline ignores** with `// karajan-sonar-ignore: <ruleId>` on the issue line. Result: the coder stops burning tokens "fixing" non-broken assertions. Brain Recovery now wraps **every** AI call in the pipeline — `semantic-detector` was the last legacy caller. 4 846/4 846 tests passing across 401 files. Safe upgrade from 2.15.0.
->
-> **v2.15.0** — Minor. Three epics, 30+ commits, ~4 000 LOC. (1) **Brain Recovery** (KJC-PCS-0044): universal error classifier with 7 rich classes (rate_limit_short, quota_daily, quota_monthly, api_down, auth_failed, network_timeout, silenced, unknown_fatal), `withBrainRecovery` wrapper wired into ALL agent invocations (no silent failures), persistent hibernation in `~/.kj/standby/<id>.json` with event-driven scheduler (no polling), `kj standby list` + `kj standby resume`, board reconcile at startup, **fallback chain** when quota exhausted with `retryAfter > 12h` (Claude → Codex → OpenCode → Aider, configurable per role via `kj init`). (2) **Model Routing + Undo** (KJC-PCS-0043): each HU gets `coder_model` + `reviewer_model` with cross-provider review by default (claude↔codex), per-HU override from board modal, OpenCode + Aider as first-class providers, ⏪ Undo button restores files via git snapshots. (3) **Self-Healing Plan** (KJC-PCS-0042): structural integrity pass breaks cycles + cleans orphan refs, smart convergence guard for self-fix loop, `kj plan fix [planId] [--prompt]` for iterating without regenerating, skip Sonar for SPIKE/DOC/RESEARCH HUs, eliminate Failed kanban column. 4 835/4 835 tests passing across 400 files. Safe upgrade from 2.14.3.
->
-> **v2.14.2** — Patch. More dogfooding fallout from GRETA Plan 2 v2.14.1: the **▶ Run button** on the HU Board appeared on every `pending` card regardless of `blocked_by` (you could launch a HU whose deps don't exist yet — the user caught it instantly), and titles on the board lost their **`[EPICA]` prefix** at some point in v2.14.x evolution, making it impossible to tell at a glance which area of the plan a card belonged to. Fixes: `canRunHu` now requires `blockedBy.length === 0` before showing ▶; the planner prompt now demands `description: "[EPICA] one-sentence description"` with INFRA/SHARED fallbacks. Plus a new doc `docs/task-templates/spec-conventions.md` collecting the 6 SPEC conventions the planner v2.14.x understands (épicas, scope exclusions, transversal deps, reuse, async observers, explicit deps), so users don't have to rediscover them by dogfooding. 2 PRs (#687, #688). 4584/4584 tests passing. Safe upgrade from 2.14.1.
->
-> **v2.14.1** — Patch. Two more planner pathologies surfaced by dogfooding v2.14.0 against GRETA Plan 2: the **self-fix loop could regress** (iter 1 would drop 15→10 issues, iter 2 then deleted HUs the first iter had added, reaching 17 — worse than before iter 2 started) and the **planner declared `blocked_by` on async observers** (HUs that an async guardrail or cron *reacts to* were marked as depending on the guardrail, breaking the GRETA "AVISA-no-BLOQUEA" principle). Fixes: P5 snapshots the plan before each self-fix iter and reverts if `newCount > currentCount`; P6 lists six async-observer patterns in the planner prompt with a "consume vs react" heuristic. After P5+P6, regenerating Plan 2 GRETA returns to the baseline-iter-1 quality (9 findings) instead of v2.14.0's 17. 2 PRs (#684, #685). 4580/4580 tests passing. Safe upgrade from 2.14.0.
->
-> **v2.14.0** — Quality pass. 16 PRs absorbing bug blockers (Solomon no longer rubber-stamps security issues misclassified as "style", coder filesystem-leak detection gains a second layer that catches `cd <abs> && pnpm init` even when the dir pre-existed, Sonar admin password rotation now surfaces silent failures), the four planner pathologies surfaced by the GRETA Plan 2 dogfooding (scope respect, transversal one-to-many deps, explicit `reuse` marker, and a brand-new **self-fix loop** where the plan-reviewer re-invokes the planner with structured feedback until zero issues remain), HU Board polish (zombie-TTL for crashed-runner prompts, less aggressive rate-limit with SSE exempt), and the first wave of `tests/` reorg (issue #368): ~93 files moved from root to mirror-subfolders. **4577/4577 tests passing**, **0 regressions** across all 16 PRs. Safe upgrade from 2.13.0.
->
-> **v2.13.0** — HU Board hardening. Five PRs make the board resilient and self-healing after a dogfooding session uncovered four pathologies: a "Karajan needs an answer" prompt modal from days earlier blocking the entire UI, 18 zombi projects reappearing after every `kj board start`, the browser serving stale HTML/JS after a server restart, and the prompt modal showing a transparent background. Now: **tombstones** persist deletes across `fullScan` (`KJC-TSK-0380`), new endpoints `DELETE /api/prompts/:id`, `DELETE /api/plans/:planId`, `GET /api/tombstones`, `POST /api/tombstones/:type/:id/restore`; new command **`kj board cleanup`** sweeps ephemeral projects, orphan prompts and dangling session dirs in one pass; **`Cache-Control: no-store`** + `/api/version` polling auto-reloads the client when the server boot time changes; new **🧹 button** as manual escape hatch; CSS `--bg-secondary` finally declared so modals are opaque. 5 PRs (#654, #655, #656, #657, #658). 4522/4522 tests passing.
->
-> **v2.12.0** — Quality-measurement release. Two new features land together: every `kj run` against a known plan now scores how faithfully the coder followed it (deterministic 0–100 **plan adherence** metric, four weighted components, rendered in `summary.md`), and a small **golden-tasks** regression suite (`todo-rest-api`, `npm-package-cli`, `react-counter-component`) catches output-quality drops between Karajan versions before npm publish. Plus the shrink-budget CI gate now exempts human-facing docs from its 200-LOC ceiling while keeping AI-rule files (CLAUDE.md, AGENTS.md, role prompts) capped. 3 PRs for plan adherence (#645–#647), 4 for golden tasks (#648, #650–#652), 1 for the CI policy (#649). 4522/4522 tests passing. Safe upgrade from 2.11.0.
->
-> **v2.11.0** — Dogfooding pass release. Two-day pass through a 10-level test plan surfaced and fixed a long tail of UX papercuts and three latent bugs that only show up on fresh `/tmp` repos: the `SonarStage` no longer loops on remoteless projects (was burning iterations until `max_iterations`-fallback-approval), the post-loop `commitAll` now tolerates the locale-specific "nothing to commit" race, the HU sub-pipeline branches off `master`/`HEAD` when the configured `main` doesn't exist, and `runFlow` now seals `session.status` at the boundary so `kj status` never shows zombi `running` runs again. Plus `hu-board` gains automatic ephemeral-project cleanup and an in-UI help modal for the five views. 14 PRs (#624–#637), 4452/4452 tests passing. Safe upgrade from 2.10.2.
->
-> **v2.10.2** — Patch release. `kj init` wizard expanded from 9 prompts to a full setup: per-role provider selection (10 roles, "inherit / pick CLI / disable"), automatic SonarQube token generation via REST API (no more web UI walkthrough), git automation flags (`auto_commit/push/pr`) and HU Board security (bind host + port). +16 new tests. Safe upgrade from 2.10.1.
->
-> **v2.10.1** — Patch release. One-line fix for a stdout contamination bug in `kj audit --agent-readiness --json` (the `[info]` banner was breaking downstream `jq` pipes), plus polish in the asciinema demo scripts. Safe upgrade from 2.10.0.
->
-> **v2.10.0** — Agent-readiness release. Karajan is now the first orchestrator with a full agent-readability surface: an `llms.txt` index at the root, a `SKILL.md` per CLI command under `docs/agents/`, and a static auditor that scores any third-party repo against the same shape. Highlights: (1) **`kj audit --agent-readiness`** scores any repo 0–100 across seven checks (llms.txt, robots AI-bot allowlist, page token budgets ≤ 32 KB, heading hierarchy, agents/README, SKILL.md coverage). LLM-free, deterministic, JSON-able. Karajan-on-Karajan: **100/100**. (2) **Six new SKILL.md files** (`kj doctor / init / board / review / resume / clean`) under `docs/agents/`, all with the same `What it does · Inputs · Outputs · Side effects · Failure modes · Example` contract; CI guards every link in `llms.txt` resolves. (3) **Webperf quality gate inside the iteration loop** (`pipeline.perf.enabled`): PASS continues, FAIL pushes blocking-metric feedback to the coder, scanner-missing skips best-effort. (4) **HU Board hardening**: binds 127.0.0.1 by default, opt-in `--bind 0.0.0.0` enforces an auto-generated token, helmet headers, rate limiting at 300 req/min — "safe by default on a coffee-shop WiFi". (5) **a11y skills auto-route**: tasks mentioning `accessibility / WCAG / ARIA / screen reader / keyboard nav` automatically pull the `frontend-ui-engineering` skill. (6) **Asciinema demo scripts** under `docs/demos/` so the recordings re-record per release instead of rotting. 5 PRs merged (#605–#609 + #610), 4358/4358 tests passing. See [CHANGELOG.md](./CHANGELOG.md) for the full punch list.
-
 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?
@@ -246,10 +216,12 @@ $ claude                         $ kj-tail
 ## The pipeline
 
 ```
-hu-reviewer? → triage → domain-curator? → discover? → architect? → planner? → coder → sonar? → impeccable? → reviewer → tester? → security? → solomon → commiter?
+pre-loop:  intent → hu-reviewer? → triage? → domain-curator? → discover? → skills? → researcher? → architect? → planner? → acceptance?
+iteration: coder → refactorer? → guard(output) → guard(perf) → sonar? → tdd → reviewer → solomon? → brain?   (loops 1..N)
+post-loop: tester? → security? → perf? → impeccable? → audit?
 ```
 
-**16 roles**, each executed by the AI agent you choose:
+**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:
 
 | Role | What it does | Default |
 |------|-------------|---------|
@@ -268,8 +240,17 @@ hu-reviewer? → triage → domain-curator? → discover? → architect? → pla
 | **security** | OWASP security audit | **On** |
 | **solomon** | Pipeline boss: evaluates every rejection, overrides style-only blocks | **On** |
 | **commiter** | Git commit, push, and PR automation after approval | Off |
+| **researcher** | Investigates the codebase before planning (file map + signatures + related tests) | Off |
+| **perf** | WebPerf quality gate — Core Web Vitals (LCP, CLS, INP) via Lighthouse | Off |
+| **brain** | Central AI orchestrator: routing, feedback enrichment, output compression | **On** |
 | **audit** | Read-only codebase health analysis (5 dimensions, A-F scores) | Standalone |
 
+> **Deterministic stages (no class):** `intent` (task-type classifier — `sw` / `infra` / `doc` / `add-tests` / `refactor` / `audit`), `skills` (slash-command surface), `acceptance` (executable acceptance tests), `guard(output)` (destructive ops + credential leaks), `guard(perf)` (frontend anti-patterns), `tdd` (test-coverage check).
+>
+> **Internal helpers (have a class, not a standalone stage):** `commiter` (git automation post-approval), `repairer` (repairs broken acceptance tests at runtime, invoked by `acceptance` / `tdd`).
+>
+> Full per-stage reference: [Pipeline roles](https://karajan-code.web.app/docs/handbook/pipeline-roles/) (handbook).
+
 ## 5 AI agents supported
 
 | Agent | CLI | Install |
@@ -362,6 +343,44 @@ No code, task descriptions, or personal data is ever sent.
 
 Opt out: set `telemetry: false` in `~/.karajan/kj.config.yml`
 
+## Recent releases
+
+> **v2.19.0 released** — Minor. Consolidates the HOME-level state of Karajan into a single root: **`~/.karajan/`**. Previously `~/.kj/` held plans, hibernated standby state, run-registry entries and worktrees, while `~/.karajan/` held sessions, hu-stories, config and the rest — no ADR justified the split and four divergent `getKjHome()` implementations had drifted. Three internal PRs land the change without breaking anyone: PR #781 unifies the resolver and introduces **`KARAJAN_HOME`** as the canonical env var (with `KJ_HOME` honoured + one-shot deprecation warning); PR #782 ships an idempotent **auto-migrator** that runs once on the next `kj` invocation — tarball backup at `~/.karajan/backup/kj-pre-migration-<ISO>.tar.gz` BEFORE moving, marker file `~/.karajan/.kj-migrated.json` prevents re-runs, cross-device safe (`rename` → `cp + rm` on `EXDEV`); PR #783 flips every default to `~/.karajan/` and adds a `legacy-kj-home` check to `kj doctor`. The HU Board reads BOTH locations until the migrator fires, so users who start the board first never see "missing plans". Restore is one `tar -xzf ~/.karajan/backup/kj-pre-migration-<ts>.tar.gz -C ~` away. Safe upgrade from 2.18.x.
+>
+> **v2.18.1 released** — Patch. Six user-feedback follow-ups to v2.18.0: **`kj-tail` after `kj resume`** (#772, was silent because `resume.js` skipped `withCliRunLog`); **standby waits in-process instead of exiting on a short cooldown** (#773, kj stays alive for waits ≤ 12 h and retries on its own; Ctrl+C during the wait prints `kj standby resume <id>`); **closed KJC-BUG-0040 — SEA linux binaries** (#774, was a race between `gh release create` and softprops, not `better-sqlite3` as the memory said — 60 s poll fix + `make_latest:false`); **stack bias — Python repos no longer get vitest** (#775 + #776 + #777, `detectProjectStack` finally cabled into the coder prompt, the HU auto-generator templates by language, and the synthesizer + `auto-hu-batch` take the stack from the filesystem). 4 971/4 971 tests passing across 416 files. Safe upgrade from 2.18.0.
+>
+> **v2.18.0** — Minor. Closes the **resilience audit** triggered by the public launch: 15 PRs across 5 phases hardening Karajan against the silent-failure family of bugs — *the problem is not that something fails, the problem is failing without telling the user why.* **Phase 1 — hibernation end to end** (#756–#759): a quota cap is classified as a recoverable quota class (incl. Claude Code's `"You've hit your session limit · resets 10:10pm"`); `withBrainRecovery` persists a standby JSON; the orchestrator consumes `action:"hibernate"`, seals the session `hibernated` (resumable) instead of `failed`; the last line printed is the exact resume command (`kj standby resume <id>`). **Phase 2 — don't lie** (#761–#763): `runCommand` surfaces ENOENT so a missing agent CLI gets an actionable error (not an empty one); `silenceTimeoutMs` is forwarded to every role so a hung agent is killed, not waited on forever; all 6 state-file writers go through `writeJsonAtomic` (write-temp + rename) — interrupted writes can no longer truncate plans, sessions, standby snapshots. **Phase 3 — don't lose or block** (#764–#767): a corrupt plan JSON is renamed aside with a loud warn (was silently dropped from `kj plan list`); `kj.config.yml` parse errors throw `Invalid YAML in <path>` (used to brick every kj command including `kj doctor`); `injectLoadedPlan` reconciles HUs left in `coding`/`reviewing`/`running` by a killed `kj run` (cross-checked against the run-registry); board SQLite gets `busy_timeout`, a `user_version` schema gate and corruption recovery. **Phase 4 — don't degrade silently** (#768–#769): `TriageRole` warns loudly when LLM output is unparseable (used to skip researcher/architect/security/tester with a chirpy "fallback defaults" summary); `verifyCoderOutput` distinguishes a git failure from "the coder did nothing" (`gitError` + `retryStrategy: null`) — no more iterations blaming the agent for infra. **Phase 5 — safety net** (#770): a `tests/resilience/` suite indexes every silent-failure mode and pins each one with a test, plus an end-to-end tripwire for the whole quota → hibernate → resume flow. Plus CI runs the `packages/hu-board` suite on every PR (#755). 4 959/4 959 tests passing across 416 files. Safe upgrade from 2.17.2.
+>
+> **v2.17.2** — Patch. Wires quota-exhaustion **hibernation end to end**. A `kj run` / `kj plan` that hits a provider session or usage cap used to abort the task with an opaque `UNKNOWN_FATAL`; now it suspends and tells you how to resume. **Session-limit classification (#756)**: `"You've hit your session limit · resets 10:10pm"` matched no rate-limit pattern → `session limit`/`weekly limit` added, and `parseCooldown` learns the 12-hour `resets 10:10pm` clock. **Hibernation persists (#757)**: `withBrainRecovery` only wrote `~/.kj/standby/<id>.json` with a `sessionState`, which no caller passed — new `buildStandbyState()` assembles it with an allowlisted env subset (never the full `process.env`). **Orchestrator consumes `action:"hibernate"` (#758)**: no code checked for it, so a hibernation sealed the HU `failed`; the coder/refactorer stages now stop cleanly and the session is sealed `hibernated` (resumable). **Resume hint (#759)**: a stopped run's last line is now the exact command — `kj standby resume <id>` for a hibernation, `kj resume <id>` otherwise. Plus CI now runs the `packages/hu-board` suite (#755). 4 931/4 931 tests passing across 410 files. Safe upgrade from 2.17.1.
+>
+> **v2.17.1** — Patch. Fixes **KJC-BUG-0055**: a project deleted from the HU Board (🗑️) no longer resurrects on the next `kj plan` or board restart. Four independent leaks closed: (1) **`sync.js` temporal gate** — the unconditional `removeTombstone` from KJC-BUG-0050 becomes a `plan.updatedAt > tombstone.deleted_at` comparison, so a tombstoned project revives only when the plan is genuinely newer than the delete; (2) **`ephemeral-cleaner.js`** now writes a tombstone and `rm -rf`'s `hu-stories/`, `sessions/` and `~/.kj/plans/` dirs when wiping ephemeral projects at boot — previously the orphan directories revived the project on the next scan; (3) **`fullScan` boot GC** sweeps orphan tombstoned dirs (the manual DB-wipe case); (4) **`DELETE /api/projects/:id`** honours `KJ_PLANS_DIR` instead of the hardcoded path. New `getTombstone()` helper in `db.js`. **Also fixes a silent `kj board start` failure (#753)**: the daemon's entry-point guard compared `import.meta.url` to a hand-built `file://` path, which wrongly returned false on Windows, symlinked/global installs and paths with spaces — the board exited 0 with an empty log. `server.js` now trusts a `KJ_BOARD_DAEMON` launcher flag, adds `uncaughtException`/`unhandledRejection` handlers and an actionable `better-sqlite3` load error; `board.js` detects an early daemon exit instead of reporting a phantom PID. 4 909/4 909 tests passing across 408 files. Safe upgrade from 2.17.0.
+>
+> **v2.17.0** — Minor. `kj audit` gains two new deterministic structural collectors and the v2.16 Sonar false-positive filter is generalised to apply across every collector. **Knip dead-exports collector** (codeQuality dim): reports unused exports/types (MINOR) and unused files (MAJOR), stack-aware (JS/TS only, needs package.json), subprocess via `--reporter json`, 120s timeout. **Madge circular-import collector** (architecture dim): detects import cycles, severity by chain length (≥4 files = MAJOR), honours tsconfig.json path aliases, 60s timeout. **Generalised FP filter**: every collector (sonar, knip, madge, osv, semgrep) now uses the same `config.audit.false_positives` shape with `tool` field plus inline marker `// karajan-audit-ignore: <tool>:<ruleId>`; legacy `config.sonar.false_positives` and `// karajan-sonar-ignore:` keep working. **Built-in catalogue** ships 4 entries by default (knip:unused-files in tests/fixtures + examples, knip:unused-exports on barrel files, madge cycles in node_modules). **BREAKING(engines)**: Node `>=20.10` → `>=20.19` (knip 6.x requirement; same flavour as the v2.8 18→20.10 bump). 4 872/4 872 tests passing across 402 files. Safe upgrade from 2.16.0 if you're on Node ≥ 20.19.
+>
+> **v2.16.0** — Minor. Quality-focused release: **deterministic Sonar false-positive filter** (KJC-TSK-0416), wire universal de Brain Recovery completado en `semantic-detector` (TSK-0413 step D), codemod `replace(/regex/g, …)` → `replaceAll(/regex/g, …)` en 41 sitios, y limpieza de hallazgos del propio `kj audit` v2.15.0. The Sonar filter combines two mechanisms: (1) **static rules** `{ rule, filePattern, reason }` from a built-in catalog (covering common false positives like `javascript:S2699` on `tests/architecture/`) plus extensible via `config.sonar.false_positives`; (2) **inline ignores** with `// karajan-sonar-ignore: <ruleId>` on the issue line. Result: the coder stops burning tokens "fixing" non-broken assertions. Brain Recovery now wraps **every** AI call in the pipeline — `semantic-detector` was the last legacy caller. 4 846/4 846 tests passing across 401 files. Safe upgrade from 2.15.0.
+>
+> **v2.15.0** — Minor. Three epics, 30+ commits, ~4 000 LOC. (1) **Brain Recovery** (KJC-PCS-0044): universal error classifier with 7 rich classes (rate_limit_short, quota_daily, quota_monthly, api_down, auth_failed, network_timeout, silenced, unknown_fatal), `withBrainRecovery` wrapper wired into ALL agent invocations (no silent failures), persistent hibernation in `~/.kj/standby/<id>.json` with event-driven scheduler (no polling), `kj standby list` + `kj standby resume`, board reconcile at startup, **fallback chain** when quota exhausted with `retryAfter > 12h` (Claude → Codex → OpenCode → Aider, configurable per role via `kj init`). (2) **Model Routing + Undo** (KJC-PCS-0043): each HU gets `coder_model` + `reviewer_model` with cross-provider review by default (claude↔codex), per-HU override from board modal, OpenCode + Aider as first-class providers, ⏪ Undo button restores files via git snapshots. (3) **Self-Healing Plan** (KJC-PCS-0042): structural integrity pass breaks cycles + cleans orphan refs, smart convergence guard for self-fix loop, `kj plan fix [planId] [--prompt]` for iterating without regenerating, skip Sonar for SPIKE/DOC/RESEARCH HUs, eliminate Failed kanban column. 4 835/4 835 tests passing across 400 files. Safe upgrade from 2.14.3.
+>
+> **v2.14.2** — Patch. More dogfooding fallout from GRETA Plan 2 v2.14.1: the **▶ Run button** on the HU Board appeared on every `pending` card regardless of `blocked_by` (you could launch a HU whose deps don't exist yet — the user caught it instantly), and titles on the board lost their **`[EPICA]` prefix** at some point in v2.14.x evolution, making it impossible to tell at a glance which area of the plan a card belonged to. Fixes: `canRunHu` now requires `blockedBy.length === 0` before showing ▶; the planner prompt now demands `description: "[EPICA] one-sentence description"` with INFRA/SHARED fallbacks. Plus a new doc `docs/task-templates/spec-conventions.md` collecting the 6 SPEC conventions the planner v2.14.x understands (épicas, scope exclusions, transversal deps, reuse, async observers, explicit deps), so users don't have to rediscover them by dogfooding. 2 PRs (#687, #688). 4584/4584 tests passing. Safe upgrade from 2.14.1.
+>
+> **v2.14.1** — Patch. Two more planner pathologies surfaced by dogfooding v2.14.0 against GRETA Plan 2: the **self-fix loop could regress** (iter 1 would drop 15→10 issues, iter 2 then deleted HUs the first iter had added, reaching 17 — worse than before iter 2 started) and the **planner declared `blocked_by` on async observers** (HUs that an async guardrail or cron *reacts to* were marked as depending on the guardrail, breaking the GRETA "AVISA-no-BLOQUEA" principle). Fixes: P5 snapshots the plan before each self-fix iter and reverts if `newCount > currentCount`; P6 lists six async-observer patterns in the planner prompt with a "consume vs react" heuristic. After P5+P6, regenerating Plan 2 GRETA returns to the baseline-iter-1 quality (9 findings) instead of v2.14.0's 17. 2 PRs (#684, #685). 4580/4580 tests passing. Safe upgrade from 2.14.0.
+>
+> **v2.14.0** — Quality pass. 16 PRs absorbing bug blockers (Solomon no longer rubber-stamps security issues misclassified as "style", coder filesystem-leak detection gains a second layer that catches `cd <abs> && pnpm init` even when the dir pre-existed, Sonar admin password rotation now surfaces silent failures), the four planner pathologies surfaced by the GRETA Plan 2 dogfooding (scope respect, transversal one-to-many deps, explicit `reuse` marker, and a brand-new **self-fix loop** where the plan-reviewer re-invokes the planner with structured feedback until zero issues remain), HU Board polish (zombie-TTL for crashed-runner prompts, less aggressive rate-limit with SSE exempt), and the first wave of `tests/` reorg (issue #368): ~93 files moved from root to mirror-subfolders. **4577/4577 tests passing**, **0 regressions** across all 16 PRs. Safe upgrade from 2.13.0.
+>
+> **v2.13.0** — HU Board hardening. Five PRs make the board resilient and self-healing after a dogfooding session uncovered four pathologies: a "Karajan needs an answer" prompt modal from days earlier blocking the entire UI, 18 zombi projects reappearing after every `kj board start`, the browser serving stale HTML/JS after a server restart, and the prompt modal showing a transparent background. Now: **tombstones** persist deletes across `fullScan` (`KJC-TSK-0380`), new endpoints `DELETE /api/prompts/:id`, `DELETE /api/plans/:planId`, `GET /api/tombstones`, `POST /api/tombstones/:type/:id/restore`; new command **`kj board cleanup`** sweeps ephemeral projects, orphan prompts and dangling session dirs in one pass; **`Cache-Control: no-store`** + `/api/version` polling auto-reloads the client when the server boot time changes; new **🧹 button** as manual escape hatch; CSS `--bg-secondary` finally declared so modals are opaque. 5 PRs (#654, #655, #656, #657, #658). 4522/4522 tests passing.
+>
+> **v2.12.0** — Quality-measurement release. Two new features land together: every `kj run` against a known plan now scores how faithfully the coder followed it (deterministic 0–100 **plan adherence** metric, four weighted components, rendered in `summary.md`), and a small **golden-tasks** regression suite (`todo-rest-api`, `npm-package-cli`, `react-counter-component`) catches output-quality drops between Karajan versions before npm publish. Plus the shrink-budget CI gate now exempts human-facing docs from its 200-LOC ceiling while keeping AI-rule files (CLAUDE.md, AGENTS.md, role prompts) capped. 3 PRs for plan adherence (#645–#647), 4 for golden tasks (#648, #650–#652), 1 for the CI policy (#649). 4522/4522 tests passing. Safe upgrade from 2.11.0.
+>
+> **v2.11.0** — Dogfooding pass release. Two-day pass through a 10-level test plan surfaced and fixed a long tail of UX papercuts and three latent bugs that only show up on fresh `/tmp` repos: the `SonarStage` no longer loops on remoteless projects (was burning iterations until `max_iterations`-fallback-approval), the post-loop `commitAll` now tolerates the locale-specific "nothing to commit" race, the HU sub-pipeline branches off `master`/`HEAD` when the configured `main` doesn't exist, and `runFlow` now seals `session.status` at the boundary so `kj status` never shows zombi `running` runs again. Plus `hu-board` gains automatic ephemeral-project cleanup and an in-UI help modal for the five views. 14 PRs (#624–#637), 4452/4452 tests passing. Safe upgrade from 2.10.2.
+>
+> **v2.10.2** — Patch release. `kj init` wizard expanded from 9 prompts to a full setup: per-role provider selection (10 roles, "inherit / pick CLI / disable"), automatic SonarQube token generation via REST API (no more web UI walkthrough), git automation flags (`auto_commit/push/pr`) and HU Board security (bind host + port). +16 new tests. Safe upgrade from 2.10.1.
+>
+> **v2.10.1** — Patch release. One-line fix for a stdout contamination bug in `kj audit --agent-readiness --json` (the `[info]` banner was breaking downstream `jq` pipes), plus polish in the asciinema demo scripts. Safe upgrade from 2.10.0.
+>
+> **v2.10.0** — Agent-readiness release. Karajan is now the first orchestrator with a full agent-readability surface: an `llms.txt` index at the root, a `SKILL.md` per CLI command under `docs/agents/`, and a static auditor that scores any third-party repo against the same shape. Highlights: (1) **`kj audit --agent-readiness`** scores any repo 0–100 across seven checks (llms.txt, robots AI-bot allowlist, page token budgets ≤ 32 KB, heading hierarchy, agents/README, SKILL.md coverage). LLM-free, deterministic, JSON-able. Karajan-on-Karajan: **100/100**. (2) **Six new SKILL.md files** (`kj doctor / init / board / review / resume / clean`) under `docs/agents/`, all with the same `What it does · Inputs · Outputs · Side effects · Failure modes · Example` contract; CI guards every link in `llms.txt` resolves. (3) **Webperf quality gate inside the iteration loop** (`pipeline.perf.enabled`): PASS continues, FAIL pushes blocking-metric feedback to the coder, scanner-missing skips best-effort. (4) **HU Board hardening**: binds 127.0.0.1 by default, opt-in `--bind 0.0.0.0` enforces an auto-generated token, helmet headers, rate limiting at 300 req/min — "safe by default on a coffee-shop WiFi". (5) **a11y skills auto-route**: tasks mentioning `accessibility / WCAG / ARIA / screen reader / keyboard nav` automatically pull the `frontend-ui-engineering` skill. (6) **Asciinema demo scripts** under `docs/demos/` so the recordings re-record per release instead of rotting. 5 PRs merged (#605–#609 + #610), 4358/4358 tests passing. See [CHANGELOG.md](./CHANGELOG.md) for the full punch list.
+
+See [CHANGELOG.md](./CHANGELOG.md) for the full version history.
+
 ## Links
 
 - [Website](https://karajancode.com) (also [kj-code.com](https://kj-code.com))

package/docs/README.es.md

@@ -141,10 +141,12 @@ kj-tail --help           # Todas las opciones
 ## El pipeline
 
 ```
-hu-reviewer? → triage → domain-curator? → discover? → architect? → planner? → coder → sonar? → impeccable? → reviewer → tester? → security? → solomon → commiter?
+pre-loop:  intent → hu-reviewer? → triage? → domain-curator? → discover? → skills? → researcher? → architect? → planner? → acceptance?
+iteration: coder → refactorer? → guard(output) → guard(perf) → sonar? → tdd → reviewer → solomon? → brain?   (bucle 1..N)
+post-loop: tester? → security? → perf? → impeccable? → audit?
 ```
 
-**16 roles**, cada uno ejecutado por el agente de IA que elijas:
+**24 etapas** repartidas en tres fases: 18 roles respaldados por agente IA (tabla abajo), 6 etapas deterministas sin llamada al LLM (`intent`, `skills`, `acceptance`, `guard(output)`, `guard(perf)`, `tdd`). Dos clases extra (`commiter`, `repairer`) son post-aprobación / auxiliares internas, no etapas independientes del pipeline. Cada rol IA es ejecutado por el agente que tú elijas:
 
 | Rol | Que hace | Por defecto |
 |-----|----------|-------------|
@@ -163,8 +165,17 @@ hu-reviewer? → triage → domain-curator? → discover? → architect? → pla
 | **security** | Auditoria de seguridad OWASP | **On** |
 | **solomon** | Jefe del pipeline: evalua cada rechazo, anula bloqueos solo de estilo | **On** |
 | **commiter** | Automatizacion de git commit, push y PR tras aprobacion | Off |
+| **researcher** | Investiga el codebase antes de planificar (mapa de ficheros + signatures + tests relacionados) | Off |
+| **perf** | Quality gate WebPerf — Core Web Vitals (LCP, CLS, INP) via Lighthouse | Off |
+| **brain** | Orquestador IA central: routing, enriquecimiento de feedback, compresión de salidas | **On** |
 | **audit** | Analisis de salud del codebase solo-lectura (5 dimensiones, scores A-F) | Standalone |
 
+> **Etapas deterministas (sin clase):** `intent` (clasificador de tipo de tarea — `sw` / `infra` / `doc` / `add-tests` / `refactor` / `audit`), `skills` (superficie de slash-commands), `acceptance` (tests de aceptación ejecutables), `guard(output)` (operaciones destructivas + fugas de credenciales), `guard(perf)` (anti-patrones frontend), `tdd` (verificación de cobertura).
+>
+> **Auxiliares internas (tienen clase, no etapa independiente):** `commiter` (automatización git post-aprobación), `repairer` (repara tests de aceptación rotos en runtime, invocado por `acceptance` / `tdd`).
+>
+> Referencia completa por etapa: [Roles del pipeline](https://karajan-code.web.app/docs/es/handbook/pipeline-roles/) (handbook).
+
 ## 5 agentes de IA soportados
 
 | Agente | CLI | Instalacion |

package/package.json

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

package/src/brain/standby-store.js

@@ -14,15 +14,17 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import os from "node:os";
 import { writeJsonAtomicSync } from "../utils/atomic-write.js";
+import { resolveHome } from "../utils/paths.js";
 
 const FILENAME_RE = /^[a-zA-Z0-9._-]+\.json$/;
 
+// Delegates to the unified resolver. PR 3 of KJC-PCS-0047 switched
+// the default to `.karajan` — hibernated sessions now persist under
+// `~/.karajan/standby/`, migrated automatically from the legacy
+// `~/.kj/standby/` on the next `kj` invocation.
 function getKjHome() {
-  if (process.env.KJ_HOME) return process.env.KJ_HOME;
-  if (process.env.VITEST) return path.join(os.tmpdir(), `kj-vitest-${process.pid}-${Math.random().toString(36).slice(2, 10)}`, ".kj");
-  return path.join(os.homedir(), ".kj");
+  return resolveHome({ defaultSegment: ".karajan" });
 }
 
 export function standbyDir() {

package/src/brain/with-brain-recovery.js

@@ -7,7 +7,7 @@
 // puede ignorarlo (fallback a long standby capped) hasta que llegue 0414.
 
 import { classifyAgentError, ERROR_CLASS } from "./agent-error-classifier.js";
-import { persistStandby } from "./standby-store.js";
+import { persistStandby, markStandbyDone } from "./standby-store.js";
 
 const ONE_MIN = 60 * 1000;
 
@@ -20,6 +20,13 @@ export const DEFAULT_RECOVERY_POLICY = Object.freeze({
   // KJC-TSK-0415: threshold de fallback. Si retryAfter > esto Y el role
   // tiene fallback configurado → switch provider en vez de hibernar.
   fallbackWaitHoursDefault: DEFAULT_FALLBACK_WAIT_HOURS,
+  // Standby-in-process: when the cooldown is short enough we keep the
+  // process alive and `await sleepFn(retryAfter)`, then retry the
+  // agent. The user sees nothing terminal — kj just pauses. A SIGINT /
+  // SIGTERM during the wait prints `kj standby resume <id>` and exits
+  // cleanly. For waits longer than this the process exits straight
+  // away (a multi-day weekly cap is not worth keeping kj running).
+  standbyWaitHoursMax: DEFAULT_FALLBACK_WAIT_HOURS,
   classes: {
     [ERROR_CLASS.RATE_LIMIT_SHORT]: { mode: "standby", maxRetries: 3 },
     [ERROR_CLASS.QUOTA_EXHAUSTED_DAILY]: { mode: "hibernate", maxRetries: 1, fallbackEligible: true },
@@ -132,10 +139,15 @@ export async function withBrainRecovery({
       }
     }
 
-    // HIBERNATE: persistir + signal action=hibernate al caller.
-    // Si el caller pasó `sessionState` (TSK-0414 PR2), persistimos el JSON
-    // automáticamente en ~/.kj/standby/<sessionId>.json. Caller decide qué
-    // hacer con action=hibernate (típicamente exit 0 para liberar memoria).
+    // HIBERNATE: the cooldown is too long for a short standby. Persist
+    // the snapshot first so a SIGINT / SIGTERM during the wait leaves a
+    // recoverable session on disk. Then either:
+    //   (a) wait in-process until cooldownUntil and retry (the common
+    //       case — daily quotas reset in a few hours), or
+    //   (b) when the wait would exceed `standbyWaitHoursMax`, return
+    //       action="hibernate" so the caller exits and the user
+    //       resumes later with `kj standby resume <id>` (weekly /
+    //       monthly caps).
     if (classPolicy.mode === "hibernate" && cls.retryAfter && cls.retryAfter > policy.hibernateThresholdMs) {
       let standbyFile = null;
       if (sessionState && sessionState.sessionId) {
@@ -147,13 +159,58 @@ export async function withBrainRecovery({
             role, provider: effectiveProvider,
             classifierMessage: cls.message,
           });
-          logger?.info?.(`[brain] hibernated session ${sessionState.sessionId} → ${standbyFile} (resume at ${cls.retryUntil})`);
         } catch (err) {
           logger?.warn?.(`[brain] failed to persist standby: ${err.message}`);
         }
       }
-      emit(emitter, "brain:hibernate-request", eventBase, { role, class: cls.class, retryUntil: cls.retryUntil, retryAfter: cls.retryAfter, standbyFile });
-      return { ok: false, action: "hibernate", recovery: cls, standbyFile };
+
+      const maxWaitMs = (policy.standbyWaitHoursMax ?? DEFAULT_FALLBACK_WAIT_HOURS) * ONE_HOUR;
+      const tooLongToWait = cls.retryAfter > maxWaitMs;
+
+      if (tooLongToWait) {
+        logger?.info?.(`[brain] hibernated session ${sessionState?.sessionId ?? "(no id)"} → ${standbyFile} (resume at ${cls.retryUntil}; wait > ${Math.round(maxWaitMs/ONE_HOUR)}h, exiting)`);
+        emit(emitter, "brain:hibernate-request", eventBase, { role, class: cls.class, retryUntil: cls.retryUntil, retryAfter: cls.retryAfter, standbyFile });
+        return { ok: false, action: "hibernate", recovery: cls, standbyFile };
+      }
+
+      // Standby-in-process: keep kj alive, sleep until the cooldown,
+      // then retry. A SIGINT / SIGTERM during the wait prints the
+      // resume command and exits — the standby JSON is already on
+      // disk so the user can pick it up later.
+      const sid = sessionState?.sessionId ?? null;
+      const onSignal = (signal) => {
+        // eslint-disable-next-line no-console
+        console.log(`\n⏸  Standby interrupted (${signal}). Resume with:`);
+        // eslint-disable-next-line no-console
+        if (sid) console.log(`     kj standby resume ${sid}`);
+        // eslint-disable-next-line no-console
+        else console.log(`     kj standby list   (no session id was assigned)`);
+        process.exit(signal === "SIGINT" ? 130 : 143);
+      };
+      const detach = () => {
+        process.removeListener("SIGINT", onSignal);
+        process.removeListener("SIGTERM", onSignal);
+      };
+      process.once("SIGINT", onSignal);
+      process.once("SIGTERM", onSignal);
+
+      const hours = Math.round((cls.retryAfter / ONE_HOUR) * 10) / 10;
+      logger?.info?.(`[brain] ${role}: standby for ~${hours}h until ${cls.retryUntil} (Ctrl+C to detach; will resume with 'kj standby resume ${sid}').`);
+      emit(emitter, "brain:standby-wait", eventBase, { role, class: cls.class, waitMs: cls.retryAfter, retryUntil: cls.retryUntil, standbyFile });
+
+      try {
+        await sleepFn(cls.retryAfter);
+      } finally {
+        detach();
+      }
+
+      // Wait finished without an interrupt — mark the standby JSON
+      // done so it does not auto-resume from disk later.
+      if (sid) {
+        try { markStandbyDone(sid); } catch { /* ignore */ }
+      }
+      emit(emitter, "brain:standby-resumed", eventBase, { role, class: cls.class });
+      continue;
     }
 
     // STANDBY: espera hasta cooldownUntil (capado por longStandbyCapMs).

package/src/checks/dir-setup.js

@@ -62,6 +62,40 @@ export function createKarajanDirsCheck() {
   };
 }
 
+/**
+ * Detect a populated legacy `~/.kj/` left over from before
+ * KJC-PCS-0047 PR 3. The auto-migrator (src/utils/home-migration.js)
+ * moves its contents to `~/.karajan/` on the next `kj` invocation,
+ * so the fix is simply "run any kj command". Severity is `warn`
+ * (informational) because the legacy dir does not break anything —
+ * it just won't get read by the board until the migration runs.
+ * @internal Exported for dynamic import from tests.
+ */
+export function createLegacyKjHomeCheck() {
+  return {
+    name: "legacy-kj-home",
+    label: "legacy ~/.kj/ directory",
+    strategy: STRATEGY.MANUAL,
+    describe: "Detect unmigrated ~/.kj/ left over from pre-2.19 layout",
+    async detect() {
+      const legacy = path.join(os.homedir(), ".kj");
+      try {
+        const entries = await fs.readdir(legacy);
+        if (entries.length === 0) return { ok: true, severity: "info", detail: "Empty legacy ~/.kj/" };
+        const marker = path.join(os.homedir(), ".karajan", ".kj-migrated.json");
+        try { await fs.access(marker); return { ok: true, severity: "info", detail: "Already migrated" }; }
+        catch { /* no marker, still pending */ }
+        return {
+          ok: false,
+          severity: "warn",
+          detail: `~/.kj/ still has ${entries.length} entries; will be migrated on the next kj invocation`,
+          fix: "Run any kj command (e.g. `kj doctor`) — the migrator runs automatically",
+        };
+      } catch { return { ok: true, severity: "info", detail: "No legacy ~/.kj/" }; }
+    },
+  };
+}
+
 export function getDirSetupChecks() {
-  return [createKarajanDirsCheck()];
+  return [createKarajanDirsCheck(), createLegacyKjHomeCheck()];
 }

package/src/cli.js

@@ -12,6 +12,7 @@ import { registerSonar } from "./cli/register-sonar.js";
 import { registerStandby } from "./cli/register-standby.js";
 import { printUpdateNotice } from "./utils/update-check.js";
 import { printWelcomeScreen } from "./utils/welcome.js";
+import { migrateKjToKarajan } from "./utils/home-migration.js";
 
 const PKG_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../package.json");
 const PKG_VERSION = JSON.parse(readFileSync(PKG_PATH, "utf8")).version;
@@ -107,6 +108,18 @@ program.action(async (_opts, command) => {
   printWelcomeScreen({ version: PKG_VERSION, config });
 });
 
+// One-shot ~/.kj/ → ~/.karajan/ consolidation. Idempotent via marker
+// file; failures non-blocking. See src/utils/home-migration.js.
+// Static import — the migrator runs on every kj invocation, no
+// lazy-load benefit + the architectural dynamic-imports budget would
+// otherwise grow by one for a permanent caller.
+try {
+  await migrateKjToKarajan();
+} catch (err) {
+  // eslint-disable-next-line no-console
+  console.warn(`\x1b[33m[warn]\x1b[0m home migration skipped: ${err.message}`);
+}
+
 try {
   await program.parseAsync();
 } catch (error) {

package/src/commands/resume.js

@@ -3,6 +3,8 @@ import readline from "node:readline";
 import { resumeFlow } from "../orchestrator.js";
 import { createActivityLog } from "../activity-log.js";
 import { printEvent } from "../utils/display/event-handlers.js";
+import { withCliRunLog } from "../utils/cli-run-log.js";
+import { registerRun, unregisterRun } from "../utils/run-registry.js";
 
 function createCliAskQuestion(opts = {}) {
   const { sessionId = null } = opts;
@@ -51,36 +53,55 @@ export async function resumeCommand({ sessionId, answer, config, logger, flags }
   const jsonMode = flags?.json;
   const quietMode = config.output?.quiet !== false;
 
-  const emitter = new EventEmitter();
-  let activityLog = null;
+  // Same wrapper as every other CLI command — without it `.kj/run.log`
+  // is never opened during the resume and `kj-tail` stays silent
+  // (every line of the resumed run goes only to the per-session
+  // activity log + the local console). Also registers the run so the
+  // HU Board shows it as live and can offer its Stop button.
+  return withCliRunLog("resume", { projectDir: config?.projectDir, logger }, async ({ forwardProgress }) => {
+    const runId = registerRun({
+      pid: process.pid,
+      planId: flags?.plan || null,
+      huIds: null,
+      projectDir: config?.projectDir || process.cwd(),
+      source: "cli-resume",
+    });
+    const cleanupRegistry = () => { if (runId) unregisterRun(runId); };
+    process.once("exit", cleanupRegistry);
+    process.once("SIGTERM", () => { cleanupRegistry(); process.exit(143); });
+    process.once("SIGINT", () => { cleanupRegistry(); process.exit(130); });
 
-  emitter.on("progress", (event) => {
-    if (!activityLog && event.sessionId) {
-      activityLog = createActivityLog(event.sessionId);
-      logger.onLog((entry) => activityLog.write(entry));
-    }
+    const emitter = new EventEmitter();
+    let activityLog = null;
+    forwardProgress(emitter);
 
-    if (activityLog) {
-      activityLog.writeEvent(event);
-    }
+    emitter.on("progress", (event) => {
+      if (!activityLog && event.sessionId) {
+        activityLog = createActivityLog(event.sessionId);
+        logger.onLog((entry) => activityLog.write(entry));
+      }
+      if (activityLog) {
+        activityLog.writeEvent(event);
+      }
+      if (!jsonMode) {
+        printEvent(event, { quiet: quietMode });
+      }
+    });
 
-    if (!jsonMode) {
-      printEvent(event, { quiet: quietMode });
-    }
-  });
+    const askQuestion = createCliAskQuestion();
+    const result = await resumeFlow({
+      sessionId,
+      answer: answer || null,
+      config,
+      logger,
+      flags: flags || {},
+      emitter,
+      askQuestion
+    });
 
-  const askQuestion = createCliAskQuestion();
-  const result = await resumeFlow({
-    sessionId,
-    answer: answer || null,
-    config,
-    logger,
-    flags: flags || {},
-    emitter,
-    askQuestion
+    if (jsonMode || !answer) {
+      console.log(JSON.stringify(result, null, 2));
+    }
+    return result;
   });
-
-  if (jsonMode || !answer) {
-    console.log(JSON.stringify(result, null, 2));
-  }
 }

package/src/hu/auto-generator.js

@@ -66,64 +66,191 @@ export function needsSetupHu({ isNewProject = false, stackHints = [], subtasks =
   return subtasks.some(s => setupKeywords.test(s));
 }
 
+// Stack-hint keyword sets. Used by filterConflictingHints (drop hints
+// from other ecosystems once one is detected) and by
+// resolveLanguageFromHints (pick the canonical language for setup +
+// acceptance_tests templates).
+const HINT_NODE = new Set(["express", "vite", "vitest", "jest", "next", "astro", "react", "vue", "svelte", "nestjs", "monorepo", "workspaces"]);
+const HINT_PYTHON = new Set(["pytest", "flask", "fastapi", "django", "numpy", "pandas"]);
+const HINT_GO = new Set(["gin", "fiber", "go"]);
+const HINT_RUST = new Set(["cargo", "rust"]);
+
 /**
- * Filter conflicting stack hints. When Node.js ecosystem keywords are present,
- * remove Go/Rust/Python keywords that were detected from gitignore patterns
- * but aren't actually part of the task.
+ * Drop hints from OTHER ecosystems when one is clearly the project's.
+ * Symmetric: previously only node-vs-go was filtered, so a Python
+ * project that also had "vitest" in a stale gitignore would still
+ * receive vitest in its setup HU.
  */
 function filterConflictingHints(hints) {
   if (!hints || hints.length === 0) return hints;
-  const nodeEcosystem = new Set(["express", "vite", "vitest", "jest", "next", "astro", "react", "vue", "svelte", "nestjs", "monorepo", "workspaces"]);
-  const goKeywords = new Set(["gin", "fiber", "go"]);
-  const hasNode = hints.some(h => nodeEcosystem.has(h));
-  if (!hasNode) return hints;
-  return hints.filter(h => !goKeywords.has(h));
+  const setForEachLang = [
+    ["python", HINT_PYTHON],
+    ["go", HINT_GO],
+    ["rust", HINT_RUST],
+    ["node", HINT_NODE],
+  ];
+  const present = setForEachLang.filter(([, set]) => hints.some((h) => set.has(h)));
+  if (present.length <= 1) return hints;
+  // First ecosystem found in the original hints order wins. We keep
+  // ambiguous keywords (those not in any set) and the winner's own
+  // keywords; we drop the explicit losers from competing ecosystems.
+  const winnerSet = present[0][1];
+  const losers = present.slice(1).flatMap(([, s]) => [...s]);
+  return hints.filter((h) => winnerSet.has(h) || !losers.includes(h));
+}
+
+/**
+ * Pick the canonical language for setup + acceptance_test templates
+ * based on the (already filtered) stack hints. Falls back to
+ * javascript so existing Node-centric runs keep their previous shape.
+ * @param {string[]} hints
+ * @returns {"python"|"go"|"rust"|"javascript"}
+ */
+export function resolveLanguageFromHints(hints) {
+  if (!hints || hints.length === 0) return "javascript";
+  if (hints.some((h) => HINT_PYTHON.has(h))) return "python";
+  if (hints.some((h) => HINT_GO.has(h))) return "go";
+  if (hints.some((h) => HINT_RUST.has(h))) return "rust";
+  return "javascript";
+}
+
+// HU templates per language. The JS template is the legacy default;
+// the others were missing — every autogenerated HU got vitest /
+// npm-install hardcoded acceptance_tests regardless of stack.
+const HU_TEMPLATES = {
+  javascript: {
+    pkgManager: "npm",
+    setupBullets: [
+      "- Create package.json (with workspaces if monorepo detected from stack hints)",
+      "- Install all runtime + dev dependencies listed in stack hints",
+      "- Install test framework WITH coverage reporter (e.g. vitest + @vitest/coverage-v8)",
+      "- Configure vitest.config.js with coverage.enabled = true",
+      "- Create .env.example with placeholder variables",
+    ],
+    setupCriteria: [
+      "npm install succeeds without errors",
+      "npm test runs without error",
+      "npm run test:coverage runs without error",
+      ".env.example exists",
+    ],
+    setupTests: [
+      "npm install --ignore-scripts 2>&1 && echo PASS || echo FAIL",
+      "npx vitest run 2>&1; test $? -eq 0 && echo PASS || echo FAIL",
+      "npx vitest run --coverage 2>&1 | grep -q 'All files\\|% Stmts' && echo PASS || echo FAIL",
+      "test -f .env.example && echo PASS || echo FAIL",
+    ],
+    taskTests: [
+      "npx vitest run 2>&1; test $? -eq 0 && echo PASS || echo FAIL",
+      "npx vitest run --coverage 2>&1 | grep -q 'All files\\|% Stmts' && echo PASS || echo FAIL",
+    ],
+  },
+  python: {
+    pkgManager: "pip",
+    setupBullets: [
+      "- Create pyproject.toml (preferred) or requirements.txt",
+      "- Create a virtual env: python -m venv .venv",
+      "- Install runtime + dev dependencies (pip install -e . or pip install -r requirements.txt)",
+      "- Install pytest with coverage (pip install pytest pytest-cov)",
+      "- Create .env.example with placeholder variables",
+    ],
+    setupCriteria: [
+      "Project metadata file exists (pyproject.toml or requirements.txt)",
+      "pytest runs without error",
+      "pytest --cov reports a total",
+      ".env.example exists",
+    ],
+    setupTests: [
+      "(test -f pyproject.toml || test -f requirements.txt) && echo PASS || echo FAIL",
+      "python -m pytest 2>&1; test $? -eq 0 && echo PASS || echo FAIL",
+      "python -m pytest --cov 2>&1 | grep -q 'TOTAL\\|coverage' && echo PASS || echo FAIL",
+      "test -f .env.example && echo PASS || echo FAIL",
+    ],
+    taskTests: [
+      "python -m pytest 2>&1; test $? -eq 0 && echo PASS || echo FAIL",
+      "python -m pytest --cov 2>&1 | grep -q 'TOTAL\\|coverage' && echo PASS || echo FAIL",
+    ],
+  },
+  go: {
+    pkgManager: "go",
+    setupBullets: [
+      "- Create go.mod with `go mod init <module>`",
+      "- Install dependencies with `go get` per import",
+      "- Create .env.example with placeholder variables",
+    ],
+    setupCriteria: [
+      "go.mod exists",
+      "go test ./... runs without error",
+      "go test -cover reports coverage",
+      ".env.example exists",
+    ],
+    setupTests: [
+      "test -f go.mod && echo PASS || echo FAIL",
+      "go test ./... 2>&1; test $? -eq 0 && echo PASS || echo FAIL",
+      "go test -cover ./... 2>&1 | grep -q 'coverage:' && echo PASS || echo FAIL",
+      "test -f .env.example && echo PASS || echo FAIL",
+    ],
+    taskTests: [
+      "go test ./... 2>&1; test $? -eq 0 && echo PASS || echo FAIL",
+    ],
+  },
+  rust: {
+    pkgManager: "cargo",
+    setupBullets: [
+      "- Initialise the crate with `cargo init`",
+      "- Add dependencies with `cargo add`",
+      "- Create .env.example with placeholder variables",
+    ],
+    setupCriteria: [
+      "Cargo.toml exists",
+      "cargo test runs without error",
+      ".env.example exists",
+    ],
+    setupTests: [
+      "test -f Cargo.toml && echo PASS || echo FAIL",
+      "cargo test 2>&1; test $? -eq 0 && echo PASS || echo FAIL",
+      "test -f .env.example && echo PASS || echo FAIL",
+    ],
+    taskTests: [
+      "cargo test 2>&1; test $? -eq 0 && echo PASS || echo FAIL",
+    ],
+  },
+};
+
+function templateFor(language) {
+  return HU_TEMPLATES[language] || HU_TEMPLATES.javascript;
 }
 
 /**
  * Build a MINIMAL setup HU — project structure + deps only.
  * NEVER includes the full original task. The coder must only do setup.
  */
-function buildSetupHu({ stackHints }) {
+function buildSetupHu({ stackHints, language = "javascript" }) {
+  const tpl = templateFor(language);
   const deps = stackHints.length > 0
     ? stackHints.map(h => `- ${h}`).join("\n")
     : "- (auto-detect from subsequent HUs)";
   const certifiedText = [
-    "**Setup: initialize project structure and install dependencies.**",
+    `**Setup: initialise the ${language} project + install dependencies (package manager: ${tpl.pkgManager}).**`,
     "",
     "SCOPE (do ONLY this, nothing else):",
-    "- Create package.json (with workspaces if monorepo detected from stack hints)",
-    "- Install all runtime + dev dependencies listed in stack hints",
-    "- Install test framework WITH coverage reporter (e.g. vitest + @vitest/coverage-v8)",
-    "- Configure vitest.config.js with coverage.enabled = true",
-    "- Create .env.example with placeholder variables",
+    ...tpl.setupBullets,
     "- Verify by running each acceptance_test command below",
     "",
     "DO NOT implement any business logic, API routes, components, or features.",
     "This HU is ONLY project scaffolding.",
     "",
     "Stack hints:",
-    deps
+    deps,
   ].join("\n");
   return {
     id: "HU-01",
-    title: "Setup: project structure + dependencies",
+    title: `Setup: ${language} project structure + dependencies`,
     task_type: "infra",
     status: "certified",
     blocked_by: [],
     certified: { text: certifiedText },
-    acceptance_criteria: [
-      "npm install succeeds without errors",
-      "npm test runs without error",
-      "npm run test:coverage runs without error",
-      ".env.example exists"
-    ],
-    acceptance_tests: [
-      "npm install --ignore-scripts 2>&1 && echo PASS || echo FAIL",
-      "npx vitest run 2>&1; test $? -eq 0 && echo PASS || echo FAIL",
-      "npx vitest run --coverage 2>&1 | grep -q 'All files\\|% Stmts' && echo PASS || echo FAIL",
-      "test -f .env.example && echo PASS || echo FAIL"
-    ]
+    acceptance_criteria: tpl.setupCriteria,
+    acceptance_tests: tpl.setupTests,
   };
 }
 
@@ -131,8 +258,9 @@ function buildSetupHu({ stackHints }) {
  * Build a MINIMAL task HU — one specific, focused piece of work.
  * Includes a short goal reference (max 80 chars) NOT the full task.
  */
-function buildTaskHu({ id, subtask, projectName, blockedBy }) {
+function buildTaskHu({ id, subtask, projectName, blockedBy, language = "javascript" }) {
   const taskType = classifyTaskType(subtask);
+  const tpl = templateFor(language);
   const certifiedText = [
     `**${subtask}**`,
     "",
@@ -143,7 +271,7 @@ function buildTaskHu({ id, subtask, projectName, blockedBy }) {
     "- Add unit tests for the new code",
     "- Run ALL acceptance_tests listed below and ensure they pass",
     "- Do NOT touch code outside this subtask's scope",
-    "- Target: <200 lines changed (like an atomic PR)"
+    "- Target: <200 lines changed (like an atomic PR)",
   ].join("\n");
   return {
     id,
@@ -155,12 +283,9 @@ function buildTaskHu({ id, subtask, projectName, blockedBy }) {
     acceptance_criteria: [
       `${subtask} is implemented and working`,
       "Unit tests cover the new code",
-      "All acceptance_tests pass"
+      "All acceptance_tests pass",
     ],
-    acceptance_tests: [
-      "npx vitest run 2>&1; test $? -eq 0 && echo PASS || echo FAIL",
-      "npx vitest run --coverage 2>&1 | grep -q 'All files\\|% Stmts' && echo PASS || echo FAIL"
-    ]
+    acceptance_tests: tpl.taskTests,
   };
 }
 
@@ -182,7 +307,8 @@ export function generateHuBatch({
   stackHints = [],
   isNewProject = false,
   researcherContext = null,
-  architectContext = null
+  architectContext = null,
+  language = null,
 }) {
   if (!originalTask || typeof originalTask !== "string") {
     throw new Error("generateHuBatch: originalTask is required");
@@ -194,12 +320,17 @@ export function generateHuBatch({
   const stories = [];
   const filteredHints = filterConflictingHints(stackHints);
   const needsSetup = needsSetupHu({ isNewProject, stackHints: filteredHints, subtasks });
+  // Caller may pass a language explicitly (when it has a real
+  // detectProjectStack result from the filesystem); otherwise fall
+  // back to inferring from the hint keywords. Default 'javascript'
+  // matches the previous behaviour for Node-centric runs.
+  const resolvedLanguage = language || resolveLanguageFromHints(filteredHints);
   let nextId = 1;
 
   const projectName = deriveProjectName(originalTask);
 
   if (needsSetup) {
-    stories.push(buildSetupHu({ stackHints: filteredHints }));
+    stories.push(buildSetupHu({ stackHints: filteredHints, language: resolvedLanguage }));
     nextId = 2;
   }
 
@@ -211,7 +342,7 @@ export function generateHuBatch({
     const blockedBy = [];
     if (setupId) blockedBy.push(setupId);
     if (previousId && previousId !== setupId) blockedBy.push(previousId);
-    stories.push(buildTaskHu({ id, subtask, projectName, blockedBy }));
+    stories.push(buildTaskHu({ id, subtask, projectName, blockedBy, language: resolvedLanguage }));
     previousId = id;
     nextId += 1;
   }

package/src/orchestrator/drivers/pre-loop-phases/auto-hu-batch.js

@@ -16,6 +16,7 @@
  */
 
 import { emitProgress, makeEvent } from "#utils/events.js";
+import { detectProjectStack } from "#utils/stack-detect.js";
 
 export async function maybeGenerateAutoHuBatch({
   flags, stageResults, task, logger, emitter, eventBase, projectDir, session,
@@ -40,19 +41,38 @@ export async function maybeGenerateAutoHuBatch({
     isNewProject = relevant.length === 0;
   } catch { /* ignore */ }
 
-  // Extract stack hints from planner + architect output
+  // Stack hints from planner + architect text. Now multi-ecosystem
+  // (was 13/16 JS keywords — Python/Go/Rust barely existed). Combined
+  // with `detectProjectStack(projectDir)` below to override the text
+  // heuristic with the actual filesystem reality when available.
   const stackHints = [];
   const combined = `${stageResults.planner?.plan || ""} ${stageResults.architect?.architecture ? JSON.stringify(stageResults.architect.architecture) : ""} ${task}`.toLowerCase();
-  const stackKeywords = ["express", "vite", "vitest", "jest", "next", "astro", "react", "vue", "svelte", "fastapi", "django", "spring", "gin", "nestjs", "monorepo", "workspaces"];
+  const stackKeywords = [
+    "express", "vite", "vitest", "jest", "next", "astro", "react", "vue", "svelte", "nestjs", "monorepo", "workspaces",
+    "pytest", "flask", "fastapi", "django", "numpy", "pandas",
+    "gin", "fiber", "go",
+    "cargo", "rust",
+    "spring",
+  ];
   for (const kw of stackKeywords) {
     if (combined.includes(kw)) stackHints.push(kw);
   }
 
+  // Filesystem trumps text. detectProjectStack inspects package.json /
+  // pyproject.toml / go.mod / Cargo.toml, so a pure-python repo gets
+  // `language: "python"` regardless of what the task text says.
+  let detectedLanguage = null;
+  try {
+    const fsStack = await detectProjectStack(projectDir);
+    if (fsStack?.language) detectedLanguage = fsStack.language;
+  } catch { /* best-effort */ }
+
   const batch = generateHuBatch({
     originalTask: task,
     subtasks,
     stackHints,
     isNewProject,
+    language: detectedLanguage,
     researcherContext: stageResults.researcher?.summary || null,
     architectContext: stageResults.architect?.architecture ? JSON.stringify(stageResults.architect.architecture) : null
   });

package/src/plan/plan-store.js

@@ -6,8 +6,8 @@
 
 import fs from "node:fs/promises";
 import path from "node:path";
-import os from "node:os";
 import { writeJsonAtomic } from "../utils/atomic-write.js";
+import { resolveHome } from "../utils/paths.js";
 import { generatePlanId, normaliseAlias } from "./plan-id.js";
 
 /**
@@ -38,33 +38,13 @@ async function handleCorruptPlanFile(filePath, error) {
 }
 import { isPlanV2, migratePlanV1toV2 } from "./plan-schema.js";
 
-// Per-process tmp dir for VITEST runs that forget to set KJ_HOME. We
-// memoise across calls so every helper in the same test process sees
-// the same root (mirrors what setting KJ_HOME explicitly would do)
-// without racing. The trailing `.kj` segment keeps semantic parity
-// with non-VITEST defaults so existing path assertions don't break.
-let _vitestKjHome = null;
-function vitestTmpKjHome() {
-  if (_vitestKjHome) return _vitestKjHome;
-  _vitestKjHome = path.join(
-    os.tmpdir(),
-    `kj-vitest-${process.pid}-${Math.random().toString(36).slice(2, 10)}`,
-    ".kj"
-  );
-  return _vitestKjHome;
-}
-
+// Delegates to the unified resolver in src/utils/paths.js. PR 3 of
+// KJC-PCS-0047 flipped the default from `.kj` to `.karajan` — plans
+// now live under `~/.karajan/plans/`. The migrator (src/utils/
+// home-migration.js) auto-moves legacy `~/.kj/plans/` content on the
+// next `kj` invocation, so existing users are not stranded.
 export function getKjHome() {
-  if (process.env.KJ_HOME) return process.env.KJ_HOME;
-  // VITEST guard — without this, a test that calls savePlan() drops
-  // fixture files into the developer's real `~/.kj/plans/` and the
-  // running HU Board's chokidar watcher ingests them as "real" plans
-  // (observed: 49 fake "Add auth" plans contaminating the user's
-  // board). Auto-isolate to a per-process tmp dir so accidental
-  // writes can't leak. Tests that NEED to assert against a known
-  // path should still set KJ_HOME explicitly.
-  if (process.env.VITEST) return vitestTmpKjHome();
-  return path.join(os.homedir(), ".kj");
+  return resolveHome({ defaultSegment: ".karajan" });
 }
 
 /**

package/src/plan/tests-synthesizer.js

@@ -33,7 +33,7 @@ import { withBrainRecovery } from "../brain/with-brain-recovery.js";
  * @param {Array<{ id: string, title?: string, scope?: string }>} args.husNeedingTests
  * @returns {string}
  */
-export function buildSynthesizerPrompt({ task, husNeedingTests }) {
+export function buildSynthesizerPrompt({ task, husNeedingTests, stack = null, testFramework = null }) {
   const lines = [
     "You previously generated an implementation plan for the task below, but some HUs were left without acceptance_tests.",
     "Your ONLY job in this call is to fill that gap.",
@@ -59,12 +59,22 @@ export function buildSynthesizerPrompt({ task, husNeedingTests }) {
     "- Tests must be writable BEFORE the HU is implemented (they should fail until done).",
     "- Return ONLY the JSON — no prose, no markdown fences around it.",
     "",
-    "## Task",
-    task,
-    "",
-    "## HUs that need acceptance_tests",
-    "",
   ];
+  // Stack-aware hint: tell the LLM what test framework / language to
+  // emit shell commands for. Without this it defaulted to vitest /
+  // npm even on Python / Go / Rust projects (sesgo-de-stack audit).
+  if (stack || testFramework) {
+    lines.push("## Project Stack — generate shell tests for THIS stack, not generic JS");
+    if (stack?.language) lines.push(`- Language: **${stack.language}**`);
+    if (stack?.frameworks?.length) lines.push(`- Frameworks: ${stack.frameworks.join(", ")}`);
+    if (testFramework?.hasTests && testFramework?.framework) {
+      lines.push(`- Test framework already in use: **${testFramework.framework}** — use it for the shell commands.`);
+    } else if (stack?.language && stack.language !== "javascript" && stack.language !== "typescript") {
+      lines.push(`- Use the canonical test runner for ${stack.language} (pytest / go test / cargo test / rspec). Do NOT emit vitest, jest, or npm commands.`);
+    }
+    lines.push("");
+  }
+  lines.push("## Task", task, "", "## HUs that need acceptance_tests", "");
   for (const hu of husNeedingTests) {
     lines.push(`### ${hu.id}: ${hu.title || ""}`);
     lines.push(hu.scope ? `Scope: ${hu.scope}` : "(no scope)");

package/src/prompts/coder.js

@@ -158,7 +158,28 @@ function renderReviewerFindingsSection(findings, huId) {
   ].join("\n");
 }
 
-export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null, domainContext = null, plan = null, projectDir = null, language = "en", provider = null, acceptanceTests = null, adrs = null, specSection = null, reviewerFindings = null, huId = null }) {
+// KJC sesgo-de-stack: Karajan used to default every prompt to JS/TS
+// (vitest, npm install, console.log, JSDoc, httpOnly cookies). When
+// the project is Python / Go / Rust / Ruby, that produced absurd
+// outputs (e.g. installing vitest in a pure-python repo to satisfy a
+// hardcoded `npx vitest run` acceptance test). When we know the
+// stack we tell the coder explicitly so it stops assuming.
+function buildStackSection({ stack, testFramework }) {
+  if (!stack && !testFramework) return null;
+  const lines = ["## Project Stack — match this, don't assume JavaScript"];
+  if (stack?.language) lines.push(`- Language: **${stack.language}**`);
+  if (stack?.frameworks?.length) lines.push(`- Frameworks: ${stack.frameworks.join(", ")}`);
+  if (testFramework?.hasTests && testFramework?.framework) {
+    lines.push(`- Test framework already in use: **${testFramework.framework}** (${testFramework.language || stack?.language || "unknown"}). Use it for new tests; do NOT add a JS test framework on top.`);
+  } else if (stack?.language && stack.language !== "javascript" && stack.language !== "typescript") {
+    lines.push(`- No test framework detected yet. Pick the canonical one for ${stack.language} (e.g. pytest for python, \`go test\` for go, \`cargo test\` for rust, rspec for ruby). Do NOT use vitest / jest / \`npm install\` in a non-JS project.`);
+  }
+  lines.push("");
+  lines.push("If an acceptance_test command on this HU points at a foreign framework (e.g. `npx vitest run` on a python project), REPLACE the command with the equivalent for the project's actual stack and use that to verify your work.");
+  return lines.join("\n");
+}
+
+export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSummary = null, coderRules = null, methodology = "tdd", serenaEnabled = false, rtkAvailable = false, deferredContext = null, productContext = null, domainContext = null, plan = null, projectDir = null, language = "en", provider = null, acceptanceTests = null, adrs = null, specSection = null, reviewerFindings = null, huId = null, stack = null, testFramework = null }) {
   const langInstruction = getLanguageInstruction(language);
   // KJC-BUG-0032 (PR-I): hard rule about file paths. Real bug: a HU
   // titled "Initialize project skeleton: create assistant/ directory…"
@@ -190,10 +211,12 @@ export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSum
     "Keep changes minimal and production-ready.",
     "Follow SOLID principles. Write small, focused functions (< 30 lines).",
     "Make atomic commits: 1 logical change = 1 commit. Keep PRs small and reviewable.",
-    "Security: use httpOnly cookies for auth tokens, validate all input, parameterize queries, never expose secrets.",
-    "No console.log — use a structured logger. No 'any' types — use JSDoc annotations.",
+    "Security: validate all input, parameterize queries, never expose secrets. Use the auth pattern that matches the stack (e.g. httpOnly cookies for web sessions).",
+    "Use the project's standard logger and type system (no console.log when a structured logger exists; use the project's type idiom — TS types, JSDoc, Python type hints, Go interfaces…).",
     SUBPROCESS_CONSTRAINTS
   ];
+  const stackRule = buildStackSection({ stack, testFramework });
+  if (stackRule) sections.push(stackRule);
   if (projectDirRule) sections.push(projectDirRule);
 
   if (serenaEnabled) {
@@ -268,7 +291,7 @@ export async function buildCoderPrompt({ task, reviewerFeedback = null, sonarSum
       "1. Find the relevant file(s) in the project",
       "2. Make the specific code change needed to resolve the issue",
       "3. If tests are missing, write them",
-      "4. If dependencies are needed, install them (npm install)",
+      "4. If dependencies are needed, install them with the project's package manager (npm install / pip install / go get / cargo add — pick the one that matches the stack above)",
       "5. Do NOT skip any issue — all must be resolved"
     );
   }

package/src/roles/coder-role.js

@@ -2,6 +2,8 @@ import { AgentRole } from "./agent-role.js";
 import { buildCoderPrompt } from "../prompts/coder.js";
 import { isHostAgent } from "../utils/agent-detect.js";
 import { HostAgent } from "../agents/host-agent.js";
+import { detectProjectStack } from "../utils/stack-detect.js";
+import { detectTestFramework } from "../utils/project-detect.js";
 
 export class CoderRole extends AgentRole {
   constructor(opts) {
@@ -54,6 +56,16 @@ export class CoderRole extends AgentRole {
   }
 
   async buildPrompt({ task, reviewerFeedback, sonarSummary, deferredContext, acceptanceTests, adrs, specSection, reviewerFindings, huId }) {
+    const projectDir = this.config?.projectDir || null;
+    // KJC sesgo-de-stack: pasar stack/testFramework al prompt para que
+    // el coder no asuma JS/vitest en proyectos Python / Go / Rust /
+    // Ruby. audit-role.js y tester-role.js ya lo hacen así.
+    let stack = null;
+    let testFramework = null;
+    if (projectDir) {
+      try { stack = await detectProjectStack(projectDir); } catch { /* best-effort */ }
+      try { testFramework = await detectTestFramework(projectDir); } catch { /* best-effort */ }
+    }
     const prompt = await buildCoderPrompt({
       task, reviewerFeedback, sonarSummary, deferredContext, acceptanceTests,
       adrs, specSection, reviewerFindings, huId,
@@ -63,7 +75,8 @@ export class CoderRole extends AgentRole {
       rtkAvailable: Boolean(this.config?.rtk?.available),
       productContext: this.config?.productContext || null,
       domainContext: this.config?.domainContext || null,
-      projectDir: this.config?.projectDir || null,
+      projectDir,
+      stack, testFramework,
       provider: this._resolvedProvider || (typeof this.resolveProvider === "function" ? this.resolveProvider() : null)
     });
     return { prompt };

package/src/utils/garbage-collector.js

@@ -30,7 +30,7 @@
 
 import fs from "node:fs/promises";
 import path from "node:path";
-import os from "node:os";
+import { resolveHome } from "./paths.js";
 
 const FINAL_PLAN_STATUSES = new Set([
   // Terminal plan states the user explicitly opted into — retention applies.
@@ -39,13 +39,15 @@ const FINAL_PLAN_STATUSES = new Set([
 const KNOWN_PLAN_STATUSES = new Set([...FINAL_PLAN_STATUSES, "draft", "running"]);
 const FINAL_SESSION_STATUSES = new Set(["approved", "failed", "stopped", "rejected", "completed"]);
 
-function getKjHome() {
-  return process.env.KJ_HOME || path.join(os.homedir(), ".kj");
-}
-
+// Post-PR-3 of KJC-PCS-0047 both helpers point at the canonical
+// `~/.karajan/` root. `getKjHome` is kept as an alias of
+// `getKarajanHome` so legacy callers inside the file continue to
+// compile during the consolidation; both names resolve to the same
+// directory now that the layout is unified.
 function getKarajanHome() {
-  return process.env.KARAJAN_HOME || path.join(os.homedir(), ".karajan");
+  return resolveHome({ defaultSegment: ".karajan" });
 }
+const getKjHome = getKarajanHome;
 
 const DAY_MS = 24 * 60 * 60 * 1000;
 

package/src/utils/home-migration.js

@@ -0,0 +1,87 @@
+// One-shot ~/.kj/ → ~/.karajan/ home consolidation (PR 2 of KJC-PCS-0047).
+// Idempotent via `<target>/.kj-migrated.json`. Tarball backup under
+// `<target>/backup/`. `plans/`, `standby/`, `worktrees/` are moved
+// wholesale; `runs/` is merged with `.karajan/` winning on conflict.
+// Cross-device safe. Non-fatal: CLI bootstrap wraps in try/catch.
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import os from "node:os";
+import { execa } from "execa";
+
+const MARKER = ".kj-migrated.json";
+const MOVE_DIRS = ["plans", "standby", "worktrees"];
+
+async function readdirOrNull(dir) {
+  try { return await fs.readdir(dir); } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+async function moveChildren(src, dst, { mergeMode = false } = {}) {
+  const children = await readdirOrNull(src);
+  if (!children?.length) return 0;
+  await fs.mkdir(dst, { recursive: true });
+  let n = 0;
+  for (const c of children) {
+    const dstChild = path.join(dst, c);
+    if (mergeMode) {
+      try { await fs.access(dstChild); continue; } catch { /* no conflict */ }
+    }
+    const srcChild = path.join(src, c);
+    try { await fs.rename(srcChild, dstChild); } catch (err) {
+      if (err.code !== "EXDEV") throw err;
+      await fs.cp(srcChild, dstChild, { recursive: true });
+      await fs.rm(srcChild, { recursive: true, force: true });
+    }
+    n += 1;
+  }
+  await fs.rm(src, { recursive: true, force: true }).catch(() => {});
+  return n;
+}
+
+export async function migrateKjToKarajan({ dryRun = false, force = false } = {}) {
+  // VITEST guard — tests setting KJ_HOME would otherwise migrate against
+  // the developer's real HOME. Migrator's own tests pass `force: true`.
+  if (process.env.VITEST && !force) return { migrated: false, reason: "vitest-skip" };
+
+  const sourceDir = process.env.KJ_HOME || path.join(os.homedir(), ".kj");
+  const targetDir = process.env.KARAJAN_HOME || path.join(os.homedir(), ".karajan");
+
+  if (path.resolve(sourceDir) === path.resolve(targetDir)) {
+    return { migrated: false, reason: "same-path" };
+  }
+  const entries = await readdirOrNull(sourceDir);
+  if (!entries) return { migrated: false, reason: "source-missing" };
+  if (entries.length === 0) return { migrated: false, reason: "source-empty" };
+
+  await fs.mkdir(targetDir, { recursive: true });
+  const markerPath = path.join(targetDir, MARKER);
+  try { await fs.access(markerPath); return { migrated: false, reason: "already-migrated" }; }
+  catch { /* not present — proceed */ }
+
+  if (dryRun) return { migrated: false, reason: "dry-run", sourceDir, targetDir };
+
+  const backupDir = path.join(targetDir, "backup");
+  await fs.mkdir(backupDir, { recursive: true });
+  const ts = new Date().toISOString().replaceAll(/[:.]/g, "-");
+  const backupPath = path.join(backupDir, `kj-pre-migration-${ts}.tar.gz`);
+  await execa("tar", ["-czf", backupPath, "-C", path.dirname(sourceDir), path.basename(sourceDir)]);
+
+  const counts = {};
+  for (const sub of MOVE_DIRS) {
+    counts[sub] = await moveChildren(path.join(sourceDir, sub), path.join(targetDir, sub));
+  }
+  counts.runs = await moveChildren(path.join(sourceDir, "runs"), path.join(targetDir, "runs"), { mergeMode: true });
+
+  const marker = { version: 1, migrated_at: new Date().toISOString(), items_moved: counts, backup_path: backupPath, source_dir: sourceDir, target_dir: targetDir };
+  await fs.writeFile(markerPath, JSON.stringify(marker, null, 2));
+
+  const summary = Object.entries(counts).filter(([, n]) => n > 0).map(([k, n]) => `${n} ${k}`).join(" + ");
+  if (summary) {
+    // eslint-disable-next-line no-console
+    console.warn(`\x1b[33m[warn]\x1b[0m Migrated ${summary} from ${sourceDir} to ${targetDir} (backup: ${backupPath})`);
+  }
+  return { migrated: true, counts, backupPath, marker };
+}

package/src/utils/paths.js

@@ -1,32 +1,85 @@
 import os from "node:os";
 import path from "node:path";
 
-// Per-process tmp dir for VITEST runs that forget to set KJ_HOME. Same
-// rationale as src/plan/plan-store.js — without this, tests that use
-// real session/board paths leak files into the developer's real
-// `~/.karajan/` and pollute the HU Board's SQLite DB. Memoised so
-// every helper in the same process agrees on the path. The trailing
-// segment is `.karajan` to keep semantic parity with non-VITEST
-// defaults (existing tests assert paths contain ".karajan/...").
-let _vitestKarajanHome = null;
-function vitestTmpKarajanHome() {
-  if (_vitestKarajanHome) return _vitestKarajanHome;
-  _vitestKarajanHome = path.join(
+// Per-process vitest root. We memoise the *root* (not the suffixed
+// `.karajan` / `.kj` path) so callers with different legacy defaults
+// — plan-store wants `.kj`, db.js wants `.karajan` — can share one
+// random tmp prefix per test run without colliding.
+let _vitestRoot = null;
+function vitestRoot() {
+  if (_vitestRoot) return _vitestRoot;
+  _vitestRoot = path.join(
     os.tmpdir(),
-    `karajan-vitest-${process.pid}-${Math.random().toString(36).slice(2, 10)}`,
-    ".karajan"
+    `karajan-vitest-${process.pid}-${Math.random().toString(36).slice(2, 10)}`
   );
-  return _vitestKarajanHome;
+  return _vitestRoot;
 }
 
-export function getKarajanHome() {
+function vitestTmpHome(defaultSegment) {
+  return path.join(vitestRoot(), defaultSegment);
+}
+
+// One-shot warning so users with KJ_HOME set in their shell rcfile do
+// not get spammed once per `kj` invocation. Reset across processes,
+// which is the granularity that matters for a humans-reading-stderr
+// audience.
+let _kjHomeWarned = false;
+function emitKjHomeDeprecationWarning() {
+  if (_kjHomeWarned) return;
+  _kjHomeWarned = true;
+  // eslint-disable-next-line no-console
+  console.warn(
+    "\x1b[33m[warn]\x1b[0m KJ_HOME is deprecated, rename to KARAJAN_HOME (KJ_HOME will be removed in a future release)"
+  );
+}
+
+/**
+ * Unified resolver for Karajan's HOME-level storage root. Used by every
+ * helper that previously rolled its own `getKjHome()` with subtly
+ * different defaults and VITEST handling.
+ *
+ * Precedence (highest first):
+ *   1. KARAJAN_HOME env var — explicit, no warning
+ *   2. KJ_HOME env var      — explicit, prints deprecation warning once
+ *   3. VITEST tmp dir       — auto-isolation under `os.tmpdir()/karajan-vitest-<pid>-<rand>/<defaultSegment>`
+ *   4. `~/<defaultSegment>` — production default
+ *
+ * Callers pass `defaultSegment` so we can preserve `.kj` for legacy
+ * paths (plan-store, standby-store) and `.karajan` for the canonical
+ * root, until PR 3 unifies the defaults too.
+ *
+ * @param {object} [options]
+ * @param {string} [options.defaultSegment=".karajan"]  HOME subdir name
+ * @returns {string} absolute path
+ */
+export function resolveHome({ defaultSegment = ".karajan" } = {}) {
+  if (process.env.KARAJAN_HOME) {
+    return path.resolve(process.env.KARAJAN_HOME);
+  }
   if (process.env.KJ_HOME) {
+    emitKjHomeDeprecationWarning();
     return path.resolve(process.env.KJ_HOME);
   }
   if (process.env.VITEST) {
-    return vitestTmpKarajanHome();
+    return vitestTmpHome(defaultSegment);
   }
-  return path.join(os.homedir(), ".karajan");
+  return path.join(os.homedir(), defaultSegment);
+}
+
+/**
+ * Canonical Karajan home (`~/.karajan` by default). Every helper that
+ * used to roll its own `getKjHome()` now goes through this one — see
+ * KJC-PCS-0047 PR 3 for the consolidation.
+ */
+export function getKarajanHome() {
+  return resolveHome({ defaultSegment: ".karajan" });
+}
+
+// Test-only export. Tests that depend on observing the deprecation
+// warning being emitted exactly once need to reset the latch between
+// cases.
+export function __resetKjHomeWarningForTests() {
+  _kjHomeWarned = false;
 }
 
 export function getSessionRoot() {