@nathapp/nax 0.28.0 → 0.29.0

package/examples/plugins/console-reporter/index.test.ts

@@ -1,207 +0,0 @@
-/**
- * Console Reporter Plugin Tests
- */
-
-import { describe, test, expect, beforeEach, afterEach } from "bun:test";
-import type {
-  RunStartEvent,
-  StoryCompleteEvent,
-  RunEndEvent,
-} from "../../../src/plugins/types";
-import { validatePlugin } from "../../../src/plugins/validator";
-import consoleReporterPlugin from "./index";
-
-describe("Console Reporter Plugin", () => {
-  let consoleOutput: string[] = [];
-  const originalLog = console.log;
-
-  beforeEach(() => {
-    consoleOutput = [];
-    console.log = (...args: unknown[]) => {
-      consoleOutput.push(args.map(String).join(" "));
-    };
-  });
-
-  afterEach(() => {
-    console.log = originalLog;
-  });
-
-  test("plugin structure passes validation", () => {
-    const validated = validatePlugin(consoleReporterPlugin);
-    expect(validated).not.toBeNull();
-    expect(validated?.name).toBe("console-reporter");
-    expect(validated?.version).toBe("1.0.0");
-    expect(validated?.provides).toEqual(["reporter"]);
-  });
-
-  test("plugin has required fields", () => {
-    expect(consoleReporterPlugin.name).toBe("console-reporter");
-    expect(consoleReporterPlugin.version).toBe("1.0.0");
-    expect(consoleReporterPlugin.provides).toContain("reporter");
-    expect(consoleReporterPlugin.setup).toBeDefined();
-    expect(consoleReporterPlugin.teardown).toBeDefined();
-    expect(consoleReporterPlugin.extensions.reporter).toBeDefined();
-  });
-
-  test("setup() reads config.verbose", async () => {
-    await consoleReporterPlugin.setup?.({ verbose: true });
-    expect(consoleOutput.some(line => line.includes("verbose mode enabled"))).toBe(true);
-
-    consoleOutput = [];
-    await consoleReporterPlugin.setup?.({ verbose: false });
-    expect(consoleOutput.some(line => line.includes("verbose mode enabled"))).toBe(false);
-  });
-
-  test("setup() defaults verbose to false", async () => {
-    await consoleReporterPlugin.setup?.({});
-    expect(consoleOutput.some(line => line.includes("verbose mode enabled"))).toBe(false);
-  });
-
-  test("onRunStart prints banner with run details", async () => {
-    const event: RunStartEvent = {
-      runId: "run-123",
-      feature: "test-feature",
-      totalStories: 5,
-      startTime: "2026-02-27T10:00:00Z",
-    };
-
-    const reporter = consoleReporterPlugin.extensions.reporter;
-    await reporter?.onRunStart?.(event);
-
-    const output = consoleOutput.join("\n");
-    expect(output).toContain("Starting Run: test-feature");
-    expect(output).toContain("Run ID: run-123");
-    expect(output).toContain("Total Stories: 5");
-    expect(output).toContain("Start Time: 2026-02-27T10:00:00Z");
-    expect(output).toContain("=".repeat(60));
-  });
-
-  test("onStoryComplete prints status line with ✓ for completed", async () => {
-    const event: StoryCompleteEvent = {
-      runId: "run-123",
-      storyId: "US-001",
-      status: "completed",
-      durationMs: 1500,
-      cost: 0.0123,
-      tier: "balanced",
-      testStrategy: "three-session-tdd",
-    };
-
-    const reporter = consoleReporterPlugin.extensions.reporter;
-    await reporter?.onStoryComplete?.(event);
-
-    const output = consoleOutput.join("\n");
-    expect(output).toContain("✓");
-    expect(output).toContain("US-001");
-    expect(output).toContain("Tier: balanced");
-    expect(output).toContain("Strategy: three-session-tdd");
-    expect(output).toContain("Duration: 1500ms");
-    expect(output).toContain("Cost: $0.0123");
-  });
-
-  test("onStoryComplete prints status line with ✗ for failed", async () => {
-    const event: StoryCompleteEvent = {
-      runId: "run-123",
-      storyId: "US-002",
-      status: "failed",
-      durationMs: 2500,
-      cost: 0.0456,
-      tier: "powerful",
-      testStrategy: "three-session-tdd-lite",
-    };
-
-    const reporter = consoleReporterPlugin.extensions.reporter;
-    await reporter?.onStoryComplete?.(event);
-
-    const output = consoleOutput.join("\n");
-    expect(output).toContain("✗");
-    expect(output).toContain("US-002");
-    expect(output).toContain("Tier: powerful");
-    expect(output).toContain("Strategy: three-session-tdd-lite");
-  });
-
-  test("onRunEnd prints summary table", async () => {
-    const event: RunEndEvent = {
-      runId: "run-123",
-      totalDurationMs: 5000,
-      totalCost: 0.0789,
-      storySummary: {
-        completed: 3,
-        failed: 1,
-        skipped: 0,
-        paused: 1,
-      },
-    };
-
-    const reporter = consoleReporterPlugin.extensions.reporter;
-    await reporter?.onRunEnd?.(event);
-
-    const output = consoleOutput.join("\n");
-    expect(output).toContain("Run Summary");
-    expect(output).toContain("Run ID: run-123");
-    expect(output).toContain("Completed: 3/5");
-    expect(output).toContain("Failed:    1/5");
-    expect(output).toContain("Skipped:   0/5");
-    expect(output).toContain("Paused:    1/5");
-    expect(output).toContain("Total Duration: 5.00s");
-    expect(output).toContain("Total Cost:     $0.0789");
-  });
-
-  test("verbose mode adds extra output in onStoryComplete", async () => {
-    await consoleReporterPlugin.setup?.({ verbose: true });
-    consoleOutput = [];
-
-    const event: StoryCompleteEvent = {
-      runId: "run-123",
-      storyId: "US-001",
-      status: "completed",
-      durationMs: 1500,
-      cost: 0.0123,
-      tier: "balanced",
-      testStrategy: "three-session-tdd",
-    };
-
-    const reporter = consoleReporterPlugin.extensions.reporter;
-    await reporter?.onStoryComplete?.(event);
-
-    const output = consoleOutput.join("\n");
-    expect(output).toContain("[verbose]");
-    expect(output).toContain("Run ID: run-123");
-    expect(output).toContain("Status: completed");
-  });
-
-  test("verbose mode adds extra output in onRunEnd", async () => {
-    await consoleReporterPlugin.setup?.({ verbose: true });
-    consoleOutput = [];
-
-    const event: RunEndEvent = {
-      runId: "run-123",
-      totalDurationMs: 5000,
-      totalCost: 0.0789,
-      storySummary: {
-        completed: 3,
-        failed: 1,
-        skipped: 0,
-        paused: 1,
-      },
-    };
-
-    const reporter = consoleReporterPlugin.extensions.reporter;
-    await reporter?.onRunEnd?.(event);
-
-    const output = consoleOutput.join("\n");
-    expect(output).toContain("Run completed in verbose mode");
-  });
-
-  test("reporter has required methods", () => {
-    const reporter = consoleReporterPlugin.extensions.reporter;
-    expect(reporter?.name).toBe("console-reporter");
-    expect(typeof reporter?.onRunStart).toBe("function");
-    expect(typeof reporter?.onStoryComplete).toBe("function");
-    expect(typeof reporter?.onRunEnd).toBe("function");
-  });
-
-  test("teardown completes without errors", async () => {
-    await expect(consoleReporterPlugin.teardown?.()).resolves.toBeUndefined();
-  });
-});

