ci(migrations): add migration safety linter

Adds a custom Python AST-based linter that fails CI on PRs introducing
the four anti-patterns the migration runtime defaults cannot reliably
catch on a quiet hour:

* op.create_index (and raw CREATE INDEX) without CONCURRENTLY,
  or with CONCURRENTLY but outside an autocommit_block().
* op.create_foreign_key (and raw ADD CONSTRAINT FOREIGN KEY)
  without NOT VALID.
* op.execute("UPDATE ...") / DELETE in-band data backfills.
* SET / RESET of lock_timeout, statement_timeout, or
  idle_in_transaction_session_timeout inside a migration file.

Each rule maps to a documented anti-pattern in CLAUDE.md.

Why custom AST instead of squawk: squawk operates on rendered SQL,
which loses the surrounding Alembic context (autocommit_block wrapping,
kwarg options on op.create_index/op.create_foreign_key) — exactly the
signals needed to distinguish safe and unsafe shapes here. AST
inspection of the migration source is tighter, has zero external deps,
runs in milliseconds, and lets each rule produce a message that points
at the correct fix.

Escape hatch: a `# migration-unsafe-ack: <one-line reason>` directive
at the top of the migration file suppresses all rules for that file.
The GitHub Actions workflow additionally checks for a
`migration-unsafe-ack` PR label; when present it runs the linter in
--warn-only mode so violations surface in logs without blocking merge.
Both signals are required to deploy a migration that intentionally
overrides the runner defaults.

The CI step lints only files changed in the PR (via
`--base-ref origin/<base>`), so existing migrations are not
retro-flagged.

Includes 12 unit tests covering each rule, the ack-directive escape
hatch (including that bare directives without a reason do not
suppress), and the autocommit_block detection.

Author: declan-scale

.github/workflows/migration-lint.yml

@@ -0,0 +1,50 @@
+name: Migration Safety Lint
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'agentex/database/migrations/alembic/versions/**.py'
+      - 'agentex/scripts/ci_tools/migration_lint.py'
+      - '.github/workflows/migration-lint.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  lint-migrations:
+    name: 'Lint changed migrations'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          # Need history back to the merge base so --base works.
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Detect migration-unsafe-ack label
+        id: ack_label
+        env:
+          LABELS: ${{ toJson(github.event.pull_request.labels.*.name) }}
+        run: |
+          if echo "$LABELS" | grep -q '"migration-unsafe-ack"'; then
+            echo "ack=1" >> "$GITHUB_OUTPUT"
+            echo "::notice title=migration-unsafe-ack label present::Linter will not fail the build, findings will surface as warnings only."
+          else
+            echo "ack=0" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Lint migrations
+        env:
+          MIGRATION_UNSAFE_ACK: ${{ steps.ack_label.outputs.ack }}
+          BASE_REF: ${{ github.event.pull_request.base.ref }}
+        run: |
+          set -euo pipefail
+          # Make the merge base reachable so --base diff works.
+          git fetch --no-tags --depth=1 origin "$BASE_REF"
+          python3 agentex/scripts/ci_tools/migration_lint.py --base "origin/$BASE_REF"

.pre-commit-config.yaml

@@ -25,3 +25,9 @@ repos:
         files: ^agentex/(src/.*|scripts/generate_openapi_spec\.py)$
         pass_filenames: false
 
+      - id: migration-safety-lint
+        name: 'lint Alembic migrations for dangerous Postgres patterns'
+        language: system
+        entry: agentex/scripts/git_hooks/migration_safety_lint.sh
+        files: ^agentex/database/migrations/alembic/versions/.*\.py$
+