@nathapp/nax 0.32.2 → 0.33.0

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[];
 }
 
 /**

package/src/prd/index.ts

@@ -107,6 +107,7 @@ export function getNextStory(prd: PRD, currentStoryId?: string | null, maxRetrie
         s.status !== "blocked" &&
         s.status !== "failed" &&
         s.status !== "paused" &&
+        s.status !== "decomposed" &&
         s.dependencies.every((dep) => completedIds.has(dep)),
     ) ?? null
   );
@@ -132,6 +133,7 @@ export function countStories(prd: PRD): {
   skipped: number;
   blocked: number;
   paused: number;
+  decomposed: number;
 } {
   return {
     total: prd.userStories.length,
@@ -144,11 +146,13 @@ export function countStories(prd: PRD): {
         s.status !== "failed" &&
         s.status !== "skipped" &&
         s.status !== "blocked" &&
-        s.status !== "paused",
+        s.status !== "paused" &&
+        s.status !== "decomposed",
     ).length,
     skipped: prd.userStories.filter((s) => s.status === "skipped").length,
     blocked: prd.userStories.filter((s) => s.status === "blocked").length,
     paused: prd.userStories.filter((s) => s.status === "paused").length,
+    decomposed: prd.userStories.filter((s) => s.status === "decomposed").length,
   };
 }
 

package/src/prd/types.ts

@@ -9,7 +9,15 @@ import type { ModelTier } from "../config";
 import type { FailureCategory } from "../tdd/types";
 
 /** User story status */
-export type StoryStatus = "pending" | "in-progress" | "passed" | "failed" | "skipped" | "blocked" | "paused";
+export type StoryStatus =
+  | "pending"
+  | "in-progress"
+  | "passed"
+  | "failed"
+  | "skipped"
+  | "blocked"
+  | "paused"
+  | "decomposed";
 
 /** Verification stage where failure occurred */
 export type VerificationStage = "verify" | "review" | "regression" | "rectification" | "agent-session" | "escalation";
@@ -38,6 +46,8 @@ export interface StructuredFailure {
   summary: string;
   /** Parsed test failures (if applicable) */
   testFailures?: TestFailureContext[];
+  /** Structured review findings from plugin reviewers (e.g., semgrep, eslint) */
+  reviewFindings?: import("../plugins/types").ReviewFinding[];
   /** ISO timestamp when failure was recorded */
   timestamp: string;
 }

package/src/review/orchestrator.ts

@@ -72,6 +72,7 @@ export class ReviewOrchestrator {
               passed: result.passed,
               output: result.output,
               exitCode: result.exitCode,
+              findings: result.findings,
             });
             if (!result.passed) {
               builtIn.pluginReviewers = pluginResults;

package/src/review/types.ts

@@ -35,6 +35,8 @@ export interface PluginReviewerResult {
   exitCode?: number;
   /** Error message if reviewer threw an exception */
   error?: string;
+  /** Structured findings from the reviewer (optional) */
+  findings?: import("../plugins/types").ReviewFinding[];
 }
 
 /** Review phase result */

package/src/tdd/isolation.ts

@@ -55,7 +55,7 @@ function matchesAllowedPath(filePath: string, allowedPaths: string[]): boolean {
   return allowedPaths.some((pattern) => {
     // Simple glob matching: ** = any directory, * = any filename segment
     const regexPattern = pattern.replace(/\*\*/g, ".*").replace(/\*/g, "[^/]*").replace(/\//g, "\\/");
-    const regex = new RegExp(`^${regexPattern}$`);
+    const regex = new RegExp(`^${regexPattern}$`); // nosemgrep: detect-non-literal-regexp — pattern from PRD scope config, not user input
     return regex.test(filePath);
   });
 }