@nathapp/nax 0.20.0 → 0.22.0

package/src/execution/iteration-runner.ts

@@ -0,0 +1,132 @@
+/**
+ * Iteration Runner (ADR-005, Phase 4)
+ *
+ * Runs a single story through the pipeline.
+ * Extracted from sequential-executor.ts to slim it below 120 lines.
+ */
+
+import { getSafeLogger } from "../logger";
+import type { StoryMetrics } from "../metrics";
+import { runPipeline } from "../pipeline/runner";
+import type { PipelineRunResult } from "../pipeline/runner";
+import { defaultPipeline } from "../pipeline/stages";
+import type { PipelineContext } from "../pipeline/types";
+import type { PRD } from "../prd/types";
+import { captureGitRef } from "../utils/git";
+import { handleDryRun } from "./dry-run";
+import type { SequentialExecutionContext } from "./executor-types";
+import { handlePipelineFailure, handlePipelineSuccess } from "./pipeline-result-handler";
+import type { StorySelection } from "./story-selector";
+
+export interface IterationResult {
+  prd: PRD;
+  storiesCompletedDelta: number;
+  costDelta: number;
+  prdDirty: boolean;
+  finalAction?: string;
+  reason?: string;
+}
+
+export async function runIteration(
+  ctx: SequentialExecutionContext,
+  prd: PRD,
+  selection: StorySelection,
+  iterations: number,
+  totalCost: number,
+  allStoryMetrics: StoryMetrics[],
+): Promise<IterationResult> {
+  const logger = getSafeLogger();
+  const { story, storiesToExecute, routing, isBatchExecution } = selection;
+
+  if (ctx.dryRun) {
+    const dryRunResult = await handleDryRun({
+      prd,
+      prdPath: ctx.prdPath,
+      storiesToExecute,
+      routing,
+      statusWriter: ctx.statusWriter,
+      pluginRegistry: ctx.pluginRegistry,
+      runId: ctx.runId,
+      totalCost,
+      iterations,
+    });
+    return {
+      prd,
+      storiesCompletedDelta: dryRunResult.storiesCompletedDelta,
+      costDelta: 0,
+      prdDirty: dryRunResult.prdDirty,
+    };
+  }
+
+  const storyGitRef = await captureGitRef(ctx.workdir);
+  const pipelineContext: PipelineContext = {
+    config: ctx.config,
+    prd,
+    story,
+    stories: storiesToExecute,
+    routing,
+    workdir: ctx.workdir,
+    featureDir: ctx.featureDir,
+    hooks: ctx.hooks,
+    plugins: ctx.pluginRegistry,
+    storyStartTime: new Date().toISOString(),
+    storyGitRef: storyGitRef ?? undefined,
+    interaction: ctx.interactionChain ?? undefined,
+  };
+
+  ctx.statusWriter.setPrd(prd);
+  ctx.statusWriter.setCurrentStory({
+    storyId: story.id,
+    title: story.title,
+    complexity: routing.complexity,
+    tddStrategy: routing.testStrategy,
+    model: routing.modelTier,
+    attempt: (story.attempts ?? 0) + 1,
+    phase: "routing",
+  });
+  await ctx.statusWriter.update(totalCost, iterations);
+
+  const pipelineResult = await runPipeline(defaultPipeline, pipelineContext, ctx.eventEmitter);
+  const currentPrd = pipelineResult.context.prd;
+
+  const handlerCtx = {
+    config: ctx.config,
+    prd: currentPrd,
+    prdPath: ctx.prdPath,
+    workdir: ctx.workdir,
+    featureDir: ctx.featureDir,
+    hooks: ctx.hooks,
+    feature: ctx.feature,
+    totalCost,
+    startTime: ctx.startTime,
+    runId: ctx.runId,
+    pluginRegistry: ctx.pluginRegistry,
+    story,
+    storiesToExecute,
+    routing: pipelineResult.context.routing ?? routing,
+    isBatchExecution,
+    allStoryMetrics,
+    storyGitRef,
+    interactionChain: ctx.interactionChain,
+  };
+
+  if (pipelineResult.success) {
+    const r = await handlePipelineSuccess(handlerCtx, pipelineResult);
+    return {
+      prd: r.prd,
+      storiesCompletedDelta: r.storiesCompletedDelta,
+      costDelta: r.costDelta,
+      prdDirty: r.prdDirty,
+      finalAction: pipelineResult.finalAction,
+    };
+  }
+  const r = await handlePipelineFailure(handlerCtx, pipelineResult);
+  return {
+    prd: r.prd,
+    storiesCompletedDelta: 0,
+    costDelta: 0,
+    prdDirty: r.prdDirty,
+    finalAction: pipelineResult.finalAction,
+    reason: pipelineResult.reason,
+  };
+}

