@thedecipherist/claude-packs 0.0.0-stage → 1.1.0

package/packs/postgres/pack.json

@@ -0,0 +1,48 @@
+{
+  "name": "postgres",
+  "version": "1.0.0",
+  "description": "PostgreSQL: migrations that never stop traffic, values always bound, types that say what they hold, and no database wiped by mistake.",
+  "type": "stock",
+  "author": "claude-packs",
+  "license": "MIT",
+  "homepage": "https://github.com/TheDecipherist/claude-packs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TheDecipherist/claude-packs.git",
+    "directory": "packs/postgres"
+  },
+  "keywords": [
+    "postgres",
+    "postgresql",
+    "sql",
+    "migrations"
+  ],
+  "engines": {
+    "claude-packs": ">=1.1.0"
+  },
+  "concepts": {
+    "postgres": [
+      "**/*.sql",
+      "**/*.prisma"
+    ]
+  },
+  "optIn": [
+    "checks/pg-index-concurrently.json",
+    "checks/pg-fk-not-valid.json",
+    "checks/pg-timestamptz.json"
+  ],
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/db-wipe-guard.mjs\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/packs/postgres/rules/postgres-migrations-never-stop-traffic.md

@@ -0,0 +1,28 @@
+---
+paths:
+  - "**/*.sql"
+  - "**/migrations/**"
+  - "**/migrate/**"
+  - "**/*.prisma"
+---
+
+# A migration never stops traffic
+
+A new table is free. A live table is not: a lock held for one long statement queues every query behind it.
+
+<constraints>
+Always do:
+- On a live table, build an index with `CONCURRENTLY`, outside a transaction. Check how the migration tool leaves its transaction first.
+- Add a foreign key or a check `NOT VALID`, then `VALIDATE` it in a later transaction.
+- Add a required column in three steps: nullable, backfill in batches, then tighten. The `postgres-safe-migration` skill walks it.
+- Change a column by expand and contract: a new column, both written, a backfill, then the old one dropped.
+- Set `lock_timeout` on a migration that takes a strong lock.
+
+Never do:
+- Add a column with a volatile default (`gen_random_uuid()`, `clock_timestamp()`, `random()`, `nextval()`) to a live table. `now()` and a constant are safe.
+- Add a `NOT NULL` column with no default to a table with rows.
+- Run a wipe (`prisma migrate reset`, `db push --force-reset`, `drizzle-kit push --force`, `db:drop`, `flush`, `dropdb`) on anything but a local database. `db-wipe-guard` refuses it.
+</constraints>
+
+## Check
+`pg-no-volatile-default`, `pg-no-required-column`, `pg-concurrently-in-txn`, and the hook `db-wipe-guard`. On a project with large live tables, name these in `"enable"`: `checks/pg-index-concurrently.json`, `checks/pg-fk-not-valid.json`. A line that is right anyway says so at its end: `-- pg: allow <reason>`.

package/packs/postgres/rules/postgres-one-pool-per-process.md

@@ -0,0 +1,21 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.py"
+  - "**/*.go"
+  - "**/*.rs"
+---
+
+# One pool per process, in one place
+
+<constraints>
+Always do:
+- Make one pool per process, in one module, and hand it to everything that needs it.
+- Size it so every process together stays under `max_connections`, with room for a migration.
+- Give back every client you take, on every path.
+- Keep a transaction short, and do no network call inside one.
+
+Never do:
+- Open a connection per request.
+- Use session state (`SET`, `LISTEN`, session advisory locks, `PREPARE`) through PgBouncer in transaction mode.
+</constraints>

package/packs/postgres/rules/postgres-queries-are-null-safe-and-bounded.md

@@ -0,0 +1,26 @@
+---
+paths:
+  - "**/*.sql"
+  - "**/*.ts"
+  - "**/*.py"
+  - "**/*.go"
+  - "**/*.rs"
+---
+
+# A query survives NULLs, and reads a bounded amount
+
+<constraints>
+Always do:
+- Write `NOT EXISTS` in place of `NOT IN (SELECT ...)`: one NULL in the subquery returns no rows at all.
+- Page with a key (`WHERE id > $1 ORDER BY id LIMIT n`). `OFFSET` still computes every row it skips.
+- Index a foreign key's referencing column when rows are looked up or deleted through it. Postgres does not do it for you.
+- Name the columns a query needs in code that ships.
+- Read `EXPLAIN (ANALYZE, BUFFERS)` on a query a hot path runs.
+
+Never do:
+- Run a query with no `LIMIT` on a table that grows, from a request.
+- Use `BETWEEN` on a `timestamptz`: write `>=` and `<`.
+</constraints>
+
+## Check
+`pg-not-exists`.

