@nathapp/nax 0.18.1

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

@@ -0,0 +1,388 @@
+/**
+ * Pipeline Result Handlers
+ *
+ * Extracted from sequential-executor.ts: handles pipeline success, failure,
+ * and dry-run outcomes after a story has been executed through the pipeline.
+ */
+
+import type { NaxConfig } from "../config";
+import { type LoadedHooksConfig, fireHook } from "../hooks";
+import type { InteractionChain } from "../interaction/chain";
+import { executeTrigger, isTriggerEnabled } from "../interaction/triggers";
+import { getSafeLogger } from "../logger";
+import type { StoryMetrics } from "../metrics";
+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;
+  prd: PRD;
+  prdPath: string;
+  workdir: string;
+  featureDir?: string;
+  hooks: LoadedHooksConfig;
+  feature: string;
+  totalCost: number;
+  startTime: number;
+  runId: string;
+  pluginRegistry: PluginRegistry;
+  story: UserStory;
+  storiesToExecute: UserStory[];
+  routing: ReturnType<typeof routeTask>;
+  isBatchExecution: boolean;
+  allStoryMetrics: StoryMetrics[];
+  timeoutRetryCountMap: Map<string, number>;
+  storyGitRef: string | null | undefined;
+  interactionChain?: InteractionChain | null;
+}
+
+export interface PipelineSuccessResult {
+  storiesCompletedDelta: number;
+  costDelta: number;
+  prd: PRD;
+  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;
+
+  // 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,
+    storyGitRef: ctx.storyGitRef ?? undefined,
+  });
+  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,
+      });
+
+      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,
+      });
+    }
+  }
+
+  // Display progress
+  const updatedCounts = countStories(prd);
+  const elapsedMs = Date.now() - ctx.startTime;
+  logger?.info("progress", "Progress update", {
+    totalStories: updatedCounts.total,
+    passedStories: updatedCounts.passed,
+    failedStories: updatedCounts.failed,
+    pendingStories: updatedCounts.pending,
+    totalCost: ctx.totalCost + costDelta,
+    costLimit: ctx.config.execution.costLimit,
+    elapsedMs,
+  });
+
+  return { storiesCompletedDelta, costDelta, prd, prdDirty: true };
+}
+
+export interface PipelineFailureResult {
+  prd: PRD;
+  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;
+
+  switch (pipelineResult.finalAction) {
+    case "pause":
+      markStoryPaused(prd, ctx.story.id);
+      await savePRD(prd, ctx.prdPath);
+      prdDirty = true;
+
+      logger?.warn("pipeline", "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,
+      });
+      break;
+
+    case "skip":
+      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,
+      });
+
+      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,
+        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,
+      });
+      break;
+
+    case "escalate": {
+      const escalationResult = await handleTierEscalation({
+        story: ctx.story,
+        storiesToExecute: ctx.storiesToExecute,
+        isBatchExecution: ctx.isBatchExecution,
+        routing: ctx.routing,
+        pipelineResult,
+        config: ctx.config,
+        prd,
+        prdPath: ctx.prdPath,
+        featureDir: ctx.featureDir,
+        hooks: ctx.hooks,
+        feature: ctx.feature,
+        totalCost: ctx.totalCost,
+        workdir: ctx.workdir,
+      });
+
+      prd = escalationResult.prd;
+      prdDirty = escalationResult.prdDirty;
+      break;
+    }
+  }
+
+  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 };
+}

package/src/execution/post-verify-rectification.ts

