@nathapp/nax 0.49.0 → 0.49.3

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.49.3] - 2026-03-18
+
+### Fixed
+- **Autofix `recheckReview` bug:** `reviewStage.execute()` returns `action:"continue"` for both pass AND built-in-check-failure (to hand off to autofix). Using `result.action === "continue"` always returned `true`, causing "Mechanical autofix succeeded" to log every cycle and looping until `MAX_STAGE_RETRIES` with no real fix. Fix: check `ctx.reviewResult?.success` directly after execute.
+- **Autofix selective mechanical fix:** `lintFix`/`formatFix` cannot fix typecheck errors. Phase 1 now only runs when the `lint` check actually failed. Typecheck-only failures skip straight to agent rectification (Phase 2).
+- **Review command logging:** `runner.ts` now logs the resolved command and workdir for every check at info level, and full output on failure at warn level — eliminates phantom failure mystery.
+- **Re-decompose on second run:** Batch-mode story selector was missing `"decomposed"` in its status skip list (single-story path already excluded it). Stories with `status: "decomposed"` were being picked up again, triggering unnecessary LLM decompose calls. Added `"decomposed"` to batch filter and a guard in routing SD-004 block.
+- **totalCost always 0:** `handlePipelineFailure` returned no `costDelta`; `iteration-runner` hardcoded `costDelta: 0` for failures. Agent cost for failed stories was silently dropped. Fix: extract `agentResult?.estimatedCost` in failure path same as success path.
+
+## [0.49.2] - 2026-03-18
+
+### Fixed
+- **Test strategy descriptions:** `TEST_STRATEGY_GUIDE` (used in plan and decompose prompts) had incorrect descriptions for `three-session-tdd` and `three-session-tdd-lite`. Both strategies use 3 sessions. Key distinction: `three-session-tdd` (strict) — test-writer makes no src/ changes, implementer makes no test changes; `three-session-tdd-lite` (lite) — test-writer may add minimal src/ stubs, implementer may expand coverage and replace stubs. Updated in `src/config/test-strategy.ts`, `docs/specs/test-strategy-ssot.md`, and `docs/architecture/ARCHITECTURE.md`.
+
+## [0.49.1] - 2026-03-18
+
+### Fixed
+- **ACP zero cost:** `acpx prompt` was called without `--format json`, causing it to output plain text instead of JSON-RPC NDJSON. Cost and token usage were always 0. Fix: pass `--format json` as a global flag so the parser receives `usage_update` (exact cost in USD) and `result.usage` (token breakdown).
+- **Decompose session name / model:** Decompose one-shots used an auto-generated timestamp session name and passed the tier string (`"balanced"`) as the model instead of the resolved model ID. Fix: session name is now `nax-decompose-<story-id>` and model tier is resolved via `resolveModel()` before the `complete()` call.
+- **`autoCommitIfDirty` skipping monorepo subdirs:** The working-directory guard rejected any workdir that wasn't exactly the git root, silently skipping commits for monorepo package subdirs. Fix: allow subdirs (`startsWith(gitRoot + '/')`); use `git add .` for subdirs vs `git add -A` at root.
+- **`complete()` missing model in `generateFromPRD()` and `plan` auto mode:** `generator.ts` ignored `options.modelDef.model`; `plan.ts` auto path didn't call `resolveModel()`. Both now pass the correct resolved model to `adapter.complete()`.
+
 ## [0.46.2] - 2026-03-17
 
 ### Fixed

package/README.md

@@ -18,8 +18,16 @@ bun install -g @nathapp/nax
 cd your-project
 nax init
 nax features create my-feature
-# Edit nax/features/my-feature/prd.json with your user stories
+
+# Option A: write prd.json manually, then run
+nax run -f my-feature
+
+# Option B: generate prd.json from a spec file, then run
+nax plan -f my-feature --from spec.md
 nax run -f my-feature
+
+# Option C: plan + run in one command
+nax run -f my-feature --plan --from spec.md
 ```
 
 ## How It Works
@@ -54,6 +62,14 @@ nax/
 └── features/         # One folder per feature
 ```
 
+**Monorepo — scaffold a package:**
+
+```bash
+nax init --package packages/api
+```
+
+Creates `packages/api/nax/context.md` for per-package agent context.
+
 ---
 
 ### `nax features create <name>`
@@ -76,20 +92,33 @@ nax features list
 
 ---
 
-### `nax analyze -f <name>`
+### `nax plan -f <name> --from <spec>`
 
-Parse a `spec.md` file into a structured `prd.json`. Uses an LLM to decompose the spec into classified user stories.
+Generate a `prd.json` from a spec file using an LLM. Replaces the deprecated `nax analyze`.
 
 ```bash
-nax analyze -f my-feature
+nax plan -f my-feature --from spec.md
 ```
 
 **Flags:**
 
 | Flag | Description |
 |:-----|:------------|
