karajan-code 1.38.1 → 1.39.0

package/README.md

@@ -82,7 +82,7 @@ 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 20 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 21 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.
 
@@ -154,7 +154,7 @@ kj-tail --help           # Full options
 
 ┌─ Terminal 2: kj-tail ────────────────────────────────────────────────────────┐
 │                                                                              │
-│  kj-tail v1.38.0 — .kj/run.log                                              │
+│  kj-tail v1.38.1 — .kj/run.log                                              │
 │                                                                              │
 │  ├─ 📋 Triage: medium (sw) — enabling researcher, architect, planner         │
 │  ├─ ⚙️ Preflight passed — all checks OK                                     │
@@ -233,7 +233,7 @@ hu-reviewer? → triage → discover? → architect? → planner? → coder →
 
 Mix and match. Use Claude as coder and Codex as reviewer. Karajan auto-detects installed agents during `kj init`.
 
-## MCP server (20 tools)
+## MCP server (21 tools)
 
 After `npm install -g karajan-code`, the MCP server auto-registers in Claude and Codex. Manual config if needed:
 
@@ -245,7 +245,7 @@ After `npm install -g karajan-code`, the MCP server auto-registers in Claude and
 # command = "karajan-mcp"
 ```
 
-**20 tools** available: `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`.
+**21 tools** available: `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`.
 
 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)).
 
@@ -267,7 +267,7 @@ Use `kj roles show <role>` to inspect any template.
 
 Karajan auto-detects and auto-configures everything it can:
 
-- **TDD**: Detects test framework (vitest, jest, mocha) → auto-enables TDD
+- **TDD**: Detects test framework for 12 languages (vitest, jest, JUnit, pytest, go test, cargo test, and more). Auto-enables TDD for code tasks, skips for doc/infra
 - **Bootstrap gate**: Validates all prerequisites (git repo, remote, config, agents, SonarQube) before any tool runs. Fails hard with actionable fix instructions, never silently degrades
 - **Injection guard**: Scans diffs for prompt injection before AI review. Detects directive overrides, invisible Unicode, oversized comment payloads. Also runs as a GitHub Action on every PR
 - **SonarQube**: Auto-starts Docker container, generates config if missing
@@ -299,7 +299,7 @@ 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 2093 tests with Vitest
+npm test              # Run 2142 tests with Vitest
 npm run validate      # Lint + test
 ```
 

package/docs/README.es.md

@@ -1,151 +1,27 @@
 <p align="center">
-<<<<<<< HEAD
-  <img src="karajan-code-logo-small.png" alt="Karajan Code" width="200">
-=======
   <img src="karajan-code-logo-small.png" alt="Karajan Code" width="180">
->>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
 </p>
 
 <h1 align="center">Karajan Code</h1>
 
 <p align="center">
-<<<<<<< HEAD
-  Orquestador local multi-agente con TDD, SonarQube y revision de codigo automatizada.
-=======
   Orquestador local multi-agente. TDD-first, basado en MCP, JavaScript vanilla.
->>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
 </p>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/karajan-code"><img src="https://img.shields.io/npm/v/karajan-code.svg" alt="npm version"></a>
-<<<<<<< HEAD
-=======
   <a href="https://www.npmjs.com/package/karajan-code"><img src="https://img.shields.io/npm/dw/karajan-code.svg" alt="npm downloads"></a>
->>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
   <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>
 </p>
 
 <p align="center">
-<<<<<<< HEAD
-  <a href="../README.md">Read in English</a>
-=======
   <a href="../README.md">Read in English</a> · <a href="https://karajancode.com">Documentacion</a>
->>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
 </p>
 
 ---
 
