[derek73]

Closes #748. Follows #757 (merged), whose nameparser/vocab/README.md it links to and which now links back. Rebased onto master as one commit after #757's squash; the earlier review rounds ran on its pre-squash commits, whose final tree this matches.

What. A design overview of the vocabulary model, beside nameparser-2.0-rfc.md. decisions/vocabulary-model stays the record and wins where they differ.

• Why readings replaced the sets; phase 1 as shipped.
• Phase 2: ambiguity derived from readings and a gate for every reading kind. fils is the worked case (a today vs gated table, emulated). It lists the gates that exist today as six rules, one per class of word (S3/S4/S6, S10, H3, P4, P5, P8), and restates phase 2 as making the gate a property of a reading. It covers the contested-head rule for titles at the front.
• Phase 3: prefer and strict packs. Decision 15's asymmetry is worked through do (John Smith DO); a pack can outrank a shape rule (Ma.). It records that decisions 6 and 15 reverse Locale packs for Alexandre Dumas fils and Jiří Dienstbier ml.: generational words that collide outside their language #684's premise: a French pack keeps both French readings of fils, so the gate, not a pack, keeps Marie Fils's family name.
• Phase 4: order versus shape (measured on Family–Title–Given), the rules a pack can choose with measured gaps, and the output model.
• First packs: left to Vocabulary model and language packs (tracking) #747.

Also: decisions/vocabulary-model's reserved-name list gains prefer and strict, reserved in build.py since #737, and decision 11 is widened to words a file refuses (Derek, 2026-10-19), matching fils in fr.toml; the README links to the RFC.

Verification. Every "today" parse was re-measured on e9855df0; corpus counts carry their date and tree, and the review recounted 315/390 and 0/60 from the agreement records. A docs-review pass ran the twelve axes, and its findings are fixed: the gate inventory, the S3 citation, the #684 reversal, the stale reserved-name list, a Van Buren example that contradicted decision 4, the decision 11 wording against fils, and open questions now linked to their issues. Content traceable to a private source was removed, including the ranked first-pack list. A second review of that fix commit found the gate list still wrong (generation words, titles and bound given names are gated by S10, H3 and P5), the John Smith D.O. example falsified by S3, decision 11 unamended, a ranking the corpus sampling produced, and a strict-pack example decision 6 does not support; all fixed in the last commit.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.05%. Comparing base (991a6f9) to head (d5f136f).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #758   +/-   ##
=======================================
  Coverage   99.05%   99.05%           
=======================================
  Files          47       47           
  Lines        4642     4642           
=======================================
  Hits         4598     4598           
  Misses         44       44           

☔ 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.