docs(design): coherence-pass fixes, and scope the primary-source rule

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>

Author: derek73

AGENTS.md

@@ -116,6 +116,24 @@ state which tree each measurement ran on (stale fetches produced
 three rounds of already-fixed findings), and landed corrections are
 re-verified here before committing.
 
+Two shapes, needing different instruments. CROSS-SESSION distillation
+is what the rule above is written for — the #381 arc harvested nine
+named sessions, and for each the source transcript is an artifact
+independent of the reviewing session, so "review your own sections"
+is a two-artifact comparison. SAME-SESSION design work (#386) has no
+such artifact: spec and docs were written in one context, so the same
+instruction degenerates into re-reading the working memory that
+produced any error, and the rationale inverts — when the source is
+NOW, the source is what got it wrong. There, compare against
+artifacts instead, in this measured order of yield: re-derive every
+number with a freshly written script (2 wrong claims on #386);
+re-read the written spec against a checklist for FIDELITY, not just
+presence (1); interrogate NAMED contested rule pairs one at a time
+(2). Unaided prose reading found none — so a general "coherence read"
+by the author is the one form to distrust, because a green report
+from the weakest instrument manufactures confidence rather than
+supplying it.
+
 **Guard tests** SHOULD carry a recorded negative control — the
 answer with the guard off, stored as data (the _EXCLUSION_EFFECT
 shape; see mechanisms.md's Verification shapes).

docs/design/decisions.md

@@ -237,6 +237,25 @@ not).
   as evidence about the corpus, not about the blast radius, and
   run tools/differential at all three baselines in the implementing
   PR regardless of how small this looks.
+- 2026-08-16 (pre-merge coherence pass) — P6 and S2 CONTEST
+  "Berg, Jan vd": today S2 wins and reports suffix="vd", while
+  P6's marker asserts family="vd Berg". P6 wins, and the rule says
+  so in its statement rather than leaving the pair to file order.
+  The reason is C-ii's, not a new judgement: vd as the British
+  Volunteer Decoration is rarer than vd as van der, and a trailing
+  abbreviation AFTER A FAMILY COMMA is the tussenvoegsel position
+  specifically.
+  Scope check on the precedence, so it cannot creep: it reaches
+  only words that are both particle and suffix vocabulary, in the
+  trailing-orphan position, under a family comma, with a given word
+  to spare. "John Smith, PhD" and "Smith, Jr." are untouched (not
+  particles), and "Jong, vd" is untouched (no given word remains),
+  which is why that row stays out of scope rather than becoming a
+  counter-example.
+  Recorded because the pair was declared in `interacts:` and left
+  unresolved — `interacts:` is advisory by design and pins nothing,
+  so a declared interaction is a prompt to state the outcome, not a
+  substitute for stating it.
 
 Open: [#380](https://github.com/derek73/python-nameparser/issues/380)
 covers "Berg, Jan vd" under this rule, but the vd reading itself is
@@ -1273,6 +1292,20 @@ Declined:
 - Still open inside the resolution: whether "Do" remains in
   family_particles once it is also the base. Recorded here rather
   than left to the implementing PR to decide by accident.
+- 2026-08-16 (pre-merge coherence pass) — the resolution moves R3
+  too, and R3 now carries its own marker. Initials read the BASE
+  family word, so anchoring "Do" changes
+  parse("Anh Do").initials() from "A." to "A. D." while
+  "Juan van der" stays "J." (no borne name, no base, and initials
+  of a bare particle run would be nonsense).
+  The general lesson, worth more than this instance: a deviates:
+  marker gets written on the rule whose STATEMENT changed, but a
+  rule can change another rule's OUTPUT without touching its
+  statement, and nothing looks for that — the runner asserts per
+  example line, so an unmarked downstream rule stays green
+  precisely because its own examples avoid the affected input.
+  When adding a marker, walk the changed rule's `interacts:`
+  targets and ask whether any of THEIR examples move.
 
 ### removed-v1-surface
 

docs/design/rules.md

@@ -256,7 +256,11 @@ P6. Rationale: a particle ending the name has nothing to link
     ending the name attaches to that family name and is written
     before it — provided at least one given word remains, so that a
     name whose only given word is the particle keeps it (the
-    words-to-spare test S2 applies to ambiguous suffixes).
+    words-to-spare test S2 applies to ambiguous suffixes). Where
+    the word is BOTH a particle and suffix vocabulary, this
+    attachment outranks the suffix reading (S2): a trailing
+    abbreviation after a family comma is the tussenvoegsel far more
+    often than the decoration it collides with.
       "Jong, Anke de"             →  family="de Jong"  deviates: #379 (today: family="Jong")
       "Beethoven, Ludwig van"     →  family="van Beethoven"  deviates: #379 (today: family="Beethoven")
       "Berg, Jan vd"              →  family="vd Berg"  deviates: #380 (today: family="Berg")
@@ -758,8 +762,14 @@ R3. Rationale: initials abbreviate the person's name words; titles,
     family word; titles, suffixes, particles and nicknames
     contribute nothing.
       "Dr. Juan Q. Xavier de la Vega III"  →  initials="J. Q. X. V."
+      "Anh Do"                    →  initials="A. D."  deviates: #385 (today: initials="A.")
       "Sean O'Connor"             →  initials="S. O."  · boundary
-    implemented: nameparser/_render.py
+    Accepted: a family that is ALL particles contributes nothing,
+    so the initials are the given words alone — "van der" has no
+    borne name to anchor a base (R2), and initials of a bare
+    particle run would be nonsense.
+      "Juan van der"              →  initials="J."
+    history: decisions.md#R2 · interacts: R2 · implemented: nameparser/_render.py
 
 R4. Rationale: case repair is a display concern, applied only on
     request and never destructively.