@nathapp/nax 0.18.1

package/src/pipeline/stages/index.ts

@@ -0,0 +1,62 @@
+/**
+ * Pipeline Stages
+ *
+ * Composable stages for the execution pipeline.
+ * Each stage performs a specific step in story execution.
+ */
+
+import type { PipelineStage } from "../types";
+import { acceptanceStage } from "./acceptance";
+import { completionStage } from "./completion";
+import { constitutionStage } from "./constitution";
+import { contextStage } from "./context";
+import { executionStage } from "./execution";
+import { optimizerStage } from "./optimizer";
+import { promptStage } from "./prompt";
+import { queueCheckStage } from "./queue-check";
+import { reviewStage } from "./review";
+import { routingStage } from "./routing";
+import { verifyStage } from "./verify";
+
+/**
+ * Default pipeline stages in execution order.
+ *
+ * This is the standard pipeline for executing a story:
+ * 1. Check for queue commands (PAUSE/ABORT/SKIP)
+ * 2. Route (classify complexity → model tier)
+ * 3. Load constitution (project coding standards)
+ * 4. Build context (gather relevant code/docs)
+ * 5. Assemble prompt (story + context + constitution)
+ * 6. Optimize prompt (reduce token usage)
+ * 7. Execute agent session (TDD or test-after)
+ * 8. Verify output (tests pass, build succeeds)
+ * 9. Review (quality checks, linting, etc.)
+ * 10. Mark complete (save PRD, fire hooks, log progress)
+ * 11. Acceptance (run acceptance tests when all stories complete)
+ */
+export const defaultPipeline: PipelineStage[] = [
+  queueCheckStage,
+  routingStage,
+  constitutionStage,
+  contextStage,
+  promptStage,
+  optimizerStage,
+  executionStage,
+  verifyStage,
+  reviewStage,
+  completionStage,
+  acceptanceStage,
+];
+
+// Re-export individual stages for custom pipeline construction
+export { queueCheckStage } from "./queue-check";
+export { routingStage } from "./routing";
+export { constitutionStage } from "./constitution";
+export { contextStage } from "./context";
+export { promptStage } from "./prompt";
+export { optimizerStage } from "./optimizer";
+export { executionStage } from "./execution";
+export { verifyStage } from "./verify";
+export { reviewStage } from "./review";
+export { completionStage } from "./completion";
+export { acceptanceStage } from "./acceptance";

package/src/pipeline/stages/optimizer.ts

@@ -0,0 +1,74 @@
+/**
+ * Optimizer Stage
+ *
+ * Optimizes the assembled prompt to reduce token usage while preserving
+ * semantic meaning. Runs between prompt assembly and agent execution.
+ *
+ * Resolution order for optimizer selection:
+ * 1. Plugin-provided optimizer (if plugins loaded)
+ * 2. Built-in strategy from config (rule-based, noop)
+ * 3. Fallback to NoopOptimizer
+ *
+ * @returns
+ * - `continue`: Optimization complete (or skipped if disabled)
+ *
+ * @example
+ * ```ts
+ * // With rule-based optimizer enabled
+ * await optimizerStage.execute(ctx);
+ * // ctx.prompt: optimized, whitespace stripped, criteria compacted
+ * // Logs: "optimizer: rule-based: 15% savings"
+ *
+ * // With optimizer disabled
+ * await optimizerStage.execute(ctx);
+ * // ctx.prompt: unchanged (passthrough)
+ * // Logs: "optimizer: noop: 0% savings"
+ * ```
+ */
+
+import { getLogger } from "../../logger/index.js";
+import { resolveOptimizer } from "../../optimizer/index.js";
+import type { PipelineContext, PipelineStage, StageResult } from "../types.js";
+
+export const optimizerStage: PipelineStage = {
+  name: "optimizer",
+  enabled: (ctx) => {
+    // Always enabled - NoopOptimizer is used when optimization is disabled
+    return true;
+  },
+
+  async execute(ctx: PipelineContext): Promise<StageResult> {
+    const logger = getLogger();
+
+    // Ensure prompt exists
+    if (!ctx.prompt) {
+      logger.warn("optimizer", "No prompt to optimize, skipping");
+      return { action: "continue" };
+    }
+
+    // Resolve optimizer (checks plugins first, then config)
+    const optimizer = resolveOptimizer(ctx.config, ctx.plugins);
+
+    // Optimize the prompt
+    const result = await optimizer.optimize({
+      prompt: ctx.prompt,
+      stories: ctx.stories,
+      contextMarkdown: ctx.contextMarkdown,
+      config: ctx.config,
+    });
+
+    // Update context with optimized prompt
+    ctx.prompt = result.prompt;
+
+    // Log optimization results
+    const savingsPercent = Math.round(result.savings * 100);
+    logger.info("optimizer", `${optimizer.name}: ${savingsPercent}% savings`, {
+      originalTokens: result.originalTokens,
+      optimizedTokens: result.optimizedTokens,
+      tokensSaved: result.originalTokens - result.optimizedTokens,
+      appliedRules: result.appliedRules,
+    });
+
+    return { action: "continue" };
+  },
+};

