@navels/neal 0.2.0 → 0.3.1

package/docs/plan-format.md

@@ -1,18 +1,19 @@
-# Neal Plan Format
+# Plan format
 
-This is the canonical public reference for executable Neal plan documents.
-The validator lives in `src/neal/plan-validation.ts` as `validatePlanDocument`.
+Executable neal plan documents follow the format defined here, the canonical
+public reference. The validator lives in `src/neal/plan-validation.ts` as
+`validatePlanDocument`.
 The selected-plan Git contract lives in `src/neal/plan-doc.ts` as
 `inspectPlanDocDisposition` and `toPlanDocMetadata`. Scope counting and status
 labels come from `getExecutionPlanScopeCount` and
 `getCurrentExecutionScopeDescriptor` in `src/neal/scopes.ts`.
 
-Executable plans are instructions for Neal's planner/coder/reviewer loop, not
+Executable plans are instructions for neal's planner/coder/reviewer loop, not
 project requirements documents. They should be specific enough that one scope
 can be implemented, reviewed, and verified without relying on hidden operator
 intent.
 
-## Execution Shape
+## Execution shape
 
 Every executable plan must choose exactly one execution shape. The plan must
 include a literal `## Execution Shape` section, and that section must contain
@@ -24,11 +25,11 @@ exactly one non-empty line:
 
 Use `one_shot` when the whole task fits in one bounded implementation scope.
 Use `multi_scope` when the task has a finite ordered queue of known scopes.
-Use `multi_scope_unknown` when Neal should repeat one bounded scope template
+Use `multi_scope_unknown` when neal should repeat one bounded scope template
 until a concrete completion rule is satisfied, but the number of iterations is
 not knowable when the plan is written.
 
-## One-Shot Format
+## One-shot format
 
 `executionShape: one_shot` must not include a literal `## Execution Queue`
 section, a literal `## Execution Loop` section, or a standalone
@@ -48,11 +49,11 @@ executionShape: one_shot
 Complete one bounded change and verify it.
 ```
 
-For status display, Neal treats a one-shot plan as one known scope. If the
+For status display, neal treats a one-shot plan as one known scope. If the
 document has a level-one Markdown title, that title can be used as the scope
-display title; otherwise Neal falls back to a generic one-scope label.
+display title. Otherwise neal falls back to a generic one-scope label.
 
-### `one_shot` Is Defended Through Plan Refinement, Not Clamped
+### `one_shot` is defended through plan refinement, not clamped
 
 An author-declared `executionShape: one_shot` is captured once from the seed
 plan document and defended through refinement by both roles' prompts: the
@@ -62,18 +63,18 @@ refined document declares any other execution shape or adds orchestration
 sections. That finding routes through the normal revision loop like any other.
 
 There is deliberately no hard mechanical clamp: if the review loop converges on
-a different shape (the reviewer accepts an expansion), Neal adopts the refined
+a different shape (the reviewer accepts an expansion), neal adopts the refined
 document's shape. An earlier version clamped the saved shape back to `one_shot`
-unconditionally, which caused non-convergence on complex plans — the planner
+unconditionally, which caused non-convergence on complex plans: the planner
 could not produce an accurate single-scope plan, so review correctly rejected
 it until the round cap failed the run.
 
 This defense applies only to the top-level authored plan. A derived plan
 declares and owns its own execution shape. Plans authored `multi_scope` or
-`multi_scope_unknown` are unaffected — refinement may adjust their scope
+`multi_scope_unknown` are unaffected. Refinement may adjust their scope
 content as usual.
 
-## Multi-Scope Format
+## Multi-scope format
 
 `executionShape: multi_scope` must include a literal `## Execution Queue`
 section. It must not include a literal `## Execution Loop` section or a
@@ -108,14 +109,14 @@ Each scope entry must include these labeled bullets:
 - `- Verification:`
 - `- Success Condition:`
 
-The queue cannot skip or repeat numbers. Neal uses the queue headings to count
+The queue cannot skip or repeat numbers. neal uses the queue headings to count
 known scopes and to show progress labels such as the current scope number and
 scope title.
 
 For a concrete in-repo multi-scope plan, see
 [../examples/issue-triage-js/PLAN.md](../examples/issue-triage-js/PLAN.md).
 
-## Multi-Scope-Unknown Format
+## Multi-scope-unknown format
 
 `executionShape: multi_scope_unknown` must include a literal
 `## Execution Loop` section with exactly one literal `### Recurring Scope`
@@ -144,58 +145,85 @@ executionShape: multi_scope_unknown
 Stop when the explicit completion rule is satisfied.
 ```
 
-The recurring scope uses the same required bullets as a fixed queue. Neal treats
+The recurring scope uses the same required bullets as a fixed queue. neal treats
 the total scope count as unknown by contract, and status displays the recurring
 scope title rather than a finite total.
 
-## Verification And Acceptance
+## Verification and acceptance
 
 A scope should name verification commands that are deterministic and
 noninteractive when possible. Examples include typecheck, test, lint, build,
 package verification, or a focused smoke command. If a command needs external
 state, credentials, network access, or manual setup, call that out in the plan
-so Neal can distinguish expected manual gates from unexpected blockers.
+so neal can distinguish expected manual gates from unexpected blockers.
 
 The success condition should state what must be true after the scope is
-complete. It is not a prose summary of the goal; it is the reviewable exit
+complete. It is not a prose summary of the goal. It is the reviewable exit
 criterion. Good success conditions mention the changed surface, the expected
 behavior or docs state, and the verification evidence required for acceptance.
 
-## Planning Normalization
+## Planning normalization
 
 `neal plan` revises the selected plan file in place. It should preserve the
-user's product objective while making the document executable by Neal.
-
-During validation, Neal may normalize known legacy plan wording before checking
+user's product objective while making the document executable by neal and
+keeping it practical for a person to review.
+
+Plan mode owns the final execution-shape decision. Its planner/reviewer loop
+chooses `one_shot`, `multi_scope`, or `multi_scope_unknown` and records that
+choice in the plan's `## Execution Shape` section. An author-declared
+`one_shot` remains subject to the defense described above.
+
+The planner inspects the current repository enough to confirm the approach and
+identify major dependencies, constraints, and affected subsystems. It adds
+moderate-to-high-level implementation detail, scope boundaries, meaningful
+verification, and success conditions. It should not try to complete the
+implementation in prose. Routine file discovery, exact tests, and local code
+choices belong to the execution coder and reviewer.
+
+The plan reviewer checks the approach, major repository constraints, scope
+shape, sequencing, verification, and completion conditions. A material omission
+that could produce the wrong implementation or make a scope unsafe is a plan
+finding. Missing routine implementation detail is not. The refined plan does
+not need exhaustive lists of files, symbols, callers, tests, commands, or
+assertions.
+
+A repository-wide invariant or global regression guarantee belongs in the plan
+only when it is necessary for the requested change to be correct. Otherwise,
+the planner narrows or removes it instead of expanding the implementation or
+verification scope. The reviewer judges verification against the requested
+change rather than requiring complete enforcement of a broader guarantee the
+plan introduced itself.
+
+During validation, neal may normalize known legacy plan wording before checking
 the final shape. Current normalization can convert legacy queue section
 headings to `## Execution Queue`, normalize compatible scope labels to literal
 `### Scope N:` headings, and normalize known aliases for the verification and
 success-condition bullet labels. Normalization is still bounded by the same
-shape rules above; it is not a license to omit the execution shape or required
+shape rules above. It is not a license to omit the execution shape or required
 scope fields.
 
 For `neal plan`, the original selected plan backup is stored under the run
-directory at `.neal/runs/<run-id>/PLAN_ORIGINAL.md`. Neal does not use a sibling
+directory at `.neal/runs/<run-id>/PLAN_ORIGINAL.md`. neal does not use a sibling
 repository backup directory for that copy.
 
-## Selected Plan Documents And Git
+## Selected plan documents and Git
 
-Neal records selected-plan metadata with `inspectPlanDocDisposition` and
+neal records selected-plan metadata with `inspectPlanDocDisposition` and
 `toPlanDocMetadata` from `src/neal/plan-doc.ts`.
 
 A selected plan document is eligible for ordinary Git inclusion only when it is
 repo-local, exists, is a regular file, and is not ignored. If that eligible
-plan document changes during a run, Neal may include it in the final tree using
+plan document changes during a run, neal may include it in the final tree using
 normal Git staging.
 
 The selected plan document can be the only allowed dirty path at writer-run
 start when it is the explicit plan under execution. Dirty work outside that
 selected plan still blocks writer-run start and queue continuation.
 
-## Ignored Or External Plan Documents
+## Ignored or external plan documents
 
 Ignored plan files, plan files outside the repository, missing paths, and
