@nathapp/nax 0.21.0 → 0.22.1

package/src/pipeline/stages/index.ts

@@ -7,6 +7,7 @@
 
 import type { PipelineStage } from "../types";
 import { acceptanceStage } from "./acceptance";
+import { autofixStage } from "./autofix";
 import { completionStage } from "./completion";
 import { constitutionStage } from "./constitution";
 import { contextStage } from "./context";
@@ -14,6 +15,8 @@ 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";
@@ -21,18 +24,21 @@ 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)
+ * 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,
@@ -43,11 +49,19 @@ export const defaultPipeline: PipelineStage[] = [
   optimizerStage,
   executionStage,
   verifyStage,
+  rectifyStage,
   reviewStage,
+  autofixStage,
+  regressionStage,
   completionStage,
-  acceptanceStage,
 ];
 
+/**
+ * Post-run pipeline stages — run once after all per-story iterations complete.
+ * Handles deferred regression and acceptance tests.
+ */
+export const postRunPipeline: PipelineStage[] = [acceptanceStage];
+
 // Re-export individual stages for custom pipeline construction
 export { queueCheckStage } from "./queue-check";
 export { routingStage } from "./routing";
@@ -57,6 +71,9 @@ 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/rectify.ts

@@ -0,0 +1,93 @@
+// 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;
+  },
+
+  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,
+    });
+
+    const testCommand = ctx.config.review?.commands?.test ?? ctx.config.quality.commands.test ?? "bun test";
+    const fixed = await _rectifyDeps.runRectificationLoop({
+      config: ctx.config,
+      workdir: ctx.workdir,
+      story: ctx.story,
+      testCommand,
+      timeoutSeconds: ctx.config.execution.verificationTimeoutSeconds,
+      testOutput,
+    });
+
+    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

@@ -0,0 +1,88 @@
+// 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 { 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 mode = ctx.config.execution.regressionGate?.mode ?? "deferred";
+    if (mode !== "per-story") return false;
+    // Only run when verify passed (or was skipped/not set)
+    // Only run when verify passed (or was skipped/not set)
+    if (ctx.verifyResult && !ctx.verifyResult.success) return false;
+    const gateEnabled = ctx.config.execution.regressionGate?.enabled ?? true;
+    return gateEnabled;
+  },
+
+  async execute(ctx: PipelineContext): Promise<StageResult> {
+    const logger = getLogger();
+    const testCommand = ctx.config.review?.commands?.test ?? ctx.config.quality.commands.test ?? "bun test";
+    const timeoutSeconds = ctx.config.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: ctx.config.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,
+    });
+
+    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,75 +1,19 @@
 /**
- * Review Stage
+ * Review Stage (ADR-005, Phase 2)
  *
- * 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.
+ * Delegates to ReviewOrchestrator for built-in checks + plugin reviewers.
  *
  * @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" }
- * ```
+ * - `escalate`: Built-in check failed (lint/typecheck) — autofix stage handles retry
+ * - `fail`: Plugin reviewer hard-failed
  */
 
-import { spawn } from "bun";
+// RE-ARCH: rewrite
 import { getLogger } from "../../logger";
-import { runReview } from "../../review";
+import { reviewOrchestrator } from "../../review/orchestrator";
 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,
