@navels/neal 0.1.0 → 0.3.0

package/docs/storage.md

@@ -1,15 +1,15 @@
-# Neal Storage Contract
+# Storage contract
 
-Neal uses project-local `.neal/` storage as the source of truth for runs, queues,
+neal uses project-local `.neal/` storage as the source of truth for runs, queues,
 review artifacts, recovery artifacts, progress, and audit history. User-level
 storage is reserved for configuration, guidance, caches, logs, and future
 optional discovery helpers.
 
-This document describes the product-level storage contract. The state transition
-and validation details for run and queue ledgers are documented separately in
+The storage contract here is product-level. Run and queue ledger state
+transition and validation details are documented separately in
 [state-machine.md](state-machine.md).
 
-## Public Automation Surface
+## Public automation surface
 
 `neal status --json` and `neal status --json --all` are the stable automation
 contracts. Scripts should prefer them over parsing raw files under `.neal/`.
@@ -37,9 +37,9 @@ know a run id. Important stable fields include:
 - `providerError` with the latest provider failure or unclassified phase error,
   including timestamp, provider id, role, label, session handle, normalized
   error kind, bounded message, and retryability where available.
-- `build` with Neal package version, Neal source Git SHA when available, Node
+- `build` with neal package version, neal source Git SHA when available, Node
   version, source marker (`meta` or `live_fallback`), and the persisted
-  coder/reviewer agent config.
+  planner/coder/reviewer agent config.
 - `artifacts` with run-local paths for the human narrative, review, progress,
   support, and related diagnostic artifacts.
 
@@ -61,30 +61,38 @@ command output.
 Storage classifications used below are: stable CLI surface, user-facing human
 artifact, support/debug artifact, internal state, and lock/concurrency artifact.
 The stable CLI surfaces in this storage contract are `neal status --json` and
-`neal status --json --all`; the project-local files are artifacts that support
-Neal operations and diagnostics.
+`neal status --json --all`. The project-local files are artifacts that support
+neal operations and diagnostics.
 
-## Project-Local Layout
+## Project-local layout
 
 | Path | Classification | Contract |
 | --- | --- | --- |
-| `.neal/runs/<run-id>/RUN_STATE.json` | Internal state | Child-run ledger. Neal validates current v1 state on read, but scripts should use `neal status --json` rather than depend on this file as a public API. |
+| `.neal/runs/<run-id>/RUN_STATE.json` | Internal state | Child-run ledger. neal validates current v1 state on read, but scripts should use `neal status --json` rather than depend on this file as a public API. |
 | `.neal/runs/<run-id>/events.ndjson` | Support/debug artifact | Append-only event log for audit, diagnostics, command output references, and provider/runtime events. Readers should tolerate malformed or partial final lines where implemented. |
 | `.neal/runs/<run-id>/stderr.log` | Support/debug artifact | Append-only stderr transcript for writer runs. It includes visible narrative lines plus low-level detail such as provider/tool telemetry, command output, reviewer context, and heartbeat diagnostics that may be hidden from the normal terminal stream. |
-| `.neal/runs/<run-id>/meta.json` | Support/debug artifact | Run metadata used for diagnostics. New writes include `version: 1`; metadata alone cannot make a run selectable for squash or status. It is not the stable automation surface. |
+| `.neal/runs/<run-id>/meta.json` | Support/debug artifact | Run metadata used for diagnostics. New writes include `version: 1`. Metadata alone cannot make a run selectable for squash or status. It is not the stable automation surface. |
 | `.neal/runs/<run-id>/PLAN_ORIGINAL.md` | Support/debug artifact | Original plan document backup for `neal plan` runs, written before in-place plan refinement so the pre-refinement input remains inspectable. |
