[brettheap]

The family half of #923 U063 and #921 U088, and RV1052d's NIT-A. It finishes #923; #921 keeps its other sections.

What changed, and why

family.py init --dry-run said it "makes no folder, remote or repository". It makes and removes temporary folders, and its folder question is os.access's, which reads the mode bits and on Windows says yes for every folder. The scaffold's --dry-run help said so in #1052; the family's did not.

I probed the family's dry run first, under an audit hook on os.mkdir, os.rmdir, shutil.rmtree, tempfile.mkdtemp and subprocess.Popen (the real gh replaced by a stub that answers repo view as not found), for the GitHub path, with GIT_AUTHOR_* and GIT_COMMITTER_* set, and with --local-remote-dir:

• It makes and removes openreposhape-branch-* (git check-ref-format --branch main, asked of an empty --git-dir), and, only where a GIT_AUTHOR_* or GIT_COMMITTER_* variable is set and not empty, one openreposhape-ident-* each for the author and the committer (git var GIT_AUTHOR_IDENT, git var GIT_COMMITTER_IDENT). It makes no openreposhape-seed-*, which is the scaffold's.
• The folders it asks about are the family folder (or --work-dir), the holder in it, and --local-remote-dir; each is asked of os.access(W_OK | X_OK) on the nearest folder that exists (folder_in_the_way, target_in_the_way), and none is made, with no probe file.
• It creates no remote and pushes nothing: the only gh call is gh repo view (and the commit listing when the repository exists), and with --local-remote-dir no gh call at all. No git init, clone or push ran.

So:

