docs: codex-review gate + controller merge workflow

[SeanOC]

Documents the new merge workflow: codex-review is now a required status check on main (parity with underware-planner), set by the cross-model stuff-codex-reviewer agent and driven by the codex-review-gate-stuff controller order. merge-green-prs merges only when every reported check — including codex-review — is genuinely green on the head SHA.

Docs-only. Also serves as the first end-to-end test of the stuff gate.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
stuff	Ready	Preview, Comment	Jul 29, 2026 3:47am

[SeanOC]

Codex gate review — changes requested

One blocking contract/correctness issue on f1f796607bd20577772d8248e32b002469ee03e3:

• [P1] docs/ci.md:433-441 (also AGENTS.md:131-138) — the controller-only merge contract is not implemented. The new text says nobody enables GitHub native auto-merge and that the city controller merges only after both required and all reported checks pass. But .github/workflows/pr-automerge.yml:35-50 still runs gh pr merge --auto --squash for every non-draft PR. It ran on this PR, whose live GitHub state has an active auto-merge request. Native auto-merge can merge when branch-protection-required contexts pass without enforcing the controller broader all-reported-check gate.

  Smallest honest fix: remove or disable .github/workflows/pr-automerge.yml in this PR so merge-green-prs is the sole automatic merger, and clean up its stale auto-merge comments/references. If native auto-merge is intentionally retained, rewrite both new documentation sections to describe the dual mechanisms and remove the all-reported-check guarantee.

[SeanOC]

Codex gate review — changes requested

Reviewed exact head 023a4e644b1db0067a80f260ff0c2d6f9529d38b. One blocking finding:

• [P1] docs/ci.md:3-23, docs/ci.md:36-78, docs/ci.md:89, and docs/ci.md:275-280 — the canonical CI guide still presents deleted pr-automerge.yml as active. It links to the deleted file, says PR open arms native auto-merge, says GitHub merges after four checks, and retains the arm job, contradicting the new controller-only / five-check section at docs/ci.md:431-475. Present-tense native-auto-merge comments also remain at .github/workflows/ci.yml:3-7, .github/workflows/param-sweep.yml:20-27, and .github/workflows/pr-autoupdate.yml:1-10. This PR exists to document and enact the replacement, so leaving the main runbook contradictory and a link broken is a blocking documentation-contract defect.

  Smallest honest fix: remove the deleted workflow from the inventory and job matrix; replace the old lifecycle / four-check text with the controller plus codex-review five-check lifecycle; and update the cited workflow comments to explain always-reporting checks in terms of branch protection and the controller gate. No additional behavior change is needed.

[SeanOC]

Codex gate review — changes requested

Reviewed bead SHA 37bdfe2b3d33e27ba915d051e158057bbc49f2ea (the live PR has since advanced to 7d542e1, which requires a fresh review).

1. P1 — .gc/settings.json:2 / .gc/settings.json:44: remove checked-in agent harness state. This unrelated file enables project MCP servers, installs automatic gc hooks, and sets skipDangerousModePermissionPrompt=true, changing agent behavior and weakening a safety prompt for repository consumers. Smallest fix: delete .gc/settings.json and add .gc/ to .gitignore. The live successor appears to contain this fix, but it was not the bead SHA reviewed here.

2. P2 — docs/imported-model-opengrid-playbook.md:209: update the remaining stale native-auto-merge lifecycle instruction. This PR deletes pr-automerge.yml and makes the controller the sole merge path, so “Auto-merge lands the PR on green” is now false operational guidance. Smallest fix: say that merge-green-prs lands the PR after all reported and required checks, including codex-review, are green.

The codex-review failure is being set only on the exact reviewed SHA 37bdfe2b3d33e27ba915d051e158057bbc49f2ea.

[SeanOC]

Codex gate review — changes requested

Reviewed exact bead SHA 7d542e1309ce3ce11d79cf64d4bb662bf91f8710. One blocking finding remains on that SHA:

• [P2] docs/imported-model-opengrid-playbook.md:209 — the lifecycle still promises native auto-merge after this PR deletes that mechanism. The line says “Auto-merge lands the PR on green,” while this change removes .github/workflows/pr-automerge.yml and establishes merge-green-prs plus codex-review as the sole automatic path. That leaves the model-import playbook with false operational guidance and contradicts the new AGENTS.md / docs/ci.md contract.

  Smallest honest fix: say that merge-green-prs lands the PR only after every reported check, including codex-review, is green; retain the note that open branches are auto-updated.

The live PR advanced to aa327171252612a30ad3ac17e0852cfcd731017d during this review and that successor appears to contain this edit. It was not the bead SHA reviewed here, so failure is being set only on 7d542e1; the new head requires a fresh gate review.

[SeanOC]

Codex gate review — pass

Reviewed exact head aa327171252612a30ad3ac17e0852cfcd731017d against main. No blocking findings.

The competing native auto-merge workflow is removed, the PR has no active native auto-merge request, the documentation matches the live five-context branch protection and hardened controller behavior, and all reported CI checks are green.

One pre-existing, non-blocking follow-up is recorded on review bead pst-3gi: the historical committed pilot-pack copy of merge-green-prs.sh should eventually be synced with the already-hardened live controller.