ci: a release gate that catches what shipped wrong by hand

Publishing these packages was manual and ungated. The 2026-08-25 release -- the
first in two days -- tripped three separate defects, all found by reading rather
than by any check:

  * kirby-combat published with NO runtime dependency declared while its code
    imported kirby_cost
  * kirby-combat and kirby-sheet both declared `kirby-cost>=0.3.0` while using
    modules and attributes absent from 0.3.0; pip resolves that constraint
    happily and installs a package that breaks on use
  * kirby-sheet 0.2.0 shipped with __version__ reporting "0.1.0"

scripts/check_release.py is those checks, runnable locally and from CI. Each
one is written against a failure that actually happened, and the script was
itself found unable to fail twice before it worked: first it only imported the
top-level package (so a missing submodule slipped through), then it turned out
Python puts cwd on sys.path, so running it from the repo validated the working
tree instead of the built wheel and reported the local version. It now probes
with -P from a temp directory.

Stated limit, in the script: attribute-level drift is NOT caught. A floor that
is too low because the code needs a FIELD added in a later version still
imports clean. A green run means "the modules resolve", not "the floor is
right".

release.yml uses PyPI Trusted Publishing, so no token lives in the repo -- the
reason the previous publish job was deleted from these workflows.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Xof4ZUS5n6A5ibX3PXNYbs

Author: site-shell

.github/workflows/release.yml

@@ -0,0 +1,69 @@
+name: Release
+
+# Publishes to PyPI when a version tag is pushed, and NOT otherwise.
+#
+# No credentials live here. The publish job uses PyPI Trusted Publishing
+# (OIDC), so there is no API token in a secret to leak or rotate -- which is
+# why the old publish job was deleted from this repo in the first place. See
+# the note at the top of tests.yml.
+#
+# The guards in `scripts/check_release.py` run BEFORE the upload, and each one
+# exists because the failure it catches actually shipped:
+#   * licensed Hero Games content in the artifact
+#   * a dependency floor lower than the version the code needs
+#   * the module's __version__ disagreeing with its own metadata
+#   * a tag that does not match the built version
+# On 2026-08-25 the first release in two days tripped three of the four, all
+# found by hand. This is that check, automated.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install the package and its test deps
+        run: pip install -e .[dev]
+
+      - name: Run the test suite
+        # Real-character tests skip here by design: they read a corpus path
+        # that CI does not have. See tests/corpus.py.
+        run: pytest -q --tb=short
+
+      - name: Build the distribution
+        run: |
+          python -m pip install --upgrade build
+          rm -rf dist build *.egg-info
+          python -m build
+
+      - name: Release guards
+        # Runs from the repo root, which is exactly the case the guard had to
+        # be hardened against -- cwd on sys.path made an earlier version
+        # validate the working tree instead of the built wheel.
+        run: python scripts/check_release.py dist/
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # Trusted Publishing; no token secret required
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/tests.yml

@@ -0,0 +1,36 @@
+name: Tests
+
+# kirby-sheet had no CI at all until 2026-08-25. The gap mattered: its
+# byte-fidelity tests -- the ones that export a character through real Hero
+# Designer and compare the output byte for byte -- SKIP unless
+# KIRBY_SHEET_ORACLE, KIRBY_SHEET_HDC and KIRBY_SHEET_HDE are set. A local run
+# without them reports "196 passed, 33 skipped" and looks green while the
+# package's central claim goes unverified.
+#
+# Those 33 cannot run here and never will: they need a licensed Hero Designer
+# installation, which this repository deliberately does not ship. So this
+# workflow gates what a reader can actually run, and the release workflow says
+# plainly that the oracle gate is a local, pre-release step.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install package + dev deps
+        run: pip install -e .[dev]
+      - name: Run tests
+        run: pytest -q --tb=short
+      - name: Report what skipped, so a silent skip is visible in the log
+        if: always()
+        run: pytest -q -rs --tb=no | tail -40