• scripts/family.py:93 (the module docstring): "and makes no folder, remote or repository" is now "and creates no remote or repository". Two new paragraphs follow at :102-117. One says the dry run LEAVES NOTHING THAT STAYS, names the two temporary folders and when each is made, says a failed removal is not reported, and says its only gh calls read. The other says the write answer is the mode bits' and why a quota, a Windows ACL or a read-only drive on Windows can pass the dry run and be refused by the real one.
• scripts/family.py:10464-10480 (init --dry-run's help): "make no folder, remote or repository" is now the scaffold's sentence, adapted: "Whether each folder can be written in is asked of os.access, which reads the mode bits and on Windows says yes for every folder, so a quota, a Windows ACL or a read-only drive on Windows can pass here and be refused by the real run. It leaves nothing that stays: it makes and removes temporary folders, creates no remote or repository and pushes nothing". The one difference from the scaffold's words is "no remote or repository", which is what the family's old help claimed and is still true.
• docs/cli.md: regenerated with scripts/render-cli-reference.py; its family section is the only hunk (@@ -959,2 +959,8 @@), and --check says [ok] docs/cli.md is what the generator produces.
• tests/test_github_limits_init_check_org.py: test_init_dry_run_help_says_the_mode_bits_and_nothing_that_stays, the family's counterpart of the scaffold's test of that name. It sits beside test_init_help_says_each_bound_where_the_value_is_typed, the only existing test that runs family.py init --help; no family help test file existed for --dry-run. It pins the whole sentence in the --dry-run entry, and that "make no folder" and "its mode bits'" are absent.
• tests/test_scaffold_reuse_seeded_legs.py: RV1052d's NIT-A, test_the_note_a_re_run_prints_says_github_only_for_a_github_leg. It monkeypatches remote_is_empty (returning False) and _held_seed (returning (seed, None, ("seed/scaffold",))), calls _reusable_remotes(..., local=False, reuse_flag=True, ...) and reads the NOTE from capsys: it must end ", and on GitHub it may be the leg's default branch." It is parametrized with local=True too (local_remote_is_empty patched), where the NOTE ends "so that branch remains." and says no word of GitHub.

#923, item by item, on this branch

• U062, passed_values' docstring (setup-project.py:2694-2704): done in AGENTS.md, README.md, docs/handbook.html and setup-project.py: the taken-clone-path refusal names the --family folder, "nothing that stays" replaces "nothing is created", and passed_values says what argparse takes as a value (#921, #923) #1051; it says argparse takes -, -5, -1.5 and -x y as values.
• U063, --dry-run's help says the folder answer is the mode bits': the scaffold in scaffold-project.py: --dry-run's help says its answer about each folder is the mode bits' and that it leaves nothing that stays, a --reuse-empty-repo re-run that takes a seed found only on seed/scaffold names that branch as remaining, and the unused COMMIT_RE import is gone (#921, #923) #1052 (scaffold-project.py:368-383), the family here.
• U064, the six pyflakes warnings: the scaffold's in scaffold-project.py: --dry-run's help says its answer about each folder is the mode bits' and that it leaves nothing that stays, a --reuse-empty-repo re-run that takes a seed found only on seed/scaffold names that branch as remaining, and the unused COMMIT_RE import is gone (#921, #923) #1052, shape_materialize.py's and family.py's in family.py and shape_materialize.py: init asks the scaffold's own manifest questions of family.yaml, so init, the scaffold and adopt refuse a validator that exits or answers with something that is not text, and a manifest that is not a mapping, in the same words, and pyflakes finds nothing in either file (#925, #923) #1057. pyflakes 4.0.0 is silent on scaffold-project.py, scripts/shape_materialize.py, scripts/family.py and setup-project.py on this branch, and no test reads COMMIT_RE or recorded_gitlink as an attribute of either (tests/test_validate_family_without_git.py:87 and tests/test_validate_pins_without_git.py:164 read the validators').

Left out of scope

• The rest of AGENTS.md, README.md, the handbook, the release notes and scaffold-project.py: the --family refusal path, "nothing is created", three ruled bump limits and a seed/scaffold re-run are unsaid or slightly wrong #921: U033 and U088's documentation half landed in AGENTS.md, README.md, docs/handbook.html and setup-project.py: the taken-clone-path refusal names the --family folder, "nothing that stays" replaces "nothing is created", and passed_values says what argparse takes as a value (#921, #923) #1051, U088's scaffold half and U006's NOTE in scaffold-project.py: --dry-run's help says its answer about each folder is the mode bits' and that it leaves nothing that stays, a --reuse-empty-repo re-run that takes a seed found only on seed/scaffold names that branch as remaining, and the unused COMMIT_RE import is gone (#921, #923) #1052; U066, U068 and U071 (the three bump limits for the release notes) and U097, which needs a ruling, are not touched here.
• family.py's run-time line --dry-run: nothing was created. and its refusals' "nothing was created": the brief for this change was the docstring and the help only, and a refusal names a folder or remote it did not create, which is true.

Tests

Each file alone, under a stub gh (exit 97), GH_TOKEN=bogus, an empty GH_CONFIG_DIR and EMAIL=tests@openreposhape.invalid, with /usr/bin/python3 -m pytest -q -p no:cacheprovider -o tmp_path_retention_policy=failed:

• tests/test_cli_reference.py: 23 passed in 27.25s
• tests/test_github_limits_init_check_org.py: 96 passed in 25.12s
• tests/test_scaffold_reuse_seeded_legs.py: 84 passed in 45.07s
• tests/test_family_init_landing.py: 19 passed in 7.13s
• tests/test_family_refuse_up_front.py: 79 passed in 70.63s
• tests/test_agents_md_codes.py: 47 passed in 1.85s
• tests/test_update_add_codes_documented.py: 6 passed in 0.51s
• tests/test_repo_hygiene.py: 100 passed in 2.29s
• tests/test_no_auto_maintenance.py: 60 passed in 10.62s
• python3 -m pyflakes scripts/family.py: no output, exit 0
• scripts/render-cli-reference.py --check: exit 0

Mutants

• RV1052d's R2c, scaffold-project.py:751 print(_seed_branch_note(target, found_on, tracking, local)) changed to pass True for local: KILLED by test_the_note_a_re_run_prints_says_github_only_for_a_github_leg[github-leg] (1 failed, 18 passed). The mirror, False for local, is killed by [bare-repository-leg]. The file was restored and cmp-ed against its copy.
• The family --dry-run help put back to "make no folder, remote or repository": KILLED by test_init_dry_run_help_says_the_mode_bits_and_nothing_that_stays (1 failed).
• The help's "reads the mode bits" changed to "reads the permissions": KILLED by the same test, and by tests/test_cli_reference.py (5 failed).
• scripts/family.py restored after each and cmp-ed.

Merges

git merge-tree --write-tree of this head with origin/main (eee089cae): clean. The four open PRs, none of which touches these four files, each also clean: #1062 (01a8b7593), #1045 (3272d5334), #1031 (b83d9c022), #1025 (4c0c52d0c).

Review round

RV1063's review of 83af669dc was READY, with one SHOULD and three NITs; this round is one commit, d996ebf1e, pushed as a fast-forward.

• SHOULD-1, tests/test_scaffold_reuse_seeded_legs.py:414: the [bare-repository-leg] case expects the path as str(Path("/remotes/Atlas-spec.git")), because _reusable_remotes prints str(Path(url)), which is \remotes\Atlas-spec.git on Windows; the test's docstring says it runs on every platform.
• NIT-1, scripts/family.py:105-109: the module docstring says one openreposhape-ident-* folder for the author when GIT_AUTHOR_NAME, _EMAIL or _DATE is set and not empty, and one for the committer when a GIT_COMMITTER_ one is, as COMMIT_IDENTITY and its loop work, per role.
• NIT-2, scripts/shape_materialize.py:1621-1622: folder_in_the_way's docstring says os.access says yes for root and for any folder on Windows, "where the real mkdir can still be refused: an ACL, a quota", so it agrees with the help. A docstring only; it widens the file list by this one file.
• NIT-3 (the Sourcery block below), left as it is: lane 3 strips it or keeps it at un-draft.
• Tests, each file alone under the stub gh: test_scaffold_reuse_seeded_legs.py 84 passed; test_github_limits_init_check_org.py 96 passed; test_cli_reference.py 23 passed; test_no_auto_maintenance.py 60 passed; pyflakes on scripts/family.py and scripts/shape_materialize.py: no output.
• Merges, git merge-tree --write-tree of d996ebf1e: clean with origin/main (6476c1704, one commit ahead, none of these files; update the branch before landing) and clean with scripts/shape_materialize.py, family.py and adopt-project.py's check: a manifest the template's own reader makes no mapping of is told it is a defect in the copy of the standard, naming the template file, and manifest_invalid's docstring is true for the holder (#1059) #1064 (l3-1059-not-a-mapping-remedy, edc9fc719), which also edits shape_materialize.py, far from :1621.

Closes #923
Part of #921

Lane: openreposhape-3 (openRepoShape-3)

🤖 Generated with Claude Code

Summary by Sourcery

Clarify family dry-run semantics and guard the platform-specific seeded re-run note behavior with tests.

Enhancements:

• Clarify that family.py init --dry-run checks folder writability via os.access, may create and remove temporary validation folders, and leaves no persistent changes while creating no remote or repository.
• Document the dry-run behavior consistently in the family module documentation, CLI help, and generated CLI reference.
• Ensure seeded re-run notes mention GitHub's default-branch behavior only for GitHub-backed legs.

Documentation:

• Update the generated CLI reference with the clarified family dry-run behavior.

Tests:

• Add coverage for the family's dry-run help wording and the distinction between temporary folders and persistent changes.
• Add coverage ensuring seeded re-run notes include GitHub-specific wording only for GitHub legs.

[sourcery-ai]

Reviewer's Guide

The PR documents and tests the true side effects and limitations of family.py init --dry-run, updates the generated CLI reference, and adds regression coverage for correct GitHub-specific seed reuse messaging.

Sequence diagram for family init dry-run side effects

sequenceDiagram
    participant User
    participant FamilyInit
    participant OS
    participant Git
    participant GitHub

    User->>FamilyInit: cmd_init(--dry-run)
    FamilyInit->>OS: os.access(folder, W_OK | X_OK)
    OS-->>FamilyInit: writable mode-bit result
    FamilyInit->>Git: git check-ref-format --branch main
    Git-->>FamilyInit: branch validity
    FamilyInit->>OS: tempfile.mkdtemp(openreposhape-branch-*)
    FamilyInit->>OS: os.rmdir(temp_branch)
    opt GIT_AUTHOR_* or GIT_COMMITTER_* is set
        FamilyInit->>OS: tempfile.mkdtemp(openreposhape-ident-*)
        FamilyInit->>Git: git var GIT_AUTHOR_IDENT or GIT_COMMITTER_IDENT
        Git-->>FamilyInit: identity result
        FamilyInit->>OS: os.rmdir(temp_identity)
    end
    opt GitHub remote checks are needed
        FamilyInit->>GitHub: gh repo view
        GitHub-->>FamilyInit: repository status
    end
    FamilyInit-->>User: dry-run result with no lasting folder, remote, repository, or push

Loading

Flow diagram for seed branch reuse messaging

flowchart TD
    A[_seed_branch_note] --> B{local}
    B -->|true| C[NOTE ends: so that branch remains.]
    B -->|false| D[NOTE ends: and on GitHub it may be the leg's default branch.]

Loading

File-Level Changes

Change	Details	Files
Clarify that family init dry runs may create and remove temporary directories while performing mode-bit write checks, rather than creating no folders at all.	Update the module documentation to describe temporary branch and identity directories, read-only GitHub checks, and cleanup behavior. Revise init --dry-run help to explain os.access semantics, platform limitations, and that no persistent folder, remote, repository, or push remains. Regenerate the CLI reference with the updated help text. Add coverage pinning the help wording and rejecting the obsolete “make no folder” and inaccurate mode-bit phrasing.	scripts/family.py docs/cli.md tests/test_github_limits_init_check_org.py
Add regression coverage ensuring seeded-leg reuse emits a GitHub-specific branch note only for GitHub-backed legs.	Exercise _reusable_remotes for both GitHub and local-remote paths with a held seed. Verify the GitHub default-branch clause is present only for the GitHub case and that the local note omits GitHub references.	tests/test_scaffold_reuse_seeded_legs.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#923	Correct passed_values’ docstring so it describes how argparse handles values beginning with -.	✅
#923	Clarify in the scaffold’s and family’s --dry-run help that folder writability is determined using os.access and its mode-bit behavior, rather than a real write test.	✅
#923	Remove the six reported pyflakes warnings from the scaffold, shape_materialize.py, and family.py.	✅

Possibly linked issues

• AGENTS.md, README.md, the handbook, the release notes and scaffold-project.py: the --family refusal path, "nothing is created", three ruled bump limits and a seed/scaffold re-run are unsaid or slightly wrong #921: The PR changes family dry-run help to say it leaves nothing that stays and tests the seed/scaffold GitHub default-branch note.

---

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-20T16:17:14Z) RV1063, lane 3's independent opus review of #1063 at 83af669: READY (no MUST).

Probe of family.py init --dry-run (audit hook on mkdir/rmdir/rmtree/mkdtemp/write-opens/Popen, os.access wrapped; stub gh, GH_TOKEN=bogus, empty GH_CONFIG_DIR, GIT_SSH_COMMAND=false, per-case empty TMPDIR), 8 cases, all exit 0 with TMPDIR left empty:

• It makes and removes openreposhape-branch-* (git check-ref-format --branch main) every time, and openreposhape-ident-* only per role whose GIT_AUTHOR_/GIT_COMMITTER_ variable is set and not empty (both: two folders; GIT_AUTHOR_NAME alone: one; set but empty: none). No openreposhape-seed-*.
• The write question is os.access(W_OK|X_OK) alone, on the nearest existing folder of the family folder or --work-dir and of --local-remote-dir; no folder is made to ask.
• No git init, clone or push. gh calls: repo view only (not found), repo view plus api .../commits?per_page=1 (zero commits, --reuse-empty-repo), none with --local-remote-dir.

Help against #1052's scaffold help: the new sentence is the scaffold's word for word except "creates no remote or repository". That is right: the scaffold's dry run runs git init --bare in openreposhape-seed-* (only_commit), the family's runs no git init at all. The other two differences (the folder list, the one holder) predate this PR and are right for a family.

docs/cli.md: one hunk, in scripts/family.py init; render-cli-reference.py --check is ok at the head and on main+PR.
#923: U062 (setup-project.py:2694-2704), U063 (scaffold #1052, family here) and U064 (pyflakes 4.0.0 silent on the four files) are all done, so Closes #923 is right.
Tests at the head, one file at a time: test_github_limits_init_check_org 96 passed, test_scaffold_reuse_seeded_legs 84 passed, test_cli_reference 23 passed, test_no_auto_maintenance 60 passed.
Mutants: R2c (scaffold-project.py:751 passes True) KILLED by [github-leg] alone (1 failed, 83 passed); its mirror (False) KILLED (4 failed); family help without "or repository" KILLED by the new help test.
Merges: clean with origin/main 6476c17 (one commit ahead, touches none of these files; update-branch before landing), clean with l3-1059-not-a-mapping-remedy edc9fc7, and clean three-way.

SHOULD-1 tests/test_scaffold_reuse_seeded_legs.py:414: the [bare-repository-leg] case expects "/remotes/Atlas-spec.git", but _reusable_remotes prints str(Path(url)), which is "\remotes\Atlas-spec.git" on Windows, so the case fails there although its docstring (:398) says it runs on every platform. Fix: target = str(Path("/remotes/Atlas-spec.git")) if local else "o/Atlas-spec".
NIT-1 scripts/family.py:104-107: "one each for the author and the committer when a GIT_AUTHOR_* or GIT_COMMITTER_* variable is set" reads as both folders from either variable; it is one per role, for _NAME, _EMAIL or _DATE. Suggest: "one for the author when GIT_AUTHOR_NAME, _EMAIL or DATE is set and not empty, and one for the committer when a GIT_COMMITTER one is".
NIT-2 scripts/shape_materialize.py:1620-1621 (on main): "it says yes for root, and for any folder on Windows, as mkdir would" contradicts "a Windows ACL ... can pass here and be refused by the real run". Follow-up, or here if the file list widens.
NIT-3 PR body: lane 3's ending (Closes #923, Part of #921, Lane line, robot line) is right and closingIssuesReferences is [923], but the Sourcery bot appended a "Summary by Sourcery" block after the robot line (no closing keyword). Strip it at un-draft, or leave it, since the squash message is explicit.

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

[brettheap]

(lane openRepoShape-3, 2026-10-20T16:25:48Z) RV1063d (independent opus delta review of fix round 1, head d996ebf): READY.

• SHOULD-1 (tests/test_scaffold_reuse_seeded_legs.py:414): fixed. _reusable_remotes prints str(Path(url)) (scaffold-project.py:735, :751, :651), and the test now expects str(Path("/remotes/Atlas-spec.git")). With PureWindowsPath logic both are \remotes\Atlas-spec.git, and the old literal was not. An in-process probe that set the module's Path to PureWindowsPath printed "NOTE the seed in \remotes\Atlas-spec.git was found only on its branch seed/scaffold: ... so that branch remains.", which the fixed target matches. So the docstring's "runs on every platform" (:398) holds.
• NIT-1 (scripts/family.py:105-109): fixed and true per role. COMMIT_IDENTITY (:2667-2672) and the loop (:2738-2765) make one openreposhape-ident-* folder only for a role with GIT_*_NAME, _EMAIL or _DATE set and not empty.
• NIT-2 (scripts/shape_materialize.py:1621-1622): fixed. It now agrees with make_folder (:1707) and with the family docstring and help (family.py:112-117, docs/cli.md:352 and :960).
• NIT-3: left on purpose. closingIssuesReferences is [923], and the only closing line is "Closes setup-project.py, shape_materialize.py, scaffold-project.py and family.py: passed_values' docstring misstates argparse, --dry-run's help does not say its folder answer is the mode bits', and six pyflakes warnings #923".
• New: no MUST or SHOULD. One optional cosmetic NIT: shape_materialize.py:1622 was not reflowed and is a short line ("...an ACL, a quota). A"). No fix round needed.

Tests at d996ebf, one file at a time under a stub gh: test_scaffold_reuse_seeded_legs.py 84 passed; test_cli_reference.py 23 passed.
Merges: git merge-tree --write-tree is clean with origin/main 6476c17 (tree 0643869) and with #1064 at edc9fc7 (tree e1496b9).

Lane: openreposhape-3 (openRepoShape-3)

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