review round: PR #517 findings

Three review agents on the whole PR. The order Background is narrowed
to what the code can implement -- a declared FAMILY-FIRST order
outranks the shape; an explicit GIVEN_FIRST is the default and cannot
be told apart from it -- and the two decisions.md restatements become
citations. The #470 citation is corrected (closed not-planned
2026-09-02, and it decided that prose in an Accepted clause is the
right home, not a workaround); the option-3 decline is scoped to
listings carrying the trace; the capability-claim lesson is
attributed to AGENTS.md axis 10; the zero-movers reason covers the
Turkic trigger too; the gate's unwitnessable conditions are recorded
as such.

The gate becomes a module-level helper so a reachability probe can
patch it back to the ungated condition and demand the 2.2.0 readings
return -- without it a refactor that stops the rotation reaching
family-first placement leaves all five stand-down rows green while
asserting nothing. O2's Accepted clause gains its pin; a peeled-title
parameter joins the East Slavic stand-down test. The #384 gate gets
its release-note bullet: it changes what 2.2.0 does for a supported
configuration, and corpus movement is not the house exemption.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: derek73

docs/design/decisions.md

@@ -140,17 +140,17 @@ P1. Rationale: a particle OPENING a name has the whole rest of the
     and no declaration has said this one ends before the string
     does. So `de Mesnil Jean` reports the whole string as the
     family, which is 1.4.0's reach as well (#471, declined by
-    design). One name
-    word means one UNIT — a particle chain (P2), a conjunction join
-    (P3) or a bound given-name pair (P5) is taken whole or not at
-    all. A title does not move the opening position (P4), but a
-    family comma does end the question: the comma has already fixed
-    the surname, so there is no positional read left for an order to
-    narrow, and a particle opening the part AFTER it takes the rest
-    of that part whatever order is declared. What is left over is not read by O4's rule for a whole name,
-    which would make the first leftover a second family name; it is
-    laid out as the positions AFTER the family in the declared order,
-    the family slot being already filled.
+    design). One name word means one UNIT — a particle chain (P2),
+    a conjunction join (P3) or a bound given-name pair (P5) is
+    taken whole or not at all. A title does not move the opening
+    position (P4), but a family comma does end the question: the
+    comma has already fixed the surname, so there is no positional
+    read left for an order to narrow, and a particle opening the
+    part AFTER it takes the rest of that part whatever order is
+    declared. What is left over is not read by O4's rule for a
+    whole name, which would make the first leftover a second family
+    name; it is laid out as the positions AFTER the family in the
+    declared order, the family slot being already filled.
       "de la Vega"                →  family="de la Vega"
       "Sir de Mesnil"             →  family="de Mesnil"
       "Mesnil de"  family-first   →  given="de"
