Add pre-push validation hook

README.md

@@ -69,9 +69,10 @@ moved, not because somebody edited a chapter.
 
 ## Git hooks
 
-The repository ships a `pre-commit` hook that keeps committed C sources in the
-project's canonical format (Emacs `cc-mode` "stroustrup"; see `AGENTS.md` for the
-full style guide). The hook lives in `scripts/hooks/` and is version controlled,
+The repository ships `pre-commit` and `pre-push` hooks. `pre-commit` keeps committed C
+sources in the project's canonical format (Emacs `cc-mode` "stroustrup"; see `AGENTS.md`
+for the full style guide), while `pre-push` runs the local build and test gates. The hooks
+live in `scripts/hooks/` and are version controlled,
 but **Git configuration is not cloned**, so every clone has to be pointed at it
 once:
 
@@ -85,8 +86,21 @@ Confirm it took effect:
 git rev-parse --git-path hooks     # should print: scripts/hooks
 ```
 
-That is the whole installation. The hook is already committed with its
-executable bit set, so nothing needs `chmod`.
+That is the whole installation: it enables both hooks. They are already committed with
+their executable bits set, so nothing needs `chmod`.
+
+The pre-push hook builds with `AKGL_WERROR=ON` and runs CTest without the performance
+suites. It also runs cppcheck and Doxygen when their tools are available. Valgrind and
+mutation testing are opt-in because they are slower:
+
+```sh
+AKGL_HOOK_MEMCHECK=1 git push
+AKGL_HOOK_MUTATION=1 git push
+```
+
+The builds live under `.git/akgl-prepush`, so the hook does not disturb the developer's
+own `build/` directory. A delete-only push is skipped. Missing optional tools are warned
+about and skipped; CI remains the hard gate. Use `git push --no-verify` to bypass the hook.
 
 ### What the hook does