-non-file paths are metadata-only. Neal records where they came from, but it does
+non-file paths are metadata-only. neal records where they came from, but it does
 not force-add them to the repository and does not treat them as package or
 source artifacts.
 
@@ -204,9 +232,9 @@ stored outside the target repository. Those plans can drive a run, but they
 remain operator-local unless the operator intentionally copies their contents
 into a tracked document.
 
-## Protocol Boundary
+## Protocol boundary
 
-Neal's terminal control protocol is not Markdown artifact content. Plan files,
+neal's terminal control protocol is not Markdown artifact content. Plan files,
 derived plans, review notes, recovery guidance, and JSON artifacts should use
 their normal schema or prose fields instead of embedding terminal control marker
 words. This keeps executable plans portable and prevents transport signals from

package/docs/prompt-evals.md

@@ -0,0 +1,96 @@
+# Prompt evals
+
+Prompt changes ship with two guards: a versioning contract that makes silent
+drift impossible, and a reviewer-recall eval that measures what a reviewer
+prompt actually does. Together they gate behavior-changing edits to the review
+doctrine.
+
+## Prompt versioning
+
+Every registered `PromptSpec` carries an integer `version` and an in-source
+changelog, and each render fixture records the version and a `renderSha` of the
+prompt it pinned. The render-integrity contract test fails when a spec's
+rendered output changes without a version bump. So "which prompt version
+produced this run" is always answerable, and a prompt edit that forgets to bump
+its version fails CI instead of drifting silently.
+
+When you change a prompt: edit it, bump its `version`, add a changelog line, and
+regenerate its render fixture. The test tells you exactly which spec is out of
+sync.
+
+## Reviewer-recall eval
+
+The eval measures a reviewer prompt against a labeled fixture set (diffs with
+known defects, plus clean diffs) and reports recall, precision, and blocking-
+finding rate. It exists so the reviewer-doctrine rewrite can be gated on
+numbers instead of intuition: run it before the change, run it after, compare.
+
+### Running it
+
+```
+pnpm build
+node scripts/eval-reviewer.mjs
+```
+
+It runs the reviewer configured in `~/.neal/config.yml` (or a repo `neal.yml`)
+against every fixture, so it makes real provider calls and bills whatever that
+reviewer bills. Run it from a checkout with an authenticated Codex/Claude CLI
+to use a subscription, the same as `scripts/qualify-sdk.sh`. It prints a table
+and writes `EVAL_REPORT.json` (gitignored).
+
+### What the numbers mean
+
+- **Recall**: labeled defects the reviewer flagged / all labeled defects. The
+  headline number for a doctrine change: a rewrite that raises precision by
+  suppressing findings will show up here as a recall drop.
+- **Precision**: blocking findings that hit a labeled file / all blocking
+  findings.
+- **Clean false-positive rate**: clean fixtures the reviewer flagged with a
+  blocking finding / clean fixtures.
+- **Blocking rate**: mean blocking findings per fixture, a proxy for how many
+  coder rounds the reviewer would force.
+
+Matching is coarse on purpose: a finding counts for a label when they name the
+same **file**. It measures "did the reviewer flag the right file", not "did it
+describe the exact defect". Do not over-read the absolute numbers. Read the
+**delta** between two prompt versions on the same fixtures.
+
+### Adding fixtures
+
+Fixtures live in `examples/reviewer-eval/`. Each is a directory with a `base/`
+tree (the before state) and a `change.diff`, plus a manifest entry:
+
+```json
+{
+  "id": "off-by-one",
+  "kind": "defective",
+  "diff": "off-by-one/change.diff",
+  "baseDir": "off-by-one/base",
+  "expectedFindings": [
+    { "file": "src/paginate.ts", "defectClass": "off-by-one", "description": "..." }
+  ]
+}
+```
+
+A defective fixture labels at least one file the diff touches. A clean fixture
+labels none. The loader (`src/neal/eval/reviewer-eval-manifest.ts`) enforces
+that structurally: it checks a label points at a file the diff modifies, but
+it does **not** try to prove the diff exhibits the defect. That proof was an
+over-specification. A human authoring the fixture asserts the defect. Keep the
+starter set growing toward ~10–15 fixtures across defect classes.
+
+## Process rule
+
+A pull request that changes reviewer-facing implementation-review prompt text must include:
+
+1. a `version` bump and changelog line on the affected spec (enforced), and
+2. before/after eval numbers in the PR description.
+
+The reviewer-recall fixtures exercise implementation review, not plan review.
+Evaluate `plan_reviewer` prompt changes with representative `neal plan` runs and
+compare objective preservation, scope quality, readability, and review-round
+count. Do not report reviewer-recall numbers for a plan-review-only change as if
+they measured the changed prompt.
+
+The eval is not run in CI (it costs live tokens). The versioning contract is
+the CI-side guard, and the eval numbers are a human review requirement.

