@nathapp/nax 0.28.0 → 0.29.0

package/docs/20260217-dogfood-findings.md

@@ -1,56 +0,0 @@
-# Dogfood Findings: E2E Test with bun-kv-store
-**Date:** 2026-02-17
-**Test Project:** `projects/ngent/test-project/` (bun-kv-store)
-**Result:** ✅ 8/8 stories, 56 tests, $0.76, 11.8 min
-
-## Bugs Found
-
-### BUG-9: Stale lock not cleaned on OOM/SIGKILL
-**Severity:** P1 | **Category:** Reliability
-**File:** `src/execution/helpers.ts` (acquireLock/releaseLock)
-
-When ngent is OOM killed (signal 9), the lock file remains and blocks subsequent runs.
-User must manually `rm ngent.lock`.
-
-**Fix:** Use PID-based lock file. On acquire, check if the PID in the lock is still alive.
-If stale (process dead), remove and re-acquire.
-
-### BUG-10: Story count ignores pre-existing "passed" status
-**Severity:** P2 | **Category:** Bug
-**File:** `src/execution/runner.ts`
-
-When resuming a run with manually edited prd.json (US-001 set to "passed"),
-the progress display shows "0 done, 7 pending" — off by one.
-The runner also re-executes the passed story instead of skipping it.
-
-**Fix:** `countStories()` and `getNextStory()` should respect existing "passed" status
-from prd.json when starting a run.
-
-### BUG-11: Routing cached from analyze, ignores config model changes
-**Severity:** P2 | **Category:** Enhancement  
-**File:** `src/execution/runner.ts` + `src/prd/index.ts`
-
-During `ngent analyze`, each story gets a `routing` object with `modelTier` baked in.
-When user later changes `config.json` model mappings (e.g., simple→fast instead of balanced),
-the cached routing in prd.json takes precedence.
-
-**Fix:** Routing should be re-evaluated at run time using current config,
-not cached from analyze. Store only `complexity` in prd.json, derive `modelTier` at runtime.
-
-### BUG-12: OOM when verify stage runs concurrent with Claude Code
-**Severity:** P1 | **Category:** Performance
-**File:** `src/pipeline/stages/verify.ts`
-
-On low-RAM VPS (~2GB), the verify stage spawns `bun test` while Claude Code's
-TypeScript language servers are still in memory. Combined memory exceeds available RAM → SIGKILL.
-
-**Fix:** Add delay after agent process exits before running verify (let Claude Code's
-child processes fully terminate). Or: skip verify if agent already ran tests
-(detect from agent output).
-
-## Non-Bugs (Working as Designed)
-- Constitution injection: ✅ worked perfectly, 614 tokens
-- Story batching: ✅ grouped simple stories correctly  
-- Cost tracking: ✅ accurate at $0.76
-- Progress display: ✅ updated correctly during run
-- Commit per story: ✅ clean conventional commits

package/docs/20260217-p2-plus-plan.md

@@ -1,117 +0,0 @@
-# Fix Plan: All Remaining P2+ Items
-**Date:** 2026-02-17
-**Branch:** master (local commits only)
-
-## Phase 1: TYPE-1 — Zod Config Validation
-
-**Files:** `src/config/loader.ts`, `src/config/schema.ts`, `src/config/validate.ts`, `package.json`
-**Problem:** Config loader uses `as unknown as` double-casting (2 instances). No runtime type safety.
-
-**Changes:**
-1. Add `zod` dependency: `bun add zod`
-2. In `src/config/schema.ts`, add a Zod schema (`NgentConfigSchema`) that mirrors the `NgentConfig` type. Use `z.infer<typeof NgentConfigSchema>` to derive the type (or keep manual type + validate against schema).
-3. In `src/config/loader.ts`, replace the `deepMerge` + `as unknown as` pattern:
-   - Merge raw objects (keep deepMerge for raw `Record<string, unknown>`)
-   - Parse merged result through `NgentConfigSchema.safeParse()`
-   - On failure, throw with Zod's formatted error messages
-   - Remove the separate `validateConfig()` call (Zod handles it)
-4. Remove or simplify `src/config/validate.ts` — Zod replaces manual validation.
-5. Update tests in `test/config.test.ts` to test Zod validation errors.
-
-**Run:** `bun test && bun run typecheck`
-**Commit:** `refactor(config): replace manual validation with Zod schema parsing`
-
-## Phase 2: BUG-4 — Batch-Wide Escalation Option
-
-**Files:** `src/config/schema.ts`, `src/execution/runner.ts`
-**Problem:** When a batch fails, only the first story escalates. Remaining retry at same tier — wasteful.
-
-**Changes:**
-1. In `src/config/schema.ts`, add to escalation config:
-   ```ts
-   escalateEntireBatch?: boolean; // default: true
-   ```
-   Add to DEFAULT_CONFIG and Zod schema.
-2. In `src/execution/runner.ts`, in the batch failure handler:
-   - If `config.autoMode.escalation.escalateEntireBatch` is true (default), escalate ALL stories in the failed batch to the next tier, not just the first.
-   - If false, keep current behavior (only first story escalates).
-3. Add tests for both modes.
-
-**Run:** `bun test && bun run typecheck`
-**Commit:** `fix(execution): add batch-wide escalation option (default: true)`
-
-## Phase 3: ENH-2 — Agent Capability Metadata
-
-**Files:** `src/agents/types.ts`, `src/agents/claude.ts`
-**Problem:** Agent adapters don't declare what they support — can't validate config or optimize routing.
-
-**Changes:**
-1. In `src/agents/types.ts`, add to `AgentAdapter`:
-   ```ts
-   readonly capabilities: {
-     supportedTiers: ModelTier[];
-     maxContextTokens: number;
-     features: Set<'tdd' | 'review' | 'refactor' | 'batch'>;
-   };
-   ```
-2. In `src/agents/claude.ts`, implement for ClaudeCodeAdapter:
-   ```ts
-   readonly capabilities = {
-     supportedTiers: ["fast", "balanced", "powerful"] as ModelTier[],
-     maxContextTokens: 200_000,
-     features: new Set(['tdd', 'review', 'refactor', 'batch'] as const),
-   };
-   ```
-3. Add a `validateAgentForTier(agent: AgentAdapter, tier: ModelTier): boolean` helper.
-4. In runner.ts, add a validation check before execution: warn if configured tier isn't in agent's supportedTiers.
-5. Add tests for capability validation.
-
-**Run:** `bun test && bun run typecheck`
-**Commit:** `feat(agents): add capability metadata and tier validation`
-
-## Phase 4: ENH-3 — Context Builder File Content Loading
-
-**Files:** `src/context/builder.ts`, `src/context/types.ts`
-**Problem:** Context only includes story metadata — no source code context for agents.
-
-**Changes:**
-1. In `src/context/types.ts`, add `relevantFiles?: string[]` to the story context input (if not already present in UserStory).
-2. In `src/context/builder.ts`, add `createFileContext(filePath: string, content: string, priority: number): ContextElement`.
-3. In `buildContext()`, after story elements, load files from `currentStory.relevantFiles`:
-   - Resolve paths relative to workdir
-   - Read file content (with size limit: max 10KB per file, max 5 files)
-   - Create context elements with priority 60
-   - Respect token budget (files are lower priority than story/deps)
-4. Add tests with temp files.
-
-**Run:** `bun test && bun run typecheck`
-**Commit:** `feat(context): load relevant source files into agent context`
-
-## Phase 5: STYLE-2 + STYLE-3 — Error Handling Consistency + Named Constants
-
-**Files:** Multiple (all modules)
-**STYLE-2 — Establish error handling pattern:**
-1. Document pattern in a comment block at top of `src/execution/helpers.ts`:
-   - Critical errors (invalid config, missing files): throw Error
-   - Expected conditions (no next story): return null/undefined
-   - Validation issues: collect and return as errors[]
-   - Non-fatal (context warnings): console.warn + continue
-2. Audit and fix the most egregious inconsistencies (don't rewrite everything).
-
-**STYLE-3 — Extract magic numbers:**
-1. In `src/agents/claude.ts`: `MAX_AGENT_OUTPUT_CHARS = 5000`
-2. In `src/execution/batching.ts`: `DEFAULT_MAX_BATCH_SIZE = 4` (already parameterized, just name the default)
-3. In `src/execution/helpers.ts`: `CONTEXT_MAX_TOKENS = 100_000`, `CONTEXT_RESERVED_TOKENS = 10_000`
-4. In `src/context/builder.ts`: `CHARS_PER_TOKEN = 3` (already documented, extract as named constant)
-5. Add JSDoc comments explaining why each value was chosen.
-
-**Run:** `bun test && bun run typecheck`
-**Commit:** `refactor: standardize error handling and extract magic numbers as named constants`
-
-## Test Strategy
-- Mode: test-after
-- Phase 1: update config tests for Zod errors
-- Phase 2: add batch escalation tests
-- Phase 3: add capability validation tests
-- Phase 4: add file context loading tests
-- Phase 5: no new tests (consistency refactor)

package/docs/20260217-partial-fixes-plan.md

@@ -1,62 +0,0 @@
-# Fix Plan: Complete Partially-Done Review Items
-**Date:** 2026-02-17
-**Branch:** master (local commits only)
-
-## Phase 1: BUG-3 — Cost Estimation Confidence Scores
-
-**File:** `src/agents/cost.ts`
-**Impact:** Users can't distinguish accurate vs estimated costs; budget tracking unreliable.
-
-**Changes:**
-1. Add `confidence: 'exact' | 'estimated' | 'fallback'` field to `CostEstimate` type
-2. `estimateCostFromOutput()` → returns confidence `'exact'` when structured tokens parsed, `'estimated'` when regex-matched
-3. `estimateCostByDuration()` → returns confidence `'fallback'`
-4. Add `formatCostWithConfidence(cost: CostEstimate): string` helper that shows confidence indicator (e.g., `$0.12 (exact)` vs `~$0.15 (estimated)`)
-5. Log warnings when fallback estimation is used
-6. Update existing tests, add tests for confidence field
-
-**Run:** `bun test`
-**Commit:** `fix(cost): add confidence scores to cost estimation`
-
-## Phase 2: MEM-1 — Lazy PRD Loading for Large Features
-
-**File:** `src/prd/index.ts`, `src/execution/runner.ts`
-**Impact:** Large PRDs (500+ stories) cause excessive memory and I/O.
-
-**Changes:**
-1. In `src/prd/index.ts`: Add `loadPRDLazy(path, options?: { storyIds?: string[] })` that loads only requested stories + metadata (story count, feature name)
-2. In `src/execution/runner.ts`: Replace full PRD reload every iteration with dirty-flag pattern:
-   - Set `prdDirty = true` only after writing PRD (story status update)
-   - Reload PRD only when dirty flag is set
-   - Use lazy loading to fetch only next batch of stories when possible
-3. Add `PRD_MAX_FILE_SIZE = 5 * 1024 * 1024` (5MB) constant — reject PRDs over this size with clear error
-
-**Run:** `bun test`
-**Commit:** `fix(prd): lazy loading and dirty-flag reload optimization`
-
-## Phase 3: ENH-1 — JSDoc for Underserved Modules
-
-**Files:** `src/agents/claude.ts`, `src/agents/types.ts`, `src/agents/cost.ts`, `bin/ngent.ts`, `src/routing/router.ts`, `src/tdd/orchestrator.ts`, `src/context/builder.ts`
-**Impact:** IDE intellisense missing, contributor onboarding harder.
-
-**Changes:**
-Add JSDoc with `@param`, `@returns`, `@example` to all exported functions:
-
-1. `src/agents/claude.ts`: Document `ClaudeCodeAdapter` class, `isInstalled()`, `run()`, `buildCommand()`
-2. `src/agents/types.ts`: Document `AgentAdapter` interface, `AgentResult`, `AgentRunOptions`
-3. `src/agents/cost.ts`: Document `estimateCostFromOutput()`, `estimateCostByDuration()`, `parseTokenUsage()`
-4. `bin/ngent.ts`: Document CLI commands and options
-5. `src/routing/router.ts`: Document `routeTask()` with decision tree example
-6. `src/tdd/orchestrator.ts`: Document `runThreeSessionTdd()` with session flow
-7. `src/context/builder.ts`: Document `buildContext()` with token budget example
-
-No logic changes — documentation only. No new tests needed.
-
-**Run:** `bun test` (ensure no regressions from doc edits)
-**Commit:** `docs: add comprehensive JSDoc to agents, routing, TDD, and CLI modules`
-
-## Test Strategy
-- Mode: test-after
-- Phase 1: update existing cost tests + add confidence tests
-- Phase 2: update runner tests for dirty-flag behavior
-- Phase 3: no new tests (docs only)

package/docs/20260217-plan-analyze-spec.md

@@ -1,117 +0,0 @@
-# Plan + Analyze Commands Spec
-**Date:** 2026-02-17
-**Status:** Approved
-
-## Commands
-
-### `ngent plan "description"`
-Interactive planning via coding agent's native plan mode.
-
-**Flow:**
-1. Spawn agent in plan mode (`claude --plan`, etc.)
-2. Agent reads codebase (scanner output injected as context)
-3. Agent asks clarifying questions until satisfied
-4. Agent produces structured spec
-5. ngent captures output → writes `ngent/spec.md`
-
-**Options:**
-- `ngent plan "Add URL shortener"` — interactive, agent takes over terminal
-- `ngent plan --from brief.md` — non-interactive, agent reads existing doc
-
-**Output:** `ngent/spec.md` with structured format:
-```markdown
-# Feature: [title]
-
-## Problem
-Why this is needed.
-
-## Requirements
-- REQ-1: ...
-- REQ-2: ...
-
-## Acceptance Criteria
-- AC-1: ...
-
-## Technical Notes
-Architecture hints, constraints, dependencies.
-
-## Out of Scope
-What this does NOT include.
-```
-
-**Agent adapter changes:**
-- Add `plan(prompt: string, options: PlanOptions): Promise<PlanResult>` to `AgentAdapter` interface
-- `PlanOptions`: `{ interactive: boolean, codebaseContext?: string, inputFile?: string }`
-- `PlanResult`: `{ specContent: string, conversationLog?: string }`
-- Claude implementation: `claude --plan` flag
-- Other agents: their equivalent plan mode
-
-**Model:** sonnet (needs good reasoning for questions + synthesis)
-
-### `ngent analyze`
-Decompose spec into classified stories → prd.json.
-
-**Flow:**
-1. Read `ngent/spec.md`
-2. Read codebase context (scanner: file tree, deps, test patterns)
-3. Single LLM call (sonnet): decompose spec into stories + classify each
-4. Output: `ngent/prd.json` with stories containing:
-   - `id`, `title`, `description`
-   - `complexity`: simple/medium/complex/expert
-   - `relevantFiles`: string[]
-   - `reasoning`: string (why this complexity)
-   - `estimatedLOC`: number
-   - `risks`: string[]
-   - `dependencies`: string[] (other story IDs)
-5. Falls back to existing keyword classification if LLM fails
-
-**Options:**
-- `ngent analyze` — reads spec.md, full decompose + classify
-- `ngent analyze --from other-spec.md` — explicit spec path
-- `ngent analyze --reclassify` — re-runs classification on existing prd.json (no decompose)
-
-**Model:** sonnet (structural decomposition needs quality)
-
-### Full workflow
-```
-ngent plan "Add URL shortener with analytics"
-ngent analyze
-ngent run
-```
-
-## Implementation Plan
-
-### Phase 1: Agent plan mode
-- Add `plan()` to `AgentAdapter` interface
-- Implement for `ClaudeCodeAdapter` using `claude --plan`
-- Add `ngent plan` CLI command
-- Codebase scanner integration (reuse existing `src/analyze/scanner.ts`)
-- Spec.md writer with structured template
-- Tests
-
-**Commit:** `feat(plan): add interactive planning via agent plan mode`
-
-### Phase 2: Analyze refactor
-- Refactor `ngent analyze` to read spec.md instead of tasks.md
-- Combine decompose + classify into single LLM call
-- Add `--from` and `--reclassify` flags
-- Remove tasks.md dependency
-- Update tests
-
-**Commit:** `feat(analyze): decompose spec into classified stories`
-
-## Config
-```json
-{
-  "plan": {
-    "model": "balanced",
-    "outputPath": "spec.md"
-  },
-  "analyze": {
-    "llmEnhanced": true,
-    "model": "balanced",
-    "fallbackToKeywords": true,
-    "maxCodebaseSummaryTokens": 5000
-  }
-}
-```