@lcv-ideas-software/cross-review 4.0.0

package/docs/architecture.md

@@ -0,0 +1,118 @@
+# Architecture
+
+This API-only `cross-review` implementation is intentionally independent from the CLI-based `cross-review-v1` project.
+
+## Runtime Layers
+
+1. MCP server: exposes workflow tools over stdio.
+2. Orchestrator: creates sessions, runs reviews, checks unanimity and asks the lead peer to revise.
+3. Peer adapters: call official provider APIs and client libraries.
+4. Model selection: queries model APIs and chooses the highest-capability documented model available to the key.
+5. Session store: writes durable JSON and Markdown artifacts under `data/sessions`.
+6. Session events: writes durable `events.ndjson` streams per session for long-running work.
+7. Token streaming: writes count-based `peer.token.delta` and `peer.token.completed` events when provider streaming is enabled.
+8. Reports: writes `session-report.md` with convergence, failures, decision quality, costs and recent events.
+9. Observability: writes one NDJSON log per process under `data/logs`.
+10. Dashboard: local read-only HTTP UI for sessions, events, reports, probes and metrics.
+
+## Real Execution Rule
+
+Runtime default is real API execution. Stubs are disabled unless `CROSS_REVIEW_STUB=1`.
+
+## Timeout Model
+
+Real API review rounds are intentionally long-running. The provider-side HTTP
+timeout is controlled by `CROSS_REVIEW_TIMEOUT_MS` and defaults to 30
+minutes.
+
+MCP hosts also have their own client-to-server request timeout. For real peer
+calls, configure the host timeout to at least 300 seconds. A lower generic
+default, such as 60 seconds, can close the MCP request while the provider calls
+are still legitimately processing.
+
+For host environments that cannot keep a long MCP request open, use
+`session_start_round` or `session_start_unanimous`. Those tools create a
+background in-process job and return immediately. Use `session_poll`,
+`session_events`, `session_metrics` and `session_report` to follow progress
+without blocking the client request. `session_cancel_job` requests cooperative
+cancellation and forwards `AbortSignal` to provider client calls where supported.
+
+## Streaming Model
+
+`CROSS_REVIEW_STREAM_EVENTS` controls normal workflow events and defaults to
+enabled. `CROSS_REVIEW_STREAM_TOKENS` controls provider token-progress events
+and also defaults to enabled. `runtime_capabilities.token_streaming` reflects
+the effective token-streaming setting, not a compile-time constant.
+
+When token streaming is active, adapters use provider-native streaming APIs:
+
+- OpenAI: Responses API streaming events, including `response.output_text.delta`.
+- Anthropic: Messages stream helper with text deltas and `finalMessage()`.
+- Gemini: `models.generateContentStream`.
+- DeepSeek: OpenAI-compatible chat completions with `stream: true`.
+
+The streaming path is not a separate fake progress channel. The same streamed
+text is accumulated and then parsed into the existing review or generation
+result.
+
+For safety, `peer.token.delta` events include character counts by default rather
+than provider text. `CROSS_REVIEW_STREAM_TEXT=1` can include redacted text in
+trusted local diagnostics, but it is intentionally opt-in because providers may
+split sensitive strings across chunks. Raw thinking content is still not
+requested or persisted.
+
+## Unanimity Rule
+
+A session converges only when the caller status is `READY`, every selected peer returns `READY`, and no peer failed or omitted a machine-readable status.
+
+Decision quality is tracked per peer:
+
+- `clean`: parsed status without warnings.
+- `format_warning`: parsed with non-blocking parser warnings.
+- `recovered`: recovered through format repair, moderation-safe retry or bounded sanitization.
+- `needs_operator_review`: no parseable status remains after recovery.
+- `failed`: provider or model-selection failure blocked the peer.
+
+`unparseable_after_recovery`, `prompt_flagged_by_moderation`,
+`silent_model_downgrade` and other rejected peer failures always block
+unanimity until resolved.
+
+## Moderation-Safe Prompting
+
+Prior peer history is summarized from structured fields instead of replaying
+raw model text. This keeps prompts smaller, reduces the chance that a verbose
+peer repeats policy-sensitive language into a later provider, and produces more
+useful audit trails.
+
+If a provider still rejects a prompt as moderated or safety-blocked, the
+orchestrator records the failure class and retries once with a compact,
+sanitized review prompt. This retry does not bypass provider policy: if the
+compact context is insufficient, the peer must return `NEEDS_EVIDENCE` or the
+session remains blocked for operator action.
+
+## Model Discovery
+
+Provider model APIs are queried at probe/session initialization:
+
+- OpenAI: Models API.
+- Anthropic: Models API.
+- Gemini: `models.list`.
+- DeepSeek: OpenAI-compatible `/models`.
+
+The selected model and selection evidence are persisted in the session capability snapshot.
+
+## Provider Thinking Baseline
+
+The peer adapters use the strongest official reasoning controls available for each provider because cross-review is correctness-oriented:
+
+- OpenAI runs through the Responses API with high reasoning effort.
+- Anthropic uses adaptive thinking and omits raw thinking content from responses.
+- Gemini enables thinking configuration for Gemini 3.x and the Gemini 2.5 fallback.
+- DeepSeek enables Thinking Mode and follows the official multi-round guidance by resending the summarized session context in each stateless request.
+
+Raw chain-of-thought is not persisted. Session continuity is represented through prompts, structured peer decisions, summaries and artifacts.
+
+## Stable Rename
+
+Stable version `2.1.0` renamed the active product to `cross-review`. The earlier development
+name remains only in historical changelog or memory notes.

package/docs/caching.md

@@ -0,0 +1,135 @@
+# Prompt Caching (v2.21.0+)
+
+`cross-review` integrates with the prompt-caching surface of every supported provider. The runtime emits a uniform `provider.cache.usage` event and persists a per-session `cache_manifest.json` so dashboards, FinOps reports and post-mortem tooling can read cache telemetry without branching on provider-specific shapes.
+
+This document describes:
+
+- per-provider behavior matrix
+- the `stablePrefix` cache key + schema-version invariant
+- pair-scoped cache keys
+- cost savings accounting
+- operator controls (kill-switch + TTL overrides)
+- empirical guidance per provider
+
+## Per-provider behavior matrix
+
+| Peer (Provider)       | Cache mode | Threshold       | TTL surface                                    | Telemetry source                                                      |
+| --------------------- | ---------- | --------------- | ---------------------------------------------- | --------------------------------------------------------------------- |
+| `codex` (OpenAI)      | `auto`     | ~1k tokens      | `prompt_cache_retention` (`in_memory` / `24h`) | `usage.prompt_tokens_details.cached_tokens`                           |
+| `claude` (Anthropic)  | `explicit` | ~4k tokens      | `cache_control.ttl` (`5m` / `1h`)              | `usage.cache_creation_input_tokens` + `usage.cache_read_input_tokens` |
+| `gemini` (Google)     | `implicit` | service-managed | n/a                                            | `usageMetadata.cachedContentTokenCount`                               |
+| `deepseek` (DeepSeek) | `auto`     | service-managed | n/a                                            | `usage.prompt_cache_hit_tokens` + `usage.prompt_cache_miss_tokens`    |
+| `grok` (xAI)          | `auto`     | service-managed | mirrors OpenAI                                 | `usage.prompt_tokens_details.cached_tokens`                           |
+
+`mode` values follow the canonical `TokenUsage.cache_provider_mode` enum:
+
+- `auto` — provider auto-detects cacheable prefix (OpenAI, DeepSeek, Grok)
+- `explicit` — runtime places cache_control breakpoints in the body (Anthropic only)
+- `implicit` — provider transparently caches and reports tokens read (Gemini)
+- `not_supported` — peer call did not produce cache telemetry
+
+## Cache key scope strategy
+
+Every cached call is bucketed by a **pair-scoped cache key**:
+
+```
+cross-review:<peer>:<caller>:v<cache_schema_version>
+```
+
+The pair scope means two different callers reviewing the same case still share cache hits within a peer; cache invalidation is bounded by the schema version. Bumping `CROSS_REVIEW_CACHE_SCHEMA_VERSION` (e.g. `v1` → `v2`) invalidates every previously cached entry, by design. Use this when prompt structure changes materially (new convergence rule, new system role line, new evidence index format).
+
+Internally, we also emit a `stablePrefixHash` (sha256 hex) computed over the LF-normalized stablePrefix. The hash is invariant across rounds for the same case — see `prompt-parts.ts` and the smoke marker `cache_hash_invariance_test`.
+
+## Cache schema versioning
+
+`stablePrefix` always begins with the line `cache_schema_version: vN`. This appears verbatim inside the cached prefix payload so any structural shift produces a different hash and a different cache scope automatically.
+
+When to bump:
+
+- Adding/removing a section in stablePrefix (system, task, review_focus, convergence_rules, evidence_index)
+- Reordering sections inside stablePrefix
+- Changing the systemRole text materially
+- Changing the convergence rules text
+
+Smoke marker `cache_schema_version_in_prefix_test` pins the first-line shape so a regression is caught locally.
+
+## Cost savings accounting
+
+The cost layer (`src/core/cost.ts`) extends `CostEstimate` with two cache-related fields:
+
+- `cache_savings_usd?: number` — populated when the rate card knows how to price the savings
+- `cache_savings_unknown?: boolean` — set when cache telemetry was present but no rate card matched
+
+Rate cards live in `src/core/cache-rates.json`. The primary input/output rates still flow through `config.cost_rates` (env vars `CROSS_REVIEW_<PROVIDER>_INPUT_USD_PER_MILLION` / `CROSS_REVIEW_<PROVIDER>_OUTPUT_USD_PER_MILLION`). The rate card delta is FALLBACK math: `(fresh_input_per_million - cached_input_per_million) × cache_read_tokens / 1e6`.
+
+Adapters surface the read/write counts via `TokenUsage.cache_read_tokens` and `TokenUsage.cache_write_tokens`. The orchestrator reads them, emits a `provider.cache.usage` event, and appends a row to `<data_dir>/sessions/<session_id>/cache_manifest.json`.
+
+## Bypass / kill-switch
+
+```
+CROSS_REVIEW_DISABLE_CACHE=true
+```
+
+Disables prompt caching globally for the runtime. Adapters fall back to the pre-v2.21 behavior (no `prompt_cache_key`, no `cache_control` blocks, no `x-grok-conv-id` header). The cost layer continues to merge `cache_read_tokens` / `cache_write_tokens` if a provider returns them anyway, so audit reproducibility is preserved.
+
+Use cases:
+
+- Provider misbehavior (cache poisoning, stale state)
+- Audit reproducibility (force every call to make a fresh inference)
+- A/B comparison between cached and uncached spend
+
+## TTL configuration
+
+```
+CROSS_REVIEW_CACHE_TTL_ANTHROPIC=5m|1h          # default 1h
+CROSS_REVIEW_CACHE_TTL_OPENAI=5m|1h             # default 1h
+```
+
+- **Anthropic** accepts `5m` and `1h` per the SDK. Values other than `5m`/`1h` are ignored with a stderr notice and the default is used.
+- **OpenAI** accepts only `in_memory` and `24h` per the Responses API (the SDK type is locked to those two strings). The runtime translates `1h` → `24h` (extended retention) and anything else → `in_memory` (the default ~5 min window).
+
+Grok mirrors OpenAI's mapping.
+
+## Anthropic cache_control placement
+
+The Anthropic adapter places exactly **one** cache_control breakpoint at the END of the system prompt block:
+
+```ts
+system: [
+  {
+    type: "text",
+    text: systemPromptText,
+    cache_control: { type: "ephemeral", ttl: "1h" },
+  },
+],
+```
+
+Anthropic supports up to 4 breakpoints per request; we reserve 3 for future additions (per-message layering, tool block caching, multi-tier prefixes). The `cache_creation_input_tokens` / `cache_read_input_tokens` fields on `response.usage` map directly to `cache_write_tokens` / `cache_read_tokens` on our canonical `TokenUsage` shape.
+
+## Empirical guidance
+
+| Provider  | Practical minimum cached prefix | Notes                                                                                      |
+| --------- | ------------------------------- | ------------------------------------------------------------------------------------------ |
+| OpenAI    | ≥ 1024 tokens                   | The Responses API auto-detects; `prompt_cache_key` improves hit rate for repeat callers.   |
+| Anthropic | ≥ 4096 tokens                   | Below this size Anthropic may not actually create the cache entry. Adapter emits a notice. |
+| Gemini    | service-managed                 | Implicit only at this writing; explicit `caches.create` is deferred.                       |
+| DeepSeek  | service-managed                 | Auto-cached; both hit and miss tokens are returned.                                        |
+| Grok      | service-managed                 | xAI mirrors OpenAI; `x-grok-conv-id` header binds the cache scope.                         |
+
+## Reference URLs
+
+- OpenAI prompt caching: https://platform.openai.com/docs/guides/prompt-caching
+- Anthropic prompt caching: https://docs.claude.com/en/docs/build-with-claude/prompt-caching
+- Google Gemini caching: https://ai.google.dev/gemini-api/docs/caching
+- DeepSeek context caching: https://api-docs.deepseek.com/guides/kv_cache
+- xAI / Grok caching: https://docs.x.ai/docs/api-reference
+
+## Smoke markers
+
+The smoke harness (`scripts/smoke.ts`) ships five anti-drift markers covering this surface:
+
+- `cache_hash_invariance_test` — round/draft/priorRounds permutations do NOT mutate `stablePrefixHash`
+- `cache_schema_version_in_prefix_test` — first line of `stablePrefix` matches `^cache_schema_version: v\d+$`
+- `cache_rates_json_loaded_test` — every provider has a rate card with a numeric `fresh_input_per_million_usd`
+- `cache_manifest_atomic_write_test` — sequential appends preserve every entry
+- `cache_disable_kill_switch_test` — `CROSS_REVIEW_DISABLE_CACHE=true` flips `config.cache.enabled`

