[brettheap]

Lane: openreposhape-5 (openRepoShape-5)
Claim: #962 (comment)

Follows #948 (#896), which landed as ebbd9fa4.

Head f1cceddf: 414e9e0a (round 0, on #948's head 45415296), 5a435acd (the merge of origin/main ebbd9fa4, #948's squash) and f1cceddf (fix round 1, on rv984's review of 5a435acd). The squash is not an ancestor of this branch, so the merge conflicted in bootstrap.py in seven hunks, and this branch's side was taken whole: main's bootstrap.py (blob e31385cd) is 45415296's byte for byte, so nothing of main's was dropped. Against ebbd9fa4 the branch is three files, templates/assembly-root/scripts/bootstrap.py, tests/test_bootstrap_casefold_twin.py (three tests changed) and the new tests/test_bootstrap_create_twins.py (+737, -68). git merge-tree --write-tree of the head against origin/main c4dd19dc is clean. One file of templates/ changes.

A pinned copy: every project's bootstrap.py takes an upstream-changed row, and re-pins it.

What #948 left (rv896's review of #948, filed as #962)

#948 leaves a leg alone when HEAD's own ref is a TWIN of the tracking branch, a branch that folds to it on a disk that folds case (Main for main). Two things were not covered:

1. Only HEAD's ref was asked. create_at_pin asked about HEAD's ref, so a leg DETACHED AT THE PIN over a packed Main, and a leg on an unborn Main beside a packed MAIN, ran checkout -b main <pin> with no refusal. On a disk that folds case that writes the loose file Main and main are both read from. What such a disk then does to the packed Main is reasoned from git's files backend (rv984), and not measured on APFS or NTFS: the packed entry stays, for-each-ref goes on listing it at its old sha while rev-parse Main reads the new file main, and a later git branch -D Main unlinks that file. The commit is still in a ref; its name is shadowed, and the state is fragile.
2. The fold was casefold() alone. APFS also reads the NFC and the NFD spelling of a name as one file, so a leg on the NFD spelling of caf and U+00E9 is a twin that _folded_twin did not see: bootstrap fast-forwarded the NFC branch under HEAD's feet and the index was left at the old commit (D NEW-CONTRACT.md;M README.md), the same harm as bootstrap.py: on a disk that folds case, a leg on Main whose tracking branch main is behind the pin is moved under its own HEAD, and bootstrap says it is on main now over an index that undoes the pin #896's.

Item 1: every spelling that folds, before checkout -b

create_at_pin asks git for-each-ref refs/heads/ (packed refs are listed too) for a branch that is a twin of the tracking branch (_folded_spelling), just before the checkout -b and after every refusal that was already there. If one is found, _say_spelling leaves the leg and prints three lines: where the leg is and the pin's sha, why it is left, and the way out. Nothing is moved and nothing is made.

• EVERY twin is a reason to leave, whether or not a tag, a remote-tracking ref, another branch, the stash or the pin holds its commits (fix round 1, below).
• A twin is only ever left in place, never moved (bootstrap.py: a leg whose HEAD is on a branch that differs from the tracking branch only in case (Main for main) is left where it is, so on a disk that folds case branch -f main no longer moves the ref HEAD stands on (#896) #948's rule, kept), and every output that is not a twin's is byte for byte what it was. fast_forward_to_pin is not changed in complexity (15, as it was).

Item 2: NFC, then casefold()

_fold(name) is unicodedata.normalize("NFC", name).casefold(), used by _folded_twin and so by all three step (a) paths, and by item 1. A name held as surrogate escapes (#704) passes through normalize as the text it is and raises nothing (a test). NFKC is not used: APFS does not fold compatibility forms, and main with U+00B2 stays no twin of main2 (two rows, and the NFKC mutant is killed).

_twin_words words the refusal by what the twin differs in. A twin that is one under casefold() alone prints #896's words byte for byte (only in case; a disk that folds case (macOS, Windows)). Any other says it differs only in case or Unicode form, and that a disk that folds case or Unicode forms (macOS folds both, Windows folds case) reads the two as one, because Windows folds case only and the words must not say it folds Unicode forms.

Fix round 1: the way out renames the twin (rv984's SHOULD 1, and #948's HEAD-twin keep line)

This replaces round 0's _kept_elsewhere, a departure from the brief that rv984 found breaks #962's Goal, and lane 5 ruled to follow the Goal. Round 0 spared a twin whose commit was an ancestor of the pin, or was held by another branch, a tag, a remote-tracking ref or the stash, and its way out kept the commits on another branch and ran again. rv984 measured that in each case that made main, a folding disk would read Main as the pin: the Goal says bootstrap never makes, with checkout -b, a ref that a folding disk reads as a branch that already exists, and these cases broke its letter. The loop the sparing avoided is real only for a way out that leaves the twin where it is: #948's keep line ("keep any commit ... check out the pin") leaves Main in place, so the next run refuses again. A way out that REMOVES the twin ends it.

• _kept_elsewhere and _spelling_at_risk are gone. _folded_spelling(sub, branch) returns the first refs/heads/ ref, packed or loose, that folds to the branch, whatever else holds its commits. _heads(sub) is the shared listing.
• The way out is a rename: git -C <leg> branch -m <twin> <name>, the path and both names through _paste_word. The twin disappears, its commits stay on the renamed branch, and the next run makes main.
• The line can be pasted as printed. _kept_name(sub, twin) chooses a name that is not there: <twin>-kept, then -kept-2 and on, the first that no branch of the leg folds to (so Main-kept is taken when main-kept is there, as on a folding disk they are one file). It is longer than the twin, so it differs from the tracking branch by more than case or Unicode form.
• bootstrap.py: a leg whose HEAD is on a branch that differs from the tracking branch only in case (Main for main) is left where it is, so on a disk that folds case branch -f main no longer moves the ref HEAD stands on (#896) #948's HEAD-twin keep line is amended the same way. A leg ON a twin with main missing goes through _say_spelling with where = the checkout is on: its first two lines are byte for byte bootstrap.py: a leg whose HEAD is on a branch that differs from the tracking branch only in case (Main for main) is left where it is, so on a disk that folds case branch -f main no longer moves the ref HEAD stands on (#896) #948's, and the third is the rename. git branch -m moves HEAD with the rename of the branch HEAD is on, an unborn branch included (probed on git 2.43.0 and 2.47.1, with and without the dangling link the emulation uses), so the next run takes the ordinary the leg was on <name>, which keeps its commits path. _say_twin keeps T7 and P9, whose switch way out is unchanged.
• _say_keep is back to the one-parameter text main had before bootstrap.py: a leg whose HEAD is on a branch that differs from the tracking branch only in case (Main for main) is left where it is, so on a disk that folds case branch -f main no longer moves the ref HEAD stands on (#896) #948: no twin line uses its second parameter now, and no non-twin line changes.

What it costs: several twins are named one at a time, each rename one run. A name is chosen when the line prints; if something makes it first, git refuses the rename and the person picks another. The cost of the old sparing, a shadowed name on a folding disk, is gone with it.

Before and after, the four states (git 2.43.0, the pasted line run through /bin/sh)

At 5a435acd and at f1cceddf. A packed Main holding a commit, main missing:

detached over a packed Main, at 5a435acd:
  [spec] spec: branch main does not exist (the pin is <pin>), and the leg has the branch Main, which differs from main only in case
          ... the leg is left as it is
          keep the commits Main holds on a branch whose name differs from main by more than case: `git -C spec branch <another name> Main`, and run bootstrap again.
at f1cceddf, the third line is:
          rename Main to a name that differs from main by more than case, its commits staying on it: `git -C spec branch -m Main Main-kept`, and run bootstrap again.
  run 2 after the pasted line: [spec] spec: branch main created at <pin> - at the pin
  after: HEAD -> refs/heads/main, heads: Main-kept (the commit), main (the pin)

the same, the commit held by a tag (rv984's SHOULD 1 case):
  at 5a435acd: [spec] spec: branch main created at <pin> - at the pin, with Main left in packed-refs
  at f1cceddf: the refusal above, and `Main-kept` after the pasted rename

HEAD on the packed Main (#948's keep line):
  at 5a435acd: "not moving the checkout off it. Keep any commit made there on a branch whose name differs from main by more than case, check out the pin in the leg, and run bootstrap again."
  at f1cceddf: the rename line, then HEAD -> refs/heads/Main-kept; run 2: branch main created at <pin>, "the leg was on Main-kept, which keeps its commits; it is on main now"

HEAD on an unborn Main beside a packed MAIN:
  at f1cceddf: run 1 names Main (rename Main Main-kept; HEAD goes with it); run 2 names MAIN (rename MAIN MAIN-kept); run 3 makes main, "the leg was on Main-kept, a branch with no commit yet"

The NFD twin of an NFC tracking branch, T7, is as in round 0: at 45415296 bootstrap fast-forwarded caf and U+00E9 under HEAD (D NEW-CONTRACT.md;M README.md); at this head the leg is left, switch is printed, and nothing moves.

Tests

tests/test_bootstrap_create_twins.py, 31 tests. It uses #948's emulation and helpers (test_bootstrap_casefold_twin), main_of (test_bootstrap_leg_moves), head_bytes (test_bootstrap_non_utf8_branch) and pasted (test_bootstrap_pasteable_lines); the lines are compared exactly, and every way out is run as printed through /bin/sh.

1. A leg detached at the pin over a real spelling Main, packed and loose (2): the lines exact, nothing moved, the rename run as printed, the next run makes main, and the commit is on Main-kept.
2. A leg ON a packed Main with main missing: the rename moves HEAD, and the next run makes main and says the leg was on Main-kept.
3. An unborn Main beside a packed MAIN: each twin named in turn and renamed, the third run makes main.
4. Two twins, MAIN and Main: the second rename is Main-kept-2, not Main-kept, which differs from MAIN-kept only in case.
5. A twin is a reason to leave however its commit is held (5 rows: the pin alone, another branch, a tag, a remote-tracking ref, the stash).
6. mains is no twin: main is made, as it was.
7. The NFD T7 test, and a missing branch beside its NFD spelling, left and renamed.
8. _kept_name (4 rows, and the NFC/NFD one), and a shell reads each word of the rename as the bytes of its names (4 rows, a byte that is not UTF-8 and a dash-led path included).
9. _folded_twin over Unicode forms (8 rows, with main and U+00B2 against main2, and U+2460 against 1, expecting False), and the fold raises nothing on a name that is not UTF-8.

At 5a435acd, with these test files copied in: 23 failed, 40 passed. 20 of the 31 tests of the new file fail there (cases 1 to 5, the NFD missing-branch test, the five _kept_name tests and the four shell rows) and the three changed tests of the casefold file fail (the unborn twin, the packed twin, the non-UTF-8 lines). The 11 that pass there pass by design: mains, the NFD T7 test, the eight _folded_twin rows (the two NFKC rows guard a mutant, not a base fault) and the fold test. At this head: 63 passed.

Mutants (each in a scratch tree, against the new file and the casefold file; none survives)

mutant	failed
the check dropped from create_at_pin (item 1)	10
_fold: casefold() alone, no NFC	6
_twin_words: always the case words	2
_say_spelling names the branch, not the twin	14
_fold: NFKC in place of NFC (rv984's O1)	2 (the two new rows)
the printed branch -m is a plain branch (a copy, not a rename)	17
the rename's two arguments swapped	17
_kept_name never loops (always -kept)	4
_kept_name compares byte for byte, with no fold	3
_kept_name folds the taken names but not the candidate	3
the HEAD-twin line says the leg has the branch for the checkout is on	4
the HEAD-twin check dropped from create_at_pin	4
the sparing put back (a twin another ref holds is left alone)	5
the new name not _paste_worded (spelled(shlex.quote(...)))	2
the twin not _paste_worded	2
_heads lists loose refs only	13

Round 0's four mutants of _kept_elsewhere (the ancestor rule, the holders, heads-only holders, the first twin) are gone with the code.

Complexity, and what is not touched

Cognitive complexity (S3776, counted from the ast): create_at_pin 14, fast_forward_to_pin 15 (unchanged), place_at_pin 6, _folded_spelling 3, _folded_twin 3, _heads 1, _kept_name 1, _twin_words 1, _say_spelling 0, _say_twin 0. New lines are within 79 columns and ASCII; the docstrings spell the Unicode forms (cafe and U+0301, caf and U+00E9). _paste_word (#973 edits it) and the NOT INITIALIZED line (#958 moves it) are not touched.

Runs

At the tree of f1cceddf (the head), git 2.43.0: the new file, test_bootstrap_casefold_twin.py, test_bootstrap_pasteable_lines.py, test_bootstrap_leg_moves.py, test_repo_hygiene.py, test_agents_md_codes.py, test_cli_reference.py and test_pinned_copy_text.py, 392 passed. git 2.47.1: the new file and the casefold file, 63 passed. Output that is not a twin's: a differential of 27 states (the tracking branch missing, at the pin, behind it, ahead of it, by HEAD on main, detached at the pin, detached elsewhere, on feature, on an unborn feature, on a ref outside refs/heads/, on mains), the leg and the printed lines read after each run: byte for byte the same at ebbd9fa4 and at this head. The rest of the suite is left to CI's tests job.

Merge checks

git merge-tree --write-tree of this head against: origin/main c4dd19dc clean; fix/961-paste-words (#973, b2887cf5) clean; fix/430-d-assembly-root-guards (#958, 0ef875c0) and slice D's round 1 (wip/l5-430d-r1-20261018, b49f34e1) one conflict each, the import block of bootstrap.py (import unicodedata here against from collections.abc import Callable, Iterator there). The resolution keeps import unicodedata and slice D's from collections.abc import Callable, Iterator, and does not keep both collections.abc lines, which would be a duplicate import (rv984's NIT 2). Round 0's scratch merges of those two (95 and 222 passed) were not re-run for round 1, whose changes lie below the import block.

Known limits

• A real APFS or NTFS disk is not available in CI: the shadowing a folding disk does to a packed twin is reasoned from git's files backend, not measured. The tests emulate the fold with a symlink, and run the real names where the disk keeps case.
• Several twins are named one at a time, and each rename takes one run.

Closes #962

🤖 Generated with Claude Code

[brettheap]

(lane openRepoShape-5, 2026-10-18T20:09Z) @codex review

[sourcery-ai]

Reviewer's Guide

Updates bootstrap branch creation to avoid hiding commits held only by case- or Unicode-equivalent refs, using NFC-plus-casefold twin detection, preservation-aware risk checks, clearer platform-specific refusals, and extensive regression tests.

Sequence diagram for twin-aware bootstrap branch creation

sequenceDiagram
    participant Bootstrap
    participant Git
    participant Leg

    Bootstrap->>Git: for-each-ref refs/heads/
    Git-->>Bootstrap: packed and loose branch spellings
    Bootstrap->>Bootstrap: _folded_twin
    Bootstrap->>Git: for-each-ref --contains tip
    Git-->>Bootstrap: refs holding the commit
    alt risky twin found
        Bootstrap->>Leg: _say_spelling
        Bootstrap-->>Leg: leave branch and commits unchanged
    else no commit would be hidden
        Bootstrap->>Git: checkout -b branch pin
        Git-->>Bootstrap: branch created at pin
    end

Loading

Flow diagram for safe tracking-branch creation

flowchart TD
    A[create_at_pin] --> B[_spelling_at_risk]
    B --> C[for-each-ref refs/heads/]
    C --> D{Twin under _fold?}
    D -->|No| C
    D -->|Yes| E[_kept_elsewhere]
    E -->|Ancestor or held by another ref| C
    E -->|Commit would be hidden| F[_say_spelling]
    F --> G[Leave leg unchanged]
    C -->|No risky spelling| H[checkout -b branch pin]

Loading

File-Level Changes

Change	Details	Files
Prevent creation of a missing tracking branch when any case- or Unicode-equivalent branch would have its unique commits hidden.	Enumerate packed and loose refs under refs/heads/. Identify the first risky twin whose tip is not retained by the pin, another branch, a tag, or a remote-tracking ref. Leave the leg unchanged and print an actionable command to rename/preserve the risky spelling before retrying.	templates/assembly-root/scripts/bootstrap.py
Extend branch-twin detection and refusal messaging to normalize Unicode names before case folding.	Add NFC normalization followed by casefolding, including safe handling of surrogate-escaped names. Differentiate case-only twins from twins differing in Unicode form and report platform-specific filesystem behavior. Reuse shared refusal formatting for HEAD twins and unrelated risky spellings.	templates/assembly-root/scripts/bootstrap.py
Add comprehensive regression coverage for risky spellings, Unicode twins, preservation rules, and exact user-facing output.	Test packed and loose case variants, unborn branches, multiple twins, and commits retained elsewhere. Test NFC/NFD branch handling, non-UTF-8 names, exact refusal text, and successful retry workflows. Validate helper behavior across Unicode forms and ensure no branch, HEAD, index, or commit is moved when refusing.	tests/test_bootstrap_create_twins.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#962	Before creating a missing branch, inspect packed and loose branches under refs/heads/ and refuse if any name folds to the requested branch, naming the existing spelling.	❌	The PR checks all such branches, but refuses only when the branch's commit would otherwise be left in no ref. If the commit is an ancestor of the pin or is held by another branch, tag, or remote-tracking ref, it creates the requested branch despite the colliding spelling. The issue calls for refusing whenever any branch name folds to the requested name.
#962	Treat NFC and NFD spellings as twins by normalizing names to NFC before casefolding.	✅
#962	Preserve the existing rule that a twin branch is left in place rather than moved.	✅

---

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.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-18T20:13:24.121295Z	5a435ac	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5a435acdf7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Normalize again after case folding

When a ref name combines case and canonical-form differences, case folding can itself produce a decomposed result: for example, Ϊ́ and ΐ fold here to ΐ and ΐ, respectively, which compare unequal even though they are canonically equivalent and alias on a case- and normalization-folding APFS volume. _folded_twin therefore misses the twin, allowing create_at_pin or fast_forward_to_pin to hide or move the aliased ref and potentially strand its commit or leave a stale index; normalize the case-folded result as well. templates/assembly-root/AGENTS-shape.mdL100-L102

Useful? React with 👍 / 👎.

[brettheap]

Independent review of #984 (#962) at 5a435acd, for lane openRepoShape-5: READY

No MUST. #984 fixes everything #962 measured: probe (b), probe (c) and the NFD twin all do their harm at 45415296 and are left alone at the head. Every output that is not a twin's, and every case-only twin's, prints byte for byte what main ebbd9fa4 prints. There is one design question for you (SHOULD 1), on the _kept_elsewhere departure.

Findings

SHOULD 1 (decision). _kept_elsewhere makes the very ref #962's Goal forbids, and the loop it avoids has another way out.

• Where: templates/assembly-root/scripts/bootstrap.py, in _kept_elsewhere and _spelling_at_risk.

• What I measured at the head. I set up a packed Main holding a commit M that is not in the pin's history, with HEAD detached at the pin and no main:

  What else holds M	Result
  only a tag	bootstrap makes main
  only a remote-tracking ref	bootstrap makes main
  only another branch	bootstrap makes main
  only refs/stash	bootstrap makes main
  nothing	refused

  In each case that makes main, emulating the fold afterwards makes Main read as the pin. The Goal says bootstrap never makes, with checkout -b, a ref that a folding disk reads as a branch that already exists, so these cases break its letter.

• The loop is real, but only for a way out that leaves the twin in place. bootstrap.py: a leg whose HEAD is on a branch that differs from the tracking branch only in case (Main for main) is left where it is, so on a disk that folds case branch -f main no longer moves the ref HEAD stands on (#896) #948's keep line ("keep any commit … check out the pin") leaves Main where it is, so the next run refuses again.

• A different way out ends the loop and meets the Goal: git -C <leg> branch -m <spelling> <another name>. The twin disappears and its commits stay on the renamed branch. If HEAD is on the twin, git moves HEAD with the rename, and the next run takes the ordinary "the leg was on <another name>, which keeps its commits" path.

• The cost is more than "a name" (reasoned, not run on APFS). On a real folding disk the twin's packed entry stays in packed-refs. for-each-ref would still list Main at its packed sha, while rev-parse Main and log Main read the new loose main. A later git branch -D Main would unlink the file main.

• refs/stash is a weak holder. It is spared like the others, but a git stash drop removes it.

• Recommendation: refuse every folded spelling under refs/heads/, give the branch -m way out, and amend bootstrap.py: a leg whose HEAD is on a branch that differs from the tracking branch only in case (Main for main) is left where it is, so on a disk that folds case branch -f main no longer moves the ref HEAD stands on (#896) #948's HEAD-twin keep line the same way. Alternatively, rule the departure accepted in the PR. The PR is still strictly better than base in every case I ran.

NIT 1. One mutant survives.

• O1: NFKC in place of NFC in _fold. The new file and the casefold file still pass (49 passed).
• Effect: under O1, main² becomes a twin of main2, and ① of 1; at the head neither is. APFS does not fold compatibility forms.
• Fix: one _folded_twin row for main² against main2, expecting False, kills it.

NIT 2. The conflict with #958's round-1 WIP (b49f34e1) is the expected import-line conflict only. Keep import unicodedata and slice D's from collections.abc import Callable, Iterator. Do not keep both collections.abc lines, which would be a duplicate import.

NIT 3. A point about my own #948 probe. Its "no ref contains M" result came from the symlink emulation, which lists the twin as a loose ref. On a real APFS the packed entry would still be listed (reasoned above), so the harm is a shadowed name and a fragile state rather than an unreachable commit. The PR's "in no ref" wording inherits that overstatement.

Checked and true

1. The merge 5a435acd (check 1).

   • git diff origin/main 5a435acd holds only the two files: bootstrap.py and the new test file, +481/−14.
   • Its sha256 (305ae3a3…) equals that of git diff 45415296 414e9e0a, so the merge adds exactly the assembly root's bootstrap.py: create_at_pin still hides a branch's commits behind a new loose ref when HEAD is detached or a third spelling is packed, and _folded_twin does not fold NFC and NFD #962's change.
   • Main's bootstrap.py blob e31385cd equals 45415296's, so nothing of main's is lost.

2. The probes, at 45415296 and at the head, run with bootstrap.py: a leg whose HEAD is on a branch that differs from the tracking branch only in case (Main for main) is left where it is, so on a disk that folds case branch -f main no longer moves the ref HEAD stands on (#896) #948's fixtures (check 2):

   • (b), detached at the pin over a packed Main: base makes main, and with the fold emulated no ref contains M. At the head the leg is left with the three exact lines; main is not made, and the only head is Main.
   • (c), an unborn Main beside a packed MAIN: base refuses, then after bootstrap.py: a leg whose HEAD is on a branch that differs from the tracking branch only in case (Main for main) is left where it is, so on a disk that folds case branch -f main no longer moves the ref HEAD stands on (#896) #948's way out makes main and hides the commit. At the head both runs refuse, the second naming MAIN.
   • NFD: base prints fast-forwarded, then the leg was on café …, with status D NEW-CONTRACT.md and M README.md. At the head the leg is left, the NFC branch is not moved, status is empty, and the words say "only in case or Unicode form" and "macOS folds both, Windows folds case".

3. bootstrap.py: a leg whose HEAD is on a branch that differs from the tracking branch only in case (Main for main) is left where it is, so on a disk that folds case branch -f main no longer moves the ref HEAD stands on (#896) #948's rules (check 4).

   • I drove place_at_pin, fast_forward_to_pin and create_at_pin through 28,800 calls against main ebbd9fa4, including Main and MAIN twins. All are byte-identical, so bootstrap.py: a leg whose HEAD is on a branch that differs from the tracking branch only in case (Main for main) is left where it is, so on a disk that folds case branch -f main no longer moves the ref HEAD stands on (#896) #948's twin words are unchanged.
   • No twin is ever moved.
   • fast_forward_to_pin has no hunk, so it stays at 15.

4. Mutants (check 5): 7 run, 6 killed.

   Mutant	Result
   w962's: check dropped	5 failed
   w962's: ancestor rule dropped	1 failed
   w962's: no NFC	5 failed
   Mine: ancestor arguments reversed	5 failed
   Mine: way out spelled instead of _paste_word	1 failed
   Mine: the twin counted as its own holder	5 failed
   Mine: NFKC	survives (NIT 1)

5. Runs at 5a435acd (check 6):

   • git 2.43.0: the new file, the casefold file, the pasteable file, test_bootstrap_leg_moves.py and the trio: 291 passed, 0 skipped. test_pinned_copy_text.py also passes.
   • git 2.47.1: the new file: 17 passed.
   • Base check: the new file against 45415296: 10 failed and 7 passed, as the body says.

6. Merges (check 7):

   • with a re-fetched origin/main ebbd9fa4: clean, tree dcf71171;
   • with b2887cf5 (bootstrap.py: the paste words it prints quote a leading =, are made of the bytes git is handed (UTF-8 on Windows), and the NOT INITIALIZED command names a leg's path as one word after a --, with ./ before a : (#961) #973): clean, dc78147a;
   • with b49f34e1 (the assembly root's validate-manifest.py and bootstrap.py: a path this user cannot read is named, never read as absent, so a scripts/ nobody may search no longer SKIPs every validator into bootstrap ok (#430, slice D) #958 WIP): the import-line conflict only (NIT 2).

7. Sonar-style checks and the pinned copy (check 8).

   • Complexity by hand: create_at_pin 14, _spelling_at_risk 5 (the body says 4; the listed or "" counts), _kept_elsewhere 2, _twin_words 1, _say_twin 1.
   • Duplication: no repeated run of 6 or more lines; two 4-line runs.
   • Asserts: none joins conditions with and.
   • Line length: added lines are at most 79 columns. The added bootstrap.py lines are ASCII.
   • Imports: the only new import is the standard library's unicodedata; the repo_shape import set is unchanged.

Could not verify

• A real APFS or NTFS disk: the packed-ref shadowing behaviour described in SHOULD 1 and NIT 3 is reasoned from git's files backend, not measured.
• git 2.55 (CI's version), and Sonar's own analyser.
• I kept within the 25-minute budget, so the wider bootstrap test files were not run.

Checklist candidates

1. The rename way out (branch -m) for every folded spelling, including bootstrap.py: a leg whose HEAD is on a branch that differs from the tracking branch only in case (Main for main) is left where it is, so on a disk that folds case branch -f main no longer moves the ref HEAD stands on (#896) #948's HEAD-twin keep line (SHOULD 1).
2. A _folded_twin row for main² against main2, expecting False (NIT 1).
3. Exclude refs/stash as a holder if _kept_elsewhere stays.
4. The <another name> placeholder makes the way-out line not pasteable as printed (w962's own limit).

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
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

[brettheap]

Fix round 1 on #984 (#962): rv984's SHOULD 1 (lane 5's ruling: refuse every folded spelling, and the way out renames the twin), #948's HEAD-twin keep line, NIT 1 and NIT 3, one commit f1cceddf on 5a435acd, pushed

rv984 found #984 READY at 5a435acd (#984 issuecomment-6254685548). SHOULD 1 was a decision: round 0's _kept_elsewhere made the very ref #962's Goal forbids. Lane 5 ruled to follow the Goal. The push is a fast-forward of fix/962-create-twins from 5a435acd to f1cceddf; nothing was forced. The change is three files: templates/assembly-root/scripts/bootstrap.py, tests/test_bootstrap_create_twins.py and tests/test_bootstrap_casefold_twin.py (three tests changed).

SHOULD 1: no sparing, and the way out renames the twin

• Dropped: _kept_elsewhere and _spelling_at_risk. _folded_spelling(sub, branch) returns the first refs/heads/ ref, packed or loose, that folds (NFC, then casefold) to the branch, whether or not a tag, a remote-tracking ref, another branch, the stash or the pin holds its commits. _heads(sub) is the shared listing.
• The way out: git -C <leg> branch -m <twin> <name>, the path and both names through _paste_word.
• A concrete name, so the line can be pasted as printed: _kept_name(sub, twin) is <twin>-kept, then -kept-2 and on, the first that no branch of the leg folds to. Main-kept is taken when main-kept is there, since on a folding disk they are one file. I chose the concrete name over the <another name> placeholder, as the brief allowed.
• Why the loop is gone: it came from a way out that left the twin in place. The rename removes it, so the next run finds no twin and makes main.
• The state rv984 measured, at 5a435acd (git 2.43.0): a packed Main whose commit a tag holds, main missing, HEAD detached at the pin: branch main created at <pin>. At f1cceddf: the refusal, the rename pasted through /bin/sh (git -C spec branch -m Main Main-kept), and the next run says created, with Main-kept holding the commit. The same for another branch, a remote-tracking ref, the stash and the pin alone (five rows).

#948's HEAD-twin keep line

• Was (a leg ON a twin, main missing): not moving the checkout off it. Keep any commit made there on a branch whose name differs from main by more than case, check out the pin in the leg, and run bootstrap again.
• Now: _say_spelling with where = the checkout is on. Its first two lines are byte for byte bootstrap.py: a leg whose HEAD is on a branch that differs from the tracking branch only in case (Main for main) is left where it is, so on a disk that folds case branch -f main no longer moves the ref HEAD stands on (#896) #948's, and the third is the same rename line.
• HEAD goes with the rename: git branch -m renames the branch HEAD is on and moves HEAD, an unborn branch included (probed on git 2.43.0 and 2.47.1, with and without the dangling link the emulation uses). The next run takes the ordinary path: branch main created at <pin>, then the leg was on Main-kept, which keeps its commits; it is on main now, or a branch with no commit yet for an unborn one.
• End to end, through /bin/sh as printed: a packed Main with HEAD on it (a test); an unborn Main beside a packed MAIN, where run 1 names Main, run 2 names MAIN (MAIN-kept) and run 3 makes main; two twins with commits, where the second name is Main-kept-2 because Main-kept differs from MAIN-kept only in case.
• _say_twin keeps T7 and P9. _say_keep is back to the one-parameter text main had before bootstrap.py: a leg whose HEAD is on a branch that differs from the tracking branch only in case (Main for main) is left where it is, so on a disk that folds case branch -f main no longer moves the ref HEAD stands on (#896) #948, which no twin line uses now; no non-twin line changes.

NIT 1: the NFKC mutant

Two _folded_twin rows, main and U+00B2 against main2, and U+2460 against 1, both expecting False (NFKC would fold them; APFS does not). The NFKC mutant: 2 failed, killed (it survived the 49 tests of round 0).

NIT 2: no change

Against #958 (0ef875c0) and slice D's round 1 (b49f34e1), merge-tree gives one conflict each, the import block of bootstrap.py. The resolution keeps import unicodedata and slice D's from collections.abc import Callable, Iterator; it does not keep both collections.abc lines, which would be a duplicate import. The body says so.

NIT 3: what a folding disk really does

The module docstring, _folded_spelling's docstring, the test file's docstrings and the body no longer say the commit ends "in no ref". They say what rv984 reasoned from git's files backend: the packed Main entry stays, for-each-ref goes on listing it at its old sha while rev-parse Main reads the new file main, and a later git branch -D Main unlinks that file: a shadowed name and a fragile state. This is not measured on APFS or NTFS, and the body says so.

Evidence

• New and changed tests: tests/test_bootstrap_create_twins.py is 31 tests. At 5a435acd, with the two test files copied in: 23 failed, 40 passed. 20 of the new file's 31 fail there; the three changed casefold tests fail (the unborn twin, the packed twin, the non-UTF-8 lines). The 11 that pass there pass by design: mains, the NFD T7 test, the eight _folded_twin rows and the fold test. At the head: 63 passed (the new file and the casefold file).
• Mutants, 16, none survives: the check dropped (10 failed), no NFC (6), always the case words (2), names the branch not the twin (14), NFKC (2), branch for branch -m (17), the rename's arguments swapped (17), _kept_name never loops (4), compares byte for byte (3), the candidate not folded (3), the HEAD-twin line says the leg has the branch (4), the HEAD-twin check dropped (4), the sparing put back (5), the new name not _paste_worded (2), the twin not _paste_worded (2), _heads loose refs only (13). Round 0's four mutants of _kept_elsewhere are gone with the code.
• git 2.43.0, at the tree of f1cceddf: the new file, the casefold file, test_bootstrap_pasteable_lines.py, test_bootstrap_leg_moves.py, test_repo_hygiene.py, test_agents_md_codes.py, test_cli_reference.py and test_pinned_copy_text.py: 392 passed in 1:53. git 2.47.1: the new file and the casefold file: 63 passed. The rest of the suite is left to CI's tests job.
• Output that is not a twin's: a differential of 28 states (4 tracking-branch states by 7 HEAD states, one not a state) against main ebbd9fa4: 27 real states, the printed lines and the leg afterwards, byte for byte the same. Nothing printed for a non-twin differs.
• Merges (git merge-tree --write-tree): origin/main c4dd19dc clean; bootstrap.py: the paste words it prints quote a leading =, are made of the bytes git is handed (UTF-8 on Windows), and the NOT INITIALIZED command names a leg's path as one word after a --, with ./ before a : (#961) #973 (b2887cf5) clean; the assembly root's validate-manifest.py and bootstrap.py: a path this user cannot read is named, never read as absent, so a scripts/ nobody may search no longer SKIPs every validator into bootstrap ok (#430, slice D) #958 and slice D's WIP one import-line conflict each (NIT 2).
• Cognitive complexity (the ast counter): fast_forward_to_pin 15 (unchanged), place_at_pin 6, create_at_pin 14, _folded_spelling 3, _heads 1, _kept_name 1, _say_spelling 0, _say_twin 0. New lines are within 79 columns and the new bootstrap.py lines are ASCII.

Not changed

_paste_word and the NOT INITIALIZED line. T7's and P9's twin lines. Every output that is not a twin's. The body (body.md) is updated: the _kept_elsewhere heading is now the rename way out.

[brettheap]

Re-check of #984 (#962)'s fix round 1 at f1cceddf, for lane openRepoShape-5: READY

I found no MUST or SHOULD. Lane 5's ruling on SHOULD 1 is carried out as ruled. There are two NITs, both small enough for a follow-up.

Findings, most severe first

• NIT 1. _kept_name can print a rename git refuses. templates/assembly-root/scripts/bootstrap.py:875-888 (the loop is at :885).
  • It only checks whether a branch folds to the same name. It does not check for a branch stored under the chosen name.
  • Scenario: the leg is detached at the pin, Main is packed and holds a commit, and a branch Main-kept/x exists.
  • Probe at the head: the printed line is git -C spec branch -m Main Main-kept. Pasted through /bin/sh it exits 128 with error: 'refs/heads/Main-kept/x' exists; cannot create 'refs/heads/Main-kept'. The next run prints the same command again, so the person has to pick a name themselves.
  • On a folding disk, a branch main-kept/x would block the rename the same way.
  • This is false against the docstring's "so the line that says to rename it can be pasted as it is". It is rare, and the line does state the rule, so the person can recover.
  • Fix: also skip a candidate when any held name starts with _fold(name) + "/", and add a row for it.
• NIT 2. No test has a twin whose name contains a slash. My mutant O3 survives with 63 of 63 passing.
  • O3 makes _folded_spelling (:871) return ref.rsplit("/", 1)[-1] instead of ref[len("refs/heads/"):].
  • The real code is right. I probed --branch team/main with a packed Team/main: it is refused, the printed git -C spec branch -m Team/main Team/main-kept works, the next run makes team/main, and Team/main-kept holds the commit.
  • Only a test row is missing.

Checked and true

1. SHOULD 1, as ruled.
   • I re-ran rv984's eight state probes at the head: (b), (c), NFD, and a twin whose commit only a tag, a remote-tracking ref, another branch, the stash or nothing holds. Every one is refused and none makes main. At 5a435acd the four holder cases made main.
   • The test rows also cover the pin itself.
   • The branch -m line, run through /bin/sh, leaves the commit on Main-kept, and the next run makes main. I also checked this in a leg where Main was checked out in a linked worktree: git moved that worktree's HEAD to Main-kept.
   • git check-ref-format --branch accepts Main-kept, Team/main-kept, the NFD café-kept, a@-kept, v1.0-kept and Main-kept-2.
   • By reasoning: adding -kept to a valid name cannot break a ref-format rule, and the fold of <twin>-kept is the fold of the branch plus -kept, so it is never the branch.
2. bootstrap.py: a leg whose HEAD is on a branch that differs from the tracking branch only in case (Main for main) is left where it is, so on a disk that folds case branch -f main no longer moves the ref HEAD stands on (#896) #948's HEAD-twin keep line.
   • A function-level comparison with main (ebbd9fa4, whose bootstrap.py is the same as a19d69cb's): 1,920 calls where create_at_pin runs on a case twin. The first two lines are byte for byte main's in all of them, and the third is the rename line every time.
   • The unborn-twin tests pass on 2.43 and on 2.47.1: the rename moves HEAD, and the next run prints the ordinary "the leg was on Main-kept, a branch with no commit yet" (or "which keeps its commits" for a twin with commits).
   • A HEAD twin with a dirty work tree is renamed, and then hits main's ordinary "could not create branch 'main'... leaving it on Main-kept" refusal. That is the same as for any other branch.
3. The three NITs from my rv984 review.
   • The NFKC mutant is killed (2 failed, the two new rows).
   • The import note is in the body: keep import unicodedata and slice D's Callable, Iterator line, and do not keep both.
   • "Shadowed name, fragile state" is true by reasoning from git's files backend: checkout -b writes a loose file, which the folding disk also reads for Main; the packed entry stays; and branch -D Main would unlink main and drop the packed entry.
4. Unchanged outputs.
   • 47,616 calls to place_at_pin, fast_forward_to_pin and create_at_pin in states that are not a twin's, plus case twins on place and fast-forward: every one is byte for byte main's. Only 4 states that are NFD twins and nothing else were skipped.
   • _say_keep prints main's text, because main's default kept="a branch" gives the same string. Its three callers (:719, :1352, :1358) pass no second argument.
5. Mutants. I re-ran three of w962's: _kept_name never loops (4 failed), the HEAD-twin where wrong (4), sparing put back (5). These match w962's counts. Of my own, O1 (check the twin only when HEAD is detached) failed 1 and O2 (_kept_name with casefold alone) failed 1. O3 survives (NIT 2).
6. Test runs at f1cceddf, through run9.sh.
   • git 2.43.0: the brief's six files, 278 passed. Adding test_pinned_copy_text.py and test_bootstrap_leg_moves.py, 114 passed. 392 in all, which matches the writer.
   • git 2.47.1: the new file, 31 passed. The casefold file, 32 passed. 63 in all, which matches.
7. Merges.
   • Re-fetched origin/main is still a19d69cb, and no commit since ebbd9fa4 touches bootstrap.py or the twin tests. The merge is clean (tree 00653ff2).
   • Against bootstrap.py: the paste words it prints quote a leading =, are made of the bytes git is handed (UTF-8 on Windows), and the NOT INITIALIZED command names a leg's path as one word after a --, with ./ before a : (#961) #973 (b2887cf5) it is clean (tree 678f4cc5). On that predicted merge, the new, casefold, pasteable and pinned-copy files pass: 247 passed.
8. Sonar-style checks.
   • Cognitive complexity: fast_forward_to_pin 15 (same as main), create_at_pin 14 (main 13), place_at_pin 6, _folded_spelling 3, _heads 1, _kept_name 1 (2 if the set comprehension is counted), _say_spelling 0, _say_twin 0.
   • The new lines are ASCII and within 79 columns.
   • The imports from repo_shape are the same seven names as before.
   • The "refs/heads/" literal was already repeated 5 times on main, so the 9 now add to an existing duplication rather than creating a new one.

Could not verify

• Nothing on a real APFS or NTFS disk; the shadowing is reasoned, not measured.
• I did not re-run the merges against the assembly root's validate-manifest.py and bootstrap.py: a path this user cannot read is named, never read as absent, so a scripts/ nobody may search no longer SKIPs every validator into bootstrap ok (#430, slice D) #958 or slice D.
• Outside this round, a possible follow-up: on a folding disk with both main and Main packed, fast_forward_to_pin writes a loose main, which shadows Main the same way. That is main's behaviour already, beyond the assembly root's bootstrap.py: create_at_pin still hides a branch's commits behind a new loose ref when HEAD is detached or a third spelling is packed, and _folded_twin does not fold NFC and NFD #962's create-only Goal, and reasoned, not measured.

[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 2 days and 5 hours by commenting @sourcery-ai review. Upgrade to get a review now.