The test run and the lint profile move from the commit gate to the push gate

.pre-commit-config.yaml

@@ -195,13 +195,19 @@ repos:
         pass_filenames: false
         always_run: true
         stages: [manual]
+      # Not pre-commit. A full suite compiled and run in front of every commit
+      # is how a gate teaches `--no-verify`: the cost lands on every save point,
+      # including the ones that touch no Rust at all, and a flag learned to skip
+      # a slow test run skips the guards standing beside it. Pre-push is where
+      # the same suite still refuses before anything leaves the machine, which
+      # is the moment refusing is worth what it costs.
       - id: engine-tests
         name: scan engine tests
         entry: cargo test --quiet
         language: system
         pass_filenames: false
         always_run: true
-        stages: [pre-commit, manual]
+        stages: [pre-push, manual]
       # The lint profile is declared in Cargo.toml, so every runner and CI hold
       # the crate to one set. This is where a contributor hears about it: a
       # profile only the workflow runs is one whose first reader is a failed
@@ -214,13 +220,18 @@ repos:
         pass_filenames: false
         always_run: true
         stages: [pre-commit, manual]
+      # Pre-push for the reason the test run is. `--all-targets` compiles the
+      # test tree as well, so this is a second full build in front of a commit,
+      # and a stage a contributor has learned to skip holds nothing at all. The
+      # profile is still read before the push, which is what the comment above
+      # asks for: the first reader of a lint is not a failed workflow.
       - id: engine-clippy
         name: clippy, under the crate's own lint profile
         entry: cargo clippy --quiet --all-targets
         language: system
         pass_filenames: false
         always_run: true
-        stages: [pre-commit, manual]
+        stages: [pre-push, manual]
       # Fires on the declaration and on every config it reads -- the files that
       # can turn a true enforcement claim into a false one -- and on nothing
       # else. A check with no firing condition is the thing this repository's

CONTRIBUTING.md

@@ -63,19 +63,41 @@ two forms the note names start being checked as well.
 
 ## Working on the engine
 
-The Rust side has two checks CI runs that the commit stage does not, because
-both are about the host or the whole tree rather than about a staged file:
+The checks sit on three rungs, and which rung one sits on is a statement about
+what it costs to run. The commit stage is what can answer from the tree in front
+of it: `cargo fmt --check`, the catalog gates, the content scan, and the guards
+registered for the stage. Nothing there compiles the test tree and nothing there
+opens a socket.
+
+The push stage is where the crate is built and exercised:
+
+```sh
+cargo test --quiet                    # the engine suite
+cargo clippy --quiet --all-targets    # the lint profile declared in Cargo.toml
+```
+
+Both stood in front of every commit until they did not. A full compile and test
+pass at every save point is how a gate teaches `--no-verify` — the cost lands on
+the commits that touch no Rust as well, and a flag learned to skip a slow suite
+skips the guards standing beside it. At `pre-push` the same two still refuse
+before anything leaves the machine, which is the moment refusing is worth the
+wait. `uphold guard --stage pre-push` runs there with them.
+
+The manual rung is the host and the network, which neither a staged file nor a
+pushed range can react to:
 
 ```sh
-scripts/deps.sh check     # rustup, rustc >= the MSRV, python3, the coverage pair
-scripts/coverage.sh       # line coverage, refused under the floor in the script
+scripts/deps.sh check          # rustup, rustc >= the MSRV, python3, the coverage pair
+scripts/coverage.sh            # line coverage, refused under the floor in the script
+uphold guard --stage manual    # the guards that ask a remote about a pin or a name
 ```
 
-Both are `manual`-stage hooks under pre-commit and prek, and named groups under
-lefthook (`lefthook run preflight`, `lefthook run coverage`), so whichever runner
-is installed can reach them. The coverage floor lives in `scripts/coverage.sh`
-and nowhere else — the workflow calls the same script, so the number that fails a
-push is the number that fails locally. Raise it in the commit that earns it.
+All three are `manual`-stage hooks under pre-commit and prek, and named groups
+under lefthook (`lefthook run preflight`, `lefthook run coverage`, `lefthook run
+uphold-manual`), so whichever runner is installed can reach them. The coverage
+floor lives in `scripts/coverage.sh` and nowhere else — the workflow calls the
+same script, so the number that fails a push is the number that fails locally.
+Raise it in the commit that earns it.
 
 Editing anything under `policy/base/` means regenerating the set lock in the
 same commit, because a bundled set ships inside the binary and its diff exists

lefthook.yml

@@ -22,15 +22,11 @@ pre-commit:
       run: cargo run --quiet -- scan
     guards:
       run: cargo run --quiet -- guard --stage pre-commit
-    engine-tests:
-      run: cargo test --quiet
     # The lint profile lives in Cargo.toml, so all three runners hold the crate
     # to the same set. What differs is when a contributor hears about it: a
     # profile only CI reads is one whose first reader is a failed push.
     engine-fmt:
       run: cargo fmt --check
-    engine-clippy:
-      run: cargo clippy --quiet --all-targets
     # Report rather than fix, which is the one difference from the ruff hook the
     # other two runners get: pre-commit and prek own the staged file after a
     # hook rewrites it, and a linter that edits a file lefthook has already
@@ -104,7 +100,17 @@ pre-merge-commit:
       run: cargo run --quiet -- guard --stage pre-merge-commit
 
 pre-push:
+  parallel: true
   commands:
+    # The suite and the lint profile, one rung up from the commit. A full
+    # compile-and-run in front of every commit is how a gate teaches
+    # `--no-verify`, and a flag learned to skip a slow test run skips the
+    # guards standing beside it; once per push is where the same two still
+    # refuse before anything leaves the machine.
+    engine-tests:
+      run: cargo test --quiet
+    engine-clippy:
+      run: cargo clippy --quiet --all-targets
     # `use_stdin: true`, which this was missing. lefthook runs a command under a
     # pseudo-TTY by default and that stdin never closes, so git's ref lines
     # never arrived and the guards that read the pushed range were asked about