workflow: replace the PR Markdown parser contract with compact pr-contract.v2 metadata

[ll7]

Archetype Metadata

archetype: refactor
evidence_tier: idea
linked_policy:
  - docs/context/issue_3472_pr_body_contracts.md
  - docs/context/issue_1512_issue_archetypes.md
  - .github/PULL_REQUEST_TEMPLATE/pr_default.md

Inputs

Affected files:

• scripts/dev/check_pr_followups.py
• tests/dev/test_check_pr_followups.py
• tests/test_ci_script_contract.py
• .github/PULL_REQUEST_TEMPLATE/pr_default.md
• docs/context/issue_3472_pr_body_contracts.md

Prerequisites: current origin/main; preserve the existing v1 parser and all current hard-gate
behavior during the bounded first slice. No external dataset, checkpoint, scheduler, or private
service is required. The first implementation PR must remain limited to the v2 schema/parser,
template emission, compatibility fixtures/tests, and migration documentation; removal of v1 is
explicitly deferred.

Goal

Separate the human PR narrative from the machine-enforced PR contract. Replace most heading and free-form Markdown parsing with a compact, schema-validated pr-contract.v2 block while keeping all current evidence, approval, follow-up, performance, and exact-head gates.

Evidence

Audit snapshot: main at aab84b50518e92e0aff7ec66a6fdbd0d1fa4cc3f.

The default PR template is 7,332 bytes and contains many sections that apply only to specific change classes. A normal support or documentation PR must still encounter and populate numerous research-oriented fields with NA explanations.

scripts/dev/check_pr_followups.py then reconstructs the contract from free-form Markdown. It contains custom logic for:

• heading and section extraction;
• continuation-line parsing;
• placeholder and option-list detection;
• linked issue and closing-keyword detection;
• residual-scope inference;
• evidence-sensitive title, path, and prose triggers;
• domain-approval fields and exact checklist labels;
• bot-only body detection;
• exact-head SHA carriers.

The validator therefore depends on exact headings and wording while also trying to infer intent from prose. This is hard to maintain, produces false positives, and makes the template larger because machine fields must remain visible as Markdown labels.

Proposed Contract

Add one hidden or bounded machine-readable block, for example:

<!-- pr-contract:v2
change_class: tooling
linked_issues:
  closes: [123]
  relates: [456]
deferred_work:
  status: none
  issues: []
evidence:
  applicability: na
  tier: null
  result: na
domain_approval:
  required: false
  status: not_required
performance:
  claimed: false
-->

The exact representation may differ, but it must be versioned, schema-validated, and independent of Markdown heading order.

Use a small declared change_class vocabulary. Suggested classes are:

• docs;
• tooling;
• runtime;
• benchmark_or_metric;
• paper_or_claim;
• performance.

The schema should require only the fields relevant to the declared class. Changed paths, title signals, and labels may still detect an implausibly weak declaration, but they should not be the primary parser for the contract.

Bounded First Slice

1. Define and validate pr-contract.v2.
2. Make the default PR template emit v2.
3. Keep the existing v1 Markdown parser for PRs without a v2 marker.
4. Migrate the existing docs-only, tooling, benchmark/evidence, and performance fixtures.
5. Do not remove v1 support until open PRs and compatibility fixtures no longer depend on it.

Implementation Instructions

1. Build a field-level map from every current template field and every check_pr_followups.py gate to one of:
   • a v2 schema field;
   • a generic human-body quality check;
   • an independent path/title consistency guard;
   • a deprecated v1-only compatibility rule.
2. Define a strict v2 schema. Reject unknown fields, invalid enum values, duplicate issue references, contradictory declarations, and missing class-specific fields.
3. Fail closed when a v2 marker exists but the block is malformed. Do not silently fall back to v1.
4. Reduce the human template to a small stable narrative, for example:
   • Summary;
   • Why / user value;
   • What changed;
   • Validation / proof;
   • Risks and rollback;
   • Follow-up or residual scope.
5. Keep research-result prose visible when the PR is evidence-bearing, but store the machine-required status fields in v2.
6. Preserve the current domain-aware approval semantics. A docs or tooling PR may opt out only when changed paths and content are consistent with that class.
7. Preserve performance evidence requirements for perf(...) changes.
8. Preserve exact-head SHA validation. If SHA carriers move into v2, keep the same fresh-head and invalid-carrier behavior.
9. Keep open-follow-up issue verification and residual-scope closure checks.
10. Split the validator internally into small responsibilities:
    • body quality;
    • v1 compatibility parsing;
    • v2 schema parsing;
    • path/title consistency;
    • remote issue-state verification;
    • report rendering.
11. Document a clear migration path for bots and agents that currently generate the old headings.

Information-Preservation Gate

The v1-to-v2 field map is the required gate. Every current enforced field and condition must have a destination.

The following may not be weakened:

