@nathapp/nax 0.32.2 → 0.33.0

package/dist/nax.js

@@ -17993,7 +17993,7 @@ var init_zod = __esm(() => {
 });
 
 // src/config/schemas.ts
-var TokenPricingSchema, ModelDefSchema, ModelEntrySchema, ModelMapSchema, ModelTierSchema, TierConfigSchema, AutoModeConfigSchema, RectificationConfigSchema, RegressionGateConfigSchema, SmartTestRunnerConfigSchema, SMART_TEST_RUNNER_DEFAULT, smartTestRunnerFieldSchema, ExecutionConfigSchema, QualityConfigSchema, TddConfigSchema, ConstitutionConfigSchema, AnalyzeConfigSchema, ReviewConfigSchema, PlanConfigSchema, AcceptanceConfigSchema, TestCoverageConfigSchema, ContextAutoDetectConfigSchema, ContextConfigSchema, AdaptiveRoutingConfigSchema, LlmRoutingConfigSchema, RoutingConfigSchema, OptimizerConfigSchema, PluginConfigEntrySchema, HooksConfigSchema, InteractionConfigSchema, StorySizeGateConfigSchema, PrecheckConfigSchema, PromptsConfigSchema, NaxConfigSchema;
+var TokenPricingSchema, ModelDefSchema, ModelEntrySchema, ModelMapSchema, ModelTierSchema, TierConfigSchema, AutoModeConfigSchema, RectificationConfigSchema, RegressionGateConfigSchema, SmartTestRunnerConfigSchema, SMART_TEST_RUNNER_DEFAULT, smartTestRunnerFieldSchema, ExecutionConfigSchema, QualityConfigSchema, TddConfigSchema, ConstitutionConfigSchema, AnalyzeConfigSchema, ReviewConfigSchema, PlanConfigSchema, AcceptanceConfigSchema, TestCoverageConfigSchema, ContextAutoDetectConfigSchema, ContextConfigSchema, AdaptiveRoutingConfigSchema, LlmRoutingConfigSchema, RoutingConfigSchema, OptimizerConfigSchema, PluginConfigEntrySchema, HooksConfigSchema, InteractionConfigSchema, StorySizeGateConfigSchema, PrecheckConfigSchema, PromptsConfigSchema, DecomposeConfigSchema, NaxConfigSchema;
 var init_schemas3 = __esm(() => {
   init_zod();
   TokenPricingSchema = exports_external.object({
@@ -18231,6 +18231,14 @@ var init_schemas3 = __esm(() => {
   PromptsConfigSchema = exports_external.object({
     overrides: exports_external.record(exports_external.enum(["test-writer", "implementer", "verifier", "single-session"]), exports_external.string().min(1, "Override path must be non-empty")).optional()
   });
+  DecomposeConfigSchema = exports_external.object({
+    trigger: exports_external.enum(["auto", "confirm", "disabled"]).default("auto"),
+    maxAcceptanceCriteria: exports_external.number().int().min(1).default(6),
+    maxSubstories: exports_external.number().int().min(1).default(5),
+    maxSubstoryComplexity: exports_external.enum(["simple", "medium", "complex", "expert"]).default("medium"),
+    maxRetries: exports_external.number().int().min(0).default(2),
+    model: exports_external.string().min(1).default("balanced")
+  });
   NaxConfigSchema = exports_external.object({
     version: exports_external.number(),
     models: ModelMapSchema,
@@ -18250,7 +18258,8 @@ var init_schemas3 = __esm(() => {
     hooks: HooksConfigSchema.optional(),
     interaction: InteractionConfigSchema.optional(),
     precheck: PrecheckConfigSchema.optional(),
-    prompts: PromptsConfigSchema.optional()
+    prompts: PromptsConfigSchema.optional(),
+    decompose: DecomposeConfigSchema.optional()
   }).refine((data) => data.version === 1, {
     message: "Invalid version: expected 1",
     path: ["version"]
@@ -18414,7 +18423,15 @@ var init_defaults = __esm(() => {
         maxBulletPoints: 8
       }
     },
-    prompts: {}
+    prompts: {},
+    decompose: {
+      trigger: "auto",
+      maxAcceptanceCriteria: 6,
+      maxSubstories: 5,
+      maxSubstoryComplexity: "medium",
+      maxRetries: 2,
+      model: "balanced"
+    }
   };
 });
 
@@ -18424,6 +18441,120 @@ var init_schema = __esm(() => {
   init_defaults();
 });
 
+// src/decompose/apply.ts
+function applyDecomposition(prd, result) {
+  const { subStories } = result;
+  if (subStories.length === 0)
+    return;
+  const parentStoryId = subStories[0].parentStoryId;
+  const originalIndex = prd.userStories.findIndex((s) => s.id === parentStoryId);
+  if (originalIndex === -1)
+    return;
+  prd.userStories[originalIndex].status = "decomposed";
+  const newStories = subStories.map((sub) => ({
+    id: sub.id,
+    title: sub.title,
+    description: sub.description,
+    acceptanceCriteria: sub.acceptanceCriteria,
+    tags: sub.tags,
+    dependencies: sub.dependencies,
+    status: "pending",
+    passes: false,
+    escalations: [],
+    attempts: 0,
+    parentStoryId: sub.parentStoryId
+  }));
+  prd.userStories.splice(originalIndex + 1, 0, ...newStories);
+}
+
+// src/decompose/sections/codebase.ts
+function buildCodebaseSection(scan) {
+  const deps = Object.entries(scan.dependencies).slice(0, 15).map(([k, v]) => `  ${k}: ${v}`).join(`
+`);
+  return [
+    "# Codebase Context",
+    "",
+    "**File Tree:**",
+    scan.fileTree,
+    "",
+    "**Dependencies:**",
+    deps || "  (none)",
+    "",
+    `**Test Patterns:** ${scan.testPatterns.join(", ")}`
+  ].join(`
+`);
+}
+
+// src/decompose/sections/constraints.ts
+function buildConstraintsSection(config2) {
+  return [
+    "# Decomposition Constraints",
+    "",
+    `- **Max sub-stories:** ${config2.maxSubStories}`,
+    `- **Max complexity per sub-story:** ${config2.maxComplexity}`,
+    "",
+    "Respond with ONLY a JSON array (no markdown code fences):",
+    "[{",
+    `  "id": "PARENT-ID-1",`,
+    `  "parentStoryId": "PARENT-ID",`,
+    `  "title": "Sub-story title",`,
+    `  "description": "What to implement",`,
+    `  "acceptanceCriteria": ["Criterion 1"],`,
+    `  "tags": [],`,
+    `  "dependencies": [],`,
+    `  "complexity": "simple",`,
+    `  "nonOverlapJustification": "Why this sub-story does not overlap with sibling stories"`,
+    "}]",
+    "",
+    "The nonOverlapJustification field is required for every sub-story."
+  ].join(`
+`);
+}
+
+// src/decompose/sections/sibling-stories.ts
+function buildSiblingStoriesSection(targetStory, prd) {
+  const siblings = prd.userStories.filter((s) => s.id !== targetStory.id);
+  if (siblings.length === 0) {
+    return `# Sibling Stories
+
+No other stories exist in this PRD.`;
+  }
+  const entries = siblings.map((s) => {
+    const acSummary = s.acceptanceCriteria.slice(0, 3).join("; ");
+    return `- **${s.id}** \u2014 ${s.title} [${s.status}]
+  AC: ${acSummary}`;
+  }).join(`
+`);
+  return ["# Sibling Stories", "", "Avoid overlapping with these existing stories in the PRD:", "", entries].join(`
+`);
+}
+
+// src/decompose/sections/target-story.ts
+function buildTargetStorySection(story) {
+  const ac = story.acceptanceCriteria.map((c, i) => `${i + 1}. ${c}`).join(`
+`);
+  const tags = story.tags.length > 0 ? story.tags.join(", ") : "none";
+  const deps = story.dependencies.length > 0 ? story.dependencies.join(", ") : "none";
+  return [
+    "# Target Story to Decompose",
+    "",
+    `**ID:** ${story.id}`,
+    `**Title:** ${story.title}`,
+    "",
+    "**Description:**",
+    story.description,
+    "",
+    "**Acceptance Criteria:**",
+    ac,
+    "",
+    `**Tags:** ${tags}`,
+    `**Dependencies:** ${deps}`,
+    "",
+    "Decompose this story into smaller sub-stories that can each be implemented independently."
+  ].join(`
+`);
+}
+
 // src/routing/chain.ts
 class StrategyChain {
   strategies;
@@ -19526,90 +19657,471 @@ var init_routing = __esm(() => {
   init_batch_route();
 });
 
-// package.json
-var package_default;
-var init_package = __esm(() => {
-  package_default = {
-    name: "@nathapp/nax",
-    version: "0.32.2",
-    description: "AI Coding Agent Orchestrator \u2014 loops until done",
-    type: "module",
-    bin: {
-      nax: "./dist/nax.js"
-    },
-    scripts: {
-      prepare: "git config core.hooksPath .githooks",
-      dev: "bun run bin/nax.ts",
-      build: 'bun build bin/nax.ts --outdir dist --target bun --define "GIT_COMMIT=\\"$(git rev-parse --short HEAD)\\""',
-      typecheck: "bun x tsc --noEmit",
-      lint: "bun x biome check src/ bin/",
-      test: "NAX_SKIP_PRECHECK=1 bun test test/ --timeout=60000",
-      "test:watch": "bun test --watch",
-      "test:unit": "bun test ./test/unit/ --timeout=60000",
-      "test:integration": "bun test ./test/integration/ --timeout=60000",
-      "test:ui": "bun test ./test/ui/ --timeout=60000",
-      prepublishOnly: "bun run build"
-    },
-    dependencies: {
-      "@anthropic-ai/sdk": "^0.74.0",
-      "@types/react": "^19.2.14",
-      chalk: "^5.6.2",
-      commander: "^13.1.0",
-      ink: "^6.7.0",
-      "ink-spinner": "^5.0.0",
-      "ink-testing-library": "^4.0.0",
-      react: "^19.2.4",
-      zod: "^4.3.6"
-    },
-    devDependencies: {
-      "@biomejs/biome": "^1.9.4",
-      "@types/bun": "^1.3.8",
-      "react-devtools-core": "^7.0.1",
-      typescript: "^5.7.3"
-    },
-    license: "MIT",
-    author: "William Khoo",
-    keywords: [
-      "ai",
-      "agent",
-      "orchestrator",
-      "tdd",
-      "coding"
-    ],
-    files: [
-      "dist/",
-      "src/",
-      "bin/",
-      "README.md",
-      "CHANGELOG.md"
-    ]
+// src/decompose/validators/complexity.ts
+function validateComplexity2(substories, maxComplexity) {
+  const errors3 = [];
+  const warnings = [];
+  const maxOrder = COMPLEXITY_ORDER[maxComplexity];
+  for (const sub of substories) {
+    const assignedOrder = COMPLEXITY_ORDER[sub.complexity];
+    if (assignedOrder > maxOrder) {
+      errors3.push(`Substory ${sub.id} complexity "${sub.complexity}" exceeds maxComplexity "${maxComplexity}"`);
+    }
+    const classified = classifyComplexity2(sub.title, sub.description, sub.acceptanceCriteria, sub.tags);
+    if (classified !== sub.complexity) {
+      const classifiedOrder = COMPLEXITY_ORDER[classified] ?? 0;
+      if (classifiedOrder > assignedOrder) {
+        warnings.push(`Substory ${sub.id} is assigned complexity "${sub.complexity}" but classifier estimates "${classified}" \u2014 may be underestimated`);
+      }
+    }
+  }
+  return { valid: errors3.length === 0, errors: errors3, warnings };
+}
+var COMPLEXITY_ORDER;
+var init_complexity = __esm(() => {
+  init_routing();
+  COMPLEXITY_ORDER = {
+    simple: 0,
+    medium: 1,
+    complex: 2,
+    expert: 3
   };
 });
 
-// src/version.ts
-var NAX_VERSION, NAX_COMMIT, NAX_BUILD_INFO;
-var init_version = __esm(() => {
-  init_package();
-  NAX_VERSION = package_default.version;
-  NAX_COMMIT = (() => {
-    try {
-      if (/^[0-9a-f]{6,10}$/.test("1012b41"))
-        return "1012b41";
-    } catch {}
-    try {
-      const result = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
-        cwd: import.meta.dir,
-        stderr: "ignore"
-      });
-      if (result.exitCode === 0) {
-        const hash2 = result.stdout.toString().trim();
-        if (/^[0-9a-f]{6,10}$/.test(hash2))
-          return hash2;
+// src/decompose/validators/coverage.ts
+function extractKeywords(text) {
+  return text.toLowerCase().split(/[\s,.:;!?()\[\]{}"'`\-_/\\]+/).filter((w) => w.length > 2 && !STOP_WORDS.has(w));
+}
+function commonPrefixLength(a, b) {
+  let i = 0;
+  while (i < a.length && i < b.length && a[i] === b[i])
+    i++;
+  return i;
+}
+function keywordsMatch(a, b) {
+  return a === b || commonPrefixLength(a, b) >= 5;
+}
+function isCovered(originalAc, substoryAcs) {
+  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++;
+    }
+  }
+  return matchCount > originalKw.length / 2;
+}
+function validateCoverage(originalStory, substories) {
+  const warnings = [];
+  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 };
+}
+var STOP_WORDS;
+var init_coverage = __esm(() => {
+  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"
+  ]);
+});
+
+// src/decompose/validators/dependency.ts
+function detectCycles(substories) {
+  const errors3 = [];
+  const idSet = new Set(substories.map((s) => s.id));
+  const adj = new Map;
+  for (const sub of substories) {
+    adj.set(sub.id, sub.dependencies.filter((d) => idSet.has(d)));
+  }
+  const WHITE = 0;
+  const GRAY = 1;
+  const BLACK = 2;
+  const color = new Map;
+  for (const id of idSet)
+    color.set(id, WHITE);
+  const reported = new Set;
+  function dfs(id, path) {
+    color.set(id, GRAY);
+    for (const dep of adj.get(id) ?? []) {
+      if (color.get(dep) === GRAY) {
+        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(" -> ");
+          errors3.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 errors3;
+}
+function validateDependencies(substories, existingStoryIds) {
+  const errors3 = [];
+  const substoryIdSet = new Set(substories.map((s) => s.id));
+  const existingIdSet = new Set(existingStoryIds);
+  const allKnownIds = new Set([...substoryIdSet, ...existingIdSet]);
+  for (const sub of substories) {
+    if (existingIdSet.has(sub.id)) {
+      errors3.push(`Substory ID "${sub.id}" collides with existing PRD story \u2014 duplicate IDs are not allowed`);
+    }
+  }
+  for (const sub of substories) {
+    for (const dep of sub.dependencies) {
+      if (!allKnownIds.has(dep)) {
+        errors3.push(`Substory ${sub.id} references non-existent story ID "${dep}"`);
       }
-    } catch {}
-    return "dev";
-  })();
-  NAX_BUILD_INFO = NAX_COMMIT === "dev" ? `v${NAX_VERSION}` : `v${NAX_VERSION} (${NAX_COMMIT})`;
+    }
+  }
+  const cycleErrors = detectCycles(substories);
+  errors3.push(...cycleErrors);
+  return { valid: errors3.length === 0, errors: errors3, warnings: [] };
+}
+
+// src/decompose/validators/overlap.ts
+function extractKeywords2(texts) {
+  const words = texts.join(" ").toLowerCase().split(/[\s,.:;!?()\[\]{}"'`\-_/\\]+/).filter((w) => w.length > 2 && !STOP_WORDS2.has(w) && !/^\d+$/.test(w));
+  return new Set(words);
+}
+function jaccardSimilarity(a, b) {
+  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;
+}
+function substoryKeywords(s) {
+  return extractKeywords2([s.title, ...s.tags]);
+}
+function storyKeywords(s) {
+  return extractKeywords2([s.title, ...s.tags ?? []]);
+}
+function validateOverlap(substories, existingStories) {
+  const errors3 = [];
+  const warnings = [];
+  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) {
+        errors3.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: errors3.length === 0, errors: errors3, warnings };
+}
+var STOP_WORDS2;
+var init_overlap = __esm(() => {
+  STOP_WORDS2 = 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"
+  ]);
+});
+
+// src/decompose/validators/index.ts
+function runAllValidators(originalStory, substories, existingStories, config2) {
+  const existingIds = existingStories.map((s) => s.id);
+  const maxComplexity = config2.maxComplexity ?? "medium";
+  const results = [
+    validateOverlap(substories, existingStories),
+    validateCoverage(originalStory, substories),
+    validateComplexity2(substories, maxComplexity),
+    validateDependencies(substories, existingIds)
+  ];
+  const errors3 = results.flatMap((r) => r.errors);
+  const warnings = results.flatMap((r) => r.warnings);
+  return { valid: errors3.length === 0, errors: errors3, warnings };
+}
+var init_validators = __esm(() => {
+  init_complexity();
+  init_coverage();
+  init_overlap();
+});
+
+// src/decompose/builder.ts
+class DecomposeBuilder {
+  _story;
+  _prd;
+  _scan;
+  _cfg;
+  constructor(story) {
+    this._story = story;
+  }
+  static for(story) {
+    return new DecomposeBuilder(story);
+  }
+  prd(prd) {
+    this._prd = prd;
+    return this;
+  }
+  codebase(scan) {
+    this._scan = scan;
+    return this;
+  }
+  config(cfg) {
+    this._cfg = cfg;
+    return this;
+  }
+  buildPrompt(errorFeedback) {
+    const sections = [];
+    sections.push(buildTargetStorySection(this._story));
+    if (this._prd) {
+      sections.push(buildSiblingStoriesSection(this._story, this._prd));
+    }
+    if (this._scan) {
+      sections.push(buildCodebaseSection(this._scan));
+    }
+    if (this._cfg) {
+      sections.push(buildConstraintsSection(this._cfg));
+    }
+    if (errorFeedback) {
+      sections.push(`## Validation Errors from Previous Attempt
+
+Fix the following errors and try again:
+
+${errorFeedback}`);
+    }
+    return sections.join(SECTION_SEP);
+  }
+  async decompose(adapter) {
+    const cfg = this._cfg;
+    const maxRetries = cfg?.maxRetries ?? 0;
+    const existingStories = this._prd ? this._prd.userStories.filter((s) => s.id !== this._story.id) : [];
+    let lastResult;
+    let errorFeedback;
+    for (let attempt = 0;attempt <= maxRetries; attempt++) {
+      const prompt = this.buildPrompt(errorFeedback);
+      const raw = await adapter.decompose(prompt);
+      const parsed = parseSubStories(raw);
+      if (!parsed.validation.valid) {
+        lastResult = parsed;
+        errorFeedback = parsed.validation.errors.join(`
+`);
+        continue;
+      }
+      const config2 = cfg ?? { maxSubStories: 5, maxComplexity: "medium" };
+      const validation = runAllValidators(this._story, parsed.subStories, existingStories, config2);
+      if (!validation.valid) {
+        lastResult = { subStories: parsed.subStories, validation };
+        errorFeedback = validation.errors.join(`
+`);
+        continue;
+      }
+      return { subStories: parsed.subStories, validation };
+    }
+    return lastResult ?? {
+      subStories: [],
+      validation: { valid: false, errors: ["Decomposition failed after all retries"], warnings: [] }
+    };
+  }
+}
+function parseSubStories(output) {
+  const fenceMatch = output.match(/```(?:json)?\s*(\[[\s\S]*?\])\s*```/);
+  let jsonText = fenceMatch ? fenceMatch[1] : output;
+  if (!fenceMatch) {
+    const arrayMatch = output.match(/\[[\s\S]*\]/);
+    if (arrayMatch) {
+      jsonText = arrayMatch[0];
+    }
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(jsonText.trim());
+  } catch (err) {
+    return {
+      subStories: [],
+      validation: { valid: false, errors: [`Failed to parse JSON: ${err.message}`], warnings: [] }
+    };
+  }
+  if (!Array.isArray(parsed)) {
+    return {
+      subStories: [],
+      validation: { valid: false, errors: ["Output is not a JSON array"], warnings: [] }
+    };
+  }
+  const errors3 = [];
+  const subStories = [];
+  for (const [index, item] of parsed.entries()) {
+    if (typeof item !== "object" || item === null) {
+      errors3.push(`Item at index ${index} is not an object`);
+      continue;
+    }
+    const r = item;
+    subStories.push({
+      id: String(r.id ?? ""),
+      parentStoryId: String(r.parentStoryId ?? ""),
+      title: String(r.title ?? ""),
+      description: String(r.description ?? ""),
+      acceptanceCriteria: Array.isArray(r.acceptanceCriteria) ? r.acceptanceCriteria : [],
+      tags: Array.isArray(r.tags) ? r.tags : [],
+      dependencies: Array.isArray(r.dependencies) ? r.dependencies : [],
+      complexity: normalizeComplexity(r.complexity),
+      nonOverlapJustification: String(r.nonOverlapJustification ?? "")
+    });
+  }
+  return {
+    subStories,
+    validation: { valid: errors3.length === 0, errors: errors3, warnings: [] }
+  };
+}
+function normalizeComplexity(value) {
+  if (value === "simple" || value === "medium" || value === "complex" || value === "expert") {
+    return value;
+  }
+  return "medium";
+}
+var SECTION_SEP = `
+
+---
+
+`;
+var init_builder2 = __esm(() => {
+  init_validators();
 });
 
 // src/prd/types.ts
@@ -19673,7 +20185,7 @@ function getNextStory(prd, currentStoryId, maxRetries) {
     }
   }
   const completedIds = new Set(prd.userStories.filter((s) => s.passes || s.status === "passed" || s.status === "skipped").map((s) => s.id));
-  return prd.userStories.find((s) => !s.passes && s.status !== "passed" && s.status !== "skipped" && s.status !== "blocked" && s.status !== "failed" && s.status !== "paused" && s.dependencies.every((dep) => completedIds.has(dep))) ?? null;
+  return prd.userStories.find((s) => !s.passes && s.status !== "passed" && s.status !== "skipped" && s.status !== "blocked" && s.status !== "failed" && s.status !== "paused" && s.status !== "decomposed" && s.dependencies.every((dep) => completedIds.has(dep))) ?? null;
 }
 function isComplete(prd) {
   return prd.userStories.every((s) => s.passes || s.status === "passed" || s.status === "skipped");
@@ -19683,10 +20195,11 @@ function countStories(prd) {
     total: prd.userStories.length,
     passed: prd.userStories.filter((s) => s.passes || s.status === "passed").length,
     failed: prd.userStories.filter((s) => s.status === "failed").length,
-    pending: prd.userStories.filter((s) => !s.passes && s.status !== "passed" && s.status !== "failed" && s.status !== "skipped" && s.status !== "blocked" && s.status !== "paused").length,
+    pending: prd.userStories.filter((s) => !s.passes && s.status !== "passed" && s.status !== "failed" && s.status !== "skipped" && s.status !== "blocked" && 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
+    paused: prd.userStories.filter((s) => s.status === "paused").length,
+    decomposed: prd.userStories.filter((s) => s.status === "decomposed").length
   };
 }
 function markStoryPassed(prd, storyId) {
@@ -19724,6 +20237,92 @@ var init_prd = __esm(() => {
   PRD_MAX_FILE_SIZE = 5 * 1024 * 1024;
 });
 
+// package.json
+var package_default;
+var init_package = __esm(() => {
+  package_default = {
+    name: "@nathapp/nax",
+    version: "0.33.0",
+    description: "AI Coding Agent Orchestrator \u2014 loops until done",
+    type: "module",
+    bin: {
+      nax: "./dist/nax.js"
+    },
+    scripts: {
+      prepare: "git config core.hooksPath .githooks",
+      dev: "bun run bin/nax.ts",
+      build: 'bun build bin/nax.ts --outdir dist --target bun --define "GIT_COMMIT=\\"$(git rev-parse --short HEAD)\\""',
+      typecheck: "bun x tsc --noEmit",
+      lint: "bun x biome check src/ bin/",
+      test: "NAX_SKIP_PRECHECK=1 bun test test/ --timeout=60000",
+      "test:watch": "bun test --watch",
+      "test:unit": "bun test ./test/unit/ --timeout=60000",
+      "test:integration": "bun test ./test/integration/ --timeout=60000",
+      "test:ui": "bun test ./test/ui/ --timeout=60000",
+      prepublishOnly: "bun run build"
+    },
+    dependencies: {
+      "@anthropic-ai/sdk": "^0.74.0",
+      "@types/react": "^19.2.14",
+      chalk: "^5.6.2",
+      commander: "^13.1.0",
+      ink: "^6.7.0",
+      "ink-spinner": "^5.0.0",
+      "ink-testing-library": "^4.0.0",
+      react: "^19.2.4",
+      zod: "^4.3.6"
+    },
+    devDependencies: {
+      "@biomejs/biome": "^1.9.4",
+      "@types/bun": "^1.3.8",
+      "react-devtools-core": "^7.0.1",
+      typescript: "^5.7.3"
+    },
+    license: "MIT",
+    author: "William Khoo",
+    keywords: [
+      "ai",
+      "agent",
+      "orchestrator",
+      "tdd",
+      "coding"
+    ],
+    files: [
+      "dist/",
+      "src/",
+      "bin/",
+      "README.md",
+      "CHANGELOG.md"
+    ]
+  };
+});
+
+// src/version.ts
+var NAX_VERSION, NAX_COMMIT, NAX_BUILD_INFO;
+var init_version = __esm(() => {
+  init_package();
+  NAX_VERSION = package_default.version;
+  NAX_COMMIT = (() => {
+    try {
+      if (/^[0-9a-f]{6,10}$/.test("f154976"))
+        return "f154976";
+    } catch {}
+    try {
+      const result = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
+        cwd: import.meta.dir,
+        stderr: "ignore"
+      });
+      if (result.exitCode === 0) {
+        const hash2 = result.stdout.toString().trim();
+        if (/^[0-9a-f]{6,10}$/.test(hash2))
+          return hash2;
+      }
+    } catch {}
+    return "dev";
+  })();
+  NAX_BUILD_INFO = NAX_COMMIT === "dev" ? `v${NAX_VERSION}` : `v${NAX_VERSION} (${NAX_COMMIT})`;
+});
+
 // src/errors.ts
 var NaxError, AgentNotFoundError, AgentNotInstalledError, StoryLimitExceededError, LockAcquisitionError;
 var init_errors3 = __esm(() => {
@@ -20015,6 +20614,11 @@ var init_types2 = __esm(() => {
       safety: "yellow",
       defaultSummary: "Human review required for story {{storyId}} \u2014 skip and continue?"
     },
+    "story-oversized": {
+      defaultFallback: "continue",
+      safety: "yellow",
+      defaultSummary: "Story {{storyId}} is oversized ({{criteriaCount}} acceptance criteria) \u2014 decompose into smaller stories?"
+    },
     "story-ambiguity": {
       defaultFallback: "continue",
       safety: "green",
@@ -21103,6 +21707,20 @@ async function checkReviewGate(context, config2, chain) {
   const response = await executeTrigger("review-gate", context, config2, chain);
   return response.action === "approve";
 }
+async function checkStoryOversized(context, config2, chain) {
+  if (!isTriggerEnabled("story-oversized", config2))
+    return "continue";
+  try {
+    const response = await executeTrigger("story-oversized", context, config2, chain);
+    if (response.action === "approve")
+      return "decompose";
+    if (response.action === "skip")
+      return "skip";
+    return "continue";
+  } catch {
+    return "continue";
+  }
+}
 var init_triggers = __esm(() => {
   init_types2();
 });
@@ -21641,7 +22259,8 @@ class ReviewOrchestrator {
               name: reviewer.name,
               passed: result.passed,
               output: result.output,
-              exitCode: result.exitCode
+              exitCode: result.exitCode,
+              findings: result.findings
             });
             if (!result.passed) {
               builtIn.pluginReviewers = pluginResults;
@@ -21697,6 +22316,10 @@ var init_review = __esm(() => {
       const result = await reviewOrchestrator.review(ctx.config.review, ctx.workdir, ctx.config.execution, ctx.plugins);
       ctx.reviewResult = result.builtIn;
       if (!result.success) {
+        const allFindings = result.builtIn.pluginReviewers?.flatMap((pr) => pr.findings ?? []) ?? [];
+        if (allFindings.length > 0) {
+          ctx.reviewFindings = allFindings;
+        }
         if (result.pluginFailed) {
           if (ctx.interaction && isTriggerEnabled("security-review", ctx.config)) {
             const shouldContinue = await _reviewDeps.checkSecurityReview({ featureName: ctx.prd.feature, storyId: ctx.story.id }, ctx.config, ctx.interaction);
@@ -22026,7 +22649,7 @@ var init_constitution2 = __esm(() => {
 });
 
 // src/context/auto-detect.ts
-function extractKeywords(title) {
+function extractKeywords3(title) {
   const stopWords = new Set([
     "the",
     "a",
@@ -22079,7 +22702,7 @@ function extractKeywords(title) {
 async function autoDetectContextFiles(options) {
   const { workdir, storyTitle, maxFiles = 5 } = options;
   const logger = getLogger();
-  const keywords = extractKeywords(storyTitle);
+  const keywords = extractKeywords3(storyTitle);
   if (keywords.length === 0) {
     logger.debug("auto-detect", "No keywords extracted from story title", { storyTitle });
     return [];
@@ -22213,6 +22836,20 @@ function formatPriorFailures(failures) {
         }
       }
     }
+    if (failure.reviewFindings && failure.reviewFindings.length > 0) {
+      parts.push(`
+**Review Findings (fix these issues):**`);
+      for (const finding of failure.reviewFindings) {
+        const source = finding.source ? ` (${finding.source})` : "";
+        parts.push(`
+- **[${finding.severity}]** \`${finding.file}:${finding.line}\`${source}`);
+        parts.push(`  **Rule:** ${finding.ruleId}`);
+        parts.push(`  **Issue:** ${finding.message}`);
+        if (finding.url) {
+          parts.push(`  **Docs:** ${finding.url}`);
+        }
+      }
+    }
     parts.push("");
   }
   return parts.join(`
@@ -22440,7 +23077,7 @@ async function generateTestCoverageSummary(options) {
 var COMMON_TEST_DIRS;
 var init_test_scanner = __esm(() => {
   init_logger2();
-  init_builder2();
+  init_builder3();
   COMMON_TEST_DIRS = ["test", "tests", "__tests__", "src/__tests__", "spec"];
 });
 
@@ -22719,7 +23356,7 @@ ${content}
   }
 }
 var _deps4;
-var init_builder2 = __esm(() => {
+var init_builder3 = __esm(() => {
   init_logger2();
   init_prd();
   init_auto_detect();
@@ -22733,7 +23370,7 @@ var init_builder2 = __esm(() => {
 
 // src/context/index.ts
 var init_context = __esm(() => {
-  init_builder2();
+  init_builder3();
   init_test_scanner();
   init_auto_detect();
 });
@@ -23948,7 +24585,7 @@ ${this._constitution}`);
       sections.push(this._contextMd);
     }
     sections.push(buildConventionsSection());
-    return sections.join(SECTION_SEP);
+    return sections.join(SECTION_SEP2);
   }
   async _resolveRoleBody() {
     if (this._workdir && this._loaderConfig) {
@@ -23970,18 +24607,18 @@ ${this._constitution}`);
     return buildRoleTaskSection(this._role, variant);
   }
 }
-var SECTION_SEP = `
+var SECTION_SEP2 = `
 
 ---
 
 `;
-var init_builder3 = __esm(() => {
+var init_builder4 = __esm(() => {
   init_isolation2();
 });
 
 // src/prompts/index.ts
 var init_prompts2 = __esm(() => {
-  init_builder3();
+  init_builder4();
 });
 
 // src/tdd/session-runner.ts
@@ -25940,9 +26577,25 @@ var init_regression2 = __esm(() => {
 });
 
 // src/pipeline/stages/routing.ts
+async function runDecompose(story, prd, config2, _workdir) {
+  const naxDecompose = config2.decompose;
+  const builderConfig = {
+    maxSubStories: naxDecompose?.maxSubstories ?? 5,
+    maxComplexity: naxDecompose?.maxSubstoryComplexity ?? "medium",
+    maxRetries: naxDecompose?.maxRetries ?? 2
+  };
+  const adapter = {
+    async decompose(_prompt) {
+      throw new Error("[decompose] No LLM adapter configured for story decomposition");
+    }
+  };
+  return DecomposeBuilder.for(story).prd(prd).config(builderConfig).decompose(adapter);
+}
 var routingStage, _routingDeps;
 var init_routing2 = __esm(() => {
   init_greenfield();
+  init_builder2();
+  init_triggers();
   init_logger2();
   init_prd();
   init_routing();
@@ -26011,6 +26664,46 @@ var init_routing2 = __esm(() => {
       if (!isBatch) {
         logger.debug("routing", ctx.routing.reasoning);
       }
+      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 \u2014 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 \u2014 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, 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 \u2014 continuing with original`, {
+                errors: result.validation.errors
+              });
+            }
+          }
+        }
+      }
       return { action: "continue" };
     }
   };
@@ -26020,7 +26713,10 @@ var init_routing2 = __esm(() => {
     isGreenfieldStory,
     clearCache,
     savePRD,
-    computeStoryContentHash
+    computeStoryContentHash,
+    applyDecomposition,
+    runDecompose,
+    checkStoryOversized
   };
 });
 
@@ -27837,12 +28533,13 @@ var init_tier_outcome = __esm(() => {
 });
 
 // src/execution/escalation/tier-escalation.ts
-function buildEscalationFailure(story, currentTier) {
+function buildEscalationFailure(story, currentTier, reviewFindings) {
   return {
     attempt: (story.attempts ?? 0) + 1,
     modelTier: currentTier,
     stage: "escalation",
     summary: `Failed with tier ${currentTier}, escalating to next tier`,
+    reviewFindings: reviewFindings && reviewFindings.length > 0 ? reviewFindings : undefined,
     timestamp: new Date().toISOString()
   };
 }
@@ -27885,6 +28582,7 @@ async function handleTierEscalation(ctx) {
   const storiesToEscalate = ctx.isBatchExecution && escalateWholeBatch ? ctx.storiesToExecute : [ctx.story];
   const escalateRetryAsLite = ctx.pipelineResult.context.retryAsLite === true;
   const escalateFailureCategory = ctx.pipelineResult.context.tddFailureCategory;
+  const escalateReviewFindings = ctx.pipelineResult.context.reviewFindings;
   const escalateRetryAsTestAfter = escalateFailureCategory === "greenfield-no-tests";
   const routingMode = ctx.config.routing.llm?.mode ?? "hybrid";
   if (!nextTier || !ctx.config.autoMode.escalation.enabled) {
@@ -27932,7 +28630,7 @@ async function handleTierEscalation(ctx) {
       const currentStoryTier = s.routing?.modelTier ?? ctx.routing.modelTier;
       const isChangingTier = currentStoryTier !== nextTier;
       const shouldResetAttempts = isChangingTier || shouldSwitchToTestAfter;
-      const escalationFailure = buildEscalationFailure(s, currentStoryTier);
+      const escalationFailure = buildEscalationFailure(s, currentStoryTier, escalateReviewFindings);
       return {
         ...s,
         attempts: shouldResetAttempts ? 0 : (s.attempts ?? 0) + 1,
@@ -30129,10 +30827,7 @@ async function executeSequential(ctx, initialPrd) {
     logger?.info("execution", "Running post-run pipeline (acceptance tests)");
     await runPipeline(postRunPipeline, { config: ctx.config, prd, workdir: ctx.workdir, story: prd.userStories[0] }, ctx.eventEmitter);
     return buildResult("max-iterations");
-  } finally {
-    stopHeartbeat();
-    writeExitSummary(ctx.logFilePath, totalCost, iterations, storiesCompleted, Date.now() - ctx.startTime);
-  }
+  } finally {}
 }
 var init_sequential_executor = __esm(() => {
   init_triggers();
@@ -61663,7 +62358,9 @@ function detectTestPatterns(workdir, dependencies, devDependencies) {
 
 // src/cli/analyze.ts
 init_schema();
+init_builder2();
 init_logger2();
+init_prd();
 init_routing();
 init_version();
 
@@ -64013,7 +64710,14 @@ var FIELD_DESCRIPTIONS = {
   "prompts.overrides.test-writer": 'Path to custom test-writer prompt (e.g., ".nax/prompts/test-writer.md")',
   "prompts.overrides.implementer": 'Path to custom implementer prompt (e.g., ".nax/prompts/implementer.md")',
   "prompts.overrides.verifier": 'Path to custom verifier prompt (e.g., ".nax/prompts/verifier.md")',
-  "prompts.overrides.single-session": 'Path to custom single-session prompt (e.g., ".nax/prompts/single-session.md")'
+  "prompts.overrides.single-session": 'Path to custom single-session prompt (e.g., ".nax/prompts/single-session.md")',
+  decompose: "Story decomposition configuration (SD-003)",
+  "decompose.trigger": "Decomposition trigger mode: auto | confirm | disabled",
+  "decompose.maxAcceptanceCriteria": "Max acceptance criteria before flagging as oversized (default: 6)",
+  "decompose.maxSubstories": "Max number of substories to generate (default: 5)",
+  "decompose.maxSubstoryComplexity": "Max complexity for any generated substory (default: 'medium')",
+  "decompose.maxRetries": "Max retries on decomposition validation failure (default: 2)",
+  "decompose.model": "Model tier for decomposition LLM calls (default: 'balanced')"
 };
 async function loadConfigFile(path13) {
   if (!existsSync20(path13))