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

package/skills/shared/db-migrations/evals/README.md

@@ -0,0 +1,10 @@
+# Evals — db-migrations
+
+`cases.yaml` specifies routing and capability expectations, not live database runs. `should_trigger` /
+`should_not_trigger` are prompt-routing checks: feed each prompt to the router and confirm db-migrations
+fires (or that the named sibling — postgresdb, drizzle-orm, backups, sql, planetscale — wins instead).
+The `capability` case is a rubric: ask the model to plan the column rename, then score the response
+against the `must_include` bullets (each phase present, in order, with lock_timeout, batched/throttled
+backfill, checksum verify, N/N-1, cooling period, forward-only). There is no database connection here;
+the DDL-shape and self-consistency check lives in `../scripts/verify.sh`. Run these through the repo's
+standard eval harness.

package/skills/shared/db-migrations/evals/cases.yaml

@@ -0,0 +1,46 @@
+skill: db-migrations
+
+should_trigger:
+  - prompt: "We need to add a NOT NULL column to a 40M-row users table without taking the app down. How?"
+    why: Core expand-contract — add-nullable, backfill, NOT VALID/VALIDATE, on a live large table.
+  - prompt: "Rename a heavily-written column on a live Postgres table without downtime."
+    why: Dual-name window with dual-write + batched backfill; the canonical sequencing case.
+  - prompt: "Our deploy keeps deadlocking every time the migration adds an index. What are we doing wrong?"
+    why: Non-obvious — symptom names a deadlock, not a migration; the fix is CONCURRENTLY + lock_timeout.
+  - prompt: "How do we backfill 80M rows into a new column without blowing up replication lag?"
+    why: Batched backfill with lag throttle and verify-before-contract; not query logic.
+  - prompt: "Necesito hacer una migración sin downtime para cambiar el tipo de una columna en producción."
+    why: Spanish phrasing for a type change on a live table — new column + backfill expand-contract.
+  - prompt: "Big ALTER on a busy MySQL table — should we use gh-ost or pt-osc?"
+    why: Non-obvious OSC-tool choice; engine-neutral choreography layer owns this decision.
+
+should_not_trigger:
+  - prompt: "This query is slow — can you read the EXPLAIN ANALYZE plan and tell me which index to add?"
+    route_to: postgresdb
+    why: Query plan reading and Postgres indexing strategy are postgresdb internals, not migration sequencing.
+  - prompt: "How do I generate and run a migration with drizzle-kit?"
+    route_to: drizzle-orm
+    why: That is the runner's CLI mechanics; the safety sequence is here but the tool usage lives in drizzle-orm.
+  - prompt: "Set up a PITR restore drill and verify our nightly backups actually restore."
+    route_to: backups
+    why: Creating and verifying backups/restores is backups; a migration only requires one as a precondition.
+  - prompt: "Write a window-function query to rank orders per customer by date."
+    route_to: sql
+    why: Pure query logic (window functions) is sql, not schema-change choreography.
+  - prompt: "Cut over a PlanetScale branch and merge the deploy request."
+    route_to: planetscale
+    why: Vitess online DDL and deploy-request cutover mechanics belong to planetscale.
+
+capability:
+  - scenario: >
+      Plan, end to end, a zero-downtime rename of a heavily-written column users.email →
+      users.email_address on Postgres, across app deploys and migrations.
+    must_include:
+      - "Expand: add email_address as a NULLABLE column, metadata-only, with lock_timeout set first"
+      - "App deploy that dual-writes both email and email_address while still reading email"
+      - "Batched backfill (bounded PK-range chunks, commit per batch) with replica-lag throttle"
+      - "Verify counts and old-vs-new checksum before contracting"
+      - "N/N-1 note: schema must satisfy both the running app and the next app at every step"
+      - "Switch reads to email_address in a separate deploy, then a cooling period"
+      - "Contract: DROP COLUMN email as a separate migration AFTER the cooling period"
+      - "Forward-only stance: rollback is redeploying the prior app, not a down() script"

package/skills/shared/db-migrations/references/backfill-and-batching.md

