@nathapp/nax 0.22.1 → 0.22.3

package/CLAUDE.md

@@ -75,6 +75,23 @@ Runner.run()  [src/execution/runner.ts — thin orchestrator only]
 
 Detailed coding standards, test architecture, and forbidden patterns are in `.claude/rules/`. Claude Code loads these automatically.
 
+
+## Code Intelligence (Solograph MCP)
+
+Use **solograph** MCP tools on-demand for code understanding. Do not use web_search, kb_search, or source_* tools.
+
+| Tool | When to use |
+|:-----|:------------|
+| `project_code_search` | Find existing patterns, symbols, or implementations before writing new code |
+| `codegraph_explain` | Get architecture overview of nax before tackling unfamiliar areas |
+| `codegraph_query` | Cypher queries — dependency analysis, impact analysis, hub files |
+| `codegraph_stats` | Quick graph stats (file/symbol counts) |
+| `codegraph_shared` | Find packages shared across projects |
+| `session_search` | Search prior Claude Code session history for relevant context |
+| `project_info` | Project registry info |
+| `project_code_reindex` | Reindex after creating or deleting source files, or major refactors |
+
+Single source of truth: VPS solograph instance (Mac01 tunnels to VPS — same data either way).
 ## IMPORTANT
 
 - Do NOT push to remote — let the human review and push.

package/bin/nax.ts

@@ -39,7 +39,7 @@
 
 import { existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { join } from "node:path";
 import chalk from "chalk";
 import { Command } from "commander";
 
@@ -217,7 +217,6 @@ program
   .option("--silent", "Silent mode (errors only)", false)
   .option("--json", "JSON mode (raw JSONL output to stdout)", false)
   .option("-d, --dir <path>", "Working directory", process.cwd())
-  .option("--status-file <path>", "Write machine-readable JSON status file (updated during run)")
   .option("--skip-precheck", "Skip precheck validations (advanced users only)", false)
   .action(async (options) => {
     // Validate directory path
@@ -331,8 +330,8 @@ program
       console.log(chalk.dim("   [Headless mode — pipe output]"));
     }
 
-    // Resolve --status-file relative to cwd (absolute paths unchanged)
-    const statusFilePath = options.statusFile ? resolve(process.cwd(), options.statusFile) : undefined;
+    // Compute status file path: <workdir>/nax/status.json
+    const statusFilePath = join(workdir, "nax", "status.json");
 
     // Parse --parallel option
     let parallel: number | undefined;

package/docs/ROADMAP.md

@@ -6,10 +6,10 @@
 
 ---
 
-## Next: v0.18.0 — Orchestration Quality
+## v0.18.0 — Orchestration Quality ✅
 
 **Theme:** Fix execution bugs and improve orchestration reliability
-**Status:** 🔲 Planned
+**Status:** ✅ Shipped (2026-03-03)
 
 ### Bugfixes (Priority)
 - [x] ~~**BUG-016:** Hardcoded 120s timeout in verify stage → read from config~~
@@ -64,19 +64,8 @@
 - [x] ~~Result: verify drops from ~125s to ~10-20s for typical single-file fixes~~
 
 ### Bun PTY Migration (BUN-001)
-- [ ] Replace `node-pty` (native addon, requires python/make/g++ to build) with `Bun.Terminal` API (v1.3.5+)
-- [ ] Update `src/agents/claude.ts` `runInteractive()` — replace `nodePty.spawn()` with `Bun.Terminal`
-- [ ] Update `src/tui/hooks/usePty.ts` — replace `IPty` interface with Bun equivalent
-- [ ] Remove `node-pty` from `dependencies` in `package.json`
-- [ ] Remove `--ignore-scripts` workaround from `.gitlab-ci.yml`
-- [ ] Benefit: no native build, no gyp/python/gcc in CI, cleaner alpine support
-
-### CI Memory Optimization (CI-001)
-- [ ] Investigate splitting test suite into parallel jobs (unit / integration / ui) to reduce per-job peak memory
-- [ ] Evaluate `bun test --shard` when stable (currently experimental)
-- [ ] Target: make test suite pass on 1GB runners (currently requires 8GB shared runner)
-- [ ] Known constraints: 2008 tests across 125 files, ~75s on local VPS (3.8GB), OOMs even with `--smol --concurrency 1`
-- [ ] Current workaround: use `saas-linux-small-amd64` (8GB) shared runner
+- [x] ~~Replace `node-pty` with `Bun.spawn` (piped stdio) — shipped in v0.18.5~~
+
 
 ---
 
@@ -125,12 +114,35 @@
 **Spec:** [docs/specs/bun-pty-migration.md](specs/bun-pty-migration.md)
 
 ### BUN-001: Replace node-pty with Bun.spawn
-- [x] Research gate: verify `Bun.Terminal` availability on Bun 1.3.9; confirm Claude Code works with piped stdio
-- [ ] `src/agents/claude.ts` `runInteractive()` — replace `nodePty.spawn()` with `Bun.spawn` (piped stdio)
-- [ ] `src/tui/hooks/usePty.ts` — replace `pty.IPty` state with `Bun.Subprocess`
-- [ ] `src/agents/types.ts` — remove `IPty` dependency from `PtyHandle` interface
-- [ ] `package.json` — remove `node-pty` from dependencies
-- [ ] `.gitlab-ci.yml` — remove `python3 make g++` from `apk add`; remove `--ignore-scripts` from `bun install`
+- [x] ~~All sub-items complete — `claude.ts` + `usePty.ts` migrated to `Bun.spawn`, `node-pty` removed from `package.json`, CI cleaned up~~
+
+---
+
+## v0.23.0 — Status File Consolidation
+
+**Theme:** Auto-write status.json to well-known paths, align readers, remove dead options
+**Status:** 🔄 In Progress (self-dev running, SFC-001 ✅)
+**Spec:** [docs/specs/status-file-consolidation.md](specs/status-file-consolidation.md)
+**Pre-requisite for:** v0.24.0 (Central Run Registry)
+
+### Stories
+- [x] ~~**SFC-001:** Auto-write project-level status — remove `--status-file` flag, always write to `<workdir>/nax/status.json`~~
+- [ ] **SFC-002:** Write feature-level status on run end — copy final snapshot to `<workdir>/nax/features/<feature>/status.json`
+- [ ] **SFC-003:** Align status readers — `nax status` + `nax diagnose` read from correct paths
+- [ ] **SFC-004:** Clean up dead code — remove `--status-file` option, `.nax-status.json` references
+
+---
+
+## v0.24.0 — Central Run Registry
+
+**Theme:** Global run index across all projects — single source of truth for all nax run history
+**Status:** 🔲 Planned
+**Spec:** [docs/specs/central-run-registry.md](specs/central-run-registry.md)
+
+### Stories
+- [ ] **CRR-001:** `src/pipeline/subscribers/registry.ts` — `wireRegistry()` subscriber, listens to `run:started`, writes `~/.nax/runs/<project>-<feature>-<runId>/meta.json` (path pointers only — no data duplication, no symlinks)
+- [ ] **CRR-002:** `src/commands/runs.ts` — `nax runs` CLI, reads `meta.json` → resolves live `status.json` from `statusPath`, displays table (project, feature, status, stories, duration, date). Filters: `--project`, `--last`, `--status`
+- [ ] **CRR-003:** `nax logs --run <runId>` — resolve run from global registry via `eventsDir`, stream logs from any directory
 
 ---
 
@@ -148,25 +160,25 @@
 - [x] ~~**BUG-041:**~~ Won't fix — superseded by FEAT-010
 - [x] ~~**FEAT-012:**~~ Won't fix — balanced tier sufficient for test-writer
 
-### → v0.22.0 Pipeline Re-Architecture (in progress)
+### → v0.22.1 Pipeline Re-Architecture ✅ Shipped (2026-03-07)
 **ADR:** [docs/adr/ADR-005-pipeline-re-architecture.md](adr/ADR-005-pipeline-re-architecture.md)
 **Plan:** [docs/adr/ADR-005-implementation-plan.md](adr/ADR-005-implementation-plan.md)
-**Branch:** `feat/re-architecture`
 
-**Theme:** Eliminate ad-hoc orchestration, consolidate 4 scattered verification paths into single orchestrator, add event-bus-driven hooks/plugins/interaction, new stages (rectify, autofix, regression).
+**Theme:** Eliminate ad-hoc orchestration, consolidate 4 scattered verification paths into single orchestrator, add event-bus-driven hooks/plugins/interaction, new stages (rectify, autofix, regression), post-run pipeline SSOT.
 
-- [ ] **Phase 0:** Test suite preparation — reorganize, split monsters, RE-ARCH tags, coverage gaps
-- [ ] **Phase 1:** VerificationOrchestrator + Pipeline Event Bus (additive, no behavior change)
-- [ ] **Phase 2:** New stages — `rectify`, `autofix`, `regression` + `retry` stage action
-- [ ] **Phase 3:** Event-bus subscribers for hooks, reporters, interaction (replace 20+ scattered call sites)
-- [ ] **Phase 4:** Delete deprecated files, simplify sequential executor to ~80 lines
+- [x] **Phase 1:** VerificationOrchestrator + Pipeline Event Bus (additive, no behavior change)
+- [x] **Phase 2:** New stages — `rectify`, `autofix`, `regression` + `retry` stage action
+- [x] **Phase 3:** Event-bus subscribers for hooks, reporters, interaction (replace 20+ scattered call sites)
+- [x] **Phase 5:** Post-run pipeline SSOT — `deferred-regression` stage, tier escalation into `iteration-runner`, `runAcceptanceLoop` → `runPipeline(postRunPipeline)`
 
-**Resolves in this version:**
-- [ ] **BUG-040:** Lint/typecheck auto-repair → `autofix` stage + `quality.commands.lintFix/formatFix`
-- [ ] **BUG-042:** Verifier failure capture → unified `VerifyResult` with `failures[]` always populated
-- [ ] **FEAT-014:** Heartbeat observability → Pipeline Event Bus with typed events
-- [ ] **BUG-026:** Regression gate triggers full retry → targeted `rectify` stage with `retry` action
-- [ ] **BUG-028:** Routing cache ignores escalation tier → cache key includes tier
+**Resolved:**
+- [x] **BUG-040:** Lint/typecheck auto-repair → `autofix` stage + `quality.commands.lintFix/formatFix`
+- [x] **BUG-042:** Verifier failure capture → unified `VerifyResult` with `failures[]` always populated
+- [x] **FEAT-014:** Heartbeat observability → Pipeline Event Bus with typed events
+- [x] **BUG-026:** Regression gate triggers full retry → targeted `rectify` stage with `retry` action
+- [x] **BUG-028:** Routing cache ignores escalation tier → cache key includes tier
+
+**Test results:** 2264 pass, 12 skip, 1 fail (pre-existing disk space flaky)
 
 ---
 
@@ -202,9 +214,6 @@
 - [x] `priorFailures` injected into escalated agent prompts via `context/builder.ts`
 - [x] Reverse file mapping for regression attribution
 
-### Central Run Registry (carried forward)
-- [ ] `~/.nax/runs/<project>-<feature>-<runId>/` with status.json + events.jsonl symlink
-
 ---
 
 ## Shipped
@@ -212,6 +221,8 @@
 | Version | Theme | Date | Details |
 |:---|:---|:---|:---|
 | v0.18.1 | Type Safety + CI Pipeline | 2026-03-03 | 60 TS errors + 12 lint errors fixed, GitLab CI green (1952/56/0) |
+| v0.22.2 | Routing Stability + SFC-001 | 2026-03-07 | BUG-040 floating outputPromise crash on LLM timeout retry; SFC-001 auto-write status.json |
+| v0.22.1 | Pipeline Re-Architecture | 2026-03-07 | VerificationOrchestrator, EventBus, new stages (rectify/autofix/regression/deferred-regression), post-run SSOT. 2264 pass |
 | v0.20.0 | Verification Architecture v2 | 2026-03-06 | Deferred regression gate, remove duplicate tests, BUG-037 |
 | v0.19.0 | Hardening & Compliance | 2026-03-04 | SEC-1 to SEC-5, BUG-1, Node.js API removal, _deps rollout |
 | v0.18.5 | Bun PTY Migration | 2026-03-04 | BUN-001: node-pty → Bun.spawn, CI cleanup, flaky test fix |
@@ -271,16 +282,17 @@
 - [x] **BUG-032:** Routing stage overrides escalated `modelTier` with complexity-derived tier. `src/pipeline/stages/routing.ts:43` always runs `complexityToModelTier(routing.complexity, config)` even when `story.routing.modelTier` was explicitly set by `handleTierEscalation()`. BUG-026 was escalated to `balanced` (logged in iteration header), but `Task classified` shows `modelTier=fast` because `complexityToModelTier("simple", config)` → `"fast"`. Related to BUG-013 (escalation routing not applied) which was marked fixed, but the fix in `applyCachedRouting()` in `pipeline-result-handler.ts:295-310` runs **after** the routing stage — too late. **Location:** `src/pipeline/stages/routing.ts:43`. **Fix:** When `story.routing.modelTier` is explicitly set (by escalation), skip `complexityToModelTier()` and use the cached tier directly. Only derive from complexity when `story.routing.modelTier` is absent.
 - [x] **BUG-033:** LLM routing has no retry on timeout — single attempt with hardcoded 15s default. All 5 LLM routing attempts in the v0.18.3 run timed out at 15s, forcing keyword fallback every time. `src/routing/strategies/llm.ts:63` reads `llmConfig?.timeoutMs ?? 15000` but there's no retry logic — one timeout = immediate fallback. **Location:** `src/routing/strategies/llm.ts:callLlm()`. **Fix:** Add `routing.llm.retries` config (default: 1) with backoff. Also surface `routing.llm.timeoutMs` in `nax config --explain` and consider raising default to 30s for batch routing which processes multiple stories.
 
-- [ ] **BUG-037:** Test output summary (verify stage) captures precheck boilerplate instead of actual `bun test` failure. **Symptom:** Logs show successful prechecks (Head) instead of failed tests (Tail). **Fix:** Change `Test output preview` log to tail the last 20 lines of output instead of heading the first 10.
-- [ ] **BUG-038:** `smart-runner` over-matching when global defaults change. **Symptom:** Changing `DEFAULT_CONFIG` matches broad integration tests that fail due to environment/precheck side effects, obscuring targeted results. **Fix:** Refine path mapping to prioritize direct unit tests and exclude known heavy integration tests from default smart-runner matches unless explicitly relevant.
+- [x] ~~**BUG-037:** Test output summary (verify stage) captures precheck boilerplate instead of actual `bun test` failure. Fixed: `.slice(-20)` tail — shipped in v0.22.1 (re-arch phase 2).~~
+- [x] ~~**BUG-038:** `smart-runner` over-matching when global defaults change. Fixed by FEAT-010 (v0.21.0) — per-attempt `storyGitRef` baseRef tracking; `git diff <baseRef>..HEAD` prevents cross-story file pollution.~~
 ### Features
 - [x] ~~`nax unlock` command~~
 - [x] ~~Constitution file support~~
 - [x] ~~Per-story testStrategy override — v0.18.1~~
 - [x] ~~Smart Test Runner — v0.18.2~~
-- [x] ~~Central Run Registry — v0.19.0~~
-- [ ] **BUN-001:** Bun PTY Migration — replace `node-pty` with `Bun.Terminal` API
+- [ ] **Central Run Registry** — moved to v0.24.0
+- [x] ~~**BUN-001:** Bun PTY Migration — replace `node-pty` with `Bun.spawn` (piped stdio). Shipped in v0.18.5.~~
 - [ ] **CI-001:** CI Memory Optimization — parallel test sharding for 1GB runners
+- [ ] **CI-001:** CI Memory Optimization — parallel test sharding to pass on 1GB runners (currently requires 8GB). Evaluate `bun test --shard` when stable.
 - [ ] Cost tracking dashboard
 - [ ] npm publish setup
 - [ ] `nax diagnose --ai` flag (LLM-assisted, future TBD)
@@ -296,4 +308,4 @@ Sequential canary → stable: `v0.12.0-canary.0` → `canary.N` → `v0.12.0`
 Canary: `npm publish --tag canary`
 Stable: `npm publish` (latest)
 
-*Last updated: 2026-03-06 (v0.21.0 shipped; v0.22.0: Pipeline Re-Architecture in progress — ADR-005, 5 phases, resolves BUG-026/028/040/042 + FEAT-014)*
+*Last updated: 2026-03-07 (v0.22.1 shipped — Pipeline Re-Architecture: VerificationOrchestrator, EventBus, new stages, post-run SSOT)*

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

@@ -0,0 +1,104 @@
+# Central Run Registry — Spec
+
+**Version:** v0.23.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-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/status-file-consolidation.md

@@ -0,0 +1,93 @@
+# Status File Consolidation — Spec
+
+**Version:** v0.22.2
+**Status:** Planned
+**Pre-requisite for:** v0.23.0 (Central Run Registry)
+
+---
+
+## Problem
+
+StatusWriter only writes `status.json` when the `--status-file` CLI flag is explicitly passed. Without it, no status file is written. Additionally, `nax status` and `nax diagnose` read from different (non-existent) paths, creating a three-way disconnect.
+
+### Current State
+
+| Component | Path | Exists? |
+|-----------|------|---------|
+| StatusWriter (writer) | `--status-file <path>` (opt-in) | Only if flag passed |
+| `nax status` (reader) | `nax/features/<feature>/status.json` | ❌ Never written |
+| `nax diagnose` (reader) | `<workdir>/.nax-status.json` | ❌ Legacy path |
+| Actual file on disk | `nax/status.json` | Only from manual flag usage |
+
+## Goal
+
+Auto-write status files to well-known paths. Zero config, zero flags. Both project-level and feature-level status always available.
+
+### Target State
+
+| File | Written | Purpose |
+|------|---------|---------|
+| `<workdir>/nax/status.json` | Continuously during run | Live monitoring: "is nax running? which feature? cost?" |
+| `<workdir>/nax/features/<feature>/status.json` | Once at run end | Historical: "what was the last run result for this feature?" |
+
+---
+
+## Stories
+
+### SFC-001: Auto-write project-level status
+
+**What:** Remove `--status-file` CLI option. StatusWriter always writes to `<workdir>/nax/status.json` automatically.
+
+**Changes:**
+- `bin/nax.ts` — remove `--status-file` option, compute `statusFile = join(workdir, "nax", "status.json")` automatically
+- `src/execution/runner.ts` — `statusFile` no longer optional in `RunOptions`, always provided
+- `src/execution/status-writer.ts` — remove the `if (!this.statusFile)` guard in `update()` (statusFile is always set)
+- `src/execution/lifecycle/run-setup.ts` — statusFile always provided
+
+**Test:** Run nax without `--status-file` flag → verify `nax/status.json` is written with correct schema.
+
+### SFC-002: Write feature-level status on run end
+
+**What:** On run complete/fail/crash, copy the final status snapshot to `<workdir>/nax/features/<feature>/status.json`.
+
+**Changes:**
+- `src/execution/status-writer.ts` — add `writeFeatureStatus(featureDir: string)` method that writes current snapshot to `<featureDir>/status.json`
+- `src/execution/runner.ts` — call `statusWriter.writeFeatureStatus(featureDir)` in the finally block (after run completes, fails, or crashes)
+- `src/execution/crash-recovery.ts` — also write feature status on crash
+
+**Test:** After a completed run, verify `nax/features/<feature>/status.json` exists with `status: "completed"` or `"failed"`.
+
+### SFC-003: Align status readers
+
+**What:** Make `nax status` and `nax diagnose` read from the correct paths.
+
+**Changes:**
+- `src/cli/status-features.ts` — `loadStatusFile()` already reads from `<featureDir>/status.json` (correct after SFC-002 writes there). No change needed for feature-level.
+- `src/cli/status-features.ts` — add project-level status display: read `nax/status.json` to show "currently running" info at the top of `nax status` output
+- `src/cli/diagnose.ts` — change `.nax-status.json` → `nax/status.json`
+
+**Test:** `nax status` shows current run info from project-level status + per-feature historical info. `nax diagnose` correctly detects running/stalled/crashed state.
+
+### SFC-004: Clean up dead code
+
+**What:** Remove deprecated paths and dead options.
+
+**Changes:**
+- `bin/nax.ts` — remove `--status-file` option definition and `statusFilePath` resolve logic
+- `src/cli/diagnose.ts` — remove `.nax-status.json` path reference
+- `src/execution/runner.ts` — remove `statusFile?` optional from `RunOptions` type (now required, auto-computed)
+
+**Test:** Verify no references to `.nax-status.json` or `--status-file` remain in codebase.
+
+---
+
+## Schema (unchanged)
+
+The `NaxStatusFile` interface in `src/execution/status-file.ts` is already correct. No schema changes needed — both project-level and feature-level files use the same `NaxStatusFile` type.
+
+---
+
+## Out of Scope
+
+- Central Run Registry (`~/.nax/runs/`) — v0.23.0
+- Status file cleanup/rotation — future

package/nax/features/post-rearch-bugfix/prd.json

@@ -0,0 +1,137 @@
+{
+  "project": "nax",
+  "branchName": "feat/post-rearch-bugfix",
+  "feature": "post-rearch-bugfix",
+  "version": "0.22.3",
+  "description": "Fix all critical and key high-priority bugs found in post-re-architecture code review. Stream deadlocks, unhandled rejections, signal handler safety, lock file reliability, interaction system, parallel executor race, and error swallowing.",
+  "userStories": [
+    {
+      "id": "FIX-C1",
+      "title": "Fix stream deadlock in acceptance and autofix stages",
+      "description": "In src/pipeline/stages/acceptance.ts (line ~136) and src/pipeline/stages/autofix.ts (line ~116), the code awaits proc.exited BEFORE reading stdout/stderr. When output exceeds the 64KB OS pipe buffer, the child blocks on write and proc.exited never resolves, causing a silent deadlock. Fix: use Promise.all([proc.exited, new Response(proc.stdout).text(), new Response(proc.stderr).text()]) to read streams concurrently with exit.",
+      "complexity": "simple",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "acceptance.ts reads stdout/stderr concurrently with proc.exited using Promise.all",
+        "autofix.ts reads stdout/stderr concurrently with proc.exited using Promise.all",
+        "No sequential await proc.exited before stream reads in either file",
+        "Existing tests pass"
+      ]
+    },
+    {
+      "id": "FIX-C2",
+      "title": "Fix emitAsync never called for human-in-the-loop interaction",
+      "description": "In src/execution/pipeline-result-handler.ts (line ~151), human-review:requested is emitted via fire-and-forget emit() instead of emitAsync(). The emitAsync() method in src/pipeline/subscribers/interaction.ts was specifically designed to wait for human response but is never called anywhere. The pipeline races past without waiting for human input. Fix: use await pipelineEventBus.emitAsync() for human-review events.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "human-review:requested event uses emitAsync instead of emit",
+        "Pipeline waits for human response before continuing",
+        "emitAsync is properly awaited at the call site",
+        "Existing tests pass"
+      ]
+    },
+    {
+      "id": "FIX-C5",
+      "title": "Fix timeoutPromise unhandled rejection in LLM routing",
+      "description": "In src/routing/strategies/llm.ts, the timeoutPromise created in callLlmOnce() uses reject() but if the timer fires between race resolution and clearTimeout, the rejection is unhandled. Add timeoutPromise.catch(() => {}) right after creation, or restructure to use a clearable pattern that does not reject.",
+      "complexity": "simple",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "timeoutPromise rejection is always handled (no unhandled rejection possible)",
+        "Existing BUG-040 tests still pass",
+        "Add test verifying no unhandled rejection when timeout fires after successful completion"
+      ]
+    },
+    {
+      "id": "FIX-C3",
+      "title": "Fix TDZ crash in signal handler — prd accessed before initialization",
+      "description": "In src/execution/runner.ts around line 123, the crash handler closure references prd which is declared later (~line 134). If SIGTERM arrives during setupRun(), accessing prd throws ReferenceError. Fix: declare let prd: PRD | undefined before the crash handler setup, and add a null guard in the getter: () => prd ? countStories(prd).total : 0.",
+      "complexity": "simple",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "prd variable declared before crash handler registration",
+        "Crash handler getter has null guard for prd",
+        "SIGTERM during setupRun does not throw ReferenceError",
+        "Existing tests pass"
+      ]
+    },
+    {
+      "id": "FIX-C6",
+      "title": "Fix parallel executor shared mutable state race condition",
+      "description": "In src/execution/parallel.ts around line 191 and 213, results.totalCost += ... and executing.splice(index, 1) are mutated concurrently from parallel promises. The splice inside .finally() can corrupt array indices when two promises resolve in the same microtask batch. Fix: replace executing array with a Set pattern; use executing.delete(p) instead of splice.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "executing collection uses Set instead of Array with splice",
+        "totalCost accumulation is safe against concurrent updates",
+        "No array index corruption possible when promises resolve simultaneously",
+        "Existing tests pass"
+      ]
+    },
+    {
+      "id": "FIX-C7",
+      "title": "Fix corrupt lock file permanently blocking all runs",
+      "description": "In src/execution/lock.ts around line 48-79, if JSON.parse(lockContent) throws on a corrupted lock file, the error propagates to the outer catch which returns false, the caller interprets this as another process is running. Fix: wrap JSON.parse in its own try-catch; treat unparseable lock files as stale and delete them.",
+      "complexity": "simple",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "Corrupt/unparseable lock file is treated as stale and deleted",
+        "A warning is logged when a corrupt lock file is found",
+        "nax can start normally after encountering a corrupt lock file",
+        "Existing tests pass"
+      ]
+    },
+    {
+      "id": "FIX-C8",
+      "title": "Fix empty catch in drainWithDeadline swallowing all errors",
+      "description": "In src/verification/executor.ts around line 36-39, the catch block in drainWithDeadline swallows ALL exceptions including TypeError, OutOfMemoryError etc. Output silently becomes empty string with no diagnostic. Fix: narrow the catch to expected stream-destroyed errors only; log unexpected errors at debug level.",
+      "complexity": "simple",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "Expected stream errors (after kill) are still silently handled",
+        "Unexpected errors are logged at debug level",
+        "Output defaults to empty string on expected stream errors",
+        "Existing tests pass"
+      ]
+    },
+    {
+      "id": "FIX-H16",
+      "title": "Fix lock file not released when setupRun fails",
+      "description": "In src/execution/lifecycle/run-setup.ts around line 153-193, the lock is acquired during setupRun but if setupRun fails, it is outside the runner main try block so the lock is never released. Fix: ensure lock release in a finally block within setupRun, or move lock acquisition inside the runner try/finally.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "Lock file is released when setupRun throws an error",
+        "Lock file is released on all error paths during setup",
+        "Existing tests pass"
+      ]
+    },
+    {
+      "id": "FIX-C4",
+      "title": "Replace uncancellable Bun.sleep timer in executor",
+      "description": "In src/verification/executor.ts around line 97-100, Bun.sleep() is used for the timeout promise but cannot be cancelled. When the process exits quickly, the sleep continues for the full timeoutMs. Fix: replace with a clearable setTimeout-based promise pattern, clearing the timer in the success path.",
+      "complexity": "simple",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "Timeout in executeWithTimeout uses clearable setTimeout not Bun.sleep",
+        "Timer is cleared when process exits before timeout",
+        "No timer leak after successful execution",
+        "Existing tests pass"
+      ]
+    },
+    {
+      "id": "FIX-H5",
+      "title": "Add hard deadline to async signal handlers",
+      "description": "In src/execution/crash-recovery.ts around line 149-170, signal handlers contain multiple await operations. If any hangs, process.exit() is never reached. Fix: add a setTimeout hard deadline (e.g. 10s) at the top of each signal handler that calls process.exit() as a fallback.",
+      "complexity": "simple",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "SIGTERM handler has a hard deadline timeout (10s) that calls process.exit",
+        "SIGINT handler has the same hard deadline",
+        "Hard deadline fires even if async operations hang",
+        "Existing tests pass"
+      ]
+    }
+  ]
+}

package/nax/features/status-file-consolidation/prd.json

@@ -0,0 +1,61 @@
+{
+  "project": "nax",
+  "branchName": "feat/status-file-consolidation",
+  "feature": "status-file-consolidation",
+  "version": "0.22.2",
+  "description": "Auto-write status.json to well-known paths (project-level + feature-level). Remove --status-file CLI flag. Align nax status and nax diagnose readers.",
+  "userStories": [
+    {
+      "id": "SFC-001",
+      "title": "Auto-write project-level status",
+      "description": "Remove --status-file CLI option. StatusWriter always writes to <workdir>/nax/status.json automatically. In bin/nax.ts, remove --status-file option and compute statusFile = join(workdir, 'nax', 'status.json'). In runner.ts, statusFile is no longer optional. In status-writer.ts, remove the if (!this.statusFile) guard in update().",
+      "complexity": "medium",
+      "status": "passed",
+      "acceptanceCriteria": [
+        "Running nax without --status-file flag writes nax/status.json automatically",
+        "nax/status.json contains valid NaxStatusFile schema with run.id, run.status, progress counts",
+        "--status-file CLI option no longer exists",
+        "StatusWriter.update() always writes (no no-op guard on missing statusFile)"
+      ]
+    },
+    {
+      "id": "SFC-002",
+      "title": "Write feature-level status on run end",
+      "description": "On run complete/fail/crash, write the final status snapshot to <workdir>/nax/features/<feature>/status.json. Add writeFeatureStatus(featureDir) method to StatusWriter. Call it in runner.ts finally block and in crash-recovery.ts.",
+      "complexity": "medium",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "After a completed run, nax/features/<feature>/status.json exists with status 'completed'",
+        "After a failed run, nax/features/<feature>/status.json exists with status 'failed'",
+        "After a crash, nax/features/<feature>/status.json exists with status 'crashed'",
+        "Feature status.json uses the same NaxStatusFile schema as project-level"
+      ]
+    },
+    {
+      "id": "SFC-003",
+      "title": "Align status readers",
+      "description": "Make nax status read project-level status from nax/status.json for currently running info. Make nax diagnose read from nax/status.json instead of .nax-status.json. status-features.ts loadStatusFile() already reads <featureDir>/status.json which SFC-002 now writes \u2014 no change needed for feature-level reads.",
+      "complexity": "simple",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "nax status shows current run info from nax/status.json at the top",
+        "nax status shows per-feature historical status from nax/features/<feature>/status.json",
+        "nax diagnose reads from nax/status.json (not .nax-status.json)",
+        "No references to .nax-status.json remain in codebase"
+      ]
+    },
+    {
+      "id": "SFC-004",
+      "title": "Clean up dead code",
+      "description": "Remove --status-file option definition from bin/nax.ts. Remove .nax-status.json path from diagnose.ts. Remove statusFile optional from RunOptions type (now required, auto-computed). Verify no stale references remain.",
+      "complexity": "simple",
+      "status": "pending",
+      "acceptanceCriteria": [
+        "No references to --status-file CLI option in codebase",
+        "No references to .nax-status.json in codebase",
+        "RunOptions.statusFile is required (not optional)",
+        "All existing tests pass"
+      ]
+    }
+  ]
+}