sl0ppty: make tools, and a ruff version that cannot drift

`ruff` is not a system package on most machines, and `pip install --user ruff` is
refused outright on a distro python (PEP 668) -- so the last two commits shipped a
formatter nobody could run without knowing to build a venv by hand. `make tools`
builds it:

    $ make tools
      ruff 0.16.3  in .venv
      survives make clean; rm -rf .venv to start over

clang-format stays a system package, because everywhere it is one. `make tools`
says so if it is missing rather than pretending it handled it.

**The venv is looked in before `$PATH`, and the order is the point.** `ruff.toml`
now pins the version with ruff's own `required-version`, so a ruff of the wrong one
refuses to run and names both versions. Preferring `$PATH` would then strand
somebody who has 0.14 from their package manager and 0.16.3 sitting in the `.venv`
the repo just built for them -- refused by the tool, with the fix already on disk
and not being looked at. Tested with exactly that: 0.14.0 on `$PATH`, `make
fmt-check` still clean.

The pin exists because a formatter whose output moves between releases turns
"formatted" into "formatted by whoever committed last", and the diff lands on the
next person to touch the file. Refusing loudly is better than reformatting quietly.
Bumping it is one line in `ruff.toml`, one in the Makefile, and a reformat commit,
which is the honest cost of a new version.

The hook resolves ruff the same way, off `git rev-parse --show-toplevel` so it works
from a subdirectory, and its "not installed" message now says `make tools` instead
of naming three package managers and hoping.

Verified from the state a fresh clone is in: with no ruff anywhere, `make fmt` says
`ruff not found. run: make tools` and stops; after `make tools` (2.6s) both `fmt`
and `fmt-check` work with nothing on `$PATH`; the hook formats a staged Python file
using the venv; the venv survives `make clean`; and `.venv/` is ignored.

`make fmt` over the whole tree after all this changed nothing, which is the useful
part: the pinned version agrees with what is already committed.

One near-miss worth recording: the `.gitignore` line for `.venv/` had to be written
twice. A `git reset --hard` undoing a throwaway probe commit took the working tree
with it, including that edit -- which is what `--hard` does, and why the state was
checked afterwards rather than assumed.

1 files changed, 21 insertions, 0 deletions

diff --git a/docs/design.md b/docs/design.md
index 012d4c2..7da7d60 100644
--- a/docs/design.md
+++ b/docs/design.md
@@ -56,6 +56,27 @@ selection, images and key encoding; everything above is ours.
 `make fmt-check` only reports, and `make hooks` installs a pre-commit hook that
 formats what you staged, so what lands in git is already formatted.
 
+Getting the two tools:
+
+```
+make tools            # a venv in .venv with the pinned ruff
+apt install clang-format          # ...or brew, or your package manager
+```
+
+clang-format is a system package everywhere. ruff usually is not, and
+`pip install --user ruff` is refused outright on a distro python (PEP 668), so
+`make tools` builds a venv in `.venv/` and everything looks there **before**
+`$PATH`. That order matters: `ruff.toml` pins the version with ruff's own
+`required-version`, so a system ruff of the wrong one refuses to run -- and
+preferring `$PATH` would strand somebody whose `.venv` has exactly the version the
+repo asked for. The venv survives `make clean`; `rm -rf .venv` starts over.
+
+The pin is there because a formatter whose output moves between releases turns
+"formatted" into "formatted by whoever committed last", and the diff lands on the
+next person. A mismatch is refused with both versions named rather than quietly
+reformatting the tree. Bumping it is one line in `ruff.toml`, one in the Makefile,
+and a reformat commit -- which is the honest cost of a new version.
+
 The base is LLVM, because that is what this code was written in by hand — two
 spaces, 80 columns, `char *p`, braces attached. The settings that differ from it
 were chosen by measuring the reformat rather than by taste: LLVM alone rewrote 38%