@navels/neal 0.2.0 → 0.3.0

package/docs/release.md

@@ -1,13 +1,12 @@
-# Release Process
+# Release process
 
-This is the canonical tracked release guide for Neal. Releases are manual,
-versioned npm operations. Normal CI remains verification-only for pushes and
-pull requests; publishing is isolated to the GitHub Actions `Publish` workflow,
-which is triggered manually with `workflow_dispatch`.
+Releases are manual, versioned npm operations. Normal CI only verifies pushes
+and pull requests. The GitHub Actions `Publish` workflow handles publishing and
+runs only through `workflow_dispatch`.
 
-## Versioning Policy
+## Versioning policy
 
-Neal uses Semantic Versioning. `package.json.version` changes only in an
+neal uses Semantic Versioning. `package.json.version` changes only in an
 intentional release-preparation pull request, not in ordinary implementation
 commits. Release versions are exact SemVer strings without a leading `v`, and
 an npm version must never be reused.
@@ -23,10 +22,10 @@ Examples:
   changing documented behavior.
 - Minor before `1.0.0`: `0.2.0` adds a feature or meaningful behavior change
   while the public contract is still settling.
-- Major: `1.0.0` establishes the stable public contract; later breaking
+- Major: `1.0.0` establishes the stable public contract. Later breaking
   contract changes require `2.0.0`, `3.0.0`, and so on.
 
-## SDK Dependency Policy
+## SDK dependency policy
 
 Direct coding-agent and AI SDK runtime dependencies must use exact SemVer specs
 in `package.json`. Do not use `latest`, caret ranges, tilde ranges, wildcards,
@@ -41,12 +40,12 @@ published CLI package:
 
 An SDK update should land as a normal dependency pull request that updates both
 `package.json` and `pnpm-lock.yaml`, runs normal CI, and records any provider
-compatibility findings. The resulting Neal release should match the user-facing
+compatibility findings. The resulting neal release should match the user-facing
 impact: use a patch release for a compatibility fix that preserves documented
 behavior, a minor release for behavior changes before `1.0.0`, and a major
 release after `1.0.0` if a documented public contract breaks.
 
-## Local Release Readiness
+## Local release readiness
 
 Prepare a release with a normal pull request that changes `package.json.version`
 to the intended exact SemVer version:
@@ -71,7 +70,7 @@ availability, and checks remote `v<version>` tag availability when an `origin`
 remote is configured. Package verification confirms the built CLI and packed
 tarball.
 
-## Manual Publish Workflow
+## Manual publish workflow
 
 After the release-preparation pull request is merged and normal CI passes, run
 the `Publish` workflow manually from `main` with:
@@ -97,12 +96,12 @@ the real publish.
 
 The real-publish path is **staged**: the workflow runs `npm stage publish`,
 which places the version in a staged, not-publicly-available state. A
-maintainer then reviews and approves it with 2FA — `npm stage list`,
+maintainer then reviews and approves it with 2FA: `npm stage list`,
 `npm stage view <stage-id>` / `npm stage download <stage-id>`, and
 `npm stage approve <stage-id>` (or the npmjs.com UI). Nothing reaches `latest`
 without that human approval, so a compromised workflow cannot ship directly.
 
-## First-Publish History
+## First-publish history
 
 `0.1.0` was published manually on 2026-07-12 with an interactive 2FA publish
 from a maintainer terminal: npm trusted publishing cannot be configured for a
@@ -110,26 +109,26 @@ package that has never been published, so the first publish had to
 authenticate directly. Every release after `0.1.0` goes through the `Publish`
 workflow and the staged flow above.
 
-## Trusted Publishing Setup
+## Trusted publishing setup
 
 The publish workflow relies on trusted publishing/OIDC and intentionally has no
 npm-token fallback. It grants `id-token: write` for OIDC, keeps repository
 contents read-only, uses the `npm-publish` GitHub environment, and runs
 `npm stage publish` only on the real-publish path (staged publishing requires
-npm >= 11.15.0; the workflow upgrades npm accordingly).
+npm >= 11.15.0, so the workflow upgrades npm accordingly).
 
 The npm-side configuration for `@navels/neal`:
 
 - Publishing access: **Require two-factor authentication and disallow tokens**.
