Add scripts/codex-review.sh (Codex reviewer harness) + document the in-session review loop

[yihanzhu]

Goal / problem

The reviewer is Codex (cross-vendor), but there's no encapsulated harness — posting Codex's review to a PR has been done ad-hoc. Build a thin, verbatim reviewer harness script, and reconcile the docs (which still imply a hand-written rubric is used) to match how the reviewer actually works.

Decision context (see issue comments): we use Codex's built-in review (codex exec review), not a custom rubric prompt (the --base flag can't take a prompt). The script wraps that command and posts Codex's output verbatim so a Claude session never edits/blends the review (preserves cross-vendor purity).

Acceptance criteria

1. New scripts/codex-review.sh — the reviewer harness:

• Usage scripts/codex-review.sh <owner>/<repo> <PR#>; print usage + exit non-zero if args missing.
• Derive the PR's base branch (gh pr view <PR#> --json baseRefName), gh pr checkout <PR#>, then run codex exec review --base <base> -o <tmpfile> (read-only sandbox is the default — do NOT pass --dangerously-bypass-approvals-and-sandbox). <tmpfile> is a temp file under /tmp (or mktemp), NOT committed.
• Post the captured review to the PR verbatim: gh pr comment <PR#> --body-file <tmpfile>, prefixed with a short header marking it the Codex cross-vendor reviewer.
• Clean up the temp file. The script only writes a PR comment — never edits files, pushes, or merges (read-only reviewer).
• #!/usr/bin/env bash, set -euo pipefail, shellcheck-clean, executable. Optional -m <model> passthrough — do NOT hardcode a model name.

2. Repurpose reviewer/codex-review.md (keep the file — CI structure check requires it): from a paste-able prompt into documentation of the real mechanism — reviewer = Codex via scripts/codex-review.sh (wraps codex exec review), read-only, comments-only, output posted verbatim. Note the two alternatives: the Codex GitHub integration (autonomous/hands-off upgrade — Codex posts on PR events itself) and codex-plugin-cc (interactive in Claude Code).

3. Document the in-session loop (in reviewer/codex-review.md): Faber spawns coder subagent → opens PR → Faber runs scripts/codex-review.sh (script posts Codex's verdict verbatim) → Faber reads it → pass = human merge gate; not pass = spawn coder (fix mode) → re-run script → repeat → ~3-round cap escalates to human. Note this is SYNCHRONOUS (runs while a Faber session drives it); the GitHub integration is the autonomous upgrade.

4. README team table — Reviewer row: "Codex via `scripts/codex-review.sh` (in-session) — or Codex GitHub integration (autonomous)".

5. RESTORE.md — reviewer recreate step references `scripts/codex-review.sh` + the GitHub-integration option (not "paste reviewer/codex-review.md").

6. Invariants preserved everywhere: cross-vendor (coder=Claude, reviewer=Codex), reviewer read-only / comments-only / never the author, verbatim posting.

Likely files

• scripts/codex-review.sh (new)
• reviewer/codex-review.md (repurpose)
• README.md (team table + Layout)
• RESTORE.md (reviewer step)

Test expectations

• CI green: codex-review.sh shellcheck-clean; structure check intact; no dangling references.
• CI does NOT run the script live (needs Codex auth + a real PR) — static check only.

Out of scope

• Setting up the Codex GitHub integration itself (document/mention only).
• The autonomous trigger layer; changing the coder or Faber.
• One concern: the reviewer harness + its docs.

[yihanzhu]

Faber — reviewer command nailed down (from Codex CLI v0.129.0 help). The docs in this issue must specify exactly this:

codex exec review --base <base-branch> -o <output-file> [--title "<PR title>"]

• Use codex exec review (not bare codex review) — it exposes -o/--model/--json for automation.
• --base main → review the PR branch's diff vs main.
• -o <file> → capture the final review to a file (then post that to the PR) — avoids the noisy exec trace on stdout.
• Runs read-only by default (sandbox: read-only, approval: never). DO NOT document --dangerously-bypass-approvals-and-sandbox — that's the opposite of a read-only reviewer.
• -m <model> is optional (defaults to gpt-5.5) — do not hardcode a model name in the docs; mention it as an optional override only.
• Can't combine --base with a custom prompt; we rely on Codex's built-in review (the whole point of this issue).

[yihanzhu]

Faber — clarification on output handling. The Codex CLI does NOT post to GitHub; it prints the review locally. So the documented flow is:

codex exec review --base main -o /tmp/codex-review.md   # capture ONLY the final review
gh pr comment <PR#> --body-file /tmp/codex-review.md     # post it as the PR comment

• The -o file is a transient temp file in /tmp — NOT committed, NOT a repo artifact. It exists only to grab the clean final review (avoiding the noisy exec trace on stdout) so it can be posted.
• The PR comment is the actual reviewer output. Docs should describe it that way, not as "keeping a file."

[yihanzhu]

Faber — temp-file cleanup precision. The capture file must be cleaned up robustly:

tmp="$(mktemp)"; trap 'rm -f "$tmp"' EXIT
codex exec review --base "$base" -o "$tmp"
gh pr comment "$pr" --body-file "$tmp"

• Use mktemp (system temp dir) + trap '... EXIT' so the file is removed even if codex/gh fails mid-run — not a bare rm at the end.
• Never write the temp file inside the repo (so it can't be accidentally committed).
• The posted PR comment is the durable record; the temp file is disposable.