@nathapp/nax 0.28.0 → 0.29.0

package/docs/releases/v0.15.3.md

@@ -1,193 +0,0 @@
-# nax v0.15.3 Release Notes
-
-**Release Date**: 2026-02-28
-**Type**: Minor Feature Release
-
-## Overview
-
-This release ships two major features:
-1. **US-010**: Constitution-to-Agent-Config Generator — Auto-generate agent-specific config files from `nax/constitution.md`
-2. **US-008**: Interaction System Wiring — Integrate the interaction system into the runner loop
-
----
-
-## New Features
-
-### US-010: Constitution-to-Agent-Config Generator
-
-The `nax/constitution.md` file is now the **single source of truth** for project coding standards. nax automatically generates agent-specific config files from it.
-
-**What's New:**
-- New `nax constitution generate` CLI command
-- Support for 5 agent formats:
-  - Claude Code (`CLAUDE.md`)
-  - OpenCode/Codex (`AGENTS.md`)
-  - Cursor (`.cursorrules`)
-  - Windsurf (`.windsurfrules`)
-  - Aider (`.aider.conf.yml`)
-- Dry-run mode for testing generation without writing files
-- Automatic file freshness checking
-
-**Usage:**
-
-```bash
-# Generate config files for all agents
-nax constitution generate
-
-# Generate for specific agent
-nax constitution generate --agent claude
-
-# Dry-run mode (preview without writing)
-nax constitution generate --dry-run
-
-# Custom paths
-nax constitution generate --constitution custom/path.md --output dist/
-```
-
-**Implementation Details:**
-- **Generators**: `src/constitution/generators/` — One generator per agent format
-- **Orchestrator**: `src/constitution/generator.ts` — Coordinates all generators
-- **CLI Command**: `src/cli/constitution.ts` — User-facing command
-- **Tests**: `test/unit/constitution-generators.test.ts` — 17 passing tests
-
-**Files Modified/Created:**
-- `src/constitution/generators/types.ts` (new)
-- `src/constitution/generators/claude.ts` (new)
-- `src/constitution/generators/opencode.ts` (new)
-- `src/constitution/generators/cursor.ts` (new)
-- `src/constitution/generators/windsurf.ts` (new)
-- `src/constitution/generators/aider.ts` (new)
-- `src/constitution/generator.ts` (new, 191 lines)
-- `src/cli/constitution.ts` (new, 109 lines)
-- `bin/nax.ts` (modified to register command)
-
----
-
-### US-008: Interaction System Wiring
-
-The interaction system (v0.15.0) is now fully integrated into the runner loop.
-
-**What's New:**
-- Interaction chain initialized at runner startup
-- Support for headless mode (skips interactions)
-- Automatic cleanup of interaction plugins on shutdown
-- Ready for trigger integration (security-review, cost-warning, pre-merge, max-retries, etc.)
-
-**Implementation Details:**
-- **Initialization**: `src/interaction/init.ts` — Creates interaction chain from config
-- **Runner Integration**: `src/execution/lifecycle/run-setup.ts` — Initializes chain during setup
-- **Cleanup**: `src/execution/lifecycle/run-cleanup.ts` — Destroys chain on shutdown
-- **Runner Context**: `src/execution/runner.ts` — Passes chain through execution pipeline
-
-**Files Modified:**
-- `src/interaction/init.ts` (new, 83 lines)
-- `src/interaction/index.ts` (exports `initInteractionChain`)
-- `src/execution/lifecycle/run-setup.ts` (modified to initialize chain)
-- `src/execution/lifecycle/run-cleanup.ts` (modified to destroy chain)
-- `src/execution/runner.ts` (modified to extract and pass chain)
-
-**Configuration:**
-
-Interaction config in `nax/config.json`:
-```json
-{
-  "interaction": {
-    "plugin": "cli",
-    "defaults": {
-      "timeout": 600000,
-      "fallback": "escalate"
-    },
-    "triggers": {
-      "security-review": true,
-      "cost-warning": true,
-      "pre-merge": true,
-      "max-retries": true
-    }
-  }
-}
-```
-
-When running `--headless`, all interactions are skipped (fallbacks applied immediately).
-
----
-
-## Breaking Changes
-
-None.
-
----
-
-## Bug Fixes
-
-None.
-
----
-
-## Documentation
-
-- Added `docs/releases/v0.15.3.md`
-- Updated `docs/ROADMAP.md` — marked US-008 and US-010 as complete
-
----
-
-## Testing
-
-- **New Tests**: 17 constitution generator tests (all passing)
-- **Test Coverage**: All generators tested with known input/output
-- **Line Count Compliance**: All new files < 400 lines
-
----
-
-## Migration Guide
-
-### For Constitution Generator (US-010)
-
-1. Ensure `nax/constitution.md` exists in your project
-2. Run `nax constitution generate` to create agent config files
-3. Commit generated files to version control
-4. Optional: Add generation to CI pipeline
-
-### For Interaction System (US-008)
-
-1. No action required — system initializes automatically if configured
-2. To enable interactions, add `interaction` section to `nax/config.json`
-3. To disable interactions, omit `interaction` section or run with `--headless`
-
----
-
-## What's Next
-
-- **v0.15.4+**: Wire trigger checkpoints into pipeline stages
-  - Pre-flight security review
-  - Cost gates (warning + exceeded)
-  - Pre-merge approval
-  - Max retries handling
-
----
-
-## Contributors
-
-- Claude Opus 4.6 <noreply@anthropic.com>
-
----
-
-## Install
-
-```bash
-# From NPM (when published)
-npm install -g @nathapp/nax@0.15.3
-
-# From source
-git clone https://github.com/nathapp/nax.git
-cd nax
-git checkout v0.15.3
-bun install
-bun run build
-npm install -g .
-```
-
----
-
-## Changelog
-
-Full changelog: https://github.com/nathapp/nax/compare/v0.15.1...v0.15.3