package/packs/postgres/rules/postgres-types-say-what-they-hold.md

@@ -0,0 +1,22 @@
+---
+paths:
+  - "**/*.sql"
+  - "**/*.prisma"
+---
+
+# A column's type says what it holds
+
+<constraints>
+Always do:
+- Use `timestamptz` for a moment in time, and `timestamp` only for a wall-clock time with no zone. Prisma and Rails default to `timestamp`: say `@db.Timestamptz` or `timestamptz` yourself.
+- Use `text`, with a `CHECK` where a length is a real rule.
+- Use `GENERATED ALWAYS AS IDENTITY` in place of `serial`.
+- Use `numeric`, or an integer count of the smallest unit, for money.
+
+Never do:
+- Use `money`, or a float for an amount.
+- Use `char(n)`.
+</constraints>
+
+## Check
+`pg-no-money`, `pg-no-float-money`. `checks/pg-timestamptz.json` is opt-in, through `"enable"`.

package/packs/postgres/rules/postgres-values-are-bound.md

@@ -0,0 +1,130 @@
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "bin/claude-packs.mjs"
+  - "lib/backup.mjs"
+  - "lib/build-queue.mjs"
+  - "lib/claude-md.mjs"
+  - "lib/config-cli.mjs"
+  - "lib/configs.mjs"
+  - "lib/coverage.mjs"
+  - "lib/custom-packs.mjs"
+  - "lib/doctor.mjs"
+  - "lib/fix-plan.mjs"
+  - "lib/git-tokens.mjs"
+  - "lib/global.mjs"
+  - "lib/hook-proof.mjs"
+  - "lib/hook-timing.mjs"
+  - "lib/hover-gate.mjs"
+  - "lib/kit-command.mjs"
+  - "lib/kit-lock.mjs"
+  - "lib/layout.mjs"
+  - "lib/logs.mjs"
+  - "lib/manifest.mjs"
+  - "lib/new.mjs"
+  - "lib/once-only-report.mjs"
+  - "lib/pack-manifest.mjs"
+  - "lib/packs.mjs"
+  - "lib/planner.mjs"
+  - "lib/repeats.mjs"
+  - "lib/repo-weight.mjs"
+  - "lib/rule-tests.mjs"
+  - "lib/rules.mjs"
+  - "lib/scan-detect.mjs"
+  - "lib/scan.mjs"
+  - "lib/selftest-cache.mjs"
+  - "lib/settings.mjs"
+  - "lib/shape-cli.mjs"
+  - "lib/shape.mjs"
+  - "lib/suggest.mjs"
+  - "lib/switches.mjs"
+  - "lib/symmetry-doctor.mjs"
+  - "lib/sync.mjs"
+  - "scripts/test-changed.mjs"
+  - "test/audio-packs.test.mjs"
+  - "test/base-laws.test.mjs"
+  - "test/base-neutral.test.mjs"
+  - "test/check-speed.test.mjs"
+  - "test/configs.test.mjs"
+  - "test/configurations.test.mjs"
+  - "test/content-sites.test.mjs"
+  - "test/cpp-pack.test.mjs"
+  - "test/custom-packs.test.mjs"
+  - "test/doctor-cache.test.mjs"
+  - "test/doctor-timeout.test.mjs"
+  - "test/every-language.test.mjs"
+  - "test/example-line.test.mjs"
+  - "test/file-size.test.mjs"
+  - "test/fix-plan.test.mjs"
+  - "test/frame-bench.test.mjs"
+  - "test/fresh-tmp.mjs"
+  - "test/full-stack.test.mjs"
+  - "test/gitignore.test.mjs"
+  - "test/global.test.mjs"
+  - "test/hook-proof.test.mjs"
+  - "test/hook-timing.test.mjs"
+  - "test/house.test.mjs"
+  - "test/hover.test.mjs"
+  - "test/install-fixes.test.mjs"
+  - "test/install.test.mjs"
+  - "test/instances.test.mjs"
+  - "test/kf-build-laws.test.mjs"
+  - "test/kf-fail-open.test.mjs"
+  - "test/kf-new-projects.test.mjs"
+  - "test/kf-refusals.test.mjs"
+  - "test/kit-cli.mjs"
+  - "test/kit-guards.test.mjs"
+  - "test/kit-lock.test.mjs"
+  - "test/layout-owned.test.mjs"
+  - "test/lock-release.test.mjs"
+  - "test/logging.test.mjs"
+  - "test/lookup.test.mjs"
+  - "test/micro.test.mjs"
+  - "test/names-sweep.test.mjs"
+  - "test/new.test.mjs"
+  - "test/no-personal-name.test.mjs"
+  - "test/noop.test.mjs"
+  - "test/npx-name.test.mjs"
+  - "test/once-only.test.mjs"
+  - "test/other-projects.test.mjs"
+  - "test/pack-manifest.test.mjs"
+  - "test/readme.test.mjs"
+  - "test/review-packs.test.mjs"
+  - "test/routes.test.mjs"
+  - "test/rule-tests.test.mjs"
+  - "test/rust-pack.test.mjs"
+  - "test/scan.test.mjs"
+  - "test/shape.test.mjs"
+  - "test/stored-text.test.mjs"
+  - "test/structure.test.mjs"
+  - "test/sub37-wb.test.mjs"
+  - "test/symmetry.test.mjs"
+  - "test/test-changed.test.mjs"
+  - "test/ui-craft.test.mjs"
+  - "test/ui-depth.test.mjs"
+  - "test/what-the-kit-finds.test.mjs"
+  - "test/worktrees.test.mjs"
+  - "test/writing.test.mjs"
+  - "**/*.py"
+  - "**/*.go"
+  - "**/*.rs"
+  - "**/*.rb"
+---
+
+# A value is bound, never written into the SQL text
+
+<constraints>
+Always do:
+- Pass every value as a parameter: `$1`, `%s`, or the driver's tagged form (`` sql`...` ``, `$queryRaw`).
+- Take a table or column name from an allow-list in the code, and quote it with the driver's identifier helper.
+- Connect read-only work as a database role that can only read. A wrapper that promises read-only is no boundary.
+
+Never do:
+- Build SQL from a value with a template string, an f-string, `%`, `.format`, `Sprintf` or `format!`.
+- Trust a value because it came from your own database or a form with validation.
+</constraints>
+
+## Check
+`pg-bind-values`. A line that is right anyway says so: `// pg: allow <reason>`.

