| name | sjulia-lead-review-merge |
| description | Use when acting as the lead/orchestrator (管理者) for parallel implementation agents in this repo: an agent has opened a PR and reported completion, and you must review its diff, resolve merge conflicts with main, run the local gates (GitHub Actions is disabled — local checks are the ONLY gates), and drive the PR to a regular merge. Also applies when integrating several agent PRs in sequence. |
Lead review & merge of an implementation-agent PR
You are the merge gate. GitHub Actions is intentionally disabled on this repo
(budget decision, 2026-07-06 — zero status checks on every PR), so nothing is
verified unless YOU verify it locally. Never merge on the strength of the
agent's report alone.
Inputs
- The PR number/branch and the linked Issue(s).
- The agent's completion report (claims to verify, not facts).
0. Verify from a dedicated lead worktree — never the main checkout
Do ALL lead verification (merges, builds, test runs) in your own worktree:
git worktree add .claude/worktrees/lead-review origin/main
A misbehaving agent can run git checkout in the shared main checkout and
yank your branch mid-verification (it happened: results suddenly "regressed"
because the tree under the running check had silently moved to main). When a
result looks impossible, git reflog the checkout you ran it in before
debugging the code. Share the warm build cache across worktrees with
CARGO_TARGET_DIR=<main-checkout>/target — but never run two cargo
invocations against it concurrently.
1. Inspect the diff without checking out the agent's branch
The authoring agent's worktree usually still holds the branch checked out —
git checkout <branch> and local git branch -D will fail. Review from
origin instead:
git fetch origin <branch>
git diff --stat main...origin/<branch>
git diff main...origin/<branch> -- <files-of-interest>
git show origin/<branch>:<new-file>
Review checklist:
- Scope: every changed file is explained by the Issue. No unrelated
resets, no
target/, editor droppings, or another agent's files.
- Hard rules (CLAUDE.md "Hard Rules — Quick Check"): workarounds carry an
(Issue #NNNN) comment + WORKAROUNDS.md entry; fixtures end with true,
are registered in manifest.toml, category-prefixed; sample-body edits
applied to ALL surfaces (bash scripts/check_sample_body_consistency.sh);
STATUS.md/DONE.md additions go UNDER the existing daily header as ###
subsections, not as a new top block.
- Claims vs evidence: pick the PR's central claim and reproduce it
locally (run the new script, the new fixture, the measured command). For a
new/changed audit script, ALWAYS run a negative test: inject a genuine
violation → the audit must FAIL naming the cause → restore → green again.
- Report red flags: "should work", missing exact test counts, a full
suite the agent "ran" but reports no numbers for. Ask the agent (or rerun)
before merging.
Pin the head SHA before final verification. Agents may push more commits
AFTER reporting completion (a late bug-fix commit invalidated one verified
suite run). Re-fetch, record the PR head SHA, and get the agent's explicit
"branch final at " confirmation before the expensive final gates.
2. Resolve conflicts on a review branch
gh pr view <N> --json mergeable,mergeStateStatus
git checkout -b review/<issue>-merge origin/<branch>
git merge origin/main
Union-resolution rules for the common both-append conflicts:
- DONE.md / STATUS.md: keep BOTH
### ... (Issue #NNNN) subsections
under the ONE shared daily ## 最新対応 (...) header (Issue #3760 policy).
- fixtures manifest.toml: keep BOTH
[[tests]] blocks and re-count the
headers afterwards — a union-resolution once dropped a [[tests]] line and
silently deregistered an entire category (#9378 bigfloat incident).
- ci.yml audit lists: keep both shellcheck lines / run steps.
- Never discard a hunk silently; if you must drop something, say why in the
merge commit body.
- After editing: verify no markers remain with
! grep -rn '<<<<<<<' <files>.
NEVER use grep -c as a success check inside a && chain — it exits 1 on
zero matches, silently aborting the rest of the chain (a merge commit once
went un-committed and un-pushed this way while later commands "succeeded").
- Code files that auto-merge cleanly can still be wrong: two branches
appending adjacent code stack both versions (a shadowed
let binding), and
a union-resolved struct-field hunk can splice a field initializer into the
middle of an unrelated method. Always cargo check immediately after a
cross-PR resolution and treat any unused_variable warning as a merge
artifact until proven otherwise.
Batching sibling VM PRs. Two VM-touching PRs pending at once → build ONE
review branch (main + A + B), fix cross-PR integration there, run ONE full
suite. Push the combined branch to PR A's head and merge A — GitHub then
auto-marks PR B merged (its commits are contained), and both Fixes # links
close. The de-facto last merge owns the suite either way.
3. Verify on the merged tree (the local gate)
Use the guarded wrapper for the final run (Issue #9644 — a clippy
warning once landed on main because the final gate wasn't rerun after
main advanced during a parallel merge window):
bash scripts/premerge_gate.sh
bash scripts/premerge_gate.sh --merge-main --nextest 'fixture_tests <category>::'
bash scripts/premerge_gate.sh --full-suite
It fetches origin/main, refuses to run on a branch that doesn't contain
the exact current origin/main SHA (--merge-main merges it in first),
runs the gates, then re-fetches: if origin/main moved DURING the gates it
fails — that verification is stale, merge the new main and rerun. On green
it prints the certified HEAD SHA for a pinned merge.
Scale to the diff — these run on the review branch AFTER the merge commit:
- Affected
scripts/check_*.sh / audit_*.sh, plus the negative test for
any new audit.
- Rust changes:
cargo fmt --check on touched files +
timeout 1800 cargo clippy --all-targets -- -D warnings.
- Narrow changes: the relevant category —
timeout 1800 cargo nextest run --release --test fixture_tests <category>::
- VM / compiler / dispatch / inference / test-harness changes, and the LAST
merge of a parallel batch: FULL suite —
timeout 1800 cargo nextest run --release --no-fail-fast (never | tail).
- AoT-touching diffs:
bash scripts/test_aot.sh.
4. Land it
Implementation agents never mark their PRs ready and never merge them. Require
the PR to remain draft throughout review; lead certification is the only
authority for the ready transition (Issue #11056).
git push origin HEAD:<branch>
gh pr view <N> --json mergeable,mergeStateStatus
bash scripts/premerge_gate.sh --pr <N>
-
--pr <N> checks that the PR is OPEN, draft, targets the configured base,
and points at local HEAD both before and after the gates. It marks ready only
after the final freshness check, publishes the server-required
sjulia/guarded-certification status, then pins the regular merge to that
SHA. A late push or manual ready action makes the gate fail loudly, while
the strict GitHub ruleset rejects stale or uncertified heads (Issue #11087).
-
Do not fall back to a direct or auto merge when guarded certification fails.
On "Base branch was modified" / "not mergeable", keep or return the PR to
draft, fetch and merge origin/main into the review branch, push, then rerun
the full guarded command; GitHub state recompute can lag a few seconds.
-
--delete-branch may fail with "used by worktree" when the agent's
worktree still holds the branch — harmless; skip local deletion and let
worktree cleanup handle it.
-
Other sessions merge to main concurrently: a CLEAN status can flip to
CONFLICTING between your check and the merge call. Loop: fetch → merge
origin/main into the review branch → resolve → push → retry. And always
diff against a freshly fetched origin/main, not the local main ref —
a stale local main makes a 8-file PR look like a 125-file one.
-
Machine discipline across parallel agents: only ONE full suite runs on the
machine at a time (the lead's); tell implementation agents to skip their
own full-suite runs, and to never kill processes by name pattern (pkill)
— an agent's broad kill once SIGTERM'd the lead's verification suite.
5. After the merge
git checkout main && git pull
git branch -D review/<issue>-merge
gh issue view <issue> --json state
- Unblock dependent work (wave-2 tasks waiting on this merge).
- Cross-PR integration: when sibling agent PRs land in sequence, re-run
the checks that couple them on main (e.g. a new
check_*.sh from one PR
vs an audit-coverage framework from another; sample-body audit vs sample
migrations). The last merger owns the full-suite run on main.
- Feed fixes back: if the review found defects, prefer
SendMessage to the
authoring agent (it has the context) with a concrete fix list and re-review
the delta. Fix directly only trivial nits and conflict resolutions — and
add commits on top; never rewrite the agent's history.
