@nathapp/nax 0.50.2 → 0.51.0

package/src/pipeline/stages/index.ts

@@ -1,86 +0,0 @@
-/**
- * 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 { acceptanceSetupStage } from "./acceptance-setup";
-import { autofixStage } from "./autofix";
-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 { rectifyStage } from "./rectify";
-import { regressionStage } from "./regression";
-import { reviewStage } from "./review";
-import { routingStage } from "./routing";
-import { verifyStage } from "./verify";
-
-/**
- * Default pipeline stages in execution order.
- *
- * New stage order (ADR-005 Phase 2):
- * 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 — scoped via smart-runner)
- * 9.  Rectify (fix test failures before escalating)
- * 10. Review (quality checks: lint, typecheck, format)
- * 11. Autofix (auto-fix lint/format before escalating)
- * 12. Regression (full-suite gate, inline mode only)
- * 13. Mark complete (save PRD, fire hooks, log progress)
- * 14. Acceptance (run AC tests when all stories complete)
- */
-export const defaultPipeline: PipelineStage[] = [
-  queueCheckStage,
-  routingStage,
-  constitutionStage,
-  contextStage,
-  promptStage,
-  optimizerStage,
-  executionStage,
-  verifyStage,
-  rectifyStage,
-  reviewStage,
-  autofixStage,
-  regressionStage,
-  completionStage,
-];
-
-/**
- * Post-run pipeline stages — run once after all per-story iterations complete.
- * Handles deferred regression and acceptance tests.
- */
-export const postRunPipeline: PipelineStage[] = [acceptanceStage];
-
-/**
- * Pre-run pipeline stages — run once before the per-story loop, after PRD is loaded.
- * Used for acceptance test setup (generation + RED gate).
- */
-export const preRunPipeline: PipelineStage[] = [acceptanceSetupStage];
-
-// 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 { rectifyStage } from "./rectify";
-export { reviewStage } from "./review";
-export { autofixStage } from "./autofix";
-export { regressionStage } from "./regression";
-export { completionStage } from "./completion";
-export { acceptanceStage } from "./acceptance";

package/src/pipeline/stages/optimizer.ts

