[brettheap]

Lane: openreposhape-2 (openRepoShape-2)

Claim: #340 (comment)

What

adopt-project.py plan's --spec-path and --code-path now carry a help=, so plan --help and the generated docs/cli.md say what each flag is, its default, the key the plan records it under, and what plan refuses on it. Both flags take one helper, _leg_path_help(leg, default), so the rule is said once. No behaviour changes.

Each flag's help says:

• where the leg is mounted, as a path in the assembly root, with its default (spec, code), recorded as legs.spec_path / legs.code_path;
• adopt-bad-leg-path (adopt-project.py accepts a non-canonical leg path such as --spec-path spec/, so the mount and its .gitmodules registration disagree and main still says adoption verified #169): a path that is empty or ., is absolute, begins with - or is longer than 255 characters; has a .. segment, a backslash, a segment that ends in a dot, or a character outside ASCII letters, digits and ._/@+~-; is not in Git's own spelling (spec/, ./spec, a//b); has a segment Git or Windows reserves (.git, CON); or is, holds or lies inside the other leg's path, whatever the case;
• adopt-leg-path-collides (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): a path that is, holds or lies inside a FILE the shape writes into the root (project.yaml is one, and contracts holds several), or is at or under shape/, whatever the case;
• the defaults pass, and either refusal writes no plan and rewrites nothing: its Remediation: line states the whole rule.

The list never says "only", and the closing sentence is about these two refusals. A value that plan accepts, or refuses under a code that is not one of the two (see "Composes with"), is not described, so the help stays true whichever other change lands first.

docs/cli.md is regenerated by scripts/render-cli-reference.py (+38 lines, only these two flags); --check passes.

Why

The flags predate docs/cli.md (#97), which renders a flag with no help= as a bare line. #169 and #172 later made plan refuse two kinds of value for them before it writes a plan, and neither touched the help. A reader of the flag-level reference AGENTS.md points every assistant at learned neither what the flags are for, nor the default, nor that spec/, project.yaml or contracts would be refused. #309 answered this for scaffold-project.py; the two front doors that take the same two flags were documented differently.

The words are #309's where they fit adoption ("where the spec leg is mounted, as a path in the assembly root (default: spec)", then "is, holds or lies inside a FILE the shape writes into the root"), with the two halves only an adoption needs or #309 left out: the canonical-spelling rule (a trailing /, a leading ./ or a //: the issue's decision 1) and shape/, where execute writes its copy of a file the root already holds. The codes are named, so an assistant can grep for the string plan prints, and a test holds each code whole on one line of the help at 80 columns, because textwrap breaks a hyphenated word at a line end and adopt-leg-path-collides would otherwise reach docs/cli.md as adopt-leg-path- and collides.

A mount over a source path the plan KEEPS in the root (--spec-path .specify, docs/ kept) is not said: plan notes it and refuses nothing (_kept_collision_notes), and check reports it as plan-leg-path-collides.

I held each sentence to the tool before writing it, as #288's review did: plan against a local source (stub gh first on PATH, GH_TOKEN=bogus, empty GH_CONFIG_DIR) with every value in the test file's tables below.

Fix round (review of 6124cb4)

The lane's own review of 6124cb4 (codex was out of quota) said CHANGES NEEDED, for wording and tests only. Findings F1 to F3 and N1 are fixed in two commits on top of 6124cb4; N2 is this body.

• F1 (b136f0e). The help read as a closed list, and plan refuses more under the same codes: an empty value, ., a leading -, a segment that ends in a dot (spec., legs./code), a non-ASCII letter (é) and 256 characters. The help now says each, says "ASCII", and says "whatever the case" of the collision clause too (Project.yaml, CONTRACTS and Shape/x are refused).
• F2 (b136f0e). Each REFUSED row of the test file now carries the words of the help that say why, so a clause dropped from the help fails the row that exercises it. The four mutants that passed 31 of 31 are killed.
• F3 (b136f0e, 409f10b). "Nothing rewrites a value or picks another for you" was false for --spec-path null (adopt-project.py plan writes null, true and other YAML keywords unquoted, so plan --spec-path null silently mounts the leg at the default spec #181). The help now says what is true of its two refusals instead: either one writes no plan and rewrites nothing, and its Remediation states the whole rule. The review's test rows for null and 2026 are not added: they would fail at this head, and composing with 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 showed a third outcome (below). 409f10b narrows the closing sentence to "Either refusal" after that composition.
• N1 (b136f0e). The plan_help fixture passes COLUMNS=80 (the width docs/cli.md is rendered at) and NO_COLOR=1 (Python 3.14's argparse colours help when FORCE_COLOR is exported), so the tests no longer depend on the shell that runs pytest.
• N2. This body.

Tests

tests/test_adopt_plan_leg_path_help.py (new, 45 tests, about 20 s). tests/test_cli_reference.py holds docs/cli.md to --help, so it agrees with a help that is missing and cannot say so; these hold the help to the tool:

• each flag carries a description naming its default, its key, both codes, the examples and the clauses (2);
• each code sits whole on a line of each flag's help at 80 columns (4);
• --code-path's help is --spec-path's with the role and default swapped (1);
• each of 31 values the help describes as refused is refused by plan with exit 2, no plan file, the code the help names and a Remediation that says nothing here rewrites or picks a path, and the help carries the clause that says why (31);
• six values the help does not describe as refused (contracts/x beside the refused contracts, docs/spec, .specify, legs/code, project, shapes) are planned and recorded under legs: (6);
• the defaults pass and are recorded as spec_path: spec / code_path: code (1).

The help is read at one width and with no colour, whatever the shell exports. With COLUMNS=120 exported the first version failed 15 of 31; the file passes 45 of 45 with COLUMNS=120 on Python 3.12, and with COLUMNS=120 FORCE_COLOR=1 on Python 3.14.7 (tools/x401-py312-cols120-409f10b.log, tools/x401-py314-cols120-forcecolor-409f10b.log).

Against main 92e29d9, which has no help: all 45 FAIL (tools/x401-newtests-at-main-92e29d9.log.gz). Against 6124cb4's help: 14 of 45 fail, each for a clause that help lacked (tools/x401-newtests-at-6124cb4.log.gz).

Mutants, one at a time, 23 of 23 killed (tools/x401-mutants-409f10b.txt): the help without each of "whatever the case" (other-leg clause), the other-leg clause, "a backslash", "Windows" and CON, "ASCII", "begins with -", "ends in a dot", "empty", ".", "longer than 255", the collision clause's "whatever the case", the closing sentence, "is absolute", the .. segment, the contracts clause, and the wording that splits a code across two lines; the tool without the shape/ refusal, without .git among Git's own names, with 300 characters allowed, with a leading - allowed, and with a trailing dot mountable; the first fix reverted; the fixture without its width pin.

Targeted run at 409f10b, S/frbin on PATH (tools/x401-targeted-409f10b.log), 523 passed, 4 skipped in 335 s:

file	tests
tests/test_adopt_plan_leg_path_help.py	45
tests/test_cli_reference.py	13
tests/test_repo_hygiene.py	50
tests/test_adopt_plan.py	57 (1 skipped: SHAPE_MEDXEHR_CLONE unset)
tests/test_scaffold_leg_path_collisions.py	104
tests/test_shape_doctor.py	258 (3 skipped)

scripts/render-cli-reference.py --check: ok. CI's three-OS result is the only Windows evidence. The rows new in this round pass é, an empty value (--spec-path=), --spec-path=-x and a 256-character value as single argv items; they read no working-tree file a helper wrote, and use nothing newer than Python 3.9 has.

Composes with

git merge-tree --write-tree of 409f10b against each head, from the remote-tracking refs, no fetch (tools/x401-mergetrees-409f10b.txt).

• origin/main 92e29d9: rc 0.
• This lane's heads: scaffold-project.py: a leg path the project's own YAML reader would read back as another type (null, ~, true, False, 2026, 1.5) is refused before anything is created, under --dry-run alike, through the one definition adopt-project.py asks, so --spec-path 2026 no longer creates three repositories whose first bootstrap fails manifest-leg-path, and adopt-project.py execute no longer says adoption verified before that bootstrap fails (#225) #266 3410be7, shape-doctor.py: a root's own contracts/shape-pin.yaml that does not read as a pin (a merge conflict, a non-UTF-8 byte, a commit: that is not 40 hex, a deleted file) is INVALID, exit 1, with the git command that puts back the last pin a tool wrote as its NEXT, instead of CANNOT ANSWER, exit 3, sending the reader to git fetch --all in the standard (#237) #267 8badae0, update-shape.py read_pin refuses update-pin-row, and the pinned validate-pins.py and validate-family.py report shape-pin-row, when a shape pin's files: is not a list, so files: 5, true or 1.5 no longer ends check, apply, shape-doctor.py and the project's own validator in TypeError: ... is not iterable (#290) #343 9e6caeb, update-shape.py: apply --add refuses a path under a file the root keeps as update-add-not-a-directory before it writes anything, and a write that fails after the copies is update-write-failed, rolled back, so neither leaves a rewritten copy and an unmoved pin behind a traceback (#285) #346 818db36, update-shape.py: a pinned copy, contracts/shape-pin.yaml or the manifest kept as a symlink, or under one, is refused as update-rewrite-symlink before anything is written, and check calls such a copy copy-is-link, so apply no longer writes the standard's bytes at the link's end and reports a commit that does not hold them (#286) #347 e965ab0, bump-leg.py: a workflow file or a leg pin that is not UTF-8 is refused by name before anything moves, so a Latin-1 comment no longer ends the run in a UnicodeDecodeError traceback (#289) #352 3416283, 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 96ff0c7, scaffold-project.py and family.py: --tracking-branch is asked of git check-ref-format --branch before anything exists, so ~, a..b, x.lock and a/ are refused under --dry-run and no longer die at the first git init -b after gh repo create has made the repositories (#283) #355 d696acc, 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 dbfad70, bump-leg.py: a workflow file, the workflows directory or the leg's pin that this user cannot open is refused by name with a remedy, so the run ends in exit 2 and not a PermissionError traceback (#383) #403 5bc6b47, shape_advisory.py and shape-doctor.py: an origin URL that is not UTF-8 names nothing, and the members row reads it as make siblings does, so a single repository is still advised, a leg clone is still sent to its root, and shape-doctor.py --root no longer ends in a UnicodeDecodeError traceback (#385) #404 f9d420a, and the branches of adopt-project.py: Plan.__init__, allowed_empty_legs, names and open_source iterate or call .get on a hand-edited plan's pins:, allow_empty_legs:, paths:, legs: and source: without asking their type, so a scalar ends check and execute in a TypeError or AttributeError traceback, exit 1, and pins: openGlass passes check, adopts, and writes eight one-letter neutral-product pins that the project's own validate-pins.py refuses #386 (5f177c9) and templates/assembly-root/scripts/validate-pins.py: a workflow file under .github/workflows/ that is not UTF-8 ends the run in a UnicodeDecodeError traceback, exit 1, with no refusal naming the file, so the project's pins gate (make validate, the validate workflow) dies on a Latin-1 comment where a non-UTF-8 pin is a clean REFUSED yaml-unreadable, exit 2 #359 (11dff7f): rc 0. shape-doctor.py: the manifest kinds row puts back a shape or leg pin under contracts/ that does not load with the git command pin_restore picks from its own state, shows a copy the shape pin has a row for or a neutral product pin with a read-only git diff, and leaves any other file to a person whatever it is called, so its NEXT no longer tells the reader to delete the pin (#291) #358 2745890: rc 1 in shape-doctor.py, the same conflict as against bare main, so not this PR's.
• Other lanes' open PRs touching adopt-project.py, docs/cli.md or tests/test_repo_hygiene.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, 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 ba58838, 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 741cbf2, 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 33c6dee, 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 1037dea, adopt-project.py: check finds, and execute refuses before any leg exists, a source symlink with an empty target and the source's own project.yaml kept in the root, and plan no longer offers root for that file (#303, #305) #387 69c54c9, family.py: init asks the holder's reader and validate-family.py about family.yaml before creating anything, --dry-run too, so --id null, --tracking-branch true, a blank --created-by and --created-on 20261011 are refused (#307) #397 abb27e6, family.py: add --dry-run makes every refusal add makes before it mounts, reads the member from throwaway clones outside the holder for the row's id and digest, and prints the row, gitlink, .gitmodules section and trailers without mounting, writing or committing anything, and add takes --trailer as bump does, so every subcommand has the dry run the module's EXIT CODES line promises (#326) #400 de628fe: rc 0. adopt-project.py: execute records in project.yaml which leg the plan gave each submodule a leg keeps, and shape-doctor.py holds the submodule to that row, so one in the other leg is MISPLACED and a real adoption's placement reads ok (#189) #394 48bdbf9: rc 0 against this head, and rc 1 in tests/test_repo_hygiene.py against bare main.
• Semantic checks on scratch merges (render-cli-reference.py --check ok on each):
  • 409f10b + main + 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 + family.py: init asks the holder's reader and validate-family.py about family.yaml before creating anything, --dry-run too, so --id null, --tracking-branch true, a blank --created-by and --created-on 20261011 are refused (#307) #397 + family.py: add --dry-run makes every refusal add makes before it mounts, reads the member from throwaway clones outside the holder for the row's id and digest, and prints the row, gitlink, .gitmodules section and trailers without mounting, writing or committing anything, and add takes --trailer as bump does, so every subcommand has the dry run the module's EXIT CODES line promises (#326) #400 (all three touch docs/cli.md or this block): the new file, test_cli_reference and test_repo_hygiene, 108 passed;
  • 409f10b + scaffold-project.py: a leg path the project's own YAML reader would read back as another type (null, ~, true, False, 2026, 1.5) is refused before anything is created, under --dry-run alike, through the one definition adopt-project.py asks, so --spec-path 2026 no longer creates three repositories whose first bootstrap fails manifest-leg-path, and adopt-project.py execute no longer says adoption verified before that bootstrap fails (#225) #266: the new file, test_cli_reference and scaffold-project.py: a leg path the project's own YAML reader would read back as another type (null, ~, true, False, 2026, 1.5) is refused before anything is created, under --dry-run alike, through the one definition adopt-project.py asks, so --spec-path 2026 no longer creates three repositories whose first bootstrap fails manifest-leg-path, and adopt-project.py execute no longer says adoption verified before that bootstrap fails (#225) #266's test_leg_path_yaml_scalars, 287 passed.

Sequencing with #266 and #314. Three outcomes exist for --spec-path null (and 2026, true, 1.5), and the help is true in each, so the order they land in does not matter to it. Today plan writes a plan for them (spec_path: null, #181). With #266, plan refuses them as adopt-bad-leg-path ("which the project would not read back as text"). With #314, plan refuses them as adopt-manifest-invalid (a scratch merge of 409f10b and #314 alone shows it). The help describes none of the three, and the tests pin none. If #266 lands, a clause naming that class may be added to the adopt-bad-leg-path list, but the help is not false without it.

Left out

• AGENTS.md's "Adopting an existing repository" section (the issue's decision 2). It does not name --spec-path / --code-path, and a sentence there raises the line cap in tests/test_repo_hygiene.py (477 on this branch; main's AGENTS.md is 481 lines under a cap of 481 since 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), which adopt-project.py: execute records in project.yaml which leg the plan gave each submodule a leg keeps, and shape-doctor.py holds the submodule to that row, so one in the other leg is MISPLACED and a real adoption's placement reads ok (#189) #394 (fix/adopt-record-submodule-placement) also edits. The flag-level reference is what the issue's title names. Brett or the lane can add the sentence in a follow-up.
• plan's other options with no help= (--org, --id, --visibility, --tracking-branch, --path-policy, --out, --work-dir) and check / execute's (decision 3: these two flags only).
• The check and execute sides of a hand-edited plan's spec_path: / code_path: (adopt-project.py accepts a non-canonical leg path such as --spec-path spec/, so the mount and its .gitmodules registration disagree and main still says adoption verified #169 and 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 closed those).
• --spec-path null itself (adopt-project.py plan writes null, true and other YAML keywords unquoted, so plan --spec-path null silently mounts the leg at the default spec #181) and the YAML words: the help does not say what plan accepts.

Closes #340

🤖 Generated with Claude Code

Summary by Sourcery

Document the leg path options and their refusal rules in plan --help and the CLI reference, with tests that keep the descriptions aligned with actual behavior.

New Features:

• Document the purpose, defaults, recorded plan keys, and validation refusals for plan --spec-path and --code-path in CLI help.

Enhancements:

• Centralize the shared leg-path option description so the two flags remain consistent.
• Regenerate the CLI reference with the expanded option descriptions.

Documentation:

• Expand docs/cli.md with the generated descriptions for both leg-path options.

Tests:

• Add comprehensive coverage ensuring the help matches accepted and refused leg-path behavior, including stable formatting and generated documentation consistency.

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

[sourcery-ai]

Reviewer's Guide

This documentation-only change adds shared, generated help text for plan's leg mount path options and a comprehensive test suite that validates the help against actual refusal and plan-recording behavior, with no runtime behavior change intended.

Sequence diagram for plan leg path validation and help

sequenceDiagram
    participant User
    participant PlanCLI
    participant LegPathHelp
    participant PlanValidation
    participant PlanFile

    User->>PlanCLI: plan --spec-path PATH --code-path PATH
    PlanCLI->>LegPathHelp: _leg_path_help(leg, default)
    LegPathHelp-->>PlanCLI: shared option description
    PlanCLI->>PlanValidation: validate leg paths
    alt invalid path
        PlanValidation-->>PlanCLI: adopt-bad-leg-path or adopt-leg-path-collides
        PlanCLI-->>User: exit 2, no plan file
    else valid path
        PlanValidation-->>PlanCLI: accepted path
        PlanCLI->>PlanFile: record legs.spec_path / legs.code_path
        PlanCLI-->>User: plan created
    end

Loading

File-Level Changes

Change	Details	Files
Document the semantics and validation behavior of the leg mount path options in the CLI help.	Add a shared helper to generate role-specific help for --spec-path and --code-path. Describe defaults, recorded plan keys, invalid path spellings, reserved names, cross-leg overlaps, generated-file collisions, and shape/ collisions. Regenerate the CLI reference with the expanded option descriptions.	adopt-project.py docs/cli.md
Add behavioral tests that keep the option help synchronized with plan validation and output.	Verify both flags describe their purpose, defaults, plan keys, refusal codes, and representative examples. Verify refused values return the documented code without writing a plan. Verify accepted values and defaults are planned and recorded under legs:. Verify the two option descriptions remain equivalent apart from role-specific substitutions.	tests/test_adopt_plan_leg_path_help.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#340	Give adopt-project.py plan --help useful descriptions for --spec-path and --code-path, including where each leg is mounted, its default, and the plan key where the value is recorded.	✅
#340	Document the path-value refusals that plan applies before writing a plan, so the help explains the adopt-bad-leg-path and adopt-leg-path-collides rules.	✅
#340	Regenerate docs/cli.md so its generated CLI reference reflects the new flag descriptions.	✅

Possibly linked issues

• adopt-project.py plan: --spec-path and --code-path have no help=, so plan --help and docs/cli.md print two bare lines for the flags that choose where each leg is mounted, and say nothing of the two refusals plan makes on them before anything is created (adopt-leg-path-collides, adopt-bad-leg-path), which #288 is documenting for the scaffold's twins #340: The PR adds help describing both flags, their defaults and recorded keys, and both refusal rules; it regenerates docs/cli.md.

---

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]

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

[brettheap]

(lane openRepoShape-2, 2026-10-12T17:00Z)

This lane reviewed its own PR #401 at 6124cb4, read-only, in its own detached worktrees, and authored nothing.

CHANGES NEEDED. All items are wording, test or PR-body changes. Sequencing: whichever of #266 and #401 lands second adds the YAML clause in item 3. Landing #266 first is simpler.

1. P3. The help (adopt-project.py:4885-4893) reads as complete, but plan also refuses these with exit 2 and the same codes:
   • a segment ending in a dot (spec.);
   • a leading -;
   • an empty value, or .;
   • non-ASCII letters (é);
   • more than 255 characters;
   • Project.yaml and CONTRACTS, because collisions also ignore case, which the help says only of the other leg.
2. P3. The tests check codes, not clauses. With no wrapping, all 31 pass when the help drops the other-leg clause, "a backslash", or "Windows" and CON.
3. P3. "Nothing rewrites a value or picks another for you" (:4894) is false for --spec-path null. plan writes spec_path: null, check says plan ok, and the leg is mounted at spec (:1366). That is adopt-project.py plan writes null, true and other YAML keywords unquoted, so plan --spec-path null silently mounts the leg at the default spec #181, which predates this PR. With scaffold-project.py: a leg path the project's own YAML reader would read back as another type (null, ~, true, False, 2026, 1.5) is refused before anything is created, under --dry-run alike, through the one definition adopt-project.py asks, so --spec-path 2026 no longer creates three repositories whose first bootstrap fails manifest-leg-path, and adopt-project.py execute no longer says adoption verified before that bootstrap fails (#225) #266 merged, plan refuses null, 2026 and true. The help does not mention that class, and the tests still pass.
4. Nit. With COLUMNS=120 exported, 15 of 31 tests fail, because argparse splits adopt-bad-leg-path at a hyphen. Pin COLUMNS=80 in plan_help.
5. Nit. The PR body is stale: the AGENTS.md cap is 481, and main and several heads moved.

Tests:

• Main 92e29d9 plus the new file: 31 failed, because the help is missing.
• Head: 31 passed.
• Head merged with main: 509 passed, 4 skipped. render-cli-reference.py --check is ok on all three.
• Mutants: the revert, the shape/ refusal and .git are killed.

Merges: git merge-tree is rc 0 against main and against every open head that touches adopt-project.py or docs/cli.md. The rc 1 results for #358, #394 and i386 match bare main. Composed with #314, #397 and #400, with #394, or with #266, the new file plus test_cli_reference.py gave 44 passed, and --check was ok.

The full report is handoffs/xFactory/attachments/lane-openRepoShape-2/review401-6124cb4/final-report.md in opensoft/brett-wip.

[brettheap]

(lane openRepoShape-2, 2026-10-12T17:48Z)

The fix round on this lane's review of 6124cb4 is pushed: 409f10b.

• F1. _leg_path_help now names the refusals the review found missing: an empty value, ., a leading -, a trailing dot, more than 255 characters, and a non-ASCII letter. The collision clause now says "whatever the case". docs/cli.md is regenerated, and --check passes.
• F2. Each refusal row asserts the words of the help that say why, not only the code. All 23 help and tool mutants are killed, including the four that survived the review. A new test keeps each refusal code whole on one line at 80 columns.
• F3. Fixed in the wording. The help stays true whichever of scaffold-project.py: a leg path the project's own YAML reader would read back as another type (null, ~, true, False, 2026, 1.5) is refused before anything is created, under --dry-run alike, through the one definition adopt-project.py asks, so --spec-path 2026 no longer creates three repositories whose first bootstrap fails manifest-leg-path, and adopt-project.py execute no longer says adoption verified before that bootstrap fails (#225) #266 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 lands, and the review's null/2026 rows are not added, because what happens to them depends on which of those two lands first.
• N1. The help fixture pins COLUMNS=80 and NO_COLOR=1.
• N2. The body is now v2.

Tests at 409f10b

• The targeted set: 523 passed, 4 skipped.
• The new file against main 92e29d9: 45 of 45 fail.
• Python 3.12 with COLUMNS=120, and 3.14 with COLUMNS=120 FORCE_COLOR=1: 45 passed each.
• Merged with scaffold-project.py: a leg path the project's own YAML reader would read back as another type (null, ~, true, False, 2026, 1.5) is refused before anything is created, under --dry-run alike, through the one definition adopt-project.py asks, so --spec-path 2026 no longer creates three repositories whose first bootstrap fails manifest-leg-path, and adopt-project.py execute no longer says adoption verified before that bootstrap fails (#225) #266 3410be7: 287 passed.
• Merged with main, 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, family.py: init asks the holder's reader and validate-family.py about family.yaml before creating anything, --dry-run too, so --id null, --tracking-branch true, a blank --created-by and --created-on 20261011 are refused (#307) #397 and family.py: add --dry-run makes every refusal add makes before it mounts, reads the member from throwaway clones outside the holder for the row's id and digest, and prints the row, gitlink, .gitmodules section and trailers without mounting, writing or committing anything, and add takes --trailer as bump does, so every subcommand has the dry run the module's EXIT CODES line promises (#326) #400: 108 passed.

Details are in handoffs/xFactory/attachments/lane-openRepoShape-2/impl340-adopt-plan-help/fix-round-60c4.md in opensoft/brett-wip.

[brettheap]

@codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-12T17:51:21.595347Z	409f10b	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 👍

Reviewed commit: 409f10bcde

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[brettheap]

(lane openRepoShape-2, 2026-10-12T19:45Z)

This lane re-verified the fix round on its own PR #401 at 409f10b, read-only in its own detached worktrees; nothing authored.

MERGEABLE WITH NITS. All five findings of the 6124cb4 review are fixed. #401 can land before or after #266.

• F1: the help names all ten refusals; plan refuses each under the code named. A model of the help's clauses found 0 divergences from the tool over 2,597 values, also on main dd8d0ea.
• F2: mu2 to mu5 are killed on merit (3, 6, 3, 4 failures, also at width 1000); mu1, mu6, mu7 too.
• F3: the false sentence is gone; the help is true alone, with main (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 refuses null as adopt-manifest-invalid) and with scaffold-project.py: a leg path the project's own YAML reader would read back as another type (null, ~, true, False, 2026, 1.5) is refused before anything is created, under --dry-run alike, through the one definition adopt-project.py asks, so --spec-path 2026 no longer creates three repositories whose first bootstrap fails manifest-leg-path, and adopt-project.py execute no longer says adoption verified before that bootstrap fails (#225) #266.
• N1: 45 passed with COLUMNS 30 to 250; no colour on Python 3.10 to 3.15.
• N2: cap 481 and the scaffold-project.py: a leg path the project's own YAML reader would read back as another type (null, ~, true, False, 2026, 1.5) is refused before anything is created, under --dry-run alike, through the one definition adopt-project.py asks, so --spec-path 2026 no longer creates three repositories whose first bootstrap fails manifest-leg-path, and adopt-project.py execute no longer says adoption verified before that bootstrap fails (#225) #266 constraint are right.

Nits, neither blocking:

1. The REFUSED rows (test :252, :255) do not pin a clause to its code. Swapping the two code names in the help passes 45 of 45.
2. The PR body names main 92e29d9 and says plan writes a plan for null; on main it is refused. Refresh at landing.

After #266, null, 2026, true, 1.5 and ~ are refused as adopt-bad-leg-path, a class the help omits. The help stays true; the second PR to land should add the clause.

Tests: with main dd8d0ea (merge-tree rc 0) 838 passed, 1 skipped; with #266 added 692 passed, 1 skipped. --check ok. CI green on three OSes.

Report: review401-6124cb4/reverify-409f10b.md, in opensoft/brett-wip.

[brettheap]

(lane openRepoShape-3, 2026-10-12T19:54:57Z) 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 #340 (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
2 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