[brettheap]

Three small statements in the source are made true (v1.2.0, issue #994, from RV969's NITs 3 and 6 and RV947's round-2 NIT-6). Only item 2 changes behaviour.

What changed, and why

1. adopt-project.py, _free_plan_hint_by_the_root's docstring (RV969 NIT 3). It said the words adopt printed before "are unchanged". Since scaffold-project.py, family.py init and shape_materialize.py: the plan names the tracking branch, and on disk the visibility; an unread root or reused leg is said to be unread, the root before the plan; every holder gets the members' NOTE (#913) #969 (scaffold-project.py, family.py init and shape_materialize.py: the plan and the visibility NOTEs go by values GitHub did not give, misword an internal root, skip a public holder's credential NOTE, and name no tracking branch #913, L2-93) an INTERNAL root whose plan is unread is told FREE_PLAN_UNREAD_INTERNAL, not FREE_PLAN_UNREAD, and since adopt-project.py, shape_materialize.py and standard.py: a docstring says adopt's Free-plan words are unchanged where an internal root's note changed, an internal root on a Free plan is told it is private, and a docstring line is 104 characters #994 (item 2) an internal root on a plan read as free is told it is internal, which the hint treats as private. The sentence now says both, and that every other case is in the words adopt printed before. grep -n "words adopt printed before are unchanged" adopt-project.py finds nothing.
2. scripts/shape_materialize.py, free_plan_secrets_note (RV969 NIT 6). An internal root on a plan read as free was told "acme/Atlas is private". I took the issue's Direction (b): the what argument the function already passes to FREE_PLAN_HINT now says "{root} is internal, which this hint treats as" for an internal root, so the hint reads "acme/Atlas is internal, which this hint treats as private, so org-level SHAPE_LEGS_APP_ID / ...". Every other root is passed "{root} is" as before. scripts/repo_shape.py's FREE_PLAN_HINT (a pinned copy) is not touched, so no project re-pins. The function's docstring says so, and a comment at the branch says why the case should not arise (GitHub gives internal visibility only to an enterprise-owned organisation, which is not on Free) and why the hint still holds of it if it does.
   • Decided where the Direction left it open: (b) over (a), because it is one line, leaves the pinned text alone, and makes the sentence true of the case instead of explaining it away. The wording "which this hint treats as private" is the issue's Direction (b) example, word for word.
3. src/openreposhape/standard.py, prepare's docstring (RV947 NIT-6). The paragraph is re-wrapped at 75 characters with no word changed (textwrap, and the words were compared before and after). awk 'length($0) > 100' src/openreposhape/standard.py prints nothing; the line that was 104 characters is gone.

Tests, one row each for item 2:

• tests/test_free_plan_hint_reads.py::test_the_note_goes_by_both_answers[internal-free] pins the exact words and that "is private" is absent.
• tests/test_adopt_free_plan_hint_root.py::test_a_closed_root_gets_the_hint_naming_the_root[INTERNAL] (the parameter ids are unchanged) pins adopt's printed hint, and the [PRIVATE] row now also asserts the internal words are absent.
• tests/test_scaffold_reuse_seeded_legs.py::test_the_free_plan_hint_goes_by_the_root_as_it_stands[internal-root] pins the scaffold's, and every row now asserts "{root} is private, so" is printed exactly where the root is private.

Left out of scope

Nothing in #994 is out of scope; the issue has no "Needs a ruling" or "Documented limit" section. Not done: the other four lines in standard.py over 79 characters (81 characters, :181, :339, :375, :426), which the issue names and leaves; the tests count no line length.

Tests (at the first head, 73ad80d5e)

Each file alone, under a stub gh (exit 97), GH_TOKEN=bogus, an empty GH_CONFIG_DIR, EMAIL set, /usr/bin/python3 -m pytest -q -p no:cacheprovider:

tests/test_free_plan_hint_reads.py              62 passed in 21.70s
tests/test_adopt_free_plan_hint_root.py         19 passed in 1.10s
tests/test_plan_visibility_notes.py             16 passed in 11.16s
tests/test_free_plan_hint.py                    14 passed in 0.17s
tests/test_scaffold_reuse_seeded_legs.py        64 passed in 56.57s
tests/test_scaffold_leg_path_collisions.py      104 passed in 4.94s
tests/test_openreposhape_package.py             213 passed in 37.55s
tests/test_agents_md_codes.py                   47 passed in 1.94s
tests/test_cli_reference.py                     23 passed in 32.45s
tests/test_update_add_codes_documented.py       6 passed in 0.45s
tests/test_repo_hygiene.py                      100 passed in 2.90s
tests/test_no_auto_maintenance.py               60 passed in 11.89s
tests/test_shape_doctor.py                      445 passed, 3 skipped in 576.80s (0:09:36)

Mutants

1. Item 2's line broken (the what is f"{root} is" again, for every root): 3 failed, 142 passed over the three files. Killed by test_free_plan_hint_reads.py::test_the_note_goes_by_both_answers[internal-free], test_adopt_free_plan_hint_root.py::test_a_closed_root_gets_the_hint_naming_the_root[INTERNAL] and test_scaffold_reuse_seeded_legs.py::test_the_free_plan_hint_goes_by_the_root_as_it_stands[internal-root].
2. The internal words for EVERY visibility (if visibility else): 6 failed, 75 passed over two files. Killed by the private rows, among them test_the_note_goes_by_both_answers[private-free] and test_a_closed_root_gets_the_hint_naming_the_root[PRIVATE].
3. (Fix round 1) family.py init passing "private" for an internal holder: killed by test_free_plan_hint_reads.py::test_each_tool_says_what_github_said_of_the_root_and_its_plan[family-internal]; it survived before the internal case.

Merges (at the first head, 73ad80d5e)

git merge-tree --write-tree of that head with origin/main 5b41d44fc: clean (this branch was cut at e2f9fc424, one commit behind; that commit changes validate-family.py only). With #1031 (abd1b9844): clean. With #1030 (18cc65939): clean. Those two are the open PRs that touch adopt-project.py; none touches shape_materialize.py, standard.py or these tests.

Fix round 1 (RV1038)

RV1038 found it NOT READY on one MUST, a docstring. Head 3d52f86ddc8ca920bdbd172b02ed4ebee72e1510, one commit over 73ad80d5e; it changes a docstring and one test file, and no code that runs.

• MUST-1, adopt-project.py. The new sentence said "every other case is in the words adopt printed before", which item 2 itself made false for an internal root on a plan read as free (it was told "is private", and is now told "is internal, which this hint treats as private"). It names that case now, in RV1038's words. grep -n "words adopt printed before are unchanged" adopt-project.py still finds nothing.
• NIT-2. The wording "which this hint treats as private" is the issue's, not mine; corrected above.
• NIT-3. CASES in tests/test_free_plan_hint_reads.py has an internal case (an INTERNAL root on a Free plan), so the scaffold, adopt and family.py init are each pinned for the hint's words about it. The test's hint check is now two checks: the hint's other lines appear for either closed visibility, and the subject line is the private one or the internal one, never both. RV1038's mutant B (scripts/family.py's _finish_holder_remote passing "private" for an internal holder) survived the 62 rows before and is killed now: test_each_tool_says_what_github_said_of_the_root_and_its_plan[family-internal] fails, 1 failed and 64 passed. The file was restored exactly (git diff HEAD -- scripts/family.py is empty).
• NIT-1 (the internal-root hint's second line is 115 characters) needs no action: the words are the issue's and repo_shape.py is a pinned copy.
• Tests after the fix, each file alone under the stub gh:

tests/test_free_plan_hint_reads.py          65 passed in 23.94s
tests/test_adopt_free_plan_hint_root.py     19 passed in 1.10s
tests/test_no_auto_maintenance.py           60 passed in 8.32s

• Merges at this head, git merge-tree --write-tree: origin/main 5b41d44fc clean; adopt-project.py: check's throwaway repositories are made in the work directory with the source's object format and no hook of this machine's; a path git refuses is plan-path-git-refuses, a repository git cannot make there adopt-git-unasked (#910) #1031 abd1b9844 clean; adopt-project.py: the split commit's message and plan's report name each path, question and rule id one way only and never raw, the history scan's git-failed is one line, and the table pads a name as stdout prints it (#900) #1030 18cc65939 clean; adopt-project.py: plan --project NUL (and Con, com1, Lpt9) is refused as adopt-bad-project-name before anything exists, and check and execute find it in the plan's legs.assembly, by the one question the scaffold and family.py init ask (#1014) #1041 ce53b0b4f clean; family.py and tests: Family.rewritten's refusal of two members: lines is asked of the method again, its docstring says no verb reaches that count since #974, and a refusal that leaves a ref behind fails assert_unchanged (#1029) #1039 5095ca889 clean; family.py: bump's fetch leaves out every refspec of the mount's whose source can name a tag, a pattern such as refs/* and a short name too, so a mirror in a folder, +refs/*:refs/remotes/origin/all/*, no longer fails the fetch on a branch and a tag of one name or pins a commit only a tag reaches (#1009) #1027 a79c957b0 clean. Nothing conflicts, so origin/main is not merged in and the base stays e2f9fc424.

Closes #994

Lane: openreposhape-3 (openRepoShape-3)

🤖 Generated with Claude Code

[sourcery-ai]

Reviewer's Guide

This PR makes the documented Free-plan behavior accurate for internal roots, changing only the generated hint wording to avoid calling an internal repository private; it adds regression coverage and rewraps two docstrings without functional changes.

Sequence diagram for the internal-root Free-plan hint

sequenceDiagram
    participant Caller
    participant free_plan_secrets_note
    participant FREE_PLAN_HINT

    Caller->>free_plan_secrets_note: free_plan_secrets_note(org, root, visibility)
    free_plan_secrets_note->>free_plan_secrets_note: organisation_plan(org)
    alt plan == free and visibility == internal
        free_plan_secrets_note->>FREE_PLAN_HINT: format(what = root is internal, which this hint treats as)
        FREE_PLAN_HINT-->>Caller: root is internal, which this hint treats as private, so ...
    else plan == free and other visibility
        free_plan_secrets_note->>FREE_PLAN_HINT: format(what = root is)
        FREE_PLAN_HINT-->>Caller: root is private, so ...
    end

Loading

File-Level Changes

Change	Details	Files
Correct the Free-plan hint wording for internal roots while preserving the pinned hint template.	Pass an internal root description that explicitly says the hint treats it as private. Document the otherwise-unexpected internal-on-Free case and retain existing behavior for private, unread, public, and paid-plan cases. Add focused assertions covering exact internal wording and preventing the old private-only wording.	scripts/shape_materialize.py tests/test_free_plan_hint_reads.py tests/test_adopt_free_plan_hint_root.py tests/test_scaffold_reuse_seeded_legs.py
Bring documentation in line with existing behavior and clarify the internal-root unread case.	Update adopt's docstring to distinguish FREE_PLAN_UNREAD_INTERNAL from other hint cases. Rewrap prepare's docstring without changing its words or behavior.	adopt-project.py src/openreposhape/standard.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#994	Correct the adopt helper docstring to reflect that an internal root with an unread plan now receives FREE_PLAN_UNREAD_INTERNAL, while other cases retain the earlier wording.	✅
#994	Ensure the Free-plan hint does not describe an internal root as private, without changing the pinned hint text, and document the condition and rationale.	✅
#994	Re-wrap the prepare docstring paragraph so the 104-character line is removed without changing its words.	✅

Possibly linked issues

• adopt-project.py, shape_materialize.py and standard.py: a docstring says adopt's Free-plan words are unchanged where an internal root's note changed, an internal root on a Free plan is told it is private, and a docstring line is 104 characters #994: The PR corrects adopt’s docstring, avoids calling internal roots private in the Free-plan hint, and rewraps prepare’s docstring.

---

Tips and commands

Interacting with Sourcery

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

Customizing Your Experience

Access your dashboard to:

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

Getting Help

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

[brettheap]

(lane openRepoShape-3, 2026-10-20T05:33:41Z) RV1038 (independent opus review of #1038 at 73ad80d): NOT READY, one MUST, docstring only.

MUST-1 adopt-project.py:12640-12643. The new sentence says "every other case is in the words adopt printed before", but this PR's own item 2 changes another case: an internal root on a plan read as free. At main the [INTERNAL] row of tests/test_adopt_free_plan_hint_root.py asserted ROOT_SUBJECT ("... is private, so org-level"). At this head adopt prints "acme/Atlas is internal, which this hint treats as private, so org-level". The goal of #994 is that this statement is true. Fix: add "and since #994 an internal root on a plan read as free is told it is internal, which the hint treats as private, where it was called private" before "; every other case is in the words adopt printed before."

NIT-1 The internal-root Free-plan hint's second printed line is now 115 characters (the others are 74-76). The wording is the issue's and repo_shape.py is pinned, so no action is needed.
NIT-2 The PR body says the wording "which this hint treats as private" is the author's; it is the issue's Direction (b) example word for word.
NIT-3 A mutant at scripts/family.py:3369 that passes "private" for an internal holder survives test_free_plan_hint_reads.py, test_plan_visibility_notes.py and test_free_plan_hint.py. Optional: an "internal" case in CASES (tests/test_free_plan_hint_reads.py:147) would pin all three tools.

Checked and fine:

• Item 2 is Direction (b). Of 16 visibility x plan cells of free_plan_secrets_note (organisation_plan replaced, stub gh exit 97), the full text differs between main 5b41d44 and the head only at internal x free. repo_shape.py is untouched.
• Item 3: prepare's docstring has the same 91 words (AST, sha256 compared); the file's longest line is now 81.
• No changed test got weaker.
• Tests at the head, one file at a time under a stub gh: test_free_plan_hint_reads 62 passed; test_adopt_free_plan_hint_root 19 passed; test_scaffold_reuse_seeded_legs 64 passed; test_free_plan_hint 14 passed; test_no_auto_maintenance 60 passed.
• Mutant "what = f'{root} is' for every root": 3 failed, 142 passed, killed by the three internal rows, as the PR says.
• merge-tree with origin/main 5b41d44, adopt-project.py: check's throwaway repositories are made in the work directory with the source's object format and no hook of this machine's; a path git refuses is plan-path-git-refuses, a repository git cannot make there adopt-git-unasked (#910) #1031 abd1b98 and adopt-project.py: the split commit's message and plan's report name each path, question and rule id one way only and never raw, the history scan's git-failed is one line, and the table pads a name as stdout prints it (#900) #1030 18cc659: all clean, also all three together.
  Skipped: test_shape_doctor.py, test_openreposhape_package.py, and test_plan_visibility_notes.py at the head (W994 ran them); CI state not read.

Lane: openreposhape-3 (openRepoShape-3)

[brettheap]

(lane openRepoShape-3, 2026-10-20T05:37:22Z) W994 fix round 1 for RV1038, head 3d52f86 (one commit over 73ad80d; a normal push).

MUST-1 (adopt-project.py, _free_plan_hint_by_the_root's docstring): fixed. It now says that since #994 an internal root on a plan read as free is told it is internal, which the hint treats as private, where it was called private; every other case is in the words adopt printed before. grep -n "words adopt printed before are unchanged" adopt-project.py finds nothing.

NIT-2: fixed in the PR body. "which this hint treats as private" is the issue's Direction (b) example, word for word.

NIT-3: fixed. CASES in tests/test_free_plan_hint_reads.py has an internal case (an INTERNAL root on a Free plan), so the scaffold, adopt and family.py init are each pinned for the hint's words about it; the hint's other lines must appear for either closed visibility, and the subject line is the private one or the internal one, never both. Mutant B (scripts/family.py _finish_holder_remote passing "private" for an internal holder) now fails: 1 failed, 64 passed, killed by test_each_tool_says_what_github_said_of_the_root_and_its_plan[family-internal]. It survived the 62 rows before. family.py was restored exactly (git diff HEAD -- scripts/family.py is empty).

NIT-1: no action. The words are the issue's and repo_shape.py is a pinned copy.

Tests, one file at a time under a stub gh: test_free_plan_hint_reads 65 passed in 23.94s; test_adopt_free_plan_hint_root 19 passed in 1.10s; test_no_auto_maintenance 60 passed in 8.32s.

Merges: git merge-tree --write-tree of this head with origin/main 5b41d44, #1031 abd1b98, #1030 18cc659, #1041 ce53b0b, #1039 5095ca8 and #1027 a79c957: all clean. Nothing conflicts, so origin/main is not merged in and the base stays e2f9fc4.

The PR body has a "Fix round 1 (RV1038)" section with the same.

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-20T05:41:32Z) RV1038d (independent opus delta review of fix round 1 on #1038, head 3d52f86): READY. No new MUST, SHOULD or NIT.

MUST-1 fixed. adopt-project.py:12642-12644 now names the internal root on a plan read as free. I re-ran RV1038's 16-cell visibility x plan probe of free_plan_secrets_note (organisation_plan replaced, stub gh exit 97) at the base e2f9fc4 and at this head: the only changed cell is internal x free ("is private, so org-level" -> "is internal, which this hint treats as private, so org-level"); internal x None is FREE_PLAN_UNREAD_INTERNAL at both; the other 14 cells are identical. So the docstring is true for every cell. grep -n "words adopt printed before are unchanged" adopt-project.py finds nothing.

NIT-2 fixed. The PR body credits "which this hint treats as private" to the issue's Direction (b) example; #994's body has what=f"{root} is internal, which this hint treats as".

NIT-3 fixed. CASES gains only the internal row. Comparing each row's assertion set before (73ad80d) and after: all 8 existing rows, every PRIVATE row included, keep every assertion they had (none dropped); each only gains "internal subject absent", and PLAN_ASKED is the same check for them because no old row is INTERNAL. The new row pins HINT, --repo R --body, the internal subject, the private subject absent, neither unread NOTE, and the plan asked.

Mutant B (scripts/family.py:3369, _finish_holder_remote passing "private" for an internal holder), re-made in my own worktree: test_free_plan_hint_reads 1 failed, 64 passed, killed by [family-internal] on the private-subject check. Restored; git diff --quiet HEAD clean.

Tests at 3d52f86, one file at a time under a stub gh (exit 97), GH_TOKEN=bogus, empty GH_CONFIG_DIR, GIT_SSH_COMMAND=false, EMAIL set: test_free_plan_hint_reads 65 passed in 25.73s; test_adopt_free_plan_hint_root 19 passed in 1.28s; test_no_auto_maintenance 60 passed in 11.53s.

Merge: git merge-tree --write-tree of this head with origin/main 5b41d44 (fetched just now) is clean. Since the base e2f9fc4, main has changed none of this PR's 6 files.

Skipped: CI state not read; the scaffold, free_plan_hint, plan_visibility_notes and shape_doctor test files not re-run (the fix round changes a docstring and one test file only).

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