docs(conventions,const): resolve part B's unresolved cross-references (#934)

[JarryShaw]

• 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 #657

What is the purpose of your pull request?

• fix
• feat
• perf
• refactor
• test
• docs
• ci
• chore

---

Description of your pull request and other information

Part B of #934: the unresolved conventions.rst cross-references that are neither the
sentinels module refs part A (#936) fixed nor the six aenum roles part C already ruled
on (plain literals, since aenum's objects.inv carries zero py: objects and conf.py
excludes it deliberately). Rebased onto #940 after review; that merge deleted
FastBindingAcknowledgmentStatus.get outright, which broke a seventh reference this PR
now also fixes -- 15 misses against the current base, not 14.

• Qualified the three sentinel refs to pcapkit.corekit.sentinels, so they resolve
  against the page docs(corekit): add the sentinels API page so conventions.rst references resolve (#934) #936 added.
• Added an autoclass entry for FEATCode to docs/source/pcapkit/const/ftp.rst, and
  widened the section's intro clause to name both classes it documents now. Chose the
  "amend the clause" option over a second heading: FEATCode is a companion of
  Command's, not a peer in the page's own overview table, and every other section in
  this file pairs one heading with one autoclass -- a second heading re-declaring the
  same .. module:: would be a shape nowhere else in the 18 const/*.rst pages uses.
• Demoted Method.get, FastBindingAcknowledgmentStatus.get and the six aenum roles
  to plain literals: the first two are gone/private targets, aenum cannot be
  cross-referenced at all -- no target can exist for any of them.
• Added AenumRoleExclusionTests to test_conventions_doc_claims.py, pinning that no
  role names aenum on this page and that the four qualified sentinel targets stay
  qualified -- both proven to fail against the pre-fix (83c7552b8) page.
• Added test_ftp_featcode_doc_page_934_unit.py, pinning the new autoclass entry the
  way test_sentinels_doc_page_934_unit.py pins part A's page; proven to fail against
  the pre-fix page.

Nitpicky sphinx-build: all 15 misses (against this branch's rebased base, b337cdbc2)
now resolve. Three more resolve as a side effect of documenting FEATCode: stale
FEATCode references inside Command._unregistered_member's and
Method._unregistered_member's own docstrings, plus one in a rendered
feat: Optional[FEATCode] parameter annotation with no clear file attribution. Two
pre-existing bugs inside FEATCode's own docstring are newly exposed rather than
introduced -- a line-wrapped :meth: role and a reference to the vendor
Command.process, deliberately excluded from vendor/ftp.rst's own :members:
allowlist. FEATCode's :show-inheritance: does genuinely introduce one new warning
of its own (an aenum._enum.StrEnum base that cannot resolve), joining five identical
ones already present for Command/Method/etc. Recording rather than fixing any of
these: out of scope for this file.

Ran the targeted tests rather than the full make test, which OOMs at 29 GB in this
environment: test_conventions_doc_claims.py (incl. the two new
AenumRoleExclusionTests methods), test_sentinel_exports_unit.py,
test_sentinels_doc_page_934_unit.py and the new FEATCode page test -- 40 passed, 1
skipped.

mypy 321 errors/38 files, pylint 8.67/10 exit 30, isort clean -- all matching the
b337cdbc2 baseline (R0401 cyclic-import churn aside, non-deterministic on an
unmodified tree).

[JarryShaw]

NEEDS CHANGES at 98bffb72a — Opus cross-review (author was Sonnet). Two small items; the central fix is verified correct and is not in question.

The 14 → 0 claim is confirmed exactly, by diffing warning sets rather than counts: base has exactly 14 conventions.rst warnings, head has 0, and zero conventions.rst entries appear in the new set — which also rules out line-shift masking. Arithmetic checks: 17 resolved − 3 new = −14, total 1303 → 1289.

1. docs/source/pcapkit/const/ftp.rst:23 and :31. Adding FEATCode under the same .. module:: as Command makes this the only one of 18 const/*.rst pages where autoclass count equals module count. I censused it: every other page sits at autoclass == module − 1; ftp.rst was 2/3 and is now 3/3. And the intro at :23 still reads "the constant enumeration for FTP Command" — singular — while the section now documents two classes. Either give FEATCode its own heading, matching how the file separates pcapkit.const.ftp.return_code, or amend that clause.

2. Nothing pins the aenum-role-free invariant. That is settled policy recorded at docs/source/conf.py:95-106, and the demotion of six roles is only as durable as a test. The scope note cited (test_conventions_doc_claims.py:32-36) excludes checking whether references resolve — it does not excuse leaving a forbidden role unpinned, and that same file's RetiredNameTests at :417 is exactly this shape: "No more IPv6_GenericExt name." Add the equivalent for :mod:aenum``/:class:~aenum.` and for the four qualified sentinel paths.

One attribution refuted, and it was the author's own. The PR body credits the third bonus fix to "the vendor Command.process's own docstring". Measured, the three are Command._unregistered_member, Method._unregistered_member, and <unknown>:1 — the last being the feat: Optional[FEATCode] annotation. Count of 3 is right, the attribution is not. Also, one of the three new warnings (aenum._enum.StrEnum, 5 → 6) is introduced by :show-inheritance: rather than exposed; acceptable since it joins five identical ones, but the body's "newly exposed, not introduced" blurs it.

Confirmed and better than claimed on the rest: Method.get's :meta private: is at method.py:293 with precedent at ftp/command.py:502/:510 — and conventions.rst already writes Method.get as a plain literal at :753/:756, so the demotion joins the file's own majority style. The worst case for the FEATCode entry was ruled out: no generator writes const/*.rst — no emitter in util/, hand commits only — so it will not be overwritten. Scope is clean by --word-diff: 11 role-markup tokens and nothing else, plus one a→an that grammar requires. No ruling wording touched, so #918 stays conflict-free.

Leaving the two pre-existing FEATCode docstring bugs unfixed is right — pcapkit/ is out of scope and #936 set the report-don't-fix precedent. Nothing UNVERIFIED.

[JarryShaw]

Both review items landed at 71bf55088, verified rather than taken on trust. Label moved to review: pending; a cross-review on a third model is in flight, so this is not a good-to-go yet.

• ftp.rst: the intro clause is widened rather than a second heading added — the author's reason is that .. module:: is unique within every one of the 18 const/*.rst files, so a heading would mean declaring pcapkit.const.ftp.command twice. Either fix satisfied the item; the claim is in the cross-review's brief.
• The aenum-role-free invariant exists and fails on the base. AenumRoleExclusionTests plus a new test_ftp_featcode_doc_page_934_unit.py. Swapping b337cdbc2's two pages under the new tests gives 5 failures across 4 nodes (subtests inflate the count); on the PR head, 4/4 pass. aenum roles in conventions.rst: 6 → 0.
• The rebase exposed a seventh reference and the author fixed it. fix(protocols): widen the two kept get overrides in mh.py to accept default #940 deleted FastBindingAcknowledgmentStatus.get outright, so :meth:…FastBindingAcknowledgmentStatus.get`` stopped resolving; it is now a literal, matching the two siblings already written that way in the same sentence. Not one of my two items — flagging it because it is new since my last review, and it is the first thing the cross-review is told to falsify.
• Merge-base is b337cdbc2 = current main, one commit, correct authorship, +169/−14 over four files. Nothing to merge, so the green is not stale green.
• tests/project whole directory: 200 tests, OK, 1 skipped. CI at this head: 54 pass / 0 fail / 5 in progress (the five main Python legs) / 3 skipping.

Outstanding regardless of this PR, tracked and not blocking it: FEATCode's own docstring still carries :rfc:5797#secion-3`` — a typo for section — and the vendor generator cites §2 for the same column while writing `FEAT Code` where the const file writes `FEAT code`.

[JarryShaw]

Housekeeping, and it is my doing: this now reads BEHIND. I pushed a test-only docstring correction to main (1bd576ec1) while the cross-review was running.

main is governed by ruleset 23497679, not by legacy branch protection — the protection API 404s, which is what misled me. It sets strict_required_status_checks_policy: true, so any push to main puts every open PR out of date. Worth recording for its own sake: the required contexts are Required checks passed plus the five Compat Python 3.10–3.14 legs — not the five long Python 3.x legs I have been calling "the required gate" in earlier comments here.

I am deliberately not rebasing yet. A rebase moves the head sha, and a verdict pinned to a superseded sha is worse than no verdict — the cross-review in flight is reading 71bf55088. Order: let it report, then rebase once, confirm via the merge-base diff that the content delta is unchanged, carry the verdict forward onto the new sha. The push touched only tests/_support.py, which this PR does not, so there is nothing for it to conflict with.

Nothing here needs action from you, and mergeable is still MERGEABLE.

[JarryShaw]

GOOD TO GO at b43717a36 — Fable cross-review (author was Sonnet). It checked all six load-bearing claims and found nothing needing a change; the four files are byte-identical to the reviewed 71bf55088, and the delta vs merge-base is unchanged at +169/−14.

You resolved the BEHIND yourself with "Update branch" (b43717a36, a merge of 1bd576ec1), so I abandoned the rebase I had prepared rather than force-push over it — my --force-with-lease refused on stale info, which is the outcome I wanted. Consequence worth stating: this PR now carries 2 commits, one a merge, against the usual one-commit rule. That was your action, so I have left it; say the word if you want it squashed instead.

The review corrected three of my framings, and I re-derived each before repeating it:

1. Two :meth: demotions, not three — FastBindingAcknowledgmentStatus.get and Method.get. I said three.
2. Method.get is not gone. It exists and is public at pcapkit/const/http/method.py:232. The demotion is still right, but for a different reason than I gave: autodoc emits no method entries for these enum classes at all. Independently corroborated by docs(conventions): 16 unresolved cross-references render as plain text, CI stays green #934's own table, which lists it at line 444 as "no target".
3. I published a wrong claim here two comments ago — that the vendor generator cites §2 and writes FEAT Code where the const file writes FEAT code. The two class docstrings are in fact byte-identical. The disagreement is within each file, between the class docstring (FEAT code, §3) and get()'s (FEAT Code, §2, quoting the RFC verbatim). Both are right in place; the PR follows the CSV header, which literally reads cmd,FEAT code,description,….

Also: the secion-3 typo is in both pcapkit/const/ftp/command.py:28 and pcapkit/vendor/ftp/command.py:68 — a third pre-existing FEATCode docstring bug, and it silently produces a wrong anchor. I will raise it separately.

Not verified, stated so rather than folded away: the body's whole-build tallies ("15 misses", the three side-effect resolutions, the one new :show-inheritance: warning) were time-boxed out. The structural facts under them are verified. Unpublished and yours to merge.