Claude Code pre-commit hook stamps provenance but doesn't run cargo fmt --check → AI commits pass locally, fail CI Format

[avrabe]

Friction (hit repeatedly while dogfooding)

AI-agent PRs (e.g. #437) keep failing the Format and Clippy CI jobs on
the first push, even though the change is otherwise correct (Test/Playwright
green). Two compounding reasons:

1. The Claude Code pre-commit hook only stamps provenance. .claude/settings.json's
   PreToolUse/pre-commit command is rivet stamp all --created-by ai-assisted
   — it does not run cargo fmt --check or clippy. So an agent's commit
   passes the local hook and only discovers fmt/clippy drift after pushing and
   waiting on CI.
2. The pre-commit framework that does cover this isn't active in fresh
   clones. .pre-commit-config.yaml has cargo-fmt (cargo fmt --all -- check) and cargo-clippy (cargo +stable clippy --all-targets -- -D warnings) — exactly the CI gates — but the git hooks are only installed
   after pre-commit install, which an agent/contributor may never run.

Net: the cheapest, most common CI failure (rustfmt) has no fast local guard in
the default agent workflow.

Suggested fix

• Add a fast cargo fmt --check step to the Claude/agent pre-commit hook
  (it runs in ~1s, and Format is the single most common first-push failure).
  Leave clippy/test out of the per-commit hook (too slow), but a fmt gate alone
  would eliminate most red first-pushes.
• Optionally document a one-shot pre-commit install --install-hooks (or a
  cargo fmt --check && cargo clippy --all-targets -- -D warnings one-liner) in
  AGENTS.md under a "before you push" heading, since docs/pre-commit.md exists
  but isn't surfaced where agents look.

Note for triagers

cargo clippy ... | grep '^error' is a deceptive local check — CI runs clippy
with -D warnings, so a warning (e.g. doc_lazy_continuation) fails CI while
that grep reports clean. Worth calling out in contributor docs.

Found by an AI agent dogfooding rivet.

[avrabe]

Addressed in #440 (REQ-174).

On investigation the root cause was more specific than "the agent hook doesn't run fmt" — there are two disagreeing pre-commit definitions in the repo:

• scripts/pre-commit (standalone file) runs cargo fmt --all -- --check and cargo clippy --all-targets -- -D warnings.
• scripts/install-hooks.sh generates its own pre-commit hook that runs only rivet validate — it never wires scripts/pre-commit.

So even a contributor who runs the documented install-hooks.sh gets a validate-only hook and no fmt/clippy guard → CI Format/Clippy surprises (this loop hit it on #437).

Fix in #440: add a fast cargo fmt --all -- --check to the installed hook, gated on staged .rs files (so non-Rust commits aren't slowed), blocking with a clear message. Kept clippy/test out of per-commit (too slow) — they stay in CI. Verified by installing the hook and confirming a misformatted staged Rust file is blocked (exit 1) while clean / non-Rust commits pass.

Two follow-ups I did not fold in (separate concerns):

1. The .claude/settings.json hook is PostToolUse-only (rivet stamp); CLAUDE.md's claim that "a Claude Code pre-commit hook runs rivet validate" is inaccurate — but CLAUDE.md is auto-generated by rivet init --agents, so the real fix is in that generator, not the file.
2. scripts/pre-commit (fmt+clippy) is now redundant with the installer's hook for fmt; worth either deleting it or having the installer source it, to remove the divergence.

[avrabe]

Triage (dogfooding loop): verified the resolution state.

• Core fix landed: ci(hooks): pre-commit also runs cargo fmt --check on staged Rust (REQ-174, #438) #440 (REQ-174, merged) added cargo fmt --all -- --check (gated on staged .rs) to the installer-generated hook — confirmed in scripts/install-hooks.sh. That closes the actual "no fast fmt guard" gap.
• Follow-up 1 (generator/CLAUDE.md accuracy): checked the current rivet init --agents output in a fresh temp project — it emits no "Claude Code pre-commit hook runs rivet validate" claim. So the generator is already clean; the inaccurate line survives only as hand-written content in this repo's CLAUDE.md (it sits above the BEGIN rivet-managed marker). And it's doubly off: .claude/settings.json holds a PostToolUse rivet stamp (provenance), not a pre-commit, and the real rivet validate pre-commit is the git hook from install-hooks.sh, not a "Claude Code" hook. A one-line correction to this repo's CLAUDE.md is all that's left there.
• Follow-up 2 (scripts/pre-commit divergence): still a maintainer design call (delete the now-redundant standalone vs. have the installer source it).

Net: the friction this issue reported is fixed. Suggest closing once the one stale CLAUDE.md line is corrected (or repurposing to just track follow-up 2).

[avrabe]

Triaged from the hourly dogfooding loop — valid, with one nuance worth recording.

Verified against the code:

• .claude/settings.json indeed only has a PostToolUse stamp hook (rivet stamp all --created-by ai-assisted) — no fmt/clippy. Confirmed.
• But scripts/install-hooks.sh was updated (after this issue was filed) and now installs a git pre-commit that runs cargo fmt --all -- --check on staged .rs and blocks. So the fmt gap is closed once you run ./scripts/install-hooks.sh. The residual gap your report correctly identifies: the default agent workflow has no fast fmt/clippy guard unless hooks are manually installed, and clippy is never per-commit.

Acted on (PR #475): implemented your second suggestion — added a "Before You Push (Rust)" section to AGENTS.md with the verbatim CI gates (cargo fmt --all -- --check, cargo clippy --all-targets -- -D warnings) and the three traps that actually bite agents: the grep '^error' blind spot under -D warnings (your triager note — kept it), -p <crate> skipping --all-targets test lints, and the commit-msg hook rejecting Word: body lines.

Stronger fix attempted, needs your call: the ideal fix is a .claude/settings.json PostToolUse hook that auto-runs cargo fmt --all on every .rs edit — that makes fmt drift impossible rather than merely documented. I attempted exactly that edit; it's correctly gated as self-modification of agent auto-run config and requires explicit maintainer authorization. If you want it, the one-line addition to the existing Edit|Write PostToolUse array is:

{ "type": "command", "if": "Edit(**/*.rs)|Write(**/*.rs)", "command": "cargo fmt --all 2>/dev/null || true" }

[avrabe]

Triaged + fixed from the hourly dogfooding loop. The report is valid, but the root cause is slightly different from the title — and the fix is now up in #505 (REQ-210).

What I verified against the code:

• The Claude Code hook (.claude/settings.json) only has a PostToolUse provenance-stamp hook — it never runs on commit, so it was never the thing that should run fmt.
• The git pre-commit hook that this repo actually uses (.git/hooks/pre-commit, which does run cargo fmt --all -- --check) was installed by the dev-only scripts/install-hooks.sh — not by the shipped command.
• The shipped command rivet init --hooks (cmd_init_hooks, rivet-cli/src/main.rs) installs a pre-commit hook that runs only rivet validate. No fmt check. So any project that adopts hooks the supported way gets no formatting gate — that's the real gap behind "AI commits pass locally, fail CI Format".

Fix (#505): cmd_init_hooks now emits a pre-commit hook that runs cargo fmt --all -- --check before rivet validate, guarded to stay language-agnostic — it runs only when command -v cargo succeeds and the commit stages at least one .rs file (git diff --cached … | grep -q '\.rs$'). Non-Rust rivet projects skip it silently. Mirrors scripts/install-hooks.sh.

Verified: temp-repo rivet init --hooks generates the hook with both guards + the preserved validate step (passes bash -n); full cli_commands suite 127/0; cargo fmt --check + clippy --all-targets -- -D warnings exit 0; rivet validate PASS.

Note on the limit (honest): this is still convenience only — git commit --no-verify (which agents use to get past the commit-msg trailer hook) bypasses the git pre-commit hook, fmt included. The durable guarantee remains CI (REQ-051). A Claude-Code-layer PreToolUse guard on git commit would survive --no-verify, but it would block the maintainer's own commits too, so I left that as a follow-up rather than ship it unilaterally.