oh-my-opencode 4.10.0 → 4.11.0

package/dist/skills/programming/references/go/type-patterns.md

@@ -0,0 +1,298 @@
+# Type Patterns
+
+How to use Go's *limited* type system to catch bugs at compile time. Go gives you fewer tools than Python/TS/Rust — this document covers the four patterns that buy back most of the safety.
+
+The four patterns:
+
+1. **Named types** for branding primitives (the Go answer to `NewType` / branded TS).
+2. **Smart constructors with unexported fields** for parse-don't-validate.
+3. **Sealed interfaces** for sum types, with `type switch` + `exhaustive` linter.
+4. **Generics with constraints** for bounded polymorphism (1.18+).
+
+---
+
+## 1. Named types — distinct primitives
+
+Same underlying type, different meaning. The Go type checker prevents *implicit* mixing — but explicit conversion is always possible. Treat this as a contract enforced at boundaries.
+
+```go
+package domain
+
+type UserID string
+type OrderID string
+type EmailRaw string  // raw, unvalidated string from input
+
+func GetUser(id UserID) User { /* ... */ }
+
+uid := UserID("u-123")
+oid := OrderID("o-456")
+
+GetUser(uid)              // ✅ OK
+GetUser(oid)              // ❌ cannot use oid (type OrderID) as UserID
+GetUser("u-123")          // ❌ untyped string literal — Go DOES catch this
+GetUser(UserID("u-123"))  // ✅ explicit conversion — accept it
+```
+
+**Use when**: IDs, opaque tokens, foreign keys, units that share a base primitive.
+
+**Reality check**: Go does NOT prevent `UserID(orderIDAsString)`. The defense is **smart constructors** for everything beyond an internal identifier. Use named types for cheap brand-only protection; combine with constructors for protection that actually holds.
+
+### Time-of-day units
+
+```go
+type Milliseconds int64
+type Seconds      int64
+
+func (ms Milliseconds) ToSeconds() Seconds {
+    return Seconds(ms / 1000)
+}
+```
+
+No implicit `Milliseconds + Seconds`. The compiler refuses. Convert explicitly.
+
+---
+
+## 2. Smart constructors with unexported fields — the Go answer to Pydantic/Zod
+
+The single most important pattern in this document. **Go has no Pydantic. It has this.**
+
+```go
+package domain
+
+import (
+    "errors"
+    "regexp"
+    "strings"
+)
+
+var (
+    ErrInvalidEmail = errors.New("invalid email")
+    emailRe         = regexp.MustCompile(`^[^@\s]+@[^@\s]+\.[^@\s]+$`)
+)
+
+// Email is a parsed, lowercased, valid email address.
+// The zero value is invalid; construct via NewEmail.
+type Email struct {
+    raw string  // unexported — cannot be set from outside the package
+}
+
+func NewEmail(s string) (Email, error) {
+    s = strings.TrimSpace(strings.ToLower(s))
+    if !emailRe.MatchString(s) {
+        return Email{}, ErrInvalidEmail
+    }
+    return Email{raw: s}, nil
+}
+
+// String implements fmt.Stringer for printing.
+func (e Email) String() string { return e.raw }
+
+// MarshalJSON keeps the wire format unchanged.
+func (e Email) MarshalJSON() ([]byte, error) {
+    return []byte(`"` + e.raw + `"`), nil
+}
+
+// UnmarshalJSON is the parsing boundary — strict mode.
+func (e *Email) UnmarshalJSON(data []byte) error {
+    if len(data) < 2 || data[0] != '"' || data[len(data)-1] != '"' {
+        return ErrInvalidEmail
+    }
+    parsed, err := NewEmail(string(data[1 : len(data)-1]))
+    if err != nil {
+        return err
+    }
+    *e = parsed
+    return nil
+}
+```
+
+**Why this works**:
+
+- `Email{raw: "anything"}` from outside the `domain` package is a compile error — `raw` is unexported.
+- The only way to obtain a non-zero `Email` is `NewEmail(...)`, which validates.
+- `UnmarshalJSON` routes wire input through the same constructor — boundary parsing is automatic.
+- Once a function signature has `email Email`, the caller has *proven* it is valid. No internal `if email == ""` checks.
+
+**Use for every domain value that has invariants**: emails, URLs, phone numbers, currency amounts, percentages, semver versions, IDs with format constraints, time ranges, anything you currently validate in three places.
+
+### The "zero value problem"
+
+Go's zero value (`Email{}`) is reachable. The mitigation is documentation + a `IsValid()` method when needed:
+
+```go
+func (e Email) IsZero() bool { return e.raw == "" }
+```
+
+Or accept it: receivers that take `Email` should *never* receive a zero-value `Email` in correct code. Tests verify it.
+
+---
+
+## 3. Sealed interfaces — sum types in Go
+
+Go has no sum types. The closest thing: an interface with an **unexported method** that only types in the same package can satisfy, dispatched via `type switch`, with the `exhaustive` linter ensuring completeness.
+
+```go
+package event
+
+// Event is a closed sum: Created | Updated | Deleted.
+// The sealed() method is unexported so external packages cannot add variants.
+type Event interface {
+    sealed()
+    OccurredAt() time.Time
+}
+
+type Created struct {
+    UserID    UserID
+    Email     Email
+    Timestamp time.Time
+}
+func (Created) sealed()                    {}
+func (e Created) OccurredAt() time.Time    { return e.Timestamp }
+
+type Updated struct {
+    UserID    UserID
+    Changes   map[string]any
+    Timestamp time.Time
+}
+func (Updated) sealed()                    {}
+func (e Updated) OccurredAt() time.Time    { return e.Timestamp }
+
+type Deleted struct {
+    UserID    UserID
+    Reason    string
+    Timestamp time.Time
+}
+func (Deleted) sealed()                    {}
+func (e Deleted) OccurredAt() time.Time    { return e.Timestamp }
+```
+
+Consumer code:
+
+```go
+func Render(e event.Event) string {
+    switch v := e.(type) {
+    case event.Created:
+        return fmt.Sprintf("created %s with %s", v.UserID, v.Email)
+    case event.Updated:
+        return fmt.Sprintf("updated %s: %v", v.UserID, v.Changes)
+    case event.Deleted:
+        return fmt.Sprintf("deleted %s (reason: %s)", v.UserID, v.Reason)
+    default:
+        panic(fmt.Sprintf("unhandled event variant: %T", v))
+    }
+}
+```
+
+The `panic` in `default` is the Go equivalent of TS's `assertNever` or Python's `assert_never`. It is only reachable if a new variant is added without updating the switch.
+
+### The `exhaustive` linter — your compiler
+
+```yaml
+# .golangci.yml
+linters:
+  enable: [exhaustive]
+linters-settings:
+  exhaustive:
+    check:
+      - switch
+      - map
+    default-signifies-exhaustive: false
+```
+
+Now adding `event.Suspended` without updating `Render` is a **lint error**. This is the closest thing Go has to Rust's match exhaustiveness check. **Treat it as compulsory.**
+
+### Sealed interface gotchas
+
+- The method MUST be unexported (`sealed()`, not `Sealed()`). Otherwise other packages can implement it.
+- `type switch` with `*Created` vs `Created` matters — pick value receivers and value cases, or pointer receivers and pointer cases. **Mixing them causes silent miss.**
+- `interface{}` is not a sealed type. Anything implementing zero methods satisfies it. Sealed interfaces have at least the `sealed()` method.
+
+---
+
+## 4. Generics with constraints — bounded polymorphism
+
+Go 1.18+. Use for genuinely generic algorithms; **do not** use for "I want this to accept anything".
+
+```go
+import "cmp"
+
+// Ordered constraint includes all ordered types (int, float, string, …).
+func Max[T cmp.Ordered](a, b T) T {
+    if a > b { return a }
+    return b
+}
+
+// Custom constraint
+type Stringer interface {
+    String() string
+}
+
+func Join[T Stringer](items []T, sep string) string {
+    parts := make([]string, len(items))
+    for i, item := range items {
+        parts[i] = item.String()
+    }
+    return strings.Join(parts, sep)
+}
+```
+
+The `cmp.Ordered` (Go 1.21+), `cmp.Compare`, and `slices`/`maps` packages cover the common cases without you writing constraints.
+
+### When NOT to use generics
+
+- "I want to accept multiple types, so I'll make it generic." Use an **interface** instead. Generics are for parametric polymorphism (same code, different types). Interfaces are for behavioral polymorphism (different code behind a contract).
+- "I want to return `any`." Use a sealed interface and a `type switch`. `any` returns are anti-patterns past public APIs.
+
+---
+
+## 5. Type assertions — the controlled escape hatch
+
+```go
+// Bad — panics on failure
+e := evt.(event.Created)
+
+// Good — comma-ok form, always
+if e, ok := evt.(event.Created); ok {
+    // use e
+}
+
+// Use errors.As for error chains
+var pgErr *pgconn.PgError
+if errors.As(err, &pgErr) {
+    // pgErr is the wrapped pg error
+}
+```
+
+**The `errcheck` and `errorlint` linters reject bare type assertions on `error` values.** Use `errors.As`. See `error-handling.md`.
+
+---
+
+## 6. Pointers vs values — the only durable rule
+
+You will see endless debates. The rule that holds up:
+
+- **If a type has a mutex, never copy it.** Use `*T` everywhere.
+- **If a type is large (> 64 bytes) and read-only, pass by value or pointer is a measured choice.** Default to pointer for "large" things.
+- **Receivers must be consistent.** All methods on `T` either take `T` or `*T`. Don't mix. The `staticcheck` linter catches mixed-receiver bugs.
+- **`nil` pointer = absence. Zero value = "not set yet".** Choose ONE convention per type. Document it.
+
+---
+
+## 7. `any` / `interface{}` — when it is acceptable
+
+Almost never in domain code. Acceptable cases:
+
+- JSON parsing of genuinely heterogeneous payloads (and even then, prefer `json.RawMessage` + targeted parsing).
+- `fmt.Sprintf` arguments (variadic `any` is unavoidable here).
+- Generic container internals before the user-facing API.
+
+The skill rejects `any` in handler signatures, service signatures, store signatures. If you find yourself writing `func Handle(payload any) error`, you have a sealed-interface waiting to happen.
+
+---
+
+## Sources
+
+- "Parse, don't validate" — Alexis King: https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/
+- exhaustive linter: https://github.com/nishanths/exhaustive
+- Generics constraints: https://go.dev/blog/intro-generics
+- cmp.Ordered: https://pkg.go.dev/cmp

