[brettheap]

Lane: openreposhape-2 (openRepoShape-2)
Claim: #537 (comment)

What was wrong

Both dry runs printed the plan and exited 0 before the one question their real runs ask of the remotes:

• family.py init --dry-run: against a holder repository that already existed, the dry run exited 0. The real run then refused family-remote-exists, after _prepare_landing_dir had already made <into>/<Family>/.
• scaffold-project.py --dry-run: the dry run never asked whether the three repositories existed. setup-project.py's plan, step (5), is that dry run, so scaffold-remote-exists came only from step (6), after the person typed yes.

What changed

• init --dry-run asks _checked_reuse, the question the real init asks before it creates the holder. It asks after the plan and refuses family-remote-exists in the real run's words. With --reuse-empty-repo and an empty holder, it prints reuse <target> (zero commits).

• scaffold-project.py --dry-run asks _reusable_remotes, the real run's question about all three repositories, the scaffold-project.py, family.py init: after a ruleset refuses the first push, neither exit RULESET_HINT offers can finish: the pull request has no base in the repository gh repo create left empty, and the scaffold's re-run is refused scaffold-remote-exists for its own two empty legs, so a ruleset-protected organisation cannot seed a new project; --reuse-empty-repo is to reuse empty legs, and the hint is to offer only that re-run #462 seed rule included. It refuses scaffold-remote-exists in the real run's words, and prints a reuse ... line for each remote the real run would reuse. So setup-project.py now refuses an existing remote at the plan, before it asks for the yes.

• There is no second check. Each dry run calls the real run's own function, so the two cannot disagree. The dry run only reads:

  • gh repo view and a commit listing, or the bare repositories with --local-remote-dir;
  • for a leg that is not empty, the one commit it holds, fetched into a temporary directory that is then deleted.

  It creates no remote, folder or work tree, and pushes nothing.

• No gh on PATH is now gh-not-found, in dry and real runs alike. A dry run used to need no gh. Now the scaffold's two reads of GitHub, remote_is_empty and remote_visibility, and the family's _remote_is_empty refuse gh-not-found, in the words pin_digest_from_gh uses, where they used to raise a FileNotFoundError traceback.

  • remote_visibility is the one a first version missed. With --reuse-empty-repo, _leg_visibility reads the root's visibility before either _reusable_remotes call asks whether the repositories exist, so the scaffold with that flag still gave a traceback in both runs until the visibility read refused too.
  • The scaffold's two reads share one refusal, _gh_not_found, so their words cannot drift apart.

• --help for both --dry-run flags says what they ask, and docs/cli.md is regenerated (render-cli-reference.py --check passes).

• The real-run order in family.py init is unchanged: only the dry-run path was touched.

Tests

New: tests/test_dry_run_asks_remotes.py, 28 tests.

• Family, against bare repositories:
  • a live holder, with and without the flag;
  • an empty holder without the flag, which names the flag;
  • an empty holder with the flag, which is reused;
  • dry and real runs give byte-identical refusals, for a live holder and an empty one.
• Scaffold, against bare repositories:
  • a leg with commits, with and without the flag;
  • a root with commits, which is sent to adopt-project.py;
  • an empty root without the flag, which names the flag;
  • three empty repositories reused;
  • the scaffold-project.py, family.py init: after a ruleset refuses the first push, neither exit RULESET_HINT offers can finish: the pull request has no base in the repository gh repo create left empty, and the scaffold's re-run is refused scaffold-remote-exists for its own two empty legs, so a ruleset-protected organisation cannot seed a new project; --reuse-empty-repo is to reuse empty legs, and the hint is to offer only that re-run #462 seed reused, with every ref unchanged and the temporary directory empty;
  • dry and real runs give byte-identical refusals.
• Against a POSIX stub gh that answers only the two reads (skipped on Windows, like every #! stub here): both tools refuse a live or empty repository, and both only read when nothing exists.
• gh-not-found, asked in process on every platform, 8 tests: each tool, the dry run and the real run, with and without --reuse-empty-repo. Each asserts exit 2, the refusal's opening sentence and the one gh argv asked, which is repo view --json visibility for the scaffold with the flag and --json name for every other run.
• Controls: a dry run where nothing exists still plans and creates nothing.

Also new: conftest.assert_the_plan_refuses_a_remote_that_exists, with one-call wrappers in test_setup_project_py.py and test_setup_sh.py. It checks that step (5) refuses before the question, and that nothing is created.

Five existing tests dry-ran the scaffold against GitHub with no stub, so the conftest gh guard now caught their repo view calls:

• Three take --local-remote-dir, since none of their assertions depend on GitHub: test_a_neutral_product_root_is_planned_by_a_dry_run, test_the_dry_run_plans_a_pinned_neutral_product_root and the 13 cases of test_a_path_that_overlaps_nothing_the_scaffold_writes_plans.
• Two need the real-org plan line, so they ask the new conftest.scaffold_dry_run_on_github, which runs the scaffold in process with a stand-in for that one question: test_internal_visibility_is_accepted and test_the_longest_name_a_disk_keeps_is_still_accepted.
• test_family.py::test_init_dry_run_plans_the_gh_topic_command_for_a_real_org does the same, inline.

Red on main (7d9bec9), with these tests run against main's code: 31 failed, 17 passed.

• Red: 26 of the 28 new tests, both setup wrappers, and the three tests that now assert the GitHub question was asked. Main's dry run exits 0 where the real run refuses, asks no gh, and has no gh-not-found; all 8 gh-not-found tests fail there.
• Green: the 2 controls, plus the 15 tests that only gained --local-remote-dir.
• Red on the first version of this PR (0c81423's code): 2 of the 8 gh-not-found tests, the scaffold with --reuse-empty-repo, dry and real, with FileNotFoundError: [Errno 2] No such file or directory: 'gh'.

Branch runs:

Run	Result
Targeted set on the fix head: every tests/test_family*.py, test_scaffold*.py, test_setup*.py, test_cli_reference.py, test_repo_hygiene.py, and the new file, plus test_reuse_visibility.py	1494 passed, 19 skipped (615 + 879)
Same set on the merge with main 7d9bec9, before the fix	1488 passed, 19 skipped
17 other files that dry-run either tool or touch gh, at the first version (test_adopt_pins, test_bump_leg*, test_doctor_gitlink_repairs, test_leg_path_yaml_scalars, test_naming_policy, test_park_resume_targets, test_pin_source_*, test_refusal_default_remediation, test_shape_advisory, test_stdout_encoding, test_tracking_branch_ref, test_reuse_visibility, test_ruleset_hint_tracking_branch, test_agents_md_codes, test_gh_guard)	1252 passed, 10 skipped
Mutants of the first version: no question, the flag forced on, folder or remote dir made first, gh-not-found removed, refusal swallowed (each twice, once per tool)	10 of 10 killed
Mutants of the remote_visibility fix: the old traceback back, the wrong code, the missing gh swallowed to None, the wrong question named, the remedy's gh sentence lost, remote_is_empty's refusal swallowed	6 of 6 killed

README follow-up (after #519)

README's "If it fails part-way" box says "A second run is refused while they exist". Suggested wording:

A second run is refused while they exist, at the plan in step (5), before the yes: the plan is the scaffold's --dry-run, which asks whether each of the three already exists (#537).

Closes #537

🤖 Generated with Claude Code

Summary by Sourcery

Make dry-run planning match real-run remote validation and handle missing GitHub CLI prerequisites consistently.

Bug Fixes:

• Make family and scaffold dry runs detect and refuse existing remotes using the same checks as real runs, before any confirmation or filesystem changes.
• Report a missing gh CLI as a gh-not-found refusal instead of exposing a traceback in both dry and real runs.

Enhancements:

• Show reuse decisions for eligible empty or seed repositories during dry-run planning while preserving a read-only execution path.

Documentation:

• Update CLI reference and option help to document that dry runs check existing remotes and create or push nothing.

Tests:

• Add comprehensive coverage for remote checks, reuse behavior, missing gh, GitHub and local remote paths, setup integration, and no-side-effect guarantees.

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

[sourcery-ai]

Reviewer's Guide

Dry runs for family initialization and project scaffolding now invoke the real remote-existence/reuse checks after printing the plan, producing the same refusals or reuse output without mutating anything; missing gh is reported as gh-not-found, with CLI documentation and extensive offline/GitHub-path tests updated accordingly.

Sequence diagram for dry-run remote checks

sequenceDiagram
    participant User
    participant CLI
    participant RemoteCheck
    participant GitHubOrBareRepo

    User->>CLI: run --dry-run
    CLI->>CLI: print plan
    alt family init
        CLI->>RemoteCheck: _checked_reuse
    else project scaffold
        CLI->>RemoteCheck: _reusable_remotes
    end
    RemoteCheck->>GitHubOrBareRepo: gh repo view and commit listing
    GitHubOrBareRepo-->>RemoteCheck: remote status and optional seed commit
    alt remote exists and is not reusable
        RemoteCheck-->>CLI: Refusal family-remote-exists or scaffold-remote-exists
        CLI-->>User: refusal, create nothing
    else remote is empty and reuse enabled
        RemoteCheck-->>CLI: reuse output
        CLI-->>User: plan and reuse lines, create nothing
    else no remote exists
        RemoteCheck-->>CLI: continue
        CLI-->>User: plan, create nothing
    end

Loading

Sequence diagram for missing gh handling

sequenceDiagram
    participant User
    participant CLI
    participant RemoteCheck
    participant gh

    User->>CLI: run family or scaffold dry-run
    CLI->>RemoteCheck: _remote_is_empty or remote_is_empty
    RemoteCheck->>gh: gh repo view
    alt gh is not on PATH
        gh-->>RemoteCheck: FileNotFoundError
        RemoteCheck-->>CLI: Refusal gh-not-found
        CLI-->>User: remediation to install or authenticate gh
    else gh is available
        gh-->>RemoteCheck: repository status
        RemoteCheck-->>CLI: remote result
    end

Loading

Flow diagram for non-mutating dry-run behavior

flowchart TD
    A[Print execution plan] --> B{Remote check passes?}
    B -->|No| C[Refuse with matching real-run code]
    B -->|Yes| D{Reusable remote?}
    D -->|Yes| E[Print reuse line]
    D -->|No remote| F[Keep planned creation steps]
    C --> G[Exit without folder, remote, repository, work tree, or push]
    E --> G
    F --> G

Loading

File-Level Changes

Change	Details	Files
Make dry-run paths perform the real run's remote-reuse checks before declaring the plan complete.	Call _checked_reuse for family holder repositories after printing the plan. Call _reusable_remotes for all scaffold repositories, including seed-reuse handling. Preserve read-only behavior: no remotes, folders, work trees, or pushes are created. Report reuse decisions and use the real run's refusal messages and exit behavior.	scripts/family.py scaffold-project.py
Normalize missing GitHub CLI handling into the existing refusal mechanism.	Convert FileNotFoundError from gh probes into gh-not-found refusals with remediation text. Apply the behavior consistently to family and scaffold remote checks.	scripts/family.py scaffold-project.py
Document the expanded dry-run behavior and validate it across local and GitHub-backed paths.	Update both CLI help strings and regenerate the CLI reference. Add coverage for existing, empty, seeded, absent, and GitHub-backed remotes, including no-gh behavior and byte-identical real/dry-run refusals. Update setup-project/setup.sh assertions so step (5) refuses before confirmation. Adjust existing tests to use local remotes or an in-process GitHub-question stand-in.	docs/cli.md tests/test_dry_run_asks_remotes.py tests/conftest.py tests/test_family.py tests/test_scaffold_e2e.py tests/test_scaffold_leg_path_collisions.py tests/test_scaffold_manifest_values.py tests/test_scaffold_pin_and_reuse.py tests/test_setup_project_py.py tests/test_setup_sh.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#537	Make family.py init --dry-run check whether the holder remote exists and refuse it consistently with a real run, without creating the family folder.	✅
#537	Make scaffold-project.py --dry-run check whether its three remotes exist and refuse them consistently with a real run, so setup stops at the plan before asking for confirmation.	✅
#537	Handle a missing gh CLI with a named gh-not-found refusal rather than a traceback when the dry runs perform these remote checks.	✅

Possibly linked issues

• Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459: The PR fixes both listed cases by calling the real reuse checks during dry runs, refusing existing remotes before setup proceeds.
• family.py init --dry-run and scaffold-project.py --dry-run exit 0 without asking whether the remotes already exist #537: The PR fixes family.py init --dry-run and scaffold-project.py --dry-run exit 0 without asking whether the remotes already exist #537 by having family init and scaffold dry runs reuse real-run remote checks and refuse existing remotes before approval.

---

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-2, 2026-10-15T10:56Z)

This lane reviewed its own PR #573 at 0c81423, read-only and in its own detached worktrees. Nothing was authored.

MERGEABLE WITH NITS. Land #565 first or together with this PR.

Findings:

1. P3, fix-in-PR. With --reuse-empty-repo and no gh, both scaffold runs still end in a traceback, raised by remote_visibility (scaffold-project.py:940-941, :196-199). That contradicts the title's "dry and real runs alike". Catch it there too, or narrow the claim.
2. P3, follow-up. Without scaffold-project.py: a leg gh sees and git cannot read is refused scaffold-remote-exists with git's terminal prompt off, and the reuse re-run's visibility lines go by each leg as it stands (#542) #565, the dry run inherits scaffold-project.py re-run: a leg that gh sees and git cannot read gets a generic failure, and the reuse run's "two new legs" and private-leg text are wrong #542's N1: a generic refusal and git's prompt.
3. P3, follow-up. The dry runs never ask *-target-exists, and never ask whether --work-dir or --local-remote-dir can be made.
4. P3, follow-up. A real init makes the folder before it asks about the remote (family.py:1753-1754).
5. P3, follow-up. Any gh repo view failure reads as "absent" in both runs.
6. nit, follow-up. setup-project.py:1886 says "plan could not be produced". README's part-way box is now unblocked by tests/test_repo_hygiene.py and docs/handbook.html: each handbook section records the hash of every README section it reads, and README.md's line cap is 1422 plus one file per raise in tests/readme-cap.d/, so two README pull requests no longer conflict on the footer's one blob or the cap's one line, and a stale page names exactly which sections to re-read (#519) #551.

Tests:

• 0c81423: 1488 passed, 19 skipped.
• Merge with scaffold-project.py: a leg gh sees and git cannot read is refused scaffold-remote-exists with git's terminal prompt off, and the reuse re-run's visibility lines go by each leg as it stands (#542) #565: 43 passed.
• Merge with setup-project.py: paste lines quote each path, the scaffold's NEXT STEPS wait for step (7), step (3) refuses a file above the clone, -- --dry-run ends at the plan, step (4) hears passed pins, and the upstream guard ignores case (#538) #569: 320 passed.
• Merge with main 3102027: 457 passed.
• Red on main: 20 of 22 new tests fail, each as its name says.

Merges: clean with main, #565, #570, #572, #576, #577, #561 and lane 5's #568, #571, #574 and #578. #569 conflicts on additive helpers, and a union resolves it. #554 conflicts on imports. docs/cli.md passes --check on every merge.

The full report is in opensoft/brett-wip at handoffs/xFactory/attachments/lane-openRepoShape-2/review573-0c81423/final-report.md.

[brettheap]

(lane openRepoShape-2, 2026-10-15T12:18Z)

This lane re-verified its own PR #573 at 69c58aa, read-only and in its own detached worktrees. Nothing was authored.

MERGEABLE. Land #565 first or together with this PR, and only on a green three-OS run.

1. Fixed. With --reuse-empty-repo and no gh, both scaffold runs now refuse gh-not-found (scaffold-project.py:211-217). Probes of 22 no-gh paths through both tools gave exit 2 and no traceback. remote_is_empty's words are unchanged byte for byte.
2. P3, follow-up, also on main. A real run makes its work directory or family folder before that refusal (scaffold-project.py:1539, family.py:1753).
3. The two main merges change only import lines.

Tests:

• 69c58aa: 1494 passed, 19 skipped.
• Merges: main 64fc9a8, 148 passed; scaffold-project.py: a leg gh sees and git cannot read is refused scaffold-remote-exists with git's terminal prompt off, and the reuse re-run's visibility lines go by each leg as it stands (#542) #565, 135; setup-project.py: paste lines quote each path, the scaffold's NEXT STEPS wait for step (7), step (3) refuses a file above the clone, -- --dry-run ends at the plan, step (4) hears passed pins, and the upstream guard ignores case (#538) #569, 434; scaffold-project.py and adopt-project.py: a pin records digest_source: local-clone and never the --pin-source path, so no committed pin file holds a local directory, and a --pin-source nothing reads is pin-source-unused (#540) #570, 310.

Merges: clean with main, #565 and #570. #569 conflicts in three test files, and a union resolves them. test_scaffold_e2e.py merges cleanly and keeps FILE_PROTOCOL.

The full report is in opensoft/brett-wip at handoffs/xFactory/attachments/lane-openRepoShape-2/review573-0c81423/reverify-69c58aa.md.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
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