pipeline_miami/verify/served_invariants_allowlist.yaml

# Shift alarms from pipeline_miami/verify/served_invariants.py that have a
# documented cause. An entry explains an alarm; it never silences the check.
# Only causes stated in the comparability config, a publisher's own notes or a
# measurement recorded in docs/cities/miami are recorded here; every other
# alarm stays REVIEW until someone looks.
#
# Keys: metric_key (exact, or a glob such as fast_*_proficiency), year (one) or
# years (a list), kind (median | count). Entries that match no current alarm
# are listed as stale at the end of __served_invariants.md and should be removed.
# Reworked 2026-09-16b (review N8): the rule now compares each year with the
# previous served year against the series' own year-to-year moves, so a
# one-year step alarms twice (the step and the return) and district-wide
# events are recorded once as a pattern.

# ── Assessments: FAST / B.E.S.T. baseline and recovery (comparability.yaml fl_assessment boundary 2022-23) ──
- metric_key: "fast_*_proficiency"
  years: ["2022-23", "2023-24", "2024-25"]
  kind: median
  reason: "FAST informational baseline in 2022-23 (first administration; comparability.yaml fl_assessment boundary 2022-23) and the recovery in the two operational years after it: every FAST grade and subject rose 3–8 pp a year; the served cells are re-read from the state's 63 SRS files by the base case"
- metric_key: "eoc_*_proficiency"
  years: ["2022-23", "2023-24", "2024-25"]
  kind: median
  reason: "B.E.S.T. EOC baseline in 2022-23 (comparability.yaml fl_assessment boundary 2022-23) and the recovery after it; served cells re-read from the SRS files by the base case"
- metric_key: "*_achievement"
  years: ["2023-24"]
  kind: median
  reason: "School Grades components in the first operational FAST/B.E.S.T. year after the 2022-23 informational baseline (comparability.yaml fl_assessment boundary 2022-23): ELA, math and science each rose 5 pp"
- metric_key: "learning_gains_*"
  years: ["2023-24"]
  kind: median
  reason: "Learning gains are computed within a test regime; 2023-24 is the first year with two FAST administrations to compare (comparability.yaml school_grades boundary 2022-23)"
- metric_key: school_grade_points_pct
  year: "2024-25"
  kind: median
  reason: "Points rose with every component in the third FAST year (comparability.yaml school_grades); the components' own alarms are explained above"
# ── 2018-19 against 2021-22: the FSA regime against the first post-pandemic year, two excluded years between (comparability.yaml fl_assessment / school_grades) ──
- metric_key: math_achievement
  years: ["2018-19", "2021-22"]
  kind: median
  reason: "2018-19 (FSA) is compared with 2021-22, the first post-pandemic School Grades year, because 2019-20 issued no grades and 2020-21 was opt-in (comparability.yaml school_grades excluded years); the 7-pp drop is the pandemic loss under one test regime"
- metric_key: "learning_gains_math*"
  years: ["2018-19", "2021-22"]
  kind: median
  reason: "As math_achievement 2018-19 / 2021-22: gains in 2021-22 are measured against 2018-19 baselines for many students after the two excluded years (comparability.yaml school_grades)"
# ── Attendance: pandemic years excluded from the chronic_absenteeism regime (comparability.yaml) ──
- metric_key: chronic_absenteeism_rate
  years: ["2020-21", "2021-22"]
  kind: median
  reason: "2019-20 and 2020-21 are excluded from the chronic_absenteeism regime (comparability.yaml); the median rose from 15% to 21% in the remote year and to 26% in 2021-22, the national post-pandemic level; served cells re-read from the state files by the base case and checked against EDFacts (cross-publisher check)"
- metric_key: absent_21plus_rate
  years: ["2020-21", "2021-22"]
  kind: median
  reason: "As chronic_absenteeism_rate 2020-21 / 2021-22 (same file, same excluded years)"
