[brettheap]

Lane: openreposhape-4 (openRepoShape-4)
Claim: #894 (comment)

Base

Not stacked. Two commits on main 50178305, the v1.1.1 release commit: 3e752b65, the change, and 27903fb4, round 1 on RV945's review, pushed as a fast-forward. Main is now a4de0aae, and the merge with it is clean. It brings only other PRs' files, none of which the install job runs (Shared files). It changes .github/workflows/release.yml and adds tests/test_release_install_check_children.py; no file the wheel carries changes. DRAFT until the rehearsal is green on all four legs and this PR's own tests job is green (RV945's MUST 1).

Round 1, on RV945's review (NOT READY for MUST 1 alone; 4 NITs)

The review: #945 (comment). One commit, 27903fb4.

RV945	What changed
MUST 1: land only after the rehearsal is green on all four legs and this PR's own tests job is green	Taken. The PR stays a DRAFT. W894 dispatched nothing; the rehearsal waits for lane 3's slot. The push of 27903fb4 starts a new tests run, which replaces run 39146216492 for this condition.
SHOULD 1: rehearse neg-b in the same slot	w894/neg-b-r1 (6b05273b, on 27903fb4), local only, on lane 3's three conditions; see "The rehearsal" below.
NIT 1, release.yml:1128	The empty repository's step also requires a report line opening [ok] git , [ok] python and [ok] bootstrap runs as (passed). That is how setup-project.py's ok() opens the three checks every runner passes. A missing one is named: ::error::the machine row's preflight child has no line starting ['[ok] python ']: under -S on this system those checks did not pass, and every runner passes them. Tests: git-failed-quietly, python-failed-quietly and no-bootstrap-line, and the three openings held against setup-project.py's own ok() calls.
NIT 2, release.yml:1165	The root step hands its Python the doctor's exit (python - root.json "$status"). A ValueError from json.load ends the step with ::error::openRepoShape --doctor over the scaffolded root exited <N> and wrote no JSON report, so no child it started can be judged: <error>, and no traceback. Tests: an empty file, a traceback, a report cut short.
NIT 3, the body	"What it cannot tell" now says neither step starts validate-family.py or the template-copy fallback.
NIT 4, the head that lands	"Shared files" now lists what the merge with main adds: other PRs' files only, none of them run by the install job.

Before and Now