package/docs/{PROMPT_SPECS.md → prompt-specs.md}

@@ -1,16 +1,16 @@
-# Neal Prompt Specs Inventory
+# Prompt specs inventory
 
 ## Scope
 
-This document is the current prompt-spec inventory for Neal's recurring
-engineering roles/tasks.
+The current prompt-spec inventory for neal's recurring engineering
+roles/tasks.
 
 - The prompt-spec contract and registry live in
   [src/neal/prompts/specs.ts](../src/neal/prompts/specs.ts).
 - Concrete prompt builders live in `src/neal/prompts/planning.ts`,
   `src/neal/prompts/execute.ts`, and `src/neal/prompts/specialized.ts`, with
   shared plan-contract and marker lines in `src/neal/prompts/shared.ts`.
-- The interactive blocked-recovery and blocked-adjudicator prompt builders live
+- The interactive blocked-recovery and consultant prompt builders live
   in `src/neal/agents/prompts.ts` (which otherwise re-exports the
   `src/neal/prompts/` builders).
 - Schema builders, object validators, and retained compatibility parsers live
@@ -21,14 +21,14 @@ Reviewer prompt surfaces share a doctrine helper in
 [src/neal/prompts/review-doctrine.ts](../src/neal/prompts/review-doctrine.ts).
 That helper owns adversarial posture, falsification, verification skepticism,
 regression-preservation, the pre-existing-failure acceptance-surface contract,
-finding-quality wording, and the three-way reviewer access mode
-(`tool-access` / `read-only` / `no-read`). It does not own schemas, provider
+finding-quality wording, and the two-way reviewer access mode
+(`tool-access` / `read-only`). It does not own schemas, provider
 selection, adjudication, or transition behavior. Its consumers are
-execute-scope review, plan review, and final completion review; the read-only
+execute-scope review, plan review, and final completion review. The read-only
 `neal review` findings loop uses its own prompts in
 `src/neal/review-findings/prompts.ts`.
 
-## Ownership Boundary
+## Ownership boundary
 
 Prompt specs live under `src/neal/prompts/`.
 
@@ -45,32 +45,32 @@ Concrete split:
 
 ## Inventory
 
-### Registered Prompt Specs
+### Registered prompt specs
 
 All schema targets are `structured_json` with provider surface
-`neal_json_block_protocol` — the prompt-spec metadata name for the runtime
+`neal_json_block_protocol`, the prompt-spec metadata name for the runtime
 `neal-json-block-v1` JSON-block transport that providers validate locally.
 
 | Prompt spec id | Current builder(s) | Current round entrypoints | Schema target | Notes |
 | --- | --- | --- | --- | --- |
-| `plan_author` | `buildPlanningPrompt`, `buildCoderPlanResponsePrompt` (`reviewMode=plan`, `reviewMode=derived-plan`) | `runCoderPlanRound`, `runCoderPlanResponseRound` | Primary planning: `buildCoderPlanSchema` / `validateCoderPlanPayload`; response rounds: `buildCoderPlanResponseSchema` / `validateCoderPlanResponsePayload` | Primary planning routes new/resumed structured sessions by persisted `plannerSessionProtocol`; legacy marker parsing is retained only for active `legacy_marker_v1` sessions. |
-| `plan_reviewer` | `buildPlanReviewerPrompt` (`mode=plan`, `mode=derived-plan`) | `runPlanReviewerRound` | `buildPlanReviewerSchema` / `PlanReviewerPayload` | Execution-shape confirmation is part of the contract. Shares skeptical doctrine without becoming implementation diff review. |
-| `scope_coder` | `buildScopePrompt`, `buildCoderResponsePrompt` | `runCoderScopeRound`, `runCoderResponseRound` | Primary execution: `buildCoderScopeSchema` / `validateCoderScopePayload`; response rounds: `buildCoderResponseSchema` / `validateCoderResponsePayload` | Primary execution routes new/resumed structured sessions by persisted `coderSessionProtocol`; legacy marker and progress-payload parsing is retained only for active `legacy_marker_v1` sessions. Also carries an `adjacent`-status blocked-recovery `response` variant (see below). |
-| `scope_reviewer` | `buildReviewerPrompt` | `runReviewerRound` | `buildReviewerSchema` / `ReviewerPayload` | Execute-scope review only; `neal review` external ranges use the separate read-only review-findings loop. Meaningful-progress remains a capability variant of `scope_reviewer`, not a new top-level id. Reviewer prompts include a run-local `scratchDir` requirement for temporary verification artifacts. |
-| `completion_coder` | `buildFinalCompletionSummaryPrompt` | `runCoderFinalCompletionSummaryRound` | `buildFinalCompletionSummarySchema` / `parseFinalCompletionSummaryPayload` | Structured advisor round, but still a coder-owned role/task. The completion packet includes aggregate review context when Neal can compute it. |
-| `completion_reviewer` | `buildFinalCompletionReviewerPrompt` | `runReviewerFinalCompletionRound` | `buildFinalCompletionReviewerSchema` / `parseFinalCompletionReviewerPayload` | Whole-plan aggregate review remains distinct from ordinary scope review and keeps its final-completion verdict schema. Reviewer prompts include a run-local `scratchDir` requirement for temporary verification artifacts. |
+| `plan_author` | `buildPlanningPrompt`, `buildCoderPlanResponsePrompt` (`reviewMode=plan`, `reviewMode=derived-plan`) | `runCoderPlanRound`, `runCoderPlanResponseRound` | Primary planning: `buildCoderPlanSchema` / `validateCoderPlanPayload`. Response rounds: `buildCoderPlanResponseSchema` / `validateCoderPlanResponsePayload`. | Primary planning routes new/resumed structured sessions by persisted `plannerSessionProtocol`. Legacy marker parsing is retained only for active `legacy_marker_v1` sessions. |
+| `plan_reviewer` | `buildPlanReviewerPrompt` (`mode=plan`, `mode=derived-plan`) | `runPlanReviewerRound` | `buildPlanReviewerSchema` / `PlanReviewerPayload` | Execution-shape confirmation is part of the contract. Reviews material approach, scope, sequencing, and verification defects without turning the plan into an implementation inventory. |
+| `scope_coder` | `buildScopePrompt`, `buildCoderResponsePrompt` | `runCoderScopeRound`, `runCoderResponseRound` | Primary execution: `buildCoderScopeSchema` / `validateCoderScopePayload`. Response rounds: `buildCoderResponseSchema` / `validateCoderResponsePayload`. | Primary execution routes new/resumed structured sessions by persisted `coderSessionProtocol`. Legacy marker and progress-payload parsing is retained only for active `legacy_marker_v1` sessions. Also carries an `adjacent`-status blocked-recovery `response` variant (see below). |
+| `scope_reviewer` | `buildReviewerPrompt` | `runReviewerRound` | `buildReviewerSchema` / `ReviewerPayload` | Execute-scope review only. `neal review` external ranges use the separate read-only review-findings loop. Meaningful-progress remains a capability variant of `scope_reviewer`, not a new top-level id. Context includes a run-local `scratchDir`, but read-only reviewer prompts omit it. |
+| `completion_coder` | `buildFinalCompletionSummaryPrompt` | `runCoderFinalCompletionSummaryRound` | `buildFinalCompletionSummarySchema` / `parseFinalCompletionSummaryPayload` | Structured advisor round, but still a coder-owned role/task. The completion packet includes aggregate review context when neal can compute it. |
+| `completion_reviewer` | `buildFinalCompletionReviewerPrompt` | `runReviewerFinalCompletionRound` | `buildFinalCompletionReviewerSchema` / `parseFinalCompletionReviewerPayload` | Whole-plan aggregate review remains distinct from ordinary scope review and keeps its final-completion verdict schema. Context includes a run-local `scratchDir`, but read-only reviewer prompts omit it. |
+| `consultant` | `buildConsultantPrompt` | `runConsultantRound` | `buildConsultantSchema` / `validateConsultantVerdictPayload` | Single no-read-safe variant for the read-only consultant. It judges entirely from neal-inlined context and its static instructions pass the shared no-read guard. |
 
-### Adjacent Current Prompt Surfaces
+### Adjacent current prompt surfaces
 
 These prompts are real but are not separate top-level prompt-spec ids:
 
 | Current builder | Registry status | Schema target | Why not a top-level id |
 | --- | --- | --- | --- |
 | `buildBlockedRecoveryCoderPrompt` (`src/neal/agents/prompts.ts`) | Registered as a `scope_coder` `response` variant with status `adjacent` | `buildCoderBlockedRecoveryDispositionSchema` / `validateCoderBlockedRecoveryDispositionPayload` | It is still the same execute-scope owner responding inside blocked recovery. |
-| `buildBlockedAdjudicatorPrompt` (`src/neal/agents/prompts.ts`) | Not in the prompt-spec registry today; a future change may register it | `buildBlockedAdjudicatorSchema` / `validateBlockedAdjudicatorVerdictPayload` via `runBlockedAdjudicatorRound` | Single no-read-safe variant for the read-only blocked adjudicator; it judges entirely from Neal-inlined context and its static instructions pass the shared no-read guard. |
 | `buildReviewFindingsDraftPrompt`, `buildReviewFindingsReviewPrompt` (`src/neal/review-findings/prompts.ts`) | Not in the prompt-spec registry | `ReviewFindingsDraft` / `ReviewFindingsReview` payloads | Read-only `neal review` findings loop with its own draft/review prompts and read-only rules. |
 
-## Contract Expectations
+## Contract expectations
 
 Each prompt spec in `src/neal/prompts/specs.ts` makes these fields explicit:
 
@@ -95,9 +95,9 @@ Three implementation details are intentionally concrete:
 
 That keeps prompt specs reviewable as contracts rather than as scattered string literals.
 
-## Prompt-Spec Wiring
+## Prompt-spec wiring
 
-Prompt specs are not the whole execution loop. They are the prompt-facing contract layer that tells Neal which role/task is being performed, what context that role/task assumes, and which output contract the result must satisfy.
+Prompt specs are not the whole execution loop. They are the prompt-facing contract layer that tells neal which role/task is being performed, what context that role/task assumes, and which output contract the result must satisfy.
 
 That wiring is intentionally split across a few modules:
 
@@ -106,14 +106,14 @@ That wiring is intentionally split across a few modules:
 - `src/neal/prompts/*.ts` owns the concrete prompt builders that render instructions for planning, execute-mode, and specialized flows.
 - `src/neal/agents/schemas.ts` owns the actual schema builders plus validators or retained parsers named by each spec's `schemaTarget`.
 - `src/neal/agents/rounds.ts` owns round execution and parsing against those schemas.
-- `src/neal/adjudicator/*.ts` owns the adjudication specs that reference prompt surfaces by `(promptSpecId, variantKind, exportName)` (see [ADJUDICATOR_INVENTORY.md](ADJUDICATOR_INVENTORY.md)).
+- `src/neal/adjudicator/*.ts` owns the adjudication specs that reference prompt surfaces by `(promptSpecId, variantKind, exportName)` (see [adjudicator-inventory.md](adjudicator-inventory.md)).
 - `src/neal/orchestrator.ts` and `src/neal/orchestrator/*.ts` own phase transitions, adoption/finalization semantics, blocked-recovery routing, and commit consequences.
 
 That split is deliberate. A prompt spec is incomplete without explicit schema linkage, but it also must not absorb sequencing or state-transition semantics that belong to the orchestrator.
 
-### Context Assembly Rules
+### Context assembly rules
 
-`requiredContext` should be read as a contract for context assembly, not just documentation for a prompt author.
+`requiredContext` should be read as a contract for context assembly, not as documentation for a prompt author.
 
 When adding or changing a prompt spec:
 
@@ -121,37 +121,41 @@ When adding or changing a prompt spec:
 2. The corresponding prompt builder in `src/neal/prompts/*.ts` should either accept that data directly or assemble it from a narrowly-scoped helper. Do not hide major context dependencies inside unrelated utilities.
 3. If a prompt needs new state, artifact, or repository-derived context, add that dependency at the owning layer first and then link it from the spec. Do not document impossible context.
 4. If a field is only used in a variant, keep that distinction explicit in the variant contract instead of pretending it is universally required.
-5. Variant `inputShape` keys must stay a subset of the spec's top-level `requiredContext` keys. Neal validates that contract at module load so prompt-spec drift fails fast in tests and at startup.
+5. Variant `inputShape` keys must stay a subset of the spec's top-level `requiredContext` keys. neal validates that contract at module load so prompt-spec drift fails fast in tests and at startup.
 
