@nathapp/nax 0.50.3 → 0.51.0

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

@@ -1,143 +0,0 @@
-/**
- * Tier Escalation Outcome Handlers
- *
- * Extracted from tier-escalation.ts: handles outcomes when escalation
- * is not possible (no tier available or max attempts reached).
- *
- * Phase 3 (ADR-005): Replaced direct fireHook() calls with event bus emissions.
- */
-
-import { getSafeLogger } from "../../logger";
-import { pipelineEventBus } from "../../pipeline/event-bus";
-import { markStoryFailed, markStoryPaused, savePRD } from "../../prd";
-import type { FailureCategory } from "../../tdd/types";
-import { appendProgress } from "../progress";
-import type { EscalationHandlerContext, EscalationHandlerResult } from "./tier-escalation";
-import { resolveMaxAttemptsOutcome } from "./tier-escalation";
-
-/**
- * Handle case when no tier is available for escalation
- */
-export async function handleNoTierAvailable(
-  ctx: EscalationHandlerContext,
-  failureCategory?: FailureCategory,
-): Promise<EscalationHandlerResult> {
-  const logger = getSafeLogger();
-  const outcome = resolveMaxAttemptsOutcome(failureCategory);
-
-  if (outcome === "pause") {
-    const pausedPrd = { ...ctx.prd };
-    markStoryPaused(pausedPrd, ctx.story.id);
-    await savePRD(pausedPrd, ctx.prdPath);
-
-    logger?.warn("execution", "Story paused - no tier available (needs human review)", {
-      storyId: ctx.story.id,
-      failureCategory,
-    });
-
-    if (ctx.featureDir) {
-      await appendProgress(
-        ctx.featureDir,
-        ctx.story.id,
-        "paused",
-        `${ctx.story.title} — Execution stopped (needs human review)`,
-      );
-    }
-
-    pipelineEventBus.emit({
-      type: "story:paused",
-      storyId: ctx.story.id,
-      reason: `Execution stopped (${failureCategory ?? "unknown"} requires human review)`,
-      cost: ctx.totalCost,
-    });
-
-    return { outcome: "paused", prdDirty: true, prd: pausedPrd };
-  }
-
-  // Outcome is "fail"
-  const failedPrd = { ...ctx.prd };
-  markStoryFailed(failedPrd, ctx.story.id, failureCategory, undefined);
-  await savePRD(failedPrd, ctx.prdPath);
-
-  logger?.error("execution", "Story failed - execution failed", {
-    storyId: ctx.story.id,
-  });
-
-  if (ctx.featureDir) {
-    await appendProgress(ctx.featureDir, ctx.story.id, "failed", `${ctx.story.title} — Execution failed`);
-  }
-
-  pipelineEventBus.emit({
-    type: "story:failed",
-    storyId: ctx.story.id,
-    story: ctx.story,
-    reason: "Execution failed",
-    countsTowardEscalation: true,
-  });
-
-  return { outcome: "failed", prdDirty: true, prd: failedPrd };
-}
-
-/**
- * Handle case when max attempts are reached
- */
-export async function handleMaxAttemptsReached(
-  ctx: EscalationHandlerContext,
-  failureCategory?: FailureCategory,
-): Promise<EscalationHandlerResult> {
-  const logger = getSafeLogger();
-  const outcome = resolveMaxAttemptsOutcome(failureCategory);
-
-  if (outcome === "pause") {
-    const pausedPrd = { ...ctx.prd };
-    markStoryPaused(pausedPrd, ctx.story.id);
-    await savePRD(pausedPrd, ctx.prdPath);
-
-    logger?.warn("execution", "Story paused - max attempts reached (needs human review)", {
-      storyId: ctx.story.id,
-      failureCategory,
-    });
-
-    if (ctx.featureDir) {
-      await appendProgress(
-        ctx.featureDir,
-        ctx.story.id,
-        "paused",
-        `${ctx.story.title} — Max attempts reached (needs human review)`,
-      );
-    }
-
-    pipelineEventBus.emit({
-      type: "story:paused",
-      storyId: ctx.story.id,
-      reason: `Max attempts reached (${failureCategory ?? "unknown"} requires human review)`,
-      cost: ctx.totalCost,
-    });
-
-    return { outcome: "paused", prdDirty: true, prd: pausedPrd };
-  }
-
-  // Outcome is "fail"
-  const failedPrd = { ...ctx.prd };
-  markStoryFailed(failedPrd, ctx.story.id, failureCategory, undefined);
-  await savePRD(failedPrd, ctx.prdPath);
-
-  logger?.error("execution", "Story failed - max attempts reached", {
-    storyId: ctx.story.id,
-    failureCategory,
-  });
-
-  if (ctx.featureDir) {
-    await appendProgress(ctx.featureDir, ctx.story.id, "failed", `${ctx.story.title} — Max attempts reached`);
-  }
-
-  pipelineEventBus.emit({
-    type: "story:failed",
-    storyId: ctx.story.id,
-    story: ctx.story,
-    reason: "Max attempts reached",
-    countsTowardEscalation: true,
-  });
-
-  return { outcome: "failed", prdDirty: true, prd: failedPrd };
-}

