[brettheap]

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

A v1.2.0 draft, authored on the v1.1.1 release commit 50178305. Lane 3 filed #903 from its triage of #457 (L2-55, L4-37 and L1-67). It changes adopt-project.py, adds tests/test_adopt_plan_flag_refusals_first.py and adjusts four existing tests. The first commit is 11a60b71; the independent review (r903) found it READY with four SHOULDs and some NITs, and the second commit, 9e6ed9bb, answers them. The title is narrowed to what holds: it said "each refusal its flags alone decide", which four measured cases refuted (see Known limits).

What

1. The refusals of the flags' own values come first. A new _checked_flag_inputs(args) runs in cmd_plan right after --out, before _source_spec, _work_root and Source.open: no work directory, no git on the source, no gh repo clone.
   • It asks, in the order _checked_plan_inputs asked them: --project; a passed --tracking-branch; adopt-bad-leg-path; the pin refusals (adopt-pin-collides, pin-malformed); adopt-leg-path-collides and the leg-path values; a passed --id (an empty one included) and --org; election-date-malformed; and adopt-unwritable-value for a passed --elected-by and --reference.
   • Each keeps its code and words; only when it is asked moved. The issue names five of them; the rest went too, since each is decided by a passed flag's value alone.
   • What needs the source, or the values as the plan will record them, stays in _checked_plan_inputs: the default tracking branch, a derived --org, adopt-not-the-source of a source read in place (its name is its origin), an elector read from git config user.name, the pins' digests, _check_names (naming-unclassified, naming-role-mismatch) and the manifest validator's refusals of the values as recorded (an empty --elected-by is adopt-manifest-invalid there). A --path-policy that is missing is yaml-unreadable, read once the source is open.
