Reviewing a contract before it leaves the machine is now the default

[hermanngeorge15]

Committed to the repo, so anyone who clones it gets the hook. Not a personal config.

File	Role
.claude/settings.json	the wiring
.claude/hooks/opencode-review.sh	the script, chmod +x
.claude/hooks/opencode-review.test.sh	16 cases, gh / git / opencode / the reviewer all stubbed — no network, no tokens
.claude/hooks/README.md	why, and how to install it elsewhere

What it does

On git push and gh pr create, the measurement contracts changed on the branch go to tools/opencode-review.sh — the independent critic, a different model family — and findings land in findings/opencode/.

Three globs, listed at the top of the script: benchmark/rubrics/*.yaml, templates/*.yaml, experiments/*.md. A phase README changing does not need an adversarial reviewer; a rubric leaving the machine does.

Why

In one session the critic caught a "guaranteed null" that nothing enforced, and an experiment record asserting a property a reader had to go and verify by hand. Both were written minutes after landing a Layer 2 control against that exact mistake.

A review you have to remember to run is Layer 3. Push is the right trigger because it is the moment the artifact stops being yours alone.

Nothing hand-rolled that the schema provides

{ "type": "command", "command": ".claude/hooks/opencode-review.sh",
  "if": "Bash(git push:*)", "async": true, "timeout": 900 }

if uses permission-rule syntax, so the hook is not spawned at all for a non-matching command — no case statement filtering inside the script. async: true keeps it off the critical path, so the push has already completed before the reviewer starts — no ( … ) & self-detach. The script still re-checks the command, because its test runs it directly.

It cannot break a push

Exits 0 on every path: missing opencode, a reviewer that exits 1, malformed stdin, no git, no merge-base. A reviewer that can break git push gets removed within a day, and then nothing is reviewed at all.

The test

ok    push, no changes                             exit 0, 0 reviewer call(s)
ok    git status is not a push                     exit 0, 0 reviewer call(s)
ok    git pushd is not a push                      exit 0, 0 reviewer call(s)
ok    gh pr view is not create                     exit 0, 0 reviewer call(s)
ok    push with a changed rubric                   exit 0, 1 reviewer call(s)
ok    reviewer argv                                argv carries the artifact
ok    README change is not reviewable              exit 0, 0 reviewer call(s)
ok    reviewer exits 1                             exit 0, 1 reviewer call(s)
ok    opencode not installed                       exit 0, 0 reviewer call(s)
ok    empty stdin / not JSON / no command / wrong shape
opencode-review.test: all 16 cases behaved as specified.

Half the cases assert the reviewer was NOT called. A hook that silently does nothing is worse than no hook, and that is the failure mode this repo keeps meeting — --dir silently selecting the default agent and exiting 0, a suite printing "all 6 cases" while eleven ran.

One case only passes because of a deliberately minimal PATH containing no opencode. Removing the stub was not enough: the developer's real binary was still on $PATH, command -v found it, and the case passed for the wrong reason. Caught while writing the test, which is the argument for writing it.

Runs in CI, along with shellcheck over .claude/hooks.

Scope

Project .claude/settings.json — committed, team-wide. LAB_REVIEW_HOOK=0 turns it off for one command; LAB_REVIEW_RUNS overrides -n (default 2, because a single run at temperature 0 is a lower bound).

After merging, open /hooks once or restart — the settings watcher only watches directories that had a settings file when the session started, so a brand-new .claude/settings.json is not picked up mid-session.

🤖 Generated with Claude Code