feat(workflow): add PR contract-version inventory and migrate PR #7343 to v2

[ll7]

Summary

Deliver issue #7892's pr-contract.v2 live-migration slice in three parts:

• Part A — scripts/dev/audit_pr_contract_versions.py: read-only inventory of open PR contract versions using the canonical pr_contract_v2 parser. Classifies each PR as v2_valid / v2_invalid / v1_compatibility / body_missing, supports deterministic JSON output, offline JSON fixtures, and a fail-closed --check mode (malformed v2 markers fail; v1-compatible PRs are reported, not failed, during the compatibility period).
• Part B — live-migrated draft PR fix: fail closed on Robot SF gate evidence #7343 to a valid pr-contract:v2 block after exact-head (5b1308eb9...) and changed-path revalidation. The complete human body is preserved; the declared block is change_class: tooling, relates: [7665, 7892], with the deferred main-protection ruleset change recorded but not authorized.
• Part C — docs/context/evidence/issue_7892_pr_contract_v2_live_migration/README.md: live observation receipt with inventory counts before/after, pre/post body digests, local parser and follow-up analyzer results, and the explicit no-CI-event-on-edited observation.

Why / user value

Open PRs keep shipping without a machine-readable contract, and the v1 Markdown parser is the only classification path. This slice adds a deterministic inventory so the migration to pr-contract.v2 can be tracked per PR, proves the live migration path on one representative tooling PR, and records the exact validation/CI behavior — all without weakening any hard gate or removing v1 support.

What changed

• scripts/dev/audit_pr_contract_versions.py (new, 170 lines)
• tests/dev/test_audit_pr_contract_versions.py (new, 230 lines, 14 tests)
• docs/context/evidence/issue_7892_pr_contract_v2_live_migration/README.md (receipt)

Validation / proof