package/dist/skills/programming/references/python/README.md

@@ -0,0 +1,314 @@
+
+# Python Programmer
+
+Modern Python. Type-strict, stack-first, async-correct.
+
+## Philosophy
+
+The type checker is your compiler. Make illegal states unrepresentable. Parse at boundaries. Own resources explicitly. Every function has a contract; the type system enforces it.
+
+## Hard rules
+
+These are deliberate project choices. Violations are always wrong, not "style preferences".
+
+### Tooling
+
+| Category | Use | Never |
+|---|---|---|
+| Package manager | `uv` | pip, poetry, conda, pipenv |
+| Type checker | `basedpyright` (`typeCheckingMode = "all"`) | pyright, mypy |
+| Linter + formatter | `ruff` (`select = ["ALL"]`) | flake8, black, isort, autopep8 |
+| Async runtime | `anyio` | `import asyncio` |
+| Data | `polars` + `duckdb` + `numpy` | pandas |
+| Web framework | FastAPI + Pydantic v2 | Flask, Django REST |
+| ORM | SQLAlchemy 2.x async | Django ORM, Tortoise |
+| HTTP client | [`httpx2`](https://github.com/pydantic/httpx2) | requests, aiohttp, httpx |
+| Testing | `pytest` | unittest |
+| CLI | `typer` + `rich` | argparse, click, fire |
+
+### The iron list
+
+1. **Frozen by default** — `@dataclass(frozen=True, slots=True)`. Pydantic: `model_config = ConfigDict(frozen=True)`. Mutable only when mutation is the documented purpose.
+2. **NewType for distinct IDs** — `UserId = NewType("UserId", int)`. Never pass raw `int` where a branded type exists.
+3. **`match` only for variants, `if` only for booleans** — **NEVER** use `if/elif/else` to discriminate on type (`isinstance`), enum value, or literal variant. `match/case` is mandatory for these — non-negotiable. **ALWAYS** end with `case unreachable: assert_never(unreachable)` — bare `case _: pass` and `case _: raise ValueError` are banned (they silently swallow new variants). `if/else` is fine only for boolean expressions, range checks, and predicate calls that aren't variant discrimination. See "Why `if/elif` on variants is banned" below for examples.
+4. **Protocol over ABC** — `typing.Protocol` for interfaces. ABC only when you need shared method implementation.
+5. **No raw dicts in signatures** — params and returns use `TypedDict`, `dataclass`, or Pydantic model. Internal scratch dicts are fine.
+6. **Parse, don't validate** — constructors produce typed objects or raise. Never pass unvalidated data deeper into the call stack.
+7. **Typed errors** — error types are dataclasses or exceptions with typed fields. Never `raise ValueError("something")` with a bare string. Use union returns when the caller is within 1-2 call levels and must handle the outcome (repository → service). Use exceptions when the error should propagate up many layers to a boundary handler (service → HTTP handler).
+8. **Final for constants** — module-level constants use `Final`. Mutable module globals are a code smell.
+9. **Explicit None** — annotate `-> X | None`. Never return `None` from a function whose signature omits it.
+10. **Context managers for resources** — files, DB connections, HTTP clients, locks. No manual `.close()`.
+11. **No Any, no object** — both are banned as type annotations. `object` erases all structural information (zero callable attributes, zero narrowing). Use `Protocol` (structural typing), `TypeVar` (generic pass-through), explicit union (known variants), or `TypedDict` (dict shapes).
+12. **No cast** — `cast()` is banned. Redesign the types.
+13. **No type: ignore** — fix the type error. The checker is right; you are wrong.
+14. **No broad except** — `except Exception` and `except BaseException` are banned. Catch the **specific** exception you expect. A broad catch swallows bugs you need to see — `KeyError`, `AttributeError`, `TypeError` all vanish silently. If you genuinely need a catch-all at a top-level boundary (CLI entry, HTTP handler), use `# noqa: BROAD_EXCEPT_OK` and log + re-raise.
+
+### Typing and safety
+
+- `basedpyright` in `typeCheckingMode = "all"`. Every public function has full annotations. Internal helpers: annotate return type; parameter types may be inferred.
+- `ruff` with `select = ["ALL"]`. Override specific rules per project in `pyproject.toml`, never globally disable the strict baseline.
+- Every new function must have a `docstring` unless its name + signature makes it completely obvious (e.g. `def full_name(first: str, last: str) -> str:`).
+- Use `X | Y` union syntax (PEP 604), never `Union[X, Y]` or `Optional[X]`.
+
+### Why `object` is banned
+
+`object` pretends to be safe ("it's the top type!") but gives **zero** narrowing and **zero** attributes. Even `Any` is more honest — it admits the boundary is untyped.
+
+```python
+# BANNED
+def process(data: object) -> object: ...
+def store(items: list[object]) -> None: ...
+results: dict[str, object] = {}
+
+# GOOD — Protocol for structural typing
+class Serializable(Protocol):
+    def serialize(self) -> bytes: ...
+def process(data: Serializable) -> ProcessResult: ...
+
+# GOOD — TypeVar for generic pass-through
+def identity[T](x: T) -> T: ...
+def first[T](items: Sequence[T]) -> T: ...
+
+# GOOD — explicit union for known variants
+def parse(raw: str | bytes) -> Document: ...
+```
+
+### Why `if/elif` on variants is banned
+
+`if/elif/else` chains on type, enum, or literal values lose compile-time exhaustiveness. When a new variant is added, nothing warns you. `match/case` + `assert_never` does.
+
+```python
+# BANNED — if/elif for type discrimination
+if isinstance(event, Click):
+    handle_click(event.x, event.y)
+elif isinstance(event, Scroll):
+    handle_scroll(event.delta)
+else:
+    raise ValueError(f"Unknown: {event}")  # runtime bomb
+
+# BANNED — if/elif for enum discrimination
+if status == Status.PENDING:
+    start_review()
+elif status == Status.ACTIVE:
+    continue_processing()
+elif status == Status.CLOSED:
+    archive()
+
+# BANNED — non-exhaustive match (swallows new variants)
+match event:
+    case Click(x, y): handle_click(x, y)
+    case _: pass
+
+# GOOD — exhaustive match with assert_never
+match event:
+    case Click(x=x, y=y):
+        handle_click(x, y)
+    case Scroll(delta=delta):
+        handle_scroll(delta)
+    case unreachable:
+        assert_never(unreachable)
+
+# GOOD — enum match
+match status:
+    case Status.PENDING: start_review()
+    case Status.ACTIVE:  continue_processing()
+    case Status.CLOSED:  archive()
+    case unreachable:    assert_never(unreachable)
+```
+
+`if/else` is fine for boolean conditions and range checks — things that aren't variant discrimination:
+
+```python
+# FINE — boolean, not variant
+if age >= 18:
+    grant_access()
+else:
+    deny_access()
+```
+
+### Why broad `except` is banned
+
+`except Exception` catches **every** non-system exception — `KeyError`, `TypeError`, `AttributeError`, `ValueError` all vanish. You lose the stack trace that would have told you exactly what went wrong. The fix is always to name the exception you expect.
+
+```python
+# BANNED — swallows bugs
+try:
+    result = api.fetch(url)
+except Exception as e:
+    logger.error(e)
+    return None
+
+# BANNED — catch-and-ignore
+try:
+    parse(data)
+except Exception:
+    pass
+
+# GOOD — catch what you expect
+try:
+    result = api.fetch(url)
+except httpx.HTTPStatusError as e:
+    logger.error("API %d: %s", e.response.status_code, e.request.url)
+    return None
+except httpx.ConnectError:
+    raise ServiceUnavailableError(service="api") from None
+
+# GOOD — top-level boundary (only place broad catch is acceptable)
+def main() -> int:  # noqa: BROAD_EXCEPT_OK
+    try:
+        return run()
+    except Exception:
+        logger.exception("unhandled error")
+        return 1
+```
+
+### Async
+
+- `import asyncio` is **BANNED**. Use `import anyio`.
+- For background tasks, use `anyio.create_task_group`. Never fire-and-forget with `asyncio.create_task`.
+- For concurrency gates, use `anyio.CapacityLimiter` (not `asyncio.Semaphore`).
+- Load `async-anyio.md` when writing async code for the full pattern library.
+
+### Data modeling — which container, when
+
+All model fields carry type annotations. No `Any`, no untyped dicts in public APIs.
+Use `polars` + `duckdb` for data. pandas is never the right answer in this stack.
+
+| Situation | Use |
+|---|---|
+| User input, API request/response | `Pydantic BaseModel (frozen=True)` |
+| Internal value object (no I/O) | `@dataclass(frozen=True, slots=True)` |
+| Function with multiple outcomes | Union of frozen dataclasses + `match` |
+| Dict shape for JSON compat / `**kwargs` | `TypedDict` |
+| Fixed constants | `StrEnum` / `IntEnum` |
+| Distinct primitive (UserId vs MovieId) | `NewType` |
+| Contract / capability | `Protocol` |
+| Contract + shared implementation | `ABC` |
+| ORM model (SQLAlchemy) | `Mapped[]` — inherently mutable, `# noqa: MUTABLE_OK` |
+| Config from env vars | `pydantic-settings BaseSettings` |
+
+**The one rule**: data crosses trust boundary → Pydantic. Everything else → dataclass.
+
+Load `data-modeling.md` for the full decision flowchart and comparison matrix.
+
+### When frozen=True does not apply
+
+- **ORM models** — SQLAlchemy `Mapped[]` requires mutation. Use `# noqa: MUTABLE_OK`.
+- **Builder / accumulator** — object exists to be mutated (counter, buffer, state machine). Docstring must explain why.
+- **Pydantic Settings** — tests override fields. Mutable is acceptable.
+
+If you need `# noqa: MUTABLE_OK`, the class docstring must say why mutation is required.
+
+### Libraries
+
+Canonical defaults (override only if `pyproject.toml` explicitly picks something else):
+
+| Domain | Library | Reason |
+|---|---|---|
+| CLI | `typer` | Type-annotated CLI from function sigs |
+| Pretty output | `rich` | Tables, progress, tracebacks, markdown |
+| HTTP client | [`httpx2`](https://github.com/pydantic/httpx2) | Next-gen HTTP client (Pydantic stewardship), HTTP/2, brotli+zstd. Always `httpx2[http2,brotli,zstd]`. See `httpx2-optimization.md` |
+| Validation | `pydantic` v2 | Fast native validator, JSON Schema |
+| Web API | `fastapi` | Async, Pydantic-native, OpenAPI |
+| ORM | `sqlalchemy` 2.x async | `Mapped[]` types, async sessions |
+| DB driver (Postgres) | `asyncpg` (via SQLAlchemy) | Fastest PG driver |
+| AI agents | `pydantic-ai` | Typed deps, structured output |
+| TUI | `textual` | Rich-based, CSS layout, widgets |
+| Logging | `rich.logging.RichHandler` | Pretty; swap to `structlog` in prod |
+
+## pyproject.toml — the one true config
+
+Scaffold a new project with all strict defaults pre-configured:
+
+```bash
+uv run ../../scripts/python/new-project.py myproject
+uv run ../../scripts/python/new-project.py myproject --path ./workspace
+uv run ../../scripts/python/new-project.py myproject --lib   # publishable library
+```
+
+Creates via `uv init`, then injects basedpyright `typeCheckingMode = "all"` + ruff `select = ["ALL"]` + pytest strict. Cross-platform (macOS, Linux, Windows).
+
+For manual setup: `uv init --app myproject`, then load `pyproject-strict.md`.
+
+## PEP 723 — inline script metadata (mandatory for ALL scripts)
+
+Every `.py` script — even throwaway — MUST use PEP 723 inline metadata with the `# ─── How to run ───` comment block. No venv, no `requirements.txt`. The script IS the environment spec. A script without the usage comment block is incomplete.
+
+Scaffold with: `uv run ../../scripts/python/new-script.py <name> --deps "httpx2[http2,brotli,zstd]"` (writes to temp dir by default, `--output` for specific path).
+
+Load `one-liners.md` for full patterns, examples, and anti-patterns.
+
+## Reference loading
+
+Load on demand — not all at once.
+
+| Need | Load |
+|---|---|
+| Full pyproject.toml config | `pyproject-strict.md` |
+| Type patterns (NewType, Final, enums, narrowing) | `type-patterns.md` |
+| Data modeling (container choice, frozen, parse-don't-validate) | `data-modeling.md` |
+| Error handling (typed errors, union returns, exhaustive match) | `error-handling.md` |
+| Async patterns (anyio) | `async-anyio.md` |
+| Data processing (polars / duckdb) | `data-processing.md` |
+| FastAPI + SQLAlchemy stack | `fastapi-stack.md` |
+| Library decision tree | `libraries.md` |
+| **httpx2 optimization** (MUST load for any network code) | `httpx2-optimization.md` |
+| **orjson** (when JSON is in the hot path; FastAPI/Pydantic v2 integration) | `orjson-stack.md` |
+| One-liner scripts (PEP 723) | `one-liners.md` |
+| PydanticAI agents | `pydantic-ai.md` |
+| Textual TUI | `textual-tui.md` |
+
+## httpx2 — mandatory for ALL network requests
+
+Every outgoing HTTP call MUST use [`httpx2`](https://github.com/pydantic/httpx2) (`httpx2[http2,brotli,zstd]`). Never `requests`, never `aiohttp`, never the original `httpx`.
+
+**ALL optimizations are ON by default — not optional, not progressive, not "nice to have".** A bare `httpx2.AsyncClient()` is a bug — treat it like a lint violation. The correct way is the factory pattern in `httpx2-optimization.md` with: HTTP/2 enabled, tuned connection pool (200/40/30s), split timeouts (5/30/10/10), transport retries (3), TCP_NODELAY, follow_redirects, and event hooks for observability.
+
+When writing or reviewing ANY network code, **ALWAYS load `httpx2-optimization.md`** and use the factory pattern verbatim. No exceptions.
+
+## No-excuse audit
+
+Violations caught by `../../scripts/python/check-no-excuse-rules.py`. Run after every edit session.
+
+| Rule ID | Catches | Opt-out |
+|---|---|---|
+| `cast-any` | `cast(Any, ...)` | None — redesign types |
+| `type-ignore` | `# type: ignore` | None — fix the type |
+| `pyright-ignore` | `# pyright: ignore` | None — fix the type |
+| `bare-except` | `except:` with no class | None — name the exception |
+| `silent-except` | `except X: pass` / `except X: ...` | None — handle or re-raise |
+| `no-asyncio` | `import asyncio` | `# noqa: ANYIO_OK` |
+| `no-pandas` | `import pandas` | `# noqa: PANDAS_OK` |
+| `mutable-dataclass` | `@dataclass` without `frozen=True` | `# noqa: MUTABLE_OK` |
+| `missing-slots` | `@dataclass` without `slots=True` | `# noqa: SLOTS_OK` |
+| `raw-dict-return` | `-> dict` in function return type | `# noqa: DICT_OK` |
+| `missing-assert-never` | `match` block without `assert_never` default | `# noqa: MATCH_OK` |
+| `generic-exception` | `raise ValueError("...")` / `raise TypeError("...")` with bare string | `# noqa: GENERIC_ERR_OK` |
+| `no-object` | `object` used as type annotation (param, return, generic arg) | `# noqa: OBJECT_OK` |
+| `if-elif-on-variant` | `if isinstance()`/`if x == Enum.V` chain that should be `match/case` | `# noqa: IF_VARIANT_OK` |
+| `oversized-module` | File exceeds 250 pure LOC (non-blank, non-comment) | `# noqa: SIZE_OK` |
+| `broad-except` | `except Exception` / `except BaseException` (too broad) | `# noqa: BROAD_EXCEPT_OK` |
+
+Fix every violation before declaring work done. basedpyright + ruff strict config catches the rest.
+
+## In tests
+
+Tests are strict too, with these exceptions (already configured in `pyproject.toml` per-file-ignores):
+
+| In tests you may | Why |
+|---|---|
+| Use `assert` | That's how pytest works (`S101` ignored) |
+| Use magic numbers | Test data (`PLR2004` ignored) |
+| Access `_private` members | Testing internals (`SLF001` ignored) |
+| Skip docstrings | Test names are the docs (`D` ignored) |
+| Have unused function args | Fixtures (`ARG` ignored) |
+
+Tests still follow the iron list — frozen dataclasses, typed errors, exhaustive match. If test fixtures need mutable state, use `# noqa: MUTABLE_OK` on the fixture class.
+
+## Existing codebases
+
+When editing an existing file that doesn't follow these rules: **write new code in strict style, don't refactor existing code in the same change.** Mixing feature work with style migration makes reviews harder and bugs likelier.
+
+## Activation
+
+This skill activates whenever you are writing or modifying any `.py` file. Even one-off scripts get the strict treatment — that is the whole point of PEP 723 + uv: production hygiene with throwaway ergonomics.