@nathapp/nax 0.18.1

package/src/pipeline/stages/acceptance.ts

@@ -0,0 +1,197 @@
+/**
+ * Acceptance Stage
+ *
+ * Runs acceptance tests when all stories are complete.
+ * Validates the feature against acceptance criteria from spec.md.
+ *
+ * Only executes when:
+ * - All stories in the PRD are complete (status: passed/failed/skipped, not pending/in-progress)
+ * - Acceptance validation is enabled in config
+ *
+ * @returns
+ * - `continue`: All acceptance tests pass
+ * - `fail`: One or more acceptance tests failed
+ *
+ * @example
+ * ```ts
+ * // All stories complete, acceptance tests pass
+ * await acceptanceStage.execute(ctx);
+ * // Returns: { action: "continue" }
+ *
+ * // All stories complete, acceptance tests fail
+ * await acceptanceStage.execute(ctx);
+ * // Returns: { action: "fail", reason: "Acceptance tests failed: AC-2, AC-5" }
+ * ```
+ */
+
+import path from "node:path";
+import { getLogger } from "../../logger";
+import { countStories } from "../../prd";
+import type { PipelineContext, PipelineStage, StageResult } from "../types";
+
+/**
+ * Parse bun test output to extract failed test names.
+ *
+ * Looks for lines containing "AC-N:" to identify which acceptance criteria failed.
+ *
+ * @param output - stdout/stderr from bun test
+ * @returns Array of failed AC IDs (e.g., ["AC-2", "AC-5"])
+ *
+ * @example
+ * ```ts
+ * const output = `
+ *   ✓ AC-1: TTL expiry
+ *   ✗ AC-2: handles empty input
+ *   ✓ AC-3: validates format
+ * `;
+ * const failed = parseTestFailures(output);
+ * // Returns: ["AC-2"]
+ * ```
+ */
+function parseTestFailures(output: string): string[] {
+  const failedACs: string[] = [];
+  const lines = output.split("\n");
+
+  for (const line of lines) {
+    // Look for Bun's (fail) marker followed by AC-N pattern
+    // Pattern: (fail) ... > AC-N: description
+    if (line.includes("(fail)")) {
+      const acMatch = line.match(/(AC-\d+):/i);
+      if (acMatch) {
+        const acId = acMatch[1].toUpperCase();
+        if (!failedACs.includes(acId)) {
+          failedACs.push(acId);
+        }
+      }
+    }
+  }
+
+  return failedACs;
+}
+
+/**
+ * Check if all stories in the PRD are complete.
+ *
+ * Stories are complete if their status is passed, failed, or skipped.
+ * Pending or in-progress stories are not complete.
+ *
+ * @param ctx - Pipeline context
+ * @returns true if all stories complete, false otherwise
+ */
+function areAllStoriesComplete(ctx: PipelineContext): boolean {
+  const counts = countStories(ctx.prd);
+  const totalComplete = counts.passed + counts.failed + counts.skipped;
+  return totalComplete === counts.total;
+}
+
+export const acceptanceStage: PipelineStage = {
+  name: "acceptance",
+
+  enabled(ctx: PipelineContext): boolean {
+    // Only run when:
+    // 1. Acceptance validation is enabled
+    // 2. All stories are complete
+    if (!ctx.config.acceptance.enabled) {
+      return false;
+    }
+
+    if (!areAllStoriesComplete(ctx)) {
+      return false;
+    }
+
+    return true;
+  },
+
+  async execute(ctx: PipelineContext): Promise<StageResult> {
+    const logger = getLogger();
+
+    logger.info("acceptance", "Running acceptance tests");
+
+    // Build path to acceptance test file
+    if (!ctx.featureDir) {
+      logger.warn("acceptance", "No feature directory — skipping acceptance tests");
+      return { action: "continue" };
+    }
+
+    const testPath = path.join(ctx.featureDir, ctx.config.acceptance.testPath);
+
+    // Check if test file exists
+    const testFile = Bun.file(testPath);
+    const exists = await testFile.exists();
+
+    if (!exists) {
+      logger.warn("acceptance", "Acceptance test file not found — skipping", {
+        testPath,
+      });
+      return { action: "continue" };
+    }
+
+    // Run bun test on the acceptance test file
+    const proc = Bun.spawn(["bun", "test", testPath], {
+      cwd: ctx.workdir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+
+    const exitCode = await proc.exited;
+    const stdout = await new Response(proc.stdout).text();
+    const stderr = await new Response(proc.stderr).text();
+
+    // Combine stdout and stderr for parsing
+    const output = `${stdout}\n${stderr}`;
+
+    // Parse test results
+    const failedACs = parseTestFailures(output);
+
+    // Check for overridden ACs (skip those)
+    const overrides = ctx.prd.acceptanceOverrides || {};
+    const actualFailures = failedACs.filter((acId) => !overrides[acId]);
+
+    // If all failed ACs are overridden, treat as success
+    if (actualFailures.length === 0 && exitCode === 0) {
+      logger.info("acceptance", "All acceptance tests passed");
+      return { action: "continue" };
+    }
+
+    if (actualFailures.length === 0 && exitCode !== 0) {
+      // Tests failed but we couldn't parse which ACs
+      // This might be a setup/teardown error
+      logger.warn("acceptance", "Tests failed but no specific AC failures detected", {
+        output,
+      });
+      return { action: "continue" }; // Don't block on unparseable failures
+    }
+
+    // If we have actual failures, report them
+    if (actualFailures.length > 0) {
+      // Log overridden failures (if any)
+      const overriddenFailures = failedACs.filter((acId) => overrides[acId]);
+      if (overriddenFailures.length > 0) {
+        logger.warn("acceptance", "Skipped failures (overridden)", {
+          overriddenFailures,
+          overrides: overriddenFailures.map((acId) => ({ acId, reason: overrides[acId] })),
+        });
+      }
+
+      logger.error("acceptance", "Acceptance tests failed", {
+        failedACs: actualFailures,
+        output,
+      });
+
+      // Store failed ACs and test output in context for fix generation
+      ctx.acceptanceFailures = {
+        failedACs: actualFailures,
+        testOutput: output,
+      };
+
+      return {
+        action: "fail",
+        reason: `Acceptance tests failed: ${actualFailures.join(", ")}`,
+      };
+    }
+
+    // All tests passed
+    logger.info("acceptance", "All acceptance tests passed");
+    return { action: "continue" };
+  },
+};

package/src/pipeline/stages/completion.ts

@@ -0,0 +1,99 @@
+/**
+ * Completion Stage
+ *
+ * Marks stories as passed, logs progress, fires completion hooks.
+ * This is the final stage in the pipeline for successful executions.
+ *
+ * @returns
+ * - `continue`: Stories marked complete, hooks fired
+ *
+ * @example
+ * ```ts
+ * // Single story completion
+ * await completionStage.execute(ctx);
+ * // Logs: "✓ Story US-001 passed"
+ * // Fires: on-story-complete hook
+ *
+ * // Batch completion
+ * await completionStage.execute(ctx);
+ * // Logs: "✓ Story US-001 passed", "✓ Story US-002 passed", ...
+ * // Progress: "📊 Progress: 5/20 stories | ✅ 5 passed | ❌ 0 failed"
+ * ```
+ */
+
+import { hookCtx } from "../../execution/helpers";
+import { appendProgress } from "../../execution/progress";
+import { fireHook } from "../../hooks";
+import { getLogger } from "../../logger";
+import { collectBatchMetrics, collectStoryMetrics } from "../../metrics";
+import { countStories, markStoryPassed, savePRD } from "../../prd";
+import type { PipelineContext, PipelineStage, StageResult } from "../types";
+
+export const completionStage: PipelineStage = {
+  name: "completion",
+  enabled: () => true,
+
+  async execute(ctx: PipelineContext): Promise<StageResult> {
+    const logger = getLogger();
+    const isBatch = ctx.stories.length > 1;
+    const sessionCost = ctx.agentResult?.estimatedCost || 0;
+
+    // Calculate PRD path
+    const prdPath = ctx.featureDir ? `${ctx.featureDir}/prd.json` : `${ctx.workdir}/nax/features/unknown/prd.json`;
+
+    // Collect story metrics
+    const storyStartTime = ctx.storyStartTime || new Date().toISOString();
+    if (isBatch) {
+      ctx.storyMetrics = collectBatchMetrics(ctx, storyStartTime);
+    } else {
+      ctx.storyMetrics = [collectStoryMetrics(ctx, storyStartTime)];
+    }
+
+    // Mark all stories in batch as passed
+    for (const completedStory of ctx.stories) {
+      markStoryPassed(ctx.prd, completedStory.id);
+
+      logger.info("completion", "Story passed", {
+        storyId: completedStory.id,
+        cost: sessionCost / ctx.stories.length,
+      });
+
+      // Log progress
+      if (ctx.featureDir) {
+        const costPerStory = sessionCost / ctx.stories.length;
+        await appendProgress(
+          ctx.featureDir,
+          completedStory.id,
+          "passed",
+          `${completedStory.title} — Cost: $${costPerStory.toFixed(4)}${isBatch ? " (batched)" : ""}`,
+        );
+      }
+
+      // Fire story-complete hook
+      await fireHook(
+        ctx.hooks,
+        "on-story-complete",
+        hookCtx(ctx.prd.feature, {
+          storyId: completedStory.id,
+          status: "passed",
+          cost: sessionCost / ctx.stories.length,
+        }),
+        ctx.workdir,
+      );
+    }
+
+    // Save PRD
+    await savePRD(ctx.prd, prdPath);
+
+    // Display progress
+    const updatedCounts = countStories(ctx.prd);
+    logger.info("completion", "Progress update", {
+      completed: updatedCounts.passed + updatedCounts.failed,
+      total: updatedCounts.total,
+      passed: updatedCounts.passed,
+      failed: updatedCounts.failed,
+    });
+
+    return { action: "continue" };
+  },
+};

package/src/pipeline/stages/constitution.ts

@@ -0,0 +1,63 @@
+/**
+ * Constitution Stage
+ *
+ * Loads the project constitution (if enabled) and stores it in context.
+ * Constitution defines coding standards, architectural rules, and forbidden patterns.
+ *
+ * @returns
+ * - `continue`: Always continues (soft failure if constitution missing)
+ *
+ * @example
+ * ```ts
+ * // Constitution enabled and found
+ * await constitutionStage.execute(ctx);
+ * // ctx.constitution: { content: "...", tokens: 500, truncated: false }
+ *
+ * // Constitution enabled but not found
+ * await constitutionStage.execute(ctx);
+ * // ctx.constitution: undefined (stage logs warning and continues)
+ * ```
+ */
+
+import { dirname } from "node:path";
+import { loadConstitution } from "../../constitution";
+import { getLogger } from "../../logger";
+import type { PipelineContext, PipelineStage, StageResult } from "../types";
+
+export const constitutionStage: PipelineStage = {
+  name: "constitution",
+  enabled: (ctx) => ctx.config.constitution.enabled,
+
+  async execute(ctx: PipelineContext): Promise<StageResult> {
+    const logger = getLogger();
+
+    // Constitution file is in nax/constitution.md
+    // featureDir is nax/features/<name>/, so we need to go up two levels
+    const ngentDir = ctx.featureDir ? dirname(dirname(ctx.featureDir)) : `${ctx.workdir}/nax`;
+
+    const result = await loadConstitution(ngentDir, ctx.config.constitution);
+
+    if (result) {
+      ctx.constitution = result;
+
+      logger.debug("constitution", "Constitution loaded", {
+        tokens: result.tokens,
+        truncated: result.truncated,
+      });
+
+      if (result.truncated) {
+        logger.warn("constitution", "Constitution truncated", {
+          originalTokens: result.originalTokens,
+          tokens: result.tokens,
+          maxTokens: ctx.config.constitution.maxTokens,
+        });
+      }
+    } else {
+      // SOFT FAILURE: Constitution missing or failed to load — continue without it
+      // This is acceptable because constitution is optional project governance
+      logger.debug("constitution", "Constitution not found or failed to load");
+    }
+
+    return { action: "continue" };
+  },
+};

package/src/pipeline/stages/context.ts

@@ -0,0 +1,117 @@
+/**
+ * Context Stage
+ *
+ * Builds contextual information for the agent from the PRD and related stories.
+ * After building core context, calls plugin context providers to inject external data.
+ * Formats as markdown for inclusion in the prompt.
+ *
+ * @returns
+ * - `continue`: Always continues (soft failure if context empty)
+ *
+ * @example
+ * ```ts
+ * // PRD has related stories with context
+ * await contextStage.execute(ctx);
+ * // ctx.contextMarkdown: "## Related Stories\n- US-001: ..."
+ *
+ * // No related context found
+ * await contextStage.execute(ctx);
+ * // ctx.contextMarkdown: "" (empty but continues)
+ * ```
+ */
+
+import type { ContextElement } from "../../context/types";
+import { buildStoryContextFull } from "../../execution/helpers";
+import { getLogger } from "../../logger";
+import type { PipelineContext, PipelineStage, StageResult } from "../types";
+
+export const contextStage: PipelineStage = {
+  name: "context",
+  enabled: () => true,
+
+  async execute(ctx: PipelineContext): Promise<StageResult> {
+    const logger = getLogger();
+
+    // Build context from PRD with element-level tracking
+    const result = await buildStoryContextFull(ctx.prd, ctx.story, ctx.config);
+
+    // SOFT FAILURE: Empty context is acceptable — agent can work without PRD context
+    // This happens when no relevant stories/context is found, which is normal
+    if (result) {
+      ctx.contextMarkdown = result.markdown;
+      ctx.builtContext = result.builtContext;
+    } else {
+      // Initialize contextMarkdown to empty string if no PRD context was built
+      ctx.contextMarkdown = ctx.contextMarkdown || "";
+    }
+
+    // Add plugin context if any providers are registered
+    if (ctx.plugins) {
+      const providers = ctx.plugins.getContextProviders();
+      if (providers.length > 0) {
+        logger.info("context", `Running ${providers.length} plugin context provider(s)`);
+
+        const pluginElements: ContextElement[] = [];
+        let pluginTokensUsed = 0;
+        const tokenBudget = ctx.config.execution.contextProviderTokenBudget;
+
+        for (const provider of providers) {
+          // Check if we have budget remaining
+          if (pluginTokensUsed >= tokenBudget) {
+            logger.info("context", "Plugin context budget exhausted, skipping remaining providers");
+            break;
+          }
+
+          try {
+            logger.info("context", `Fetching context from plugin: ${provider.name}`);
+            const providerResult = await provider.getContext(ctx.story);
+
+            // Check if adding this provider's content would exceed budget
+            if (pluginTokensUsed + providerResult.estimatedTokens > tokenBudget) {
+              logger.info("context", `Skipping plugin ${provider.name}: would exceed budget`);
+              break;
+            }
+
+            // Add plugin context as a new element
+            pluginElements.push({
+              type: "file", // Reuse file type for external context
+              content: `## ${providerResult.label}\n\n${providerResult.content}`,
+              priority: 50, // Medium priority (between dependencies and errors)
+              tokens: providerResult.estimatedTokens,
+            });
+
+            pluginTokensUsed += providerResult.estimatedTokens;
+            logger.info(
+              "context",
+              `Added context from plugin ${provider.name} (${providerResult.estimatedTokens} tokens)`,
+            );
+          } catch (error) {
+            logger.error("context", `Plugin context provider error: ${provider.name}`, {
+              error: error instanceof Error ? error.message : String(error),
+            });
+            // Continue with other providers on error (soft failure)
+          }
+        }
+
+        // Append plugin context to existing markdown
+        if (pluginElements.length > 0) {
+          const pluginMarkdown = pluginElements.map((el) => el.content).join("\n\n");
+          ctx.contextMarkdown = ctx.contextMarkdown ? `${ctx.contextMarkdown}\n\n${pluginMarkdown}` : pluginMarkdown;
+
+          // Update built context with plugin elements
+          if (ctx.builtContext) {
+            ctx.builtContext.elements.push(...pluginElements);
+            ctx.builtContext.totalTokens += pluginTokensUsed;
+          }
+
+          logger.info(
+            "context",
+            `Added ${pluginElements.length} plugin context element(s) (${pluginTokensUsed} tokens total)`,
+          );
+        }
+      }
+    }
+
+    return { action: "continue" };
+  },
+};

package/src/pipeline/stages/execution.ts

@@ -0,0 +1,194 @@
+/**
+ * Execution Stage
+ *
+ * Spawns the agent session(s) to execute the story/stories.
+ * Handles both single-session (test-after) and three-session TDD.
+ *
+ * @returns
+ * - `continue`: Agent session succeeded
+ * - `fail`: Agent not found or prompt missing
+ * - `escalate`: Agent session failed (will retry with higher tier)
+ * - `pause`: Three-session TDD fallback (backward compatible, no failureCategory)
+ *
+ * TDD failure routing by failureCategory:
+ * - `isolation-violation` (strict mode) → escalate + ctx.retryAsLite=true
+ * - `isolation-violation` (lite mode)   → escalate
+ * - `session-failure`                   → escalate
+ * - `tests-failing`                     → escalate
+ * - `verifier-rejected`                 → escalate
+ * - no category / unknown               → pause (backward compatible)
+ *
+ * @example
+ * ```ts
+ * // Single session (test-after)
+ * await executionStage.execute(ctx);
+ * // ctx.agentResult: { success: true, estimatedCost: 0.05, ... }
+ *
+ * // Three-session TDD
+ * await executionStage.execute(ctx);
+ * // ctx.agentResult: { success: true, estimatedCost: 0.15, ... }
+ * ```
+ */
+
+import { getAgent, validateAgentForTier } from "../../agents";
+import { resolveModel } from "../../config";
+import { getLogger } from "../../logger";
+import type { FailureCategory } from "../../tdd";
+import { runThreeSessionTdd } from "../../tdd";
+import type { PipelineContext, PipelineStage, StageResult } from "../types";
+
+/**
+ * Determine the pipeline action for a failed TDD result, based on its failureCategory.
+ *
+ * This is a pure routing function — it mutates only `ctx.retryAsLite` when needed.
+ * Exported for unit testing.
+ *
+ * @param failureCategory  - Category set by the TDD orchestrator (or undefined)
+ * @param isLiteMode       - Whether the story was running in tdd-lite mode
+ * @param ctx              - Pipeline context (mutated: ctx.retryAsLite may be set)
+ * @param reviewReason     - Human-readable reason string from the TDD result
+ */
+export function routeTddFailure(
+  failureCategory: FailureCategory | undefined,
+  isLiteMode: boolean,
+  ctx: Pick<PipelineContext, "retryAsLite">,
+  reviewReason?: string,
+): StageResult {
+  if (failureCategory === "isolation-violation") {
+    // Strict mode: request a lite-mode retry on next attempt
+    if (!isLiteMode) {
+      ctx.retryAsLite = true;
+    }
+    return { action: "escalate" };
+  }
+
+  if (
+    failureCategory === "session-failure" ||
+    failureCategory === "tests-failing" ||
+    failureCategory === "verifier-rejected"
+  ) {
+    return { action: "escalate" };
+  }
+
+  // Default: no category or unknown — backward-compatible pause for human review
+  return {
+    action: "pause",
+    reason: reviewReason || "Three-session TDD requires review",
+  };
+}
+
+export const executionStage: PipelineStage = {
+  name: "execution",
+  enabled: () => true,
+
+  async execute(ctx: PipelineContext): Promise<StageResult> {
+    const logger = getLogger();
+
+    // HARD FAILURE: No agent available — cannot proceed without an agent
+    const agent = getAgent(ctx.config.autoMode.defaultAgent);
+    if (!agent) {
+      return {
+        action: "fail",
+        reason: `Agent "${ctx.config.autoMode.defaultAgent}" not found`,
+      };
+    }
+
+    // Three-session TDD path (respect tdd.enabled config)
+    const isTddStrategy =
+      ctx.routing.testStrategy === "three-session-tdd" || ctx.routing.testStrategy === "three-session-tdd-lite";
+    const isLiteMode = ctx.routing.testStrategy === "three-session-tdd-lite";
+
+    // TYPE-2 fix: TddConfig has no enabled field, removed dead code
+    if (isTddStrategy) {
+      logger.info("execution", `Starting three-session TDD${isLiteMode ? " (lite)" : ""}`, {
+        storyId: ctx.story.id,
+        lite: isLiteMode,
+      });
+
+      const tddResult = await runThreeSessionTdd({
+        agent,
+        story: ctx.story,
+        config: ctx.config,
+        workdir: ctx.workdir,
+        modelTier: ctx.routing.modelTier,
+        contextMarkdown: ctx.contextMarkdown,
+        dryRun: false,
+        lite: isLiteMode,
+      });
+
+      ctx.agentResult = {
+        success: tddResult.success,
+        estimatedCost: tddResult.totalCost,
+        rateLimited: false,
+        output: "",
+        exitCode: tddResult.success ? 0 : 1,
+        durationMs: 0, // TDD result doesn't track total duration
+      };
+
+      if (!tddResult.success) {
+        // Store failure category in context for runner to use at max-attempts decision
+        ctx.tddFailureCategory = tddResult.failureCategory;
+
+        // Log needsHumanReview context when present
+        if (tddResult.needsHumanReview) {
+          logger.warn("execution", "Human review needed", {
+            storyId: ctx.story.id,
+            reason: tddResult.reviewReason,
+            lite: tddResult.lite,
+            failureCategory: tddResult.failureCategory,
+          });
+        }
+
+        return routeTddFailure(tddResult.failureCategory, isLiteMode, ctx, tddResult.reviewReason);
+      }
+
+      return { action: "continue" };
+    }
+
+    // Single/batch session (test-after) path
+    // HARD FAILURE: Missing prompt indicates pipeline misconfiguration
+    if (!ctx.prompt) {
+      return { action: "fail", reason: "Prompt not built (prompt stage skipped?)" };
+    }
+
+    // Validate agent supports the requested tier
+    if (!validateAgentForTier(agent, ctx.routing.modelTier)) {
+      logger.warn("execution", "Agent tier mismatch", {
+        storyId: ctx.story.id,
+        agentName: agent.name,
+        requestedTier: ctx.routing.modelTier,
+        supportedTiers: agent.capabilities.supportedTiers,
+      });
+    }
+
+    const result = await agent.run({
+      prompt: ctx.prompt,
+      workdir: ctx.workdir,
+      modelTier: ctx.routing.modelTier,
+      modelDef: resolveModel(ctx.config.models[ctx.routing.modelTier]),
+      timeoutSeconds: ctx.config.execution.sessionTimeoutSeconds,
+      dangerouslySkipPermissions: ctx.config.execution.dangerouslySkipPermissions,
+    });
+
+    ctx.agentResult = result;
+
+    if (!result.success) {
+      logger.error("execution", "Agent session failed", {
+        exitCode: result.exitCode,
+        stderr: result.stderr || "",
+        rateLimited: result.rateLimited,
+        storyId: ctx.story.id,
+      });
+      if (result.rateLimited) {
+        logger.warn("execution", "Rate limited — will retry", { storyId: ctx.story.id });
+      }
+      return { action: "escalate" };
+    }
+
+    logger.info("execution", "Agent session complete", {
+      storyId: ctx.story.id,
+      cost: result.estimatedCost,
+    });
+    return { action: "continue" };
+  },
+};