package/packs/postgres/skills/postgres-safe-migration/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: postgres-safe-migration
+description: Use when writing a migration for a table that holds data, when changing a column, adding a required column, an index or a constraint, or when a pg- check refuses a migration.
+---
+
+# Change a live Postgres table (one job: the change lands, and no query waits for it)
+
+<constraints>
+Always do:
+1. Find out how big the table is and how busy, or ask. A new or empty table needs none of this.
+2. Find out how the migration tool leaves a transaction, before writing `CONCURRENTLY`. Each has its own way:
+   | Tool | How |
+   |---|---|
+   | Rails | `disable_ddl_transaction!` |
+   | Django | `atomic = False` |
+   | Diesel | `run_in_transaction = false` in `metadata.toml` |
+   | goose | `-- +goose NO TRANSACTION` |
+   | dbmate | `-- migrate:up transaction:false` |
+   | sqlx | `-- no-transaction` on the first line |
+   | Alembic | `autocommit_block()` |
+   | Knex | `exports.config = { transaction: false }` |
+   | node-pg-migrate | `pgm.noTransaction()` |
+
+   Drizzle runs every pending migration in one transaction: take the index out of its migrations and run it apart.
+3. Add a required column:
+   ```sql
+   ALTER TABLE t ADD COLUMN owner_id bigint;              -- 1. nullable, instant
+   -- 2. the code writes it, and a backfill runs in batches
+   ALTER TABLE t ADD CONSTRAINT t_owner CHECK (owner_id IS NOT NULL) NOT VALID;
+   ALTER TABLE t VALIDATE CONSTRAINT t_owner;             -- 3. a later transaction, no write lock
+   ALTER TABLE t ALTER COLUMN owner_id SET NOT NULL;      -- 4. the valid check skips the scan
+   ALTER TABLE t DROP CONSTRAINT t_owner;
+   ```
+4. Add a foreign key: `ADD CONSTRAINT ... NOT VALID`, then `VALIDATE CONSTRAINT` in a later transaction. In one transaction it gains nothing.
+5. Add a unique constraint: `CREATE UNIQUE INDEX CONCURRENTLY`, then `ADD CONSTRAINT ... UNIQUE USING INDEX`.
+6. Change a type: check first whether it rewrites. `varchar` to `text` does not. Most others do: add a new column, write both, backfill, switch reads, drop the old one.
+7. A failed `CONCURRENTLY` leaves an invalid index: drop it, then build it again.
+8. Set a short `lock_timeout` on a statement that takes a strong lock, and retry it.
+9. Deploy the code that can read both shapes first, and drop what is old only after nothing reads it.
+
+Never do:
+- Backfill a large table in one `UPDATE`.
+- Rename a column in one step while old code still runs.
+- Refuse `now()` or a constant default as unsafe: since PostgreSQL 11 both are instant.
+</constraints>

