@navels/neal 0.1.0

package/docs/PROMPT_SPECS.md

@@ -0,0 +1,266 @@
+# Neal Prompt Specs Inventory
+
+## Scope
+
+This document is 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
+  in `src/neal/agents/prompts.ts` (which otherwise re-exports the
+  `src/neal/prompts/` builders).
+- Schema builders, object validators, and retained compatibility parsers live
+  in `src/neal/agents/schemas.ts`.
+- Round sequencing lives in `src/neal/agents/rounds.ts`.
+
+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
+selection, adjudication, or transition behavior. Its consumers are
+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
+
+Prompt specs live under `src/neal/prompts/`.
+
+That boundary is deliberate: the adjudicator owns loop mechanics, not prompt
+ownership. Keeping prompt specs in `src/neal/prompts/` avoids baking them back
+into `src/neal/agents/rounds.ts` and avoids putting prompt semantics inside the
+adjudicator package.
+
+Concrete split:
+
+- prompt-spec library owns role/task prompt identity, required context, schema linkage, and provider-variant metadata
+- adjudicator / round runner owns coder-reviewer sequencing, retries, convergence, and transition hooks
+- transitions own finalization, adoption, blocked-recovery routing, and commit semantics
+
+## Inventory
+
+### 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-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. |
+
+### 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
+
+Each prompt spec in `src/neal/prompts/specs.ts` makes these fields explicit:
+
+- `id`
+- `role`
+- `purpose`
+- `requiredContext`
+- `schemaTarget`
+- `baseInstructions`
+- `providerVariants`
+- `evaluationNotes`
+- `firstMigrationPriority`
+- `currentHome`
+- `ownershipNotes`
+- `variants`
+
+Three implementation details are intentionally concrete:
+
+1. `baseInstructions` names the current prompt-builder function and its explicit input shape.
+2. `requiredContext` lists the exact context keys the prompt assumes, including artifact and repository inputs that are not always passed as one raw function argument today.
+3. `schemaTarget` names the concrete schema builder plus validator/parser surface.
+
+That keeps prompt specs reviewable as contracts rather than as scattered string literals.
+
+## 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.
+
+That wiring is intentionally split across a few modules:
+
+- `src/neal/prompts/specs.ts` owns prompt-spec identity, required-context contracts, schema linkage metadata, and provider-variant policy.
+- `src/neal/prompts/review-doctrine.ts` owns shared reviewer posture for execute-scope review, plan review, and final completion review.
+- `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/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
+
+`requiredContext` should be read as a contract for context assembly, not just documentation for a prompt author.
+
+When adding or changing a prompt spec:
+
+1. Every required field in `requiredContext` should have one clear source such as a prompt argument, persisted run artifact, review history packet, repository-state query, orchestrator-state field, or operator input.
+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.
+
+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.
+
+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?"
+
+### 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`.
+
+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
+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-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`).
+
+Use a provider-specific override only when at least one of these is true:
+
+- deterministic fixture coverage shows shared wording is ambiguous or misleading for one provider
+- the provider API exposes a materially different structured-output surface that the prompt must acknowledge
+- the same shared wording repeatedly causes provider-specific failure modes that cannot be handled in adapter code alone
+
+Do not add provider-specific variants merely because:
+
+- one provider is stylistically different
+- a wording preference is subjective
+- a single anecdotal run felt better with custom phrasing
+
+Before introducing divergence, prefer this order:
+
+1. tighten the shared prompt wording
+2. tighten schema or parser validation
+3. localize provider-surface differences in the provider adapters
+4. add a prompt-spec provider variant only if the role/task instructions genuinely need to differ
+
+When a provider-specific variant is added, record why the shared wording was insufficient and which fixture or failure evidence justified the fork.
+
+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.
+
+## 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:
+
+- prompt specs define the coder/reviewer role/task contracts that adjudication specs reference
+- adjudication specs define which coder prompt, reviewer prompt, schemas, artifact/context packet, and convergence rule belong to a loop
+- the adjudicator helpers own loop mechanics such as round invocation and settled-vs-revise synthesis
+- execute and plan transitions own operational meaning such as adoption, blocked recovery, replacement, and finalization
+
+That means prompt specs stay separate from:
+
+- phase transitions
+- success/block routing
+- commit/finalization semantics
+- operator-adoption policy
+
+Three current role/task boundaries matter especially:
+
+- `scope_reviewer` keeps meaningful-progress as a capability variant, not a separate top-level prompt id
+- `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
+
+Add prompt specs in a disciplined order:
+
+1. Confirm the feature is a recurring role/task surface rather than a one-off continuation inside an existing role. If it is only a bounded continuation, prefer a variant on an existing spec.
+2. Add or update the prompt spec in `src/neal/prompts/specs.ts` with explicit `requiredContext`, `schemaTarget`, `baseInstructions`, and ownership notes.
+3. Implement or update the concrete prompt builder in the relevant `src/neal/prompts/*.ts` module.
+4. Keep schema linkage explicit by adding or updating the corresponding schema builder and validator/parser surface in `src/neal/agents/schemas.ts` when structured control output is required.
+5. Add or update deterministic fixtures and prompt-render assertions under `test/fixtures/prompts/` and the prompt-spec regression tests.
+6. Only after the prompt contract is stable should adjudicator work decide whether the new surface deserves its own adjudication spec or reuses an existing loop family.
+
+Use a new top-level `PromptSpecId` only when the role/task is genuinely distinct in at least one of these ways:
+
+- 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
+
+Otherwise prefer a variant such as `response`, `derived_plan`, `meaningful_progress`, or `final_completion`.
+
+## Testing
+
+Deterministic prompt regression coverage has three fixture layers:
+
+- prompt-render assertions for required sections and invariants
+- inventory assertions that every curated role/task still points at explicit builders and schema targets
+- fixture inputs for known ambiguity cases such as execution-shape declaration and meaningful-progress review
+
+Current coverage:
+
+- planning prompts have dedicated JSON fixtures under `test/fixtures/prompts/planning/`
+- execute and completion prompts have deterministic fixture coverage under `test/fixtures/prompts/execute/` and `test/fixtures/prompts/specialized/`
+- 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).
+
+## 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.
+
+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
+
+The blocked-adjudicator prompt and the `neal review` findings prompts take no guidance injection.
+
+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.
+
+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.
+
+Non-goals: no repo-local `.neal/guidance/` override, no full-prompt replacement, no per-scope guidance variants, and no substitution of built-in sections.
+
+The module lives in [src/neal/prompts/guidance.ts](../src/neal/prompts/guidance.ts). Tests in [test/user-guidance.test.ts](../test/user-guidance.test.ts) cover default-directory loading, the `NEAL_GUIDANCE_DIR` override, empty-file no-op, injection into coder/reviewer/planner and blocked-recovery prompts, additive injection (structured actions and the plan contract survive), and guidance diagnostics.

package/docs/README.md

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

package/docs/architecture.md

@@ -0,0 +1,113 @@
+# Architecture
+
+A one-page map of how neal is built. The deep contracts live in the linked docs;
+this page is the synthesis — how the run loop, the persisted state, the provider
+registry, and the prompt layer fit together.
+
+```
+            plan.md
+              │
+        ┌─────▼─────────────────────────────────────────────┐
+        │  Orchestrator  (src/neal/orchestrator.ts + phases/) │
+        │                                                     │
+        │   plan refinement ─▶ per-scope coder/reviewer loop  │
+        │        │                     │                      │
+        │        │                     ├─ split-plan (subdivide)
+        │        │                     └─ blocked recovery (adjudicated)
+        │        ▼                     ▼                      │
+        │   final-completion review ─▶ squash                 │
+        └───────┬─────────────────────────┬───────────────────┘
+                │                          │
+   roles ◀──────┤                          ├──────▶ persisted state
+   Provider     │                          │        .neal/ ledgers
+   registry     ▼                          ▼        (run + queue)
+   (planner / coder / reviewer)     prompt specs + structured rounds
+```
+
+## 1. The run loop (orchestrator)
+
+`src/neal/orchestrator.ts` drives a deterministic state machine over a plan
+document. The phases live in `src/neal/orchestrator/phases/`:
+
+- **planning** — refines the authored plan into an executable shape
+  (`plan-refinement.ts`, `plan-validation.ts`; see
+  [plan-format.md](plan-format.md)) through its own planner/reviewer loop.
+- **coder** — runs one scope with the coder role from a fresh context, then
+  commits.
+- **review** — hands the committed diff to the read-only reviewer role; findings
+  route back to the coder until accepted.
+- **recovery** — interactive/unattended blocked recovery is the single chokepoint
+  every block class funnels through, fronted by a bounded, read-only **blocked
+  adjudicator** (`adjudicator/blocked-adjudicator.ts`) that triages coder-blocked
+  signals, reviewer `review_stuck` deadlocks, and the split-plan invalid-payload
+  block. Under unattended runs it autonomously resolves a narrow recoverable class
+  (and escalates genuine walls); under attended runs it surfaces its verdict as
+  advice and yields.
+
+After every scope is accepted, a **final-completion review**
+(`final-completion-review.ts`) checks the whole plan, then neal squashes the run
+into a clean commit range.
+
+## 2. State and persistence
+
+Every run is **crash-safe and resumable** because all state is persisted under
+the project-local `.neal/` directory ([storage.md](storage.md)) via atomic writes
+(`atomic-write.ts`). Two ledgers:
+
+- **Run state** (`RUN_STATE.json`) — the phase/status state machine for a single
+  run, with documented invariants ([state-machine.md](state-machine.md)).
+- **Plan queue** (`plan-queue.ts`) — the ordered set of scopes and their
+  completion.
+
+`neal resume` (`resume-decision.ts`, `resume-planner.ts`) reconstructs an
+interrupted run from these ledgers — which is why a killed process never loses
+committed work. A per-run lock (`run-lock.ts`) prevents concurrent runs from
+colliding.
+
+## 3. Providers and roles
+
+The three roles — planner, coder, reviewer — are bound to providers
+independently, so you can run different vendors/models per role. The provider
+**registry** (`src/neal/providers/registry.ts`) is where capabilities are
+declared and **enforced**:
+
+- **Native adapters:** `openai-codex` and `anthropic-claude` wrap the vendors'
+  agentic SDKs (which own their tool loop and sandbox).
+- **`generic-agentic`:** a neal-owned agentic loop over any OpenAI-compatible /
+  OpenRouter model, with a jailed tool surface
+  (`providers/generic-agentic-tools.ts`).
+
+The key invariant: **the reviewer role is read-only by construction.** Every
+provider definition is checked at registration
+(`assertStructuredAdvisorReadOnly`) to declare `write:false, shell:false` for its
+structured-advisor (reviewer) capability — so a reviewer structurally cannot
+mutate the repo, regardless of prompt. See [providers.md](providers.md) and
+[SECURITY.md](../SECURITY.md) for the full trust model.
+
+## 4. Prompts and adjudication
+
+Each role's behavior is defined by versioned **prompt specs**
+(`src/neal/agents/`, [PROMPT_SPECS.md](PROMPT_SPECS.md)) and run through shared
+**structured rounds** (`agents/rounds.ts`) that force schema-validated output
+(`agents/schemas.ts`). The coder/reviewer adjudication loop is inventoried in
+[ADJUDICATOR_INVENTORY.md](ADJUDICATOR_INVENTORY.md). Structured output is
+schema-enforced (not loose JSON), which is also how `neal compat` attributes a
+model's failures to the model rather than to transport noise.
+
+## 5. Model qualification (`neal compat`)
+
+`neal compat` (`src/neal/commands/compat.ts`) is a self-contained harness that
+drives a candidate model through the planner/coder/reviewer roles on trivial
+bundled fixtures, classifies failures structurally (protocol vs structured-output
+vs behavior), and emits a PASS/FAIL matrix. It's how the dated
+[compatible-models.md](compatible-models.md) whitelist is produced, and it
+doubles as the live CI smoke for dependency bumps (see
+[maintenance.md](maintenance.md) and [compat.md](compat.md)).
+
+## Where to go next
+
+- [plan-format.md](plan-format.md) — the executable plan contract
+- [state-machine.md](state-machine.md) — run/queue state invariants
+- [providers.md](providers.md) — provider adapter contract + extension checklist
+- [PROMPT_SPECS.md](PROMPT_SPECS.md) — prompt-spec ownership boundaries
+- [storage.md](storage.md) — the `.neal/` storage contract

package/docs/automation.md

@@ -0,0 +1,65 @@
+# Automation Contract
+
+This document is the machine-facing contract for driving neal from scripts,
+CI, and benchmark harnesses.
+
+Noninteractive harnesses should run `neal execute <plan.md>` for an already
+accepted executable plan, or `neal run <plan.md>` when Neal should refine and
+execute one or more plans as a serial queue. Use `neal resume --run <run-id>` to
+continue an interrupted writer run; pass `--message` only when status says the
+run is waiting for operator guidance. After each writer command, classify the
+result from the process exit code plus `neal status --json --run <run-id>` when
+a run id is known. Use `neal status --json --all` only for run discovery and
+queue overview, not as a replacement for exact run-local status.
+
+`neal execute`, `neal run`, and `neal resume` do not prompt for input. They run
+with closed stdin and either complete, stop in a controlled state, or fail fast
+when setup, configuration, CLI usage, Git state, or worktree preconditions are
+invalid. Keyboard controls are available only when stdin is a TTY. `neal setup`
+and public `neal squash` remain interactive setup and maintenance commands, not
+the harness execution path.
+
+The stable JSON classification fields are:
+
+- `runId`, `status`, `effectiveStatus`, `publicStatus`, `phase`,
+  `publicPhase`, and `nextAction` for outcome and follow-up decisions.
+- `waitingForOperatorGuidance`, `pendingOperatorGuidance`, `blocker`,
+  `manualGate`, `health`, and `lock.kind` for controlled incomplete states,
+  timeouts, and stale or live writer-lock evidence.
+- `providerError` for the latest provider or phase failure. Provider failures
+  expose provider id, role, label, session handle, normalized kind, bounded
+  message, retryability, and timestamp without raw provider payloads.
+- `commits`, `squash`, and `patch` for patch selection. `patch` includes the
+  default-submission decision, reason, base/head/range, source, commit count,
+  changed-file count, changed files, and unavailable reason.
+- `build` for reproducibility: Neal package version, Neal source Git SHA when
+  available, Node version, whether the values came from run `meta.json` or live
+  fallback, and the persisted planner/coder/reviewer agent config.
+
+Default public patch submission is conservative. Submit automatically only when
+`patch.defaultSubmissionEligible` is true. Neal sets that only for clean
+completed execute runs with a non-empty readable patch range. Successful squash
+metadata is preferred (`squash.originalBaseCommit..squash.replacementCommit`);
+otherwise completed unsquashed execute runs use
+`commits.initialBaseCommit ?? commits.baseCommit` through `commits.finalCommit`.
+Failed, blocked, paused, running, provider-error, waiting, timed-out,
+malformed-squash, pending-squash, unreadable-range, and empty-patch runs can
+still expose patch metadata for analysis, but are not default-submission
+eligible.
+
+For public traces, copy `neal status --json --run <run-id>` output and the
+run-local `RUN_NARRATIVE.md` path reported at
+`artifacts.runNarrativeMarkdownPath`. Do not publish raw run directories,
+`RUN_NARRATIVE.json`, `events.ndjson`, `stderr.log`, `RUN_STATE.json`, full
+diffs, prompts, provider responses, or provider payloads as benchmark traces.
+
+Writer command exit codes (`0`, `1`, `2`, `3`) are defined in the README's
+[Command Exit Codes](../README.md#command-exit-codes) section.
+
+Harnesses own wall-clock timeouts. Launch Neal in a process group, terminate
+that group on timeout, wait a short grace period, and force-kill the group if it
+does not exit. When a run id is known, call `neal status --json --run <run-id>`
+after termination and record the wrapper timeout as the primary classification.
+Status JSON stays readable for interrupted runs and includes `lock.kind`, so a
+wrapper can distinguish a cleaned-up timeout (`none`) from a still-active or
+stale writer lock.

package/docs/comparison.md

@@ -0,0 +1,105 @@
+# Why neal instead of X?
+
+neal is a harness, not an agent. It runs three independent roles — planner,
+coder, reviewer — each bound to whatever provider and model you choose
+([providers.md](providers.md)), and drives them with a deterministic state
+machine ([architecture.md](architecture.md)) rather than letting a model decide
+the control flow. Verdicts are schema-validated structured output, not prose an
+orchestrator model interprets. Every run is persisted under `.neal/` and
+resumable after a crash ([storage.md](storage.md)). The reviewer is read-only by
+construction: the provider registry rejects any reviewer capability that
+declares write or shell access, so a reviewer structurally cannot mutate the
+repo regardless of prompt. Most alternatives are agents; neal is the loop that
+holds agents accountable to a plan.
+
+## Claude Code
+
+What it's great at: interactive, conversational coding with a single very
+capable agent. Its subagents delegate work, plan mode gates execution behind an
+approved plan, and hooks let you inject your own checks into the tool loop.
+
+The structural difference: Claude Code is a single-vendor agent product.
+Its subagents are prompt-scoped delegates inside one product, sharing a vendor
+and orchestrated by a model — the top-level agent decides when to delegate and
+how to weigh what comes back. There is no cross-vendor adversarial review: the
+judge and the judged are the same vendor, often the same model family. neal is
+not a competitor to Claude Code; it is a consumer of it. The `anthropic-claude`
+adapter drives Claude Code's SDK as a coder or reviewer, and the common
+configuration is exactly the adversarial split Claude Code cannot express:
+Codex codes, Claude reviews, and a deterministic orchestrator — not a model —
+decides what happens with the verdict.
+
+Pick Claude Code when the work is exploratory or conversational, when you want
+a human in the loop turn by turn, or when you have no plan yet. neal wants a
+plan document; Claude Code is a good place to figure one out.
+
+## Aider (architect/editor mode)
+
+What it's great at: fast, terminal-native pair programming. Its
+architect/editor mode was an early demonstration that splitting reasoning from
+editing across two models improves results.
+
+The structural difference: Aider's two models cooperate on one change — the
+architect proposes, the editor applies — and the control flow between them is
+mediated by the models within a chat session. There is no independent reviewer
+producing a structured verdict that a state machine acts on, no scoped plan
+queue where each scope starts the coder from a fresh context, and continuity is
+conversation-shaped rather than a persisted run ledger. neal's roles are
+adversarial rather than cooperative: the reviewer judges committed diffs it had
+no hand in producing, findings route back to the coder until a schema-validated
+accept, and `neal resume` reconstructs an interrupted run from the `.neal/`
+ledgers rather than replaying a chat.
+
+Pick Aider for tight interactive edits where you are the reviewer and the loop
+is you. neal earns its overhead on multi-scope work where drift over a long
+session is the failure mode.
+
+## OpenHands and autonomous agents
+
+What they're great at: sandboxed, hands-off execution — hand an issue to an
+agent in an isolated runtime and come back to a pull request. The sandbox makes
+broad autonomy defensible.
+
+The structural difference: these systems bet on maximizing agent autonomy and
+containing it with a sandbox. neal bets the opposite way: local-first execution
+in your checkout, a human-authored plan as the contract for what may happen,
+and bounded autonomy with structural escalation — blocked states that wait for
+`neal resume --message`, manual gates for work only a human can do, and a
+bounded adjudicator that resolves a narrow recoverable class and escalates
+genuine walls. Even `--unattended` mode only bounds how long neal persists
+before failing cleanly; it never widens authorization.
+
+Pick an autonomous agent when you want isolation and don't need to constrain
+the path taken. Pick neal when the plan is the point — when you want to
+specify the decomposition, the verification per scope, and the stop conditions,
+and have the machine enforce them.
+
+## If you just want CI review
+
+PR-review bots comment on diffs after they reach the forge. neal's review is
+inside the loop: every scope's committed diff is judged before the run moves
+on, and a final-completion review checks the whole plan before the squash — so
+findings are fixed by the same coder in the same run, not triaged later.
+`neal review` also works standalone against any committed range, role-symmetric
+(the coder provider drafts findings, the read-only reviewer adjudicates them),
+local, and provider-agnostic — no forge integration or CI required. The two are
+complementary: neal reviews before you push, bots review after.
+
+## What neal does not do
+
+- **No GUI.** neal is a CLI with narrative terminal output; state lives in
+  files under `.neal/`.
+- **No sandbox of its own for the coder.** Writer providers run with broad
+  local permissions (Codex under `danger-full-access`, Claude under
+  `bypassPermissions`, the generic writer's `run` tool is unsandboxed shell).
+  Bring your own isolation — disposable checkout, container, or VM. See
+  [SECURITY.md](../SECURITY.md).
+- **Serial scopes only, today.** Scopes execute one at a time, and `neal run`
+  queues run plans serially. There is no parallel scope execution.
+- **It requires a plan document.** There is no "just fix it" mode — the
+  authored plan, with its mandatory `## Execution Shape` section
+  ([plan-format.md](plan-format.md)), is the product's opinion. If writing a
+  plan feels like overhead, neal is the wrong tool for that task.
+- **No provider plugins yet.** Adapters are built-in (`openai-codex`,
+  `anthropic-claude`, `openai-compatible`, `generic-agentic`); external
+  provider plugins are future work.