@lcv-ideas-software/cross-review 4.0.0

package/docs/reports/cross-review-v2-api-capability-smoke-2026-04-30.md

@@ -0,0 +1,354 @@
+# Cross Review v2 - API Capability Smoke
+
+Date: 2026-04-30, America/Sao_Paulo
+Runtime under test: local `cross-review-v2` source, package version `2.1.1`
+
+## Purpose
+
+This report records a real provider capability smoke test for the API-first
+runtime. It is intended to support release review without exposing API keys,
+raw secrets, full prompts or full provider responses.
+
+The test used the same Windows environment variable strategy as the MCP host
+configuration. The keys were detected in the current process, User environment
+and Machine environment. No key value was printed or written to this report.
+
+## Official Documentation Checked
+
+- OpenAI latest model: `https://platform.openai.com/docs/guides/latest-model`
+  (redirects to `https://developers.openai.com/api/docs/guides/latest-model`)
+- OpenAI reasoning:
+  `https://platform.openai.com/docs/guides/reasoning`
+- Anthropic adaptive thinking: `https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking`
+- Anthropic effort: `https://platform.claude.com/docs/en/build-with-claude/effort`
+- Google Gemini thinking: `https://ai.google.dev/gemini-api/docs/thinking`
+- DeepSeek quick start: `https://api-docs.deepseek.com/`
+- DeepSeek thinking mode: `https://api-docs.deepseek.com/guides/thinking_mode`
+- DeepSeek multi-round conversation: `https://api-docs.deepseek.com/guides/multi_round_chat`
+
+Relevant current documentation observations:
+
+- OpenAI documents GPT-5.5 as the latest model page, recommends updating the
+  model slug to `gpt-5.5`, recommends the Responses API for reasoning,
+  tool-calling and multi-turn use cases, and documents `xhigh` for the hardest
+  asynchronous agentic tasks and security/code review workloads.
+- Anthropic's official Claude API Docs on `platform.claude.com` document
+  `claude-opus-4-7` with adaptive thinking and `output_config.effort`,
+  including `xhigh` for advanced coding and complex agentic work.
+- Gemini documents `thinkingConfig` for Gemini API calls; the real model
+  metadata for `gemini-3.1-pro-preview` reports `thinking: true`.
+- DeepSeek documents `deepseek-v4-pro`, `thinking.type=enabled`,
+  `reasoning_effort=high|max`, JavaScript OpenAI-client examples with
+  top-level `thinking` and `reasoning_effort`, the 2026-07-24 deprecation of
+  `deepseek-chat` and `deepseek-reasoner`, and stateless multi-round chat
+  behavior.
+
+## Model Exclusion Rationale
+
+- `deepseek-chat` and `deepseek-reasoner` are excluded because DeepSeek marks
+  both names for deprecation on 2026-07-24 and maps them to compatibility names
+  for `deepseek-v4-flash`.
+- `claude-haiku-4-5` is excluded because the cross-review role requires the
+  advanced Opus/Sonnet adaptive-thinking line. Anthropic documents adaptive
+  thinking support for Opus 4.7, Opus 4.6 and Sonnet 4.6; Haiku is not in the
+  active advanced priority set for this peer-review role.
+- `gemini-3-pro-preview` is excluded because the user's key exposes the newer
+  `gemini-3.1-pro-preview` model with thinking support. The runtime should use
+  the highest visible advanced thinking model and avoid older intermediate
+  previews when a newer advanced model is available.
+
+## Redacted Model API Excerpts
+
+The following snippets are reduced to non-secret model metadata needed for
+release review. They are not full API-key-bearing responses.
+
+```json
+{
+  "openai": {
+    "models_endpoint_count": 126,
+    "relevant_model_ids": [
+      "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"
+    ],
+    "selected": "gpt-5.5",
+    "reported_model": "gpt-5.5-2026-04-23"
+  },
+  "anthropic": {
+    "models_endpoint_count": 9,
+    "relevant_model_ids": [
+      "claude-opus-4-7",
+      "claude-opus-4-6",
+      "claude-sonnet-4-6",
+      "claude-opus-4-5-20251101",
+      "claude-haiku-4-5-20251001"
+    ],
+    "selected": "claude-opus-4-7",
+    "reported_model": "claude-opus-4-7"
+  },
+  "gemini": {
+    "models_endpoint_count": 55,
+    "selected_model_metadata": {
+      "id": "gemini-3.1-pro-preview",
+      "displayName": "Gemini 3.1 Pro Preview",
+      "inputTokenLimit": 1048576,
+      "outputTokenLimit": 65536,
+      "supportedActions": [
+        "generateContent",
+        "countTokens",
+        "createCachedContent",
+        "batchGenerateContent"
+      ],
+      "thinking": true
+    },
+    "reported_model": "gemini-3.1-pro-preview"
+  },
+  "deepseek": {
+    "models_endpoint_count": 2,
+    "model_ids": ["deepseek-v4-flash", "deepseek-v4-pro"],
+    "selected": "deepseek-v4-pro",
+    "reported_model": "deepseek-v4-pro"
+  }
+}
+```
+
+## Real API Results
+
+All four provider capability checks succeeded.
+
+### OpenAI
+
+- Configured model: `gpt-5.5`
+- API model catalog count visible to the key: `126`
+- Selected model: `gpt-5.5`
+- Reported model from real Responses API call: `gpt-5.5-2026-04-23`
+- Capability tested: Responses API, `reasoning.effort=xhigh`
+- Reasoning tokens observed: `15`
+- Output preview: `OK_OPENAI`
+
+### Anthropic
+
+- Configured model: `claude-opus-4-7`
+- API model catalog count visible to the key: `9`
+- Relevant advanced models observed: `claude-opus-4-7`,
+  `claude-opus-4-6`, `claude-sonnet-4-6`
+- Selected model: `claude-opus-4-7`
+- Capability tested: Messages API, `thinking.type=adaptive`,
+  `thinking.display=omitted`, `output_config.effort=max`
+- Additional capability test: `output_config.effort=xhigh`
+- Reported model from both real calls: `claude-opus-4-7`
+- Stop reason: `end_turn`
+
+### Google Gemini
+
+- Configured model: `gemini-3.1-pro-preview`
+- API model catalog count visible to the key: `55`
+- Selected model: `gemini-3.1-pro-preview`
+- Selected model metadata:
+  - `inputTokenLimit`: `1048576`
+  - `outputTokenLimit`: `65536`
+  - `supportedActions`: `generateContent`, `countTokens`,
+    `createCachedContent`, `batchGenerateContent`
+  - `thinking`: `true`
+- Capability tested: `generateContent` with `thinkingConfig.thinkingLevel=HIGH`
+- Thoughts token count observed: `115`
+- Output preview: `OK_GEMINI`
+
+### DeepSeek
+
+- Configured model: `deepseek-v4-pro`
+- API model catalog count visible to the key: `2`
+- Models visible to the key: `deepseek-v4-flash`, `deepseek-v4-pro`
+- Selected model: `deepseek-v4-pro`
+- Capability tested: OpenAI-compatible chat completions with
+  `thinking.type=enabled` and `reasoning_effort=max`
+- Reasoning tokens observed: `29`
+- Output preview: `OK_DEEPSEEK`
+
+## Local Runtime Evidence
+
+`npm test` passed after the latest change set. The test command includes:
+
+1. `npm run build`
+2. `npm run smoke`
+3. `npm run runtime-smoke`
+
+Runtime smoke reported this server identity:
+
+```json
+{
+  "name": "cross-review-v2",
+  "publisher": "LCV Ideas & Software",
+  "version": "2.1.1",
+  "release_date": "2026-04-30",
+  "transport": "stdio",
+  "api_only": true,
+  "cli_execution": false,
+  "stable_release": true,
+  "max_output_tokens": 20000,
+  "stub": true,
+  "retry_timeout_ms": 1800000
+}
+```
+
+The package dry run reported:
+
+```json
+{
+  "id": "@lcv-ideas-software/cross-review-v2@2.1.1",
+  "name": "@lcv-ideas-software/cross-review-v2",
+  "version": "2.1.1",
+  "filename": "lcv-ideas-software-cross-review-v2-2.1.1.tgz",
+  "entryCount": 91,
+  "bundled": []
+}
+```
+
+The dry-run file list includes `dist/`, `docs/`, `README.md`, `LICENSE`,
+`NOTICE`, `SECURITY.md`, `CHANGELOG.md`, `package.json`, and this report. It
+does not include `data/`, `.env`, logs, session files or API keys.
+
+Full dry-run path list:
+
+```text
+CHANGELOG.md
+LICENSE
+NOTICE
+README.md
+SECURITY.md
+dist/scripts/runtime-smoke.d.ts
+dist/scripts/runtime-smoke.js
+dist/scripts/runtime-smoke.js.map
+dist/scripts/smoke.d.ts
+dist/scripts/smoke.js
+dist/scripts/smoke.js.map
+dist/src/core/config.d.ts
+dist/src/core/config.js
+dist/src/core/config.js.map
+dist/src/core/convergence.d.ts
+dist/src/core/convergence.js
+dist/src/core/convergence.js.map
+dist/src/core/cost.d.ts
+dist/src/core/cost.js
+dist/src/core/cost.js.map
+dist/src/core/orchestrator.d.ts
+dist/src/core/orchestrator.js
+dist/src/core/orchestrator.js.map
+dist/src/core/reports.d.ts
+dist/src/core/reports.js
+dist/src/core/reports.js.map
+dist/src/core/session-store.d.ts
+dist/src/core/session-store.js
+dist/src/core/session-store.js.map
+dist/src/core/status.d.ts
+dist/src/core/status.js
+dist/src/core/status.js.map
+dist/src/core/timeouts.d.ts
+dist/src/core/timeouts.js
+dist/src/core/timeouts.js.map
+dist/src/core/types.d.ts
+dist/src/core/types.js
+dist/src/core/types.js.map
+dist/src/dashboard/server.d.ts
+dist/src/dashboard/server.js
+dist/src/dashboard/server.js.map
+dist/src/mcp/server.d.ts
+dist/src/mcp/server.js
+dist/src/mcp/server.js.map
+dist/src/observability/logger.d.ts
+dist/src/observability/logger.js
+dist/src/observability/logger.js.map
+dist/src/peers/anthropic.d.ts
+dist/src/peers/anthropic.js
+dist/src/peers/anthropic.js.map
+dist/src/peers/base.d.ts
+dist/src/peers/base.js
+dist/src/peers/base.js.map
+dist/src/peers/deepseek.d.ts
+dist/src/peers/deepseek.js
+dist/src/peers/deepseek.js.map
+dist/src/peers/errors.d.ts
+dist/src/peers/errors.js
+dist/src/peers/errors.js.map
+dist/src/peers/gemini.d.ts
+dist/src/peers/gemini.js
+dist/src/peers/gemini.js.map
+dist/src/peers/model-selection.d.ts
+dist/src/peers/model-selection.js
+dist/src/peers/model-selection.js.map
+dist/src/peers/openai.d.ts
+dist/src/peers/openai.js
+dist/src/peers/openai.js.map
+dist/src/peers/registry.d.ts
+dist/src/peers/registry.js
+dist/src/peers/registry.js.map
+dist/src/peers/retry.d.ts
+dist/src/peers/retry.js
+dist/src/peers/retry.js.map
+dist/src/peers/stub.d.ts
+dist/src/peers/stub.js
+dist/src/peers/stub.js.map
+dist/src/peers/text.d.ts
+dist/src/peers/text.js
+dist/src/peers/text.js.map
+dist/src/security/redact.d.ts
+dist/src/security/redact.js
+dist/src/security/redact.js.map
+docs/api-keys.md
+docs/architecture.md
+docs/costs.md
+docs/github-security-baseline.md
+docs/model-selection.md
+docs/reports/cross-review-v2-api-capability-smoke-2026-04-30.md
+docs/reports/cross-review-v2-format-recovery-findings-2026-04-28.md
+package.json
+```
+
+## Regression Coverage Added
+
+- `scripts/smoke.ts` verifies `CROSS_REVIEW_V2_MAX_OUTPUT_TOKENS` accepts
+  positive integers and falls back to `20000` for invalid values.
+- `scripts/smoke.ts` verifies all four adapters use the configured output
+  token value rather than hard-coded limits.
+- `scripts/smoke.ts` verifies Anthropic, Gemini and DeepSeek thinking markers
+  are present in adapter source.
+- `scripts/smoke.ts` verifies active priority lists do not contain
+  `claude-haiku-4-5`, `gemini-3-pro-preview`, `deepseek-chat` or
+  `deepseek-reasoner`.
+- `scripts/smoke.ts` verifies a provider returning only
+  `claude-haiku-4-5-20251001` does not cause a silent weak-model downgrade; the
+  selected model remains `claude-opus-4-7` with `confidence=unknown`.
+- `scripts/smoke.ts` verifies malformed, mismatched, overlapping, repeated,
+  CRLF and long private-key markers do not reintroduce the previous redaction
+  complexity issue.
+- `scripts/smoke.ts` verifies empty peer output triggers the full decision retry
+  and records `decision_retry_succeeded`.
+- `scripts/smoke.ts` verifies moderation recovery, model fallback, budget
+  preflight, cooperative cancellation, runtime events and metrics.
+
+## Pre-Commit Identity
+
+This evidence report is intentionally pre-commit. The candidate is based on
+current `main` HEAD `b7ae98836dfe8c461d72b406e5ab30712705d765` plus the local
+working-tree changes described above. The `release_date` constant is
+intentionally set to `2026-04-30`, the planned ship date for package `2.1.1`.
+The final commit SHA and GitHub release tag will be produced only after
+cross-review approval and the commit/push workflow.
+
+## Release Implications
+
+- The current model defaults are reachable with the user's keys.
+- The runtime should continue to prefer advanced thinking-capable models only.
+- `claude-haiku-4-5`, `gemini-3-pro-preview`, `deepseek-chat` and
+  `deepseek-reasoner` must stay out of active priority lists.
+- If a provider model API returns candidates but none match the advanced
+  priority list, the runtime must keep the documented advanced fallback rather
+  than silently downgrading to a weaker returned candidate.
+- `CROSS_REVIEW_V2_MAX_OUTPUT_TOKENS=20000` remains the configured production
+  output budget; this smoke used a smaller request budget to avoid unnecessary
+  test output while proving the parameters are accepted.

