fix(guards): ratchet the docstring-restatement reach floor to its measured population (#17517)

[mrveiss]

Thinking Path

Two unrelated PRs (#17505, #17502) went red on the same two shards immediately after their authors cleared every review thread. Same shards, same test, different work — that is a shared-cause signature, so I measured before anyone started debugging their own branch.

repo_tests/docstring_restatement_guard_17165_test.py::test_the_sweep_reaches_the_codebase
ReachFloorError: [docstring-restatement-scan] floor 23000 sits 1001 below its live
population of 24001 named public non-test symbols, exceeding the allowance of 1000

Measured on 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. Neither PR was defective; they were the first two to arrive after the population saturated the guard.

The declaration's own note at :74-78 anticipates this maintenance — "re-measure and ratchet down per RATCHET_BASELINES.md if it is ever found loose". It has been found tight, which is the same re-measurement in the other direction.

What Changed

repo_tests/docstring_restatement_guard_17165_test.py — floor ratcheted 23_000 → 24_000, the measured live population, with growth=1_000 unchanged so the working margin is restored.

Raising a floor tightens this guard: it asserts the sweep reaches at least this many symbols, so a future regression that silently narrows discovery still trips. This is the correct ratchet direction and is not a relaxation.

Verification

• Measured, not guessed: len(_public_symbols(REPO_ROOT)) on 9ea37f7cb3 = 24000. _public_symbols is AST-based over tracked_paths(root, "*.py"), so the count is of the tree, not of an import graph.
• Guard re-run on this branch: 6 passed, 1 warning in 13.84s.
• Run on the CI-parity interpreter (~/.venv-python-suite, Python 3.14.6 / pytest 9.1.1), not the shell default 3.10.12 — that distinction cost a day elsewhere (bug(hooks): pre-push announces a 132s pytest budget and enforces 200s — the printed value is the vitest one #17409).
• Pre-push hook ran in full; no bypass.

Single-issue rationale

A ratchet baseline is a hub file, explicitly exempt from the same-file batching rule, and it shares no reviewer surface with any open PR. It also must land alone and first: #17505 and #17502 are both blocked behind it and rebase onto it.

Follow-up left open, deliberately

#17517's third acceptance criterion is not addressed here: the guard's only symptom of saturation was an unrelated PR turning red. There was no signal at margin 0 — no warning, no headroom in the pass output — so margin-zero and margin-plenty are indistinguishable until someone else pays for it. Reporting remaining headroom belongs in a separate change; raising the floor buys ~1,000 symbols and does not fix the blindness.

Refs #17517

Model Used

Claude Opus 5 (1M context)

[coderabbitai]

Warning

Review limit reached

Next included review available in 27 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Repository: mrveiss/AutoBot-AI/.coderabbit.yaml

Review profile: ASSERTIVE

Plan: Advanced

Run ID: ef71cd5b-f31a-4bd3-83fb-1ddcd8a1fdd9

📥 Commits

Reviewing files that changed from the base of the PR and between 424a65f and b5da249.

📒 Files selected for processing (1)

• repo_tests/docstring_restatement_guard_17165_test.py

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ SSOT Configuration Compliance: Passing

🎉 No new hardcoded values of either class — ssot and other both block.

Known backlog in pipeline-scripts/hardcoded_values_baseline.txt is suppressed and tracked in #14371.