From 920d5c6c3a8cc73cc9b659b7c5e903c52d3afa14 Mon Sep 17 00:00:00 2001
From: Yeachan-Heo <hurrc04@gmail.com>
Date: Mon, 25 May 2026 20:06:13 +0000
Subject: [PATCH] Catch stale Rust compile drift before push

Add a repository-local pre-push gate that runs the locked Rust workspace build from the repo root, plus concise install and verification docs for maintainers.

Constraint: ROADMAP #694 requires a local installable hook artifact only; branch protection remains external.
Rejected: CI or branch-protection changes | outside the requested local pre-push gate scope.
Confidence: high
Scope-risk: narrow
Directive: Keep .github/hooks/pre-push and contributor docs synchronized if the Rust workspace build command changes.
Tested: bash -n .github/hooks/pre-push; SKIP_CLAW_PRE_PUSH_BUILD=1 .github/hooks/pre-push; git diff --check; python3 .github/scripts/check_doc_source_of_truth.py; cargo fmt --manifest-path rust/Cargo.toml --all -- --check; cargo build --manifest-path rust/Cargo.toml --workspace --locked; .github/hooks/pre-push
Not-tested: shellcheck and markdownlint unavailable in environment.
---
 .github/hooks/pre-push                             | 10 ++++++++--
 CONTRIBUTING.md                                    | 14 ++++++++++++++
 ...3-roadmap-pinpoints-693-695-verification-map.md |  5 +++--
 3 files changed, 25 insertions(+), 4 deletions(-)

diff --git a/.github/hooks/pre-push b/.github/hooks/pre-push
index 2f396744..c3644a31 100755
--- a/.github/hooks/pre-push
+++ b/.github/hooks/pre-push
@@ -8,6 +8,11 @@
 # caught before pushing to main or PR branches.
 set -euo pipefail
 
+if [[ "${SKIP_CLAW_PRE_PUSH_BUILD:-}" == "1" ]]; then
+  echo "pre-push: SKIP_CLAW_PRE_PUSH_BUILD=1 set; skipping cargo workspace build" >&2
+  exit 0
+fi
+
 repo_root="$(git rev-parse --show-toplevel 2>/dev/null)"
 cd "$repo_root"
 
@@ -16,5 +21,6 @@ if [[ ! -f rust/Cargo.toml ]]; then
   exit 0
 fi
 
-echo "pre-push: cargo build --manifest-path rust/Cargo.toml --workspace" >&2
-cargo build --manifest-path rust/Cargo.toml --workspace
+build_cmd=(cargo build --manifest-path rust/Cargo.toml --workspace --locked)
+echo "pre-push: ${build_cmd[*]}" >&2
+"${build_cmd[@]}"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 92c629ae..0f191be2 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -33,6 +33,20 @@ cargo build --workspace
 .\target\debug\claw.exe --help
 ```
 
+## Local pre-push build gate
+
+Install the repository-local hook to catch stale compile errors before pushing:
+
+```bash
+git config core.hooksPath .github/hooks
+```
+
+This sets the repo's Git hook directory to `.github/hooks`; if you already use a
+custom `core.hooksPath`, copy or chain `.github/hooks/pre-push` instead. The hook
+runs `cargo build --manifest-path rust/Cargo.toml --workspace --locked` from the
+repository root. If you must bypass it for a non-code/docs-only push, set
+`SKIP_CLAW_PRE_PUSH_BUILD=1`; the hook prints when that escape hatch is used.
+
 ## Checks before opening a pull request
 
 Run the smallest relevant tests for your change, then the broader checks when
diff --git a/docs/g013-roadmap-pinpoints-693-695-verification-map.md b/docs/g013-roadmap-pinpoints-693-695-verification-map.md
index 131c57ce..0c113e61 100644
--- a/docs/g013-roadmap-pinpoints-693-695-verification-map.md
+++ b/docs/g013-roadmap-pinpoints-693-695-verification-map.md
@@ -17,7 +17,8 @@ covered by the Claw Code 2.0 board.
 
 - Hook: `.github/hooks/pre-push`
 - Install command: `git config core.hooksPath .github/hooks`
-- Gate: `cargo build --manifest-path rust/Cargo.toml --workspace`
+- Gate: `cargo build --manifest-path rust/Cargo.toml --workspace --locked`
+- Escape hatch: `SKIP_CLAW_PRE_PUSH_BUILD=1` prints an explicit skip message.
 - Purpose: mirror the CI build job locally so stale field/variant references are
   caught before push.
 
@@ -43,5 +44,5 @@ bash -n .github/hooks/pre-push
 cargo fmt --manifest-path rust/Cargo.toml --all -- --check
 cargo test --manifest-path rust/Cargo.toml -p claw-analog rag_response_ -- --nocapture
 cargo test --manifest-path rust/Cargo.toml -p runtime startup_preflight -- --nocapture
-cargo build --manifest-path rust/Cargo.toml --workspace
+cargo build --manifest-path rust/Cargo.toml --workspace --locked
 ```