@1aboveio/skills 1.0.21 → 1.0.23

package/skills/cicd/github-actions/scripts/watch-run.mjs

@@ -0,0 +1,511 @@
+#!/usr/bin/env node
+// watch-run — wait for one GitHub Actions run and report only the job/step transitions it
+// actually makes. Read-only: it only reads `gh run view`.
+//
+//   node watch-run.mjs --run <id> [--repo <owner>/<name>]
+//     [--interval-seconds 30] [--stall-minutes 15] [--max-minutes 60]
+//     [--slow-step-minutes 5] [--read-retries 2] [--unreadable-polls 3]
+//
+// Why this exists instead of `gh run watch`:
+//
+//   `gh run watch` repaints a status block — and an elapsed clock — every 30 seconds. To
+//   anything that reads output activity as progress (a log tail, a file mtime, an agent
+//   skim), that repaint is indistinguishable from a run doing work, and the run's own steps
+//   are exactly what stops being visible: a job wedged in one step for twenty minutes reads
+//   the same as a job moving.
+//
+// So this polls discrete JSON reads and treats only a change in the canonical run state as
+// progress. Each change is reported as the job/step transition that caused it, with the
+// duration of the step that moved, and a slow step is called out once while it is still
+// running rather than discovered afterwards.
+//
+// Streams:
+//   stdout  exactly one terminal JSON verdict, at exit.
+//   stderr  one compact JSON record per observed run-state change (`kind:"transition"`,
+//           `progress:true`, with a `changes` list of job/step transitions), one
+//           `{"warning":"slow-ci-step"}` per slow job or step, one provider-unreadable
+//           record when reads fail, and one closing `{"summary":true}` line.
+//
+// The record's projection is `state` — run status/conclusion plus each job's status and
+// current step, no clocks. `at`, `elapsedMs` and `observations` are for humans; a
+// background-task predicate watches `progress`/`state`, never log size or mtime.
+//
+// Exit codes: 0 the run succeeded (or was neutral/skipped). 4 failed, cancelled, timed out,
+// stalled, unreadable, or an unknown run state. 2 usage error.
+
+import { execFileSync } from 'node:child_process'
+
+const PASSING = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED'])
+const STATUSES = new Set(['REQUESTED', 'WAITING', 'PENDING', 'QUEUED', 'IN_PROGRESS', 'COMPLETED'])
+const CONCLUSIONS = new Set([...PASSING, 'FAILURE', 'CANCELLED', 'TIMED_OUT', 'ACTION_REQUIRED', 'STALE', 'STARTUP_FAILURE'])
+const RUN_FIELDS = 'status,conclusion,jobs,workflowName,headSha,url,attempt'
+const MAX_MINUTES_CEILING = 240
+const MAX_READ_BYTES = 16 * 1024 * 1024
+const MAX_REPORTED_CHANGES = 25
+
+function help() {
+  return `watch-run --run <id> [options]
+
+Wait for one Actions run, reporting job and step transitions. Read-only; it never
+re-runs, cancels, dispatches, or edits anything.
+
+  --run <id>                 run to watch (required)
+  --repo <owner>/<name>      repository; defaults to the current checkout
+  --interval-seconds <n>     poll interval (default 30)
+  --stall-minutes <n>        no-observable-change bound while nothing is in progress
+                             (default 15); suspended while a job or step is running
+  --max-minutes <n>          absolute ceiling (default 60, max ${MAX_MINUTES_CEILING})
+  --slow-step-minutes <n>    warn once per job or step running longer (default 5)
+  --read-retries <n>         extra attempts inside one poll (default 2)
+  --unreadable-polls <n>     consecutive unreadable polls before UNKNOWN (default 3)
+
+Outcome values: SUCCESS, NEUTRAL, FAILED, CANCELLED, STALLED, UNKNOWN.
+
+Exit 0: SUCCESS, NEUTRAL. Exit 4: every other outcome. Exit 2: usage.`
+}
+
+function parseArgs(argv) {
+  const args = {
+    intervalSeconds: 30,
+    stallMinutes: 15,
+    maxMinutes: 60,
+    slowStepMinutes: 5,
+    readRetries: 2,
+    unreadablePolls: 3,
+  }
+  const numbers = {
+    '--interval-seconds': 'intervalSeconds',
+    '--stall-minutes': 'stallMinutes',
+    '--max-minutes': 'maxMinutes',
+    '--slow-step-minutes': 'slowStepMinutes',
+    '--read-retries': 'readRetries',
+    '--unreadable-polls': 'unreadablePolls',
+  }
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--run') args.run = argv[++i]
+    else if (arg === '--repo') args.repo = argv[++i]
+    else if (numbers[arg]) args[numbers[arg]] = Number(argv[++i])
+    else if (arg === '--help' || arg === '-h') args.help = true
+    else args.unknown = arg
+  }
+  return args
+}
+
+function validate(args) {
+  if (args.unknown) return `unknown argument ${args.unknown}`
+  if (!/^[1-9][0-9]*$/.test(String(args.run ?? ''))) return '--run must be a positive integer'
+  if (args.repo != null && !/^[A-Za-z0-9][A-Za-z0-9_.-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(String(args.repo))) {
+    return '--repo must be owner/name'
+  }
+  for (const key of ['intervalSeconds', 'stallMinutes', 'maxMinutes', 'slowStepMinutes']) {
+    if (!Number.isFinite(args[key]) || args[key] <= 0) return `${key} must be a positive number`
+  }
+  for (const key of ['readRetries', 'unreadablePolls']) {
+    if (!Number.isInteger(args[key]) || args[key] < 0) return `${key} must be a non-negative integer`
+  }
+  if (args.unreadablePolls < 1) return '--unreadable-polls must be at least 1'
+  if (args.maxMinutes > MAX_MINUTES_CEILING) return `--max-minutes exceeds the ${MAX_MINUTES_CEILING}-minute ceiling`
+  return null
+}
+
+const sleepMs = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+function readTimeoutMs({ intervalSeconds, maxMinutes, elapsedMs }) {
+  const perRead = Math.max(1000, intervalSeconds * 3000)
+  const remaining = Math.max(1000, maxMinutes * 60_000 - elapsedMs)
+  return Math.min(perRead, remaining, 60_000)
+}
+
+function ghJson(ghArgs, timeoutMs) {
+  try {
+    const stdout = execFileSync('gh', ghArgs, {
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      killSignal: 'SIGKILL',
+      maxBuffer: MAX_READ_BYTES,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, GH_PROMPT_DISABLED: '1' },
+    })
+    const data = JSON.parse(stdout)
+    if (!data || typeof data !== 'object' || Array.isArray(data)) return { ok: false, error: 'gh run view returned no object' }
+    return { ok: true, data }
+  } catch (error) {
+    const stderr = String(error?.stderr ?? '').trim()
+    return { ok: false, error: stderr || String(error?.message ?? 'gh run view failed') }
+  }
+}
+
+function readRun(args, timeoutMs) {
+  const ghArgs = ['run', 'view', String(args.run), '--json', RUN_FIELDS]
+  if (args.repo) ghArgs.push('--repo', args.repo)
+  return ghJson(ghArgs, timeoutMs)
+}
+
+const upper = (value) => String(value ?? '').toUpperCase()
+const timeMs = (value) => {
+  const parsed = Date.parse(value ?? '')
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : null
+}
+
+function normalizeSteps(job) {
+  return (Array.isArray(job?.steps) ? job.steps : []).map((step, index) => ({
+    index: Number.isFinite(step?.number) ? step.number : index + 1,
+    name: step?.name || `step-${index + 1}`,
+    status: upper(step?.status) || null,
+    conclusion: upper(step?.conclusion) || null,
+    startedMs: timeMs(step?.startedAt),
+    completedMs: timeMs(step?.completedAt),
+  }))
+}
+
+function normalizeJob(job) {
+  const steps = normalizeSteps(job)
+  const current = steps.filter((step) => step.status === 'IN_PROGRESS').at(-1)
+    ?? steps.filter((step) => step.status !== null).at(-1)
+    ?? null
+  return {
+    id: String(job?.databaseId ?? job?.url ?? job?.name ?? 'unnamed-job'),
+    name: job?.name || 'unnamed-job',
+    status: upper(job?.status) || null,
+    conclusion: upper(job?.conclusion) || null,
+    startedMs: timeMs(job?.startedAt),
+    completedMs: timeMs(job?.completedAt),
+    url: typeof job?.url === 'string' && job.url.startsWith('http') ? job.url : null,
+    steps,
+    current,
+  }
+}
+
+// The canonical projection: run status/conclusion plus each job's status and the step it is
+// on. Sorted by job name, no clocks — this is what "the run changed" means, and what a
+// background task can predicate on.
+function project(data) {
+  const jobs = (Array.isArray(data.jobs) ? data.jobs : [])
+    .filter(Boolean)
+    .map(normalizeJob)
+    .sort((a, b) => {
+      const key = (job) => JSON.stringify([job.name, job.id, job.status, job.conclusion,
+        job.steps.map((step) => [step.index, step.name, step.status, step.conclusion])])
+      return key(a) < key(b) ? -1 : key(a) > key(b) ? 1 : 0
+    })
+  const state = {
+    run: {
+      attempt: data.attempt ?? null,
+      status: upper(data.status) || null,
+      conclusion: upper(data.conclusion) || null,
+      workflow: data.workflowName ?? null,
+      sha: data.headSha ?? null,
+    },
+    jobs: jobs.map((job) => ({
+      id: job.id,
+      name: job.name,
+      status: job.status,
+      conclusion: job.conclusion,
+      step: job.current?.name ?? null,
+      stepStatus: job.current?.status ?? null,
+    })),
+    running: jobs.flatMap((job) => job.steps
+      .filter((step) => step.status === 'IN_PROGRESS')
+      .map((step) => `${job.name} / ${step.name}`)),
+    waiting: jobs.filter((job) => job.status !== 'COMPLETED' && job.status !== 'IN_PROGRESS')
+      .map((job) => `${job.name}:${job.status ?? 'unknown'}`),
+  }
+  // The change key is finer than the emitted projection: a step moving is a change even
+  // when the job and run statuses are unchanged. It is never emitted — only compared.
+  const key = JSON.stringify([
+    state.run,
+    jobs.map((job) => [job.id, job.name, job.status, job.conclusion, job.steps.map((step) => [step.index, step.name, step.status, step.conclusion])]),
+  ])
+  return { jobs, state, key }
+}
+
+const label = (status, conclusion) => conclusion || status || 'unknown'
+
+// The transitions between two projections, as lines a human can read in a log tail.
+function describeChanges(previousState, previousJobs, { jobs, state }) {
+  const changes = []
+  if (previousState && previousJobs) {
+    if (previousState.run.status !== state.run.status || previousState.run.conclusion !== state.run.conclusion) {
+      changes.push(`run: ${label(previousState.run.status, previousState.run.conclusion)} -> ${label(state.run.status, state.run.conclusion)}`)
+    }
+    if (previousState.run.attempt !== state.run.attempt) {
+      changes.push(`run attempt: ${previousState.run.attempt} -> ${state.run.attempt}`)
+    }
+    const before = new Map(previousJobs.map((job) => [job.id, job]))
+    for (const job of jobs) {
+      const prior = before.get(job.id)
+      if (!prior) changes.push(`job ${job.name}: appeared (${label(job.status, job.conclusion)})`)
+      else if (prior.status !== job.status || prior.conclusion !== job.conclusion) {
+        changes.push(`job ${job.name}: ${label(prior.status, prior.conclusion)} -> ${label(job.status, job.conclusion)}`)
+      }
+      const priorSteps = new Map((prior?.steps ?? []).map((step) => [step.index, label(step.status, step.conclusion)]))
+      for (const step of job.steps) {
+        const was = priorSteps.get(step.index)
+        const now = label(step.status, step.conclusion)
+        if (!was) changes.push(`step ${job.name} / ${step.name}: appeared (${now})`)
+        else if (was !== now) changes.push(`step ${job.name} / ${step.name}: ${was} -> ${now}`)
+      }
+    }
+  }
+  if (previousState && changes.length === 0) changes.push('run state changed (job, step, or run metadata)')
+  const extra = Math.max(0, changes.length - MAX_REPORTED_CHANGES)
+  return {
+    changes: changes.slice(0, MAX_REPORTED_CHANGES),
+    changesOmitted: extra,
+  }
+}
+
+// One warning per job run and per step run, emitted while they are still running.
+function slowRecords(jobs, { thresholdMs, warned, nowMs, runUrl }) {
+  const out = []
+  const emit = (kind, key, { durationMs, ...fields }) => {
+    if (warned.has(key) || durationMs <= thresholdMs) return
+    warned.add(key)
+    out.push(JSON.stringify({
+      warning: 'slow-ci-step',
+      kind,
+      durationSec: Math.round(durationMs / 1000),
+      thresholdSec: Math.round(thresholdMs / 1000),
+      ...fields,
+    }))
+  }
+  for (const job of jobs) {
+    const jobEnd = job.completedMs ?? nowMs
+    if (job.startedMs) {
+      emit('job', `job|${job.name}|${job.startedMs}`, {
+        job: job.name,
+        step: null,
+        status: label(job.status, job.conclusion),
+        durationMs: jobEnd - job.startedMs,
+        url: job.url ?? runUrl,
+      })
+    }
+    for (const step of job.steps) {
+      if (!step.startedMs) continue
+      emit('step', `step|${job.name}|${step.name}|${step.startedMs}`, {
+        job: job.name,
+        step: step.name,
+        status: label(step.status, step.conclusion),
+        durationMs: (step.completedMs ?? nowMs) - step.startedMs,
+        url: job.url ?? runUrl,
+      })
+    }
+  }
+  return out
+}
+
+function failureDetail(jobs) {
+  const failed = jobs.filter((job) => job.conclusion && !PASSING.has(job.conclusion))
+  const named = failed.map((job) => {
+    const steps = job.steps.filter((step) => step.conclusion && !PASSING.has(step.conclusion)).map((step) => step.name)
+    return steps.length > 0 ? `${job.name} (${job.conclusion}: ${steps.join(', ')})` : `${job.name} (${job.conclusion})`
+  })
+  return {
+    failedJobs: named,
+    detail: named.length > 0 ? named.join('; ') : 'the run finished without a conclusion',
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2))
+  if (args.help) {
+    console.log(help())
+    return 0
+  }
+  const invalid = validate(args)
+  if (invalid) {
+    console.error(`watch-run: ${invalid}`)
+    return 2
+  }
+
+  const startedMs = Date.now()
+  const slowThresholdMs = args.slowStepMinutes * 60_000
+  const warnedSlow = new Set()
+  let lastKey = null
+  let lastState = null
+  let previousState = null
+  let previousJobs = null
+  let lastRunUrl = null
+  let unreadablePolls = 0
+  let observations = 0
+  let transitions = 0
+  let lastError = null
+  let changedAtMs = startedMs
+  let lastReadable = true
+  let lastUnreadableKey = null
+  let latestJobs = []
+
+  const finish = (result) => {
+    const endMs = Date.now()
+    const failures = failureDetail(latestJobs)
+    const verdict = {
+      outcome: result.outcome,
+      terminal: true,
+      reason: result.reason ?? null,
+      detail: result.detail ?? null,
+      run: {
+        id: Number(args.run),
+        attempt: lastState?.run?.attempt ?? null,
+        status: lastState?.run?.status ?? null,
+        conclusion: lastState?.run?.conclusion ?? null,
+        workflow: lastState?.run?.workflow ?? null,
+        sha: lastState?.run?.sha ?? null,
+        url: lastRunUrl,
+      },
+      jobs: lastState?.jobs ?? [],
+      failedJobs: failures.failedJobs,
+      slowJobs: [...warnedSlow].filter((key) => key.startsWith('job|')).map((key) => key.slice(4, key.lastIndexOf('|'))),
+      slowSteps: [...warnedSlow].filter((key) => key.startsWith('step|')).map((key) => {
+        const [, job, ...rest] = key.split('|')
+        return `${job} / ${rest.slice(0, -1).join('|')}`
+      }),
+      observations,
+      transitions,
+      elapsedMs: endMs - startedMs,
+    }
+    console.log(JSON.stringify(verdict, null, 2))
+    console.error(JSON.stringify({
+      summary: true,
+      outcome: verdict.outcome,
+      reason: verdict.reason,
+      failedJobs: verdict.failedJobs,
+      slowSteps: verdict.slowSteps,
+      running: lastState?.running ?? [],
+    }))
+    return result.exitCode
+  }
+
+  for (;;) {
+    observations += 1
+    const elapsedMs = Date.now() - startedMs
+    const timeoutMs = readTimeoutMs({ intervalSeconds: args.intervalSeconds, maxMinutes: args.maxMinutes, elapsedMs })
+
+    let read = null
+    for (let attempt = 0; attempt <= args.readRetries; attempt += 1) {
+      read = readRun(args, timeoutMs)
+      if (read.ok) break
+      if (attempt < args.readRetries) await sleepMs(Math.min(1000, args.intervalSeconds * 1000))
+    }
+
+    if (!read.ok) {
+      unreadablePolls += 1
+      lastError = read.error
+      const key = `unreadable|${read.error}`
+      if (lastReadable || key !== lastUnreadableKey) {
+        lastUnreadableKey = key
+        lastReadable = false
+        transitions += 1
+        console.error(JSON.stringify({
+          kind: 'transition',
+          progress: false,
+          reason: 'provider-unreadable',
+          at: new Date().toISOString(),
+          state: { readable: false, error: read.error },
+        }))
+      }
+      if (unreadablePolls >= args.unreadablePolls) {
+        return finish({ outcome: 'UNKNOWN', reason: 'unreadable', detail: `gh run view failed ${unreadablePolls} polls in a row: ${lastError}`, exitCode: 4 })
+      }
+      if (Date.now() - startedMs >= args.maxMinutes * 60_000) {
+        return finish({ outcome: 'UNKNOWN', reason: 'max-minutes', detail: `watch reached its ${args.maxMinutes}m ceiling while the provider was unreadable: ${lastError}`, exitCode: 4 })
+      }
+      await sleepMs(args.intervalSeconds * 1000)
+      continue
+    }
+
+    unreadablePolls = 0
+    const { jobs, state, key } = project(read.data)
+    latestJobs = jobs
+    lastState = state
+    lastRunUrl = read.data.url ?? null
+
+    if (!STATUSES.has(state.run.status)) {
+      return finish({ outcome: 'UNKNOWN', reason: 'unknown-run-state', detail: `unsupported run status: ${state.run.status ?? 'missing'}`, exitCode: 4 })
+    }
+    if ((state.run.conclusion && !CONCLUSIONS.has(state.run.conclusion)) ||
+        (state.run.status === 'COMPLETED' && !state.run.conclusion)) {
+      return finish({ outcome: 'UNKNOWN', reason: 'unknown-run-conclusion', detail: `unsupported run conclusion: ${state.run.conclusion ?? 'missing'}`, exitCode: 4 })
+    }
+
+    const malformed = jobs.find((job) => !STATUSES.has(job.status) ||
+      (job.conclusion && !CONCLUSIONS.has(job.conclusion)) ||
+      job.steps.some((step) => !STATUSES.has(step.status) ||
+        (step.conclusion && !CONCLUSIONS.has(step.conclusion))))
+    if (malformed) {
+      return finish({ outcome: 'UNKNOWN', reason: 'unknown-job-state', detail: `unsupported job or step state in ${malformed.name}`, exitCode: 4 })
+    }
+
+    if (key !== lastKey || !lastReadable) {
+      const stateChanged = key !== lastKey
+      const { changes, changesOmitted } = describeChanges(previousState, previousJobs, { jobs, state })
+      const reason = lastKey === null ? 'run-state-initial' : lastReadable ? 'run-state' : 'provider-readable'
+      lastKey = key
+      if (stateChanged) changedAtMs = Date.now()
+      transitions += 1
+      lastReadable = true
+      console.error(JSON.stringify({
+        kind: 'transition',
+        progress: stateChanged,
+        reason,
+        at: new Date().toISOString(),
+        ...(reason === 'run-state-initial' ? {} : { changes: stateChanged ? changes : [], changesOmitted: stateChanged ? changesOmitted : 0 }),
+        state,
+      }))
+    }
+    previousState = state
+    previousJobs = jobs
+
+    for (const warning of slowRecords(jobs, { thresholdMs: slowThresholdMs, warned: warnedSlow, nowMs: Date.now(), runUrl: lastRunUrl })) {
+      console.error(warning)
+    }
+
+    if (state.run.status === 'COMPLETED') {
+      const conclusion = state.run.conclusion
+      if (PASSING.has(conclusion)) {
+        return finish({
+          outcome: conclusion === 'SUCCESS' ? 'SUCCESS' : 'NEUTRAL',
+          reason: `run-${String(conclusion).toLowerCase()}`,
+          exitCode: 0,
+        })
+      }
+      const failures = failureDetail(jobs)
+      return finish({
+        outcome: conclusion === 'CANCELLED' ? 'CANCELLED' : 'FAILED',
+        reason: `run-${String(conclusion || 'unknown').toLowerCase()}`,
+        detail: failures.detail,
+        exitCode: 4,
+      })
+    }
+
+    const inProgress = state.running.length > 0 || jobs.some((job) => job.status === 'IN_PROGRESS')
+
+    if (Date.now() - startedMs >= args.maxMinutes * 60_000) {
+      return finish({
+        outcome: 'STALLED',
+        reason: 'max-minutes',
+        detail: `watch reached its ${args.maxMinutes}m ceiling with the run still ${state.run.status ?? 'unknown'}`,
+        exitCode: 4,
+      })
+    }
+    // Nothing progressed and nothing is running: this is the shape that hides behind a
+    // repainting status line — a job queued for a runner that will never match it.
+    if (!inProgress && Date.now() - changedAtMs >= args.stallMinutes * 60_000) {
+      return finish({
+        outcome: 'STALLED',
+        reason: 'no-progress',
+        detail: state.waiting.length > 0
+          ? `no job or step started for ${args.stallMinutes}m; waiting on ${state.waiting.join(', ')}`
+          : `no observable run-state change for ${args.stallMinutes}m`,
+        exitCode: 4,
+      })
+    }
+
+    await sleepMs(args.intervalSeconds * 1000)
+  }
+}
+
+process.exitCode = await main().catch((error) => {
+  console.error(JSON.stringify({ error: 'watch-run-failed', detail: String(error?.message ?? error) }))
+  return 4
+})

