Add an advisory agent hook for mid-phrase line breaks

[Flix6x]

Description

The docstring convention — break lines only after punctuation — has been missed in three PRs in a row (#2364, #2218, #2385), each time caught by a reviewer rather than the author. #2384 documented the rule harder, and the very next PR broke it. Documentation is evidently not the missing piece.

• .claude/hooks/reflow_check.py — the check
• .claude/hooks/reflow-check.sh + wiring in .claude/settings.json, as a PreToolUse hook on git commit

Two deliberate choices

It is an agent hook, not a pre-commit hook. The misses have been an agent's, and contributors shouldn't pay a false-positive tax for that. It's also the only form that works: the check is a heuristic, and a heuristic gate that a human hits on embedded OpenAPI YAML gets disabled. An agent can read "line 2028 may break mid-phrase", look at the line, and judge — the same way worktree-guard.sh explains itself rather than just failing.

It is advisory and never blocks. Exits 0 always, and inspects only the lines being added. A legacy file is therefore not a wall — the repo has ~4350 candidate hits across 72% of files, and reflowing unrelated prose is not something a commit should be doing.

On the false-positive rate

Docstrings here carry OpenAPI YAML, shell commands and bullet lists — none of it prose, none of it ending in punctuation. Suppressing those cuts the noise where it matters:

file	before suppression	after
api/v3_0/sensors.py	494	59
api/v3_0/assets.py	385	15
data/models/planning/storage.py	199	173

storage.py stays high because it is genuinely prose-heavy — that's the honest number rather than a tuned one. Since the hook only looks at added lines, the standing count matters little; what matters is that a new mid-phrase break gets surfaced.

How to test

Proven capable of failing (per #2384):

# staged docstring broken mid-phrase -> reported
Possible mid-phrase line breaks in docstrings or comments:
  probe_demo.py:4: This sentence breaks in the middle of a

# correctly reflowed -> silent

It caught a real one while I was writing #2385: a comment of mine ending "…so running each test twice in one".

Further improvements

• If it proves accurate enough in practice, a blocking variant scoped to flexmeasures/data/models/planning/** could follow. Better to run it advisory first.

Related items

• Require new tests to be proven capable of failing #2384 — the convention this enforces.
• Add a Pyomo-free scheduling backend (direct highspy model construction) #2364, Combined Heat and Power (CHP) #2218, Run the scheduler constraint tests under both backends #2385 — the three misses.

[read-the-docs-community]

Documentation build overview

📚 flexmeasures | 🛠️ Build #33897286 | 📁 Comparing 961e245 against latest (b33ec32)

  🔍 Preview build  

1 file changed

± api/v3_0.html