@navels/neal 0.6.7 → 0.6.9

package/dist/neal/prompts/execute.js

@@ -35,6 +35,7 @@ export function buildScopePrompt(planDoc, progressText) {
         'Use `blocked` for unexpected impasses; use `manual_gate` for intentional waits where `manualGate.resumeChecks` can prove the external work is complete.',
         'When action=`manual_gate`, include a non-null `manualGate` object with non-empty `id`, `title`, `reason`, `instructionsMarkdown`, and at least one command resume check. Keep `derivedPlan` and `blockedReason` empty.',
         'When action is anything other than `manual_gate`, set `manualGate` to null.',
+        'Do not open a manual gate on tooling built in this same scope (a test harness, a procedure, a script): it has not been reviewed yet. Check for this before you start building, and set action=`split_plan` with a derived plan that builds and verifies the tooling in its own scope and opens the gate at the start of the next. Use `blocked` only when no such derived plan is practical.',
         `If the target remains viable but the current scope has proven to be the wrong execution shape, set action=\`split_plan\` instead of forcing the bad shape or using action=\`blocked\`.`,
         'Use action=`split_plan` only when the current scope result should be discarded and replaced by a safer derived plan for the same target.',
         'When action=`split_plan`, put the complete derived plan body in `derivedPlan`.',

package/dist/neal/prompts/planning.js

@@ -35,6 +35,7 @@ function getPlanReviewerReadinessLines() {
         'A ready plan preserves the requested objective, proposes a sound approach, accounts for major architectural constraints and dependencies, uses a valid execution shape with coherent scopes, and gives each scope meaningful verification and a reviewable success condition.',
         'The plan is written for both neal and the operator. It should be concise enough for a person to review, specific enough to guide implementation, and open enough for the coder to make local choices after inspecting the code.',
         'Raise a blocking finding only when an omission is likely to produce the wrong implementation, make a scope unsafe or impractical, hide a major dependency, leave sequencing materially unclear, or allow incorrect work to appear complete.',
+        'Raise a blocking scope granularity finding when a single scope both builds tooling for the operator to use (a test harness, a procedure, a script) and opens a manual gate on its use. A gate opens before its scope is reviewed, so that tooling belongs in its own scope, reviewed and accepted first, with the gate opening at the start of the next scope.',
         'Missing routine implementation detail is not a finding. Do not require exhaustive file, symbol, caller, test, command, assertion, line-number, pinned-value, or fixture inventories.',
         'More detail can make a plan worse by turning tentative implementation choices into acceptance requirements. Ask for low-level detail only when it records a fixed decision, preserves compatibility, or prevents a known failure.',
         ...getPlanVerificationScopeLines('reviewer'),
@@ -71,6 +72,7 @@ function getPlanningPromptBaseLines(planDoc) {
         'Do not leave planning-only scaffolding in the final file. Remove or replace sections such as planning mode instructions, Required Inputs for the planner, Verification For This Planning Task, and Completion Criteria For This Planning Task.',
         'Your refined plan will be reviewed for execution readiness on three dimensions; satisfy each before finalizing: scope granularity (the work is divided into coherent, bounded scopes without exhaustive path inventories), verification concreteness (each scope names meaningful checks without specifying every possible oracle), and resume safety (scopes have understandable ordering and clean stopping points).',
         'Make the final plan explicit about its execution shape, scope goals and approach, sequencing, meaningful verification, and success conditions. Add constraints, non-goals, or blocker handling only where the task needs them.',
+        'A manual gate pauses a scope for operator work outside the agent process, and it opens before that scope has been reviewed. So when the plan needs operator work that depends on something the run builds (a test harness, a procedure, a script), split it into two scopes: the first builds that tooling and verifies it as far as it can without the operator, and is reviewed and accepted like any other scope; the next scope opens the manual gate at its start and works with the results.',
         'Choose `multi_scope` when the work changes orchestration or state-machine behavior, resume semantics, persistence or schema shape, multiple independent subsystems, or otherwise naturally falls into staged rollout checkpoints.',
         'Choose `multi_scope_unknown` when the work repeats one bounded recurring slice at a time and the total number of scopes is intentionally unknown until an explicit completion condition is satisfied.',
         'Choose `one_shot` only when the work can realistically be executed, reviewed, and verified as one bounded scope without hidden staging assumptions.',
@@ -123,6 +125,7 @@ function getAuthoredOneShotPlanningLines(authoredOneShot) {
     }
     return [
         'This plan was authored as a single-scope (`one_shot`) plan; keep it one scope, make the smallest complete change, and do not restructure it into multiple scopes.',
+        'The one exception is operator work that depends on something the run builds: that plan cannot stay one scope, so declare `multi_scope`, expand only as far as the tooling scope and the manual-gate scope require, and say why in `message`.',
     ];
 }
 function getAuthoredOneShotReviewerLines(authoredOneShot) {
@@ -131,6 +134,7 @@ function getAuthoredOneShotReviewerLines(authoredOneShot) {
     }
     return [
         'This plan was authored `one_shot`; raise a blocking finding if the document declares any other execution shape or adds orchestration sections.',
+        'The one exception is a plan that needs operator work that depends on something the run builds: accept `multi_scope` there when the expansion goes only as far as the tooling scope and the manual-gate scope require, and do not ask for that work to be folded back into one scope.',
     ];
 }
 export function buildPlanningPrompt(planDoc, planDocument, options) {

package/dist/neal/prompts/specs.js

@@ -90,7 +90,7 @@ const CONSULTANT_CONTEXT = context('ConsultantPromptContext', [
 export const PROMPT_SPECS = [
     {
         id: 'plan_author',
-        version: 5,
+        version: 6,
         changelog: [
             {
                 version: 1,
@@ -112,6 +112,10 @@ export const PROMPT_SPECS = [
                 version: 5,
                 renderSha: '148ed793be3f39c4a5505289ab3045ff124d8c44a53bf5fa9ccc8c3c5f20d408',
             },
+            {
+                version: 6,
+                renderSha: '7c302d4befbb252b8346fce67c47dbab38668c9a232f92a715831ddc11da59ec',
+            },
         ],
         role: 'coder',
         purpose: 'Author or revise concise, human-reviewable Neal-executable plans at moderate-to-high-level implementation detail.',
@@ -186,7 +190,7 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'plan_reviewer',
-        version: 4,
+        version: 5,
         changelog: [
             {
                 version: 1,
@@ -204,6 +208,10 @@ export const PROMPT_SPECS = [
                 version: 4,
                 renderSha: '65ad05a8bbe1f4a6d631db8778bf6bed82249151f3412a7773f9568ae2d40f11',
             },
+            {
+                version: 5,
+                renderSha: '45730ee47b7cb5dc93bc776a6db4a3fb1800160b0c6173d41b43b81c6244f85a',
+            },
         ],
         role: 'reviewer',
         purpose: 'Review human-reviewable Neal-executable plans for material approach, scope, verification, and resume-safety defects.',
@@ -289,7 +297,7 @@ export const PROMPT_SPECS = [
     },
     {
         id: 'scope_coder',
-        version: 3,
+        version: 4,
         changelog: [
             {
                 version: 1,
@@ -303,6 +311,10 @@ export const PROMPT_SPECS = [
                 version: 3,
                 renderSha: '8fb94430bf9d9abcb11f905106a3a04fc1b81bd101104c88f84a8693f705c5ea',
             },
+            {
+                version: 4,
+                renderSha: '7c413f0bd9a71f77cc2dc93c44af6f672717324d8e4071bde93ecc25756b2841',
+            },
         ],
         role: 'coder',
         purpose: 'Execute exactly one bounded implementation scope and respond to in-scope review feedback without starting new scopes.',

package/docs/maintenance.md

@@ -10,7 +10,7 @@ Grouped so at most a handful of dependency PRs are ever open at once:
 | Bucket | Contents | Cadence | Update posture |
 | --- | --- | --- | --- |
 | **Weekly non-major** | everything except the native SDKs (minor/patch/pin/digest) | weekly, one grouped PR | auto-merge after CI and the live smoke pass, subject to a 3-day soak |
-| **Native SDKs** | `@openai/codex-sdk` and `@anthropic-ai/claude-agent-sdk`, both exact-pinned. `ai`, `@ai-sdk/openai-compatible`, and `zod` also stay exact-pinned. | one grouped PR, opened after the 3-day soak instead of waiting for the weekly schedule | qualify on a subscription-authenticated machine with `scripts/qualify-sdk.sh`. Never auto-merge. Skip the CI smoke because it does not exercise the native adapters. |
+| **Native SDKs** | `@openai/codex-sdk` and `@anthropic-ai/claude-agent-sdk`, both exact-pinned. `ai`, `@ai-sdk/openai-compatible`, and `zod` also stay exact-pinned. | one grouped PR, opened after the 3-day soak instead of waiting for the weekly schedule | qualify on a subscription-authenticated machine with `scripts/qualify-sdk.sh`. Never auto-merge. The CI smoke skips itself on these PRs because it does not exercise the native adapters. |
 | **Library majors** | every npm major except the native SDKs (`typescript`, `@types/node`, `ai`, `@ai-sdk/openai-compatible`, `zod`, etc.) | monthly, one grouped PR | review manually because some need code changes |
 | **GitHub Actions majors** | `actions/checkout`, `actions/setup-node`, `actions/upload-artifact`, etc. | monthly, one grouped PR separate from library majors | review and merge on green CI. Do not auto-merge because a major action bump can still change behavior. |
 
@@ -19,7 +19,7 @@ tool-calling, structured output, or sandbox behavior. That breaks neal's loop
 **without** breaking compilation. And CI can't behaviorally exercise the
 native adapters: their auth is subscription-based and lives only on a
 maintainer's machine. Everything else is behaviorally exercised in CI: the
-live smoke runs on every package.json/lockfile PR, so the weekly grouped PR
+live smoke runs on package.json/lockfile PRs that change something it exercises, so the weekly grouped PR
 is gated on it as a whole.
 
 ## The update flow
@@ -31,7 +31,7 @@ is gated on it as a whole.
 2. **Verify (automatic).** CI (`.github/workflows/ci.yml`) runs typecheck + lint
    + unit tests + package verification on Node 24.18.0, which catches
    **API-shape / contract** breaks. The live smoke
-   (`.github/workflows/smoke.yml`) runs on every package.json / lockfile PR: a
+   (`.github/workflows/smoke.yml`) runs on package.json / lockfile PRs that change something it exercises (a version bump or a native-SDK pin bump skips it): a
    real `neal compat` run against a cheap OpenRouter model through
    `openai-compatible`, catching **behavioral** breaks in the AI-SDK tier. The
    weekly non-major PR auto-merges when both are green.

package/docs/plan-format.md

@@ -61,6 +61,8 @@ planner is instructed to keep the plan one scope and make the smallest complete
 change, and the plan reviewer is instructed to raise a blocking finding if the
 refined document declares any other execution shape or adds orchestration
 sections. That finding routes through the normal revision loop like any other.
+The one exception is operator work that depends on something the run builds;
+see [Manual gates](#manual-gates).
 
 There is deliberately no hard mechanical clamp: if the review loop converges on
 a different shape (the reviewer accepts an expansion), neal adopts the refined
@@ -172,6 +174,46 @@ complete. It is not a prose summary of the goal. It is the reviewable exit
 criterion. Good success conditions mention the changed surface, the expected
 behavior or docs state, and the verification evidence required for acceptance.
 
+## Manual gates
+
+A manual gate is how the coder pauses a scope for work only the operator can do:
+running something on real hardware, flipping a setting in an external console,
+making a call the plan left to a person. The coder writes instructions and one
+or more resume checks, neal saves the instructions to a run-local `GATE-<id>.md`
+file and stops, and `neal resume --run <run-id>` re-runs the checks and hands the
+scope back to the coder when they pass.
+
+A gate opens during the coder's first pass on a scope, before any review. The
+reviewer sees nothing from that scope until the coder says the scope is done. So
+anything the operator is asked to use at the gate has to come from a scope that
+was already reviewed and accepted.
+
+When a plan needs operator work that depends on something the run builds (a test
+harness, a procedure, a script), split it into two scopes. The first builds that
+tooling and verifies it as far as it can without the operator, and is reviewed
+and accepted like any other scope. The next scope opens the manual gate at its
+start and works with the results.
+
+```md
+### Scope 1: Build the sensor test harness
+- Goal: Add `scripts/sensor-harness.sh`, which runs the calibration sweep against an attached board and writes `tmp/sensor-results.json`.
+- Verification: `pnpm test`, plus a harness dry run against the recorded fixture.
+- Success Condition: The harness runs end to end against the fixture and its output matches the documented result format.
+
+### Scope 2: Run the harness on hardware and apply the results
+- Goal: Open a manual gate asking the operator to run the harness on the bench board. Then set the calibration constants from `tmp/sensor-results.json`.
+- Verification: The gate's resume check confirms `tmp/sensor-results.json` exists and parses; then `pnpm test`.
+- Success Condition: The calibration constants come from a real hardware run, and the tests pass with them.
+```
+
+The planner, the plan reviewer, and the coder all hold to this. The planner
+splits the plan this way. The plan reviewer raises a blocking finding on a scope
+that both builds operator-facing tooling and gates on the operator using it. A
+coder that lands in such a scope anyway returns `split_plan` with the two-scope
+version instead of opening the gate. A plan authored `one_shot` may expand to
+`multi_scope` for this, only as far as the tooling scope and the gate scope
+require.
+
 ## Planning normalization
 
 `neal plan` revises the selected plan file in place. It should preserve the

package/docs/troubleshooting.md

@@ -121,6 +121,15 @@ run-local `GATE-<id>.md` file shown by `neal status`.
 **Fix:** do the manual step, then `neal resume --run <run-id>`, which re-runs
 the gate's checks and resumes the scope when they pass. No `--message` here.
 
+**Symptom:** the same gate keeps reopening: you do the step, resume, the coder
+patches the script or procedure it handed you, and the gate opens again.
+**Cause:** the tooling you were handed was built in the same scope that opened
+the gate. A gate opens before its scope is reviewed, so that tooling reached you
+unreviewed, and each fix-and-reopen round skips the reviewer too.
+**Fix:** don't resume again. Split the plan so the tooling gets its own scope
+ahead of the gate scope, then start a new run on the revised plan. See
+[Manual gates](plan-format.md#manual-gates).
+
 **Symptom:** a run seems hung or died silently.
 **Where to look:** raw detail is persisted even when hidden from the terminal:
 `.neal/runs/<run-id>/stderr.log` (full transcript) and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@navels/neal",
-  "version": "0.6.7",
+  "version": "0.6.9",
   "description": "A source-first multi-agent CLI for planning, executing, reviewing, and resuming scoped code changes.",
   "license": "MIT",
   "publishConfig": {
@@ -8,7 +8,7 @@
   },
   "author": "Lee Nave",
   "type": "module",
-  "packageManager": "pnpm@11.25.0",
+  "packageManager": "pnpm@11.26.0",
   "homepage": "https://github.com/navels/neal#readme",
   "repository": {
     "type": "git",
@@ -40,8 +40,8 @@
     "examples"
   ],
   "engines": {
-    "node": ">=24.20.0",
-    "pnpm": ">=11.25.0"
+    "node": ">=24.21.0",
+    "pnpm": ">=11.26.0"
   },
   "scripts": {
     "build": "rm -rf dist && node node_modules/typescript-7/bin/tsc -p tsconfig.json && chmod +x dist/neal/index.js",
@@ -55,21 +55,21 @@
     "typecheck": "node node_modules/typescript-7/bin/tsc --noEmit -p tsconfig.json && node node_modules/typescript-7/bin/tsc -p tsconfig.test.json"
   },
   "dependencies": {
-    "@ai-sdk/openai-compatible": "3.0.43",
-    "@anthropic-ai/claude-agent-sdk": "0.3.261",
-    "@openai/codex-sdk": "0.153.4",
-    "ai": "7.0.92",
+    "@ai-sdk/openai-compatible": "3.0.47",
+    "@anthropic-ai/claude-agent-sdk": "0.3.274",
+    "@openai/codex-sdk": "0.154.0",
+    "ai": "7.0.97",
     "dotenv": "^17.4.2",
     "yaml": "^2.9.0",
-    "zod": "4.5.4"
+    "zod": "4.6.2"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^24.13.3",
-    "eslint": "^10.9.1",
+    "@types/node": "^24.13.4",
+    "eslint": "^10.10.0",
     "tsx": "^4.23.13",
     "typescript": "^6.0.3",
     "typescript-7": "npm:typescript@^7.0.2",
-    "typescript-eslint": "^8.69.0"
+    "typescript-eslint": "^8.70.0"
   }
 }