• uv run pytest tests/dev/test_audit_pr_contract_versions.py -q → 14 passed
• uv run pytest tests/dev/test_check_pr_followups.py tests/test_ci_script_contract.py -q → regression, 232 passed combined
• uv run ruff check scripts/dev/audit_pr_contract_versions.py scripts/dev/pr_contract_v2.py scripts/dev/check_pr_followups.py tests/dev/test_audit_pr_contract_versions.py → clean
• uv run ruff format --check scripts/dev/audit_pr_contract_versions.py tests/dev/test_audit_pr_contract_versions.py → clean
• git diff --check → clean
• Live inventory: 8 open PRs before migration (all v1_compatibility); 7 v1_compatibility + 1 v2_valid (fix: fail closed on Robot SF gate evidence #7343) after
• Proposed and live fix: fail closed on Robot SF gate evidence #7343 bodies both parse ok via parse_pr_contract_v2 and pass analyze_body (follow-up analyzer)

Risks and rollback

• The one external write is the fix: fail closed on Robot SF gate evidence #7343 body edit (prepend-only, human body preserved; documented digests allow restoration). No merge, approval, v1 removal, branch-protection, or ruleset change is made.
• The inventory tool requires gh read access or a fixture; failures are explicit.

Follow-up / residual scope

• v1 parser removal and any main-protection ruleset change remain separately authorized (see workflow: replace the PR Markdown parser contract with compact pr-contract.v2 metadata #7665 and the fix: fail closed on Robot SF gate evidence #7343 deferred-work declaration).

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 87a1fd1c-c984-4336-ba45-97cbda641bda

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🔍 PR Contract Check Summary

Overall Status: 🟢 PASSED

Check	Status	Description
1. Closes-discipline	✅ PASSED	Demand Refs #N for epic issues
2. Closure declaration	⚠️ WARNING	Require Closes/Refs for title issues
3. State-refresh-only	✅ PASSED	Reject docs/context state updates
4. Evidence hygiene	✅ PASSED	Checks markers and provenance fields
5. Evidence writer usage	✅ PASSED	Require the shared marked writer path
6. Successor discipline	⚠️ WARNING	Require successor statement on multi-PR issues
7. Worker-lane label	⚪ None	Label PRs from cheap worker lane
8. Placeholder docstring ratchet	✅ PASSED	Reject NEW TODO/empty docstrings in added diff lines

⚠️ Warnings

• WARN: PR title references issue fix: fail closed on Robot SF gate evidence #7343, but the PR body lacks a closure declaration (e.g., 'Closes fix: fail closed on Robot SF gate evidence #7343' or 'Refs fix: fail closed on Robot SF gate evidence #7343').
• WARN: Issue fix: fail closed on Robot SF gate evidence #7343 has already been referenced in 1 merged PR(s), but the PR body does not contain a successor statement ('successor slice' or 'does not duplicate').

ℹ️ Info

• No worker-lane provenance detected.

---

This check is mechanized. Please resolve any blockers to pass CI.

[ll7]

Exact-head self-review

• Evaluated Head SHA: 2cff7d83ebab577cbd9dcc6f1d5cb98ee94cc5bd
• Base SHA: 097084dfd53a984f082bae22e31630eee00778dd (current origin/main at review)
• Metadata Digest: fbf80dcf2ebf2b1b1122605ef72d6944b84aed1456272ebc6ea0eb99f3035b0a

Intended design

Issue #7892 requires (A) a read-only inventory tool for PR contract versions, (B) live migration of draft PR #7343 to a valid pr-contract:v2 block after exact-head revalidation, and (C) a live observation receipt. The implementation satisfies all three: audit_pr_contract_versions.py classifies PRs via the canonical parser with deterministic JSON/--check; #7343's body was prepended with the exact declared v2 block (tooling, relates 7665+7892, deferred main-protection ruleset) via REST at unchanged head 5b1308eb9; the receipt records inventory counts, digests, and the no-CI-event-on-edit observation.

Validation

• pytest tests/dev/test_audit_pr_contract_versions.py → 14 passed
• pytest tests/dev/test_check_pr_followups.py tests/test_ci_script_contract.py → 232 passed (regression)
• ruff check + ruff format --check on new/changed surfaces → clean
• git diff --check → clean
• pr_ready_check.sh (final, with PR body) → passed
• Hosted checks on head 2cff7d83e: 37 success, 2 expected skips, 0 failures
• Base-sensitive selector: gate not required (no base-sensitive files changed)
• Current-base CAS: passed (base fresh at 097084dfd, head matches)
• Evidence-registry ratchet: baseline refreshed (evidence_tree manifest only); 54 tests passed
• Docs-evidence-integrity: catalog.yaml entries added for the new evidence bundle; local check passed

Findings disposition

No actionable findings. Workflow/tooling-only change with live migration evidence; no benchmark, metric, or scientific claim.

gate-verdict: accepted @ 2cff7d83ebab577cbd9dcc6f1d5cb98ee94cc5bd
base-policy: ordinary-cas @ 2cff7d83ebab577cbd9dcc6f1d5cb98ee94cc5bd
pr-metadata: reconciled @ fbf80dcf2ebf2b1b1122605ef72d6944b84aed1456272ebc6ea0eb99f3035b0a

[ll7]

Exact-head self-review

• Evaluated Head SHA: 157b225a94ab769a6099c9bd8bbae14f4444033c
• Base SHA: 097084dfd53a984f082bae22e31630eee00778dd (current origin/main after branch refresh)
• Metadata Digest: fbf80dcf2ebf2b1b1122605ef72d6944b84aed1456272ebc6ea0eb99f3035b0a

Intended design

Issue #7892 requires (A) a read-only inventory tool for PR contract versions, (B) live migration of draft PR #7343 to a valid pr-contract:v2 block after exact-head revalidation, and (C) a live observation receipt. The implementation satisfies all three; this head is a content-identical main refresh (the only delta from 2cff7d83e is the merged .github/workflows/codeql.yml dependency bump #7878).

Validation

• pytest tests/dev/test_audit_pr_contract_versions.py → 14 passed
• pytest tests/dev/test_check_pr_followups.py tests/test_ci_script_contract.py → 232 passed (regression)
• ruff check + ruff format --check on new/changed surfaces → clean
• git diff --check → clean
• pr_ready_check.sh (final, with PR body) → passed
• Hosted checks on head 157b225a9: 38 success, 1 expected skip, 0 failures
• Base-sensitive selector: gate not required (no base-sensitive files changed)
• Current-base CAS: passed (base fresh at 097084dfd, head matches)
• Evidence-registry ratchet: baseline refreshed (evidence_tree manifest only); 54 tests passed
• Docs-evidence-integrity: catalog.yaml entries added for the new evidence bundle; local check passed

Findings disposition

No actionable findings. Workflow/tooling-only change with live migration evidence; no benchmark, metric, or scientific claim.

gate-verdict: accepted @ 157b225a94ab769a6099c9bd8bbae14f4444033c
base-policy: ordinary-cas @ 157b225a94ab769a6099c9bd8bbae14f4444033c
pr-metadata: reconciled @ fbf80dcf2ebf2b1b1122605ef72d6944b84aed1456272ebc6ea0eb99f3035b0a