@navels/neal 0.2.0 → 0.3.1

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

package/docs/storage.md

@@ -1,15 +1,15 @@
-# Neal Storage Contract
+# Storage contract
 
-Neal uses project-local `.neal/` storage as the source of truth for runs, queues,
+neal uses project-local `.neal/` storage as the source of truth for runs, queues,
 review artifacts, recovery artifacts, progress, and audit history. User-level
 storage is reserved for configuration, guidance, caches, logs, and future
 optional discovery helpers.
 
-This document describes the product-level storage contract. The state transition
-and validation details for run and queue ledgers are documented separately in
+The storage contract here is product-level. Run and queue ledger state
+transition and validation details are documented separately in
 [state-machine.md](state-machine.md).
 
-## Public Automation Surface
+## Public automation surface
 
 `neal status --json` and `neal status --json --all` are the stable automation
 contracts. Scripts should prefer them over parsing raw files under `.neal/`.
@@ -37,9 +37,9 @@ know a run id. Important stable fields include:
 - `providerError` with the latest provider failure or unclassified phase error,
   including timestamp, provider id, role, label, session handle, normalized
   error kind, bounded message, and retryability where available.
-- `build` with Neal package version, Neal source Git SHA when available, Node
+- `build` with neal package version, neal source Git SHA when available, Node
   version, source marker (`meta` or `live_fallback`), and the persisted
-  coder/reviewer agent config.
+  planner/coder/reviewer agent config.
 - `artifacts` with run-local paths for the human narrative, review, progress,
   support, and related diagnostic artifacts.
 
@@ -61,30 +61,38 @@ command output.
 Storage classifications used below are: stable CLI surface, user-facing human
 artifact, support/debug artifact, internal state, and lock/concurrency artifact.
 The stable CLI surfaces in this storage contract are `neal status --json` and
-`neal status --json --all`; the project-local files are artifacts that support
-Neal operations and diagnostics.
+`neal status --json --all`. The project-local files are artifacts that support
+neal operations and diagnostics.
 
-## Project-Local Layout
+## Project-local layout
 
 | Path | Classification | Contract |
 | --- | --- | --- |
-| `.neal/runs/<run-id>/RUN_STATE.json` | Internal state | Child-run ledger. Neal validates current v1 state on read, but scripts should use `neal status --json` rather than depend on this file as a public API. |
+| `.neal/runs/<run-id>/RUN_STATE.json` | Internal state | Child-run ledger. neal validates current v1 state on read, but scripts should use `neal status --json` rather than depend on this file as a public API. |
 | `.neal/runs/<run-id>/events.ndjson` | Support/debug artifact | Append-only event log for audit, diagnostics, command output references, and provider/runtime events. Readers should tolerate malformed or partial final lines where implemented. |
 | `.neal/runs/<run-id>/stderr.log` | Support/debug artifact | Append-only stderr transcript for writer runs. It includes visible narrative lines plus low-level detail such as provider/tool telemetry, command output, reviewer context, and heartbeat diagnostics that may be hidden from the normal terminal stream. |
-| `.neal/runs/<run-id>/meta.json` | Support/debug artifact | Run metadata used for diagnostics. New writes include `version: 1`; metadata alone cannot make a run selectable for squash or status. It is not the stable automation surface. |
+| `.neal/runs/<run-id>/meta.json` | Support/debug artifact | Run metadata used for diagnostics. New writes include `version: 1`. Metadata alone cannot make a run selectable for squash or status. It is not the stable automation surface. |
 | `.neal/runs/<run-id>/PLAN_ORIGINAL.md` | Support/debug artifact | Original plan document backup for `neal plan` runs, written before in-place plan refinement so the pre-refinement input remains inspectable. |