package/src/pipeline/stages/prompt.ts

@@ -0,0 +1,57 @@
+/**
+ * Prompt Stage
+ *
+ * Assembles the final prompt for the agent from:
+ * - Story/stories (batch or single)
+ * - Context markdown
+ * - Constitution content
+ *
+ * @returns
+ * - `continue`: Prompt built successfully
+ *
+ * @example
+ * ```ts
+ * // Single story with constitution
+ * await promptStage.execute(ctx);
+ * // ctx.prompt: "# CONSTITUTION\n...\n\n# Task: Add login button\n..."
+ *
+ * // Batch of stories without constitution
+ * await promptStage.execute(ctx);
+ * // ctx.prompt: "# Batch Task: 3 Stories\n## Story 1: US-001...\n"
+ * ```
+ */
+
+import { buildBatchPrompt, buildSingleSessionPrompt } from "../../execution/prompts";
+import { getLogger } from "../../logger";
+import type { PipelineContext, PipelineStage, StageResult } from "../types";
+
+export const promptStage: PipelineStage = {
+  name: "prompt",
+  enabled: (ctx) =>
+    ctx.routing.testStrategy !== "three-session-tdd" && ctx.routing.testStrategy !== "three-session-tdd-lite",
+
+  async execute(ctx: PipelineContext): Promise<StageResult> {
+    const logger = getLogger();
+    const isBatch = ctx.stories.length > 1;
+
+    const prompt = isBatch
+      ? buildBatchPrompt(ctx.stories, ctx.contextMarkdown, ctx.constitution)
+      : buildSingleSessionPrompt(ctx.story, ctx.contextMarkdown, ctx.constitution);
+
+    ctx.prompt = prompt;
+
+    if (isBatch) {
+      logger.info("prompt", "Batch session prepared", {
+        storyCount: ctx.stories.length,
+        testStrategy: "test-after",
+      });
+    } else {
+      logger.info("prompt", "Single session prepared", {
+        storyId: ctx.story.id,
+        testStrategy: "test-after",
+      });
+    }
+
+    return { action: "continue" };
+  },
+};

package/src/pipeline/stages/queue-check.ts

