babysit-prs: codify the decide-and-defer non-convergence resolution playbook (own-once, no duplication of safety.md)

[kyle-sexton]

Problem

When a PR's review threads keep regenerating DISTINCT findings of the same class (an inherently
leaky fix surface), patching never converges. The playbook that cleared these PRs:

1. Verify genuine non-convergence, not legitimate per-finding depth.
2. Make the scope/architecture call.
3. Ship-if-strictly-better + file a tracked follow-up (residual gaps + durable root-cause approach).
4. Resolve the threads on that decided-and-tracked basis.
5. Merge.

Done ad-hoc via Opus agents each time; codify it. Evidence: dotfiles#213, #224; follow-ups
dotfiles#232, plugins #365 / #366 / #367. Retrospective
.work/handoffs/babysit-autopilot-retro.md §1.6 / §2.2.

Recommended shape (re-derived blind to the original "skill" framing)

NOT a skill, NOT an engine signal. Extend the existing references — almost entirely pointers.
The constituent parts already exist across three owners; a new skill would restate them and drift:

1. Verify genuine non-convergence → owned by reference/safety.md "Verify Before Escalating
   Non-Convergence". Point, do not restate the (a)/(b) test.
2. Ship-if-strictly-better + tracked follow-up → the fix-now-or-ticket rule already owned by the
   pull-request skill's reference/monitor.md ("never merge past a confirmed-valid finding with
   neither a fix nor a tracked issue"). Point — ideally lift it to the shared plugin
   reference/review-discipline.md so both skills point at one copy.
3. Durable disposition so later snapshots don't re-flag the deferred finding → owned by
   reference/feedback.md "Feedback Dispositions" (dispose --reason …). Decide-and-defer is
   mechanically a new deferred disposition reason (one reason line + a new accepted --reason
   value in the ledger).
4. Resolve-on-decided-basis + gate-proven merge → guarded wrappers already owned by safety.md +
   SKILL.md autopilot widening.

New content — one home

The only genuinely new content is the thin sequencing playbook + the autopilot authorization. Home:
a new subsection under safety.md's "Verify Before Escalating Non-Convergence" (the most-pointed-at
owner of the non-convergence flow; the resolution is a mutation-authorization nuance = safety's
domain), plus the deferred reason line in feedback.md. orchestration.md Fix-Round-Cap and
SKILL.md autopilot each gain one pointer to it. Each fact stays owned once.

Load-bearing reconciliation (verified)

The babysit merge gate blocks on ANY unresolved thread unconditionally
(scripts/babysit_merge.py:253 if threads: → blocker; independent of GitHub's
requireThreadResolution, which it tracks separately). So — unlike the human-judgment merge in the
pull-request skill's monitor.md, where you can merge-past-with-a-ticket and leave the thread open —
reaching a babysit gate-proven merge REQUIRES resolving the deferred threads. This is not a new
invariant: it applies autopilot's existing "addressed → resolve" widening to a new "addressed" class
= decided-and-deferred-to-a-tracked-follow-up. Reconcile explicitly with safety.md's "never resolve
a thread over a live, unaddressed finding" and feedback.md's "a disposition never overrides
structured CHANGES_REQUESTED". Therefore: autopilot-only; applies to bot/AI-review threads and
(under the human widening) addressed human threads; never an unaddressed live CHANGES_REQUESTED.

Files

• reference/safety.md — new "Decide-and-Defer Resolution (autopilot)" subsection
• reference/feedback.md — new deferred disposition reason

Rejected shapes

Separate skill (restates safety.md + monitor.md = 2nd/3rd copies, drift), engine signal/script
(genuine non-convergence is a content judgment the engine is explicitly forbidden to make from
metadata — round count alone is insufficient by design), subagent (the verify step can reuse the
existing review-discipline extractor; the decide-and-defer call is orchestrator judgment, not
fan-out).

[kyle-sexton]

Lane

babysit (safe tier, /loop 15m /source-control:babysit-prs)

Triggering example

#467 (fix(toolchain): resolve default branch by detection, not assumption), rounds 2-5 this session — a clean, real-time instance of exactly the pattern this issue describes:

