@nathapp/nax 0.39.0 → 0.39.2

package/dist/nax.js

@@ -18281,7 +18281,8 @@ var init_schemas3 = __esm(() => {
       typecheck: exports_external.string().optional(),
       lint: exports_external.string().optional(),
       test: exports_external.string().optional()
-    })
+    }),
+    pluginMode: exports_external.enum(["per-story", "deferred"]).default("per-story")
   });
   PlanConfigSchema = exports_external.object({
     model: ModelTierSchema,
@@ -18529,7 +18530,8 @@ var init_defaults = __esm(() => {
     review: {
       enabled: true,
       checks: ["typecheck", "lint"],
-      commands: {}
+      commands: {},
+      pluginMode: "per-story"
     },
     plan: {
       model: "balanced",
@@ -20159,7 +20161,9 @@ async function tryLlmBatchRoute(config2, stories, label = "routing") {
   const logger = getSafeLogger();
   try {
     logger?.debug("routing", `LLM batch routing: ${label}`, { storyCount: stories.length, mode });
-    await routeBatch(stories, { config: config2 });
+    const agentName = config2.execution?.agent ?? "claude";
+    const adapter = getAgent(agentName);
+    await routeBatch(stories, { config: config2, adapter });
     logger?.debug("routing", "LLM batch routing complete", { label });
   } catch (err) {
     logger?.warn("routing", "LLM batch routing failed, falling back to individual routing", {
@@ -20169,6 +20173,7 @@ async function tryLlmBatchRoute(config2, stories, label = "routing") {
   }
 }
 var init_batch_route = __esm(() => {
+  init_registry();
   init_logger2();
   init_llm();
 });
@@ -20793,7 +20798,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@nathapp/nax",
-    version: "0.39.0",
+    version: "0.39.2",
     description: "AI Coding Agent Orchestrator \u2014 loops until done",
     type: "module",
     bin: {
@@ -20857,8 +20862,8 @@ var init_version = __esm(() => {
   NAX_VERSION = package_default.version;
   NAX_COMMIT = (() => {
     try {
-      if (/^[0-9a-f]{6,10}$/.test("e6f293e"))
-        return "e6f293e";
+      if (/^[0-9a-f]{6,10}$/.test("d6c0898"))
+        return "d6c0898";
     } catch {}
     try {
       const result = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
@@ -22813,16 +22818,20 @@ async function getChangedFiles(workdir, baseRef) {
 }
 
 class ReviewOrchestrator {
-  async review(reviewConfig, workdir, executionConfig, plugins) {
+  async review(reviewConfig, workdir, executionConfig, plugins, storyGitRef) {
     const logger = getSafeLogger();
     const builtIn = await runReview(reviewConfig, workdir, executionConfig);
     if (!builtIn.success) {
       return { builtIn, success: false, failureReason: builtIn.failureReason, pluginFailed: false };
     }
+    if (reviewConfig.pluginMode === "deferred") {
+      logger?.debug("review", "Plugin reviewers deferred \u2014 skipping per-story execution");
+      return { builtIn, success: true, pluginFailed: false };
+    }
     if (plugins) {
       const reviewers = plugins.getReviewers();
       if (reviewers.length > 0) {
-        const baseRef = executionConfig?.storyGitRef;
+        const baseRef = storyGitRef ?? executionConfig?.storyGitRef;
         const changedFiles = await getChangedFiles(workdir, baseRef);
         const pluginResults = [];
         for (const reviewer of reviewers) {
@@ -22897,7 +22906,7 @@ var init_review = __esm(() => {
     async execute(ctx) {
       const logger = getLogger();
       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);
+      const result = await reviewOrchestrator.review(ctx.config.review, ctx.workdir, ctx.config.execution, ctx.plugins, ctx.storyGitRef);
       ctx.reviewResult = result.builtIn;
       if (!result.success) {
         const allFindings = result.builtIn.pluginReviewers?.flatMap((pr) => pr.findings ?? []) ?? [];
@@ -31461,6 +31470,78 @@ var init_reporters = __esm(() => {
   init_logger2();
 });
 
+// src/execution/deferred-review.ts
+var {spawn: spawn3 } = globalThis.Bun;
+async function captureRunStartRef(workdir) {
+  try {
+    const proc = _deferredReviewDeps.spawn({
+      cmd: ["git", "rev-parse", "HEAD"],
+      cwd: workdir,
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    const [, stdout] = await Promise.all([proc.exited, new Response(proc.stdout).text()]);
+    return stdout.trim();
+  } catch {
+    return "";
+  }
+}
+async function getChangedFilesForDeferred(workdir, baseRef) {
+  try {
+    const proc = _deferredReviewDeps.spawn({
+      cmd: ["git", "diff", "--name-only", `${baseRef}...HEAD`],
+      cwd: workdir,
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    const [, stdout] = await Promise.all([proc.exited, new Response(proc.stdout).text()]);
+    return stdout.trim().split(`
+`).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+async function runDeferredReview(workdir, reviewConfig, plugins, runStartRef) {
+  if (!reviewConfig || reviewConfig.pluginMode !== "deferred") {
+    return;
+  }
+  const reviewers = plugins.getReviewers();
+  if (reviewers.length === 0) {
+    return;
+  }
+  const changedFiles = await getChangedFilesForDeferred(workdir, runStartRef);
+  const reviewerResults = [];
+  let anyFailed = false;
+  for (const reviewer of reviewers) {
+    try {
+      const result = await reviewer.check(workdir, changedFiles);
+      reviewerResults.push({
+        name: reviewer.name,
+        passed: result.passed,
+        output: result.output,
+        exitCode: result.exitCode
+      });
+      if (!result.passed) {
+        anyFailed = true;
+      }
+    } catch (error48) {
+      const errorMsg = error48 instanceof Error ? error48.message : String(error48);
+      reviewerResults.push({
+        name: reviewer.name,
+        passed: false,
+        output: "",
+        error: errorMsg
+      });
+      anyFailed = true;
+    }
+  }
+  return { runStartRef, changedFiles, reviewerResults, anyFailed };
+}
+var _deferredReviewDeps;
+var init_deferred_review = __esm(() => {
+  _deferredReviewDeps = { spawn: spawn3 };
+});
+
 // src/execution/dry-run.ts
 async function handleDryRun(ctx) {
   const logger = getSafeLogger();
@@ -31644,22 +31725,6 @@ function resolveMaxAttemptsOutcome(failureCategory) {
       return "fail";
   }
 }
-async function tryLlmBatchRoute2(config2, stories, label = "routing") {
-  const mode = config2.routing.llm?.mode ?? "hybrid";
-  if (config2.routing.strategy !== "llm" || mode === "per-story" || stories.length === 0)
-    return;
-  const logger = getSafeLogger();
-  try {
-    logger?.debug("routing", `LLM batch routing: ${label}`, { storyCount: stories.length, mode });
-    await routeBatch(stories, { config: config2 });
-    logger?.debug("routing", "LLM batch routing complete", { label });
-  } catch (err) {
-    logger?.warn("routing", "LLM batch routing failed, falling back to individual routing", {
-      error: err.message,
-      label
-    });
-  }
-}
 function shouldRetrySameTier(verifyResult) {
   return verifyResult?.status === "RUNTIME_CRASH";
 }
@@ -31739,7 +31804,7 @@ async function handleTierEscalation(ctx) {
     clearCacheForStory(story.id);
   }
   if (routingMode === "hybrid") {
-    await tryLlmBatchRoute2(ctx.config, storiesToEscalate, "hybrid-re-route-pipeline");
+    await tryLlmBatchRoute(ctx.config, storiesToEscalate, "hybrid-re-route-pipeline");
   }
   return {
     outcome: "escalated",
@@ -31752,6 +31817,7 @@ var init_tier_escalation = __esm(() => {
   init_hooks();
   init_logger2();
   init_prd();
+  init_batch_route();
   init_llm();
   init_escalation();
   init_helpers();
@@ -32062,6 +32128,8 @@ async function executeSequential(ctx, initialPrd) {
   ];
   const allStoryMetrics = [];
   let warningSent = false;
+  let deferredReview;
+  const runStartRef = await captureRunStartRef(ctx.workdir);
   pipelineEventBus.clear();
   wireHooks(pipelineEventBus, ctx.hooks, ctx.workdir, ctx.feature);
   wireReporters(pipelineEventBus, ctx.pluginRegistry, ctx.runId, ctx.startTime);
@@ -32074,7 +32142,8 @@ async function executeSequential(ctx, initialPrd) {
     storiesCompleted,
     totalCost,
     allStoryMetrics,
-    exitReason
+    exitReason,
+    deferredReview
   });
   startHeartbeat(ctx.statusWriter, () => totalCost, () => iterations, ctx.logFilePath);
   try {
@@ -32093,6 +32162,7 @@ async function executeSequential(ctx, initialPrd) {
             return buildResult2("pre-merge-aborted");
           }
         }
+        deferredReview = await runDeferredReview(ctx.workdir, ctx.config.review, ctx.pluginRegistry, runStartRef);
         return buildResult2("completed");
       }
       const selected = selectNextStories(prd, ctx.config, ctx.batchPlan, currentBatchIndex, lastStoryId, ctx.useBatch);
@@ -32176,6 +32246,7 @@ var init_sequential_executor = __esm(() => {
   init_reporters();
   init_prd();
   init_crash_recovery();
+  init_deferred_review();
   init_iteration_runner();
   init_story_selector();
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.39.0",
+  "version": "0.39.2",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {

package/src/config/defaults.ts

@@ -116,6 +116,7 @@ export const DEFAULT_CONFIG: NaxConfig = {
     enabled: true,
     checks: ["typecheck", "lint"],
     commands: {},
+    pluginMode: "per-story",
   },
   plan: {
     model: "balanced",

package/src/config/runtime-types.ts

@@ -216,6 +216,8 @@ export interface ReviewConfig {
     lint?: string;
     test?: string;
   };
+  /** Plugin reviewer mode: "per-story" (run after each story) or "deferred" (run once at end of run, default: "per-story") */
+  pluginMode?: "per-story" | "deferred";
 }
 
 /** Plan config */

package/src/config/schemas.ts

@@ -170,6 +170,7 @@ const ReviewConfigSchema = z.object({
     lint: z.string().optional(),
     test: z.string().optional(),
   }),
+  pluginMode: z.enum(["per-story", "deferred"]).default("per-story"),
 });
 
 const PlanConfigSchema = z.object({

package/src/execution/deferred-review.ts

@@ -0,0 +1,105 @@
+/**
+ * Deferred Plugin Review (DR-003)
+ *
+ * Captures the run-start git ref and runs all plugin reviewers once after
+ * all stories complete, using the full diff from run-start to HEAD.
+ */
+
+import { spawn } from "bun";
+import type { PluginRegistry } from "../plugins";
+import type { ReviewConfig } from "../review/types";
+
+/** Injectable deps for testing */
+export const _deferredReviewDeps = { spawn };
+
+export interface DeferredReviewResult {
+  runStartRef: string;
+  changedFiles: string[];
+  reviewerResults: Array<{
+    name: string;
+    passed: boolean;
+    output: string;
+    exitCode?: number;
+    error?: string;
+  }>;
+  anyFailed: boolean;
+}
+
+/** Capture the current HEAD git ref. Returns "" on failure. */
+export async function captureRunStartRef(workdir: string): Promise<string> {
+  try {
+    const proc = _deferredReviewDeps.spawn({
+      cmd: ["git", "rev-parse", "HEAD"],
+      cwd: workdir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [, stdout] = await Promise.all([proc.exited, new Response(proc.stdout).text()]);
+    return stdout.trim();
+  } catch {
+    return "";
+  }
+}
+
+async function getChangedFilesForDeferred(workdir: string, baseRef: string): Promise<string[]> {
+  try {
+    const proc = _deferredReviewDeps.spawn({
+      cmd: ["git", "diff", "--name-only", `${baseRef}...HEAD`],
+      cwd: workdir,
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const [, stdout] = await Promise.all([proc.exited, new Response(proc.stdout).text()]);
+    return stdout.trim().split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/** Run all plugin reviewers once with the full diff since runStartRef. */
+export async function runDeferredReview(
+  workdir: string,
+  reviewConfig: ReviewConfig,
+  plugins: PluginRegistry,
+  runStartRef: string,
+): Promise<DeferredReviewResult | undefined> {
+  if (!reviewConfig || reviewConfig.pluginMode !== "deferred") {
+    return undefined;
+  }
+
+  const reviewers = plugins.getReviewers();
+  if (reviewers.length === 0) {
+    return undefined;
+  }
+
+  const changedFiles = await getChangedFilesForDeferred(workdir, runStartRef);
+
+  const reviewerResults: DeferredReviewResult["reviewerResults"] = [];
+  let anyFailed = false;
+
+  for (const reviewer of reviewers) {
+    try {
+      const result = await reviewer.check(workdir, changedFiles);
+      reviewerResults.push({
+        name: reviewer.name,
+        passed: result.passed,
+        output: result.output,
+        exitCode: result.exitCode,
+      });
+      if (!result.passed) {
+        anyFailed = true;
+      }
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      reviewerResults.push({
+        name: reviewer.name,
+        passed: false,
+        output: "",
+        error: errorMsg,
+      });
+      anyFailed = true;
+    }
+  }
+
+  return { runStartRef, changedFiles, reviewerResults, anyFailed };
+}

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

@@ -12,7 +12,8 @@ import { type LoadedHooksConfig, fireHook } from "../../hooks";
 import { getSafeLogger } from "../../logger";
 import type { PRD, StructuredFailure, UserStory } from "../../prd";
 import { markStoryFailed, savePRD } from "../../prd";
-import { clearCacheForStory, routeBatch as llmRouteBatch } from "../../routing/strategies/llm";
+import { tryLlmBatchRoute } from "../../routing/batch-route";
+import { clearCacheForStory } from "../../routing/strategies/llm";
 import type { FailureCategory } from "../../tdd/types";
 import { calculateMaxIterations, escalateTier, getTierConfig } from "../escalation";
 import { hookCtx } from "../helpers";
@@ -172,25 +173,6 @@ export async function preIterationTierCheck(
   return { shouldSkipIteration: true, prdDirty: true, prd: failedPrd };
 }
 
-/**
- * Try LLM batch routing for ready stories. Logs and swallows errors (falls back to per-story routing).
- */
-async function tryLlmBatchRoute(config: NaxConfig, stories: UserStory[], label = "routing"): Promise<void> {
-  const mode = config.routing.llm?.mode ?? "hybrid";
-  if (config.routing.strategy !== "llm" || mode === "per-story" || stories.length === 0) return;
-  const logger = getSafeLogger();
-  try {
-    logger?.debug("routing", `LLM batch routing: ${label}`, { storyCount: stories.length, mode });
-    await llmRouteBatch(stories, { config });
-    logger?.debug("routing", "LLM batch routing complete", { label });
-  } catch (err) {
-    logger?.warn("routing", "LLM batch routing failed, falling back to individual routing", {
-      error: (err as Error).message,
-      label,
-    });
-  }
-}
-
 export interface EscalationHandlerContext {
   story: UserStory;
   storiesToExecute: UserStory[];

package/src/execution/executor-types.ts

@@ -13,6 +13,7 @@ import type { RoutingResult } 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 { StatusWriter } from "./status-writer";
 
 export interface SequentialExecutionContext {
@@ -41,6 +42,7 @@ export interface SequentialExecutionResult {
   totalCost: number;
   allStoryMetrics: StoryMetrics[];
   exitReason: "completed" | "cost-limit" | "max-iterations" | "stalled" | "no-stories" | "pre-merge-aborted";
+  deferredReview?: DeferredReviewResult;
 }
 
 /**

package/src/execution/sequential-executor.ts

@@ -15,6 +15,8 @@ import type { PipelineContext } from "../pipeline/types";
 import { generateHumanHaltSummary, isComplete, isStalled, loadPRD } from "../prd";
 import type { PRD } from "../prd/types";
 import { startHeartbeat } from "./crash-recovery";
+import { captureRunStartRef, runDeferredReview } from "./deferred-review";
+import type { DeferredReviewResult } from "./deferred-review";
 import type { SequentialExecutionContext, SequentialExecutionResult } from "./executor-types";
 import { runIteration } from "./iteration-runner";
 import { selectNextStories } from "./story-selector";
@@ -37,6 +39,9 @@ export async function executeSequential(
   ];
   const allStoryMetrics: StoryMetrics[] = [];
   let warningSent = false;
+  let deferredReview: DeferredReviewResult | undefined;
+
+  const runStartRef = await captureRunStartRef(ctx.workdir);
 
   pipelineEventBus.clear();
   wireHooks(pipelineEventBus, ctx.hooks, ctx.workdir, ctx.feature);
@@ -52,6 +57,7 @@ export async function executeSequential(
     totalCost,
     allStoryMetrics,
     exitReason,
+    deferredReview,
   });
 
   startHeartbeat(
@@ -82,6 +88,7 @@ export async function executeSequential(
             return buildResult("pre-merge-aborted");
           }
         }
+        deferredReview = await runDeferredReview(ctx.workdir, ctx.config.review, ctx.pluginRegistry, runStartRef);
         return buildResult("completed");
       }
 

package/src/pipeline/stages/review.ts

@@ -25,7 +25,13 @@ export const reviewStage: PipelineStage = {
 
     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);
+    const result = await reviewOrchestrator.review(
+      ctx.config.review,
+      ctx.workdir,
+      ctx.config.execution,
+      ctx.plugins,
+      ctx.storyGitRef,
+    );
 
     ctx.reviewResult = result.builtIn;
 

package/src/review/orchestrator.ts

@@ -74,6 +74,7 @@ export class ReviewOrchestrator {
     workdir: string,
     executionConfig: NaxConfig["execution"],
     plugins?: PluginRegistry,
+    storyGitRef?: string,
   ): Promise<OrchestratorReviewResult> {
     const logger = getSafeLogger();
 
@@ -83,11 +84,16 @@ export class ReviewOrchestrator {
       return { builtIn, success: false, failureReason: builtIn.failureReason, pluginFailed: false };
     }
 
+    if (reviewConfig.pluginMode === "deferred") {
+      logger?.debug("review", "Plugin reviewers deferred — skipping per-story execution");
+      return { builtIn, success: true, pluginFailed: false };
+    }
+
     if (plugins) {
       const reviewers = plugins.getReviewers();
       if (reviewers.length > 0) {
         // Use the story's start ref if available to capture auto-committed changes
-        const baseRef = executionConfig?.storyGitRef;
+        const baseRef = storyGitRef ?? executionConfig?.storyGitRef;
         const changedFiles = await getChangedFiles(workdir, baseRef);
         const pluginResults: ReviewResult["pluginReviewers"] = [];
 

package/src/review/types.ts

@@ -65,4 +65,6 @@ export interface ReviewConfig {
     lint?: string;
     test?: string;
   };
+  /** When to run plugin reviewers: per-story (default) or deferred (skip per-story, run once at end) */
+  pluginMode?: "per-story" | "deferred";
 }

package/src/routing/batch-route.ts

@@ -2,6 +2,7 @@
  * LLM Batch Routing Helper
  */
 
+import { getAgent } from "../agents/registry";
 import type { NaxConfig } from "../config";
 import { getSafeLogger } from "../logger";
 import type { UserStory } from "../prd";
@@ -21,7 +22,9 @@ export async function tryLlmBatchRoute(config: NaxConfig, stories: UserStory[],
   const logger = getSafeLogger();
   try {
     logger?.debug("routing", `LLM batch routing: ${label}`, { storyCount: stories.length, mode });
-    await llmRouteBatch(stories, { config });
+    const agentName = config.execution?.agent ?? "claude";
+    const adapter = getAgent(agentName);
+    await llmRouteBatch(stories, { config, adapter });
     logger?.debug("routing", "LLM batch routing complete", { label });
   } catch (err) {
     logger?.warn("routing", "LLM batch routing failed, falling back to individual routing", {