@@ -0,0 +1,103 @@
+/**
+ * Queue Check Stage
+ *
+ * Checks for queue commands (PAUSE/ABORT/SKIP) before executing a story.
+ * Processes commands atomically and updates PRD accordingly.
+ */
+
+import { clearQueueFile, readQueueFile } from "../../execution/queue-handler";
+import { getLogger } from "../../logger";
+import { markStorySkipped, savePRD } from "../../prd";
+import type { PipelineContext, PipelineStage, StageResult } from "../types";
+
+/**
+ * Queue Check Stage
+ *
+ * Checks for queue commands (PAUSE/ABORT/SKIP) before executing a story.
+ * If a command is found, processes it and returns appropriate action.
+ *
+ * @returns
+ * - `continue`: No queue commands, proceed
+ * - `pause`: PAUSE/ABORT command found, stop execution
+ * - `skip`: SKIP command removed all stories from batch
+ *
+ * @example
+ * ```ts
+ * // User writes: echo "PAUSE" > .queue.txt
+ * const result = await queueCheckStage.execute(ctx);
+ * // result: { action: "pause", reason: "User requested pause via .queue.txt" }
+ * ```
+ */
+export const queueCheckStage: PipelineStage = {
+  name: "queue-check",
+  enabled: () => true,
+
+  async execute(ctx: PipelineContext): Promise<StageResult> {
+    const logger = getLogger();
+    const queueCommands = await readQueueFile(ctx.workdir);
+
+    if (queueCommands.length === 0) {
+      return { action: "continue" };
+    }
+
+    for (const cmd of queueCommands) {
+      if (cmd.type === "PAUSE") {
+        logger.warn("queue", "Paused by user", { command: "PAUSE" });
+        await clearQueueFile(ctx.workdir);
+        return { action: "pause", reason: "User requested pause via .queue.txt" };
+      }
+
+      if (cmd.type === "ABORT") {
+        logger.warn("queue", "Aborting: marking remaining stories as skipped");
+
+        // Mark all pending stories as skipped
+        for (const s of ctx.prd.userStories) {
+          if (s.status === "pending") {
+            markStorySkipped(ctx.prd, s.id);
+          }
+        }
+
+        // Save PRD path from featureDir
+        const prdPath = ctx.featureDir ? `${ctx.featureDir}/prd.json` : `${ctx.workdir}/nax/features/unknown/prd.json`;
+        await savePRD(ctx.prd, prdPath);
+        await clearQueueFile(ctx.workdir);
+
+        return { action: "pause", reason: "User requested abort" };
+      }
+
+      if (cmd.type === "SKIP") {
+        // Check if this SKIP applies to any story in the current batch
+        const isTargeted = ctx.stories.some((s) => s.id === cmd.storyId);
+
+        if (isTargeted) {
+          logger.warn("queue", "Skipping story by user request", {
+            storyId: cmd.storyId,
+          });
+
+          // Mark as skipped in PRD
+          markStorySkipped(ctx.prd, cmd.storyId);
+
+          // Save PRD
+          const prdPath = ctx.featureDir
+            ? `${ctx.featureDir}/prd.json`
+            : `${ctx.workdir}/nax/features/unknown/prd.json`;
+          await savePRD(ctx.prd, prdPath);
+
+          // Remove from batch
+          ctx.stories = ctx.stories.filter((s) => s.id !== cmd.storyId);
+
+          // If batch is now empty, skip this iteration
+          if (ctx.stories.length === 0) {
+            await clearQueueFile(ctx.workdir);
+            return { action: "skip", reason: "All stories in batch were skipped" };
+          }
+        }
+      }
+    }
+
+    // Clear processed commands
+    await clearQueueFile(ctx.workdir);
+
+    return { action: "continue" };
+  },
+};

package/src/pipeline/stages/review.ts

