main is RED: check-public-doc-tables fails on b493f4981 — #1054 added prose past the BENCHMARKS/FEATURES budgets

[localai-bot]

scripts/check-public-doc-tables.py exits 1 on origin/main at b493f4981, and it runs in the agent-record CI job (ci.yml:160) and in scripts/agent-preflight.sh:68 and in the pre-push hook. So main is red and every branch inherits it, and every push is blocked.

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

Measured on a clean detached worktree, not the shared checkout.

Which commit, and why it got through

Bisected over the last 12 commits on main, checking out only the two doc files against a fixed checker:

b493f4981 rc=1   fix(ENG-EXPERT-STREAM) (#1035)
0f8580e26 rc=1   feat(SPEC-MTP-K-GT-1) (#1043)
e34d71379 rc=1   fix(qwen3.5): drop redundant AppleClang capture (#1054)   <- introduced
283c7e492 rc=0   record(ORACLE-LLAMACPP-REPIN-STOCK) (#1051)

#1054 added two prose paragraphs to docs/BENCHMARKS.md (:459) and one to docs/FEATURES.md. Its PR body lists its verification: check-doc-checkpoint.py, test_doc_checkpoint.py, check-agent-record.py, test_agent_record.py, git diff --check — check-public-doc-tables.py is not among them, and the contributor states the host had neither CMake nor Clang. It is an external contribution, where CI red is routinely dismissed as a fork artifact (#584 shape), so a real red had good cover to pass unnoticed.

This is NOT the shared-file-budget antipattern

Worth stating, because the reflex is to retire the budget. check-public-doc-tables.py:17 is explicit: "Nothing here budgets the WHOLE FILE. Adding a measurement row must never..." — table ROWS are unbudgeted, only PROSE paragraphs are capped, and :105 repeats that none of the limits bounds the whole file. Adding a measurement (the normal operation) is never blocked. So the gate is behaving as designed and AGENTS.md's "limit an entry, not a shared file" rule is already satisfied.

Do not raise the constants and do not retire the budget. That would be making a red gate green by widening its scope, which AGENTS.md forbids. The content is what is wrong: it was written as prose when the page's contract says content belongs in table ROWS and prose only explains them.

Fix

Move #1054's added content into table rows on both pages, preserving every fact:

• docs/BENCHMARKS.md:459 — "Darwin Qwen3.5 build repair (2026-08-16) ... Benchmarking is NOT APPLICABLE ... the binding gate is the Apple Clang build" is a disposition, exactly what a BENCHMARKS row records. There is a keyed table immediately below (:470).
• docs/FEATURES.md — "the Qwen3.5 MoE loader builds under Apple Clang with warnings promoted to errors; its layout-refusal path uses the same messages and behavior on every platform" is a platform/feature fact belonging in the feature table.

Do not delete the content and do not merge paragraphs together to slip under the count — that games the counter while leaving the page in the shape the contract rejects.

Also worth fixing

The pre-push hook reports this failure and then offers --no-verify, so the first person to hit an inherited red is invited to push past it. That is how a red like this stays alive across many branches.

[localai-bot]

Duplicate of #1055, which was filed at 20:40:03 — 37 minutes before this one — and fixed by #1057 (ef6669292), merged 21:37:36.

check-public-doc-tables.py now exits 0 on origin/main. #1057 folded the two Darwin paragraphs into table rows and left the checker untouched, which is the correct fix and the one this issue argued for.

My PR #1064 is closed as the duplicate. The analysis here — that this is NOT the shared-file-budget antipattern, because check-public-doc-tables.py:17 and :105 state that table ROWS are unbudgeted and only prose is capped, so raising the constants would have been widening a red gate to green — is retained for the record.

[localai-bot]

Correction: the central claim in this issue is WRONG

This issue argued that the paragraph budget is not the shared-file-budget antipattern, citing check-public-doc-tables.py:17 and :105. That is incorrect, and the checker's own source says so directly. Recording it here because a closed issue is still where the next author looks.

Those two lines say ROWS are unbudgeted. They do not say the PAGE is. The PageRules docstring continues:

THAT SENTENCE IS TRUE OF ROWS, AND ONLY OF ROWS. max_h2_sections and max_prose_paragraphs are still whole-page COUNTS, and both live pages sit on the paragraph one: docs/BENCHMARKS.md measures 35 of 35 and docs/FEATURES.md 21 of 21. So adding a PARAGRAPH does still cost somebody's paragraph. That is deliberate rather than overlooked.

So max_prose_paragraphs is a whole-page count and is an instance of the shape AGENTS.md Records rejects ("cap the entry, never the file"). The checker concedes this and defends it as a deliberate trade — rows are the growth mode of a keyed table, prose is the decay mode the gate exists to stop, the same argument #364 used to keep long_paragraphs in STATUS_RATCHET while deleting chars.

#1057, which actually fixed this, got it right where I did not:

A whole-page paragraph count on a shared file is exactly the shape AGENTS.md Records rejects ("Limit an entry, not a shared file"), and ENG-RECORD-CONFLICT-SURFACES already scopes the removal of the doc-gating global counters. This change does not attempt it.

That is the better record: it concedes the antipattern, names the row that owns removing it, and declines to do it inside a red-repair change.

The operational conclusion was unaffected — do not move the constant in a red-repair PR — but it rests on a different and sounder reason than the one given above: raising a budget is a checker-semantics change that owes its own row, spec and red-before test. It does not depend on the antipattern question at all.

Credit to the implementer on #1064 for catching this rather than inheriting my framing. ENG-RECORD-CONFLICT-SURFACES owns the actual removal.