@1aboveio/skills 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,274 @@
+# 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. Five 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*: it must not advance that counter or overwrite that source's last readable contribution to the stall-state snapshot. During a partial outage, the still-readable sibling remains informative and genuine progress from it still resets the change clock.
+4. **A change clock** (`lastChangeMs`) — the stall bound is *no observable change*, not elapsed time.
+5. **The last synthetic batch PR number** — retain
+   `mergeability_check.queue_pull_request_number` from every readable active queue
+   observation (and accept the older top-level spelling). Mergify removes that relationship
+   from `queue show` after dequeue, but the terminal reason belongs to the synthetic batch,
+   not the original PR.
+
+### 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 <number> --json | jq '{position, queue_rule_name, queued_at}'   # membership now
+mergify queue show <number> --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.
+- **A `resolve-issues` chain line is one entry.** Its deepest PR carries the others' commits, so enqueue only that PR; its merge lands the line, and GitHub marks the others merged.
+- **"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 (for a stack, one comment on the top PR queues every member down to the root, and dequeuing a member dequeues the PRs above it), 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 <number> --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"`, unless a non-Mergify check is still pending: CI running is progress, so the full `--stall-minutes` (default 45) applies. After membership has been observed, the full bound 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.
+
+  Before queue membership, a completed failing non-Mergify GitHub check settles
+  immediately as `STALLED` with `reason: "admission-checks-failed"` and a
+  `failedChecks` summary. This is not `DEQUEUED`: the PR was never admitted.
+  Mergify's own queue/protection checks are excluded, pending/neutral/skipped
+  checks keep watching, and after membership Mergify remains the lifecycle
+  authority for failed batches and dequeue routing.
+
+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 |
+|---|---|
+| batch check `FAILURE`, `ERROR`, or `TIMED_OUT` | `checks-failed`; fix round, fresh verdict, new enqueue |
+| batch checks cancelled before validation executes | `checks-cancelled`; report the cancelled checks and hand back so an unchanged-SHA requeue can be considered |
+| `pull-request-updated`, `draft-pull-request-changed` | HEAD moved; verdict stale; re-enter delivery after fresh validation |
+| `conflict`, `conflict-with-base-branch` | rebase, regenerate generated files instead of hand-merging them, re-run checks, push, then `@mergifyio queue`. Still "Waiting for `-conflict`" while GitHub says `MERGEABLE`: comment `@mergifyio refresh` |
+| `conditions-unmet`, `frozen`, `manual`, `pr-manually-dequeued`, `checks-timeout` | hand back with the condition/reason quoted |
+| unknown | `unknown`; hand back, fail closed, and preserve `rawReason` |
+
+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.
+
+The selected `state:"dequeued"` Mergify status comment is parsed as structured evidence:
+`dequeuedAtMs`, `rawReason`, its draft PR fallback, and provider-reported failing checks. On
+dequeue, the watcher queries the retained batch PR once and attaches its failed or cancelled
+`statusCheckRollup` entries to the terminal verdict. A missing or deleted batch PR remains a
+truthful `DEQUEUED`: `batchPr.readable` is false, the retained number and `rawReason` survive,
+and any checks named by the provider comment remain available. An unchanged-SHA requeue can
+produce a new synthetic PR; every readable active observation replaces the retained number,
+so the newest batch wins over stale comment fallback.
+
+## 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`. Retain that source's last readable stall-state contribution instead; a readable sibling can still report genuine progress and reset the change clock.
+- 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` | `45` | 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. A running queue check changes nothing it can see until the run ends, so the bound must exceed the repo's queue CI duration (20-48 min on this fleet) |
+| `--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. Applies only while no non-Mergify check is pending; while CI runs, the post-entry bound applies, so a CI-gated admission needs no relaunch |
+| `--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. An hour without a verdict is a queue to hand back to a human or relaunch. The sibling `resolve-issues` watcher enforces the same ceiling; a cap honoured by one of two watchers is not a cap |
+| `--slow-job-minutes` | `5` | warn when a single CI job runs longer than this (see [CI profile](#ci-profile)) |
+| `--quiet` | off | suppress the per-poll progress heartbeat on stderr (slow-job warnings and the closing profile summary still print) |
+
+Output streams:
+
+| stream | content |
+|---|---|
+| stdout | exactly one pretty-printed terminal JSON verdict, at exit — carrying `phases`, `seenQueued`, the outcome, and `ciProfile` |
+| 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; plus one `{"warning":"slow-ci-job"}` record per slow CI job; and, last, one `{"ciProfileSummary":true}` line after the verdict |
+
+Each regular-poll 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.
+At the end of the watch, one additional bounded `gh pr view` reads the synthetic batch PR, when
+one was observed: after a dequeue to classify it, and on every terminal verdict to profile the
+queue's CI (a single read serves both). It enriches the already-settled verdict and never participates
+in queue membership, the absence counter, or the stall clock.
+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`.
+
+## CI profile
+
+Every watch also profiles the CI it waited on, at no extra poll cost: each `gh pr view` already
+returns the PR's check runs with their start and finish times.
+
+- **Jobs.** Every non-Mergify check run on the PR, plus the checks on the queue's batch PR (read
+  once at the end). Mergify's own checks are left out; their duration is queue wait, not CI work.
+  A job still running is timed up to now, so a slow job shows up while it is still running.
+- **Slow-job warning.** A job that runs longer than `--slow-job-minutes` (default 5) gets one
+  `{"warning":"slow-ci-job","name",…,"durationSec","thresholdSec","detailsUrl"}` line on stderr,
+  once per job run, even under `--quiet`.
+- **Verdict field.** The terminal JSON carries `ciProfile`: `verdict` (`ok`, `slow`, or
+  `no-timing-data`), `slowestJob`, `slowJobs`, every job's `durationSec` slowest-first, and
+  `phases` with how long the PR spent in each lifecycle phase (waiting for admission, in the
+  queue).
+
+- **Closing summary line.** After the verdict, the last stderr line is
+  `{"ciProfileSummary":true,"outcome","verdict","jobCount","slowJobMinutes","slowest","slowJobs"}`,
+  with at most three slow jobs named as `"<name> <sec>s"`. The verdict is pretty-printed over
+  many lines, so a short log tail lands inside `phases` and misses the profile; this line is
+  what a 10-line tail shows. A background runner that reports only the exit code (Pi's
+  `bg_task_status`) shows neither: read the log tail (`bg_task_log`) when the watch ends, and
+  report the profile. Identity #894 (2026-09-29) warned about a 338s job that no one read.
+
+Profiling is observation only: it never changes the outcome or the exit code. A slow-job
+warning is a lead for whoever owns the CI (split the job, cache, move it to a nightly lane) —
+the `github-actions` skill covers those fixes.