scripts/check_release.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+"""Guards a release artifact against the four ways a kirby package has shipped wrong.
+
+Run it on `dist/` before uploading, locally or in CI:
+
+    python scripts/check_release.py dist/
+
+Each check exists because the failure it catches actually happened, and each
+one shipped or nearly shipped a package that pip installs happily and that
+breaks, or lies, on use. Exit code 1 on any failure; nothing here is advisory.
+
+1. LICENSED CONTENT. These packages ship no Hero Games data -- no `.hdt`, no
+   `.hdc`, no `.hde`. That is a licensing boundary, not a preference, and the
+   only place it can be enforced is the built artifact: a stray fixture path
+   in MANIFEST.in or package_data would carry one in silently.
+
+2. DEPENDENCY FLOORS THAT DO NOT EXIST. On 2026-08-25 both kirby-combat and
+   kirby-sheet declared `kirby-cost>=0.3.0` while importing modules that 0.3.0
+   does not contain. pip resolves that constraint to 0.3.0 without complaint
+   and hands the user a package that dies at import. So: install the built
+   wheel into a clean venv with no local packages visible, and import EVERY
+   submodule.
+
+   WHAT THIS DOES NOT CATCH, stated plainly: drift at the ATTRIBUTE level. If
+   a floor is too low because the code needs `TemplateData.defense` — a field
+   added in a later version — every module still imports and this check passes.
+   Only running the package's own suite against the installed distribution
+   would catch that, and the suite needs a Hero Designer template that CI does
+   not have. Treat a green run here as "the modules resolve", not "the floor
+   is right".
+
+3. VERSION DISAGREEMENT. kirby-sheet 0.2.0 shipped with
+   `kirby_sheet.__version__ == "0.1.0"` while its metadata said 0.2.0 --
+   pip reporting one number and the code another. kirby-combat had the same
+   drift at 0.3.28. Three instances make it a pattern.
+
+4. TAG/VERSION MISMATCH (CI only). A tag that disagrees with pyproject means
+   the published version and the git history point at different code.
+"""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tarfile
+import tempfile
+import venv
+import zipfile
+from pathlib import Path
+
+LICENSED_SUFFIXES = (".hdt", ".hdc", ".hde")
+
+
+def fail(msg: str) -> None:
+    print(f"FAIL  {msg}")
+
+
+def ok(msg: str) -> None:
+    print(f"ok    {msg}")
+
+
+def artifact_names(path: Path) -> list[str]:
+    if path.suffix == ".whl":
+        return zipfile.ZipFile(path).namelist()
+    return tarfile.open(path).getnames()
+
+
+def check_licensed(dist: Path) -> bool:
+    clean = True
+    for art in sorted(dist.iterdir()):
+        if art.suffix not in (".whl", ".gz"):
+            continue
+        bad = [n for n in artifact_names(art) if n.lower().endswith(LICENSED_SUFFIXES)]
+        if bad:
+            fail(f"{art.name} carries licensed content: {bad[:5]}")
+            clean = False
+        else:
+            ok(f"{art.name}: no .hdt/.hdc/.hde")
+    return clean
+
+
+def wheel_metadata(wheel: Path) -> dict[str, list[str]]:
+    z = zipfile.ZipFile(wheel)
+    name = next(n for n in z.namelist() if n.endswith(".dist-info/METADATA"))
+    meta: dict[str, list[str]] = {}
+    for line in z.read(name).decode().splitlines():
+        if not line or line[0].isspace():
+            continue
+        if ": " in line:
+            k, v = line.split(": ", 1)
+            meta.setdefault(k, []).append(v)
+    return meta
+
+
+def check_install_and_version(wheel: Path) -> bool:
+    """Install into a clean venv and confirm it imports and agrees about its version.
+
+    The venv is built WITHOUT system site packages and installed with
+    --no-cache-dir, so a dependency that only resolves because it happens to
+    be on this machine cannot mask a floor that is too low.
+    """
+    meta = wheel_metadata(wheel)
+    dist_name = meta["Name"][0]
+    version = meta["Version"][0]
+    module = dist_name.replace("-", "_")
+
+    with tempfile.TemporaryDirectory() as tmp:
+        env_dir = Path(tmp) / "v"
+        venv.create(env_dir, with_pip=True, system_site_packages=False)
+        py = env_dir / "bin" / "python"
+        proc = subprocess.run(
+            [str(py), "-m", "pip", "install", "-q", "--no-cache-dir", str(wheel)],
+            capture_output=True, text=True, cwd=tmp,
+        )
+        if proc.returncode != 0:
+            fail(f"{dist_name} {version} does not install cleanly:\n{proc.stderr[-600:]}")
+            return False
+
+        # EVERY submodule, not just the top-level package.
+        #
+        # A bare `import kirby_sheet` was the first version of this check and
+        # it was worthless: it passed a wheel pinned to a kirby-cost that did
+        # not contain the modules the package imports, because nothing at top
+        # level reached them. Walking the package forces every module-level
+        # `from kirby_cost.engine.damage import ...` to actually resolve,
+        # which is how a floor that is too low announces itself.
+        probe = (
+            "import json,importlib,pkgutil;"
+            f"m=importlib.import_module({module!r});"
+            "bad=[];"
+            "\n"
+            "for _mi in pkgutil.walk_packages(m.__path__, m.__name__ + '.'):\n"
+            "    try:\n"
+            "        importlib.import_module(_mi.name)\n"
+            "    except Exception as e:\n"
+            "        bad.append(f'{_mi.name}: {type(e).__name__}: {e}')\n"
+            "from importlib.metadata import version as v\n"
+            f"print(json.dumps({{'module':getattr(m,'__version__',None),'meta':v({dist_name!r}),'bad':bad}}))"
+        )
+        # Deliberately clear the template variable: a package must import with
+        # no Hero Designer installation configured.
+        env = {k: val for k, val in os.environ.items() if k != "KIRBY_COST_HDT"}
+        # cwd=tmp and -P are both load-bearing, and this check was WORTHLESS
+        # without them. Python puts the current directory on sys.path, so
+        # running this from a package's own repo -- the normal way -- imported
+        # the local source tree instead of the installed wheel. Measured
+        # 2026-08-25: a wheel pinned to kirby-cost==0.3.0 passed, because the
+        # probe was resolving kirby_cost from
+        # /home/.../kirby-cost/kirby_cost and reporting version 0.4.0. The
+        # guard was validating the working tree and calling it an artifact.
+        # -P (3.11+) drops cwd from sys.path; cwd=tmp puts it somewhere with
+        # nothing importable in it. Belt and braces, deliberately.
+        proc = subprocess.run(
+            [str(py), "-P", "-c", probe],
+            capture_output=True, text=True, env=env, cwd=tmp,
+        )
+        if proc.returncode != 0:
+            fail(f"{dist_name} {version} installs but does not import:\n{proc.stderr[-800:]}")
+            return False
+
+        got = json.loads(proc.stdout.strip().splitlines()[-1])
+        if got["bad"]:
+            fail(
+                f"{dist_name} {version} installs but {len(got['bad'])} submodule(s) "
+                f"do not import -- usually a dependency floor lower than what the "
+                f"code actually needs:"
+            )
+            for line in got["bad"][:6]:
+                print(f"        {line}")
+            return False
+        ok(f"{dist_name} {version}: every submodule imports, with no template configured")
+        if got["module"] is None:
+            fail(f"{module}.__version__ is not defined")
+            return False
+        if got["module"] != got["meta"]:
+            fail(
+                f"{module}.__version__ is {got['module']!r} but the distribution "
+                f"says {got['meta']!r} -- pip and the code would report different numbers"
+            )
+            return False
+        ok(f"{module}.__version__ agrees with the distribution metadata ({got['meta']})")
+    return True
+
+
+def check_tag(wheel: Path) -> bool:
+    """Only meaningful in CI, where the tag is what triggered the release."""
+    ref = os.environ.get("GITHUB_REF_NAME")
+    if not ref:
+        return True
+    version = wheel_metadata(wheel)["Version"][0]
+    if ref.lstrip("v") != version:
+        fail(f"tag {ref!r} does not match the built version {version!r}")
+        return False
+    ok(f"tag {ref} matches the built version")
+    return True
+
+
+def main() -> int:
+    dist = Path(sys.argv[1] if len(sys.argv) > 1 else "dist")
+    if not dist.is_dir():
+        fail(f"{dist} is not a directory")
+        return 1
+    wheels = sorted(dist.glob("*.whl"))
+    if len(wheels) != 1:
+        fail(f"expected exactly one wheel in {dist}, found {len(wheels)}")
+        return 1
+
+    results = [
+        check_licensed(dist),
+        check_install_and_version(wheels[0]),
+        check_tag(wheels[0]),
+    ]
+    if all(results):
+        print("\nall release guards passed")
+        return 0
+    print("\nrelease guards FAILED -- do not upload")
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())