[derek73]

Closes #815

N3 (the lone-word nickname rule) now sets a suffix aside, as H1 (a title and one name word) and M4 (a maiden marker makes the lone name word the family) already do. A nickname, one name word and a suffix read the word as the family name and no longer report given-or-family:

'Smitty' Jones Jr.    2.0.0–2.8.2: given 'Jones', family ''  (+ given-or-family since 2.3.0)
                      now:         family 'Jones', suffix 'Jr.'
Jones (Smitty) PhD    same move

This is option A from the issue, chosen with the Nepal cost below accepted.

How

N3's early count in _assign_main (one piece in the segment) is unchanged. The suffixed shape is decided at O5's given-or-family site, after the trailing peel has set the suffix aside and after O5's own clauses (no title, maiden name or script order; the word not an initial, bound given name or particle) have said nothing else decided it. A nickname there takes the family and the report goes. The scan is gated on state.extracted, so a name with no delimited clause pays no frame: Madonna, Smith Jr. and the reference name keep master's call counts, and the moved names get cheaper ('Smitty' Jones Jr. 233 → 217).

Reach, each pinned by a case row:

• A nickname in any part of the name: Jones Jr., 'Smitty' → family. The early count reads the nickname this way too.
• An S1 credential clause: Jones (PhD) Jr. → family. The clause still carries the nickname role at assign, and the bare Jones (PhD) already read family.
• Words outside O5's claim list: a given name written short ('Smitty' Chas. Jr.) and a period-shaped word ('Smitty' Xyz. Jr.) → family.
• An ambiguous acronym in capitals: 'Smitty' Jones ING → family, because S4 reads it as the suffix.

Not reached, by design:

