@navels/neal 0.1.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/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');
-});