@nathapp/nax 0.18.1

package/docs/20260217-quick-wins-plan.md

@@ -0,0 +1,66 @@
+# Fix Plan: Quick Wins Batch (PERF-1, TYPE-2, ENH-4, ENH-5)
+**Date:** 2026-02-17
+**Branch:** master (local commits only)
+
+## Phase 1: PERF-1 — Optimize Batch Story Selection
+
+**File:** `src/execution/batching.ts`, `src/execution/helpers.ts`
+**Problem:** `groupStoriesIntoBatches()` is called with already-filtered ready stories, but inside the main run loop, batch candidate re-checking is O(n²).
+**Fix:**
+1. In `src/execution/helpers.ts`, add `getReadyStoriesPreGrouped(prd: PRD): { simple: UserStory[], nonSimple: UserStory[] }` that partitions ready stories once.
+2. In `src/execution/batching.ts`, the current `groupStoriesIntoBatches()` is already O(n) — it iterates once. The real PERF-1 issue is in runner.ts where batch candidates are re-checked every iteration. Add a `precomputeBatchPlan(stories: UserStory[], maxBatchSize?: number): StoryBatch[]` that computes the full batch plan once upfront, so the runner just pops the next batch.
+3. In runner.ts, call `precomputeBatchPlan()` once after PRD load (and after prdDirty reload), iterate through batches instead of re-grouping each iteration.
+
+**Run:** `bun test`
+**Commit:** `perf(batching): precompute batch plan to eliminate O(n²) re-checking`
+
+## Phase 2: TYPE-2 — QueueCommand Discriminated Union
+
+**Files:** `src/queue/types.ts`, `src/queue/manager.ts`, `src/execution/runner.ts`, `src/execution/queue-handler.ts`
+**Problem:** `QueueCommand` is `"PAUSE" | "ABORT" | { type: "SKIP"; storyId: string }` — mixed string/object, requires `typeof cmd === "object"` checks.
+**Fix:**
+1. Change `QueueCommand` to discriminated union:
+   ```ts
+   export type QueueCommand =
+     | { type: "PAUSE" }
+     | { type: "ABORT" }
+     | { type: "SKIP"; storyId: string };
+   ```
+2. Update `parseQueueFile()` in `src/queue/manager.ts`: push `{ type: "PAUSE" }` instead of `"PAUSE"`.
+3. Update all consumers in `src/execution/runner.ts` and `src/execution/queue-handler.ts`: change `cmd === "PAUSE"` to `cmd.type === "PAUSE"`, remove `typeof cmd === "object"` checks.
+4. Update tests in `test/queue.test.ts` and `test/runner.test.ts`.
+
+**Run:** `bun test`
+**Commit:** `refactor(queue): convert QueueCommand to discriminated union`
+
+## Phase 3: ENH-4 — Progress Display + ENH-5 — TDD Dry-Run
+
+**Files:** `src/execution/runner.ts`, `src/tdd/orchestrator.ts`
+**ENH-4 — Progress display:**
+1. In runner.ts, after each story/batch completes, print a progress summary:
+   ```
+   📊 Progress: 5/12 stories | ✅ 4 passed | ❌ 1 failed | 💰 $0.45/$5.00 | ⏱️ ~8 min remaining
+   ```
+2. Add helper `formatProgress(counts, totalCost, costLimit, elapsed, totalStories): string` in `src/execution/helpers.ts`.
+3. Calculate ETA from average story duration × remaining stories.
+
+**ENH-5 — TDD dry-run:**
+1. Add `dryRun?: boolean` to TDD orchestrator options.
+2. When `dryRun === true`, log what would happen without spawning agents:
+   ```
+   [DRY RUN] Would run 3-session TDD for US-005
+     Session 1: test-writer (model: haiku)
+     Session 2: implementer (model: haiku)  
+     Session 3: verifier (model: haiku)
+   ```
+3. Return success with zero cost.
+4. Wire `--dry-run` flag from CLI through to runner and TDD orchestrator.
+
+**Run:** `bun test`
+**Commit:** `feat: add progress display and TDD dry-run mode`
+
+## Test Strategy
+- Mode: test-after
+- Phase 1: update batching tests for precomputeBatchPlan
+- Phase 2: update queue + runner tests for new discriminated union
+- Phase 3: add test for formatProgress helper and dry-run path

package/docs/20260217-split-runner-plan.md