-  This blocks every traditional token permanently; trusted publishers are
+  This blocks every traditional token permanently. Trusted publishers are
   unaffected because they use OIDC, and staged approvals always require a
   maintainer's 2FA.
 - Trusted publisher: owner/repo `navels/neal`, workflow filename
   `publish.yml`, environment `npm-publish`, allowed action **`npm stage
-  publish` only** (stage-only; plain `npm publish` is deliberately not
+  publish` only** (stage-only, plain `npm publish` is deliberately not
   granted).
 
-## Release Boundaries
+## Release boundaries
 
 The current workflow checks that the remote `v<version>` tag is available, but
 it does not create tags or GitHub releases. Do not promise or perform release

package/docs/review-convergence.md

@@ -0,0 +1,246 @@
+# Plan-review convergence
+
+Plan review either converges or the run fails. The reviewer is asked "is this
+plan execution-ready?" fresh every round against a document that grows with each
+fix, so every individually-defensible new finding forces another full revision
+round. The only non-acceptance exits used to be terminal failures: reaching the
+round cap, and an unattended coder block. That produced two failure modes in
+real runs: long negotiations that keep re-litigating verification strength after
+the plan is already correct, and runs that terminally fail when a coder
+legitimately needs author input it must not fabricate.
+
+The convergence policy addresses both failure modes as **deterministic
+orchestration policy**, not prompt tuning. It never shortens a negotiation that
+surfaced a genuine plan-correctness defect, and only stops burning rounds on
+verification-hardening demands once the plan itself is correct. And a
+coder-authored plan-stage block no longer terminally fails: it lands as a
+recoverable blocked-with-reason state that an operator can answer via
+`neal resume --message` (see
+[Coder-authored plan-stage block recovery](#coder-authored-plan-stage-block-recovery)).
+
+The core round policy is a single pure function,
+`synthesizePlanReviewRoundFromFindings` in `src/neal/adjudicator/planning.ts`,
+shared by the runtime (`runPlanReviewPhase`) and by the fixture replay harness
+under `test/fixtures/plan-review-ledgers/` (see that directory's `SCHEMA.md`), so
+the policy pinned by the committed ledgers is exactly the policy that runs.
+
+## Finding classes
+
+Every plan-review finding carries a declared `findingClass`:
+
+- **`plan_correctness`**: the plan would build the wrong thing, build an
+  unverifiable thing, or contains an impossible or self-contradictory
+  instruction. These always force a revision round (or block at the cap). The
+  auto-generated plan-structure findings default to `plan_correctness`.
+- **`verification_hardening`**: the finding only demands strengthening *how the
+  plan will be verified* (more oracles, more pinning, more coverage of
+  already-specified behavior) without asserting the plan builds the wrong or an
+  unverifiable thing. Past the round threshold these can convert to recorded
+  debt instead of forcing another round.
+
+The class has two deliberately different boundaries:
+
+- **Reviewer-payload boundary (strict).** An *absent* class normalizes to
+  `plan_correctness`. A *present-but-invalid* class value is rejected exactly as
+  an invalid `severity` is: the sequential payload validator throws
+  `must be exactly one of: plan_correctness, verification_hardening`, so an
+  invalid class is a validation error, never a silent downgrade.
+- **Persisted-state boundary (tolerant).** When hydrating a saved run,
+  `hydrateFinding` maps a present-but-unknown class to `plan_correctness` and
+  leaves an absent class `undefined` (execute-review findings never carry a
+  class and must stay unaffected). Older run states load without error.
+
+The system-wide fail-safe does **not** depend on hydration filling absence: the
+decision sites convert only an *explicit* `verification_hardening`, so any
+absent/`undefined`/unknown class is always round-forcing (blocking).
+
+## The debt round threshold
+
+The knob `neal.plan_review_debt_round_threshold` (default **3**, read via
+`getPlanReviewDebtRoundThreshold(cwd)`) is the reviewer round at or past which a
+novel verification-hardening finding may convert to debt instead of forcing a
+round. Below the threshold, every blocking finding forces a revision round
+regardless of class. Early rounds are for genuine convergence, not banking.
+
+## Disposition policy
+
+For each round the policy partitions the merged open blocking findings
+(`classifyPlanReviewConvergence`) into `debtConvertible` and `roundForcing`:
+
+Pre-cap, a finding is `debtConvertible` only when **all** of:
+
+- its class is exactly `verification_hardening`
+- it is a **first occurrence** of its canonical (the minimum round across all
+  merged findings sharing that canonical equals the current round)
+- the current round is `>= threshold`.
+
+Everything else is `roundForcing`: any `plan_correctness`/absent/unknown class,
+**any repeat occurrence** of an existing canonical (a re-raised point still earns
+a dedicated round pre-cap), or any below-threshold round.
+
+From that partition:
+
+- **Arrival-time conversion.** A `debtConvertible` finding banks as `deferred`
+  plan-review debt the moment it arrives, even when a co-occurring
+  `plan_correctness` or repeat finding forces the round, so novelty-bounded
+  hardening asks never extend the round count.
+- **Accept-with-recorded-reservations landing.** When every open blocking
+  finding is `debtConvertible` and none is `roundForcing`, the round lands
+  accepted (`landAcceptedWithDebt`). It reuses the existing acceptance
+  transition (`accept_plan` → `done` for top-level plan review,
+  `accept_derived_plan` for a derived-plan review), so no adjudication-spec
+  outcome is added.
+
+Branch precedence in `resolvePlanReviewDisposition` is strict:
+
+1. convergence block (reopen / stall) →
+2. round-forcing blocking findings →
+3. accept-with-debt →
+4. open non-blocking findings →
+5. clean acceptance.
+
+Because `roundForcing` outranks `landAcceptedWithDebt`, a single open
+plan-correctness or repeat blocker keeps the round forced even when convertible
+hardening findings are present alongside it.
+
+## Cap behavior
+
+At the round cap (`round >= roundLimit`) there are no rounds left to force, so the
+convertible predicate becomes **class-only**: *every* open
+`verification_hardening` finding converts regardless of first-occurrence or
+threshold. The cap contract:
+
+- If the convergence block did **not** fire and *every* open blocking finding is
+  `verification_hardening`, the run lands accepted-with-debt (all convert).
+- If any open blocking finding is `plan_correctness` (or absent/unknown class),
+  the run terminal-blocks with the existing max-rounds reason.
+
+The convergence block keeps precedence at the cap too: a re-opened
+(`getReopenedCanonical`, ≥3 blocking rounds of one canonical) or stalled
+(`hasRepeatedUnresolvedBlockingCanonicals`) finding, *even hardening-class*,
+terminal-blocks rather than converting. So a re-litigated-but-not-reopened
+hardening point converts at the cap, but a genuinely stuck one still blocks.
+
+## Plan-review debt: two fields, two lifecycles
+
+Debt is modeled as a **canonical-keyed projection of the current findings**
+(`toPlanReviewDebt`), never an accumulator: for each canonical whose
+latest-round finding is a `deferred` `verification_hardening` finding, exactly
+one debt item is emitted (latest round wins, `originRound` = that finding's
+round). A banked canonical that later reopens, is fixed, or is rejected simply
+drops out of the projection. The lifecycle is automatic, with no stale or
+duplicate entries and no ad-hoc removal rule.
+
+There are two distinct top-level state fields:
+
+- **`planReviewDebt`**: the **current-negotiation** projection. Recomputed as
+  `toPlanReviewDebt(mergedFindings)` everywhere the current findings change
+  (`synthesizePlanReviewRound` / `runPlanReviewPhase` and
+  `runPlanningResponsePhase`). This is what a top-level plan run carries to the
+  queue on completion.
+- **`inheritedPlanReviewDebt`**: **durable, write-once**. Seeded only at init
+  from the queue handoff and **never recomputed by any plan-review phase**.
+
+Two fields are required because an *execution* child re-enters plan review: the
+execute runnable-phase registry includes `reviewer_plan`,
+`coder_plan_response`, and `coder_plan_optional_response`, so
+`runPlanReviewPhase` runs inside the execution child during split-plan recovery.
+If a single recomputed field were both seeded from the inherited debt and
+recomputed as `toPlanReviewDebt(mergedFindings)`, that derived-plan review would
+project only the derived plan's own findings and **erase** the inherited
+top-level debt before the next scope reviewer saw it. Keeping
+`inheritedPlanReviewDebt` write-once and untouched by any plan-review phase
+guarantees a derived-plan review in the execution child can only ever mutate
+`planReviewDebt`, never the inherited debt the execution reviewer actually needs.
+
+## Cross-run handoff (and its exclusion)
+
+Plan→execution handoff is **cross-run, not in-process**: `neal run` runs planning
+and execution as separate fresh child runs. The durable carrier is the
+`PlanAndExecuteQueueItem`:
+
+1. On planning-child completion, `completePlanningStage` copies
+   `finalState.planReviewDebt` onto the queue item alongside `acceptedPlanPath`
+   (covering both in-process completion and the cross-process resume through
+   `continuePlanAndExecuteQueueFromChildRun`).
+2. When the fresh execution child starts, `runFreshPlanAndExecuteChild` passes
+   the item's debt as the `inheritedPlanReviewDebt` init option **only** for the
+   execution stage. `createInitialState` seeds the durable
+   `inheritedPlanReviewDebt` state field from it (the recomputed `planReviewDebt`
+   always starts empty).
+3. `buildReviewerContextPacket` surfaces the inherited debt to the execution
+   reviewer as full items (`canonicalId`, `findingClass`, `originRound`,
+   `claim`, `requiredAction`) under a dedicated `## Inherited Plan-Review Debt`
+   section, not a bare count.
+
+**Exclusion (by design):** cross-run propagation is supported only inside a
+single `neal run` queue (planning child → execution child). A standalone
+`neal plan` run persists debt only in its own run record. A later
+`neal execute`/`neal run` against the accepted plan is a fresh run that
+re-reviews the plan and does **not** inherit that debt.
+
+## Where debt is visible
+
+- **`REVIEW.md`** (`renderReviewMarkdown`): each finding line carries
+  `- Finding class:` (with `n/a` for classless execute-review findings), and a
+  dedicated `## Plan Review Debt` section lists `Inherited:` and `Current:`
+  groups.
+- **`neal status`** (`buildStatusSnapshot` / `renderHumanStatusSnapshot`): a
+  `planReviewDebt` snapshot field sums both arrays with a per-item `inherited`
+  flag, rendered as a `Plan review debt:` line.
+- **Reviewer context packet**: the `## Inherited Plan-Review Debt` section
+  described above.
+
+## Coder-authored plan-stage block recovery
+
+The other non-acceptance exit is a plan-stage coder block. A coder-authored
+plan-stage **response** block (a `coder_plan_response` or
+`coder_plan_optional_response` block, the only plan-stage path that previously
+terminal-failed) lands as the documented blocked contract instead of a terminal
+failure. `finalizeBlockedPlanReviewResponse`
+(`src/neal/orchestrator/phases/planning.ts`) takes an explicit `blockCause`
+(`coder_authored` | `dirty_worktree` | `reviewer_convergence`), and for a
+`coder_authored` block on the top-level plan stage, in **both attended and
+unattended runs**, it:
+
+- persists `status: 'blocked'` with a durable `blockerReason` (the coder's
+  reported blocker), so the writer exits **2** (not `failed`/exit 3) and the
+  reason surfaces in both the JSON and human `neal status` renderings.
+- makes the block answerable via `neal resume --message`, reusing the existing
+  `pendingPlanReviewGuidance` channel and `runPlanningResponseAdjudication`
+  delivery. `recordPlanReviewGuidance`
+  (`src/neal/commands/recovery-guidance.ts`) maps the origin to the phase that
+  consumes the guidance: a `reviewer_plan` block still delivers to
+  `coder_plan_response` (unchanged), while a coder-authored response block returns
+  to its own origin phase (a `coder_plan_optional_response` block returns to
+  `coder_plan_optional_response`), so the re-run selects the right open findings
+  and delivers the guidance instead of accepting on an empty blocking set.
+  Recorded guidance forces a response adjudication even when a prior blocked
+  response closed every finding, so the operator's answer is never silently
+  discarded.
+
+The invariant is that `blockerReason` is `null` whenever `status !== 'blocked'`.
+The resume-planner blocked→running transitions clear it so it never outlives its
+block.
+
+Only `coder_authored` response blocks take this recoverable landing, and the
+durable `blockerReason` is the discriminator. A `dirty_worktree` safety block
+(the planner dirtied non-plan files with no operator to clean them) records no
+`blockerReason`: it lands at the same response phase but stays a normal blocked
+state: it is not reported or answerable as waiting for `--message` guidance, and
+it keeps its prior bare-resume behavior when a resumable planner session exists. A
+`dirty_worktree` safety block and reviewer cap/stall exhaustion (`reviewer_convergence`)
+under `unattended` keep terminal-failing (exit 3).
+
+**Exclusion (the initial `coder_plan` authoring block):** the author-input route
+does **not** cover the initial `coder_plan` block. That block already lands
+`status: 'blocked'` (exit 2, not a terminal failure) and stays resumable via a
+bare `neal resume`. Delivering an operator answer to a re-run authoring round
+would require a second guidance-delivery channel this policy deliberately avoids.
+Its `--message` route is a deliberate follow-up, not part of this policy.
+
+## Related references
+
+- `docs/plan-format.md`: executable plan shapes and normalization.
+- `docs/state-machine.md`: persisted run and queue state invariants.
+- `docs/adjudicator-inventory.md`: the shared coder/reviewer loop inventory.

package/docs/state-machine.md

@@ -1,29 +1,29 @@
-# Neal State Machine
+# State machine
 
 The product-level storage layout, artifact classifications, run pointers,
 retention guidance, and no-global-index decision are documented in
-[storage.md](storage.md). This document focuses on the persisted ledgers and the
-state invariants Neal enforces when reading and writing them.
+[storage.md](storage.md). What follows covers the persisted ledgers and the
+state invariants neal enforces when reading and writing them.
 
-Neal keeps two persisted ledgers:
+neal keeps two persisted ledgers:
 
 - `OrchestrationState` is the child-run ledger. It lives in each run directory as `RUN_STATE.json` and records one plan or execute writer run.
 - `PlanAndExecuteQueueState` is the parent queue ledger. It lives under `.neal/queues/<queue-id>/QUEUE_STATE.json` and tracks serial `neal run` children, their active stage, child run ids, and queue-level stop status.
 
-These ledgers are related but separate. A queue item points at child run state paths; child runs do not own the queue's status, item ordering, or current queue pointer.
+These ledgers are related but separate. A queue item points at child run state paths. Child runs do not own the queue's status, item ordering, or current queue pointer.
 
-## Hydration And Validation
+## Hydration and validation
 
-`src/neal/state.ts` owns v1 child-run hydration. It reads JSON, checks the basic shape, requires the current v1 fields Neal writes, and rejects unknown enum-like strings while hydrating phase references. Missing or malformed required child-run fields fail load instead of receiving invented defaults.
+`src/neal/state.ts` owns v1 child-run hydration. It reads JSON, checks the basic shape, requires the current v1 fields neal writes, and rejects unknown enum-like strings while hydrating phase references. Missing or malformed required child-run fields fail load instead of receiving invented defaults.
 
 `src/neal/state-invariants.ts` owns semantic validation after hydration and before save. `assertValidOrchestrationState` is pure: it has no filesystem, git, provider, logger, or clock dependency. The same invariant layer runs when `loadState` returns hydrated state and when `saveState` builds the timestamped next state.
 
 Queue state has its own parser and invariants in `src/neal/plan-queue.ts`, centered on `parsePlanAndExecuteQueueState` and related queue item parsing helpers.
 
-## Schema Versions
+## Schema versions
 
-Persisted JSON that Neal reads as durable schema is versioned at v1.
-`RUN_STATE.json` hydrates through `normalizeStateV1`; `.neal/current.json`,
+Persisted JSON that neal reads as durable schema is versioned at v1.
+`RUN_STATE.json` hydrates through `normalizeStateV1`. `.neal/current.json`,
 queue state, `.neal/current-queue.json`, queue child links, run narratives,
 squash audit results, and the active writer lock all have v1 write shapes or
 parsers.
@@ -32,7 +32,7 @@ Run `meta.json` is support data, not child-run state. Optional context artifacts
 such as `plan-progress.json` are written as v1 and read defensively so malformed
 or unsupported support data does not replace the canonical run ledger.
 
-## State Views And Public Lifecycle
+## State views and public lifecycle
 
 Persisted v1 child-run state remains record-shaped, but most callers should not
 treat `OrchestrationState` as one large nullable programming model.
@@ -55,7 +55,7 @@ human output can say `waiting_for_guidance`, `paused`, `blocked`, `failed`, or
 fields such as `effectiveStatus`, `waitingForOperatorGuidance`, and
 `pendingOperatorGuidance`.
 
-## Phase And Status
+## Phase and status
 
 Known child-run phases and statuses are centralized in `state-invariants.ts` through `ORCHESTRATION_PHASES`, `ORCHESTRATION_STATUSES`, and their runtime guard helpers. Runnable dispatch is authored in `src/neal/orchestrator/run-loop.ts` as purpose-specific registries for plan, execute, interactive recovery, and execute finalization phases. Those registries are composed into `RUNNABLE_PHASE_REGISTRY` for dispatch and exposed through top-level-mode helpers so tests can assert which phases are runnable for plan and execute runs.
 
@@ -68,16 +68,18 @@ The enforced phase/status relationship is intentionally small:
 
 Read-only `neal review` is not a writer-run mode. It writes isolated findings artifacts under `.neal/reviews/<review-id>/` and does not create `OrchestrationState`.
 
-## Recovery State
+## Recovery state
 
 Interactive blocked recovery is owned by `interactiveBlockedRecovery` while the active phase is `interactive_blocked_recovery`. The invariant layer validates execute-mode ownership, supported source phases, bounded turn counters, contiguous turn numbers, and disposition result phases.
 
-Every block class — coder-blocked signals, reviewer `review_stuck` deadlocks, and
-the split-plan invalid-payload block — funnels through the single
-`enterInteractiveBlockedRecovery` chokepoint, where the generalized blocked
-adjudicator triages it (see Site A below). The adjudicator is read-only: it never
-grants authorization, expands scope, or waives verification gates. Its verdict
-auto-acts only under unattended runs; attended runs surface it as advice and yield.
+Every block class (coder-blocked signals, reviewer `review_stuck` deadlocks, and
+the split-plan invalid-payload block) funnels through the single
+`enterInteractiveBlockedRecovery` chokepoint, where the consultant triages it (see
+Site A below). The consultant is read-only: it never grants authorization, expands
+scope, or waives verification gates. A recoverable verdict acts automatically under
+both run modes. The modes differ only on a non-recoverable verdict, which finalizes
+the run terminally under unattended runs and yields to the operator (carrying the
+verdict as advice) under attended runs.
 
 Public resume eligibility is classified by `src/neal/resume-decision.ts` before
 any recovery mutation. That read-only decision layer combines loaded child-run
@@ -91,7 +93,7 @@ selected actions only after the selected run has been classified as executable.
 `state-invariants.ts` mirrors the allowed phase sets so changes to recovery
 behavior are visible in focused tests.
 
-## Unattended Mode
+## Unattended mode
 
 `--unattended` / `agent.unattended` resolves to a persisted
 `OrchestrationState.unattended` boolean (default `false`) for both plan and
@@ -99,17 +101,17 @@ execute top-level modes, so a separate `neal resume` process and the `neal run`
 plan→execute hand-off see it without re-passing a flag. The flag overrides the
 config key. The resolved value is also threaded into the planner, reviewer,
 coder, final-completion, and plan-reviewer prompts, where it adds one autonomy
-line only when true; with `unattended` false the rendered prompts are
+line only when true. With `unattended` false the rendered prompts are
 byte-identical to attended output.
 
-Unattended changes only the three structural operator-block sites; it never
+Unattended changes only the three structural operator-block sites. It never
 weakens verification, authorization, or squash/grading, and never removes
 `block_for_operator` from any decision surface. Every unattended branch gates on
 structural state (`state.unattended`, `actionResolution.effectiveAction`,
 `phase`, `blockedFromPhase`, the bounded auto-resume counter), never on
 substring-matching assistant or guidance text.
 
-- **Site A — execute-mode interactive recovery.** All fresh blocks funnel
+- **Site A: execute-mode interactive recovery.** All fresh blocks funnel
   through `enterInteractiveBlockedRecovery` (`src/neal/orchestrator/phases/recovery.ts`).
   Under unattended, while `unattendedAutoResumeCount < UNATTENDED_MAX_AUTO_RESUMES`
   (a module constant, reconciled so it never pushes past
@@ -119,46 +121,46 @@ substring-matching assistant or guidance text.
   message uses, increments the persisted counter, and lets the run proceed into
   the recovery phase. Past the cap (or the `maxTurns` boundary) it runs the
   shared terminal-fail action instead of waiting.
-- **Generalized blocked adjudicator (bounded, both modes).** Inside
+- **The consultant (bounded, both modes).** Inside
   `enterInteractiveBlockedRecovery`, *before* the generic auto-resume / yield
-  decision, eligible blocks are triaged by a read-only adjudicator
-  (`runBlockedAdjudicator`, in `src/neal/adjudicator/blocked-adjudicator.ts`,
+  decision, eligible blocks are triaged by the read-only consultant
+  (`runConsultant`, in `src/neal/adjudicator/consultant.ts`,
   running through the same no-write reviewer plumbing the review/final-completion
   reviewers use, making zero commits and zero file edits). Eligible source phases
-  (`ADJUDICATOR_ELIGIBLE_SOURCE_PHASES`) are the coder-block phases (`coder_scope`
+  (`CONSULTANT_ELIGIBLE_SOURCE_PHASES`) are the coder-block phases (`coder_scope`
   / `coder_response` / `coder_optional_response`, which also carry the split-plan
   invalid-payload block) and the reviewer `review_stuck` phases (`reviewer_scope` /
-  `reviewer_plan`). The adjudicator first applies an anti-thrash guard
+  `reviewer_plan`). The consultant first applies an anti-thrash guard
   (`recentBlocks`, keyed on scope identity + source phase + normalized blocker key +
   evidence fingerprint): a same-scope repeat with no new evidence short-circuits to
   `recoverable:false` without an LLM round. Otherwise it returns a verdict
-  `{ recoverable, triageCategory, resolutionDirective, rationale }`. Under
-  unattended, a `recoverable` `misunderstanding` verdict with a concrete in-scope
-  directive enters recovery with that directive injected as the pending turn
-  (consumed exactly like a human `neal resume --message`); a `recoverable:false`
-  genuine wall (`authorization` / `external_precondition` / `impossible_task`) runs
-  the shared terminal-fail action. Under attended, the same gated adjudicator runs
-  read-only, persists its verdict as `interactiveBlockedRecovery.adjudicatorAdvice`,
-  and the run yields for the operator (no auto-apply). It is bounded by the counter
-  `reviewStuckArbiterCount` against the `review_stuck_arbiter_max_attempts` knob
-  (default `1`, `0` disables) -- a SEPARATE budget that never touches
+  `{ recoverable, triageCategory, resolutionDirective, rationale }`. A `recoverable`
+  `misunderstanding` verdict with a concrete in-scope directive enters recovery with
+  that directive injected as the pending turn (consumed exactly like a human
+  `neal resume --message`) under both run modes. The modes differ only on a
+  `recoverable:false` genuine blocker (`authorization` / `external_precondition` /
+  `impossible_task`): unattended runs the shared terminal-fail action, while attended
+  persists the verdict as `interactiveBlockedRecovery.consultantAdvice` and yields for
+  the operator. It is bounded by the counter
+  `consultantAttemptCount` against the `consultant_max_attempts` knob
+  (default `1`, `0` disables). It's a separate budget that never touches
   `unattendedAutoResumeCount` or `interactiveBlockedRecovery.maxTurns`. Every other
   case (ineligible source phase, disabled/exhausted cap, turn cap, or any
-  adjudicator error) falls through to the generic auto-resume / yield path
-  unchanged, writing neither `recentBlocks` nor `adjudicatorAdvice`.
+  consultant error) falls through to the generic auto-resume / yield path
+  unchanged, writing neither `recentBlocks` nor `consultantAdvice`.
   The decisions are auditable from the structured event log via the
-  `review_stuck_arbiter.{start,verdict,resolved,declined,exhausted}` events, which
+  `consultant.{start,verdict,resolved,declined}` events, which
   carry `scopeNumber`, `sourcePhase`, `blockedReason`, and (on `verdict`/`resolved`)
   `recoverable`, `triageCategory`, `targetCanonicalIds`, and the post-increment
-  `reviewStuckArbiterCount`.
-- **Sites B and C — final-completion review and the top-level plan-review gate.**
+  `consultantAttemptCount`.
+- **Sites B and C: final-completion review and the top-level plan-review gate.**
   These gates block directly (bypassing the recovery chokepoint), and their own
-  budgets — the final-completion continue-execution cap and the
-  review-round/convergence cap — already bounded the autonomous effort. Under
+  budgets (the final-completion continue-execution cap and the
+  review-round/convergence cap) already bounded the autonomous effort. Under
   unattended they run the shared terminal-fail action immediately rather than
-  saving `status:'blocked'`; there is no auto-resume and no synthesized
+  saving `status:'blocked'`. There is no auto-resume and no synthesized
   `pendingPlanReviewGuidance`. Site C edits only the `topLevelMode !== 'execute'`
-  branch of `finalizeBlockedPlanReviewResponse`; execute-mode derived-plan-review
+  branch of `finalizeBlockedPlanReviewResponse`. Execute-mode derived-plan-review
   blocks (`topLevelMode === 'execute'`) re-enter site A and are handled there.
 
 The shared terminal-fail action is `persistUnattendedBlockUnresolvedFailure`
@@ -167,14 +169,14 @@ The shared terminal-fail action is `persistUnattendedBlockUnresolvedFailure`
 `phase`/`blockedFromPhase` for diagnostics), re-render execution artifacts, write
 a `failed` checkpoint retrospective, and emit the classified
 `unattended.block_unresolved` log event (`reason:'unattended_block_unresolved'`
-plus the `UnattendedBlockSite` origin) — deliberately without `notifyBlocked`,
+plus the `UnattendedBlockSite` origin), deliberately without `notifyBlocked`,
 which is the attended wait notification. The run exits with writer code `3`, and
 any produced diff/plan is left unsubmitted as an artifact. There is no top-level
-reason field on `OrchestrationState`; the classification rides the log event and
+reason field on `OrchestrationState`. The classification lives in the log event and
 retrospective. Attended runs are unchanged and still wait for
 `neal resume --message` at all three sites.
 
-## Resume Planning
+## Resume planning
 
 New-run initialization and existing-run resume reconciliation are separate.
 `loadOrInitialize` still provides the command-facing entrypoint, but resume
@@ -198,10 +200,10 @@ normalization, event logging, pointer writes, and execution artifacts.
 when the shared decision says interactive recovery is waiting for guidance.
 Pending guidance resumes with plain `neal resume --run <run-id>`. Queue
 continuation still belongs to `continuePlanAndExecuteQueueFromChildRun` after
-the resumed child run finishes; selecting a child run for resume does not
+the resumed child run finishes. Selecting a child run for resume does not
 advance or repair the parent queue by itself.
 
-## Derived Plans
+## Derived plans
 
 Derived-plan fields are child-run state because they describe replacement execution for the active child run, not the parent queue. The invariant layer enforces these ownership rules:
 
@@ -212,23 +214,23 @@ Derived-plan fields are child-run state because they describe replacement execut
 
 Derived-plan execution should continue to flow through the existing orchestrator transition helpers before any future shape refactor changes the persisted fields.
 
