[brettheap]

Lane: openreposhape-5 (openRepoShape-5)
Claim: #304 (comment)

What was wrong

AGENTS.md step 7 told an assistant that any non-zero exit of adopt-project.py execute is "to fix the plan and re-run into fresh legs". That is the way out of a failed verification, exit 1. In GitHub mode execute has two more non-zero exits, both exit 2, and both come after both legs and the split branch are pushed:

• gh pr create refused: The branch IS pushed. Open the pull request by hand: and the command. execute returned before _verify, so no table was printed and the pull request to open by hand was for a split nothing had checked.
• The topic will not set: after adoption verified, The split IS pushed and the pull request IS open. Set the topic by hand: and three commands.

On either, the way out is the printed command, and "re-run into fresh legs" abandons a finished adoption for a second pair of legs. No test reached either function, because --local-remote-dir, the path every test takes, skips both (if not local:).

What this changes

• AGENTS.md step 7, four lines longer (477 -> 481 on origin/main, the cap raised with a dated entry in tests/test_repo_hygiene.py; AGENTS.md, README and scaffold-project.py --help: say that a --spec-path or --code-path that is, holds or lies inside a file the shape writes, and a --pin of spec, code or shape or of one product twice, are refused before anything is created, and name those three in the pin refusal's remediation, so an agent briefed from AGENTS.md can say so before it runs the scaffold (#288) #309 landed first and its 464 -> 477 entry is kept as it is). It keys the advice to the exit the tool prints: exit 1 keeps its content (the source is untouched, fix the plan, re-run into fresh legs); exit 2 saying IS pushed (GitHub only, gh pr create or the topic refused) comes after both legs and the split are pushed and verified, so finish with the command it prints and never re-run into fresh legs.
• adopt-project.py, behaviour (fix round 1, below): a refused gh pr create no longer returns before the verification. The by-hand command is printed after the table, and only when the table passed.
• adopt-project.py, the module docstring's EXIT CODES paragraph. It gave exit 2 one meaning, "the question could not be asked". It now names the two exit 2s that come after the push and the verification, in the tool's own words, and says that a failed verification outranks both. --help carries none of it, so docs/cli.md is unchanged (scripts/render-cli-reference.py --check: docs/cli.md is what the generator produces).
• tests/test_adopt_github_exits.py (new, 11 tests). The issue's reproduction as a test: a #!/bin/sh gh that refuses one command (the pattern of tests/test_scaffold_leg_paths.py, WINDOWS_SKIP) and a throwaway global git config rewriting https://github.com/ to bare repositories under tmp_path, so no network. Each exit is asserted as exit 2 with its REFUSED block and its by-hand command word for word, a table, both legs and the split branch pushed; the command comes after the table in a merged stream; a verification that really fails gives exit 1 with a refused pull request and no command to open one. Step 7's anchors (IS pushed, gh pr create, the topic) and the EXIT CODES paragraph are asserted against what the tool prints, so rewording either side alone fails a test.

Fix round 1: execute verifies on a refused gh pr create

The issue's second "what would fix it" bullet. Reproduced on d3f71d6 first (a source with its own contracts/shape-pin.yaml kept in the root fails the verification for real, nothing in the tool replaced):

scenario, GitHub mode, merged stdout+stderr	before (d3f71d6)	after
gh pr create refused, split verifies	exit 2; no table; Open the pull request by hand (line 19)	exit 2; table (27), adoption verified (33), then Open the pull request by hand (37), the last thing printed
gh pr create refused, split FAILS verification	exit 2; Open the pull request by hand for a split that is wrong, never verified	exit 1; the finding and the footer; No pull request was opened, and none should be: the split above did not pass verification.; no command to open one
topic refused, either	unchanged	unchanged (exit 2 / exit 1)

The order, and why. The split is pushed, then gh pr create is tried; a refusal prints its REFUSED block at once (what failed); the topic is not tried; _verify runs; then the by-hand lines are printed or withheld by what _verify said. Evidence for each step:

• The by-hand text has to come after the verdict. The command is only right for a split that passed; a failed one must not get it (the brief), and a person who sees only the REFUSED block above, which names the exact gh pr create ... that was tried, may paste it. So _open_it_by_hand runs after _verify, and a failed split gets the sentence above in its place.
• It flushes stdout first. Under a pipe stdout is block-buffered and the table is on it. In the merged logs above (stdout to the same file as stderr), every stderr line lands ahead of every stdout line on d3f71d6: the topic's by-hand commands print at line 7 of 26, before the table at 20. A test (..._comes_after_the_table) fails without the flush.
• The topic is not tried after a refused pull request, as before (it returned early). Its by-hand message says the pull request IS open, so printing it would be false; the stub gh lets a topic through, and a test asserts it is never set on this path.
• Verifying first and opening the pull request only on a pass was considered and not done: it reorders every successful run's output (the pull request line moves below adoption verified, and _verify's NEXT: review the pull request is printed first), and it is not "the code path the topic case uses". It would fix something real, below.