@@ -0,0 +1,75 @@
+# Fix Plan: STYLE-1 — Split runner.ts (901 LOC) into Focused Modules
+**Date:** 2026-02-17
+**Branch:** master (local commits only)
+
+## Overview
+
+Split `src/execution/runner.ts` (901 LOC) into 5 focused modules under `src/execution/`. Preserve all exports via barrel `index.ts`. No logic changes — pure file reorganization.
+
+## Target Structure
+
+```
+src/execution/
+  runner.ts       → Main run() loop only (~300 LOC)
+  prompts.ts      → buildSingleSessionPrompt(), buildBatchPrompt() (~80 LOC)
+  batching.ts     → groupStoriesIntoBatches(), StoryBatch type (~70 LOC)
+  escalation.ts   → escalateTier() (~30 LOC)
+  queue-handler.ts → readQueueFile(), clearQueueFile() (~60 LOC)
+  helpers.ts      → hookCtx(), maybeGetContext(), buildStoryContext(), getAllReadyStories(), acquireLock(), releaseLock(), ExecutionResult type (~200 LOC)
+  progress.ts     → (already exists, unchanged)
+  index.ts        → Updated barrel exports
+```
+
+## Phase 1: Extract prompts.ts and batching.ts
+
+**Extract from runner.ts:**
+1. `buildSingleSessionPrompt()` (lines ~62-90) → `src/execution/prompts.ts`
+2. `buildBatchPrompt()` (lines ~92-130) → `src/execution/prompts.ts`
+3. `StoryBatch` interface (line ~132) → `src/execution/batching.ts`
+4. `groupStoriesIntoBatches()` (lines ~141-187) → `src/execution/batching.ts`
+
+**Update imports in runner.ts** to import from new files.
+**Update `src/execution/index.ts`** to re-export from new files.
+
+**Run:** `bun test`
+**Commit:** `refactor(execution): extract prompts and batching modules from runner`
+
+## Phase 2: Extract escalation.ts, queue-handler.ts, and helpers.ts
+
+**Extract from runner.ts:**
+1. `escalateTier()` (lines ~220-242) → `src/execution/escalation.ts`
+2. `readQueueFile()` (lines ~283-317) → `src/execution/queue-handler.ts`
+3. `clearQueueFile()` (lines ~319-330) → `src/execution/queue-handler.ts`
+4. `hookCtx()` (lines ~244-254) → `src/execution/helpers.ts`
+5. `maybeGetContext()` (lines ~256-281) → `src/execution/helpers.ts`
+6. `buildStoryContext()` (lines ~189-218) → `src/execution/helpers.ts`
+7. `getAllReadyStories()` (lines ~340-358) → `src/execution/helpers.ts`
+8. `acquireLock()` / `releaseLock()` (lines ~360-410) → `src/execution/helpers.ts`
+9. `ExecutionResult` interface (line ~333) → `src/execution/helpers.ts`
+
+**Update imports in runner.ts** to import from new files.
+**Update `src/execution/index.ts`** to re-export `escalateTier` and `StoryBatch`.
+
+**Critical:** Tests import directly from `../src/execution/runner`:
+- `test/routing.test.ts` imports `escalateTier` from runner
+- `test/runner.test.ts` imports `buildBatchPrompt`, `groupStoriesIntoBatches`, `escalateTier`, `StoryBatch` from runner
+- `test/runner-fixes.test.ts` imports `groupStoriesIntoBatches` from runner
+
+These must be updated to import from the new module paths OR we re-export from runner.ts for backward compat (prefer re-export for minimal test changes).
+
+**Strategy:** Re-export moved functions from runner.ts so existing test imports don't break:
+```ts
+// runner.ts — re-exports for backward compatibility
+export { buildBatchPrompt } from './prompts';
+export { groupStoriesIntoBatches, type StoryBatch } from './batching';
+export { escalateTier } from './escalation';
+```
+
+**Run:** `bun test`
+**Commit:** `refactor(execution): extract escalation, queue-handler, and helpers from runner`
+
+## Test Strategy
+- Mode: test-after
+- No new tests — all 231 existing tests must pass unchanged
+- Re-export pattern ensures test imports remain valid
+- Verify with `bun test && bun run typecheck`

package/docs/20260217-v03-impl-plan.md

@@ -0,0 +1,80 @@
+# v0.3 Implementation Plan
+**Date:** 2026-02-17
+**Branch:** master
+
+## Phase 1: Constitution System (smallest, unblocks Phase 2-3)
+### 1a: Constitution loader
+**File:** `src/constitution/index.ts` (NEW)
+- Load `constitution.md` from project dir
+- Token counting/truncation with warning
+- Config integration (`constitution.enabled`, `constitution.path`, `constitution.maxTokens`)
+
+### 1b: Inject into agent prompts
+**File:** `src/execution/prompts.ts`
+- Add constitution content at priority 95 in prompt assembly
+- Truncation warning if exceeds maxTokens
+
+### 1c: `ngent init` generates starter constitution
+**File:** `src/cli/init.ts`
+- Add constitution.md template generation
+
+### Tests
+- Constitution loading, truncation, missing file handling
+- Prompt injection with/without constitution
+- Init creates constitution.md
+
+**Commit:** `feat(constitution): add constitution system with prompt injection`
+
+## Phase 2: LLM-Enhanced Analyze
+### 2a: Codebase scanner
+**File:** `src/analyze/scanner.ts` (NEW)
+- File tree generation (src/, max depth 3)
+- Package.json dependency extraction
+- Existing test pattern detection
+
+### 2b: LLM classifier
+**File:** `src/analyze/classifier.ts` (NEW)
+- Single LLM call with structured JSON output
+- Parse and validate response
+- Graceful fallback to keyword matching on failure
+
+### 2c: Integration with analyze command
+**File:** `src/cli/analyze.ts` or existing analyze path
+- Config: `analyze.llmEnhanced`, `analyze.classifierModel`, `analyze.fallbackToKeywords`
+- Merge LLM output into prd.json (relevantFiles, reasoning, risks)
+
+### Tests
+- Scanner output format
+- Classifier prompt construction and response parsing
+- Fallback behavior on LLM failure
+- Integration with existing analyze flow
+
+**Commit:** `feat(analyze): add LLM-enhanced story classification`
+
+## Phase 3: Review Phase
+### 3a: Review runner
+**File:** `src/review/index.ts` (NEW)
+- Run configurable checks (typecheck, lint, test)
+- Custom commands per check
+- Collect pass/fail results
+
+### 3b: Integration with execution
+**File:** `src/execution/runner.ts`
+- After story passes → run review phase
+- Mark story as failed with review reason if any check fails
+- Log results to progress.txt
+
+### Tests
+- Review runner with passing/failing checks
+- Config-driven check selection
+- Integration with story completion flow
+
+**Commit:** `feat(review): add post-implementation review phase`
+
+## Test Strategy
+- Mode: test-after
+- All new modules get unit tests
+- Run `bun test && bun run typecheck` after each phase
+
+## Version
+- Bump to 0.3.0 after all phases complete