-| `.neal/runs/<run-id>/scratch/` | Support/debug artifact | Run-local scratch root for execute-scope and final-completion reviewer verification artifacts such as copied tests, scratch builds, logs, and modified throwaway files. It is not durable state, but it remains project-local `.neal/` data for retention and privacy purposes. |
-| `.neal/runs/<run-id>/plan-progress.json` | Internal state | Machine-readable v1 progress artifact used by Neal context and summaries. |
+| `.neal/runs/<run-id>/DERIVED_PLAN_SCOPE_<scope>.md` | User-facing human artifact | Replacement execution plan produced when the coder splits an active scope. |
+| `.neal/runs/<run-id>/SCOPE_<scope>_INVALID_DERIVED_PLAN.md` | Support/debug artifact | Rejected split-plan payload and its validation errors. Written only when the returned replacement plan is invalid. |
+| `.neal/runs/<run-id>/SCOPE_<scope>_DISCARDED.diff` | Support/debug artifact | Scope work preserved before neal resets it while adopting a replacement plan. |
+| `.neal/runs/<run-id>/GATE-<id>.md` | User-facing human artifact | Instructions and resume checks for an active manual gate. |
+| `.neal/runs/<run-id>/scratch/` | Support/debug artifact | Reserved run-local scratch root for execute-scope and final-completion review. Read-only reviewer prompts do not use it. It is not durable state, but it remains project-local `.neal/` data for retention and privacy purposes. |
+| `.neal/runs/<run-id>/plan-progress.json` | Internal state | Machine-readable v1 progress artifact used by neal context and summaries. |
 | `.neal/runs/<run-id>/PLAN_PROGRESS.md` | User-facing human artifact | Human-readable progress summary for the active plan or scope. |
 | `.neal/runs/<run-id>/RETROSPECTIVE.md` | User-facing human artifact | Human-readable retrospective or checkpoint summary. Archived variants such as `RETROSPECTIVE-scope-*.md` may also exist. |
+| `.neal/runs/<run-id>/RUN_METRICS.json` | Support/debug artifact | Machine-readable metrics paired with the current retrospective. Archived variants such as `RUN_METRICS-scope-*.json` may also exist. |
 | `.neal/runs/<run-id>/RUN_NARRATIVE.md` | User-facing human artifact | Human-readable run narrative. It includes a benchmark trace section with status, patch-policy, provider-error, and reproducibility summaries suitable for public result bundles. |
-| `.neal/runs/<run-id>/RUN_NARRATIVE.json` | Internal state | Narrative source data that Neal may read to update the human narrative. It is not a public trace artifact. |
+| `.neal/runs/<run-id>/RUN_NARRATIVE.json` | Internal state | Narrative source data that neal may read to update the human narrative. It is not a public trace artifact. |
 | `.neal/runs/<run-id>/REVIEW.md` | User-facing human artifact | Scope or plan review history and findings. |
+| `.neal/runs/<run-id>/REVIEW-<commit>.md` | User-facing human artifact | Archived review history for an accepted scope commit. |
+| `.neal/runs/<run-id>/REVIEWER_CONTEXT.md` | Support/debug artifact | Bounded reviewer-continuity packet rendered for inspection. |
+| `.neal/runs/<run-id>/REVIEWER_CONTEXT.json` | Support/debug artifact | Machine-readable reviewer-continuity packet without the rendered prompt markdown. |
 | `.neal/runs/<run-id>/RECOVERY.md` | User-facing human artifact | Interactive blocked-recovery transcript/history for a run. |
 | `.neal/runs/<run-id>/FINAL_COMPLETION_REVIEW.md` | User-facing human artifact | Whole-plan final completion review. |
 | `.neal/runs/<run-id>/SQUASH_RESULT.json` | Support/debug artifact | Versioned audit artifact from `neal squash`. It records the squash decision/result but is not the stable automation surface. |
 | `.neal/runs/<run-id>/QUEUE_LINK.json` | Internal state | Link from a child run back to its parent plan-and-execute queue item. |
-| `.neal/queues/<queue-id>/QUEUE_STATE.json` | Internal state | Parent queue ledger. Neal validates it on read, but it is not a public JSON API. |
+| `.neal/queues/<queue-id>/QUEUE_STATE.json` | Internal state | Parent queue ledger. neal validates it on read, but it is not a public JSON API. |
 | `.neal/queues/<queue-id>/QUEUE_SUMMARY.md` | User-facing human artifact | Human-readable summary for a plan-and-execute queue. |
 | `.neal/reviews/<review-id>/meta.json` | Support/debug artifact | Review metadata for a read-only `neal review` request. |
 | `.neal/reviews/<review-id>/events.ndjson` | Support/debug artifact | Append-only review event log. |
