coding-os 0.3.2__py3-none-any.whl

core/skills/shell-scripting/scripts/lint_script.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# lint_script.sh — PURPOSE: check a script against the seven non-negotiables.
+# INPUT: one or more script paths (*.sh / *.py). OUTPUT: findings on stderr,
+# "<n> issue(s)" result on stdout; exit 1 if any issue. DEPS: grep, bash,
+# and ShellCheck when available. NOTES: heuristic and fail-closed; a clean
+# pass is necessary not sufficient. Spec: docs/playbooks/skill-authoring.md.
+set -euo pipefail
+IFS=$'\n\t'
+
+log() { printf '%s\n' "$*" >&2; }
+usage() { echo "usage: $0 <script> [<script> ...]" >&2; exit 2; }
+[[ $# -ge 1 ]] || usage
+
+issues=0
+
+flag() { log "  ✗ $1"; issues=$((issues + 1)); }
+
+# NOTE: grep the file directly, never a "$(cat)" here-string — large
+# here-strings deadlock under this bash (see bash-heredoc-deadlock.md).
+check_bash() {
+  local f="$1"
+  head -1 "$f" | grep -qE '^#!.*(bash|sh)' || flag "$f: missing shebang"
+  grep -qE 'set -[a-z]*e[a-z]* ' "$f" || flag "$f: no 'set -euo pipefail'"
+  grep -q 'trap ' "$f" || log "  · $f: no trap (ok if no temp state)"
+  if grep -nE '(/Users/[A-Za-z]|/home/[a-z])' "$f" | grep -qvE '^[0-9]+:[[:space:]]*#'; then
+    flag "$f: hardcoded absolute home path — take a flag instead"
+  fi
+  if command -v shellcheck >/dev/null 2>&1; then
+    shellcheck -S warning "$f" >/dev/null 2>&1 || flag "$f: shellcheck warnings (run: shellcheck $f)"
+  fi
+}
+
+check_python() {
+  local f="$1"
+  grep -q 'argparse' "$f" || grep -q 'sys.argv' "$f" \
+    || flag "$f: no argument parsing (argparse/sys.argv)"
+  if grep -nE "['\"](/Users/[A-Za-z]|/home/[a-z])" "$f" | grep -qvE '^[0-9]+:[[:space:]]*#'; then
+    flag "$f: hardcoded absolute home path — take a flag instead"
+  fi
+}
+
+for f in "$@"; do
+  [[ -f "$f" ]] || { flag "$f: not a file"; continue; }
+  log "checking $f"
+  case "$f" in
+    *.sh) check_bash "$f" ;;
+    *.py) check_python "$f" ;;
+    *) log "  · $f: unknown type, skipped" ;;
+  esac
+done
+
+printf '%d issue(s)\n' "$issues"
+[[ "$issues" -eq 0 ]]

core/skills/shell-scripting/scripts/new_script.py

@@ -0,0 +1,131 @@
+"""Scaffold a production-grade Bash or Python script skeleton.
+
+PURPOSE:      Emit a script that already satisfies the seven non-negotiables
+              (strict mode, trap, arg-parsing, progress, parseable result) so
+              the agent fills logic instead of re-deriving boilerplate.
+INPUT:        --lang bash|python  (required) · --name <snake_case> (required)
+              [--root <dir>]      target dir, default `scripts` (consumer-relative)
+              [--force]           overwrite an existing file
+OUTPUT:       One file: <root>/<name>.{sh,py}. Prints the path on stdout.
+DEPENDENCIES: stdlib only.
+NOTES:        Idempotent — refuses to overwrite without --force. The emitted
+              script is itself lint-clean against lint_script.sh. Spec:
+              docs/playbooks/skill-authoring.md § scripts contract.
+"""
+
+from __future__ import annotations
+
+import argparse
+import stat
+import sys
+from pathlib import Path
+
+BASH_TEMPLATE = """\
+#!/usr/bin/env bash
+# {name}.sh — PURPOSE: <one line> / INPUT: <flags> / OUTPUT: <result> / DEPS: <bins> / NOTES: <gotchas>
+set -euo pipefail
+IFS=$'\\n\\t'
+
+_tmp=""
+cleanup() {{ [[ -n "$_tmp" ]] && rm -f "$_tmp"; }}
+trap cleanup EXIT
+
+log() {{ printf '%s\\n' "$*" >&2; }}            # narration -> stderr
+usage() {{ echo "usage: $0 --input <path> [--dry-run]" >&2; exit 2; }}
+
+input=""
+dry_run=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --input)   input="${{2:?--input needs a value}}"; shift 2 ;;
+    --dry-run) dry_run=1; shift ;;
+    -h|--help) usage ;;
+    *) echo "unknown arg: $1" >&2; usage ;;
+  esac
+done
+[[ -n "$input" ]] || {{ echo "error: --input is required" >&2; usage; }}
+
+log "[1/1] working on $input (dry_run=$dry_run)..."
+# TODO: real work here. Fail-closed: let set -e abort on any error.
+
+printf '{{"ok":true,"input":"%s"}}\\n' "$input"   # result -> stdout, parseable
+"""
+
+PYTHON_TEMPLATE = '''\
+"""{name}.py — PURPOSE: <one line>.
+
+INPUT:        --input <path> (required) [--dry-run]
+OUTPUT:       JSON result on stdout; progress on stderr.
+DEPENDENCIES: stdlib only.
+NOTES:        Idempotent; fail-closed (non-zero exit on any unmet precondition).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def run(input_path: Path, *, dry_run: bool, log) -> dict:
+    log(f"[1/1] working on {{input_path}} (dry_run={{dry_run}})...")
+    if not input_path.exists():
+        raise FileNotFoundError(input_path)
+    # TODO: real work here.
+    return {{"ok": True, "input": str(input_path)}}
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\\n")[0])
+    parser.add_argument("--input", required=True, type=Path)
+    parser.add_argument("--dry-run", action="store_true")
+    args = parser.parse_args(argv)
+
+    def log(msg: str) -> None:
+        print(msg, file=sys.stderr)
+
+    result = run(args.input, dry_run=args.dry_run, log=log)
+    print(json.dumps(result))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))
+'''
+
+
+def build(lang: str, name: str) -> tuple[str, str]:
+    if lang == "bash":
+        return f"{name}.sh", BASH_TEMPLATE.format(name=name)
+    return f"{name}.py", PYTHON_TEMPLATE.format(name=name)
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("--lang", required=True, choices=("bash", "python"))
+    parser.add_argument("--name", required=True)
+    parser.add_argument("--root", default="scripts", type=Path)
+    parser.add_argument("--force", action="store_true")
+    args = parser.parse_args(argv)
+
+    if not args.name.replace("_", "").isalnum():
+        print(f"error: --name must be snake_case alnum, got {args.name!r}", file=sys.stderr)
+        return 2
+
+    filename, content = build(args.lang, args.name)
+    args.root.mkdir(parents=True, exist_ok=True)
+    target = args.root / filename
+    if target.exists() and not args.force:
+        print(f"error: {target} exists (use --force)", file=sys.stderr)
+        return 1
+
+    target.write_text(content, encoding="utf-8")
+    if args.lang == "bash":
+        target.chmod(target.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    print(str(target))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

core/skills/shell-scripting/versions.json

@@ -0,0 +1,23 @@
+{
+  "shellcheck": {
+    "ecosystem": "github",
+    "package": "koalaman/shellcheck",
+    "version": "0.11.0",
+    "source": "https://github.com/koalaman/shellcheck/releases",
+    "checked": "2026-06-05"
+  },
+  "shfmt": {
+    "ecosystem": "github",
+    "package": "mvdan/sh",
+    "version": "3.13.1",
+    "source": "https://github.com/mvdan/sh/releases",
+    "checked": "2026-06-05"
+  },
+  "python": {
+    "ecosystem": "endoflife",
+    "package": "python",
+    "version": "3.14.5",
+    "source": "https://endoflife.date/python",
+    "checked": "2026-06-05"
+  }
+}

core/skills/sql-authoring/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: sql-authoring
+tier: architecture
+domain: [backend, data]
+description: Write correct, fast, injection-proof SQL queries — SELECT/INSERT/UPDATE/DELETE, joins, CTEs, window functions, pagination, upserts. Use when writing or reviewing any query, reading an EXPLAIN plan, fixing an N+1, choosing keyset vs offset pagination, or porting SQL between PostgreSQL and MySQL. Covers parameterization (never string-build SQL), set-based thinking, index-aware querying, and plan reading. Triggers — "write a query", "this query is slow", "EXPLAIN", "N+1", "SQL", "optimize the query", "join", "pagination". Pairs with db-design (schema + index DESIGN — this skill is query CRAFT), security-web (injection), backend-fundamentals (data access layer).
+globs: ""
+paths: []
+last_reviewed: "2026-06-04"
+versions_ref: versions.json
+---
+
+# SQL Authoring
+
+A query is correct, fast, and safe — in that order, none optional. Schema and index *design* belong to [db-design](../db-design/SKILL.md); this skill is the *query* craft: how to express intent so the planner picks an index, how to read the plan when it doesn't, and how to never hand an attacker a string-built statement.
+
+> Read an EXPLAIN plan without eyeballing it:
+> `psql -c 'EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) <query>' | python3 scripts/analyze_plan.py`
+
+## Always parameterize — no exceptions
+
+```python
+# Wrong — SQL injection; one apostrophe in `name` and the query breaks or leaks
+cur.execute(f"SELECT * FROM users WHERE name = '{name}'")
+
+# Correct — the driver binds; the value never touches the SQL text
+cur.execute("SELECT * FROM users WHERE name = %s", (name,))
+```
+
+String-built SQL is the #1 OWASP injection vector — the server-side rules are owned by [security-web](../security-web/SKILL.md). The query-craft rule: **values are always bind parameters; only identifiers you control (validated against an allow-list) are ever interpolated.** An ORM gives you this for free until you reach for `raw()` — then it's on you.
+
+## Think in sets, not rows
+
+```sql
+-- Wrong — N+1: one query per order, 1000 orders = 1001 round trips
+SELECT id FROM orders WHERE user_id = $1;          -- then, per row:
+SELECT * FROM line_items WHERE order_id = $1;
+
+-- Correct — one query, the join does the work
+SELECT o.id, li.*
+FROM orders o
+JOIN line_items li ON li.order_id = o.id
+WHERE o.user_id = $1;
+```
+
+N+1 is the most common real-world slowness. It hides behind ORM lazy-loading — `for order in orders: order.items` issues a query per iteration. Fix with a join, a `prefetch`/`selectinload`, or an `IN (...)` batch. Full recipes → [references/query-patterns.md](references/query-patterns.md).
+
+## Index-aware querying (the query's half of the contract)
+
+Index *design* is db-design's job; using one is yours. A query defeats its own index when it:
+
+- wraps the indexed column in a function: `WHERE lower(email) = $1` skips an index on `email` (needs an index on `lower(email)`);
+- leads with a wildcard: `LIKE '%foo'` cannot use a b-tree;
+- mismatches type: `WHERE id = '42'` (text vs int) may force a cast + seq scan;
+- `OR`s across columns the planner can't combine — often better as `UNION`.
+
+When in doubt, read the plan — don't guess. Seq scan on a big table with a selective filter = a missing or unused index. [references/reading-explain.md](references/reading-explain.md).
+
+## Pagination — keyset over offset at scale
+
+```sql
+-- Wrong — OFFSET 100000 still scans + discards 100000 rows
+SELECT * FROM events ORDER BY created_at DESC OFFSET 100000 LIMIT 20;
+
+-- Correct — keyset: O(log n) seek via the index, stable under inserts
+SELECT * FROM events WHERE created_at < $1 ORDER BY created_at DESC LIMIT 20;
+```
+
+Offset pagination degrades linearly and double-shows rows when the set shifts. Keyset (cursor) paginates in constant time off the ordering index. Use offset only for small, bounded sets (an admin table's page 3).
+
+## Mutations — upsert, returning, transactions
+
+- **Upsert**: Postgres `INSERT … ON CONFLICT (key) DO UPDATE`; MySQL `INSERT … ON DUPLICATE KEY UPDATE`. Never read-then-write (race).
+- **`RETURNING`** (Postgres) hands back the written row in one round trip — no follow-up SELECT.
+- Wrap multi-statement invariants in a transaction; keep it short (locks held = contention). `SELECT … FOR UPDATE` to serialize a read-modify-write.
+
+## PostgreSQL vs MySQL (the traps that bite on a port)
+
+| | PostgreSQL | MySQL |
+|---|---|---|
+| upsert | `ON CONFLICT DO UPDATE` | `ON DUPLICATE KEY UPDATE` |
+| returning written row | `RETURNING *` | no `RETURNING` (re-SELECT or `LAST_INSERT_ID()`) |
+| string quote | single quotes only; `"x"` = identifier | back-tick identifiers; `"x"` may be a string |
+| case sensitivity | identifiers fold lower; data case-sensitive | identifier case depends on OS/`lower_case_table_names` |
+| JSON | `jsonb` + GIN index | `JSON` (no partial-key index pre-8.0; functional indexes after) |
+| booleans | native `boolean` | `TINYINT(1)` |
+
+Versions pinned in [versions.json](versions.json). Don't assume a feature ports — check.
+
+## Anti-patterns (reject on sight)
+
+- f-string / `+`-built SQL with a runtime value → parameterize.
+- `SELECT *` in application code → name columns (stable, index-only scans possible).
+- A query in a loop → batch or join.
+- `OFFSET` on a large, growing table → keyset.
+- `WHERE func(col) = x` against an index on `col` → match the index expression.
+- Read-then-write where an upsert/`FOR UPDATE` is correct → race condition.
+- Trusting a query is fast without `EXPLAIN ANALYZE` on production-shaped data.
+
+## See also
+
+- [references/query-patterns.md](references/query-patterns.md) — joins, CTEs, window functions, keyset, upsert, N+1 cures.
+- [references/reading-explain.md](references/reading-explain.md) — how to read a plan + the `analyze_plan.py` script.
+- [db-design](../db-design/SKILL.md) — schema, index, and normalization DESIGN (the other half).
+- [security-web](../security-web/SKILL.md) — injection defense (server-side SSOT).

core/skills/sql-authoring/assets/query-review-checklist.md

@@ -0,0 +1,26 @@
+<!-- domain:DB | layer:asset | ssot:false | updated:2026-06-04 -->
+# Query Review Checklist
+
+Run before shipping any query that touches a real table.
+
+## Safety
+- [ ] Every runtime value is a bind parameter (`%s`/`$1`/`?`) — zero string interpolation of values.
+- [ ] Any interpolated identifier is validated against an allow-list (never user input).
+- [ ] Multi-statement invariants wrapped in a transaction; read-modify-write uses upsert or `FOR UPDATE`.
+
+## Correctness
+- [ ] Joins have the right cardinality (no accidental fan-out duplicating rows).
+- [ ] `NULL` semantics handled (`= NULL` is never true; use `IS NULL` / `COALESCE`).
+- [ ] Keyset pagination has a unique tiebreaker in `ORDER BY`.
+- [ ] Upsert conflict target is a real unique/PK constraint.
+
+## Performance
+- [ ] No query inside a loop (N+1) — batched or joined.
+- [ ] No `SELECT *` in application code — columns named.
+- [ ] Filter expressions match an index (no `func(col)`, no type mismatch, no leading `%`).
+- [ ] Large/growing list paginated by keyset, not `OFFSET`.
+- [ ] `EXPLAIN (ANALYZE, FORMAT JSON)` run on production-shaped data; `analyze_plan.py` → no unexpected seq scans / estimate misses.
+
+## Portability (if the code targets both engines)
+- [ ] Upsert / `RETURNING` / identifier-quoting differences handled (SKILL.md table).
+- [ ] versions.json engine versions current (`make skills-check-versions`).

core/skills/sql-authoring/references/query-patterns.md

@@ -0,0 +1,89 @@
+<!-- domain:DB | layer:reference | ssot:true | updated:2026-06-04 -->
+# Query Patterns — Joins, CTEs, Windows, Keyset, Upsert
+
+> P: The concrete query shapes for the common hard cases, each bad→good.
+> R: Writing a non-trivial query — aggregation, ranking, pagination, batch write.
+> S: Designing the schema/indexes those queries hit — that's [db-design](../../db-design/SKILL.md).
+> N: [SKILL.md](../SKILL.md), [reading-explain.md](reading-explain.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## N+1 cures
+
+```python
+# Wrong — ORM lazy load: 1 + N queries
+for order in session.query(Order).filter_by(user_id=uid):
+    print(order.items)          # one SELECT per order
+
+# Correct — eager load in one round trip
+session.query(Order).options(selectinload(Order.items)).filter_by(user_id=uid)
+```
+
+Raw-SQL equivalent: replace the per-row lookup with a `JOIN`, or batch the keys
+into `WHERE id = ANY($1)` (Postgres) / `WHERE id IN (...)` (MySQL) and group in
+the app. One query beats a thousand every time.
+
+## CTEs for readability (and the materialization trap)
+
+```sql
+WITH recent AS (
+  SELECT * FROM events WHERE created_at > now() - interval '7 days'
+)
+SELECT user_id, count(*) FROM recent GROUP BY user_id;
+```
+
+Postgres 12+ inlines a CTE when it's referenced once (no optimization fence).
+Pre-12, a CTE was always materialized — a hidden perf cliff. Add `MATERIALIZED`
+/ `NOT MATERIALIZED` to be explicit when it matters. MySQL 8 supports CTEs and
+recursive CTEs similarly.
+
+## Window functions — rank without a self-join
+
+```sql
+-- top 3 orders per user, no correlated subquery
+SELECT * FROM (
+  SELECT *, row_number() OVER (PARTITION BY user_id ORDER BY total DESC) AS rn
+  FROM orders
+) ranked
+WHERE rn <= 3;
+```
+
+`row_number / rank / dense_rank / lag / lead / sum() OVER (...)` replace whole
+classes of slow self-joins and app-side loops. Both engines support them (MySQL 8+).
+
+## Keyset pagination (cursor)
+
+```sql
+-- page 1
+SELECT id, created_at FROM events ORDER BY created_at DESC, id DESC LIMIT 20;
+-- next page: pass the last row's (created_at, id) as the cursor
+SELECT id, created_at FROM events
+WHERE (created_at, id) < ($1, $2)
+ORDER BY created_at DESC, id DESC LIMIT 20;
+```
+
+Include a unique tiebreaker (`id`) in the ORDER BY so the cursor is total —
+otherwise rows with equal `created_at` get skipped or repeated. Needs an index
+on `(created_at DESC, id DESC)`.
+
+## Upsert (no read-then-write race)
+
+```sql
+-- Postgres
+INSERT INTO counters (key, n) VALUES ($1, 1)
+ON CONFLICT (key) DO UPDATE SET n = counters.n + 1
+RETURNING n;
+
+-- MySQL
+INSERT INTO counters (key, n) VALUES (?, 1)
+ON DUPLICATE KEY UPDATE n = n + 1;
+```
+
+The conflict target must be a unique/PK constraint. Read-modify-write in the app
+double-counts under concurrency; the upsert is atomic.
+
+## Bulk insert
+
+One multi-row `INSERT ... VALUES (...), (...), (...)` (or `COPY` / `LOAD DATA`
+for thousands) beats a loop of single inserts by 10–100×. Batch in chunks of a
+few hundred to a few thousand to bound statement size.

core/skills/sql-authoring/references/reading-explain.md

@@ -0,0 +1,52 @@
+<!-- domain:DB | layer:reference | ssot:true | updated:2026-06-04 -->
+# Reading an EXPLAIN Plan
+
+> P: How to read a PostgreSQL plan, what each node means, and the script that summarizes it.
+> R: A query is slow, or you want to confirm it uses the index before shipping.
+> S: Choosing which index to create — that's [db-design](../../db-design/SKILL.md).
+> N: [SKILL.md](../SKILL.md), [query-patterns.md](query-patterns.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## Always ANALYZE on real-shaped data
+
+```sql
+EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) SELECT ...;
+```
+
+`EXPLAIN` alone shows the planner's *estimate*; `ANALYZE` runs the query and
+shows *actual* rows + time. The gap between estimated and actual rows is the
+single most useful signal — a 100× gap means the planner is working from wrong
+statistics and probably chose the wrong plan. `BUFFERS` shows cache vs disk.
+
+> Never `EXPLAIN ANALYZE` a mutating statement on production without wrapping it
+> in a transaction you `ROLLBACK` — ANALYZE *executes* the query.
+
+## Node types, worst → best for a selective filter
+
+| Node | Means | Good when | Bad when |
+|---|---|---|---|
+| Seq Scan | read every row | tiny table, or you need most rows | big table + selective `WHERE` → missing index |
+| Index Scan | walk the index, fetch rows | selective filter | low selectivity (returning most rows) |
+| Index Only Scan | answer from the index alone | covering index | — (this is the goal) |
+| Bitmap Heap Scan | index → sorted heap fetch | medium selectivity, multiple conditions | — |
+| Nested Loop | for each outer, probe inner | small outer × indexed inner | large inputs both sides → use hash/merge |
+| Hash Join | build hash, probe | large unsorted joins | tiny inputs (overhead) |
+
+## The three things to check first
+
+1. **Seq Scan on a big table** with a selective `WHERE` → a missing or unused index. Check the filter expression matches an index (no `func(col)`, no type mismatch).
+2. **Estimate vs actual row gap** ≥ ~10× → `ANALYZE <table>` to refresh stats, or rethink a correlated predicate the planner can't model.
+3. **Nested Loop over thousands** of inner rows → the planner mis-estimated; a hash/merge join is usually cheaper.
+
+## Let the script triage it
+
+```bash
+psql -qAtc 'EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) <query>' \
+  | python3 ../scripts/analyze_plan.py
+```
+
+`analyze_plan.py` walks the JSON plan and emits only the actionable lines (seq
+scans on big inputs, estimate misses, risky nested loops) — you read three lines
+instead of a 200-line tree. It is offline and DB-free: it only parses the JSON
+you pipe in.

core/skills/sql-authoring/scripts/analyze_plan.py

@@ -0,0 +1,100 @@
+"""Summarize a PostgreSQL EXPLAIN (FORMAT JSON) plan and flag problems.
+
+PURPOSE:      Turn a verbose EXPLAIN plan into a few actionable lines so the
+              agent reads one summary, not a 200-line tree. Flags seq scans on
+              big inputs, bad row estimates, and risky nested loops.
+INPUT:        EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) output on stdin, or
+              --file <path>. [--rows-threshold N] big-scan cutoff (default 1000).
+              [--estimate-ratio R] estimate-miss factor (default 10). [--json]
+OUTPUT:       Findings + a one-line verdict on stderr; result on stdout
+              ("clean" or "N finding(s)"). Exit 0 clean, 1 if findings, 2 usage.
+DEPENDENCIES: stdlib only. Works offline — you pipe the plan in.
+NOTES:        Pure analysis layer (walk_plan) is unit-testable without a DB.
+              Spec: docs/playbooks/skill-authoring.md; craft: ../SKILL.md.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def _node_findings(node: dict, rows_threshold: int, estimate_ratio: float) -> list[str]:
+    out: list[str] = []
+    ntype = node.get("Node Type", "?")
+    rel = node.get("Relation Name")
+    plan_rows = node.get("Plan Rows")
+    actual = node.get("Actual Rows")
+    where = f" on {rel}" if rel else ""
+
+    if ntype == "Seq Scan":
+        big = (actual if actual is not None else plan_rows) or 0
+        if big >= rows_threshold:
+            out.append(
+                f"seq scan{where}: {big} rows — missing/unused index on the filtered column?"
+            )
+
+    if plan_rows and actual is not None and plan_rows > 0:
+        ratio = max(plan_rows, actual) / max(min(plan_rows, actual), 1)
+        if ratio >= estimate_ratio:
+            out.append(
+                f"estimate off{where}: planned {plan_rows} vs actual {actual} "
+                f"({ratio:.0f}x) — stale stats (ANALYZE) or a bad correlation assumption"
+            )
+
+    if ntype == "Nested Loop" and node.get("Plans"):
+        inner_rows = max((c.get("Actual Rows", c.get("Plan Rows", 0)) or 0) for c in node["Plans"])
+        if inner_rows >= rows_threshold:
+            out.append(
+                f"nested loop over ~{inner_rows} inner rows — a hash/merge join may be cheaper"
+            )
+
+    return out
+
+
+def walk_plan(plan: dict, rows_threshold: int, estimate_ratio: float) -> list[str]:
+    findings = _node_findings(plan, rows_threshold, estimate_ratio)
+    for child in plan.get("Plans", []):
+        findings.extend(walk_plan(child, rows_threshold, estimate_ratio))
+    return findings
+
+
+def analyze(explain_json: object, rows_threshold: int, estimate_ratio: float) -> list[str]:
+    # EXPLAIN FORMAT JSON returns a list whose first item holds {"Plan": {...}}.
+    root = explain_json[0] if isinstance(explain_json, list) else explain_json
+    if not isinstance(root, dict) or "Plan" not in root:
+        raise ValueError("input is not an EXPLAIN (FORMAT JSON) plan")
+    return walk_plan(root["Plan"], rows_threshold, estimate_ratio)
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("--file", default=None)
+    parser.add_argument("--rows-threshold", default=1000, type=int)
+    parser.add_argument("--estimate-ratio", default=10.0, type=float)
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    args = parser.parse_args(argv)
+
+    raw = Path(args.file).read_text(encoding="utf-8") if args.file else sys.stdin.read()
+    if not raw.strip():
+        print("error: no EXPLAIN JSON on stdin (or --file)", file=sys.stderr)
+        return 2
+    try:
+        findings = analyze(json.loads(raw), args.rows_threshold, args.estimate_ratio)
+    except (json.JSONDecodeError, ValueError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    for f in findings:
+        print(f"  ✗ {f}", file=sys.stderr)
+    if args.as_json:
+        print(json.dumps({"findings": findings, "count": len(findings)}))
+    else:
+        print("clean" if not findings else f"{len(findings)} finding(s)")
+    return 1 if findings else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

core/skills/sql-authoring/versions.json

@@ -0,0 +1,17 @@
+{
+  "postgresql": {
+    "ecosystem": "endoflife",
+    "package": "postgresql",
+    "version": "18.4",
+    "source": "https://endoflife.date/postgresql",
+    "checked": "2026-06-05"
+  },
+  "mysql": {
+    "ecosystem": "endoflife",
+    "package": "mysql",
+    "track": "lts",
+    "version": "9.7.0",
+    "source": "https://endoflife.date/mysql",
+    "checked": "2026-06-05"
+  }
+}