@nathapp/nax 0.50.2 → 0.51.0

package/src/pipeline/stages/routing.ts

@@ -1,276 +0,0 @@
-/**
- * Routing Stage
- *
- * Classifies story complexity and determines model tier + test strategy.
- * Uses cached complexity/testStrategy/modelTier from story if contentHash matches.
- * modelTier: uses escalated tier if explicitly set (BUG-032), otherwise derives from config.
- *
- * 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
- * // Story has cached routing with matching contentHash
- * await routingStage.execute(ctx);
- * // ctx.routing: { complexity: "simple", modelTier: "fast", testStrategy: "test-after", reasoning: "..." }
- * // modelTier is derived from current config.autoMode.complexityRouting
- * ```
- */
-
-import { join } from "node:path";
-import { getAgent } from "../../agents/registry";
-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,
-  agentGetFn?: import("../types").AgentGetFn,
-): Promise<DecomposeResult> {
-  const naxDecompose = config.decompose;
-  const builderConfig: BuilderDecomposeConfig = {
-    maxSubStories: naxDecompose?.maxSubstories ?? 5,
-    maxComplexity: naxDecompose?.maxSubstoryComplexity ?? "medium",
-    maxRetries: naxDecompose?.maxRetries ?? 2,
-  };
-
-  // Resolve the default agent adapter for LLM-backed decompose.
-  // Falls back to agent.complete() with JSON mode — works with both CLI and ACP adapters.
-  const agent = (agentGetFn ?? getAgent)(config.autoMode.defaultAgent);
-  if (!agent) {
-    throw new Error(`[decompose] Agent "${config.autoMode.defaultAgent}" not found — cannot decompose`);
-  }
-
-  // Resolve decompose model: config.decompose.model tier → actual model string
-  const decomposeTier = naxDecompose?.model ?? "balanced";
-  let decomposeModel: string | undefined;
-  try {
-    const { resolveModel } = await import("../../config/schema");
-    const models = config.models as Record<string, unknown>;
-    const entry = models[decomposeTier] ?? models.balanced;
-    if (entry) decomposeModel = resolveModel(entry as Parameters<typeof resolveModel>[0]).model;
-  } catch {
-    // resolveModel can throw on malformed entries — fall through to let complete() handle it
-  }
-
-  const storySessionName = `nax-decompose-${story.id.toLowerCase()}`;
-  const adapter = {
-    async decompose(prompt: string): Promise<string> {
-      return agent.complete(prompt, {
-        model: decomposeModel,
-        jsonMode: true,
-        config,
-        sessionName: storySessionName,
-      });
-    },
-  };
-
-  return DecomposeBuilder.for(story).prd(prd).config(builderConfig).decompose(adapter);
-}
-
-export const routingStage: PipelineStage = {
-  name: "routing",
-  enabled: () => true,
-
-  async execute(ctx: PipelineContext): Promise<StageResult> {
-    const logger = getLogger();
-
-    // Resolve agent adapter for LLM routing (shared with execution)
-    const agentName = ctx.config.execution?.agent ?? "claude";
-    const adapter = (ctx.agentGetFn ?? _routingDeps.getAgent)(agentName);
-
-    // Staleness detection (RRP-003):
-    // - story.routing absent                   → cache miss (no prior routing)
-    // - story.routing + no contentHash         → legacy cache hit (manual / pre-RRP-003 routing, honor as-is)
-    // - story.routing + contentHash matches    → cache hit
-    // - story.routing + contentHash mismatches → cache miss (stale, re-classify)
-    const hasExistingRouting = ctx.story.routing !== undefined;
-    const hasContentHash = ctx.story.routing?.contentHash !== undefined;
-    let currentHash: string | undefined;
-    let hashMatch = false;
-    if (hasContentHash) {
-      currentHash = _routingDeps.computeStoryContentHash(ctx.story);
-      hashMatch = ctx.story.routing?.contentHash === currentHash;
-    }
-    const isCacheHit = hasExistingRouting && (!hasContentHash || hashMatch);
-
-    let routing: { complexity: string; testStrategy: string; modelTier: string; reasoning?: string };
-
-    if (isCacheHit) {
-      // Cache hit: legacy routing (no contentHash) or matching contentHash — use cached values
-      routing = await _routingDeps.routeStory(ctx.story, { config: ctx.config, adapter }, ctx.workdir, ctx.plugins);
-      // Override with cached values only when they are actually set
-      if (ctx.story.routing?.complexity) routing.complexity = ctx.story.routing.complexity;
-      // BUG-062: Only honor stored testStrategy for legacy/manual routing (no contentHash).
-      // When contentHash exists, the LLM strategy layer already recomputes testStrategy
-      // fresh via determineTestStrategy() — don't clobber it with the stale PRD value.
-      if (!hasContentHash && ctx.story.routing?.testStrategy) routing.testStrategy = ctx.story.routing.testStrategy;
-      // BUG-032: Use escalated modelTier if explicitly set (by handleTierEscalation),
-      // otherwise derive from complexity + current config
-      if (ctx.story.routing?.modelTier) {
-        routing.modelTier = ctx.story.routing.modelTier;
-      } else {
-        routing.modelTier = _routingDeps.complexityToModelTier(
-          routing.complexity as import("../../config").Complexity,
-          ctx.config,
-        );
-      }
-    } else {
-      // Cache miss: no routing, or contentHash present but mismatched — fresh classification
-      routing = await _routingDeps.routeStory(ctx.story, { config: ctx.config, adapter }, ctx.workdir, ctx.plugins);
-      // currentHash already computed if a mismatch was detected; compute now if starting fresh
-      currentHash = currentHash ?? _routingDeps.computeStoryContentHash(ctx.story);
-      ctx.story.routing = {
-        ...(ctx.story.routing ?? {}),
-        complexity: routing.complexity as import("../../config").Complexity,
-        initialComplexity:
-          ctx.story.routing?.initialComplexity ?? (routing.complexity as import("../../config").Complexity),
-        testStrategy: routing.testStrategy as import("../../config").TestStrategy,
-        reasoning: routing.reasoning ?? "",
-        contentHash: currentHash,
-      };
-      if (ctx.prdPath) {
-        await _routingDeps.savePRD(ctx.prd, ctx.prdPath);
-      }
-    }
-
-    // BUG-010: Greenfield detection — force test-after if no test files exist
-    // MW-011: For monorepo stories, scan the story's package workdir (story.workdir), not the
-    // repo root. Scanning the repo root would find tests in OTHER packages and incorrectly
-    // classify the story as non-greenfield even when the target package has zero tests.
-    const greenfieldDetectionEnabled = ctx.config.tdd.greenfieldDetection ?? true;
-    if (greenfieldDetectionEnabled && routing.testStrategy.startsWith("three-session-tdd")) {
-      const greenfieldScanDir = ctx.story.workdir ? join(ctx.workdir, ctx.story.workdir) : ctx.workdir;
-      const isGreenfield = await _routingDeps.isGreenfieldStory(ctx.story, greenfieldScanDir);
-      if (isGreenfield) {
-        logger.info("routing", "Greenfield detected — forcing test-after strategy", {
-          storyId: ctx.story.id,
-          originalStrategy: routing.testStrategy,
-          scanDir: greenfieldScanDir,
-        });
-        routing.testStrategy = "test-after";
-        routing.reasoning = `${routing.reasoning} [GREENFIELD OVERRIDE: No test files exist, using test-after instead of TDD]`;
-      }
-    }
-
-    // Set ctx.routing after all overrides are applied
-    ctx.routing = routing as RoutingResult;
-
-    const isBatch = ctx.stories.length > 1;
-
-    logger.debug("routing", "Task classified", {
-      complexity: ctx.routing.complexity,
-      modelTier: ctx.routing.modelTier,
-      testStrategy: ctx.routing.testStrategy,
-      storyId: ctx.story.id,
-    });
-
-    if (!isBatch) {
-      logger.debug("routing", ctx.routing.reasoning);
-    }
-
-    // SD-004: Oversized story detection and decomposition
-    const decomposeConfig = ctx.config.decompose;
-    if (decomposeConfig && ctx.story.status !== "decomposed") {
-      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, ctx.agentGetFn);
-          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: "decomposed",
-              reason: `Decomposed into ${result.subStories.length} substories`,
-              subStoryCount: result.subStories.length,
-            };
-          }
-          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, ctx.agentGetFn);
-            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: "decomposed",
-                reason: `Decomposed into ${result.subStories.length} substories`,
-                subStoryCount: result.subStories.length,
-              };
-            }
-            logger.warn("routing", `Story ${ctx.story.id} decompose failed after retries — continuing with original`, {
-              errors: result.validation.errors,
-            });
-          }
-        }
-      }
-    }
-
-    return { action: "continue" };
-  },
-};
-
-/**
- * Swappable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
- * Tests can override individual functions without poisoning the module registry.
- */
-export const _routingDeps = {
-  routeStory,
-  complexityToModelTier,
-  isGreenfieldStory,
-  clearCache,
-  savePRD,
-  computeStoryContentHash,
-  applyDecomposition,
-  runDecompose,
-  checkStoryOversized,
-  getAgent,
-};

package/src/pipeline/stages/verify.ts

@@ -1,286 +0,0 @@
-/**
- * Verify Stage
- *
- * Verifies the agent's work meets basic requirements by running tests.
- * This is a lightweight verification before the full review stage.
- *
- * @returns
- * - `continue`: Tests passed, OR TEST_FAILURE (ctx.verifyResult.success===false → rectifyStage handles it)
- * - `escalate`: TIMEOUT or RUNTIME_CRASH (structural — rectify can't fix these)
- */
-
-import { basename, join } from "node:path";
-import type { SmartTestRunnerConfig } from "../../config/types";
-import { getLogger } from "../../logger";
-import { logTestOutput } from "../../utils/log-test-output";
-import { detectRuntimeCrash } from "../../verification/crash-detector";
-import type { VerifyStatus } from "../../verification/orchestrator-types";
-import { regression } from "../../verification/runners";
-import { _smartRunnerDeps } from "../../verification/smart-runner";
-import { isMonorepoOrchestratorCommand } from "../../verification/strategies/scoped";
-import type { PipelineContext, PipelineStage, StageResult } from "../types";
-
-const DEFAULT_SMART_RUNNER_CONFIG: SmartTestRunnerConfig = {
-  enabled: true,
-  testFilePatterns: ["test/**/*.test.ts"],
-  fallback: "import-grep",
-};
-
-/**
- * Coerces boolean or partial config into a full SmartTestRunnerConfig
- */
-function coerceSmartTestRunner(val: boolean | SmartTestRunnerConfig | undefined): SmartTestRunnerConfig {
-  if (val === undefined || val === true) return DEFAULT_SMART_RUNNER_CONFIG;
-  if (val === false) return { ...DEFAULT_SMART_RUNNER_CONFIG, enabled: false };
-  return val;
-}
-
-/**
- * Build the scoped test command from discovered test files.
- * Uses the testScoped template (with {{files}} placeholder) if configured,
- * otherwise falls back to buildSmartTestCommand heuristic.
- */
-function buildScopedCommand(testFiles: string[], baseCommand: string, testScopedTemplate?: string): string {
-  if (testScopedTemplate) {
-    return testScopedTemplate.replace("{{files}}", testFiles.join(" "));
-  }
-  return _smartRunnerDeps.buildSmartTestCommand(testFiles, baseCommand);
-}
-
-/**
- * Read the npm package name from <dir>/package.json.
- * Returns null if not found or file has no name field.
- */
-async function readPackageName(dir: string): Promise<string | null> {
-  try {
-    const content = await Bun.file(join(dir, "package.json")).json();
-    return typeof content.name === "string" ? content.name : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Substitute {{package}} placeholder in a testScoped template.
- *
- * Reads the npm package name from <packageDir>/package.json.
- * Returns null when package.json is absent or has no name field — callers
- * should skip the template entirely in that case (non-JS/non-Node projects
- * have no package identity to inject, so don't fall back to a dir name guess).
- *
- * @param template   - Template string (e.g. "bunx turbo test --filter={{package}}")
- * @param packageDir - Absolute path to the package directory
- * @returns Resolved template, or null if {{package}} cannot be resolved
- */
-async function resolvePackageTemplate(template: string, packageDir: string): Promise<string | null> {
-  if (!template.includes("{{package}}")) return template;
-  const name = await _verifyDeps.readPackageName(packageDir);
-  if (name === null) {
-    // No package.json or no name field — skip template, can't resolve {{package}}
-    return null;
-  }
-  return template.replaceAll("{{package}}", name);
-}
-
-export const verifyStage: PipelineStage = {
-  name: "verify",
-  enabled: (ctx: PipelineContext) => !ctx.fullSuiteGatePassed,
-  skipReason: () => "not needed (full-suite gate already passed)",
-
-  async execute(ctx: PipelineContext): Promise<StageResult> {
-    const logger = getLogger();
-
-    // PKG-003: use centrally resolved effective config (set once per story in iteration-runner)
-    // Falls back to ctx.config for contexts that predate PKG-003 (e.g., acceptance-loop)
-    const effectiveConfig = ctx.effectiveConfig ?? ctx.config;
-
-    // Skip verification if tests are not required
-    if (!effectiveConfig.quality.requireTests) {
-      logger.debug("verify", "Skipping verification (quality.requireTests = false)", { storyId: ctx.story.id });
-      return { action: "continue" };
-    }
-
-    // Skip verification if no test command is configured
-    const testCommand = effectiveConfig.review?.commands?.test ?? effectiveConfig.quality.commands.test;
-    const testScopedTemplate = effectiveConfig.quality.commands.testScoped;
-    if (!testCommand) {
-      logger.debug("verify", "Skipping verification (no test command configured)", { storyId: ctx.story.id });
-      return { action: "continue" };
-    }
-
-    logger.info("verify", "Running verification", { storyId: ctx.story.id });
-
-    // MW-006: resolve effective workdir for test execution
-    const effectiveWorkdir = ctx.story.workdir ? join(ctx.workdir, ctx.story.workdir) : ctx.workdir;
-
-    // Determine effective test command (smart runner or full suite)
-    let effectiveCommand = testCommand;
-    let isFullSuite = true;
-    const smartRunnerConfig = coerceSmartTestRunner(effectiveConfig.execution.smartTestRunner);
-    const regressionMode = effectiveConfig.execution.regressionGate?.mode ?? "deferred";
-
-    // Resolve {{package}} in testScoped template for monorepo stories.
-    // Returns null if package.json is absent (non-JS project) — falls through to smart-runner.
-    let resolvedTestScopedTemplate: string | undefined = testScopedTemplate;
-    if (testScopedTemplate && ctx.story.workdir) {
-      const resolved = await resolvePackageTemplate(testScopedTemplate, effectiveWorkdir);
-      resolvedTestScopedTemplate = resolved ?? undefined; // null → skip template
-    }
-
-    // Monorepo orchestrators (turbo, nx) handle change-aware scoping natively via their own
-    // filter syntax. Skip nax's smart runner — appending file paths would produce invalid syntax.
-    // Instead, use the testScoped template (with {{package}} resolved) to scope per-story.
-    const isMonorepoOrchestrator = isMonorepoOrchestratorCommand(testCommand);
-
-    if (isMonorepoOrchestrator) {
-      if (resolvedTestScopedTemplate && ctx.story.workdir) {
-        // Use the resolved scoped template (e.g. "bunx turbo test --filter=@koda/cli")
-        effectiveCommand = resolvedTestScopedTemplate;
-        isFullSuite = false;
-        logger.info("verify", "Monorepo orchestrator — using testScoped template", {
-          storyId: ctx.story.id,
-          command: effectiveCommand,
-        });
-      } else {
-        logger.info("verify", "Monorepo orchestrator — running full suite (no package context)", {
-          storyId: ctx.story.id,
-          command: effectiveCommand,
-        });
-      }
-    } else if (smartRunnerConfig.enabled) {
-      // MW-006: pass packagePrefix so git diff is scoped to the package in monorepos
-      const sourceFiles = await _smartRunnerDeps.getChangedSourceFiles(
-        effectiveWorkdir,
-        ctx.storyGitRef,
-        ctx.story.workdir,
-      );
-
-      // Pass 1: path convention mapping
-      const pass1Files = await _smartRunnerDeps.mapSourceToTests(sourceFiles, effectiveWorkdir);
-      if (pass1Files.length > 0) {
-        logger.info("verify", `[smart-runner] Pass 1: path convention matched ${pass1Files.length} test files`, {
-          storyId: ctx.story.id,
-        });
-        effectiveCommand = buildScopedCommand(pass1Files, testCommand, resolvedTestScopedTemplate);
-        isFullSuite = false;
-      } else if (smartRunnerConfig.fallback === "import-grep") {
-        // Pass 2: import-grep fallback
-        const pass2Files = await _smartRunnerDeps.importGrepFallback(
-          sourceFiles,
-          effectiveWorkdir,
-          smartRunnerConfig.testFilePatterns,
-        );
-        if (pass2Files.length > 0) {
-          logger.info("verify", `[smart-runner] Pass 2: import-grep matched ${pass2Files.length} test files`, {
-            storyId: ctx.story.id,
-          });
-          effectiveCommand = buildScopedCommand(pass2Files, testCommand, resolvedTestScopedTemplate);
-          isFullSuite = false;
-        }
-      }
-    }
-
-    // US-003: If we are falling back to the full suite AND mode is deferred, skip this stage
-    // because the deferred regression gate will handle the full suite at run-end.
-    if (isFullSuite && regressionMode === "deferred") {
-      logger.info("verify", "[smart-runner] No mapped tests — deferring full suite to run-end (mode: deferred)", {
-        storyId: ctx.story.id,
-      });
-      return { action: "continue" };
-    }
-
-    if (isFullSuite) {
-      logger.info("verify", "[smart-runner] No mapped tests — falling back to full suite", {
-        storyId: ctx.story.id,
-      });
-    }
-
-    // BUG-044: Log the effective command for observability
-    logger.info("verify", isFullSuite ? "Running full suite" : "Running scoped tests", {
-      storyId: ctx.story.id,
-      command: effectiveCommand,
-    });
-
-    // Use unified regression gate (includes 2s wait for agent process cleanup)
-    const result = await _verifyDeps.regression({
-      workdir: effectiveWorkdir,
-      command: effectiveCommand,
-      timeoutSeconds: effectiveConfig.execution.verificationTimeoutSeconds,
-      acceptOnTimeout: effectiveConfig.execution.regressionGate?.acceptOnTimeout ?? true,
-    });
-
-    // Store result on context for rectify stage
-    ctx.verifyResult = {
-      success: result.success,
-      status: (result.status === "TIMEOUT"
-        ? "TIMEOUT"
-        : result.success
-          ? "PASS"
-          : detectRuntimeCrash(result.output)
-            ? "RUNTIME_CRASH"
-            : "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
-      if (result.status === "TIMEOUT") {
-        const timeout = effectiveConfig.execution.verificationTimeoutSeconds;
-        logger.error(
-          "verify",
-          `Test suite exceeded timeout (${timeout}s). This is NOT a test failure — consider increasing execution.verificationTimeoutSeconds or scoping tests.`,
-          {
-            exitCode: result.status,
-            storyId: ctx.story.id,
-            timeoutSeconds: timeout,
-          },
-        );
-      } else {
-        logger.error("verify", "Tests failed", {
-          exitCode: result.status,
-          storyId: ctx.story.id,
-        });
-      }
-
-      // Log tail of output at debug level for context (ENH-001)
-      // BUG-037: Use .slice(-20) to show failures, not prechecks
-      if (result.status !== "TIMEOUT") {
-        logTestOutput(logger, "verify", result.output, { storyId: ctx.story.id });
-      }
-
-      // RUNTIME_CRASH and TIMEOUT are structural — escalate immediately (rectify can't fix them)
-      if (result.status === "TIMEOUT" || detectRuntimeCrash(result.output)) {
-        return {
-          action: "escalate",
-          reason:
-            result.status === "TIMEOUT"
-              ? `Test suite TIMEOUT after ${effectiveConfig.execution.verificationTimeoutSeconds}s (not a code failure)`
-              : `Tests failed with runtime crash (exit code ${result.status ?? "non-zero"})`,
-        };
-      }
-
-      // TEST_FAILURE: ctx.verifyResult is set with success:false — rectifyStage handles it next
-      return { action: "continue" };
-    }
-
-    logger.info("verify", "Tests passed", { storyId: ctx.story.id });
-    return { action: "continue" };
-  },
-};
-
-/**
- * Swappable dependencies for testing (avoids mock.module() which leaks in Bun 1.x).
- */
-export const _verifyDeps = {
-  regression,
-  readPackageName,
-};