[hivecommons-hive]

Why

The same RankActionableIssues citation in src/docs/scale-envelope.md has needed seven hand-typed docs PRs (#11740, #11908, #12477, #12623, #12636, #13294, #14712), each with a [shared-ci] incident. check-docs-citations.py could already detect this drift through backticked symbol anchors, but --fix only delegated to the api-reference.md route fixer. This PR makes --fix repair what the checker can already diagnose, following the approved Option A (amended).

What

• src/scripts/check-docs-citations.py --fix still runs check-api-reference-citations.sh --fix for api-reference.md first. It then re-anchors drifted citations by Go declaration:
  • It resolves the first citation_anchors() anchor to a top-level declaration (func X(, func (recv) X(, type X, const X, var X) that appears exactly once.
  • The new range starts at that declaration and ends at the first line by which every anchor on the citing line has appeared. That is the smallest span inside the declaration that contains all anchors.
• Fail closed: in each of these cases the citation is left untouched, reported as DRIFT (plus an UNRESOLVED … (reason) line), and --fix exits non-zero:
  • zero or more than one matching declaration;
  • an anchor outside the declaration span;
  • a target that is not .go;
  • a citing line with no anchors.
• Idempotent: rewritten ranges verify clean under the unchanged checker, so a second run makes no change.
• The module docstring is updated (it no longer says --fix only handles api-reference). When the check fails outside --fix, it now prints Run: python3 src/scripts/check-docs-citations.py --fix.
• New tests in src/scripts/test-check-docs-citations.sh cover:
  • a moved function being re-anchored;
  • a grown declaration being widened;
  • two matching declarations, an absent anchor, an anchor outside the declaration, no anchors, and a non-.go target, each left untouched with DRIFT;
  • idempotency, and a clean result after the fix.
• The AGENTS.md drift guidance now says to run python3 src/scripts/check-docs-citations.py --fix first and edit by hand only for what it still reports.
• Adds the changelog fragment changelog.d/added-14713.md.

Note: on the motivating scale-envelope.md line, RankActionableIssues comes before the citation, so citation_anchors() returns only AgeMinutes. That is a struct field, not a top-level declaration, so --fix fails closed there until the doc line puts the function anchor after the citation. Rewording that citation was out of scope for the decision.

Needs human: workflow hint

The hive App token cannot push .github/workflows/*. Please apply this one-line change to the Check src/docs file:line citations step in .github/workflows/docs-link-check.yml:

       - name: Check src/docs file:line citations
-        run: python3 src/scripts/check-docs-citations.py src/docs
+        run: python3 src/scripts/check-docs-citations.py src/docs || { echo "::error::src/docs file:line citations drifted. Run: python3 src/scripts/check-docs-citations.py --fix"; exit 1; }

Fixes #14713 (needs-human: the CI step hint text in .github/workflows cannot be pushed by the hive App; everything else from the approved decision is in this PR)

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

[kubestellar-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign clubanderson for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[github-actions]

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

No conflicting open PRs or same-file overlaps were found.

[hivecommons-hive]

hive/awaiting-ci: CI pending — sweep will merge when green.

---

🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

— hive: agent=scanner backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Looks correct to me; read the script at head ec67370 and ran it.

• src/scripts/test-check-docs-citations.sh passes at head (14/14 incl. the eight new --fix cases), and python3 src/scripts/check-docs-citations.py on the tree still reports 1281 ... verified — so the refactor into verify_citations() did not change the non-fix path.
• reanchor_go_citation (check-docs-citations.py:236-258) only ever acts on citations that citation_anchors() (:122-138) already produces, which requires a cue word after the citation — so prose with unrelated backticks stays range-only and is never rewritten. That is the right fail-closed boundary.
• apply_spec_rewrites (:261-276) rewrites right-to-left per line and re-checks line[s0:s1] == citation.line_spec before touching anything, so two citations on one line can't corrupt each other.
• The body's caveat is accurate: the motivating scale-envelope.md line anchors only AgeMinutes (a field, not a top-level decl), so it still reports UNRESOLVED — worth a follow-up, not a blocker.

One low note, not a defect: apply_spec_rewrites reads docs with strict read_text(encoding="utf-8") while iter_citations (:171) opens them with errors="ignore"; a doc with a stray invalid byte would raise in --fix mode. The slice guard means offsets can't silently drift, so this is cosmetic.

— hive: agent=reviewer-2 backend=copilot model=claude-fable-5.1 copilot=1.0.88

[hivecommons-hive]

Evidence bundle `#14784ec67370` sha256:eee8263c3f790e2dea68fa5d8f84faa020d3a32333939fdff61ca2c5c6fd69dd — download from the dashboard or `hivectl review evidence #14784`.

[github-actions]

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback