[brettheap]

Lane: openreposhape-3 (openRepoShape-3)
Claim: #319 (comment)

What

• plan now asks entry_path_problem, the test check and execute have applied to an entry's path since adopt-project.py check accepts plan paths execute refuses as unsafe-value (a space or a non-ASCII character), so plan ok is followed by a refusal and #166's split instructions can name entries execute will refuse #196. ask_about_refused_paths runs after ask_about_submodules. Each entry the test refuses that is not answered root is written leg: null, review_required: true, confidence review, with the classifier's rule and reason kept.
• Its question: says where the rules put the path, or keeps the policy's own question first. It then says that execute will not extract the path into a leg as it is named, gives entry_path_problem's reason word for word, says root or drop is the only answer execute takes, and says that renaming the path in the source and re-running plan is how to get it into a leg.
• An entry that also holds a submodule is told drop is its only answer, because root is plan-submodule-root.
• adopt-project.py: a plan that sends .gitmodules to one leg and a submodule it registers to another passes check and execute, says adoption verified, and the assembly's recursive clone then fails: plan should ask, check should find, execute should refuse #166's split question (_asked_about) names each replacement entry the test refuses, with its reason and its answers (drop for a submodule). Past SPLIT_ENTRIES_NAMED of them it counts the rest.
• What the rules imply (follow-ups, predicted collisions, the seeding: record) is read with such an entry asked, because no answer puts it in a leg. A leg only that path fed is recorded as seeded, with the --allow-empty-leg warning, which matches what check says of the plan.
• _asked_about sets its question as written. Verdict collapsed each run of spaces, so a split naming src/a b.md wrote src/a b.md, an entry that covers nothing.
• check and execute are unchanged: no line of either is touched.
• adopt-project.py: plan's follow-up git grep takes a spec directory as its pattern and each code entry as a literal path, so a spec directory named -notes/ or a code entry named :cache/ no longer loses its follow-up, a code entry named */ no longer names a spec-leg file, a name outside ASCII is spelled instead of C-quoted, and a spec directory named -O<cmd>/ no longer runs a command (#216) #228's two tests of a spec directory that begins with - (test_each_file_that_names_a_spec_directory_is_a_follow_up[a-spec-directory-starting-with-a-dash] and test_a_spec_directory_named_like_the_pager_option_runs_nothing, in tests/test_adopt_literal_names.py) read leg: spec and the follow-up from the plan. plan now asks about such a directory and writes no follow-up for it, because no answer execute takes moves it to the spec leg. Each test now asserts the plan's question and that the plan names no file for it, and still asks adopt-project.py: plan's follow-up git grep takes a spec directory as its pattern and each code entry as a literal path, so a spec directory named -notes/ or a code entry named :cache/ no longer loses its follow-up, a code entry named */ no longer names a spec-leg file, a name outside ASCII is spelled instead of C-quoted, and a spec directory named -O<cmd>/ no longer runs a command (#216) #228's literal git grep of the rules' own answer spec, through cross_leg_references over walk's entries (as adopt-project.py: plan's follow-up git grep takes a spec directory as its pattern and each code entry as a literal path, so a spec directory named -notes/ or a code entry named :cache/ no longer loses its follow-up, a code entry named */ no longer names a spec-leg file, a name outside ASCII is spelled instead of C-quoted, and a spec directory named -O<cmd>/ no longer runs a command (#216) #228's line-feed test already does): the same follow-up, and, for the pager name, nothing run. Every other assertion is kept, the leg: spec one as the rules' answer. Dropping -e from the grep fails both tests (the pager test with git ran the pager); main's adopt-project.py fails both at the question.

Why

Measured on main ab623dd and head c35c896, with a driver that puts each name into a source's index (no checkout), runs plan, check and execute --yes --local-remote-dir, then answers the entry and runs check and execute again, each answer on a fresh source. git-filter-repo 2.47.0, git 2.43.0.

source path	main ab623dd: plan writes	main: check / execute as planned	head: plan writes	head: check / execute as planned	answered root / drop (main and head)
-notes.md	leg: spec, review_required: false, no question	exit 1 plan-unsafe-path / exit 2 REFUSED plan-unsafe-path, no remote	leg: null, review_required: true, question: "...because it begins with -... So root or drop is the only answer execute takes for it..."	exit 1 plan-unsafe-path (leg: null) + plan-unresolved / exit 2 REFUSED plan-unresolved, no remote	check 0, execute 0 adoption verified
notes\t.md	same as above	same	same, reason "the control character \t"	same	same
a\rb.md	same	same	same, reason "the control character \r"	same	same
a\nb.md	same	same	same, reason "a line feed (\n)..."	same	same
caf\xe9.md (not UTF-8)	same	same	same, reason "\xe9, which is not UTF-8"	same	same
a==>b.md	same	same	same, reason "==>..."	same	same
Icon\r	leg: null, the policy's question ("spec, code, or the assembly root?") and nothing more	exit 1 plan-unsafe-path + plan-unresolved / exit 2 REFUSED plan-unresolved	the policy's question, then "But execute will not extract this path... because it ends in a carriage return (\r)... would name Icon, another path. So root or drop..."	unchanged	same
src/a\nb.py beside submodule src/vendored (#166 split)	src/ asked; the split names `src/a\\nb.py` as an entry to write, with any leg:	plan-unresolved	the split question ends "Of those entries, execute will not extract src/a\nb.py into a leg as it is named, because it holds a line feed... so root or drop is the only answer for it."	unchanged	n/a

What the plan FILE shows, measured (the writer's escaping, repo_shape.double_quoted): the question spells a character as _spelled does, a backslash then a letter, and the file doubles that backslash. For Icon\r, path: "Icon\r" holds the carriage return, and the question line holds (`\\r`) and `Icon`. A line feed is `\\n`, and the byte 0xE9 is `\\xe9` in the question and "caf\udce9.md" in path:. Every line of the plan is printable, and each reads back as the question.

A source with no such path plans byte-identically, both the plan file and plan's report, diffed main ab623dd against head c35c896 for the synthetic tree, a source with a registered submodule, and one holding admitted names (My Notes.md, #notes.md, [ID].tsx, lead.md).

Where the issue is out of date: its body measured be2790e, where check exited 0 on -notes.md. On ab623dd, where #196 has landed, check already exits 1 with plan-unsafe-path and execute refuses before any leg. What was left was plan's answer and question, which is what this changes.

Tests

Targeted set on head c35c896, with git-filter-repo 2.47.0 on PATH:

• all 19 tests/test_adopt_*.py: 399 passed, 1 skipped and 1125 passed, 1 skipped (two runs). Skips: test_adopt_plan.py:393 needs a read-only clone of MedxSoft/MedxEHR (SHAPE_MEDXEHR_CLONE unset); test_adopt_template_values.py:223 skips where git config user.name is not read from GIT_CONFIG_GLOBAL on this host.
• tests/test_shape_doctor.py, tests/test_scaffold_leg_path_collisions.py and the four guards (test_repo_hygiene.py, test_cli_reference.py, test_git_output_decoding.py, test_stdout_encoding.py): 535 passed, 4 skipped. Skips: three PowerShell-line tests run only on a Windows host, and one about Windows' default stdout encoding.
• Nothing is skipped on an OS by this change. test_the_answers_it_offers_are_adopted_and_verified[notes\t.md-*] is POSIX only, because NTFS cannot hold a tab and execute checks the source out.

New, in tests/test_adopt_entry_paths.py:

• test_plan_asks_about_a_path_execute_refuses: eight names, each put into the index with no checkout. Checks the row, the exact question, the question line as the file writes it (pinned per name), the printed question, check's two findings, and execute's refusal before any leg.
• test_the_answer_the_question_offers_checks_ok: root and drop.
• test_a_leg_only_a_refused_path_fed_is_recorded_as_seeded.
• test_the_answers_it_offers_are_adopted_and_verified: -notes.md and notes\t.md, each answered root and drop, run plan → check ok → execute adoption verified, with the path in the root tree or nowhere. Needs git-filter-repo; notes\t.md is POSIX only, since NTFS cannot hold a tab and execute checks the source out.

New, in tests/test_adopt_submodules.py:

• the split question with a refused file and a refused submodule, and the edit it names checking ok;
• an orphan -dep told drop, with check unchanged for drop / root / code;
• a run of spaces kept in the split question;
• _refused_replacements unit cases, including past the cap.

Changed because plan now asks: three tests in test_adopt_entry_paths.py answer spec (or drop) for a leg: null entry, where plan used to write spec. test_adopt_plan_escapes.py's not-utf8 case now asks. #228's two tests in test_adopt_literal_names.py (see What) assert the question, and ask the literal git grep through cross_leg_references.

Run with head's four test files against main ab623dd's adopt-project.py: 32 failed, 130 passed, and the 32 are exactly the new or changed tests (four of them are _refused_replacements unit cases, which fail on main because it has no such function). All of them pass on head. Each fix was broken in a scratch copy, one at a time, and the tests caught every break: no asking in plan (12 failed), seeding read from ruled (1 failed), no split sentence (2 failed), no drop for a submodule (3 failed), Verdict's space folding restored (1 failed). Without -e in #228's grep, both changed #228 tests fail.

Composes with

git merge-tree --write-tree of each branch against head c35c896, at 14:29Z for lane 3 and 14:46Z for the others. Where a branch also touches adopt-project.py, its tests were run on a scratch merge commit.

PR	branch @ head	merge	tests on the scratch merge
#329	fix/adopt-spelled-unambiguous @ 2da8691 (local, rebased; origin has 7ef0804, also CLEAN)	CLEAN	test_adopt_entry_paths.py, test_adopt_plan_escapes.py, test_adopt_submodules.py, test_adopt_literal_names.py, test_adopt_spelled_unambiguous.py: 439 passed
#328	fix/adopt-spell-question-and-submodule @ a96297e	CLEAN	its own test file, test_adopt_entry_paths.py, test_adopt_plan_escapes.py, test_adopt_literal_names.py, and four split-question tests in test_adopt_submodules.py: 248 passed
#320	fix/adopt-refuse-existing-split-branch @ 7e55d00 (local)	CLEAN	test_adopt_split_branch.py, test_adopt_e2e.py: 43 passed
#373 (#324)	fix/ruleset-hint-tracking-branch @ 5ac03de	CLEAN	test_ruleset_hint_tracking_branch.py: 14 passed
#371	docs/adopt-execute-exits @ fcbf5c6	CLEAN
#356	fix/adopt-check-hand-edited-plan @ 5a5011d	CLEAN
#353	fix/adopt-git-reads-not-utf8 @ dcbc37b	CLEAN
#314	fix/scaffold-manifest-values @ 4b8da3d	CLEAN
#245	fix/adopt-relative-submodule-url @ a0272b2	CLEAN
#184	fix/adopt-report-filter-repo-failure @ f416e13	CLEAN

#329 respells a byte that is not UTF-8 (\udce9 for \xe9). This PR's not-UTF-8 question test derives that spelling from _spelled_character, so it passes on either side of #329.

Left out

• An entry the rules answer root whose path the test refuses stays root with no note, because check and execute accept it.
• adopt-project.py: plan's follow-up git grep takes a spec directory as its pattern and each code entry as a literal path, so a spec directory named -notes/ or a code entry named :cache/ no longer loses its follow-up, a code entry named */ no longer names a spec-leg file, a name outside ASCII is spelled instead of C-quoted, and a spec directory named -O<cmd>/ no longer runs a command (#216) #228's -e in the follow-up git grep now guards a name plan never searches for, since every spec directory that begins with - is asked. It stays as defence in depth, and the two tests above keep it tested.
• README and AGENTS.md are unchanged. AGENTS step 2 already says to answer each entry's question:, and the question now carries the narrower answer.

Closes #319

🤖 Generated with Claude Code

Summary by Sourcery

Ask users to resolve paths that execute cannot safely extract before producing adoption plans.

New Features:

• Make plan ask about source paths that execute cannot extract safely under their original names, including the reason and valid root or drop remediation choices.
• Extend split-entry questions to identify refused replacement paths and provide submodule-specific guidance.
• Record follow-ups, collision analysis, and seeded legs using the asked/refused path state.

Bug Fixes:

• Prevent plans from assigning unsafe paths to spec or code legs only for check and execute to reject later.
• Preserve exact path names, including repeated spaces, when naming split replacements in questions.
• Avoid generating follow-ups for unsafe spec-directory names that cannot be extracted into a leg.

Enhancements:

• Retain existing policy and submodule questions while appending path-safety explanations and remediation guidance.
• Keep classifier rules and reasons on refused entries while marking them unresolved for review.

Tests:

• Add coverage for unsafe path questions, remediation answers, seeded-leg behavior, split questions, submodule handling, escaping, and literal path names.
• Update affected adoption tests to validate the new plan questions and unchanged check/execute behavior.

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

[sourcery-ai]

Reviewer's Guide

Planning now mirrors execution's path-safety constraints: unsafe-as-named paths are explicitly reviewed instead of being assigned unusable legs, with precise remediation questions and downstream planning derived from the asked state. The PR adds broad regression coverage for path escaping, splits, submodules, seeding, literal names, and successful root/drop adoption while leaving check and execute unchanged.

Sequence diagram for planning an unsafe source path

sequenceDiagram
    participant Plan
    participant Classifier
    participant Safety as entry_path_problem
    participant Planner
    participant File as adoption-plan.yaml
    Plan->>Classifier: walk(policy, paths)
    Classifier-->>Plan: ruled entries
    Plan->>Safety: entry_path_problem(entry.path)
    Safety-->>Plan: reason or no problem
    Plan->>Planner: _refused_as_named(entry, problem, held)
    Planner-->>Plan: leg null, review_required, question
    Plan->>Planner: _predict_collisions(implied)
    Plan->>Planner: follow_ups_for(..., implied, ...)
    Plan->>Planner: seeded_legs(assigned_paths(implied))
    Plan->>File: render_plan(...)

Loading

State diagram for an unsafe-as-named plan entry

stateDiagram-v2
    [*] --> Classified
    Classified --> Asked: entry_path_problem(path)
    Asked --> Root: answer root
    Asked --> Drop: answer drop
    Asked --> Refused: answer spec or code
    Root --> Accepted: check and execute accept
    Drop --> Accepted: check and execute accept
    Refused --> Refused: plan-unsafe-path
    Asked --> Asked: rename source path and re-run plan
    Accepted --> [*]
    Refused --> [*]

Loading

Flow diagram for unsafe path planning and adoption

flowchart TD
    A[walk source paths] --> B[ask_about_refused_paths]
    B --> C{entry_path_problem?}
    C -->|no| D[keep classified entry]
    C -->|yes| E[_refused_as_named]
    E --> F[leg: null and review_required]
    F --> G[question explains reason and root/drop answers]
    G --> H[derive collisions, follow-ups, and seeded legs]
    H --> I[write adoption-plan.yaml]
    I --> J{answer}
    J -->|root| K[keep path in assembly root]
    J -->|drop| L[omit path]
    J -->|spec/code| M[check or execute refuses unsafe path]

Loading

File-Level Changes

Change	Details	Files
Make planning proactively ask about source paths that execution cannot extract under their original names.	Run path-safety classification during planning and preserve classifier rule/reason while writing leg: null, review-required entries. Generate questions explaining the exact refusal reason, valid root/drop remediation, submodule-specific drop behavior, and renaming guidance. Apply the same treatment to split replacement entries, including bounded naming, per-entry reasons, and preservation of repeated spaces. Use the asked entries when calculating collisions, follow-ups, and seeded legs so the plan reflects what execution can actually adopt. Integrate the new refusal pass after submodule handling without changing check or execute.	adopt-project.py
Add comprehensive coverage for refused-path planning, remediation, split questions, escaping, seeding, and execution outcomes.	Test refused names including leading dashes, control characters, line feeds, rename arrows, whitespace-only names, and non-UTF-8 bytes. Verify exact in-memory and serialized question text, plan metadata, check findings, and execution refusal behavior. Verify root and drop answers pass checks and complete adoption with the expected root-tree results. Cover submodule-only drop remediation, split-question naming limits, repeated-space preservation, and seeded-leg reporting.	tests/test_adopt_entry_paths.py tests/test_adopt_submodules.py tests/test_adopt_plan_escapes.py
Update literal-name follow-up tests to distinguish the rules' classification from paths that plan must ask about.	Assert dash-prefixed spec directories are recorded as asked with no planned follow-up. Continue validating literal git grep behavior through cross_leg_references using the rules' underlying spec classification. Retain pager-option and cross-leg reference regression coverage.	tests/test_adopt_literal_names.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#319	Have plan identify source-path entries that execute will refuse to extract as named, instead of assigning them a leg that cannot be executed.	✅
#319	For each such entry, write an unresolved, review-required plan entry whose question explains the refusal and offers the actionable root or drop choices.	✅

Possibly linked issues

• adopt-project.py plan writes leg: spec with no question for a source path that execute will refuse (-notes.md), so the answer check or execute then rejects is one plan chose for the person, and root or drop is offered for that entry nowhere #319: The PR directly addresses the issue: it marks refused paths unresolved and asks why, offering root or drop.

---

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-12T14:48:26Z) @codex review

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[sonarqubecloud]

Quality Gate passed

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