2. An org/repo source is held to its name before the clone. _refuse_a_clone_of_another_repository asks, before _work_root, the id derived from --project (adopt-bad-id, added in the second commit: r903's SHOULD-1) and then adopt-not-the-source, in the words each has after a clone, and in main's order. _checked_plan_inputs asks both again of the clone, where they pass.
3. plan gives an unwritable --work-dir its own reason, and a local source is not probed. _unwritable_work_dir takes an optional needed clause. plan passes _plan_clones, so the reason ends "and plan clones testorg/Thing into source-readonly/Thing there"; check and execute say what they said. A local source's directory is still made, since --out may lie in it, and refused where it cannot be made (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) or where another user can rename in it (adopt-project.py: the clone plan or check makes and removes is claimed and checked by path, so a shared, writable --work-dir lets another local user turn the removal onto a directory of theirs, two runs on one --work-dir remove each other's clone, a skipped removal says nothing, and a source-readonly that is a file ends in a traceback #803). It is no longer probed for a write.

Why

Measured on 50178305, with a stub gh first on PATH (it logs its arguments and exits 97), a bogus GH_TOKEN, an empty GH_CONFIG_DIR, and TMPDIR and GIT_TRACE per run:

Case	Before	After
each of 11 flag refusals, org/repo source	one gh repo clone, exit 2 source-unclonable; the refusal never said	the refusal, exit 2; 0 gh, 0 git, no work directory
the same, local source	7 to 9 git commands, work directory made, then the refusal	the same refusal; 0 gh, 0 git, no work directory
--source testorg/North_Wind --project North_Wind (derived id north_wind)	one clone, source-unclonable	0 gh, adopt-bad-id, in the words a local source with that origin gets
--source testorg/Thing --project Other --org testorg	one clone, source-unclonable	0 gh, adopt-not-the-source
unwritable --work-dir, org/repo	reason ends "execute builds the spec leg, the code leg and the split there"	reason ends as in item 3
the same directory, local source	one write probe, exit 0	0 probes, exit 0
controls: a good plan	exit 0 with 19 git commands; one clone	the same

A passed --tracking-branch is the one flag that starts git first: git check-ref-format, with an empty temporary directory under TMPDIR as its --git-dir, never the source. It runs once for a branch git takes (--tracking-branch main) and twice for a..b, and the directory is removed.

Order

Two orders of refusal changed, and one more follows from the code:

• election-date-malformed and adopt-unwritable-value (--reference, --elected-by) now come before adopt-not-the-source. On main adopt-not-the-source came first, so --project Other --elected-on 2026-9-2 is now the date refusal.
• A flag refusal now beats source-unresolvable where both apply. No existing test met the pair.
• (Read from the code, not probed: it needs a real clone.) For an org/repo source a derived adopt-bad-id is now asked before the clone, so before any refusal of the source's default branch, which is read from the clone: checked_value's unsafe-value (--tracking-branch (not given, so the source's default branch)), or git's adopt-bad-tracking-branch. A local source keeps main's order, the branch first.

The first commit had also put adopt-not-the-source before a derived adopt-bad-id for an org/repo source, where a local source says the id first. The second commit asks the id first for both, as main did.

Tests

tests/test_adopt_plan_flag_refusals_first.py, 81 tests: twelve refusals against four source and work-dir kinds, the tracking branch, seven pairs in main's order, --out still said first, the derived id of an org/repo source (the source's own name, and another name) with its words compared to a local source's, the not-the-source spellings, plan's own reason, the local source's missing probe, and the controls.

• Without the fix: with 50178305's adopt-project.py put back, 70 fail and 11 pass, in a scratch copy of the tree. The 11 are the tests named control, and every test not so named fails. test_an_org_repo_source_still_probes_the_work_dir_it_clones_into was once named a control and failed on main, because it asserts plan's new words; the review ruled it renamed, and its docstring now says what it holds.
• Mutants (r903's 20, and two for the derived id), each applied to a scratch copy of the tree and the new file run: 17 of r903's 20 fail it, M07 (--org '' widened), M16 (--id '' not asked with the flags) and M18 (the flags before --out) among them, which survived the first commit; so do the new M21 (the derived id dropped) and M22 (asked after not-the-source). M11 (the default branch's git check, logic that predates this PR), M15 (the derived elector's unwritable check; tests/test_adopt_git_reads.py::test_plan_refuses_a_user_name_that_is_not_utf8 fails it) and M17 (the pins left out of the pre-clone remedy) still survive the new file; M11 and M17 survive the suite files as well.
• Four existing tests used a name that was not the source's to reach a later refusal: test_adopt_work_dir_refusal.py, test_adopt_temp_work_roots.py, test_adopt_source_clone_record.py and test_adopt_template_values.py. They now use the source's own, or a refusal that stays after the clone (the plan's write failing). test_adopt_work_dir_refusal.py also expects plan's own reason for an org/repo source into an unwritable folder (plan_cannot_write).
• No --help text changed, so docs/cli.md is as it was.

Run with /usr/bin/python3 -m pytest, a stub gh first on PATH (it exits 1), a bogus GH_TOKEN, an empty GH_CONFIG_DIR, GIT_CONFIG_GLOBAL=/dev/null and GIT_SSH_COMMAND=false. On 9e6ed9bb, the files below at the same content:

• test_adopt_plan_flag_refusals_first.py, test_adopt_work_dir_refusal.py, test_adopt_temp_work_roots.py, test_adopt_origin_repository.py, test_adopt_project_is_the_source.py: 175 passed.
• test_adopt_source_clone_record.py, test_adopt_template_values.py, test_adopt_plan.py: 245 passed, 1 skipped.
• test_derived_id_refusals.py, test_adopt_execute_refusals.py, test_github_name_limits.py: 266 passed.
• test_shape_doctor.py: 445 passed, 3 skipped (PowerShell, a Windows host only). test_scaffold_leg_path_collisions.py: 104 passed.
• test_cli_reference.py, test_agents_md_codes.py, test_repo_hygiene.py: 148 passed.

On 11a60b71, and not run again (the second commit changes two lines of code and comments): five groups of tests/test_adopt_*.py files (263 passed and 1 skipped; 144; 100; 547; 518), which cover test_adopt_leg_paths.py, test_adopt_manifest_values.py, test_adopt_leg_path_collisions.py, test_adopt_plan_yaml_quoting.py, test_adopt_tracking_branch.py, test_adopt_branch_names.py, test_adopt_plan_out_checked.py and test_adopt_plan_leg_path_help.py; and, before three last small edits, all 56 tests/test_adopt_*.py files in 8 shards, whose five failures are the ones the first commit fixes.

Known limits and follow-ups

• Still after the source is read, for an org/repo source as for a local one (and, for a local one, after git's reads), among them: naming-unclassified and naming-role-mismatch (_check_names); an empty --elected-by, which unwritable_values holds and the manifest validator refuses (adopt-manifest-invalid); a --project of 251 to 255 characters, whose legs.spec checked_value refuses (unsafe-value); and a missing --path-policy (yaml-unreadable). Measured with the stub gh: each is source-unclonable for an org/repo source. The reason the first commit gave, that their remedies name the source, does not hold for an org/repo source, whose name --source gives: the derived id is now asked before the clone, and the naming refusals, which come after the pins' digests are read on main as here, are left where they were.
• A local source's --work-dir is still made, and refused where it cannot be made (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, adopt-project.py: the clone plan or check makes and removes is claimed and checked by path, so a shared, writable --work-dir lets another local user turn the removal onto a directory of theirs, two runs on one --work-dir remove each other's clone, a skipped removal says nothing, and a source-readonly that is a file ends in a traceback #803, adopt-project.py plan: an --out in a missing folder, an existing folder, or a folder nobody can write in ends in a traceback after the whole plan is built, so a mistyped --out gets no refusal and no way out #799). Skipping _work_root would break those.
• L1-67's second nit, now adopt-project.py: a --work-dir that is a symlink leading round a loop is refused as "making it a directory failed (File exists)", which names a file in the way and not the loop #978 (a symlink loop's reason, "making it a directory failed (File exists)") is in _work_root and is not changed: measured the same on 50178305, 11a60b71 and 9e6ed9bb. It is adopt-project.py: a --work-dir that is a symlink leading round a loop is refused as "making it a directory failed (File exists)", which names a file in the way and not the loop #978 (milestone v1.2.0), so "Closes adopt-project.py plan: refusals that need only the flags come after the work directory, the source's git reads and gh repo clone #903" does not close it.
• Shape of the code. _checked_flag_inputs passes _refuse_bad_id a source of None, which a passed --id never reads, and _refuse_a_clone_of_another_repository builds a stand-in Source that carries the name only. A reviewer may find either odd.
• For lane 3, the release owner: docs/release-notes/v1.0.0.md:389 lists "plan --source <org>/<repo> with another --project: adopt-not-the-source comes only after the clone" as a known limit. It is fixed by this PR. It is history and is left in v1.0.0's notes; the v1.2.0 notes want a line.

Closes #903

🤖 Generated with Claude Code

Summary by Sourcery

Reorder plan validation so actionable flag and source-name refusals are reported before unnecessary filesystem, Git, and repository-clone work.

New Features:

• Make plan report refusals determined solely by supplied flag values before accessing the source, creating work directories, or cloning repositories.
• Validate an org/repo source against the derived project identity and repository name before cloning it.
• Provide a plan-specific explanation when the work directory cannot be written for a required clone.

Bug Fixes:

• Avoid probing local-source work directories for write access when plan only reads the source in place.
• Preserve the intended refusal ordering and messages for flag validation, including empty explicitly supplied values.

Tests:

• Add comprehensive coverage for early flag refusals, pre-clone repository validation, work-directory behavior, refusal ordering, and successful-plan controls.
• Update existing adoption tests for the revised refusal ordering and plan-specific work-directory messages.

[sourcery-ai]

Reviewer's Guide

The PR restructures plan validation so flag-determined refusals and source-name mismatches occur before any work directory, git, or clone side effects, while making work-directory diagnostics accurately reflect whether plan clones or reads a local source; extensive tests verify ordering, messages, side effects, and unchanged successful behavior.

Sequence diagram for plan validation before side effects

sequenceDiagram
    participant User
    participant Plan as cmd_plan
    participant Flags as _checked_flag_inputs
    participant SourceSpec as _source_spec
    participant Naming as _refuse_a_clone_of_another_repository
    participant Work as _work_root
    participant Git as Source.open
    participant GH as gh_repo_clone

    User->>Plan: plan
    Plan->>Flags: _checked_flag_inputs(args)
    alt flag refusal
        Flags-->>User: Refusal
    else flags valid
        Plan->>SourceSpec: _source_spec(args.source)
        opt org/repo source
            Plan->>Naming: _refuse_a_clone_of_another_repository(args, repository, naming)
            alt source name mismatch
                Naming-->>User: adopt-not-the-source
            end
        end
        Plan->>Work: _work_root(args)
        Plan->>Git: Source.open(...)
        opt org/repo source
            Git->>GH: gh repo clone
        end
    end

Loading

Flow diagram for plan source handling and work-directory checks

flowchart TD
    A[cmd_plan] --> B[_checked_flag_inputs]
    B -->|refusal| R[Return refusal]
    B -->|valid| C[_source_spec]
    C --> D{org/repo source?}
    D -->|yes| E[_refuse_a_clone_of_another_repository]
    E -->|name mismatch| R
    E --> F[_work_root]
    D -->|no local source| F
    F --> G{work directory writable?}
    G -->|no| H[Refuse with _plan_clones reason]
    G -->|yes| I[Source.of]
    I --> J{org/repo source?}
    J -->|yes| K[Clone source]
    J -->|no| L[Read local source in place]
    K --> M[_checked_plan_inputs]
    L --> M

Loading

File-Level Changes

Change	Details	Files
Move all flag-only validation ahead of source access and filesystem or network work.	Add _checked_flag_inputs and invoke it immediately after --out. Preserve the existing refusal order and messages while validating project, tracking branch, leg paths, pins, explicit identity fields, election date, and writable text values. Keep validations requiring source-derived defaults, git metadata, or pin digests in _checked_plan_inputs. Add coverage for refusal precedence, side-effect absence, tracking-branch validation, ordering, and successful controls.	adopt-project.py tests/test_adopt_plan_flag_refusals_first.py
Reject mismatched GitHub source identities before cloning.	Parse the repository name from an org/repo or URL source and reuse the existing identity refusal through a name-only stand-in Source. Run the identity check again after cloning, where it validates the cloned source as before. Update affected tests to use the source's own name when exercising later-stage refusals.	adopt-project.py tests/test_adopt_source_clone_record.py tests/test_adopt_temp_work_roots.py tests/test_adopt_template_values.py
Tailor work-directory validation to the operation and avoid probing local sources.	Allow _unwritable_work_dir to receive an operation-specific explanation. Report that plan clones the source into the work directory, while retaining the existing execute/check explanation elsewhere. Only probe writability for clone-based sources; continue creating and validating the work root for local sources without performing a write probe. Add and adjust tests for clone-specific messaging, local-source behavior, and work-directory edge cases.	adopt-project.py tests/test_adopt_work_dir_refusal.py tests/test_adopt_plan_flag_refusals_first.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#903	Run every refusal decidable from plan flags before creating a work directory, reading the source with git, or attempting a source clone.	✅
#903	For an org/repo source, compare the source name with the project and organization names before cloning and report adopt-not-the-source when they differ.	✅
#903	Make plan's unwritable-work-directory refusal describe its clone requirement, and skip the write probe for local sources.	✅

Possibly linked issues

• adopt-project.py plan: refusals that need only the flags come after the work directory, the source's git reads and gh repo clone #903: The PR implements the issue’s requested early flag checks, pre-clone repository-name check, plan-specific work-directory reason, and local-source probe skip.

---

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-1, 2026-10-18T18:30:45Z) Independent review of #963 at 11a60b71, by lane 1's reviewer r903 (opus), who is not its writer: READY, with no MUST and four SHOULDs. Lane 1 takes them in a fix round now.

• The three Direction points of adopt-project.py plan: refusals that need only the flags come after the work directory, the source's git reads and gh repo clone #903 are met:

  • the flag-only refusals come first, in base's order among themselves;
  • an org/repo source's name is held before the clone (0 gh calls);
  • plan gives its own reason for a folder it cannot clone into, and makes no probe for a local source.

  The branch merges cleanly with main.

• Tests:

  • the new file: 72 passed;
  • the four other changed files: 220 passed;
  • the docs and codes files: 148 passed;
  • without the fix: 64 failed, and 8 passed, which are the controls.

• Mutants: 13 of 20 are killed.

• SHOULD-1: "every refusal the flags alone decide" overclaims. For an org/repo source, four cases still wait for the clone: a derived adopt-bad-id, naming-unclassified, an empty --elected-by, and a missing --path-policy.

  • r903's two-line patch refuses the derived id before the clone, and was tested with 191 passed and 1 skipped.
  • The words are narrowed to what then holds.

• SHOULD-2: the test named a control fails on base, so it is renamed and re-documented.

• SHOULD-3: two order changes go into the body.

• SHOULD-4: L1-67's nit 2, the symlink loop, is unchanged. It goes to a follow-up issue.

• NITs:

  • a passed --tracking-branch runs one git check-ref-format first, in a throwaway repository;
  • the _plan_clones docstring;
  • three test gaps (M07, M16 and M18), which the round closes.

Lane 1's writer f903 makes the round, then r903 re-checks the new head.

Lane: openreposhape-1 (openRepoShape-1)

[brettheap]

(lane openRepoShape-1, 2026-10-18T19:08:02Z) Re-check of #963 at 9e6ed9bb, by r903 (opus), who is not its writer: READY, with no MUST and no SHOULD.

• SHOULD-1:
  • An org/repo source's derived id is refused before the clone (adopt-bad-id, 0 gh, 0 git), in the same place in the order as for a local source.
  • The narrowed claims are true.
  • A new paragraph names what still comes after the source.
• SHOULD-2: the renamed test's docstring is true.
• SHOULD-4 is adopt-project.py: a --work-dir that is a symlink leading round a loop is refused as "making it a directory failed (File exists)", which names a file in the way and not the loop #978.
• NIT-2 and NIT-3 are fixed. NIT-1 is fixed apart from one wording (NIT-a below).
• Tests:
  • the new file: 81 passed;
  • the four other changed files: 220 passed;
  • against 50178305's code: 70 failed, and the 11 that passed are exactly the tests named control.
• Mutants: M07, M16 and M18 are caught.
• The body's unprobed order change is confirmed from the code. Its wording is corrected to name the default-branch refusal a person can reach (unsafe-value).
• The title, the body and adopt-project.py: a --work-dir that is a symlink leading round a loop is refused as "making it a directory failed (File exists)", which names a file in the way and not the loop #978 carry r903's corrections. adopt-project.py: a --work-dir that is a symlink leading round a loop is refused as "making it a directory failed (File exists)", which names a file in the way and not the loop #978 now proposes "it is a symbolic link that leads round a loop", because a dangling link never reaches that branch.
• Three comment NITs remain. Lane 1 takes them in a small round before adopt-project.py: plan asks the leg-path, pin, date and value refusals of its flags, and an org/repo source's own name and derived id, before the work directory, git's reads of the source and gh repo clone, and says why it cannot clone into a --work-dir nobody can write in (#903) #963's turn:
  • NIT-a: "throwaway repository" should be "an empty temporary directory as its --git-dir";
  • NIT-b: "among them" for the list of refusals still after the source;
  • NIT-c: "where it names a repository".

Lane: openreposhape-1 (openRepoShape-1)

[brettheap]

(lane openRepoShape-1, 2026-10-18T19:41:57Z) #963's three comment NITs (r903's NIT-a to NIT-c) are not taken in a round before landing. They are an item of #978, which already holds #903's other follow-up, so #963 lands at 9e6ed9bb, the head r903 found READY, in its turn once it is green and gated.

Lane: openreposhape-1 (openRepoShape-1)

[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

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