@nathapp/nax 0.18.1

package/src/tdd/types.ts

@@ -0,0 +1,81 @@
+/** TDD session role */
+export type TddSessionRole = "test-writer" | "implementer" | "verifier";
+
+/** Failure categories for TDD orchestrator results */
+export type FailureCategory =
+  /** Test-writer violated file isolation or created no test files */
+  | "isolation-violation"
+  /** A session crashed, timed out, or the agent failed to produce usable output */
+  | "session-failure"
+  /** Tests were written and implemented but still fail after all sessions */
+  | "tests-failing"
+  /** Verifier explicitly rejected the implementation */
+  | "verifier-rejected"
+  /** Greenfield project with no test files — TDD not applicable (BUG-010) */
+  | "greenfield-no-tests";
+
+/** Isolation verification result */
+export interface IsolationCheck {
+  /** Whether isolation passed (no hard violations) */
+  passed: boolean;
+  /** Hard violation files (files that must not be modified) */
+  violations: string[];
+  /** Soft violation files (allowed-path overrides, warning only) */
+  softViolations?: string[];
+  /** Warning files (e.g., implementer touching test files slightly) */
+  warnings?: string[];
+  /** Human-readable description of what was checked */
+  description?: string;
+}
+
+/** Result of a single TDD session */
+export interface TddSessionResult {
+  /** Session role */
+  role: TddSessionRole;
+  /** Whether session completed successfully */
+  success: boolean;
+  /** Isolation check results (if applicable) */
+  isolation?: IsolationCheck;
+  /** Cost of this session (USD) */
+  estimatedCost: number;
+  /** Files changed by this session (from git diff) */
+  filesChanged: string[];
+  /** Duration of this session in milliseconds */
+  durationMs: number;
+  /** Git branch created/used (optional legacy field) */
+  branch?: string;
+  /** ISO timestamp (optional legacy field) */
+  timestamp?: string;
+  /** Error message (if success=false) */
+  error?: string;
+  /** Number of tests written/passed/failed */
+  tests?: {
+    total: number;
+    passed: number;
+    failed: number;
+  };
+}
+
+/** Result of a three-session TDD orchestration */
+export interface ThreeSessionTddResult {
+  /** Overall success */
+  success: boolean;
+  /** Individual session results */
+  sessions: TddSessionResult[];
+  /** Whether human review is needed */
+  needsHumanReview: boolean;
+  /** Reason for review (if any) */
+  reviewReason?: string;
+  /** Total cost of all sessions (USD) */
+  totalCost: number;
+  /** Whether lite mode was used (skips test-writer/implementer isolation) */
+  lite: boolean;
+  /** Category of failure (if success is false) */
+  failureCategory?: FailureCategory;
+  /**
+   * Verifier verdict parsed from .nax-verifier-verdict.json (for logging/debugging).
+   * null      = verdict file was missing or malformed (no verdict available)
+   * undefined = verdict was not attempted (e.g. early-exit before session 3 ran)
+   */
+  verdict?: import("./verdict").VerifierVerdict | null;
+}

package/src/tdd/verdict.ts

@@ -0,0 +1,271 @@
+/**
+ * Verifier Verdict — types and reader
+ *
+ * The verifier (session 3) writes a structured verdict file to
+ * `.nax-verifier-verdict.json` in the workdir. This module reads,
+ * validates, and interprets that verdict.
+ */
+
+import { unlink } from "node:fs/promises";
+import path from "node:path";
+import { getLogger } from "../logger";
+import type { FailureCategory } from "./types";
+
+/** File name written by the verifier agent */
+export const VERDICT_FILE = ".nax-verifier-verdict.json";
+
+/** Structured verdict written by the verifier (session 3) */
+export interface VerifierVerdict {
+  /** Schema version */
+  version: 1;
+
+  /** Overall approval */
+  approved: boolean;
+
+  /** Test results */
+  tests: {
+    /** Did all tests pass? */
+    allPassing: boolean;
+    /** Number of passing tests */
+    passCount: number;
+    /** Number of failing tests */
+    failCount: number;
+  };
+
+  /** Implementer test modification review */
+  testModifications: {
+    /** Were test files modified by implementer? */
+    detected: boolean;
+    /** List of modified test files */
+    files: string[];
+    /** Are the modifications legitimate? */
+    legitimate: boolean;
+    /** Reasoning for legitimacy judgment */
+    reasoning: string;
+  };
+
+  /** Acceptance criteria check */
+  acceptanceCriteria: {
+    /** All criteria met? */
+    allMet: boolean;
+    /** Per-criterion status */
+    criteria: Array<{
+      criterion: string;
+      met: boolean;
+      note?: string;
+    }>;
+  };
+
+  /** Code quality assessment */
+  quality: {
+    /** Overall quality: good | acceptable | poor */
+    rating: "good" | "acceptable" | "poor";
+    /** Issues found */
+    issues: string[];
+  };
+
+  /** Fixes applied by the verifier */
+  fixes: string[];
+
+  /** Overall reasoning */
+  reasoning: string;
+}
+
+/**
+ * Validate that a parsed object has the required fields for a VerifierVerdict.
+ * Returns true if the object appears to be a valid verdict.
+ */
+function isValidVerdict(obj: unknown): obj is VerifierVerdict {
+  if (!obj || typeof obj !== "object") return false;
+  const v = obj as Record<string, unknown>;
+
+  // Required top-level fields
+  if (v.version !== 1) return false;
+  if (typeof v.approved !== "boolean") return false;
+
+  // tests sub-object
+  if (!v.tests || typeof v.tests !== "object") return false;
+  const tests = v.tests as Record<string, unknown>;
+  if (typeof tests.allPassing !== "boolean") return false;
+  if (typeof tests.passCount !== "number") return false;
+  if (typeof tests.failCount !== "number") return false;
+
+  // testModifications sub-object
+  if (!v.testModifications || typeof v.testModifications !== "object") return false;
+  const mods = v.testModifications as Record<string, unknown>;
+  if (typeof mods.detected !== "boolean") return false;
+  if (!Array.isArray(mods.files)) return false;
+  if (typeof mods.legitimate !== "boolean") return false;
+  if (typeof mods.reasoning !== "string") return false;
+
+  // acceptanceCriteria sub-object
+  if (!v.acceptanceCriteria || typeof v.acceptanceCriteria !== "object") return false;
+  const ac = v.acceptanceCriteria as Record<string, unknown>;
+  if (typeof ac.allMet !== "boolean") return false;
+  if (!Array.isArray(ac.criteria)) return false;
+
+  // quality sub-object
+  if (!v.quality || typeof v.quality !== "object") return false;
+  const quality = v.quality as Record<string, unknown>;
+  if (!["good", "acceptable", "poor"].includes(quality.rating as string)) return false;
+  if (!Array.isArray(quality.issues)) return false;
+
+  // fixes and reasoning
+  if (!Array.isArray(v.fixes)) return false;
+  if (typeof v.reasoning !== "string") return false;
+
+  return true;
+}
+
+/**
+ * Read the verifier verdict file from the workdir.
+ *
+ * Returns the parsed VerifierVerdict when the file exists and is valid.
+ * Returns null if:
+ * - File does not exist
+ * - File is not valid JSON
+ * - Required fields are missing or invalid
+ *
+ * Never throws.
+ */
+export async function readVerdict(workdir: string): Promise<VerifierVerdict | null> {
+  const logger = getLogger();
+  const verdictPath = path.join(workdir, VERDICT_FILE);
+
+  try {
+    const file = Bun.file(verdictPath);
+    const exists = await file.exists();
+    if (!exists) {
+      return null;
+    }
+
+    let parsed: unknown;
+    try {
+      parsed = await file.json();
+    } catch (parseErr) {
+      logger.warn("tdd", "Verifier verdict file is not valid JSON — ignoring", {
+        path: verdictPath,
+        error: String(parseErr),
+      });
+      return null;
+    }
+
+    if (!isValidVerdict(parsed)) {
+      logger.warn("tdd", "Verifier verdict file missing required fields — ignoring", {
+        path: verdictPath,
+      });
+      return null;
+    }
+
+    return parsed;
+  } catch (err) {
+    logger.warn("tdd", "Failed to read verifier verdict file — ignoring", {
+      path: verdictPath,
+      error: String(err),
+    });
+    return null;
+  }
+}
+
+/**
+ * Delete the verifier verdict file from the workdir.
+ * Ignores all errors (file may not exist, permissions, etc.).
+ */
+export async function cleanupVerdict(workdir: string): Promise<void> {
+  const verdictPath = path.join(workdir, VERDICT_FILE);
+  try {
+    await unlink(verdictPath);
+  } catch {
+    // Intentionally ignored — file may not exist or already be deleted
+  }
+}
+
+/** Result of categorizing a verifier verdict */
+export interface VerdictCategorization {
+  success: boolean;
+  failureCategory?: FailureCategory;
+  reviewReason?: string;
+}
+
+/**
+ * Categorize a verifier verdict into a success/failure outcome.
+ *
+ * @param verdict - The parsed verdict (or null if not available)
+ * @param testsPass - Fallback: whether tests pass independently (used when verdict is null)
+ * @returns Categorized outcome with optional failureCategory and reviewReason
+ *
+ * Logic:
+ * - verdict.approved = true → success
+ * - Not approved, illegitimate test mods → verifier-rejected
+ * - Not approved, tests failing → tests-failing
+ * - Not approved, criteria not met → verifier-rejected
+ * - Not approved, poor quality → verifier-rejected
+ * - Not approved, other → verifier-rejected (catch-all)
+ * - null verdict, testsPass=true → success
+ * - null verdict, testsPass=false → tests-failing
+ */
+export function categorizeVerdict(verdict: VerifierVerdict | null, testsPass: boolean): VerdictCategorization {
+  // No verdict — fall back to test-only check
+  if (!verdict) {
+    if (testsPass) {
+      return { success: true };
+    }
+    return {
+      success: false,
+      failureCategory: "tests-failing",
+      reviewReason: "Tests failing after all sessions (no verdict file)",
+    };
+  }
+
+  // Approved
+  if (verdict.approved) {
+    return { success: true };
+  }
+
+  // Not approved — classify the reason
+
+  // 1. Illegitimate test modifications (implementer cheated)
+  if (verdict.testModifications.detected && !verdict.testModifications.legitimate) {
+    const files = verdict.testModifications.files.join(", ") || "unknown files";
+    return {
+      success: false,
+      failureCategory: "verifier-rejected",
+      reviewReason: `Verifier rejected: illegitimate test modifications in ${files}. ${verdict.testModifications.reasoning}`,
+    };
+  }
+
+  // 2. Tests failing
+  if (!verdict.tests.allPassing) {
+    return {
+      success: false,
+      failureCategory: "tests-failing",
+      reviewReason: `Tests failing: ${verdict.tests.failCount} failure(s). ${verdict.reasoning}`,
+    };
+  }
+
+  // 3. Acceptance criteria not met
+  if (!verdict.acceptanceCriteria.allMet) {
+    const unmet = verdict.acceptanceCriteria.criteria.filter((c) => !c.met).map((c) => c.criterion);
+    return {
+      success: false,
+      failureCategory: "verifier-rejected",
+      reviewReason: `Acceptance criteria not met: ${unmet.join("; ")}`,
+    };
+  }
+
+  // 4. Poor quality
+  if (verdict.quality.rating === "poor") {
+    return {
+      success: false,
+      failureCategory: "verifier-rejected",
+      reviewReason: `Poor code quality: ${verdict.quality.issues.join("; ")}`,
+    };
+  }
+
+  // Catch-all: verdict says not approved but no clear specific reason
+  return {
+    success: false,
+    failureCategory: "verifier-rejected",
+    reviewReason: verdict.reasoning || "Verifier rejected without specific reason",
+  };
+}

