@nathapp/nax 0.28.0 → 0.30.0

package/docs/specs/feat-014-heartbeat-observability.md

@@ -1,127 +0,0 @@
-# FEAT-014 — Structured Log & Heartbeat
-
-**Status:** Proposal
-**Target:** v0.21.0
-**Author:** Nax Dev
-**Date:** 2026-03-06
-
----
-
-## 1. Problem
-
-nax runs take 30–120 minutes for multi-story features with no "where are we?" view:
-- `nax status` shows last known state (stale, no stage detail)
-- `nax logs --follow` is raw JSONL event stream (too noisy)
-
-Users have no visibility into current story, current stage, elapsed time, cost, or pass/fail counts during a run.
-
----
-
-## 2. Heartbeat Data Model
-
-```typescript
-// src/events/types.ts
-interface RunHeartbeat {
-  type: "run.heartbeat";
-  timestamp: string;
-  runId: string;
-  elapsedSeconds: number;
-  currentStory: {
-    id: string;
-    title: string;
-    status: string;
-    currentStage: string;       // "routing" | "execution" | "verify" | "review" | "completion"
-    stageElapsedSeconds: number;
-    attempts: number;
-    modelTier: string;
-  } | null;                     // null between stories (e.g. deferred regression)
-  storyCounts: {
-    total: number;
-    passed: number;
-    failed: number;
-    pending: number;
-    running: number;
-  };
-  estimatedCostUsd: number;
-  lastActivityAt: string;
-}
-```
-
----
-
-## 3. Implementation Plan
-
-**Heartbeat emitter** (`runner.ts`):
-```typescript
-const intervalSec = config.logging?.heartbeatIntervalSeconds ?? 30;
-if (intervalSec > 0) {
-  const id = setInterval(async () => {
-    const hb = buildHeartbeat(runState);
-    emitEvent("run.heartbeat", hb);
-    await statusWriter.writeHeartbeat(hb);
-  }, intervalSec * 1000);
-  runCleanup(() => clearInterval(id));
-}
-```
-
-**Stage transition events** — each pipeline stage emits:
-```typescript
-emitEvent("stage.enter", { storyId, stage: "verify", timestamp });
-// ... logic ...
-emitEvent("stage.exit", { storyId, stage: "verify", result: action, durationMs });
-```
-
----
-
-## 4. CLI Changes
-
-**`nax status`** (extended output):
-```
-┌─ Run Status ──────────────────────────────────────────────────┐
-│ Feature: verify-v2    Elapsed: 12m 34s    Cost: $0.42         │
-│ Stories: ✅ 2 passed  ❌ 0 failed  ⏳ 3 pending               │
-├─ Current Story ───────────────────────────────────────────────┤
-│ US-003: Smart test runner baseline tracking                    │
-│ Stage: execution (fast tier, attempt 1)  — 2m 18s in stage    │
-└───────────────────────────────────────────────────────────────┘
-```
-
-**`nax logs --follow --heartbeat`** — filter to heartbeat-only lines (progress bar style, replaces previous line).
-
----
-
-## 5. Files Affected
-
-| File | Change |
-|---|---|
-| `src/execution/runner.ts` | Add heartbeat `setInterval`, clear on cleanup |
-| `src/events/types.ts` | Add `RunHeartbeat` interface |
-| `src/execution/status-writer.ts` | Add `writeHeartbeat()` method |
-| `src/pipeline/stages/*.ts` | Emit `stage.enter` / `stage.exit` |
-| `src/cli/status.ts` | Render heartbeat table from `status.json` |
-| `src/cli/logs.ts` | Add `--heartbeat` filter flag |
-| `src/config/schemas.ts` | Add `logging.heartbeatIntervalSeconds` |
-| `src/config/types.ts` | Add `LoggingConfig` interface |
-
----
-
-## 6. Config Changes
-
-```jsonc
-{
-  "logging": {
-    "heartbeatIntervalSeconds": 30   // 0 = disabled
-  }
-}
-```
-
----
-
-## 7. Test Plan
-
-- Heartbeat emitted every N seconds (mock `setInterval`)
-- Heartbeat written to `status.json`
-- `stage.enter` / `stage.exit` emitted by each pipeline stage
-- `heartbeatIntervalSeconds: 0` → no interval, no events
-- Interval cleared on run completion (no leak)
-- `nax status` renders table when `status.json` has `heartbeat` field

package/docs/specs/status-file-consolidation.md

@@ -1,93 +0,0 @@
-# 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