@@ -0,0 +1,181 @@
+/**
+ * Review Stage
+ *
+ * Runs post-implementation review phase if enabled.
+ * Checks code quality, tests, linting, etc. via review module.
+ * After built-in checks, runs plugin reviewers if any are registered.
+ *
+ * @returns
+ * - `continue`: Review passed
+ * - `fail`: Review failed (hard failure)
+ *
+ * @example
+ * ```ts
+ * // Review enabled and passes
+ * await reviewStage.execute(ctx);
+ * // ctx.reviewResult: { success: true, totalDurationMs: 1500, ... }
+ *
+ * // Review enabled but fails
+ * await reviewStage.execute(ctx);
+ * // Returns: { action: "fail", reason: "Review failed: typecheck errors" }
+ * ```
+ */
+
+import { spawn } from "bun";
+import { getLogger } from "../../logger";
+import { runReview } from "../../review";
+import type { PipelineContext, PipelineStage, StageResult } from "../types";
+
+/**
+ * Get list of changed files from git.
+ * Includes both staged and unstaged changes.
+ *
+ * @param workdir - Working directory
+ * @returns Array of changed file paths
+ */
+async function getChangedFiles(workdir: string): Promise<string[]> {
+  try {
+    // Get both staged and unstaged changes
+    const [stagedProc, unstagedProc] = [
+      spawn({
+        cmd: ["git", "diff", "--name-only", "--cached"],
+        cwd: workdir,
+        stdout: "pipe",
+        stderr: "pipe",
+      }),
+      spawn({
+        cmd: ["git", "diff", "--name-only"],
+        cwd: workdir,
+        stdout: "pipe",
+        stderr: "pipe",
+      }),
+    ];
+
+    await Promise.all([stagedProc.exited, unstagedProc.exited]);
+
+    const stagedFiles = (await new Response(stagedProc.stdout).text())
+      .trim()
+      .split("\n")
+      .filter((line) => line.length > 0);
+
+    const unstagedFiles = (await new Response(unstagedProc.stdout).text())
+      .trim()
+      .split("\n")
+      .filter((line) => line.length > 0);
+
+    // Combine and deduplicate
+    return Array.from(new Set([...stagedFiles, ...unstagedFiles]));
+  } catch {
+    return [];
+  }
+}
+
+export const reviewStage: PipelineStage = {
+  name: "review",
+  enabled: (ctx) => ctx.config.review.enabled,
+
+  async execute(ctx: PipelineContext): Promise<StageResult> {
+    const logger = getLogger();
+
+    logger.info("review", "Running review phase");
+
+    // Run built-in checks (typecheck, lint, test)
+    const reviewResult = await runReview(ctx.config.review, ctx.workdir, ctx.config.execution);
+    ctx.reviewResult = reviewResult;
+
+    // HARD FAILURE: Review failure means code quality gate not met
+    if (!reviewResult.success) {
+      logger.error("review", "Review failed (built-in checks)", {
+        reason: reviewResult.failureReason,
+        storyId: ctx.story.id,
+      });
+      return { action: "fail", reason: `Review failed: ${reviewResult.failureReason}` };
+    }
+
+    // Run plugin reviewers if any are registered
+    if (ctx.plugins) {
+      const pluginReviewers = ctx.plugins.getReviewers();
+      if (pluginReviewers.length > 0) {
+        logger.info("review", `Running ${pluginReviewers.length} plugin reviewer(s)`);
+
+        const changedFiles = await getChangedFiles(ctx.workdir);
+        const pluginReviewerResults: Array<{
+          name: string;
+          passed: boolean;
+          output: string;
+          exitCode?: number;
+          error?: string;
+        }> = [];
+
+        for (const reviewer of pluginReviewers) {
+          logger.info("review", `Running plugin reviewer: ${reviewer.name}`);
+          try {
+            const result = await reviewer.check(ctx.workdir, changedFiles);
+
+            // Capture result for debugging
+            pluginReviewerResults.push({
+              name: reviewer.name,
+              passed: result.passed,
+              output: result.output,
+              exitCode: result.exitCode,
+            });
+
+            if (!result.passed) {
+              logger.error("review", `Plugin reviewer failed: ${reviewer.name}`, {
+                output: result.output,
+                storyId: ctx.story.id,
+              });
+
+              // Store results in review result before failing
+              if (ctx.reviewResult) {
+                ctx.reviewResult.pluginReviewers = pluginReviewerResults;
+              }
+
+              return {
+                action: "fail",
+                reason: `Review failed: plugin reviewer '${reviewer.name}' failed`,
+              };
+            }
+
+            logger.info("review", `Plugin reviewer passed: ${reviewer.name}`);
+          } catch (error) {
+            const errorMsg = error instanceof Error ? error.message : String(error);
+            logger.error("review", `Plugin reviewer error: ${reviewer.name}`, {
+              error: errorMsg,
+              storyId: ctx.story.id,
+            });
+
+            // Capture error for debugging
+            pluginReviewerResults.push({
+              name: reviewer.name,
+              passed: false,
+              output: "",
+              error: errorMsg,
+            });
+
+            // Store results in review result before failing
+            if (ctx.reviewResult) {
+              ctx.reviewResult.pluginReviewers = pluginReviewerResults;
+            }
+
+            return {
+              action: "fail",
+              reason: `Review failed: plugin reviewer '${reviewer.name}' threw error`,
+            };
+          }
+        }
+
+        // Store successful plugin reviewer results
+        if (ctx.reviewResult) {
+          ctx.reviewResult.pluginReviewers = pluginReviewerResults;
+        }
+      }
+    }
+
+    logger.info("review", "Review passed", {
+      durationMs: reviewResult.totalDurationMs,
+      storyId: ctx.story.id,
+    });
+    return { action: "continue" };
+  },
+};

