karajan-code 1.19.0 → 1.21.0

package/package.json

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

package/src/cli.js

@@ -18,6 +18,10 @@ import { resumeCommand } from "./commands/resume.js";
 import { sonarCommand, sonarOpenCommand } from "./commands/sonar.js";
 import { rolesCommand } from "./commands/roles.js";
 import { agentsCommand } from "./commands/agents.js";
+import { discoverCommand } from "./commands/discover.js";
+import { triageCommand } from "./commands/triage.js";
+import { researcherCommand } from "./commands/researcher.js";
+import { architectCommand } from "./commands/architect.js";
 
 const PKG_PATH = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../package.json");
 const PKG_VERSION = JSON.parse(readFileSync(PKG_PATH, "utf8")).version;
@@ -93,6 +97,8 @@ program
   .option("--methodology <name>")
   .option("--no-auto-rebase")
   .option("--no-sonar")
+  .option("--enable-sonarcloud", "Enable SonarCloud scan (complementary to SonarQube)")
+  .option("--no-sonarcloud")
   .option("--checkpoint-interval <n>", "Minutes between interactive checkpoints (default: 5)")
   .option("--pg-task <cardId>", "Planning Game card ID (e.g., KJC-TSK-0042)")
   .option("--pg-project <projectId>", "Planning Game project ID")
@@ -191,6 +197,59 @@ program
     });
   });
 
+program
+  .command("discover")
+  .description("Analyze task for gaps, ambiguities and missing info")
+  .argument("<task>")
+  .option("--mode <name>", "Discovery mode: gaps|momtest|wendel|classify|jtbd", "gaps")
+  .option("--discover <name>", "Override discover agent")
+  .option("--discover-model <name>", "Override discover model")
+  .option("--json", "Output raw JSON")
+  .action(async (task, flags) => {
+    await withConfig("discover", flags, async ({ config, logger }) => {
+      await discoverCommand({ task, config, logger, mode: flags.mode, json: flags.json });
+    });
+  });
+
+program
+  .command("triage")
+  .description("Classify task complexity and recommend pipeline roles")
+  .argument("<task>")
+  .option("--triage <name>", "Override triage agent")
+  .option("--triage-model <name>", "Override triage model")
+  .option("--json", "Output raw JSON")
+  .action(async (task, flags) => {
+    await withConfig("triage", flags, async ({ config, logger }) => {
+      await triageCommand({ task, config, logger, json: flags.json });
+    });
+  });
+
+program
+  .command("researcher")
+  .description("Research codebase for a task (files, patterns, constraints)")
+  .argument("<task>")
+  .option("--researcher <name>", "Override researcher agent")
+  .option("--researcher-model <name>", "Override researcher model")
+  .action(async (task, flags) => {
+    await withConfig("researcher", flags, async ({ config, logger }) => {
+      await researcherCommand({ task, config, logger });
+    });
+  });
+
+program
+  .command("architect")
+  .description("Design solution architecture (layers, patterns, contracts)")
+  .argument("<task>")
+  .option("--architect <name>", "Override architect agent")
+  .option("--architect-model <name>", "Override architect model")
+  .option("--context <text>", "Additional context (e.g. researcher output)")
+  .option("--json", "Output raw JSON")
+  .action(async (task, flags) => {
+    await withConfig("architect", flags, async ({ config, logger }) => {
+      await architectCommand({ task, config, logger, context: flags.context, json: flags.json });
+    });
+  });
+
 program
   .command("resume")
   .description("Resume a paused session")

package/src/commands/architect.js