• Round 2: DEFAULT_BRANCH used before assignment on clean-tree path (fixed)
• Round 3: diff-via-feature-upstream-ref equalled HEAD, producing a silently empty diff (fixed — switched to origin/HEAD detection)
• Round 4: hard-coded origin breaks non-origin remotes (fixed — added branch.<name>.remote detection)
• Round 5: TWO more new codex P2/P1 findings on the exact same remote/branch-resolution block — "resolve the remote default branch instead of the feature upstream" and "select an existing remote when the feature branch has no upstream"

At round 5 the worker was explicitly briefed on this issue's criteria and did the verify-before-escalating analysis your safety.md section describes (read actual thread content, not just round count): confirmed the findings are real and distinct, confirmed the current state is strictly better than PR start (3 genuine bugs fixed), identified the root cause as a hand-rolled resolver duplicated across two files when a canonical implementation already exists in-repo (git-tree-reset.sh's gh repo view --json defaultBranchRef fallback), classified+deferred both round-5 findings with a recommendation instead of attempting a 5th narrow patch, and flagged explicitly that gate-green here (READINESS_OK) was a coincidental token-balance, not proof of full address — a real trap this exercise surfaced.

Observed vs expected

Observed: the judgment call (verify non-convergence, defer with a recommendation rather than patch a 5th time) already works when a worker is explicitly briefed with the pattern and pointed at safety.md's Verify-Before-Escalating section — but this only happened because the orchestrator (main babysit loop) recognized the 4-consecutive-rounds pattern itself and hand-authored a bespoke prompt for it. Expected per this issue: the engine should surface this signal so the orchestrator doesn't have to notice it by eyeballing round history — e.g. a same_thread_reopened_after_reply or consecutive_new_findings_same_file_count field in the snapshot, so a generic worker dispatch (not a specially-crafted one) gets routed into the decide-and-defer playbook automatically.

Category

behavioral

Note

This is supporting evidence for the issue's own "Evidence" section (dotfiles#213/#224, plugins#365/#366/#367) — same pattern, different repo/plugin, useful as a second independent data point for whatever the eventual snapshot signal design looks like.

[kyle-sexton]

This was generated by AI during triage.

T2 triage planning comment. Implementation plan below, verified against the live skill code/docs. Ends with an open design question that gates ratification.

---

Verification against the live code (all claims confirmed)

Paths are under plugins/source-control/skills/babysit-prs/.