package/src/tui/App.tsx

@@ -0,0 +1,265 @@
+/**
+ * App — root TUI component.
+ *
+ * Orchestrates the layout, stories panel, agent panel, and status bar.
+ */
+
+import { Box, Text, useApp, useInput } from "ink";
+import { useState } from "react";
+import { writeQueueCommand } from "../utils/queue-writer";
+import { AgentPanel } from "./components/AgentPanel";
+import { CostOverlay } from "./components/CostOverlay";
+import { HelpOverlay } from "./components/HelpOverlay";
+import { StatusBar } from "./components/StatusBar";
+import { StoriesPanel } from "./components/StoriesPanel";
+import { type KeyboardAction, useKeyboard } from "./hooks/useKeyboard";
+import { MIN_TERMINAL_WIDTH, useLayout } from "./hooks/useLayout";
+import { usePipelineEvents } from "./hooks/usePipelineEvents";
+import { usePty } from "./hooks/usePty";
+import { PanelFocus } from "./types";
+import type { TuiProps } from "./types";
+
+/**
+ * Root TUI application component.
+ *
+ * Renders the TUI with:
+ * - Responsive layout (single/narrow/wide)
+ * - Stories panel with status icons
+ * - Status bar showing current story/stage
+ * - Live updates via pipeline events
+ *
+ * @example
+ * ```tsx
+ * const emitter = new PipelineEventEmitter();
+ *
+ * render(
+ *   <App
+ *     feature="auth-system"
+ *     stories={initialStories}
+ *     totalCost={0}
+ *     elapsedMs={0}
+ *     events={emitter}
+ *   />
+ * );
+ * ```
+ */
+export function App({ feature, stories: initialStories, events, queueFilePath, ptyOptions }: TuiProps) {
+  const layout = useLayout();
+  const state = usePipelineEvents(
+    events,
+    initialStories.map((s) => s.story),
+  );
+  const { exit } = useApp();
+
+  // Focus management (Tab toggles between Stories and Agent panels)
+  const [focus, setFocus] = useState<PanelFocus>(PanelFocus.Stories);
+
+  // Overlay state
+  const [showHelp, setShowHelp] = useState(false);
+  const [showCost, setShowCost] = useState(false);
+  const [showQuitConfirm, setShowQuitConfirm] = useState(false);
+  const [showAbortConfirm, setShowAbortConfirm] = useState(false);
+
+  // Wire PTY hook for agent session
+  const { outputLines: agentOutputLines, handle: ptyHandle } = usePty(ptyOptions ?? null);
+
+  // Handle keyboard actions
+  const handleKeyboardAction = async (action: KeyboardAction) => {
+    switch (action.type) {
+      case "TOGGLE_FOCUS":
+        setFocus((prev) => (prev === PanelFocus.Stories ? PanelFocus.Agent : PanelFocus.Stories));
+        break;
+
+      case "ESCAPE_AGENT":
+        setFocus(PanelFocus.Stories);
+        break;
+
+      case "SHOW_HELP":
+        setShowHelp(true);
+        break;
+
+      case "SHOW_COST":
+        setShowCost(true);
+        break;
+
+      case "CLOSE_OVERLAY":
+        setShowHelp(false);
+        setShowCost(false);
+        setShowQuitConfirm(false);
+        setShowAbortConfirm(false);
+        break;
+
+      case "QUIT":
+        // If a story is running, show confirmation
+        if (state.currentStory) {
+          setShowQuitConfirm(true);
+        } else {
+          exit();
+        }
+        break;
+
+      case "PAUSE":
+        if (queueFilePath) {
+          await writeQueueCommand(queueFilePath, { type: "PAUSE" });
+        }
+        break;
+
+      case "ABORT":
+        // If a story is running, show confirmation
+        if (state.currentStory) {
+          setShowAbortConfirm(true);
+        } else if (queueFilePath) {
+          await writeQueueCommand(queueFilePath, { type: "ABORT" });
+        }
+        break;
+
+      case "SKIP":
+        if (queueFilePath) {
+          await writeQueueCommand(queueFilePath, { type: "SKIP", storyId: action.storyId });
+        }
+        break;
+
+      case "RETRY":
+        // TODO: Implement retry logic for last failed story
+        // This would require tracking the last failed story and resetting its status
+        break;
+
+      default:
+        break;
+    }
+  };
+
+  // Custom input handler for confirmation dialogs and PTY routing
+  useInput((input, key) => {
+    // Handle confirmation dialogs
+    if (showQuitConfirm || showAbortConfirm) {
+      const inputKey = input.toLowerCase();
+      if (inputKey === "y") {
+        if (showQuitConfirm) {
+          exit();
+        } else if (showAbortConfirm && queueFilePath) {
+          writeQueueCommand(queueFilePath, { type: "ABORT" });
+          setShowAbortConfirm(false);
+        }
+      } else if (inputKey === "n" || input === "\x1b") {
+        // n or Esc cancels
+        setShowQuitConfirm(false);
+        setShowAbortConfirm(false);
+      }
+      return;
+    }
+
+    // Route input to PTY when agent panel is focused
+    if (focus === PanelFocus.Agent && ptyHandle) {
+      // Ctrl+] escapes back to TUI controls (handled by useKeyboard)
+      if (key.ctrl && input === "]") {
+        return; // Let useKeyboard handle it
+      }
+      // All other input goes to PTY
+      ptyHandle.write(input);
+    }
+  });
+
+  // Wire keyboard hook (disabled during confirmation dialogs)
+  useKeyboard({
+    focus,
+    currentStory: state.currentStory,
+    onAction: handleKeyboardAction,
+    disabled: showQuitConfirm || showAbortConfirm,
+  });
+
+  const currentRouting = state.currentStory?.routing;
+
+  // Warn if terminal is too small
+  const isTooSmall = layout.width < MIN_TERMINAL_WIDTH;
+
+  return (
+    <Box flexDirection="column" height="100%">
+      {/* Header */}
+      <Box paddingX={1} borderStyle="single" borderBottom borderColor="cyan">
+        <Text bold color="cyan">
+          nax run — {feature}
+        </Text>
+      </Box>
+
+      {/* Warning for very small terminals */}
+      {isTooSmall && (
+        <Box paddingX={1} backgroundColor="yellow">
+          <Text color="black">
+            ⚠️ Terminal too narrow ({layout.width} cols). Minimum {MIN_TERMINAL_WIDTH} cols recommended.
+          </Text>
+        </Box>
+      )}
+
+      {/* Main content area */}
+      <Box flexDirection={layout.mode === "single" ? "column" : "row"} flexGrow={1}>
+        {/* Stories panel */}
+        <StoriesPanel
+          stories={state.stories}
+          totalCost={state.totalCost}
+          elapsedMs={state.elapsedMs}
+          width={layout.mode === "single" ? layout.width : layout.storiesPanelWidth}
+          compact={layout.mode === "single"}
+          maxHeight={layout.mode === "single" ? 10 : undefined}
+        />
+
+        {/* Agent panel */}
+        <AgentPanel focused={focus === PanelFocus.Agent} outputLines={agentOutputLines} />
+      </Box>
+
+      {/* Status bar */}
+      <StatusBar
+        currentStory={state.currentStory}
+        currentStage={state.currentStage}
+        modelTier={currentRouting?.modelTier}
+        testStrategy={currentRouting?.testStrategy}
+      />
+
+      {/* Overlays */}
+      <HelpOverlay visible={showHelp} />
+      <CostOverlay visible={showCost} stories={state.stories} totalCost={state.totalCost} />
+
+      {/* Quit confirmation */}
+      {showQuitConfirm && (
+        <Box position="absolute" width="100%" height="100%" justifyContent="center" alignItems="center">
+          <Box
+            flexDirection="column"
+            borderStyle="double"
+            borderColor="yellow"
+            paddingX={2}
+            paddingY={1}
+            backgroundColor="black"
+          >
+            <Text color="yellow">⚠️ Story is running. Quit anyway?</Text>
+            <Box paddingTop={1}>
+              <Text dimColor>
+                Press <Text color="yellow">y</Text> to confirm, <Text color="yellow">n</Text> to cancel
+              </Text>
+            </Box>
+          </Box>
+        </Box>
+      )}
+
+      {/* Abort confirmation */}
+      {showAbortConfirm && (
+        <Box position="absolute" width="100%" height="100%" justifyContent="center" alignItems="center">
+          <Box
+            flexDirection="column"
+            borderStyle="double"
+            borderColor="red"
+            paddingX={2}
+            paddingY={1}
+            backgroundColor="black"
+          >
+            <Text color="red">⚠️ Story is running. Abort anyway?</Text>
+            <Box paddingTop={1}>
+              <Text dimColor>
+                Press <Text color="yellow">y</Text> to confirm, <Text color="yellow">n</Text> to cancel
+              </Text>
+            </Box>
+          </Box>
+        </Box>
+      )}
+    </Box>
+  );
+}

