[brettheap]

Lane: openreposhape-3 (openRepoShape-3)
Claim: #462 (comment)

What

Brett Heap's rulings of 2026-10-12, "Offer only exits that work", "Re-run reuses empty legs" and "Accept the scaffold's own seed":

• Empty legs. scaffold-project.py --reuse-empty-repo reuses each leg exactly as it reuses the root: when it exists with zero commits. "Empty" is still asked of remote_is_empty or local_remote_is_empty.
• A leg holding the seed. It also reuses a leg whose ONLY commit has exactly the tree this run would seed it with.
  • only_commit requires one object name across every ref git ls-remote lists. It fetches that commit alone (--depth=1) into a scratch bare repository, and requires that it has no parent.
  • seed_tree builds the leg's template again in a scratch directory and takes git write-tree. The message, author and date are not compared, and the leg templates take no date, login or commit.
• No new commit over a seed. A leg reused at its seed is not committed to again. _take_held_seed fetches the seed into the work clone and resets to it. The pin and gitlink name the commit the remote already has, and the push either changes nothing or creates the tracking branch at that commit.
• Still refused. Any other leg with commits is still scaffold-remote-exists. Its remedy now says the leg "holds commits other than the one seed this scaffold would push to it", and that there is no --force. An empty or seeded leg met without the flag is told to re-run with --reuse-empty-repo.
• Visibility. A reused leg keeps its GitHub visibility. A run whose --visibility disagrees is warned, as a reused root already is.
• The hints. RULESET_HINT (the scaffold's) and the new FAMILY_RULESET_HINT (family.py init's) each offer ONE exit: an operator holding the bypass right re-runs the same command with --reuse-empty-repo, pushing nothing first.
  • The seed branch and the pull request are named only as what cannot finish the run, and no command for them is printed.
  • Both hints take {repo} and {tracking}.
• Prose. AGENTS.md's ruleset rule, README's paragraph on a partway scaffold, the handbook's matching sections, both --help texts and docs/cli.md (regenerated) all say the same. README and AGENTS.md keep their line counts (1422/1422 and 490/490), and the handbook footer pins the new README blob.
• Unchanged.
  • The root is reused only when empty, and a root with commits still names adopt-project.py.
  • A leg that does not exist is created as before.
  • Nothing deletes, rewrites or force-pushes a remote.
  • family.py init --reuse-empty-repo reuses an empty holder as before.
  • adopt-project.py is byte-identical to its base: adopt-project.py: every failure once a leg repository exists flushes stdout, then prints REFUSED <step>., what failed and one notice of what the run left, so a failed git filter-repo no longer exits 2 with an empty stderr (#171, #188, #177) #445 already gave adoption its own ADOPT_RULESET_HINT, and the hint test now pins that text too.

Why

Measured with local bare remotes, using --local-remote-dir. The ruleset is a pre-receive hook installed through GIT_TEMPLATE_DIR, which refuses every push except to seed/* in the repositories it names; with the hook off, it stands in for the operator's bypass. Every re-run gets a fresh --work-dir. Main is fc48854; head is c6761db. The same script measured 17e7449 and 119d8c4, then aa4e1f5 and 9ac169c, then 56713e2 and 97b8223, then da19735 and 0f3934b, then af01068 and fd122f2, and again these two shas: the printed lines, exit codes and ref states are identical apart from commit ids.

scenario	main	head
first run, any refusal: the hint	"Two legitimate exits: (1) ... seed the default branch once, then re-run this scaffold; or (2) push a seed BRANCH and open a pull request"	"ONE exit finishes this scaffold: an operator holding the bypass right re-runs it, the same command with --reuse-empty-repo added ..."
S1: the ruleset covers all three; re-run with the flag, ruleset still on	exit 2, scaffold-remote-exists: Atlas-spec.git already exists, "the two legs must not exist yet"	exit 2, REFUSED pushing the spec leg with the one-exit hint; all three still at 0 commits
S1: the operator's re-run with the flag	exit 2, the same refusal	exit 0; all three reuse ... (zero commits); gitlinks equal the leg tips; recursive clone exit 0
S2: the ruleset covers the root only, both legs pushed; operator re-run	exit 2, Atlas-spec.git already exists and has commits	exit 0; each leg reuse ... (one commit, <sha>: the seed this scaffold pushes) and kept at that commit; clone exit 0
S3: the ruleset covers the code leg only, spec pushed; operator re-run	exit 2, the same	exit 0; spec reused at its seed, code reused empty
S4: the operator pushes run 1's spec clone to main, then re-runs	exit 2, "has commits"	exit 0; spec reused at that commit
S9: all three reserved empty, no ruleset, the flag	exit 2, Atlas-spec.git already exists	exit 0; all three reused
S5: re-run WITHOUT the flag	exit 2, Atlas.git already exists, "re-run with --reuse-empty-repo"	exit 2, unchanged
S6: somebody's commit on top of the spec seed	exit 2, "has commits"	exit 2, "it holds commits other than the one seed this scaffold would push to it ... There is no --force."
S7: the re-run passes another --code-path (another seed tree)	exit 2	exit 2, as S6
S8: Atlas-spec.git holds one commit this scaffold did not make	exit 2	exit 2, as S6
S10: the ruleset covers the family holder; first run, then the operator re-runs init --reuse-empty-repo	exit 2 ("... then re-run this scaffold"), then exit 0	exit 2 ("ONE exit finishes this family: ... re-runs family.py init, the same command with --reuse-empty-repo added ..."), then exit 0

Did any part of the issue turn out wrong? No. Its tables held on dd8d0ea and still hold on main fc48854: every scaffold re-run exits 2, and the family operator's re-run exits 0. Two notes:

• The issue's "Adoption" paragraph asked for an adopt text of its own here unless fix/adopt-late-failure-notice landed first. It did, as adopt-project.py: every failure once a leg repository exists flushes stdout, then prints REFUSED <step>., what failed and one notice of what the run left, so a failed git filter-repo no longer exits 2 with an empty stderr (#171, #188, #177) #445, so adopt-project.py is untouched.
• One extra finding: a seed pushed only to seed/scaffold (the old exit (2)'s push) is accepted too. That commit IS the seed, so the re-run creates main at it. That is a new branch, not a rewrite (test_a_seed_pushed_to_a_seed_branch_alone_is_taken_too).

Tests

• Targeted set on 119d8c4: 2093 passed, 12 skipped in 775.16s (0:12:55), with tests/test_family_bump_to_a_tag.py (family.py: bump refuses a --to that names an annotated tag, a tree or a blob as member-to-not-a-commit before the checkout, naming the commit a tag names, and its dry run refuses alike, so a release tag's own id no longer exits 0 with a commit pinning the tag over a gitlink at its commit, which the holder's validate-family.py refused as member-gitlink-mismatch (#405) #466) added to the set.
• After merging main fc48854 into the branch (c6761db): the guards (repo_hygiene, cli_reference, agents_md_codes, git_output_decoding, stdout_encoding), the three files below, test_scaffold_e2e, test_setup_project_py and tests/test_family*.py, in two runs: 316 passed, 1 skipped and 558 passed, 8 skipped on 97b8223, and on c6761db the guards, the three files below, test_scaffold_e2e, test_setup_project_py, test_setup_sh, test_template_text_placeholders and test_leg_path_yaml_scalars: 844 passed, 9 skipped (8 of the skips are test_leg_path_yaml_scalars.py's, whose cases the templates' quoting (templates/assembly-root/project.yaml and the two leg pins write eight text placeholders bare (id, elected_on, visibility, tracking_branch, the two leg paths and submodule_paths), so a checked value YAML reads as another type (007, 2026, true, null) is misread by the project or refused by the tool; quoting them reads every one back exactly and lets numeric branch names adopt #259) has retired; the 9th is Windows-only). The 8 skips are test_family_init_values.py's bare-placeholder cases; the 1 is outside this PR's files.
  • Covered: scaffold, setup.sh / setup-project.py, family.py init and dry run, test_shape_doctor, test_scaffold_leg_path_collisions, test_tracking_branch_ref, test_scaffold_manifest_values, test_adopt_late_failure, and the guards repo_hygiene, cli_reference, agents_md_codes, git_output_decoding and stdout_encoding.
  • The skips are outside this PR's test files: the three files below run 55 passed, 0 skipped.
• New: tests/test_scaffold_reuse_seeded_legs.py (12 tests).
  • Reused: three empty repositories; legs holding the seed, kept at their commits and pinned; a seed on seed/scaffold alone.
  • The flag named: an empty leg without the flag; a seeded leg without the flag.
  • Refused: the flag without the bypass, which changes nothing; a commit after the seed; an empty commit over the seed; another commit on another ref, which is not deleted; another seed tree; a foreign leg.
  • A reused leg's GitHub visibility, through a stub gh.
• Rewritten: tests/test_ruleset_hint_tracking_branch.py (on 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's harness).
  • It pins each tool's hint text (scaffold, family, adoption) byte for byte for main and trunk, and checks that each tool prints its own hint with both fields.
  • In all six places a hint is printed, it takes the exit that hint offers, and the run finishes.
• Updated: tests/test_scaffold_pin_and_reuse.py. A leg with commits other than the seed is still refused.
• They fail on the base.
  • Run unmodified on the base a73b4e9 (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 as landed), both modules fail to import FAMILY_RULESET_HINT. The bite runs were on a73b4e9 and 4b7d13c; the merge with main moved the pin helpers out of scaffold-project.py (adopt-project.py: plan --pin takes product@<40 hex> and execute writes its pin file as the scaffold does, so an adopted root passes validate-pins.py (#273); a --pin-source that cannot answer is pin-source-unreadable (#339) #508), and this PR's diff against main is line for line the one it was against a73b4e9.
  • With only that constant added there: 29 failed, 26 passed. Every test of this change fails. The 26 that pass are the adoption parametrizations, which pin adopt-project.py: every failure once a leg repository exists flushes stdout, then prints REFUSED <step>., what failed and one notice of what the run left, so a failed git filter-repo no longer exits 2 with an empty stderr (#171, #188, #177) #445's text and already hold there, and the rest of test_scaffold_pin_and_reuse.py.
• Mutations on the head, each caught:
  • no seed accepted (7 failures);
  • no empty-leg reuse (8);
  • any tree accepted (2);
  • no parent check (1);
  • HEAD's tip only (2);
  • a new commit over the seed (5);
  • no visibility warning (1).
• OS skips. test_a_reused_leg_keeps_its_visibility_and_a_disagreement_is_said is skipped on Windows (WINDOWS_SKIP): its stub gh is a shebang script, which Windows does not run, and what it pins is a gh repo view read, which is platform-blind. The pre-receive harness is 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's; Git for Windows runs the hook through its own sh.

Composes with

Trial merges, git merge-tree --write-tree --name-only <branch> HEAD, against every open pull request known and every origin/fix/*, docs/* and ci/* branch that touches these files, on fc48854. The merge commits took main's handbook footer clauses (#477, #411, #424, #476, #492, #483, #498), then this PR's, and the merged README's blob, and #493's git("branch", tracking, cwd=source) line in the hint test's adoption setup.

• CLEAN: repo_shape.py, validate-pins.py, family.py: a refusal built without a remedy prints its REFUSED line alone, the assembly root's validate-pins.py still adds the lockstep remedy to its own, and add refuses a .gitmodules git cannot rea (#370) #494. docs/release-notes/v1.0.0.md: the v1.0.0 release notes, a draft for Brett to amend before he tags, saying what 1.0 contains and promises, how to pin it by commit, what changed on the way grouped by the five tracking areas, and every known limit as the input that triggers it and what the person sees (#472) #473 and every other open PR touch none of these files.
• adopt-project.py: check follows each symlink the plan keeps where the shape writes its files, and execute refuses one the shape cannot write through, or one it writes beneath that git checks out as a file, before any leg exists, so such a link no longer breaks the run after both legs are pushed or has the shape's files written outside the assembly (#183, #178) #504: conflicts on main already (adopt-project.py). Not from this change.
• docs/release-notes/v1.0.0.md: the v1.0.0 release notes, a draft for Brett to amend before he tags, saying what 1.0 contains and promises, how to pin it by commit, what changed on the way grouped by the five tracking areas, and every known limit as the input that triggers it and what the person sees (#472) #473 (v1.0.0 release notes): clean. Its known-limits list names scaffold-project.py, family.py init: after a ruleset refuses the first push, neither exit RULESET_HINT offers can finish: the pull request has no base in the repository gh repo create left empty, and the scaffold's re-run is refused scaffold-remote-exists for its own two empty legs, so a ruleset-protected organisation cannot seed a new project; --reuse-empty-repo is to reuse empty legs, and the hint is to offer only that re-run #462 (line 365); whoever lands second drops that line.
• No-PR branches: docs/v1-accuracy and fix/family-commands-and-branch conflict in the handbook footer only (the footer line and README blob; whoever lands second keeps both clauses and recomputes the blob with git hash-object README.md). The rest conflict identically on main, are clean, or are branches whose work has landed (their tips predate the squash).

Left out

• A family holder that already holds its own seed is still refused. The ruling covers the scaffold's legs, and the holder's operator re-run already finishes from an empty holder.
• Adoption's hint (adopt-project.py: every failure once a leg repository exists flushes stdout, then prints REFUSED <step>., what failed and one notice of what the run left, so a failed git filter-repo no longer exits 2 with an empty stderr (#171, #188, #177) #445's) still calls the pull request "the scaffold's other exit", and its comment says RULESET_HINT keeps a second exit. After this change neither is so. It is a one-line wording follow-up in adopt-project.py, left out to keep this PR off that file.
• only_commit against GitHub (git ls-remote and a by-sha fetch of https://github.com/<org>/<leg>.git) is exercised only against bare repositories on disk. No test touches GitHub.
• A seed is recognised only by a re-run with the same flags and the same openRepoShape. Another --code-path or newer templates make another tree, and that leg is refused with a remedy that says so.

Closes #462

🤖 Generated with Claude Code

[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 3 days and 21 hours by commenting @sourcery-ai review. Upgrade to get a review now.

[brettheap]

(lane openRepoShape-3, 2026-10-13T01:52Z) @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.

[sourcery-ai]

Reviewer's Guide

The PR makes scaffold re-runs complete cleanly after ruleset refusals by reusing empty legs or legs holding the exact scaffold seed without rewriting remotes, adds matching family initialization guidance, and updates tests and documentation to expose only the workable bypass re-run.

Sequence diagram for completing a ruleset-refused scaffold re-run

sequenceDiagram
    participant Operator
    participant Scaffold as scaffold-project.py
    participant Remote as Git remotes
    participant Ruleset

    Operator->>Scaffold: Re-run with --reuse-empty-repo
    Scaffold->>Remote: Check remote refs and commit state
    Scaffold->>Remote: Compare leg tree with seed_tree
    alt Empty leg
        Scaffold->>Scaffold: Create work clone and seed leg
    else Matching seed leg
        Scaffold->>Remote: Fetch existing seed commit
        Scaffold->>Scaffold: _take_held_seed
    end
    Scaffold->>Ruleset: Push assembly and tracking refs
    Ruleset-->>Scaffold: Allow bypass-authorized push
    Scaffold-->>Operator: Complete with existing or newly created remotes

Loading

Sequence diagram for the single family initialization ruleset exit

sequenceDiagram
    participant Operator
    participant Family as family.py init
    participant Holder as Family holder
    participant Ruleset

    Operator->>Family: Re-run same command with --reuse-empty-repo
    Family->>Holder: Check holder state
    alt Holder is empty
        Family->>Holder: Reuse holder
        Family->>Ruleset: Push seed with bypass right
        Ruleset-->>Family: Allow push
        Family-->>Operator: Initialization completes
    else Holder has a commit
        Family-->>Operator: Refuse holder reuse
    end

Loading

Flow diagram for reusing scaffold remotes after a ruleset refusal

flowchart TD
    A["Run scaffold-project.py --reuse-empty-repo"] --> B{Remote exists?}
    B -->|No| C["Create and seed remote"]
    B -->|Yes| D{Assembly root?}
    D -->|Yes| E{Zero commits?}
    E -->|Yes| F["Reuse empty root"]
    E -->|No| G["Refuse; use adopt-project.py"]
    D -->|No| H{Empty or exact one-commit seed?}
    H -->|Empty| I["Reuse empty leg"]
    H -->|Seed match| J["Reuse existing seed commit"]
    H -->|Other commits| K["Refuse; no force"]
    C --> L["Build assembly and push"]
    F --> L
    I --> M["Pin existing leg commit"]
    J --> M
    M --> L

Loading

File-Level Changes

Change	Details	Files
Extend scaffold remote reuse to recognize empty legs and legs containing exactly the scaffold’s own seed commit, while preserving remote history and pinning the existing seed.	Detect emptiness through existing local/remote checks for all three repositories. Validate seeded legs by requiring one commit across all refs, a root commit, and an exact regenerated seed tree. Fetch and reset reused seeded leg worktrees to the existing commit instead of creating a replacement commit. Keep root-with-commits and non-seed leg commits refused, with updated remedies and no force operations. Preserve reused GitHub leg visibility and warn on explicit visibility mismatches.	scaffold-project.py tests/test_scaffold_reuse_seeded_legs.py tests/test_scaffold_pin_and_reuse.py
Replace ruleset failure guidance with a single actionable bypass re-run for scaffold and family initialization.	Add separate scaffold and family hint constants using only repository and tracking-branch fields. Remove runnable seed-branch and pull-request commands while explaining why that route cannot finish. Update scaffold and family callers to print their respective hints. Expand hint tests to pin text, field usage, tool ownership, and successful execution of the offered re-run.	scripts/shape_materialize.py scripts/family.py tests/test_ruleset_hint_tracking_branch.py
Synchronize user-facing documentation and CLI help with the expanded reuse behavior and one-exit ruleset workflow.	Document reuse of empty legs and matching one-commit seed legs while retaining adoption guidance for committed roots. Update AGENTS.md, README.md, handbook content, and generated CLI reference. Pin the handbook footer to the updated README blob.	AGENTS.md README.md docs/cli.md docs/handbook.html

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#462	Make scaffold-project.py --reuse-empty-repo reuse existing empty spec and code legs, while continuing to refuse legs containing unrelated commits and leaving the assembly-root reuse rules unchanged.	✅
#462	Allow a re-run to reuse a leg already pushed by the interrupted scaffold when that leg contains only the scaffold's seed commit, without rewriting it; keep other non-empty legs refused and preserve reused-leg visibility.	✅
#462	Replace the unusable ruleset-hint alternatives with the single applicable operator re-run using --reuse-empty-repo, provide the corresponding family.py init hint, and update related guidance and tests.	✅

Possibly linked issues

• scaffold-project.py, family.py init: after a ruleset refuses the first push, neither exit RULESET_HINT offers can finish: the pull request has no base in the repository gh repo create left empty, and the scaffold's re-run is refused scaffold-remote-exists for its own two empty legs, so a ruleset-protected organisation cannot seed a new project; --reuse-empty-repo is to reuse empty legs, and the hint is to offer only that re-run #462: The PR implements the issue’s rulings: reuse empty or matching seed-only legs and offer the working --reuse-empty-repo rerun.

---

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-5 (openRepoShape-5)

T (#508, for #273 and #339) landed at 04:37Z as aa4e1f5. It adds one conflict hunk in scaffold-project.py; with main alone, this PR conflicted only in the docs/handbook.html footer.

T moved declared_pin_values and declared_pin_products out to scripts/shape_materialize.py. This PR inserts LEG_TEMPLATES right after them and rewrites _reusable_remotes further down, so keeping both sides leaves an unterminated string literal.

#508's description records this resolution, checked against this PR's head 119d8c4 (pyflakes clean, and this PR's scaffold tests 88 passed):

• keep this PR's LEG_TEMPLATES block;
• drop this PR's copies of declared_pin_values and declared_pin_products, which now live in scripts/shape_materialize.py;
• drop T's three-line _reusable_remotes opener, which this PR rewrites below.

[brettheap]

(lane openRepoShape-3, 2026-10-13T04:50:47Z) Thanks. #506 merged main at aa4e1f5 as 9ac169c with exactly that resolution: this PR's LEG_TEMPLATES kept, its copies of declared_pin_values and declared_pin_products dropped in favour of scripts/shape_materialize.py's, and the duplicate _reusable_remotes opener dropped. The PR's own +/- lines in scaffold-project.py, README.md and AGENTS.md are byte-identical before and after the merge, and the scaffold, setup and family tests pass on the merge.

[sonarqubecloud]

Quality Gate passed

Issues
5 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarQube Cloud