-| `.neal/runs/<run-id>/scratch/` | Support/debug artifact | Run-local scratch root for execute-scope and final-completion reviewer verification artifacts such as copied tests, scratch builds, logs, and modified throwaway files. It is not durable state, but it remains project-local `.neal/` data for retention and privacy purposes. |
-| `.neal/runs/<run-id>/plan-progress.json` | Internal state | Machine-readable v1 progress artifact used by Neal context and summaries. |
+| `.neal/runs/<run-id>/DERIVED_PLAN_SCOPE_<scope>.md` | User-facing human artifact | Replacement execution plan produced when the coder splits an active scope. |
+| `.neal/runs/<run-id>/SCOPE_<scope>_INVALID_DERIVED_PLAN.md` | Support/debug artifact | Rejected split-plan payload and its validation errors. Written only when the returned replacement plan is invalid. |
+| `.neal/runs/<run-id>/SCOPE_<scope>_DISCARDED.diff` | Support/debug artifact | Scope work preserved before neal resets it while adopting a replacement plan. |
+| `.neal/runs/<run-id>/GATE-<id>.md` | User-facing human artifact | Instructions and resume checks for an active manual gate. |
+| `.neal/runs/<run-id>/scratch/` | Support/debug artifact | Reserved run-local scratch root for execute-scope and final-completion review. Read-only reviewer prompts do not use it. It is not durable state, but it remains project-local `.neal/` data for retention and privacy purposes. |
+| `.neal/runs/<run-id>/plan-progress.json` | Internal state | Machine-readable v1 progress artifact used by neal context and summaries. |
 | `.neal/runs/<run-id>/PLAN_PROGRESS.md` | User-facing human artifact | Human-readable progress summary for the active plan or scope. |
 | `.neal/runs/<run-id>/RETROSPECTIVE.md` | User-facing human artifact | Human-readable retrospective or checkpoint summary. Archived variants such as `RETROSPECTIVE-scope-*.md` may also exist. |
+| `.neal/runs/<run-id>/RUN_METRICS.json` | Support/debug artifact | Machine-readable metrics paired with the current retrospective. Archived variants such as `RUN_METRICS-scope-*.json` may also exist. |
 | `.neal/runs/<run-id>/RUN_NARRATIVE.md` | User-facing human artifact | Human-readable run narrative. It includes a benchmark trace section with status, patch-policy, provider-error, and reproducibility summaries suitable for public result bundles. |
-| `.neal/runs/<run-id>/RUN_NARRATIVE.json` | Internal state | Narrative source data that Neal may read to update the human narrative. It is not a public trace artifact. |
+| `.neal/runs/<run-id>/RUN_NARRATIVE.json` | Internal state | Narrative source data that neal may read to update the human narrative. It is not a public trace artifact. |
 | `.neal/runs/<run-id>/REVIEW.md` | User-facing human artifact | Scope or plan review history and findings. |
+| `.neal/runs/<run-id>/REVIEW-<commit>.md` | User-facing human artifact | Archived review history for an accepted scope commit. |
+| `.neal/runs/<run-id>/REVIEWER_CONTEXT.md` | Support/debug artifact | Bounded reviewer-continuity packet rendered for inspection. |
+| `.neal/runs/<run-id>/REVIEWER_CONTEXT.json` | Support/debug artifact | Machine-readable reviewer-continuity packet without the rendered prompt markdown. |
 | `.neal/runs/<run-id>/RECOVERY.md` | User-facing human artifact | Interactive blocked-recovery transcript/history for a run. |
 | `.neal/runs/<run-id>/FINAL_COMPLETION_REVIEW.md` | User-facing human artifact | Whole-plan final completion review. |
 | `.neal/runs/<run-id>/SQUASH_RESULT.json` | Support/debug artifact | Versioned audit artifact from `neal squash`. It records the squash decision/result but is not the stable automation surface. |
 | `.neal/runs/<run-id>/QUEUE_LINK.json` | Internal state | Link from a child run back to its parent plan-and-execute queue item. |
