@navels/neal 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lee Nave
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,527 @@
+# neal
+
+[![CI](https://github.com/navels/neal/actions/workflows/ci.yml/badge.svg)](https://github.com/navels/neal/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/@navels/neal.svg)](https://www.npmjs.com/package/@navels/neal)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> **A source-first, multi-agent coding loop.** Separate **planner**, **coder**, and **reviewer** roles — each on the provider and model you choose — drive scoped, reviewed, crash-safe changes to your repository.
+
+![neal driving a planner/coder/reviewer run](https://raw.githubusercontent.com/navels/neal/main/assets/neal-demo.gif)
+
+neal is a source-first local planner/coder/reviewer loop for your repo. You write a plan; neal refines it with your configured planner role, runs each scope with your configured coder role, commits the result, and hands the diff to your configured reviewer role before moving on. When every scope is accepted, a final review pass checks the whole plan, and run artifacts stay under `.neal/` so interrupted work can resume.
+
+### What makes it interesting
+
+- **Roles, not one monolithic agent.** Planner, coder, and reviewer are independent, separately configurable roles — mix vendors and models per role (e.g. Codex codes, Claude reviews).
+- **The reviewer is read-only** — declared at provider registration and enforced mechanically in each adapter (OS sandbox for Codex, SDK tool allowlist for Claude, a neal-owned jailed toolset for OpenRouter models), pinned by a conformance test — never just prompt-deep. See [SECURITY.md](SECURITY.md) and [docs/providers.md](docs/providers.md).
+- **`neal compat`** — a built-in harness that qualifies any OpenAI-compatible / OpenRouter model across all three roles and emits a dated PASS/FAIL whitelist. See [docs/compatible-models.md](docs/compatible-models.md).
+- **Crash-safe and resumable** — every run's state and artifacts live under `.neal/`; `neal resume` continues an interrupted run.
+- **Bounded autonomous recovery** — neal resolves a class of reviewer/coder deadlocks itself, and escalates genuine blockers.
+
+For how the pieces fit together, see the [architecture overview](docs/architecture.md).
+Wondering how this differs from Claude Code, Aider, or OpenHands? See
+[docs/comparison.md](docs/comparison.md).
+
+**Contents:** [Quickstart](#quickstart) ·
+[Why neal exists](#why-neal-exists) ·
+[neal is built with neal](#neal-is-built-with-neal) ·
+[Installation](#installation) ·
+[Provider Setup](#provider-setup) ·
+[Command Tour](#command-tour) ·
+[Commands](#commands) ·
+[Exit Codes](#command-exit-codes) ·
+[Configuration](#configuration) ·
+[Artifacts](#artifacts-and-storage) ·
+[Plan Shape](#plan-shape) ·
+[Safety Notes](#safety-notes)
+
+## Quickstart
+
+```bash
+npm install -g @navels/neal
+neal setup          # pick providers for the coder and reviewer roles
+neal check          # verify config and provider readiness
+```
+
+The cheapest way to try neal is a single OpenRouter API key — no Codex or
+Claude subscription required: run `neal setup --provider generic-agentic
+--all-roles`, set `OPENAI_COMPATIBLE_API_KEY`, and pick a model from the
+[qualified-model whitelist](docs/compatible-models.md). The flagship
+configuration — Codex writes, Claude reviews — uses those two locally
+authenticated CLIs instead; see [Provider Setup](#provider-setup).
+
+From a Git repository with at least one commit, write a minimal plan and run
+it:
+
+```md
+# Add a project description
+
+## Execution Shape
+
+executionShape: one_shot
+
+## Objective
+
+Add a one-line project description to the top of README.md and keep the
+existing content unchanged.
+```
+
+```bash
+neal run PLAN.md
+```
+
+neal refines the plan through the planner/reviewer loop, executes each scope
+with a fresh-context coder, has the reviewer judge every diff before moving
+on, and persists run state under `.neal/` — interrupt it any time and
+`neal resume` continues where it stopped. Plan shapes, queues, and loops:
+[docs/plan-format.md](docs/plan-format.md). If something misbehaves:
+[docs/troubleshooting.md](docs/troubleshooting.md).
+
+## Why neal exists
+
+neal grew out of a large frontend upgrade (Ember 3.28 to Ember 5) where the agent would drift over time from its initial instructions, which led to me wanting to break up the work into smaller chunks and reset the agent context before each chunk. I also wanted to incorporate my typical manual workflow of having Claude review Codex's work, copy/pasting findings and responses until both agents were satisfied with the result, before reviewing myself. I settled on this flow for neal:
+
+- start with a plan of what work needs to be done and how to do it
+- neal sends this through the planner/reviewer loop to ensure it is broken into manageable chunks (aka scopes) and formatted for execution by neal
+- each scope is run through the coder/reviewer loop with the coder starting with a fresh context
+- when the reviewer is satisfied, neal moves on to the next scope with the previous scope committed
+- after all scopes are complete, the entire set of changes is run through the coder/reviewer loop a final time
+- if a scope is found to be too large, the coder can split it into a sub-plan
+- if the coder is blocked on something, it can consult the reviewer for assistance
+- if neal exits for any reason, `neal resume` will attempt to continue, prompting for direction if the coder was blocked
+- run artifacts and state are recorded in `.neal/`
+
+![neal execution flow](docs/assets/neal-execution-flow.png)
+
+The name comes from `anneal`: repeated controlled adjustment toward a more stable result.
+
+## neal is built with neal
+
+neal's development is its own primary proof. The blocked-handling redesign in
+this release — replacing an ad-hoc support loop with the unified, budgeted
+blocked adjudicator — was planned, implemented, and reviewed by neal driving
+itself: Codex wrote each scope from a fresh context, Claude reviewed every
+diff, and the run artifacts under `.neal/` were the working record. Much of
+the code and documentation in this repository was written by coding agents
+under human direction; the architecture, the judgment calls, and the final
+review are human.
+
+The public repository begins at a single squashed commit because the
+pre-release history carried private working context; it is preserved
+privately. From v0.1.0 forward, development happens in the open — including
+runs where neal maintains neal.
+
+## Installation
+
+```bash
+npm install -g @navels/neal
+```
+
+neal requires Node.js >= 22.13 and drives your configured provider CLIs/SDKs
+(OpenAI Codex, Anthropic Claude, or any OpenAI-compatible / OpenRouter model) —
+see [Provider Setup](#provider-setup). On Windows, run neal from WSL2 with the
+target repository on the Linux filesystem; direct PowerShell or cmd.exe
+operation is not a supported launch path.
+
+### Run from source / contribute
+
+```bash
+corepack enable && pnpm install && pnpm start -- help
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contributor setup, the development
+link, verification commands, CI gates, and canonical doc references.
+
+## Provider Setup
+
+neal delegates planning, coding, and reviewing to provider-owned local runtimes, selected by provider id in the `agent.coder.provider` and `agent.reviewer.provider` config keys. The planner inherits the coder provider/model unless `agent.planner` is configured explicitly. Each provider still owns its credentials, account state, model availability, permissions, quotas, and rate limits.
+
+| Provider id | Roles it serves | What you need | Docs |
+| --- | --- | --- | --- |
+| `openai-codex` | planner, coder, reviewer | Local OpenAI Codex runtime, authenticated through its own provider-owned setup | [docs/providers.md](docs/providers.md) |
+| `anthropic-claude` | planner, coder, reviewer | Local Anthropic Claude runtime, authenticated through its own provider-owned setup | [docs/providers.md](docs/providers.md) |
+| `openai-compatible` | reviewer only (API-only: no repository tools — neal inlines diff/artifact context — no session resume, no `effort`) | Any OpenAI-compatible Chat Completions endpoint (DeepSeek, OpenRouter, vLLM, and similar) via the `providers.openai_compatible` config block; env fallbacks `OPENAI_COMPATIBLE_BASE_URL`, `OPENAI_COMPATIBLE_API_KEY`, `OPENAI_COMPATIBLE_MODEL` | [docs/providers.md](docs/providers.md#openai-compatible-endpoints) |
+| `generic-agentic` | coder (and the inherited planner); reviewer through a read-only toolset | The same `providers.openai_compatible` block plus a strong tool-calling model | [docs/providers.md](docs/providers.md#generic-agentic-writer), [docs/compat.md](docs/compat.md) |
+
+For `generic-agentic`, neal owns the agentic loop and supplies its own file/search/shell tools, so the endpoint only needs reliable tool calling; its reviewer inspects the repository directly through read-only tools instead of judging inlined context — prefer it over `openai-compatible` for reviewer duty when the model calls tools reliably. It never persists provider sessions (`neal resume` restarts the interrupted scope from scratch in a fresh session) and runs with the same trust level as the other writer providers — its coder-role `run` tool is unsandboxed shell. Use paid tool-calling model slugs for coder duty; `:free` pools are reviewer-only. Before trusting a generic-agentic model with real work, qualify it with `neal compat` (see [docs/compat.md](docs/compat.md)) to confirm it can drive the full loop.
+
+Run setup once before first writer-run use:
+
+```bash
+neal setup
+```
+
+`neal setup` detects local runtime availability for built-in providers without making live provider calls, asks for coder and reviewer defaults, and writes explicit `agent.coder` and `agent.reviewer` provider/model settings to `~/.neal/config.yml`. The planner inherits coder by default; interactive setup asks before writing an explicit planner override. To script the same provider for every role:
+
+```bash
+neal setup --provider anthropic-claude --all-roles
+```
+
+When a model is omitted, setup writes `model: null` so the provider chooses its default model. Existing effective provider settings are not overwritten unless you confirm interactively or pass `--force`.
+
+Authenticate or configure each provider through its normal provider-owned local setup before running provider-backed workflows such as `neal plan`, `neal execute`, `neal run`, or `neal resume`. Neal does not collect or store provider credentials. Provider contract details are in [docs/providers.md](docs/providers.md). External provider adapters are future work.
+
+After setup, verify local config and provider readiness:
+
+```bash
+neal check
+```
+
+After the config passes, `neal check` prints the effective planner/coder/reviewer roles and prompts before sending one small prompt to each configured role for live connectivity verification. In non-interactive shells, it validates config and reports that live provider verification was skipped. Common setup and auth failures, with their exact messages and fixes, are collected in [docs/troubleshooting.md](docs/troubleshooting.md).
+
+## Command Tour
+
+Writer commands require a Git repository with an existing `HEAD` commit before
+provider execution. Create and commit the repository's initial baseline before
+asking neal to plan, run, execute, resume, or squash work.
+
+Use `neal plan` and `neal execute` separately when you want to review the
+normalized plan document before execution:
+
+```bash
+neal plan PLAN.md
+neal execute PLAN.md
+neal execute PLAN.md --no-squash
+```
+
+Refine and execute one or more plans serially:
+
+```bash
+neal run tmp/A.md tmp/B.md
+neal run --no-squash tmp/A.md tmp/B.md
+```
+
+Run headless (CI, cron, or a benchmark harness) with no operator available to
+answer an operator block:
+
+```bash
+neal execute PLAN.md --unattended
+neal run --unattended tmp/A.md tmp/B.md
+```
+
+Try the dependency-free in-repo example without provider calls:
+
+```bash
+pnpm --dir examples/issue-triage-js test
+```
+
+To run the same example through Neal after configuring providers:
+
+```bash
+neal setup
+neal check
+cd examples/issue-triage-js
+neal run PLAN.md
+pnpm test
+```
+
+See [examples/issue-triage-js/README.md](examples/issue-triage-js/README.md)
+for the example guide and safety notes.
+
+Resume interrupted work:
+
+```bash
+neal resume
+neal resume --run <run-id>
+```
+
+Give guidance only when `neal status` or `neal resume` says the selected run is waiting for it:
+
+```bash
+neal resume --run <run-id> --message "Keep the change bounded to the failing test and rerun the required validation gate."
+```
+
+Review already-committed work:
+
+```bash
+neal review --last 3
+neal review "Focus on auth/session handling." --since origin/main
+```
+
+Inspect status:
+
+```bash
+neal status
+neal status --run <run-id>
+neal status --json --run <run-id>
+neal status --all
+neal status --json --all
+```
+
+## Automation Contract
+
+neal keeps a stable machine-facing contract for driving it from scripts, CI, and benchmark harnesses: writer exit codes, the `neal status --json` classification schema, patch-submission eligibility, and harness timeout and trace-publishing guidance. See [docs/automation.md](docs/automation.md).
+
+## Commands
+
+```bash
+neal setup
+neal plan <plan.md> [--unattended]
+neal execute <plan.md> [--no-squash] [--unattended]
+neal run [--no-squash] [--unattended] <plan.md> [more-plans...]
+neal resume [--run <run-id>] [--message "..."]
+neal review [message] (--last <n> | --since <base>)
+neal squash [plan.md]
+neal check
+neal compat [--model <slug>] [--role coder|reviewer|planner|all] [--reference openai-codex|anthropic-claude|generic-agentic:<slug>] [--json]
+neal status [--json] [--run <run-id>]
+neal status [--json] --all
+neal version
+neal help
+neal --help
+neal -h
+```
+
+`neal plan` revises the target plan file in place and stores the original-plan backup at `.neal/runs/<run-id>/PLAN_ORIGINAL.md`.
+
+`neal execute` runs an already-ready plan. It requires a Git repository with at least one commit and no dirty work outside the selected plan document, and can edit files and create commits. When the selected plan document is repo-local, nonignored, and changed, neal may include it in the run's final tree through ordinary Git staging. Ignored, missing, non-file, or outside-repository plan documents are recorded as metadata only and are not force-added. Completed execute runs squash run-owned commits by default without confirmation; pass `--no-squash` to leave the individual commits in place.
+
+`neal run` refines each plan through the planning loop, then executes the accepted plan. It requires a Git repository with at least one commit and uses the same clean-worktree admission as `neal execute`: dirty work outside the selected plan document blocks writer-run start and queue continuation. Queue items run serially. The queue stops at the first blocked, failed, paused, or operator-attention run. Execution children use the same selected-plan-document handling as `neal execute`: eligible repo-local nonignored plan documents may land in the final run tree, while ignored or outside-repository plans remain metadata-only. Execution children squash completed run-owned commits by default; pass `--no-squash` to preserve per-scope commits.
+
+`neal resume` continues the selected writer run when it is mechanically resumable, including ordinary failed, paused, and stale-running states. With no `--run`, neal uses the current local run pointer. If the run is waiting for operator guidance, `neal resume` and `neal status` explain the blocker and print the exact `neal resume --run <run-id> --message "..."` command. `--message` is reserved for that waiting-guidance state.
+
+If a coder scope reaches expected human work that Neal cannot perform itself, the run can wait in `waiting_for_manual_gate`. `neal status` shows the gate title, reason, run-local `GATE-<id>.md` instructions file, last failed check if any, and the resume command. `neal resume --run <run-id>` runs the gate's configured noninteractive command checks before provider execution; failed checks keep the gate open, and passing checks clear the gate and resume the same coder scope. Manual gates do not use `neal resume --message`.
+
+### Unattended Mode
+
+`--unattended` (on `neal plan`, `neal execute`, and `neal run`) runs Neal
+headlessly — CI, cron, or a benchmark harness — when no operator is available:
+eligible blocks auto-resume for a small bounded number of turns with a fixed
+conservative guidance message, and the operator review gates fail cleanly and
+terminally (exit code `3`, produced artifacts left unsubmitted) instead of
+waiting for `neal resume --message`; verification, authorization, and the
+squash/grading paths are never weakened. The resolved value is persisted on run
+state, so a later `neal resume` and the `neal run` plan→execute hand-off keep
+the same behavior without re-passing the flag. The squash preference
+(`--no-squash`) is likewise persisted on run state across resume. See
+[config.yml](config.yml) for the `agent.unattended` config key (default
+`false`; the flag overrides it) and [docs/state-machine.md](docs/state-machine.md)
+for the operator-block and gate states.
+
+`neal review` never mutates your repository: candidate findings are drafted on the coder provider and judged by the read-only reviewer, and neal verifies after every provider call that the worktree and neal's own run state are byte-unchanged, failing the review otherwise. It uses neal's built-in adversarial review posture by default; the optional positional message is additive context. The selector is resolved when the command starts, and neal reviews commits ending at the current checkout `HEAD` for `--last` or `--since`. Dirty worktrees are allowed because the selected committed range is the review target. Accepted findings are printed to the terminal and written under `.neal/reviews/<review-id>/`.
+
+`neal squash` squashes run-owned commits for a completed plan. With no argument, it selects the latest completed execute-mode run with readable run-local state and uses that run's recorded plan doc. With a plan argument, it selects the latest completed execute-mode run for that plan. It preserves later commits added after the selected neal run by replaying them on top of the replacement squash commit. It previews the selected run, commit range, later commits to preserve, plan-document disposition, commit-message source, and generated semantic commit message, then requires interactive TTY confirmation before rewriting history. The replacement commit is signed when Git signing is configured for commits. Squash result artifacts keep Neal provenance separately from the Git commit message, including the run id, selected and normalized plan paths, plan-document disposition, replacement-tree inclusion, commit-message source, and commit-message subject.
+
+`neal setup` configures explicit coder and reviewer provider defaults for fresh writer runs, with an optional planner override. It reports local runtime availability, writes `~/.neal/config.yml` by default, preserves unrelated user config, and recommends provider-owned authentication followed by `neal check` after writing.
+
+`neal check` validates the effective config, reports the effective planner, coder, and reviewer provider/model choices, then prompts before making live provider connectivity calls. When the resolved **coder or reviewer** role uses a non-native (generic-agentic / openai-compatible) provider, it prints a one-line pointer to `neal compat`; native adapters (`openai-codex`/`anthropic-claude`) do not. (The planner inherits the coder provider by default, so the coder check already covers the common case; an explicitly configured non-native planner alongside native coder/reviewer is not separately flagged.)
+
+`neal compat` is a **compatibility smoke test, not a skill benchmark**: it answers whether an OpenAI-compatible model can drive neal's loop at all as a coder, reviewer, or planner. It reuses `neal check`'s structured pre-filter, then drives the candidate through complete neal runs against bundled trivial fixtures (`examples/compat/`) in throwaway git copies (it never mutates a committed fixture), and emits a binary PASS/FAIL matrix per (model, role) with a structural failure mode for each FAIL. `--model <slug>` runs the slug on the `generic-agentic` provider in the candidate role, and `--reference <id>` names a native provider (`openai-codex` default, or `anthropic-claude`) for the non-candidate roles so a FAIL is attributable to the candidate; `--role` defaults to `all`; `--json` prints a stable machine-readable matrix. It is fully self-contained — the only prerequisites are the neal repo and an API key — forces unattended mode so a model is never penalized for a resumable halt, and exits non-zero on an overall FAIL. See [docs/compat.md](docs/compat.md) for the PASS definition, failure-mode taxonomy, and `--json` schema, and [docs/compatible-models.md](docs/compatible-models.md) for the verified-model whitelist.
+
+`neal status` prints a human-readable summary by default. `neal status --all` lists writer runs from `.neal/runs/*/RUN_STATE.json`. `neal status --json` and `neal status --json --all` are the stable automation contracts. Runs waiting on manual gates report `effectiveStatus: "waiting_for_manual_gate"` and include a nullable `manualGate` summary with the gate instructions path and resume command.
+
+`neal version` prints the package version.
+
+`neal help`, `neal --help`, and `neal -h` print the supported usage surface, including the package version.
+
+## Command Exit Codes
+
+The writer commands `neal plan`, `neal execute`, `neal run`, and `neal resume`
+use this shell contract:
+
+- `0`: completed writer run, completed `neal run` queue, or resume selection
+  that was already done.
+- `1`: invalid CLI usage, missing setup or configuration, pre-run Git/worktree
+  precondition failure, or another thrown error before Neal has a writer result.
+- `2`: controlled incomplete state: blocked, waiting for operator guidance,
+  waiting for a manual gate, paused, already running under a live lock, or
+  manual-gate resume checks still failing.
+- `3`: failed writer run or failed `neal run` queue after Neal has run
+  state/result evidence.
+
+Use `neal status --json` for the stable detailed automation interface. `neal
+status` exits `0` when it successfully reports status, even if the reported run
+is blocked, paused, waiting for guidance, waiting for a manual gate, or failed.
+
+## Terminal Output
+
+neal prints narrative-focused progress by default. The default stream says what the loop is doing at a human level, while raw provider detail, command output, session handles, and reviewer context are kept out of the normal terminal view.
+
+Interactive TTY writer runs accept live keys:
+
+- `q`: stop after the current scope
+- `v`: switch between narrative and low-level detail views
+
+The read-only long-running `neal review` command also supports the `v` detail toggle. Toggling views is process-local terminal state only; provider prompts, run state, resume behavior, artifacts, and command semantics stay unchanged.
+
+Low-level detail is still persisted for debugging. Inspect `.neal/runs/<run-id>/stderr.log` and `.neal/runs/<run-id>/events.ndjson` for writer runs, or the corresponding review artifact directory for read-only review loops.
+
+## Configuration
+
+Config precedence is:
+
+1. repo `config.yml`
+2. `~/.neal/config.yml`
+3. built-in defaults
+
+Fresh writer-run commands require explicit `agent.coder.provider` and `agent.reviewer.provider` settings from either user or repo config. The built-in defaults remain for compatibility paths, but they are not enough to start new plan, execute, run, or check workflows. If either role is missing, neal reports the missing config key. Use `neal setup` for first-time provider/model defaults; edit YAML manually only when you need precise control.
+
+The checked-in [config.yml](config.yml) is a commented template. Machine-local overrides usually belong in `~/.neal/config.yml`.
+
+Manual writer-provider config shape:
+
+```yaml
+agent:
+  coder:
+    provider: openai-codex
+    model: null
+  reviewer:
+    provider: anthropic-claude
+    model: null
+```
+
+In that simple config, the effective planner role inherits the coder provider
+and model:
+
+```yaml
+agent:
+  planner:
+    provider: openai-codex
+    model: null
+  coder:
+    provider: openai-codex
+    model: null
+  reviewer:
+    provider: anthropic-claude
+    model: null
+```
+
+`model: null` means "let the provider choose its default model." You can keep other settings, such as `neal.notify_bin`, in the same file. neal currently ships built-in writer-run adapters for OpenAI Codex and Anthropic Claude, plus two adapters for OpenAI-compatible Chat Completions endpoints: the reviewer-only `openai-compatible` adapter and the `generic-agentic` writer adapter, which runs the coder role through a neal-owned agentic loop and tool set and the reviewer role through a read-only subset of those tools. See [docs/providers.md](docs/providers.md) for the provider contract, capability checks, telemetry/error mapping, and testing checklist.
+
+The reviewer role can target an OpenAI-compatible endpoint with a `providers.openai_compatible` block (DeepSeek shown; config first, environment fallbacks `OPENAI_COMPATIBLE_BASE_URL`, `OPENAI_COMPATIBLE_API_KEY`, and `OPENAI_COMPATIBLE_MODEL`):
+
+```yaml
+providers:
+  openai_compatible:
+    base_url: https://api.deepseek.com
+    api_key_env: DEEPSEEK_API_KEY
+    default_model: deepseek-chat
+
+agent:
+  coder:
+    provider: openai-codex
+    model: null
+  reviewer:
+    provider: openai-compatible
+    model: deepseek-chat
+```
+
+`openai-compatible` is reviewer/structured-advisor only: coder or planner selection fails the capability check, it has no repository tool access (neal inlines diff and artifact context into reviewer prompts, so the reviewer cannot independently run verification), no session resume, and no `effort` support. Behavior, model quality, and rate limits vary by upstream provider.
+
+Advanced configs can override the planner independently:
+
+```yaml
+agent:
+  planner:
+    provider: openai-codex
+    model: gpt-plan
+  coder:
+    provider: openai-codex
+    model: gpt-code
+  reviewer:
+    provider: anthropic-claude
+    model: null
+```
+
+Each role also accepts an optional `effort` reasoning-depth override. Omitting it
+or setting `effort: null` keeps the provider default. Supported values are
+`minimal, low, medium, high, xhigh` for `openai-codex` and
+`low, medium, high, xhigh, max` for `anthropic-claude`; an unsupported value is
+rejected before a run starts. Planner effort inheritance mirrors planner model
+inheritance: the planner inherits the coder effort only when
+`agent.planner.provider` is not configured explicitly and `agent.planner.effort`
+is omitted. When `agent.planner.provider` is set explicitly, an omitted
+`agent.planner.effort` resolves to the provider default (`null`), so set
+`agent.planner.effort` explicitly to override it.
+
+```yaml
+agent:
+  coder:
+    provider: openai-codex
+    model: null
+    effort: high
+  reviewer:
+    provider: anthropic-claude
+    model: null
+    effort: xhigh
+```
+
+### Custom Guidance
+
+neal supports additive guidance files for local preferences alongside the built-in protocol prompts:
+
+- `~/.neal/guidance/coder.md`
+- `~/.neal/guidance/reviewer.md`
+- `~/.neal/guidance/planner.md`
+
+Set `NEAL_GUIDANCE_DIR=/path/to/guidance` to load those same `coder.md`, `reviewer.md`, and `planner.md` files from another directory. neal records applied guidance roles, selected paths, and byte counts in run artifacts; guidance contents stay out of terminal output.
+
+## Artifacts And Storage
+
+Writer run artifacts live under `.neal/runs/<run-id>/`, including the original-plan backup at `.neal/runs/<run-id>/PLAN_ORIGINAL.md` and reviewer scratch space under `.neal/runs/<run-id>/scratch/`. Queue artifacts live under `.neal/queues/<queue-id>/`. Review findings artifacts live under `.neal/reviews/<review-id>/`.
+
+Reviewer scratch is for temporary verification artifacts, copied tests, scratch builds, logs, and modified throwaway files. Root-level scratch directories such as `build_review/` are still ordinary project-tree dirtiness and must be cleaned up by the operator or committed through the normal accepted-scope flow.
+
+Project-local `.neal/` is the source of truth for runs, queues, reviews, progress, and audit history. Keep `.neal/` ignored by Git. It may contain prompts, diffs, command output, local paths, provider responses, reviewer scratch files, copied tests, build logs, and project-specific context. Use `neal status --all` to discover run IDs, and use `--run <run-id>` to select a run for `resume` or `status`.
+
+For what may (and may not) be published from a run as public automation or benchmark traces, see [docs/automation.md](docs/automation.md).
+
+The storage layout, artifact classifications, run pointers, and retention guidance are documented in [docs/storage.md](docs/storage.md). Persisted run and queue state boundaries are documented in [docs/state-machine.md](docs/state-machine.md).
+
+## Known Limitations
+
+- Writer providers currently run with broad local permissions. See [docs/providers.md](docs/providers.md) and Safety Notes for the current provider permission boundaries.
+- neal stores project-local artifacts under `.neal/`. Those artifacts may contain prompts, diffs, command output, paths, provider responses, and local context; see [docs/storage.md](docs/storage.md) for artifact retention and privacy details.
+- External provider plugins are future work.
+- Provider accounts and authentication come from local provider SDK/CLI sessions.
+
+## Plan Shape
+
+Every executable neal plan must declare exactly one execution shape in a literal `## Execution Shape` section.
+The full executable-plan format reference is [docs/plan-format.md](docs/plan-format.md).
+
+Use `executionShape: one_shot` when the full task can be implemented, reviewed, and verified as one bounded scope:
+
+```md
+## Execution Shape
+
+executionShape: one_shot
+```
+
+Use `executionShape: multi_scope` when the work is a finite ordered queue:
+
+```md
+## Execution Shape
+
+executionShape: multi_scope
+
+## Execution Queue
+
+### Scope 1: Add parser support
+- Goal: Parse the new contract safely.
+- Verification: `pnpm typecheck`
+- Success Condition: The parser accepts valid input and rejects malformed input.
+
+### Scope 2: Add regression coverage
+- Goal: Lock the new behavior in with tests.
+- Verification: `pnpm test`
+- Success Condition: The new path is covered and existing shapes still pass.
+```
+
+Use `executionShape: multi_scope_unknown` when the work repeats one bounded recurring slice at a time, but the total number of slices is intentionally unknown until a stop rule becomes true.
+
+## Safety Notes
+
+Writer commands can edit files and create commits in the target repository. Run neal in a disposable checkout, branch, worktree, container, or VM when the repository or provider credentials are sensitive.
+
+Current writer providers run with broad local permissions. The OpenAI Codex provider is configured with `approvalPolicy: never` and `sandboxMode: danger-full-access`; the Claude provider uses `permissionMode: bypassPermissions`. Treat planner and coder providers as capable of modifying the checkout unless you have added external sandboxing. The reviewer role is read-only — OS-sandboxed for the Codex reviewer, and enforced at the SDK/tool-wiring level for the others, so outside Codex the guarantee is only as strong as the adapter. Reviewers can also read files outside the repository unless the adapter jails reads (only `generic-agentic` does); see [SECURITY.md](SECURITY.md).
+
+`neal execute` and `neal run` can create commits and rewrite run-owned commits into a final squash commit by default. Squashed commit messages are semantic summaries of the implemented project change; plan provenance is kept in Neal artifacts instead of commit subjects, bullets, or trailers. Repo-local nonignored selected plan documents may be included in the run's final tree when they changed. Ignored, missing, non-file, or outside-repository plan documents are metadata-only and are not force-added. `neal squash` rewrites history for plan-owned commits after printing a preview and receiving interactive confirmation. Neal rejects finalization and squash attempts that would include files matching `.gitignore` rules, even if those files were force-added.
+
+Read-only commands are intentionally narrower: `neal status` and `neal review` skip the writer lock. `neal review` writes only review artifacts under `.neal/reviews/`.
+
+Roles carry very different privilege: the coder role (and the inherited planner) executes shell commands and writes files with your privileges in the working directory, while the reviewer role is structurally read-only, enforced per provider adapter. Running an unknown or untrusted model in the coder role — for example via `neal compat` against an arbitrary OpenAI-compatible / OpenRouter slug — grants that model coder-level shell access, so run untrusted models inside a container or disposable sandbox. See [SECURITY.md](SECURITY.md) for the full trust model and how to report a suspected vulnerability.
+
+## Notifications
+
+Notifications are opt-in. If `neal.notify_bin` is configured, neal runs that command with the notification text for `blocked`, `complete`, `done`, and `retry`. With no configured path, notifications stay disabled.

package/SECURITY.md

@@ -0,0 +1,91 @@
+# Security
+
+neal is a local planner/coder/reviewer loop that delegates work to
+provider-owned agent runtimes on your machine. This document describes neal's
+trust model so you can run it safely, and how to report a suspected
+vulnerability.
+
+## Trust Model
+
+neal assigns providers to roles, and the roles have very different privilege
+levels. Understand this boundary before pointing neal at a sensitive repository
+or an untrusted model.
+
+### Coder role: full local privileges
+
+The coder role (and the planner, which inherits the coder provider by default)
+executes shell commands and writes files with the **invoking user's
+privileges** in the working directory. neal does not add its own sandbox around
+these providers:
+
+- The Claude coder runs with `permissionMode: bypassPermissions`.
+- The Codex coder runs with `approvalPolicy: never` and
+  `sandboxMode: danger-full-access`.
+- The `generic-agentic` coder drives a neal-owned agentic loop whose `run` tool
+  is unsandboxed shell.
+
+Treat any provider acting in the coder or planner role as capable of running
+arbitrary commands and modifying anything the current user can reach, unless you
+have added external sandboxing yourself.
+
+### Reviewer role: read-only
+
+The reviewer role is **read-only**, enforced in two layers:
+
+- **Declared capability.** Every provider definition must declare its reviewer
+  (structured-advisor) capability with `write:false, shell:false`; the registry
+  validates this at every provider resolution, so a writable reviewer
+  definition cannot be handed out.
+- **Adapter wiring.** Each adapter enforces the declaration mechanically:
+  - The Codex reviewer runs under `sandboxMode: read-only`, which Codex
+    enforces with an OS-level sandbox (Seatbelt on macOS, Landlock on Linux) —
+    the strongest guarantee of the four.
+  - The Claude reviewer is limited to the `Read`, `Grep`, and `Glob` tools at
+    the SDK level; no write or shell tool exists in the reviewer session.
+  - The `generic-agentic` reviewer is bound to a neal-owned read-only toolset
+    (`read_file`, `list_dir`, `grep`, and a read-only `git_diff` over a commit
+    range); write and shell tools are absent from that toolset by construction.
+  - The `openai-compatible` reviewer has no tools at all; it judges
+    neal-inlined context.
+
+Both layers are pinned by tests, including a registry-driven conformance test
+(`test/reviewer-readonly-conformance.test.ts`) that fails if a provider is
+registered without read-only wiring verification. Apart from the OS-sandboxed
+Codex reviewer, enforcement is process-level (SDK and tool wiring), not an
+external sandbox, so it is only as strong as the adapter and the runtime under
+it.
+
+**Read-only is not read-jailed.** Only the `generic-agentic` reviewer restricts
+*reads* to the repository (path-jailed, with symlink resolution). The Claude
+and Codex reviewers can read anything the invoking user can read — including
+files outside the repository such as `~/.ssh` or cloud credentials — and file
+contents they read are sent to the provider's API. On sensitive machines,
+follow the conservative guidance in the README
+[Safety Notes](README.md#safety-notes): run neal in a disposable checkout,
+branch, worktree, container, or VM.
+
+**`neal review` drafts with the coder.** The read-only `neal review` command
+judges findings with the read-only reviewer adapter, but the agent that
+*drafts* candidate findings runs on the coder provider with coder privileges.
+neal verifies after every drafting call that the worktree and neal's own run
+state are byte-unchanged and fails the review otherwise — detection, not
+prevention. See [docs/providers.md](docs/providers.md) for the exact guarantee
+split.
+
+### Untrusted or unknown models
+
+Running an unknown or untrusted model in the coder role — for example via
+`neal compat` against an arbitrary OpenAI-compatible / OpenRouter slug on the
+`generic-agentic` provider — grants that model **coder-level unsandboxed shell
+access** in the working directory. Run untrusted models inside a container or
+disposable sandbox; do not point a coder-role untrusted model at a repository or
+machine you care about.
+
+See [docs/providers.md](docs/providers.md) for the per-provider permission
+boundaries, capability checks, and adapter contracts.
+
+## Reporting a Vulnerability
+
+Please report suspected vulnerabilities **privately**, not in public issues. Use
+the GitHub repository's Security Advisories "Report a vulnerability" flow so the
+report stays confidential until a fix is available.