docs: cut timed context from the Sphinx prose and root docs (#719)

[JarryShaw]

Please follow the guide below

• Searched for similar pull requests
• Followed the coding style (make pylint, make mypy, make isort)
• make test passes, and a test case covers the change
• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible — N/A — changelog 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?

• fix — corrects a defect
• feat — adds a feature
• perf — changes performance, not behaviour
• refactor — changes neither behaviour nor performance
• test — tests only
• docs — documentation only
• ci — workflows or build tooling
• chore — anything else

---

Description of your pull request and other information

First slice of #719, which asks for a prose sweep for concision and the removal of timed context. This takes the objectively testable half — a sentence naming when something changed, or which issue changed it, either is or is not there — across docs/source/**/*.rst and the root documents. 15 files, +59/−80.

What came out, about 20 statements: until GitHub issue #911 moved all four definitions here; they used to read .../-02.html, which is dead: measured 2026-09-19 as a 404; was deleted from the Wikipedia article on 2026-08-25; Since #617, building a protocol; one doc-only commit since 1.3.0 … open and uncommented since May 2024.

What stayed, deliberately. Version-bounded prose is contract rather than history, so .. deprecated:: directives, the Python-version tables, "requires Python 3.11 or older until 0.12.1 is published" and "upstream is unmaintained, the cap is not expected to lift" are all untouched. Every design decision stayed too, reframed from past tense to present where the tense was the only thing dating it — why gap is not derived from hdl, the RFC 791 versus TCP conflict-resolution rule, why PCAP-NG revision -03, why no IPX LINK.

One reframe worth reading closely. The v*-tag warning:: in releasing.rst was entirely a narrative about #888, and also the only thing stopping someone reinstating the shared PCAPKIT_TAG_EXISTS check that caused releases to skip silently and finish green. Cutting it would have removed a guard rail; it is now stated as the hazard rather than as the incident, keeping the cross-reference to the section that prevents it.

Two corrections I made to the sweep before committing it. A rewrite in sentinels.rst said the sentinel types are "re-exported from their original modules", which inverts the direction — they are defined in pcapkit.corekit.sentinels and re-exported by the old modules. Verified by NullType.__module__ and an identity check, then reworded. And my own first attempt at that fix introduced "used to live beside", which is the very thing this slice removes.

Out of scope and untouched: CHANGELOG.md (generated by util/changelog_md.py), docs/source/changelog/, and the five contributing/conventions/ pages rewritten under #948/#949/#951/#952.

pytest tests/project tests/corekit/test_sentinel_exports_unit.py: 246 passed, 1 skipped, 697 subtests, 0 failed. That second file is included because it reads a convention page and is what a previous slice of this programme broke.

Not the whole of #719. docs/source/pcapkit/** is ~140 files and only 13 were touched; contributing/pep.rst needs a closer read to separate real citations from narrative; demo.rst and contributing/testing.rst are untouched. Remaining directories are worth their own slices.

[JarryShaw]

GOOD TO GO at 55f12f686 — fable cross-review. Head has since advanced to e45d31260, which fixes the two prose nits the review itself named and changes nothing else; reasoning below.

Third model on this slice (written by sonnet, edited by me, reviewed by fable). It confirmed the parts that mattered, each independently derived:

• Nothing but timed context came out. Every removed passage names an issue, a date, or a past state. The design rationale all survives and was checked against HEAD^ individually — gap-not-from-hdl, the RFC 791 versus TCP first-write-wins contrast, PCAP-NG -03, the IPX closed registry, both ext.rst keyword rationales.
• The releasing.rst reframe holds. It judged the new warning states the rule, the mechanism and the observable failure, and that a maintainer could not reasonably overrule it as a bare instruction. The `Each job past version_check…`_ reference resolves; the line-287 instance outside this diff proves the markup-stripped implicit target works on this exact page.
• Sentinels verified by execution, not by reading: NullType.__module__ == 'pcapkit.corekit.sentinels', and module.NullType is sentinels.NullType plus the same for NULL, NoValueType/NO_VALUE, NoDefaultType/NO_DEFAULT — all identity-true, so the "respectively" mapping is right.
• Tests re-derived both ways: 246 passed / 697 subtests under pytest, and plain unittest at 228 + 19 = 247 = 246 + 1 skipped, so no subtest undercount is hiding a failure.

Two prose nits it raised, both real, both now fixed at e45d31260:

• vendor/pcapng.rst read "the ids the three crawlers select on first exist only in -03" — garbled, because my slice dropped a clause around it. Now "exist only in -03, where the registries are real tables".
• The sentinels.rst note said the types are "documented below instead", whose antecedent went with the removed history. Now "documented below and explicitly marked private".

One finding I am deliberately not acting on here, and tracking instead. It found leftover timed context in two files this slice did edit: releasing.rst still has "Until #888, every job past version_check shared one guard", "had their reviewers removed on #887", and "the shape #888 was actually about"; workflows.rst still has the heading "The skip cascade (#888)" and "originally-named 22 contexts". These are in #719's scope. I left them because renaming a section heading risks the references that point at it, and widening a slice after its review is how a clean diff becomes an unreviewed one. They go in the next slice.

Why the verdict carries to e45d31260: the only delta is those two sentences, both specified by the review itself, with the full suite re-run at 246 passed / 1 skipped / 697 subtests. Unpublished and yours to merge.

[JarryShaw]

GOOD TO GO at 7c6b8a681 — opus cross-review, scoped to the merge rather than the content.

The head moved because the branch took a merge commit, parents e45d31260 and e87c4b00c, so the earlier verdict no longer tracked it. I verified the content is unchanged before relabelling, and the review re-derived both claims independently:

• git diff e45d31260 7c6b8a681 -- over this PR's 15 files prints nothing.
• git diff --stat e87c4b00c...7c6b8a681 is still 15 files, +59/−80.

It added a check I had not thought of: git merge-base e87c4b00c 7c6b8a681 returns e87c4b00c itself, so main is an ancestor and the two-dot and three-dot diffs are identical. That is positive proof the merge reverted none of main's content — conflict-free status alone does not give you that.

On the real hazard, that a clean merge can still break the docs, the structural result settles most of it: across all 19 files on both sides of the merge, not one named anchor, substitution definition or section-title underline was added or removed, so the reference graph is byte-identical to main's. It then enumerated the cross-boundary references both ways. The one worth naming is releasing.rst:90, which quotes pep.rst verbatim — "version-driven rather than tag-driven" — and #955 rewrote that file heavily. The string survives, moved from :893 to :847.

It also found a genuine factual error, and correctly charged it to neither this PR nor the merge. pep.rst:861 claims all four publishing jobs are gated on PCAPKIT_TAG_EXISTS; I confirmed against create-release.yml on main that only github is (:343), while tag, pypi and conda gate on their own artefact and say so in comments at :437, :511, :610. It predates this PR and sits outside its 15 files — a leftover my own #955 slice read past. Filing it separately.

Labelled review: good-to-go. CI is at 57 ok / 0 fail / 1 inc, so not ready to merge yet — and the merge is yours either way.