gate-25: the auth lookback is a fixed 20 lines, so it reads the previous method's attribute — and prose

[rubenvdlinde]

check_contract_coverage.py::_method_is_public_endpoint decides whether a controller method is network-facing by regex-searching a fixed 20-line window above the declaration:

def _method_is_public_endpoint(lines, decl_idx):
    start = max(0, decl_idx - 20)
    head = "\n".join(lines[start : decl_idx + 1])
    return bool(_PUBLIC_AUTH_RE.search(head))

The window is not bounded by the previous declaration and does not distinguish an attribute from prose. Two consequences, both live on decidesk development:

1. Neighbour leak — the window reaches into the previous method

SettingsController::setPublicationConfig (declaration L203) is #[AuthorizedAdminSetting(AdminSettings::class)] — admin only. The #[NoAdminRequired] at L183 belongs to getPublicationConfig, the method above it, and L183 is exactly the first line of the 20-line window. Gate-25 reports the admin-only method as a new public endpoint.

2. Prose leak — a sentence about the attribute is read as the attribute

SettingsController::update is admin-only, and its docblock explains precisely that:

* below; it is NOT the #[NoAdminRequired] posture of the read routes.

That sentence, whose whole content is that the method is not NoAdminRequired, makes the gate classify it as public. Same family as .github#358 (gate-19 and gate-26 parse prose) — now in gate-25.

⚠️ The remedy this shape invites is the harmful one. The obvious way to silence #2 is to delete the accurate sentence — degrading documentation to dodge a regex, which is the failure mode x-external-register and x-relation-schema-field were added to gate-54 to avoid.

Direction and blast radius

Ran gate-25's own helper over all 178 public controller methods in decidesk:

• 4 methods classified public with no public marker anywhere in their own docblock or attributes (3 constructors — harmless, they are not routes — plus setPublicationConfig, which is).
• 0 false negatives. A PHP attribute must sit adjacent to its declaration, so the window never falls short; it only over-reaches.

So this over-reports rather than opening a green hole, which is the safe direction — but it means "new public endpoint" is not reliable evidence about a method's auth posture, and an author trusting it could change an endpoint's posture to match the gate.

Suggested fix

Bound the lookback at the previous function declaration rather than at a fixed line count, and mask docblock/comment text before matching (the same _strip_ts_comments / _code_mask idea check_e2e_coverage.py already has, applied to PHP). An attribute is adjacent to its declaration by language rule, so the window can be much tighter than 20 lines.

Found while closing decidesk's four gate-25 findings; two of the four were getPublicationConfig (genuinely public) and setPublicationConfig (this false positive). Both are now covered by a real Newman contract collection regardless, so the finding was still worth acting on.

[rubenvdlinde]

Sequencing note from the gate-fixes wave (2026-08-11). Landed this session, smallest blast radius first, each with a fixture observed red-before / green-after: #366 (the gate-16 fixture #364 shipped without), #368 (gate-7 hasPermission/canAccess, #360), #370 (gate-24 both registration APIs, #349), #371 (gate-61 honest empty-scope reason, #347).

This one was deliberately NOT landed in that wave. The per-issue reason is in the next comment / in fleet-board/findings/github-gate-fixes.md; the common one is that every remaining item either changes what a gate counts rather than what it says, or lives in quality.yml where run-helper-suites.sh cannot reach it — and four gate changes in one session is already the limit at which the next fleet measurement stays attributable.

[rubenvdlinde]

Held, and the suggested remedy has a trap worth naming before anyone implements it.

Half 1 — the neighbour leak — is easy and safe. Bound the lookback at the previous function declaration instead of a fixed 20 lines. An attribute is adjacent to its declaration by language rule, so the window can only ever be too wide, never too narrow.

Half 2 — "mask docblock/comment text before matching" — is NOT the same shape as check_e2e_coverage.py's _strip_ts_comments, and applying it literally would BREAK THE GATE. Two PHP-specific facts turn a false-positive fix into a false-negative hole, which is the strictly worse direction:

1. # is a PHP line-comment character, but #[ opens an ATTRIBUTE. A stripper that treats # as "comment to end of line" deletes every #[PublicPage] / #[NoAdminRequired] in the file. gate-25 would then see no public endpoint anywhere and go permanently, silently green.
2. Docblocks cannot be stripped at all, because _PUBLIC_AUTH_RE matches @PublicPage / @NoAdminRequired — the docblock form is one of the two things it is looking for. Removing docblocks removes half the gate's input.

So the discriminator is not comment-vs-code, it is tag-vs-prose, and it has to be positional: a real docblock tag sits at the start of a docblock line (* @NoAdminRequired), and a real attribute sits at the start of a line modulo whitespace. The SettingsController::update false positive is a sentence containing `#[NoAdminRequired]` in backticks, mid-line — which those two rules exclude without touching anything a compiler would read.

gate-25 has no fixture at all today (no-fixture-yet in UNCOVERED.md), so whoever picks this up should write it first, with a #[PublicPage] arm that must stay detected as the negative control against exactly the hole above. That, plus this issue's own warning that the obvious way to silence half 2 is to delete the accurate docblock sentence, is why it was not rushed into this wave.