@@ -0,0 +1,105 @@
+# Backfill and batching
+
+Filling historical rows is where a "zero-downtime" plan most often turns into an outage: one giant
+`UPDATE` locks rows, balloons WAL/undo, and pins replicas behind minutes of lag. The fix is always the
+same shape — **bounded chunks, commit per chunk, throttle on lag, verify before you contract.**
+
+## The loop, in words
+
+1. Pick a chunk key. A monotonic PK is best; range over `id BETWEEN :lo AND :hi`, not `OFFSET`
+   (OFFSET re-scans and gets slower every batch).
+2. Update one chunk, touching only rows that still need it (`WHERE new_col IS NULL`), then **commit**.
+3. Read replica lag and the app error rate. If either climbs past your threshold, sleep / back off.
+4. Advance the window and repeat until the table is covered.
+5. Verify counts and a checksum of old-vs-new. Only then schedule the contract step.
+
+A few thousand rows per batch is a sane start; tune by watching lag. Smaller batches = lower lag, more
+total wall-clock time.
+
+## Postgres — server-side batched backfill
+
+```sql
+-- Run once per batch from your runner/script, advancing :lo/:hi between calls.
+-- Touch only unfilled rows so re-runs are cheap and the loop is idempotent.
+UPDATE users
+SET    email_address = email
+WHERE  id BETWEEN :lo AND :hi
+  AND  email_address IS NULL;
+```
+
+```sql
+-- A self-contained PL/pgSQL loop that commits each batch (PG 11+ supports COMMIT in a procedure).
+-- Run as a PROCEDURE via CALL, not inside an outer transaction.
+CREATE OR REPLACE PROCEDURE backfill_email_address(batch_size int DEFAULT 5000)
+LANGUAGE plpgsql AS $$
+DECLARE
+  lo bigint := 0;
+  hi bigint;
+  max_id bigint;
+BEGIN
+  SELECT max(id) INTO max_id FROM users;
+  WHILE lo <= max_id LOOP
+    hi := lo + batch_size;
+    UPDATE users
+    SET    email_address = email
+    WHERE  id >= lo AND id < hi
+      AND  email_address IS NULL;
+    COMMIT;                       -- release locks + flush WAL each batch
+    PERFORM pg_sleep(0.1);        -- throttle; raise if replica lag climbs
+    lo := hi;
+  END LOOP;
+END;
+$$;
+```
+
+Throttle by replica lag instead of a fixed sleep when you can — query
+`SELECT max(replay_lag) FROM pg_stat_replication;` between batches and back off while it is high.
+(For the meaning of those replication views, see `../../postgresdb/SKILL.md`.)
+
+## MySQL — batched backfill
+
+MySQL has no in-loop `COMMIT` inside a single statement, so drive the loop from your script and run one
+bounded `UPDATE` per iteration with `autocommit` on:
+
+```sql
+-- One batch; the script advances @lo/@hi and sleeps between iterations.
+UPDATE users
+SET    email_address = email
+WHERE  id >= @lo AND id < @hi
+  AND  email_address IS NULL
+LIMIT  5000;
+```
+
+Watch `SHOW REPLICA STATUS` → `Seconds_Behind_Source` between batches; pause while it grows. For a
+single very large `ALTER` (not a data backfill), use an online-schema-change tool instead — see
+`tools-and-runners.md` for gh-ost vs pt-osc.
+
+## Verify before you contract
+
+Counts and a checksum must agree before any column is dropped or marked `NOT NULL`.
+
+```sql
+-- 1. No rows left unfilled.
+SELECT count(*) AS remaining FROM users WHERE email_address IS NULL;  -- expect 0
+
+-- 2. Old and new agree, row for row.
+SELECT count(*) AS mismatches
+FROM   users
+WHERE  email_address IS DISTINCT FROM email;                          -- expect 0
+```
+
+A non-zero mismatch is a data-correctness bug, not a migration step — investigate the dual-write path
+before contracting. If the divergence is in the *source* data (bad/duplicate rows), that is
+`../../data-cleaning/SKILL.md` territory.
+
+## Very large tables — snapshot + CDC
+
+When an online loop would run for days, do it out of band:
+
+1. Snapshot the table into the new shape (a copy job or a logical dump).
+2. Stream changes that happened during the snapshot via change-data-capture (logical replication / binlog
+   readers) so the copy catches up to live.
+3. Cut over reads once the copy is caught up and verified.
+
+This is the same idea gh-ost and pt-osc automate for a single MySQL `ALTER`; for a multi-table or
+cross-engine move you build it explicitly. Either way the verify-before-contract rule does not change.

package/skills/shared/db-migrations/references/expand-contract-playbook.md