@@ -966,7 +966,7 @@ C2. Rationale: text beyond the recognized comma parts should be
 ## Name order (O)
 
 Background: written name order varies by convention: given-first (the library's default reading), family-first, and family-first with the given name last (Vietnamese, where the person is called by the last element, given names are frequently two syllables — the given_names view stays correct wherever the internal boundary falls — and quốc ngữ is Latin script, so no native-script signal exists at all). The order is declared by the caller or a locale pack, never detected — but a few conventions leave a recognizable trace in the name itself. Patronymics are one: East Slavic names carry a father's-name derivative with distinctive endings between given and family, and Turkic names use a standalone marker word ("oglu" son-of, "qizi" daughter-of) after the father's name. Where such a trace is present and unambiguous, an opted-in parser can restore the intended reading from a family-first listing.
-A declared order is a property of the DATA SOURCE rather than of any one string: the caller sets it to match how their records are written, and it governs what no vocabulary and no script license has already claimed (O4) — it outranks what the parser could infer from the shape of a particular name, and yields where a name's own script settles the order instead (W4, where a name written wholly in an East Asian script reads family-first whatever order the caller declared). Two consequences run through this document. Under the default given-first order a string opening with a never-given particle is a surname whose given name is simply absent, so the fold takes the rest of it (P1). Under a declared family-first order the caller has already said that what follows the family is not more surname — so the fold stops there, and the rotations below, whose whole job is to RESTORE the default reading from a family-first listing, have nothing left to restore. A shape neither order settles is the family comma's job, and the parser does not guess at it.
+A declared order is a property of the DATA SOURCE rather than of any one string: the caller sets it to match how their records are written, and it governs what no vocabulary and no script license has already claimed (O4). A declared FAMILY-FIRST order outranks what the parser could infer from the shape of a particular name; the given-first reading is the parser's DEFAULT rather than a declaration it can tell apart from one, and the traces above are what refine it (O1, O2). And the declaration yields where a name's own script settles the order instead (W4, where a name written wholly in an East Asian script reads family-first whatever order the caller declared). Two consequences run through this document. Under the default given-first order a string opening with a never-given particle is a surname whose given name is simply absent, so the fold takes the rest of it (P1). Under a declared family-first order the caller has already said that what follows the family is not more surname — so the fold stops there, and the rotations below, whose whole job is to RESTORE the default reading from a family-first listing, have nothing left to restore. A shape neither order settles is the family comma's job, and the parser does not guess at it.
 
 O1. Rationale: an East Slavic name written family-first still shows
     its patronymic — the distinctive ending identifies which word is
@@ -987,16 +987,17 @@ O1. Rationale: an East Slavic name written family-first still shows
       "Иван Петрович Абрамович"  [ru]  →  family="Абрамович"  · boundary
     Accepted: under a declared family-first order the readings part
     on natural-order input, and the declaration wins. A family-first
-    listing reads the same either way — the first example above is
-    that same parse with FAMILY_FIRST declared — while with East
-    Slavic handling active and FAMILY_FIRST declared the
-    natural-order Иван Петрович Сидоров reads family Иван, given
-    Петрович, middle Сидоров. That is the caller's declaration being
-    honored on input they said was written family-first, not a
-    defect (#384). The example grammar takes one annotation, so a
-    pack and an order cannot share an example line; the parse is
-    pinned in tests/v2/test_locales.py and decisions.md#O1 records
-    why options 2 and 3 were declined.
+    listing reads the same either way under FAMILY_FIRST — the first
+    example above is that same parse with FAMILY_FIRST declared,
+    and under FAMILY_FIRST_GIVEN_LAST the listing's given and middle
+    swap, so only the family is invariant — while with East Slavic
+    handling active and FAMILY_FIRST declared the natural-order
+    Иван Петрович Сидоров reads family Иван, given Петрович, middle
+    Сидоров. That is the caller's declaration being honored on input
+    they said was written family-first, not a defect (#384). No
+    registered example annotation combines a pack with an order, so
+    the parse is pinned in tests/v2/test_locales.py instead, and
+    decisions.md#O1 records why options 2 and 3 were declined.
     history: decisions.md#O1 · implemented: nameparser/_pipeline/_post_rules.py
 
 O2. Rationale: a Turkic patronymic marker is a separate word that

docs/design/rules.md

@@ -18,6 +18,8 @@ Release Log
 
     - **Mark ba as an acronym that is also an ordinary name, so a bare trailing Ba keeps the family name.** ``HumanName("Anna Ba")`` gives last ``Ba`` and reports a suffix-or-name ambiguity, where 2.0.0 through 2.2.0 gave suffix ``Ba`` and no last name. The SPACED full-name form keeps the credential reading: ``John Smith BA`` still gives suffix ``BA``, now flagged, and the dotted ``John Smith B.A.`` is an unflagged suffix, the periods settling it. The COMMA forms move, and this is the marking's real cost: ``Smith, BA`` gives first ``BA``, and ``John Smith, BA`` gives first ``BA``, last ``John Smith``, where 2.0.0 through 2.2.0 gave suffix ``BA`` for both -- what ``Smith, Ed`` costs, which S2 already accepted for the other ambiguous acronyms. A bracketed or quoted ``John Smith (BA)`` falls through to nickname parsing, as the 2.0 note for ``ma``/``do`` below recorded for that pair. Write ``B.A.`` to keep the credential reading. BA is a common credential and Ba a real surname in Vietnamese and Senegalese Fula, which is the ``ma``/``Ma`` shape exactly. No corpus name moves (#342)
 
+    - **Fix the East Slavic and Turkic patronymic rotations overriding a declared family-first name order.** With ``patronymic_rules`` opted in and ``Policy(name_order=FAMILY_FIRST)``, ``Мицкевич Адам Юзеф`` gave last ``Адам`` through 2.2.0 and now gives last ``Мицкевич`` -- the reading the declaration asks for -- and ``oglu Ahmad Vali Ali`` with Turkic handling gave last ``Ahmad`` and now ``oglu``. The rotations exist to restore the given-first reading a family-first listing hides, so under a declared family-first order the declaration decides. No corpus name moves. See the ``O1`` entry of ``docs/design/decisions.md`` (closes #384)
+
     **Additions**
 
     - **Add the renunciate titles to the given-name title list, so a renunciate's one name is a given name.** ``HumanName("Swami Vivekananda")`` gives first ``Vivekananda`` with an empty last name, where every release since 1.4.0 gave last ``Vivekananda``; ``Guru Nanak``, ``Baba Ramdev`` and ``Lama Zopa`` move the same way, and so do the Devanagari and Bengali spellings added below. Two name words behind the title are unchanged -- ``Swami Vivekananda Saraswati`` keeps last ``Saraswati`` -- and a surname-retaining title is untouched: ``Rabbi Cohen`` still gives last ``Cohen``. ``venerable`` is deliberately not in the list, the traditions using it splitting on whether the family name survives. See the ``indic-honorifics`` entry of ``docs/design/decisions.md`` (closes #346)

docs/release_log.rst

@@ -65,6 +65,23 @@
 _RENDERS_ELSEWHERE = frozenset({Role.TITLE, Role.NICKNAME, Role.MAIDEN})
 
 
+def _rotations_apply(state: ParseState) -> bool:
+    # Both patronymic rotations RESTORE the given-first reading a
+    # family-first listing hides, so rules.md#O1's scope clause holds
+    # them to the default order: a caller who declared family-first has
+    # already said what the rotation would infer, and position decides
+    # (decisions.md#O1, the 2026-09-07 entry on #384). `state.order`,
+    # not policy.name_order, for the reason the P1 fold gives -- a
+    # script_orders entry can override the policy, and the roles the
+    # rotations read are the ones assign actually made. None means
+    # assign positioned nothing: a family comma (which the NO_COMMA
+    # test already excludes) or an early return with no name piece to
+    # position, so there is no declaration to defer to and the
+    # rotation's own shape test decides.
+    return state.structure is Structure.NO_COMMA and (
+        state.order is None or state.order[0] is Role.GIVEN)
+
+
 def _mark_suffix_entries(tokens: list[WorkToken], state: ParseState) -> None:
     # In place over the caller's token list, the way every other rule
     # in post_rules writes: a state-in/state-out spelling here cost
@@ -462,18 +479,7 @@ def post_rules(state: ParseState) -> ParseState:
     # middle_as_family fold below runs comma or not (v1 order:
     # patronymics first, then handle_middle_name_as_last)
     rules = state.policy.patronymic_rules
-    # Both rotations RESTORE the given-first reading a family-first
-    # listing hides, so rules.md#O1's scope clause holds them to the
-    # default order: a caller who declared family-first has already
-    # said what the rotation would infer, and position decides
-    # (decisions.md#O1, the 2026-09-07 entry on #384). `state.order`,
-    # not policy.name_order, for the reason the P1 fold above gives --
-    # a script_orders entry can override the policy, and the roles the
-    # rotations read are the ones assign actually made. None means
-    # assign consulted no order at all, which is the default reading.
-    read_order = state.order
-    rotations_apply = state.structure is Structure.NO_COMMA and (
-        read_order is None or read_order[0] is Role.GIVEN)
+    rotations_apply = _rotations_apply(state)
     # rules.md#O1: "a name of exactly three name words — titles,
     # suffixes and nicknames aside — whose last name word carries a
     # patronymic ending and whose middle name word does not reads as

nameparser/_pipeline/_post_rules.py

@@ -123,19 +123,25 @@ def test_no_swap_when_more_fields_present() -> None:
 #: word. This column is the negative control: it is the reading the
 #: two stand-down tests below exist to prevent, recorded as data and
 #: re-measurable (`pip install nameparser==2.2.0`) rather than left in
-#: a comment. Nothing asserts on it -- what the tests assert is the
-#: expected column -- but a failure quotes it, so a rotation that
-#: fires again says so in the message.
+#: a comment. The stand-down tests do not assert on it -- what they
+#: assert is the expected column -- but a failure quotes it, so a
+#: rotation that fires again says so in the message. The vacuity probe
+#: below DOES assert on it, which is what keeps this column honest.
+#: The key is (input, declared order): each input picks out its own
+#: pack, `Мицкевич` being East Slavic and `oglu` Turkic, so no pack
+#: identifier is needed to disambiguate a row.
 _PRE_GATE_FAMILY = {
     ("Мицкевич Адам Юзеф", FAMILY_FIRST): "Адам",
     ("Мицкевич Адам Юзеф", FAMILY_FIRST_GIVEN_LAST): "Юзеф",
+    ("Dr. Мицкевич Адам Юзеф", FAMILY_FIRST): "Адам",
+    ("Dr. Мицкевич Адам Юзеф", FAMILY_FIRST_GIVEN_LAST): "Юзеф",
     ("oglu Ahmad Vali Ali", FAMILY_FIRST): "Ahmad",
     ("oglu Ahmad Vali Ali", FAMILY_FIRST_GIVEN_LAST): "Ali",
 }
 
 
 def _assert_rotation_stood_down(pack: Policy, order: Policy, text: str,
-                                family: str) -> None:
+                                family: str, title: str = "") -> None:
     """The pack opted in under `order` reads `text` exactly as `order`
     alone reads it, family included."""
     out = _parsed(text, dataclasses.replace(pack,
@@ -149,6 +155,7 @@ def _assert_rotation_stood_down(pack: Policy, order: Policy, text: str,
         f"the pack changed the reading; before the gate the 2.2.0 "
         f"wheel read family {pre_gate!r} here")
     assert _by_role(out, Role.FAMILY) == family
+    assert _by_role(out, Role.TITLE) == title
 
 
 def test_east_slavic_rotation() -> None:
@@ -181,9 +188,18 @@ def test_east_slavic_skips_when_middle_is_also_patronymic() -> None:
     assert _by_role(out, Role.FAMILY) == "Abramovich"
 
 
+@pytest.mark.parametrize("text,title", [
+    ("Мицкевич Адам Юзеф", ""),
+    # a peeled title must not move the shape the gate is claimed of:
+    # rules.md#O1 counts name words "titles, suffixes and nicknames
+    # aside", so the rotation still reaches this input pre-gate
+    # (_PRE_GATE_FAMILY records the same family as the bare form) and
+    # the title has to survive the stand-down
+    ("Dr. Мицкевич Адам Юзеф", "Dr."),
+])
 @pytest.mark.parametrize("order", _FAMILY_FIRST)
 def test_east_slavic_stands_down_under_a_declared_family_first_order(
-        order: Policy) -> None:
+        order: Policy, text: str, title: str) -> None:
     # rules.md#O1's scope clause (decisions.md#O1, 2026-09-07, #384):
     # the rotation RESTORES the default reading a family-first listing
     # hides, so a declared family-first order supplies that reading and
@@ -196,8 +212,7 @@ def test_east_slavic_stands_down_under_a_declared_family_first_order(
     # order class and the two place the given name differently: the
     # rotation rewrote a different word under each (_PRE_GATE_FAMILY),
     # so one order alone would leave the other's reading unpinned.
-    _assert_rotation_stood_down(_ES, order, "Мицкевич Адам Юзеф",
-                                "Мицкевич")
+    _assert_rotation_stood_down(_ES, order, text, "Мицкевич", title)
 
 
 def test_east_slavic_off_by_default() -> None:
@@ -226,6 +241,30 @@ def test_turkic_stands_down_under_a_declared_family_first_order(
                                 "oglu")
 
 
+def test_the_order_gate_is_what_stands_the_rotations_down(
+        monkeypatch: pytest.MonkeyPatch) -> None:
+    """Reachability probe: with the gate patched back to the ungated
+    condition, every stand-down input must rotate again, reading the
+    family _PRE_GATE_FAMILY records from the 2.2.0 wheel. If this
+    fails green-side, the stand-down rows above have gone vacuous --
+    the rotation no longer reaches their inputs."""
+    from nameparser._pipeline import _post_rules
+    monkeypatch.setattr(
+        _post_rules, "_rotations_apply",
+        lambda state: state.structure is _post_rules.Structure.NO_COMMA)
+    for pack, text in ((_ES, "Мицкевич Адам Юзеф"),
+                       (_ES, "Dr. Мицкевич Адам Юзеф"),
+                       (_TK, "oglu Ahmad Vali Ali")):
+        for order in (_FF, _FFGL):
+            policy = dataclasses.replace(pack,
+                                         name_order=order.name_order)
+            out = _parsed(text, policy)
+            assert _by_role(out, Role.FAMILY) == \
+                _PRE_GATE_FAMILY[text, policy.name_order], (
+                f"{text!r} no longer reaches the rotation under "
+                f"{policy.name_order}; the stand-down rows are vacuous")
+
+
 def test_leading_never_given_particle_folds_into_family() -> None:
     # v1 handle_non_first_name_prefix: a leading particle that is never
     # a given name ('de') means the whole name is a surname

tests/v2/pipeline/test_post_rules.py

@@ -14,7 +14,8 @@
 from nameparser import Locale, Parser, locales, parse, parser_for
 from nameparser._lexicon import _VOCAB_FIELDS, Lexicon
 from nameparser._policy import (
-    FAMILY_FIRST, UNSET, PatronymicRule, Policy, Script, _SCRIPT_RANGES,
+    FAMILY_FIRST, FAMILY_FIRST_GIVEN_LAST, UNSET, PatronymicRule, Policy,
+    Script, _SCRIPT_RANGES,
 )
 from nameparser._types import AmbiguityKind
 from nameparser.locales import ja as _ja
@@ -773,6 +774,30 @@ def test_the_rotation_stands_down_under_a_declared_family_first_order(
         "Иван", "Петрович", "Сидоров")
 
 
+def test_the_turkic_marker_lands_in_a_name_field_under_both_orders(
+        ) -> None:
+    """Pins the prose decisions.md#O1's 2026-09-07 entry states for O2.
+
+    Gate-independent: `Ali Ahmad Vali oglu` is natural-order input,
+    so the rotation would not fire on it under the default order
+    either. What the two readings show is O2's own 2026-07-02
+    Accepted consequence reached by a second route -- a declared
+    family-first order leaves the marker standing in a name field.
+    Under FAMILY_FIRST that costs nothing visible, the family being
+    the word the rotation would have chosen anyway; under
+    FAMILY_FIRST_GIVEN_LAST the marker becomes the GIVEN name, which
+    is the reading rules.md#O2 carries as Accepted.
+    """
+    ff = parser_for(locales.TR_AZ, base=Parser(
+        policy=Policy(name_order=FAMILY_FIRST)))
+    n = ff.parse("Ali Ahmad Vali oglu")
+    assert (n.family, n.given, n.middle) == ("Ali", "Ahmad", "Vali oglu")
+    ffgl = parser_for(locales.TR_AZ, base=Parser(
+        policy=Policy(name_order=FAMILY_FIRST_GIVEN_LAST)))
+    n = ffgl.parse("Ali Ahmad Vali oglu")
+    assert (n.family, n.given, n.middle) == ("Ali", "oglu", "Ahmad Vali")
+
+
 def test_locales_import_is_lazy(monkeypatch: pytest.MonkeyPatch) -> None:
     # importing the package must not import any pack module; PEP 562
     # loads them on first attribute access (the lazy-access contract: