[brettheap]

Lane: openreposhape-1 (openRepoShape-1)
Claim: #652 (comment)

This PR goes straight to main, and is not stacked: #650 (D2), which it was authored on, has landed as 3dc34b8. The branch merged main at 2fac979 before its first commit, and at 66b230e (with #718's check --local-remote-dir) before the review's fix round.

What

How adopt-project.py reads --source, and what becomes of the clone it makes.

• A --source is read by its spelling first (_source_spec).

  • Read in place: a path spelled as one (/, ~, ./, ../, a drive or a share).
  • Cloned: an org/repo name, or a github.com url.
  • A name that is ALSO a path here is refused as source-ambiguous, and the refusal names both spellings: ./acme/Atlas reads the directory, and https://github.com/acme/Atlas clones the repository (L1-24).

• One name, however it is spelled (_github_name). A trailing /, an empty segment and one .git are dropped. https://github.com/<o>/<r>, git@github.com:<o>/<r>.git and github.com/<o>/<r>, with no scheme, all name <o>/<r>.

  • gh is handed <o>/<r>, the clone is source-readonly/<r>, and the plan records repository: <o>/<r> (L1-43).
  • A url on another host is source-unresolvable, by its host. A missing path that is no owner/repo (a/b/c) is source-unresolvable and never reaches gh.

• The plan records whether plan made its clone: source.cloned: true or false.

  • A clone plan made, gone or no longer whole, is cloned again from GitHub by its recorded name. It is never read through the current directory. "No longer whole" means it is not the top of a repository of its own, or no longer holds the plan's commit.
  • Any other local_path that is gone is plan-source-gone, named by its key, with --source as the way past it (L1-22, L1-26, L1-27). The way out names no recorded org/repo as GitHub's: the plan does not record the host a clone's origin was on.

