@nathapp/nax 0.27.1 → 0.29.0

package/docs/specs/bun-pty-migration.md

@@ -1,171 +0,0 @@
-# BUN-001: Bun PTY Migration
-
-**Version:** v0.18.5  
-**Status:** Planned  
-**Author:** Nax Dev  
-**Date:** 2026-03-04
-
----
-
-## Problem
-
-nax uses `node-pty` (a native C++ addon) to spawn interactive Claude Code sessions and drive the TUI. This creates several pain points:
-
-| Pain Point | Impact |
-|:---|:---|
-| Requires `python`, `make`, `g++` at build time | CI `before_script` must `apk add python3 make g++`; `--ignore-scripts` is a fragile workaround |
-| Native build fails on Alpine if workaround is removed | Blocks moving to 1GB runners (CI-001) |
-| Not Bun-native — `require("node-pty")` uses CJS | Inconsistent with Bun-first codebase |
-| No type safety without `@types/node-pty` | Interface `IPty` lives in node-pty types |
-
----
-
-## Solution
-
-Replace `node-pty` with **`Bun.spawn`** configured with `stdin: "pipe"` and `stdout: "pipe"` for interactive mode, OR `Bun.Terminal` API if it provides PTY semantics in Bun 1.3.7+.
-
-### Research Gate (first task)
-
-Before writing any code, verify Bun PTY support:
-
-```bash
-# Check if Bun.Terminal exists
-bun -e "console.log(typeof Bun.Terminal)"
-
-# Check for any PTY-related Bun APIs
-bun -e "console.log(Object.keys(Bun).filter(k => k.toLowerCase().includes('pty') || k.toLowerCase().includes('term')))"
-```
-
-**If `Bun.Terminal` is available:** Use it directly for full PTY semantics.  
-**If not available:** Use `Bun.spawn` with piped stdio. Claude Code works headlessly — no raw TTY required for nax's use case.
-
----
-
-## Scope
-
-### Files to change
-
-| File | Change |
-|:---|:---|
-| `src/agents/claude.ts` | `runInteractive()` — replace `nodePty.spawn()` with Bun equivalent |
-| `src/agents/types.ts` | `PtyHandle` interface — remove dependency on `IPty` |
-| `src/tui/hooks/usePty.ts` | Replace `nodePty.spawn()` + `pty.IPty` state with Bun equivalent |
-| `package.json` | Remove `node-pty` from `dependencies` |
-| `.gitlab-ci.yml` | Remove `--ignore-scripts` from both `bun install` calls |
-| `.gitlab-ci.yml` | Remove `python3 make g++` from `apk add` in `before_script` |
-
-### Files NOT to change
-
-- `src/agents/adapters/` — use `runInteractive()` via interface only
-- `src/pipeline/` — no pty usage
-- Test files — `_deps` pattern already covers mocking
-
----
-
-## Implementation Plan
-
-### Phase 1 — Research
-
-1. Run research gate on Mac01 (Bun 1.3.9) to confirm `Bun.Terminal` availability
-2. Test `claude -p "hello"` with `Bun.spawn` piped stdio to confirm headless operation
-3. Determine if `resize()` is actually called during nax runs (check execution logs)
-
-### Phase 2 — `src/agents/claude.ts`
-
-Replace `runInteractive()`:
-
-```typescript
-// BEFORE (node-pty)
-const ptyProc = nodePty.spawn(cmd[0], cmd.slice(1), {
-  name: "xterm-256color", cols: 80, rows: 24,
-  cwd: options.workdir, env: this.buildAllowedEnv(options),
-});
-ptyProc.onData((data) => options.onOutput(Buffer.from(data)));
-ptyProc.onExit((e) => options.onExit(e.exitCode));
-
-// AFTER (Bun.spawn)
-const proc = Bun.spawn(cmd, {
-  cwd: options.workdir,
-  env: { ...this.buildAllowedEnv(options), TERM: "xterm-256color" },
-  stdin: "pipe", stdout: "pipe", stderr: "pipe",
-});
-// Stream stdout chunks to onOutput
-(async () => {
-  for await (const chunk of proc.stdout) {
-    options.onOutput(Buffer.from(chunk));
-  }
-})();
-proc.exited.then((code) => options.onExit(code ?? 1));
-```
-
-New `PtyHandle` mapping:
-
-| `IPty` API | Bun equivalent |
-|:---|:---|
-| `ptyProc.write(data)` | `proc.stdin.write(data)` |
-| `ptyProc.kill()` | `proc.kill()` |
-| `ptyProc.pid` | `proc.pid` |
-| `ptyProc.resize(c, r)` | no-op (or `Bun.Terminal.resize()` if available) |
-
-### Phase 3 — `src/tui/hooks/usePty.ts`
-
-Replace `pty.IPty` state with `Bun.Subprocess`:
-
-```typescript
-// Remove:
-import type * as pty from "node-pty";
-const [ptyProcess, setPtyProcess] = useState<pty.IPty | null>(null);
-
-// Replace with:
-const [proc, setProc] = useState<ReturnType<typeof Bun.spawn> | null>(null);
-```
-
-All `ptyProc.*` calls map directly to Bun subprocess equivalents.
-
-### Phase 4 — CI cleanup
-
-```yaml
-# before_script: remove python3 make g++
-- apk add --no-cache git
-
-# bun install: remove --ignore-scripts
-- bun install --frozen-lockfile
-```
-
-### Phase 5 — package.json
-
-Remove `"node-pty": "^1.1.0"` from `dependencies`.
-
----
-
-## Acceptance Criteria
-
-| # | Criteria |
-|:---|:---|
-| AC1 | `node-pty` removed — `bun install` completes without native build |
-| AC2 | `bun run typecheck` passes — no `IPty` or `node-pty` references |
-| AC3 | CI `before_script` no longer installs `python3 make g++` |
-| AC4 | CI `bun install` runs without `--ignore-scripts` |
-| AC5 | `runInteractive()` spawns Claude Code via `Bun.spawn` — sessions complete |
-| AC6 | `usePty` hook — output streams and lifecycle work correctly |
-| AC7 | All existing tests pass (2126 pass, 0 fail) |
-| AC8 | `nax run` works end-to-end on Mac01 with a real story |
-
----
-
-## Risks
-
-| Risk | Mitigation |
-|:---|:---|
-| `Bun.Terminal` not available/stable in 1.3.9 | Fall back to `Bun.spawn` pipe mode (test first) |
-| Claude Code requires a real PTY | Test `claude -p "hello"` piped before committing |
-| TUI rendering degrades without PTY | Acceptable — TUI is rarely used in headless nax runs |
-| `resize()` breaks | nax doesn't actively call resize during agent sessions; safe no-op |
-
----
-
-## Out of Scope
-
-- `Bun.Terminal` advanced features (if not stable)
-- CI-001 memory sharding (separate item)
-- Windows PTY support

