cross-review

name	cross-review
description	Verify an implementer's diff with an INDEPENDENT, different-vendor sub-agent (diff plus contract only), LOCALLY and BEFORE the PR is opened; turn blocking issues into fix-tasks and loop until clean — only then does the implementer open its PR.

cross-review — independent verification

The implementer never signs off on its own work — a different model does, and review is a sub-agent that returns a structured report, not a transcript anyone needs to read through.

Cross-review runs LOCALLY, BEFORE the PR is created (config.yaml's Cross-Review Rule, layer 1). The implementer resolves every blocking finding first; only a clean review earns the PR. CodeRabbit then reviews the PR independently after creation (layer 2 — never pre-empted or duplicated here), and pr-shepherd owns everything after PR creation (layer 3).

Procedure

1. Verify the worktree is fully committed BEFORE taking the diff: sys_os_shell("git -C .worktrees/<task_id> status --porcelain") must return EMPTY. Staged, unstaged, or untracked files mean the branch diff would miss work — send the task back to the implementer to commit everything first; never review a dirty worktree. Then get the diff — sys_os_shell("git -C .worktrees/<task_id> diff main...HEAD"). (Only for a PR that already exists — e.g. re-reviewing a fix pushed to an open PR under pr-shepherd — use gh pr diff <pr> instead.)
2. Run the deterministic gates first — tests / lint / typecheck via sys_os_shell, executed FROM the task's worktree (e.g. sys_os_shell("cd .worktrees/<task_id> && <test cmd>")) so they validate the diff under review, never buhhdy's own checkout — gates run anywhere else are false-green evidence. If red, re-dispatch the implementer to drive it green first; don't involve the reviewer yet.
3. Dispatch a DIFFERENT-vendor sub-agent as reviewer (Claude built it → codex, gemini-*, or opencode; Codex built it → claude_code, gemini-*, or opencode; a gemini-* worker built it → claude_code, codex, or opencode; opencode built it → claude_code, codex, or gemini-*. The three gemini-* workers are ONE vendor and never review each other; gemini-* defaults to gemini-standard, or gemini-complex for large/multimodal diffs). Use a task-based title such as review-auth-refactor, never the raw vendor name: sys_session_send(agent="claude_code"|"codex"|"gemini-standard"|"gemini-complex"|"opencode", title="review-<task_slug>", args={purpose: "review", input: "<the diff> + <the acceptance contract>. Review ONLY against the contract. Report blocking / non-blocking / suggestions. Do not edit code."}). Give it the diff as text — do NOT point it at the implementer's worktree. Fetch the diff and emit the sys_session_send call in the SAME turn you decide to review — never end a turn having only announced "I'll load cross-review and fetch the diff" with no tool call (that dropped turn stalls the run; nothing dispatches and no inbox wake arrives). Once the reviewer dispatch is in flight, end your turn; collect the inbox-delivered structured report with sys_read_inbox when it returns. Use sys_session_get_history only to debug an empty or unclear review result.
4. The reviewer SURFACES issues; it does not fix them.
5. For each blocking issue: add a fix-task to the registry scoped to the same worktree, and send the concrete fixes back to the SAME implementer conversation via sys_session_send — reuse the original implementer's agent + title (or address it by session_id) with purpose: "implement", so the worker keeps its worktree/branch context. A new title would spawn a fresh worker with no memory of the task. Then loop to step 1.
6. When gates are green AND there are zero blocking issues, the diff passes review — NOW the implementer opens its PR (body carrying Closes #N for its tracker issue and the test-run evidence from step 2: commands run + results; verify both are present before counting it deliverable). Record the PR URL in the registry and hand the PR to pr-shepherd. buhhdy does NOT merge it.
7. If the contract can't be satisfied within the escalation rule's budget (two fix attempts by the original implementer — see core-workflows' shared notes), stop and escalate to the human with specifics, and WAIT.

Notes

• Cross-review requires a reviewer from a DIFFERENT vendor than the implementer, so it needs at least two AVAILABLE workers (per buhhdy's roster preflight). If only one worker — or only one vendor that can review this implementer's PR — is available on the machine, you CANNOT run independent cross-vendor review: don't dispatch a reviewer that can't boot, say so explicitly, and pull in the human at the plan gate.
• Give the reviewer ONLY the diff + contract — never the implementer's transcript or worktree. The cross-vendor independence is the whole point.
• Review is a coding sub-agent (claude_code/codex/gemini-*/opencode) dispatched with purpose: "review" — a DIFFERENT vendor from the one that built the diff. It reports issues and never edits; only the implementer opens a PR, so a stray reviewer edit never reaches the deliverable.
• Non-blocking issues / suggestions go in the registry as follow-ups; they don't block the PR.