package/examples/plugins/console-reporter/index.ts

@@ -1,110 +0,0 @@
-/**
- * Console Reporter Plugin
- *
- * Sample reporter plugin that demonstrates the plugin API.
- * Prints formatted output to the console for run lifecycle events.
- */
-
-import type {
-  NaxPlugin,
-  IReporter,
-  RunStartEvent,
-  StoryCompleteEvent,
-  RunEndEvent,
-} from "../../../src/plugins/types";
-
-interface ConsoleReporterConfig {
-  verbose?: boolean;
-}
-
-let verboseMode = false;
-
-/**
- * Console reporter implementation.
- */
-const reporter: IReporter = {
-  name: "console-reporter",
-
-  async onRunStart(event: RunStartEvent): Promise<void> {
-    console.log("\n" + "=".repeat(60));
-    console.log(`🚀 Starting Run: ${event.feature}`);
-    console.log(`   Run ID: ${event.runId}`);
-    console.log(`   Total Stories: ${event.totalStories}`);
-    console.log(`   Start Time: ${event.startTime}`);
-    console.log("=".repeat(60) + "\n");
-
-    if (verboseMode) {
-      console.log("[console-reporter] Verbose mode enabled");
-    }
-  },
-
-  async onStoryComplete(event: StoryCompleteEvent): Promise<void> {
-    const statusIcon = event.status === "completed" ? "✓" : "✗";
-    const statusColor = event.status === "completed" ? "\x1b[32m" : "\x1b[31m";
-    const resetColor = "\x1b[0m";
-
-    console.log(
-      `${statusColor}${statusIcon}${resetColor} ${event.storyId} | ` +
-      `Tier: ${event.tier} | ` +
-      `Strategy: ${event.testStrategy} | ` +
-      `Duration: ${event.durationMs}ms | ` +
-      `Cost: $${event.cost.toFixed(4)}`
-    );
-
-    if (verboseMode) {
-      console.log(`   [verbose] Run ID: ${event.runId}, Status: ${event.status}`);
-    }
-  },
-
-  async onRunEnd(event: RunEndEvent): Promise<void> {
-    console.log("\n" + "=".repeat(60));
-    console.log("📊 Run Summary");
-    console.log("=".repeat(60));
-
-    const { storySummary } = event;
-    const total = storySummary.completed + storySummary.failed + storySummary.skipped + storySummary.paused;
-
-    console.log(`Run ID: ${event.runId}`);
-    console.log(`\nStory Results:`);
-    console.log(`  ✓ Completed: ${storySummary.completed}/${total}`);
-    console.log(`  ✗ Failed:    ${storySummary.failed}/${total}`);
-    console.log(`  ⊘ Skipped:   ${storySummary.skipped}/${total}`);
-    console.log(`  ⏸ Paused:    ${storySummary.paused}/${total}`);
-    console.log(`\nMetrics:`);
-    console.log(`  Total Duration: ${(event.totalDurationMs / 1000).toFixed(2)}s`);
-    console.log(`  Total Cost:     $${event.totalCost.toFixed(4)}`);
-    console.log("=".repeat(60) + "\n");
-
-    if (verboseMode) {
-      console.log("[console-reporter] Run completed in verbose mode");
-    }
-  },
-};
-
-/**
- * Console reporter plugin export.
- */
-const consoleReporterPlugin: NaxPlugin = {
-  name: "console-reporter",
-  version: "1.0.0",
-  provides: ["reporter"],
-
-  async setup(config: Record<string, unknown>): Promise<void> {
-    const reporterConfig = config as ConsoleReporterConfig;
-    verboseMode = reporterConfig.verbose ?? false;
-
-    if (verboseMode) {
-      console.log("[console-reporter] Plugin initialized with verbose mode enabled");
-    }
-  },
-
-  async teardown(): Promise<void> {
-    // No cleanup needed for console output
-  },
-
-  extensions: {
-    reporter,
-  },
-};
-
-export default consoleReporterPlugin;

package/memory/topic/feat-010-baseref.md

@@ -1,28 +0,0 @@
-# FEAT-010 — baseRef Tracking Design Decision
-
-## Decision
-Capture `baseRef = current HEAD` **in-memory at each attempt start** (not stored in PRD).
-Use `git diff <baseRef>..HEAD` in smart-runner instead of `HEAD~1`.
-
-## Why per-attempt, not per-story
-- Story may retry after other stories have committed
-- Storing in PRD: retry would use stale baseRef from first attempt → includes other stories' files ❌
-- Capturing fresh per attempt: retry anchors to HEAD at that moment → only sees its own commits ✅
-
-## Why no cross-story pollution
-- Story 1 retry baseRef = HEAD after stories 2+3 committed
-- diff <baseRef>..HEAD = only story 1 retry's own commits
-- Other stories' commits are BEFORE baseRef → excluded automatically
-
-## Flow
-```
-attempt start → captureGitRef() → baseRef (in-memory)
-agent runs → makes N commits
-verify → getChangedSourceFiles(workdir, baseRef)
-         → git diff <baseRef>..HEAD
-         → only this attempt's changed files ✅
-```
-
-## Edge Cases
-- Agent makes 0 commits → diff = empty → fallback to full suite (existing behavior)
-- Partial commits on failure → next attempt captures new baseRef → clean isolation

