karajan-code 4.70.4 → 5.0.1

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

@@ -1,439 +0,0 @@
-/**
- * Sonar stage logic + sonar retry logic.
- * Extracted from iteration-stages.js for maintainability.
- */
-
-import { SonarRole } from "../../roles/sonar-role.js";
-import { addCheckpoint, markSessionStatus, saveSession } from "../../session/store.js";
-import {
-  setReviewerFeedback, setSonarSummary, resetRetryCount, incrementRetryCount,
-} from "../../session/mutators.js";
-import { emitProgress, makeEvent } from "../../utils/events.js";
-import { invokeSolomon } from "../solomon-escalation.js";
-import { sonarUp, isSonarReachable } from "../../sonar/manager.js";
-import { canResolveSonarProjectKey } from "../../sonar/project-key.js";
-import { addEntries } from "../feedback-queue.js";
-
-/**
- * Detect sonar errors that are caused by a malformed `sonar-project.properties`
- * (or equivalent CLI args) — i.e. the scanner refused to start at all because
- * a path is wrong, a key is missing, or a value is invalid. These are NOT
- * findings about user code; they're the coder's own configuration mistake.
- *
- * When this fires, the right move is to send a precise diagnostic to the
- * coder so it fixes the config in the next iteration. Bypassing with the
- * Brain (or Solomon) on a config error means iterating 5 times against the
- * same wall — Sonar can't possibly succeed until the config is fixed.
- *
- * Returns a string with actionable guidance, or null when the error is a
- * different category (auth, network, scanner crash) that the coder can't
- * resolve from inside the codebase.
- */
-function detectSonarConfigError(rawError) {
-  if (!rawError || typeof rawError !== "string") return null;
-
-  // "Invalid value of sonar.tests for X — The folder 'tests' does not exist"
-  // (and its sonar.sources / sonar.exclusions / sonar.coverage.* siblings).
-  const invalidPath = rawError.match(/Invalid value of (sonar\.\w[\w.]*) for [^\n]+\nERROR The folder '([^']+)' does not exist/);
-  if (invalidPath) {
-    const [, key, dir] = invalidPath;
-    return [
-      `The Sonar property \`${key}=${dir}\` in sonar-project.properties points to a directory that doesn't exist.`,
-      `Fix one of these in the SAME iteration:`,
-      ` - Create the \`${dir}/\` directory in the project root, or`,
-      ` - Edit sonar-project.properties so \`${key}\` points to an existing directory, or`,
-      ` - Remove the \`${key}\` line entirely if the project legitimately has no such folder.`,
-      `Without this fix, Sonar will refuse to scan and the run will burn every remaining iteration on the same error.`,
-    ].join("\n");
-  }
-
-  // Fallback patterns for other config-shaped failures.
-  if (/Invalid value of sonar\./i.test(rawError)) {
-    return `Sonar refused to start because of an invalid value in sonar-project.properties. Read the scanner's error above and fix the offending key in this iteration: ${rawError.slice(0, 300)}`;
-  }
-  if (/sonar-project\.properties.*not found/i.test(rawError) || /No project key/i.test(rawError)) {
-    return `Sonar can't find a usable sonar-project.properties. Generate one at the project root with at minimum: sonar.projectKey, sonar.projectName, sonar.sources=src, and sonar.tests pointing to an EXISTING directory (or omit it).`;
-  }
-  return null;
-}
-
-async function handleSonarStalled({ repeatDetector, logger, emitter, eventBase, session, budgetSummary }) {
-  const repeatCounts = repeatDetector.getRepeatCounts();
-  const message = `No progress: SonarQube issues repeated ${repeatCounts.sonar} times.`;
-  logger.warn(message);
-  await markSessionStatus(session, "stalled");
-  const repeatState = repeatDetector.isStalled();
-  emitProgress(
-    emitter,
-    makeEvent("session:end", { ...eventBase, stage: "sonar" }, {
-      status: "stalled",
-      message,
-      detail: { reason: repeatState.reason, repeats: repeatCounts.sonar, budget: budgetSummary() }
-    })
-  );
-  return { action: "stalled", result: { approved: false, sessionId: session.id, reason: "stalled" } };
-}
-
-async function handleSonarRetryLimit({ config, logger, emitter, eventBase, session, iteration, askQuestion, task, maxSonarRetries, sonarResult, brainCtx }) {
-  // Brain: when enabled, skip Solomon — Brain handles via max_iterations
-  if (brainCtx?.enabled) {
-    logger.info("Brain: sonar retry limit reached — Brain will handle via max_iterations (Solomon bypassed)");
-    emitProgress(emitter, makeEvent("brain:sonar-retry-limit", { ...eventBase, stage: "sonar" }, {
-      message: `Sonar sub-loop limit reached (${session.sonar_retry_count}/${maxSonarRetries}) — Brain handling`,
-      detail: { subloop: "sonar", retryCount: session.sonar_retry_count, limit: maxSonarRetries, gateStatus: sonarResult.gateStatus }
-    }));
-    resetRetryCount(session, "sonar");
-    await saveSession(session);
-    return { action: "continue" };
-  }
-
-  emitProgress(
-    emitter,
-    makeEvent("solomon:escalate", { ...eventBase, stage: "sonar" }, {
-      message: `Sonar sub-loop limit reached (${session.sonar_retry_count}/${maxSonarRetries})`,
-      detail: { subloop: "sonar", retryCount: session.sonar_retry_count, limit: maxSonarRetries, gateStatus: sonarResult.gateStatus }
-    })
-  );
-
-  const solomonResult = await invokeSolomon({
-    config, logger, emitter, eventBase, stage: "sonar", askQuestion, session, iteration,
-    conflict: {
-      stage: "sonar",
-      task,
-      iterationCount: session.sonar_retry_count,
-      maxIterations: maxSonarRetries,
-      history: [{ agent: "sonar", feedback: session.last_sonar_summary }]
-    }
-  });
-
-  if (solomonResult.action === "pause") {
-    return { action: "pause", result: { paused: true, sessionId: session.id, question: solomonResult.question, context: "sonar_fail_fast" } };
-  }
-  if (solomonResult.action === "subtask") {
-    return { action: "pause", result: { paused: true, sessionId: session.id, subtask: solomonResult.subtask, context: "sonar_subtask" } };
-  }
-  if (solomonResult.action === "continue") {
-    if (solomonResult.humanGuidance) {
-      setReviewerFeedback(session, `${session.last_reviewer_feedback}\nUser guidance: ${solomonResult.humanGuidance}`);
-    }
-    resetRetryCount(session, "sonar");
-    await saveSession(session);
-    return { action: "continue" };
-  }
-
-  return null;
-}
-
-// KJC-BUG-0359 (#2158): with only the severity counts the coder guessed and
-// tripped sonar_repeat. Each issue travels in the feedback, its path without
-// the project key; past the cap, the rest is counted, never silently dropped.
-const MAX_ISSUES_FOR_CODER = 25;
-export function formatIssuesForCoder(issues) {
-  if (!Array.isArray(issues) || issues.length === 0) return "";
-  const lines = issues.slice(0, MAX_ISSUES_FOR_CODER).map((i) => {
-    const file = String(i.file ?? "").replace(/^[^:]*:/, "");
-    return `- [${i.severity}] ${i.rule} ${file}:${i.line} ${i.message}`;
-  });
-  const rest = issues.length - lines.length;
-  if (rest > 0) lines.push(`…and ${rest} more`);
-  return `\nIssues to fix:\n${lines.join("\n")}`;
-}
-
-async function handleSonarBlocking({ sonarResult, config, logger, emitter, eventBase, session, iteration, repeatDetector, budgetSummary, askQuestion, task, brainCtx }) {
-  // If the ONLY quality gate failure is coverage, treat as non-blocking warning
-  if (sonarResult.conditions) {
-    const failedConditions = sonarResult.conditions.filter(c => c.status === "ERROR");
-    const onlyCoverage = failedConditions.length > 0 && failedConditions.every(c =>
-      c.metricKey === "new_coverage" || c.metricKey === "coverage"
-    );
-    if (onlyCoverage) {
-      logger.warn("Quality gate failed on coverage only — treating as advisory (code quality is clean)");
-      emitProgress(emitter, makeEvent("sonar:end", { ...eventBase, stage: "sonar" }, {
-        status: "warn",
-        message: "Quality gate: coverage below threshold (advisory — code quality is clean)"
-      }));
-      setReviewerFeedback(session, null);
-      return { action: "ok", stageResult: { gateStatus: "WARN_COVERAGE", advisory: true } };
-    }
-  }
-
-  repeatDetector.addIteration(sonarResult.issues, []);
-  const repeatState = repeatDetector.isStalled();
-  if (repeatState.stalled) {
-    return handleSonarStalled({ repeatDetector, logger, emitter, eventBase, session, budgetSummary });
-  }
-
-  const summary = `Sonar gate blocking (${sonarResult.gateStatus}). Resolve critical findings first.${formatIssuesForCoder(sonarResult.issues)}`;
-  setReviewerFeedback(session, summary);
-  // Brain: push sonar feedback into queue when enabled
-  if (brainCtx?.enabled) {
-    const { processRoleOutput } = await import("../brain-coordinator.js");
-    processRoleOutput(brainCtx, { roleName: "sonar", output: { verdict: "fail", summary }, iteration });
-  }
-  incrementRetryCount(session, "sonar");
-  await saveSession(session);
-  const maxSonarRetries = config.session.max_sonar_retries ?? config.session.fail_fast_repeats;
-
-  if (session.sonar_retry_count >= maxSonarRetries) {
-    const result = await handleSonarRetryLimit({ config, logger, emitter, eventBase, session, iteration, askQuestion, task, maxSonarRetries, sonarResult, brainCtx });
-    if (result) return result;
-  }
-
-  return { action: "continue" };
-}
-
-export async function runSonarStage({ config, logger, emitter, eventBase, session, trackBudget, iteration, repeatDetector, budgetSummary, sonarState, askQuestion, task, brainCtx }) {
-  // Required-input guards. Without these, the bug class that broke the
-  // FASE-2 run on 2026-04-29 (run-hu-batch.js called runSonarStage
-  // without sonarState) is silent: the stage threw `Cannot read
-  // properties of undefined (reading 'issuesInitial')` later, the HU
-  // sub-pipeline's catch swallowed it as "non-blocking", and the
-  // Sonar gate effectively never ran. Failing fast here surfaces the
-  // missing wiring at the first iteration so any new caller fixes it
-  // before burning budget.
-  if (!sonarState || typeof sonarState !== "object") {
-    throw new Error("runSonarStage: `sonarState` is required (object with issuesInitial/issuesFinal slots — usually ctx.sonarState).");
-  }
-  if (!session) {
-    throw new Error("runSonarStage: `session` is required.");
-  }
-  logger.setContext({ iteration, stage: "sonar" });
-  emitProgress(
-    emitter,
-    makeEvent("sonar:start", { ...eventBase, stage: "sonar" }, {
-      message: "SonarQube scanning",
-      detail: { provider: "sonarqube", executorType: "local" }
-    })
-  );
-
-  // Auto-manage SonarQube: ensure it is reachable before scanning
-  const sonarHost = config.sonarqube?.host || "http://localhost:9000";
-
-  if (!await isSonarReachable(sonarHost)) {
-    logger.info("SonarQube not reachable, attempting to start...");
-    emitProgress(emitter, makeEvent("sonar:start", { ...eventBase, stage: "sonar" }, { message: "Starting SonarQube Docker..." }));
-
-    const upResult = await sonarUp(sonarHost);
-    if (upResult.exitCode !== 0) {
-      logger.warn(`SonarQube could not be started: ${upResult.stderr || upResult.stdout}`);
-      emitProgress(emitter, makeEvent("sonar:end", { ...eventBase, stage: "sonar" }, {
-        status: "skip",
-        message: "SonarQube not available — install Docker and run 'kj sonar start' to enable static analysis"
-      }));
-      return { action: "ok", stageResult: { gateStatus: "SKIPPED", reason: "SonarQube not available" } };
-    }
-
-    let ready = false;
-    for (let attempt = 0; attempt < 12; attempt++) {
-      await new Promise(r => setTimeout(r, 5000));
-      if (await isSonarReachable(sonarHost)) { ready = true; break; }
-    }
-    if (!ready) {
-      logger.warn("SonarQube started but not ready after 60s");
-      emitProgress(emitter, makeEvent("sonar:end", { ...eventBase, stage: "sonar" }, {
-        status: "skip", message: "SonarQube started but not ready — will retry next iteration"
-      }));
-      return { action: "ok", stageResult: { gateStatus: "PENDING", reason: "SonarQube starting up" } };
-    }
-    logger.info("SonarQube is ready");
-  }
-
-  // 2026-05-07 (N4 dogfooding): when the working tree has neither a git
-  // remote nor an explicit `sonarqube.project_key`, the scanner inside
-  // SonarRole would throw "Missing git remote.origin.url" — the Brain
-  // logs that as a sonar error, the iteration cap is reached, and the
-  // run finalises as "approved" by exhaustion fallback even though no
-  // sonar gate ever ran. KJC-TSK-0373 silenced this for the audit
-  // collector but the run loop hit it on the parallel code path.
-  // Skipping cleanly here means the gate reports "SKIPPED" once and
-  // the iteration loop progresses on the next stage.
-  if (!await canResolveSonarProjectKey(config)) {
-    logger.info("Sonar gate skipped: no git remote and no sonarqube.project_key configured");
-    emitProgress(emitter, makeEvent("sonar:end", { ...eventBase, stage: "sonar" }, {
-      status: "skip",
-      message: "Sonar skipped — no git remote and no sonarqube.project_key configured (run `git remote add origin …` or set `sonarqube.project_key` to enable)"
-    }));
-    return { action: "ok", stageResult: { gateStatus: "SKIPPED", reason: "no git remote and no sonarqube.project_key configured" } };
-  }
-
-  const sonarRole = new SonarRole({ config, logger, emitter });
-  await sonarRole.init({ iteration });
-  const sonarStart = Date.now();
-  let sonarOutput;
-  try {
-    sonarOutput = await sonarRole.run();
-  } catch (err) {
-    logger.warn(`Sonar threw: ${err.message}`);
-    sonarOutput = { ok: false, result: { error: err.message }, summary: `Sonar error: ${err.message}` };
-  }
-  trackBudget({ role: "sonar", provider: "sonar", result: sonarOutput, duration_ms: Date.now() - sonarStart });
-  const sonarResult = sonarOutput.result;
-
-  if (!sonarResult.gateStatus && sonarResult.error) {
-    const isTokenError = /unable to resolve sonar token/i.test(sonarResult.error);
-    const errorMessage = isTokenError
-      ? "SonarQube is running but no authentication token is configured. Fix: run 'kj init' to configure it, or set KJ_SONAR_TOKEN env var, or add sonarqube.token to ~/.karajan/kj.config.yml."
-      : `Sonar scan failed: ${sonarResult.error}`;
-
-    emitProgress(
-      emitter,
-      makeEvent("sonar:end", { ...eventBase, stage: "sonar" }, {
-        status: "fail",
-        message: errorMessage
-      })
-    );
-
-    // Brain: when enabled, skip Solomon for sonar errors — Brain handles via max_iterations.
-    if (brainCtx?.enabled) {
-      // BUT: if the error is a *configuration* mistake (sonar.tests pointing to a
-      // missing folder, etc.), iterating won't help — Sonar will refuse to scan
-      // again and again. Push a typed feedback entry into the brain queue so the
-      // next coder iteration sees a concrete fix-this-config diagnostic AND so
-      // handleMaxIterations doesn't auto-finalize as approved (config is a
-      // "correctness" category — pending entries block approval).
-      const configHint = detectSonarConfigError(sonarResult.error);
-      if (configHint) {
-        addEntries(brainCtx.feedbackQueue, [{
-          source: "sonar",
-          severity: "high",
-          category: "correctness",
-          description: configHint,
-          iteration
-        }]);
-        setReviewerFeedback(session, configHint);
-        logger.info("Brain: sonar config error detected — feeding fix-this-config diagnostic to coder");
-        emitProgress(emitter, makeEvent("brain:sonar-config-error", { ...eventBase, stage: "sonar" }, {
-          message: "Sonar refused to scan — config error fed back to coder",
-          detail: { hint: configHint.slice(0, 240) }
-        }));
-        return { action: "continue" };
-      }
-      logger.info("Brain: sonar error — Brain will handle (Solomon bypassed)");
-      emitProgress(emitter, makeEvent("brain:sonar-error", { ...eventBase, stage: "sonar" }, {
-        message: `Sonar error — Brain handling: ${errorMessage.slice(0, 200)}`,
-        detail: { error: errorMessage }
-      }));
-      return { action: "continue" };
-    }
-
-    // Let Solomon decide: continue without sonar or stop
-    const solomonResult = await invokeSolomon({
-      config, logger, emitter, eventBase, stage: "sonar_error", askQuestion, session, iteration,
-      conflict: {
-        stage: "sonar_error",
-        task,
-        iterationCount: iteration,
-        maxIterations: config.max_iterations,
-        history: [{ agent: "sonar", feedback: errorMessage }]
-      }
-    });
-
-    if (solomonResult.action === "approve" || solomonResult.action === "continue") {
-      logger.info(`Solomon decided to continue without SonarQube: ${solomonResult.ruling?.result?.conditions?.join(", ") || "no conditions"}`);
-      return { action: "continue" };
-    }
-
-    if (solomonResult.action === "pause") {
-      return { action: "return", result: { paused: true, sessionId: session.id, question: solomonResult.question, context: "sonar_error" } };
-    }
-
-    // Solomon couldn't resolve — fail
-    await markSessionStatus(session, "failed");
-    throw new Error(errorMessage);
-  }
-
-  setSonarSummary(session, sonarOutput.summary);
-  if (typeof sonarResult.openIssuesTotal === "number") {
-    if (sonarState.issuesInitial === null) {
-      sonarState.issuesInitial = sonarResult.openIssuesTotal;
-    }
-    sonarState.issuesFinal = sonarResult.openIssuesTotal;
-  }
-  await addCheckpoint(session, {
-    stage: "sonar",
-    iteration,
-    project_key: sonarResult.projectKey,
-    quality_gate: sonarResult.gateStatus,
-    open_issues: sonarResult.openIssuesTotal,
-    provider: "sonar",
-    model: null
-  });
-
-  emitProgress(
-    emitter,
-    makeEvent("sonar:end", { ...eventBase, stage: "sonar" }, {
-      status: sonarResult.blocking ? "fail" : "ok",
-      message: `Quality gate: ${sonarResult.gateStatus}`,
-      detail: { projectKey: sonarResult.projectKey, gateStatus: sonarResult.gateStatus, openIssues: sonarResult.openIssuesTotal, provider: "sonarqube", executorType: "local" }
-    })
-  );
-
-  if (sonarResult.blocking) {
-    return handleSonarBlocking({ sonarResult, config, logger, emitter, eventBase, session, iteration, repeatDetector, budgetSummary, askQuestion, task, brainCtx });
-  }
-
-  // Sonar passed — reset retry counter
-  resetRetryCount(session, "sonar");
-  const issuesInitial = sonarState.issuesInitial ?? sonarResult.openIssuesTotal ?? 0;
-  const issuesFinal = sonarState.issuesFinal ?? sonarResult.openIssuesTotal ?? 0;
-  const stageResult = {
-    gateStatus: sonarResult.gateStatus,
-    // KJC-TSK-0839: the key and the files the scan indexed, for the verdict's per-source proof.
-    projectKey: sonarResult.projectKey,
-    indexedFiles: sonarResult.indexedFiles ?? [],
-    openIssues: sonarResult.openIssuesTotal,
-    issuesInitial,
-    issuesFinal,
-    issuesResolved: Math.max(issuesInitial - issuesFinal, 0)
-  };
-
-  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",
-      detail: { provider: "sonarcloud", executorType: "local" }
-    })
-  );
-
-  const { runSonarCloudScan } = await import("../../sonar/cloud-scanner.js");
-  const scanStart = Date.now();
-  let result;
-  try {
-    result = await runSonarCloudScan(config);
-  } catch (err) {
-    logger.warn(`SonarCloud threw: ${err.message}`);
-    result = { ok: false, error: err.message };
-  }
-  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, provider: "sonarcloud", executorType: "local" }
-    })
-  );
-
-  // SonarCloud is advisory — never blocks the pipeline
-  return { action: "ok", stageResult: { ok: result.ok, projectKey: result.projectKey, message } };
-}

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