-<<<<<<< HEAD
-## Que es Karajan Code?
-
-Karajan Code (`kj`) orquesta multiples agentes de IA a traves de un pipeline automatizado: generacion de codigo, analisis estatico, revision de codigo, testing y auditorias de seguridad — todo en un solo comando.
-
-En lugar de ejecutar un agente de IA y revisar manualmente su output, `kj` encadena agentes con quality gates. El coder escribe codigo, SonarQube lo analiza, el reviewer lo revisa, y si hay problemas, el coder recibe otra oportunidad. Este bucle se repite hasta que el codigo es aprobado o se alcanza el limite de iteraciones.
-
-**Caracteristicas principales:**
-- **Pipeline multi-agente** con 11 roles configurables
-- **5 agentes de IA soportados**: Claude, Codex, Gemini, Aider, OpenCode
-- **Servidor MCP** con 20 herramientas — usa `kj` desde Claude, Codex o cualquier host compatible con MCP sin salir de tu agente. [Ver configuracion MCP](#servidor-mcp)
-- **Bootstrap obligatorio** — valida prerequisitos del entorno (git, remote, config, agentes, SonarQube) antes de cada ejecucion. Si algo falta, para con instrucciones claras
-- **TDD obligatorio** — se exigen cambios en tests cuando se modifican ficheros fuente
-- **Integracion con SonarQube** — analisis estatico con quality gates (requiere [Docker](#requisitos))
-- **Perfiles de revision** — standard, strict, relaxed, paranoid
-- **Tracking de presupuesto** — monitorizacion de tokens y costes por sesion con `--trace`
-- **Automatizacion Git** — auto-commit, auto-push, auto-PR tras aprobacion
-- **Gestion de sesiones** — pausa/reanudacion con deteccion fail-fast y limpieza automatica de sesiones expiradas
-- **Sistema de plugins** — extiende con agentes custom via `.karajan/plugins/`
-- **Checkpoints interactivos** — en lugar de matar tareas largas, pausa cada 5 minutos con un informe de progreso y te deja decidir: continuar, parar o ajustar el tiempo
-- **Descomposicion de tareas** — triage detecta cuando una tarea debe dividirse y recomienda subtareas; con integracion Planning Game, crea cards vinculadas con bloqueo secuencial
-- **Retry con backoff** — recuperacion automatica ante errores transitorios de API (429, 5xx) con backoff exponencial y jitter
-- **Pipeline stage tracker** — vista de progreso acumulativo durante `kj_run` mostrando que stages estan completadas, en ejecucion o pendientes — tanto en CLI como via eventos MCP para renderizado en tiempo real en el host
-- **Guardarrailes de observabilidad del planner** — telemetria continua de heartbeat/stall, proteccion configurable por silencio maximo (`session.max_agent_silence_minutes`) y limite duro de ejecucion (`session.max_planner_minutes`) para evitar bloqueos prolongados en `kj_plan`/planner
-- **Standby por rate-limit** — cuando un agente alcanza limites de uso, Karajan parsea el tiempo de espera, espera con backoff exponencial y reanuda automaticamente en vez de fallar
-- **Preflight handshake** — `kj_preflight` requiere confirmacion humana de la configuracion de agentes antes de ejecutar, previniendo que la IA cambie asignaciones silenciosamente
-- **Config de 3 niveles** — sesion > proyecto > global con scoping de `kj_agents`
-- **Mediacion inteligente del reviewer** — el scope filter difiere automaticamente issues del reviewer fuera de scope (ficheros no presentes en el diff) como deuda tecnica rastreada en vez de bloquear; Solomon media reviews estancados; el contexto diferido se inyecta en el prompt del coder
-- **Integracion con Planning Game** — combina opcionalmente con [Planning Game](https://github.com/AgenteIA-Geniova/planning-game) para gestion agil de proyectos (tareas, sprints, estimacion) — como Jira, pero open-source y nativo XP
-
-> **Mejor con MCP** — Karajan Code esta disenado para usarse como servidor MCP dentro de tu agente de IA (Claude, Codex, etc.). El agente envia tareas a `kj_run`, recibe notificaciones de progreso en tiempo real, y obtiene resultados estructurados — sin copiar y pegar.
-
-## Requisitos
-
-- **Node.js** >= 18
-- **Docker** — necesario para el analisis estatico con SonarQube. Si no tienes Docker o no necesitas SonarQube, desactivalo con `--no-sonar` o `sonarqube.enabled: false` en la config
-- Al menos un agente de IA instalado: Claude, Codex, Gemini o Aider
-
-## Pipeline
-
-```
-triage? ─> researcher? ─> planner? ─> coder ─> refactorer? ─> sonar? ─> reviewer ─> tester? ─> security? ─> commiter?
-```
-
-| Rol | Descripcion | Por defecto |
-|-----|-------------|-------------|
-| **triage** | Director de pipeline — analiza la complejidad y activa roles dinamicamente | **On** |
-| **researcher** | Investiga el contexto del codebase antes de planificar | Off |
-| **planner** | Genera planes de implementacion estructurados | Off |
-| **coder** | Escribe codigo y tests siguiendo metodologia TDD | **Siempre activo** |
-| **refactorer** | Mejora la claridad del codigo sin cambiar comportamiento | Off |
-| **sonar** | Ejecuta analisis estatico SonarQube y quality gates | On (si configurado) |
-| **reviewer** | Revision de codigo con perfiles de exigencia configurables | **Siempre activo** |
-| **tester** | Quality gate de tests y verificacion de cobertura | **On** |
-| **security** | Auditoria de seguridad OWASP | **On** |
-| **solomon** | Supervisor de sesion — monitoriza salud de iteraciones con 5 reglas (incl. reviewer overreach), media reviews estancados, escala ante anomalias | **On** |
-| **commiter** | Automatizacion de git commit, push y PR tras aprobacion | Off |
-
-Los roles marcados con `?` son opcionales y se pueden activar por ejecucion o via config.
-
-## Instalacion
-
-### Desde npm (recomendado)
-
-```bash
-npm install -g karajan-code
-kj init
-```
-
-### Desde codigo fuente
-
-```bash
-git clone https://github.com/manufosela/karajan-code.git
-cd karajan-code
-./scripts/install.sh
-```
-
-### Setup no interactivo (CI/automatizacion)
-
-```bash
-./scripts/install.sh \
-  --non-interactive \
-  --kj-home /ruta/a/.karajan \
-  --sonar-host http://localhost:9000 \
-  --sonar-token "$KJ_SONAR_TOKEN" \
-  --coder claude \
-  --reviewer codex \
-  --run-doctor true
-```
-
-### Setup multi-instancia
-
-Guias completas: [`docs/multi-instance.md`](multi-instance.md) | [`docs/install-two-instances.md`](install-two-instances.md)
-
-```bash
-./scripts/setup-multi-instance.sh
-```
-
-## Agentes soportados
-
-| Agente | CLI | Instalacion |
-|--------|-----|-------------|
-| **Claude** | `claude` | `npm install -g @anthropic-ai/claude-code` |
-| **Codex** | `codex` | `npm install -g @openai/codex` |
-| **Gemini** | `gemini` | Ver [Gemini CLI docs](https://github.com/google-gemini/gemini-cli) |
-| **Aider** | `aider` | `pipx install aider-chat` (o `pip3 install aider-chat`) |
-
-`kj init` auto-detecta los agentes instalados. Si solo hay uno disponible, se asigna a todos los roles automaticamente.
-=======
 Tu describes lo que quieres construir. Karajan orquesta multiples agentes de IA para planificarlo, implementarlo, testearlo, revisarlo con SonarQube e iterar. Sin que tengas que supervisar cada paso.
 
 ## Que es Karajan?
@@ -162,6 +38,7 @@ Claude Code es excelente. Usalo para codificacion interactiva basada en sesiones
 
 Usa Karajan cuando quieras:
 
+- **Un pipeline repetible y documentado** que corre igual cada vez
 - **TDD por defecto.** Los tests se escriben antes de la implementacion, no despues
 - **Integracion con SonarQube.** Quality gates como parte del flujo, no como algo secundario
 - **Solomon como jefe del pipeline.** Cada rechazo del reviewer es evaluado por un supervisor que decide si es valido o solo ruido de estilo
@@ -171,7 +48,7 @@ Usa Karajan cuando quieras:
 - **Local-first.** Tu codigo, tus claves, tu maquina. Ningun dato sale salvo que tu lo digas
 - **Zero costes de API.** Karajan usa CLIs de agentes de IA (Claude Code, Codex, Gemini CLI), no APIs. Pagas tu suscripcion existente (Claude Pro, ChatGPT Plus), no tarifas por token
 
-Si Claude Code es un programador de pares inteligente, Karajan es el pipeline CI/CD para desarrollo asistido por IA. Funcionan genial juntos: Karajan esta disenado para usarse como servidor MCP dentro de Claude Code.
+Si Claude Code es un programador de pares inteligente, Karajan es el pipeline CI/CD para desarrollo asistido por IA. Funcionan genial juntos: Karajan esta diseñado para usarse como servidor MCP dentro de Claude Code.
 
 ## Instalacion
 
@@ -180,26 +57,11 @@ npm install -g karajan-code
 ```
 
 Eso es todo. No requiere Docker (SonarQube usa Docker, pero Karajan lo gestiona automaticamente). Sin ficheros de configuracion que copiar. `kj init` auto-detecta tus agentes instalados.
->>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
 
 ## Tres formas de usar Karajan
 
 Karajan instala **tres comandos**: `kj`, `kj-tail` y `karajan-mcp`.
 
-<<<<<<< HEAD
-### 1. CLI — Directamente desde terminal
-
-```bash
-kj run "Implementar autenticacion de usuario con JWT"
-kj code "Anadir validacion de inputs al formulario de registro"
-kj review "Revisar los cambios de autenticacion"
-kj plan "Refactorizar la capa de base de datos"
-```
-
-### 2. MCP — Dentro de tu agente de IA
-
-El caso de uso principal. Karajan corre como servidor MCP dentro de Claude Code, Codex o Gemini. El agente tiene acceso a 20 herramientas (`kj_run`, `kj_code`, `kj_review`, etc.) y delega el trabajo pesado al pipeline de Karajan.
-=======
 ### 1. CLI: directamente desde terminal
 
 Ejecuta Karajan directamente. Ves la salida completa del pipeline en tiempo real.
@@ -215,41 +77,26 @@ kj plan "Refactorizar la capa de base de datos"                     # Planificar
 ### 2. MCP: dentro de tu agente de IA
 
 Este es el caso de uso principal. Karajan corre como servidor MCP dentro de Claude Code, Codex o Gemini. Le pides algo a tu agente de IA y el delega el trabajo pesado al pipeline de Karajan.
->>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
 
 ```
 Tu → Claude Code → kj_run (via MCP) → triage → coder → sonar → reviewer → tester → security
 ```
 
-<<<<<<< HEAD
-**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.
-
-### 3. kj-tail — Monitorizar desde otro terminal
-
-**La herramienta companera.** Abre un segundo terminal en el **mismo directorio del proyecto** donde esta trabajando tu agente de IA:
-=======
-El servidor MCP se auto-registra durante `npm install`. Tu agente de IA ve 20 herramientas (`kj_run`, `kj_code`, `kj_review`, etc.) y las usa segun necesite.
+El servidor MCP se auto-registra durante `npm install`. Tu agente de IA ve 21 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.
 
 ### 3. kj-tail: monitorizar desde otro terminal
 
 **La herramienta compañera.** Abre un segundo terminal en el **mismo directorio del proyecto** donde esta trabajando tu agente de IA:
->>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
 
 ```bash
 kj-tail
 ```
 
-<<<<<<< HEAD
-Veras la salida del pipeline en vivo — etapas, resultados, iteraciones, errores — tal como ocurren.
-
-```bash
-=======
 Veras la salida del pipeline en vivo (etapas, resultados, iteraciones, errores) tal como ocurren. La misma vista que ejecutar `kj run` directamente.
 
 ```
->>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
 kj-tail                  # Seguir pipeline en tiempo real (por defecto)
 kj-tail -v               # Verbose: incluir heartbeats de agente y presupuesto
 kj-tail -t               # Mostrar timestamps
@@ -260,172 +107,6 @@ kj-tail --help           # Todas las opciones
 
 > **Importante**: `kj-tail` debe ejecutarse desde el mismo directorio donde el agente de IA esta trabajando. Lee `<proyecto>/.kj/run.log`, que se crea cuando Karajan arranca un pipeline via MCP.
 
-**Flujo tipico:**
-
-```
-┌──────────────────────────┐    ┌──────────────────────────┐
-│  Terminal 1               │    │  Terminal 2               │
-│                           │    │                           │
-│  $ claude                 │    │  $ kj-tail                │
-│  > implementa la          │    │                           │
-│    siguiente tarea        │    │  ├─ 📋 Triage: medium     │
-│    prioritaria            │    │  ├─ 🔬 Researcher ✅      │
-│                           │    │  ├─ 🧠 Planner ✅         │
-│  (Claude llama a kj_run   │    │  ├─ 🔨 Coder ✅           │
-<<<<<<< HEAD
-│   via MCP — solo ves      │    │  ├─ 🔍 Sonar: OK         │
-=======
-│   via MCP, solo ves       │    │  ├─ 🔍 Sonar: OK         │
->>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
-│   el resultado final)     │    │  ├─ 👁️ Reviewer ❌        │
-│                           │    │  ├─ ⚖️ Solomon: 2 cond.   │
-│                           │    │  ├─ 🔨 Coder (iter 2) ✅  │
-│                           │    │  ├─ ✅ Review: APPROVED    │
-│                           │    │  ├─ 🧪 Tester: passed     │
-│                           │    │  └─ 🏁 Result: APPROVED   │
-└──────────────────────────┘    └──────────────────────────┘
-```
-
-<<<<<<< HEAD
-**Ejemplo con pipeline completo** — tarea compleja con todos los roles:
-
-```
-┌─ Terminal 1 ─────────────────────────────────────────────────────────────────┐
-│                                                                              │
-│  $ claude                                                                    │
-│                                                                              │
-│  > Construye una API REST para un sistema de reservas. Requisitos:           │
-│  > - Express + TypeScript con validacion Zod en cada endpoint                │
-│  > - Endpoints: POST /bookings, GET /bookings/:id,                           │
-│  >   PATCH /bookings/:id/cancel                                              │
-│  > - Una reserva tiene: id, guestName, roomType (standard|suite|penthouse),  │
-│  >   checkIn, checkOut, status (confirmed|cancelled)                         │
-│  > - Validar: checkOut posterior a checkIn, sin fechas pasadas,              │
-│  >   roomType debe ser un valor valido del enum                              │
-│  > - Cancelar devuelve 409 si ya esta cancelada                              │
-│  > - Usa TDD. Ejecutalo con Karajan con architect y planner activos,         │
-│  >   modo paranoid. Coder claude, reviewer codex.                            │
-│                                                                              │
-│  Claude llama a kj_run via MCP con:                                          │
-│    --enable-architect --enable-researcher --enable-planner --mode paranoid    │
-│                                                                              │
-└──────────────────────────────────────────────────────────────────────────────┘
-
-┌─ Terminal 2: kj-tail ────────────────────────────────────────────────────────┐
-│                                                                              │
-│  kj-tail v1.36.1 — .kj/run.log                                              │
-│                                                                              │
-│  ├─ 📋 Triage: medium (sw) — activando researcher, architect, planner        │
-│  ├─ ⚙️ Preflight passed — all checks OK                                     │
-│  ├─ 🔬 Researcher: 8 ficheros, 3 patrones, 5 restricciones                  │
-│  ├─ 🏗️ Architect: diseno 3 capas (routes → service → validators)            │
-│  ├─ 🧠 Planner: 6 pasos — tests primero, luego rutas, servicio, validadores │
-│  │                                                                           │
-│  ▶ Iteracion 1/5                                                             │
-│  ├─ 🔨 Coder (claude): 3 endpoints + 18 tests                               │
-│  ├─ 📋 TDD: PASS (3 src, 2 test)                                            │
-│  ├─ 🔍 Sonar: Quality gate OK                                               │
-│  ├─ 👁️ Reviewer (codex): REJECTED (2 blocking)                              │
-│  │   "Falta 404 para GET booking inexistente"                                │
-│  │   "Endpoint cancel sin test de idempotencia"                              │
-│  ├─ ⚖️ Solomon: approve_with_conditions (2 condiciones)                     │
-│  │   "Anadir respuesta 404 y test para GET /bookings/:id con id desconocido" │
-│  │   "Anadir test: cancelar reserva ya cancelada devuelve 409, no 500"       │
-│  │                                                                           │
-│  ▶ Iteracion 2/5                                                             │
-│  ├─ 🔨 Coder (claude): corregido — 22 tests                                 │
-│  ├─ 📋 TDD: PASS                                                            │
-│  ├─ 🔍 Sonar: OK                                                            │
-│  ├─ 👁️ Reviewer (codex): APPROVED                                           │
-│  ├─ 🧪 Tester: passed — cobertura 94%, 22 tests                             │
-│  ├─ 🔒 Security: passed — 0 criticos, 1 bajo (helmet recomendado)           │
-│  ├─ 📊 Audit: CERTIFIED (3 advertencias)                                    │
-│  │                                                                           │
-│  🏁 Resultado: APPROVED                                                      │
-│     🔬 Investigacion: 8 ficheros, 3 patrones                                 │
-│     🗺 Plan: 6 pasos (tests primero)                                         │
-│     🧪 Cobertura: 94%, 22 tests                                              │
-│     🔒 Seguridad: OK                                                         │
-│     🔍 Sonar: OK                                                             │
-│     💰 Presupuesto: $0.42 (claude: $0.38, codex: $0.04)                      │
-│                                                                              │
-└──────────────────────────────────────────────────────────────────────────────┘
-```
-
-## Comandos CLI
-
-Consulta la [documentacion completa de comandos](../README.md#cli-commands) en el README principal (ingles). Resumen:
-
-| Comando | Descripcion |
-|---------|-------------|
-| `kj init` | Wizard interactivo de configuracion |
-| `kj run <task>` | Pipeline completo: coder → sonar → reviewer |
-| `kj code <task>` | Solo coder (sin revision) |
-| `kj review <task>` | Solo reviewer (sobre diff actual) |
-| `kj plan <task>` | Generar plan de implementacion |
-| `kj scan` | Ejecutar analisis SonarQube |
-| `kj doctor` | Verificar entorno (git, Docker, agentes, SonarQube) |
-| `kj config` | Mostrar configuracion actual |
-| `kj report` | Informes de sesion con tracking de presupuesto |
-| `kj resume <id>` | Reanudar sesion pausada |
-| `kj roles` | Inspeccionar roles y templates del pipeline |
-| `kj sonar` | Gestionar contenedor Docker de SonarQube |
-
-## Servidor MCP
-
-Karajan Code expone un servidor MCP para integracion con cualquier host compatible (Claude, Codex, agentes custom).
-
-Tras `npm install -g karajan-code`, el servidor MCP se auto-registra en las configs de Claude y Codex. Config manual:
-
-```json
-{
-  "mcpServers": {
-    "karajan-mcp": {
-      "command": "karajan-mcp"
-    }
-  }
-}
-```
-
-### Herramientas MCP
-
-| Herramienta | Descripcion |
-|-------------|-------------|
-| `kj_init` | Inicializar config y SonarQube |
-| `kj_doctor` | Verificar dependencias del sistema |
-| `kj_config` | Mostrar configuracion |
-| `kj_scan` | Ejecutar analisis SonarQube |
-| `kj_run` | Ejecutar pipeline completo (con notificaciones de progreso en tiempo real) |
-| `kj_resume` | Reanudar sesion pausada |
-| `kj_report` | Leer informes de sesion (soporta `--trace`) |
-| `kj_roles` | Listar roles o mostrar templates |
-| `kj_code` | Modo solo coder |
-| `kj_review` | Modo solo reviewer |
-| `kj_plan` | Generar plan de implementacion con telemetria heartbeat/stall y diagnostico mas claro |
-
-### MCPs complementarios recomendados
-
-Karajan Code funciona perfectamente solo, pero combinarlo con estos servidores MCP le da a tu agente un entorno de desarrollo completo:
-
-| MCP | Para que | Caso de uso |
-|-----|----------|-------------|
-| [**Planning Game MCP**](https://github.com/AgenteIA-Geniova/planning-game-mcp) | Puente MCP para [Planning Game](https://github.com/AgenteIA-Geniova/planning-game), gestor agil open-source (tareas, sprints, estimacion, XP). Solo necesario si usas Planning Game | `kj_run` con `--pg-task` obtiene contexto completo de la tarea y actualiza el estado al completar |
-| [**GitHub MCP**](https://github.com/modelcontextprotocol/servers/tree/main/src/github) | Crear PRs, gestionar issues, leer repos desde el agente | Combinar con `--auto-push` para flujo completo: codigo → revision → push → PR |
-| [**Serena**](https://github.com/oramasearch/serena) | Navegacion a nivel de simbolo (find references, go-to-definition) para proyectos JS/TS | Activar con `--enable-serena` para inyectar contexto de simbolos en prompts de coder/reviewer |
-| [**Chrome DevTools MCP**](https://github.com/anthropics/anthropic-quickstarts/tree/main/chrome-devtools-mcp) | Automatizacion de navegador, screenshots, inspeccion de consola/red | Verificar cambios de UI visualmente tras modificar codigo frontend |
-
-## Templates de roles
-
-Cada rol tiene un template `.md` con instrucciones que el agente de IA sigue. Los templates se resuelven en orden de prioridad:
-
-1. **Override de proyecto**: `.karajan/roles/<rol>.md` (en la raiz del proyecto)
-2. **Override de usuario**: `$KJ_HOME/roles/<rol>.md`
-3. **Built-in**: `templates/roles/<rol>.md` (incluido en el paquete)
-
-Usa `kj roles show <rol>` para inspeccionar cualquier template. Crea un override de proyecto para personalizar el comportamiento por proyecto.
-
-**Variantes de revision**: `reviewer-strict`, `reviewer-relaxed`, `reviewer-paranoid` — seleccionables via flag `--mode` o config `review_mode`.
-=======
 [**Ver la demo completa del pipeline**](https://karajancode.com#demo): triage, arquitectura, TDD, SonarQube, code review, arbitraje de Solomon, auditoria de seguridad.
 
 ## El pipeline
@@ -441,7 +122,7 @@ hu-reviewer? → triage → discover? → architect? → planner? → coder →
 | **hu-reviewer** | Certifica historias de usuario antes de codificar (6 dimensiones, 7 antipatrones) | Auto (media/compleja) |
 | **triage** | Clasifica complejidad, activa roles, auto-simplifica para tareas triviales | **On** |
 | **discover** | Detecta huecos en requisitos (Mom Test, Wendel, JTBD) | Off |
-| **architect** | Disena la arquitectura de la solucion antes de planificar | Off |
+| **architect** | Diseña la arquitectura de la solucion antes de planificar | Off |
 | **planner** | Genera planes de implementacion estructurados | Off |
 | **coder** | Escribe codigo y tests siguiendo metodologia TDD | **Siempre on** |
 | **refactorer** | Mejora la claridad del codigo sin cambiar comportamiento | Off |
@@ -466,19 +147,19 @@ hu-reviewer? → triage → discover? → architect? → planner? → coder →
 
 Mezcla y combina. Usa Claude como coder y Codex como reviewer. Karajan auto-detecta agentes instalados durante `kj init`.
 
-## Servidor MCP (20 herramientas)
+## Servidor MCP (21 herramientas)
 
 Tras `npm install -g karajan-code`, el servidor MCP se auto-registra en Claude y Codex. Config manual si es necesario:
 
 ```bash
-# Claude: anadir a ~/.claude.json → "mcpServers":
+# Claude: añadir a ~/.claude.json → "mcpServers":
 # { "karajan-mcp": { "command": "karajan-mcp" } }
 
-# Codex: anadir a ~/.codex/config.toml → [mcp_servers."karajan-mcp"]
+# Codex: añadir a ~/.codex/config.toml → [mcp_servers."karajan-mcp"]
 # command = "karajan-mcp"
 ```
 
-**20 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`.
+**21 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`.
 
 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)).
 
@@ -500,7 +181,7 @@ Usa `kj roles show <rol>` para inspeccionar cualquier template.
 
 Karajan auto-detecta y auto-configura todo lo que puede:
 
-- **TDD**: Detecta framework de tests (vitest, jest, mocha) y auto-activa TDD
+- **TDD**: Detecta framework de tests para 12 lenguajes (vitest, jest, JUnit, pytest, go test, cargo test, y mas). Auto-activa TDD para tareas de codigo, lo salta para doc/infra
 - **Bootstrap gate**: Valida todos los prerequisitos (repo git, remote, config, agentes, SonarQube) antes de ejecutar. Falla con instrucciones claras, nunca degrada silenciosamente
 - **Injection guard**: Escanea diffs en busca de prompt injection antes del review de IA. Detecta directivas de override, Unicode invisible, payloads en comentarios sobredimensionados. Tambien como GitHub Action en cada PR
 - **SonarQube**: Auto-arranca contenedor Docker, genera config si falta
@@ -511,11 +192,11 @@ Karajan auto-detecta y auto-configura todo lo que puede:
 
 Sin configuracion por proyecto requerida. Si quieres personalizar, la config se apila: sesion > proyecto > global.
 
-## Por qué JavaScript vanilla?
+## Por que JavaScript vanilla?
 
-No es nostalgia ni cabezonería. Es que llevo usando JavaScript desde 1997, cuando Brendan Eich lo creó en una semana y nos cambió la vida a los que hacíamos webs. Conozco sus tripas, sus bugs, sus rarezas. Y sé que quien conoce JS de verdad convierte esos bugs en features. TypeScript existe para que developers acostumbrados a lenguajes fuertemente tipados no entren en pánico al ver JS. Respeto eso. Pero yo no lo necesito. Los tests son mi seguridad de tipos. JSDoc y un buen IDE son mi intellisense. Y no tener un compilador entre el código y yo es lo que me permite moverme a 57 releases en 45 días sin miedo.
+No es nostalgia ni cabezoneria. Es que llevo usando JavaScript desde 1997, cuando Brendan Eich lo creo en una semana y nos cambio la vida a los que haciamos webs. Conozco sus tripas, sus bugs, sus rarezas. Y se que quien conoce JS de verdad convierte esos bugs en features. TypeScript existe para que developers acostumbrados a lenguajes fuertemente tipados no entren en panico al ver JS. Respeto eso. Pero yo no lo necesito. Los tests son mi seguridad de tipos. JSDoc y un buen IDE son mi intellisense. Y no tener un compilador entre el codigo y yo es lo que me permite moverme a 57 releases en 45 dias sin miedo.
 
-[Por qué JavaScript vanilla: la versión larga](why-vanilla-js.md)
+[Por que JavaScript vanilla: la version larga](why-vanilla-js.md)
 
 ## Compañeros recomendados
 
@@ -525,7 +206,6 @@ No es nostalgia ni cabezonería. Es que llevo usando JavaScript desde 1997, cuan
 | [**Planning Game MCP**](https://github.com/AgenteIA-Geniova/planning-game-mcp) | Gestion agil de proyectos (tareas, sprints, estimacion), nativo XP |
 | [**GitHub MCP**](https://github.com/modelcontextprotocol/servers/tree/main/src/github) | Crear PRs, gestionar issues directamente desde el agente |
 | [**Chrome DevTools MCP**](https://github.com/anthropics/anthropic-quickstarts/tree/main/chrome-devtools-mcp) | Verificar cambios de UI visualmente tras modificar frontend |
->>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
 
 ## Contribuir
 
@@ -533,32 +213,15 @@ No es nostalgia ni cabezonería. Es que llevo usando JavaScript desde 1997, cuan
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-<<<<<<< HEAD
-npm test              # Ejecutar 1040+ tests con Vitest
-npm run test:watch    # Modo watch
-npm run validate      # Lint + test
-```
-
-- Tests: [Vitest](https://vitest.dev/)
-- Commits: [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `refactor:`, `test:`, `chore:`)
-- PRs: un solo proposito por PR, < 300 lineas cambiadas
-=======
-npm test              # Ejecutar 2093 tests con Vitest
+npm test              # Ejecutar 2142 tests con Vitest
 npm run validate      # Lint + test
 ```
 
 Issues y pull requests bienvenidos. Si algo no funciona como esta documentado, [abre un issue](https://github.com/manufosela/karajan-code/issues). Es la contribucion mas util en esta fase.
->>>>>>> 8792e49efcdc75995e024d81339b100c7b253920
 
 ## Enlaces
 
 - [Web](https://karajancode.com) (tambien [kj-code.com](https://kj-code.com))
-<<<<<<< HEAD
-- [Changelog](../CHANGELOG.md)
-- [Politica de seguridad](../SECURITY.md)
-- [Licencia (AGPL-3.0)](../LICENSE)
-- [Issues](https://github.com/manufosela/karajan-code/issues)
-=======
 - [Documentacion completa](https://karajancode.com/docs/)
 - [Changelog](../CHANGELOG.md)
 - [Politica de seguridad](../SECURITY.md)
@@ -567,4 +230,3 @@ Issues y pull requests bienvenidos. Si algo no funciona como esta documentado, [
 ---
 
 Construido por [@manufosela](https://github.com/manufosela). Head of Engineering en Geniova Technologies, co-organizador de NodeJS Madrid, autor de [Liderazgo Afectivo](https://www.liderazgoafectivo.com). 90+ paquetes npm publicados.
->>>>>>> 8792e49efcdc75995e024d81339b100c7b253920

package/package.json

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

package/src/cli.js

@@ -25,9 +25,14 @@ import { architectCommand } from "./commands/architect.js";
 import { auditCommand } from "./commands/audit.js";
 import { boardCommand } from "./commands/board.js";
 
+import { printUpdateNotice } from "./utils/update-check.js";
+
 const PKG_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../package.json");
 const PKG_VERSION = JSON.parse(readFileSync(PKG_PATH, "utf8")).version;
 
+// Non-blocking update check (runs in background, prints after command output)
+printUpdateNotice(PKG_VERSION).catch(() => {});
+
 async function withConfig(commandName, flags, fn) {
   const { config } = await loadConfig();
   const merged = applyRunOverrides(config, flags || {});

package/src/guards/output-guard.js

@@ -10,13 +10,23 @@ const DESTRUCTIVE_PATTERNS = [
   { id: "format-disk", pattern: /mkfs\.|fdisk|dd\s+if=/, severity: "critical", message: "Disk format operation detected" },
 ];
 
-// Built-in credential patterns
+// Built-in credential patterns (ALL critical — secrets must NEVER be committed)
 const CREDENTIAL_PATTERNS = [
   { id: "aws-key", pattern: /AKIA[0-9A-Z]{16}/, severity: "critical", message: "AWS access key exposed" },
   { id: "private-key", pattern: /-----BEGIN\s+(RSA\s+)?PRIVATE\s+KEY-----/, severity: "critical", message: "Private key exposed" },
-  { id: "generic-secret", pattern: /(password|secret|token|api_key|apikey)\s*[:=]\s*["'][^"']{8,}["']/i, severity: "warning", message: "Potential secret/credential exposed" },
+  { id: "generic-secret", pattern: /(password|secret|token|api_key|apikey)\s*[:=]\s*["'][^"']{8,}["']/i, severity: "critical", message: "Hardcoded secret detected. Use .env file + process.env instead" },
   { id: "github-token", pattern: /gh[pousr]_[A-Za-z0-9_]{36,}/, severity: "critical", message: "GitHub token exposed" },
   { id: "npm-token", pattern: /npm_[A-Za-z0-9]{36,}/, severity: "critical", message: "npm token exposed" },
+  { id: "openai-key", pattern: /sk-[A-Za-z0-9]{20,}/, severity: "critical", message: "OpenAI API key exposed" },
+  { id: "anthropic-key", pattern: /sk-ant-[A-Za-z0-9_-]{20,}/, severity: "critical", message: "Anthropic API key exposed" },
+  { id: "stripe-key", pattern: /sk_live_[A-Za-z0-9]{20,}/, severity: "critical", message: "Stripe secret key exposed" },
+  { id: "stripe-test", pattern: /sk_test_[A-Za-z0-9]{20,}/, severity: "critical", message: "Stripe test key exposed. Use .env even for test keys" },
+  { id: "google-api-key", pattern: /AIza[A-Za-z0-9_-]{35}/, severity: "critical", message: "Google API key exposed" },
+  { id: "firebase-key", pattern: /"apiKey"\s*:\s*"AIza[A-Za-z0-9_-]{35}"/, severity: "critical", message: "Firebase API key hardcoded. Use .env file" },
+  { id: "slack-token", pattern: /xox[bpors]-[A-Za-z0-9-]{10,}/, severity: "critical", message: "Slack token exposed" },
+  { id: "jwt-secret", pattern: /jwt[_-]?secret\s*[:=]\s*["'][^"']{8,}["']/i, severity: "critical", message: "JWT secret hardcoded. Use .env file" },
+  { id: "database-url", pattern: /(mongodb|postgres|mysql|redis):\/\/[^"'\s]+:[^"'\s]+@/i, severity: "critical", message: "Database URL with credentials exposed. Use .env file" },
+  { id: "hardcoded-key-assignment", pattern: /(?:const|let|var)\s+\w*(?:key|secret|token|password)\w*\s*=\s*["'][A-Za-z0-9_-]{16,}["']/i, severity: "critical", message: "Hardcoded key in variable. Use process.env or .env file" },
 ];
 
 // Default protected files (block if these appear in added/modified lines)

package/src/hu/store.js

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import path from "node:path";
+import { execSync } from "node:child_process";
 import { getKarajanHome } from "../utils/paths.js";
 
 // FUTURE: hu-storage adapter for PG/Trello/etc — currently local files only
@@ -208,3 +209,138 @@ export async function createHistoryRecord(sessionId, { task, result, approved, s
   await fs.writeFile(path.join(dir, "batch.json"), JSON.stringify(batch, null, 2));
   return batch;
 }
+
+/* ── Manual HU management ─────────────────────────────────────────── */
+
+/**
+ * Detect project info from the given directory.
+ * @param {string} cwd - Directory to detect project from.
+ * @returns {{ name: string, remoteUrl: string|null }}
+ */
+export function detectProject(cwd) {
+  const name = path.basename(cwd);
+  let remoteUrl = null;
+  try {
+    remoteUrl = execSync("git remote get-url origin", { cwd, encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+  } catch { /* not a git repo or no remote */ }
+  return { name, remoteUrl };
+}
+
+/**
+ * Derive a project slug from a directory path.
+ * @param {string} projectDir - Absolute path to the project.
+ * @returns {string}
+ */
+function projectSlug(projectDir) {
+  return path.basename(projectDir);
+}
+
+/**
+ * Get the batch file path for a project.
+ * @param {string} projectDir
+ * @returns {string}
+ */
+function projectBatchPath(projectDir) {
+  return path.join(getHuDir(), projectSlug(projectDir), "batch.json");
+}
+
+/**
+ * Load the project batch, or return a fresh empty batch if none exists.
+ * @param {string} projectDir
+ * @returns {Promise<object>}
+ */
+async function loadProjectBatch(projectDir) {
+  const filePath = projectBatchPath(projectDir);
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return {
+      project: projectSlug(projectDir),
+      created_at: new Date().toISOString(),
+      stories: []
+    };
+  }
+}
+
+/**
+ * Save a project batch to disk (auto-creates directory).
+ * @param {string} projectDir
+ * @param {object} batch
+ */
+async function saveProjectBatch(projectDir, batch) {
+  const filePath = projectBatchPath(projectDir);
+  await fs.mkdir(path.dirname(filePath), { recursive: true });
+  batch.updated_at = new Date().toISOString();
+  await fs.writeFile(filePath, JSON.stringify(batch, null, 2));
+}
+
+/**
+ * Create a manual HU (user story) for a project.
+ * Auto-creates the batch file if it doesn't exist.
+ * @param {string} projectDir
+ * @param {{ title: string, description?: string, status?: string, acceptanceCriteria?: string }} data
+ * @returns {Promise<object>} The created HU.
+ */
+export async function createManualHu(projectDir, { title, description, status, acceptanceCriteria }) {
+  if (!title) throw new Error("title is required to create a HU");
+  const batch = await loadProjectBatch(projectDir);
+  const now = new Date().toISOString();
+  const hu = {
+    id: `HU-${Date.now()}-${batch.stories.length}`,
+    title,
+    description: description || "",
+    status: status || HU_STATUS.PENDING,
+    acceptanceCriteria: acceptanceCriteria || "",
+    createdAt: now,
+    updatedAt: now
+  };
+  batch.stories.push(hu);
+  await saveProjectBatch(projectDir, batch);
+  return hu;
+}
+
+/**
+ * List all HUs for a project.
+ * @param {string} projectDir
+ * @returns {Promise<Array<{ id: string, title: string, status: string, createdAt: string }>>}
+ */
+export async function listHus(projectDir) {
+  const batch = await loadProjectBatch(projectDir);
+  return batch.stories.map(s => ({
+    id: s.id,
+    title: s.title,
+    status: s.status,
+    createdAt: s.createdAt
+  }));
+}
+
+/**
+ * Update the status of a specific HU.
+ * @param {string} projectDir
+ * @param {string} huId
+ * @param {string} status
+ * @returns {Promise<object>} The updated HU.
+ */
+export async function updateHuStatus(projectDir, huId, status) {
+  const batch = await loadProjectBatch(projectDir);
+  const hu = batch.stories.find(s => s.id === huId);
+  if (!hu) throw new Error(`HU ${huId} not found`);
+  hu.status = status;
+  hu.updatedAt = new Date().toISOString();
+  await saveProjectBatch(projectDir, batch);
+  return hu;
+}
+
+/**
+ * Get a single HU by id.
+ * @param {string} projectDir
+ * @param {string} huId
+ * @returns {Promise<object>}
+ */
+export async function getHu(projectDir, huId) {
+  const batch = await loadProjectBatch(projectDir);
+  const hu = batch.stories.find(s => s.id === huId);
+  if (!hu) throw new Error(`HU ${huId} not found`);
+  return hu;
+}

package/src/mcp/server-handlers.js

@@ -906,6 +906,44 @@ async function handleAudit(a, server, extra) {
   return handleAuditDirect(a, server, extra);
 }
 
+async function handleHu(a, server) {
+  const action = a.action;
+  if (!action) return failPayload("Missing required field: action");
+
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  const { createManualHu, listHus, getHu, updateHuStatus } = await import("../hu/store.js");
+
+  switch (action) {
+    case "create": {
+      if (!a.title) return failPayload("Missing required field: title (required for create)");
+      const hu = await createManualHu(projectDir, {
+        title: a.title,
+        description: a.description,
+        status: a.status,
+        acceptanceCriteria: a.acceptanceCriteria
+      });
+      return { ok: true, hu };
+    }
+    case "list": {
+      const hus = await listHus(projectDir);
+      return { ok: true, hus };
+    }
+    case "get": {
+      if (!a.huId) return failPayload("Missing required field: huId (required for get)");
+      const hu = await getHu(projectDir, a.huId);
+      return { ok: true, hu };
+    }
+    case "update": {
+      if (!a.huId) return failPayload("Missing required field: huId (required for update)");
+      if (!a.status) return failPayload("Missing required field: status (required for update)");
+      const hu = await updateHuStatus(projectDir, a.huId, a.status);
+      return { ok: true, hu };
+    }
+    default:
+      return failPayload(`Unknown hu action: ${action}`);
+  }
+}
+
 async function handleBoard(a) {
   const action = a.action || "status";
   const { loadConfig: lc } = await import("../config.js");
@@ -947,7 +985,8 @@ const toolHandlers = {
   kj_researcher:  (a, server, extra) => handleResearcher(a, server, extra),
   kj_architect:   (a, server, extra) => handleArchitect(a, server, extra),
   kj_audit:       (a, server, extra) => handleAudit(a, server, extra),
-  kj_board:       (a) => handleBoard(a)
+  kj_board:       (a) => handleBoard(a),
+  kj_hu:          (a, server) => handleHu(a, server)
 };
 
 export async function handleToolCall(name, args, server, extra) {

package/src/mcp/tools.js

@@ -47,7 +47,7 @@ export const tools = [
   {
     name: "kj_run",
     description:
-      "Run full coder -> sonar -> reviewer loop. Sends real-time progress notifications via MCP logging. May return paused state with a question if fail-fast is triggered.",
+      "Run the full Karajan pipeline. IMPORTANT: Pass the user's task description exactly as they wrote it. Do NOT group, split, reorder, or modify tasks yourself. Karajan handles decomposition, role activation, iteration, and quality gates internally. Do NOT override pipeline parameters (enableHuReviewer, mode, methodology) unless the user explicitly requested it. If you have observations about the task, use kj_suggest instead.",
     inputSchema: {
       type: "object",
       required: ["task"],
@@ -182,7 +182,7 @@ export const tools = [
   },
   {
     name: "kj_code",
-    description: "Run coder-only mode",
+    description: "Run coder-only mode. Pass the user's task exactly as described. Do NOT split or reinterpret the task.",
     inputSchema: {
       type: "object",
       required: ["task"],
@@ -197,7 +197,7 @@ export const tools = [
   },
   {
     name: "kj_review",
-    description: "Run reviewer-only mode against current diff",
+    description: "Run reviewer-only mode against current diff. Do NOT filter or pre-process the diff before passing it.",
     inputSchema: {
       type: "object",
       required: ["task"],
@@ -223,7 +223,7 @@ export const tools = [
   },
   {
     name: "kj_plan",
-    description: "Generate implementation plan for a task",
+    description: "Generate implementation plan for a task. Pass the task as the user described it. Karajan's planner decides the approach.",
     inputSchema: {
       type: "object",
       required: ["task"],
@@ -317,5 +317,22 @@ export const tools = [
         port: { type: "number", description: "Port (default: 4000)" }
       }
     }
+  },
+  {
+    name: "kj_hu",
+    description: "Manage user stories (HUs) in the local board",
+    inputSchema: {
+      type: "object",
+      required: ["action"],
+      properties: {
+        action: { type: "string", enum: ["create", "update", "list", "get"], description: "Action to perform" },
+        title: { type: "string", description: "HU title (required for create)" },
+        description: { type: "string", description: "HU description" },
+        acceptanceCriteria: { type: "string", description: "Acceptance criteria" },
+        huId: { type: "string", description: "HU ID (required for update/get)" },
+        status: { type: "string", description: "HU status (for create/update)", enum: ["pending", "coding", "reviewing", "done", "failed", "blocked"] },
+        projectDir: { type: "string", description: "Project directory (defaults to cwd)" }
+      }
+    }
   }
 ];

package/src/orchestrator/iteration-stages.js

@@ -444,15 +444,20 @@ export async function runSonarStage({ config, logger, emitter, eventBase, sessio
   const sonarResult = sonarOutput.result;
 
   if (!sonarResult.gateStatus && sonarResult.error) {
+    const isTokenError = /unable to resolve sonar token/i.test(sonarResult.error);
+    const errorMessage = isTokenError
+      ? "SonarQube is running but no authentication token is configured. Fix: run 'kj init' to configure it, or set KJ_SONAR_TOKEN env var, or add sonarqube.token to ~/.karajan/kj.config.yml."
+      : `Sonar scan failed: ${sonarResult.error}`;
+
     await markSessionStatus(session, "failed");
     emitProgress(
       emitter,
       makeEvent("sonar:end", { ...eventBase, stage: "sonar" }, {
         status: "fail",
-        message: `Sonar scan failed: ${sonarResult.error}`
+        message: errorMessage
       })
     );
-    throw new Error(`Sonar scan failed: ${sonarResult.error}`);
+    throw new Error(errorMessage);
   }
 
   session.last_sonar_summary = sonarOutput.summary;
@@ -680,7 +685,7 @@ async function fetchReviewDiff(session, logger) {
     logger.info(`Reviewer reading PR diff #${session.becaria_pr_number}`);
     return diff;
   }
-  return generateDiff({ baseRef: session.session_start_sha });
+  return generateDiff({ baseRef: session.session_start_sha, stageNewFiles: true });
 }
 
 export async function runReviewerStage({ reviewerRole, config, logger, emitter, eventBase, session, trackBudget, iteration, reviewRules, task, repeatDetector, budgetSummary, askQuestion }) {

package/src/orchestrator/preflight-checks.js

@@ -252,8 +252,8 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
       result.ok = false;
       result.errors.push({
         check: "sonar-auth",
-        message: "SonarQube authentication failed.",
-        fix: "Regenerate the SonarQube token and update it via kj_init or in kj.config.yml under sonarqube.token."
+        message: "SonarQube is running but no authentication token is configured.",
+        fix: "Fix: run 'kj init' to configure it, or set KJ_SONAR_TOKEN env var, or add sonarqube.token to ~/.karajan/kj.config.yml."
       });
       logger.error("Preflight: Sonar auth failed");
     }

package/src/orchestrator/solomon-escalation.js

@@ -2,6 +2,68 @@ import { SolomonRole } from "../roles/solomon-role.js";
 import { addCheckpoint, pauseSession } from "../session-store.js";
 import { emitProgress, makeEvent } from "../utils/events.js";
 
+/**
+ * Build a human-readable escalation message from raw Solomon conflict data.
+ * Replaces the raw JSON dump with structured, plain-text output.
+ *
+ * @param {object} solomonResult - The conflict object passed to escalateToHuman
+ * @param {object} [session]     - Current session (optional, used for extra context)
+ * @returns {string} Formatted message suitable for display to the user
+ */
+export function formatEscalationMessage(solomonResult, session) {
+  const stage = solomonResult?.stage || "unknown";
+  const solomonReason = solomonResult?.solomonReason || null;
+  const history = solomonResult?.history || [];
+
+  const lines = [];
+  lines.push(`--- Conflict: ${stage} ---`);
+  lines.push("");
+
+  // Extract reviewer/agent feedback from history
+  const feedbackEntries = history.filter(entry => entry && typeof entry === "object");
+  if (feedbackEntries.length > 0) {
+    lines.push("Reviewer feedback:");
+    for (const entry of feedbackEntries) {
+      const agent = entry.agent || "unknown";
+      const feedback = entry.feedback || "No feedback provided";
+      // Split multi-line feedback (e.g. "R-1: ...\nR-2: ...") into bullet points
+      const feedbackLines = String(feedback).split("\n").filter(l => l.trim());
+      if (feedbackLines.length === 1) {
+        lines.push(`  [${agent}] ${feedbackLines[0]}`);
+      } else {
+        lines.push(`  [${agent}]`);
+        for (const fl of feedbackLines) {
+          lines.push(`    - ${fl}`);
+        }
+      }
+    }
+    lines.push("");
+  }
+
+  // Solomon's reason (if it tried and failed)
+  if (solomonReason) {
+    lines.push(`Solomon could not resolve the conflict: ${solomonReason}`);
+    lines.push("");
+  }
+
+  // Iteration context
+  const iterationCount = solomonResult?.iterationCount;
+  const maxIterations = solomonResult?.maxIterations;
+  if (iterationCount !== undefined && maxIterations !== undefined) {
+    lines.push(`Iterations: ${iterationCount}/${maxIterations}`);
+    lines.push("");
+  }
+
+  lines.push("Options:");
+  lines.push("  1. Accept coder's work as-is");
+  lines.push("  2. Retry with reviewer's feedback");
+  lines.push("  3. Stop the session");
+  lines.push("");
+  lines.push("How should we proceed?");
+
+  return lines.join("\n");
+}
+
 export async function invokeSolomon({ config, logger, emitter, eventBase, stage, conflict, askQuestion, session, iteration }) {
   const solomonEnabled = Boolean(config.pipeline?.solomon?.enabled);
 
@@ -86,8 +148,7 @@ export async function invokeSolomon({ config, logger, emitter, eventBase, stage,
 }
 
 export async function escalateToHuman({ askQuestion, session, emitter, eventBase, stage, conflict, iteration }) {
-  const reason = conflict?.solomonReason || `${stage} conflict unresolved`;
-  const question = `${stage} conflict requires human intervention: ${reason}\nDetails: ${JSON.stringify(conflict?.history?.slice(-2) || [], null, 2)}\n\nHow should we proceed?`;
+  const question = formatEscalationMessage({ ...conflict, stage }, session);
 
   if (askQuestion) {
     const answer = await askQuestion(question, { iteration, stage });

package/src/review/diff-generator.js

@@ -13,8 +13,12 @@ export async function computeBaseRef({ baseBranch = "main", baseRef = null }) {
   return mergeBase.stdout.trim();
 }
 
-export async function generateDiff({ baseRef }) {
-  const result = await runCommand("git", ["diff", `${baseRef}`]);
+export async function generateDiff({ baseRef, stageNewFiles = false }) {
+  // Stage untracked files so they appear in the diff (coder creates files but doesn't git add)
+  if (stageNewFiles) {
+    await runCommand("git", ["add", "-A"]);
+  }
+  const result = await runCommand("git", ["diff", stageNewFiles ? "--cached" : "", `${baseRef}`].filter(Boolean));
   if (result.exitCode !== 0) {
     throw new Error(`git diff failed: ${result.stderr || result.stdout}`);
   }

package/src/review/tdd-policy.js

@@ -21,15 +21,17 @@ function isSourceFile(file, extensions = []) {
 
 const SKIP_TDD_TASK_TYPES = new Set(["doc", "infra"]);
 
+const DEFAULT_TEST_PATTERNS = ["/tests/", "/__tests__/", ".test.", ".spec.", "/src/test/", "/test/", "Test.java", "Test.kt", "test_", "_test.py", "_test.go", "Test.cs", "_spec.rb", "Test.php", "_test.dart", "Tests.swift"];
+const DEFAULT_SOURCE_EXTENSIONS = [".js", ".jsx", ".ts", ".tsx", ".py", ".go", ".java", ".kt", ".rb", ".php", ".cs", ".rs", ".swift", ".dart"];
+
 export function evaluateTddPolicy(diff, developmentConfig = {}, untrackedFiles = [], taskType = null) {
   if (taskType && SKIP_TDD_TASK_TYPES.has(taskType)) {
     return { ok: true, reason: "tdd_not_applicable_for_task_type", sourceFiles: [], testFiles: [] };
   }
 
   const requireTestChanges = developmentConfig.require_test_changes !== false;
-  const patterns = developmentConfig.test_file_patterns || ["/tests/", "/__tests__/", ".test.", ".spec."];
-  const extensions =
-    developmentConfig.source_file_extensions || [".js", ".jsx", ".ts", ".tsx", ".py", ".go", ".java", ".rb", ".php", ".cs"];
+  const patterns = developmentConfig.test_file_patterns || DEFAULT_TEST_PATTERNS;
+  const extensions = developmentConfig.source_file_extensions || DEFAULT_SOURCE_EXTENSIONS;
 
   const diffFiles = extractChangedFiles(diff);
   const extra = Array.isArray(untrackedFiles) ? untrackedFiles : [];

package/src/sonar/scanner.js

@@ -225,7 +225,7 @@ export async function runSonarScan(config, projectKey = null) {
       ok: false,
       stdout: "",
       stderr:
-        "Unable to resolve Sonar token. Set KJ_SONAR_TOKEN env var, configure sonarqube.token in kj.config.yml, or save credentials in ~/.karajan/sonar-credentials.json.",
+        "Unable to resolve Sonar token. Fix: (1) run 'kj init' to configure it, (2) set KJ_SONAR_TOKEN env var, or (3) add sonarqube.token to ~/.karajan/kj.config.yml.",
       exitCode: 1
     };
   }

package/src/utils/display.js

@@ -452,7 +452,11 @@ const EVENT_HANDLERS = {
   question: (event, icon) => {
     console.log();
     console.log(`${ANSI.bold}${ANSI.yellow}${icon} Paused - question:${ANSI.reset}`);
-    console.log(`  ${event.detail?.question || event.message}`);
+    const questionText = event.detail?.question || event.message || "";
+    const questionLines = questionText.split("\n");
+    for (const line of questionLines) {
+      console.log(`  ${line}`);
+    }
     console.log(`${ANSI.dim}Resume with: kj resume ${event.sessionId} --answer "<response>"${ANSI.reset}`);
   },
 

package/src/utils/project-detect.js

@@ -1,15 +1,62 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 
-const TEST_FRAMEWORKS = ["vitest", "jest", "@jest/core", "mocha", "ava", "tap", "playwright", "@playwright/test"];
-
-const CONFIG_FILES = [
+// --- JS/TS ---
+const JS_FRAMEWORKS = ["vitest", "jest", "@jest/core", "mocha", "ava", "tap", "playwright", "@playwright/test"];
+const JS_CONFIG_FILES = [
   "vitest.config.js", "vitest.config.ts",
   "jest.config.js", "jest.config.ts", "jest.config.mjs",
   ".mocharc.yml", ".mocharc.json",
   "playwright.config.js", "playwright.config.ts"
 ];
 
+// --- Multi-language project markers ---
+const LANGUAGE_MARKERS = [
+  // Java / Kotlin (Maven)
+  { file: "pom.xml", framework: "junit", language: "java" },
+  // Java / Kotlin (Gradle)
+  { file: "build.gradle", framework: "junit", language: "java" },
+  { file: "build.gradle.kts", framework: "junit", language: "kotlin" },
+  // Python
+  { file: "pytest.ini", framework: "pytest", language: "python" },
+  { file: "pyproject.toml", framework: "pytest", language: "python" },
+  { file: "setup.py", framework: "pytest", language: "python" },
+  { file: "setup.cfg", framework: "pytest", language: "python" },
+  { file: "tox.ini", framework: "pytest", language: "python" },
+  // Go
+  { file: "go.mod", framework: "go-test", language: "go" },
+  // Rust
+  { file: "Cargo.toml", framework: "cargo-test", language: "rust" },
+  // C# / .NET
+  { file: "*.csproj", glob: true, framework: "dotnet-test", language: "csharp" },
+  { file: "*.sln", glob: true, framework: "dotnet-test", language: "csharp" },
+  // Ruby
+  { file: "Gemfile", framework: "rspec", language: "ruby" },
+  { file: ".rspec", framework: "rspec", language: "ruby" },
+  // PHP
+  { file: "phpunit.xml", framework: "phpunit", language: "php" },
+  { file: "phpunit.xml.dist", framework: "phpunit", language: "php" },
+  // Swift
+  { file: "Package.swift", framework: "xctest", language: "swift" },
+  // Dart / Flutter
+  { file: "pubspec.yaml", framework: "dart-test", language: "dart" },
+];
+
+/** Test file patterns per language (used by TDD policy). */
+export const TEST_PATTERNS_BY_LANGUAGE = {
+  javascript: ["/tests/", "/__tests__/", ".test.", ".spec."],
+  java:       ["/src/test/", "/test/", "Test.java", "Tests.java", "IT.java"],
+  kotlin:     ["/src/test/", "/test/", "Test.kt", "Tests.kt", "/src/androidTest/"],
+  python:     ["/tests/", "/test/", "test_", "_test.py", "tests.py"],
+  go:         ["_test.go"],
+  rust:       ["/tests/", "#[test]", "#[cfg(test)]"],
+  csharp:     ["/Tests/", "/Test/", "Tests.cs", "Test.cs", ".Tests/"],
+  ruby:       ["/spec/", "/test/", "_spec.rb", "_test.rb"],
+  php:        ["/tests/", "/test/", "Test.php"],
+  swift:      ["/Tests/", "Tests.swift"],
+  dart:       ["/test/", "_test.dart"],
+};
+
 function frameworkFromConfig(filename) {
   if (filename.startsWith("vitest")) return "vitest";
   if (filename.startsWith("jest")) return "jest";
@@ -19,32 +66,49 @@ function frameworkFromConfig(filename) {
 
 /**
  * Detect if the project has a test framework configured.
- * Checks: package.json devDependencies/dependencies for known test frameworks.
- * Also checks for config files (vitest.config, jest.config, .mocharc, playwright.config).
+ * Checks JS (package.json), then multi-language project markers.
  * @param {string} cwd - Project root
- * @returns {Promise<{hasTests: boolean, framework: string|null}>}
+ * @returns {Promise<{hasTests: boolean, framework: string|null, language: string|null}>}
  */
 export async function detectTestFramework(cwd = process.cwd()) {
+  // 1. JS/TS: check package.json
   try {
     const pkgRaw = await fs.readFile(path.join(cwd, "package.json"), "utf8");
     const pkg = JSON.parse(pkgRaw);
     const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
 
-    for (const fw of TEST_FRAMEWORKS) {
+    for (const fw of JS_FRAMEWORKS) {
       if (allDeps[fw]) {
-        return { hasTests: true, framework: fw };
+        return { hasTests: true, framework: fw, language: "javascript" };
       }
     }
   } catch { /* no package.json or parse error */ }
 
-  for (const cf of CONFIG_FILES) {
+  // 2. JS/TS: check config files
+  for (const cf of JS_CONFIG_FILES) {
     try {
       await fs.access(path.join(cwd, cf));
-      return { hasTests: true, framework: frameworkFromConfig(cf) };
+      return { hasTests: true, framework: frameworkFromConfig(cf), language: "javascript" };
+    } catch { /* not found */ }
+  }
+
+  // 3. Multi-language: check project markers
+  for (const marker of LANGUAGE_MARKERS) {
+    try {
+      if (marker.glob) {
+        const entries = await fs.readdir(cwd);
+        const ext = marker.file.replace("*", "");
+        if (entries.some((e) => e.endsWith(ext))) {
+          return { hasTests: true, framework: marker.framework, language: marker.language };
+        }
+      } else {
+        await fs.access(path.join(cwd, marker.file));
+        return { hasTests: true, framework: marker.framework, language: marker.language };
+      }
     } catch { /* not found */ }
   }
 
-  return { hasTests: false, framework: null };
+  return { hasTests: false, framework: null, language: null };
 }
 
 /**

package/src/utils/update-check.js

@@ -0,0 +1,74 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getKarajanHome } from "./paths.js";
+
+const CACHE_FILE = "update-check.json";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const PACKAGE_NAME = "karajan-code";
+
+/**
+ * Check npm for a newer version. Non-blocking, cached for 24h.
+ * Returns { updateAvailable, latest, current } or null if check fails/cached.
+ */
+export async function checkForUpdate(currentVersion) {
+  try {
+    const cachePath = path.join(getKarajanHome(), CACHE_FILE);
+
+    // Check cache first
+    try {
+      const raw = await fs.readFile(cachePath, "utf8");
+      const cache = JSON.parse(raw);
+      if (cache.checkedAt && Date.now() - cache.checkedAt < CACHE_TTL_MS) {
+        if (!cache.latest || cache.latest === currentVersion) return null;
+        return { updateAvailable: true, latest: cache.latest, current: currentVersion };
+      }
+    } catch { /* no cache or expired */ }
+
+    // Fetch from npm (timeout 3s, don't block)
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 3000);
+    const res = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, {
+      signal: controller.signal,
+      headers: { "Accept": "application/json" },
+    });
+    clearTimeout(timeout);
+
+    if (!res.ok) return null;
+    const data = await res.json();
+    const latest = data.version;
+
+    // Save cache
+    await fs.mkdir(getKarajanHome(), { recursive: true });
+    await fs.writeFile(cachePath, JSON.stringify({ latest, checkedAt: Date.now() }), "utf8");
+
+    if (latest === currentVersion) return null;
+    if (compareVersions(latest, currentVersion) > 0) {
+      return { updateAvailable: true, latest, current: currentVersion };
+    }
+    return null;
+  } catch {
+    return null; // Network error, offline, etc. Never block.
+  }
+}
+
+/**
+ * Print update notice if available. Call at CLI startup, non-blocking.
+ */
+export async function printUpdateNotice(currentVersion) {
+  const result = await checkForUpdate(currentVersion);
+  if (result?.updateAvailable) {
+    console.log(`\n  Update available: v${result.current} → v${result.latest}`);
+    console.log(`  Run: npm install -g ${PACKAGE_NAME}\n`);
+  }
+}
+
+/** Simple semver compare: returns >0 if a > b, <0 if a < b, 0 if equal */
+function compareVersions(a, b) {
+  const pa = a.split(".").map(Number);
+  const pb = b.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
+    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
+  }
+  return 0;
+}

package/templates/roles/coder.md

@@ -28,6 +28,15 @@ Before reporting done, verify that ALL parts of the task are addressed:
 - If you write tests first (TDD), the implementation MUST make those tests pass.
 - Do NOT commit code that doesn't compile or doesn't pass tests.
 
+## Secrets and environment variables
+
+- NEVER hardcode API keys, tokens, passwords, secrets, or credentials in source code. No exceptions, not even for public keys or test keys.
+- ALWAYS use environment variables via `process.env` (Node.js), `os.environ` (Python), or the equivalent for the project's language.
+- If the project needs API keys, create a `.env.example` file with placeholder values and add `.env` to `.gitignore`.
+- If `.gitignore` does not already include `.env`, add it.
+- If the task requires Firebase, Stripe, OpenAI, or any third-party API: use `.env` for the keys and document required variables in `.env.example` or README.
+- Database connection strings with credentials MUST use environment variables.
+
 ## File modification safety
 
 - NEVER overwrite existing files entirely. Always make targeted, minimal edits.