package/src/execution/executor-types.ts

@@ -1,73 +0,0 @@
-/**
- * Sequential Executor Types (ADR-005, Phase 4)
- *
- * Extracted from sequential-executor.ts to slim it below 200 lines.
- */
-
-import type { NaxConfig } from "../config";
-import type { LoadedHooksConfig } from "../hooks";
-import type { InteractionChain } from "../interaction/chain";
-import type { StoryMetrics } from "../metrics";
-import type { PipelineEventEmitter } from "../pipeline/events";
-import type { RoutingResult } from "../pipeline/types";
-import type { AgentGetFn } from "../pipeline/types";
-import type { PluginRegistry } from "../plugins";
-import type { PRD, UserStory } from "../prd/types";
-import type { StoryBatch } from "./batching";
-import type { DeferredReviewResult } from "./deferred-review";
-import type { PidRegistry } from "./pid-registry";
-import type { StatusWriter } from "./status-writer";
-
-export interface SequentialExecutionContext {
-  prdPath: string;
-  workdir: string;
-  config: NaxConfig;
-  hooks: LoadedHooksConfig;
-  feature: string;
-  featureDir?: string;
-  dryRun: boolean;
-  useBatch: boolean;
-  pluginRegistry: PluginRegistry;
-  eventEmitter?: PipelineEventEmitter;
-  statusWriter: StatusWriter;
-  logFilePath?: string;
-  runId: string;
-  startTime: number;
-  batchPlan: StoryBatch[];
-  interactionChain?: InteractionChain | null;
-  /** Protocol-aware agent resolver (ACP wiring). Falls back to standalone getAgent when absent. */
-  agentGetFn?: AgentGetFn;
-  /** PID registry for crash recovery — register child PIDs so they can be killed on SIGTERM. */
-  pidRegistry?: PidRegistry;
-}
-
-export interface SequentialExecutionResult {
-  prd: PRD;
-  iterations: number;
-  storiesCompleted: number;
-  totalCost: number;
-  allStoryMetrics: StoryMetrics[];
-  exitReason: "completed" | "cost-limit" | "max-iterations" | "stalled" | "no-stories" | "pre-merge-aborted";
-  deferredReview?: DeferredReviewResult;
-}
-
-/**
- * Build a preview routing from cached story.routing or config defaults.
- * The pipeline routing stage performs full classification and overwrites ctx.routing.
- * This preview is used only for logging, status display, and event emission.
- */
-export function buildPreviewRouting(story: UserStory, config: NaxConfig): RoutingResult {
-  const cached = story.routing;
-  const defaultComplexity = "medium" as const;
-  const defaultTier = "balanced" as const;
-  const defaultStrategy = "test-after" as const;
-  return {
-    complexity: (cached?.complexity as RoutingResult["complexity"]) ?? defaultComplexity,
-    modelTier:
-      (cached?.modelTier as RoutingResult["modelTier"]) ??
-      (config.autoMode.complexityRouting?.[defaultComplexity] as RoutingResult["modelTier"]) ??
-      defaultTier,
-    testStrategy: (cached?.testStrategy as RoutingResult["testStrategy"]) ?? defaultStrategy,
-    reasoning: cached ? "cached from story.routing" : "preview (pending pipeline routing stage)",
-  };
-}

package/src/execution/helpers.ts

