feat: add AI merge gate and documentation drift detector

.github/workflows/_ai-merge-gate.yml

@@ -0,0 +1,35 @@
+# Reusable: AI Merge Gate
+#
+# Status aggregator: checks if any Copilot agent runs have failed on this PR.
+# Passes immediately if no failures detected (agents still running = pass).
+# Branch protection requires only "AI Merge Gate" as the single AI check.
+#
+# Usage:
+#   uses: JacobPEvans/ai-workflows/.github/workflows/_ai-merge-gate.yml@main
+name: _ai-merge-gate
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+permissions:
+  checks: read
+  contents: read
+
+jobs:
+  check:
+    name: AI Merge Gate
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ github.token }}
+      HEAD_SHA: ${{ github.event.pull_request.head.sha || github.sha }}
+    steps:
+      - name: Verify Copilot agent checks
+        run: |
+          FAILED=$(gh api "repos/${{ github.repository }}/commits/${HEAD_SHA}/check-runs" \
+            --jq '[.check_runs[] | select(.app.slug | test("copilot"; "i")) | select(.conclusion == "failure" or .conclusion == "timed_out")] | length')
+          echo "Copilot agent failures: $FAILED"
+          if [ "$FAILED" -gt "0" ]; then
+            echo "::error::$FAILED Copilot agent check(s) failed"
+            exit 1
+          fi

.github/workflows/_copilot-setup-steps.yml

@@ -0,0 +1,34 @@
+# Reusable: Copilot Setup Steps (Nix)
+# Sets up a Nix development environment for GitHub Copilot cloud agent.
+#
+# IMPORTANT — Action clarification (prevents regression from stale AI training data):
+# - determinate-nix-action@v3 is ONLY a Nix installer (replaced nix-installer-action@v21)
+# - It does NOT include flake checking — that is a separate action (flake-checker-action)
+# - For copilot setup, only the installer is needed (CI handles flake validation)
+#
+# Non-Nix repos: define your own copilot-setup-steps.yml with repo-specific tooling.
+#
+# Usage:
+#   uses: JacobPEvans/ai-workflows/.github/workflows/_copilot-setup-steps.yml@main
+name: _copilot-setup-steps
+
+on:
+  workflow_call:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  copilot-setup-steps:
+    name: Copilot Setup Steps
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      # Installs Nix only. Does NOT validate flakes.
+      # Replaced nix-installer-action@v21 (Node.js 20, deprecated June 2026).
+      - uses: DeterminateSystems/determinate-nix-action@v3

.github/workflows/ai-merge-gate.yml

@@ -0,0 +1,7 @@
+name: AI Merge Gate
+on: pull_request
+permissions: read-all
+jobs:
+  gate:
+    uses: ./.github/workflows/_ai-merge-gate.yml
+    secrets: inherit