[brettheap]

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

Merge and round (2026-10-15): main 396c0ff (#570) is merged in (c3d8a97), with no conflict to resolve, and every case below still holds on it, #574's family.py changes included. The round adds #459's L2-60 and #461's L2-67 (60e1601), described under L2-34 and Tests, a second commit (5263d78) that gives L2-60's refusal a remediation that fits, and a third (227bc3b) for the two problems the reviewer's re-verify of that found: a traceback for init --into named for the family over a holder with no search bit, and the same kind of remediation for a folder that is only unwritable.

What changed

scaffold-project.py and scripts/family.py init now ask the same question in the dry run and the real run, before anything is made: every folder the run makes and each working tree it writes, then every remote. The real run makes its folders only after all of that.

• L2-34: folders and target-exists. Before the remote question, both runs ask:

  • whether --work-dir, --local-remote-dir and the family folder can be made. A file at the folder or above it is refused, and so is a folder this user cannot write in. The codes are scaffold-folder-cannot-be-made and family-folder-cannot-be-made. A file is told to be moved aside; a folder that is only unwritable is told to be given write and search permission, or replaced by another --work-dir, --local-remote-dir or --into (the flag it was met by): "Remediation: nothing was created, and --dry-run refuses the same. Give this user write and search permission on that folder, or choose another , and run this again." It is the sentence the trees get, from one _unwritable_remediation.
  • whether a working tree is in the way. A file where a tree or the holder goes is now scaffold-target-exists / family-target-exists, beside the non-empty folder both tools already refused.

  The real run's own mkdir (make_folder) refuses in the system's words, so a folder that changes between the question and the mkdir gets a refusal too. No run ends in a FileExistsError or NotADirectoryError traceback any more.

• L2-60: an existing EMPTY working tree or holder this user cannot write in. The question about a working tree passed any folder that held nothing, so with such a tree at mode 555 the dry run exited 0 and the real run made the bare remotes and then died with a PermissionError traceback at the first file it wrote there (on GitHub, that leaves created repositories behind). target_in_the_way now asks, after the emptiness check, the question folder_cannot_be_made asks of a folder to make, os.access(W_OK | X_OK), and answers is a folder this user cannot write in (one constant, shared by both). A folder that holds anything is still is not empty, whatever its mode. Both tools already asked target_in_the_way for every tree and for the holder before the remote question, so each refuses it by name, scaffold-target-exists or family-target-exists, in the dry run and the real run, before any remote is made, and no caller changed.

  • Its remediation. The tools' own sentence for this code, "choose an empty --work-dir. There is no --force: re-running over a live tree…", is about a tree that holds something, and wrong for an empty folder whose only fault is its permissions. target_remediation (scripts/shape_materialize.py) is the one place that chooses, by what target_in_the_way said. For the unwritable folder it says: "Remediation: nothing was created, and --dry-run refuses the same. Give this user write and search permission on that folder, or choose another <flag>, and run this again." The flag is --work-dir for the scaffold, and for init the one the person landed by: --work-dir where there is no family folder, --into otherwise. Every other answer (a file, a folder that holds something) gets the tool's own sentence, exactly as it was. The finding codes are unchanged.

• init --into named for the family, over a holder this user cannot search. Orbit/Orbit is the holder there, and _landing asked (into / family / MANIFEST).is_file() of it: Path.is_file() raised PermissionError for a holder with no search bit (mode 600), so both runs ended in a traceback before any question; at mode 555 it was already refused by name. It is the same on main 396c0ff. _landing now asks os.path.isfile, which answers False, as _standard_checkout beside it does. Every other .is_file() or .exists() on the landing path is guarded already: the folder and tree questions use os.path.lexists and stat / iterdir inside try, and the two bare.exists() calls (_local_remote_is_empty, both tools) come after the --local-remote-dir question, which refuses a folder with no w or no x first (probed at modes 600 and 000, the folder itself and a path below it, and the default landing in a folder named for the family).

• L2-36: only gh's not-found means absent. gh 2.x answers a missing repository with exit 1 and GraphQL: Could not resolve to a Repository with the name '<o>/<r>'. (repository). The words come from GitHub's GraphQL error, and gh's FetchRepository builds the same ones when the API returns no repository. The string is in the local gh 2.96.0 binary. Only exit 1 with those words reads as absent. Every other gh repo view failure, in the dry run and the real run, is remote-unreadable, which names the command, its exit and gh's first line. That covers a 401, a rate limit, no network, gh's exit 4, and the not-found words under any exit but 1.

• L2-35: no empty family folder. A real init asks _checked_reuse before _prepare_landing_dir, so a refusal leaves no folder. The scaffold's real run likewise no longer makes --work-dir (or a temporary directory) before its remote question.

The questions are one definition in scripts/shape_materialize.py, which is not a shape copy, so nothing is re-pinned: folder_cannot_be_made, refuse_unmakeable_folder, make_folder, target_in_the_way, target_remediation and refuse_unless_not_found. Both tools import them.

--dry-run's help in both tools names the folder question, and docs/cli.md is regenerated (render-cli-reference.py --check passes).

tests/test_scaffold_manifest_values.py's fake gh used to answer every call fake gh: no network here, exit 1. It now answers repo view the way GitHub answers for a repository it does not have, so test_a_value_once_misread_reaches_gh_as_an_accepted_one_does still reaches gh repo create.

Tests

New file: tests/test_dry_run_parity.py, 86 tests: the 43 of the first head, 9 for L2-60, 11 for its remediation and 23 for the third commit.

• The issue's seven measured cases (four scaffold, three init) and six beside them: a file above --work-dir or --local-remote-dir, --into a file, the family's --work-dir a file or holding a file named for the holder, and the family's --local-remote-dir a file. In every case both runs refuse with the same REFUSED line and the same stdout and stderr, and nothing under the test's directory is made, changed or removed, the temporary directory included.
• A folder this user cannot write in, for both tools.
• A stub gh answering repo view in each way, for both tools and both modes. The failing answers are an HTTP 401, a rate limit, no network, exit 4, and the not-found words under exit 4: each is refused by name at the first repo view, and nothing is created. gh's not-found answer still plans (dry run) and goes on to gh repo create (real run). One more case covers --reuse-empty-repo with a 401.
• L2-35: a real init refused family-remote-exists leaves no into/. The scaffold's real run refused scaffold-remote-exists or gh-not-found leaves no --work-dir.
• The real run's own mkdir refusing by name, when the question is made to say yes.
• In-process unit tests of the five helpers.
• L2-60: one test per tool (scaffold's root, init's holder), per mode (--dry-run, real run) and per way the empty tree cannot be written in (no w, mode 555; no x, mode 600): 8 tests. Each asserts the REFUSED line, exit 2, no traceback, nothing made or changed under the test's directory and no bare remote. Plus an in-process test that target_in_the_way names an empty unwritable folder and still says is not empty for one that holds a file. They are skipped for root and on Windows, as the unwritable fixture is, which is now built on the same maker.
• The remediation: the eight L2-60 run tests also pin the new sentence on each tool's unwritable row (--work-dir for the scaffold, --into for init); two more pin --work-dir under init --work-dir; eight pin that a tree holding a file or a non-empty folder keeps its old sentence exactly, per tool and mode; one tests the chooser. On 60e1601's source 13 of the 63 fail (the eight keep-old tests pass there, as they pin what must stay).
• The third commit: the Orbit/Orbit layout (--into named for the family) at modes 555 and 600, dry run and real run, refused by name with nothing made; one row per flag for the unwritable folder's sentence (scaffold --work-dir and --local-remote-dir; init --into, --work-dir and --local-remote-dir), dry run and real run, 10 tests; the ancestor case (ro/wd) pins it too; eight cases where a file stands in the way keep the old "move what stands in the way aside"; one tests refuse_unmakeable_folder's choice. On 5263d78's source 15 of the 86 fail (the 8 keep-old tests and the 555 layout pass there, as controls).
• L2-67: the two tests that spelled POSIX strerror text (File exists, Not a directory) now build the expected text from the exception mkdir raises (mkdir_says), so they hold where the system words it otherwise. Under an uncommitted plugin that words os.mkdir's failures as Windows does, the old file fails 5 tests and the new one passes the same 5.

Red on main 2989b4c: 41 failed, 2 passed (the first head's 43 tests). The two that pass are the not-found controls, which must pass on main.

Red on the merge (main 396c0ff and this file, before the L2-60 change): 9 failed, 43 passed. The 9 are the L2-60 tests: each dry run exited 0 and each real run made the bare remotes and then raised PermissionError.

Runs (Linux, /usr/bin/python3 3.12, targeted files only; the first three rows are the first head's):

Run	Tree	Result
New file on main	2989b4c + the test	41 failed, 2 passed
Targeted: every test_scaffold*, test_family*, test_setup*, plus test_dry_run_asks_remotes, test_dry_run_parity, test_reuse_visibility, test_tracking_branch_ref, test_free_plan_hint, test_cli_reference, test_repo_hygiene	2989b4c + the fix	1775 passed, 19 skipped
New file, with Path.write_text writing CRLF in pytest and every child	the fix	43 passed
test_dry_run_parity, test_dry_run_asks_remotes	the merge c3d8a97	71 passed
New file with the L2-60 tests	the merge, before the L2-60 change	9 failed, 43 passed
Same targeted set, in two runs	c47bde20 (this head less one test-only fixture merge)	913 + 1041 = 1954 passed, 19 skipped (test_family_init_values' template-quoting skips)
New file, plain and with the CRLF plugin	60e1601	52 passed, 52 passed
Confirmation: test_dry_run_parity, test_dry_run_asks_remotes, test_family, test_family_init_values, test_family_init_landing, test_family_dry_run, test_scaffold_manifest_values, test_cli_reference, test_repo_hygiene	60e1601	554 passed, 19 skipped
New file on 60e1601's source, before the remediation change	60e1601 + the new tests	13 failed, 50 passed
test_dry_run_parity, test_dry_run_asks_remotes	5263d78	91 passed
New file, with the CRLF plugin	5263d78	63 passed
test_dry_run_parity, test_dry_run_asks_remotes, test_family_dry_run, test_family_init_landing, test_family_init_values, test_scaffold_manifest_values, test_cli_reference, test_repo_hygiene	5263d78	459 passed, 19 skipped
New file on 5263d78's source, before the third commit	5263d78 + the new tests	15 failed, 71 passed
test_dry_run_parity, test_dry_run_asks_remotes, test_family_dry_run, test_family_init_landing	227bc3b	184 passed
New file, with the CRLF plugin	227bc3b	86 passed
The four files above, every test_scaffold*, test_cli_reference, test_repo_hygiene	227bc3b	905 passed
Every test_family* and test_setup*	227bc3b	976 passed, 19 skipped

An independent probe (the reviewer's, run by hand against a stub gh that refuses anything but repo view) agrees on the merge: the seven cases, the 401 stub in both tools and both modes, and --reuse-empty-repo each give the same REFUSED line in the dry run and the real run with nothing made, and the L2-60 case X1 and X2 refuse alike after the change.

Mutants: 39 killed of 39, none survived, each run against the new file in a scratch clone.

• The first head's 13, re-run on the merged code: any failure reading as absent again, and the not-found words accepted under any exit; init making its folder before _checked_reuse; either dry run skipping the folder question; no writability check, and the question asked of the path only; no question about what stands at the target, no --local-remote-dir question, no holder question, no tree question; make_folder letting the OSError out; the scaffold making --work-dir before the remote question.
• L2-60's, 9: target_in_the_way asking nothing; asking only W_OK (killed by the no-x tests) or only X_OK (the no-w tests); asking the folder above the tree; asking before the emptiness check (killed by the unit test alone); the scaffold's dry run or its real run skipping the trees; init's dry run skipping the holder; init's holder question ignoring the answer.
• L2-67's, 2: make_folder quoting the whole exception, or a fixed File exists.
• The third commit's, 8 (on 227bc3b): _landing asking Path.is_file() again (killed by the two mode-600 Orbit/Orbit tests); an unwritable folder getting the old sentence again, or every folder refusal getting the new one; init's family-folder question naming no flag; _landing_flag always --into; init's --local-remote-dir question naming --into, and the scaffold's naming --work-dir; refuse_unmakeable_folder ignoring the flag it is given.
• The remediation's, 7 (on 5263d78): the chooser always returning the old sentence (the unwritable case gets it), or never (a held tree gets the new one); init always saying --into, or always --work-dir; the scaffold saying --into; each caller asking the chooser about a held tree.

README follow-up

None. README's and AGENTS.md's words about the plan and init --dry-run stay true as written.

Closes #609

🤖 Generated with Claude Code

Summary by Sourcery

Make scaffold and family initialization preflight all filesystem targets and remote lookups consistently, refusing unsafe or indeterminate runs before creating files or repositories.

New Features:

• Align dry-run and real-run validation for scaffold and family initialization so both reject unmakeable folders and occupied or unwritable targets before creating anything.
• Treat only GitHub CLI's explicit repository-not-found response as an absent remote, and refuse other repository lookup failures.

Bug Fixes:

• Prevent refused family initialization and scaffold runs from leaving empty directories or partially created remotes behind.
• Replace filesystem tracebacks caused by files, permissions, or inaccessible paths with named refusals and actionable remediation.
• Handle family initialization paths that cannot be searched without raising a permission traceback.

Enhancements:

• Centralize folder, target, remediation, and remote-lookup checks for reuse by both commands.
• Report system-specific directory creation errors without hard-coded platform wording.

Documentation:

• Update CLI help and reference documentation to describe preflight folder checks and dry-run behavior.

Tests:

• Add comprehensive parity tests covering filesystem conflicts, permissions, remote lookup failures, refusal remediation, and platform-specific mkdir errors.
• Update fake GitHub CLI responses to use the canonical repository-not-found response.

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

[sourcery-ai]

Reviewer's Guide

The PR centralizes filesystem and GitHub remote preflight logic, makes scaffold and family init ask identical questions in dry-run and real modes before creating anything, and adds extensive tests and documentation for refusal semantics and side-effect-free failures.

Sequence diagram for parity-safe scaffold and family initialization

sequenceDiagram
    participant User
    participant Tool as ScaffoldOrFamilyInit
    participant Preflight as shape_materialize
    participant GH as gh_repo_view
    participant FS as Filesystem
    participant Writer as RemoteAndTreeWriter

    User->>Tool: run(dry_run_or_real)
    Tool->>Preflight: refuse_unmakeable_folder()
    Tool->>Preflight: target_in_the_way()
    Tool->>GH: repo_view(repository)
    GH-->>Tool: exit 1 + Could not resolve to a Repository
    Tool->>Preflight: refuse_unless_not_found()
    Preflight-->>Tool: remote is absent
    alt dry run
        Tool-->>User: print plan, create nothing
    else real run
        Tool->>Preflight: make_folder()
        Tool->>Writer: create remotes and working trees
        Writer->>FS: write folders and trees
    end

Loading

Flow diagram for preflight refusal decisions

flowchart TD
    Start[Start scaffold or family init] --> Folders[Check folders with folder_cannot_be_made]
    Folders --> Targets[Check trees or holder with target_in_the_way]
    Targets --> Remote[Run gh repo view]
    Remote --> Status{Exit 1 and gh not-found words?}
    Status -->|No| Unreadable[Refuse remote-unreadable]
    Status -->|Yes| Repos[Continue as repository absent]
    Folders -->|Cannot make| FolderRefusal[Refuse scaffold-folder-cannot-be-made or family-folder-cannot-be-made]
    Targets -->|File, non-empty, or unreadable| TargetRefusal[Refuse scaffold-target-exists or family-target-exists]
    Repos --> Mode{Dry run?}
    Mode -->|Yes| Plan[Print plan; make nothing]
    Mode -->|No| Make[make_folder, then create remotes and trees]

Loading

File-Level Changes

Change	Details	Files
Align dry-run and real-run preflight checks so all filesystem destinations are validated before any writes.	Added shared checks for creatable parent folders, writable directories, existing files, and non-empty working-tree targets. Moved folder creation until after filesystem and remote checks, preventing leftover temporary, work, or family directories. Wrapped race-condition mkdir failures as named refusals instead of traceback errors. Applied the same ordering and refusal behavior to scaffold and family initialization.	scaffold-project.py scripts/family.py scripts/shape_materialize.py docs/cli.md
Treat only GitHub CLI's canonical exit-1 not-found response as evidence that a remote is absent.	Added shared validation of gh repo view results, including exit status and first diagnostic line. Classified authentication, rate-limit, network, exit-4, and malformed not-found responses as remote-unreadable. Updated both scaffold and family remote probes to use the stricter classification.	scaffold-project.py scripts/family.py scripts/shape_materialize.py
Add comprehensive parity and failure-mode coverage for the new preflight behavior.	Added 43 tests covering filesystem conflicts, permissions, remote failures, ordering, no-side-effect guarantees, helper behavior, and race-time mkdir failures. Updated the fake gh fixture to emit the canonical GitHub not-found response. Added CLI documentation and help-text assertions for folder preflight questions.	tests/test_dry_run_parity.py tests/test_scaffold_manifest_values.py docs/cli.md

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#609	Make scaffold and family.py init dry runs check whether the folders they need can be created and whether their working-tree targets are clear, refusing files, non-empty targets, and unwritable locations as the real runs do.	✅
#609	Treat only GitHub CLI’s not-found response as evidence that a repository is absent; refuse other gh repo view failures by name in both dry and real runs.	✅
#609	Have family.py init check whether the holder’s remote can be reused before creating its family folder, so a refusal leaves no empty folder.	✅

Possibly linked issues

• Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459: Link: the PR fixes all three issue items—L2-34 folder/target checks, L2-36 gh not-found handling, and L2-35 avoiding an empty init folder after refusal.
• Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459: The PR specifically fixes both cited dry-run remote-check omissions and the empty-folder side effect, so it closes the issue.

---

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-15T19:28:50Z)

This lane reviewed its own PR #622 at 7f7e1b4, read-only in its own detached worktrees, and authored nothing.

MERGEABLE WITH NITS, with no sequencing constraint.

• P3, follow-up: an empty tree target or holder this user cannot write in is still not asked about (scripts/shape_materialize.py:1363). The dry run exits 0. The real run makes the remote, then raises a PermissionError traceback. Main does the same.
• nit, follow-up: tests/test_dry_run_parity.py:369 and :608 assert POSIX strerror text with no Windows skip.

A separate probe checked the seven cases and the 401 stub in both tools and both modes. Each time the dry and real runs refused alike and made nothing. 11 of 13 mutants were killed.

Tests at the head: 1775 passed, 19 skipped; 967 passed, 1 skipped. Merged: 1898 passed, 19 skipped; 947 passed, 1 skipped. merge-tree with bcfa364 is clean.

Report: handoffs/xFactory/attachments/lane-openRepoShape-2/review622-7f7e1b4/final-report.md in opensoft/brett-wip.

[brettheap]

(lane openRepoShape-2, 2026-10-15T23:58:42Z) Readiness round on this PR, re-verified CLEAN at 227bc3b (rv622r). The round carries no merge word.

• c3d8a97 is git's own clean merge of main 396c0ff. This PR's earlier diff is unchanged by it.
• L2-60 (Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459). An EXISTING EMPTY target or holder folder that this user cannot write in is now refused by name, in the dry run and the real run, in both the scaffold and family.py init, before any remote exists. The refusal is scaffold-target-exists or family-target-exists, "is a folder this user cannot write in".
  • The remediation: give this user write and search permission on that folder, or choose another flag. The flag named is --work-dir, --into or --local-remote-dir, whichever placed the folder.
  • Every other case keeps its old sentence exactly.
• L2-67 (Tracking: the test suite, CI and the docs #461). The strerror tests build their expected text from the exception, so they pass with Windows wording.
• A pre-existing traceback is fixed. With --into named for the family and the holder at mode 600, init crashed at _landing's is_file(). It now refuses by name.
• Probes:
  • 58 cases, plus a sweep of 128 cases (8 modes over 16 landing and remote positions, each in both modes). The sweep found no traceback and no difference between the dry run and the real run, and no refused real run made anything.
  • rv609's own 22-case probe now differs from 7f7e1b4 only where L2-60 refuses.
• Tests and mutants:
  • test_dry_run_parity (86), test_dry_run_asks_remotes, test_family_dry_run and test_family_init_landing give 184 passed.
  • The writer's wider sets give 905 + 976 passed.
  • On a predicted merge with main bf7b19b, 490 passed.
  • 31 + 8 writer mutants and 19 reviewer mutants were all killed.

227bc3b needs Linux green as a new H0 (SonarCloud has passed). It is waiting for a merge word from Brett Heap.

[sonarqubecloud]

Quality Gate passed

Issues
3 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