@@ -1,74 +0,0 @@
-/**
- * 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

@@ -1,79 +0,0 @@
-/**
- * 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 { getLogger } from "../../logger";
-import { PromptBuilder } from "../../prompts";
-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;
-
-    // PKG-004: use centrally resolved effective config
-    const effectiveConfig = ctx.effectiveConfig ?? ctx.config;
-
-    let prompt: string;
-    if (isBatch) {
-      const builder = PromptBuilder.for("batch")
-        .withLoader(ctx.workdir, ctx.config)
-        .stories(ctx.stories)
-        .context(ctx.contextMarkdown)
-        .constitution(ctx.constitution?.content)
-        .testCommand(effectiveConfig.quality?.commands?.test)
-        .hermeticConfig(effectiveConfig.quality?.testing);
-      prompt = await builder.build();
-    } else {
-      // Both test-after and tdd-simple use the tdd-simple prompt (RED/GREEN/REFACTOR)
-      const role = "tdd-simple" as const;
-      const builder = PromptBuilder.for(role)
-        .withLoader(ctx.workdir, ctx.config)
-        .story(ctx.story)
-        .context(ctx.contextMarkdown)
-        .constitution(ctx.constitution?.content)
-        .testCommand(effectiveConfig.quality?.commands?.test)
-        .hermeticConfig(effectiveConfig.quality?.testing);
-      prompt = await builder.build();
-    }
-
-    ctx.prompt = prompt;
-
-    if (isBatch) {
-      logger.info("prompt", "Batch session prepared", {
-        storyCount: ctx.stories.length,
-        testStrategy: ctx.routing.testStrategy,
-      });
-    } else {
-      logger.info("prompt", "Single session prepared", {
-        storyId: ctx.story.id,
-        testStrategy: ctx.routing.testStrategy,
-      });
-    }
-
-    return { action: "continue" };
-  },
-};

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

@@ -1,103 +0,0 @@
-/**
- * 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/rectify.ts

@@ -1,101 +0,0 @@
-// RE-ARCH: keep
-/**
- * Rectify Stage (ADR-005, Phase 2)
- *
- * Runs after a failed verify stage. Attempts to fix test failures by
- * running a rectification loop (agent + re-verify cycle).
- *
- * Enabled only when ctx.verifyResult?.success === false.
- *
- * Returns:
- * - `retry` fromStage:"verify" — rectification fixed the failures
- * - `escalate`                 — max retries exhausted
- */
-
-import { getLogger } from "../../logger";
-import { pipelineEventBus } from "../event-bus";
-import type { PipelineContext, PipelineStage, StageResult } from "../types";
-
-export const rectifyStage: PipelineStage = {
-  name: "rectify",
-
-  enabled(ctx: PipelineContext): boolean {
-    // Only run when verify failed
-    if (!ctx.verifyResult) return false;
-    if (ctx.verifyResult.success) return false;
-    // Only run when rectification is enabled in config
-    return ctx.config.execution.rectification?.enabled ?? false;
-  },
-
-  skipReason(ctx: PipelineContext): string {
-    if (!ctx.verifyResult || ctx.verifyResult.success) return "not needed (verify passed)";
-    return "disabled (rectification not enabled in config)";
-  },
-
-  async execute(ctx: PipelineContext): Promise<StageResult> {
-    const logger = getLogger();
-    const { verifyResult } = ctx;
-
-    if (!verifyResult || verifyResult.success) {
-      return { action: "continue" };
-    }
-
-    const testOutput = verifyResult.rawOutput ?? "";
-    const maxRetries = ctx.config.execution.rectification?.maxRetries ?? 3;
-
-    logger.info("rectify", "Starting rectification loop", {
-      storyId: ctx.story.id,
-      failCount: verifyResult.failCount,
-      maxRetries,
-    });
-
-    ctx.rectifyAttempt = (ctx.rectifyAttempt ?? 0) + 1;
-    const rectifyAttempt = ctx.rectifyAttempt;
-
-    pipelineEventBus.emit({
-      type: "rectify:started",
-      storyId: ctx.story.id,
-      attempt: rectifyAttempt,
-      testOutput,
-    });
-
-    // PKG-004: use centrally resolved effective config
-    const effectiveConfig = ctx.effectiveConfig ?? ctx.config;
-    const testCommand = effectiveConfig.review?.commands?.test ?? effectiveConfig.quality.commands.test ?? "bun test";
-    const fixed = await _rectifyDeps.runRectificationLoop({
-      config: ctx.config,
-      workdir: ctx.workdir,
-      story: ctx.story,
-      testCommand,
-      timeoutSeconds: effectiveConfig.execution.verificationTimeoutSeconds,
-      testOutput,
-      agentGetFn: ctx.agentGetFn,
-    });
-
-    pipelineEventBus.emit({
-      type: "rectify:completed",
-      storyId: ctx.story.id,
-      attempt: rectifyAttempt,
-      fixed,
-    });
-
-    if (fixed) {
-      logger.info("rectify", "Rectification succeeded — retrying verify", { storyId: ctx.story.id });
-      // Clear verifyResult so verify stage re-runs fresh
-      ctx.verifyResult = undefined;
-      return { action: "retry", fromStage: "verify" };
-    }
-
-    logger.warn("rectify", "Rectification exhausted — escalating", { storyId: ctx.story.id });
-    return {
-      action: "escalate",
-      reason: `Rectification exhausted after ${maxRetries} attempts (${verifyResult.failCount} test failures)`,
-    };
-  },
-};
-
-/**
- * Injectable deps for testing.
- */
-import { runRectificationLoop } from "../../verification/rectification-loop";
-export const _rectifyDeps = { runRectificationLoop };

package/src/pipeline/stages/regression.ts

