@navels/neal 0.2.0 → 0.3.0

package/docs/architecture.md

@@ -1,113 +1,109 @@
 # Architecture
 
-A one-page map of how neal is built. The deep contracts live in the linked docs;
-this page is the synthesis — how the run loop, the persisted state, the provider
-registry, and the prompt layer fit together.
-
-```
-            plan.md
-              │
-        ┌─────▼─────────────────────────────────────────────┐
-        │  Orchestrator  (src/neal/orchestrator.ts + phases/) │
-        │                                                     │
-        │   plan refinement ─▶ per-scope coder/reviewer loop  │
-        │        │                     │                      │
-        │        │                     ├─ split-plan (subdivide)
-        │        │                     └─ blocked recovery (adjudicated)
-        │        ▼                     ▼                      │
-        │   final-completion review ─▶ squash                 │
-        └───────┬─────────────────────────┬───────────────────┘
-                │                          │
-   roles ◀──────┤                          ├──────▶ persisted state
-   Provider     │                          │        .neal/ ledgers
-   registry     ▼                          ▼        (run + queue)
-   (planner / coder / reviewer)     prompt specs + structured rounds
-```
+neal drives a plan document through a deterministic state machine with
+planning and execution phases using coding agents in planner, coder, and reviewer roles.
+The planning phase has the planner and reviewer revise the plan until
+it has a valid execution shape, logical scopes, and a repository-grounded
+implementation approach at a level a person can still review. File-level
+discovery and local implementation choices stay in the execution phase.
+
+During the execution phase, the coder implements a scope of work
+with a fresh context, commits, and the reviewer checks the work. Any findings
+are fed back to the coder and addressed. This coder/reviewer loop continues
+until the reviewer is satisfied and execution proceeds to the next scope.
+Once all scopes are complete, the coder and reviewer make a final pass to
+review all the commits together. Finally, neal squashes all the work into a single commit.
+
+Each role (planner, coder, reviewer) has its own prompt-driven behavior
+and is backed by whatever provider (Anthropic, Codex, OpenRouter) and
+model you choose. Run state is saved under `.neal/` so that a run can be
+easily resumed without losing work in progress.
 
 ## 1. The run loop (orchestrator)
 
 `src/neal/orchestrator.ts` drives a deterministic state machine over a plan
 document. The phases live in `src/neal/orchestrator/phases/`:
 
-- **planning** — refines the authored plan into an executable shape
-  (`plan-refinement.ts`, `plan-validation.ts`; see
-  [plan-format.md](plan-format.md)) through its own planner/reviewer loop.
-- **coder** — runs one scope with the coder role from a fresh context, then
+- **planning:** uses its own planner/reviewer loop to refine the plan you wrote
+  into a human-reviewable shape neal can execute,
+  decides whether it is `one_shot`, `multi_scope`, or `multi_scope_unknown`,
+  and records that choice in the plan (`plan-refinement.ts` and
+  `plan-validation.ts`). See [plan-format.md](plan-format.md).
+- **coder:** runs one scope with the coder role from a fresh context, then
   commits.
-- **review** — hands the committed diff to the read-only reviewer role; findings
-  route back to the coder until accepted.
-- **recovery** — interactive/unattended blocked recovery is the single chokepoint
-  every block class funnels through, fronted by a bounded, read-only **blocked
-  adjudicator** (`adjudicator/blocked-adjudicator.ts`) that triages coder-blocked
-  signals, reviewer `review_stuck` deadlocks, and the split-plan invalid-payload
-  block. Under unattended runs it autonomously resolves a narrow recoverable class
-  (and escalates genuine walls); under attended runs it surfaces its verdict as
-  advice and yields.
-
-After every scope is accepted, a **final-completion review**
+- **review:** hands the committed diff to the read-only reviewer. Its findings
+  go back to the coder until the reviewer accepts the change.
+- **recovery:** when a run gets stuck, the consultant is engaged. This is a role
+  backed by the reviewer provider/model (`adjudicator/consultant.ts`):
+  it can inspect the run but never change it, and it gets only a limited number
+  of tries. There are three kinds of stuck:
+  the coder reports it can't proceed, the coder and reviewer keep going back and
+  forth without resolution, or a step that tried to break a
+  scope into a smaller plan produced a plan that wasn't valid. When the fix is
+  small and safe, the consultant returns a directive that neal applies, and the
+  run keeps going. Otherwise the run stops and waits for you, or fails cleanly
+  if it's running unattended.
+
+After every scope is accepted, a final-completion review
 (`final-completion-review.ts`) checks the whole plan, then neal squashes the run