@@ -1,84 +0,0 @@
-/**
- * StageExecutor class wrappers for the first 3 pipeline stages adopted
- * under KJC-TSK-0328 (triage, coder, reviewer).
- *
- * Why these 3:
- *   - Triage is the first stage a pipeline runs — proves the registry is
- *     consulted before any execution.
- *   - Coder runs inside the iteration loop — proves the contract works
- *     for stages that run N times per pipeline.
- *   - Reviewer has the most complex signature (fetchReviewDiff + handle
- *     rejection + Solomon escalation path) — proves the contract does not
- *     artificially limit stage complexity.
- *
- * Contract: each class extends StageExecutor and delegates `execute(ctx)`
- * to the existing `run{Stage}Stage` function. This keeps back-compat:
- * flow-runner can still call the function directly during the transition,
- * while the registry path is available for future iterations (and for
- * anyone writing a new stage).
- *
- * A shared `stageRegistry` singleton is exported with the 3 stages
- * pre-registered so callers do `stageRegistry.get("coder")` without
- * rebuilding the registry.
- *
- * Future Oleada 3 will finish the migration by having flow-runner ONLY
- * use the registry path, deleting the direct function imports.
- */
-
-import { StageExecutor, StageRegistry } from "./stage-executor.js";
-
-// TSK-0336: stage subclasses use DYNAMIC imports inside execute() so that
-// loading this module does not pull in the whole roles/ + agents/ graph.
-// Orchestrator tests mock role/agent modules partially — eagerly importing
-// triage-stage / coder-stage / reviewer-stage here would cascade through
-// agent-role.js → BaseRole and crash those partial mocks. Deferring the
-// import keeps canRun/construction cheap and the test surface unchanged.
-export class TriageStage extends StageExecutor {
-  constructor() { super("triage"); }
-  canRun(ctx) {
-    // Triage runs when the triage pipeline flag is on (default: true for
-    // kj_run; tests may flip it off via config.pipeline.triage.enabled).
-    return ctx?.pipelineFlags?.triageEnabled !== false;
-  }
-  async execute(ctx) {
-    // Import via the pre-loop-stages barrel so test mocks that target
-    // `src/orchestrator/pre-loop-stages.js` (the historical surface) still
-    // apply when a stage is invoked via the registry.
-    const { runTriageStage } = await import("../pre-loop-stages.js");
-    return runTriageStage(ctx);
-  }
-}
-
-export class CoderStage extends StageExecutor {
-  constructor() { super("coder"); }
-  canRun(ctx) {
-    // Coder always runs unless the analysis-only path disables it.
-    return ctx?.pipelineFlags?.coderRequired !== false;
-  }
-  async execute(ctx) {
-    // Import via iteration-stages barrel for the same reason as TriageStage —
-    // preserve the existing mock surface used by orchestrator unit tests.
-    const { runCoderStage } = await import("../iteration-stages.js");
-    return runCoderStage(ctx);
-  }
-}
-
-export class ReviewerStage extends StageExecutor {
-  constructor() { super("reviewer"); }
-  canRun(ctx) {
-    return ctx?.pipelineFlags?.reviewerEnabled !== false;
-  }
-  async execute(ctx) {
-    const { runReviewerStage } = await import("../iteration-stages.js");
-    return runReviewerStage(ctx);
-  }
-}
-
-/**
- * Shared registry singleton with the 3 pre-registered stages. New stages
- * should be added here as they migrate to the StageExecutor contract.
- */
-export const stageRegistry = new StageRegistry();
-stageRegistry.register(new TriageStage());
-stageRegistry.register(new CoderStage());
-stageRegistry.register(new ReviewerStage());

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

