karajan-code 2.7.3 → 2.8.0

package/src/orchestrator/stages/hu-reviewer-phases/detect-and-apply-splits.js

@@ -0,0 +1,127 @@
+/**
+ * HU Reviewer phase: detect splittable HUs and apply the split.
+ *
+ * Extracted from `runHuReviewerStage` in PR-M (audit follow-up,
+ * KJC-PCS-0033). Was 78 LOC inlined inside the 311-LOC parent
+ * function — moving it brings the stage closer to a clean
+ * load → split → evaluate → return shape.
+ *
+ * For each pending HU in the batch:
+ *
+ *   1. Run the deterministic indicator detector
+ *      (src/hu/splitting-detector.js). If no indicators, skip.
+ *   2. Pick the first heuristic that matches; ask the LLM for a
+ *      split proposal. Retry with other heuristics on failure.
+ *   3. In autonomous mode (askQuestion=null) the proposal is
+ *      auto-accepted. In interactive mode the FDE confirms.
+ *   4. Replace the original story with the proposed sub-HUs in
+ *      the batch and persist.
+ *
+ * Behaviour identical to the inlined version — only the container
+ * changes. The closure variables (batch, askQuestion, config,
+ * logger, emitter, eventBase, batchSessionId) become explicit
+ * function parameters.
+ */
+
+import { saveHuBatch, updateStoryStatus } from "#hu/store.js";
+import { emitProgress, makeEvent } from "#utils/events.js";
+import { detectIndicators, selectHeuristic } from "#hu/splitting-detector.js";
+import { generateSplitProposal, formatSplitProposalForFDE, buildSplitDependencies } from "#hu/splitting-generator.js";
+
+/**
+ * Build a fresh sub-HU story object from a proposal entry. Same
+ * shape the inlined code produced; centralised to avoid the
+ * autonomous + interactive paths drifting apart.
+ */
+function buildSubHuStory(sub) {
+  const text = `${sub.title}\n\n${sub.text}\n\nAcceptance Criteria:\n${(sub.acceptanceCriteria || []).map((ac) => `- ${ac}`).join("\n")}`;
+  const now = new Date().toISOString();
+  return {
+    id: sub.id,
+    status: "pending",
+    original: { text },
+    blocked_by: sub.blocked_by || [],
+    certified: null,
+    quality: null,
+    context_requests: [],
+    created_at: now,
+    updated_at: now,
+  };
+}
+
+/**
+ * Replace `story` in `batch.stories` with the expanded sub-HUs and
+ * emit the `hu-reviewer:split-accepted` event.
+ */
+function applySplit({ batch, story, proposal, heuristic, source, eventBase, emitter }) {
+  const updatedSubHUs = buildSplitDependencies(proposal.subHUs, story);
+  const storyIndex = batch.stories.findIndex((s) => s.id === story.id);
+  const newStories = updatedSubHUs.map(buildSubHuStory);
+  batch.stories.splice(storyIndex, 1, ...newStories);
+  emitProgress(emitter, makeEvent("hu-reviewer:split-accepted", { ...eventBase, stage: "hu-reviewer" }, {
+    message: `${source} accepted split of ${story.id} into ${updatedSubHUs.length} sub-HUs`,
+    detail: { originalId: story.id, subHUs: updatedSubHUs.map((s) => s.id), heuristic }
+  }));
+}
+
+/**
+ * @param {object} args
+ * @param {object} args.batch              — HU batch (mutated in place)
+ * @param {string} args.batchSessionId     — for saveHuBatch persistence
+ * @param {Function|null} args.askQuestion — interactive prompt (null = auto-accept)
+ * @param {object} args.config
+ * @param {object} args.logger
+ * @param {object} args.emitter
+ * @param {object} args.eventBase
+ */
+export async function detectAndApplySplits({ batch, batchSessionId, askQuestion, config, logger, emitter, eventBase }) {
+  const storiesToSplit = [...batch.stories].filter((s) => s.status === "pending");
+  for (const story of storiesToSplit) {
+    const indicators = detectIndicators(story.original.text);
+    if (indicators.length === 0) continue;
+
+    let heuristic = selectHeuristic(indicators);
+    if (!heuristic) continue;
+
+    const triedHeuristics = [];
+
+    while (heuristic) {
+      const proposal = await generateSplitProposal(
+        { id: story.id, text: story.original.text },
+        heuristic, config, logger
+      );
+
+      if (!proposal) {
+        triedHeuristics.push(heuristic);
+        heuristic = selectHeuristic(indicators, triedHeuristics);
+        continue;
+      }
+
+      if (!askQuestion) {
+        // Autonomous mode: auto-accept the split.
+        applySplit({ batch, story, proposal, heuristic, source: "Auto", eventBase, emitter });
+      } else {
+        // Interactive mode: ask FDE for confirmation.
+        const formatted = formatSplitProposalForFDE(proposal);
+        const question = `Split proposed for ${story.id}:\n${formatted}\nAccept? (yes/no/try another)`;
+        emitProgress(emitter, makeEvent("hu-reviewer:split-proposal", { ...eventBase, stage: "hu-reviewer" }, {
+          message: `Split proposal for ${story.id} using heuristic: ${heuristic}`,
+          detail: { originalId: story.id, heuristic, subHUCount: proposal.subHUs.length }
+        }));
+        const answer = await askQuestion(question, { iteration: 0, stage: "hu-reviewer" });
+        if (!answer || answer.toLowerCase().startsWith("yes")) {
+          applySplit({ batch, story, proposal, heuristic, source: "FDE", eventBase, emitter });
+        } else if (answer.toLowerCase().includes("try") || answer.toLowerCase().startsWith("no")) {
+          triedHeuristics.push(heuristic);
+          heuristic = selectHeuristic(indicators, triedHeuristics);
+          if (!heuristic) {
+            updateStoryStatus(batch, story.id, "needs_context");
+          }
+          continue;
+        }
+      }
+      break;
+    }
+    await saveHuBatch(batchSessionId, batch);
+  }
+}