-| `--from <path>` | Explicit spec path (overrides default `spec.md`) |
-| `--reclassify` | Re-classify existing `prd.json` without re-decomposing |
+| `-f, --feature <name>` | Feature name (required) |
+| `--from <spec-path>` | Path to spec file (required) |
+| `--auto` / `--one-shot` | Skip interactive Q&A — single LLM call, no back-and-forth |
+| `-b, --branch <branch>` | Override default branch name |
+| `-d, --dir <path>` | Project directory |
+
+**Interactive vs one-shot:**
+- Default (no flag): interactive planning session — nax asks clarifying questions, refines the plan iteratively
+- `--auto` / `--one-shot`: single LLM call, faster but less precise
+
+---
+
+### `nax analyze` *(deprecated)*
+
+> ⚠️ **Deprecated.** Use `nax plan` instead. `nax analyze` remains available for backward compatibility but will be removed in a future version.
 
 ---
 
@@ -105,10 +134,23 @@ nax run -f my-feature
 
 | Flag | Description |
 |:-----|:------------|
-| `-f, --feature <name>` | Feature name (required) |
+| `-f, --feature <name>` | Feature name |
+| `-a, --agent <name>` | Force a specific agent (`claude`, `opencode`, `codex`, etc.) |
+| `--plan` | Run plan phase first (requires `--from`) |
+| `--from <spec-path>` | Spec file for `--plan` |
+| `--one-shot` | Skip interactive Q&A during planning (ACP only) |
+| `--force` | Overwrite existing `prd.json` when using `--plan` |
+| `--parallel <n>` | Max parallel sessions (`0` = auto based on CPU cores; omit = sequential) |
 | `--dry-run` | Preview story routing without running agents |
 | `--headless` | Non-interactive output (structured logs, no TUI) |
-| `-d, --dir <path>` | Project directory (defaults to `cwd`) |
+| `--verbose` | Debug-level logging |
+| `--quiet` | Warnings and errors only |
+| `--silent` | Errors only |
+| `--json` | Raw JSONL output to stdout (for scripting) |
+| `--skip-precheck` | Skip precheck validations (advanced users only) |
+| `--no-context` | Disable context builder (skip file context in prompts) |
+| `--no-batch` | Execute all stories individually (disable batching) |
+| `-d, --dir <path>` | Working directory |
 
 **Examples:**
 
@@ -116,11 +158,23 @@ nax run -f my-feature
 # Preview what would run (no agents spawned)
 nax run -f user-auth --dry-run
 
-# Run in a different directory
-nax run -f user-auth -d /path/to/project
+# Plan from spec then run — one command
+nax run -f user-auth --plan --from spec.md
+
+# Run with parallel execution (auto concurrency)
+nax run -f user-auth --parallel 0
+
+# Run with up to 3 parallel worktree sessions
+nax run -f user-auth --parallel 3
+
+# Force a specific agent
+nax run -f user-auth --agent opencode
 
 # Run in CI/CD (structured output)
 nax run -f user-auth --headless
+
+# Raw JSONL for scripting
+nax run -f user-auth --json
 ```
 
 ---
@@ -199,6 +253,58 @@ Output sections:
 
 ---
 
+### `nax generate`
+
+Generate agent config files from `nax/context.md`. Supports Claude Code, OpenCode, Codex, Cursor, Windsurf, Aider, and Gemini.
+
+```bash
+nax generate
+```
+
+**Flags:**
+
+| Flag | Description |
+|:-----|:------------|
+| `-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 |
+| `--no-auto-inject` | Disable auto-injection of project metadata |
+| `--package <dir>` | Generate for a specific monorepo package (e.g. `packages/api`) |
+| `--all-packages` | Generate for all discovered packages |
+
+**What it generates:**
+
+| Agent | File |
+|:------|:-----|
+| Claude Code | `CLAUDE.md` |
+| OpenCode | `AGENTS.md` |
+| Codex | `AGENTS.md` |
+| Cursor | `.cursorrules` |
+| Windsurf | `.windsurfrules` |
+| Aider | `.aider.md` |
+| Gemini | `GEMINI.md` |
+
+**Workflow:**
+
+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
+
+**Monorepo (per-package):**
+
+```bash
+# Generate CLAUDE.md for a single package
+nax generate --package packages/api
+
+# Generate for all packages (auto-discovers workspace packages)
+nax generate --all-packages
+```
+
+Each package can have its own `nax/context.md` at `<package>/nax/context.md` for package-specific agent instructions.
+
+---
+
 ### `nax prompts -f <name>`
 
 Assemble and display the prompt that would be sent to the agent for each story role.
@@ -439,6 +545,170 @@ If the regression gate detects failures, nax maps them to the responsible story
 
 ---
 
