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. The step-by-step gate procedure is in references/mergeability-gate.md (load it when entering that phase).

Dependency declaration (read before composing)

This skill is a same-repo LOCAL SIBLING. A consuming orchestrator MUST declare the dependency at its own distribution surface and PROBE for this skill before spawning. The probe is a tool call, not an assertion from recall (A9 SUPERVISED EXECUTION; truth #2 CONTEXT EXPLICIT):

test -f ../shepherd-driver/assets/shepherd-driver-prompt.md \
  && test -f ../shepherd-driver/assets/completion-schema.json \
  && echo "shepherd-driver present" \
  || echo "MISSING shepherd-driver - stop and ask the operator"

On a probe MISS the orchestrator stops and asks the operator rather than re-implementing the loop inline (avoids HAND-ROLLED HALLUCINATION and PHANTOM DEPENDENCY).

This skill itself COMPOSES apm-review-panel. A consuming orchestrator inherits that transitive dependency; the spawned shepherd-driver subagent PROBES for it at preflight (all load-bearing panel assets under $REPO_ROOT/.agents/skills/apm-review-panel/) and returns status: blocked ONLY on a genuine asset MISS, before any checkout (see the spawn body Step 0.0). Note: a missing skill TOOL is NOT a miss -- in the normal subagent context the panel is executed INLINE from its on-disk SKILL.md + schemas (Step X.1.1), which is a first-class path, not a fallback.

Convergence loop contract (per PR)

The shepherd-driver subagent runs this loop (full detail in the spawn body):

1. Phase X.0 -- fetch + classify copilot-pull-request-reviewer[bot] inline review per assets/copilot-classification-prompt.md.
2. Phase X.1 -- run the apm-review-panel against the PR: via the skill tool if present, otherwise (the normal subagent case) execute it INLINE from its on-disk SKILL.md + schemas. Both paths produce the same single recommendation comment.

…