From 3f692e6e6d8cefad8cafb80b4ca72eff8e83787b Mon Sep 17 00:00:00 2001 From: xeonvs <11463419+xeonvs@users.noreply.github.com> Date: Fri, 23 Oct 2026 15:22:19 +0200 Subject: [PATCH] chore: prepare v0.13.0 release --- .next-version | 2 +- .release-metadata.json | 10 +- .release-source-date-epoch | 2 +- .release-version | 2 +- CHANGELOG.md | 16 ++ PLANS.md | 170 +--------------- changelog.d/264.feature.md | 4 - changelog.d/266.security.md | 1 - docs/codex/ENGINEERING_WORKFLOW_STATE.yaml | 2 +- docs/configuration.md | 2 +- docs/engineering/execution_history/README.md | 3 +- ...lt-policy-fallback-for-single-mr-review.md | 185 ++++++++++++++++++ .../execution_history/plans/README.md | 2 +- docs/release.md | 6 +- examples/gitlab/ocr-review.gitlab-ci.yml | 2 +- tests/test_integration_contracts.py | 10 +- tests/test_operations_docs.py | 38 ++-- 17 files changed, 247 insertions(+), 210 deletions(-) delete mode 100644 changelog.d/264.feature.md delete mode 100644 changelog.d/266.security.md create mode 100644 docs/engineering/execution_history/plans/2026-10-23-toolkit-0-13-0-protected-default-policy-fallback-for-single-mr-review.md diff --git a/.next-version b/.next-version index 54d1a4f2..a803cc22 100644 --- a/.next-version +++ b/.next-version @@ -1 +1 @@ -0.13.0 +0.14.0 diff --git a/.release-metadata.json b/.release-metadata.json index 59b67f36..1b64e22c 100644 --- a/.release-metadata.json +++ b/.release-metadata.json @@ -1,13 +1,7 @@ { "schema_version": "ocr-toolkit.release-authorization/v1", - "version": "0.12.1", + "version": "0.13.0", "issues": [ - 248, - 249, - 250, - 251, - 252, - 253, - 258 + 264 ] } diff --git a/.release-source-date-epoch b/.release-source-date-epoch index 0f1f1726..c56a1730 100644 --- a/.release-source-date-epoch +++ b/.release-source-date-epoch @@ -1 +1 @@ -1792673087 +1792761040 diff --git a/.release-version b/.release-version index 34a83616..54d1a4f2 100644 --- a/.release-version +++ b/.release-version @@ -1 +1 @@ -0.12.1 +0.13.0 diff --git a/CHANGELOG.md b/CHANGELOG.md index 8bbd84a7..a2e789d3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,19 @@ +## 0.13.0 - 2026-10-23 + +### 🚀 Features + +- GitLab MR reviews now default `OCR_GITLAB_TARGET_PROTECTION_MODE` from `required` to `auto`: when the actual target is unprotected, the toolkit can use the same project's protected default branch for review rules and governed context while keeping the result comment-only. + + - Changed: current MR reviews require a detached pipeline and bind the checked-out source, GitLab diff version, actual target, and policy commit in receipt v11; stale or unverifiable results stop before publication and approval. + - Migration: use `required` to retain protected-target-only admission, or `unprotected` for the previous limited comment-only path. Existing `--local` reviews remain standalone and do not require GitLab MR variables. + + ([#264](https://github.com/xeonvs/open-code-review-toolkit/issues/264)) + +### Security + +- Require OpenTelemetry API 1.45.1 or newer to exclude vulnerable tracestate parsing in MCP’s dependency graph. ([#266](https://github.com/xeonvs/open-code-review-toolkit/issues/266)) + + ## 0.12.1 - 2026-10-22 ### 🐛 Bug Fixes diff --git a/PLANS.md b/PLANS.md index 07567d5b..cce9cdfa 100644 --- a/PLANS.md +++ b/PLANS.md @@ -4,172 +4,6 @@ Use this file for active or blocked repository work. Update it before implementa before handoff or commit. Completed stable plans are indexed in [the execution-history archive](docs/engineering/execution_history/README.md). -## Active Plan: Toolkit 0.13.0 protected default-policy fallback for single-MR review +## Recently Completed -plan_schema_version: 2 -Status: active -Owner: root -Last Updated: 2026-10-23 -Release classification: #264 `release-required`, target v0.13.0; #265 `no-release` planning and the requested harness maintenance are separate logical changes in the same feature PR. - -### Goal - -Implement #264 without conflating the actual MR code target with protected policy authority, record the conditional #265 follow-up without activating chain review, and deliver, independently verify, and reconcile the stable v0.13.0 release through the protected repository workflow. - -### Plan Origin - -`plan_mode_approved` - -### Requested Scope - -The feature PR contains #264 implementation and public-contract updates plus a separate logical documentation commit for #265. Its first commit contains only this reviewed plan. Self-review every subsequent logical commit. Before the final feature push, run Codex Security on the changed range, then one real local toolkit/OCR review through the documented private-artifact path and fix admitted findings. Audit project documentation, agent instructions, and routes; correct any findings in a separate commit before final reviews. Use the protected feature PR, development artifact verification, protected release PR, stable publication/receipt, issue closure, and site check after actual publication. In the release PR, archive the complete repository plan and reset `PLANS.md`; after publication, reconcile external facts against the immutable receipt and issue comments without another repository PR. Clean obsolete completed-run GitHub Actions artifacts and superseded caches without touching published Release assets or active-run inputs. Do not run additional checks on another host or environment. -The owner later requested an Astra harness/process audit. Its bounded current-branch follow-up removes one duplicate setup shared by two negative installed-artifact probes and preserves the failing command's exit status in the quality wrapper; keep both wheel/sdist behavioral cases and independent published-artifact gates. Capture per-test durations in the next required full quality run rather than adding a separate heavy measurement run. -After the feature PR's dependency-audit job identified vulnerable `opentelemetry-api` 1.44.0 in the committed lock, the owner requested a local pre-push dependency audit analogous to the Gitleaks gate. Remediate the package floor and lock, make local and hosted audit use one script and one pinned uv version, preserve local environment isolation and failure status, and validate the corrected boundary without another model review or redundant full quality run. - -### Requirement Traceability - -| Requirement | Outcome | Queue | Status | -| --- | --- | --- | --- | -| REQ-001 | Absent protection setting selects `auto`; explicit `required` and `unprotected`, malformed values, local entry point, and existing operator-file contracts retain their stated behavior | WQ-02, WQ-05 | done | -| REQ-002 | Authenticate same-project MR and bind source H, actual target T, validated diff base/version B, and invocation; qualify detached, merged-result, and merge-train forms without synthetic-source confusion | WQ-02, WQ-03 | done | -| REQ-003 | For an actually unprotected target, select the same project's protected default branch and immutable P; enforce rule provenance and preserve context/federation controls without pretending the target is protected | WQ-03, WQ-04 | done | -| REQ-004 | Version result/receipt identity and capability decisions; reject old/forged contradictions, retain supported historical readback, and render truthful provenance and comment-only outcomes | WQ-04, WQ-05 | done | -| REQ-005 | Revalidate code and authority before publication and approval; stale or unverifiable identity fails closed, bounded policy-only fast-forward remains pinned to P, and unprotected targets never receive new approval | WQ-05 | done | -| REQ-006 | Preserve early exits, evidence applicability, DLP, current-MR context, ordinary outcomes, previous-review lifecycle, and controlled boundary budgets; expose actual target T as distinct untrusted code evidence when B and P differ | WQ-03, WQ-04, WQ-05 | done | -| REQ-007 | Update public configuration, GitLab examples, context, operations, security threat model, decision flow, strategy/roadmap, README, evidence matrix, and migration/changelog entry coherently | WQ-06, WQ-08 | done | -| REQ-008 | Record #265 as inactive BL-025 with its durable issue links, full backlog fields, per-variant #264 dependencies, A–F alternatives, relationship shapes, request surfaces, activation authority, validation and non-claims; reconcile the merged entry back to #265 without runtime or public setting | WQ-07, WQ-09 | in_progress | -| REQ-009 | Review every commit; run applicable tests, secret scan, security diff scan, real local OCR review, and protected feature PR checks | WQ-01, WQ-02–WQ-09 | pending | -| REQ-010 | Publish and independently read back v0.13.0 distributions, provenance, attestation, tag, immutable Release, receipt, tracked issue/milestone, and post-release site notification | WQ-10, WQ-11 | pending | -| REQ-011 | Archive the repository-complete plan and reset `PLANS.md` in the protected release PR; independently reconcile later external facts against the immutable receipt and issue comments without another PR | WQ-10, WQ-12 | pending | -| REQ-012 | Reclaim Actions storage from obsolete completed-run artifacts and superseded caches, with before/after readback and retained release/current-run evidence | WQ-13 | done | -| REQ-013 | Add meaningful boundary coverage in touched Python modules and report final affected-file coverage; do not claim a before/after comparison from an incomplete baseline | WQ-02–WQ-05, WQ-14 | done | -| REQ-014 | Reduce duplicate installed-artifact negative-probe setup, preserve exact quality failure exit status, and record timing/process evidence without weakening wheel/sdist or registry gates | WQ-14 | done | -| REQ-015 | Align this active plan and future archive ownership with the installed engineering-workflow lifecycle without rewriting the consolidated historical release archive; keep release and development instructions consistent and avoid a duplicate full quality run for documentation-only changes | WQ-15 | done | -| REQ-016 | Remediate the current `opentelemetry-api` audit finding and require the same fail-closed installed-dependency audit locally before each push and in hosted security CI | WQ-09 | in_progress | - -### Explicit Non-Goals - -No related-MR discovery, chain/integration review, merge orchestration, source-branch policy bootstrap, fork/cross-project authority, new CI variable or policy field, second model pass, direct external MCP passthrough, approval revocation, downstream-project mutation, or new public command for #265. No separate host QA. Actual target protection is not a coverage score, and a successful current-MR review does not prove a parent or future integration. -Do not drop wheel or sdist packaging, remove the existing installed local-review scenarios, or repeat full tests in the release publication gate to optimize this task. Matrix reduction awaits measured scenario timing and an independent maintenance decision. - -### Constraints - -- GitLab acquisition is authenticated, bounded, and same-project; missing or contradictory source/target/project, diff, branch protection, default metadata, or Git objects fail with explicit diagnostics, not inferred fallback. -- `B..H` is the current MR delta. `B != T` is valid if the authenticated MR diff identity is coherent. Never substitute `P..H`, `T..H`, synthetic `CI_COMMIT_SHA`, or unrelated CI evidence. Preserve B/H deltas while exposing T as a separate bounded, untrusted code snapshot; T content never becomes P authority. -- Capture actual target branch/head/protection and policy project/branch/P/protection separately. Only a protected authority may supply rules, context policy and eligible guidance; changed feature-branch material remains untrusted evidence. External absolute or omitted rule forms cannot claim P provenance. -- Preserve `off|metadata|enriched`, governed registry-v2 admission and budget gates, same-revision evidence, accepted-decision applicability, DLP, immutable Git isolation, existing setup-pending/two-MR onboarding, and terminal/stale/no-change lifecycle boundaries. -- Recheck the bound code tuple, authority, and present CI job identity before each provider write. Policy-only advancement is acceptable only with bounded proof of same protected branch and ancestry; keep captured P. Changed default/protection, rewrite, missing authority, cross-job handoff, or unverifiable ancestry fail closed. Read-before-write retains a residual provider race. -- An actually unprotected target is always comment-only, including when `OCR_AUTO_APPROVE=true`; prior bot approvals may remain and are not revoked. Protected targets keep their own policy and approval gates. -- Use only synthetic/private-safe examples and artifacts. Follow signed, linear protected PR and trusted-base release authorization; no manual mutation of immutable release objects. - -### Inputs And Sources - -- Live [#264](https://github.com/xeonvs/open-code-review-toolkit/issues/264) (updated 2026-10-23 08:52 UTC) and [#265](https://github.com/xeonvs/open-code-review-toolkit/issues/265) (updated 08:31 UTC), including acceptance lists; GitLab's official MR/version, project, CI-variable, merged-results and merge-train API documentation. -- Current `main` baseline `b8786e7`, stable `.release-version=0.12.1`, next `.next-version=0.13.0`, empty active plan, and the completed v0.12.1 archive. -- Canonical owners: `AGENTS.md`, `docs/engineering/project_principles.md`, `docs/development.md`, `docs/release.md`, `docs/review-decision-flow.md`, `docs/review-context.md`, `docs/engineering/toolkit_strategy.md`, `ROADMAP.md`, `docs/codex/TASKS_BACKLOG.md`, and `docs/engineering/test_evidence_matrix.md`. - -### User Decisions And Answers - -The owner selected a full stable v0.13.0 release after #264 and chose one feature PR containing #265 as a separate logical commit. The owner requested the previous release's plan-first, self-review, security then local OCR review, protected PR, artifact/receipt, site-after-release and clean plan closure sequence. The root agent must switch to the feature branch; #265 remains planning-only and does not itself authorize a release. -The owner additionally requested cleanup of GitHub Actions run artifacts because storage is scarce; this is `no-release` operational work. -The owner also requested regular coverage improvement in touched files; focus on behavior and failure branches rather than tests that only reproduce an implementation. -The owner requested a separate Astra agent to audit harness duplication and process, then apply justified corrections. This scoped harness maintenance is `no-release` by itself and does not add another release trigger or publication job. -The owner later requested that the release PR return `PLANS.md` to its template state and that external readback close the work without a post-release repository PR. The release archive must describe publication as pending at merge; the immutable receipt and Actions-owned issue comments carry verified external facts afterward. The release workflow and validation contracts must be updated in the release branch before publication so they do not require the old closure PR; the guide is aligned in WQ-15. - -### Completed Baseline State - -v0.12.1 is published and externally reconciled; prior release and internal follow-up issues are closed. `main` was clean and synchronized with `origin/main` at `b8786e7`. Both current issues are open. `feature/264-auto-policy-0.13.0` was created from that baseline; its first signed commit contains only this plan and draft feature PR [#266](https://github.com/xeonvs/open-code-review-toolkit/pull/266) is open. Milestone v0.13.0 tracks #264 only. At activation no feature implementation existed. BL-024 is historical, so BL-025 is the next unused backlog identifier. - -### Current Work Queue - -| Queue | Requirements | Exit evidence | Status | -| --- | --- | --- | --- | -| WQ-01 | REQ-009 | Review and commit only this plan; establish goal, milestone and feature PR identity | `done` | -| WQ-02 | REQ-001, REQ-002, REQ-009, REQ-013 | Provider/config/CI identity changes and production-boundary tests; self-reviewed commit | `done` | -| WQ-03 | REQ-002, REQ-003, REQ-006, REQ-009, REQ-013 | Immutable diff/authority/rule acquisition, distinct target T evidence/readback and applicability tests; self-reviewed commit | `done` | -| WQ-04 | REQ-003, REQ-004, REQ-006, REQ-009, REQ-013 | Capability/context/federation, receipt/result v11 and hostile readback tests; self-reviewed commit | `done` | -| WQ-05 | REQ-001, REQ-004, REQ-005, REQ-006, REQ-009, REQ-013 | Full-identity freshness at current-result and static-note writes, publication/approval/draft and cleanup boundaries, receipt-less error isolation, cross-run private-artifact isolation, and local-entry tests; self-reviewed commit | `done` | -| WQ-06 | REQ-007, REQ-009 | Public contracts, examples, threat model, decision flow, changelog; self-reviewed commit | `done` | -| WQ-07 | REQ-008, REQ-009 | Self-contained BL-025 with Source #265 and reference #264, status/theme/prerequisites/trigger/scope/deliverables/acceptance/exclusions/validation/future release classification; per-variant dependencies, A–F coverage, graph shapes and request/publication trade-offs; aligned strategy/roadmap and self-reviewed separate commit | `done` | -| WQ-08 | REQ-007, REQ-009 | Documentation/instruction/route audit, distinct correction commit, focused documentation checks and valid instruction contract | `done` | -| WQ-14 | REQ-014, REQ-009, REQ-013 | Astra-backed installed negative-probe setup and quality exit-status corrections, focused tests, docs, timing in the next full quality gate, separate self-reviewed commit | `done` | -| WQ-15 | REQ-015, REQ-009 | Adopt the canonical active-plan headings and queue statuses, add a dedicated per-plan archive index, align workflow state and documentation, pass lifecycle/route/documentation checks without repeating the full quality gate, and self-review the commit | `done` | -| WQ-09 | REQ-008, REQ-009, REQ-016 | Codex Security scan, corrected real local toolkit/OCR review, finding fixes, patched dependency and a shared local/CI pre-push audit gate with focused verification, then final feature PR checks/merge; mark verified acceptance checkboxes in #264/#265, link the merged BL-025 entry in #265 and record selected/deferred/rejected variants there | `in_progress` | -| WQ-10 | REQ-010 | Verified deterministic TestPyPI development wheel and sdist, release PR repository prep and protected checks/merge | `pending` | -| WQ-11 | REQ-010 | Stable TestPyPI/PyPI, provenance, attestation, immutable release/receipt, issue/milestone and real site readback | `pending` | -| WQ-12 | REQ-011 | Independently verify exact external receipts, issue/milestone and site state; close the goal with `PLANS.md` already clean from the release PR and no post-release repository change | `pending` | -| WQ-13 | REQ-012 | Inventory completed-run artifacts/cache, delete only obsolete bytes, retain current PR and latest release evidence, verify remaining inventory and record reclaimed size | `done` | - -### Locked Decisions - -Use `auto` as the absent-setting default and retain explicit modes. Use closed provider-neutral authority/capability identity with GitLab acquisition behind the adapter. Receipt v11 distinguishes code target from policy authority; historical v9/v10 remain readback-only under their original invariants, never guessed into a new profile. Choose clear rejection for unsupported pipeline or rule forms. Keep #265 in BL-025 only until separately activated by owner approval. Track only #264 in the v0.13.0 release issue set; close #265 through its feature PR after its planning deliverable is reviewed. - -### Verification - -- Focused parser/provider, real temporary Git and bounded local HTTP, result/receipt hostile-readback, context/federation, posting/approval, lifecycle and source-identity tests for every #264 acceptance branch; preserve exact owner entry points and note test doubles beyond them. -- A B!=T!=P evidence fixture must prove T-only implementation facts are available as untrusted target evidence without changing B..H deltas, policy authority, historical store readback or bounded admission. -- Public example/preflight and `--local` contract tests, clean installed wheel/sdist runtime probes, one actual OCR review for changed model-visible behavior, plus `scripts/quality.sh check`, `scripts/gitleaks.sh`, instruction-contract lint if routes change, documentation links/semantic audit and final scoped diff review. -- Record final per-file coverage for touched Python modules, add meaningful branch/boundary tests where coverage is weak, and compare only complete aggregate runs; the available pre-feature per-file baseline is incomplete and cannot support a growth claim. -- Codex Security diff scan after implementation and before final feature push; then a correctly invoked local toolkit/OCR review to completion with private physical output path, terminal status, report and findings readback. Fix admitted findings with focused regression and self-review; repeat a full model scan only for incomplete coverage or a materially new unreviewed boundary. -- Exact required protected feature/release PR checks; stable workflow's independent hash, registry provenance, supported-Python installed smoke, immutable receipt readback and post-publication external verification. Check the live site only after release notification/deployment. - -### Latest Validation Results - -Plan-only signed commit `d616e98` contains only `PLANS.md` and passed `git diff --check`; `scripts/gitleaks.sh --tree` and the reachable-range scan passed before its push. Draft PR #266 exists, and #264 is in milestone v0.13.0 while #265 remains outside it. At that plan-only point no feature test or review gate had run. -GitHub Actions inventory at 2026-10-23 shows 42 artifacts totaling 14,613,655 bytes and four caches totaling 142,839,380 bytes. The current draft-PR artifact is 7,171 bytes; the completed v0.12.1 release and its development-build artifact remain useful for recovery/readback. Two superseded uv caches account for 89,449,983 bytes. All 100 most recent workflow runs are completed. -All 195 listed workflow runs were confirmed completed. Deleted 21 obsolete distribution artifacts and two superseded uv caches. Readback lists 21 remaining artifacts totaling 1,422,439 bytes and two retained caches totaling 53,389,397 bytes, so listed stored bytes fell by 102,641,199. The current PR SARIF, latest release/development distributions, and immutable v0.12.1 Release assets remain; GitHub's cache-usage aggregate briefly lagged the cache listing after deletion. -Focused provider tests pass (68 tests, 2026-10-23). Review of the B!=T!=P execution path found a real evidence gap: T was fetched and stored in the receipt but not available through evidence MCP. WQ-03 now explicitly includes a versioned, bounded target evidence snapshot. The pre-change complete quality log from 2026-10-22 provides a comparable baseline for affected-file coverage; final numbers remain pending. -Signed self-reviewed implementation commits: `cd74ac4` binds detached MR CI, same-project provider and target/policy snapshot; `a1d056a` adds bounded target T evidence v5 and protected-P ancestry support; the following execution commit binds diagnostics and receipt v11, including the local-policy collection regression fix. Focused provider/local tests: 148 passed; evidence/freshness tests: 201 passed; execution/receipt/docs-contract tests: 254 passed. Full quality, security and local OCR gates remain pending until documentation is complete. Review of posting found additional mid-publication freshness transitions now being corrected in WQ-05. -Signed self-reviewed planning commit `76a1c3a` records conditional BL-025 for #265 and its roadmap placement without runtime changes or a release claim. Its scoped diff check passed. #265 still needs issue-body reconciliation after the feature PR merges. -WQ-05 focused source and boundary suites passed with 686 tests and 299 subtests after the CI-job handoff and current-version-contract additions. Ruff format/check, mypy across 132 source files, and diff whitespace checks passed. A second independent seam audit found the review-to-post interval in a shared checkout; receipt and preview/setup status now bind the supplied GitLab job ID, code 75 prevents a losing review from adopting another run's status, and the example uses job-specific output paths. Production GitLab uses one review/post pair per CI job. Full quality and final security/OCR reviews remain pending until WQ-06/WQ-08 documentation is committed. -Signed self-reviewed WQ-05 commit `d5bc468` contains the posting, cross-run, current-version contract and regression changes. WQ-06 public documentation now explains v11, default `auto`, B/H/T/P, job-specific handoff, local private paths and the no-note failure policy. The public GitLab example omits the selector so its still-published wheel pin remains valid until the release PR advances it; the new toolkit then supplies the `auto` default. The 51 focused documentation/example contracts passed. -Signed self-reviewed WQ-06 commit `58d29d3` contains the public docs, examples and changelog. Signed self-reviewed commit `0b416c8` makes the historical v9/v10/v11 nested-schema mapping explicit, so a future v12 cannot inherit a predecessor's federation or publication schema by fallback; 129 receipt/approval/freshness tests and 94 subtests passed. The WQ-08 documentation/instruction audit corrected context and federation ownership routes, engineering contracts and example links; the instruction contract is valid, the 51 focused documentation contracts pass, and full quality and final reviews remain pending. -The first full quality attempt stopped at a single Ruff formatting defect in the public-example contract test; it was corrected in amended documentation commit `ae83977`. The next full pytest/coverage run reached 86.36% total coverage and 2270 passing tests, but 14 tests still asserted obsolete local-status, private-error-note or historical-receipt publication behavior. Six affected test modules now assert the current no-write/no-status boundaries and retain late debug/progress coverage; 108 focused tests passed with three qualified skips before the successful complete run below. -Astra's read-only harness audit confirmed #260 is closed and the expensive installed-artifact suite already runs on one Ubuntu/Python 3.12 CI leg; other legs start in parallel, while stable publication verifies new artifacts without repeating full pytest. Different observed CI runs spanned 13m24s and 4m22s, which is directional evidence rather than a controlled benchmark. The remaining duplicate was two negative probes creating equivalent clean no-dependency environments. The quality wrapper also reduced an underlying failing command's exit status to 1 before the WQ-14 fix. -The bounded WQ-14 patch now shares one module-scoped wheel-only interpreter between both read-only negative dependency probes, preserves their distinct PATH/cwd assertions, and makes `scripts/quality.sh` propagate failure statuses. The fake-uv regression checks exit codes 2, 7 and 130 plus stop-before-coverage behavior. All 12 focused harness tests pass in 2.14 seconds; 40 focused documentation/environment tests, repository-wide Ruff check/format, instruction-contract lint and whitespace checks pass. The prior failed quality log is retained in a private task archive outside the repository. -The complete local quality gate now passes: 2288 tests, five qualified skips and 357 subtests in 295.67 seconds, with 86.47% aggregate line/branch coverage. The installed wheel/sdist MCP scenario accounts for 157.09 seconds; the shared negative-probe setup takes 1.06 seconds, and the independent wheel/sdist behavioral cases remain intact. Current changed-file coverage includes 100% for `posting/freshness.py` and `review_identity.py`, 88.02% for `review_receipt.py`, 86.74% for `providers/gitlab.py`, and 80.14% for `posting/workflow.py`. The available pre-change JSON was collected from an incomplete test run (70.24%) and is not a valid before/after baseline; do not report it as coverage growth. A public-tree secret scan passes. Astra's process recommendation is captured in the bounded harness commit; the remaining expensive integration matrix needs a separately measured follow-up before any reduction. -Codex Security completed a diff scan of `b8786e73783fb9a9b2572da6a409a456191f2186..e6ab0ca87161a38389d63d933da03151a6448912` with complete coverage of 25 changed source files and zero findings. The scan reported the existing read-before-write provider race as a residual risk, not a validated finding. Later bounded scans cover changed runtime deltas below; none of these reports is represented as coverage of subsequent correction commits. -The first local preflight lacked an authentication-mode selection and required API model; a later candidate command used local-unsupported `--background-file` and was rejected before OCR ran. The corrected native ChatGPT invocation used checksum-verified OCR 1.13.3 and physical private outputs. It exited zero, delivered JSON and Markdown, completed 29/29 selected items with DLP admission and seven reconciled mandatory evidence calls, and reported one high bug in old-review cleanup after the first deletion. Commit `eeca61a` retains current-run comments after a destructive cleanup attempt and stops on unconfirmed deletes; 95 posting/freshness tests pass. Separate instruction/contract commit `08f0a70` adds the launch guard and truthful partial-cleanup diagram; 51 documentation tests and instruction-contract lint pass. -The corrected head then passed the complete quality gate: 2290 tests, five skips and 357 subtests in 296.21 seconds, with 86% rounded aggregate coverage and 81% rounded posting-workflow coverage. A second Codex Security scan covered the changed runtime delta from `e6ab0ca` through `e60108f` and returned zero validated findings. The second local OCR 1.13.3 review exited zero with physical private JSON/Markdown, 29/29 completed, zero failed/waived/reused, eight reconciled evidence calls and DLP admission. One auxiliary model file-read used a nonexistent path; selected-item coverage remained complete. It reported three medium bugs: target-only tree-limit abort, setup-note rollback after partial old cleanup, and unpublished draft carry-forward. The optional T limit correction is `ee2f5d2`; unreadable T identity and non-budget read errors still fail closed. Posting correction `e8e2d3d` retains replacement notes after a cleanup attempt, attempts removal of definitely unattempted draft IDs and excludes pending drafts from published-finding fingerprints. Instruction/contract update `c8017d2` records exact local result verification and the partial-state boundaries. The focused evidence/posting/docs suite passed 344 tests and 205 subtests; types, Ruff, instruction-contract lint, and staged secret checks passed. The generic `plan_lifecycle.py check` exposed this repository's customized active heading and consolidated historical archive; WQ-15 migrates only future per-plan ownership while retaining legacy history. -The complete quality gate on corrected runtime head `bb0c9c4` passed on 2026-10-23: 2297 tests, five qualified skips and 357 subtests in 301.94 seconds, with 86.52% aggregate coverage. The installed wheel/sdist MCP test took 158.27 seconds. WQ-15 changes only plan, workflow state, navigation, release/development guidance, and its documentation contract test; no runtime or product test code changed. -The WQ-15 migration uses the installed plan schema without changing the consolidated historical archive. `plan_lifecycle.py check`, instruction-contract lint, 45 focused documentation/integration tests, Ruff on the touched test file, documentation navigation with zero errors or warnings, public-tree secret scan, and `git diff --check` pass on 2026-10-23. The full quality gate was not repeated for this bounded documentation delta. -Codex Security's third diff scan covered the three runtime files changed in `e60108f..27e489a` and completed with zero findings. The third local OCR 1.13.3 review at `27e489a` exited zero, delivered physical private JSON and Markdown, completed 31/31 selected items with zero failed/waived/reused, reconciled eight mandatory evidence calls, and passed DLP. Two auxiliary file reads failed but did not reduce selected-item coverage. It found two medium bugs: the documented `--local --preserve-private-artifacts` path was unreachable, and a newly fetched protected policy tip could be a shallow boundary that hid a direct fast-forward. Signed self-reviewed commit `2385854` enables explicit local private retention with a DLP-projected report while retaining a non-postable marked raw result; direct provider diagnostic finalization still produces no successful report. Signed self-reviewed commit `57ddf56` retries shallow ancestry proof through one depth-128 history fetch, retains exact immutable P and fail-closed behavior, and avoids collecting unbounded fetch output. A real remote-after-checkout regression and local/diagnostic tests pass; the affected focused suite has 189 passing tests. The documentation, decision flow, evidence matrix and review-efficiency instruction changes are included in this separate logical commit. No fourth full security or OCR review is justified by these corrections; their focused regressions and the completed quality gate below cover the final runtime handoff. -The completed final local quality gate passes on the corrected runtime and prepared documentation: 2300 tests, five qualified skips and 357 subtests in 300.82 seconds, with 86.54% aggregate coverage. Compared with the preceding complete run on `bb0c9c4`, aggregate coverage is 0.02 percentage points higher; this is not a claim about the unavailable pre-feature baseline. Affected-file final coverage is 100% for `posting/freshness.py`, 85% for `review_runner.py`, and 81% for `evidence/repository.py`. The plan lifecycle check, instruction-contract lint and documentation navigation check also pass, with zero navigation errors or warnings. Do not rerun the full gate for the final documentation-only evidence update. -The first hosted PR run passed every check except `dependency-audit`, which found `opentelemetry-api` 1.44.0 via MCP. The corrected lock resolves 1.45.1 under uv 0.13.4 without changing lock revision or unrelated packages. The shared local/CI audit script passes in its isolated environment with no known vulnerabilities; `pip check`, `uv lock --check`, 51 affected tests, repository-wide Ruff format check, instruction-contract lint, plan lifecycle check, and documentation navigation pass. The audit wrapper's focused tests prove exact CI pin agreement, isolated environment, fallback from the older installed uv, and preservation of sync/audit failure exit statuses. The prior full runtime and model reviews remain valid for unchanged runtime code; the narrow dependency/workflow change is verified by its focused tests and the next protected CI run. - -### Risks And Recovery - -GitLab diff/version and pipeline variants may require rejecting unsupported forms before model work; do not guess identity. Shallow Git history beyond the bounded retry may still prevent proving policy fast-forward; fail closed with actionable unavailable outcome. If protection/default selection or target changes during review, retain earlier valid publication and report stale. External publication or workflow state must be read back before retry; resume a failed authorized release through its documented exact-artifact recovery rather than republishing different bytes. Preserve private review artifacts until report and admitted findings are verified. - -### Resume Point - -WQ-09: run the local audit and secret/history checks on the committed correction before the feature push, then await protected PR checks and merge after they pass. The runtime quality gate and complete model reviews have finished; do not repeat them without a specific coverage gap. After feature merge, mark verified GitHub issue checkboxes. In the release branch, update workflow and validation contracts for same-PR plan closure before protected release checks. - -### Plan Fidelity Check - -- [x] #264 and #265 outcomes, non-goals, updated #264 identity/freshness additions, and user decisions map to REQ and ordered WQ items. -- [x] Release classification, 0.13.0 target, #265 no-release boundary and plan/closure ownership are explicit. -- [x] Each acceptance family has focused verification and production-boundary evidence; reviews, site timing, and external receipts have owners. -- [x] Risks, fail-closed recovery, immutable artifacts and first safe unfinished action are recorded. -- [x] The newly requested Actions storage cleanup has an independent `no-release` requirement and readback owner. -- [x] The later plan-format and bounded-validation request has a separate requirement, queue item, owner and first safe unfinished action. -- [x] The observed dependency-audit failure and requested local-before-push gate map to REQ-016 and WQ-09 without expanding model review scope. - -### Reconciliation Check - -- [x] This plan reflects the current issue bodies and clean `b8786e7` baseline at activation. -- [ ] Reconcile changed implementation, test, PR, release and external facts before their dependent milestones and final archive. - -### Closure Gate - -- [ ] Every in-scope requirement and queue item is done with final validation evidence. -- [ ] No issue, instruction, document, backlog or release state contradicts the delivered result. -- [ ] The protected release PR archives repository-complete work with external delivery pending and leaves no active plan; exact external receipts are independently verified after publication without another repository PR. - -### Post-Close Delivery - -Pending: feature and release PRs, stable artifacts, immutable receipt, tracked issue/milestone, site check and external readback. Completion requires their independent readback, not a local commit or green advisory job alone. - -### Handoff Notes - -Root owns `PLANS.md`, BL-025 status, commit sequencing, external writes and final synthesis. Delegated work must not close the plan or mutate shared plan state. At interruption, read this current plan and `git status`, then resume the first non-terminal WQ item without repeating side effects. +- [x] 2026-10-23: Completed Toolkit 0.13.0 protected default-policy fallback for single-MR review; [full archived plan](docs/engineering/execution_history/plans/2026-10-23-toolkit-0-13-0-protected-default-policy-fallback-for-single-mr-review.md). diff --git a/changelog.d/264.feature.md b/changelog.d/264.feature.md deleted file mode 100644 index 3b0cc57d..00000000 --- a/changelog.d/264.feature.md +++ /dev/null @@ -1,4 +0,0 @@ -GitLab MR reviews now default `OCR_GITLAB_TARGET_PROTECTION_MODE` from `required` to `auto`: when the actual target is unprotected, the toolkit can use the same project's protected default branch for review rules and governed context while keeping the result comment-only. - -- Changed: current MR reviews require a detached pipeline and bind the checked-out source, GitLab diff version, actual target, and policy commit in receipt v11; stale or unverifiable results stop before publication and approval. -- Migration: use `required` to retain protected-target-only admission, or `unprotected` for the previous limited comment-only path. Existing `--local` reviews remain standalone and do not require GitLab MR variables. diff --git a/changelog.d/266.security.md b/changelog.d/266.security.md deleted file mode 100644 index 7d4dc999..00000000 --- a/changelog.d/266.security.md +++ /dev/null @@ -1 +0,0 @@ -Require OpenTelemetry API 1.45.1 or newer to exclude vulnerable tracestate parsing in MCP’s dependency graph. diff --git a/docs/codex/ENGINEERING_WORKFLOW_STATE.yaml b/docs/codex/ENGINEERING_WORKFLOW_STATE.yaml index 5c7c4908..31192278 100644 --- a/docs/codex/ENGINEERING_WORKFLOW_STATE.yaml +++ b/docs/codex/ENGINEERING_WORKFLOW_STATE.yaml @@ -32,7 +32,7 @@ plan_archive_indexes: - docs/engineering/execution_history/README.md - docs/engineering/README.md - docs/README.md -active_plan: PLANS.md +active_plan: null runtime_agent_config_managed: true instruction_contract_version: 3 planning_contract_version: 2 diff --git a/docs/configuration.md b/docs/configuration.md index d011d8df..d690b1f4 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -158,7 +158,7 @@ These names belong to `examples/gitlab/ocr-review.gitlab-ci.yml`; they are shell | --- | --- | --- | --- | --- | | **`OCR_VERSION`** | Example pipeline | Yes | Qualified OCR pin for the example's toolkit release | Exact binary release pinned with its asset checksum in the [pipeline](../examples/gitlab/ocr-review.gitlab-ci.yml); not resolved dynamically. | | **`OCR_SHA256`** | Example pipeline | Yes | Manifest SHA-256 for `opencodereview-linux-amd64` | Exact digest pinned alongside `OCR_VERSION` in the pipeline; must belong to the same release entry. | -| **`OCR_TOOLKIT_VERSION`** | Example pipeline | Yes | `0.12.1` | Exact toolkit wheel release installed by the current published example; update this pin with the published release. | +| **`OCR_TOOLKIT_VERSION`** | Example pipeline | Yes | `0.13.0` | Exact toolkit wheel version selected by the example; advance this table and the example together in the release PR. | | **`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 153cf57e..90e6faa2 100644 --- a/docs/engineering/execution_history/README.md +++ b/docs/engineering/execution_history/README.md @@ -1,6 +1,6 @@ # Execution History Index -`PLANS.md` owns active or blocked repository work. This archive preserves completed plans so an agent can recover the decisions, validation evidence, merge receipts, hashes, and resume context behind a published toolkit version. It also retains the historical [review-context design checkpoint](review_context_design_checkpoint.md) (formerly `m5_context_contracts.md`) and [evidence migration matrix](evidence_migration_matrix.md); neither owns current runtime contracts. +`PLANS.md` owns active or blocked repository work. This archive preserves completed repository plans, their decisions, validation evidence and pre-publication handoffs. Historical entries may also include later merge receipts and hashes; current external delivery is verified through the immutable release receipt and Actions-owned issue comments. It also retains the historical [review-context design checkpoint](review_context_design_checkpoint.md) (formerly `m5_context_contracts.md`) and [evidence migration matrix](evidence_migration_matrix.md); neither owns current runtime contracts. - [2026-10-22-toolkit-site-launch-and-release-notification.md](2026-10-22-toolkit-site-launch-and-release-notification.md) @@ -14,6 +14,7 @@ | Stable tag | Primary archived plan | Related context in the same archive | | --- | --- | --- | +| `v0.13.0` | [Protected policy fallback for single-MR reviews](plans/2026-10-23-toolkit-0-13-0-protected-default-policy-fallback-for-single-mr-review.md) | #264 protected-policy authority with distinct code target, #265 conditional BL-025 planning, security dependency audit, protected feature merge and verified development artifacts; stable-delivery handoff pending. | | `v0.12.1` | [Review diagnostics, DLP and OCR 1.13.3](releases.md#plan-toolkit-0-12-1) | Protected feature/release merges, local OCR and security review, verified development and stable artifacts, immutable release, issue/milestone closure, live site refresh, and external reconciliation. | | `v0.12.0` | [OCR 1.13.2, external-tool context and optional local ChatGPT auth](releases.md#plan-toolkit-0-12-0) | Adjacent local OCR qualification, protected MR-context navigation, optional local native authentication and compatible dependency/security updates; protected stable delivery and external reconciliation verified. | | `v0.11.3` | [OCR 1.12.13 and reviewed qualification signals](releases.md#plan-toolkit-0-11-3) | Adjacent 1.12.12–1.12.13 qualification, conservative provider/model/deadline review routing, and preserved timeout outcomes; verified stable delivery and external reconciliation. | diff --git a/docs/engineering/execution_history/plans/2026-10-23-toolkit-0-13-0-protected-default-policy-fallback-for-single-mr-review.md b/docs/engineering/execution_history/plans/2026-10-23-toolkit-0-13-0-protected-default-policy-fallback-for-single-mr-review.md new file mode 100644 index 00000000..def298d2 --- /dev/null +++ b/docs/engineering/execution_history/plans/2026-10-23-toolkit-0-13-0-protected-default-policy-fallback-for-single-mr-review.md @@ -0,0 +1,185 @@ +# Execution Plan Archive + +This snapshot records the completed repository plan before stable publication. +The original Active Plan heading below identifies its source; `Status: done` marks +its closure. [PLANS.md](../../../../PLANS.md) owns current work, and the +[stable index](../README.md#release-index) links this archive. External delivery +belongs to the immutable receipt and Actions-owned issue comments. + +## Active Plan: Toolkit 0.13.0 protected default-policy fallback for single-MR review + +plan_schema_version: 2 +Status: done +Owner: root +Last Updated: 2026-10-23 +Release classification: #264 `release-required`, target v0.13.0; #265 `no-release` planning and the requested harness maintenance are separate logical changes in the same feature PR. + +### Goal + +Implement #264 without conflating the actual MR code target with protected policy authority, record the conditional #265 follow-up without activating chain review, and prepare the protected v0.13.0 release with the repository plan archived in that release PR. Stable publication and independent external reconciliation remain required post-close delivery for the active user goal. + +### Plan Origin + +`plan_mode_approved` + +### Requested Scope + +The feature PR contains #264 implementation and public-contract updates plus a separate logical documentation commit for #265. Its first commit contains only this reviewed plan. Self-review every subsequent logical commit. Before the final feature push, run Codex Security on the changed range, then one real local toolkit/OCR review through the documented private-artifact path and fix admitted findings. Audit project documentation, agent instructions, and routes; correct any findings in a separate commit before final reviews. Use the protected feature PR, development artifact verification, protected release PR, stable publication/receipt, issue closure, and site check after actual publication. In the release PR, archive the complete repository plan and reset `PLANS.md`; after publication, reconcile external facts against the immutable receipt and issue comments without another repository PR. Clean obsolete completed-run GitHub Actions artifacts and superseded caches without touching published Release assets or active-run inputs. Do not run additional checks on another host or environment. +The owner later requested an Astra harness/process audit. Its bounded current-branch follow-up removes one duplicate setup shared by two negative installed-artifact probes and preserves the failing command's exit status in the quality wrapper; keep both wheel/sdist behavioral cases and independent published-artifact gates. Capture per-test durations in the next required full quality run rather than adding a separate heavy measurement run. +After the feature PR's dependency-audit job identified vulnerable `opentelemetry-api` 1.44.0 in the committed lock, the owner requested a local pre-push dependency audit analogous to the Gitleaks gate. Remediate the package floor and lock, make local and hosted audit use one script and one pinned uv version, preserve local environment isolation and failure status, and validate the corrected boundary without another model review or redundant full quality run. +The owner requires the release PR to be the last repository change for this version. Repository planning ends after the release candidate is prepared and archived; protected release checks/merge and external stable publication/readback continue as required Post-Close Delivery, outside this closed repository plan rather than falsely marked complete. + +### Requirement Traceability + +| Requirement | Outcome | Queue | Status | +| --- | --- | --- | --- | +| REQ-001 | Absent protection setting selects `auto`; explicit `required` and `unprotected`, malformed values, local entry point, and existing operator-file contracts retain their stated behavior | WQ-02, WQ-05 | done | +| REQ-002 | Authenticate same-project MR and bind source H, actual target T, validated diff base/version B, and invocation; qualify detached, merged-result, and merge-train forms without synthetic-source confusion | WQ-02, WQ-03 | done | +| REQ-003 | For an actually unprotected target, select the same project's protected default branch and immutable P; enforce rule provenance and preserve context/federation controls without pretending the target is protected | WQ-03, WQ-04 | done | +| REQ-004 | Version result/receipt identity and capability decisions; reject old/forged contradictions, retain supported historical readback, and render truthful provenance and comment-only outcomes | WQ-04, WQ-05 | done | +| REQ-005 | Revalidate code and authority before publication and approval; stale or unverifiable identity fails closed, bounded policy-only fast-forward remains pinned to P, and unprotected targets never receive new approval | WQ-05 | done | +| REQ-006 | Preserve early exits, evidence applicability, DLP, current-MR context, ordinary outcomes, previous-review lifecycle, and controlled boundary budgets; expose actual target T as distinct untrusted code evidence when B and P differ | WQ-03, WQ-04, WQ-05 | done | +| REQ-007 | Update public configuration, GitLab examples, context, operations, security threat model, decision flow, strategy/roadmap, README, evidence matrix, and migration/changelog entry coherently | WQ-06, WQ-08 | done | +| REQ-008 | Record #265 as inactive BL-025 with its durable issue links, full backlog fields, per-variant #264 dependencies, A–F alternatives, relationship shapes, request surfaces, activation authority, validation and non-claims; reconcile the merged entry back to #265 without runtime or public setting | WQ-07, WQ-09 | done | +| REQ-009 | Review every commit; run applicable tests, secret scan, security diff scan, real local OCR review, and protected feature PR checks | WQ-01, WQ-02–WQ-09 | done | +| REQ-010 | Verify development artifacts and prepare the exact v0.13.0 release PR candidate: stable/next markers, issue authorization, epoch, changelog, notes, example pin, updated validation and protected handoff | WQ-10 | done | +| REQ-011 | Archive the repository-complete plan and reset `PLANS.md` in the protected release PR, with external facts explicitly pending outside repository plan closure | WQ-10 | done | +| REQ-012 | Reclaim Actions storage from obsolete completed-run artifacts and superseded caches, with before/after readback and retained release/current-run evidence | WQ-13 | done | +| REQ-013 | Add meaningful boundary coverage in touched Python modules and report final affected-file coverage; do not claim a before/after comparison from an incomplete baseline | WQ-02–WQ-05, WQ-14 | done | +| REQ-014 | Reduce duplicate installed-artifact negative-probe setup, preserve exact quality failure exit status, and record timing/process evidence without weakening wheel/sdist or registry gates | WQ-14 | done | +| REQ-015 | Align this active plan and future archive ownership with the installed engineering-workflow lifecycle without rewriting the consolidated historical release archive; keep release and development instructions consistent and avoid a duplicate full quality run for documentation-only changes | WQ-15 | done | +| REQ-016 | Remediate the current `opentelemetry-api` audit finding and require the same fail-closed installed-dependency audit locally before each push and in hosted security CI | WQ-09 | done | +| REQ-017 | After repository closure, pass protected release checks/merge, publish and independently read back stable distributions, provenance, attestation, tag, immutable Release/receipt, #264/milestone and real site notification without another repository PR | WQ-11, WQ-12; Post-Close Delivery | out_of_scope | + +### Explicit Non-Goals + +No related-MR discovery, chain/integration review, merge orchestration, source-branch policy bootstrap, fork/cross-project authority, new CI variable or policy field, second model pass, direct external MCP passthrough, approval revocation, downstream-project mutation, or new public command for #265. No separate host QA. Actual target protection is not a coverage score, and a successful current-MR review does not prove a parent or future integration. +Do not drop wheel or sdist packaging, remove the existing installed local-review scenarios, or repeat full tests in the release publication gate to optimize this task. Matrix reduction awaits measured scenario timing and an independent maintenance decision. + +### Constraints + +- GitLab acquisition is authenticated, bounded, and same-project; missing or contradictory source/target/project, diff, branch protection, default metadata, or Git objects fail with explicit diagnostics, not inferred fallback. +- `B..H` is the current MR delta. `B != T` is valid if the authenticated MR diff identity is coherent. Never substitute `P..H`, `T..H`, synthetic `CI_COMMIT_SHA`, or unrelated CI evidence. Preserve B/H deltas while exposing T as a separate bounded, untrusted code snapshot; T content never becomes P authority. +- Capture actual target branch/head/protection and policy project/branch/P/protection separately. Only a protected authority may supply rules, context policy and eligible guidance; changed feature-branch material remains untrusted evidence. External absolute or omitted rule forms cannot claim P provenance. +- Preserve `off|metadata|enriched`, governed registry-v2 admission and budget gates, same-revision evidence, accepted-decision applicability, DLP, immutable Git isolation, existing setup-pending/two-MR onboarding, and terminal/stale/no-change lifecycle boundaries. +- Recheck the bound code tuple, authority, and present CI job identity before each provider write. Policy-only advancement is acceptable only with bounded proof of same protected branch and ancestry; keep captured P. Changed default/protection, rewrite, missing authority, cross-job handoff, or unverifiable ancestry fail closed. Read-before-write retains a residual provider race. +- An actually unprotected target is always comment-only, including when `OCR_AUTO_APPROVE=true`; prior bot approvals may remain and are not revoked. Protected targets keep their own policy and approval gates. +- Use only synthetic/private-safe examples and artifacts. Follow signed, linear protected PR and trusted-base release authorization; no manual mutation of immutable release objects. + +### Inputs And Sources + +- Live [#264](https://github.com/xeonvs/open-code-review-toolkit/issues/264) (updated 2026-10-23 08:52 UTC) and [#265](https://github.com/xeonvs/open-code-review-toolkit/issues/265) (updated 08:31 UTC), including acceptance lists; GitLab's official MR/version, project, CI-variable, merged-results and merge-train API documentation. +- Current `main` baseline `b8786e7`, stable `.release-version=0.12.1`, next `.next-version=0.13.0`, empty active plan, and the completed v0.12.1 archive. +- Canonical owners: `AGENTS.md`, `docs/engineering/project_principles.md`, `docs/development.md`, `docs/release.md`, `docs/review-decision-flow.md`, `docs/review-context.md`, `docs/engineering/toolkit_strategy.md`, `ROADMAP.md`, `docs/codex/TASKS_BACKLOG.md`, and `docs/engineering/test_evidence_matrix.md`. + +### User Decisions And Answers + +The owner selected a full stable v0.13.0 release after #264 and chose one feature PR containing #265 as a separate logical commit. The owner requested the previous release's plan-first, self-review, security then local OCR review, protected PR, artifact/receipt, site-after-release and clean plan closure sequence. The root agent must switch to the feature branch; #265 remains planning-only and does not itself authorize a release. +The owner additionally requested cleanup of GitHub Actions run artifacts because storage is scarce; this is `no-release` operational work. +The owner also requested regular coverage improvement in touched files; focus on behavior and failure branches rather than tests that only reproduce an implementation. +The owner requested a separate Astra agent to audit harness duplication and process, then apply justified corrections. This scoped harness maintenance is `no-release` by itself and does not add another release trigger or publication job. +The owner later requested that the release PR return `PLANS.md` to its template state and that external readback close the work without a post-release repository PR. The release archive must describe publication as pending at merge; the immutable receipt and Actions-owned issue comments carry verified external facts afterward. The release workflow and validation contracts must be updated in the release branch before publication so they do not require the old closure PR; the guide is aligned in WQ-15. +This is an explicit scope transfer, not a cancellation: REQ-017 and WQ-11/WQ-12 are outside the repository plan so the installed lifecycle can close it in the release PR. They remain mandatory for the user-facing goal and are enumerated in Post-Close Delivery. Unverified external facts stay pending in the archived snapshot. + +### Completed Baseline State + +v0.12.1 is published and externally reconciled; prior release and internal follow-up issues are closed. `main` was clean and synchronized with `origin/main` at `b8786e7`. Both current issues are open. `feature/264-auto-policy-0.13.0` was created from that baseline; its first signed commit contains only this plan and draft feature PR [#266](https://github.com/xeonvs/open-code-review-toolkit/pull/266) is open. Milestone v0.13.0 tracks #264 only. At activation no feature implementation existed. BL-024 is historical, so BL-025 is the next unused backlog identifier. + +### Current Work Queue + +| Queue | Requirements | Exit evidence | Status | +| --- | --- | --- | --- | +| WQ-01 | REQ-009 | Review and commit only this plan; establish goal, milestone and feature PR identity | `done` | +| WQ-02 | REQ-001, REQ-002, REQ-009, REQ-013 | Provider/config/CI identity changes and production-boundary tests; self-reviewed commit | `done` | +| WQ-03 | REQ-002, REQ-003, REQ-006, REQ-009, REQ-013 | Immutable diff/authority/rule acquisition, distinct target T evidence/readback and applicability tests; self-reviewed commit | `done` | +| WQ-04 | REQ-003, REQ-004, REQ-006, REQ-009, REQ-013 | Capability/context/federation, receipt/result v11 and hostile readback tests; self-reviewed commit | `done` | +| WQ-05 | REQ-001, REQ-004, REQ-005, REQ-006, REQ-009, REQ-013 | Full-identity freshness at current-result and static-note writes, publication/approval/draft and cleanup boundaries, receipt-less error isolation, cross-run private-artifact isolation, and local-entry tests; self-reviewed commit | `done` | +| WQ-06 | REQ-007, REQ-009 | Public contracts, examples, threat model, decision flow, changelog; self-reviewed commit | `done` | +| WQ-07 | REQ-008, REQ-009 | Self-contained BL-025 with Source #265 and reference #264, status/theme/prerequisites/trigger/scope/deliverables/acceptance/exclusions/validation/future release classification; per-variant dependencies, A–F coverage, graph shapes and request/publication trade-offs; aligned strategy/roadmap and self-reviewed separate commit | `done` | +| WQ-08 | REQ-007, REQ-009 | Documentation/instruction/route audit, distinct correction commit, focused documentation checks and valid instruction contract | `done` | +| WQ-14 | REQ-014, REQ-009, REQ-013 | Astra-backed installed negative-probe setup and quality exit-status corrections, focused tests, docs, timing in the next full quality gate, separate self-reviewed commit | `done` | +| WQ-15 | REQ-015, REQ-009 | Adopt the canonical active-plan headings and queue statuses, add a dedicated per-plan archive index, align workflow state and documentation, pass lifecycle/route/documentation checks without repeating the full quality gate, and self-review the commit | `done` | +| WQ-09 | REQ-008, REQ-009, REQ-016 | Codex Security scan, corrected real local toolkit/OCR review, finding fixes, patched dependency and a shared local/CI pre-push audit gate with focused verification, then final feature PR checks/merge; mark verified acceptance checkboxes in #264/#265, link the merged BL-025 entry in #265 and record selected/deferred/rejected variants there | `done` | +| WQ-10 | REQ-010, REQ-011 | Verified deterministic TestPyPI development wheel and sdist, exact release metadata/notes/example, legacy-marker contract correction, repository-plan archive/reset, local validation and self-reviewed candidate ready for a signed commit | `done` | +| WQ-11 | REQ-017 | Protected release PR checks/merge; stable TestPyPI/PyPI, provenance, attestation, immutable release/receipt, issue/milestone and real site readback after repository closure | `out_of_scope` | +| WQ-12 | REQ-017 | Independently verify exact external receipts, issue/milestone and site state; close the user goal with `PLANS.md` already clean and no post-release repository change | `out_of_scope` | +| WQ-13 | REQ-012 | Inventory completed-run artifacts/cache, delete only obsolete bytes, retain current PR and latest release evidence, verify remaining inventory and record reclaimed size | `done` | + +### Locked Decisions + +Use `auto` as the absent-setting default and retain explicit modes. Use closed provider-neutral authority/capability identity with GitLab acquisition behind the adapter. Receipt v11 distinguishes code target from policy authority; historical v9/v10 remain readback-only under their original invariants, never guessed into a new profile. Choose clear rejection for unsupported pipeline or rule forms. Keep #265 in BL-025 only until separately activated by owner approval. Track only #264 in the v0.13.0 release issue set; close #265 through its feature PR after its planning deliverable is reviewed. + +### Verification + +- Focused parser/provider, real temporary Git and bounded local HTTP, result/receipt hostile-readback, context/federation, posting/approval, lifecycle and source-identity tests for every #264 acceptance branch; preserve exact owner entry points and note test doubles beyond them. +- A B!=T!=P evidence fixture must prove T-only implementation facts are available as untrusted target evidence without changing B..H deltas, policy authority, historical store readback or bounded admission. +- Public example/preflight and `--local` contract tests, clean installed wheel/sdist runtime probes, one actual OCR review for changed model-visible behavior, plus `scripts/quality.sh check`, `scripts/gitleaks.sh`, instruction-contract lint if routes change, documentation links/semantic audit and final scoped diff review. +- Record final per-file coverage for touched Python modules, add meaningful branch/boundary tests where coverage is weak, and compare only complete aggregate runs; the available pre-feature per-file baseline is incomplete and cannot support a growth claim. +- Codex Security diff scan after implementation and before final feature push; then a correctly invoked local toolkit/OCR review to completion with private physical output path, terminal status, report and findings readback. Fix admitted findings with focused regression and self-review; repeat a full model scan only for incomplete coverage or a materially new unreviewed boundary. +- Exact required protected feature/release PR checks; stable workflow's independent hash, registry provenance, supported-Python installed smoke, immutable receipt readback and post-publication external verification. Check the live site only after release notification/deployment. + +### Latest Validation Results + +Plan-only signed commit `d616e98` contains only `PLANS.md` and passed `git diff --check`; `scripts/gitleaks.sh --tree` and the reachable-range scan passed before its push. Draft PR #266 exists, and #264 is in milestone v0.13.0 while #265 remains outside it. At that plan-only point no feature test or review gate had run. +GitHub Actions inventory at 2026-10-23 shows 42 artifacts totaling 14,613,655 bytes and four caches totaling 142,839,380 bytes. The current draft-PR artifact is 7,171 bytes; the completed v0.12.1 release and its development-build artifact remain useful for recovery/readback. Two superseded uv caches account for 89,449,983 bytes. All 100 most recent workflow runs are completed. +All 195 listed workflow runs were confirmed completed. Deleted 21 obsolete distribution artifacts and two superseded uv caches. Readback lists 21 remaining artifacts totaling 1,422,439 bytes and two retained caches totaling 53,389,397 bytes, so listed stored bytes fell by 102,641,199. The current PR SARIF, latest release/development distributions, and immutable v0.12.1 Release assets remain; GitHub's cache-usage aggregate briefly lagged the cache listing after deletion. +Focused provider tests pass (68 tests, 2026-10-23). Review of the B!=T!=P execution path found a real evidence gap: T was fetched and stored in the receipt but not available through evidence MCP. WQ-03 now explicitly includes a versioned, bounded target evidence snapshot. The pre-change complete quality log from 2026-10-22 provides a comparable baseline for affected-file coverage; final numbers remain pending. +Signed self-reviewed implementation commits: `cd74ac4` binds detached MR CI, same-project provider and target/policy snapshot; `a1d056a` adds bounded target T evidence v5 and protected-P ancestry support; the following execution commit binds diagnostics and receipt v11, including the local-policy collection regression fix. Focused provider/local tests: 148 passed; evidence/freshness tests: 201 passed; execution/receipt/docs-contract tests: 254 passed. Full quality, security and local OCR gates remain pending until documentation is complete. Review of posting found additional mid-publication freshness transitions now being corrected in WQ-05. +Signed self-reviewed planning commit `76a1c3a` records conditional BL-025 for #265 and its roadmap placement without runtime changes or a release claim. Its scoped diff check passed. #265 still needs issue-body reconciliation after the feature PR merges. +WQ-05 focused source and boundary suites passed with 686 tests and 299 subtests after the CI-job handoff and current-version-contract additions. Ruff format/check, mypy across 132 source files, and diff whitespace checks passed. A second independent seam audit found the review-to-post interval in a shared checkout; receipt and preview/setup status now bind the supplied GitLab job ID, code 75 prevents a losing review from adopting another run's status, and the example uses job-specific output paths. Production GitLab uses one review/post pair per CI job. Full quality and final security/OCR reviews remain pending until WQ-06/WQ-08 documentation is committed. +Signed self-reviewed WQ-05 commit `d5bc468` contains the posting, cross-run, current-version contract and regression changes. WQ-06 public documentation now explains v11, default `auto`, B/H/T/P, job-specific handoff, local private paths and the no-note failure policy. The public GitLab example omits the selector so its still-published wheel pin remains valid until the release PR advances it; the new toolkit then supplies the `auto` default. The 51 focused documentation/example contracts passed. +Signed self-reviewed WQ-06 commit `58d29d3` contains the public docs, examples and changelog. Signed self-reviewed commit `0b416c8` makes the historical v9/v10/v11 nested-schema mapping explicit, so a future v12 cannot inherit a predecessor's federation or publication schema by fallback; 129 receipt/approval/freshness tests and 94 subtests passed. The WQ-08 documentation/instruction audit corrected context and federation ownership routes, engineering contracts and example links; the instruction contract is valid, the 51 focused documentation contracts pass, and full quality and final reviews remain pending. +The first full quality attempt stopped at a single Ruff formatting defect in the public-example contract test; it was corrected in amended documentation commit `ae83977`. The next full pytest/coverage run reached 86.36% total coverage and 2270 passing tests, but 14 tests still asserted obsolete local-status, private-error-note or historical-receipt publication behavior. Six affected test modules now assert the current no-write/no-status boundaries and retain late debug/progress coverage; 108 focused tests passed with three qualified skips before the successful complete run below. +Astra's read-only harness audit confirmed #260 is closed and the expensive installed-artifact suite already runs on one Ubuntu/Python 3.12 CI leg; other legs start in parallel, while stable publication verifies new artifacts without repeating full pytest. Different observed CI runs spanned 13m24s and 4m22s, which is directional evidence rather than a controlled benchmark. The remaining duplicate was two negative probes creating equivalent clean no-dependency environments. The quality wrapper also reduced an underlying failing command's exit status to 1 before the WQ-14 fix. +The bounded WQ-14 patch now shares one module-scoped wheel-only interpreter between both read-only negative dependency probes, preserves their distinct PATH/cwd assertions, and makes `scripts/quality.sh` propagate failure statuses. The fake-uv regression checks exit codes 2, 7 and 130 plus stop-before-coverage behavior. All 12 focused harness tests pass in 2.14 seconds; 40 focused documentation/environment tests, repository-wide Ruff check/format, instruction-contract lint and whitespace checks pass. The prior failed quality log is retained in a private task archive outside the repository. +The complete local quality gate now passes: 2288 tests, five qualified skips and 357 subtests in 295.67 seconds, with 86.47% aggregate line/branch coverage. The installed wheel/sdist MCP scenario accounts for 157.09 seconds; the shared negative-probe setup takes 1.06 seconds, and the independent wheel/sdist behavioral cases remain intact. Current changed-file coverage includes 100% for `posting/freshness.py` and `review_identity.py`, 88.02% for `review_receipt.py`, 86.74% for `providers/gitlab.py`, and 80.14% for `posting/workflow.py`. The available pre-change JSON was collected from an incomplete test run (70.24%) and is not a valid before/after baseline; do not report it as coverage growth. A public-tree secret scan passes. Astra's process recommendation is captured in the bounded harness commit; the remaining expensive integration matrix needs a separately measured follow-up before any reduction. +Codex Security completed a diff scan of `b8786e73783fb9a9b2572da6a409a456191f2186..e6ab0ca87161a38389d63d933da03151a6448912` with complete coverage of 25 changed source files and zero findings. The scan reported the existing read-before-write provider race as a residual risk, not a validated finding. Later bounded scans cover changed runtime deltas below; none of these reports is represented as coverage of subsequent correction commits. +The first local preflight lacked an authentication-mode selection and required API model; a later candidate command used local-unsupported `--background-file` and was rejected before OCR ran. The corrected native ChatGPT invocation used checksum-verified OCR 1.13.3 and physical private outputs. It exited zero, delivered JSON and Markdown, completed 29/29 selected items with DLP admission and seven reconciled mandatory evidence calls, and reported one high bug in old-review cleanup after the first deletion. Commit `eeca61a` retains current-run comments after a destructive cleanup attempt and stops on unconfirmed deletes; 95 posting/freshness tests pass. Separate instruction/contract commit `08f0a70` adds the launch guard and truthful partial-cleanup diagram; 51 documentation tests and instruction-contract lint pass. +The corrected head then passed the complete quality gate: 2290 tests, five skips and 357 subtests in 296.21 seconds, with 86% rounded aggregate coverage and 81% rounded posting-workflow coverage. A second Codex Security scan covered the changed runtime delta from `e6ab0ca` through `e60108f` and returned zero validated findings. The second local OCR 1.13.3 review exited zero with physical private JSON/Markdown, 29/29 completed, zero failed/waived/reused, eight reconciled evidence calls and DLP admission. One auxiliary model file-read used a nonexistent path; selected-item coverage remained complete. It reported three medium bugs: target-only tree-limit abort, setup-note rollback after partial old cleanup, and unpublished draft carry-forward. The optional T limit correction is `ee2f5d2`; unreadable T identity and non-budget read errors still fail closed. Posting correction `e8e2d3d` retains replacement notes after a cleanup attempt, attempts removal of definitely unattempted draft IDs and excludes pending drafts from published-finding fingerprints. Instruction/contract update `c8017d2` records exact local result verification and the partial-state boundaries. The focused evidence/posting/docs suite passed 344 tests and 205 subtests; types, Ruff, instruction-contract lint, and staged secret checks passed. The generic `plan_lifecycle.py check` exposed this repository's customized active heading and consolidated historical archive; WQ-15 migrates only future per-plan ownership while retaining legacy history. +The complete quality gate on corrected runtime head `bb0c9c4` passed on 2026-10-23: 2297 tests, five qualified skips and 357 subtests in 301.94 seconds, with 86.52% aggregate coverage. The installed wheel/sdist MCP test took 158.27 seconds. WQ-15 changes only plan, workflow state, navigation, release/development guidance, and its documentation contract test; no runtime or product test code changed. +The WQ-15 migration uses the installed plan schema without changing the consolidated historical archive. `plan_lifecycle.py check`, instruction-contract lint, 45 focused documentation/integration tests, Ruff on the touched test file, documentation navigation with zero errors or warnings, public-tree secret scan, and `git diff --check` pass on 2026-10-23. The full quality gate was not repeated for this bounded documentation delta. +Codex Security's third diff scan covered the three runtime files changed in `e60108f..27e489a` and completed with zero findings. The third local OCR 1.13.3 review at `27e489a` exited zero, delivered physical private JSON and Markdown, completed 31/31 selected items with zero failed/waived/reused, reconciled eight mandatory evidence calls, and passed DLP. Two auxiliary file reads failed but did not reduce selected-item coverage. It found two medium bugs: the documented `--local --preserve-private-artifacts` path was unreachable, and a newly fetched protected policy tip could be a shallow boundary that hid a direct fast-forward. Signed self-reviewed commit `2385854` enables explicit local private retention with a DLP-projected report while retaining a non-postable marked raw result; direct provider diagnostic finalization still produces no successful report. Signed self-reviewed commit `57ddf56` retries shallow ancestry proof through one depth-128 history fetch, retains exact immutable P and fail-closed behavior, and avoids collecting unbounded fetch output. A real remote-after-checkout regression and local/diagnostic tests pass; the affected focused suite has 189 passing tests. The documentation, decision flow, evidence matrix and review-efficiency instruction changes are included in this separate logical commit. No fourth full security or OCR review is justified by these corrections; their focused regressions and the completed quality gate below cover the final runtime handoff. +The completed final local quality gate passes on the corrected runtime and prepared documentation: 2300 tests, five qualified skips and 357 subtests in 300.82 seconds, with 86.54% aggregate coverage. Compared with the preceding complete run on `bb0c9c4`, aggregate coverage is 0.02 percentage points higher; this is not a claim about the unavailable pre-feature baseline. Affected-file final coverage is 100% for `posting/freshness.py`, 85% for `review_runner.py`, and 81% for `evidence/repository.py`. The plan lifecycle check, instruction-contract lint and documentation navigation check also pass, with zero navigation errors or warnings. Do not rerun the full gate for the final documentation-only evidence update. +The first hosted PR run passed every check except `dependency-audit`, which found `opentelemetry-api` 1.44.0 via MCP. The corrected lock resolves 1.45.1 under uv 0.13.4 without changing lock revision or unrelated packages. The shared local/CI audit script passes in its isolated environment with no known vulnerabilities; `pip check`, `uv lock --check`, 51 affected tests, repository-wide Ruff format check, instruction-contract lint, plan lifecycle check, and documentation navigation pass. The audit wrapper's focused tests prove exact CI pin agreement, isolated environment, fallback from the older installed uv, and preservation of sync/audit failure exit statuses. The prior full runtime and model reviews remain valid for unchanged runtime code; the narrow dependency/workflow change is verified by its focused tests and the next protected CI run. +The corrective feature head `dc62581` passed every protected PR check, including the shared dependency-audit job, all five platform/Python jobs, CodeQL, dependency review, build and security. PR #266 merged as `24b0ba0`, with the squash tree exactly equal to that reviewed head. All 17 implementation boxes in #264 are checked while it remains open on the v0.13.0 milestone for stable receipt closure. #265 has all nine planning boxes checked, links merged conditional BL-025 and the recommended/deferred/rejected alternatives, and is closed with no runtime chain feature. Main-bound TestPyPI development run `39959060145` succeeded at `24b0ba0`; independent TestPyPI API readback found both `0.13.0.dev122` wheel (`3b144dbe955d172a170a2ee942dabce318a466619056f95672b9d3e3ad6e21db`) and sdist (`dfa2c922b2bb7a820e518e8efc5b5981563423afbc068b580dd4feb07ea73efe`). +On 2026-10-23, release preparation from exact feature merge `24b0ba0` advanced stable/next markers to 0.13.0/0.14.0, set source epoch to 1792761040 (one second after the merge), authorized only open milestone issue #264, rendered the complete Towncrier section and adjacent release notes, and advanced the checksum-pinned GitLab example to the same stable version. The legacy reconciliation marker remains 0.12.1 as historical evidence. The updated contract tests no longer treat it as the current plan boundary. One hundred seven focused release, documentation, example and integration tests passed; Ruff format, uv lock, instruction-contract, plan-lifecycle, documentation-navigation and whitespace checks passed. The complete implementation gate and hosted feature PR matrix already passed on the same runtime/dependency code, so this repository-only release preparation does not repeat a full local pytest run. +The checked lifecycle archived this repository plan and left `PLANS.md` with no active work. The generated archive's relative index link was corrected before delivery. All 108 focused release/documentation/integration tests then passed on the closed layout; plan lifecycle, instruction contract and documentation navigation passed with no errors or warnings. Two independent source-epoch-controlled v0.13.0 builds produced byte-identical distributions and passed Twine: wheel SHA-256 `2c7c36f3f0df6c03314d49fbd89cb08eb82db794991b47e7b4627161547ce5f6`, sdist SHA-256 `e579ea7f448861828cc4d42fd3c13c0f5193273bfc56964377eb0d17b13399d2`. Protected release PR checks and all external stable facts remain unverified at this pre-publication handoff. +The first protected release PR matrix exposed one documentation mismatch: `docs/configuration.md` still listed example toolkit version 0.12.1 while the release example and marker selected 0.13.0. All five platform jobs failed the same environment-table assertion; each completed its other tests, including 2303 passing tests on Ubuntu/Python 3.12. The table and release preparation instruction were corrected in the same unmerged PR candidate. A focused suite of 114 environment, release, documentation and integration tests passed; instruction-contract lint and documentation navigation also passed. This correction changes no runtime or packaged distribution bytes; the protected matrix must still validate the amended head before merge. + +### Risks And Recovery + +GitLab diff/version and pipeline variants may require rejecting unsupported forms before model work; do not guess identity. Shallow Git history beyond the bounded retry may still prevent proving policy fast-forward; fail closed with actionable unavailable outcome. If protection/default selection or target changes during review, retain earlier valid publication and report stale. External publication or workflow state must be read back before retry; resume a failed authorized release through its documented exact-artifact recovery rather than republishing different bytes. Preserve private review artifacts until report and admitted findings are verified. + +### Resume Point + +No in-scope repository work remains. Required external delivery is classified in Post-Close Delivery. + +### Plan Fidelity Check + +- [x] #264 and #265 outcomes, non-goals, updated #264 identity/freshness additions, and user decisions map to REQ and ordered WQ items. +- [x] Release classification, 0.13.0 target, #265 no-release boundary and plan/closure ownership are explicit. +- [x] Each acceptance family has focused verification and production-boundary evidence; reviews, site timing, and external receipts have owners. +- [x] Risks, fail-closed recovery, immutable artifacts and first safe unfinished action are recorded. +- [x] The newly requested Actions storage cleanup has an independent `no-release` requirement and readback owner. +- [x] The later plan-format and bounded-validation request has a separate requirement, queue item, owner and first safe unfinished action. +- [x] The observed dependency-audit failure and requested local-before-push gate map to REQ-016 and WQ-09 without expanding model review scope. +- [x] The owner-directed repository-plan boundary classifies protected release PR and publication/readback as required post-close delivery under REQ-017, with no claim that those external facts already exist. + +### Reconciliation Check + +- [x] This plan reflects the current issue bodies and clean `b8786e7` baseline at activation. +- [x] Reconcile changed implementation, test, PR, release and external facts before their dependent milestones and final archive. + +### Closure Gate + +- [x] Every in-scope repository requirement and queue item is terminal with applicable validation evidence; REQ-017 is explicitly transferred to required post-close delivery. +- [x] No issue, instruction, document, backlog or release candidate state contradicts the prepared result. +- [x] The checked lifecycle archives repository-complete work and resets the active plan in this protected release PR; external receipt verification remains post-close work without another repository PR. + +### Post-Close Delivery + +Required post-close delivery outside the closed repository plan: commit and push the signed release candidate, pass the protected release PR checks and merge it; verify stable TestPyPI/PyPI artifacts, provenance, attestations, annotated tag, immutable GitHub Release and v2 receipt, #264/milestone closure, site notification and live site state. Independently read back those exact external facts against the receipt and Actions-owned issue comments before completing the user goal. None is asserted complete by this pre-publication archive, and no separate repository closure PR is planned. + +### Handoff Notes + +No in-scope repository work remains. The archived snapshot records pre-publication facts; immutable receipt and Actions-owned issue comments own later external delivery evidence. diff --git a/docs/engineering/execution_history/plans/README.md b/docs/engineering/execution_history/plans/README.md index 6c52326f..2076357a 100644 --- a/docs/engineering/execution_history/plans/README.md +++ b/docs/engineering/execution_history/plans/README.md @@ -3,5 +3,5 @@ Each new repository plan archived through the engineering-workflow lifecycle is indexed here. Earlier releases remain in the [consolidated historical archive](../releases.md) and the [stable release index](../README.md#release-index). - +- [2026-10-23-toolkit-0-13-0-protected-default-policy-fallback-for-single-mr-review.md](2026-10-23-toolkit-0-13-0-protected-default-policy-fallback-for-single-mr-review.md) diff --git a/docs/release.md b/docs/release.md index b7fb3de9..766e1671 100644 --- a/docs/release.md +++ b/docs/release.md @@ -27,7 +27,7 @@ The delivery sequence is: 7. require CI readback of the immutable `release-receipt.json`, then close the tracked issues and milestone; 8. independently read back the exact external state against the immutable receipt and issue comments, then close the delivery objective without another repository pull request. -The release pull request is the final repository mutation before stable publication. It owns stable and next version markers, deterministic source epoch, tracked authorization metadata, generated Towncrier changelog, release notes, and reconciliation of the plan and status documents. Follow the checked [plan archive and external reconciliation](#external-reconciliation-and-plan-archiving) below. The v0.13.0 release PR must update CI contracts that previously required `.release-reconciled-version` to advance through a post-publication closure PR; historical marker values and archived plans remain evidence for older releases. The release PR must not claim that registry files, provenance, tag, immutable Release, receipt, or installs already exist. The protected-main merge may run the normal TestPyPI development workflow described below; verify its workflow outcome, but do not treat that development build as another stable release or repeat stable artifact readback. +The release pull request is the final repository mutation before stable publication. It owns stable and next version markers, deterministic source epoch, tracked authorization metadata, generated Towncrier changelog, release notes, and reconciliation of the plan and status documents. Follow the checked [plan archive and external reconciliation](#external-reconciliation-and-plan-archiving) below. `.release-reconciled-version` is historical evidence for releases that used a post-publication repository closure PR; it does not advance for plans closed in the release PR. Current validation uses the archived plan, stable index and immutable external receipts instead. The release PR must not claim that registry files, provenance, tag, immutable Release, receipt, or installs already exist. The protected-main merge may run the normal TestPyPI development workflow described below; verify its workflow outcome, but do not treat that development build as another stable release or repeat stable artifact readback. List tracked release issues in a release PR as bare references or ordinary non-closing prose. Do not use GitHub closing-keyword forms such as `close`, `closes`, `closed`, `fix`, `fixes`, `fixed`, `resolve`, or `resolves` together with those issue references: merging such a PR can close the issues before the immutable receipt exists. The Release workflow is the sole closure owner, and acts only after its post-publication receipt readback. @@ -57,7 +57,7 @@ Development builds never create tags or GitHub Releases and never publish to pro ## Stable release -Prepare `release/vX.Y.Z` locally from synchronized `main`. Update `.release-version`, `.release-source-date-epoch`, package metadata, documentation, checksum-pinned examples, and the Towncrier changelog. Reconcile the active plan and release history as described below. The pull request title must be exactly `Release vX.Y.Z`. Required CI, security, CodeQL, Dependency Review, and build checks must pass before squash merge. Because TestPyPI is public disclosure, the protected feature/release review includes the privacy and license gate before either publication path. +Prepare `release/vX.Y.Z` locally from synchronized `main`. Update `.release-version`, `.release-source-date-epoch`, package metadata, documentation, checksum-pinned examples and their `docs/configuration.md` default table, and the Towncrier changelog. Run `tests/test_environment_contract.py` with the focused release/documentation contracts before the release PR so the published example and documented pin agree. Reconcile the active plan and release history as described below. The pull request title must be exactly `Release vX.Y.Z`. Required CI, security, CodeQL, Dependency Review, and build checks must pass before squash merge. Because TestPyPI is public disclosure, the protected feature/release review includes the privacy and license gate before either publication path. Squash-merging that exact repository-owned release PR is the only human publication gate. The **Release** workflow then: @@ -94,7 +94,7 @@ Release CI owns independent SHA-256 comparison of TestPyPI, PyPI, the GitHub wor The immutable receipt carries the release PR, reviewed base/head/merge/tree, original workflow run and attempt, tracked issue set, distribution hashes, registry/provenance verification states, annotated-tag target, and supported-Python matrix. Independent external readback confirms facts that the receipt cannot assert about itself, especially Release asset equality and immutable state. Issue comments retain the receipt asset hash and are the durable post-merge closure surface. -In the release PR, use the installed `engineering-workflow` plan lifecycle to archive the complete repository plan under `docs/engineering/execution_history/plans/` with external delivery pending. Link the archived file from the stable-tag row in the [execution-history index](engineering/execution_history/README.md), and return `PLANS.md` to its template state. The lifecycle transition updates the active-plan state and managed archive indexes atomically; review its result as ordinary release documentation. Earlier plans in `releases.md` remain historical and are not rewritten by the new lifecycle. +In the release PR, use the installed `engineering-workflow` plan lifecycle to archive the complete repository plan under `docs/engineering/execution_history/plans/` with external delivery pending. Classify unverified publication and readback as required post-close delivery outside the repository plan; do not mark those facts complete before the external receipt exists. Link the archived file from the stable-tag row in the [execution-history index](engineering/execution_history/README.md), and return `PLANS.md` to its template state. The lifecycle transition updates the active-plan state and managed archive indexes atomically; review its result as ordinary release documentation. Earlier plans in `releases.md` remain historical and are not rewritten by the new lifecycle. After publication, independently verify the immutable release, workflow, tag, receipt, issue, milestone, branch and synchronized-main state. Keep those exact external facts in the immutable receipt and Actions-owned issue comments; the archived plan truthfully retains the pre-publication handoff as historical context. Do not revise older release sections opportunistically, publish another stable version, or mutate an existing release object. Use stable tags rather than calendar years as lookup keys. diff --git a/examples/gitlab/ocr-review.gitlab-ci.yml b/examples/gitlab/ocr-review.gitlab-ci.yml index 5eba7aea..2ec5b4a3 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.13.3" - OCR_TOOLKIT_VERSION: "0.12.1" + OCR_TOOLKIT_VERSION: "0.13.0" OCR_TOOLKIT_CHECKSUMS_URL: "https://github.com/xeonvs/open-code-review-toolkit/releases/download/v${OCR_TOOLKIT_VERSION}/SHA256SUMS" OCR_SHA256: "843be0e56fdff0a5ca6f86c5866f942d6a372dff1c0ca19e7893d72495abf45c" OCR_POST_MODE: "draft" diff --git a/tests/test_integration_contracts.py b/tests/test_integration_contracts.py index d83744a2..0f66f8f1 100644 --- a/tests/test_integration_contracts.py +++ b/tests/test_integration_contracts.py @@ -160,11 +160,11 @@ def test_gitlab_docs_match_the_current_review_surface() -> None: item for item in manifest["releases"] if item["version"] == example_version ) assert example_entry["status"] == "tested" - # A feature branch retains the published example pair until release - # preparation advances both toolkit and OCR pins atomically. - stable = (PROJECT_ROOT / ".release-version").read_text().strip() - reconciled = (PROJECT_ROOT / ".release-reconciled-version").read_text().strip() - if stable != reconciled: + # An active plan can qualify a newer OCR version before release preparation + # advances the published example. Once the plan is archived, the example + # must name the current recommendation without relying on a legacy marker. + plan = (PROJECT_ROOT / "PLANS.md").read_text() + if "## Active Plan:" not in plan: assert example_version == recommended linux_digest = next( asset["sha256"] diff --git a/tests/test_operations_docs.py b/tests/test_operations_docs.py index 34fbef90..e5c65396 100644 --- a/tests/test_operations_docs.py +++ b/tests/test_operations_docs.py @@ -158,7 +158,7 @@ def test_documentation_indexes_route_to_canonical_owners() -> None: def test_release_archive_reconciles_current_external_delivery_truth() -> None: - """Preserve the last legacy archive while the new plan closure is prepared.""" + """Keep legacy receipts and current repository closure distinct.""" release_guide = (PROJECT_ROOT / "docs" / "release.md").read_text(encoding="utf-8") release_archive = ( @@ -191,27 +191,39 @@ def test_release_archive_reconciles_current_external_delivery_truth() -> None: assert "without another repository pull request" in release_guide assert "under `docs/engineering/execution_history/plans/`" in release_guide - assert "The v0.13.0 release PR must update CI contracts" in release_guide + assert "does not advance for plans closed in the release PR" in release_guide assert "List tracked release issues in a release PR as bare references" in release_guide assert "The Release workflow is the sole closure owner" in release_guide - assert archive_version == release_version + assert reconciled_version == archive_version assert reconciled_version_key <= release_version_key - if reconciled_version == release_version: - assert "completed" in current_status - assert "external reconciliation verified" in current_status - assert "pending" not in current_status - assert "External reconciliation date:" in current_release - else: - assert f"plan-toolkit-{reconciled_version.replace('.', '-')}" in release_archive - assert "pending" in current_status - assert "External reconciliation date:" not in current_release + assert "completed" in current_status + assert "external reconciliation verified" in current_status + assert "External reconciliation date:" in current_release current_index_row = next( line for line in release_index.splitlines() if line.startswith(f"| `v{release_version}`") ) - if reconciled_version == release_version: + if release_version == archive_version: assert "external reconciliation" in current_index_row assert "stable-delivery handoff" not in current_index_row + else: + plan_directory = PROJECT_ROOT / "docs/engineering/execution_history/plans" + stable_archives = [] + for path in plan_directory.glob("*.md"): + if path.name == "README.md": + continue + text = path.read_text(encoding="utf-8") + if re.search(rf"^## Active Plan: Toolkit {re.escape(release_version)}\b", text, re.M): + stable_archives.append((path, text)) + assert len(stable_archives) == 1 + archive_path, archived_plan = stable_archives[0] + assert "Status: done" in archived_plan + assert "### Post-Close Delivery" in archived_plan + assert "outside the closed repository plan" in archived_plan + assert f"plans/{archive_path.name}" in current_index_row + assert "stable-delivery handoff" in current_index_row + assert "external reconciliation verified" not in current_index_row + assert "## Active Plan:" not in (PROJECT_ROOT / "PLANS.md").read_text(encoding="utf-8") def test_review_signal_audit_keeps_group_data_outside_toolkit_authority() -> None: