@nathapp/nax 0.32.2 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.32.2",
+  "version": "0.34.0",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {

package/src/cli/analyze.ts

@@ -12,7 +12,11 @@ import { getAgent } from "../agents/registry";
 import { scanCodebase } from "../analyze/scanner";
 import type { NaxConfig } from "../config";
 import { resolveModel } from "../config/schema";
+import { applyDecomposition } from "../decompose/apply";
+import { DecomposeBuilder } from "../decompose/builder";
+import type { DecomposeConfig as BuilderDecomposeConfig, DecomposeResult, SubStory } from "../decompose/types";
 import { getLogger } from "../logger";
+import { loadPRD, savePRD } from "../prd";
 import type { PRD, UserStory } from "../prd";
 import { routeTask } from "../routing";
 import { NAX_VERSION } from "../version";
@@ -201,3 +205,144 @@ async function generateAcceptanceTestsForFeature(
     logger.warn("cli", "Failed to generate acceptance tests", { error: (error as Error).message });
   }
 }
+
+// ============================================================================
+// SD-004: Story decompose CLI entry points
+// ============================================================================
+
+/** Default runDecompose implementation — replaced in tests via _decomposeCLIDeps. */
+async function runDecomposeDefault(
+  story: UserStory,
+  prd: PRD,
+  config: NaxConfig,
+  _featureDir: string,
+): Promise<DecomposeResult> {
+  const naxDecompose = config.decompose;
+  const builderConfig: BuilderDecomposeConfig = {
+    maxSubStories: naxDecompose?.maxSubstories ?? 5,
+    maxComplexity: naxDecompose?.maxSubstoryComplexity ?? "medium",
+    maxRetries: naxDecompose?.maxRetries ?? 2,
+  };
+  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);
+}
+
+/** Load PRD from featureDir and return both PRD and resolved path. */
+async function loadPRDFromDir(featureDir: string): Promise<{ prd: PRD; prdPath: string }> {
+  const prdPath = join(featureDir, "prd.json");
+  const prd = await loadPRD(prdPath);
+  return { prd, prdPath };
+}
+
+/** Build a human-readable summary of decomposed substories. */
+function buildSummaryLines(subStories: SubStory[]): string[] {
+  const lines: string[] = ["Decomposed substories:"];
+  for (const sub of subStories) {
+    lines.push(`  ${sub.id}  ${sub.title}  [${sub.complexity}]  parent: ${sub.parentStoryId}`);
+  }
+  return lines;
+}
+
+/** Default print implementation — writes lines to stdout. */
+function printSummaryDefault(lines: string[]): void {
+  for (const line of lines) {
+    process.stdout.write(`${line}\n`);
+  }
+}
+
+/**
+ * Swappable dependencies for CLI decompose functions.
+ * Tests override individual entries without using mock.module().
+ */
+export const _decomposeCLIDeps = {
+  loadPRD: loadPRDFromDir,
+  runDecompose: runDecomposeDefault,
+  applyDecomposition,
+  savePRD,
+  printSummary: printSummaryDefault,
+};
+
+/**
+ * Decompose a single story by ID via --decompose <storyId>.
+ *
+ * Loads the PRD, runs decomposition, applies result, and saves the updated PRD.
+ * Prints a summary table of the generated substories.
+ */
+export async function decomposeStory(
+  storyId: string,
+  options: { featureDir: string; config: NaxConfig },
+): Promise<void> {
+  const { featureDir, config } = options;
+  const logger = getLogger();
+
+  const { prd, prdPath } = await _decomposeCLIDeps.loadPRD(featureDir);
+
+  const story = prd.userStories.find((s) => s.id === storyId);
+  if (!story) {
+    throw new Error(`Story ${storyId} not found in PRD`);
+  }
+
+  const result = await _decomposeCLIDeps.runDecompose(story, prd, config, featureDir);
+
+  if (!result.validation.valid) {
+    logger.warn("cli", `Decompose failed for ${storyId}: ${result.validation.errors.join(", ")}`);
+    return;
+  }
+
+  _decomposeCLIDeps.applyDecomposition(prd, result);
+  await _decomposeCLIDeps.savePRD(prd, prdPath);
+
+  const lines = buildSummaryLines(result.subStories);
+  _decomposeCLIDeps.printSummary(lines);
+}
+
+/**
+ * Decompose all oversized stories via --decompose-oversized.
+ *
+ * Iterates all stories, decomposes any that exceed config.decompose.maxAcceptanceCriteria
+ * AND have complex/expert complexity. Saves the PRD once after all decompositions.
+ */
+export async function decomposeOversized(options: { featureDir: string; config: NaxConfig }): Promise<void> {
+  const { featureDir, config } = options;
+  const logger = getLogger();
+
+  const { prd, prdPath } = await _decomposeCLIDeps.loadPRD(featureDir);
+
+  const threshold = config.decompose?.maxAcceptanceCriteria ?? 6;
+  const oversized = prd.userStories.filter((s) => {
+    const complexity = s.routing?.complexity;
+    return s.acceptanceCriteria.length > threshold && (complexity === "complex" || complexity === "expert");
+  });
+
+  if (oversized.length === 0) {
+    logger.info("cli", "No oversized stories found");
+    return;
+  }
+
+  const allSubStories: SubStory[] = [];
+  let anyDecomposed = false;
+
+  for (const story of oversized) {
+    const result = await _decomposeCLIDeps.runDecompose(story, prd, config, featureDir);
+    if (result.validation.valid) {
+      _decomposeCLIDeps.applyDecomposition(prd, result);
+      allSubStories.push(...result.subStories);
+      anyDecomposed = true;
+    } else {
+      logger.warn("cli", `Decompose failed for ${story.id}: ${result.validation.errors.join(", ")}`);
+    }
+  }
+
+  if (anyDecomposed) {
+    await _decomposeCLIDeps.savePRD(prd, prdPath);
+  }
+
+  if (allSubStories.length > 0) {
+    const lines = buildSummaryLines(allSubStories);
+    _decomposeCLIDeps.printSummary(lines);
+  }
+}

