[JarryShaw]

• Searched for similar pull requests
• Followed the coding style
• make test passes, and a test case covers the change
• 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

Part of #1103 round 5. This is the non-API docs slice, and it also converts issue/PR reference syntax across the repo, as the owner asked on #1103. Base is main 4c3d30163.

• Roles: 134 references now use :issue:/:pr:, in Sphinx-rendered text only.
  • workflows.rst 85, releasing.rst 24, pep.rst 4, and 21 in pcapkit/ docstrings and #: comments.
  • Plain # comments keep #NNN. Links to Discussions and to other repos keep their URLs.
  • Each number was checked against the API. refactor(util): share one stdlib-only Actions helper across the CI scripts (#2047) #2050 is a PR, not an issue.
• New check: tests/project/test_docs_issue_pr_roles_1103_unit.py.
  • It flags hand-written GitHub issue/PR links and bare #NNN in rendered text.
  • It skips literals, code blocks, comments, doctests and roles.
  • On main it finds 131 violations beyond the 8 allowlisted entries, 139 in all; here it finds only the allowlisted ones.
  • The rule is written down in conventions/documentation.rst.
• Allowlisted for now: about 9 references stay hand-written because other tests pin their exact text. ci(experimental): skip or stop superseded runs instead of cancelling them, so commits are not marked red #1938, ci: Python 3.14t and GraalPy experimental legs produce no JUnit XML #2073, ci: Containment summary reports a superseded stop as 'tests exited 0' #2077, ci(python): GraalPy's unit tier stops on an xdist worker MemoryError under the 2 GiB per-process heap #1753, ci: stop repeating text-only PR pin tests on every main unit leg #1954, test: sort the remaining GraalPy-only failures into defects and gates #1963, ci: PyPy workers on the ALL tier grow until they are OOM-killed #2005 and (#1962) each have a reason in the allowlist. A follow-up changes those pins and drops the entries together.
• Stale claims and anchors:
  • process.rst: the shared changelog PR merged on 2026-10-01, and Lint's import-error expectation.
  • workflows.rst: the script table now covers experimental.yml's windows job.
  • pep.rst: pypcapfile fails from 3.12 up.
  • index.rst: cryptography isn't pure Python.
  • Citations into third-party actions and the runner now name functions, not lines.
  • A typo in an ext.rst sample.
• Build: pinned docs venv with sphinx-autodoc-typehints 3.17.2. 0 warnings without -n; with -n, the same 116 as main, all on API pages.
• Tests: the docs tests, the tests that read the changed pages, and the new check pass (160). Isort and the tier guard pass (134). The AST guard is OK on all 10 .py files.

[JarryShaw]

GOOD TO GO at 3dcd2f3f1 (Sonnet review).

• Roles: all 66 distinct numbers added in the diff were checked with the API, and every role matches. The four PRs (2023, 2037, 2038, 2050) use :pr:.
• Placement: every changed .py line is a docstring or a #: comment. No conversion landed in a plain # comment, YAML, a test or a code block.
• Check test: it fails on main and passes here. ScannerTests covers the exclusions: literals, code blocks, comments, Discussions and other-repo links, doctests. All 8 allowlist entries have true reasons, each one a real pin in another test, and a stale-entry test keeps each entry honest. It sets __tier__ = 'LATEST'.
• Count corrected: the PR body said 142 violations on main. I re-ran the check on a clean main tree: it finds 131 beyond the 8 allowlisted entries, 139 in all. The body now says so.
• Prose claims:
  • docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657 merged 2026-10-01.
  • Lint expects pylint's import-error.
  • experimental.yml's windows job runs leg_summary.py and pip_install.py.
  • pypcapfile is gated < '3.12'.
  • The named runner and action functions exist.
• Checks: the AST guard is OK on all 10 pcapkit/ files. 46 test files: 633 passed.

[github-actions]

Coverage: 91.55% (unit tier, Python 3.15, 3dcd2f3f1, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	4	20	2	95.16%
pcapkit/const	19599	880	2618	866	92.12%
pcapkit/corekit	2589	75	816	37	96.48%
pcapkit/dumpkit	282	3	102	3	98.44%
pcapkit/foundation	2971	23	1036	25	98.80%
pcapkit/interface	138	4	52	3	96.32%
pcapkit/protocols	17418	219	4574	185	98.14%
pcapkit/toolkit	869	36	298	10	95.20%
pcapkit/utilities	504	7	146	5	98.15%
pcapkit/vendor	4432	1988	1018	167	51.87%

Per-file detail: the coverage-html artifact of this run.

[JarryShaw]

Ready to merge at 3dcd2f3f1.

• Review: Sonnet GOOD TO GO. All 66 distinct role numbers were checked against the API, and every allowlist entry is a real pin in another test.
• CI: 61 CheckRuns passed, 0 failed, 0 pending. Required checks passed is SUCCESS, and the KTLO legs show no warnings.
• Ordering: I merged this PR into main and ran tests/project plus the root modules under the plain unittest ordering leg: 2297 tests, with the new check included, 0 failures, 0 errors.
• Merge order: this PR conflicts with docs(foundation): fifth whole-repo pass over foundation, toolkit, dumpkit, interface and utilities (#1103) #2157 in pcapkit/foundation/engines/pcapng.py; a test merge found it. Whichever of the two merges second needs a rebase, and I'll do that as soon as the first one lands.

[JarryShaw]

Rebased onto main after #2157 merged: 3dcd2f3f1 → ac32f4281.

• Conflict: one docstring sentence in PCAPNG._block_name (pcapkit/foundation/engines/pcapng.py) that both PRs reworded. I kept this PR's :issue: role and docs(foundation): fifth whole-repo pass over foundation, toolkit, dumpkit, interface and utilities (#1103) #2157's timeless ending ("the two counts agree").
• Everything else is unchanged; git range-diff shows only that hunk.
• Tests: the roles test, tests/foundation/engines and the docstring contract pass on the new head (194).
• Old head: Required checks passed SUCCESS.

The patch changed in that hunk, so CI runs again. A short delta check is running.

[JarryShaw]

Review: GOOD TO GO at ac32f4281 (Sonnet): rebase check: range-diff differs only in the merged _block_name hunk, the "two counts agree" claim matches the per-kind whole-file counter, and the roles, engines and docstring-contract tests pass.

[JarryShaw]

Ready to merge at ac32f4281. Part of #1103 (round 5).

• Review: Sonnet GOOD TO GO.
• CI: Required checks passed SUCCESS, 0 failed. Still open: the board's Sync Status.
• KTLO: 12 legs, no warnings.
• Ordering: project leg merged into main: 2299 tests, 0 failures.