[brettheap]

Closes #1014.

adopt-project.py plan now refuses a --project that no Windows disk can make a folder of (NUL, Con, com1, Lpt9, in any case). check finds the same name in a plan, and execute refuses it. All three use the one function the scaffold and family.py init already ask: shape_materialize.refuse_an_unholdable_name, from #1010 (e076e3e8). The two NITs from RV1010's review of #1010 are closed here too.

What changed

SHOULD-1, plan. _checked_flag_inputs now asks the question of --project as adopt-bad-project-name. It runs with the flags, so nothing exists yet: no work directory, no git in the source, no gh repo clone, no gh call and no plan file. On main, plan --project NUL wrote a plan (project NUL (nul) in acme, exit 0). Now:

REFUSED adopt-bad-project-name: --project is 'NUL', which names the assembly root and the folder `execute` clones it into, and `NUL` is a Windows device name (with or without an extension), which cannot be created there.
Remediation: no plan was written. Run `plan` again with another --project. It names the assembly root, and so the folder `execute` clones the root into and the folder every clone of it is made in; and a root is cloned on Windows too, where no file or folder can be called a device name (`CON`, `PRN`, `AUX`, `NUL`, `COM1`-`COM9`, `LPT1`-`LPT9`, in any case, with or without an extension), and a name ending in a dot or a space is made under another name. Where --project is the source's own name, it cannot be changed here: an in-place adoption keeps the source's own name, and whether to rename the source is a human's decision, made first on GitHub (`gh repo rename`); then run `plan` again against the renamed repository, with its new name as --project.

SHOULD-1, check and execute. The question is now the first one in _what_cannot_be_held. That is the one list execute refuses the first entry of (_repository_urls) and check reports every entry of (_held_findings, #863). It is asked of the plan's legs.assembly, under the same code, both on GitHub and under --local-remote-dir. The code joins RENAMES_THE_LEGS, so check asks gh nothing about the legs of a name that has to change. On main, check of a plan for NUL printed plan ok, exit 0, after gh repo view acme/NUL-spec and acme/NUL-code. Now it gives one finding, FINDING adopt-bad-project-name: <plan>: legs.assembly is 'NUL', ..., exit 1, and the stub gh logs nothing.

NIT-1. "nul\n" is added to @pytest.mark.parametrize("passed", ...) of test_a_name_no_root_can_have_on_windows_speaks_before_a_passed_id in tests/test_derived_id_refusals.py. The row's asserts are unchanged; its docstring says what the row holds. It kills RV1010's mutant C (see Mutants).

NIT-2. "whatever the id" now reads "whatever id is passed" in _refuse_an_unholdable_project_name's docstring (scaffold-project.py) and in the docstring of test_a_name_the_policy_refuses_too_is_refused_by_the_policy (tests/test_scaffold_device_names.py). These are comments only.

Measured with a stub gh (logs, exit 97), GH_TOKEN=bogus, an empty GH_CONFIG_DIR and GIT_SSH_COMMAND=false, on a one-commit local source:

--project	plan at main	plan at head	check (main's plan) at main	check (main's plan) at head
NUL, Con, com1, Lpt9	exit 0, plan written, 0 gh calls	exit 2 adopt-bad-project-name, no plan, 0 gh calls	exit 0 plan ok, 2 repo view calls	exit 1, one FINDING adopt-bad-project-name, 0 gh calls, --work-dir empty
Nullable, Console, Auxo	exit 0	exit 0	exit 0 plan ok	exit 0 plan ok (2 repo view calls, as at main)

Decisions the Direction left open

1. The code is adopt-bad-project-name. It is one code for plan, check and execute, as adopt-name-too-long and adopt-bad-org are.
2. Where plan asks it. It is asked in _checked_flag_inputs, right before a passed --id's question, and only where the naming policy holds the three names --project makes (_names_held, the gate the passed-id question already used).
   • adopt's naming refusal is asked after the source is read, because its remedy names the source. So the gate is how "the naming refusal first" is kept without reading the source.
   • A name the policy refuses too keeps its refusal from main. With an --id, NUL.git and Nul. are naming-unclassified. With no --id, they are adopt-bad-id for the derived id, as the scaffold says scaffold-bad-id.
   • The order is then: the naming refusal, then this one, then a passed --id's sentence (foo_bar, '', and nul with a line break).
   • The leg-path, --pin and collision refusals of _checked_flag_inputs still come before it, as they do in the scaffold.
3. check and execute ask it of legs.assembly, not project:.
   • execute clones the root into <work-dir>/<legs.assembly>.
   • Every name in _what_cannot_be_held comes from legs:.
   • project: names no folder; only _not_the_source reads it.
   • A plan that plan wrote holds the same value in both, so "a plan whose project: is NUL" is found.
4. It is first in the list, before the names' lengths. It is asked under --local-remote-dir too, because a root is cloned there as well.
5. One remedy for all three subcommands. plan starts it with "no plan was written." (PLAN_NOT_WRITTEN); check and execute start it with "no repository was created.", as ORG_REMEDIATION does. plan asks before it reads the source, so it cannot yet tell whether --project is the source's own name. The remedy therefore gives both ways out: another --project, or, in place, the rename first, in _rename_first's words.
6. Docs. adopt-project.py's --help is unchanged, as the scaffold's --project help was in scaffold-project.py, family.py and shape_materialize.py: the scaffold refuses a --project no Windows disk can make a folder of, by the one question init asks of --family, and the five folder flags' --help say what an empty value and . mean (#989, part of #999) #1010, so docs/cli.md is unchanged. AGENTS.md, the README and the handbook name no adopt-* or scaffold-bad-project-name code, so they are unchanged too. The module docstring gains one sentence.

Left out of scope

• The issue has no "Needs a ruling" or "Documented limit" section.
• RV1010's NIT-3 (scaffold-project.py asks _refuse_a_name_no_root_can_have twice) is not part of adopt-project.py: plan and check take a Windows device name (--project NUL, Con) that the scaffold and family.py init now refuse #1014 and is unchanged.
• There is no end-to-end execute run. The issue's Verify does not ask for one, and execute's refusal is held in process through _repository_urls, which cmd_execute calls right after _check_names.

Tests

Each test file was run alone under the stub gh (exit 97), with GH_TOKEN=bogus, an empty GH_CONFIG_DIR, GIT_SSH_COMMAND=false and EMAIL=tests@openreposhape.invalid. The command was /usr/bin/python3 -m pytest -q -p no:cacheprovider --basetemp=<scratch>/bt-<name> -o tmp_path_retention_policy=failed tests/<file>. They ran at 13fd52e93 (on e2f9fc424). It was then rebased onto 5b41d44fc, which changes only templates/family-root/scripts/validate-family.py and its test; the rows marked "after the rebase" ran at the head.

File	Result
tests/test_adopt_device_names.py (new)	44 passed in 13.20s
the same file against origin/main's code (the rows must fail there)	31 failed, 13 passed: every device row fails; the 9 control rows and the 4 naming-first rows pass
tests/test_derived_id_refusals.py	63 passed in 10.51s
tests/test_scaffold_device_names.py	48 passed in 12.85s
tests/test_adopt_plan_flag_refusals_first.py	89 passed in 28.93s
tests/test_github_limits_init_check_org.py	95 passed in 26.32s
tests/test_github_name_limits.py	64 passed in 22.91s
tests/test_adopt_leg_paths.py	351 passed in 64.78s
tests/test_scaffold_leg_path_collisions.py	104 passed in 3.73s
tests/test_agents_md_codes.py	47 passed in 1.96s
tests/test_cli_reference.py	23 passed in 28.97s
tests/test_update_add_codes_documented.py	6 passed in 0.47s
tests/test_repo_hygiene.py	100 passed in 2.49s
tests/test_no_auto_maintenance.py	60 passed in 11.77s
tests/test_shape_doctor.py (after the rebase)	445 passed, 3 skipped in 641.11s (0:10:41)
tests/test_adopt_device_names.py (after the rebase)	44 passed in 14.53s
tests/test_repo_hygiene.py (after the rebase)	100 passed in 2.42s

pyflakes gives the same count on the four changed files as on main (1, which predates this change). No added line is over 79 characters.

Mutants

Each mutant changed one hunk in a separate worktree of the commit. The file was then restored with git checkout and checked by sha256 (OK every time).

Mutant	Killed by
M1: plan does not ask the question	19 failed: all 16 test_plan_refuses_a_device_name_before_anything_exists rows and 3 test_plan_says_the_name_before_a_passed_id rows
M2: plan asks it after a passed --id's question	2 failed: test_plan_says_the_name_before_a_passed_id[foo_bar] and []
M3: plan asks it without the _names_held gate	4 failed: test_plan_leaves_a_name_the_policy_refuses_to_the_policy (NUL.git, Nul. with --id foo and foo_bar)
M4: plan asks it after the source is read (after _check_names in _checked_plan_inputs)	19 failed: the same rows as M1 (git ran, the work directory was made)
M5: _what_cannot_be_held does not ask it	12 failed: 4 test_check_finds_a_device_name_and_asks_gh_nothing and 8 test_execute_refuses_it_first_of_the_list_check_reads
M6: the code is not in RENAMES_THE_LEGS	12 failed: the 4 check rows (assert ['repo view t...ameWithOwner'] == []) and the 8 list rows
M7: the list asks it only without --local-remote-dir	4 failed: test_execute_refuses_it_first_of_the_list_check_reads[*-local]
M8: RV1010's mutant C (the scaffold's device question moved after checked_value("--id"))	1 failed: test_a_name_no_root_can_have_on_windows_speaks_before_a_passed_id[nul\n] (REFUSED unsafe-value: --id is 'nul\n')