package/src/cli/config.ts

@@ -193,6 +193,15 @@ const FIELD_DESCRIPTIONS: Record<string, string> = {
   "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")',
+
+  // Decompose
+  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')",
 };
 
 /** Options for config command */

package/src/config/defaults.ts

@@ -163,4 +163,12 @@ export const DEFAULT_CONFIG: NaxConfig = {
     },
   },
   prompts: {},
+  decompose: {
+    trigger: "auto",
+    maxAcceptanceCriteria: 6,
+    maxSubstories: 5,
+    maxSubstoryComplexity: "medium",
+    maxRetries: 2,
+    model: "balanced",
+  },
 };

package/src/config/schema.ts

@@ -45,6 +45,7 @@ export type {
   StorySizeGateConfig,
   PrecheckConfig,
   SmartTestRunnerConfig,
+  DecomposeConfig,
   NaxConfig,
 } from "./types";
 

package/src/config/schemas.ts

@@ -300,6 +300,15 @@ const PromptsConfigSchema = z.object({
     .optional(),
 });
 
+const DecomposeConfigSchema = z.object({
+  trigger: z.enum(["auto", "confirm", "disabled"]).default("auto"),
+  maxAcceptanceCriteria: z.number().int().min(1).default(6),
+  maxSubstories: z.number().int().min(1).default(5),
+  maxSubstoryComplexity: z.enum(["simple", "medium", "complex", "expert"]).default("medium"),
+  maxRetries: z.number().int().min(0).default(2),
+  model: z.string().min(1).default("balanced"),
+});
+
 export const NaxConfigSchema = z
   .object({
     version: z.number(),
@@ -321,6 +330,7 @@ export const NaxConfigSchema = z
     interaction: InteractionConfigSchema.optional(),
     precheck: PrecheckConfigSchema.optional(),
     prompts: PromptsConfigSchema.optional(),
+    decompose: DecomposeConfigSchema.optional(),
   })
   .refine((data) => data.version === 1, {
     message: "Invalid version: expected 1",

package/src/config/types.ts

@@ -412,6 +412,22 @@ export interface PromptsConfig {
   overrides?: Partial<Record<"test-writer" | "implementer" | "verifier" | "single-session" | "tdd-simple", string>>;
 }
 
+/** Decompose config (SD-003) */
+export interface DecomposeConfig {
+  /** Trigger mode: 'auto' = decompose automatically, 'confirm' = ask user, 'disabled' = skip */
+  trigger: "auto" | "confirm" | "disabled";
+  /** Max acceptance criteria before flagging a story as oversized (default: 6) */
+  maxAcceptanceCriteria: number;
+  /** Max number of substories to generate (default: 5) */
+  maxSubstories: number;
+  /** Max complexity for any generated substory (default: 'medium') */
+  maxSubstoryComplexity: Complexity;
+  /** Max retries on decomposition validation failure (default: 2) */
+  maxRetries: number;
+  /** Model tier for decomposition LLM calls (default: 'balanced') */
+  model: ModelTier;
+}
+
 /** Full nax configuration */
 export interface NaxConfig {
   /** Schema version */
@@ -452,6 +468,8 @@ export interface NaxConfig {
   precheck?: PrecheckConfig;
   /** Prompt override settings (PB-003) */
   prompts?: PromptsConfig;
+  /** Decompose settings (SD-003) */
+  decompose?: DecomposeConfig;
 }
 
 /** Resolve a ModelEntry (string shorthand or full object) into a ModelDef */

package/src/context/elements.ts

@@ -83,6 +83,19 @@ export function formatPriorFailures(failures: StructuredFailure[]): string {
         }
       }
     }
+
+    if (failure.reviewFindings && failure.reviewFindings.length > 0) {
+      parts.push("\n**Review Findings (fix these issues):**");
+      for (const finding of failure.reviewFindings) {
+        const source = finding.source ? ` (${finding.source})` : "";
+        parts.push(`\n- **[${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("");
   }
 

package/src/context/greenfield.ts

@@ -69,7 +69,7 @@ function globToRegex(pattern: string): RegExp {
     .replace(/\{([^}]+)\}/g, (_, group) => `(${group.replace(/,/g, "|")})`) // {a,b} = (a|b)
     .replace(/\\\.\\\*/g, "\\.[^/]*"); // Fix escaped .* back to .\*
 
-  return new RegExp(`${regexStr}$`);
+  return new RegExp(`${regexStr}$`); // nosemgrep: detect-non-literal-regexp — pattern from internal .gitignore, not user input
 }
 
 /**

package/src/decompose/apply.ts

@@ -0,0 +1,44 @@
+/**
+ * PRD Mutation — Apply Decomposition (SD-003)
+ *
+ * Marks the original story as 'decomposed', inserts substories after the
+ * original with status 'pending' and parentStoryId.
+ */
+
+import type { PRD, UserStory } from "../prd";
+import type { DecomposeResult } from "./types";
+
+/**
+ * Apply a decomposition result to a PRD:
+ * - Marks the original story as 'decomposed'
+ * - Inserts substories after the original with status 'pending' and parentStoryId
+ */
+export function applyDecomposition(prd: PRD, result: DecomposeResult): void {
+  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;
+
+  // Mark original story as decomposed
+  prd.userStories[originalIndex].status = "decomposed";
+
+  // Convert substories to UserStory format with parentStoryId attached
+  const newStories = subStories.map((sub): UserStory & { parentStoryId: string } => ({
+    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,
+  }));
+
+  // Insert substories immediately after the original story
+  prd.userStories.splice(originalIndex + 1, 0, ...newStories);
+}

package/src/decompose/builder.ts

@@ -0,0 +1,181 @@
+/**
+ * DecomposeBuilder — fluent API for composing story decomposition prompts.
+ *
+ * Usage:
+ *   const result = await DecomposeBuilder.for(story)
+ *     .prd(prd)
+ *     .codebase(scan)
+ *     .config(cfg)
+ *     .decompose(adapter);
+ */
+
+import type { CodebaseScan } from "../analyze/types";
+import type { PRD, UserStory } from "../prd";
+import { buildCodebaseSection } from "./sections/codebase";
+import { buildConstraintsSection } from "./sections/constraints";
+import { buildSiblingStoriesSection } from "./sections/sibling-stories";
+import { buildTargetStorySection } from "./sections/target-story";
+import type { DecomposeAdapter, DecomposeConfig, DecomposeResult, SubStory } from "./types";
+import { runAllValidators } from "./validators/index";
+
+export const SECTION_SEP = "\n\n---\n\n";
+
+export class DecomposeBuilder {
+  private _story: UserStory;
+  private _prd: PRD | undefined;
+  private _scan: CodebaseScan | undefined;
+  private _cfg: DecomposeConfig | undefined;
+
+  private constructor(story: UserStory) {
+    this._story = story;
+  }
+
+  static for(story: UserStory): DecomposeBuilder {
+    return new DecomposeBuilder(story);
+  }
+
+  prd(prd: PRD): this {
+    this._prd = prd;
+    return this;
+  }
+
+  codebase(scan: CodebaseScan): this {
+    this._scan = scan;
+    return this;
+  }
+
+  config(cfg: DecomposeConfig): this {
+    this._cfg = cfg;
+    return this;
+  }
+
+  buildPrompt(errorFeedback?: string): string {
+    const sections: string[] = [];
+
+    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\n\nFix the following errors and try again:\n\n${errorFeedback}`,
+      );
+    }
+
+    return sections.join(SECTION_SEP);
+  }
+
+  async decompose(adapter: DecomposeAdapter): Promise<DecomposeResult> {
+    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: DecomposeResult | undefined;
+    let errorFeedback: string | undefined;
+
+    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("\n");
+        continue;
+      }
+
+      // Run post-parse validators
+      const config: DecomposeConfig = cfg ?? { maxSubStories: 5, maxComplexity: "medium" };
+      const validation = runAllValidators(this._story, parsed.subStories, existingStories, config);
+
+      if (!validation.valid) {
+        lastResult = { subStories: parsed.subStories, validation };
+        errorFeedback = validation.errors.join("\n");
+        continue;
+      }
+
+      return { subStories: parsed.subStories, validation };
+    }
+
+    return (
+      lastResult ?? {
+        subStories: [],
+        validation: { valid: false, errors: ["Decomposition failed after all retries"], warnings: [] },
+      }
+    );
+  }
+}
+
+function parseSubStories(output: string): DecomposeResult {
+  // Extract JSON array (handles optional markdown code fences)
+  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: unknown;
+  try {
+    parsed = JSON.parse(jsonText.trim());
+  } catch (err) {
+    return {
+      subStories: [],
+      validation: { valid: false, errors: [`Failed to parse JSON: ${(err as Error).message}`], warnings: [] },
+    };
+  }
+
+  if (!Array.isArray(parsed)) {
+    return {
+      subStories: [],
+      validation: { valid: false, errors: ["Output is not a JSON array"], warnings: [] },
+    };
+  }
+
+  const errors: string[] = [];
+  const subStories: SubStory[] = [];
+
+  for (const [index, item] of parsed.entries()) {
+    if (typeof item !== "object" || item === null) {
+      errors.push(`Item at index ${index} is not an object`);
+      continue;
+    }
+    const r = item as Record<string, unknown>;
+    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 as string[]) : [],
+      tags: Array.isArray(r.tags) ? (r.tags as string[]) : [],
+      dependencies: Array.isArray(r.dependencies) ? (r.dependencies as string[]) : [],
+      complexity: normalizeComplexity(r.complexity),
+      nonOverlapJustification: String(r.nonOverlapJustification ?? ""),
+    });
+  }
+
+  return {
+    subStories,
+    validation: { valid: errors.length === 0, errors, warnings: [] },
+  };
+}
+
+function normalizeComplexity(value: unknown): "simple" | "medium" | "complex" | "expert" {
+  if (value === "simple" || value === "medium" || value === "complex" || value === "expert") {
+    return value;
+  }
+  return "medium";
+}

package/src/decompose/index.ts

@@ -0,0 +1,8 @@
+export { DecomposeBuilder, SECTION_SEP } from "./builder";
+export type { DecomposeConfig, DecomposeResult, SubStory, ValidationResult, DecomposeAdapter } from "./types";
+export {
+  buildTargetStorySection,
+  buildSiblingStoriesSection,
+  buildCodebaseSection,
+  buildConstraintsSection,
+} from "./sections";

package/src/decompose/sections/codebase.ts

@@ -0,0 +1,26 @@
+/**
+ * Codebase context section builder.
+ *
+ * Builds a prompt section from scanCodebase output.
+ */
+
+import type { CodebaseScan } from "../../analyze/types";
+
+export function buildCodebaseSection(scan: CodebaseScan): string {
+  const deps = Object.entries(scan.dependencies)
+    .slice(0, 15)
+    .map(([k, v]) => `  ${k}: ${v}`)
+    .join("\n");
+
+  return [
+    "# Codebase Context",
+    "",
+    "**File Tree:**",
+    scan.fileTree,
+    "",
+    "**Dependencies:**",
+    deps || "  (none)",
+    "",
+    `**Test Patterns:** ${scan.testPatterns.join(", ")}`,
+  ].join("\n");
+}

package/src/decompose/sections/constraints.ts

