@nathapp/nax 0.28.0 → 0.29.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.28.0",
+  "version": "0.29.0",
   "description": "AI Coding Agent Orchestrator \u2014 loops until done",
   "type": "module",
   "bin": {
-    "nax": "./bin/nax.ts"
+    "nax": "./dist/nax.js"
   },
   "scripts": {
     "prepare": "git config core.hooksPath .githooks",
@@ -16,7 +16,8 @@
     "test:watch": "bun test --watch",
     "test:unit": "bun test ./test/unit/ --timeout=60000",
     "test:integration": "bun test ./test/integration/ --timeout=60000",
-    "test:ui": "bun test ./test/ui/ --timeout=60000"
+    "test:ui": "bun test ./test/ui/ --timeout=60000",
+    "prepublishOnly": "bun run build"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.74.0",
@@ -43,5 +44,12 @@
     "orchestrator",
     "tdd",
     "coding"
+  ],
+  "files": [
+    "dist/",
+    "src/",
+    "bin/",
+    "README.md",
+    "CHANGELOG.md"
   ]
-}
+}

package/src/cli/config.ts

@@ -143,6 +143,8 @@ const FIELD_DESCRIPTIONS: Record<string, string> = {
 
   // Context
   context: "Context injection configuration",
+  "context.fileInjection":
+    "Mode: 'disabled' (default, MCP-aware agents pull context on-demand) | 'keyword' (legacy git-grep injection for non-MCP agents). Set context.fileInjection in config.",
   "context.testCoverage": "Test coverage context settings",
   "context.testCoverage.enabled": "Enable test coverage context injection",
   "context.testCoverage.detail": "Detail level: names-only | names-and-counts | describe-blocks",
@@ -517,7 +519,7 @@ function displayConfigWithDescriptions(
 
     // Display description comment if available
     if (description) {
-      // Include path only for prompts section (where tests expect "prompts.overrides" to appear)
+      // Include path for prompts section (where tests expect "prompts.overrides" to appear)
       const isPromptsSubSection = currentPathStr.startsWith("prompts.");
       const comment = isPromptsSubSection ? `${currentPathStr}: ${description}` : description;
       console.log(`${indentStr}# ${comment}`);

package/src/config/defaults.ts

@@ -128,6 +128,7 @@ export const DEFAULT_CONFIG: NaxConfig = {
     testPath: "acceptance.test.ts",
   },
   context: {
+    fileInjection: "disabled",
     testCoverage: {
       enabled: true,
       detail: "names-and-counts",

package/src/config/schemas.ts

@@ -202,6 +202,7 @@ const ContextAutoDetectConfigSchema = z.object({
 const ContextConfigSchema = z.object({
   testCoverage: TestCoverageConfigSchema,
   autoDetect: ContextAutoDetectConfigSchema,
+  fileInjection: z.enum(["keyword", "disabled"]).default("disabled"),
 });
 
 const AdaptiveRoutingConfigSchema = z.object({

package/src/config/types.ts

@@ -339,6 +339,7 @@ export interface ContextAutoDetectConfig {
 export interface ContextConfig {
   testCoverage: TestCoverageConfig;
   autoDetect: ContextAutoDetectConfig;
+  fileInjection?: "keyword" | "disabled";
 }
 
 /** Story size gate thresholds (v0.16.0) */

package/src/context/builder.ts

@@ -23,6 +23,11 @@ import {
 import { generateTestCoverageSummary } from "./test-scanner";
 import type { BuiltContext, ContextBudget, ContextElement, StoryContext } from "./types";
 
+// Dependency injection for testability
+export const _deps = {
+  autoDetectContextFiles,
+};
+
 // Re-export for backward compatibility
 export {
   estimateTokens,
@@ -188,6 +193,10 @@ async function addFileElements(
   const MAX_FILE_SIZE_BYTES = 10 * 1024;
   const MAX_FILES = 5;
 
+  // Skip all file injection when fileInjection is 'disabled' or undefined (treat missing as disabled)
+  const fileInjection = storyContext.config?.context?.fileInjection;
+  if (fileInjection !== "keyword") return;
+
   let contextFiles = getContextFiles(story);
 
   // Auto-detect contextFiles if empty and enabled (BUG-006)
@@ -198,7 +207,7 @@ async function addFileElements(
   ) {
     const autoDetectConfig = storyContext.config?.context?.autoDetect;
     try {
-      const detected = await autoDetectContextFiles({
+      const detected = await _deps.autoDetectContextFiles({
         workdir: storyContext.workdir,
         storyTitle: story.title,
         maxFiles: autoDetectConfig?.maxFiles ?? 5,

package/src/prompts/sections/role-task.ts

@@ -15,7 +15,8 @@ export function buildRoleTaskSection(variant: "standard" | "lite"): string {
       "- Implement source code in src/ to make tests pass\n" +
       "- Do NOT modify test files\n" +
       "- Run tests frequently to track progress\n" +
-      "- Goal: all tests green"
+      "- When all tests are green, stage and commit ALL changed files with git commit -m 'feat: <description>'\n" +
+      "- Goal: all tests green, all changes committed"
     );
   }
 
@@ -27,6 +28,7 @@ export function buildRoleTaskSection(variant: "standard" | "lite"): string {
     "- Write tests first (test/ directory), then implement (src/ directory)\n" +
     "- All tests must pass by the end\n" +
     "- Use Bun test (describe/test/expect)\n" +
-    "- Goal: all tests green, all criteria met"
+    "- When all tests are green, stage and commit ALL changed files with git commit -m 'feat: <description>'\n" +
+    "- Goal: all tests green, all criteria met, all changes committed"
   );
 }

package/src/review/runner.ts

@@ -208,7 +208,12 @@ export async function runReview(
   let firstFailure: string | undefined;
 
   // RQ-001: Check for uncommitted tracked files before running checks
-  const uncommittedFiles = await _deps.getUncommittedFiles(workdir);
+  const allUncommittedFiles = await _deps.getUncommittedFiles(workdir);
+  // Exclude nax runtime files — written by nax itself during the run, not by the agent
+  const NAX_RUNTIME_FILES = new Set(["nax/status.json", ".nax-verifier-verdict.json"]);
+  const uncommittedFiles = allUncommittedFiles.filter(
+    (f) => !NAX_RUNTIME_FILES.has(f) && !f.match(/^nax\/features\/.+\/prd\.json$/),
+  );
   if (uncommittedFiles.length > 0) {
     const fileList = uncommittedFiles.join(", ");
     logger?.warn("review", `Uncommitted changes detected before review: ${fileList}`);

package/src/version.ts

@@ -36,4 +36,5 @@ export const NAX_COMMIT: string = (() => {
   return "dev";
 })();
 
-export const NAX_BUILD_INFO = `v${NAX_VERSION} (${NAX_COMMIT})`;
+/** Human-readable build info string — omits commit when unavailable. */
+export const NAX_BUILD_INFO: string = NAX_COMMIT === "dev" ? `v${NAX_VERSION}` : `v${NAX_VERSION} (${NAX_COMMIT})`;

package/.claude/rules/01-project-conventions.md

@@ -1,34 +0,0 @@
-# Project Conventions
-
-## Language & Runtime
-
-- **Bun-native only.** Use `Bun.file()`, `Bun.write()`, `Bun.spawn()`, `Bun.sleep()`. Never use Node.js equivalents (`fs.readFile`, `child_process.spawn`, `setTimeout` for delays).
-- TypeScript strict mode. No `any` unless unavoidable (document why).
-- Target: Bun 1.3.7+.
-
-## File Size
-
-- **400-line hard limit** for all source and test files.
-- If a file approaches 400 lines, split it before adding more code.
-- Split by logical concern (one function/class per file when possible).
-
-## Module Structure
-
-- Every directory with 2+ exports gets a barrel `index.ts`.
-- Types go in `types.ts` per module directory.
-- Import from barrels (`src/routing`), **never from internal paths** (`src/routing/router`). This prevents singleton fragmentation in Bun's module registry.
-
-## Logging
-
-- Use the project logger (`src/logger`). Never use `console.log` / `console.error` in source code.
-- Log format: no emojis. Use `[OK]`, `[WARN]`, `[FAIL]`, `->`. Machine-parseable.
-
-## Commits
-
-- Conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`.
-- Atomic — one logical change per commit.
-- Never include `[run-release]` unless explicitly told to.
-
-## Formatting
-
-- Biome handles formatting and linting. Run `bun run lint` before committing.

package/.claude/rules/02-test-architecture.md

@@ -1,39 +0,0 @@
-# Test Architecture
-
-## Directory Structure
-
-Tests **must** mirror the `src/` directory structure:
-
-```
-src/routing/strategies/foo.ts    → test/unit/routing/strategies/foo.test.ts
-src/execution/runner.ts          → test/unit/execution/runner.test.ts
-src/pipeline/stages/verify.ts   → test/unit/pipeline/stages/verify.test.ts
-src/verification/smart-runner.ts → test/unit/verification/smart-runner.test.ts
-```
-
-## Test Categories
-
-| Category | Location | Purpose |
-|:---|:---|:---|
-| Unit | `test/unit/<mirror-of-src>/` | Test individual functions/classes in isolation |
-| Integration | `test/integration/<feature>.test.ts` | Test multiple modules working together |
-| UI | `test/ui/` | TUI component tests |
-
-## Placement Rules
-
-1. **Never create test files in `test/` root.** Always place in the appropriate subdirectory.
-2. **Never create standalone bug-fix test files** like `test/execution/post-verify-bug026.test.ts`. Add tests to the existing relevant test file instead. If the relevant file would exceed 400 lines, split the file by describe block — not by bug number.
-3. **Never create `TEST_COVERAGE_*.md` or documentation files in `test/`.** Put docs in `docs/`.
-4. **Unit test directories must exist under `test/unit/`**, mirroring `src/`. Do not create top-level test directories like `test/execution/` or `test/context/` — use `test/unit/execution/` and `test/unit/context/`.
-
-## File Naming
-
-- Test files: `<source-file-name>.test.ts` — must match the source file name exactly.
-- One test file per source file (for unit tests).
-- If a test file needs splitting, split by describe block into `<module>-<concern>.test.ts`.
-
-## Temp Files & Fixtures
-
-- Use `mkdtempSync(join(tmpdir(), "nax-test-"))` for temporary directories.
-- Clean up in `afterAll()` — never leave files in `test/tmp/`.
-- Integration tests needing git: always `git init` + `git add .` + `git commit` in the temp fixture before testing.

package/.claude/rules/03-test-writing.md

@@ -1,58 +0,0 @@
-# Test Writing Rules
-
-## Mocking
-
-### Never use `mock.module()`
-
-`mock.module()` in Bun 1.x is **globally scoped and leaks between test files**. It poisons the ESM module registry for the entire test run. `mock.restore()` does NOT undo `mock.module()` overrides.
-
-**Instead, use dependency injection:**
-
-```typescript
-// In source file: export a swappable deps object
-export const _deps = {
-  readConfig: () => loadConfig(),
-  runCommand: (cmd: string) => Bun.spawn(cmd.split(" ")),
-};
-
-// In test file: override _deps directly
-import { _deps } from "src/mymodule";
-
-beforeEach(() => {
-  _deps.readConfig = mock(() => fakeConfig);
-});
-
-afterEach(() => {
-  mock.restore(); // restores mock() spies (NOT mock.module)
-  _deps.readConfig = originalReadConfig;
-});
-```
-
-### General Mocking Rules
-
-- Always call `mock.restore()` in `afterEach()`.
-- Use `mock()` (function-level) freely — it's properly scoped.
-- Never rely on test file execution order. Each file must be independently runnable.
-- Store original function references before overriding `_deps` and restore in `afterEach`.
-
-## CI Compatibility
-
-- Tests requiring the `claude` binary: guard with `const skipInCI = process.env.CI ? test.skip : test;`
-- Tests requiring specific OS features: guard with platform checks.
-- Never send real signals (`process.kill`) — mock `process.on()` instead.
-
-## Spawning & Subprocesses
-
-- Never spawn full `nax` processes in tests — prechecks fail in temp dirs.
-- Wrap `Bun.spawn()` in try/catch — throws `ENOENT` for missing binaries (not a failed exit code).
-
-## Test Structure
-
-- One `describe()` block per source function or class being tested.
-- Keep test files under 400 lines. Split by `describe()` block if needed.
-- Use `test/helpers/` for shared mock factories and fixtures. Don't copy-paste mocking setup between files.
-
-## Imports
-
-- **Import from barrels** (`src/routing`), not internal paths (`src/routing/router`).
-- This matches the project convention and prevents Bun singleton fragmentation where the same module loaded via two different paths creates two separate instances.

package/.claude/rules/04-forbidden-patterns.md

@@ -1,29 +0,0 @@
-# Forbidden Patterns
-
-These patterns are **banned** from the nax codebase. Violations must be caught during implementation, not after.
-
-## Source Code
-
-| ❌ Forbidden | ✅ Use Instead | Why |
-|:---|:---|:---|
-| `mock.module()` | Dependency injection (`_deps` pattern) | Leaks globally in Bun 1.x, poisons other test files |
-| `console.log` / `console.error` in src/ | Project logger (`src/logger`) | Unstructured output breaks test capture and log parsing |
-| `fs.readFileSync` / `fs.writeFileSync` | `Bun.file()` / `Bun.write()` | Bun-native project — no Node.js file APIs |
-| `child_process.spawn` / `child_process.exec` | `Bun.spawn()` / `Bun.spawnSync()` | Bun-native project — no Node.js process APIs |
-| `setTimeout` / `setInterval` for delays | `Bun.sleep()` | Bun-native equivalent |
-| Hardcoded timeouts in logic | Config values from schema | Hardcoded values can't be tuned per-environment |
-| `import from "src/module/internal-file"` | `import from "src/module"` (barrel) | Prevents singleton fragmentation (BUG-035) |
-| Files > 400 lines | Split by concern | Unmaintainable; violates project convention |
-
-## Test Files
-
-| ❌ Forbidden | ✅ Use Instead | Why |
-|:---|:---|:---|
-| Test files in `test/` root | `test/unit/`, `test/integration/`, etc. | Orphaned files with no clear ownership |
-| Standalone bug-fix test files (`*-bug026.test.ts`) | Add to existing relevant test file | Fragments test coverage, creates ownership confusion |
-| `TEST_COVERAGE_*.md` in test/ | `docs/` directory | Test dir is for test code only |
-| `rm -rf` in test cleanup | `mkdtempSync` + OS temp dir | Accidental deletion risk |
-| Tests depending on alphabetical file execution order | Independent, self-contained test files | Cross-file coupling causes phantom failures |
-| Copy-pasted mock setup across files | `test/helpers/` shared factories | DRY; single place to update when interfaces change |
-| Spawning full `nax` process in tests | Mock the relevant module | Prechecks fail in temp dirs; slow; flaky |
-| Real signal sending (`process.kill`) | Mock `process.on()` | Can kill the test runner |

package/.claude/settings.json

@@ -1,15 +0,0 @@
-{
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "bun x biome lint --write src/ bin/"
-          }
-        ]
-      }
-    ]
-  }
-}

package/.githooks/pre-commit

@@ -1,16 +0,0 @@
-#!/usr/bin/env bash
-# nax pre-commit hook — runs typecheck + lint
-# Install: git config core.hooksPath .githooks
-
-set -e
-
-# Ensure bun is on PATH (git hooks run with minimal PATH)
-export PATH="$HOME/.bun/bin:$PATH"
-
-echo "[pre-commit] Running typecheck..."
-bun run typecheck
-
-echo "[pre-commit] Running lint..."
-bun run lint
-
-echo "[pre-commit] OK"

package/.gitlab-ci.yml

@@ -1,103 +0,0 @@
-# .gitlab-ci.yml - nax CI/CD
-# Bun-native, single package (no turbo/monorepo)
-#
-# Triggers:
-#   - MR: test only (gate for merge)
-#   - [run-release] on master: test + release + notify
-#   - [run-prerelease] on non-master: test + canary release + notify
-#   - release-by-bot commits and tags: skipped entirely
-
-stages:
-  - test
-  - release
-  - notify
-
-# --- Stage: Test ---
-test:
-  stage: test
-  image: 
-    name: nathapp/node-bun:22.21.0-1.3.9-alpine
-    pull_policy: always
-  before_script:
-    - apk add --no-cache git 
-    - git config --global safe.directory '*'
-    - git config --global user.name "CI Runner"
-    - git config --global user.email "ci@nathapp.io"
-  cache:
-    key:
-      files:
-        - bun.lock
-    paths:
-      - node_modules/
-    policy: pull-push
-  script:
-    - bun install --frozen-lockfile
-    - bun run typecheck
-    - bun run lint
-    - bun run test
-  rules:
-    - if: '$CI_COMMIT_MESSAGE =~ /release-by-bot/ || $CI_COMMIT_TAG'
-      when: never
-    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
-    - if: '$CI_COMMIT_MESSAGE =~ /run-prerelease/ && $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH'
-    - if: '$CI_COMMIT_MESSAGE =~ /run-release/ && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
-
-# --- Stage: Release ---
-release:
-  stage: release
-  image: 
-    name: nathapp/node-bun:22.21.0-1.3.9-alpine
-    pull_policy: always
-  cache:
-    key:
-      files:
-        - bun.lock
-    paths:
-      - node_modules/
-    policy: pull
-  variables:
-    NPM_REGISTRY: "//registry.npmjs.org/"
-    NPM_RELEASE_TOKEN: $NPM_TOKEN
-  before_script:
-    - apk add --no-cache git
-    - git config --global safe.directory '*'
-    - git config --global user.name "$GITLAB_USER_NAME"
-    - git config --global user.email "$GITLAB_USER_EMAIL"
-  script:
-    - bun install --frozen-lockfile
-    - VERSION=$(bun -e "console.log(require('./package.json').version)")
-    - bun run build
-    - echo "${NPM_REGISTRY}:_authToken=${NPM_RELEASE_TOKEN}" > .npmrc
-    - npm publish --access public
-    - git tag -a "v${VERSION}" -m "v${VERSION}"
-    - git push "https://${GITLAB_USER_NAME}:${CI_GIT_TOKEN}@${CI_REPOSITORY_URL#*@}" --tags
-  rules:
-    - if: '$CI_COMMIT_MESSAGE =~ /release-by-bot/ || $CI_COMMIT_TAG'
-      when: never
-    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
-      when: never
-    - if: '$CI_COMMIT_MESSAGE =~ /run-prerelease/ && $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH'
-      variables:
-        NPM_REGISTRY: "//npm.nathapp.io/"
-        NPM_RELEASE_TOKEN: $NPM_PRIVATE_TOKEN
-    - if: '$CI_COMMIT_MESSAGE =~ /run-release/ && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
-
-# --- Stage: Notify ---
-notify:
-  stage: notify
-  image: 
-    name: registry-intl.cn-hongkong.aliyuncs.com/gkci/node:22.14.0-alpine-ci
-    pull_policy: always
-  needs: [release]
-  script:
-    - VERSION=$(node -e "console.log(require('./package.json').version)")
-    - 'curl -s -X POST -H "Content-Type: application/json" -d "{\"chat_id\": \"$TELEGRAM_CHAT_ID\", \"text\": \"nax v${VERSION} released\"}" https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage'
-  rules:
-    - if: '$CI_COMMIT_MESSAGE =~ /release-by-bot/ || $CI_COMMIT_TAG'
-      when: never
-    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
-      when: never
-    - if: '$TELEGRAM_BOT_TOKEN == null || $TELEGRAM_BOT_TOKEN == ""'
-      when: never
-    - if: '$CI_COMMIT_MESSAGE =~ /run-prerelease/ && $CI_COMMIT_BRANCH != $CI_DEFAULT_BRANCH'
-    - if: '$CI_COMMIT_MESSAGE =~ /run-release/ && $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

package/.mcp.json

@@ -1,8 +0,0 @@
-{
-  "mcpServers": {
-    "code-graph": {
-      "type": "http",
-      "url": "http://192.168.1.142:3100/mcp"
-    }
-  }
-}

package/BRIEF.md

@@ -1,140 +0,0 @@
-# nax — Brief
-
-## What
-AI coding agent orchestrator (CLI, Bun + TypeScript). Takes a feature spec, decomposes into user stories via LLM, routes each to the right model tier by complexity, and executes them with auto-escalation and retry. Supports three-session TDD for quality-critical work. Currently v0.10.1 on master. Published as `@nathapp/nax` (not yet on npm — local/global install only).
-
-## Architecture
-
-```
-spec.md + tasks.md
-    ↓
-nax analyze → prd.json (user stories with routing metadata)
-    ↓
-nax run → pipeline per story:
-    routing → context → constitution → prompt → optimizer → execution → review → acceptance → completion
-                                                  ↑                                ↑
-                                            (v0.10 plugin)                   (v0.10 plugin)
-    ↑                         ↑
-  plugin routers        plugin context-providers
-```
-
-**Key modules:**
-
-| Module | Purpose |
-|:-------|:--------|
-| `pipeline/` | Stage-based runner — each stage returns continue/skip/fail/escalate/pause |
-| `routing/` | Strategy chain: keyword → LLM → adaptive → manual → plugin |
-| `context/` | Builds per-story context from PRD + dependencies within token budget |
-| `tdd/` | Three-session orchestrator: test-writer → implementer → verifier with git-diff isolation |
-| `execution/` | Spawns `claude -p` via ClaudeCodeAdapter, handles timeouts and cost tracking |
-| `status-file/` | *(v0.10.1)* Atomic JSON status writer for external monitoring (dashboards/CI) |
-| `acceptance/` | LLM-generated acceptance tests, validates story output |
-| `agents/` | Adapter pattern — currently only Claude Code, designed for Codex/Gemini/OpenCode |
-| `hooks/` | Lifecycle events (on-start, on-complete, on-pause, on-error) via shell commands |
-| `config/` | Layered config: global (`~/.nax/`) → project (`nax/`) with Zod validation + deep merge |
-| `constitution/` | Injected rules/constraints prepended to every agent prompt |
-| `plugins/` | *(v0.10)* Plugin loader, registry, and extension point interfaces |
-| `optimizer/` | *(v0.10)* Prompt optimization stage (rule-based built-in + plugin support) |
-
-## Key Decisions
-
-| Decision | Why | Date | Ref |
-|:---------|:----|:-----|:----|
-| Classify complexity upfront, not start-cheap | Avoids wasting cycles on wrong model; LLM routing is cheap (~$0.002/story) | 2026-02-16 | SPEC.md |
-| Three-session TDD (not two) | Session 3 (verifier) catches cases where implementer subtly modifies tests; git-diff isolation between all sessions | 2026-02-16 | SPEC.md |
-| LLM outputs testStrategy directly | Keyword matching caused false positives ("endpoint"→TDD). LLM handles nuance better | 2026-02-23 | #11, #12 |
-| Stage-based pipeline over monolithic runner | Composable, testable, each stage can skip/fail independently | 2026-02-17 | v0.3-spec |
-| Bun over Node | Faster test execution, native TypeScript, built-in file APIs | 2026-02-16 | — |
-| Token budget for context | Prevents context overflow (200k window); reserves 100k for agent reasoning | 2026-02-17 | context/builder.ts |
-| Constitution as separate file | Project-level rules (coding standards, forbidden patterns) injected into every prompt without modifying CLAUDE.md | 2026-02-18 | — |
-| Hooks over built-in integrations | Users wire their own notifications/CI via shell commands; nax stays standalone | 2026-02-16 | SPEC.md |
-| Dropped greenfield scaffolding (#13) | Chicken-and-egg: nax/ must exist inside project, but scaffolding creates the project. Manual US-000 works fine. Existing tools (na-cli, nest new) handle scaffolding better. | 2026-03-03 | #13 |
-| Test-writer allowed paths for barrel exports | `src/index.ts` re-exports are common TDD collateral; soft-warn instead of hard-block | 2026-02-22 | #9 |
-| Story pause doesn't block unrelated stories | Dependency graph determines which stories can proceed independently | 2026-02-22 | #10 |
-| Use actual BuiltContext tokens in frontmatter | Re-estimating tokens independently caused mismatches; element-level tracking is more accurate for audit | 2026-02-23 | #15 |
-| Shared TDD prompt module | Extracting TDD prompts from orchestrator ensures consistency between CLI and execution | 2026-02-23 | #15 |
-| Plugin system over ad-hoc extension | Unified registration/loading for all extension points (optimizer, router, agent, reviewer, context, reporter). Reuses existing interfaces. | 2026-03-03 | #8, #14 |
-| Deep merge for global+project config | More intuitive than section replace; users only override what they change. Hooks and constitution concatenate (global first). | 2026-03-03 | #14 |
-| No LLM optimizer built-in | Fast-tier LLM rewrite adds cost/complexity. Rule-based covers deterministic wins. External LLM optimizers (LLMLingua, etc.) can be added via plugins. | 2026-03-03 | #8 |
-| TDD-Lite over removing TDD | TDD is nax's differentiator; instead of dropping it, add a relaxed variant (lite) where only verifier stays isolated. Strict for TS libs, lite for UI/polyglot. | 2026-02-24 | #20 |
-| Fix nax over replacing with dev-orchestrator | dev-orchestrator lacks TDD pipeline, structured logging, PRD workflow. Porting those is more work than fixing nax's weaknesses. | 2026-02-24 | `docs/20260224-nax-roadmap-phases.md` |
-| Dry-run marks stories as passed | Previous dry-run never changed story status, causing infinite loop until maxIterations. Now marks passed + saves PRD for natural completion. | 2026-02-24 | `09996c8` |
-| Targeted git reset for TDD fallback | `git checkout .` was too aggressive; now resets only files touched by the failed session, preserving other local changes. | 2026-02-24 | `d1dc4b9` |
-| Atomic Status File (v0.10.1) | Machine-readable status tracking via JSON. Atomic write (write-then-rename) prevents partial reads during polling. | 2026-02-25 | `status-file-v0.10.1.md` |
-| Category-based TDD routing (v0.10.1) | Isolation violations trigger strategy downgrade (Lite) while mechanical failures trigger tier escalation. Reduces manual pause/resume cycles. | 2026-02-25 | `status-file-v0.10.1.md` |
-
-## Config Reference
-
-Config loaded from `~/.nax/config.json` (global) deep-merged with `nax/config.json` (project). CLI flags override both.
-
-**Resolution order:** Built-in defaults → `~/.nax/config.json` → `nax/config.json` → CLI flags
-
-| Section | Key | Type | Default | Purpose |
-|:--------|:----|:-----|:--------|:--------|
-| models | fast/balanced/powerful | ModelDef \| string | haiku/sonnet/opus | Maps abstract tiers to actual models |
-| autoMode | complexityRouting | Record<Complexity, Tier> | simple→fast, medium→balanced, complex/expert→powerful | Which tier handles which complexity |
-| autoMode | escalation.tierOrder | TierConfig[] | fast×5, balanced×3, powerful×2 | Retry budget per tier before escalating |
-| routing | strategy | keyword\|llm\|manual\|adaptive\|custom | keyword | How stories get classified |
-| routing | llm.mode | one-shot\|per-story\|hybrid | hybrid | Batch-route upfront + re-route on retry |
-| execution | costLimit | number (USD) | 5.0 | Pause run when cost exceeds this |
-| execution | sessionTimeoutSeconds | number | 600 | Kill agent session after this |
-| execution | verificationTimeoutSeconds | number | 300 | Kill test/typecheck/lint subprocess |
-| quality | commands.test | string | (auto-detect) | Custom test command |
-| quality | forceExit | boolean | false | Append --forceExit to test command |
-| quality | stripEnvVars | string[] | CLAUDECODE, REPL_ID, AGENT | Env vars removed during verification |
-| tdd | sessionTiers | {testWriter, implementer, verifier} | balanced/story-tier/fast | Per-session model overrides |
-| tdd | testWriterAllowedPaths | string[] | src/index.ts, src/**/index.ts | Soft-allowed paths for test-writer |
-| constitution | path | string | constitution.md | Relative to config dir (~/.nax/ or nax/) |
-| constitution | skipGlobal | boolean | false | *(v0.10)* Skip global constitution for this project |
-| context | testCoverage.detail | names-only\|names-and-counts\|describe-blocks | names-and-counts | How much test info to inject |
-| context | testCoverage.maxTokens | number | 500 | Token budget for test coverage section |
-| context | testCoverage.scopeToStory | boolean | true | Filter test coverage to story-relevant files only |
-| acceptance | enabled | boolean | true | Run LLM acceptance validation |
-| analyze | llmEnhanced | boolean | true | Use LLM for story decomposition |
-| optimizer | enabled | boolean | false | *(v0.10)* Enable prompt optimization stage |
-| optimizer | strategy | noop\|rule-based | noop | *(v0.10)* Built-in optimizer strategy |
-| hooks | skipGlobal | boolean | false | *(v0.10)* Skip global hooks for this project |
-| plugins | (array) | PluginConfigEntry[] | [] | *(v0.10)* Explicit plugin modules + config |
-
-Full schema with Zod validation: `src/config/schema.ts`
-
-## v0.10 Specs
-
-| Feature | Spec File | Stories | Summary |
-|:--------|:----------|:--------|:--------|
-| Plugin System | `docs/v0.10-plugin-system.md` | 9 | Loader, registry, 6 extension point interfaces (optimizer, router, agent, reviewer, context-provider, reporter) |
-| Prompt Optimizer | `docs/v0.10-prompt-optimizer.md` | 5 | NoopOptimizer (default), RuleBasedOptimizer (strip whitespace, compact criteria, dedup context), optimizer pipeline stage |
-| Global Config | `docs/v0.10-global-config.md` | 7 | `~/.nax/` directory, deep merge (project wins), hooks concatenate (global first), constitution concatenate, `nax init --global`, `skipGlobal` opt-out |
-| Status File & Smart Escalation | `docs/specs/status-file-v0.10.1.md` | 9 | Atomic JSON status tracking, failure categorization, retry-as-lite strategy downgrade |
-
-**Total: ~30 user stories** across 4 features.
-
-## Version History
-
-| Version | What Changed | Issues |
-|:--------|:-------------|:-------|
-| v0.10.1 | Status file (machine-readable), Smart TDD escalation (retryAsLite), Verifier Verdicts | #16 |
-| v0.10.0 | Plugin system, Global config layering, Prompt optimizer stage | #8, #14 |
-| v0.9.3 | Prompt Audit CLI (`nax prompts`), context isolation unit tests, scoped test coverage scanner | #15 |
-
-## Roadmap
-
-| Priority | Feature | Status | Ref |
-|:---------|:--------|:-------|:----|
-| **Done** | Phase 1: TDD-Lite strategy + zero-file fallback | ✅ Done | #20, `docs/20260224-nax-roadmap-phases.md` |
-| **Next** | Phase 2: LLM Service Layer — agent interface with pluggable backends | 📋 Planned | #3 |
-| **Next** | Phase 3: Worktree parallelism — N stories concurrent | 📋 Planned | — |
-| **Backlog** | CLI for paused stories (`nax stories`, `nax resume`) | 📋 Planned | #18 |
-| **Backlog** | Quality flags + review.checks unification | 📋 Planned | #19 |
-
-### Phase Dependency Chain
-```
-Phase 1: tdd-lite + fallback     ← standalone, no blockers
-    ↓
-Phase 2: LLM Service Layer (#3)  ← abstracts agent spawning (claude-cli, openclaw, api)
-    ↓
-Phase 3: Worktree parallelism    ← needs Phase 2 for multi-agent coordination
-```
-
----
-*Updated 2026-02-25*