t1k:babysit-pr
| Field | Value |
|---|---|
| Module | t1k-maintainer |
| Version | 4.10.58 |
| Effort | medium |
| Tools | — |
Keywords: ci, flaky, merge, monitor, pr, pull-request, watch
How to invoke
Section titled “How to invoke”/t1k:babysit-pr<pr-number-or-url> [--dry-run]TheOneKit Babysit PR
Section titled “TheOneKit Babysit PR”Monitor a pull request until it is merged. Handles flaky CI, simple merge conflicts, and auto-merges when conditions are met.
Trigger Phrases
Section titled “Trigger Phrases”“babysit pr”, “babysit-pr”, “watch pr”, “monitor pr”, “auto merge”, “flaky ci”
Workflow
Section titled “Workflow”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 exitThe 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:
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-branchIt 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) getsgh run rerun --failedONCE 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--autois 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 atheonekit-*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 whosedelete_branch_on_mergeisfalsenothing 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-branchopts out. Two guards always win: a LONG-LIVED head (a base branch such asstagingon the promotion PR, or anyprotectedBranches.globsname) 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
supersededwhen 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.
Post-Merge: develop build decision
Section titled “Post-Merge: develop build decision”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.
Operations
Section titled “Operations”| Flag | Default | Description |
|---|---|---|
--dry-run | off | Print actions without executing them |
--max-retries | 3 | Max CI retry attempts before escalating |
--no-auto-merge | off | Skip 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.
Commands Used
Section titled “Commands Used”S=".claude/scripts/t1k-gh-status.cjs"; [ -f "$S" ] || S="$HOME/.claude/scripts/t1k-gh-status.cjs" # skills/t1k-git/references/gh-status-lookup.mdbun "$S" pr <owner/repo> <number> --json --fresh --expect-head <sha> # the read behind a merge/arm decision: direct, same headgh pr view <number> --json reviews,mergeablegh run rerun <run-id> --failedgh pr merge <number> --squash --autogh pr diff <number>Merge Conditions (all must be true)
Section titled “Merge Conditions (all must be true)”- 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
Conflict Resolution Policy
Section titled “Conflict Resolution Policy”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
Do Not Arm Auto-Merge Past a Held Gate
Section titled “Do Not Arm Auto-Merge Past a Held Gate”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.
Claim Lifecycle Awareness
Section titled “Claim Lifecycle Awareness”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 state | Claim state |
|---|---|
Draft (isDraft: true) + t1k:claim label | Live claim — issue is booked |
Ready-for-review (isDraft: false) | Released-to-review — claim transitioning to merge |
| Merged or closed | Claim 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.
Competing-PR detection
Section titled “Competing-PR detection”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:
adminMerge.enabled == truein config- PR is not draft (
isDraft: false) statusCheckRollup == SUCCESS(all required CI checks green)
Command:
gh pr merge <N> --admin --squash --delete-branchWhat --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:
gh pr merge <N> --auto --squash --delete-branchReport the fallback reason. Never silently override CI status.
Config reference: issueClaim.adminMerge block in t1k-config-core.json:
enabled(bool, defaultfalse) — master gaterequireCiGreen(bool, defaulttrue) — enforced; admin-merge never fires on red/pending CIbypassReview(bool, defaulttrue) — documents that--adminbypasses 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.
Hard rules
Section titled “Hard rules”- Admin-merge CI gate:
--adminNEVER bypasses red or pending CI. IfstatusCheckRollup != SUCCESS, fall back to--autoand report. Do not silently land a bad PR.
Hard rules
Section titled “Hard rules”- Never force-push or rewrite history on shared branches. A stale merge ref is cleared by a merge commit, not a rebase.
Contribution Scoring
Section titled “Contribution Scoring”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.