rsc-universal 0.1.1

package/skills/proposals/scripts/verify.sh

@@ -0,0 +1,201 @@
+#!/usr/bin/env bash
+#
+# verify.sh — structural lint for a proposal / SOW markdown draft.
+#
+# WHAT IT DOES (read-only; never edits a file)
+#   Greps a generated proposal/SOW markdown for its required-section contract and
+#   flags scope-creep and smuggled-legal language. It is a STRUCTURE check, not a
+#   quality judgement — the persuasion rigor lives in the capability eval.
+#     1. Required proposal sections present: executive summary, scope, pricing/
+#        investment, timeline, next step.
+#     2. If the doc looks like a SOW, its required clauses are present:
+#        exclusions, acceptance criteria, change order, payment schedule.
+#     3. Weasel / scope-creep ban-list ABSENT: "etc.", "as needed", "and more",
+#        "TBD" (in scope), unbounded "ongoing".  -> FAIL (these lose free-work fights)
+#     4. Binding-legal smuggle WARNING: "indemnif", "governing law",
+#        "limitation of liability", "intellectual property assigns/assignment".
+#        -> warn "route to contracts" (do not draft binding terms here).
+#     5. Executive-summary length 200–400 words -> warn if outside.
+#
+# EXIT CODES
+#   0  clean, or no target file to inspect (empty target is NOT a failure),
+#      or warn-only findings
+#   1  a required section is missing, or a banned weasel word is present
+#   2  bad usage
+#
+# HOW TO RUN (point it at YOUR draft, not the skills repo)
+#   ./verify.sh proposal.md            # lint one file
+#   ./verify.sh --path proposals/      # lint every *.md / *.markdown under a dir
+#   ./verify.sh                        # scan ./ ; if nothing matches, skip + exit 0
+#
+# Runs on stock macOS bash 3.2: no mapfile, no associative arrays.
+
+set -euo pipefail
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; NC=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; NC=''
+fi
+
+ok_count=0; skip_count=0; warn_count=0; fail_count=0
+ok()   { printf '%s[ ok ]%s %s\n' "$GREEN"  "$NC" "$*"; ok_count=$((ok_count + 1)); }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; skip_count=$((skip_count + 1)); }
+warn() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; warn_count=$((warn_count + 1)); }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; fail_count=$((fail_count + 1)); }
+
+usage() { sed -n '2,33p' "$0" | sed 's/^# \{0,1\}//'; }
+
+# --- arg parse --------------------------------------------------------------
+SCAN_PATH=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --path)    SCAN_PATH="${2:?--path needs a value}"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    -*)        printf '%sUnknown argument: %s%s\n\n' "$RED" "$1" "$NC"; usage; exit 2 ;;
+    *)         SCAN_PATH="$1"; shift ;;
+  esac
+done
+[ -z "$SCAN_PATH" ] && SCAN_PATH="."
+
+if [ ! -e "$SCAN_PATH" ]; then
+  printf '%sPath not found: %s%s\n' "$RED" "$SCAN_PATH" "$NC"; exit 2
+fi
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# --- collect candidate markdown files --------------------------------------
+# A single file is used as-is; a directory is searched for *.md / *.markdown.
+FILES=""
+if [ -f "$SCAN_PATH" ]; then
+  FILES="$SCAN_PATH"
+else
+  FILES="$(find "$SCAN_PATH" -type f \( -name '*.md' -o -name '*.markdown' \) 2>/dev/null || true)"
+fi
+
+# Empty / clean target is NOT a failure — nothing to lint, exit 0.
+if [ -z "$FILES" ]; then
+  skip "no proposal/SOW markdown found under '$SCAN_PATH' — nothing to lint"
+  printf '\nok=%d skip=%d warn=%d fail=%d\n' "$ok_count" "$skip_count" "$warn_count" "$fail_count"
+  exit 0
+fi
+
+# gci <pattern> <file>: case-insensitive grep, swallow no-match (so set -e is safe).
+gci() { grep -iE -e "$1" "$2" >/dev/null 2>&1; }
+
+# word_count_section <file> <start-heading-regex>: words from the first matching
+# heading until the next markdown "## " heading. 0 if the heading is absent.
+exec_summary_words() {
+  awk '
+    BEGIN { inseg=0; words=0 }
+    tolower($0) ~ /^#+ +(executive summary|exec summary|resumen ejecutivo|resum executiu)/ { inseg=1; next }
+    inseg && /^#{1,6} / { inseg=0 }
+    inseg { words += NF }
+    END { print words+0 }
+  ' "$1"
+}
+
+printf 'Linting %d file(s) under: %s\n\n' "$(printf '%s\n' "$FILES" | grep -c .)" "$SCAN_PATH"
+
+# --- per-file checks --------------------------------------------------------
+printf '%s\n' "$FILES" | while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  printf '%s— %s%s\n' "$YELLOW" "$f" "$NC"
+
+  # 1. required proposal sections
+  gci 'executive summary|exec summary|resumen ejecutivo|resum executiu' "$f" \
+    && ok "  exec summary present" || fail "  missing executive summary"
+  gci '(^|[^a-z])scope([^a-z]|$)|what.?s included|abast|alcance' "$f" \
+    && ok "  scope present" || fail "  missing scope section"
+  gci 'pricing|investment|tiers?|inversi|preu|precio' "$f" \
+    && ok "  pricing/investment present" || fail "  missing pricing/investment section"
+  gci 'timeline|milestones?|calendari|cronograma' "$f" \
+    && ok "  timeline/milestones present" || fail "  missing timeline section"
+  gci 'next steps?|mutual action|propers passos|pr.ximos pasos|call to action' "$f" \
+    && ok "  next-step/close present" || fail "  missing next-step/close"
+
+  # 2. SOW-specific clauses (only if the doc declares itself a SOW)
+  if gci 'statement of work|scope of work|^#.*\bsow\b|abast del projecte' "$f"; then
+    ok "  detected SOW — checking SOW clauses"
+    gci 'exclud|exclusion|not (in scope|included)|out of scope|fora d.abast|excluido' "$f" \
+      && ok "    explicit exclusions present" || fail "    SOW missing explicit EXCLUSIONS"
+    gci 'acceptance criteria|accept(ed|ance)|criteris d.acceptaci|criterios de aceptaci' "$f" \
+      && ok "    acceptance criteria present" || fail "    SOW missing acceptance criteria"
+    gci 'change order|change.?request|written approval|ordre de canvi|orden de cambio' "$f" \
+      && ok "    change-order clause present" || fail "    SOW missing change-order clause"
+    gci 'payment (schedule|milestones?|terms)|on signature|on acceptance|calendari de pagament' "$f" \
+      && ok "    payment schedule present" || fail "    SOW missing payment schedule"
+  else
+    skip "  not a SOW (skipping SOW-specific clause checks)"
+  fi
+
+  # 3. weasel / scope-creep ban-list -> FAIL
+  weasel="$(grep -inE 'etc\.|[^a-z]as needed|and more|[^a-z]tbd[^a-z]|ongoing (support|work|maintenance)' "$f" 2>/dev/null || true)"
+  if [ -n "$weasel" ]; then
+    fail "  weasel / scope-creep words (bound them with a quantity):"
+    printf '%s\n' "$weasel" | head -n 5 | sed 's/^/        /'
+  else
+    ok "  no weasel / scope-creep words"
+  fi
+
+  # 4. binding-legal smuggle -> WARN (route to contracts)
+  legal="$(grep -inE 'indemnif|governing law|limitation of liability|intellectual property (assigns|assignment)|liability cap' "$f" 2>/dev/null || true)"
+  if [ -n "$legal" ]; then
+    warn "  binding-legal language found — route these to the contracts skill / MSA:"
+    printf '%s\n' "$legal" | head -n 5 | sed 's/^/        /'
+  else
+    ok "  no smuggled binding-legal clauses"
+  fi
+
+  # 5. exec-summary length 200–400 words -> WARN
+  w="$(exec_summary_words "$f")"
+  if [ "$w" -eq 0 ]; then
+    : # absence already reported in check 1
+  elif [ "$w" -lt 200 ] || [ "$w" -gt 400 ]; then
+    warn "  exec summary is $w words (aim 200–400)"
+  else
+    ok "  exec summary length ok ($w words)"
+  fi
+  printf '\n'
+done
+
+# The while-pipe runs in a subshell under bash 3.2, so its counters don't survive.
+# Re-derive the pass/fail decision from a second, quiet aggregate pass.
+agg_fail=0
+while IFS= read -r f; do
+  [ -z "$f" ] && continue
+  for p in \
+    'executive summary|exec summary|resumen ejecutivo|resum executiu' \
+    '(^|[^a-z])scope([^a-z]|$)|what.?s included|abast|alcance' \
+    'pricing|investment|tiers?|inversi|preu|precio' \
+    'timeline|milestones?|calendari|cronograma' \
+    'next steps?|mutual action|propers passos|pr.ximos pasos|call to action'
+  do
+    gci "$p" "$f" || agg_fail=$((agg_fail + 1))
+  done
+  if gci 'statement of work|scope of work|^#.*\bsow\b|abast del projecte' "$f"; then
+    for p in \
+      'exclud|exclusion|not (in scope|included)|out of scope|fora d.abast|excluido' \
+      'acceptance criteria|accept(ed|ance)|criteris d.acceptaci|criterios de aceptaci' \
+      'change order|change.?request|written approval|ordre de canvi|orden de cambio' \
+      'payment (schedule|milestones?|terms)|on signature|on acceptance|calendari de pagament'
+    do
+      gci "$p" "$f" || agg_fail=$((agg_fail + 1))
+    done
+  fi
+  if grep -iE 'etc\.|[^a-z]as needed|and more|[^a-z]tbd[^a-z]|ongoing (support|work|maintenance)' "$f" >/dev/null 2>&1; then
+    agg_fail=$((agg_fail + 1))
+  fi
+done <<EOF
+$FILES
+EOF
+
+printf 'Done. (re-run after fixing any [fail] lines above)\n'
+cat <<'NOTE'
+
+Note: [fail] = a broken section contract or scope-creep word (fix before sending).
+      [warn] = binding-legal language or an off-length exec summary (review/justify).
+NOTE
+
+if [ "$agg_fail" -gt 0 ]; then exit 1; fi
+exit 0

