[brettheap]

Part of #228: pull request 3 of 4 of feature 006-release-pypi, plan.md "Delivery". It holds User Story 5, which is Phase 7 of specs/006-release-pypi/tasks.md (T018 to T021).

One dispatched workflow now builds the wheel, uploads it to TestPyPI, checks the install on three legs, and uploads it to PyPI. .github/workflows/release.yml has four jobs, build, testpypi, install and pypi, and tests/test_release_workflow.py holds it.

Nothing is published here. release.yml's on: block holds workflow_dispatch and nothing else, with one required string input, version (release.yml:231-241). No push, tag, pull request or schedule starts a run. The two upload jobs also run only on a v* tag, so a dispatch on a branch uploads nothing.

• Environments: testpypi runs in the GitHub environment testpypi, and pypi in the environment pypi.
• Authentication: trusted publishing (OIDC). id-token: write is granted to those two jobs and to no other, and the file holds no PyPI token and no secrets. reference (grep -c 'secrets\.' gives 0).

No lane pushes a tag or dispatches the workflow without Brett Heap's word (plan.md gate G8).

What it adds

• tests/test_release_workflow.py (T018, 7b5167a): the tests come before the workflow, so every test that reads release.yml fails until T019 to T021 write it, naming the file and the tasks. They read it with the pinned openRepoShape's own load_yaml (research R9), and skip without the submodule.
  • The shape: grep -c '^def test_' counts 56 test functions at T018 and 66 at the fix head 9682f0b, under ten prefixes: test_release_trigger_, _lock_, _build_, _stamp_writer_, _guard_build_, _guard_upload_, _upload_, _install_check_, _reads_ and _header_. The lock tests and the digest-label test read nothing of release.yml, so they pass before it exists.
  • Run, not only read: each step is run as GitHub runs a bash step, with every GITHUB_*, RUNNER_*, LANES_* and TMUX* variable removed, and gh and curl faked.
    • That covers the repository guard under every row of contracts/workflows.md's table, each upload job's first-step guard, the version check, the ref and branch steps under the rehearsal rule, the gate on tests.yml's four jobs, and the digest step, which also runs in a copy of the checkout whose standard or pin names another definition.
    • The wheel check runs on synthetic wheels made from HEAD's blobs. The wheel as built passes, as a final and as a pre-release. A wheel with no licenses/LICENSE, a changed payload byte, a mode 0755 made 0644, or a mode 0644 made 0755 fails, and a line of its refusal names the file.
    • The stamp writer is run on a copy of the committed stamp and read back by --version from a package_tree. It refuses a file already stamped, and a value no release carries.
• release.yml's shape and its build job (T019, 0de7213): adapted step for step from openRepoShape v1.1.0 (190133d), under the model's step names, with design.md Decision 10's differences.
  • The shape: workflow_dispatch with version, permissions: {}, the release concurrency group that never cancels, bash by default, and VERSION and PYTHONUTF8 in env.
  • build: contents: read and actions: read, 16 steps (counted at 29cc1b3), and five outputs: wheel, wheel-sha256, digest, to-testpypi and to-pypi. In order, it:
    • checks the version, X.Y.Z or X.Y.ZrcN and never 0.0.0, and runs the repository guard (FR-048), which records to-testpypi and to-pypi;
    • checks the ref (on a tag, the annotated tag v<version> whose object names the run's commit, read from the forge and from git; on a branch, a rehearsal; any other ref is refused), that the commit is on main or on release/v<major>.<minor>, and that the checkout is that commit and clean;
    • reads both environments' rules, and the gate: guard-launch-mode, tests, tests-no-submodule and package each ran in a push or dispatch run of tests.yml on this commit, none is still running, and the newest to finish succeeded;
    • holds the digest: the pinned submodule's tree_digest equals tree_digest_from_gh, and its TREE_DIGEST_DEFINITION equals the literal sorted-ls-tree-r-v1 and the pin's digest_definition;
    • installs the tools from the build lock by hash, extracts the commit twice with git archive, writes the five-field stamp into both (REPOSITORY from GITHUB_REPOSITORY), builds each with python -m build --wheel --no-isolation, and requires one file;
    • checks the wheel against the commit's own blobs, byte for byte and mode for mode, then records its name and sha256 and uploads it as an artifact.
  • Every action is pinned by a full commit, with its release tag beside it.
• release.yml's testpypi, install and pypi jobs (T020, fb2249f): TestPyPI, then the install check, then PyPI.
  • testpypi and pypi: each runs in its own environment, on a v* tag and where the build's record says so (to-testpypi, to-pypi), so pypi is skipped in an rc rehearsal. Each holds exactly id-token: write, actions: read and contents: read.
    • The first step is the repository guard again. TestPyPI takes any release from opensoft/openRepoTools-code and a pre-release alone from opensoft/openRepoTools. PyPI takes a final from opensoft/openRepoTools-code and nothing else.
    • Then come the model's steps as they are: the artifact and its sha256, the environment's rules, this run's approval and the tag read again, an index that holds no file of the version but the verified wheel, the upload by pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33, and the served digest read up to 20 times.
  • install (contents: read): ubuntu and macOS on Python 3.x, and ubuntu on 3.9, with no Windows leg.
    • The wheel comes from TestPyPI by its recorded digest on a tag, and is the build's artifact on a branch. pipx comes from its hash lock and places the one link, and --version is checked line for line.
    • The offline --install beside pipx's link is set up as tests.yml's package job sets its own: the skip line and the count line exact, 28 receipt rows, the link unchanged.
    • The macOS leg runs it again under /bin/bash, whose BASH_VERSION must begin 3.2. The 3.9 leg compiles the installed payload's lanes-index and lane-worktrees.
• release.yml's header, RELEASING (T021, a04b9e2): the header comment alone, in contracts/workflows.md's six sections, in order. The jobs are unchanged.
  • What the workflow does and its four jobs, with Decision 10's differences named.
  • The procedure, on Brett Heap's word: the CI wait, the annotated tag in v1.0.0's message form, the dispatch, the two approvals, gh release create once PyPI serves the version, then release/vX.Y at vX.Y.0.
  • Release branching: main stays the trunk; release/vX.Y branches carry tagged releases and their patches; v1.1.1 back-ported to release/v1.1 openRepoShape#850's branch and tag policy, the two rehearsals (never 1.1.0; 1.1.0rc1 first), where releases come from (the repository guard's table), and what the workflow never reads (FR-046).
• The empty-index ruling (ac2ca2b): the lead's ruling of 2026-10-18 on T020's first doubt, written into openspec/changes/release-tags-pypi/design.md, the pypi-package delta spec, specs/006-release-pypi/contracts/workflows.md and specs/006-release-pypi/spec.md. design.md numbers it item 15, as round 1 fixed it (a review NIT).
  • The upload jobs' empty-index check is the model's form. A 404 passes. The verified wheel already there at its digest, not yanked, passes, and the upload adds nothing new. Anything else refuses.
  • The strict form would make "Re-run failed jobs" impossible after an upload that went through but whose served-digest check timed out.
• The marks (29cc1b3): specs/006-release-pypi/tasks.md marks T018 to T021 done.
• The review's two fix rounds (c6cea2a and 9682f0b, 11 commits on 1b41ce7): they change three files and no other line of release.yml. git diff --stat 1b41ce7 9682f0b gives 3 files, 843 insertions and 56 deletions.
  • The three files: tests/test_release_workflow.py; one comment in release.yml (:1381-1383, which now says which test holds the install check's offline --install equal to tests.yml's, instead of saying the two cannot drift); and design.md's two NITs.
  • Round 1 (c6cea2a, 7 commits):
    • 1d5d657: a test holds the install check's offline --install to tests.yml's, line for line but for the fingerprint, and release.yml's comment says so;
    • 2ed477f: each upload job's guard is run on refs other than the version's own tag, and refuses each;
    • 5116295: the stamp writer writes neither copy until both are checked, and the whole step stamps the run's own repository;
    • d0620ab: the wheel check is run on one synthetic wheel per member check, each refused naming what is wrong;
    • 34f4239: the sha256 checks before each upload and before the install are held by their steps' names and commands, and the install check's is run (the review's MUST, under Review);
    • 5bc35c3: the build's guard is held to refuse a ref that is neither a tag nor a branch;
    • c6cea2a: design.md numbers the T020 ruling 15, and says the 3.9 leg compiles with compile().
  • Round 2 (9682f0b, 4 commits on round 1, tests only):
    • 2a5d56c: both upload jobs' index checks are run against a fake index, holding the empty-index ruling and the served check's 20 reads;
    • 7b1c693: the install check's --version step and its Python 3.9 step are run;
    • bc454ad: the macOS rerun is tied to the offline --install, naming its ten differences;
    • 9682f0b: the header's approval step and branch cut are pinned, and both copies of the guard's table are tied to GUARD_ROWS.

The notes and the code leg, named before they exist. PR 4 follows this PR directly, and the migration's cutover follows all four. So five places describe them in the present tense:

• .github/workflows/release.yml:108-112: RELEASING step 5 runs gh release create … --notes-file <spec>/docs/release-notes/v<version>.md. PR 4 adds docs/release-notes/v1.0.0.md and v1.1.0.md, and <spec> is the spec leg that the cutover makes. tests/test_release_workflow.py:3163 (at 9682f0b) holds that line of the header.
• .github/workflows/release.yml:142-144: v1.1.0 "is built later, from another commit, in opensoft/openRepoTools-code".
• .github/workflows/release.yml:171-174: "FROM v1.1.0 ON, release tags are made in opensoft/openRepoTools-code".
• .github/workflows/release.yml:189-191: the ref step fetches the tag from opensoft/openRepoTools-code with no credentials, and the migration creates that repository.
• .github/workflows/release.yml:222-228: after the cutover the workflow runs in the code leg, which holds none of docs/, openspec/, specs/, README.md, AGENTS.md and CLAUDE.md. test_release_reads_nothing_the_code_leg_will_not_hold holds that no step names one.

Runs

• Queue prefix q3d (ba4a3df, branch lane3-queue/q3d-228pr3-on-q2g: q2g 43ec2fe + this head 9682f0b, on main 00d52ae, tree de5db63): tests.yml run 39302680250, pending. This is the run of record for the landing.
• Lane 3's verify at 9682f0b: the selection -k "test_release_ or test_tests_yml_ or repo_hygiene" gives 646 passed, and actionlint is clean (Releases: annotated tags, release/vX.Y branches, and openrepotools on TestPyPI and PyPI from v1.1.0 #228 6273049912).

Review. An independent review by lane openRepoTools-2, from two reviewers (tests and mutants, and reading and probes), of 85a7b05..29cc1b3, gave LAND after fixes (#228 6273189381). At 1b41ce7 the merge of PR 2's review fixes leaves release.yml and the test file byte-identical to 29cc1b3, so that range is this PR's own.

• No finding shows release.yml doing a wrong thing today. Every finding but one false comment and some NITs is about what the tests fail to hold.
• The MUST, M1: the sha256 checks in front of each upload and in front of the install could be deleted with the suite green. Four mutants showed it (X4, X7, I10 and I19), and each left the suite at 312 passed and 0 failed. Round 1's 34f4239 holds the checks by their steps' names and exact commands, and runs the install check's. It should kill I10 as well, which the re-check confirms.
• Rounds 1 and 2 kill the survivors that lane 2's verdict maps to R1 and R2. Of its 56 surviving mutants, 16 are R1, 10 are R2, 4 are "R1, confirm" (I10, I3, I17 and I18), 25 are NEW, and 1 is right to pass. Lane 3's fix-branch notice is Releases: annotated tags, release/vX.Y branches, and openrepotools on TestPyPI and PyPI from v1.1.0 #228 6273049912.
• Lane 2's re-check of 1b41ce7..9682f0b is pending, and PR 3 lands only after it. Lane 2's three conditions for landing are: M1 fixed, that re-check, and Linux CI green.
• The NEW findings go to PR 3b, a tests-and-docs follow-up on 9682f0b, per lane 3's ruling (Releases: annotated tags, release/vX.Y branches, and openrepotools on TestPyPI and PyPI from v1.1.0 #228 6273289912). Nothing more goes into PR 3 before the re-check. The re-check says which of the NEW survivors rounds 1 and 2 already kill, and whatever survives goes to PR 3b, not to this PR.
• Six items go to v1.2.0 proposals, each a change in behaviour or in CI: lint in CI, the two wheel checks' mode handling, the CRC traceback, the index checks' tracebacks, placement under bash 3.2, and the settings release.yml:194-199 names.
• What the reviewers ran, at 29cc1b3 unless named:
  • actionlint 1.7.12 on release.yml and tests.yml, at 29cc1b3 and at 1b41ce7: clean;
  • -k test_release_workflow: 312 passed, at both commits, and again offline (dead proxies and GIT_ALLOW_PROTOCOL=file), where decoys for gh, curl, wget, pip and git's network commands logged nothing;
  • 104 mutants of release.yml, 48 killed and 56 survived;
  • the repository guard's table, 931 rows (7 repositories, 19 versions and 7 refs), under bash 5.2 and 3.2.57: 0 unexpected, the two tables identical, and only the code leg, on a final at the tag v$VERSION, reaches PyPI;
  • the stamp writer, 29 of 29; the CI gate, 16 of 16; the wheel check on lane 3's 20 defective wheels, each named with exit 1 except the symlink and CRC NITs;
  • the empty-index and served-digest checks, probed in both upload jobs: the scripts are right today;
  • the lead's empty-index ruling (ac2ca2b) matches its docs, apart from the item number round 1 fixed.
• What could not be checked: what only GitHub runs (OIDC trusted publishing, the environments' protection and approval wait, the real API shapes, artifacts across re-run attempts, the publish action's container, the index's lag); what only macOS runs (Apple's own /bin/bash 3.2, BSD tools, pipx on the three legs); a real hatchling wheel; Python 3.9 itself; and a syscall-level offline proof.

Notes for other work

• PR 3b (tests, comments and docs only, on 9682f0b) follows PR 3. Lane 3 lands it after PR 3 by cherry-picking it onto main, and lane 2 re-checks it with the same mutant set (Releases: annotated tags, release/vX.Y branches, and openrepotools on TestPyPI and PyPI from v1.1.0 #228 6273289912).
• PR 4 (the release notes and README) follows from main.
• The migration's single rehearsal waits for all four PRs (D1, Triad migration (feature 004-migrate-to-triad): execution tracking under Brett Heap's word of 2026-10-07 #186).
• The 1.1.0rc1 rehearsal to TestPyPI is a later step, on Brett Heap's word.

Landing: Brett Heap's decision 4 on #228 ("Yes, merge when green (Recommended)"), and his word of 2026-10-18T20:3xZ, "use this as approval to merge when green for all merges thru v1.1.0".

• Lane openRepoTools-3 lands the queue in one order: openRepoTools becomes the openrepotools package: pipx installs the wheel with the whole payload, --install leaves pipx's link to pipx, --version names the release, and every count line says where the other commands come from (#228, PR 1 of 4) #262, PR 2, PR 3, PR 4, T025's docs PR, then The handoff's tree inventory names a record it could not read whatever its schema, and a leg directory it cannot search is never read as absent (#246 follow-up, before the cutover) #255.
• This PR squash-merges after an independent review, once Linux CI is green on the exact tree main will have after its squash. The record is a queue run of tests.yml on lane 3's prefix branch, under Runs.
• PR 3 lands only after lane 2's re-check of 1b41ce7..9682f0b. q3d is q2g plus this head, so PR 2's package job runs on it.
• When its turn comes, lane 3 pushes a head that merges main into 9682f0b with q3d's tree, as a fast-forward, so the tree under review is the tree that was tested.

Lane: openRepoTools-3

🤖 Generated with Claude Code

[sourcery-ai]

Sorry @brettheap, your pull request is larger than the review limit of 150,000 diff characters

[sonarqubecloud]

Quality Gate passed

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