Toolkit 0.10.0: local review provider, diagnostics and OCR controls

[xeonvs]

Scope and delivery state

Tracks #181 and #182; replaces planning Draft #183 with the owner's approval.
Target: toolkit 0.10.0. The approved execution plan and source-review decisions
are in PLANS.md. This remains a Draft: no merge, stable release, package
publication or issue closure is authorized.

Implementation and Draft handoff are complete. All 13 checks pass on final head
6169a649c57295b1ec2437824385e644b5dea364, with verified SSH signature and matching
local/remote refs. The old remote branch is removed without losing any
commits. Owned temporary data is recoverably cleaned; #181/#182 and v0.10.0 remain open.

Implemented

• Shared reporting and provider boundaries. Provider-neutral admitted review
  facts, health, findings, coverage, warnings, token/tool usage and verified MCP
  attribution are shared. GitLab keeps its acquisition, receipts, posting caps,
  suppression, discussions and approval transactions. Characterized GitLab
  rendering remains covered by parity/regression tests; this does not implement
  a GitHub adapter or a generic forge API framework.
• Explicit local provider. preflight --local and review --local use the
  same toolkit/OCR/LLM/tool-use/finalization pipeline. Local execution resolves
  immutable commit/range inputs, ignores inherited forge identity, makes no
  GitLab acquisition/publication calls, and rejects unsupported MR context or
  context adapters. No worktree snapshot, repository scan or resumed-session
  workflow is introduced.
• Local delivery. Every DLP-admitted finding is emitted to plain Markdown
  and the console, without posting caps, remote badges or HTML disclosures.
  --report defaults to the --result path plus .md; it requires a fresh,
  distinct target and publishes a complete owner-only artifact without replacing
  existing files. The ordinary JSON artifact remains separate. Failures report
  a closed stage-specific summary, never untrusted findings or a fabricated
  forge receipt.
• Mandatory evidence remains mandatory. Registry validation and the toolkit
  self-query do not substitute for an actual completed evidence-summary call.
  Claimed OCR usage is reconciled with the real action record. Optional external
  MCP servers cannot replace the built-in evidence server.
• Private debug bundle. --debug-dir requires a fresh 0700 directory and
  --local, and conflicts with legacy private retention. It records actual
  configuration/identity/evidence/MCP/preview/process/admission/DLP/cleanup/report
  decisions, bounded raw and finalized artifacts, and value-free DLP locations,
  actions, sizes and digests. Files use 0600; truncation, missing/unavailable
  captures, omitted decisions and incomplete journals are explicit. Observation
  does not rescan DLP, skip checks, retain the OCR runtime session or replace the
  original review outcome when a diagnostic write fails.
• Reasoning controls. OCR_LLM_REASONING_EFFORT accepts unset/empty or
  case-insensitive none|minimal|low|medium|high|xhigh|max. Unset adds no overlay;
  explicit none is sent. Chat Completions uses reasoning_effort; Responses
  uses reasoning.effort and preserves siblings. Equal manual values are allowed;
  conflicting values/types and nonempty Anthropic shortcuts fail in the shared
  configure/preflight owner. Existing review effort and token budgets are unchanged.
• Privacy-independent progress. OCR_REVIEW_PROGRESS=true enables only
  toolkit phase labels and a 30-second heartbeat on stderr, capped at 120 messages.
  It never reads OCR result/stderr/session artifacts or changes the agent audience.
  Progress stays out of JSON, Markdown, receipts and DLP inputs. Timer shutdown,
  closed/full output, resource failures and signal paths are tested.

Verification already completed

• Final exact-head checks: CI 34221864029
  passes all five OS/Python jobs, 1700 tests, 86.73% total coverage and all
  four scoped floors. Build artifacts,
  Security,
  CodeQL
  and Dependency review
  pass. Gitleaks 8.24.3 scanned the complete 12-commit feature history with no leaks.

• Security review completed before this follow-up push. Codex Security scan
  0431df4b-1ce4-4d8b-9771-9395c8b45298 is sealed with zero findings for
  8ae890b..63387c3: 25 source inventory files plus all supplemental changed
  tests/configuration/docs were reviewed. Its service retained an intermediate
  deferred reconciliation row, so sealed coverage is marked partial despite
  the final six completed surfaces; this limitation is explicit, not a claim of
  fully clean automated coverage. TAC access and scan token accounting were
  unavailable. The later small CI-progress/test correction received separate
  pre-push static security and semantic review.

