@nathapp/nax 0.18.1

package/docs/20260217-dogfood-findings.md

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

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

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

@@ -0,0 +1,117 @@
+# 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
+  }
+}
+```