package/docs/specs/bug-039-orphan-processes.md

@@ -1,131 +0,0 @@
-# BUG-039 — Orphan Process Prevention
-
-**Status:** Proposal
-**Target:** v0.21.0
-**Author:** Nax Dev
-**Date:** 2026-03-06
-
----
-
-## 1. Problem
-
-When nax aborts a story (timeout, error, SIGTERM), several child processes are left running as orphans:
-- `bun run lint` / `bun run typecheck` (review stage)
-- `git diff`, `git log`, `git rev-parse` (smart runner, utils/git.ts)
-- `claude` CLI (decompose — no timeout at all)
-
-These processes accumulate across stories and survive after nax exits, consuming CPU/memory.
-
----
-
-## 2. Root Causes
-
-| Location | Process | Issue | Severity |
-|---|---|---|---|
-| `review/runner.ts:runCheck()` | `lint`, `typecheck` | No timeout, no kill, not in PidRegistry | 🔴 Critical |
-| `agents/claude.ts:decompose()` | `claude` CLI | No timeout set | 🔴 Critical |
-| `utils/git.ts:captureGitRef()` | `git rev-parse` | No timeout | 🟡 Medium |
-| `utils/git.ts:hasCommitsForStory()` | `git log` | No timeout | 🟡 Medium |
-| `verification/smart-runner.ts` | `git diff` | No timeout, not killed on verify abort | 🟡 Medium |
-| `agents/claude.ts:runOnce()` | `claude` CLI | SIGTERM only — no SIGKILL follow-up after grace period | 🟡 Medium |
-| `agents/claude.ts:runOnce()` | `claude` CLI | If timeout throws, `pidRegistry.unregister()` skipped → PID leaks | 🟡 Medium |
-| `routing/strategies/llm.ts` | `claude` CLI | Timeout kills proc but streams not drained → `proc.exited` may hang | 🟡 Medium |
-| `verification/executor.ts:drainWithDeadline()` | internal | `setTimeout` in drain race never cleared | 🟢 Minor |
-| `execution/pid-registry.ts:killPid()` | `kill` binary | Spawns `kill` subprocesses without timeout | 🟢 Minor |
-
-**Already correct:** `executor.ts:executeWithTimeout()` — SIGTERM + grace + SIGKILL process group. `crash-recovery.ts` — `pidRegistry.killAll()` on all signals. `pid-registry.ts:cleanupStale()` — kills orphans at startup.
-
----
-
-## 3. Proposed Fixes
-
-### Fix 1 — Shared `gitWithTimeout()` helper
-
-Replace all bare git spawns in `utils/git.ts` and `smart-runner.ts`:
-
-```typescript
-// src/utils/git.ts
-const GIT_TIMEOUT_MS = 10_000;
-
-async function gitWithTimeout(args: string[], workdir: string): Promise<{ stdout: string; exitCode: number }> {
-  const proc = Bun.spawn(["git", ...args], { cwd: workdir, stdout: "pipe", stderr: "pipe" });
-  const timerId = setTimeout(() => proc.kill("SIGKILL"), GIT_TIMEOUT_MS);
-  const exitCode = await proc.exited;
-  clearTimeout(timerId);
-  const stdout = await new Response(proc.stdout).text();
-  return { stdout, exitCode };
-}
-```
-
-Apply to: `captureGitRef()`, `hasCommitsForStory()`, `getChangedSourceFiles()` in `smart-runner.ts`.
-
-### Fix 2 — Review `runCheck()` timeout
-
-Wrap each check spawn with SIGTERM+SIGKILL pattern. Config: `review.checkTimeoutSeconds` (default: 120).
-
-### Fix 3 — `decompose()` timeout
-
-Add `timeoutSeconds` to `DecomposeOptions` (default: 300). Apply same setTimeout → SIGTERM pattern as `runOnce()`.
-
-### Fix 4 — `runOnce()` SIGKILL follow-up + `finally` unregister
-
-```typescript
-setTimeout(() => {
-  timedOut = true;
-  proc.kill("SIGTERM");
-  setTimeout(() => { try { proc.kill("SIGKILL"); } catch {} }, gracePeriodMs);
-}, timeoutMs);
-
-// Always unregister, even on exception:
-try {
-  const exitCode = await proc.exited;
-  clearTimeout(timeoutId);
-} finally {
-  await pidRegistry.unregister(processPid);
-}
-```
-
-### Fix 5 — `llm.ts` stream drain on timeout
-
-Cancel streams before killing to prevent `proc.exited` hang:
-
-```typescript
-} catch (err) {
-  clearTimeout(timeoutId);
-  proc.stdout.cancel().catch(() => {});
-  proc.stderr.cancel().catch(() => {});
-  proc.kill();
-  throw err;
-}
-```
-
-### Fix 6 — `drainWithDeadline()` timer cleanup
-
-Store and clear the setTimeout handle after the race resolves.
-
----
-
-## 4. Files Affected
-
-| File | Change |
-|---|---|
-| `src/utils/git.ts` | Add `gitWithTimeout()` helper; use in all git spawns |
-| `src/verification/smart-runner.ts` | Use `gitWithTimeout()` for `git diff` |
-| `src/review/runner.ts` | Add timeout + SIGTERM/SIGKILL to `runCheck()` |
-| `src/config/schemas.ts` | Add `review.checkTimeoutSeconds` (default: 120) |
-| `src/config/types.ts` | Add `checkTimeoutSeconds` to `ReviewConfig` |
-| `src/agents/claude.ts` | Fix `decompose()` timeout; `runOnce()` SIGKILL + finally |
-| `src/agents/types.ts` | Add `timeoutSeconds` to `DecomposeOptions` |
-| `src/routing/strategies/llm.ts` | Cancel streams before kill on timeout |
-| `src/verification/executor.ts` | `clearTimeout` in `drainWithDeadline()` |
-
----
-
-## 5. Test Plan
-
-- `runCheck()` with hanging command → killed after `checkTimeoutSeconds`
-- `decompose()` with hanging claude → times out, PID unregistered
-- `runOnce()` timeout → SIGKILL after grace period; PID unregistered even on exception
-- `gitWithTimeout()` → returns error after 10s (no hanging promise)
-- `drainWithDeadline()` → no leaked setTimeout (verify with fake timers)
-- `llm.ts` timeout → `proc.exited` resolves after kill (no hang)

package/docs/specs/bug-040-review-rectification.md

@@ -1,82 +0,0 @@
-# BUG-040 — Review Rectification Loop
-
-**Status:** Proposal
-**Target:** v0.21.0
-**Author:** Nax Dev
-**Date:** 2026-03-06
-
----
-
-## 1. Problem
-
-A story that fails lint or typecheck during the review stage is **permanently killed** — no retry, no agent fix, immediate escalation. This wastes an entire escalation slot on a trivial auto-fixable error.
-
-**Example:** Agent implements story correctly. All tests pass (verify ✅). Review runs `biome check` → 3 lint errors. Review returns `{ action: "fail" }` → story marked failed → escalates to `balanced` → `balanced` agent re-implements from scratch → also gets lint errors → `powerful` tier used. All for a `biome --fix` that takes 2 seconds.
-
----
-
-## 2. Root Cause
-
-```
-review.ts:execute() → runReview() → { success: false }
-  → return { action: "fail" }        ← always "fail" for any review failure
-
-pipeline-result-handler.ts
-  case "fail": markStoryFailed()     ← permanent, no retry
-```
-
-The verify stage correctly returns `"escalate"` on test failure, enabling rectification. Review has no equivalent.
-
----
-
-## 3. Proposed Architecture
-
-```
-review.ts → runReview() fails
-  → return { action: "review-rectify", output }   ← NEW
-
-pipeline-result-handler.ts
-  case "review-rectify":
-    → runReviewRectification(story, reviewOutput, config, workdir)
-        → agent: "Fix these lint/typecheck errors:\n<output>"
-        → re-run review
-        → pass?  → "continue"
-        → fail?  → "escalate" (if attempts exhausted)
-```
-
----
-
-## 4. Files Affected
-
-| File | Change |
-|---|---|
-| `src/pipeline/stages/review.ts` | Return `{ action: "review-rectify", output }` instead of `"fail"` |
-| `src/pipeline/types.ts` | Add `"review-rectify"` to `StageAction` union |
-| `src/execution/pipeline-result-handler.ts` | Handle `"review-rectify"` → call `runReviewRectification()` |
-| `src/execution/review-rectification.ts` | **New:** `runReviewRectification()` loop |
-| `src/config/schemas.ts` | Add `review.maxRectificationAttempts` (default: 1) |
-| `src/config/types.ts` | Add `maxRectificationAttempts` to `ReviewConfig` |
-
----
-
-## 5. Config Changes
-
-```jsonc
-{
-  "review": {
-    "enabled": true,
-    "checks": ["typecheck", "lint"],
-    "maxRectificationAttempts": 1   // 0 = revert to old "fail" behavior
-  }
-}
-```
-
----
-
-## 6. Test Plan
-
-- Lint failure → `runReviewRectification()` called with lint output
-- Rectification passes → story continues (not escalated)
-- Rectification fails → story escalates (not permanently failed)
-- `maxRectificationAttempts: 0` → old behavior (immediate escalate)
-- Plugin reviewer rejection → still `"fail"` (not routed through rectification)

