@nathapp/nax 0.50.3 → 0.51.0

package/src/execution/deferred-review.ts

@@ -1,105 +0,0 @@
-/**
- * Deferred Plugin Review (DR-003)
- *
- * Captures the run-start git ref and runs all plugin reviewers once after
- * all stories complete, using the full diff from run-start to HEAD.
- */
-
-import { spawn } from "bun";
-import type { PluginRegistry } from "../plugins";
-import type { ReviewConfig } from "../review/types";
-
-/** Injectable deps for testing */
-export const _deferredReviewDeps = { spawn };
-
-export interface DeferredReviewResult {
-  runStartRef: string;
-  changedFiles: string[];
-  reviewerResults: Array<{
-    name: string;
-    passed: boolean;
-    output: string;
-    exitCode?: number;
-    error?: string;
-  }>;
-  anyFailed: boolean;
-}
-
-/** Capture the current HEAD git ref. Returns "" on failure. */
-export async function captureRunStartRef(workdir: string): Promise<string> {
-  try {
-    const proc = _deferredReviewDeps.spawn({
-      cmd: ["git", "rev-parse", "HEAD"],
-      cwd: workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    const [, stdout] = await Promise.all([proc.exited, new Response(proc.stdout).text()]);
-    return stdout.trim();
-  } catch {
-    return "";
-  }
-}
-
-async function getChangedFilesForDeferred(workdir: string, baseRef: string): Promise<string[]> {
-  try {
-    const proc = _deferredReviewDeps.spawn({
-      cmd: ["git", "diff", "--name-only", `${baseRef}...HEAD`],
-      cwd: workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    const [, stdout] = await Promise.all([proc.exited, new Response(proc.stdout).text()]);
-    return stdout.trim().split("\n").filter(Boolean);
-  } catch {
-    return [];
-  }
-}
-
-/** Run all plugin reviewers once with the full diff since runStartRef. */
-export async function runDeferredReview(
-  workdir: string,
-  reviewConfig: ReviewConfig,
-  plugins: PluginRegistry,
-  runStartRef: string,
-): Promise<DeferredReviewResult | undefined> {
-  if (!reviewConfig || reviewConfig.pluginMode !== "deferred") {
-    return undefined;
-  }
-
-  const reviewers = plugins.getReviewers();
-  if (reviewers.length === 0) {
-    return undefined;
-  }
-
-  const changedFiles = await getChangedFilesForDeferred(workdir, runStartRef);
-
-  const reviewerResults: DeferredReviewResult["reviewerResults"] = [];
-  let anyFailed = false;
-
-  for (const reviewer of reviewers) {
-    try {
-      const result = await reviewer.check(workdir, changedFiles);
-      reviewerResults.push({
-        name: reviewer.name,
-        passed: result.passed,
-        output: result.output,
-        exitCode: result.exitCode,
-      });
-      if (!result.passed) {
-        anyFailed = true;
-      }
-    } catch (error) {
-      const errorMsg = error instanceof Error ? error.message : String(error);
-      reviewerResults.push({
-        name: reviewer.name,
-        passed: false,
-        output: "",
-        error: errorMsg,
-      });
-      anyFailed = true;
-    }
-  }
-
-  return { runStartRef, changedFiles, reviewerResults, anyFailed };
-}

package/src/execution/dry-run.ts

@@ -1,81 +0,0 @@
-/**
- * Dry Run Handler (ADR-005, Phase 4)
- *
- * Extracted from pipeline-result-handler.ts to slim that file below 200 lines.
- */
-
-import { getSafeLogger } from "../logger";
-import { pipelineEventBus } from "../pipeline/event-bus";
-import type { PluginRegistry } from "../plugins";
-import { markStoryPassed, savePRD } from "../prd";
-import type { PRD, UserStory } from "../prd/types";
-import type { routeTask } from "../routing";
-import type { StatusWriter } from "./status-writer";
-
-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,
-    });
-  }
-
-  for (const s of ctx.storiesToExecute) {
-    markStoryPassed(ctx.prd, s.id);
-  }
-  await savePRD(ctx.prd, ctx.prdPath);
-
-  for (const s of ctx.storiesToExecute) {
-    pipelineEventBus.emit({
-      type: "story:completed",
-      storyId: s.id,
-      story: s,
-      passed: true,
-      runElapsedMs: 0,
-      cost: 0,
-      modelTier: 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/escalation/escalation.ts

@@ -1,46 +0,0 @@
-/**
- * Model Tier Escalation (ADR-003)
- *
- * Handles escalating model tiers through configurable tier chain
- * with per-tier attempt budgets.
- */
-
-import type { TierConfig } from "../../config";
-
-/**
- * Escalate to the next tier in the configured order.
- *
- * @param currentTier - Current tier name
- * @param tierOrder - Ordered tier config array from config (e.g., [{tier:"fast",attempts:5}, ...])
- * @returns Next tier name, or null if at max tier
- *
- * @example
- * ```typescript
- * const tiers = [{tier:"fast",attempts:5}, {tier:"balanced",attempts:3}, {tier:"powerful",attempts:2}];
- * escalateTier("fast", tiers);    // => "balanced"
- * escalateTier("powerful", tiers); // => null
- * ```
- */
-export function escalateTier(currentTier: string, tierOrder: TierConfig[]): string | null {
-  const getName = (t: TierConfig) => t.tier ?? (t as unknown as { name?: string }).name ?? null;
-  const currentIndex = tierOrder.findIndex((t) => getName(t) === currentTier);
-  if (currentIndex === -1 || currentIndex === tierOrder.length - 1) {
-    return null;
-  }
-  return getName(tierOrder[currentIndex + 1]);
-}
-
-/**
- * Get the tier config for a given tier name.
- */
-export function getTierConfig(tierName: string, tierOrder: TierConfig[]): TierConfig | undefined {
-  const getName = (t: TierConfig) => t.tier ?? (t as unknown as { name?: string }).name ?? null;
-  return tierOrder.find((t) => getName(t) === tierName);
-}
-
-/**
- * Calculate total max iterations from tier order (sum of all attempts).
- */
-export function calculateMaxIterations(tierOrder: TierConfig[]): number {
-  return tierOrder.reduce((sum, t) => sum + t.attempts, 0);
-}

package/src/execution/escalation/index.ts

@@ -1,13 +0,0 @@
-/**
- * Escalation module exports
- */
-
-export { escalateTier, getTierConfig, calculateMaxIterations } from "./escalation";
-export {
-  resolveMaxAttemptsOutcome,
-  preIterationTierCheck,
-  handleTierEscalation,
-  type PreIterationCheckResult,
-  type EscalationHandlerContext,
-  type EscalationHandlerResult,
-} from "./tier-escalation";

package/src/execution/escalation/tier-escalation.ts

@@ -1,346 +0,0 @@
-/**
- * Tier Escalation Logic
- *
- * Handles model tier escalation when stories fail:
- * - Pre-iteration tier budget checks
- * - Tier escalation with attempt counter reset
- * - Max attempts outcome resolution (pause vs fail)
- */
-
-import type { NaxConfig } from "../../config";
-import { type LoadedHooksConfig, fireHook } from "../../hooks";
-import { getSafeLogger } from "../../logger";
-import type { PRD, StructuredFailure, UserStory } from "../../prd";
-import { markStoryFailed, savePRD } from "../../prd";
-import { tryLlmBatchRoute } from "../../routing/batch-route";
-import { clearCacheForStory } from "../../routing/strategies/llm";
-import type { FailureCategory } from "../../tdd/types";
-import { calculateMaxIterations, escalateTier, getTierConfig } from "../escalation";
-import { hookCtx } from "../helpers";
-import { appendProgress } from "../progress";
-import { handleMaxAttemptsReached, handleNoTierAvailable } from "./tier-outcome";
-
-/** Build a StructuredFailure for tier escalation. */
-function buildEscalationFailure(
-  story: UserStory,
-  currentTier: string,
-  reviewFindings?: import("../../plugins/types").ReviewFinding[],
-  cost?: number,
-): StructuredFailure {
-  return {
-    attempt: (story.attempts ?? 0) + 1,
-    modelTier: currentTier,
-    stage: "escalation" as const,
-    summary: `Failed with tier ${currentTier}, escalating to next tier`,
-    reviewFindings: reviewFindings && reviewFindings.length > 0 ? reviewFindings : undefined,
-    cost: cost ?? 0,
-    timestamp: new Date().toISOString(),
-  };
-}
-
-/**
- * Determine the outcome when max attempts are reached for an escalation.
- *
- * Returns 'pause' if the failure category requires human review
- * (isolation-violation or verifier-rejected). For all other categories
- * (session-failure, tests-failing, or no category) returns 'fail'.
- *
- * Exported for unit-testing without running the full runner loop.
- */
-export function resolveMaxAttemptsOutcome(failureCategory?: FailureCategory): "pause" | "fail" {
-  if (!failureCategory) {
-    return "fail";
-  }
-
-  switch (failureCategory) {
-    case "isolation-violation":
-    case "verifier-rejected":
-    case "greenfield-no-tests":
-      return "pause";
-    case "runtime-crash":
-      return "pause";
-    case "session-failure":
-    case "tests-failing":
-      return "fail";
-    default:
-      // Exhaustive check: if a new FailureCategory is added, this will error
-      failureCategory satisfies never;
-      return "fail";
-  }
-}
-
-export interface PreIterationCheckResult {
-  shouldSkipIteration: boolean;
-  prdDirty: boolean;
-  prd: PRD;
-}
-
-/**
- * Pre-iteration tier escalation check (BUG-16 + BUG-17 fix)
- *
- * Check if story has exceeded current tier's attempt budget BEFORE spawning agent.
- * If exceeded, escalate to next tier or mark as failed.
- */
-export async function preIterationTierCheck(
-  story: UserStory,
-  routing: { modelTier: string },
-  config: NaxConfig,
-  prd: PRD,
-  prdPath: string,
-  featureDir: string | undefined,
-  hooks: LoadedHooksConfig,
-  feature: string,
-  totalCost: number,
-  workdir: string,
-): Promise<PreIterationCheckResult> {
-  const logger = getSafeLogger();
-  const currentTier = story.routing?.modelTier ?? routing.modelTier;
-  const tierOrder = config.autoMode.escalation?.tierOrder || [];
-  const tierCfg = tierOrder.length > 0 ? getTierConfig(currentTier, tierOrder) : undefined;
-
-  if (!tierCfg || (story.attempts ?? 0) < tierCfg.attempts) {
-    // Story still has budget in current tier
-    return { shouldSkipIteration: false, prdDirty: false, prd };
-  }
-
-  // Exceeded current tier budget — try to escalate
-  const nextTier = escalateTier(currentTier, tierOrder);
-  const routingMode = config.routing.llm?.mode ?? "hybrid";
-
-  if (nextTier && config.autoMode.escalation.enabled) {
-    logger?.warn("escalation", "Story exceeded tier budget, escalating", {
-      storyId: story.id,
-      attempts: story.attempts,
-      tierAttempts: tierCfg.attempts,
-      currentTier,
-      nextTier,
-    });
-
-    // Update story routing in PRD and reset attempts for new tier
-    const updatedPrd = {
-      ...prd,
-      userStories: prd.userStories.map((s) =>
-        s.id === story.id
-          ? {
-              ...s,
-              attempts: 0, // Reset attempts for new tier
-              routing: s.routing ? { ...s.routing, modelTier: nextTier } : { ...routing, modelTier: nextTier },
-            }
-          : s,
-      ) as PRD["userStories"],
-    } as PRD;
-    await savePRD(updatedPrd, prdPath);
-
-    // Clear routing cache for story to avoid returning old cached decision
-    clearCacheForStory(story.id);
-
-    // Hybrid mode: re-route story after escalation
-    if (routingMode === "hybrid") {
-      await tryLlmBatchRoute(config, [story], "hybrid-re-route");
-    }
-
-    // Skip to next iteration (will reload PRD and use new tier)
-    return { shouldSkipIteration: true, prdDirty: true, prd: updatedPrd };
-  }
-
-  // No next tier or escalation disabled — mark story as failed
-  logger?.error("execution", "Story failed - all tiers exhausted", {
-    storyId: story.id,
-    attempts: story.attempts,
-  });
-
-  const failedPrd = { ...prd };
-  markStoryFailed(failedPrd, story.id, undefined, undefined);
-  await savePRD(failedPrd, prdPath);
-
-  if (featureDir) {
-    await appendProgress(featureDir, story.id, "failed", `${story.title} — All tiers exhausted`);
-  }
-
-  await fireHook(
-    hooks,
-    "on-story-fail",
-    hookCtx(feature, {
-      storyId: story.id,
-      status: "failed",
-      reason: `All tiers exhausted (${story.attempts} attempts)`,
-      cost: totalCost,
-    }),
-    workdir,
-  );
-
-  // Skip to next iteration (will pick next story)
-  return { shouldSkipIteration: true, prdDirty: true, prd: failedPrd };
-}
-
-export interface EscalationHandlerContext {
-  story: UserStory;
-  storiesToExecute: UserStory[];
-  isBatchExecution: boolean;
-  routing: { modelTier: string; testStrategy: string };
-  pipelineResult: {
-    reason?: string;
-    context: {
-      retryAsLite?: boolean;
-      tddFailureCategory?: FailureCategory;
-      reviewFindings?: import("../../plugins/types").ReviewFinding[];
-    };
-  };
-  config: NaxConfig;
-  prd: PRD;
-  prdPath: string;
-  featureDir?: string;
-  hooks: LoadedHooksConfig;
-  feature: string;
-  totalCost: number;
-  workdir: string;
-  /** Verify result from the pipeline verify stage — used to detect RUNTIME_CRASH (BUG-070) */
-  verifyResult?: { status: string; success: boolean };
-  /** Cost of the failed attempt being escalated (BUG-067: accumulated across escalations) */
-  attemptCost?: number;
-}
-
-export interface EscalationHandlerResult {
-  outcome: "escalated" | "paused" | "failed" | "retry-same";
-  prdDirty: boolean;
-  prd: PRD;
-}
-
-/**
- * Determine if the pipeline should retry the same tier due to a transient runtime crash.
- *
- * Returns true when the verify result status is RUNTIME_CRASH — these are Bun
- * runtime-level failures, not code quality issues, so escalating the model tier
- * would not help. Instead the same tier should be retried.
- *
- * @param verifyResult - Verify result from the pipeline verify stage
- */
-export function shouldRetrySameTier(verifyResult: { status: string; success: boolean } | undefined): boolean {
-  return verifyResult?.status === "RUNTIME_CRASH";
-}
-
-/**
- * Swappable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
- */
-export const _tierEscalationDeps = {
-  savePRD,
-};
-
-/**
- * Handle tier escalation after pipeline escalation action
- *
- * Escalates to next tier or marks story as paused/failed based on failure category.
- */
-export async function handleTierEscalation(ctx: EscalationHandlerContext): Promise<EscalationHandlerResult> {
-  const logger = getSafeLogger();
-
-  // BUG-070: Runtime crashes are transient — retry same tier, do NOT escalate
-  if (shouldRetrySameTier(ctx.verifyResult)) {
-    logger?.warn("escalation", "Runtime crash detected — retrying same tier (transient, not a code issue)", {
-      storyId: ctx.story.id,
-    });
-    return { outcome: "retry-same", prdDirty: false, prd: ctx.prd };
-  }
-
-  const nextTier = escalateTier(ctx.routing.modelTier, ctx.config.autoMode.escalation.tierOrder);
-  const escalateWholeBatch = ctx.config.autoMode.escalation.escalateEntireBatch ?? true;
-  const storiesToEscalate = ctx.isBatchExecution && escalateWholeBatch ? ctx.storiesToExecute : [ctx.story];
-
-  // Retrieve TDD-specific context flags set by executionStage
-  const escalateRetryAsLite = ctx.pipelineResult.context.retryAsLite === true;
-  const escalateFailureCategory = ctx.pipelineResult.context.tddFailureCategory;
-  const escalateReviewFindings = ctx.pipelineResult.context.reviewFindings;
-  // S5: Auto-switch to test-after on greenfield-no-tests
-  const escalateRetryAsTestAfter = escalateFailureCategory === "greenfield-no-tests";
-  const routingMode = ctx.config.routing.llm?.mode ?? "hybrid";
-
-  if (!nextTier || !ctx.config.autoMode.escalation.enabled) {
-    // No next tier or escalation disabled — pause or fail based on failure category
-    return await handleNoTierAvailable(ctx, escalateFailureCategory);
-  }
-
-  const maxAttempts = calculateMaxIterations(ctx.config.autoMode.escalation.tierOrder);
-  const canEscalate = storiesToEscalate.every((s) => (s.attempts ?? 0) < maxAttempts);
-
-  if (!canEscalate) {
-    // Max attempts reached — pause or fail based on failure category
-    return await handleMaxAttemptsReached(ctx, escalateFailureCategory);
-  }
-
-  // Can escalate — log and update stories
-  for (const s of storiesToEscalate) {
-    const currentTestStrategy = s.routing?.testStrategy ?? ctx.routing.testStrategy;
-    const shouldSwitchToTestAfter = escalateRetryAsTestAfter && currentTestStrategy !== "test-after";
-
-    if (shouldSwitchToTestAfter) {
-      logger?.warn("escalation", "Switching strategy to test-after (greenfield-no-tests fallback)", {
-        storyId: s.id,
-        fromStrategy: currentTestStrategy,
-        toStrategy: "test-after",
-      });
-    } else {
-      logger?.warn("escalation", "Escalating story to next tier", {
-        storyId: s.id,
-        nextTier,
-        retryAsLite: escalateRetryAsLite,
-      });
-    }
-  }
-
-  const pipelineReason = ctx.pipelineResult.reason ? `: ${ctx.pipelineResult.reason}` : "";
-  const errorMessage = `Attempt ${ctx.story.attempts + 1} failed with model tier: ${ctx.routing.modelTier}${ctx.isBatchExecution ? " (in batch)" : ""}${pipelineReason}`;
-
-  const updatedPrd = {
-    ...ctx.prd,
-    userStories: ctx.prd.userStories.map((s) => {
-      const shouldEscalate = storiesToEscalate.some((story) => story.id === s.id);
-      if (!shouldEscalate) return s;
-
-      // S5: Check if this is a one-time test-after switch
-      const currentTestStrategy = s.routing?.testStrategy ?? ctx.routing.testStrategy;
-      const shouldSwitchToTestAfter = escalateRetryAsTestAfter && currentTestStrategy !== "test-after";
-
-      const baseRouting = s.routing ?? { ...ctx.routing };
-      const updatedRouting = {
-        ...baseRouting,
-        modelTier: shouldSwitchToTestAfter ? baseRouting.modelTier : nextTier,
-        ...(escalateRetryAsLite ? { testStrategy: "three-session-tdd-lite" as const } : {}),
-        ...(shouldSwitchToTestAfter ? { testStrategy: "test-after" as const } : {}),
-      };
-
-      // BUG-011: Reset attempt counter on tier escalation
-      const currentStoryTier = s.routing?.modelTier ?? ctx.routing.modelTier;
-      const isChangingTier = currentStoryTier !== nextTier;
-      const shouldResetAttempts = isChangingTier || shouldSwitchToTestAfter;
-
-      // Build escalation failure (BUG-067: include cost for accumulatedAttemptCost in metrics)
-      const escalationFailure = buildEscalationFailure(s, currentStoryTier, escalateReviewFindings, ctx.attemptCost);
-
-      return {
-        ...s,
-        attempts: shouldResetAttempts ? 0 : (s.attempts ?? 0) + 1,
-        routing: updatedRouting,
-        priorErrors: [...(s.priorErrors || []), errorMessage],
-        priorFailures: [...(s.priorFailures || []), escalationFailure],
-      } as UserStory;
-    }) as PRD["userStories"],
-  } as PRD;
-
-  await _tierEscalationDeps.savePRD(updatedPrd, ctx.prdPath);
-
-  // Clear routing cache for all escalated stories to avoid returning old cached decisions
-  for (const story of storiesToEscalate) {
-    clearCacheForStory(story.id);
-  }
-
-  // Hybrid mode: re-route escalated stories
-  if (routingMode === "hybrid") {
-    await tryLlmBatchRoute(ctx.config, storiesToEscalate, "hybrid-re-route-pipeline");
-  }
-
-  return {
-    outcome: "escalated",
-    prdDirty: true,
-    prd: updatedPrd,
-  };
-}