package/packs/python/checks/py-no-bare-except.json

@@ -0,0 +1,18 @@
+{
+  "id": "py-no-bare-except",
+  "why": "A bare except also catches KeyboardInterrupt and SystemExit, and hides every bug in the block. Catch the exception you expect, by name.",
+  "rule": ".claude/rules/python-errors-and-resources.md",
+  "concepts": [
+    "python"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/venv/**"
+  ],
+  "pattern": "^\\s*except\\s*:",
+  "flags": "m",
+  "bad": "try:\n    run()\nexcept:\n    log()",
+  "good": "try:\n    run()\nexcept ValueError:\n    log()"
+}

package/packs/python/checks/py-no-eval.json

@@ -0,0 +1,18 @@
+{
+  "id": "py-no-eval",
+  "why": "eval and exec run whatever text they are given.",
+  "rule": ".claude/rules/python-errors-and-resources.md",
+  "concepts": [
+    "python"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/venv/**"
+  ],
+  "pattern": "^[^#\\n]*(?<![\\w.])(?:eval|exec)\\(",
+  "flags": "m",
+  "bad": "value = eval(text)",
+  "good": "value = json.loads(text)\nmodel.eval()"
+}

package/packs/python/checks/py-no-mutable-default.json

@@ -0,0 +1,18 @@
+{
+  "id": "py-no-mutable-default",
+  "why": "A mutable default is made once and shared by every call, so one call changes the next.",
+  "rule": ".claude/rules/python-errors-and-resources.md",
+  "concepts": [
+    "python"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/venv/**"
+  ],
+  "pattern": "^\\s*(?:async\\s+)?def\\s+\\w+\\([^)]*=\\s*(?:\\[\\s*\\]|\\{\\s*\\}|set\\(\\)|dict\\(\\)|list\\(\\))",
+  "flags": "m",
+  "bad": "def add(row, rows=[]):\n    rows.append(row)",
+  "good": "def add(row, rows=None):\n    rows = rows or []"
+}

package/packs/python/checks/py-no-shell-true.json

@@ -0,0 +1,18 @@
+{
+  "id": "py-no-shell-true",
+  "why": "shell=True hands a string to a shell, so any value in it can run a command. Pass a list of arguments.",
+  "rule": ".claude/rules/python-errors-and-resources.md",
+  "concepts": [
+    "python"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/venv/**"
+  ],
+  "pattern": "\\bsubprocess\\.\\w+\\([^)\\n]*\\bshell\\s*=\\s*True",
+  "flags": "m",
+  "bad": "subprocess.run(f\"ls {path}\", shell=True)",
+  "good": "subprocess.run([\"ls\", path], check=True)"
+}

package/packs/python/checks/py-no-star-import.json

@@ -0,0 +1,18 @@
+{
+  "id": "py-no-star-import",
+  "why": "A star import hides where a name came from, and any new name in that module can silently replace one of yours.",
+  "rule": ".claude/rules/python-errors-and-resources.md",
+  "concepts": [
+    "python"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/venv/**"
+  ],
+  "pattern": "^from\\s+\\S+\\s+import\\s+\\*",
+  "flags": "m",
+  "bad": "from helpers import *",
+  "good": "from helpers import load, save"
+}

package/packs/python/checks/py-no-swallowed-exception.json

@@ -0,0 +1,18 @@
+{
+  "id": "py-no-swallowed-exception",
+  "why": "An exception caught and dropped is a failure nobody will ever see. Handle it, log it, or let it rise.",
+  "rule": ".claude/rules/python-errors-and-resources.md",
+  "concepts": [
+    "python"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/venv/**"
+  ],
+  "pattern": "^\\s*except\\b[^\\n]*:\\s*(?:#[^\\n]*)?\\n\\s*pass\\b|^\\s*except\\b(?:\\s+\\(?(?:Exception|BaseException)\\b[^\\n:]*)?:[ \\t]*(?:pass|continue|return\\b(?:[ \\t]+(?:None|True|False|0|1|\\[\\]|\\{\\}|\"\"|''))?)[ \\t]*(?:#[^\\n]*)?$",
+  "flags": "m",
+  "bad": "try:\n    run()\nexcept ValueError:\n    pass\ntry:\n    run()\nexcept Exception: return 0",
+  "good": "try:\n    run()\nexcept ValueError as e:\n    log.warning(e)\ntry:\n    run()\nexcept FileNotFoundError: return None"
+}

package/packs/python/checks/py-none-by-is.json

@@ -0,0 +1,18 @@
+{
+  "id": "py-none-by-is",
+  "why": "`== None` calls __eq__, which a class can change. `is None` asks the real question.",
+  "rule": ".claude/rules/python-errors-and-resources.md",
+  "concepts": [
+    "python"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/venv/**"
+  ],
+  "pattern": "^[^#\\n]*[=!]=\\s*None\\b",
+  "flags": "m",
+  "bad": "if value == None:\n    run()",
+  "good": "if value is None:\n    run()"
+}

package/packs/python/checks/py-open-with-with.json

@@ -0,0 +1,18 @@
+{
+  "id": "py-open-with-with",
+  "why": "A file opened without `with` stays open when anything raises.",
+  "rule": ".claude/rules/python-errors-and-resources.md",
+  "concepts": [
+    "python"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/venv/**"
+  ],
+  "pattern": "^\\s*\\w+\\s*=\\s*open\\(|^(?!\\s*with\\b)[^#\\n]*\\b(?:json\\.load\\(\\s*open\\(|open\\([^\\n]*\\)\\s*\\.\\s*(?:read|readlines|write)\\()",
+  "flags": "m",
+  "bad": "f = open(path)\ndata = f.read()\nrows = json.load(open(path))",
+  "good": "with open(path) as f:\n    data = f.read()"
+}

package/packs/python/checks/py-requests-timeout.json

@@ -0,0 +1,18 @@
+{
+  "id": "py-requests-timeout",
+  "why": "requests waits forever by default: one slow server hangs the program.",
+  "rule": ".claude/rules/python-errors-and-resources.md",
+  "concepts": [
+    "python"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/venv/**"
+  ],
+  "pattern": "\\brequests\\.(?:get|post|put|patch|delete|head)\\((?![^)\\n]*\\btimeout\\s*=)",
+  "flags": "m",
+  "bad": "r = requests.get(url)",
+  "good": "r = requests.get(url, timeout=10)"
+}

package/packs/python/checks/py-subprocess-output-checked.json

@@ -0,0 +1,18 @@
+{
+  "id": "py-subprocess-output-checked",
+  "why": "Reading .stdout straight off subprocess.run loses the return code, so a failed tool looks like an empty result and a gate goes green. A tool's failure and nothing to report must never give the same output.",
+  "rule": ".claude/rules/python-errors-and-resources.md",
+  "concepts": [
+    "python"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/venv/**"
+  ],
+  "pattern": "^[^#\\n]*\\bsubprocess\\.run\\((?![^\\n]*\\bcheck\\s*=\\s*True)[^\\n]*\\)\\s*\\.\\s*(?:stdout|stderr)\\b",
+  "flags": "m",
+  "bad": "names = subprocess.run([\"git\", \"diff\"], capture_output=True, text=True).stdout.split()",
+  "good": "names = subprocess.run([\"git\", \"diff\"], capture_output=True, text=True, check=True).stdout.split()\nr = subprocess.run(cmd)\nif r.returncode:\n    fail()"
+}

package/packs/python/checks/py-yaml-safe-load.json

@@ -0,0 +1,18 @@
+{
+  "id": "py-yaml-safe-load",
+  "why": "yaml.load can build arbitrary objects from the text it reads.",
+  "rule": ".claude/rules/python-errors-and-resources.md",
+  "concepts": [
+    "python"
+  ],
+  "globs": [],
+  "exclude": [
+    "**/node_modules/**",
+    "**/.venv/**",
+    "**/venv/**"
+  ],
+  "pattern": "\\byaml\\.load\\((?![^)\\n]*Loader\\s*=\\s*yaml\\.SafeLoader)",
+  "flags": "m",
+  "bad": "data = yaml.load(text)",
+  "good": "data = yaml.safe_load(text)"
+}

package/packs/python/pack.json

@@ -0,0 +1,26 @@
+{
+  "name": "python",
+  "version": "1.0.0",
+  "description": "Python projects: what is repeated becomes a template in the forms Python has for it, errors are handled where they can be, resources are closed, subprocess and network calls are safe.",
+  "type": "stock",
+  "author": "claude-packs",
+  "license": "MIT",
+  "homepage": "https://github.com/TheDecipherist/claude-packs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TheDecipherist/claude-packs.git",
+    "directory": "packs/python"
+  },
+  "keywords": [
+    "python"
+  ],
+  "engines": {
+    "claude-packs": ">=0.25.0"
+  },
+  "concepts": {
+    "python": [
+      "**/*.py",
+      "**/*.pyi"
+    ]
+  }
+}