package/docs/reports/cross-review-v2-format-recovery-findings-2026-04-28.md

@@ -0,0 +1,223 @@
+# Cross Review v2 - Format Recovery Findings
+
+Date: 2026-04-28, America/Sao_Paulo
+Runtime: pre-stable API-first runtime 2.0.0-alpha.2
+
+## Context
+
+This report records real operational issues found while using the API-first cross-review runtime
+that later became `cross-review-v2`, while reviewing the published Maestro Editorial AI v0.3.11
+release.
+
+The reviewed release itself was published successfully:
+
+- Repository: `LCV-Ideas-Software/maestro-app`
+- Commit: `ec37513`
+- Release: `v0.3.11`
+- Release URL: `https://github.com/LCV-Ideas-Software/maestro-app/releases/tag/v0.3.11`
+- Release asset: `maestro-editorial-ai-v0.3.11-windows-x64-portable.zip`
+- Asset SHA-256: `f97947b1a7ea74ae8d652d64fbbb0b9146fe5a2d6b60bf176aaa0346d66f6b62`
+- CI, Release, CodeQL, and Code Quality runs: success
+- Open code scanning alerts: 0
+- Open Dependabot alerts: 0
+
+## Sessions
+
+- `b560d4fb-640e-46cf-9ff3-26218cdfdddf`
+- `16d55e54-4b8c-4153-8451-818c3fc37625`
+- `41e5d453-84ed-45a3-9c6d-c70c31a9d9f9`
+
+Relevant persisted files live under:
+
+- `data/sessions/<session-id>/meta.json`
+- `data/sessions/<session-id>/agent-runs/*.json`
+- `data/sessions/b560d4fb-640e-46cf-9ff3-26218cdfdddf/evidence/`
+
+## Findings
+
+### 1. READY content can be classified as NEEDS_EVIDENCE when `summary` exceeds 800 chars
+
+Several peers returned semantically clear `READY` decisions, but the structured
+parser rejected the response because `summary` was longer than 800 characters.
+The round then recorded the peer as `NEEDS_EVIDENCE`.
+
+Observed examples:
+
+- `b560d4fb-640e-46cf-9ff3-26218cdfdddf`
+- `41e5d453-84ed-45a3-9c6d-c70c31a9d9f9`
+
+The parser warning shape was:
+
+```text
+summary: Too big: expected string to have <=800 characters
+```
+
+Impact:
+
+- A peer can agree with the decision but still block convergence.
+- The operator must inspect raw artifacts to distinguish a true disagreement
+  from a formatting failure.
+- This increases false-negative convergence results.
+
+Recommended fix:
+
+- Treat overlong summary as a recoverable format violation, not as substantive
+  `NEEDS_EVIDENCE`.
+- Server-side normalize by truncating `summary` to the schema limit while
+  preserving the full raw text in the artifact.
+- Add a parser warning such as `summary_truncated`, but keep `status=READY`
+  when the status is otherwise parseable and valid.
+
+### 2. Recovery rounds can silently narrow quorum scope
+
+After full-peer rounds produced `codex`, `gemini`, and `deepseek` as `READY`,
+an isolated recovery call was sent only to `claude`. Claude returned `READY`,
+and the runtime marked that round as converged because `expected_peers=["claude"]`.
+
+Observed session:
+
+- `41e5d453-84ed-45a3-9c6d-c70c31a9d9f9`
+
+Impact:
+
+- The tool can report `converged=true` for the recovery round while the session
+  no longer represents a single strict quadrilateral round.
+- The correct human interpretation is "all peers reached READY across the
+  original round plus a format-recovery round", not "the latest full quorum
+  round converged".
+
+Recommended fix:
+
+- Add a first-class "format recovery" mode that retries only failed-format
+  peers but preserves the original quorum scope.
+- Convergence should distinguish:
+  - `latest_round_converged`
+  - `session_quorum_converged`
+  - `recovery_converged`
+- The public response should not collapse a recovery-only quorum into ordinary
+  strict unanimity.
+
+### 3. Minimal prompts can cause peers to review the schema instead of the decision
+
+In session `16d55e54-4b8c-4153-8451-818c3fc37625`, the draft included a JSON
+schema example with placeholders like `READY|NOT_READY`. DeepSeek interpreted
+the template itself as the artifact under review and returned `NOT_READY`
+because it saw no concrete decision.
+
+Impact:
+
+- Attempts to reduce prompt size for parser compliance can create semantic
+  ambiguity.
+- The model may correctly reject the prompt, but for the wrong target.
+
+Recommended fix:
+
+- The runtime should inject a non-ambiguous response contract internally instead of
+  requiring the caller to include a schema template in `draft`.
+- Use a separate transport-level response schema or provider-native structured
+  output where available.
+- If a schema example must be included, wrap it in a clearly labeled
+  `RESPONSE_FORMAT_INSTRUCTIONS` block and keep the reviewed artifact separate.
+
+### 4. The runtime needs automated per-peer format retries
+
+The operator had to manually create shorter prompts and isolated calls to
+recover from parser failures.
+
+Impact:
+
+- Manual recovery is slow and easy to misinterpret.
+- It can distort convergence scope, as described above.
+
+Recommended fix:
+
+- Add an automatic retry path when parsing fails but raw text includes a
+  recognizable status.
+- Retry only the affected peer with a compact reformat instruction and the
+  original evidence.
+- Preserve the original peer set in session convergence computation.
+- Cap retries per peer to avoid runaway cost.
+
+### 5. Raw status extraction should be separated from structured payload validation
+
+The current behavior appears to conflate:
+
+- status detection (`READY`, `NOT_READY`, `NEEDS_EVIDENCE`)
+- structured object validation
+- convergence eligibility
+
+Impact:
+
+- A valid status can be hidden by a non-critical structured validation issue.
+
+Recommended fix:
+
+- Parse status first.
+- Validate structured fields second.
+- Classify format defects by severity:
+  - fatal: no recognizable status, invalid JSON with no recoverable status
+  - recoverable: overlong summary, too many follow-ups, missing optional fields
+  - warning: extra fields, markdown fence around JSON
+- Allow recoverable defects to become `READY_WITH_WARNINGS` internally, while
+  still counting as READY for convergence if the status is unambiguous.
+
+## Suggested Acceptance Tests
+
+1. Peer returns valid JSON with `status=READY` and a 1,500-character summary.
+   Expected: status counts as READY; summary is truncated or moved to raw text;
+   parser warning is recorded.
+
+2. Four-peer round where three peers parse READY and one peer has overlong
+   summary but raw status READY.
+   Expected: session convergence can become true without manual intervention
+   after automatic recovery or normalization.
+
+3. Recovery call for one peer after a four-peer round.
+   Expected: session-level quorum remains the original four peers; the response
+   explicitly reports that the latest call was a format recovery.
+
+4. Draft includes a response schema example and a separate artifact.
+   Expected: peers review the artifact, not the schema placeholder.
+
+5. Peer returns markdown-fenced JSON.
+   Expected: parser extracts JSON and records a warning instead of rejecting.
+
+## Operator Interpretation for Maestro v0.3.11
+
+For the Maestro v0.3.11 review, the substantive result was favorable:
+
+- Codex: READY
+- Gemini: READY
+- DeepSeek: READY
+- Claude: READY after isolated format-recovery prompt
+
+However, because Claude's READY was obtained in an isolated recovery call, the
+The runtime should not present this as a normal single-round quadrilateral convergence.
+It should present it as recovered unanimity with explicit scope and audit trail.
+
+## Implementation Update
+
+Implemented locally after this report:
+
+- Overlong `summary`, `evidence_sources`, `caller_requests` and `follow_ups`
+  fields are now normalized server-side when the peer status is unambiguous.
+- Parser warnings now preserve the recovery reason in the audit trail instead
+  of converting the peer to a false `NEEDS_EVIDENCE`.
+- Markdown-fenced JSON and tagged JSON are extracted with explicit parser
+  warnings.
+- Invalid JSON with an unambiguous `"status": "..."` key is recovered as a
+  status-only structured result.
+- Responses with no parseable status now trigger one automatic per-peer format
+  recovery attempt before the round is judged blocked.
+- Recovery calls that cover only a subset of peers now preserve the prior
+  expected quorum and expose `latest_round_converged`,
+  `session_quorum_converged`, `recovery_converged` and `quorum_peers`.
+- `statusInstruction()` now tells peers not to review the response-format
+  instructions as the artifact under review.
+
+Validated with:
+
+- `npm run typecheck`
+- `npm run smoke`
+- `npm run build`
+- `npm run lint`

