feat(release): define qualification evidence contracts

[JerrettDavis]

Description

Define the canonical, versioned evidence contracts required before Headroom can safely qualify exact main SHAs and migrate publication to a protected release branch.

The release migration preflight found that #1490 provides deterministic runtime rollout identity, but X-102 and its required evidence contracts do not exist on main. This PR implements the earliest prerequisite, X-001A. It deliberately does not create release, retarget Release Please, or alter publication behavior.

Related planning work: X-001A and H-106.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that changes existing behavior)
• Documentation update
• Performance improvement
• Code refactoring (no functional changes)

Changes Made

• Added Draft 2020-12 schemas for candidate manifests, gate results, versioned policy, integration results, benchmark result references, and qualification manifests.
• Added shared artifact, producer, evidence, rollout, override, revocation, and Gate B runtime-payload-equivalence identities with fail-closed constraints.
• Added six valid examples and negative tests for schema-version drift, unsafe rollout overrides, revocation, incomplete Gate B identity, unexpected fields, and invalid A1/B experiments.
• Added ADRs for main/release semantics, immutable artifact identity, A1-versus-B benchmarking, the black-box benchmark boundary, and auditable overrides.
• Declared the already-locked jsonschema package as a direct development dependency.
• Merged current upstream main and retained upstream's Ruff 0.16.3 pin.

Testing

• Contract tests pass
• Release-workflow tests pass
• PR-governance tests pass
• Ruff check passes
• Ruff format check passes
• New tests cover fail-closed behavior

Latest focused validation

python -m pytest \
  tests/test_release_contracts.py \
  tests/test_release_workflows.py \
  scripts/tests/test_pr_governance.py -q

87 passed in 16.28s

ruff check release tests/test_release_contracts.py
All checks passed!

ruff format --check tests/test_release_contracts.py
1 file already formatted

The combined local suite that included tests/test_rollout.py could not collect in the isolated conflict-resolution worktree because that worktree did not contain the locally built headroom._core extension. The contract, workflow, and governance suites above ran successfully. GitHub CI is authoritative for the full matrix.

Real Behavior Proof

• Environment: Windows 11, PowerShell, Python 3.12.13, and jsonschema 4.26.0.
• Steps: Validate every checked-in example against the canonical local schema registry; validate a real resolve_rollout({}).to_dict() snapshot; mutate schema versions, rollout eligibility, revocation, evidence status, Gate B equivalence, A1/B optimization state, and unknown fields.
• Observed: Valid examples and the runtime rollout snapshot validate. Fail-closed negative cases are rejected.
• Not tested or activated: No release branch, ruleset, lifecycle variable, promotion flow, benchmark dispatch, release-policy check, or publication path was created or enabled.

Runtime Rollout Safety

• Rollout-managed features: None. This PR consumes the rollout snapshot identity introduced by feat: add deterministic runtime rollout controls #1490.
• Minimum rollout channel: Stable.
• Stable/default behavior changed: No runtime or publication behavior changes.
• Kill switch / disable path: Not applicable; these contracts are inert until later producers and controllers consume them.
• Unsafe override required: No. An unsafe rollout override is explicitly ineligible for qualification.
• Qualification impact: Establishes the X-001A wire contracts only. It does not claim qualification or create the release-policy check.
• Rollback path: Revert the contract commit. No remote branch, ruleset, secret, variable, tag, release, or registry state is mutated.

Review Readiness

• Self-review completed
• Ready for human review

Checklist

• Follows repository style guidelines
• Includes corresponding documentation
• Adds tests for the new contracts and negative cases
• Focused tests pass locally
• Does not manually edit CHANGELOG.md; Release Please owns it

Screenshots

Not applicable. This PR defines machine-readable contracts and architecture decisions.

Additional Notes

Current release path

main push
  -> Release Please PR targeting main
  -> merge
  -> tag and GitHub Release
  -> release.yml (PyPI/npm/GitHub Packages) and docker.yml (GHCR)

A published GitHub Release can still reach publication jobs. H-106 must remain inactive until X-102 can assemble authoritative qualification evidence and emit the stable release-policy check. H-107 must add the final publication guard.

Dependency justification

jsonschema is mature, pure Python, and already present in uv.lock through existing dependencies. This PR makes it direct without adding or upgrading a resolved package.

Next bounded work

Continue with H-101, then the remaining evidence producers and X-102. Do not activate H-106 merely because these schemas have landed.

[github-actions]

PR governance

This PR does not yet satisfy the required template fields:

• Fill in Real Behavior Proof → Environment.
• Fill in Real Behavior Proof → Exact command / steps.
• Fill in Real Behavior Proof → Observed result.
• Fill in Real Behavior Proof → Not tested.
• Fill in Runtime Rollout Safety → Rollout-managed feature(s).
• Fill in Runtime Rollout Safety → Minimum rollout channel.
• Fill in Runtime Rollout Safety → Stable/default behavior changed.
• Fill in Runtime Rollout Safety → Kill switch / disable path.
• Fill in Runtime Rollout Safety → Unsafe override required.
• Fill in Runtime Rollout Safety → Qualification impact.
• Fill in Runtime Rollout Safety → Rollback path.
• Check I have performed a self-review before requesting human review.
• Check This PR is ready for human review or convert the PR back to draft.

Please update the PR body, or move the PR back to draft while it is still in progress.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!