1. Merge gate blocks on ANY unresolved thread, unconditionally. scripts/babysit_merge.py:253 — if threads: appends a blocker ("{n} unresolved review thread(s) … -- resolve or address the finding") for every unresolved thread. requireThreadResolution is tracked separately (defaulted False at line 106; surfaced under effectiveRules at 136), and is not what drives this blocker. So the issue's load-bearing claim holds exactly: reaching a gate-proven babysit merge requires actually resolving the deferred threads — a durable disposition alone never clears the gate.
2. dispose --reason is free-form; deferred is a docs-only addition. scripts/manage_feedback_ledger.py:194-196 declares --reason with no choices= enum (help text: "typically approval, stale, or non-actionable"). Adding deferred therefore needs zero code change — it is a new documented reason string. The helper (line 220-221) only requires --feedback-id + --reason present.
3. The deferred finding is a disposable feedback id. Feedback ids are <prefix>:<value> (scripts/babysit_feedback.py:159-171 item_id); a regenerating codex inline finding surfaces as inlineReview:<id> (bot review) in the PR's blocking/material id space (scripts/babysit_delta.py:346-347). dispose requires the id be present among those ids — it is. Note the two distinct id spaces: dispose keys off the snapshot feedback id (inlineReview:…/review:…); source-control-babysit-resolve-thread --thread-id keys off the GraphQL thread id. Both actions are needed and target different identifiers.
4. Cross-ref conventions (match existing style): from a reference/*.md file, sibling refs are bare backticked filenames (e.g. `safety.md`); from SKILL.md, they are `reference/safety.md`.

Load-bearing conflict this plan MUST resolve (not just point at)

SKILL.md Autopilot step 2 (lines 148-149) states as an absolute:

"A thread is resolved only because its concern is fixed or confirmed stale — never to clear the merge gate over a live concern."

Decide-and-defer resolves over a concern that is genuine, unfixed, and not stale, specifically to clear the merge gate. That is an unavoidable third resolution basis. A one-line pointer into step 2 would point into text that forbids the very thing it points to — an implementer following step 2 literally would refuse to defer. SKILL.md step 2 therefore needs a wording edit, not just a pointer (see change 4 below). This is the crux and the open question at the end.

Change set — four files, docs-only, each fact owned once

1. reference/safety.md — new subsection (the only genuinely new content)

Insert immediately after the "Verify Before Escalating Non-Convergence" section (after line 113), before "Guarded Mutation Wrappers":

### Decide-and-Defer Resolution (autopilot)

When the Verify step above confirms case-(a) genuine non-convergence — review threads that keep
regenerating distinct findings of the same class on an inherently leaky fix surface, each finding
real but the surface never converging under patching — autopilot may resolve those threads on a
decided-and-tracked basis instead of attempting an unbounded next patch round. In order:

1. **Verify it is genuine.** Confirm case (a) by reading actual thread content per the section
   above — distinct findings of the same class recurring on the same surface — never a high round
   count or a second opinion's metadata read.
2. **Make the scope/architecture call.** The root cause is usually a structural choice (a
   hand-rolled surface where a canonical in-repo implementation already exists, or a design the PR
   was never scoped to rewrite), not the individual findings. Decide whether the durable fix is
   in-scope for this PR or belongs to a follow-up.
3. **Ship-if-strictly-better + tracked follow-up.** Proceed only when the PR's current state is
   strictly better than its start (genuine defects fixed, nothing regressed), and only under the
   fix-now-or-ticket rule that already governs merging past a confirmed-valid finding
   (`review-discipline.md`, VALID (defer); the pull-request skill's `monitor.md` §3.3 Phase A owns
   the "never merge past a confirmed-valid finding with neither a fix nor a tracked issue"
   statement). File a durable follow-up issue capturing the residual gaps AND the durable
   root-cause approach, and link it.
4. **Record the deferral durably.** Dispose each deferred finding in the feedback ledger with the
   `deferred` reason (`feedback.md`, Feedback Dispositions) so a later snapshot cycle does not
   re-flag it as a fresh blocker.
5. **Resolve the threads on that decided-and-tracked basis** via the autopilot resolve wrapper
   (`--resolve --include-human`, Guarded Mutation Wrappers below). The babysit merge gate blocks on
   ANY unresolved thread (`scripts/babysit_merge.py`, the `if threads:` blocker), independent of
   GitHub's `requireThreadResolution`, so a deferred disposition alone does not clear the gate —
   the thread must actually be resolved. Disposition and resolution key off different identifiers
   (the snapshot feedback id vs. the GraphQL thread id); do both.
6. **Merge** through the deterministic gate.

**Authorization scope — autopilot only.** This is a mutation-authorization nuance, not a new
invariant: it admits one new "addressed" class — decided-and-deferred-to-a-tracked-follow-up — to
autopilot's existing addressed-thread widening (`SKILL.md`, Autopilot). It applies to bot and
AI-review threads and, under that same human widening, to addressed human threads. It NEVER applies
to an unaddressed live `CHANGES_REQUESTED` or any live human blocking finding — those stay
stop-and-ask in every tier until GitHub state resolves them (`feedback.md`; a disposition never
overrides structured `CHANGES_REQUESTED`). Safe and worker tiers do not resolve on this basis (safe
never resolves; worker resolves only pre-push-outdated bot threads). For the "never resolve a thread
over a live, unaddressed finding" rule (Never Do Automatically) and the "address first, then
resolve" order, a decided-and-tracked finding counts as **addressed**; an undecided, untracked
finding does not — resolving over it stays forbidden.

2. reference/feedback.md — the deferred disposition reason

(a) In the "Feedback Dispositions" intro sentence (line 51-52), widen the triage-outcome list:

• from: as an approval, stale, or non-actionable,
• to: as an approval, stale, non-actionable, or deferred,

(b) Add a bullet to the same section's list (after the --feedback-id / dispositioned-ids / CHANGES_REQUESTED bullets, ~line 64):

- `deferred` — a finding verified as genuine but consciously deferred to a tracked follow-up under
  the decide-and-defer non-convergence playbook (`safety.md`, Decide-and-Defer Resolution): the PR
  shipped strictly-better with the residual gap and root-cause approach captured in a linked
  follow-up issue, so a later snapshot cycle must not re-flag it as a fresh blocker. Autopilot-only;
  never a substitute for addressing a live `CHANGES_REQUESTED`. `--reason` is free-form, so
  `deferred` is a documented reason string, not a ledger code change.

3. reference/orchestration.md — one-line pointer in "Fix-Round Cap"

Append to the Fix-Round Cap section's final sentence (after line 391, which already routes to
safety.md's Verify Before Escalating Non-Convergence):

When that verification confirms case-(a) non-convergence rather than gating a next round, the
autopilot resolution path — decide the scope call, ship-if-strictly-better with a tracked follow-up,
defer, resolve, merge — is `safety.md`'s Decide-and-Defer Resolution (autopilot).

4. SKILL.md — wording edit to Autopilot step 2 (NOT merely a pointer)

Autopilot step 2 (lines 148-149) currently reads: "A thread is resolved only because its concern
is fixed or confirmed stale — never to clear the merge gate over a live concern." Widen the
resolution basis to admit the deferred class and point to the owner:

• from: A thread is resolved only because its concern is fixed or confirmed stale — never to clear the merge gate over a live concern.
• to: A thread is resolved only because its concern is fixed, confirmed stale, or (autopilot only) decided-and-deferred to a tracked follow-up per reference/safety.md's Decide-and-Defer Resolution — never to clear the merge gate over a concern that has had no fix, no staleness finding, and no tracked deferral.

This single edit doubles as the required SKILL.md pointer; no separate pointer line is needed.

Optional, in-scope-but-separable (own-once improvement)

The issue notes the fix-now-or-ticket rule ideally be lifted from the pull-request skill's
monitor.md §3.3 into the shared source-control/reference/review-discipline.md so both skills
point at one copy (review-discipline.md already owns the adjacent VALID (defer) classification,
so the seam exists). This plan points at the existing owner rather than restating it, which is
sufficient and non-drifting on its own. Trigger to do the lift: if a third caller needs the same
"never merge/defer past a confirmed-valid finding with neither a fix nor a tracked issue" sentence,
or the next monitor.md/safety.md edit touches it — lift then, updating both pointers. Recorded as
deferred, not dropped.

Verification after implementation

• Docs-only change; no script edits. Run the repo's markdown lint/format over the four files.
• Grep-confirm no fact is stated twice: the fix-or-ticket rule appears only in monitor.md (pointed
  at, not copied); the merge-gate-blocks-on-any-thread fact appears once in the new safety.md
  subsection.
• Confirm the four cross-refs resolve to real section headings.

Open design question (why this is routed for human ratification)

Change 4 weakens a stated safety absolute on the most autonomous tier: it lets autopilot resolve
a review thread over a live, genuine, unfixed finding — to force a merge — gated only on the agent's
own content judgment of "genuine non-convergence." That is a principled carve-out, but it is a
design ratification call, not mechanical codification: issue #375 is a needs-triage proposal
whose author "re-derived blind" (thinking-out-loud), not an approved spec. A human should
explicitly bless overriding SKILL.md step 2's "resolved only because fixed or confirmed stale …
never to clear the merge gate over a live concern" before this ships. The plan above is concrete and
implement-ready once that carve-out is approved; quality is not the blocker, authorization is.

[kyle-sexton]

This is an AI-generated decision brief. ~2 minutes.

Decision brief — reframing the T2 triage plan (implement-ready, but ends in one open ratification question) into a discrete decision. The change set there is drafted and correct; this brief exists to get the one authorization call made, not to re-derive it.

Problem

Should babysit autopilot be authorized to resolve a review thread over a live, genuine, unfixed finding — specifically to clear the merge gate — when non-convergence has been rigorously verified? And if yes, does the already-drafted docs/wording change correctly scope that authorization to autopilot-only, verified-genuine, ship-if-strictly-better, tracked-follow-up?

Today (verified against live code)

• SKILL.md Autopilot step 2 (lines 148-149) forbids exactly this, verbatim: "A thread is resolved only because its concern is fixed or confirmed stale — never to clear the merge gate over a live concern." Decide-and-defer resolves over a finding that is genuine, unfixed, and not stale — an unavoidable third resolution basis step 2 currently prohibits.
• The merge gate hard-blocks on any unresolved thread. scripts/babysit_merge.py — the if threads: branch appends a blocker for every unresolved thread ("{n} unresolved review thread(s) … resolve or address the finding"), independent of GitHub's requireThreadResolution. So reaching a gate-proven babysit merge requires actually resolving the deferred threads; a durable disposition alone never clears the gate.
• What the plan changes: one wording edit to SKILL.md step 2 (admit a "decided-and-deferred to a tracked follow-up, autopilot only" basis), plus three additive pointers/reasons (reference/safety.md new subsection, reference/feedback.md new deferred reason, reference/orchestration.md one-line pointer). Docs-only; --reason is already free-form so no script change. Full before/after wording lives in the T2 comment.

External facts

N/A — internal governance / design-ratification call. No external sourcing applies.

Options

Option 1 — Approve the carve-out as drafted (autopilot-only). RECOMMENDED.
Ship the 4-file change set as written. The authorization is already tightly fenced: verify-before-escalating (read actual thread content, not round count), ship-only-if-strictly-better, mandatory tracked follow-up issue capturing residual gaps + durable root-cause approach, deferred disposition logged, autopilot-only, and never over a live unaddressed CHANGES_REQUESTED. Together these leave a complete audit trail for every exercise.
Rationale — on the reversibility asymmetry: the docs wording reverts cheaply, but the behavior it unlocks does not — once autopilot resolves a live thread to force a real merge, that merge is in history and cannot be undone. The load-bearing risk is therefore autopilot self-judging "genuine non-convergence" on an irreversible action. The drafted guardrails mitigate this specifically: the decision is content-gated (not metadata/round-count), the outcome is bounded to strictly-better states, and the residual is always tracked — meaning a wrong self-judgment surfaces as a filed follow-up + logged disposition rather than a silent lost finding. That audit trail is what makes the irreversible action acceptable, and it is why this beats keeping the rule absolute (Option 3, which would strand real "clearly-better, non-converging" PRs the retro shows recurring). Reversibility of the wording keeps the downside cheap if the trail later shows the trust was misplaced.

Option 2 — Approve but narrow further.
Same carve-out, but require an explicit secondary check before it fires (e.g. a second-agent confirmation of case-(a) non-convergence, or restrict first to bot/AI-review threads and defer the human-thread widening). Higher assurance on the self-judgment risk; more mechanism, and partly redundant with the existing verify step.

Option 3 — Reject; keep step 2 absolute.
Autopilot always stop-and-asks on genuine non-convergence rather than self-authorizing a merge. Maximum safety, zero new irreversible authority — but it strands the exact clean-but-non-converging PR class the retro documents (dotfiles#213/#224, plugins#365-367, live #467), forcing a human into every instance and defeating the issue's purpose.

Option 4 — Approve for a trial period with a review checkpoint.
Ship as drafted, but bound the first N exercises (or a fixed window) and review every decide-and-defer merge before making the authorization standing. Directly targets the "first real exercise can't be undone" concern via human oversight on early instances; cost is a bit of process and a checkpoint someone must own.

Note: Options 1 and 4 are compatible — approving as drafted and attaching a first-exercises checkpoint is a reasonable merge if the irreversibility concern outweighs trust in the drafted guardrails.

Cross-link

Interacts with #476 (feat(source-control): babysit autopilot merge tier, OPEN, priority: high, status: ready). This carve-out is the mechanism that tier would exercise to reach a gate-proven merge past a decided-and-deferred thread — so the ratification decided here gates behavior #476 depends on.

The ask

Pick an option. On Option 1/2/4 the T2 change set is implement-ready as-is; on Option 3 the plan is dropped and step 2 stays absolute. Quality is not the blocker — authorization is.