package/packs/python/rules/python-errors-and-resources.md

@@ -0,0 +1,26 @@
+---
+# concepts: python
+paths:
+  - "placeholder"
+---
+
+# Errors are handled where something can be done; every resource closes itself
+
+<constraints>
+Always do:
+- Catch the exception you expect, by name, where something can be done about it. Otherwise let it rise.
+- Open files, sockets and locks with `with`.
+- Give every network call a timeout.
+- Pass `subprocess` a list of arguments, with `check=True` or a read of its return code: a tool's failure and "nothing to report" must never give the same output.
+- Compare with `None` by `is`.
+- Default a mutable argument to `None` and build it in the function.
+- Load YAML with `yaml.safe_load`.
+
+Never do:
+- Write a bare `except:`, or `except ...: pass`.
+- Use `shell=True`, `eval` or `exec` on text that came from outside.
+- Import with `*`.
+</constraints>
+
+## Check
+`py-no-bare-except`, `py-subprocess-output-checked`, `py-no-swallowed-exception`, `py-no-mutable-default`, `py-no-shell-true`, `py-open-with-with`, `py-none-by-is`, `py-no-eval`, `py-no-star-import`, `py-requests-timeout`, `py-yaml-safe-load`.

package/packs/python/rules/python-repeats-become-templates.md

