@navels/neal 0.1.0 → 0.3.0

package/dist/neal/state.js

@@ -85,7 +85,7 @@ export async function createInitialState(init, baseCommit) {
         agentConfig: init.agentConfig,
         unattended: init.unattended ?? false,
         unattendedAutoResumeCount: 0,
-        reviewStuckArbiterCount: 0,
+        consultantAttemptCount: 0,
         autoSquashOnCompletion: init.autoSquashOnCompletion ?? true,
         progressJsonPath: init.progressJsonPath,
         progressMarkdownPath: init.progressMarkdownPath,
@@ -136,6 +136,14 @@ export async function createInitialState(init, baseCommit) {
         interactiveBlockedRecovery: null,
         interactiveBlockedRecoveryHistory: [],
         pendingPlanReviewGuidance: null,
+        // Current-negotiation plan-review debt always starts empty; it is a
+        // projection of the current findings recomputed as review rounds run.
+        planReviewDebt: [],
+        // Durable inherited plan-review debt is seeded once from the queue handoff
+        // (execution stage) and never recomputed; default empty for every other run.
+        inheritedPlanReviewDebt: [...(init.inheritedPlanReviewDebt ?? [])],
+        // A fresh run starts running, so the blocked-reason invariant requires null.
+        blockerReason: null,
         status: 'running',
     };
 }
@@ -189,6 +197,7 @@ const REVIEWER_MEANINGFUL_PROGRESS_ACTIONS = ['accept', 'block_for_operator', 'r
 const REVIEW_FINDING_SOURCES = ['reviewer', 'plan_structure'];
 const REVIEW_FINDING_SEVERITIES = ['blocking', 'non_blocking'];
 const REVIEW_FINDING_STATUSES = ['open', 'fixed', 'rejected', 'deferred'];
+const PLAN_REVIEWER_FINDING_CLASSES = ['plan_correctness', 'verification_hardening'];
 const MANUAL_GATE_CHECK_TYPES = ['command'];
 const MANUAL_GATE_CHECK_CWDS = ['repo', 'run_dir'];
 const MANUAL_GATE_RESUME_PHASES = ['coder_scope'];
@@ -592,15 +601,30 @@ function hydrateRecentBlock(value, fieldPath = 'recentBlocks[]') {
         recordedAt: readString(record, 'recordedAt', `${fieldPath}.recordedAt`),
     };
 }
+// Tolerant read for the plan-review finding class: an absent key stays
+// undefined (execute-review findings and legacy states never set it and must be
+// unaffected), a recognized class is kept, and any other present value is
+// coerced to the fail-safe plan_correctness rather than throwing like readEnum.
+function readTolerantFindingClass(record, key) {
+    if (!hasOwn(record, key)) {
+        return undefined;
+    }
+    const value = record[key];
+    return typeof value === 'string' && PLAN_REVIEWER_FINDING_CLASSES.includes(value)
+        ? value
+        : 'plan_correctness';
+}
 function hydrateFinding(value, fieldPath = 'findings[]') {
     const finding = requireRecord(value, fieldPath);
     const evidence = readOptionalNullableString(finding, 'evidence', `${fieldPath}.evidence`);
+    const findingClass = readTolerantFindingClass(finding, 'findingClass');
     return {
         id: readString(finding, 'id', `${fieldPath}.id`),
         canonicalId: readString(finding, 'canonicalId', `${fieldPath}.canonicalId`),
         round: readSafeInteger(finding, 'round', `${fieldPath}.round`),
         source: readEnum(finding, 'source', REVIEW_FINDING_SOURCES, `${fieldPath}.source`),
         severity: readEnum(finding, 'severity', REVIEW_FINDING_SEVERITIES, `${fieldPath}.severity`),
+        ...(findingClass !== undefined ? { findingClass } : {}),
         files: readStringArray(finding, 'files', `${fieldPath}.files`),
         claim: readString(finding, 'claim', `${fieldPath}.claim`),
         ...(evidence !== undefined ? { evidence } : {}),
@@ -647,23 +671,23 @@ function hydrateInteractiveBlockedRecoveryDirective(value, fieldPath) {
         terminalOnly: readBoolean(directive, 'terminalOnly', `${fieldPath}.terminalOnly`),
     };
 }
-const BLOCKED_ADJUDICATOR_TRIAGE_CATEGORIES = [
+const CONSULTANT_TRIAGE_CATEGORIES = [
     'misunderstanding',
     'authorization',
     'external_precondition',
     'impossible_task',
 ];
-function hydrateInteractiveBlockedRecoveryAdjudicatorAdvice(record, fieldPath) {
-    const advice = readOptionalNullableRecord(record, 'adjudicatorAdvice', `${fieldPath}.adjudicatorAdvice`);
+function hydrateInteractiveBlockedRecoveryConsultantAdvice(record, fieldPath) {
+    const advice = readOptionalNullableRecord(record, 'consultantAdvice', `${fieldPath}.consultantAdvice`);
     if (!advice) {
         return undefined;
     }
     return {
-        recordedAt: readString(advice, 'recordedAt', `${fieldPath}.adjudicatorAdvice.recordedAt`),
-        recoverable: readBoolean(advice, 'recoverable', `${fieldPath}.adjudicatorAdvice.recoverable`),
-        triageCategory: readEnum(advice, 'triageCategory', BLOCKED_ADJUDICATOR_TRIAGE_CATEGORIES, `${fieldPath}.adjudicatorAdvice.triageCategory`),
-        resolutionDirective: readString(advice, 'resolutionDirective', `${fieldPath}.adjudicatorAdvice.resolutionDirective`),
-        rationale: readString(advice, 'rationale', `${fieldPath}.adjudicatorAdvice.rationale`),
+        recordedAt: readString(advice, 'recordedAt', `${fieldPath}.consultantAdvice.recordedAt`),
+        recoverable: readBoolean(advice, 'recoverable', `${fieldPath}.consultantAdvice.recoverable`),
+        triageCategory: readEnum(advice, 'triageCategory', CONSULTANT_TRIAGE_CATEGORIES, `${fieldPath}.consultantAdvice.triageCategory`),
+        resolutionDirective: readString(advice, 'resolutionDirective', `${fieldPath}.consultantAdvice.resolutionDirective`),
+        rationale: readString(advice, 'rationale', `${fieldPath}.consultantAdvice.rationale`),
     };
 }
 function hydrateInteractiveBlockedRecoveryFields(record, fieldPath) {
@@ -671,7 +695,7 @@ function hydrateInteractiveBlockedRecoveryFields(record, fieldPath) {
     if (!INTERACTIVE_BLOCKED_RECOVERY_SOURCE_PHASES.has(sourcePhase)) {
         throwInvalidState(`${fieldPath}.sourcePhase`, `unsupported interactive blocked recovery source phase ${JSON.stringify(sourcePhase)}`);
     }
-    const advice = hydrateInteractiveBlockedRecoveryAdjudicatorAdvice(record, fieldPath);
+    const advice = hydrateInteractiveBlockedRecoveryConsultantAdvice(record, fieldPath);
     return {
         enteredAt: readString(record, 'enteredAt', `${fieldPath}.enteredAt`),
         sourcePhase: sourcePhase,
@@ -681,9 +705,9 @@ function hydrateInteractiveBlockedRecoveryFields(record, fieldPath) {
         pendingDirective: hydrateInteractiveBlockedRecoveryDirective(readRequired(record, 'pendingDirective', `${fieldPath}.pendingDirective`), `${fieldPath}.pendingDirective`),
         turns: readArray(record, 'turns', `${fieldPath}.turns`).map((turn, index) => hydrateInteractiveBlockedRecoveryTurn(turn, `${fieldPath}.turns[${index}]`)),
         // Only attach the key when persisted advice exists, so a recovery record with
-        // no adjudicator advice round-trips byte-for-byte (no `adjudicatorAdvice:
+        // no consultant advice round-trips byte-for-byte (no `consultantAdvice:
         // undefined` residue).
-        ...(advice ? { adjudicatorAdvice: advice } : {}),
+        ...(advice ? { consultantAdvice: advice } : {}),
     };
 }
 function hydrateInteractiveBlockedRecovery(value, fieldPath = 'interactiveBlockedRecovery') {
@@ -712,7 +736,7 @@ function hydratePendingPlanReviewGuidance(record, fieldPath = 'pendingPlanReview
     const guidance = requireRecord(value, fieldPath);
     return {
         message: readString(guidance, 'message', `${fieldPath}.message`),
-        sourcePhase: readEnum(guidance, 'sourcePhase', ['reviewer_plan'], `${fieldPath}.sourcePhase`),
+        sourcePhase: readEnum(guidance, 'sourcePhase', ['reviewer_plan', 'coder_plan_response', 'coder_plan_optional_response'], `${fieldPath}.sourcePhase`),
         recordedAt: readString(guidance, 'recordedAt', `${fieldPath}.recordedAt`),
     };
 }
@@ -742,8 +766,13 @@ function hydrateRound(value, fieldPath = 'rounds[]') {
         findings: readStringArray(round, 'findings', `${fieldPath}.findings`),
     };
 }
-function hydrateResidualReviewDebtItem(value, fieldPath) {
+export function hydrateResidualReviewDebtItem(value, fieldPath) {
     const item = requireRecord(value, fieldPath);
+    // findingClass/originRound are declared only for plan-review debt; legacy
+    // execute-phase debt carries neither, so both stay optional and undefined when
+    // absent. findingClass reuses the tolerant reader (unknown → plan_correctness).
+    const findingClass = readTolerantFindingClass(item, 'findingClass');
+    const originRound = readOptionalSafeInteger(item, 'originRound', `${fieldPath}.originRound`);
     return {
         id: readString(item, 'id', `${fieldPath}.id`),
         canonicalId: readString(item, 'canonicalId', `${fieldPath}.canonicalId`),
@@ -754,6 +783,8 @@ function hydrateResidualReviewDebtItem(value, fieldPath) {
         requiredAction: readString(item, 'requiredAction', `${fieldPath}.requiredAction`),
         coderDisposition: readNullableString(item, 'coderDisposition', `${fieldPath}.coderDisposition`),
         coderCommit: readNullableString(item, 'coderCommit', `${fieldPath}.coderCommit`),
+        ...(findingClass !== undefined ? { findingClass } : {}),
+        ...(originRound !== undefined ? { originRound } : {}),
     };
 }
 function hydrateCompletedScope(value, fieldPath = 'completedScopes[]') {
@@ -819,7 +850,7 @@ function normalizeStateV1(parsed) {
         agentConfig: hydrateAgentConfig(readRequired(state, 'agentConfig'), 'agentConfig'),
         unattended: readOptionalBoolean(state, 'unattended') ?? false,
         unattendedAutoResumeCount: readOptionalSafeInteger(state, 'unattendedAutoResumeCount') ?? 0,
-        reviewStuckArbiterCount: readOptionalSafeInteger(state, 'reviewStuckArbiterCount') ?? 0,
+        consultantAttemptCount: readOptionalSafeInteger(state, 'consultantAttemptCount') ?? 0,
         // Legacy-tolerant: states persisted before this field existed hydrate to
         // true, preserving the historical always-squash behavior on resume.
         autoSquashOnCompletion: readOptionalBoolean(state, 'autoSquashOnCompletion') ?? true,
@@ -875,9 +906,22 @@ function normalizeStateV1(parsed) {
         interactiveBlockedRecovery: hydrateInteractiveBlockedRecovery(readRequired(state, 'interactiveBlockedRecovery')),
         interactiveBlockedRecoveryHistory: readArray(state, 'interactiveBlockedRecoveryHistory').map((record, index) => hydrateInteractiveBlockedRecoveryRecord(record, `interactiveBlockedRecoveryHistory[${index}]`)),
         pendingPlanReviewGuidance: hydratePendingPlanReviewGuidance(state),
+        // Both plan-review debt arrays are legacy-tolerant: run states persisted
+        // before these fields existed hydrate to an empty array.
+        planReviewDebt: hydratePlanReviewDebtArray(state, 'planReviewDebt'),
+        inheritedPlanReviewDebt: hydratePlanReviewDebtArray(state, 'inheritedPlanReviewDebt'),
+        // Legacy-tolerant: run states persisted before this field existed hydrate to
+        // null. The blocked-reason invariant is enforced in assertValidOrchestrationState.
+        blockerReason: readOptionalNullableString(state, 'blockerReason') ?? null,
         status: readEnum(state, 'status', ['running', 'paused', 'done', 'blocked', 'failed']),
     };
 }
+function hydratePlanReviewDebtArray(state, key) {
+    if (!hasOwn(state, key)) {
+        return [];
+    }
+    return readArray(state, key).map((item, index) => hydrateResidualReviewDebtItem(item, `${key}[${index}]`));
+}
 export async function loadState(path) {
     const content = await readFile(path, 'utf8');
     const parsed = JSON.parse(content);

package/dist/neal/status.js

@@ -24,6 +24,7 @@ const PROVIDER_ERROR_KINDS = new Set([
     'structured_output_invalid',
     'permission_denied',
     'session_unavailable',
+    'content_refused',
     'provider_failed',
     'unknown',
 ]);
@@ -157,6 +158,7 @@ export async function buildStatusSnapshot(args) {
         lock,
         health,
         findings: summarizeFindings(state),
+        planReviewDebt: summarizePlanReviewDebt(state),
         commits,
         squash,
         providerError,
@@ -245,7 +247,7 @@ export function renderHumanStatusSnapshot(snapshot) {
     if (shouldShowScope(snapshot)) {
         lines.push(`- Current scope: ${snapshot.currentScopeNumber}`);
     }
-    lines.push(`- Health: ${snapshot.health.classification} - ${snapshot.health.reason}`, `- Findings: ${snapshot.findings.openBlocking} open blocking, ${snapshot.findings.openNonBlocking} open non-blocking (${snapshot.findings.total} total)`, `- Operator guidance: waiting=${formatBoolean(snapshot.waitingForOperatorGuidance)}, pending=${formatBoolean(snapshot.pendingOperatorGuidance)}`);
+    lines.push(`- Health: ${snapshot.health.classification} - ${snapshot.health.reason}`, `- Findings: ${snapshot.findings.openBlocking} open blocking, ${snapshot.findings.openNonBlocking} open non-blocking (${snapshot.findings.total} total)`, `- Plan review debt: ${formatPlanReviewDebtLine(snapshot.planReviewDebt)}`, `- Operator guidance: waiting=${formatBoolean(snapshot.waitingForOperatorGuidance)}, pending=${formatBoolean(snapshot.pendingOperatorGuidance)}`);
     if (snapshot.lastMeaningfulEvent) {
         lines.push(`- Last progress: ${snapshot.lastMeaningfulEvent.type} - ${snapshot.lastMeaningfulEvent.summary}`);
     }
@@ -337,6 +339,14 @@ function shouldShowScope(snapshot) {
 function formatBoolean(value) {
     return value ? 'yes' : 'no';
 }
+function formatPlanReviewDebtLine(debt) {
+    if (debt.total === 0) {
+        return '0';
+    }
+    const rounds = [...new Set(debt.items.map((item) => item.originRound).filter((round) => round !== null))].sort((a, b) => a - b);
+    const roundsSuffix = rounds.length > 0 ? ` (rounds ${rounds.join(', ')})` : '';
+    return `${debt.total}${roundsSuffix}`;
+}
 function formatLockSummary(lock) {
     switch (lock.kind) {
         case 'none':
@@ -513,6 +523,10 @@ function summarizeBlocker(state, events, invalidDerivedPlanPayloadPath, guidance
         };
     }
     const candidates = [
+        {
+            reason: nonEmptyString(state.blockerReason),
+            source: 'RUN_STATE.json blocker reason',
+        },
         {
             reason: guidance?.category === 'scope_accounting_guardrail' ? guidance.summary : null,
             source: 'blocked guidance',
@@ -903,6 +917,19 @@ function summarizeFindings(state) {
         deferred: state.findings.filter((finding) => finding.status === 'deferred').length,
     };
 }
+function summarizePlanReviewDebt(state) {
+    const toItem = (item, inherited) => ({
+        canonicalId: item.canonicalId,
+        findingClass: item.findingClass ?? null,
+        originRound: item.originRound ?? null,
+        inherited,
+    });
+    const items = [
+        ...state.inheritedPlanReviewDebt.map((item) => toItem(item, true)),
+        ...state.planReviewDebt.map((item) => toItem(item, false)),
+    ];
+    return { total: items.length, items };
+}
 function summarizeCommits(state) {
     return {
         initialBaseCommit: state.initialBaseCommit,

package/dist/neal/support.js

@@ -8,9 +8,9 @@ function appendInteractiveBlockedRecoverySection(lines, title, recovery, options
     if (recovery.pendingDirective) {
         lines.push(`- Pending terminal directive at ${recovery.pendingDirective.recordedAt}: ${recovery.pendingDirective.operatorGuidance}`);
     }
-    if (recovery.adjudicatorAdvice) {
-        const advice = recovery.adjudicatorAdvice;
-        lines.push(`- Adjudicator advice at ${advice.recordedAt} (read-only, not auto-applied):`, `  - Recoverable: ${advice.recoverable ? 'yes' : 'no'}`, `  - Triage category: ${advice.triageCategory}`, `  - Suggested directive: ${advice.resolutionDirective || 'n/a'}`, `  - Rationale: ${advice.rationale}`);
+    if (recovery.consultantAdvice) {
+        const advice = recovery.consultantAdvice;
+        lines.push(`- Consultant advice at ${advice.recordedAt} (read-only, not auto-applied):`, `  - Recoverable: ${advice.recoverable ? 'yes' : 'no'}`, `  - Triage category: ${advice.triageCategory}`, `  - Suggested directive: ${advice.resolutionDirective || 'n/a'}`, `  - Rationale: ${advice.rationale}`);
     }
     if (recovery.turns.length === 0) {
         lines.push('- Operator guidance: pending');

package/docs/README.md

@@ -1,22 +1,26 @@
-# Neal Docs
+# Docs
 
-These docs are current product and implementation references, not an archive of
-historical implementation plans.
+These are the current product and implementation references. Historical plans
+don't belong here.
 
-- [architecture.md](architecture.md): one-page map of how neal is built — **start here**
-- [providers.md](providers.md): built-in provider adapter contract and extension checklist
-- [maintenance.md](maintenance.md): dependency-update and versioning policy
-- [compat.md](compat.md): `neal compat` model-compatibility smoke test (PASS/FAIL per model/role)
-- [compatible-models.md](compatible-models.md): dated whitelist of `neal compat`-verified models
-- [plan-format.md](plan-format.md): executable plan shapes, normalization, and selected-plan Git behavior
-- [storage.md](storage.md): project-local `.neal/` storage contract and artifact classes
-- [release.md](release.md): manual release process, versioning, and SDK-update policy
-- [demo.md](demo.md): safe `asciinema` terminal demo recording workflow
+- [architecture.md](architecture.md): how neal is built (**start here**)
+- [providers.md](providers.md): provider capabilities, permissions, and adapter contracts
+- [compatible-models.md](compatible-models.md): dated `neal compat` results
+- [compat.md](compat.md): the model-compatibility smoke test and PASS/FAIL contract
+- [plan-format.md](plan-format.md): executable plan shapes and selected-plan Git behavior
+- [troubleshooting.md](troubleshooting.md): common setup, run, lock, and squash failures
+- [automation.md](automation.md): exit codes, status JSON, and harness behavior
+- [storage.md](storage.md): project-local `.neal/` storage and artifact classes
 - [state-machine.md](state-machine.md): persisted run and queue state invariants
-- [PROMPT_SPECS.md](PROMPT_SPECS.md): prompt-spec inventory and ownership boundaries
-- [ADJUDICATOR_INVENTORY.md](ADJUDICATOR_INVENTORY.md): shared coder/reviewer loop inventory
-- [../examples/issue-triage-js/README.md](../examples/issue-triage-js/README.md): dependency-free in-repo example
-  for local testing and an optional live Neal run
+- [review-convergence.md](review-convergence.md): plan-review finding classes, debt, and convergence
+- [prompt-specs.md](prompt-specs.md): prompt-spec inventory and ownership boundaries
+- [prompt-evals.md](prompt-evals.md): prompt versioning and reviewer-recall evals
+- [adjudicator-inventory.md](adjudicator-inventory.md): shared coder/reviewer loop inventory
+- [maintenance.md](maintenance.md): dependency updates and versioning
+- [release.md](release.md): manual release process and SDK-update policy
+- [demo.md](demo.md): safe `asciinema` recording workflow
+- [../examples/issue-triage-js/README.md](../examples/issue-triage-js/README.md):
+  dependency-free local example and optional live neal run
 
-The public README carries the user-facing workflow. Keep docs here focused on
-contracts that help maintain or extend Neal.
+The public README owns the user-facing workflow. Keep these docs focused on
+contracts that help maintain or extend neal.

package/docs/{ADJUDICATOR_INVENTORY.md → adjudicator-inventory.md}

@@ -1,17 +1,17 @@
-# Neal Adjudicator Inventory
+# Adjudicator inventory
 
 ## Scope
 
-This document is the current contract for Neal's adjudicator layer: the shared
+The current contract for neal's adjudicator layer covers the shared
 coder/reviewer loop vocabulary, the typed adjudication specs, the read-only
-loops that reuse the same contract, and the blocked adjudicator.
+loops that reuse the same contract, and the consultant.
 
 Two things are explicit:
 
-- Neal uses the terms `adjudicator` and `adjudication spec`.
+- neal uses the terms `adjudicator` and `adjudication spec`.
 - Only recurring coder/reviewer loop mechanics belong to the shared
   adjudicator. Prompt ownership stays under `src/neal/prompts/` (see
-  [PROMPT_SPECS.md](PROMPT_SPECS.md)) and transition semantics stay in the
+  [prompt-specs.md](prompt-specs.md)) and transition semantics stay in the
   orchestrator layers.
 
 The typed contract for writer-run adjudication specs lives in
@@ -22,7 +22,7 @@ are attached to each in-scope writer-run adjudication spec as `loopContract`
 metadata. Read-only `neal review` findings use the same contract-only pattern
 with artifacts under `.neal/reviews/<review-id>/`.
 
-## Module Map
+## Module map
 
 | Module | Owns |
 | --- | --- |
@@ -31,10 +31,10 @@ with artifacts under `.neal/reviews/<review-id>/`.
 | `src/neal/adjudicator/planning.ts` | Planning-family context resolution plus reviewer and plan-response round adjudication for `plan_review` and `derived_plan_review` |
 | `src/neal/adjudicator/execute.ts` | Execute-family context resolution, reviewer and coder-response round adjudication, findings synthesis, convergence detection (reopened canonical, stuck window), disposition resolution |
 | `src/neal/adjudicator/final-completion.ts` | Final-completion context resolution plus summary and reviewer round adjudication |
-| `src/neal/adjudicator/blocked-adjudicator.ts` | Read-only triage of eligible blocked states (see Blocked Adjudicator below) |
+| `src/neal/adjudicator/consultant.ts` | Read-only triage of eligible blocked states (see Consultant below) |
 | `src/neal/adjudicator/artifacts.ts` | Resolving the active adjudication contract from run state and rendering it into artifacts |
 
-## Ownership Split
+## Ownership split
 
 - Shared loop contract (`contracts.ts`):
   - loop kind, side-effect policy, allowed outcomes, terminal outcomes,
@@ -42,7 +42,7 @@ with artifacts under `.neal/reviews/<review-id>/`.
   - import-time validation that every in-scope adjudication spec declares the
     shared contract fields, plus validation for the contract-only
     review-findings loop
-  - descriptive metadata only; runtime phase routing and state mutation stay in
+  - descriptive metadata only. Runtime phase routing and state mutation stay in
     the transition layer
 - Adjudication spec (`specs.ts`):
   - coder and reviewer prompt-surface references, validated at import time
@@ -53,8 +53,8 @@ with artifacts under `.neal/reviews/<review-id>/`.
   - validated allowed transition outcomes declared per spec
 - Adjudicator helpers (`planning.ts`, `execute.ts`, `final-completion.ts`):
   - per-family context resolution from run state
-  - reviewer/coder round invocation, including inline-context assembly for
-    reviewers without repository read access
+  - reviewer/coder round invocation, including supplying the commit-range diff
+    to read-only reviewers that lack their own range-diff tool
   - execute-family findings synthesis, reopened-finding and stuck-window
     detection, and disposition resolution
 - Transition layer (`src/neal/orchestrator.ts`, `src/neal/orchestrator/run-loop.ts`,
@@ -71,7 +71,7 @@ with artifacts under `.neal/reviews/<review-id>/`.
   - `createdCommits` and final-commit consequences
 - Prompt-spec layer:
   - prompt identity, builders, and role/task ownership under
-    `src/neal/prompts/` (see [PROMPT_SPECS.md](PROMPT_SPECS.md))
+    `src/neal/prompts/` (see [prompt-specs.md](prompt-specs.md))
 
 `transitionSignals` in `specs.ts` are validated allowed outcomes, not a
 dispatch table. Import-time validation checks each spec against one explicit
@@ -81,7 +81,7 @@ re-checks the resolved outcome against the active adjudication spec, and the
 transition layer still maps those outcomes explicitly in runtime code rather
 than dispatching off `transitionSignals` directly.
 
-## Transition Signals
+## Transition signals
 
 | Spec | Family | Validated transition signals |
 | --- | --- | --- |
@@ -93,7 +93,7 @@ than dispatching off `transitionSignals` directly.
 The `AdjudicationTransitionSignal` union also declares `leave_adjacent`, which
 no in-scope spec or family currently uses.
 
-## Loop Contracts
+## Loop contracts
 
 Every in-scope spec declares allowed outcomes
 `accepted, revise, blocked, failed, cap_reached` with terminal outcomes
@@ -106,12 +106,12 @@ Every in-scope spec declares allowed outcomes
 | `execute_review` | `execute` | `code_changes` | `state.maxRounds` (review iterations) | `implementation_scope` at `state.createdCommits` plus `state.reviewMarkdownPath` |
 | `final_completion_review` | `final_completion` | `code_changes` | `state.finalCompletionContinueExecutionMax` (continued execution) | `final_completion_review` at `FINAL_COMPLETION_REVIEW.md` and `state.finalCompletionReviewVerdict` |
 
-## In-Scope Adjudication Specs
+## In-scope adjudication specs
 
 ### `plan_review`
 
 - Current loop surfaces: `runCoderPlanRound`, `runPlanReviewerRound`, `runCoderPlanResponseRound(reviewMode=plan)`
-- Artifact under review: top-level Neal-executable plan markdown
+- Artifact under review: top-level neal-executable plan markdown
 - Prompt surfaces:
   - coder primary: `plan_author.primary` via `buildPlanningPrompt`
   - coder response: `plan_author.response` via `buildCoderPlanResponsePrompt`
@@ -120,11 +120,11 @@ Every in-scope spec declares allowed outcomes
   - coder primary: `buildCoderPlanSchema` / `validateCoderPlanPayload`
   - coder response: `buildCoderPlanResponseSchema` / `validateCoderPlanResponsePayload`
   - reviewer: `buildPlanReviewerSchema` / `PlanReviewerPayload`
-  - provider surfaces: coder primary/response use `coder_structured_schema`; reviewer uses `structured_advisor_schema`
+  - provider surfaces: coder primary/response use `coder_structured_schema` and reviewer uses `structured_advisor_schema`
 - Convergence rule:
   - settle when reviewer returns no open findings and the plan remains structurally valid
   - revise when findings route back to required or optional plan response
-  - block when coder returns structured `action=blocked`; round code still renders compatibility markers for downstream state
+  - block when coder returns structured `action=blocked`. Round code still renders compatibility markers for downstream state
 - Transition targets: `accept_plan`, `request_revision`, `optional_revision`, `block_for_operator`
 
 ### `derived_plan_review`
@@ -137,7 +137,7 @@ Every in-scope spec declares allowed outcomes
 - Output contracts:
   - coder response: `buildCoderPlanResponseSchema` / `validateCoderPlanResponsePayload`
   - reviewer: `buildPlanReviewerSchema` / `PlanReviewerPayload`
-  - provider surfaces: coder response uses `coder_structured_schema`; reviewer uses `structured_advisor_schema`
+  - provider surfaces: coder response uses `coder_structured_schema` and reviewer uses `structured_advisor_schema`
 - Convergence rule:
   - settle when reviewer returns no open findings and the derived plan is safe to adopt
   - revise through the same planning-family response loop as ordinary plan review
@@ -157,7 +157,7 @@ Every in-scope spec declares allowed outcomes
   - coder primary: `buildCoderScopeSchema` / `validateCoderScopePayload`
   - coder response: `buildCoderResponseSchema` / `validateCoderResponsePayload`
   - reviewer: `buildReviewerSchema` / `ReviewerPayload`
-  - provider surfaces: coder primary/response use `coder_structured_schema`; reviewer uses `structured_advisor_schema`
+  - provider surfaces: coder primary/response use `coder_structured_schema` and reviewer uses `structured_advisor_schema`
 - Convergence rule:
   - settle when the reviewer returns no blocking findings and
     `meaningfulProgressAction === accept`, including top-level scopes already
@@ -165,13 +165,13 @@ Every in-scope spec declares allowed outcomes
     `advance_parent` is downgraded to `accept` with an explanatory rationale)
   - `advance_parent` is a distinct empty-derived-scope parent-advancement
     signal: it settles by finalizing the parent objective only when
-    deterministic classification finds it eligible; an eligible empty-derived
+    deterministic classification finds it eligible. An eligible empty-derived
     classification can also upgrade a findings-free `block_for_operator` to
     `advance_parent`
   - revise when findings reopen `coder_response` or `coder_optional_response`
   - block when reviewer returns `block_for_operator`, `replace_plan`, or an
     unsafe `advance_parent`, or coder returns structured `action=blocked` /
-    `action=split_plan`; round code still renders compatibility markers for
+    `action=split_plan`. Round code still renders compatibility markers for
     downstream state
 - Transition targets: `accept_scope`, `request_revision`, `optional_revision`, `block_for_operator`, `replace_plan`, `advance_parent`
 - Public review note:
@@ -182,7 +182,7 @@ Every in-scope spec declares allowed outcomes
 ### `final_completion_review`
 
 - Current loop surfaces: `runCoderFinalCompletionSummaryRound`, `runReviewerFinalCompletionRound`
-- Artifact under review: whole-plan completion packet assembled after the terminal execute scope settles, including aggregate review context for `initialBaseCommit..finalCommit` when Neal can read that range
+- Artifact under review: whole-plan completion packet assembled after the terminal execute scope settles, including aggregate review context for `initialBaseCommit..finalCommit` when neal can read that range
 - Prompt surfaces:
   - coder: `completion_coder.final_completion` via `buildFinalCompletionSummaryPrompt`
   - reviewer: `completion_reviewer.final_completion` via `buildFinalCompletionReviewerPrompt`
@@ -192,7 +192,7 @@ Every in-scope spec declares allowed outcomes
   - provider surfaces: coder and reviewer both use `structured_advisor_schema`
 - Convergence rule:
   - settle when reviewer returns one of the three whole-plan decisions
-  - no coder-response revision round exists; `continue_execution` hands control
+  - no coder-response revision round exists. `continue_execution` hands control
     back to execute transitions rather than mutating the adjudicator loop
 - Transition targets: `accept_complete`, `continue_execution`, `block_for_operator`
 - Aggregate review context:
@@ -200,7 +200,7 @@ Every in-scope spec declares allowed outcomes
     `initialBaseCommit` and resolved final commit, then records commit
     subjects, diff stat, and changed files when available
   - if the aggregate range cannot be read, the packet records an explicit
-    unavailable reason; the reviewer prompt treats that as a completion-review
+    unavailable reason. The reviewer prompt treats that as a completion-review
     evidence gap rather than proof of correctness
   - the final completion reviewer shares the adversarial falsification,
     verification-skepticism, regression-preservation, and
@@ -208,7 +208,7 @@ Every in-scope spec declares allowed outcomes
     `src/neal/prompts/review-doctrine.ts`, but keeps the final-completion
     verdict schema instead of the ordinary scope-review findings schema
 
-## Contract-Only Read-Only Loops
+## Contract-only read-only loops
 
 ### `review`
 
@@ -224,7 +224,7 @@ Every in-scope spec declares allowed outcomes
   - settle when reviewer returns `accepted` with final markdown
   - revise when reviewer returns concrete findings
   - block when reviewer returns `blocked`, provider validation fails, or
-    protected writer state changes; `cap_reached` when the configured
+    protected writer state changes. `cap_reached` when the configured
     review-round cap is reached without acceptance
 - Loop contract (`REVIEW_FINDINGS_ADJUDICATED_LOOP_CONTRACT` in `contracts.ts`):
   - loop kind: `review`
@@ -233,54 +233,55 @@ Every in-scope spec declares allowed outcomes
   - terminal artifact: `.neal/reviews/<review-id>/REVIEW_FINAL.md`
 - State ownership:
   - review artifacts live under `.neal/reviews/<review-id>/`
-  - review never becomes a writer-run command path; a read-only guard asserts
+  - review never becomes a writer-run command path. A read-only guard asserts
     that `.neal/current.json`, `.neal/current-queue.json`, and run-local
     `RUN_STATE.json` files are unchanged after the loop
 
-## Blocked Adjudicator
+## Consultant
 
-`src/neal/adjudicator/blocked-adjudicator.ts` (`runBlockedAdjudicator`) is a
+`src/neal/adjudicator/consultant.ts` (`runConsultant`) is a
 read-only triage step for blocked writer runs. It decides whether a block is an
-autonomously recoverable misunderstanding — resolvable within the existing
-scope with no new authorization, external state, or scope expansion — or a
-genuine wall (`authorization`, `external_precondition`, `impossible_task`)
+autonomously recoverable misunderstanding (resolvable within the existing
+scope with no new authorization, external state, or scope expansion) or a
+genuine blocker (`authorization`, `external_precondition`, `impossible_task`)
 that must escalate to a human. It is not an adjudication spec: it makes no
-commits and no file edits, and only returns a `BlockedAdjudicatorVerdict`.
+commits and no file edits, and only returns a `ConsultantVerdict`.
 
 Gates, enforced at the recovery chokepoint
-(`src/neal/orchestrator/phases/recovery.ts`); any failed gate falls through to
-generic recovery with no adjudicator invocation:
+(`src/neal/orchestrator/phases/recovery.ts`). Any failed gate falls through to
+generic recovery with no consultant invocation:
 
-- Source-phase eligibility: `ADJUDICATOR_ELIGIBLE_SOURCE_PHASES` is
+- Source-phase eligibility: `CONSULTANT_ELIGIBLE_SOURCE_PHASES` is
   `reviewer_scope`, `reviewer_plan`, `coder_scope`, `coder_response`,
   `coder_optional_response`. Reviewer phases are eligible only for structural
-  `review_stuck:` reasons; any coder block on the coder phases is eligible.
-- Per-scope budget: `state.reviewStuckArbiterCount`, bounded by
-  `neal.review_stuck_arbiter_max_attempts` (default `1`; `0` disables) and
+  `review_stuck:` reasons. Any coder block on the coder phases is eligible.
+- Per-scope budget: `state.consultantAttemptCount`, bounded by
+  `neal.consultant_max_attempts` (default `1`, `0` disables) and
   reset to `0` at scope boundaries. One invocation consumes one unit whether it
-  auto-acts (unattended) or only produces advice (attended, where the verdict
-  is surfaced as operator advice and never auto-applied).
+  auto-applies a recoverable verdict (both run modes) or, on a non-recoverable
+  verdict, finalizes terminally (unattended) or surfaces the verdict as operator
+  advice and yields (attended).
 - Anti-thrash window: a block that repeats a `state.recentBlocks` record with
   the same scope identity (`scopeNumber` + `derivedScopeIndex`), the same
-  `sourcePhase`, and the same normalized blocker key — with no new evidence —
+  `sourcePhase`, the same normalized blocker key, and no new evidence
   short-circuits to a non-recoverable `impossible_task` verdict without
   running an LLM round. The chokepoint is the sole writer of
-  `state.recentBlocks`; the adjudicator module's window helpers are pure.
+  `state.recentBlocks`. The consultant module's window helpers are pure.
 
-Verdict schema constraints (`buildBlockedAdjudicatorSchema` /
-`validateBlockedAdjudicatorVerdictPayload` in `src/neal/agents/schemas.ts`):
+Verdict schema constraints (`buildConsultantSchema` /
+`validateConsultantVerdictPayload` in `src/neal/agents/schemas.ts`):
 `recoverable=true` is valid only with `triageCategory=misunderstanding` plus a
-non-empty `resolutionDirective`; `recoverable=false` must not pair with
-`misunderstanding`; `rationale` must be non-empty; `targetCanonicalIds` is
+non-empty `resolutionDirective`. `recoverable=false` must not pair with
+`misunderstanding`. `rationale` must be non-empty. `targetCanonicalIds` is
 optional and defaults to `[]`. A malformed verdict is rejected so it can never
 drive an autonomous recovery.
 
-Prompt and round: `buildBlockedAdjudicatorPrompt` in
+Prompt and round: `buildConsultantPrompt` in
 `src/neal/agents/prompts.ts` (a single no-read-safe variant that judges
-entirely from Neal-inlined context) run through `runBlockedAdjudicatorRound`
+entirely from neal-inlined context) run through `runConsultantRound`
 in `src/neal/agents/rounds.ts`.
 
-## Adjacent Or Non-Adjudicator Flows
+## Adjacent or non-adjudicator flows
 
 - `interactive_blocked_recovery` (declared in `ADJUDICATION_ADJACENT_FLOWS`):
   - current entrypoint: `runInteractiveBlockedRecoveryPhase`
@@ -288,23 +289,23 @@ in `src/neal/agents/rounds.ts`.
     than forming a pure coder/reviewer adjudication loop, so this remains
     transition-layer-owned
 
-## Spec Family Mapping
+## Spec family mapping
 
 - Planning family: `plan_review`, `derived_plan_review`
 - Execute family: `execute_review` (meaningful-progress remains a capability of
   this family, not a separate adjudication spec)
 - Final-completion family: `final_completion_review`
 - Contract-only read-only loops: `review`
-- Adjacent read-only triage: the blocked adjudicator (not a spec)
+- Adjacent read-only triage: the consultant (not a spec)
 
 Shared reviewer doctrine does not collapse these families. It is prompt wording
-reused across execute-scope review, plan review, and final completion review;
-schemas, allowed transition outcomes, and artifact/context packets remain
+reused across execute-scope review, plan review, and final completion review.
+Schemas, allowed transition outcomes, and artifact/context packets remain
 family-specific.
 
 New loop variants should extend the adjudication-spec family or remain
-explicitly adjacent; they should not reintroduce bespoke coder/reviewer loop
+explicitly adjacent. They should not reintroduce custom coder/reviewer loop
 wiring inside `src/neal/orchestrator.ts`. When adding or changing a spec, keep
 `transitionSignals`, the family runtime contract, and the loop contract in
-sync — `specs.ts` and `contracts.ts` validate all three at import time, so
+sync. `specs.ts` and `contracts.ts` validate all three at import time, so
 drift fails fast in tests and at startup.