package/src/pipeline/stages/routing.ts

@@ -0,0 +1,81 @@
+/**
+ * Routing Stage
+ *
+ * Classifies story complexity and determines model tier + test strategy.
+ * Uses cached complexity/testStrategy from story if available, but ALWAYS
+ * derives modelTier from current config (never cached).
+ *
+ * @returns
+ * - `continue`: Routing determined, proceed to next stage
+ *
+ * @example
+ * ```ts
+ * // Story has cached routing with complexity
+ * await routingStage.execute(ctx);
+ * // ctx.routing: { complexity: "simple", modelTier: "fast", testStrategy: "test-after", reasoning: "..." }
+ * // modelTier is derived from current config.autoMode.complexityRouting
+ * ```
+ */
+
+import { isGreenfieldStory } from "../../context/greenfield";
+import { getLogger } from "../../logger";
+import { complexityToModelTier, routeStory } from "../../routing";
+import { clearCache, routeBatch } from "../../routing/strategies/llm";
+import type { PipelineContext, PipelineStage, RoutingResult, StageResult } from "../types";
+
+export const routingStage: PipelineStage = {
+  name: "routing",
+  enabled: () => true,
+
+  async execute(ctx: PipelineContext): Promise<StageResult> {
+    const logger = getLogger();
+
+    // If story has cached routing, use it but re-derive modelTier from current config
+    // Otherwise, perform fresh classification
+    let routing: { complexity: string; testStrategy: string; modelTier: string; reasoning?: string };
+    if (ctx.story.routing) {
+      // Use cached complexity/testStrategy, but re-derive modelTier from current config
+      routing = await routeStory(ctx.story, { config: ctx.config }, ctx.workdir, ctx.plugins);
+      // Override with cached complexity if available
+      routing.complexity = ctx.story.routing.complexity;
+      routing.testStrategy = ctx.story.routing.testStrategy;
+      // Re-derive modelTier from cached complexity and current config
+      routing.modelTier = complexityToModelTier(routing.complexity as import("../../config").Complexity, ctx.config);
+    } else {
+      // Fresh classification
+      routing = await routeStory(ctx.story, { config: ctx.config }, ctx.workdir, ctx.plugins);
+    }
+
+    // BUG-010: Greenfield detection — force test-after if no test files exist
+    const greenfieldDetectionEnabled = ctx.config.tdd.greenfieldDetection ?? true;
+    if (greenfieldDetectionEnabled && routing.testStrategy.startsWith("three-session-tdd")) {
+      const isGreenfield = await isGreenfieldStory(ctx.story, ctx.workdir);
+      if (isGreenfield) {
+        logger.info("routing", "Greenfield detected — forcing test-after strategy", {
+          storyId: ctx.story.id,
+          originalStrategy: routing.testStrategy,
+        });
+        routing.testStrategy = "test-after";
+        routing.reasoning = `${routing.reasoning} [GREENFIELD OVERRIDE: No test files exist, using test-after instead of TDD]`;
+      }
+    }
+
+    // Set ctx.routing after all overrides are applied
+    ctx.routing = routing as RoutingResult;
+
+    const isBatch = ctx.stories.length > 1;
+
+    logger.debug("routing", "Task classified", {
+      complexity: ctx.routing.complexity,
+      modelTier: ctx.routing.modelTier,
+      testStrategy: ctx.routing.testStrategy,
+      storyId: ctx.story.id,
+    });
+
+    if (!isBatch) {
+      logger.debug("routing", ctx.routing.reasoning);
+    }
+
+    return { action: "continue" };
+  },
+};