# ── Climate survey: participation and the pandemic year ──
- metric_key: "survey_*"
  kind: count
  reason: "The count of schools with a served composite is the workbook's own school list minus the schools it withholds under 10 responses, which varies by year (parsed n<10 school counts 2018-19 → 2024-25: students 7 / 69 / 98 / 52 / 44 / 105 / 81; parents 8 / 112 / 104 / 59 / 121 / 126; staff 60 / 46 / 43 / 45 / 56 / 55 / 48); every served composite is re-read from its workbook by the base case, so the count is a property of the file, not of the load"
- metric_key: "survey_*"
  years: ["2019-20", "2020-21", "2021-22"]
  kind: median
  reason: "2020-21 was the remote/hybrid year (comparability.yaml flagged year): students' safety and leadership composites rose 4–5 pp, staff safety and resources 3–4 pp, the students' response rate from 36% to 50% and then 64%, and the 2021-22 values are the return; the workbooks' own values, re-read by the base case for 2019-20, 2020-21, 2021-22 and 2022-23 composites. 2019-20 is included because it is the first served staff year (the 2018-19 staff workbook was retired 2026-09-16) and a first year is compared with the next, i.e. with the remote year"
- metric_key: "survey_parents_*"
  years: ["2018-19", "2020-21"]
  kind: median
  reason: "The 2018-19 parent workbook withholds 8 schools under 10 responses against 112 in 2020-21 (parsed n<10 counts): the composite's median moves with the school set (the 2020-21 alarm is the same step seen from the other side)"
# ── Economic disadvantage: Community Eligibility changes the reported share (decision M.8) ──
- metric_key: pct_econ_disadv
  year: "2024-25"
  kind: median
  reason: "The School Grades file's share is not comparable across Community Eligibility Provision status (decision M.8, docs/cities/miami/03_integration_plan.md); the district-wide median fell 6 pp in 2024-25 with the file's own values (base case re-read). Sits at the alarm threshold (lift 3.1), so it appears and disappears with small changes in the school universe."
# ── English learners: the exact share is served only where the file hides no race cell ──
- metric_key: pct_ell
  kind: count
  reason: "pct_ell is exact only for schools whose ELL file hides no race cell (2026-09-16 accuracy fixes: hidden cells are intervals of 0–9 students, served as pct_ell_lower_bound / pct_ell_upper_bound); the exact share covers 76–108 schools a year and its count moves with how many cells the file hides, not with the load. The model and the peer groups use the lower bound, whose coverage is complete."
# ── October membership by grade: the 2022-23 file leaves zero cells blank ──
- metric_key: "enrollment_oct_g*"
  years: ["2022-23", "2023-24"]
  kind: count
  reason: "The 2022-23 membership file leaves about 25 zero grade cells blank that the adjacent years print as 0 (of the 31 schools without a grade-3 cell in 2022-23, 24 show 0 in 2021-22 and 26 in 2023-24; 2022-23 has 190 zero grade-3 cells against 213–220 in the other years); the served cells match the file (base case enrollment_oct_g3 2022-23), so the count drops in 2022-23 and recovers in 2023-24"
- metric_key: "enrollment_oct_g*"
  years: ["2022-23", "2023-24"]
  kind: median
  reason: "As the count entry: with the zero cells absent from 2022-23 the median of the remaining cells is higher that year and returns in 2023-24"
# ── Reference series ──
- metric_key: enrollment_oct_ccd
  years: ["2018-19", "2022-23"]
  kind: count
  reason: "The federal CCD directory lists 510 Dade schools in 2018-19 and 534 in 2022-23 (its own school list; charter openings in between); a reference-only series compared with the state count school by school in the cross-publisher check"
- metric_key: per_pupil_expenditure_school_federal
  year: "2024-25"
  kind: median
  reason: "Federal ESSER relief funds had to be obligated by 30 September 2024, so federal per-pupil spending fell in 2024-25 (the state and local series do not move)"