ADR-011 Policy-Trace ATO Evidence Statement (Closes #413)

On this page

Posture statement

Canopy’s eligibility-determination logic depends on hundreds of policy values — federal income thresholds, jurisdiction-specific deduction percentages, time limits, operational windows. Under ADR-011 every such value MUST be:

  • (a) in rulesets/{jurisdiction}/jurisdiction.toml with a matching entry in rulesets/{jurisdiction}/citations.toml pointing at an authoritative source (PAMMS section, federal CFR / USC citation, agency operational tunable), OR

  • (b) in rulesets/federal/*.json with an inline _citation field on the value, OR

  • (c) in compliance/adr-011-literal-allowlist.toml with a written rationale (e.g. "constant required by RFC X", "test fixture", "doc string").

There is no fourth case. A policy value that does not match (a), (b), or (c) fails the build. The four gates listed below collectively prove this.

This posture is the official ATO evidence for ADR-011. Every PR that touches a policy value re-runs the gates; CI rejects drift before it lands on main.

The four gates

Gate What it does Proves part of How to regenerate

cargo xtask policy audit

Walks every key in rulesets/{jurisdiction}/jurisdiction.toml and asserts a matching [citations."<key>"] entry exists with a non-empty source_ref, authority, and verified_date. Flags stale citations (older than the configurable freshness window). CI job: adr-011-policy-audit.

(a)

cargo xtask policy sync-cache && cargo xtask policy audit. Failures emit one line per missing or stale key — fix by adding the citation, refreshing verified_date, or removing the policy value.

cargo xtask rules check

Compiles every JDM ruleset under rulesets/{federal,jurisdiction}/ against the embedded zen-engine 0.55 schema. Catches malformed expression trees, dangling input refs, and missing _citation fields on federal value-tables. CI job: rules-check.

(b)

cargo xtask rules check. Failures emit the ruleset path + the failing node id.

cargo xtask policy audit-literals

Greps services/canopy-{snap,tanf,medicaid,caps,wic}/src//.rs and crates/canopy-contracts-/src//*.rs (657) for numeric literals in eligibility-determining code paths. Every match must either (i) live behind a param_table.<key> lookup, (ii) be in compliance/adr-011-literal-allowlist.toml with a reason, or (iii) be in a [cfg(test)] block. CI job: adr-011-literal-audit.

(c) — surfaces values that escaped (a) and (b)

cargo xtask policy audit-literals. Add a row to the allowlist when the value is legitimately not policy (e.g. Decimal::new(7, 0) for "days per week" — federal calendar constant, not eligibility policy).

cargo xtask policy audit-unwraps

Companion gate: scans services//src/*/params.rs for silent .unwrap_or(<numeric>) fallbacks on jurisdiction.toml reads. A silent numeric fallback masks a missing citation — the audit rejects them and requires .with_context(|| "<key> missing from jurisdiction.toml — required per ADR-011")? instead. CI job: adr-011-unwrap-audit.

(a) — closes the loophole where a missing TOML key would silently default to a hardcoded value

cargo xtask policy audit-unwraps. Failures emit file:line — convert the silent fallback to a with_context error.

End-to-end regeneration

Producing a fresh evidence pack for an ATO submission:

# 1. Refresh PAMMS source repos (PolicySource trait — Georgia uses GitLab clones).
cargo xtask policy sync-cache

# 2. Run all four gates.
cargo xtask policy audit
cargo xtask rules check
cargo xtask policy audit-literals
cargo xtask policy audit-unwraps

# 3. Snapshot the citation manifest for the evidence binder.
cp rulesets/georgia/citations.toml evidence/adr-011-citations-$(date +%Y-%m-%d).toml

All four commands exit 0 on a clean tree. Non-zero exits are the failure modes — every emitted line names the offending key / file / pattern.

What this does NOT prove

Per the scoping in ADR-011 §6, this evidence statement covers policy traceability only. It does not certify:

  • The accuracy of the cited value — a PAMMS section may have been amended after the citation’s verified_date. The audit emits staleness warnings (configurable threshold) but does not block on them; periodic re-verification is a separate operational process tracked in the evidence binder’s "currency review" log.

  • The semantic correctness of the JDM ruleset — cargo xtask rules check proves a ruleset compiles, not that it implements the cited policy correctly. Per-program unit + integration tests cover semantics; the JDM rewrite plan documents the determination-flow coverage.

  • The downstream use of FTI / IEVS / SSA data — those are covered by ADR-004 and the compliance-data-tenancy audit, not by ADR-011.

Allowlist hygiene

compliance/adr-011-literal-allowlist.toml is a narrow exception list. The audit rejects:

  • Empty reason fields.

  • Rows that match unbounded patterns (* alone).

  • Rows older than the freshness window without a verified_date refresh.

Per ADR-011 §5, every allowlist row is reviewed at each compliance currency cycle. Allowlist size on main as of {{revdate}} (regenerate via wc -l compliance/adr-011-literal-allowlist.toml).

Cross-references

Edit this page · default