Skip to content

t1k:babysit-pr

FieldValue
Modulet1k-maintainer
Version4.10.58
Effortmedium
Tools—

Keywords: ci, flaky, merge, monitor, pr, pull-request, watch

/t1k:babysit-pr
<pr-number-or-url> [--dry-run]

Monitor a pull request until it is merged. Handles flaky CI, simple merge conflicts, and auto-merges when conditions are met.

“babysit pr”, “babysit-pr”, “watch pr”, “monitor pr”, “auto merge”, “flaky ci”

Start
└─ Fetch PR state (status, reviews, conflicts)
├─ APPROVED + GREEN + no conflicts → merge → decide develop build → report
├─ CI FAILING → classify failure
│ ├─ Known flaky test → retry CI
│ ├─ Red from a stale merge ref (main fixed since) → own PR: merge main in, once
│ └─ Real failure → report to user, stop
├─ MERGE CONFLICT → attempt auto-resolve
│ ├─ Simple (non-overlapping) → resolve + push
│ └─ Complex (overlapping logic) → report to user, stop
└─ PENDING → session-owned background `t1k-pr-watch.cjs` run (`run_in_background`, zero model tokens), re-enter on its exit

The wait is delegated, never held here. Babysit supervises: it classifies, retries, resolves, merges. A wait is a different job with a different budget, and it is DETERMINISTIC — so it is a script, .claude/scripts/t1k-pr-watch.cjs, started with Bash run_in_background:true (session-owned: it ends with the session, and the orchestrator waits for it in-turn). No model runs while it waits, so no watcher agent is spawned for a PR (the pr-watcher-agent-guard hook denies one). Re-enter when its exit notification arrives. No poll interval, no --watch, no inline sleep loop. Full procedure, spawn shape, and the four-state report read: references/wait-delegation.md.

Ship Mode — one background script, PR opened to merged and released

Section titled “Ship Mode — one background script, PR opened to merged and released”

Right after a PR you opened is up, launch ONE background script instead of hand-polling checks, re-runs, the merge and the Release run:

Terminal window
P=".claude/scripts/t1k-pr-ship.cjs"; [ -f "$P" ] || P="$HOME/.claude/scripts/t1k-pr-ship.cjs"
bun "$P" --repo <owner>/<repo> --pr <n> --timeout-min 45 # session-owned run_in_background; read ONLY the last stdout line
# the head branch is DELETED on merge by default; opt out with --no-delete-branch

It composes the PR watcher (references/wait-delegation.md) and prints exactly one of [t1k:pr-shipped pr=N merge=<sha> release=<ok|superseded|skipped> tags=<module@version,...>] (exit 0) or [t1k:pr-stuck pr=N reason=<token>] (exit 1 needs a human or a fix, exit 2 no verdict). Done (Core Requirement 11) is the shipped line, not “PR opened” or “merged”.

  • Failed required check: INFRA (clock skew, App token missing, lost runner, full disk, or a failing test named by an OPEN flaky test: issue) gets gh run rerun --failed ONCE per check, then escalates. Anything else is REAL: it stops with the failing test names and is never re-run (Core Requirement 14).
  • Merge: a direct gh pr merge --squash --match-head-commit <green sha> after a fresh mergeability read, because --auto is refused as “clean status” once nothing is pending. Never --admin, never past red or pending, never a PR that is not yours, a draft, held, a fork, or a theonekit-* PR from a clone that is not that kit (hard stops, rules/kit-pr-workflow-boundary.md).
  • Head branch delete (default ON): the merge adds --delete-branch, because on a repo whose delete_branch_on_merge is false nothing else removes the head and the branch leaks (the 2026-10-16 incident: 13–26 leaked branches per repo on the1platform-core, studio-auth, The1Platform, marketing-hub). --no-delete-branch opts out. Two guards always win: a LONG-LIVED head (a base branch such as staging on the promotion PR, or any protectedBranches.globs name) and a head branch checked out in ANY worktree — a home branch, flag or no flag (skills/t1k-git/references/worktree-home-branch.md).
  • Release: waits for the Release run on the merge commit; a cancelled run is superseded when a later run’s tag contains the merge.

Classification table, exit codes, what it does not do (Plane and Jenkins post-merge hooks do not see its merge), --dry-run: references/ship-mode.md. The wait-and-judge flow below stays the manual path.

Red from a stale merge ref — main was red under me, now fixed

Section titled “Red from a stale merge ref — main was red under me, now fixed”

A required check can fail on a PR whose diff cannot cause it: it ran on refs/pull/<N>/merge, built on a main that was red, and that ref does not recompute when main is fixed. gh run rerun --failed re-tests the same frozen ref and cannot clear it. Detect with the fetch + merge-base --is-ancestor + merge-tree triple; own PR only: git merge --no-ff origin/main, normal push, once, then resume the watch. Not your PR, conflicts, or main still red: do not act, escalate with the named cause. Commands, evidence and message: references/stale-merge-ref.md.

A merge this skill performs is the one merge an in-session step can observe, so it is the one that carries the decision. When the merge target is a develop-class branch and the repo has a Jenkins job, run the t1k-jenkins-build decision — facts, rubric, verdict — and report it alongside the merge result.

Skip silently, in one line, when there is no job for the repo/branch or no Jenkins credential resolves. A missing Jenkins is not a failure of this skill and must never fail the merge report. The decision never triggers a Release job. Because auto-merges are commonly observed post-session, this covers only the merges babysit actually performs — a merge landing after the session ends gets no decision, which is the accepted gap (phase 8b).

Dedupe against the jenkins-build-nudge hook’s frame (R12). The gh pr merge Bash call this step performs is the same call the hook watches, so it can ALSO fire the hook’s own [t1k:develop-build-decision ...] frame this same turn. Match by repo + PR number, per t1k-jenkins-build/SKILL.md § “Avoiding a double decision (R12)” — when a matching frame already appeared this turn, this step’s own merge is that SAME decision, not a second one: run the decision once, report one verdict. Only decide independently here when no matching frame appeared.

FlagDefaultDescription
--dry-runoffPrint actions without executing them
--max-retries3Max CI retry attempts before escalating
--no-auto-mergeoffSkip merge step (monitor only)

There is no --poll-interval — the background script owns its own cadence (--interval-sec). agents/t1k-ci-watcher.md serves non-PR targets only. gh quota: skills/t1k-git/references/github-api-limits.md.

Terminal window
S=".claude/scripts/t1k-gh-status.cjs"; [ -f "$S" ] || S="$HOME/.claude/scripts/t1k-gh-status.cjs" # skills/t1k-git/references/gh-status-lookup.md
bun "$S" pr <owner/repo> <number> --json --fresh --expect-head <sha> # the read behind a merge/arm decision: direct, same head
gh pr view <number> --json reviews,mergeable
gh run rerun <run-id> --failed
gh pr merge <number> --squash --auto
gh pr diff <number>
  • Approved review, only where branch protection requires one (never a gate on your own session’s PR)
  • No changes-requested reviews
  • All required status checks green
  • No merge conflicts
  • PR is not in draft state

Auto-resolve (safe):

  • Documentation-only files (.md, CHANGELOG, docs/)
  • Generated files with clear regeneration command
  • Package lock files (re-generate from manifest)

Escalate to user (unsafe — stop):

  • Overlapping logic in source files
  • Schema or migration conflicts
  • Any conflict in security-sensitive files

gh pr merge --auto is a one-way action: it merges the instant required checks go green, and nothing later can call it back. So do NOT arm it while a gate the user wants held is pending — an open review, a gate the user asked to inspect before landing, a check whose result decides whether the PR should land at all.

Polling cannot stop an armed --auto. A watcher that later reports the held gate red arrives after GitHub already merged on whatever it considered required. If the user wants a hold, the hold is not arming — watch, report, and let the user release it.

This is the one decision on this path that a later report cannot undo, so it is the one that must be made before the wait starts, not during it.

A draft PR carrying the t1k:claim label and body marker t1k-claim: owner/repo#N represents a live claim on the referenced issue. babysit-pr observes the following lifecycle states:

PR stateClaim state
Draft (isDraft: true) + t1k:claim labelLive claim — issue is booked
Ready-for-review (isDraft: false)Released-to-review — claim transitioning to merge
Merged or closedClaim ended — GitHub state is the truth; no extra mutation needed

Auto-release on merge/close: when babysit observes the PR merge or close, the claim is automatically released by the merge/close event itself. No additional gh issue edit or claim script call is needed.

Check for competing draft PRs on the same issue on each check where a draft with the t1k:claim label first appears — on first observation, and again on every watcher report after a state change on the tracked issue. That bounds how often it runs while still catching a rival claim raised mid-wait. Monitoring signal only — babysit-pr does NOT auto-close. Shared procedure with t1k-triage’s Step 3-dup, full detail: skills/t1k-triage/references/competing-pr-backstop.md (../t1k-triage/references/competing-pr-backstop.md).

Admin-Merge Mode (data-driven, default OFF)

Section titled “Admin-Merge Mode (data-driven, default OFF)”

Admin-merge is an opt-in mode gated by issueClaim.adminMerge.enabled in .claude/t1k-config-core.json. It is OFF by default.

When it fires: ONLY when ALL of the following are true:

  1. adminMerge.enabled == true in config
  2. PR is not draft (isDraft: false)
  3. statusCheckRollup == SUCCESS (all required CI checks green)

Command:

Terminal window
gh pr merge <N> --admin --squash --delete-branch

What --admin bypasses: the required-human-review branch protection rule ONLY — so an unattended PR (e.g., a sync-back PR with no available reviewer) can land. It does NOT bypass red or pending CI.

--delete-branch (both commands above) requires a TOPIC-branch head. A PR from a linked worktree’s HOME branch (git rev-parse --git-common-dir ≠ .git) merges WITHOUT the flag, then the home branch is re-pointed — never deleted: skills/t1k-git/references/worktree-home-branch.md.

Fallback when CI is red or pending: do NOT admin-merge. Fall back to standard auto-merge:

Terminal window
gh pr merge <N> --auto --squash --delete-branch

Report the fallback reason. Never silently override CI status.

Config reference: issueClaim.adminMerge block in t1k-config-core.json:

  • enabled (bool, default false) — master gate
  • requireCiGreen (bool, default true) — enforced; admin-merge never fires on red/pending CI
  • bypassReview (bool, default true) — documents that --admin bypasses required-review ONLY

This is the SSOT for admin-merge logic. Phase 4’s ship pipeline invokes this mode; it does not duplicate the merge prose here.

  • Admin-merge CI gate: --admin NEVER bypasses red or pending CI. If statusCheckRollup != SUCCESS, fall back to --auto and report. Do not silently land a bad PR.
  • Never force-push or rewrite history on shared branches. A stale merge ref is cleared by a merge commit, not a rebase.

On first check only, invoke t1k:contribution-score with type=sync-back-pr + PR URL/title/body (catches PRs opened outside any T1K skill). Fire-and-forget; SSOT gates non-T1K repos. See .claude/skills/t1k-contribution-score/SKILL.md.