[brettheap]

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

What changed and why

The defect. A commit made inside members/<Project> and never pushed passed the only question bump asked of --to, git cat-file -t, because the object is in the mount's own store. bump --to pinned it, exit 0, validate-family.py passed, and the holder could then be bootstrapped nowhere else. bump-leg.py refuses its twin as bump-leg-commit-local-only.

The ruling is the triage's D2, option 1, which Brett Heap approved at 2026-10-15T16:49:38Z: refuse it as bump-leg.py does.

The code (scripts/family.py only):

• _checked_to_names_a_commit now routes both of its commit returns through _checked_on_a_remote_branch. One is a plain commit; the other is the commit an annotated tag names, after the family.py bump --to: make the checks add makes (a duplicate id, an annotated tag's own id), and say to push first for an unpushed commit #541 peel. Both are asked after the fetch and before anything is checked out or written.
• _on_a_remote_branch asks bump-leg.py's question in the same git words and under the same name: git for-each-ref --contains <commit> --format=%(refname) refs/remotes/origin/. A failure of the question itself is a CommandFailed, exit 2, never read as an answer.
• The refusal is new: member-to-local-only, exit 2.
  • Its detail says the commit is in the member's own object store, in members/<P>, but reachable from no branch of <repository>. For a peeled tag it names the tag as typed and the commit it names, because the line saying what the tag names is printed only after the check returns.
  • Its remediation says to push it to a branch of the member and run the same command again, keeping bump-leg.py's reason: a pin the rest of the world cannot fetch is a family the rest of the world cannot bootstrap.
  • When the fetch failed, it ends with bump-leg.py's stale-refs sentence, adapted: the answer came from stale remote-tracking refs, so fix the network or the credential and run it again before believing it.
• bump --dry-run asks the same function, so it refuses in the same two lines. The holder is left byte for byte as it was in both runs.
• The split of codes stays. An id the member does not hold after the fetch is still member-to-unknown. A tree, a blob or a tag of either is still member-to-not-a-commit, because reachability is asked only of a commit.
• Offline answers from the remote-tracking refs the mount already has, as bump-leg.py does. A commit they contain is pinned, after the fetch note. A commit they do not contain is refused with the stale-refs sentence. A bump is never refused only because it is offline.
• The fetch note tells the whole rule (fix round 1, F2). The note cmd_bump prints when the member's fetch fails said only half of it, and now reads: note: could not fetch members/<P> from its origin; the commit must already be in its object store and on a branch of its remote as last fetched. These words are cmd_bump's only change.
• Docstrings. _checked_to_names_a_commit gains a paragraph for the new code (D2, family.py bump --to: pins a commit only the member's mount holds, which bump-leg.py refuses as local-only #613). Its paragraph about a tag whose commit is on no branch now says which code each case gets: member-to-unknown where the mount does not hold it, member-to-local-only where it does. The _bump_dry_run and _checked_bump_target docstrings name family.py bump --to: pins a commit only the member's mount holds, which bump-leg.py refuses as local-only #613 beside family.py bump --to: make the checks add makes (a duplicate id, an annotated tag's own id), and say to push first for an unpushed commit #541.

Why the question is written once here rather than shared. bump-leg.py's name has a hyphen, so it can only be loaded by path. That would run a whole command-line tool's top level for one for-each-ref. No module both tools import (repo_shape, shape_materialize) holds the question. Moving it into one would also change bump-leg.py, which this issue does not need. Lane 2's open #622 rewrites family.py's shape_materialize import block and adds to shape_materialize.py, so a shared helper there would also widen that merge.

Not changed.

• --help is unchanged, so docs/cli.md is too.
• add --at is out of scope: it reads a bare clone of the remote, so everything it sees is on the remote.
• AGENTS.md spells no member-to-* code and has no family-codes list for the new code to join. It is at its 492-line cap (tests/test_repo_hygiene.py:633) and is not edited.

Tests

The final run, on the bytes of head d845ec01 (fix round 1; -q -rfEs, test identities, frvenv first, one basetemp): 503 passed, 0 failed, 0 skipped in 300 s. The first head, a15c6601, gave 501 passed over the same files. It covered 15 files:

• test_family_bump_to_local_only.py (new);
• test_family_bump_to_checks.py, test_family_dry_run.py, test_family_bump_remove_rollback.py, test_family_bump_to_a_tag.py, test_family_add_excludes.py;
• test_family.py, test_family_member_path.py, test_family_tracking_branch.py, test_family_add_member_id.py, test_family_remove_gitmodules.py;
• test_refusal_default_remediation.py, test_repo_hygiene.py, test_cli_reference.py, test_agents_md_codes.py.

Discovery run (the code change with the tests unchanged): 12 failed, 314 passed, every failure member-to-local-only. Those are the issue's 12 cases in 5 files, 6 of them through commit_in_mount:

• test_family_bump_to_checks.py: test_bump_to_a_commit_recording_another_rows_id_is_refused_alike, test_a_duplicate_id_read_through_a_linked_manifest_is_put_back, test_a_duplicate_id_behind_a_tag_is_refused_after_the_peel_line;
• test_family_dry_run.py: test_bump_dry_run_reads_the_members_manifest_at_to_and_refuses_as_bump, test_bump_dry_run_leaves_a_linked_manifest_to_the_real_run;
• test_family_bump_remove_rollback.py: test_a_to_with_no_project_yaml_is_refused_before_the_checkout;
• test_family_add_excludes.py: test_bump_moves_the_gitlink_past_the_operators_excludes;
• test_family.py: test_bump_finishes_a_bump_an_earlier_run_staged_and_did_not_commit, and test_bump_with_a_non_ascii_trailer_lands_it_as_typed in all four of its cells.

How they changed: they push first, with no assertion changed.

• One new helper, pushed_from_the_mount in tests/test_family.py, pushes the commit to a branch of a private bare remote beside the holder and points the mount's origin at it. The fixture's own remotes are still only read; the other tests read them, and older is their main~1.
• commit_in_mount (test_family_dry_run.py) pushes through it unless push=False. That covers the 6 cases above.
• commit_in_member (test_family.py) pushes through it, covering 5 cases. Its three other callers bump to the pinned commit or only stage a gitlink, and the push changes nothing they assert.
• The one inline mount commit, in test_bump_moves_the_gitlink_past_the_operators_excludes, calls the helper, and its docstring says so.
• No existing test pinned the mount-only behaviour as its subject, so none was turned into a refusal test.
• family.py bump --to: make the checks add makes (a duplicate id, an annotated tag's own id), and say to push first for an unpushed commit #541's test_a_commit_missing_after_a_failed_fetch_is_not_called_unpushed asserts the fetch note, so it now asserts the note's new words (F2).

New, tests/test_family_bump_to_local_only.py (8 tests on test_family_dry_run.py's harness):

• The issue's case. A commit made in the mount and never pushed: bump --to and bump --to --dry-run both give exit 2 and member-to-local-only, in the same two lines, with nothing on stdout. The holder is unchanged: member HEAD, family.yaml, the index, status, .gitmodules, .git/config, the work tree, objects, HEAD and the gitlink. The premise is checked: the mount holds the commit, no remote-tracking ref contains it, and the member's remote lacks it. The control follows: the same commit, pushed to a branch of the member's remote, is pinned by the same command, exit 0, and the gate is green.
• An annotated tag made in the mount, of such a commit: refused in both runs, naming the tag and the peeled commit.
• A tree and a blob only the mount holds: still member-to-not-a-commit.
• A commit only another remote's branch holds (fix round 1, F1). A commit is pushed only to a second remote of the mount, fork, branch forked. The premise is checked: it is under refs/remotes/fork/ and not under refs/remotes/origin/. Both runs refuse it member-to-local-only, in the same words. This pins ruling 1's refs/remotes/origin/.
• A pin add --at made from a tag alone (fix round 1, D1). The member's remote has a release commit that only its annotated tag reaches. add --at <the tag's id> pins that commit. bump --to that very commit is refused member-to-local-only by both runs, with nothing moved. Once the commit is pushed to a branch of the member, the same command says nothing to do, exit 1.
• Offline, the refs contain it: dry run exit 0 with the row, then the real run pins it. Each has the fetch note as its only stderr line.
• Offline, mount-only: refused in both runs, after the fetch note, with the stale-refs sentence.

Mutants. Each was run in a scratch clone over the new file, test_family_bump_to_checks.py and test_family_dry_run.py: the first two at a15c6601, M7 at d845ec01.

• Reachability check removed (if True: return commit): 3 failed, 70 passed. The issue's case, the tag and offline mount-only cases each fail with member HEAD changed: the real run checked the mount out at the unpushed commit and pinned it.
• refs/heads/ instead of refs/remotes/origin/: 4 failed, 69 passed.
  • The same three fail, because the fixture's mount stands on main, so its local main holds the unpushed commit.
  • So does family.py bump --to: make the checks add makes (a duplicate id, an annotated tag's own id), and say to push first for an unpushed commit #541's test_bump_to_a_commit_not_pushed_says_to_push_it_first. Its commit, pushed from a separate working clone, is on no local branch of the mount, and the mutant refused it as local-only: assert 2 == 0.
• M7, refs/remotes/ (any remote) instead of refs/remotes/origin/ (R613's review): 1 failed, 74 passed. The failure is the new second-remote test: the real run checked the mount out at the fork-only commit and pinned it, member HEAD changed. Before fix round 1, every test passed under M7.

Known limits

• A pin add --at made from a tag alone cannot be named by bump --to again until its commit is pushed to a branch (D1 of R613's review; the coordinator chose option (a), accept and document).
  • The case: a release commit on no branch of the member, with only its tag pushed. add --at <the tag's id> pins that commit, and the mount holds it, because the clone brought every tag.
  • What is now refused: bump --to that same commit, which said nothing to do, exit 1, before family.py bump --to: pins a commit only the member's mount holds, which bump-leg.py refuses as local-only #613. So is validate-family.py's own remedy for a digest that does not recompute (family.py bump --member <P> --to <commit>). Both are now member-to-local-only, exit 2.
  • This follows ruling 1 to the letter: a commit the member holds that no branch of its remote reaches. bump-leg.py refuses its twin alike. The refusal's own way out works: pushing the commit to a branch of the member lets the same command through.
  • _checked_to_names_a_commit's docstring says so. Exempting a --to equal to the row's own pin would need a new ruling.
  • docs/release-notes/v1.0.0.md:260 says a repeated bump says nothing to do. For such a pin that no longer holds; it is a line for the v1.1.0 notes, not this PR.

Shared files

Re-read with ls-remote at 2026-10-15T22:00:55Z for head d845ec01 (R613's verification). Every merge-tree is clean.

• main 7fdec0af: tree 9f1b0916. Since this branch's base 77bb5f0f, main gained adopt-project.py and shape-doctor.py: one reading of origin, so a local clone's right --org is no longer refused, a url ending / names its repository, and the doctor's adoption line asks for --org wherever plan reads none (#521, #427) #591, adopt-project.py: the Makefile block execute appends and the cross-leg follow-up name each leg where the plan mounts it, so --spec-path legs/spec exports a CONTRACTS_DIR that exists and a nested --code-path gets the right ../ path (#522) #572 and shape-doctor.py: the members row says make siblings places the working clones from a holder in a folder named after its repository, and that from anywhere else it clones nothing and prints the mv, as it does since #578 (#605) #624. None of them touches this PR's files.
• family.py: add, bump and remove refuse before their first write a merge, cherry-pick, revert, rebase or git am in progress, a .gitmodules, members/ or family.yaml the sparse checkout leaves out, and a file named members, which each failed after writing and was rolled back, or committed in the wrong place (#612) #626 (lane 4, family.py add, bump and remove: a merge or rebase in progress, an excluded .gitmodules or a members that is a file makes them fail after their first writes #612, fix/family-verbs-refuse-up-front, head 54c30a81): tree 0295b3d6, auto-merging scripts/family.py.
  • family.py: add, bump and remove refuse before their first write a merge, cherry-pick, revert, rebase or git am in progress, a .gitmodules, members/ or family.yaml the sparse checkout leaves out, and a file named members, which each failed after writing and was rolled back, or committed in the wrong place (#612) #626 adds cmd_bump's early refusals before the fetch.
  • This PR changes cmd_bump only in the fetch note's words (fix round 1, F2).
  • Its other hunks are two new helpers above _checked_to_names_a_commit, that function's docstring and two return lines, and one sentence each in the _bump_dry_run and _checked_bump_target docstrings.
• scaffold-project.py and family.py: both runs ask whether each folder they make can be made and take only gh's not-found answer as "absent", so --dry-run refuses a file where a folder goes, or a gh repo view that fails otherwise, by name as the real run does, and a refused init leaves no empty family folder (#609) #622 (lane 2, fix/609-dry-run-parity, head 7f7e1b44): tree c58840b5, auto-merging docs/cli.md, scaffold-project.py and scripts/family.py. It changes family.py's import block, _remote_is_empty, _print_init_plan, _prepare_landing_dir, cmd_init and build_parser.
• The old note's words: no sibling's own test asserts them. family.py: add, bump and remove refuse before their first write a merge, cherry-pick, revert, rebase or git am in progress, a .gitmodules, members/ or family.yaml the sparse checkout leaves out, and a file named members, which each failed after writing and was rolled back, or committed in the wrong place (#612) #626 and scaffold-project.py and family.py: both runs ask whether each folder they make can be made and take only gh's not-found answer as "absent", so --dry-run refuses a file where a folder goes, or a gh repo view that fails otherwise, by name as the real run does, and a refused init leaves no empty family folder (#609) #622 carry them only in the lines they inherited unchanged from main, and every merge above takes this PR's words.

Closes #613

🤖 Generated with Claude Code

[sourcery-ai]

Reviewer's Guide

family.py now refuses bump --to targets that exist only in a member’s object store and are reachable from no branch of its remote, matching bump-leg.py while preserving existing object-type, offline, and refusal-code behavior; tests and fixtures were expanded accordingly.

Sequence diagram for validating a family bump target

sequenceDiagram
    participant User
    participant Family as family.py
    participant Git as member git repository
    participant Remote as origin remote

    User->>Family: bump --to target
    Family->>Git: git fetch origin
    Git-->>Family: fetched refs or CommandFailed
    Family->>Git: git cat-file -t target
    Git-->>Family: commit or annotated tag
    Family->>Git: git for-each-ref --contains commit refs/remotes/origin/
    Git-->>Family: matching remote-tracking branch or none
    alt commit reachable from remote branch
        Family-->>User: continue bump or dry-run
    else commit is local-only
        Family-->>User: Refusal member-to-local-only
    end

Loading

Sequence diagram for offline bump target validation

sequenceDiagram
    participant User
    participant Family as family.py
    participant Git as member git repository

    User->>Family: bump --to target
    Family->>Git: git fetch origin
    Git-->>Family: CommandFailed
    Family->>Git: git cat-file -t target
    Git-->>Family: commit
    Family->>Git: git for-each-ref --contains commit refs/remotes/origin/
    alt existing remote-tracking ref contains commit
        Git-->>Family: matching ref
        Family-->>User: fetch note, then allow bump
    else no existing remote-tracking ref contains commit
        Git-->>Family: no ref
        Family-->>User: fetch note and member-to-local-only
    end

Loading

Flow diagram for local-only bump target outcomes

flowchart TD
    A[Resolve --to target] --> B{Member holds a commit?}
    B -->|No| C[Refuse member-to-unknown]
    B -->|Yes| D{Remote-tracking branch reaches commit?}
    D -->|Yes| E[Allow bump or dry-run]
    D -->|No| F[Refuse member-to-local-only]
    F --> G[Push commit to a branch and retry]
    H[Tree, blob, or non-commit tag target] --> I[Refuse member-to-not-a-commit]

Loading

File-Level Changes

Change	Details	Files
Added remote-branch reachability validation for commits targeted by bump --to, including commits peeled from annotated tags.	Run git for-each-ref --contains against refs/remotes/origin/ after fetching and before checkout or writes. Raise member-to-local-only with push remediation when a locally held commit is reachable from no remote branch. Preserve member-to-unknown and member-to-not-a-commit classifications, and use stale-ref messaging when fetches fail. Apply identical validation to real and dry-run bump paths and document the new behavior.	scripts/family.py
Updated test fixtures so existing bump targets are pushed to an isolated member remote, avoiding unintended local-only refusals.	Add a helper that creates a private bare remote, points the member origin to it, and pushes test commits. Make mount and member commit helpers push by default, with an explicit opt-out for local-only scenarios.	tests/test_family.py tests/test_family_dry_run.py tests/test_family_add_excludes.py
Added focused coverage for local-only, annotated-tag, object-type, offline, dry-run, and successful-control scenarios.	Verify member-to-local-only refusal, unchanged holder state, matching real/dry-run diagnostics, and tag peeling details. Verify offline decisions use existing remote-tracking refs and distinguish stale-ref refusals from pinnable commits. Retain existing behavior for unknown objects and trees/blobs, and confirm pushed commits still pin successfully.	tests/test_family_bump_to_local_only.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#613	Refuse bump --to when the requested commit is held in the member mount but is not reachable from any branch of the member’s remote, using the member-to-local-only refusal before checkout or writes.	✅
#613	Apply the same reachability rule to commits named by annotated tags, while preserving the existing distinctions for unknown objects and non-commit objects.	✅
#613	When fetch fails, determine reachability from the mount’s existing remote-tracking refs: allow commits those refs contain and refuse commits they do not, with a stale-refs warning; keep dry-run behavior consistent with the real run.	✅

---

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.

[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

[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 23 hours and 1 minute by commenting @sourcery-ai review. Upgrade to get a review now.