workflow: audit pr-contract versions and migrate PR #7343 to v2

[ll7]

Parent and dispatch role

• Parent migration programme: workflow: replace the PR Markdown parser contract with compact pr-contract.v2 metadata #7665.
• Representative live target: draft PR fix: fail closed on Robot SF gate evidence #7343.
• Initial inventory on 2026-08-25: nine open PRs; only fix(benchmark): make release doctor CI evidence robust to concurrency cancellations (#7880) #7887 contains pr-contract:v2.
• Exact observed fix: fail closed on Robot SF gate evidence #7343 head: 5b1308eb9d4015232200d99d5f7cd37d4e27e1de.
• fix: fail closed on Robot SF gate evidence #7343 changes only workflow, developer documentation, tooling, and tests; it is suitable for change_class: tooling.
• No open PR covered this residual slice when prepared.

Agent execution contract

archetype: workflow-migration
resource: local
one_pr: true
external_write: one-reviewed-pr-body-edit
v1_removal_authorized: false
branch_protection_change_authorized: false
claim_boundary: workflow-compatibility-only

Inputs

Affected files:

• scripts/dev/audit_pr_contract_versions.py (new inventory tool)
• scripts/dev/pr_contract_v2.py (reuse; no duplicate parser)
• scripts/dev/check_pr_followups.py (reuse)
• tests/dev/test_audit_pr_contract_versions.py (new tests)
• tests/dev/test_check_pr_followups.py
• tests/test_ci_script_contract.py
• docs/context/evidence/issue_<this issue>_pr_contract_v2_live_migration/ (receipt)
• docs/context/issue_7665_pr_contract_v2.md
• .github/PULL_REQUEST_TEMPLATE/pr_default.md
• live PR fix: fail closed on Robot SF gate evidence #7343 body (one authenticated body edit after revalidation)

Prerequisites: current origin/main; gh CLI with authenticated read access for the inventory
tool; no external dataset, checkpoint, scheduler, or private service. The one PR-body edit is
permitted only after exact-head and changed-path revalidation per Part B.

Goal

Add a read-only, testable inventory for PR contract versions, migrate one representative non-research PR from the compatibility body to a valid pr-contract.v2 block, and record the live validation/CI behavior. Preserve every existing hard gate and all human-readable information.

Read first

• parent workflow: replace the PR Markdown parser contract with compact pr-contract.v2 metadata #7665;
• scripts/dev/pr_contract_v2.py;
• scripts/dev/check_pr_followups.py;
• tests/dev/test_check_pr_followups.py;
• docs/context/issue_7665_pr_contract_v2.md;
• .github/PULL_REQUEST_TEMPLATE/pr_default.md;
• live PR fix: fail closed on Robot SF gate evidence #7343 at its current head and body.

Part A — Read-only inventory tool

Add one small tool, suggested path:

scripts/dev/audit_pr_contract_versions.py

The tool must:

1. Accept a repository name and obtain open PR metadata through gh or a supplied JSON fixture.
2. Reuse scripts/dev/pr_contract_v2.py; do not duplicate the parser.
3. Classify each PR as:
   • v2_valid;
   • v2_invalid;
   • v1_compatibility (no v2 marker);
   • body_missing or another explicit unavailable state.
4. Record PR number, URL, author, draft state, head SHA, contract class when valid, and a credential-free remediation summary.
5. Support deterministic JSON output and a fail-closed --check mode.
6. Never edit a PR, expose tokens, or infer scientific validity.
7. Permit offline tests using fixture JSON; tests must not require network access.

--check should fail when any v2 marker is malformed. It may report v1-compatible PRs without failing during the compatibility period. Add an explicit option or policy constant for later retirement, but do not enable retirement behavior in this issue.

Part B — Migrate live PR #7343

Before any write:

1. Re-fetch fix: fail closed on Robot SF gate evidence #7343.
2. Require it to remain open and draft.
3. Require the exact head to remain 5b1308eb9d4015232200d99d5f7cd37d4e27e1de, or stop and post the changed head/body to this issue for re-admission.
4. Re-check its changed paths. Stop if the scope is no longer workflow/tooling/docs/tests only.
5. Save a SHA-256 digest of the pre-edit body in the issue-scoped receipt; do not commit the full volatile body twice.

Prepend a valid v2 block while preserving the complete existing human body. The intended declaration is:

change_class: tooling
linked_issues:
  closes: []
  relates:
    - 7665
    - <this issue number>
deferred_work:
  status: open
  issues: []
  reason: "After merge and observation on main, a maintainer must separately apply the reviewed main-protection ruleset change requiring merge-queue-gate. This issue does not authorize that ruleset change."
evidence:
  applicability: na
  tier: null
  result: na
domain_approval:
  required: false
  status: not_required
  domains: []
  note: "NA - control-plane workflow/tooling change; no simulation, benchmark, metric, model, safety, or publication claim."
performance:
  claimed: false
exact_head: 5b1308eb9d4015232200d99d5f7cd37d4e27e1de

Use the exact schema shape required by pr_contract_v2.py. Validate the complete proposed body locally before gh pr edit or an equivalent authenticated edit. Do not remove or rewrite the human Summary, Issue, Validation, or Follow-up sections except for a minimal correction required to avoid contradiction.

Part C — Live observation receipt

Add a compact, versioned receipt under an issue-scoped path such as:

docs/context/evidence/issue_<this issue>_pr_contract_v2_live_migration/

Record:

• repository and audit timestamp;
• exact source commit used for the inventory tool;
• open-PR counts by contract classification before and after the edit;
• target PR number, URL, author type, draft state, head SHA, changed-path class, and pre/post body SHA-256;
• local parser/check command and result;
• whether a GitHub event/check run was triggered by the body edit;
• workflow/check names, run IDs, conclusions, and exact head when available;
• if no CI event is configured for edited, state this explicitly and run the canonical remote/body validator without claiming hosted-CI coverage;
• all unavailable observations and the no-v1-removal boundary.

Do not copy credentials, webhook URLs, local absolute paths, or unrelated PR body contents into the receipt.

Acceptance criteria

• The inventory tool is deterministic for a fixed fixture and reuses the canonical v2 parser.
• A malformed v2 marker fails --check; a valid v2 block is parsed with field-specific output.
• V1-compatible PRs remain accepted/reported during this slice.
• Tests cover valid v2, invalid v2 with no v1 fallback, v1 compatibility, missing body, duplicate PR numbers, and credential-safe output.
• fix: fail closed on Robot SF gate evidence #7343 is edited only after exact-head and changed-path revalidation.
• The migrated body retains all prior human information and passes the canonical PR-body validator.
• The v2 declaration is tooling, non-evidence-bearing, non-performance, and records the deferred branch-protection action without authorizing it.
• The receipt records before/after body digests and live check behavior at the unchanged fix: fail closed on Robot SF gate evidence #7343 head.
• No v1 parser removal, branch-protection mutation, merge, benchmark action, or scientific claim occurs.

Validation

uv run pytest tests/dev/test_audit_pr_contract_versions.py -q
uv run pytest tests/dev/test_check_pr_followups.py -q
uv run pytest tests/test_ci_script_contract.py -q
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
uv run ruff format --check scripts/dev/audit_pr_contract_versions.py tests/dev/test_audit_pr_contract_versions.py
git diff --check
PR_READY_MODE=final BASE_REF=origin/main scripts/dev/pr_ready_check.sh

Also record the exact live inventory and PR-body validation commands. Use the actual new test path if repository conventions require a different name.

Non-goals

• no v1 parser removal or deprecation warning;
• no mass edit of open PRs;
• no migration of research-, benchmark-, metric-, evidence-, paper-, or performance-facing PRs;
• no branch-protection or ruleset write;
• no merge or approval of fix: fail closed on Robot SF gate evidence #7343;
• no inference that schema validity proves implementation correctness, domain validity, or merge readiness.

Stop conditions

Stop and apply state:blocked when:

• fix: fail closed on Robot SF gate evidence #7343 closes, loses draft status, changes head, or gains non-tooling/evidence-sensitive paths before migration;
• the proposed block cannot preserve its deferred follow-up under the current schema;
• the canonical validator changes and the migration requires weakening a hard gate;
• another open PR implements the same inventory and live-migration receipt;
• authenticated PR-body edit permission is unavailable.

Completion handoff

The implementation PR must use Closes #<this issue> and Relates #7665. After merge, post the merged commit, inventory command, receipt path, #7343 body-edit timestamp/digests, and observed check run IDs to #7665. Keep #7665 parked. A separate author decision is required before any v1 retirement or branch-protection change.

[ll7]

Claiming this issue for implementation (agent-claims/issue-7892).

• Machine/thread: local autopilot loop (worktree-based)
• Planned branch: feat/issue-7892-pr-contract-v2-migration
• Scope: Part A inventory tool + Part B fix: fail closed on Robot SF gate evidence #7343 migration + Part C live receipt; no v1 removal, no branch-protection change.
• Stale-claim cleanup: claim is released when the implementation PR merges or the run is abandoned with a handoff comment.