docs(foundation): convert bare citations to the issue role in docstrings

[JarryShaw]

Please follow the guide below

• Searched for similar pull requests
• Followed the coding style
• make test passes, and a test case covers the change — docstring-only, so no test change, matching docs(corekit): convert bare citations to the issue role in corekit docstrings #1000
• Added a changelog entry — N/A, centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

• docs — documentation only

---

Description of your pull request and other information

Third tranche of #989. Converts bare #NNN citations under foundation, utilities, toolkit and dumpkit to :issue: roles, continuing #1000's corekit pass.

Scope follows the ruling on #989: plain # comments keep the bare form (GitHub's code view links them; reST roles would render literally), so only docstrings, other string literals and #: autodoc doc-comments convert.

Tokenised by token kind, base e8a60d153 → head:

	base	head
bare in strings	28	0
bare in #: doc-comments	4	0
bare in plain # comments	24	24, untouched
:issue: roles	0	33
explicit issues/NNN hyperlinks	1	0

33 roles from 32 bare sites plus the one explicit hyperlink in utilities/decorators.py. All 18 distinct numbers resolve to issues, not pull requests, so :issue: is correct at every site. DictDumper#125 in dumpkit/common.py is left alone — it cites another repository.

Rendered text is unchanged: the :issue: caption is #%s. Docs build stays at 61 warnings, same WARNING/ERROR lines, including the two pre-existing docutils errors.

[JarryShaw]

GOOD TO GO at 277dc685e — opus cross-review, a different model from the sonnet agent that wrote the diff, briefed to falsify. It changed nothing in the diff and found no defect. What it corrected was the narrative, in two places worth recording:

• Plain-comment citations are 25 under the reviewer's convention, 24 under mine — the difference is JarryShaw/DictDumper#125 at pcapkit/dumpkit/common.py:240, a cross-repo reference this PR deliberately leaves alone. Either way the invariant is stronger than a count match: every plain # comment token is byte-identical base-vs-head.
• My note that the 7 local test failures were "invisible to CI" was wrong in its reason. tests/dumpkit/test_plist_escaping_regression.py and tests/foundation/reassembly/test_tcp_runtime.py are both in tests._tiers.fixture_tier_paths() (measured on main: 19 entries, both present), which the Integration and parity jobs run. They are invisible to the unit matrix only. The conclusion held — all 5 Integration legs and both parity legs are green here, so the local failures were purely a fresh worktree without generated captures.

The strongest evidence came from the review rather than from the PR: ast.dump with every docstring blanked is identical base-vs-head in all 9 files, which I re-derived independently. All 33 roles sit in docstring-position literals, none in a runtime string, none inside a doctest or .. code-block::. The change provably cannot alter behaviour, which is why no test accompanies it.

Also confirmed independently: 18 distinct cited numbers, every one an issue and none a pull request — including the four with commit-style titles (#832, #833, #886, #923) that look like PRs and are not.

Not yet ready to merge: 6 CheckRun legs still in flight, 0 failures so far.

[JarryShaw]

Ready to merge at 277dc685e — closing the "not yet" on the verdict above. CI is complete: 69 CheckRun legs green, 3 skipped, 0 failures, 0 in flight, and mergeStateStatus is CLEAN. The opus cross-review verdict stands at this head; nothing has been pushed since.

Unpublished changes on my side: none. Yours to merge.