Skip to content

docs(design): Standing blocks for decisions S2, S5, S7, S8 and S9 (#762) - #823

Merged
derek73 merged 3 commits into
masterfrom
docs/standing-s-section
Oct 22, 2026
Merged

derek73 merged 3 commits into
masterfrom
docs/standing-s-section

Conversation

@derek73

@derek73 derek73 commented Oct 22, 2026

Copy link
Copy Markdown
Owner

Part of #762. Five older decisions files gain a ## Standing block (one present-tense line per decision in force, each pointing at its log entry) and a ## Log heading, and their keys leave tests/v2/decisions_without_standing.json:

  • S2 (a suffix word ends a name and never opens the string)
  • S5 (the given part's trailing slot after a family comma)
  • S7 (the company of an unambiguous credential)
  • S8 (the credential's trailing run)
  • S9 (unlisted words that join the ambiguous class by shape)

Docs only; no behavior moves.

How the lines were checked

  • Every example a line cites was parsed on the tree, in the comma shapes it touches. Each block opens by saying its examples name fields as the default order reads them.
  • Before each line, docs/design/decisions/, docs/design/rules/ and the vocabulary were searched for later entries that changed the decision.
  • Every pointer was resolved with design_docs._resolve to confirm it names the intended entry, not just an entry. One didn't: S9's 2026-09-17/18 bundle needs the full date in its pointer.

Head notes added (edit kind 1)

Review

Two rounds of design-docs-reviewer (opus): one over the branch, one over the fix commit.

Round 1 found:

  • S7's boundaries (connective, one-letter numeral, a vd/mc particle) stated without the limit that S8's credential run passes through them: John Smith PhD V Ma reads suffix 'PhD V Ma'.
  • S8 line 1 missing the split Ph. D., which starts no run in a main segment.
  • S9 saying "eleven wordlists". S6's whole-PR review round had corrected this to every wordlist.
  • S5 claiming any particle behind a member ends the given part. vd and mc are looked past: Doe, John MA vd reads suffix 'MA'.
  • A missing line: neither S9 switch reaches the v1 shim.
  • Role names that hold only under the default order.
  • A missing S5 Should Doe, John MA read MA as a credential, as 1.4.0 did, or at least report the fork? #531 head note.
  • Three S2 decisions with no line.
  • Uneven Not standing: coverage.

Round 2 found (all fixed):

  • My S7 scope named S8's run but not C13's: Smith, PhD V Ma reads suffix 'PhD V Ma'.
  • The Ph. D. gap was described as "no comma", but it is "main segment": John Smith Ph. D. Jones, Jr. keeps family 'Jones'.
  • The order qualifier was applied unevenly. It is now one sentence per block.
  • One S9 line pointed at the entry that is superseded on that very point.

Stale rule text found and left (rules/ not edited)

  • rules/S7, "What ends the run": a connective, a one-letter numeral and any name word do not end the run wherever S8's or C13's run starts (John Smith PhD V Ma, John Smith PhD i Ma, Smith, PhD V Ma all read wholly as suffix). rules/S2's Precedence bullet "A credential's run against its company" names only two of the shapes S8 took over.
  • rules/S5, "How far 'ending the given part' reaches": it says the reach ends at a particle "the suffix vocabulary does not also claim", then gives Doe, John MA do as its example. But do is suffix vocabulary, in the ambiguous half. What the tree distinguishes is the unambiguous half (vd, mc), so it should read "does not also claim as an unambiguous suffix word".
  • rules/S8, "Where the run starts": stated universally, but the split Ph. D. in a main segment starts no run (John Smith Ph. D. Jones → family 'Jones'). It needs an Accepted bullet, or a deviates: marker if the gap is unintended.
  • rules/S9, Then: "by SHAPE where the caller asks for it", though both shapes are admitted by default (the rule's own first bullet says so). I didn't edit this: nameparser/_pipeline/_classify.py:208 quotes the phrase, so changing it also means changing that citation.
  • Source entries: decisions/C13's Should a comma part opening with a credential be a suffix comma? John Smith, PhD Jones reads family John Smith #603 entry and S8's Should a name word after a credential join the suffix? John Smith PhD Jones reads middle Smith PhD #602 REVERSED paragraph call the Ph. D. gap "no-comma". It also holds before a suffix comma. They could take an edit-kind-2 note.

Nothing here belongs to the parallel sessions' files (P1, P2, P3, P6, P7, R4).

Tests

  • tests/v2/test_design_docs.py and tests/v2/test_doc_citations.py: 153 passed.
  • Full suite on 3.11 and on 3.15: 22,772 passed, 125 skipped, 3 xfailed each, run on the first commit. The two fix commits change only decisions prose, and the doc tests pass on them.

Generated by Claude Code

Each of the five files gains a ## Standing block, one present-tense
line per decision in force pointing at its entry, and a ## Log
heading; the five keys leave decisions_without_standing.json.

Every example a line cites was parsed on the tree. Entries a later
decision reversed in part gain an edit-kind-1 head note: S2's #614
(counting view, by #620 and #624) and #620 (BOUND mark and gathering,
by #625); S5's first 2026-09-18 entry (its open follow-up, by #531)
and #578 (wholly, by #602); S7's #544 ((6), its ACCEPTED LIMITS and
(d)'s example by #601/#602/#603, (c)'s `John Om Ma` by the 2026-10-21
marking of `om`); S8's #602 (by #679 and #627); S9's two 2026-09-14
switch entries (by #563, #564 and #544).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QWGUtYQHfXnSCyAJrS7Gwu
…#762)

- S7: the company's boundaries (connective, one-letter numeral, the
  vd/mc particle) are scoped to where no credential run (S8) starts.
- S8: the split `Ph. D.` with no comma starts no run (decisions/C13's
  #603 entry), now an exception in line 1 and an Elsewhere line.
- S9: "unlisted" means in no wordlist at all, not eleven (decisions/
  S6's whole-PR review round corrected the roster); the caps entry's
  head says so; a line records that neither switch reaches the v1
  shim.
- S5: a particle behind a member ends the given part unless it is
  also an unambiguous suffix word (`Doe, John MA vd` → suffix 'MA');
  the #531 entry's open maiden gap gains its head note.
- S2: lines for the third residual, #620's numeral fork and #625's
  particle-or-given key.
- Role-named examples that hold only under the default order say so;
  S5 and S9 list their #682 split under Not standing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QWGUtYQHfXnSCyAJrS7Gwu
- S7: the company's boundaries are scoped to where neither S8's run
  nor C13's (a part a credential opens after a comma) starts:
  `Smith, PhD V Ma` reads suffix 'PhD V Ma'.
- S8, S7: the split `Ph. D.` starts no run in a main segment, before
  a suffix comma too (`John Smith Ph. D. Jones, Jr.` → family
  'Jones'), not only with no comma.
- Each block opens by saying its examples name fields as the default
  order reads them, replacing the per-example qualifiers that the
  first fix applied unevenly.
- S9: the line pointing at the 2026-09-14 caps entry keeps only what
  that entry decided (membership, not tags); the full roster is the
  Elsewhere line to decisions/S6.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QWGUtYQHfXnSCyAJrS7Gwu
@derek73 derek73 added docs Documentation fixes and updates tests design labels Oct 22, 2026 — with Claude
@derek73 derek73 self-assigned this Oct 22, 2026
@codecov

codecov Bot commented Oct 22, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.05%. Comparing base (7006e33) to head (030f195).

Additional details and impacted files
@@           Coverage Diff           @@
##           master     #823   +/-   ##
=======================================
  Coverage   99.05%   99.05%           
=======================================
  Files          47       47           
  Lines        4659     4659           
=======================================
  Hits         4615     4615           
  Misses         44       44           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@derek73
derek73 merged commit 341195a into master Oct 22, 2026
12 checks passed
@derek73
derek73 deleted the docs/standing-s-section branch October 22, 2026 18:28
derek73 added a commit that referenced this pull request Oct 22, 2026
#762) (#825)

* Fix stale rule prose and record two undated decisions (#762 round 2 follow-ups)

From the round-2 reviews (#822, #823, #824):
- rules/S5: the particle that ends the reach is one the suffix
  vocabulary does not claim as an unambiguous word (do is ambiguous).
- rules/S7 and S2: what ends the company does not end a credential's
  run; a one-letter numeral and a name word are the run's, and after a
  comma a connective is too. In a main segment P3 joins a connective
  first (John Smith PhD y Ma reads family 'PhD y Ma').
- rules/S9: the Then names where each shape is admitted, and the
  _classify.py citation follows it.
- decisions/S8: #602's merged Ph. D. kept out of reach is marked
  superseded after a comma by #603.
- decisions/P6: #700's al- note corrected; only an attached al- stays
  lower case under a caller's mask.
- decisions/P1 and P2: the family-comma reach (#395) and the group
  distribution bullet get dated entries and Standing lines.

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

* Narrow the connective claim to C13's part; fix the al- note, a stale comment and two entry placements

Review of dceef4e:
- rules/S7, S2 and decisions/S7's Standing line: a connective is joined
  by P3 before the run is read and so ends it, except in a part a
  credential opens after a comma (C13); 'Smith, John PhD and Ma' reads
  middle 'PhD and Ma'.
- decisions/P6: the mask reaches al- as the whole family or a given name;
  beside another family word, before or after it, al- is lowercased
  ('smith, al-' -> 'Smith al-').
- nameparser/_types.py: the S5 paraphrase now says 'unambiguous'.
- decisions/P1: the #395 family-comma entry moves into the log run.
- decisions/P2: the dated line takes the decision's date (8e8160b,
  2026-07-12), not the recording commit's.

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

* Place the connective by position; name the al- roles; date P2 by its first record

Second review of the follow-ups: a connective between the credential and
a following word is joined to it first, so no run starts, while one
further in is the run's ('John Smith PhD Jones and Ma'); the al- mask
reaches the given name and a lone-al- family, and the middle name keeps
it lower case; P2's line goes back to 2026-08-16, the bullet's first
record, since the split and the surnames view are v1's (9a3d187).

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

* Point S7's connective clause at P8 for a letter read as an initial

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

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

design docs Documentation fixes and updates tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants