docs(tests,pcapkit): paraphrase the remaining quoted rulings instead of quoting them (#719)

[JarryShaw]

The ruling on #982 is to paraphrase a ruling rather than quote it, and to avoid verbatim quotes because
one may record something said outside GitHub and so be unverifiable. #949 already applied that to
docs/source/contributing/; #982 applied it to the sites it happened to touch. This issue is the rest.

Scope, measured. A cross-review matched every quoted span in all 742 .py files against the whole repo
comment corpus — 2047 issue comments, 334 inline review comments, 981 issue and pull-request bodies — and
found 95 sites whose surrounding prose attributes a quotation to the owner, a maintainer, or "a ruling".
tests/ carries 97 verbatim lines across 52 files; pcapkit/ carries 48 across 30.

Three defect classes were found inside that set, which is why converting the rest is worth doing rather
than cosmetic:

• A quotation that exists nowhere. Four sites carried a sentence attributed to the owner, "verbatim",
  that matched exactly one item in 3362 — the comment reporting the finding. Fixed in docs(pcapkit,ci): cite the issue a defect belongs to, not the pull request (#719) #982.
• A quotation that was altered. tests/corekit/test_sentinel_exports_unit.py rendered "export the
  objects (like NULL) to users" where docs: sweep all prose for concision and accuracy, and drop timed context outside the changelog #719 says "to __all__, and leave the types (like NullType)
  out" — the second half deleted and a checkable claim about a module attribute replaced by an
  interpretation. Fixed in docs(pcapkit,ci): cite the issue a defect belongs to, not the pull request (#719) #982, and a second file carried the same text.
• A typo silently corrected under a verbatim label. const: bring the 16 bespoke registries onto EnumRegistry, after fixing the base's str-key dispatch #860 says "properly create new entires"; 12
  sites across 8 files render "entries" and none render the real word. Four fixed in docs(pcapkit,ci): cite the issue a defect belongs to, not the pull request (#719) #982; eight remain,
  six of them in generated const/vendor pairs that must stay byte-identical in their generated regions,
  so they need a regeneration-safe change rather than a hand edit.

The marker does not bound the problem, which is the trap to design around: 16 sites attribute a quotation
to a #NNN with no verbatim anywhere near it, and a further five quote "the ruling" with no number at
all, so there is nothing to grep against. A sweep keyed on verbatim misses both families. Search the
italic-quote pattern as well.

Known remainders, so the next pass starts from a list rather than a search: the eight pcapkit/ typo
sites; three further "I prefer (2) directly" quotations in
tests/corekit/test_enum_lookup_reparent_930_unit.py (left in #982 as out of scope); and
pcapkit/corekit/sentinels.py:490, where "per GitHub issue #937" reads as authority rather than
provenance.

The convention to apply, settled across #719 and #982: a sentence attributing a ruling names the issue
where the ruling was given and may use "per"; a sentence describing what changed uses an action verb —
"landed in", "renamed in", "filed as" — and names the issue the change belongs to, never the pull-request
number.

Not urgent, and deliberately not folded into #982, which has already taken six review rounds.

[JarryShaw]

Commented on #982 for the narrowing decision.

[JarryShaw]

Scope narrowed by the owner's ruling on #982: "Do the narrowing."

The rule is now paraphrase only what cannot be sourced; re-cite what can — not the blanket conversion this
issue was first written against.

Why the narrowing is better aimed, from what #982 actually measured. Blanket paraphrase was a clear win on
exactly one class and a clear loss on two:

• Unsourceable → paraphrase. Four sites carried a sentence attributed to the owner "verbatim" that matched
  one item in a 3362-item corpus: the comment reporting the finding. There was nothing to check, so paraphrase
  converted an unfalsifiable claim into a falsifiable one. Done in docs(pcapkit,ci): cite the issue a defect belongs to, not the pull request (#719) #982, attributed to PR fix(const,vendor): stop EtherType and Socket minting on an unrecognised value #878.
• Real but mis-cited → re-cite, do not paraphrase. The "export the objects (like NULL) to users" text
  was not invented: it is a splice of docs: sweep all prose for concision and accuracy, and drop timed context outside the changelog #719's export ruling with the tail of the owner's own fix(corekit): export only the sentinel objects, not their types #911
  comment, "we only expose the final objects to users". Paraphrasing deleted a verifiable quotation and left
  a dependent sentence grounded on the wrong one of two docs: sweep all prose for concision and accuracy, and drop timed context outside the changelog #719 rulings.
• Real and correctly cited → leave alone. The const: bring the 16 bespoke registries onto EnumRegistry, after fixing the base's str-key dispatch #860 minting quotation was fully sourceable. Paraphrasing it
  dropped the owner's load-bearing first sentence, "I think we should not mint on get still actually", and
  recast a direct ruling as an inference.

So the sweep is no longer "convert 95 sites". For each of the 95, establish which class it is first — and
the classification is the work, not the rewriting.

The typo question is resolved by the same rule. #860 says "properly create new entires"; 12 sites
across 8 files render "entries" and none render the real word. Since that quotation is sourceable it stays a
quotation, so reproduce the typo and mark it [sic] — which keeps the text matchable against the thread.
Eight pcapkit/ sites remain, six of them in generated const/vendor pairs needing a regeneration-safe
change rather than a hand edit.

Remainders, as a list rather than a search: those eight pcapkit/ typo sites; three "I prefer (2) directly" quotations in tests/corekit/test_enum_lookup_reparent_930_unit.py (at :32, :202, :454 — all
genuine, so under the narrowed rule they stay and only their citations need checking); and
pcapkit/corekit/sentinels.py:490, where "per GitHub issue #937" reads as authority rather than provenance —
a preposition defect, not a wrong number.

The marker still does not bound the problem, and this matters more under the narrowed rule than the old
one, because classification needs the full set: 16 sites attribute a quotation to a #NNN with no
verbatim anywhere near it, and five quote "the ruling" with no number at all — nothing to grep, and
nothing to check them against either, which puts them in the unsourceable class by default. Search the
italic-quote pattern as well as verbatim.

Two checks that caught real defects in #982 and should be run on every site here: a thread with zero
comments cannot be the source of a quotation, and a re-quote is not a source — a thread carrying the text
only under an "(from #NNN)" caption is relaying it, which is how one defect survived five review rounds.

[JarryShaw]

Updated on #982. I still prefer paraphrasing with contexts.

[JarryShaw]

Superseding my 12:57Z comment, which now states the wrong rule. That comment set the scope to the
narrowing — paraphrase only what cannot be sourced, re-cite what can. The owner has since reversed it, on #982
and again here: paraphrasing with context is what he wants, because narrowing does not help a reader who
has no context, and documentation should read like statements, not conversations — verbatim quoting makes a
docstring read like a discussion.

The rule, to apply at every site:

State the rule in our own words, carry the reason a reader needs, and cite the issue where it was settled.
No quotation of the maintainer, sourceable or not.

So the scope is wider than the narrowing, not narrower: all 95 owner/ruling-attributed quote sites
across tests/ and pcapkit/, not only the unsourceable ones. Quotations of RFC text, code literals and
ordinary prose are untouched — they are not what the ruling is about.

What #982 has already converted, as worked examples of the form: the sentinel export rule now says
__all__ keeps the object and leaves the type out and why — the types are not part of the public surface
— settled on #719, implemented under #911; the minting rule says get() does not mint and only register()
creates an entry and why — only IANA-registered values are legitimate and get() has not enough
information to construct one — settled on #860. A further 15 sites in the same four files are being converted
now, so #982 leaves no mixture behind it.

The one thing worth carrying forward from the narrowing discussion, because it is a drafting hazard rather
than a rule: a terse line converts badly. Dropping the quote marks off something like "Q1 - bare it is."
produces an assertion with no content, which is a worse artefact than the quotation was. The thread has to be
read so the statement can say what was decided and why it matters at that site — which is the whole point
of "with context".

The [sic] question dissolves. #860's entires spelling only needed marking while it was a quotation.
Eight pcapkit/ sites still render it silently as entries; under this rule they become statements and the
spelling stops mattering. Six of those eight are vendor/ templates or their generated const/ outputs, which
must stay byte-identical in their generated regions, so they need a regeneration-safe change rather than a hand
edit.

Remainders unchanged: those eight pcapkit/ sites; three "I prefer (2) directly" quotations in
tests/corekit/test_enum_lookup_reparent_930_unit.py at :32, :202 and :454 — all three now convert,
where the narrowing would have kept them; and pcapkit/corekit/sentinels.py:490, where "per GitHub issue
#937" reads as authority rather than provenance.

And the marker still does not bound the set: 16 sites attribute a quotation to a #NNN with no verbatim
near it, and five quote "the ruling" with no number at all. Search the italic-quote pattern as well.

[JarryShaw]

Labelled blocked, with the blocker written down so nobody has to guess.

Blocker: #982 must merge first. That pull request is converting the quotations in four files
(tests/corekit/test_sentinel_exports_unit.py, tests/const/test_const_registry_protocol.py,
test_const_enum_no_mint.py, test_const_enum_builtin_parity.py). Starting here before it lands would mean
two changes editing the same docstrings on different branches, which clobbers silently — the later push wins
and nothing announces that the earlier one happened.

Checkable condition to unblock: gh pr view 982 --json state returns MERGED. Nothing else gates it.

One scope figure has already moved, measured rather than estimated. #982's own conversion pass found ~29
owner-attributed quotations in those four files, not the 15 I had counted. My count was low for a reproducible
reason worth recording here, because this issue's sweep will hit it too: my regex required an owner word
(owner, maintainer, ruling, verbatim) in the text preceding the quotation, so it missed every site
whose lead-in did not use one. The wider method that found them was a tokenize/ast scan of every comment and
docstring for any double-quoted span of 12+ characters, traced to its thread with gh api. Use that method
here, not a marker grep — the 95-site figure for the rest of the tree was derived the narrow way and is
therefore a floor, not a total.

Two further boundary notes from that pass, both of which this issue inherits:

• Rulings given on a pull-request thread need a PR-to-issue mapping, and those mappings are judgement
  calls, not lookups. docs(pcapkit,ci): cite the issue a defect belongs to, not the pull request (#719) #982 resolved PR fix(vendor): stop get() minting; _missing_ fixed for 21 of 105 (#775) #838 to Registries mint a permanent member for every unrecognised value: 1,169 extend_enum sites across 113 registries #775, fix(ipx): order Socket._missing_ range branches narrowest-first #847 to reg: three Socket._missing_ range branches are unreachable, shadowed by a wider earlier branch #841, fix(reg)!: drop TransportProtocol's IntFlag base now that nothing composes #836 to reg: drop TransportProtocol's IntFlag base once nothing builds a composite #808, fix(corekit): make EnumRegistry.get's no-default marker an identity sentinel (#857) #859 to const: make EnumRegistry.get's NO_DEFAULT a sentinel object, not -1 #857, and fix(const): refuse a multi-bit proto in AppType._dispatch rather than resolving it LSB-first (#759) #783 to
  const(apptype): per-registry __canonical__ divergence makes get(port, proto=<multi-bit>) return a different service #759. Each needs confirming rather than trusting.
• Some "reasons" in the tree came from an agent's comment that the owner then accepted, not from the owner's
  own words. If only owner-worded reasons should survive, that is a separate and larger trim than this issue
  currently describes.

Also inherited: pcapkit/corekit/enum.py:87 still carries the #842 contracts as a quotation, in a file #982
does not own.

[JarryShaw]

Unblocked — the written condition is met. #982 merged at 15:46:53Z as 88e130c4e, so the file-collision
risk that gated this issue is gone. blocked removed.

What #982 landed, so this issue starts from the right baseline rather than re-deriving it:

• 28 quotations converted to statements across 20 docstring/comment locations in four files — sentinel 4,
  registry-protocol 9, no-mint 12, builtin-parity 3. Each carries the rule, the reason a reader needs, and the
  issue it was settled on.
• The verbatim marker is not the right instrument for the remaining sweep, measured. My own count of these
  four files was 15 and the converting worker's was ~29; the authoritative 28 came from a tokenize/ast scan
  of every comment and docstring for any double-quoted span of 12+ characters. A marker grep undercounts because
  two of builtin-parity's three used bare double quotes rather than *"…"*, and because a lead-in without
  the words owner/maintainer/ruling/verbatim defeats a context regex. So the 95-site figure in this issue is a
  floor. Use the AST scan.
• tests/ is exempt from the issue-citation half of the docs: sweep all prose for concision and accuracy, and drop timed context outside the changelog #719 ruling —
  docs/source/contributing/conventions/documentation.rst:203-210, landed in docs(contributing): record the tests/ and changelog PR-citation exemptions #980. I briefed against that
  carve-out and it produced a false pointer: three sites re-pointed from PR #836 to #808, where fix(reg)!: drop TransportProtocol's IntFlag base now that nothing composes #836's
  body says in bold its rulings went beyond what reg: drop TransportProtocol's IntFlag base once nothing builds a composite #808 asked for and reg: drop TransportProtocol's IntFlag base once nothing builds a composite #808 carries neither. Reverted in docs(pcapkit,ci): cite the issue a defect belongs to, not the pull request (#719) #982's
  final commit. Under tests/, de-quote but keep the pull-request citation.
• Two pre-existing defects fixed in passing, both worth watching for elsewhere: a site that quoted an agent's
  analysis while framing it as the owner's ruling, and one that conflated EnumRegistry.get() mints through its default, contradicting its own "It never mints" contract #864's ruling with Registries mint a permanent member for every unrecognised value: 1,169 extend_enum sites across 113 registries #775's criterion.

Remainders, unchanged: the eight pcapkit/ sites rendering #860's entires as entries — six in generated
const/vendor pairs needing a regeneration-safe change rather than a hand edit; three "I prefer (2) directly" quotations in tests/corekit/test_enum_lookup_reparent_930_unit.py at :32, :202, :454; and
pcapkit/corekit/sentinels.py:490, where "per GitHub issue #937" reads as authority rather than provenance — a
preposition defect, not a wrong number.

Two checks that each caught a real defect in #982 and should run on every site here: a thread with zero
comments cannot be the source of a quotation, and a re-quote is not a source — a thread carrying the text
only under an "(from #NNN)" caption is relaying it, which is how one defect survived five review rounds.

[JarryShaw]

A question the remaining groups will keep hitting, so it is worth settling once.

#719's convention is to cite the issue a ruling was settled on rather than the pull request that carried it out. The written exemption covers tests/ and the changelog, on the ground that a cited pull request there often closes no issue and the fact lives in the pull request's own body or review thread instead.

That same situation arises under pcapkit/, and #991 hit it twice:

• the exception ruling was given in fix(corekit): reparent the unblocked non-registry enums onto EnumLookup (#877) #921's review; fix(corekit,utilities): raise pcapkit exceptions from EnumLookup.get, following stdlib Enum's shape #923 only re-quotes it, so "recorded on fix(corekit,utilities): raise pcapkit exceptions from EnumLookup.get, following stdlib Enum's shape #923" is true but is not where it was given;
• design: should the non-registry helper enums share a lookup interface, or be made strictly immutable? #877's phase 2 has two halves — fix(corekit): reparent the unblocked non-registry enums onto EnumLookup (#877) #921 covered 17 of the 24 non-registry enumerations and refactor(const,protocols): reparent the last seven non-registry enums onto EnumLookup #930 the remaining seven — so "design: should the non-registry helper enums share a lookup interface, or be made strictly immutable? #877's phase-2 re-parenting" does not pin which half, and refactor(const,protocols): reparent the last seven non-registry enums onto EnumLookup #930's is cited two files away.

With the pull request unnameable there is no fully compliant wording, only a least-bad one. Three ways out:

1. extend the exemption to pcapkit/ for a ruling given in a pull request's review, citing it where no issue carries the fact;
2. keep the locative form and accept that it is loose;
3. name the pull request alongside the issue.

I lean to (1), scoped narrowly to where no issue carries the fact, because the alternative is prose that is precise about nothing in particular. Labelling needs: decision.

This does not block the remaining five groups — I will use (2) until you rule, since it is the reversible option.

[JarryShaw]

I still prefer no directly quoting of our conversation unless it's a must. paraphrasing with references and contexts is better convention.