@dsalazardev/ai-hub-cli 0.0.0-stage → 0.2.0

package/skills/shared/spring-boot/references/testing.md

@@ -0,0 +1,95 @@
+# Testing depth (JUnit 5 + slices + Testcontainers)
+
+SKILL.md has the slice table, `@MockitoBean`, the `@WebMvcTest` example, and the
+`@ServiceConnection` snippet. This is the depth: when each slice earns its cost, container
+reuse, the modern test clients, `@DataJpaTest` patterns, and a CI gate.
+
+## Slice selection (cost vs coverage)
+
+- **`@WebMvcTest(Foo.class)`** — loads only that controller, Bean Validation, Jackson, and
+  Spring Security. Milliseconds. Supply collaborators with `@MockitoBean`. Use for: status
+  codes, validation errors, JSON shape, auth rules.
+- **`@DataJpaTest`** — loads JPA + a database, wraps each test in a transaction it rolls back.
+  Use for: derived queries, `@Query` correctness, mappings, fetch behavior. Point it at a real
+  Postgres via Testcontainers (below) rather than H2, so dialect differences don't hide bugs.
+- **`@SpringBootTest`** — full context; slowest. Use only for genuine end-to-end paths
+  (controller -> service -> real repo -> DB). Add `webEnvironment = RANDOM_PORT` + `WebTestClient`
+  for real HTTP.
+
+Reach down this list only when the cheaper slice can't express the assertion.
+
+## Mocking — `@MockitoBean`, not `@MockBean`
+
+`@MockBean`/`@SpyBean` are removed in Boot 4. Use `@MockitoBean`/`@MockitoSpyBean` from
+`org.springframework.test.context.bean.override.mockito`. They replace the matching bean in
+the context for that test class.
+
+```java
+@WebMvcTest(UserController.class)
+class UserControllerTest {
+    @Autowired MockMvc mvc;
+    @MockitoBean UserService users;
+
+    @Test void returns201() throws Exception {
+        when(users.create(any())).thenReturn(new UserResponse(1L, "Ada", "ada@x.io"));
+        mvc.perform(post("/api/users").contentType(APPLICATION_JSON)
+                .content("{\"name\":\"Ada\",\"email\":\"ada@x.io\"}"))
+           .andExpect(status().isCreated())
+           .andExpect(header().string("Location", "/api/users/1"));
+    }
+}
+```
+
+`MockMvcTester` (Boot 4, AssertJ-style) is the more fluent alternative to raw `MockMvc` for
+new tests; `WebTestClient` is the choice for real-port `@SpringBootTest`.
+
+## Testcontainers + `@ServiceConnection`
+
+A container `@Bean` annotated `@ServiceConnection` registers its `ConnectionDetails`
+automatically — Spring points the datasource at the container with no `@DynamicPropertySource`.
+
+```java
+@TestConfiguration(proxyBeanMethods = false)
+class ContainersConfig {
+    @Bean @ServiceConnection
+    PostgreSQLContainer<?> postgres() { return new PostgreSQLContainer<>("postgres:17"); }
+}
+
+@DataJpaTest
+@Import(ContainersConfig.class)
+@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)  // use the real container
+class UserRepositoryTest {
+    @Autowired UserRepository repo;
+    @Test void findsByEmail() { /* save + assert */ }
+}
+```
+
+Speed local runs with reuse — survives across test JVMs:
+
+```text
+# ~/.testcontainers.properties
+testcontainers.reuse.enable=true
+```
+
+…and `new PostgreSQLContainer<>("postgres:17").withReuse(true)`. (Reuse is a local convenience;
+CI usually starts fresh containers per run.)
+
+## `@DataJpaTest` patterns
+
+- **Test-data builders** beat hand-built entity graphs: a `users().withEmail(...).build()`
+  helper keeps tests readable and tolerant of new required fields.
+- Use `TestEntityManager` to persist + `flush()` + `clear()` before asserting a query, so you
+  read from the DB, not the first-level cache.
+- Each test rolls back by default — don't assert across tests or rely on insertion order.
+
+## CI gate
+
+Wire the build's test phase plus this skill's static reviewer:
+
+```bash
+./mvnw -q verify          # compile + unit + slice + integration tests (or ./gradlew check)
+./scripts/verify.sh src   # flag legacy Spring idioms (WebSecurityConfigurerAdapter, @MockBean, javax.*, …)
+```
+
+Run real integration tests behind a tag/profile so the fast slices give quick feedback and the
+container-backed tests run on the gate.

package/skills/shared/spring-boot/scripts/verify.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+#
+# verify.sh — static reviewer for legacy / wrong-generation Spring Boot idioms.
+#
+# Usage:
+#   ./scripts/verify.sh [TARGET_PATH]     # defaults to "."
+#
+# Greps the project's Spring sources (*.java, application*.yml|yaml|properties) for idioms
+# that are removed or discouraged on the Boot 4 / Framework 7 / Security 7 / Jakarta 11
+# generation, and prints each hit with the modern replacement. Read-only: it never edits a
+# file. On a clean tree — or a tree with no Spring sources at all — it prints nothing
+# actionable and exits 0 (no false failure). It exits 1 only when at least one finding is
+# present, so it can double as a non-blocking CI lint signal.
+#
+# Compatible with stock macOS bash 3.2: no mapfile, no associative arrays, no process
+# substitution that trips `set -u`.
+
+set -euo pipefail
+
+TARGET="${1:-.}"
+
+if [ -t 1 ]; then
+  RED=$'\033[31m'; GREEN=$'\033[32m'; YELLOW=$'\033[33m'; RESET=$'\033[0m'
+else
+  RED=''; GREEN=''; YELLOW=''; RESET=''
+fi
+
+if [ ! -e "$TARGET" ]; then
+  printf '%serror:%s target path %s does not exist.\n' "$RED" "$RESET" "$TARGET" >&2
+  exit 2
+fi
+
+findings=0
+
+# Run a grep over Java sources; print findings with a fix hint. Never fails the script by
+# itself (grep's no-match exit 1 is swallowed); increments the global findings counter.
+scan_java() {
+  pattern="$1"; label="$2"; fix="$3"
+  hits="$(grep -REn --include='*.java' -- "$pattern" "$TARGET" 2>/dev/null || true)"
+  if [ -n "$hits" ]; then
+    findings=1
+    printf '%s[finding]%s %s -> %s\n' "$YELLOW" "$RESET" "$label" "$fix"
+    printf '%s\n' "$hits" | sed 's/^/    /'
+  fi
+}
+
+scan_config() {
+  pattern="$1"; label="$2"; fix="$3"
+  hits="$(grep -REn --include='application*.yml' --include='application*.yaml' \
+            --include='application*.properties' -- "$pattern" "$TARGET" 2>/dev/null || true)"
+  if [ -n "$hits" ]; then
+    findings=1
+    printf '%s[finding]%s %s -> %s\n' "$YELLOW" "$RESET" "$label" "$fix"
+    printf '%s\n' "$hits" | sed 's/^/    /'
+  fi
+}
+
+# --- removed / wrong-generation idioms ---
+scan_java 'WebSecurityConfigurerAdapter'        'WebSecurityConfigurerAdapter (removed in Security 6/7)' 'a SecurityFilterChain bean + lambda DSL'
+scan_java '@(MockBean|SpyBean)\b'               '@MockBean / @SpyBean (removed in Boot 4)'               '@MockitoBean / @MockitoSpyBean'
+scan_java '\.(authorizeRequests|antMatchers|mvcMatchers)\s*\(' 'authorizeRequests / antMatchers / mvcMatchers (gone in Security 6/7)' 'authorizeHttpRequests + requestMatchers'
+scan_java 'import[[:space:]]+javax\.persistence' 'javax.persistence import (Jakarta EE 11 baseline)'      'jakarta.persistence.*'
+scan_java 'import[[:space:]]+javax\.validation'  'javax.validation import (Jakarta EE 11 baseline)'       'jakarta.validation.*'
+
+# --- discouraged patterns (heuristic) ---
+# Field @Autowired: an @Autowired line whose payload is not a method/constructor (no '(').
+field_autowired="$(grep -REn --include='*.java' -- '@Autowired' "$TARGET" 2>/dev/null \
+  | grep -Ev '\(' || true)"
+if [ -n "$field_autowired" ]; then
+  findings=1
+  printf '%s[finding]%s field/setter @Autowired (heuristic) -> %s\n' "$YELLOW" "$RESET" 'constructor injection, final fields'
+  printf '%s\n' "$field_autowired" | sed 's/^/    /'
+fi
+
+# @Transactional inside a @RestController source file (tx belongs on the service).
+tx_in_controller=""
+ctrl_files="$(grep -REl --include='*.java' -- '@RestController' "$TARGET" 2>/dev/null || true)"
+if [ -n "$ctrl_files" ]; then
+  # bash 3.2-safe iteration over newline-separated file list
+  OLDIFS="$IFS"; IFS='
+'
+  for f in $ctrl_files; do
+    hit="$(grep -En -- '@Transactional' "$f" 2>/dev/null || true)"
+    if [ -n "$hit" ]; then
+      tx_in_controller="${tx_in_controller}${f}:\n${hit}\n"
+    fi
+  done
+  IFS="$OLDIFS"
+fi
+if [ -n "$tx_in_controller" ]; then
+  findings=1
+  printf '%s[finding]%s @Transactional in a @RestController file -> %s\n' "$YELLOW" "$RESET" 'move @Transactional to the service method'
+  printf '%b' "$tx_in_controller" | sed 's/^/    /'
+fi
+
+# csrf().disable() with no rationale comment on the same line.
+csrf_hits="$(grep -REn --include='*.java' -- 'csrf\s*\(\s*\)\s*\.\s*disable|csrf\(.*disable' "$TARGET" 2>/dev/null || true)"
+if [ -n "$csrf_hits" ]; then
+  csrf_unexplained="$(printf '%s\n' "$csrf_hits" | grep -Ev '//' || true)"
+  if [ -n "$csrf_unexplained" ]; then
+    findings=1
+    printf '%s[finding]%s csrf().disable() with no rationale comment -> %s\n' "$YELLOW" "$RESET" 'disable only for stateless token APIs; add a // comment saying why'
+    printf '%s\n' "$csrf_unexplained" | sed 's/^/    /'
+  fi
+fi
+
+scan_config 'ddl-auto:[[:space:]]*(update|create-drop)' 'hibernate ddl-auto=update/create-drop in config' 'use validate + Flyway/Liquibase migrations'
+
+if [ "$findings" -eq 0 ]; then
+  printf '%s[ ok ]%s no legacy Spring idioms found in %s\n' "$GREEN" "$RESET" "$TARGET"
+  exit 0
+fi
+
+printf '%s[note]%s findings above are advisory; review and migrate to the Boot 4 idioms.\n' "$RED" "$RESET"
+exit 1