package/skills/cicd/github-flow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: github-flow
 description: "Deliver a change after the commit: push, open a PR, wait for checks, and merge to main through the repo's flow (direct push, pull request, or merge queue). Use whenever you commit or finish a change, when CONTRIBUTING.md has a Delivery section, and for asks like 'commit this', 'push it', 'open a PR', 'ship it', 'land it', 'get it merged'. Also: declare a repo's delivery flow, or write the CI conventions and Delivery section into CONTRIBUTING.md on request. NOT for writing workflow YAML (github-actions), Mergify config or a stuck queued PR (mergify), cutting a release (resolve-release), or PRs that resolve-issues or rush-issues deliver."
-release-version: 0.50.1
+release-version: 0.50.3
 ---
 **Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
 # GitHub Flow
@@ -58,15 +58,37 @@ Commit only the files of this change. Leave unrelated working-tree changes alone
    - Stack repo (`mergify-hooks/` in the git hooks dir; the pre-push hook says "Use 'mergify stack
      push'"): replace steps 2–3 with the `mergify` skill's `scripts/stack-push.mjs`. Put
      `Closes #<n>` in the commit message. Never `--no-verify`.
-4. Wait for the checks: `gh pr checks --watch --required --fail-fast`.
-   - "no required checks": run it again without `--required`.
-   - "no checks reported": wait 30 seconds and retry; after 5 minutes with none, the repo has no CI
-     for this PR. Continue.
-   - Red: go to [Fix a red check](#fix-a-red-check).
+4. Wait for the checks to settle:
+
+   ```bash
+   node "$SKILL_DIR/scripts/watch-checks.mjs" --pr <number>
+   ```
+
+   It preserves the existing bar: required checks, falling back to all checks when none
+   are required. It writes one record only when the selected check set actually changes — a stationary phase stays
+   quiet rather than redrawing. Read the terminal verdict:
+   - exit 0 `CHECKS_PASSED`: go to step 5.
+   - exit 0 `NO_CHECKS`: none reported within the bound. Continue only if the repository's
+     policy permits no CI; otherwise diagnose the missing checks.
+   - exit 4 `CHECKS_FAILED`: the verdict names them. Go to [Fix a red check](#fix-a-red-check).
+   - exit 4 `STALLED` / `UNKNOWN`: report the verdict and stop. Never merge on a guess.
+
+   Avoid redraw-based waits: the elapsed clock in `gh pr checks --watch` looks like
+   progress to a log monitor even while one check is stationary. Keep the repository's
+   existing check policy; observation does not add optional checks as merge gates.
 5. Merge once green: `gh pr merge --<mergeMethod> --delete-branch`, adding `--auto` when
    `autoMerge: true`. On a refusal for review, go to [Stop at a human gate](#stop-at-a-human-gate).
-6. Confirm `gh pr view --json state,mergeCommit` shows `MERGED`, then
-   `git switch <branch> && git pull --ff-only`.
+6. Prove the merge — a zero exit from `gh pr merge --auto` means the *request* was accepted:
+
+   ```bash
+   node "$SKILL_DIR/scripts/watch-checks.mjs" --pr <number> --until merged
+   ```
+
+   Continue only after `MERGED`, which prints `pr.mergedSha`; a checkless open PR still
+   needs provider merge confirmation. Exit 4 `STALLED` with `reason: merge-gate:blocked` is the
+   human gate; `merge-gate:behind` or `merge-gate:dirty` needs a rebase or a conflict fix. A PR
+   with an accepted auto-merge request is never called a gate — the provider owns the next step,
+   so the ceiling is the hand-back there. Then `git switch <branch> && git pull --ff-only`.
 
 ## Flow: merge-queue
 
@@ -76,7 +98,11 @@ Commit only the files of this change. Leave unrelated working-tree changes alone
      `scripts/watch-pr-delivery.mjs` to a verdict. Enqueue several ready PRs together.
    - `queue: github`: `gh pr merge --auto` with no merge method; the queue sets it.
 3. Dequeued: with Mergify, follow its dequeue-reason table. Re-enqueue only after the cause is fixed.
-4. Confirm the merge and update the local default branch as in pull-request step 6.
+4. Confirm the merge, then update the local default branch as in pull-request step 6.
+   - `queue: mergify`: the queue watcher's `MERGED` verdict carries the merge commit. The
+     `queued` label disappearing is not a merge.
+   - `queue: github`: `watch-checks.mjs --pr <number> --until merged --max-minutes 120`. The
+     ceiling is the hand-back; auto-merge being accepted is not a merge.
 
 ## Fix a red check