@@ -0,0 +1,32 @@
+/**
+ * Constraints section builder.
+ *
+ * Builds a prompt section with decomposition constraints:
+ * max substories, max complexity, output JSON schema, nonOverlapJustification requirement.
+ */
+
+import type { DecomposeConfig } from "../types";
+
+export function buildConstraintsSection(config: DecomposeConfig): string {
+  return [
+    "# Decomposition Constraints",
+    "",
+    `- **Max sub-stories:** ${config.maxSubStories}`,
+    `- **Max complexity per sub-story:** ${config.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("\n");
+}

package/src/decompose/sections/index.ts

@@ -0,0 +1,4 @@
+export { buildTargetStorySection } from "./target-story";
+export { buildSiblingStoriesSection } from "./sibling-stories";
+export { buildCodebaseSection } from "./codebase";
+export { buildConstraintsSection } from "./constraints";

package/src/decompose/sections/sibling-stories.ts

@@ -0,0 +1,25 @@
+/**
+ * Sibling stories section builder.
+ *
+ * Builds a prompt section with all other PRD stories (id, title, status, AC summary)
+ * to help the LLM avoid overlap.
+ */
+
+import type { PRD, UserStory } from "../../prd";
+
+export function buildSiblingStoriesSection(targetStory: UserStory, prd: PRD): string {
+  const siblings = prd.userStories.filter((s) => s.id !== targetStory.id);
+
+  if (siblings.length === 0) {
+    return "# Sibling Stories\n\nNo other stories exist in this PRD.";
+  }
+
+  const entries = siblings
+    .map((s) => {
+      const acSummary = s.acceptanceCriteria.slice(0, 3).join("; ");
+      return `- **${s.id}** — ${s.title} [${s.status}]\n  AC: ${acSummary}`;
+    })
+    .join("\n");
+
+  return ["# Sibling Stories", "", "Avoid overlapping with these existing stories in the PRD:", "", entries].join("\n");
+}

package/src/decompose/sections/target-story.ts

@@ -0,0 +1,31 @@
+/**
+ * Target story section builder.
+ *
+ * Builds a prompt section with full story details and decompose instruction.
+ */
+
+import type { UserStory } from "../../prd";
+
+export function buildTargetStorySection(story: UserStory): string {
+  const ac = story.acceptanceCriteria.map((c, i) => `${i + 1}. ${c}`).join("\n");
+  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("\n");
+}