@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/python-app-distribution/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: python-app-distribution
+description: Ships a Python application to people who do not have Python, by freezing it with PyInstaller or compiling it with Nuitka per target OS, wrapping Windows builds in an Inno Setup or MSIX installer with Authenticode signing, signing macOS app bundles with a Developer ID under the hardened runtime and notarizing them with notarytool, and publishing wheels and an sdist to PyPI through GitHub trusted publishing. Use when turning a Python script, CLI or Qt/Tk GUI into a downloadable .exe, .app or .dmg, an installer, or a pip-installable release, or when a frozen build misses data files, gets flagged by SmartScreen or Gatekeeper, or a PyPI upload needs to drop API tokens.
+license: MIT
+compatibility: Any Agent Skills host. Builds must run on each target OS (no cross-compiling); macOS signing needs Xcode command line tools and an Apple Developer account, Windows signing needs a code-signing certificate or signing service.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "python"
+  kete-loom/owner: "Kete-org"
+---
+
+# Python app distribution
+
+Ship a build the user can double-click or `pip install` without warnings, missing files or a second Python install, built the same way every time in CI.
+
+Project layout, `pyproject.toml` tooling and code style belong to `python-patterns`. Version numbers and changelogs belong to `release-management`. This skill covers turning a working app into artifacts and getting them signed and published.
+
+## 0. Decide the channel
+
+Ask, or infer from the project:
+
+| Users | Ship |
+|---|---|
+| Developers who have Python | Wheel + sdist on PyPI (`pip install`, `pipx install`, `uv tool install`) |
+| End users on Windows | Frozen app inside an installer (Inno Setup `.exe`, or MSIX) |
+| End users on macOS | Signed, notarized `.app`, usually inside a `.dmg` |
+| End users on Linux | Frozen folder in a tarball, or AppImage/Flatpak (check the project's preference) |
+
+If both developers and end users are targets, do both. If signing credentials do not exist yet, **stop and ask**: who owns the Apple Developer account and the Windows certificate, and where CI may read them.
+
+## 1. Make the app freezable
+
+1. One entry point (`src/app/__main__.py` or a `[project.scripts]` function).
+2. Read bundled data through `importlib.resources`, or through a helper that checks `getattr(sys, "frozen", False)` and `sys._MEIPASS` for PyInstaller. Never rely on the current working directory.
+3. Write user data to the platform's user directory (`platformdirs`), never next to the executable; `Program Files` and signed `.app` bundles are read-only.
+4. Pin dependencies with a lockfile so builds are repeatable.
+
+## 2. Freeze
+
+### PyInstaller
+
+1. `pyinstaller --name MyApp --windowed --onedir src/app/__main__.py` once, then commit the generated `MyApp.spec` and build from it: `pyinstaller MyApp.spec --clean --noconfirm`.
+2. Declare data files and hidden imports in the spec (`datas`, `hiddenimports`), not by copying files after the build.
+3. Prefer `--onedir` for GUI apps inside an installer or `.app`: faster start, fewer antivirus false positives. Use `--onefile` only for a single-file CLI download.
+4. Build on each OS and architecture you ship (Windows x64, macOS arm64 and x86_64 or universal2, Linux on the oldest glibc you support). PyInstaller does not cross-compile.
+
+### Nuitka
+
+`python -m nuitka --mode=standalone --include-data-dir=src/app/assets=assets src/app/__main__.py` (or `--mode=onefile`, `--mode=app` on macOS). Test standalone first; data-file problems are easier to see there. Expect longer builds and a C compiler requirement; Nuitka's benefit is speed and harder-to-unpack code, not secrecy.
+
+### Smoke test the frozen build
+
+Run the built executable on a clean machine or VM without Python, exercise the main path, and check its log for `ModuleNotFoundError` or missing files.
+
+## 3. Windows: installer and signing
+
+1. Installer: Inno Setup script (`installer.iss`) compiled with `iscc installer.iss`, or MSIX packaged with `makeappx pack` (MSIX gives clean uninstall and Store distribution; it needs a manifest and signing with a matching publisher). Details in `references/windows-macos-signing.md`.
+2. Sign the app executable first, then the installer: `signtool sign /fd SHA256 /tr <timestamp URL> /td SHA256 ...`. Always timestamp so signatures outlive the certificate.
+3. Code-signing keys now live in hardware or a cloud signing service (for example Azure Artifact Signing, formerly Trusted Signing, or a CA's cloud HSM); plan CI around that, not around a `.pfx` in a secret.
+4. A new certificate still builds SmartScreen reputation gradually; tell the user to expect warnings on the first downloads.
+
+## 4. macOS: sign, notarize, staple
+
+1. Sign every binary inside the bundle, inside out, with the hardened runtime and a secure timestamp: `codesign --force --options runtime --timestamp --entitlements entitlements.plist --sign "Developer ID Application: <Team> (<TEAMID>)" MyApp.app` (nested `.dylib`/`.so` files first, or use the PyInstaller `--codesign-identity` option and re-check).
+2. Verify: `codesign --verify --deep --strict --verbose=2 MyApp.app`.
+3. Package (`.dmg` via `hdiutil create`, or a `.zip`), sign the `.dmg`, then notarize: `xcrun notarytool submit MyApp.dmg --keychain-profile <profile> --wait`.
+4. On failure read the log: `xcrun notarytool log <submission-id> --keychain-profile <profile>`.
+5. Staple: `xcrun stapler staple MyApp.dmg`, then check with `spctl --assess --type open --context context:primary-signature -v MyApp.dmg`.
+
+Entitlements, CI keychain setup and common notarization errors are in `references/windows-macos-signing.md`.
+
+## 5. PyPI: wheels, sdist, trusted publishing
+
+1. Build backend declared in `pyproject.toml` (`hatchling`, `setuptools`, `flit-core`, `uv_build`, or `maturin`/`scikit-build-core` for compiled extensions).
+2. Build: `python -m build` (or `uv build`), then `twine check dist/*`. Install the wheel into a fresh virtual environment and run the CLI once.
+3. Compiled extensions: build platform wheels with `cibuildwheel` in CI; pure Python ships one `py3-none-any` wheel.
+4. Publish from CI with trusted publishing, no API token: register the publisher on PyPI (project settings, or a pending publisher for a new project) naming the repository, workflow file and environment; the workflow then needs `permissions: id-token: write` and `pypa/gh-action-pypi-publish@release/v1`. Template in `references/pypi-trusted-publishing.md`.
+5. Rehearse on TestPyPI first. A version number can never be re-uploaded, even after deleting it.
+
+## 6. CI
+
+One workflow, triggered by a version tag: a build matrix per OS that freezes, signs, smoke-tests and uploads artifacts; a publish job that needs the builds and runs in a protected environment with required reviewers. Secrets (Apple app-specific password or API key, signing credentials) live only in that environment.
+
+## Never
+
+- Never commit certificates, `.p12` files, passwords or PyPI tokens.
+- Never tell users to disable Gatekeeper, SmartScreen or antivirus as the fix.
+- Never ship an unsigned build labelled as a release when signing was expected; ask first.
+- Never publish to PyPI from a developer laptop when the project has a CI publisher.
+
+## Regulated or high-stakes distribution
+
+Export controls on cryptography, app-store rules and licence obligations of bundled libraries (GPL/LGPL Qt bindings, for example) are not covered here. Flag them and have the owner or legal review before a public release.
+
+## Report back
+
+```
+## Distribution: <app> <version>
+Channels: <PyPI | Windows installer | macOS dmg | Linux>
+Builds: <OS/arch -> artifact, size>
+Signing: Windows <signed+timestamped yes/no>, macOS <signed, notarized, stapled yes/no>
+PyPI: <TestPyPI ok, trusted publisher configured, published yes/no>
+Smoke tests: <clean-machine result per OS>
+Open items: <credentials, reputation, licences>
+```

package/skills/python-app-distribution/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Turn our PySide6 desktop tool into a signed Windows installer our customers can download",
+    "The PyInstaller build works on my machine but the exe can't find its icons and config file",
+    "macOS says our Python app is damaged and can't be opened; set up codesign and notarization",
+    "Publish our library to PyPI from GitHub Actions without storing an API token",
+    "Compile our Python CLI with Nuitka into a single binary for Linux and macOS"
+  ],
+  "should_not_trigger": [
+    "Set up ruff, mypy and a pyproject.toml for our new Python service",
+    "Decide the next semantic version and write release notes for this sprint's changes",
+    "Pin the Python interpreter version so every developer and CI use the same one",
+    "Write a Dockerfile that runs our Python API in production",
+    "Write pytest fixtures for the billing module"
+  ]
+}

package/skills/python-app-distribution/references/pypi-trusted-publishing.md

@@ -0,0 +1,55 @@
+# PyPI trusted publishing (GitHub Actions)
+
+Read this when wiring a release workflow. Trusted publishing exchanges a short-lived GitHub OIDC token for a PyPI upload token; nothing long-lived is stored.
+
+## On PyPI
+
+Project settings, Publishing, add a GitHub publisher with: owner, repository, workflow file name (for example `release.yml`) and environment name (for example `pypi`). For a project that does not exist yet, add a pending publisher from your account's Publishing page. Do the same on TestPyPI for rehearsals.
+
+## Workflow
+
+```yaml
+name: release
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build twine
+      - run: python -m build
+      - run: twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi          # must match the publisher on PyPI
+    permissions:
+      id-token: write          # required for trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+```
+
+For TestPyPI add `with: repository-url: https://test.pypi.org/legacy/` and a separate environment.
+
+Keep `id-token: write` on the publish job only, and protect the environment with required reviewers and a tag rule. Recent versions of the publish action also generate and upload attestations by default; leave that on.
+
+## Checks before the first real upload
+
+- `name` and `version` in `pyproject.toml` are right; the version matches the tag.
+- `readme`, `license` and `classifiers` render: `twine check` passes.
+- A fresh `pip install` of the TestPyPI release works (`--extra-index-url https://pypi.org/simple/` so dependencies resolve).

