@nathapp/nax 0.28.0 → 0.29.0

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

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

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

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