package/docs/specs/central-run-registry.md

@@ -1,116 +0,0 @@
-# Central Run Registry — Spec
-
-**Version:** v0.24.0
-**Status:** Planned
-
----
-
-## Problem
-
-nax stores run state per-project at `<workdir>/nax/features/<feature>/status.json`. There is no global index — you must `cd` into each project to see its run history. There is no way to answer "what has nax run across all my projects recently?"
-
-## Existing Layout (per-project)
-
-```
-<workdir>/nax/
-  config.json
-  features/
-    <feature>/
-      prd.json
-      status.json       ← live run state (NaxStatusFile, written continuously)
-      runs/
-        <timestamp>.jsonl ← event log
-```
-
-`status.json` already contains: runId, feature, status (running/completed/failed/crashed), progress counts, cost, current story, startedAt, etc. — everything needed for a global view.
-
-## Goal
-
-A global `~/.nax/runs/` registry that indexes every nax run via path references — no data duplication, no symlinks.
-
----
-
-## Directory Structure
-
-```
-~/.nax/runs/
-  <project>-<feature>-<runId>/
-    meta.json    ← pointer record only (paths + minimal identifiers)
-```
-
-### meta.json Schema
-
-```json
-{
-  "runId": "run-2026-03-07T05-30-00-000Z",
-  "project": "my-app",
-  "feature": "auth-system",
-  "workdir": "/Users/william/projects/my-app",
-  "statusPath": "/Users/william/projects/my-app/nax/features/auth-system/status.json",
-  "eventsDir": "/Users/william/projects/my-app/nax/features/auth-system/runs",
-  "registeredAt": "2026-03-07T05:30:00.000Z"
-}
-```
-
-- Written **once** on run start — never updated (source of truth stays in `statusPath`)
-- `nax runs` reads `meta.json` to locate `statusPath`, then reads live `status.json` for current state
-- If `statusPath` doesn't exist (project deleted/moved) → show `[unavailable]` gracefully
-
----
-
-## Implementation
-
-### CRR-000: Events File Writer (new subscriber)
-
-- New module: `src/pipeline/subscribers/events-writer.ts` — `wireEventsWriter()`
-- Writes to `~/.nax/events/<project>/events.jsonl` — one JSON line per lifecycle event
-- Listens to event bus: `run:started`, `story:started`, `story:completed`, `story:failed`, `run:completed`
-- Each line: `{"ts", "event", "runId", "feature", "project", "storyId?"}`
-- `run:completed` emits an `on-complete` event — used by external tooling (watchdog) to distinguish clean exit from crash
-- Best-effort: never throw/block the main run on write failure
-- Directory created on first write
-
-**Motivation:** External tools (nax-watchdog, CI integrations) need a reliable signal that nax exited gracefully. Currently nax writes no machine-readable completion event, causing false crash reports. This also provides the foundation for CRR — `meta.json` can reference the events file path.
-
-### CRR-001: Registry Writer (new subscriber)
-
-- New module: `src/execution/run-registry.ts` — `registerRun(meta)`, `getRunsDir()`
-- On run start: create `~/.nax/runs/<project>-<feature>-<runId>/meta.json`
-- Wire as **event bus subscriber** (`wireRegistry()` in `src/pipeline/subscribers/registry.ts`) — listens to `run:started`
-- Best-effort: never throw/block the main run on registry failure (try/catch + warn log)
-- `~/.nax/runs/` created on first call — no separate init step
-
-### CRR-002: `nax runs` CLI Command
-
-```
-nax runs                         # All runs, newest first (default: last 20)
-nax runs --project my-app        # Filter by project name
-nax runs --last 50               # Show last N runs
-nax runs --status failed         # Filter by status (running/completed/failed/crashed)
-```
-
-**Output table:**
-```
-RUN ID                        PROJECT    FEATURE        STATUS      STORIES   DURATION   DATE
-run-2026-03-07T05-30-00-000Z  my-app     auth-system    completed   5/5       45m        2026-03-07 13:30
-run-2026-03-07T04-00-00-000Z  nax        re-arch        failed      3/5       1h 2m      2026-03-07 12:00
-```
-
-- Reads all `~/.nax/runs/*/meta.json`, resolves live `status.json` from `statusPath`
-- Sorts by `registeredAt` desc
-- If `statusPath` missing → status shows `[unavailable]`
-- New command: `src/commands/runs.ts`
-
-### CRR-003: `nax logs` Enhancement
-
-- `nax logs --run <runId>` — resolve run from global registry, locate `eventsDir`, stream logs
-- No need to be in the project directory
-- Falls back to current behaviour (local feature context) when `--run` not specified
-
----
-
-## Out of Scope
-
-- Registry cleanup/prune command (future)
-- Remote sync (future)
-- Search by story ID (future)