package/src/orchestrator/stages/hu-reviewer-stage.js

@@ -6,14 +6,13 @@
 import { DiscoverRole } from "../../roles/discover-role.js";
 import { HuReviewerRole } from "../../roles/hu-reviewer-role.js";
 import { createAgent } from "../../agents/index.js";
-import { addCheckpoint } from "../../session-store.js";
+import { addCheckpoint } from "../../session/store.js";
 import { emitProgress, makeEvent } from "../../utils/events.js";
 import { buildDecompositionPrompt, parseDecompositionOutput } from "../../prompts/hu-reviewer.js";
 import { createStallDetector } from "../../utils/stall-detector.js";
 import { createHuBatch, loadHuBatch, saveHuBatch, updateStoryStatus, updateStoryQuality, updateStoryCertified, addContextRequest, answerContextRequest } from "../../hu/store.js";
 import { topologicalSort } from "../../hu/graph.js";
-import { detectIndicators, selectHeuristic } from "../../hu/splitting-detector.js";
-import { generateSplitProposal, formatSplitProposalForFDE, buildSplitDependencies } from "../../hu/splitting-generator.js";
+import { detectAndApplySplits } from "./hu-reviewer-phases/detect-and-apply-splits.js";
 
 /**
  * Use an AI agent to decompose a complex task into multiple formal HUs.
@@ -239,83 +238,11 @@ export async function runHuReviewerStage({ config, logger, emitter, eventBase, s
     batch = await createHuBatch(batchSessionId, stories);
   }
 
-  // --- Splitting detection: check each pending HU for split indicators before 6D evaluation ---
-  const storiesToSplit = [...batch.stories].filter(s => s.status === "pending");
-  for (const story of storiesToSplit) {
-    const indicators = detectIndicators(story.original.text);
-    if (indicators.length === 0) continue;
-
-    let heuristic = selectHeuristic(indicators);
-    if (!heuristic) continue;
-
-    const triedHeuristics = [];
-    let splitAccepted = false;
-
-    while (heuristic && !splitAccepted) {
-      const proposal = await generateSplitProposal(
-        { id: story.id, text: story.original.text },
-        heuristic, config, logger
-      );
-
-      if (!proposal) {
-        triedHeuristics.push(heuristic);
-        heuristic = selectHeuristic(indicators, triedHeuristics);
-        continue;
-      }
+  // --- Splitting detection: extracted to hu-reviewer-phases/detect-and-apply-splits.js (PR-M) ---
+  await detectAndApplySplits({
+    batch, batchSessionId, askQuestion, config, logger, emitter, eventBase,
+  });
 
-      if (!askQuestion) {
-        // Autonomous mode: auto-accept the split
-        const updatedSubHUs = buildSplitDependencies(proposal.subHUs, story);
-        const storyIndex = batch.stories.findIndex(s => s.id === story.id);
-        const newStories = updatedSubHUs.map(sub => ({
-          id: sub.id, status: "pending",
-          original: { text: `${sub.title}\n\n${sub.text}\n\nAcceptance Criteria:\n${(sub.acceptanceCriteria || []).map(ac => `- ${ac}`).join("\n")}` },
-          blocked_by: sub.blocked_by || [], certified: null, quality: null,
-          context_requests: [], created_at: new Date().toISOString(), updated_at: new Date().toISOString()
-        }));
-        batch.stories.splice(storyIndex, 1, ...newStories);
-        splitAccepted = true;
-        emitProgress(emitter, makeEvent("hu-reviewer:split-accepted", { ...eventBase, stage: "hu-reviewer" }, {
-          message: `Auto-accepted split of ${story.id} into ${updatedSubHUs.length} sub-HUs`,
-          detail: { originalId: story.id, subHUs: updatedSubHUs.map(s => s.id), heuristic }
-        }));
-      } else {
-        // Interactive mode: ask FDE for confirmation
-        const formatted = formatSplitProposalForFDE(proposal);
-        const question = `Split proposed for ${story.id}:\n${formatted}\nAccept? (yes/no/try another)`;
-        emitProgress(emitter, makeEvent("hu-reviewer:split-proposal", { ...eventBase, stage: "hu-reviewer" }, {
-          message: `Split proposal for ${story.id} using heuristic: ${heuristic}`,
-          detail: { originalId: story.id, heuristic, subHUCount: proposal.subHUs.length }
-        }));
-        const answer = await askQuestion(question, { iteration: 0, stage: "hu-reviewer" });
-        if (!answer || answer.toLowerCase().startsWith("yes")) {
-          const updatedSubHUs = buildSplitDependencies(proposal.subHUs, story);
-          const storyIndex = batch.stories.findIndex(s => s.id === story.id);
-          const newStories = updatedSubHUs.map(sub => ({
-            id: sub.id, status: "pending",
-            original: { text: `${sub.title}\n\n${sub.text}\n\nAcceptance Criteria:\n${(sub.acceptanceCriteria || []).map(ac => `- ${ac}`).join("\n")}` },
-            blocked_by: sub.blocked_by || [], certified: null, quality: null,
-            context_requests: [], created_at: new Date().toISOString(), updated_at: new Date().toISOString()
-          }));
-          batch.stories.splice(storyIndex, 1, ...newStories);
-          splitAccepted = true;
-          emitProgress(emitter, makeEvent("hu-reviewer:split-accepted", { ...eventBase, stage: "hu-reviewer" }, {
-            message: `FDE accepted split of ${story.id} into ${updatedSubHUs.length} sub-HUs`,
-            detail: { originalId: story.id, subHUs: updatedSubHUs.map(s => s.id), heuristic }
-          }));
-        } else if (answer.toLowerCase().includes("try") || answer.toLowerCase().startsWith("no")) {
-          triedHeuristics.push(heuristic);
-          heuristic = selectHeuristic(indicators, triedHeuristics);
-          if (!heuristic) {
-            updateStoryStatus(batch, story.id, "needs_context");
-          }
-          continue;
-        }
-      }
-      break;
-    }
-    await saveHuBatch(batchSessionId, batch);
-  }
 
   // --- Evaluate loop (re-evaluate entire batch until all certified or needs_context with no askQuestion) ---
   const huReviewerOnOutput = ({ stream, line }) => {

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

@@ -5,7 +5,7 @@
 
 import { PlannerRole } from "../../roles/planner-role.js";
 import { createAgent } from "../../agents/index.js";
-import { addCheckpoint, markSessionStatus } from "../../session-store.js";
+import { addCheckpoint, markSessionStatus } from "../../session/store.js";
 import { emitProgress, makeEvent, emitAgentOutput } from "../../utils/events.js";
 import { parsePlannerOutput } from "../../prompts/planner.js";
 import { createStallDetector } from "../../utils/stall-detector.js";

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

@@ -4,7 +4,7 @@
  */
 
 import { ResearcherRole } from "../../roles/researcher-role.js";
