Repository navigation
ci(guards): the docstring-restatement reach floor is saturated — main sits exactly at the cap, so any PR adding a public symbol goes red #17517
Description
Defect
repo_tests/docstring_restatement_guard_17165_test.py::test_the_sweep_reaches_the_codebase fails on every PR that adds a public symbol, and has nothing to do with the PR that trips it.
ReachFloorError: [docstring-restatement-scan] floor 23000 sits 1001 below its live
population of 24001 named public non-test symbols, which exceeds the declared
allowance of 1000 (skips=0 + growth=1000)
Why it is a base problem, not a PR problem
Measured on current origin/main (9ea37f7cb3) with the CI-parity interpreter:
live public symbols on main: 24000
floor 23_000 + growth 1_000 = cap 24_000 -> at the cap, margin 0
main passes with exactly zero headroom. Any branch adding one public function, method or class reaches 24,001 and fails. That is not a property of the branch — it is the guard being saturated.
Confirmed on two unrelated PRs simultaneously, both red on the same two shards (8/12 and 12/12), both with all review threads cleared:
- fix(phase-validation): 'UI/UX 100%' measured only that files exist (#17089) #17505 — phase-validation work
- fix(deps): check that both declaration planes resolve the same, and let the floor check reach a venv it is not running in (#17448, #17449) #17502 — requirements-plane guard
Neither is defective. Both are the first PRs to arrive after the population reached the cap.
Root cause
declare(...) at :79-85 sets floor=23_000, growth=1_000. The floor has not been re-measured as the codebase grew, so the 1,000 of headroom the comment describes as "roughly the size of a single large feature PR's worth of new public surface" has been consumed to zero by ordinary feature work — exactly as the comment at :74-78 anticipates:
re-measure and ratchet down per
RATCHET_BASELINES.mdif it is ever found loose
It has been found tight, which is the same maintenance in the other direction.
Fix
Ratchet the floor up to the measured live population, keeping the growth allowance:
floor=24_000, # re-measured on 9ea37f7cb3
growth=1_000,Raising a floor tightens the guard — it asserts the sweep reaches at least this many symbols. This is the correct ratchet direction and restores the 1,000-symbol working margin.
Acceptance criteria
-
floorre-measured against currentmainand raised to it; the measurement command and its output recorded in the PR. - fix(phase-validation): 'UI/UX 100%' measured only that files exist (#17089) #17505 and fix(deps): check that both declaration planes resolve the same, and let the floor check reach a venv it is not running in (#17448, #17449) #17502 pass shards 8/12 and 12/12 after rebasing, with no change to either branch.
- The saturation mode is made visible before it blocks anyone: the guard's failure message, or a scheduled check, reports remaining headroom so "0 margin" is observable before the next PR turns red rather than after. A floor whose only symptom is an unrelated PR failing is a floor that reports too late.
Activity
fix(guards): ratchet the docstring-restatement reach floor to its mea…
mrveiss commentedon Sep 29, 2026
This is the clearest statement of a class with five known instances and no owner
Raised to the owner as a scope call rather than filed as a sixth issue. The five:
mainat exactly zero headroomMIN_GUARDS_EXAMINEDsaturated at 132 vs a mutated reach of 132 —assert 132 < 132The shared defect: a reach floor is pinned as an absolute constant against a population that grows, so it saturates, and then it reddens PRs that did nothing wrong. Each has been fixed by its own re-pin, which is the shape the one-defect-one-fix rule warns about — five rediscoveries are five witnesses to one finding, not five repairs.
Two remedies already refuted, recorded so they are not re-proposed (from #17818's dedup):
narrowed < full. No: that asserts the mutated term is load-bearing, but loses the property that the floor itself is tight enough to notice — which is the non-vacuity check on the guard, and the only form that can be expressed against a pinned constant.The shape that survives both, proposed on #17818: assert the window as one invariant —
narrowed < FLOOR <= full— so a stale pin fails with a message naming the window it must sit in, rather than as a bare132 < 132. That converts every future saturation from a puzzle into an instruction, across all five sites.Owner call: whether this issue is promoted to own the class (it is the clearest statement of it), or a new umbrella is created with these five as children. Not filing a sixth issue unilaterally — an umbrella nobody asked for is backlog.
fix(guards): relative reach floors for the two guards that tripped on…
fix(egress): four knowledge connectors go through the egress guard, a…