@@ -0,0 +1,90 @@
+import { createAgent } from "../agents/index.js";
+import { assertAgentsAvailable } from "../agents/availability.js";
+import { resolveRole } from "../config.js";
+import { buildArchitectPrompt, parseArchitectOutput } from "../prompts/architect.js";
+
+function formatArchitect(result) {
+  const lines = [];
+  lines.push(`## Architecture Design`);
+  lines.push(`**Verdict:** ${result.verdict || "unknown"}`, "");
+
+  const arch = result.architecture;
+  if (arch) {
+    if (arch.type) lines.push(`**Type:** ${arch.type}`, "");
+
+    if (arch.layers?.length) {
+      lines.push("### Layers");
+      for (const l of arch.layers) {
+        if (typeof l === "string") {
+          lines.push(`- ${l}`);
+        } else {
+          lines.push(`- **${l.name}**: ${l.responsibility || ""}`);
+        }
+      }
+      lines.push("");
+    }
+
+    if (arch.patterns?.length) {
+      lines.push("### Patterns");
+      for (const p of arch.patterns) lines.push(`- ${p}`);
+      lines.push("");
+    }
+
+    if (arch.tradeoffs?.length) {
+      lines.push("### Tradeoffs");
+      for (const t of arch.tradeoffs) {
+        lines.push(`- **${t.decision}**: ${t.rationale || ""}`);
+        if (t.alternatives?.length) lines.push(`  Alternatives: ${t.alternatives.join(", ")}`);
+      }
+      lines.push("");
+    }
+
+    if (arch.apiContracts?.length) {
+      lines.push("### API Contracts");
+      for (const c of arch.apiContracts) {
+        lines.push(`- \`${c.method || "GET"} ${c.endpoint}\``);
+      }
+      lines.push("");
+    }
+  }
+
+  if (result.questions?.length) {
+    lines.push("### Clarification Questions");
+    for (const q of result.questions) {
+      lines.push(`- ${q.question || q}`);
+    }
+    lines.push("");
+  }
+
+  if (result.summary) lines.push(`---\n${result.summary}`);
+  return lines.join("\n");
+}
+
+export async function architectCommand({ task, config, logger, context, json }) {
+  const architectRole = resolveRole(config, "architect");
+  await assertAgentsAvailable([architectRole.provider]);
+  logger.info(`Architect (${architectRole.provider}) starting...`);
+
+  const agent = createAgent(architectRole.provider, config, logger);
+  const prompt = buildArchitectPrompt({ task, researchContext: context });
+  const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
+  const result = await agent.runTask({ prompt, onOutput, role: "architect" });
+
+  if (!result.ok) {
+    throw new Error(result.error || result.output || "Architect failed");
+  }
+
+  const parsed = parseArchitectOutput(result.output);
+
+  if (json) {
+    console.log(JSON.stringify(parsed || result.output, null, 2));
+    return;
+  }
+
+  if (parsed?.verdict) {
+    console.log(formatArchitect(parsed));
+  } else {
+    console.log(result.output);
+  }
+  logger.info("Architect completed.");
+}

package/src/commands/discover.js

@@ -0,0 +1,87 @@
+import { createAgent } from "../agents/index.js";
+import { assertAgentsAvailable } from "../agents/availability.js";
+import { resolveRole } from "../config.js";
+import { buildDiscoverPrompt, parseDiscoverOutput } from "../prompts/discover.js";
+import { parseMaybeJsonString } from "../review/parser.js";
+
+function formatDiscover(result, mode) {
+  const lines = [];
+  lines.push(`## Discovery (${mode})`);
+  lines.push(`**Verdict:** ${result.verdict || "unknown"}`, "");
+
+  if (result.gaps?.length) {
+    lines.push("## Gaps");
+    for (const g of result.gaps) {
+      const sev = g.severity ? ` [${g.severity}]` : "";
+      lines.push(`- ${g.description || g}${sev}`);
+      if (g.suggestedQuestion) lines.push(`  → ${g.suggestedQuestion}`);
+    }
+    lines.push("");
+  }
+
+  if (result.momTestQuestions?.length) {
+    lines.push("## Mom Test Questions");
+    for (const q of result.momTestQuestions) {
+      lines.push(`- ${q.question || q}`);
+      if (q.rationale) lines.push(`  _${q.rationale}_`);
+    }
+    lines.push("");
+  }
+
+  if (result.wendelChecklist?.length) {
+    lines.push("## Wendel Checklist");
+    for (const w of result.wendelChecklist) {
+      const icon = w.status === "pass" ? "✓" : w.status === "fail" ? "✗" : "?";
+      lines.push(`- [${icon}] ${w.condition}: ${w.justification || ""}`);
+    }
+    lines.push("");
+  }
+
+  if (result.classification) {
+    lines.push("## Classification");
+    lines.push(`- Type: ${result.classification.type}`);
+    if (result.classification.adoptionRisk) lines.push(`- Adoption risk: ${result.classification.adoptionRisk}`);
+    if (result.classification.frictionEstimate) lines.push(`- Friction: ${result.classification.frictionEstimate}`);
+    lines.push("");
+  }
+
+  if (result.jtbds?.length) {
+    lines.push("## Jobs-to-be-Done");
+    for (const j of result.jtbds) {
+      lines.push(`- **${j.id || ""}**: ${j.functional || j}`);
+    }
+    lines.push("");
+  }
+
+  if (result.summary) lines.push(`---\n${result.summary}`);
+  return lines.join("\n");
+}
+
+export async function discoverCommand({ task, config, logger, mode, json }) {
+  const discoverRole = resolveRole(config, "discover");
+  await assertAgentsAvailable([discoverRole.provider]);
+  logger.info(`Discover (${discoverRole.provider}) starting — mode: ${mode || "gaps"}...`);
+
+  const agent = createAgent(discoverRole.provider, config, logger);
+  const prompt = buildDiscoverPrompt({ task, mode: mode || "gaps" });
+  const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
+  const result = await agent.runTask({ prompt, onOutput, role: "discover" });
+
+  if (!result.ok) {
+    throw new Error(result.error || result.output || "Discover failed");
+  }
+
+  const parsed = parseDiscoverOutput(result.output);
+
+  if (json) {
+    console.log(JSON.stringify(parsed || result.output, null, 2));
+    return;
+  }
+
+  if (parsed?.verdict) {
+    console.log(formatDiscover(parsed, mode || "gaps"));
+  } else {
+    console.log(result.output);
+  }
+  logger.info("Discover completed.");
+}

package/src/commands/researcher.js

@@ -0,0 +1,40 @@
+import { createAgent } from "../agents/index.js";
+import { assertAgentsAvailable } from "../agents/availability.js";
+import { resolveRole } from "../config.js";
+
+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 researching the codebase."
+].join(" ");
+
+function buildResearchPrompt(task) {
+  return [
+    SUBAGENT_PREAMBLE,
+    "Investigate the codebase for the following task.",
+    "Identify affected files, patterns, constraints, prior decisions, risks, and test coverage.",
+    "Return a single valid JSON object with your findings and nothing else.",
+    '{"affected_files":[string],"patterns":[string],"constraints":[string],"prior_decisions":[string],"risks":[string],"test_coverage":string}',
+    `## Task\n${task}`
+  ].join("\n\n");
+}
+
+export async function researcherCommand({ task, config, logger }) {
+  const researcherRole = resolveRole(config, "researcher");
+  await assertAgentsAvailable([researcherRole.provider]);
+  logger.info(`Researcher (${researcherRole.provider}) starting...`);
+
+  const agent = createAgent(researcherRole.provider, config, logger);
+  const prompt = buildResearchPrompt(task);
+  const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
+  const result = await agent.runTask({ prompt, onOutput, role: "researcher" });
+
+  if (!result.ok) {
+    throw new Error(result.error || result.output || "Researcher failed");
+  }
+
+  if (result.output) {
+    console.log(result.output);
+  }
+  logger.info("Researcher completed.");
+}

package/src/commands/triage.js

@@ -0,0 +1,63 @@
+import { createAgent } from "../agents/index.js";
+import { assertAgentsAvailable } from "../agents/availability.js";
+import { resolveRole } from "../config.js";
+import { buildTriagePrompt } from "../prompts/triage.js";
+import { parseMaybeJsonString } from "../review/parser.js";
+
+function formatTriage(result) {
+  const lines = [];
+  lines.push(`## Triage Result`);
+  lines.push(`- **Level:** ${result.level || "unknown"}`);
+  if (result.taskType) lines.push(`- **Task type:** ${result.taskType}`);
+  if (result.reasoning) lines.push(`- **Reasoning:** ${result.reasoning}`);
+  lines.push("");
+
+  if (result.roles?.length) {
+    lines.push("### Recommended Roles");
+    for (const r of result.roles) {
+      lines.push(`- ${r}`);
+    }
+    lines.push("");
+  }
+
+  if (result.shouldDecompose) {
+    lines.push("### Decomposition Suggested");
+    if (result.subtasks?.length) {
+      for (const s of result.subtasks) {
+        lines.push(`- ${typeof s === "string" ? s : s.title || s}`);
+      }
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+export async function triageCommand({ task, config, logger, json }) {
+  const triageRole = resolveRole(config, "triage");
+  await assertAgentsAvailable([triageRole.provider]);
+  logger.info(`Triage (${triageRole.provider}) starting...`);
+
+  const agent = createAgent(triageRole.provider, config, logger);
+  const prompt = buildTriagePrompt({ task });
+  const onOutput = ({ line }) => process.stdout.write(`${line}\n`);
+  const result = await agent.runTask({ prompt, onOutput, role: "triage" });
+
+  if (!result.ok) {
+    throw new Error(result.error || result.output || "Triage failed");
+  }
+
+  const parsed = parseMaybeJsonString(result.output);
+
+  if (json) {
+    console.log(JSON.stringify(parsed || result.output, null, 2));
+    return;
+  }
+
+  if (parsed?.level) {
+    console.log(formatTriage(parsed));
+  } else {
+    console.log(result.output);
+  }
+  logger.info("Triage completed.");
+}

package/src/config.js

@@ -101,6 +101,18 @@ const DEFAULTS = {
       disabled_rules: ["javascript:S1116", "javascript:S3776"]
     }
   },
+  sonarcloud: {
+    enabled: false,
+    organization: null,
+    token: null,
+    project_key: null,
+    host: "https://sonarcloud.io",
+    scanner: {
+      sources: "src,public,lib",
+      exclusions: "**/node_modules/**,**/dist/**,**/build/**,**/*.min.js",
+      test_inclusions: "**/*.test.js,**/*.spec.js,**/tests/**,**/__tests__/**"
+    }
+  },
   policies: {},
   serena: { enabled: false },
   planning_game: { enabled: false, project_id: null, codeveloper: null },
@@ -347,6 +359,9 @@ function applyBecariaOverride(out, flags) {
 
 function applyMiscOverrides(out, flags) {
   if (flags.noSonar || flags.sonar === false) out.sonarqube.enabled = false;
+  out.sonarcloud = out.sonarcloud || {};
+  if (flags.enableSonarcloud === true) out.sonarcloud.enabled = true;
+  if (flags.noSonarcloud === true || flags.sonarcloud === false) out.sonarcloud.enabled = false;
 
   out.planning_game = out.planning_game || {};
   if (flags.pgTask) out.planning_game.enabled = true;

package/src/mcp/server-handlers.js

@@ -469,6 +469,138 @@ export async function handleDiscoverDirect(a, server, extra) {
   return { ok: true, ...result.result, summary: result.summary };
 }
 
+export async function handleTriageDirect(a, server, extra) {
+  const config = await buildConfig(a, "triage");
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const triageRole = resolveRole(config, "triage");
+  await assertAgentsAvailable([triageRole.provider]);
+
+  const projectDir = await resolveProjectDir(server);
+  const runLog = createRunLog(projectDir);
+  runLog.logText(`[kj_triage] started`);
+  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: "triage", message: line, detail: { stream, agent: triageRole.provider } });
+  };
+  const stallDetector = createStallDetector({
+    onOutput, emitter, eventBase, stage: "triage", provider: triageRole.provider
+  });
+
+  const { TriageRole } = await import("../roles/triage-role.js");
+  const triage = new TriageRole({ config, logger, emitter });
+  await triage.init({ task: a.task });
+
+  sendTrackerLog(server, "triage", "running", triageRole.provider);
+  runLog.logText(`[triage] agent launched, waiting for response...`);
+  let result;
+  try {
+    result = await triage.run({ task: a.task, onOutput: stallDetector.onOutput });
+  } finally {
+    stallDetector.stop();
+    const stats = stallDetector.stats();
+    runLog.logText(`[triage] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
+    runLog.close();
+  }
+
+  if (!result.ok) {
+    sendTrackerLog(server, "triage", "failed");
+    throw new Error(result.result?.error || result.summary || "Triage failed");
+  }
+
+  sendTrackerLog(server, "triage", "done");
+  return { ok: true, ...result.result, summary: result.summary };
+}
+
+export async function handleResearcherDirect(a, server, extra) {
+  const config = await buildConfig(a, "researcher");
+  const logger = createLogger(config.output.log_level, "mcp");
+
+  const researcherRole = resolveRole(config, "researcher");
+  await assertAgentsAvailable([researcherRole.provider]);
+
+  const projectDir = await resolveProjectDir(server);
+  const runLog = createRunLog(projectDir);
+  runLog.logText(`[kj_researcher] started`);
+  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: "researcher", message: line, detail: { stream, agent: researcherRole.provider } });
+  };
+  const stallDetector = createStallDetector({
+    onOutput, emitter, eventBase, stage: "researcher", provider: researcherRole.provider
+  });
+
+  const { ResearcherRole } = await import("../roles/researcher-role.js");
+  const researcher = new ResearcherRole({ config, logger, emitter });
+  await researcher.init({ task: a.task });
+
+  sendTrackerLog(server, "researcher", "running", researcherRole.provider);
+  runLog.logText(`[researcher] agent launched, waiting for response...`);
+  let result;
+  try {
+    result = await researcher.run({ task: a.task, onOutput: stallDetector.onOutput });
+  } finally {
+    stallDetector.stop();
+    const stats = stallDetector.stats();
+    runLog.logText(`[researcher] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
+    runLog.close();
+  }
+
+  if (!result.ok) {
+    sendTrackerLog(server, "researcher", "failed");
+    throw new Error(result.result?.error || result.summary || "Researcher failed");
+  }
+
+  sendTrackerLog(server, "researcher", "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");
+
+  const architectRole = resolveRole(config, "architect");
+  await assertAgentsAvailable([architectRole.provider]);
+
+  const projectDir = await resolveProjectDir(server);
+  const runLog = createRunLog(projectDir);
+  runLog.logText(`[kj_architect] started`);
+  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: "architect", message: line, detail: { stream, agent: architectRole.provider } });
+  };
+  const stallDetector = createStallDetector({
+    onOutput, emitter, eventBase, stage: "architect", provider: architectRole.provider
+  });
+
+  const { ArchitectRole } = await import("../roles/architect-role.js");
+  const architect = new ArchitectRole({ config, logger, emitter });
+  await architect.init({ task: a.task });
+
+  sendTrackerLog(server, "architect", "running", architectRole.provider);
+  runLog.logText(`[architect] agent launched, waiting for response...`);
+  let result;
+  try {
+    result = await architect.run({ task: a.task, researchContext: a.context || null, onOutput: stallDetector.onOutput });
+  } finally {
+    stallDetector.stop();
+    const stats = stallDetector.stats();
+    runLog.logText(`[architect] finished — lines=${stats.lineCount}, bytes=${stats.bytesReceived}, elapsed=${Math.round(stats.elapsedMs / 1000)}s`);
+    runLog.close();
+  }
+
+  if (!result.ok) {
+    sendTrackerLog(server, "architect", "failed");
+    throw new Error(result.result?.error || result.summary || "Architect failed");
+  }
+
+  sendTrackerLog(server, "architect", "done");
+  return { ok: true, ...result.result, summary: result.summary };
+}
+
 /* ── Preflight helpers ─────────────────────────────────────────────── */
 
 const AGENT_ROLES = new Set(["coder", "reviewer", "tester", "security", "solomon"]);
