templates/family-root README.md and AGENTS-shape.md, AGENTS.md and validate-family.py: the holder's own docs say its parent folder is "named after the family" and omit "EXACTLY, case included", and "never hand-edit the members: block" is contradicted by the validator's repair remedies #763

Goal: the holder's own README and AGENTS-shape.md say what the standard's README, the handbook and siblings.py say about the folder's name, and AGENTS.md, AGENTS-shape.md and validate-family.py agree on when a person may edit a row of family.yaml by hand.

Filed by lane openRepoShape-5, from rv695's review of #695's PR (#738, its N6, "could ride a later re-pin") and from the checklist candidate of #681's PR (#747, "AGENTS.md and the validator disagree on hand edits"). Words only; no behaviour changes.

Lands after: lane 5's #695 (PR #738, fix/695-family-docs, head c42286de), which writes "EXACTLY, case included" into the standard's README (README.md:913 at that head) and the handbook (docs/handbook.html:1343), and adds tests/test_family_docs_one_spelling.py, and #681 (PR #747), which adds the hand-edit remedy. The lines below are at main 66b230ed.

Pinned copies. templates/family-root/AGENTS-shape.md is pinned in every holder (FAMILY_COPIED_VERBATIM, scripts/shape_materialize.py:525-547), so a change to it rides in one upstream-changed row, with the shape bump. templates/family-root/README.md is rendered once at init (its {{FAMILY}} placeholders) and never re-rendered: update-shape.py apply does not touch it (#738's body), so a change reaches new holders only.

Lines

• N6, the holder's docs say "named after the family" and not "EXACTLY, case included". templates/family-root/README.md:72-73 ("When this holder's parent folder is not named after the family ...") and templates/family-root/AGENTS-shape.md:96-97 ("When the parent folder is not named after the family ..."). templates/family-root/scripts/siblings.py:969 compares folder.name == family exactly, and :1003 has a separate branch for a folder whose name differs only in case (folder.name.casefold() == family.casefold()), so "named after the family" reads as a case-insensitive match when the tool's rule is exact. README.md, the handbook, AGENTS.md and the family-root docs: init's --into sentence names the family-landing-in-standard refusal, make siblings is described as it stops before cloning, and members/ has its one-spelling rule (#695) #738's body: "Lane 3 asked for L21 only in the standard's README paragraph, so it is not owed here; it could ride in the same re-pin." Direction: say it in both, as the standard's README says it ("must be named EXACTLY after its repository, case included, on every disk"), and extend tests/test_family_docs_one_spelling.py to the two files so the three places cannot drift. The README line is for new holders; the pinned AGENTS-shape.md reaches the rest.
• AGENTS.md and the holder's AGENTS-shape.md say never to hand-edit family.yaml's members: block; the validator's remedies tell the person to. AGENTS.md:398-399 ("Never hand-edit family.yaml's members: block — the tool rewrites it wholesale") and templates/family-root/AGENTS-shape.md:38 ("do not hand-edit the members: block — the tool rewrites it wholesale"). Against them: RESTORE_ROW (templates/family-root/scripts/validate-family.py:1192-1194, printed by member-gitlink-unnamed at :1254 and :1317: "If its row was deleted or its path: edited by hand, put the row back as git last had it"), and, at validate-family.py and validate-pins.py: a staged gitlink removal says to commit it, member-gitlink-absent puts the gitlink back by hand, the variant mv is guarded, and a pin row with no path: is shape-pin-row (#681) #747's head 031ba75e, member-gitlink-absent's "a member that is to go has its row taken out by hand" (validate-family.py:501). A person who follows AGENTS.md and then the validator is told two things. The sentence is true of the normal path (add, bump and remove rewrite the block, and a hand edit there makes the gitlink and the pin disagree); the remedies are for a holder already in a repair state. Direction: one of two, and the issue's author picks with the evidence of the remedies as printed: say in AGENTS.md:398 and AGENTS-shape.md:38 that the validator may name a hand repair of a row and that then the commit is the person's, or change the remedies to say "put the row back with git" (git log -p -- family.yaml shows it) and "remove the member with family.py remove", which validate-family.py: a staged git rm is named again and fails retyped, the member-gitlink-absent remedy ends in a refused add, a shape-pin row with no path: reads None, and #639's mv orphans a live checkout and is stated by OS #681 found cannot run once the gitlink is gone (L2-38), so the second wording needs that case proved first.

Verify: tests/test_family_docs_one_spelling.py (new in #738) with a case per file; tests/test_readme_sections.py, tests/test_pinned_copy_text.py, tests/test_repo_hygiene.py and tests/test_template_text_placeholders.py pass on Linux. For the second line, a test that reads AGENTS.md:398, AGENTS-shape.md:38 and the validator's two remedies and fails when one says "never" and another says to do it, as #738's file does for the folder sentence. No behaviour changes, so no docs/cli.md change unless a --help text moves.

Overlaps. fix/695-family-docs (#738) edits templates/family-root/README.md, templates/family-root/AGENTS-shape.md and AGENTS.md (other sentences: the --into sentence and the one-spelling sentence); l3-563-docs (#630) edits AGENTS.md and README. fix/681-validate-family-remedies (#747) and fix/648-bootstrap-and-gate-order (#682) edit validate-family.py; if the second line changes a remedy it lands after both. README.md has a line cap (tests/readme-cap.d/): no line here adds one to the standard's README.

Parent: #459.

Milestone: v1.1.1. Words only, and the three sentences are consistent with what the tools do today.

🤖 Generated with Claude Code