scaffold-project.py and family.py init: --reuse-empty-repo reuses a leg that is empty or whose one commit is the scaffold's own seed, and the ruleset hint offers that re-run, by an operator holding the bypass right, as its one exit, so a project a ruleset refused part-way is finished by one re-run, not refused scaffold-remote-exists for its own legs or sent to a pull request with no base (#462)

AGENTS.md

@@ -34,9 +34,9 @@ almost always an explicit `--org <their-org>`. Pass `--allow-upstream-org`
 only if the human asks for it in those words.
 
 **Never bypass an organisation ruleset.** A ruleset that refuses a direct push
-to `main` is doing its job; the exits are in the scaffold's own failure message
-(seed by pull request, or ask an operator with the bypass right). `--admin` is
-not a remedy.
+to `main` is doing its job; the exit is in the tool's own failure message (for
+a scaffold or `family.py init`: an operator holding the bypass right re-runs
+it with `--reuse-empty-repo`). `--admin` is not a remedy.
 
 ## 1. Confirm what you are about to do
 

README.md

@@ -455,15 +455,15 @@ manifest, sets the topic `xf-project-atlas` on all three, clones the root as
 > created. A failed push says so in as many words — *NOTHING has been rolled
 > back. What already exists is listed above; delete it by hand if you want a
 > clean re-run* — and it is no less true of a failure anywhere else. A second
-> run is refused while the legs exist, and there is no `--force`, because
-> re-running over a live project is not a scaffold: delete what was created —
-> `gh repo delete <org>/<name>`, which needs the `delete_repo` scope, and
-> `gh repo delete --help` names `gh auth refresh -s delete_repo` as how to get
-> it — or scaffold under a different `--project`. `--reuse-empty-repo` covers
-> exactly one case: an assembly ROOT that already exists with ZERO commits,
-> which is a reserved name rather than a project. It applies to the root alone
-> — an existing leg is refused whatever it holds, and a root that HAS commits
-> is a live repository, which `adopt-project.py` converts in place instead.
+> run is refused while they exist, and there is no `--force`: delete what was
+> created — `gh repo delete <org>/<name>`, which needs the `delete_repo` scope
+> (`gh auth refresh -s delete_repo`) — or scaffold under a different
+> `--project`, or re-run with `--reuse-empty-repo`. That reuses each of the
+> three that has ZERO commits, a reserved name rather than a project, and a
+> leg whose one commit is the seed this scaffold pushes, so a run a ruleset
+> refused is finished by an operator holding the bypass right re-running it.
+> A leg with other commits is refused, and a root that HAS commits is a live
+> repository, which `adopt-project.py` converts in place instead.
 > `--visibility internal` is the third value every tool here accepts; only a
 > GitHub Enterprise Cloud organisation offers it at all, and one that does not
 > is refused by GitHub rather than by this tool.

docs/cli.md

@@ -253,10 +253,10 @@ options:
   --name NAME           display name
   --visibility {private,public,internal}
                         default: private for a fresh scaffold; with --reuse-
-                        empty-repo and an existing assembly root, the two new
-                        legs INHERIT that root's own visibility instead (a
+                        empty-repo and an existing assembly root, the legs it
+                        creates INHERIT that root's own visibility instead (a
                         mismatch with an explicit --visibility is a warning,
-                        not a refusal)
+                        not a refusal, and so is a reused leg's)
   --pin-owner PIN_OWNER
                         the organisation an UNQUALIFIED --pin name resolves
                         under (default: opensoft, where every neutral
@@ -298,10 +298,14 @@ options:
                         create bare repositories here instead of calling `gh
                         repo create` (the TEST path; no network)
   --no-push
-  --reuse-empty-repo    if <org>/<Project> already exists and has ZERO
-                        commits, use it as the assembly root instead of
-                        refusing. A repository with commits is still refused:
-                        that is a live project, not a slot.
+  --reuse-empty-repo    if <org>/<Project>, <Project>-spec or <Project>-code
+                        already exists and has ZERO commits, use it instead of
+                        refusing, and a leg whose one commit is the seed this
+                        scaffold pushes too: an operator holding the bypass
+                        right finishes a run a ruleset refused by re-running
+                        it with this. A root with commits, and a leg with any
+                        other, is still refused: that is a live repository,
+                        not a slot.
   --pin openProduct@COMMIT
                         declare a neutral-product pin, e.g. --pin
                         openGlass@<40 hex>. It writes

docs/handbook.html

@@ -1018,17 +1018,17 @@ <h2>If it fails part-way</h2>
       <div class="out"><pre><code>NOTHING has been rolled back. What already exists is listed above; delete it by hand if you want a clean re-run</code></pre></div>
       <p>&mdash; and it is no less true of a failure anywhere else.</p>
       <ul class="plain">
-        <li>A second run is refused while the legs exist, and there is no <code>--force</code>,
-        because re-running over a live project is not a scaffold.</li>
+        <li>A second run is refused while they exist, and there is no <code>--force</code>.</li>
         <li>Delete what was created with <code>gh repo delete &lt;org&gt;/&lt;name&gt;</code>, which
-        needs the <code>delete_repo</code> scope; <code>gh repo delete --help</code> names
-        <code>gh auth refresh -s delete_repo</code> as how to get it. Or scaffold under a different
-        <code>--project</code>.</li>
-        <li><code>--reuse-empty-repo</code> covers exactly one case: an assembly ROOT that already
-        exists with ZERO commits, which is a reserved name rather than a project. It applies to the
-        root alone &mdash; an existing leg is refused whatever it holds, and a root that HAS commits
-        is a live repository, which <a href="#adopt"><code>adopt-project.py</code></a> converts in
-        place instead.</li>
+        needs the <code>delete_repo</code> scope (<code>gh auth refresh -s delete_repo</code>). Or
+        scaffold under a different <code>--project</code>, or re-run with
+        <code>--reuse-empty-repo</code>.</li>
+        <li><code>--reuse-empty-repo</code> reuses each of the three that has ZERO commits, a
+        reserved name rather than a project, and a leg whose one commit is the seed this scaffold
+        pushes, so a run a ruleset refused is finished by an operator holding the bypass right
+        re-running it. A leg with other commits is refused, and a root that HAS commits is a live
+        repository, which <a href="#adopt"><code>adopt-project.py</code></a> converts in place
+        instead.</li>
         <li><code>--visibility internal</code> is the third value every tool here accepts; only a
         GitHub Enterprise Cloud organisation offers it at all, and one that does not is refused by
         GitHub rather than by this tool.</li>
@@ -1798,8 +1798,9 @@ <h2>For AI assistants</h2>
         setup.sh refuses because the organisation you were given resolves to opensoft, STOP and relay
         what it said; the fix is almost always an explicit <code>--org &lt;their-org&gt;</code>.</li>
         <li><strong>Never bypass an organisation ruleset.</strong> A ruleset that refuses a direct
-        push to <code>main</code> is doing its job; the exits are in the scaffold&rsquo;s own failure
-        message. <code>--admin</code> is not a remedy.</li>
+        push to <code>main</code> is doing its job; the exit is in the tool&rsquo;s own failure
+        message (for a scaffold or <code>family.py init</code>: an operator holding the bypass right
+        re-runs it with <code>--reuse-empty-repo</code>). <code>--admin</code> is not a remedy.</li>
         <li><strong>Never reset, stash or force-push to make a refused
         <a href="#park"><code>make park</code></a> or <code>make resume</code> succeed.</strong> A
         parked WIP commit is a real pushed commit, and <code>resume</code> refusing on divergence
@@ -1870,9 +1871,11 @@ <h2>For AI assistants</h2>
       above drift, added (#424); the assistant&rsquo;s route when its shell has no terminal, added
       (#476); the one-liner asking at the person&rsquo;s own terminal, never reading the answer
       from the pipe, added (#492); the statements the v1.0.0 accuracy pass found false, corrected
-      here as in the README, added (#483); a taken clone path refused up front, added (#498) &mdash;
-      a page cannot name the commit that contains it, and the blob below is the fact a test checks.
-      README.md blob 43df8f47b8a70678a2ff1836f01468a686e41eb6. Every command, flag, exit code
+      here as in the README, added (#483); a taken clone path refused up front, added (#498);
+      <code>--reuse-empty-repo</code> reusing an empty leg and a leg holding the scaffold&rsquo;s
+      own seed, and the one ruleset exit that re-run is, added (#462) &mdash; a page cannot name
+      the commit that contains it, and the blob below is the fact a test checks.
+      README.md blob 8c658efcc9ca35144eb9be15cb1a9b7059041e30. Every command, flag, exit code
       and file name on this page is quoted from that README and from AGENTS.md.</p>
     </footer>
   </main>