Repository navigation
[scanner] Gate proposal: auto-re-anchor drifted src/docs line-range citations #14713
Description
Class
Line-range citations in src/docs/*.md that point into frequently edited Go files drift every time the cited function moves, turning the required relative links and anchors resolve check red on the default branch and on every open PR until someone hand-edits a number.
Prior instances (same root cause, same site)
- docs: fix drifted scale-envelope citation failing link check fleet-wide [scanner] #9389 —
scale-envelope.mdcitation intoclient.godrifted, fleet-wide red - 📖 docs: refresh scale-envelope client.go citation (v5 docs-citation check red) #11740 — same citation drifted again, v5 red
- [shared-ci] relative links and anchors resolve failing across hivecommons/hive #14711 / 📖 docs: re-anchor the RankActionableIssues citation in scale-envelope.md #14712 — same citation drifted a third time after 🐛 dashboard: anchor tracker rows on the open PR when the issue has closed #14657 grew
RankActionableIssues
Each one was a one-line docs PR plus a [shared-ci] incident, a stamped comment on every affected PR, and a kick cycle of lost merges.
Missing gate
src/scripts/check-docs-citations.py already parses the backticked symbol anchors next to each citation (RankActionableIssues, AgeMinutes), but --fix only delegates to the older api-reference.md fixer. Proposal: teach --fix to re-anchor any citation whose anchors are found elsewhere in the target file (move/widen the range to the span that contains every anchor), and run it in one of two places:
- A. In the existing
relative links and anchors resolvejob: run--fix, and if it produced a diff, fail with the exactsed/patch to apply (the same shape ascheck-api-reference-citations.sh --fixoutput). Keeps CI read-only; makes the repair a copy-paste. - B. As a post-merge auto-fix workflow on
v5(likecli-pin-bump): run--fix, open a signed docs PR when the default branch drifts, so PRs are never red for a base-branch citation.
Either keeps the check as the verdict; the difference is who types the number.
Decision taken by hive: none yet — this changes what CI is allowed to rewrite, so it is parked for a maintainer accept/decline.
Risk: governance
— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88
Activity
hivecommons-hive commentedon Oct 27, 2026
What to reply
/hive approve: go with the recommendation/hive decision <your instructions>: go ahead, following your instructions/hive help: show these againIf what this issue waited on has been done (a merged fix, or an action taken outside this repository), a maintainer can reply
/fixedto close it as completed; Hive clears its park labels.Only a maintainer with write access can un-park; everything else is ignored. Full command reference: https://github.com/hivecommons/hive/blob/v5/src/docs/maintainer-commands.md.
clubanderson commentedon Oct 28, 2026
/hive decision approve
Approved — narrowed to the cheapest deterministic shape. Option A (amended) only; Option B rejected.
Why approve
This is a real, recurring cost: the same
RankActionableIssuescitation insrc/docs/scale-envelope.mdhas now needed seven hand-typed docs PRs (#11740, #11908, #12477, #12623, #12636, #13294, #14712), each one paired with a[shared-ci]incident and a fleet-wide redrelative links and anchors resolvecheck. The existing tooling does not already cover this:check-docs-citations.pyalready parses the backticked symbol anchors next to a citation and detects the drift, but--fixonly delegates tocheck-api-reference-citations.sh, which knows route-registration strings inapi-reference.mdand nothing else. So the gap is exactly "make--fixable to repair what the checker can already diagnose". That is self-healing, needs no baseline file, and adds no new CI surface.Why Option B is rejected
A post-merge auto-fix workflow on
v5adds a new workflow with write permissions, generates bot PRs, and still leaves the default branch red for a full cycle between the breaking merge and the fix PR landing. CI must stay read-only on docs; the repair belongs in the PR that caused the drift (or in the fix agent's loop), not in a robot committing tov5.Implementation instructions (binding)
v5, docs + script + tests + changelog fragment together.--fixpath ofsrc/scripts/check-docs-citations.py. No new script, no new workflow, no new required check. Keep the existing delegation tocheck-api-reference-citations.sh --fixforapi-reference.md.citation_anchors()output). Resolve the first anchor to a top-level Go declaration in the cited file (func X(,func (recv) X(,type X,const X,var X) found exactly once. New range = that declaration's start line through its closing brace / end of declaration, narrowed to the smallest span that contains every anchor on the citing line. Do not search by substring across the file for the new range..go, or if the citing line has no anchors: leave the citation untouched and reportDRIFTexactly as today.--fixmust still exit non-zero when anything remains unresolved, matching the api-reference fixer's contract.Check src/docs file:line citationsstep: when it fails, printRun: python3 src/scripts/check-docs-citations.py --fix(same shape as thecheck-api-reference-citations.sh --fixhint inchangelog-fragment-guard.yml). Do not run--fixin CI and diff; do not commit from CI.--fixtwice must produce no diff on the second run; the rewritten range must verify clean under the unchanged checker.src/scripts/test-check-docs-citations.shfixtures, covering at minimum: function moved → re-anchored; function moved and grew so an anchor fell outside → widened; two declarations match the anchor → untouched + DRIFT; anchor absent from the file → untouched + DRIFT; citation with no anchors → untouched; non-.gotarget → untouched; idempotency.check-api-reference-citations.sh --fix) to runpython3 src/scripts/check-docs-citations.py --fixfirst and only fall back to a manual edit when it reports unresolved drift.changelog.d/describing the new--fixcapability and its fail-closed rules; update the docstring at the top ofcheck-docs-citations.pywhich currently says--fixis api-reference-only.Out of scope for this PR: changing which files cite line ranges, adding anchors to citations that currently lack them, and any post-merge auto-commit workflow.
hivecommons-hive commentedon Oct 28, 2026
Un-parked by @clubanderson. Decision: approve
stage/045-needs-decisionis cleared when present andapproved-directionis applied; anyholdlabel is left exactly as it was.hivecommons-hive commentedon Oct 28, 2026
🔒 Claimed by agent
scanner(agent on hive hosted-available-oke-11-placeholder-r05x). The claim lasts 2h0m0s without activity and renews while the work continues. Reply/unclaimto release, or/claimto take it over if you outrank the holder.hivecommons-hive commentedon Oct 28, 2026
🔓 Claim by agent
scannerreleased (holding agent relaunched).