Merges

git merge-tree --write-tree of the head ce53b0b4f3ecc22f5686b438b523614c8e9243a8:

With	Result
origin/main 5b41d44fc	clean, tree 535279bb (the head's own tree)
#1031 abd1b9844 (fix/910-check-throwaway-repos, touches adopt-project.py)	clean, tree 9e4988f4
#1030 18cc65939 (fix/900-spelled-names, touches adopt-project.py)	clean, tree 89b24784

No other open PR (7 open) touches adopt-project.py, scaffold-project.py or the three test files.

Fix round 1 (RV1041)

RV1041 (independent review at ce53b0b4f): READY, no MUST, no SHOULD, one NIT.

• NIT-1 (decision 4, "first in the list"): its mutant R1, which moves the device question to the end of _what_cannot_be_held, survived both test files, because the test named "first of the list" only asserted [CODE]. c0ccf755f adds test_the_device_question_comes_before_the_organisations in tests/test_adopt_device_names.py: a 40-character org:, not local, and legs.assembly NUL give the codes [adopt-bad-project-name, adopt-org-too-long], in that order. Only that test file changed; adopt-project.py is untouched.
• R1 now: 1 failed (the new row, ['adopt-org-too-long', 'adopt-bad-project-name'] != [CODE, 'adopt-org-too-long']), 44 passed. adopt-project.py was restored and its sha256 matched (e6cf9639...).
• Tests at c0ccf755f, each file alone, same stub setup: test_adopt_device_names.py 45 passed, test_adopt_plan_flag_refusals_first.py 89 passed, test_no_auto_maintenance.py 60 passed.

Lane: openreposhape-3 (openRepoShape-3)
🤖 Generated with Claude Code

Summary by Sourcery

Refuse Windows device names as adoption project roots before any artifacts or repositories are created, and report the same validation consistently during plan, check, and execute.

New Features:

• Reject Windows device names used as adoption project roots during planning, checking, and execution.

Bug Fixes:

• Prevent invalid project names from producing plans, repository lookups, or repositories that cannot be created on Windows.
• Ensure checks identify invalid assembly-root names before querying GitHub or validating dependent leg repositories.

Enhancements:

• Use a shared project-name refusal across adoption workflows and align it with the existing scaffold and family initialization naming policy.

Tests:

• Add coverage for device-name refusals, validation ordering, GitHub/local execution paths, and valid prefix-matching names.

[sourcery-ai]

Reviewer's Guide

This PR consistently rejects Windows device-name project roots as adopt-bad-project-name: plan validates --project before any side effects, while check and execute validate legs.assembly through their shared refusal list before GitHub queries or repository creation. It adds comprehensive regression tests for refusal ordering, local and GitHub execution paths, valid near-matches, and scaffold behavior.

Sequence diagram for project-name validation across adopt commands

sequenceDiagram
    actor User
    participant Adopt as adopt-project.py
    participant Policy as Naming policy
    participant Shape as shape_materialize
    participant GitHub as gh
    participant FS as Filesystem

    User->>Adopt: plan --project NUL
    Adopt->>Policy: _names_held(project, pins)
    Policy-->>Adopt: true
    Adopt->>Shape: refuse_an_unholdable_name(adopt-bad-project-name)
    Shape-->>Adopt: refusal
    Adopt-->>User: REFUSED adopt-bad-project-name
    Note over Adopt,FS: No source read, gh call, work directory, or plan file

    User->>Adopt: check plan
    Adopt->>Adopt: _what_cannot_be_held(legs.assembly)
    Adopt->>Shape: refuse_an_unholdable_name(adopt-bad-project-name)
    Shape-->>Adopt: refusal
    Adopt-->>User: FINDING adopt-bad-project-name
    Note over Adopt,GitHub: No gh repo view calls

    User->>Adopt: execute plan
    Adopt->>Adopt: _what_cannot_be_held(legs.assembly)
    Adopt->>Shape: refuse_an_unholdable_name(adopt-bad-project-name)
    Shape-->>Adopt: refusal
    Adopt-->>User: REFUSED adopt-bad-project-name
    Note over Adopt,FS: No repository is created

Loading

Flow diagram for shared assembly-root refusal handling

flowchart TD
    A[Project root enters command] --> B{Command}
    B -->|plan --project| C[_names_held]
    C --> D[refuse_an_unholdable_name]
    D --> E{Windows device name?}
    E -->|yes| F[adopt-bad-project-name]
    F --> G[No plan written]
    E -->|no| H[Continue plan validation]

    B -->|check or execute| I[Read legs.assembly]
    I --> J[_what_cannot_be_held]
    J --> D
    F --> K{Command result}
    K -->|check| L[Finding reported; skip GitHub leg queries]
    K -->|execute| M[Refuse before repository creation]

Loading

File-Level Changes

Change	Details	Files
Added a shared project-name refusal for Windows device names and wired it into adoption planning before any side effects.	Reuse shape_materialize.refuse_an_unholdable_name with the new adopt-bad-project-name code and common remediation text. Validate held --project names in _checked_flag_inputs before source access, work-directory creation, Git, GitHub, or plan writing. Preserve refusal ordering relative to naming-policy and passed-ID validation, including names rejected by the naming policy.	adopt-project.py
Extended plan validation findings so existing plans reject invalid assembly roots consistently during checking and execution.	Check legs.assembly as the first item in _what_cannot_be_held, including local-remote execution. Add the new code to RENAMES_THE_LEGS so check avoids GitHub leg lookups when the root must be renamed. Make execute refuse before repository creation while check reports the finding.	adopt-project.py
Added regression coverage for device-name handling and refusal precedence across adoption workflows.	Test NUL, Con, com1, and Lpt9 across local and cloned sources, with no side effects or GitHub calls. Test check and execute behavior for GitHub and local remote layouts, plus valid control names. Cover refusal ordering before invalid IDs and update scaffold-related mutation coverage.	tests/test_adopt_device_names.py tests/test_derived_id_refusals.py
Clarified existing scaffold test and implementation documentation for passed-ID terminology.	Update docstrings from “whatever the id” to “whatever id is passed.”	scaffold-project.py tests/test_scaffold_device_names.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#1014	Have adopt-project.py plan refuse Windows-unholdable --project names using the shared refusal function, before creating anything, while preserving naming-policy refusal order.	✅
#1014	Have adopt-project.py check find a Windows-unholdable name in the plan’s project: field.	❌	The PR checks legs.assembly, not project:. Plans produced by plan ordinarily carry the same value in both fields, but a plan with an unholdable project: and a different legs.assembly will not be caught on that basis. The issue explicitly asks check to inspect project:.
#1014	Close the two review nits by adding the nul\n test row and correcting the two docstrings’ wording about passed IDs.	✅

Possibly linked issues

• adopt-project.py: plan and check take a Windows device name (--project NUL, Con) that the scaffold and family.py init now refuse #1014: The PR adds the shared name check to plan and check/execute, and includes the requested test row and wording fixes.

---

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-3, 2026-10-20T05:49:06Z) RV1041 (independent opus review, ruling 8) of #1041 at ce53b0b: READY. No MUST, no SHOULD, one NIT.

Probes (stub gh exit 97, GH_TOKEN=bogus, empty GH_CONFIG_DIR, GIT_SSH_COMMAND=false), main 5b41d44 vs head:

• plan --project NUL, Con, com1, Lpt9 (with and without --id foo): main exit 0 and a plan; head exit 2 adopt-bad-project-name, no plan, no work dir, 0 gh calls.
• check of main's plans for those four: main exit 0 plan ok (2 repo view calls on GitHub); head exit 1, one FINDING adopt-bad-project-name, 0 gh calls, on GitHub and under --local-remote-dir.
• NUL.git and Nul.: plan and check are byte-identical to main (adopt-bad-id / naming-unclassified; check finds naming-unclassified only).
• Nullable, Console, Auxo: plan and check byte-identical to main (exit 0, plan ok).
• 60 outputs compared: only the 24 device rows differ.
• execute of main's NUL plan at head: exit 2 adopt-bad-project-name, 0 gh calls, nothing made, both modes. At main under --local-remote-dir it made NUL/, NUL-spec.git and NUL-code.git (exit 0).

Decisions: all agreed. legs.assembly over project: is right: project: is read only by _not_the_source (adopt-project.py:15817). A hand edit with project: NUL and legs.assembly: Zqxj passes check, but nothing named NUL is ever made. The _names_held gate keeps naming first (M3 killed: 4 rows).