package/skills/shared/sql/SKILL.md

@@ -0,0 +1,286 @@
+---
+name: sql
+description: "Use when writing or reviewing advanced SQL query logic independent of any one engine — multi-table joins, window functions, CTEs including recursive ones, GROUP BY and GROUPING SETS aggregation, and set operations — or when a query returns too many rows, too few, or wrong totals. NOT engine internals, indexes or EXPLAIN (that is `postgresdb`), NOT MySQL config (that is `mysql`), NOT OLAP columnar specifics (that is `duckdb`)."
+tags: [sql, query, joins, window-functions, cte]
+recommends: [postgresdb, mysql, duckdb, drizzle-orm]
+origin: ai-hub
+---
+
+# SQL — engine-agnostic query craft
+
+This skill is the portable query-writing layer that sits *above* any one database engine. It owns
+the SELECT-side craft: joins and what each does to row count and NULLs, window functions
+(`PARTITION`/`ORDER`/frame), CTEs (including recursive), aggregation (`GROUP BY`/`GROUPING SETS`/`HAVING`),
+set operations (`UNION`/`INTERSECT`/`EXCEPT`), conditional logic (`CASE`/`COALESCE`/`NULLIF`), and the
+NULL three-valued-logic traps that quietly corrupt results across *every* engine. You write queries a
+reviewer accepts on Postgres, MySQL 8, SQLite, DuckDB, SQL Server, or BigQuery with minimal change, and
+you flag exactly where a construct is non-portable and what the dialect substitute is. The target
+standard is **SQL:2023 (ISO/IEC 9075:2023)**, the ninth edition published June 2023; window functions
+have been standard since **SQL:2003**, so they are safe to assume everywhere.
+
+This is about *thinking in sets and frames*, not about one product's planner, DDL, indexing, or ops.
+
+## When to use
+
+- Writing a non-trivial read query: multi-table join, "top-N per group", running totals,
+  period-over-period deltas, dedup, pivots, cohort/funnel shaping.
+- Reaching for a window function and unsure about `PARTITION BY` vs `GROUP BY`, or `ROWS` vs `RANGE`
+  vs `GROUPS` frames.
+- Structuring a query with CTEs or recursive CTEs (hierarchies, graph walks, generated series).
+- Aggregation shaping: `GROUP BY`, `HAVING`, `GROUPING SETS`/`ROLLUP`/`CUBE`, conditional aggregates.
+- Combining result sets with `UNION`/`INTERSECT`/`EXCEPT`; deciding `ALL` vs distinct.
+- Debugging a query that returns *too many rows* (join fan-out), *too few* (NULL-eating `NOT IN`), or
+  *wrong aggregates* (counting joined duplicates).
+- Translating a procedural loop ("for each row, query again") into one set-based statement.
+- Reviewing SQL for portability and correctness regardless of the target engine.
+
+## When NOT to use
+
+| The ask | Route to |
+| --- | --- |
+| Engine-level Postgres: DDL types, indexes, EXPLAIN, VACUUM, RLS, pooling | `../postgresdb/SKILL.md` |
+| MySQL-specific behavior/config (InnoDB, buffer pool) | `../mysql/SKILL.md` |
+| DuckDB local-analytics / columnar specifics | `../duckdb/SKILL.md` |
+| ClickHouse columnar OLAP engine specifics | `../clickhouse-analytics/SKILL.md` |
+| ORM/builder API ergonomics (the API, not the emitted SQL) | `../drizzle-orm/SKILL.md`, `../prisma-orm/SKILL.md` |
+| Schema design / DDL / migrations | `../db-migrations/SKILL.md` |
+| BI dashboards, reporting layout, metric definitions | `../business-intelligence/SKILL.md` |
+| Cleaning messy data as a pipeline task | `../data-cleaning/SKILL.md` |
+
+The defining line: **`sql` = portable query-language craft; engine skills = one product's behavior,
+storage, and operations.** When the engine isn't decided, or the question is "how do I express this in
+SQL at all" rather than "how does Postgres run it" — you are in the right place.
+
+## Non-negotiables
+
+1. **Explicit `JOIN` syntax, never comma-joins.** `FROM a, b WHERE a.id = b.a_id` hides the join
+   condition in the filter — drop the `WHERE` clause by accident and you get a silent cross product.
+2. **Alias and qualify every column in a multi-table query.** `SELECT id, name` is ambiguous and breaks
+   the moment two joined tables share a column name; `SELECT o.id, c.name` survives schema changes.
+3. **`NOT EXISTS` over `NOT IN` whenever the inner side is nullable.** `NOT IN` returns *zero rows* if the
+   subquery yields a single NULL (3VL `UNKNOWN` is never `TRUE`); `NOT EXISTS` is NULL-safe. Standard, not
+   engine-specific.
+4. **Know your implicit window frame.** A window function with `ORDER BY` but no explicit frame defaults to
+   `RANGE BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW`, which lumps *tied* rows together — not `ROWS`. This
+   silently wrong running total is the single most common window bug, identical across engines. Write the
+   frame explicitly.
+5. **Every non-aggregated SELECT column appears in `GROUP BY`.** Engines that let you skip it (old MySQL)
+   return an arbitrary row per group — a correctness landmine, not a convenience.
+6. **`UNION ALL` unless you genuinely need dedup.** Bare `UNION` sorts/hashes to remove duplicates — real
+   cost — and silently collapses rows you meant to keep. Add `ALL` by default; remove it deliberately.
+7. **Reason about NULL 3VL before writing any predicate.** `NULL = NULL` is `UNKNOWN`, `x <> 5` excludes
+   NULL `x`, and `COUNT(col)` skips NULLs while `COUNT(*)` does not. Decide what NULL means before the WHERE.
+8. **One set-based statement beats a procedural loop.** "For each row, run another query" is almost always a
+   join or a window function — orders of magnitude faster and atomic. Reach for sets first.
+
+## Decision tables
+
+### JOIN chooser
+
+| Want | Use | Row-count effect | NULL behavior |
+| --- | --- | --- | --- |
+| Only matching pairs | `INNER JOIN` | Can shrink **and** fan out on 1-to-many | Unmatched rows dropped |
+| All left rows + matches | `LEFT JOIN` | ≥ left row count | Right columns NULL when no match |
+| All rows from both | `FULL JOIN` | ≥ max(left, right) | NULLs on whichever side lacks a match |
+| Every combination | `CROSS JOIN` | left × right (multiplies!) | None |
+| "Left rows that have a match" | semi-join via `EXISTS` | = left, no duplication | No right columns added |
+| "Left rows with no match" | anti-join via `NOT EXISTS` | ≤ left | NULL-safe (unlike `NOT IN`) |
+
+A 1-to-many `JOIN` *fans out* the left row once per match. If you then `SUM`/`COUNT`, the aggregate is
+inflated. Use a semi-join (`EXISTS`) when you only want existence, not the joined columns.
+
+### GROUP BY vs window function
+
+| You want… | Use | Result |
+| --- | --- | --- |
+| One row per group (collapse detail) | `GROUP BY` | Fewer rows; only group keys + aggregates survive |
+| Keep every row **and** add a per-group number | `... OVER (PARTITION BY …)` | Same row count; aggregate alongside detail |
+
+Rule of thumb: if the question is "per X, the total/rank/previous," and you still want the individual
+rows, it is a window function. If you only want the rollup, it is `GROUP BY`.
+
+### Frame chooser (`ROWS` / `RANGE` / `GROUPS`)
+
+| Frame unit | Counts by | Use for | Portability |
+| --- | --- | --- | --- |
+| `ROWS` | Physical rows | Running totals, moving averages | Everywhere |
+| `RANGE` | Value range of the `ORDER BY` key | "All rows within ±N of this value/date" | Everywhere |
+| `GROUPS` | Peer groups (tied rows) | "N distinct ordering-value steps back" | **Not in MySQL 8** |
+
+`ROWS` and `RANGE` plus `EXCLUDE` and numeric `RANGE` offsets work on Postgres 11+ and SQLite 3.28+.
+**MySQL 8 supports only `ROWS` and `RANGE` — no `GROUPS`, no `EXCLUDE`.** See `references/window-functions.md`.
+
+### Subquery vs JOIN vs CTE
+
+| Need | Reach for |
+| --- | --- |
+| Existence / anti-existence test | correlated `EXISTS` / `NOT EXISTS` |
+| Combine columns from another table | `JOIN` |
+| Name an intermediate result, reuse or read it cleanly | CTE (`WITH`) |
+| Hierarchy, graph walk, generated series | recursive CTE (`WITH RECURSIVE`) |
+
+## Copy-paste patterns
+
+Every fence is `sql`. Full depth in `references/`.
+
+**Top-N per group** — never `LIMIT` inside a correlated subquery.
+
+```sql
+-- Bad: correlated subquery runs once per customer; non-portable LIMIT placement
+SELECT * FROM orders o
+WHERE o.id IN (
+  SELECT id FROM orders i WHERE i.customer_id = o.customer_id
+  ORDER BY i.amount DESC LIMIT 3
+);
+
+-- Good: one pass, ranked, then filtered
+SELECT customer_id, id, amount
+FROM (
+  SELECT customer_id, id, amount,
+         ROW_NUMBER() OVER (PARTITION BY customer_id ORDER BY amount DESC) AS rn
+  FROM orders
+) ranked
+WHERE rn <= 3;
+```
+
+**Running total** — make the frame explicit so ties don't lump.
+
+```sql
+-- Bad: no frame -> implicit RANGE, tied dates collapse into one running value
+SELECT day, SUM(amount) OVER (ORDER BY day) AS running FROM sales;
+
+-- Good: explicit ROWS frame counts physical rows
+SELECT day,
+       SUM(amount) OVER (ORDER BY day ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW) AS running
+FROM sales;
+```
+
+**Period-over-period with `LAG`.**
+
+```sql
+-- Good: previous row's value per partition; NULL on the first row is expected
+SELECT month, revenue,
+       revenue - LAG(revenue) OVER (PARTITION BY product_id ORDER BY month) AS delta,
+       ROUND(100.0 * (revenue - LAG(revenue) OVER (PARTITION BY product_id ORDER BY month))
+             / NULLIF(LAG(revenue) OVER (PARTITION BY product_id ORDER BY month), 0), 2) AS pct_change
+FROM monthly_revenue;
+```
+
+`NULLIF(prev, 0)` guards against divide-by-zero; the first row's `LAG` is NULL by design.
+
+**Dedup keeping latest** — `QUALIFY` is convenient but narrow.
+
+```sql
+-- Portable: rank then filter in an outer query
+SELECT * FROM (
+  SELECT *, ROW_NUMBER() OVER (PARTITION BY email ORDER BY updated_at DESC) AS rn
+  FROM users
+) d WHERE rn = 1;
+
+-- DuckDB / BigQuery / Snowflake only: QUALIFY skips the wrapper. NOT in Postgres/MySQL/SQLite.
+SELECT * FROM users
+QUALIFY ROW_NUMBER() OVER (PARTITION BY email ORDER BY updated_at DESC) = 1;
+```
+
+**Recursive CTE with a depth guard** — always bound the recursion.
+
+```sql
+-- Good: org chart walk; depth column stops runaway / cyclic graphs
+WITH RECURSIVE tree AS (
+  SELECT id, manager_id, name, 1 AS depth
+  FROM employees WHERE manager_id IS NULL
+  UNION ALL
+  SELECT e.id, e.manager_id, e.name, t.depth + 1
+  FROM employees e JOIN tree t ON e.manager_id = t.id
+  WHERE t.depth < 50            -- hard ceiling; for true cycles track a path array
+)
+SELECT * FROM tree;
+```
+
+**Conditional aggregation / pivot** — `FILTER` reads cleaner than `CASE`.
+
+```sql
+-- Portable everywhere: CASE inside the aggregate
+SELECT region,
+       SUM(CASE WHEN status = 'paid' THEN amount ELSE 0 END) AS paid,
+       SUM(CASE WHEN status = 'open' THEN amount ELSE 0 END) AS open
+FROM invoices GROUP BY region;
+
+-- Postgres/SQLite/DuckDB: FILTER is the standard, more readable form. NOT in MySQL/SQL Server.
+SELECT region,
+       SUM(amount) FILTER (WHERE status = 'paid') AS paid,
+       SUM(amount) FILTER (WHERE status = 'open') AS open
+FROM invoices GROUP BY region;
+```
+
+**`GROUPING SETS` / `ROLLUP`** — one scan, multiple aggregation levels.
+
+```sql
+-- Good: subtotals per (region, product), per region, and grand total in one query
+SELECT region, product, SUM(amount) AS total
+FROM sales
+GROUP BY ROLLUP (region, product);   -- = GROUPING SETS ((region,product),(region),())
+```
+
+**Anti-join via `NOT EXISTS`** — the NULL-safe "rows with no match."
+
+```sql
+-- Good: customers who never ordered; correct even if orders.customer_id has NULLs
+SELECT c.id, c.name FROM customers c
+WHERE NOT EXISTS (SELECT 1 FROM orders o WHERE o.customer_id = c.id);
+```
+
+**The `NOT IN`-NULL footgun.**
+
+```sql
+-- Bad: if ANY returned customer_id is NULL, this yields ZERO rows, silently
+SELECT * FROM customers
+WHERE id NOT IN (SELECT customer_id FROM orders);
+
+-- Good: NOT EXISTS, or NOT IN with an explicit IS NOT NULL filter on the inner column
+SELECT * FROM customers c
+WHERE NOT EXISTS (SELECT 1 FROM orders o WHERE o.customer_id = c.id);
+```
+
+## Portability quick map
+
+| Construct | Notes |
+| --- | --- |
+| `QUALIFY` | DuckDB / BigQuery / Snowflake only — elsewhere wrap in a subquery and filter `rn` |
+| `FILTER (WHERE …)` | Postgres / SQLite / DuckDB — MySQL & SQL Server need `CASE` |
+| `GROUPS` frame, `EXCLUDE` | Postgres 11+, SQLite 3.28+ — **not in MySQL 8** |
+| `EXCEPT` | Standard; Oracle spells it `MINUS` |
+| Row limiting | `LIMIT … OFFSET` (Postgres/MySQL/SQLite/DuckDB) vs `FETCH FIRST n ROWS ONLY` (standard/SQL Server 2012+) vs `TOP n` (SQL Server) |
+| Set-op column match | By **position and type**, not by name — order your columns identically |
+
+Full six-engine matrix in `references/portability.md`.
+
+## Anti-patterns / rationalizations -> STOP
+
+| Rationalization | Reality | STOP |
+| --- | --- | --- |
+| "`NOT IN` is clearer than `NOT EXISTS`" | One NULL in the inner set returns zero rows, silently | Use `NOT EXISTS` for nullable inner columns |
+| "`SELECT *` is fine in this query" | Hides which columns matter; breaks `GROUP BY`, ambiguous on joins | Project explicit, qualified columns |
+| "Old MySQL let me skip the GROUP BY column" | You get an arbitrary row per group | List every non-aggregated column |
+| "No frame needed, I just want a running sum" | Implicit `RANGE` lumps tied rows -> wrong total | Write `ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW` |
+| "I'll loop in app code and query per row" | N+1 round trips; a window function does it in one scan | Express it as one set-based statement |
+| "`UNION` to merge these results" | Pays a dedup sort and drops rows you wanted | `UNION ALL` unless dedup is the goal |
+| "`COUNT(*)` after the join is the real count" | A 1-to-many join fanned the rows out | Count on the base table or use a semi-join |
+| "Add `DISTINCT` to fix the duplicate rows" | Masks a fan-out join instead of fixing it | Find the join multiplying rows; fix the grain |
+
+## Verify
+
+Run `scripts/verify.sh` from your project root. It is read-only, never connects to a database, and runs
+on stock macOS bash 3.2. It heuristically scans discovered `.sql` files and warns on the footguns above
+(`NOT IN (SELECT …)`, comma-joins with WHERE-join predicates, `SELECT *` alongside `GROUP BY`, window
+`OVER (… ORDER BY …)` with no explicit frame) and, if `sqlfluff` is installed, lints with `--dialect ansi`.
+It exits non-zero only on a real `sqlfluff` lint error or unbalanced parens/quotes (dollar-quote aware);
+every heuristic is advisory `[warn]`, and an empty target passes clean.
+
+## See Also
+
+- `references/window-functions.md` — ranking/offset/aggregate-over catalog, every frame unit worked, `EXCLUDE`, named windows, implicit-frame trap, per-engine matrix.
+- `references/joins-and-sets.md` — every join type with row-count reasoning, semi/anti/lateral joins, set ops + `ALL`/dedup/`MINUS`, the fan-out-inflates-aggregates bug.
+- `references/ctes-and-recursion.md` — CTE structuring, recursive template (hierarchy/graph/series) with cycle + depth guards, the optimization-fence portability note.
+- `references/portability.md` — full dialect matrix across Postgres / MySQL 8 / SQLite / DuckDB / SQL Server / BigQuery.
+- Siblings: `../postgresdb/SKILL.md`, `../mysql/SKILL.md`, `../duckdb/SKILL.md`, `../clickhouse-analytics/SKILL.md`, `../drizzle-orm/SKILL.md`, `../prisma-orm/SKILL.md`, `../db-migrations/SKILL.md`. ORM/engine internals are out of scope here — this skill owns the SQL those tools ultimately emit.

