From 09d32cb8529a4bf3bb0fa4420cf67438041d0965 Mon Sep 17 00:00:00 2001
From: "Tj (bougyman) Vanderpoel" <bougyman@users.noreply.github.com>
Date: Wed, 12 Aug 2026 09:09:18 -0400
Subject: [PATCH] ci: catch and auto-fix AGENTS.md usage-rules drift

Nothing previously ran `mix usage_rules.sync` automatically, so an
ash/oban bump could silently drift AGENTS.md's generated block with
nothing catching it (verified it's currently in sync, but that's
incidental, not enforced). Adds a `--check` gate to ci.yaml for drift
introduced within a PR, plus a new usage-rules-sync workflow that
applies the sync and opens a PR if anything changed, for drift from
any other source. See #79.
---
 .github/workflows/ci.yaml               |  6 +++
 .github/workflows/usage-rules-sync.yaml | 56 +++++++++++++++++++++++++
 2 files changed, 62 insertions(+)
 create mode 100644 .github/workflows/usage-rules-sync.yaml

diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
index 0d80faa..2445487 100644
--- a/.github/workflows/ci.yaml
+++ b/.github/workflows/ci.yaml
@@ -47,6 +47,12 @@ jobs:
         run: mix deps.get
       -
         run: mix format --check-formatted
+      -
+        # Catches drift introduced within this PR (e.g. an ash/oban bump
+        # without re-running the sync) - see #79. The reactive auto-fix
+        # for drift from any other source lives in its own workflow
+        # (usage-rules-sync.yaml), not here.
+        run: mix usage_rules.sync --check
       -
         run: mix test
 
diff --git a/.github/workflows/usage-rules-sync.yaml b/.github/workflows/usage-rules-sync.yaml
new file mode 100644
index 0000000..695aefb
--- /dev/null
+++ b/.github/workflows/usage-rules-sync.yaml
@@ -0,0 +1,56 @@
+---
+name: usage-rules-sync
+
+on:  # yamllint disable-line rule:truthy
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  sync:
+    name: Sync AGENTS.md usage rules
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: app
+    steps:
+      -
+        uses: actions/checkout@v7
+      -
+        uses: erlef/setup-beam@v1
+        with:
+          otp-version: "29.0.3"
+          elixir-version: "1.20.3"
+          disable_problem_matchers: true
+      -
+        run: mix deps.get
+      -
+        # Applies non-interactively. Verified this is a no-op (exit 0, no
+        # changes) when AGENTS.md is already in sync with the current
+        # usage_rules config, so this workflow is safe to run on every
+        # push to main with no extra guard needed - see #79.
+        name: Sync AGENTS.md from the current usage_rules config
+        run: mix usage_rules.sync --yes
+      -
+        # No-op (no PR opened, nothing pushed) when there's nothing to
+        # commit - verified against the action's own docs. Note: a PR
+        # opened here via the default GITHUB_TOKEN queues ci.yaml's own
+        # run but leaves it pending manual approval (GitHub's anti-loop
+        # protection for token-authored PRs) - not a full CI skip, just
+        # an extra click before it runs.
+        name: Open a PR if the sync produced any changes
+        uses: peter-evans/create-pull-request@v8
+        with:
+          commit-message: "chore: sync AGENTS.md usage rules"
+          title: "chore: sync AGENTS.md usage rules"
+          body: >-
+            Auto-generated by the usage-rules-sync workflow - `mix
+            usage_rules.sync` found the checked-in AGENTS.md out of sync
+            with the current ash/oban usage-rules content and applied the
+            update.
+          branch: usage-rules-sync
+          delete-branch: true