main is RED on check-public-doc-tables: #1054 pushed BENCHMARKS and FEATURES over their prose budgets, and the pre-push hook now blocks every branch

[localai-bot]

Found while pushing PR #1041. This blocks every branch in the repo, not just mine.

The failure

$ python3 scripts/check-public-doc-tables.py      # at origin/main
ERROR: the public keyed-table docs are not valid:
  - docs/BENCHMARKS.md has 36 prose paragraphs, over the 35 budget
  - docs/FEATURES.md has 22 prose paragraphs, over the 21 budget
exit 1

The pre-push hook runs this checker and refuses the push, so any branch that merges current main inherits a red it did not cause:

pre-push: check-public-doc-tables.py FAILED on 29126316606e
pre-push: refusing to push. Fix the record or pages and amend, or re-run with --no-verify

Bisected, not guessed

Ran the checker at each commit in a detached worktree:

commit	exit	BENCHMARKS	FEATURES	subject
fa3723b85	0	ok	ok	spec(LTX25-DECODE-SPEED) (#1038)
d9441ef3e	0	ok	ok	feat(MODEL-MUSIC-MUSIC3) (#1004)
283c7e492	0	ok	ok	record(ORACLE-LLAMACPP-REPIN-STOCK) (#1051)
e34d71379	1	36/35	22/21	fix(qwen3.5): drop redundant AppleClang capture (#1054)
0f8580e26	1	36/35	22/21	feat(SPEC-MTP-K-GT-1) (#1043)

e34d71379 is where it flips. It is a two-character source fix ([&kRequired] → []) that also added +5 lines to docs/BENCHMARKS.md and +4 to docs/FEATURES.md. Its PR body lists its verification — check-doc-checkpoint, test_doc_checkpoint, check-agent-record, test_agent_record, git diff --check — and check-public-doc-tables.py is not among them. The PR also records that the host had neither CMake nor Clang, so the local gate was partial by disclosure.

The deeper problem is the checker, not the commit

AGENTS.md names this exact shape as defective, in two places:

Limit an entry, not a shared file. A shared-file budget forces each addition to remove another entry. Merging two such edits cleanly is worse than conflicting, because it applies both removals.

A gate often creates the lock. If a checker requires every change to edit one shared file, the checker is defective. Move the obligation to a per-row surface. Do not delete the obligation.

A global paragraph budget on docs/BENCHMARKS.md and docs/FEATURES.md is precisely a shared-file budget. It makes the two documents a lock: every row that adds an explanatory paragraph must find another to delete, and two branches that each delete one merge cleanly into a double deletion. It also produces exactly what happened here — a red that appears on an unrelated author's push, sourced from a commit that landed hours earlier.

What a fix owes

Whichever direction is chosen, it needs its own row, spec and fresh review, because it changes checker semantics:

• Preferred, per AGENTS.md: move the obligation off the shared file. Bound prose per keyed entry, or drop the paragraph budget and keep the per-cell MAX_CELL_CHARS = 220 limit that already does the real work.
• If the budget stays, it must not be a bare count that any unrelated commit can trip — and the pre-push hook should report whose paragraphs are over, not just the total.
• Either way: a red-before test, and a control proving the checker still catches the thing the budget was written for.

Immediate unblock: a records-only PR that brings the two counts back under budget would turn main green today, but it is the anti-pattern above — someone's explanation gets deleted to make room. I am not doing that unilaterally; it is a call for whoever owns the checker.

I pushed #1041 with --no-verify and argued it in the PR body, per AGENTS.md ("Hooks are bypassable convenience, not evidence"; "a commit that needs an exception argues for it in its own message"). The matched-arm evidence is above: origin/main alone fails with the identical numbers, so the branch did not cause it.

Related: #1042 (two defects in check-agent-record's owed_issues() found today), #632.

FOLLOWING_AGENTS_PROTOCOL

Following-Agents-Protocol: true
AI-Assisted: true
Assisted-by: AGENT:claude-opus-5 [claude-code]