karajan-code 1.59.1 → 2.0.0

package/src/roles/solomon-role.js

@@ -36,27 +36,51 @@ function buildPrompt({ conflict, task, instructions }) {
   }
 
   sections.push(
-    "You are Solomon, the conflict resolver in a multi-role AI pipeline.",
-    "You are activated when agents cannot reach agreement after their iteration limit.",
-    "## Decision hierarchy",
+    "You are Solomon, the autonomous pipeline boss in a multi-agent AI coding orchestrator.",
+    "You are activated whenever ANYTHING deviates from normal flow: rate limits, agent failures, conflicts, max iterations, quality gate issues.",
+    "",
+    "## Core principle",
+    "The pipeline NEVER skips a quality stage (review, tests, sonar, security) without exhausting alternatives first.",
+    "NEVER approve skipping a stage as your first option. Follow the recovery hierarchy below.",
+    "",
+    "## ABSOLUTE RULE: Security issues from reviewer are NEVER overridable",
+    "If the reviewer's blocking_issues contain security-related issues (categories: authentication, authorization, injection, XSS, CSRF, exposed secrets/credentials, cryptography, session management, input validation), you MUST:",
+    "- Set ruling to \"continue\" (NOT \"approve\")",
+    "- Return the reviewer feedback to the coder for fixing",
+    "- NEVER approve or skip security issues regardless of task complexity or deadline",
+    "This rule overrides all other rules including the recovery hierarchy.",
+    "",
+    "## Recovery hierarchy (STRICT ORDER — follow top to bottom)",
+    "When a stage fails or an agent is unavailable:",
+    "1. **wait** — If there is a known cooldown (cooldownUntil), and it is less than 10 minutes, WAIT. Set ruling to 'approve_with_conditions' with condition 'wait for cooldown' and set waitUntil.",
+    "2. **retry_with_alternative** — Try the same stage with a DIFFERENT agent. The pipeline has multiple agents (claude, codex, gemini). Set ruling to 'approve_with_conditions' with condition specifying the alternative agent.",
+    "3. **evaluate_risk** — Only if no alternatives are available, evaluate the risk of skipping. Consider: task complexity, what the stage would catch, security implications.",
+    "   - If risk is LOW (trivial task, no security impact, style-only review): approve with a clear justification.",
+    "   - If risk is HIGH (complex task, security changes, new dependencies): escalate_human.",
+    "4. **escalate_human** — When you cannot resolve it safely. Always prefer this over blindly approving.",
+    "",
+    "## Quality hierarchy",
     "Security > Correctness > Tests > Architecture > Maintainability > Style",
     "- Green tests are sacred. Never dismiss a failing test.",
     "- Style preferences NEVER block approval.",
-    "- Hardcoded values that will come from DB later are acceptable (contextual false positive).",
     "- Sonar INFO/MINOR issues are always dismissable.",
     "- Sonar BLOCKER/CRITICAL must be fixed unless they are proven false positives.",
+    "",
     "## Classification rules",
     "For each issue, classify as:",
     "1. **critical** (security, correctness, tests broken) — action: must_fix",
     "2. **important** (architecture, maintainability) — action: should_fix",
     "3. **style** (naming, formatting, preferences, false positives) — action: dismiss",
-    "## Your decision options",
-    '1. **approve** — All pending issues are style/false positives. Pipeline continues.',
-    '2. **approve_with_conditions** — Important issues exist but are fixable. Give exact instructions to Coder for one more attempt.',
-    '3. **escalate_human** — Critical issues that cannot be resolved, ambiguous requirements, architecture decisions, or business logic decisions.',
-    '4. **create_subtask** — A prerequisite task must be completed first to resolve the conflict. The current task will pause, the subtask runs, then the current task resumes.',
+    "",
+    "## Ruling options",
+    '1. **approve** — FORBIDDEN when a quality stage (review, tests, sonar, security) was skipped or failed. You MUST try alternatives first (wait for cooldown, use different agent). Only allowed when all stages completed successfully and remaining issues are style/false positives.',
+    '2. **approve_with_conditions** — Fixable issues or recovery actions needed. Include exact conditions (wait, retry with alternative agent, specific fix instructions). Set extraIterations and/or alternativeAgent.',
+    '3. **escalate_human** — Cannot resolve safely. Critical issues, ambiguous requirements, architecture decisions, high-risk skip.',
+    '4. **create_subtask** — A prerequisite task must be completed first.',
+    "",
     "Return a single valid JSON object with your ruling and nothing else.",
-    'JSON schema: {"ruling":"approve"|"approve_with_conditions"|"escalate_human"|"create_subtask","classification":[{"issue":string,"category":"critical"|"important"|"style","action":"must_fix"|"should_fix"|"dismiss"}],"conditions":[string],"dismissed":[string],"escalate":boolean,"escalate_reason":string|null,"subtask":{"title":string,"description":string,"reason":string}|null}'
+    'JSON schema: {"ruling":"approve"|"approve_with_conditions"|"escalate_human"|"create_subtask","classification":[{"issue":string,"category":"critical"|"important"|"style","action":"must_fix"|"should_fix"|"dismiss"}],"conditions":[string],"dismissed":[string],"escalate":boolean,"escalate_reason":string|null,"extraIterations":number|null,"alternativeAgent":string|null,"waitUntil":string|null,"subtask":{"title":string,"description":string,"reason":string}|null}',
+    "When ruling is approve_with_conditions, set extraIterations (1-5) and/or alternativeAgent (claude|codex|gemini) as appropriate."
   );
 
   const stage = conflict?.stage || "unknown";