-import { addCheckpoint } from "../../session-store.js";
+import { addCheckpoint } from "../../session/store.js";
 import { emitProgress, makeEvent, emitAgentOutput } from "../../utils/events.js";
 import { createStallDetector } from "../../utils/stall-detector.js";
 

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

@@ -3,10 +3,11 @@
  * Extracted from iteration-stages.js for maintainability.
  */
 
-import { addCheckpoint, markSessionStatus, saveSession } from "../../session-store.js";
+import { addCheckpoint, markSessionStatus, saveSession } from "../../session/store.js";
+import { setReviewerFeedback, setDeferredIssues } from "../../session/mutators.js";
 import { generateDiff } from "../../review/diff-generator.js";
 import { validateReviewResult } from "../../review/schema.js";
-import { filterReviewScope, buildDeferredContext } from "../../review/scope-filter.js";
+import { filterReviewScope } from "../../review/scope-filter.js";
 import { emitProgress, makeEvent, emitAgentOutput } from "../../utils/events.js";
 import { runReviewerWithFallback } from "../reviewer-fallback.js";
 import { invokeSolomon } from "../solomon-escalation.js";
@@ -110,7 +111,7 @@ async function handleReviewerStalledSolomon({ review, repeatCounts, repeatState,
   if (solomonResult.action === "continue") {
     repeatDetector.reviewer = { lastHash: null, repeatCount: 0 };
     if (solomonResult.humanGuidance) {
-      session.last_reviewer_feedback = `Solomon/user guidance: ${solomonResult.humanGuidance}`;
+      setReviewerFeedback(session, `Solomon/user guidance: ${solomonResult.humanGuidance}`);
       await saveSession(session);
     }
     return { review };
@@ -144,7 +145,6 @@ async function handleReviewerRejection({ review, repeatDetector, config, logger,
   if (brainCtx?.enabled && config.brain?.bypass_solomon_on_correctness !== false) {
     const cats = categorizeIssues(review.blocking_issues);
     const nonStyleIssues = cats.security + cats.correctness + cats.tests;
-    const styleIssues = cats.style;
     // Only bypass if there ARE non-style issues (correctness, tests, security, or "other" is correctness)
     // If it's style-only, let Solomon evaluate whether to override
     if (nonStyleIssues > 0 || cats.other > 0) {
@@ -156,9 +156,9 @@ async function handleReviewerRejection({ review, repeatDetector, config, logger,
         detail: { categories: cats, queueSize: brainCtx.feedbackQueue.entries.length }
       }));
       // Persist flat feedback for compat with non-Brain flow
-      session.last_reviewer_feedback = review.blocking_issues
+      setReviewerFeedback(session, review.blocking_issues
         .map((x, idx) => `R-${idx + 1} [${x.severity || "medium"}]: ${x.description}`)
-        .join("\n");
+        .join("\n"));
       await saveSession(session);
       return null; // null = continue to next iteration (coder fixes)
     }
@@ -339,7 +339,7 @@ export async function runReviewerStage({ reviewerRole, config, logger, emitter,
     logger.info(`Scope filter: deferred ${demoted.length} out-of-scope issue(s)${allDemoted ? " — auto-approved" : ""}`);
 
     // Accumulate deferred issues in session for tracking
-    if (!session.deferred_issues) session.deferred_issues = [];
+    if (!session.deferred_issues) setDeferredIssues(session, []);
     session.deferred_issues.push(...deferred);
     await saveSession(session);
 

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

@@ -4,10 +4,57 @@
  */
 
 import { SonarRole } from "../../roles/sonar-role.js";
-import { addCheckpoint, markSessionStatus, saveSession } from "../../session-store.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 { 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();
@@ -34,7 +81,7 @@ async function handleSonarRetryLimit({ config, logger, emitter, eventBase, sessi
       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 }
     }));
-    session.sonar_retry_count = 0;
+    resetRetryCount(session, "sonar");
     await saveSession(session);
     return { action: "continue" };
   }
@@ -66,9 +113,9 @@ async function handleSonarRetryLimit({ config, logger, emitter, eventBase, sessi
   }
   if (solomonResult.action === "continue") {
     if (solomonResult.humanGuidance) {
-      session.last_reviewer_feedback += `\nUser guidance: ${solomonResult.humanGuidance}`;
+      setReviewerFeedback(session, `${session.last_reviewer_feedback}\nUser guidance: ${solomonResult.humanGuidance}`);
     }
-    session.sonar_retry_count = 0;
+    resetRetryCount(session, "sonar");
     await saveSession(session);
     return { action: "continue" };
   }
@@ -89,7 +136,7 @@ async function handleSonarBlocking({ sonarResult, config, logger, emitter, event
         status: "warn",
         message: "Quality gate: coverage below threshold (advisory — code quality is clean)"
       }));
-      session.last_reviewer_feedback = null;
+      setReviewerFeedback(session, null);
       return { action: "ok", stageResult: { gateStatus: "WARN_COVERAGE", advisory: true } };
     }
   }
@@ -101,13 +148,13 @@ async function handleSonarBlocking({ sonarResult, config, logger, emitter, event
   }
 
   const summary = `Sonar gate blocking (${sonarResult.gateStatus}). Resolve critical findings first.`;
-  session.last_reviewer_feedback = summary;
+  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 });
   }
