karajan-code 1.16.0 → 1.17.0

package/src/orchestrator.js

@@ -26,97 +26,93 @@ import { applyPolicies } from "./guards/policy-resolver.js";
 import { resolveReviewProfile } from "./review/profiles.js";
 import { CoderRole } from "./roles/coder-role.js";
 import { invokeSolomon } from "./orchestrator/solomon-escalation.js";
-import { runTriageStage, runResearcherStage, runPlannerStage, runDiscoverStage } from "./orchestrator/pre-loop-stages.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 { runTesterStage, runSecurityStage } from "./orchestrator/post-loop-stages.js";
 import { waitForCooldown, MAX_STANDBY_RETRIES } from "./orchestrator/standby.js";
 
 
+// --- Extracted helper functions (pure refactoring, zero behavior change) ---
 
-export async function runFlow({ task, config, logger, flags = {}, emitter = null, askQuestion = null, pgTaskId = null, pgProject = null }) {
+function resolvePipelineFlags(config) {
+  return {
+    plannerEnabled: Boolean(config.pipeline?.planner?.enabled),
+    refactorerEnabled: Boolean(config.pipeline?.refactorer?.enabled),
+    researcherEnabled: Boolean(config.pipeline?.researcher?.enabled),
+    testerEnabled: Boolean(config.pipeline?.tester?.enabled),
+    securityEnabled: Boolean(config.pipeline?.security?.enabled),
+    reviewerEnabled: config.pipeline?.reviewer?.enabled !== false,
+    discoverEnabled: Boolean(config.pipeline?.discover?.enabled),
+    architectEnabled: Boolean(config.pipeline?.architect?.enabled),
+  };
+}
+
+async function handleDryRun({ task, config, flags, emitter, pipelineFlags }) {
+  const { plannerEnabled, refactorerEnabled, researcherEnabled, testerEnabled, securityEnabled, reviewerEnabled, discoverEnabled, architectEnabled } = pipelineFlags;
   const plannerRole = resolveRole(config, "planner");
   const coderRole = resolveRole(config, "coder");
   const reviewerRole = resolveRole(config, "reviewer");
   const refactorerRole = resolveRole(config, "refactorer");
-  let plannerEnabled = Boolean(config.pipeline?.planner?.enabled);
-  let refactorerEnabled = Boolean(config.pipeline?.refactorer?.enabled);
-  let researcherEnabled = Boolean(config.pipeline?.researcher?.enabled);
-  let testerEnabled = Boolean(config.pipeline?.tester?.enabled);
-  let securityEnabled = Boolean(config.pipeline?.security?.enabled);
-  let reviewerEnabled = config.pipeline?.reviewer?.enabled !== false;
-  let discoverEnabled = Boolean(config.pipeline?.discover?.enabled);
-  // Triage is always mandatory — it classifies taskType for policy resolution
   const triageEnabled = true;
 
-  // --- Dry-run: return summary without executing anything ---
-  if (flags.dryRun) {
-    const dryRunPolicies = applyPolicies({
-      taskType: flags.taskType || config.taskType || null,
-      policies: config.policies,
-    });
-    const projectDir = config.projectDir || process.cwd();
-    const { rules: reviewRules } = await resolveReviewProfile({ mode: config.review_mode, projectDir });
-    const coderRules = await loadFirstExisting(resolveRoleMdPath("coder", projectDir));
-    const coderPrompt = buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology, serenaEnabled: Boolean(config.serena?.enabled) });
-    const reviewerPrompt = buildReviewerPrompt({ task, diff: "(dry-run: no diff)", reviewRules, mode: config.review_mode, serenaEnabled: Boolean(config.serena?.enabled) });
-
-    const summary = {
-      dry_run: true,
-      task,
-      policies: dryRunPolicies,
-      roles: {
-        planner: plannerRole,
-        coder: coderRole,
-        reviewer: reviewerRole,
-        refactorer: refactorerRole
-      },
-      pipeline: {
-        discover_enabled: discoverEnabled,
-        triage_enabled: triageEnabled,
-        planner_enabled: plannerEnabled,
-        refactorer_enabled: refactorerEnabled,
-        sonar_enabled: Boolean(config.sonarqube?.enabled),
-        reviewer_enabled: reviewerEnabled,
-        researcher_enabled: researcherEnabled,
-        tester_enabled: testerEnabled,
-        security_enabled: securityEnabled,
-        solomon_enabled: Boolean(config.pipeline?.solomon?.enabled)
-      },
-      limits: {
-        max_iterations: config.max_iterations,
-        max_iteration_minutes: config.session?.max_iteration_minutes,
-        max_total_minutes: config.session?.max_total_minutes,
-        max_sonar_retries: config.session?.max_sonar_retries,
-        max_reviewer_retries: config.session?.max_reviewer_retries,
-        max_tester_retries: config.session?.max_tester_retries,
-        max_security_retries: config.session?.max_security_retries
-      },
-      prompts: {
-        coder: coderPrompt,
-        reviewer: reviewerPrompt
-      },
-      git: config.git
-    };
+  const dryRunPolicies = applyPolicies({
+    taskType: flags.taskType || config.taskType || null,
+    policies: config.policies,
+  });
+  const projectDir = config.projectDir || process.cwd();
+  const { rules: reviewRules } = await resolveReviewProfile({ mode: config.review_mode, projectDir });
+  const coderRules = await loadFirstExisting(resolveRoleMdPath("coder", projectDir));
+  const coderPrompt = buildCoderPrompt({ task, coderRules, methodology: config.development?.methodology, serenaEnabled: Boolean(config.serena?.enabled) });
+  const reviewerPrompt = buildReviewerPrompt({ task, diff: "(dry-run: no diff)", reviewRules, mode: config.review_mode, serenaEnabled: Boolean(config.serena?.enabled) });
 
-    emitProgress(
-      emitter,
-      makeEvent("dry-run:summary", { sessionId: null, iteration: 0, stage: "dry-run", startedAt: Date.now() }, {
-        message: "Dry-run complete — no changes made",
-        detail: summary
-      })
-    );
+  const summary = {
+    dry_run: true,
+    task,
+    policies: dryRunPolicies,
+    roles: { planner: plannerRole, coder: coderRole, reviewer: reviewerRole, refactorer: refactorerRole },
+    pipeline: {
+      discover_enabled: discoverEnabled,
+      architect_enabled: architectEnabled,
+      triage_enabled: triageEnabled,
+      planner_enabled: plannerEnabled,
+      refactorer_enabled: refactorerEnabled,
+      sonar_enabled: Boolean(config.sonarqube?.enabled),
+      reviewer_enabled: reviewerEnabled,
+      researcher_enabled: researcherEnabled,
+      tester_enabled: testerEnabled,
+      security_enabled: securityEnabled,
+      solomon_enabled: Boolean(config.pipeline?.solomon?.enabled)
+    },
+    limits: {
+      max_iterations: config.max_iterations,
+      max_iteration_minutes: config.session?.max_iteration_minutes,
+      max_total_minutes: config.session?.max_total_minutes,
+      max_sonar_retries: config.session?.max_sonar_retries,
+      max_reviewer_retries: config.session?.max_reviewer_retries,
+      max_tester_retries: config.session?.max_tester_retries,
+      max_security_retries: config.session?.max_security_retries
+    },
+    prompts: { coder: coderPrompt, reviewer: reviewerPrompt },
+    git: config.git
+  };
 
-    return summary;
-  }
+  emitProgress(
+    emitter,
+    makeEvent("dry-run:summary", { sessionId: null, iteration: 0, stage: "dry-run", startedAt: Date.now() }, {
+      message: "Dry-run complete — no changes made",
+      detail: summary
+    })
+  );
 
