@nathapp/nax 0.28.0 → 0.29.0

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

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

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

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