package/docs/costs.md

@@ -0,0 +1,40 @@
+# Costs
+
+Runtime calls are real provider API calls by default.
+
+## Smoke Tests
+
+`npm test` uses `CROSS_REVIEW_STUB=1` and does not call provider APIs.
+
+## Real Runs
+
+`probe_peers`, `session_init`, `ask_peers` and `run_until_unanimous` may call provider APIs when keys are present.
+
+The server records token usage returned by providers. Paid review/generation tools are blocked until explicit budget ceilings and rate cards are configured. This avoids stale hard-coded prices because provider pricing changes frequently.
+
+`CROSS_REVIEW_MAX_OUTPUT_TOKENS` controls the maximum output budget requested from all providers. The default is `20000`; raise or lower it in the MCP host configuration according to the desired quality/cost tradeoff. Invalid, zero or negative values fall back to the default.
+
+## Required Financial Configuration
+
+Set rates through Windows environment variables or the MCP host configuration before running paid calls. Values are USD per million tokens. Use current official provider pricing; this project intentionally does not ship default provider prices.
+
+```powershell
+[Environment]::SetEnvironmentVariable("CROSS_REVIEW_MAX_SESSION_COST_USD", "20", "User")
+[Environment]::SetEnvironmentVariable("CROSS_REVIEW_PREFLIGHT_MAX_ROUND_COST_USD", "20", "User")
+[Environment]::SetEnvironmentVariable("CROSS_REVIEW_UNTIL_STOPPED_MAX_COST_USD", "20", "User")
+[Environment]::SetEnvironmentVariable("CROSS_REVIEW_OPENAI_INPUT_USD_PER_MILLION", "<current OpenAI input rate>", "User")
+[Environment]::SetEnvironmentVariable("CROSS_REVIEW_OPENAI_OUTPUT_USD_PER_MILLION", "<current OpenAI output rate>", "User")
+[Environment]::SetEnvironmentVariable("CROSS_REVIEW_ANTHROPIC_INPUT_USD_PER_MILLION", "<current Anthropic input rate>", "User")
+[Environment]::SetEnvironmentVariable("CROSS_REVIEW_ANTHROPIC_OUTPUT_USD_PER_MILLION", "<current Anthropic output rate>", "User")
+[Environment]::SetEnvironmentVariable("CROSS_REVIEW_GEMINI_INPUT_USD_PER_MILLION", "<current Gemini input rate>", "User")
+[Environment]::SetEnvironmentVariable("CROSS_REVIEW_GEMINI_OUTPUT_USD_PER_MILLION", "<current Gemini output rate>", "User")
+[Environment]::SetEnvironmentVariable("CROSS_REVIEW_DEEPSEEK_INPUT_USD_PER_MILLION", "<current DeepSeek input rate>", "User")
+[Environment]::SetEnvironmentVariable("CROSS_REVIEW_DEEPSEEK_OUTPUT_USD_PER_MILLION", "<current DeepSeek output rate>", "User")
+```
+
+`CROSS_REVIEW_MAX_SESSION_COST_USD` sets the default per-session budget guard. `CROSS_REVIEW_PREFLIGHT_MAX_ROUND_COST_USD` blocks a round before calls begin when the estimated cost exceeds the configured value. `CROSS_REVIEW_UNTIL_STOPPED_MAX_COST_USD` is required for `until_stopped=true`.
+
+When the estimated session cost exceeds the configured limit, the run is
+finalized as `max-rounds` with reason `budget_exceeded`. Missing financial
+configuration finalizes the session as `max-rounds` with reason
+`financial_controls_missing` before any paid provider call is made.

package/docs/evidence-preflight.md

@@ -0,0 +1,88 @@
+# Evidence Preflight (v3.5.0)
+
+`run_until_unanimous` and `session_start_unanimous` run a **pure textual
+evidence preflight** before any paid peer call. It catches the
+`f0db3970`-class failure — a submission that _claims_ completed
+operational work (tests pass, a diff exists, a build was validated) but
+embeds **zero concrete evidence** — and fails it locally with
+`needs_evidence_preflight` instead of burning API budget across multiple
+`NEEDS_EVIDENCE` rounds.
+
+## Scope boundary (important)
+
+cross-review is an **API-only orchestrator**. The preflight:
+
+- **does NOT** execute shell, run `git diff`, or read the repo;
+- **does NOT** package evidence for you;
+- only inspects text the caller already supplied — `task`,
+  `initial_draft`, the structured `evidence` field, and
+  already-attached evidence.
+
+Evidence _packaging_ (`git diff --stat`, hunks, `git status --short`,
+validation-command tails, changed-file lists, target commit) is a
+**caller-side responsibility**. Build it into a local agent helper,
+prompt workflow, or shared utility — never inside the MCP server.
+
+## How it decides
+
+The preflight trips **only** when **both** are true:
+
+1. **Completed-work claim present** — the text matches one of:
+   `\d+ passed/failed`, `git diff`, `git status`, `npm run`,
+   `cargo test|build`, `build passed/succeeded/clean/green`,
+   `tests? pass/passed/green`, `git diff --check`.
+2. **Zero evidence markers** — the text contains none of: fenced code
+   blocks (` ``` `), `@@ -`/`@@ +` diff hunks, 7+ hex-char hashes,
+   `file.ext:NN` line refs, `$ `/`> ` command-prompt lines.
+
+Mere keyword presence does **not** trip it. "I plan to write a patch"
+or "here is the test plan" is a design review with legitimately no diff
+— it passes.
+
+A non-empty `evidence` field **or** any attached evidence makes the
+preflight pass unconditionally — that is the caller's authoritative
+declaration that concrete evidence exists.
+
+## Minimum evidence format
+
+To pass the preflight when your task makes a completed-work claim,
+embed at least one of these inline in `initial_draft` or in the
+`evidence` field:
+
+- a fenced code block with the relevant diff hunk(s) — `@@ -N,M +N,M @@`;
+- `file/path.ext:LINE` references for every changed location;
+- raw command output (the `$ cmd` line plus its output) for every
+  validation you claim — `npm run typecheck`, `cargo test`,
+  `git diff --check`, `rg` scans;
+- content hashes (`sha256`, `md5`) when asserting artifact identity.
+
+This is the same provenance-grade material the R1 evidence-upfront
+contract already expects. The preflight just refuses to spend API when
+it is obviously absent.
+
+## The `evidence` field
+
+Both `run_until_unanimous` and `session_start_unanimous` accept an
+optional `evidence: string`. When non-empty it satisfies the preflight
+unconditionally. Use it to attach the caller-packaged evidence bundle
+without inflating `initial_draft`.
+
+## Opt-out
+
+Set `CROSS_REVIEW_EVIDENCE_PREFLIGHT=off` to disable the preflight
+entirely (default: `on`). Disabling is rarely needed — the trip
+condition is deliberately conservative — but the escape hatch exists
+for callers whose tasks legitimately make completed-work claims in
+prose without inline markers.
+
+## Outcome when it trips
+
+- session finalized: `outcome = "aborted"`, `reason =
+"needs_evidence_preflight"`;
+- event emitted: `session.evidence_preflight_failed` with
+  `completed_work_claim_matched`, `evidence_marker_found`,
+  `structured_evidence_supplied`, `attachments_present`;
+- **zero paid peer calls** were made.
+
+Re-submit with evidence embedded inline, with the `evidence` field
+populated, or with evidence attached via `session_attach_evidence`.

package/docs/github-security-baseline.md

@@ -0,0 +1,32 @@
+# GitHub Security Baseline
+
+This project is prepared to become a public repository.
+
+Required repository settings after the remote is created:
+
+1. Enable Secret Protection / Secret Scanning.
+2. Enable Push Protection.
+3. Enable Code Scanning with CodeQL Default Setup.
+4. Enable Code Quality.
+5. Enable Dependabot alerts.
+6. Enable Dependabot security updates.
+7. Enable Dependabot version updates from `.github/dependabot.yml`.
+8. Enable Dependabot auto-merge workflow only after branch rules are active.
+9. Protect `main` with a repository ruleset.
+10. Require code scanning results with CodeQL security alerts: All / alerts: All.
+11. Require code quality thresholds: Any / Any.
+12. Require CI to pass before merge.
+13. Disable force-push and branch deletion on `main`.
+
+Package publishing is active after the repository is created and the `NPM_TOKEN` secret is
+configured. Pushes to `main` auto-create an organization-standard display tag such as `v02.01.00`
+from `package.json`; the tag then creates a normal GitHub Release and publishes
+`@lcv-ideas-software/cross-review` to npmjs.com and GitHub Packages. The API-first package is
+separate from the CLI package `@lcv-ideas-software/cross-review-v1`.
+
+CodeQL Advanced Setup is intentionally not committed. If Advanced Setup ever becomes necessary,
+it must be proposed with justification and approved before adding a workflow file.
+
+No secrets, runtime sessions, logs, prompts, provider responses, API keys or local AI memories may
+be committed. The `.gitignore` is intentionally strict because this repository is designed for
+public release from its first push.

package/docs/model-selection.md

@@ -0,0 +1,105 @@
+# Model Selection
+
+The server uses automatic model selection unless an explicit environment override is present.
+
+## Rules
+
+1. Query the provider's official model API using the current API key.
+2. Keep only models that can perform text generation for the peer role.
+3. Exclude known non-thinking, low-capacity or deprecated models from cross-review priority lists.
+4. Compare returned model IDs against the documented priority list.
+5. Select the first available model in that priority list.
+6. Persist the selected model, candidate list, source URL, confidence and reason in the session snapshot.
+
+If a provider returns models but none match the advanced thinking priority list, the runtime keeps the documented advanced fallback instead of silently downgrading to a weaker random candidate. That makes availability problems visible in probes and review rounds.
+
+The no-downgrade behavior is covered by `scripts/smoke.ts`: when a provider
+returns only a weak/deprecated candidate such as `claude-haiku-4-5`, selection
+stays on the documented advanced fallback and records `confidence=unknown`.
+
+## Current Priority Lists
+
+OpenAI/Codex:
+
+```text
+gpt-5.5 > gpt-5.4 > gpt-5.2 > gpt-5.1-codex-max > gpt-5.1-codex > gpt-5.1 > gpt-5-pro > gpt-5
+```
+
+Anthropic/Claude:
+
+```text
+claude-opus-4-7 > claude-opus-4-6 > claude-sonnet-4-6
+```
+
+Haiku is intentionally excluded because the cross-review role requires advanced reasoning depth.
+
+Google/Gemini:
+
+```text
+gemini-2.5-pro > gemini-3.1-pro-preview
+```
+
+Operator preference 2026-05-07: `gemini-2.5-pro` is the runtime default because under Google One AI Ultra subscription it carries 1k requests/day vs `gemini-3.1-pro-preview`'s 250 requests/day; `gemini-3.1-pro-preview` remains in the priority list as a fallback. Workspace policy (operator directive 2026-05-07): only `gemini-*-pro` variants ≥ 2.5 are permitted — no `*-flash` variants and no models below 2.5 (those are deprecated). `gemini-3-pro-preview` is intentionally excluded from the active fallback path because preview model deprecation is tracked through official Gemini release notes and this project avoids soon-to-deprecate intermediate previews when a newer advanced model is available.
+
+DeepSeek:
+
+```text
+deepseek-v4-pro > deepseek-v4-flash
+```
+
+`deepseek-chat` and `deepseek-reasoner` are not active fallbacks because DeepSeek has announced their deprecation for 2026-07-24. `deepseek-v4-pro` is the preferred thinking-capable model for this project.
+
+xAI/Grok:
+
+```text
+grok-4.20-multi-agent > grok-4-latest > grok-4.3 > grok-4.20-reasoning > grok-4.20 > grok-4-1-fast > grok-4 > grok-3-fast > grok-3
+```
+
+`GROK_API_KEY` is the canonical auth variable. The operator chooses the model
+with `CROSS_REVIEW_GROK_MODEL`. Per official xAI reasoning docs, only
+`grok-4.20-multi-agent` accepts an explicit `reasoning.effort` request body
+field, where the value selects agent count (`low`/`medium` = 4 agents,
+`high`/`xhigh` = 16 agents). Automatic-reasoning Grok models such as
+`grok-4-latest`, `grok-4.20`, and `grok-4.20-reasoning` must not receive that
+field; the adapter detects the configured model and omits it automatically.
+The xAI model catalog currently recommends `grok-4.3` for general Chat API
+usage; the multi-agent model remains first in this project because it is the
+only documented Grok model with explicit agent-count control.
+
+## Thinking Configuration
+
+Cross-review-v2 is optimized for correctness over latency and cost. Provider adapters explicitly request thinking/reasoning where the official APIs support it:
+
+- OpenAI/Codex: Responses API with reasoning effort `xhigh` by default.
+- Anthropic/Claude: adaptive thinking with omitted thinking display plus `output_config.effort=xhigh` by default on Opus 4.7.
+- Google/Gemini: `thinkingConfig.thinkingLevel=HIGH` for Gemini 3.x and automatic thinking budget for Gemini 2.5 Pro fallback.
+- DeepSeek: `thinking.type=enabled` with `reasoning_effort=max` by default.
+- Grok: `reasoning.effort` is sent only for `grok-4.20-multi-agent`; all other
+  Grok reasoning models use xAI automatic reasoning without the explicit field.
+
+## Official Documentation Refresh — 2026-05-05
+
+Checked against primary provider documentation before the v2.16.0 protocol
+repair:
+
+- OpenAI: GPT-5.5 is the current recommended frontier model for complex
+  reasoning/coding, with Responses API reasoning effort values through `xhigh`
+  and 1M context / 128K output.
+- Anthropic: Claude Opus 4.7 is the generally available complex-reasoning and
+  agentic-coding default; current docs expose 1M context and adaptive thinking.
+- Google Gemini: Gemini 3.1 Pro Preview is the current advanced Gemini 3.1
+  option; Gemini 3 Pro Preview is deprecated/shut down and must stay out of
+  active fallbacks.
+- DeepSeek: DeepSeek-V4 exposes `deepseek-v4-pro` and `deepseek-v4-flash`;
+  legacy `deepseek-chat` and `deepseek-reasoner` are scheduled for
+  discontinuation on 2026-07-24 and must stay out of priority fallbacks.
+- xAI Grok: the model catalog currently recommends `grok-4.3` for general Chat
+  API use, while reasoning docs identify `grok-4.20-multi-agent` as the only
+  explicit `reasoning.effort` model. Other Grok reasoning models reason
+  automatically and must not receive explicit effort.
+
+## Important
+
+The priority list is intentionally code-level configuration, not hidden behavior. Provider model catalogs and deprecation schedules change often, so this file and `src/peers/model-selection.ts` must be reviewed against official provider documentation whenever defaults change.
+
+The redacted real-API capability smoke for the current default models is recorded in `docs/reports/cross-review-api-capability-smoke-2026-04-30.md`.