package/skills/python/SKILL.md

@@ -0,0 +1,369 @@
+---
+name: python
+description: "Use when writing, reviewing, modernizing, typing, or packaging Python at the language level (any framework or none) - PEP 695 generics and the type-alias statement, mypy --strict typing, dataclasses/Protocol/TypedDict/Enum choices, asyncio.TaskGroup and structured concurrency, stdlib idioms (pathlib/itertools/functools/contextlib/match), src/ layout + pyproject.toml managed with uv, and a ruff+mypy+pytest verify gate. Triggers: 'set up a Python project with uv', 'is this Pythonic / modernize to 3.12+', 'make mypy --strict pass', 'convertir este gather a TaskGroup', 'dataclass slots frozen vs NamedTuple', any .py file or pyproject.toml. NOT building a FastAPI/ASGI service (that is fastapi), NOT a deep pytest fixture/mock suite (that is testing-py)."
+tags: [python, typing, async, packaging, uv]
+recommends: [fastapi, secure-coding, deployment]
+origin: risco
+---
+
+# Modern Python at the language level
+
+Write, review, modernize, type, and package Python that reads like a typed,
+flat-control-flow, stdlib-first program whose dependencies and tooling all live in one
+`pyproject.toml`. Types are part of the design, not decoration; the stdlib is large and you
+reach for it before a dependency; correctness is `ruff` + a type checker + `pytest` in one gate.
+
+Targets **Python 3.12+ (floor) / 3.14 (current**, released 7 Oct 2025): PEP 695 inline
+type parameters (`class Box[T]:`, `type Alias = ...`), `asyncio.TaskGroup`, and — in 3.14 —
+deferred annotation evaluation by default (PEP 649/749, no more `from __future__ import
+annotations`), PEP 750 template strings (`t"..."`), and `compression.zstd`. Tooling pins:
+**uv 0.11** (project + package manager), **ruff 0.15** (lint + format), **mypy 1.20
+`--strict`** (or Astral's `ty`, still preview — default to mypy), **pytest 8**.
+
+## When to use / When NOT to use
+
+**Use when** the question is *the language* in any `.py` file or `pyproject.toml`: typing,
+generics, protocols, dataclass/NamedTuple/TypedDict/Enum choices, async (`TaskGroup`, timeouts,
+cancellation — not a web server), comprehensions, context managers, error handling; setting up a
+project from zero with `uv` (init, venv, lockfile, scripts); modernizing to PEP 695; or wiring
+the `ruff` + type-checker + `pytest` + `verify.sh` gate.
+
+**When NOT to use (delegate):**
+
+- Building a FastAPI / ASGI service (routes, Pydantic models, SQLAlchemy, uvicorn) ->
+  [`fastapi`](../fastapi/SKILL.md). That skill owns the service shape; this one owns the
+  language it is written in.
+- A pytest suite as the primary task — fixtures, parametrize matrices, mocking, coverage,
+  property-based testing -> `testing-py` (this skill keeps only the *baseline*: a few tests
+  so `verify.sh` has something to run, then hands off).
+- Language-agnostic threat modeling / authz / OWASP review ->
+  [`secure-coding`](../secure-coding/SKILL.md) (this skill keeps Python-specific safety: no
+  `eval`/`pickle` of untrusted data, `subprocess` without `shell=True`, `secrets` over `random`).
+- Containerfile / CI pipeline / deploy mechanics -> [`deployment`](../deployment/SKILL.md)
+  (this skill ships only a uv-based CI note).
+- Another language -> `go`, `typescript`, `rust`, etc. Django ORM/models/migrations -> `django`.
+
+Python typing, async language semantics, and uv packaging live **here**, not in a separate
+skill — this skill is the canonical authority for the language substrate under any Python program.
+
+## Decision rules
+
+Apply on every Python edit:
+
+1. **Type the boundary.** Every public function, method, and module-level name gets an
+   annotation; let inference handle locals. Untyped public API defeats `--strict`.
+2. **Flat control flow.** Guard-clause and `return`/`raise` early; keep the happy path
+   unindented — arrow code hides the logic.
+3. **Stdlib before a dependency.** `pathlib`, `itertools`, `functools`, `dataclasses`,
+   `collections` cover most needs; a new dep is a maintenance liability you must justify.
+4. **One `pyproject.toml`, managed with uv.** Never hand-edit `requirements.txt`; `uv add`
+   writes the dep and updates `uv.lock`, which you commit.
+5. **Prefer immutability.** `@dataclass(frozen=True, slots=True)` for value objects; mutate
+   only where you must — shared mutable state is the bug you debug at 2am.
+6. **`pathlib`, not `os.path`.** `Path("a") / "b"` over `os.path.join`; it is typed and composable.
+7. **Structured `logging`, never `print` in a library.** `print` writes to a caller's stdout
+   you do not own; `logging.getLogger(__name__)` lets them configure it.
+8. **`asyncio.TaskGroup` over bare `gather`.** A `TaskGroup` cancels siblings on first error and
+   propagates an `ExceptionGroup`; `gather` leaks tasks on failure (rule 8 in Async below).
+9. **No mutable default arguments.** `def f(xs: list[int] | None = None)` then `xs = xs or []`;
+   `def f(xs=[])` shares one list across all calls — a classic latent bug.
+10. **Everything passes the gate.** `ruff check` + `ruff format --check` + `mypy --strict` +
+    `pytest` — green locally via `scripts/verify.sh` before you call it done.
+
+## Typing
+
+Type the boundary; run `mypy --strict` so untyped code and implicit `Any` are errors, not
+silent gaps. Use **PEP 695** inline syntax for all new generic code — no explicit `TypeVar`
+objects:
+
+```python
+# Good (3.12+): inline type parameter and the `type` alias statement.
+def first[T](xs: list[T]) -> T:
+    return xs[0]
+
+class Box[T]: ...
+type UserId = int                 # `type` statement: a real alias, lazily evaluated
+# Bad (legacy): `T = TypeVar("T")` then a Generic[T] — fine in old code, don't write it new.
+```
+
+Core choices: `Protocol` (structural, no inheritance) over an ABC when you only need "has these
+methods"; `X | None` (not `Optional[X]`); `Literal`/`Enum` for closed value sets; `Final` for
+constants; `Self` for fluent returns; `@overload` for signature families. Narrow with
+`isinstance`, `assert`, or an `is None` guard — mypy follows the flow. In **3.14** annotations
+are lazy by default (PEP 649/749), so forward references resolve without `from __future__ import
+annotations`.
+
+Full PEP 695 bounds/constraints/variance, `Protocol` vs ABC, `TypedDict`
+`Required`/`NotRequired`, `ParamSpec`/`TypeVarTuple`, `TypeGuard`/`TypeIs`, `cast`, and common
+`--strict` errors with fixes -> `references/typing.md`.
+
+## Data modeling
+
+Pick the carrier by what the data *is*, not by habit:
+
+| Need | Use | Why |
+| --- | --- | --- |
+| Immutable value object, typed fields, methods | `@dataclass(frozen=True, slots=True)` | Hashable, no `__dict__` overhead, real types |
+| Small fixed tuple, positional + named, immutable | `NamedTuple` | Tuple semantics + field names; cheap |
+| Shape of an external/JSON dict, no runtime class | `TypedDict` | Types a plain `dict` without wrapping it |
+| Closed set of named constants | `Enum` / `StrEnum` / `IntEnum` | One source of truth; `Literal`-friendly |
+| Mutable bag of related state with behavior | plain class / `@dataclass` | When you genuinely need mutation |
+| Runtime-validated I/O model (parse untrusted data) | Pydantic -> [`fastapi`](../fastapi/SKILL.md) | Validation is a service concern, not language |
+
+```python
+from dataclasses import dataclass
+
+@dataclass(frozen=True, slots=True)
+class Point:
+    x: float
+    y: float
+    def translated(self, dx: float, dy: float) -> "Point":
+        return Point(self.x + dx, self.y + dy)   # returns a new value, never mutates
+```
+
+Frozen-slots dataclass when you want methods + hashability + clear types; `NamedTuple` when
+the thing genuinely *is* a small tuple you also unpack positionally.
+
+## Stdlib idioms
+
+Reach into the stdlib before adding a dependency.
+
+- **`pathlib`** for all filesystem paths: `Path("data") / name`, `p.read_text()`,
+  `p.glob("*.json")`, `p.with_suffix(".bak")`.
+- **`collections`**: `defaultdict(list)`, `Counter(words)`, `deque(maxlen=100)` for ring buffers.
+- **`itertools`**: `chain`, `groupby`, `islice`, `batched` (3.12+) instead of hand-rolled loops.
+- **`functools`**: `@cache` / `@lru_cache` for pure memoization, `@cached_property`, `partial`.
+- **`contextlib`**: `@contextmanager`, `ExitStack` for dynamic resource sets, `suppress(FileNotFoundError)`.
+
+Prefer comprehensions over `map`/`filter`+`lambda`; prefer a generator (`(... for ...)`) when
+you only iterate once. Use `match` for structural dispatch over a chain of `isinstance`:
+
+```python
+from functools import cache
+from pathlib import Path
+
+@cache
+def config_dir() -> Path:                 # computed once, memoized
+    return Path.home() / ".config" / "myapp"
+
+def area(shape: object) -> float:
+    match shape:                          # structural dispatch, captures by attribute/key
+        case {"kind": "circle", "r": float(r)}:
+            return 3.14159 * r * r
+        case _:
+            raise TypeError(f"unknown shape: {shape!r}")
+```
+
+f-strings for formatting; note 3.14's PEP 750 `t"..."` template strings yield a `Template`
+(not a `str`) for *safe custom interpolation* (e.g. escaping) — use them when an f-string would
+inject untrusted text. Full cookbook (itertools/functools/collections recipes, `match`
+patterns, dataclass `field`/`default_factory`/`__post_init__`, `Enum`/`StrEnum`/`IntFlag`) ->
+`references/stdlib.md`.
+
+## Errors & resources
+
+Define a small exception hierarchy rooted in one base so callers can catch broadly or
+narrowly; chain causes with `raise ... from`; never write a bare `except:`.
+
+```python
+class AppError(Exception): ...
+class NotFoundError(AppError): ...
+
+def load(path: Path) -> str:
+    try:
+        return path.read_text()
+    except FileNotFoundError as e:
+        raise NotFoundError(f"missing {path}") from e   # preserves the cause chain
+```
+
+Use `except*` to handle an `ExceptionGroup` (what a `TaskGroup` raises) by member type.
+Prefer **EAFP** (try the operation, handle the failure) over LBYL race-prone pre-checks.
+Always release resources with `with` (a context manager), not manual try/finally close.
+
+## Async (language level)
+
+Use `asyncio.run(main())` as the single entry point. **`asyncio.TaskGroup` (3.11+) over bare
+`gather`** — it is the structured-concurrency primitive: a child failure cancels its siblings
+and surfaces as an `ExceptionGroup`, and no task outlives the block.
+
+```python
+import asyncio
+
+# Bad: gather leaks the other tasks on first failure and loses structure.
+async def fetch_all_bad(ids: list[int]) -> list[bytes]:
+    return await asyncio.gather(*(fetch(i) for i in ids))
+
+# Good: TaskGroup — sibling cancellation on error, bounded lifetime, real grouping.
+async def fetch_all(ids: list[int]) -> list[bytes]:
+    async with asyncio.TaskGroup() as tg:
+        tasks = [tg.create_task(fetch(i)) for i in ids]
+    return [t.result() for t in tasks]                  # block exited => all done or raised
+```
+
+Bound every wait with `async with asyncio.timeout(5.0):`. On `CancelledError`, clean up and
+**re-raise** — swallowing it breaks cancellation for the whole tree. Async is for **IO-bound**
+concurrency only; CPU-bound work blocks the loop — push it to `asyncio.to_thread` / a
+`ProcessPoolExecutor` (or 3.14's free-threaded build). **HTTP servers belong to
+[`fastapi`](../fastapi/SKILL.md), not here.** Runtime model, `ExceptionGroup`/`except*`, queues
+with backpressure, cancellation discipline, and sync<->async bridging -> `references/async.md`.
+
+## Project layout & packaging (uv)
+
+Use a `src/` layout so tests import the installed package, not the source tree by accident:
+
+```text
+myapp/
+  src/myapp/__init__.py
+  src/myapp/core.py
+  tests/test_core.py
+  pyproject.toml
+  uv.lock              # committed
+  scripts/verify.sh
+```
+
+`pyproject.toml` is the single config — PEP 621 metadata, dependency groups, and tool config:
+
+```toml
+[project]
+name = "myapp"
+version = "0.1.0"
+requires-python = ">=3.12"
+dependencies = ["httpx>=0.27"]
+
+[project.scripts]
+myapp = "myapp.core:main"          # console entry point
+
+[dependency-groups]
+dev = ["ruff>=0.15", "mypy>=1.13", "pytest>=8"]
+
+[build-system]
+requires = ["uv_build>=0.11"]
+build-backend = "uv_build"         # uv's own backend, stable since July 2025
+
+[tool.ruff]
+line-length = 100
+
+[tool.mypy]
+strict = true
+```
+
+Core uv verbs (each updates `uv.lock`, which you commit):
+
+```bash
+uv init --package myapp        # scaffold pyproject.toml + src/ + .venv
+uv add httpx                   # add a runtime dep
+uv add --dev ruff mypy pytest  # add to the dev group
+uv sync --frozen               # install exactly from the lockfile (CI + fresh clones)
+uv run pytest -q               # run inside the managed venv
+uv python install 3.14         # pin/install an interpreter
+```
+
+## Quality gate + verify.sh
+
+One local gate, mirroring CI: `ruff check --fix .`, `ruff format .`, `mypy --strict src`
+(or `ty check`), `pytest -q`. `scripts/verify.sh` runs all of them, skips a missing tool/dir
+with a warning, and exits non-zero on any real failure — run `./scripts/verify.sh` from the
+project root before declaring done. CI is `astral-sh/setup-uv` + `uv sync --frozen` + the same
+four commands; full pipeline -> [`deployment`](../deployment/SKILL.md).
+
+## pytest baseline
+
+Carry just enough to make `verify.sh` meaningful — plain `test_*` functions, `assert`,
+`pytest.raises`, one `parametrize`, `tmp_path` for files:
+
+```python
+import pytest
+from myapp.core import head
+
+@pytest.mark.parametrize("xs, expected", [(["a", "b"], "a"), (["x"], "x")])
+def test_head_returns_first(xs: list[str], expected: str) -> None:
+    assert head(xs) == expected
+
+def test_head_rejects_empty() -> None:
+    with pytest.raises(ValueError):
+        head([])
+
+def test_writes_file(tmp_path) -> None:
+    (tmp_path / "f.txt").write_text("hi")
+    assert (tmp_path / "f.txt").read_text() == "hi"
+```
+
+Deep fixtures, mocking, coverage gates, and property-based testing belong to `testing-py` —
+stop at the baseline and hand off.
+
+## Security (embedded, Python-specific)
+
+Generic threat modeling and authz live in [`secure-coding`](../secure-coding/SKILL.md); these Python-specific controls stay here:
+
+```python
+# Bad                                          # Good
+eval(user_input)                                ast.literal_eval(user_input)   # never eval/exec input
+pickle.loads(network_bytes)                     json.loads(network_bytes)      # never unpickle untrusted data
+subprocess.run(cmd, shell=True)                 subprocess.run(["ls", path])   # list args, no shell=True
+random.random()  # tokens                       secrets.token_urlsafe(32)      # secrets, not random, for secrets
+```
+
+Keep deps locked (`uv.lock`) and audited (`pip-audit` / `uv` resolution); read secrets from
+env or a secret manager, never hardcode or log them.
+
+## Anti-patterns / rationalizations -> STOP
+
+| Rationalization | Reality / Do instead |
+| --- | --- |
+| "`def f(xs=[])` is fine, it's empty" | One list shared across all calls; use `= None` then `xs = xs or []`. |
+| "bare `except:` to be safe" | Swallows `KeyboardInterrupt`/bugs; catch a specific type. |
+| "`from module import *`" | Pollutes the namespace, breaks tooling; import names explicitly. |
+| "`print()` to debug this library" | Writes to a stdout you don't own; use `logging.getLogger(__name__)`. |
+| "`os.path.join` is what I know" | `pathlib.Path` is typed and composable; use `/`. |
+| "I'll add types later" | Untyped public API defeats `--strict`; type the boundary now. |
+| "edit `requirements.txt` by hand" | Drifts from the lock; `uv add` / `uv remove` and commit `uv.lock`. |
+| "`asyncio.gather` is simpler" | Leaks siblings on failure; `TaskGroup` for structured concurrency. |
+| "swallow `CancelledError`, it's noise" | Breaks cancellation for the whole tree; clean up and re-raise. |
+| "`time.sleep` inside this coroutine" | Blocks the event loop; `await asyncio.sleep(...)`. |
+| "`pickle.loads` the cache, it's ours" | Any untrusted byte = code execution; use `json`. |
+| "explicit `TypeVar` everywhere" | New code uses PEP 695 `def f[T]` / `class C[T]` / `type X`. |
+
+## Quick reference
+
+| Task | Command / idiom |
+| --- | --- |
+| New project | `uv init --package myapp` |
+| Add dep / dev dep | `uv add httpx` / `uv add --dev pytest` |
+| Reproducible install | `uv sync --frozen` |
+| Run in venv | `uv run python -m myapp` |
+| Lint + autofix | `uv run ruff check --fix .` |
+| Format (check) | `uv run ruff format --check .` |
+| Type check | `uv run mypy --strict src` |
+| Test | `uv run pytest -q` |
+| Local gate | `./scripts/verify.sh` |
+| Generic | `def f[T](x: T) -> T:` / `type Alias = ...` |
+| Optional | `X | None` (not `Optional[X]`) |
+| Structured async | `async with asyncio.TaskGroup() as tg: tg.create_task(...)` |
+| Memoize | `@functools.cache` |
+| Token | `secrets.token_urlsafe(32)` |
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+When this skill runs in a project with a `02-DOCS/` layer (the
+[`harness`](../harness/SKILL.md) Karpathy wiki), record this project's Python conventions
+there so the next agent inherits them — *recorded, not gated*, never block the task on this.
+
+1. **Find** `02-DOCS/wiki/stack/python.md`, linked from a `## Knowledge map` in the root `CLAUDE.md`.
+2. **If missing or stale**, write the project's real choices (interpreter floor, `src/` layout,
+   uv workflow, ruff/mypy config, async-vs-sync stance, data-modeling defaults) and add the link.
+3. **Read it first on every use**; bump its `Updated` date when a convention changes.
+
+No `02-DOCS/` layer? Skip silently (optionally suggest `harness`).
+
+## See Also
+
+Sibling skills: [`fastapi`](../fastapi/SKILL.md) (the FastAPI/ASGI service shape — this skill
+owns the language it is written in), [`secure-coding`](../secure-coding/SKILL.md) (language-
+agnostic threat modeling/authz — this skill keeps the Python-specific controls),
+[`deployment`](../deployment/SKILL.md) (Containerfile/CI/shipping — this skill ships only the
+uv CI note), and `testing-py` (by id; deep pytest technique — this skill carries only the baseline).
+
+Local references (read when): `references/typing.md` (PEP 695 generics, Protocol vs ABC,
+TypedDict, narrowing, `--strict` fixes); `references/async.md` (asyncio model, TaskGroup vs
+gather, timeouts, cancellation, queues, CPU-bound); `references/stdlib.md`
+(itertools/functools/collections/contextlib/pathlib cookbook, `match`, dataclasses, Enum).

package/skills/python/evals/README.md

@@ -0,0 +1,19 @@
+# Eval harness — `python` skill
+
+These cases are read by an **agent harness** (a Claude agent with the skill catalog loaded),
+not a plain shell script. `cases.yaml` is the fixture; this file is the procedure. Two things
+are measured: **triggering** (does `python` fire on language-level prompts and stay silent on
+near-misses that belong to `fastapi`, `testing-py`, `django`, `secure-coding`, `deployment`?)
+and **capability** (does loading the skill make a scaffold answer measurably better?).
+
+**Triggering:** load the full sibling descriptions, start a fresh session per prompt, feed each
+`should_trigger.prompt` and confirm `python` fires; feed each `should_not_trigger.prompt` and
+confirm it routes to the stated `route_to` and does *not* fire `python`. LLM routing is
+non-deterministic — run 3–5 trials each and pass on the majority; target ≥90% accuracy.
+
+**Capability:** run the `capability.scenario` twice — once with the skill body unavailable, once
+with `python/SKILL.md` (and references) loaded — and grade each output against the `must_include`
+rubric (fraction of points present and correct, averaged over 3 trials). Pass bar: ≥80% with the
+skill, and a clear margin over the without-skill baseline. No network is required; grading is
+rubric-based and partly judgment (e.g. "no mutable default argument"). Keep `cases.yaml` faithful
+to SKILL.md's "When to use / When NOT to use" — change them together.

package/skills/python/evals/cases.yaml

@@ -0,0 +1,46 @@
+skill: python
+
+should_trigger:
+  - prompt: "Set up a new Python project with uv — package layout, pyproject, lint and types."
+    why: "Core packaging/layout/uv duty of this skill: src/ layout, pyproject.toml, ruff+mypy wiring."
+  - prompt: "Is this idiomatic Python? Modernize it to 3.12+ typing."
+    why: "Language-level idiom review plus PEP 695 modernization is the spine of the skill."
+  - prompt: "Add type hints to this module and make mypy --strict pass."
+    why: "Typing the boundary and satisfying a strict checker is owned here, even without naming the tool."
+  - prompt: "Convertir este asyncio.gather a algo más seguro con cancelación correcta."
+    why: "Non-obvious + Spanish: structured concurrency / TaskGroup at the language level; user describes the problem without naming TaskGroup."
+  - prompt: "Should I use a frozen slots dataclass or a NamedTuple for this value object?"
+    why: "Non-obvious data-modeling decision the skill's table resolves; no framework or tool named."
+  - prompt: "This function takes xs=[] as a default and the list keeps growing across calls — what's wrong?"
+    why: "Classic mutable-default-argument bug; a language-level anti-pattern this skill diagnoses without the user naming it."
+
+should_not_trigger:
+  - prompt: "Add a FastAPI route that returns a Pydantic response model with async SQLAlchemy."
+    route_to: "fastapi"
+    why: "Service/route/Pydantic/ORM wiring belongs to fastapi; this skill owns only the language it is written in."
+  - prompt: "Write a thorough pytest suite with shared fixtures, mocking, and a coverage gate."
+    route_to: "testing-py"
+    why: "Deep test technique is testing-py; python carries only the baseline and hands off."
+  - prompt: "Model this table as a Django ORM model with migrations and an admin view."
+    route_to: "django"
+    why: "Django ORM/models/migrations/admin is the django skill, not the language substrate."
+  - prompt: "Threat-model this login flow and review it for OWASP-class authorization issues."
+    route_to: "secure-coding"
+    why: "Language-agnostic threat modeling and authz/abuse review is secure-coding; only Python-specific controls stay here."
+  - prompt: "Write a multi-stage Containerfile and a GitHub Actions pipeline to deploy this Python app."
+    route_to: "deployment"
+    why: "Containerfile / CI / shipping mechanics are deployment; this skill ships only a uv-based CI note."
+
+capability:
+  - scenario: "Scaffold a typed src/-layout Python package with uv: one stdlib-idiomatic module
+      using a PEP 695 generic, one asyncio TaskGroup function, a pyproject.toml with ruff+mypy
+      config and a console entry point, a baseline pytest test, and scripts/verify.sh."
+    must_include:
+      - "uv commands: uv init --package, uv add / uv add --dev, and uv sync --frozen for reproducible installs"
+      - "pyproject.toml with a [project] table (PEP 621, requires-python >=3.12) and a build-system/backend"
+      - "a PEP 695 inline generic (e.g. def first[T](xs: list[T]) -> T or class Box[T]), not an explicit TypeVar object"
+      - "an asyncio.TaskGroup function (not bare asyncio.gather) with cancellation-safe structure"
+      - "mypy --strict configured (e.g. [tool.mypy] strict = true) and ruff check/format wired in"
+      - "at least one pytest test_* function (assert and/or pytest.raises)"
+      - "no mutable default argument (uses = None then x = x or [], or field(default_factory=...)) and no bare except"
+      - "an explicit note that HTTP routes/services belong to fastapi, not this skill"