> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Regulatory Monitoring & Automation

> Runbook for how Encore OS detects regulatory change: Federal Register and curated AZ/AHCCCS/CMS/ONC source watchers, deadline alerts, and a deep-dive agent.

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:

| Layer                        | What it watches                                       | How                                                          | Output                                  |
| ---------------------------- | ----------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------- |
| **Federal Register watcher** | New federal RULE / PRORULE documents                  | FR API, keyword + optional AI semantic match to tracked regs | One GitHub issue per material new rule  |
| **Curated source watcher**   | AZ/AHCCCS, CMS sub-regulatory, ASTP/ONC, SAMHSA pages | Fetch + content-hash diff                                    | One GitHub issue per changed source     |
| **Deadline alerts**          | Known compliance deadlines                            | Calendar diff (≤60 days / overdue)                           | One rolling GitHub issue, kept current  |
| **Deep-dive agent**          | Anything the above can't reason about                 | `regulatory-change-watcher` agent (WebSearch/WebFetch)       | Prioritized impact analysis (read-only) |

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

| Secret / env          | Effect                                                                                                                                                                             |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AI_GATEWAY_API_KEY`  | Enables the AI semantic-match fallback in the FR watcher, routed through the PF-111 Vercel AI Gateway (shared with the runtime + eval harness). Without it, keyword matching only. |
| `REGULATORY_AI_MODEL` | Override the matcher model (default `anthropic/claude-sonnet-4.6`, the GR standard lane).                                                                                          |

## Artifacts at a glance

| File                                 | Role                                     | Maintained by                    |
| ------------------------------------ | ---------------------------------------- | -------------------------------- |
| `REGULATORY_COMPLIANCE_TRACKER.md`   | System of record (regs → specs → status) | Humans                           |
| `REGULATORY_DEADLINE_CALENDAR.json`  | Machine-readable deadlines               | Humans                           |
| `REGULATORY_SOURCES.json`            | Curated watch list                       | Humans                           |
| `REGULATORY_CHANGES_LOG.json`        | FR watcher seen-state                    | FR watcher (committed by CI)     |
| `SOURCE_REGULATORY_CHANGES_LOG.json` | Source watcher seen-state                | Source watcher (committed by CI) |

***

## Running locally

```bash theme={null}
# Federal Register (dry-run files nothing)
npm run audit:regulatory-changes -- --days=30 --dry-run

# Curated sources (dry-run)
npm run audit:regulatory-sources -- --dry-run

# Deadlines (console report)
npm run audit:regulatory-deadlines
```

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