@nathapp/nax 0.32.2 → 0.33.0

package/src/decompose/types.ts

@@ -0,0 +1,55 @@
+/**
+ * Decompose module types.
+ *
+ * DecomposeConfig, SubStory, DecomposeResult, ValidationResult.
+ */
+
+/** Configuration for story decomposition */
+export interface DecomposeConfig {
+  /** Maximum number of sub-stories to generate */
+  maxSubStories: number;
+  /** Maximum allowed complexity for any sub-story */
+  maxComplexity: "simple" | "medium" | "complex" | "expert";
+  /** Maximum number of retries on validation failure */
+  maxRetries?: number;
+}
+
+/** A single decomposed sub-story */
+export interface SubStory {
+  /** Sub-story ID (e.g., "SD-001-1") */
+  id: string;
+  /** Parent story ID */
+  parentStoryId: string;
+  /** Sub-story title */
+  title: string;
+  /** Sub-story description */
+  description: string;
+  /** Acceptance criteria */
+  acceptanceCriteria: string[];
+  /** Tags for routing */
+  tags: string[];
+  /** Dependencies (story IDs) */
+  dependencies: string[];
+  /** Complexity classification */
+  complexity: "simple" | "medium" | "complex" | "expert";
+  /** Justification that this sub-story does not overlap with sibling stories */
+  nonOverlapJustification: string;
+}
+
+/** Validation result for decomposition output */
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}
+
+/** Result of decomposing a story */
+export interface DecomposeResult {
+  subStories: SubStory[];
+  validation: ValidationResult;
+}
+
+/** Adapter interface for calling the decompose LLM */
+export interface DecomposeAdapter {
+  decompose(prompt: string): Promise<string>;
+}

package/src/decompose/validators/complexity.ts

@@ -0,0 +1,45 @@
+/**
+ * Complexity validator.
+ *
+ * Validates each substory complexity is <= config.maxSubstoryComplexity (default: medium).
+ * Reuses classifyComplexity() from src/routing/router.ts as a cross-check against LLM-assigned complexity.
+ */
+
+import { classifyComplexity } from "../../routing";
+import type { SubStory, ValidationResult } from "../types";
+
+export type ComplexityLevel = "simple" | "medium" | "complex" | "expert";
+
+const COMPLEXITY_ORDER: Record<ComplexityLevel, number> = {
+  simple: 0,
+  medium: 1,
+  complex: 2,
+  expert: 3,
+};
+
+export function validateComplexity(substories: SubStory[], maxComplexity: ComplexityLevel): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const maxOrder = COMPLEXITY_ORDER[maxComplexity];
+
+  for (const sub of substories) {
+    const assignedOrder = COMPLEXITY_ORDER[sub.complexity];
+
+    if (assignedOrder > maxOrder) {
+      errors.push(`Substory ${sub.id} complexity "${sub.complexity}" exceeds maxComplexity "${maxComplexity}"`);
+    }
+
+    // Cross-check with classifyComplexity
+    const classified = classifyComplexity(sub.title, sub.description, sub.acceptanceCriteria, sub.tags);
+    if (classified !== sub.complexity) {
+      const classifiedOrder = COMPLEXITY_ORDER[classified as ComplexityLevel] ?? 0;
+      if (classifiedOrder > assignedOrder) {
+        warnings.push(
+          `Substory ${sub.id} is assigned complexity "${sub.complexity}" but classifier estimates "${classified}" — may be underestimated`,
+        );
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/decompose/validators/coverage.ts

@@ -0,0 +1,134 @@
+/**
+ * Coverage validator.
+ *
+ * Checks that the union of substory acceptance criteria covers
+ * the original story's AC using keyword matching.
+ * Warns on unmatched original criteria.
+ */
+
+import type { UserStory } from "../../prd";
+import type { SubStory, ValidationResult } from "../types";
+
+const STOP_WORDS = new Set([
+  "a",
+  "an",
+  "the",
+  "and",
+  "or",
+  "but",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "have",
+  "has",
+  "had",
+  "do",
+  "does",
+  "did",
+  "will",
+  "would",
+  "could",
+  "should",
+  "may",
+  "might",
+  "can",
+  "to",
+  "of",
+  "in",
+  "on",
+  "at",
+  "for",
+  "with",
+  "by",
+  "from",
+  "as",
+  "it",
+  "its",
+  "that",
+  "this",
+  "these",
+  "those",
+  "not",
+  "no",
+  "so",
+  "if",
+  "then",
+  "than",
+  "when",
+  "which",
+  "who",
+  "what",
+  "how",
+  "all",
+  "each",
+  "any",
+  "up",
+  "out",
+  "about",
+  "into",
+  "through",
+  "after",
+  "before",
+]);
+
+function extractKeywords(text: string): string[] {
+  return text
+    .toLowerCase()
+    .split(/[\s,.:;!?()\[\]{}"'`\-_/\\]+/)
+    .filter((w) => w.length > 2 && !STOP_WORDS.has(w));
+}
+
+function commonPrefixLength(a: string, b: string): number {
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i]) i++;
+  return i;
+}
+
+/**
+ * Two keywords match if they are identical or share a common prefix of ≥5 chars.
+ * This handles morphological variants like "register" / "registration" (prefix "regist" = 6).
+ * It does NOT match unrelated words that start with "re" ("reset" vs "register" = 2 chars).
+ */
+function keywordsMatch(a: string, b: string): boolean {
+  return a === b || commonPrefixLength(a, b) >= 5;
+}
+
+/**
+ * Returns true if the original AC is "covered" by the union of substory ACs.
+ * Covered means: strictly more than half of the original AC's keywords have a
+ * match (exact or common-prefix ≥5) in the substory AC keywords.
+ */
+function isCovered(originalAc: string, substoryAcs: string[]): boolean {
+  const originalKw = extractKeywords(originalAc);
+  if (originalKw.length === 0) return true;
+
+  const substoryKwList = substoryAcs.flatMap(extractKeywords);
+
+  let matchCount = 0;
+  for (const kw of originalKw) {
+    if (substoryKwList.some((s) => keywordsMatch(kw, s))) {
+      matchCount++;
+    }
+  }
+
+  // Require strictly more than half of the original AC's keywords to match
+  return matchCount > originalKw.length / 2;
+}
+
+export function validateCoverage(originalStory: UserStory, substories: SubStory[]): ValidationResult {
+  const warnings: string[] = [];
+
+  const allSubstoryAcs = substories.flatMap((s) => s.acceptanceCriteria);
+
+  for (const ac of originalStory.acceptanceCriteria ?? []) {
+    if (!isCovered(ac, allSubstoryAcs)) {
+      warnings.push(`Original AC not covered by any substory: "${ac}"`);
+    }
+  }
+
+  return { valid: true, errors: [], warnings };
+}

package/src/decompose/validators/dependency.ts

@@ -0,0 +1,91 @@
+/**
+ * Dependency validator.
+ *
+ * Validates:
+ * - No circular dependencies among substories
+ * - All referenced dependency IDs exist (in substories or existing PRD)
+ * - No ID collisions with existing PRD story IDs
+ */
+
+import type { SubStory, ValidationResult } from "../types";
+
+function detectCycles(substories: SubStory[]): string[] {
+  const errors: string[] = [];
+  const idSet = new Set(substories.map((s) => s.id));
+
+  // Build adjacency map (only edges within the substory set)
+  const adj: Map<string, string[]> = new Map();
+  for (const sub of substories) {
+    adj.set(
+      sub.id,
+      sub.dependencies.filter((d) => idSet.has(d)),
+    );
+  }
+
+  const WHITE = 0; // unvisited
+  const GRAY = 1; // in current path
+  const BLACK = 2; // done
+
+  const color: Map<string, number> = new Map();
+  for (const id of idSet) color.set(id, WHITE);
+
+  const reported = new Set<string>();
+
+  function dfs(id: string, path: string[]): void {
+    color.set(id, GRAY);
+    for (const dep of adj.get(id) ?? []) {
+      if (color.get(dep) === GRAY) {
+        // Found a cycle — report it once
+        const cycleKey = [...path, dep].sort().join(",");
+        if (!reported.has(cycleKey)) {
+          reported.add(cycleKey);
+          const cycleStart = path.indexOf(dep);
+          const cycleNodes = cycleStart >= 0 ? path.slice(cycleStart) : path;
+          const cycleStr = [...cycleNodes, dep].join(" -> ");
+          errors.push(`Circular dependency detected: ${cycleStr}`);
+        }
+      } else if (color.get(dep) === WHITE) {
+        dfs(dep, [...path, dep]);
+      }
+    }
+    color.set(id, BLACK);
+  }
+
+  for (const id of idSet) {
+    if (color.get(id) === WHITE) {
+      dfs(id, [id]);
+    }
+  }
+
+  return errors;
+}
+
+export function validateDependencies(substories: SubStory[], existingStoryIds: string[]): ValidationResult {
+  const errors: string[] = [];
+
+  const substoryIdSet = new Set(substories.map((s) => s.id));
+  const existingIdSet = new Set(existingStoryIds);
+  const allKnownIds = new Set([...substoryIdSet, ...existingIdSet]);
+
+  // ID collisions with existing PRD
+  for (const sub of substories) {
+    if (existingIdSet.has(sub.id)) {
+      errors.push(`Substory ID "${sub.id}" collides with existing PRD story — duplicate IDs are not allowed`);
+    }
+  }
+
+  // Non-existent dependency references
+  for (const sub of substories) {
+    for (const dep of sub.dependencies) {
+      if (!allKnownIds.has(dep)) {
+        errors.push(`Substory ${sub.id} references non-existent story ID "${dep}"`);
+      }
+    }
+  }
+
+  // Circular dependencies
+  const cycleErrors = detectCycles(substories);
+  errors.push(...cycleErrors);
+
+  return { valid: errors.length === 0, errors, warnings: [] };
+}

package/src/decompose/validators/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Validator orchestrator.
+ *
+ * runAllValidators() runs all validators in sequence and returns merged ValidationResult.
+ */
+
+import type { UserStory } from "../../prd";
+import type { DecomposeConfig, SubStory, ValidationResult } from "../types";
+import type { ComplexityLevel } from "./complexity";
+import { validateComplexity } from "./complexity";
+import { validateCoverage } from "./coverage";
+import { validateDependencies } from "./dependency";
+import { validateOverlap } from "./overlap";
+
+export function runAllValidators(
+  originalStory: UserStory,
+  substories: SubStory[],
+  existingStories: UserStory[],
+  config: DecomposeConfig,
+): ValidationResult {
+  const existingIds = existingStories.map((s) => s.id);
+  const maxComplexity = (config.maxComplexity ?? "medium") as ComplexityLevel;
+
+  const results = [
+    validateOverlap(substories, existingStories),
+    validateCoverage(originalStory, substories),
+    validateComplexity(substories, maxComplexity),
+    validateDependencies(substories, existingIds),
+  ];
+
+  const errors = results.flatMap((r) => r.errors);
+  const warnings = results.flatMap((r) => r.warnings);
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/decompose/validators/overlap.ts

@@ -0,0 +1,128 @@
+/**
+ * Overlap validator.
+ *
+ * Checks keyword + tag similarity between each substory and all existing PRD stories.
+ * Uses Jaccard-like normalized keyword intersection over title + tags.
+ * Flags pairs with similarity > 0.6 as warnings, > 0.8 as errors.
+ */
+
+import type { UserStory } from "../../prd";
+import type { SubStory, ValidationResult } from "../types";
+
+const STOP_WORDS = new Set([
+  "a",
+  "an",
+  "the",
+  "and",
+  "or",
+  "but",
+  "is",
+  "are",
+  "was",
+  "were",
+  "be",
+  "been",
+  "being",
+  "have",
+  "has",
+  "had",
+  "do",
+  "does",
+  "did",
+  "will",
+  "would",
+  "could",
+  "should",
+  "may",
+  "might",
+  "can",
+  "to",
+  "of",
+  "in",
+  "on",
+  "at",
+  "for",
+  "with",
+  "by",
+  "from",
+  "as",
+  "it",
+  "its",
+  "that",
+  "this",
+  "these",
+  "those",
+  "not",
+  "no",
+  "so",
+  "if",
+  "then",
+  "than",
+  "when",
+  "which",
+  "who",
+  "what",
+  "how",
+  "all",
+  "each",
+  "any",
+  "up",
+  "out",
+  "about",
+  "into",
+  "through",
+  "after",
+  "before",
+]);
+
+function extractKeywords(texts: string[]): Set<string> {
+  const words = texts
+    .join(" ")
+    .toLowerCase()
+    .split(/[\s,.:;!?()\[\]{}"'`\-_/\\]+/)
+    .filter((w) => w.length > 2 && !STOP_WORDS.has(w) && !/^\d+$/.test(w));
+  return new Set(words);
+}
+
+function jaccardSimilarity(a: Set<string>, b: Set<string>): number {
+  if (a.size === 0 && b.size === 0) return 0;
+  let intersectionSize = 0;
+  for (const word of a) {
+    if (b.has(word)) intersectionSize++;
+  }
+  const unionSize = a.size + b.size - intersectionSize;
+  return unionSize === 0 ? 0 : intersectionSize / unionSize;
+}
+
+// Use title + tags only for overlap detection to get stable, meaningful similarity scores
+function substoryKeywords(s: SubStory): Set<string> {
+  return extractKeywords([s.title, ...s.tags]);
+}
+
+function storyKeywords(s: UserStory): Set<string> {
+  return extractKeywords([s.title, ...(s.tags ?? [])]);
+}
+
+export function validateOverlap(substories: SubStory[], existingStories: UserStory[]): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  for (const sub of substories) {
+    const subKw = substoryKeywords(sub);
+    for (const existing of existingStories) {
+      const exKw = storyKeywords(existing);
+      const sim = jaccardSimilarity(subKw, exKw);
+      if (sim > 0.8) {
+        errors.push(
+          `Substory ${sub.id} overlaps with existing story ${existing.id} (similarity ${sim.toFixed(2)} > 0.8)`,
+        );
+      } else if (sim > 0.6) {
+        warnings.push(
+          `Substory ${sub.id} may overlap with existing story ${existing.id} (similarity ${sim.toFixed(2)} > 0.6)`,
+        );
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

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

@@ -20,12 +20,17 @@ import { appendProgress } from "../progress";
 import { handleMaxAttemptsReached, handleNoTierAvailable } from "./tier-outcome";
 
 /** Build a StructuredFailure for tier escalation. */
-function buildEscalationFailure(story: UserStory, currentTier: string): StructuredFailure {
+function buildEscalationFailure(
+  story: UserStory,
+  currentTier: string,
+  reviewFindings?: import("../../plugins/types").ReviewFinding[],
+): StructuredFailure {
   return {
     attempt: (story.attempts ?? 0) + 1,
     modelTier: currentTier,
     stage: "escalation" as const,
     summary: `Failed with tier ${currentTier}, escalating to next tier`,
+    reviewFindings: reviewFindings && reviewFindings.length > 0 ? reviewFindings : undefined,
     timestamp: new Date().toISOString(),
   };
 }
@@ -192,6 +197,7 @@ export interface EscalationHandlerContext {
     context: {
       retryAsLite?: boolean;
       tddFailureCategory?: FailureCategory;
+      reviewFindings?: import("../../plugins/types").ReviewFinding[];
     };
   };
   config: NaxConfig;
@@ -224,6 +230,7 @@ export async function handleTierEscalation(ctx: EscalationHandlerContext): Promi
   // Retrieve TDD-specific context flags set by executionStage
   const escalateRetryAsLite = ctx.pipelineResult.context.retryAsLite === true;
   const escalateFailureCategory = ctx.pipelineResult.context.tddFailureCategory;
+  const escalateReviewFindings = ctx.pipelineResult.context.reviewFindings;
   // S5: Auto-switch to test-after on greenfield-no-tests
   const escalateRetryAsTestAfter = escalateFailureCategory === "greenfield-no-tests";
   const routingMode = ctx.config.routing.llm?.mode ?? "hybrid";
@@ -288,7 +295,7 @@ export async function handleTierEscalation(ctx: EscalationHandlerContext): Promi
       const shouldResetAttempts = isChangingTier || shouldSwitchToTestAfter;
 
       // Build escalation failure
-      const escalationFailure = buildEscalationFailure(s, currentStoryTier);
+      const escalationFailure = buildEscalationFailure(s, currentStoryTier, escalateReviewFindings);
 
       return {
         ...s,

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";
@@ -181,7 +181,8 @@ export async function executeSequential(
 
     return buildResult("max-iterations");
   } finally {
-    stopHeartbeat();
-    writeExitSummary(ctx.logFilePath, totalCost, iterations, storiesCompleted, Date.now() - ctx.startTime);
+    // BUG-060: Do NOT stopHeartbeat or writeExitSummary here.
+    // runner.ts owns the full lifecycle (including deferred regression gate)
+    // and handles heartbeat + exit summary after all post-run work completes.
   }
 }

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/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)) {