@nathapp/nax 0.18.1

package/docs/20260222-fix-plan-v091-routing-isolation.md

@@ -0,0 +1,197 @@
+# Fix Plan: v0.9.1 — Routing Respect + TDD Isolation Rework
+
+**Date:** 2026-02-22
+**Branch:** fix/v0.9.1-routing-isolation
+**Base:** Revert commits 211a884 and 4fa39a4, then apply clean fixes
+
+## Context
+
+Two commits (211a884, 4fa39a4) attempted to fix 4 issues but introduced problems:
+1. `determineTestStrategy()` still overrides LLM complexity via keyword scan
+2. Story count prompt hint isn't enforced
+3. `analyzeConfig` metadata is fine but incomplete (missing naxVersion)
+4. Isolation check now always passes (toothless)
+
+This plan implements clean fixes for all 4 issues.
+
+---
+
+## Phase 1: Revert and Create Branch
+
+1. `git revert --no-commit 4fa39a4 211a884` (revert both commits)
+2. `git checkout -b fix/v0.9.1-routing-isolation`
+3. Commit: `revert: undo 211a884 and 4fa39a4 for clean reimplementation`
+
+---
+
+## Phase 2: Fix Routing — LLM testStrategy in Decomposition
+
+**Problem:** `determineTestStrategy()` re-scans keywords after LLM already classified complexity, overriding LLM decisions for simple tasks.
+
+**Fix:** When `strategy=llm`, have the LLM output `testStrategy` directly in its decomposition response. `determineTestStrategy()` is only used for keyword-mode fallback.
+
+### Changes:
+
+**File: `src/agents/claude.ts`** (decomposition prompt)
+- Add to the decomposition prompt schema: each story must include `testStrategy: "three-session-tdd" | "test-after"`
+- Add decision rules to prompt:
+  ```
+  testStrategy rules:
+  - "three-session-tdd": ONLY for complex/expert tasks that are security-critical (auth, encryption, tokens) or define public API contracts
+  - "test-after": for all other tasks including simple/medium complexity
+  - A task being "simple" complexity should almost never be three-session-tdd
+  ```
+- Add `testStrategy` to the expected JSON response schema alongside existing `complexity` field
+
+**File: `src/cli/analyze.ts`**
+- When building UserStory from LLM decomposition result:
+  - Use `ds.testStrategy` directly (from LLM response) instead of calling `determineTestStrategy()`
+  - Fallback to `determineTestStrategy()` only if LLM didn't return a testStrategy
+- When using keyword classification (non-LLM path): keep calling `determineTestStrategy()` as-is
+- Add `routing.strategy: "llm" | "keyword"` and `routing.llmModel` to the story routing object
+
+**File: `src/prd/types.ts`**
+- Add to `StoryRouting`:
+  ```ts
+  strategy?: "keyword" | "llm";
+  llmModel?: string;
+  ```
+
+### Tests:
+- Update existing analyze tests to verify LLM-classified stories use LLM's testStrategy
+- Add test: simple story with "auth" in tags gets `test-after` from LLM (not overridden to three-session-tdd)
+
+---
+
+## Phase 3: Enforce Max Stories + Add analyzeConfig
+
+**Problem:** Prompt hint for max stories isn't enforced. analyzeConfig missing naxVersion.
+
+### Changes:
+
+**File: `src/agents/claude.ts`** (decomposition prompt)
+- Add grouping guidelines (from 211a884 — this part was good):
+  ```
+  Grouping Guidelines:
+  - Combine small related tasks into single stories
+  - Maximum stories: {maxStories} (from config). If you generate more, merge related ones.
+  - Aim for coherent units of value
+  ```
+- Pass `maxStories` from config into the prompt template
+
+**File: `src/cli/analyze.ts`**
+- After LLM returns stories, if count > `config.execution.maxStoriesPerFeature`:
+  - Log a warning: `"LLM returned {n} stories, exceeding max {max}. Consider re-running with stricter grouping."`
+  - Do NOT auto-truncate (could lose important work). Just warn.
+- Add `analyzeConfig` to PRD output:
+  ```ts
+  analyzeConfig: {
+    naxVersion: pkg.version,  // read from package.json
+    model: config.analyze.model,
+    llmEnhanced: config.analyze.llmEnhanced,
+    maxStoriesPerFeature: config.execution.maxStoriesPerFeature,
+    routingStrategy: config.analyze.llmEnhanced ? "llm" : "keyword",
+  }
+  ```
+
+**File: `src/prd/types.ts`**
+- Add to PRD interface:
+  ```ts
+  analyzeConfig?: {
+    naxVersion: string;
+    model: string;
+    llmEnhanced: boolean;
+    maxStoriesPerFeature: number;
+    routingStrategy: "keyword" | "llm";
+  };
+  ```
+
+### Tests:
+- Test that analyzeConfig is populated with correct values
+- Test warning logged when stories exceed max
+
+---
+
+## Phase 4: TDD Isolation — Detector + Verifier Judgment
+
+**Problem:** Isolation check always passes after 211a884. Should detect and report, let verifier judge.
+
+### Changes:
+
+**File: `src/tdd/types.ts`**
+- Update `IsolationCheck`:
+  ```ts
+  interface IsolationCheck {
+    /** Whether strict isolation was maintained (no test files touched) */
+    strictPass: boolean;
+    /** Test files modified by implementer */
+    modifiedTestFiles: string[];
+    /** Verdict: clean (no changes), needs-review (verifier must judge) */
+    verdict: "clean" | "needs-review";
+    description: string;
+  }
+  ```
+
+**File: `src/tdd/isolation.ts`**
+- `verifyImplementerIsolation()` returns honest results:
+  - If no test files modified: `{ strictPass: true, modifiedTestFiles: [], verdict: "clean" }`
+  - If test files modified: `{ strictPass: false, modifiedTestFiles: [...], verdict: "needs-review" }`
+  - Do NOT return `passed: true` when files were modified
+
+**File: `src/tdd/orchestrator.ts`**
+- After Session 2 isolation check:
+  - If `verdict === "clean"`: proceed normally
+  - If `verdict === "needs-review"`: inject modified file info into verifier (Session 3) prompt
+- Update verifier prompt:
+  ```
+  ⚠️ ISOLATION REVIEW REQUIRED
+  The implementer modified these test files: {modifiedTestFiles}
+  
+  You MUST review the changes to these files and determine:
+  - LEGITIMATE: Fixing genuinely incorrect test expectations, adding missing imports,
+    adjusting test fixtures to match correct implementation behavior
+  - VIOLATION: Removing test cases, weakening assertions, deleting acceptance criteria
+    checks, adding tests to inflate pass rate
+  
+  Include your verdict in the output:
+  - isolationVerdict: "approved" | "rejected"
+  - isolationReason: "<explanation>"
+  
+  If REJECTED: fail the story.
+  ```
+- Parse verifier output for isolation verdict
+- Log the verdict (approved/rejected + reason) to structured JSONL
+
+**File: `src/tdd/orchestrator.ts`** (runTddSession result handling)
+- When isolation.verdict === "needs-review" and verifier says "rejected":
+  - Mark story as failed with reason "TDD isolation violation confirmed by verifier"
+- When isolation.verdict === "needs-review" and verifier says "approved":
+  - Mark story as passed with warning logged
+
+### Tests:
+- Test isolation detection: modified test files → verdict "needs-review"
+- Test clean isolation: no test files → verdict "clean"  
+- Test orchestrator injects isolation context into verifier prompt when needs-review
+- Test story fails when verifier rejects isolation
+
+---
+
+## Phase 5: Version Bump + Cleanup
+
+1. Bump version to `0.9.1` in `package.json`
+2. Run full test suite: `bun test`
+3. Commit: `fix(v0.9.1): routing respects LLM complexity, isolation reworked to detector+verifier`
+4. Do NOT push.
+
+---
+
+## Test Strategy
+- Mode: test-after
+- Reason: Internal refactor with existing test coverage. Tests updated alongside implementation per phase.
+
+## Commits
+- Phase 1: `revert: undo 211a884 and 4fa39a4 for clean reimplementation`
+- Phase 2: `fix(routing): LLM decomposition outputs testStrategy directly`
+- Phase 3: `fix(analyze): enforce max stories warning, add analyzeConfig with naxVersion`
+- Phase 4: `fix(tdd): isolation becomes detector, verifier makes judgment`
+- Phase 5: `chore: bump to v0.9.1`

