# Verification Governance

This document summarizes the public verification-governance contract that sits on top of the repository test workflow.

For the authoritative execution order and acceptance rules, follow:

- `tests/TEST_SOP.md`
- `tests/E2E_TESTING_NOTICE.md`
- `tests/E2E_TESTING_SOP.md`
- `docs/release/ci_regression_policy.md`

## Standard Governance Checks

The standard local and CI-parity validation flow includes two explicit governance checks:

- `python scripts/verify_quality_governance.py`
  - keeps `pyproject.toml` coverage settings aligned with the staged ratchet policy in `tests/coverage_governance_policy.json`
  - protects mutation-threshold, SOP-guidance, and coverage-policy drift
- `python scripts/verify_test_debt_governance.py`
  - fails closed on stale or under-documented entries in `tests/skip_policy.json`
  - fails closed on stale or under-documented entries in `tests/mutation_survivor_allowlist.json`

Backend unit coverage should be gathered through the shared helper instead of ad hoc `coverage run` invocations:

```bash
python scripts/run_backend_coverage.py --start-dir tests --pattern "test_*.py" --enforce-skip-policy tests/skip_policy.json --coverage-json .tmp/coverage/backend_unit_coverage.json
```

## Coverage Review Surface

Before any future coverage-floor promotion, review hotspot-family coverage with:

```bash
python scripts/report_coverage_governance.py --coverage-json <path-to-coverage.json>
```

This report is the governed review surface for critical families such as:

- `safe_io`
- security boundaries
- connector config and ingress seams
- config and bootstrap seams

Retained release-cycle review evidence lives in:

- `tests/coverage_promotion_reviews.json`

The current enforced stage is `ratchet-55`, which means the repository floor is now
`fail_under = 55.0`. The promotion is backed by two consecutive ratchet-45 release-cycle
reviews with immutable release commits, full-suite artifact hashes, all required hotspot
percentages, and named regression owners.

## Governance Baseline

- `tests/coverage_governance_policy.json` is the source of truth for the current enforced floor, next planned ratchet target, hotspot families, and temporary exceptions.
- `pyproject.toml` coverage settings must stay aligned with the active stage floor declared in `tests/coverage_governance_policy.json`.
- `tests/coverage_promotion_reviews.json` is the retained promotion-evidence ledger for reviewed hotspot summaries across release cycles.
- Ratchet-55 evidence must identify consecutive release boundaries, the reviewed commit,
  full-suite command and artifact SHA-256, all required hotspot percentages, and owned suites.
- Rollback is atomic: a future approved rollback must move both the policy current stage and
  `pyproject.toml` floor together; config drift fails the governance check.
- Test-debt governance remains fail-closed; review metadata such as `reason` and `review_after` must stay current for governed skip-policy and mutation-survivor entries.
- Detailed CI-gate composition and merge requirements remain documented in `docs/release/ci_regression_policy.md` and `tests/TEST_SOP.md`.