apm-issue-autopilot

# apm-issue-autopilot - intake-to-merge issue orchestrator

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 an A11 RECONCILIATION LOOP, MANUALLY INVOKED, over a
queue of issues each driven to a terminal state under non-determinism.
It generalizes [batch-bug-shepherd](../batch-bug-shepherd/SKILL.md)
from bugs-only to ANY issue type, and promotes the full
[apm-triage-panel](../apm-triage-panel/SKILL.md) rubric to the central
front gate. It does NOT re-implement triage, panel review, or the
per-PR convergence loop -- it COMPOSES existing skills.

## What it composes (do not re-implement)

- [apm-triage-panel](../apm-triage-panel/SKILL.md) -- the triage
  rubric, run per issue in DIRECT (orchestrator-return) mode.
- [shepherd-driver](../shepherd-driver/SKILL.md) -- the per-PR drive-
  to-merge convergence loop and cross-PR mergeability gate (which in
  turn composes apm-review-panel).
- [pr-description-skill](../pr-description-skill/SKILL.md) -- authors
  the anchored, mermaid-validated body of the ONE issue PR opened at
  Phase 4 acceptance-close (see `assets/acceptance-observer.md`). The
  PR body is never hand-rolled.

All three are same-repo LOCAL SIBLINGS. This skill DECLARES each
dependency here AND in `apm.yml`, and PROBES for each at its use-site
(Phase 1 triage, Phase 4 PR-open, Phase 5 shepherd) with a tool call --
never an assertion from recall (A9 SUPERVISED EXECUTION).

## Hard boundaries

- MANUAL invocation only. No event triggers, no label triggers, no
  gh-aw. Labels (`status/accepted`, `status/shepherding`) are WRITTEN
  for bookkeeping but are NEVER the trigger.
- Triage is paramount. The autopilot ESCALATES to the maintainer by
  default; auto-implementation is the narrow exception, reached only
  for a clear, bounded, high-confidence accept the maintainer
  approved.
- ONE consolidated triage review for the whole batch, not drop-by-
  drop. Exactly one human checkpoint (Phase 2).
- Never auto-merge. Mergeability is the terminal state; the human
  approves the protected merge.
- Escalation NEVER auto-closes or auto-declines an issue. It surfaces
  the issue to the maintainer running the session and leaves it for
  human action (inherits batch-bug-shepherd terminal-handling).

## Architecture invariants

- **Fan-out, not serial.** Triage, solution-pipeline (and its Plan
  lenses + per-wave task children), and shepherd-driver all run as
  parallel child threads via the runtime `task` affordance. A
  single-loop variant is an anti-pattern. Subagent capacity is
  UNLIMITED and is NEVER a deferral reason.
- **Worktree isolation, with one-writer integration.** Every solution-
  pipeline and shepherd-driver child runs in its OWN git worktree (one
  per issue/PR). Within Phase 4, a pipeline child further spawns ONE
  task child per task PER WAVE, each in its OWN worktree branched off
  the issue branch at the wave base; the pipeline child is the SOLE
  WRITER of the issue branch and integrates task branches via `git
  merge --no-ff` at the wave gate. Tasks in a wave are mutually
  independent and touch disjoint files by construction (planner-
  enforced), so integration is conflict-free -- a real conflict is a
  planning error and triggers a re-plan, never a hand-resolve. Do NOT
  fan out against one shared working tree. Triage and verifier/lens
  children are read-only and may share a read-only REPO_ROOT.
- **One persisted state table.** A single `plan.md` ground-truth table
  plus a machine-readable `proceed_manifest` is the canonical session
  state (B4 PLAN MEMENTO). Reload it at every phase boundary; never
  keep parallel state in memory. The orchestrator is the SOLE writer
  (one-writer rule); children return JSON, the parent writes rows.
- **Escalate by default.** The confidence gate
  ([assets/confidence-gate-rubric.md](assets/confidence-gate-rubric.md))
  routes anything doubtful to the human. Auto-proceed is the exception.
- **Triage children are advisory-only.** A triage child runs the
  apm-triage-panel rubric and returns structured JSON. It MUST NOT
  post a comment, apply a label, touch the working tree, or use any
  GitHub safe-output channel. A child that emits a comment is a hard
  retry/fail.
- **Fold by default at the PR layer.** Inherited from shepherd-driver:
  every follow-up inside a PR's stated scope is folded; only scope-
  crossing items defer with a one-line boundary note.
- **Deterministic tool bridge.** Every consequential write (label,
  assign, PR open, push, comment, merge probe) and every present-state
  fact (CI status, mergeable, head sha, duplicate existence, PR-in-
  flight) goes through a deterministic CLI (`gh`, `git`, `uv run
  ruff`) wrapped in plan + execute + verify. Never assert these from
  recall.
- **ASCII only.** All artifacts (tables, comments, commits, the
  digest) stay within printable ASCII; status symbols `[+] [!] [x]
  [i] [*] [>]`.

## Dependency probes (run before composing)

Phase 1 (before triage fan-out):

```
test -f ../apm-triage-panel/SKILL.md \
  && echo "apm-triage-panel present" \
  || echo "MISSING apm-triage-panel - stop and ask the operator"
```

Phase 5 (before shepherd-driver fan-out):

```
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"
```

Phase 4 (before a pipeline child opens the issue PR -- the child
re-probes this in its own worktree before `gh pr create`):

```
test -f ../pr-description-skill/SKILL.md \
  && test -f ../pr-description-skill/assets/pr-body-template.md \
  && echo "pr-description-skill present" \
  || echo "MISSING pr-description-skill - stop and ask the operator"
```

On a probe MISS, STOP and ask the operator to restore the sibling; do
NOT re-implement the composed logic inline.

## Phases

Work through the