-| `.neal/queues/<queue-id>/QUEUE_STATE.json` | Internal state | Parent queue ledger. Neal validates it on read, but it is not a public JSON API. |
+| `.neal/queues/<queue-id>/QUEUE_STATE.json` | Internal state | Parent queue ledger. neal validates it on read, but it is not a public JSON API. |
 | `.neal/queues/<queue-id>/QUEUE_SUMMARY.md` | User-facing human artifact | Human-readable summary for a plan-and-execute queue. |
 | `.neal/reviews/<review-id>/meta.json` | Support/debug artifact | Review metadata for a read-only `neal review` request. |
 | `.neal/reviews/<review-id>/events.ndjson` | Support/debug artifact | Append-only review event log. |
@@ -97,19 +105,20 @@ Neal operations and diagnostics.
 | `.neal/current.json` | Internal state | Default writer-run pointer for commands that need the current run. |
 | `.neal/current-queue.json` | Internal state | Preferred current plan-and-execute queue pointer. |
 | `.neal/active-run.lock` | Lock/concurrency artifact | Active writer-run lock. It prevents unrelated writer commands from mutating the same checkout concurrently. |
+| `.neal/NOTES.md` | User-facing human artifact | Optional operator-authored notes included in bounded context packets. neal reads this file but does not create it. |
 
 Writer processes remove their own active lock during normal shutdown and on
-`SIGINT`/`SIGTERM`. Timeout wrappers should still launch Neal in a process group
+`SIGINT`/`SIGTERM`. Timeout wrappers should still launch neal in a process group
 and terminate the group, because provider-owned child processes are outside the
 lock file contract. After a timeout, call `neal status --json --run <run-id>`
-when the run id is known; treat the wrapper timeout as the primary result while
-using `status`, `health`, and `lock.kind` to record whether Neal's run state is
+when the run id is known. Treat the wrapper timeout as the primary result while
+using `status`, `health`, and `lock.kind` to record whether neal's run state is
 still running, cleaned up, live, stale, cross-host, or unreadable.
 
-## Patch Automation Policy
+## Patch automation policy
 
 Default public prediction submission should use only
-`patch.defaultSubmissionEligible: true`. Neal sets that value only for clean
+`patch.defaultSubmissionEligible: true`. neal sets that value only for clean
 completed execute runs with a non-empty readable patch range.
 
 When a completed run has a successful squash artifact, the status read model
@@ -124,28 +133,28 @@ runs may still report patch-bearing metadata for diagnostics or private
 analysis. They are not default-submission eligible, and `patch.reason` explains
 why.
 
-## Source Of Truth
+## Source of truth
 
 Project-local `.neal/` remains the source of truth for run, queue, review,
 recovery, progress, and audit artifacts.
 
 Run-local `.neal/runs/<run-id>/RUN_STATE.json` is the only writer-run ledger
-path Neal writes. `.neal/current.json` points at the default writer run; it is a
+path neal writes. `.neal/current.json` points at the default writer run. It is a
 pointer, not a copy of the ledger.
 
 There is no required global run index in v1. Future global discovery, if added,
 must be optional and rebuildable from project-local data. It must not become the
 only place where run or queue history can be recovered.
 
-## Ledgers And Pointers
+## Ledgers and pointers
 
 `.neal/runs/<run-id>/RUN_STATE.json` and
-`.neal/queues/<queue-id>/QUEUE_STATE.json` are persisted ledgers. Neal validates
+`.neal/queues/<queue-id>/QUEUE_STATE.json` are persisted ledgers. neal validates
 them on read. Child-run state uses strict current v1 hydration: missing or
 malformed required child-run fields fail instead of receiving defaults. These
 ledgers are not public JSON APIs.
 
-Neal does not write, read, migrate, or repair a session mirror. Use
+neal does not write, read, migrate, or repair a session mirror. Use
 `.neal/current.json` as the default writer-run pointer, `neal status --all` to
 discover run IDs, and `--run <run-id>` when selecting a specific run for
 `resume` or `status`.
@@ -154,9 +163,9 @@ Squash discovery requires readable run-local state. Run metadata and progress
 artifacts can help humans inspect a run, but they cannot make a run selectable
 for `neal squash` without `.neal/runs/<run-id>/RUN_STATE.json`.
 
