docs(contributing): cut the contributing pages and repair drifted line references

docs/source/contributing/conventions/documentation.rst

@@ -29,41 +29,38 @@ and ``to`` stay lowercase unless they lead, which was the reading put to the own
 *Issue and Pull Request Labels* on :ref:`process` are both in it.
 
 **The casing is the easy half.** A heading can be in Title Case already and still
-break the rule by being a clause rather than a title. The sweep of
-:file:`docs/source/contributing/` under this ruling found, of 62 headings, 24 already
-right, 16 needing only re-casing, and **22 to be rewritten**. *What a Failed Lookup
-Raises* was correctly cased and is now *Failed-Lookup Exceptions*.
+break the rule by being a clause rather than a title: *What a Failed Lookup Raises* was
+correctly cased and is now *Failed-Lookup Exceptions*. Of the 62 headings under
+:file:`docs/source/contributing/` when this was ruled, 22 needed rewriting and 16 only
+re-casing.
 
-The line that sweep drew, and the one to keep drawing: a **finite verb** makes a heading
-a sentence and earns a rewrite, while a gerund or infinitive phrase is a noun phrase and
-needs only re-casing -- so *Running the tests* became *Running the Tests* rather than
-being reworded.
+The line to draw: a **finite verb** makes a heading a sentence and earns a rewrite,
+while a gerund or infinitive phrase is a noun phrase and needs only re-casing -- so
+*Running the tests* becomes *Running the Tests* rather than being reworded.
 
 .. note::
 
    A heading also has to describe the section beneath it, and a rewrite is the moment
-   to check that. Two of that sweep's own new titles were renamed again in review for
-   failing it. *One Approval, Whole Release* became *The Release Pipeline* because the
-   section opens on a Mermaid flowchart while the approval prose it had been named for
-   sat well below, leaving the page's most navigable artefact unfindable from the table
-   of contents.
+   to check that. *One Approval, Whole Release* was renamed *The Release Pipeline*
+   because the section opens on a Mermaid flowchart while the approval prose it had
+   been named for sat well below, leaving the page's most navigable artefact
+   unfindable from the table of contents.
 
 Renaming a Heading
 ~~~~~~~~~~~~~~~~~~
 
-Two mechanical traps, both of which bit on that sweep rather than being hypothetical.
+Two mechanical traps, both of which have bitten rather than being hypothetical.
 
 **Re-measure the underline against the new text.** A case flip usually keeps the
 length; a rewrite almost never does, and docutils reports an underline shorter than
-its heading in a build that does not fail on warnings. The sweep re-checked all 62 and
-found none short, which is the standard to hold.
+its heading in a build that does not fail on warnings. Re-check every heading; none
+of the 62 was short.
 
 **A heading is a link target, so a rename is a repository-wide sweep** rather than a
 :file:`docs/source/` one. In scope: ``.rst`` prose, ``:ref:`` and ``:doc:`` link text,
 toctree entries, implicit ``` `Text`_ ``` references, **and** :mod:`pcapkit` docstrings
-and the files under :file:`tests/`. Applying that scope to the heading rename took two
-passes: the first reported one surviving stale reference; review found **five**, spread
-across :file:`pcapkit/corekit/sentinels.py`,
+and the files under :file:`tests/`. A heading rename once left **five** stale
+references, spread across :file:`pcapkit/corekit/sentinels.py`,
 :file:`tests/corekit/test_sentinel_exports_unit.py` and
 :file:`tests/project/test_conventions_doc_claims.py`. The first of those is a shipped
 module docstring that renders into the API reference, so a reader following it searches
@@ -73,9 +70,8 @@ the page for a string no longer on it.
 
    **Derive the list of old headings from the pre-change file, not from the diff.** A
    diff-derived list silently drops any heading whose underline is not adjacent in the
-   hunk, which is why the second pass undercounted as well as the first. What
-   worked was a whitespace-flattened search for every pre-change heading string across
-   every tracked file.
+   hunk. A whitespace-flattened search for every pre-change heading string across
+   every tracked file is what works.
 
 Nothing in CI catches a reference a rename left behind. :file:`docs/source/conf.py`
 sets no ``nitpicky`` and :file:`docs/Makefile` leaves ``SPHINXOPTS`` empty, so the
@@ -121,7 +117,7 @@ type hierarchy. **Quote a node label whose text Mermaid would otherwise try to p
 and leave a bare identifier bare. That is what the exemplars do with *node* labels, and
 it falls close to the ``TD``/``LR`` line without following it: every node label in the
 six ``TD`` graphs is quoted, since every one of them is prose; the ``LR`` graphs quote
-only where the text forces it, which today is ``h1["HTTP/1.*"]`` and ``h2["HTTP/2"]`` in
+only where the text forces it, which is ``h1["HTTP/1.*"]`` and ``h2["HTTP/2"]`` in
 :file:`docs/source/pcapkit/protocols/index.rst` and nowhere else. Everything else there
 uses the bare ``A{{Meta}}``, ``B(Base)``, ``D([user customisation ...])`` and
 ``subgraph name [Title]`` forms, and spends its quotes on ``click`` targets instead.
@@ -170,7 +166,7 @@ is the duplication the owner ruled out on :issue:`719`.
    For the same reason, do not add an inline ``.. contents::`` to a page. The ``furo``
    theme already renders a sticky page-local table of contents on every page, so an
    inline directive is a second copy of it; the one in :file:`docs/source/index.rst`
-   has been commented out since 2023 and should stay that way.
+   is commented out and should stay that way.
 
    One setting there was decided by measurement rather than by preference:
    ``toc_object_entries`` carries, in a comment beside it, the figures that settled it,
@@ -292,7 +288,7 @@ Format and Mechanics
 
 *  **reStructuredText under** :file:`docs/source/`, **Markdown outside it.** The owner
    ruled this on :issue:`719`, correcting a blanket *always* ``.rst`` that had been in
-   circulation until then: the Sphinx documentation is reST, and the other documents --
+   circulation: the Sphinx documentation is reST, and the other documents --
    the READMEs included -- are Markdown where that applies. ``CONTRIBUTING.md``'s own
    *Documentation* section records the same split. One trap arrived with the ruling:
    :file:`MANIFEST.in` reaches the two READMEs under :file:`examples/` through

docs/source/contributing/conventions/mint-criterion.rst

@@ -143,6 +143,6 @@ only ``ast.Name`` nodes finds every mint and no unmint at all:
    Calling ``Cls(value)`` on a registry whose ``_missing_`` mints **mutates the
    class**. A probe is not a read: it installs a member that every later lookup then
    finds. :class:`~pcapkit.const.mh.cga_type.CGAType` is the one registry this applies
-   to today, but snapshot ``{member.value for member in Cls}`` before any lookup
+   to, but snapshot ``{member.value for member in Cls}`` before any lookup
    regardless, and use a throwaway process per registry when comparing behaviour across
    revisions.

docs/source/contributing/conventions/process.rst

@@ -18,7 +18,7 @@ The ``all`` Extra
 ``all`` means **core addons only** -- the things that let the library itself run at
 full functionality -- rather than everything a user might conceivably want. The owner
 settled that on :issue:`910` and named
-the three that qualify to date: the CLI addon, the crypto addon, and ``pycrate``.
+the three that qualify: the CLI addon, the crypto addon, and ``pycrate``.
 
 On the tree, in :file:`pyproject.toml`:
 
@@ -226,9 +226,9 @@ these, so that its status is readable without opening it:
 
 Two things the board shows rather than the rule: ``wip`` and ``needs: decision``
 legitimately **co-occur**, when the bulk of an issue is being worked and one
-sub-question is held for the owner -- :issue:`918` itself was labelled that way while this
-page was being written. And an open issue with no state label at all is a gap rather
-than a category, which is worth checking for rather than assuming away:
+sub-question is held for the owner -- :issue:`918` itself was labelled that way. And
+an open issue with no state label at all is a gap rather than a category, which is
+worth checking for rather than assuming away:
 
 .. code-block:: shell
 

docs/source/contributing/conventions/registry-protocol.rst

@@ -30,9 +30,9 @@ bespoke ``__new__`` exempts a registry from the template, not from the protocol.
 The Two-Tier Hierarchy
 ~~~~~~~~~~~~~~~~~~~~~~
 
-:class:`~pcapkit.corekit.enum.EnumRegistry` is not the only base any more. Since
-phase 1 of :issue:`877` it has a
-parent, and the line between them is whether the enumeration may *grow*:
+:class:`~pcapkit.corekit.enum.EnumRegistry` is not the only base: per phase 1 of
+:issue:`877` it has a parent, and the line between them is whether the enumeration
+may *grow*:
 
 =================================================== ==============================================================
 :class:`~pcapkit.corekit.enum.EnumLookup`           ``get``, ``get_all``, ``_validate_value``
@@ -65,7 +65,7 @@ itself and broken ``int``, ``str`` and flag registries at once.
 *instead* of ``register``, and it answers the owner's other requirement: the base has
 to offer range-validation logic for its inheriting classes to hook into. The
 base implementation accepts everything; an override states a range, in the shape the