Tests at head, one file at a time: test_adopt_device_names 44, test_derived_id_refusals 63, test_adopt_plan_flag_refusals_first 89, test_scaffold_device_names 48, test_scaffold_leg_path_collisions 104, test_agents_md_codes 47, test_cli_reference 23, test_update_add_codes_documented 6, test_repo_hygiene 100, test_no_auto_maintenance 60, all passed. The docs guards need no doc: neither requires a new adopt-* code to be documented.

Mutants: M3 killed (4), M6 killed (12). Mine, R1 (the device question moved last in _what_cannot_be_held), survives: see NIT-1.

NIT-1 (tests/test_adopt_device_names.py:236): decision 4, "first in the list", is held by no test. With org "a"*40 and legs.assembly NUL the list is [adopt-bad-project-name, adopt-org-too-long] at head and the reverse under R1. Fix: one row with a 40-character org asserting that order.

Merges (git merge-tree --write-tree): origin/main 5b41d44 clean (tree 535279bb), #1038 3d52f86 clean, #1031 abd1b98 clean, #1030 18cc659 clean; test_adopt_device_names gives 44 passed on each predicted merge.

Lane: openreposhape-3 (openRepoShape-3)

[brettheap]

(lane openRepoShape-3, 2026-10-20T05:52:22Z) F1041 (fix round 1 for RV1041, READY with one NIT) of #1041: NIT-1 is closed at c0ccf75.

NIT-1 (decision 4, "first in the list" was held by no test): tests/test_adopt_device_names.py gains test_the_device_question_comes_before_the_organisations. It calls _what_cannot_be_held with org "a"*40, not local, and legs.assembly NUL, and asserts the codes are exactly [adopt-bad-project-name, adopt-org-too-long], in that order. Only that test file changed (10 lines added); adopt-project.py is untouched.

RV1041's mutant R1 (the device question moved to the end of _what_cannot_be_held) now fails: 1 failed (the new row, ['adopt-org-too-long', 'adopt-bad-project-name'] != [adopt-bad-project-name, adopt-org-too-long]), 44 passed. adopt-project.py was restored and its sha256 matched (e6cf9639...).

Tests at c0ccf75, each file alone under the stub gh (exit 97), GH_TOKEN=bogus, an empty GH_CONFIG_DIR, GIT_SSH_COMMAND=false and EMAIL set: test_adopt_device_names.py 45 passed, test_adopt_plan_flag_refusals_first.py 89 passed, test_no_auto_maintenance.py 60 passed.

The PR body gains a "Fix round 1 (RV1041)" section; the rest is kept. The PR is still a DRAFT. Lane 3's coordinator checked the 10-line diff against RV1041's suggested row, so no second review round is needed.

Lane: openreposhape-3 (openRepoShape-3)

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