phx-watch-pr

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.

1. 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.

1. Never merge or deploy — watching and --fix authorize neither action.
2. --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.

1. 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