@nathapp/nax 0.32.2 → 0.34.0

package/src/execution/lifecycle/run-completion.ts

@@ -9,9 +9,12 @@
  */
 
 import type { NaxConfig } from "../../config";
+import { fireHook } from "../../hooks/runner";
+import type { HooksConfig } from "../../hooks/types";
 import { getSafeLogger } from "../../logger";
 import type { StoryMetrics } from "../../metrics";
 import { saveRunMetrics } from "../../metrics";
+import { pipelineEventBus } from "../../pipeline/event-bus";
 import { countStories, isComplete, isStalled } from "../../prd";
 import type { PRD } from "../../prd";
 import type { StatusWriter } from "../status-writer";
@@ -23,6 +26,7 @@ import { runDeferredRegression } from "./run-regression";
  */
 export const _runCompletionDeps = {
   runDeferredRegression,
+  fireHook,
 };
 
 export interface RunCompletionOptions {
@@ -38,6 +42,9 @@ export interface RunCompletionOptions {
   workdir: string;
   statusWriter: StatusWriter;
   config: NaxConfig;
+  hooksConfig?: HooksConfig;
+  /** Whether the run used sequential (non-parallel) execution. Defaults to true. */
+  isSequential?: boolean;
 }
 
 export interface RunCompletionResult {
@@ -52,6 +59,32 @@ export interface RunCompletionResult {
   };
 }
 
+/**
+ * Check if deferred regression should be skipped (RL-006).
+ *
+ * Smart-skip applies when:
+ * 1. All stories have fullSuiteGatePassed === true
+ * 2. Execution is sequential (or defaults to sequential when not specified)
+ * 3. There is at least one story metric
+ */
+function shouldSkipDeferredRegression(allStoryMetrics: StoryMetrics[], isSequential: boolean | undefined): boolean {
+  // Default to sequential mode
+  const effectiveSequential = isSequential !== false;
+
+  // Must be sequential mode
+  if (!effectiveSequential) {
+    return false;
+  }
+
+  // Must have at least one story metric
+  if (allStoryMetrics.length === 0) {
+    return false;
+  }
+
+  // All stories must have fullSuiteGatePassed === true
+  return allStoryMetrics.every((m) => m.fullSuiteGatePassed === true);
+}
+
 /**
  * Handle final run completion: save metrics, log summary, update status
  */
@@ -70,28 +103,77 @@ export async function handleRunCompletion(options: RunCompletionOptions): Promis
     workdir,
     statusWriter,
     config,
+    hooksConfig,
+    isSequential,
   } = options;
 
   // Run deferred regression gate before final metrics
   const regressionMode = config.execution.regressionGate?.mode;
   if (regressionMode === "deferred" && config.quality.commands.test) {
-    const regressionResult = await _runCompletionDeps.runDeferredRegression({
-      config,
-      prd,
-      workdir,
-    });
-
-    logger?.info("regression", "Deferred regression gate completed", {
-      success: regressionResult.success,
-      failedTests: regressionResult.failedTests,
-      affectedStories: regressionResult.affectedStories,
-    });
+    if (shouldSkipDeferredRegression(allStoryMetrics, isSequential)) {
+      logger?.info(
+        "regression",
+        "Smart-skip: skipping deferred regression (all stories passed full-suite gate in sequential mode)",
+      );
+    } else {
+      const regressionResult = await _runCompletionDeps.runDeferredRegression({
+        config,
+        prd,
+        workdir,
+      });
+
+      logger?.info("regression", "Deferred regression gate completed", {
+        success: regressionResult.success,
+        failedTests: regressionResult.failedTests,
+        affectedStories: regressionResult.affectedStories,
+      });
+
+      if (!regressionResult.success) {
+        // Mark affected stories as regression-failed (RL-004)
+        for (const storyId of regressionResult.affectedStories) {
+          const story = prd.userStories.find((s) => s.id === storyId);
+          if (story) {
+            story.status = "regression-failed";
+          }
+        }
+        // Reflect regression gate failure in run status (RL-004)
+        statusWriter.setRunStatus("failed");
+
+        if (hooksConfig) {
+          await _runCompletionDeps.fireHook(
+            hooksConfig as import("../../hooks/runner").LoadedHooksConfig,
+            "on-final-regression-fail",
+            {
+              event: "on-final-regression-fail",
+              feature,
+              status: "failed",
+              failedTests: regressionResult.failedTests,
+              affectedStories: regressionResult.affectedStories,
+            },
+            workdir,
+          );
+        }
+      }
+    }
   }
 
   const durationMs = Date.now() - startTime;
   const runCompletedAt = new Date().toISOString();
 
-  // Save run metrics
+  // Compute final story counts before emitting completion event (RL-002)
+  const finalCounts = countStories(prd);
+
+  // Emit run:completed after regression gate with real story counts (RL-002)
+  pipelineEventBus.emit({
+    type: "run:completed",
+    totalStories: finalCounts.total,
+    passedStories: finalCounts.passed,
+    failedStories: finalCounts.failed,
+    durationMs,
+    totalCost,
+  });
+
+  // Save run metrics (best-effort — disk write errors do not fail the run)
   const runMetrics = {
     runId,
     feature,
@@ -100,15 +182,18 @@ export async function handleRunCompletion(options: RunCompletionOptions): Promis
     totalCost,
     totalStories: allStoryMetrics.length,
     storiesCompleted,
-    storiesFailed: countStories(prd).failed,
+    storiesFailed: finalCounts.failed,
     totalDurationMs: durationMs,
     stories: allStoryMetrics,
   };
 
-  await saveRunMetrics(workdir, runMetrics);
+  try {
+    await saveRunMetrics(workdir, runMetrics);
+  } catch (err) {
+    logger?.warn("run.complete", "Failed to save run metrics", { error: String(err) });
+  }
 
   // Log run completion
-  const finalCounts = countStories(prd);
 
   // Prepare per-story metrics summary
   const storyMetricsSummary = allStoryMetrics.map((sm) => ({

package/src/execution/parallel-executor.ts

@@ -22,6 +22,14 @@ import { getAllReadyStories, hookCtx } from "./helpers";
 import { executeParallel } from "./parallel";
 import type { StatusWriter } from "./status-writer";
 
+/**
+ * Injectable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
+ * @internal - test use only.
+ */
+export const _parallelExecutorDeps = {
+  fireHook,
+};
+
 export interface ParallelExecutorOptions {
   prdPath: string;
   workdir: string;
@@ -158,7 +166,18 @@ export async function runParallelExecution(
       feature,
       totalCost,
     });
-    await fireHook(hooks, "on-complete", hookCtx(feature, { status: "complete", cost: totalCost }), workdir);
+    await _parallelExecutorDeps.fireHook(
+      hooks,
+      "on-all-stories-complete",
+      hookCtx(feature, { status: "passed", cost: totalCost }),
+      workdir,
+    );
+    await _parallelExecutorDeps.fireHook(
+      hooks,
+      "on-complete",
+      hookCtx(feature, { status: "complete", cost: totalCost }),
+      workdir,
+    );
 
     // Skip to metrics and cleanup
     const durationMs = Date.now() - startTime;

package/src/execution/pipeline-result-handler.ts

@@ -39,6 +39,7 @@ export interface PipelineHandlerContext {
   allStoryMetrics: StoryMetrics[];
   storyGitRef: string | null | undefined;
   interactionChain?: InteractionChain | null;
+  storyStartTime?: number;
 }
 
 export interface PipelineSuccessResult {
@@ -62,11 +63,13 @@ export async function handlePipelineSuccess(
 
   const storiesCompletedDelta = ctx.storiesToExecute.length;
   for (const completedStory of ctx.storiesToExecute) {
+    const now = Date.now();
     logger?.info("story.complete", "Story completed successfully", {
       storyId: completedStory.id,
       storyTitle: completedStory.title,
       totalCost: ctx.totalCost + costDelta,
-      durationMs: Date.now() - ctx.startTime,
+      durationMs: now - ctx.startTime,
+      storyDurationMs: ctx.storyStartTime ? now - ctx.storyStartTime : undefined,
     });
 
     pipelineEventBus.emit({
@@ -90,6 +93,7 @@ export async function handlePipelineSuccess(
     totalCost: ctx.totalCost + costDelta,
     costLimit: ctx.config.execution.costLimit,
     elapsedMs: Date.now() - ctx.startTime,
+    storyDurationMs: ctx.storyStartTime ? Date.now() - ctx.storyStartTime : undefined,
   });
 
   return { storiesCompletedDelta, costDelta, prd, prdDirty: true };

package/src/execution/runner.ts

@@ -10,6 +10,7 @@
 
 import type { NaxConfig } from "../config";
 import type { LoadedHooksConfig } from "../hooks";
+import { fireHook } from "../hooks";
 import { getSafeLogger } from "../logger";
 import type { StoryMetrics } from "../metrics";
 import type { PipelineEventEmitter } from "../pipeline/events";
@@ -20,6 +21,15 @@ import { clearCache as clearLlmCache, routeBatch as llmRouteBatch } from "../rou
 import { precomputeBatchPlan } from "./batching";
 import { stopHeartbeat, writeExitSummary } from "./crash-recovery";
 import { getAllReadyStories } from "./helpers";
+import { hookCtx } from "./story-context";
+
+/**
+ * Injectable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
+ * @internal - test use only.
+ */
+export const _runnerDeps = {
+  fireHook,
+};
 
 // Re-export for backward compatibility
 export { resolveMaxAttemptsOutcome } from "./escalation";
@@ -289,6 +299,16 @@ export async function run(options: RunOptions): Promise<RunResult> {
       storiesCompleted = acceptanceResult.storiesCompleted;
     }
 
+    // Fire on-all-stories-complete before regression gate (RL-001)
+    if (isComplete(prd)) {
+      await _runnerDeps.fireHook(
+        hooks,
+        "on-all-stories-complete",
+        hookCtx(feature, { status: "passed", cost: totalCost }),
+        workdir,
+      );
+    }
+
     // Handle run completion: save metrics, log summary, update status
     const { handleRunCompletion } = await import("./lifecycle/run-completion");
     const completionResult = await handleRunCompletion({

package/src/execution/sequential-executor.ts

@@ -14,7 +14,7 @@ import { wireReporters } from "../pipeline/subscribers/reporters";
 import type { PipelineContext } from "../pipeline/types";
 import { generateHumanHaltSummary, isComplete, isStalled, loadPRD } from "../prd";
 import type { PRD } from "../prd/types";
-import { startHeartbeat, stopHeartbeat, writeExitSummary } from "./crash-recovery";
+import { startHeartbeat } from "./crash-recovery";
 import type { SequentialExecutionContext, SequentialExecutionResult } from "./executor-types";
 import { runIteration } from "./iteration-runner";
 import { selectNextStories } from "./story-selector";
@@ -82,14 +82,6 @@ export async function executeSequential(
             return buildResult("pre-merge-aborted");
           }
         }
-        pipelineEventBus.emit({
-          type: "run:completed",
-          totalStories: 0,
-          passedStories: 0,
-          failedStories: 0,
-          durationMs: Date.now() - ctx.startTime,
-          totalCost,
-        });
         return buildResult("completed");
       }
 
@@ -181,7 +173,6 @@ export async function executeSequential(
 
     return buildResult("max-iterations");
   } finally {
-    stopHeartbeat();
-    writeExitSummary(ctx.logFilePath, totalCost, iterations, storiesCompleted, Date.now() - ctx.startTime);
+    // Cleanup moved to runner.ts (RL-007): exit summary and heartbeat stop are owned by runner
   }
 }

package/src/hooks/types.ts

@@ -4,17 +4,23 @@
  * Script-based lifecycle hooks configured via hooks.json.
  */
 
+/** All supported hook events — runtime array used for validation */
+export const HOOK_EVENTS = [
+  "on-start",
+  "on-story-start",
+  "on-story-complete",
+  "on-story-fail",
+  "on-pause",
+  "on-resume",
+  "on-session-end",
+  "on-all-stories-complete",
+  "on-complete",
+  "on-error",
+  "on-final-regression-fail",
+] as const;
+
 /** All supported hook events */
-export type HookEvent =
-  | "on-start"
-  | "on-story-start"
-  | "on-story-complete"
-  | "on-story-fail"
-  | "on-pause"
-  | "on-resume"
-  | "on-session-end"
-  | "on-complete"
-  | "on-error";
+export type HookEvent = (typeof HOOK_EVENTS)[number];
 
 /** Single hook definition */
 export interface HookDef {
@@ -64,4 +70,8 @@ export interface HookContext {
   agent?: string;
   /** Current iteration number */
   iteration?: number;
+  /** Number of failed tests (on-final-regression-fail) */
+  failedTests?: number;
+  /** Stories affected by regression failure (on-final-regression-fail) */
+  affectedStories?: string[];
 }

package/src/interaction/index.ts

@@ -53,6 +53,7 @@ export {
   checkPreMerge,
   checkStoryAmbiguity,
   checkReviewGate,
+  checkStoryOversized,
 } from "./triggers";
 export type { TriggerContext } from "./triggers";
 

package/src/interaction/triggers.ts

@@ -227,3 +227,24 @@ export async function checkReviewGate(
   const response = await executeTrigger("review-gate", context, config, chain);
   return response.action === "approve";
 }
+
+/**
+ * Check story-oversized trigger (decompose, skip, or continue)
+ */
+export async function checkStoryOversized(
+  context: TriggerContext,
+  config: NaxConfig,
+  chain: InteractionChain,
+): Promise<"decompose" | "skip" | "continue"> {
+  if (!isTriggerEnabled("story-oversized", config)) return "continue";
+
+  try {
+    const response = await executeTrigger("story-oversized", context, config, chain);
+    if (response.action === "approve") return "decompose";
+    if (response.action === "skip") return "skip";
+    return "continue";
+  } catch {
+    // No plugin registered or all plugins failed — apply default fallback
+    return "continue";
+  }
+}

package/src/interaction/types.ts

@@ -83,6 +83,7 @@ export type TriggerName =
   | "max-retries" // skip (yellow) — max retries reached
   | "pre-merge" // escalate (yellow) — before merging to main
   | "human-review" // skip (yellow) — human review required on max retries / critical failure
+  | "story-oversized" // continue (yellow) — story has too many acceptance criteria
   | "story-ambiguity" // continue (green) — story requirements unclear
   | "review-gate"; // continue (green) — code review checkpoint
 
@@ -150,6 +151,12 @@ export const TRIGGER_METADATA: Record<TriggerName, TriggerMetadata> = {
     safety: "yellow",
     defaultSummary: "Human review required for story {{storyId}} — skip and continue?",
   },
+  "story-oversized": {
+    defaultFallback: "continue",
+    safety: "yellow",
+    defaultSummary:
+      "Story {{storyId}} is oversized ({{criteriaCount}} acceptance criteria) — decompose into smaller stories?",
+  },
   "story-ambiguity": {
     defaultFallback: "continue",
     safety: "green",

package/src/metrics/tracker.ts

@@ -62,6 +62,11 @@ export function collectStoryMetrics(ctx: PipelineContext, storyStartTime: string
   // fall back to routing.complexity for backward compat
   const initialComplexity = story.routing?.initialComplexity ?? routing.complexity;
 
+  // fullSuiteGatePassed: true only for TDD strategies when gate passes
+  const isTddStrategy =
+    routing.testStrategy === "three-session-tdd" || routing.testStrategy === "three-session-tdd-lite";
+  const fullSuiteGatePassed = isTddStrategy ? (ctx.fullSuiteGatePassed ?? false) : false;
+
   return {
     storyId: story.id,
     complexity: routing.complexity,
@@ -76,6 +81,7 @@ export function collectStoryMetrics(ctx: PipelineContext, storyStartTime: string
     firstPassSuccess,
     startedAt: storyStartTime,
     completedAt: new Date().toISOString(),
+    fullSuiteGatePassed,
   };
 }
 
@@ -132,6 +138,7 @@ export function collectBatchMetrics(ctx: PipelineContext, storyStartTime: string
       firstPassSuccess: true, // batch = first pass success
       startedAt: storyStartTime,
       completedAt: new Date().toISOString(),
+      fullSuiteGatePassed: false, // batches are not TDD-gated
     };
   });
 }

package/src/metrics/types.ts

@@ -34,6 +34,8 @@ export interface StoryMetrics {
   startedAt: string;
   /** Timestamp when completed */
   completedAt: string;
+  /** Whether TDD full-suite gate passed (only true for TDD strategies when gate passes) */
+  fullSuiteGatePassed?: boolean;
 }
 
 /**

package/src/pipeline/stages/review.ts

@@ -30,6 +30,12 @@ export const reviewStage: PipelineStage = {
     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", ctx.config)) {

package/src/pipeline/stages/routing.ts

@@ -8,8 +8,13 @@
  * RRP-003: contentHash staleness detection — if story.routing.contentHash is missing or
  * does not match the current story content, treats cached routing as a miss and re-classifies.
  *
+ * SD-004: Oversized story detection — after routing, checks if story exceeds
+ * config.decompose.maxAcceptanceCriteria with complex/expert complexity. Decomposes
+ * based on trigger mode (auto / confirm / disabled).
+ *
  * @returns
  * - `continue`: Routing determined, proceed to next stage
+ * - `skip`: Story was decomposed into substories; runner should pick up first substory
  *
  * @example
  * ```ts
@@ -20,13 +25,42 @@
  * ```
  */
 
+import type { NaxConfig } from "../../config";
 import { isGreenfieldStory } from "../../context/greenfield";
+import { applyDecomposition } from "../../decompose/apply";
+import { DecomposeBuilder } from "../../decompose/builder";
+import type { DecomposeConfig as BuilderDecomposeConfig, DecomposeResult } from "../../decompose/types";
+import { checkStoryOversized } from "../../interaction/triggers";
 import { getLogger } from "../../logger";
 import { savePRD } from "../../prd";
+import type { PRD, UserStory } from "../../prd";
 import { complexityToModelTier, computeStoryContentHash, routeStory } from "../../routing";
 import { clearCache, routeBatch } from "../../routing/strategies/llm";
 import type { PipelineContext, PipelineStage, RoutingResult, StageResult } from "../types";
 
+/**
+ * Run story decomposition using DecomposeBuilder.
+ * Used as the default implementation in _routingDeps.runDecompose.
+ * In production, replace with an LLM-backed adapter.
+ */
+async function runDecompose(story: UserStory, prd: PRD, config: NaxConfig, _workdir: string): Promise<DecomposeResult> {
+  const naxDecompose = config.decompose;
+  const builderConfig: BuilderDecomposeConfig = {
+    maxSubStories: naxDecompose?.maxSubstories ?? 5,
+    maxComplexity: naxDecompose?.maxSubstoryComplexity ?? "medium",
+    maxRetries: naxDecompose?.maxRetries ?? 2,
+  };
+
+  // Stub adapter — replaced in tests via _routingDeps injection.
+  const adapter = {
+    async decompose(_prompt: string): Promise<string> {
+      throw new Error("[decompose] No LLM adapter configured for story decomposition");
+    },
+  };
+
+  return DecomposeBuilder.for(story).prd(prd).config(builderConfig).decompose(adapter);
+}
+
 export const routingStage: PipelineStage = {
   name: "routing",
   enabled: () => true,
@@ -116,6 +150,58 @@ export const routingStage: PipelineStage = {
       logger.debug("routing", ctx.routing.reasoning);
     }
 
+    // SD-004: Oversized story detection and decomposition
+    const decomposeConfig = ctx.config.decompose;
+    if (decomposeConfig) {
+      const acCount = ctx.story.acceptanceCriteria.length;
+      const complexity = ctx.routing.complexity;
+      const isOversized =
+        acCount > decomposeConfig.maxAcceptanceCriteria && (complexity === "complex" || complexity === "expert");
+
+      if (isOversized) {
+        if (decomposeConfig.trigger === "disabled") {
+          logger.warn(
+            "routing",
+            `Story ${ctx.story.id} is oversized (${acCount} ACs) but decompose is disabled — continuing with original`,
+          );
+        } else if (decomposeConfig.trigger === "auto") {
+          const result = await _routingDeps.runDecompose(ctx.story, ctx.prd, ctx.config, ctx.workdir);
+          if (result.validation.valid) {
+            _routingDeps.applyDecomposition(ctx.prd, result);
+            if (ctx.prdPath) {
+              await _routingDeps.savePRD(ctx.prd, ctx.prdPath);
+            }
+            logger.info("routing", `Story ${ctx.story.id} decomposed into ${result.subStories.length} substories`);
+            return { action: "skip", reason: `Decomposed into ${result.subStories.length} substories` };
+          }
+          logger.warn("routing", `Story ${ctx.story.id} decompose failed after retries — continuing with original`, {
+            errors: result.validation.errors,
+          });
+        } else if (decomposeConfig.trigger === "confirm") {
+          const action = await _routingDeps.checkStoryOversized(
+            { featureName: ctx.prd.feature, storyId: ctx.story.id, criteriaCount: acCount },
+            ctx.config,
+            // biome-ignore lint/style/noNonNullAssertion: confirm mode is only reached when interaction chain is present in production; tests mock checkStoryOversized directly
+            ctx.interaction!,
+          );
+          if (action === "decompose") {
+            const result = await _routingDeps.runDecompose(ctx.story, ctx.prd, ctx.config, ctx.workdir);
+            if (result.validation.valid) {
+              _routingDeps.applyDecomposition(ctx.prd, result);
+              if (ctx.prdPath) {
+                await _routingDeps.savePRD(ctx.prd, ctx.prdPath);
+              }
+              logger.info("routing", `Story ${ctx.story.id} decomposed into ${result.subStories.length} substories`);
+              return { action: "skip", reason: `Decomposed into ${result.subStories.length} substories` };
+            }
+            logger.warn("routing", `Story ${ctx.story.id} decompose failed after retries — continuing with original`, {
+              errors: result.validation.errors,
+            });
+          }
+        }
+      }
+    }
+
     return { action: "continue" };
   },
 };
@@ -131,4 +217,7 @@ export const _routingDeps = {
   clearCache,
   savePRD,
   computeStoryContentHash,
+  applyDecomposition,
+  runDecompose,
+  checkStoryOversized,
 };

package/src/pipeline/types.ts

@@ -110,6 +110,8 @@ export interface PipelineContext {
   tddFailureCategory?: FailureCategory;
   /** Set to true when TDD full-suite gate already passed — verify stage skips to avoid redundant run (BUG-054) */
   fullSuiteGatePassed?: boolean;
+  /** Structured review findings from plugin reviewers — passed to escalation for retry context */
+  reviewFindings?: import("../plugins/types").ReviewFinding[];
 }
 
 /**

package/src/plugins/types.ts

@@ -119,6 +119,37 @@ export type { IPromptOptimizer } from "../optimizer/types";
 // Review Extension
 // ============================================================================
 
+/**
+ * A single structured finding from a review check.
+ *
+ * Designed to be service-agnostic — works with Semgrep, ESLint, SonarQube,
+ * Snyk, CodeQL, and other SAST/DAST/linting tools.
+ */
+export interface ReviewFinding {
+  /** Rule or check ID (e.g., "detect-non-literal-regexp", "no-unused-vars") */
+  ruleId: string;
+  /** Severity level (tool-agnostic scale) */
+  severity: "critical" | "error" | "warning" | "info" | "low";
+  /** File path (relative to workdir) */
+  file: string;
+  /** Line number (1-indexed) */
+  line: number;
+  /** Column number (1-indexed, optional) */
+  column?: number;
+  /** End line number (optional, for multi-line findings) */
+  endLine?: number;
+  /** End column number (optional) */
+  endColumn?: number;
+  /** Human-readable message */
+  message: string;
+  /** Optional URL for rule documentation or details */
+  url?: string;
+  /** Source tool that produced this finding (e.g., "semgrep", "eslint", "snyk") */
+  source?: string;
+  /** Finding category (e.g., "security", "performance", "style", "bug") */
+  category?: string;
+}
+
 /**
  * Result from a review check.
  */
@@ -129,6 +160,8 @@ export interface ReviewCheckResult {
   output: string;
   /** Exit code from the check process (if applicable) */
   exitCode?: number;
+  /** Structured findings (optional — plugins can provide machine-readable results) */
+  findings?: ReviewFinding[];
 }
 
 /**