[brettheap]

Lane: openreposhape-4 (openRepoShape-4)
Claim: #688 (comment)

What changed and why

#688's three lines of #459, each measured on main 4ce90457 before the change, and again on bf1f099b (init --dry-run --local-remote-dir: the newline name, a name holding U+202E, GIT_AUTHOR_NAME=' ', --family CON and --family Lpt9 each still exit 0 and print the plan). Every refusal below is asked before any remote or folder exists, and --dry-run refuses alike. Only scripts/family.py changes, in _creator_name, _checked_family_identity, one call in cmd_init and new code beside them.

1. The creator, from every source (R423 (a), L4-114). #426 (#641) asked unwritable_reason of the creator only when git config user.name supplied it. Measured on main: init --created-by $'Ada\nLovelace' --dry-run exited 0 and the plan printed created by Ada and Lovelace on 2026-10-16 on two lines; --created-by holding U+202E, an ESC, a tab or Jos<e9> exited 0; so did GIT_AUTHOR_NAME holding each of them. _creator_name now asks once, of whichever source answered:

REFUSED family-unwritable-value: --created-by is 'Ada\nLovelace', which `init` records in the holder's `family.yaml`, and it holds a line break, and it is written as one line.
Remediation: nothing was created, and `--dry-run` refuses the same. Pass --created-by again, retyped. A byte that is not UTF-8 reaches a command line from a terminal or a script whose encoding is not the locale's, which the manifest could keep only as a lone surrogate, and that is no character; …

The remediation names the source that answered (CREATOR_UNWRITABLE_REMEDIATIONS), as the issue asks. For GIT_AUTHOR_NAME it reads … `init` read the creator from GIT_AUTHOR_NAME, because no --created-by was given: correct that variable, or unset it, for git makes the holder's first commit as it too; --created-by 'Your Name' changes only who `family.yaml` records. The environment keeps it as the bytes it was given, …. It does not say to pass --created-by: with the flag the creator is fine and git is asked about the same variable, so that run was family-bad-commit-identity for it (lane 1's review). For git config user.name it is #426's text, byte for byte. The detail still names the creator as _manifest_flags (#307) does, so this refusal and family-manifest-invalid agree on who is meant: --created-by, or --created-by (not given, so GIT_AUTHOR_NAME or `git config user.name`).

A GIT_AUTHOR_NAME of whitespace alone, with no --created-by and no git config user.name, was family-no-creator saying "no GIT_AUTHOR_NAME" of a variable that was set, and told the person to pass --created-by, which led to the same family-bad-commit-identity. It now says the variable is the cause, and to unset it and pass the flag:

REFUSED family-no-creator: no --created-by, a GIT_AUTHOR_NAME of whitespace alone, and no `git config user.name`. Creating a family is a human's act and the manifest records whose.
Remediation: unset GIT_AUTHOR_NAME, which git would make the holder's first commit as and refuses, and re-run with --created-by 'Your Name'.

The first exit of each of these two remedies is run in the tests, dry and real, and goes on to a holder.

2. The commit's identity (R423 (b), L4-115). _creator_name passes over a GIT_AUTHOR_NAME of whitespace alone and reads git config user.name, but env_commit replaces a variable only when it is unset or empty. Measured on main: GIT_AUTHOR_NAME=' ' with a good user.name, a real init exited 2 with fatal: name consists only of disallowed characters after <remotes>/Orbit.git and the work directory existed. cmd_init now asks git, after the clone URL and manifest questions and before the landing and the plan. It runs git var GIT_AUTHOR_IDENT and git var GIT_COMMITTER_IDENT, from an empty directory and no repository as _ask_git_branch asks, for each role the person set a variable of, with stand-ins where env_commit puts its fallback:

REFUSED family-bad-commit-identity: git refuses the author the holder's first commit would be made as, from GIT_AUTHOR_NAME '   ' (`git var GIT_AUTHOR_IDENT`: fatal: name consists only of disallowed characters:).
Remediation: nothing was created, and `--dry-run` refuses the same. Correct each variable named, or unset it, and run again. `init` makes the holder's first commit with them only after the holder's remote and work directory exist, and git would refuse them there. Unset or empty, a name or an address is `init`'s own and a date is the moment of the commit; --created-by sets who `family.yaml` records, not who git makes the commit as.

Git echoes a value it refuses (fatal: invalid date format: <the date>) as it was given, so the refusal quotes git's words with shown_path, as a path is quoted (#610): as they are when printable, as repr spells them when not. Raw, a GIT_AUTHOR_DATE holding a line break began a second line of the refusal of its own choosing, and U+202E reached the terminal. For a date of x and a line break and REFUSED family-fake: not real, the refusal is one line, ending:

… from GIT_AUTHOR_NAME 'Ada', GIT_AUTHOR_EMAIL 'ada@example.invalid' and GIT_AUTHOR_DATE 'x\nREFUSED family-fake: not real' (`git var GIT_AUTHOR_IDENT`: 'fatal: invalid date format: x\nREFUSED family-fake: not real').

The issue gave two directions: ask git, or name a blank variable. I chose to ask git because it is the only one that reaches the issue's goal ("every identity … it cannot write down"). A git commit in a scratch repository also fails on a name of only <> and on a GIT_AUTHOR_DATE or GIT_COMMITTER_DATE it cannot read (fatal: invalid date format). git var gave the same exit as git commit in every case measured. A blank check would leave those two failing after the remote exists. It is also the house pattern of refuse_bad_branch (#283): git's own answer, not a copy of its rules.

3. The holder's name (#459 comment 6192725913, the Windows family-name line). --family must be one CamelCase token (^[A-Za-z][A-Za-z0-9]*$). CON, Con, nul, PRN, Aux, COM1 and Lpt9 are each such a token, and on main each exited 0, real runs included. No Windows disk can make a folder of that name. _checked_family_identity now asks the leg path rule (shape_materialize._unmountable_reason) of the name, after the policy, as the issue directs:

REFUSED family-bad-holder-name: --family is 'CON', which names the holder and the folders `init` makes for it, and `CON` is a Windows device name (with or without an extension), which cannot be created there.

Where the issue and main differ. The issue says a trailing . or space is accepted. On main both were already refused before anything existed: Orbit. as family-bad-id (the derived id orbit.), or naming-unclassified with --id orbit, because the policy's token holds no dot; and 'Orbit ' as unsafe-value. They stay so. Asking the rule after the policy keeps those refusals unchanged, and leaves the device name as the only answer the rule can give here. Their rows pin it.

Tests

tests/test_family_init_asks_every_value.py (new, 78 tests, on the harness of tests/test_non_utf8_git_reads.py, #426). It asserts the exit code, the refusal code and its full words, the remediation in full, an empty stdout and nothing made (no remotes, work directory or family folder), for the dry run and the real run:

• the creator: --created-by and GIT_AUTHOR_NAME with a line break, U+202E, an ESC and a tab, and Jos<e9> from each (POSIX only, skipped on Windows); the git config user.name row's remediation whole; the first exit of the variable's remedy (correct it, or unset it) and of the blank-variable refusal's (unset it and pass the flag), each run to a holder; controls José (flag) and Mehr<U+200C>dad (variable) initialise and are recorded;
• the identity: the issue's row (both names ' ', a good user.name, under --work-dir and --into), each role alone, a name of only <>, a bad GIT_COMMITTER_DATE, and --created-by not getting past a blank GIT_AUTHOR_NAME; controls: every name and address empty still initialises, and an empty name or address beside a valid date in the same role (a role git IS asked about) still does, one row per role and variable; git's words for a date holding a line break and for one holding U+202E are pinned spelled, never raw. Git's words are fixed text under LC_ALL=C (PYTHONUTF8=1);
• the holder's name: the seven device names (dry run), CON real under both landings, the trailing dot and space rows, and controls COM0, LPT10, CONX, Conan and Nullify.

ONE targeted run on the merged head 22b7903a (main bf1f099b merged in; scripts/family.py sha256 ae4dfea6…, the new file 4d5d46b3…), 33 files: the new file, the 29 existing files that run family.py init (27, and tests/test_derived_id_refusals.py and tests/test_free_plan_hint_reads.py, which main gained since), and tests/test_repo_hygiene.py, tests/test_cli_reference.py and tests/test_agents_md_codes.py: 2533 passed, 23 skipped, 1 xfailed in 24 min, exit 0. The 23 skips are 16 and 3 in tests/test_family_init_values.py (rows that do not apply to the template in use, which quotes the placeholder or id:), 3 in tests/test_shape_doctor.py (the PowerShell line, Windows only) and 1 in tests/test_stdout_encoding.py (Windows' own default); the xfail is tests/test_shape_doctor.py's strict one for #735. CI's full Linux suite is the rest.

Fix round 1, 0748fc46 (SonarCloud: S6389 on a raw U+202E in the test source, and S1192 on the identity stand-ins): the test spells U+202E and U+200C as escapes, the stand-ins are spelled once, and the new file alone ran again, 57 passed.

Fix round 2, 6958dfbc (lane 1's review): ONE run of the new file, tests/test_family_init_values.py, tests/test_family.py, tests/test_clone_url_bytes.py, tests/test_non_utf8_git_reads.py, tests/test_repo_hygiene.py, tests/test_cli_reference.py and tests/test_agents_md_codes.py: 513 passed, 19 skipped, exit 0, in 4 min, the 19 skips being tests/test_family_init_values.py's template rows above (scripts/family.py sha256 bf599aa3…, the new file 69e214c1…).

Mutants, each against the new file, all run on the bytes of 6958dfbc:

mutant	result
M1: the creator asked only when git config user.name answered (main's rule)	killed, 18 failed
M2: the setting's remediation for every source	killed, 18 failed
M3: a blank-variable check in place of git var	killed, 9 failed
M4: cmd_init does not ask for the commit's identity at all	killed, 18 failed
M5: no holder-name question	killed, 9 failed
F1: the variable's remedy back to "pass --created-by 'Your Name', or correct that variable"	killed, 9 failed
F2: no blank-variable refusal (family-no-creator as it was)	killed, 2 failed
F3: git's words quoted raw, not by shown_path	killed, 4 failed
F4: a stand-in only where a variable is unset, not where it is empty (lane 1's R5)	killed, 8 failed

What it cannot tell

• Windows is reasoned, not run: this host cannot make a CON folder. The rule is the one the leg path already rides on (tests/test_adopt_leg_paths.py).
• The identity question gets git var's verdict, and git var agreed with git commit in every case measured (git 2.43). It is not git commit itself.

Shared files

scripts/family.py only. scripts/shape_materialize.py is not touched: _unmountable_reason is imported, as adopt-project.py imports _refuse_bad_leg_paths and update-shape.py _ask_git_branch. Every hunk is in the import block (two imports after unwritable_reason), after _classify_family_name, one line in _checked_family_identity, one call in cmd_init, and _creator_name with the constants above it. Merging main (bf1f099b) conflicted once, in the import block, where #660 added its own from shape_materialize import (free_plan_secrets_note, repository_visibility) at the same place; the two imports are independent and both stay.

git merge-tree --write-tree of this head 6958dfbc, each head read with ls-remote just before (2026-10-17):

• main bf1f099b: clean, tree 58f28f95;
• family.py add: a members/ renamed with git mv is renamed back in two steps through a free name, after what the disk lacks under it is put back, and a printed --sparse says the git it needs, so no remedy fails as typed (#685) #767 fix/685-spellings-remedies bbb961f8: clean, tree 4ad03479;
• shape_materialize.py, scaffold-project.py and family.py: the folder refusals and family-operation-in-progress name a path as shown_source names it, so an ESC or a line break in a path no longer reaches the terminal (#692) #731 fix/692-raw-folder-paths ab55c29f: clean, tree 1e9b301b;
• family.py: add's refusal of a member's own gitlink held only under another spelling of its row's path moves it back to that path in the index alone, so the printed remedy no longer takes the member's gitlink away from its row (#646) #670 fix/646-add-member-variant-remedy 6d7e4ff0: clean, tree 5ad8799c;
• lane 4's other PRs, all in scripts/family.py: family.py: bump fetches every branch of the member's origin whatever the mount's refspec and drops the origin/ refs no ref of origin backs, says a tag of the remote reaches a commit no branch does instead of "a pin the rest of the world cannot fetch", and tells a mount with no origin it has none instead of to fix the network (#686) #795 fix/686-bump-reachability 444934d9, clean, tree f5a55a13; family.py and shape_materialize.py: the NEXT push line names the branch by its full refname on both sides, so a branch beginning with + or named like a tag pushes as itself, and a tracking branch whose last part is over 250 bytes, which git cannot lock, is refused by refuse_bad_branch before anything exists, --dry-run too (#689) #813 fix/689-next-push-refspec b5a7a7f1, clean, tree bc717bd2; family.py and scaffold-project.py: add --local-remote-dir refuses a member clone URL .gitmodules cannot hold as text, --dry-run alike, each clone-URL remedy names a link's target and a lone surrogate, and the READMEs quote the clone URL, so the line under a b/ pastes as one command (#693) #812 fix/693-local-remote-dir 831d76c6, clean, tree a4c727ce;
• lane 4's branch with no PR yet, fix/684-family-holder-states 70153862: clean, tree 454cdd2b.

Closes #688

🤖 Generated with Claude Code

Summary by Sourcery

Refuse unrecordable creators, invalid first-commit identities, and Windows-incompatible family names before family initialization creates anything.

New Features:

• Validate creator values from all supported sources before initialization and provide source-specific remediation.
• Validate Git author and committer identities before creating remotes or work directories, including dry runs.
• Reject Windows device names used as family names.

Bug Fixes:

• Prevent unsafe creator values, invalid Git identities, and unholdable Windows family names from being accepted or created after partial setup.
• Ensure rejected values are safely quoted in refusal messages.

Enhancements:

• Align holder-name validation with the existing leg-path portability rules.
• Add comprehensive coverage for creator sources, Git identity failures, Windows names, dry runs, and no-side-effect guarantees.

Tests:

• Add focused tests covering 78 refusal, remediation, control, and initialization scenarios for family initialization.

[sourcery-ai]

Reviewer's Guide

The PR adds preflight validation to family initialization so unsafe creator values, identities Git would reject, and Windows-uncreatable family names are refused consistently before any remote or filesystem artifacts exist, including during dry runs, with extensive regression coverage.

Sequence diagram for family init preflight validation

sequenceDiagram
    participant User
    participant Init as family.py init
    participant Git
    participant PathRule as shape_materialize._unmountable_reason
    participant Filesystem

    User->>Init: cmd_init(args)
    Init->>Init: _creator_name(args)
    Init->>Git: git config user.name
    Init->>Init: unwritable_reason(created_by)
    alt creator is unwritable
        Init-->>User: Refusal family-unwritable-value
    end
    Init->>PathRule: _unmountable_reason(family)
    alt family names an uncreatable Windows device
        Init-->>User: Refusal family-bad-holder-name
    end
    Init->>Git: git var GIT_AUTHOR_IDENT
    Init->>Git: git var GIT_COMMITTER_IDENT
    alt Git rejects a configured identity
        Init-->>User: Refusal family-bad-commit-identity
    else all preflight checks pass
        Init->>Filesystem: Create remote and work directory
        Init-->>User: Print plan or complete initialization
    end

Loading

Flow diagram for dry-run and real-run preflight refusals

flowchart TD
    A[family.py init] --> B[_creator_name]
    B -->|unwritable creator| R1[Refuse family-unwritable-value]
    B --> C[_checked_family_identity]
    C -->|uncreatable family name| R2[Refuse family-bad-holder-name]
    C --> D[_refuse_unusable_commit_identity]
    D -->|git var rejects identity| R3[Refuse family-bad-commit-identity]
    D --> E{--dry-run}
    E -->|yes| P[Print initialization plan]
    E -->|no| F[Create remote and work directory]
    R1 --> G[Nothing created]
    R2 --> G
    R3 --> G

Loading

File-Level Changes

Change	Details	Files
Validate creator values from every supported source before initialization proceeds.	Apply unwritable-value checks to --created-by, GIT_AUTHOR_NAME, and git config user.name. Select source-specific remediation text while preserving the existing refusal details.	scripts/family.py
Preflight Git’s author and committer identities before creating remotes or working directories.	Use git var GIT_AUTHOR_IDENT and GIT_COMMITTER_IDENT in an empty temporary context. Substitute the same fallbacks used by env_commit and report Git’s native rejection details. Run the check for dry runs and real runs after manifest validation.	scripts/family.py
Reject Windows device names supplied as the family identity.	Reuse _unmountable_reason after family naming-policy validation. Raise family-bad-holder-name with remediation explaining affected holder paths and Windows restrictions.	scripts/family.py
Add comprehensive regression coverage for early refusals, source-specific diagnostics, and unchanged valid behavior.	Cover unsafe creator inputs, invalid Git identities, Windows device names, dry-run parity, landing modes, and no-artifact guarantees. Verify valid Unicode names and near-device-name controls still initialize.	tests/test_family_init_asks_every_value.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#688	Refuse an unwritable creator name from any source—--created-by, GIT_AUTHOR_NAME, or git config user.name—before creating anything, including under --dry-run, and identify the source in the remediation.	✅
#688	Before creating anything, ask Git whether the author and committer identities the first commit will use are acceptable, so invalid environment-provided identity values are refused up front, including under --dry-run.	✅
#688	Refuse a --family name that Windows cannot represent as a folder, before creating anything and including under --dry-run.	✅

Possibly linked issues

• Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459: The PR fixes the issue’s creator and commit identity failures and rejects Windows device names before creation; it says trailing-dot and trailing-space cases were already refused.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[brettheap]

(lane openRepoShape-1, 2026-10-17T11:15:31Z)

Lane 1's independent review of #809 at 0748fc4: CHANGES NEEDED

All three of #688's lines are fixed, and I measured each one. Nothing is made and gh is never called before any of the three refusals. git var gave the same answer as git commit in every identity case I tried, and ordinary output is byte-identical to main. Two small defects remain in the words of the new refusals, along with one test gap and one stale paragraph in the body. Each takes a line or two to fix.

How I measured. The head 0748fc46 already contains main bf1f099b (the merge base is main), so the local merge is the head itself. I compared it with main in separate checkouts. Every probe used:

• a stub gh first on PATH that logs each call and exits 97;
• GH_TOKEN=bogus, an empty GH_CONFIG_DIR and a probe-local global git config;
• --local-remote-dir and --work-dir under a case directory, with the case tree listed before and after each run.

The delta 22b7903a..0748fc46

• The stand-in identity cannot reach a commit. It exists only in the identity dict passed to run([... "var", ident], env=identity). run builds {**os.environ, **env} for that one process. env_commit builds its own environment from os.environ with its own fallbacks.
  • A real run with only GIT_AUTHOR_NAME=Ada and GIT_COMMITTER_EMAIL set made the holder's commit as author Ada <scaffold fallback address> and committer openRepoShape scaffold <the given address>, on the work tree and on the remote.
  • "identity check" appears in no commit header. The only hits in the holder are two existing template docstrings (siblings.py:703, validate-family.py:617), which main has too.
• The git var answer cannot differ because of the stand-in. Git judges the name, the address and the date separately. In 19 identity cases, a stand-in name never changed the verdict on a date or an address, and the reverse held too. env_commit always sets both a name and an address, so user.useConfigOnly, an empty user.name and EMAIL never take part. All of these were measured below.
• Nothing else changed. All 33 of my probe outputs (19 identity, 14 creator) are byte-identical between 22b7903a and 0748fc46. The test file's AST is unchanged, and no raw Cf character is left in its source.

The issue's lines

1. R423 (a), the creator from every source: fixed. Dry runs; main exits 0 with the plan, and the head exits 2 with family-unwritable-value, an empty stdout, the value shown with !r, and nothing made. Every source got its own remedy.
   • --created-by holding LF, CR, U+2028, U+0085, DEL, U+009B, U+2066, Jos<e9>.
   • GIT_AUTHOR_NAME holding U+202E, ESC, <e9>, the bytes ED A0 80, LF after a name.
   • U+FEFF is accepted on both, as unwritable_reason intends.
2. R423 (b), a blank GIT_AUTHOR_NAME: fixed for the issue's row, partly fixed without user.name (finding 2).
   • Main: git commit exit 128 with fatal: name consists only of disallowed characters:, after 119 paths existed under the case directory (remotes/Orbit.git, work/Orbit).
   • Head: family-bad-commit-identity, 0 paths.
   • The same holds for author only, committer only, a tab name, a name of only \x1b\x07, and for GIT_*_DATE set to now, @0, 99999999999 +0000 or ESC bytes. Main fails all of these at the commit and the head refuses them first.
   • Agreements that need no refusal: useConfigOnly=true with no identity, an empty user.name, EMAIL alone, the author name set but not the committer's, and an address of ' ', '<>', a\nb or a non-UTF-8 byte. Each exits 0 on both.
3. The Windows family name: fixed.
   • CON, con, Con, Nul, COM1, LPT9 and Lpt9 exit 0 on main and are family-bad-holder-name on the head.
   • CONSOLE, COM10 and COM0 pass on both.
   • NUL and CONIN$ are unsafe-value on both, and AUX. and CON.txt are family-bad-id on both. The body is right that main already refused the dot and space names; the issue's premise was wrong there.
   • COM¹ and LPT³ are unsafe-value on both, because SAFE_ARG_RE is ASCII.
   • The check is the shared shape_materialize._unmountable_reason, imported, not a second copy.

The GitHub path (no --local-remote-dir), real runs. The head refuses the blank author, --family CON and a tab in GIT_AUTHOR_NAME with zero gh calls and nothing made. The control run reaches gh repo view Acme/Orbit --json name. Main reaches gh repo view in all four.

Findings, ranked

1. The new identity refusal quotes git's words raw, and git echoes the bad value. Should fix.

The detail escapes each variable ({os.environ[key]!r}) and then pastes exc.output raw. Git only turns C0 controls other than tab and LF into ?. A line break, U+202E or a C1 control in a GIT_*_DATE therefore reaches the terminal as written, and so does a line break in a name made only of disallowed characters.

GIT_AUTHOR_DATE=$'x\nREFUSED family-fake: not real' python3 scripts/family.py init --org Acme --family Orbit \
  --created-by 'T H' --created-on 2026-09-02 --local-remote-dir "$T/remotes" --work-dir "$T/work" --dry-run

At the head, stderr has 3 lines, and the second is a forged one:

REFUSED family-bad-commit-identity: ... from GIT_AUTHOR_DATE 'x\nREFUSED family-fake: not real' (`git var GIT_AUTHOR_IDENT`: fatal: invalid date format: x
REFUSED family-fake: not real).

With GIT_AUTHOR_DATE=$'2026\u202e-01-01', stderr holds one raw U+202E. Main printed the same raw words inside the git commit failure, after the remote existed. That is older behaviour, but this refusal is new text and should follow #610's rule (shown_path: printable as is, otherwise repr).

The fix, which I ran on the head with the new file at 57 passed (every expected word is printable, so no test changes):

        except CommandFailed as exc:
            # Git echoes a value it refuses (a date) as it was given.
            said = (exc.output if exc.output.isprintable()
                    else repr(exc.output))
            ...
                f"made as, from {listed} (`git var {ident}`: {said})")

After it, the same probe gives 2 lines: ... (git var GIT_AUTHOR_IDENT: 'fatal: invalid date format: x\nREFUSED family-fake: not real'). I suggest one row that pins it.

2. Two remedies whose first exit leads to the next refusal for the same cause. Should fix ("Offer only exits that work").

(a) A blank GIT_AUTHOR_NAME and no user.name. --dry-run gives:

REFUSED family-no-creator: no --created-by, no GIT_AUTHOR_NAME and no `git config user.name`. ...
Remediation: re-run with --created-by 'Your Name'.

Following that remedy (--created-by 'Ada') gives REFUSED family-bad-commit-identity: ... from GIT_AUTHOR_NAME ' ' .... The detail says there is no GIT_AUTHOR_NAME when there is a blank one, and the blank one is the cause.

(b) GIT_AUTHOR_NAME=$'\x1b\x07', no --created-by. This gives family-unwritable-value, whose remedy begins pass --created-by 'Your Name', or correct that variable. Passing --created-by 'Ada' then gives family-bad-commit-identity for the same variable.

Replacement text:

• In CREATOR_UNWRITABLE_REMEDIATIONS["GIT_AUTHOR_NAME"], replace " `init` read the creator from GIT_AUTHOR_NAME, because no --created-by was given: pass --created-by 'Your Name', or correct that variable." with " `init` read the creator from GIT_AUTHOR_NAME, because no --created-by was given: correct that variable, or unset it, for git makes the holder's first commit as it too; --created-by 'Your Name' changes only who `family.yaml` records." (ENV_REMEDIATION in the test follows.)
• In _creator_name, when GIT_AUTHOR_NAME is set but blank, use the detail "no --created-by, a GIT_AUTHOR_NAME of whitespace alone, and no `git config user.name`" and the remediation "Remediation: unset GIT_AUTHOR_NAME, which git would make the holder's first commit as and refuses, and re-run with --created-by 'Your Name'."
• Or, instead, ask _refuse_an_unusable_commit_identity() before _creator_name. Each remedy then works in turn, but the identity process would come before the clone URL's question, which the docstring puts after it. That is your call.

3. Test gap: "empty is env_commit's fallback" is not pinned inside a role that is asked.

Mutant R5, identity = {key: os.environ.get(key, stand_in) ...} (a stand-in only when unset, not when empty), passes all 57 tests. It does make a wrong refusal:

GIT_AUTHOR_NAME= GIT_AUTHOR_DATE='2026-01-01T00:00:00 +0000' ... init ... --created-by 'T H'

• Head: exit 0, holder made.
• Main: exit 0, holder made.
• R5: exit 2, ... from GIT_AUTHOR_DATE '2026-01-01T00:00:00 +0000' (git var GIT_AUTHOR_IDENT: fatal: empty ident name (for <...>) n...

The existing control empties every variable, so no role is asked at all. Add a control row with an empty name and a valid date in the same role, one per role, that initialises.

4. The body's merge-tree paragraph names the old head, and two of its sibling heads have moved.

Replace the paragraph that begins "git merge-tree --write-tree of this head 22b7903a" and its list with:

"git merge-tree --write-tree of this head 0748fc46, each head read with ls-remote just before (2026-10-17): main bf1f099b: clean, tree 0831e0db; #767 fix/685-spellings-remedies bbb961f8: clean, tree 247f4d1f; #731 fix/692-raw-folder-paths ab55c29f: clean, tree 8ce2d357; #670 fix/646-add-member-variant-remedy 6d7e4ff0: clean, tree 80971577; lane 4's branches that have no PR yet, all in scripts/family.py: fix/684-family-holder-states 70153862, clean, tree 25c84004; fix/686-bump-reachability 444934d9, clean, tree 53385043; fix/689-next-push-refspec fa513848, clean, tree c18cd55b; fix/693-local-remote-dir 831d76c6, clean, tree 0f89383a."

I measured all eight as clean. #670 and fix/693 moved since the body was written.

The rest of the body is true at 0748fc46:

• The sha256 values check out: 653018ab… for family.py and f524e44d… for the test at the head; ae4dfea6… and 4d5d46b3… at 22b7903a.
• There are 57 tests.
• "git var gave the same exit as git commit in every case measured" matches my 19 cases.
• "Every refusal below is asked before any remote or folder exists" matches the case trees and the stub's empty log.

Tests

revert	result
R1: the creator asked only when user.name answered	killed, 18 failed (the 8+1 flag rows and 8+1 variable rows)
R2: no holder-name call	killed, 9 failed
R3: no identity call in cmd_init	killed, 13 failed
R4: the committer role dropped from COMMIT_IDENTITY	killed, 8 failed
R5: stand-in only when unset	survived, 57 passed (finding 3)

• The asserts are honest: whole-word refusal and remediation, an empty stdout, nothing_was_created, and the manifest read back on the real controls.
• The new file has no pytest.raises and no composite assert … and.
• By hand, _refuse_an_unusable_commit_identity has a cognitive complexity of about 9.
• At my read, the rollup showed SonarCloud SUCCESS, tests-git-bash SUCCESS and package SUCCESS, with tests still running.

Runs

The runs were at 0748fc46, with git-filter-repo on PATH and GIT_ALLOW_PROTOCOL unset: 905 passed, 19 skipped, 0 failed over 13 files. The files were:

• test_family_init_asks_every_value.py and test_non_utf8_git_reads.py: 104 passed;
• test_clone_url_bytes.py and test_family_init_values.py: 136 passed, 19 skipped;
• test_family_init_landing.py, test_family_refuse_up_front.py and test_family_dry_run.py: 147 passed;
• test_agents_md_codes.py, test_cli_reference.py, test_repo_hygiene.py, test_derived_id_refusals.py and test_adopt_leg_paths.py: 518 passed.

Ordinary output is byte-identical to main. After masking the case path, the shape sha and the holder sha, stdout and stderr match main's in three cases:

• user.name creator, dry run: 642 bytes;
• the same, real run: 2243 bytes;
• every identity variable set, real run: 2279 bytes. The two holders' work trees differ only in the clone path and the shape pin, and the commit's author, committer and dates match.

No probe left a temporary directory behind, and the change adds no network call.

Windows

This is reasoned; CI runs on Linux. git var is run the same way as _ask_git_branch, which already runs there. os.environ is case-insensitive there, which does not matter here. The tests that need non-UTF-8 bytes skip on Windows for the right reason. No text-mode byte counts are involved. The device rule matters only on Windows, and it is the rule the leg path already uses.

For the checklist (outside #688)

• commit.gpgsign=true with a gpg that fails. --dry-run exits 0, and the real run fails at git commit (error: gpg failed to sign…) after 120 paths exist, at the head as on main. The commit can still fail after the remote exists for reasons other than identity.
• A bad GIT_AUTHOR_NAME with --created-by. GIT_AUTHOR_NAME=$'Ada\x1b[31mX' with --created-by 'T H' exits 0, and the holder's first commit author is Ada^[[31mX. The manifest is clean, but the commit keeps the raw ESC.
• WINDOWS_DEVICE_RE lacks the superscript device names. It has no COM¹–COM³, LPT¹–LPT³, CONIN$ or CONOUT$, and _unmountable_reason('COM¹') is None. These are unreachable today through SAFE_ARG_RE, for both --family and leg paths, but the shared rule should say so.
• Optional trim. The clause "and a name ending in a dot or a space is made under another name" in HOLDER_NAME_REMEDIATION describes names that never reach this refusal.

Lane: openreposhape-1 (openRepoShape-1)

[brettheap]

(lane openRepoShape-1, 2026-10-17T13:05:40Z)

Lane 1's re-verification of #809 at 6958dfb: PR-READY

All four findings are fixed, measured on a local merge of 6958dfbc with current main 98f14976. The merge was clean and gave tree 76c2dfa8, the same tree git merge-tree predicts. One sentence of the body needs a refresh before landing, and one small new wording point is below; neither blocks.

#	Finding	Measured on the merge	Status
1	git's words quoted raw in family-bad-commit-identity	Line-break date (GIT_AUTHOR_DATE=$'x\nREFUSED family-fake: not real'): exit 2, stderr 2 lines, no forged line, 0 raw U+202E, 0 non-printable characters besides line ends. git's words are now 'fatal: invalid date format: x\nREFUSED family-fake: not real'. U+202E date (GIT_AUTHOR_DATE=$'2026\u202e-01-01'): exit 2, 'fatal: invalid date format: 2026\u202e-01-01', no raw U+202E. Nothing was made in either case. Current main exits 0 on both dry runs, because the failure there only comes at the commit. The quoting goes through shown_path, which is #610's rule (text if text.isprintable() else repr(text)); repo_shape.py is the same file on main.	fixed
2	remedies whose first exit led to the next refusal for the same cause	Blank GIT_AUTHOR_NAME, no user.name: family-no-creator: no --created-by, a GIT_AUTHOR_NAME of whitespace alone, and no .... Following it literally (variable unset, --created-by 'Ada'), the real run exits 0 and makes the holder. GIT_AUTHOR_NAME=$'\x1b\x07', no --created-by: family-unwritable-value with "correct that variable, or unset it". Unset with a good user.name: the real run exits 0. Corrected to Ada: the real run exits 0. Unset with no user.name: the plain family-no-creator, a different cause; then --created-by 'Ada': the real run exits 0. No remedy now leads into a refusal for the same cause.	fixed
3	the empty-fallback control was not pinned inside a role that is asked	Mutant R5 (os.environ.get(key, stand_in)) on the merge: 8 failed, 70 passed. The failures are the author-name and committer-name rows of the new "empty beside a date" test, both remedy-exit tests' unset rows, and the blank-creator remedy test, each dry and real. The address rows pass under R5, as they should: git accepts an empty address.	fixed
4	stale merge-tree paragraph	Every tree in the paragraph reproduces exactly at 6958dfbc. Since it was written, though, main moved to 98f14976 and #767, #670 and #812 landed; #795, #813 and fix/684 have new heads. Replacement text is below.	true as of its read, now outdated

Ordinary init matches current main byte for byte after masking the case path, the shape sha and the holder sha, in three cases:

• user.name creator, dry run;
• the same, real run;
• every identity variable set, real run.

Stdout and stderr are identical in all three; the byte counts differ only by the case path's length. The two holders' trees differ only in the clone path, the shape pin and tree_sha256. The body's sha256 values check out: bf599aa3… for family.py and 69e214c1… for the new file, which has 78 tests.

Runs on the merge, in one mode with git-filter-repo on PATH: 1224 passed, 19 skipped, 0 failed over 20 files.

• My earlier 13 files.
• Main's new family tests: test_family_add_member_variant.py, test_family_add_refusals.py, test_family_add_spellings_remedies.py, test_family_bootstrap_gate_order.py, test_family_members_case_variants.py, test_validate_family_unnamed_mounts.py and test_setup_family_folder.py.

Checks at 6958dfbc: tests, tests-git-bash, package and SonarCloud Code Analysis are all SUCCESS.

Body refresh before landing. Replace the paragraph that begins "git merge-tree --write-tree of this head 6958dfbc" and its list with:

"git merge-tree --write-tree of this head 6958dfbc, each head read with ls-remote just before (2026-10-17): main 98f14976 (#767, #670 and #812 have landed in it): clean, tree 76c2dfa8; #731 fix/692-raw-folder-paths ab55c29f: clean, tree 1e9b301b; lane 4's other PRs, all in scripts/family.py: #795 fix/686-bump-reachability 7d7a69b1, clean, tree 21afbf72; #813 fix/689-next-push-refspec 15c3b5ab, clean, tree 36ab5304; lane 4's branch with no PR yet, fix/684-family-holder-states fdc90a6e: clean, tree 35fb34dd."

The local merge with main is also clean against each of those four heads.

New, minor (for the checklist): GIT_AUTHOR_NAME=$'\u00a0' (or any other non-ASCII whitespace) with no user.name gets the new blank-variable family-no-creator. Its remediation says the variable is one git "refuses", but git accepts NBSP: the same variable with --created-by Ada exits 0. The remedy itself still works (unset it and pass --created-by); only the word "refuses" is untrue for those characters. If you want it exact, "which git would make the holder's first commit as" without "and refuses" is true for every blank value.

Lane: openreposhape-1 (openRepoShape-1)

[sourcery-ai]

Sorry @brettheap, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 7 hours and 20 minutes by commenting @sourcery-ai review. Upgrade to get a review now.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud