Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Three committed contributor docs carry the parser's normative rules and their re
- **decisions/** β€” the ADR-style record, one file per key: dated entries, Declined: (rejected WITH evidence), Excluded: (what must stay out of a wordlist and why), Open: (issue links, never restated; also keyed to a vocabulary set for contested memberships β€” the right-rule-wrong-set class), 3-0-reevaluations (append whenever a design cites 1.4 parity as load-bearing).
- **mechanisms.md** β€” problem-shape catalog with citable contract statements; stage-attribution claims in comments must cite an entry verbatim, never restate it in fresh words.

**Each rule and decisions entry is its own named file** (`rules/S6-case-signal-at-the-suffix-slot.md`, `decisions/vocabulary-collisions.md`), and each folder's README.md indexes them; a new rule or a new decisions key is a new file plus its index line, which `tests/v2/test_design_docs.py` holds to the file's heading and name, and tests/v2/design_docs.py is the one module that knows the layout (#713). Citations carry the ID only, never the name, so a file can be renamed freely. **When you cite a rule or decision in chat, a commit or a PR, give its name with its ID** β€” "S6 (the case signal at the suffix slot)" β€” since the ID alone tells the reader nothing about which rule it is.
**Each rule and decisions entry is its own named file** (`rules/S6-case-signal-at-the-suffix-slot.md`, `decisions/vocabulary-collisions.md`), and each folder's README.md indexes them; a new rule or a new decisions key is a new file plus its index line (a new decisions file opening with `## Standing` and `## Log`, decisions/README.md), which `tests/v2/test_design_docs.py` holds to the file's heading and name, and tests/v2/design_docs.py is the one module that knows the layout (#713). Citations carry the ID only, never the name, so a file can be renamed freely. **When you cite a rule or decision in chat, a commit or a PR, give its name with its ID** β€” "S6 (the case signal at the suffix slot)" β€” since the ID alone tells the reader nothing about which rule it is.

**Same-PR amendment rule.** Any PR that changes or clarifies parser behavior β€” or the boundaries around a documented rule, since a neighboring change can invalidate a rule's stated limits without touching its code β€” amends the rules in the same diff (the doc diff is part of the reviewable change, like tests). A change that resolves or reverses a design question adds a decisions entry; a new reusable pattern adds a mechanisms.md entry; a fixed deviation removes its `deviates:` marker in the same PR (the examples test forces this). Issues proposing behavior changes should be drafted in rule shape β€” rationale, statement, examples with boundaries, accepted consequences, open questions, exclusions β€” so landing an accepted proposal is a copy, not a rewrite.

Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,18 @@
# C13 β€” a credential opening the part after the comma

## Standing

- A suffix word that starts S8's credential run, with only titles in front of it, opens the part after the comma as the postnominal part, and every word after it reads as that run reads: a title word as a title, any other as a suffix; each word the opened part takes from the given name is reported β€” 2026-10-04 #603.
- Behind a one-word name before the comma the opened part is all suffixes (`Doe, PhD Jones`); reading the next word as the given name was declined β€” 2026-10-04 #603.
- A title/suffix dual opens nothing, nor does a member of the ambiguous class or a suffix word S8's run start refuses β€” 2026-10-04 #603.
- The split credential `Ph. D.` starts the run as `PhD` does β€” 2026-10-04 #603.
- Under strict mode the veto refuses an initial-shaped word the suffix reading, not the opened run (`Smith, PSM I.`), stated in rules/C14 since its split β€” 2026-10-04 #603.
- A title word past the second comma that is not also suffix vocabulary is a title. This is rules/C2's decision, indexed here because #603's entry is its only record (no decisions file is keyed C2) β€” 2026-10-04 #603.

Open: none in this file.

## Log

- 2026-10-04 (Derek), #603 (decided at group's head since #613, decisions/C1) β€” A CREDENTIAL OPENING THE PART AFTER THE COMMA MAKES IT THE POSTNOMINAL PART, WHATEVER FOLLOWS; AND A TITLE WORD PAST THE SECOND COMMA IS A TITLE. One word that is neither suffix nor title vocabulary used to flip the whole comma reading: `John Smith, PhD Jones` read family 'John Smith', given 'PhD', where `John Smith, MD FACS` and `Eric H. Holder, Jr. Attorney General` were already read as a name and its postnominals. Now the first suffix word of the part, with only titles in front of it, opens the part when it starts S2's run (`_pieces.starts_a_credential_run`, #602's own predicate, so the two runs cannot disagree about what starts one), and every word after it reads as that run reads: a title word as a title, any other as a suffix. The mechanism was the one #296 built for a part holding no name word, extended rather than added beside; where this entry had segment deciding it, #613 (decisions/C1) decides it once at group's head. Every word the opened part takes that would otherwise have made it the given part is reported (`suffix-or-name`), as #602's run reports what it absorbs.
THE ONE-WORD PATH, DECIDED (Derek): the whole part is suffixes. `Doe, PhD Jones` reads family 'Doe', suffix 'PhD Jones', no given name, as `Smith, PhD` already reads. DECLINED: reading the credential as a suffix and the next name word as the given name (`Smith, PhD Jones` β†’ given 'Jones'), proposed by analogy with a title at the head of the given part. Asked whether that is a real format, it is not -- nobody writes `Family, Credential Given` on purpose -- and the one realistic input it served, a misplaced generation (`Smith, Jr. John` for `Smith Jr., John`), is garbage in, garbage out. One reading for both comma paths was the deciding ground: the one-word path disagreeing with the full-name path is the shape #429, #430 and #432 each found. Accepted cost: `Smith, Jr. John` loses 'John' to the suffix, where 2.3 read given 'John' with 'Jr.' misfiled as a title.
A TITLE/SUFFIX DUAL OPENS NOTHING (Derek). A word in both vocabularies (`md`, `ms`, `sr`, the ranks `lt`, `cpl` and the rest) is the listing form's title in front of a given name, `Smith, Ms Jane`, and a credential behind it opens nothing either (`Smith, Ms PhD Jones` keeps given 'PhD', as `Smith, MD PhD Ma` keeps given 'Ma' under #544). DECLINED after building it: a dual opening the part behind two or more words before the comma. Derek first chose it for `John Smith, MD Jones`; the reviews found what the count cannot see -- a surname of two words (`GarcΓ­a MΓ‘rquez, Ms Gabriela`, `Smith Jones, Sr. Maria`), a title in front of a one-word surname (`Dr. Smith, Ms Jane`, the count taking the title as a word), and spaced initials (`GarcΓ­a MΓ‘rquez, Ms G. J.`) each lost the given name -- and with the word explained (a dual is a word in both lists, decided by position), Derek chose that duals never open. So `John Smith, MD Jones` and the `MD - PhD - FACS` delimiter rows keep their 2.3 reading. An ambiguous-class member opens nothing either (`John Smith, Ma Jones` keeps given 'Ma'), nor does a suffix word S2's run start refuses (`John Smith, vd Jones`).
Expand Down
Original file line number Diff line number Diff line change
@@ -1,3 +1,11 @@
# C14 β€” strict mode: a suffix word written as an initial

## Standing

- Strict mode is a rule of its own: the switch reads only the caller's configuration, and it vetoes an initial-shaped suffix word in the comma's decision and in a part after the comma that is nothing but suffix words, except in a run a credential opens, which takes the vetoed word (`Smith, PSM I.`, decisions/C13's #603), while the given part's walk after a family comma is strict-blind β€” 2026-10-19 #761.

Open: none in this file; the switch's reach into the count before the comma (`Smith V., Ma`) stays decisions/S4's 2026-09-18 rough edge.

## Log

- 2026-10-19 (Derek), #761 β€” STRICT MODE IS A RULE OF ITS OWN. The strict comma-suffix switch (`Policy(lenient_comma_suffixes=False)`) was a sentence of rules/C1 and a clause of rules/C13, and rules/C9 and rules/T4 restated it by pointing at C1. It reads nothing in the written name, only the caller's configuration, so under docs/design/AGENTS.md's one rule per piece of evidence it is a rule rather than a clause of the hub; split out while the C section moved to the skeleton format. Moved here unchanged in meaning: C1's sentence and its two strict examples (`John Smith, V.`, `john smith, v`), C13's `Smith, PSM I.` exception, which becomes this rule's boundary, and C9's clause that the run ends at an initial-shaped word. C1, C9, C13 and T4 now cite this rule, and so does W3 for the honorific split-off, whose comma-side question the switch also reaches (`田中さん, V.` keeps さん glued under it; root AGENTS.md's honorific-peel paragraph and the case row `ja_honorific_glued_family_comma_strict_knob`). The switch's own history stays where it was decided: decisions/C1's 2026-07 and 2026-07-12/13 entries (its blast radius, the one-letter roman numerals, and its date) and decisions/C13's #603 STRICT MODE paragraph (the opened run takes the vetoed word). The given part's walk after a family comma is strict-blind, measured on d7e1d47a (`Smith, John V`, `Smith, John PhD I` and `Smith, John Jr. V.` read the same under the switch as without it; C14's `Smith, John V` boundary pins the first), so this rule scopes the veto to the comma's decision and to a part after the comma that is nothing but suffix words. decisions/C9's #430/#432 sentence that "the strict knob is consulted" and "the run ends at the numeral" means that credential-run continuation, not the given part's walk. Two drafts of this rule overstated the reach (a run "inside a comma part", then "in the part after the comma", which in the listing form is the given part too); the PR reviews found both. One reach of the switch no rule states, the count before the comma reading the vetoed word as a name word (`Smith V., Ma` β†’ family 'V.'), stays recorded as decisions/S4's 2026-09-18 rough edge.
Original file line number Diff line number Diff line change
@@ -1,5 +1,20 @@
# P8 β€” a single-letter connective against the initial it spells

## Standing

- In a name written in more than one case, a bare Latin capital connective reads as an initial and a Cyrillic capital joins where P3's word count lets a connective join at all (`Иван Π‘Π΅Ρ€Π³Π΅ΠΉ И ΠŸΠ΅Ρ‚Ρ€ΠΎΠ²`; at three words it stays a middle name) β€” 2026-07-30 #267; 2026-09-13 #383.
- In a name written wholly in one case, a member of `conjunctions_ambiguous` reads as an initial and reports `conjunction-or-initial`, and any other single-letter connective joins where P3's count lets it; the default members are `e`, decided here, and `i`, added with the conjunction itself by decisions/P3's #397 entry as this log foresaw β€” 2026-09-13 #383.
- Both questions are asked over the name's own words, those before a maiden marker's run and outside a delimited clause; the one-case member's `initial` tag is given per token at every name length, three words included, though no role moves there: `john e smith` capitalizes to `John E Smith` and reports `conjunction-or-initial`, where with `e` removed from the subset it gives `John e Smith` and no report β€” 2026-09-13 #383.
- The subset is the knob, with no switch beside it; that a locale pack cannot remove a member is accepted β€” 2026-09-13 #383.
- The facade's `initials()` follows the parse's tags as the core does (the #528 amendment inside the entry) β€” 2026-09-13 #383.
- An orphan `conjunctions_ambiguous` entry is inert and nothing checks it β€” 2026-09-13 #383.
- The `initial` tag is not purely a shape claim: a marked connective in a one-case name carries it (amends decisions/M4) β€” 2026-09-13 #383.
- Inside a hyphenated word the connective keeps its lowercase in case repair, decided in decisions/R4 β€” 2026-09-24 #478.

Open: none in this file.

## Log

- 2026-07-30 #267 β€” the four-word single-letter asymmetry: a bare Latin capital connective is vetoed as an initial while a Cyrillic capital joins. #267's closure ("v2.0 behaves this way by default … verify it was the right call") showed only the Cyrillic half; the Latin-capital veto was never separately adjudicated, which rules/P8 records as an Accepted consequence (rules/P3 until the 2026-10-19 split).

- 2026-09-13 #383 + #479 β€” BLESSED for the mixed-case half, and DECIDED BY VOCABULARY for the one-case half, which is the half the question never reached. A single-letter connective joins only on positive evidence. Where a name is written in more than one case the writing is that evidence and nothing moves: a bare LATIN capital reads as an initial ("Jose E Maria Santos" β†’ middle "E Maria"), which is #383 answered with "bless". The shape is still LATIN and the phrase "Latin-capital veto" does not retire with this change β€” `_INITIAL` is ASCII-only, so a Cyrillic capital is never initial-shaped, joins, and #267's reading above is untouched. An earlier draft of this work claimed the phrase retires; it was overstated, and what became evidence-based is the one-case half alone.
Expand Down
Original file line number Diff line number Diff line change
@@ -1,5 +1,15 @@
# P9 β€” a particle that is also a suffix word, beside a family comma

## Standing

- A particle that is also an unambiguous suffix word, with a name piece behind it in the part before a family comma, heads that name and stays family in any case (`SMITH VD MA, JOHN`) β€” 2026-10-02 #573.
- Such a word standing between post-nominals after a family comma keeps the post-nominal reading in any case and reports the fork it decided (`suffix-or-name`); with nothing behind it, it ends the name and attaches by P6 β€” 2026-10-02 #573.
- A never-given particle opening the given part makes the member behind it a name rather than a credential. This is rules/S5's site, indexed here because this entry is its record (decisions/S5's #573 entry points back here) β€” 2026-10-02 #573.

Open: none in this file. The mixed-case `Doe, Jane PhD vd Ma`, which #573 left aside, was decided silent the same day (decisions/S5's #578) and that was reversed by #602 (decisions/S8's 2026-10-04 entry): it reads suffix 'PhD vd Ma'.

## Log

- 2026-10-02 (Derek), #573 β€” A WORD OF BOTH THE PARTICLE AND THE UNAMBIGUOUS SUFFIX VOCABULARY READS ALIKE IN EVERY CASE AT THE THREE SITES WHERE THE UNIFORM CASE SPLIT IT. Resolves the shapes decisions/C4's 2026-10-01 #554 entry left open. `vd` and `mc` split in names written wholly in one case, in three shapes, each split one stage acting on a reading the next never took. The mixed-case spellings were not all right either: `Smith vd Ma, John` read family 'Smith Ma', suffix 'vd' in 2.2.0 and 2.3.0, #530 having fixed it only in this cycle, and the fixes below move mixed-case names as well as uniform ones (blast radius, below).
BEFORE A FAMILY COMMA (P2 when decided, rules/P9 since its 2026-10-19 split). `SMITH VD MA, JOHN` read family 'SMITH MA', suffix 'VD' (2.2.0, 2.3.0 and this cycle's tree; 2.0.0 and 2.1.0 read family 'SMITH VD MA'). In one case the S2 trailing reading takes `VD MA`, so the particle chain stops before `VD`; the part before a family comma then takes strict suffix words one piece at a time, and the lone `VD` was peeled from between two family words. DECIDED in that per-piece read: a particle that is suffix vocabulary too, with a name piece behind it in the part, heads that name and stays family (P2's join), so `VD MA` reads family whatever the case. Not decided in the chain: a comma followed by no name word reads that same part positionally, trailing credential included (`Berg de MA, Prof.` keeps suffix 'MA' and its report), and the chain runs before that choice is made. A first draft skipped the chain's stop for the whole family part and moved exactly that shape; a widened grid caught it. Declined: reading `VD MA` as credentials, family 'SMITH', which the comma's naming of the family argues against. `SMITH VD, JOHN` and `SMITH VD JR, JOHN` keep the suffix: nothing, or a suffix word, stands behind the particle.
BETWEEN CREDENTIALS AFTER A FAMILY COMMA (P6 when decided, rules/P9 since its 2026-10-19 split). `DOE, JANE PHD VD MA` read family 'VD DOE', suffix 'PHD, MA': assign had read `PHD VD MA` whole, and P6's attachment, which outranks the suffix reading for such a word by design, reached into the run and pulled `VD` out. DECIDED: P6 gains a third exception β€” a lone such word with a post-nominal read in front of it and another behind, a title between it and the one in front transparent (H5), keeps the post-nominal reading in any case, reported as S2's credential fork. The test is the roles assign gave, asking whether it read the run whole, so a member read as the credential in front speaks as a degree does (`DOE, JANE MA VD PHD` stays whole); a first draft asked S2's company query instead, which counts only an unambiguous credential in front, and missed that shape and the titled one (`DOE, JANE PHD PROF. VD MA`). A generation counts on either side, and that is a decision rather than a side effect: P6's tussenvoegsel stands right behind the given name, so any post-nominal between them says the word is not one, and `Berg, Jan PhD vd Jr.` reads suffix 'PhD vd Jr.' where 2.2.0 and 2.3.0 read family 'vd Berg', suffix 'PhD, Jr.' β€” the shape `Berg, Jan van Jr.` P6's rationale names has no post-nominal in front and still attaches. No title is skipped BEHIND the word: a title there leaves it a name in assign (`DOE, JANE PHD VD PROF. MA` reads middle 'VD PROF.', as before), so a skip there was dead code, measured never to fire over the grid below, and was removed. Boundaries: with nothing behind it the word ends the name and attaches (`Doe, Jane PhD vd` β†’ family 'vd Doe', 2.2.0's and 2.3.0's reading); two such words side by side are one particle run, which P6 takes whole as its first exception says (`DOE, JANE PHD VD MC MA` β†’ family 'VD MC DOE', unchanged); a plain particle between credentials was never read as a post-nominal and attaches as before (`Doe, Jane PhD de PhD` β†’ family 'de Doe'). Declined: middle 'VD MA', 2.0.0's and 2.1.0's reading β€” under #554 run membership asks what the word IS.
Expand Down
Loading
Loading