/phx-watch-pr

name: phx-watch-pr
description: Watch an Elixir/Phoenix PR with an Amp Orb keep-alive lease until required
  non-deployment CI is green and review threads are resolved.

Watch PR — Amp-Native Lifecycle

Use the `elixir_phoenix_watch_pr` plugin tool. Do not launch `gh pr checks --watch`, `gh run watch`, a foreground sleep loop, or the copied Claude watcher script: none of those owns an Amp Orb keep-alive lease.

Iron Laws

1. **Acquire one bounded keep-alive lease** — start the plugin lifecycle once, then let its durable state and dedupe handle polling and plugin reloads. 2. **Deployment is never readiness** — deployment, release, preview, production, and prod checks are reported under `excludedChecks`; they are never counted as passing or failing required CI. 3. **Never merge or deploy** — watching and `--fix` authorize neither action. 4. **`--fix` uses the same worker thread** — the plugin serializes one concise event turn at a time and directs that turn to the installed `phx-pr-review` workflow for actionable review feedback or failed required CI. Validate the cause before editing. 5. **Every watch is bounded** — timeout and every other terminal path release the lease. A timeout is incomplete, never success.

Start

Parse the PR number/URL and flags, then call:

elixir_phoenix_watch_pr {
  "action": "start",
  "pr": "<number-or-url>",
  "checksOnly": false,
  "fix": false
}

Map `--checks-only` and `--fix` to booleans. Map `--max-hours`, `--quiet-minutes`, and `--poll-seconds` to `maxDurationHours`, `quietPeriodMinutes`, and `pollIntervalSeconds`. Defaults are 2 hours maximum, 15 minutes quiet, and 60 seconds polling. Report the tool's initial snapshot and then stop taking turns; the plugin wakes this thread only for actionable failures or feedback and terminal outcomes.

Event Handling

• Unchanged snapshots do not wake the model.
• A changed head SHA resets readiness but does not itself wake the model.
• Failed or cancelled required non-deployment CI wakes the model once per

distinct actionable snapshot. Pending and passing progress keeps polling inference-silent.

• Excluded deployment-like checks appear separately in explicit status and

terminal summaries. Their transitions do not reset readiness or wake the model.

• Any unresolved review thread keeps the lease active.
• A head push, required-check transition, review, or comment resets the quiet

clock. This includes a review with no unresolved thread or dedicated check, but routine non-actionable activity does not wake the model.

• With `--fix`, unresolved feedback explicitly loads `phx-pr-review`; required

CI failures include check names and links. Re-fetch threads or inspect logs, fix only valid branch-owned causes, verify, push the authorized PR branch update, reply, and resolve where appropriate. Do not blindly rerun shared CI.

• Required CI must remain green with zero unresolved threads and no relevant

activity for the full quiet period before success releases the lease. Never accept an early green snapshot as immediate readiness.

Status and Stop

Use the same tool with `"action": "status"` or `"action": "stop"`. Stop is idempotent and releases the lease; it does not delete durable history.

Post-Completion Boundary

The plugin registers an optional durable Amp webhook and stores its bearer URL in the owner-only credential file reported by the tool. If a repository administrator configures GitHub to send PR review/check events to that URL, a later event can wake the paused Orb and probe the authoritative PR state. Webhook events must identify the exact watched PR number or current watched head SHA; empty or unrelated repository events are ignored.

The plugin never changes GitHub webhook settings. Without that external setup, polling ends after the quiet period and a later human comment cannot wake a paused Orb. Say this explicitly; do not imply polling continues after lease release.

Reference

• `references/watcher-mechanics.md` — lease, durability, filtering, webhook,

and billing behavior