Rethink the maiden-marker rule (M2): a marker stands after the current name and takes words up to the trailing suffix run

Implemented in #609 (with #602). The tables below show the branch's readings. Where the shipped behavior differs from the prototype's, the row says so.

Why. M2 grew by patching, and it is now one of the longest rules in rules.md. Each of #424, #533, #535, #538 and #549 added a stop, an exception or a release check, and the decisions.md entry runs to about 13,000 words. The rule scans forward from the marker and stops at the first suffix-looking word. Every later fix repairs what that stop got wrong:

The numeral, credential and title stops are each asked twice.
A link exception keeps Puig i Soler together.
A release invariant (Should Doe, Jane nee Smith MA read MA as a credential? The maiden name keeps it, where it gives up PhD and Jr. #533) asks of every stop whether the name left standing reads what it gave up as post-nominals, and models every join that might absorb those words. Should a maiden clause keep a credential it would hand to a name part? Dr. nee Smith PhD Prof. reads family PhD #548 is that invariant failing at the one stop that never checks it.

Some of the rule's examples also describe input nobody writes. Jane née Jones Smith came in with the first design (2026-07-03) on an unsourced claim about running text. The differential corpus holds no real-world name of that shape, and today it reads family Jane.

Proposed statement. A prototype measured this; see the comments below.

Where a marker counts. A maiden marker is a marker only where it stands in the part of the name that holds the family name, and the word straight before it is a name word of that part:
- With no comma, that part is the whole name.
- With a family comma, it is the part before the comma, so Doe nee Smith, Jane takes a maiden name and Doe, Jane nee Smith does not.
- A word in the leading title run, a suffix, or a connective is not a name word.
- Having a name somewhere before the marker is not enough. In Jane Doe PhD nee Smith the word straight before nee is a suffix, so nee is an ordinary word.
- A particle before the marker is a name word: with nothing after it to attach to, it isn't working as a particle there. That keeps Mai Le née Nguyen and Anh Do née Tran.
- A suffix word opening the name is a name word, because a suffix never opens the string (S2). That keeps abd née Jones.
Anywhere else the marker is an ordinary word. The condition is positional, not about roles: under FAMILY_FIRST, Smith Jane née Jones has its marker after the given name and keeps working, as Russian document order (Иванова Анна урожд. Петрова) and 旧姓 need.
What it takes. Read the end of the name as if the clause weren't written, with the trailing rule (the suffix peel and the title chain) and before any join: the part before the marker, plus the suffix- and title-shaped words at the end. Whatever trailing run that reading finds ends the clause. The marker takes every word between itself and that run, always including the first word after it. The marker itself is dropped.

Before a family comma, no trailing rule reads the part, and the family part takes a suffix word from anywhere in it. There the clause ends at the first suffix word and hands the rest back to the family part, as today, so Doe née Smith PhD Prof., Jane reads as Doe PhD Prof., Jane does.
The run is bound. Where a trailing rule reads the part, the take consumes the run and gives each word the suffix or title role the reading found. No later join can reach into it.
Unchanged:
- delimited clauses (M1/M3);
- multi-word markers;
- the particle-join bound;
- a lone name word beside the clause reading as the family (M4, parse("Smith née Jones") reports no family name — a maiden clause empties a one-word name, where 1.4.0 kept it #445).

What falls out.

The release invariant holds by construction. What the clause gives up is given its suffix or title role directly.
Gone: the double asking, the release check's join modelling (P2 chain, P5 bound join, P6 attachment), and the link exception. A connective in the middle of the clause isn't a stop.
"A maiden clause doesn't change how the trailing rule reads the end of the name" is now the rule itself, not a property each stop has to defend. The test suite already pins it. It is the trailing rule's reading, not the full parse's: where a particle chain would take the words in the clause-free name, binding (point 3) keeps them suffixes and titles.
Degenerate input follows from that one principle. No reading of it is designed for.

Examples. Both columns are measured. "Today" is master at aa401d8. "Proposed" is the prototype's variant 7 (proto/issue-601-m2-rethink, local).

Input	Today	Proposed
`Jane Smith née Jones`	maiden Jones	unchanged
`Maria López née García Pérez`	maiden `García Pérez`	unchanged
`Doe nee Smith, Jane`	maiden Smith	unchanged
`Smith Jane née Jones` (`FAMILY_FIRST`)	maiden Jones	unchanged
`Mai Le née Nguyen`	maiden Nguyen	unchanged
`Jane Doe nee Puig i Soler`	maiden `Puig i Soler` (link exception)	unchanged, with no exception needed
`Jane Doe nee Smith MA Prof.`	maiden Smith, suffix MA, title Prof.	unchanged
`Doe née Smith PhD Prof., Jane`	family `Doe Prof.`, suffix PhD, maiden Smith	unchanged (as `Doe PhD Prof., Jane` reads)
`Anh Do geb. van Dyke Smith Rev.`	maiden `van Dyke Smith Rev.`	maiden `van Dyke Smith`, title `Rev.`
`Mai Le geb. Ma Jones Prof.`	maiden `Ma Jones Prof.`	maiden `Ma Jones`, title `Prof.` (`MA Jones` the same: the first word is always taken)
`Jane Doe nee Smith DO DO`	maiden `Smith DO DO`	maiden Smith, suffix `DO DO`
`Dr. nee Smith PhD Prof.`	family `PhD`, maiden Smith	given `nee`, family Smith, suffix PhD, title `Dr. Prof.`
`Dr. nee Smith i MA`	family `i`, maiden Smith	given `nee`, family Smith, suffix `i MA`
`John nee Prof. ba MA`	maiden `Prof. ba MA`	maiden `Prof. ba`, suffix MA (as `John ba MA` reads)
`Jane van der Berg nee Prof. King. MA`	maiden `Prof. King.`, suffix MA	maiden `Prof.`, title `King.`, suffix MA
`Jane Doe nee Ma DO Rev.`	maiden `Ma DO`, title Rev.	maiden Ma, suffix DO, title Rev.
`Doe, Jane nee Smith`	maiden Smith	middle `nee Smith`
`Jane Doe PhD nee Smith`	maiden Smith, suffix PhD	suffix `PhD nee Smith` (the marker is a word, and #602's run takes it in)
`Jane Doe Jr. nee Smith`	maiden Smith, suffix Jr.	~~middle `Doe Jr. nee`, family Smith~~ suffix `Jr. nee Smith`: the marker is a word, and #602's run takes it in
`Smith, John, PhD née Jones`	maiden Jones	suffix `PhD née Jones`
`Jane Smith née V`	family `née`, suffix V	maiden V
`Jane Doe nee Smith PhD Smith`	middle `Doe PhD`, family Smith, maiden Smith	~~maiden `Smith PhD Smith` (see #602)~~ maiden Smith, suffix `PhD Smith`: the clause-free name's credential starts #602's run, and the take consumes it

Accepted consequences.

Family, Given née Maiden stops taking a maiden name. Callers use a delimited clause (Doe, Jane (née Smith)) or maiden_delimiters.
A given name with no current surname needs delimiters. Mary née Jones keeps M4's reading, family Mary.
A marker after a title, a suffix or a connective is a word. All three shapes are junk input.
A word that is also a credential reads the way the trailing rule reads it. JANE Q. DOE GEB. LE DO DO gives suffix DO DO. This is not how the full parse reads JANE Q. DOE DO DO, where the particle chain takes the pair as family DO DO: binding keeps that chain out of the released run. Jane van der Berg nee Prof. King. MA differs from its clause-free name the same way (Jane van der Berg King. MA reads family van der Berg King.).
Found while implementing: a trailing numeral is read by its shape. The prototype read the clause's last word without the numeral fork, so John née Jones Smith VI kept VI in the maiden name. The branch asks the fork, giving maiden Jones Smith, suffix VI.

Settled (formerly open questions).

A credential in the middle of the clause. Settled by Should a name word after a credential join the suffix? John Smith PhD Jones reads middle Smith PhD #602: Jane Doe nee Smith PhD Smith gives maiden Smith, suffix PhD Smith.
The given-only head. Kept as a rules.md#M2 boundary example: Jane née Jones Smith gives family Jane, maiden Jones Smith. That is degenerate input, so no reading is designed for it.
Jane Smith née V. Accepted as maiden V. The first word after the marker is always taken, a lone numeral included. Recorded in decisions.md#M2.

How we'll know.

~~Triage the 108 case and facade rows the prototype fails~~ (done; see the triage comment).
~~Rewrite the rules.md M2 statement and examples.~~ (done in Maiden marker counts only behind a surname; a credential starts a suffix run (#601, #602) #609)
~~Run the differential gate at every ledgered baseline.~~ (done in Maiden marker counts only behind a surname; a credential starts a suffix run (#601, #602) #609; every gate exits 0)
~~Rerun Should Jane Doe nee Smith Prof. read Prof. as a title? The maiden name keeps it, where Jane Doe Prof. gives the title #535's grids, the plausible-input grid and the corpus.~~ (done: with Should a name word after a credential join the suffix? John Smith PhD Jones reads middle Smith PhD #602 switched off, the branch reads all of those texts exactly as the prototype's variant 7 did, 0 differences, and variant 7 held 0 violations on Should Jane Doe nee Smith Prof. read Prof. as a title? The maiden name keeps it, where Jane Doe Prof. gives the title #535's grids)

Exclusions. No change to:

the delimited clause (M1/M3);
the marker vocabulary;
the comma-part logic beyond point 1.

Supersedes: #548. Related: #533, #535, #538, #549, #445, #602.

Prototype results (2026-10-03). These numbers come from a throwaway prototype on a local branch (proto/issue-601-m2-rethink). Seven variants of _maiden_take sat behind an environment switch, so one tree parses both ways. Every number below is a dated measurement.

The first draft's "computed once" was wrong. A run computed once over the name as written counts the clause's own words as spare. A particle before the marker then chains across the removed clause into the released words.

Grid A: 19,250 new violations.
John nee Prof. ba MA read family ba.
Jane van der Berg nee Prof. King. MA read family van der Berg King..

Three fixes were tried:

Variant	What it does	Result
v2/v3	grow the clause until the existing release check accepts it	0 violations, but it inherits the check's caution about particles, so `Anh Do geb. de la Vega PhD Prof.` kept `PhD Prof.` in the maiden name
v5/v6	bind the once-computed reading as roles (v5 by tagging, v6 by consuming)	no chain can cross into the released words, but the words-to-spare count still includes the clause: `John nee Smith ba` read `ba` as a credential while `John ba` reads it as a name
v7	read the run over the name as if the clause weren't written, then bind it; before a family comma, keep today's stop at the first suffix word	adopted in the body above

The particle half of point 1 was dropped. Variant 1 declined Anh Do née Tran and Mai Le née Nguyen, because Do, Le and Van are particle vocabulary.

v7 measurements (each grid parsed in separate processes with the prototype off and on):

Population	Size	M2 invariant violations today	v7	Readings moved
#535 grid A (recipe in decisions.md)	327,936	15,586	0	180,280
#535 grid B	173,057	8,713	0	76,437
Differential corpora	1,508	0	0	60
Plausible-input grid*	339,054	–	–	51,963

* Ten heads (including Anh Do, Mai Le, Jane van der Berg, Jane de la Cruz) × three markers × 1–2 maiden words × 18 trailing runs × an optional , PhD, in three cases.

The violation counts are my own invariant check, written to #535's recipe. Today's figures differ from #535's recorded 17,854 and 11,149, presumably from merges since. The grid moves are dominated by the head rule declining clauses on junk heads. Nearly all the plausible-grid moves free a trailing title or credential that today keeps in the maiden name, wherever a particle stands in the head or the clause (Anh Do geb. van Dyke Smith Rev.).

Test suite: 304 failures under v7, against 0 with the prototype off. By test file:

136 are the corpus invariant that appending née X changes nothing else. It conflicts with point 1 for every name ending in a suffix.
21 are rules.md M2 examples, and 1 is a P5 example.
38 are tests of the old take's internals and properties: 26 group-stage unit tests, 5 property tests (the given part after a family comma, the clause-free-tail pairing and a pinned ambiguity count), 3 revise round-trips, 2 post-rules tests, 1 benchmark pin and 1 parser test.
108 are case and facade rows, not yet triaged.

Size: v7's take needs none of the release-check helpers and no link exception. The current take plus the link exception is about 225 non-comment lines, before those helpers are counted. A real implementation's size is still to be measured.

Triage of the prototype's case and facade failures (2026-10-04). The 108 failures were 68 case rows. The 40 facade failures are all among them, because the facade runs the same table through HumanName.

Two prototype fixes during triage cleared 26 rows:

25 rows had the right fields but a missing suffix-or-name report. That was a prototype gap: v7 gave the released run its roles in group, so assign never filed its reports on those words. v7 now carries the peel's picks and its numeral report onto the run it consumes, and all 25 pass.
Lord Chancellor née Jones was a head-rule bug. The title run must be measured on the words before the marker, where H3 gives Chancellor back as the name word, while a lone title (Dr. nee …) still counts as a title.

42 case rows remain, 39 of them facade too. All are intended or consistent with the model:

Group	Rows	Verdict
Marker in the given part after a family comma (`Doe, Jane nee …`)	34	point 1, accepted; each reads as the same name with `nee` as an ordinary word
Head rule: suffix, lone title or tail part before the marker	3	intended (`Jane Doe Jr. nee Smith Ma`, `Dr. nee Jones Smith Prof.`, `Smith, John, Jr nee Jones MA`)
The run frees what today keeps	1	`Jane van der Berg nee Smith Prof.` gives title `Prof.`; today's row pins the release check's cautious keep
The run is consumed where the particle chain would take it	2	`Jane Doe nee Smith DO DO` gives suffix `DO DO`; `Jane Doe nee Smith i DO Prof.` gives suffix `i DO` (the trailing rule's reading; see point 2)
Numeral straight after the marker	1	open question 3 (`Jane Doe nee V Prof.` gives maiden V)
Suffix word in the middle of the clause	1	the model keeps it; #602's question (`abd née Jones Jr Smith Berg` gives maiden `Jones Jr Smith Berg`)

Family-comma readings worth a release note. All follow from the marker being an ordinary word there:

The particle attachment (P6) now reaches a trailing particle. Doe, Jane nee Smith St. gives family St. Doe, as Doe, Jane Smith St. does. … do, … Do and … MA do move the same way (5 rows).
Particles before the marker no longer attach to the family. Berg, Jane van der nee Smith DO gives middle van der nee Smith and family Berg, as Berg, Jane van der Smith DO reads.

Totals under v7 after these fixes:

Measure	Result
#535 grids A and B	0 violations
Corpus	36 readings move (was 60)
Grid A / grid B readings moved	153,048 / 62,110
Test suite	275 failures (0 with the prototype off)

The 275 failures break down as:

134 for the corpus-append invariant;
21 rules.md M2 examples and 1 P5 example;
the 42 case rows and 39 facade rows above;
38 tests of the old take's internals and properties.

A correction to the body (now edited): point 2 reads the clause-free name with the trailing rule alone, before any join. It is not the full parse. Where a particle chain would take the words (JANE Q. DOE DO DO reads family DO DO), binding keeps them suffixes and titles.

Prototype: proto/issue-601-m2-rethink at 9344dd97 (local).

Treat the two degenerate #601 readings as garbage in, not regressions

Simplify the #601/#602 code (/simplify pass)

Record #601's two patterns in mechanisms.md, and when to rethink a rule

Merge origin/master (#608, #606) into the #601/#602 branch

Merge pull request #609 from derek73/feat/issue-601-602-m2-rethink

Simplify what the /simplify pass on PR #616 found

A maiden marker counts only behind a surname, up to the name's traili…

Fix what the review of derek73#601/derek73#602 found

Merge origin/master (derek73#604) into the derek73#601/derek73#602 br…

Share P6's particle tail and the maiden take's candidates as one pred…

Check derek73#610's candidate superset at the take, on unjoined pieces

Read every citation shape the tree writes; fix what that exposes

Fix #632's second-round review: reach, controls, stale prose

Read every citation shape the tree writes; fix what that exposes

Fix #632's second-round review: reach, controls, stale prose

Check rule citations in every shape, ledgers included; fix the stale …

Fix prose the 2.4 changes made stale (pre-release sweep) (#647)

Navigation Menu

Repository navigation

Rethink the maiden-marker rule (M2): a marker stands after the current name and takes words up to the trailing suffix run #601

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Rethink the maiden-marker rule (M2): a marker stands after the current name and takes words up to the trailing suffix run #601

Description

Activity

derek73 commented on Oct 4, 2026

derek73 commented on Oct 4, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions