fix(hooks): lower Stop timeout + add opt-in pre-push workspace gate (#462) (#469)

Final umbrella items from #462 once #464 (PEP 723) and #465 (per-crate
scoping) have shipped:

- **Stop hook timeout 600s → 120s.** Anything past 2 min on Stop is
  treated as a hang now, not silently accepted. With #465's scoped
  clippy/test, a typical single-crate edit completes well under that.
- **`ci/git-hooks/pre-push`** runs the workspace-wide gate (`cargo
  fmt --check`, `cargo clippy --workspace --all-targets -- -D warnings`,
  `cargo test --workspace`) before any branch leaves the machine. Opt
  in once per clone with `git config core.hooksPath ci/git-hooks`.
- Auto-skips when no `.rs`/`Cargo.toml`/`Cargo.lock`/toolchain change
  is in the push range, so doc-only pushes are free.
- Bypass via `git push --no-verify` or `FBUILD_SKIP_PRE_PUSH=1`.

Rationale: Stop hook is per-conversation interactive feedback (fast,
scoped). Push is the boundary where workspace correctness actually
matters. CI still runs the same workspace verification — pre-push
just catches escapes locally.

Items from #462 that are already covered:
- *Skip-gate by file-extension diff* → #465 (no-Rust-changes returns
  early; doc-only edits skip entirely).
- *Scope clippy + test to affected crates* → #465.
- *Serialize lint then test* → #465 keeps the concurrent-with-early-exit
  pattern; the early-exit on lint failure already captures the
  "don't waste time testing if lint is broken" win.

Closes #462.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: zackees

.claude/settings.json

@@ -62,7 +62,7 @@
           {
             "type": "command",
             "command": "cd \"$(git rev-parse --show-toplevel)\" && uv run --script ci/hooks/check-on-stop.py",
-            "timeout": 600
+            "timeout": 120
           }
         ]
       }

ci/git-hooks/README.md

@@ -0,0 +1,40 @@
+# Local git hooks
+
+Tracked git hooks for fbuild. Opt in **once per clone**:
+
+```bash
+git config core.hooksPath ci/git-hooks
+```
+
+After that, every hook in this directory is wired up automatically. The
+directory is on the repo's normal source path so updates flow with
+`git pull`.
+
+## Hooks
+
+- **`pre-push`** — workspace-wide safety net. Runs `cargo fmt --check`,
+  `cargo clippy --workspace --all-targets -- -D warnings`, and
+  `cargo test --workspace` before any branch is pushed. Skipped when
+  the push touches no Rust files. Bypass with `git push --no-verify`
+  or `FBUILD_SKIP_PRE_PUSH=1 git push`.
+
+  Why here and not in the Stop hook: the Claude Code Stop hook
+  (`ci/hooks/check-on-stop.py`) is scoped to changed crates for fast
+  iteration (#465). The workspace-wide gate belongs at the
+  *push* boundary, where it actually prevents an escape, not at the
+  conversation-stop boundary, where it just adds latency. See #462.
+
+## Opting out per-push
+
+```bash
+git push --no-verify        # bypass all hooks
+FBUILD_SKIP_PRE_PUSH=1 git push   # bypass only pre-push, keep others
+```
+
+## Adding a new hook
+
+1. Drop an executable script named exactly the git event
+   (`pre-commit`, `commit-msg`, `pre-push`, `post-merge`, ...).
+2. Make it skip cleanly when there's no work to do — `pre-push` here
+   filters by changed-file extensions so non-Rust pushes are free.
+3. Document the bypass mechanism in the script header.

ci/git-hooks/pre-push

@@ -0,0 +1,87 @@
+#!/usr/bin/env sh
+# Pre-push gate: full workspace lint + tests before code leaves this machine.
+#
+# Stop hook (`ci/hooks/check-on-stop.py`) is scoped to the changed crates
+# for fast iteration feedback — see #465. This hook is the workspace-wide
+# safety net. CI also runs `cargo clippy --workspace` + `cargo test
+# --workspace` on every push; this just catches escapes locally so you
+# don't need to wait on a remote runner to find out.
+#
+# Opt in once per clone:
+#
+#     git config core.hooksPath ci/git-hooks
+#
+# Bypass for a single push (e.g. emergency fix where CI must arbitrate):
+#
+#     git push --no-verify
+#
+# Skipped automatically when:
+#   - the cargo workspace has no `.rs`, `Cargo.toml`, or `Cargo.lock`
+#     differences vs the upstream HEAD being pushed to
+#   - the env var `FBUILD_SKIP_PRE_PUSH=1` is set
+#
+# Exit codes:
+#   0 - all checks passed (or skipped)
+#   1 - lint or test failed; push is rejected
+
+set -e
+
+if [ "${FBUILD_SKIP_PRE_PUSH:-0}" = "1" ]; then
+    echo "pre-push: FBUILD_SKIP_PRE_PUSH=1 — skipping workspace gate"
+    exit 0
+fi
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+cd "$REPO_ROOT"
+
+# Read git's per-ref input from stdin: <local ref> <local sha> <remote ref> <remote sha>
+# When pushing a new branch, remote sha is 40 zeros — fall back to upstream/HEAD.
+ZERO="0000000000000000000000000000000000000000"
+RUST_TOUCHED=0
+while read -r _local_ref local_sha _remote_ref remote_sha; do
+    if [ -z "$local_sha" ] || [ "$local_sha" = "$ZERO" ]; then
+        # Deletion — nothing to lint.
+        continue
+    fi
+    if [ -z "$remote_sha" ] || [ "$remote_sha" = "$ZERO" ]; then
+        # New branch — diff against upstream's default branch.
+        base="$(git merge-base "$local_sha" origin/HEAD 2>/dev/null || echo "")"
+        if [ -z "$base" ]; then
+            # No upstream HEAD known — be conservative and run the gate.
+            RUST_TOUCHED=1
+            break
+        fi
+    else
+        base="$remote_sha"
+    fi
+    if git diff --name-only "$base" "$local_sha" 2>/dev/null \
+        | grep -Eq '(\.rs$|Cargo\.toml$|Cargo\.lock$|rust-toolchain\.toml$|^\.cargo/)'; then
+        RUST_TOUCHED=1
+        break
+    fi
+done
+
+if [ "$RUST_TOUCHED" = "0" ]; then
+    echo "pre-push: no Rust changes in this push — skipping workspace gate"
+    exit 0
+fi
+
+echo "pre-push: running workspace lint + tests"
+echo "  (set FBUILD_SKIP_PRE_PUSH=1 to bypass)"
+
+soldr cargo fmt --all -- --check || {
+    echo "pre-push: rustfmt --check failed; run \`soldr cargo fmt --all\`" >&2
+    exit 1
+}
+
+soldr cargo clippy --workspace --all-targets -- -D warnings || {
+    echo "pre-push: clippy --workspace failed" >&2
+    exit 1
+}
+
+soldr cargo test --workspace || {
+    echo "pre-push: cargo test --workspace failed" >&2
+    exit 1
+}
+
+echo "pre-push: workspace gate passed"