karajan-code 1.38.0 → 1.38.2

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.37.0 — .kj/run.log                                              │
+│  kj-tail v1.38.1 — .kj/run.log                                              │
 │                                                                              │
 │  ├─ 📋 Triage: medium (sw) — enabling researcher, architect, planner         │
 │  ├─ ⚙️ Preflight passed — all checks OK                                     │
@@ -205,7 +205,7 @@ hu-reviewer? → triage → discover? → architect? → planner? → coder →
 
 | Role | What it does | Default |
 |------|-------------|---------|
-| **hu-reviewer** | Certifies user stories before coding (6 dimensions, 7 antipatterns) | Off |
+| **hu-reviewer** | Certifies user stories before coding (6 dimensions, 7 antipatterns) | Auto (medium/complex) |
 | **triage** | Classifies complexity, activates roles, auto-simplifies for trivial tasks | **On** |
 | **discover** | Detects gaps in requirements (Mom Test, Wendel, JTBD) | Off |
 | **architect** | Designs solution architecture before planning | Off |
@@ -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,13 +267,14 @@ 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
 - **Pipeline complexity**: Triage classifies task → trivial tasks skip reviewer loop
 - **Provider outages**: Retries on 500/502/503/504 with backoff (same as rate limits)
 - **Coverage**: Coverage-only quality gate failures treated as advisory
+- **HU Manager**: Complex tasks auto-decompose into formal user stories with dependencies. Each HU runs as its own sub-pipeline with state tracking visible in the HU Board
 
 No per-project configuration required. If you want to customize, config is layered: session > project > global.
 
@@ -298,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 2044 tests with Vitest
+npm test              # Run 2142 tests with Vitest
 npm run validate      # Lint + test
 ```
 
@@ -314,4 +315,4 @@ Issues and pull requests welcome. If something doesn't work as documented, [open
 
 ---
 
-Built by [@manufosela](https://github.com/manufosela). Head of Engineering at Geniova Technologies, co-organizer of NodeJS Madrid, author of [Liderazgo Afectivo](https://www.amazon.es/dp/B0D7F4C8KC). 90+ npm packages published.
+Built by [@manufosela](https://github.com/manufosela). Head of Engineering at Geniova Technologies, co-organizer of NodeJS Madrid, author of [Liderazgo Afectivo](https://www.liderazgoafectivo.com). 90+ npm packages published.

package/docs/README.es.md

@@ -38,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
@@ -47,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
 
@@ -81,7 +82,7 @@ Este es el caso de uso principal. Karajan corre como servidor MCP dentro de Clau
 Tu → Claude Code → kj_run (via MCP) → triage → coder → sonar → reviewer → tester → security
 ```
 
-El servidor MCP se auto-registra durante `npm install`. Tu agente de IA ve 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.
 
@@ -106,28 +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 ✅           │
-│   via MCP, solo ves       │    │  ├─ 🔍 Sonar: OK         │
-│   el resultado final)     │    │  ├─ 👁️ Reviewer ❌        │
-│                           │    │  ├─ ⚖️ Solomon: 2 cond.   │
-│                           │    │  ├─ 🔨 Coder (iter 2) ✅  │
-│                           │    │  ├─ ✅ Review: APPROVED    │
-│                           │    │  ├─ 🧪 Tester: passed     │
-│                           │    │  └─ 🏁 Result: APPROVED   │
-└──────────────────────────┘    └──────────────────────────┘
-```
-
 [**Ver la demo completa del pipeline**](https://karajancode.com#demo): triage, arquitectura, TDD, SonarQube, code review, arbitraje de Solomon, auditoria de seguridad.
 
 ## El pipeline
@@ -140,10 +119,10 @@ hu-reviewer? → triage → discover? → architect? → planner? → coder →
 
 | Rol | Que hace | Por defecto |
 |-----|----------|-------------|
-| **hu-reviewer** | Certifica historias de usuario antes de codificar (6 dimensiones, 7 antipatrones) | Off |
+| **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 |
@@ -168,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)).
 
@@ -202,21 +181,22 @@ 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
 - **Complejidad del pipeline**: Triage clasifica la tarea, las triviales saltan el loop del reviewer
 - **Caidas de proveedor**: Reintentos en 500/502/503/504 con backoff (igual que rate limits)
 - **Cobertura**: Fallos de quality gate solo por cobertura se tratan como advisory
+- **HU Manager**: Las tareas complejas se descomponen automaticamente en historias de usuario formales con dependencias. Cada HU se ejecuta como su propio sub-pipeline con seguimiento de estado visible en el HU Board
 
 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
 
@@ -233,7 +213,7 @@ 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
-npm test              # Ejecutar 2044 tests con Vitest
+npm test              # Ejecutar 2142 tests con Vitest
 npm run validate      # Lint + test
 ```
 
@@ -249,4 +229,4 @@ 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.amazon.es/dp/B0D7F4C8KC). 90+ paquetes npm publicados.
+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.

package/package.json

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

package/src/commands/code.js

@@ -13,7 +13,9 @@ export async function codeCommand({ task, config, logger }) {
   if (config.coder_rules) {
     try {
       coderRules = await fs.readFile(config.coder_rules, "utf8");
-    } catch { /* no coder rules file, that's ok */ }
+    } catch {
+      try { coderRules = await fs.readFile("coder-rules.md", "utf8"); } catch { /* no coder rules file */ }
+    }
   }
   const prompt = buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology || "tdd" });
   const onOutput = ({ line }) => process.stdout.write(`${line}\n`);

package/src/commands/init.js

@@ -128,7 +128,7 @@ async function ensureReviewRules(reviewRulesPath, logger) {
     "# Review Rules\n\n- Focus on security, correctness, and test coverage.\n",
     "utf8"
   );
-  logger.info("Created review-rules.md");
+  logger.info("Created .karajan/review-rules.md");
 }
 
 async function ensureCoderRules(coderRulesPath, logger) {
@@ -150,7 +150,7 @@ async function ensureCoderRules(coderRulesPath, logger) {
     ].join("\n");
   }
   await fs.writeFile(coderRulesPath, content, "utf8");
-  logger.info("Created coder-rules.md");
+  logger.info("Created .karajan/coder-rules.md");
 }
 
 async function setupSonarQube(config, logger) {
@@ -271,8 +271,10 @@ export async function initCommand({ logger, flags = {} }) {
   logger.info(`Ensured ${karajanHome} exists`);
 
   const configPath = getConfigPath();
-  const reviewRulesPath = path.resolve(process.cwd(), "review-rules.md");
-  const coderRulesPath = path.resolve(process.cwd(), "coder-rules.md");
+  const karajanDir = path.join(process.cwd(), ".karajan");
+  await ensureDir(karajanDir);
+  const reviewRulesPath = path.resolve(karajanDir, "review-rules.md");
+  const coderRulesPath = path.resolve(karajanDir, "coder-rules.md");
 
   const { config, exists: configExists } = await loadConfig();
   const interactive = flags.noInteractive !== true && isTTY();

package/src/config.js

@@ -39,8 +39,8 @@ const DEFAULTS = {
   review_mode: "standard",
   max_iterations: 5,
   max_budget_usd: null,
-  review_rules: "./review-rules.md",
-  coder_rules: "./coder-rules.md",
+  review_rules: "./.karajan/review-rules.md",
+  coder_rules: "./.karajan/coder-rules.md",
   base_branch: "main",
   coder_options: { model: null, auto_approve: true, fallback_coder: null },
   reviewer_options: {

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

@@ -482,7 +482,9 @@ export async function handleCodeDirect(a, server, extra) {
   if (config.coder_rules) {
     try {
       coderRules = await fs.readFile(config.coder_rules, "utf8");
-    } catch { /* no coder rules file */ }
+    } catch {
+      try { coderRules = await fs.readFile("coder-rules.md", "utf8"); } catch { /* no coder rules file */ }
+    }
   }
   const prompt = buildCoderPrompt({ task: a.task, coderRules, methodology: config.development?.methodology || "tdd" });
   sendTrackerLog(server, "coder", "running", coderRole.provider);
@@ -904,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");
@@ -945,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/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.