RonanCodes/skills/code-review-gate

Code Review Gate

Make the [[council-of-llms|Council of LLMs]] run automatically before a push, and decide per-repo whether it runs at all. This is the "code review is the new bottleneck" idea from Farhan Thawar's talk turned into a real gate: the local pre-push hook is already the CI gate in these repos (see /ro:ship), so the review belongs right there.

Two design rules, both from the user:

1. Opt-in per project. A repo records its decision in a config file, so the gate is never a surprise and the team can share the setting.
2. First-run check. The first time the council is asked to run in a project with no recorded decision, ask the human once (on / ask-each-push / off) and write the file. Never silently start blocking pushes.

The config (resolver, like ro ci)

Resolution order, later wins:

1. built-in default: { prePushReview: "ask", blockOn: "critical", level: "strict", lenses: ["all"] }
2. ~/.claude/code-review-policy.json (global personal default)
3. .ro-code-review.json (committed: the team-shared decision)
4. .ro-code-review.local.json (gitignored: personal override for this checkout)

// .ro-code-review.json
{
  "prePushReview": "on",          // "on" = run + block; "ask" = first-run prompt then notice-only; "off" = no-op
  "blockOn": "critical",          // "critical" | "critical+major" | "none" (none = report only, never block)
  "level": "standard",            // "critical" | "standard" | "strict" (default strict: full council incl. nitpicks)
  "lenses": ["all"],              // or ["security","architecture",...]; an explicit list overrides the level's set
  "ignore": ["comment-style"],    // finding classes never reported in this repo (suppression stays visible in the report)
  "scopes": {                      // per-class surface limits instead of full on/off
    "em-dash": "user-facing"      // enforced on release notes / site copy / docs; ignored in comments, commits, PR bodies
  },
  "checklist": [                   // repo-specific checks every council run verifies
    "Every new MCP tool ships with an HTTP shim, a docs-registry section, and a Bruno entry in the same PR"
  ],
  "models": {                      // optional: different model per lens (the ensemble-table idea)
    "security-reviewer": "opus",
    "simplicity-reviewer": "haiku"
  }
}

level, ignore, scopes, and checklist are read by the council, not the hook; their semantics (which lenses each level runs, the class tiers, the user-facing scope, the suppression footer) live in /ro:council-review under "Levels (how hard the council bites)". The gate just resolves and passes them through: the hook's claude -p call inherits the repo's resolved level, so a level: "critical" repo gets a showstopper-only pre-push review automatically.

prePushReview values:

• on — run the council on the pushed range; block the push when the verdict crosses blockOn.
• ask — the unconfigured state. The hook does NOT block; it prints a one-time notice telling the user to run /ro:code-review-gate to choose on/off. This is the "first-run check".
• off — the hook is a no-op (exits 0 immediately).

Subcommands

install (default)

1. Detect the hook system: prefer .husky/pre-push (the convention in these repos); fall back to .git/hooks/pre-push.
2. First-run prompt (AskUserQuestion) if no .ro-code-review*.json exists:

   "Run the code-review council automatically before every push in this repo?"

   • On, block on critical (recommended) — full gate.
   • On, report only — runs the council, writes a report, never blocks (blockOn: none).
   • Ask me later — write prePushReview: "ask" (notice-only until decided).
   • Off — don't run on push. Also ask: commit the decision (.ro-code-review.json, shared) or keep it personal (.ro-code-review.local.json, gitignored)?

3. Write the chosen config file. If personal, ensure .ro-code-review.local.json is in .gitignore.
4. Append the gate call to the pre-push hook (idempotent: skip if already present), AFTER the existing local-CI gate so review runs on code that already builds/lints/tests:

   # --- ro code-review gate (managed by /ro:code-review-gate) ---
   bash "$(git rev-parse --show-toplevel)/.ro/pre-push-review.sh" "$@" </dev/null || exit 1
   

5. Copy scripts/pre-push-review.sh into the repo at .ro/pre-push-review.sh (gitignore .ro/ if not already) and chmod +x. Pinning a copy in-repo keeps the hook working without the plugin on PATH for the script itself; it still needs the claude CLI to run the council.
6. Print what changed and how to disable (/ro:code-review-gate disable).

status

Show the resolved config (which file won), whether the hook is installed, and the last report under .code-review/.

enable / disable

Flip prePushReview to on / off in the nearest config file (create .ro-code-review.local.json if none). --block-on and --scope set the other keys.

run

Run the gate logic now against the working tree (a dry run of what the hook would do), without pushing. Useful to test the setup.

How the hook behaves (the loop)

scripts/pre-push-review.sh (installed at .ro/pre-push-review.sh):

1. Resolve config. If prePushReview is off → exit 0. If ask → print the one-time notice and exit 0 (never block an undecided repo).
2. Read the pushed refs from stdin (git's pre-push protocol: <local ref> <local sha> <remote ref> <remote sha>) and compute the range: remote_sha..local_sha, or main...local_sha for a brand-new branch (all-zero remote sha).
3. If the claude CLI is not on PATH, print a notice and exit 0 (never hard-fail a push over missing tooling; the gate is best-effort, the human still owns the push).
4. Run the council headlessly:

   claude -p "/ro:council-review --pre-push --block-on <blockOn> <range>"
   

   The council writes .code-review/council-<ts>.md and signals the verdict via exit code (0 = clean / below threshold, 1 = blocked).
5. On block: print the report path and the next step, then exit 1 (push aborted):

   Council requested changes (N critical). Report: .code-review/council-<ts>.md Fix and re-push, or run /ro:council-review --fix to dispatch a dev agent, then push again.

The report → dev-agent loop is deliberately NOT run from inside the git hook (a hook is a blocking, non-interactive git operation, and the agent that wrote the code is usually not alive at push time). Instead:

• Interactively, /ro:council-review --fix routes the report to the author agent if it is still live in the session, otherwise spawns a fresh dev agent, fixes, and re-reviews.
• Inside an autonomous loop (/ro:ralph, /ro:planner-worker, /ro:night-shift), the loop already owns the worker, so it feeds the council report straight back to that worker and re-runs the council before opening the PR.

This keeps the honest boundary: the hook gates; the fix loop routes.

Notes

• Keep blockOn: critical by default. A pre-push council can take minutes; blocking on every minor finding makes pushes painful and trains people to --no-verify (which the way-of-working lens flags anyway).
• The gate composes with /ro:ship: local CI gate first (build/lint/types/test), then the council, then push.
• To review without the gate, just call /ro:council-review directly.