@nathapp/nax 0.18.1

package/docs/v0.5-spec.md

@@ -0,0 +1,237 @@
+# ngent v0.5 Specification
+**Date:** 2026-02-17
+**Status:** Approved
+
+## Theme: Cost Intelligence
+
+v0.5 makes ngent cost-aware — track spending, control routing, and auto-optimize model selection based on observed data.
+
+## Feature 1: Metrics Tracking
+
+### Problem
+No visibility into where money goes. Users can't answer: "Which stories cost the most?", "What's my haiku pass rate?", "Am I wasting money on sonnet for simple tasks?"
+
+### Solution
+Log structured metrics per run and per story. Persist to `ngent/metrics.json`.
+
+### Data Model
+```typescript
+interface RunMetrics {
+  runId: string;
+  feature: string;
+  startedAt: string;
+  completedAt: string;
+  totalCost: number;
+  totalStories: number;
+  storiesCompleted: number;
+  storiesFailed: number;
+  totalDurationMs: number;
+  stories: StoryMetrics[];
+}
+
+interface StoryMetrics {
+  storyId: string;
+  complexity: string;
+  modelTier: string;
+  modelUsed: string;
+  attempts: number;          // how many tries (escalations)
+  finalTier: string;         // tier that succeeded
+  success: boolean;
+  cost: number;
+  durationMs: number;
+  firstPassSuccess: boolean; // passed on first attempt?
+}
+
+interface AggregateMetrics {
+  totalRuns: number;
+  totalCost: number;
+  totalStories: number;
+  firstPassRate: number;       // % passing on first attempt
+  escalationRate: number;      // % needing model upgrade
+  avgCostPerStory: number;
+  avgCostPerFeature: number;
+  modelEfficiency: Record<string, {
+    attempts: number;
+    successes: number;
+    passRate: number;
+    avgCost: number;
+    totalCost: number;
+  }>;
+  complexityAccuracy: Record<string, {
+    predicted: number;
+    actualTierUsed: string;   // most common final tier
+    mismatchRate: number;      // predicted simple but needed sonnet
+  }>;
+}
+```
+
+### CLI
+```bash
+ngent status --cost           # show aggregate metrics
+ngent status --cost --last    # show last run metrics
+ngent status --cost --model   # show per-model efficiency
+```
+
+### Acceptance Criteria
+- [ ] Per-story metrics logged during run
+- [ ] Per-run summary persisted to metrics.json
+- [ ] Aggregate metrics calculated across all runs
+- [ ] `ngent status --cost` displays formatted report
+- [ ] Metrics survive across runs (append, not overwrite)
+
+---
+
+## Feature 2: Pluggable Routing
+
+### Problem
+Routing is hardcoded — keyword matching or LLM classification. Developers can't inject domain knowledge like "always use opus for database migrations" or "use haiku for all docs tasks".
+
+### Solution
+`RoutingStrategy` interface. Built-in strategies + custom strategy loading.
+
+### Interface
+```typescript
+interface RoutingStrategy {
+  readonly name: string;
+  route(story: UserStory, context: RoutingContext): RoutingDecision;
+}
+
+interface RoutingContext {
+  config: NgentConfig;
+  codebaseContext?: string;
+  metrics?: AggregateMetrics;
+}
+
+interface RoutingDecision {
+  complexity: string;
+  modelTier: ModelTier;
+  testStrategy: string;
+  reasoning: string;
+}
+```
+
+### Built-in Strategies
+- `keyword` — current keyword matching (default fallback)
+- `llm` — LLM classification (v0.3)
+- `adaptive` — metrics-driven (v0.5, see Feature 3)
+- `manual` — user specifies tier per story in prd.json
+
+### Custom Strategy
+```json
+{
+  "routing": {
+    "strategy": "custom",
+    "customStrategyPath": "./my-router.ts"
+  }
+}
+```
+
+```typescript
+// my-router.ts
+import type { RoutingStrategy } from "ngent";
+
+export default {
+  name: "my-project-router",
+  route(story, context) {
+    if (story.tags.includes("migration")) return { modelTier: "powerful", ... };
+    if (story.tags.includes("docs")) return { modelTier: "fast", ... };
+    // fallback to keyword
+    return null; // null = use fallback strategy
+  },
+} satisfies RoutingStrategy;
+```
+
+### Strategy Chain
+Custom strategy can return `null` to delegate to next strategy:
+```
+custom → adaptive → llm → keyword
+```
+
+### Acceptance Criteria
+- [ ] RoutingStrategy interface exported
+- [ ] Custom strategy loaded from config path
+- [ ] Strategy chain with null-delegation fallback
+- [ ] Built-in strategies: keyword, llm, manual
+- [ ] Config validation for strategy selection
+
+---
+
+## Feature 3: Adaptive Routing
+
+### Problem
+Static routing wastes money. Haiku might handle 90% of "medium" stories, but routing always sends them to sonnet.
+
+### Solution
+Use historical metrics to auto-adjust routing thresholds.
+
+### Algorithm
+```
+For each complexity level:
+  1. Check metrics: what's haiku's pass rate for this complexity?
+  2. Calculate: effectiveCost = haikuCost + (failRate × escalationCost)
+  3. Compare: is effectiveCost < sonnetCost?
+  4. If yes → route to haiku (escalation handles failures)
+  5. If no → route to sonnet (haiku wastes more than it saves)
+```
+
+### Thresholds
+```json
+{
+  "routing": {
+    "strategy": "adaptive",
+    "adaptive": {
+      "minSamples": 10,         // need 10 stories before adapting
+      "costThreshold": 0.8,     // switch when effectiveCost > 80% of next tier
+      "fallbackStrategy": "llm" // use before enough data collected
+    }
+  }
+}
+```
+
+### Acceptance Criteria
+- [ ] Reads historical metrics for routing decisions
+- [ ] Falls back to configured strategy when insufficient data
+- [ ] Respects minSamples threshold
+- [ ] Calculates effective cost including escalation
+- [ ] Auto-adjusts routing per complexity level
+- [ ] Logs reasoning for adaptive decisions
+
+---
+
+## Implementation Plan
+
+### Phase 1: Metrics Tracking
+**Files:** `src/metrics/tracker.ts`, `src/metrics/aggregator.ts`, `src/metrics/index.ts`
+- StoryMetrics collection during pipeline execution
+- RunMetrics summary on completion
+- AggregateMetrics calculation
+- Persistence to `ngent/metrics.json`
+- `ngent status --cost` display
+
+**Commit:** `feat(metrics): add per-story and per-run cost tracking`
+
+### Phase 2: Pluggable Routing
+**Files:** `src/routing/strategy.ts`, `src/routing/chain.ts`, `src/routing/strategies/`
+- RoutingStrategy interface
+- Strategy chain with fallback
+- Custom strategy loader (dynamic import)
+- Manual strategy (read from prd.json)
+- Config schema update
+
+**Commit:** `feat(routing): add pluggable routing strategy system`
+
+### Phase 3: Adaptive Routing
+**Files:** `src/routing/strategies/adaptive.ts`
+- Read AggregateMetrics
+- Calculate effective cost per complexity
+- Route based on cost optimization
+- Fallback when insufficient data
+
+**Commit:** `feat(routing): add adaptive metrics-driven routing strategy`
+
+## Test Strategy
+- Mode: test-after
+- Run `bun test && bun run typecheck` after each phase
+
+## Estimated Effort
+~500-700 LOC across 3 phases.

