Add an advisory agent hook reviewing the files a push adds

[Flix6x]

Description

A file can enter a branch without anyone deciding it should. This has happened twice recently:

• .git-exclude (containing a lone conftest.py) reached Balance internal commodity nodes (heat/steam networks) via first-class balance groups #2289 through a merge and survived until review caught it.
• A git add -A swept scheduling_problem.py into a commit that imported nothing from it — noticed only by auditing the commit afterwards.

Both were additions. Modified files are nearly always deliberate; a brand-new file nobody mentioned is the one worth a second look.

• .claude/hooks/push_file_review.py — lists what a push adds relative to the merge-base, and names the ones that look unintended
• Wired in .claude/settings.json as a PreToolUse hook on git push, next to the existing test-reminder.sh

What it flags

Dotfiles, .orig/.rej/.bak/.swp debris, scratch-looking names (local, scratch, probe, debug, tmp), build and runtime artifacts, and anything outside flexmeasures/, documentation/, tests/, .github/, .claude/.

Everything added is listed regardless; the flagged subset just gets called out.

Two deliberate choices

Advisory, exits 0. It cannot know intent — it can only ask whether an addition was meant. That is a question an agent can answer by looking, and a blocking gate cannot. Same reasoning as #2386.

It prints which base it used. The base is the tracked upstream when there is one, else origin/main. Getting that wrong makes the added-file list either noisy or empty, and a stacked branch's base changes when its parent merges — #2289's went from feat/chp to main mid-flight. Printing it makes a wrong guess visible rather than silent.

How to test

Proven capable of failing (per #2384). Against a synthetic commit adding .git-exclude, scratch/local_probe.py and a legitimate module:

This push adds 5 file(s), compared against origin/main:
    .claude/hooks/push-file-review.sh
    .claude/hooks/push_file_review.py
    .git-exclude
    flexmeasures/data/models/planning/legit_module.py
    scratch/local_probe.py

Worth confirming you meant to add these:
    .git-exclude — a dotfile
    scratch/local_probe.py — a scratch-looking name

It flags the two junk files, and leaves the legitimate module and its own files alone. With only a legitimate addition, it lists it and flags nothing.

Limits

It can ask "did you mean to add this?" but not "does this belong in this commit" — it would have caught .git-exclude cleanly, and the scheduling_problem.py case only partially.

Related items

• Add an advisory agent hook for mid-phrase line breaks #2386 — the docstring hook this follows in shape.
• Balance internal commodity nodes (heat/steam networks) via first-class balance groups #2289 — where .git-exclude surfaced.