feat(S2): read an all-caps credential after a comma by default (#564)

[derek73]

Closes #564.

Policy.unlisted_caps_suffixes becomes a CapsSuffixes StrEnum, OFF / AFTER_COMMA / EVERYWHERE, defaulting to AFTER_COMMA. The field was new in 2.4 and unreleased, so no deprecation is owed. Passing the old True / False raises a TypeError that names CapsSuffixes.EVERYWHERE / CapsSuffixes.OFF.

Why the comma position is safe by default: the all-caps SURNAME convention (Jean DUPONT, DUPONT, Jean) writes the capitals at the end of a name or before a comma, never after a comma behind a full name. The off default was argued for the convention's positions and was switching this one off along with them.

text	2.3.0	default (AFTER_COMMA)
John Smith, XYZ	given XYZ, family John Smith	suffix XYZ, reported
Ahmad Jayadi, CHA / John Smith, RAI	given CHA / RAI	suffix, reported
The Rt Hon Kenneth Clarke QC MP, HMG	given HMG	suffix QC MP, HMG
John Smith, LEED AP	given LEED	suffix LEED AP (closes the deviates: #291 marker)
John Smith, PhD XYZ	given PhD	suffix PhD XYZ
García Márquez, MJ	given MJ	given MJ (unchanged; undotted paired initials)
Smith, XYZ	given XYZ	given XYZ (unchanged; one name word)
GISCARD d'ESTAING, VALÉRY / LLOYD FitzGERALD, RONALD / LLOYD WEBBER, ANDREW PhD	given name kept	given name kept (the name carries no contrast)
John Smith XYZ (no comma)	family XYZ	family XYZ (trailing slot needs EVERYWHERE)

Decisions (Derek's calls marked in decisions.md#S2)

• API: a StrEnum, not two booleans or a mixed bool | "comma". OFF exists so a capitalized given name behind a two-word surname can still be kept (García Márquez, GABRIEL → suffix GABRIEL by default, the accepted cost).
• Two letters: a lone two-capital word is never admitted at the comma. Where the name carries the contrast, the comma decides a two-capital word exactly as Dotted initials after a two-word surname read as a credential: García Márquez, G.J. has no given name #563 decides M.J.. Measured: 0 of 1295 swapped inputs differ.
• Mixed runs: an unlisted all-caps word is a by-shape member of C1's Should a credential run after a comma keep its comma when the last word is an ambiguous acronym? John Smith, PhD MEng reads first PhD, last John Smith #544 run beside listed credentials. Otherwise adding a credential (PhD XYZ, XYZ Jr.) would flip the reading back to a name.
• The name's contrast: a word of the name's own before the comma that holds a capital and whose last cased letter is lowercase (read after composing the word, passing over non-letters, caseless letters, and a lowercase letter whose capital is not one letter, like ß), not claimed by the vocabulary as a title, particle, connective, credential or generation. Smith, DiCaprio, IJzerman, al-Rashid, d'Estaing, McDonald and Džokić carry it. A surname written in capitals ends in a capital whatever is glued in front of it (d'ESTAING, al-ASSAD, McDONALD, FitzGERALD, DeVITO, St-PIERRE), so such a record keeps its given name, with no prefix list. Derek reached this through istitle(), "contains a capital", "not all capitals but contains a capital" and "capital then lowercase"; each one's leaks are recorded in decisions.md#S2. The accepted costs: an all-lowercase name, an unlisted mixed-case title (Doña), and in an otherwise all-caps record a glued lowercase ending or a mixed-case hyphenated part (JOHN O'NEILL's, JOHN SMITH-Jones, JEAN-pierre DUPONT).
• Prerequisite: Why does De La Cruz, Ed lose its given name? #575, without which Van Buren, MARTIN and De La Cruz, MARIA would have lost their given names.

Implementation

• segment: the all-caps run test and the Should a credential run after a comma keep its comma when the last word is an ambiguous acronym? John Smith, PhD MEng reads first PhD, last John Smith #544 run's caps member share one name_contrast(), which reads the own-words walk case_class already does.
• classify: tags a caps word in the part a suffix comma opened under the default too, so case repair keeps XYZ (rules.md#R4). A forced-repair test guards this, with its negative control run.
• Two predicates for two questions: in_any_wordlist (the caps shape's "unlisted") and claimed_as_non_name (which words can carry the contrast; a caller's surname list counts as name text).
• Cost: every caller asks first, in C, what the predicate would decline anyway. Names with no all-caps word after the comma cost exactly what they do on master (Smith, John, Smith, JOHN, John Smith, PhD, John Smith, MA, John Smith, CPA, Ph. D., MD PhD, and the benchmark reference). John Smith, XYZ goes from 251 to 266. An all-caps record with a credential pays a constant +26. Past that, the contrast test is linear in the words before the comma (about four frames a word) and constant in a word's letters.

Docs and ledgers

rules.md S2/C1/C2/R4, decisions.md#S2 (plus a C1 pointer), mechanisms.md, customize.rst, usage.rst, modules.rst (adds CapsSuffixes), the release log, and all five ledgers. A fix(#564) rule classifies the movers. #342's comma pair (RAI/CHA) reads suffix again by its capitals, so that rule's fields lose given and John Smith, RAI's watched shape is re-recorded.

Verification

• Tests: full suite 10896 passed; mypy, ruff and the docs doctests are clean.
• Gate: exits 0 at 1.4.0, 2.0.0, 2.1.0, 2.2.0 and 2.3.0. The radar-unclassified counts are what they were before the change (0/5/6/7/7).
• Equivalence: reviewers measured OFF against master's default over the corpora, every cases.py text and generated grids of up to 388k names, with 0 differences.
• Review: a docs review and a code review, then five reviews of fix commits. Every round found defects in the previous fix: the two-letter rule text, case repair, frame guards, a series of leaky definitions of the name's contrast (ending in "a capital and a lowercase last letter"), a surname-list interaction, the lone-capital istitle() pitfall, and caseless letters (ʾ, ʼ, 李) stopping the last-letter scan. All are fixed and pinned by case rows. The last two commits (that caseless-letter fix, and making the scan's fall-through reachable after Codecov flagged it as dead code, with the same answers on 1.4M inputs) were reviewed together: no defects; the decisions.md#S2 recipe now states the extraction regex its input count depends on.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.90%. Comparing base (7394078) to head (71fea58).

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #577      +/-   ##
==========================================
+ Coverage   98.89%   98.90%   +0.01%     
==========================================
  Files          45       45              
  Lines        4070     4118      +48     
==========================================
+ Hits         4025     4073      +48     
  Misses         45       45              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.