Scope PYTHON_GIL=0 off the PyPI publish job.

Keep free-threaded GIL=0 on gate/build only, never workflow-wide or on
pypa/gh-action-pypi-publish, matching the shared Trusted Publishing rule.

Author: lbliii

.github/workflows/python-publish.yml

@@ -1,10 +1,20 @@
-# This workflow will upload a Python Package to PyPI when a release is created
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
-
-# This workflow uses actions that are not certified by GitHub.
-# They are provided by a third-party and are governed by
-# separate terms of service, privacy policy, and support
-# documentation.
+# Upload to PyPI when a GitHub release is published.
+#
+# Authentication: PyPI Trusted Publishing (OIDC). No API token in this repo.
+#
+# Free-threaded rule (shared across chirp / kida / furatena / pounce / milo-cli):
+#   - Set PYTHON_GIL=0 only on jobs that run this repo's 3.14t code
+#     (release-gate / release-build).
+#   - Never set PYTHON_GIL at workflow scope, and never on pypi-publish —
+#     pypa/gh-action-pypi-publish uses a non-free-threaded interpreter and
+#     aborts if PYTHON_GIL=0 is inherited.
+#
+# Trusted Publishing registration:
+#   PyPI project name: kida-templates
+#   Owner:             lbliii
+#   Repository:        kida
+#   Workflow name:     python-publish.yml
+#   Environment name:  pypi
 
 name: Upload Python Package
 
@@ -18,6 +28,8 @@ permissions:
 jobs:
   release-gate:
     runs-on: ubuntu-latest
+    env:
+      PYTHON_GIL: "0"
     steps:
       - uses: actions/checkout@v7
 
@@ -40,7 +52,6 @@ jobs:
         env:
           CI: true
           BENCHMARK_SUITE: core
-          PYTHON_GIL: "0"
         run: |
           uv run pytest -n 0 -q --tb=short \
             tests/test_kida_expressions.py \
@@ -52,7 +63,8 @@ jobs:
     runs-on: ubuntu-latest
     needs:
       - release-gate
-
+    env:
+      PYTHON_GIL: "0"
     steps:
       - uses: actions/checkout@v7
 

changelog.d/+pypi-gil-scoping.changed.md

@@ -0,0 +1,2 @@
+PyPI Trusted Publishing keeps ``PYTHON_GIL=0`` on free-threaded gate/build
+jobs only, never on the ``pypa/gh-action-pypi-publish`` upload job.

tests/templates/test_github_report_contracts.py

@@ -175,6 +175,20 @@ def test_release_workflow_keeps_exact_free_threaded_python_setup():
     assert "allow-prereleases: true" in setup_python_step
 
 
+def test_pypi_publish_does_not_inherit_python_gil():
+    """pypa upload container is not free-threaded; GIL=0 belongs on our jobs only."""
+    workflow = (WORKFLOWS_DIR / "python-publish.yml").read_text(encoding="utf-8")
+
+    assert "\nenv:\n  PYTHON_GIL:" not in workflow
+    assert "Never set PYTHON_GIL at workflow scope" in workflow
+    gate_env = workflow.split("release-gate:", 1)[1].split("steps:", 1)[0]
+    build_env = workflow.split("release-build:", 1)[1].split("steps:", 1)[0]
+    publish_job = workflow.split("pypi-publish:", 1)[1]
+    assert 'PYTHON_GIL: "0"' in gate_env
+    assert 'PYTHON_GIL: "0"' in build_env
+    assert "PYTHON_GIL" not in publish_job
+
+
 def test_local_ruff_targets_use_the_same_repository_scope_as_ci():
     """Local lint, fix, format, and format-check targets cover the whole repo."""
     makefile = (ROOT_DIR / "Makefile").read_text(encoding="utf-8")