spec-spine: Skill for Claude Code

/shepherd: from open PR to merged, with evidence

CI is where reality pushes back. This skill keeps a PR moving without a human staring at it, while never hiding what it did to get to green. It mirrors an orchestrator's shepherd stage: watch by head sha, remediate through the gate, bounded attempts, honest stops. Bound by .claude/rules/orchestrator-rules.md (checkpoints are real stops) and .claude/rules/adversarial-prompt-refusal.md (a coupling refusal goes to a human, not around them).

Step 0: resolve the PR

git branch --show-current
gh pr view ${ARGUMENTS:-} --json number,url,headRefName,headRefOid,baseRefName,mergeStateStatus,isDraft,reviewDecision

• No PR for the branch: stop and say so (run /ship first). Do not open one here.
• The branch must be a feature branch, never the default branch.
• Record headRefOid: every check you read is for this sha and no other.

Step 1: watch the checks (by head sha)

Poll loop discipline: start at 15 s, multiply by 1.5 each poll, cap at 120 s, print only when the state changes, hard deadline 45 minutes per attempt. Never busy-loop.

gh pr checks <number> --json name,state,bucket,link 2>/dev/null \
  || gh pr view <number> --json statusCheckRollup

Read the rollup for the recorded head sha only. Classify:

• every required check SUCCESS: go to Step 3;
• any required check FAILURE or CANCELLED: go to Step 2;
• PENDING or QUEUED: keep polling;
• a response missing the fields you need: stop as a typed failure ("cannot read a shape that cannot terminate"), never poll blind;
• the deadline passes: stop, report which checks never completed, and say the PR needs a human.

Step 2: remediate (at most two rounds)

For the failing check, fetch the evidence first:

gh run list --branch "$(git branch --show-current)" --limit 5 --json databaseId,name,conclusion,headSha
gh run view <run-id> --log-failed | tail -80

Then, on the branch:

1. Diagnose from the log tail; read the failing test or gate output, not the summary line.
2. Fix inside the spec's territory. If the failure is the coupling gate (C-001 or C-002), claim the path in the spec being implemented or add the extends edge on its owner; never edit an owning spec to ratify code that contradicts it (coherence guard: stop and report). A // Spec: comment header is the other legitimate claim for a file no frontmatter should list.
3. Run the gate exactly as AGENTS.md lists it; it must exit 0 locally.
4. /commit (conventional, spec id as scope, regenerated shards staged), then git push.
5. Re-read headRefOid. Restart Step 1's watch on the new sha with a fresh 45 minute budget. Checks from the old sha are stale; never mix them.