@@ -66,14 +90,48 @@ function buildPrompt({ conflict, task, instructions }) {
   const isFirstRejection = conflict?.isFirstRejection ?? false;
   const isRepeat = conflict?.isRepeat ?? false;
 
+  const budgetUsd = conflict?.budget_usd;
+  const budgetLine = typeof budgetUsd === "number" ? `Budget spent so far: $${budgetUsd.toFixed(2)}` : "";
+
   sections.push(
     `## Conflict context`,
     `Stage: ${stage}`,
     `Iterations exhausted: ${iterationCount}/${maxIterations}`,
     `isFirstRejection: ${isFirstRejection}`,
-    `isRepeat: ${isRepeat}`
+    `isRepeat: ${isRepeat}`,
+    budgetLine,
+    "",
+    "## Budget awareness",
+    "Consider the cost-benefit ratio when deciding. If significant budget has been spent with little progress,",
+    "prefer approving the current work or escalating to human. If progress is good and budget is low,",
+    "prefer continuing with conditions. Never waste budget on style-only iterations."
   );
 
+  if (conflict?.previousSolomonRulings?.length > 0) {
+    const rulingLines = conflict.previousSolomonRulings.map((r, idx) =>
+      `${idx + 1}. Stage: ${r.conflictStage}, Ruling: ${r.ruling}${r.alternativeAgent ? `, agent: ${r.alternativeAgent}` : ""}${r.error ? ` (FAILED: ${r.error})` : ""}`
+    ).join("\n");
+    sections.push(
+      "## Your previous rulings in this session (DO NOT repeat failed strategies)",
+      rulingLines,
+      "If a previous ruling failed (e.g., alternative agent also rate-limited), do NOT suggest the same strategy again. Escalate or try a different approach."
+    );
+  }
+
+  // Rate limit specific instruction
+  if (stage?.includes("rate_limit")) {
+    const rateLimitedAgent = conflict?.history?.[0]?.feedback?.match(/Agent "(\w+)"/)?.[1] || "unknown";
+    sections.push(
+      "## CRITICAL: Agent rate-limited",
+      `Agent "${rateLimitedAgent}" is rate-limited. You MUST NOT approve skipping this stage.`,
+      "Your ONLY valid options are:",
+      `1. approve_with_conditions + alternativeAgent: pick a different agent (available: claude, codex, gemini — NOT "${rateLimitedAgent}")`,
+      "2. approve_with_conditions + waitUntil: if cooldown is known and <10min",
+      "3. escalate_human: if no alternatives work",
+      `DO NOT set ruling to "approve". The stage MUST be completed by some agent.`
+    );
+  }
+
   if (conflict?.issueCategories) {
     sections.push(`## Issue categories\n${JSON.stringify(conflict.issueCategories, null, 2)}`);
   }

package/src/roles/tester-role.js

@@ -1,6 +1,6 @@
-import { BaseRole } from "./base-role.js";
-import { createAgent as defaultCreateAgent } from "../agents/index.js";
+import { AgentRole } from "./agent-role.js";
 import { extractFirstJson } from "../utils/json-extract.js";
+import { detectTestFramework } from "../utils/project-detect.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -8,108 +8,134 @@ const SUBAGENT_PREAMBLE = [
   "Do NOT use any MCP tools. Focus only on evaluating test quality."
 ].join(" ");
 
-function resolveProvider(config) {
-  return (
-    config?.roles?.tester?.provider ||
-    config?.roles?.coder?.provider ||
-    "claude"
-  );
-}
-
-function buildPrompt({ task, diff, sonarIssues, instructions }) {
-  const sections = [SUBAGENT_PREAMBLE];
-
-  if (instructions) {
-    sections.push(instructions);
+/**
+ * Map test framework to the command that runs tests with coverage.
+ */
+const COVERAGE_COMMANDS = {
+  vitest: "npx vitest run --coverage --reporter=verbose 2>&1",
+  jest: "npx jest --coverage --verbose 2>&1",
+  mocha: "npx c8 mocha 2>&1",
+  playwright: "npx playwright test 2>&1",
+  pytest: "pytest --cov --tb=short 2>&1",
+  "go-test": "go test -cover -v ./... 2>&1",
+  "cargo-test": "cargo test --verbose 2>&1",
+  junit: "mvn test 2>&1",
+  rspec: "bundle exec rspec 2>&1",
+  phpunit: "vendor/bin/phpunit --coverage-text 2>&1",
+  "dotnet-test": "dotnet test --collect:\"XPlat Code Coverage\" 2>&1",
+  "dart-test": "dart test 2>&1"
+};
+
+const TEST_COMMANDS = {
+  vitest: "npx vitest run --reporter=verbose 2>&1",
+  jest: "npx jest --verbose 2>&1",
+  mocha: "npx mocha 2>&1",
+  playwright: "npx playwright test 2>&1",
+  pytest: "pytest --tb=short 2>&1",
+  "go-test": "go test -v ./... 2>&1",
+  "cargo-test": "cargo test --verbose 2>&1",
+  junit: "mvn test 2>&1",
+  rspec: "bundle exec rspec 2>&1",
+  phpunit: "vendor/bin/phpunit 2>&1",
+  "dotnet-test": "dotnet test 2>&1",
+  "dart-test": "dart test 2>&1"
+};
+
+export class TesterRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "tester" });
   }
 
-  sections.push(
-    "You are a test quality gate. You do NOT write tests — you evaluate them.",
-    "Run the test suite, check coverage, identify missing scenarios, and evaluate assertion quality.",
-    "Return a single valid JSON object with your findings and nothing else.",
-    'JSON schema: {"tests_pass":boolean,"coverage":{"overall":number,"services":number,"utilities":number},"missing_scenarios":[string],"quality_issues":[string],"verdict":"pass"|"fail"}',
-    `## Task\n${task}`
-  );
-
-  if (diff) {
-    sections.push(`## Git diff\n${diff}`);
+  extractInput(input) {
+    if (typeof input === "string") return { task: input, diff: null, sonarIssues: null };
+    return {
+      task: input?.task || this.context?.task || "",
+      diff: input?.diff || null,
+      sonarIssues: input?.sonarIssues || null,
+      onOutput: input?.onOutput || null
+    };
   }
 
-  if (sonarIssues) {
-    sections.push(`## Sonar test issues\n${sonarIssues}`);
-  }
-
-  return sections.join("\n\n");
-}
-
-function parseTesterOutput(raw) {
-  return extractFirstJson(raw);
-}
+  async buildPrompt({ task, diff, sonarIssues }) {
+    const projectDir = this.config?.projectDir || process.cwd();
+    const detection = await detectTestFramework(projectDir);
+
+    const sections = [SUBAGENT_PREAMBLE];
+    if (this.instructions) sections.push(this.instructions);
+
+    sections.push(
+      "You are a test quality gate. Your job is to EXECUTE the test suite, measure REAL coverage, and evaluate quality.",
+      "You MUST run the actual test command — do NOT guess or estimate results."
+    );
+
+    if (detection.hasTests && detection.framework) {
+      const coverageCmd = COVERAGE_COMMANDS[detection.framework];
+      const testCmd = TEST_COMMANDS[detection.framework];
+      sections.push(
+        `## Detected test framework: ${detection.framework} (${detection.language})`,
+        "**Step 0**: If node_modules/ does not exist, run `npm install` (or `pnpm install`) first.",
+        `**Step 1**: Run the test suite with coverage:`,
+        "```bash",
+        coverageCmd || testCmd,
+        "```",
+        "If the coverage command fails (missing dependency), fall back to:",
+        "```bash",
+        testCmd,
+        "```",
+        "**Step 2**: Parse the output to extract: pass/fail count, coverage percentages, any failures.",
+        "**Step 3**: Return a single JSON object with REAL numbers from the test output."
+      );
+    } else {
+      sections.push(
+        "## No test framework detected",
+        "**Step 0**: If package.json exists but node_modules/ does not, run `npm install` first.",
+        "**Step 1**: Look at package.json or project files to find test scripts.",
+        "**Step 2**: Try running `npm test` or detect the framework from config files.",
+        "**Step 3**: If tests exist, run them. If no tests exist, report tests_pass: false with verdict: 'fail'.",
+        "**Step 4**: Return a JSON object with your findings."
+      );
+    }
 
-export class TesterRole extends BaseRole {
-  constructor({ config, logger, emitter = null, createAgentFn = null }) {
-    super({ name: "tester", config, logger, emitter });
-    this._createAgent = createAgentFn || defaultCreateAgent;
+    sections.push(
+      "",
+      "Return ONLY a single valid JSON object:",
+      '{"tests_pass":boolean,"coverage":{"overall":number,"services":number,"utilities":number},"missing_scenarios":[string],"quality_issues":[string],"verdict":"pass"|"fail"}',
+      "",
+      "- coverage.overall MUST be a real number from the test runner output, NOT an estimate",
+      "- If coverage tool is not available, set coverage.overall to null (not 0, not a guess)",
+      "- tests_pass must reflect whether the actual test run succeeded",
+      `## Task\n${task}`
+    );
+    if (diff) sections.push(`## Git diff\n${diff}`);
+    if (sonarIssues) sections.push(`## Sonar test issues\n${sonarIssues}`);
+    return { prompt: sections.join("\n\n") };
   }
 
-  async execute(input) {
-    const { task, diff, sonarIssues } = typeof input === "string"
-      ? { task: input, diff: null, sonarIssues: null }
-      : { task: input?.task || this.context?.task || "", diff: input?.diff || null, sonarIssues: input?.sonarIssues || null };
-
-    const provider = resolveProvider(this.config);
-    const agent = this._createAgent(provider, this.config, this.logger);
-
-    const prompt = buildPrompt({ task, diff, sonarIssues, instructions: this.instructions });
-    const result = await agent.runTask({ prompt, role: "tester" });
-
-    if (!result.ok) {
-      return {
-        ok: false,
-        result: {
-          error: result.error || result.output || "Tester failed",
-          provider
-        },
-        summary: `Tester failed: ${result.error || "unknown error"}`
-      };
-    }
+  parseOutput(raw) { return extractFirstJson(raw); }
 
-    try {
-      const parsed = parseTesterOutput(result.output);
-      if (!parsed) {
-        return {
-          ok: false,
-          result: { error: "Failed to parse tester output: no JSON found", provider },
-          summary: "Tester output parse error: no JSON found"
-        };
-      }
+  isSuccessful(parsed) {
+    const verdict = parsed.verdict || (parsed.tests_pass ? "pass" : "fail");
+    return verdict === "pass";
+  }
 
-      const verdict = parsed.verdict || (parsed.tests_pass ? "pass" : "fail");
-      const ok = verdict === "pass";
-      const coverage = parsed.coverage || {};
+  buildSuccessResult(parsed, provider) {
+    const verdict = parsed.verdict || (parsed.tests_pass ? "pass" : "fail");
+    return {
+      tests_pass: Boolean(parsed.tests_pass),
+      coverage: parsed.coverage || {},
+      missing_scenarios: parsed.missing_scenarios || [],
+      quality_issues: parsed.quality_issues || [],
+      verdict,
+      provider
+    };
+  }
 
-      return {
-        ok,
-        result: {
-          tests_pass: Boolean(parsed.tests_pass),
-          coverage,
-          missing_scenarios: parsed.missing_scenarios || [],
-          quality_issues: parsed.quality_issues || [],
-          verdict,
-          provider
-        },
-        summary: (() => {
-          const missingPart = parsed.missing_scenarios?.length ? `; ${parsed.missing_scenarios.length} missing scenario(s)` : "";
-          const qualityPart = parsed.quality_issues?.length ? `; ${parsed.quality_issues.length} quality issue(s)` : "";
-          return `Verdict: ${verdict}; Coverage: ${coverage.overall ?? "?"}%${missingPart}${qualityPart}`;
-        })()
-      };
-    } catch (err) {
-      return {
-        ok: false,
-        result: { error: `Failed to parse tester output: ${err.message}`, provider },
-        summary: `Tester output parse error: ${err.message}`
-      };
-    }
+  buildSummary(parsed) {
+    const verdict = parsed.verdict || (parsed.tests_pass ? "pass" : "fail");
+    const coverage = parsed.coverage || {};
+    const coverageStr = coverage.overall != null ? `${coverage.overall}%` : "not measured";
+    const missingPart = parsed.missing_scenarios?.length ? `; ${parsed.missing_scenarios.length} missing scenario(s)` : "";
+    const qualityPart = parsed.quality_issues?.length ? `; ${parsed.quality_issues.length} quality issue(s)` : "";
+    return `Verdict: ${verdict}; Coverage: ${coverageStr}${missingPart}${qualityPart}`;
   }
 }

package/src/roles/triage-role.js

@@ -1,5 +1,4 @@
-import { BaseRole } from "./base-role.js";
-import { createAgent as defaultCreateAgent } from "../agents/index.js";
+import { AgentRole } from "./agent-role.js";
 import { buildTriagePrompt } from "../prompts/triage.js";
 import { VALID_TASK_TYPES } from "../guards/policy-resolver.js";
 import { extractFirstJson } from "../utils/json-extract.js";
@@ -7,18 +6,7 @@ import { extractFirstJson } from "../utils/json-extract.js";
 const VALID_LEVELS = new Set(["trivial", "simple", "medium", "complex"]);
 const VALID_ROLES = new Set(["planner", "researcher", "refactorer", "reviewer", "tester", "security", "impeccable"]);
 const FALLBACK_TASK_TYPE = "sw";
-
-function resolveProvider(config) {
-  return (
-    config?.roles?.triage?.provider ||
-    config?.roles?.coder?.provider ||
-    "claude"
-  );
-}
-
-function parseTriageOutput(raw) {
-  return extractFirstJson(raw);
-}
+const FALLBACK_RESULT = { level: "medium", roles: ["reviewer"], taskType: FALLBACK_TASK_TYPE, shouldDecompose: false };
 
 function normalizeRoles(roles) {
   if (!Array.isArray(roles)) return [];
@@ -27,115 +15,66 @@ function normalizeRoles(roles) {
 
 function normalizeSubtasks(subtasks) {
   if (!Array.isArray(subtasks)) return [];
-  return subtasks
-    .map((s) => (typeof s === "string" ? s.trim() : ""))
-    .filter(Boolean)
-    .slice(0, 5);
+  return subtasks.map((s) => (typeof s === "string" ? s.trim() : "")).filter(Boolean).slice(0, 5);
 }
 
 function normalizeDomainHints(hints) {
   if (!Array.isArray(hints)) return [];
-  return hints
-    .map((h) => (typeof h === "string" ? h.trim().toLowerCase() : ""))
-    .filter(Boolean);
+  return hints.map((h) => (typeof h === "string" ? h.trim().toLowerCase() : "")).filter(Boolean);
 }
 
-export class TriageRole extends BaseRole {
-  constructor({ config, logger, emitter = null, createAgentFn = null }) {
-    super({ name: "triage", config, logger, emitter });
-    this._createAgent = createAgentFn || defaultCreateAgent;
+export class TriageRole extends AgentRole {
+  constructor(opts) {
+    super({ ...opts, name: "triage" });
   }
 
-  async execute(input) {
-    const task = typeof input === "string"
-      ? input
-      : input?.task || this.context?.task || "";
-    const onOutput = typeof input === "string" ? null : input?.onOutput || null;
-
-    const provider = resolveProvider(this.config);
-    const agent = this._createAgent(provider, this.config, this.logger);
-
-    const prompt = buildTriagePrompt({ task, instructions: this.instructions });
-    const runArgs = { prompt, role: "triage" };
-    if (onOutput) runArgs.onOutput = onOutput;
-    const result = await agent.runTask(runArgs);
+  async buildPrompt({ task }) {
+    return { prompt: buildTriagePrompt({ task, instructions: this.instructions }) };
+  }
 
-    if (!result.ok) {
-      return {
-        ok: false,
-        result: {
-          error: result.error || result.output || "Triage failed",
-          provider
-        },
-        summary: `Triage failed: ${result.error || "unknown error"}`,
-        usage: result.usage
-      };
+  parseOutput(raw) { return extractFirstJson(raw); }
+
+  buildSuccessResult(parsed, provider) {
+    const level = VALID_LEVELS.has(parsed.level) ? parsed.level : "medium";
+    const roles = normalizeRoles(parsed.roles);
+    const reasoning = String(parsed.reasoning || "").trim() || "No reasoning provided.";
+    const shouldDecompose = Boolean(parsed.shouldDecompose);
+    const subtasks = normalizeSubtasks(parsed.subtasks);
+    const taskType = VALID_TASK_TYPES.has(parsed.taskType) ? parsed.taskType : FALLBACK_TASK_TYPE;
+    const domainHints = normalizeDomainHints(parsed.domainHints);
+
+    const result = { level, roles, reasoning, taskType, domainHints, provider };
+    if (shouldDecompose && subtasks.length > 0) {
+      result.shouldDecompose = true;
+      result.subtasks = subtasks;
+    } else {
+      result.shouldDecompose = false;
     }
+    return result;
+  }
 
-    try {
-      const parsed = parseTriageOutput(result.output);
-      if (!parsed) {
-        return {
-          ok: true,
-          result: {
-            level: "medium",
-            roles: ["reviewer"],
-            reasoning: "Unstructured output, using safe defaults.",
-            taskType: FALLBACK_TASK_TYPE,
-            provider,
-            raw: result.output
-          },
-          summary: "Triage complete (fallback defaults)",
-          usage: result.usage
-        };
-      }
-
-      const level = VALID_LEVELS.has(parsed.level) ? parsed.level : "medium";
-      const roles = normalizeRoles(parsed.roles);
-      const reasoning = String(parsed.reasoning || "").trim() || "No reasoning provided.";
-      const shouldDecompose = Boolean(parsed.shouldDecompose);
-      const subtasks = normalizeSubtasks(parsed.subtasks);
-      const taskType = VALID_TASK_TYPES.has(parsed.taskType) ? parsed.taskType : FALLBACK_TASK_TYPE;
-
-      const domainHints = normalizeDomainHints(parsed.domainHints);
-
-      const triageResult = {
-        level,
-        roles,
-        reasoning,
-        taskType,
-        domainHints,
-        provider
-      };
+  buildSummary(parsed) {
+    const level = VALID_LEVELS.has(parsed.level) ? parsed.level : "medium";
+    const roles = normalizeRoles(parsed.roles);
+    const decomposeNote = parsed.shouldDecompose ? " — decomposition recommended" : "";
+    return `Triage: ${level} (${roles.length} role${roles.length === 1 ? "" : "s"})${decomposeNote}`;
+  }
 
-      if (shouldDecompose && subtasks.length > 0) {
-        triageResult.shouldDecompose = true;
-        triageResult.subtasks = subtasks;
-      } else {
-        triageResult.shouldDecompose = false;
-      }
+  handleParseNull(agentResult, provider) {
+    return {
+      ok: true,
+      result: { ...FALLBACK_RESULT, reasoning: "Unstructured output, using safe defaults.", provider, raw: agentResult.output },
+      summary: "Triage complete (fallback defaults)",
+      usage: agentResult.usage
+    };
+  }
 
-      const decomposeNote = shouldDecompose ? " — decomposition recommended" : "";
-      return {
-        ok: true,
-        result: triageResult,
-        summary: `Triage: ${level} (${roles.length} role${roles.length === 1 ? "" : "s"})${decomposeNote}`,
-        usage: result.usage
-      };
-    } catch { /* agent output is not structured JSON */
-      return {
-        ok: true,
-        result: {
-          level: "medium",
-          roles: ["reviewer"],
-          reasoning: "Failed to parse triage output, using safe defaults.",
-          taskType: FALLBACK_TASK_TYPE,
-          provider,
-          raw: result.output
-        },
-        summary: "Triage complete (fallback defaults)",
-        usage: result.usage
-      };
-    }
+  handleParseError(_err, agentResult, provider) {
+    return {
+      ok: true,
+      result: { ...FALLBACK_RESULT, reasoning: "Failed to parse triage output, using safe defaults.", provider, raw: agentResult.output },
+      summary: "Triage complete (fallback defaults)",
+      usage: agentResult.usage
+    };
   }
 }

package/src/session-store.js

@@ -5,7 +5,7 @@ import { getSessionRoot } from "./utils/paths.js";
 
 const SESSION_ROOT = getSessionRoot();
 
-export function newSessionId() {
+function newSessionId() {
   const now = new Date();
   const stamp = now.toISOString().replaceAll(/[:.]/g, "-");
   return `s_${stamp}`;

package/src/skills/skill-detector.js

@@ -63,6 +63,8 @@ const TASK_TEXT_PATTERNS = [
   { pattern: /\bgo(?:lang)?\b/i, skill: "go" },
   { pattern: /\brust\b/i, skill: "rust" },
   { pattern: /\bpython\b/i, skill: "python" },
+  { pattern: /\bdjango\b/i, skill: "python" },
+  { pattern: /\bflask\b/i, skill: "python" },
   { pattern: /\bruby\b/i, skill: "ruby" },
   { pattern: /\bflutter\b/i, skill: "flutter" },
   { pattern: /\bswift\b/i, skill: "swift" },
@@ -76,6 +78,15 @@ const TASK_TEXT_PATTERNS = [
   { pattern: /\breport\b/i, skill: "data-report" },
   { pattern: /\banalysis\b/i, skill: "data-report" },
   { pattern: /\bfindings\b/i, skill: "data-report" },
+  // Frontend/backend broad categories
+  { pattern: /\bfrontend\b/i, skill: "frontend-design" },
+  { pattern: /\bCSS\b/i, skill: "frontend-design" },
+  { pattern: /\bHTML\b/i, skill: "frontend-design" },
+  { pattern: /\bbackend\b/i, skill: "express" },
+  { pattern: /\bnode\.?js\b/i, skill: "express" },
+  { pattern: /\bAPI\b/, skill: "express" },
+  { pattern: /\bwebsocket\b/i, skill: "express" },
+  { pattern: /\breal[- ]time\b/i, skill: "express" },
 ];
 
 /**

package/src/sonar/config-resolver.js

@@ -27,6 +27,8 @@ export function resolveSonarHost(rawHost) {
  *   2. config.sonarqube.token
  *   3. SONAR_TOKEN env var
  *
+ * For async resolution (including credentials file), use resolveSonarTokenAsync.
+ *
  * @param {object} [config={}] - Karajan config object
  * @returns {string|null} Token string or null if none found
  */
@@ -39,6 +41,22 @@ export function resolveSonarToken(config = {}) {
   return token || null;
 }
 
+/**
+ * Async version of resolveSonarToken that also checks the credentials file
+ * for previously generated tokens.
+ *
+ * @param {object} [config={}] - Karajan config object
+ * @returns {Promise<string|null>} Token string or null if none found
+ */
+export async function resolveSonarTokenAsync(config = {}) {
+  const syncToken = resolveSonarToken(config);
+  if (syncToken) return syncToken;
+
+  // Check credentials file for persisted token
+  const fileCreds = (await loadSonarCredentials()) || {};
+  return fileCreds.token || null;
+}
+
 /**
  * Resolve SonarQube admin credentials from (in priority order):
  *   1. Env vars: KJ_SONAR_ADMIN_USER / KJ_SONAR_ADMIN_PASSWORD
@@ -57,12 +75,13 @@ export async function resolveSonarCredentials(config = {}) {
     process.env.KJ_SONAR_ADMIN_USER ||
     config.sonarqube?.admin_user ||
     fileCreds.user ||
-    null;
+    "admin"; // Default for fresh SonarQube installs
 
   const candidates = [
     process.env.KJ_SONAR_ADMIN_PASSWORD,
     config.sonarqube?.admin_password,
     fileCreds.password,
+    "admin", // Default password for fresh SonarQube installs (zero-config)
   ].filter(Boolean);
 
   return { user, passwords: [...new Set(candidates)] };

package/src/sonar/credentials.js

@@ -33,3 +33,20 @@ export async function loadSonarCredentials() {
 export function credentialsPath() {
   return path.join(getKarajanHome(), CREDENTIALS_FILENAME);
 }
+
+/**
+ * Save a generated token to ~/.karajan/sonar-credentials.json so it persists across sessions.
+ * Merges with existing credentials (preserves user/password if present).
+ */
+export async function saveSonarToken(token) {
+  const filePath = path.join(getKarajanHome(), CREDENTIALS_FILENAME);
+  let existing = {};
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    existing = JSON.parse(raw);
+  } catch { /* file may not exist */ }
+  existing.token = token;
+  const dir = getKarajanHome();
+  await fs.mkdir(dir, { recursive: true });
+  await fs.writeFile(filePath, JSON.stringify(existing, null, 2), "utf8");
+}

package/src/sonar/project-key.js

@@ -9,7 +9,7 @@ function slug(value) {
     .replaceAll(/(^-+)|(-+$)/g, "");
 }
 
-export function normalizeProjectKey(value) {
+function normalizeProjectKey(value) {
   const out = slug(value);
   if (!out) return "kj-default";
   return /[a-z]/.test(out) ? out : `kj-${out}`;