@@ -1,38 +0,0 @@
-/**
- * Execution Helper Functions
- *
- * Re-export barrel for backward compatibility.
- * Story context: ./story-context
- * Lock management: ./lock
- */
-
-/**
- * Error Handling Pattern for Ngent
- *
- * 1. Critical Errors (invalid config, missing required files, security violations):
- *    - Action: throw Error with descriptive message
- *
- * 2. Expected Conditions (no more stories, queue empty, optional feature unavailable):
- *    - Action: return null or undefined
- *
- * 3. Validation Issues (multiple collected errors, partial data problems):
- *    - Action: collect errors in array and return as { errors: string[] }
- *
- * 4. Non-Fatal Warnings (context build failures, optional file missing, rate limit):
- *    - Action: console.warn() + continue execution
- */
-
-// Story context building
-export {
-  type ExecutionResult,
-  hookCtx,
-  maybeGetContext,
-  buildStoryContext,
-  buildStoryContextFull,
-  getAllReadyStories,
-  type StoryCounts,
-  formatProgress,
-} from "./story-context";
-
-// Lock management
-export { acquireLock, releaseLock } from "./lock";

package/src/execution/index.ts

@@ -1,27 +0,0 @@
-export type { RunOptions, RunResult } from "./runner";
-export { run } from "./runner";
-export type { FailureCategory } from "../tdd/types";
-export { appendProgress } from "./progress";
-export { groupStoriesIntoBatches, type StoryBatch } from "./batching";
-export { escalateTier, getTierConfig, calculateMaxIterations } from "./escalation";
-export { readQueueFile, clearQueueFile } from "./queue-handler";
-export {
-  hookCtx,
-  maybeGetContext,
-  buildStoryContext,
-  getAllReadyStories,
-  acquireLock,
-  releaseLock,
-  formatProgress,
-  type ExecutionResult,
-  type StoryCounts,
-} from "./helpers";
-export {
-  installCrashHandlers,
-  startHeartbeat,
-  stopHeartbeat,
-  writeExitSummary,
-  resetCrashHandlers,
-  type CrashRecoveryContext,
-} from "./crash-recovery";
-export { PidRegistry } from "./pid-registry";

package/src/execution/iteration-runner.ts

@@ -1,160 +0,0 @@
-/**
- * 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 { join } from "node:path";
-import { loadConfigForWorkdir } from "../config/loader";
-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;
-  /** Set when finalAction === "decomposed" — number of sub-stories created */
-  subStoryCount?: number;
-}
-
-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 storyStartTime = Date.now();
-  const storyGitRef = await captureGitRef(ctx.workdir);
-
-  // BUG-067: Accumulate cost from all prior failed attempts (stored in priorFailures by handleTierEscalation)
-  const accumulatedAttemptCost = (story.priorFailures || []).reduce((sum, f) => sum + (f.cost || 0), 0);
-
-  // PKG-003: Resolve per-package effective config once per story (not per-stage)
-  const effectiveConfig = story.workdir
-    ? await _iterationRunnerDeps.loadConfigForWorkdir(join(ctx.workdir, "nax", "config.json"), story.workdir)
-    : ctx.config;
-
-  const pipelineContext: PipelineContext = {
-    config: ctx.config,
-    effectiveConfig,
-    prd,
-    story,
-    stories: storiesToExecute,
-    routing,
-    workdir: ctx.workdir,
-    prdPath: ctx.prdPath,
-    featureDir: ctx.featureDir,
-    hooks: ctx.hooks,
-    plugins: ctx.pluginRegistry,
-    storyStartTime: new Date().toISOString(),
-    storyGitRef: storyGitRef ?? undefined,
-    interaction: ctx.interactionChain ?? undefined,
-    agentGetFn: ctx.agentGetFn,
-    pidRegistry: ctx.pidRegistry,
-    accumulatedAttemptCost: accumulatedAttemptCost > 0 ? accumulatedAttemptCost : 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,
-    storyStartTime,
-  };
-
-  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: r.costDelta,
-    prdDirty: r.prdDirty,
-    finalAction: pipelineResult.finalAction,
-    reason: pipelineResult.reason,
-    subStoryCount: pipelineResult.subStoryCount,
-  };
-}
-
-/**
- * Swappable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
- */
-export const _iterationRunnerDeps = {
-  loadConfigForWorkdir,
-};