docs(design): the three keystone decisions from the post-#381 backlog review - #386

Grouping is vocabulary's job and is order-independent; assignment
is name_order's job. #364, #365 and #368 are one question seen
from three angles: P1's fold sites and P2's chain are expressed
over ROLES, and roles come from _effective_order, so both rules'
coverage varied with the declared order by accident rather than by
design.

P1 now states that the fold takes the particle and the ONE name
word it attaches to. "Takes everything" was never argued for -- it
was the shape of v1's handle_non_first_name_prefix. Measured
against the three differential corpora (782 names), filtered to
the shape that actually changes, this moves exactly one name,
"de Mesnil Garcia"; #364's warning that "each ledger would need
re-examining" was written without the filter.

#368 REVERSES: shipped behavior is correct. A mid-name chain has a
head word and is positioned like any other group, so
"Juan de la Vega" under FAMILY_FIRST is family="Juan". What
NON_GIVEN_NAME_PARTICLES guarantees is that the bare word never
reads as a given name, not that no name part may begin with one.
The asymmetry with the leading case is P4's: a leading particle
chains nothing, so without the fold pure position makes the bare
particle the given name -- measurable today on the ambiguous half,
where "van Mesnil Juan" gives given="van". The deviates: marker
comes out and the issue closes won't-fix.

New rule P6 records the trailing orphan: a particle ending the
name attaches to the family beside it and renders before it,
scoped to the comma form. The words-to-spare guard is load-bearing
-- #379's own subject "van" is in the ambiguous half, so a
never-given-only rule would not fix the issue it was filed for,
while an unguarded rule breaks Vietnamese "Nguyen, Van".

Rules P1 and P6 carry deviates: markers for #364, #379 and #380;
P6 has no implemented: pointer because nothing implements it yet.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

#326 asks whether suffix should split into generation and
credentials, arguing the split is tractable because "the
vocabulary is already split". That was true when the issue was
written (2026-08-02). The 2.1.0 East Asian work landed five days
later and put 24 postnominal honorifics -- 20 CJK, 4 Hebrew -- in
suffix_words, which now reads 11 generational, 5 neither, 24
honorific. The largest group is neither of CLDR's two buckets, so
"adopt CLDR's model" is not available as the cheap answer.

Decision: do not split. Record the composition so #296, #291, #325
and #289 stop waiting on a distinction the model cannot express,
and note the question this leaves unexamined -- whether the
honorifics belong in `suffix` at all, given rules.md#W3 already
calls an honorific "no part of the name on either side".

Recorded as a failure mode rather than a fact: the field widened
three times without any step being recorded as a widening of its
MEANING. rules.md#S2's Background still calls it "two different
things", accurately as written. The rules doc pinned the behavior;
what slipped is the field's definition, which no rule owns.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Review question: are the numbers in these entries useful later?
Audited what this branch introduced. rules.md is clean -- no bare
numbers, only rule IDs, which is right for a normative doc. The
perishable counts are all in decisions.md, and they split three
ways.

Counts that carry an argument stay: "245 of 782 comma names,
exactly one with a trailing particle" IS the corpus-blindness
finding, and the two one-name movers are the findings themselves.

One count carried no argument and is deleted rather than dated:
"over all 782 names of the three differential corpora" becomes
"over every name in the three differential corpora". The phrase
already said whole-corpus-no-prefilter; the integer only offered a
way to go stale.

The two vocabulary compositions get a recompute one-liner. These
are the #326 hazard reproduced one level up -- the suffix entry's
own thesis is that #326 quoted a composition and rotted in five
days, and the mitigation I gave it was a date, which is the same
mitigation #326 had. decisions.md's convention already makes dated
entries frozen evidence; what was missing is a way for a reader who
wants today's answer to get it without trusting the snapshot. A
test asserting the counts is explicitly declined in the entry: that
is the constant-content pattern and would fail on every legitimate
vocabulary addition.

AGENTS.md gains the general rule, since this will recur wherever an
entry quotes something that drifts.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Two findings from a targeted pass over the contested pairs this
branch creates. Prose reading found neither; naming the pairs and
interrogating them one at a time found both.

