docs: record pypi publish fallback

Author: AbdelStark

.github/workflows/release-pypi.yml

@@ -5,8 +5,10 @@
 #     publishes to PyPI and creates a GitHub release.
 #   - manual dispatch publishes the same locked artifacts to TestPyPI only.
 #
-# Uses PyPI Trusted Publishing (OIDC); no API tokens are stored in repository
-# secrets. The PyPI trusted-publisher claim is bound to this workflow path.
+# Intended to use PyPI Trusted Publishing (OIDC). If the PyPI
+# account-side trusted-publisher mapping is missing, maintainers may
+# publish the validated dist/ files with a scoped token and must record
+# that fallback in the release tracker and notes.
 name: Release PyPI
 
 on:

CHANGELOG.md

@@ -16,7 +16,7 @@ No unreleased changes.
 
 ### Release Summary
 
-- First Python package release target for GenoLeWM's alpha public surface.
+- First Python package release for GenoLeWM's alpha public surface.
 - Publishes the v0.2.1 serious-completion artifact chain: stronger
   post-v0.2 checkpoint lineage, broader benchmark-suite evidence,
   released-artifact planning demo, and generated paper package.
@@ -252,11 +252,15 @@ No unreleased changes.
     plumbing evidence only, not a Carbon-backed model result.
 
 - **PyPI release workflow hardening** (issue #100).
-  - `.github/workflows/release-pypi.yml` is now the trusted-publisher
-    workflow path for tagged releases.
-  - Release artifacts build from the committed `uv.lock`, publish to
-    PyPI via OIDC trusted publishing, and emit GitHub/Sigstore build
-    provenance with `SHA256SUMS` attached to the GitHub release.
+  - `.github/workflows/release-pypi.yml` is the intended
+    trusted-publisher workflow path for tagged releases.
+  - Release artifacts build from the committed `uv.lock`, run the
+    package and source-distribution gates, emit GitHub/Sigstore build
+    provenance, and attach `SHA256SUMS` to the GitHub release.
+  - The `0.2.1` upload exposed an account-side PyPI trusted-publisher
+    configuration gap (`invalid-publisher`), so the validated
+    distributions were published with the maintainer token available to
+    the release runner and the fallback was recorded in #201.
 
 - **Receipt-verification tutorial notebook** (issue #99).
   - `examples/07_verify_receipt.ipynb` verifies a committed
@@ -499,8 +503,9 @@ No unreleased changes.
 
 ### Security
 
-- PyPI Trusted Publishing (OIDC) on the release workflow — no
-  long-lived API tokens are stored in repository secrets.
+- PyPI release workflow configured for Trusted Publishing (OIDC);
+  `0.2.1` was published through a maintainer-token fallback after PyPI
+  rejected the trusted-publisher claim.
 - CodeQL Python analysis on every PR + weekly schedule.
 
 ## [0.1.0-draft] — 2026-05-20

docs/release/signing-keys.md

@@ -6,27 +6,33 @@ themselves are published here when they're issued.
 
 ## Status
 
-No signed binaries exist yet. The first package-release target is
-`0.2.1`, published through the protected PyPI workflow. This page exists
-so [`SECURITY`](../security.md) can reference a stable URL.
+No signed binaries exist yet. The first package release is `0.2.1`.
+The tag workflow built and validated the release distributions, but PyPI
+rejected the trusted-publisher exchange with `invalid-publisher`; the
+same validated distributions were then published with a maintainer token
+and recorded in the release tracker. This page exists so
+[`SECURITY`](../security.md) can reference a stable URL.
 
 ## Planned posture
 
 - Maintainer key fingerprints listed here, one per row, with
   `[Maintainer name] — [PGP fingerprint] — [valid from] — [revoked at]`.
 - Release artifacts on PyPI published via PyPI trusted publishing
-  (OIDC, no long-lived API tokens).
+  (OIDC) once the account-side publisher mapping is configured; until
+  then, any maintainer-token fallback must be recorded in the release
+  tracker and public release notes.
 - Release artifacts on GitHub attached to a signed tag and
   Sigstore-backed build provenance.
 - Hugging Face Hub model weights signed via the `safetensors`
   manifest; the manifest hash is the trust anchor (RFC-0011 §3.7).
 
 ## Until then
 
-- PyPI project releases are published from the `Release PyPI` workflow
+- PyPI project releases should publish from the `Release PyPI` workflow
   at `.github/workflows/release-pypi.yml` through trusted publishing.
   Verify the workflow's OIDC claim against the trusted-publisher
-  configuration before each protected tag.
+  configuration before each protected tag; if PyPI rejects the claim,
+  use only a scoped maintainer-token fallback and record the exception.
 - The repository's tags are GPG-signed by the project lead. Verify
   with `git tag -v vX.Y.Z` after importing the lead's GPG key.
 - Release assets should also verify with the GitHub CLI

docs/spec/09-release-and-versioning.md

@@ -151,10 +151,12 @@ trusted only after their hashes match the fetched manifest.
 6. Open a release PR. Require sign-off from a non-author maintainer.
 7. Merge to `main`. Tag `v<X>.<Y>.<Z>`.
 8. CI builds the PyPI artifacts from `uv.lock`, publishes them through
-   `.github/workflows/release-pypi.yml` via trusted publishing, and
-   emits GitHub/Sigstore build provenance. The source distribution must
-   include the release-critical repo assets used by documented release
-   gates: `bench/`, `configs/first_experiment/`, `tools/`, `docs/`,
+   `.github/workflows/release-pypi.yml` via trusted publishing when the
+   PyPI account-side publisher mapping is configured, and emits
+   GitHub/Sigstore build provenance. If PyPI rejects the trusted
+   publisher claim, a scoped maintainer-token fallback is allowed only
+   when it is recorded in the release tracker and public notes. The source distribution must include the release-critical repo assets
+   used by documented release gates: `bench/`, `configs/first_experiment/`, `tools/`, `docs/`,
    `rfcs/`, `examples/`, README, ROADMAP, and AGENTS.
 9. Publish CHANGELOG to the release notes.
 10. For paper/demo releases: validate the checked first-experiment
@@ -607,7 +609,7 @@ Revocation-list mechanism is an [open question](#open-questions).
 
 | Channel | Status | Use |
 |---------|--------|-----|
-| PyPI | 0.2.1 release target | package wheels and sdists through trusted publishing |
+| PyPI | 0.2.1 published | package wheels and sdists through trusted publishing or recorded maintainer-token fallback |
 | HuggingFace Hub | v0.1 published | model checkpoints and dataset artifacts |
 | GitHub releases | v0.1 published | terminal-demo, paper, and publication-evidence assets |
 | Homebrew | Planned | post v1 |

tests/lint/test_docs_release_blocker_contract.py

@@ -405,7 +405,7 @@ def test_public_docs_do_not_claim_unreleased_package_distribution() -> None:
     else:
         assert "python -m pip install geno-lewm" in normalized
         assert "first PyPI release has not been cut yet" not in normalized
-        assert "0.2.1 release target" in RELEASE_SPEC.read_text(encoding="utf-8")
+        assert "0.2.1 published" in RELEASE_SPEC.read_text(encoding="utf-8")
 
 
 def test_faq_keeps_target_numbers_behind_release_evidence() -> None: