[brettheap]

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

Two re-run paths of scaffold-project.py, from the review of #506 and carried on #459 as v1.0.0 known limits. Both did their harm through the message. Base: main bfed143, merged with main b4c1f50 at 26a5f6a6 (no conflicts; main has moved on since, by files this PR does not touch). Head: 6889d991.

What changed

A leg gh sees and git cannot read. _reusable_remotes asks gh whether a leg is empty. For a leg that is not empty, _held_seed then asks git, through only_commit, whether its one commit is this scaffold's seed. gh can see a repository that git cannot read: gh is logged in and git has no credential for the host. In that case only_commit's CommandFailed reached main as the generic REFUSED a git or gh command failed, with --reuse-empty-repo and without it. Typed in a terminal, git stopped before that at its Username for ...: prompt, because run() set no GIT_TERMINAL_PROMPT.

• only_commit runs its git ls-remote and git fetch under PROBE_ENV, which is GIT_TERMINAL_PROMPT=0. They do this through a new optional env overlay on shape_materialize.run; with env unset, run behaves as before.
• _held_seed catches only_commit's CommandFailed and returns why, in one line: the command, its exit code and git's first fatal: line. _reusable_remotes then refuses the leg as scaffold-remote-exists, as it refuses any leg with commits (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's must-keep). The remedy says git could not read the leg, so whether it holds the seed cannot be asked: let git read it (on GitHub, gh auth setup-git), then re-run.

The reuse re-run's visibility lines.

• _leg_visibility's NOTE and WARNING spoke of "the two new legs". They are printed before _reusable_remotes knows which legs exist, so a re-run that reused one leg or both still called them new. Now they say what happens to a leg this run creates, and that a reused leg keeps its own visibility.
• _private_leg_note went by the run's visibility alone. So a private run that reused a public leg called that leg private, right beside the WARNING that it is public. And a public run that reused private legs printed no note at all. Now _create_remotes returns each repository's visibility as it stands: the run's for one it created, GitHub's for one it reused. The note names each private or internal leg at its own visibility. Two legs at the same visibility print the sentence they always did.

The Free-plan hint follows the root. _private_leg_note printed free_plan_secret_hint whenever a leg was private or internal. The hint says the organisation's secrets "resolve to EMPTY" inside the validate workflow, and offers repository secrets or an upgrade to Team. That is true of the repository the workflow runs in, the assembly root, and only when the root is private or internal: on the Free plan an organisation secret reaches a public repository. So a run with --visibility public, or a reused public root, that reused a private leg printed a false hint (rv542's matrix found 15 such runs this PR had added).

• _create_remotes now also carries the root's visibility out of the run: GitHub's for a reused root, read with remote_visibility and no second WARNING (_leg_visibility has already said where the run's flag disagrees with it), else the run's.
• The hint is printed only when that value is private or internal. The per-leg NOTE is unchanged: a public root still needs a credential to read a private leg.

Tests

• New, in tests/test_scaffold_reuse_seeded_legs.py: eighteen tests.
  • Seventeen run against a fake gh, which are POSIX-only, like that file's existing gh test. Three of them rewrite git's https://github.com/<org>/, to a missing path (the two unreadable-leg cases) or to a local server that answers 401 under a pseudo-terminal (the pty case). The other fourteen set no rewrite and reach no git remote: the five visibility-text cases and nine Free-plan-hint cases (the fake gh answers api orgs/<org> with the plan FAKE_GH_PLAN names).
  • One runs in-process and checks that both probe commands carry PROBE_ENV. It runs on every platform.
  • The nine hint cases: a public run over a new root, a reused public root, a public root the run inherits, and --visibility private over a public root print the NOTE and no hint; a public flag over a private root, an internal root, a private root with reused legs and a fresh private run print both; a paid plan prints the NOTE alone.
• Changed: tests/test_reuse_visibility.py's assertion of the old NOTE wording, and the in-process test's composite assert, now two (Sonar S9073).
• Red at the first head fdb0fa53, with this PR's test file: the first four hint cases, which print the hint at a public root.
• Red on main bfed143: 13 of the 18 new tests, and the updated assertion.
  • The terminal test hangs at Username for 'http://127.0.0.1:…': until the harness kills it at 90 s.
  • The unreadable-leg tests get REFUSED a git or gh command failed.
  • The in-process test fails because main has no PROBE_ENV.
  • Four of the five visibility-text cases fail on the old NOTE wording or the missing note; both-public is a control and passes.
  • Five of the nine hint cases fail: private-flag-over-public-root prints the false hint, and public-run-new-root, public-root-reused, public-root-inherited and public-flag-over-private-root get no NOTE at all for the reused private leg, since main goes by the run's visibility. The other four are controls and pass.
• Targeted run on the head 6889d991: 1183 passed, 19 skipped (1174 and 19 on the merge 26a5f6a6, plus the nine hint cases). It covered every tests/test_scaffold*.py, test_setup*.py and test_family_init*.py, plus test_template_text_placeholders.py, test_cli_reference.py, test_repo_hygiene.py, test_reuse_visibility.py, test_free_plan_hint.py and test_ruleset_hint_tracking_branch.py. scripts/render-cli-reference.py --check passes, and no --help text changed.
• Mutants of the hint, 5 of 5 killed at 6889d991: the hint ignores the root; a reused root takes the run's flag instead of GitHub's; an internal root is not closed; the hint's root condition inverted; the NOTE gated by the root too.
• Mutants of the first commit, 6 of 6 killed at fdb0fa53, not re-run: no CommandFailed catch; no PROBE_ENV on ls-remote; no PROBE_ENV on fetch; the reused leg's visibility not kept for the note; the old NOTE wording; git's last line in place of its first fatal: line.

Left out

• adopt-project.py:7131-7138 keys the same Free-plan hint to the legs while the adopted root keeps its own visibility. It is as on main, and belongs to Tracking: adopt-project.py, converting an existing repository in place #457.
• --filter=tree:0 on the probe fetch, which Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459 marks optional. It saves a download and changes no message. git 2.43 accepts it on a URL fetch (measured: one object fetched, and the probe marked as a promisor), so it can follow in its own change.
• The manifest's visibility: still records the run's value. A re-run whose reused legs keep another visibility makes the template's comment, "this is all three repositories' visibility", untrue. That is not a message, so it is left out of this PR.

README follow-up (after #519): none needed.

Closes #542

🤖 Generated with Claude Code

Summary by Sourcery

Make scaffold-project reuse checks fail clearly for unreadable remotes and report repository visibility and credential guidance according to each leg and the assembly root as they actually stand.

Bug Fixes:

• Refuse existing GitHub legs that gh can see but git cannot read with a specific access-related remediation instead of a generic command failure or terminal hang.
• Report reused and newly created leg visibility accurately, including per-leg private/internal access notes and Free-plan hints based on the assembly root's actual visibility.

Enhancements:

• Disable terminal prompts for scaffold seed probes and support per-command environment overlays.
• Improve reuse visibility messaging so it reflects each repository's current state and avoids describing reused legs as newly created.

Tests:

• Add coverage for unreadable legs, disabled git prompts, mixed reused-leg visibility, and Free-plan hint behavior across root visibility and billing plans.

[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

The PR hardens scaffold reruns by preventing Git credential prompts during seeded-leg probes, turning Git-inaccessible but GitHub-visible legs into precise existing-remote refusals, and making reuse visibility messaging reflect each leg’s actual visibility, with comprehensive regression tests.

Sequence diagram for unreadable seeded-leg refusal

sequenceDiagram
    participant Scaffold as scaffold-project.py
    participant GH as gh
    participant Git as git
    participant Run as shape_materialize.run

    Scaffold->>GH: remote_is_empty
    GH-->>Scaffold: repository has commits
    Scaffold->>Git: only_commit
    Git->>Run: git ls-remote and git fetch
    Run->>Git: GIT_TERMINAL_PROMPT=0
    Git-->>Run: CommandFailed
    Run-->>Scaffold: command, exit code, first fatal line
    Scaffold-->>Scaffold: refuse as scaffold-remote-exists
    Scaffold-->>Scaffold: advise git access, then re-run

Loading

Flow diagram for per-leg reuse visibility messaging

flowchart TD
    A[_create_remotes] --> B{Leg reused?}
    B -->|No| C[Record run visibility]
    B -->|Yes| D[_reused_leg_visibility]
    D --> E[Read GitHub visibility]
    C --> F[Return each leg visibility]
    E --> F
    F --> G[_private_leg_note]
    G --> H{Private or internal legs?}
    H -->|Yes| I[Name each affected leg at its actual visibility]
    H -->|No| J[No visibility note]

Loading

File-Level Changes

Change	Details	Files
Make remote-leg probing non-interactive and convert unreadable GitHub legs into actionable existing-remote refusals.	Add an environment overlay to command execution while preserving the caller environment. Disable Git terminal prompts for git ls-remote and git fetch probes. Capture Git command, exit status, and diagnostic text when a leg cannot be read. Refuse unreadable legs as scaffold-remote-exists and recommend configuring Git authentication before rerunning.	scaffold-project.py scripts/shape_materialize.py
Report visibility based on each leg’s actual state during reuse reruns.	Clarify that visibility notes apply to legs created this run while reused legs retain their existing visibility. Return each leg’s effective visibility from remote creation and use it for private/internal-leg guidance. Generate per-leg or combined notes only for legs that are actually private or internal.	scaffold-project.py tests/test_reuse_visibility.py
Expand regression coverage for unreadable remotes, prompt suppression, and per-leg visibility messaging.	Add fake-gh, rewritten Git-host, and pseudo-terminal scenarios covering unreadable legs with and without reuse. Verify both probe commands receive the non-interactive environment. Test mixed, matching, and public/private/internal visibility combinations and update wording assertions.	tests/test_scaffold_reuse_seeded_legs.py tests/test_reuse_visibility.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#542	When GitHub CLI can see a non-empty leg but Git cannot read it, avoid a terminal credential prompt and refuse the leg as scaffold-remote-exists with a leg-specific explanation and remedy, rather than the generic command-failed message.	✅
#542	Make reuse-run visibility messages accurately describe legs created versus reused, and base private/internal-leg notes on each leg’s actual visibility rather than only the run’s requested visibility.	✅

Possibly linked issues

• Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459: The PR implements both requested fixes: unreadable legs are refused as scaffold-remote-exists, and reuse visibility messages reflect each leg’s status.

---

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:55Z)

This lane reviewed its own PR #565 at fdb0fa5, read-only in its own detached worktrees, and authored nothing.

CHANGES NEEDED, one small fix. A fix round follows on this branch. The PR lands only on Brett Heap's word.

Findings:

• P3, fix in this PR. The Free-plan hint now prints when the assembly root is public (scaffold-project.py:1193-1196). It is keyed to the legs, but the workflow runs in the root. A public run that reuses a private leg says org secrets "resolve to EMPTY" and suggests upgrading to Team. Key the hint to the root's own visibility (read at :982) and add a test.
• Nit, fix in this PR: split the composite assert at tests/test_scaffold_reuse_seeded_legs.py:484 (Sonar S9073).
• Nit, fix in this PR: the PR body and squash message say eight tests rewrite git's URL. Three do.
• Follow-ups for Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459:
  • the push of a reused empty leg still waits at Username for (:1249);
  • ssh, prompting credential helpers and askpass still prompt;
  • the SSH-rewrite remedy (:512);
  • the manifest visibility:;
  • --filter=tree:0 fails on a local path.

Tests at fdb0fa5: 5170 passed, 32 skipped (61 targeted files). Main with the new tests: 9 failed, 14 passed, each for its stated reason. 22 refusal probes all refused scaffold-remote-exists with nothing created. In a 272-run text matrix, the NOTE, the WARNING and the private-leg note agreed every time. CI: Linux and macOS passed; Windows was still running.

Merges: clean with main, #570, #569 and fix/522.

The full report is handoffs/xFactory/attachments/lane-openRepoShape-2/review565-fdb0fa5/final-report.md in opensoft/brett-wip.

[brettheap]

(lane openRepoShape-2, 2026-10-15T11:49Z)

This lane re-verified its own PR #565 at 6889d99, read-only in its own detached worktrees, and authored nothing.

MERGEABLE WITH NITS. Land it before #573: #573's --dry-run reaches only_commit, and alone it meets a leg git cannot read with the generic refusal or a Username for wait. Landing waits for the v1.0.0 tag, Brett Heap's word and three-OS CI.

• Fixed: the Free-plan hint prints only for a private or internal root. Of 256 runs, it printed in all 159 with a closed root and leg, and in none of the 66 with a public root.
• Fixed: Sonar reports 0 issues; the texts' counts hold.
• Nit, follow-up: the hint still names the legs as its reason (scaffold-project.py:1210).
• Nit: squash-message.md:4 omits the b4c1f50 merge.

Tests at 6889d99: 1183 passed, 19 skipped (21 files). fdb0fa5 with the new tests: 4 failed, each a hint at a public root.

Merges: clean with main 9f80939 and #570. #573 conflicts with main itself, in two test files.

The report is handoffs/xFactory/attachments/lane-openRepoShape-2/review565-fdb0fa5/reverify-6889d99.md in opensoft/brett-wip.

[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