package/src/pipeline/stages/verify.ts

@@ -0,0 +1,100 @@
+/**
+ * Verify Stage
+ *
+ * Verifies the agent's work meets basic requirements by running tests.
+ * This is a lightweight verification before the full review stage.
+ *
+ * @returns
+ * - `continue`: Tests passed
+ * - `escalate`: Tests failed (retry with escalation)
+ *
+ * @example
+ * ```ts
+ * // Tests pass
+ * await verifyStage.execute(ctx);
+ * // Logs: "✓ Tests passed"
+ *
+ * // Tests fail
+ * await verifyStage.execute(ctx);
+ * // Returns: { action: "escalate", reason: "Tests failed (exit code 1)" }
+ * ```
+ */
+
+import { getLogger } from "../../logger";
+import { regression } from "../../verification/gate";
+import type { PipelineContext, PipelineStage, StageResult } from "../types";
+
+export const verifyStage: PipelineStage = {
+  name: "verify",
+  enabled: () => true,
+
+  async execute(ctx: PipelineContext): Promise<StageResult> {
+    const logger = getLogger();
+
+    // Skip verification if tests are not required
+    if (!ctx.config.quality.requireTests) {
+      logger.debug("verify", "Skipping verification (quality.requireTests = false)", { storyId: ctx.story.id });
+      return { action: "continue" };
+    }
+
+    // Skip verification if no test command is configured
+    const testCommand = ctx.config.review?.commands?.test ?? ctx.config.quality.commands.test;
+    if (!testCommand) {
+      logger.debug("verify", "Skipping verification (no test command configured)", { storyId: ctx.story.id });
+      return { action: "continue" };
+    }
+
+    logger.info("verify", "Running verification", { storyId: ctx.story.id });
+
+    // Use unified regression gate (includes 2s wait for agent process cleanup)
+    const result = await regression({
+      workdir: ctx.workdir,
+      command: testCommand,
+      timeoutSeconds: ctx.config.execution.verificationTimeoutSeconds,
+    });
+
+    // HARD FAILURE: Tests must pass for story to be marked complete
+    if (!result.success) {
+      // BUG-019: Distinguish timeout from actual test failures
+      if (result.status === "TIMEOUT") {
+        const timeout = ctx.config.execution.verificationTimeoutSeconds;
+        logger.error(
+          "verify",
+          `Test suite exceeded timeout (${timeout}s). This is NOT a test failure — consider increasing execution.verificationTimeoutSeconds or scoping tests.`,
+          {
+            exitCode: result.status,
+            storyId: ctx.story.id,
+            timeoutSeconds: timeout,
+          },
+        );
+      } else {
+        logger.error("verify", "Tests failed", {
+          exitCode: result.status,
+          storyId: ctx.story.id,
+        });
+      }
+
+      // Log first few lines of output for context (skip for TIMEOUT — output is misleading)
+      if (result.output && result.status !== "TIMEOUT") {
+        const outputLines = result.output.split("\n").slice(0, 10);
+        if (outputLines.length > 0) {
+          logger.debug("verify", "Test output preview", {
+            storyId: ctx.story.id,
+            output: outputLines.join("\n"),
+          });
+        }
+      }
+
+      return {
+        action: "escalate",
+        reason:
+          result.status === "TIMEOUT"
+            ? `Test suite TIMEOUT after ${ctx.config.execution.verificationTimeoutSeconds}s (not a code failure)`
+            : `Tests failed (exit code ${result.status ?? "non-zero"})`,
+      };
+    }
+
+    logger.info("verify", "Tests passed", { storyId: ctx.story.id });
+    return { action: "continue" };
+  },
+};