Filed unassigned by the os-dev seat working #9294 (session session_01XqDQYVU5smx29ts9pAErja). Observation, not a defect with a repro — recording it because the asymmetry is invisible from the outside.
What
scripts/docs-audit/affected-docs.mjs narrows the symbol set three times before the route bridge runs, and publishes only one of the three:
| narrowing |
kind |
published? |
rendered in the PR comment? |
MAX_ROUTES_PER_SYMBOL cap |
per-run, measured |
yes, crossCuttingSymbols |
yes |
SCREAMING_SNAKE constants |
structural, by kind |
no |
no |
| container declarations (added by #9431 / #9294) |
structural, by kind |
no |
no |
The file is otherwise emphatic that a narrowing must be readable: "Both guards run BEFORE the bridge... and BOTH publish what they removed", and "Silence from this tool must never be readable as 'there is nothing there'". weakAnchorsDropped, overbroadAnchors, anchorlessChanges, unmappedCommandFiles and unanchoredRuleBlocks all exist for that reason.
The two kind rules are the exception, and the second one was added following the precedent of the first.
Why it is only an observation
Neither rule can remove a doc anchor — both operate purely on bridge eligibility, and both are structural rather than data-dependent, so a reader who knows the rule can predict the outcome without a report. That is a real difference from the cap, which fires on a per-run count nobody can predict. So the case for publishing is consistency and reviewability, not a measured miss: nothing is known to have been silently lost through either.
The failure direction if one of them is ever wrong is a recall miss on the route and sdk kinds, and today nothing would say so.
Cost, which is why #9294 left it
The publication would need a new JSON field and a render branch in .github/workflows/docs-drift-check.yml — the drift comment reads a fixed list of fields (overbroadAnchors, crossCuttingSymbols, weakAnchorsDropped, anchorlessChanges, packageMentionDocs) and would ignore an unrendered key, leaving a half-wired field that reads as published but is not. That is two files, and #9294's file surface was one.
Widening crossCuttingSymbols to mean "symbols kept out of the bridge, with why" was considered and not done: the entries are already self-describing (sendError (6 routes)), so RestServer (container) would slot in cleanly, but the JSON key would then be a misnomer and renaming it breaks the workflow's reader.
Suggested shape, if it is ever taken
One field carrying all three with their reasons, one render branch, and the existing crossCuttingSymbols key kept as an alias for one release so the workflow never reads undefined. Decide first whether the consistency is worth two files touching a script that has had three cards queued on it in a week (#9294, #9331, #9432).
Refs: #9294, #9431, #9432, #9192.
Generated by Claude Code
Filed unassigned by the
os-devseat working #9294 (sessionsession_01XqDQYVU5smx29ts9pAErja). Observation, not a defect with a repro — recording it because the asymmetry is invisible from the outside.What
scripts/docs-audit/affected-docs.mjsnarrows the symbol set three times before the route bridge runs, and publishes only one of the three:MAX_ROUTES_PER_SYMBOLcapcrossCuttingSymbolsSCREAMING_SNAKEconstantsThe file is otherwise emphatic that a narrowing must be readable: "Both guards run BEFORE the bridge... and BOTH publish what they removed", and "Silence from this tool must never be readable as 'there is nothing there'".
weakAnchorsDropped,overbroadAnchors,anchorlessChanges,unmappedCommandFilesandunanchoredRuleBlocksall exist for that reason.The two kind rules are the exception, and the second one was added following the precedent of the first.
Why it is only an observation
Neither rule can remove a doc anchor — both operate purely on bridge eligibility, and both are structural rather than data-dependent, so a reader who knows the rule can predict the outcome without a report. That is a real difference from the cap, which fires on a per-run count nobody can predict. So the case for publishing is consistency and reviewability, not a measured miss: nothing is known to have been silently lost through either.
The failure direction if one of them is ever wrong is a recall miss on the
routeandsdkkinds, and today nothing would say so.Cost, which is why #9294 left it
The publication would need a new JSON field and a render branch in
.github/workflows/docs-drift-check.yml— the drift comment reads a fixed list of fields (overbroadAnchors,crossCuttingSymbols,weakAnchorsDropped,anchorlessChanges,packageMentionDocs) and would ignore an unrendered key, leaving a half-wired field that reads as published but is not. That is two files, and #9294's file surface was one.Widening
crossCuttingSymbolsto mean "symbols kept out of the bridge, with why" was considered and not done: the entries are already self-describing (sendError (6 routes)), soRestServer (container)would slot in cleanly, but the JSON key would then be a misnomer and renaming it breaks the workflow's reader.Suggested shape, if it is ever taken
One field carrying all three with their reasons, one render branch, and the existing
crossCuttingSymbolskey kept as an alias for one release so the workflow never readsundefined. Decide first whether the consistency is worth two files touching a script that has had three cards queued on it in a week (#9294, #9331, #9432).Refs: #9294, #9431, #9432, #9192.
Generated by Claude Code