@nathapp/nax 0.18.1

package/src/prd/index.ts

@@ -0,0 +1,172 @@
+/**
+ * PRD Operations
+ */
+
+import { existsSync, statSync } from "node:fs";
+import type { FailureCategory } from "../tdd/types";
+import type { PRD, UserStory } from "./types";
+
+export type { PRD, UserStory, StoryRouting, StoryStatus, EscalationAttempt } from "./types";
+export { isStalled, markStoryAsBlocked, generateHumanHaltSummary, getContextFiles, getExpectedFiles } from "./types";
+export type { FailureCategory } from "../tdd/types";
+
+/** Maximum PRD file size (5MB) - reject larger PRDs to prevent memory issues */
+export const PRD_MAX_FILE_SIZE = 5 * 1024 * 1024;
+
+/** Load PRD from file */
+export async function loadPRD(path: string): Promise<PRD> {
+  if (!existsSync(path)) {
+    throw new Error(`PRD file not found: ${path}`);
+  }
+
+  // Check file size to prevent loading oversized PRDs
+  const stats = statSync(path);
+  if (stats.size > PRD_MAX_FILE_SIZE) {
+    const sizeMB = (stats.size / (1024 * 1024)).toFixed(2);
+    const limitMB = (PRD_MAX_FILE_SIZE / (1024 * 1024)).toFixed(2);
+    throw new Error(
+      `PRD file is too large (${sizeMB} MB exceeds ${limitMB} MB limit). Split this feature into smaller features or reduce story count.`,
+    );
+  }
+
+  const prd: PRD = await Bun.file(path).json();
+
+  // BUG-21: Normalize story fields to prevent null/undefined arithmetic issues
+  // BUG-004: Auto-default optional PRD fields in-memory (tags, status, acceptanceCriteria, storyPoints)
+  for (const story of prd.userStories) {
+    story.attempts = story.attempts ?? 0;
+    story.priorErrors = story.priorErrors ?? [];
+    story.escalations = story.escalations ?? [];
+    story.dependencies = story.dependencies ?? [];
+    story.tags = story.tags ?? [];
+    story.status = story.status ?? "pending";
+    story.acceptanceCriteria = story.acceptanceCriteria ?? [];
+    story.storyPoints = story.storyPoints ?? 1;
+  }
+
+  return prd;
+}
+
+/** Save PRD to file */
+export async function savePRD(prd: PRD, path: string): Promise<void> {
+  prd.updatedAt = new Date().toISOString();
+  await Bun.write(path, JSON.stringify(prd, null, 2));
+}
+
+/**
+ * Get the next story to work on.
+ *
+ * Priority 1 (retry): If `currentStoryId` is provided and that story has
+ * `status === "failed"` with `attempts <= maxRetries`, return it immediately
+ * so the executor retries the same story before moving on.
+ *
+ * Priority 2 (normal): First pending story whose dependencies are satisfied.
+ *
+ * @param prd - PRD containing all stories
+ * @param currentStoryId - ID of the story just executed (optional)
+ * @param maxRetries - Max retry attempts per story before giving up (optional)
+ */
+export function getNextStory(prd: PRD, currentStoryId?: string | null, maxRetries?: number): UserStory | null {
+  // Priority 1: Retry current story if failed but has attempts remaining
+  if (currentStoryId != null && maxRetries != null && maxRetries > 0) {
+    const currentStory = prd.userStories.find((s) => s.id === currentStoryId);
+    if (currentStory && currentStory.status === "failed" && (currentStory.attempts ?? 0) <= maxRetries) {
+      return currentStory;
+    }
+  }
+
+  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
+  );
+}
+
+/**
+ * Check if all stories are complete (passed or skipped).
+ *
+ * @design Does NOT account for blocked/failed stories — a PRD with blocked stories
+ * is NOT complete. Use `isStalled()` separately to detect when forward progress
+ * is impossible (all remaining stories blocked or depend on blocked).
+ */
+export function isComplete(prd: PRD): boolean {
+  return prd.userStories.every((s) => s.passes || s.status === "passed" || s.status === "skipped");
+}
+
+/** Count stories by status */
+export function countStories(prd: PRD): {
+  total: number;
+  passed: number;
+  failed: number;
+  pending: number;
+  skipped: number;
+  blocked: number;
+  paused: number;
+} {
+  return {
+    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,
+    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,
+  };
+}
+
+/** Mark a story as passed */
+export function markStoryPassed(prd: PRD, storyId: string): void {
+  const story = prd.userStories.find((s) => s.id === storyId);
+  if (story) {
+    story.passes = true;
+    story.status = "passed";
+  }
+}
+
+/** Mark a story as failed */
+export function markStoryFailed(prd: PRD, storyId: string, failureCategory?: FailureCategory): void {
+  const story = prd.userStories.find((s) => s.id === storyId);
+  if (story) {
+    story.status = "failed";
+    story.attempts += 1;
+    if (failureCategory !== undefined) {
+      story.failureCategory = failureCategory;
+    }
+  }
+}
+
+/** Mark a story as skipped */
+export function markStorySkipped(prd: PRD, storyId: string): void {
+  const story = prd.userStories.find((s) => s.id === storyId);
+  if (story) {
+    story.status = "skipped";
+  }
+}
+
+/** Mark a story as paused */
+export function markStoryPaused(prd: PRD, storyId: string): void {
+  const story = prd.userStories.find((s) => s.id === storyId);
+  if (story) {
+    story.status = "paused";
+    story.attempts = (story.attempts ?? 0) + 1;
+  }
+}

package/src/prd/types.ts

@@ -0,0 +1,202 @@
+/**
+ * PRD (Product Requirements Document) Types
+ *
+ * Machine-readable task state for orchestration.
+ */
+
+import type { Complexity, TestStrategy } from "../config";
+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";
+
+/** Routing metadata per story */
+export interface StoryRouting {
+  complexity: Complexity;
+  /** Model tier (derived at runtime from config, not persisted) */
+  modelTier?: ModelTier;
+  testStrategy: TestStrategy;
+  reasoning: string;
+  estimatedCost?: number;
+  /** Estimated lines of code (from LLM classifier) */
+  estimatedLOC?: number;
+  /** Implementation risks (from LLM classifier) */
+  risks?: string[];
+  /** Classification strategy used */
+  strategy?: "keyword" | "llm";
+  /** Model used for classification (if LLM strategy) */
+  llmModel?: string;
+}
+
+/** Escalation attempt tracking */
+export interface EscalationAttempt {
+  fromTier: ModelTier;
+  toTier: ModelTier;
+  reason: string;
+  timestamp: string;
+}
+
+/** A single user story */
+export interface UserStory {
+  /** Story ID (e.g., "US-001") */
+  id: string;
+  /** Story title */
+  title: string;
+  /** Story description */
+  description: string;
+  /** Acceptance criteria */
+  acceptanceCriteria: string[];
+  /** Tags for routing (e.g., ["security", "public-api"]) */
+  tags: string[];
+  /** Dependencies (story IDs that must complete first) */
+  dependencies: string[];
+  /** Current status */
+  status: StoryStatus;
+  /** Whether all acceptance criteria pass */
+  passes: boolean;
+  /** Routing metadata (set during analyze phase) */
+  routing?: StoryRouting;
+  /** Escalation history */
+  escalations: EscalationAttempt[];
+  /** Number of attempts */
+  attempts: number;
+  /** Story points estimate (optional, defaults to 1) */
+  storyPoints?: number;
+  /** @deprecated Use contextFiles instead. Relevant source files for context injection */
+  relevantFiles?: string[];
+  /** Files loaded into agent prompt before execution */
+  contextFiles?: string[];
+  /** Files that must exist after execution (pre-flight gate) */
+  expectedFiles?: string[];
+  /** Prior error messages from failed attempts */
+  priorErrors?: string[];
+  /** Custom context strings */
+  customContext?: string[];
+  /** Category of the last failure (set when story is marked failed) */
+  failureCategory?: FailureCategory;
+  /** Worktree path for parallel execution (set when --parallel is used) */
+  worktreePath?: string;
+}
+
+// ============================================================================
+// Resolver Functions
+// ============================================================================
+
+/**
+ * Get files to load into agent prompt before execution.
+ * Falls back to relevantFiles for backward compatibility.
+ */
+export function getContextFiles(story: UserStory): string[] {
+  return story.contextFiles ?? story.relevantFiles ?? [];
+}
+
+/**
+ * Get files that must exist after execution (pre-flight gate).
+ * Does NOT fall back to relevantFiles. Asset check is opt-in only.
+ */
+export function getExpectedFiles(story: UserStory): string[] {
+  return story.expectedFiles ?? [];
+}
+
+// ============================================================================
+// ADR-003: Stall Detection Helpers
+// ============================================================================
+
+/**
+ * Check if a PRD run is stalled — all remaining stories are blocked, paused, or
+ * depend on blocked/paused stories, making forward progress impossible.
+ */
+export function isStalled(prd: PRD): boolean {
+  const remaining = prd.userStories.filter((s) => s.status !== "passed" && s.status !== "skipped");
+  if (remaining.length === 0) return false;
+
+  const blockedIds = new Set(
+    prd.userStories
+      .filter((s) => s.status === "blocked" || s.status === "failed" || s.status === "paused")
+      .map((s) => s.id),
+  );
+
+  return remaining.every(
+    (s) =>
+      s.status === "blocked" ||
+      s.status === "failed" ||
+      s.status === "paused" ||
+      s.dependencies.some((dep) => blockedIds.has(dep)),
+  );
+}
+
+/**
+ * Mark a story as blocked (e.g., dependency failed, unresolvable issue).
+ */
+export function markStoryAsBlocked(prd: PRD, storyId: string, reason: string): void {
+  const story = prd.userStories.find((s) => s.id === storyId);
+  if (story) {
+    story.status = "blocked";
+    story.priorErrors = [...(story.priorErrors || []), `BLOCKED: ${reason}`];
+  }
+}
+
+/**
+ * Generate a human-readable summary when all progress is stalled.
+ */
+export function generateHumanHaltSummary(prd: PRD): string {
+  const blocked = prd.userStories.filter((s) => s.status === "blocked");
+  const failed = prd.userStories.filter((s) => s.status === "failed");
+  const paused = prd.userStories.filter((s) => s.status === "paused");
+  const pending = prd.userStories.filter((s) => s.status === "pending" || s.status === "in-progress");
+
+  const lines = [
+    `🛑 STALLED: ${prd.feature}`,
+    "",
+    `Blocked (${blocked.length}):`,
+    ...blocked.map((s) => `  ${s.id}: ${s.title} — ${s.priorErrors?.slice(-1)[0] || "unknown"}`),
+    "",
+    `Failed (${failed.length}):`,
+    ...failed.map((s) => `  ${s.id}: ${s.title} — ${s.priorErrors?.slice(-1)[0] || "unknown"}`),
+    "",
+    `Paused (${paused.length}):`,
+    ...paused.map((s) => `  ${s.id}: ${s.title} — ${s.priorErrors?.slice(-1)[0] || "user paused"}`),
+  ];
+
+  if (pending.length > 0) {
+    lines.push(
+      "",
+      `Waiting on blocked/paused dependencies (${pending.length}):`,
+      ...pending.map((s) => `  ${s.id}: ${s.title} — depends on: ${s.dependencies.join(", ")}`),
+    );
+  }
+
+  return lines.join("\n");
+}
+
+/** The full PRD document */
+export interface PRD {
+  /** Project name */
+  project: string;
+  /** Feature name */
+  feature: string;
+  /** Git branch name */
+  branchName: string;
+  /** Creation timestamp */
+  createdAt: string;
+  /** Last updated timestamp */
+  updatedAt: string;
+  /** All user stories */
+  userStories: UserStory[];
+  /** Configuration used during analyze phase */
+  analyzeConfig?: {
+    /** nax version that generated this PRD */
+    naxVersion: string;
+    /** Model tier used for analysis */
+    model: string;
+    /** Whether LLM-enhanced decomposition was used */
+    llmEnhanced: boolean;
+    /** Maximum stories per feature (from config) */
+    maxStoriesPerFeature: number;
+    /** Routing strategy used */
+    routingStrategy: "keyword" | "llm";
+  };
+  /** Acceptance test overrides (AC-N → reason for accepting despite test failure) */
+  acceptanceOverrides?: Record<string, string>;
+}