From cdea5264ada0609edb46d1a72d1c556228d2bb95 Mon Sep 17 00:00:00 2001 From: xeonvs <11463419+xeonvs@users.noreply.github.com> Date: Wed, 26 Aug 2026 10:25:52 +0200 Subject: [PATCH] Release v0.8.3 --- .next-version | 2 +- .release-metadata.json | 9 +- .release-source-date-epoch | 2 +- .release-version | 2 +- CHANGELOG.md | 21 + PLANS.md | 366 +----------------- changelog.d/139.bugfix.md | 1 - changelog.d/140.bugfix.md | 1 - changelog.d/142.feature.md | 4 - changelog.d/143.maintenance.md | 1 - docs/compatibility.md | 6 +- docs/configuration.md | 6 +- docs/engineering/execution_history/README.md | 1 + .../engineering/execution_history/releases.md | 76 ++++ examples/gitlab/ocr-review.gitlab-ci.yml | 2 +- tests/test_operations_docs.py | 4 +- tests/test_release_notes.py | 18 + 17 files changed, 134 insertions(+), 388 deletions(-) delete mode 100644 changelog.d/139.bugfix.md delete mode 100644 changelog.d/140.bugfix.md delete mode 100644 changelog.d/142.feature.md delete mode 100644 changelog.d/143.maintenance.md diff --git a/.next-version b/.next-version index ee94dd8..b60d719 100644 --- a/.next-version +++ b/.next-version @@ -1 +1 @@ -0.8.3 +0.8.4 diff --git a/.release-metadata.json b/.release-metadata.json index ff21d73..ca837e8 100644 --- a/.release-metadata.json +++ b/.release-metadata.json @@ -1,9 +1,10 @@ { "issues": [ - 135, - 136, - 137 + 139, + 140, + 142, + 143 ], "schema_version": "ocr-toolkit.release-authorization/v1", - "version": "0.8.2" + "version": "0.8.3" } diff --git a/.release-source-date-epoch b/.release-source-date-epoch index 241e042..7a102d1 100644 --- a/.release-source-date-epoch +++ b/.release-source-date-epoch @@ -1 +1 @@ -1787648187 +1787732180 diff --git a/.release-version b/.release-version index 100435b..ee94dd8 100644 --- a/.release-version +++ b/.release-version @@ -1 +1 @@ -0.8.2 +0.8.3 diff --git a/CHANGELOG.md b/CHANGELOG.md index f6517bc..74bcf2c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,24 @@ +## 0.8.3 - 2026-08-26 + +### ๐Ÿš€ Features + +- GitLab technical details now make OCR review activity easier to explain without implying unsupported token attribution. + + - **Added:** the existing inline `all OCR tool calls` line shows every non-zero counter from the closed OCR inspection, review-output, and toolkit context/evidence set instead of collapsing entries after the six most frequent tools. + - **Unchanged:** aggregate input/output/cache token usage remains separate because OCR does not report per-tool token consumption; raw call arguments, results, dynamic external MCP tool names, receipt v5, DLP, findings, severity, and automatic approval are unchanged. + + ([#142](https://github.com/xeonvs/open-code-review-toolkit/issues/142)) + +### ๐Ÿ› Bug Fixes + +- Made OCR compatibility failure publication authoritative and recoverable. The workflow now selects closed status or evidence from the actual qualification outcome, atomically replaces output handoffs, and can publish a failure status without loading unrelated support metadata. It still publishes the bounded issue and diagnostic artifact before returning a red job, while aggregate promotion remains blocked and raw diagnostics remain private. ([#139](https://github.com/xeonvs/open-code-review-toolkit/issues/139)) +- Fixed the GitLab example's stale positive `OCR_MAX_TOOLS` default by delegating with sentinel `0`. Added exact parsing for OCR's supported max-tools normalization notice and behavior-based compatibility evidence for numeric CLI boundaries, including the effective template-owned tool-loop value. The notice remains operator-only: raw OCR stderr, findings, result warnings, receipts, DLP, telemetry, lifecycle commands, and automatic-approval semantics are unchanged. ([#140](https://github.com/xeonvs/open-code-review-toolkit/issues/140)) + +### ๐Ÿ›  Maintenance + +- Keep both macOS endpoint CI jobs as visible best-effort compatibility diagnostics while retaining Linux, coverage, quality, security, dependency, package, and CodeQL checks as release-blocking gates. ([#143](https://github.com/xeonvs/open-code-review-toolkit/issues/143)) + + ## 0.8.2 - 2026-08-25 ### ๐Ÿš€ Features diff --git a/PLANS.md b/PLANS.md index 0eacf20..ca171a2 100644 --- a/PLANS.md +++ b/PLANS.md @@ -4,368 +4,4 @@ Use this file for active or blocked repository work. Update it before implementa ## Active Work -### Toolkit 0.8.3 โ€” OCR boundaries and review tool-usage visibility - -Status: `active` -Owner: Codex -Plan Origin: `resumed` -Release classification: `release-required` -Target stable version: `0.8.3` -Last Updated: 2026-08-26 - -#### Goal - -Close #139 and #140 and add one bounded review-usage feature as one protected -0.8.3 release: make a failed OCR -qualification's closed status authoritative even when stale evidence or invalid -support metadata exists, and replace the stale example-owned `OCR_MAX_TOOLS=30` -contract with installed-OCR delegation plus behaviorally qualified numeric CLI -boundaries. Extend the existing one-line GitLab technical summary so its bounded -numeric breakdown shows the useful non-zero OCR review-tool counters rather than -only the first six. Preserve private diagnostics, aggregate-promotion blocking, -the exact OCR 1.10.0 pin, DLP, receipt v5, posting, and automatic-approval -semantics. - -#### Requested Scope - -- Select OCR compatibility issue input from the actual qualification outcome; - retained evidence from a failed step must never win over its failed status. -- Ensure every handled qualification failure after evidence creation, including - a late issue-body write failure, commits a closed failure status before the - workflow publishes the issue/artifact and restores the red job outcome. -- Let `upsert-issue --status` validate and publish a closed status independently - of an invalid support manifest that the command does not consume. -- Replace the GitLab example's release-specific max-tools value with OCR's - supported `0` sentinel and document the exact default as inherited from OCR. -- Recognize only the installed OCR's closed max-tools normalization diagnostic; - expose a toolkit-authored operator notice without publishing raw stderr or - treating the diagnostic's reported minimum as proof of the effective loop cap. -- Extend OCR qualification to exercise the behavior and effective semantics of - toolkit-managed numeric OCR review options at omitted/default, sentinel, - invalid-below-boundary, accepted-boundary, representative, and maximum edges - where a maximum exists. Record only bounded closed facts in evidence. -- Add separate bug-fix changelog fragments for #139 and #140, update canonical - development/public contracts, and complete the protected PR and stable-release - lifecycle without a local real-LLM/model invocation. -- Keep the current inline `all OCR tool calls` format while publishing every - admitted non-zero counter that helps explain review activity: OCR repository - inspection (`file_read`, `file_read_diff`, `file_find`, `code_search`), review - output/lifecycle (`code_comment`, `task_done`), toolkit context/evidence - (`ocr_toolkit_evidence`, `context_list`, `context_get`), and the already - verified per-server MCP summary. -- Treat tool-call counts as operational activity only. Keep aggregate token - input/output/cache telemetry alongside them, but do not claim or derive - per-tool token consumption because OCR 1.10.0 does not provide that contract. -- Keep the Linux Python 3.12-3.14 matrix, quality, security, dependency, build, - and CodeQL checks release-blocking while making the two macOS endpoint jobs - best-effort diagnostics that cannot delay the priority Linux hotfix release. - -#### Requirement Traceability - -| Requirement | Source | Outcome | Work items | Verification | -| --- | --- | --- | --- | --- | -| `REQ-139-A` | #139 acceptance 1 | Qualification outcome, not file existence, selects evidence versus status | `WQ-02` | Workflow contract test with retained evidence and failed outcome | -| `REQ-139-B` | #139 acceptance 2 | Late output failure produces authoritative failed status | `WQ-02` | Injected issue-body and partial/failed write tests | -| `REQ-139-C` | #139 acceptance 3 | Status recovery does not load the support manifest | `WQ-02` | Invalid-manifest CLI recovery test | -| `REQ-139-D` | #139 acceptance 4-6 | Issue/artifact publish before red job; aggregate blocked; projection stays closed and private-safe | `WQ-02`, `WQ-04` | Focused script/workflow tests and privacy diff review | -| `REQ-140-A` | #140 expected behavior/scope | Public example delegates max-tools default to installed OCR | `WQ-03` | Environment, docs, and integration contract tests | -| `REQ-140-B` | #140 acceptance 2-4 | Exact enriched/MCP preview accepts valid sentinel and handles known normalization without ambiguous/raw diagnostics | `WQ-03` | Parser negatives plus production-caller integration with controlled OCR peer | -| `REQ-140-C` | #140 scope/acceptance 5 | Qualification records behavioral numeric boundaries and effective-value ownership | `WQ-03` | Exact OCR 1.10.0 no-model probe and evidence-schema tests | -| `REQ-140-D` | #140 acceptance 6 | Current docs/tests avoid toolkit-release wording where OCR owns the contract | `WQ-03`, `WQ-04` | Documentation contract tests and full-text review | -| `REQ-USAGE-A` | #142 and user-approved manager-facing usage summary | Existing inline technical format includes every admitted useful non-zero tool counter, deterministically ordered by count then name | `WQ-06` | Formatter and complete summary regressions with more than six tools | -| `REQ-USAGE-B` | #142 result/privacy boundary | Only bounded names and integer counters cross into GitLab; arguments, results, paths, IDs, provider data, and unknown/unattributed names remain private | `WQ-06` | Hostile map/name/count, DLP, Markdown, and note-budget regressions | -| `REQ-USAGE-C` | #142 honest token explanation | Tool activity appears beside aggregate token usage without percentages or per-tool token attribution | `WQ-06` | Rendering and documentation assertions | -| `REQ-USAGE-D` | #142 existing trust contracts | The expanded diagnostic is not a finding, receipt proof, telemetry source, severity input, or approval signal | `WQ-06`, `WQ-07` | Posting, DLP, and approval regression review | -| `REQ-MACOS-A` | Owner-authorized hotfix release policy | macOS 3.12 and 3.14 jobs continue to run but are explicitly non-blocking; Linux endpoints and all non-platform release gates remain required | `WQ-08` | Workflow contract test plus live ruleset readback | -| `REQ-REL` | Repository release contract | Deliver 0.8.3 through reviewed feature and release PRs with external reconciliation | `WQ-01`, `WQ-04`, `WQ-05` | Protected checks, registries, attestations, tag, receipt, issue/milestone closure | - -#### Explicit Non-Goals - -- Do not update OCR beyond exact 1.10.0 or change its checksum-pinned evidence - except for additive qualification facts required by #140. -- Do not add a toolkit prompt/context max-tokens alias, a new configuration - format, automatic discovery from help text, or a second compatibility service. -- Do not infer a maximum from absent diagnostics or treat OCR's documented - `min 10` help text as authoritative over observed behavior. -- Do not publish raw subprocess output, filesystem paths, provider/model data, - repository content, credentials, or exception strings in issues or receipts. -- Do not change DLP, receipt v5, severity, findings, posting transactions, - telemetry ownership, or automatic-approval eligibility. -- Do not run a local real LLM/model/provider review. A controlled deterministic - HTTP peer may exercise the OCR process boundary but is not model evidence. -- Do not reorganize tests or production modules beyond the cohesive owners - directly required by these two fixes. -- Do not change the current one-line technical-summary layout, publish a catalog - of merely available tools, add per-tool token estimates/percentages, or expose - raw tool-call arguments, results, errors, paths, request IDs, or dynamic - external MCP tool names. -- Do not remove macOS support metadata or stop its endpoint jobs from running; - only their merge-blocking status changes. Do not weaken Linux, coverage, - quality, security, dependency, package, or release-publication gates. - -#### Constraints - -- Start from clean synchronized `main` at stable `v0.8.2`; use branch prefix - `codex/` and signed logical commits. -- Before each commit: focused tests, requirement/trust-boundary self-review, - complete staged diff review, and `git diff --check`. -- Run `scripts/quality.sh check` and `scripts/gitleaks.sh` once on the final - feature head. Hosted PR checks own the full OS/Python matrix and package build; - do not duplicate those gates locally without a new package boundary. -- Keep subprocess reads bounded, exact-schema status/evidence hostile on load, - and issue projection based only on closed enums and validated version/run IDs. -- Preserve the user-owned environment: isolated temporary `HOME` only, no OCR - config/credential writes, no global OCR installation change, and full cleanup. - -#### Inputs And Sources - -- GitHub issues #139, #140, and #142, including their complete acceptance criteria. -- `.github/workflows/ocr-compatibility.yml`, `scripts/ocr_compat.py`, - `src/ocr_toolkit/review_runner.py`, current focused tests and public contracts. -- `docs/engineering/project_principles.md` persisted/atomic-state, external-format, - subprocess, outcome-consistency, and integration-proof boundaries. -- Official OCR `v1.10.0` source in `cmd/opencodereview/shared_flags.go`, - `cmd/opencodereview/shared.go`, and embedded `task_template.json`. -- Official OCR `v1.10.0` built-in registry and tools configuration: six native - review tools (`task_done`, `code_comment`, `file_read`, `file_read_diff`, - `file_find`, and `code_search`); toolkit context/evidence tools remain owned by - the exact MCP composition and receipt. -- Isolated local OCR 1.10.0 no-model preview evidence: omitted and `0` accepted; - negative rejected; `1..49` report normalization to `50`; `50+` accepted; help - says `min 10`; embedded template owns `MAX_TOOL_REQUEST_TIMES=100` and applies - CLI max-tools only when it raises that template value. - -#### User Decisions And Answers - -- Take both currently open issues into active work. -- Local execution against a real LLM/provider is explicitly waived because this - environment has no access; do not claim that evidence. -- Continue the established efficient workflow: logical commits, self-review, - one final complete local gate, and protected hosted CI. -- Resume and complete the full stable 0.8.3 lifecycle now: update the existing - Draft, make it ready, merge through protected `main`, publish and independently - verify the stable artifacts, then close the tracked issues and milestone. -- macOS endpoint jobs remain useful best-effort compatibility diagnostics but - must not block the priority Linux hotfix release; all Linux and non-platform - release gates stay mandatory. -- The accepted manager-facing question is โ€œwhere did the review activity go?โ€: - preserve the current inline format, show the selected numeric counters, and - explicitly avoid claiming exact per-tool token attribution. - -#### Completed Baseline State - -- `main` is clean at stable merge `6dae5b3821eb7aa22c8c8d8d9c17f869278340c7` - and tree `ba935a1f0a7f0e6e6c899120ecdc08e3822097c4`. -- Toolkit 0.8.2 and OCR 1.10.0 are published and reconciled; `.next-version` is - `0.8.3`; no active plan or open milestone existed before this activation. -- #139 reproduces three authority/recovery gaps added by the 0.8.2 failure path. -- #140 reproduces before any provider call because successful OCR preview stderr - currently accepts only the background-warning grammar. -- The previously handed-off Draft head `e5a889f` is clean and fully green across - protected hosted checks. Its current formatter publishes the aggregate total - but truncates a valid per-tool breakdown to six entries, which is insufficient - for the newly approved activity explanation. - -#### Current Work Queue - -| Work item | Status | Scope and commit boundary | -| --- | --- | --- | -| `WQ-01` | `done` | Signed planning commit `85b3097`; branch `codex/v0.8.3-ocr-boundaries`; milestone `v0.8.3` #6 with #139/#140; planning push; Draft PR #141 with exact scope/non-claims | -| `WQ-02` | `done` | #139: outcome-authoritative workflow selection; portable atomic evidence/status/issue-body handoffs; closed late-write recovery; manifest-independent status upsert; regression tests; public contract and `139.bugfix.md` | -| `WQ-03` | `done` | #140: example sentinel `0`; exact normalization parser and operator-only notice; behavioral numeric/effective-loop qualification; updated exact OCR evidence/hash; full enriched/MCP preview regression; public/development contracts and `140.bugfix.md` | -| `WQ-04` | `done` | Reconciled public/development contracts and requirements; complete quality/coverage, manifest, Towncrier, and privacy/data-flow review are green; final Draft push and hosted readback are handoff actions, not release delivery | -| `WQ-05` | `in_progress` | Owner-authorized stable delivery: exact-head review and feature merge; development publication readback; protected `release/v0.8.3` PR; stable workflow; independent registry/tag/provenance/attestation/install/receipt verification; issue and milestone closure | -| `WQ-06` | `done` | #142 feature commit `a416f37`: the existing inline formatter now shows every admitted useful non-zero counter; external MCP stays aggregated by verified server; focused hostile-value/DLP/approval tests, public operational wording, and `142.feature.md` define the activity-not-token-attribution contract | -| `WQ-07` | `done` | One final full local gate and overall reporting/privacy/approval self-review are green; this signed handoff commit is followed by one final push, Draft/issue coordination, and exact-head hosted readback as delivery evidence rather than another repository-content change | -| `WQ-08` | `in_progress` | Make macOS 3.12/3.14 CI entries explicitly best-effort, preserve their execution and all mandatory Linux/non-platform gates, update the workflow contract/docs/changelog, and reconcile the live protected-main ruleset before readiness | - -#### Locked Decisions - -- Both issues belong to stable 0.8.3 and remain separate changelog entries. -- `OCR_MAX_TOOLS` remains an optional example-local variable but defaults to - sentinel `0`, whose meaning is exactly โ€œinherit installed OCR templateโ€. -- OCR's normalization diagnostic is a bounded installed-component fact. Its raw - text never crosses into result/posting/receipt; the toolkit reports only parsed - integers and distinguishes the reported normalization target from the actual - template-owned loop limit. -- A failed qualification status is authoritative whenever the qualification step - outcome is failure, even if a complete evidence file also exists. -- `upsert-issue --status` has no support-manifest dependency; evidence-driven - discovery, qualification, aggregation, and promotion retain manifest validation. -- OCR remains external and pinned to 1.10.0. No local model result substitutes - for hosted exact-binary or deterministic controlled-peer evidence. -- The existing `all OCR tool calls: N total (...)` line remains the sole OCR - tool-counter format. It lists admitted non-zero counters by descending count - and then name; no grouping, percentages, or token-allocation inference is added. -- Built-in OCR and toolkit-owned context/evidence names may be shown as activity. - External dynamic MCP tools remain represented only through the existing - verified per-server aggregate; unknown raw names never gain public meaning. -- Linux is the release-priority platform. macOS remains supported and exercised - at both Python endpoints, but its two hosted jobs are advisory rather than - protected-main requirements; failures stay visible for follow-up. - -#### Verification - -- #139: focused `tests/test_ocr_compat.py` and workflow-source tests covering - retained evidence, late write failure, invalid manifest, closed schemas, - publication-before-red ordering, and blocked aggregation. -- #140: focused environment/integration/review-runner/compatibility tests covering - sentinel/default, normalization, duplicate/near-miss/Unicode/oversized stderr, - known/unknown success output, invalid non-zero diagnostics, effective-value - evidence, and the complete evidence/MCP production caller up to the model gate. -- Exact installed OCR 1.10.0: isolated no-real-model boundary probe only; preserve - command/exit/closed diagnostics/effective counts and remove its temporary HOME. -- Final feature head: `scripts/quality.sh check`, coverage floors, - `PYTHONPATH=src python scripts/ocr_compat.py validate`, Towncrier draft, - `scripts/gitleaks.sh`, `git diff --check`, and clean-tree confirmation. -- Hosted: all protected Draft feature checks on the exact final head. Development - publication, stable release, registry/provenance/install readback, and closure - remain deferred under `docs/release.md`. -- Tool-usage slice: focused formatter/posting/result-DLP/approval tests must prove - more than six useful counters remain visible, deterministic and bounded; raw - call content and unknown names remain absent; aggregate token rendering and - approval decisions are unchanged. -- macOS CI policy: workflow-source tests prove both endpoint jobs still exist and - are marked non-blocking while every Linux endpoint remains blocking; live - ruleset readback must omit only the two macOS contexts. - -#### Latest Validation Results - -- 2026-08-25 reconnaissance: clean synchronized `main`; workflow audit reports - canonical owners and complete documentation indexes; exactly #139 and #140 are - open; both have no milestone. -- Isolated OCR 1.10.0 preview matrix reproduced #140 without LLM access and was - fully cleaned. Official tag source disproved the assumption that reported - normalization target `50` is necessarily the effective loop cap. -- No implementation, repository metadata, issue, milestone, branch, or PR write - preceded this plan materialization. -- Coordination completed after the signed plan commit: milestone `v0.8.3` #6, - #139/#140 assignment, planning head push, and Draft PR #141. The owner then - explicitly deferred merge and release; no publication belongs to this run. -- #139 focused validation: 95 compatibility/workflow tests pass; Ruff and - `git diff --check` pass. Self-review confirms the workflow selects output from - `steps.qualify.outcome`, all file handoffs preserve the old baseline until an - atomic replace, status recovery consumes only its closed schema, raw details - remain private, and the restored red qualification blocks aggregation. -- #140 focused validation: 212 runtime/compatibility/environment/integration/ - documentation tests pass with Ruff, manifest validation, Towncrier draft, and - `git diff --check`. Exact installed OCR 1.10.0 Darwin arm64 no-model probes - pass in isolated temporary homes: CLI minimum/normalization target `50`, - effective template value `100`, and explicit `101` producing 101 rounds. - The enriched production caller performs collection, store/bootstrap, MCP - registration/self-query, and exact preview before its controlled model - boundary; the parsed normalization becomes only a CI notice and leaves result - warnings, DLP, receipt, posting, telemetry, and approval inputs unchanged. -- Final local quality gate passes 1,269 tests plus 310 subtests at 86.16% - combined branch coverage; risk groups report 84%, 82%, 85%, and 87% against - floors 80%, 80%, 85%, and 85%. Ruff format/check, strict MyPy, Bandit, - manifest validation, the rendered 0.8.3 Towncrier draft, and complete - requirement/privacy/data-flow self-review pass. The first gate invocation - stopped before tests on four format-only differences; Ruff formatted those - files, signed commit `743d8fa` amended the logical slice, and the complete - gate then passed on the corrected implementation head. -- Protected hosted checks subsequently passed on exact pushed head - `e5a889ff2c415adc1dbce706582da5480024cc7d` and tree - `1b89c1a69a7014baa0199343c457e7eb69419697`; PR #141 remained Draft, #139/#140 - acceptance boxes were checked, and both issues plus milestone stayed open. -- The user then approved an additive numeric tool-activity breakdown in the - existing format. No repository or GitHub write for that new slice preceded - this resumed-plan materialization. -- #142 now owns the additive feature under milestone `v0.8.3`. The combined - focused formatter, posting, result-DLP, approval, documentation, and release - gate passes 330 tests plus 133 subtests; the rendered Towncrier draft keeps - #142 under Features with #139/#140 separately under Bug Fixes. -- Feature self-review confirms only the nine compile-time native/context/evidence - labels and bounded positive integer counts can enter the inline line. Unknown - or dynamic names remain private, static labels cannot create DLP false - positives, filtered projections retain safe native counts, and the aggregate - token line plus receipt/approval authorities are unchanged. -- Final local quality passes 1,275 tests plus 324 subtests at 86.35% combined - branch coverage. Risk groups pass at 84%, 82%, 86%, and 87% against floors - 80%, 80%, 85%, and 85%; Ruff format/check, strict MyPy, and Bandit pass. - Lock and OCR-manifest validation, the rendered Towncrier draft, - checksum-verified temporary Gitleaks 8.24.3, `git diff --check`, and clean-tree - confirmation also pass. The global Gitleaks installation and OCR/LLM state - were not changed. - -#### Risks And Recovery - -- A stale evidence artifact may coexist with failure status. Recovery: bind issue - selection to step outcome and keep aggregate dependent on the restored red job. -- Status output itself may encounter unsafe/partial filesystem state. Recovery: - use a bounded same-directory atomic writer and fail the job without adopting a - partial status; workflow upload remains diagnostic, never promotion evidence. -- Future OCR diagnostics may change spelling or semantics. Recovery: exact closed - parsing and compatibility probes fail closed; promote a new grammar only with a - checksum-pinned OCR release and tests. -- The OCR help/runtime/template mismatch can mislead documentation. Recovery: - document sentinel ownership and observed behavior separately; never derive a - runtime contract from help text alone. -- External write or hosted CI failure: preserve local commits and Draft PR, record - exact run evidence, fix only the demonstrated boundary, and rerun its focused - gate before a new signed commit. -- Tool counts can be mistaken for token allocation, and one tool call can return - very different context volume from another. Recovery: label them only as OCR - tool calls, retain the separate aggregate token line, document the limitation, - and never compute per-tool token shares. -- A hostile or future OCR result can add names or excessive counters. Recovery: - admit only the closed useful set, validate bounded integer counts, sort - deterministically, and omit unknown/raw entries without changing review or - approval state. - -#### Resume Point - -Finish `WQ-08`, push the signed feature head, and require the updated hosted -checks plus exact live-ruleset readback. Then make PR #141 ready and complete -`WQ-05` through feature merge, protected release PR, stable publication, -independent external verification, issue receipts, and milestone closure. - -#### Plan Fidelity Check - -- [x] Every requested issue acceptance criterion maps to a stable requirement and work item. -- [x] Release target, local-LLM waiver, privacy boundaries, and unchanged contracts are explicit. -- [x] Inputs distinguish current repository behavior, official OCR source, and observed probes. -- [x] Rejected scope and overengineering boundaries are explicit. -- [x] Each logical commit has focused verification and self-review gates. -- [x] External writes, hosted delivery, recovery, and exact resume state are represented. -- [x] The accepted tool list, current-format decision, token-attribution - non-claim, and unknown/external-tool privacy boundary are explicit. - -#### Reconciliation Check - -- [x] `PLANS.md` was inactive and the worktree was clean at activation. -- [x] #139, #140, and #142 are the complete open release issue set and do not conflict with backlog/roadmap scope. -- [x] Stable 0.8.2 closure remains historical and is not rewritten. -- [x] Target 0.8.3 matches `.next-version` and no competing milestone exists. -- [x] The new reporting slice extends the open Draft and milestone without - changing the completed #139/#140 contracts or deferred-release boundary. - -#### Closure Gate - -- [x] All implementation requirements and in-scope work items are terminal with current local validation evidence. -- [x] Complete diff self-review confirms issue, workflow, subprocess, privacy, DLP, approval, and documentation boundaries. -- [ ] Exact feature head is green locally and in protected hosted checks with resolved review threads. -- [ ] PR #141 is merged from the exact reviewed head and development publication is verified. -- [ ] Release PR is merged from its exact reviewed head; stable artifacts, tag, - provenance, attestations, immutable Release, installs, and receipt are verified. -- [ ] #139/#140/#142 plus the macOS CI policy issue and milestone `v0.8.3` are closed only after stable receipt publication. - -#### Post-Close Delivery - -- This run is authorized to complete the protected feature and stable-release - lifecycle. Readiness, feature merge, development publication, release merge, - stable publication, and external reconciliation remain separate gates. -- #139/#140/#142 and milestone `v0.8.3` remain open until stable receipt publication. -- Final handoff must repeat that no local real-LLM/provider qualification was run - or claimed, while identifying the exact deterministic OCR boundary evidence. -- #142 and its feature fragment separately own the manager-facing reporting - change; #139 and #140 stay checked/open and do not absorb it. -- Final handoff must state that tool-call counts explain review activity only; - exact per-tool token consumption remains unavailable in OCR 1.10.0. - -#### Handoff Notes - -- Resume at `WQ-08` on exact Draft head `62f5bd7`; do not repeat completed feature work. -- The source-level max-tools mismatch is material: reported normalization `50` - and embedded template default `100` are distinct facts. Preserve that distinction - in code, evidence, docs, changelog, issue updates, and future OCR upgrades. +No active or blocked repository work. diff --git a/changelog.d/139.bugfix.md b/changelog.d/139.bugfix.md deleted file mode 100644 index 3c637d2..0000000 --- a/changelog.d/139.bugfix.md +++ /dev/null @@ -1 +0,0 @@ -Made OCR compatibility failure publication authoritative and recoverable. The workflow now selects closed status or evidence from the actual qualification outcome, atomically replaces output handoffs, and can publish a failure status without loading unrelated support metadata. It still publishes the bounded issue and diagnostic artifact before returning a red job, while aggregate promotion remains blocked and raw diagnostics remain private. diff --git a/changelog.d/140.bugfix.md b/changelog.d/140.bugfix.md deleted file mode 100644 index 64c0f0b..0000000 --- a/changelog.d/140.bugfix.md +++ /dev/null @@ -1 +0,0 @@ -Fixed the GitLab example's stale positive `OCR_MAX_TOOLS` default by delegating with sentinel `0`. Added exact parsing for OCR's supported max-tools normalization notice and behavior-based compatibility evidence for numeric CLI boundaries, including the effective template-owned tool-loop value. The notice remains operator-only: raw OCR stderr, findings, result warnings, receipts, DLP, telemetry, lifecycle commands, and automatic-approval semantics are unchanged. diff --git a/changelog.d/142.feature.md b/changelog.d/142.feature.md deleted file mode 100644 index 4b7711b..0000000 --- a/changelog.d/142.feature.md +++ /dev/null @@ -1,4 +0,0 @@ -GitLab technical details now make OCR review activity easier to explain without implying unsupported token attribution. - -- **Added:** the existing inline `all OCR tool calls` line shows every non-zero counter from the closed OCR inspection, review-output, and toolkit context/evidence set instead of collapsing entries after the six most frequent tools. -- **Unchanged:** aggregate input/output/cache token usage remains separate because OCR does not report per-tool token consumption; raw call arguments, results, dynamic external MCP tool names, receipt v5, DLP, findings, severity, and automatic approval are unchanged. diff --git a/changelog.d/143.maintenance.md b/changelog.d/143.maintenance.md deleted file mode 100644 index 5ae323c..0000000 --- a/changelog.d/143.maintenance.md +++ /dev/null @@ -1 +0,0 @@ -Keep both macOS endpoint CI jobs as visible best-effort compatibility diagnostics while retaining Linux, coverage, quality, security, dependency, package, and CodeQL checks as release-blocking gates. diff --git a/docs/compatibility.md b/docs/compatibility.md index 8fd65cd..00d4e49 100644 --- a/docs/compatibility.md +++ b/docs/compatibility.md @@ -37,9 +37,9 @@ OCR 1.9.10 is the historical exact toolkit 0.8.0 and 0.8.1 dependency. Its termi 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 โ€” toolkit 0.8.2 target +### OCR 1.10.0 โ€” toolkit 0.8.2 and 0.8.3 target -OCR 1.10.0 is the only version accepted by toolkit 0.8.2 preflight and pinned by its 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`. Toolkit 0.8.2 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. +OCR 1.10.0 is the only version accepted by toolkit 0.8.2 and 0.8.3 preflight and pinned by the current 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](engineering/review_signal_ownership.md). @@ -47,7 +47,7 @@ OCR 1.10.0 also adds `--output`; `ocr-ci review` rejects `--output`, `--output=. 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 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. +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. 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. diff --git a/docs/configuration.md b/docs/configuration.md index 974f852..6fc0762 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -58,7 +58,7 @@ Since 0.8.0, `OCR_USE_ANTHROPIC` is not a compatibility alias. Any presence fail If `OCR_LLM_EXTRA_BODY` already owns that field, an exactly equal JSON integer is deduplicated. A different value, or a boolean, string, float, or null at that field, fails configuration with a migration error; remove the duplicate field or keep the same integer in both places. Other `OCR_LLM_EXTRA_BODY` members are preserved. For example, set `OCR_LLM_MAX_COMPLETION_TOKENS=4096` when a gateway accepts short probes but rejects a full review before generation because it reserves spending against the requested output cap. -Toolkit 0.8.2 does not derive this value from `/models.max_completion_tokens`. That metadata is a model capability boundary, not an account spending limit or proof of how a gateway reserves request cost. +The toolkit does not derive this value from `/models.max_completion_tokens`. That metadata is a model capability boundary, not an account spending limit or proof of how a gateway reserves request cost. The inherited value is version-owned and therefore changes with a qualified OCR upgrade. The toolkit observed `max_completion_tokens=58888` from OCR 1.9.10 and `16384` from OCR 1.10.0 when the variable was unset. Deployments that require an invariant gateway-specific cap must set `OCR_LLM_MAX_COMPLETION_TOKENS` explicitly rather than depending on either OCR default. @@ -92,9 +92,9 @@ These names belong to `examples/gitlab/ocr-review.gitlab-ci.yml`; they are shell | Variable | Source / owner | Required | Exact default | Behavior | | --- | --- | --- | --- | --- | -| **`OCR_VERSION`** | Example pipeline | Yes | `v1.10.0` | Checksum-pinned recommended OCR binary release for toolkit 0.8.2. | +| **`OCR_VERSION`** | Example pipeline | Yes | `v1.10.0` | Checksum-pinned recommended OCR binary release for toolkit 0.8.3. | | **`OCR_SHA256`** | Example pipeline | Yes | `f8f99ea071bed77dbcaa15fdd2083287bb8ae408d5928b3943ebe0788d191b6b` | Expected Linux AMD64 OCR binary digest. | -| **`OCR_TOOLKIT_VERSION`** | Example pipeline | Yes | `0.8.2` | Exact toolkit wheel release installed by the current published example. | +| **`OCR_TOOLKIT_VERSION`** | Example pipeline | Yes | `0.8.3` | Exact toolkit wheel release installed by the current published example. | | **`OCR_TOOLKIT_CHECKSUMS_URL`** | Example pipeline | Yes | Release URL derived from `OCR_TOOLKIT_VERSION` | Toolkit `SHA256SUMS` URL. | | `OCR_TOOLKIT_WHEEL` | Example shell | Computed | `open_code_review_toolkit-${OCR_TOOLKIT_VERSION}-py3-none-any.whl` | Exact wheel filename selected from the release. | | `OCR_TOOLKIT_WHEEL_SHA256` | Example shell | Computed | Matching value from `SHA256SUMS` | Digest checked before installing the toolkit wheel. | diff --git a/docs/engineering/execution_history/README.md b/docs/engineering/execution_history/README.md index b4ee2c7..f512c2e 100644 --- a/docs/engineering/execution_history/README.md +++ b/docs/engineering/execution_history/README.md @@ -6,6 +6,7 @@ | Stable tag | Primary archived plan | Related context in the same archive | | --- | --- | --- | +| `v0.8.3` | [OCR boundaries and review tool-usage visibility](releases.md#plan-toolkit-0-8-3) | Authoritative compatibility failure publication, installed-OCR numeric boundary ownership, complete bounded review tool-activity counters, advisory macOS endpoint checks, feature merge, development artifact verification, explicit local-LLM non-claim, and stable-delivery handoff. | | `v0.8.2` | [OCR 1.10.0, review effort, and compatibility failure recovery](releases.md#plan-toolkit-0-8-2) | Exact OCR 1.10.0 promotion, medium review effort, private grouping/round data, toolkit-owned output/DLP/approval boundaries, failed-qualification retention, BL-017 ownership audit, feature merge, development artifact verification, explicit local-LLM non-claim, and stable-delivery handoff. | | `v0.8.1` | [Completion cap, safe provider failures, and validation ownership](releases.md#plan-toolkit-0-8-1) | Protocol-aware completion cap, canonical provider configuration, bounded provider-failure projection, privacy and approval invariants, protected validation deduplication, feature merge, development artifact verification, and stable-delivery handoff. | | `v0.8.0` | [Remediation threads, GitLab commands, and documentation](releases.md#plan-toolkit-0-8-0) | Policy-v2 verified remediation history, context-store v2, provider-neutral forge views, exact live-username commands, environment cleanup, mode-oriented examples, OCR 1.9.10, 85% coverage and risk-group gates, protected feature merge, explicit enriched-qualification waiver, and stable-delivery handoff. | diff --git a/docs/engineering/execution_history/releases.md b/docs/engineering/execution_history/releases.md index 14962cf..6274df4 100644 --- a/docs/engineering/execution_history/releases.md +++ b/docs/engineering/execution_history/releases.md @@ -2,6 +2,82 @@ This archive preserves completed execution plans moved out of the active registry; the release index associates each plan with the stable tag or release cycle it supported. `PLANS.md` remains the source for active or blocked repository work; historical receipts here remain part of the audit trail. + + +## Toolkit 0.8.3 โ€” OCR boundaries and review tool-usage visibility + +Status: repository complete; external stable delivery pending +Release classification: `release-required` +Target stable version: `0.8.3` +Repository completion date: 2026-08-26 + +### Goal and delivered scope + +Deliver the priority 0.8.3 hotfix without changing OCR 1.10.0, DLP, receipt v5, +posting transactions, severity, findings, telemetry ownership, or automatic +approval. Compatibility publication now follows the actual qualification +outcome, recovers through a closed status independently of invalid support +metadata, and publishes its bounded issue/artifact before restoring a red job. +The GitLab example delegates max-tools ownership to installed OCR with sentinel +`0`; exact behavior-based qualification distinguishes OCR's reported +normalization target `50` from its template-owned effective loop value `100`. + +The existing GitLab `all OCR tool calls` line now shows every non-zero admitted +counter from the fixed nine-tool review set, sorted by count and name. Those +counts describe activity only: OCR 1.10.0 does not report per-tool token use, +and raw arguments, results, paths, IDs, unknown names, and dynamic external MCP +tool names remain private. Both macOS endpoint jobs continue to run as advisory +diagnostics; all Linux, coverage, quality, security, dependency, package, and +CodeQL gates remain release-blocking. + +### Decisions and non-claims + +- Issues #139, #140, #142, and #143 are the complete tracked release set. +- OCR remains checksum-pinned to 1.10.0; current numeric behavior belongs to the + installed OCR and is qualified behaviorally rather than copied into toolkit + configuration constants. +- A recognized max-tools normalization becomes a toolkit-authored operator + notice only. Raw stderr and the notice do not enter results, DLP, receipts, + telemetry, lifecycle commands, findings, severity, or approval decisions. +- No local real-LLM/provider review or separate qualification receipt was run or + claimed. Deterministic exact-OCR no-model probes and a controlled local peer + cover the process boundary; protected hosted and release gates cover delivery. +- macOS support metadata is unchanged. Advisory endpoint failures remain visible + for follow-up but cannot delay a Linux-priority hotfix release. + +### Repository and hosted evidence + +- Final feature head `6520a53db6b4f9d907735456be43e0b17ec296af` + passed all 13 hosted checks with no review threads. PR #141 was squash-merged + as verified commit `74b3f46f72f1d6231c44cc39ca12f732a46da706`; + reviewed and merged tree are both + `6ab22194ecb44329a7b89be918c4c5afb8f8daf7`. +- The final local gate passed 1,275 tests plus 324 subtests at 86.35% combined + branch coverage. Risk groups passed at 84%, 82%, 86%, and 87% against floors + 80%, 80%, 85%, and 85%; Ruff, strict MyPy, Bandit, Gitleaks, lock validation, + OCR manifest validation, Towncrier draft, and diff review also passed. +- Development workflow run 32946899220 published `0.8.3.dev72`. Independent + TestPyPI readback matched wheel SHA-256 + `892c8662a1e797940b1fd7587fcde7ba8e2c0e8bee437f71c3592bdafdce745a` + and sdist SHA-256 + `920264937ba787341e468121d52e83cd945f669c4995eb72f1612d0adb49df00`; + provenance and clean wheel/sdist installs passed. +- The live protected-main ruleset retains ten required Linux/non-platform + contexts and omits only the two macOS endpoint contexts. Workflow source keeps + three Linux jobs blocking and both macOS endpoint jobs running with explicit + advisory status. + +### Stable delivery handoff + +The release PR is the final repository mutation. External closure remains +pending until its exact reviewed head is squash-merged and the stable workflow +is independently reconciled across TestPyPI, PyPI, workflow artifacts, and the +immutable GitHub Release. Closure requires byte/hash equality, PEP 740 +provenance and GitHub attestations, annotated `v0.8.3` tag readback, Python +3.12-3.14 wheel/sdist install and CLI smoke, Actions-owned receipt comments, +closed #139/#140/#142/#143, closed milestone `v0.8.3`, and clean synchronized +local `main`. + ## Repository-Complete Plan: v0.8.2 OCR 1.10.0 and review effort diff --git a/examples/gitlab/ocr-review.gitlab-ci.yml b/examples/gitlab/ocr-review.gitlab-ci.yml index 8210d92..eb91c13 100644 --- a/examples/gitlab/ocr-review.gitlab-ci.yml +++ b/examples/gitlab/ocr-review.gitlab-ci.yml @@ -7,7 +7,7 @@ default: variables: OCR_VERSION: "v1.10.0" - OCR_TOOLKIT_VERSION: "0.8.2" + OCR_TOOLKIT_VERSION: "0.8.3" OCR_TOOLKIT_CHECKSUMS_URL: "https://github.com/xeonvs/open-code-review-toolkit/releases/download/v${OCR_TOOLKIT_VERSION}/SHA256SUMS" OCR_SHA256: "f8f99ea071bed77dbcaa15fdd2083287bb8ae408d5928b3943ebe0788d191b6b" OCR_POST_MODE: "draft" diff --git a/tests/test_operations_docs.py b/tests/test_operations_docs.py index 7d5eb6b..2d77606 100644 --- a/tests/test_operations_docs.py +++ b/tests/test_operations_docs.py @@ -473,10 +473,10 @@ def test_ocr_compatibility_workflow_is_bounded_and_protected() -> None: for contract in ( "OCR 1.9.9 โ€” inherited predecessor", "OCR 1.9.10 โ€” toolkit 0.8.0 target and 0.8.2 predecessor", - "OCR 1.10.0 โ€” toolkit 0.8.2 target", + "OCR 1.10.0 โ€” toolkit 0.8.2 and 0.8.3 target", "ocr.llm-retry-report/v1", "not toolkit telemetry", - "Deploy toolkit 0.8.2 directly with OCR 1.10.0", + "Deploy toolkit 0.8.2 or 0.8.3 directly with OCR 1.10.0", "max_completion_tokens=16384", "do not install OCR 1.9.10 as an intermediate step", ): diff --git a/tests/test_release_notes.py b/tests/test_release_notes.py index 92e9b71..eb95a1f 100644 --- a/tests/test_release_notes.py +++ b/tests/test_release_notes.py @@ -164,6 +164,24 @@ def test_082_release_notes_are_actionable_for_people_and_deployment_agents() -> assert phrase in notes +def test_083_release_notes_cover_hotfix_activity_and_release_gates() -> None: + """Keep the hotfix delta actionable without overstating telemetry or macOS gates.""" + + changelog = (ROOT / "CHANGELOG.md").read_text(encoding="utf-8") + notes = release.release_notes(changelog, "0.8.3") + + for phrase in ( + "actual qualification outcome", + "sentinel `0`", + "template-owned tool-loop value", + "all OCR tool calls", + "does not report per-tool token consumption", + "macOS endpoint CI jobs", + "Linux, coverage, quality, security, dependency, package, and CodeQL", + ): + assert phrase in notes + + def test_extracts_only_the_exact_release_section() -> None: changelog = "# Changelog\n\n## 0.2.0 - later\n\nnew\n\n## 0.1.0 - now\n\nfirst\n"