Gate a PR through merge-on-green

Run the review gates on one existing PR and merge it only after every required gate is green. This is the natural-language entry point for Codex and the same workflow as the Claude Code /gate command.

Plugin paths

The role briefs and scripts below live in this plugin, not necessarily in the target repository. Resolve these paths from this skill file before executing or reading them:

• ../../agents/orchestration-code-reviewer.md
• ../../agents/orchestration-design-reviewer.md
• ../../agents/orchestration-implementer.md
• ../../agents/orchestration-security-reviewer.md
• ../../scripts/context_pipeline.py
• ../../scripts/api_agent.py
• ../../scripts/merge-guard.sh
• ../../scripts/merge-on-green.sh
• ../../scripts/orchestration-engine.py
• ../../scripts/review-ledger.py
• ../../scripts/run-gates.sh
• ../../scripts/run-verification.sh
• ../../scripts/version_policy.py

Execute scripts by absolute path while keeping the target repository as the working directory.

Procedure

0. Validate the active runtime against repository policy before opening or resuming a review: version_policy.py --plugin-root <resolved-plugin-root> --config .orchestration/config.yaml. Stop fail-closed unless it reports status: compatible. review-ledger.py permit-review and merge-guard.sh repeat this check mechanically, so an older runtime cannot mint review authority or record/assert merge evidence.

Before each code-reviewer or security-reviewer pass, resolve its route with scripts/context_pipeline.py route --config .orchestration/config.yaml --role <role>. Desktop routes use fresh native agents. API routes build their request with context_pipeline.py payload --config ... --role <role> and use the api_agent.py run --request - adapter with the ticket and a stable run id. Give API reviewers exact-head CI results with payload --ci-evidence <gh api "repos/{owner}/{repo}/commits/<full-exact-head>/check-runs" output> --review-head <full-exact-head> (or --fetch-ci-evidence --review-head ...) so a CI-only check can be ci_verified instead of not_run. First issue a phase permit from the durable ledger with review-ledger.py permit-review <pr> --role <role> --head <full-exact-head>; pass it to run --review-pr <pr> --review-authorization <token>. The ledger issues it only while that gate is the permitted next phase, and it cannot be reused. This is sequencing, not human authentication. Desktop fallback is allowed only before provider acknowledgement; submitted, timed-out, or uncertain work must be reconciled instead of duplicated. If permit-review reports a started review, reconcile that run with api_agent.py reconcile --run-id <run>, which also cancels its permit; if the permit is still started afterwards, run review-ledger.py cancel-permit <pr> --phase-permit <token> --reason <text>. Either way the review re-runs under a new permit; no PASS is ever inferred. For a native desktop reviewer, write its final structured JSON first, then run review-ledger.py complete-review <pr> --role <role> --phase-permit <token> --result <file>. complete-review is for desktop reviewers only: API execution creates the same completion receipt after successful provider output, so an API run goes straight to record with its token. Repeating complete-review with the identical result returns the existing receipt with already_completed: true; a different result is refused. complete-review refuses a permit an API run already started; recover it with api_agent.py reconcile instead.

permit-review binds the local git rev-parse HEAD, because reviewers and receipts read the local tree. When the current checkout is not at the exact PR head, do not move it: git worktree add --detach <review-path> <full-exact-head>, run permit-review, the reviewers, complete-review, and record from <review-path>, then git worktree remove <review-path>. Linked worktrees resolve the same shared review ledger and canonical config.