package/src/execution/lifecycle/index.ts

@@ -3,7 +3,6 @@
  */
 
 export { runAcceptanceLoop, type AcceptanceLoopContext, type AcceptanceLoopResult } from "./acceptance-loop";
-export { emitStoryComplete, type StoryCompleteEvent } from "./story-hooks";
 export { outputRunHeader, outputRunFooter, type RunHeaderOptions, type RunFooterOptions } from "./headless-formatter";
 export { handleParallelCompletion, type ParallelCompletionOptions } from "./parallel-lifecycle";
 export { handleRunCompletion, type RunCompletionOptions, type RunCompletionResult } from "./run-completion";

package/src/execution/lifecycle/run-regression.ts

@@ -14,16 +14,16 @@ import type { PRD, UserStory } from "../../prd";
 import { countStories } from "../../prd";
 import { hasCommitsForStory } from "../../utils/git";
 import { parseBunTestOutput } from "../../verification";
+import { runRectificationLoop } from "../../verification/rectification-loop";
+import { fullSuite } from "../../verification/runners";
 import { reverseMapTestToSource } from "../../verification/smart-runner";
-import { runRectificationLoop } from "../post-verify-rectification";
-import { runVerification } from "../verification";
 
 /**
  * Injectable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
  * @internal - test use only.
  */
 export const _regressionDeps = {
-  runVerification,
+  runVerification: fullSuite,
   runRectificationLoop,
   parseBunTestOutput,
   reverseMapTestToSource,
@@ -133,7 +133,7 @@ export async function runDeferredRegression(options: DeferredRegressionOptions):
 
   // Step 1: Run full test suite
   const fullSuiteResult = await _regressionDeps.runVerification({
-    workingDirectory: workdir,
+    workdir: workdir,
     command: testCommand,
     timeoutSeconds,
     forceExit: config.quality.forceExit,
@@ -268,7 +268,7 @@ export async function runDeferredRegression(options: DeferredRegressionOptions):
   // Step 4: Re-run full suite to confirm
   logger?.info("regression", "Re-running full suite after rectification");
   const retryResult = await _regressionDeps.runVerification({
-    workingDirectory: workdir,
+    workdir: workdir,
     command: testCommand,
     timeoutSeconds,
     forceExit: config.quality.forceExit,

package/src/execution/pipeline-result-handler.ts

@@ -1,31 +1,27 @@
 /**
- * Pipeline Result Handlers
+ * Pipeline Result Handlers (ADR-005, Phase 4)
  *
- * Extracted from sequential-executor.ts: handles pipeline success, failure,
- * and dry-run outcomes after a story has been executed through the pipeline.
+ * Handles pipeline success, failure outcomes after story execution.
+ * Dry-run handling: see execution/dry-run.ts
+ * applyCachedRouting: removed (P4-001 — pipeline routing stage is sole source)
  */
 
 import type { NaxConfig } from "../config";
-import { type LoadedHooksConfig, fireHook } from "../hooks";
+import type { LoadedHooksConfig } from "../hooks";
 import type { InteractionChain } from "../interaction/chain";
-import { executeTrigger, isTriggerEnabled } from "../interaction/triggers";
 import { getSafeLogger } from "../logger";
 import type { StoryMetrics } from "../metrics";
+import { pipelineEventBus } from "../pipeline/event-bus";
 import type { PipelineRunResult } from "../pipeline/runner";
 import type { PluginRegistry } from "../plugins";
 import { countStories, markStoryFailed, markStoryPaused, savePRD } from "../prd";
 import type { PRD, UserStory } from "../prd/types";
 import type { routeTask } from "../routing";
 import { handleTierEscalation } from "./escalation";
-import { hookCtx } from "./helpers";
-import { emitStoryComplete } from "./lifecycle/story-hooks";
-import { runPostAgentVerification } from "./post-verify";
 import { appendProgress } from "./progress";
-import type { StatusWriter } from "./status-writer";
 
-/** Context needed by pipeline result handlers */
 export interface PipelineHandlerContext {
-  config: import("../config").NaxConfig;
+  config: NaxConfig;
   prd: PRD;
   prdPath: string;
   workdir: string;
@@ -41,7 +37,6 @@ export interface PipelineHandlerContext {
   routing: ReturnType<typeof routeTask>;
   isBatchExecution: boolean;
   allStoryMetrics: StoryMetrics[];
-  timeoutRetryCountMap: Map<string, number>;
   storyGitRef: string | null | undefined;
   interactionChain?: InteractionChain | null;
 }
@@ -53,68 +48,40 @@ export interface PipelineSuccessResult {
   prdDirty: boolean;
 }
 
-/**
- * Handle a successful pipeline execution:
- * - Post-agent verification
- * - Emit story completion events
- * - Log progress
- */
 export async function handlePipelineSuccess(
   ctx: PipelineHandlerContext,
   pipelineResult: PipelineRunResult,
 ): Promise<PipelineSuccessResult> {
   const logger = getSafeLogger();
   const costDelta = pipelineResult.context.agentResult?.estimatedCost || 0;
-  let prd = ctx.prd;
+  const prd = ctx.prd;
 
-  // Collect story metrics
   if (pipelineResult.context.storyMetrics) {
     ctx.allStoryMetrics.push(...pipelineResult.context.storyMetrics);
   }
 
-  // Post-agent verification
-  const verifyResult = await runPostAgentVerification({
-    config: ctx.config,
-    prd,
-    prdPath: ctx.prdPath,
-    workdir: ctx.workdir,
-    featureDir: ctx.featureDir,
-    story: ctx.story,
-    storiesToExecute: ctx.storiesToExecute,
-    allStoryMetrics: ctx.allStoryMetrics,
-    timeoutRetryCountMap: ctx.timeoutRetryCountMap,
-  });
-  const verificationPassed = verifyResult.passed;
-  prd = verifyResult.prd;
-
-  let storiesCompletedDelta = 0;
-  if (verificationPassed) {
-    storiesCompletedDelta = ctx.storiesToExecute.length;
-
-    const reporters = ctx.pluginRegistry.getReporters();
-    for (const completedStory of ctx.storiesToExecute) {
-      logger?.info("story.complete", "Story completed successfully", {
-        storyId: completedStory.id,
-        storyTitle: completedStory.title,
-        totalCost: ctx.totalCost + costDelta,
-        durationMs: Date.now() - ctx.startTime,
-      });
+  const storiesCompletedDelta = ctx.storiesToExecute.length;
+  for (const completedStory of ctx.storiesToExecute) {
+    logger?.info("story.complete", "Story completed successfully", {
+      storyId: completedStory.id,
+      storyTitle: completedStory.title,
+      totalCost: ctx.totalCost + costDelta,
+      durationMs: Date.now() - ctx.startTime,
+    });
 
-      await emitStoryComplete(reporters, {
-        runId: ctx.runId,
-        storyId: completedStory.id,
-        status: "completed",
-        durationMs: Date.now() - ctx.startTime,
-        cost: costDelta,
-        tier: ctx.routing.modelTier,
-        testStrategy: ctx.routing.testStrategy,
-      });
-    }
+    pipelineEventBus.emit({
+      type: "story:completed",
+      storyId: completedStory.id,
+      story: completedStory,
+      passed: true,
+      durationMs: Date.now() - ctx.startTime,
+      cost: costDelta,
+      modelTier: ctx.routing.modelTier,
+      testStrategy: ctx.routing.testStrategy,
+    });
   }
 
-  // Display progress
   const updatedCounts = countStories(prd);
-  const elapsedMs = Date.now() - ctx.startTime;
   logger?.info("progress", "Progress update", {
     totalStories: updatedCounts.total,
     passedStories: updatedCounts.passed,
@@ -122,7 +89,7 @@ export async function handlePipelineSuccess(
     pendingStories: updatedCounts.pending,
     totalCost: ctx.totalCost + costDelta,
     costLimit: ctx.config.execution.costLimit,
-    elapsedMs,
+    elapsedMs: Date.now() - ctx.startTime,
   });
 
   return { storiesCompletedDelta, costDelta, prd, prdDirty: true };
@@ -133,16 +100,11 @@ export interface PipelineFailureResult {
   prdDirty: boolean;
 }
 
-/**
- * Handle a failed pipeline execution based on finalAction:
- * pause, skip, fail, or escalate.
- */
 export async function handlePipelineFailure(
   ctx: PipelineHandlerContext,
   pipelineResult: PipelineRunResult,
 ): Promise<PipelineFailureResult> {
   const logger = getSafeLogger();
-  const reporters = ctx.pluginRegistry.getReporters();
   let prd = ctx.prd;
   let prdDirty = false;
 
@@ -151,114 +113,49 @@ export async function handlePipelineFailure(
       markStoryPaused(prd, ctx.story.id);
       await savePRD(prd, ctx.prdPath);
       prdDirty = true;
-
-      logger?.warn("pipeline", "Story paused", {
+      logger?.warn("pipeline", "Story paused", { storyId: ctx.story.id, reason: pipelineResult.reason });
+      pipelineEventBus.emit({
+        type: "story:paused",
         storyId: ctx.story.id,
-        reason: pipelineResult.reason,
-      });
-
-      await fireHook(
-        ctx.hooks,
-        "on-pause",
-        hookCtx(ctx.feature, {
-          storyId: ctx.story.id,
-          reason: pipelineResult.reason || "Pipeline paused",
-          cost: ctx.totalCost,
-        }),
-        ctx.workdir,
-      );
-
-      await emitStoryComplete(reporters, {
-        runId: ctx.runId,
-        storyId: ctx.story.id,
-        status: "paused",
-        durationMs: Date.now() - ctx.startTime,
-        cost: pipelineResult.context.agentResult?.estimatedCost || 0,
-        tier: ctx.routing.modelTier,
-        testStrategy: ctx.routing.testStrategy,
+        reason: pipelineResult.reason || "Pipeline paused",
+        cost: ctx.totalCost,
       });
       break;
 
     case "skip":
-      logger?.warn("pipeline", "Story skipped", {
-        storyId: ctx.story.id,
-        reason: pipelineResult.reason,
-      });
+      logger?.warn("pipeline", "Story skipped", { storyId: ctx.story.id, reason: pipelineResult.reason });
       prdDirty = true;
-
-      await emitStoryComplete(reporters, {
-        runId: ctx.runId,
-        storyId: ctx.story.id,
-        status: "skipped",
-        durationMs: Date.now() - ctx.startTime,
-        cost: 0,
-        tier: ctx.routing.modelTier,
-        testStrategy: ctx.routing.testStrategy,
-      });
       break;
 
     case "fail":
       markStoryFailed(prd, ctx.story.id, pipelineResult.context.tddFailureCategory);
       await savePRD(prd, ctx.prdPath);
       prdDirty = true;
-
-      logger?.error("pipeline", "Story failed", {
-        storyId: ctx.story.id,
-        reason: pipelineResult.reason,
-      });
+      logger?.error("pipeline", "Story failed", { storyId: ctx.story.id, reason: pipelineResult.reason });
 
       if (ctx.featureDir) {
         await appendProgress(ctx.featureDir, ctx.story.id, "failed", `${ctx.story.title} — ${pipelineResult.reason}`);
       }
 
-      // Fire human-review trigger when story has exceeded max retries and interaction chain is available
-      if (
-        ctx.interactionChain &&
-        ctx.story.attempts !== undefined &&
-        ctx.story.attempts >= ctx.config.execution.rectification.maxRetries &&
-        isTriggerEnabled("human-review", ctx.config)
-      ) {
-        try {
-          await executeTrigger(
-            "human-review",
-            {
-              featureName: ctx.feature,
-              storyId: ctx.story.id,
-              iteration: ctx.story.attempts,
-              reason: pipelineResult.reason || "Max retries exceeded",
-            },
-            ctx.config,
-            ctx.interactionChain,
-          );
-        } catch (err) {
-          logger?.warn("pipeline", "human-review trigger failed", {
-            storyId: ctx.story.id,
-            error: String(err),
-          });
-        }
-      }
-
-      await fireHook(
-        ctx.hooks,
-        "on-story-fail",
-        hookCtx(ctx.feature, {
-          storyId: ctx.story.id,
-          status: "failed",
-          reason: pipelineResult.reason || "Pipeline failed",
-          cost: ctx.totalCost,
-        }),
-        ctx.workdir,
-      );
-
-      await emitStoryComplete(reporters, {
-        runId: ctx.runId,
+      pipelineEventBus.emit({
+        type: "story:failed",
         storyId: ctx.story.id,
-        status: "failed",
-        durationMs: Date.now() - ctx.startTime,
-        cost: pipelineResult.context.agentResult?.estimatedCost || 0,
-        tier: ctx.routing.modelTier,
-        testStrategy: ctx.routing.testStrategy,
+        story: ctx.story,
+        reason: pipelineResult.reason || "Pipeline failed",
+        countsTowardEscalation: true,
+        feature: ctx.feature,
+        attempts: ctx.story.attempts,
       });
+
+      if (ctx.story.attempts !== undefined && ctx.story.attempts >= ctx.config.execution.rectification.maxRetries) {
+        pipelineEventBus.emit({
+          type: "human-review:requested",
+          storyId: ctx.story.id,
+          reason: pipelineResult.reason || "Max retries exceeded",
+          feature: ctx.feature,
+          attempts: ctx.story.attempts,
+        });
+      }
       break;
 
     case "escalate": {
@@ -277,7 +174,6 @@ export async function handlePipelineFailure(
         totalCost: ctx.totalCost,
         workdir: ctx.workdir,
       });
-
       prd = escalationResult.prd;
       prdDirty = escalationResult.prdDirty;
       break;
@@ -286,102 +182,3 @@ export async function handlePipelineFailure(
 
   return { prd, prdDirty };
 }
-
-/**
- * Apply cached routing overrides from story.routing to a fresh routing decision.
- */
-export function applyCachedRouting(
-  routing: ReturnType<typeof routeTask>,
-  story: UserStory,
-  config: NaxConfig,
-): ReturnType<typeof routeTask> {
-  if (!story.routing) return routing;
-  const overrides: Partial<ReturnType<typeof routeTask>> = {};
-  if (story.routing.complexity) {
-    overrides.complexity = story.routing.complexity;
-  }
-  // BUG-013 fix: Use story.routing.modelTier directly if present (set by escalation).
-  // Only derive from complexity if modelTier is not explicitly set.
-  if (story.routing.modelTier) {
-    overrides.modelTier = story.routing.modelTier as ReturnType<typeof routeTask>["modelTier"];
-  } else if (story.routing.complexity) {
-    const tierFromComplexity = config.autoMode.complexityRouting[story.routing.complexity] ?? "balanced";
-    overrides.modelTier = tierFromComplexity as ReturnType<typeof routeTask>["modelTier"];
-  }
-  if (story.routing.testStrategy) {
-    overrides.testStrategy = story.routing.testStrategy;
-  }
-  return { ...routing, ...overrides };
-}
-
-/** Context for dry-run iteration handling */
-export interface DryRunContext {
-  prd: PRD;
-  prdPath: string;
-  storiesToExecute: UserStory[];
-  routing: ReturnType<typeof routeTask>;
-  statusWriter: StatusWriter;
-  pluginRegistry: PluginRegistry;
-  runId: string;
-  totalCost: number;
-  iterations: number;
-}
-
-export interface DryRunResult {
-  storiesCompletedDelta: number;
-  prdDirty: boolean;
-}
-
-/** Handle dry-run iteration: log what would happen, mark stories passed. */
-export async function handleDryRun(ctx: DryRunContext): Promise<DryRunResult> {
-  const logger = getSafeLogger();
-
-  ctx.statusWriter.setPrd(ctx.prd);
-  ctx.statusWriter.setCurrentStory({
-    storyId: ctx.storiesToExecute[0].id,
-    title: ctx.storiesToExecute[0].title,
-    complexity: ctx.routing.complexity,
-    tddStrategy: ctx.routing.testStrategy,
-    model: ctx.routing.modelTier,
-    attempt: (ctx.storiesToExecute[0].attempts ?? 0) + 1,
-    phase: "routing",
-  });
-  await ctx.statusWriter.update(ctx.totalCost, ctx.iterations);
-
-  for (const s of ctx.storiesToExecute) {
-    logger?.info("execution", "[DRY RUN] Would execute agent here", {
-      storyId: s.id,
-      storyTitle: s.title,
-      modelTier: ctx.routing.modelTier,
-      complexity: ctx.routing.complexity,
-      testStrategy: ctx.routing.testStrategy,
-    });
-  }
-
-  // Mark stories as passed so the loop progresses
-  for (const s of ctx.storiesToExecute) {
-    const { markStoryPassed } = await import("../prd");
-    markStoryPassed(ctx.prd, s.id);
-  }
-  await savePRD(ctx.prd, ctx.prdPath);
-
-  // Emit onStoryComplete events for dry-run
-  const reporters = ctx.pluginRegistry.getReporters();
-  for (const s of ctx.storiesToExecute) {
-    await emitStoryComplete(reporters, {
-      runId: ctx.runId,
-      storyId: s.id,
-      status: "completed",
-      durationMs: 0,
-      cost: 0,
-      tier: ctx.routing.modelTier,
-      testStrategy: ctx.routing.testStrategy,
-    });
-  }
-
-  ctx.statusWriter.setPrd(ctx.prd);
-  ctx.statusWriter.setCurrentStory(null);
-  await ctx.statusWriter.update(ctx.totalCost, ctx.iterations);
-
-  return { storiesCompletedDelta: ctx.storiesToExecute.length, prdDirty: true };
-}