@@ -0,0 +1,152 @@
+# Expand-contract playbook
+
+Ordered deploy/migrate checklists for the common changes. Every example DDL sets `lock_timeout` first
+and uses the non-blocking path, so it is safe to ship as written. Each phase is a **separate deploy**;
+the cooling period between *switch reads* and *contract* is what preserves a no-schema-change rollback.
+
+Notation: `M` = a migration (schema change), `A` = an app deploy. They alternate.
+
+---
+
+## Add a `NOT NULL` column
+
+A single `ADD COLUMN ... NOT NULL DEFAULT <expr>` or `SET NOT NULL` validates/rewrites the whole table
+under lock. Split it.
+
+1. **M1 (expand)** — add the column nullable; metadata-only.
+   ```sql
+   SET lock_timeout = '1s';
+   ALTER TABLE users ADD COLUMN status text;
+   ```
+2. **A1** — app dual-writes `status` on every insert/update (defaults it in code).
+3. **Backfill** — fill historical rows in batches (see `backfill-and-batching.md`).
+4. **M2** — add the constraint without a blocking scan, then validate, then flip `NOT NULL`.
+   ```sql
+   SET lock_timeout = '1s';
+   ALTER TABLE users ADD CONSTRAINT users_status_nn CHECK (status IS NOT NULL) NOT VALID;
+   ALTER TABLE users VALIDATE CONSTRAINT users_status_nn;
+   ALTER TABLE users ALTER COLUMN status SET NOT NULL;
+   ```
+   On PG 12+, a validated `CHECK (col IS NOT NULL)` lets `SET NOT NULL` skip its own full scan.
+
+---
+
+## Rename a column
+
+The running app reads the old name, so you cannot rename in place. Run a dual-name window.
+
+1. **M1 (expand)** — add the new column nullable.
+   ```sql
+   SET lock_timeout = '1s';
+   ALTER TABLE users ADD COLUMN email_address text;
+   ```
+2. **A1** — write BOTH `email` and `email_address`; keep READING `email`.
+3. **Backfill** `email_address` from `email` in batches; verify counts/checksum.
+4. **A2** — read `email_address`; still dual-write both. **Cooling period starts.**
+5. **M2 (contract)** — days later, after the new app has run clean.
+   ```sql
+   SET lock_timeout = '1s';
+   ALTER TABLE users DROP COLUMN email;
+   ```
+
+A view aliasing the new column to the old name can shorten the app-side change, but it does not remove
+the need for the cooling period.
+
+---
+
+## Split one column into two
+
+Example: `full_name` → `first_name`, `last_name`.
+
+1. **M1** — add both new columns nullable.
+   ```sql
+   SET lock_timeout = '1s';
+   ALTER TABLE people ADD COLUMN first_name text;
+   ALTER TABLE people ADD COLUMN last_name text;
+   ```
+2. **A1** — on write, populate all three (`full_name` plus the two parts).
+3. **Backfill** the split for historical rows; verify a reconstructed `full_name` matches the original.
+4. **A2** — read the split columns; keep writing `full_name` through the cooling period.
+5. **M2 (contract)** — drop `full_name` after cooling.
+
+Merging two columns into one is the same shape with the directions reversed.
+
+---
+
+## Change a column type
+
+A non-trivial type change rewrites every row and can invalidate the running app's expectations. Treat it
+as a rename to a new column.
+
+1. **M1** — add the new column with the target type, nullable.
+   ```sql
+   SET lock_timeout = '1s';
+   ALTER TABLE orders ADD COLUMN amount_cents bigint;
+   ```
+2. **A1** — dual-write both old and new; read the old.
+3. **Backfill** with the conversion expression in batches; verify.
+4. **A2** — read the new column; keep dual-writing.
+5. **M2 (contract)** — drop the old column after cooling.
+
+This avoids the in-place `ALTER COLUMN ... TYPE`, which takes an exclusive lock and rewrites under it
+(and, with a `USING` expression, can fail mid-rewrite on bad data).
+
+---
+
+## Drop a column or table
+
+Dropping is a *contract* step, never the first move — the running app may still reference it.
+
+1. **A1** — ship an app version that no longer reads or writes the target.
+2. Wait the cooling period; confirm via logs/metrics that nothing touches it.
+3. **M1 (contract)** — drop it.
+   ```sql
+   SET lock_timeout = '1s';
+   ALTER TABLE users DROP COLUMN legacy_flag;
+   ```
+
+`DROP COLUMN` is metadata-only and fast in Postgres, but the lock it needs is brief-yet-exclusive, so
+keep `lock_timeout` short and retry rather than queue behind a long transaction.
+
+---
+
+## Add a foreign key
+
+`ADD CONSTRAINT ... FOREIGN KEY` validates every existing row under lock. Split validation off.
+
+1. Ensure the referenced column is indexed/unique (add that index `CONCURRENTLY` first if missing).
+2. **M1** — add the constraint as `NOT VALID` (instant; only new/changed rows are checked).
+   ```sql
+   SET lock_timeout = '1s';
+   ALTER TABLE orders
+     ADD CONSTRAINT orders_user_fk FOREIGN KEY (user_id) REFERENCES users (id) NOT VALID;
+   ```
+3. **M2** — validate existing rows without blocking writes.
+   ```sql
+   ALTER TABLE orders VALIDATE CONSTRAINT orders_user_fk;
+   ```
+
+If validation reveals orphan rows, that is a data-correctness problem — clean it before validating
+(see `../../data-cleaning/SKILL.md`), do not loosen the constraint.
+
+---
+
+## Add an index on a live table
+
+Plain `CREATE INDEX` holds a SHARE lock and blocks writes for the whole build — the classic "our deploy
+deadlocks when we add an index" symptom.
+
+```sql
+-- This statement must NOT run inside a transaction block.
+CREATE INDEX CONCURRENTLY idx_orders_user_id ON orders (user_id);
+```
+
+A failed `CONCURRENTLY` build leaves an INVALID index. Find it and rebuild:
+
+```sql
+DROP INDEX CONCURRENTLY idx_orders_user_id;
+CREATE INDEX CONCURRENTLY idx_orders_user_id ON orders (user_id);
+```
+
+How to make a runner skip its transaction wrapper for this one statement is in `tools-and-runners.md`.
+For Postgres lock-level semantics (which lock blocks what), see `../../postgresdb/SKILL.md`.