package/skills/shared/sql/evals/README.md

@@ -0,0 +1,9 @@
+# Eval harness — `sql`
+
+These cases are hand-graded prompts, not an automated test suite. Run them through an agent harness and grade honestly.
+
+**Triggering.** For each prompt in `cases.yaml`, start a fresh agent session with only the `sql` skill discoverable, paste the prompt verbatim, and run 3–5 trials (the decision is stochastic). A `should_trigger` case passes if the skill fires in the majority of trials; a `should_not_trigger` case passes if it stays quiet and the agent would plausibly route to the named `route_to` sibling (or `none`). Aim for ≥ 90% trigger accuracy across all cases — the near-misses (indexing, MySQL config, ORM builder, migrations, ClickHouse) deliberately share vocabulary with this skill, so they test intent, not keywords.
+
+**Capability.** Run each `capability` scenario twice — once WITHOUT the skill (clean agent) and once WITH it loaded — and score each transcript against its `must_include` rubric, one point per bullet that is specifically and correctly covered (not merely name-dropped). The skill passes if WITH-coverage reaches ≥ 80% of the bullets and clearly beats WITHOUT (target ≥ +30 points or fail→pass). If a baseline agent already nails the rubric, tighten it.
+
+**Artifact check.** `scripts/verify.sh` lints emitted `.sql` files heuristically (read-only, no DB connection); it complements the capability eval but does not replace it. Record trial counts and per-bullet verdicts so a reviewer can audit.

package/skills/shared/sql/evals/cases.yaml

@@ -0,0 +1,49 @@
+skill: sql
+
+should_trigger:
+  - prompt: "Get the top 3 orders per customer by amount"
+    why: Classic top-N-per-group — ROW_NUMBER partitioned by customer, filtered on the rank. Core window-function craft.
+  - prompt: "My SUM is double the real total after I joined order_items, why?"
+    why: Non-obvious. A one-to-many join fans out rows and inflates every downstream aggregate — the canonical wrong-total bug this skill owns.
+  - prompt: "Write a running 7-day total with a window function"
+    why: Frame-clause craft (explicit ROWS vs implicit RANGE on tied dates).
+  - prompt: "Necesito una función de ventana para el ranking por categoría"
+    why: Spanish window-function trigger (PARTITION BY category, RANK/ROW_NUMBER).
+  - prompt: "Recursive CTE to walk an org-chart hierarchy with a depth limit"
+    why: WITH RECURSIVE with a depth/cycle guard — squarely in scope.
+  - prompt: "NOT IN with a subquery returns zero rows even though data exists"
+    why: Non-obvious. The NULL three-valued-logic footgun — NOT IN over a NULL-bearing subquery; fix is NOT EXISTS.
+  - prompt: "per què el JOIN duplica files i em surten totals inflats?"
+    why: Catalan trigger for the join fan-out / inflated-aggregate diagnosis.
+  - prompt: "Gaps and islands: find consecutive login streaks per user"
+    why: Non-obvious named pattern solved with window functions (difference of row numbers).
+
+should_not_trigger:
+  - prompt: "Add an index to speed up this Postgres query and read the EXPLAIN plan"
+    route_to: postgresdb
+    why: Engine internals — indexing and planner output are Postgres behavior, not portable query craft.
+  - prompt: "Configure MySQL InnoDB buffer pool size for better throughput"
+    route_to: mysql
+    why: MySQL engine configuration, not SQL query logic.
+  - prompt: "Write this query using Drizzle's query builder API"
+    route_to: drizzle-orm
+    why: ORM builder ergonomics; this skill owns the raw SQL, not the builder API.
+  - prompt: "Design the schema and write the migration for this orders table"
+    route_to: db-migrations
+    why: Schema design / DDL / migration, not SELECT-side query craft.
+  - prompt: "Optimize this columnar scan in ClickHouse"
+    route_to: clickhouse-analytics
+    why: OLAP columnar-engine specifics, not engine-agnostic query language.
+
+capability:
+  - scenario: >
+      Given orders(customer_id, created_at, amount), write a portable query returning each
+      customer's most recent order plus the percent change in amount vs their previous order.
+      Note any non-portable construct you use.
+    must_include:
+      - Uses a window function (LAG, or ROW_NUMBER to pick the latest)
+      - Explicit PARTITION BY customer_id ORDER BY created_at
+      - Handles the first-order case where the previous amount is NULL or zero (NULLIF/COALESCE or a filter)
+      - Computes percent change correctly ((cur - prev) / prev * 100)
+      - Flags at least one portability caveat (e.g. QUALIFY is DuckDB/BigQuery only; otherwise wrap in a subquery)
+      - Does NOT rely on an implicit window frame where ties on created_at would change the result

package/skills/shared/sql/references/ctes-and-recursion.md

@@ -0,0 +1,63 @@
+# CTEs and recursion
+
+## Non-recursive CTEs
+
+`WITH name AS (…)` names an intermediate result so you can reference it (possibly multiple times) and read the query top-down instead of inside-out. Chain them; each may reference the ones above.
+
+```sql
+WITH paid AS (
+  SELECT customer_id, SUM(amount) AS spent
+  FROM orders WHERE status = 'paid'
+  GROUP BY customer_id
+),
+ranked AS (
+  SELECT *, RANK() OVER (ORDER BY spent DESC) AS rnk FROM paid
+)
+SELECT * FROM ranked WHERE rnk <= 10;
+```
+
+Use CTEs to: name a step, avoid repeating a subquery, or stage a recursive walk. Do **not** assume a CTE is materialized for free — see the optimization fence below.
+
+## Recursive CTEs
+
+`WITH RECURSIVE` has two arms joined by `UNION [ALL]`: an **anchor** (the seed rows) and a **recursive member** that references the CTE name. It iterates until the recursive arm produces no new rows.
+
+### Hierarchy (org chart) with a depth guard
+
+```sql
+WITH RECURSIVE chart AS (
+  SELECT id, manager_id, name, 1 AS depth, ARRAY[id] AS path
+  FROM employees WHERE manager_id IS NULL
+  UNION ALL
+  SELECT e.id, e.manager_id, e.name, c.depth + 1, c.path || e.id
+  FROM employees e
+  JOIN chart c ON e.manager_id = c.id
+  WHERE c.depth < 50              -- depth guard: bound the walk
+    AND e.id <> ALL(c.path)       -- cycle guard: don't revisit a node
+)
+SELECT * FROM chart ORDER BY path;
+```
+
+A real cyclic graph will loop forever (or exhaust memory) without a guard. Use **both**: a depth ceiling *and* a visited-path check. The `path` array technique is Postgres/DuckDB; SQLite/MySQL track depth and a string path instead. SQL Server requires `OPTION (MAXRECURSION n)`.
+
+### Graph walk (reachability)
+
+Same shape: anchor = start node, recursive arm follows edges, cycle guard on the accumulated path. Switch `UNION ALL` to `UNION` to collapse duplicate paths to the same node.
+
+### Generated series
+
+```sql
+-- Portable date spine without a numbers table
+WITH RECURSIVE days(d) AS (
+  SELECT DATE '2026-01-01'
+  UNION ALL
+  SELECT d + INTERVAL '1 day' FROM days WHERE d < DATE '2026-12-31'
+)
+SELECT d FROM days;
+```
+
+Postgres/DuckDB prefer `generate_series()`; SQLite and BigQuery have their own (`generate_series`, `GENERATE_DATE_ARRAY`). The recursive form above works where those don't.
+
+## The optimization fence portability note
+
+Historically Postgres **always materialized** a CTE — an optimization fence that could block predicate push-down and hurt performance. Since **Postgres 12** a CTE referenced once and free of side effects is inlined by default; force the old behavior with `WITH x AS MATERIALIZED (…)` or prevent it with `AS NOT MATERIALIZED`. Other engines (MySQL 8, SQLite, DuckDB, SQL Server) generally inline CTEs as ordinary subqueries. Do not rely on a CTE as a performance barrier across engines.