package/docs/20260223-fix-plan-prompt-audit.md

@@ -0,0 +1,62 @@
+# Fix Plan: nax prompts CLI + Scoped Test Coverage
+**Date:** 2026-02-23
+**Branch:** master (direct, v0.9.3)
+
+## Phase 1: `nax prompts` CLI Command (US-001)
+
+### Fix 1: Add CLI command handler
+**File:** `src/cli/prompts.ts` (new)
+**Change:** New CLI command that:
+- Accepts `-f <feature>` (required), `--out <dir>` (optional, default stdout), `--story <id>` (optional filter)
+- Loads PRD from feature dir
+- Loads config
+- For each story (or filtered story):
+  - Runs routing (classify complexity)
+  - Runs context building (buildContext + formatContextAsMarkdown)
+  - Loads constitution (if configured)
+  - Assembles prompt via buildSingleSessionPrompt / buildBatchPrompt
+  - For three-session-tdd stories: also builds test-writer/implementer/verifier prompts
+  - Outputs to stdout or writes files with YAML frontmatter
+
+### Fix 2: Register CLI command
+**File:** `src/cli/index.ts`
+**Change:** Add `prompts` subcommand to the CLI parser. Wire to handler.
+
+### Fix 3: Add tests
+**File:** `test/prompts-cli.test.ts` (new)
+**Change:** Test that:
+- `nax prompts` loads PRD and produces prompt files
+- Frontmatter includes storyId, testStrategy, contextTokens
+- `--story` flag filters to single story
+- Three-session-tdd stories produce separate session prompts
+- Output dir is created if it doesn't exist
+
+## Phase 2: Scoped Test Coverage Scanner (US-003)
+
+### Fix 4: Add story scoping to test scanner
+**File:** `src/context/test-scanner.ts`
+**Change:**
+- Accept optional `scopeFiles?: string[]` parameter
+- When scopeFiles provided, derive test file patterns (e.g., `src/health.service.ts` → `**/health.service.{spec,test}.ts`)
+- Filter scan results to only matching test files
+- Fall back to full scan when scopeFiles is empty/undefined
+
+### Fix 5: Wire scoping in context builder
+**File:** `src/context/builder.ts`
+**Change:** Pass `currentStory.contextFiles` to generateTestCoverageSummary as scopeFiles.
+
+### Fix 6: Add config option
+**File:** `src/config/schema.ts`
+**Change:** Add `context.testCoverage.scopeToStory` boolean (default: true) to config schema.
+
+### Fix 7: Add tests for scoped scanning
+**File:** `test/context.test.ts` or `test/test-scanner.test.ts`
+**Change:** Test that test coverage scan respects scopeFiles filter.
+
+## Test Strategy
+- Mode: test-after
+- Run: `bun test` after each phase
+
+## Commits
+- Phase 1: `feat: add nax prompts CLI command for prompt inspection`
+- Phase 2: `feat: scope test coverage scanner to story-relevant files`