package/skills/shared/db-migrations/references/tools-and-runners.md

@@ -0,0 +1,88 @@
+# Tools and runners (2026)
+
+This skill is engine- and runner-neutral; this file is the lookup for *which* tool and *how* to make it
+run the unsafe-by-default step safely. Versions are current as of 2026-06.
+
+## Versioned vs declarative
+
+- **Versioned** runners replay an ordered list of scripts (V1, V2, …). You write each step; the runner
+  tracks which have run. Flyway, Liquibase, Alembic, golang-migrate, drizzle-kit.
+- **Declarative** (schema-as-code) tools take your *target* schema and compute the diff to get there.
+  Atlas is the main one. You review the planned diff; you do not hand-write each `ALTER`.
+
+Declarative removes drift and hand-written DDL errors, but the *sequencing* in this skill still applies —
+a planned diff that drops then re-adds a column, or adds `NOT NULL` in one shot, is still an outage. Read
+the plan before you apply it.
+
+## Stack → tool
+
+| Stack / need | Tool | Version (2026-06) | Note |
+|---|---|---|---|
+| JVM, SQL-first, many DBs | Flyway | 12.6.x (12.6.1, May 2026) | Version-based, 50+ DBs. Redgate dropped the Teams tier in 2025, pushing to Enterprise / Native Connectors. |
+| Max format flexibility | Liquibase | current | SQL/XML/YAML/JSON changelogs; most flexible, most verbose. |
+| Python / SQLAlchemy | Alembic | 1.18.x (1.18.4, Feb 2026) | Requires Python ≥ 3.10; plugin system since 1.18.0. |
+| Go | golang-migrate | current | The Go standard; up/down SQL files. |
+| TypeScript / Drizzle | drizzle-kit | current | Runner mechanics in `../../drizzle-orm/SKILL.md`; safety sequence here. |
+| Schema-as-code, planned diffs | Atlas | current | Declarative — give it the target, review the diff. |
+| Vitess / PlanetScale | branch + deploy request | — | Online DDL built into the workflow; see `../../planetscale/SKILL.md`. |
+| Big MySQL `ALTER`, native online DDL can't keep it online | gh-ost or pt-osc | — | See below. |
+
+## Running a statement OUTSIDE the per-migration transaction
+
+`CREATE INDEX CONCURRENTLY` (and `DROP INDEX CONCURRENTLY`, `ALTER TYPE ... ADD VALUE` on older PG)
+**cannot run inside a transaction block**, but most runners wrap each migration in `BEGIN/COMMIT` by
+default. Opt the offending migration out:
+
+- **Flyway** — name the script with the `B`/`transactional=false` setting, or set
+  `flyway.executeInTransaction=false` (per-script via a `-- flyway:` config callback / config file).
+- **Alembic** — set `transaction_per_migration` appropriately and, for the autogenerate path, emit the
+  statement with `op.execute(...)` after committing; the common pattern is
+  `with op.get_context().autocommit_block(): op.execute("CREATE INDEX CONCURRENTLY ...")`.
+- **Django** — add `atomic = False` to the `Migration` class (or use `AddIndexConcurrently` from
+  `django.contrib.postgres.operations`).
+- **Rails** — `disable_ddl_transaction!` in the migration, then `add_index ..., algorithm: :concurrently`.
+- **golang-migrate** — split the concurrent statement into its own migration file; migrate runs each file
+  without wrapping when the statement requires it (keep one statement per file).
+- **drizzle-kit** — generate the SQL, then hand-edit the migration so the concurrent statement stands
+  alone; details in `../../drizzle-orm/SKILL.md`.
+
+## gh-ost vs pt-osc (big MySQL ALTER)
+
+Both copy the table into a new shape and swap it in, so a large `ALTER` does not hold a long metadata
+lock. They differ in *how* they capture concurrent writes:
+
+| | gh-ost | pt-online-schema-change |
+|---|---|---|
+| Change capture | Triggerless — reads the binlog | Trigger-based — triggers on the original table |
+| Consistency | Eventual (binlog replay) | Strict (synchronous triggers) |
+| Write overhead | Lower; no triggers on the hot table | Higher; every write fires a trigger |
+| Throttling | Throttles on replica lag; easy pause/resume | Throttles, but triggers can fail to get the metadata lock under heavy concurrency / long transactions |
+| Cutover control | Fine-grained, can postpone | Less granular |
+
+**Prefer gh-ost on a very busy master** — triggerless means no write amplification on the hot path, and
+the lag-aware throttle plus postponable cutover are easier to operate. Reach for pt-osc when you need
+strict synchronous consistency and the write volume is modest enough that trigger overhead and
+metadata-lock contention are not a concern.
+
+## CI gate — Squawk
+
+**Squawk** is the standard static linter for Postgres migration SQL. Run it in CI so a bare
+`CREATE INDEX`, a one-shot `NOT NULL`, a blocking constraint add, or a column drop fails the PR before
+review.
+
+```yaml
+# .github/workflows/migrations.yml (excerpt)
+- name: Lint migrations
+  run: npx squawk@latest migrations/*.sql
+```
+
+```toml
+# .squawk.toml — example: keep the dangerous rules on, silence ones you handle out of band
+[lint]
+excluded_rules = []   # start strict; add an id here only with a written reason
+# e.g. "prefer-robust-stmts" enforces lock_timeout + CONCURRENTLY patterns
+```
+
+`scripts/verify.sh` in this skill runs the same class of static checks (no DB connection) against the
+example migrations shipped in these references, so the skill stays self-consistent with what it tells you
+to gate on.

