@nathapp/nax 0.50.3 → 0.51.2

package/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.51.0] - 2026-03-21
+
+### Added
+
+- **STRAT-001: `no-test` strategy** — New test strategy for stories with zero behavioral change (config, docs, CI/build files, dependency bumps, pure refactors). Requires `noTestJustification` field at every assignment point (plan prompt, LLM routing, batch routing) to prevent lazy test-skipping. `no-test` stories use an implement-only prompt (no RED/GREEN/REFACTOR), are exempt from greenfield override (BUG-010) and test-after escalation (S5), and batch separately from tested stories.
+- **DIR-001: Rename `nax/` → `.nax/`** — Project-level config directory now uses hidden dot-prefix convention (like `.git/`, `.claude/`). `PROJECT_NAX_DIR = ".nax"` SSOT constant in `src/config/paths.ts`. Package configs moved from `<pkg>/nax/config.json` to `.nax/packages/<pkg>/config.json`. 93 files updated.
+- **BUG-073: Acceptance fix story quality** — Fix stories now include acceptance test file path, truncated failure output, and "fix implementation not tests" instruction. Batched by related stories (cap 8) instead of 1-per-AC. Fix stories inherit `workdir` from related story. `>80%` AC failure triggers test regeneration instead of fix stories.
+- **BUG-073: Acceptance staleness detection** — SHA-256 fingerprint of AC set stored in `acceptance-meta.json`. Acceptance test auto-regenerates (with `.bak` backup) when stories are added/removed/modified.
+
+### Fixed
+
+- **fix(acceptance):** Correct `__dirname` depth in generator prompt — test file is exactly 3 `../` levels from root, not 4.
+- **fix(acceptance):** Acceptance tests always run from repo root — covers both single repo and monorepo. Test uses `__dirname`-based paths into packages.
+- **fix(acceptance):** Fix stories use per-package config for review/verify stages when `story.workdir` is set.
+- **fix(review):** Fallback to `quality.commands` when `review.commands` not configured — prevents routing failures in monorepo packages.
+- **fix(review):** Use optional chaining for `quality?.commands` — avoids crash when config has no quality section.
+- **fix(pkg):** Remove `src/` and `bin/` from npm `files` — only `dist/` published. 354 files / 4.7MB → 5 files / 3.1MB.
+
+### Refactored
+
+- **refactor(test):** Add `withDepsRestore` helper in `test/helpers/deps.ts` — eliminates save/restore boilerplate across 13 test files (−98 net lines).
+
+### Migration
+
+- Rename your project's `nax/` directory to `.nax/`
+- For monorepo: move `<pkg>/nax/config.json` → `.nax/packages/<pkg>/config.json`
+- Update `.gitignore` patterns: `nax/**/runs/` → `.nax/**/runs/`, etc.
+
+---
+
 ## [0.50.0] - 2026-03-19
 
 ### Added

package/README.md

@@ -33,15 +33,20 @@ nax run -f my-feature --plan --from spec.md
 ## How It Works
 
 ```
-analyze → route → execute → verify → (loop until all stories pass) → regression gate
+(plan →) acceptance setup → route → execute → verify → (escalate) → regression gate → acceptance
 ```
 
-1. **Analyze** each user story — classify complexity, select test strategy
-2. **Route** to the right model tier (cheap → standard → premium)
-3. **Execute** an agent session (Claude Code by default)
-4. **Verify** tests pass; escalate model tier on failure
-5. **Loop** until all stories are complete or a cost/iteration limit is hit
-6. **Regression gate** — deferred full-suite verification after all stories pass
+1. **Plan** *(optional)* — `nax run --plan` generates a `prd.json` from a spec file using an LLM
+2. **Acceptance setup** *(pre-run)* — generate acceptance tests and assert RED (tests must fail before implementation)
+3. **Route** — classify story complexity and select model tier (fast → balanced → powerful)
+4. **Context** — gather relevant code, tests, and project standards
+5. **Execute** — run an agent session (Claude Code, Codex, Gemini CLI, or ACP)
+6. **Verify** — run scoped tests; if failing, **rectify** before escalating
+7. **Review** — lint + typecheck; if failing, **autofix** before escalating
+8. **Escalate** — on repeated failure, retry with a higher model tier
+9. **Loop** — repeat steps 3–8 per story until all pass or a cost/iteration limit is hit
+10. **Regression gate** — deferred full-suite run after all stories pass
+11. **Acceptance** *(post-run)* — run the generated acceptance tests against the completed feature
 
 ---
 
@@ -49,7 +54,7 @@ analyze → route → execute → verify → (loop until all stories pass) → r
 
 ### `nax init`
 
-Initialize nax in your project. Creates the `nax/` folder structure.
+Initialize nax in your project. Creates the `.nax/` folder structure.
 
 ```bash
 nax init
@@ -57,7 +62,7 @@ nax init
 
 Creates:
 ```
-nax/
+.nax/
 ├── config.json       # Project-level config
 └── features/         # One folder per feature
 ```
@@ -68,7 +73,7 @@ nax/
 nax init --package packages/api
 ```
 
-Creates `packages/api/nax/context.md` for per-package agent context.
+Creates `.nax/mono/packages/api/context.md` for per-package agent context.
 
 ---
 
@@ -80,7 +85,7 @@ Scaffold a new feature.
 nax features create user-auth
 ```
 
-Creates `nax/features/user-auth/prd.json` — edit this file to define your user stories.
+Creates `.nax/features/user-auth/spec.md` — fill in the overview, user stories, and acceptance criteria, then run `nax plan` to generate `prd.json`.
 
 ### `nax features list`
 
@@ -135,7 +140,7 @@ nax run -f my-feature
 | Flag | Description |
 |:-----|:------------|
 | `-f, --feature <name>` | Feature name |
-| `-a, --agent <name>` | Force a specific agent (`claude`, `opencode`, `codex`, etc.) |
+| `-a, --agent <name>` | Force a specific agent (`claude`, `opencode`, `codex`, etc.). Only applies when `agent.protocol = "cli"` — ignored when using ACP protocol. |
 | `--plan` | Run plan phase first (requires `--from`) |
 | `--from <spec-path>` | Spec file for `--plan` |
 | `--one-shot` | Skip interactive Q&A during planning (ACP only) |
@@ -201,21 +206,28 @@ nax status -f my-feature
 
 ---
 
-### `nax logs -f <name>`
+### `nax logs`
 
-Stream logs from the current or last run.
+Stream logs from the current or last run. Run from your project directory.
 
 ```bash
-nax logs -f my-feature
+# List all recorded runs
+nax logs --list
 
-# Follow in real-time
-nax logs -f my-feature --follow
+# Follow current run in real-time
+nax logs --follow
 
 # Filter by story
-nax logs -f my-feature --story US-003
+nax logs --story US-003
 
-# Filter by level
-nax logs -f my-feature --level error
+# Filter by log level
+nax logs --level error
+
+# Select a specific run by ID
+nax logs --run <runId>
+
+# Raw JSONL output (for scripting)
+nax logs --json
 ```
 
 ---
@@ -255,7 +267,7 @@ Output sections:
 
 ### `nax generate`
 
-Generate agent config files from `nax/context.md`. Supports Claude Code, OpenCode, Codex, Cursor, Windsurf, Aider, and Gemini.
+Generate agent config files from `.nax/context.md`. Supports Claude Code, OpenCode, Codex, Cursor, Windsurf, Aider, and Gemini.
 
 ```bash
 nax generate
@@ -265,7 +277,7 @@ nax generate
 
 | Flag | Description |
 |:-----|:------------|
-| `-c, --context <path>` | Context file path (default: `nax/context.md`) |
+| `-c, --context <path>` | Context file path (default: `.nax/context.md`) |
 | `-o, --output <dir>` | Output directory (default: project root) |
 | `-a, --agent <name>` | Generate for a specific agent only (`claude`, `opencode`, `cursor`, `windsurf`, `aider`, `codex`, `gemini`) |
 | `--dry-run` | Preview without writing files |
@@ -287,7 +299,7 @@ nax generate
 
 **Workflow:**
 
-1. Create `nax/context.md` — describe your project's architecture, conventions, and coding standards
+1. Create `.nax/context.md` — describe your project's architecture, conventions, and coding standards
 2. Run `nax generate` — writes agent config files to the project root (and per-package if configured)
 3. Commit the generated files — your agents will automatically pick them up
 