package/memory/topic/feat-013-test-after-deprecation.md

@@ -1,22 +0,0 @@
-# FEAT-013 — Deprecate test-after from auto routing
-
-## Decision
-Remove `test-after` as the default fallback in `auto` mode.
-Change simple/medium stories to route to `three-session-tdd-lite` instead.
-
-## Why
-- `test-after` has high test failure rate — tests rubber-stamp implementation rather than driving design
-- Failed test-after stories escalate to powerful tier anyway → costs more in the end
-- `three-session-tdd-lite` = better quality at moderate cost increase
-
-## New auto routing decision tree
-```
-security/public-api keywords  → three-session-tdd
-complex/expert complexity     → three-session-tdd (or lite if ui/cli tags)
-simple/medium (default)       → three-session-tdd-lite  ← was test-after
-```
-
-## Backward compatibility
-- `tddStrategy: "off"` in config still routes to `test-after` (explicit opt-in)
-- `tddStrategy: "strict"` → three-session-tdd (unchanged)
-- `tddStrategy: "lite"` → three-session-tdd-lite (unchanged)

package/nax/config.json

@@ -1,154 +0,0 @@
-{
-  "version": 1,
-  "models": {
-    "fast": {
-      "provider": "anthropic",
-      "model": "haiku"
-    },
-    "balanced": {
-      "provider": "anthropic",
-      "model": "sonnet"
-    },
-    "powerful": {
-      "provider": "anthropic",
-      "model": "sonnet"
-    }
-  },
-  "autoMode": {
-    "enabled": true,
-    "defaultAgent": "claude",
-    "fallbackOrder": [
-      "claude"
-    ],
-    "complexityRouting": {
-      "simple": "fast",
-      "medium": "balanced",
-      "complex": "balanced",
-      "expert": "powerful"
-    },
-    "escalation": {
-      "enabled": true,
-      "tierOrder": [
-        {
-          "tier": "fast",
-          "attempts": 3
-        },
-        {
-          "tier": "balanced",
-          "attempts": 2
-        },
-        {
-          "tier": "powerful",
-          "attempts": 1
-        }
-      ],
-      "escalateEntireBatch": false
-    }
-  },
-  "routing": {
-    "strategy": "llm",
-    "llm": {
-      "model": "fast",
-      "fallbackToKeywords": true,
-      "cacheDecisions": true,
-      "mode": "hybrid",
-      "timeoutMs": 60000
-    }
-  },
-  "execution": {
-    "maxIterations": 6,
-    "iterationDelayMs": 2000,
-    "costLimit": 8.0,
-    "sessionTimeoutSeconds": 7200,
-    "verificationTimeoutSeconds": 600,
-    "maxStoriesPerFeature": 15,
-    "rectification": {
-      "enabled": true,
-      "maxRetries": 2,
-      "fullSuiteTimeoutSeconds": 600,
-      "maxFailureSummaryChars": 2000,
-      "abortOnIncreasingFailures": true
-    },
-    "regressionGate": {
-      "enabled": true,
-      "mode": "deferred",
-      "timeoutSeconds": 600,
-      "acceptOnTimeout": true,
-      "maxRectificationAttempts": 2
-    }
-  },
-  "quality": {
-    "requireTypecheck": true,
-    "requireLint": true,
-    "requireTests": true,
-    "commands": {
-      "test": "bun run test",
-      "typecheck": "bun run typecheck",
-      "lint": "bun run lint",
-      "testScoped": "bun test --timeout=60000 {{files}}"
-    },
-    "forceExit": false,
-    "detectOpenHandles": true,
-    "detectOpenHandlesRetries": 1,
-    "gracePeriodMs": 5000,
-    "drainTimeoutMs": 2000,
-    "shell": "/bin/sh",
-    "stripEnvVars": [
-      "CLAUDECODE",
-      "REPL_ID",
-      "AGENT"
-    ],
-    "environmentalEscalationDivisor": 2
-  },
-  "tdd": {
-    "maxRetries": 2,
-    "autoVerifyIsolation": true,
-    "autoApproveVerifier": true,
-    "strategy": "lite",
-    "sessionTiers": {
-      "testWriter": "balanced",
-      "verifier": "fast"
-    }
-  },
-  "constitution": {
-    "enabled": true,
-    "path": "constitution.md",
-    "maxTokens": 2000
-  },
-  "analyze": {
-    "llmEnhanced": false,
-    "model": "balanced",
-    "fallbackToKeywords": true,
-    "maxCodebaseSummaryTokens": 5000
-  },
-  "review": {
-    "enabled": true,
-    "checks": [
-      "typecheck",
-      "lint"
-    ],
-    "commands": {
-      "typecheck": "bun run typecheck",
-      "lint": "bun run lint"
-    }
-  },
-  "plan": {
-    "model": "balanced",
-    "outputPath": "spec.md"
-  },
-  "acceptance": {
-    "enabled": false,
-    "maxRetries": 2,
-    "generateTests": false,
-    "testPath": "acceptance.test.ts"
-  },
-  "context": {
-    "testCoverage": {
-      "enabled": true,
-      "detail": "names-and-counts",
-      "maxTokens": 500,
-      "testPattern": "**/*.test.{ts,js}",
-      "scopeToStory": true
-    }
-  }
-}

