@nathapp/nax 0.19.0 → 0.21.0

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

@@ -0,0 +1,301 @@
+/**
+ * Deferred Regression Gate
+ *
+ * Runs full test suite once after all stories complete, then attempts
+ * targeted rectification per responsible story. Handles edge cases:
+ * - Partial completion: only check stories marked passed
+ * - Overlapping file changes: try last modified story first
+ * - Unmapped tests: warn and mark all passed stories for re-verification
+ */
+
+import type { NaxConfig } from "../../config";
+import { getSafeLogger } from "../../logger";
+import type { PRD, UserStory } from "../../prd";
+import { countStories } from "../../prd";
+import { hasCommitsForStory } from "../../utils/git";
+import { parseBunTestOutput } from "../../verification";
+import { reverseMapTestToSource } from "../../verification/smart-runner";
+import { runRectificationLoop } from "../post-verify-rectification";
+import { runVerification } from "../verification";
+
+/**
+ * Injectable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
+ * @internal - test use only.
+ */
+export const _regressionDeps = {
+  runVerification,
+  runRectificationLoop,
+  parseBunTestOutput,
+  reverseMapTestToSource,
+};
+
+export interface DeferredRegressionOptions {
+  config: NaxConfig;
+  prd: PRD;
+  workdir: string;
+}
+
+export interface DeferredRegressionResult {
+  success: boolean;
+  failedTests: number;
+  passedTests: number;
+  rectificationAttempts: number;
+  affectedStories: string[];
+}
+
+/**
+ * Map a test file to the story responsible for it via git log.
+ *
+ * Searches recent commits for story IDs in the format US-NNN.
+ * Returns the first matching story ID, or undefined if not found.
+ */
+async function findResponsibleStory(
+  testFile: string,
+  workdir: string,
+  passedStories: UserStory[],
+): Promise<UserStory | undefined> {
+  const logger = getSafeLogger();
+
+  // Try each passed story in reverse order (most recent first)
+  for (let i = passedStories.length - 1; i >= 0; i--) {
+    const story = passedStories[i];
+    const hasCommits = await hasCommitsForStory(workdir, story.id, 50);
+    if (hasCommits) {
+      logger?.info("regression", `Mapped test to story ${story.id}`, { testFile });
+      return story;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Run deferred regression gate after all stories complete.
+ *
+ * Steps:
+ * 1. Run full test suite
+ * 2. If failures, reverse-map test files to source files to stories
+ * 3. For each affected story, attempt targeted rectification
+ * 4. Re-run full suite to confirm fixes
+ * 5. Return results with affected story list
+ */
+export async function runDeferredRegression(options: DeferredRegressionOptions): Promise<DeferredRegressionResult> {
+  const logger = getSafeLogger();
+  const { config, prd, workdir } = options;
+
+  // Check if regression gate is deferred
+  const regressionMode = config.execution.regressionGate?.mode ?? "deferred";
+  if (regressionMode === "disabled") {
+    logger?.info("regression", "Deferred regression gate disabled");
+    return {
+      success: true,
+      failedTests: 0,
+      passedTests: 0,
+      rectificationAttempts: 0,
+      affectedStories: [],
+    };
+  }
+
+  if (regressionMode !== "deferred") {
+    logger?.info("regression", "Regression gate mode is not deferred, skipping");
+    return {
+      success: true,
+      failedTests: 0,
+      passedTests: 0,
+      rectificationAttempts: 0,
+      affectedStories: [],
+    };
+  }
+
+  const testCommand = config.quality.commands.test ?? "bun test";
+  const timeoutSeconds = config.execution.regressionGate?.timeoutSeconds ?? 120;
+  const maxRectificationAttempts = config.execution.regressionGate?.maxRectificationAttempts ?? 2;
+
+  // Only check stories that have been marked as passed
+  const counts = countStories(prd);
+  const passedStories = prd.userStories.filter((s) => s.status === "passed");
+
+  if (passedStories.length === 0) {
+    logger?.info("regression", "No passed stories to verify (partial completion)");
+    return {
+      success: true,
+      failedTests: 0,
+      passedTests: 0,
+      rectificationAttempts: 0,
+      affectedStories: [],
+    };
+  }
+
+  logger?.info("regression", "Running deferred full-suite regression gate", {
+    totalStories: counts.total,
+    passedStories: passedStories.length,
+  });
+
+  // Step 1: Run full test suite
+  const fullSuiteResult = await _regressionDeps.runVerification({
+    workingDirectory: workdir,
+    command: testCommand,
+    timeoutSeconds,
+    forceExit: config.quality.forceExit,
+    detectOpenHandles: config.quality.detectOpenHandles,
+    detectOpenHandlesRetries: config.quality.detectOpenHandlesRetries,
+    timeoutRetryCount: 0,
+    gracePeriodMs: config.quality.gracePeriodMs,
+    drainTimeoutMs: config.quality.drainTimeoutMs,
+    shell: config.quality.shell,
+    stripEnvVars: config.quality.stripEnvVars,
+  });
+
+  if (fullSuiteResult.success) {
+    logger?.info("regression", "Full suite passed");
+    return {
+      success: true,
+      failedTests: 0,
+      passedTests: fullSuiteResult.passCount ?? 0,
+      rectificationAttempts: 0,
+      affectedStories: [],
+    };
+  }
+
+  // Handle timeout
+  const acceptOnTimeout = config.execution.regressionGate?.acceptOnTimeout ?? true;
+  if (fullSuiteResult.status === "TIMEOUT" && acceptOnTimeout) {
+    logger?.warn("regression", "Full-suite regression gate timed out (accepted as pass)");
+    return {
+      success: true,
+      failedTests: 0,
+      passedTests: 0,
+      rectificationAttempts: 0,
+      affectedStories: [],
+    };
+  }
+
+  if (!fullSuiteResult.output) {
+    logger?.error("regression", "Full suite failed with no output");
+    return {
+      success: false,
+      failedTests: fullSuiteResult.failCount ?? 0,
+      passedTests: fullSuiteResult.passCount ?? 0,
+      rectificationAttempts: 0,
+      affectedStories: [],
+    };
+  }
+
+  // Step 2: Parse failures and map to source files to stories
+  const testSummary = _regressionDeps.parseBunTestOutput(fullSuiteResult.output);
+  const affectedStories = new Set<string>();
+  const affectedStoriesObjs = new Map<string, UserStory>();
+
+  logger?.warn("regression", "Regression detected", {
+    failedTests: testSummary.failed,
+    passedTests: testSummary.passed,
+  });
+
+  // Extract test file paths from failures
+  const testFilesInFailures = new Set<string>();
+  for (const failure of testSummary.failures) {
+    if (failure.file) {
+      testFilesInFailures.add(failure.file);
+    }
+  }
+
+  if (testFilesInFailures.size === 0) {
+    logger?.warn("regression", "No test files found in failures (unmapped)");
+    // Mark all passed stories for re-verification
+    for (const story of passedStories) {
+      affectedStories.add(story.id);
+      affectedStoriesObjs.set(story.id, story);
+    }
+  } else {
+    // Map test files to source files to stories
+    const testFilesArray = Array.from(testFilesInFailures);
+    const sourceFilesArray = _regressionDeps.reverseMapTestToSource(testFilesArray, workdir);
+
+    logger?.info("regression", "Mapped test files to source files", {
+      testFiles: testFilesArray.length,
+      sourceFiles: sourceFilesArray.length,
+    });
+
+    for (const testFile of testFilesArray) {
+      const responsibleStory = await findResponsibleStory(testFile, workdir, passedStories);
+      if (responsibleStory) {
+        affectedStories.add(responsibleStory.id);
+        affectedStoriesObjs.set(responsibleStory.id, responsibleStory);
+      } else {
+        logger?.warn("regression", "Could not map test file to story", { testFile });
+      }
+    }
+  }
+
+  if (affectedStories.size === 0) {
+    logger?.warn("regression", "No stories could be mapped to failures");
+    return {
+      success: false,
+      failedTests: testSummary.failed,
+      passedTests: testSummary.passed,
+      rectificationAttempts: 0,
+      affectedStories: Array.from(affectedStories),
+    };
+  }
+
+  // Step 3: Attempt rectification per story
+  let rectificationAttempts = 0;
+  const affectedStoriesList = Array.from(affectedStoriesObjs.values());
+
+  for (const story of affectedStoriesList) {
+    for (let attempt = 0; attempt < maxRectificationAttempts; attempt++) {
+      rectificationAttempts++;
+
+      logger?.info("regression", `Rectifying story ${story.id} (attempt ${attempt + 1}/${maxRectificationAttempts})`);
+
+      const fixed = await _regressionDeps.runRectificationLoop({
+        config,
+        workdir,
+        story,
+        testCommand,
+        timeoutSeconds,
+        testOutput: fullSuiteResult.output,
+        promptPrefix: `# DEFERRED REGRESSION: Full-Suite Failures\n\nYour story ${story.id} broke tests in the full suite. Fix these regressions.`,
+      });
+
+      if (fixed) {
+        logger?.info("regression", `Story ${story.id} rectified successfully`);
+        break; // Move to next story
+      }
+    }
+  }
+
+  // Step 4: Re-run full suite to confirm
+  logger?.info("regression", "Re-running full suite after rectification");
+  const retryResult = await _regressionDeps.runVerification({
+    workingDirectory: workdir,
+    command: testCommand,
+    timeoutSeconds,
+    forceExit: config.quality.forceExit,
+    detectOpenHandles: config.quality.detectOpenHandles,
+    detectOpenHandlesRetries: config.quality.detectOpenHandlesRetries,
+    timeoutRetryCount: 0,
+    gracePeriodMs: config.quality.gracePeriodMs,
+    drainTimeoutMs: config.quality.drainTimeoutMs,
+    shell: config.quality.shell,
+    stripEnvVars: config.quality.stripEnvVars,
+  });
+
+  const success = retryResult.success || (retryResult.status === "TIMEOUT" && acceptOnTimeout);
+
+  if (success) {
+    logger?.info("regression", "Deferred regression gate passed after rectification");
+  } else {
+    logger?.warn("regression", "Deferred regression gate still failing after rectification", {
+      remainingFailures: retryResult.failCount,
+    });
+  }
+
+  return {
+    success,
+    failedTests: retryResult.failCount ?? 0,
+    passedTests: retryResult.passCount ?? 0,
+    rectificationAttempts,
+    affectedStories: Array.from(affectedStories),
+  };
+}

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

@@ -83,7 +83,6 @@ export async function handlePipelineSuccess(
     storiesToExecute: ctx.storiesToExecute,
     allStoryMetrics: ctx.allStoryMetrics,
     timeoutRetryCountMap: ctx.timeoutRetryCountMap,
-    storyGitRef: ctx.storyGitRef ?? undefined,
   });
   const verificationPassed = verifyResult.passed;
   prd = verifyResult.prd;

package/src/execution/post-verify.ts

@@ -4,18 +4,15 @@
  * Runs verification after the agent completes, reverts story state on failure.
  */
 
-import { spawn } from "bun";
 import type { NaxConfig } from "../config";
 import { getSafeLogger } from "../logger";
 import type { StoryMetrics } from "../metrics";
 import type { PRD, StructuredFailure, UserStory, VerificationStage } from "../prd";
 import { getExpectedFiles, savePRD } from "../prd";
-import type { TestFailure, VerificationResult } from "../verification";
+import type { VerificationResult } from "../verification";
 import { parseBunTestOutput } from "../verification";
-import { getTierConfig } from "./escalation";
 import { revertStoriesOnFailure, runRectificationLoop } from "./post-verify-rectification";
-import { appendProgress } from "./progress";
-import { getEnvironmentalEscalationThreshold, parseTestOutput, runVerification } from "./verification";
+import { runVerification } from "./verification";
 
 /** Build a StructuredFailure from verification result and test output. */
 function buildStructuredFailure(
@@ -44,37 +41,6 @@ function buildStructuredFailure(
   };
 }
 
-/** Get test files changed since a git ref. Returns empty array if detection fails. */
-async function getChangedTestFiles(workdir: string, gitRef?: string): Promise<string[]> {
-  if (!gitRef) return [];
-  try {
-    const proc = spawn({
-      cmd: ["git", "diff", "--name-only", gitRef, "HEAD"],
-      cwd: workdir,
-      stdout: "pipe",
-      stderr: "pipe",
-    });
-    const exitCode = await proc.exited;
-    if (exitCode !== 0) return [];
-    const stdout = await new Response(proc.stdout).text();
-    return stdout
-      .trim()
-      .split("\n")
-      .filter(
-        (f) =>
-          f && (f.includes("test/") || f.includes("__tests__/") || f.endsWith(".test.ts") || f.endsWith(".spec.ts")),
-      );
-  } catch {
-    return [];
-  }
-}
-
-/** Scope a test command to only run specific test files. */
-function scopeTestCommand(baseCommand: string, testFiles: string[]): string {
-  if (testFiles.length === 0) return baseCommand;
-  return `${baseCommand} ${testFiles.join(" ")}`;
-}
-
 export interface PostVerifyOptions {
   config: NaxConfig;
   prd: PRD;
@@ -85,7 +51,6 @@ export interface PostVerifyOptions {
   storiesToExecute: UserStory[];
   allStoryMetrics: StoryMetrics[];
   timeoutRetryCountMap: Map<string, number>;
-  storyGitRef?: string;
 }
 
 export interface PostVerifyResult {
@@ -100,128 +65,38 @@ export interface PostVerifyResult {
  * not user/PRD input. No shell injection risk from untrusted sources.
  */
 export async function runPostAgentVerification(opts: PostVerifyOptions): Promise<PostVerifyResult> {
-  const {
-    config,
-    prd,
-    prdPath,
-    workdir,
-    featureDir,
-    story,
-    storiesToExecute,
-    allStoryMetrics,
-    timeoutRetryCountMap,
-    storyGitRef,
-  } = opts;
-  const logger = getSafeLogger();
+  const { config, prd, prdPath, workdir, featureDir, story, storiesToExecute, allStoryMetrics } = opts;
 
   if (!config.quality.commands.test) return { passed: true, prd };
 
-  // Scoped verification: only run test files changed by this story
-  const changedTestFiles = await getChangedTestFiles(workdir, storyGitRef);
-  const testCommand = scopeTestCommand(config.quality.commands.test, changedTestFiles);
-  const timeoutRetryCount = timeoutRetryCountMap.get(story.id) || 0;
-
-  const verificationResult = await _postVerifyDeps.runVerification({
-    workingDirectory: workdir,
-    expectedFiles: _postVerifyDeps.getExpectedFiles(story),
-    command: testCommand,
-    timeoutSeconds: config.execution.verificationTimeoutSeconds,
-    forceExit: config.quality.forceExit,
-    detectOpenHandles: config.quality.detectOpenHandles,
-    detectOpenHandlesRetries: config.quality.detectOpenHandlesRetries,
-    timeoutRetryCount,
-    gracePeriodMs: config.quality.gracePeriodMs,
-    drainTimeoutMs: config.quality.drainTimeoutMs,
-    shell: config.quality.shell,
-    stripEnvVars: config.quality.stripEnvVars,
-  });
-
   const rectificationEnabled = config.execution.rectification?.enabled ?? false;
+  const regressionMode = config.execution.regressionGate?.mode;
 
-  if (verificationResult.success) {
-    logger?.info("verification", "Scoped verification passed");
-    if (verificationResult.output) {
-      const analysis = _postVerifyDeps.parseTestOutput(verificationResult.output, 0);
-      if (analysis.passCount > 0) {
-        logger?.debug("verification", "Scoped test results", {
-          passCount: analysis.passCount,
-          failCount: analysis.failCount,
-        });
-      }
-    }
-
-    // Regression Gate (BUG-009): run full suite after scoped tests pass
-    const regressionGateResult = await runRegressionGate(
-      config,
-      workdir,
-      story,
-      changedTestFiles,
-      rectificationEnabled,
-    );
-    if (regressionGateResult.status === "passed" || regressionGateResult.status === "skipped") {
-      return { passed: true, prd };
-    }
-
-    // Regression failed -- build StructuredFailure and revert stories
-    // verificationResult is always set when status === "failed" (see RegressionGateResult)
-    const regressionVerificationResult = regressionGateResult.verificationResult ?? {
-      status: "TEST_FAILURE" as const,
-      success: false,
-      countsTowardEscalation: true,
-    };
-    const regressionFailure = buildStructuredFailure(
-      story,
-      "regression",
-      regressionVerificationResult,
-      "Full-suite regression detected",
-    );
-    const updatedPrd = await _postVerifyDeps.revertStoriesOnFailure({
-      prd,
-      prdPath,
-      story,
-      storiesToExecute,
-      allStoryMetrics,
-      featureDir,
-      diagnosticContext: "REGRESSION: full-suite regression detected",
-      countsTowardEscalation: true,
-      priorFailure: regressionFailure,
-    });
-    return { passed: false, prd: updatedPrd };
-  }
-
-  // --- Verification failed ---
-  // Attempt rectification if enabled and tests failed (not timeout/env)
-  const isTestFailure = verificationResult.status === "TEST_FAILURE" && verificationResult.output;
-  if (rectificationEnabled && isTestFailure && verificationResult.output) {
-    const fixed = await _postVerifyDeps.runRectificationLoop({
-      config,
-      workdir,
-      story,
-      testCommand,
-      timeoutSeconds: config.execution.verificationTimeoutSeconds,
-      testOutput: verificationResult.output,
-    });
-    if (fixed) return { passed: true, prd };
-  }
-
-  // Track timeout retries for --detectOpenHandles escalation
-  if (verificationResult.status === "TIMEOUT") {
-    timeoutRetryCountMap.set(story.id, timeoutRetryCount + 1);
+  // Skip per-story regression gate only when explicitly set to deferred
+  if (regressionMode === "deferred") {
+    return { passed: true, prd };
   }
 
-  logger?.warn("verification", `Verification ${verificationResult.status}`, {
-    status: verificationResult.status,
-    error: verificationResult.error?.split("\n")[0],
-  });
+  // Run full-suite regression gate (per-story mode)
+  const regressionGateResult = await runRegressionGate(config, workdir, story, rectificationEnabled);
 
-  // Handle environmental failure escalation
-  if (verificationResult.countsTowardEscalation && verificationResult.status === "ENVIRONMENTAL_FAILURE") {
-    checkEnvironmentalEscalation(config, story, prd, logger);
+  if (regressionGateResult.status === "passed" || regressionGateResult.status === "skipped") {
+    return { passed: true, prd };
   }
 
-  // Revert stories and save
-  const diagnosticContext = verificationResult.error || `Verification failed: ${verificationResult.status}`;
-  const verifyFailure = buildStructuredFailure(story, "verify", verificationResult, diagnosticContext);
+  // Regression failed -- build StructuredFailure and revert stories
+  // verificationResult is always set when status === "failed" (see RegressionGateResult)
+  const regressionVerificationResult = regressionGateResult.verificationResult ?? {
+    status: "TEST_FAILURE" as const,
+    success: false,
+    countsTowardEscalation: true,
+  };
+  const regressionFailure = buildStructuredFailure(
+    story,
+    "regression",
+    regressionVerificationResult,
+    "Full-suite regression detected",
+  );
   const updatedPrd = await _postVerifyDeps.revertStoriesOnFailure({
     prd,
     prdPath,
@@ -229,11 +104,10 @@ export async function runPostAgentVerification(opts: PostVerifyOptions): Promise
     storiesToExecute,
     allStoryMetrics,
     featureDir,
-    diagnosticContext,
-    countsTowardEscalation: verificationResult.countsTowardEscalation ?? false,
-    priorFailure: verifyFailure,
+    diagnosticContext: "REGRESSION: full-suite regression detected",
+    countsTowardEscalation: true,
+    priorFailure: regressionFailure,
   });
-
   return { passed: false, prd: updatedPrd };
 }
 
@@ -242,22 +116,17 @@ interface RegressionGateResult {
   verificationResult?: VerificationResult;
 }
 
-/** Run regression gate (full suite) after scoped tests pass. */
+/** Run full-suite regression gate. */
 async function runRegressionGate(
   config: NaxConfig,
   workdir: string,
   story: UserStory,
-  changedTestFiles: string[],
   rectificationEnabled: boolean,
 ): Promise<RegressionGateResult> {
   const logger = getSafeLogger();
   const regressionGateEnabled = config.execution.regressionGate?.enabled ?? true;
-  const scopedTestsWereRun = changedTestFiles.length > 0;
 
-  if (!regressionGateEnabled || !scopedTestsWereRun) {
-    if (regressionGateEnabled && !scopedTestsWereRun) {
-      logger?.debug("regression-gate", "Skipping regression gate (full suite already run in scoped verification)");
-    }
+  if (!regressionGateEnabled) {
     return { status: "skipped" };
   }
 
@@ -286,9 +155,7 @@ async function runRegressionGate(
   // Handle timeout: accept as pass if configured (BUG-026)
   const acceptOnTimeout = config.execution.regressionGate?.acceptOnTimeout ?? true;
   if (regressionResult.status === "TIMEOUT" && acceptOnTimeout) {
-    logger?.warn("regression-gate", "[BUG-026] Full-suite regression gate timed out (accepted as pass)", {
-      reason: "Timeout is not evidence of regression — scoped verification already passed",
-    });
+    logger?.warn("regression-gate", "[BUG-026] Full-suite regression gate timed out (accepted as pass)");
     return { status: "passed" };
   }
 
@@ -305,7 +172,7 @@ async function runRegressionGate(
       timeoutSeconds: config.execution.regressionGate.timeoutSeconds,
       testOutput: regressionResult.output,
       promptPrefix:
-        "# REGRESSION: Cross-Story Test Failures\n\nYour changes passed scoped tests but broke unrelated tests. Fix these regressions.",
+        "# REGRESSION: Full-Suite Test Failures\n\nYour changes broke tests in the full suite. Fix these regressions.",
     });
     if (fixed) return { status: "passed" };
   }
@@ -313,44 +180,14 @@ async function runRegressionGate(
   return { status: "failed", verificationResult: regressionResult };
 }
 
-/** Check if environmental failure should trigger early escalation. */
-function checkEnvironmentalEscalation(
-  config: NaxConfig,
-  story: UserStory,
-  prd: PRD,
-  logger: ReturnType<typeof getSafeLogger>,
-): void {
-  const currentTier = story.routing?.modelTier || config.autoMode.escalation.tierOrder[0]?.tier;
-  const tierCfg = currentTier
-    ? _postVerifyDeps.getTierConfig(currentTier, config.autoMode.escalation.tierOrder)
-    : undefined;
-  if (!tierCfg) return;
-
-  const threshold = _postVerifyDeps.getEnvironmentalEscalationThreshold(
-    tierCfg.attempts,
-    config.quality.environmentalEscalationDivisor,
-  );
-  const currentAttempts = prd.userStories.find((s) => s.id === story.id)?.attempts ?? 0;
-  if (currentAttempts >= threshold) {
-    logger?.warn("verification", "Environmental failure hit early escalation threshold", {
-      currentAttempts,
-      threshold,
-    });
-  }
-}
-
 /**
  * Swappable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
  */
 export const _postVerifyDeps = {
   parseBunTestOutput,
-  parseTestOutput,
   runVerification,
   getExpectedFiles,
   savePRD,
   revertStoriesOnFailure,
   runRectificationLoop,
-  appendProgress,
-  getTierConfig,
-  getEnvironmentalEscalationThreshold,
 };

package/src/execution/runner.ts

@@ -299,6 +299,7 @@ export async function run(options: RunOptions): Promise<RunResult> {
       startTime,
       workdir,
       statusWriter,
+      config,
     });
 
     const { durationMs, runCompletedAt, finalCounts } = completionResult;

package/src/execution/sequential-executor.ts

@@ -271,6 +271,7 @@ export async function executeSequential(
         hooks: ctx.hooks,
         plugins: ctx.pluginRegistry,
         storyStartTime,
+        storyGitRef: storyGitRef ?? undefined, // FEAT-010: per-attempt baseRef for precise smart-runner diff
         interaction: ctx.interactionChain ?? undefined,
       };