@@ -301,7 +313,7 @@ nax generate --package packages/api
 nax generate --all-packages
 ```
 
-Each package can have its own `nax/context.md` at `<package>/nax/context.md` for package-specific agent instructions.
+Each package can have its own context file at `.nax/mono/<package>/context.md` for package-specific agent instructions (created via `nax init --package <package>`).
 
 ---
 
@@ -317,7 +329,7 @@ nax prompts -f my-feature
 
 | Flag | Description |
 |:-----|:------------|
-| `--init` | Export default role templates to `nax/templates/` for customization |
+| `--init` | Export default role templates to `.nax/templates/` for customization |
 | `--role <role>` | Show prompt for a specific role (`implementer`, `test-writer`, `verifier`, `tdd-simple`) |
 
 After running `--init`, edit the templates and nax will use them automatically via `prompts.overrides` config.
@@ -354,12 +366,19 @@ nax agents
 
 ---
 
-### `nax config --explain`
+### `nax config`
 
-Display the effective merged configuration with inline explanations for every field.
+Display the effective merged configuration (global + project layers).
 
 ```bash
-nax config -f my-feature --explain
+# Show merged config
+nax config
+
+# Show with field descriptions
+nax config --explain
+
+# Show only fields where project overrides global
+nax config --diff
 ```
 
 ---
@@ -371,7 +390,7 @@ Config is layered — project overrides global:
 | File | Scope |
 |:-----|:------|
 | `~/.nax/config.json` | Global (all projects) |
-| `nax/config.json` | Project-level override |
+| `.nax/config.json` | Project-level override |
 
 **Key options:**
 
@@ -414,7 +433,7 @@ Review commands (`lint`, `typecheck`) are executed directly via `Bun.spawn` —
 }
 ```
 ```json
-// nax/config.json
+// .nax/config.json
 "quality": {
   "commands": {
     "typecheck": "bun run build-and-check"
@@ -442,13 +461,15 @@ Use `testScoped` to define the exact scoped test command with a `{{files}}` plac
 
 If `testScoped` is not configured, nax falls back to a heuristic that replaces the last path-like token in the `test` command. **Recommended:** always configure `testScoped` explicitly to avoid surprises.
 
-**TDD strategy options:**
+**TDD strategy options:** <a name="tdd-strategy-options"></a>
 
 | Value | Behaviour |
 |:------|:----------|
-| `auto` | nax decides based on complexity and tags |
-| `lite` | Prefer `three-session-tdd-lite` for complex stories |
-| `strict` | Always use full `three-session-tdd` for complex stories |
+| `auto` | nax decides based on complexity and tags — simple→`tdd-simple`, security/public-api→`three-session-tdd`, else→`three-session-tdd-lite` |
+| `strict` | Always use `three-session-tdd` (strictest — all stories) |
+| `lite` | Always use `three-session-tdd-lite` |
+| `simple` | Always use `tdd-simple` (1 session) |
+| `off` | No TDD — tests written after implementation (`test-after`) |
 
 ---
 
@@ -462,12 +483,12 @@ Customize the instructions sent to each agent role for your project's specific n
 
 ```bash
 nax prompts --init              # Create default templates