package/skills/python-app-distribution/references/windows-macos-signing.md

@@ -0,0 +1,70 @@
+# Windows installers and macOS signing
+
+Read this when writing the installer script, setting up signing in CI or debugging a notarization failure. Check Apple's and Microsoft's current documentation before relying on a specific certificate product; both change their signing offerings.
+
+## Inno Setup (minimal)
+
+```ini
+[Setup]
+AppId={{8C5E2F0A-REPLACE-WITH-YOUR-GUID}}
+AppName=MyApp
+AppVersion=1.4.0
+DefaultDirName={autopf}\MyApp
+DefaultGroupName=MyApp
+OutputBaseFilename=MyApp-1.4.0-setup
+Compression=lzma2
+SolidCompression=yes
+ArchitecturesAllowed=x64compatible
+ArchitecturesInstallIn64BitMode=x64compatible
+PrivilegesRequiredOverridesAllowed=dialog
+
+[Files]
+Source: "dist\MyApp\*"; DestDir: "{app}"; Flags: recursesubdirs ignoreversion
+
+[Icons]
+Name: "{group}\MyApp"; Filename: "{app}\MyApp.exe"
+
+[Run]
+Filename: "{app}\MyApp.exe"; Flags: nowait postinstall skipifsilent
+```
+
+Keep `AppId` fixed forever; upgrades find the old install by it. Compile with `iscc installer.iss`. Inno Setup can call the signer itself through a `SignTool=` entry so the uninstaller is signed too.
+
+## MSIX
+
+Needs an `AppxManifest.xml` whose `Publisher` matches the signing certificate subject exactly. Package with `makeappx pack /d <folder> /p MyApp.msix`, sign with `signtool sign /fd SHA256 ...`. MSIX apps run with a virtualized file system and registry; test file writes and per-user settings.
+
+## signtool
+
+```
+signtool sign /fd SHA256 /tr http://timestamp.example-ca.com /td SHA256 /a dist\MyApp\MyApp.exe
+signtool verify /pa /v dist\MyApp\MyApp.exe
+```
+
+Use the timestamp URL your CA or signing service documents. Cloud signing services ship their own signtool plug-in (dlib) and metadata file instead of `/a` or `/f`.
+
+## macOS entitlements for a frozen Python app
+
+Frozen Python apps often need these under the hardened runtime:
+
+```xml
+<key>com.apple.security.cs.allow-unsigned-executable-memory</key><true/>
+<key>com.apple.security.cs.disable-library-validation</key><true/>
+```
+
+Add only what the app needs; start without them and add one at a time if the signed app crashes at launch. Camera, microphone or Apple Events access also need usage strings in `Info.plist`.
+
+## macOS signing in CI
+
+1. Export the Developer ID Application certificate as `.p12`, store it base64-encoded with its password as CI secrets.
+2. In the job: create a temporary keychain (`security create-keychain`), import the `.p12` (`security import ... -T /usr/bin/codesign`), allow codesign access (`security set-key-partition-list -S apple-tool:,apple:`), sign, then delete the keychain.
+3. Notarize with an App Store Connect API key (`xcrun notarytool submit --key <p8> --key-id <id> --issuer <uuid>`) or an app-specific password stored with `xcrun notarytool store-credentials`.
+
+## Common notarization failures
+
+| Message | Fix |
+|---|---|
+| The binary is not signed with a valid Developer ID certificate | A nested `.so`/`.dylib` was skipped; sign every Mach-O file |
+| The signature does not include a secure timestamp | Add `--timestamp` |
+| The executable does not have the hardened runtime enabled | Add `--options runtime` |
+| Signed app fails after editing | Any change after signing breaks it; sign last, then package |

