--local-remote-dir: family.py add takes a directory whose name is not UTF-8 into .gitmodules, the clone-URL refusal's remedy misses a link's target and a lone surrogate, and the READMEs' clone line is rendered unquoted #693

Goal: a --local-remote-dir the tools cannot write down is refused by every tool that writes it, with a remedy that says why, and the clone line the READMEs print pastes as one command.

Filed by lane openRepoShape-5 on Brett Heap's word of 2026-10-16T12:17:02Z ("#459's family lines (~38)"), from lane 4's R433 lines on #459 (comment 6214823552, R433 O1 to O4). Lane 4 judged each OPEN on 95780dd (cluster T10); re-read and probed on d4a7fab. #640 (landed, a5245427) asked the question of init's holder URL and the scaffold's assembly URL only. Lines marked MIXED touch scaffold-project.py and the assembly, spec and code roots' READMEs as well as family.py.

Pinned copies. None of the Python files below is pinned. The READMEs (templates/*-root/README.md) are rendered once, not pinned, so no holder or project re-pins.

Lines (line numbers at d4a7fab)

• R433 O2, family.py add --local-remote-dir <a directory whose name is not UTF-8> runs to exit 0, and git writes the URL into .gitmodules. cmd_add (scripts/family.py:4191) asks no clone-URL question; _member_url (:581-585) builds the path. Probed on main with a caf<e9>/IRQS.git bare repository: add exits 0, commits, and .gitmodules holds url = .../caf\xe9/IRQS.git. make siblings reads .gitmodules with errors="replace" (templates/family-root/scripts/siblings.py:240-243), so that url becomes caf�/... there, another path than the one the holder is pinned to (read from the code, not run). Direction: ask add the question init asks (unwritable_reason(url), family-unwritable-value, scripts/family.py:1633-1662) of _member_url's result under --local-remote-dir, before anything is mounted and under --dry-run alike, with the existing remedy's words.
• R433 O3, a symlink whose target is not UTF-8 gets a refusal whose remediation does not say so. --local-remote-dir link, link a UTF-8 name pointing at a caf<e9> directory, is refused by init and the scaffold, correctly, naming the RESOLVED url caf\udce9/..., but CLONE_URL_REMEDIATION (scripts/family.py:1619-1631, scaffold-project.py:852) says "Pass a --local-remote-dir whose path is one line of UTF-8 text ... a directory renamed or made anew", not that the typed path is text and its TARGET is not. MIXED. Direction: where the typed path is text and the resolved one is not, say the link's target is the fault.
• R433 O4, a path holding an unpaired UTF-16 surrogate gets a reason the remediation does not explain (Windows; reasoned, not run). unwritable_reason says it holds a lone surrogate, which is no character (unwritable_reason, scripts/shape_materialize.py:1902, the sentence at :1941), but CLONE_URL_REMEDIATION explains only "a byte that is not UTF-8" (scripts/family.py:1619, scaffold-project.py:852), where scaffold-project.py writes --elected-by, --reference and --name between literal double quotes with no escaping and asks none of them whether a file can hold it, so a line break leaves a project.yaml its own validators refuse, a backslash is recorded as another character (CORP\nick as CORP, a line feed, ick), and a byte that is not UTF-8 dies in write_lf after the legs are pushed #282's UNWRITABLE_REMEDIATION (scaffold-project.py:792) says "a byte that is not UTF-8, or a lone surrogate". MIXED. Direction: add the surrogate to the remediation's reasons, in both constants; the same edit as the line above.
• R433 O1, the READMEs' clone line is not quoted. git clone --recurse-submodules {{CLONE_URL}} (templates/family-root/README.md:9, templates/assembly-root/README.md:15 and :33) and {{ASSEMBLY_CLONE_URL}} (templates/spec-root/README.md:13, templates/code-root/README.md:13) take a local path raw; the values are "CLONE_URL": url (scripts/family.py:1708) and urls["assembly"] (scaffold-project.py:1792-1793). A --local-remote-dir under a b/ is accepted, exit 0, and writes git clone --recurse-submodules <...>/a b/Atlas.git into each README (R433 measured; not re-run here), a line that splits when pasted, as one holding $, ', ; or & does. family.py and siblings.py print commands with unquoted paths, so under a folder with a space the member-git-dir-cached remedy's rm -rf would delete the wrong directory, and add's push line fails #486's shell_line quotes printed commands, not rendered template lines. MIXED. Direction: render the value through shell_quoted(url, "posix") (scripts/repo_shape.py:3215; POSIX, not the host's dialect, since the README is a committed file read on every OS, and Printed commands are POSIX-only: quote the bare paste lines in bump-leg.py and update-shape.py, and say in the docs that pasted commands are for a POSIX shell #532 says pasted commands are for a POSIX shell), which leaves a GitHub url and an ordinary path bare, so no existing README changes. A row for a b/ and one for ' in each tool's README.

Left out: R433 O5 (directory_named skips every bad-name test on Windows, tests/test_clone_url_bytes.py:136-147) is a test gap that the line itself says loses nothing on Linux CI, and CI has no Windows job since #597; it stays on #459.

Overlaps: #621 and #634 edit scaffold-project.py (other functions); #639 edits family.py's remove functions. Lane 3's #460 lines may touch the family-root README (R605's template line); the clone-line edit is one line of it and is rendered, not pinned. Land README edits one at a time (#519).

Mark the four lines → this issue on #459, and tick them there when this closes.

🤖 Generated with Claude Code