@navels/neal 0.1.0

package/docs/release.md

@@ -0,0 +1,147 @@
+# Release Process
+
+This is the canonical tracked release guide for Neal. Releases are manual,
+versioned npm operations. Normal CI remains verification-only for pushes and
+pull requests; publishing is isolated to the GitHub Actions `Publish` workflow,
+which is triggered manually with `workflow_dispatch`.
+
+## Versioning Policy
+
+Neal uses Semantic Versioning. `package.json.version` changes only in an
+intentional release-preparation pull request, not in ordinary implementation
+commits. Release versions are exact SemVer strings without a leading `v`, and
+an npm version must never be reused.
+
+Before `1.0.0`, minor releases may include meaningful behavior changes while
+the CLI, configuration, exit-code, and artifact contracts settle. After
+`1.0.0`, breaking changes to documented CLI commands, flags, configuration,
+exit codes, or durable run artifacts require a major version.
+
+Examples:
+
+- Patch: `0.1.1` fixes a defect or compatibility issue without intentionally
+  changing documented behavior.
+- Minor before `1.0.0`: `0.2.0` adds a feature or meaningful behavior change
+  while the public contract is still settling.
+- Major: `1.0.0` establishes the stable public contract; later breaking
+  contract changes require `2.0.0`, `3.0.0`, and so on.
+
+## SDK Dependency Policy
+
+Direct coding-agent and AI SDK runtime dependencies must use exact SemVer specs
+in `package.json`. Do not use `latest`, caret ranges, tilde ranges, wildcards,
+workspace specs, file specs, or link specs for these direct dependencies in a
+published CLI package:
+
+- `@anthropic-ai/claude-agent-sdk`
+- `@openai/codex-sdk`
+- `ai`
+- `@ai-sdk/openai-compatible`
+- `zod`
+
+An SDK update should land as a normal dependency pull request that updates both
+`package.json` and `pnpm-lock.yaml`, runs normal CI, and records any provider
+compatibility findings. The resulting Neal release should match the user-facing
+impact: use a patch release for a compatibility fix that preserves documented
+behavior, a minor release for behavior changes before `1.0.0`, and a major
+release after `1.0.0` if a documented public contract breaks.
+
+## Local Release Readiness
+
+Prepare a release with a normal pull request that changes `package.json.version`
+to the intended exact SemVer version:
+
+```sh
+pnpm version <version> --no-git-tag-version
+```
+
+Run the local release-readiness gates from the repository root:
+
+```sh
+RELEASE_VERSION=<version> RELEASE_DRY_RUN=true pnpm run validate:release
+pnpm typecheck
+pnpm test
+pnpm build
+node scripts/verify-package.mjs
+```
+
+`validate:release` checks that the workflow input version matches
+`package.json.version`, validates required package metadata, checks npm version
+availability, and checks remote `v<version>` tag availability when an `origin`
+remote is configured. Package verification confirms the built CLI and packed
+tarball.
+
+## Manual Publish Workflow
+
+After the release-preparation pull request is merged and normal CI passes, run
+the `Publish` workflow manually from `main` with:
+
+- `version`: the exact `package.json.version`, without a leading `v`
+- `dry_run`: `true`
+
+The workflow is guarded to `refs/heads/main`, uses the `npm-publish`
+environment, grants `contents: read` and `id-token: write`, installs with
+`pnpm install --frozen-lockfile`, and runs these gates before any publish step:
+
+```sh
+RELEASE_VERSION=<version> RELEASE_DRY_RUN=<dry_run> pnpm run validate:release
+pnpm typecheck
+pnpm test
+pnpm build
+node scripts/verify-package.mjs
+```
+
+Review the dry-run result before any real publish. Run `Publish` again with
+`dry_run: false` only when a first-publish or later release-preparation plan has
+explicitly authorized the real publish.
+
+## First-Publish Boundary
+
+`@navels/neal` is not yet published to the npm registry. Local validation and
+the workflow run dry-run release checks, including `npm publish --dry-run
+--access public`. A real public publish (`npm publish --access public`) happens
+only on the `dry_run: false` path, under the configured npm trusted publishing
+and an explicit authorization from a first-publish or later release-preparation
+plan.
+
+## Trusted Publishing Setup
+
+The publish workflow relies on trusted publishing/OIDC and intentionally has no
+npm-token fallback. It grants `id-token: write` for OIDC, keeps repository
+contents read-only, uses the `npm-publish` GitHub environment, and publishes
+with `npm publish --access public` only on the real-publish path.
+
+Use this npm CLI setup command as the trusted publisher reference:
+
+```sh
+npm install -g npm@^11.10.0
+npm trust github @navels/neal --repo navels/neal --file publish.yml --env npm-publish --allow-publish
+```
+
+Current first-publish limitation: `@navels/neal` is not currently published, and
+the `npm trust github` command may be blocked until the package already exists
+on the npm registry. The npm trusted publisher configuration must match the
+repository workflow: package `@navels/neal`, owner/repo `navels/neal`, workflow
+filename `publish.yml`, environment `npm-publish`, and allowed action
+`npm publish`.
+
+## Release Boundaries
+
+The current workflow checks that the remote `v<version>` tag is available, but
+it does not create tags or GitHub releases. Do not promise or perform release
+marker creation as part of the current publish workflow. If tags or GitHub
+releases are needed after a successful publish, add them in a separate plan with
+the required permissions and explicit operator approval.
+
+Recovery rule for later real publishes: if `npm publish` succeeds but a later
+release-marker step fails in a separate plan, do not rerun the publish blindly.
+First confirm the npm version exists, then create only the missing marker.
+
+Official references:
+
+- GitHub `workflow_dispatch` inputs:
+  <https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow>
+- npm trusted publishing:
+  <https://docs.npmjs.com/trusted-publishers/>
+- npm trust command:
+  <https://docs.npmjs.com/cli/v11/commands/npm-trust/>

package/docs/state-machine.md

@@ -0,0 +1,266 @@
+# Neal 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.
+
+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.
+
+## 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-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
+
+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.
+
+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
+
+Persisted v1 child-run state remains record-shaped, but most callers should not
+treat `OrchestrationState` as one large nullable programming model.
+`src/neal/state-views.ts` exposes typed views over the current v1 fields without
+changing the stored JSON shape:
+
+- shared metadata and public lifecycle views
+- plan and execute run views
+- interactive blocked-recovery views
+- derived-plan and final-completion views
+
+The public lifecycle view treats `status` as the product-facing lifecycle owner
+and treats `phase` as an internal runnable cursor or diagnostic detail.
+`src/neal/run-status.ts` and status rendering build on that lifecycle view so
+human output can say `waiting_for_guidance`, `paused`, `blocked`, `failed`, or
+`done` without requiring users to interpret raw phase names.
+
+`neal status --json` remains the stable automation surface. It still exposes raw
+`phase` and `status` fields for diagnostics, and it preserves derived public
+fields such as `effectiveStatus`, `waitingForOperatorGuidance`, and
+`pendingOperatorGuidance`.
+
+## 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.
+
+The enforced phase/status relationship is intentionally small:
+
+- `phase === 'done'` if and only if `status === 'done'`.
+- `phase === 'blocked'` may use `status === 'blocked'` or `status === 'failed'`.
+- `status === 'running'` is invalid with terminal `done` or `blocked` phases.
+- Failed states may preserve the phase that failed, because provider, reviewer, coder, or artifact errors are useful to resume and diagnostic tooling only when the failing phase remains visible.
+
+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
+
+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.
+
+Public resume eligibility is classified by `src/neal/resume-decision.ts` before
+any recovery mutation. That read-only decision layer combines loaded child-run
+state with lock, queue, and retrospective evidence, then returns the shared
+vocabulary used by `neal resume`, `neal status`, and run narratives: continue,
+needs message, pending message, already running, done, or cannot resume.
+
+Blocked resume eligibility still depends on the planner actions from
+`src/neal/resume-planner.ts`, with the orchestrator recovery code applying the
+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` / `agent.unattended` resolves to a persisted
+`OrchestrationState.unattended` boolean (default `false`) for both plan and
+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
+byte-identical to attended output.
+
+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
+  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
+  `interactiveBlockedRecovery.maxTurns`), it appends a synthesized conservative
+  guidance turn (`UNATTENDED_AUTO_RESUME_GUIDANCE` from
+  `src/neal/blocked-guidance.ts`) via the same turn-recording helper a human
+  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
+  `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`,
+  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`
+  / `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
+  (`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
+  `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`.
+  The decisions are auditable from the structured event log via the
+  `review_stuck_arbiter.{start,verdict,resolved,declined,exhausted}` 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.**
+  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
+  unattended they run the shared terminal-fail action immediately rather than
+  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
+  blocks (`topLevelMode === 'execute'`) re-enter site A and are handled there.
+
+The shared terminal-fail action is `persistUnattendedBlockUnresolvedFailure`
+(`src/neal/orchestrator/phases/shared.ts`), which mirrors the
+`persistCoderFailureState` failed-run shape: save `status:'failed'` (preserving
+`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`,
+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
+retrospective. Attended runs are unchanged and still wait for
+`neal resume --message` at all three sites.
+
+## Resume Planning
+
+New-run initialization and existing-run resume reconciliation are separate.
+`loadOrInitialize` still provides the command-facing entrypoint, but resume
+reconciliation is modeled as explicit `ResumeAction` values from
+`planResumeActions` and applied by `applyResumeActions`.
+
+Current resume actions cover stopped-status normalization, restoring a resumable
+blocked source phase, keeping non-resumable blocked runs blocked, promoting
+accepted or pending unexecuted derived plans, blocking rejected abandoned derived
+plans, flushing derived-plan notifications, recovering clean committed
+scope work that is waiting for review, waiting for operator guidance, processing
+pending operator guidance, and no-op completion for done runs.
+
+`neal resume` is the safe first recovery command for mechanical interruptions.
+The command gathers read-only context, asks the shared decision layer what should
+happen, and calls `loadRunForResume()` only for decisions that should execute
+the selected run. `loadRunForResume()` remains the mutation boundary for resume
+normalization, event logging, pointer writes, and execution artifacts.
+
+`neal resume --run <run-id> --message "..."` is the operator-input path only
+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
+advance or repair the parent queue by itself.
+
+## 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:
+
+- A non-null `derivedPlanStatus` requires a non-null `derivedPlanPath`.
+- A `derivedScopeIndex` requires execute mode, an accepted derived plan, a parent scope number, and a plan path.
+- `awaiting_derived_plan_execution` requires an accepted derived plan that has not started executing yet and no active created commits.
+- Pending or rejected derived plans cannot have a `derivedScopeIndex`.
+
+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 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.
+
+## 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.
+
+## Change Checklist
+
+When adding a child-run phase:
+
+- Add the phase to `OrchestrationPhase` in `src/neal/types.ts`.
+- Add it to `ORCHESTRATION_PHASES` in `src/neal/state-invariants.ts`.
+- If it is runnable, add it to `RUNNABLE_PHASE_REGISTRY` in `src/neal/orchestrator/run-loop.ts`.
+- Update any recovery or blocked-resume phase sets that should include or exclude it.
+- Add tests in `test/state-invariants.test.ts` or `test/run-loop.test.ts` for the new membership and dispatch contract.
+
+When adding a child-run persisted field:
+
+- Add the type in `OrchestrationState`.
+- Initialize it in `createInitialState`.
+- Parse it in `normalizeStateV1`.
+- Validate semantic combinations in `assertValidOrchestrationState` when the field can make state invalid.
+- Extend state round-trip or invariant tests.
+
+When adding a queue-state field:
+
+- Add the type in `PlanAndExecuteQueueState` or `PlanAndExecuteQueueItem`.
+- Initialize it in queue creation or child transition helpers.
+- 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
+
+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
+hydration isolated, keep semantic checks centralized in `state-invariants.ts`,
+and route new logic through typed state views and the resume planner.
+
+After those views have stabilized in real runs and tests, a v2 envelope or
+discriminated internal TypeScript model can be considered separately. Any future
+shape should preserve `neal status --json` as the automation contract and keep
+v1 run-local ledgers readable unless an explicit migration command exists.

package/docs/storage.md

@@ -0,0 +1,207 @@
+# Neal Storage Contract
+
+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
+[state-machine.md](state-machine.md).
+
+## 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/`.
+The status JSON includes public status and phase strings, next action, commit
+and patch summaries, provider-error metadata, build metadata, and active writer
+lock evidence through `lock.kind`.
+
+The single-run JSON is the authoritative read model for wrappers that already
+know a run id. Important stable fields include:
+
+- `runId`, `status`, `effectiveStatus`, `publicStatus`, `phase`,
+  `publicPhase`, and `nextAction` for classification and follow-up.
+- `waitingForOperatorGuidance`, `pendingOperatorGuidance`, `blocker`,
+  `manualGate`, `resumeDecision`, `health`, and `lock` for blocked, waiting,
+  paused, timed-out, live-lock, stale-lock, and manually gated states.
+- `commits` with `initialBaseCommit`, `baseCommit`, `finalCommit`,
+  `createdCommitCount`, and accepted-scope final commits.
+- `squash` with the run-local audit artifact path, summary status
+  (`missing`, `pending`, `complete`, or `malformed`), replacement/final-head
+  commits, original base/final commits, and an unavailable reason when the
+  summary cannot provide complete metadata.
+- `patch` with the conservative default-submission decision, reason, patch
+  source, base/head/range, commit count, changed-file count, changed files, and
+  unavailable reason.
+- `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
+  version, source marker (`meta` or `live_fallback`), and the persisted
+  coder/reviewer agent config.
+- `artifacts` with run-local paths for the human narrative, review, progress,
+  support, and related diagnostic artifacts.
+
+`neal status --json --all` is the discovery surface. Each listed run is built
+from the same status snapshot path, so list entries retain the public status,
+phase, next action, commit, squash, provider-error, build, patch, lock, and
+artifact summaries. Scripts that need a final decision for one run should still
+read that run with `--run <run-id>`.
+
+Status reads are best-effort for optional artifacts. Missing or malformed
+`SQUASH_RESULT.json`, unreadable patch ranges, missing run metadata, and old
+runs without build metadata are represented in the JSON summary instead of
+making status fail. The canonical run ledger still must be readable.
+
+Raw `.neal` files are inspectable support artifacts. Internal JSON files are not
+public JSON APIs unless this repository documents that guarantee for a specific
+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.
+
+## 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>/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>/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>/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_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>/REVIEW.md` | User-facing human artifact | Scope or plan review history and findings. |
+| `.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_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. |
+| `.neal/reviews/<review-id>/REVIEW_REQUEST.md` | User-facing human artifact | Original review request, selected range, and loop prompts. |
+| `.neal/reviews/<review-id>/REVIEW_CONTEXT.json` | Support/debug artifact | Resolved local commit range, changed files, diff stat, and diff used for findings. |
+| `.neal/reviews/<review-id>/REVIEW_DRAFT.md` | User-facing human artifact | Human-readable draft findings history for each review loop round. |
+| `.neal/reviews/<review-id>/REVIEW_REVIEW.json` | Support/debug artifact | Versioned review loop summary, including outcome, cap, and round reviews. |
+| `.neal/reviews/<review-id>/REVIEW_ROUNDS.json` | Support/debug artifact | Versioned round-by-round review draft/review prompt and response history. |
+| `.neal/reviews/<review-id>/REVIEW_FINAL.md` | User-facing human artifact | Accepted final reviewed findings artifact, written only after reviewer acceptance. |
+| `.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. |
+
+Writer processes remove their own active lock during normal shutdown and on
+`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
+still running, cleaned up, live, stale, cross-host, or unreadable.
+
+## Patch Automation Policy
+
+Default public prediction submission should use only
+`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
+prefers `squash.originalBaseCommit..squash.replacementCommit` and reports
+`patch.source: "squash_replacement"`. Unsquashed completed execute runs fall
+back to `commits.initialBaseCommit ?? commits.baseCommit` through
+`commits.finalCommit` and report `patch.source: "final_commit"`.
+
+Failed, blocked, paused, running, waiting, provider-error, timed-out,
+manual-gate, malformed-squash, pending-squash, unreadable-range, and empty-patch
+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
+
+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
+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
+
+`.neal/runs/<run-id>/RUN_STATE.json` and
+`.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/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`.
+
+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
+
+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.
+
+Run `meta.json` is diagnostic support data. New writes include `version: 1`, but
+status, resume, and squash selection derive canonical run facts from run-local
+state.
+
+Important replacement artifacts under `.neal/` are written through per-file
+atomic replacement helpers so a reader should see either the old complete file
+or the new complete file. This is still not a multi-file transaction: related
+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
+
+`.neal/` may contain prompts, local paths, command output, diffs, review text,
+provider responses, user guidance diagnostics, reviewer scratch files, copied
+tests, build logs, and project-specific context. Review `.neal/` before sharing
+archives, bug reports, or support bundles.
+
+Public automation bundles should copy `neal status --json` output and
+`RUN_NARRATIVE.md` when a safe per-run trace is needed. Do not publish raw run
+directories, `RUN_NARRATIVE.json`, `events.ndjson`, `stderr.log`, or internal
+state ledgers as benchmark traces.
+
+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 is safe only when you no longer need resume, history, diagnostics,
+or audit data for the item being removed.
+
+Reasonable manual cleanup options:
+
+- remove old `.neal/runs/<run-id>/` directories when resume and run history for
+  those runs are no longer needed
+- remove old `.neal/queues/<queue-id>/` directories when queue resume and queue
+  history are no longer needed
+- 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
+queue. Prefer keeping the full directory until the related work has been merged,
+archived, or otherwise recorded somewhere durable.