package/nax/features/bug-039-medium/prd.json

@@ -1,45 +0,0 @@
-{
-  "project": "nax",
-  "feature": "bug-039-medium",
-  "branchName": "fix/bug-039-process-cleanup-medium",
-  "createdAt": "2026-03-06T04:51:00.000Z",
-  "updatedAt": "2026-03-06T04:51:00.000Z",
-  "userStories": [
-    {
-      "id": "US-001",
-      "title": "runOnce() SIGKILL follow-up after grace period",
-      "description": "In src/agents/claude.ts:runOnce(), the timeout handler only sends SIGTERM but never follows up with SIGKILL. Claude may ignore SIGTERM and run indefinitely. Add a SIGKILL after a 5-second grace period, mirroring the pattern in src/verification/executor.ts:executeWithTimeout(). Also move pidRegistry.unregister(processPid) into a finally block so it is always called even if the timeout path throws an exception.",
-      "acceptanceCriteria": [
-        "When runOnce() times out, SIGTERM is sent first",
-        "After 5 seconds grace period, SIGKILL is sent to ensure the process is dead",
-        "pidRegistry.unregister(processPid) is called in a finally block — always runs regardless of success or exception path",
-        "Existing runOnce() tests still pass",
-        "New test: timeout path always unregisters PID even if SIGTERM/SIGKILL throws"
-      ],
-      "tags": ["bug", "process", "cleanup"],
-      "dependencies": [],
-      "status": "pending",
-      "passes": false,
-      "escalations": [],
-      "attempts": 0
-    },
-    {
-      "id": "US-002",
-      "title": "LLM routing stream drain fix on timeout",
-      "description": "In src/routing/strategies/llm.ts:callLlmOnce(), when the timeout fires, proc.kill() is called but the stdout/stderr ReadableStreams from the Bun.spawn() are never cancelled or drained. This can cause proc.exited to hang indefinitely because Bun's piped streams may block exit. Fix: before calling proc.kill(), cancel both streams with proc.stdout.cancel() and proc.stderr.cancel() wrapped in try/catch. This ensures proc.exited resolves promptly after kill.",
-      "acceptanceCriteria": [
-        "On LLM timeout, proc.stdout and proc.stderr are cancelled before proc.kill()",
-        "proc.exited resolves promptly after timeout kill (does not hang)",
-        "clearTimeout(timeoutId) still called in both success and error paths",
-        "Existing LLM routing tests still pass",
-        "New test: timeout path resolves without hanging (use fake timers or short timeout)"
-      ],
-      "tags": ["bug", "process", "cleanup", "llm"],
-      "dependencies": [],
-      "status": "pending",
-      "passes": false,
-      "escalations": [],
-      "attempts": 0
-    }
-  ]
-}