-generated registries currently spell by hand in ``_missing_``:
+generated registries spell by hand in ``_missing_``:
 
 .. code-block:: python
 
@@ -104,10 +104,9 @@ Three things about it are easy to get wrong:
 
    Re-parenting every non-registry enumeration onto
    :class:`~pcapkit.corekit.enum.EnumLookup` was **phase 2** of
-   :issue:`877`, and it is now
-   **complete**: the phase landed for 24 of the 24 non-registry enumerations.
-   **Zero enumerations remain outside the hierarchy**, measured by the same runtime
-   walk over both the :mod:`enum` and ``aenum`` flavours that once found seven.
+   :issue:`877`, and it is **complete**: the phase landed for 24 of the 24
+   non-registry enumerations. **Zero enumerations remain outside the hierarchy**,
+   measured by a runtime walk over both the :mod:`enum` and ``aenum`` flavours.
 
 Failed-Lookup Exceptions
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -273,7 +272,7 @@ in **zero** of them, and neither class carried an alias (``__members__`` 6 and 4
 docstrings to refer to. Offered the choice between merging the widened copies and
 deleting them in a follow-up, the owner ruled for deleting them outright. Both
 ``get`` methods and both suppressions went with it, and
-:mod:`pcapkit.protocols.internet.mh` now defines no ``get`` at all.
+:mod:`pcapkit.protocols.internet.mh` defines no ``get`` at all.
 
 The one input where the copies **did** differ is why this matters beyond line count,
 and it is the trap for whoever writes the next override: the base branches on
@@ -476,7 +475,7 @@ That leaves the classes with something to decide:
        exactly as for the :class:`int` tier above; ``PDUKind``'s are :class:`str` ASN.1
        identifiers from 3GPP TS 38.413, and ASN.1 identifiers are case-significant by
        construction, so it lands the same way for a different reason.
-       **None** of the six defines a ``get`` of its own any more. Two did when this
+       **None** of the six defines a ``get`` of its own. Two did when this
        audit was taken --
        ``FastBindingAcknowledgmentStatus`` and ``IPv6AddressPrefixCode``, for
        signature reasons (no ``default``, and an :class:`int`/:class:`str` dispatch)
@@ -519,7 +518,7 @@ wider than a case fix:
 * ``CommandType`` **and** ``ConformanceRequirement``. By parity with
   ``TransportProtocol`` -- an :class:`int`-valued enumeration whose *names* are the
   specification's own tokens -- the measured spelling disagreement above would make
-  these two case-insensitive. Nothing looks them up by string today, though: the
+  these two case-insensitive. Nothing looks them up by string, though: the
   crawler translates the CSV's lower-case letters to the upper-case member names at
   generation time. Both classes inherit
   :class:`~pcapkit.corekit.enum.EnumLookup`, since
@@ -540,11 +539,9 @@ rather than changing it.
 
 .. note::
 
-   The obstacle this page used to record -- that the base's string-key path does not
-   fall through to a value lookup, so an ``aenum.StrEnum`` registry would stop
-   resolving a valid value that is not also a name -- **no longer applies.**
-   :meth:`~pcapkit.corekit.enum.EnumLookup.get` now checks ``_value2member_map_``
-   when the name lookup misses, so such a value resolves:
+   :meth:`~pcapkit.corekit.enum.EnumLookup.get` checks ``_value2member_map_`` when
+   the name lookup misses, so an ``aenum.StrEnum`` registry still resolves a valid
+   value that is not also a name:
 
    .. code-block:: pycon
 

docs/source/contributing/pep.rst

@@ -611,7 +611,7 @@ Writing the reassembler is the smaller half of the job. It would go at
 methods,
 :meth:`~pcapkit.foundation.reassembly.reassembly.Reassembly.reassembly` and
 :meth:`~pcapkit.foundation.reassembly.reassembly.Reassembly.submit`. Registering
-it, though, is currently inert:
+it, though, is inert:
 :meth:`~pcapkit.foundation.extraction.Extractor.register_reassembly` accepts any
 protocol name, while
 :class:`~pcapkit.foundation.extraction.Extractor` only ever instantiates the
@@ -996,7 +996,7 @@ dissectors later. The third format, the :rfc:`6088` traffic selectors of
 nobody has claimed it.
 
 **Wave 2 or 3 — per-entry coverage of the option and parameter registries.** The
-option, parameter, block and frame registries are *enumerated* today but not
+option, parameter, block and frame registries are *enumerated* but not
 *implemented* throughout: a code can be registered, and named, and still have no
 working per-entry read/make pair behind it. The goal of this item is to close
 that gap to zero for every code whose format is actually specified.