Skip to main content
This is the operating manual for how we detect regulatory change and keep our compliance system of record current. It ties together the scripts, the weekly GitHub Actions job, the deep-dive agent, and the artifacts they read and write.

​
The picture

Three automated tripwires run weekly (Mon 09:00 UTC, .github/workflows/regulatory-watch.yml), plus one human-driven deep-dive agent: Every issue is labeled regulatory,compliance and links back to the affected specs from REGULATORY_COMPLIANCE_TRACKER.md.

​
1. Federal Register watcher

scripts/audit/check-regulatory-changes.ts (npm run audit:regulatory-changes).
  • Pulls FR documents published in the lookback window (--days=7 in CI).
  • Maps each to tracked regulations via distinctive CFR/CMS tokens parsed from REGULATORY_COMPLIANCE_TRACKER.md.
  • AI semantic fallback (optional): when AI_GATEWAY_API_KEY is set, documents that the keyword matcher misses get a semantic pass (scripts/audit/lib/ai-spec-matcher.ts) routed through the PF-111 Vercel AI Gateway — one gateway/secret shared with the runtime edge functions + eval harness, so no per-feature Anthropic key is needed (#1125). Degrades to keyword-only if the key is absent or the call fails. Model is anthropic/claude-sonnet-4.6 by default (the GR standard lane; REGULATORY_AI_MODEL to override).
  • Files an issue per material new document and records it in REGULATORY_CHANGES_LOG.json so it’s never re-filed.
Coverage limit: Federal Register only. State, AHCCCS, and CFR-codification events are the curated watcher’s and the agent’s job.

​
2. Curated source watcher

scripts/audit/check-source-regulatory-changes.ts (npm run audit:regulatory-sources).
  • Watch list lives in REGULATORY_SOURCES.json — AHCCCS policy manuals, AZ ADHS licensing, Arizona CSPMP, CMS BH/prior-auth pages, ASTP/ONC certification, SAMHSA Part 2. Each entry maps to the specs it affects.
  • Fetches each page, normalizes to text (strips scripts/styles/markup), and content-hashes it. A changed hash files one issue; the first observation only records a baseline (no issue), so adding a source doesn’t spam.
  • State lives in SOURCE_REGULATORY_CHANGES_LOG.json.
A content-hash change is a tripwire, not a diff — it means “this page moved, look at it”, not “rule X changed”. Triage the page, then act. Adding a source: append to REGULATORY_SOURCES.json with id, name, jurisdiction, url, and the mapped specIds. Next run baselines it.

​
3. Deadline alerts

scripts/audit/check-regulatory-deadlines.ts (npm run audit:regulatory-deadlines:ci).
  • Reads REGULATORY_DEADLINE_CALENDAR.json.
  • In CI (--file-issue) it upserts a single rolling issue, “Upcoming & overdue compliance deadlines”, listing everything overdue or due within 60 days. The issue is closed automatically when nothing is overdue or upcoming.
  • Locally, run without flags for a console report, or --fail-on-overdue to gate.
Keeping it accurate: when a deadline is met or slips, update both REGULATORY_DEADLINE_CALENDAR.json and REGULATORY_COMPLIANCE_TRACKER.md.

​
4. Deep-dive agent

automation/agents/regulatory-change-watcher.md (Sonnet; WebSearch/WebFetch). For interactive investigation the scripts can’t do — reasoning about a specific rule’s impact, researching an AHCCCS policy change, or scoping a new deadline. Read-only: it surfaces a prioritized impact analysis; it does not file issues or edit specs.

​
State persistence (why the workflow commits back)

The two watchers keep “what have I already seen” state in REGULATORY_CHANGES_LOG.json and SOURCE_REGULATORY_CHANGES_LOG.json. The weekly workflow runs with contents: write and commits those logs back after each run. Without that, every run would start blind and re-file duplicate issues. The commit uses [skip ci] so it doesn’t trigger other workflows.

​
Optional configuration

​
Artifacts at a glance

​
Running locally

Filing issues requires the gh CLI authenticated (GH_TOKEN); dry-run and the plain deadline report need no auth.