Policy Currency Runbook

On this page

How to keep canopy’s cited policy values provably current. The tooling is ADR-031 §1 (epic &59); the underlying traceability discipline is ADR-011.

The moving parts

cargo xtask policy audit

Deterministic, blocking. Validates both citation families — jurisdiction (rulesets/{j}/citations.toml ↔ jurisdiction.toml) and federal (rulesets/federal/citations.toml ↔ the JSON data files): completeness, reverse completeness (orphans), value consistency, staleness, source-pin schema, and the annual indexing windows (rulesets/federal/indexing.toml).

cargo xtask policy sync-cache --jurisdiction {j} [--pin]

Clones/pulls the PAMMS source repos into rulesets/{j}/.policy-cache/ and records the sync manifest (per-repo HEAD + per-cited-file SHA-256). --pin back-fills source_sha256 onto citations whose source_ref resolves in the cache (format-preserving; idempotent).

cargo xtask policy drift --jurisdiction {j} [--no-sync]

Advisory, never edits values. Re-syncs (unless --no-sync) and compares each committed source_sha256 pin against the current hash of its cited file. Exit 1 on drift; the adr-031-policy-drift CI job is permanently allow_failure: true.

When drift fires

A CHANGED: finding means the upstream manual section changed since the value was last verified — it does not mean the value is wrong. For each drifted source file:

  1. Re-read the section in the policy cache (rulesets/{j}/.policy-cache/<source_ref>, anchor in the citation’s section field). The drift report lists every affected citation with its manual_transmittal / effective_date / verified_date context.

  2. If the value changed upstream: update jurisdiction.toml, then the citation (value, effective_date, manual_transmittal, notes), and set verified_date to today.

  3. If the value is unchanged (editorial churn, unrelated edits in the same file): bump the citation’s verified_date to today.

  4. Re-pin: cargo xtask policy sync-cache --jurisdiction {j} --pin — the new hashes commit with your MR, and drift returns to clean.

A MISSING UPSTREAM: finding means the cited file no longer exists in the refreshed cache (moved or deleted upstream): find the section’s new home, update the citation’s source_ref, re-verify, re-pin.

When the audit fires

  • ORPHAN: — a citation targets a key/value that no longer exists. Fix the key, remove the citation, or (only when the value genuinely lives in JDM rule content / service code) allowlist it with a written reason in compliance/adr-031-citation-orphan-allowlist.toml.

  • OUT-OF-WINDOW: — an indexed federal family’s newest table predates the current annual window (warning inside the family’s publication grace, error after). Transcribe the new federal tables (FNS COLA / HHS FPL / ACF SMI / CMS-416 instructions) into a new rulesets/federal/*-{year}.json, cite it, and assign it in indexing.toml if the pattern doesn’t already match.

  • UNINDEXED: — a new federal data file has no indexing.toml family. Declare its cutover cadence or add it to the static family.

  • MISSING: / MISMATCH: / SCHEMA: — forward completeness, value consistency, and citation-schema findings per ADR-011; fix the cited value or the citation.

  • STALE: (warning) — verified_date older than 365 days: re-verify the value against its source and bump the date (re-pin while you’re there).

Annual cycle

The cutovers and grace windows live in rulesets/federal/indexing.toml (SNAP COLA Oct 1, FPL Jan 1, SMI Jul 1, CMS-416 Oct 1) — the audit flags an out-of-window family automatically, so the calendar enforces itself. The update procedure per family is in rulesets/federal/README.adoc.

New jurisdictions

A jurisdiction with a git-backed, PAMMS-like manual system gets the full loop (sync → pin → drift) via [policy_source] in its jurisdiction.toml (canopy_policy::source::PammsGitSource). A jurisdiction without one uses type = "manual": citations carry authority = "manual", every resolution answers manual-verification-required (ManualSource), and currency rests on the staleness check + the jurisdiction’s own verification process.

Edit this page · default