-  session.sonar_retry_count = (session.sonar_retry_count || 0) + 1;
+  incrementRetryCount(session, "sonar");
   await saveSession(session);
   const maxSonarRetries = config.session.max_sonar_retries ?? config.session.fail_fast_repeats;
 
@@ -120,6 +167,20 @@ async function handleSonarBlocking({ sonarResult, config, logger, emitter, event
 }
 
 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,
@@ -188,8 +249,31 @@ export async function runSonarStage({ config, logger, emitter, eventBase, sessio
       })
     );
 
-    // Brain: when enabled, skip Solomon for sonar errors — Brain handles via max_iterations
+    // 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)}`,
@@ -224,7 +308,7 @@ export async function runSonarStage({ config, logger, emitter, eventBase, sessio
     throw new Error(errorMessage);
   }
 
-  session.last_sonar_summary = sonarOutput.summary;
+  setSonarSummary(session, sonarOutput.summary);
   if (typeof sonarResult.openIssuesTotal === "number") {
     if (sonarState.issuesInitial === null) {
       sonarState.issuesInitial = sonarResult.openIssuesTotal;
@@ -255,7 +339,7 @@ export async function runSonarStage({ config, logger, emitter, eventBase, sessio
   }
 
   // Sonar passed — reset retry counter
-  session.sonar_retry_count = 0;
+  resetRetryCount(session, "sonar");
   const issuesInitial = sonarState.issuesInitial ?? sonarResult.openIssuesTotal ?? 0;
   const issuesFinal = sonarState.issuesFinal ?? sonarResult.openIssuesTotal ?? 0;
   const stageResult = {

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

@@ -0,0 +1,86 @@
+/**
+ * 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());
+
+export { StageExecutor, StageRegistry };

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

@@ -71,7 +71,7 @@ export class StageExecutor {
    * @param {StageContext} _ctx
    * @returns {Promise<StageOutcome | void>}
    */
-  // eslint-disable-next-line no-unused-vars
+   
   async onFailure(err, _ctx) {
     throw err;
   }

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

@@ -4,7 +4,7 @@
  */
 
 import { TriageRole } from "../../roles/triage-role.js";
-import { addCheckpoint } from "../../session-store.js";
+import { addCheckpoint } from "../../session/store.js";
 import { emitProgress, makeEvent, emitAgentOutput } from "../../utils/events.js";
 import { selectModelsForRoles } from "../../utils/model-selector.js";
 import { createStallDetector } from "../../utils/stall-detector.js";

package/src/orchestrator/standby.js

@@ -1,4 +1,5 @@
 import { emitProgress, makeEvent } from "../utils/events.js";
+import { setStatus } from "../session/mutators.js";
 
 const DEFAULT_COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
 const MAX_COOLDOWN_MS = 30 * 60 * 1000; // 30 minutes
@@ -37,7 +38,7 @@ export async function waitForCooldown({ cooldownMs, cooldownUntil, agent, retryC
   }));
 
   // Update session status
-  session.status = "standby";
+  setStatus(session, "standby");
 
   // Wait with periodic heartbeats
   const startTime = Date.now();
@@ -64,7 +65,7 @@ export async function waitForCooldown({ cooldownMs, cooldownUntil, agent, retryC
     detail: { agent, retryCount: retryCount + 1 }
   }));
 
-  session.status = "running";
+  setStatus(session, "running");
 }
 
 export { DEFAULT_COOLDOWN_MS, MAX_COOLDOWN_MS, MAX_STANDBY_RETRIES, HEARTBEAT_INTERVAL_MS };