Release 0.8.0: remediation threads, GitLab commands, and docs

.github/workflows/ci.yml

@@ -40,7 +40,13 @@ jobs:
         with:
           python-version: ${{ matrix.python }}
       - run: uv sync --frozen
-      - run: uv run pytest --cov=ocr_toolkit --cov-report=term-missing --cov-fail-under=70
+      - name: Test with boundary coverage gates
+        run: |
+          uv run pytest --cov=ocr_toolkit --cov-report=term-missing --cov-fail-under=85
+          uv run coverage report --include=src/ocr_toolkit/ocr_result.py,src/ocr_toolkit/preflight.py --fail-under=80
+          uv run coverage report --include=src/ocr_toolkit/posting/workflow.py,src/ocr_toolkit/posting/gitlab.py,src/ocr_toolkit/posting/snapshot.py,src/ocr_toolkit/posting/gitlab_approval.py --fail-under=80
+          uv run coverage report --include=src/ocr_toolkit/review_runner.py,src/ocr_toolkit/context/broker.py,src/ocr_toolkit/context/store.py,src/ocr_toolkit/context/dlp.py,src/ocr_toolkit/posting/approval.py --fail-under=85
+          uv run coverage report --include=src/ocr_toolkit/mcp_config.py,src/ocr_toolkit/providers/gitlab.py,src/ocr_toolkit/providers/gitlab_context.py,src/ocr_toolkit/providers/gitlab_discussions.py,src/ocr_toolkit/providers/gitlab_remediation.py,src/ocr_toolkit/context/policy.py,src/ocr_toolkit/result_contract.py --fail-under=85
 
   quality:
     name: quality

README.md

@@ -27,17 +27,17 @@ Stable distributions are published to [PyPI](https://pypi.org/project/open-code-
 
 ## How reviews evolve
 
-On a successful rerun, the toolkit replaces untouched OCR-only notes instead of accumulating stale reviews. A human reply transfers that discussion to the team: the conversation is preserved and a matching finding is suppressed. Reply with `/ocr suppress` to keep a discussion open without future repeats, or `/ocr resolve` to suppress it and resolve the discussion after the next successful posting transaction.
+On a successful rerun, the toolkit replaces untouched OCR-only notes instead of accumulating stale reviews. A human reply transfers that discussion to the team: the conversation is preserved and a matching finding is suppressed. Reply with `/ocr suppress` or `@<live-bot-username> suppress` to keep a discussion open without future repeats; use the corresponding `resolve` command to resolve it after the next successful posting transaction. For example, a bot named `mr.bot` accepts the exact reply `@mr.bot resolve`.
 
 Suppression uses both the GitLab diff position and a stable finding fingerprint, so ordinary line shifts do not normally bring the same bug back. A materially changed finding can still receive a new discussion. See [GitLab review operations](docs/operations.md) for the complete lifecycle, posting modes, permissions, failure behavior, and Mermaid state diagram.
 
-After every current review note publishes, the GitLab adapter can add a conservative approval bound to receipt v5's exact reviewed source SHA and merge-request author. This write is enabled by default; set `OCR_AUTO_APPROVE=false` when the bot must remain comment-only. Complete optional MR metadata and complete zero-record enrichment remain eligible, while degraded metadata, required context degradation, admitted mutable context, legacy receipts, publication filtering, any direct external MCP, author movement, or bot self-authorship prevents an approval write. GitLab approval rules and protected-branch policy remain authoritative. The toolkit only adds an eligible approval; it never removes an existing approval when a later review is ineligible or disabled.
+After every current review note publishes, the GitLab adapter can add a conservative approval bound to receipt v5's exact reviewed source SHA and merge-request author. This write is enabled by default; set `OCR_AUTO_APPROVE=false` when the bot must remain comment-only. DLP-clean metadata, generic discussions, and adapter records do not independently block approval, while degraded metadata, DLP rejection, required context degradation, admitted remediation history, legacy receipts, publication filtering, any direct external MCP, author movement, or bot self-authorship prevents an approval write. GitLab approval rules and protected-branch policy remain authoritative. The toolkit only adds an eligible approval; it never removes an existing approval when a later review is ineligible or disabled.
 
 Accepted tradeoffs can be recorded in `.opencodereview/accepted-decisions.md`; the evidence collector supplies only applicable target-ref decisions and never lets a source change self-authorize its review. Root and nested target `AGENTS.md`/`CLAUDE.md` guidance is similarly exposed through the existing evidence MCP with deterministic scope and precedence, while any guidance touched by the merge request is excluded. See [Accepted project decisions](docs/configuration.md#accepted-project-decisions) and [Target project guidance](docs/configuration.md#target-project-guidance) for formats and trust boundaries.
 
 ## Project architecture
 
-The shipped Repository Evidence Engine reads immutable base/head Git objects, stores bounded typed facts and deltas, creates the compact bootstrap used by OCR, and exposes detailed facts, scoped completeness, and base/head changes through the mandatory built-in read-only MCP server. Version 0.7.0 establishes protected-policy enriched reviews: they can acquire stable GitLab discussions and authorize external issue/document records through a provider-neutral stdio or HTTPS proxy before OCR. Version 0.7.1 adds closed receipt-v5 publication semantics, reconciled count-only evidence use, privacy-safe normalized token reporting, and deterministic Recommended focus ranking. The same built-in MCP exposes only opaque committed `context_list`/`context_get` handles; it has no provider network or arbitrary identifier path. Direct external MCP remains a separate privileged, comment-only operator boundary.
+The shipped Repository Evidence Engine reads immutable base/head Git objects, stores bounded typed facts and deltas, creates the compact bootstrap used by OCR, and exposes detailed facts, scoped completeness, and base/head changes through the mandatory built-in read-only MCP server. Protected-policy enriched reviews can acquire stable GitLab discussions, verified remediation history, and authorized external issue/document records before OCR. Forge-specific acquisition and posting stay at provider edges; the broker, DLP, store, MCP, receipts, and tests use common contracts so a future GitHub adapter can reuse them without inheriting GitLab API semantics. The same built-in MCP exposes only opaque committed `context_list`/`context_get` handles; it has no provider network or arbitrary identifier path. Direct external MCP remains a separate privileged, comment-only operator boundary.
 
 - [Toolkit strategy](docs/engineering/toolkit_strategy.md) - durable product boundaries, architecture, invariants, and non-goals.
 - [Bounded review context](docs/review-context.md) - protected policy, adapter protocol, GitLab discussions, opaque handles, DLP, receipt, and cleanup contracts.
@@ -58,7 +58,7 @@ ocr-ci review --result /tmp/ocr-result.json --stderr /tmp/ocr-stderr.log -- ...
 ocr-ci post --result /tmp/ocr-result.json --stderr /tmp/ocr-stderr.log
 ```
 
-See the [`examples/gitlab/ocr-review.gitlab-ci.yml`](examples/gitlab/ocr-review.gitlab-ci.yml) example, the [GitLab setup guide](docs/gitlab.md), and [GitLab review operations](docs/operations.md).
+See the [GitLab mode matrix](examples/gitlab/README.md), the complete [`ocr-review.gitlab-ci.yml`](examples/gitlab/ocr-review.gitlab-ci.yml) pipeline, the [GitLab setup guide](docs/gitlab.md), and [GitLab review operations](docs/operations.md).
 
 ## Configuration and safety
 
@@ -68,6 +68,7 @@ Repository content, OCR output, and provider responses are untrusted inputs. The
 
 ## Development and release
 
+- [Documentation index](docs/README.md)
 - [Contributing](CONTRIBUTING.md)
 - [Code of Conduct](CODE_OF_CONDUCT.md)
 - [Development guide](docs/development.md)

ROADMAP.md

@@ -11,7 +11,7 @@ flowchart LR
     M0 --> M3["M3 External MCP hardening<br/>established"]
     M1 --> M2["M2 Ecosystem and framework coverage<br/>established"]
     M1 --> M4["M4 Policy and project guidance<br/>established"]
-    M1 --> M5["M5 Bounded review-context enrichment<br/>established"]
+    M1 --> M5["M5 Bounded review-context enrichment<br/>established / in progress"]
     M3 --> M5
     M4 --> M5
     M1 --> M6["M6 Profiles and quality measurement<br/>planned / conditional"]
@@ -22,7 +22,8 @@ flowchart LR
     classDef planned fill:#57606a,stroke:#424a53,color:#ffffff
     classDef conditional fill:#9a6700,stroke:#7d4e00,color:#ffffff
 
-    class M0,M1,M2,M3,M4,M5 established
+    class M0,M1,M2,M3,M4 established
+    class M5 next
     class M6 planned
     class M7 conditional
 ```
@@ -34,7 +35,7 @@ flowchart LR
 | M2 Ecosystem and framework coverage | Established | Supply framework and template evidence selected from demonstrated use without creating framework-specific review engines. | Established evidence, snapshot/delta, scoped-completeness, and built-in MCP contracts. | Selected static plugins and template review rules have deterministic fixtures, bounds, provenance, component ownership, completeness, first-class source/target delta queries, installed-artifact validation, verified use through the existing built-in MCP, and independently read-back stable delivery. |
 | M3 External MCP hardening | Established | Qualify and document the safe-use envelope and residual limits of the shipped generic external-MCP composition boundary. | Existing external MCP and built-in composition plus BL-011 real-OCR qualification. | Canonical security and configuration guidance records the direct-composition trust boundaries, tool-name allowlist limits, server-owned object authorization, shared plan/main exposure, response/session persistence, failure degradation, and receipt non-claims observed with checksum-verified OCR and a real synthetic stdio peer. Managed OAuth remains conditional. |
 | M4 Policy and project guidance | Established | Supply relevant target-branch decisions and guidance without allowing self-whitelisting. | Evidence scoping and target/source snapshots. | Stable delivery independently proves backward-compatible structured decisions, bounded target-derived guidance, one read-only MCP lifecycle, and closure of the tracked release work. |
-| M5 Bounded review-context enrichment | Established | Extend invocation evidence with bounded forge discussions and optional external records through one provider-neutral, capability-constrained context lifecycle, without a second review engine. | Established M1, M3, and M4 boundaries plus the v0.7.0 BL-023 delivery. | The v0.7.0 release acquires bounded snapshots, applies immutable protected-target context/DLP policy, authorizes every object before opaque handle minting, projects fixed `context_list`/`context_get` tools through the existing toolkit MCP, contains OCR persistence, validates publication independently, exposes partial/degraded outcomes, and blocks automatic approval for admitted mutable context. The protected release workflow and independent external readback remain mandatory delivery evidence rather than repository-authored claims. |
+| M5 Bounded review-context enrichment | Established / in progress | Extend invocation evidence with bounded forge discussions, verified remediation history, and optional external records through one provider-neutral, capability-constrained context lifecycle, without a second review engine. | Established M1, M3, and M4 boundaries plus the v0.7.0 BL-023 delivery. | v0.7.0 establishes bounded discussion/reference acquisition. The v0.8.0 extension remains in progress until exact-head external OCR+LLM qualification proves policy-v2 remediation selection, context-store v2 and fixed MCP projection, live bot-root/mention identity, DLP isolation, comment-only remediation, provider-neutral reuse boundaries, and no raw provider-data leakage. The protected release workflow and independent external readback remain mandatory delivery evidence rather than repository-authored claims. |
 | M6 Profiles and quality measurement | Planned / conditional | Audit current OCR telemetry and result-derived review signals; add model-profile aliases only after demonstrated operational need. | Established receipt-v5 result, discussion, coverage, posting, normalized token, and reconciled MCP/evidence-use signals; a demonstrated alias need and owner-approved matrix are required only for profile implementation. | The audit either proves current bounded reporting sufficient or isolates a separately scoped provider-neutral gap; any later model profiles remain independent from explicit coverage and budget controls. |
 | M7 Later and conditional work | Conditional | Activate routing, more ecosystems, fuzzing, configuration, forge adapters, or governance work only from demonstrated need. | Milestone-specific activation signals and stable preceding contracts. | Each item meets its own trigger and ships as a coherent validated slice without weakening core invariants. |
 
@@ -44,7 +45,7 @@ flowchart LR
 - M3 is established from BL-011's real-OCR characterization of the current generic composition boundary. Direct composition is an operator-configured privileged facility, not safe author-triggered reference resolution. BL-012 remains conditional and does not block M3 or M5 when reviewed static credentials or a stdio proxy suffice.
 - M2 is established through independently verified stable delivery of its framework plugins, template rules, scoped evidence, deltas, and built-in MCP projection. Conditional future ecosystem packs remain in M7 and do not reopen M2.
 - M4 is established through independently verified v0.6.0 artifacts and later protected-target identity improvements. M5 consumes but does not reopen its policy boundary.
-- M5 is established by the v0.7.0 BL-023 release content. Direct provider-specific MCP enforcement is not a second M5 path: external records stay behind the broker, while generic direct MCP retains the established M3 operator boundary. Its dependency graph is exactly `M1 -> M5`, `M3 -> M5`, and `M4 -> M5`; it is not a gate for M6 or M7. The protected release workflow, immutable receipt, and independent registry/GitHub readback remain mandatory external delivery closure and are not inferred from this status update.
+- M5's foundation is established by the v0.7.0 BL-023 release content; its v0.8.0 remediation/provider-neutral extension remains in progress and release-deferred until external qualification of the exact feature head. Direct provider-specific MCP enforcement is not a second M5 path: external records stay behind the broker, while generic direct MCP retains the established M3 operator boundary. Its dependency graph is exactly `M1 -> M5`, `M3 -> M5`, and `M4 -> M5`; it is not a gate for M6 or M7. The protected release workflow, immutable receipt, and independent registry/GitHub readback remain mandatory external delivery closure and are not inferred from this status update.
 - The M6 measurement-gap audit can begin from receipt v5, privacy-safe normalized token buckets, and reconciled MCP/evidence-action counts delivered in v0.7.1. BL-017 may inventory M5 receipts if they exist, but M5 does not create a second telemetry implementation or exporter. BL-016 remains parked because OCR already exposes direct run-level selection.
 - Versioned documentation remains a separate MCP integration: the toolkit supplies package/version evidence but does not store documentation.
 - Additional code-hosting adapters remain conditional and GitLab-first M5 does not depend on them.

changelog.d/120.bugfix.md

@@ -0,0 +1,5 @@
+Malformed context policies, provider projections, and persisted remediation counts now fail closed at their owned contract boundaries; exclusive GitLab discussion/remediation limits and omitted reply counts now reflect only the applicable records. Operator adapters cannot request the internal remediation resource class, publishable discussion/reference text gets publication-specific DLP, and per-record text limits remain budget omissions rather than invalid-content failures.
+Toolkit-generated OCR background is now qualified by the installed, preflight-supported OCR executable under `review --preview` before model execution, with the exact production refs, rules, and selection inputs. OCR remains the sole owner of its current thresholds: a recognized soft warning enters the CI log and finalized result summary, while a recognized hard character/file-size rejection produces only an identity-bound closed numeric failure summary. Unknown preview failures remain generic and fail closed; detailed evidence stays available through the built-in MCP, and explicit truncation preserves the mandatory evidence-call instruction.
+Ordinary reviews now remove toolkit-generated evidence, bootstrap, protected rules, context, action receipts, and local DLP diagnostics after both OCR success and failure; only the closed static pre-execution status remains available for the posting handoff when OCR rejects input before model execution.
+If OCR rejects a generated background and preview cleanup also fails, the closed OCR rejection now remains available to the static posting handoff; a cleanup-only failure still blocks model execution and publication. Provider compatibility entry points also convert impossible missing projections into explicit closed errors instead of relying on runtime assertions.
+Repeated `scripts/quality.sh coverage|check` invocations now replace their own log before running, so a current result cannot include stale output from an earlier interrupted or failed invocation.

changelog.d/120.feature.md

@@ -0,0 +1,7 @@
+Extends bounded review context while preserving existing policy documents:
+
+- **Added:** `ocr.review-context-policy/v2` accepts optional `remediation_threads`; `context_list`/`context_get` expose admitted records as opaque `remediation_thread` resources from the ephemeral `ocr.context-store/v2`.
+- **Added:** the checksum-pinned GitLab example exposes `OCR_MAX_TOOLS` with default `30`, matching OCR 1.9.10, and passes it explicitly to each review so integrations can raise the per-file tool-round bound deliberately.
+- **Changed:** rollout guidance separates optional `/models` metadata validation from `ocr llm test` connectivity and from a completed review, and warns that an allowed-to-fail OCR job can leave a pipeline green without usable review evidence.
+- **Changed:** a remediation root now requires the authenticated live bot ID plus a valid toolkit marker/fingerprint, is excluded from generic discussion and reference projections, and always makes the review comment-only. DLP-clean metadata, generic discussions, and adapter records do not independently block automatic approval; DLP rejection and required-source degradation remain blocking.
+- **Migration:** existing `ocr.review-context-policy/v1` documents remain accepted for generic discussions and references. Use policy v2 only when selecting `remediation_threads`; ephemeral stores are rebuilt per run and have no migration step.

changelog.d/120.maintenance.md

@@ -0,0 +1 @@
+**Changed:** Actions storage maintenance now shards its bounded completed-run lookup by UTC day, retaining the ten-page fail-closed limit per shard. It removes completed TestPyPI preview runs after 14 days, TestPyPI development and ordinary runs after 30 days, and stable `Release` runs after 60 days; active and newer runs remain untouched. A run is no longer removed before the longer log-retention promise for its workflow. No operator migration is required.

changelog.d/120.security.md

@@ -0,0 +1 @@
+`ocr-ci review --preserve-private-artifacts` can retain owner-only OCR session/context state for local diagnosis without creating a posting receipt. It also writes a bounded, value-free `ocr.private-dlp-decisions/v1` sidecar with JSON path, detector subtype, size units, SHA-256, and explicit truncation counts so operators can diagnose conservative false-positive classes locally. Ordinary and validated GitLab merge-request execution never retain this attribution; the latter rejects the flag before OCR starts and keeps deterministic cleanup mandatory.

changelog.d/123.doc.md

@@ -0,0 +1 @@
+**Added:** navigation-only indexes at `docs/README.md`, `docs/codex/README.md`, and `docs/engineering/README.md` route users and maintainers to existing canonical contracts without changing their ownership.