-# Edit nax/templates/*.md
+# Edit .nax/templates/*.md
 nax prompts --export test-writer # Preview a role's prompt
 nax run -f my-feature           # Uses your custom prompts
 ```
 
-**Full guide:** See [Prompt Customization Guide](docs/prompt-customization.md) for detailed instructions, role reference, and best practices.
+**Full guide:** See [Prompt Customization Guide](docs/guides/prompt-customization.md) for detailed instructions, role reference, and best practices.
 
 ---
 
@@ -477,12 +498,13 @@ nax selects a test strategy per story based on complexity and tags:
 
 | Strategy | Sessions | When | Description |
 |:---------|:---------|:-----|:------------|
-| `test-after` | 1 | Refactors, deletions, config, docs | Single session, no TDD discipline |
+| `no-test` | 1 | Config, docs, CI, pure refactors with no behavior change | No tests written or run — requires `noTestJustification` in prd.json |
+| `test-after` | 1 | Refactors, deletions | Single session, tests written after implementation |
 | `tdd-simple` | 1 | Simple stories | Single session with TDD prompt (red-green-refactor) |
 | `three-session-tdd-lite` | 3 | Medium stories | Three sessions, relaxed isolation rules |
 | `three-session-tdd` | 3 | Complex/security stories | Three sessions, strict file isolation |
 
-Configure the default TDD behavior in `nax/config.json`:
+Configure the default TDD behavior in `.nax/config.json`:
 
 ```json
 {
@@ -492,11 +514,7 @@ Configure the default TDD behavior in `nax/config.json`:
 }
 ```
 
-| Value | Behaviour |
-|:------|:----------|
-| `auto` | nax decides based on complexity and tags (default) |
-| `lite` | Prefer `three-session-tdd-lite` for complex stories |
-| `strict` | Always use full `three-session-tdd` for complex stories |
+See [TDD strategy options](#tdd-strategy-options) for all values.
 
 ---
 
@@ -544,7 +562,7 @@ Configured under `quality.testing` — supports **per-package override** in mono
 
 > **Tip:** `externalBoundaries` and `mockGuidance` complement `context.md`. nax provides the rule ("mock all I/O"), while `context.md` provides project-specific knowledge ("use `ioredis-mock` for Redis"). Use both for best results.
 
-> **Monorepo:** Each package can override `quality.testing` in its own `packages/<name>/nax/config.json`. For example, `packages/api` can specify Redis boundaries while `packages/web` specifies HTTP-only.
+> **Monorepo:** Each package can override `quality.testing` in its own `.nax/mono/<package>/config.json`. For example, `packages/api` can specify Redis boundaries while `apps/web` specifies HTTP-only.
 
 > **Opt-out:** Set `quality.testing.hermetic: false` if your project requires real integration calls (e.g. live database tests against a local dev container).
 
@@ -552,34 +570,41 @@ Configured under `quality.testing` — supports **per-package override** in mono
 
 ## Story Decomposition
 
-When a story is too large (complex/expert with >6 acceptance criteria), nax can automatically decompose it into smaller sub-stories. This runs during the routing stage.
+Story decomposition is **opt-in** — disabled by default. Enable it by adding a `decompose` block to `.nax/config.json`.
 
-**Trigger:** The `story-oversized` interaction trigger fires when a story exceeds the configured thresholds. You can approve decomposition, skip the story, or continue as-is.
-
-**How it works:**
-
-1. The `DecomposeBuilder` constructs a prompt with the target story, sibling stories (to prevent overlap), and codebase context
-2. An LLM generates sub-stories with IDs, titles, descriptions, acceptance criteria, and dependency ordering
-3. Post-decompose validators check:
-   - **Overlap** — sub-stories must not duplicate scope of existing stories
-   - **Coverage** — sub-stories must cover all parent acceptance criteria
-   - **Complexity** — each sub-story must be simpler than the parent
-   - **Dependencies** — dependency graph must be acyclic with valid references
-4. The parent story is replaced in the PRD with the validated sub-stories
+When enabled, nax checks during the routing stage whether a story is oversized (complex/expert complexity with more ACs than `maxAcceptanceCriteria`). If so, an LLM breaks it into smaller sub-stories and replaces the original in the PRD.
 
 **Configuration:**
 
 ```json
 {
   "decompose": {
-    "enabled": true,
-    "maxSubStories": 5,
-    "minAcceptanceCriteria": 6,
-    "complexityThreshold": ["complex", "expert"]
+    "trigger": "auto",
+    "maxAcceptanceCriteria": 6,
+    "maxSubstories": 5,
+    "maxSubstoryComplexity": "medium",
+    "maxRetries": 2,
+    "model": "balanced"
   }
 }
 ```
 
+**Trigger modes:**
+
+| Value | Behaviour |
+|:------|:----------|
+| `auto` | Decompose automatically — no confirmation prompt |
+| `confirm` | Show interaction prompt — you approve, skip, or continue as-is |
+| `disabled` | Never decompose — log a warning if story is oversized |
+
+> **Note:** `storySizeGate` (under `precheck`) is a separate pre-run guard that warns if stories exceed size limits before execution starts. Decomposition happens during routing, mid-run.
+
+**How it works:**
+
+1. An LLM generates sub-stories with IDs, titles, descriptions, acceptance criteria, and dependency ordering
+2. Post-decompose validators check overlap, coverage, complexity, and dependency ordering
+3. The parent story is replaced in the PRD with the validated sub-stories
+
 ---
 
 ## Regression Gate
@@ -601,8 +626,8 @@ After all stories pass their individual verification, nax can run a deferred ful
 | Mode | Behaviour |
 |:-----|:----------|
 | `disabled` | No regression gate |
-| `per-story` | Full suite after each story (expensive) |
-| `deferred` | Full suite once after all stories pass (recommended) |
+| `per-story` | Full suite after each story — higher cost and slower if stories fail regression |
+| `deferred` | Full suite once after all stories pass (recommended) — **default** |
 
 If the regression gate detects failures, nax maps them to the responsible story via git blame and attempts automated rectification. If rectification fails, affected stories are marked as `regression-failed`.
 
@@ -646,7 +671,9 @@ nax run -f my-feature --parallel 3
 
 ## Agents
 
-nax supports multiple coding agents. By default it uses Claude Code via the ACP protocol.
+nax supports multiple coding agents via the [Agent Client Protocol (ACP)](https://github.com/openclaw/acpx). **ACP protocol is recommended** — it provides persistent sessions, structured cost/token reporting, and works with all supported agents.
+
+> **CLI protocol** (`agent.protocol: "cli"`) is supported for Claude Code only and is being gradually deprecated in favour of ACP. New projects should use ACP.
 
 ```bash
 # List installed agents and their capabilities
@@ -655,21 +682,16 @@ nax agents
 
 **Supported agents:**
 
-| Agent | Protocol | Notes |
-|:------|:---------|:------|
-| `claude` | ACP (default) | Claude Code via acpx |
-| `opencode` | ACP | OpenCode via acpx |
-| `codex` | ACP | Codex via acpx |
-| `cursor` | ACP | Cursor via acpx |
-| `windsurf` | ACP | Windsurf via acpx |
-| `aider` | ACP | Aider via acpx |
-| `gemini` | ACP | Gemini CLI via acpx |
+| Agent | CLI mode |
+|:------|:---------|
+| `claude` | ✅ Stable |
+| All others (`codex`, `gemini`, `opencode`, `cursor`, `copilot`, `kilo`, `qwen`, `kimi`, `iflow`, `droid`, `kiro`, and more) | 🧪 Experimental |
 
-**ACP protocol (default):**
+nax connects to agents via [acpx](https://github.com/openclaw/acpx). All agents run as persistent ACP sessions — nax sends prompts and receives structured JSON-RPC responses including token counts and exact USD cost per session. For the full list of supported agents and their ACP startup commands, see the [acpx agent docs](https://github.com/openclaw/acpx#agents).
 
-nax uses [acpx](https://github.com/nathapp/acpx) as the ACP transport. All agents run as persistent sessions — nax sends prompts and receives structured JSON-RPC responses including token counts and exact USD cost per session.
+> **Note:** When `agent.protocol` is set to `"acp"`, the `--agent` CLI flag has no effect — all execution routes through the ACP adapter regardless of agent name.
 
-> **Known issue — `acpx` ≤ 0.3.1:** The `--model` flag is not supported. Model selection via `execution.model` or per-package `model` overrides has no effect when using acpx as the ACP transport. This is a limitation in the underlying `@zed-industries/claude-agent-acp` adapter, which ignores runtime model requests and always uses the model configured in Claude Code settings. A fix is being tracked in [openclaw/acpx#49](https://github.com/openclaw/acpx/issues/49). As a workaround, set your preferred model directly in Claude Code settings before running nax.
+> **Known issue — `acpx` ≤ 0.3.1:** The `--model` flag is not supported. Model selection via `execution.model` or per-package `model` overrides has no effect. As a temporary workaround, use the [nathapp-io/acpx](https://github.com/nathapp-io/acpx) fork which adds `--model` support. Upstream fix is tracked in [openclaw/acpx#49](https://github.com/openclaw/acpx/issues/49).
 
 **Configuring agents:**
 
@@ -683,10 +705,11 @@ nax uses [acpx](https://github.com/nathapp/acpx) as the ACP transport. All agent
 }
 ```
 
-**Force a specific agent at runtime:**
+**Force a specific agent at runtime (CLI protocol only):**
 
 ```bash
-nax run -f my-feature --agent opencode
+# Only applies when agent.protocol = "cli" (Claude Code only — other agents experimental)
+nax run -f my-feature --agent claude
 ```
 
 ---
@@ -708,27 +731,27 @@ nax init --package packages/web
 
 ### Per-Package Config
 
-Each package can override specific config fields by placing a `nax/config.json` inside the package directory:
+Each package's config and context are stored centrally under the root `.nax/mono/` directory:
 
 ```
 repo-root/
-├── nax/
-│   └── config.json          # root config
-├── packages/
-│   ├── api/
-│   │   └── nax/
-│   │       ├── config.json  # overrides for api package
-│   │       └── context.md   # agent context for api
-│   └── web/
-│       └── nax/
-│           ├── config.json  # overrides for web package
-│           └── context.md   # agent context for web
+├── .nax/
+│   ├── config.json                    # root config
+│   └── mono/
+│       ├── packages/
+│       │   └── api/
+│       │       ├── config.json        # overrides for packages/api
+│       │       └── context.md        # agent context for packages/api
+│       └── apps/
+│           └── api/
+│               ├── config.json        # overrides for apps/api
+│               └── context.md        # agent context for apps/api
 ```
 
 **Overridable fields per package:** `execution`, `review`, `acceptance`, `quality`, `context`
 
 ```json
-// packages/api/nax/config.json
+// .nax/mono/packages/api/config.json
 {
   "quality": {
     "commands": {
@@ -764,7 +787,7 @@ When `nax plan` generates stories for a monorepo, it auto-discovers packages fro
 - `turbo.json` → `packages` field
 - `package.json` → `workspaces`
 - `pnpm-workspace.yaml` → `packages`
-- Existing `*/nax/context.md` files
+- Existing `.nax/mono/*/context.md` files
 
 ### Generate Agent Files for All Packages
 
@@ -772,7 +795,7 @@ When `nax plan` generates stories for a monorepo, it auto-discovers packages fro
 nax generate --all-packages
 ```
 
-Generates a `CLAUDE.md` (or agent-specific file) in each discovered package directory, using the package's own `nax/context.md` if present.
+Generates a `CLAUDE.md` (or agent-specific file) in each discovered package directory, using the package's own `.nax/mono/<package>/context.md` if present.
 
 ---
 
@@ -780,7 +803,7 @@ Generates a `CLAUDE.md` (or agent-specific file) in each discovered package dire
 
 Integrate notifications, CI triggers, or custom scripts via lifecycle hooks.
 
-**Project hooks** (`nax/hooks.json`):
+**Project hooks** (`.nax/hooks.json`):
 
 ```json
 {
@@ -883,7 +906,7 @@ nax can pause execution and prompt you for decisions at critical points. Configu
 | `max-retries` | 🟡 Yellow | `skip` | Story exhausted all retry attempts — skip and continue? |
 | `pre-merge` | 🟡 Yellow | `escalate` | Checkpoint before merging to main branch |
 | `human-review` | 🟡 Yellow | `skip` | Human review required on critical failure |
-| `story-oversized` | 🟡 Yellow | `continue` | Story too complex — decompose into sub-stories? |
+| `story-oversized` | 🟡 Yellow | `continue` | Story too complex — decompose into sub-stories? (only fires when `decompose.trigger = "confirm"`) |
 | `story-ambiguity` | 🟢 Green | `continue` | Story requirements unclear — continue with best effort? |
 | `review-gate` | 🟢 Green | `continue` | Code review checkpoint before proceeding |
 
@@ -913,7 +936,7 @@ nax can pause execution and prompt you for decisions at critical points. Configu
 
 Extend nax with custom reviewers, reporters, or integrations.
 
-**Project plugins** (`nax/config.json`):
+**Project plugins** (`.nax/config.json`):
 
 ```json
 {
@@ -976,35 +999,85 @@ nax precheck -f my-feature
 
 **Run stopped mid-way**
 
-nax saves progress in `nax/features/<name>/prd.json`. Re-run with the same command — completed stories are skipped automatically.
+nax saves progress in `.nax/features/<name>/prd.json`. Re-run with the same command — completed stories are skipped automatically.
 
 ---
 
 ## PRD Format
 
-User stories are defined in `nax/features/<name>/prd.json`:
+User stories are defined in `.nax/features/<name>/prd.json`. Typically generated by `nax plan` — but you can write it by hand.
 
 ```json
 {
+  "project": "my-app",
   "feature": "user-auth",
+  "branchName": "feat/user-auth",
+  "createdAt": "2026-01-01T00:00:00.000Z",
+  "updatedAt": "2026-01-01T00:00:00.000Z",
   "userStories": [
     {
       "id": "US-001",
       "title": "Add login endpoint",
-      "description": "POST /auth/login with email/password",
+      "description": "POST /auth/login accepts email + password, returns signed JWT on success",
       "acceptanceCriteria": [
-        "Returns JWT on success",
-        "Returns 401 on invalid credentials"
+        "Returns 200 + JWT on valid credentials",
+        "Returns 401 on invalid credentials",
+        "Rate-limits to 5 attempts per minute"
       ],
-      "complexity": "medium",
       "tags": ["auth", "security"],
-      "status": "pending"
+      "dependencies": [],
+      "status": "pending",
+      "passes": false,
+      "attempts": 0,
+      "escalations": [],
+      "contextFiles": ["src/auth/types.ts"],
+      "expectedFiles": ["src/auth/login.ts", "test/auth/login.test.ts"]
+    },
+    {
+      "id": "US-002",
+      "title": "Update changelog",
+      "description": "Add v1.0 entry to CHANGELOG.md",
+      "acceptanceCriteria": ["CHANGELOG.md has v1.0 section"],
+      "tags": ["docs"],
+      "dependencies": [],
+      "status": "pending",
+      "passes": false,
+      "attempts": 0,
+      "escalations": [],
+      "routing": {
+        "complexity": "simple",
+        "testStrategy": "no-test",
+        "noTestJustification": "Docs-only change — no executable code",
+        "reasoning": "Pure documentation update"
+      }
     }
   ]
 }
 ```
 
-> **Note:** Use `"status": "passed"` (not `"done"`) to manually mark a story complete.
+**Key fields:**
+
+| Field | Required | Description |
+|:------|:---------|:------------|
+| `id` | ✅ | Story ID — must be unique (e.g. `US-001`) |
+| `title` | ✅ | Short story title |
+| `description` | ✅ | What needs to be built |
+| `acceptanceCriteria` | ✅ | Testable outcomes — used for acceptance tests |
+| `tags` | ✅ | Routing hints that influence complexity classification and test strategy selection. Security tags (`auth`, `security`, `jwt`, `oauth`, `rbac`, etc.) and public-API tags (`public-api`, `endpoint`, `sdk`, etc.) force `three-session-tdd`. UI/integration tags (`ui`, `layout`, `cli`, `integration`) prefer `three-session-tdd-lite`. |
+| `dependencies` | ✅ | Story IDs that must pass before this one runs |
+| `status` | ✅ | `pending` \| `in-progress` \| `passed` \| `failed` \| `skipped` \| `blocked` \| `paused` |
+| `passes` | ✅ | `true` once all ACs pass — set by nax, not manually |
+| `attempts` | ✅ | Retry counter — set by nax |
+| `escalations` | ✅ | Escalation history — set by nax |
+| `contextFiles` | optional | Files pre-loaded into agent prompt |
+| `expectedFiles` | optional | Files that must exist after execution (pre-flight gate) |
+| `workdir` | optional | Package subdirectory for monorepo stories (e.g. `packages/api`) |
+| `routing` | optional | Pre-set routing — skip LLM classification if provided |
+| `routing.testStrategy` | optional | Override test strategy (e.g. `no-test`, `tdd-simple`). Only honored when `routing.contentHash` is absent — omit `contentHash` to prevent the LLM classifier from overriding your manual value. |
+| `routing.noTestJustification` | required if `no-test` | Explain why no tests are needed |
+| `storyPoints` | optional | Estimate (default: 1) |
+
+> **Tip:** Use `"status": "passed"` to manually skip a story that's already done.
 
 ---