package/skills/cicd/mergify/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }

package/skills/cicd/mergify/scripts/audit-core.mjs

@@ -0,0 +1,208 @@
+// Import-only core for auditing a repo's .mergify.yml against this skill's best-practice default.
+//
+//   node audit.mjs [--file .mergify.yml] [--workflows .github/workflows] [--allow-warn] [--json]
+//
+// Like ensure-coverage's ci-audit.mjs, this is a BENCHMARK THAT ABSTAINS, not a YAML
+// parser (the repo ships no YAML dependency). Every check works on the raw text and
+// returns `abstain` when it cannot decide, rather than risk a false verdict. A check
+// that can't find the structure it needs is reported `abstain`, never `pass`.
+//
+// Exit: 2 if any FAIL, 1 if any WARN (unless --allow-warn), else 0.
+import fs from 'node:fs'
+import path from 'node:path'
+
+// The lines indented UNDER a `key:` (by the first child's indent), or null if the key
+// is absent. Enough structure-awareness to scope a check to one block without a parser.
+export function blockUnder(text, key) {
+  const lines = text.split('\n')
+  const i = lines.findIndex((l) => new RegExp(`^(\\s*)${key}\\s*:`).test(l))
+  if (i < 0) return null
+  const keyIndent = lines[i].match(/^(\s*)/)[1].length
+  const out = []
+  for (let j = i + 1; j < lines.length; j++) {
+    const l = lines[j]
+    if (l.trim() === '' || l.trim().startsWith('#')) { out.push(l); continue }
+    const ind = l.match(/^(\s*)/)[1].length
+    if (ind <= keyIndent) break
+    out.push(l)
+  }
+  return out.join('\n')
+}
+
+// Strip `#` comments so a check never trips on prose that merely NAMES a bad pattern.
+const uncommented = (text) => text.split('\n').map((l) => l.replace(/(^|\s)#.*$/, '')).join('\n')
+
+// The base branches a workflow's `pull_request` trigger is limited to, or null when it runs for any
+// base (no `branches:` filter, or one that matches every branch). Text-level, like the rest.
+export function pullRequestBranches(raw) {
+  const text = uncommented(raw)
+  const on = blockUnder(text, 'on') ?? ''
+  const inline = text.match(/^on\s*:\s*(.+)$/m)?.[1] ?? ''
+  if (!/pull_request\b(?!_target)/.test(on + inline)) return null
+  const flow = (on + inline).match(/pull_request\s*:\s*\{[^}]*branches\s*:\s*\[([^\]]*)\]/)?.[1]
+  const pr = blockUnder(on, 'pull_request')
+  // Any branches-ignore skips some base, and a stacked PR's base is a branch like any other.
+  const ignored = (on + inline).match(/pull_request\s*:\s*\{[^}]*branches-ignore\s*:\s*\[([^\]]*)\]/)?.[1]
+    ?? pr?.match(/^\s*branches-ignore\s*:\s*\[([^\]]*)\]/m)?.[1]
+    ?? ((blockUnder(pr ?? '', 'branches-ignore') ?? '').split('\n').map((l) => l.match(/^\s*-\s*(.+)$/)?.[1]).filter(Boolean).join(',') || null)
+  if (ignored) return ignored.split(',').map((b) => `!${b.trim().replace(/^['"]|['"]$/g, '')}`).filter((b) => b !== '!')
+  const listed = flow ?? pr?.match(/^\s*branches\s*:\s*\[([^\]]*)\]/m)?.[1]
+    ?? (blockUnder(pr ?? '', 'branches') ?? '').split('\n').map((l) => l.match(/^\s*-\s*(.+)$/)?.[1]).filter(Boolean).join(',')
+  if (!listed) return null
+  const branches = listed.split(',').map((b) => b.trim().replace(/^['"]|['"]$/g, '')).filter(Boolean)
+  return branches.some((b) => b === '**' || b === '*') ? null : branches
+}
+
+export function auditText(raw, { workflows } = {}) {
+  const text = uncommented(raw)
+  const f = []
+  const add = (check, status, detail) => f.push({ check, status, detail })
+
+  // 1. Deprecated auto-queue forms — decidable, always wrong.
+  if (/\bauto_merge\s*:\s*true/.test(text)) add('deprecated-forms', 'fail', '`auto_merge: true` is deprecated — use auto_merge_conditions (configuration.md §1).')
+  else if (/\bautoqueue\s*:/.test(text)) add('deprecated-forms', 'fail', '`queue_rules[].autoqueue` is deprecated — use auto_merge_conditions (configuration.md §1).')
+  else add('deprecated-forms', 'pass', 'no deprecated auto_merge/autoqueue.')
+
+  // 2. Enqueue policy: hybrid (auto scoped to a passed review) is the default.
+  const amc = blockUnder(text, 'auto_merge_conditions')
+  if (amc == null) {
+    if (/auto_merge_conditions\s*:/.test(text)) add('enqueue-policy', 'abstain', 'auto_merge_conditions present but its block could not be read — check by hand.')
+    else add('enqueue-policy', 'note', 'no auto_merge_conditions → fully MANUAL enqueue. OK if deliberate (say so in a comment); the default is hybrid (configuration.md §1).')
+  } else if (!/approved-reviews-by/.test(amc)) {
+    add('enqueue-policy', 'warn', 'auto_merge_conditions has no review arm (`approved-reviews-by`) — this is the retired indiscriminate form; scope auto-enqueue to a passed review (configuration.md §1).')
+  } else if (!/changes-requested-reviews-by/.test(amc)) {
+    add('enqueue-policy', 'warn', 'auto_merge_conditions approves without also requiring `#changes-requested-reviews-by = 0` — an open change request could be out-voted; add it (configuration.md §1).')
+  } else {
+    add('enqueue-policy', 'pass', 'hybrid: auto-enqueue scoped to a passed review.')
+  }
+
+  // 3. branch_protection_injection_mode: merge (only meaningful with a queue).
+  if (!/queue_rules\s*:/.test(text)) add('injection-mode', 'abstain', 'no queue_rules found — not a queue config?')
+  else if (/branch_protection_injection_mode\s*:\s*merge/.test(text)) add('injection-mode', 'pass', 'branch_protection_injection_mode: merge.')
+  else add('injection-mode', 'warn', 'branch_protection_injection_mode is not `merge` — a required Mergify check can then block queue ENTRY (traps.md).')
+
+  // 4. Gate defined once (anchor) and asserted in multiple places.
+  if (!/&gate\b/.test(text)) add('gate-anchor', 'abstain', 'no `&gate` anchor — cannot check the define-once/assert-thrice shape.')
+  else {
+    const refs = (text.match(/\*gate\b/g) || []).length
+    if (refs >= 2) add('gate-anchor', 'pass', `gate anchor referenced ${refs}× (define once, assert many).`)
+    else add('gate-anchor', 'warn', `gate anchor referenced only ${refs}× — assert it in queue_conditions AND merge_conditions (and the merge protection), not hand-copied.`)
+  }
+
+  // 5. `-draft` must NOT sit in queue_conditions/merge_conditions (epic-986 incident).
+  //    It belongs in auto_merge_conditions only.
+  for (const key of ['queue_conditions', 'merge_conditions']) {
+    const block = blockUnder(text, key)
+    if (block == null) continue
+    if (/(^|\s)-\s*-draft\b|(^|\s)-draft\b/.test(block)) {
+      add('draft-placement', 'warn', `\`-draft\` appears in ${key} — GitHub can't merge a draft anyway, and a queued draft strands the whole batch (epic-986). Keep -draft in auto_merge_conditions only (traps.md, \`-draft\` note).`)
+    }
+  }
+  if (!f.some((x) => x.check === 'draft-placement')) add('draft-placement', 'pass', '-draft not misplaced in queue/merge conditions.')
+
+  // 6. Batch mode is on per this skill's default. The standard is `batch_size: 3`,
+  //    written explicitly: unset, `batch_size` silently runs at Mergify's built-in
+  //    default of 1 (no batching), so the absence reads as a silent no-batch, not a
+  //    batched default. Dynamic {min, max} is batching too (configuration.md §2-3).
+  const qr = blockUnder(text, 'queue_rules')
+  if (qr == null) {
+    add('batch-mode', 'abstain', 'no queue_rules found — nothing to batch.')
+  } else {
+    const inline = qr.match(/^\s*batch_size\s*:\s*(\S.*)$/m)?.[1]
+    const under = blockUnder(qr, 'batch_size')
+    const bs = inline ?? (under != null && under.trim() !== '' ? under : null)
+    if (bs == null) add('batch-mode', 'warn', 'no `batch_size` on the queue rule — it silently runs at Mergify\'s built-in 1, so batches NEVER form; set batch_size: 3 (this skill\'s default), or say deliberately why not (configuration.md §2-3).')
+    else if (/^\s*min\s*:/.test(bs)) add('batch-mode', 'pass', 'dynamic batch_size {min, max} — batching on.')
+    else if (/^\s*[2-9]\d*\s*$/.test(bs.trim())) add('batch-mode', 'pass', `batch_size ${bs.trim()} — batching on.`)
+    else add('batch-mode', 'warn', `batch_size: ${bs.trim()} — batches never form (must be > 1); raise it to 3 (this skill's default), or say deliberately why not (configuration.md §2-3).`)
+  }
+
+  // 7. No checks timeout. Unset means `auto` (p95 of recent runs + margin): a queue run
+  //    that only waits for busy runners crosses it and green PRs get dequeued and bisected
+  //    (2026-10-10). Every queue rule needs `checks_timeout: null`, set on the rule or in
+  //    `defaults.queue_rule` (configuration.md, "Set no checks timeout").
+  if (qr == null) {
+    add('checks-timeout', 'abstain', 'no queue_rules found — no checks timeout to check.')
+  } else {
+    const defaults = blockUnder(blockUnder(text, 'defaults') ?? '', 'queue_rule')
+    const defaultValue = defaults?.match(/^\s*checks_timeout\s*:\s*(\S.*?)\s*$/m)?.[1]
+    const rules = qr.split(/^(?=\s*-\s+name\s*:)/m).filter((r) => /^\s*-\s+name\s*:/.test(r))
+    const capped = []
+    for (const rule of rules) {
+      const name = rule.match(/name\s*:\s*(\S+)/)[1]
+      const value = rule.match(/^\s*checks_timeout\s*:\s*(\S.*?)\s*$/m)?.[1] ?? defaultValue
+      if (value !== 'null' && value !== '~') capped.push(`${name} (${value ?? 'unset = auto'})`)
+    }
+    if (rules.length === 0) add('checks-timeout', 'abstain', 'no named queue rule could be read — check checks_timeout by hand.')
+    else if (capped.length) add('checks-timeout', 'warn', `queue rule(s) with a checks timeout: ${capped.join(', ')} — a run slowed by busy runners gets green PRs dequeued and bisected; set checks_timeout: null and let each job's timeout-minutes end a hang (configuration.md, "Set no checks timeout").`)
+    else add('checks-timeout', 'pass', 'every queue rule sets checks_timeout: null.')
+  }
+
+  // 8. The queue keeps the PR's commits. Squash and rebase rewrite them, so a PR built on another
+  //    conflicts once its parent lands: in a Depends-On stack or a chained PR, not a GitHub-native
+  //    stack, which Mergify rebases itself. A note, not a warning (configuration.md, "Stack-ready").
+  if (qr == null) {
+    add('merge-method', 'abstain', 'no queue_rules found — no merge method to check.')
+  } else {
+    const rules = qr.split(/^(?=\s*-\s+name\s*:)/m).filter((r) => /^\s*-\s+name\s*:/.test(r))
+    const methods = rules.map((r) => [r.match(/name\s*:\s*(\S+)/)[1], r.match(/^\s*merge_method\s*:\s*(\S+)/m)?.[1]?.replace(/^['"]|['"]$/g, '')])
+    const rewriting = methods.filter(([, m]) => m === 'squash' || m === 'rebase')
+    const unknown = methods.filter(([, m]) => m !== undefined && !['merge', 'merge-batch', 'fast-forward', 'squash', 'rebase'].includes(m))
+    if (rules.length === 0) add('merge-method', 'abstain', 'no named queue rule could be read — check merge_method by hand.')
+    else if (unknown.length && !rewriting.length) add('merge-method', 'abstain', `unrecognized merge_method: ${unknown.map(([n, m]) => `${n} (${m})`).join(', ')} — check by hand that it keeps the PR's commits.`)
+    else if (rewriting.length) add('merge-method', 'note', `queue rule(s) that rewrite commits: ${rewriting.map(([n, m]) => `${n} (${m})`).join(', ')} — fine for GitHub-native stacks; a Depends-On stack (--no-github-native) or a resolve-issues chain conflicts after its parent lands, so use merge-batch (batch_size > 1) or merge for those (configuration.md, "Stack-ready").`)
+    else add('merge-method', 'pass', 'every queue rule keeps the PR\'s commits.')
+  }
+
+  // 9. CI runs on stacked PRs: a `pull_request` trigger filtered to the base branch never runs on a
+  //    PR based on another PR's branch, so a Depends-On stack gets no CI. A GitHub-native stack runs
+  //    CI as if each PR targets the stack base, so this is a note (configuration.md, "Stack-ready").
+  if (!workflows) {
+    add('stacked-pr-ci', 'abstain', 'no workflows read — pass --workflows <dir> to check that CI runs on stacked PRs.')
+  } else {
+    const filtered = workflows.map((w) => [w.name, pullRequestBranches(w.text)]).filter(([, b]) => b)
+    if (!workflows.length) add('stacked-pr-ci', 'abstain', 'no workflow files found — check the triggers behind the required checks by hand.')
+    else if (filtered.length) add('stacked-pr-ci', 'note', `pull_request limited to base branches in: ${filtered.map(([n, b]) => `${n} [${b.join(', ')}]`).join(', ')} — fine for GitHub-native stacks; a Depends-On stack (--no-github-native) gets no CI from these, so drop the branches filter (or use "**") on every workflow behind a required check if you use one (configuration.md, "Stack-ready").`)
+    else add('stacked-pr-ci', 'pass', 'pull_request triggers run for PRs on any base branch.')
+  }
+
+  return f
+}
+
+function verdict(findings) {
+  if (findings.some((x) => x.status === 'fail')) return 'FAIL'
+  if (findings.some((x) => x.status === 'warn')) return 'WARN'
+  return 'PASS'
+}
+
+export function runCli(argv) {
+  const flags = { file: '.mergify.yml', json: false, allowWarn: false, workflows: undefined }
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]
+    if (a === '--file') flags.file = argv[++i]
+    else if (a === '--workflows') flags.workflows = argv[++i]
+    else if (a === '--json') flags.json = true
+    else if (a === '--allow-warn') flags.allowWarn = true
+  }
+  if (!fs.existsSync(flags.file)) {
+    console.error(`mergify-audit: no config at ${flags.file} (pass --file <path>).`)
+    return 2
+  }
+  // Workflows: --workflows, else .github/workflows beside the config when it exists.
+  const dir = flags.workflows ?? path.join(path.dirname(path.resolve(flags.file)), '.github', 'workflows')
+  const workflows = fs.existsSync(dir) && fs.statSync(dir).isDirectory()
+    ? fs.readdirSync(dir).filter((n) => /\.ya?ml$/.test(n)).sort().map((n) => ({ name: n, text: fs.readFileSync(path.join(dir, n), 'utf8') }))
+    : undefined
+  const findings = auditText(fs.readFileSync(flags.file, 'utf8'), { workflows })
+  const v = verdict(findings)
+  if (flags.json) {
+    console.log(JSON.stringify({ file: flags.file, verdict: v, findings }, null, 2))
+  } else {
+    const glyph = { pass: '✓', note: '·', abstain: '?', warn: '⚠', fail: '✗' }
+    for (const x of findings) console.log(`${glyph[x.status] || '?'} [${x.status}] ${x.check}: ${x.detail}`)
+    console.log(`\n${v} — ${flags.file}`)
+  }
+  if (v === 'FAIL') return 2
+  if (v === 'WARN') return flags.allowWarn ? 0 : 1
+  return 0
+}

package/skills/cicd/mergify/scripts/audit.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from './audit-core.mjs'
+
+process.exitCode = runCli(process.argv.slice(2))