package/skills/shared/db-migrations/scripts/verify.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — db-migrations skill gate.
+#
+# This is a self-consistency + artifact-shape check on the skill's OWN files, not a live DB check.
+# It NEVER connects to a database and NEVER writes anything.
+#
+# What it asserts:
+#   1. The skill ships a Squawk / migration-lint reference (CI gate the body tells you to add).
+#   2. SKILL.md documents each forbidden DDL pattern as a Bad->Good (lock_timeout, CONCURRENTLY,
+#      multi-step NOT NULL, batched backfill).
+#   3. Example .sql shipped in references/ is itself safe — none of the danger signatures the body
+#      forbids: bare CREATE INDEX (no CONCURRENTLY), an ALTER that is missing lock_timeout, or
+#      ADD COLUMN ... NOT NULL without the multi-step path. (DROP INDEX CONCURRENTLY is exempt from
+#      the lock_timeout rule; it manages its own locking.)
+#
+# Exit code: non-zero only if the skill's own artifacts are inconsistent with what the body teaches.
+# An empty / missing references dir is a clean skip, not a failure (exit 0).
+#
+# Portable to stock macOS bash 3.2: no mapfile, no associative arrays; arrays are initialised so they
+# expand safely under `set -u`.
+
+GREEN=$'\033[32m'; YELLOW=$'\033[33m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+fail() { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+# Resolve the skill root from this script's location, so the gate works from any CWD.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+SKILL_MD="$SKILL_DIR/SKILL.md"
+REF_DIR="$SKILL_DIR/references"
+
+# ---- 1. SKILL.md documents the safe patterns ----
+if [ -f "$SKILL_MD" ]; then
+  needles=(
+    "lock_timeout"
+    "CONCURRENTLY"
+    "NOT VALID"
+    "VALIDATE CONSTRAINT"
+    "Squawk"
+  )
+  missing=""
+  for n in "${needles[@]}"; do
+    grep -Fq "$n" "$SKILL_MD" || missing="$missing $n"
+  done
+  if [ -n "$missing" ]; then
+    fail "SKILL.md is missing required safe-migration concepts:$missing"
+  else
+    ok "SKILL.md documents lock_timeout, CONCURRENTLY, NOT VALID/VALIDATE, Squawk"
+  fi
+  # The body must show a Bad->Good contrast (it teaches by counter-example).
+  if grep -Eq -- '--[[:space:]]*Bad' "$SKILL_MD" && grep -Eq -- '--[[:space:]]*Good' "$SKILL_MD"; then
+    ok "SKILL.md shows Bad->Good DDL contrasts"
+  else
+    fail "SKILL.md should contrast a Bad vs Good DDL fence"
+  fi
+else
+  fail "SKILL.md not found at $SKILL_MD"
+fi
+
+# ---- 2. Squawk / lint reference is shipped ----
+if [ -d "$REF_DIR" ] && grep -rIlq -- "squawk" "$REF_DIR" 2>/dev/null; then
+  ok "references/ ship a Squawk migration-lint reference"
+elif [ -d "$REF_DIR" ]; then
+  fail "references/ exist but no Squawk lint reference found (the body's CI gate is undocumented)"
+else
+  skip "no references/ dir — nothing to lint-reference yet"
+fi
+
+# ---- 3. Example .sql in references/ is itself safe ----
+SQL_FILES=()
+if [ -d "$REF_DIR" ]; then
+  while IFS= read -r -d '' f; do
+    SQL_FILES+=("$f")
+  done < <(find "$REF_DIR" -type f -name '*.sql' -print0 2>/dev/null)
+fi
+
+# The references ship example DDL inside fenced code blocks, not standalone .sql files. If real .sql
+# files exist, scan them; otherwise this is a clean skip (no false failure on an empty target).
+if [ "${#SQL_FILES[@]}" -eq 0 ]; then
+  skip "no standalone .sql files in references/ to scan (examples live in fenced code blocks)"
+else
+  for f in "${SQL_FILES[@]}"; do
+    # Strip line comments so a "-- Bad: ..." annotation never trips the scanner.
+    body="$(sed -e 's/--.*$//' "$f")"
+
+    # bare CREATE INDEX without CONCURRENTLY
+    if printf '%s' "$body" | grep -Eiq 'create[[:space:]]+(unique[[:space:]]+)?index' \
+       && ! printf '%s' "$body" | grep -Eiq 'create[[:space:]]+(unique[[:space:]]+)?index[[:space:]]+concurrently'; then
+      fail "$f: CREATE INDEX without CONCURRENTLY"
+    fi
+
+    # ADD COLUMN ... NOT NULL in one shot (the multi-step path uses a separate NOT VALID CHECK)
+    if printf '%s' "$body" | grep -Eiq 'add[[:space:]]+column[^;]*not[[:space:]]+null'; then
+      fail "$f: ADD COLUMN ... NOT NULL in a single statement"
+    fi
+
+    # any ALTER TABLE that is not preceded anywhere in the file by a lock_timeout
+    if printf '%s' "$body" | grep -Eiq 'alter[[:space:]]+table' \
+       && ! printf '%s' "$body" | grep -Fiq 'lock_timeout'; then
+      fail "$f: ALTER TABLE without a lock_timeout in the same file"
+    fi
+  done
+  [ "$EXIT" -eq 0 ] && ok "example .sql in references/ is free of forbidden DDL signatures (${#SQL_FILES[@]} files)"
+fi
+
+printf '\n'
+if [ "$EXIT" -eq 0 ]; then ok "verify.sh passed"; else fail "verify.sh found inconsistencies"; fi
+exit "$EXIT"