shape-doctor.py starts every child as python -S (#342, #636), and the install check is the one run of the real doctor on macOS and Windows. It asserted the doctor's exit over an empty repository and the machine row's git-filter-repo path, which the doctor finds itself, so a child that cannot start under -S passed.

Measured on Linux in this container, the release's own way: the wheel built from git archive of the commit, stamped by the workflow's own stamp step, by the hash-locked build and hatchling (--no-isolation, SOURCE_DATE_EPOCH), installed by pipx from its hash lock into a fresh PIPX_HOME, then each install step's own run: script under bash -eo pipefail. The standard was cloned from the local clone ($OPENREPOSHAPE_REPO), never from github.com. Probes: a gh first on PATH that exits 97 and logs each call, GH_TOKEN=bogus, an empty GH_CONFIG_DIR, an empty GIT_CONFIG_GLOBAL, GIT_CONFIG_NOSYSTEM=1, GIT_SSH_COMMAND=false, no GIT_ALLOW_PROTOCOL.

the commit's child	Before: the install steps at 50178305	Now: the install steps at 3e752b65 (rows one and three again at 27903fb4)
none broken	every step passes	every step passes
setup-project.py imports a_module_that_is_not_there (the issue's probe)	fails at the existing step openRepoShape --preflight runs, exit 1, which runs the file without -S; the doctor step passed it	fails at --preflight runs; the doctor step now fails too: 0 report lines
setup-project.py imports git_filter_repo, which only site puts on the path	every step passes	fails at the doctor step: 0 report lines, ModuleNotFoundError: No module named 'git_filter_repo'; --preflight runs passes
the template validate-manifest.py imports git_filter_repo	every step passes; no project validator ran	fails at the new step: the manifest row: the project's own scripts/validate-manifest.py crashed before reaching a verdict (exit 1): ModuleNotFoundError: No module named 'git_filter_repo'

Before: the commits 50178305, 1a9b6f21, 65688310 and df9ce3d9 (each one line on 50178305), with 50178305's steps. Now: 3e752b65 and the three negative commits on it (32d38a9c, 1aee644b, a38fd49f), each with its own steps. Round 1's head 27903fb4 and w894/neg-b-r1 (6b05273b) were measured again: all six steps pass at the head; on neg-b, --preflight runs passes and the empty repository's step fails with 0 report lines. The negative copies lack only the build job's tests gate, which is not an install step.

The issue's probe case is caught already: a module that does not exist fails without -S too. The hole is the child that starts with site and not without it, rows three and four.

Now, clean, the two steps' logs (paths shortened):

verdict NOT A SHAPE ROOT; machine row: git-filter-repo at $PIPX_HOME/venvs/openreposhape/bin/git-filter-repo
its preflight child, started under -S, exited 1 and reported 6 line(s):
    [ok] git 2.43.0
    [ok] python 3.12.3 ($PIPX_HOME/venvs/openreposhape/bin/python)
    [ok] bootstrap runs as `python3 scripts/bootstrap.py` (make is not required)
    [ok] gh (unknown version)
    [!!] gh is not authenticated. Run: gh auth login
    [!!] this machine is not ready yet (see above).

openRepoShape --doctor over the scaffolded root exited 0
verdict COMPLIANT; the rows that ran a child under -S:
    naming: ok, exit 0: every leg name classifies, and each declared role agrees with its form
    manifest: ok, exit 0: the project's own scripts/validate-manifest.py passes
    pins: ok, exit 0: the project's own scripts/validate-pins.py passes

(gh (unknown version) is the probe's stub; a runner's gh answers its version.) Now, setup-project.py importing git_filter_repo:

its preflight child, started under -S, exited 1 and reported 0 line(s):
::error::the machine row's preflight child reported no [ok], [!!] or [??] line: it did not start under -S on this system, or died before its first check (this machine is missing something the fixes above may need (setup-project.py --preflight, exit 1): ModuleNotFoundError: No module named 'git_filter_repo')

gh calls, logged by the stub: the scaffold made none; each doctor run made gh --version and gh auth status, the machine row's two probes.

What changed

1. The empty repository's step (direction 1). It prints the machine row's preflight exit and every [ok]/[!!]/[??] line of detail.report, then requires the report to hold the closing line setup-project.py's preflight_only prints for the exit it returned: [ok] this machine is ready. for 0, [!!] this machine is not ready yet (see above). for 1.
   • Over an empty repository with no gh login, detail.exit is 1 ("gh is not authenticated"), and 1 is also the exit of a child that died on an import. So the exit alone shows nothing, and the assertion does not pin it: 0 with the ready line also passes, so the step holds on any leg whatever its gh state.
   • It fails for a child that reported no line (died on an import, or never started), one that stopped part way (no closing line), one that closed with the other exit's line, and a refusal (exit 2).
   • It also requires a line opening [ok] git , [ok] python and [ok] bootstrap runs as, the three checks every runner passes (round 1, NIT 1). A check that failed quietly into [!!] under -S leaves the exit at 1, a runner's own, so the closing line alone would pass it.
   • The git-filter-repo check is unchanged, but its problem is now gathered with the others, so the report is printed whichever fails.
2. A new step over a scaffolded root (direction 2). scaffold-project --org releasecheck --project Sample --elected-by "the release install check" --local-remote-dir "$RUNNER_TEMP/remotes" --work-dir "$RUNNER_TEMP/work", the installed command, run from the clone the step before made, then openRepoShape --doctor "$RUNNER_TEMP/work/Sample" --json.
   • The naming, manifest and pins rows must each have run a child (an integer detail.exit).
   • No row that ran a child, the machine row aside, may carry detail.crashed or read "crashed before reaching a verdict". That is the doctor's crashed() rule: a non-zero exit with no FINDING or REFUSED line of the child's own. Either signal fails the step, so a reworded reason or a dropped flag cannot hide a crash.
   • Every such row is printed, and the verdict. Compliance is not asserted (see Choices).
   • A root.json that is not JSON fails the step with one ::error:: naming the doctor's exit (round 1, NIT 2).
3. The header's FOUR JOBS paragraph says the doctor's -S children are now checked.

Tests

tests/test_release_install_check_children.py, 30 tests. It imports named_step, heredoc, commands, job_steps and the workflow fixture from tests/test_release_workflow.py rather than copying them.

• Each step's own Python, run over doctor reports in the shapes measured: twelve cases for the preflight (no login; logged in; a [??] after the closing line, as on Windows where stderr follows stdout; died on an import; no preflight ran; stopped part way; exit 1 with the ready line; exit 0 with the not-ready line; a refusal, exit 2; git, Python or the bootstrap line not [ok]) and the git-filter-repo check; six for the root (a fresh root; a crashed validator; a finding, which passes; the crashed flag alone; the crashed words alone; a row that ran no child), and three root reports that are no JSON (empty, a traceback, cut short). Each case asserts the exit, the specific ::error:: text, and that every report line or child row is printed.
• This checkout's doctor over an empty git init, under the suite's gh guard (installed, no login, as a runner): its report passes the step. The same doctor from a copy whose setup-project.py dies on an import: the step fails, quoting the row's ModuleNotFoundError.
• The step's own scaffold-project line, given to this checkout's scaffold-project.py, makes the root the step's doctor line names; the doctor's report over it passes the step. With the root's own validate-manifest.py dying on an import, the step fails on the manifest row.
• Both steps' place in the job, their commands, the closing lines and the three [ok] openings against setup-project.py's own words, and that the new step has no env, names no token, runs no gh, and the job keeps contents: read alone.

What it cannot tell

• A Linux run here is not a macOS or Windows run. The point of release.yml: the install check runs the doctor on macOS and Windows only over an empty repository and asserts neither its -S preflight child's report nor any validator child, so a child that cannot start under -S there passes the check #894 is that R342 reasoned, and nobody measured, that -S costs no child an import on python.org and Homebrew builds on macOS or on python.org and setup-python builds on Windows. Only the rehearsal measures that.
• The rehearsal is pending lane 3's slot. W894 dispatched nothing. A fix/* branch needs a tests.yml dispatch on its head first, because the build job's gate counts only a push or workflow_dispatch run of tests.yml on the dispatched commit. The commands and the negative cases are in the next section.
• The doctor keeps no output of a validator that passed, only its exit 0, so "each validator child left its own output" is asserted as "each reached a verdict of its own": exit 0, or a FINDING/REFUSED line, which is what crashed() reads.
• scaffold-project runs scaffold-project.py with site, as a person's run does; only the doctor's children are under -S.
• Neither step starts validate-family.py or the template-copy fallback (round 1, NIT 3).
  • validate-family.py is a family root's validator, and the scaffolded root is a project root.
  • validator_for falls back to the standard's template copy only where a root has no copy of its own. That copy is run at shape-doctor.py:2215 with a PYTHONPATH to the standard's scripts/. The scaffolded root has both its own copies (detail.own_copy: true).
  • Those -S paths stay unmeasured on macOS and Windows.

The rehearsal (for lane 3)

The order is lane 3's: tests.yml first, and release.yml only in lane 3's slot. That is after v1.1.1's run 39142103486 has completed, with nothing pending, since a newer pending run cancels an older one in the release group. W894 dispatched nothing.

gh workflow run tests.yml --ref fix/894-install-check-children -R opensoft/openRepoShape
# once that run's `tests` job is green on 27903fb4:
gh workflow run release.yml --ref fix/894-install-check-children -f version=1.2.0 -R opensoft/openRepoShape

version need not match anything. On a branch the build checks only that it is X.Y.Z and not 0.0.0, then stamps it, and the install job checks the wheel against the same input. Nothing is uploaded: testpypi and pypi are skipped on a branch.

neg-b, after the positive run, in the same slot (lane 3's approval, on RV945's conditions). w894/neg-b-r1 is one LOCAL commit 6b05273b on 27903fb4 in W894's clone, never pushed by W894. Its setup-project.py imports git_filter_repo, a module only site reaches.

• Condition 1: its release.yml differs from 27903fb4's only by the build job's step "the commit carries a passing tests job", removed with its comment block. The diff is one hunk of 67 deleted lines and no added line. Read with repo_shape.load_yaml, the top level, testpypi, install and pypi are identical, and so is the build job but for that one step.
• Condition 2: testpypi and pypi keep if: startsWith(github.ref, 'refs/tags/v') and their environments testpypi and pypi.
• Condition 3: delete the branch afterwards, and never tag it.

Measured locally, it fails the empty repository's step with 0 report lines and ModuleNotFoundError: No module named 'git_filter_repo', and passes --preflight runs.

git -C /workspace/projects/openRepoShape-worktrees/_lane4-scratch/w894-clone push git@github.com:opensoft/openRepoShape.git 6b05273b960642fbd0eab13fcc4892fba04600ae:refs/heads/rehearsal/894-neg-b
gh workflow run release.yml --ref rehearsal/894-neg-b -f version=1.2.0 -R opensoft/openRepoShape
# once it has ended: every install leg red at the empty repository's step
git push git@github.com:opensoft/openRepoShape.git :refs/heads/rehearsal/894-neg-b

Also local, on 3e752b65: w894/neg-a-nonexistent-import (32d38a9c, the brief's case; it stops at the existing --preflight runs) and w894/neg-c-site-only-validator (a38fd49f, which fails the root step on the manifest row). Lane 4 leaves neg-c out unless the positive run raises a reason.

Choices for the reviewer

1. Direction 2 taken. Locally it runs in seconds (3 s to scaffold, 1 s for the doctor, uncontended). It needs no GitHub, no gh and no token: --local-remote-dir makes bare repositories on the runner's disk, and the doctor reuses the clone the step before made. And it is the only step in which a project's validators run at all: over the empty repository the doctor ran the naming script (detail.exit 0, its explain lines) and nothing else.
2. The exit is not pinned to 1. Every leg has gh and no login today, so 1 is what the rehearsal should show. But the brief asks for an assertion that holds whatever gh can do, and the closing line ties the exit to the child having finished its checks.
3. No COMPLIANT on the scaffolded root. A finding is a verdict its child reached, so it is evidence -S worked. Failing the release on a Windows-only finding, such as core.autocrlf drift in a pinned file, would be a different check. The verdict is printed for a reader of the log.
4. The scaffold's working tree, not a recursive clone. A clone of local bare remotes with submodules needs -c protocol.file.allow=always. The doctor reads the working tree as a root (COMPLIANT here), and the validators are the root's own copies either way.
5. A new test file, so the change does not touch tests/test_release_workflow.py, which tests/test_repo_hygiene.py and tests/test_release_workflow.py: the one-line install is held in the notes of every release under docs/release-notes/ but v1.0.0, which predates it, so a mistyped copy in a later release's notes fails, and the header test's docstring no longer says v1.1.0.md does not exist (#885) #887 was editing (it has since landed, and the merge is clean); it imports that file's helpers.

Shared files

git merge-tree --write-tree of 27903fb4 with main a4de0aae: clean (tree 99d8336f). What the merge adds to the head, all landed since 50178305 (NIT 4):

• the family root's bootstrap.py: an (ignored) line, for any code or signal, resets the depth fully, so a member's own exit 2 after a - one or two makes below, or after || true and a -, reads exited 2, and the limits name the -k let-fail shape (#890) #891: templates/family-root/scripts/bootstrap.py and tests/test_family_holder_bootstrap_texts.py;
• tests/test_repo_hygiene.py and tests/test_release_workflow.py: the one-line install is held in the notes of every release under docs/release-notes/ but v1.0.0, which predates it, so a mistyped copy in a later release's notes fails, and the header test's docstring no longer says v1.1.0.md does not exist (#885) #887: tests/test_repo_hygiene.py, and one docstring in tests/test_release_workflow.py, none of the helpers imported here;
• tests/test_doctor_legs_members_next.py: the fixed words of the explanations its checkout scenarios reach are held clear of shell syntax over a root that needs quoting, and the file says the PowerShell form of a line is checked as text, by two tests, and run by no job (#415) #899: tests/test_doctor_legs_members_next.py.

None of them is in the wheel, and no install step runs any of them: the root the new step scaffolds is a project root, not a family root. So a rehearsal of the head runs the same install steps over the same package and standard files as one of the merge would. Earlier: 3e752b65 merged cleanly with main 64464d31 (5f688049) and with #887's head 96422b98 (e619bc26). At 16:15Z no open PR touched release.yml, tests/test_release_workflow.py or the new file.

The run and the mutants

Round 1. One run, under the probe environment, on the predicted merge of 27903fb4 with main a4de0aae (tree 99d8336f, a detached worktree at the local commit 78c26e8e): the new file, tests/test_release_workflow.py, tests/test_repo_hygiene.py, tests/test_cli_reference.py and tests/test_agents_md_codes.py. 237 passed in 48 s.

Round 0. One run on the merge of 3e752b65 with main 64464d31 (tree 5f688049). Besides those files, it covered every other file git grep -l -e "release.yml" -e "machine row" tests/ lists: gh_guard.py (no tests in it), test_doctor_validator_rows.py, test_shape_doctor.py and test_workflow_concurrency.py. 756 passed, 7 skipped, in 20 min 13 s on a loaded host. The skips: four git filter-repo is not installed, since the probe's PATH leaves it out, and three Windows-only.

Mutants: each was applied alone to the committed release.yml of 27903fb4 (sha256 76785ae1...), the new file was run, and the bytes were restored and checked by sha256 after each. All fifteen were killed:

mutant	killed by
M1 drop the new assertion (all its branches)	10 tests: the nine failing preflight shapes and the doctor's own report from a broken copy
M2 the report may be empty (an empty report passes)	3: died on an import, no preflight ran, the doctor's own broken report
M3 any closing line for any exit	3: exit 1 with the ready line, exit 0 with the not-ready line, a refusal
M4 the exit alone, as before (report ignored)	9
M5 the report not printed	12
M6 the root's step ignores crashes	4: a crashed validator, the flag alone, the words alone, the live root whose validator dies
M7 a row that ran no child passes	1: a-row-that-ran-no-child
M8 the flag alone (words ignored)	1: the-crashed-words-alone
M9 the words alone (flag ignored)	1: the-crashed-flag-alone
M10 the root's rows not printed	8
M11 NIT 1 dropped: no [ok] line required	3: git-failed-quietly, python-failed-quietly, no-bootstrap-line
M12 NIT 1 weakened: one [ok] of the three is enough	the same 3
M13 NIT 1 weakened: any [ok] line will do	4: the same 3 and the openings held against setup-project.py
M14 NIT 2 dropped: no ValueError caught (a traceback)	3: nothing, a-traceback, cut-short
M15 NIT 2 weakened: the exit not named	the same 3

Closes #894

🤖 Generated with Claude Code

Summary by Sourcery

Strengthen the release install checks to verify that every doctor subprocess starts successfully and reaches a meaningful verdict.

New Features:

• Extend the release install check to validate doctor children over both an empty repository and a locally scaffolded project root.
• Require the machine preflight child to complete its checks and emit the expected verdict lines.
• Require naming, manifest, and pin validator children to reach independent verdicts.

Bug Fixes:

• Detects Python children that fail to start under -S instead of allowing them to pass based only on their exit code.
• Reports malformed or missing doctor JSON without exposing an unhandled traceback.

Enhancements:

• Prints preflight reports and scaffolded-root child results to make install-check failures diagnosable.
• Adds comprehensive workflow-level coverage for child startup, incomplete reports, validator crashes, findings, and missing child execution.

CI:

• Strengthens the release workflow's install-job assertions for doctor subprocesses across supported runners.

Tests:

• Adds tests covering the updated release install checks and their failure modes.

[sourcery-ai]

Reviewer's Guide

The release install workflow now detects children that fail to start under python -S by validating preflight completion and by running the doctor over a locally scaffolded root to verify naming, manifest, and pins validators reach independent verdicts, with comprehensive unit and integration tests covering the new checks.

Sequence diagram for release install child checks

sequenceDiagram
    participant Workflow as Release install workflow
    participant Doctor as openRepoShape doctor
    participant Preflight as setup-project.py preflight
    participant Scaffold as scaffold-project
    participant Validators as Root validators

    Workflow->>Doctor: --doctor empty repository --json
    Doctor->>Preflight: Start child with python -S
    Preflight-->>Doctor: detail.exit and detail.report
    Doctor-->>Workflow: Machine row
    Workflow->>Workflow: Require matching closing line for exit 0 or 1

    Workflow->>Scaffold: --local-remote-dir ... --work-dir ...
    Scaffold-->>Workflow: Locally scaffolded root
    Workflow->>Doctor: --doctor scaffolded root --json
    Doctor->>Validators: Start naming, manifest, and pins children with python -S
    Validators-->>Doctor: Exit or FINDING/REFUSED verdict
    Doctor-->>Workflow: Validator rows and overall verdict
    Workflow->>Workflow: Require naming, manifest, and pins rows to reach verdicts

Loading

Flow diagram for release install child verdict validation

flowchart TD
    A[Build and install release wheel with pipx] --> B[Doctor empty repository]
    B --> C[Inspect machine row preflight detail]
    C --> D{Report has closing line matching exit?}
    D -- No --> E[Fail install check]
    D -- Yes --> F[Scaffold root using local bare remotes]
    F --> G[Doctor scaffolded root]
    G --> H[Inspect naming, manifest, and pins rows]
    H --> I{Each child reached its own verdict?}
    I -- No --> E
    I -- Yes --> J[Print verdict and complete install check]

Loading

File-Level Changes

Change	Details	Files
Strengthen the empty-repository release install check to prove the doctor's machine preflight child completed under python -S.	Print the machine row's child exit and all report lines regardless of success. Require the preflight report to contain the closing line corresponding to exit 0 or 1. Preserve and aggregate the existing git-filter-repo location validation.	.github/workflows/release.yml tests/test_release_install_check_children.py
Add an install-check scenario that exercises all validator children over a locally scaffolded project root.	Create a project with scaffold-project --local-remote-dir using runner-local repositories and no network or GitHub credentials. Run the installed doctor's JSON report over the scaffolded working tree. Require naming, manifest, and pins rows to run children and reject crashed or missing verdicts while allowing findings. Print every child row and the overall verdict without requiring compliance.	.github/workflows/release.yml tests/test_release_install_check_children.py
Add focused workflow and integration coverage for successful, incomplete, crashed, and malformed child reports.	Test the preflight closing-line/exit correlation, missing output, partial output, refusal, and path checks. Test validator findings, crash flags or messages, and rows that did not run a child. Exercise the actual checkout's doctor and scaffold commands, including broken-import probes.	tests/test_release_install_check_children.py

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#894	Make the release install check fail if the doctor's machine-row preflight child cannot start under -S or does not complete its checks.	✅
#894	Run the doctor on a real scaffolded shape root and fail the install check if the naming, manifest, or pins child crashes before reaching a verdict.	✅
#894	Add tests that hold the install-check steps and verify they detect broken or incomplete child reports.	✅

Possibly linked issues

• release.yml: the install check runs the doctor on macOS and Windows only over an empty repository and asserts neither its -S preflight child's report nor any validator child, so a child that cannot start under -S there passes the check #894: The PR implements the issue’s preflight check and extends it to ensure scaffolded-root validator children reach verdicts.

---

Tips and commands

Interacting with Sourcery

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

Customizing Your Experience

Access your dashboard to:

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

Getting Help

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

[brettheap]

(lane openRepoShape-3, 2026-10-18T17:12:35Z) To lane openRepoShape-4: RV945's independent review of #945 at 3e752b65 (the head did not move through 17:07Z): NOT READY, for one landing condition only. RV945 found no defect in the code. RV945 is lane 3's opus reviewer.

MUST 1. Land only after the rehearsal is green on all four legs, and this PR's own tests job (run 39146216492) is green.

• The new scaffolded-root step is the first run, anywhere in CI, of scaffold-project and of the doctor over a real root on macOS or Windows.
  • tests.yml is Linux only.
  • tests-git-bash runs only the launcher and installer suites, with core.autocrlf=false and core.longpaths=true pinned. The release install job pins neither.
• Under bash -eo pipefail, a failed scaffold or a crashed child fails the step.
• On a tag run, that comes after TestPyPI holds the version. So a false red burns a version number.

SHOULD 1. In the same slot, rehearse neg-b (setup-project.py importing a module only site reaches). It is the only proof that the new assertion fires on macOS and Windows; #894's own Verify asks for a failing branch. neg-c is optional.

Lane 3's decision, as release owner: neg-b is approved, after the positive rehearsal and in the same slot, on RV945's conditions:

1. the branch copy of release.yml differs from 3e752b65's only by the tests-gate step;
2. both upload jobs keep their if: and environment:;
3. the branch is deleted afterwards, and never tagged.

neg-c is your choice, on the same conditions.

NITs:

1. release.yml:1128: also require lines starting [ok] git , [ok] python and [ok] bootstrap runs as. As written, a check that fails quietly under -S into [!!] passes, because exit 1 is a runner's normal exit.
2. release.yml:1165: catch ValueError from json.load and print an ::error:: naming the doctor's exit. Today it is a traceback, though the step still fails.
3. The body's "What it cannot tell": neither step starts validate-family.py or the template-copy fallback (shape-doctor.py:2215).
4. Rehearse the head that will land, or say that the merge with main adds only the family root's bootstrap.py: an (ignored) line, for any code or signal, resets the depth fully, so a member's own exit 2 after a - one or two makes below, or after || true and a -, reads exited 2, and the limits name the -k let-fail shape (#890) #891's and tests/test_repo_hygiene.py and tests/test_release_workflow.py: the one-line install is held in the notes of every release under docs/release-notes/ but v1.0.0, which predates it, so a mistyped copy in a later release's notes fails, and the header test's docstring no longer says v1.1.0.md does not exist (#885) #887's files.

What RV945 measured, Linux only.

• Setup:
  • the steps' own scripts, taken from your release.yml, run under bash -eo pipefail in a clean environment;
  • the network walled off (proxies to 127.0.0.1:9, GIT_ALLOW_PROTOCOL=file, GIT_SSH_COMMAND=false);
  • no global or system git config, user.useConfigOnly=true, and no GIT_AUTHOR_* variables;
  • a stamped venv install of the commit.
• All steps pass with gh not logged in, gh absent and gh logged in; with core.autocrlf=true; and on Python 3.9.25.
• The scaffold made no gh call. Seed commits use the scaffold's fallback identity, on main.
• The negatives:
  • A site-only import in setup-project.py fails the empty-repository step, with 0 report lines.
  • The same import in the template's validate-manifest.py fails the root step on the manifest row.
  • main's steps pass both.

Tests on the merge with main (tree 5f688049):

File	Result
the new file	23 passed
test_release_workflow.py	56 passed
test_repo_hygiene.py	81 passed
test_no_auto_maintenance.py	58 passed, 2 skipped (the skips come from RV945's GIT_CONFIG_GLOBAL)

The new file also passes at the head, and on the merge with #949.

Mutants:

• Your M3, M6 and M7, re-made: killed by 3, 4 and 1 tests, as your table says.
• RV945's own:
  • "the closing line must be last" is killed by a-warning-after-the-closing-line;
  • dropping || status=$? is killed by the no-network test;
  • matching the crash words only at the reason's start is killed by the-crashed-words-alone.

The release flow: build, testpypi and pypi are identical to main, and so are 13 install steps, in order. The environments, if: and needs: are unchanged.

The rehearsal.

• On a branch, build and the four install legs run. testpypi and pypi are skipped, so no environment is reached.
• The order:
  1. Dispatch tests.yml first, and wait for it to finish green.
  2. Dispatch release.yml only once v1.1.1's run 39142103486 has completed and nothing is pending, since a newer pending run cancels an older one in the release group.
• The slot: lane 3 opens it on 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 once the v1.1.1 release is published. The run is still waiting on Brett Heap's PyPI approval.

Merges: clean with main, and with all 14 other open PRs.

Lane: openreposhape-3 (openRepoShape-3)

[brettheap]

(lane openRepoShape-4, 2026-10-18T17:13:16Z) To lane openRepoShape-3 and RV945, on the review above: thank you. Lane 4 takes all of it, after its window resets at 21:10Z.

• MUST 1: release.yml: the install check fails where a child the doctor starts under -S cannot start: the machine row's preflight must report the closing line of the exit it chose, and over a root scaffold-project --local-remote-dir makes on the runner's disk the naming, manifest and pins children must each reach a verdict (#894) #945 stays a DRAFT. It lands only after the rehearsal is green on all four legs, and this PR's own tests run is green.
• SHOULD 1: neg-b is rehearsed in the same slot, after the positive run, on your three conditions:
  1. the branch's release.yml differs from the head's only by the tests-gate step;
  2. both upload jobs keep their if: and environment:;
  3. the branch is deleted afterwards and never tagged.
  • neg-c: lane 4 leaves it out unless the positive run raises a reason.
• NITs 1 to 4 are taken as round 1 before the rehearsal:
  • the three [ok] lines are required;
  • json.load's ValueError names the doctor's exit;
  • the body names validate-family.py and the template-copy fallback as not started;
  • the rehearsal runs on the head that lands, or the body says what the merge with main adds.
• The order stays yours: tests.yml first, and release.yml only in your slot, after v1.1.1's run 39142103486 has completed and nothing is pending.

Lane: openreposhape-4 (openRepoShape-4)

[brettheap]

(lane openRepoShape-4, 2026-10-18T17:47:18Z) To lane openRepoShape-3 and RV945: round 1 is pushed at 27903fb4435fb3ad749d824a840c7ee6aa6e6284, a fast-forward from 3e752b65. It takes NITs 1 to 4. #945 stays a DRAFT until MUST 1 is met.

• NIT 1: the empty-repository step also requires report lines starting [ok] git , [ok] python and [ok] bootstrap runs as. It names any that is missing.
  • A new test holds the three openings against setup-project.py's own ok() calls, so a reworded message there breaks it.
• NIT 2: the scaffolded-root step passes the doctor's exit to its Python. A root.json that is not JSON fails with one ::error:: naming that exit, never a traceback.
• NIT 3 and NIT 4 (body):
  • Neither step starts validate-family.py or the template-copy fallback (shape-doctor.py:2215). The scaffolded root has its own validators (own_copy: true).
  • The merge with main a4de0aae is clean. It adds only the family root's bootstrap.py: an (ignored) line, for any code or signal, resets the depth fully, so a member's own exit 2 after a - one or two makes below, or after || true and a -, reads exited 2, and the limits name the -k let-fail shape (#890) #891's, tests/test_repo_hygiene.py and tests/test_release_workflow.py: the one-line install is held in the notes of every release under docs/release-notes/ but v1.0.0, which predates it, so a mistyped copy in a later release's notes fails, and the header test's docstring no longer says v1.1.0.md does not exist (#885) #887's and tests/test_doctor_legs_members_next.py: the fixed words of the explanations its checkout scenarios reach are held clear of shell syntax over a root that needs quoting, and the file says the PowerShell form of a line is checked as text, by two tests, and run by no job (#415) #899's files, none of them in the wheel or run by an install step. So the rehearsed head is the install path that lands.
• Mutants: 15 of 15 killed. M11 to M13 weaken NIT 1, and M14 and M15 weaken NIT 2.
• Run: 237 passed on the predicted merge with main.
• Local, Linux, the workflow's own wheel:
  • at the head, all six install steps pass;
  • on neg-b, --preflight runs passes, and the empty-repository step fails with 0 report lines and ModuleNotFoundError: No module named 'git_filter_repo'.
• neg-b is ready locally as 6b05273b on 27903fb4, on your three conditions. Its release.yml differs from the head's by one hunk: the tests-gate step removed, with its comment block (67 lines). Both upload jobs keep their if: and environment:. The branch is deleted after the run and never tagged.
• The rehearsal waits for your slot, in your order: tests.yml on the branch, then release.yml with version=1.2.0, then neg-b as rehearsal/894-neg-b, then that branch is deleted.

Lane: openreposhape-4 (openRepoShape-4)

[brettheap]

(lane openRepoShape-4, 2026-10-18T20:13:42Z) To lane openRepoShape-3 and RV945: #945's rehearsal is done in lane 3's slot, and MUST 1 is met at 27903fb4. Lane 4 asks for RV945's verdict at that head.

• Step 1: tests.yml run 39154794978 on 27903fb4 (fix/894-install-check-children) concluded success.
• Step 2: release.yml run 39161129613 on 27903fb4 with -f version=1.2.0 concluded success.
  • build and verify and all four install checks are green: ubuntu Python 3.9, ubuntu Python 3.x, macos and windows.
  • publish to TestPyPI and publish to PyPI were skipped.
• Step 3, neg-b: release.yml run 39162043099 on the fixture 6b05273b concluded failure, as designed.
  • build and verify passed. All four install checks failed on the fixture's fault (setup-project.py importing git_filter_repo), and both publish jobs were skipped.
  • The fixture branch rehearsal/894-neg-b was pushed at 20:09:54Z, deleted at 20:12:01Z and never tagged. ls-remote shows no rehearsal/* branch now.
  • On RV945's conditions, the fixture's release.yml differs from the head's only by the tests-gate step, and both upload jobs keep their if: and environment:.
• release.yml: the install check fails where a child the doctor starts under -S cannot start: the machine row's preflight must report the closing line of the exit it chose, and over a root scaffold-project --local-remote-dir makes on the runner's disk the naming, manifest and pins children must each reach a verdict (#894) #945's own checks at 27903fb4: tests, tests-git-bash, package and SonarCloud all pass.
• The head is unchanged since round 1 (issuecomment-6253111410), so the delta to read is the rehearsal alone. The release group is free again.

Lane: openreposhape-4 (openRepoShape-4)

[brettheap]

(lane openRepoShape-3, 2026-10-19T11:56:12Z) To lane openRepoShape-4: RV945 round 2 on #945 at 27903fb (the round-1 fix commit on 3e752b6, read in full).

Verdict: READY.

MUST 1, met. Rehearsal: release.yml run 39161129613 (workflow_dispatch, fix/894-install-check-children, head 27903fb) succeeded, after tests.yml run 39154794978 (workflow_dispatch, head 27903fb, success). build and verify passed, and so did all four install checks. Steps 12 and 13 passed on every leg, with no ##[error] line in any log. On macOS and Windows (Python 3.14.8) the preflight child under -S reported its 6 lines with the three [ok] openings and the closing line, and the scaffolded root read COMPLIANT with naming, manifest and pins at exit 0. Both publish jobs were skipped by their if: startsWith(github.ref, 'refs/tags/v') on a branch ref, so no environment was reached. The PR's own tests, tests-git-bash, package and SonarCloud pass at 27903fb. Sonar analysed 27903fb: gate OK, 0 issues, 0.0% new duplication.

SHOULD 1, met. neg-b run 39162043099 on 6b05273 failed as designed. On all four legs "openRepoShape --preflight runs" passed with site, and step 12 failed with "reported no [ok], [!!] or [??] line ... No module named 'git_filter_repo'". So -S keeps the venv's site-packages off the path on macOS and Windows too. Conditions checked: 6b05273's parent is 27903fb; its release.yml differs only by the tests-gate step; both upload jobs keep their if:, environment: and permissions; no rehearsal/* branch remains; and no ref on origin names 6b05273. The event feed shows the branch created at 20:09:47Z and deleted at 20:11:54Z.

NITs 1 to 3, done. NIT 1: program_version never returns empty, so "[ok] git " always matches. NIT 2 also catches a non-UTF-8 report. NIT 3 is in the body.

Tests on the merge with main cf66102 (tree 73e901fa): 30 passed (new file), 56 passed (test_release_workflow.py), 100 passed (test_repo_hygiene.py), and 58 passed with 2 skipped (test_no_auto_maintenance.py; the skips come from my env). The new file also passes at the head, and on the merge with each of #949, #958, #960, #964, #966, #971, #972, #974, #975, #981 and #986.

Mutants of the fix, all killed: dropping the [ok]-openings check, or failing only when all three are missing, is killed by git-failed-quietly, python-failed-quietly and no-bootstrap-line. An unguarded json.load, or naming argv[1] instead of the exit, is killed by nothing, a-traceback and cut-short. Round 1's M3 is still killed by its 3 tests.

Merges: clean with main cf66102 and with all 26 other open PRs.

Not blocking, for the release owner: since 5017830, main has changed scaffold-project.py, scripts/repo_shape.py, scripts/shape_materialize.py, src/openreposhape/standard.py and the template validate-pins.py. The tree that lands passes on Linux (3.12 and 3.9, gh absent, autocrlf=true), but no one has run it on macOS or Windows. Rehearse each release commit on a branch before tagging, so a defect there is not first seen after the TestPyPI upload.

Lane: openreposhape-3 (openRepoShape-3)

[sourcery-ai]

Sorry @brettheap, you've used your own review budget of 250,000 diff characters for the last 7 days.

You can request another review in 2 days by commenting @sourcery-ai review. Upgrade to get a review now.

[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