• One clone path (Source.clone). It asks, in order:

  1. the work directory (adopt-project.py: a --work-dir that is a file or cannot be made ends plan, check and execute in a traceback, and --help says nothing of --work-dir or of where --org comes from #650);
  2. whether its target already holds something: adopt-work-dir-occupied, by name, where it was source-unclonable with a remedy about gh auth status. execute's way out begins by saying that no leg repository was created and nothing was pushed, and ends by saying that an earlier execute given that --work-dir keeps the clone it made there;
  3. then it prints the NOTE, then it clones.

• A clone no plan records is removed (_leave_the_clones, in main's finally, L1-23):

  • plan removes its clone when it writes no plan, and keeps it once the plan is written, whatever ends the run after;
  • check removes its --source clone, and the one it makes again;
  • a clone is removed only while its real path is still the one it was made at, so nothing a symlink leads to goes, whenever the symlink was put there;
  • read-only files are removed too, as Windows needs, and no mode is ever lowered;
  • a clone that cannot be removed is named in a NOTE on stderr, and the exit stays the command's.

  execute keeps its clone, and the work directory it made says so on its last line, as before.

• --help for --source (plan, check and execute) and --work-dir (plan and check) says all this. docs/cli.md is regenerated.

Why (repro on main)

Probed on 2fac979 and on d7b12c5 (#650's head), with a stand-in gh that parses names as gh does and clones from disk. No real gh was run.

• L1-24. The current directory held ./acme/Atlas, with one local-only commit.
  • plan --source acme/Atlas exited 0, made 0 gh calls, and planned that directory.
  • Its plan's clone gone, check printed "is cloned again, as --source acme/Atlas would clone it", made no call, and read the directory: plan-stale and plan-uncovered: LOCAL.md.
• L1-43. With gh's own parse, --source acme/Atlas/ was refused source-unclonable: … expected the "[HOST/]OWNER/REPO" format, plus the gh auth status remedy. With a stand-in that skips the parse, it cloned into source-readonly/ itself. Then adopt-not-the-source refused it, and the clone stayed.
  • acme//Atlas, acme/Atlas.git, the urls and github.com/acme/Atlas each went to gh as typed. None wrote a plan.
• L1-22. A local source with no origin, moved away: check and execute handed the path to gh repo clone and refused source-unclonable with the gh auth status remedy.
  • A recorded D:\work\Atlas was source-unresolvable: --source 'D:\\work\\Atlas' is neither…, naming a --source nobody passed.
• L1-27. A moved clone whose origin is gitlab.com/acme/Atlas was cloned again from github.com as acme/Atlas. Only plan-stale stopped it.
• L1-26. A clone plan made was cleaned four ways: emptied, files removed with directories kept (macOS's cleaner), packs removed, HEAD removed. Every one was refused git-failed.
  • Emptied inside another repository, it was read as that repository, until a git ls-remote failed as "a git or gh command failed".
• L1-23. One run each of plan, check --source, a refused plan, execute --source and check (its plan's clone gone) left 4 clones in the temp folder. Three of them said nothing.
  • check --work-dir W and then execute --work-dir W, as check's help says to run them, failed at the clone check left: source-unclonable with the gh auth status remedy.
• Two spellings the review asked about (on 2fac979):
  • --source Atlas with no ./Atlas is source-unresolvable before any gh call. It is unchanged.
  • github.com/acme/Atlas cloned, and was then refused adopt-not-the-source, with or without --org, so it never worked. It is now read as acme/Atlas.

How

All of it is in adopt-project.py.

• _source_spec, _repository_in_url, _github_name and SOURCE_URL_RE read a --source:

  1. a path by its spelling;
  2. a url, or github.com/…, by its host;
  3. an owner/repo name, refused as source-ambiguous when it is also a path here;
  4. anything else as a path.

  A name that is not text, or begins with - (S8705), is never an owner/repo, as before.

• Source.open takes a --source. Source.in_place reads a path. Source.clone clones a name, and asks the work directory, the target, and only then prints the NOTE.

• Plan.open_source and _recorded_source replace _where_the_clone_is_gone.

  • A recorded local_path is read as a path and never as a --source.
  • A recorded repository is only ever cloned from GitHub, by its name, and never read as a directory here.
  • Only source.cloned: true lets check and execute clone again.
  • _not_a_whole_clone asks git rev-parse --show-toplevel and cat-file -e <commit>^{commit}.
  • A clone made again at the plan's own local_path (the same --work-dir) is the plan's source again, and is kept.

• render_plan writes cloned: after local_path:, with three comment lines above source:.

• _leave_the_clones runs before _leave_the_work_root in main's finally.

  • It removes each clone Source.clone listed on args.clones for plan and check, and keeps plan's once cmd_plan has written the plan (args.plan_written, set right after write_lf), whatever ends the run after.
  • It leaves any clone whose real path is not the work directory's own source-readonly/<repo>: a symlink at any level, there before the run or put there during it, is never followed. Source.clone lists each target with the real path it had when it was made, and only that path is removed, its parent only then.
  • _remove_a_tree retries only an os.unlink, os.remove or os.rmdir that failed, after ADDING the write bit (onexc from Python 3.12), never changes a symlink, and raises anything else. A clone that cannot be removed is named in a NOTE on stderr, inside contextlib.suppress(OSError, UnicodeError), so no traceback leaves main's finally.

• --help: plan --source; check --source and execute --source (SOURCE_OVERRIDE_HELP); and --work-dir on plan and check (_work_dir_help's new but, and CLONE_TARGET_HELD). Each code sits whole on one line at 80 columns.

The two new codes, source-ambiguous and plan-source-gone, are named in --help, and so in docs/cli.md. AGENTS.md names neither, and no registry lists codes; tests/test_agents_md_codes.py and tests/test_repo_hygiene.py ran in both modes.

Compatibility

• Plans written before this change have no source.cloned. They are read as false: their local_path is read in place while it exists, and once it is gone it is plan-source-gone, never cloned again.
• No released version clones a gone recorded clone again. That came with adopt-project.py and tests/conftest.py: a run without --work-dir removes the empty work directory it made, and a recorded clone that is gone is cloned again, so no empty openreposhape-adopt-* is left and no source-unclonable follows (#526) #594 (c972032), which is in neither v1.0.0 nor v1.0.1. So only plans plan wrote on unreleased main since 2026-10-16T01:10Z lose it. Their refusal, plan-source-gone, says to pass --source again: the clone's path, or the org/repo plan cloned from GitHub.
• The tool does not guess from the path's shape.
• A --source <org>/<repo> that is also a directory here was read as that directory. It is now refused as source-ambiguous. Write ./<org>/<repo> to read the directory.

Tests

tests/test_adopt_source_clone_record.py is new, with 50 cases. They run in process, with gh repo clone stood in for by a git clone of a repository on disk (gh_clones). The helpers are imported from tests/test_adopt_temp_work_roots.py and tests/test_adopt_plan_leg_path_help.py, not copied.

• Red on the base. The first 45 cases were run on 44512ab (main 2fac979 with adopt-project.py: a --work-dir that is a file or cannot be made ends plan, check and execute in a traceback, and --help says nothing of --work-dir or of where --org comes from #650) with only the new file added: 42 fail and 3 pass. The 3 are guards: the clone made again at the plan's own path is kept; a symlinked source-readonly leads elsewhere; a local source and a --work-dir marker are left alone. They pass on the base, where nothing is removed, and each fails with its guard reverted (below).
• Added in the review's fix round (5 cases), each failing with its own change reverted:
  • the work directory swapped for a symlink during the run (F1);
  • a plan whose report is cut short after it is written (F2);
  • a clone holding a directory nobody can read, and one holding a directory nobody can write in (F4);
  • execute's occupied refusal (N1).

Changed tests:

• tests/test_adopt_temp_work_roots.py: gone() follows the NOTE's new ending.
• tests/test_adopt_work_dir_refusal.py: the re-clone-order test's plan records cloned: true, since a path the person gave is never cloned again; and adopt-work-dir-occupied joins plan's and check's --work-dir codes.
• tests/test_adopt_template_values.py: six hand-edited local_path cases are now plan-source-gone, by the key, where they named a --source nobody passed. Their guards are kept: no traceback, no gh, exit 2, no leg.

Revert table, on cecc7e0. Each change was reverted alone, in its own scratch copy. Each run covered the new file, the three changed files and tests/test_cli_reference.py: 185 tests, all passing with the change. "Fails" counts the tests that fail with the change reverted; the test names are in the writer's report.

change reverted	fails
C1 source-ambiguous (a name that is also a path here is read as the path)	3 (plan, check, execute)
C2 a missing a/b/c goes to gh again	3 (incl. S8705's -u/x and --upload-pack=x/y cases)
C3 no normalisation, no url reading	12 (every spelling, the url control, the recorded testorg/Thing/, another host)
C4 a recorded name read through the current directory	2
C5 cloned: not written	16 (every re-clone test, D2's order test, #526's two)
C6 a person's moved path cloned again from its origin's name	5
C7 a gone path handed to Source.open again	14 (incl. the six template_values cases and the drive letter)
C8 _not_a_whole_clone answers "whole"	6
C9 no occupied-target question	3
C10 nothing removed	8
C11 a re-clone at the plan's path listed for removal	1
C12 no real-path guard at all	2 (the symlink there before the run, and the one put there during it)
C13 no read-only retry	1
F1 the first head's guard (islink of the clone and its parent)	1 (the work directory swapped during the run)
F2 the clone kept only when plan ends 0	1 (the report cut short)
F4a any failed function retried, os.open included	1 (the unreadable directory: a TypeError traceback)
F4b no NOTE	2
F4c the mode set to S_IWRITE rather than the bit added	1 (a directory loses read and search)
N1 execute's old way out	1
F6 plan-source-gone's old sentence	14
N4 the way out naming the recorded org/repo	6
C14 the NOTE's old words	2
C15 the help texts	12 (incl. test_cli_reference's 5)
C16 docs/cli.md not regenerated	5

Targeted runs, on cecc7e0 with dirty 0 (after the merge of main 66b230e). Flags: /usr/bin/python3 -m pytest, a stub gh that refuses everything, GH_TOKEN=bogus, an empty GH_CONFIG_DIR. The files: the 96 from grep -l -E 'adopt-project|adopt_project|\bADOPT\b' tests/*.py, which include test_agents_md_codes.py, test_repo_hygiene.py, test_shape_doctor.py and test_scaffold_leg_path_collisions.py, plus test_cli_reference.py. That is 97 files, in 4 shards per mode.

• Mode A (git-filter-repo on PATH): 6821 passed, 13 skipped, 1 xfailed, 0 failed.
• Mode B (PATH=stub:/usr/local/bin:/usr/bin:/bin, filter-repo hidden): 6446 passed, 388 skipped, 1 xfailed, 0 failed.

Windows

• CI is Linux only (ci: run the test suite on Linux only #597). Every path and name the new tests make is legal on NTFS. A url --source with a scheme, or in git's user@host: form, is only ever a string and never touches the file system. github.com/<o>/<r> with no scheme is also asked whether it is a path here, for source-ambiguous.
• Read-only files. Windows refuses to unlink a read-only file, and git writes a clone's packs read-only. _remove_a_tree makes such a file writable and retries. The test emulates Windows' refusal on Linux, and it fails with the retry reverted (C13).
• Paths. A drive-letter local_path is refused by its key on every platform. The symlink test skips where symlinks cannot be made.

Not in this PR

• A local --source that is a SUBDIRECTORY of a repository plans only that subtree (files: 1 of 3) and records the subdirectory. It goes on Tracking: adopt-project.py, converting an existing repository in place #457's checklist.
• execute keeps its own clone in a --work-dir it was given. A re-run given that directory is refused adopt-work-dir-occupied, by name, rather than with the gh remedy.

Known limits

• Only a clone plan made is asked whether it is whole: by --show-toplevel, and whether it still holds the plan's commit object. A clone with a damaged pack that still holds that commit is not asked further. That is git fsck's question, and a large source would pay for it on every run.
• www.github.com is read as another host (adopt-project.py: --source <org/repo> reads a directory of that name under the current one, a trailing / clones into source-readonly/ itself, and a recorded clone that is gone or emptied is refused for the wrong reason #652's review, N3; on Tracking: adopt-project.py, converting an existing repository in place #457's checklist).

Closes #652

🤖 Generated with Claude Code

[sourcery-ai]

Reviewer's Guide

The PR makes --source resolution spelling-driven and GitHub-name aware, persists whether a plan created its clone, safely recreates only damaged or missing plan-created clones, cleans up unrecorded transient clones, and updates tests and CLI documentation for the new behavior.

Sequence diagram for plan-created source recovery

sequenceDiagram
    participant Command
    participant Plan
    participant Source
    participant GitHub
    Command->>Plan: open_source(override, work_root)
    Plan->>Plan: _recorded_source(local_path)
    alt source.cloned is not true
        Plan-->>Command: plan-source-gone
    else clone is present and whole
        Plan->>Source: in_place(local_path)
        Source-->>Command: recorded source
    else clone is gone or not whole
        Plan->>Plan: _recorded_repository()
        Plan->>Source: clone(repository, work_root)
        Source->>GitHub: gh repo clone owner/repo
        GitHub-->>Source: source-readonly/repo
        Source-->>Command: recreated source
    end

Loading

Entity relationship diagram for persisted source provenance

erDiagram
    PLAN {
        string local_path
        string repository
        boolean cloned
        string commit
    }
    SOURCE_CLONE {
        string path
        string repository
        string commit
    }
    PLAN ||--o| SOURCE_CLONE : records

Loading

Flow diagram for --source resolution

flowchart TD
    A[--source spelling] --> B{Path spelling?}
    B -->|Yes| C[Read path in place]
    B -->|No| D{GitHub URL or github.com path?}
    D -->|Yes| E{Valid owner/repo?}
    E -->|No| F[source-unresolvable]
    E -->|Yes| G[Normalize to owner/repo]
    D -->|No| H{Valid owner/repo name?}
    H -->|No| I[Read existing path or refuse source-unresolvable]
    H -->|Yes| J{Also an existing path?}
    J -->|Yes| K[source-ambiguous]
    J -->|No| G
    G --> L[Source.clone]
    C --> M[Source.in_place]

Loading

Flow diagram for transient clone cleanup

flowchart TD
    A[Source.clone] --> B[Record clone in args.clones]
    B --> C{Command result}
    C -->|plan wrote a plan recording clone| D[Keep clone]
    C -->|plan wrote no plan| E[_leave_the_clones]
    C -->|check| E
    E --> F{Symlinked path?}
    F -->|Yes| G[Keep clone]
    F -->|No| H[_remove_a_tree]
    H --> I[Make read-only files writable]
    I --> J[Remove clone]

Loading

File-Level Changes

Change	Details	Files
Introduces deterministic parsing and normalization of --source values, distinguishing local paths, GitHub repository names, and supported GitHub URL/SCP spellings before filesystem or gh operations.	Adds _source_spec and _github_name parsing with path-first precedence and repository-name normalization. Rejects ambiguous path/repository spellings and unsupported hosts or malformed repository names with dedicated refusal codes. Routes all repository clones through a single target and validation path.	adopt-project.py tests/test_adopt_source_clone_record.py
Records clone provenance in plans and changes how recorded sources are reopened, so only clones created by plan can be automatically recreated.	Writes source.cloned and treats missing legacy values as false for compatibility. Always clones recorded repository names from GitHub rather than interpreting them through the current directory. Validates recorded clones as independent repositories containing the planned commit, recloning damaged or missing plan-created clones and refusing other missing paths as plan-source-gone. Preserves the plan's own work-directory clone behavior and reports occupied clone targets explicitly.	adopt-project.py tests/test_adopt_source_clone_record.py tests/test_adopt_temp_work_roots.py tests/test_adopt_template_values.py tests/test_adopt_work_dir_refusal.py
Adds lifecycle tracking and cleanup for transient source clones made by plan and check.	Tracks clone paths created during a run and removes unrecorded clones in main's cleanup path. Keeps clones recorded by a successful plan, execute clones, user-provided paths, symlink-reached targets, and the plan's recreated clone. Adds read-only-file retry handling for clone deletion, including Windows-style failures.	adopt-project.py tests/test_adopt_source_clone_record.py
Updates CLI guidance and generated documentation to describe source resolution, clone persistence, refusal codes, and work-directory behavior.	Expands --source and --work-dir help for plan, check, and execute. Documents source-ambiguous, plan-source-gone, and adopt-work-dir-occupied. Regenerates the corresponding CLI reference.	adopt-project.py docs/cli.md tests/test_adopt_source_clone_record.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#652	Interpret --source by its spelling rather than accidentally adopting a same-named current-directory path, and normalize GitHub repository spellings so trailing slashes clone into the repository-named directory.	✅
#652	Record whether the plan created the clone and use that record to handle missing or emptied clones appropriately, without treating a user-provided local path as a tool-created clone.	✅
#652	Remove clones that no plan records, including temporary clones created by execute.	❌	The PR removes unrecorded clones made by plan and check, but explicitly excludes execute: it lists no execute clone for cleanup and says execute keeps its clone. The issue specifically includes a fresh clone made by execute among the clones that should be removed.

Possibly linked issues

• Tracking: adopt-project.py, converting an existing repository in place #457: The PR implements the requested fixes, including recording source.cloned, correcting source-name handling, and removing unrecorded clones.

---

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.

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