Require shared accepted-iteration summaries for Crane PR updates

[mrjf]

Background

During the githubnext/apm Python-to-Go migration, the long-running Crane PR stayed stale while later accepted iterations continued to land. The PR body still described an older iteration, while the real state had moved ahead through later commits and issue comments. That made reviewers ask whether the PR was actually tracking the latest work.

APM fixed this locally by adding an Accepted Iteration Summary section to its Crane workflow prompt. That local prompt requires Crane to build one shared accepted-iteration summary and reuse it everywhere: PR body, PR comment, migration issue comment, and repo-memory history.

Problem

For a long-running Crane migration, a PR is the main review surface. If the PR body or comments lag behind the latest accepted commit, reviewers have to reconstruct state from commit logs, issue comments, workflow runs, and repo-memory. That is fragile and makes a completed or near-completed migration look abandoned or misleading.

The default push-to-pull-request-branch safe output also emits a generic push comment, but that is not enough. Reviewers need the content of the accepted iteration: what changed, what score moved, what command or milestone advanced, and which commit/run proved it.

Proposed implementation

Update upstream workflows/crane.md with a dedicated Accepted Iteration Summary contract after the verification step.

The prompt should require Crane to construct a short shared summary for every accepted iteration before updating any output surface. Include these fields when available:

• Iteration number and accepted status.
• Current milestone or focus.
• Concise change summary with up to three compact bullets.
• Commit short SHA linked to the commit URL.
• Workflow run URL.
• Migration score, best score, and signed delta.
• Progress or parity counts, such as parity_passing / parity_total.
• CI fix-attempt count when greater than zero.

Then require the same summary to be reused in:

• The PR body.
• A new explicit PR comment via add-comment for existing PR updates.
• The migration issue status or per-iteration comment.
• The repo-memory iteration history entry.

For existing PRs, the prompt should explicitly say: use push-to-pull-request-branch, then also emit an add-comment safe output. Do not rely on the generic push comment as the only reviewer-facing update.

The summary should stay compact, roughly ten bullets or 1000 characters max. It should link to full evidence instead of pasting full diffs or long logs.

Suggested test coverage

Add a prompt-level test similar to the local APM test in tests/unit/test_crane_workflow_prompt.py that asserts:

• Accepted Iteration Summary exists in workflows/crane.md.
• The prompt mentions a single shared source summary.
• The prompt mentions all four output surfaces: PR body, PR comment, migration issue comment, and repo-memory history.
• The prompt mentions add-comment and push-to-pull-request-branch.

Acceptance criteria

• Every accepted existing-PR iteration creates a contentful PR comment.
• The PR body reflects the latest accepted iteration or points clearly to it.
• The migration issue and repo-memory history use the same facts as the PR update.
• A reviewer can understand the latest accepted commit without reading raw workflow logs.

Provenance

This came from the githubnext/apm Crane migration experience, especially githubnext/apm#91 and githubnext/apm#78.