@nathapp/nax 0.91.8-canary.4 → 0.91.8-canary.6
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.
- package/CHANGELOG.md +24 -0
- package/README.md +22 -42
- package/dist/nax.js +84430 -113860
- package/package.json +7 -7
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
|
|
62
|
+
nax has one execution mode, **workflow** (`execution.mode: "workflow"`). `execution.mode: "pipeline"` is rejected at config load.
|
|
63
63
|
|
|
64
|
-
### Workflow mode
|
|
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
|
|
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"
|
|
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
|
-
"
|
|
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"
|
|
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`
|
|
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 /
|
|
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
|
|
221
|
+
### Test Strategies
|
|
231
222
|
|
|
232
|
-
|
|
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 |
|
|
235
|
-
|
|
236
|
-
| `three-session-tdd` |
|
|
237
|
-
| `three-session-tdd-lite` |
|
|
238
|
-
| `tdd-simple` |
|
|
239
|
-
| `test-after` |
|
|
240
|
-
| `no-test` |
|
|
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
|
|
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
|
|
241
|
+
### Regression Gate
|
|
251
242
|
|
|
252
|
-
In
|
|
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`,
|
|
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
|
|
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
|
|