@navels/neal 0.2.0 → 0.3.0

package/docs/comparison.md

@@ -1,105 +0,0 @@
-# Why neal instead of X?
-
-neal is a harness, not an agent. It runs three independent roles — planner,
-coder, reviewer — each bound to whatever provider and model you choose
-([providers.md](providers.md)), and drives them with a deterministic state
-machine ([architecture.md](architecture.md)) rather than letting a model decide
-the control flow. Verdicts are schema-validated structured output, not prose an
-orchestrator model interprets. Every run is persisted under `.neal/` and
-resumable after a crash ([storage.md](storage.md)). The reviewer is read-only by
-construction: the provider registry rejects any reviewer capability that
-declares write or shell access, so a reviewer structurally cannot mutate the
-repo regardless of prompt. Most alternatives are agents; neal is the loop that
-holds agents accountable to a plan.
-
-## Claude Code
-
-What it's great at: interactive, conversational coding with a single very
-capable agent. Its subagents delegate work, plan mode gates execution behind an
-approved plan, and hooks let you inject your own checks into the tool loop.
-
-The structural difference: Claude Code is a single-vendor agent product.
-Its subagents are prompt-scoped delegates inside one product, sharing a vendor
-and orchestrated by a model — the top-level agent decides when to delegate and
-how to weigh what comes back. There is no cross-vendor adversarial review: the
-judge and the judged are the same vendor, often the same model family. neal is
-not a competitor to Claude Code; it is a consumer of it. The `anthropic-claude`
-adapter drives Claude Code's SDK as a coder or reviewer, and the common
-configuration is exactly the adversarial split Claude Code cannot express:
-Codex codes, Claude reviews, and a deterministic orchestrator — not a model —
-decides what happens with the verdict.
-
-Pick Claude Code when the work is exploratory or conversational, when you want
-a human in the loop turn by turn, or when you have no plan yet. neal wants a
-plan document; Claude Code is a good place to figure one out.
-
-## Aider (architect/editor mode)
-
-What it's great at: fast, terminal-native pair programming. Its
-architect/editor mode was an early demonstration that splitting reasoning from
-editing across two models improves results.
-
-The structural difference: Aider's two models cooperate on one change — the
-architect proposes, the editor applies — and the control flow between them is
-mediated by the models within a chat session. There is no independent reviewer
-producing a structured verdict that a state machine acts on, no scoped plan
-queue where each scope starts the coder from a fresh context, and continuity is
-conversation-shaped rather than a persisted run ledger. neal's roles are
-adversarial rather than cooperative: the reviewer judges committed diffs it had
-no hand in producing, findings route back to the coder until a schema-validated
-accept, and `neal resume` reconstructs an interrupted run from the `.neal/`
-ledgers rather than replaying a chat.
-
-Pick Aider for tight interactive edits where you are the reviewer and the loop
-is you. neal earns its overhead on multi-scope work where drift over a long
-session is the failure mode.
-
-## OpenHands and autonomous agents
-
-What they're great at: sandboxed, hands-off execution — hand an issue to an
-agent in an isolated runtime and come back to a pull request. The sandbox makes
-broad autonomy defensible.
-
-The structural difference: these systems bet on maximizing agent autonomy and
-containing it with a sandbox. neal bets the opposite way: local-first execution
-in your checkout, a human-authored plan as the contract for what may happen,
-and bounded autonomy with structural escalation — blocked states that wait for
-`neal resume --message`, manual gates for work only a human can do, and a
-bounded adjudicator that resolves a narrow recoverable class and escalates
-genuine walls. Even `--unattended` mode only bounds how long neal persists
-before failing cleanly; it never widens authorization.
-
-Pick an autonomous agent when you want isolation and don't need to constrain
-the path taken. Pick neal when the plan is the point — when you want to
-specify the decomposition, the verification per scope, and the stop conditions,
-and have the machine enforce them.
-
-## If you just want CI review
-
-PR-review bots comment on diffs after they reach the forge. neal's review is
-inside the loop: every scope's committed diff is judged before the run moves
-on, and a final-completion review checks the whole plan before the squash — so
-findings are fixed by the same coder in the same run, not triaged later.
-`neal review` also works standalone against any committed range, role-symmetric
-(the coder provider drafts findings, the read-only reviewer adjudicates them),
-local, and provider-agnostic — no forge integration or CI required. The two are
-complementary: neal reviews before you push, bots review after.
-
-## What neal does not do
-
-- **No GUI.** neal is a CLI with narrative terminal output; state lives in
-  files under `.neal/`.
-- **No sandbox of its own for the coder.** Writer providers run with broad
-  local permissions (Codex under `danger-full-access`, Claude under
-  `bypassPermissions`, the generic writer's `run` tool is unsandboxed shell).
-  Bring your own isolation — disposable checkout, container, or VM. See
-  [SECURITY.md](../SECURITY.md).
-- **Serial scopes only, today.** Scopes execute one at a time, and `neal run`
-  queues run plans serially. There is no parallel scope execution.
-- **It requires a plan document.** There is no "just fix it" mode — the
-  authored plan, with its mandatory `## Execution Shape` section
-  ([plan-format.md](plan-format.md)), is the product's opinion. If writing a
-  plan feels like overhead, neal is the wrong tool for that task.
-- **No provider plugins yet.** Adapters are built-in (`openai-codex`,
-  `anthropic-claude`, `openai-compatible`, `generic-agentic`); external
-  provider plugins are future work.

package/docs/issue-pipeline.md

@@ -1,124 +0,0 @@
-# GitHub Issue Pipeline
-
-Assign a GitHub issue to neal and get a reviewed pull request back. A maintainer
-applies a trigger label to an issue; a GitHub Actions runner turns the issue
-into a neal plan, runs neal's planner/coder/reviewer loop to completion, and
-opens a pull request assigned to a human — or reports back on the issue if neal
-blocks. Humans own merge; the pipeline never pushes to a protected branch.
-
-This is a self-hosting use of neal itself: neal already *is* the middle of the
-loop (cross-model review, deterministic gating, bounded recovery), so the
-pipeline is a thin trigger plus a thin publish around `neal run`.
-
-## What it does
-
-```
-maintainer applies the trigger label to an issue
-        │  (gate: the labeler must have write access — the issue author is irrelevant)
-        ▼
-issue title + body ──▶ seed .neal/PLAN.md ──▶ neal run --unattended
-        │                                        (Opus 4.8 writes, sol reviews each diff)
-        ├─ exit 0 ──▶ push neal/issue-<n>, open a PR, assign the maintainer
-        ├─ exit 2 ──▶ comment the blocker on the issue, keep the branch
-        └─ exit 3 ──▶ comment the failure on the issue, open no PR
-```
-
-The plan is seeded inside `.neal/` — wrapper-owned, gitignored territory — so
-it can never collide with a tracked file or appear in review diffs, and it is
-never committed. The refined plan travels with the outcome instead: the PR
-body (or the blocked/failed issue comment) embeds it in a collapsed details
-block, which outlives the 3-day `.neal/` artifact retention.
-
-The outcome also carries a cost ledger — per-provider turns, tokens, and
-dollars aggregated from the run's `RUN_METRICS-final*.json` files. Claude
-cost is provider-reported; reviewer cost is rate-computed from neal's
-vendored published rate card (see `docs/providers.md`) and marked as such.
-
-## Running an issue locally
-
-`scripts/neal-issue-local.sh <issue-number> [plan-doc]` is the pipeline's
-local twin for subscription billing: the coder rides the Claude CLI login and
-the reviewer the codex CLI login (per `~/.neal/config.yml`) instead of the
-API keys CI uses. It shares the plan seed and PR-body construction with
-`pipeline/run.sh` through `pipeline/lib.sh`, so a local run produces the same
-branch name, the same PR format, and the same embedded plan and cost ledger.
-The optional second argument substitutes a pre-authored plan (for example a
-`multi_scope` plan spanning several issues) for the seeded `one_shot` one.
-The script unsets `OPENAI_API_KEY`/`ANTHROPIC_API_KEY` for the run so a stray
-exported key cannot silently switch billing from subscription to API.
-
-Every run executes in its own git worktree under `<repo>-worktrees/issue-<n>`,
-branched from `origin/main`. Runs on different issues can proceed in parallel
-(git enforces one worktree per branch), and the main checkout stays free for
-your own work throughout. On success the worktree is removed after the push —
-the branch lives on the PR. On blocked/failed outcomes the worktree is kept:
-it is the resume state (`cd` in and `neal resume`). The practical concurrency
-cap is your subscriptions, not git: parallel runs share your Claude and
-ChatGPT rate limits.
-
-- **Coder:** Claude Opus 4.8 (`anthropic-claude` adapter, `ANTHROPIC_API_KEY`).
-- **Reviewer:** GPT-5.6-sol via the `openai-compatible` adapter pointed at the
-  OpenAI API (`OPENAI_API_KEY`). The reviewer judges neal-inlined diff/context;
-  it has no repository tools, which keeps the runner setup to two env vars and
-  no extra CLI.
-
-## Setup
-
-One-time, by a maintainer. The workflow no-ops safely until this is done.
-
-1. **Secrets** (repo → Settings → Secrets → Actions, on the `neal-pipeline`
-   environment): `ANTHROPIC_API_KEY` and `OPENAI_API_KEY`. Use short-lived,
-   minimally-scoped keys and rotate them (see Security below).
-2. **Environment**: create a `neal-pipeline` environment (Settings →
-   Environments). Optionally add required reviewers so each run needs a manual
-   click before the secrets are exposed — recommended for a public repo.
-3. **Reviewer model**: set the repo variable `NEAL_REVIEWER_MODEL` to the sol
-   model slug your OpenAI key serves. Before the first run, qualify it:
-   `neal compat --model <slug> --role reviewer --reference anthropic-claude`
-   (locally, with the same key). If sol is not reachable over the OpenAI
-   Chat Completions API, point `NEAL_REVIEWER_BASE_URL`/`NEAL_REVIEWER_MODEL` at
-   an endpoint that serves it, or switch the reviewer to the `openai-codex`
-   adapter in `pipeline/config.yml`.
-4. **Trigger label**: create a label (default `neal:go`; override with the repo
-   variable `NEAL_TRIGGER_LABEL`). Optionally set `NEAL_READY_LABEL` (e.g.
-   `ready-for-human`) to tag the PRs neal opens.
-5. **Branch protection**: protect `main` (require PR + review). The pipeline can
-   push `neal/issue-*` branches and open PRs, but must never be able to merge or
-   push to `main`.
-
-## Security model
-
-This runs on a public repository, so the trust boundary is "arbitrary internet
-text becomes instructions to an agent with push access." The controls:
-
-- **Maintainer-gated trigger.** The gate checks the *labeler's* repo permission
-  (`write`/`maintain`/`admin`), not the issue author. An untrusted issue cannot
-  start a run — only a maintainer applying the label can.
-- **Untrusted issue input.** The issue title/body are passed as environment
-  variables (never interpolated into a shell command) and written to the seed
-  plan with `printf '%s'`, so they cannot inject shell commands. neal then
-  treats the seed as plan input, refined through the planner/reviewer loop.
-- **Least privilege.** The workflow token can push `neal/issue-*` branches, open
-  PRs, and comment — nothing else. Branch protection keeps the human merge gate.
-- **Boundaries in the plan.** The seed forbids edits to `.github/**` /
-  `pipeline/**` and forbids reading or printing secrets — defense-in-depth on
-  top of the token scope.
-- **Secret exposure caveat.** The coder runs with shell in the runner, where
-  `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` live in the environment. A
-  prompt-injected coder could try to exfiltrate them; the maintainer gate is
-  what makes that acceptable (only a maintainer's labeled issue ever runs). Use
-  short-lived, minimally-scoped keys, the `neal-pipeline` environment's approval
-  gate, and rotate on any suspicion.
-
-## v1 limitations
-
-- **Seed shape is `one_shot`.** Best for well-scoped issues ("fix X", "add Y").
-  For large multi-part work neal's coder will split the scope into a sub-plan;
-  if it can't be done in scope, neal blocks and comments asking for a smaller
-  issue. Write issues with a clear, bounded objective for best results.
-- **Reviewer reads inlined context, not the repo.** The `openai-compatible`
-  reviewer judges the diff neal inlines, not the working tree. Switch to an
-  `openai-codex` reviewer (OS-sandboxed, repo-reading) once sol is confirmed on
-  that adapter's API path, if repo-reading review is wanted.
-- **No comment-driven iteration yet.** On a blocked run you re-apply the label to
-  retry; a maintainer-comment → `neal resume --message` loop is a v2 addition.

package/examples/compat/is-even-add-test/PLAN.md

@@ -1,30 +0,0 @@
-# Compat fixture: replace the placeholder test
-
-## Execution Shape
-
-executionShape: one_shot
-
-## Objective
-
-`src/is-even.js` exports a correct `isEven(n)` helper. Its test in
-`test/is-even.test.js` is only a placeholder that always fails
-(`assert.ok(false, ...)`).
-
-Replace the placeholder assertion with a real test that exercises `isEven` —
-asserting `isEven(4)` is `true` is enough — so the test suite passes. Keep the
-existing `test(...)` block; only the placeholder assertion needs to change.
-
-## Boundaries
-
-Allowed paths:
-
-- `test/is-even.test.js`
-
-Forbidden:
-
-- Do not edit `src/is-even.js` (it is already correct).
-- Do not add dependencies or new files.
-
-## Verification
-
-Run `node --test test/is-even.test.js`; it must exit `0`.

package/examples/compat/is-even-add-test/broken.diff

@@ -1,11 +0,0 @@
-diff --git a/test/is-even.test.js b/test/is-even.test.js
-index 52c2a94..0e9eec5 100644
---- a/test/is-even.test.js
-+++ b/test/is-even.test.js
-@@ -5,5 +5,5 @@ import { isEven } from '../src/is-even.js';
- 
- test('isEven identifies even numbers', () => {
-   // TODO: replace this placeholder with a real assertion on isEven.
--  assert.ok(false, 'TODO: replace this placeholder with a real test for isEven');
-+  assert.equal(isEven(4), false);
- });

package/examples/compat/is-even-add-test/good.diff

@@ -1,11 +0,0 @@
-diff --git a/test/is-even.test.js b/test/is-even.test.js
-index 52c2a94..28d1d73 100644
---- a/test/is-even.test.js
-+++ b/test/is-even.test.js
-@@ -5,5 +5,5 @@ import { isEven } from '../src/is-even.js';
- 
- test('isEven identifies even numbers', () => {
-   // TODO: replace this placeholder with a real assertion on isEven.
--  assert.ok(false, 'TODO: replace this placeholder with a real test for isEven');
-+  assert.equal(isEven(4), true);
- });

package/examples/compat/is-even-add-test/package.json

@@ -1,5 +0,0 @@
-{
-  "name": "@navels/neal-compat-is-even-add-test",
-  "private": true,
-  "type": "module"
-}

package/examples/compat/is-even-add-test/src/is-even.js

@@ -1,3 +0,0 @@
-// Trivial compat fixture: this helper is already correct. The work is to add a
-// real test in place of the placeholder.
-export const isEven = (n) => n % 2 === 0;

package/examples/compat/is-even-add-test/test/is-even.test.js

@@ -1,9 +0,0 @@
-import assert from 'node:assert/strict';
-import test from 'node:test';
-
-import { isEven } from '../src/is-even.js';
-
-test('isEven identifies even numbers', () => {
-  // TODO: replace this placeholder with a real assertion on isEven.
-  assert.ok(false, 'TODO: replace this placeholder with a real test for isEven');
-});

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

@@ -1,32 +0,0 @@
-# Compat fixture: fix the broken string helper
-
-## Execution Shape
-
-executionShape: one_shot
-
-## Objective
-
-`src/strings.js` exports several small string helpers. Exactly one of them is
-buggy: `reverse(s)` is supposed to return the string with its characters
-reversed, but it returns the string unchanged. The `reverse` test in
-`test/strings.test.js` fails because of this.
-
-Read `src/strings.js`, locate the faulty `reverse` helper, and make the smallest
-complete change so it returns the reversed string. Do not touch the other
-helpers, which already pass their tests.
-
-## Boundaries
-
-Allowed paths:
-
-- `src/strings.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/strings.test.js`; it must exit `0`.

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

@@ -1,12 +0,0 @@
-diff --git a/src/strings.js b/src/strings.js
-index c338691..fbfe71b 100644
---- a/src/strings.js
-+++ b/src/strings.js
-@@ -5,6 +5,6 @@ export const upper = (s) => s.toUpperCase();
- export const lower = (s) => s.toLowerCase();
- 
- // BUG: this does not actually reverse the string.
--export const reverse = (s) => s.split('').join('');
-+export const reverse = (s) => s.split('').join('-');
- 
- export const repeat = (s, n) => s.repeat(n);

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

@@ -1,12 +0,0 @@
-diff --git a/src/strings.js b/src/strings.js
-index c338691..d17fc16 100644
---- a/src/strings.js
-+++ b/src/strings.js
-@@ -5,6 +5,6 @@ export const upper = (s) => s.toUpperCase();
- export const lower = (s) => s.toLowerCase();
- 
- // BUG: this does not actually reverse the string.
--export const reverse = (s) => s.split('').join('');
-+export const reverse = (s) => s.split('').reverse().join('');
- 
- export const repeat = (s, n) => s.repeat(n);

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

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

package/examples/compat/reverse-grep-edit/src/strings.js

@@ -1,10 +0,0 @@
-// Trivial compat fixture: several string helpers live here. Exactly one of them
-// is buggy, so an agent must read/grep to locate the faulty function.
-export const upper = (s) => s.toUpperCase();
-
-export const lower = (s) => s.toLowerCase();
-
-// BUG: this does not actually reverse the string.
-export const reverse = (s) => s.split('').join('');
-
-export const repeat = (s, n) => s.repeat(n);

package/examples/compat/reverse-grep-edit/test/strings.test.js

@@ -1,15 +0,0 @@
-import assert from 'node:assert/strict';
-import test from 'node:test';
-
-import { lower, repeat, reverse, upper } from '../src/strings.js';
-
-test('upper/lower/repeat helpers are correct', () => {
-  assert.equal(upper('abc'), 'ABC');
-  assert.equal(lower('ABC'), 'abc');
-  assert.equal(repeat('ab', 3), 'ababab');
-});
-
-test('reverse returns the string reversed', () => {
-  assert.equal(reverse('abc'), 'cba');
-  assert.equal(reverse('neal'), 'laen');
-});