-  const repeatDetector = new RepeatDetector({ threshold: getRepeatThreshold(config) });
-  const coderRoleInstance = new CoderRole({ config, logger, emitter, createAgentFn: createAgent });
-  const startedAt = Date.now();
-  const eventBase = { sessionId: null, iteration: 0, stage: null, startedAt };
+  return summary;
+}
+
+function createBudgetManager({ config, emitter, eventBase }) {
   const budgetTracker = new BudgetTracker({ pricing: config?.budget?.pricing });
   const budgetLimit = Number(config?.max_budget_usd);
   const hasBudgetLimit = Number.isFinite(budgetLimit) && budgetLimit >= 0;
   const warnThresholdPct = Number(config?.budget?.warn_threshold_pct ?? 80);
+  let stageCounter = 0;
 
   function budgetSummary() {
     const s = budgetTracker.summary();
@@ -124,7 +120,6 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
     return s;
   }
 
-  let stageCounter = 0;
   function trackBudget({ role, provider, model, result, duration_ms }) {
     const metrics = extractUsageMetrics(result, model);
     budgetTracker.record({ role, provider, ...metrics, duration_ms, stage_index: stageCounter++ });
@@ -132,7 +127,8 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
     if (!hasBudgetLimit) return;
     const totalCost = budgetTracker.total().cost_usd;
     const pctUsed = budgetLimit === 0 ? 100 : (totalCost / budgetLimit) * 100;
-    const status = totalCost > budgetLimit ? "fail" : pctUsed >= warnThresholdPct ? "paused" : "ok";
+    const warnOrOk = pctUsed >= warnThresholdPct ? "paused" : "ok";
+    const status = totalCost > budgetLimit ? "fail" : warnOrOk;
     emitProgress(
       emitter,
       makeEvent("budget:update", { ...eventBase, stage: role }, {
@@ -149,6 +145,10 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
     );
   }
 
+  return { budgetTracker, budgetLimit, budgetSummary, trackBudget };
+}
+
+async function initializeSession({ task, config, flags, pgTaskId, pgProject }) {
   const baseRef = await computeBaseRef({ baseBranch: config.base_branch, baseRef: flags.baseRef || null });
   const sessionInit = {
     task,
@@ -168,146 +168,124 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
   };
   if (pgTaskId) sessionInit.pg_task_id = pgTaskId;
   if (pgProject) sessionInit.pg_project_id = pgProject;
-  const session = await createSession(sessionInit);
-
-  eventBase.sessionId = session.id;
+  return createSession(sessionInit);
+}
 
-  // --- Planning Game: mark card as In Progress ---
-  let pgCard = null;
-  if (pgTaskId && pgProject && config.planning_game?.enabled !== false) {
-    try {
-      const { fetchCard, updateCard } = await import("./planning-game/client.js");
-      pgCard = await fetchCard({ projectId: pgProject, cardId: pgTaskId });
-      if (pgCard && pgCard.status !== "In Progress") {
-        await updateCard({
-          projectId: pgProject,
-          cardId: pgTaskId,
-          firebaseId: pgCard.firebaseId,
-          updates: {
-            status: "In Progress",
-            startDate: new Date().toISOString(),
-            developer: "dev_016",
-            codeveloper: config.planning_game?.codeveloper || null
-          }
-        });
-        logger.info(`Planning Game: ${pgTaskId} → In Progress`);
-      }
-    } catch (err) {
-      logger.warn(`Planning Game: could not update ${pgTaskId}: ${err.message}`);
+async function markPgCardInProgress({ pgTaskId, pgProject, config, logger }) {
+  if (!pgTaskId || !pgProject || config.planning_game?.enabled === false) {
+    return null;
+  }
+  try {
+    const { fetchCard, updateCard } = await import("./planning-game/client.js");
+    const pgCard = await fetchCard({ projectId: pgProject, cardId: pgTaskId });
+    if (pgCard && pgCard.status !== "In Progress") {
+      await updateCard({
+        projectId: pgProject,
+        cardId: pgTaskId,
+        firebaseId: pgCard.firebaseId,
+        updates: {
+          status: "In Progress",
+          startDate: new Date().toISOString(),
+          developer: "dev_016",
+          codeveloper: config.planning_game?.codeveloper || null
+        }
+      });
+      logger.info(`Planning Game: ${pgTaskId} → In Progress`);
     }
+    return pgCard;
+  } catch (err) {
+    logger.warn(`Planning Game: could not update ${pgTaskId}: ${err.message}`);
+    return null;
   }
-  session.pg_card = pgCard || null;
+}
 
-  emitProgress(
-    emitter,
-    makeEvent("session:start", eventBase, {
-      message: "Session started",
-      detail: {
-        task,
-        coder: coderRole.provider,
-        reviewer: reviewerRole.provider,
-        maxIterations: config.max_iterations
-      }
-    })
-  );
+function applyTriageOverrides(pipelineFlags, roleOverrides) {
+  const keys = ["plannerEnabled", "researcherEnabled", "architectEnabled", "refactorerEnabled", "reviewerEnabled", "testerEnabled", "securityEnabled"];
+  for (const key of keys) {
+    if (roleOverrides[key] !== undefined) {
+      pipelineFlags[key] = roleOverrides[key];
+    }
+  }
+}
 
-  // Accumulate stage results for final summary
-  const stageResults = {};
-  const sonarState = { issuesInitial: null, issuesFinal: null };
+async function handlePgDecomposition({ triageResult, pgTaskId, pgProject, config, askQuestion, emitter, eventBase, session, stageResults, logger }) {
+  const shouldDecompose = triageResult.stageResult?.shouldDecompose
+    && triageResult.stageResult.subtasks?.length > 1
+    && pgTaskId
+    && pgProject
+    && config.planning_game?.enabled !== false
+    && askQuestion;
+
+  if (!shouldDecompose) return;
+
+  try {
+    const { buildDecompositionQuestion, createDecompositionSubtasks } = await import("./planning-game/decomposition.js");
+    const { createCard, relateCards, fetchCard } = await import("./planning-game/client.js");
+
+    const question = buildDecompositionQuestion(triageResult.stageResult.subtasks, pgTaskId);
+    const answer = await askQuestion(question);
+
+    if (answer && (answer.trim().toLowerCase() === "yes" || answer.trim().toLowerCase() === "sí" || answer.trim().toLowerCase() === "si")) {
+      const parentCard = await fetchCard({ projectId: pgProject, cardId: pgTaskId }).catch(() => null);
+      const createdSubtasks = await createDecompositionSubtasks({
+        client: { createCard, relateCards },
+        projectId: pgProject,
+        parentCardId: pgTaskId,
+        parentFirebaseId: parentCard?.firebaseId || null,
+        subtasks: triageResult.stageResult.subtasks,
+        epic: parentCard?.epic || null,
+        sprint: parentCard?.sprint || null,
+        codeveloper: config.planning_game?.codeveloper || null
+      });
 
-  // --- Discover (pre-triage, opt-in) ---
-  if (flags.enableDiscover !== undefined) discoverEnabled = Boolean(flags.enableDiscover);
-  if (discoverEnabled) {
-    const discoverResult = await runDiscoverStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget });
-    stageResults.discover = discoverResult.stageResult;
-  }
+      stageResults.triage.pgSubtasks = createdSubtasks;
+      logger.info(`Planning Game: created ${createdSubtasks.length} subtasks from decomposition`);
 
-  if (triageEnabled) {
-    const triageResult = await runTriageStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget });
-    if (triageResult.roleOverrides.plannerEnabled !== undefined) plannerEnabled = triageResult.roleOverrides.plannerEnabled;
-    if (triageResult.roleOverrides.researcherEnabled !== undefined) researcherEnabled = triageResult.roleOverrides.researcherEnabled;
-    if (triageResult.roleOverrides.refactorerEnabled !== undefined) refactorerEnabled = triageResult.roleOverrides.refactorerEnabled;
-    if (triageResult.roleOverrides.reviewerEnabled !== undefined) reviewerEnabled = triageResult.roleOverrides.reviewerEnabled;
-    if (triageResult.roleOverrides.testerEnabled !== undefined) testerEnabled = triageResult.roleOverrides.testerEnabled;
-    if (triageResult.roleOverrides.securityEnabled !== undefined) securityEnabled = triageResult.roleOverrides.securityEnabled;
-    stageResults.triage = triageResult.stageResult;
-
-    // --- PG decomposition: offer to create subtasks in Planning Game ---
-    const pgDecompose = triageResult.stageResult?.shouldDecompose
-      && triageResult.stageResult.subtasks?.length > 1
-      && pgTaskId
-      && pgProject
-      && config.planning_game?.enabled !== false
-      && askQuestion;
-
-    if (pgDecompose) {
-      try {
-        const { buildDecompositionQuestion, createDecompositionSubtasks } = await import("./planning-game/decomposition.js");
-        const { createCard, relateCards, fetchCard } = await import("./planning-game/client.js");
-
-        const question = buildDecompositionQuestion(triageResult.stageResult.subtasks, pgTaskId);
-        const answer = await askQuestion(question);
-
-        if (answer && (answer.trim().toLowerCase() === "yes" || answer.trim().toLowerCase() === "sí" || answer.trim().toLowerCase() === "si")) {
-          const parentCard = await fetchCard({ projectId: pgProject, cardId: pgTaskId }).catch(() => null);
-          const createdSubtasks = await createDecompositionSubtasks({
-            client: { createCard, relateCards },
-            projectId: pgProject,
-            parentCardId: pgTaskId,
-            parentFirebaseId: parentCard?.firebaseId || null,
-            subtasks: triageResult.stageResult.subtasks,
-            epic: parentCard?.epic || null,
-            sprint: parentCard?.sprint || null,
-            codeveloper: config.planning_game?.codeveloper || null
-          });
+      emitProgress(
+        emitter,
+        makeEvent("pg:decompose", { ...eventBase, stage: "triage" }, {
+          message: `Created ${createdSubtasks.length} subtasks in Planning Game`,
+          detail: { subtasks: createdSubtasks.map((s) => ({ cardId: s.cardId, title: s.title })) }
+        })
+      );
 
-          stageResults.triage.pgSubtasks = createdSubtasks;
-          logger.info(`Planning Game: created ${createdSubtasks.length} subtasks from decomposition`);
-
-          emitProgress(
-            emitter,
-            makeEvent("pg:decompose", { ...eventBase, stage: "triage" }, {
-              message: `Created ${createdSubtasks.length} subtasks in Planning Game`,
-              detail: { subtasks: createdSubtasks.map((s) => ({ cardId: s.cardId, title: s.title })) }
-            })
-          );
-
-          await addCheckpoint(session, {
-            stage: "pg-decompose",
-            subtasksCreated: createdSubtasks.length,
-            cardIds: createdSubtasks.map((s) => s.cardId)
-          });
-        }
-      } catch (err) {
-        logger.warn(`Planning Game decomposition failed: ${err.message}`);
-      }
+      await addCheckpoint(session, {
+        stage: "pg-decompose",
+        subtasksCreated: createdSubtasks.length,
+        cardIds: createdSubtasks.map((s) => s.cardId)
+      });
     }
+  } catch (err) {
+    logger.warn(`Planning Game decomposition failed: ${err.message}`);
   }
+}
 
-  if (flags.enablePlanner !== undefined) plannerEnabled = Boolean(flags.enablePlanner);
-  if (flags.enableResearcher !== undefined) researcherEnabled = Boolean(flags.enableResearcher);
-  if (flags.enableRefactorer !== undefined) refactorerEnabled = Boolean(flags.enableRefactorer);
-  if (flags.enableReviewer !== undefined) reviewerEnabled = Boolean(flags.enableReviewer);
-  if (flags.enableTester !== undefined) testerEnabled = Boolean(flags.enableTester);
-  if (flags.enableSecurity !== undefined) securityEnabled = Boolean(flags.enableSecurity);
+function applyFlagOverrides(pipelineFlags, flags) {
+  if (flags.enablePlanner !== undefined) pipelineFlags.plannerEnabled = Boolean(flags.enablePlanner);
+  if (flags.enableResearcher !== undefined) pipelineFlags.researcherEnabled = Boolean(flags.enableResearcher);
+  if (flags.enableArchitect !== undefined) pipelineFlags.architectEnabled = Boolean(flags.enableArchitect);
+  if (flags.enableRefactorer !== undefined) pipelineFlags.refactorerEnabled = Boolean(flags.enableRefactorer);
+  if (flags.enableReviewer !== undefined) pipelineFlags.reviewerEnabled = Boolean(flags.enableReviewer);
+  if (flags.enableTester !== undefined) pipelineFlags.testerEnabled = Boolean(flags.enableTester);
+  if (flags.enableSecurity !== undefined) pipelineFlags.securityEnabled = Boolean(flags.enableSecurity);
+}
 
-  // --- Policy resolver: gate stages by taskType ---
-  // Priority: explicit flag > config > triage classification > default (sw)
+function resolvePipelinePolicies({ flags, config, stageResults, emitter, eventBase, session, pipelineFlags }) {
   const resolvedPolicies = applyPolicies({
     taskType: flags.taskType || config.taskType || stageResults.triage?.taskType || null,
     policies: config.policies,
   });
   session.resolved_policies = resolvedPolicies;
 
-  // Apply policy gates on shallow copies (never mutate the caller's config)
+  let updatedConfig = config;
   if (!resolvedPolicies.tdd) {
-    config = { ...config, development: { ...config.development, methodology: "standard", require_test_changes: false } };
+    updatedConfig = { ...updatedConfig, development: { ...updatedConfig.development, methodology: "standard", require_test_changes: false } };
   }
   if (!resolvedPolicies.sonar) {
-    config = { ...config, sonarqube: { ...config.sonarqube, enabled: false } };
+    updatedConfig = { ...updatedConfig, sonarqube: { ...updatedConfig.sonarqube, enabled: false } };
   }
   if (!resolvedPolicies.reviewer) {
-    reviewerEnabled = false;
+    pipelineFlags.reviewerEnabled = false;
   }
 
   emitProgress(
@@ -318,622 +296,579 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
     })
   );
 
-  // --- Researcher (pre-planning) ---
+  return updatedConfig;
+}
+
+async function runPlanningPhases({ config, logger, emitter, eventBase, session, stageResults, pipelineFlags, coderRole, trackBudget, task, askQuestion }) {
   let researchContext = null;
-  if (researcherEnabled) {
+  let plannedTask = task;
+
+  if (pipelineFlags.researcherEnabled) {
     const researcherResult = await runResearcherStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget });
     researchContext = researcherResult.researchContext;
     stageResults.researcher = researcherResult.stageResult;
   }
 