The code reuses the topic's path, with no second verification: cmd_execute already ran _verify after the topic step; the early return 2 is gone, _open_the_pull_request prints the REFUSED block and returns False as before, and the by-hand lines moved to a small _open_it_by_hand called once the verdict is known. The exit is 2 if the pull request was refused or the topic failed, and a failed verification outranks both with exit 1.

Tests for it (tests/test_adopt_github_exits.py, 7 tests, all end to end through the real CLI):

• test_each_exit_after_the_push_is_exit_2_with_a_command_to_finish_by_hand[gh-pr-create-refused] now expects the table, adoption verified, no pull request line, the topic never set;
• ..._the_command_to_open_a_refused_pull_request_comes_after_the_table: merged stream, table < adoption verified < by-hand, which is the last thing printed;
• ..._a_failed_verification_outranks_a_refused_pull_request: exit 1, the finding, no Open the pull request by hand, no IS pushed;
• ..._the_same_source_verifies_when_gh_opens_the_pull_request: its control, exit 0.
  Driving a real failing verification was practical (a source's own pin kept in the root, the way adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188's tests do it), so nothing is injected.

Fails before, passes after: the 5 changed or new tests fail on d3f71d6 (the step 7 reading, the EXIT CODES reading, the pr-create run, the order run, the failed-verification run); the topic run and the control pass there, as they should. Mutation probes of the new hunk, each failing at least one new test: restoring the early return 2 (3 fail); ignoring the verdict in _open_it_by_hand (the failed-verification test); removing the flush (the order test); trying the topic after a refusal (the pr-create run); returning 0 for a refused pull request (2 fail); AGENTS.md or the docstring back to d3f71d6 (their readings).

Fix round 2: the review of 16aa9ff (0 blocker, 2 should-fix, 8 nits)

S1, a closed stdout (should). _open_it_by_hand flushed stdout with sys.stdout.flush(), which raises BrokenPipeError when nobody reads stdout any more (execute ... | head, | true), so the run ended in a traceback and the command to open the pull request, which main printed, was never printed. It now calls _flush_stdout(), which is lane 1's #188 helper under the same name and shape (contextlib.suppress(OSError)), at the same place in the file and with the same text, so the two merge to one definition. A test drives the real CLI with a stdout whose reading end is closed: the command is on stderr, there is no traceback, and the exit is 120, Python's own for a stdout it cannot flush as it exits, which main gave and 16aa9ff gave too (so the exit does not tell them apart; the traceback and the missing command do).

pr scenario, stdout closed (| true)	c7c02fa (main)	16aa9ff	this head
by-hand command	printed	not printed, traceback in _open_it_by_hand	printed
exit	120	120 (Python's, for the stdout it cannot flush as it exits)	120

S1, the other case, NOT built here. If the verification itself raises (a git that will not list a tree, a full disk), the by-hand line is still lost: a CommandFailed gives exit 2 with two REFUSED blocks and no word that the legs and the split are pushed, an OSError a traceback with exit 1, which step 7 reads as "a failed verification". #188's _verify catches those, reports them with its notice and the branch to delete, and exits 2; composed, both give REFUSED verifying the split, the notice, and "No pull request was opened, and none should be". That needs #188's handler, so it is its to compose, not this PR's to build.

S2. origin/main is merged into the branch (merge commits c519f57 and a92fcad, no rebase or force). The one conflict was the AGENTS.md cap: #309's 464 -> 477 entry is kept as it is, this PR's entry is now 477 -> 481 and the cap is 481, the real wc -l AGENTS.md after the merge (477 on main, and step 7 grows from 5 lines to 9). The composition section above is refreshed against the current heads.

Nits.

• N1. The dated entry uses the file's em dash, and the five-versus-four sentence and "(fix round 1)" are gone: it describes the change, not the branch's history.
• N2. NEXT: review the pull request on <root> moved out of _verify into _next_steps(names), which cmd_execute calls only when no pull request was refused. After a refused one, the by-hand command is the next step and the last line. Under --local-remote-dir it is unchanged (see "Left out").
• N3. The printed command now works without a terminal. gh pr create without --title and --body asks for them, and where there is no terminal it exits 1 before any request (must provide --title and --body ... when not running interactively; the review ran it offline with a bogus token, an empty config directory and an .invalid host, and this fix round did not run gh at all), so an assistant told by step 7 to "finish with the command it prints" could not. The tool already knew both, so _pull_request_command builds the arguments once, _open_the_pull_request runs them, and _open_it_by_hand prints the same list, shell-quoted. A test reads back the arguments the stub gh was refused with and compares them with the parsed printed command; nothing runs the printed command. Two costs, stated: the body is the split commit's message, which lists every moved path, so for a large repository the printed command is as long as that list (the REFUSED block above it already prints the same text unquoted); and the quoting is POSIX, as adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188's printed git ... --delete already is. _open_it_by_hand's signature is now (repositories, names, tracking, branch, message, passed), which the adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188 note carries.
• N4. The EXIT CODES paragraph said execute "has two more exit 2s". It now says it has other exit 2s once the leg repositories exist (a refused push, a refused mount) and that two of them are GitHub mode's alone.
• N5. The follow-up claiming adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188's _flush_stdout() covers the topic's by-hand commands printing above the table was false; it is corrected above ("Left out").
• N6. Nothing to do: the coordinator lands with an explicit squash message.
• N7. Wording only, for the adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188 composition: "was not verified" would be exact where adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188's _verify could not verify at all. It is in the note on adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188.
• N8. The end-to-end environment keeps the real gh unreachable. subprocess goes on to the next PATH directory when the program it found cannot be executed (a noexec temp directory gives EACCES), and the next gh would be the operator's. So the run's environment now carries GH_TOKEN=bogus-token-for-tests and GH_CONFIG_DIR an empty directory, and PATH is the stub first and then the inherited PATH WITH every directory that holds a gh taken out (without_a_real_gh), which finds git and python because the directories are taken out only when each of git, git-filter-repo, python3, python, sh, env, sed, tr, uname and cat is found at the same place without them. Where it is not (/usr/bin on Linux holds gh beside git, and Homebrew's bin beside the git a run is meant to use), PATH is returned whole and the token and the config directory are what keep the real gh from acting. The stub records the token and config directory it was run with, and a test holds them to the bogus token and the empty directory.

Tests. tests/test_adopt_github_exits.py is 11 tests now. On a throwaway worktree at 16aa9ff with this file: 5 failed, 6 passed. Failing there: the EXIT CODES reading (N4), [gh-pr-create-refused] (N2), the order test (N2, N3), the printed-command test (N3) and the closed-stdout test (S1). Passing there, as they should: step 7, [the-topic-will-not-set], the failed-verification test and its control, and the without_a_real_gh unit test and the environment test (N8: nothing in 16aa9ff's production code to fail, the environment is the test's). Mutation probes (15, each reverted by path in a throwaway worktree): the unguarded flush back, the flush removed, _flush_stdout not suppressing, the printed command cut to the old form, unquoted, run without the body, NEXT always or never said, the EXIT CODES paragraph reverted, the cap back to 477, the token or the config directory dropped from the environment, and without_a_real_gh either keeping every directory or dropping the shared ones: each is caught by at least one test, and a title with the leg names swapped, which no test caught at first, is caught by the title assertion added for it.

Evidence for the whole PR

• Reproduction (the issue's script, unchanged but for temp paths, on c7c02fa, git 2.43.0): both loops exit 2 with every message the issue quotes; the first printed no VERIFICATION table.
• Every non-zero exit of execute, with line numbers, is tabulated in the lane's report. Also run: first gh repo create refused (exit 2, nothing created), second refused (spec leg exists, empty), split push refused by a hook (exit 2, legs pushed), and the naive re-run after the topic exit (refused at gh repo create, as a taken name is).
• Targeted tests on the head (c5a8a55, origin/main a1b3a4b merged in):
  • tests/test_repo_hygiene.py tests/test_cli_reference.py tests/test_adopt_github_exits.py: 74 passed.
  • tests/test_adopt_e2e.py tests/test_adopt_plan.py: 75 passed, 1 skipped (SHAPE_MEDXEHR_CLONE is unset: the MedxEHR-backed plan test needs a read-only clone of MedxSoft/MedxEHR).
  • tests/test_adopt_execute_refusals.py tests/test_adopt_verify.py: 53 passed.
  • tests/test_git_output_decoding.py (origin/main's text-mode guard, which reads test files like this PR's): 67 passed.
  • scripts/render-cli-reference.py --check: docs/cli.md is what the generator produces.

Composition (git merge-tree --write-tree HEAD <ref>, head c5a8a55, origin/main a1b3a4b)

• origin/main, adopt-project.py: execute prints the command and its stderr when a leg cannot be built, so a git filter-repo that fails after both leg remotes exist no longer exits 2 with an empty stderr (#171) #184 (fix/adopt-report-filter-repo-failure, f416e13), adopt-project.py: a relative .gitmodules url the plan keeps in a leg is resolved from the source's remote and from the leg's, and where the two differ check finds it and execute refuses before any leg exists, so a recursive clone no longer fails after adoption verified (#190) #245 (fix/adopt-relative-submodule-url, d72544c, which now contains AGENTS.md, README and scaffold-project.py --help: say that a --spec-path or --code-path that is, holds or lies inside a file the shape writes, and a --pin of spec, code or shape or of one product twice, are refused before anything is created, and name those three in the pin refusal's remediation, so an agent briefed from AGENTS.md can say so before it runs the scaffold (#288) #309), and the lane-5 siblings F (69c54c9), K (21fbea4), L (8f43c96), M (14e2d68), Q (a30091f) and U (233dc71): all clean. AGENTS.md, README and scaffold-project.py --help: say that a --spec-path or --code-path that is, holds or lies inside a file the shape writes, and a --pin of spec, code or shape or of one product twice, are refused before anything is created, and name those three in the pin refusal's remediation, so an agent briefed from AGENTS.md can say so before it runs the scaffold (#288) #309 and adopt-project.py: the assembly root is cloned with no git template and the verification refuses a mount whose gitlink is not the commit pushed to its leg (adopt-mount-commit), so an operator's init.templateDir holding modules/spec and modules/code no longer ends adoption verified over a split nobody can clone (#243) #268 have landed; the one conflict with AGENTS.md, README and scaffold-project.py --help: say that a --spec-path or --code-path that is, holds or lies inside a file the shape writes, and a --pin of spec, code or shape or of one product twice, are refused before anything is created, and name those three in the pin refusal's remediation, so an agent briefed from AGENTS.md can say so before it runs the scaffold (#288) #309, the AGENTS.md cap in tests/test_repo_hygiene.py, is resolved in the merge commit (477 -> 481, cap 481 = wc -l AGENTS.md).
• adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188 (fix/adopt-late-failure-notice, 918e8f2): conflicts in AGENTS.md (step 7) and in six regions of adopt-project.py, all in code this PR rewrote and adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188 edits (nine regions in all, and three of those are adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188's own against origin/main since adopt-project.py: the assembly root is cloned with no git template and the verification refuses a mount whose gitlink is not the commit pushed to its leg (adopt-mount-commit), so an operator's init.templateDir holding modules/spec and modules/code no longer ends adoption verified over a split nobody can clone (#243) #268 landed, so they are not this PR's). Not resolved in either branch. The note for lane 1, with the joined step 7 (482 lines, cap 482), the join of each region and the one patch adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188's tests need, is posted on adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188: the two [...-pull-request] parametrizations of test_a_gh_step_after_the_split_gets_its_by_hand_exit call _open_the_pull_request alone and look for the by-hand text, which is _open_it_by_hand's now. Checked on a throwaway tree (87373a6, where adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188 merges clean, plus this PR's diff plus adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188, joined by hand, never committed): 106 passed over tests/test_adopt_github_exits.py, the whole of tests/test_adopt_late_failure.py, tests/test_adopt_verify.py and the cap test; without the one test patch exactly those two parametrizations fail. _flush_stdout() and the two imports are the same text on both branches, at the same place, so they merge to one definition.
• fix/adopt-record-submodule-placement (An adopted assembly records nothing about which leg a human chose for a source submodule, so shape-doctor.py cannot verify a kept gitlink's placement and can only note it; adopt should write the plan's submodule answers into the assembly #189, 3e86200), fix/adopt-root-kept-symlinks (6c44591), fix/adopt-plan-quote-yaml-keywords (e337f44): conflict in adopt-project.py (and, for An adopted assembly records nothing about which leg a human chose for a source submodule, so shape-doctor.py cannot verify a kept gitlink's placement and can only note it; adopt should write the plan's submodule answers into the assembly #189, the cap line) in exactly the same regions with this PR absent (git merge-tree origin/main <ref>: 1 + 1, 3 and 3 conflict regions either way); none of them is this PR's. With An adopted assembly records nothing about which leg a human chose for a source submodule, so shape-doctor.py cannot verify a kept gitlink's placement and can only note it; adopt should write the plan's submodule answers into the assembly #189 (cap 472, +8) as well the cap would be 489; arithmetic only. README.md, docs/handbook.html and docs/cli.md are not touched here, so the handbook's README-blob footer does not move.

At opening (origin/main 8cdca5e, which merges clean): lane 1 has since moved fix/adopt-plan-quote-yaml-keywords to d38e143, which now merges clean, and #189 to 27d039b.

Left out, and why

• README.md and docs/handbook.html: unchanged. Neither states the rule: README's adoption section and the handbook's #adopt say that execute verifies and never say what a non-zero exit means; their "re-run" / "clean re-run" sentences are the scaffold's (#partway, lane 4's AGENTS.md, README and scaffold-project.py --help: say that a --spec-path or --code-path that is, holds or lies inside a file the shape writes, and a --pin of spec, code or shape or of one product twice, are refused before anything is created, and name those three in the pin refusal's remediation, so an agent briefed from AGENTS.md can say so before it runs the scaffold (#288) #309 territory). Changing the README would also move the handbook's machine-checked README.md blob footer for no gain.
• The verification footer and --help. The footer (_verify, exit 1) is true for the exit it describes, and tests/test_adopt_verify.py holds its text; adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188 rewrites it. --help carries no exit-code text.
• NEXT: review the pull request on <root> under --local-remote-dir is still printed, as it always was, with no pull request ever opened. This PR stops saying it after a refused pull request (fix round 2); a local run is a test or rehearsal path, and its NEXT block is the only clone-and-bootstrap guidance it has.
• Candidate follow-ups, not done:
  • GitHub mode opens the pull request BEFORE it verifies, so a failed verification leaves a pull request open for the wrong split (probed, a source's own pin kept in the root: pull request .../pull/1 printed, then the finding, exit 1). Verify, then open, would avoid it, at the cost of reordering every successful run's output.
  • After a refused pull request the topic is not tried and the by-hand text does not list the three gh repo edit commands, so a person who opens the pull request by hand still has no topic set.
  • The topic's by-hand commands print above the table in a merged log (line 21 of 26 with adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188 composed, line 7 on main): _set_the_topic prints them before _verify runs, so adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188's _flush_stdout() only stops them jumping ahead of the leg lines. _set_the_topic's docstring ("the caller reports it after the table") is false on main and stays false with adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188. Printing them after the verification, the way this PR does for the pull request, would make it true.
• No remediation on three exit 2s (a refused gh repo create, a refused split push, a failed git filter-repo): on c7c02fa each prints a REFUSED block or, for the last, nothing at all (probed: exit 2, empty stderr, two leg repositories left). adopt-project.py: execute prints the command and its stderr when a leg cannot be built, so a git filter-repo that fails after both leg remotes exist no longer exits 2 with an empty stderr (#171) #184 and adopt-project.py: a failure AFTER both legs are pushed (the split-branch push, the mount, the split commit) prints only REFUSED <step> with no notice of what already exists and no stdout flush, so the combined log shows REFUSED before the bare … lines and the re-run meets leg-remote-exists unexplained #188 are the open PRs on these.

Review

An adversarial review of 16aa9ff found 2 should-fix items and 8 nits. Fix round 2 addresses all of them. A re-verification of c5a8a55 found 0 blockers, 0 should-fix items and 4 nits:

• the end-to-end environment still passes GH_HOST and the enterprise tokens through;
• this body's composition tips had moved (refreshed above);
• two counts in lane 1's composition note were off (corrected before posting);
• the not verified half of the NEXT condition has no test.

No probe ran the real gh: every probe used a stub first on PATH, a bogus GH_TOKEN and an empty GH_CONFIG_DIR.

Closes #304

🤖 Generated with Claude Code

Summary by Sourcery

Handle post-push GitHub refusals as manual completion paths while verifying the split first and preserving failed-verification precedence.

New Features:

• Add GitHub-mode end-to-end coverage for refused pull requests, failed topics, verification precedence, command output ordering, and safe gh execution environments.

Bug Fixes:

• Continue verification after a refused gh pr create, only provide a by-hand pull-request command when verification passes, and ensure verification failures retain exit 1 precedence.
• Prevent refused pull-request handling from attempting topic updates or emitting misleading next steps.
• Preserve by-hand instructions when stdout is closed and ensure they appear after verification output.

Enhancements:

• Clarify agent guidance and CLI exit-code documentation so GitHub exit 2 cases after successful pushes are completed manually rather than rerun.
• Print a complete, shell-quoted, non-interactive gh pr create command with the original title and body.

Tests:

• Add comprehensive tests covering GitHub refusal paths, output ordering, command fidelity, verification precedence, closed stdout handling, and protection against invoking a real GitHub CLI.

Chores:

• Update the AGENTS.md line-count hygiene cap for the expanded guidance.

[brettheap]

(lane openRepoShape-5, 2026-10-12T13:26Z) @codex review

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

[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 execute distinguish verification failures from post-push GitHub refusals: a refused pull-request creation now proceeds through verification, prints a complete manual command only for a verified split, and returns exit 1 when verification fails; documentation and extensive isolated end-to-end tests are updated accordingly.

Sequence diagram for GitHub pull-request refusal verification

sequenceDiagram
    participant User
    participant Execute as adopt-project.py execute
    participant GitHub as gh
    participant Verify as _verify
    participant Manual as _open_it_by_hand

    Execute->>GitHub: _pull_request_command()
    GitHub-->>Execute: CommandFailed
    Execute->>Verify: _verify(...)
    Verify-->>Execute: verified
    Execute->>Manual: _open_it_by_hand(..., passed)
    Manual->>Manual: _flush_stdout()
    alt verification passed
        Manual-->>User: Open the pull request by hand
        Execute-->>User: exit 2
    else verification failed
        Manual-->>User: No pull request was opened
        Execute-->>User: exit 1
    end

Loading

Flow diagram for execute post-push exit handling

flowchart TD
    A[Legs and split branch pushed] --> B[gh pr create]
    B -->|succeeds| C[Set repository topic]
    B -->|refused| D[_verify]
    C --> E[_verify]
    D --> F{Verification passed?}
    E --> G{Verification passed?}
    F -->|yes| H[_open_it_by_hand]
    F -->|no| I[Report no pull request should be opened]
    G -->|yes| J{Topic set?}
    G -->|no| K[Report verification findings]
    H --> L[Print complete gh pr create command]
    L --> M[Exit 2]
    I --> N[Exit 1]
    K --> N
    J -->|yes| O[_next_steps]
    J -->|no| P[Print topic commands]
    O --> Q[Exit 0]
    P --> R[Exit 2]

Loading

File-Level Changes

Change	Details	Files
Clarifies exit-specific recovery guidance so completed GitHub adoptions are not rerun unnecessarily.	Distinguishes exit 1 verification failures from exit 2 post-push GitHub refusals. Directs reviewers and assistants to follow the command printed for IS pushed exits.	AGENTS.md tests/test_repo_hygiene.py
Ensures refused pull-request creation is verified before presenting manual recovery instructions.	Continues through _verify after gh pr create refuses and prevents topic setup on that path. Makes verification failure take precedence with exit 1 and suppresses the pull-request command when the split is invalid. Moves normal next-step guidance so it is omitted when no pull request exists. Flushes stdout safely before stderr recovery output, including closed-pipe handling. Builds one fully specified, shell-quoted gh pr create command for execution and manual reuse. Updates the module exit-code documentation to describe the two GitHub-specific exit 2 cases.	adopt-project.py
Adds end-to-end coverage for GitHub refusal paths, output ordering, command fidelity, verification precedence, and test isolation from real GitHub CLI state.	Uses a shell gh stub and local bare repositories to exercise GitHub-mode execution without network access. Checks pushed leg and split branches, exact refusal/manual-command text, verification tables, exit codes, and topic behavior. Verifies the printed pull-request command matches the refused invocation, including title and body. Covers merged stdout/stderr ordering and closed stdout without traceback. Protects tests from invoking a real gh by controlling PATH, token, and config directory.	tests/test_adopt_github_exits.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#304	Make AGENTS.md step 7 distinguish a failed verification (exit 1, fix the plan and re-run) from an exit 2 marked IS pushed (finish using the printed manual command and do not re-run), and document these post-push exit cases in the tool’s exit-code guidance.	✅
#304	When gh pr create is refused, run verification before returning and provide the manual command only after a passing verification, so the command is not offered for an invalid split and the verification table is available.	✅
#304	Add regression coverage for both GitHub-mode post-push refusals, including their exit guidance, pushed state, verification output, and the refused-PR verification-failure case.	✅

Possibly linked issues

• AGENTS.md step 7 tells an agent that a non-zero adopt-project.py execute exit is to fix the plan and re-run into fresh legs, but in GitHub mode execute exits 2 with the split pushed when gh pr create is refused, and exits 2 after adoption verified when the topic will not set, so following step 7 abandons a pushed adoption whose own exit is a command to run by hand #304: The PR updates step 7, verifies before reporting a refused pull request, documents exit 2, and adds regression tests.

---

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.

[sonarqubecloud]

Quality Gate passed

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