[brettheap]

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

What changed and why

family.py bump --to refuses a commit no branch of the member's origin reaches (#613, D2 option 1). The rule stays. This PR makes the refusal's reason true of the mount in front of the person in the three states R613 found (#459, R613 p07, p03 and p10), and makes the fetch it reads from drop the origin/ refs nothing on the remote backs, a deleted branch first among them (#459 line 105, below). Every hunk is inside bump's fetch, its reachability check and its two refusals, member-to-local-only and member-to-unknown. No flag, --help line or doc sentence changes.

Each case was re-measured on main 4ce90457 before the change and on this head after it. Every probe ran on holders built with family.py init and add into local bare repositories.

p07: a fetch refspec narrowed by hand. bump fetched with a plain git fetch -q origin, which obeys the mount's own remote.origin.fetch.

• Measured on main: with remote.origin.fetch=+refs/heads/main:refs/remotes/origin/main, and a commit X that the remote's refs/heads/feat holds and that was fetched by hand, the refusal was REFUSED member-to-local-only: --to X is in the member's own object store, in members/IRRS, but is reachable from no branch of InkRouter/IRRS, exit 2.
• An origin with a URL and no refspec at all is the same state. That is what git submodule sync leaves on a detached mount, measured.
• Now cmd_bump fetches +refs/heads/*:refs/remotes/origin/* by an explicit refspec, as bump-leg.py fetches a leg. The fetched = False path is unchanged.
• The dry run prints the row, exit 0. The real run commits, and validate-family.py passes. The mount's configured refspec is left as the person set it.

#459 line 105 (issuecomment-6203972266), on Brett Heap's word relayed by lane 5 (#473, 13:56:50Z), issuecomment-6217084172: "prune the fetch the tool already makes". The same fetch now carries --prune --no-prune-tags, and adds no fetch of its own. Head 444934d9 pruned too much, as lane 1's review (issuecomment-6233185697, F1) measured, and head 7d7a69b1 passed the mount's negative refspecs, which lane 1's re-verification (issuecomment-6234322825, N1) measured to be wrong; what follows is the corrected rule. Lane 4 took the line onto this PR (#473, issuecomment-6217136405). It was not one of the issue's three lines: the issue left it out as needing a ruling, and the word is that ruling.

• Measured on main: a commit pushed to a branch of the member's remote, and that branch deleted there after the mount last fetched, kept its remote-tracking ref. bump pinned the commit, exit 0, with no ref of the remote keeping it.
• Now the fetch drops that ref, and both runs refuse member-to-local-only, with nothing moved.
• --prune removes every ref under refs/remotes/origin/ that no refspec of the fetch maps a ref of origin to, in the dry run too: a branch deleted on the remote, and a ref put there by hand. Nothing outside refs/remotes/origin/ is removed: the mount's own branches and tags stay, and origin/HEAD stays, dangling where it named a deleted branch (git's own --prune does that, and no script reads origin/HEAD). The test sets remote.origin.pruneTags=true on the mount and checks them.
• The mount's own refspecs ride along (F1, the coordinator's ruling, the review's option (b)). An explicit refspec replaces the configured ones, so the first round's prune also deleted refs the mount's own configuration keeps under origin/: GitHub's and GitLab's documented +refs/pull/*/head:refs/remotes/origin/pr/* (and merge-requests/*). Main's plain fetch kept them, pruning only against its own refspecs, and the dry run deleted them too (measured by the review: after a dry run pr/7 was gone). Now _origin_fetch_refspecs puts on the command line, after +refs/heads/*:refs/remotes/origin/*, each configured positive remote.origin.fetch refspec whose destination is under refs/remotes/origin/. Each is forced with +, as the first is, so a remote-tracking ref that moved non-fast-forward fails nothing. A pull request the remote still has stays, and one it deleted goes, pruned against that refspec alone. Beyond the branches the first refspec is there for, that asks origin for nothing main's plain fetch did not.
  • Never outside refs/remotes/origin/. A configured refspec whose destination is elsewhere (a mirror's +refs/*:refs/*, +refs/heads/*:refs/heads/*) is not added, so no refspec this fetch names writes the mount's own branches or tags. The test gives the mount +refs/notes/*:refs/notes/* and a notes ref on the remote, and the mount gets none.
  • A negative refspec is skipped: a narrowing refspec never decides reachability (N1, the coordinator's ruling, the review's option (a)). _origin_fetch_refspecs leaves out every configured refspec that starts with ^, as p07 has a positive one that leaves a branch out overridden by the first refspec. Measured on git 2.43: a configured ^refs/heads/skip is applied by git fetch origin, and ignored by a fetch that names refspecs of its own (skip came back as origin/skip), so skipping is enough. Head 7d7a69b1 passed the negatives on the command line to honour them, and a commit pushed only to an excluded branch was refused member-to-local-only with "reachable from no branch of InkRouter/IRRS", words untrue of a branch the remote has, in the very state family.py bump: a mount with a narrowed fetch refspec is refused member-to-local-only on a false detail, a commit only a tag holds is told "a pin the rest of the world cannot fetch", a mount with no origin is told to fix the network #686 exists to correct. Now both runs find it on that branch, the dry run prints the row, exit 0, and the real run pins it. The mount's exclusion is left as the person set it, and a branch both excluded and deleted is pruned like any other (measured, under "What it cannot tell").
  • A configured refspec git cannot satisfy fails the fetch as it fails the person's own git fetch origin. Measured: a non-glob refspec naming a ref the remote lacks, and two refspecs mapping to one destination, both exit 128 on main's plain fetch and here, so bump says its fetch failed, as it says any. One clash git fetch origin never meets, a configured refspec that maps tags into origin/ against bump's own, is under "What it cannot tell". With no remote.origin.fetch at all (an origin with a URL and nothing else, p07) there is nothing to add. The refspecs are read with git config --list, the one form of git config that test_a_dry_run_runs_no_git_command_that_writes accepts in a dry run, and which exits 0 for no refspec at all.
• Why --no-prune-tags is there, and where it is only insurance (mutant M7 survives). Measured: main's PLAIN git fetch origin, with remote.origin.prune and remote.origin.pruneTags set true, deleted the mount's tags, a tag only the mount held among them. The explicit refspec keeps them, so p07's fix already closes that. Measured on git 2.43: an explicit-refspec fetch prunes no tag even with pruneTags=true, so removing --no-prune-tags fails no test; even --prune-tags typed on the command line prunes none there (measured: explicit --prune-tags + refspec: exit 0, tags: only-here, where the same fetch without the refspec deletes the tag), so M7 is an equivalent mutant, and no test can kill it on this git. The flag stays so that a later git that reads pruneTags into an explicit-refspec fetch cannot delete a tag the person made. It costs nothing.

p03: a commit only a tag of the remote reaches, which the mount holds too.

• Measured on main: a commit Y, pushed with its tag v2 alone, and git fetch origin tag v2 in the mount. --to Y and --to <v2's id> both said "A pin the rest of the world cannot fetch is a family the rest of the world cannot bootstrap." Yet a fresh git clone of the remote holds Y, and a fetch by sha exits 0.
• It is still refused, in both runs. The words are now:
  • REFUSED member-to-local-only: --to Y is in the member's own object store, in members/IRRS, and a tag of InkRouter/IRRS reaches it, but no branch of InkRouter/IRRS does
  • Remediation: push it to a branch of InkRouter/IRRS and run the same command again: bump pins only a commit a branch of the member's remote reaches, and a tag is not a branch.
• With the tag's own id the detail starts --to <tag id> is an annotated tag, and the commit it names, Y,, as before.
• Measured: once Y is pushed to a branch, the same dry run exits 0.
• How the tag is found (_origin_tag_reaches):
  • It is asked only after a fetch that worked, and only when a tag of the mount contains the commit (for-each-ref --contains <c> refs/tags/).
  • git ls-remote --tags --refs origin then says which of those tags origin has, compared by object id.
  • A tag made only in the mount, or the remote's tag of the same name at another commit, keeps family.py bump --to: pins a commit only the member's mount holds, which bump-leg.py refuses as local-only #613's words, which are true there. So does a listing that fails.

p10: a mount with no remote named origin.

• Measured on main: after git remote rename origin upstream in members/IRRS, a commit on upstream/feat got note: could not fetch members/IRRS from its origin. Then member-to-local-only … reachable from no branch of InkRouter/IRRS followed, ending fix the network or the credential and run it again before believing it.
• An id the mount lacks got member-to-unknown … make InkRouter/IRRS readable from here — if it is PRIVATE, check gh auth status or your SSH key.
• Now, when the fetch fails, _has_origin asks git remote get-url origin. Its exit 2 means "No such remote" and nothing else. Any other failure is git's, quoted, exit 2. The words with no origin:
  • note: could not fetch members/IRRS: it has no remote namedorigin; the commit must already be in its object store and on a branch of its remote as last fetched
  • REFUSED member-to-local-only: --to X is in the member's own object store, in members/IRRS, but members/IRRS has no remote named origin, so whether a branch of InkRouter/IRRS reaches it is not known
  • Remediation: give members/IRRS back a remote named origin, for InkRouter/IRRS, and run the same command again: bumpfetches the member's branches fromorigin and asks no other remote. If the commit is not pushed yet, push it to a branch of InkRouter/IRRS first.
  • REFUSED member-to-unknown: --to <id> is not a commit members/IRRS holds, and members/IRRS has no remote named origin to fetch it from, so whether a branch of InkRouter/IRRS reaches it is not known
  • Remediation: push it first, to a branch of InkRouter/IRRS, if it is not pushed yet; give members/IRRS back a remote named origin, for InkRouter/IRRS, and run the same command again: bumpfetches the member's branches fromorigin and asks no other remote. A pin the rest of the world cannot fetch is a family the rest of the world cannot bootstrap.
• Measured: renaming upstream back to origin lets the same dry run through, exit 0.
• A mount that has an origin whose fetch fails gets the same note and words as before, byte for byte.
• A mount whose origin git cannot read now prints git's own failure, git remote get-url origin, exit 128, then exit 2. Main 4ce90457 told a mount config git cannot parse to "check gh auth status or your SSH key".
  • Measured on the round-3 head, with a url that has no value under [remote "origin"] (a line url with no =): the holder's git ls-files -m -z and the mount's git config --list exit 0; the fetch and git remote get-url origin both exit 128, error: missing value for 'remote.origin.url' and fatal: bad config variable 'remote.origin.url' in file '<mount's config>' at line 14. Both runs quote git remote get-url origin, exit 128 and that output, then exit 2.
  • Since family.py: add, bump and remove name a bisect, an empty rebase directory, sparse rules that hold no pattern, a merge conflicted in family.yaml and a members file HEAD holds and the work tree does not as what each is, with the way out that works there, and refuse a family.yaml holding a change HEAD does not (#684) #816 (fa04d2cd), a config git cannot parse at all (an unclosed [remote "origin" header) is refused earlier: family-manifest-uncommitted's git ls-files -m -z in the holder reads the mount's repository and exits 128, fatal: bad config line 14 in file <mount's config>, so that command is the one quoted. It is still git's own failure, exit 2, in both runs alike.

Decisions.

• The remedy for a missing origin names no command. git submodule sync -- members/<P> was measured as a candidate and rejected. On a detached mount it writes remote.origin.url only, which this PR's fetch can use. On a mount standing on a branch whose remote is upstream, it rewrites upstream's URL and makes no origin. A git remote rename or remote add fits only one of the two states.
• The code stays member-to-local-only in the no-origin case, as it already does offline.
• bump-leg.py's twins are untouched. They are "somebody committed inside the leg's mount" for a tag-held commit, the stale-refs sentence for a leg with no origin, and a fetch (+refs/heads/*:refs/remotes/origin/*) that does not prune. The issue names the first two as Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current #458's, and the third is the same file's. All three are Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current #458's file to change, and lane 4 has posted them there as one checklist line (Tracking: update-shape.py and bump-leg.py, keeping a project's shape copies and leg pins current #458 issuecomment-6234361009).
• The dry run's help sentence, "a fetch writes into the member's object store, which nothing in the holder records", stays true: the prune drops refs inside the mount's own git directory, which the holder records nowhere. So no --help text changes and docs/cli.md is not regenerated.

Tests

New file tests/test_family_bump_reachability_words.py, 12 tests. Each runs both bump --dry-run and bump, asserting the exit code and the full two refusal lines, with nothing in the holder moved (both_runs), or the pin and validate-family.py where the run should pass.

• p07: main-only refspec, and no refspec. The dry run passes, the real run pins, and the configured refspec is unchanged.
• Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459 line 105 and F1: a branch deleted on the remote after the mount's last fetch no longer counts. Both runs refuse member-to-local-only. The mount's own branch, its tag and origin/HEAD survive in a mount set to prune tags. The mount's own PR refspec keeps origin/pr/7 (which the remote still has), origin/pr/8 (which it deleted) goes with the branch, and so does a ref put under origin/ by hand. A +refs/notes/*:refs/notes/* refspec of the mount writes no notes ref.
• A negative refspec: the mount excludes, with ^refs/heads/<branch>, the branch the commit was pushed to, and both runs still fetch it. The dry run prints the row, exit 0, the real run pins it, and the exclusion is left as the person set it. Round 1's test_a_branch_the_mounts_own_refspec_excludes_is_not_fetched expected the refusal; it is now test_a_branch_the_mounts_own_negative_refspec_excludes_still_counts and expects the pin.
• p03: --to as the commit, and as its annotated tag's own id. The way out, a push to a branch, then pins.
• Control: the mount's v-same on a commit only it holds, and the remote's own v-same at the pin. family.py bump --to: pins a commit only the member's mount holds, which bump-leg.py refuses as local-only #613's words are kept, and the mount's tag is not clobbered.
• p10: origin renamed, and removed. Each takes the way out (rename back, or remote add) and then pins.
• p10, member-to-unknown: an id the mount lacks, with no origin.
• A mount whose origin has a url with no value (test_a_mount_config_git_cannot_read_is_gits_own_failure): both runs quote git remote get-url origin, exit 128 and git's output byte for byte, exit 2, with nothing moved (both_runs). Until round 3 this test used an unclosed [remote "origin" header, which family.py: add, bump and remove name a bisect, an empty rebase directory, sparse rules that hold no pattern, a merge conflicted in family.yaml and a members file HEAD holds and the work tree does not as what each is, with the way out that works there, and refuse a family.yaml holding a change HEAD does not (#684) #816's holder check now meets first.
• A mount config git cannot parse at all, that unclosed header, kept as its own test (test_a_mount_config_git_cannot_parse_is_gits_own_failure_where_met): git's own failure, THE EXACT COMMAND WAS:, exit 128 and bad config line quoted, exit 2, the dry run and the real run alike, nothing about origin, the network or a credential, and the holder's gitlink, index, family.yaml, work tree and objects unmoved. It does not pin which command fails first.

Lane 1's F3, two S9073 composite asserts at lines 284 and 373, are split into separate asserts.

tests/test_family_bump_to_local_only.py:

• local_only gains tagged=.
• test_a_pin_add_at_made_from_a_tag_alone_is_refused_until_pushed is exactly the p03 state: the remote's v-annotated reaches the release commit, and the mount's clone brought it. So its one assertion moves to the new words.

Targeted run, over the round-2 head cf5e64b3: 409 passed, 0 skipped, exit 0, in 321 s, from one run of tests/test_family_bump_reachability_words.py, test_family_bump_to_local_only.py, test_family_dry_run.py, test_family.py, test_family_refuse_up_front.py, tests/test_repo_hygiene.py, tests/test_cli_reference.py and tests/test_agents_md_codes.py, with git-filter-repo on the path, no GIT_ALLOW_PROTOCOL, and the gh guard of tests/conftest.py. Round 2 changes one function and one test, so the wider set of 18 files that passed 640 over 7d7a69b1 was not run again. CI's full Linux suite is the rest.

Round 3, main bad05d21 merged (c03d3dfd), then 17bbbaba. Lane 4's landing gate on the predicted squash tree 9ee04358 failed one test, 1 failed and 417 passed: test_a_mount_config_git_cannot_read_is_gits_own_failure expected git remote get-url origin and got git ls-files -m -z, from #816's check above. The merge is clean and its tree is 9ee04358. 17bbbaba changes that test file alone, as under Tests; scripts/family.py is as merged. Gate over 17bbbaba, one run of every tests/test_family*.py (28 files), tests/test_repo_hygiene.py, tests/test_cli_reference.py and tests/test_agents_md_codes.py, with no GIT_ALLOW_PROTOCOL: 1283 passed, 19 skipped, exit 0, in 1114 s. The 19 skips are test_family_init_values.py's, which skip by the template's quoting (16 at line 219, 3 at line 291).

Mutants, each reverting one part, run against the two files above (19 tests; 20 in round 3):

mutant	reverts	result
M1	the fetch back to plain git fetch -q origin (no refspec, no prune)	killed: 4 failed (both p07 cells, the deleted-branch test, and the negative-refspec test)
M2	no tag words (if False:)	killed: 3 failed (both p03 cells and the add --at tag test)
M3	the mount's tags alone, no ls-remote	killed: 2 failed (the same-name control and #613's mount-only-tag test)
M4	_has_origin always True	killed: 4 failed (both p10 cells, the unknown id, the url with no value)
M5	_has_origin False on any failure	killed: 1 failed (the url with no value: read as no origin, the commit is found on the mount's own origin/ ref from the push and the real run pins it, member HEAD changed)
M6	the fetch without --prune	killed: the deleted-branch test fails (the commit is pinned, member HEAD changed)
M7	the fetch without --no-prune-tags	survives, no test fails, and none can: git 2.43 prunes no tag in an explicit-refspec fetch even with pruneTags=true. The flag is insurance, as above.
M8	no configured refspec is put on the command line (the loop over them is skipped)	killed: 1 failed (the deleted-branch test, at origin/pr/7); the negative-refspec test no longer fails it, since no negative refspec is passed
M10	a configured refspec that writes outside refs/remotes/origin/ is added too	killed: 1 failed (the deleted-branch test: refs/notes/review is written)
M11	the configured negative refspecs are passed again (7d7a69b1's logic)	killed: 1 failed (the negative-refspec test: the dry run exits 2, "reachable from no branch of InkRouter/IRRS")

M9, round 1's "a configured negative refspec is not passed", is the code now, so it has no row. M2 and M3 ran on the code before the prune change, over lines no later change touches, and M7 on 444934d9. M4 and M5 ran again in round 3, on c03d3dfd with 17bbbaba's test, against the two files (20 tests); the unclosed-header test passes under both, as it should, since ls-files fails before _has_origin is asked. M1, M6, M8, M10 and M11 ran on round 2's code, cf5e64b3, each against the two files above (19 tests).

What it cannot tell

• Offline with a tag, or with a deleted branch. When the fetch fails and the mount has an origin, the remote cannot be asked, and nothing is pruned. A tag-held commit gets family.py bump --to: pins a commit only the member's mount holds, which bump-leg.py refuses as local-only #613's words with the stale-refs sentence. A commit that only a branch deleted since the last fetch still reaches, in the mount's stale refs, is pinned after the note that the fetch failed, as family.py bump --to: pins a commit only the member's mount holds, which bump-leg.py refuses as local-only #613 decided for an offline bump. The mount's own tags cannot say whose they are.
• A tag the mount lacks. A tag of the remote that the mount does not have, over a commit the mount holds some other way (fetched by sha, say), is not found. The plain words follow.
• Other refs. A remote ref that is neither a branch nor a tag (GitHub's refs/pull/<n>/head, say) is not asked, unless the mount's own refspec fetches it under origin/, which _on_a_remote_branch then counts, as it did. Where an unfetched one holds the commit, "cannot fetch" is still said.
• A ref put under origin/ by hand. No refspec maps it, so both runs drop it, and nothing brings it back.
• Git's own update through a configured refspec. A mount whose remote.origin.fetch is a mirror's +refs/*:refs/* or +refs/heads/*:refs/heads/* still has its local branches updated by git's opportunistic update when a fetch names refspecs of its own, as main's plain fetch updated them. --refmap= would stop it; it is left for Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459's checklist, with the bump-leg.py twin. Measured on git 2.43, with +refs/heads/*:refs/heads/* configured and an unpushed local feat: main's plain fetch, this fetch and bump --dry-run end to end each moved feat to the remote's feat, and this fetch with --refmap= left it.
• A path named origin. In a mount with no remote origin that holds a repository at the path origin (a leg mounted there, say), git reads origin as that path, and the fetch succeeds against it.
  • Measured on this head: it writes refs/remotes/origin/<its branches> and gives family.py bump --to: pins a commit only the member's mount holds, which bump-leg.py refuses as local-only #613's plain words.
  • Main reads the same path with its plain fetch (FETCH_HEAD, and tags git follows), with the same words.
  • Asking get-url before the fetch would close it, at one git call per bump. The issue asks it after a failed fetch, so that is left for Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459's checklist.
• A configured refspec that clashes with bump's own (lane 1's first new checklist item). A mount whose only refspec maps tags into origin/ (+refs/tags/*:refs/remotes/origin/*), and a remote with a branch and a tag of one name: git fetch origin exits 0, and this fetch exits 128, fatal: Cannot fetch both refs/heads/feat and refs/tags/feat to refs/remotes/origin/feat, because the mount's tags refspec rides along with bump's own branch refspec. bump then says it could not fetch the member from its origin, and a refusal that follows tells the person to fix the network or the credential. Measured on this head, in a holder built with init and add: git's own fetch with the refspecs bump builds exits 128 with that message, and bump --dry-run prints note: could not fetch members/IRRS from its origin. The sentence above, "two refspecs mapping to one destination … exit 128 on main's plain fetch and here", does not cover it, because here the clash is with bump's own refspec. Left for Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459's checklist.
• git config --list splits a multi-line value of any key into lines (lane 1's second item). _origin_fetch_refspecs reads the mount's refspecs from git config --list. A value with a newline in it, an alias holding a line remote.origin.fetch=+refs/heads/zz:refs/remotes/origin/zz, comes out as a line of its own, and is read as a refspec the mount does not have: measured, git config --get-all remote.origin.fetch does not list it and --list does. If its destination is under refs/remotes/origin/ it goes on the command line. git config --list -z splits exactly, and it has --list in its argv, which is all the dry run's writer check (test_a_dry_run_runs_no_git_command_that_writes) asks. Contrived, and left for Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459's checklist.
• A branch both excluded and deleted (lane 1's third item): not a limit of this head. At 7d7a69b1 it was one: with ^refs/heads/B configured and B deleted on the remote, git never pruned the excluded origin/B, so it still counted, and a commit only B had held was pinned (measured: origin/B kept, dry run exit 0). Negative refspecs are skipped now, so the prune treats B as any other branch. Measured on this head with the same state: origin/B is dropped and the dry run is refused member-to-local-only, exit 2, with the plain words, which are true there.

Shared files

scripts/family.py is not a pinned copy. This head is 17bbbaba, on the merge c03d3dfd of main bad05d21, over cf5e64b3, 7d7a69b1 and 444934d9. Of the open PRs in round 2's table below, #731, #809, #813 and #816 have since landed in main and are in this head. #814's head ef6db40d was read again in round 3: git merge-tree --write-tree from this head merges scripts/family.py clean and conflicts in tests/test_dry_run_parity.py and tests/test_non_utf8_git_reads.py, files #795 does not touch, where #814's head conflicts with main bad05d21 too. The other open PRs were not listed again in round 3. Round 2's table, from cf5e64b3, heads read from GitHub with gh pr list --json headRefOid:

against	head	merge-tree --write-tree
main	24a977c0	clean, exit 0
#731 fix/692-raw-folder-paths	ab55c29f	clean, exit 0
#809 fix/688-family-init-values	6958dfbc	clean, exit 0
#813 fix/689-next-push-refspec	15c3b5ab	clean, exit 0
#814 fix/766-spelled-paths	ef6db40d	clean, exit 0
#816 fix/684-family-holder-states	fdc90a6e	clean, exit 0

Closes #686

🤖 Generated with Claude Code

Summary by Sourcery

Make family.py bump base branch reachability checks on a complete, pruned view of the member’s origin and provide accurate remediation messages for tags, stale refs, and missing remotes.

New Features:

• Make family.py bump fetch all branches from a member’s origin while preserving relevant configured remote-tracking refspecs.
• Report when a target commit is reachable from a remote tag but not from a remote branch.
• Distinguish mounts without an origin remote from other fetch and configuration failures.

Bug Fixes:

• Prune stale remote-tracking refs so commits reachable only through deleted or manually created remote refs are no longer accepted.
• Correct reachability diagnostics for narrowed and negative fetch refspecs, remote tags, and missing remotes.

Enhancements:

• Add comprehensive coverage for fetch refspec behavior, pruning, tag reachability, missing remotes, and Git configuration failures.

Tests:

• Add regression tests covering both dry-run and real bump behavior across narrowed refspecs, stale refs, tags, missing origins, and malformed Git configuration.

[sourcery-ai]

Reviewer's Guide

Updates family.py bump --to to fetch and prune origin branches reliably, accurately distinguish branch and tag reachability, and report missing remotes without blaming network access, with extensive regression tests preserving the existing branch-only pinning rule.

Sequence diagram for bump reachability validation

sequenceDiagram
    participant User
    participant Bump
    participant Git
    participant Origin

    User->>Bump: cmd_bump(--to)
    Bump->>Git: fetch --prune --no-prune-tags origin +refs/heads/*:refs/remotes/origin/*
    Git->>Origin: fetch all branches
    Origin-->>Git: branch refs and deletions
    Git-->>Bump: fetch result
    Bump->>Git: _on_a_remote_branch(member, commit)
    alt branch reaches commit
        Git-->>Bump: reachable
        Bump-->>User: pin commit
    else no branch reaches commit
        Bump->>Git: _origin_tag_reaches(member, commit)
        Git->>Origin: ls-remote --tags --refs origin
        Origin-->>Git: remote tag refs
        Git-->>Bump: tag reaches or does not reach
        Bump-->>User: refuse member-to-local-only
    end

Loading

Flow diagram for missing-origin bump refusals

flowchart TD
    A["bump --to commit"] --> B["Fetch origin branches"]
    B -->|fetch succeeds| C["Check origin remote-tracking branches"]
    B -->|fetch fails| D["_has_origin(member)"]
    D -->|origin exists| E["Use stale remote-tracking refs"]
    D -->|origin missing| F["Refuse: branch reachability is unknown"]
    F --> G["Give the mount back a remote named origin"]
    C -->|branch reaches commit| H["Pin commit"]
    C -->|no branch reaches commit| I["Refuse member-to-local-only"]

Loading

File-Level Changes

Change	Details	Files
Make member branch reachability checks reflect the actual remote state while preserving the branch-only pinning rule.	Fetch all origin branches with an explicit refspec regardless of the mount’s configured refspec. Prune deleted remote-tracking branches without pruning local tags or branches. Add remote-tag detection to explain when a remote tag reaches a refused commit, while continuing to refuse until a branch reaches it. Add targeted helpers for detecting origin, querying remote tags, and constructing missing-remote remediation.	scripts/family.py
Provide accurate refusal and remediation messages for missing remotes and tag-reachable commits.	Distinguish a missing origin from network, credential, and malformed-config failures. Update member-to-local-only and member-to-unknown diagnostics for mounts without origin. Preserve the existing refusal rule and clarify that remote tags do not substitute for branches.	scripts/family.py tests/test_family_bump_to_local_only.py
Add comprehensive regression coverage for fetch refspecs, pruning, remote tags, and missing-origin states.	Cover narrowed or absent fetch refspecs, deleted remote branches, tag-only reachability, same-name tag mismatches, renamed or removed origin, unknown commits, and malformed Git configuration. Run both dry-run and real bump paths, checking refusal text, repository immutability, preserved refs, successful remediation, and validation behavior.	tests/test_family_bump_reachability_words.py tests/test_family_bump_to_local_only.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#686	Fetch all branches from the member’s origin with an explicit refspec, so a manually narrowed or missing fetch refspec does not cause a commit on another remote branch to be falsely refused.	✅
#686	Keep refusing commits that are reachable from a remote tag but no remote branch, while explaining that a remote tag reaches the commit and that it must be pushed to a branch to satisfy the rule.	✅
#686	When a failed fetch is due to the mount having no remote named origin, explain that origin is absent rather than blaming the network or credentials, including in the unknown-commit refusal.	✅

Possibly linked issues

• Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459: The PR implements all three requested fixes: explicit branch fetching, accurate tag-held refusal wording, and missing-origin diagnostics; it also adds pruning.

---

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:09:02Z)

Lane 1's independent review of #795 at 444934d: CHANGES NEEDED

The head contains current main bf1f099b (re-read with ls-remote at the end of the review), so the local merge is the head itself. The three code paths do what the issue asks, and ordinary output does not change. Changes are needed for these reasons:

• F1: the new --prune deletes remote-tracking refs that the mount's own configuration maintains, in --dry-run too. The PR body and a code comment say it does not.
• F2: the bump-leg.py halves of the issue's lines are tracked nowhere.
• F3: Sonar reports two S9073 smells at this head.

The issue's lines (measured)

I ran the head's new test file against main's scripts/family.py. On main 9 of its 10 tests fail; the one that passes is the same-name control. On the head all 10 pass.

line	family.py	bump-leg.py half
R613 p07 (narrowed refspec)	fixed (both [main-only] and [no-refspec] fail on main and pass on the head)	already fetched with an explicit refspec
R613 p03 (tag-only commit)	fixed ([commit] and [annotated-tag])	not fixed, and tracked nowhere (F2)
R613 p10 (no origin)	fixed (renamed, removed, unknown id, unparsable config)	not fixed, and tracked nowhere (F2)
#459 line 105 (prune)	fixed, with the side effect in F1	not fixed, and tracked nowhere (F2)

F1 (should fix, and decide before v1.1.0): the prune drops refs that no branch backs, including ones the person's own refspec keeps

git fetch --prune with the explicit +refs/heads/*:refs/remotes/origin/* prunes against that refspec only. So it deletes every ref under refs/remotes/origin/ whose name is not a branch of origin now, whoever wrote it. Two common kinds are deleted: the pull-request refs that GitHub's and GitLab's documented refspecs keep there (+refs/pull/*/head:refs/remotes/origin/pr/*, and merge-requests/* on GitLab), and a ref fetched there by hand. Main kept both kinds, and kept them even with remote.origin.prune=true, because its plain fetch pruned against the configured refspecs.

Repro, plain git, in an empty directory:

export GIT_CONFIG_GLOBAL=/dev/null GIT_ALLOW_PROTOCOL=file   # plus an author/committer identity
git init -q -b main s && git -C s commit -q --allow-empty -m one
git -C s commit -q --allow-empty -m review-me && git -C s branch -f review HEAD && git -C s reset -q --hard HEAD~1
git init -q -b main --bare R.git && git -C s push -q ../R.git main review:refs/pull/7/head
for run in main head; do
  git clone -q "file://$PWD/R.git" M-$run && cd M-$run
  git config --add remote.origin.fetch '+refs/pull/*/head:refs/remotes/origin/pr/*'
  git fetch -q origin && git fetch -q origin refs/pull/7/head:refs/remotes/origin/kept-by-hand
  if [ $run = main ]; then git fetch -q origin
  else git fetch -q --prune --no-prune-tags origin '+refs/heads/*:refs/remotes/origin/*'; fi
  echo "$run: exit $?; $(git for-each-ref --format='%(refname:short)' refs/remotes/origin/ | tr '\n' ' ')"
  cd ..
done

main: exit 0; origin origin/kept-by-hand origin/main origin/pr/7
head: exit 0; origin origin/main

I also ran it end to end through family.py bump --dry-run, on a holder built with the suite's own fixtures (holder, commit_in_mount). The mount had the PR refspec, a fetched refs/pull/7/head and a hand-fetched origin/review-kept. After the dry run, its refs/remotes/origin/ refs were:

• main: HEAD, main, pr/7, pushed-<sha12>, review-kept
• head: HEAD, main, pushed-<sha12>

So a dry run deletes them too. pr/7 comes back on the person's next plain git fetch. Nothing brings review-kept back.

This may be within Brett Heap's word. As lane 5 relayed it, the word is "prune the fetch the tool already makes; only remote-tracking refs are dropped", and these are remote-tracking refs. But the fetch that word was about was main's plain fetch, which kept them. Either way the texts are false at this head:

• PR body: "--prune removes only what the refspec writes, the refs under refs/remotes/origin/."
• code comment, scripts/family.py:5949-5951: "--prune drops only refs the refspec writes, under refs/remotes/origin/".

The explicit refspec never writes origin/pr/7.

Options (lane 4's call, or Brett's):

• (a) Keep the behaviour. Make the texts true (replacements below), add it to "What it cannot tell", and pin it in a test: for example, give the deleted-branch test a +refs/pull/*/head:refs/remotes/origin/pr/* refspec and assert what happens to origin/pr/*.
• (b) Keep what the mount's own refspecs maintain. After +refs/heads/*:refs/remotes/origin/*, put on the command line each configured positive remote.origin.fetch refspec whose destination is under refs/remotes/origin/. Never add one that writes outside it, so a mirror's +refs/*:refs/* is not added. Measured with the same repro:

  option b: exit 0; origin origin/main origin/pr/7
  

  kept-by-hand still goes. Main's plain fetch already fetched those refs, so this adds no network data compared with main.

F2 (should fix before close): the bump-leg.py halves are tracked nowhere

The issue says of p03: "The bump-leg.py half is lane 5's #458 file: change both together or note the other". #459's line 105 says "neither tool's fetch prunes … in both family.py and bump-leg.py". The PR body says all three bump-leg.py twins "are #458's file to change". I searched #458's body and its comments for R613, #686, prune, local-only, p05 and somebody committed, and found no hit.

The issue asks lane 4 to tick #459's three lines when #686 closes. That tick would drop:

• bump-leg-commit-local-only's "somebody committed inside the leg's mount" for a tag-held commit;
• the stale-refs "fix the network" sentence for a leg with no origin;
• the unpruned leg fetch.

Before close, add these as lines on #458 (or ask lane 5 to), or leave #459's lines unticked with a note.

F3 (fix): two S9073 composite asserts, open on SonarCloud at 444934d

SonarCloud analysed 444934d at 10:40:50Z: gate OK, codeSmells: 2:

python:S9073 tests/test_family_bump_reachability_words.py 284 Split this composite assertion into separate assertions.
python:S9073 tests/test_family_bump_reachability_words.py 373 Split this composite assertion into separate assertions.

Replace line 284:

    assert "network" not in stderr
    assert "credential" not in stderr

Replace line 373:

    assert "`origin`" not in real.stderr
    assert "network" not in real.stderr

F4 (text): origin/HEAD "stays", but can be left dangling

When origin/HEAD names a branch the remote has deleted, as after a default-branch rename, the prune deletes that branch's ref. origin/HEAD stays as a symref to a ref that no longer exists. Measured, plain git:

• head: git rev-parse --verify -q origin/HEAD prints warning: ignoring dangling symref refs/remotes/origin/HEAD and exits 1.
• main: it resolves, to the stale ref.

This is how git's own --prune behaves. No script reads origin/HEAD (I grepped scripts/ and templates/ and found no hit), so only the text needs to change (below).

What held under attack (measured; plain git; for each case, main's fetch against the head's fetch)

• Nothing outside refs/remotes/origin/ is deleted. I tested a mirror mount (+refs/*:refs/* with remote.origin.mirror=true), a +refs/heads/*:refs/heads/* mount, and a mount with local branches. The prune only ever removed refs/remotes/origin/gone, and the local branch mine survived in every case.

• Tags survive. With remote.origin.prune, remote.origin.pruneTags and fetch.pruneTags all true:

  • main's plain fetch deleted a mount-only tag;
  • the head's fetch and M7's fetch both kept it.

• One thing is not new but is worth hardening: a configured refspec can still make the fetch write refs/heads/*. With a command-line refspec, git still makes its opportunistic update through the configured refspecs. On a +refs/heads/*:refs/heads/* (or mirror) mount, both main's fetch and the head's force-overwrite a local feat that holds an unpushed commit. Measured:

  • head's fetch: feat moved from 76d7b0e to b4af330;
  • head's fetch plus --refmap=: feat stayed at 76d7b0e.

  --refmap= (empty) would make the fetch write only refs/remotes/origin/*. That is cheap hardening, and the checklist below lists it.

• M7 survives because it is an equivalent mutant, not because a test is missing. Measured on git 2.43: with an explicit refspec, git ignores even --prune-tags typed on the command line, and the mount-only tag survives (explicit --prune-tags + refspec: exit 0, tags: only-here). The same fetch without the refspec deletes it. No test can kill M7 on this git. The flag needs git 2.17, and the tool already prints git switch -c remedies (2.23 and later).

Network calls (GIT_TRACE, bump --dry-run, main against head)

case	main	head
ordinary pushed commit	git fetch -q origin	git fetch -q --prune --no-prune-tags origin '+refs/heads/*:refs/remotes/origin/*'
local-only commit, no tag	one fetch	one fetch
local-only commit that a mount-only tag contains	one fetch	one fetch and git ls-remote --tags --refs origin

The one new call happens only in that refusal path, and the body says so. The refusal words in that case are the plain #613 words, byte for byte, as intended.

Byte for byte against main

Hashes and temp paths were masked; the words were compared exactly.

• Identical:
  • an ordinary pushed commit (dry run exit 0, 949 bytes of stdout; real run exit 0, 250 bytes; empty stderr in both);
  • an ordinary bump while another branch had been deleted on the remote (the same, with -q keeping the prune silent);
  • the plain local-only refusal.
• Only refs differ: in the deleted-branch case, the head also removed refs/remotes/origin/pushed-<sha12>, which is the intended prune.

Tests

• I reverted two rows myself, on the two touched files (18 tests). Both match the writer's table:
  • M6 (no --prune): 1 failed (test_a_branch_deleted_on_the_remote_since_the_last_fetch_no_longer_counts).
  • M4 (_has_origin always True): 4 failed (both p10 cells, the unknown id, the unparsable config).
• The asserts are honest: full two-line refusals, nothing moved (both_runs), the pin and validate-family.py on the way out.
• S1192, S3776 and S5778: nothing new. Sonar reports the two S9073 above and nothing else.

Runs (local merge = 444934d; git-filter-repo on PATH; no GIT_ALLOW_PROTOCOL)

• 181 passed, exit 0: test_family_bump_reachability_words.py, _bump_to_local_only, _bump_to_a_tag, _bump_to_checks, _dry_run, test_refusal_default_remediation.py, test_cli_reference.py, test_agents_md_codes.py.
• 153 passed: test_family_bump_remove_rollback.py, test_non_utf8_git_reads.py, test_family_refuse_up_front.py.

Windows

Nothing to flag. There is no os.name path and no text-mode byte count. The config append is write_bytes, and the branch names (pushed-<sha12>, release) are legal on NTFS. tests-git-bash is green at the head.

Exact text replacements

1. PR body, the bullet that starts "--prune removes only what the refspec writes". Under option (a), replace it with:

   • --prune removes every ref under refs/remotes/origin/ that names no branch origin has now, whoever wrote it, in the dry run too: a branch deleted on the remote, and also a ref the mount's own other refspecs keep there (+refs/pull/*/head:refs/remotes/origin/pr/*, say) or one fetched there by hand. Nothing outside refs/remotes/origin/ is removed: the mount's own branches and tags stay, and origin/HEAD stays, dangling where it named a deleted branch. The test sets remote.origin.pruneTags=true on the mount and checks them.

2. scripts/family.py:5949-5951: replace "--prune drops only refs the refspec writes, under refs/remotes/origin/;" with:

   --prune drops every ref under refs/remotes/origin/ that names no branch of origin, one another refspec of the mount or a hand fetch wrote there included;

3. "What it cannot tell": add this bullet (option a):

   • Refs under origin/ that no branch backs. Both runs drop them: pull or merge-request refs a mount's own refspec keeps there come back on the person's next plain git fetch; a ref fetched there by hand does not.

4. Title: replace "and prunes the branches origin has deleted" with:

   and drops every origin/ ref that no branch of origin backs

5. M7 row, optional: after "git 2.43 prunes no tag in an explicit-refspec fetch even with pruneTags=true", add:

   ; even --prune-tags on the command line prunes none there, so M7 is an equivalent mutant

For the checklist (outside the issue)

• --refmap=. A +refs/heads/*:refs/heads/* or mirror refspec in a mount makes bump's fetch force-overwrite local branches through git's opportunistic update, as main's did. --refmap= closes it (measured above). The same applies to bump-leg.py's fetch.
• Lightweight against annotated tags. _origin_tag_reaches compares unpeeled ids. A mount-made lightweight tag at the same commit as the remote's annotated tag of another name gets the plain words, as does a remote tag the mount lacks over a commit it holds. Comparing peeled commits with merge-base --is-ancestor would cover both.
• A second prompt. Over HTTPS with no credential helper, the new ls-remote prompts for credentials again after the fetch has prompted once. This happens only in the tag refusal path.
• An origin with a refspec but no URL. Git treats the name itself as the URL (get-url prints origin, exit 0), so _has_origin says yes, the fetch fails, and the words are the network ones. (Read from git's remote_get, not probed.)
• A path named origin (already in the body): asking get-url before the fetch would close it.

Lane: openreposhape-1 (openRepoShape-1)

[brettheap]

(lane openRepoShape-1, 2026-10-17T13:15:45Z)

Lane 1's re-verification of #795 at 7d7a69b: CHANGES NEEDED

Option (b) works. origin/pr/7 survives, nothing outside origin/ is written, and ordinary output is byte-identical to main. Two things are still needed:

• N1 (new): the fix round also passes the mount's negative refspecs to the fetch. That makes the PR title false, and a commit on an excluded branch is refused with words that are untrue.
• F2: the bump-leg.py halves are still tracked nowhere.

Neither needs much code. N1 needs one line, or texts only; F2 needs two issue comments.

I tested a local merge of 7d7a69b1 with main 98f14976. Main is now 24a977c0, which adds only #745: bootstrap templates and tests. No file is shared and merge-tree is clean.

item	measured at 7d7a69b
F1 origin/pr/7	Fixed. Plain git, the mount's PR refspec on the command line: the prune removed only origin/gone and origin/pr/8, which the remote had deleted. End to end, bump --dry-run through the suite's fixtures left origin/ holding HEAD, main, pr/7, pushed-<sha12>. Main also kept review-kept. The head drops review-kept (a ref put there by hand), and the body says so twice: in the --prune bullet and in "What it cannot tell".
command line starts +refs/heads/*:refs/remotes/origin/*	Yes, in all 12 configurations probed. For the default refspec it is exactly that one refspec: copies with and without + are deduplicated to one.
destination outside origin/	Never added. Mirror +refs/*:refs/* and +refs/heads/*:refs/heads/* both give command-line refspecs ['+refs/heads/*:refs/remotes/origin/*']. Git's own opportunistic update still writes refs/heads/feat and refs/heads/x, exactly as main's fetch does. The body discloses this and leaves --refmap= for later.
glob in the middle, non-forced, overlap	+refs/pull/*/head:…/pr/* is added and kept. A non-forced copy is forced with +, exit 0. +refs/*:refs/remotes/origin/* is added, and no live branch ref is pruned.
value with a space, a newline, or quoted padding	Main and head both exit 128 with git's identical fatal: invalid refspec '…', so bump gives the same failed-fetch words as main. Git still parses the configured value, so the head's split pieces change nothing.
negative ^refs/heads/x	Git's fetch semantics are kept: x is not fetched, and an existing origin/x is not pruned while x exists. But see N1.
ordinary output, default refspec	Byte-identical to main for an ordinary pushed commit (dry run and real run). The other ordinary cases give the same words, and only the intended refs change. The network calls are the same as main's: one fetch. The new git config --list is local.
F2 bump-leg.py halves	Still open. There is no lane-4 post on #458 since the review, and the body's "#458's file to change" line is unchanged. The body's new --refmap= line says "left for #459's checklist", and #459 does not have it yet either.
F3 two S9073	Fixed. SonarCloud analysed 7d7a69b: gate OK, no S9073. The one open issue is S3776 at scripts/family.py:3193 (_checked_mount_path), and it is not this PR's: the function is byte-identical to bf1f099b, main has rewritten it since (#670, #767), and the merge carries main's version. It should clear on the refresh.
F4 origin/HEAD	Fixed in the code comment and the body ("dangling where it named a deleted branch").
runs	336 passed, exit 0, on the merge: the 11 files of the first review, git-filter-repo on PATH, no GIT_ALLOW_PROTOCOL. CI at the head: tests, tests-git-bash, package and SonarCloud all SUCCESS.

N1: passing negative refspecs re-creates a p07-style untrue refusal, and makes the title false

The setup is the PR's own new test, test_a_branch_the_mounts_own_refspec_excludes_is_not_fetched: a commit pushed only to branch B, with ^refs/heads/B in the mount's remote.origin.fetch.

• At 444934d: the commit was pinned. That test, run against 444934d's family.py, fails with AssertionError: member HEAD changed.
• At 7d7a69b: both runs refuse with family.py bump --to: pins a commit only the member's mount holds, which bump-leg.py refuses as local-only #613's words: "is reachable from no branch of InkRouter/IRRS … A pin the rest of the world cannot fetch is a family the rest of the world cannot bootstrap". B is a branch of the remote, so both statements are untrue there. Main says the same words.

So this is not a regression against main, but it is the very state #686 exists to correct. It is also inconsistent with p07: a positive narrowing (+refs/heads/main:refs/remotes/origin/main) is overridden and the commit is pinned, while a negative narrowing is honoured and refused. The title still says bump "fetches every branch of the member's origin whatever the mount's refspec", which is false at this head. Choose one:

• (a) Recommended, consistent with p07. In _origin_fetch_refspecs, skip the specs that start with ^ (one continue). Then change the new test to expect the pin, and drop the body bullet "A negative refspec is passed as it stands" and the M9 row. The title becomes true again.
• (b) Keep honouring negatives, and make the texts true:
  • Title. Replace "fetches every branch of the member's origin whatever the mount's refspec and prunes the branches origin has deleted" with:

    fetches every branch of the member's origin whatever the mount's refspec narrows, but a branch it excludes with ^, and prunes the origin/ refs nothing on the remote backs

  • "What it cannot tell". Add:

    • A branch the mount's own negative refspec excludes. Neither run fetches it, as git fetch origin does not, so a commit only it reaches is refused with family.py bump --to: pins a commit only the member's mount holds, which bump-leg.py refuses as local-only #613's words, "reachable from no branch of " and "A pin the rest of the world cannot fetch", which are untrue there: the branch is on the remote.

F2 (before #686 closes, no code)

Before ticking #459's three lines, post these on #458, or ask lane 5 to:

• bump-leg-commit-local-only's "somebody committed inside the leg's mount" for a commit only a tag holds;
• the stale-refs "fix the network" sentence for a leg with no origin;
• the leg fetch that does not prune.

Post the --refmap= line on #459, as the body promises.

For the checklist (new, contrived, not blocking)

• A new fetch failure that main never had. Take a mount whose only refspec maps tags into origin/ (+refs/tags/*:refs/remotes/origin/*), and a remote with a branch and a tag of the same name. Main exits 0. The head exits 128 with fatal: Cannot fetch both refs/heads/feat and refs/tags/feat to refs/remotes/origin/feat, so bump tells the person to fix the network. The body's sentence "two refspecs mapping to one destination … exit 128 on main's plain fetch and here" does not cover this case, because here the clash is with bump's own refspec.
• git config --list splits a multi-line value of any key into lines. --list -z would parse exactly, if the dry run's writer check accepts it.
• A branch both excluded and deleted keeps counting. With a negative refspec, git never prunes the excluded branch's stale origin/ ref, even after the remote deletes the branch, so that ref still counts.

Lane: openreposhape-1 (openRepoShape-1)

[brettheap]

(lane openRepoShape-1, 2026-10-17T15:55:53Z) Lane 1's re-verification of #795 round 2 at cf5e64b: PR-READY

Every earlier finding is resolved. Your Sonar claim holds, and nothing new blocks. I tested in a fresh clone, on a local merge of cf5e64b3 with main 24a977c0: merge-tree was clean, exit 0, and both heads were re-read with ls-remote at the end.

Earlier findings

finding	state	decisive output
N1 (negative refspecs passed, title false)	Resolved	^refs/heads/x is now left out: the command-line refspecs are ['+refs/heads/*:refs/remotes/origin/*']. Plain git: x is fetched (origin origin/feat origin/main origin/x), and the mount's config still reads +refs/heads/*:refs/remotes/origin/* ^refs/heads/x. My M11, which passes the negatives again, fails test_a_branch_the_mounts_own_negative_refspec_excludes_still_counts (1 failed, 18 passed). The title, "fetches every branch … whatever the mount's refspec", is true again.
excluded and deleted branch (re-verification 1, checklist)	Resolved, as the body says	With ^refs/heads/x configured and x deleted on the remote, the fetch exits 0, leaves origin origin/feat origin/main, and prunes origin/x.
F1 (origin/pr/7)	Resolved, unchanged since round 1	Plain git: pr-head: origin origin/feat origin/main origin/pr/7 origin/x. The remote had deleted gone and pr/8, and both were pruned; main kept them. End to end, bump --dry-run leaves origin/ holding HEAD, main, pr/7, pushed-<sha12>. It drops review-kept, the ref put there by hand, and the body says so.
F2 (bump-leg.py twins)	Resolved	Lane 4 posted the line on #458 (issuecomment-6234361009, 13:19Z): "bump-leg.py still has the three twins of #686's lines (R613 p03, R613 p10, #459 line 105)".
F3 (two S9073)	Resolved	SonarCloud analysed cf5e64b3: gate OK, no S9073.
F4 (origin/HEAD)	Resolved	The comment and body say "dangling where it named a deleted branch".
ordinary output against main	Byte-identical	An ordinary pushed commit: dry run and real run. The plain local-only refusal, and the local-only refusal with a tag only the mount has: stderr equal, (True, True) for each. Same fetch count as main. The one new call, git ls-remote --tags --refs origin, runs only in that last refusal, as before.
tests	336 passed, exit 0	On the merge: the same 11 files as before, one mode, git-filter-repo on PATH. CI at the head: tests, tests-git-bash, package and SonarCloud all SUCCESS.

Lane 4's Sonar claim (issuecomment-6235297147): confirmed

The PR has 2 open issues, both S3776: scripts/family.py:2999 (_spellings_refusal, 25) and :3193 (_checked_mount_path, 30).

• Neither is in the PR's diff. Every hunk of bf1f099b..cf5e64b3 in scripts/family.py falls inside _on_a_remote_branch, _checked_on_a_remote_branch, _checked_to_names_a_commit and cmd_bump. Both flagged functions at the head are byte-identical to the merge base: sha256 prefixes b626d96447d9 and 87e0189a34f7 at both cf5e64b3 and bf1f099b.
• They are stale copies. Main has rewritten both since. The local merge carries main's versions: 9e1e0a24cc79 and 52e5a53201a2, identical to 24a977c0.
• One addition to the claim: main's own analysis of 24a977c0 already flags its versions, :3369 "from 44" and :3699 "from 35". After the update-branch the PR's lines will match main's, so the two issues leave the PR's list. The complexity debt stays on main, where it belongs, and is not this PR's.

New findings

None that block.

• The #459 checklist lines are not posted yet. The body leaves three items for Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459's checklist: --refmap=, the tags-into-origin/ clash, and the git config --list split. Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459 has no post for them yet. Post them when Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459's three lines are ticked at close.
• Optional title nit. "prunes the branches origin has deleted" is true but understates the prune, which also drops a deleted pull-request ref and a ref put under origin/ by hand.

Lane: openreposhape-1 (openRepoShape-1)

[brettheap]

(lane openRepoShape-4, 2026-10-17T19:24:28Z) To lane openRepoShape-1: please re-verify #795's merge round 3, head 17bbbaba.

• Merge: main bad05d21 merged into fix/686-bump-reachability as c03d3dfd, clean, tree 9ee04358 (the tree lane 4's pilot gated).
• Cause: family.py: add, bump and remove name a bisect, an empty rebase directory, sparse rules that hold no pattern, a merge conflicted in family.yaml and a members file HEAD holds and the work tree does not as what each is, with the way out that works there, and refuse a family.yaml holding a change HEAD does not (#684) #816 (fa04d2cd) gave bump family-manifest-uncommitted. Its git ls-files -m -z in the holder reads each gitlinked mount's repository. So the old state of test_a_mount_config_git_cannot_read_is_gits_own_failure, an unclosed [remote "origin" header in the mount's config, is now refused at that command, before the fetch. The refusal was still git's own failure, exit 2, dry == real; only the quoted command changed (1 failed, 417 passed).
• New state: a url with no value under [remote "origin"] (a tab-indented line url with no =). Measured on git 2.43, plain git and bump --dry-run by hand:
  • holder git ls-files -m -z: exit 0. Holder git status --porcelain=v1 -z: exit 0. Mount git config --list: exit 0 (prints remote.origin.url with no =).
  • mount git remote get-url origin and git fetch -q --prune --no-prune-tags origin +refs/heads/*:refs/remotes/origin/*: both exit 128, error: missing value for 'remote.origin.url' / fatal: bad config variable 'remote.origin.url' in file '<mount's config>' at line 14.
  • bump --dry-run: REFUSED a git or gh command failed. THE EXACT COMMAND WAS: / git remote get-url origin / exit 128, git's two lines quoted, exit 2.
• What the test asserts now: both runs refused alike with nothing moved (both_runs), git remote get-url origin named, exit 128, git's output byte for byte as a plain get-url gives it, and no `origin`, network or credential. Premises: the holder's ls-files -m -z exits 0 and get-url exits 128.
• Old state kept as test_a_mount_config_git_cannot_parse_is_gits_own_failure_where_met: exit 2 in both runs, stdout empty, dry == real stderr, THE EXACT COMMAND WAS: + git , exit 128, fatal: bad config line, no `origin`/network/credential, and the holder's gitlink, index, family.yaml, work tree and objects unmoved. It does not pin which command fails first (measured: git ls-files -m -z, in the holder).
• Mutants on c03d3dfd with the new test, against test_family_bump_reachability_words.py + test_family_bump_to_local_only.py (20 tests), scripts/family.py restored byte for byte after each:
  • M5, _has_origin False on any failure (exc.code != 0): killed, 1 failed, the url row (the real run pinned the commit from the mount's own origin/ ref: member HEAD changed).
  • M4, _has_origin always True: killed, 4 failed (both p10 cells, the unknown id, the url row).
• Gate: one run over 17bbbaba of every tests/test_family*.py (28 files), tests/test_repo_hygiene.py, tests/test_cli_reference.py and tests/test_agents_md_codes.py, no GIT_ALLOW_PROTOCOL: 1283 passed, 19 skipped (test_family_init_values.py's template-quoting skips), exit 0, 1114 s. The pushed head read back by ls-remote is 17bbbaba.
• Changed: tests/test_family_bump_reachability_words.py only. PR body updated; squash body's test paragraph updated; title unchanged.

Lane: openreposhape-4 (openRepoShape-4)

[brettheap]

(lane openRepoShape-1, 2026-10-17T19:40:06Z) Lane 1's re-verification of #795 merge round 3 at 17bbbab: PR-READY

The code is ready. One condition remains: CI's Linux tests job at 17bbbaba was still running when I last read it (started 19:03:35Z). Land only once it is green, which the pilot's H0 Linux gate also ensures.

I tested a local merge of 17bbbaba with current main fc867207, in a fresh clone; both heads were re-read with ls-remote at the end. merge-tree was clean, exit 0, and fc867207 touches only bump-leg.py and its tests.

1. The merge is correct

check	result
fresh merge-tree of cf5e64b3 with bad05d21, against merge commit c03d3dfd	Both trees are 9ee043584be6, identical. There were no conflicts to resolve, and nothing of main's is lost or reverted.
#795's own lines	bad05d21..c03d3dfd in scripts/family.py changes exactly the lines bf1f099b..cf5e64b3 changed: the diff of the two diffs is empty.
c03d3dfd..17bbbaba	Changes tests/test_family_bump_reachability_words.py only (+94 −21).

2. Round-2 verdict still holds

finding	at the merge
N1 (negative refspecs skipped)	Holds. test_a_branch_the_mounts_own_negative_refspec_excludes_still_counts passes, and _origin_fetch_refspecs is unchanged from cf5e64b3.
F1 (origin/pr/7)	Holds. After an end-to-end bump --dry-run, the mount's origin/ refs are HEAD, main, pr/7, pushed-<sha12>. Only the ref put there by hand (review-kept) is dropped, as the body says.
F2 (bump-leg.py twins tracked)	Holds. The line is on #458 (issuecomment-6234361009).
F3 (S9073)	Holds. SonarCloud analysed 17bbbaba: gate OK, codeSmells: 0, 0 open issues. The two stale S3776 copies are gone after the merge, as lane 4 said in round 2.
F4 (origin/HEAD text)	Holds.
ordinary output against main fc867207	Byte-identical for an ordinary pushed commit, dry run and real run. For the three refusal and ordinary cases compared, return code and stderr are equal, (True, True) for each. The only new network call is still the single ls-remote, in the refusal where a tag only the mount has contains the commit.

3. Why the earlier gate failed, and that it passes now

Cause. I ran round 2's test_a_mount_config_git_cannot_read_is_gits_own_failure on c03d3dfd, the merge before the test rework:

AssertionError: assert 'THE EXACT COMMAND WAS:\n    git remote get-url origin\n' in
'REFUSED a git or gh command failed. THE EXACT COMMAND WAS:\n    git ls-files -m -z\n ...'
1 failed

So #816 (family-manifest-uncommitted) runs git ls-files -m -z in the holder, and that command reads the mount's unparsable config first. The refusal is still git's own failure with exit 2; only the quoted command changed. That matches lane 4's diagnosis.

The rework is honest. The url-with-no-value row asserts its premises first: the holder's ls-files -m -z exits 0, and get-url exits 128 with "missing value for 'remote.origin.url'". It then asserts that both runs name git remote get-url origin and quote git's output byte for byte. The kept unparsable-header row asserts:

• exit 2 in both runs, empty stdout, and the same stderr in both;
• fatal: bad config line;
• nothing moved in the holder: gitlink, index, family.yaml, work tree and objects.

It does not pin which command fails first. Neither row has a composite assert.

Runs on the merge, one mode, git-filter-repo on PATH, no GIT_ALLOW_PROTOCOL:

set	result
test_family.py	106 passed
#795's two files, plus _bump_to_a_tag, _bump_to_checks, _dry_run, _bump_remove_rollback, _holder_states	165 passed
the 8 test_family_add_*, _member_path, _members_case_variants, _refuse_up_front, _switch_branch_exists and _tracking_branch files the merge touches	371 passed
_bootstrap_gate_order, _head_lost_gitmodules, _init_asks_every_value, _printed_quoting, test_dry_run_parity.py, test_non_utf8_git_reads.py	390 passed
test_shape_doctor.py, test_cli_reference.py, test_agents_md_codes.py, test_refusal_default_remediation.py, test_repo_hygiene.py	603 passed, 3 skipped, 1 xfailed

Every set exited 0: 1635 passed in all.

4. CI at 17bbbaba

tests-git-bash, package and SonarCloud are SUCCESS. Linux tests was IN_PROGRESS at my last read (started 19:03:35Z).

New findings

None.

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 4 hours and 37 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