-Final completion has one additional context assembly rule: `buildFinalCompletionPacket()` includes `aggregateReviewContext` for the whole implementation range from `initialBaseCommit` to the resolved final commit. When the range can be read, the packet carries commit subjects, diff stat, and changed files; when it cannot, it carries an explicit `unavailableReason` so the reviewer treats the missing aggregate range as evidence to consider instead of silently accepting completion.
+Final completion has one additional context assembly rule: `buildFinalCompletionPacket()` includes `aggregateReviewContext` for the whole implementation range from `initialBaseCommit` to the resolved final commit. When the range can be read, the packet carries commit subjects, diff stat, and changed files. When it cannot, it carries an explicit `unavailableReason` so the reviewer treats the missing aggregate range as evidence to consider instead of silently accepting completion.
 
-Execute-scope and final-completion reviewer prompts also receive a deterministic run-local `scratchDir` under `.neal/runs/<run-id>/scratch/`. Reviewers are instructed to use it for temporary verification artifacts, copied tests, scratch builds, logs, and modified throwaway files, and not to create project-root scratch directories such as `build_review/` or leave project-tree scratch files behind.
+Execute-scope and final-completion reviewer context includes a deterministic
+run-local `scratchDir` under `.neal/runs/<run-id>/scratch/`. A `tool-access`
+prompt tells the reviewer to use that directory for temporary verification
+artifacts. A `read-only` prompt omits the directory and forbids scratch work.
+Every built-in reviewer currently uses `read-only` mode.
 
 The goal is for reviewers to be able to answer two questions quickly:
 
 - "What does this prompt assume is available?"
-- "Where does Neal actually get that data?"
+- "Where does neal actually get that data?"
 
-### Schema-Linkage Rules
+### Schema-linkage rules
 
 `schemaTarget` exists so prompt changes remain coupled to the concrete validator or retained parser surface they must satisfy.
 
 The `PromptSchemaTarget` type admits two kinds:
 
 - `structured_json` means the prompt must remain aligned with a named schema builder and validator or retained object parser in `src/neal/agents/schemas.ts`, delivered through the `neal-json-block-v1` transport.
-- `terminal_marker` means a legacy prompt is governed by a plain-text final-line protocol. It remains in the type, but no current spec or variant declares it — every current schema target is `structured_json`.
+- `terminal_marker` means a legacy prompt is governed by a plain-text final-line protocol. It remains in the type, but no current spec or variant declares it. Every current schema target is `structured_json`.
 
 For coder-owned decisions, `structured_json` maps to
 `CoderAdapter.runStructuredPrompt()` via the shared structured-coder helper.
 `runPrompt(..., outputSchema)` is retained as raw provider compatibility
-outside Neal product control paths; it is not the prompt-spec surface for
-Neal-owned coder decisions. The retained terminal-marker and progress-payload
+outside neal product control paths. It is not the prompt-spec surface for
+neal-owned coder decisions. The retained terminal-marker and progress-payload
 parsers exist only for active `legacy_marker_v1` primary sessions loaded from
 older run state.
 
 If a prompt change would force validator or retained parser behavior to change, treat that as a contract change and review the prompt spec, prompt builder, schema builder, and tests together.
 
-## Provider Variants
+## Provider variants
 
 Provider-specific variants are allowed, but they are not the default escape hatch. Each spec declares `providerVariants` for `shared` (status `default`) plus `openai-codex` and `anthropic-claude` (status `reserved_for_justified_divergence`).
 
@@ -180,9 +184,9 @@ The `neal-json-block-v1` JSON-block transport is intentionally an adapter
 concern, not a prompt-spec variant: the shared prompt builders own review
 substance, schema linkage, and meaningful-progress semantics, while provider
 adapters own the local control-block transport instructions so providers
-return prose plus a final `neal-json` block that Neal validates locally.
+return prose plus a final `neal-json` block that neal validates locally.
 
-## Adjudicator Alignment
+## Adjudicator alignment
 
 Adjudication specs in `src/neal/adjudicator/specs.ts` reference prompt surfaces by `(promptSpecId, variantKind, exportName)`, and that linkage is validated at import time against the prompt-spec registry. The relationship is:
 
