[brettheap]

Lane: openreposhape-3 (openRepoShape-3)
Claim: #405 (comment)

What

family.py bump now asks what --to names in the member's objects. It asks after the fetch, before the dry run leaves and before the real run checks the member out (_checked_to_names_a_commit, called from cmd_bump):

• A commit's id goes on exactly as before. An id the member does not hold also goes on to git's own failure, exit 2, as before.
• An annotated tag of a commit is refused as member-to-not-a-commit, exit 2. That includes a tag of a tag, since ^{} peels through both. The refusal names the commit the tag peels to and the re-run --to <that commit>.
• A tree, a blob, or an annotated tag of either is refused as member-to-not-a-commit, naming what it is.
• The dry run refuses the same way. bump --dry-run prints the same two lines, exit 2. Both runs leave the holder's HEAD, index, status, family.yaml, work tree and object store as they were, and the member's checkout too.
• It is asked of what the fetch brought. A release tag pushed to the member's remote reaches the mount only through bump's own fetch. A check asked before the fetch would find nothing and let the tag through to the checkout, so the order is held by a test (fix round 1, below).

No refusal code is added or renamed. No --help text, README or AGENTS.md line changes. add --at still peels (#236), unchanged.

Peel or refuse: refuse, matching bump-leg.py

• bump-leg.py refuses the same input. Measured on main dd8d0ea: bump-leg.py --to <annotated tag of a spec-leg commit> exits 2 with bump-leg-validators-red. Its own validate-pins.py reports pin-gitlink-mismatch: the gitlink is the peeled commit and the pin is the tag. Every byte is rolled back, and --to the peeled commit then lands. So the other tool that writes a pin from --to refuses a tag's id, and family.py bump now does too. It refuses by name and before anything moves, not through a gate after the rewrite.
• The precedent text says a pin is a commit. member-to-not-a-commit's remediation already says "a pin is a commit or it is nothing". AGENTS.md's leg section spells the flag --to <40 hex> and says "A bump nobody read is a pin nobody chose". Peeling would put a commit nobody typed on the old -> new line the person reads. Refusing keeps the choice theirs and costs one re-run, with the commit the refusal prints.
• add --at peels for a different reason. add's row was always read back from the mount's checkout, so peeling there kept what add already pinned (family.py: add asks every refusal of the holder and of a throwaway clone of the member before it mounts anything, and unwinds and names whatever fails after the mount, so a refused add (a leg, a short or unknown --at, an empty member) no longer leaves a staged gitlink and .gitmodules section that the next add commits under its own title (#203) #236). bump never pinned the commit for a tag's id; it wrote the tag. There is no behaviour of bump's to keep.
• The issue suggested member-at-unknown for a tag of a tree or a blob. That is add's code for an --at the member does not reach. bump has one --to code, and this input is exactly "not a commit", so it gets member-to-not-a-commit and no new code.

Why

Re-measured with the issue's probe: local bare remotes, a throwaway global git config, GIT_ALLOW_PROTOCOL=file, a gh stub that exits 97 first on PATH, GH_TOKEN=bogus and an empty GH_CONFIG_DIR. Main is dd8d0ea; scripts/family.py is the same bytes at today's main decff87. Head is 6cc1d33; scripts/family.py is the same bytes at 3c8e452, the current head, which adds only a test. Ids differ between the two runs because a tag's tagger time does.

family.py bump --to …	main dd8d0ea	head 6cc1d33
annotated tag of a commit, --dry-run	exit 0. Prints commit 563e182ec759 -> 967a20cd1fb2 (the tag) and gitlink members/Atlas 563e182ec759 -> 6ee6110b9567 (the commit)	exit 2. REFUSED member-to-not-a-commit: --to f894f193… is an annotated tag in testorg/Atlas, not a commit; the commit it names is 4ee1df80… Holder unchanged
the same, real run	exit 0, committed c377f73f73cc. Row pin.commit = 967a20cd… (the tag), HEAD's gitlink = 6ee6110b…. validate-family.py exit 1: FINDING member-gitlink-mismatch	exit 2, the same two lines. Holder unchanged. validate-family.py exit 0, family ok
then --to the commit the tag names	exit 0 (the repair); validate-family.py exit 0	exit 0; validate-family.py exit 0
annotated tag of an annotated tag	dry run exit 0 with the same split; real run exit 0, commits	exit 2 in both runs, naming the commit (4ee1df80…)
a tree's id, a blob's id	exit 2 in both runs, worded differently: the dry run says REFUSED resolving 94e92b9846ef in members/Atlas, where a real bump checks it out, the real run says REFUSED checking members/Atlas out at 94e92b9846ef	exit 2 in both runs, the same two lines: … names a tree in testorg/Atlas, not a commit (or a blob)
annotated tag of a tree or a blob	as for a tree or a blob	exit 2 in both runs: … is an annotated tag of a tree in testorg/Atlas, not a commit (or of a blob)
bump-leg.py --to <tag of a spec commit> (this PR leaves it unchanged)	--dry-run exit 0 (commit 1a3d5f6737f6 -> 98bf2b546aaf); real run exit 2 bump-leg-validators-red, rolled back	unchanged

What the issue got right, re-checked on dd8d0ea: every claim held. These were the tag's id in pin.commit, the peeled commit in the gitlink, validate-family.py exit 1, and the dry run's split commit/gitlink lines. bump-leg.py's exit 2 bump-leg-validators-red held too. Only the line numbers moved: cmd_bump is at :2482 on dd8d0ea, not :2233.

Tests

• New: tests/test_family_bump_to_a_tag.py, 7 tests.
  • test_bump_to_an_annotated_tag_is_refused_naming_the_commit_it_tags covers a tag of a commit and a tag of a tag. Both runs give exit 2 and the same two lines, word for word, with nothing moved (test_family_dry_run.py's byte snapshot). Then the re-run the refusal names pins that commit in the row and the gitlink, and validate-family.py exits 0.
  • test_bump_to_a_tree_a_blob_or_a_tag_of_one_is_refused_by_name covers a tree, a blob, a tag of a tree and a tag of a blob.
  • test_a_release_tag_only_the_fetch_brings_is_refused_after_the_fetch (fix round 1, 3c8e452) is the issue's own flow.
    • A private bare copy of the member's remote gets a new commit and an annotated tag, pushed. The mount's origin points at that copy, and as a premise neither object is in the mount.
    • The real run goes first, so no dry run's fetch hands it the tag. It refuses, naming the new commit, with the holder unchanged, and afterwards the mount holds the tag.
    • The dry run then prints the same two lines. --to the named commit pins it, and validate-family.py exits 0.
  • Every tag is made in the test's own copy of the member's mount. The fixture's remotes are never written to.
• The new tests fail on main and pass on head.
  • On main dd8d0ea, the first six: 6 failed in 9.31s. The tag cases fail with member HEAD changed. The tree and blob cases fail because the dry run's and the real run's stderr differ.
  • On main 75052cb (same scripts/family.py), all seven: 7 failed in 10.69s.
  • On head 3c8e452: 7 passed.
• Bite checks, run on scratch copies of family.py.
  • The check moved under --dry-run only: 6 failed.
  • kind == "tag" let through: 4 failed, 2 passed. The tree and blob cases still pass, as they should.
  • The check moved ABOVE the fetch (the review's mutant): 1 failed, 6 passed in 12.06s. The failing test is the new after-the-fetch one: the real run moved the member and committed (member HEAD changed).
• Targeted set on 3c8e452: 342 passed in 327.00s (on 6cc1d33: 341 passed in 259.48s). Files: test_family_bump_to_a_tag.py, test_family.py, test_family_dry_run.py, test_family_member_path.py, test_family_add_excludes.py, test_family_add_member_id.py, test_family_add_refusals.py, test_family_member_name.py, test_validate_family_duplicates.py.
• Guards on 3c8e452: 224 passed, 1 skipped in 23.85s (on 6cc1d33: 224 passed, 1 skipped in 21.87s). Files: test_repo_hygiene.py, test_cli_reference.py, test_agents_md_codes.py, test_git_output_decoding.py, test_stdout_encoding.py. The one skip is existing, test_stdout_encoding.py:286 ("the default this is about is Windows' own").
• Composed with family.py: bump and remove put the holder back when a hook, a lock or git refuses them after they write, and say what they put back or what is left with the commands that put it back; they ask first what their dry runs ask first; and remove refuses a held index.lock before it unmounts and a .gitmodules that gives the member's path to two submodules, of which git rm took out one (#365, #360) #416. HEAD 3c8e452 merged with fix/family-bump-remove-rollback 39e27ff. test_family_bump_to_a_tag.py, test_family_bump_remove_rollback.py and test_family_dry_run.py gave 97 passed in 98.22s.
• No OS skips. No new test is skipped on any OS. The tests make annotated tags, trees and blobs with plain git and compare text with no paths in it beyond members/IRRS.

Composes with

Trial merges (git merge-tree --write-tree) of HEAD 3c8e452 against every open branch that touches scripts/family.py. Main 75052cb also merges clean:

branch	PR	result
fix/family-bump-remove-rollback 39e27ff	#416	CLEAN. The merged cmd_bump asks this check before if args.dry_run:, then #416's _checked_bump_target and its PinRollback; the composed tests pass (above)
fix/trailer-non-ascii-old-git d079893	#376	CLEAN
fix/ruleset-hint-tracking-branch 741cbf2	#373	CLEAN
fix/family-init-values abb27e6	#397	CLEAN
fix/scaffold-tracking-branch-ref-format 16073e2 (local ref 6fdbe3d)	#355	CLEAN (both)
fix/template-quoted-placeholders 12715cf (local ref 4d64794)	#395	CLEAN (both)

The test file is new, so no branch touches it. Branches already merged were skipped.

Left out

• bump-leg.py refuses a tag's id only through its validators, after the rewrite (rolled back, exit 2); it does not name the tag before anything moves. Its --dry-run previews the tag's id as the new commit and exits 0, so the dry run does not say what the real run does. That is a follow-up for that tool.
• add --at keeps peeling a tag's id to its commit (family.py: add asks every refusal of the holder and of a throwaway clone of the member before it mounts anything, and unwinds and names whatever fails after the mount, so a refused add (a leg, a short or unknown --at, an empty member) no longer leaves a staged gitlink and .gitmodules section that the next add commits under its own title (#203) #236), while bump now refuses one. Its wording also differs: add says a tag of a tree "names a tree". Making it refuse would break an input that works today, so the coordinator is filing a separate issue for that decision.

Closes #405

🤖 Generated with Claude Code

Summary by Sourcery

Reject non-commit --to targets before checkout so family bumps cannot create invalid pins.

Bug Fixes:

• Reject family.py bump --to values that resolve to annotated tags, trees, or blobs instead of commits, preventing invalid member pin and gitlink mismatches.
• Apply the validation consistently to regular and dry-run bumps after fetching newly available objects.

Enhancements:

• Provide actionable refusal messages that identify the object type and, for commit tags, the commit to use instead.

Tests:

• Add coverage for annotated tags, nested tags, trees, blobs, tag-of-tree/blob inputs, dry-run parity, rollback behavior, and tags introduced by the bump fetch.

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

[brettheap]

(lane openRepoShape-3, 2026-10-12T19:53:08Z) @codex review

[sourcery-ai]

Reviewer's Guide

The PR adds preflight object-type validation for family.py bump --to, preventing annotated tags, trees, and blobs from being recorded as commit pins or producing gitlink mismatches. It applies the same refusal behavior to dry runs and real runs, preserves existing handling for commits and missing objects, and adds comprehensive state-preserving regression tests.

Sequence diagram for preflight validation of family bump targets

sequenceDiagram
    participant User
    participant Family as family.py
    participant Member as Member repository
    participant Holder as Holder repository

    User->>Family: bump --to commit
    Family->>Member: fetch
    Family->>Member: git cat-file -t commit
    alt target is a commit
        Family->>Member: checkout target
        Family->>Holder: update pin and gitlink
    else target is tag, tree, or blob
        Family->>Member: git rev-parse --verify target^{}
        Family->>Member: git cat-file -t peeled target
        Family-->>User: Refusal member-to-not-a-commit
        Family-->>User: remediation with commit to rerun
    end

Loading

Flow diagram for safe dry-run and real-run bump validation

flowchart TD
    A[family.py bump --to target] --> B[Fetch member objects]
    B --> C{_checked_to_names_a_commit}
    C -->|commit| D{--dry-run}
    C -->|tag, tree, or blob| E[Refuse member-to-not-a-commit]
    E --> F[Holder and member remain unchanged]
    D -->|yes| G[Print bump preview]
    D -->|no| H[Checkout commit and update pin/gitlink]
    G --> I[Exit 0]
    H --> J[Validate family]
    I --> K[No repository changes]

Loading

File-Level Changes

Change	Details	Files
Validate the object type named by family.py bump --to before any checkout or dry-run processing, refusing non-commit objects consistently.	Resolve the requested object in the member repository after fetch. Accept commit IDs unchanged while preserving Git’s behavior for missing objects. Reject annotated tags, including nested tags, with the peeled commit and rerun command. Reject trees, blobs, and annotated tags of either with descriptive member-to-not-a-commit refusals. Run the validation before both dry-run and real bump paths so holder and member state remain unchanged.	scripts/family.py
Add regression coverage for tag, tree, and blob targets across dry-run and real bump modes.	Test annotated tags of commits and tags of tags, including exact refusal output and successful rerun using the named commit. Test trees, blobs, and annotated tags of each, verifying object-specific diagnostics. Verify both modes return exit 2, produce identical refusals, and leave repository state untouched. Verify fixtures create tags only in the member mount and validate the repaired commit pin.	tests/test_family_bump_to_a_tag.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#405	Make family.py bump --to handle annotated tag object IDs without writing a tag ID into pin.commit while the gitlink points to the peeled commit; it may refuse the tag or pin its target commit.	✅
#405	Ensure bump --dry-run gives the same tag-related outcome as a real bump, and refuse non-commit targets such as trees, blobs, and tags of those objects before changing repository state.	✅
#405	Apply the same --to tag handling decision to bump-leg.py, so its real and dry-run behavior is consistent.	❌	The PR explicitly leaves bump-leg.py unchanged; its dry run can still report success with a tag ID, while the real run relies on validators to refuse and roll back.

Possibly linked issues

• family.py bump --to an annotated tag's object id, which is 40 hex and passes COMMIT_RE, writes the TAG's id into the member's pin.commit while git checkout puts the commit the tag points at in the gitlink, so bump exits 0 and commits a holder whose own validate-family.py reports member-gitlink-mismatch, exit 1, where add --at pins the commit the same tag names #405: The PR directly fixes the reported mismatch by refusing annotated-tag --to IDs before changes, in both real and dry runs.

---

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]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[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

[brettheap]

(lane openRepoShape-3, 2026-10-13T00:36Z) @codex review

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.