package/skills/python-patterns/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: python-patterns
+description: Idiomatic modern Python 3 for writing and restructuring application code, covering type hints, dataclasses versus pydantic at trust boundaries, exception design, context managers, pyproject.toml packaging with uv, poetry or pip, ruff and mypy/pyright setup, and asyncio pitfalls. Use when writing new Python modules, modernising an older codebase, choosing how to model data or errors, or setting up a Python project's tooling.
+license: MIT
+compatibility: Any Agent Skills host. Targets CPython 3.10+; notes call out 3.11 and 3.12 features. Needs python and one of uv, poetry or pip.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "python"
+  kete-loom/owner: "Kete-org"
+---
+
+# Python patterns
+
+Write Python the project's tools can check: typed, explicit about errors and resources, and packaged from one `pyproject.toml`.
+
+## 0. Read the project first
+
+1. Find the supported Python version: `requires-python` in `pyproject.toml`, `.python-version`, CI matrix. Never use syntax newer than the lowest supported version (for example `match` needs 3.10, `except*` and `asyncio.TaskGroup` need 3.11, `type X = ...` and `def f[T]()` need 3.12).
+2. Find the package manager: `uv.lock` means uv, `poetry.lock` means poetry, `requirements*.txt` or only `pyproject.toml` means pip. Use that tool; never mix them in one project.
+3. Find the linters and type checker: `[tool.ruff]`, `[tool.mypy]`, `[tool.pyright]` or `pyrightconfig.json`, `.pre-commit-config.yaml`. Follow their settings over this skill.
+4. If the project has none of these and the user wants a new setup, use `references/tooling.md`.
+
+## 1. Types
+
+- Annotate every public function's parameters and return type. Inside function bodies, let inference work.
+- Use built-in generics and unions: `list[str]`, `dict[str, int]`, `str | None` (3.10+). Use `typing` only for what builtins lack (`Protocol`, `TypedDict`, `Literal`, `Final`, `TypeVar`, `overload`).
+- Accept abstract, return concrete: take `Iterable[T]` or `Mapping[K, V]` from `collections.abc`, return `list[T]` or `dict[K, V]`.
+- Prefer `Protocol` over inheritance for "anything with a `.read()` method".
+- `Any` is an escape hatch, not a type. If you need it, leave a comment saying why. Prefer `object` when you only pass a value through.
+- Put imports used only in annotations under `if TYPE_CHECKING:` when they cause import cycles, and add `from __future__ import annotations` (or quote the annotation) so the name isn't evaluated at runtime, where it doesn't exist.
+- Never silence the checker with a bare `# type: ignore`; use the code, e.g. `# type: ignore[arg-type]`, plus a reason.
+
+## 2. Modelling data
+
+Decision rule:
+
+| Data | Use |
+|---|---|
+| Internal value object, trusted input | `@dataclass(frozen=True, slots=True)` (`slots` needs 3.10) |
+| Untrusted input: HTTP bodies, config files, queue messages, LLM output | pydantic `BaseModel` (or the project's existing validator) |
+| A dict shape you can't change (JSON passed through) | `TypedDict` |
+| Fixed set of choices | `enum.Enum` / `StrEnum` (3.11) or `Literal[...]` |
+
+- Validate once at the boundary, then pass typed objects inward. Don't re-validate in every layer, and don't let raw `dict[str, Any]` travel through the core.
+- Mutable defaults: never `def f(items=[])` or `items: list = []` on a dataclass. Use `None` and create inside, or `field(default_factory=list)`.
+- Pydantic v1 and v2 APIs differ (`.dict()` vs `.model_dump()`, `@validator` vs `@field_validator`). Check the installed major version before writing model code.
+
+## 3. Errors
+
+- Raise specific exceptions. Define one base exception per package (`class BillingError(Exception)`) and subclass it for cases callers handle differently.
+- Catch the narrowest type you can handle, as close as possible to where you can do something useful. Never `except:` or `except Exception: pass`.
+- When translating an error, chain it: `raise ConfigError(f"bad port {raw!r}") from exc`.
+- Log *or* raise, not both at every layer. Log once, at the edge (request handler, CLI main, worker loop).
+- Use `logger.exception(...)` inside `except` to keep the traceback. Use `logging.getLogger(__name__)`, never `print` for diagnostics in library code.
+- Don't use exceptions for ordinary control flow across many layers; return `None` or a result type when absence is normal.
+- `assert` is stripped under `python -O`. Never use it to validate input.
+
+## 4. Resources and context managers
+
+- Anything that must be closed (files, sockets, DB connections, locks, temp dirs, HTTP clients) goes in `with` / `async with`.
+- Write small context managers with `contextlib.contextmanager` (or `asynccontextmanager`); put cleanup in `finally`.
+- Use `contextlib.ExitStack` when the number of resources is dynamic.
+- Always pass `encoding="utf-8"` to `open()` for text files; the default depends on the platform.
+- Use `pathlib.Path` for paths, not string concatenation.
+
+## 5. asyncio
+
+1. Never call blocking code in a coroutine (`time.sleep`, `requests`, sync DB drivers, heavy CPU). Use the async library or `await asyncio.to_thread(fn, ...)`.
+2. Every coroutine must be awaited. A call without `await` returns a coroutine object and does nothing.
+3. Keep a reference to tasks from `asyncio.create_task`; the loop only holds weak references, so an unreferenced task can be garbage-collected mid-run. On 3.11+ prefer `async with asyncio.TaskGroup() as tg:` which awaits and cancels children for you.
+4. Put timeouts on network calls: `asyncio.timeout(s)` (3.11+) or `asyncio.wait_for(...)`.
+5. Don't swallow `asyncio.CancelledError`. If you catch it to clean up, re-raise it.
+6. `asyncio.gather(...)` without `return_exceptions=True` cancels nothing when one fails; the others keep running. Use `TaskGroup` when siblings should stop together.
+7. Bound concurrency with `asyncio.Semaphore` instead of launching thousands of tasks.
+8. Call `asyncio.run(main())` once at the program entry point; never from inside a running loop.
+
+## 6. Idioms worth enforcing
+
+- Comprehensions for simple transforms; a plain loop once there is more than one condition or a side effect.
+- `enumerate`, `zip(..., strict=True)` (3.10), `itertools`, `functools.cache` before hand-rolled versions.
+- f-strings for formatting, but `logger.info("user %s", user_id)` style in logging calls (lazy formatting).
+- `__all__` or a leading underscore to mark what is public.
+- No module-level side effects beyond constants: no network calls, no DB connections at import time. Put entry points under `if __name__ == "__main__":` or a `[project.scripts]` entry.
+- Never build SQL, shell commands or file paths from user input with string formatting. Use parameterised queries, `subprocess.run([...])` with a list and no `shell=True`, and validated paths.
+
+## 7. Packaging and environments
+
+- One `pyproject.toml` holds metadata, dependencies and tool config. No new `setup.py` unless a C build needs it.
+- Always work in a virtual environment. Never `pip install` into the system or global interpreter, and never with `sudo`.
+- Add dependencies with the project's tool so the lockfile updates: `uv add httpx`, `uv add --dev pytest`; `poetry add httpx`, `poetry add --group dev pytest`; pip projects edit `pyproject.toml` (or `requirements.in`) then reinstall.
+- Commit the lockfile for applications. Libraries declare ranges in `[project.dependencies]` and don't pin exact versions.
+- Run tools through the environment: `uv run pytest`, `poetry run mypy .`, or an activated `.venv`.
+
+Commands and config snippets for each tool: `references/tooling.md`.
+
+## 8. Before you finish
+
+1. Run the formatter and linter the project uses (usually `ruff format` and `ruff check`).
+2. Run the type checker (`mypy` or `pyright`) on the files you touched. Fix new errors; don't add ignores to hide them.
+3. Run the tests. For writing tests, use the `python-testing` skill.
+4. Stop and ask the user before: raising `requires-python`, switching package manager, upgrading a major dependency (pydantic 1 to 2, SQLAlchemy 1 to 2), or turning on strict type checking for the whole project.
+
+## Report back
+
+State: files changed, the lint, type-check and test commands you ran with their results, and any new dependency added (name and why).

package/skills/python-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Should this config object be a dataclass or a pydantic model? It's loaded from a YAML file users edit.",
+    "Set up a new Python package with pyproject.toml, uv, ruff and mypy strict",
+    "Modernise this Python 3.7-era module: add type hints, replace the dict soup with proper types",
+    "My asyncio service freezes whenever it calls the old requests-based client, how should I restructure it?",
+    "Design an exception hierarchy for our Python billing library so callers can catch the right errors"
+  ],
+  "should_not_trigger": [
+    "Write pytest tests with fixtures and parametrize for the invoice module",
+    "Review this Python pull request for bugs before I merge it",
+    "mypy says 'Cannot find implementation or library stub for module named yaml', fix it",
+    "Add a FastAPI endpoint that creates a user and returns 201",
+    "Write idiomatic Go error handling for this HTTP handler"
+  ]
+}

package/skills/python-patterns/references/tooling.md

@@ -0,0 +1,101 @@
+# Python tooling reference
+
+Read this when setting up a new project or adding tooling to one that has none. If the project already configures a tool, keep its settings.
+
+## Package managers
+
+| Task | uv | poetry | pip + venv |
+|---|---|---|---|
+| Create env | `uv venv` (or implicit on `uv sync`) | `poetry install` | `python -m venv .venv` then activate |
+| Install from lock | `uv sync` | `poetry install` | `pip install -e ".[dev]"` or `pip install -r requirements.txt` |
+| Install exactly the lock, fail if stale (CI) | `uv sync --locked` | `poetry check --lock && poetry install` | `pip install -r requirements.txt` (pinned via pip-tools) |
+| Add runtime dep | `uv add httpx` | `poetry add httpx` | edit `[project.dependencies]`, reinstall |
+| Add dev dep | `uv add --dev pytest` | `poetry add --group dev pytest` | edit `[dependency-groups]` (install with `pip install --group dev` on a pip that supports it) or `[project.optional-dependencies].dev` / a requirements file |
+| Update lock | `uv lock` / `uv lock --upgrade-package httpx` | `poetry lock` / `poetry update httpx` | `pip-compile` (pip-tools) |
+| Run a tool | `uv run pytest` | `poetry run pytest` | activate `.venv`, then `pytest` |
+
+uv notes:
+- `uv sync` is exact by default: it removes packages not in the lockfile.
+- `--locked` errors if `uv.lock` is out of date; `--frozen` uses the lockfile without checking it.
+- Dev dependencies live in `[dependency-groups]` and the `dev` group is synced by default; skip it with `--no-dev`.
+
+## Minimal pyproject.toml
+
+```toml
+[project]
+name = "acme-billing"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.27"]
+
+[project.scripts]
+acme-billing = "acme_billing.cli:main"
+
+[dependency-groups]
+dev = ["pytest", "ruff", "mypy"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+```
+
+Use a `src/` layout (`src/acme_billing/__init__.py`) so tests import the installed package, not the working directory.
+
+## ruff
+
+```toml
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "S", "RUF"]
+```
+
+- `ruff check .` lints, `ruff check --fix .` applies safe fixes, `ruff format .` formats (replaces black). `ruff format` does not sort imports; with `I` selected, `ruff check --fix` does that (replaces isort).
+- `B` (bugbear) catches mutable defaults and loop-variable capture; `S` (bandit) catches `shell=True`, `eval` and hard-coded secrets; `UP` rewrites old syntax for `target-version`.
+- Rule selectors live under `[tool.ruff.lint]`, not top-level `[tool.ruff]`.
+
+## mypy
+
+```toml
+[tool.mypy]
+python_version = "3.11"
+strict = true
+warn_unreachable = true
+
+[[tool.mypy.overrides]]
+module = ["legacy.*"]
+ignore_errors = true
+```
+
+- Turn on `strict` for new code; on an existing codebase enable it per package with `overrides` instead of all at once.
+- Missing stubs: install `types-<pkg>` (for example `types-requests`), or set `ignore_missing_imports = true` in an override for that one module.
+- `mypy --install-types` can fetch missing stub packages, but review what it adds.
+
+## pyright
+
+```toml
+[tool.pyright]
+pythonVersion = "3.11"
+typeCheckingMode = "strict"
+venvPath = "."
+venv = ".venv"
+```
+
+- `typeCheckingMode` is `off`, `basic`, `standard` or `strict`.
+- If pyright can't resolve imports, it is almost always looking at the wrong interpreter: set `venvPath`/`venv` or run it inside the environment.
+
+## pre-commit
+
+```yaml
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: <pin a release tag>
+    hooks:
+      - id: ruff-check  # older ruff-pre-commit releases call it `ruff` (kept as a legacy alias)
+        args: [--fix]
+      - id: ruff-format
+```
+
+Pin `rev` to a real tag; check the ruff-pre-commit releases page for the current one.

