docs(opencode): add reasoning capability validation procedure - #577

🤖: AI agent (First Mate), AI-assisted change (OpenCode). Human review required before merge.

Summary

Adds integrations/isolation/acq-kits/opencode/docs/reasoning-validation.md: the separate procedure ADR 0006 requires before reasoning may be published, plus the result of running its design experiment live on OpenCode 2.0.30. The finding is "not verifiable here / recommend the field stay absent for all models". No script, no data, no schema or catalog change, no capability value.

Key findings (details and limits are in the doc):

• OpenCode 2.0.30 treats a provider-model reasoning setting as an unsupported legacy setting and omits it (logged as a normalization warning). Request, variants, events and usage were identical for absent, true and false.
• model#low|medium|high variants work and send reasoning_effort regardless of the field.
• The USAi gateway returned no reasoning field and no reasoning_tokens for the four models examined. Hidden thinking shows only as token accounting, which differs per family, and the effort and disable switches tried had no observable effect, so there is no usable control on any model. Every model is therefore indeterminate and the field stays absent: a null observation or a control working only on another model cannot establish false, which needs an explicit target-specific gateway or vendor statement that the model's reasoning capability itself is unsupported (a rejected parameter, effort value or endpoint is not one); true needs target-specific positive evidence.
• Consequence: the ADR's mapping table row (neutral reasoning to OpenCode reasoning) is a no-op on the pinned version. ADR 0006 is now amended (see below).

Issues

• Verify and publish reasoning capability metadata for USAi models #574
• Carry reasoning and input-modality capability metadata through the neutral model catalog #366

Before / After

• Before: ADR 0006 says a separate reasoning procedure is required; none exists.
• After: the procedure exists with purpose, scope, preconditions, steps, controls, classification, decision rule, evidence-file format, stop conditions and limits, and its decision rule currently publishes nothing.

Verification

Run live (sandbox with OpenCode 2.0.30, gateway reached through the sandbox proxy):

• About 60 direct gateway requests (chat completions, streaming and non-streaming) across claude-sonnet-5.5, gpt-6-astra, gemini-3.5-flash, gpt_5_2_default_v2, with llama_4_maverick once: baseline, reasoning_effort low/high/none and thinking: disabled (the last two on two models only).
• 18 OpenCode runs against the live gateway (3 models, field absent/true/false, 2 runs each, isolated XDG tree, --standalone) plus 1 smoke run.
• About 25 OpenCode runs against a local stand-in server to compare request bodies and events for field absent/true/false, --thinking, and variants.
• Binary inspection of the OpenCode 2.0.30 executable by text search.

Not run: OpenCode 1.x, any model other than those listed, repeat runs beyond single digits, cost and latency measurement, the Quickstart projection. The procedure itself was not executed end to end (its steps were exercised piecemeal).

Checks (re-run after the amendment): make validate passes; markdownlint (.github/linters/run-markdownlint.mjs) passes; pytest 779 passed; ruff reports only pre-existing findings in unrelated files; pre-commit secret scan passes. Raw notes were kept in a gitignored scratch directory and are not in the PR.

Owner decision and ADR 0006 amendment

The owner of the epic accepted keeping reasoning absent for every model (2026-11-04). A second commit amends integrations/isolation/docs/decisions/0006-neutral-model-capability-metadata.md with a dated Amendment section (status stays proposed, history not rewritten):

• Mapping row reasoning now reads "not applied on 2.0.30": OpenCode 2.0.30 drops the field with the warning omitted unsupported legacy setting; variants do not depend on it.
• Evidence table row for reasoning now points to reasoning-validation.md and states the decision rule: no value is published; revisit only if a future OpenCode or gateway exposes an observable control.
• Renderer note: render-provider-config.mjs still emits a supplied boolean reasoning (and its tests assert that). Nothing is emitted today because the catalog and snapshots carry no reasoning. Harmless on 2.0.30 beyond one logged warning per model; OpenCode 1.x behavior was not tested. Code and tests were deliberately not changed.
• Unresolved: OpenCode 1.x, cost and latency, models not probed, consumers outside the kit.

Still docs only: no schema, catalog, renderer or script change.

Merge Guard

Docs only. Human review required. Do not merge as authority for publishing any reasoning value; ADR 0006 is still proposed.

Rollback

Revert the commits on this branch (docs only).

Security Impact

No credential exposure. The API key was read only through the environment variable placeholder by OpenCode and by throwaway local scripts that did not print, log or store it, and no environment dump was run. The document contains no key, no transcripts and no non-public hostnames. No change to authentication, data handling or attack surface.