-## Final Completion
+## Final completion
 
-Final-completion review is execute-mode only. The `final_completion_review` phase requires a `finalCompletionSummary`. When a reviewer verdict exists, `finalCompletionResolvedAction` must match the effective action, including the continue-execution cap case where Neal resolves to operator blocking instead of starting another scope.
+Final-completion review is execute-mode only. The `final_completion_review` phase requires a `finalCompletionSummary`. When a reviewer verdict exists, `finalCompletionResolvedAction` must match the effective action, including the continue-execution cap case where neal resolves to operator blocking instead of starting another scope.
 
 When final completion review asks to continue execution, the orchestrator may clear summary and verdict fields and reopen `coder_scope`. That reopened running state is valid.
 
-Accepted execute scopes also pass through execute finalization before Neal either opens the next scope or starts final-completion review. The persisted internal runnable cursor for that step is `execute_finalization`, which is separate from the public `neal squash` command. Public `neal squash` is a post-run command with selection, preview, and interactive TTY confirmation before it rewrites history.
+Accepted execute scopes also pass through execute finalization before neal either opens the next scope or starts final-completion review. The persisted internal runnable cursor for that step is `execute_finalization`, which is separate from the public `neal squash` command. Public `neal squash` is a post-run command with selection, preview, and interactive TTY confirmation before it rewrites history.
 