• Read as a second name word: a one-letter numeral (V, S10), the gated words fils, Junior and KC (S11), and a Title case acronym (Ing, S4).
• A title word as the one word: 'Smitty' Pope Jr. keeps H4's title-or-name (new N3 Precedence bullet).
• A nickname alone before a comma, or an empty head: 'Smitty', Jones Jr. and , 'Smitty' Jones Jr. stay given.
• Claimed words beside a suffix: 'Smitty' J. Jr. stays given (N3's Except), while bare 'Smitty' J. reads family. That inconsistency predates this PR and is recorded in Accepted rather than widened.

Under the family-first orders the field was the family already; only the report goes.

Measured moves (2026-11-05, comparator: master 90a9a86)

Source	Moves	Names that could move*
committed corpora (test_snapshot.py)	1: 'Smitty' Jones Jr.	—
cldr_agreement.py, every view	0	—
fec-individuals (--base)	0	10 of 1,893,964
ctgov-officials	0	6 of 352,104
govuk-people	0	1 of 6,021
ukec-individuals, tse-donors, dof-signatures	0	0
psc-individuals agreement (--base)	matches the base	—
nepal-candidates	3, all worse, accepted	3

* Names that parse with a nickname, a suffix, no middle name and exactly one of given and family.

The Nepal three each have a surname the suffix vocabulary also lists (Od, D.C, जी.सी.) beside a clan name in brackets that was read as a nickname: Rewati Od (Mahar), Sumnime D.C(Oli), गोपाल जी.सी.(घर्ती क्षेत्री). The given name went from given with a report to family with none.

The snapshot.jsonl diff holds the one move plus new rule-example and shape-inventory entries.

Docs (same-PR amendment)

• rules/N3:
  • Then: "whatever suffix stands beside them".
  • Except: an initial (T5, T4), a bound given name (P5) or a particle (P4) keeps its reading beside a suffix.
  • Precedence: a title word left as the one name word is H4's.
  • Accepted: the Nepal cost; the bare claimed word; the comma reach.
  • rules_budget.json re-recorded; N3 grew.
• rules/O5: N3's Except bullet and examples. M4's exception now names only the given-name and initial claims, since M4 flips a particle.
• rules/M4: its nickname bullet.
• decisions/N3: the 2026-11-05 Should 'Smitty' Jones Jr. read family 'Jones', as 'Smitty' Jones does? (N3 counts a suffix; H1 and M4 set it aside) #815 entry, with the counts, the populations and the comparator.
• decisions/H1: the Open line is closed and the Dr. Smith née Jones reports no family name — a maiden name suppresses the title-plus-one-word rule #410 head marked. The heads of decisions/O5's parse("Andrew") reports no ambiguity, but given-or-family is a guess #449 and decisions/M4's parse("Smith née Jones") reports no family name — a maiden clause empties a one-word name, where 1.4.0 kept it #445 entries are marked superseded in part.
• shapes.py: a nickname-and-suffix arrangement under each order.
• Release log: one Change bullet.

Tests and negative controls

• test_parser.py suffix grid: 440 rows (5 nickname spellings × 4 word spellings × 11 suffixes × the default and FAMILY_FIRST orders). FAMILY_FIRST_GIVEN_LAST reads every row as FAMILY_FIRST does, by roles, tags and reports. It compares as_dict() whole and takes 0.05s.
  • Control: all 440 rows fail on master 90a9a86; none fail on the branch.
• Claimed-word test: 5 rows. Control: moving the nickname test ahead of the claim clause flips all 5 to family.
• cases.py: 18 new rows, and the existing row renamed and flipped. The field-sweep count goes from 1647 to 1662.
• Runs: uv run pytest, -n0 -m serial (the frame band holds), mypy, ruff, and Python 3.15 in its own environment all pass.

Reviews

Round 1, on fc83ff2:

• pr-review-toolkit:code-reviewer: no code defect. Fixed the release-log range (2.8.0 → 2.8.2, the report since 2.3.0) and gated the scan on state.extracted, which removes the frames it found on lone words with no nickname.
• pr-review-toolkit:pr-test-analyzer: fixed.
  • Added rows for the title word (H4 Precedence), caps vs Title case acronyms, gated words, VI and Ph. D., a quoted nickname after the word, the comma reach, the period shape and the given abbreviation.
  • Corrected the grid comment that said the caps acronyms don't move.
• pr-review-toolkit:comment-analyzer: fixed the release-log range and the limit sentence, the cross-segment reach, the stale comment wraps and the case-note version range.
• design-docs-reviewer: fixed.
  • The false "as under M4" particle claim; the stale grid size; unrecorded reach (comma, S1).
  • Then's universal (added the H4 Precedence and the comma Accepted bullets); the decisions/H1 Dr. Smith née Jones reports no family name — a maiden name suppresses the title-plus-one-word rule #410 head; the population for each zero; the uncited Except legs.
• /simplify (reuse, simplification, efficiency, altitude):
  • Applied: parse each bare name once; drop the order that reads identically; compare as_dict() whole; remove the tautological control test; state the N3 handoff once; collapse the count history.
  • Altitude: no finding. Merging the two N3 sites would move readings and cost 25 frames on 'Smitty' Jones.
  • Skipped: dropping grid-duplicated case rows, which would move the snapshot.

Round 2, on the fix commits 430e59d and 50b1736:

• code-reviewer: the gate is reading-neutral. It was fuzzed with asserts over 6,811 corpus names under seven parsers plus 60,000 random strings, and dropping FFGL loses nothing. Fixed three rows mislabelled parity: 'Smitty' J. Jr. → fix(suffix-routing), 'Smitty' Jones, Jr. → fix(Should parse("Smith, Jr.") put "Jr." in title rather than suffix? #296), 'Smitty' Pope Jr. → feat(An input composed entirely of titles should report an ambiguity — "The Right Hon. the President of the Queen's Bench Division" #491).
• pr-test-analyzer: both controls hold. Fixed the Xyz. mechanism (case note and decisions entry), the grid parse count (480) and the missing empty-head row.
• design-docs-reviewer: fixed.
  • The Nepal suffixes are vocabulary readings, not dotted-shape ones.
  • N3's Except lead now lists exactly its three readings.
  • O5's M4 exception no longer contradicts M4 on particles.
    Round 3, on the round-2 fix commit 1991581:
• design-docs-reviewer: three prose and label errors, no reading errors; all fixed in the last commit.
  • जी.सी. is listed nowhere. It reads as a suffix through its chunk जी, a hi/mr honorific that period_joined_vocab takes as a suffix chunk; removing that honorific leaves it family. Corrected in decisions/N3 and in the Accepted bullet.
  • O5's M4 exception narrowed to a bound given name and an initial, since Chas. née Jones → family.
  • 'Smitty' Pope Jr. relabelled fix(#489), the title-peel floor that moved it; An input composed entirely of titles should report an ambiguity — "The Right Hon. the President of the Queen's Bench Division" #491 added only the report.
• Follow-up noted, not fixed here: rules/M4's own Except says "a word the vocabulary has claimed as a given name", which is wider than its code (bound given names only). The wording predates this PR; it is M4's to fix.

🤖 Generated with Claude Code