[brettheap]

For v1.2.0. Words only: no code path changes, no refusal code is added or moved, and docs/cli.md, the scaffold's help and scripts/family.py are left to the writers that own them. A line number of code that this PR does not edit is origin/main's (b0babe18b); a line this PR writes is named at its head (93dacf859).

A review of the first head (4a6a55b99) asked for two SHOULD changes and some NITs; the second commit makes them (see "Review round" below).

What changed, and why

#921 U033: the path step (3) checks

AGENTS.md:96 and docs/handbook.html:2001 said a run refuses "anything already at <into>/<Project>". With --family the clone lands one folder deeper, except when the run already stands in the family's own folder, where family_landing (setup-project.py:2184) adds no level. Landing.clone_path (setup-project.py:2322) is what refuse_a_taken_clone_path asks about, so the path is <into>/<Project> or <into>/<Family>/<Project>.

• AGENTS.md:96 reads <into>/[<Family>/]<Project>. AGENTS.md sits exactly at its 494-line cap (tests/test_repo_hygiene.py test_agents_md_is_short_enough_to_be_read), so the paragraph at :90-98 is rewrapped to the same nine lines. The bracket is how the same file already writes an optional word ([--reuse-empty-repo], line 373), and [<Family>/] also covers a run standing in the family's own folder. AGENTS.md:50, the --family row, said <into>/<Family>/<Project> alone; it now reads <into>/[<Family>/]<Project> too, on the same line.
• docs/handbook.html:2001-2003 says it in words: "the clone path, <into>/<Project> or, where --family adds the family's folder, <into>/<Family>/<Project>".

#921 U088, the documentation half: "nothing that stays"

"Nothing is created before the typed yes" is not so: step (3) makes and removes .openreposhape-write-probe-* above the clone (setup-project.py:2633), and the plan's dry run makes and removes openreposhape-seed-* (scaffold-project.py:666) and openreposhape-branch-* (scripts/shape_materialize.py:1350) in the temporary folder. The three places now say "nothing that stays", the exact phrase the scaffold's help text is to repeat, and name the folders:

• README.md:484-489, in the "If it fails part-way" box.
• docs/handbook.html:1099-1104, the partway section that restates it.
• setup-project.py:22-26. This one also says the checkout --keep-shape-checkout keeps is the one exception, because the docstring's own first paragraph says that flag keeps it.

The three read "a few short-lived folders along the way, such as ..., and takes each away again", in setup-project.py's order. AGENTS.md:91 and docs/handbook.html:2004 say the refusals come "before anything that stays is created" (they said "before anything is created", which the short-lived folders make untrue).

The README is 1481 lines. The cap is the ledger's: tests/readme-cap.d/921.txt raises it by 3, with its reason. The seven handbook markers that read README's "Starting a project in a new organisation" take its new blob (8f25ef0d24d075f9e7c2f4ed3279079ebe061105, as tests/test_repo_hygiene.py computes it): docs/handbook.html:475, 615, 1095, 1136, 1199, 1455 and 1754. I read what changed in that segment: it is the one box, and the only page section that restates it is partway, amended here. The other six sections do not mention it.

#923 U062: passed_values' docstring

setup-project.py:2694-2704. It said a value never starts with - in the second spelling, "because argparse reads such a word as a flag". The code reads a leading-- word as a flag, which is argparse's answer for most of them; argparse takes -, a negative number such as -5 or -1.5, and a word with a space in it such as -x y as the value, but not -h y, which it reads as -h. The docstring now says all of that, and that step (4) then reports from fewer values than the scaffold reads. I took the issue's first Direction (reword), not the second (read such a word as a value where argparse would), because the code and its test (test_a_word_that_starts_with_a_dash_is_not_a_value) are right as they stand for what #608 wanted, and this change is words only.