-## Atomic Writes And Locks
+## Atomic writes and locks
 
 `src/neal/atomic-write.ts` provides per-file atomic replacement helpers. State, current run pointers, queue state, queue pointers, queue links, queue summaries, run metadata, progress artifacts, review/final-completion/recovery/split-plan/retrospective artifacts, run narratives, and default squash audit writes use temp-file-plus-rename writes where in scope.
 
 This is not a multi-file transaction. If a process stops between writes, each individual JSON or text file should be either the previous complete file or the next complete file, but related files can briefly disagree. Resume and status commands must continue to tolerate that by resolving run paths and validating loaded state.
 
-The active-run lock is separate. `src/neal/run-lock.ts` uses exclusive creation for `.neal/active-run.lock`; that acquisition path should not be converted to atomic rename because the exclusive-create behavior is the mutual exclusion mechanism.
+The active-run lock is separate. `src/neal/run-lock.ts` uses exclusive creation for `.neal/active-run.lock`. That acquisition path should not be converted to atomic rename because the exclusive-create behavior is the mutual exclusion mechanism.
 
-## Change Checklist
+## Change checklist
 
 When adding a child-run phase:
 
@@ -253,7 +255,7 @@ When adding a queue-state field:
 - Parse and validate it in `parsePlanAndExecuteQueueState` or `parsePlanAndExecuteQueueItem`.
 - Include it in queue summary or current queue pointer output only when it is operator-facing or needed for resume.
 
-## Future Refactor Path
+## Future refactor path
 
 Do not jump directly from the current record-shaped `OrchestrationState` to a
 persisted discriminated union. The lower-risk path now in place is to keep v1