package/docs/reports/cross-review-v2-official-provider-docs-refresh-2026-05-05.md

@@ -0,0 +1,60 @@
+# cross-review-v2 Official Provider Docs Refresh — 2026-05-05
+
+Scope: official documentation check for the five cross-review-v2 peers before
+the v2.16.0 protocol repair release.
+
+## Sources Checked
+
+- OpenAI — GPT-5.5 latest-model guide:
+  https://developers.openai.com/api/docs/guides/latest-model
+- OpenAI — model catalog:
+  https://developers.openai.com/api/docs/models
+- OpenAI — Responses API reasoning fields:
+  https://developers.openai.com/api/reference/resources/responses
+- Anthropic — Claude model overview:
+  https://platform.claude.com/docs/en/about-claude/models/overview
+- Anthropic — extended/adaptive thinking:
+  https://platform.claude.com/docs/en/build-with-claude/extended-thinking
+- Google — Gemini models:
+  https://ai.google.dev/gemini-api/docs/models
+- Google — Gemini thinking:
+  https://ai.google.dev/gemini-api/docs/thinking
+- DeepSeek — API changelog:
+  https://api-docs.deepseek.com/updates
+- DeepSeek — reasoning model guide:
+  https://api-docs.deepseek.com/guides/reasoning_model
+- xAI — Grok reasoning:
+  https://docs.x.ai/developers/model-capabilities/text/reasoning
+- xAI — Grok multi-agent:
+  https://docs.x.ai/developers/model-capabilities/text/multi-agent
+- xAI — models and pricing / aliases:
+  https://docs.x.ai/developers/models
+
+## Findings Applied
+
+- OpenAI: `gpt-5.5` remains the correct top Codex/OpenAI priority. Responses
+  API reasoning effort through `xhigh` is still compatible with the adapter.
+- Anthropic: `claude-opus-4-7` remains the strongest Claude default for complex
+  reasoning and agentic coding. The adapter's adaptive-thinking path remains
+  aligned with current docs.
+- Gemini: `gemini-3.1-pro-preview` remains the correct advanced Gemini priority.
+  `gemini-3-pro-preview` is deprecated/shut down and remains excluded.
+- DeepSeek: `deepseek-v4-pro` and `deepseek-v4-flash` are the current V4 API
+  models. Legacy `deepseek-chat` and `deepseek-reasoner` are scheduled for
+  discontinuation on 2026-07-24 and remain excluded from priority fallbacks.
+- Grok: `GROK_API_KEY` is canonical in this project. The xAI model catalog
+  currently recommends `grok-4.3` for general Chat API use, while the reasoning
+  docs identify `grok-4.20-multi-agent` as the only Grok model that accepts
+  explicit `reasoning.effort`. Automatic-reasoning models such as
+  `grok-4-latest`, `grok-4.3`, `grok-4.20`, and `grok-4.20-reasoning` must omit
+  that field. The priority list preserves operator choice through
+  `CROSS_REVIEW_GROK_MODEL` and keeps the explicit multi-agent model first for
+  cross-review runs that require agent-count control.
+
+## Code/Docs Changes
+
+- Updated `src/peers/model-selection.ts` Grok priority list and docs URL.
+- Clarified Grok model/effort behavior in `src/peers/grok.ts`,
+  `src/core/config.ts`, `README.md`, and `docs/model-selection.md`.
+- Added smoke coverage so the official-doc-backed priority list keeps current
+  model IDs and excludes known deprecated/weak IDs.