@@ -1,99 +0,0 @@
-// RE-ARCH: keep
-/**
- * Regression Stage (ADR-005, Phase 2)
- *
- * Runs a full-suite regression gate as part of the per-story pipeline,
- * when regressionGate.mode === "per-story" AND verify passed.
- *
- * This replaces the per-story regression gate previously handled in
- * src/execution/post-verify.ts (which will be deleted in Phase 4).
- *
- * Returns:
- * - `continue`  — full suite passed
- * - `escalate`  — full suite failed after optional rectification
- */
-
-import { getLogger } from "../../logger";
-import { logTestOutput } from "../../utils/log-test-output";
-import { verificationOrchestrator } from "../../verification/orchestrator";
-import type { VerifyContext } from "../../verification/orchestrator-types";
-import { pipelineEventBus } from "../event-bus";
-import type { PipelineContext, PipelineStage, StageResult } from "../types";
-
-export const regressionStage: PipelineStage = {
-  name: "regression",
-
-  enabled(ctx: PipelineContext): boolean {
-    const effectiveConfig = ctx.effectiveConfig ?? ctx.config;
-    const mode = effectiveConfig.execution.regressionGate?.mode ?? "deferred";
-    if (mode !== "per-story") return false;
-    // Only run when verify passed (or was skipped/not set)
-    if (ctx.verifyResult && !ctx.verifyResult.success) return false;
-    const gateEnabled = effectiveConfig.execution.regressionGate?.enabled ?? true;
-    return gateEnabled;
-  },
-
-  skipReason(ctx: PipelineContext): string {
-    const effectiveConfig = ctx.effectiveConfig ?? ctx.config;
-    const mode = effectiveConfig.execution.regressionGate?.mode ?? "deferred";
-    if (mode !== "per-story") return `not needed (regression mode is '${mode}', not 'per-story')`;
-    return "disabled (regression gate not enabled in config)";
-  },
-
-  async execute(ctx: PipelineContext): Promise<StageResult> {
-    const logger = getLogger();
-    // PKG-004: use centrally resolved effective config
-    const effectiveConfig = ctx.effectiveConfig ?? ctx.config;
-    const testCommand = effectiveConfig.review?.commands?.test ?? effectiveConfig.quality.commands.test ?? "bun test";
-    const timeoutSeconds = effectiveConfig.execution.regressionGate?.timeoutSeconds ?? 120;
-
-    logger.info("regression", "Running full-suite regression gate", { storyId: ctx.story.id });
-
-    const verifyCtx: VerifyContext = {
-      workdir: ctx.workdir,
-      testCommand,
-      timeoutSeconds,
-      storyId: ctx.story.id,
-      acceptOnTimeout: effectiveConfig.execution.regressionGate?.acceptOnTimeout ?? true,
-      config: ctx.config,
-    };
-
-    const result = await _regressionStageDeps.verifyRegression(verifyCtx);
-
-    pipelineEventBus.emit({ type: "verify:completed", storyId: ctx.story.id, result });
-
-    if (result.success) {
-      logger.info("regression", "Full-suite regression gate passed", { storyId: ctx.story.id });
-      return { action: "continue" };
-    }
-
-    if (result.status === "TIMEOUT") {
-      logger.warn("regression", "Regression gate timed out (accepted as pass)", { storyId: ctx.story.id });
-      return { action: "continue" };
-    }
-
-    logger.warn("regression", "Full-suite regression detected", {
-      storyId: ctx.story.id,
-      failCount: result.failCount,
-    });
-    logTestOutput(logger, "regression", result.rawOutput, { storyId: ctx.story.id });
-
-    pipelineEventBus.emit({
-      type: "regression:detected",
-      storyId: ctx.story.id,
-      failedTests: result.failCount,
-    });
-
-    return {
-      action: "escalate",
-      reason: `Full-suite regression: ${result.failCount} test(s) failing`,
-    };
-  },
-};
-
-/**
- * Injectable deps for testing.
- */
-export const _regressionStageDeps = {
-  verifyRegression: (ctx: VerifyContext) => verificationOrchestrator.verifyRegression(ctx),
-};

