[anth-volk]

Fixes #4206

Based on master. It was stacked on #4203, which adds make quality and has merged. The branch was then rebased onto master as a plain series of its own eight commits, with no merge commits, so GitHub can rebase-merge it. The commit references below are the rebased ones.

Summary

• .githooks/pre-commit runs make quality from the root of the working tree before git commit. make quality checks the working tree, so the hook first requires it to hold exactly what is being committed. It stops the commit, naming the files and saying what to do:

  • while tracked files have unstaged changes ("stage exactly what this commit needs and run git commit without paths, or set the rest aside with git stash push --keep-index"). This includes fixes make quality made in an earlier, failed run, git commit <paths> while other files are changed, and a case-only rename on a file system that ignores case. The hook lists files with core.ignorecase=false to catch the last one;
  • while untracked files exist outside the ignore files ("add them, remove them, or list them in .git/info/exclude");
  • while Python files or tool settings (pyproject.toml, setup.cfg, mypy.ini, ruff.toml, .importlinter) are hidden only by .git/info/exclude or a global excludes file, since ruff, mypy and Import Linter can read them anyway. The hook lists a wholly untracked directory once (--directory), and leaves out virtual environments (a directory with pyvenv.cfg) and directories with neither kind of file;
  • while those excludes match tracked Python files, which ruff would skip but CI checks;
  • while tracked files are marked skip-worktree or assume-unchanged, which git diff doesn't compare ("run git update-index --no-skip-worktree --no-assume-unchanged"). It matches git's tags with [[:lower:]S]. bash 3.2, macOS's /bin/sh, matches uppercase letters with [a-z] in UTF-8 locales, so [a-z] would refuse every commit there;
  • when make quality fails;
  • when ruff's fixes changed a file ("review the fixes, stage them, then commit again");
  • when make or uv isn't installed, or the dev environment (.venv, or UV_PROJECT_ENVIRONMENT) is missing, instead of passing without running the checks.

  Names outside ASCII are shown as they are. The hook clears MAKEFLAGS, MFLAGS, GNUMAKEFLAGS, MAKEFILES, MAKELEVEL, MAKE, MAKE_COMMAND and MAKEOVERRIDES before running make, so they can't make it ignore a failing check or replace $(MAKE). It stops the commit if git diff or git ls-files itself fails. It needs only git, make, uv and the shell.

• .githooks/pre-merge-commit runs the same hook, without needing dirname. git runs it, not pre-commit, for a merge that commits without conflicts.

• make install runs .githooks/turn-on.sh, then uv sync --frozen --extra dev as before. The script sets core.hooksPath to .githooks at the root of a git working tree, including a linked worktree. It changes nothing, and says why, when:

  • the directory isn't the root of a working tree, such as a source tree unpacked inside another repository. It checks this with git rev-parse --show-prefix, so a differently cased path doesn't confuse it;
  • core.hooksPath already names another directory;
  • the clone has hooks of its own in .git/hooks, including symbolic links and a linked directory, which core.hooksPath would stop git running;
  • git can't write the setting, for example while another command holds .git/config's lock.

  It never fails, so make install still installs, and outside a repository it does nothing.

• core.hooksPath is a setting of the clone, so every worktree runs the hooks. git resolves the relative path in each working tree, so each worktree runs its own checkout's copy, and a worktree on a branch from before the hooks runs none.

• New enforced rule api.quality.pre-commit-hook.

  • tests/unit/test_pre_commit_hook.py runs the hooks in temporary repositories whose Makefile's quality target stands in for the checks.
  • The tests run with a PATH holding only git, make, sh, find, env and a stand-in uv that records its calls. They use no global or system git settings, and a scratch XDG_CONFIG_HOME.
  • The rule lists all 35 hook tests as its enforcer nodes.
  • The proof runs a hook that ignores everything (rejected) and a minimal correct one (accepted) through six refusal scenarios and one passing commit.

• Docs: AGENTS.md, the GitHub PRs skill's "Commit Hygiene" (the rule's rationale), the testing skill and README.md say:

  • to run make install once per clone, and again in each new worktree for its .venv;
  • to stage everything the commit needs;
  • what the hooks cover, and not to skip them.

Design choices for review

• The decision (tracker task 6.4 · 9) was a git pre-commit hook running all of make quality, and no Claude Code hook. It covers every agent and person in clones where make install ran. git commit --no-verify skips it, and git's cherry-pick, revert, rebase and am can make commits without hooks (some steps, such as a rebase's reword, do run them). CI's Quality checks job still runs the same checks and blocks the merge.
• The working tree must match the commit. That is stricter than checking only staged files, but make quality reads files on disk. Without the rule, fixes from an earlier run, partial staging, or an untracked file could make the result differ from what is committed. The one way to commit part of the changes is git stash push --keep-index first.
• A new worktree needs make install before its first commit. Without its .venv, the hook stops the commit and says so, rather than let uv run build the environment in the middle of the commit.
• make quality takes about 3 seconds with warm caches and about 10 seconds cold (mypy 6.7 s, the guards 2.0 s), measured on Run every quality check through make quality, locally and in CI #4203's branch. A review run through this hook with cold caches and no network took about 13 to 14 seconds.
• Known limits. None of these lets a commit pass silently in normal use, and CI still runs the checks:
  • An untracked .gitignore that hides itself can hide files from the hook.
  • A clean filter in .gitattributes can make the committed blob differ from the checked file.
  • PYTHONPATH or MYPYPATH in the environment can add code the checks read.
  • A sparse checkout, or core.ignoreStat=true, marks files so that every commit is refused.
• Untracked tool directories. In a clone with untracked .claude/ or .codex/ directories, commits are refused until those are listed in .git/info/exclude or ignored.
• make install in CI jobs now also sets core.hooksPath in the job's checkout. No job that runs make install makes commits.
• I didn't run make install in my own clone, because the setting would apply to every worktree of it, including other sessions' worktrees. The tests use temporary repositories.

CI wiring and environment variables

No workflow changes. The tests run in the existing Test shards (make test).

• The hooks read PATH, to find make and uv, and UV_PROJECT_ENVIRONMENT when it is set. They also read the variables git sets for hooks, such as GIT_INDEX_FILE. They read no secret.
• .githooks/turn-on.sh reads only git's settings.
• The tests set PATH, HOME, GIT_CONFIG_GLOBAL=/dev/null, GIT_CONFIG_NOSYSTEM=1, the git author and committer, and paths for their own markers, for their temporary repositories. They remove GIT_*, UV_* and make's variables inherited from the test run.

Testing

Red, at 312b58bef (tests and fixtures only): 10 of 12 tests failed. There was no hook, and make install set nothing.

Green, at be86f1117: all 12 passed.

Review round 1, red at f252e7806: 15 of 23 tests failed. Several of those failed because the first hook needed mktemp, which the tests' PATH leaves out. The rest covered:

• unstaged changes, untracked files and fixes left by an earlier run;
• commit -a;
• a merge;
• UV_PROJECT_ENVIRONMENT;
• a worktree's own hook;
• make install beside an enclosing repository, another core.hooksPath, or the clone's own hooks;
• both hooks being executable.

Green at c764aa1c7: all 23 pass, by node ID.

Review round 2, red at 26ee1ab90: 9 of 33 test cases failed. They covered:

• a merge without dirname;
• a Python file hidden by .git/info/exclude;
• MAKE and MAKE_COMMAND;
• skip-worktree and assume-unchanged files;
• a symlinked hook and a linked .git/hooks;
• a locked .git/config.

The same commit also does two other things:

• It changes tests/unit/test_locked_test_environments.py::test_make_install_syncs_the_locked_development_environment. That test asserted that make install's recipe was exactly uv sync --frozen --extra dev, and would have failed in CI. It now checks that the recipe syncs the locked environment and that its other commands install nothing.
• It isolates the tests from $XDG_CONFIG_HOME/git/ignore.

Green at ac4e18a2b: all 33 cases pass.

Review round 3, red at dc4ecd28c: 8 test cases failed on macOS. They covered:

• a commit under en_US.UTF-8;
• ruff.toml, mypy.ini and lib/pyproject.toml hidden by .git/info/exclude;
• a hidden virtual environment, which must not stop the commit;
• a tracked file .git/info/exclude matches;
• a case-only rename;
• the advice for git commit <paths>.

Green at fc36ee404: all 42 hook cases pass, also with the test run itself under en_US.UTF-8.

Also run locally at fc36ee404:

• make quality: passes, and changes no file;
• shellcheck on the three scripts and both fixtures, also as dash: nothing reported;
• python -m scripts.rules guard --base-ref origin/quality/make-quality and validate: pass;
• Run every quality check through make quality, locally and in CI #4203's make-quality tests (7 pytest functions, 23 unittest IDs), since this changes the Makefile they read: pass.

Per this workstream's rules, only the tests this work added or changed were run locally; CI runs the rest.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.11%. Comparing base (e5a00db) to head (fc36ee4).
⚠️ Report is 10 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #4207      +/-   ##
==========================================
- Coverage   92.15%   92.11%   -0.05%     
==========================================
  Files         296      296              
  Lines       16696    16696              
  Branches     2722     2722              
==========================================
- Hits        15386    15379       -7     
- Misses        794      801       +7     
  Partials      516      516              

Flag	Coverage Δ
integration	52.41% <ø> (ø)
unit	90.17% <ø> (-0.05%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.