package/docs/specs/feat-010-smart-runner-git-history.md

@@ -1,96 +0,0 @@
-# FEAT-010 — Smart Test Runner: Git-History Mode
-
-**Status:** Proposal
-**Target:** v0.21.0
-**Author:** Nax Dev
-**Date:** 2026-03-06
-
----
-
-## 1. Problem with Current Approach
-
-Smart Test Runner uses `git diff --name-only HEAD` (or `HEAD~1`) to find changed files. This breaks in several scenarios:
-
-| Scenario | Problem |
-|---|---|
-| Agent makes 3 commits | `HEAD~1` only sees last commit; earlier changes missed |
-| Agent uses `git commit --amend` | HEAD stays same; diff shows nothing |
-| Uncommitted staged changes | Picks up unrelated staged changes |
-| Story retried after partial commit | Baseline resets to wrong point |
-
-Result: empty `[]` → full suite fallback (150s+) → deferred mode skips → no per-story tests.
-
----
-
-## 2. Proposed Solution
-
-Track a **baseCommitHash** per story at session start. On verify, diff `HEAD` vs `baseCommitHash` — exact files the agent touched regardless of commit count.
-
-```
-Story starts → capture git HEAD → store as story.baseRef
-Agent runs   → makes N commits (any pattern)
-Verify runs  → git diff --name-only story.baseRef HEAD → precise file list
-```
-
----
-
-## 3. Implementation Details
-
-**Capture baseRef** in `sequential-executor.ts` before agent launch:
-```typescript
-story.baseRef = await captureGitRef(workdir);  // already exists in utils/git.ts
-await savePrd(prd, prdPath);
-```
-
-**New mode branch** in `smart-runner.ts`:
-```typescript
-if (mode === "git-history" && story?.baseRef) {
-  return gitWithTimeout(["diff", "--name-only", story.baseRef, "HEAD"], workdir);
-}
-// fallback: existing git-diff logic
-```
-
----
-
-## 4. Files Affected
-
-| File | Change |
-|---|---|
-| `src/prd/types.ts` | Add `baseRef?: string` to `UserStory` |
-| `src/execution/sequential-executor.ts` | Capture `baseRef` before agent, persist to PRD |
-| `src/verification/smart-runner.ts` | Add `"git-history"` mode |
-| `src/config/schemas.ts` | Add `smartTestRunner.mode: "git-diff" | "git-history"` |
-| `src/config/types.ts` | Add `mode` to `SmartTestRunnerConfig` |
-
----
-
-## 5. Config Changes
-
-```jsonc
-{
-  "execution": {
-    "smartTestRunnerConfig": {
-      "mode": "git-history",   // "git-diff" (default) | "git-history"
-      "enabled": true
-    }
-  }
-}
-```
-
----
-
-## 6. Migration / Compatibility
-
-- Default: `"git-diff"` — no behavior change
-- `"git-history"` opt-in
-- Missing `story.baseRef` → falls back to `"git-diff"` (no crash)
-- nax self-dev config should switch to `"git-history"` immediately
-
----
-
-## 7. Test Plan
-
-- `baseRef` captured and persisted before agent runs
-- Multi-commit session: all files detected (not just last commit's)
-- Missing `baseRef` → graceful fallback to `"git-diff"`
-- `captureGitRef()` failure → `baseRef` undefined, fallback used

package/docs/specs/feat-011-file-context-strategy.md

@@ -1,73 +0,0 @@
-# FEAT-011 — File Context Strategy
-
-**Status:** Proposal
-**Target:** v0.21.0
-**Author:** Nax Dev
-**Date:** 2026-03-06
-
----
-
-## 1. Problem
-
-nax injects full file content into agent prompts for all relevant source files. For large files (500+ lines), this bloats the context window — increasing cost and reducing focus. The agent has tool access to read files directly, making full content injection for large files redundant.
-
----
-
-## 2. Proposed Config
-
-```jsonc
-{
-  "context": {
-    "fileContext": {
-      "strategy": "auto",      // "auto" | "full" | "path-only"
-      "maxInlineLines": 500,   // threshold for "auto" mode
-      "previewLines": 20       // lines shown in path-only / large-file preview
-    }
-  }
-}
-```
-
----
-
-## 3. Injection Logic
-
-| Strategy | Condition | Agent receives |
-|---|---|---|
-| `"full"` | always | Complete file content |
-| `"path-only"` | always | Relative path + line count only |
-| `"auto"` | file ≤ `maxInlineLines` | Complete file content |
-| `"auto"` | file > `maxInlineLines` | Path + line count + first `previewLines` lines |
-
-**Large file preview format:**
-```
-// src/execution/sequential-executor.ts (847 lines — use Read tool for full content)
-import { ... } from "...";
-// first 20 lines...
-```
-
----
-
-## 4. Files Affected
-
-| File | Change |
-|---|---|
-| `src/config/schemas.ts` | Add `context.fileContext` schema |
-| `src/config/types.ts` | Add `FileContextConfig` interface |
-| `src/context/builder.ts` | Apply strategy when injecting file content |
-| `src/context/providers/` | Update providers that inject raw file content |
-
----
-
-## 5. Cost Impact
-
-Primary benefit is **quality** (more focused context), not raw cost savings. Rough estimate for a typical 5-story run: ~3000 tokens saved if avg file is 800 lines. At sonnet pricing: <$0.01 per run — marginal, but compounds.
-
----
-
-## 6. Test Plan
-
-- `strategy: "full"` → always full content regardless of line count
-- `strategy: "path-only"` → always path + count only
-- `strategy: "auto"`, 300-line file → full content
-- `strategy: "auto"`, 600-line file → path + 20-line preview
-- Default: `"auto"` with `maxInlineLines: 500`

package/docs/specs/feat-012-tdd-writer-tier.md

@@ -1,79 +0,0 @@
-# FEAT-012 — TDD Test Writer Tier Validation
-
-**Status:** Won't Fix — balanced tier is sufficient for test-writer; not worth the added complexity
-**Target:** v0.21.0
-**Author:** Nax Dev
-**Date:** 2026-03-06
-
----
-
-## 1. Problem
-
-nax TDD runs two sessions: **testWriter** then **implementer**. The testWriter tier is configured separately (`tdd.sessionTiers.testWriter`, default `"balanced"`). The implementer uses the story's routed `modelTier`.
-
-**Risk:** If testWriter runs `"fast"` and the implementer runs `"powerful"`, the tests written may be too shallow — they test happy paths but miss edge cases a powerful model's implementation handles. Result: powerful implementer writes sophisticated code, all tests pass (trivially), then the deferred regression gate catches real failures.
-
----
-
-## 2. Tier Ordering
-
-```
-fast (1) < balanced (2) < powerful (3)
-```
-
-**Invariant:** `testWriterTier >= implementerTier`
-
----
-
-## 3. Validation Logic
-
-In `src/tdd/session-runner.ts` before launching testWriter:
-
-```typescript
-const tierOrder = { fast: 1, balanced: 2, powerful: 3 };
-const writerTier = config.tdd.sessionTiers?.testWriter ?? "balanced";
-const implementerTier = story.routing.modelTier ?? "balanced";
-
-if (tierOrder[writerTier] < tierOrder[implementerTier]) {
-  if (config.tdd.enforceWriterTierParity) {
-    effectiveWriterTier = implementerTier; // auto-elevate
-    logger.warn("tdd", `Auto-elevated testWriter tier ${writerTier} → ${implementerTier}`);
-  } else {
-    logger.warn("tdd", `testWriter tier (${writerTier}) < implementer tier (${implementerTier}) — tests may be shallow`);
-  }
-}
-```
-
----
-
-## 4. Config Changes
-
-```jsonc
-{
-  "tdd": {
-    "sessionTiers": { "testWriter": "balanced", "verifier": "fast" },
-    "enforceWriterTierParity": false   // NEW — auto-elevates testWriter when true
-  }
-}
-```
-
-`nax config --explain`: *"testWriter tier should be ≥ implementer tier. Enable enforceWriterTierParity to auto-elevate."*
-
----
-
-## 5. Files Affected
-
-| File | Change |
-|---|---|
-| `src/tdd/session-runner.ts` | Tier comparison + warn/elevate logic |
-| `src/config/schemas.ts` | Add `tdd.enforceWriterTierParity` (boolean, default false) |
-| `src/config/types.ts` | Add `enforceWriterTierParity` to `TddConfig` |
-| `src/config/defaults.ts` | Default: `false` |
-
----
-
-## 6. Test Plan
-
-- `writerTier < implementerTier`, `enforceWriterTierParity: false` → warning logged, tier unchanged
-- `writerTier < implementerTier`, `enforceWriterTierParity: true` → tier elevated, warning logged
-- `writerTier >= implementerTier` → no warning, no change

package/docs/specs/feat-013-test-after-review.md

@@ -1,89 +0,0 @@
-# FEAT-013 — Test-After Strategy Review & Deprecation Path
-
-**Status:** Proposal
-**Target:** v0.21.0
-**Author:** Nax Dev
-**Date:** 2026-03-06
-
----
-
-## 1. Problem with `test-after`
-
-`test-after` runs the agent in a single session: implement first, then write tests. Structural problem: **the agent writes tests to match its own (possibly broken) implementation.** Tests confirm buggy behavior rather than guarding against it.
-
----
-
-## 2. Strategy Comparison
-
-| Strategy | Order | Sessions | Quality | Risk |
-|---|---|---|---|---|
-| `tdd-lite` | Tests → Impl | 2 | ✅ High | Low |
-| `three-session-tdd` | Tests → Impl → Verify | 3 | ✅✅ Highest | Very low |
-| `test-after` | Impl → Tests | 1 | ⚠️ Variable | High — tests may confirm bugs |
-
----
-
-## 3. Proposed Changes
-
-### 3.1 Post-write isolation verify (opt-in fix)
-
-After agent's session completes, run new test files against a clean stash of the implementation — tests should **fail** without the implementation (proving they actually test something):
-
-```
-1. Agent writes impl + tests
-2. git stash (hide impl changes)
-3. Run new test files → should FAIL (no impl)
-4. git stash pop
-5. If tests PASSED in step 3 → escalate ("trivially passing tests")
-6. Normal verify (impl + tests together)
-```
-
-Config: `tdd.testAfterIsolationVerify: true` (default: false)
-
-### 3.2 Remove from auto-routing
-
-LLM router and keyword router no longer auto-assign `test-after`. It only runs when:
-- Explicitly set in PRD (`testStrategy: "test-after"`)
-- OR `execution.allowTestAfter: true` and router returns it
-
-### 3.3 Warning in `nax config --explain`
-
-### 3.4 Config gate
-
-```jsonc
-{
-  "execution": { "allowTestAfter": true },        // NEW — false blocks test-after
-  "tdd": { "testAfterIsolationVerify": false }    // NEW — opt-in isolation check
-}
-```
-
----
-
-## 4. Migration Path
-
-| Version | Change |
-|---|---|
-| v0.21.0 | Warning in --explain. Remove from auto-routing. Add `allowTestAfter` config. |
-| v0.22.0 | `allowTestAfter` default → `false`. Explicit opt-in required. |
-| v0.23.0+ | Evaluate full removal. |
-
----
-
-## 5. Files Affected
-
-| File | Change |
-|---|---|
-| `src/routing/strategies/llm.ts` | Remove `test-after` from auto-assignable set |
-| `src/routing/strategies/keyword.ts` | Remove `test-after` from auto-assignable set |
-| `src/tdd/session-runner.ts` | Add isolation verify step for `test-after` |
-| `src/config/schemas.ts` | Add `execution.allowTestAfter`, `tdd.testAfterIsolationVerify` |
-| `src/cli/config.ts` | Add warning in `--explain` for `test-after` |
-
----
-
-## 6. Test Plan
-
-- `allowTestAfter: false` + router selects `test-after` → fallback to `tdd-lite` + warning
-- `testAfterIsolationVerify: true` + tests pass on clean stash → escalate
-- `testAfterIsolationVerify: true` + tests fail on clean stash → normal (tests are genuine)
-- LLM router no longer returns `test-after` in auto-routing