docs(source-control): wire babysit autopilot §3 to the tier flags, specify the approve mechanic and review-context precondition (#675)

[kyle-sexton]

Closes #675

Gate-off flip precondition for the autopilot merge tier (#476). All changes are prose/contract + test-pinning: no behavioral change to the merge gate or any script, and the tier still ships DISABLED.

Implements the operator-approved RECOMMENDED options recorded on #675:

• §3 wiring — fork (b), reference-file restructure. Autopilot's step 3 in SKILL.md no longer inlines a base-only merge command that would ignore the tier flags when the tier is enabled. It now points at reference/safety.md, the single home for both the base and the enabled-tier merge paths, so an ENABLED config can no longer merge via the flagless base path. Chosen over raising the skill-quality line cap (SKILL.md sits at 499/500).
• Second-account approve mechanic (specified). The concrete out-of-band approval the gate's distinct-bot criterion requires: gh pr review … --approve under a distinct <approver-bot-logins> identity (GH_TOKEN or gh auth switch, never the PR author or a lane identity), only after a genuine clean review pass, on the live head so --expected-head holds.
• Review-context requiredness — fork (a), required-context precondition. Enabling the tier now carries a documented operator precondition: the base branch ruleset must make the review workflow a required status context, so mergeStateStatus == CLEAN actually proves the review ran. Chosen over a merge-gate review-context config (rejected fork b) to keep the gate deterministic with nothing new to wire — and deliberately kept distinct from the existing snapshot-side babysit_review_gate_context (a review-trigger timing signal, not a merge predicate).

The skill-contract tests are split/extended to pin all three contracts against drift (the worker-tier push paragraph, which has no merge tier, keeps its inline-command assertion).

Related

• Stacked on feat(source-control): babysit autopilot merge tier, gate-enforced and disabled by default #665 (feat/476-autopilot-merge-tier) and must land after it — this PR is based on that branch, not main; retarget to main once feat(source-control): babysit autopilot merge tier, gate-enforced and disabled by default #665 merges.
• Version reconciliation at rebase: bumped to 0.14.1, continuous with the current base (feat/476 @ 0.14.0). feat(source-control): babysit autopilot merge tier, gate-enforced and disabled by default #665's plugin version is being re-composed to 0.15.0 (collision with feat(source-control): layer convention config across three layers #660's 0.14.0); when feat(source-control): babysit autopilot merge tier, gate-enforced and disabled by default #665 lands, rebase this and re-bump to one increment past whatever main then carries (expected 0.15.1).
• Precedent for the flip-precondition designation: babysit classifier: count_classified counts stale pipe-row classifications from non-thread review-summary comments #642, feat(source-control): babysit autopilot merge tier — bot-account review + criteria-gated merge #476.

Verification

• engine.test.sh: 312 tests pass, ruff clean, guarded-wrapper behavior checks pass.
• check-skill.sh babysit-prs: PASS (SKILL.md 499/500, internal refs resolve, markdownlint clean).
• markdownlint on safety.md + CHANGELOG.md: 0 errors.

🤖 Generated with Claude Code

[claude]

Claude finished @kyle-sexton's task in 2m 22s —— View job

---

PR Review

• Gather context and read PR changes
• Review SKILL.md changes (§3 wiring fork b)
• Review reference/safety.md additions (merged merge paths)
• Review test_skill_contract.py (split/extended contract tests)
• Review plugin.json (version bump)
• Review CHANGELOG.md

---

Overall this is a well-executed prose/contract PR. The design choices are sound and the implementation is coherent. No correctness bugs or security issues found. A few observations below, mostly minor.

SKILL.md — §3 redirection (fork b)

The rewrite of step 3 correctly removes the inlined flagless merge command and points at safety.md. The new wording is precise: it names the gate wrapper, mentions the tier-flag layering, and anchors everything to the single home. The phrase "exact command … is the single home in reference/safety.md" is clear about the indirection intent.

One wording nit: the Autopilot merge tier paragraph (line 181) now uses "The concrete enabled-path merge command, the second-account approve mechanic, and the review-workflow requiredness precondition for enabling the tier are the single home in reference/safety.md." Grammatically, three items cannot be "the single home" (a collective is fine, but "single home" implies one item). A minor clarification like "are documented in the single home, reference/safety.md" would read more naturally. Not blocking.

# current (line 181)
...are the single home in [reference/safety.md](reference/safety.md).
# suggested
...are documented in the single home, [reference/safety.md](reference/safety.md).

reference/safety.md — Enabled-Path Mechanics section

Enabled-path merge command. The prose "never the four-flagless base command" is correct and appropriately alarming. The exit 3 / exit 2 distinction (umbrella without params vs. param without umbrella) is a useful operational detail.

Second-account approve mechanic. The two equivalent forms (GH_TOKEN=… vs. gh auth switch) are both documented — good. The constraint chain (distinct identity → genuine pass → submit only on clean → submit on live head so pin holds) is complete and properly ordered. No gaps found.

Review-workflow requiredness precondition. The logic is sound: mergeStateStatus == CLEAN only proves required contexts passed, so a merely-present but optional review workflow offers no CLEAN-status guarantee. The conclusion ("operator enabling precondition, verified before the flip, not something the merge gate can self-enforce") is correct and is the right scope for this document.

One detail worth confirming: the section says "the review workflow" without naming which workflow check context the operator must require. The PR description notes this is "deliberately kept distinct from the existing snapshot-side babysit_review_gate_context," which makes sense, but an operator reading only safety.md may wonder which specific workflow name to mark required. A parenthetical like "(the same check name reported by your review CI job)" or a pointer to the babysit_review_gate_context config as a hint for identification would reduce ambiguity. Not blocking, but worth noting.

The long single-line command block (line 177 in safety.md) is acceptable — splitting a CLI example with continuations would make it harder to copy. Markdownlint already passes per the PR description.

test_skill_contract.py — test split and new assertions

Test split is correct. The original test_worker_push_paths_require_the_post_push_head was looping over two markers ("After the worker's final push" and "In worker mode, after a worker's fix") with identical assertions. Since the contracts are now different (worker tier keeps the inline command; autopilot §3 delegates to safety.md), splitting these into two focused tests with divergent assertions is exactly right.

test_autopilot_step3_points_at_safety_for_the_tier_wired_command: The assertion self.assertIn("--autopilot-merge-tier", paragraph) works because the prose contains `--autopilot-merge-tier` and substring match passes through backticks. This is technically correct but implicit — a future reader might wonder why there are no backticks in the assertion string. A one-line comment would help:

# The backtick-wrapped `--autopilot-merge-tier` in prose satisfies a plain substring check.
self.assertIn("--autopilot-merge-tier", paragraph)

Again, not blocking.

test_safety_md_specifies_the_enabled_path_mechanics: The multi-line string assertion for the four-flag sequence correctly relies on the command being a single physical line in safety.md's code block — no newline can break the match. The comment on line 174 ("Fenced command lines land in their own paragraphs") explains why this test avoids _paragraph_containing and reads the whole file. That's the right call.

The for header in (...) subTest loop is correct: the three bold headers in safety.md match exactly. Assertions on "*only* autopilot merge path once the tier is enabled" and "operator enabling precondition" are precise enough to catch any prose rewording that softens the constraints.

plugin.json and CHANGELOG.md

Version bump 0.14.0 → 0.14.1 is appropriate for a docs/contract change with no behavioral shift. CHANGELOG entry matches the three-point summary in the PR description. Date is absent from ## [0.14.1], consistent with the existing ## [0.14.0] entry style — no new inconsistency introduced.

Summary

No correctness bugs, no security issues, no behavioral regressions (tier remains DISABLED). The three findings worth considering before or after merge:

Priority	Location	Finding
Low	SKILL.md:181	"are the single home" — grammatically awkward for a three-item list
Low	safety.md:202-210	"the review workflow" is unnamed — operator may not know which check context to require
Cosmetic	test_skill_contract.py:106	Implicit backtick-passthrough assertion; a comment would clarify intent

All are non-blocking. The PR achieves its stated goal — closing the three coherence gaps that were prerequisites for ever flipping the tier on — cleanly and verifiably.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3936ea57c9

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 2m 55s —— View job

---

PR Review

• Gather context and read PR changes
• Investigate Codex P1 finding: direct-gate path and tier flag coverage
• Review full diff vs base branch (commits 3936ea5 + 7f6e56d)
• Post findings

---

This PR now carries two commits. The second commit (7f6e56d) was pushed in response to the Codex P1 inline comment and correctly resolves it. Here is a complete review of both commits together.

Codex P1 — resolution verified

The P1 finding was valid: the Fan-out section's zero-blocker direct-gate path retained the flagless --merge --expected-head <snapshotted-head-sha> form, so an ENABLED tier would still merge clean PRs without the lane / approver / block-label / issue-link / human-veto criteria — the same fail-open that §3 was supposed to close.

Commit 7f6e56d sweeps both surfaces that were missed:

1. SKILL.md — Fan-out paragraph (lines 257–261)
The direct-gate path now reads: "but an enabled autopilot merge tier adds the tier flags (reference/safety.md), never the flagless base command." This mirrors the §3 fix exactly — both autopilot merge surfaces now point at safety.md rather than spelling any command inline. The wording is precise and consistent with §3.

2. reference/safety.md — Pinned-Command Degradation (lines 251–254)
The degraded-handoff paragraph correctly delegates to the "Autopilot Merge Tier: Enabled-Path Mechanics" section above rather than repeating the four-flag command, so there is one source of truth for the enabled-path command. The constraint ("so the operator's manual merge is held to the same tier criteria the blocked gate would have enforced") is the right framing — it prevents the degradation path from being a back door that bypasses the tier's gate.

3. test_skill_contract.py — test_direct_gate_path_wires_the_tier_when_enabled
The three assertions ("an enabled autopilot merge tier adds the tier flags", "reference/safety.md", "never the flagless base command") correctly pin the direct-gate paragraph against drift. The marker "A non-draft PR with zero blockers" is the right anchor for _paragraph_containing — it uniquely identifies the Fan-out paragraph.

4. Merge-surface sweep completeness
The remaining --merge occurrences in SKILL.md are correct as-is:

• SKILL.md:191 — generic readiness wrapper (read-only, no --merge in the executable form; the --merge appears only in the addendum)
• SKILL.md:413 — worker §7 push path. Worker tier has no merge tier by design; the inline command is correct and test_worker_push_path_pins_the_post_push_head_command pins it.

5. Line cap: SKILL.md is at exactly 499/500 — the commit's "net-zero" claim holds.

Remaining low-priority observations (unchanged from prior review)

These were identified in the previous review pass and are still present. None are blocking.

Priority	Location	Finding
Low	SKILL.md:181	"are the single home in reference/safety.md" — grammatically awkward for a three-item list; "are documented in the single home, reference/safety.md" reads more naturally
Low	safety.md:202–210	"the review workflow" is unnamed — an operator reading only safety.md may not know which check context to mark required in the branch ruleset
Cosmetic	test_skill_contract.py:117	assertIn("--autopilot-merge-tier", paragraph) passes through backtick delimiters implicitly; a comment clarifying that would help future readers

Summary

The Codex P1 finding is correctly resolved. No new correctness bugs, security issues, or behavioral regressions are introduced. Both autopilot merge surfaces (§3 worker-final-push and the Fan-out direct-gate) now consistently point at safety.md for the enabled-path command; the degraded handoff follows suit; and a new contract test pins the direct-gate invariant against drift. The tier remains DISABLED.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7f6e56d5cf

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8e780eae33

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ed71ed698d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 4m 16s —— View job

---

PR Review

• Gather context and read PR changes
• Analyze latest Codex P1 finding (direct-gate path missing approve step)
• Review current SKILL.md state (direct-gate paragraph)
• Review current reference/safety.md state
• Review test_skill_contract.py coverage
• Post complete findings

---

This review covers the full diff against origin/main at HEAD e09e4ae. Five commits, all prose/contract — no behavioral change to any script or gate. The tier still ships DISABLED.

Open P1: direct-gate path missing the review/approve step (unresolved)

The Codex P1 posted on commit ed71ed698d is valid and unresolved at HEAD. The latest commit (e09e4ae) only updated CHANGELOG.md.

The gap. The Fan-out paragraph (SKILL.md:252–261) routes zero-blocker PRs to "only a direct mode-appropriate source-control-babysit-merge gate check." Commit af8cfa1 correctly added the tier flags (via safety.md pointer), so an ENABLED config no longer sends these PRs through the flagless base path. However, "only a… gate check" still means: no review/approve step runs first. The gate's --autopilot-merge-tier criterion requires a distinct-bot approval on the live head (safety.md:185–186): "the gate only verifies one exists on the live head, it never creates it." Without the review/approve mechanic having run, no bot approval exists → gate refuses → PR falls to human list. The enabled tier makes the direct-gate path silently inoperable for zero-blocker autopilot PRs.

The tension with the tier paragraph. SKILL.md:181 says "per candidate PR autopilot runs a genuine review pass… then runs the pinned merge gate." This tier-level invariant would cover the direct-gate path too — but the Fan-out "only gate check" language directly contradicts it for that routing branch. An agent following the Fan-out instructions skips the review pass; an agent following the tier paragraph runs it. The contradiction is the defect.

safety.md compound gap. The "Enabled-path merge command" bullet (safety.md:171) opens with "After the worker's final push and a fresh post-push snapshot…" — it's scoped to the worker-path. A direct-gate PR has no worker push; this bullet doesn't speak to it, so an agent following only safety.md finds no enabled-path command for the zero-blocker case.

Concrete fix. The Fan-out paragraph's tier-enabled sentence (lines 258–259) needs to expand from "but an enabled autopilot merge tier adds the tier flags (reference/safety.md), never the flagless base command" to also direct the review/approve step first. Something like:

…but when the tier is enabled, first run the review/approve mechanic on the snapshotted head (safety.md → Second-account approve mechanic), then the tier-flagged gate — never the flagless base command.

And the safety.md "Enabled-path merge command" lead sentence should clarify it applies to both the worker-path and the direct-gate path (replacing "After the worker's final push" with "After the review/approve step and the pinned head to merge on"). A contract test asserting the Fan-out paragraph's review-mechanic reference (parallel to test_direct_gate_path_wires_the_tier_when_enabled) would pin this against drift.

---

Remaining low-priority observations (carried from prior reviews, still present)

Priority	Location	Finding
Low	SKILL.md:181	"are the single home in reference/safety.md" — grammatically awkward for a three-item list; "are documented in the single home, reference/safety.md" reads more naturally
Low	safety.md:205–220	"the review workflow" is unnamed — an operator reading only safety.md may not know which check context to mark required in the branch ruleset
Cosmetic	test_skill_contract.py:117	assertIn("--autopilot-merge-tier", paragraph) passes through backtick delimiters implicitly; a one-line comment clarifying that would help future readers

Summary

The P1 Codex finding from commit ed71ed698d is still open at HEAD e09e4ae — the latest commit only aligned the CHANGELOG. The direct-gate Fan-out paragraph and safety.md's "Enabled-path merge command" bullet together leave zero-blocker autopilot PRs with no review/approve direction for the enabled tier, making that routing branch silently blocked at the gate. Since this PR's stated purpose is to complete the flip precondition docs, this gap is blocking for the PR's stated goal before the tier can ever be enabled.