@1aboveio/skills 0.10.0

package/skills/cicd-pipeline/mergify/references/configuration.md

@@ -0,0 +1,183 @@
+# Mergify Configuration
+
+The four settings this skill opinionates, and the checklist that puts them in
+place. Governed by [Rule 1](../SKILL.md#rule-1--fetch-the-docs-before-writing-config):
+fetch the schema before writing any of it, and finish with `validate` **and**
+`simulate`.
+
+## The Four Settings
+
+### 1. Enqueue — auto on ready + review-PASS, manual otherwise
+
+A PR **auto-enqueues** the moment it is ready, a review has passed, and CI is
+green. Short of that it stays held, and a human enqueues it by hand with
+`@mergifyio queue`.
+
+**How:** set `merge_protections_settings.auto_merge_conditions` to that AND-list.
+Its *presence* enables conditional auto-merge; the conditions scope *which* PRs.
+The manual path is not a second setting — `@mergifyio queue` queues a PR
+regardless of `auto_merge_conditions`, and `merge_conditions` gate on CI only
+(never review), so a hand-queued PR still merges on green without a review.
+
+```yaml
+merge_protections_settings:
+  reporting_method: check-runs
+  post_comment: true
+  # AUTO-enqueue only a ready PR whose review passed; everything else waits for a
+  # human `@mergifyio queue`. "review PASS" = ≥1 approval and no open change request.
+  # `-draft` belongs HERE (don't auto-queue a draft), but stays OUT of
+  # queue_conditions/merge_conditions — see the `-draft` note further down.
+  auto_merge_conditions:
+    - "-draft"
+    - "#approved-reviews-by >= 1"
+    - "#changes-requested-reviews-by = 0"
+    - *gate
+```
+
+Why this is the default and not bare-manual: scoping auto-merge to a *passed
+review* keeps the routine case one-click-free **without** letting an unreviewed
+PR ride in — the failure a review gate exists to stop. It also avoids the mirror
+failure: the retired "auto-queue every non-draft PR" form had no review arm, so a
+green-but-unreviewed PR merged and a reviewer requesting changes could lose the
+race to the queue. The review arm is the point; the manual hatch (above) covers
+the "land it without waiting" case.
+
+**To go fully manual instead** (queueing the only entry), omit
+`auto_merge_conditions` entirely and say so in a comment — an omitted key reads as
+an oversight and someone will "fix" it back.
+
+Do **not** use `merge_protections_settings.auto_merge: true` or
+`queue_rules[].autoqueue: true` — both are deprecated.
+
+Developers enqueue by commenting `@mergifyio queue`, or by ticking the checkbox
+Mergify renders in its queue status comment (`merge_queue.queue_controls_comment`,
+default `true`). Mergify acknowledges a command with a 👍 reaction; **no 👍 means
+the command was not processed**, which is a different problem from a PR that
+failed its conditions.
+
+### 2 & 3. Batch mode, size 3
+
+```yaml
+queue_rules:
+  - name: default
+    batch_size: 3
+    batch_max_wait_time: 30 seconds
+    batch_max_failure_resolution_attempts: 10
+merge_queue:
+  max_parallel_checks: 3
+```
+
+**The default this skill ships is `batch_size: 3`** — written explicitly, never
+assumed: an unset `batch_size` silently runs the queue at Mergify's built-in
+default of 1, i.e. no batching, so the key being present is the act that turns
+batching on. With it set, Mergify does not simply test "the next three in the
+queue": priority and
+queue order seed a batch, **stacks always stay together**, and similarity (shared
+scopes, then changed directories, then queue time) fills the remaining slots.
+Related PRs enqueued together reliably ride one batch — that is how the queue
+collects a delivery — while unrelated ones may split, deliberately, so one PR's
+failure cannot drag unrelated work into a bisection. When a batch goes red,
+Mergify **bisects** it — splitting and retesting until it isolates the culprit,
+then dequeuing only that PR. Innocent PRs stay in the queue. `max_parallel_checks`
+caps how many splits run at once, so match it to `batch_size`; more is wasted.
+
+`batch_max_wait_time` is the knob that decides how eagerly the queue collects a
+batch, and it is a straight latency tax on a **lone** PR — Mergify waits the full
+window before giving up on company. Where PRs arrive one at a time, keep it at
+seconds, not minutes. Where delivery is bursty — an epic landing a stack, a set
+of related PRs expected together — a longer window (a few minutes) buys the batch
+(N PRs, one CI run) at the cost of a slightly slower lone PR. Set it from how PRs
+actually arrive, not from either extreme.
+
+**Two hard requirements:**
+
+- GitHub branch protection **"Require branches to be up to date before merging"
+  must be DISABLED.** Batches cannot merge with it on — the original PRs are not
+  up to date by GitHub's reckoning even though the batch was tested against base.
+  This is the single most common reason a batched queue never merges anything.
+- Batching disables **in-place checks**. In-place is only active when all three
+  hold: `max_parallel_checks == 1`, every queue has `batch_size == 1`, *and*
+  every queue CI is single-step (no extra `merge_conditions` — either empty or
+  identical to `queue_conditions`). A two-step CI like this repo's `*gate` +
+  `*queue_gate` fails the third condition even at `batch_size 1`. Everything
+  downstream of that (below) follows from it.
+
+Revisit the size from evidence, not taste: if batches go red often enough that
+bisection is the normal path, the changes are less independent than assumed and
+3 is too wide.
+
+### 4. Enforce head (freshness against base)
+
+```yaml
+queue_rules:
+  - name: default
+    update_method: rebase   # rebase | merge
+```
+
+**Read this before relying on it.** `update_method` governs how a PR is updated
+with its base branch **when the check is done in place** — and in-place checks
+are off whenever `batch_size > 1`. Under `batch_size: 3` the option is inert.
+
+That is not a gap. With batching, Mergify builds a **queue branch** of
+`base + batch` and runs CI there, so what gets tested is always fresh against
+base by construction. The PR's own branch simply is not what gets tested.
+
+Keep `update_method: rebase` in the config anyway, so dropping to `batch_size: 1`
+does not silently change behaviour — but comment it, or the next reader will
+believe it is doing work it is not.
+
+**If you need the PR branch itself kept fresh** (e.g. contributors run local
+checks against it), that is a separate lever:
+
+| Want | Use |
+|------|-----|
+| Fresh tree under test | Nothing — the queue branch already gives you this |
+| Rebase the PR branch, on demand | `@mergifyio update` or `@mergifyio rebase` comment |
+| Rebase the PR branch, automatically | a `pull_request_rules` entry with the `update` or `rebase` action |
+| Fresh head at enqueue time | `#commits-behind = 0` in `queue_conditions` (blocks entry rather than fixing it) |
+
+Automatic updating fights the queue — every update retriggers the PR's CI — so
+prefer on-demand unless you have a reason.
+
+## Setup Checklist
+
+1. Fetch the schema and the relevant doc pages.
+2. Copy `assets/templates/mergify.yml` → `.mergify.yml`; replace placeholders.
+3. Name the real CI check in the `gate` anchor; add the `or` exemption **only**
+   if that check is path-filtered, and list the workflow file's own path.
+4. `mergify config validate`.
+5. `mergify config simulate <PR-URL>` against a real PR — ideally one that hits
+   the exempt path, since that is where configs break.
+6. **Audit against this skill's default:**
+   `node ~/.agents/skills/mergify/scripts/audit.mjs --file .mergify.yml`.
+   (Absolute, like the watcher above: you run this from the repo being audited, where a
+   CWD-relative `scripts/…` does not resolve.)
+   It checks the shape `config validate` can't — enqueue policy (hybrid vs the retired
+   indiscriminate auto-queue), `branch_protection_injection_mode: merge`, the
+   define-once/assert-many gate anchor, `-draft` misplaced in queue/merge
+   conditions, and batch mode actually on (`batch_size: 3` — this skill's
+   default; an unset `batch_size` runs at Mergify's built-in 1, so batching
+   silently off is a real state). It **abstains** rather than guess, so a `?` means "check by hand," not
+   "fine." `--json` for machine output; exits non-zero on any warn (`--allow-warn` to
+   downgrade). Runs on the committed `.mergify.yml`, so it fits a pre-merge check.
+7. Confirm Mergify's app id: `gh api /apps/mergify --jq .id`.
+8. `gh ruleset list` — if a ruleset already covers this branch, fold these rules
+   into it (**PUT**) rather than stacking a second one. Overlapping rulesets are
+   additive and the most restrictive wins, which is a confusing way to be blocked.
+9. Inventory anything that pushes to the protected branch — the `update` rule
+   will block it. Add each as a bypass actor (GitHub Actions = `15368`):
+   `grep -rnE 'git push|create-pull-request|github-script' .github/workflows/`
+10. Apply `assets/templates/ruleset.json`. Dry-run with
+   `"enforcement": "evaluate"` first if you want to see what it would block —
+   read the results from `rule-suites`.
+11. Prove the allowed path **before** the blocked one: enqueue a PR with
+    `@mergifyio queue`, confirm the 👍, and watch `mergify queue show <PR> -v`
+    through to merge. A ruleset strict enough to block humans can also block
+    Mergify if a bypass id is wrong, and you would rather learn that while you
+    can still merge the fix.
+12. Now prove the blocked path: open a throwaway PR and try to merge it without
+    enqueuing, as a non-bypass user. GitHub must refuse, naming the ruleset.
+13. Decide the escape hatches: keep `priority_rules` (jump the line), and either
+    keep or delete the `emergency-merge` rule (skips CI, cannot be limited to
+    admins). Keep the `OrganizationAdmin` bypass either way — it is the only way
+    back in if Mergify has an outage.

package/skills/cicd-pipeline/mergify/references/diagnosis.md

@@ -0,0 +1,73 @@
+# Diagnosing A Stuck PR
+
+Two tools, two different questions — and when they disagree, the disagreement is
+itself the diagnosis. For watching a PR through to merge (a different job, with
+its own rules) see [`watch-contract.md`](watch-contract.md).
+
+## Querying PR and Queue Status
+
+### Mergify's own view — why a PR is or isn't moving
+
+```bash
+mergify queue status                    # all batches + waiting PRs
+mergify queue status --branch main      # one branch
+mergify queue status --json             # parseable
+mergify queue show <PR>                 # one PR: position, priority, CI state
+mergify queue show <PR> -v              # + full checks table and conditions tree
+mergify queue show <PR> --json
+```
+
+`mergify queue show <PR> -v` is the one to reach for. The conditions tree shows
+which conditions are met and **which single one is blocking** — that is the
+answer to "why is this stuck", and nothing else in the toolchain reports it.
+
+Queue states worth recognising:
+
+| State | Meaning |
+|-------|---------|
+| `waiting_for_batch` | Queued, not yet picked into a batch |
+| `waiting_for_previous_batches` | Blocked on an earlier batch |
+| `preparing` / `running` | Batch is being set up / running CI |
+| `bisecting` | Batch failed; splitting to find the culprit |
+| `failed` | CI failed for this batch |
+| `waiting_for_merge` | CI passed, waiting on GitHub |
+| `waiting_schedule` | Outside the configured merge schedule |
+| `frozen` | Queue is paused |
+
+### GitHub's view — the raw checks and merge state
+
+```bash
+gh pr checks <PR>                          # check-run table, exit 1 if any failed
+gh pr checks <PR> --watch                  # block until they settle
+gh pr view <PR> --json state,isDraft,mergeable,mergeStateStatus,statusCheckRollup
+gh pr view <PR> --json labels --jq '.labels[].name'   # queued / dequeued labels
+```
+
+Mergify labels a PR `queued` on entry and `dequeued` on removal
+(`merge_queue.queued_label` / `dequeued_label`). These are **lifecycle** signals,
+not a cheap membership check — what they mean depends on what you saw before
+them, which is why reading them is the watcher's job and not a one-off `gh`
+call. See [`watch-contract.md`](watch-contract.md).
+
+### Which one to ask
+
+Use **both, in this order** — they answer different questions and disagreeing
+answers are themselves the diagnosis:
+
+1. `mergify queue show <PR> -v` — is it in the queue, and what condition blocks it?
+2. `gh pr checks <PR>` — is the underlying CI actually green?
+
+A check that is **green in GitHub but unmet in Mergify** means the condition
+names the wrong check. A check that is **absent** (never created, e.g. filtered
+out by the workflow's `paths:`) reads as permanently unmet — see the trap below.
+
+### Pause / resume
+
+```bash
+mergify queue pause --reason "production incident — halting merges"
+mergify queue unpause
+```
+
+Pausing does not cancel running CI; it stops new merges. The reason is visible
+to everyone in `queue status`. Add `--yes-i-am-sure` in scripts.
+

package/skills/cicd-pipeline/mergify/references/traps.md

@@ -0,0 +1,78 @@
+# Traps
+
+These are the ones that cost real time. Each has been hit in production.
+
+
+**A path-filtered check is *absent*, not failing.** If the workflow has an
+`on.pull_request.paths:` filter, a PR touching none of those paths never creates
+the check — and `check-success = <name>` can never be satisfied. Those PRs sit in
+the queue forever with nothing reporting why. Write the condition as an `or` with
+an explicit exemption (see the template's `gate` anchor), and **include the
+workflow file's own path in the exemption** — otherwise a workflow-only PR takes
+the exempt branch and can merge with the gate red, which is precisely the change
+most able to disable the gate.
+
+**Never write `success_conditions: [queue-name = default]`** in a
+`merge_protections` rule to force merges through the queue. Merge-protection
+conditions are injected into the queue's **entry** conditions, while the GitHub
+ruleset requires the resulting check **before** entry — entry waits on a check
+that cannot go green until after entry, and the repository deadlocks with every
+PR parked at "Waiting for queue conditions". `branch_protection_injection_mode:
+merge` does **not** prevent this; it governs GitHub-side injection, not Mergify's
+own merge protections. Queue-only merges are a **GitHub ruleset** job, not a
+Mergify-config job — use the `update` rule, as in
+[Enforcing Queue-Only Merges](branch-protection.md#enforcing-queue-only-merges).
+
+**A required status check does not make the queue mandatory.** Once it goes
+green, anyone with write access can merge directly and the queue never sees the
+PR. Only the `update` rule stops that.
+
+**`update` locks out your own automation.** Enabling it without adding the
+GitHub Actions app (or whatever pushes to the branch) as a bypass actor turns
+every release/version-bump job red. Inventory pushers before you enable it.
+
+**Do not make Mergify the sole bypass actor without a break-glass path.** If
+Mergify is the only actor that can write to the branch and Mergify has an
+outage, nobody can merge the fix either. Keep `OrganizationAdmin` bypass.
+
+**Define the gate once, assert it three times.** The queue-entry gate, the
+queue-merge gate and the GitHub-required merge protection must be the same YAML
+anchor. Three hand-written copies drift, and the drift shows up as an
+unmergeable PR, not as an error.
+
+**`merge_conditions` re-asserting `queue_conditions` is not redundant.** Mergify
+tests the batch merged with its base — a tree that existed when no individual
+PR's CI ran.
+
+**`-draft` is deliberately absent** from `queue_conditions` and
+`merge_conditions`. Under manual enqueue nothing queues a draft by accident, and
+a leftover draft condition presents as "queued, no reason given". Know what the
+absence costs before you re-add it or rely on it: GitHub cannot merge a draft PR,
+so a draft that *is* enqueued rides a whole batch CI run and then fails at the
+merge call, taking the batch's innocent PRs through that failure. Marking a
+queued PR as draft no longer dequeues it either — `@mergifyio dequeue` does.
+
+**Stop drafts at *creation*, not just at the queue.** The paragraph above is the
+queue side — it does not stop a PR being *born* a draft, and the queue does not
+filter drafts out. So the guard belongs where PRs are opened. `mergify stack`
+opens each PR per its `--draft` flag, falling back to git config
+`mergify-cli.stack-create-as-draft`, which is `false` when unset and only counts
+the literal string `"true"`. The failure mode is therefore a **global**
+`mergify-cli.stack-create-as-draft=true` inherited into every repo, silently
+drafting every agent-opened PR. Pin it off in the repo so no inherited value can
+flip it:
+
+```bash
+git config mergify-cli.stack-create-as-draft false
+```
+
+An explicit `--draft` on the `mergify stack` invocation still overrides this, so
+also confirm no wrapper or alias passes it. (Deliberate drafting is a separate
+case: `resolve-issues`' integration gate converts per-unit PRs to draft *after*
+opening the combined PR — that is intended and not what this guard is about.)
+
+**Under a required Mergify check, set `branch_protection_injection_mode: merge`.**
+The default (`queue`) injects ruleset requirements into entry conditions too, and
+a Mergify check that deliberately fails pre-queue then blocks the enqueue that
+would make it pass.
+

package/skills/cicd-pipeline/mergify/references/watch-contract.md

@@ -0,0 +1,218 @@
+# Mergify Delivery Watch Contract
+
+Use this contract whenever an agent queues or watches a PR through Mergify, whether the work is a full `resolve-issues` delivery or a simple PR. The goal is to avoid the recurring false states where a dequeued PR is reported as healthy, a not-yet-admitted PR is reported as failed, or a stale GitHub check-rollup is treated as Mergify queue truth.
+
+## A Watch Observes A Progression, Not A State
+
+Read this before the state machine — it is the premise the rest of the file rests on, and skipping it is how a correct-looking watcher gets built anyway.
+
+The queue lifecycle is a **sequence**, and every verdict worth having is a *transition* between its phases, never a property of a single reading:
+
+```
+NOT_YET_QUEUED  ──enqueue accepted──▶  QUEUED  ──┬──▶  MERGED
+     │                                           ├──▶  DEQUEUED
+     └──▶ STALLED (never admitted)               └──▶  CLOSED_UNMERGED
+```
+
+The identical observation means opposite things on either side of queue entry:
+
+| Reading | Before entry | After entry |
+|---|---|---|
+| active queue membership absent | `NOT_YET_QUEUED` — healthy, keep waiting | **`DEQUEUED`** — terminal, read the reason |
+
+So the watcher's memory *is* the verdict. Four pieces of state must survive across polls:
+
+1. **`seenQueued`** — has queue entry ever been observed? Every downstream transition depends on it. Set from the `queued` label **or** `mergify queue show`.
+2. **A re-read counter** (`missingActiveReads` / `absentStreak`) — one absence is suspicion, two consecutive *readable* absences settle `DEQUEUED`.
+3. **Readable vs. absent** — a failed `gh`/`mergify` call is *no information* and must not advance that counter.
+4. **A change clock** (`lastChangeMs`) — the stall bound is *no observable change*, not elapsed time.
+
+### Why a per-poll predicate cannot satisfy this
+
+A background-task runner that re-executes a command each tick and reads its exit code is a **stateless predicate evaluator**. There is nowhere to keep items 1–4, so the shape is wrong before the code is. This is not theoretical — pi session `019fae8f` produced four hand-rolled watchers for one PR, and each failed a different one of the four:
+
+| Hand-rolled watcher | Failure |
+|---|---|
+| `state ∈ {MERGED, CLOSED}` | A dequeued PR is plain `OPEN`. Dequeue is structurally invisible; the watch runs to its ceiling reporting health. |
+| `.queued // false` | The JSON-shape trap below — never observes entry, so item 1 stays false and the whole dequeue path is dead code. |
+| single absent read → terminal | No item 2. Settled `DEQUEUED` on a PR that was mid-`checking`. |
+| `mergify … \|\| printf '{"queued":false}'` | No item 3. Converts an outage into a false dequeue, *faster* than the stall bound rather than through it. |
+
+Two of the four were written *after* the agent had been told to check for dequeue, and one of those reported a false `DEQUEUED` on a healthy PR. Knowing the requirement does not rescue the shape.
+
+**Therefore: run [`../scripts/watch-pr-delivery.mjs`](../scripts/watch-pr-delivery.mjs).** It is one long-lived process owning its own poll loop, so items 1–4 live in its locals. Do not wrap it in an outer poller — that reintroduces exactly the shape it exists to replace.
+
+### `phases` — the progression as output
+
+The watcher emits `phases`: the ordered list of lifecycle phases actually observed, on both the terminal verdict and every heartbeat. It resolves the one ambiguity the terminal outcome cannot:
+
+| terminal | `phases` | meaning | fix |
+|---|---|---|---|
+| `STALLED` | `["NOT_YET_QUEUED","STALLED"]` | never admitted (`reason` is usually `admission-stall`) | enqueue it, or diagnose why admission never happened |
+| `STALLED` | `["NOT_YET_QUEUED","QUEUED","STALLED"]` | admitted, then wedged in the queue (`reason` is usually `stall-bound`) | read the blocking condition |
+
+`WAITING` is deliberately not a phase — it is the re-read suspicion state *inside* `QUEUED`, and recording it would oscillate a healthy PR's progression into noise.
+
+## Enqueue Before You Watch
+
+The watch observes only — it never posts `@mergifyio queue`. Check membership first, because on a repo configured for manual delivery the answer decides whether a watch is worth starting at all:
+
+```bash
+mergify queue show <PR> --json | jq '{position, queue_rule_name, queued_at}'   # membership now
+mergify queue show <PR> --json | jq '.queue_rule.config.autoqueue'             # can it self-queue?
+grep -n "auto_merge_conditions" .mergify.yml                                   # or auto-enqueue?
+```
+
+Read `autoqueue` from the **resolved** config Mergify reports, not from `.mergify.yml`. The authorable key is deprecated, so a correct config never contains it and grepping the file always finds nothing — which tells you nothing. `queue show` reports the effective value either way.
+
+If the PR is not queued, `autoqueue` is `false`, **and** the repo has no `auto_merge_conditions`, nothing will ever put it in the queue on its own. A watch started there can only end `STALLED` — enqueue first, then watch. A repo whose `.mergify.yml` says *"delivery stays manual"* is exactly this case.
+
+A 👍 on the command comment acknowledges the *command*, not queue entry.
+
+## Batch Delivery — Enqueue The Whole Ready Set Together
+
+Batch mode is configured at the queue level (`batch_size`, `batch_max_wait_time`), but whether a batch ever *happens* is a delivery decision. Mergify only batches PRs that are **in the queue together**: it holds the gate open for `batch_max_wait_time`, then tests up to `batch_size` PRs as one CI run. So the batching lever in an agent's hands is *enqueue timing and grouping* — not config. (Config's part is one line: write `batch_size: 3` — the skill's default. It must be explicit: an unset `batch_size` silently runs at Mergify's built-in default of 1, i.e. no batching — see [`configuration.md`](configuration.md#2--3-batch-mode-size-3).)
+
+**The default delivery pattern is to enqueue the whole ready set in one pass.** When several PRs against the same base are merge-ready — a stack, an epic's units, a burst of related edits — enqueue them all before watching any:
+
+- One batch CI run for N PRs instead of N. Serial delivery — enqueue #1, watch it merge, then enqueue #2 — means each PR rides its own batch: N CI runs and N watch cycles for work that could have landed in one. Being in the queue together is never slower; it is usually several CI runs faster.
+- A red batch is safe: Mergify bisects it and dequeues only the culprit; the innocent PRs carry on.
+- **"If possible" is the escape hatch, not the rule.** A lone PR, or a set where the rest still wait on review/CI/conflict, is enqueued as-is — `batch_max_wait_time` bounds the wait for company, and a ready PR is never held back for a straggler.
+
+**Mergify groups PRs into a batch by relationship, not queue order.** It does not simply take the next N in the queue: priority and queue order seed a batch, **stacks always stay together**, and similarity (shared scopes, then changed directories, then queue time) fills the remaining slots. Consequences:
+
+- Related PRs enqueued together reliably ride one batch — that is the pattern to aim for.
+- Unrelated PRs may still split across batches. That is Mergify's choice and it is correct: it keeps one PR's failure from dragging unrelated work into a bisection. Do not force co-batching (e.g. by inventing scopes) to fight it.
+
+**Mechanics.** `@mergifyio queue` is per-PR — it is a comment posted on the PR and takes no PR list — so "together" means posting it on each ready PR in the same pass, then watching: one `watch-pr-delivery.mjs` per PR, launched together (they are cheap at the default interval), or the batch as a whole via `mergify queue status`. Enqueue promptly once a PR is ready: the batch window is the fill time, and a PR entering after it closes rides the *next* batch.
+
+While a batch forms, `waiting_for_batch` just means the gate is still open — keep watching, do not read it as stuck. `bisecting` means the batch went red and Mergify is splitting it — keep watching; only the culprit leaves the queue.
+
+## Source Of Truth
+
+Use Mergify and GitHub for different facts:
+
+1. `gh pr view <PR> --json state,mergedAt,mergeCommit,labels,url,comments`
+   - authoritative for whether the PR merged or closed
+   - source for Mergify lifecycle labels: `queued` and `dequeued`
+   - `comments` is not optional padding: it is the only source for *when* a `dequeued` label was applied (Mergify's status-comment payload), which is what distinguishes this attempt's dequeue from a stale label left by a previous one. Omit it and that guard silently degrades to "no reliable timestamp" on every poll. It costs no extra request — same call.
+2. `mergify queue show <PR> --json`
+   - authoritative for active queue membership, position, queue rule, CI state, and condition tree
+3. `gh pr checks <PR>` / check-rollup
+   - useful for debugging CI, but not authoritative for queue membership
+
+Do not use `Mergify Merge Queue` check-rollup state alone to decide queued/dequeued status. It can be stale, neutral, or in progress while the queue tool says something more precise.
+
+## State Machine
+
+A watcher must retain history for the PR it is watching.
+
+- `MERGED`: PR state is `MERGED` or `mergedAt` is set. Return the PR merge commit SHA, not the branch head. The caller still owes ancestry verification.
+
+  On this path Mergify removes `queued` **without ever adding `dequeued`** — so a watcher that waits for a `dequeued` label to decide anything waits forever on the happy path. The label is also a lifecycle mirror that is never cleared on re-enqueue, so its mere presence is not this attempt's outcome; date it against the watch's start before treating it as terminal (see the `#629` guards in the script).
+- `CLOSED_UNMERGED`: PR state is `CLOSED` with no merge. Terminal hand-back.
+- `QUEUED`: `queued` label is present, or `mergify queue show --json` reports active membership. Set `seenQueued = true`.
+
+  **Do not test for `queued: true` — that field does not exist on a queued PR.** Verified live against PR #1396: a PR *in* the queue returns `position`, `queue_rule_name`, `queued_at`, and `queue_rule` — and no `queued` key at all. Only the *not*-queued answer is literally `{"number": <PR>, "queued": false}`. A watcher keyed on `queued === true` therefore never observes queue entry, so `seenQueued` stays false forever and every downstream transition that depends on it (`DEQUEUED`, the re-read rule) is silently dead. Infer membership the way the bundled script does:
+
+  ```js
+  const queued = parsed.queued === true || Boolean(parsed.queue_rule_name || parsed.queue_rule)
+  ```
+- `DEQUEUED`: PR is still open and unmerged, and either:
+  - `dequeued` label is present (this-watch timestamp guards apply — see `#629`), or
+  - **process-local** membership was observed (`everActive`) and is now absent across two consecutive readable re-reads (`lost-queue-membership`).
+- `NOT_YET_QUEUED`: active queue membership is absent before this process has observed membership. This is not a dequeue. It usually means the queue command has not been processed yet, the PR is waiting for queue conditions, or Mergify status has not refreshed. **`--seen-queued` alone does not leave this state** — that flag is a resume *hint* for callers/phases; it does not prove this process saw membership (epic-824 `#859` first watch false-`DEQUEUED` when the counter started from the seed).
+- `WAITING`: membership was observed, then one readable absence — re-read suspicion, not terminal.
+- `STALLED`: no observable queue/admission state has changed for the configured stall bound. Terminal hand-back, not a merge failure. The bound is **phase-aware**: pre-admission (never observed membership this process) uses the shorter `--admission-stall-minutes` (default 3) and reports `reason: "admission-stall"`; after membership has been observed, the full `--stall-minutes` (default 10) applies and reports `reason: "stall-bound"`. Same terminal outcome and exit code either way — only wall time and `reason` change. A dead admission path (forgotten enqueue, stale Mergify status, unreadable queue API) must not burn the post-entry bound. An `admission-stall` while Mergify is visibly waiting on a green-or-pending admission check is often a **too-short window**, not a broken enqueue — relaunch with the CI-gated 15m pair above rather than treating 60m as the next step.
+
+The critical invariant: after a watcher has **observed** queue entry in this process (`everActive`), it must never keep reporting `queued:false` as a routine healthy snapshot. If the PR did not merge, loss of queue membership is a queue exit. Seeding `seenQueued` via `--seen-queued` before the first successful membership poll must not invent that observation.
+
+## Re-read Rule
+
+GitHub can briefly expose neither `queued` nor `dequeued` during a label transition. Treat a single missing-label read **after process-local membership** as suspicion, then re-read. Two consecutive missing active-membership reads settle the transition as `DEQUEUED` unless the PR merged in the meantime. Absences before `everActive` stay `NOT_YET_QUEUED`.
+
+## Dequeue Reason
+
+Record both fields when the queue gives you a reason:
+
+- `rawReason`: the provider's exact string or visible status text
+- `reason`: the routing class used by the caller
+
+Suggested routing classes:
+
+| raw reason shape | route |
+|---|---|
+| `checks-failed` | fix round, fresh verdict, new enqueue |
+| `pull-request-updated`, `draft-pull-request-changed` | HEAD moved; verdict stale; re-enter delivery after fresh validation |
+| `conflict`, `conflict-with-base-branch` | rebase/evidence refresh, then enqueue |
+| `conditions-unmet`, `frozen`, `manual`, `pr-manually-dequeued`, `checks-timeout` | hand back with the condition/reason quoted |
+| unknown | hand back; fail closed |
+
+When the reason is not machine-readable, quote the Mergify status comment, queue show condition leaf, or event-log URL in `rawReason` rather than inventing a reason.
+
+## Watcher Requirements
+
+- Run as one background task or one script invocation; do not spend foreground turns polling.
+- Retry transient `gh`, GraphQL, and Mergify CLI failures. EOF, TLS handshake timeouts, and temporary API failures are not dequeue signals — an unreadable read is *no information*, not a "not queued" observation, and must not advance the counter that settles `DEQUEUED`.
+- Bound every subprocess read on its own timeout, in addition to the stall/ceiling bounds below — those are only evaluated after a poll returns, so an unbounded read can hang the watcher past both of them.
+- **Run the bundled script. Do not hand-roll a watcher** — see the progression section above for why the hand-rolled shape cannot hold the contract, whatever care goes into the code. (If you are reading a legacy shell watcher: avoid shell-reserved variable names such as `status`.)
+- Keep enqueue and watch separate. A watch observes only; it does not post `@mergifyio queue`, `@mergifyio dequeue`, or merge.
+- Confirm the PR is queued, or can become queued, *before* launching the watch — see [Enqueue Before You Watch](#enqueue-before-you-watch). A watch that cannot enqueue, on a PR nothing else will enqueue either, can only end `STALLED`.
+- Emit an observation record every poll, not only on the terminal verdict. `NOT_YET_QUEUED` and `QUEUED` are both non-terminal and cover the entire healthy path, so a watcher that speaks only at the end is silent for essentially its whole life — indistinguishable, to the caller trying to decide whether delivery is progressing, from a hung or dead process. Keep the heartbeat off the machine-contract stream: stdout carries exactly the one terminal JSON document callers parse, stderr carries the per-poll records.
+- Bound on stalled state, not total elapsed time alone. `waiting_for_previous_batches` can be slow but healthy if position/state changes.
+
+## Script
+
+Use the bundled watcher for simple PR delivery checks:
+
+```bash
+node ~/.agents/skills/mergify/scripts/watch-pr-delivery.mjs \
+  --repo <owner>/<repo> \
+  --pr 1302
+```
+
+Options:
+
+| flag | default | meaning |
+|---|---:|---|
+| `--interval-seconds` | `90` | poll interval |
+| `--stall-minutes` | `10` | post-entry terminal stall bound — no observable delivery-state change for this long *after queue membership has been observed* is `STALLED` with `reason: "stall-bound"`. A *no-change* bound, not elapsed time: any movement in position, label, or queue state resets it, so a slow-but-healthy queue is never cut off by it |
+| `--admission-stall-minutes` | `3` | pre-admission terminal stall bound — no observable change *before this process has observed membership* is `STALLED` with `reason: "admission-stall"`. Shorter on purpose: after enqueue, queue entry should appear quickly, and a dead admission path must not wait out the full post-entry bound. Capped at `--stall-minutes` so a caller that shortens the post-entry bound keeps both phases tight. **When Mergify admission itself waits on CI** (status still "waiting on PR admission gate" / warehouse lane / similar), keep the 3m default for the first watch, then relaunch with **`--admission-stall-minutes 15` and `--stall-minutes` ≥ 15** — the admission bound cannot exceed the post-entry stall. Do **not** jump to `--max-minutes 60` for that; 60 is only the absolute ceiling |
+| `--max-minutes` | `60` | absolute safety ceiling; bounds the watch even while the queue keeps reporting change, so a busy queue whose position keeps moving cannot keep the stall clock resetting forever. **60 minutes is also a hard maximum** — a larger value exits `2` rather than being silently clamped, because a caller that believes it has a four-hour watch and has one hour is worse off than one told plainly to relaunch. A batch takes minutes, so an hour of continuous movement without finishing is already a queue to hand back to a human. The sibling `resolve-issues` watcher enforces the same ceiling; a cap honoured by one of two watchers is not a cap |
+| `--quiet` | off | suppress the per-poll progress heartbeat on stderr |
+
+Output streams:
+
+| stream | content |
+|---|---|
+| stdout | exactly one pretty-printed terminal JSON verdict, at exit — carrying `phases`, `seenQueued`, and the outcome |
+| stderr | one compact JSON record per poll (`progress: true`), with the live outcome, PR labels, queue membership/position, `phases`, `changed`, and `sinceChangeMs` — the stall clock made visible |
+
+Each subprocess read (`gh pr view`, `mergify queue show`) also carries its own bounded
+timeout — a small multiple of `--interval-seconds`, clamped to never exceed the **effective
+phase stall bound** (pre-admission: `--admission-stall-minutes`; post-entry: `--stall-minutes`)
+capped by `--max-minutes`, then divided by the number of reads made per poll (2 here:
+`gh pr view` + `mergify queue show`). The two reads together cannot outlive the bound that will
+actually fire `STALLED` on this poll — so a hung pre-admission poll cannot outlive the short
+admission clock, and a post-entry poll is not permanently clamped to the admission value.
+Those stall/ceiling bounds are only evaluated after a poll returns, and a single hung read
+cannot alone consume more than half of a small stall/ceiling bound. (The sibling watcher makes
+one read per poll, so its clamp divides by 1 and the single-read guarantee is the whole bound
+there.)
+
+The `--interval-seconds` default is already set for scale. Two API calls per poll at 90s is
+80/hour per watched PR — roughly 60 concurrent watchers before an authenticated GitHub token's
+5,000/hour limit is in range, which comfortably covers an epic-sized `resolve-issues` delivery.
+(At the former 30s default it was 240/hour, or about 20 watchers.) The cost is at most 90s of
+extra merge-detection latency against a queue that takes minutes per batch — a cheap trade.
+Shorten it only for a single foreground watch where that latency actually matters.
+
+Exit codes:
+
+| code | meaning |
+|---:|---|
+| 0 | merged; JSON includes `outcome:"MERGED"` and `mergedSha` |
+| 4 | terminal but not merged: `DEQUEUED`, `CLOSED_UNMERGED`, or `STALLED` |
+| 2 | usage error |
+
+The script emits JSON on stdout. The caller is responsible for recording the delivery attempt/outcome and proving ancestry for `MERGED`.