@@ -1,155 +0,0 @@
-/**
- * StageExecutor — contract for per-stage orchestration logic (KJC-TSK-0315).
- *
- * The current orchestrator branches on a flat `pipelineFlags` object inside a
- * monolithic `runFlow`. This contract is the first step toward replacing those
- * branches with self-describing stage objects: each stage declares whether it
- * wants to run (`canRun`), how to run (`execute`), and what to do on failure
- * (`onFailure`). The orchestrator iterates a registry of stages instead of
- * owning knowledge of every pipeline flag.
- *
- * Scope for this PR: define the contract + a tiny registry. Existing stage
- * functions (e.g. src/orchestrator/stages/triage-stage.js) continue to be
- * called directly by flow-runner.js; future refactors can migrate them to
- * StageExecutor class form incrementally without touching the orchestrator.
- *
- * @typedef {Object} StageContext
- * @property {Object} config
- * @property {Object} session
- * @property {Object} logger
- * @property {Object} emitter
- * @property {Object} eventBase
- * @property {Object} pipelineFlags
- * @property {Object} stageResults
- * @property {Function} [trackBudget]
- * @property {Function} [askQuestion]
- * @property {Object} [brainCtx]
- * @property {number} [iteration]
- *
- * @typedef {Object} StageOutcome
- * @property {string} status - "ok" | "skipped" | "failed"
- * @property {*} [result]
- * @property {string} [detail]
- */
-
-export class StageExecutor {
-  /**
-   * @param {string} name - unique stage slug (e.g. "triage", "reviewer")
-   */
-  constructor(name) {
-    if (!name || typeof name !== "string") {
-      throw new Error("StageExecutor requires a non-empty name");
-    }
-    this.name = name;
-  }
-
-  /**
-   * Decide whether this stage should run for the current context. Default is
-   * true; subclasses override to gate on pipelineFlags or task type.
-   * @param {StageContext} _ctx
-   * @returns {boolean | Promise<boolean>}
-   */
-  canRun(_ctx) {
-    return true;
-  }
-
-  /**
-   * Run the stage. MUST be overridden. Return a StageOutcome describing what
-   * happened; the runner persists `result` under ctx.stageResults[this.name].
-   * @param {StageContext} _ctx
-   * @returns {Promise<StageOutcome>}
-   */
-  async execute(_ctx) {
-    throw new Error(`StageExecutor(${this.name}).execute() not implemented`);
-  }
-
-  /**
-   * Error hook. Default behaviour rethrows so the orchestrator's global
-   * failure handling kicks in; subclasses can override to recover silently,
-   * return a partial result, or escalate to Solomon before rethrowing.
-   * @param {Error} err
-   * @param {StageContext} _ctx
-   * @returns {Promise<StageOutcome | void>}
-   */
-   
-  async onFailure(err, _ctx) {
-    throw err;
-  }
-}
-
-/**
- * Registry of StageExecutor instances keyed by stage name. Kept intentionally
- * small — the orchestrator iterates `list()` in declared order and invokes
- * `canRun` / `execute` / `onFailure` as needed.
- */
-export class StageRegistry {
-  constructor() {
-    /** @type {Map<string, StageExecutor>} */
-    this._stages = new Map();
-  }
-
-  /**
-   * @param {StageExecutor} stage
-   */
-  register(stage) {
-    if (!(stage instanceof StageExecutor)) {
-      throw new Error("StageRegistry.register(): argument must be a StageExecutor");
-    }
-    if (this._stages.has(stage.name)) {
-      throw new Error(`StageRegistry: stage "${stage.name}" already registered`);
-    }
-    this._stages.set(stage.name, stage);
-    return this;
-  }
-
-  /**
-   * @param {string} name
-   * @returns {StageExecutor | undefined}
-   */
-  get(name) {
-    return this._stages.get(name);
-  }
-
-  /**
-   * @returns {StageExecutor[]}
-   */
-  list() {
-    return [...this._stages.values()];
-  }
-
-  /**
-   * @param {string} name
-   * @returns {boolean}
-   */
-  has(name) {
-    return this._stages.has(name);
-  }
-
-  get size() {
-    return this._stages.size;
-  }
-}
-
-/**
- * Run a stage via the contract. Centralizes the canRun/execute/onFailure
- * dance so future call sites don't reinvent it. Returns null when `canRun`
- * returns false (stage skipped).
- *
- * @param {StageExecutor} stage
- * @param {StageContext} ctx
- * @returns {Promise<StageOutcome | null>}
- */
-export async function runStage(stage, ctx) {
-  if (!(stage instanceof StageExecutor)) {
-    throw new Error("runStage(): first argument must be a StageExecutor");
-  }
-  const shouldRun = await stage.canRun(ctx);
-  if (!shouldRun) return null;
-  try {
-    return await stage.execute(ctx);
-  } catch (err) {
-    const recovered = await stage.onFailure(err, ctx);
-    if (recovered !== undefined) return recovered;
-    throw err;
-  }
-}