package/skills/python-testing/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: python-testing
+description: Writes and repairs pytest suites for Python code using fixtures and conftest.py, parametrize, monkeypatch and unittest.mock, tmp_path, pytest-asyncio for coroutines, coverage with pytest-cov, and a procedure for diagnosing flaky or order-dependent tests. Use when adding tests to a Python project, converting unittest-style tests to pytest, mocking an external call in a Python test, or chasing a pytest test that passes locally but fails in CI.
+license: MIT
+compatibility: Any Agent Skills host. Needs python and pytest; async tests need pytest-asyncio (or anyio's pytest plugin), coverage needs pytest-cov.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "python"
+  kete-loom/owner: "Kete-org"
+---
+
+# Python testing with pytest
+
+Tests that are fast, deterministic and fail for one clear reason.
+
+## 0. Find the setup
+
+1. Find the test command: `[tool.pytest.ini_options]` in `pyproject.toml`, `pytest.ini`, `tox.ini`, `noxfile.py`, `Makefile`, CI config. Run through the env manager (`uv run pytest`, `poetry run pytest`, or an activated venv).
+2. Read the nearest `conftest.py` files. Reuse existing fixtures before writing new ones.
+3. Run the suite once and record the result. If it already fails, **stop and tell the user** which tests fail before you change anything.
+4. Note plugins in use (`pytest-asyncio`, `anyio`, `pytest-mock`, `pytest-django`, `pytest-xdist`, `hypothesis`). Follow their conventions; don't add a new plugin without asking.
+
+## 1. Writing a test
+
+- File `tests/test_<module>.py`, function `test_<behaviour>_<condition>`, e.g. `test_total_rejects_negative_quantity`.
+- One behaviour per test. Arrange, act, assert. Plain `assert`; pytest rewrites it to show values.
+- Test through the public API. Don't assert on private helpers or call counts unless the call is the behaviour.
+- Errors: `with pytest.raises(ValueError, match="negative"):`. Keep the `with` block to the single call that should raise.
+- Floats: `assert x == pytest.approx(0.3)`.
+- Warnings: `with pytest.warns(DeprecationWarning):`.
+
+## 2. Fixtures
+
+- A fixture provides one thing. Name it for what it gives (`user`, `db_session`), not what it does.
+- Cleanup goes after `yield` in the fixture:
+
+  ```python
+  @pytest.fixture
+  def client():
+      c = make_client()
+      yield c
+      c.close()
+  ```
+
+- Scope: default `function`. Widen to `module` or `session` only for expensive, read-only resources; a shared mutable fixture causes order-dependent failures.
+- Share fixtures through `conftest.py` in the closest directory that needs them, not one giant root file.
+- Factories: when tests need several variants, return a function (`make_user(role="admin")`) rather than writing ten fixtures.
+- Avoid `autouse=True` except for true global guards (blocking network, resetting a singleton).
+
+## 3. Parametrize
+
+```python
+@pytest.mark.parametrize(
+    ("raw", "expected"),
+    [("1h", 3600), ("90s", 90), ("0m", 0)],
+    ids=["hours", "seconds", "zero"],
+)
+def test_parse_duration(raw, expected):
+    assert parse_duration(raw) == expected
+```
+
+- Use it for the same behaviour over many inputs; use separate tests when the assertions differ.
+- Give `ids` when values are long or unreadable.
+- Mark one known case with `pytest.param(..., marks=pytest.mark.xfail(reason="#123"))` rather than deleting it.
+
+## 4. Patching and mocking
+
+Decision rule: patch only boundaries you don't own or can't run fast (network, clock, randomness, subprocess, third-party SDKs). Never mock the unit under test.
+
+- Environment and attributes: `monkeypatch.setenv("API_URL", "http://test")`, `monkeypatch.setattr(module, "fetch", fake)`, `monkeypatch.delenv(..., raising=False)`. Undone automatically.
+- **Patch where the name is looked up, not where it is defined.** If `app/billing.py` does `from app.http import post`, patch `app.billing.post`.
+- Use `unittest.mock.create_autospec(Real)` or `patch(..., autospec=True)` so the mock fails on wrong signatures.
+- Coroutines: `AsyncMock` (used automatically by `patch` when the target is `async def`).
+- Prefer a small fake class or an in-memory implementation over a deep chain of `MagicMock().a.b.return_value`.
+- HTTP: use the project's existing tool (`respx` for httpx, `responses` for requests) instead of patching internals.
+- Time: inject a clock, or use the project's freezer (`time-machine`, `freezegun`). Never `sleep` in a test to wait for time to pass.
+
+More mocking patterns and pitfalls: `references/mocking.md`.
+
+## 5. Files and output
+
+- `tmp_path` gives a fresh `pathlib.Path` per test; `tmp_path_factory` for session scope. Never write into the repo or `/tmp` directly.
+- `capsys` / `capfd` for stdout and stderr, `caplog` for log records (`caplog.set_level(logging.INFO)` first).
+- `monkeypatch.chdir(tmp_path)` when code uses relative paths.
+
+## 6. Async code
+
+- pytest-asyncio: mark tests `@pytest.mark.asyncio`, or set `asyncio_mode = "auto"` in `[tool.pytest.ini_options]` so every `async def` test runs. The default mode is `strict`; in strict mode async fixtures need `@pytest_asyncio.fixture`. An unmarked `async def` test never runs: older pytest skips it with a warning, pytest 8.4+ fails it.
+- If the project uses anyio (common with FastAPI/Starlette/httpx), use `@pytest.mark.anyio` and its `anyio_backend` fixture instead. Don't install both styles in one suite.
+- Await everything. A test that calls a coroutine without `await` passes without running it; pytest emits a "coroutine was never awaited" warning. Treat that warning as a failure.
+- Bound waits with `asyncio.timeout(...)` / `asyncio.wait_for(...)` so a hung test fails rather than blocks CI.
+- Check the installed pytest-asyncio version's docs for event-loop scope options before changing loop scope; the API changed across releases.
+
+## 7. Coverage
+
+- `pytest --cov=<package> --cov-report=term-missing` (pytest-cov). Use `--cov-branch` to see untaken branches.
+- Read the missing lines; add tests for behaviour that matters (error paths, boundaries), not to hit a number.
+- Respect `fail_under` in `[tool.coverage.report]` if set. Never lower it without asking.
+
+## 8. Flaky tests
+
+Work through in order, and stop at the first cause you can prove:
+
+1. Reproduce: rerun the single test many times (`pytest path::test -x --count 50` with pytest-repeat if installed, or a shell loop).
+2. Order dependence: run it alone, then with the full file, then with pytest-randomly's seed from the failing run (`--randomly-seed=<seed>`), or disable shuffling with `-p no:randomly` to compare. Passing alone but failing in the suite means shared state: a module-level cache, a wide-scope mutable fixture, an unreset singleton, leaked env vars.
+3. Parallelism: compare with and without `-n auto` (pytest-xdist). Shared files, ports or DB rows break under xdist; use `tmp_path` and per-worker names (`worker_id` fixture).
+4. Time and randomness: dates near midnight or month end, timezones, unseeded `random`, set or dict ordering assumptions.
+5. Async and threads: missing `await`, sleeps used as synchronisation, tasks still running after the test ends.
+6. Real network or external services.
+
+Fix the cause. Never "fix" flakiness by adding retries, `sleep`, or `@pytest.mark.skip` without the user agreeing; if you must quarantine, use `xfail(strict=False, reason=...)` with an issue link.
+
+## Rules
+
+- Never delete, skip or weaken an existing test to get green. Explain to the user if you think a test is wrong.
+- No real network, no real clock dependence, no shared state between tests.
+- Run the single new test first, then its file, then the whole suite.
+- After three focused attempts at a failing test, stop and report what you tried.
+
+For test-first workflow (red, green, refactor), use the `tdd-workflow` skill. For browser-level tests, use `e2e-testing-playwright`.
+
+## Report back
+
+Tests added or changed (names), the exact command run, pass/fail counts, coverage change if measured, and for flaky tests the proven root cause.

package/skills/python-testing/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Write pytest tests for the parse_invoice function, use parametrize for the edge cases",
+    "How do I mock the httpx call inside my service when testing it with pytest?",
+    "test_sync_orders passes on my machine but fails randomly in CI with pytest-xdist",
+    "Add tests for this async def fetch_rates coroutine, we use pytest-asyncio",
+    "Convert these unittest.TestCase classes to plain pytest functions with fixtures"
+  ],
+  "should_not_trigger": [
+    "Should I use a dataclass or pydantic for this Python settings object?",
+    "Review my Python diff for mutable default arguments and swallowed exceptions",
+    "pip install fails with ResolutionImpossible on our Python project, sort it out",
+    "Write Jest tests for this TypeScript reducer",
+    "Write a Playwright end-to-end test for the login page"
+  ]
+}