+## Parallel Execution
+
+nax can run multiple stories concurrently using git worktrees — each story gets an isolated worktree so agents don't step on each other.
+
+```bash
+# Auto concurrency (based on CPU cores)
+nax run -f my-feature --parallel 0
+
+# Fixed concurrency
+nax run -f my-feature --parallel 3
+```
+
+**How it works:**
+
+1. Stories are grouped by dependency order (dependent stories wait for their prerequisites)
+2. Each batch of independent stories gets its own git worktree
+3. Agent sessions run concurrently inside those worktrees
+4. Once a batch completes, changes are merged back in dependency order
+5. Merge conflicts are automatically rectified by re-running the conflicted story on the updated base
+
+**Config:**
+
+```json
+{
+  "execution": {
+    "maxParallelSessions": 4
+  }
+}
+```
+
+> Sequential mode (no `--parallel`) is the safe default. Use parallel for large feature sets with independent stories.
+
+---
+
+## Agents
+
+nax supports multiple coding agents. By default it uses Claude Code via the ACP protocol.
+
+```bash
+# List installed agents and their capabilities
+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 |
+
+**ACP protocol (default):**
+
+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.
+
+**Configuring agents:**
+
+```json
+{
+  "execution": {
+    "defaultAgent": "claude",
+    "protocol": "acp",
+    "fallbackOrder": ["claude", "codex", "opencode", "gemini"]
+  }
+}
+```
+
+**Force a specific agent at runtime:**
+
+```bash
+nax run -f my-feature --agent opencode
+```
+
+---
+
+## Monorepo Support
+
+nax supports monorepos with workspace-level and per-package configuration.
+
+### Setup
+
+```bash
+# Initialize nax at the repo root
+nax init
+
+# Scaffold per-package context for a specific package
+nax init --package packages/api
+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:
+
+```
+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
+```
+
+**Overridable fields per package:** `execution`, `review`, `acceptance`, `quality`, `context`
+
+```json
+// packages/api/nax/config.json
+{
+  "quality": {
+    "commands": {
+      "test": "turbo test --filter=@myapp/api",
+      "lint": "turbo lint --filter=@myapp/api"
+    }
+  }
+}
+```
+
+### Per-Package Stories
+
+In your `prd.json`, set `workdir` on each story to point to the package:
+
+```json
+{
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "Add auth endpoint",
+      "workdir": "packages/api",
+      "status": "pending"
+    }
+  ]
+}
+```
+
+nax will run the agent inside that package's directory and apply its config overrides automatically.
+
+### Workspace Detection
+
+When `nax plan` generates stories for a monorepo, it auto-discovers packages from:
+- `turbo.json` → `packages` field
+- `package.json` → `workspaces`
+- `pnpm-workspace.yaml` → `packages`
+- Existing `*/nax/context.md` files
+
+### Generate Agent Files for All Packages
+
+```bash
+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.
+
+---
+
 ## Hooks
 
 Integrate notifications, CI triggers, or custom scripts via lifecycle hooks.

package/dist/nax.js

@@ -3267,10 +3267,10 @@ Security-critical functions (authentication, cryptography, tokens, sessions, cre
 password hashing, access control) must be classified at MINIMUM "medium" complexity
 regardless of LOC count. These require at minimum "tdd-simple" test strategy.`, TEST_STRATEGY_GUIDE = `## Test Strategy Guide
 
-- test-after: Simple changes with well-understood behavior. Write tests after implementation.
-- tdd-simple: Medium complexity. Write key tests first, implement, then fill coverage.
-- three-session-tdd: Complex stories. Full TDD cycle with separate test-writer and implementer sessions.
-- three-session-tdd-lite: Expert/high-risk stories. Full TDD with additional verifier session.`, GROUPING_RULES = `## Grouping Rules
+- test-after: Simple changes with well-understood behavior. Write tests after implementation in a single session.
+- tdd-simple: Medium complexity. Write failing tests first, then implement to pass them \u2014 all in one session.
+- three-session-tdd: Complex stories. 3 sessions: (1) test-writer writes failing tests \u2014 no src/ changes allowed, (2) implementer makes them pass without modifying test files, (3) verifier confirms correctness.
+- three-session-tdd-lite: Expert/high-risk stories. 3 sessions: (1) test-writer writes failing tests and may create minimal src/ stubs for imports, (2) implementer makes tests pass and may add missing coverage or replace stubs, (3) verifier confirms correctness.`, GROUPING_RULES = `## Grouping Rules
 
 - Combine small, related tasks into a single "simple" or "medium" story.
 - Do NOT create separate stories for every single file or function unless complex.
@@ -18729,7 +18729,10 @@ describe("${options.featureName} - Acceptance Tests", () => {
 
 IMPORTANT: Output raw TypeScript code only. Do NOT use markdown code fences (\`\`\`typescript or \`\`\`). Start directly with the import statement.`;
   logger.info("acceptance", "Generating tests from PRD refined criteria", { count: refinedCriteria.length });
