[brettheap]

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

Closes #784.

Stacked on #772; lands after it. Lands after the v1.1.0 tag.

What changed, and why

A dangling symbolic link at ../<Project> read as an empty slot, because exists follows a link. Measured with #772's head 1d149933 and a link to nothing at ../IRRS in the two-member holder. Every claim in the issue held:

• make siblings --dry-run: [IRRS] would clone ... -> .../IRRS (state would clone), from siblings.py: a file, or a folder make siblings cannot list or enter, at ../<Project> is NOT A CLONE, reported and left as it is, so the run no longer ends in a traceback at iterdir before the members after it are placed, and make park no longer ends in one over a folder it cannot enter (#735) #772's place called on its own.
• The real make siblings: the layout row was sibling IRRS CLONE FAILED -. git cannot clone into a path that is a link to nothing: fatal: could not create work tree dir 'slot': File exists, exit 128 (measured).
• The doctor's members row: sibling was 'absent', so the row said make siblings places the member there.
• make park and make resume: SKIPPED no clone, as siblings.py: a file, or a folder make siblings cannot list or enter, at ../<Project> is NOT A CLONE, reported and left as it is, so the run no longer ends in a traceback at iterdir before the members after it are placed, and make park no longer ends in one over a folder it cannot enter (#735) #772 left them.

templates/family-root/scripts/siblings.py:

• not_a_clone (:471) now answers "is a link to nothing", with link as the kind of thing (:496). The docstring is at :487.
• place therefore reports the slot as NOT A CLONE, in the finding the other NOT A CLONE slots get: "<who>: <at> is a link to nothing, so this command will not write into it. Move it aside or name the link something else; nothing here overwrites a link somebody made."
• The link is left as it is, and the dry run says NOT A CLONE, not would clone.
• dispatch (--make) is unchanged: holds_git (:460) answers "no" for a link to nothing (:776), so make park and make resume keep SKIPPED no clone.

shape-doctor.py:

• unclonable (:7974) answers dangling for a link to nothing (:7996), so sibling_slot (:8004) says not-a-clone, and the doctor and make siblings agree again.
• The row's sentence comes from UNREADABLE_BESIDE (:8174, "dangling": "is a link to nothing" at :8176). It says what is there and nothing of what make siblings does with it. That holds for every holder, because one whose pinned siblings.py predates this change still ends CLONE FAILED on the link.
• The comments on sibling_slot, UNREADABLE_BESIDE and beside_sentence (:8179) say so.

What is tested

• tests/test_shape_doctor.py:
  • UNREADABLE_SLOTS (:4071) gains a-link-to-nothing (:4077), skipped on Windows, where a symbolic link needs a privilege (LINKS_HOLD, :4065). holder_with_slot builds it at :4103.
  • The row test (:4131) asserts not-a-clone, UNREADABLE_SAYS["dangling"] (:4016), no word of make siblings, ok and COMPLIANT.
  • The agreement test (:4164) asserts that the holder's own siblings.py --dry-run prints NOT A CLONE for it.
• tests/test_family.py:

  • test_siblings_reports_a_slot_it_cannot_read_as_not_a_clone (:1976) gains a-link-to-nothing (:1940). On a real run it asserts:

    • exit 1;
    • sibling IRRS NOT A CLONE -;
    • the finding, word for word;
    • IRSS still placed;
    • the slot unchanged.

    "Unchanged" is checked with as_it_is (:1944): a link and where it leads, a file and what it says, or a folder's files. It replaces siblings.py: a file, or a folder make siblings cannot list or enter, at ../<Project> is NOT A CLONE, reported and left as it is, so the run no longer ends in a traceback at iterdir before the members after it are placed, and make park no longer ends in one over a folder it cannot enter (#735) #772's two separate checks.

  • test_a_make_verb_skips_a_slot_with_no_clone (:2016, siblings.py: a file, or a folder make siblings cannot list or enter, at ../<Project> is NOT A CLONE, reported and left as it is, so the run no longer ends in a traceback at iterdir before the members after it are placed, and make park no longer ends in one over a folder it cannot enter (#735) #772's mode-000 test, now parametrized) asserts SKIPPED no clone for the link too.

• Red first: with siblings.py: a file, or a folder make siblings cannot list or enter, at ../<Project> is NOT A CLONE, reported and left as it is, so the run no longer ends in a traceback at iterdir before the members after it are placed, and make park no longer ends in one over a folder it cannot enter (#735) #772's head's siblings.py and shape-doctor.py, the three new NOT A CLONE cases fail (3 failed, 31 passed). The real run's layout row is sibling IRRS CLONE FAILED -, and the doctor gives 'absent' == 'not-a-clone' false. The --make case passes there too, because SKIPPED no clone was already the behaviour.

Commands, with a stub gh (exit 97) first on PATH, GH_TOKEN=bogus and an empty GH_CONFIG_DIR, at e966a684, on #772's head 1d149933 (main e3137010):

/usr/bin/python3 -m pytest -q -rsx -p no:cacheprovider --basetemp=<scratch>/bt-a -o tmp_path_retention_policy=failed tests/test_family.py tests/test_family_siblings_placement.py tests/test_siblings_family_name.py tests/test_family_makefile_siblings.py tests/test_park_resume_targets.py tests/test_windows_paths.py tests/test_family_printed_quoting.py tests/test_update_shape_add.py tests/test_update_shape_kept_helper.py tests/test_repo_hygiene.py tests/test_cli_reference.py
723 passed in 168.79s (0:02:48)

/usr/bin/python3 -m pytest -q -rsx -p no:cacheprovider --basetemp=<scratch>/bt-b -o tmp_path_retention_policy=failed tests/test_shape_doctor.py tests/test_doctor_members_spelled.py tests/test_doctor_gitmodules_not_utf8.py
473 passed, 3 skipped in 361.88s (0:06:01)   (skips: tests/test_shape_doctor.py:10436, the PowerShell line, Windows host only)

/usr/bin/python3 -m pytest -q -rsx -p no:cacheprovider --basetemp=<scratch>/bt-c -o tmp_path_retention_policy=failed tests/test_shape_doctor.py -k "sibling or not_a_clone or slot"
42 passed, 402 deselected in 25.00s

Pinned shape copies

templates/family-root/scripts/siblings.py is a family-root copy carried by digest. A holder pinned before this change shows an upstream-changed row for it until update-shape.py brings it forward. No other pinned copy is touched.

Notes

• The Windows skip is LINKS_HOLD, not conftest.WINDOWS_SKIP. It skips on Windows alike, but its reason is the true one, "a symbolic link needs a privilege on Windows". WINDOWS_SKIP's reason is a POSIX shell, which these tests do not need.
• No docs change: no doc describes these slots or quotes the NOT A CLONE finding, and siblings.py's --help is unchanged.

🤖 Generated with Claude Code

Summary by Sourcery

Handle dangling sibling links consistently as non-cloneable slots across sibling placement and shape diagnostics.

New Features:

• Treat dangling symbolic links as non-cloneable sibling slots and report them without modifying the link.

Bug Fixes:

• Keep dry-run sibling placement results consistent with real runs by preventing clone attempts into dangling links.
• Classify dangling links consistently in the shape doctor's member reports instead of marking them absent.

Tests:

• Add coverage for preserving dangling links, reporting them as NOT A CLONE, and skipping them for make operations.

[sourcery-ai]

Reviewer's Guide

The PR closes the gap where Path.exists() treated dangling ../<Project> links as empty slots: sibling placement and shape-doctor inspection now classify them consistently as NOT A CLONE/not-a-clone, report the link without overwriting it, and retain existing no-clone behavior for make verbs. Expanded tests verify exact diagnostics, link preservation, cross-tool agreement, and Windows-specific symlink handling.

Sequence diagram for dangling-link classification

sequenceDiagram
    participant User
    participant Siblings as siblings.py
    participant Doctor as shape-doctor.py
    participant Slot as ProjectSlot

    User->>Siblings: not_a_clone(ProjectSlot)
    Siblings->>Slot: exists()
    Slot-->>Siblings: false
    Siblings->>Slot: is_symlink()
    Slot-->>Siblings: true
    Siblings-->>User: NOT A CLONE
    Siblings-->>User: leave link unchanged

    User->>Doctor: sibling_slot(ProjectSlot)
    Doctor->>Slot: exists()
    Slot-->>Doctor: false
    Doctor->>Slot: is_symlink()
    Slot-->>Doctor: true
    Doctor->>Doctor: unclonable(ProjectSlot)
    Doctor->>Doctor: beside_sentence(ProjectSlot)
    Doctor-->>User: not-a-clone, is a link to nothing

Loading

File-Level Changes

Change	Details	Files
Treat dangling symbolic links as non-cloneable slots instead of absent paths.	Detect links whose targets do not exist in sibling placement and doctor inspection. Report NOT A CLONE and leave the link untouched during dry runs and real runs. Keep --make operations skipping the slot as having no clone. Use consistent doctor wording and not-a-clone state for dangling links.	templates/family-root/scripts/siblings.py shape-doctor.py
Add coverage for dangling-link behavior and preserve existing unreadable-slot coverage.	Parametrize family placement tests to create files, locked folders, and dangling links. Assert failure status, exact diagnostic output, subsequent member placement, and unchanged slot contents. Verify park/resume skip dangling links and doctor output agrees with siblings dry-run output. Skip symlink cases on Windows with a symlink-specific reason.	tests/test_family.py tests/test_shape_doctor.py

Possibly linked issues

• siblings.py (make siblings) and the doctor: a dangling symlink at ../<Project> reads as an empty slot, so the dry run says "would clone" and the doctor says absent, while the real run ends CLONE FAILED #784: The PR implements the issue’s requested detection, reporting, dry-run behavior, and tests for dangling sibling symlinks.

---

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-3, 2026-10-17T05:16:27Z) Independent review of #788 by RV-d (opus), on head e966a684 (stacked on #772): READY. No MUST and no SHOULD; two optional NITs. It lands only after the v1.1.0 tag, after #772.

Each link at ../IRRS, on a real two-member holder (--dry-run, make siblings, make park, make resume, then the doctor):

link	#772's head: dry / real / doctor	#788: dry / real / doctor
absolute, to nothing	would clone / CLONE FAILED / absent	NOT A CLONE / NOT A CLONE / not-a-clone, "is a link to nothing"
relative, to nothing	same	same
a link to a link to nothing	same	same
to a missing folder inside an existing one	same	same
a link loop	same	same
a relative link to a folder with files (control)	NOT A CLONE	unchanged
an absolute link to an empty folder (control)	cloned through the link	unchanged
into a folder this user cannot enter	"a folder that cannot be listed"	unchanged (N1)

• make park and make resume say SKIPPED no clone for every dangling variant.
• IRSS is always placed after it.
• The link chain is untouched.
• The doctor agrees with make siblings in every row.

Answers:

• The wording matches siblings.py: a file, or a folder make siblings cannot list or enter, at ../<Project> is NOT A CLONE, reported and left as it is, so the run no longer ends in a traceback at iterdir before the members after it are placed, and make park no longer ends in one over a folder it cannot enter (#735) #772's other slots. The doctor's sentence claims nothing about make siblings, so it stays true for a holder pinned before this change.
• The body names the pinned family-root copy.
• LINKS_HOLD, not WINDOWS_SKIP, is right. WINDOWS_SKIP's reason is a POSIX shell, and tests/test_adopt_attributes_eol_block.py:65 and tests/test_adopt_empty_symlinks.py:56 define their own symlink skip the same way.

NITs (optional):

• N1 (siblings.py:471, shape-doctor.py:7974): a link into a folder this user cannot enter is worded as a folder ("cannot be listed", "name the directory something else"). Both tools agree, and it is siblings.py: a file, or a folder make siblings cannot list or enter, at ../<Project> is NOT A CLONE, reported and left as it is, so the run no longer ends in a traceback at iterdir before the members after it are placed, and make park no longer ends in one over a folder it cannot enter (#735) #772's wording. Check target.is_symlink() first in the OSError branch.
• N2: is_symlink() is False for a Windows junction, so a dangling junction still reads as an empty slot. Untestable here. As a follow-up, also check os.path.isjunction, as family_link does.

Mutants: all 5 are killed by the four a-link-to-nothing tests:

• not_a_clone ignores is_symlink;
• unclonable treats a dangling link as empty;
• the dry run says "would clone";
• the doctor loses its "dangling" wording;
• a link gets the file wording.

Tests:

• five files: 271 passed;
• tests/test_shape_doctor.py -k (siblings rows): 43 passed;
• the link probe: 8 passed on both heads.

Merges: clean with bf1f099b, every other open lane-3 PR, and lane 4's #690 tip.

Lane: openreposhape-3 (openRepoShape-3)

[brettheap]

(lane openRepoShape-3, 2026-10-18T00:09:07Z) #788 is restacked after #772's squash (112eeed), as bec71bb5, by lane 3's three-merge recipe (writer R788, sonnet-xhigh):

1. f204abe1 merges siblings.py: a file, or a folder make siblings cannot list or enter, at ../<Project> is NOT A CLONE, reported and left as it is, so the run no longer ends in a traceback at iterdir before the members after it are placed, and make park no longer ends in one over a folder it cannot enter (#735) #772's final head bcb8e54a. It is clean.
2. 5f7ea9b3 merges the squash 112eeed2, taking ours only for siblings.py: a file, or a folder make siblings cannot list or enter, at ../<Project> is NOT A CLONE, reported and left as it is, so the run no longer ends in a traceback at iterdir before the members after it are placed, and make park no longer ends in one over a folder it cannot enter (#735) #772's four files, which conflicted as expected. git diff bcb8e54a 112eeed2 is empty on them, and this merge changed none of them.
3. bec71bb5 merges main e62b5e17. It is clean.

• git diff --name-only origin/main bec71bb5 lists only siblings.py and shape-doctor.py: a link to nothing at ../<Project> is NOT A CLONE, reported and left as it is, so the dry run no longer says would clone where the real run ends CLONE FAILED, and the doctor's members row no longer calls the slot absent (#784) #788's four files. Its -U0 changed lines equal the reviewed delta 1d149933..e966a684: 173 lines on each side, +120/-53.
• Tests on bec71bb5, under a stub gh: the nine family and siblings files of siblings.py and shape-doctor.py: a link to nothing at ../<Project> is NOT A CLONE, reported and left as it is, so the dry run no longer says would clone where the real run ends CLONE FAILED, and the doctor's members row no longer calls the slot absent (#784) #788's gate set, 607 passed; tests/test_shape_doctor.py, 441 passed, 3 skipped.
• Main has since moved to bee84d5 (scripts/shape_materialize.py and adopt-project.py: a --pin-source that is no clone's top level is refused pin-source-not-a-clone, and check finds a recorded one before a partial clone's NOTE, so a folder inside a clone no longer records the digest of part of its tree, or of nothing (#800) #842), which shares no file with siblings.py and shape-doctor.py: a link to nothing at ../<Project> is NOT A CLONE, reported and left as it is, so the dry run no longer says would clone where the real run ends CLONE FAILED, and the doctor's members row no longer calls the slot absent (#784) #788. The squash tree over it is 1cddc5a9.
• siblings.py and shape-doctor.py: a link to nothing at ../<Project> is NOT A CLONE, reported and left as it is, so the dry run no longer says would clone where the real run ends CLONE FAILED, and the doctor's members row no longer calls the slot absent (#784) #788 lands at a lane-3 turn by fast refresh, once its CI on bec71bb5 is green. siblings.py and shape-doctor.py: a Windows junction to nothing at ../<Project> is NOT A CLONE, as a link to nothing is, so the dry run no longer says would clone and the doctor's members row no longer calls the slot absent (#793) #794 stays stacked on this branch, and its diff is unchanged.

Lane: openreposhape-3 (openRepoShape-3)

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