@@ -97,19 +105,20 @@ Neal operations and diagnostics.
 | `.neal/current.json` | Internal state | Default writer-run pointer for commands that need the current run. |
 | `.neal/current-queue.json` | Internal state | Preferred current plan-and-execute queue pointer. |
 | `.neal/active-run.lock` | Lock/concurrency artifact | Active writer-run lock. It prevents unrelated writer commands from mutating the same checkout concurrently. |
+| `.neal/NOTES.md` | User-facing human artifact | Optional operator-authored notes included in bounded context packets. neal reads this file but does not create it. |
 
 Writer processes remove their own active lock during normal shutdown and on
-`SIGINT`/`SIGTERM`. Timeout wrappers should still launch Neal in a process group
+`SIGINT`/`SIGTERM`. Timeout wrappers should still launch neal in a process group
 and terminate the group, because provider-owned child processes are outside the
 lock file contract. After a timeout, call `neal status --json --run <run-id>`
-when the run id is known; treat the wrapper timeout as the primary result while
-using `status`, `health`, and `lock.kind` to record whether Neal's run state is
+when the run id is known. Treat the wrapper timeout as the primary result while
+using `status`, `health`, and `lock.kind` to record whether neal's run state is
 still running, cleaned up, live, stale, cross-host, or unreadable.
 
-## Patch Automation Policy
+## Patch automation policy
 
 Default public prediction submission should use only
-`patch.defaultSubmissionEligible: true`. Neal sets that value only for clean
+`patch.defaultSubmissionEligible: true`. neal sets that value only for clean
 completed execute runs with a non-empty readable patch range.
 
 When a completed run has a successful squash artifact, the status read model
@@ -124,28 +133,28 @@ runs may still report patch-bearing metadata for diagnostics or private
 analysis. They are not default-submission eligible, and `patch.reason` explains
 why.
 
-## Source Of Truth
+## Source of truth
 
 Project-local `.neal/` remains the source of truth for run, queue, review,
 recovery, progress, and audit artifacts.
 
 Run-local `.neal/runs/<run-id>/RUN_STATE.json` is the only writer-run ledger
-path Neal writes. `.neal/current.json` points at the default writer run; it is a
+path neal writes. `.neal/current.json` points at the default writer run. It is a
 pointer, not a copy of the ledger.
 
 There is no required global run index in v1. Future global discovery, if added,
 must be optional and rebuildable from project-local data. It must not become the
 only place where run or queue history can be recovered.
 
-## Ledgers And Pointers
+## Ledgers and pointers
 
 `.neal/runs/<run-id>/RUN_STATE.json` and
-`.neal/queues/<queue-id>/QUEUE_STATE.json` are persisted ledgers. Neal validates
+`.neal/queues/<queue-id>/QUEUE_STATE.json` are persisted ledgers. neal validates
 them on read. Child-run state uses strict current v1 hydration: missing or
 malformed required child-run fields fail instead of receiving defaults. These
 ledgers are not public JSON APIs.
 
-Neal does not write, read, migrate, or repair a session mirror. Use
+neal does not write, read, migrate, or repair a session mirror. Use
 `.neal/current.json` as the default writer-run pointer, `neal status --all` to
 discover run IDs, and `--run <run-id>` when selecting a specific run for
 `resume` or `status`.
@@ -154,9 +163,9 @@ Squash discovery requires readable run-local state. Run metadata and progress
 artifacts can help humans inspect a run, but they cannot make a run selectable
 for `neal squash` without `.neal/runs/<run-id>/RUN_STATE.json`.
 
-## Schema Versions And Writes
+## Schema versions and writes
 
-Neal-owned JSON schemas use `version: 1` where they are read back as durable
+neal-owned JSON schemas use `version: 1` where they are read back as durable
 state or audit data. That includes child-run state, current run pointers, queue
 state, current queue pointers, queue child links, progress summaries, run
 narratives, squash audit results, review artifacts, and the active writer lock.
@@ -172,7 +181,7 @@ files such as state, progress, reviews, and pointers can briefly disagree if a
 process stops between writes. Append-only event logs remain append-only, and the
 active writer lock keeps exclusive file creation for acquisition.
 
-## Retention And Privacy
+## Retention and privacy
 
 `.neal/` may contain prompts, local paths, command output, diffs, review text,
 provider responses, user guidance diagnostics, reviewer scratch files, copied
@@ -188,7 +197,7 @@ Run and review artifacts are intentionally inspectable, but they should be
 treated as project data. Apply the same retention and access controls you use
 for source, logs, and local debugging output.
 
-## Manual Cleanup
+## Manual cleanup
 
 Manual cleanup is safe only when you no longer need resume, history, diagnostics,
 or audit data for the item being removed.
@@ -202,6 +211,6 @@ Reasonable manual cleanup options:
 - remove stale `.neal/current.json` or `.neal/current-queue.json` pointers only
   after confirming they do not point to work you still intend to resume
 
-Deleting run or queue state removes Neal's resume and history for that run or
+Deleting run or queue state removes neal's resume and history for that run or
 queue. Prefer keeping the full directory until the related work has been merged,
 archived, or otherwise recorded somewhere durable.

package/docs/troubleshooting.md

@@ -6,7 +6,7 @@ prints. When in doubt: `neal check`, then `.neal/runs/<run-id>/stderr.log`.
 ## Install and first run
 
 **Symptom:** install or startup fails on an old Node.
-**Cause:** neal requires Node.js >= 22.13 (`engines`); `.nvmrc` pins `24`.
+**Cause:** neal requires Node.js >= 24.18.0 (`engines`). `.nvmrc` pins `24.18.0`.
 **Fix:** `nvm use` in this repo, or upgrade Node before `npm install -g @navels/neal`.
 
 **Symptom:** `pnpm: command not found` when running from source.
@@ -20,13 +20,13 @@ After source changes, `pnpm build` again so the linked command sees `dist/`.
 
 **Symptom:** `neal setup` lists a provider with `- runtime not found`.
 **Cause:** setup detects local runtime surfaces only (the `@openai/codex-sdk`
-entrypoint; an SDK-bundled or on-PATH `claude` executable) — never auth.
+entrypoint, an SDK-bundled or on-PATH `claude` executable), never auth.
 **Fix:** install the provider's SDK/CLI, then rerun `neal setup` and `neal check`.
 
 ## Provider auth failures (`neal check`)
 
 `neal check` sends one small prompt per unique configured provider/model
-(interactive TTY only — non-interactive input prints
+(interactive TTY only. Non-interactive input prints
 `Provider verification skipped: non-interactive input.`). Known failures:
 
 **Symptom:** `Claude Code refused bypass-permissions mode while running as root.`
@@ -40,31 +40,34 @@ Claude Code refuses under root/sudo.
 directory (e.g. run the `codex` CLI there once), then `neal check` again.
 
 **Symptom:** `OpenAI Codex could not persist the check session.`
-**Fix:** transient; run `neal check` again. If it repeats, redo the provider's
+**Fix:** transient. Run `neal check` again. If it repeats, redo the provider's
 local setup.
 
 **Symptom:** a `not logged in` message from either vendor CLI.
-**Cause:** provider auth is provider-owned; neal never collects credentials.
+**Cause:** provider auth is provider-owned, so neal never collects credentials.
 **Fix:** complete the provider's normal local auth setup (the `codex` / `claude`
 login flows), then `neal check` again.
 
 **Symptom:** `Set providers.openai_compatible.base_url (or OPENAI_COMPATIBLE_BASE_URL) and OPENAI_COMPATIBLE_API_KEY before running Neal.`
 (or `No model is resolvable for the openai-compatible ... role`).
-**Cause:** `openai-compatible` / `generic-agentic` resolve settings config-first
-with env fallbacks: `base_url` → `OPENAI_COMPATIBLE_BASE_URL`; the key is read
-from the env var named by `api_key_env` (default `OPENAI_COMPATIBLE_API_KEY`);
-model from `agent.<role>.model` → `default_model` → `OPENAI_COMPATIBLE_MODEL`.
+**Cause:** `openai-compatible` resolves settings from config first,
+with env fallbacks: `base_url` → `OPENAI_COMPATIBLE_BASE_URL`. The key is read
+from the env var named by `api_key_env` (default `OPENAI_COMPATIBLE_API_KEY`).
+Model from `agent.<role>.model` → `default_model` → `OPENAI_COMPATIBLE_MODEL`.
 **Fix:** set the missing key. For OpenRouter: `base_url: https://openrouter.ai/api/v1`,
 `api_key_env: OPENROUTER_API_KEY`, and export `OPENROUTER_API_KEY`. (OpenRouter
-wraps upstream 429s in HTTP-200 bodies; neal unwraps and retries them.)
+wraps upstream 429s in HTTP-200 bodies, so neal unwraps and retries them.)
 
 ## Runs that won't start
 
-**Symptom:** plan validation errors such as
-`Missing required `## Execution Shape` section.` or
-``## Execution Shape` must contain exactly one non-empty line.`
+**Symptom:** plan validation errors such as:
+
+```text
+Missing required `## Execution Shape` section.
+`## Execution Shape` must contain exactly one non-empty line.
+```
 **Cause:** every executable plan must declare exactly one of
-`executionShape: one_shot | multi_scope | multi_scope_unknown`; `multi_scope`
+`executionShape: one_shot | multi_scope | multi_scope_unknown`. `multi_scope`
 also requires an `## Execution Queue` with contiguous `### Scope N:` headings,
 each carrying `- Goal:` / `- Verification:` / `- Success Condition:` bullets.
 **Fix:** see [plan-format.md](plan-format.md), or let `neal plan` refine the
@@ -72,23 +75,23 @@ document into executable shape.
 
 **Symptom:** a missing-config error naming `agent.coder.provider` or
 `agent.reviewer.provider`.
-**Cause:** fresh writer runs require explicit coder and reviewer providers;
-built-in defaults are not enough.
+**Cause:** fresh writer runs require explicit coder and reviewer providers.
+Built-in defaults are not enough.
 **Fix:** `neal setup`, then `neal check`.
 
 **Symptom:** `Cannot start neal execute with a dirty worktree:` followed by
 `git status` lines (queues: `Cannot continue neal run with a dirty worktree:`).
-**Cause:** writer admission requires a clean worktree; only the selected plan
+**Cause:** writer admission requires a clean worktree. Only the selected plan
 document and neal-owned paths (`.neal/`) are exempt. Leftover reviewer scratch
 (`build_review/`, `scratch/`, …) gets a
-`Likely Neal reviewer scratch leakage detected:` diagnostic but still blocks —
-the paths are not proven neal-owned.
+`Likely Neal reviewer scratch leakage detected:` diagnostic but still blocks,
+because the paths are not proven neal-owned.
 **Fix:** use `neal resume` for in-progress scope work, or commit, stash, move,
 or remove the dirty paths and start clean.
 
 **Symptom:** a Git precondition error before any provider runs.
 **Fix:** writer commands require a Git repository with an existing `HEAD`
-commit; create the initial baseline commit first.
+commit. Create the initial baseline commit first.
 
 ## Stuck or blocked runs
 
@@ -100,26 +103,26 @@ something it may not resolve alone, and attended runs wait for guidance.
 accepted in that waiting-for-guidance state.
 
 **Symptom:** `effectiveStatus: "waiting_for_manual_gate"`.
-**Cause:** the scope reached expected human work; instructions are in the
+**Cause:** the scope reached expected human work. Instructions are in the
 run-local `GATE-<id>.md` file shown by `neal status`.
-**Fix:** do the manual step, then `neal resume --run <run-id>` — it re-runs
+**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:** 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
-`.neal/runs/<run-id>/events.ndjson` (event log; startup-silence retries appear
-as `provider.turn_liveness_*` events). On a live TTY, press `v` for the
+`.neal/runs/<run-id>/events.ndjson` (event log, where startup-silence retries
+appear as `provider.turn_liveness_*` events). On a live TTY, press `v` for the
 low-level detail view. `neal status --json --run <run-id>` carries the latest
 `providerError` classification.
 
 ## Lock issues
 
-The writer lock is `.neal/active-run.lock`; writer processes remove it on
+The writer lock is `.neal/active-run.lock`. Writer processes remove it on
 normal shutdown and on SIGINT/SIGTERM.
 
 **Symptom:** `another Neal writer run is active in this checkout`.