• Overall self-review corrected CI progress that stayed at preview while OCR
  ran: observer state now reaches nonlocal progress paths while local report
  creation remains local-only. The orchestrator matrix adds on/off assertions.
  Current OCR-pin and renamed README-heading assertions are also synchronized;
  historical fixtures and all safety assertions remain intact. The follow-up
  matrix passed all test executions (1700 tests on the Linux coverage owner,
  86.73% total coverage and all four scoped floors). Its one formatting-only
  correction was applied exactly as hosted Ruff requested. All 13 checks on
  5a33e0f then passed: CI 34221252576, Build 34221252503, security
  34221252488, CodeQL 34221252685 and dependency review 34221252618.
  Gitleaks 8.24.3 scanned the complete 11-commit feature history with no leaks.
  The final docs-only head also passed, as recorded above.

• Fresh Linux amd64 OCR 1.11.6 qualification passed in
  34218232310,
  including all upstream asset/checksum readback and the complete current suite.
  Evidence, human source-review conclusion, manifest and executable OCR pins are
  promoted together. The installed Darwin arm64 binary is updated without a
  post-waiver local launch. Stable toolkit example pins remain at the published
  release; external Draft qualification must install the exact Draft artifact.

• The initial hosted five-platform matrix passed 1694 tests per platform and
  found two stale environment-inventory expectations for the new controls.
  Those expected defaults are synchronized without relaxing assertions. Quality,
  package build, dependencies, secrets, Bandit and CodeQL passed; final-head
  full-suite/coverage checks now pass as recorded above.

• Runtime/reporting/controls and installed-artifact matrix: 829 tests and
  400 subtests passed. Installed direct-wheel and sdist-derived-wheel scenarios
  cover real Git, subprocess and stdio MCP boundaries, hostile repository imports,
  optional external MCP, polluted CI identity, forged mandatory usage, clean/
  finding/warning/partial/budget/filtered/failure outcomes, and normal/debug/progress
  parity. SIGTERM is exercised against both the synthetic OCR child and ocr-ci.

• Maintainer qualification matrix: 114 tests passed, including rejection of
  missing current promotion proof and independence of historical readback from
  changed live defaults. Recorded 1.11.4/1.11.5 evidence files remain unchanged.

• Checksum-verified real OCR 1.11.6 on Darwin arm64 passed the complete current
  no-LLM qualification suite: existing numeric, budget, grouping, JSON, Rules and
  comment contracts; 16 language routes; default OCaml/Kotlin-script test exclusions;
  and reasoning wire capture for unset, none and high in both OpenAI protocols.

• Ruff, formatting, mypy and runtime Bandit checks passed for the implemented
  slices. Gitleaks 8.24.3 scanned the tree and complete feature history through
  c38ca40; final-head hosted gates subsequently passed as recorded above.

The installed integration helper substitutes only the external OCR collaborator;
it is not another production review engine. Real-OCR probes use the actual verified
binary with local deterministic peers. The reasoning capture peer deliberately
rejects the request without executing a model, so this proves the wire format,
not provider acceptance or application. No real LLM calls were made.

OCR 1.11.6 changes reviewed and accounted for

• OCaml/ReasonML allowlist and built-in Rules, plus Kotlin .kts routing and test
  exclusions: consumed selection changes, now covered by live qualification.
• Upstream Action controls/progress: feature input, not an Action dependency;
  its human-audience stderr streaming is not adopted by the toolkit.
• OpenAI/Responses/Anthropic header-timeout wiring: native transport correction;
  no additional toolkit timeout API or result-schema adaptation.
• Node launcher signal forwarding, editor cancellation, viewer line numbering
  and Pages documentation: upstream-only boundaries, not new toolkit workflows.
• No independent provider-profile, scan or telemetry backlog activation is claimed.

Draft handoff checklist

• Fresh hosted Linux qualification, complete release-asset readback, exact OCR
  1.11.6 pin promotion and local installed-binary update.
• README, configuration, local/debug guidance, operations/decision flow,
  compatibility, strategy, roadmap, backlog, threat model and evidence matrix
  reconciled. Existing result/receipt/context schemas remain unchanged.
• Complete immutable feature-range security review and overall self-review,
  with the sealed coverage-metadata limitation described above. The owner approved
  read-only security preflight; tests and OCR probes were not rerun locally.
• Full final-head quality, packaging, security and required hosted checks.
• External GitLab/local/debug/progress and reasoning qualification checklist
  recorded in docs/local.md#configured-external-qualification, including exact
  Draft artifact identity and explicit unverified provider application.
• Final exact-head readback, clean worktree and recoverable temporary-data cleanup.
  The user waived further local validation runs; remaining automated validation
  was completed in GitHub Actions.

External provider/model/protocol qualification must test unset, explicit none
and the intended nonempty effort, including provider acceptance and evidence of
application. HTTP 200 alone is insufficient; unsupported or unprovable behavior
must remain explicit. No automatic weakening of DLP/security, model substitution,
merge, release or issue closure is part of this Draft delivery.