@@ -0,0 +1,27 @@
+---
+# concepts: python
+paths:
+  - "placeholder"
+---
+
+# Anything repeated in Python becomes a template: pick the form that fits the repeat
+
+<constraints>
+Always do:
+- Match the repeat to its form:
+  - A block with the same statements and other names: one function, with what differs as its parameters. `template-law` and `scan` list what differs.
+  - The same set-up and tear-down around different work: a context manager.
+  - The same wrapping around many functions (retry, timing, logging): a decorator.
+  - The same fields passed around together: a `dataclass`.
+  - One call repeated with other arguments: a list of rows and one loop.
+  - Classes alike except for a few values: class attributes on one base class. Except for a few methods: a base class or a `Protocol`, each kind holding only what is its own.
+  - A script copied to start the next one: one module both import, with `if __name__ == "__main__":` in each.
+- Keep shared code in a package the scripts import, not beside them.
+
+Never do:
+- Copy a file to change a few lines, or keep a package and a loose copy of the same module side by side.
+- Add a flag parameter to merge two things that are different.
+</constraints>
+
+## Check
+`template-law` refuses a new copy, a near copy, or a function the repo already has. The `python-extract-template` skill walks the change.

package/packs/python/skills/python-extract-template/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: python-extract-template
+description: Use when template-law refuses Python code, when scan lists repeated Python, or when copying a Python file, class or block to change it.
+---
+
+# Extract a Python repeat into one template (one job: pick the Python form, and move every copy to it)
+
+Follow `make-it-a-template`. This skill is its Python forms.
+
+<constraints>
+Always do:
+1. A repeated block: one function, what differs as parameters, keyword-only where a call would read badly.
+2. The same set-up and tear-down: a context manager.
+   ```python
+   @contextmanager
+   def timed(label):
+       start = perf_counter()
+       yield
+       log.info("%s took %.2fs", label, perf_counter() - start)
+   ```
+3. The same wrapping around many functions: a decorator, with `functools.wraps`.
+4. One call with other arguments: rows and one loop.
+   ```python
+   ROWS = [("--host", "localhost"), ("--port", 8080)]
+   for flag, default in ROWS:
+       parser.add_argument(flag, default=default)
+   ```
+5. Fields that travel together: a `dataclass(frozen=True)`.
+6. A whole file duplicated (a script beside a package): keep the package, and make the script import it.
+7. Run what the change reaches. Then search for the old names: none is left.
+
+Never do:
+- Share through a module-level mutable value.
+- Hide two different behaviours behind one flag.
+</constraints>