-## Schema Versions And Writes
+## Schema versions and writes
 
-Neal-owned JSON schemas use `version: 1` where they are read back as durable
+neal-owned JSON schemas use `version: 1` where they are read back as durable
 state or audit data. That includes child-run state, current run pointers, queue
 state, current queue pointers, queue child links, progress summaries, run
 narratives, squash audit results, review artifacts, and the active writer lock.
@@ -172,7 +181,7 @@ files such as state, progress, reviews, and pointers can briefly disagree if a
 process stops between writes. Append-only event logs remain append-only, and the
 active writer lock keeps exclusive file creation for acquisition.
 
-## Retention And Privacy
+## Retention and privacy
 
 `.neal/` may contain prompts, local paths, command output, diffs, review text,
 provider responses, user guidance diagnostics, reviewer scratch files, copied
@@ -188,7 +197,7 @@ Run and review artifacts are intentionally inspectable, but they should be
 treated as project data. Apply the same retention and access controls you use
 for source, logs, and local debugging output.
 
-## Manual Cleanup
+## Manual cleanup
 
 Manual cleanup is safe only when you no longer need resume, history, diagnostics,
 or audit data for the item being removed.
@@ -202,6 +211,6 @@ Reasonable manual cleanup options:
 - remove stale `.neal/current.json` or `.neal/current-queue.json` pointers only
   after confirming they do not point to work you still intend to resume
 
-Deleting run or queue state removes Neal's resume and history for that run or
+Deleting run or queue state removes neal's resume and history for that run or
 queue. Prefer keeping the full directory until the related work has been merged,
 archived, or otherwise recorded somewhere durable.

package/docs/troubleshooting.md

@@ -6,7 +6,7 @@ prints. When in doubt: `neal check`, then `.neal/runs/<run-id>/stderr.log`.
 ## Install and first run
 
 **Symptom:** install or startup fails on an old Node.
-**Cause:** neal requires Node.js >= 22.13 (`engines`); `.nvmrc` pins `24`.
+**Cause:** neal requires Node.js >= 24.18.0 (`engines`). `.nvmrc` pins `24.18.0`.
 **Fix:** `nvm use` in this repo, or upgrade Node before `npm install -g @navels/neal`.
 
 **Symptom:** `pnpm: command not found` when running from source.
@@ -20,13 +20,13 @@ After source changes, `pnpm build` again so the linked command sees `dist/`.
 
 **Symptom:** `neal setup` lists a provider with `- runtime not found`.
 **Cause:** setup detects local runtime surfaces only (the `@openai/codex-sdk`
-entrypoint; an SDK-bundled or on-PATH `claude` executable) — never auth.
+entrypoint, an SDK-bundled or on-PATH `claude` executable), never auth.
 **Fix:** install the provider's SDK/CLI, then rerun `neal setup` and `neal check`.
 
 ## Provider auth failures (`neal check`)
 
 `neal check` sends one small prompt per unique configured provider/model
-(interactive TTY only — non-interactive input prints
+(interactive TTY only. Non-interactive input prints
 `Provider verification skipped: non-interactive input.`). Known failures:
 
 **Symptom:** `Claude Code refused bypass-permissions mode while running as root.`
@@ -40,31 +40,34 @@ Claude Code refuses under root/sudo.
 directory (e.g. run the `codex` CLI there once), then `neal check` again.
 
 **Symptom:** `OpenAI Codex could not persist the check session.`
-**Fix:** transient; run `neal check` again. If it repeats, redo the provider's
+**Fix:** transient. Run `neal check` again. If it repeats, redo the provider's
 local setup.
 
 **Symptom:** a `not logged in` message from either vendor CLI.
-**Cause:** provider auth is provider-owned; neal never collects credentials.
+**Cause:** provider auth is provider-owned, so neal never collects credentials.
 **Fix:** complete the provider's normal local auth setup (the `codex` / `claude`
 login flows), then `neal check` again.
 
 **Symptom:** `Set providers.openai_compatible.base_url (or OPENAI_COMPATIBLE_BASE_URL) and OPENAI_COMPATIBLE_API_KEY before running Neal.`
 (or `No model is resolvable for the openai-compatible ... role`).
-**Cause:** `openai-compatible` / `generic-agentic` resolve settings config-first
-with env fallbacks: `base_url` → `OPENAI_COMPATIBLE_BASE_URL`; the key is read
-from the env var named by `api_key_env` (default `OPENAI_COMPATIBLE_API_KEY`);
-model from `agent.<role>.model` → `default_model` → `OPENAI_COMPATIBLE_MODEL`.
+**Cause:** `openai-compatible` resolves settings from config first,
+with env fallbacks: `base_url` → `OPENAI_COMPATIBLE_BASE_URL`. The key is read
+from the env var named by `api_key_env` (default `OPENAI_COMPATIBLE_API_KEY`).
+Model from `agent.<role>.model` → `default_model` → `OPENAI_COMPATIBLE_MODEL`.
 **Fix:** set the missing key. For OpenRouter: `base_url: https://openrouter.ai/api/v1`,
 `api_key_env: OPENROUTER_API_KEY`, and export `OPENROUTER_API_KEY`. (OpenRouter
-wraps upstream 429s in HTTP-200 bodies; neal unwraps and retries them.)
+wraps upstream 429s in HTTP-200 bodies, so neal unwraps and retries them.)
 
 ## Runs that won't start
 
-**Symptom:** plan validation errors such as
-`Missing required `## Execution Shape` section.` or
-``## Execution Shape` must contain exactly one non-empty line.`
+**Symptom:** plan validation errors such as:
+
+```text
+Missing required `## Execution Shape` section.
+`## Execution Shape` must contain exactly one non-empty line.
+```
 **Cause:** every executable plan must declare exactly one of
-`executionShape: one_shot | multi_scope | multi_scope_unknown`; `multi_scope`
+`executionShape: one_shot | multi_scope | multi_scope_unknown`. `multi_scope`
 also requires an `## Execution Queue` with contiguous `### Scope N:` headings,
 each carrying `- Goal:` / `- Verification:` / `- Success Condition:` bullets.
 **Fix:** see [plan-format.md](plan-format.md), or let `neal plan` refine the
@@ -72,23 +75,23 @@ document into executable shape.
 
 **Symptom:** a missing-config error naming `agent.coder.provider` or
 `agent.reviewer.provider`.
-**Cause:** fresh writer runs require explicit coder and reviewer providers;
-built-in defaults are not enough.
+**Cause:** fresh writer runs require explicit coder and reviewer providers.
+Built-in defaults are not enough.
 **Fix:** `neal setup`, then `neal check`.
 
 **Symptom:** `Cannot start neal execute with a dirty worktree:` followed by
 `git status` lines (queues: `Cannot continue neal run with a dirty worktree:`).
-**Cause:** writer admission requires a clean worktree; only the selected plan
+**Cause:** writer admission requires a clean worktree. Only the selected plan
 document and neal-owned paths (`.neal/`) are exempt. Leftover reviewer scratch
 (`build_review/`, `scratch/`, …) gets a
-`Likely Neal reviewer scratch leakage detected:` diagnostic but still blocks —
-the paths are not proven neal-owned.
+`Likely Neal reviewer scratch leakage detected:` diagnostic but still blocks,
+because the paths are not proven neal-owned.
 **Fix:** use `neal resume` for in-progress scope work, or commit, stash, move,
 or remove the dirty paths and start clean.
 
 **Symptom:** a Git precondition error before any provider runs.
 **Fix:** writer commands require a Git repository with an existing `HEAD`
-commit; create the initial baseline commit first.
+commit. Create the initial baseline commit first.
 
 ## Stuck or blocked runs
 
@@ -100,26 +103,26 @@ something it may not resolve alone, and attended runs wait for guidance.
 accepted in that waiting-for-guidance state.
 
 **Symptom:** `effectiveStatus: "waiting_for_manual_gate"`.
