karajan-code 1.27.0 → 1.28.0

package/package.json

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

package/src/cli.js

@@ -22,6 +22,7 @@ import { discoverCommand } from "./commands/discover.js";
 import { triageCommand } from "./commands/triage.js";
 import { researcherCommand } from "./commands/researcher.js";
 import { architectCommand } from "./commands/architect.js";
+import { auditCommand } from "./commands/audit.js";
 
 const PKG_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../package.json");
 const PKG_VERSION = JSON.parse(readFileSync(PKG_PATH, "utf8")).version;
@@ -253,6 +254,18 @@ program
     });
   });
 
+program
+  .command("audit")
+  .description("Analyze codebase health (read-only)")
+  .argument("[task]")
+  .option("--dimensions <list>", "Comma-separated: security,quality,performance,architecture,testing", "all")
+  .option("--json", "Output raw JSON")
+  .action(async (task, flags) => {
+    await withConfig("audit", flags, async ({ config, logger }) => {
+      await auditCommand({ task: task || "Analyze the full codebase", config, logger, dimensions: flags.dimensions, json: flags.json });
+    });
+  });
+
 program
   .command("resume")
   .description("Resume a paused session")

package/src/commands/audit.js

@@ -0,0 +1,99 @@
+import { createAgent } from "../agents/index.js";
+import { assertAgentsAvailable } from "../agents/availability.js";
+import { resolveRole } from "../config.js";
+import { buildAuditPrompt, parseAuditOutput, AUDIT_DIMENSIONS } from "../prompts/audit.js";
+
+function formatFindings(findings) {
+  const lines = [];
+  for (const f of findings) {
+    const loc = f.file ? `${f.file}${f.line ? `:${f.line}` : ""}` : "";
+    const rule = f.rule ? ` [${f.rule}]` : "";
+    lines.push(`  - [${f.severity.toUpperCase()}] ${loc}${rule}`);
+    lines.push(`    ${f.description}`);
+    if (f.recommendation) lines.push(`    Fix: ${f.recommendation}`);
+  }
+  return lines;
+}
+
+function formatDimension(name, dim) {
+  const lines = [];
+  lines.push(`### ${name} — Score: ${dim.score}`);
+  if (dim.findings.length === 0) {
+    lines.push("  No issues found.");
+  } else {
+    lines.push(...formatFindings(dim.findings));
+  }
+  lines.push("");
+  return lines;
+}
+
+function formatRecommendations(recs) {
+  const lines = ["## Top Recommendations", ""];
+  for (const r of recs) {
+    lines.push(`${r.priority}. [${r.dimension}] ${r.action} (impact: ${r.impact}, effort: ${r.effort})`);
+  }
+  lines.push("");
+  return lines;
+}
+
+const DIMENSION_LABELS = {
+  security: "Security",
+  codeQuality: "Code Quality",
+  performance: "Performance",
+  architecture: "Architecture",
+  testing: "Testing"
+};
+
+function formatAudit(parsed) {
+  const lines = [];
+  lines.push("## Codebase Health Report");
+  lines.push(`**Overall Health:** ${parsed.summary.overallHealth}`);
+  lines.push(`**Total Findings:** ${parsed.summary.totalFindings} (${parsed.summary.critical} critical, ${parsed.summary.high} high, ${parsed.summary.medium} medium, ${parsed.summary.low} low)`);
+  lines.push("");
+
+  for (const dim of AUDIT_DIMENSIONS) {
+    if (parsed.dimensions[dim]) {
+      lines.push(...formatDimension(DIMENSION_LABELS[dim] || dim, parsed.dimensions[dim]));
+    }
+  }
+
+  if (parsed.topRecommendations?.length) {
+    lines.push(...formatRecommendations(parsed.topRecommendations));
+  }
+
+  if (parsed.textSummary) lines.push(`---\n${parsed.textSummary}`);
+  return lines.join("\n");
+}
+
+export async function auditCommand({ task, config, logger, dimensions, json }) {
+  const auditRole = resolveRole(config, "audit");
+  await assertAgentsAvailable([auditRole.provider]);
+  logger.info(`Audit (${auditRole.provider}) starting...`);
+
+  const agent = createAgent(auditRole.provider, config, logger);
+  const dimList = dimensions && dimensions !== "all"
+    ? dimensions.split(",").map(d => d.trim().toLowerCase()).map(d => d === "quality" ? "codeQuality" : d).filter(d => AUDIT_DIMENSIONS.includes(d))
+    : null;
+
+  const prompt = buildAuditPrompt({ task: task || "Analyze the full codebase", dimensions: dimList });
+  const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
+  const result = await agent.runTask({ prompt, onOutput, role: "audit" });
+
+  if (!result.ok) {
+    throw new Error(result.error || result.output || "Audit failed");
+  }
+
+  const parsed = parseAuditOutput(result.output);
+
+  if (json) {
+    console.log(JSON.stringify(parsed || result.output, null, 2));
+    return;
+  }
+
+  if (parsed?.summary) {
+    console.log(formatAudit(parsed));
+  } else {
+    console.log(result.output);
+  }
+  logger.info("Audit completed.");
+}

package/src/config.js

@@ -414,7 +414,7 @@ export function resolveRole(config, role) {
   let provider = roleConfig.provider ?? null;
   if (!provider && role === "coder") provider = legacyCoder;
   if (!provider && role === "reviewer") provider = legacyReviewer;
-  if (!provider && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "impeccable" || role === "triage" || role === "discover" || role === "architect")) {
+  if (!provider && (role === "planner" || role === "refactorer" || role === "solomon" || role === "researcher" || role === "tester" || role === "security" || role === "impeccable" || role === "triage" || role === "discover" || role === "architect" || role === "audit")) {
     provider = roles.coder?.provider || legacyCoder;
   }
 

package/src/mcp/run-kj.js

@@ -76,11 +76,14 @@ export async function runKjCommand({ command, commandArgs = [], options = {}, en
 
   const timeout = options.timeoutMs ? Number(options.timeoutMs) : undefined;
 
-  const result = await execa("node", args, {
+  const execOpts = {
     env: runEnv,
     reject: false,
     timeout
-  });
+  };
+  if (options.projectDir) execOpts.cwd = options.projectDir;
+
+  const result = await execa("node", args, execOpts);
 
   const ok = result.exitCode === 0;
   const payload = {

package/src/mcp/server-handlers.js

@@ -25,20 +25,37 @@ import { currentBranch } from "../utils/git.js";
 import { isPreflightAcked, ackPreflight, getSessionOverrides } from "./preflight.js";
 
 /**
- * Resolve the user's project directory via MCP roots.
- * Falls back to process.cwd() if roots are not available.
+ * Resolve the user's project directory.
+ * Priority: 1) explicit projectDir param, 2) MCP roots, 3) error with instructions.
  */
-async function resolveProjectDir(server) {
+async function resolveProjectDir(server, explicitProjectDir) {
+  // 1. Explicit projectDir from tool parameter — always wins
+  if (explicitProjectDir) return explicitProjectDir;
+
+  // 2. MCP roots (host-provided workspace directory)
   try {
     const { roots } = await server.listRoots();
     if (roots?.length > 0) {
       const uri = roots[0].uri;
-      // MCP roots use file:// URIs
       if (uri.startsWith("file://")) return new URL(uri).pathname;
       return uri;
     }
   } catch { /* client may not support roots */ }
-  return process.cwd();
+
+  // 3. Check if process.cwd() looks like a real project (has package.json or .git)
+  const cwd = process.cwd();
+  try {
+    const hasGit = await fs.access(`${cwd}/.git`).then(() => true).catch(() => false);
+    const hasPkg = await fs.access(`${cwd}/package.json`).then(() => true).catch(() => false);
+    if (hasGit || hasPkg) return cwd;
+  } catch { /* ignore */ }
+
+  // 4. No valid project directory — fail with clear instructions
+  throw new Error(
+    `Cannot determine project directory. The MCP server is running from "${cwd}" which does not appear to be your project. ` +
+    `Fix: pass the "projectDir" parameter with the absolute path to your project (e.g., projectDir: "/home/user/my-project"), ` +
+    `or run "kj init" inside your project directory.`
+  );
 }
 
 export function asObject(value) {
@@ -260,7 +277,7 @@ export async function handleRunDirect(a, server, extra) {
   if (config.pipeline?.security?.enabled) requiredProviders.push(resolveRole(config, "security").provider);
   await assertAgentsAvailable(requiredProviders);
 
-  const projectDir = await resolveProjectDir(server);
+  const projectDir = await resolveProjectDir(server, a.projectDir);
   const runLog = createRunLog(projectDir);
   runLog.logText(`[kj_run] started — task="${a.task.slice(0, 80)}..."`);
 
@@ -293,7 +310,7 @@ export async function handleResumeDirect(a, server, extra) {
   const config = await buildConfig(a);
   const logger = createLogger(config.output.log_level, "mcp");
 
-  const projectDir = await resolveProjectDir(server);
+  const projectDir = await resolveProjectDir(server, a.projectDir);
   const runLog = createRunLog(projectDir);
   runLog.logText(`[kj_resume] started — session="${a.sessionId}"`);
 
@@ -349,7 +366,7 @@ export async function handlePlanDirect(a, server, extra) {
   const plannerRole = resolveRole(config, "planner");
   await assertAgentsAvailable([plannerRole.provider]);
 
-  const projectDir = await resolveProjectDir(server);
+  const projectDir = await resolveProjectDir(server, a.projectDir);
   const runLog = createRunLog(projectDir);
   const silenceTimeoutMs = Number(config?.session?.max_agent_silence_minutes) > 0
     ? Math.round(Number(config.session.max_agent_silence_minutes) * 60 * 1000)
@@ -416,7 +433,7 @@ export async function handleCodeDirect(a, server, extra) {
   const coderRole = resolveRole(config, "coder");
   await assertAgentsAvailable([coderRole.provider]);
 
-  const projectDir = await resolveProjectDir(server);
+  const projectDir = await resolveProjectDir(server, a.projectDir);
   const runLog = createRunLog(projectDir);
   runLog.logText(`[kj_code] started — provider=${coderRole.provider}`);
   const emitter = buildDirectEmitter(server, runLog, extra);
@@ -465,7 +482,7 @@ export async function handleReviewDirect(a, server, extra) {
   const reviewerRole = resolveRole(config, "reviewer");
   await assertAgentsAvailable([reviewerRole.provider, config.reviewer_options?.fallback_reviewer]);
 
-  const projectDir = await resolveProjectDir(server);
+  const projectDir = await resolveProjectDir(server, a.projectDir);
   const runLog = createRunLog(projectDir);
   runLog.logText(`[kj_review] started — provider=${reviewerRole.provider}`);
   const emitter = buildDirectEmitter(server, runLog, extra);
@@ -512,7 +529,7 @@ export async function handleDiscoverDirect(a, server, extra) {
   const discoverRole = resolveRole(config, "discover");
   await assertAgentsAvailable([discoverRole.provider]);
 
-  const projectDir = await resolveProjectDir(server);
+  const projectDir = await resolveProjectDir(server, a.projectDir);
   const runLog = createRunLog(projectDir);
   runLog.logText(`[kj_discover] started — mode=${a.mode || "gaps"}`);
   const emitter = buildDirectEmitter(server, runLog, extra);
@@ -565,7 +582,7 @@ export async function handleTriageDirect(a, server, extra) {
   const triageRole = resolveRole(config, "triage");
   await assertAgentsAvailable([triageRole.provider]);
 
-  const projectDir = await resolveProjectDir(server);
+  const projectDir = await resolveProjectDir(server, a.projectDir);
   const runLog = createRunLog(projectDir);
   runLog.logText(`[kj_triage] started`);
   const emitter = buildDirectEmitter(server, runLog, extra);
@@ -609,7 +626,7 @@ export async function handleResearcherDirect(a, server, extra) {
   const researcherRole = resolveRole(config, "researcher");
   await assertAgentsAvailable([researcherRole.provider]);
 
-  const projectDir = await resolveProjectDir(server);
+  const projectDir = await resolveProjectDir(server, a.projectDir);
   const runLog = createRunLog(projectDir);
   runLog.logText(`[kj_researcher] started`);
   const emitter = buildDirectEmitter(server, runLog, extra);
@@ -646,6 +663,54 @@ export async function handleResearcherDirect(a, server, extra) {
   return { ok: true, ...result.result, summary: result.summary };
 }
 
+export async function handleAuditDirect(a, server, extra) {
+  const config = await buildConfig(a, "audit");
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const auditRole = resolveRole(config, "audit");
+  await assertAgentsAvailable([auditRole.provider]);
+
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  const runLog = createRunLog(projectDir);
+  runLog.logText(`[kj_audit] started — dimensions=${a.dimensions || "all"}`);
+  const emitter = buildDirectEmitter(server, runLog, extra);
+  const eventBase = { sessionId: null, iteration: 0, startedAt: Date.now() };
+  const onOutput = ({ stream, line }) => {
+    emitter.emit("progress", { type: "agent:output", stage: "audit", message: line, detail: { stream, agent: auditRole.provider } });
+  };
+  const stallDetector = createStallDetector({
+    onOutput, emitter, eventBase, stage: "audit", provider: auditRole.provider
+  });
+
+  const { AuditRole } = await import("../roles/audit-role.js");
+  const audit = new AuditRole({ config, logger, emitter });
+  await audit.init({ task: a.task || "Analyze the full codebase" });
+
+  sendTrackerLog(server, "audit", "running", auditRole.provider);
+  runLog.logText(`[audit] agent launched, waiting for response...`);
+  let result;
+  try {
+    result = await audit.run({
+      task: a.task || "Analyze the full codebase",
+      dimensions: a.dimensions || null,
+      onOutput: stallDetector.onOutput
+    });
+  } finally {
+    stallDetector.stop();
+    const stats = stallDetector.stats();
+    runLog.logText(`[audit] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
+    runLog.close();
+  }
+
+  if (!result.ok) {
+    sendTrackerLog(server, "audit", "failed");
+    throw new Error(result.result?.error || result.summary || "Audit failed");
+  }
+
+  sendTrackerLog(server, "audit", "done");
+  return { ok: true, ...result.result, summary: result.summary };
+}
+
 export async function handleArchitectDirect(a, server, extra) {
   const config = await buildConfig(a, "architect");
   const logger = createLogger(config.output.log_level, "mcp");
@@ -653,7 +718,7 @@ export async function handleArchitectDirect(a, server, extra) {
   const architectRole = resolveRole(config, "architect");
   await assertAgentsAvailable([architectRole.provider]);
 
-  const projectDir = await resolveProjectDir(server);
+  const projectDir = await resolveProjectDir(server, a.projectDir);
   const runLog = createRunLog(projectDir);
   runLog.logText(`[kj_architect] started`);
   const emitter = buildDirectEmitter(server, runLog, extra);
@@ -780,7 +845,7 @@ function buildReportArgs(a) {
 
 async function handleStatus(a, server) {
   const maxLines = a.lines || 50;
-  const projectDir = await resolveProjectDir(server);
+  const projectDir = await resolveProjectDir(server, a.projectDir);
   return readRunLog(projectDir, maxLines);
 }
 
@@ -938,6 +1003,10 @@ async function handleArchitect(a, server, extra) {
   return handleArchitectDirect(a, server, extra);
 }
 
+async function handleAudit(a, server, extra) {
+  return handleAuditDirect(a, server, extra);
+}
+
 /* ── Handler dispatch map ─────────────────────────────────────────── */
 
 const toolHandlers = {
@@ -958,7 +1027,8 @@ const toolHandlers = {
   kj_discover:    (a, server, extra) => handleDiscover(a, server, extra),
   kj_triage:      (a, server, extra) => handleTriage(a, server, extra),
   kj_researcher:  (a, server, extra) => handleResearcher(a, server, extra),
-  kj_architect:   (a, server, extra) => handleArchitect(a, server, extra)
+  kj_architect:   (a, server, extra) => handleArchitect(a, server, extra),
+  kj_audit:       (a, server, extra) => handleAudit(a, server, extra)
 };
 
 export async function handleToolCall(name, args, server, extra) {

package/src/mcp/tools.js

@@ -53,6 +53,7 @@ export const tools = [
       required: ["task"],
       properties: {
         task: { type: "string", description: "Task description for the coder (can include a Planning Game card ID like KJC-TSK-0042)" },
+        projectDir: { type: "string", description: "Absolute path to the project directory. Required when KJ MCP server runs from a different directory than the target project." },
         pgTask: { type: "string", description: "Planning Game card ID (e.g., KJC-TSK-0042). If provided, fetches full card details as task context and updates card status on completion." },
         pgProject: { type: "string", description: "Planning Game project ID (e.g., 'Karajan Code'). Required when pgTask is used." },
         planner: { type: "string" },
@@ -112,6 +113,7 @@ export const tools = [
       properties: {
         sessionId: { type: "string", description: "Session ID to resume" },
         answer: { type: "string", description: "Answer to the question that caused the pause" },
+        projectDir: { type: "string", description: "Absolute path to the project directory" },
         kjHome: { type: "string" }
       }
     }
@@ -185,6 +187,7 @@ export const tools = [
         task: { type: "string" },
         coder: { type: "string" },
         coderModel: { type: "string" },
+        projectDir: { type: "string", description: "Absolute path to the project directory" },
         kjHome: { type: "string" }
       }
     }
@@ -200,6 +203,7 @@ export const tools = [
         reviewer: { type: "string" },
         reviewerModel: { type: "string" },
         baseRef: { type: "string" },
+        projectDir: { type: "string", description: "Absolute path to the project directory" },
         kjHome: { type: "string" }
       }
     }
@@ -226,6 +230,7 @@ export const tools = [
         plannerModel: { type: "string" },
         coder: { type: "string", description: "Legacy alias for planner" },
         coderModel: { type: "string", description: "Legacy alias for plannerModel" },
+        projectDir: { type: "string", description: "Absolute path to the project directory" },
         kjHome: { type: "string" }
       }
     }
@@ -242,6 +247,7 @@ export const tools = [
         context: { type: "string", description: "Additional context for the analysis (e.g., research output)" },
         pgTask: { type: "string", description: "Planning Game card ID (e.g., KJC-TSK-0042). If provided, fetches full card details as additional context." },
         pgProject: { type: "string", description: "Planning Game project ID. Required when pgTask is used." },
+        projectDir: { type: "string", description: "Absolute path to the project directory" },
         kjHome: { type: "string" }
       }
     }
@@ -254,6 +260,7 @@ export const tools = [
       required: ["task"],
       properties: {
         task: { type: "string", description: "Task description to classify" },
+        projectDir: { type: "string", description: "Absolute path to the project directory" },
         kjHome: { type: "string" }
       }
     }
@@ -266,6 +273,7 @@ export const tools = [
       required: ["task"],
       properties: {
         task: { type: "string", description: "Task description to research" },
+        projectDir: { type: "string", description: "Absolute path to the project directory" },
         kjHome: { type: "string" }
       }
     }
@@ -279,6 +287,19 @@ export const tools = [
       properties: {
         task: { type: "string", description: "Task description to architect" },
         context: { type: "string", description: "Additional context (e.g., researcher output)" },
+        projectDir: { type: "string", description: "Absolute path to the project directory" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_audit",
+    description: "Analyze codebase health without modifying files. Returns findings across security, code quality, performance, architecture, and testing dimensions.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectDir: { type: "string", description: "Absolute path to the project to audit" },
+        dimensions: { type: "string", description: "Comma-separated dimensions to analyze: security,codeQuality,performance,architecture,testing (default: all)" },
         kjHome: { type: "string" }
       }
     }

package/src/prompts/audit.js

@@ -0,0 +1,210 @@
+const SUBAGENT_PREAMBLE = [
+  "IMPORTANT: You are running as a Karajan sub-agent.",
+  "Do NOT ask about using Karajan, do NOT mention Karajan, do NOT suggest orchestration.",
+  "Do NOT use any MCP tools. Focus only on auditing the codebase for health, quality, and risks.",
+  "DO NOT modify any files — this is a read-only analysis. Only use: Read, Grep, Glob, Bash (for analysis commands like wc, find, git log, du, npm ls)."
+].join(" ");
+
+export const AUDIT_DIMENSIONS = ["security", "codeQuality", "performance", "architecture", "testing"];
+
+const VALID_HEALTH = new Set(["good", "fair", "poor", "critical"]);
+const VALID_SCORES = new Set(["A", "B", "C", "D", "F"]);
+const VALID_SEVERITIES = new Set(["critical", "high", "medium", "low"]);
+const VALID_IMPACT = new Set(["high", "medium", "low"]);
+
+export function buildAuditPrompt({ task, instructions, dimensions = null, context = null }) {
+  const sections = [SUBAGENT_PREAMBLE];
+
+  if (instructions) {
+    sections.push(instructions);
+  }
+
+  sections.push(
+    "You are a codebase auditor for Karajan Code, a multi-agent coding orchestrator.",
+    "Analyze the project across multiple dimensions and produce a comprehensive health report.",
+    "DO NOT modify any files. This is a READ-ONLY analysis."
+  );
+
+  const activeDimensions = dimensions
+    ? dimensions.filter(d => AUDIT_DIMENSIONS.includes(d))
+    : AUDIT_DIMENSIONS;
+
+  if (activeDimensions.includes("security")) {
+    sections.push(
+      "## Security Analysis",
+      [
+        "- Hardcoded secrets, API keys, tokens in source code",
+        "- SQL/NoSQL injection vectors",
+        "- XSS vulnerabilities (innerHTML, dangerouslySetInnerHTML, eval)",
+        "- Command injection (exec, spawn with user input)",
+        "- Insecure dependencies (check package.json for known vulnerable packages)",
+        "- Missing input validation at system boundaries",
+        "- Authentication/authorization gaps"
+      ].join("\n")
+    );
+  }
+
+  if (activeDimensions.includes("codeQuality")) {
+    sections.push(
+      "## Code Quality Analysis (SOLID, DRY, KISS, YAGNI)",
+      [
+        "- Functions/methods longer than 50 lines",
+        "- Files longer than 500 lines",
+        "- Duplicated code blocks (same logic in multiple places)",
+        "- God classes/modules (too many responsibilities)",
+        "- Deep nesting (>4 levels)",
+        "- Dead code (unused exports, unreachable branches)",
+        "- Missing error handling (uncaught promises, empty catches)",
+        "- Over-engineering (abstractions for single use)"
+      ].join("\n")
+    );
+  }
+
+  if (activeDimensions.includes("performance")) {
+    sections.push(
+      "## Performance Analysis",
+      [
+        "- N+1 query patterns",
+        "- Synchronous file I/O in request handlers",
+        "- Missing pagination on list endpoints",
+        "- Large bundle imports (importing entire libraries for one function)",
+        "- Missing lazy loading",
+        "- Expensive operations in loops",
+        "- Missing caching opportunities"
+      ].join("\n")
+    );
+  }
+
+  if (activeDimensions.includes("architecture")) {
+    sections.push(
+      "## Architecture Analysis",
+      [
+        "- Circular dependencies",
+        "- Layer violations (UI importing from data layer directly)",
+        "- Coupling between modules (shared mutable state)",
+        "- Missing dependency injection",
+        "- Inconsistent patterns across the codebase",
+        "- Missing or outdated documentation",
+        "- Configuration scattered vs centralized"
+      ].join("\n")
+    );
+  }
+
+  if (activeDimensions.includes("testing")) {
+    sections.push(
+      "## Testing Analysis",
+      [
+        "- Test coverage gaps (source files without corresponding tests)",
+        "- Test quality (assertions per test, meaningful test names)",
+        "- Missing edge case coverage",
+        "- Test isolation (shared state between tests)",
+        "- Flaky test indicators (timeouts, sleep, retries)"
+      ].join("\n")
+    );
+  }
+
+  sections.push(
+    "Return a single valid JSON object and nothing else.",
+    'JSON schema: {"ok":true,"result":{"summary":{"overallHealth":"good|fair|poor|critical","totalFindings":number,"critical":number,"high":number,"medium":number,"low":number},"dimensions":{"security":{"score":"A|B|C|D|F","findings":[]},"codeQuality":{"score":"A|B|C|D|F","findings":[]},"performance":{"score":"A|B|C|D|F","findings":[]},"architecture":{"score":"A|B|C|D|F","findings":[]},"testing":{"score":"A|B|C|D|F","findings":[]}},"topRecommendations":[{"priority":number,"dimension":string,"action":string,"impact":"high|medium|low","effort":"high|medium|low"}]},"summary":string}',
+    'Each finding: {"severity":"critical|high|medium|low","file":string,"line":number,"rule":string,"description":string,"recommendation":string}',
+    `Only include dimensions you were asked to analyze: ${activeDimensions.join(", ")}`
+  );
+
+  if (context) {
+    sections.push(`## Context\n${context}`);
+  }
+
+  sections.push(`## Task\n${task}`);
+
+  return sections.join("\n\n");
+}
+
+function parseFinding(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const severity = String(raw.severity || "").toLowerCase();
+  if (!VALID_SEVERITIES.has(severity)) return null;
+  return {
+    severity,
+    file: raw.file || "",
+    line: typeof raw.line === "number" ? raw.line : 0,
+    rule: raw.rule || "",
+    description: raw.description || "",
+    recommendation: raw.recommendation || ""
+  };
+}
+
+function parseDimension(raw) {
+  if (!raw || typeof raw !== "object") return { score: "F", findings: [] };
+  const score = VALID_SCORES.has(raw.score) ? raw.score : "F";
+  const findings = (Array.isArray(raw.findings) ? raw.findings : [])
+    .map(parseFinding)
+    .filter(Boolean);
+  return { score, findings };
+}
+
+function parseRecommendation(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  return {
+    priority: typeof raw.priority === "number" ? raw.priority : 99,
+    dimension: raw.dimension || "",
+    action: raw.action || "",
+    impact: VALID_IMPACT.has(raw.impact) ? raw.impact : "medium",
+    effort: VALID_IMPACT.has(raw.effort) ? raw.effort : "medium"
+  };
+}
+
+export function parseAuditOutput(raw) {
+  const text = raw?.trim() || "";
+  const jsonMatch = /\{[\s\S]*\}/.exec(text);
+  if (!jsonMatch) return null;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonMatch[0]);
+  } catch {
+    return null;
+  }
+
+  // Handle both wrapped (result.summary) and flat structures
+  const resultObj = parsed.result || parsed;
+  const summaryObj = resultObj.summary || {};
+
+  const overallHealth = VALID_HEALTH.has(summaryObj.overallHealth)
+    ? summaryObj.overallHealth
+    : "poor";
+
+  const dims = resultObj.dimensions || {};
+  const dimensions = {};
+  for (const d of AUDIT_DIMENSIONS) {
+    dimensions[d] = parseDimension(dims[d]);
+  }
+
+  const totalFindings = Object.values(dimensions)
+    .reduce((sum, d) => sum + d.findings.length, 0);
+
+  const bySeverity = { critical: 0, high: 0, medium: 0, low: 0 };
+  for (const d of Object.values(dimensions)) {
+    for (const f of d.findings) {
+      bySeverity[f.severity] = (bySeverity[f.severity] || 0) + 1;
+    }
+  }
+
+  const topRecommendations = (Array.isArray(resultObj.topRecommendations) ? resultObj.topRecommendations : [])
+    .map(parseRecommendation)
+    .filter(Boolean)
+    .sort((a, b) => a.priority - b.priority);
+
+  return {
+    summary: {
+      overallHealth,
+      totalFindings,
+      critical: bySeverity.critical,
+      high: bySeverity.high,
+      medium: bySeverity.medium,
+      low: bySeverity.low
+    },
+    dimensions,
+    topRecommendations,
+    textSummary: parsed.summary || resultObj.textSummary || ""
+  };
+}

package/src/roles/audit-role.js

@@ -0,0 +1,105 @@
+import { BaseRole } from "./base-role.js";
+import { createAgent as defaultCreateAgent } from "../agents/index.js";
+import { buildAuditPrompt, parseAuditOutput, AUDIT_DIMENSIONS } from "../prompts/audit.js";
+
+function resolveProvider(config) {
+  return (
+    config?.roles?.audit?.provider ||
+    config?.roles?.coder?.provider ||
+    "claude"
+  );
+}
+
+function buildSummary(parsed) {
+  const { summary } = parsed;
+  const parts = [];
+  if (summary.critical > 0) parts.push(`${summary.critical} critical`);
+  if (summary.high > 0) parts.push(`${summary.high} high`);
+  if (summary.medium > 0) parts.push(`${summary.medium} medium`);
+  if (summary.low > 0) parts.push(`${summary.low} low`);
+
+  const findingsStr = parts.length > 0 ? parts.join(", ") : "no issues";
+  return `Overall health: ${summary.overallHealth}. ${summary.totalFindings} findings (${findingsStr})`;
+}
+
+function resolveInput(input, context) {
+  if (typeof input === "string") {
+    return { task: input, onOutput: null, dimensions: null, context: null };
+  }
+  return {
+    task: input?.task || context?.task || "",
+    onOutput: input?.onOutput || null,
+    dimensions: input?.dimensions || null,
+    context: input?.context || null
+  };
+}
+
+function parseDimensions(dimensionsStr) {
+  if (!dimensionsStr || dimensionsStr === "all") return null;
+  const requested = dimensionsStr.split(",").map(d => d.trim().toLowerCase());
+  // Map "quality" shorthand to "codeQuality"
+  const mapped = requested.map(d => d === "quality" ? "codeQuality" : d);
+  const valid = mapped.filter(d => AUDIT_DIMENSIONS.includes(d));
+  return valid.length > 0 ? valid : null;
+}
+
+export class AuditRole extends BaseRole {
+  constructor({ config, logger, emitter = null, createAgentFn = null }) {
+    super({ name: "audit", config, logger, emitter });
+    this._createAgent = createAgentFn || defaultCreateAgent;
+  }
+
+  async execute(input) {
+    const { task, onOutput, dimensions: rawDimensions, context } = resolveInput(input, this.context);
+    const dimensions = typeof rawDimensions === "string"
+      ? parseDimensions(rawDimensions)
+      : rawDimensions;
+    const provider = resolveProvider(this.config);
+    const agent = this._createAgent(provider, this.config, this.logger);
+
+    const prompt = buildAuditPrompt({ task, instructions: this.instructions, dimensions, context });
+    const runArgs = { prompt, role: "audit" };
+    if (onOutput) runArgs.onOutput = onOutput;
+    const result = await agent.runTask(runArgs);
+
+    if (!result.ok) {
+      return {
+        ok: false,
+        result: { error: result.error || result.output || "Audit failed", provider },
+        summary: `Audit failed: ${result.error || "unknown error"}`,
+        usage: result.usage
+      };
+    }
+
+    try {
+      const parsed = parseAuditOutput(result.output);
+      if (!parsed) {
+        return {
+          ok: true,
+          result: { raw: result.output, provider },
+          summary: "Audit complete (unstructured output)",
+          usage: result.usage
+        };
+      }
+
+      return {
+        ok: true,
+        result: {
+          summary: parsed.summary,
+          dimensions: parsed.dimensions,
+          topRecommendations: parsed.topRecommendations,
+          provider
+        },
+        summary: buildSummary(parsed),
+        usage: result.usage
+      };
+    } catch {
+      return {
+        ok: true,
+        result: { raw: result.output, provider },
+        summary: "Audit complete (unstructured output)",
+        usage: result.usage
+      };
+    }
+  }
+}

package/src/roles/index.js

@@ -12,3 +12,4 @@ export { SecurityRole } from "./security-role.js";
 export { SolomonRole } from "./solomon-role.js";
 export { DiscoverRole } from "./discover-role.js";
 export { ArchitectRole } from "./architect-role.js";
+export { AuditRole } from "./audit-role.js";

package/templates/roles/audit.md

@@ -0,0 +1,68 @@
+# Audit Role
+
+You are the **Codebase Auditor**. Analyze the project for health, quality, and risks. DO NOT modify any files — this is a read-only analysis.
+
+## Tools allowed
+ONLY use: Read, Grep, Glob, Bash (for analysis commands only — `wc`, `find`, `git log`, `du`, `npm ls`). DO NOT use Edit or Write.
+
+## Analysis dimensions
+
+### 1. Security
+- Hardcoded secrets, API keys, tokens in source code
+- SQL/NoSQL injection vectors
+- XSS vulnerabilities (innerHTML, dangerouslySetInnerHTML, eval)
+- Command injection (exec, spawn with user input)
+- Insecure dependencies (check package.json for known vulnerable packages)
+- Missing input validation at system boundaries
+- Authentication/authorization gaps
+
+### 2. Code Quality (SOLID, DRY, KISS, YAGNI)
+- Functions/methods longer than 50 lines
+- Files longer than 500 lines
+- Duplicated code blocks (same logic in multiple places)
+- God classes/modules (too many responsibilities)
+- Deep nesting (>4 levels)
+- Dead code (unused exports, unreachable branches)
+- Missing error handling (uncaught promises, empty catches)
+- Over-engineering (abstractions for single use)
+
+### 3. Performance
+- N+1 query patterns
+- Synchronous file I/O in request handlers
+- Missing pagination on list endpoints
+- Large bundle imports (importing entire libraries for one function)
+- Missing lazy loading
+- Expensive operations in loops
+- Missing caching opportunities
+
+### 4. Architecture
+- Circular dependencies
+- Layer violations (UI importing from data layer directly)
+- Coupling between modules (shared mutable state)
+- Missing dependency injection
+- Inconsistent patterns across the codebase
+- Missing or outdated documentation
+- Configuration scattered vs centralized
+
+### 5. Testing
+- Test coverage gaps (source files without corresponding tests)
+- Test quality (assertions per test, meaningful test names)
+- Missing edge case coverage
+- Test isolation (shared state between tests)
+- Flaky test indicators (timeouts, sleep, retries)
+
+## Task
+
+{{task}}
+
+## Context
+
+{{context}}
+
+## Output format
+
+Return a single valid JSON object and nothing else.
+
+JSON schema: {"ok":true,"result":{"summary":{"overallHealth":"good|fair|poor|critical","totalFindings":number,"critical":number,"high":number,"medium":number,"low":number},"dimensions":{"security":{"score":"A|B|C|D|F","findings":[]},"codeQuality":{"score":"A|B|C|D|F","findings":[]},"performance":{"score":"A|B|C|D|F","findings":[]},"architecture":{"score":"A|B|C|D|F","findings":[]},"testing":{"score":"A|B|C|D|F","findings":[]}},"topRecommendations":[{"priority":number,"dimension":string,"action":string,"impact":"high|medium|low","effort":"high|medium|low"}]},"summary":string}
+
+Each finding: {"severity":"critical|high|medium|low","file":string,"line":number,"rule":string,"description":string,"recommendation":string}

package/templates/skills/kj-audit.md

@@ -0,0 +1,63 @@
+# kj-audit — Codebase Health Audit
+
+Analyze the current codebase for security, code quality, performance, architecture, and testing issues. This is a READ-ONLY analysis — do not modify any files.
+
+## Your task
+
+$ARGUMENTS
+
+## Dimensions to analyze
+
+### 1. Security
+- Hardcoded secrets, API keys, tokens in source code
+- SQL/NoSQL injection vectors (string concatenation in queries)
+- XSS vulnerabilities (innerHTML, dangerouslySetInnerHTML, eval)
+- Command injection (exec, spawn with user input)
+- Insecure dependencies (check package.json for known vulnerable packages)
+- Missing input validation at system boundaries
+- Authentication/authorization gaps
+
+### 2. Code Quality (SOLID, DRY, KISS, YAGNI)
+- Functions/methods longer than 50 lines
+- Files longer than 500 lines
+- Duplicated code blocks (same logic in multiple places)
+- God classes/modules (too many responsibilities)
+- Deep nesting (>4 levels)
+- Dead code (unused exports, unreachable branches)
+- Missing error handling (uncaught promises, empty catches)
+- Over-engineering (abstractions for single use)
+
+### 3. Performance
+- N+1 query patterns
+- Synchronous file I/O in request handlers
+- Missing pagination on list endpoints
+- Large bundle imports (importing entire libraries for one function)
+- Missing lazy loading
+- Expensive operations in loops
+- Missing caching opportunities
+
+### 4. Architecture
+- Circular dependencies
+- Layer violations (UI importing from data layer directly)
+- Coupling between modules (shared mutable state)
+- Missing dependency injection
+- Inconsistent patterns across the codebase
+- Missing or outdated documentation
+- Configuration scattered vs centralized
+
+### 5. Testing
+- Test coverage gaps (source files without corresponding tests)
+- Test quality (assertions per test, meaningful test names)
+- Missing edge case coverage
+- Test isolation (shared state between tests)
+- Flaky test indicators (timeouts, sleep, retries)
+
+## Output
+
+For each dimension, provide:
+- **Score**: A (excellent) to F (failing)
+- **Findings**: severity, file, line, rule, description, recommendation
+
+End with:
+- **Overall Health**: good / fair / poor / critical
+- **Top Recommendations**: prioritized list of actions with impact and effort estimates