The versioned support contract lives in compatibility/ocr-support.json. It records the recommended OCR version, every tested or observed release, exact upstream asset digests, and a SHA-256 link to normalized machine evidence. The toolkit package never downloads OCR; deployments keep using an explicitly pinned, checksum-verified binary.
The OCR compatibility workflow discovers stable upstream releases newer than the manifest monitoring floor. Its daily trigger is scheduled for 07:15 UTC, after the observed upstream release window; GitHub may delay or omit scheduled delivery, so exact-tag manual dispatch remains the recovery path. Drafts, prereleases, non-semantic tags, unexpected asset sets, oversized metadata or downloads, redirects outside the reviewed GitHub origins, and checksum disagreement fail closed. Every binary digest must agree with both GitHub release metadata and the upstream sha256sum.txt.
Candidate execution uses the verified Linux amd64 binary on an Ubuntu runner. The harness checks the reported version, the CLI flags consumed by the GitLab integration, range preview behavior, an actual JSON review through a deterministic local gateway, an aggregate-budget review that must preserve completed findings and emit budget-attributed partial coverage, and the additive JSON fields consumed by posting. Toolkit-managed numeric OCR options are also exercised at omitted/default, sentinel, invalid-below-boundary, minimum minus one, minimum, representative, and maximum edges when bounded. The evidence records closed outcomes, recognized diagnostics, normalization, ownership, and effective values observed through real loop behavior; CLI help text is not accepted as runtime evidence. For OCR 1.9.0 and later the harness also requires JSON preview without a session-store side effect and proves that additive comment thinking is accepted but not published to GitLab. Upstream source review separately verifies how OCR derives that field; the toolkit probe does not claim to reproduce a provider's private reasoning channel. Evidence permits unknown new fields but requires the fields the toolkit reads. Legacy result statuses and the versioned ocr.run-manifest/v1 outcome are normalized through one shared toolkit contract; manifest coverage sets, failure classifications, terminal state, and budget attribution must agree before a result can be published.
Built-in MCP qualification follows the protocol revisions supported by the recommended OCR release's exact MCP SDK. The current recommended release uses Go MCP SDK v1.6.1 and initiates revision 2025-11-25; the evidence server also retains 2025-06-18, 2025-03-26, and 2024-11-05 for qualified older clients. For an unknown client revision the server follows MCP negotiation semantics by returning its current supported revision, leaving acceptance or termination to the client. Qualification exercises initialize, the initialized notification, ping, tool discovery, and bounded summary/list/get calls through the exact SDK rather than relying only on handcrafted JSON-RPC fixtures.
The built-in stdio entry uses the toolkit's current absolute Python executable in isolated mode. OCR therefore does not depend on PATH lookup, and untrusted repository modules cannot shadow the installed toolkit when the MCP subprocess starts.
Candidates then take one of two lanes:
Before selecting a lane, classify every upstream changelog item as a toolkit-consumed contract change, a demonstrated future-backlog impact, or release-note-only context. For each added capability, record whether the toolkit consumes it, which runtime or CI boundary it can affect, whether adaptation is required, and which source/probe supports that conclusion. Only consumed contracts justify toolkit code or release scope; a new upstream capability does not create roadmap work unless the toolkit has a demonstrated need for it. If qualification requires a CI behavior change beyond version and checksum pins, record that impact in its own Towncrier fragment rather than hiding it inside the compatibility-version entry.
Classify a pin-only promotion and its machine or human qualification evidence as Maintenance. If the qualification exposes an existing toolkit incompatibility and the delivery corrects it, classify that outcome as a Bug Fix. If the toolkit begins exposing or consuming an upstream capability, classify that outcome as a Feature. Effective built-in rule or reviewable-file changes remain Rules even when they arrive with an otherwise maintenance-only OCR promotion.
automatic-safe: only an adjacent patch in the already-tested major/minor line, with every probe passing and maintenance-only release notes containing no material compatibility signal. When several releases are discovered together, each keeps the manifest recommendation as its tested baseline but is classified against its adjacent predecessor. The aggregation job prepares one cumulative compatibility patch only when the complete sequence is contiguous and every member is automatic-safe. The patch covers the manifest, evidence, runtime preflight version, and GitLab example version/checksum. It never writes directly tomain.human-review-required: every minor/major release, skipped or non-increasing patch, changed or failed contract, feature-bearing release, material/security/deprecation/config/provider signal, or ambiguous release notes. The workflow creates or refreshes one qualification issue with machine evidence, a bounded plain-text release-change excerpt, and a human checklist.
Each OCR version owns one stable HTML marker and one qualification issue. The workflow performs a single upsert through bounded direct issue listing rather than GitHub's eventually consistent search index. Historical issues closed with the duplicate label remain as incident evidence but do not compete for canonical identity. Any other duplicate state fails closed instead of creating another issue; after operators select and reconcile the canonical issue, reruns update it in place.
The qualification step writes evidence, public issue text, and its closed status through same-directory atomic replacements. The step outcome is authoritative: a successful step publishes validated evidence, while a failed step publishes only the closed failure status even if retained evidence exists from work completed before the failure. Status-based recovery validates no support manifest because it does not consume support metadata. The workflow publishes the issue and diagnostic artifact before restoring the failed job outcome; dependent aggregation and promotion jobs therefore remain blocked. Raw exceptions and subprocess output stay in the private job log and never enter the status or issue projection.
Evidence records optional capabilities separately from required compatibility. OCR 1.8.7 and later expose per-run provider/model overrides and additive llm result identity; older tested releases remain valid without these fields. OCR 1.9.4 additionally prints its session ID only in human-readable terminal summaries; JSON output and the toolkit-consumed result contract are unchanged. OCR 1.9.5 makes the existing aggregate budget flag visible in scan JSON, while the toolkit remains on review and separately qualifies that review's partial manifest, completed findings, and budget-attributed coverage. OCR 1.9.8 adds Bedrock as an upstream provider, moves human-audience JSON/SARIF progress to stderr, and changes only upstream skill guidance to consume native severity. The toolkit configures none of the Bedrock credential boundary, invokes review with agent audience, and already consumes the same tolerant structured severity/category result fields. Session identity and scan-only output remain OCR-owned signals rather than toolkit metrics. Profile or telemetry work must require the capability it consumes rather than treating the recommended version alone as proof.
OCR 1.9.9 was adopted and qualified for toolkit 0.7.1. It makes file background override inline background and names each static main-loop stop trigger in the failed-item reason. The toolkit therefore rejects caller --background and --background-file inputs and supplies only its own evidence bootstrap file. The new reason literals remain bounded data inside the existing ocr.run-manifest/v1 failed-item contract: retention, publication projection, DLP, and posting diagnostics already preserve or redact that field without deriving authority from its prose. Expanded upstream provider tool_choice tests do not change a consumed wire contract. Its evidence remains historical and does not require an intermediate 1.9.9 installation when deploying toolkit 0.8.0.
OCR 1.9.10 is the historical exact toolkit 0.8.0 and 0.8.1 dependency. Its terminal retry summary groups noteworthy requests by review stage, but JSON retains the unchanged structured ocr.llm-retry-report/v1; the OCR result and ocr.run-manifest/v1 contracts are unchanged. The report remains private OCR diagnostics and is not toolkit telemetry, a DLP or receipt input, finding evidence, a severity input, an outcome signal, or an automatic-approval signal. The upstream background-compression join and safe resume-checkpoint changes apply to ocr scan; the toolkit invokes ocr review. The VS Code merge-file change is outside the toolkit contract. With no toolkit completion-cap override, the qualified OpenAI wire request used max_completion_tokens=58888.
Deploy toolkit 0.8.0 or 0.8.1 directly with OCR 1.9.10. The historical public Linux amd64 example verified SHA-256 359e5bafda1438a47ef389399f4994350e1016371eac1dc17a2c428acb228e6c; its manifest entry and evidence remain unchanged.
OCR 1.10.0 was the only version accepted by toolkit 0.8.2 and 0.8.3 preflight and pinned by their published GitLab example. It groups related changed files before review, uses path-aware findings, and supports one, two, or three review rounds through effort=low|medium|high. The toolkit writes an explicit medium default, so a normal run permits two rounds; operators may select low for one round or high for three. Grouping, filtering, and additional rounds can add provider requests, latency, and token cost. Aggregate budget and manifest completeness remain authoritative, and incomplete or budget-stopped reviews remain ineligible for automatic approval.
Group labels are model-produced and group keys contain sorted changed paths. Additive group/round result fields remain untrusted private diagnostics: the toolkit sanitizes them when needed but excludes them from findings, GitLab text, receipt v5, fingerprints, severity, lifecycle commands, toolkit telemetry, and approval. OCR's own opt-in telemetry can include these repository-derived high-cardinality values; see the signal-ownership audit.
OCR 1.10.0 also adds --output; ocr-ci review rejects --output, --output=..., -o, and attached short forms before preview because the toolkit retains sole ownership of the private result descriptor and atomic validation/cleanup. Improved upstream git errors remain private OCR stderr and do not widen GitLab diagnostics. With no toolkit completion-cap override, the qualified OpenAI wire request now uses max_completion_tokens=16384, down from 58,888 in OCR 1.9.10. Qualification also proved that an explicit positive override reaches the wire; operators must select its value from their provider/model contract rather than a toolkit recommendation.
Its max-tools CLI reports a minimum and normalization target of 50, while the embedded review template owns 100 rounds and the CLI only raises that value. Exact-binary behavioral probes therefore observe effective 100 for omitted, sentinel 0, 49, and 50, and effective 101 for explicit 101; --max-tools 49 still prints the 50 normalization target. Toolkit preview accepts only that exact diagnostic shape and emits a closed operator notice. It does not copy raw stderr into the OCR result or derive finding, receipt, DLP, telemetry, lifecycle, or approval authority from the notice. The public example now passes sentinel 0 instead of a stale release-specific positive value.
Deploy toolkit 0.8.2 or 0.8.3 directly with OCR 1.10.0; do not install OCR 1.9.10 as an intermediate step. The public Linux amd64 example verifies SHA-256 f8f99ea071bed77dbcaa15fdd2083287bb8ae408d5928b3943ebe0788d191b6b; the manifest records the complete hosted asset set and qualification evidence.
OCR 1.10.1 is the historical version accepted by toolkit 0.8.4 preflight and pinned by its published GitLab example. Hosted Linux and independent Darwin arm64 qualification preserve the OCR result and ocr.run-manifest/v1 contracts, inherited OpenAI completion cap 16384, explicit 4096 override, default-medium two-round behavior, and effective max-tools values from 1.10.0. The --max-tools help text advertises a lower minimum, but actual CLI behavior still normalizes 49 to 50, the embedded template keeps effective 100, and explicit 101 raises it; the toolkit uses those behaviorally observed values and keeps the example on sentinel 0.
Toolkit 0.8.4 reduces an exact accepted soft background diagnostic to the private numeric ocr.toolkit-advisory/v1 projection after publication DLP. It is rendered only with a valid receipt v5 in GitLab Technical details and does not enter OCR warnings, coverage, DLP counts, telemetry, or automatic-approval inputs. Raw OCR output cannot supply the reserved field; duplicate, extended, unknown, malformed, or unbound forms fail closed.
The release bounds private session task/cache keys to 64 characters. Those values remain OCR-owned private routing data and do not enter toolkit telemetry, receipt v5, findings, fingerprints, lifecycle commands, or approval. OCR also adds .m to its reviewable allowlist and resolves MATLAB versus Objective-C from file content so the corresponding built-in rules can be selected. The upstream repository-local providers.go rule is not part of the toolkit-wide rules contract.
The upstream GitHub Action, delegate skill, npm launcher, and built-in provider preset are not consumed. The toolkit downloads the native binary in its GitLab example and writes an explicit protocol and provider configuration, so these changes add no implicit provider selection or CI execution path.
Deploy toolkit 0.8.4 directly with OCR 1.10.1. The public Linux amd64 example verifies SHA-256 8b806c221d409727a21611b4a7952d8e15edadbbc25f5affccaeb8f677e4055c; the local Darwin arm64 artifact verifies 8fc24bd825c9d918b894be05c0cf27fac8d30bc549257c812d87337167c7563c, and the upstream sha256sum.txt verifies ec72bda51f1227f412ee00602d952868efc57d847cce0ae1586fb97069d4139d.
OCR 1.10.2 is the historical version accepted by toolkit 0.8.5 preflight and pinned by its published GitLab example. Hosted run 33055459209, canonical issue #151, adjacent source review, and checksum-verified isolated Darwin checks preserve the OCR result, ocr.run-manifest/v1, default-medium two-round review, effective max-tools, completion-cap override, DLP, receipt v5, telemetry ownership, and approval contracts.
OCR now records grouping tasks and grace-round requests in its private session/retry state. The grouping request uses the review template's inherited OpenAI completion cap 16384 instead of the separate 4096 used by the predecessor; an explicit positive OCR_LLM_MAX_COMPLETION_TOKENS still overlays every protocol request. Its value remains deployment-owned. These private task records and group/path values do not enter toolkit findings, GitLab text, receipts, DLP signals, telemetry, or approval inputs.
Solidity (.sol) and Vyper (.vy) join the effective built-in Rules and reviewable-file contract. The upstream session-comparison command is not invoked by the toolkit. Upstream reusable GitHub Action checkpoint ranges cover only that Action's range selection; the GitLab toolkit keeps its own immutable range/snapshot and publication lifecycle, so the change only partially overlaps BL-021 and does not activate or complete a second forge adapter.
The hosted qualification initially labelled the patch automatic-safe because maintenance keywords masked the Features section. Human review overrode that result, and the classifier now treats feature-bearing patch notes as material so they require the human lane.
Deploy toolkit 0.8.5 directly with OCR 1.10.2. The public Linux amd64 example verifies SHA-256 e9205614f80e009ee7b1f444c9da08486fb9ff6db022954fe9203d923ab720b2; the independently checked Darwin arm64 artifact verifies 74fc7bcc0e6d0790c5ca033fd82a5474b6f05d443ed51a26a6f61c0cac6589fd, and the upstream sha256sum.txt verifies b5176aaa04a7f00bd84dd61556ca29e6cbdfcfe64cc50af6653163d9be4e7654.
OCR 1.11.0 is the only runtime version accepted by toolkit 0.8.6 preflight and pinned by its GitLab example. OCR 1.10.2 remains a strict comparison baseline for the grouping-inventory transition and is not a supported fallback. Hosted run 33158664020, canonical issue #155, adjacent source review, and checksum-verified evidence preserve the OCR result, ocr.run-manifest/v1, inherited OpenAI completion cap 16384, support for an operator-selected positive completion-cap override, default-medium two-round review, receipt v5, DLP, toolkit telemetry, summary, and approval contracts. The toolkit leaves that override unset and does not recommend a provider-specific value.
The private grouping and other-files prompts now use status-first STATUS path (+N/-M) inventory entries. Repeatable qualification accepts the old path (STATUS, +N/-M) shape only for historical OCR 1.10.0 through 1.10.2 and the new shape from OCR 1.11.0 onward; the 1.11.0 promotion compares the adjacent 1.10.2 and 1.11.0 evidence. Mixed, duplicate, reordered, malformed, status-inconsistent, truncated, or churn-losing evidence fails closed. Production toolkit code consumes neither format. file_find now supports repository-relative subpaths and both slash styles. The built-in allowlist and Rules add Handlebars (.hbs) and Mustache (.mustache). OCR's base subtask timeout is now 15 minutes and scales linearly with low/medium/high review rounds to 15/30/45 minutes, so the GitLab job allows 45 minutes.
OCR 1.11.0 preserves provider-native reasoning across assistant turns, removes the filter's forced tool_choice, and retains readable reasoning plus signed or encrypted native replay payloads inside the OCR session. The toolkit does not consume that state: its isolated session home is removed before publication, and reasoning, native payloads, and request controls cannot enter findings, GitLab notes, receipt v5, DLP counters, toolkit telemetry, tool/token summary, or approval inputs. Explicit operator-owned OCR_LLM_EXTRA_BODY.tool_choice remains distinct from OCR's removed forced filter value and is not published.
The release corrects stale --max-tools help text; max-tools runtime behavior is unchanged from the behaviorally qualified 1.10.2 baseline. Omitted and sentinel 0 select template default 100; 1-49 reports normalization to 50, while normalized 50 and explicit 50 remain effectively 100; only a value above 100 raises the effective cap. The toolkit's closed normalization notice remains diagnostics-only and cannot affect findings, completeness, receipt, DLP, telemetry, lifecycle, or approval.
Upstream GitHub Action, OpenCode plugin, npm launcher, Korean documentation, built-in provider presets, and interactive provider-validation changes are not toolkit execution paths and are not claimed as toolkit behavior.
Deploy toolkit 0.8.6 directly with OCR 1.11.0; do not install 1.10.2 as an intermediate version. The public Linux amd64 example verifies SHA-256 13f68cc2eca1a36d42140e9d37797b68fea5cbbf4b6345ec01ec1b06910fab60; the independently verified Darwin arm64 artifact uses ac8bf5a0fcd176bb9dcc15b169e90f4b52bf32787adef17a850489dbed97fb78, and the upstream sha256sum.txt verifies 9dff050ec859882bef26037415b8bd9e5db70c5a7d960e5eb3989385372311ee.
The contiguous 1.9.7 through 1.9.8 promotion combines the repository-owned hosted Linux qualification with adjacent upstream source review. It also repeats the required 1.9.8 contract probes through the checksum-verified Darwin arm64 artifact. Multi-tool MCP initialization, fixed tool discovery and dispatch, and owner-only session persistence remain compatible with the M5 design: the toolkit may expose several fixed tools from its one built-in process, while an isolated HOME contains OCR's .opencodereview/sessions state for deterministic cleanup. Gemini and Bedrock are optional upstream provider capabilities that the toolkit neither selects nor configures; mirror-aware installation is outside the toolkit-owned download path; native severity retains the structured result fields already consumed; and human-audience progress routing does not affect the toolkit's agent-audience invocation. Therefore this promotion requires no toolkit CI behavior adaptation beyond version and checksum pins. These source observations establish capability only; the M5 production-path tests remain responsible for proving the toolkit's composition and containment.
An automatic-safe result is not an automatic stable release. It must still pass a normal protected compatibility PR and a separate signed stable-release PR. If a dedicated OCR update bot credential is not configured, the workflow publishes the exact patch as an artifact and records the resume action in the issue; the default GITHUB_TOKEN is intentionally not used to create a PR that would fail to trigger the full protected workflow set.
Promotion changes recommended_version, advances monitoring_floor, adds the tested release and evidence, and updates every machine-readable or executable version/checksum pin. Never edit only one copy. Human-qualified candidates must record the compatibility conclusion and release-note impact; an automatic-safe candidate may also record a reviewed conclusion when it is delivered with a human-reviewed chain instead of using the generic machine conclusion. Conclusions may name only versions present in that promotion. A reviewed promotion may cross only one adjacent semantic-version boundary at a time: the next patch, the next minor at .0, or the next major at .0.0; minor and major transitions always require an explicit human conclusion. Automatic-safe preparation remains limited to adjacent patches in the already-tested major/minor line and retains the same protected review boundary even though the patch itself is mechanical.
Rollback selects a previously tested manifest entry, restores its runtime and executable-example pins, and travels through the same release-required path. Do not delete historical evidence: it explains the prior support decision and lets future qualification distinguish a rollback from an unseen release.