shepherd-driver - per-PR drive-to-merge convergence loop

shepherd-driver - per-PR drive-to-merge convergence loop

This SKILL.md is the natural-language module derived from a genesis design packet; refactors re-run the genesis skill from that packet.

This skill is a COMPOSED BUILDING BLOCK, not a user-facing entrypoint. It was extracted (genesis R3 EXTRACT) from batch-bug-shepherd when a second consumer (apm-issue-autopilot) needed the same per-PR convergence loop. Both orchestrators COMPOSE this skill; neither re-implements the loop. It in turn COMPOSES the apm-review-panel skill for the review pass -- it does NOT re-implement panel review.

Boundary (what this skill does and does NOT do)

DOES: take ONE PR that already exists and drive it to a terminal landing-ready state; resolve cross-PR merge conflicts; emit the PR-facing advisory and supersede comments; return a schema-valid completion_return.

Does NOT: triage issues, decide which issues are worth fixing, open the first PR for an issue, choose the batch, or maintain the orchestrator's ground-truth table. Those are the parent orchestrator's responsibility. If you find yourself triaging or opening greenfield PRs, you are in the wrong skill.

How an orchestrator composes this skill

The parent orchestrator, for each PR in its batch, spawns ONE shepherd-driver subagent with the spawn body in assets/shepherd-driver-prompt.md. The orchestrator passes the inputs that prompt declares (PR_NUMBER, ISSUE_NUMBER, AUTHOR, HEAD_REPO, HEAD_BRANCH, MAINTAINER_CAN_MODIFY, REPO_ROOT, ORIGIN, optional PANEL_PRIOR). The subagent owns the whole convergence loop end-to-end and returns a completion_return.

After every shepherded PR returns ready-to-merge, the orchestrator runs the conflict-resolution phase: probe mergeability and, on DIRTY / BEHIND / CONFLICTING, spawn one conflict-resolution subagent per assets/conflict-resolution-prompt.md.