package/src/pipeline/stages/review.ts

@@ -1,94 +0,0 @@
-/**
- * Review Stage (ADR-005, Phase 2)
- *
- * Delegates to ReviewOrchestrator for built-in checks + plugin reviewers.
- *
- * @returns
- * - `continue`: Review passed
- * - `escalate`: Built-in check failed (lint/typecheck) — autofix stage handles retry
- * - `escalate`: Plugin reviewer failed and security-review trigger responded non-abort
- * - `fail`: Plugin reviewer hard-failed (no trigger, or trigger responded abort)
- */
-
-// RE-ARCH: rewrite
-import { join } from "node:path";
-import { checkSecurityReview, isTriggerEnabled } from "../../interaction/triggers";
-import { getLogger } from "../../logger";
-import { reviewOrchestrator } from "../../review/orchestrator";
-import type { PipelineContext, PipelineStage, StageResult } from "../types";
-
-export const reviewStage: PipelineStage = {
-  name: "review",
-  enabled: (ctx) => (ctx.effectiveConfig ?? ctx.config).review.enabled,
-
-  async execute(ctx: PipelineContext): Promise<StageResult> {
-    const logger = getLogger();
-
-    // PKG-004: use centrally resolved effective config
-    const effectiveConfig = ctx.effectiveConfig ?? ctx.config;
-
-    logger.info("review", "Running review phase", { storyId: ctx.story.id });
-
-    // MW-010: scope review to package directory when story.workdir is set
-    const effectiveWorkdir = ctx.story.workdir ? join(ctx.workdir, ctx.story.workdir) : ctx.workdir;
-
-    const result = await reviewOrchestrator.review(
-      effectiveConfig.review,
-      effectiveWorkdir,
-      effectiveConfig.execution,
-      ctx.plugins,
-      ctx.storyGitRef,
-      ctx.story.workdir, // MW-010: scope changed-file checks to package
-    );
-
-    ctx.reviewResult = result.builtIn;
-
-    if (!result.success) {
-      // Collect structured findings from plugin reviewers for escalation context
-      const allFindings = result.builtIn.pluginReviewers?.flatMap((pr) => pr.findings ?? []) ?? [];
-      if (allFindings.length > 0) {
-        ctx.reviewFindings = allFindings;
-      }
-
-      if (result.pluginFailed) {
-        // security-review trigger: prompt before permanently failing
-        if (ctx.interaction && isTriggerEnabled("security-review", effectiveConfig)) {
-          const shouldContinue = await _reviewDeps.checkSecurityReview(
-            { featureName: ctx.prd.feature, storyId: ctx.story.id },
-            effectiveConfig,
-            ctx.interaction,
-          );
-          if (!shouldContinue) {
-            logger.error("review", `Plugin reviewer failed: ${result.failureReason}`, { storyId: ctx.story.id });
-            return { action: "fail", reason: `Review failed: ${result.failureReason}` };
-          }
-          logger.warn("review", "Security-review trigger escalated — retrying story", { storyId: ctx.story.id });
-          return { action: "escalate", reason: `Review failed: ${result.failureReason}` };
-        }
-
-        logger.error("review", `Plugin reviewer failed: ${result.failureReason}`, { storyId: ctx.story.id });
-        return { action: "fail", reason: `Review failed: ${result.failureReason}` };
-      }
-
-      logger.warn("review", "Review failed (built-in checks) — handing off to autofix", {
-        reason: result.failureReason,
-        storyId: ctx.story.id,
-      });
-      // ctx.reviewResult is already set with success:false — autofixStage handles it next
-      return { action: "continue" };
-    }
-
-    logger.info("review", "Review passed", {
-      durationMs: result.builtIn.totalDurationMs,
-      storyId: ctx.story.id,
-    });
-    return { action: "continue" };
-  },
-};
-
-/**
- * Swappable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
- */
-export const _reviewDeps = {
-  checkSecurityReview,
-};