ci: catch and auto-fix AGENTS.md usage-rules drift - #88
Merged
Conversation
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.
There was a problem hiding this comment.
Pull request overview
This PR adds automated safeguards to prevent AGENTS.md’s generated usage-rules block from drifting silently when dependencies (e.g., ash/oban) change, aligning with the maintenance goals in issue #79.
Changes:
- Adds a CI gate to fail PRs when
AGENTS.md’s generated usage-rules block is out of sync (mix usage_rules.sync --check). - Introduces a dedicated workflow that auto-runs the sync on pushes to
main(and via manual dispatch) and opens a PR when updates are needed.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| .github/workflows/usage-rules-sync.yaml | New workflow to run mix usage_rules.sync --yes and open a PR if it produces changes. |
| .github/workflows/ci.yaml | Adds mix usage_rules.sync --check to the existing test job to catch drift within PRs. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
bougyman
force-pushed
the
issue-79-usage-rules-sync
branch
from
August 12, 2026 18:30
501d5f4 to
5bb3878
Compare
6 tasks
bougyman
added a commit
that referenced
this pull request
Aug 12, 2026
…t hook (#90) ## Summary - `mix git_hooks` sets `core.hooksPath` to `githooks/` (idempotent). `mix setup` runs it, and is expected to grow more steps over time as more repo-management tasks land in this project. - Adds a new `pre-push` hook alongside the existing `commit-msg` one - reuses `ci/conventional_commits.sh` as-is (no changes needed: with no env vars set it already falls back to `main`/`origin/main` as base and the current branch as head, exactly right for a local push) to catch anything that slipped past `commit-msg` (a commit made before the hooks were installed, an amend, etc.), not just the current `HEAD`. - Removes `app/lib/mix/tasks/githooks.install.ex` - an exact duplicate of this same idea living in `app/`'s own mix project instead of the new top-level one. - Updates `Readme.adoc`/`AGENTS.md`/`app/usage-rules.md`'s references to the old manual `git config core.hooksPath githooks` / `mix githooks.install` steps to point at `mix setup` instead. ## Test plan - [x] `mix setup` run twice - installs cleanly, idempotent (identical output, no error) - [x] `githooks/pre-push` run directly - exits 0 against this branch's own commits - [x] The underlying validation logic is already proven to catch bad subjects for real: this exact `ci/conventional_commits.sh` failed CI on PR #88's badly-worded merge commit earlier today - [x] `mix test`/`mix format --check-formatted` clean in both projects (root and `app/`) - [x] `mix usage_rules.sync --check` still passes after editing `app/usage-rules.md` - [x] Confirmed no remaining references anywhere to the removed `githooks.install` task 🤖 Generated with [Claude Code](https://claude.com/claude-code)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #79. Nothing previously ran
mix usage_rules.syncautomatically, so an ash/oban version bump could silently driftAGENTS.md's generated block with nothing catching it.mix usage_rules.sync --checktoci.yaml'stestjob (right aftermix format --check-formatted) - catches drift introduced within a reviewed PR.usage-rules-sync.yamlworkflow (push tomain+workflow_dispatch) that applies the sync non-interactively and opens a PR viapeter-evans/create-pull-request@v8if anything changed - catches drift from any other source.Test plan
mix usage_rules.sync --check- currently exits0(already in sync)--checkactually catches drift: deliberately broke a line inAGENTS.md, confirmed it exits non-zero with a diff, restored the originalmix usage_rules.sync --yesis a safe no-op (exit 0, no changes) against the current in-sync stateactionlintclean on all three workflow files (re-verified after merging in everything that's landed onmainsince this branch was cut, including the repo rename and the new root-level Mix project)mix format --check-formatted && mix usage_rules.sync --check) - passespeter-evans/create-pull-request@v8is a real current tag via the GitHub API directlyNote
The bot-authored PR (when drift is found) queues
ci.yaml's own run via the defaultGITHUB_TOKEN, but GitHub's anti-loop protection leaves it pending manual approval rather than running automatically - not a blocker, just an extra click.🤖 Generated with Claude Code