[brettheap]

Lane: openreposhape-2 (openRepoShape-2)
Claim: #660 (comment)

Lands after #621 (on main as 4ce9045). This branch is cut from it.

The Free-plan secrets hint (FREE_PLAN_HINT) holds when the repository whose validate workflow reads SHAPE_LEGS_APP_ID and SHAPE_LEGS_APP_PRIVATE_KEY (the assembly root, or the family holder) is private or internal AND its organisation is on the GitHub Free plan. That is two questions for GitHub, and either can go unanswered. Since #621 adopt and the scaffold ask the first one of the root. This PR asks both questions in all three tools, in one place, and says which answer GitHub did not give instead of guessing.

What changed

scripts/shape_materialize.py (new, beside refuse_unless_not_found). This file is not a shape copy, so nothing re-pins.

• visibility_in(answer) reads a gh repo view --json visibility answer. It returns one of GitHub's three visibilities, in any case, or None.
• repository_visibility(repository) is the one visibility reader for the scaffold and family.py. A failed gh repo view is None. A gh that cannot be started is left to the caller, because the scaffold still refuses that as gh-not-found (family.py init --dry-run and scaffold-project.py --dry-run exit 0 without asking whether the remotes already exist #537).
• organisation_plan(org) returns "free", "other", "not-an-organisation", or None (unread).
  • "not-an-organisation" is gh's not-found answer to gh api orgs/<owner>. GitHub answers 404 there when the owner is a personal account, which has no organisation secrets (review round 1, F1).
  • None covers every other failure (a 403, a 502, a gh that cannot be started) and an answer that names no plan.
  • The command goes through subprocess.run, because the not-found reading is of the command's own stderr, which run folds into stdout.
• gh_said_not_found(probe, words) is scaffold-project.py and family.py init: the dry runs skip the target-exists and folder checks, and any gh repo view failure reads as "does not exist" #609's reading of gh's not-found answer (exit 1, gh's words on stderr), taken out of refuse_unless_not_found, which now asks it. It takes gh's words for each API:
  • GH_NOT_FOUND_WORDS for gh repo view (GraphQL), as before;
  • the new GH_API_NOT_FOUND_WORDS, Not Found (HTTP 404), for gh api (REST).
• free_plan_secrets_note(org, root, visibility) is the decision all three tools now share:
  • unread root: ROOT_VISIBILITY_UNREAD (moved here from adopt, word for word), and the plan is not asked;
  • public root: nothing;
  • private or internal root on free: FREE_PLAN_HINT, with the root alone as its subject;
  • private or internal root whose plan is unread: the new FREE_PLAN_UNREAD;
  • any other plan, or an owner that is not an organisation: nothing.

scripts/family.py (L2-58, L2-71). _finish_holder_remote now takes reuse.

• A holder that --reuse-empty-repo reused is asked of GitHub (repository_visibility), and the NOTE and the hint go by that answer.
• A holder this run created goes by --visibility, as before: it was created at that visibility.
• An unread reused holder gets ROOT_VISIBILITY_UNREAD and no NOTE. Whether it is private is exactly the question that went unanswered.
• The hint's subject is f"{repository} is", the holder alone, as the scaffold and adopt say it since adopt-project.py and scaffold-project.py: the Free-plan secrets hint goes by the assembly root's own visibility on GitHub and names the root as its reason, so a public source adopted with private legs is no longer told its organisation secrets resolve to EMPTY (#602) #621.
• The NOTE no longer says "and its members will be too" (decision below).

scaffold-project.py (L2-57).

• remote_visibility is now repository_visibility, plus the same gh-not-found refusal, in the same words, for the same argv.
• _create_remotes no longer falls back to or args.visibility for a reused root, so an unread root stands as None.
• _private_leg_note prints free_plan_secrets_note.

adopt-project.py (L2-59).

• _free_plan_hint_by_the_root prints free_plan_secrets_note.
• _root_visibility keeps its own gh call, through adopt's run, and reads the answer with visibility_in.
• ROOT_VISIBILITY_UNREAD now lives in shape_materialize.py, and import json is gone (its only user was the parse).
• Adopt's messages are byte for byte as before. The probe below compares stdout and the gh call log for four cases.

scripts/repo_shape.py is untouched. FREE_PLAN_HINT's text stays. free_plan_secret_hint stays too: the three tools no longer call it, and removing it from the pinned copy would re-pin every project.

New messages, as a probe printed them (stub gh, testorg):

NOTE this run could not read testorg's plan from GitHub, so it cannot say whether the Free-plan secrets hint applies. testorg/Atlas is private, so it applies when testorg is on the GitHub Free plan: organisation secrets are then not delivered to testorg/Atlas, so org-level SHAPE_LEGS_APP_ID / SHAPE_LEGS_APP_PRIVATE_KEY resolve to EMPTY in its `validate` workflow and must be set as REPOSITORY secrets on testorg/Atlas instead. `gh api orgs/testorg --jq .plan.name`, run with an owner's login, says which plan it is on.

init's NOTE, before:

NOTE testorg/Orbit is private and its members will be too: give it a way to read them — a GitHub App (SHAPE_LEGS_APP_ID + SHAPE_LEGS_APP_PRIVATE_KEY, preferred) or a SHAPE_LEGS_TOKEN PAT with contents:read on the members AND their legs — or the `validate` check cannot check them out.

and after:

NOTE testorg/Orbit is private: give it a way to read the members you add that are private or internal — a GitHub App (SHAPE_LEGS_APP_ID + SHAPE_LEGS_APP_PRIVATE_KEY, preferred) or a SHAPE_LEGS_TOKEN PAT with contents:read on the members AND their legs — or the `validate` check cannot check them out.

init's hint: "testorg/Orbit and its members are private, so org-level ..." is now "testorg/Orbit is private, so org-level ...". The scaffold over a reused root whose visibility read fails (HTTP 502) printed the hint ("testorg/Atlas is private, so org-level ..."), whatever the root was. It now prints ROOT_VISIBILITY_UNREAD, adopt's NOTE: "NOTE this run could not read testorg/Atlas's visibility from GitHub, so it cannot say whether the Free-plan secrets hint applies. ...".

Decisions the issue left open

• family.yaml's visibility: records the run's value, not the value read from GitHub.
  • L2-58's own direction says this field "is L2-23's question for the family". L2-23 is a confirmed known limit on Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459: the field records the run's value, and its comment is to be reworded when the template is next touched. So this PR does not change what the field means.
  • Recording the read value would need the read before the manifest is rendered. refuse_unholdable_manifest checks that very table before the plan, and before _checked_reuse knows whether a holder exists. So either a gh repo view --json visibility would come ahead of the existence check in both runs, or family.yaml would be written from a table other than the one that was checked. The first moves the first gh question that tests/test_dry_run_asks_remotes.py pins for init --reuse-empty-repo with no gh.
  • The other two tools do the same: the scaffold records the run's explicit --visibility over a reused root that disagrees (tests/test_reuse_visibility.py), and adopt records the plan's while its root keeps its own.
  • test_init_notes_a_reused_holder_at_its_own_visibility pins this, so a later change to it is a deliberate one.
• The NOTE's "and its members will be too" is dropped (DB11). init mounts no member, and add mounts a member of any visibility, so nothing here decides what that sentence promised. The NOTE now names the members it is about: those you add that are private or internal. It is still printed only for a closed holder, as before, and now by the holder's own visibility.
• Adopt and the one reader. Adopt keeps its own gh call in _root_visibility and shares only the reading (visibility_in). Its 11 reader tests (adopt-project.py and scaffold-project.py: the Free-plan secrets hint goes by the assembly root's own visibility on GitHub and names the root as its reason, so a public source adopted with private legs is no longer told its organisation secrets resolve to EMPTY (#602) #621) monkeypatch adopt.run, so a call through shape_materialize.run would escape them.
• An unread root does not ask the plan. ROOT_VISIBILITY_UNREAD already names both conditions, so it holds whatever the plan is. This keeps adopt-project.py and scaffold-project.py: the Free-plan secrets hint goes by the assembly root's own visibility on GitHub and names the root as its reason, so a public source adopted with private legs is no longer told its organisation secrets resolve to EMPTY (#602) #621's behaviour and its gh calls in adopt.
• The rider stopped at one reader and its callers. L2-59 is organisation_plan, the one decision function the three callers share, the three call sites, and the one test that named the old function (test_every_creating_tool_calls_the_hint). No README or template edit was needed. README.md:631 ("the creating tools check and say so") is still true.
• FREE_PLAN_UNREAD's last clause, "run with an owner's login", rests on GitHub's REST page for GET /orgs/{org} ("the authenticated user must be an organization owner" for the full details). It is not measured: no probe here reached GitHub.

Tests

New file tests/test_free_plan_hint_reads.py, 50 tests (38, and 12 from review round 1):

file	test	what it pins
tests/test_free_plan_hint_reads.py	test_each_tool_says_what_github_said_of_the_root_and_its_plan (scaffold, adopt, family × public, private, visibility-502, visibility-403, plan-502, not-an-organisation, plan-unnamed, paid; 24)	in each tool: the hint only for a root GitHub calls private on a plan it calls free, naming the root alone; ROOT_VISIBILITY_UNREAD for a root whose --json visibility read fails (HTTP 502, or a SAML 403), with the plan not asked; FREE_PLAN_UNREAD for a plan read that fails or names no plan; nothing for a public root, a paid plan, or an owner gh says is no organisation (gh: Not Found (HTTP 404)); never "its members"; the root's visibility is asked
tests/test_free_plan_hint_reads.py	test_init_notes_a_reused_holder_at_its_own_visibility (public, private, internal, visibility-502, visibility-404)	init's NOTE goes by GitHub's answer, in the new words; no NOTE for an unread holder; family.yaml keeps the run's visibility
tests/test_free_plan_hint_reads.py	test_init_asks_nothing_of_a_holder_it_creates	a holder init creates gets the NOTE and the hint at the run's visibility, and GitHub is not asked
tests/test_free_plan_hint_reads.py	test_init_takes_a_holder_gh_cannot_be_asked_about_as_unread	in process, every platform: a reused holder whose visibility read cannot start gh (OSError) gets ROOT_VISIBILITY_UNREAD, and no NOTE or hint at the run's --visibility
tests/test_free_plan_hint_reads.py	test_the_plan_is_free_other_or_unread (11)	organisation_plan, through a faked subprocess.run: free, free with whitespace, team, enterprise, empty, blank line, a REST 404 (not an organisation), a SAML 403, a 502, a 502 whose stdout carries a 404 body, and no gh
tests/test_free_plan_hint_reads.py	test_a_visibility_read_is_one_of_three_or_unread	repository_visibility: lowercased, an unknown word unread, a failed gh unread, a missing gh raised to the caller
tests/test_free_plan_hint_reads.py	test_the_note_goes_by_both_answers (7)	free_plan_secrets_note: each answer pair, not-an-organisation included, and the plan asked only of a closed root
tests/test_scaffold_reuse_seeded_legs.py	fake_gh	two new stub knobs: visibility_errors (fails only repo view --json visibility) and plan_error (fails api orgs/<org>)
tests/test_adopt_free_plan_hint_root.py	create_the_legs	passes fake_gh's other keywords through
tests/test_free_plan_hint.py	test_every_creating_tool_calls_the_hint, and the module docstring	each tool calls free_plan_secrets_note with its own organisation; the docstring says the file's silence tests are free_plan_secret_hint's, which no tool calls since #660 (F7)

• Red at the base (main + adopt-project.py and scaffold-project.py: the Free-plan secrets hint goes by the assembly root's own visibility on GitHub and names the root as its reason, so a public source adopted with private legs is no longer told its organisation secrets resolve to EMPTY (#602) #621, with only the tests): 31 failed, 7 passed. The 7 are the cases adopt-project.py and scaffold-project.py: the Free-plan secrets hint goes by the assembly root's own visibility on GitHub and names the root as its reason, so a public source adopted with private legs is no longer told its organisation secrets resolve to EMPTY (#602) #621 already fixed: scaffold public, private and paid; adopt public, private, visibility-502 and paid.
• Mutants: 15 of 15 killed, each by at least one new test. The files were restored byte-exact afterwards (sha256 checked).
  • M1, family.py skips the holder read: 9 failed, among them [family-public].
  • M2, an unread holder taken as the run's: [family-visibility-502] and test_init_notes_...[visibility-502].
  • M3, the NOTE says "and its members will be too" again: 7 failed, among them [family-private].
  • M4, the hint's subject " and its members are": 12 failed.
  • M5, the scaffold takes an unread root as the run's: [scaffold-visibility-502].
  • M6, an unnamed plan read as other: 5 failed, among them [*-plan-unnamed].
  • M7, a failed plan read as other: 5 failed, among them [*-plan-502].
  • M8, an unread plan left silent: 7 failed.
  • M9, an unread root left silent: 6 failed.
  • M10, a public root asks the plan: 9 failed, among them [*-public].
  • M11, repository_visibility swallows a missing gh: the unit test and both scaffold gh-not-found tests in test_dry_run_asks_remotes.py.
  • M12, no lowercasing: 36 failed.
  • M13, an unknown word kept: the unit test and adopt-project.py and scaffold-project.py: the Free-plan secrets hint goes by the assembly root's own visibility on GitHub and names the root as its reason, so a public source adopted with private legs is no longer told its organisation secrets resolve to EMPTY (#602) #621's [unknown-word].
  • M14, adopt asks the plan of no organisation: 7 failed.
  • M15, the plan name not lowercased: [free-spaced].
• Review round 1, mutants: 4 of 4 killed (against test_free_plan_hint_reads.py, test_adopt_free_plan_hint_root.py, test_dry_run_asks_remotes.py, test_free_plan_hint.py and test_scaffold_reuse_seeded_legs.py; files restored byte-exact).
  • rv660-R2, init takes an unstartable gh as the run's visibility: test_init_takes_a_holder_gh_cannot_be_asked_about_as_unread. It survived all 129 tests before this round.
  • F1-a, the not-found reading reverted: [scaffold|adopt|family-not-an-organisation] and the unit row.
  • F1-b, every exit-1 failure read as not an organisation: [*-plan-502], [saml-403] and 2 more.
  • F1-c, the plan read with GraphQL's not-found words: the same 4 as F1-a.
• Red before round 1's fix (bc8c73b's shape_materialize.py, the new tests): 4 failed, 46 passed. The 4 are the three tools' not-an-organisation rows and the unit row.
• Targeted, on Linux. CI runs the whole suite on this PR.
  • Review round 1 at 0b97f1a: 806 passed, 3 skipped. The 10 files are the 4 this PR's tests change (test_free_plan_hint_reads.py, test_free_plan_hint.py, test_adopt_free_plan_hint_root.py, test_scaffold_reuse_seeded_legs.py), test_shape_doctor.py, test_scaffold_leg_path_collisions.py, test_dry_run_asks_remotes.py, and the 3 that name refuse_unless_not_found or remote-unreadable (test_adopt_github_exits.py, test_adopt_split_branch.py, test_dry_run_parity.py).
  • Round 0: 36 files at main 879d804 + adopt-project.py and scaffold-project.py: the Free-plan secrets hint goes by the assembly root's own visibility on GitHub and names the root as its reason, so a public source adopted with private legs is no longer told its organisation secrets resolve to EMPTY (#602) #621 + this diff, in a scratch repository: 2896 passed, 4 skipped. The same 36 files at bc8c73b were stopped for an account swap at about 82%, with 2398 passed and 0 failed.
• The round-0 36 files are every tests/test_scaffold*.py, test_family*.py and test_adopt*.py that names free_plan, FREE_PLAN, visibility or ROOT_VISIBILITY, every test file that names a function or message this changes, test_free_plan_hint.py, test_reuse_visibility.py, test_dry_run_asks_remotes.py, test_family.py, test_dry_run_parity.py, test_push_branch_refspec.py, test_ruleset_hint_tracking_branch.py, test_repo_hygiene.py, test_cli_reference.py, test_agents_md_codes.py, test_shape_doctor.py and test_scaffold_leg_path_collisions.py.
• scripts/render-cli-reference.py --check: ok, because no --help text changed.
• pyflakes: the same 6 warnings as main in the four files (L2-65), and none in the new test file.
• Probe. A stub gh that exits 97 on anything it was not given, GH_TOKEN=bogus, an empty GH_CONFIG_DIR and an isolated HOME ran each tool at the base and at this change.
  • adopt's stdout and gh calls are byte-identical before and after for private on Free, public, internal on a paid plan, and an unread root.
  • The before and after texts above are from the same probe.
  • Review round 1: with api orgs/someuser answered gh: Not Found (HTTP 404) on stderr, the 404 JSON body on stdout and exit 1, these runs printed FREE_PLAN_UNREAD at bc8c73b and print nothing about the plan at 0b97f1a: the scaffold (--org someuser, reused and fresh), init (reused and created) and adopt. A testorg plan read that fails with 502 still prints FREE_PLAN_UNREAD.

Review round 1 (rv660, CHANGES REQUIRED)

• F1 (should-fix): a personal account got FREE_PLAN_UNREAD, and its remedy (gh api orgs/<owner> --jq .plan.name) can never answer for one. GitHub answers GET /orgs/<login> 404 where the login is not an organisation. Now gh's not-found answer there is "not an organisation", and nothing is printed: a personal account has no organisation secrets. The answer is read by scaffold-project.py and family.py init: the dry runs skip the target-exists and folder checks, and any gh repo view failure reads as "does not exist" #609's reading (gh_said_not_found), taken out of refuse_unless_not_found rather than written twice. Every other failure stays FREE_PLAN_UNREAD.
• F8: rv660-R2 (except OSError: visibility = args.visibility in scripts/family.py) survived every test. It is now killed by a new in-process test. The table gains a 403 visibility row in each tool, and init's test a 404 row.
• F7: tests/test_free_plan_hint.py's docstring now says its silence tests are free_plan_secret_hint's, which no tool calls since the Free-plan hint's reads: a public reused holder gets the "private" NOTE and hint, an unread root is taken as the run's visibility, and an unread plan is silent #660, and what the tools do instead.
• rv660's F2-F6 are held for Tracking: setup, scaffold, family and the shared helpers, creating projects and families #459 until this lands, and are not changed here.

Not changed

• The scaffold's reused LEG whose visibility cannot be read still takes the run's (_reused_leg_visibility, return seen or args.visibility, scaffold-project.py:1348). It decides only the per-leg NOTE and whether the hint is asked at all. the Free-plan hint's reads: a public reused holder gets the "private" NOTE and hint, an unread root is taken as the run's visibility, and an unread plan is silent #660 is about the root.
• _leg_visibility's return reused_visibility or "private" (scaffold-project.py:1135) is the visibility a NEW leg is created at when the root cannot be read and no --visibility was given. It is a creation default, and nothing claims it of the root.
• family.yaml's visibility: for a reused holder records the run's value (scripts/family.py:1708; L2-23, a known limit).
• init's plan line remotes gh repo create --private prints under --reuse-empty-repo too (scripts/family.py:1759). The next line says the holder is reused.
• init's NOTE is still gated on the holder being closed, so a public holder whose members will be private gets no credential NOTE at init. The gate is as before.
• README.md and the templates: nothing. README's "If the legs are private" sentence is README.md and the handbook: the sentences #566, #572 and #573 leave false or incomplete (an ambiguous record that arrives answered, the spec mount's CONTRACTS_DIR, a second setup run refused at the plan) #606's (L2-66).

Closes #660

🤖 Generated with Claude Code

Summary by Sourcery

Make Free-plan secrets guidance reflect GitHub’s reported repository visibility and organisation plan without guessing when either value is unavailable.

New Features:

• Add shared handling for repository visibility and organisation-plan responses when deciding Free-plan secrets guidance.
• Report explicit guidance when GitHub cannot determine a repository’s visibility or organisation plan.

Bug Fixes:

• Prevent reused public roots or family holders from being incorrectly treated as private based on the run’s requested visibility.
• Avoid silently treating unread organisation plans as paid and distinguish personal-account owners from unread organisation plans.
• Stop describing family members as private when only the holder’s visibility is known.

Enhancements:

• Centralize visibility parsing, organisation-plan classification, and Free-plan secrets notes across scaffold, adopt, and family creation flows.
• Preserve the run’s recorded family visibility while using GitHub’s actual visibility for reused holders and roots.
• Share GitHub not-found detection across repository and REST API queries.

Tests:

• Add comprehensive coverage for visibility and plan outcomes across scaffold, adopt, and family workflows, including failures, personal accounts, and unstartable GitHub CLI scenarios.
• Extend GitHub stubs to simulate visibility-specific and organisation-plan failures.

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

[sourcery-ai]

Reviewer's Guide

The PR moves Free-plan secret guidance into shared materialization helpers that separately normalize repository visibility and organization-plan responses, then updates scaffold, adopt, and family flows to report confirmed, unread, or non-applicable states without guessing—especially for reused roots and holders—while retaining existing command/refusal semantics and adding broad cross-tool coverage.

Sequence diagram for reused root visibility and plan handling

sequenceDiagram
    participant Tool as CreatingTool
    participant Materialize as shape_materialize.py
    participant GitHub as GitHubCLI
    Tool->>Materialize: repository_visibility(root)
    Materialize->>GitHub: gh repo view root --json visibility
    GitHub-->>Materialize: visibility or command failure
    Materialize-->>Tool: public, private, internal, or None
    Tool->>Materialize: free_plan_secrets_note(org, root, visibility)
    alt visibility unread
        Materialize-->>Tool: ROOT_VISIBILITY_UNREAD
    else public
        Materialize-->>Tool: no note
    else private or internal
        Materialize->>GitHub: gh api orgs/org --jq .plan.name
        GitHub-->>Materialize: free, other, unread
        Materialize-->>Tool: FREE_PLAN_HINT, FREE_PLAN_UNREAD, or no note
    end

Loading

Flow diagram for shared Free-plan secrets decision

flowchart TD
    A["Creating tool receives root visibility"] --> B{"Visibility readable?"}
    B -- "No" --> C["Return ROOT_VISIBILITY_UNREAD"]
    B -- "Public" --> D["No secrets note"]
    B -- "Private or internal" --> E["organisation_plan(org)"]
    E --> F{"Plan readable?"}
    F -- "No" --> G["Return FREE_PLAN_UNREAD"]
    F -- "Free" --> H["Return FREE_PLAN_HINT for root"]
    F -- "Other" --> D

Loading

File-Level Changes

Change	Details	Files
Centralize repository visibility, organization-plan reads, and Free-plan secret-note decisions while preserving tool-specific command execution behavior.	Add normalized readers for GitHub repository visibility and organization plan, distinguishing unread answers from public or paid results. Add shared messages for unread root visibility and unread organization plans, and emit the existing Free-plan hint only when both conditions are confirmed. Keep adopt’s GitHub invocation path intact while reusing the shared response parsing and decision logic.	scripts/shape_materialize.py adopt-project.py scaffold-project.py scripts/family.py
Make reused roots and family holders use GitHub-reported visibility instead of the run’s requested visibility.	Query reused assembly roots and family holders for their actual visibility; do not fall back to --visibility when the query is unreadable. Continue recording family.yaml visibility from the run’s requested value, and avoid querying holders created during the current run. Preserve scaffold gh-not-found refusal behavior while treating failed visibility reads as unread for existing repositories.	scaffold-project.py scripts/family.py
Correct credential guidance to describe only repositories and members whose status the tools actually establish.	Remove the claim that a holder’s members will share the holder’s visibility. Name only the root or holder in the Free-plan hint and describe later private or internal members in the init NOTE. Add coverage for public, private, internal, unread-visibility, unread-plan, paid-plan, and newly created-holder cases across all three tools.	scripts/family.py tests/test_free_plan_hint_reads.py
Expand tests and GitHub stubs to validate both independent reads and their call ordering.	Add 38 tests covering shared readers, decision branching, all three creating tools, and preservation of existing adopt behavior. Extend the fake gh executable to simulate visibility-specific failures and organization-plan failures. Update source-level assertions to require calls to the shared decision function.	tests/test_free_plan_hint_reads.py tests/test_scaffold_reuse_seeded_legs.py tests/test_adopt_free_plan_hint_root.py tests/test_free_plan_hint.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#660	For family.py init --reuse-empty-repo, determine the reused holder’s visibility from GitHub rather than from the run’s --visibility, report when it cannot be read, and base the private-holder NOTE and Free-plan hint on the holder alone.	✅
#660	For creating tools, do not infer a reused root’s visibility from the run’s --visibility when GitHub cannot be read; report unread visibility, and report an unread organization plan rather than silently treating it like a paid plan.	✅
#660	Correct family.py init’s private-visibility NOTE and Free-plan hint so they do not claim that the holder’s future members are private.	✅

Possibly linked issues

• the Free-plan hint's reads: a public reused holder gets the "private" NOTE and hint, an unread root is taken as the run's visibility, and an unread plan is silent #660: The PR implements the issue’s requested fixes: reused holders use GitHub visibility, unread roots and plans are reported, and hints name only the root.
• Tracking: adopt-project.py, converting an existing repository in place #457: The PR fixes adopt’s root-based visibility gating and root-only hint subject, and also carries the scaffold wording rider; broader changes extend beyond this 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-2, 2026-10-16T18:27:13Z)

Review round 1 for rv660's CHANGES REQUIRED, at 0b97f1a (was bc8c73b). Only F1, F7 and F8 change. F2-F6 are held for #459 until this lands.

• F1 (should-fix): a personal account got FREE_PLAN_UNREAD. GitHub answers gh api orgs/<owner> with 404 where the owner is not an organisation, and organisation_plan took every failure as an unread plan.
  • It now answers not-an-organisation for gh's not-found answer there, and free_plan_secrets_note prints nothing for it: a personal account has no organisation secrets.
  • The answer is read by gh_said_not_found, which is scaffold-project.py and family.py init: the dry runs skip the target-exists and folder checks, and any gh repo view failure reads as "does not exist" #609's reading (exit 1, gh's words on stderr) taken out of refuse_unless_not_found, not a second one. It takes REST's words, Not Found (HTTP 404), beside GraphQL's.
  • A 403, a 502, a blank answer and every other failure stay FREE_PLAN_UNREAD.
  • New rows: [scaffold|adopt|family-not-an-organisation] and a unit row. All four were red before the fix.
• F8: rv660-R2 survived every test. A new in-process test, test_init_takes_a_holder_gh_cannot_be_asked_about_as_unread, pins a reused holder whose visibility read cannot start gh as unread, and kills R2. Each tool's table gains a SAML 403 visibility row, and init's test a 404 one.
• F7: tests/test_free_plan_hint.py's docstring now says its silence tests are free_plan_secret_hint's, which no tool calls since the Free-plan hint's reads: a public reused holder gets the "private" NOTE and hint, an unread root is taken as the run's visibility, and an unread plan is silent #660, and what the tools do instead.

Tests.

• 10 files: 806 passed, 3 skipped. They are the 4 changed test files, the 2 doctor files, test_dry_run_asks_remotes.py, and the 3 that name refuse_unless_not_found or remote-unreadable.
• render-cli-reference.py --check: ok.
• Mutants, 4 of 4 killed: rv660-R2; F1-a, the reading reverted; F1-b, every exit-1 failure read as not an organisation; F1-c, GraphQL's words used for the REST read.
• Probe with a stub gh: for someuser (404), the scaffold (reused and fresh), init (reused and created) and adopt printed FREE_PLAN_UNREAD at bc8c73b and nothing at 0b97f1a. A 502 still prints it.

[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