@@ -77,105 +21,27 @@ export const reviewStage: PipelineStage = {
   async execute(ctx: PipelineContext): Promise<StageResult> {
     const logger = getLogger();
 
-    logger.info("review", "Running review phase");
+    logger.info("review", "Running review phase", { storyId: ctx.story.id });
+
+    const result = await reviewOrchestrator.review(ctx.config.review, ctx.workdir, ctx.config.execution, ctx.plugins);
 
-    // Run built-in checks (typecheck, lint, test)
-    const reviewResult = await runReview(ctx.config.review, ctx.workdir, ctx.config.execution);
-    ctx.reviewResult = reviewResult;
+    ctx.reviewResult = result.builtIn;
+
+    if (!result.success) {
+      if (result.pluginFailed) {
+        logger.error("review", `Plugin reviewer failed: ${result.failureReason}`, { storyId: ctx.story.id });
+        return { action: "fail", reason: `Review failed: ${result.failureReason}` };
+      }
 
-    // BUG-030: Review failure (lint/typecheck) should escalate, not hard-fail.
-    // Lint/typecheck errors are auto-fixable — give the agent a retry with error context.
-    // Only plugin reviewer rejections are hard failures.
-    if (!reviewResult.success) {
       logger.warn("review", "Review failed (built-in checks) — escalating for retry", {
-        reason: reviewResult.failureReason,
+        reason: result.failureReason,
         storyId: ctx.story.id,
       });
-      return { action: "escalate", 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;
-        }
-      }
+      return { action: "escalate", reason: `Review failed: ${result.failureReason}` };
     }
 
     logger.info("review", "Review passed", {
-      durationMs: reviewResult.totalDurationMs,
+      durationMs: result.builtIn.totalDurationMs,
       storyId: ctx.story.id,
     });
     return { action: "continue" };

package/src/pipeline/stages/verify.ts

@@ -1,7 +1,7 @@
 /**
  * Verify Stage
  *
- * Verifies the agent\'s work meets basic requirements by running tests.
+ * Verifies the agent's work meets basic requirements by running tests.
  * This is a lightweight verification before the full review stage.
  *
  * @returns
@@ -11,7 +11,8 @@
 
 import type { SmartTestRunnerConfig } from "../../config/types";
 import { getLogger } from "../../logger";
-import { regression } from "../../verification/gate";
+import type { VerifyStatus } from "../../verification/orchestrator-types";
+import { regression } from "../../verification/runners";
 import { _smartRunnerDeps } from "../../verification/smart-runner";
 import type { PipelineContext, PipelineStage, StageResult } from "../types";
 
@@ -109,6 +110,21 @@ export const verifyStage: PipelineStage = {
       acceptOnTimeout: ctx.config.execution.regressionGate?.acceptOnTimeout ?? true,
     });
 
+    // Store result on context for rectify stage
+    ctx.verifyResult = {
+      success: result.success,
+      status: (result.status === "TIMEOUT" ? "TIMEOUT" : result.success ? "PASS" : "TEST_FAILURE") as VerifyStatus,
+      storyId: ctx.story.id,
+      strategy: "scoped",
+      passCount: result.passCount ?? 0,
+      failCount: result.failCount ?? 0,
+      totalCount: (result.passCount ?? 0) + (result.failCount ?? 0),
+      failures: [],
+      rawOutput: result.output,
+      durationMs: 0,
+      countsTowardEscalation: result.countsTowardEscalation,
+    };
+
     // HARD FAILURE: Tests must pass for story to be marked complete
     if (!result.success) {
       // BUG-019: Distinguish timeout from actual test failures

package/src/pipeline/subscribers/hooks.ts

@@ -0,0 +1,133 @@
+// RE-ARCH: keep
+/**
+ * Hooks Subscriber (ADR-005, Phase 3 US-P3-001)
+ *
+ * Maps pipeline events to nax lifecycle hooks (on-start, on-story-start,
+ * on-story-complete, on-story-fail, on-pause, on-complete).
+ *
+ * Design:
+ * - All hook calls are fire-and-forget (matching prior fireHook behavior)
+ * - Errors in hooks are logged, never rethrown
+ * - Returns unsubscribe function for cleanup
+ */
+
+import { hookCtx } from "../../execution/story-context";
+import { type LoadedHooksConfig, fireHook } from "../../hooks";
+import { getSafeLogger } from "../../logger";
+import type { PipelineEventBus } from "../event-bus";
+
+export type UnsubscribeFn = () => void;
+
+/**
+ * Wire pipeline lifecycle hooks to the event bus.
+ *
+ * @param bus       - The pipeline event bus
+ * @param hooks     - Loaded hooks config (from nax.config)
+ * @param workdir   - Working directory for hook script execution
+ * @param feature   - Feature name (for hook context payload)
+ * @returns Unsubscribe function (call to remove all subscriptions)
+ */
+export function wireHooks(
+  bus: PipelineEventBus,
+  hooks: LoadedHooksConfig,
+  workdir: string,
+  feature: string,
+): UnsubscribeFn {
+  const logger = getSafeLogger();
+
+  const safe = (name: string, fn: () => Promise<void>) => {
+    fn().catch((err) => logger?.warn("hooks-subscriber", `Hook "${name}" failed`, { error: String(err) }));
+  };
+
+  const unsubs: UnsubscribeFn[] = [];
+
+  // run:started → on-start
+  unsubs.push(
+    bus.on("run:started", (ev) => {
+      safe("on-start", () => fireHook(hooks, "on-start", hookCtx(feature, { status: "running" }), workdir));
+    }),
+  );
+
+  // story:started → on-story-start
+  unsubs.push(
+    bus.on("story:started", (ev) => {
+      safe("on-story-start", () =>
+        fireHook(
+          hooks,
+          "on-story-start",
+          hookCtx(feature, { storyId: ev.storyId, model: ev.modelTier, agent: ev.agent }),
+          workdir,
+        ),
+      );
+    }),
+  );
+
+  // story:completed → on-story-complete
+  unsubs.push(
+    bus.on("story:completed", (ev) => {
+      safe("on-story-complete", () =>
+        fireHook(
+          hooks,
+          "on-story-complete",
+          hookCtx(feature, { storyId: ev.storyId, status: "passed", cost: ev.cost }),
+          workdir,
+        ),
+      );
+    }),
+  );
+
+  // story:failed → on-story-fail
+  unsubs.push(
+    bus.on("story:failed", (ev) => {
+      safe("on-story-fail", () =>
+        fireHook(
+          hooks,
+          "on-story-fail",
+          hookCtx(feature, { storyId: ev.storyId, status: "failed", reason: ev.reason }),
+          workdir,
+        ),
+      );
+    }),
+  );
+
+  // story:paused → on-pause
+  unsubs.push(
+    bus.on("story:paused", (ev) => {
+      safe("on-pause (story)", () =>
+        fireHook(
+          hooks,
+          "on-pause",
+          hookCtx(feature, { storyId: ev.storyId, reason: ev.reason, cost: ev.cost }),
+          workdir,
+        ),
+      );
+    }),
+  );
+
+  // run:paused → on-pause
+  unsubs.push(
+    bus.on("run:paused", (ev) => {
+      safe("on-pause (run)", () =>
+        fireHook(
+          hooks,
+          "on-pause",
+          hookCtx(feature, { storyId: ev.storyId, reason: ev.reason, cost: ev.cost }),
+          workdir,
+        ),
+      );
+    }),
+  );
+
+  // run:completed → on-complete
+  unsubs.push(
+    bus.on("run:completed", (ev) => {
+      safe("on-complete", () =>
+        fireHook(hooks, "on-complete", hookCtx(feature, { status: "complete", cost: ev.totalCost ?? 0 }), workdir),
+      );
+    }),
+  );
+
+  return () => {
+    for (const u of unsubs) u();
+  };
+}