docs(conventions): harvest the settled rulings, correct the stale prose (#918)

[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

Both halves of #918, on top of 4f3d43df7. Nothing under pcapkit/ changes.

Half 1 — the five passages #927 left here. All verified against the merged tree,
not copied from the issue:

• FEATCode.get('ZZ-NOT-REAL') now named as raising EnumKeyError, adding that it
  is a KeyError so an except KeyError is unaffected.
• The _validate_value bullet gains the unwrapped path: with no usable default,
  get re-raises an in-library ValueError as it stands. Measured — an override
  raising EnumValueError('CUSTOM 99') reaches the caller with that message and
  one CRITICAL record, not two.
• New What a Failed Lookup Raises for fix(corekit,utilities): raise pcapkit exceptions from EnumLookup.get, following stdlib Enum's shape #923's ruling, kept as provenance-vs-shape,
  plus the quiet/loud asymmetry (name miss quiet=True, 0 log records; value miss
  loud, 1 — both measured).
• Case Sensitivity records that TransportProtocol.get is now only a case fold
  (its whole body is two super().get() calls) and that Criticality.get is gone —
  its override's only remaining job was the conversion fix(corekit,utilities): raise pcapkit exceptions from EnumLookup.get, following stdlib Enum's shape #923 retired.
• The #877 phase-2 .. note:: said the phase "has not happened yet". It has
  partly happened: 17 of the 24 non-registry enumerations are on EnumLookup,
  and seven are not (CommandType, ConformanceRequirement, ESPStatus, and the
  four mh helpers). A runtime walk reproduces the page's own census exactly —
  151 enumerations, 127 registries, 24 non-registry, 7 outside.

Half 2 — the five harvested rulings. #1 (sentinel housing, "Okay one module for
all four it is.") was already on the page from #911/#922, so it is unchanged. The
other four land in a new Which bases an IPv6 extension header names section:

• refactor(ipv6): rename IPv6_GenericExt to IPv6_Ext and make it the shared base (#917) #924's subclassing ruling, with the code-is-not-evidence warning stated before
  the criterion, since IPv4.__proto__ is Internet.__proto__ is True (measured) and
  a classification derived from dispatch would make all eight headers standalone.
• The RFC census, each citation fetched and read rather than relayed:
  AH RFC 4302 §3.1.1, ESP RFC 4303 §3.1.1 (both with IPv4 diagrams), HIP RFC 7401
  App. C.2 (Next Header: 139 under an IPv4 header) and §5.1. MH fails on
  RFC 6275 §6.1.1's IPv6-only pseudo-header plus RFC 5944's UDP 434; Shim6 likewise.
  The section says plainly that own-protocolhood alone is not sufficient, since
  that reading was put to you on refactor(ipv6): rename IPv6_GenericExt to IPv6_Ext and make it the shared base (#917) #924 and not taken.
• Regular update [test/rc/abc] #4, the retired IPv6_GenericExt name: it lived on main from b3551cb63 to
  93cf940b3, under four hours, after the newest tag — git grep finds it in no
  release.
• Merge [test/rc/protochain] #5, ESP as a pair of coexisting facts. IANA's IPv6 Extension Header Types CSV was
  fetched: 11 rows, 50,Encapsulating Security Payload,[RFC4303] among them, 147
  absent. RFC 8200 §4.5's exclusion opens "For this purpose," — confirmed in the RFC
  text, where it is line-wrapped, which is why a line-oriented grep misses it. The
  short-circuit reason is cross-referenced to IPv6.__generic_ext_codes__ and
  pcapkit.protocols.internet.ipv6_ext rather than restated.

On splitting the page (#918 part 2): not done here, deliberately. It cannot be
done without a test change. tests/corekit/test_sentinel_exports_unit.py:157-164 opens
docs/source/contributing/conventions.rst and slices
text.index('.. _sentinel-convention:') through
text.index('.. _registry-protocol:', start) — put those two anchors in different files
and it raises ValueError, not a wrong answer. A split also wants the index.rst
toctree entry, and seven prose citations of the path across pcapkit/ and tests/.
Landing that as a pure move, in its own commit, is reviewable; landing it under +300
lines of new prose is not. Part 2 of #918 therefore stays open.

Two side-effects worth naming. The page's own title is now House Conventions —
it carries a protocol-class ruling, and a preamble reading "design rulings for
pcapkit.const" would have been false. The three prose references to the old title in
tests/const/test_const_ftp_featcode_case_903_unit.py follow. And EnumValueError had
no autoexception entry in docs/source/pcapkit/utilities/exceptions.rst while
EnumKeyError did, so every :exc: reference to it — five on this page alone —
rendered as plain text; one entry added.

Still unresolved on this page, all pre-existing and none introduced here:
pcapkit.corekit.sentinels has no docs page at all (5 dead :mod: refs, plus
NoValueType), FEATCode has no autoclass entry (3), and aenum has no
intersphinx inventory (3). Each wants its own change; sentinels in particular needs
a toctree decision.

Tests. tests/project/test_conventions_doc_claims.py, 15 new, pinning what is
checkable: the four .. _label: anchors (the guard a later split has to keep passing),
the three phase-2 figures against a runtime walk, the bases-per-header table against
__bases__ and against STANDALONE_MEMBERS, the absence of IPv6_GenericExt from
pcapkit/, and the FEATCode name miss. Proven to fail without the prose — five
mutations (Seven→Six, 17→20, EnumKeyError→KeyError, HIP's row flipped to
extension-only, the new anchor deleted) each fail with a message naming the drift.
RetiredNameTests is the exception and is a forward guard rather than a test of this
change: nothing here could make it fail without editing pcapkit/.

Counts: tests/project 193 OK (178 before), test_sentinel_exports_unit 18 OK,
test_ipv6_ext_unit + test_const_ftp_featcode_case_903_unit + test_enum_lookup_base_unit
77 OK. Docs-only, so no coverage delta is claimed. sphinx-build succeeded with the
same 61 warnings as before and none on either edited page; verified in the rendered
HTML rather than by warning count, since this project builds without -W and without
nitpicky — all 24 cross-references in the new section resolve to real <a href>s, and
:ref:extension-header-subclassing`` renders as a link. The build was run with
PYTHONPATH exported and the log confirms it documented this worktree.

[JarryShaw]

GOOD TO GO at df87cb33b — Sonnet cross-review (author was Opus). The verdict holds, but one of its supporting claims is false and I am not relaying it.

The reviewer wrote that grep -r "class Criticality" returns nothing across the tree — "the class is genuinely gone". That is wrong. Measured on 4f3d43df7:

pcapkit/protocols/application/ngap.py:218:class Criticality(EnumLookup, IntEnum):
  bases: ('EnumLookup', 'IntEnum')   members: ['reject', 'ignore', 'notify']   has own get: False

The class is alive, exported in __all__, and re-parented onto EnumLookup by #921. Only the get override is gone.

The document itself is correct — line 487 reads "Criticality.get went further and no longer exists", which is about the method, and line 642 likewise. So this is a reviewer error rather than a PR defect. Worth stating anyway: had the page actually claimed the class was gone, this review would have blessed it. The distinction was flagged in the author's own hand-back, where it corrected my brief for making the same slip.

Everything else re-derived and confirmed:

• The quiet/loud asymmetry is stated, not omitted — FEATCode.get('ZZ-NOT-REAL') raises EnumKeyError with 0 log records; TransType.get(99999) raises EnumValueError with 1 CRITICAL.
• __bases__ on all eight headers match the table: five on (IPv6_Ext,), AH/ESP on (IPsec, IPv6_Ext), HIP on (IPv6_Ext, Internet). The "code is not evidence" caveat is present, and IPv4.__proto__ is Internet.__proto__ → True confirmed live.
• The new test file is not tautological. Stripping IPsec from AH's bases failed two tests immediately, so it pins against real __bases__ rather than the document's own prose. PhaseTwoRemainderTests derives the 17-of-24 and seven-outside figures by a real package walk, then regex-matches them out of the page.
• The split reasoning holds: sentinel-convention → registry-protocol is a 149-line gap on both trees, so only the preamble grew and the sliced section is untouched.
• RFC and IANA claims fetched from source: RFC 8200 §4.5's exclusion is scoped by "For this purpose," with ESP among upper-layer headers; IANA's registry has 11 rows with ESP=50 present; __generic_ext_codes__ has 7 codes with ESP absent.

One cosmetic imprecision, not worth a revision: the page calls AH's and ESP's RFC sentences "the same sentence", where RFC 4302 §3.1.1 says "calls for" and RFC 4303 §3.1.1 "translates to" — parallel, not identical.

Note the page will need one edit shortly. It states seven enumerations remain outside EnumLookup; #930 is in flight and makes that zero, and its own PhaseTwoRemainderTests will fail when that lands. I am sequencing the two rather than letting them race.