@@ -662,6 +794,27 @@ async function handleDiscover(a, server, extra) {
   return handleDiscoverDirect(a, server, extra);
 }
 
+async function handleTriage(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  return handleTriageDirect(a, server, extra);
+}
+
+async function handleResearcher(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  return handleResearcherDirect(a, server, extra);
+}
+
+async function handleArchitect(a, server, extra) {
+  if (!a.task) {
+    return failPayload("Missing required field: task");
+  }
+  return handleArchitectDirect(a, server, extra);
+}
+
 /* ── Handler dispatch map ─────────────────────────────────────────── */
 
 const toolHandlers = {
@@ -679,7 +832,10 @@ const toolHandlers = {
   kj_code:      (a, server, extra) => handleCode(a, server, extra),
   kj_review:    (a, server, extra) => handleReview(a, server, extra),
   kj_plan:      (a, server, extra) => handlePlan(a, server, extra),
-  kj_discover:  (a, server, extra) => handleDiscover(a, server, extra)
+  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)
 };
 
 export async function handleToolCall(name, args, server, extra) {

package/src/mcp/tools.js

@@ -93,6 +93,7 @@ export const tools = [
         checkpointInterval: { type: "number", description: "Minutes between interactive checkpoints (default: 5). Set 0 to disable." },
         taskType: { type: "string", enum: ["sw", "infra", "doc", "add-tests", "refactor"], description: "Explicit task type for policy resolution. Overrides triage classification." },
         noSonar: { type: "boolean" },
+        enableSonarcloud: { type: "boolean", description: "Enable SonarCloud scan (complementary to SonarQube)" },
         kjHome: { type: "string" },
         sonarToken: { type: "string" },
         timeoutMs: { type: "number" }
@@ -242,5 +243,42 @@ export const tools = [
         kjHome: { type: "string" }
       }
     }
+  },
+  {
+    name: "kj_triage",
+    description: "Classify task complexity and recommend which pipeline roles to activate. Returns level (trivial/simple/medium/complex), taskType, recommended roles, and optional decomposition.",
+    inputSchema: {
+      type: "object",
+      required: ["task"],
+      properties: {
+        task: { type: "string", description: "Task description to classify" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_researcher",
+    description: "Research the codebase for a task. Identifies affected files, patterns, constraints, prior decisions, risks, and test coverage.",
+    inputSchema: {
+      type: "object",
+      required: ["task"],
+      properties: {
+        task: { type: "string", description: "Task description to research" },
+        kjHome: { type: "string" }
+      }
+    }
+  },
+  {
+    name: "kj_architect",
+    description: "Design solution architecture for a task. Returns layers, patterns, data model, API contracts, tradeoffs, and a verdict (ready/needs_clarification).",
+    inputSchema: {
+      type: "object",
+      required: ["task"],
+      properties: {
+        task: { type: "string", description: "Task description to architect" },
+        context: { type: "string", description: "Additional context (e.g., researcher output)" },
+        kjHome: { type: "string" }
+      }
+    }
   }
 ];

package/src/orchestrator/iteration-stages.js

@@ -427,6 +427,47 @@ export async function runSonarStage({ config, logger, emitter, eventBase, sessio
   return { action: "ok", stageResult };
 }
 
+export async function runSonarCloudStage({ config, logger, emitter, eventBase, session, trackBudget, iteration }) {
+  logger.setContext({ iteration, stage: "sonarcloud" });
+  emitProgress(
+    emitter,
+    makeEvent("sonarcloud:start", { ...eventBase, stage: "sonarcloud" }, {
+      message: "SonarCloud scanning"
+    })
+  );
+
+  const { runSonarCloudScan } = await import("../sonar/cloud-scanner.js");
+  const scanStart = Date.now();
+  const result = await runSonarCloudScan(config);
+  trackBudget({ role: "sonarcloud", provider: "sonarcloud", result: { ok: result.ok }, duration_ms: Date.now() - scanStart });
+
+  await addCheckpoint(session, {
+    stage: "sonarcloud",
+    iteration,
+    project_key: result.projectKey,
+    exitCode: result.exitCode,
+    provider: "sonarcloud",
+    model: null
+  });
+
+  const status = result.ok ? "ok" : "warn";
+  const message = result.ok
+    ? `SonarCloud scan passed (project: ${result.projectKey})`
+    : `SonarCloud scan issue: ${(result.stderr || "").slice(0, 200)}`;
+
+  emitProgress(
+    emitter,
+    makeEvent("sonarcloud:end", { ...eventBase, stage: "sonarcloud" }, {
+      status,
+      message,
+      detail: { projectKey: result.projectKey, exitCode: result.exitCode }
+    })
+  );
+
+  // SonarCloud is advisory — never blocks the pipeline
+  return { action: "ok", stageResult: { ok: result.ok, projectKey: result.projectKey, message } };
+}
+
 async function handleReviewerStalledSolomon({ review, repeatCounts, repeatState, config, logger, emitter, eventBase, session, iteration, task, askQuestion, budgetSummary, repeatDetector }) {
   logger.warn(`Reviewer stalled (${repeatCounts.reviewer} repeats). Invoking Solomon mediation.`);
   emitProgress(

package/src/orchestrator.js

@@ -30,7 +30,7 @@ import { resolveReviewProfile } from "./review/profiles.js";
 import { CoderRole } from "./roles/coder-role.js";
 import { invokeSolomon } from "./orchestrator/solomon-escalation.js";
 import { runTriageStage, runResearcherStage, runArchitectStage, runPlannerStage, runDiscoverStage } from "./orchestrator/pre-loop-stages.js";
-import { runCoderStage, runRefactorerStage, runTddCheckStage, runSonarStage, runReviewerStage } from "./orchestrator/iteration-stages.js";
+import { runCoderStage, runRefactorerStage, runTddCheckStage, runSonarStage, runSonarCloudStage, runReviewerStage } from "./orchestrator/iteration-stages.js";
 import { runTesterStage, runSecurityStage } from "./orchestrator/post-loop-stages.js";
 import { waitForCooldown, MAX_STANDBY_RETRIES } from "./orchestrator/standby.js";
 
@@ -910,6 +910,15 @@ async function runQualityGateStages({ config, logger, emitter, eventBase, sessio
     }
   }
 
+  if (config.sonarcloud?.enabled) {
+    const cloudResult = await runSonarCloudStage({
+      config, logger, emitter, eventBase, session, trackBudget, iteration: i
+    });
+    if (cloudResult.stageResult) {
+      stageResults.sonarcloud = cloudResult.stageResult;
+    }
+  }
+
   return { action: "ok" };
 }
 

package/src/sonar/cloud-scanner.js

@@ -0,0 +1,76 @@
+import { runCommand } from "../utils/process.js";
+import { resolveSonarProjectKey } from "./project-key.js";
+
+function buildCloudScannerArgs(projectKey, config) {
+  const sc = config.sonarcloud || {};
+  const scanner = sc.scanner || {};
+  const host = sc.host || "https://sonarcloud.io";
+  const token = process.env.KJ_SONARCLOUD_TOKEN || sc.token;
+  const organization = process.env.KJ_SONARCLOUD_ORG || sc.organization;
+
+  const args = [
+    `-Dsonar.host.url=${host}`,
+    `-Dsonar.projectKey=${projectKey}`
+  ];
+
+  if (token) args.push(`-Dsonar.token=${token}`);
+  if (organization) args.push(`-Dsonar.organization=${organization}`);
+  if (scanner.sources) args.push(`-Dsonar.sources=${scanner.sources}`);
+  if (scanner.exclusions) args.push(`-Dsonar.exclusions=${scanner.exclusions}`);
+  if (scanner.test_inclusions) args.push(`-Dsonar.test.inclusions=${scanner.test_inclusions}`);
+
+  return args;
+}
+
+export async function runSonarCloudScan(config, projectKey = null) {
+  const sc = config.sonarcloud || {};
+  const token = process.env.KJ_SONARCLOUD_TOKEN || sc.token;
+  const organization = sc.organization || process.env.KJ_SONARCLOUD_ORG;
+
+  if (!token) {
+    return {
+      ok: false,
+      projectKey: null,
+      stdout: "",
+      stderr: "SonarCloud token not configured. Set sonarcloud.token in kj.config.yml or KJ_SONARCLOUD_TOKEN env var.",
+      exitCode: 1
+    };
+  }
+
+  if (!organization) {
+    return {
+      ok: false,
+      projectKey: null,
+      stdout: "",
+      stderr: "SonarCloud organization not configured. Set sonarcloud.organization in kj.config.yml or KJ_SONARCLOUD_ORG env var.",
+      exitCode: 1
+    };
+  }
+
+  let effectiveProjectKey;
+  try {
+    effectiveProjectKey = projectKey || sc.project_key || await resolveSonarProjectKey(config, { projectKey });
+  } catch (error) {
+    return {
+      ok: false,
+      projectKey: null,
+      stdout: "",
+      stderr: error?.message || String(error),
+      exitCode: 1
+    };
+  }
+
+  const scannerTimeout = 15 * 60 * 1000;
+  const args = buildCloudScannerArgs(effectiveProjectKey, config);
+
+  // Use npx @sonar/scan (no Docker needed)
+  const result = await runCommand("npx", ["@sonar/scan", ...args], { timeout: scannerTimeout });
+
+  return {
+    ok: result.exitCode === 0,
+    projectKey: effectiveProjectKey,
+    stdout: result.stdout,
+    stderr: result.stderr,
+    exitCode: result.exitCode
+  };
+}