package/docs/20260224-nax-roadmap-phases.md

@@ -0,0 +1,189 @@
+# nax Roadmap — TDD-Lite, LLM Service Layer, Parallelism
+
+*Date: 2026-02-24*
+*Status: Proposed*
+
+---
+
+## Context
+
+nax v0.10.0 has a solid TDD pipeline for TypeScript libraries, but struggles with:
+- Non-TS/polyglot projects (UI, shell scripts, integration-heavy)
+- No parallelism (sequential story execution)
+- Memory-heavy (long-running agent sessions, OOMs on 4GB VPS)
+- Single agent backend (claude CLI only, no OpenClaw sub-agents)
+
+dev-orchestrator (OpenClaw skill) solves execution well — worktrees, parallel coders, phase-by-phase memory — but lacks nax's TDD pipeline, structured logging, PRD workflow, and CLI.
+
+## nax vs dev-orchestrator — Honest Comparison
+
+| Capability | nax v0.10.0 | dev-orchestrator |
+|:-----------|:-----------|:-----------------|
+| **TDD pipeline** | ✅ Three-session (strict isolation) | ❌ None |
+| **Verification** | ✅ Isolated verifier | ❌ Code review only |
+| **Test quality gates** | ✅ Coverage, typecheck, lint | ❌ Up to the coder |
+| **Planning/PRD** | ✅ `nax plan` → `analyze` → structured stories | ❌ Simple task decomposition |
+| **Parallelism** | ❌ Sequential (batch = same session) | ✅ Git worktrees, true parallel |
+| **Memory** | ❌ Peaks 3-4GB+, OOMs on VPS | ✅ Phase-by-phase ~1-2GB, exits between phases |
+| **Agent backends** | ❌ claude CLI only | ✅ OpenClaw sessions_spawn + claude CLI |
+| **Structured logging** | ✅ JSONL, `nax runs list/show` | ❌ None |
+| **Hooks/plugins** | ✅ Global hooks, plugin system | ❌ None |
+| **Escalation tiers** | ✅ Automatic model escalation | ❌ Manual |
+| **Reproducibility** | ✅ Same PRD = same run | ❌ Depends on orchestrator prompt |
+| **Polyglot support** | ❌ TDD isolation breaks for UI/bash | ✅ Handles anything |
+| **Setup overhead** | ❌ PRD → analyze → config → run | ✅ Zero — just spawn with task |
+| **CLI** | ✅ Full CLI (`nax plan/run/accept/stories`) | ❌ OpenClaw skill only |
+
+### Key Insight
+
+nax's TDD pipeline is its strongest differentiator. dev-orchestrator's execution model (worktrees + phase-by-phase agents) is proven and lighter. The gap is **agent spawning** — nax can't spawn parallel managed agents (#3 LLM Service Layer).
+
+## Decision
+
+**Fix nax** in phases. Port dev-orchestrator's execution strengths into nax rather than rebuilding nax's TDD/PRD pipeline elsewhere.
+
+---
+
+## Phase 1 — TDD-Lite + Fallback (Quick Win)
+
+**Goal:** Solve GitLab #20, support non-TS projects without abandoning TDD.
+
+### Three TDD Tiers
+
+| Strategy | Test Writer | Implementer | Verifier | Use Case |
+|:---------|:-----------|:------------|:---------|:---------|
+| `three-session-tdd` (strict) | Isolated — no source access | Isolated — no test access | Isolated ✅ | TS libraries, APIs |
+| `three-session-tdd-lite` | Can read source, write tests | Free to modify anything | Isolated ✅ | UI, polyglot, integration |
+| `test-after` | N/A | Writes code + tests together | N/A | Simple tasks |
+
+### Fallback Logic
+
+- If test-writer produces **0 test files** in strict mode → auto-downgrade to `tdd-lite` and retry
+- No wasted iteration, no story pause
+
+### Config
+
+```json
+{
+  "tdd": {
+    "strategy": "auto" | "strict" | "lite" | "off",
+    "enabled": true
+  }
+}
+```
+
+- `auto` (default): LLM router classifies testability, picks strict or lite
+- `strict`: Always three-session-tdd
+- `lite`: Always three-session-tdd-lite
+- `off`: test-after for everything
+
+### Scope
+
+- Modify `src/tdd/` prompts for lite mode (relax isolation rules for test-writer)
+- Add fallback logic in `src/execution/runner.ts`
+- Add `strategy` to routing decision
+- Update config schema
+- No architecture changes needed
+
+---
+
+## Phase 2 — LLM Service Layer (GitLab #3)
+
+**Goal:** Abstract agent spawning so nax can use multiple backends and run agents in parallel.
+
+### Agent Interface
+
+```typescript
+interface Agent {
+  name: string;
+  spawn(options: AgentSpawnOptions): Promise<AgentSession>;
+  isInstalled(): Promise<boolean>;
+}
+
+interface AgentSession {
+  id: string;
+  status: 'running' | 'completed' | 'failed';
+  workdir: string;
+  wait(): Promise<AgentResult>;
+  kill(): Promise<void>;
+  steer?(message: string): Promise<void>;  // optional
+}
+
+interface AgentSpawnOptions {
+  prompt: string;
+  workdir: string;
+  model?: string;
+  timeout?: number;
+  env?: Record<string, string>;
+}
+```
+
+### Backends
+
+| Backend | How | Parallelism | Where |
+|:--------|:----|:-----------|:------|
+| `ClaudeCliAgent` | `claude -p` (existing) | ❌ Sequential | VPS, Mac01 |
+| `OpenClawAgent` | `sessions_spawn` | ✅ Managed sub-agents | OpenClaw environments |
+| `ApiAgent` | Direct Anthropic/Google API | ✅ Concurrent requests | Anywhere |
+
+### Key Design Decisions
+
+- Agent selection via config: `autoMode.defaultAgent: "claude-cli" | "openclaw" | "api"`
+- Each backend implements the same interface — runner doesn't care
+- `ApiAgent` is the lightest (no CLI overhead) but needs prompt engineering for tool use
+
+---
+
+## Phase 3 — Worktree Parallelism
+
+**Goal:** Run N stories concurrently using git worktrees + LLM Service Layer agents.
+
+### Flow
+
+```
+nax run -f feature --parallel 3
+  │
+  ├── Worktree: .nax-wt/story-001/ → Agent 1 (tdd pipeline)
+  ├── Worktree: .nax-wt/story-002/ → Agent 2 (tdd pipeline)
+  └── Worktree: .nax-wt/story-003/ → Agent 3 (tdd pipeline)
+  │
+  ├── Each agent exits after its story (phase-by-phase memory)
+  ├── Verifier runs per-worktree (isolated)
+  └── Merge back to main branch on pass
+```
+
+### Benefits
+
+- True parallelism (stolen from dev-orchestrator's proven model)
+- Phase-by-phase execution = low memory (solves VPS OOM)
+- Each worktree is isolated — no git conflicts during execution
+- Merge conflicts detected at merge time, not runtime
+
+### Dependencies
+
+- Phase 2 (LLM Service Layer) — need agent spawning abstraction
+- Worktree management utilities (create, merge, cleanup)
+- Dependency-aware scheduling (respect story dependencies in PRD)
+
+---
+
+## Dependency Chain
+
+```
+Phase 1: tdd-lite + fallback     ← standalone, no blockers
+    ↓
+Phase 2: LLM Service Layer (#3)  ← abstracts agent spawning
+    ↓
+Phase 3: Worktree parallelism    ← needs Phase 2
+    ↓
+Memory optimization              ← comes free with Phase 3
+```
+
+---
+
+## Open Questions
+
+1. Should `ApiAgent` support tool use (file read/write/exec) or is it prompt-only?
+2. For OpenClaw backend — do we use `sessions_spawn` (managed) or `exec` with claude CLI?
+3. Worktree merge strategy — rebase or merge commit?
+4. Should nax accept a `--backend` flag or always use config?