@nathapp/nax 0.91.8-canary.3 → 0.91.8-canary.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/README.md +22 -42
  3. package/dist/nax.js +79465 -104545
  4. package/package.json +2 -2
package/CHANGELOG.md CHANGED
@@ -10,6 +10,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
10
10
 
11
11
  ## Unreleased
12
12
 
13
+ ### Removed
14
+
15
+ - **Pipeline mode (C1).** Workflow mode is the only execution mode. Removed with pipeline mode: the eight-stage
16
+ story pipeline and its acceptance, TDD-session, autofix, mutation-check and prompt-optimizer stages; story
17
+ worktree isolation; `nax accept` and `nax prompts`; the `IPromptOptimizer` plugin extension point (a plugin
18
+ that still provides an optimizer fails to load with a named error). `execution.mode: "workflow"` stays
19
+ accepted.
20
+ - **What a config or command that still asks for it gets:**
21
+ - `execution.mode: "pipeline"` or `execution.maxIterations` fails config load with
22
+ `CONFIG_PIPELINE_MODE_REMOVED` (`Invalid configuration in <source> — pipeline mode was removed: <keys>.`),
23
+ naming each key and the fix.
24
+ - `nax run -m/--max-iterations`, `--parallel` and `--no-batch`, `nax accept` and `nax prompts` exit with an
25
+ error saying they were removed.
26
+ - A key that only configured pipeline mode, or that nothing read, still loads: it is dropped before
27
+ validation with one warning per key or section,
28
+ `Config key "<path>" has been removed — <hint>. Remove it from your config.` The keys are listed in
29
+ `docs/guides/configuration.md` (Removed keys) and include the `acceptance` and `optimizer` sections,
30
+ `prompts.overrides`, `hooks` (lifecycle hooks are read from `.nax/hooks.json`), `execution.storyIsolation`,
31
+ `execution.worktreeDependencies`, `execution.flakeDetection`, `execution.mutationCheck`, most
32
+ `execution.rectification.*` leaves, `tdd.sessionTiers` and the other TDD-session keys, `quality.autofix`,
33
+ `quality.typecheckOutput` and the `lintFix`/`formatFix` commands.
34
+ - An old cost ledger, prompt audit or `prd.json` that names a removed role, stage or failure category still
35
+ loads; the value is shown as recorded.
36
+
13
37
  ### Fixed
14
38
 
15
39
  - **Run log, review round 2 (nax#2491).** The repeated-tool-error line releases its per-run ledger of reported
package/README.md CHANGED
@@ -59,9 +59,9 @@ See the [documentation index](https://github.com/nathapp-io/nax/blob/main/docs/R
59
59
 
60
60
  ## How It Works
61
61
 
62
- nax has two execution modes. **Workflow mode** is the default (`execution.mode: "workflow"`). The **pipeline** mode (`execution.mode: "pipeline"`) is deprecated: it still runs, warns at config load, and will be removed in a future release.
62
+ nax has one execution mode, **workflow** (`execution.mode: "workflow"`). `execution.mode: "pipeline"` is rejected at config load.
63
63
 
64
- ### Workflow mode (default)
64
+ ### Workflow mode
65
65
 
66
66
  ```
67
67
  story: implement → gates → full suite → story review → fix rounds → residual ruling
@@ -77,14 +77,10 @@ feature: repo gates → branch review → branch fix → re-review → adjudicat
77
77
  7. **Feature workflow** — after the last story: repo gates, one whole-branch review, up to `workflow.maxBranchFixRounds` (default 2) fix rounds each with a scoped re-review, adjudication, final gates, and up to `workflow.finalGateRepairRounds` (default 1) repair passes
78
78
  8. **Publish** — `workflow.publish` (`pr` by default) commits the ledger, pushes, opens or finds a draft PR, waits for CI, and promotes the draft when the deterministic readiness checks pass
79
79
 
80
- Stories run one at a time. `--parallel` and story batching are ignored in workflow mode.
80
+ Stories run one at a time. `--parallel` and `-m/--max-iterations` fail with a removed message.
81
81
 
82
82
  See [Workflow Mode](https://github.com/nathapp-io/nax/blob/main/docs/guides/workflow-mode.md) for the full loop, end states, publishing modes and config reference, and [ADR-034](https://github.com/nathapp-io/nax/blob/main/docs/adr/ADR-034-workflow-execution-mode.md) for the design.
83
83
 
84
- ### Pipeline mode (deprecated)
85
-
86
- Selected with `execution.mode: "pipeline"`. Each story runs through a staged pipeline: acceptance setup, routing, context, execution, verify, review (semantic and adversarial), escalation, and a regression gate after all stories pass. Pipeline mode is frozen; no new features are added to it.
87
-
88
84
  ---
89
85
 
90
86
  ## CLI Reference
@@ -105,11 +101,9 @@ Selected with `execution.mode: "pipeline"`. Each story runs through a staged pip
105
101
  | [`nax logs`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-logs) | Stream or query run logs |
106
102
  | [`nax runs`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-runs) | List recorded run metadata (`nax runs show <run-id>`) |
107
103
  | `nax replay` | Reconstruct a post-mortem timeline for a previous run |
108
- | `nax accept` | Override failed acceptance criteria (pipeline mode; workflow mode does not run acceptance tests) |
109
104
  | [`nax unlock`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-unlock) | Release a stale lock from a crashed nax process |
110
105
  | [`nax doctor`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md) | Diagnose the nax installation and environment |
111
106
  | [`nax generate`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-generate) | Generate agent context files (`CLAUDE.md`, `AGENTS.md`, …) from `.nax/context.md` |
112
- | [`nax prompts`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-prompts--f-name) | Assemble or initialize prompts |
113
107
  | `nax context` | Inspect context-engine artifacts and feature fragments |
114
108
  | `nax rules` | Lint, export, or migrate the canonical rules store (`.nax/rules/`) |
115
109
  | `nax detect` | Detect test-file patterns and optionally persist them |
@@ -138,19 +132,16 @@ For full flag details, see the [CLI Reference](https://github.com/nathapp-io/nax
138
132
  ```json
139
133
  {
140
134
  "execution": {
141
- "mode": "workflow", // "workflow" (default) | "pipeline" (deprecated)
142
- "maxIterations": 20, // Note: `nax run -m <n>` overrides this only when the flag is passed
135
+ "mode": "workflow", // only "workflow" is accepted; "pipeline" is rejected
143
136
  "costLimit": 30, // USD; past it, the run stops its loops and publishes a draft
144
137
  "permissionProfile": "unrestricted", // "unrestricted" | "safe" | "scoped"
145
- "storyIsolation": "shared", // "shared" | "worktree" (workflow mode forces "shared")
146
138
  "bashApproval": "raw", // "raw" | "gated" | "escalate" — how agent Bash commands are adjudicated
147
139
  "sandbox": {
148
140
  "enabled": true, // OS sandbox around agent-authored Bash / Exec commands (on by default)
149
141
  "network": { "allowedDomains": ["registry.npmjs.org"] } // Omit for unrestricted, [] for no network
150
142
  },
151
143
  "commandInterceptor": {
152
- "provider": "rtk", // Token-reducing proxy for the Git tool
153
- "enabled": true, // Off by default — opt in per project
144
+ "enabled": true, // Token-reducing proxy (rtk) for the Git tool; off by default — opt in per project
154
145
  "git": { "verbs": ["log", "diff"] } // Only these subcommands are rewritten
155
146
  }
156
147
  },
@@ -191,11 +182,11 @@ For full flag details, see the [CLI Reference](https://github.com/nathapp-io/nax
191
182
  }
192
183
  ```
193
184
 
194
- The `execution.mode` default is `"workflow"`. Setting `"pipeline"` loads with a deprecation warning. In workflow mode the `workflow` block governs the loops; the pipeline-only keys (`acceptance`, `tdd`, `execution.regressionGate`) are not read by the workflow story loop. See [Workflow Mode](https://github.com/nathapp-io/nax/blob/main/docs/guides/workflow-mode.md) for the complete `workflow` reference.
185
+ The `execution.mode` default is `"workflow"`; setting `"pipeline"` is rejected at load. The `workflow` block governs the loops. Keys that belonged to pipeline mode are warned about and stripped at load. See [Workflow Mode](https://github.com/nathapp-io/nax/blob/main/docs/guides/workflow-mode.md) for the complete `workflow` reference.
195
186
 
196
187
  `mcp` attaches external Model Context Protocol (MCP) servers as tool providers — nax is a client only, never an MCP server. The server id is the tool-name namespace: the `codebase-memory` server advertises its tools as `codebase-memory__search_graph`, `codebase-memory__trace_path`, and so on. Before any of those tools are grantable, run `nax mcp lock` at the project root: it connects every enabled server once, pins the advertised tool surface (name + input-schema hash) to `.nax/mcp-lock.json`, and that lockfile is committed like `bun.lock`. `stages` is the attachment control — a server's tools attach only to the listed pipeline stages, and an empty list attaches nowhere. MCP tool reach follows the permission profile: `unrestricted` advertises every attached server's tools, `scoped` only what the stage's `Mcp(...)` rules admit, and `safe` none at all. `allowedTools` narrows which locked tools are grantable; omitted means every locked tool is.
197
188
 
198
- `execution.commandInterceptor` rewrites the `Git` tool's argv through `rtk` so `log` and `diff` output reaches the model compressed. It is confined to the Git site: user-authored `quality.commands` and `acceptance.command` are never wrapped. It fails open — if the `rtk` binary is missing the call runs as plain git.
189
+ `execution.commandInterceptor` rewrites the `Git` tool's argv through `rtk` so `log` and `diff` output reaches the model compressed. It is confined to the Git site: user-authored `quality.commands` are never wrapped. It fails open — if the `rtk` binary is missing the call runs as plain git.
199
190
 
200
191
  **Both features are native-agent only.** An ACP agent (`claude`, `codex`, `opencode`, `gemini`, `pi`) brings its own tools, so nax's `Git` tool is never invoked and no MCP tool is advertised. A project on `"protocol": "acp"` can hold a complete, valid config for both and get zero effect, with no error. The built-in defaults (`agent.protocol: "hybrid"`, `agent.default: "native"`) let both take effect once configured (the interceptor itself is off by default); a config that switches to an ACP agent does not.
201
192
 
@@ -215,7 +206,7 @@ See [Sandbox & Command Safety](https://github.com/nathapp-io/nax/blob/main/docs/
215
206
 
216
207
  ### Project trust
217
208
 
218
- nax runs repository-controlled code — project plugins, context plugin providers, hooks, MCP servers and the quality / test / acceptance / setup commands — unsandboxed on the host. Before a gated command (`nax run`, `nax plan`, `nax mcp lock`, …) acts on a project, that project's folder must be trusted, and a refusal exits 2 with `run: nax trust add <root>`.
209
+ nax runs repository-controlled code — project plugins, context plugin providers, hooks, MCP servers and the quality / test / setup commands — unsandboxed on the host. Before a gated command (`nax run`, `nax plan`, `nax mcp lock`, …) acts on a project, that project's folder must be trusted, and a refusal exits 2 with `run: nax trust add <root>`.
219
210
 
220
211
  ```bash
221
212
  nax trust add "$PWD" # trust this checkout (asks for confirmation)
@@ -227,19 +218,19 @@ Trust is hierarchical and stored once per machine (`~/.nax/trust.json`): an entr
227
218
 
228
219
  See [`nax trust`](https://github.com/nathapp-io/nax/blob/main/docs/guides/cli-reference.md#nax-trust) for the full surface.
229
220
 
230
- ### Test Strategies (pipeline mode)
221
+ ### Test Strategies
231
222
 
232
- In pipeline mode, each story gets a test strategy. `tdd.strategy` (default `"auto"`) selects how strategies are chosen: `auto` picks per story based on complexity and content — security-critical stories always get `three-session-tdd` regardless of complexity. The strategy values are:
223
+ Each story in `prd.json` carries a `testStrategy` label assigned at plan time. `tdd.strategy` (default `"auto"`) selects how strategies are chosen: `auto` picks per story based on complexity and content, and security-critical stories always get `three-session-tdd` regardless of complexity. The strategy values are:
233
224
 
234
- | Strategy | Sessions | When to use |
235
- |:---------|:---------|:------------|
236
- | `three-session-tdd` | 3 | Expert stories and security-critical code (auth, tokens, RBAC) — strict isolation: test-writer cannot touch `src/`, implementer cannot touch tests |
237
- | `three-session-tdd-lite` | 3 | Complex stories — relaxed isolation: test-writer may add minimal `src/` stubs |
238
- | `tdd-simple` | 1 | Simple and medium stories — single session, TDD discipline (red → green → refactor) |
239
- | `test-after` | 1 | Exploratory / prototyping — implement first, add tests after |
240
- | `no-test` | 0 | Config-only, docs, CI, dependency bumps — requires `noTestJustification` |
225
+ | Strategy | When to use |
226
+ |:---------|:------------|
227
+ | `three-session-tdd` | Expert stories and security-critical code (auth, tokens, RBAC) |
228
+ | `three-session-tdd-lite` | Complex stories |
229
+ | `tdd-simple` | Simple and medium stories |
230
+ | `test-after` | Exploratory / prototyping — implement first, add tests after |
231
+ | `no-test` | Config-only, docs, CI, dependency bumps — requires `noTestJustification` |
241
232
 
242
- Workflow mode does not read these strategies: the implementer writes its own tests in one session, and the gates decide the result. See [Test Strategies Guide](https://github.com/nathapp-io/nax/blob/main/docs/guides/test-strategies.md) for the pipeline routing decision tree and security override rules.
233
+ Workflow mode does not read these strategies: the implementer writes its own tests in one session, and the gates decide the result. See [Test Strategies Guide](https://github.com/nathapp-io/nax/blob/main/docs/guides/test-strategies.md) for the routing decision tree and security override rules.
243
234
 
244
235
  ### Story Decomposition
245
236
 
@@ -247,22 +238,12 @@ An oversized story is split into smaller sub-stories with `nax plan -f <feature>
247
238
 
248
239
  See [Story Decomposition Guide](https://github.com/nathapp-io/nax/blob/main/docs/guides/decomposition.md).
249
240
 
250
- ### Regression Gate (pipeline mode)
241
+ ### Regression Gate
251
242
 
252
- In pipeline mode, after all stories pass, nax runs the full test suite once. If it fails, nax maps each failing test file back to the story that introduced it and runs a targeted rectification cycle for that story. A suite timeout is accepted as a pass by default (`execution.regressionGate.acceptOnTimeout`). If failures remain, the affected stories are marked `regression-failed`, the run status becomes `failed`, and the `on-final-regression-fail` hook fires.
253
-
254
- In workflow mode the equivalent checks are the `full-suite` gate in each story and the `final-gates` step of the feature workflow.
243
+ In workflow mode the full-suite checks are the `full-suite` gate in each story and the `final-gates` step of the feature workflow. `execution.regressionGate.timeoutSeconds` bounds the full-suite run. `acceptOnTimeout` only changes the status label (`passed-on-timeout` instead of `timeout`); either way a timed-out suite is a red gate in workflow mode.
255
244
 
256
245
  See [Regression Gate Guide](https://github.com/nathapp-io/nax/blob/main/docs/guides/regression-gate.md).
257
246
 
258
- ### Parallel & Isolated Execution
259
-
260
- Parallel execution is a pipeline-mode feature. With `--parallel <n>` in pipeline mode, nax runs up to `n` stories whose dependencies are already satisfied at the same time, each in its own git worktree (`0` = auto, based on CPU cores). Both modes run the regression gate once at the end; only sequential runs attribute a regression to a story and rectify it — in parallel mode it is reported for a human. Workflow mode ignores `--parallel` and runs stories one at a time.
261
-
262
- Even in sequential pipeline mode, stories can be isolated in per-story git worktrees (`execution.storyIsolation: "worktree"`) to prevent cross-story state leakage. Workflow mode forces `storyIsolation` to `shared`.
263
-
264
- See [Parallel Execution Guide](https://github.com/nathapp-io/nax/blob/main/docs/guides/parallel-execution.md).
265
-
266
247
  ### Monorepo Support
267
248
 
268
249
  Per-package context files, per-package test commands, and per-story working directories are supported. Initialize with `nax init --package packages/api`. Package config files live at `.nax/mono/packages/<pkg>/config.json`.
@@ -271,13 +252,13 @@ See [Monorepo Guide](https://github.com/nathapp-io/nax/blob/main/docs/guides/mon
271
252
 
272
253
  ### Hooks
273
254
 
274
- Lifecycle hooks, defined in `.nax/hooks.json` (project) and `~/.nax/hooks.json` (global) — not in `config.json` — fire at key points (`on-start`, `on-story-complete`, `on-all-stories-complete`, `on-workflow-start`, `on-workflow-step`, `on-workflow-publish`, `on-complete`, `on-final-regression-fail`, and more). Use them to trigger deployments, send notifications, or integrate with external systems.
255
+ Lifecycle hooks, defined in `.nax/hooks.json` (project) and `~/.nax/hooks.json` (global) — not in `config.json` — fire at key points (`on-start`, `on-story-complete`, `on-all-stories-complete`, `on-workflow-start`, `on-workflow-step`, `on-workflow-publish`, `on-complete`, and more). Use them to trigger deployments, send notifications, or integrate with external systems.
275
256
 
276
257
  See [Hooks Guide](https://github.com/nathapp-io/nax/blob/main/docs/guides/hooks.md).
277
258
 
278
259
  ### Plugins
279
260
 
280
- Extensible plugin architecture for prompt optimization, custom routing, code review, and reporting. Plugins live in `.nax/plugins/` (project) or `~/.nax/plugins/` (global). Post-run action plugins (e.g. auto-PR creation) can implement `IPostRunAction` for results-aware post-completion workflows.
261
+ Extensible plugin architecture for custom routing, code review, and reporting. Plugins live in `.nax/plugins/` (project) or `~/.nax/plugins/` (global). Post-run action plugins (e.g. auto-PR creation) can implement `IPostRunAction` for results-aware post-completion workflows.
281
262
 
282
263
  See [Plugin System](https://github.com/nathapp-io/nax/blob/main/docs/architecture/subsystems.md#23-plugin-system).
283
264
 
@@ -309,7 +290,6 @@ See [Agents Guide](https://github.com/nathapp-io/nax/blob/main/docs/guides/agent
309
290
  | HOME env warning | Set HOME to an absolute path — nax warns if it contains `~` |
310
291
  | Monorepo packages misclassified | Ensure `.nax/mono/packages/<pkg>/config.json` is set up per package |
311
292
  | Agent Bash refused because the sandbox is unavailable | The OS sandbox is on by default and `raw` Bash requires it. Run `nax sandbox probe` to see why it cannot enforce on this machine, then fix the environment, set the stage's `bashApproval` to `gated`/`escalate`, or set `execution.sandbox.enabled: false` |
312
- | Acceptance tests regenerating every run (pipeline mode) | Check `acceptance-meta.json` — stale fingerprints indicate outdated story context. Workflow mode does not run acceptance tests |
313
293
 
314
294
  See the [Troubleshooting Guide](https://github.com/nathapp-io/nax/blob/main/docs/guides/troubleshooting.md) for more.
315
295