package/nax/features/bugfix-v0171/prd.json

@@ -1,52 +0,0 @@
-{
-  "project": "nax",
-  "branchName": "feat/v0.17.x-bugfixes",
-  "feature": "bugfix-v0171",
-  "userStories": [
-    {
-      "id": "BF-001",
-      "title": "Emit run.complete on SIGTERM shutdown (BUG-017)",
-      "description": "When nax receives SIGTERM, the crash-recovery handler shuts down cleanly but never emits the final run.complete JSONL event. This means the run log has no aggregate cost/duration summary when nax is killed externally.\n\nFind where SIGTERM is caught in src/execution/ and ensure a run.complete event is emitted before exit with: totalCost (sum of agent.complete costs), totalIterations, exitReason='sigterm', duration.\n\nAcceptance criteria:\n1. When nax is killed with SIGTERM mid-run, JSONL ends with run.complete event containing totalCost, totalIterations, exitReason='sigterm', duration\n2. Existing tests pass\n3. Add a unit test simulating SIGTERM that verifies run.complete is written",
-      "complexity": "simple",
-      "status": "pending",
-      "attempts": 0,
-      "priorErrors": [
-        "Attempt 1 failed with model tier: fast"
-      ],
-      "escalations": [],
-      "dependencies": [],
-      "tags": [],
-      "acceptanceCriteria": [],
-      "storyPoints": 1,
-      "routing": {
-        "complexity": "simple",
-        "modelTier": "balanced",
-        "testStrategy": "three-session-tdd-lite",
-        "reasoning": "three-session-tdd-lite: public-api, strategy:lite"
-      }
-    },
-    {
-      "id": "BF-002",
-      "title": "Add storyId to all JSONL events (BUG-020)",
-      "description": "Many JSONL events have empty or missing storyId. Audit and fix these event emitters to include storyId when a story is active:\n- src/pipeline/stages/verify.ts (verify info/debug events)\n- src/pipeline/stages/execution.ts (execution events)\n- src/tdd/orchestrator.ts (tdd session events)\n- src/execution/pipeline-result-handler.ts (escalation events)\n\nAcceptance criteria:\n1. Events at stages agent.start, agent.complete, verify, tdd, execution, escalation include storyId in data when a story is active\n2. Existing tests pass\n3. Add tests verifying storyId presence on key events",
-      "complexity": "simple",
-      "status": "pending",
-      "attempts": 0,
-      "priorErrors": [
-        "Attempt 1 failed with model tier: fast"
-      ],
-      "escalations": [],
-      "dependencies": [],
-      "tags": [],
-      "acceptanceCriteria": [],
-      "storyPoints": 1,
-      "routing": {
-        "complexity": "simple",
-        "modelTier": "balanced",
-        "testStrategy": "three-session-tdd-lite",
-        "reasoning": "three-session-tdd-lite: strategy:lite"
-      }
-    }
-  ],
-  "updatedAt": "2026-03-02T08:59:51.238Z"
-}