-**Fix:** as printed — `neal resume --run <run-id>` to continue that run, or
+**Fix:** as printed: `neal resume --run <run-id>` to continue that run, or
 wait for it to finish.
 
 **Symptom:** `another Neal process is already resuming this run` (with
@@ -128,17 +131,17 @@ wait for it to finish.
 
 **Symptom:** `stale Neal writer lock found in this checkout` /
 `no process with that PID is running on this host.`
-**Fix:** `neal resume --run <run-id>` clears stale same-host locks itself; if
+**Fix:** `neal resume --run <run-id>` clears stale same-host locks itself. If
 you're starting different work instead, inspect the run, then remove the lock
 file the message names.
 
 **Symptom:** `Neal writer lock belongs to another host`.
-**Fix:** inspect the other host before removing the lock; the message prints
+**Fix:** inspect the other host before removing the lock. The message prints
 the exact resume command for that checkout.
 
 **Symptom:** `could not read the active Neal writer lock`.
 **Fix:** as printed: inspect the named lock file before starting another
-writer run; remove it only after confirming no writer process is active.
+writer run. Remove it only after confirming no writer process is active.
 
 ## "It squashed when I didn't want it to"
 

package/examples/compat/add-edit-verify/PLAN.md

@@ -1,5 +1,7 @@
 # Compat fixture: fix `add`
 
+> Fixture note: this plan describes the pre-fix state and is intentionally not updated after the fix lands.
+
 ## Execution Shape
 
 executionShape: one_shot

package/examples/compat/add-edit-verify/broken.diff

@@ -1,8 +1,8 @@
 diff --git a/src/add.js b/src/add.js
-index 4125f75..a3e4914 100644
+index 6946b9a..e9fa11d 100644
 --- a/src/add.js
 +++ b/src/add.js
 @@ -1,2 +1,2 @@
- // Trivial compat fixture: this addition helper is intentionally buggy.
+ // Trivial compat fixture: an arithmetic helper exercised by test/add.test.js.
 -export const add = (a, b) => a - b;
 +export const add = (a, b) => a * b;

package/examples/compat/add-edit-verify/good.diff

@@ -1,8 +1,8 @@
 diff --git a/src/add.js b/src/add.js
-index 4125f75..0088c50 100644
+index 6946b9a..ee66238 100644
 --- a/src/add.js
 +++ b/src/add.js
 @@ -1,2 +1,2 @@
- // Trivial compat fixture: this addition helper is intentionally buggy.
+ // Trivial compat fixture: an arithmetic helper exercised by test/add.test.js.
 -export const add = (a, b) => a - b;
 +export const add = (a, b) => a + b;

package/examples/compat/add-edit-verify/src/add.js

@@ -1,2 +1,2 @@
-// Trivial compat fixture: this addition helper is intentionally buggy.
+// Trivial compat fixture: an arithmetic helper exercised by test/add.test.js.
 export const add = (a, b) => a - b;

package/examples/compat/manifest.json

@@ -2,51 +2,47 @@
   "fixtures": [
     {
       "id": "add-edit-verify",
-      "roles": ["coder", "reviewer"],
+      "roles": [
+        "coder",
+        "reviewer"
+      ],
       "projectDir": "add-edit-verify",
       "planDoc": "add-edit-verify/PLAN.md",
       "verifyCommand": "node --test test/add.test.js",
-      "referenceFix": { "file": "src/add.js", "from": "a - b", "to": "a + b" },
-      "reviewer": {
-        "goodDiff": "add-edit-verify/good.diff",
-        "brokenDiff": "add-edit-verify/broken.diff"
-      }
-    },
-    {
-      "id": "reverse-grep-edit",
-      "roles": ["coder", "reviewer"],
-      "projectDir": "reverse-grep-edit",
-      "planDoc": "reverse-grep-edit/PLAN.md",
-      "verifyCommand": "node --test test/strings.test.js",
       "referenceFix": {
-        "file": "src/strings.js",
-        "from": "s.split('').join('')",
-        "to": "s.split('').reverse().join('')"
+        "file": "src/add.js",
+        "from": "a - b",
+        "to": "a + b"
       },
       "reviewer": {
-        "goodDiff": "reverse-grep-edit/good.diff",
-        "brokenDiff": "reverse-grep-edit/broken.diff"
+        "goodDiff": "add-edit-verify/good.diff",
+        "brokenDiff": "add-edit-verify/broken.diff"
       }
     },
     {
-      "id": "is-even-add-test",
-      "roles": ["coder", "reviewer"],
-      "projectDir": "is-even-add-test",
-      "planDoc": "is-even-add-test/PLAN.md",
-      "verifyCommand": "node --test test/is-even.test.js",
+      "id": "sum-grep-edit",
+      "roles": [
+        "coder",
+        "reviewer"
+      ],
+      "projectDir": "sum-grep-edit",
+      "planDoc": "sum-grep-edit/PLAN.md",
+      "verifyCommand": "node --test test/numbers.test.js",
       "referenceFix": {
-        "file": "test/is-even.test.js",
-        "from": "assert.ok(false, 'TODO: replace this placeholder with a real test for isEven');",
-        "to": "assert.equal(isEven(4), true);"
+        "file": "src/numbers.js",
+        "from": "(total, n) => total",
+        "to": "(total, n) => total + n"
       },
       "reviewer": {
-        "goodDiff": "is-even-add-test/good.diff",
-        "brokenDiff": "is-even-add-test/broken.diff"
+        "goodDiff": "sum-grep-edit/good.diff",
+        "brokenDiff": "sum-grep-edit/broken.diff"
       }
     },
     {
       "id": "plan-greeting",
-      "roles": ["planner"],
+      "roles": [
+        "planner"
+      ],
       "projectDir": "plan-greeting",
       "issuePrompt": "plan-greeting/ISSUE.md",
       "verifyCommand": "node --test test/greet.test.js",

package/examples/compat/sum-grep-edit/PLAN.md

@@ -0,0 +1,33 @@
+# Compat fixture: fix the number helper that never adds
+
+> Fixture note: this plan describes the pre-fix state and is intentionally not updated after the fix lands.
+
+## Execution Shape
+
+executionShape: one_shot
+
+## Objective
+
+`src/numbers.js` exports several small number helpers. One of them is faulty:
+`sumAll(ns)` is supposed to return the total of the list, but it always returns
+`0`. The `sumAll` test in `test/numbers.test.js` fails because of this.
+
+Read `src/numbers.js`, locate the faulty `sumAll` helper, and make the smallest
+complete change so it returns the sum of the list. Do not touch the other
+helpers, which already pass their tests.
+
+## Boundaries
+
+Allowed paths:
+
+- `src/numbers.js`
+
+Forbidden:
+
+- Do not edit the test file.
+- Do not change the other (already-correct) helpers.
+- Do not add dependencies or new files.
+
+## Verification
+
+Run `node --test test/numbers.test.js`; it must exit `0`.

package/examples/compat/sum-grep-edit/broken.diff

@@ -0,0 +1,12 @@
+diff --git a/src/numbers.js b/src/numbers.js
+index e6677cc..6a5102c 100644
+--- a/src/numbers.js
++++ b/src/numbers.js
+@@ -4,6 +4,6 @@ export const double = (n) => n * 2;
+ 
+ export const negate = (n) => -n;
+ 
+-export const sumAll = (ns) => ns.reduce((total, n) => total, 0);
++export const sumAll = (ns) => ns.reduce((total, n) => total + 1, 0);
+ 
+ export const countOf = (ns) => ns.length;

package/examples/compat/sum-grep-edit/good.diff

@@ -0,0 +1,12 @@
+diff --git a/src/numbers.js b/src/numbers.js
+index e6677cc..89f58ba 100644
+--- a/src/numbers.js
++++ b/src/numbers.js
+@@ -4,6 +4,6 @@ export const double = (n) => n * 2;
+ 
+ export const negate = (n) => -n;
+ 
+-export const sumAll = (ns) => ns.reduce((total, n) => total, 0);
++export const sumAll = (ns) => ns.reduce((total, n) => total + n, 0);
+ 
+ export const countOf = (ns) => ns.length;

package/examples/compat/sum-grep-edit/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "@navels/neal-compat-sum-grep-edit",
+  "private": true,
+  "type": "module"
+}

package/examples/compat/sum-grep-edit/src/numbers.js

@@ -0,0 +1,9 @@
+// Trivial compat fixture: small number helpers. test/numbers.test.js is the
+// source of truth for their behavior.
+export const double = (n) => n * 2;
+
+export const negate = (n) => -n;
+
+export const sumAll = (ns) => ns.reduce((total, n) => total, 0);
+
+export const countOf = (ns) => ns.length;

package/examples/compat/sum-grep-edit/test/numbers.test.js

@@ -0,0 +1,15 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { countOf, double, negate, sumAll } from '../src/numbers.js';
+
+test('double/negate/countOf helpers are correct', () => {
+  assert.equal(double(4), 8);
+  assert.equal(negate(3), -3);
+  assert.equal(countOf([1, 2, 3]), 3);
+});
+
+test('sumAll returns the total of the list', () => {
+  assert.equal(sumAll([1, 2, 3]), 6);
+  assert.equal(sumAll([]), 0);
+});

package/examples/issue-triage-js/README.md

@@ -59,18 +59,3 @@ guarantee that a live provider-backed run will complete successfully.
 
 Normal repository CI validates this example through non-live tests and package
 checks without running providers.
-
-## Manual Canary Workflow
-
-Maintainers can dispatch the `Example Canary` GitHub Actions workflow when they
-want a live provider-backed smoke test for this example. The workflow is
-manual-only, uses the `example-canary` environment, and requires the
-environment to provide `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or both depending
-on the selected coder and reviewer providers.
-
-The canary builds Neal, writes a temporary `~/.neal/config.yml` from the
-selected provider roles, runs the example baseline tests, runs
-`node ../../dist/neal/index.js run PLAN.md --no-squash` from this directory,
-and uploads only curated markdown support artifacts from the example-local
-`.neal/` directory. Scheduled canaries are deferred until cost and flakiness are
-understood from intentional manual runs.

package/examples/reviewer-eval/clean-doc/base/src/clamp.ts

@@ -0,0 +1,3 @@
+export function clamp(value: number, lo: number, hi: number): number {
+  return Math.max(lo, Math.min(hi, value));
+}

package/examples/reviewer-eval/clean-doc/change.diff

@@ -0,0 +1,9 @@
+diff --git a/src/clamp.ts b/src/clamp.ts
+index 58793c4..c7a624d 100644
+--- a/src/clamp.ts
++++ b/src/clamp.ts
+@@ -1,3 +1,4 @@
++/** Restrict `value` to the inclusive range [lo, hi]. */
+ export function clamp(value: number, lo: number, hi: number): number {
+   return Math.max(lo, Math.min(hi, value));
+ }

package/examples/reviewer-eval/clean-extract/base/src/greet.ts

@@ -0,0 +1,3 @@
+export function greet(name: string): string {
+  return 'Hello, ' + name.trim() + '!';
+}

package/examples/reviewer-eval/clean-extract/change.diff

@@ -0,0 +1,13 @@
+diff --git a/src/greet.ts b/src/greet.ts
+index 1c1e070..b768208 100644
+--- a/src/greet.ts
++++ b/src/greet.ts
+@@ -1,3 +1,7 @@
++function normalize(name: string): string {
++  return name.trim();
++}
++
+ export function greet(name: string): string {
+-  return 'Hello, ' + name.trim() + '!';
++  return 'Hello, ' + normalize(name) + '!';
+ }

package/examples/reviewer-eval/dropped-error/base/src/load.ts

@@ -0,0 +1,4 @@
+export async function loadConfig(read: () => Promise<string>): Promise<string> {
+  const raw = await read();
+  return raw.trim();
+}

package/examples/reviewer-eval/dropped-error/change.diff

@@ -0,0 +1,15 @@
+diff --git a/src/load.ts b/src/load.ts
+index 3da1e73..d7835c0 100644
+--- a/src/load.ts
++++ b/src/load.ts
+@@ -1,4 +1,8 @@
+ export async function loadConfig(read: () => Promise<string>): Promise<string> {
+-  const raw = await read();
+-  return raw.trim();
++  try {
++    const raw = await read();
++    return raw.trim();
++  } catch {
++    return '';
++  }
+ }