workflow(7520): stabilize PR metadata before expensive integration checks

[ll7]

Parent and dependency

Parent policy: #7520.

Depends on the report-only admission classifier in #7647. This issue may define fixtures and the metadata contract before #7647 completes, but it must not enable automatic admission invalidation or workflow suppression until the pilot reason codes are reviewed.

Related current-check classification owner: #7416.

Observed problem

PR title/body reconciliation, exact-head review publication, and automated metadata repair can occur after hosted checks have started. GitHub then cancels or supersedes PR-body and contract runs, starts replacements, and invalidates exact-head evidence that was correct before the mutation.

The repository now distinguishes some superseded checks from real failures under #7416, but it does not prevent avoidable metadata churn from consuming CI and review capacity.

Objective

Define a versioned PR metadata epoch and preparation-to-integration transition. Metadata must be reconciled before a candidate enters expensive integration. A later material metadata mutation must invalidate the admission epoch explicitly and return the PR to cheap preparation checks before new full CI or exact-head review is admitted.

Metadata epoch

The epoch must bind at least:

• PR number and repository;
• exact head SHA and base SHA;
• normalized title and body digest;
• linked-issue and closing-reference set;
• label set relevant to admission and holds;
• requested-reviewer state;
• domain/author approval requirements;
• producer and observation source;
• invalidation reasons.

Cosmetic or generated-body differences may be normalized only by a reviewed deterministic rule. Unknown changes are material.

Required behavior

1. Preparation writers reconcile title/body and required trailers before requesting integration admission.
2. workflow(7520): implement report-only adaptive integration admission #7647 reports whether the current metadata epoch is complete and stable enough to become an integration candidate.
3. Full CI and exact-head review bind to that epoch.
4. A material body, title, label, reviewer, base, or head mutation invalidates the epoch.
5. An invalidated PR returns to cheap checks; old successful evidence remains historical and cannot authorize merge.
6. The system reports why an epoch changed and which checks must be repeated.

In scope

• Add a deterministic metadata canonicalizer/digest or extend the existing PR-metadata owner.
• Add an explicit preparation-complete / integration-epoch record without introducing a parallel readiness framework.
• Update canonical PR writers to publish metadata before integration admission where practical.
• Detect writes that occur after admission and classify their effect.
• Add fixtures for body-only reconciliation, exact-head trailer change, cosmetic normalization, base refresh, label hold, reviewer request, automated comment-only review, and concurrent writer mutation.
• Report superseded-check churn and invalidated exact-head reviews during the decide: adaptive integration admission without capping agent implementation #7520 pilot.

Out of scope

• no prohibition on necessary PR-body correction;
• no conversion of stale evidence into current evidence;
• no merge authorization from a metadata digest;
• no replacement of friction: distinguish queued CI starvation from superseded-check failures #7416 check-state classification;
• no broad rewrite of every bot or reviewer;
• no activation before workflow(7520): implement report-only adaptive integration admission #7647 report-only evidence is reviewed.

Acceptance criteria

• A preparation-complete metadata epoch is deterministic for identical PR state.
• Full CI and exact-head review records name the epoch they evaluated.
• A material metadata or head/base mutation invalidates the epoch and cannot inherit merge authority.
• Cosmetic normalization is explicit, deterministic, tested, and narrowly bounded.
• Automated writers can detect an active integration epoch and either avoid the write or record the required re-admission.
• Superseded checks remain non-success under friction: distinguish queued CI starvation from superseded-check failures #7416; replacement checks are not misreported as historical failure.
• The pilot reports the number of expensive checks and reviews invalidated by later metadata mutation.
• All read-only and check-only modes perform no GitHub mutation.

Candidate paths

• existing PR metadata digest/reconciliation helpers under scripts/dev/;
• canonical PR body/comment writers;
• pr_loop_policy.py and workflow(7520): implement report-only adaptive integration admission #7647 integration;
• focused tests under tests/dev/;
• concise workflow documentation.

Validation

uv run pytest -q tests/dev -k "pr_metadata or metadata_epoch or pr_loop_policy or ci_status"
uv run ruff check scripts/dev tests/dev
uv run ruff format --check scripts/dev tests/dev
git diff --check

Claim boundary

Workflow consistency, CI economy, and exact-head traceability only. A stable metadata epoch does not prove implementation correctness, scientific validity, review approval, or merge readiness.

schema: goal_autopilot_preparation.v1
repository: ll7/robot_sf_ll7
issue: 7649
source_body_sha256: 8346c7d7840e40f6026db5c6bc17efa040d002fb557763d83520788b456d612b
source_comments_sha256: 
audit_schema: open_issue_contract_audit.v1
audit_digest: d786f5a92e6ce3a2ff06d411d96bfdc16a9baadf72ba34c61c7518379d0a59e4
audit_classification: blocked
next_action: resolve_named_blocker
authority: blocker_owner
execution_mode: blocker
preferred_worker: MaxRunner
expected_pr_runner_label: runner:max
implementation_admitted: False
state_ready_change_proposed: False
mutation_batch: 20260830-goal-autopilot-prepare

This packet is preparation evidence only. It never overrides live labels, exact claim state, branch state, typed dependencies, domain gates, compute authority, release authority, or scientific evidence rules.

[ll7]

blocked-triage-v1: blocker resolved

• Blocked-by: #7647 — the report-only adaptive integration admission classifier. workflow(7520): implement report-only adaptive integration admission #7647 is
  CLOSED (2026-08-21) with the merged implementation PR feat(workflow): add report-only integration admission classifier (#7647) #7656 (integration_admission_report.v1).
• Secondary condition ("must not enable automatic invalidation or workflow suppression until the
  pilot reason codes are reviewed"): the sibling issue ci(7520): run cheap policy preflights before full environment setup #7648 was implemented and merged as
  ci(workflow): use lightweight environment setup for metadata and policy workflows (#7648) #8013 (ci(workflow): use lightweight environment setup for metadata and policy workflows,
  2026-08-30), which activated the cheap-preflight behavior — demonstrating the pilot reason
  codes were reviewed and accepted for the same decide: adaptive integration admission without capping agent implementation #7520 lane.
• Resolution: the entry gate recorded in this issue body is satisfied; the issue's
  implementation contract (objective/scope/acceptance criteria) is complete and no active
  claim, worktree, or job exists. Repairing lifecycle labels: state:blocked and
  dependency:has-blockers are stale with respect to current evidence.