-  // --- Planner ---
-  let plannedTask = task;
+  // --- Architect (between researcher and planner) ---
+  let architectContext = null;
+  if (pipelineFlags.architectEnabled) {
+    const architectResult = await runArchitectStage({
+      config, logger, emitter, eventBase, session, coderRole, trackBudget,
+      researchContext,
+      discoverResult: stageResults.discover || null,
+      triageLevel: stageResults.triage?.level || null,
+      askQuestion
+    });
+    architectContext = architectResult.architectContext;
+    stageResults.architect = architectResult.stageResult;
+  }
+
   const triageDecomposition = stageResults.triage?.shouldDecompose ? stageResults.triage.subtasks : null;
-  if (plannerEnabled) {
-    const plannerResult = await runPlannerStage({ config, logger, emitter, eventBase, session, plannerRole, researchContext, triageDecomposition, trackBudget });
+  if (pipelineFlags.plannerEnabled) {
+    const plannerRole = resolveRole(config, "planner");
+    const plannerResult = await runPlannerStage({ config, logger, emitter, eventBase, session, plannerRole, researchContext, architectContext, triageDecomposition, trackBudget });
     plannedTask = plannerResult.plannedTask;
     stageResults.planner = plannerResult.stageResult;
 
-    // BecarIA: dispatch planner comment (only on resume where PR already exists)
-    if (Boolean(config.becaria?.enabled) && session.becaria_pr_number) {
-      try {
-        const { dispatchComment } = await import("./becaria/dispatch.js");
-        const { detectRepo } = await import("./becaria/repo.js");
-        const repo = await detectRepo();
-        if (repo) {
-          const p = plannerResult.stageResult;
-          await dispatchComment({
-            repo, prNumber: session.becaria_pr_number, agent: "Planner",
-            body: `Plan: ${p?.summary || plannedTask}`,
-            becariaConfig: config.becaria
-          });
-        }
-      } catch { /* non-blocking */ }
+    await tryBecariaComment({
+      config, session, logger,
+      agent: "Planner",
+      body: `Plan: ${plannerResult.stageResult?.summary || plannedTask}`
+    });
+  }
+
+  return { plannedTask };
+}
+
+async function tryBecariaComment({ config, session, logger, agent, body }) {
+  if (!config.becaria?.enabled || !session.becaria_pr_number) return;
+  try {
+    const { dispatchComment } = await import("./becaria/dispatch.js");
+    const { detectRepo } = await import("./becaria/repo.js");
+    const repo = await detectRepo();
+    if (repo) {
+      await dispatchComment({
+        repo, prNumber: session.becaria_pr_number, agent,
+        body, becariaConfig: config.becaria
+      });
     }
+  } catch { /* non-blocking */ }
+}
+
+async function handleCheckpoint({ checkpointDisabled, askQuestion, lastCheckpointAt, checkpointIntervalMs, elapsedMinutes, i, config, budgetTracker, stageResults, emitter, eventBase, session, budgetSummary }) {
+  if (checkpointDisabled || !askQuestion || (Date.now() - lastCheckpointAt) < checkpointIntervalMs) {
+    return { action: "continue_loop", checkpointDisabled, lastCheckpointAt };
   }
 
-  const gitCtx = await prepareGitAutomation({ config, task, logger, session });
+  const elapsedStr = elapsedMinutes.toFixed(1);
+  const iterInfo = `${i - 1}/${config.max_iterations} iterations completed`;
+  const budgetInfo = budgetTracker.total().cost_usd > 0 ? ` | Budget: $${budgetTracker.total().cost_usd.toFixed(2)}` : "";
+  const stagesCompleted = Object.keys(stageResults).join(", ") || "none";
+  const checkpointMsg = `Checkpoint — ${elapsedStr} min elapsed | ${iterInfo}${budgetInfo} | Stages completed: ${stagesCompleted}. What would you like to do?`;
 
-  const projectDir = config.projectDir || process.cwd();
-  const { rules: reviewRules } = await resolveReviewProfile({ mode: config.review_mode, projectDir });
-  await coderRoleInstance.init();
+  emitProgress(
+    emitter,
+    makeEvent("session:checkpoint", { ...eventBase, iteration: i, stage: "checkpoint" }, {
+      message: `Interactive checkpoint at ${elapsedStr} min`,
+      detail: { elapsed_minutes: Number(elapsedStr), iterations_done: i - 1, stages: stagesCompleted }
+    })
+  );
 
-  const checkpointIntervalMs = (config.session.checkpoint_interval_minutes ?? 5) * 60 * 1000;
-  let lastCheckpointAt = Date.now();
-  let checkpointDisabled = false;
+  const answer = await askQuestion(
+    `${checkpointMsg}\n\nOptions:\n1. Continue 5 more minutes\n2. Continue until done (no more checkpoints)\n3. Continue for N minutes (reply with the number)\n4. Stop now`
+  );
 
-  for (let i = 1; i <= config.max_iterations; i += 1) {
-    const elapsedMinutes = (Date.now() - startedAt) / 60000;
+  await addCheckpoint(session, { stage: "interactive-checkpoint", elapsed_minutes: Number(elapsedStr), answer });
 
-    // --- Interactive checkpoint: pause and ask every N minutes ---
-    if (!checkpointDisabled && askQuestion && (Date.now() - lastCheckpointAt) >= checkpointIntervalMs) {
-      const elapsedStr = elapsedMinutes.toFixed(1);
-      const iterInfo = `${i - 1}/${config.max_iterations} iterations completed`;
-      const budgetInfo = budgetTracker.total().cost_usd > 0 ? ` | Budget: $${budgetTracker.total().cost_usd.toFixed(2)}` : "";
-      const stagesCompleted = Object.keys(stageResults).join(", ") || "none";
-      const checkpointMsg = `Checkpoint — ${elapsedStr} min elapsed | ${iterInfo}${budgetInfo} | Stages completed: ${stagesCompleted}. What would you like to do?`;
+  const trimmedAnswer = (answer || "").trim();
+  const isExplicitStop = trimmedAnswer === "4" || trimmedAnswer.toLowerCase().startsWith("stop");
 
-      emitProgress(
-        emitter,
-        makeEvent("session:checkpoint", { ...eventBase, iteration: i, stage: "checkpoint" }, {
-          message: `Interactive checkpoint at ${elapsedStr} min`,
-          detail: { elapsed_minutes: Number(elapsedStr), iterations_done: i - 1, stages: stagesCompleted }
-        })
-      );
+  if (isExplicitStop) {
+    await markSessionStatus(session, "stopped");
+    emitProgress(
+      emitter,
+      makeEvent("session:end", { ...eventBase, iteration: i, stage: "user-stop" }, {
+        status: "stopped",
+        message: "Session stopped by user at checkpoint",
+        detail: { approved: false, reason: "user_stopped", elapsed_minutes: Number(elapsedStr), budget: budgetSummary() }
+      })
+    );
+    return { action: "stop", result: { approved: false, sessionId: session.id, reason: "user_stopped", elapsed_minutes: Number(elapsedStr) } };
+  }
 
-      const answer = await askQuestion(
-        `${checkpointMsg}\n\nOptions:\n1. Continue 5 more minutes\n2. Continue until done (no more checkpoints)\n3. Continue for N minutes (reply with the number)\n4. Stop now`
-      );
+  return parseCheckpointAnswer({ trimmedAnswer, checkpointDisabled, config });
+}
 
-      await addCheckpoint(session, { stage: "interactive-checkpoint", elapsed_minutes: Number(elapsedStr), answer });
-
-      // Explicit stop: only when the user clearly chose option 4 or typed "stop".
-      // A null/empty answer (e.g. elicitInput failure, AI timeout) defaults to
-      // "continue 5 more minutes" so the session is not killed accidentally.
-      const trimmedAnswer = (answer || "").trim();
-      const isExplicitStop = trimmedAnswer === "4" || trimmedAnswer.toLowerCase().startsWith("stop");
-
-      if (isExplicitStop) {
-        await markSessionStatus(session, "stopped");
-        emitProgress(
-          emitter,
-          makeEvent("session:end", { ...eventBase, iteration: i, stage: "user-stop" }, {
-            status: "stopped",
-            message: "Session stopped by user at checkpoint",
-            detail: { approved: false, reason: "user_stopped", elapsed_minutes: Number(elapsedStr), budget: budgetSummary() }
-          })
-        );
-        return { approved: false, sessionId: session.id, reason: "user_stopped", elapsed_minutes: Number(elapsedStr) };
-      }
+function parseCheckpointAnswer({ trimmedAnswer, checkpointDisabled, config }) {
+  if (!trimmedAnswer) {
+    return { action: "continue_loop", checkpointDisabled, lastCheckpointAt: Date.now() };
+  }
+  if (trimmedAnswer === "2" || trimmedAnswer.toLowerCase().startsWith("continue until")) {
+    return { action: "continue_loop", checkpointDisabled: true, lastCheckpointAt: Date.now() };
+  }
+  if (trimmedAnswer === "1" || trimmedAnswer.toLowerCase().includes("5 m")) {
+    return { action: "continue_loop", checkpointDisabled, lastCheckpointAt: Date.now() };
+  }
+  const customMinutes = Number.parseInt(trimmedAnswer.replaceAll(/\D/g, ""), 10);
+  if (customMinutes > 0) {
+    config.session.checkpoint_interval_minutes = customMinutes;
+    return { action: "continue_loop", checkpointDisabled, lastCheckpointAt: Date.now() };
+  }
+  return { action: "continue_loop", checkpointDisabled, lastCheckpointAt: Date.now() };
+}
 
-      // No answer or unrecognized → default to continue 5 more minutes
-      if (!trimmedAnswer) {
-        lastCheckpointAt = Date.now();
-      } else if (trimmedAnswer === "2" || trimmedAnswer.toLowerCase().startsWith("continue until")) {
-        checkpointDisabled = true;
-      } else if (trimmedAnswer === "1" || trimmedAnswer.toLowerCase().includes("5 m")) {
-        lastCheckpointAt = Date.now();
-      } else {
-        const customMinutes = parseInt(trimmedAnswer.replace(/\D/g, ""), 10);
-        if (customMinutes > 0) {
-          lastCheckpointAt = Date.now();
-          config.session.checkpoint_interval_minutes = customMinutes;
-        } else {
-          lastCheckpointAt = Date.now();
-        }
-      }
-    }
+async function checkSessionTimeout({ askQuestion, elapsedMinutes, config, session, emitter, eventBase, i, budgetSummary }) {
+  if (askQuestion || elapsedMinutes <= config.session.max_total_minutes) return;
 
-    // --- Hard timeout: only when no askQuestion available ---
-    if (!askQuestion && elapsedMinutes > config.session.max_total_minutes) {
-      await markSessionStatus(session, "failed");
-      emitProgress(
-        emitter,
-        makeEvent("session:end", { ...eventBase, iteration: i, stage: "timeout" }, {
-          status: "fail",
-          message: "Session timed out",
-          detail: { approved: false, reason: "timeout", budget: budgetSummary() }
-        })
-      );
-      throw new Error("Session timed out");
-    }
+  await markSessionStatus(session, "failed");
+  emitProgress(
+    emitter,
+    makeEvent("session:end", { ...eventBase, iteration: i, stage: "timeout" }, {
+      status: "fail",
+      message: "Session timed out",
+      detail: { approved: false, reason: "timeout", budget: budgetSummary() }
+    })
+  );
+  throw new Error("Session timed out");
+}
 
-    if (budgetTracker.isOverBudget(config?.max_budget_usd)) {
-      await markSessionStatus(session, "failed");
-      const totalCost = budgetTracker.total().cost_usd;
-      const message = `Budget exceeded: $${totalCost.toFixed(2)} > $${budgetLimit.toFixed(2)}`;
-      emitProgress(
-        emitter,
-        makeEvent("session:end", { ...eventBase, iteration: i, stage: "budget" }, {
-          status: "fail",
-          message,
-          detail: { approved: false, reason: "budget_exceeded", budget: budgetSummary(), max_budget_usd: budgetLimit }
-        })
-      );
-      throw new Error(message);
-    }
+async function checkBudgetExceeded({ budgetTracker, config, session, emitter, eventBase, i, budgetLimit, budgetSummary }) {
+  if (!budgetTracker.isOverBudget(config?.max_budget_usd)) return;
 
-    eventBase.iteration = i;
-    const iterStart = Date.now();
-    const becariaEnabled = Boolean(config.becaria?.enabled) && gitCtx?.enabled;
-    logger.setContext({ iteration: i, stage: "iteration" });
+  await markSessionStatus(session, "failed");
+  const totalCost = budgetTracker.total().cost_usd;
+  const message = `Budget exceeded: $${totalCost.toFixed(2)} > $${budgetLimit.toFixed(2)}`;
+  emitProgress(
+    emitter,
+    makeEvent("session:end", { ...eventBase, iteration: i, stage: "budget" }, {
+      status: "fail",
+      message,
+      detail: { approved: false, reason: "budget_exceeded", budget: budgetSummary(), max_budget_usd: budgetLimit }
+    })
+  );
+  throw new Error(message);
+}
 
-    emitProgress(
-      emitter,
-      makeEvent("iteration:start", { ...eventBase, stage: "iteration" }, {
-        message: `Iteration ${i}/${config.max_iterations}`,
-        detail: { iteration: i, maxIterations: config.max_iterations }
-      })
-    );
+async function handleStandbyResult({ stageResult, session, emitter, eventBase, i, stage, logger }) {
+  if (!stageResult?.action || stageResult.action !== "standby") {
+    return { handled: false };
+  }
 
-    logger.info(`Iteration ${i}/${config.max_iterations}`);
+  const standbyRetries = session.standby_retry_count || 0;
+  if (standbyRetries >= MAX_STANDBY_RETRIES) {
+    await pauseSession(session, {
+      question: `Rate limit standby exhausted after ${standbyRetries} retries. Agent: ${stageResult.standbyInfo.agent}`,
+      context: { iteration: i, stage, reason: "standby_exhausted" }
+    });
+    emitProgress(emitter, makeEvent(`${stage}:rate_limit`, { ...eventBase, stage }, {
+      status: "paused",
+      message: `Standby exhausted after ${standbyRetries} retries`,
+      detail: { agent: stageResult.standbyInfo.agent, sessionId: session.id }
+    }));
+    return {
+      handled: true,
+      action: "return",
+      result: { paused: true, sessionId: session.id, question: `Rate limit standby exhausted after ${standbyRetries} retries`, context: "standby_exhausted" }
+    };
+  }
+  session.standby_retry_count = standbyRetries + 1;
+  await saveSession(session);
+  await waitForCooldown({ ...stageResult.standbyInfo, retryCount: standbyRetries, emitter, eventBase, logger, session });
+  return { handled: true, action: "retry" };
+}
 
-    // --- Coder ---
-    const coderResult = await runCoderStage({ coderRoleInstance, coderRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration: i });
-    if (coderResult?.action === "pause") {
-      return coderResult.result;
-    }
-    if (coderResult?.action === "standby") {
-      const standbyRetries = session.standby_retry_count || 0;
-      if (standbyRetries >= MAX_STANDBY_RETRIES) {
-        await pauseSession(session, {
-          question: `Rate limit standby exhausted after ${standbyRetries} retries. Agent: ${coderResult.standbyInfo.agent}`,
-          context: { iteration: i, stage: "coder", reason: "standby_exhausted" }
-        });
-        emitProgress(emitter, makeEvent("coder:rate_limit", { ...eventBase, stage: "coder" }, {
-          status: "paused",
-          message: `Standby exhausted after ${standbyRetries} retries`,
-          detail: { agent: coderResult.standbyInfo.agent, sessionId: session.id }
-        }));
-        return { paused: true, sessionId: session.id, question: `Rate limit standby exhausted after ${standbyRetries} retries`, context: "standby_exhausted" };
-      }
-      session.standby_retry_count = standbyRetries + 1;
-      await saveSession(session);
-      await waitForCooldown({ ...coderResult.standbyInfo, retryCount: standbyRetries, emitter, eventBase, logger, session });
-      i -= 1; // Retry the same iteration
-      continue;
-    }
+async function handleBecariaEarlyPrOrPush({ becariaEnabled, config, session, emitter, eventBase, gitCtx, task, logger, stageResults, i }) {
+  if (!becariaEnabled) return;
 
-    // --- Refactorer ---
-    if (refactorerEnabled) {
-      const refResult = await runRefactorerStage({ refactorerRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration: i });
-      if (refResult?.action === "pause") {
-        return refResult.result;
-      }
-      if (refResult?.action === "standby") {
-        const standbyRetries = session.standby_retry_count || 0;
-        if (standbyRetries >= MAX_STANDBY_RETRIES) {
-          await pauseSession(session, {
-            question: `Rate limit standby exhausted after ${standbyRetries} retries. Agent: ${refResult.standbyInfo.agent}`,
-            context: { iteration: i, stage: "refactorer", reason: "standby_exhausted" }
+  try {
+    const { dispatchComment } = await import("./becaria/dispatch.js");
+    const { detectRepo } = await import("./becaria/repo.js");
+    const repo = await detectRepo();
+
+    if (session.becaria_pr_number) {
+      const pushResult = await incrementalPush({ gitCtx, task, logger, session });
+      if (pushResult) {
+        session.becaria_commits = [...(session.becaria_commits ?? []), ...pushResult.commits];
+        await saveSession(session);
+
+        if (repo) {
+          const feedback = session.last_reviewer_feedback || "N/A";
+          const commitList = pushResult.commits.map((c) => `- \`${c.hash.slice(0, 7)}\` ${c.message}`).join("\n");
+          await dispatchComment({
+            repo, prNumber: session.becaria_pr_number, agent: "Coder",
+            body: `Issues corregidos:\n${feedback}\n\nCommits:\n${commitList}`,
+            becariaConfig: config.becaria
           });
-          emitProgress(emitter, makeEvent("refactorer:rate_limit", { ...eventBase, stage: "refactorer" }, {
-            status: "paused",
-            message: `Standby exhausted after ${standbyRetries} retries`,
-            detail: { agent: refResult.standbyInfo.agent, sessionId: session.id }
-          }));
-          return { paused: true, sessionId: session.id, question: `Rate limit standby exhausted after ${standbyRetries} retries`, context: "standby_exhausted" };
         }
-        session.standby_retry_count = standbyRetries + 1;
-        await saveSession(session);
-        await waitForCooldown({ ...refResult.standbyInfo, retryCount: standbyRetries, emitter, eventBase, logger, session });
-        i -= 1; // Retry the same iteration
-        continue;
       }
-    }
-
-    // --- TDD Policy ---
-    const tddResult = await runTddCheckStage({ config, logger, emitter, eventBase, session, trackBudget, iteration: i, askQuestion });
-    if (tddResult.action === "pause") {
-      return tddResult.result;
-    }
-    if (tddResult.action === "continue") {
-      continue;
-    }
+    } else {
+      const earlyPr = await earlyPrCreation({ gitCtx, task, logger, session, stageResults });
+      if (earlyPr) {
+        session.becaria_pr_number = earlyPr.prNumber;
+        session.becaria_pr_url = earlyPr.prUrl;
+        session.becaria_commits = earlyPr.commits;
+        await saveSession(session);
+        emitProgress(emitter, makeEvent("becaria:pr-created", { ...eventBase, stage: "becaria" }, {
+          message: `Early PR created: #${earlyPr.prNumber}`,
+          detail: { prNumber: earlyPr.prNumber, prUrl: earlyPr.prUrl }
+        }));
 
-    // --- SonarQube ---
-    if (config.sonarqube.enabled) {
-      const sonarResult = await runSonarStage({
-        config, logger, emitter, eventBase, session, trackBudget, iteration: i,
-        repeatDetector, budgetSummary, sonarState,
-        askQuestion, task
-      });
-      if (sonarResult.action === "stalled" || sonarResult.action === "pause") {
-        return sonarResult.result;
-      }
-      if (sonarResult.action === "continue") {
-        continue;
-      }
-      if (sonarResult.stageResult) {
-        stageResults.sonar = sonarResult.stageResult;
-        // BecarIA: dispatch sonar comment
-        if (becariaEnabled && session.becaria_pr_number) {
-          try {
-            const { dispatchComment } = await import("./becaria/dispatch.js");
-            const { detectRepo } = await import("./becaria/repo.js");
-            const repo = await detectRepo();
-            if (repo) {
-              const s = sonarResult.stageResult;
-              await dispatchComment({
-                repo, prNumber: session.becaria_pr_number, agent: "Sonar",
-                body: `SonarQube scan: ${s.summary || "completed"}`,
-                becariaConfig: config.becaria
-              });
-            }
-          } catch { /* non-blocking */ }
+        if (repo) {
+          const commitList = earlyPr.commits.map((c) => `- \`${c.hash.slice(0, 7)}\` ${c.message}`).join("\n");
+          await dispatchComment({
+            repo, prNumber: earlyPr.prNumber, agent: "Coder",
+            body: `Iteración ${i} completada.\n\nCommits:\n${commitList}`,
+            becariaConfig: config.becaria
+          });
         }
       }
     }
+  } catch (err) {
+    logger.warn(`BecarIA early PR/push failed (non-blocking): ${err.message}`);
+  }
+}
 
-    // --- BecarIA Gateway: early PR or incremental push ---
-    if (becariaEnabled) {
-      try {
-        const { dispatchComment } = await import("./becaria/dispatch.js");
-        const { detectRepo } = await import("./becaria/repo.js");
-        const repo = await detectRepo();
-
-        if (!session.becaria_pr_number) {
-          // First iteration: commit + push + create PR
-          const earlyPr = await earlyPrCreation({ gitCtx, task, logger, session, stageResults });
-          if (earlyPr) {
-            session.becaria_pr_number = earlyPr.prNumber;
-            session.becaria_pr_url = earlyPr.prUrl;
-            session.becaria_commits = earlyPr.commits;
-            await saveSession(session);
-            emitProgress(emitter, makeEvent("becaria:pr-created", { ...eventBase, stage: "becaria" }, {
-              message: `Early PR created: #${earlyPr.prNumber}`,
-              detail: { prNumber: earlyPr.prNumber, prUrl: earlyPr.prUrl }
-            }));
-
-            // Post coder comment on new PR
-            if (repo) {
-              const commitList = earlyPr.commits.map((c) => `- \`${c.hash.slice(0, 7)}\` ${c.message}`).join("\n");
-              await dispatchComment({
-                repo, prNumber: earlyPr.prNumber, agent: "Coder",
-                body: `Iteración ${i} completada.\n\nCommits:\n${commitList}`,
-                becariaConfig: config.becaria
-              });
-            }
-          }
-        } else {
-          // Subsequent iterations: incremental push + comment
-          const pushResult = await incrementalPush({ gitCtx, task, logger, session });
-          if (pushResult) {
-            session.becaria_commits = [...(session.becaria_commits || []), ...pushResult.commits];
-            await saveSession(session);
-
-            if (repo) {
-              const feedback = session.last_reviewer_feedback || "N/A";
-              const commitList = pushResult.commits.map((c) => `- \`${c.hash.slice(0, 7)}\` ${c.message}`).join("\n");
-              await dispatchComment({
-                repo, prNumber: session.becaria_pr_number, agent: "Coder",
-                body: `Issues corregidos:\n${feedback}\n\nCommits:\n${commitList}`,
-                becariaConfig: config.becaria
-              });
-            }
-          }
-        }
-      } catch (err) {
-        logger.warn(`BecarIA early PR/push failed (non-blocking): ${err.message}`);
+async function handleSolomonCheck({ config, session, emitter, eventBase, logger, task, i, askQuestion, becariaEnabled }) {
+  if (config.pipeline?.solomon?.enabled === false) return { action: "continue" };
+
+  try {
+    const { evaluateRules, buildRulesContext } = await import("./orchestrator/solomon-rules.js");
+    const rulesContext = await buildRulesContext({ session, task, iteration: i });
+    const rulesResult = evaluateRules(rulesContext, config.solomon?.rules);
+
+    if (rulesResult.alerts.length > 0) {
+      for (const alert of rulesResult.alerts) {
+        emitProgress(emitter, makeEvent("solomon:alert", { ...eventBase, stage: "solomon" }, {
+          status: alert.severity === "critical" ? "fail" : "warn",
+          message: alert.message,
+          detail: alert.detail
+        }));
+        logger.warn(`Solomon alert [${alert.rule}]: ${alert.message}`);
       }
+
+      const pauseResult = await checkSolomonCriticalAlerts({ rulesResult, askQuestion, session, i });
+      if (pauseResult) return pauseResult;
     }
 
-    // --- Reviewer ---
-    let review = {
-      approved: true,
-      blocking_issues: [],
-      non_blocking_suggestions: [],
-      summary: "Reviewer disabled by pipeline",
-      confidence: 1
-    };
-    if (reviewerEnabled) {
-      const reviewerResult = await runReviewerStage({
-        reviewerRole, config, logger, emitter, eventBase, session, trackBudget,
-        iteration: i, reviewRules, task, repeatDetector, budgetSummary, askQuestion
+    if (becariaEnabled && session.becaria_pr_number) {
+      const alerts = rulesResult.alerts || [];
+      const alertMsg = alerts.length > 0
+        ? alerts.map(a => `- [${a.severity}] ${a.message}`).join("\n")
+        : "No anomalies detected";
+      await tryBecariaComment({
+        config, session, logger,
+        agent: "Solomon",
+        body: `Supervisor check iteración ${i}: ${alertMsg}`
       });
-      if (reviewerResult.action === "pause") {
-        return reviewerResult.result;
-      }
-      if (reviewerResult.action === "standby") {
-        const standbyRetries = session.standby_retry_count || 0;
-        if (standbyRetries >= MAX_STANDBY_RETRIES) {
-          await pauseSession(session, {
-            question: `Rate limit standby exhausted after ${standbyRetries} retries. Agent: ${reviewerResult.standbyInfo.agent}`,
-            context: { iteration: i, stage: "reviewer", reason: "standby_exhausted" }
-          });
-          emitProgress(emitter, makeEvent("reviewer:rate_limit", { ...eventBase, stage: "reviewer" }, {
-            status: "paused",
-            message: `Standby exhausted after ${standbyRetries} retries`,
-            detail: { agent: reviewerResult.standbyInfo.agent, sessionId: session.id }
-          }));
-          return { paused: true, sessionId: session.id, question: `Rate limit standby exhausted after ${standbyRetries} retries`, context: "standby_exhausted" };
-        }
-        session.standby_retry_count = standbyRetries + 1;
-        await saveSession(session);
-        await waitForCooldown({ ...reviewerResult.standbyInfo, retryCount: standbyRetries, emitter, eventBase, logger, session });
-        i -= 1; // Retry the same iteration
-        continue;
-      }
-      review = reviewerResult.review;
-      if (reviewerResult.stalled) {
-        return reviewerResult.stalledResult;
-      }
     }
+  } catch (err) {
+    logger.warn(`Solomon rules evaluation failed: ${err.message}`);
+  }
 
-    // --- Iteration end ---
-    const iterDuration = Date.now() - iterStart;
-    emitProgress(
-      emitter,
-      makeEvent("iteration:end", { ...eventBase, stage: "iteration" }, {
-        message: `Iteration ${i} completed`,
-        detail: { duration: iterDuration }
-      })
-    );
+  return { action: "continue" };
+}
 
-    // Reset standby counter after successful iteration
-    session.standby_retry_count = 0;
-
-    // --- Solomon supervisor: anomaly detection after each iteration ---
-    if (config.pipeline?.solomon?.enabled !== false) {
-      try {
-        const { evaluateRules, buildRulesContext } = await import("./orchestrator/solomon-rules.js");
-        const rulesContext = await buildRulesContext({ session, task, iteration: i });
-        const rulesResult = evaluateRules(rulesContext, config.solomon?.rules);
-
-        if (rulesResult.alerts.length > 0) {
-          for (const alert of rulesResult.alerts) {
-            emitProgress(emitter, makeEvent("solomon:alert", { ...eventBase, stage: "solomon" }, {
-              status: alert.severity === "critical" ? "fail" : "warn",
-              message: alert.message,
-              detail: alert.detail
-            }));
-            logger.warn(`Solomon alert [${alert.rule}]: ${alert.message}`);
-          }
-
-          if (rulesResult.hasCritical && askQuestion) {
-            const alertSummary = rulesResult.alerts
-              .filter(a => a.severity === "critical")
-              .map(a => a.message)
-              .join("\n");
-            const answer = await askQuestion(
-              `Solomon detected critical issues:\n${alertSummary}\n\nShould I continue, pause, or revert?`,
-              { iteration: i, stage: "solomon" }
-            );
-            if (!answer || answer.toLowerCase().includes("pause") || answer.toLowerCase().includes("stop")) {
-              await pauseSession(session, {
-                question: `Solomon supervisor paused: ${alertSummary}`,
-                context: { iteration: i, stage: "solomon", alerts: rulesResult.alerts }
-              });
-              return { paused: true, sessionId: session.id, reason: "solomon_alert" };
-            }
-          }
-        }
+async function checkSolomonCriticalAlerts({ rulesResult, askQuestion, session, i }) {
+  if (!rulesResult.hasCritical || !askQuestion) return null;
 
-        // BecarIA: dispatch solomon comment
-        if (becariaEnabled && session.becaria_pr_number) {
-          try {
-            const { dispatchComment } = await import("./becaria/dispatch.js");
-            const { detectRepo } = await import("./becaria/repo.js");
-            const repo = await detectRepo();
-            if (repo) {
-              const alerts = rulesResult.alerts || [];
-              const alertMsg = alerts.length > 0
-                ? alerts.map(a => `- [${a.severity}] ${a.message}`).join("\n")
-                : "No anomalies detected";
-              await dispatchComment({
-                repo, prNumber: session.becaria_pr_number, agent: "Solomon",
-                body: `Supervisor check iteración ${i}: ${alertMsg}`,
-                becariaConfig: config.becaria
-              });
-            }
-          } catch { /* non-blocking */ }
-        }
-      } catch (err) {
-        logger.warn(`Solomon rules evaluation failed: ${err.message}`);
-      }
+  const alertSummary = rulesResult.alerts
+    .filter(a => a.severity === "critical")
+    .map(a => a.message)
+    .join("\n");
+  const answer = await askQuestion(
+    `Solomon detected critical issues:\n${alertSummary}\n\nShould I continue, pause, or revert?`,
+    { iteration: i, stage: "solomon" }
+  );
+  if (!answer || answer.toLowerCase().includes("pause") || answer.toLowerCase().includes("stop")) {
+    await pauseSession(session, {
+      question: `Solomon supervisor paused: ${alertSummary}`,
+      context: { iteration: i, stage: "solomon", alerts: rulesResult.alerts }
+    });
+    return { action: "pause", result: { paused: true, sessionId: session.id, reason: "solomon_alert" } };
+  }
+  return null;
+}
+
+async function handleBecariaReviewDispatch({ becariaEnabled, config, session, review, i, logger }) {
+  if (!becariaEnabled || !session.becaria_pr_number) return;
+
+  try {
+    const { dispatchReview, dispatchComment } = await import("./becaria/dispatch.js");
+    const { detectRepo } = await import("./becaria/repo.js");
+    const repo = await detectRepo();
+    if (!repo) return;
+
+    const bc = config.becaria;
+    if (review.approved) {
+      await dispatchReview({
+        repo, prNumber: session.becaria_pr_number,
+        event: "APPROVE", body: review.summary || "Approved", agent: "Reviewer", becariaConfig: bc
+      });
+    } else {
+      const blocking = review.blocking_issues?.map((x) => `- ${x.id || "ISSUE"} [${x.severity || ""}] ${x.description}`).join("\n") || "";
+      await dispatchReview({
+        repo, prNumber: session.becaria_pr_number,
+        event: "REQUEST_CHANGES",
+        body: blocking || review.summary || "Changes requested",
+        agent: "Reviewer", becariaConfig: bc
+      });
     }
 
-    // --- BecarIA Gateway: dispatch review result ---
-    if (becariaEnabled && session.becaria_pr_number) {
-      try {
-        const { dispatchReview, dispatchComment } = await import("./becaria/dispatch.js");
-        const { detectRepo } = await import("./becaria/repo.js");
-        const repo = await detectRepo();
-        if (repo) {
-          const bc = config.becaria;
-          // Formal review (APPROVE / REQUEST_CHANGES)
-          if (review.approved) {
-            await dispatchReview({
-              repo, prNumber: session.becaria_pr_number,
-              event: "APPROVE", body: review.summary || "Approved", agent: "Reviewer", becariaConfig: bc
-            });
-          } else {
-            const blocking = review.blocking_issues?.map((x) => `- ${x.id || "ISSUE"} [${x.severity || ""}] ${x.description}`).join("\n") || "";
-            await dispatchReview({
-              repo, prNumber: session.becaria_pr_number,
-              event: "REQUEST_CHANGES",
-              body: blocking || review.summary || "Changes requested",
-              agent: "Reviewer", becariaConfig: bc
-            });
-          }
-
-          // Detailed comment
-          const status = review.approved ? "APPROVED" : "REQUEST_CHANGES";
-          const blocking = review.blocking_issues?.map((x) => `- ${x.id || "ISSUE"} [${x.severity || ""}] ${x.description}`).join("\n") || "";
-          const suggestions = review.non_blocking_suggestions?.map((s) => `- ${typeof s === "string" ? s : `${s.id || ""} ${s.description || s}`}`).join("\n") || "";
-          let reviewBody = `Review iteración ${i}: ${status}`;
-          if (blocking) reviewBody += `\n\n**Blocking:**\n${blocking}`;
-          if (suggestions) reviewBody += `\n\n**Suggestions:**\n${suggestions}`;
-          await dispatchComment({
-            repo, prNumber: session.becaria_pr_number, agent: "Reviewer",
-            body: reviewBody, becariaConfig: bc
-          });
+    const status = review.approved ? "APPROVED" : "REQUEST_CHANGES";
+    const blocking = review.blocking_issues?.map((x) => `- ${x.id || "ISSUE"} [${x.severity || ""}] ${x.description}`).join("\n") || "";
+    const suggestions = review.non_blocking_suggestions?.map((s) => {
+      const detail = typeof s === "string" ? s : `${s.id || ""} ${s.description || s}`;
+      return `- ${detail}`;
+    }).join("\n") || "";
+    let reviewBody = `Review iteración ${i}: ${status}`;
+    if (blocking) reviewBody += `\n\n**Blocking:**\n${blocking}`;
+    if (suggestions) reviewBody += `\n\n**Suggestions:**\n${suggestions}`;
+    await dispatchComment({
+      repo, prNumber: session.becaria_pr_number, agent: "Reviewer",
+      body: reviewBody, becariaConfig: bc
+    });
 
-          logger.info(`BecarIA: dispatched review for PR #${session.becaria_pr_number}`);
-        }
-      } catch (err) {
-        logger.warn(`BecarIA dispatch failed (non-blocking): ${err.message}`);
-      }
+    logger.info(`BecarIA: dispatched review for PR #${session.becaria_pr_number}`);
+  } catch (err) {
+    logger.warn(`BecarIA dispatch failed (non-blocking): ${err.message}`);
+  }
+}
+
+async function handlePostLoopStages({ config, session, emitter, eventBase, coderRole, trackBudget, i, task, stageResults, becariaEnabled, testerEnabled, securityEnabled, askQuestion, logger }) {
+  const postLoopDiff = await generateDiff({ baseRef: session.session_start_sha });
+
+  if (testerEnabled) {
+    const testerResult = await runTesterStage({
+      config, logger, emitter, eventBase, session, coderRole, trackBudget,
+      iteration: i, task, diff: postLoopDiff, askQuestion
+    });
+    if (testerResult.action === "pause") return { action: "return", result: testerResult.result };
+    if (testerResult.action === "continue") return { action: "continue" };
+    if (testerResult.stageResult) {
+      stageResults.tester = testerResult.stageResult;
+      await tryBecariaComment({ config, session, logger, agent: "Tester", body: `Tests: ${testerResult.stageResult.summary || "completed"}` });
     }
+  }
 
-    if (review.approved) {
-      session.reviewer_retry_count = 0;
-
-      // --- Post-loop stages: Tester → Security ---
-      const postLoopDiff = await generateDiff({ baseRef: session.session_start_sha });
-
-      if (testerEnabled) {
-        const testerResult = await runTesterStage({
-          config, logger, emitter, eventBase, session, coderRole, trackBudget,
-          iteration: i, task, diff: postLoopDiff, askQuestion
-        });
-        if (testerResult.action === "pause") {
-          return testerResult.result;
-        }
-        if (testerResult.action === "continue") {
-          continue;
-        }
-        if (testerResult.stageResult) {
-          stageResults.tester = testerResult.stageResult;
-          // BecarIA: dispatch tester comment
-          if (becariaEnabled && session.becaria_pr_number) {
-            try {
-              const { dispatchComment } = await import("./becaria/dispatch.js");
-              const { detectRepo } = await import("./becaria/repo.js");
-              const repo = await detectRepo();
-              if (repo) {
-                const t = testerResult.stageResult;
-                await dispatchComment({
-                  repo, prNumber: session.becaria_pr_number, agent: "Tester",
-                  body: `Tests: ${t.summary || "completed"}`,
-                  becariaConfig: config.becaria
-                });
-              }
-            } catch { /* non-blocking */ }
-          }
-        }
-      }
+  if (securityEnabled) {
+    const securityResult = await runSecurityStage({
+      config, logger, emitter, eventBase, session, coderRole, trackBudget,
+      iteration: i, task, diff: postLoopDiff, askQuestion
+    });
+    if (securityResult.action === "pause") return { action: "return", result: securityResult.result };
+    if (securityResult.action === "continue") return { action: "continue" };
+    if (securityResult.stageResult) {
+      stageResults.security = securityResult.stageResult;
+      await tryBecariaComment({ config, session, logger, agent: "Security", body: `Security scan: ${securityResult.stageResult.summary || "completed"}` });
+    }
+  }
 
-      if (securityEnabled) {
-        const securityResult = await runSecurityStage({
-          config, logger, emitter, eventBase, session, coderRole, trackBudget,
-          iteration: i, task, diff: postLoopDiff, askQuestion
-        });
-        if (securityResult.action === "pause") {
-          return securityResult.result;
-        }
-        if (securityResult.action === "continue") {
-          continue;
-        }
-        if (securityResult.stageResult) {
-          stageResults.security = securityResult.stageResult;
-          // BecarIA: dispatch security comment
-          if (becariaEnabled && session.becaria_pr_number) {
-            try {
-              const { dispatchComment } = await import("./becaria/dispatch.js");
-              const { detectRepo } = await import("./becaria/repo.js");
-              const repo = await detectRepo();
-              if (repo) {
-                const s = securityResult.stageResult;
-                await dispatchComment({
-                  repo, prNumber: session.becaria_pr_number, agent: "Security",
-                  body: `Security scan: ${s.summary || "completed"}`,
-                  becariaConfig: config.becaria
-                });
-              }
-            } catch { /* non-blocking */ }
-          }
-        }
-      }
+  return { action: "proceed" };
+}
 
-      // --- All post-loop checks passed → finalize ---
-      const gitResult = await finalizeGitAutomation({ config, gitCtx, task, logger, session, stageResults });
-      if (stageResults.planner?.ok) {
-        stageResults.planner.completedSteps = [...(stageResults.planner.steps || [])];
-      }
-      session.budget = budgetSummary();
-      await markSessionStatus(session, "approved");
-
-      // --- Planning Game: mark card as To Validate ---
-      if (pgCard && pgProject) {
-        try {
-          const { updateCard } = await import("./planning-game/client.js");
-          const { buildCompletionUpdates } = await import("./planning-game/adapter.js");
-          const pgUpdates = buildCompletionUpdates({
-            approved: true,
-            commits: gitResult?.commits || [],
-            startDate: session.pg_card?.startDate || session.created_at,
-            codeveloper: config.planning_game?.codeveloper || null
-          });
-          await updateCard({
-            projectId: pgProject,
-            cardId: session.pg_task_id,
-            firebaseId: pgCard.firebaseId,
-            updates: pgUpdates
-          });
-          logger.info(`Planning Game: ${session.pg_task_id} → To Validate`);
-        } catch (err) {
-          logger.warn(`Planning Game: could not update ${session.pg_task_id} on completion: ${err.message}`);
-        }
-      }
+async function finalizeApprovedSession({ config, gitCtx, task, logger, session, stageResults, emitter, eventBase, budgetSummary, pgCard, pgProject, review, i }) {
+  const gitResult = await finalizeGitAutomation({ config, gitCtx, task, logger, session, stageResults });
+  if (stageResults.planner?.ok) {
+    stageResults.planner.completedSteps = [...(stageResults.planner.steps ?? [])];
+  }
+  session.budget = budgetSummary();
+  await markSessionStatus(session, "approved");
 
-      const deferredIssues = session.deferred_issues || [];
-      emitProgress(
-        emitter,
-        makeEvent("session:end", { ...eventBase, stage: "done" }, {
-          message: deferredIssues.length > 0
-            ? `Session approved (${deferredIssues.length} deferred issue(s) tracked as tech debt)`
-            : "Session approved",
-          detail: { approved: true, iterations: i, stages: stageResults, git: gitResult, budget: budgetSummary(), deferredIssues }
-        })
-      );
-      return { approved: true, sessionId: session.id, review, git: gitResult, deferredIssues };
+  await markPgCardToValidate({ pgCard, pgProject, config, session, gitResult, logger });
+
+  const deferredIssues = session.deferred_issues || [];
+  emitProgress(
+    emitter,
+    makeEvent("session:end", { ...eventBase, stage: "done" }, {
+      message: deferredIssues.length > 0
+        ? `Session approved (${deferredIssues.length} deferred issue(s) tracked as tech debt)`
+        : "Session approved",
+      detail: { approved: true, iterations: i, stages: stageResults, git: gitResult, budget: budgetSummary(), deferredIssues }
+    })
+  );
+  return { approved: true, sessionId: session.id, review, git: gitResult, deferredIssues };
+}
+
+async function markPgCardToValidate({ pgCard, pgProject, config, session, gitResult, logger }) {
+  if (!pgCard || !pgProject) return;
+
+  try {
+    const { updateCard } = await import("./planning-game/client.js");
+    const { buildCompletionUpdates } = await import("./planning-game/adapter.js");
+    const pgUpdates = buildCompletionUpdates({
+      approved: true,
+      commits: gitResult?.commits || [],
+      startDate: session.pg_card?.startDate || session.created_at,
+      codeveloper: config.planning_game?.codeveloper || null
+    });
+    await updateCard({
+      projectId: pgProject,
+      cardId: session.pg_task_id,
+      firebaseId: pgCard.firebaseId,
+      updates: pgUpdates
+    });
+    logger.info(`Planning Game: ${session.pg_task_id} → To Validate`);
+  } catch (err) {
+    logger.warn(`Planning Game: could not update ${session.pg_task_id} on completion: ${err.message}`);
+  }
+}
+
+async function handleReviewerRetryAndSolomon({ config, session, emitter, eventBase, logger, review, task, i, askQuestion }) {
+  session.last_reviewer_feedback = review.blocking_issues
+    .map((x) => `${x.id || "ISSUE"}: ${x.description || "Missing description"}`)
+    .join("\n");
+  session.reviewer_retry_count = (session.reviewer_retry_count || 0) + 1;
+  await saveSession(session);
+
+  const maxReviewerRetries = config.session.max_reviewer_retries ?? config.session.fail_fast_repeats;
+  if (session.reviewer_retry_count < maxReviewerRetries) {
+    return { action: "continue" };
+  }
+
+  emitProgress(
+    emitter,
+    makeEvent("solomon:escalate", { ...eventBase, stage: "reviewer" }, {
+      message: `Reviewer sub-loop limit reached (${session.reviewer_retry_count}/${maxReviewerRetries})`,
+      detail: { subloop: "reviewer", retryCount: session.reviewer_retry_count, limit: maxReviewerRetries }
+    })
+  );
+
+  const solomonResult = await invokeSolomon({
+    config, logger, emitter, eventBase, stage: "reviewer", askQuestion, session, iteration: i,
+    conflict: {
+      stage: "reviewer",
+      task,
+      iterationCount: session.reviewer_retry_count,
+      maxIterations: maxReviewerRetries,
+      history: [{ agent: "reviewer", feedback: session.last_reviewer_feedback }]
     }
+  });
 
-    session.last_reviewer_feedback = review.blocking_issues
-      .map((x) => `${x.id || "ISSUE"}: ${x.description || "Missing description"}`)
-      .join("\n");
-    session.reviewer_retry_count = (session.reviewer_retry_count || 0) + 1;
+  if (solomonResult.action === "pause") {
+    return { action: "return", result: { paused: true, sessionId: session.id, question: solomonResult.question, context: "reviewer_fail_fast" } };
+  }
+  if (solomonResult.action === "continue") {
+    if (solomonResult.humanGuidance) {
+      session.last_reviewer_feedback += `\nUser guidance: ${solomonResult.humanGuidance}`;
+    }
+    session.reviewer_retry_count = 0;
     await saveSession(session);
+    return { action: "continue" };
+  }
+  if (solomonResult.action === "subtask") {
+    return { action: "return", result: { paused: true, sessionId: session.id, subtask: solomonResult.subtask, context: "reviewer_subtask" } };
+  }
 
-    const maxReviewerRetries = config.session.max_reviewer_retries ?? config.session.fail_fast_repeats;
-    if (session.reviewer_retry_count >= maxReviewerRetries) {
-      emitProgress(
-        emitter,
-        makeEvent("solomon:escalate", { ...eventBase, stage: "reviewer" }, {
-          message: `Reviewer sub-loop limit reached (${session.reviewer_retry_count}/${maxReviewerRetries})`,
-          detail: { subloop: "reviewer", retryCount: session.reviewer_retry_count, limit: maxReviewerRetries }
-        })
-      );
+  return { action: "continue" };
+}
 
-      const solomonResult = await invokeSolomon({
-        config, logger, emitter, eventBase, stage: "reviewer", askQuestion, session, iteration: i,
-        conflict: {
-          stage: "reviewer",
-          task,
-          iterationCount: session.reviewer_retry_count,
-          maxIterations: maxReviewerRetries,
-          history: [{ agent: "reviewer", feedback: session.last_reviewer_feedback }]
-        }
-      });
 
-      if (solomonResult.action === "pause") {
-        return { paused: true, sessionId: session.id, question: solomonResult.question, context: "reviewer_fail_fast" };
-      }
-      if (solomonResult.action === "continue") {
-        if (solomonResult.humanGuidance) {
-          session.last_reviewer_feedback += `\nUser guidance: ${solomonResult.humanGuidance}`;
-        }
-        session.reviewer_retry_count = 0;
-        await saveSession(session);
-        continue;
-      }
-      if (solomonResult.action === "subtask") {
-        return { paused: true, sessionId: session.id, subtask: solomonResult.subtask, context: "reviewer_subtask" };
-      }
+async function runPreLoopStages({ config, logger, emitter, eventBase, session, flags, pipelineFlags, coderRole, trackBudget, task, askQuestion, pgTaskId, pgProject, stageResults }) {
+  // --- Discover (pre-triage, opt-in) ---
+  if (flags.enableDiscover !== undefined) pipelineFlags.discoverEnabled = Boolean(flags.enableDiscover);
+  if (pipelineFlags.discoverEnabled) {
+    const discoverResult = await runDiscoverStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget });
+    stageResults.discover = discoverResult.stageResult;
+  }
+
+  // --- Triage (always on) ---
+  const triageResult = await runTriageStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget });
+  applyTriageOverrides(pipelineFlags, triageResult.roleOverrides);
+  stageResults.triage = triageResult.stageResult;
+
+  await handlePgDecomposition({ triageResult, pgTaskId, pgProject, config, askQuestion, emitter, eventBase, session, stageResults, logger });
+
+  applyFlagOverrides(pipelineFlags, flags);
+  const updatedConfig = resolvePipelinePolicies({ flags, config, stageResults, emitter, eventBase, session, pipelineFlags });
+
+  // --- Researcher → Planner ---
+  const { plannedTask } = await runPlanningPhases({ config: updatedConfig, logger, emitter, eventBase, session, stageResults, pipelineFlags, coderRole, trackBudget, task, askQuestion });
+
+  return { plannedTask, updatedConfig };
+}
+
+async function runCoderAndRefactorerStages({ coderRoleInstance, coderRole, refactorerRole, pipelineFlags, config, logger, emitter, eventBase, session, plannedTask, trackBudget, i }) {
+  const coderResult = await runCoderStage({ coderRoleInstance, coderRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration: i });
+  if (coderResult?.action === "pause") return { action: "return", result: coderResult.result };
+  const coderStandby = await handleStandbyResult({ stageResult: coderResult, session, emitter, eventBase, i, stage: "coder", logger });
+  if (coderStandby.handled) {
+    return coderStandby.action === "return"
+      ? { action: "return", result: coderStandby.result }
+      : { action: "retry" };
+  }
+
+  if (pipelineFlags.refactorerEnabled) {
+    const refResult = await runRefactorerStage({ refactorerRole, config, logger, emitter, eventBase, session, plannedTask, trackBudget, iteration: i });
+    if (refResult?.action === "pause") return { action: "return", result: refResult.result };
+    const refStandby = await handleStandbyResult({ stageResult: refResult, session, emitter, eventBase, i, stage: "refactorer", logger });
+    if (refStandby.handled) {
+      return refStandby.action === "return"
+        ? { action: "return", result: refStandby.result }
+        : { action: "retry" };
+    }
+  }
+
+  return { action: "ok" };
+}
+
+async function runQualityGateStages({ config, logger, emitter, eventBase, session, trackBudget, i, askQuestion, repeatDetector, budgetSummary, sonarState, task, stageResults }) {
+  const tddResult = await runTddCheckStage({ config, logger, emitter, eventBase, session, trackBudget, iteration: i, askQuestion });
+  if (tddResult.action === "pause") return { action: "return", result: tddResult.result };
+  if (tddResult.action === "continue") return { action: "continue" };
+
+  if (config.sonarqube.enabled) {
+    const sonarResult = await runSonarStage({
+      config, logger, emitter, eventBase, session, trackBudget, iteration: i,
+      repeatDetector, budgetSummary, sonarState, askQuestion, task
+    });
+    if (sonarResult.action === "stalled" || sonarResult.action === "pause") return { action: "return", result: sonarResult.result };
+    if (sonarResult.action === "continue") return { action: "continue" };
+    if (sonarResult.stageResult) {
+      stageResults.sonar = sonarResult.stageResult;
+      await tryBecariaComment({ config, session, logger, agent: "Sonar", body: `SonarQube scan: ${sonarResult.stageResult.summary || "completed"}` });
     }
   }
 
+  return { action: "ok" };
+}
+
+async function runReviewerGateStage({ pipelineFlags, reviewerRole, config, logger, emitter, eventBase, session, trackBudget, i, reviewRules, task, repeatDetector, budgetSummary, askQuestion }) {
+  if (!pipelineFlags.reviewerEnabled) {
+    return {
+      action: "ok",
+      review: { approved: true, blocking_issues: [], non_blocking_suggestions: [], summary: "Reviewer disabled by pipeline", confidence: 1 }
+    };
+  }
+
+  const reviewerResult = await runReviewerStage({
+    reviewerRole, config, logger, emitter, eventBase, session, trackBudget,
+    iteration: i, reviewRules, task, repeatDetector, budgetSummary, askQuestion
+  });
+  if (reviewerResult.action === "pause") return { action: "return", result: reviewerResult.result };
+  const revStandby = await handleStandbyResult({ stageResult: reviewerResult, session, emitter, eventBase, i, stage: "reviewer", logger });
+  if (revStandby.handled) {
+    return revStandby.action === "return"
+      ? { action: "return", result: revStandby.result }
+      : { action: "retry" };
+  }
+  if (reviewerResult.stalled) return { action: "return", result: reviewerResult.stalledResult };
+  return { action: "ok", review: reviewerResult.review };
+}
+
+async function handleApprovedReview({ config, session, emitter, eventBase, coderRole, trackBudget, i, task, stageResults, pipelineFlags, askQuestion, logger, gitCtx, budgetSummary, pgCard, pgProject, review }) {
+  session.reviewer_retry_count = 0;
+  const postLoopResult = await handlePostLoopStages({
+    config, session, emitter, eventBase, coderRole, trackBudget, i, task, stageResults,
+    becariaEnabled: Boolean(config.becaria?.enabled), testerEnabled: pipelineFlags.testerEnabled, securityEnabled: pipelineFlags.securityEnabled, askQuestion, logger
+  });
+  if (postLoopResult.action === "return") return { action: "return", result: postLoopResult.result };
+  if (postLoopResult.action === "continue") return { action: "continue" };
+
+  const result = await finalizeApprovedSession({ config, gitCtx, task, logger, session, stageResults, emitter, eventBase, budgetSummary, pgCard, pgProject, review, i });
+  return { action: "return", result };
+}
+
+async function handleMaxIterationsReached({ session, budgetSummary, emitter, eventBase, config, stageResults }) {
   session.budget = budgetSummary();
   await markSessionStatus(session, "failed");
   emitProgress(
@@ -947,6 +882,143 @@ export async function runFlow({ task, config, logger, flags = {}, emitter = null
   return { approved: false, sessionId: session.id, reason: "max_iterations" };
 }
 
+async function initFlowContext({ task, config, logger, emitter, askQuestion, pgTaskId, pgProject, flags }) {
+  const coderRole = resolveRole(config, "coder");
+  const reviewerRole = resolveRole(config, "reviewer");
+  const refactorerRole = resolveRole(config, "refactorer");
+  const pipelineFlags = resolvePipelineFlags(config);
+  const repeatDetector = new RepeatDetector({ threshold: getRepeatThreshold(config) });
+  const coderRoleInstance = new CoderRole({ config, logger, emitter, createAgentFn: createAgent });
+  const startedAt = Date.now();
+  const eventBase = { sessionId: null, iteration: 0, stage: null, startedAt };
+  const { budgetTracker, budgetLimit, budgetSummary, trackBudget } = createBudgetManager({ config, emitter, eventBase });
+
+  const session = await initializeSession({ task, config, flags, pgTaskId, pgProject });
+  eventBase.sessionId = session.id;
+
+  const pgCard = await markPgCardInProgress({ pgTaskId, pgProject, config, logger });
+  session.pg_card = pgCard || null;
+
+  emitProgress(
+    emitter,
+    makeEvent("session:start", eventBase, {
+      message: "Session started",
+      detail: { task, coder: coderRole.provider, reviewer: reviewerRole.provider, maxIterations: config.max_iterations }
+    })
+  );
+
+  const stageResults = {};
+  const sonarState = { issuesInitial: null, issuesFinal: null };
+
+  const preLoopResult = await runPreLoopStages({ config, logger, emitter, eventBase, session, flags, pipelineFlags, coderRole, trackBudget, task, askQuestion, pgTaskId, pgProject, stageResults });
+  const { plannedTask } = preLoopResult;
+  const updatedConfig = preLoopResult.updatedConfig;
+
+  const gitCtx = await prepareGitAutomation({ config: updatedConfig, task, logger, session });
+  const projectDir = updatedConfig.projectDir || process.cwd();
+  const { rules: reviewRules } = await resolveReviewProfile({ mode: updatedConfig.review_mode, projectDir });
+  await coderRoleInstance.init();
+
+  return {
+    coderRole, reviewerRole, refactorerRole, pipelineFlags, repeatDetector, coderRoleInstance,
+    startedAt, eventBase, budgetTracker, budgetLimit, budgetSummary, trackBudget,
+    session, pgCard, stageResults, sonarState, plannedTask, config: updatedConfig,
+    gitCtx, reviewRules
+  };
+}
+
+async function runSingleIteration(ctx) {
+  const {
+    coderRoleInstance, coderRole, refactorerRole, pipelineFlags, config, logger, emitter, eventBase,
+    session, plannedTask, trackBudget, i, reviewerRole, reviewRules, task, repeatDetector,
+    budgetSummary, askQuestion, sonarState, stageResults, gitCtx, pgCard, pgProject
+  } = ctx;
+
+  const iterStart = Date.now();
+  const becariaEnabled = Boolean(config.becaria?.enabled) && gitCtx?.enabled;
+  logger.setContext({ iteration: i, stage: "iteration" });
+
+  emitProgress(emitter, makeEvent("iteration:start", { ...eventBase, stage: "iteration" }, {
+    message: `Iteration ${i}/${config.max_iterations}`,
+    detail: { iteration: i, maxIterations: config.max_iterations }
+  }));
+  logger.info(`Iteration ${i}/${config.max_iterations}`);
+
+  const crResult = await runCoderAndRefactorerStages({ coderRoleInstance, coderRole, refactorerRole, pipelineFlags, config, logger, emitter, eventBase, session, plannedTask, trackBudget, i });
+  if (crResult.action === "return" || crResult.action === "retry") return crResult;
+
+  const qgResult = await runQualityGateStages({ config, logger, emitter, eventBase, session, trackBudget, i, askQuestion, repeatDetector, budgetSummary, sonarState, task, stageResults });
+  if (qgResult.action === "return" || qgResult.action === "continue") return qgResult;
+
+  await handleBecariaEarlyPrOrPush({ becariaEnabled, config, session, emitter, eventBase, gitCtx, task, logger, stageResults, i });
+
+  const revResult = await runReviewerGateStage({ pipelineFlags, reviewerRole, config, logger, emitter, eventBase, session, trackBudget, i, reviewRules, task, repeatDetector, budgetSummary, askQuestion });
+  if (revResult.action === "return" || revResult.action === "retry") return revResult;
+  const review = revResult.review;
+
+  const iterDuration = Date.now() - iterStart;
+  emitProgress(emitter, makeEvent("iteration:end", { ...eventBase, stage: "iteration" }, {
+    message: `Iteration ${i} completed`, detail: { duration: iterDuration }
+  }));
+  session.standby_retry_count = 0;
+
+  const solomonResult = await handleSolomonCheck({ config, session, emitter, eventBase, logger, task, i, askQuestion, becariaEnabled });
+  if (solomonResult.action === "pause") return { action: "return", result: solomonResult.result };
+
+  await handleBecariaReviewDispatch({ becariaEnabled, config, session, review, i, logger });
+
+  if (review.approved) {
+    const approvedResult = await handleApprovedReview({ config, session, emitter, eventBase, coderRole, trackBudget, i, task, stageResults, pipelineFlags, askQuestion, logger, gitCtx, budgetSummary, pgCard, pgProject, review });
+    if (approvedResult.action === "return" || approvedResult.action === "continue") return approvedResult;
+  }
+
+  const retryResult = await handleReviewerRetryAndSolomon({ config, session, emitter, eventBase, logger, review, task, i, askQuestion });
+  if (retryResult.action === "return") return retryResult;
+
+  return { action: "next" };
+}
+
+export async function runFlow({ task, config, logger, flags = {}, emitter = null, askQuestion = null, pgTaskId = null, pgProject = null }) {
+  const pipelineFlags = resolvePipelineFlags(config);
+
+  if (flags.dryRun) {
+    return handleDryRun({ task, config, flags, emitter, pipelineFlags });
+  }
+
+  const ctx = await initFlowContext({ task, config, logger, emitter, askQuestion, pgTaskId, pgProject, flags });
+  config = ctx.config;
+
+  const checkpointIntervalMs = (config.session.checkpoint_interval_minutes ?? 5) * 60 * 1000;
+  let lastCheckpointAt = Date.now();
+  let checkpointDisabled = false;
+
+  let i = 0;
+  while (i < config.max_iterations) {
+    i += 1;
+    const elapsedMinutes = (Date.now() - ctx.startedAt) / 60000;
+
+    const cpResult = await handleCheckpoint({
+      checkpointDisabled, askQuestion, lastCheckpointAt, checkpointIntervalMs, elapsedMinutes,
+      i, config, budgetTracker: ctx.budgetTracker, stageResults: ctx.stageResults, emitter, eventBase: ctx.eventBase, session: ctx.session, budgetSummary: ctx.budgetSummary
+    });
+    if (cpResult.action === "stop") return cpResult.result;
+    checkpointDisabled = cpResult.checkpointDisabled;
+    lastCheckpointAt = cpResult.lastCheckpointAt;
+
+    await checkSessionTimeout({ askQuestion, elapsedMinutes, config, session: ctx.session, emitter, eventBase: ctx.eventBase, i, budgetSummary: ctx.budgetSummary });
+    await checkBudgetExceeded({ budgetTracker: ctx.budgetTracker, config, session: ctx.session, emitter, eventBase: ctx.eventBase, i, budgetLimit: ctx.budgetLimit, budgetSummary: ctx.budgetSummary });
+
+    ctx.eventBase.iteration = i;
+    ctx.i = i;
+
+    const iterResult = await runSingleIteration({ ...ctx, config, logger, emitter, askQuestion, task, pgProject, i });
+    if (iterResult.action === "return") return iterResult.result;
+    if (iterResult.action === "retry") { i -= 1; }
+  }
+
+  return handleMaxIterationsReached({ session: ctx.session, budgetSummary: ctx.budgetSummary, emitter, eventBase: ctx.eventBase, config, stageResults: ctx.stageResults });
+}
+
 export async function resumeFlow({ sessionId, answer, config, logger, flags = {}, emitter = null, askQuestion = null }) {
   const session = answer
     ? await resumeSessionWithAnswer(sessionId, answer)
@@ -958,8 +1030,8 @@ export async function resumeFlow({ sessionId, answer, config, logger, flags = {}
   }
 
   // Allow resuming "stopped" sessions (checkpoint stop) and "failed" sessions
-  const resumableStatuses = ["running", "stopped", "failed"];
-  if (!resumableStatuses.includes(session.status)) {
+  const resumableStatuses = new Set(["running", "stopped", "failed"]);
+  if (!resumableStatuses.has(session.status)) {
     logger.info(`Session ${sessionId} has status ${session.status} — not resumable`);
     return session;
   }