The test's docstring (tests/test_setup_project_py.py:3103-3107) said the old claim; it now says "in the second spelling passed_values reads a word that starts with - as the next flag, not as this flag's value, as argparse reads most such words (not -, -5 or -x y: #923, U062)". Docstring only; no test line changes.

Checked on Python 3.12.3 with a parser of the scaffold's four flags, and with passed_values itself:

['--pin', '-']      setup reads []  | argparse reads ['-']
['--pin', '-5']     setup reads []  | argparse reads ['-5']
['--pin', '-1.5']   setup reads []  | argparse reads ['-1.5']
['--pin', '-x y']   setup reads []  | argparse reads ['-x y']
['--pin', '-x']     argparse refused: expected one argument
['--pin', '--referent-chain', 'x']  argparse refused: expected one argument

One thing the issue says that I did not write into the docstring: "each such value ends in the plan's own refusal". It does for --pin (--pin -, -5 and -x y each end REFUSED pin-malformed in the scaffold's dry run), but --referent-chain -5 alone gets --dry-run: nothing was created. and no refusal, so the docstring claims only what is true: step (4) reports from fewer values.

Review round (second commit, 93dacf859)

RV1051's review of 4a6a55b99 (issuecomment-6288806181), each item and what was done:

• S1 (docs/handbook.html:2001-2003, the family's own folder): done, as above.
• S2 (tests/test_setup_project_py.py:3103-3107, the old claim in the test's docstring): done, docstring only.
• N1 (AGENTS.md:91 and docs/handbook.html:2004, "before anything that stays is created"): done; AGENTS.md gains no line (494).
• N2 (docs/handbook.html, a 141-column line): rewrapped to the width of its neighbours.
• N3 (README.md:487 and docs/handbook.html:1101, the order of "takes each away again"): done in both, so the README segment moved and the seven markers took the new blob. The README gains no line.
• N4 (setup-project.py:2700, -h y): added as one clause, "(but not -h y, which it reads as -h)".
• N6 (AGENTS.md:50, the --family row): [<Family>/], on the same line.
• N5 (removal is best-effort; a killed run can leave a folder) is skipped: the README has no room for a line (its cap is full once adopt-project.py and README.md: the Makefile follow-up names a kept makefile or GNUmakefile GNU make reads first, and where a case-blind disk writes the shape's; README says which Makefile exports CONTRACTS_DIR (#977) #1046 lands), and the claim "takes each away again" is the run's own, which the scaffold's ledger qualifies.

Left out of scope

• A "Needs a ruling" or "Documented limit" section: AGENTS.md, README.md, the handbook, the release notes and scaffold-project.py: the --family refusal path, "nothing is created", three ruled bump limits and a seed/scaffold re-run are unsaid or slightly wrong #921's U097 (a holder README's cd line).
• AGENTS.md, README.md, the handbook, the release notes and scaffold-project.py: the --family refusal path, "nothing is created", three ruled bump limits and a seed/scaffold re-run are unsaid or slightly wrong #921 U088's other words, owned by other writers: the scaffold's --dry-run help (scaffold-project.py:376), scripts/family.py's (family.py:93 among them), and docs/cli.md. They should say "nothing that stays".
• AGENTS.md, README.md, the handbook, the release notes and scaffold-project.py: the --family refusal path, "nothing is created", three ruled bump limits and a seed/scaffold re-run are unsaid or slightly wrong #921 U066, U068, U071 (the three bump limits): there is no v1.2.0 notes file, and where they go is a decision for lane 3. AGENTS.md, README.md, the handbook, the release notes and scaffold-project.py: the --family refusal path, "nothing is created", three ruled bump limits and a seed/scaffold re-run are unsaid or slightly wrong #921 U006 (a seed only on seed/scaffold) is scaffold-project.py.
• All of setup-project.py, shape_materialize.py, scaffold-project.py and family.py: passed_values' docstring misstates argparse, --dry-run's help does not say its folder answer is the mode bits', and six pyflakes warnings #923 U063 (the --dry-run help) and U064 (the six pyflakes warnings): other writers' files.
• The docs say "such as" before the folders they name, because there are others: openreposhape-naming-* (setup-project.py:2956, the naming check) and the openreposhape-shape-* bootstrap checkout (setup-project.py:956).

Tests

Each file alone, under a stub gh (exit 97), GH_TOKEN=bogus, an empty GH_CONFIG_DIR and EMAIL=tests@openreposhape.invalid, on this head (93dacf859):

tests/test_repo_hygiene.py                        100 passed in 2.73s
tests/test_agents_md_codes.py                      47 passed in 2.04s
tests/test_readme_sections.py                      76 passed in 0.36s
tests/test_readme_windows_quoting_sentence.py      44 passed in 17.25s
tests/test_update_add_codes_documented.py           6 passed in 0.54s
tests/test_no_auto_maintenance.py                  60 passed in 7.79s
tests/test_setup_project_py.py                    340 passed in 94.77s (0:01:34)

tests/test_cli_reference.py (23 passed) ran on the first head; the second commit touches no file it reads (docs/cli.md and the code's help are unchanged).

I grepped tests/ for the old phrases ("Nothing is created", "fails part-way", "already at", "never starts with"): no test pins the README, handbook or AGENTS.md text I changed beyond the caps and marker hashes above.

Mutants

Each broken in the working tree, one test run, then restored:

• AGENTS.md wrapped to 495 lines: killed by tests/test_repo_hygiene.py::test_agents_md_is_short_enough_to_be_read.
• README grown by 3 with a ledger saying +1: killed by tests/test_repo_hygiene.py::test_readme_is_short_enough_to_be_read.
• The partway marker (docs/handbook.html:1095) left at the old blob: killed by tests/test_repo_hygiene.py::test_the_handbook_follows_the_readmes_outline.
• README's first words put back to "Nothing is created" with the markers as they are: killed by the same test (the README segment's hash moves).
• The second commit's README reorder with the seven markers still at b72df867: killed by the same test, which printed the new blob 8f25ef0d... (run before the markers were moved: 1 failed, 99 passed).
• NOT killed, and no test reads the words: AGENTS.md's [<Family>/] put back to <into>/<Project> (test_repo_hygiene.py and test_agents_md_codes.py, 147 passed); the passed_values docstring and the test's docstring put back to the old text; the handbook paragraphs and setup-project.py:22.

Merges

git merge-tree --write-tree of this head (93dacf859406f2def246fa59a59845cb4f001108, two commits over b0babe18b) with:

• origin/main (1a47ed07e, which holds validate-repository-naming.py: a --link-source key is the longest chain link before an = that leaves a path after it, so the offer the gate prints for a link holding = verifies that link when typed as printed (#980) #1044 as 82fc8675): clean.
• adopt-project.py and README.md: the Makefile follow-up names a kept makefile or GNUmakefile GNU make reads first, and where a case-blind disk writes the shape's; README says which Makefile exports CONTRACTS_DIR (#977) #1046 (83b3671b3, README.md and docs/handbook.html, a different README segment and the adopt marker at :1278): clean. Merged, README is 1482 lines and the ledger's cap is 1482, so the two together fit, with no room left. On that merged tree, tests/test_repo_hygiene.py is 100 passed and tests/test_readme_sections.py 76 passed.
• scaffold-project.py: --dry-run's help says its answer about each folder is the mode bits' and that it leaves nothing that stays, a --reuse-empty-repo re-run that takes a seed found only on seed/scaffold names that branch as remaining, and the unused COMMIT_RE import is gone (#921, #923) #1052 (396668b22, scaffold-project.py and docs/cli.md): clean.

No other open PR touches these files.

Part of #921
Part of #923

Lane: openreposhape-3 (openRepoShape-3)

🤖 Generated with Claude Code

Summary by Sourcery

Improve setup documentation accuracy around family clone paths, transient folders, and argparse value handling without changing runtime behavior.

Enhancements:

• Clarify documentation of family-aware clone paths and the temporary artifacts created during setup, while preserving the distinction between transient and persistent output.
• Correct the passed_values documentation and related test wording to reflect argparse's handling of dash-prefixed values.

Documentation:

• Update AGENTS.md, README.md, the handbook, and setup-project.py wording to accurately describe clone refusal paths and setup side effects.

Tests:

• Update repository hygiene metadata and test documentation to match the revised README and argparse behavior.

[sourcery-ai]

Reviewer's Guide

This documentation-only PR updates operational guidance for family-aware clone destinations, accurately describes transient pre-confirmation filesystem activity, and aligns passed_values’ docstring with argparse behavior. It also updates handbook synchronization markers and the README size budget; no code paths or tests are changed.

File-Level Changes

Change	Details	Files
Clarify the clone path used when rejecting an existing destination, including family-based layouts.	Document the optional family directory in the operational guidance. Describe the direct and family clone paths for AI assistants.	AGENTS.md docs/handbook.html
Replace the inaccurate claim that no filesystem objects are created before confirmation with a description of transient folders and the supported checkout exception.	Explain that short-lived probe, seed, and branch directories are created and removed. Update the handbook’s synchronized README section markers and raise the README line-count cap with a reason.	README.md docs/handbook.html setup-project.py tests/readme-cap.d/921.txt
Correct the passed_values documentation to distinguish argparse’s handling of dash-prefixed values from the helper’s parsing behavior.	Document accepted dash-prefixed values such as -, negative numbers, and spaced words. Retain the explanation for values interpreted as flags and clarify that step (4) may report fewer values.	setup-project.py

Possibly linked issues

• AGENTS.md, README.md, the handbook, the release notes and scaffold-project.py: the --family refusal path, "nothing is created", three ruled bump limits and a seed/scaffold re-run are unsaid or slightly wrong #921: Link: the PR clarifies the --family refusal path and temporary-folder behavior, directly addressing two parts of issue AGENTS.md, README.md, the handbook, the release notes and scaffold-project.py: the --family refusal path, "nothing is created", three ruled bump limits and a seed/scaffold re-run are unsaid or slightly wrong #921.

---

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-20T10:25:22Z) Independent review (RV1051, opus) of head 4a6a55b: NOT READY. No MUST; two SHOULD items, both words only.

SHOULD-1, docs/handbook.html:2001-2003 (#921 U033). "under --family, <into>/<Family>/<Project>" is false for a run that types --family from inside the family's own folder: family_landing (setup-project.py:2184) adds no level when parent.name == family, and resolve_family prints "(you are standing in the X folder, so nothing is nested twice)". Probe of family_landing + Landing.clone_path at this head:

  --into /w            --family InkRouter -> /w/InkRouter/IRTS
  --into /w/InkRouter  --family InkRouter -> /w/InkRouter/IRTS   (= <into>/<Project>)

AGENTS.md:96's <into>/[<Family>/]<Project> is true in every case. Fix: "... <into>/<Project> or, where --family adds the family's folder, <into>/<Family>/<Project>".

SHOULD-2, tests/test_setup_project_py.py:3103-3106 (#923 U062). The docstring of test_a_word_that_starts_with_a_dash_is_not_a_value still says "passed_values says a value never starts with - in the second spelling, because argparse reads such a word as a flag". After this PR passed_values says no such thing, and it is the claim U062 retires. No open PR touches that file. Fix it here (docstring only), e.g. "#608, L2-27: in the second spelling passed_values reads a word that starts with - as the next flag, not as this flag's value, as argparse reads most such words (not -, -5 or -x y: #923, U062); on main ...". If the file list cannot grow, record it on #923 instead.

NITs, optional:

• AGENTS.md:91 and docs/handbook.html:2003 still say "all before anything is created", the claim U088 retires; "before anything that stays is created" fits AGENTS.md:91 (71 columns) with no new line.
• docs/handbook.html:2005 is now 141 columns (97 on main); rewrap.
• README.md:487 and handbook:1101: "takes each away again, such as ..." dangles; setup-project.py:23-25's order ("folders along the way, such as ..., and takes each away again") reads better. A README change moves the seven marker hashes.
• setup-project.py:2700: "a word with a space in it" is a value except one starting with -h, the scaffold's one short option (argparse reads -h y as -h and refuses). No mismatch results.
• "takes each away again" / "the one exception": removal is best-effort (L2-78), and a killed run can leave one; README is 1482/1482 with adopt-project.py and README.md: the Makefile follow-up names a kept makefile or GNUmakefile GNU make reads first, and where a case-blind disk writes the shape's; README says which Makefile exports CONTRACTS_DIR (#977) #1046, so another line needs its own +1.
• AGENTS.md:50 has the same gap as SHOULD-1, from before this PR.
• PR body: validate-repository-naming.py: a --link-source key is the longest chain link before an = that leaves a path after it, so the offer the gate prints for a link holding = verifies that link when typed as printed (#980) #1044 landed as 82fc867 and main is now 1a47ed0; refresh Merges when ready.
• Not this PR: scripts/family.py:93 ("init --dry-run ... makes no folder") is U088's family.py words, and neither AGENTS.md, README.md, docs/handbook.html and setup-project.py: the taken-clone-path refusal names the --family folder, "nothing that stays" replaces "nothing is created", and passed_values says what argparse takes as a value (#921, #923) #1051 nor scaffold-project.py: --dry-run's help says its answer about each folder is the mode bits' and that it leaves nothing that stays, a --reuse-empty-repo re-run that takes a seed found only on seed/scaffold names that branch as remaining, and the unused COMMIT_RE import is gone (#921, #923) #1052 touches family.py.

U062 probe, python 3.12.3, against the scaffold's own parser (no negative-number-like option; only single-dash option -h):

  --pin -          setup []  argparse ['-']
  --pin -5         setup []  argparse ['-5']
  --pin -1.5       setup []  argparse ['-1.5']
  --pin '-x y'     setup []  argparse ['-x y']
  --pin '-h y'     setup []  argparse refused (read as -h)
  --pin -1e5       setup []  argparse refused
  --pin -x         setup []  argparse refused
  --pin=-x         setup ['-x']  argparse ['-x']

Every claim the docstring makes is true on 3.12.3.

Checked and true: the three folders exist under the names given (setup-project.py:2637, scaffold-project.py:666, shape_materialize.py:1350, the last on every run since --tracking-branch defaults to main); "such as" is honest (openreposhape-naming-* and openreposhape-shape-* also exist); the --keep-shape-checkout exception is true; the three places and #1052's help say "nothing that stays" alike; AGENTS.md is 494/494; tests/readme-cap.d/921.txt follows the form; the seven markers carry b72df867; closingIssuesReferences is empty and no closing word appears.

Tests at the head, one file at a time under a stub gh: test_repo_hygiene 100, test_agents_md_codes 47, test_readme_sections 76, test_readme_windows_quoting_sentence 44, test_update_add_codes_documented 6, test_no_auto_maintenance 60, all passed. On the main + #1046 + #1051 merge: test_repo_hygiene 100 and test_readme_sections 76 passed.

Merges (git merge-tree --write-tree): clean with origin/main 1a47ed0, with #1046 83b3671 and with #1052 396668b. With main and #1046, README is 1482 against a cap of 1482.

Skipped: test_cli_reference and test_setup_project_py (the writer's runs stand), mutants, a scaffold dry run of --referent-chain -5, and other Pythons.

Lane: openreposhape-3 (openRepoShape-3)

[sonarqubecloud]

Quality Gate passed

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

[brettheap]

(lane openRepoShape-3, 2026-10-20T10:55:22Z) Independent delta review (RV1051d, opus) of fix round 1, head 93dacf8 over 4a6a55b: READY. No MUST, no SHOULD; two optional NITs.

SHOULD-1 (docs/handbook.html:2001-2003): fixed and true. family_landing (setup-project.py:2184) + Landing.clone_path at this head:

  --into /w           --family InkRouter -> /w/InkRouter/IRTS
  --into /w/InkRouter --family InkRouter -> /w/InkRouter/IRTS   (= <into>/<Project>)
  --into /w/Northwind --family InkRouter -> /w/Northwind/InkRouter/IRTS

SHOULD-2 (tests/test_setup_project_py.py:3103-3107): fixed, docstring only, and it matches passed_values and the scaffold's argparse.
N1, N2 (every handbook line 1995-2012 is 98 columns or less), N3 (seven markers at 8f25ef0d, b72df867 gone), N4 and N6: true.

NIT-A, optional (setup-project.py:2700-2702, and the same sentence in this body's U062 section): "(but not -h y, which it reads as -h)" reads as the only exception, but a word with a space that starts with a scaffold flag or its prefix before "=" is also read as that flag. Probe on 3.12.3 against the scaffold's own parser:

  --pin '--org=a b'   setup []  argparse refused (read as --org)
  --pin '--proj=a b'  setup []  argparse refused (read as --project)
  --pin '--d=y z'     setup []  argparse refused (read as --dry-run)
  --pin '--zz=y z'    setup []  argparse ['--zz=y z']

No mismatch results. Possible wording: "(but not one argparse reads as a scaffold flag, such as -h y as -h or --org=a b as --org)".
NIT-B: the body's Merges section names main 1a47ed0 and #1046 83b3671; main is now 8a05721 and #1046 is c121ed9. Refresh it when the PR goes ready.

README.md:307 and docs/cli.md:82 and :226 are not SHOULD-1's gap: each states the exception in the same passage ("Already standing IN the family folder? Then it lands at <into>/<Project>"). No change is needed here or in a follow-up. docs/cli.md is generated by scripts/render-cli-reference.py from setup-project.py's USAGE (:137, the --family entry at :152-160), and #1052 is the only open PR that touches it.

The second commit's trailer is Co-Authored-By: Claude Sonnet 5.5 (the first commit's is Opus 5.5). The squash message decides what lands.

Tests at this head, one file at a time under a stub gh (exit 97), GH_TOKEN=bogus, an empty GH_CONFIG_DIR, GIT_SSH_COMMAND=false: test_repo_hygiene 100, test_agents_md_codes 47, test_readme_sections 76, test_no_auto_maintenance 60, all passed.

Merges (git merge-tree --write-tree): clean with origin/main 8a05721, with #1046 c121ed9, with #1052 396668b, and main + #1051 + #1046 together. In that three-way tree, README is 1482 against a cap of 1482 (1422 + 60) and AGENTS.md is 494; #1046 moves only the adopt marker, so the seven markers stay 8f25ef0d.

Body: closingIssuesReferences is empty, no closing word, and it ends Part of #921, Part of #923, the Lane line and the robot line, before Sourcery's block.

Lane: openreposhape-3 (openRepoShape-3)

[sourcery-ai]

Sorry @brettheap, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 1 day and 6 hours by commenting @sourcery-ai review. Upgrade to get a review now.