-**Cause:** the scope reached expected human work; instructions are in the
+**Cause:** the scope reached expected human work. Instructions are in the
 run-local `GATE-<id>.md` file shown by `neal status`.
-**Fix:** do the manual step, then `neal resume --run <run-id>` — it re-runs
+**Fix:** do the manual step, then `neal resume --run <run-id>`, which re-runs
 the gate's checks and resumes the scope when they pass. No `--message` here.
 
 **Symptom:** a run seems hung or died silently.
 **Where to look:** raw detail is persisted even when hidden from the terminal:
 `.neal/runs/<run-id>/stderr.log` (full transcript) and
-`.neal/runs/<run-id>/events.ndjson` (event log; startup-silence retries appear
-as `provider.turn_liveness_*` events). On a live TTY, press `v` for the
+`.neal/runs/<run-id>/events.ndjson` (event log, where startup-silence retries
+appear as `provider.turn_liveness_*` events). On a live TTY, press `v` for the
 low-level detail view. `neal status --json --run <run-id>` carries the latest
 `providerError` classification.
 
 ## Lock issues
 
-The writer lock is `.neal/active-run.lock`; writer processes remove it on
+The writer lock is `.neal/active-run.lock`. Writer processes remove it on
 normal shutdown and on SIGINT/SIGTERM.
 
 **Symptom:** `another Neal writer run is active in this checkout`.
-**Fix:** as printed — `neal resume --run <run-id>` to continue that run, or
+**Fix:** as printed: `neal resume --run <run-id>` to continue that run, or
 wait for it to finish.
 
 **Symptom:** `another Neal process is already resuming this run` (with
@@ -128,17 +131,17 @@ wait for it to finish.
 
 **Symptom:** `stale Neal writer lock found in this checkout` /
 `no process with that PID is running on this host.`
-**Fix:** `neal resume --run <run-id>` clears stale same-host locks itself; if
+**Fix:** `neal resume --run <run-id>` clears stale same-host locks itself. If
 you're starting different work instead, inspect the run, then remove the lock
 file the message names.
 
 **Symptom:** `Neal writer lock belongs to another host`.
-**Fix:** inspect the other host before removing the lock; the message prints
+**Fix:** inspect the other host before removing the lock. The message prints
 the exact resume command for that checkout.
 
 **Symptom:** `could not read the active Neal writer lock`.
 **Fix:** as printed: inspect the named lock file before starting another
-writer run; remove it only after confirming no writer process is active.
+writer run. Remove it only after confirming no writer process is active.
 
 ## "It squashed when I didn't want it to"
 

package/examples/compat/add-edit-verify/PLAN.md

@@ -1,5 +1,7 @@
 # Compat fixture: fix `add`
 
+> Fixture note: this plan describes the pre-fix state and is intentionally not updated after the fix lands.
+
 ## Execution Shape
 
 executionShape: one_shot

package/examples/compat/add-edit-verify/broken.diff

@@ -1,8 +1,8 @@
 diff --git a/src/add.js b/src/add.js
-index 4125f75..a3e4914 100644
+index 6946b9a..e9fa11d 100644
 --- a/src/add.js
 +++ b/src/add.js
 @@ -1,2 +1,2 @@
- // Trivial compat fixture: this addition helper is intentionally buggy.
+ // Trivial compat fixture: an arithmetic helper exercised by test/add.test.js.
 -export const add = (a, b) => a - b;
 +export const add = (a, b) => a * b;

package/examples/compat/add-edit-verify/good.diff

@@ -1,8 +1,8 @@
 diff --git a/src/add.js b/src/add.js
-index 4125f75..0088c50 100644
+index 6946b9a..ee66238 100644
 --- a/src/add.js
 +++ b/src/add.js
 @@ -1,2 +1,2 @@
- // Trivial compat fixture: this addition helper is intentionally buggy.
+ // Trivial compat fixture: an arithmetic helper exercised by test/add.test.js.
 -export const add = (a, b) => a - b;
 +export const add = (a, b) => a + b;