[brettheap]

Lane: openreposhape-5 (openRepoShape-5)
Claim: #303 (comment)
Claim: #305 (comment)

Two ways check said plan ok to a source execute could not adopt, both reproduced on c7c02fa with the issues' own scripts.

#303, a symlink whose target is empty. A 120000 entry whose blob is the empty blob passed check, which never reads a link's target.

• With symlinks on (git's default where the disk can hold one), execute created both leg repositories, then failed in its first clone of the source: exit 2, nothing on stderr, two empty legs left behind. Linux refuses a symlink to nothing. This happened whatever the plan answered: docs/empty-link sent to spec, and a top-level empty-link answered root or drop.
• With core.symlinks=false, it said adoption verified. The spec leg held the empty link, a clone of that leg exited 128, and the assembly's recursive clone exited 1. The top-level link answered root or code verified the same way. Only drop gave an assembly that clones.

#305, the source's own project.yaml answered root. plan asked about it under ambiguous-top-level-yaml, whose question offers root. Answered root, check said plan ok. execute wrote the shape's manifest beside the source's file as shape/project.yaml, said "nothing was overwritten" and adoption verified. shape-doctor.py then said NOT A SHAPE ROOT (exit 2) and pointed at adopt-project.py plan. make bootstrap failed naming (exit 2), manifest (exit 1), pins (exit 2). Answered code or spec, the doctor said COMPLIANT and bootstrap ok.

What changed

• plan-empty-symlink (adopt-project.py check passes a source whose tree holds a symlink with an empty target, so with symlinks on execute creates both leg repositories and then fails cloning the source (on main with exit 2 and nothing on stderr, #171), and with core.symlinks=false it says adoption verified over a leg or root that no clone with symlinks on can check out #303). _empty_symlink_findings reports each 120000 row of size 0 in Source.tree(). The size ls-tree -l gives a symlink is the length of its target, so no target is read; a SHA-256 repository reports size 0 too.
  • It is listed right after 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's plan-unsafe-path, through _source_path_findings, on the line _entry_findings already had. So check prints it, and execute refuses it through _refuse_what_check_finds before any leg exists (adopt-project.py execute refuses only plan-unresolved and plan-stale, so a plan check rejects as uncovered or with a bad leg creates and pushes both legs before it fails verification #168).
  • EMPTY_SYMLINK_REMEDIATION is said once after the findings, in check and in execute's refusal. The fix is in the source: give the link a target, or remove it, commit, and re-run plan.
  • plan notes each such link in check's words, and still writes the plan.
• ambiguous-project-yaml (adopt-project.py check passes a plan that keeps the source's own project.yaml in the root, and execute writes the shape's manifest beside it as shape/project.yaml and says adoption verified, so shape-doctor.py calls the adopted assembly NOT A SHAPE ROOT and its first make bootstrap fails #305). A new rule in contracts/path-classification.yaml, above ambiguous-top-level-yaml, for the file project.yaml. Its question asks spec, code or drop, and says root is not an answer for this file. release.yaml keeps the old question.
• plan-root-blocks-manifest (adopt-project.py check passes a plan that keeps the source's own project.yaml in the root, and execute writes the shape's manifest beside it as shape/project.yaml and says adoption verified, so shape-doctor.py calls the adopted assembly NOT A SHAPE ROOT and its first make bootstrap fails #305). adopt-project.py: check finds, and execute refuses before any leg exists, a kept root path where the shape writes a directory or its shape/ copy, whether the disk keeps case or not; the materializer never writes over a copy (#262, #263) #313's machinery is extended, not copied: _shape_blocks, which _root_shape_findings runs over each disk, now refuses the root holding project.yaml outright, with no copy question after it. It fires for a kept row at that path (file or symlink), or a kept directory there, on a disk that keeps case or one that ignores it. The finding's remediation is adopt-project.py: check finds, and execute refuses before any leg exists, a kept root path where the shape writes a directory or its shape/ copy, whether the disk keeps case or not; the materializer never writes over a copy (#262, #263) #313's _fix_the_kept_path.
  • A submodule there stays plan-submodule-root's, said once.
  • _kept_there is the at-or-under lookup the copy branch already did, factored out for both.
  • execute refuses it before any leg exists, through the same list.
• Files. adopt-project.py (+205/-13), contracts/path-classification.yaml (+28), the two new test files (399 and 366 lines) and tests/test_adopt_root_shape_paths.py (+6/-2).

Decisions

• adopt-project.py check passes a source whose tree holds a symlink with an empty target, so with symlinks on execute creates both leg repositories and then fails cloning the source (on main with exit 2 and nothing on stderr, #171), and with core.symlinks=false it says adoption verified over a leg or root that no clone with symlinks on can check out #303 is refused whatever the plan answers, and whatever core.symlinks says.
  • Where symlinks are made, no answer adopts. The run fails at the first clone of the source, which checks the whole tree out before anything is taken out. Measured with the link in docs/ (sent to spec), at the top level answered root and drop, and with every path rooted or dropped and both legs seeded: there the seeded legs were pushed and the assembly's clone exited 128.
  • check cannot know where execute will run. A check that passed drop with symlinks off would pass a plan the next Linux machine cannot adopt, and the root's own validate workflow runs on ubuntu-latest.
  • The remediation costs one commit in the source.
• adopt-project.py check passes a plan that keeps the source's own project.yaml in the root, and execute writes the shape's manifest beside it as shape/project.yaml and says adoption verified, so shape-doctor.py calls the adopted assembly NOT A SHAPE ROOT and its first make bootstrap fails #305 covers the manifest only. The issue asked whether other rendered root paths need the same rule. Measured on c7c02fa, with the source's own file kept in the root at each of the 18 assembly_root_paths():
  • check passes all 18.
  • These verify over a broken assembly: contracts/spec-pin.yaml and contracts/code-pin.yaml (DRIFTED, pins fail); scripts/validate-pins.py, scripts/validate-manifest.py, scripts/repo_shape.py and contracts/repository-naming.yaml (INVALID); scripts/validate-repository-naming.py (COMPLIANT, naming fails); scripts/bootstrap.py (COMPLIANT, and make bootstrap runs the source's own script).
  • contracts/shape-pin.yaml fails verification after both legs exist.
  • README.md, AGENTS.md, CLAUDE.md, .gitignore, .gitattributes, AGENTS-shape.md and the workflow come out COMPLIANT with the copy beside them. Makefile is rooted by default, and the follow-up merge is its designed exit.
  • project.yaml is the one path plan's own question offered root for. The others are reached only by hand-editing a contracts/ or scripts/ answer to root. They are left for a follow-up issue (under Left out), not folded in here.
• A symlink at project.yaml is refused too. On c7c02fa:
  • a link to the source's own file verified and was NOT A SHAPE ROOT;
  • a link to nothing had the manifest written through it, and came out COMPLIANT on Linux. A clone that makes no symlinks holds that link as a file naming its target, so it is refused anyway, and materialize_assembly_root writes the shape files through a root-kept symlink to anywhere on disk, and crashes with a traceback on a link loop, after both legs are pushed #183 refuses a link to nothing at a shape path regardless;
  • a directory project.yaml/ verified and was NOT A SHAPE ROOT.
• A case twin Project.yaml kept in the root is refused, with the case aside. It adopts COMPLIANT on Linux. On a disk that ignores case, place writes the manifest beside it. This is the trade adopt-project.py accepts a leg mount path that collides with a directory the shape writes, such as --spec-path contracts, so the adoption fails after both legs are pushed (main: at the first bootstrap) #172 and adopt-project.py: check finds, and execute refuses before any leg exists, a kept root path where the shape writes a directory or its shape/ copy, whether the disk keeps case or not; the materializer never writes over a copy (#262, #263) #313 already make.

Evidence

• Reproductions, on this head (exits as printed; scripts and logs are in the lane's report):
  • adopt-project.py check passes a source whose tree holds a symlink with an empty target, so with symlinks on execute creates both leg repositories and then fails cloning the source (on main with exit 2 and nothing on stderr, #171), and with core.symlinks=false it says adoption verified over a leg or root that no clone with symlinks on can check out #303 run 1: check exit 1, one plan-empty-symlink finding; execute exit 2, REFUSED plan-empty-symlink, leg repositories left: empty.
  • adopt-project.py check passes a source whose tree holds a symlink with an empty target, so with symlinks on execute creates both leg repositories and then fails cloning the source (on main with exit 2 and nothing on stderr, #171), and with core.symlinks=false it says adoption verified over a leg or root that no clone with symlinks on can check out #303 run 2 (core.symlinks=false): the same finding and refusal; no leg, no verification.
  • Top-level empty-link, symlinks off and answered root, code or drop, and symlinks on and answered root or drop: each check exit 1, execute exit 2, no leg.
  • adopt-project.py check passes a plan that keeps the source's own project.yaml in the root, and execute writes the shape's manifest beside it as shape/project.yaml and says adoption verified, so shape-doctor.py calls the adopted assembly NOT A SHAPE ROOT and its first make bootstrap fails #305 root: check exit 1, one plan-root-blocks-manifest finding; execute exit 2, leg repositories: empty.
  • adopt-project.py check passes a plan that keeps the source's own project.yaml in the root, and execute writes the shape's manifest beside it as shape/project.yaml and says adoption verified, so shape-doctor.py calls the adopted assembly NOT A SHAPE ROOT and its first make bootstrap fails #305 code, spec and drop: plan ok, adoption verified, the root's project.yaml begins schema_version: 1, doctor COMPLIANT, bootstrap ok.
  • The plan's entry for project.yaml now reads rule: ambiguous-project-yaml, with no (root) in its question.
  • project.yaml as a link to a file, a link to nothing, a directory, and the twin Project.yaml: each check exit 1 and REFUSED plan-root-blocks-manifest.
  • No row needs real GitHub or a cloud tool.
• New tests. tests/test_adopt_empty_symlinks.py (28) and tests/test_adopt_root_manifest.py (27).
  • The symlinks are made with git update-index --cacheinfo, so no disk symlink is needed. The one test that checks a link out (a link given a target, end to end) is skipped on Windows by its marker, before it runs.
  • On c7c02fa: 37 failed, 18 passed. The 18 are the controls that must pass on both sides: a symlink with a target, the remediations adopting, project.yaml sent to a leg or dropped, a submodule there, other shape paths keeping their copy, and release.yaml's question.
• One existing test changed. test_a_file_kept_at_a_path_the_shape_writes_is_not_a_finding in tests/test_adopt_root_shape_paths.py held that a kept file at any shape path is no finding. It now holds that for every path but the manifest, which is plan-root-blocks-manifest.
• Mutation probes: 14 of 14 hunks reverted one at a time, each killed by at least one new test.
• Targeted runs. The adopt list and the doctor ran on a local state of this branch (7a22a21) whose files were this head's but for tests/test_adopt_root_shape_paths.py. That file was re-run on this head, so the adopt list is two runs, not one sum.
  • The 15 adopt files (test_adopt_empty_symlinks, _root_manifest, _root_shape_paths, _leg_path_collisions, _execute_refusals, _plan, _e2e, _submodules, _verify, _mount_ignored, _ignored_shape_files, _entry_paths, _finding_spelling, _history_gitlinks, _spec_only) on 7a22a21: 837 passed, 1 failed, 1 skipped (a MedxEHR clone the plan test needs). The one failure is the adopt-project.py: check finds, and execute refuses before any leg exists, a kept root path where the shape writes a directory or its shape/ copy, whether the disk keeps case or not; the materializer never writes over a copy (#262, #263) #313 test this head changes.
  • tests/test_adopt_root_shape_paths.py alone, on this head: 120 passed.
  • tests/test_shape_doctor.py, as its own stream: 242 passed, 3 skipped (PowerShell lines only a Windows host prints).
  • tests/test_scaffold_leg_path_collisions.py, tests/test_repo_hygiene.py and tests/test_cli_reference.py: 167 passed.
  • This head merged with origin/main at 87373a6, which brings tests/conftest.py's new git() identity: the two new files, tests/test_adopt_root_shape_paths.py and the three above, 342 passed.

Review

An independent opus review at 69c54c9 approved with nits: 0 blocker, 0 should, 8 nit. It reproduced every row of both issues on c7c02fa and on this head, and killed 6 of 6 mutants: two of the writer's re-run, four of its own. Its targeted runs on this head merged with origin/main ab623dd (git merge-tree clean, with #349's session gh guard in place; not re-run on 161c6c9):

• the new files, tests/test_adopt_root_shape_paths.py, tests/test_scaffold_leg_path_collisions.py, tests/test_adopt_execute_refusals.py, tests/test_repo_hygiene.py and tests/test_cli_reference.py: 379 passed;
• the other adopt files, in two streams: 303 passed, 1 skipped (the MedxEHR clone), and 323 passed;
• the clone-template, literal-names, template-values, plan-escapes, stdout-encoding and Windows-path tests, which cover adopt-project.py: the assembly root is cloned with no git template and the verification refuses a mount whose gitlink is not the commit pushed to its leg (adopt-mount-commit), so an operator's init.templateDir holding modules/spec and modules/code no longer ends adoption verified over a split nobody can clone (#243) #268 and adopt-project.py: a value execute writes into a file is asked whether a file can hold it, in plan, in check and in execute before any leg exists, so a byte that is not UTF-8 in --elected-by, --reference or a local --source directory no longer pushes both legs before write_lf raises (#255) #270: 266 passed, 2 skipped (an operator user.name set; Windows only);
• tests/test_shape_doctor.py: 254 passed, 3 skipped (PowerShell lines only a Windows host prints).

c7c02fa's own tests/test_adopt_root_shape_paths.py against this head's code gave 1 failed (the project.yaml row, :191) and 119 passed, so no other #313 behaviour changed.

• N1, a cross-lane composition. On the tree merged with lane 1's fix/adopt-root-kept-symlinks (materialize_assembly_root writes the shape files through a root-kept symlink to anywhere on disk, and crashes with a traceback on a link loop, after both legs are pushed #183, 6c44591), tests/test_adopt_root_symlinks.py::test_a_link_with_an_empty_target_is_fixed_in_the_source fails: AssertionError: assert 'plan-empty-symlink' == 'plan-root-symlink'. An empty link at or above a shape path is reported by both findings, and execute refuses with the first, which is this branch's. The two remediations agree (fix it in the source). Whichever of the two lands second removes the duplicate report. The same file also fails 3 other tests on origin/main with materialize_assembly_root writes the shape files through a root-kept symlink to anywhere on disk, and crashes with a traceback on a link loop, after both legs are pushed #183 and without this branch ([a-link-at-the-copy-itself] and test_the_materializer_refuses_before_it_writes, two cases), because adopt-project.py: check finds, and execute refuses before any leg exists, a kept root path where the shape writes a directory or its shape/ copy, whether the disk keeps case or not; the materializer never writes over a copy (#262, #263) #313's plan-root-blocks-shape-copy and materialize-copy-blocked answer first; those are not this branch's. Lane 1 has the note on materialize_assembly_root writes the shape files through a root-kept symlink to anywhere on disk, and crashes with a traceback on a link loop, after both legs are pushed #183.
• N2 and N3 are known nits, left for a later round.
  • N2: an empty link AT project.yaml (or at a adopt-project.py: check finds, and execute refuses before any leg exists, a kept root path where the shape writes a directory or its shape/ copy, whether the disk keeps case or not; the materializer never writes over a copy (#262, #263) #313 copy path) gets plan-root-blocks-manifest, whose fix offers drop, and plan-empty-symlink, which says drop is no fix.
  • N3: plan notes every empty link (25 links print 25 NOTEs), where check names 20 and counts the rest.
• N4 to N8 are smaller. N5 was the stale numbers in this body, corrected here. N6 (a symlink target that begins with a NUL byte passes check and fails like adopt-project.py check passes a source whose tree holds a symlink with an empty target, so with symlinks on execute creates both leg repositories and then fails cloning the source (on main with exit 2 and nothing on stderr, #171), and with core.symlinks=false it says adoption verified over a leg or root that no clone with symlinks on can check out #303) and N8 (the issue's _verify bullet) are follow-up issues. N7 is under Left out.

Merge-tree

git merge-tree --write-tree --name-only of this head (69c54c9), against heads fetched at 2026-10-12T15:14Z. It is a textual merge only; the semantic meeting with #183 was tested by the review (N1).

• origin/main: clean at 0f67f7b. That includes shape_materialize.py: render substitutes in one pass and refuses only a placeholder its table lacks, so --elected-by '{{SPEC_PATH}}' is no longer recorded as spec and {{NOPE}} no longer refuses after the legs are pushed (#260) #316 (34ecbc2), adopt-project.py: the assembly root is cloned with no git template and the verification refuses a mount whose gitlink is not the commit pushed to its leg (adopt-mount-commit), so an operator's init.templateDir holding modules/spec and modules/code no longer ends adoption verified over a split nobody can clone (#243) #268 (e43fa95), adopt-project.py: a value execute writes into a file is asked whether a file can hold it, in plan, in check and in execute before any leg exists, so a byte that is not UTF-8 in --elected-by, --reference or a local --source directory no longer pushes both legs before write_lf raises (#255) #270 (f795cf7) and adopt-project.py: a relative .gitmodules url the plan keeps in a leg is resolved from the source's remote and from the leg's, and where the two differ check finds it and execute refuses before any leg exists, so a recursive clone no longer fails after adoption verified (#190) #245 (161c6c9), which have landed since this branch was cut. It was clean at 161c6c9 and at ab623dd, the review's merge, too.
• Open PRs touching adopt-project.py: adopt-project.py: execute prints the command and its stderr when a leg cannot be built, so a git filter-repo that fails after both leg remotes exist no longer exits 2 with an empty stderr (#171) #184 (f416e13), adopt-project.py: _elector keeps a user.name byte that is not UTF-8 for #255's question, _remote_repository reads such an origin URL as no org/repo, and plan asks adopt-no-org before checked_value, so a Latin-1 name is refused as adopt-unwritable-value naming --elected-by, and plan, check and execute go on past such an origin, where both ended in a UnicodeDecodeError traceback (#292) #353 (dcbc37b), adopt-project.py: check finds, and execute refuses before any leg exists, a plan follow_ups: that is not a list of text and an elected_on: that election_date does not read, with or without a reference:, so follow_ups: 5 is no longer a traceback and elected_on: someday is no longer refused under a flag neither command takes (#293, #294) #356 (5a5011d), adopt-project.py, AGENTS.md: execute verifies before it exits on a refused gh pr create, and step 7 keys its way out to the exit it prints, so an IS pushed exit 2 is finished by hand, not re-run into a second pair of legs (#304) #371 (34b9500), shape_materialize.py: RULESET_HINT names the run's tracking branch where it named main, as the pull request's base and the ref the scaffold and the family holder pushed (#324) #373 (5ac03de), adopt-project.py: plan asks about every source path execute will not extract as it is named, with the reason and root or drop as its only answers, so -notes.md is no longer planned leg: spec for check to refuse, and #166's split question says the same of such an entry (#319) #377 (c35c896), adopt-project.py: _spelled writes a raw byte that is not UTF-8 as \udcNN and a character as \xNN, as the plan's own path: does, so the byte 0x85 and the character U+0085 no longer both read \x85, and 34 pairs of different names no longer read as one in a question or a finding (#329) #378 (2da8691), adopt-project.py: check reports the split branch an earlier run left as execute's adopt-branch-exists, and a branch in git's way of it as plan-split-branch-taken, which execute now refuses before any leg exists, so a source branch adopt no longer has both legs made before git filter-repo fails (#320) #382 (7e55d00) and adopt-project.py: check and execute spell a plan's hand-edited question: in plan-unresolved, its source: commit: in plan-stale and a submodule name in missing value for '<key>' with _spelled, so a line feed in any of them no longer forges a FINDING line and an ESC no longer reaches the terminal (#328) #384 (a96297e) are all clean. adopt-project.py: check finds, and execute refuses before any leg exists, a plan follow_ups: that is not a list of text and an elected_on: that election_date does not read, with or without a reference:, so follow_ups: 5 is no longer a traceback and elected_on: someday is no longer refused under a flag neither command takes (#293, #294) #356 and adopt-project.py: check reports the split branch an earlier run left as execute's adopt-branch-exists, and a branch in git's way of it as plan-split-branch-taken, which execute now refuses before any leg exists, so a source branch adopt no longer has both legs made before git filter-repo fails (#320) #382 conflict with origin/main alone (2 and 5 blocks, from adopt-project.py: a relative .gitmodules url the plan keeps in a leg is resolved from the source's remote and from the leg's, and where the two differ check finds it and execute refuses before any leg exists, so a recursive clone no longer fails after adoption verified (#190) #245's landing), not with this head.
• scaffold-project.py and adopt-project.py ask the project's YAML reader and validate-manifest.py about the manifest's values before anything exists, so --id null, --tracking-branch true and a blank --elected-by are refused (#258, #261) #314 (4b8da3d) is NOT clean: one block, in _entry_findings' docstring, where each side adds a paragraph after the same one (this head's "THEN THE SOURCE'S EMPTY SYMLINKS (adopt-project.py check passes a source whose tree holds a symlink with an empty target, so with symlinks on execute creates both leg repositories and then fails cloning the source (on main with exit 2 and nothing on stderr, #171), and with core.symlinks=false it says adoption verified over a leg or root that no clone with symlinks on can check out #303)" and scaffold-project.py and adopt-project.py ask the project's YAML reader and validate-manifest.py about the manifest's values before anything exists, so --id null, --tracking-branch true and a blank --elected-by are refused (#258, #261) #314's "A VALUE NO FILE CAN HOLD"). Keep both. It had been clean at f45edf4, and it has 3 blocks against origin/main alone since adopt-project.py: a relative .gitmodules url the plan keeps in a leg is resolved from the source's remote and from the leg's, and where the two differ check finds it and execute refuses before any leg exists, so a recursive clone no longer fails after adoption verified (#190) #245 landed, so it needs a merge of main in any case.
• Lane 1's branches without a PR: fix/adopt-late-failure-notice (9f1778d), fix/adopt-record-submodule-placement (70f4d29) and fix/adopt-plan-quote-yaml-keywords (d38e143) are clean. fix/adopt-plan-quote-yaml-keywords was 3 blocks against this head at e337f44, and conflicts with origin/main alone in 4.
  • fix/adopt-root-kept-symlinks (6c44591, materialize_assembly_root writes the shape files through a root-kept symlink to anywhere on disk, and crashes with a traceback on a link loop, after both legs are pushed #183) conflicts in 3 blocks of adopt-project.py: the module docstring's check paragraph, _entry_findings' docstring and its return line. They are the same 3 that c7c02fa itself has with that branch, and my one added docstring line sits inside the first. It has 5 blocks against origin/main alone.
• Lane 5's fix/adopt-pin-writes-pin-file (d806e8f): clean. docs/adopt-execute-exits is adopt-project.py, AGENTS.md: execute verifies before it exits on a refused gh pr create, and step 7 keys its way out to the exit it prints, so an IS pushed exit 2 is finished by hand, not re-run into a second pair of legs (#304) #371, above.
• When materialize_assembly_root writes the shape files through a root-kept symlink to anywhere on disk, and crashes with a traceback on a link loop, after both legs are pushed #183 lands, an empty symlink kept at or above a shape path is reported twice, by plan-empty-symlink and by materialize_assembly_root writes the shape files through a root-kept symlink to anywhere on disk, and crashes with a traceback on a link loop, after both legs are pushed #183's plan-root-symlink (N1). A dangling link kept at project.yaml is reported twice too, by plan-root-blocks-manifest and plan-root-symlink, and an empty one three times. Whichever lands second should keep one.

Left out

• _verify and the materializer do not themselves refuse a root project.yaml that is not the shape's manifest. This is the issue's second bullet. Once execute refuses the plan before any leg, through the same list check prints, nothing reaches them with one. It is a follow-up issue (N8).
• A top-level file named project.yaml only once case is ignored (Project.yaml) is still asked ambiguous-top-level-yaml's question, which offers root. check refuses that answer with the case aside, before any leg.
• adopt-project.py execute exits 2 with nothing on stderr when git filter-repo fails, after both leg remotes exist: _build_the_legs swallows CommandFailed on the premise that run already reported it, and run only raises #171 (a failed clone exits 2 silently) is lane 1's PR adopt-project.py: execute prints the command and its stderr when a leg cannot be built, so a git filter-repo that fails after both leg remotes exist no longer exits 2 with an empty stderr (#171) #184. This PR only keeps the empty-symlink run from reaching that clone.
• Follow-up issues proposed, not filed by this PR:
  • the source's own file kept in the root at one of the other shape paths the root's tools read (the pins, the validators, scripts/repo_shape.py, the naming policy, scripts/bootstrap.py, contracts/shape-pin.yaml), each measured above;
  • a symlink whose target begins with a NUL byte (\0spec.md, size 8), which plan-empty-symlink's size test does not see: it fails like adopt-project.py check passes a source whose tree holds a symlink with an empty target, so with symlinks on execute creates both leg repositories and then fails cloning the source (on main with exit 2 and nothing on stderr, #171), and with core.symlinks=false it says adoption verified over a leg or root that no clone with symlinks on can check out #303 (N6);
  • _verify asking whether the split's root project.yaml is the shape's manifest (N8);
  • an entry git cannot check out where execute runs, other than an empty symlink or a NUL-led one (a target longer than the platform allows, say), which is still found only by the first clone, after both legs exist. adopt-project.py check passes a source whose tree holds a symlink with an empty target, so with symlinks on execute creates both leg repositories and then fails cloning the source (on main with exit 2 and nothing on stderr, #171), and with core.symlinks=false it says adoption verified over a leg or root that no clone with symlinks on can check out #303 leaves this as a note.

Closes #303
Closes #305

🤖 Generated with Claude Code

Summary by Sourcery

Refuse adoption plans that contain empty source symlinks or keep the source's project.yaml in the assembly root, and guide users toward valid remediations.

Bug Fixes:

• Reject source symlinks with empty targets during plan validation and execution before any leg repositories are created.
• Prevent adoption plans from keeping the source's own project.yaml in the assembly root, avoiding invalid shape manifests.

Enhancements:

• Add dedicated path classification for project.yaml that directs it to a leg or drop instead of root.
• Extend root-shape collision detection and reporting to treat the assembly manifest as an uncopyable root path.
• Provide remediation messages and plan notes for empty symlinks and manifest-root conflicts.

Tests:

• Add comprehensive tests covering empty symlink detection, refusal timing, remediation, manifest classification, root conflicts, case variants, symlinks, directories, and successful alternatives.

[brettheap]

(lane openRepoShape-5, 2026-10-12T15:16Z) @codex review

[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.

[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.

[sourcery-ai]

Reviewer's Guide

The PR closes two adoption gaps: it detects and refuses empty-target source symlinks before any repositories are created, and it prevents a kept source project.yaml from displacing the assembly’s required root manifest by changing planning, collision findings, execution preflight, and comprehensive tests.

Sequence diagram for adoption preflight refusals

sequenceDiagram
    participant User
    participant Plan as adopt-project.py plan
    participant Check as adopt-project.py check
    participant Execute as adopt-project.py execute
    participant Source
    participant Legs as Leg repositories

    User->>Plan: plan
    Plan->>Source: tree()
    Source-->>Plan: empty symlink and project.yaml entries
    Plan-->>User: plan-empty-symlink NOTE
    Plan-->>User: ambiguous-project-yaml question without root
    User->>Check: check
    Check->>Source: tree()
    Check->>Check: _source_path_findings()
    Check->>Check: _shape_blocks()
    Check-->>User: plan-empty-symlink or plan-root-blocks-manifest
    User->>Execute: execute
    Execute->>Check: _refuse_what_check_finds()
    Check-->>Execute: refusal before leg creation
    Execute-->>User: REFUSED
    Note over Execute,Legs: No leg repositories are created

Loading

File-Level Changes

Change	Details	Files
Reject source symlinks with empty targets during planning validation and execution preflight.	Detect zero-size 120000 entries from Source.tree() without checking out the source. Add plan-empty-symlink findings and plan notes with source-remediation guidance. Route the finding through the existing pre-execution refusal path so no legs or clones are created. Add coverage for detection, ordering, remediation, plan answers, symlink settings, and end-to-end refusal.	adopt-project.py tests/test_adopt_empty_symlinks.py
Prevent the source’s own root project.yaml from conflicting with the generated shape manifest.	Add an ambiguous-project-yaml classification rule that permits only spec, code, or drop. Extend root-shape collision analysis with plan-root-blocks-manifest for files, symlinks, directories, and case variants at the manifest path. Reuse kept-path lookup logic and preserve submodule handling and existing copy behavior for other shape paths. Refuse invalid plans before leg creation and test compliant alternatives and diagnostics.	adopt-project.py contracts/path-classification.yaml tests/test_adopt_root_manifest.py tests/test_adopt_root_shape_paths.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#303	Detect tracked symlinks with empty targets from the source tree, independent of checkout configuration, and report them in plan and check with remediation.	✅
#303	Have execute refuse a source containing an empty-target symlink before creating any leg repositories, regardless of the plan's answer for that path.	✅
#305	Detect a plan that keeps the source's own project.yaml in the assembly root, and make check fail and execute refuse it before creating any leg repositories.	✅
#305	Change the planning question for a top-level project.yaml so it does not offer root as an answer.	✅
#305	Make verification independently reject an assembly whose root project.yaml is not the shape's manifest.	❌	The PR explicitly leaves _verify and the materializer without this check, relying on check and execute to block the problematic plan earlier. The issue lists verification refusal as a separate fix so adoption cannot be reported as verified over an invalid manifest.

Possibly linked issues

• adopt-project.py check passes a plan that keeps the source's own project.yaml in the root, and execute writes the shape's manifest beside it as shape/project.yaml and says adoption verified, so shape-doctor.py calls the adopted assembly NOT A SHAPE ROOT and its first make bootstrap fails #305: The PR adds a check finding and execute refusal for root-kept project.yaml, and changes its plan question to exclude root.
• adopt-project.py check passes a source whose tree holds a symlink with an empty target, so with symlinks on execute creates both leg repositories and then fails cloning the source (on main with exit 2 and nothing on stderr, #171), and with core.symlinks=false it says adoption verified over a leg or root that no clone with symlinks on can check out #303: The PR reports empty-target symlinks in plan/check and refuses execution before creating leg repositories, directly addressing the issue.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[brettheap]

(lane openRepoShape-3, 2026-10-12T19:53:10Z) A v1.0.0 scope notice. Brett Heap scoped openRepoShape's first release today: every procedure in AGENTS.md works end to end for ordinary repositories on Linux, macOS and Windows. The tag waits for every in-scope issue to close and a full test run to pass on all three OSes on the release commit. This PR closes #305 (P2, parent #457): in scope, in the v1.0.0 milestone. Nothing changes in how it lands. Known-limit issues stay open, without the milestone, under their area's parent.

[sonarqubecloud]

Quality Gate passed

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