You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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 resolve job: run --fix, and if it produced a diff, fail with the exact sed/patch to apply (the same shape as check-api-reference-citations.sh --fix output). Keeps CI read-only; makes the repair a copy-paste.
B. As a post-merge auto-fix workflow on v5 (like cli-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.
/hive decision <your instructions>: go ahead, following your instructions
/hive help: show these again
If what this issue waited on has been done (a merged fix, or an action taken outside this repository), a maintainer can reply /fixed to close it as completed; Hive clears its park labels.
Approved — narrowed to the cheapest deterministic shape. Option A (amended) only; Option B rejected.
Why approve
This is a real, recurring cost: the same RankActionableIssues citation in src/docs/scale-envelope.md has 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 red relative links and anchors resolve check. The existing tooling does not already cover this: check-docs-citations.py already parses the backticked symbol anchors next to a citation and detects the drift, but --fix only delegates to check-api-reference-citations.sh, which knows route-registration strings in api-reference.md and nothing else. So the gap is exactly "make --fix able 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 v5 adds 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 to v5.
Implementation instructions (binding)
Single PR, no sub-issues. Do not fan this out into tracking issues. One PR against v5, docs + script + tests + changelog fragment together.
Extend the existing --fix path of src/scripts/check-docs-citations.py. No new script, no new workflow, no new required check. Keep the existing delegation to check-api-reference-citations.sh --fix for api-reference.md.
Deterministic re-anchoring only — anchor by Go declaration, not by fuzzy text. A citation is eligible for rewrite only if (a) it already fails the current anchor check and (b) the citing line carries at least one backticked symbol anchor (the existing 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.
Fail closed. If the anchor resolves to zero or more than one declaration, if any anchor is not found inside the resolved declaration span, if the cited file is not .go, or if the citing line has no anchors: leave the citation untouched and report DRIFT exactly as today. --fix must still exit non-zero when anything remains unresolved, matching the api-reference fixer's contract.
CI stays read-only. The only CI change permitted is the error text of the Check src/docs file:line citations step: when it fails, print Run: python3 src/scripts/check-docs-citations.py --fix (same shape as the check-api-reference-citations.sh --fix hint in changelog-fragment-guard.yml). Do not run --fix in CI and diff; do not commit from CI.
Idempotent. Running --fix twice must produce no diff on the second run; the rewritten range must verify clean under the unchanged checker.
Tests in src/scripts/test-check-docs-citations.sh fixtures, 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-.go target → untouched; idempotency.
Fix-agent integration: update the scanner/fix agent's drift playbook (wherever the current "hand-edit the number" guidance lives, e.g. the memory that says to run check-api-reference-citations.sh --fix) to run python3 src/scripts/check-docs-citations.py --fix first and only fall back to a manual edit when it reports unresolved drift.
Changelog fragment under changelog.d/ describing the new --fix capability and its fail-closed rules; update the docstring at the top of check-docs-citations.py which currently says --fix is 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.
🔒 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 /unclaim to release, or /claim to take it over if you outrank the holder.
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).