1. Read .orchestration/config.yaml and run orchestration-engine.py validate-config. For schema_version: 2, use orchestration-engine.py adapter-plan --host codex <transition> for the configured gate or merge transition; branch roles, evidence, approvals, CI categories, and adapters come from that plan. For legacy configs, continue with the existing review gates below. Keep the configured worker_trust_profile fixed for every reviewer. It governs only worker-versus-host assumptions and never relaxes application, tenant, client, ticket-input, or provider security.
2. Open the durable review ledger and build this round's brief: review-ledger.py open <pr> then review-ledger.py brief <pr>. The failure ledger lives on disk, not in this conversation -- it survives compaction, normalizes component keys so a repeated defect actually accumulates strikes, and decides when the loop stops. Paste the brief output verbatim into every reviewer pass this round. A round is the ledger's shared review generation for one exact head, never the arrival order of individual gate responses. It carries the round number, the scope mode, the round-aware uncertainty rule, and the open component keys to reuse. Without it a reviewer assumes round 1 and reviews with full blocking authority. If the PR head moved for a non-findings change after the current generation completed, first run review-ledger.py rebind-generation <pr> --head <full-exact-head> --reason "<auditable reason>". This starts a fresh review generation while preserving history, findings, strikes, and repair-cycle accounting. It is valid only when the prior generation is complete and has no open blocker or outstanding permit. Never use it instead of record-repair for a findings repair.
3. Launch the code-review gate and any required security-review gate concurrently against the same exact PR head, raw diff, and round brief. Do not let one reviewer's findings contaminate the other's independent pass. Run code review as a fresh pass. If the host supports subagents, launch one with orchestration-code-reviewer.md; otherwise apply that brief yourself without using the implementer's reasoning as evidence. Generate and pass the raw unified base-to-head git diff as the default and authoritative code input, alongside only the ticket, configured rules docs, stable repository map, and round brief. Do not pass a full-codebase index; additional source is allowed only for a named verification or regression. The reviewer must finish the full checklist, diff, and adversarial matrix even after finding a blocker, then return only concise structured review JSON. Explanations belong only to findings; each finding has a stable component key. A blocker must name a concrete failing input/precondition, production path, wrong outcome/impact, and reproduction or exact falsifying assertion under the selected profile. Do not let a reviewer expand the PR into new host infrastructure based only on a stronger, unconfigured threat model.
4. Before launching the pair, read the authoritative PR headRefName and baseRefName from GitHub, save the raw base-to-head unified diff to a file, and run orchestration-engine.py security-gate --source-branch <headRefName> --target-branch <baseRefName> --diff-file <raw-diff-file>. This shared decision evaluates security_required_when, security_required_source_branches, and security_required_target_branches. Save its JSON output and bind it to the generation with review-ledger.py record-security-gate <pr> --head <full-exact-head> --decision <security-gate-output.json>. The ledger requires every configured gates: entry; a configured security-review is waived only by a recorded required: false decision for this generation's exact head, and stays required when none is recorded. Record a new decision after every record-repair or rebind-generation. If required is true, run a fresh security-review pass using orchestration-security-reviewer.md with the same raw unified diff and diff-isolated context. If it is false, record the decision and skip. If metadata, diff capture, configuration validation, or the decision command fails, stop fail-closed; never infer that security is optional.
5. Wait for both launched reviewers, then record every completed gate through the ledger, blocking and advisory findings alike: review-ledger.py record <pr> --gate code-review --result .orchestration/.review-results/code-review.json --head <exact-sha> --phase-permit <token> (plus --ci-evidence <exact-head file> when it has a ci_verified check). The validated JSON carries disposition, severity, regression, and explanation. Both concurrent results retain the same generation and scope mode regardless of which is recorded first. A partial generation cannot return gates-clear; every issued gate must be recorded. The ledger increments strikes, auto-resolves components this gate no longer reports, demotes out-of-scope new findings in a frozen round, and returns next_action. Its effective_verdict governs, not the claimed one.
6. Act on next_action. Never merge while a blocking component is open.
   • review -- run review-ledger.py repair-brief <pr> once after all gates record. Give that single deduplicated brief to one fresh implementer on the same branch. The implementer must map every stable finding ID to root cause, planned change, affected boundaries, objective closure condition, and named verification before editing. After editing it writes the strict repair JSON named by the brief; record it with review-ledger.py record-repair <pr> --report <file>; it stores the full commit id git resolves from the report head. Record that head's record-security-gate decision. A claimed closure is not proof. Re-run code and required security reviewers concurrently against that exact repaired head, record both with record ... --head <exact-sha>, then call review-ledger.py complete-repair-review <pr>. Advisory findings go to the PR body and never widen the repair.
   • redesign -- an agreed finding survived a completed repair. Run orchestration-design-reviewer.md scoped to the named component against the root design and a revised adversarial matrix; no further implementation starts until it returns VERDICT: PASS, then record review-ledger.py redesign <pr> --key <key> --verdict PASS.
   • escalate-human -- the repair cap is spent with blocking findings still open. STOP: do not merge and do not run another round. Give the user review-ledger.py handoff <pr> with the PR link. A component that survives two evidenced repairs needs human diagnosis, not another autonomous patch.
   • gates-clear -- necessary, not sufficient. Confirm the security gate actually ran if the diff triggers it, then continue.
7. For each configured verification: entry whose when: applies to the target, run run-verification.sh <name>. A GREEN result file is required; RED or a missing result file blocks the merge.
8. Confirm every required configured target CI check is green.
9. Carry the ledger's advisory findings into the PR body as follow-ups, then record the all-green marker with merge-guard.sh --record-green <pr> [result_file], then merge with merge-on-green.sh <pr> <branch> all-green <verify_path>. The merge script itself revalidates the active plugin version, exact PR head branch/sha, exact target base branch/sha, and marker freshness; never treat host hook registration as required evidence.

Report each gate verdict, the round number and scope mode, any blocking findings, the advisory findings carried to the PR body, verification result paths, CI status, and the merge result. CI-green alone is not the gate; the independent verdicts are mandatory.