-  const rawOutput = await _generatorPRDDeps.adapter.complete(prompt, { config: options.config });
+  const rawOutput = await _generatorPRDDeps.adapter.complete(prompt, {
+    model: options.modelDef.model,
+    config: options.config
+  });
   const testCode = extractTestCode(rawOutput);
   const refinedJsonContent = JSON.stringify(refinedCriteria.map((c, i) => ({
     acId: `AC-${i + 1}`,
@@ -19170,6 +19173,8 @@ class SpawnAcpSession {
       "acpx",
       "--cwd",
       this.cwd,
+      "--format",
+      "json",
       ...this.permissionMode === "approve-all" ? ["--approve-all"] : [],
       "--model",
       this.model,
@@ -19742,7 +19747,11 @@ class AcpAgentAdapter {
       await client.start();
       let session = null;
       try {
-        session = await client.createSession({ agentName: this.name, permissionMode });
+        session = await client.createSession({
+          agentName: this.name,
+          permissionMode,
+          sessionName: _options?.sessionName
+        });
         let timeoutId;
         const timeoutPromise = new Promise((_, reject) => {
           timeoutId = setTimeout(() => reject(new Error(`complete() timed out after ${timeoutMs}ms`)), timeoutMs);
@@ -22241,7 +22250,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@nathapp/nax",
-    version: "0.49.0",
+    version: "0.49.3",
     description: "AI Coding Agent Orchestrator \u2014 loops until done",
     type: "module",
     bin: {
@@ -22314,8 +22323,8 @@ var init_version = __esm(() => {
   NAX_VERSION = package_default.version;
   NAX_COMMIT = (() => {
     try {
-      if (/^[0-9a-f]{6,10}$/.test("6a5bc7a"))
-        return "6a5bc7a";
+      if (/^[0-9a-f]{6,10}$/.test("30ff375"))
+        return "30ff375";
     } catch {}
     try {
       const result = Bun.spawnSync(["git", "rev-parse", "--short", "HEAD"], {
@@ -24348,6 +24357,8 @@ async function resolveCommand(check2, config2, executionConfig, workdir) {
 }
 async function runCheck(check2, command, workdir) {
   const startTime = Date.now();
+  const logger = getSafeLogger();
+  logger?.info("review", `Running ${check2} check`, { check: check2, command, workdir });
   try {
     const parts = command.split(/\s+/);
     const executable = parts[0];
@@ -24386,6 +24397,17 @@ async function runCheck(check2, command, workdir) {
     const stderr = await new Response(proc.stderr).text();
     const output = [stdout, stderr].filter(Boolean).join(`
 `);
+    if (exitCode !== 0) {
+      logger?.warn("review", `${check2} check failed`, {
+        check: check2,
+        command,
+        workdir,
+        exitCode,
+        output: output.slice(0, 2000)
+      });
+    } else {
+      logger?.debug("review", `${check2} check passed`, { check: check2, command, durationMs: Date.now() - startTime });
+    }
     return {
       check: check2,
       command,
@@ -24671,8 +24693,8 @@ async function recheckReview(ctx) {
   const { reviewStage: reviewStage2 } = await Promise.resolve().then(() => (init_review(), exports_review));
   if (!reviewStage2.enabled(ctx))
     return true;
-  const result = await reviewStage2.execute(ctx);
-  return result.action === "continue";
+  await reviewStage2.execute(ctx);
+  return ctx.reviewResult?.success === true;
 }
 function collectFailedChecks(ctx) {
   return (ctx.reviewResult?.checks ?? []).filter((c) => !c.success);
@@ -24784,11 +24806,18 @@ var init_autofix = __esm(() => {
       const lintFixCmd = effectiveConfig.quality.commands.lintFix;
       const formatFixCmd = effectiveConfig.quality.commands.formatFix;
       const effectiveWorkdir = ctx.story.workdir ? join18(ctx.workdir, ctx.story.workdir) : ctx.workdir;
-      if (lintFixCmd || formatFixCmd) {
+      const failedCheckNames = new Set((reviewResult.checks ?? []).filter((c) => !c.success).map((c) => c.check));
+      const hasLintFailure = failedCheckNames.has("lint");
+      logger.info("autofix", "Starting autofix", {
+        storyId: ctx.story.id,
+        failedChecks: [...failedCheckNames],
+        workdir: effectiveWorkdir
+      });
+      if (hasLintFailure && (lintFixCmd || formatFixCmd)) {
         if (lintFixCmd) {
           pipelineEventBus.emit({ type: "autofix:started", storyId: ctx.story.id, command: lintFixCmd });
           const lintResult = await _autofixDeps.runCommand(lintFixCmd, effectiveWorkdir);
-          logger.debug("autofix", `lintFix exit=${lintResult.exitCode}`, { storyId: ctx.story.id });
+          logger.debug("autofix", `lintFix exit=${lintResult.exitCode}`, { storyId: ctx.story.id, command: lintFixCmd });
           if (lintResult.exitCode !== 0) {
             logger.warn("autofix", "lintFix command failed \u2014 may not have fixed all issues", {
               storyId: ctx.story.id,
@@ -24799,7 +24828,10 @@ var init_autofix = __esm(() => {
         if (formatFixCmd) {
           pipelineEventBus.emit({ type: "autofix:started", storyId: ctx.story.id, command: formatFixCmd });
           const fmtResult = await _autofixDeps.runCommand(formatFixCmd, effectiveWorkdir);
-          logger.debug("autofix", `formatFix exit=${fmtResult.exitCode}`, { storyId: ctx.story.id });
+          logger.debug("autofix", `formatFix exit=${fmtResult.exitCode}`, {
+            storyId: ctx.story.id,
+            command: formatFixCmd
+          });
           if (fmtResult.exitCode !== 0) {
             logger.warn("autofix", "formatFix command failed \u2014 may not have fixed all issues", {
               storyId: ctx.story.id,
@@ -24810,11 +24842,12 @@ var init_autofix = __esm(() => {
         const recheckPassed = await _autofixDeps.recheckReview(ctx);
         pipelineEventBus.emit({ type: "autofix:completed", storyId: ctx.story.id, fixed: recheckPassed });
         if (recheckPassed) {
-          if (ctx.reviewResult)
-            ctx.reviewResult = { ...ctx.reviewResult, success: true };
           logger.info("autofix", "Mechanical autofix succeeded \u2014 retrying review", { storyId: ctx.story.id });
           return { action: "retry", fromStage: "review" };
         }
+        logger.info("autofix", "Mechanical autofix did not resolve all failures \u2014 proceeding to agent rectification", {
+          storyId: ctx.story.id
+        });
       }
       const agentFixed = await _autofixDeps.runAgentRectification(ctx);
       if (agentFixed) {
@@ -26178,7 +26211,9 @@ async function autoCommitIfDirty(workdir, stage, role, storyId) {
         return gitRoot;
       }
     })();
-    if (realWorkdir !== realGitRoot)
+    const isAtRoot = realWorkdir === realGitRoot;
+    const isSubdir = realGitRoot && realWorkdir.startsWith(`${realGitRoot}/`);
+    if (!isAtRoot && !isSubdir)
       return;
     const statusProc = _gitDeps.spawn(["git", "status", "--porcelain"], {
       cwd: workdir,
@@ -26195,7 +26230,8 @@ async function autoCommitIfDirty(workdir, stage, role, storyId) {
       dirtyFiles: statusOutput.trim().split(`
 `).length
     });
-    const addProc = _gitDeps.spawn(["git", "add", "-A"], { cwd: workdir, stdout: "pipe", stderr: "pipe" });
+    const addArgs = isSubdir ? ["git", "add", "."] : ["git", "add", "-A"];
+    const addProc = _gitDeps.spawn(addArgs, { cwd: workdir, stdout: "pipe", stderr: "pipe" });
     await addProc.exited;
     const commitProc = _gitDeps.spawn(["git", "commit", "-m", `chore(${storyId}): auto-commit after ${role} session`], {
       cwd: workdir,
@@ -29440,9 +29476,24 @@ async function runDecompose(story, prd, config2, _workdir, agentGetFn) {
   if (!agent) {
     throw new Error(`[decompose] Agent "${config2.autoMode.defaultAgent}" not found \u2014 cannot decompose`);
   }
+  const decomposeTier = naxDecompose?.model ?? "balanced";
+  let decomposeModel;
+  try {
+    const { resolveModel: resolveModel2 } = await Promise.resolve().then(() => (init_schema(), exports_schema));
+    const models = config2.models;
+    const entry = models[decomposeTier] ?? models.balanced;
+    if (entry)
+      decomposeModel = resolveModel2(entry).model;
+  } catch {}
+  const storySessionName = `nax-decompose-${story.id.toLowerCase()}`;
   const adapter = {
     async decompose(prompt) {
-      return agent.complete(prompt, { jsonMode: true, config: config2 });
+      return agent.complete(prompt, {
+        model: decomposeModel,
+        jsonMode: true,
+        config: config2,
+        sessionName: storySessionName
+      });
     }
   };
   return DecomposeBuilder.for(story).prd(prd).config(builderConfig).decompose(adapter);
@@ -29526,7 +29577,7 @@ var init_routing2 = __esm(() => {
         logger.debug("routing", ctx.routing.reasoning);
       }
       const decomposeConfig = ctx.config.decompose;
-      if (decomposeConfig) {
+      if (decomposeConfig && ctx.story.status !== "decomposed") {
         const acCount = ctx.story.acceptanceCriteria.length;
         const complexity = ctx.routing.complexity;
         const isOversized = acCount > decomposeConfig.maxAcceptanceCriteria && (complexity === "complex" || complexity === "expert");
@@ -34229,6 +34280,7 @@ async function handlePipelineFailure(ctx, pipelineResult) {
   const logger = getSafeLogger();
   let prd = ctx.prd;
   let prdDirty = false;
+  const costDelta = pipelineResult.context.agentResult?.estimatedCost || 0;
   switch (pipelineResult.finalAction) {
     case "pause":
       markStoryPaused(prd, ctx.story.id);
@@ -34295,7 +34347,7 @@ async function handlePipelineFailure(ctx, pipelineResult) {
       break;
     }
   }
-  return { prd, prdDirty };
+  return { prd, prdDirty, costDelta };
 }
 var init_pipeline_result_handler = __esm(() => {
   init_logger2();
@@ -34400,7 +34452,7 @@ async function runIteration(ctx, prd, selection, iterations, totalCost, allStory
   return {
     prd: r.prd,
     storiesCompletedDelta: 0,
-    costDelta: 0,
+    costDelta: r.costDelta,
     prdDirty: r.prdDirty,
     finalAction: pipelineResult.finalAction,
     reason: pipelineResult.reason
@@ -34438,7 +34490,7 @@ function buildPreviewRouting(story, config2) {
 function selectNextStories(prd, config2, batchPlan, currentBatchIndex, lastStoryId, useBatch) {
   if (useBatch && currentBatchIndex < batchPlan.length) {
     const batch = batchPlan[currentBatchIndex];
-    const storiesToExecute = batch.stories.filter((s) => !s.passes && s.status !== "passed" && s.status !== "skipped" && s.status !== "blocked" && s.status !== "failed" && s.status !== "paused");
+    const storiesToExecute = batch.stories.filter((s) => !s.passes && s.status !== "passed" && s.status !== "skipped" && s.status !== "blocked" && s.status !== "failed" && s.status !== "paused" && s.status !== "decomposed");
     if (storiesToExecute.length === 0) {
       return { selection: null, nextBatchIndex: currentBatchIndex + 1 };
     }
@@ -67305,7 +67357,16 @@ async function planCommand(workdir, config2, options) {
     const cliAdapter = _deps2.getAgent(agentName);
     if (!cliAdapter)
       throw new Error(`[plan] No agent adapter found for '${agentName}'`);
-    rawResponse = await cliAdapter.complete(prompt, { jsonMode: true, workdir, config: config2 });
+    let autoModel;
+    try {
+      const planTier = config2?.plan?.model ?? "balanced";
+      const { resolveModel: resolveModel2 } = await Promise.resolve().then(() => (init_schema(), exports_schema));
+      const models = config2?.models;
+      const entry = models?.[planTier] ?? models?.balanced;
+      if (entry)
+        autoModel = resolveModel2(entry).model;
+    } catch {}
+    rawResponse = await cliAdapter.complete(prompt, { model: autoModel, jsonMode: true, workdir, config: config2 });
     try {
       const envelope = JSON.parse(rawResponse);
       if (envelope?.type === "result" && typeof envelope?.result === "string") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.49.0",
+  "version": "0.49.3",
   "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {

package/src/acceptance/generator.ts

@@ -108,7 +108,10 @@ IMPORTANT: Output raw TypeScript code only. Do NOT use markdown code fences (\`\
 
   logger.info("acceptance", "Generating tests from PRD refined criteria", { count: refinedCriteria.length });
 
-  const rawOutput = await _generatorPRDDeps.adapter.complete(prompt, { config: options.config });
+  const rawOutput = await _generatorPRDDeps.adapter.complete(prompt, {
+    model: options.modelDef.model,
+    config: options.config,
+  });
   const testCode = extractTestCode(rawOutput);
 
   const refinedJsonContent = JSON.stringify(

package/src/agents/acp/adapter.ts

@@ -694,8 +694,13 @@ export class AcpAgentAdapter implements AgentAdapter {
 
       let session: AcpSession | null = null;
       try {
-        // complete() is one-shot — ephemeral session, no session name, no sidecar
-        session = await client.createSession({ agentName: this.name, permissionMode });
+        // complete() is one-shot — ephemeral session, no sidecar
+        // Use caller-provided sessionName if available (aids tracing), otherwise timestamp-based
+        session = await client.createSession({
+          agentName: this.name,
+          permissionMode,
+          sessionName: _options?.sessionName,
+        });
 
         // Enforce timeout via Promise.race — session.prompt() can hang indefinitely
         let timeoutId: ReturnType<typeof setTimeout> | undefined;

package/src/agents/acp/parser.ts

@@ -70,7 +70,7 @@ export function parseAcpxJsonOutput(rawOutput: string): {
           }
         }
 
-        // Final result with token breakdown (camelCase from acpx)
+        // Final result with token breakdown
         if (event.id !== undefined && event.result && typeof event.result === "object") {
           const result = event.result as Record<string, unknown>;
 

package/src/agents/acp/spawn-client.ts

@@ -135,6 +135,8 @@ class SpawnAcpSession implements AcpSession {
       "acpx",
       "--cwd",
       this.cwd,
+      "--format",
+      "json",
       ...(this.permissionMode === "approve-all" ? ["--approve-all"] : []),
       "--model",
       this.model,

package/src/agents/types.ts

@@ -127,6 +127,12 @@ export interface CompleteOptions {
    * Pass when available so complete() honours permissionProfile / dangerouslySkipPermissions.
    */
   config?: NaxConfig;
+  /**
+   * Named session to use for this completion call.
+   * If omitted, a timestamp-based ephemeral session name is generated.
+   * Pass a meaningful name (e.g. "nax-decompose-us-001") to aid debugging.
+   */
+  sessionName?: string;
 }
 
 /**

package/src/cli/plan.ts

@@ -138,7 +138,17 @@ export async function planCommand(workdir: string, config: NaxConfig, options: P
     const prompt = buildPlanningPrompt(specContent, codebaseContext, undefined, relativePackages, packageDetails);
     const cliAdapter = _deps.getAgent(agentName);
     if (!cliAdapter) throw new Error(`[plan] No agent adapter found for '${agentName}'`);
-    rawResponse = await cliAdapter.complete(prompt, { jsonMode: true, workdir, config });
+    let autoModel: string | undefined;
+    try {
+      const planTier = config?.plan?.model ?? "balanced";
+      const { resolveModel } = await import("../config/schema");
+      const models = config?.models as Record<string, unknown> | undefined;
+      const entry = models?.[planTier] ?? models?.balanced;
+      if (entry) autoModel = resolveModel(entry as Parameters<typeof resolveModel>[0]).model;
+    } catch {
+      // fall through — complete() will use its own fallback
+    }
+    rawResponse = await cliAdapter.complete(prompt, { model: autoModel, jsonMode: true, workdir, config });
     // CLI adapter returns {"type":"result","result":"..."} envelope — unwrap it
     try {
       const envelope = JSON.parse(rawResponse) as Record<string, unknown>;

package/src/config/test-strategy.ts

@@ -53,10 +53,10 @@ regardless of LOC count. These require at minimum "tdd-simple" test strategy.`;
 
 export const TEST_STRATEGY_GUIDE = `## Test Strategy Guide
 
-- test-after: Simple changes with well-understood behavior. Write tests after implementation.
-- tdd-simple: Medium complexity. Write key tests first, implement, then fill coverage.
-- three-session-tdd: Complex stories. Full TDD cycle with separate test-writer and implementer sessions.
-- three-session-tdd-lite: Expert/high-risk stories. Full TDD with additional verifier session.`;
+- test-after: Simple changes with well-understood behavior. Write tests after implementation in a single session.
+- tdd-simple: Medium complexity. Write failing tests first, then implement to pass them — all in one session.
+- three-session-tdd: Complex stories. 3 sessions: (1) test-writer writes failing tests — no src/ changes allowed, (2) implementer makes them pass without modifying test files, (3) verifier confirms correctness.
+- three-session-tdd-lite: Expert/high-risk stories. 3 sessions: (1) test-writer writes failing tests and may create minimal src/ stubs for imports, (2) implementer makes tests pass and may add missing coverage or replace stubs, (3) verifier confirms correctness.`;
 
 export const GROUPING_RULES = `## Grouping Rules
 

package/src/execution/iteration-runner.ts

@@ -142,7 +142,7 @@ export async function runIteration(
   return {
     prd: r.prd,
     storiesCompletedDelta: 0,
-    costDelta: 0,
+    costDelta: r.costDelta,
     prdDirty: r.prdDirty,
     finalAction: pipelineResult.finalAction,
     reason: pipelineResult.reason,

package/src/execution/pipeline-result-handler.ts

@@ -102,6 +102,7 @@ export async function handlePipelineSuccess(
 export interface PipelineFailureResult {
   prd: PRD;
   prdDirty: boolean;
+  costDelta: number;
 }
 
 export async function handlePipelineFailure(
@@ -111,6 +112,8 @@ export async function handlePipelineFailure(
   const logger = getSafeLogger();
   let prd = ctx.prd;
   let prdDirty = false;
+  // Always capture cost even for failed stories — agent ran and spent tokens
+  const costDelta = pipelineResult.context.agentResult?.estimatedCost || 0;
 
   switch (pipelineResult.finalAction) {
     case "pause":
@@ -185,5 +188,5 @@ export async function handlePipelineFailure(
     }
   }
 
-  return { prd, prdDirty };
+  return { prd, prdDirty, costDelta };
 }

package/src/execution/story-selector.ts

@@ -39,7 +39,8 @@ export function selectNextStories(
         s.status !== "skipped" &&
         s.status !== "blocked" &&
         s.status !== "failed" &&
-        s.status !== "paused",
+        s.status !== "paused" &&
+        s.status !== "decomposed",
     );
 
     if (storiesToExecute.length === 0) {

package/src/pipeline/stages/autofix.ts

@@ -61,12 +61,22 @@ export const autofixStage: PipelineStage = {
     // Effective workdir for running commands (scoped to package if monorepo)
     const effectiveWorkdir = ctx.story.workdir ? join(ctx.workdir, ctx.story.workdir) : ctx.workdir;
 
-    // Phase 1: Mechanical fix (if commands are configured)
-    if (lintFixCmd || formatFixCmd) {
+    // Identify which checks failed
+    const failedCheckNames = new Set((reviewResult.checks ?? []).filter((c) => !c.success).map((c) => c.check));
+    const hasLintFailure = failedCheckNames.has("lint");
+
+    logger.info("autofix", "Starting autofix", {
+      storyId: ctx.story.id,
+      failedChecks: [...failedCheckNames],
+      workdir: effectiveWorkdir,
+    });
+
+    // Phase 1: Mechanical fix — only for lint failures (lintFix/formatFix cannot fix typecheck errors)
+    if (hasLintFailure && (lintFixCmd || formatFixCmd)) {
       if (lintFixCmd) {
         pipelineEventBus.emit({ type: "autofix:started", storyId: ctx.story.id, command: lintFixCmd });
         const lintResult = await _autofixDeps.runCommand(lintFixCmd, effectiveWorkdir);
-        logger.debug("autofix", `lintFix exit=${lintResult.exitCode}`, { storyId: ctx.story.id });
+        logger.debug("autofix", `lintFix exit=${lintResult.exitCode}`, { storyId: ctx.story.id, command: lintFixCmd });
         if (lintResult.exitCode !== 0) {
           logger.warn("autofix", "lintFix command failed — may not have fixed all issues", {
             storyId: ctx.story.id,
@@ -78,7 +88,10 @@ export const autofixStage: PipelineStage = {
       if (formatFixCmd) {
         pipelineEventBus.emit({ type: "autofix:started", storyId: ctx.story.id, command: formatFixCmd });
         const fmtResult = await _autofixDeps.runCommand(formatFixCmd, effectiveWorkdir);
-        logger.debug("autofix", `formatFix exit=${fmtResult.exitCode}`, { storyId: ctx.story.id });
+        logger.debug("autofix", `formatFix exit=${fmtResult.exitCode}`, {
+          storyId: ctx.story.id,
+          command: formatFixCmd,
+        });
         if (fmtResult.exitCode !== 0) {
           logger.warn("autofix", "formatFix command failed — may not have fixed all issues", {
             storyId: ctx.story.id,
@@ -91,10 +104,13 @@ export const autofixStage: PipelineStage = {
       pipelineEventBus.emit({ type: "autofix:completed", storyId: ctx.story.id, fixed: recheckPassed });
 
       if (recheckPassed) {
-        if (ctx.reviewResult) ctx.reviewResult = { ...ctx.reviewResult, success: true };
         logger.info("autofix", "Mechanical autofix succeeded — retrying review", { storyId: ctx.story.id });
         return { action: "retry", fromStage: "review" };
       }
+
+      logger.info("autofix", "Mechanical autofix did not resolve all failures — proceeding to agent rectification", {
+        storyId: ctx.story.id,
+      });
     }
 
     // Phase 2: Agent rectification — spawn agent with review error context
@@ -134,8 +150,11 @@ async function recheckReview(ctx: PipelineContext): Promise<boolean> {
   // Import reviewStage lazily to avoid circular deps
   const { reviewStage } = await import("./review");
   if (!reviewStage.enabled(ctx)) return true;
-  const result = await reviewStage.execute(ctx);
-  return result.action === "continue";
+  // reviewStage.execute updates ctx.reviewResult in place.
+  // We cannot use result.action here because review returns "continue" for BOTH
+  // pass and built-in-check-failure (to hand off to autofix). Check success directly.
+  await reviewStage.execute(ctx);
+  return ctx.reviewResult?.success === true;
 }
 
 function collectFailedChecks(ctx: PipelineContext): ReviewCheckResult[] {

package/src/pipeline/stages/routing.ts

@@ -65,9 +65,28 @@ async function runDecompose(
   if (!agent) {
     throw new Error(`[decompose] Agent "${config.autoMode.defaultAgent}" not found — cannot decompose`);
   }
+
+  // Resolve decompose model: config.decompose.model tier → actual model string
+  const decomposeTier = naxDecompose?.model ?? "balanced";
+  let decomposeModel: string | undefined;
+  try {
+    const { resolveModel } = await import("../../config/schema");
+    const models = config.models as Record<string, unknown>;
+    const entry = models[decomposeTier] ?? models.balanced;
+    if (entry) decomposeModel = resolveModel(entry as Parameters<typeof resolveModel>[0]).model;
+  } catch {
+    // resolveModel can throw on malformed entries — fall through to let complete() handle it
+  }
+
+  const storySessionName = `nax-decompose-${story.id.toLowerCase()}`;
   const adapter = {
     async decompose(prompt: string): Promise<string> {
-      return agent.complete(prompt, { jsonMode: true, config });
+      return agent.complete(prompt, {
+        model: decomposeModel,
+        jsonMode: true,
+        config,
+        sessionName: storySessionName,
+      });
     },
   };
 
@@ -177,7 +196,7 @@ export const routingStage: PipelineStage = {
 
     // SD-004: Oversized story detection and decomposition
     const decomposeConfig = ctx.config.decompose;
-    if (decomposeConfig) {
+    if (decomposeConfig && ctx.story.status !== "decomposed") {
       const acCount = ctx.story.acceptanceCriteria.length;
       const complexity = ctx.routing.complexity;
       const isOversized =

package/src/review/runner.ts

@@ -99,6 +99,9 @@ const SIGKILL_GRACE_PERIOD_MS = 5_000;
  */
 async function runCheck(check: ReviewCheckName, command: string, workdir: string): Promise<ReviewCheckResult> {
   const startTime = Date.now();
+  const logger = getSafeLogger();
+
+  logger?.info("review", `Running ${check} check`, { check, command, workdir });
 
   try {
     // Parse command into executable and args
@@ -152,6 +155,18 @@ async function runCheck(check: ReviewCheckName, command: string, workdir: string
     const stderr = await new Response(proc.stderr).text();
     const output = [stdout, stderr].filter(Boolean).join("\n");
 
+    if (exitCode !== 0) {
+      logger?.warn("review", `${check} check failed`, {
+        check,
+        command,
+        workdir,
+        exitCode,
+        output: output.slice(0, 2000),
+      });
+    } else {
+      logger?.debug("review", `${check} check passed`, { check, command, durationMs: Date.now() - startTime });
+    }
+
     return {
       check,
       command,

package/src/utils/git.ts

@@ -181,7 +181,11 @@ export async function autoCommitIfDirty(workdir: string, stage: string, role: st
         return gitRoot;
       }
     })();
-    if (realWorkdir !== realGitRoot) return;
+    // Allow: workdir IS the git root, or workdir is a subdirectory (monorepo package)
+    // Reject: workdir has no git repo at all (realGitRoot would be empty/error)
+    const isAtRoot = realWorkdir === realGitRoot;
+    const isSubdir = realGitRoot && realWorkdir.startsWith(`${realGitRoot}/`);
+    if (!isAtRoot && !isSubdir) return;
 
     const statusProc = _gitDeps.spawn(["git", "status", "--porcelain"], {
       cwd: workdir,
@@ -199,7 +203,11 @@ export async function autoCommitIfDirty(workdir: string, stage: string, role: st
       dirtyFiles: statusOutput.trim().split("\n").length,
     });
 
-    const addProc = _gitDeps.spawn(["git", "add", "-A"], { cwd: workdir, stdout: "pipe", stderr: "pipe" });
+    // Use "git add ." when workdir is a monorepo package subdir — only stages files under
+    // that package, preventing accidental cross-package commits.
+    // Use "git add -A" at repo root to capture renames/deletions across the full tree.
+    const addArgs = isSubdir ? ["git", "add", "."] : ["git", "add", "-A"];
+    const addProc = _gitDeps.spawn(addArgs, { cwd: workdir, stdout: "pipe", stderr: "pipe" });
     await addProc.exited;
 
     const commitProc = _gitDeps.spawn(["git", "commit", "-m", `chore(${storyId}): auto-commit after ${role} session`], {