@@ -0,0 +1,188 @@
+/**
+ * Post-Verify Rectification Loop
+ *
+ * Extracted from post-verify.ts: rectification retry loop and
+ * failure reversion logic shared by both scoped and regression paths.
+ */
+
+import { getAgent } from "../agents";
+import type { NaxConfig } from "../config";
+import { resolveModel } from "../config";
+import { getSafeLogger } from "../logger";
+import type { StoryMetrics } from "../metrics";
+import type { PRD, UserStory } from "../prd";
+import { getExpectedFiles, savePRD } from "../prd";
+import { appendProgress } from "./progress";
+import { type RectificationState, createRectificationPrompt, shouldRetryRectification } from "./rectification";
+import { parseBunTestOutput } from "./test-output-parser";
+import { runVerification } from "./verification";
+
+export interface RectificationLoopOptions {
+  config: NaxConfig;
+  workdir: string;
+  story: UserStory;
+  testCommand: string;
+  timeoutSeconds: number;
+  testOutput: string;
+  promptPrefix?: string;
+}
+
+/**
+ * Run the rectification retry loop. Returns true if rectification fixed all failures.
+ */
+export async function runRectificationLoop(opts: RectificationLoopOptions): Promise<boolean> {
+  const { config, workdir, story, testCommand, timeoutSeconds, testOutput, promptPrefix } = opts;
+  const logger = getSafeLogger();
+
+  const rectificationConfig = config.execution.rectification;
+  const testSummary = parseBunTestOutput(testOutput);
+
+  const rectificationState: RectificationState = {
+    attempt: 0,
+    initialFailures: testSummary.failed,
+    currentFailures: testSummary.failed,
+  };
+
+  const label = promptPrefix ? "regression rectification" : "rectification";
+  logger?.info("rectification", `Starting ${label} loop`, {
+    storyId: story.id,
+    initialFailures: rectificationState.initialFailures,
+    maxRetries: rectificationConfig.maxRetries,
+  });
+
+  while (shouldRetryRectification(rectificationState, rectificationConfig)) {
+    rectificationState.attempt++;
+
+    logger?.info("rectification", `${label} attempt ${rectificationState.attempt}/${rectificationConfig.maxRetries}`, {
+      storyId: story.id,
+      currentFailures: rectificationState.currentFailures,
+    });
+
+    let rectificationPrompt = createRectificationPrompt(testSummary.failures, story, rectificationConfig);
+    if (promptPrefix) {
+      rectificationPrompt = `${promptPrefix}\n\n${rectificationPrompt}`;
+    }
+
+    const agent = getAgent(config.autoMode.defaultAgent);
+    if (!agent) {
+      logger?.error("rectification", "Agent not found, cannot retry");
+      break;
+    }
+
+    const modelTier = story.routing?.modelTier || config.autoMode.escalation.tierOrder[0]?.tier || "balanced";
+    const modelDef = resolveModel(config.models[modelTier]);
+
+    const agentResult = await agent.run({
+      prompt: rectificationPrompt,
+      workdir,
+      modelTier,
+      modelDef,
+      timeoutSeconds: config.execution.sessionTimeoutSeconds,
+      dangerouslySkipPermissions: config.execution.dangerouslySkipPermissions,
+    });
+
+    if (!agentResult.success) {
+      logger?.warn("rectification", `Agent ${label} session failed`, {
+        storyId: story.id,
+        attempt: rectificationState.attempt,
+      });
+    }
+
+    const retryVerification = await runVerification({
+      workingDirectory: workdir,
+      expectedFiles: getExpectedFiles(story),
+      command: testCommand,
+      timeoutSeconds,
+      forceExit: config.quality.forceExit,
+      detectOpenHandles: config.quality.detectOpenHandles,
+      detectOpenHandlesRetries: config.quality.detectOpenHandlesRetries,
+      timeoutRetryCount: 0,
+      gracePeriodMs: config.quality.gracePeriodMs,
+      drainTimeoutMs: config.quality.drainTimeoutMs,
+      shell: config.quality.shell,
+      stripEnvVars: config.quality.stripEnvVars,
+    });
+
+    if (retryVerification.success) {
+      logger?.info("rectification", `[OK] ${label} succeeded!`, {
+        storyId: story.id,
+        attempt: rectificationState.attempt,
+        initialFailures: rectificationState.initialFailures,
+      });
+      return true;
+    }
+
+    if (retryVerification.output) {
+      const newTestSummary = parseBunTestOutput(retryVerification.output);
+      rectificationState.currentFailures = newTestSummary.failed;
+      testSummary.failures = newTestSummary.failures;
+      testSummary.failed = newTestSummary.failed;
+      testSummary.passed = newTestSummary.passed;
+    }
+  }
+
+  if (rectificationState.attempt >= rectificationConfig.maxRetries) {
+    logger?.warn("rectification", `${label} exhausted max retries`, {
+      storyId: story.id,
+      attempts: rectificationState.attempt,
+      remainingFailures: rectificationState.currentFailures,
+    });
+  } else if (rectificationState.currentFailures > rectificationState.initialFailures) {
+    logger?.warn("rectification", `${label} aborted due to further regression`, {
+      storyId: story.id,
+      initialFailures: rectificationState.initialFailures,
+      currentFailures: rectificationState.currentFailures,
+    });
+  }
+
+  return false;
+}
+
+export interface RevertStoriesOptions {
+  prd: PRD;
+  prdPath: string;
+  story: UserStory;
+  storiesToExecute: UserStory[];
+  allStoryMetrics: StoryMetrics[];
+  featureDir?: string;
+  diagnosticContext: string;
+  countsTowardEscalation: boolean;
+}
+
+/** Revert stories to pending on verification failure and save PRD. */
+export async function revertStoriesOnFailure(opts: RevertStoriesOptions): Promise<PRD> {
+  const storyIds = new Set(opts.storiesToExecute.map((s) => s.id));
+
+  // Remove stale metrics
+  for (let i = opts.allStoryMetrics.length - 1; i >= 0; i--) {
+    if (storyIds.has(opts.allStoryMetrics[i].storyId)) {
+      opts.allStoryMetrics.splice(i, 1);
+    }
+  }
+
+  // Revert stories to pending with diagnostic context
+  opts.prd.userStories = opts.prd.userStories.map((s) =>
+    storyIds.has(s.id)
+      ? {
+          ...s,
+          priorErrors: [...(s.priorErrors || []), opts.diagnosticContext],
+          status: "pending" as const,
+          passes: false,
+        }
+      : s,
+  );
+
+  if (opts.countsTowardEscalation) {
+    opts.prd.userStories = opts.prd.userStories.map((s) =>
+      s.id === opts.story.id ? { ...s, attempts: s.attempts + 1 } : s,
+    );
+  }
+
+  await savePRD(opts.prd, opts.prdPath);
+
+  if (opts.featureDir) {
+    await appendProgress(opts.featureDir, opts.story.id, "failed", `${opts.story.title} -- ${opts.diagnosticContext}`);
+  }
+
+  return opts.prd;
+}