@karajan-family/code 4.21.0

package/src/orchestrator/solomon-escalation.js

@@ -0,0 +1,305 @@
+import { SolomonRole } from "../roles/solomon-role.js";
+import { addCheckpoint, pauseSession, saveSession } from "../session/store.js";
+import { setSuggestions } from "../session/mutators.js";
+import { emitProgress, makeEvent } from "../utils/events.js";
+import { msg, getLang } from "../utils/messages.js";
+
+/**
+ * @typedef {import("../types/solomon.js").Conflict} Conflict
+ * @typedef {import("../types/solomon.js").SolomonResult} SolomonResult
+ */
+
+/**
+ * Architectural invariant (DO NOT BREAK):
+ * `invokeSolomon` MUST NOT be called directly from stages, rules or agent
+ * code. The only callers should be:
+ *   - Karajan Brain (via `src/brain/solomon-consult.js`)
+ *   - The orchestrator's escalation path (`src/orchestrator/flow-runner.js`)
+ *     on behalf of Brain.
+ * The v2.3.0 audit fixed 21 violations of this rule. Keeping Solomon behind
+ * Brain is what the "Brain-as-gateway, Solomon-as-judge" architecture
+ * depends on — see docs/ARCHITECTURE.md §Brain/Solomon.
+ */
+
+/**
+ * Build a human-readable escalation message from raw Solomon conflict data.
+ * Replaces the raw JSON dump with structured, plain-text output.
+ *
+ * @param {object} solomonResult - The conflict object passed to escalateToHuman
+ * @param {object} [session]     - Current session (optional, used for extra context)
+ * @returns {string} Formatted message suitable for display to the user
+ */
+export function formatEscalationMessage(solomonResult, session) {
+  const stage = solomonResult?.stage || "unknown";
+  const solomonReason = solomonResult?.solomonReason || null;
+  const history = solomonResult?.history || [];
+  const lang = getLang(session?.config_snapshot);
+
+  const lines = [];
+  lines.push(msg("solomon_conflict", lang, { stage }));
+  lines.push("");
+
+  // Extract reviewer/agent feedback from history
+  const feedbackEntries = history.filter(entry => entry && typeof entry === "object");
+  if (feedbackEntries.length > 0) {
+    lines.push(msg("solomon_feedback", lang));
+    for (const entry of feedbackEntries) {
+      const agent = entry.agent || "unknown";
+      const feedback = entry.feedback || "No feedback provided";
+      // Split multi-line feedback (e.g. "R-1: ...\nR-2: ...") into bullet points
+      const feedbackLines = String(feedback).split("\n").filter(l => l.trim());
+      if (feedbackLines.length === 1) {
+        lines.push(`  [${agent}] ${feedbackLines[0]}`);
+      } else {
+        lines.push(`  [${agent}]`);
+        for (const fl of feedbackLines) {
+          lines.push(`    - ${fl}`);
+        }
+      }
+    }
+    lines.push("");
+  }
+
+  // Solomon's reason (if it tried and failed)
+  if (solomonReason) {
+    lines.push(`${msg("solomon_reason", lang)} ${solomonReason}`);
+    lines.push("");
+  }
+
+  // Iteration context
+  const iterationCount = solomonResult?.iterationCount;
+  const maxIterations = solomonResult?.maxIterations;
+  if (iterationCount !== undefined && maxIterations !== undefined) {
+    lines.push(msg("pipeline_iteration", lang, { current: iterationCount, max: maxIterations }));
+    lines.push("");
+  }
+
+  lines.push(msg("solomon_options", lang));
+  lines.push("");
+  lines.push(msg("solomon_proceed", lang));
+
+  return lines.join("\n");
+}
+
+/**
+ * Extract Solomon's previous rulings from session checkpoints.
+ * Gives Solomon memory of its own decisions to avoid repeating failed strategies.
+ */
+function extractSolomonHistory(session) {
+  const checkpoints = session?.checkpoints || [];
+  return checkpoints
+    .filter(cp => cp.stage === "solomon")
+    .map(cp => ({
+      conflictStage: cp.conflictStage,
+      ruling: cp.ruling,
+      alternativeAgent: cp.alternativeAgent,
+      waitUntil: cp.waitUntil,
+      conditions: cp.conditions,
+      error: cp.error || null
+    }));
+}
+
+/**
+ * Consult Solomon (or fall back to human escalation) for a given conflict.
+ * See the Conflict typedef for the shape of the `conflict` argument and
+ * the invariant above for who is allowed to call this.
+ *
+ * @param {Object}    params
+ * @param {Object}    params.config
+ * @param {Object}    params.logger
+ * @param {Object}    [params.emitter]
+ * @param {Object}    [params.eventBase]
+ * @param {string}    params.stage
+ * @param {Conflict}  params.conflict
+ * @param {Function}  [params.askQuestion]
+ * @param {Object}    [params.session]
+ * @param {number}    [params.iteration]
+ * @returns {Promise<SolomonResult>}
+ */
+export async function invokeSolomon({ config, logger, emitter, eventBase, stage, conflict, askQuestion, session, iteration }) {
+  const solomonEnabled = Boolean(config.pipeline?.solomon?.enabled);
+
+  if (!solomonEnabled) {
+    return escalateToHuman({ askQuestion, session, emitter, eventBase, stage, conflict, iteration });
+  }
+
+  // KJC-BUG-0113: the fallback used to be "gemini" — Google retired the
+  // Gemini Code Assist CLI for individuals (IneligibleTierError), so an
+  // unconfigured Solomon died on every escalation. Claude matches the
+  // brain.provider default.
+  const solomonProvider = config?.roles?.solomon?.provider || "claude";
+  emitProgress(
+    emitter,
+    makeEvent("solomon:start", { ...eventBase, stage: "solomon" }, {
+      message: `Solomon arbitrating ${stage} conflict`,
+      detail: { conflictStage: stage, provider: solomonProvider, executorType: "agent" }
+    })
+  );
+
+  // Collect pending suggestions from the session for Solomon's context
+  const pendingSuggestions = Array.isArray(session.suggestions) && session.suggestions.length > 0
+    ? session.suggestions.slice()
+    : null;
+
+  const solomon = new SolomonRole({ config, logger, emitter });
+  await solomon.init({ task: conflict.task, iteration });
+  let ruling;
+  try {
+    // Inject Solomon's own history so it doesn't repeat failed strategies
+    const solomonHistory = extractSolomonHistory(session);
+    const enrichedConflict = {
+      ...conflict,
+      ...(pendingSuggestions && { hostSuggestions: pendingSuggestions }),
+      ...(solomonHistory.length > 0 && { previousSolomonRulings: solomonHistory })
+    };
+    ruling = await solomon.run({ conflict: enrichedConflict });
+  } catch (err) {
+    logger.warn(`Solomon threw: ${err.message}`);
+    return escalateToHuman({
+      askQuestion, session, emitter, eventBase, stage, iteration,
+      conflict: { ...conflict, solomonReason: `Solomon error: ${err.message}` }
+    });
+  }
+
+  // Clear processed suggestions from session
+  if (pendingSuggestions) {
+    setSuggestions(session, []);
+    try { await saveSession(session); } catch { /* best-effort */ }
+  }
+
+  const solomonError = ruling.result?.error;
+  if (!ruling.ok && solomonError) {
+    logger.warn(`Solomon execution failed: ${solomonError}`);
+  }
+
+  emitProgress(
+    emitter,
+    makeEvent("solomon:end", { ...eventBase, stage: "solomon" }, {
+      message: ruling.ok
+        ? `Solomon ruling: ${ruling.result?.ruling || "unknown"}`
+        : `Solomon failed: ${(solomonError || ruling.summary || "unknown error").slice(0, 200)}`,
+      detail: { ...ruling.result, provider: solomonProvider, executorType: "agent" }
+    })
+  );
+
+  await addCheckpoint(session, {
+    stage: "solomon",
+    iteration,
+    conflictStage: conflict?.stage || stage,
+    ruling: ruling.result?.ruling,
+    alternativeAgent: ruling.result?.alternativeAgent || null,
+    waitUntil: ruling.result?.waitUntil || null,
+    conditions: ruling.result?.conditions || [],
+    escalate: ruling.result?.escalate,
+    error: solomonError ? solomonError.slice(0, 500) : undefined,
+    subtask: ruling.result?.subtask?.title || null
+  });
+
+  // Record the ruling for the session journal (decisions.md). Lazy-import so
+  // this module stays free of journal-specific deps for callers that don't
+  // need them.
+  try {
+    const { recordSolomonRuling } = await import("../session/journal/decisions-writer.js");
+    recordSolomonRuling(session, {
+      stage: conflict?.stage || stage,
+      trigger: conflict?.reason || conflict?.summary || "solomon invoked",
+      conflict: {
+        task: conflict?.task,
+        reason: conflict?.reason,
+        summary: conflict?.summary,
+        iterationCount: conflict?.iterationCount,
+      },
+      ruling: ruling.result?.ruling || (ruling.ok ? "continue" : "escalate_human"),
+      reasoning: ruling.result?.reasoning || ruling.summary || "",
+      conditions: ruling.result?.conditions || [],
+      alternativeAgent: ruling.result?.alternativeAgent || null,
+    });
+  } catch { /* best-effort, don't break the pipeline on a journal hiccup */ }
+
+  if (!ruling.ok) {
+    const reason = ruling.result?.escalate_reason || solomonError || ruling.summary;
+    return escalateToHuman({
+      askQuestion, session, emitter, eventBase, stage, iteration,
+      conflict: { ...conflict, solomonReason: reason }
+    });
+  }
+
+  const r = ruling.result?.ruling;
+  if (r === "approve") {
+    return { action: "approve", conditions: [], ruling };
+  }
+  if (r === "approve_with_conditions") {
+    return {
+      action: "continue",
+      conditions: ruling.result?.conditions || [],
+      extraIterations: ruling.result?.extraIterations || null,
+      alternativeAgent: ruling.result?.alternativeAgent || null,
+      waitUntil: ruling.result?.waitUntil || null,
+      ruling
+    };
+  }
+
+  if (r === "escalate_human") {
+    return escalateToHuman({
+      askQuestion, session, emitter, eventBase, stage, iteration,
+      conflict: { ...conflict, solomonReason: ruling.result?.escalate_reason || "Solomon escalated to human" }
+    });
+  }
+
+  if (r === "create_subtask") {
+    return { action: "subtask", subtask: ruling.result?.subtask, ruling };
+  }
+
+  return { action: "continue", conditions: [], ruling };
+}
+
+export function parseEscalationAnswer(answer) {
+  if (!answer) return null;
+  const trimmed = answer.trim().toLowerCase();
+  // Option 1: Accept coder's work as-is
+  if (trimmed === "1" || trimmed === "accept" || trimmed === "yes" || trimmed === "sí" || trimmed === "si") {
+    return { action: "continue", humanGuidance: "Accept coder's work as-is" };
+  }
+  // Option 2: Retry with reviewer's feedback
+  if (trimmed === "2" || trimmed === "retry") {
+    return { action: "continue", humanGuidance: "Retry with reviewer feedback" };
+  }
+  // Option 3: Stop the session
+  if (trimmed === "3" || trimmed.startsWith("stop") || trimmed.startsWith("pause")) {
+    return { action: "stop" };
+  }
+  // Free-text: treat as human guidance (backward compat)
+  return { action: "continue", humanGuidance: answer.trim() };
+}
+
+export async function escalateToHuman({ askQuestion, session, emitter, eventBase, stage, conflict, iteration }) {
+  const question = formatEscalationMessage({ ...conflict, stage }, session);
+
+  if (askQuestion) {
+    const answer = await askQuestion(question, { iteration, stage });
+    const parsed = parseEscalationAnswer(answer);
+    if (parsed && parsed.action === "continue") {
+      return { action: "continue", humanGuidance: parsed.humanGuidance };
+    }
+    if (parsed && parsed.action === "stop") {
+      // Fall through to pause session
+    } else if (answer) {
+      return { action: "continue", humanGuidance: answer };
+    }
+  }
+
+  await pauseSession(session, {
+    question,
+    context: { iteration, stage, conflict }
+  });
+  emitProgress(
+    emitter,
+    makeEvent("question", { ...eventBase, stage }, {
+      status: "paused",
+      message: question,
+      detail: { question, sessionId: session.id }
+    })
+  );
+
+  return { action: "pause", question };
+}

package/src/orchestrator/solomon-rules.js

@@ -0,0 +1,212 @@
+/**
+ * Solomon rules engine — detects anomalies during session execution.
+ * Each rule returns { triggered: boolean, severity: "warn"|"critical", message, detail }
+ */
+
+const DEFAULT_RULES = {
+  max_stale_iterations: 3,
+  no_new_dependencies_without_task: true,
+  scope_guard: true,
+  reviewer_overreach: true,
+  reviewer_style_block: true
+};
+
+export function evaluateRules(context, rulesConfig = {}) {
+  const rules = { ...DEFAULT_RULES, ...rulesConfig };
+  const alerts = [];
+
+  // Rule 1: Stale iterations (no progress)
+  if (rules.max_stale_iterations && context.staleIterations >= rules.max_stale_iterations) {
+    alerts.push({
+      rule: "max_stale_iterations",
+      severity: "critical",
+      message: `${context.staleIterations} iterations without progress. Same errors repeating.`,
+      detail: { staleIterations: context.staleIterations, limit: rules.max_stale_iterations }
+    });
+  }
+
+  // Rule 3: New dependencies not in task (only flag suspicious runtime deps, not dev/test tooling)
+  if (rules.no_new_dependencies_without_task && context.newDependencies?.length > 0) {
+    const testTooling = /vitest|jest|mocha|coverage|eslint|prettier|typescript|@types\//i;
+    const buildTooling = /webpack|vite|rollup|esbuild|tsup|unbuild/i;
+    const depsNotInTask = context.newDependencies.filter(dep => {
+      if (testTooling.test(dep) || buildTooling.test(dep)) return false;
+      if (dep.startsWith("dev:") || dep.startsWith("@vitest/") || dep.startsWith("@types/")) return false;
+      return !context.task?.toLowerCase().includes(dep.toLowerCase());
+    });
+    if (depsNotInTask.length > 0) {
+      alerts.push({
+        rule: "no_new_dependencies_without_task",
+        severity: "warn",
+        message: `New dependencies added not mentioned in task: ${depsNotInTask.join(", ")}`,
+        detail: { dependencies: depsNotInTask }
+      });
+    }
+  }
+
+  // Rule 4: Scope guard — files outside expected scope
+  if (rules.scope_guard && context.outOfScopeFiles?.length > 0) {
+    alerts.push({
+      rule: "scope_guard",
+      severity: "warn",
+      message: `Files modified outside expected scope: ${context.outOfScopeFiles.join(", ")}`,
+      detail: { files: context.outOfScopeFiles }
+    });
+  }
+
+  // Rule 5: Reviewer overreach — reviewer consistently flags out-of-scope issues
+  if (rules.reviewer_overreach && context.reviewerDemotedCount > 0) {
+    const severity = context.reviewerDemotedCount >= 3 ? "critical" : "warn";
+    alerts.push({
+      rule: "reviewer_overreach",
+      severity,
+      message: `Reviewer flagged ${context.reviewerDemotedCount} out-of-scope issue(s) that were auto-demoted by scope filter.`,
+      detail: { demotedCount: context.reviewerDemotedCount, autoApproved: context.reviewerAutoApproved || false }
+    });
+  }
+
+  // Rule 6: Reviewer style-only block — all blocking issues are style/naming/formatting, not security/correctness
+  if (rules.reviewer_style_block && context.blockingIssues?.length > 0) {
+    const styleKeywords = /\b(naming|name|rename|style|format|formatting|indent|spacing|camelCase|snake_case|convention|cosmetic|readability|comment|jsdoc|documentation|whitespace|semicolon|quotes|trailing)\b/i;
+    // Anti-style: if any of these match, the issue is NOT style — it's a real correctness/security concern.
+    // Fixes KJC-BUG-0026 (Solomon approving legitimate security blockers misclassified as "style").
+    // Decomposed by concern (S5843, complexity 71 → 7 named groups).
+    // The union of tokens is byte-identical to the original alternation.
+    const SECURITY_KEYWORD_GROUPS = [
+      /\b(sql\s*injection|xss|csrf|ssrf|rce|injection|vulnerab|exploit)\b/i,
+      /\b(sanitiz|escape\b|encod\b|cors|traversal|prototype[-_\s]*pollution|deserializ)\b/i,
+      /\b(auth|authn|authz|password|secret|credential|token|api[-_\s]*key|private[-_\s]*key)\b/i,
+      /\b(hash|cipher|crypto|encrypt|decrypt|tls|ssl|certificate)\b/i,
+      /\b(leak|sensitive|pii|privacy|insecure|unsafe)\b/i,
+      /\b(race[-_\s]*condition|deadlock|memory[-_\s]*leak|null[-_\s]*deref|uaf|overflow)\b/i,
+      /\b(eval\b|exec\b|spawn|shell|command[-_\s]*injection)\b/i,
+    ];
+    const securityKeywords = { test: (text) => SECURITY_KEYWORD_GROUPS.some((re) => re.test(text)) };
+    const securityCategories = new Set(["security", "correctness", "bug", "vulnerability"]);
+    const styleSeverities = new Set(["low", "minor"]);
+    const blockingSeverities = new Set(["critical", "high", "blocker", "major"]);
+    const isSecurityIssue = issue => {
+      const desc = issue.description || "";
+      const sev = (issue.severity || "").toLowerCase();
+      const cat = (issue.category || issue.type || "").toLowerCase();
+      const tags = Array.isArray(issue.tags) ? issue.tags.map(t => String(t).toLowerCase()) : [];
+      if (blockingSeverities.has(sev)) return true;
+      if (securityCategories.has(cat)) return true;
+      if (tags.some(t => securityCategories.has(t))) return true;
+      return securityKeywords.test(desc);
+    };
+    const allStyle = context.blockingIssues.every(issue => {
+      if (isSecurityIssue(issue)) return false;
+      const desc = issue.description || "";
+      const sev = (issue.severity || "").toLowerCase();
+      return styleSeverities.has(sev) || styleKeywords.test(desc);
+    });
+    if (allStyle) {
+      alerts.push({
+        rule: "reviewer_style_block",
+        severity: "critical",
+        message: `Reviewer blocked on ${context.blockingIssues.length} style-only issue(s). Style preferences should not block approval — escalating to Solomon mediation.`,
+        detail: { issueCount: context.blockingIssues.length, issues: context.blockingIssues.map(i => i.description) }
+      });
+    }
+  }
+
+  return {
+    alerts,
+    hasCritical: alerts.some(a => a.severity === "critical"),
+    hasWarnings: alerts.some(a => a.severity === "warn")
+  };
+}
+
+/**
+ * Build context for rules evaluation from git diff and session state.
+ */
+export async function buildRulesContext({ session, task, iteration, blockingIssues }) {
+  const context = {
+    task,
+    iteration,
+    filesChanged: 0,
+    staleIterations: 0,
+    newDependencies: [],
+    outOfScopeFiles: [],
+    reviewerDemotedCount: 0,
+    reviewerAutoApproved: false,
+    blockingIssues: blockingIssues || []
+  };
+
+  // Count reviewer scope-filter demotions from session checkpoints
+  const scopeFilterCheckpoints = (session.checkpoints || [])
+    .filter(cp => cp.stage === "reviewer-scope-filter");
+  if (scopeFilterCheckpoints.length > 0) {
+    const latest = scopeFilterCheckpoints.at(-1);
+    context.reviewerDemotedCount = latest.demoted_count || 0;
+    context.reviewerAutoApproved = latest.auto_approved || false;
+  }
+
+  // Count files changed via git
+  try {
+    // Audit follow-up: was using execaCommand with template-string
+    // interpolation of `baseRef`. baseRef comes from session state, not
+    // user input, but the shape is a known shell-injection vector.
+    // Switched to execa with arg arrays so no shell expansion happens.
+    const { execa } = await import("execa");
+    const baseRef = session.session_start_sha || "HEAD~1";
+
+    // Files changed
+    const diffResult = await execa("git", ["diff", "--name-only", String(baseRef)], { reject: false });
+    if (diffResult.stdout) {
+      const files = diffResult.stdout.split("\n").filter(Boolean);
+      context.filesChanged = files.length;
+
+      // Detect scope: config files, CI/CD, etc. that are often out of scope
+      // Exclude .env.example (legitimate for new projects) and files within projectDir
+      const scopePatterns = [".github/", ".gitlab-ci", "docker-compose", "firebase.json", "firestore.rules"];
+      const projectDir = session?.config_snapshot?.projectDir || null;
+      context.outOfScopeFiles = files.filter(f => {
+        // Files inside projectDir are always in scope
+        if (projectDir && f.startsWith(projectDir.replace(/^\.\//, ""))) return false;
+        // .env (but not .env.example) is out of scope
+        if (f.endsWith(".env") && !f.endsWith(".env.example")) return true;
+        return scopePatterns.some(pattern => f.includes(pattern));
+      });
+
+      // Detect new dependencies
+      if (files.includes("package.json")) {
+        try {
+          const pkgDiff = await execa("git", ["diff", String(baseRef), "--", "package.json"], { reject: false });
+          const addedDeps = (pkgDiff.stdout || "").split("\n")
+            .filter(line => line.startsWith("+") && line.includes('"') && !line.startsWith("+++"))
+            .map(line => {
+              const match = /"([^"]+)":\s*"/.exec(line);
+              return match ? match[1] : null;
+            })
+            .filter(Boolean)
+            .filter(name => !new Set(["name", "version", "description", "main", "scripts", "type", "license", "author"]).has(name));
+          context.newDependencies = addedDeps;
+        } catch { /* ignore */ }
+      }
+    }
+  } catch { /* git not available */ }
+
+  // Count stale iterations from session checkpoints
+  // "Stale" means TRULY no progress: same exact feedback AND zero files changed
+  const checkpoints = session.checkpoints || [];
+  const reviewerCps = checkpoints.filter(cp => cp.stage === "reviewer").slice(-3);
+  const coderCps = checkpoints.filter(cp => cp.stage === "coder").slice(-3);
+
+  if (reviewerCps.length >= 3) {
+    const feedbacks = reviewerCps.map(cp => cp.note || "");
+    const uniqueFeedbacks = new Set(feedbacks);
+    const filesChanged = coderCps.some(cp => (cp.filesChanged || 0) > 0);
+
+    // Only stale if feedback is identical AND no files changed
+    if (uniqueFeedbacks.size === 1 && !filesChanged) {
+      context.staleIterations = reviewerCps.length;
+    }
+    // If issues are changing between iterations, there IS progress
+  }
+
+  return context;
+}
+
+export { DEFAULT_RULES };

package/src/orchestrator/stages/architect-stage.js

@@ -0,0 +1,172 @@
+/**
+ * Architect stage logic.
+ * Extracted from pre-loop-stages.js for maintainability.
+ */
+
+import { ArchitectRole } from "../../roles/architect-role.js";
+import { createAgent } from "../../agents/index.js";
+import { addCheckpoint } from "../../session/store.js";
+import { emitProgress, makeEvent, emitAgentOutput } from "../../utils/events.js";
+import { createStallDetector } from "../../utils/stall-detector.js";
+import { getIntegration } from "../integrations.js";
+
+async function handleArchitectClarification({ architectOutput, askQuestion, config, logger, emitter, eventBase, session, architectOnOutput, architectProvider, coderRole, researchContext, discoverResult, triageLevel, trackBudget }) {
+  if (!architectOutput.ok
+    || architectOutput.result?.verdict !== "needs_clarification"
+    || !architectOutput.result?.questions?.length) {
+    return architectOutput;
+  }
+
+  const questions = architectOutput.result.questions;
+  if (!askQuestion) {
+    logger.warn("Architect returned needs_clarification but no interactive input available — continuing with best-effort decisions");
+    return architectOutput;
+  }
+
+  const formatted = "The architect needs clarification before proceeding:\n\n"
+    + questions.map((q, i) => `${i + 1}. ${q}`).join("\n")
+    + "\n\nPlease provide your answers:";
+
+  emitProgress(
+    emitter,
+    makeEvent("architect:clarification", { ...eventBase, stage: "architect" }, {
+      message: "Architect needs clarification — pausing for human input",
+      detail: { questions }
+    })
+  );
+
+  const answer = await askQuestion(formatted, { iteration: 0, stage: "architect" });
+  if (!answer) return architectOutput;
+
+  const architect2 = new ArchitectRole({ config, logger, emitter, createAgentFn: createAgent });
+  await architect2.init({ task: session.task, sessionId: session.id, iteration: 0 });
+  const rerunStart = Date.now();
+  const rerunStall = createStallDetector({
+    onOutput: architectOnOutput, emitter, eventBase, stage: "architect", provider: architectProvider
+  });
+  let result;
+  try {
+    result = await architect2.execute({
+      task: session.task,
+      onOutput: rerunStall.onOutput,
+      researchContext,
+      discoverResult,
+      triageLevel,
+      humanAnswers: answer
+    });
+  } finally {
+    rerunStall.stop();
+  }
+  trackBudget({
+    role: "architect",
+    provider: architectProvider,
+    model: config?.roles?.architect?.model || coderRole.model,
+    result,
+    duration_ms: Date.now() - rerunStart
+  });
+  return result;
+}
+
+export async function runArchitectStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget, researchContext = null, discoverResult = null, triageLevel = null, askQuestion = null }) {
+  logger.setContext({ iteration: 0, stage: "architect" });
+  const architectProvider = config?.roles?.architect?.provider || coderRole.provider;
+  emitProgress(
+    emitter,
+    makeEvent("architect:start", { ...eventBase, stage: "architect" }, {
+      message: "Architect designing solution architecture",
+      detail: { architect: architectProvider, provider: architectProvider, executorType: "agent" }
+    })
+  );
+  const architectOnOutput = (payload) => emitAgentOutput(emitter, eventBase, "architect", architectProvider, payload);
+  const architectStall = createStallDetector({
+    onOutput: architectOnOutput, emitter, eventBase, stage: "architect", provider: architectProvider
+  });
+
+  const architect = new ArchitectRole({ config, logger, emitter, createAgentFn: createAgent });
+  await architect.init({ task: session.task, sessionId: session.id, iteration: 0 });
+  const architectStart = Date.now();
+  let architectOutput;
+  try {
+    architectOutput = await architect.execute({
+      task: session.task,
+      onOutput: architectStall.onOutput,
+      researchContext,
+      discoverResult,
+      triageLevel
+    });
+  } catch (err) {
+    logger.warn(`Architect threw: ${err.message}`);
+    architectOutput = { ok: false, summary: `Architect error: ${err.message}`, result: { error: err.message } };
+  } finally {
+    architectStall.stop();
+  }
+  trackBudget({
+    role: "architect",
+    provider: architectProvider,
+    model: config?.roles?.architect?.model || coderRole.model,
+    result: architectOutput,
+    duration_ms: Date.now() - architectStart
+  });
+
+  await addCheckpoint(session, {
+    stage: "architect",
+    iteration: 0,
+    ok: architectOutput.ok,
+    provider: architectProvider,
+    model: config?.roles?.architect?.model || coderRole.model || null
+  });
+
+  // --- Interactive clarification loop ---
+  architectOutput = await handleArchitectClarification({
+    architectOutput, askQuestion, config, logger, emitter, eventBase, session,
+    architectOnOutput, architectProvider, coderRole, researchContext, discoverResult, triageLevel, trackBudget
+  });
+
+  const stageResult = {
+    ok: architectOutput.ok,
+    verdict: architectOutput.result?.verdict || null,
+    architecture: architectOutput.result?.architecture || null,
+    questions: architectOutput.result?.questions || []
+  };
+
+  emitProgress(
+    emitter,
+    makeEvent("architect:end", { ...eventBase, stage: "architect" }, {
+      status: architectOutput.ok ? "ok" : "fail",
+      message: architectOutput.ok ? "Architecture completed" : `Architecture failed: ${architectOutput.summary}`,
+      detail: { ...stageResult, provider: architectProvider, executorType: "agent" }
+    })
+  );
+
+  const architectContext = architectOutput.ok ? architectOutput.result : null;
+
+  // TSK-0339: ADR creation is now a tracker hook. The orchestrator ships the
+  // tradeoffs; the registered adapter decides whether/how to persist them
+  // (PG creates ADR cards, another tracker might create Jira issues, an
+  // unregistered tracker is a no-op).
+  const tradeoffs = architectOutput.result?.architecture?.tradeoffs;
+  if (architectOutput.ok
+    && architectOutput.result?.verdict === "ready"
+    && tradeoffs?.length > 0
+    && session.pg_task_id
+    && session.pg_project_id) {
+    try {
+      const adrResult = await getIntegration("tracker")?.createAdrsFromTradeoffs?.({
+        tradeoffs,
+        pgTaskId: session.pg_task_id,
+        pgProject: session.pg_project_id,
+        taskTitle: session.task,
+      });
+      if (adrResult) {
+        stageResult.adrs = adrResult;
+        if (adrResult.created > 0) {
+          logger.info(`Architect: created ${adrResult.created} ADR(s) in tracker`);
+        }
+      }
+    } catch (err) {
+      logger.warn(`Architect: failed to create ADRs: ${err.message}`);
+    }
+  }
+
+  return { architectContext, stageResult };
+}