@1aboveio/skills 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,274 @@
+# Mergify Configuration
+
+The 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: 10 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.
+
+The default is **10 seconds**, not 0. A coordinated enqueue (`stack-push.mjs
+--enqueue`, an epic's units) lands its PRs within seconds, and those were most
+of the batches a two-week audit of seven repos found (27 formed in the wait
+window, 18 behind a running check, 2026-09-27 → 10-10). At 0 the first PR of a
+burst starts alone: with `max_parallel_checks > 1` the rest each start their
+own check (more CI runs), and with `max_parallel_checks: 1` they wait out the
+first PR's whole run before batching (slower). PRs that pile up behind a
+running check still batch at any window.
+
+**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 second queue-only check in
+  `merge_conditions` 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.
+
+## The Queue Run Is The Integration Run
+
+Rules settled by the 2026-10-10 audit of seven repos (Mergify event log,
+2026-09-27 → 10-10). Each one is a one-liner; the example is the shape to copy.
+
+- **Run each heavy check once, in the queue only.** Never copy a queue-only
+  check (authenticated E2E, integration, smoke) onto the PR lane to "catch it
+  earlier": that runs it twice and lengthens integration. Make it reliable
+  instead. Example: identity's `Queue authenticated validation` stays on
+  `mergify/merge-queue/**` only; its flakes were fixed in the test, not moved.
+- **Never skip the tests on the queue branch.** A queue lane that reports green
+  without testing turns the queue into a slow merge button. Example (kyc, the
+  anti-pattern): `if [[ "$HEAD_REF" == mergify/merge-queue/* ]]; then echo
+  skip=true` — the queue ran 1.4 min against 10.6 min on PRs, and main CI then
+  failed 7 of 16 times.
+- **Do not rerun CI on push to the base branch.** The queue already tested the
+  exact tree that lands there, and the `update` rule makes the queue the only
+  way in. Drop `push: branches: [main]` from test workflows and drop nightly
+  `schedule:` reruns of the gate; keep deploy and post-deploy workflows, which
+  do work the queue cannot. Do not build verdict-reuse machinery to make the
+  main run cheap — remove the trigger. Example (ai #1687, identity #1222,
+  a1 #387): `on: { pull_request: , workflow_dispatch: }`. Keep a `schedule:`
+  only for a different job, such as a weekly full-history security scan.
+- **Size `max_parallel_checks` to the runners, not to `batch_size`.** On a
+  shared self-hosted pool, one batch can fill the pool; a second speculative
+  batch only queues for runners and slows every shard. Example: identity keeps
+  `max_parallel_checks: 1` because one batch runs ~10 jobs on ~13 org-wide
+  runners and shard waits already reached p90 197 s.
+- **Fix a flaky queue check; retry only as a dated stopgap.** Each flaky
+  failure costs a full queue run plus a re-enqueue. `max_checks_retries: 1`
+  re-runs a failed batch once before splitting or dequeuing; set it only with a
+  comment listing the flakes being fixed and saying to return it to 0. Example:
+  fmm-express #1541.
+- **Set no checks timeout.** `checks_timeout` defaults to `auto` (p95 of recent
+  queue runs plus a margin). On a busy shared runner pool, a run that is only
+  waiting for runners crosses it, and Mergify dequeues and bisects PRs whose
+  checks would pass. Set `checks_timeout: null` on every queue rule; a hung job
+  is ended by its own `timeout-minutes`. Example (2026-10-10): fmm-express at 35
+  min and skyee at auto ~43 min dequeued green PRs while waiting for runners.
+
+## Stack-ready
+
+**A GitHub-native stack needs only Mergify's ruleset bypass `exempt`
+([branch-protection.md](branch-protection.md)).** GitHub runs a native stack's
+PR CI as if each PR targets the stack base, and Mergify rebases a survivor
+itself after a partial landing, so a `branches: [main]` filter and a squash
+queue both work. Native stacks are the `mergify stack push` default and what
+`resolve-issues` `stack` mode builds (`gh stack link`).
+Example (stack-sandbox, 2026-10-20): a `[main]`-filtered workflow ran on every
+PR of a three-PR native stack, and a squash queue landed it whole, then
+partially with the top PR red.
+
+**A `Depends-On` stack (`--no-github-native`, or a push GitHub refused to
+register), or a `resolve-issues` chain, needs three more settings:**
+
+- **Run PR CI on every base.** On every workflow behind a required check, use
+  `on: { pull_request: }` with no `branches:` filter, or `branches: ["**"]`. A
+  filter to the base branch never runs on a PR based on another PR's branch,
+  so the stack gets no CI until each parent merges. Example (2026-10-16):
+  fmm-express (`test.yml`, `android.yml`) and identity (`ci.yml`) filtered to
+  `[main]`.
+- **Merge with commits kept.** `merge_method: merge-batch` with
+  `batch_size: 3`, or `merge` at batch size 1. `squash` and `rebase` rewrite
+  the commits a child PR is built on, so it conflicts once its parent lands.
+  Example: kyc's `default` queue squashed.
+- **Auto-delete head branches** (setup step 8), so `Depends-On` stack survivors retarget.
+
+`audit.mjs` reports the first two as notes (`merge-method`, `stacked-pr-ci`),
+never warnings; it reads `.github/workflows` beside the config, or
+`--workflows <dir>`. It cannot tell which workflows run a required check, so it
+notes any base-filtered `pull_request` trigger.
+
+## Setup Checklist
+
+1. Fetch the schema and the relevant doc pages.
+2. Copy `assets/templates/mergify.yml` → `.mergify.yml`; replace placeholders.
+3. Remove `push: branches: [<base>]` and gate-rerun `schedule:` triggers from test
+   workflows ([The Queue Run Is The Integration Run](#the-queue-run-is-the-integration-run)).
+   Name the CI roll-up job in the `gate` anchor. It must report on every PR (no workflow
+   `paths:`; `github-actions` skill). Path-filtered workflow you can't fix: add the `or`
+   exemption and list the workflow file's own path ([traps.md](traps.md)).
+4. `mergify config validate`.
+5. `mergify config simulate <PR-URL>` against a real PR; with an exemption, use a PR
+   that hits the exempt path.
+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 — [stack-ready](#stack-ready) notes (commits
+   kept, CI on stacked PRs, for `Depends-On` stacks), 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. **Enable GitHub "Automatically delete head branches"** before relying on
+   stacked PRs in the merge queue:
+   `gh api repos/<owner>/<repo> -X PATCH -f delete_branch_on_merge=true`.
+   With this off, survivors of a stack dequeue with "could not be retargeted
+   onto the queue base branch" after a parent merges — see
+   [`traps.md`](traps.md). Confirm: `gh api repos/<owner>/<repo> --jq .delete_branch_on_merge`.
+9. `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.
+10. 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/`
+11. 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`.
+12. Prove the allowed path **before** the blocked one: enqueue a PR with
+    `@mergifyio queue`, confirm the 👍, and watch `mergify queue show <number> -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.
+13. 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.
+14. 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/mergify/references/diagnosis.md

@@ -0,0 +1,109 @@
+# 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 <number>             # one PR: position, priority, CI state
+mergify queue show <number> -v          # + full checks table and conditions tree
+mergify queue show <number> --json
+```
+
+`queue show` takes the bare PR number: `2399`, never a URL or `#2399`. Outside
+the repo's checkout, add `--repository <owner/repo>` (or `-r`); `--repo` and
+`-R` do not exist.
+Example: `mergify queue show 2399 --repository 1aboveio/agentier --json`.
+
+`mergify queue show <number> -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 <number> -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.
+
+
+## Measuring A Slow Queue
+
+Measure before tuning. Mergify's event log answers "is the queue slow, and why"
+per repo; `gh pr checks` cannot.
+
+```bash
+curl -s -H "Authorization: Bearer $(gh auth token)" \
+  "https://api.mergify.com/v1/repos/<owner>/<repo>/logs?per_page=100&received_from=<ISO date>"
+# follow the `Link: rel="next"` header to page
+```
+
+Events to use: `action.queue.enter` / `leave` (`metadata.queued_at`,
+`dequeue_code`, `merged`, `pull_request_head_sha`, `unsuccessful_checks`) and
+`action.queue.checks_start` / `checks_end` (`speculative_check_pull_request`:
+`pull_request_numbers`, `checks_started_at`, `checks_ended_at`,
+`checks_conclusion`).
+
+Compute, per repo:
+
+| Metric | Healthy | Points at |
+|---|---|---|
+| First-try merge rate | ≥ 85 % | Below it: queue-only checks failing |
+| `CHECKS_FAILED` later merged with the **same head SHA** | ≈ 0 | Flaky or infra failure — fix the check ([configuration.md](configuration.md#the-queue-run-is-the-integration-run)) |
+| Time in queue minus queue CI duration | ≈ 1 min | More: `batch_max_wait_time` or `max_parallel_checks` waits |
+| Multi-PR batches formed in the wait window vs behind a running check | — | Whether `batch_max_wait_time` is earning its latency |
+
+Then read the failing job logs (`gh run view <id> --log-failed`) and group by
+cause: real defect, flaky test, in-repo infra (artifact upload resets, ports,
+caches), or outside the repo (runner host, package mirror). Only the middle two
+are fixed in the repo.

package/skills/cicd/mergify/references/stacks.md

@@ -0,0 +1,84 @@
+# Stacked PRs (`mergify stack`)
+
+> Read when: pushing, opening, updating, or enqueuing PRs in a repo with Mergify stack hooks;
+> the pre-push hook says "Use 'mergify stack push'"; a `Change-Id` is missing.
+
+## CLI version
+
+**Use mergify CLI 2026.10.5 or newer.** `stack-push.mjs` refuses an older one (exit 6). Since
+2026.9.16.1, `stack push` registers a GitHub-native stack by default: GitHub holds the order, and
+PR bodies carry no `Depends-On:`. Mergify's queue lands it only when Mergify's bypass on every
+ruleset protecting the base is `exempt` ([traps.md](traps.md)).
+
+```bash
+mergify --version
+brew upgrade mergify-cli      # untrusted-tap refusal: brew trust --formula mergifyio/tap/mergify-cli
+```
+
+## When a repo uses stacks
+
+- **Stack repo:** `.git/hooks/mergify-hooks/` exists (installed by `mergify stack setup`). Every
+  commit gets a `Change-Id:` trailer; the pre-push hook refuses plain `git push` on a branch
+  with an upstream.
+- **Not a stack repo:** no hooks. Push with `git push` + `gh pr create` (`github-flow`). Never
+  use `mergify stack` there, and never wait on a queue the repo has no `.mergify.yml` for.
+
+## Workflow
+
+1. Start a stack branch that tracks trunk: `mergify stack new <type>/<topic>`.
+2. Commit. **One commit = one PR.** Put `Closes #<n>` in the commit message, not only the PR body.
+3. Push:
+   ```bash
+   node <mergify-skill>/scripts/stack-push.mjs              # push, report PR numbers
+   node <mergify-skill>/scripts/stack-push.mjs --enqueue    # push, then enqueue every stack PR
+   node <mergify-skill>/scripts/stack-push.mjs --dry-run    # show the plan only
+   ```
+   It refuses a non-stack repo (exit 3), stops on a missing `Change-Id` or empty stack (exit
+   4), refuses a CLI older than 2026.10.5 (exit 6), and prints each PR as JSON on stdout. The last stderr line lists the PRs.
+4. Fix after review or CI: amend the commit that PR belongs to, then push again. A new commit
+   opens a new PR. New commits cancel a PR's queue request, so push a queued PR with
+   `--enqueue`; without it, the script warns which PRs need requeueing.
+   - Tip commit: `git commit --amend`.
+   - Older commit: commit the fix on top, then `mergify stack squash <fix-sha> into <target-sha>`.
+     Squash keeps the target's message and `Change-Id`, so its PR updates in place.
+5. Enqueue the whole stack together (Rule 3), then watch each PR with `watch-pr-delivery.mjs`.
+6. After a lower PR merges: `mergify stack sync`, then push again.
+
+## Rules
+
+- **Never `git push --no-verify`** to get past the stack hook, and never `stack push --no-verify`.
+- **A multi-commit branch that must be one PR** (an integration branch): ask the user before
+  `git branch --unset-upstream` + `git push`. A stack push there opens one PR per commit.
+- **Pass `--trunk origin/main`.** Without it the CLI may resolve trunk from the branch's own
+  upstream ("targets itself", "could not determine trunk branch"). The script always passes it.
+- **Keep PR bodies:** push with `--keep-pull-request-title-and-body`, or set it once per repo:
+  `git config mergify-cli.stack-keep-pr-title-body true`. Without it every push rewrites the
+  title and body from the commit message.
+- **Keep the `Change-Id:` trailer in the last paragraph** of the message. A cherry-pick, a
+  `commit-tree`, or a rewritten message can drop it; `git commit --amend --no-edit` re-adds it.
+  A changed or missing `Change-Id` closes the old PR and opens a new one.
+- **Find a PR by number from `mergify stack list --json`** (`entries[].pull_number`). Its head
+  branch is `stack/<user>/<branch>/<slug>--<id>`; `gh pr view <local-branch>` finds nothing.
+- **Rebase conflict** ("rebase failed — there may be conflicts"): resolve, `git rebase
+  --continue`, push again. `--skip-rebase` only to avoid dismissing approvals.
+- **Retarget or dequeue after a parent merges** ("could not be retargeted"): see
+  [traps.md](traps.md) (`delete_branch_on_merge`, `--force-rebase`).
+
+## Command card
+
+| Do | Command |
+|---|---|
+| Push / create / update PRs | `mergify stack push --trunk origin/main --keep-pull-request-title-and-body` |
+| Preview | add `--dry-run` |
+| List commits and PRs | `mergify stack list --trunk origin/main [--json]` |
+| New stack branch | `mergify stack new <name>` |
+| Fold a fix into an older commit | `mergify stack squash <src>... into <target>` |
+| Fold commits into their parent | `mergify stack fixup <commit>...` |
+| Pause a rebase at a commit to amend it | `mergify stack edit <commit>`, amend, `git rebase --continue` |
+| Reword, reorder, drop | `mergify stack reword` / `reorder` / `drop` |
+| Rebase on trunk, drop merged | `mergify stack sync` |
+| Check out a stack from GitHub | `mergify stack checkout <name>` |
+| Install hooks | `mergify stack setup` |
+| CLI version (needs 2026.10.5+) | `mergify --version` |
+
+Not commands: `stack status`, `stack submit`, `mergify version`, `--repo` (use `--repository`).

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

@@ -0,0 +1,119 @@
+# 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. Fix the workflow: drop `paths:` and
+filter inside the job behind one always-reporting `gate` (`github-actions` skill,
+`conditional-ci.md`). If you cannot, write the condition as an `or` with an
+explicit `-files ~=` exemption, 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`. Auto-enqueue skips drafts (`-draft` in `auto_merge_conditions`), 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.
+
+**`Depends-On` stacked PRs dequeue with "could not be retargeted onto the queue base
+branch" when head branches survive merge.** This applies to a `Depends-On` stack
+(`--no-github-native`, or a push that printed `not registered on GitHub`); GitHub
+retargets a native stack's next PR itself, and auto-delete stays on as the guard. This is not a `.mergify.yml`
+`batch_size` / `merge-batch` bug. Mergify *can* land a stack when members are
+queued together (stack-aware base + batching), but after a lower member merges
+GitHub must restack the survivors onto `main`. That retarget happens when the
+merged PR's **head branch is deleted**. If the repository has
+`delete_branch_on_merge: false`, parent stack refs stay on the remote, GitHub
+never moves the next PR's base from `parent-head` → `main`, and Mergify dequeues
+with `base-ref-alignment-timeout` / "stacked on another whose head branch still
+exists after merging" — even while the tip was already in the queue and draft
+batch CI was green. Hit on skyee-ai-risk ADR 0044 stack (#2108 after #2107;
+#2110 after #2108/#2109). Fix the repo setting, not the queue rule:
+
+```bash
+gh api repos/<owner>/<repo> -X PATCH -f delete_branch_on_merge=true \
+  --jq .delete_branch_on_merge
+```
+
+Verify with `gh api repos/<owner>/<repo> --jq .delete_branch_on_merge` (must be
+`true`). If a tip is already stuck, `mergify stack push --force-rebase` (or a
+manual base edit onto `main`) unblocks that incident; auto-delete prevents the
+next one. On a `Depends-On` stack (`--no-github-native`), keep the full
+`Depends-On: #N` chain on every member — without it Mergify may not treat the
+chain as a stack and keeps literal bases, which collides with
+`queue_conditions: base = main`. A GitHub-native stack carries no `Depends-On`;
+Mergify reads its order from GitHub. Do not merge unrelated `main` PRs
+through the middle of an open stack unless you expect another rebase cycle.
+For GitHub-native stacks, Mergify's ruleset bypass should be **`exempt`** (not
+only `always`); see [Stacked Pull Requests](https://docs.mergify.com/merge-queue/stacks/).
+
+
+**A queue lane that skips its tests is a merge button, not a queue.** A
+workflow that sets every job to skip on `mergify/merge-queue/*` ("the queue
+reuses the PR's CI") reports green on a tree no CI ran: the PR merged with its
+base. The breakage the queue exists to catch then lands on `main`. Run the
+integration checks on the queue branch; skip only what the queue branch cannot
+change.