package/docs/specs/bug-041-cross-story-test-isolation.md

@@ -1,88 +0,0 @@
-# BUG-041 — Cross-Story Test Isolation
-
-**Status:** Won't Fix — superseded by FEAT-010 (baseRef tracking eliminates root cause)
-**Target:** N/A
-**Author:** Nax Dev
-**Date:** 2026-03-06
-
----
-
-## 1. Problem
-
-**Scenario:**
-1. Story A touches `src/parser.ts`. Verify runs `test/unit/parser.test.ts` → 2 tests fail. Story A escalates.
-2. Story B touches `src/formatter.ts`. Smart runner also picks up `test/unit/parser.test.ts` (both changed since common base). Formatter tests pass, parser tests still fail (inherited from Story A).
-3. Story B is marked failed — its implementation was correct. It escalates needlessly.
-
-**Root cause:** Verify has no memory of which test failures pre-existed before a story's session. All failures are attributed to the current story.
-
----
-
-## 2. Root Cause
-
-The verify stage runs tests and reports pass/fail with no concept of:
-- Which tests were already failing before this story ran
-- Whether a failure is "inherited" vs "introduced by this story"
-
----
-
-## 3. Proposed Solution
-
-### 3.1 Baseline snapshot at story start
-
-Before the agent session starts (same time as FEAT-010's `baseRef` capture), record which test files the smart runner would pick up for this story and which are already failing. Store as `story.inheritedFailures: string[]`.
-
-### 3.2 Verify: filter inherited failures
-
-After running tests and parsing `TestFailure[]`:
-- If ALL failures are in `inheritedFailures` files → return `{ action: "continue" }` with warning: *"Failures are pre-existing — not attributed to this story"*
-- If ANY failure is in a new file → escalate normally
-
-### 3.3 Re-verify when source story resolves
-
-When Story A eventually passes verify, clear its test files from downstream stories' `inheritedFailures` so they get re-evaluated on the next run.
-
----
-
-## 4. Data Model Changes
-
-```typescript
-// src/prd/types.ts
-interface UserStory {
-  baseRef?: string;               // from FEAT-010
-  inheritedFailures?: string[];   // NEW — test files already failing before this story
-}
-```
-
----
-
-## 5. Files Affected
-
-| File | Change |
-|---|---|
-| `src/prd/types.ts` | Add `inheritedFailures?: string[]` to `UserStory` |
-| `src/execution/sequential-executor.ts` | Capture `inheritedFailures` baseline before agent runs |
-| `src/verification/smart-runner.ts` | Export `runBaselineCheck(testFiles, workdir)` helper |
-| `src/pipeline/stages/verify.ts` | Filter inherited failures from escalation decision |
-| `src/execution/lifecycle/run-regression.ts` | Clear inherited failures when source story passes |
-
----
-
-## 6. Edge Cases
-
-| Scenario | Handling |
-|---|---|
-| Baseline check times out | `inheritedFailures: []` — conservative, may incorrectly blame story but no false passes |
-| Flaky inherited failure disappears | Story B's verify finds no inherited failures → correct attribution |
-| ALL test files in `inheritedFailures` | Return `continue` with warning |
-| First story in a run | No prior failures → `inheritedFailures: []` → normal behavior |
-| Deferred regression gate | Runs after all stories pass — inherited failures expected to be resolved |
-
----
-
-## 7. Test Plan
-
-- Story B inherits Story A's failing test file → verify returns `continue` (not escalated)
-- Story B introduces new failing test → escalated normally
-- Story A passes → Story B's `inheritedFailures` cleared for next run
-- Baseline check timeout → `inheritedFailures: []` → conservative

package/docs/specs/bug-042-verifier-failure-capture.md

@@ -1,117 +0,0 @@
-# BUG-042 — Verifier Test Failure Capture
-
-**Status:** Proposal
-**Target:** v0.21.0
-**Author:** Nax Dev
-**Date:** 2026-03-06
-
----
-
-## 1. Problem
-
-The deferred regression gate (`run-regression.ts`) calls `parseBunTestOutput()` → gets structured `TestFailure[]` (file, testName, error, stackTrace) → targeted rectification works well.
-
-The per-story verify stage (`verify.ts`) does NOT call `parseBunTestOutput()` on failure → passes raw output string to rectification → agent receives a wall of text and must parse it mentally.
-
-**Same failure, two different agent experiences:**
-
-| Path | Agent gets | Quality |
-|---|---|---|
-| Deferred regression | Structured `TestFailure[]` | ✅ Precise context |
-| Per-story verify | Raw output (last 20 lines) | ⚠️ Noisy, may miss root cause |
-
----
-
-## 2. Current vs Proposed Data Flow
-
-**Current:**
-```
-verify.ts → runVerification() → { success: false, output: "...raw..." }
-  → rectification: testOutput = raw string
-  → priorFailures[].testFailures = undefined
-  → agent prompt: wall of text
-```
-
-**Proposed:**
-```
-verify.ts → runVerification() → { success: false, output: "...raw..." }
-  → parseBunTestOutput(output) → TestFailure[]
-  → VerificationResult.failures = TestFailure[]
-  → rectification: testOutput + structured failures
-  → priorFailures[].testFailures = TestFailure[]
-  → agent prompt: structured failure table
-```
-
----
-
-## 3. Code Changes
-
-**`src/verification/types.ts`** — add failures field:
-```typescript
-interface VerificationResult {
-  success: boolean;
-  output?: string;
-  status: "SUCCESS" | "TEST_FAILURE" | "TIMEOUT" | "ERROR";
-  passCount?: number;
-  failCount?: number;
-  failures?: TestFailure[];   // NEW
-}
-```
-
-**`src/pipeline/stages/verify.ts`** — parse on failure:
-```typescript
-// Add to _verifyDeps:
-export const _verifyDeps = {
-  regression,
-  parseBunTestOutput,   // NEW — injectable for tests
-};
-
-// After runVerification() failure:
-if (!result.success && result.output) {
-  result.failures = _verifyDeps.parseBunTestOutput(result.output).failures;
-}
-```
-
-**Structured log** — replace last-20-lines with failure summary:
-```typescript
-// Current: logger.warn("verify", "Test failures", { output: last20lines });
-// Proposed:
-for (const f of (result.failures ?? []).slice(0, 5)) {
-  logger.warn("verify", `FAIL: ${f.testName}`, { file: f.file, error: f.error });
-}
-```
-
-**`src/execution/post-verify-rectification.ts`** — populate `testFailures` in `StructuredFailure`:
-```typescript
-const structuredFailure: StructuredFailure = {
-  // ...existing fields
-  testFailures: result.failures?.map(f => ({
-    file: f.file ?? "",
-    testName: f.testName,
-    error: f.error,
-    stackTrace: f.stackTrace ?? [],
-  })),
-};
-```
-
----
-
-## 4. Files Affected
-
-| File | Change |
-|---|---|
-| `src/verification/types.ts` | Add `failures?: TestFailure[]` to `VerificationResult` |
-| `src/pipeline/stages/verify.ts` | Call `parseBunTestOutput()` on failure; add to `_verifyDeps` |
-| `src/execution/post-verify-rectification.ts` | Populate `testFailures` from `result.failures` |
-| `src/execution/verification.ts` | Pass `failures` through if available |
-
----
-
-## 5. Test Plan
-
-- `verify.ts` test failure → `result.failures` populated with `TestFailure[]`
-- `result.failures` forwarded to rectification loop and `priorFailures`
-- Agent prompt includes structured failure table (via existing priorFailures formatter)
-- `parseBunTestOutput` in `_verifyDeps` is mockable
-- Empty/no output → `result.failures = []` (no crash)
-- Timeout → `result.failures` not set (timeout ≠ test failure)