package/src/tui/components/AgentPanel.tsx

@@ -0,0 +1,75 @@
+/**
+ * AgentPanel — displays PTY output from agent session.
+ *
+ * Renders a scrollable text buffer showing live agent output.
+ * When focused, displays a border highlight.
+ */
+
+import { Box, Text } from "ink";
+import Spinner from "ink-spinner";
+
+/**
+ * Props for AgentPanel component.
+ */
+export interface AgentPanelProps {
+  /** Whether the panel is focused (receives keyboard input) */
+  focused?: boolean;
+  /** PTY output lines (buffered) */
+  outputLines?: string[];
+}
+
+/**
+ * Maximum number of output lines to buffer.
+ *
+ * Prevents memory bloat from long-running agent sessions.
+ * Last 500 lines typically contain all relevant info for debugging.
+ */
+const MAX_OUTPUT_LINES = 500;
+
+/**
+ * AgentPanel component.
+ *
+ * Displays PTY output from the agent session in a scrollable text buffer.
+ * Shows a border highlight when focused to indicate keyboard input routing.
+ *
+ * @example
+ * ```tsx
+ * const [outputLines, setOutputLines] = useState<string[]>([]);
+ *
+ * <AgentPanel
+ *   focused={agentFocused}
+ *   outputLines={outputLines}
+ *   onData={(data) => setOutputLines(prev => [...prev, data])}
+ * />
+ * ```
+ */
+export function AgentPanel({ focused = false, outputLines = [] }: AgentPanelProps) {
+  const borderColor = focused ? "cyan" : "gray";
+
+  // Buffer output lines (last N lines only)
+  const bufferedLines = outputLines.length > MAX_OUTPUT_LINES ? outputLines.slice(-MAX_OUTPUT_LINES) : outputLines;
+
+  const hasOutput = bufferedLines.length > 0;
+
+  return (
+    <Box flexDirection="column" flexGrow={1} borderStyle="single" borderColor={borderColor}>
+      {/* Header */}
+      <Box paddingX={1} borderStyle="single" borderBottom borderColor={borderColor}>
+        <Text bold color={focused ? "cyan" : undefined}>
+          Agent {focused && <Text dimColor>(focused)</Text>}
+        </Text>
+      </Box>
+
+      {/* Output buffer */}
+      <Box flexDirection="column" paddingX={1} paddingY={1}>
+        {hasOutput ? (
+          bufferedLines.map((line, i) => <Text key={`line-${i}-${line.slice(0, 20)}`}>{line}</Text>)
+        ) : (
+          <Text dimColor>
+            <Spinner type="dots" /> Waiting for agent...
+          </Text>
+        )}
+      </Box>
+    </Box>
+  );
+}