[derek73]

Part of #752. Docs only: no parse moves except one new rules-corpus row.

Vocabulary phase 2's design was agreed on 2026-10-23, with the ; change, the title-batch order and the Nepali words decided on 2026-10-24. Sub-phases 2a and 2b are being built now, and their PRs need a committed record to cite. This PR writes that record, following docs/design/AGENTS.md's "Landing a design".

Where each part lands

• docs/design/vocabulary-model-rfc.md, Phase 2. It replaces "the shape that design starts from" with the agreed design:

  • the three sources of readings (vocabulary, declared name, shape);
  • the two derived markers, with may_be_initial kept as a flag;
  • the four-step gate (floor, form, structure, count), and where it does not reproduce the six rules it replaces (H3 and P5 stay floors; the acronym's nine decision sites stay);
  • the cue table;
  • the numeral predicate, fils and the agnomens, and joined and split credentials;
  • the front of the name;
  • abbreviated given names and brackets;
  • the surfacing split (Ambiguity.alternative in 2.x, Token.reading in 3.0);
  • the phase 1 reserved names;
  • sub-phases 2a to 2m and their dependencies.

  Unshipped behavior is written as intended ("is to"), and every "today" claim was checked against the tree.

• The RFC's Phase 3 and Phase 4 sections. Phase 3 now agrees with Phase 2: Ma. is settled in the default, and default = false gets its meaning in phase 2. The Phase 4 surname-span row notes that it shipped as the opt-in Policy(two_family_names=True) (rules/O6, Add a Policy switch for names with two family names (#754) #875, Fix the review findings on two_family_names (#875) #878), which a pack can later switch on.

• decisions/vocabulary-model.md. Three new entries:

  Entry	What it records
  2026-10-23 Phase 2: derive ambiguity from clashing readings and extend the gate to every reading kind #752	Every agreed decision as a numbered item, each with its reason and key measurement, plus the declined options with their evidence. A note says which rules changes wait for their sub-phase PRs.
  2026-10-24 Phase 2: derive ambiguity from clashing readings and extend the gate to every reading kind #752	Derek's later calls: the ; change, shipped in Read a semicolon between post-nominals as a comma (D15) #871. The title batches go in order of lone-head breakage. buddha, siddha and gyani go in the default gate; guru waits for a ne pack.
  2026-10-24 Read a surname written as two dotted initials as a name, not a credential (#864) #872	The paired-initials predicate the split merge is to share. The sa decline is left to decisions/C8.

  Other edits to the file:

  • two new Standing lines;
  • the Standing line on title-phrase modifiers is updated to the head-only rule;
  • decision 10 gains an unparked note, and decision 20 a note that phase 2 applies it in the default;
  • the Open handles for Phase 2: derive ambiguity from clashing readings and extend the gate to every reading kind #752 and Should Chas. Smith read given Chas.? Abbreviated given names read as titles today #789 are updated.

  The measurements are dated snapshots from a throwaway spike on 638685b4, with recompute commands where a figure drifts. Each sub-phase PR re-measures on its own base.

• mechanisms.md. New Verification shape PAIRED-SPELLINGS-PER-CHANGE: the spelling-consistency measure, with the trap the spike hit (comparing a family's last word as written counted 1,043 false "now apart" pairs).

• rules/S8. One deviates: #827 row, John Smith Ph. D. Jones → suffix Ph. D. Jones, since S8's wording already covers it. The rules corpus and snapshot are re-recorded for that one new row.

• AGENTS.md. One sentence: a cache keyed on files cannot see a switch set by environment variable.

Deliberately left in the gitignored spec

• The per-spike tables, the ctgov tally and the box-by-box PSC tables. They are evidence for decisions now recorded with their key figures, and each sub-phase PR re-measures.
• The Reading dataclass sketch. The RFC states the split and the fields; the exact API is 2m's design.
• Rules amendments for behavior whose statement changes: rules/H2's own example, rules/S1's ambiguous-class Except, the numeral wording of S8 and S10, and the front of the name. The decisions entry says these land with their sub-phase PRs under the same-PR amendment rule.
• No new Excluded entries. Listing vi to x is a Declined line; it is not a word refusal.

Open points recorded for later PRs

• 2e must say how the merged split credential, a member of the ambiguous class, can start S8's run, which S8 refuses an ambiguous member.
• 2h must measure the count-only agnomen gate before it lands. The measured gate also carried S6's case lean.

Checks

• Docs tests: uv run pytest tests/v2/test_design_docs.py tests/v2/test_doc_citations.py tests/v2/test_rules_doc.py passes, as does the full suite: 24,373 passed, 158 skipped, 3 xfailed.
• First design-docs review: 13 findings, all fixed in 0f62206. The main ones:
  • the split credential's S8 run start, recorded above as 2e's;
  • unshipped behavior written in the present tense;
  • the agnomen evidence;
  • Read a surname written as two dotted initials as a name, not a credential (#864) #872's scope;
  • dates attributed to the wrong entry;
  • positional pointers.
• Second review of the fix commit: six findings, all fixed in 077c1c7 (more present-tense claims, the last positional pointer, the sa decline, fil.toml existing already, Should Chas. Smith read given Chas.? Abbreviated given names read as titles today #789's Open handle).
• Not changed here: the second review noted that decisions/C8's 2026-10-25 Should Maria de Sa keep its surname, as Maria de Sá does? #857 entry puts the trailing DE SA leftover down to S6, where the spike pointed at the count. That is left for Take sa out of the vocabulary, so Maria de Sa keeps its surname (#857) #879's follow-up.

No real names from the local corpora: counts and token shapes only.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.07%. Comparing base (632685c) to head (077c1c7).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #881   +/-   ##
=======================================
  Coverage   99.07%   99.07%           
=======================================
  Files          47       47           
  Lines        4781     4781           
=======================================
  Hits         4737     4737           
  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.