• substantive changes require a human-authored summary;
• declared deferred work requires an open follow-up issue or explicit disposition;
• residual scope cannot be silently closed;
• evidence-sensitive changes require correct evidence applicability, tier, result classification, and domain approval;
• performance claims require measured proof;
• exact-head carriers must match the evaluated head;
• malformed or missing required data fails closed.

At least 98% of reusable guidance must remain in the template, schema documentation, or linked archetype guide. All hard gates must remain at 100%.

Acceptance Criteria

• A docs-only PR can satisfy the contract without filling a page of NA fields.
• A benchmark- or claim-facing PR cannot avoid evidence and approval fields by declaring tooling when its changed paths or title contradict that declaration.
• The v2 parser does not depend on Markdown heading order or exact narrative labels.
• A malformed v2 block fails with field-specific remediation.
• Existing v1 fixtures retain their current pass/fail outcome during the compatibility period.
• check_pr_followups.py is materially smaller or is split into focused modules with lower branch complexity.
• The human template is substantially shorter while every current hard gate remains enforced.

Verification Gates

Run at minimum:

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/check_pr_followups.py tests/dev/test_check_pr_followups.py

Add explicit fixtures and tests for:

• minimal valid docs v2;
• minimal valid tooling v2;
• benchmark v2 missing evidence fields;
• paper-facing v2 missing approval;
• performance claim missing measurements;
• malformed YAML or duplicate keys;
• unknown fields and enum values;
• declared class inconsistent with changed paths;
• v2 marker present but invalid, with no v1 fallback;
• v1 compatibility parity;
• exact-head SHA match and mismatch;
• deferred work with closed, missing, and open follow-up issues.

Run the new workflow against at least one live migration PR before removing any current required check.

Non-Goals

• Do not weaken evidence, approval, follow-up, performance, or exact-head policy.
• Do not infer scientific validity from a schema-valid body.
• Do not redesign issue archetypes in this issue.
• Do not remove v1 support in the first PR.

Related

• ci: enforce PR body, follow-up, and domain-aware approval contracts #3472
• docs/context/issue_3472_pr_body_contracts.md
• .github/PULL_REQUEST_TEMPLATE/pr_default.md
• scripts/dev/check_pr_followups.py
• tests/dev/test_check_pr_followups.py

Residual next slice

The bounded first slice is complete. Keep #7665 open and parked for one separately admitted migration slice. The remaining scope is limited to (1) inventorying existing open PRs that still use v1, (2) migrating one representative non-research PR and observing its live CI path, and (3) only then deciding whether v1 retirement has evidence-preserving prerequisites. No v1 removal or branch-protection change is authorized by this residual slice.

This residual is workflow-only and makes no benchmark or research claim.

schema: goal_autopilot_preparation.v1
repository: ll7/robot_sf_ll7
issue: 7665
source_body_sha256: cc7066ad7910c60a469489e99060273456155bf000d2c965a72b639fc0cf7f3b
source_comments_sha256: 
audit_schema: open_issue_contract_audit.v1
audit_digest: 1c191411793929640684e0827d763f3a2009a8682ab98dcefa8c2ded3e54f4ea
audit_classification: state_conflict
next_action: reconcile_state_labels
authority: lifecycle_owner
execution_mode: lifecycle
preferred_worker: MaxRunner
expected_pr_runner_label: runner:max
implementation_admitted: False
state_ready_change_proposed: False
mutation_batch: open-issues-20260830-04

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]

Autopilot implementation admission

• Claim: agent-claims/issue-7665 anchored at eabba3b6add9aa0b06a23440e4f0fcd4f30806de
• Branch: autopilot/issue-7665-20260822
• Worktree: /home/luttkule/git/robot_sf_ll7.worktrees/issue-7665-20260822
• Scope: bounded v2 schema/parser, default-template emission, v1 compatibility fixtures/tests,
  and migration documentation; v1 removal is deferred.
• Validation: focused parser/contract tests, Ruff, and the repository readiness path required by
  the issue contract.
• Cleanup: release the claim after a merged PR or record the exact validation/blocker state and
  preserve the worktree for handoff if delivery cannot proceed.

[ll7]

First slice delivered

PR #7762 merged successfully at
37a44055ea2cd94a6993a38719699a7cfa753407.

• Delivered: strict pr-contract:v2 schema/parser, default-template emission, v1 compatibility,
  migration documentation, focused fixtures, and shared v2 exact_head carrier enforcement.
• Proof: final head 1f3a92ae4241ea67aee2326e8bf3dc5ed14a4cbe; full local readiness passed against
  origin/main=eabba3b6; 397 focused tests passed; hosted required checks and exact-head changed
  coverage passed; guarded merge receipt status was ready before the squash merge.
• Claim boundary: workflow/control-plane implementation only; no benchmark, planner, model, or
  paper-facing result is claimed.

The issue remains open because live migration of existing PRs and eventual v1 removal were
explicitly deferred by the bounded first-slice contract. The transient implementation claim is
released with reason merged; residual work is parked for a separately admitted migration slice.