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 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; 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 18 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.
• Canonical-owner gate (driver-enforced). Every fix gets one architecture classification vs .github/instructions/architecture.instructions.md; a new owner, centralization, or split-authority repair needs the full dual guardrail (behavioral + static + test_architecture_* + mutation break) before ready-to-merge. shepherd-driver enforces and returns it; the orchestrator only records the evidence.
• 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.