package/docs/v0.6-spec.md

@@ -0,0 +1,371 @@
+# nax v0.6 Specification
+**Date:** 2026-02-17
+**Status:** Draft
+
+## Theme: Terminal User Interface
+
+v0.6 adds an interactive TUI that wraps the orchestration loop, giving developers real-time visibility and control over agent execution — without leaving the terminal.
+
+### Core Insight
+
+**Relentless TUI = monitoring dashboard. nax TUI = interactive co-pilot.**
+
+Relentless streams piped text into a read-only panel. nax embeds the actual Claude Code session in a PTY — the developer can **approve permission prompts, intervene mid-execution, and steer** while nax handles the orchestration loop around it.
+
+---
+
+## Feature 1: PTY-Embedded Agent Sessions
+
+### Problem
+`nax run` currently spawns Claude Code with `-p` (print mode) — fully non-interactive. The developer has no visibility into what the agent is doing or ability to intervene. For `--dangerously-skip-permissions` this is fine, but for interactive use (where the developer approves each tool call), there's no way to see/interact with the agent.
+
+### Solution
+Embed the agent session in a PTY panel within the TUI. Agent output streams in real-time. Keyboard input routes to the agent's stdin when the agent panel is focused.
+
+### Design
+```
+┌─ nax run ─────────────────────────────────────────────────────┐
+│ ┌─ Stories ──────────┐ ┌─ Agent ────────────────────────────┐ │
+│ │ ✅ US-001 setup    │ │ $ claude                           │ │
+│ │ ✅ US-002 models   │ │                                    │ │
+│ │ 🔄 US-003 api     │ │ I'll implement the API routes...   │ │
+│ │ ⬚ US-004 tests    │ │                                    │ │
+│ │ ⬚ US-005 docs     │ │ > Allow: Write src/routes/api.ts?  │ │
+│ │                    │ │   [Y/n]  _                         │ │
+│ │ Cost: $0.42        │ │                                    │ │
+│ │ Time: 4m 23s       │ │                                    │ │
+│ └────────────────────┘ └────────────────────────────────────┘ │
+│ ┌─ Status ──────────────────────────────────────────────────┐ │
+│ │ Story 3/5 · US-003 · medium · sonnet · single-session    │ │
+│ └───────────────────────────────────────────────────────────┘ │
+└───────────────────────────────────────────────────────────────┘
+```
+
+### PTY Architecture (Agent-Agnostic)
+
+The PTY embedding is **agent-agnostic by design**. The agent panel is a terminal emulator widget — it doesn't parse or understand agent-specific output. Whatever the agent prints, we display. Whatever the user types, we forward. This means any coding agent that runs in a terminal works automatically:
+
+| Agent | Interactive PTY? | Notes |
+|:---|:---|:---|
+| Claude Code | ✅ | Permission prompts, rich ANSI output |
+| Codex CLI | ✅ | Similar interactive flow |
+| Aider | ✅ | Chat-style terminal UI |
+| OpenCode | ✅ | Terminal-based |
+| Any CLI tool | ✅ | If it runs in a terminal, it works in the panel |
+
+```typescript
+// Agent adapter spawns with PTY instead of piped stdio
+interface AgentSpawnOptions {
+  mode: 'pty' | 'pipe';     // pty = interactive TUI, pipe = headless (-p mode)
+  onOutput?: (data: string) => void;  // stream to TUI panel
+  onInput?: () => ReadableStream;     // keyboard from TUI
+}
+```
+
+- **`node-pty`** for PTY allocation (battle-tested, used by VS Code)
+- Agent panel captures all PTY output (ANSI codes preserved)
+- Focused panel routes keystrokes to PTY stdin
+- When not in TUI mode, behavior is unchanged (pipe mode, `-p`)
+- Adding a new agent to the TUI requires only implementing `runInteractive()` on the adapter — zero TUI code changes
+
+### Acceptance Criteria
+- [ ] Agent session runs in embedded PTY
+- [ ] Real-time output streaming to TUI panel
+- [ ] Keyboard input routes to agent when panel focused
+- [ ] Permission prompts visible and answerable
+- [ ] Falls back to pipe mode when `--headless` flag or no TTY
+
+---
+
+## Feature 2: Story Progress Panel
+
+### Problem
+During a run, the developer has no idea which stories are done, which failed, or what's currently executing without reading log output.
+
+### Solution
+Left sidebar showing all stories with live status icons, cost accumulator, and elapsed time.
+
+### Story States
+```
+⬚  pending       — not started
+🔄 running       — agent working on it
+✅ passed        — completed successfully
+❌ failed        — all attempts exhausted
+⏭️  skipped       — skipped by queue command or dependency failure
+🔁 retrying      — escalating to higher tier
+⏸️  paused        — queue PAUSE received
+```
+
+### Data Source
+Pipeline context already tracks story status. The TUI subscribes to pipeline events:
+
+```typescript
+interface PipelineEvents {
+  'story:start': (story: UserStory, routing: RoutingResult) => void;
+  'story:complete': (story: UserStory, result: StageResult) => void;
+  'story:escalate': (story: UserStory, fromTier: string, toTier: string) => void;
+  'stage:enter': (stage: string, story: UserStory) => void;
+  'stage:exit': (stage: string, result: StageResult) => void;
+  'run:complete': (summary: RunSummary) => void;
+}
+```
+
+### Cost Display
+- Per-story cost (from metrics tracker, v0.5)
+- Running total
+- Projected total (based on avg cost × remaining stories)
+
+### Acceptance Criteria
+- [ ] All stories listed with real-time status icons
+- [ ] Cost accumulator updates per story completion
+- [ ] Elapsed time displayed
+- [ ] Current stage shown in status bar (routing → constitution → prompt → execution → verify → review)
+- [ ] Pipeline events emitted from runner
+
+---
+
+## Feature 3: Interactive Controls
+
+### Problem
+Queue commands (`PAUSE`, `ABORT`, `SKIP`) require writing to a file. Developers want keyboard shortcuts.
+
+### Solution
+Keyboard shortcuts that write queue commands + additional TUI-only controls.
+
+### Keybindings
+```
+p          — Pause after current story (writes PAUSE to queue)
+a          — Abort run (writes ABORT to queue)
+s          — Skip current story (writes SKIP <current-story-id>)
+Tab        — Toggle focus between Stories panel and Agent panel
+q          — Quit TUI (confirms if run is active)
+?          — Show help overlay
+Esc        — Close overlay / unfocus agent panel
+r          — Retry last failed story
+c          — Show cost breakdown overlay
+```
+
+When the Agent panel is focused, all keys route to the PTY **except**:
+- `Ctrl+]` — escape back to TUI controls (like `screen`/`tmux` prefix)
+
+### Acceptance Criteria
+- [ ] Keyboard shortcuts trigger queue commands
+- [ ] Focus mode for agent panel (keys → PTY)
+- [ ] Escape sequence to return to TUI controls
+- [ ] Help overlay with keybinding reference
+- [ ] Confirmation prompt before abort/quit during active run
+
+---
+
+## Feature 4: Headless Mode Compatibility
+
+### Problem
+CI/CD, cron jobs, and `nax run` via scripts need headless operation. TUI should be opt-in, not forced.
+
+### Solution
+TUI activates only when:
+1. stdout is a TTY, AND
+2. `--headless` flag is NOT passed
+
+```bash
+nax run                  # TUI mode (if TTY)
+nax run --headless       # pipe mode (current behavior)
+nax run | tee log.txt    # pipe mode (not a TTY)
+NAX_HEADLESS=1 nax run   # pipe mode (env override)
+```
+
+### Acceptance Criteria
+- [ ] TUI auto-activates on TTY
+- [ ] `--headless` forces pipe mode
+- [ ] Non-TTY detection falls back to pipe mode
+- [ ] `NAX_HEADLESS` env var override
+- [ ] All existing functionality works in headless mode (no regressions)
+
+---
+
+## Feature 5: Responsive Layout
+
+### Problem
+Terminal widths vary (80–200+ columns). The 2-panel layout needs to adapt.
+
+### Solution
+Three layout breakpoints:
+
+```
+< 80 cols:   Single column (stories above, agent below, stacked)
+80–140 cols: 2-column (stories left, agent right)
+> 140 cols:  2-column with wider agent panel + stage detail in status bar
+```
+
+Vertical: Agent panel takes remaining height. Stories panel scrolls if >15 stories.
+
+### Acceptance Criteria
+- [ ] Layout adapts to terminal width
+- [ ] Resize events handled (SIGWINCH)
+- [ ] Single-column mode functional on 80-col terminals
+- [ ] Stories panel scrollable
+
+---
+
+## Non-Goals (v0.6)
+
+- **3-column layout** — Relentless-style message queue panel. Not needed; nax doesn't have a message queue concept.
+- **Animated effects** — Typing animations, pulsing cursors. Keep it clean and fast.
+- **Mouse support** — Keyboard-only for v0.6. Mouse can come later.
+- **Theming/colors config** — Hardcoded color scheme (chalk). Configurable themes deferred.
+- **Log panel** — Agent output IS the log. No separate log panel needed.
+
+---
+
+## Technical Stack
+
+| Component | Choice | Rationale |
+|:---|:---|:---|
+| **UI framework** | [Ink](https://github.com/vadimdemedes/ink) (React for terminal) | Declarative, Bun-compatible, used by Relentless |
+| **PTY library** | [node-pty](https://github.com/microsoft/node-pty) | Battle-tested (VS Code), split I/O, cross-platform |
+| **Terminal detection** | `process.stdout.isTTY` + `--headless` flag | Standard approach |
+| **Layout** | Ink `<Box>` with flexbox | Built into Ink |
+
+### Component Tree
+```
+<App>
+  <Layout cols={termWidth}>
+    <StoriesPanel stories={stories} costs={costs} elapsed={elapsed} />
+    <AgentPanel pty={ptyProcess} focused={agentFocused} />
+  </Layout>
+  <StatusBar story={current} stage={currentStage} routing={routing} />
+  {showHelp && <HelpOverlay />}
+  {showCosts && <CostOverlay metrics={metrics} />}
+</App>
+```
+
+### File Structure
+```
+src/
+  tui/
+    index.ts              # TUI entry point, Ink render()
+    App.tsx               # Root component
+    components/
+      StoriesPanel.tsx    # Story list with status icons
+      AgentPanel.tsx      # PTY output display + input routing
+      StatusBar.tsx       # Current story/stage info
+      HelpOverlay.tsx     # Keybinding reference
+      CostOverlay.tsx     # Cost breakdown table
+    hooks/
+      usePty.ts           # PTY lifecycle management
+      usePipelineEvents.ts # Subscribe to pipeline events
+      useKeyboard.ts      # Keyboard shortcut handler
+      useLayout.ts        # Terminal size + breakpoint detection
+    types.ts              # TUI-specific types
+```
+
+### Agent Adapter Changes
+```typescript
+// src/agents/types.ts — extend AgentAdapter
+interface AgentAdapter {
+  // existing
+  run(command: string[], options: RunOptions): Promise<AgentResult>;
+  
+  // new: PTY mode for TUI
+  runInteractive?(
+    command: string[], 
+    options: RunOptions & { 
+      onOutput: (data: Buffer) => void;
+      onExit: (code: number) => void;
+    }
+  ): PtyHandle;
+}
+
+interface PtyHandle {
+  write(data: string): void;   // send input to agent
+  resize(cols: number, rows: number): void;
+  kill(): void;
+  pid: number;
+}
+```
+
+---
+
+## Implementation Plan
+
+### Phase 1: Pipeline Events + Headless Flag
+**Files:** `src/pipeline/runner.ts`, `src/pipeline/events.ts`, `src/cli/run.ts`
+- Add EventEmitter to pipeline runner
+- Emit story/stage lifecycle events
+- Add `--headless` flag and TTY detection
+- No visual changes — just the event plumbing
+
+**Commit:** `feat(pipeline): add event emitter for TUI integration`
+
+### Phase 2: Ink Scaffolding + Stories Panel
+**Files:** `src/tui/`, `package.json` (add ink, react, node-pty deps)
+- Ink app bootstrap
+- StoriesPanel with mock data
+- StatusBar
+- Layout with breakpoints
+- Wire to pipeline events (stories update live)
+
+**Commit:** `feat(tui): add Ink-based TUI with stories panel`
+
+### Phase 3: PTY Agent Panel
+**Files:** `src/tui/components/AgentPanel.tsx`, `src/tui/hooks/usePty.ts`, `src/agents/claude.ts`
+- node-pty integration in Claude adapter
+- AgentPanel rendering PTY output
+- Focus management (Tab to switch, Ctrl+] to escape)
+- Input routing to PTY stdin
+
+**Commit:** `feat(tui): embed agent PTY session in TUI`
+
+### Phase 4: Interactive Controls + Overlays
+**Files:** `src/tui/hooks/useKeyboard.ts`, `src/tui/components/HelpOverlay.tsx`, `src/tui/components/CostOverlay.tsx`
+- Keyboard shortcuts (p/a/s/q/?)
+- Help overlay
+- Cost breakdown overlay
+- Confirmation prompts
+
+**Commit:** `feat(tui): add keyboard controls and overlays`
+
+### Phase 5: Responsive Layout + Polish
+**Files:** `src/tui/hooks/useLayout.ts`, `src/tui/App.tsx`
+- SIGWINCH handling
+- Single-column breakpoint
+- Scrollable stories panel
+- Edge cases (tiny terminals, rapid resize)
+
+**Commit:** `feat(tui): responsive layout and polish`
+
+## Test Strategy
+- **Unit tests:** Pipeline events, layout breakpoint logic, keybinding handler
+- **Snapshot tests:** Ink component rendering (ink-testing-library)
+- **Integration:** Full TUI with mock agent adapter (no real Claude Code)
+- Mode: test-after per phase
+
+## Dependencies (new)
+```json
+{
+  "ink": "^5.0.0",
+  "react": "^18.3.0",
+  "node-pty": "^1.0.0"
+}
+```
+
+DevDependencies:
+```json
+{
+  "ink-testing-library": "^4.0.0",
+  "@types/react": "^18.3.0"
+}
+```
+
+## Estimated Effort
+~1,200–1,500 LOC across 5 phases. Largest phase is Phase 3 (PTY integration).
+
+## Risk Assessment
+
+| Risk | Mitigation |
+|:---|:---|
+| `node-pty` native compilation on different platforms | Provide fallback to pipe mode; node-pty is well-maintained |
+| Ink + Bun compatibility | Ink 5.x works with Bun; verify in Phase 2 before investing in Phase 3 |
+| PTY output flooding (fast agent output) | Buffer/throttle rendering to 30fps; Ink handles this natively |
+| ANSI escape code rendering in Ink | Use `<Static>` or raw output mode for agent panel |
+| node-pty adds ~5MB to install size | Acceptable tradeoff; it's optional (headless mode works without it) |