P6 and S2 contest "Berg, Jan vd" -- today S2 wins and reports
suffix="vd", while P6's marker asserts family="vd Berg". Nothing
said who wins. P6 does, and its statement now says so, which is how
rules.md pins a contest (H2, M1 and W3 all carry precedence
clauses in their statements; _CROSS_RULE_WINNERS is the ledger's
instrument, not this document's). The precedence is scoped so it
cannot creep: both particle and suffix vocabulary, trailing-orphan
position, family comma, given word to spare. "John Smith, PhD" and
"Smith, Jr." are not particles; "Jong, vd" has no given word left.

R2's #385 resolution moves R3's output and R3 was silent about it.
Initials read the BASE family word, so anchoring "Do" takes
parse("Anh Do").initials() from "A." to "A. D."; R3 now carries its
own deviates: marker, plus the "Juan van der" row where no borne
name means no base and initials stay "J.". The general lesson is
recorded with it: a marker lands on the rule whose STATEMENT
changed, but a rule can move another rule's OUTPUT without touching
its statement, and the runner cannot see it -- an unmarked
downstream rule stays green because its own examples avoid the
input. Walk `interacts:` when adding a marker.

AGENTS.md's primary-source rule gains its missing scope. It was
written for CROSS-SESSION distillation, where the source transcript
is an artifact independent of the reviewing session -- #381
harvested nine such sessions. Same-session design work has no such
artifact, and the instruction degenerates into re-reading the
memory that produced the error. The amendment names both shapes and
records the measured yield ordering from this branch: re-derived
measurements 2, spec-vs-doc fidelity 1, named contested pairs 2,
unaided prose reading 0.

Not decided here: whether a rule with no implemented: pointer (P6
is the first) is a shape rules.md wants.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Running the axis named in the previous commit, over the rules this
branch touched and the decision entries they rest on.

P1's statement said the fold takes "the particle and the ONE name
word it attaches to" -- contradicted by its own example, since
"de la Vega" is two particles onto one word. Now "the particle
run", with a clause saying the run is every particle in sequence,
never-given and ambiguous alike. decisions.md#P1's #364 entry
carried the same wording and is corrected with it, as is the P1
excerpt quoted in _post_rules.py.

P6's precedence over S2 is stated for a SHAPE ("where the word is
both a particle and suffix vocabulary"), but
decisions.md#vocabulary-collisions C-ii says precedence between two
non-name readings is a per-word frequency judgement. Measured,
three words are both: vd, do and mc. Only vd was weighed, so do and
mc inherit its answer unexamined. Recorded on both sides rather
than papered over -- stating a per-word judgement as a general
clause is how an unexamined word acquires a decision, and naming
the two lets the next reader see which was actually argued.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

The exactly-one-pointer guard added two commits ago claimed more
than it enforced. Its docstring said a shipped rule "cannot keep a
stale tracking pointer once its issues close", but the test reads
the doc only and cannot see code. Meanwhile
test_implemented_matches_citing_modules skipped any rule without
implemented:, so a rule that gained code and a citation while
keeping tracked: passed both. That is exactly the state the
docstring called unrepresentable.

The citations test now handles the tracked: branch, and the
docstring states its own scope instead of the pair's: neither test
alone makes a stale pointer unrepresentable, the pair does.
Mutation-tested on the finding's own scenario -- adding a P6
citation to _post_rules.py while leaving tracked: in place now
fails with the swap instruction, and the restore was verified by
diff.

The DEVIATION note on P1 wrote its example values in double quotes,
which put four extra quoted spans inside the citation block that
test_citations_are_verbatim_excerpts parses -- it passed only
because the check takes the FIRST span. Moving the note above the
citation line, a natural edit, would have made the excerpt resolve
to "de Mesnil Juan" and failed against prose that is entirely
correct. Values are unquoted now, and the note says why so the next
editor does not helpfully re-add them.

Considered and rejected: asserting exactly one quoted span per
citation block, which would be the unrepresentable-states fix.
Measured first -- 38 blocks carry one, but _group.py's M1 block
legitimately carries six, so the invariant does not hold today and
imposing it would mean rewriting an unrelated comment.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>