batch-bug-shepherd

# batch-bug-shepherd - Outer-loop bug-queue orchestrator

This skill is an A10 ORCHESTRATOR-SAGA over fan-out waves (triage,
strategic-alignment, PR-cross-reference, fix, drive-to-merge,
conflict-resolution) with a persisted ground-truth table between
phases. It COMPOSES the
[shepherd-driver](../shepherd-driver/SKILL.md) skill as the per-PR
drive-to-merge engine -- it does NOT re-implement the review +
fold + push + CI loop. shepherd-driver transitively COMPOSES
[apm-review-panel](../apm-review-panel/SKILL.md); this skill inherits
that edge and never reaches into panel internals directly. It also
COMPOSES the `apm-ceo` persona (host-repo agent at
`.apm/agents/apm-ceo.agent.md`) for the strategic-alignment gate,
which checks every LEGIT bug against `PRINCIPLES.md` before allowing
fix / drive work to proceed. Per-PR shepherding is delegated to
shepherd-driver; per-issue verification, strategic alignment,
PR-in-flight branching, greenfield fix dispatch, post-wave
mergeability re-probe, and the cross-session table are owned here.

The skill is ADVISORY at the panel layer and EXECUTIVE at the
orchestrator layer: it WILL push commits, open PRs, post comments,
close superseded PRs. Every consequential write goes through a
deterministic CLI (`gh`, `git`, `uv run ruff`) wrapped in plan +
execute + verify (A9 SUPERVISED EXECUTION).

## Architecture invariants

These 17 rules bind every wave. The one-line essence is below; the
FULL binding text (rationale, edge cases, inherited-from-driver
detail) lives in `references/invariants.md`. **Load
`references/invariants.md` before planning Phase 0** -- the summaries
here are dispatch anchors, not the complete contract.

- **Fan-out, not serial.** Triage / alignment / fix / drive run as
  parallel child threads; single-loop is an anti-pattern.
- **Verify before fix.** No fix dispatched until the bug reproduces
  on HEAD (`LEGIT`); `UNCLEAR` -> human, `FIXED-AT-HEAD` -> close.
- **PR-in-flight detection is mandatory.** `gh pr list` every legit
  issue before any fix; duplicating community work is the worst
  failure mode this skill defends against.
- **Drive, do not split shepherd from complete.** ONE shepherd-driver
  subagent owns the whole per-PR loop; no separate panel + completion
  waves.
- **Mutation-break gate.** A regression trap is real only if deleting
  the production guard makes the test FAIL.
- **Superseding-PR fallback (inherited).** On contributor-fork push
  failure the driver opens an authorship-preserving PR under
  `microsoft/apm` and returns `superseded`.
- **Single-writer interlock.** One idempotent panel comment + one
  driver advisory per PR; the orchestrator never posts to a PR.
- **ASCII only.** Printable ASCII in every artifact (cp1252 safety).
- **Lint contract is the push gate (inherited).** `ruff check` +
  `ruff format --check` silent before any `git push`.
- **Ground-truth table is the single source of truth.** One plan.md
  table, rewritten on every return, re-read at each wave start
  (B4 PLAN MEMENTO + B8 ATTENTION ANCHOR).
- **Cross-session message reports only on green.** Failures stay in
  the subagent session until resolved or escalated to a human.
- **Operator visibility is a contract.** Progress mermaid + live
  table at every boundary; dispatch table before every fan-out
  (`assets/progress-diagram.md`).
- **Mergeability is post-wave truth.** Re-probe `mergeStateStatus`
  before claiming ready; Phase 5 resolves conflicts with
  `--force-with-lease` (bare `--force` prohibited).
- **Two-comment-per-PR cap.** Driver advisory + resolution
  confirmation only; the in-loop panel comment is idempotent and does
  not add to the count. No third comment, ever.
- **Bias toward folding (inherited).** The driver folds in-scope
  follow-ups into the PR; only genuinely separable work becomes a
  tracking issue.
- **Strategic-alignment gate before drive.** Phase 1.5 runs one
  `apm-ceo` subagent per LEGIT row; demoted rows skip Phase 2-5; the
  gate fails open to `aligned`, aborts only if the persona /
  `PRINCIPLES.md` is missing.
- **Worktree isolation.** Every fix and drive child runs in its OWN
  git worktree (one per issue/PR); never fan out mutating children
  against a shared `REPO_ROOT` (they would race on `.git/index` and
  the checked-out branch). Triage is read-only and may share one.

## Composition with shepherd-driver

`shepherd-driver` is the per-PR drive-to-merge engine. This skill
spawns ONE shepherd-driver subagent per PR (both in-flight community
PRs and own greenfield fix PRs) using the spawn body
`../shepherd-driver/assets/shepherd-driver-prompt.md`. The driver owns
the whole convergence loop -- Copilot classification, apm-review-panel,
fold-vs-defer, push, CI watch, with its own caps -- and
returns a `completion_return` matching
`../shepherd-driver/assets/completion-schema.json`
(`ready-to-merge` | `advisory-with-deferred` | `superseded` |
`blocked`).

The cross-PR conflict-resolution / mergeability phase is ALSO
shepherd-driver's: Phase 5 delegates to
`../shepherd-driver/assets/conflict-resolution-prompt.md` with the
step-by-step gate in
`../shepherd-driver/references/mergeability-gate.md`.

shepherd-driver is a same-repo LOCAL SIBLING declared in `apm.yml`
(`dependencies.apm: [../shepherd-driver]`). PROBE for it before the
drive wave -- a tool call, not an assertion from recall (A9 SUPERVISED
EXECUTION):

```
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, STOP and ask the operator to restore the sibling; do
NOT re-implement the loop inline (avoids HAND-ROLLED HALLUCINATION and
PHANTOM DEPENDENCY). The driver transitively composes
`apm-review-panel` and probes for it at its own preflight, returning
`status: blocked` on a miss. The orchestrator NEVER reaches into
shepherd-driver or apm-review-panel internals.