-into a clean commit range.
+into a clean commit.
 
 ## 2. State and persistence
 
-Every run is **crash-safe and resumable** because all state is persisted under
-the project-local `.neal/` directory ([storage.md](storage.md)) via atomic writes
-(`atomic-write.ts`). Two ledgers:
+Every run is crash-safe and resumable, because all state is saved under the
+project-local `.neal/` directory ([storage.md](storage.md)) with atomic writes
+(`atomic-write.ts`). Two files hold that state:
 
-- **Run state** (`RUN_STATE.json`) — the phase/status state machine for a single
-  run, with documented invariants ([state-machine.md](state-machine.md)).
-- **Plan queue** (`plan-queue.ts`) — the ordered set of scopes and their
-  completion.
+- **Run state** (`RUN_STATE.json`): the phase and status of a single run, with
+  its invariants documented in [state-machine.md](state-machine.md).
+- **Plan queue** (`plan-queue.ts`): the ordered list of scopes and which ones
+  are done.
 
-`neal resume` (`resume-decision.ts`, `resume-planner.ts`) reconstructs an
-interrupted run from these ledgers — which is why a killed process never loses
-committed work. A per-run lock (`run-lock.ts`) prevents concurrent runs from
-colliding.
+`neal resume` (`resume-decision.ts`, `resume-planner.ts`) rebuilds an interrupted
+run from these files. A per-run lock (`run-lock.ts`) keeps two runs from colliding.
 
 ## 3. Providers and roles
 
-The three roles — planner, coder, reviewer — are bound to providers
-independently, so you can run different vendors/models per role. The provider
-**registry** (`src/neal/providers/registry.ts`) is where capabilities are
-declared and **enforced**:
+The three roles (planner, coder, reviewer) are each bound to a provider on their
+own, so you can run a different vendor or model for each one. The provider
+registry (`src/neal/providers/registry.ts`) is where each provider's capabilities
+are declared and enforced:
 
 - **Native adapters:** `openai-codex` and `anthropic-claude` wrap the vendors'
-  agentic SDKs (which own their tool loop and sandbox).
-- **`generic-agentic`:** a neal-owned agentic loop over any OpenAI-compatible /
-  OpenRouter model, with a jailed tool surface
-  (`providers/generic-agentic-tools.ts`).
-
-The key invariant: **the reviewer role is read-only by construction.** Every
-provider definition is checked at registration
-(`assertStructuredAdvisorReadOnly`) to declare `write:false, shell:false` for its
-structured-advisor (reviewer) capability — so a reviewer structurally cannot
-mutate the repo, regardless of prompt. See [providers.md](providers.md) and
-[SECURITY.md](../SECURITY.md) for the full trust model.
+  agentic SDKs, which own their own tool loop and sandbox.
+- **`openai-compatible`:** a neal-owned agent loop over any OpenAI-compatible or
+  OpenRouter model. File tools are jailed to the repository, while the coder's
+  shell tool is unsandboxed (`providers/openai-compatible-tools.ts`).
+
+The most important rule: the reviewer can't write, by construction. At
+registration, every provider is checked (`assertStructuredAdvisorReadOnly`) to
+confirm its reviewer capability declares `write: false` and `shell: false`. So a
+reviewer can't change the repo, no matter what the prompt says. See
+[providers.md](providers.md) and [SECURITY.md](../SECURITY.md) for the full trust
+model.
 
 ## 4. Prompts and adjudication
 