@@ -204,7 +208,7 @@ Three current role/task boundaries matter especially:
 - `scope_reviewer` and `completion_reviewer` share adversarial doctrine, but they keep separate schemas and adjudication families
 - `completion_reviewer` is plan-review-adjacent in the adjudicator family mapping, but its execute-mode completion transitions remain outside prompt ownership
 
-## Adding Or Extending Prompt Specs
+## Adding or extending prompt specs
 
 Add prompt specs in a disciplined order:
 
@@ -219,7 +223,7 @@ Use a new top-level `PromptSpecId` only when the role/task is genuinely distinct
 
 - it has its own durable artifact or output contract
 - it has a materially different required-context packet
-- it is expected to recur as an independently understandable Neal surface
+- it is expected to recur as an independently understandable neal surface
 
 Otherwise prefer a variant such as `response`, `derived_plan`, `meaningful_progress`, or `final_completion`.
 
@@ -238,28 +242,28 @@ Current coverage:
 - completion fixtures and render assertions pin aggregate range review, cross-scope invariant review, happy-path reachability, mocked-risk skepticism, and concrete completion-blocking issue quality
 - inventory assertions in `test/review.test.ts` pin module ownership, schema targets, and current-home metadata
 
-The blocked-recovery prompt is covered by the same additive guidance model as its owning coder role; the blocked-adjudicator prompt takes no guidance injection (see below).
+The blocked-recovery prompt is covered by the same additive guidance model as its owning coder role. The consultant prompt takes no guidance injection (see below).
 
-## User Guidance Injection
+## User guidance injection
 
-Users can layer their own guidance onto Neal's built-in coder, reviewer, and planner prompts without forking the prompt source. The injection surface is deliberately additive: built-in sections still own structured coder envelopes, retained legacy terminal-marker compatibility, reviewer verdict JSON schemas, and the canonical plan contract.
+Users can layer their own guidance onto neal's built-in coder, reviewer, and planner prompts without forking the prompt source. The injection surface is deliberately additive: built-in sections still own structured coder envelopes, retained legacy terminal-marker compatibility, reviewer verdict JSON schemas, and the canonical plan contract.
 
 Guidance files (all optional):
 
-- `~/.neal/guidance/coder.md` — injected into scope coder (including the retained legacy variant), scope response, interactive blocked recovery, and final completion summary prompts
-- `~/.neal/guidance/reviewer.md` — injected into scope reviewer, plan reviewer, and final completion reviewer prompts
-- `~/.neal/guidance/planner.md` — injected into plan author (including the retained legacy variant) and plan response prompts
+- `~/.neal/guidance/coder.md`: injected into scope coder (including the retained legacy variant), scope response, interactive blocked recovery, and final completion summary prompts
+- `~/.neal/guidance/reviewer.md`: injected into scope reviewer, plan reviewer, and final completion reviewer prompts
+- `~/.neal/guidance/planner.md`: injected into plan author (including the retained legacy variant) and plan response prompts
 
-The blocked-adjudicator prompt and the `neal review` findings prompts take no guidance injection.
+The consultant prompt and the `neal review` findings prompts take no guidance injection.
 
-By default Neal reads those files from `~/.neal/guidance/`. For each role, a
+By default neal reads those files from `~/.neal/guidance/`. For each role, a
 missing or whitespace-only `~/.neal/guidance/<role>.md` file is a no-op. Set
 `NEAL_GUIDANCE_DIR` to point at another directory with the same file names for
-testing or profile experiments; that override wins over the default directory.
+testing or profile experiments. That override wins over the default directory.
 
-When present, the file contents are appended under a fixed `## User Guidance` section inside the built-in prompt; structured output contracts, completion markers, and the canonical plan contract survive injection.
+When present, the file contents are appended under a fixed `## User Guidance` section inside the built-in prompt. Structured output contracts, completion markers, and the canonical plan contract survive injection.
 
-Diagnostics: when a Neal writer run initializes or resumes, it logs which roles have guidance applied and the byte count to the run's `stderr.log` and as a `run.user_guidance_applied` / `run.user_guidance_scanned` event. That is enough to confirm a guidance file was picked up without dumping contents.
+Diagnostics: when a neal writer run initializes or resumes, it logs which roles have guidance applied and the byte count to the run's `stderr.log` and as a `run.user_guidance_applied` / `run.user_guidance_scanned` event. That is enough to confirm a guidance file was picked up without dumping contents.
 
 Non-goals: no repo-local `.neal/guidance/` override, no full-prompt replacement, no per-scope guidance variants, and no substitution of built-in sections.