-Each role's behavior is defined by versioned **prompt specs**
-(`src/neal/agents/`, [PROMPT_SPECS.md](PROMPT_SPECS.md)) and run through shared
-**structured rounds** (`agents/rounds.ts`) that force schema-validated output
-(`agents/schemas.ts`). The coder/reviewer adjudication loop is inventoried in
-[ADJUDICATOR_INVENTORY.md](ADJUDICATOR_INVENTORY.md). Structured output is
-schema-enforced (not loose JSON), which is also how `neal compat` attributes a
-model's failures to the model rather than to transport noise.
+Each role's behavior comes from versioned prompt specs (`src/neal/prompts/`,
+[prompt-specs.md](prompt-specs.md)). They run through shared structured rounds
+(`agents/rounds.ts`) that force the model's output to match a schema
+(`agents/schemas.ts`). The full coder/reviewer loop is listed in
+[adjudicator-inventory.md](adjudicator-inventory.md).
 
 ## 5. Model qualification (`neal compat`)
 
-`neal compat` (`src/neal/commands/compat.ts`) is a self-contained harness that
-drives a candidate model through the planner/coder/reviewer roles on trivial
-bundled fixtures, classifies failures structurally (protocol vs structured-output
-vs behavior), and emits a PASS/FAIL matrix. It's how the dated
-[compatible-models.md](compatible-models.md) whitelist is produced, and it
-doubles as the live CI smoke for dependency bumps (see
+`neal compat` (`src/neal/commands/compat.ts`) is a self-contained harness. It
+runs a candidate model through the planner, coder, and reviewer roles on small
+bundled fixtures, sorts any failures into clear kinds (protocol,
+structured-output, or behavior), and prints a PASS/FAIL table. It's how the
+[compatible-models.md](compatible-models.md) whitelist gets made, and it also
+serves as the live CI smoke test when a dependency is bumped (see
 [maintenance.md](maintenance.md) and [compat.md](compat.md)).
 
 ## Where to go next
 
-- [plan-format.md](plan-format.md) — the executable plan contract
-- [state-machine.md](state-machine.md) — run/queue state invariants
-- [providers.md](providers.md) — provider adapter contract + extension checklist
-- [PROMPT_SPECS.md](PROMPT_SPECS.md) — prompt-spec ownership boundaries
-- [storage.md](storage.md) — the `.neal/` storage contract
+- [plan-format.md](plan-format.md): the executable plan contract
+- [state-machine.md](state-machine.md): run/queue state invariants
+- [providers.md](providers.md): provider adapter contract + extension checklist
+- [prompt-specs.md](prompt-specs.md): prompt-spec ownership boundaries
+- [storage.md](storage.md): the `.neal/` storage contract

package/docs/automation.md

@@ -1,12 +1,12 @@
-# Automation Contract
+# Automation contract
 
-This document is the machine-facing contract for driving neal from scripts,
-CI, and benchmark harnesses.
+The machine-facing contract for driving neal from scripts, CI, and benchmark
+harnesses.
 
 Noninteractive harnesses should run `neal execute <plan.md>` for an already
-accepted executable plan, or `neal run <plan.md>` when Neal should refine and
+accepted executable plan, or `neal run <plan.md>` when neal should refine and
 execute one or more plans as a serial queue. Use `neal resume --run <run-id>` to
-continue an interrupted writer run; pass `--message` only when status says the
+continue an interrupted writer run. Pass `--message` only when status says the
 run is waiting for operator guidance. After each writer command, classify the
 result from the process exit code plus `neal status --json --run <run-id>` when
 a run id is known. Use `neal status --json --all` only for run discovery and
@@ -32,15 +32,15 @@ The stable JSON classification fields are:
 - `commits`, `squash`, and `patch` for patch selection. `patch` includes the
   default-submission decision, reason, base/head/range, source, commit count,
   changed-file count, changed files, and unavailable reason.
-- `build` for reproducibility: Neal package version, Neal source Git SHA when
+- `build` for reproducibility: neal package version, neal source Git SHA when
   available, Node version, whether the values came from run `meta.json` or live
   fallback, and the persisted planner/coder/reviewer agent config.
 
 Default public patch submission is conservative. Submit automatically only when
-`patch.defaultSubmissionEligible` is true. Neal sets that only for clean
+`patch.defaultSubmissionEligible` is true. neal sets that only for clean
 completed execute runs with a non-empty readable patch range. Successful squash
-metadata is preferred (`squash.originalBaseCommit..squash.replacementCommit`);
-otherwise completed unsquashed execute runs use
+metadata is preferred (`squash.originalBaseCommit..squash.replacementCommit`).
+Otherwise completed unsquashed execute runs use
 `commits.initialBaseCommit ?? commits.baseCommit` through `commits.finalCommit`.
 Failed, blocked, paused, running, provider-error, waiting, timed-out,
 malformed-squash, pending-squash, unreadable-range, and empty-patch runs can
@@ -54,9 +54,9 @@ run-local `RUN_NARRATIVE.md` path reported at
 diffs, prompts, provider responses, or provider payloads as benchmark traces.
 
 Writer command exit codes (`0`, `1`, `2`, `3`) are defined in the README's
-[Command Exit Codes](../README.md#command-exit-codes) section.
+[Command exit codes](../README.md#command-exit-codes) section.
 
-Harnesses own wall-clock timeouts. Launch Neal in a process group, terminate
+Harnesses own wall-clock timeouts. Launch neal in a process group, terminate
 that group on timeout, wait a short grace period, and force-kill the group if it
 does not exit. When a run id is known, call `neal status --json --run <run-id>`
 after termination and record the wrapper timeout as the primary classification.

package/docs/compat.md

@@ -1,15 +1,15 @@
-# `neal compat` — model compatibility smoke test
+# `neal compat`: model compatibility smoke test
 
 `neal compat` answers one question per model: **can this OpenAI-compatible model
-drive neal's loop at all** — as a coder, a reviewer, or a planner? It is a
+drive neal's loop at all**, as a coder, a reviewer, or a planner? It is a
 **compatibility smoke test, not a performance benchmark**. There is no
 resolve-rate, no score, no ranking, and no real SWE-bench repo involved. The
-fixtures are deliberately trivial; any working agent should pass them. A failure
+fixtures are deliberately trivial. Any working agent should pass them. A failure
 therefore means something is **fundamentally wrong** with the model's ability to
-operate neal's contract — not that a task was hard.
+operate neal's contract. It does not mean a task was hard.
 
 `neal compat` is fully self-contained in the neal repo. The only things an
-operator needs to qualify a model are the neal checkout plus an API key — no
+operator needs to qualify a model are the neal checkout plus an API key: no
 external benchmark assets, no dataset download, no remote runner.
 
 ## Compatibility, not skill
@@ -18,7 +18,7 @@ external benchmark assets, no dataset download, no remote runner.
   tool calls + structured output, no max-step loops, no unresolved operator
   blocks, a clean finalization) **and** solve a trivial bundled fixture.
 - **Not measured:** skill. No resolve-rate, no scores, no rankings, no real
-  SWE-bench repos — trivial fixtures only.
+  SWE-bench repos, trivial fixtures only.
 - **Outcome:** a binary **PASS / FAIL per (model, role)**, with a structural
   failure mode recorded for every FAIL.
 
@@ -30,42 +30,42 @@ external benchmark assets, no dataset download, no remote runner.
   role's provider can answer one small structured probe
   (`provider_check_payload`). It proves *connectivity and basic protocol*, not
   that the model can complete a full neal run. When the resolved **coder or
-  reviewer** role uses a non-native (generic-agentic / openai-compatible)
-  provider, `neal check` prints a one-line pointer: *"This is a generic-agentic
+  reviewer** role uses the non-native `openai-compatible`
+  provider, `neal check` prints a one-line pointer: *"This is an openai-compatible
   model - run `neal compat` to confirm it can drive the full loop."* Native
   adapters (`openai-codex`, `anthropic-claude`) do not get the pointer. The
   planner inherits the coder provider by default, so the coder check covers the
-  common case; an explicitly configured non-native planner paired with native
+  common case. An explicitly configured non-native planner paired with native
   coder/reviewer is not separately flagged (run `neal compat --role planner`
   to qualify it).
 - **`neal compat`** runs the same structured pre-filter first (it reuses
   `check`'s `verifyConfiguredProviders`), then drives the model through complete
   neal runs against the bundled fixtures and produces a PASS/FAIL matrix.
 
-So: `neal check` is the cheap connectivity gate; `neal compat` is the full-loop
-qualification gate that `check` points generic-agentic users toward.
+So `neal check` is the cheap connectivity gate. `neal compat` is the full-loop
+qualification gate that `check` points openai-compatible users toward.
 
 ## Usage
 
 ```bash
-neal compat [--model <slug>] [--role coder|reviewer|planner|all] [--reference openai-codex|anthropic-claude|generic-agentic:<slug>] [--json]
+neal compat [--model <slug>] [--role coder|reviewer|planner|all] [--reference openai-codex|anthropic-claude|openai-compatible:<slug>] [--json]
 ```
 
 - `--role` (default `all`) selects which role(s) to test: `coder`, `reviewer`,
   `planner`, or `all`.
-- `--model <slug>` runs the slug on the **`generic-agentic`** provider in the
-  candidate role (provider forced to `generic-agentic`, any configured effort
+- `--model <slug>` runs the slug on the **`openai-compatible`** provider in the
+  candidate role (provider forced to `openai-compatible`, any configured effort
   dropped, so the slug drives a clean OpenRouter call). When omitted, the
   candidate role uses its configured provider/model unchanged.
 - `--reference <id>` names the provider for the **non-candidate** roles so a
   FAIL is attributable to the candidate in the tested role, not to a weak (and
-  possibly flaky) partner. Accepted forms: a native provider id — `openai-codex`
-  (the default when omitted while `--model` is set) or `anthropic-claude` — or
-  `generic-agentic:<openrouter-model>` to run the reference roles on an
+  possibly flaky) partner. Accepted forms: a native provider id (`openai-codex`,
+  the default when omitted while `--model` is set, or `anthropic-claude`), or
+  `openai-compatible:<openrouter-model>` to run the reference roles on an
   OpenRouter model. A bare model slug is rejected. Native reference roles run on
   that adapter's default model (`gpt-5.5` for `openai-codex`, `claude-opus-4-8`
   for `anthropic-claude`). Prefer a native reference for whitelist
-  qualification; see [compatible-models.md](compatible-models.md) for why
+  qualification. See [compatible-models.md](compatible-models.md) for why
   OpenRouter references proved unreliable as qualification partners. When
   **neither** `--model` nor `--reference` is given, every role stays on its
   configured provider/model (pure pass-through).
@@ -74,8 +74,10 @@ neal compat [--model <slug>] [--role coder|reviewer|planner|all] [--reference op
 
 The command resolves its base config via the same writer-provider resolver the
 other commands use, then derives a candidate config by cloning it and routing the
-tested role onto `generic-agentic` (when `--model` is set) and the non-candidate
-roles onto the native reference adapter (when either flag is set). It runs
+tested role onto `openai-compatible` (when `--model` is set) and the non-candidate
+roles onto the resolved reference provider: a native adapter at its default
+model, or `openai-compatible` at the slug from the
+`openai-compatible:<slug>` form (when either flag is set). It runs
 against **throwaway git copies** of the bundled fixtures and **never mutates** a
 committed fixture under `examples/compat/`. The process exits non-zero when the
 overall result is FAIL.
@@ -95,18 +97,29 @@ fixtures are:
 | Fixture | Roles | Contract surface |
 | --- | --- | --- |
 | `add-edit-verify` | coder, reviewer | edit + verify + commit |
-| `reverse-grep-edit` | coder, reviewer | read/grep-then-edit |
-| `is-even-add-test` | coder, reviewer | add-a-test |
+| `sum-grep-edit` | coder, reviewer | read/grep-then-edit |
 | `plan-greeting` | planner | emit a `one_shot` plan |
 
+Each fixture maps to a distinct way neal *directs* a model. A fixture that only
+varies the coding task (not the direction shape) would measure skill, which this
+command deliberately does not. That is why there are exactly three.
+
 Each coder fixture bundles buggy source, a test that fails against the buggy
 source, and a `PLAN.md` declaring `executionShape: one_shot` that describes the
 smallest complete fix. The reviewer fixtures reuse the same projects, each paired
 with two pre-made unified diffs (`good.diff`, `broken.diff`). The planner fixture
 provides an issue-statement seed (`ISSUE.md`) and no reviewer diffs.
 
+Fixture source and test files deliberately avoid any comment or claim that
+becomes false once `good.diff` applies (`// BUG: …`, "intentionally buggy",
+a stale `// TODO:`). A reviewer worktree is the project plus the applied diff, so
+such text is a real defect in the material under review and draws legitimate
+blocking findings on the known-good diff. The one exception is each fixture's
+`PLAN.md`, which describes the pre-fix state by definition and carries a fixture
+note saying so.
+
 `examples/issue-triage-js` remains an optional tier-2 "real-ish" check above the
-trivial gate; `neal compat` does not require it.
+trivial gate. `neal compat` does not require it.
 
 ### Manifest schema
 
@@ -132,27 +145,33 @@ trivial gate; `neal compat` does not require it.
 A planner fixture sets `"roles": ["planner"]` and provides `"issuePrompt"`
 instead of `reviewer`. Any fixture carrying the `reviewer` role must also define
 `verifyCommand`: reviewer fixtures reuse the coder project's command as the
-deterministic good/broken oracle — `goodDiff` must make it pass, `brokenDiff`
+deterministic good/broken oracle: `goodDiff` must make it pass, `brokenDiff`
 must make it fail. The `referenceFix` is used only by the structural fixture
 self-test (`test/compat-fixtures.test.ts`), never by a model run.
 
 ## Definition of PASS (per model, per role)
 
 Across **every** fixture for the role, the model must (1) **complete the run
-cleanly** — the run reaches `status: 'done'` (not `'failed'` / `'blocked'`), does
-not emit an `unattended.block_unresolved` event, and does not exceed its
-step/round budget — **and** (2) produce the **role-correct result**:
+cleanly** and (2) produce the **role-correct result**. A clean run reaches
+`status: 'done'` (not `'failed'` / `'blocked'`), does not emit an
+`unattended.block_unresolved` event, and does not exceed its step/round budget.
+The role-correct result is:
 
 - **coder:** `finalState.status === 'done'` **and** the fixture's
   `verifyCommand` exits `0` in the throwaway worktree (the failing test now
   passes).
 - **reviewer:** the review-findings loop converges (`outcome === 'accepted'`) for
-  **both** diffs, and the converged findings discriminate them: **zero** blocking
-  findings for the good diff and **≥1** blocking finding (a `ReviewFindingItem`
-  with `severity === 'blocking'`) for the broken diff. `outcome` alone is not
-  sufficient — it is `'accepted'` whenever the findings artifact converges,
-  including a zero-finding artifact — so the good/broken verdict is scored on
-  `draft.findings` severities.
+  **both** diffs, and the converged findings **discriminate** them. Counting
+  blocking findings (a `ReviewFindingItem` with `severity === 'blocking'`) per
+  diff, PASS iff `blocking(broken) >= 1` **and** `blocking(good) < blocking(broken)`.
+  Severity calibration is **not** graded: a reviewer may raise blocking findings
+  on the good diff and still PASS, as long as the broken diff draws strictly more.
+  A reviewer that blocks on neither diff, or equally on both, FAILs. `outcome`
+  alone is not sufficient (it is `'accepted'` whenever the findings artifact
+  converges, including a zero-finding artifact), so the verdict is scored on
+  `draft.findings` severities. The verdict is a **pair** verdict: both the good
+  and broken cells carry the same `pass`, and each carries its own
+  `blockingCount`.
 - **planner** (secondary): the emitted plan document validates via
   `validatePlanDocument` as a schema-conformant `one_shot` plan.
 
@@ -164,44 +183,48 @@ penalized for a halt that a human operator would simply have resumed.
 
 ## Failure-mode taxonomy
 
-Each FAIL records a mode derived from **structural run state** — `finalState.status`,
-emitted run events, `ReviewFindingsOutcome`, and `validatePlanDocument` — never
-from substring-matching model prose. When more than one applies, the earliest in
-this list (most specific cause first) is recorded:
+Each FAIL records a mode derived from **structural run state**
+(`finalState.status`, emitted run events, `ReviewFindingsOutcome`, and
+`validatePlanDocument`), never from substring-matching model prose. When more than
+one applies, the earliest in this list (most specific cause first) is recorded:
 
-- `protocol` — the `verifyConfiguredProviders` pre-filter threw for the candidate
-  (it could not emit one valid `provider_check_payload`); fixtures were skipped.
-- `provider_failed` — the run failed with a model-attributable provider error
+- `protocol`: the `verifyConfiguredProviders` pre-filter threw for the candidate
+  (it could not emit one valid `provider_check_payload`). Fixtures were skipped.
+- `provider_failed`: the run failed with a model-attributable provider error
   event (transport/auth/transient/other) rather than a clean completion, **except**
   a provider error whose `errorKind` is a structured-output kind, which is recorded
   as `structured_output` (below). This is also the bucket for a **writer** run that
-  ends `status: 'failed'` without a more specific structural signal — including
+  ends `status: 'failed'` without a more specific structural signal, including
   step/round-budget exhaustion, which the current runtime does not surface to compat
   as a distinct cap event, so writer step-cap exhaustion is reported here rather than
   as `max_step_loop`.
-- `block_unresolved` — the run emitted `unattended.block_unresolved` (the model
-  escalated to an operator block unattended mode could not resolve within budget),
-  or the review loop's outcome was `'blocked'`.
-- `max_step_loop` — the **reviewer** loop's outcome was `'cap_reached'` (the
+- `block_unresolved`: the run emitted `unattended.block_unresolved` (the model
+  escalated to an operator block that unattended mode could not resolve within
+  budget), or the review loop's outcome was `'blocked'`.
+- `max_step_loop`: the **reviewer** loop's outcome was `'cap_reached'` (the
   review-findings convergence cap was hit). Writer (coder/planner) step-cap
   exhaustion is not separately distinguishable under the current runtime and is
   classified as `provider_failed` (above).
-- `wrong_or_empty_output` — coder: the run reached `done` but `verifyCommand`
-  exited non-zero (or the diff was empty); reviewer: the verdict was wrong
-  (accepted the broken diff with no blocking finding, or flagged the good diff
-  with a blocking finding); planner: the emitted plan was not a schema-conformant
-  `one_shot` plan.
-- `structured_output` — the model could not produce or honor **schema-enforced**
+- `wrong_or_empty_output`. Coder: the run reached `done` but `verifyCommand`
+  exited non-zero (or the diff was empty); reviewer: the findings did not
+  discriminate the pair (no blocking finding on the broken diff, or the good diff
+  drew at least as many blocking findings as the broken one), recorded on both
+  cells of the pair; planner: the emitted plan was not a schema-conformant
+  `one_shot` plan. When one diff's review **failed** outright, the pair verdict is
+  unscoreable: that diff keeps its own failure mode and the other cell fails with
+  the same mode and a `pair unscoreable: …` detail, so the systematic cause is
+  what gets attributed.
+- `structured_output`: the model could not produce or honor **schema-enforced**
   JSON. This covers a reviewer/planner round whose payload failed schema validation
   (surfaced as the corresponding round error) **and** a coder/reviewer provider
   error whose `errorKind` is `structured_output_invalid` or
-  `structured_output_missing` — e.g. an OpenRouter (generic-agentic) gateway that
+  `structured_output_missing`, e.g. an OpenRouter (openai-compatible) gateway that
   rejects the `type: 'json_schema'` request (HTTP 400) or returns a missing/invalid
   object. This is distinct from `provider_failed` (transport/auth/other transport
   errors) and from `wrong_or_empty_output` (a syntactically valid verdict/output
   that was substantively wrong). Both the coder (`classifyWriterFailure`) and
   reviewer (`classifyReviewerThrownFailure`) paths attribute these kinds here.
-- `finalization_error` — the run failed during finalization/artifact writing, or
+- `finalization_error`: the run failed during finalization/artifact writing, or
   the run produced no final document where one was expected.
 
 When no structural signal is conclusive, `provider_failed` is recorded with the
@@ -220,20 +243,21 @@ whitelist (`docs/compatible-models.md`):
 
 ```jsonc
 {
-  "schemaVersion": 1,
+  "schemaVersion": 2,
   "model": "deepseek/deepseek-chat",   // candidate --model, or null when omitted
-  "reference": null,                    // native provider id (openai-codex | anthropic-claude), or null when omitted
+  "reference": null,                    // the --reference value as given: a native provider id (openai-codex | anthropic-claude), openai-compatible:<slug>, or null when omitted
   "role": "all",                        // coder | reviewer | planner | all
-  "candidateProviders": {               // provider each role used as the candidate: "generic-agentic" per role when --model is set, else the configured provider
-    "coder": "generic-agentic",
-    "reviewer": "generic-agentic",
-    "planner": "generic-agentic"
+  "candidateProviders": {               // provider each role used as the candidate: "openai-compatible" per role when --model is set, else the configured provider
+    "coder": "openai-compatible",
+    "reviewer": "openai-compatible",
+    "planner": "openai-compatible"
   },
   "cells": [
     {
       "role": "coder",                  // coder | reviewer | planner
       "fixtureId": "add-edit-verify",   // manifest id; "provider:<role>" for a protocol pre-filter FAIL
       "diffKind": null,                 // "good" | "broken" for reviewer cells, else null
+      "blockingCount": null,            // blocking findings on this diff; null for non-reviewer or errored cells
       "pass": true,
       "failureMode": null,              // one of the taxonomy modes when pass=false, else null
       "detail": null                    // human-readable explanation when pass=false, else null
@@ -251,6 +275,12 @@ whitelist (`docs/compatible-models.md`):
 }
 ```
 
+No tooling gates on `schemaVersion`. It exists so a stored report's scoring
+semantics are identifiable. Version `2` is the discrimination criterion described
+above plus `blockingCount`. Version `1` reports scored the reviewer on zero
+blocking findings for the good diff and retained no counts, so they cannot be
+re-scored.
+
 A role roll-up is PASS iff it has at least one cell and every one of its cells
 passed. `overallPass` is true iff every targeted role roll-up passed. The process
 exits non-zero when `overallPass` is false.
@@ -260,10 +290,10 @@ exits non-zero when `overallPass` is false.
 Cheap by construction: trivial fixtures and cheap models. If qualifying a model
 gets expensive, the fixture set is too big.
 
-## Phase B — building the whitelist
+## Phase B: building the whitelist
 
 With a provider configured (OpenRouter **paid** slugs only, never `:free`) and a
 known-good `--reference`, run `neal compat --model <slug> --role all --json` for
 each candidate and fill the dated [`compatible-models.md`](compatible-models.md)
-matrix from the JSON output. Date and version the matrix — model behavior drifts,
+matrix from the JSON output. Date and version the matrix. Model behavior drifts,
 so re-run on version bumps.