Implement Alabama Unemployment Insurance (al_ui) (ref #8282)

changelog.d/al-ui.added.md

@@ -0,0 +1 @@
+Implement Alabama Unemployment Insurance (al_ui).

lessons/agent-lessons.md

@@ -0,0 +1,37 @@
+# Agent Lessons Learned
+
+Accumulated from /encode-policy-v2 and /backdate-program runs across all contributors.
+Loaded by implementation agents on future runs.
+
+## New Lessons from Alabama UI Implementation (2026-05-14)
+
+### PARAMETER
+- Restrict parameter descriptions to the authorized verb set (limits/provides/sets/excludes/deducts/uses); reject synonyms like "requires" even when grammatically correct.
+- Drop explanatory tails from parameter descriptions after the canonical "X provides this Y under the Z program." form; trailing "to determine..." or "based on..." clauses are noise.
+- Strip trailing zeros from decimal parameter values (e.g., 44.50 to 44.5) so the YAML matches the canonical numeric form.
+- Include the program acronym in parameter labels (e.g., "Alabama UI state unemployment rate" not "Alabama state unemployment rate") so labels are unambiguous when multiple programs share a state.
+
+### VARIABLE
+- Remove inline statute-restatement comments when the class-level `reference` already cites the same authority; keep inline comments only for non-obvious idioms (e.g., half-down rounding) or non-obvious parameter timing.
+- Replace hard-coded weeks-per-year integers (52) with framework constants like `WEEKS_IN_YEAR`; the same rule applies to other calendar constants.
+- Inline single-use intermediates (e.g., `uncapped_mba = ...; return np.round(uncapped_mba)`) into the return expression when the intermediate name adds no clarity over the operations.
+
+### FORMULA
+- Do not wrap a partial-benefit calculation that already returns 0 at the unemployed boundary in a redundant `where(earnings < WBA, partial, WBA)` selector; the wrapper silently pays full WBA when earnings meet or exceed WBA.
+- Test the partial-benefit boundary explicitly at earnings = WBA and earnings > WBA expecting 0; passing tests on earnings < WBA do not exercise the formula's exit branch.
+
+### REFERENCE
+- A procedural Admin Code section (filing mechanics, deadlines, recordkeeping) cannot serve as the citation authority for a substantive amount or rate; cite the substantive statute or rule that establishes the value.
+- When an Admin Code rule has not been republished since a later statutory amendment changed the value, follow the statute and cite it; document the staleness so future contributors do not "fix" the model back to the obsolete admin-code figure.
+- USDOL Comparison-of-State-UI-Laws "Minimum Wages Needed to Qualify" columns are derived illustrative figures (assumes equal-quarter wage pattern), not statutory floors; do not encode them as parameters.
+
+### TEST
+- Reform-helper Python modules that set parameter-driven enum or bracket values for YAML tests belong alongside the YAML tests in the test directory; document the unusual placement in a header comment so future readers do not move them.
+- After fixing a formula bug discovered post-implementation, add the missing boundary test in the same commit so the regression is locked in immediately.
+
+### WORKFLOW
+- When the reference implementation for a new program lives in a sibling PR not yet merged, read it from the parent repo path rather than expecting it on the current worktree base; coordinate this in the implementation spec.
+- Clean `__pycache__` directories between worktrees that share a parent path to avoid `conftest.py` collisions that intermittently block test collection.
+- When two reviewers conflict on statute-vs-admin-code authority, resolve via the more recent enactment date and the substantive-vs-procedural distinction; record the rationale in the PR so the next contributor inherits the decision.
+- Honor user-driven historical-scope simplifications (e.g., "2020 onward only") by collapsing pre-scope dated entries and trimming reference research to the in-scope window; do not silently encode out-of-scope history.
+

policyengine_us/parameters/gov/states/al/dol/unemployment_insurance/eligibility/bpw_to_hqw_multiplier.yaml

@@ -0,0 +1,16 @@
+description: Alabama sets this multiple of high quarter wages as the minimum total base period wages required under the Unemployment Compensation program.
+
+values:
+  2020-01-01: 1.5
+
+metadata:
+  unit: /1
+  period: year
+  label: Alabama UI base period wages to high quarter wages multiplier
+  reference:
+    - title: Code of Alabama § 25-4-77(a)(4)(a)
+      href: https://law.justia.com/codes/alabama/title-25/chapter-4/article-4/section-25-4-77/
+    - title: Alabama UC Benefit Rights and Responsibilities Handbook
+      href: https://labor.alabama.gov/docs/guides/uc_brr.pdf#page=8
+    - title: U.S. DOL Comparison of State UI Laws 2023, Table 3-2
+      href: https://oui.doleta.gov/unemploy/pdf/uilawcompar/2023/monetary.pdf#page=5

policyengine_us/parameters/gov/states/al/dol/unemployment_insurance/eligibility/quarters_with_wages.yaml

@@ -0,0 +1,16 @@
+description: Alabama sets this minimum number of calendar quarters of the base period in which wages must have been paid under the Unemployment Compensation program.
+
+values:
+  2020-01-01: 2
+
+metadata:
+  unit: int
+  period: year
+  label: Alabama UI required quarters with wages
+  reference:
+    - title: Code of Alabama § 25-4-77(a)(4)
+      href: https://law.justia.com/codes/alabama/title-25/chapter-4/article-4/section-25-4-77/
+    - title: Alabama UC Benefit Rights and Responsibilities Handbook
+      href: https://labor.alabama.gov/docs/guides/uc_brr.pdf#page=7
+    - title: U.S. DOL Comparison of State UI Laws 2023, Table 3-2
+      href: https://oui.doleta.gov/unemploy/pdf/uilawcompar/2023/monetary.pdf#page=5

policyengine_us/parameters/gov/states/al/dol/unemployment_insurance/index.yaml

@@ -0,0 +1,9 @@
+metadata:
+  propagate_metadata_to_children: true
+  economy: false
+  household: true
+  reference:
+    - title: Code of Alabama 1975, Title 25, Chapter 4 — Unemployment Compensation
+      href: https://law.justia.com/codes/alabama/title-25/chapter-4/
+    - title: Alabama UC Benefit Rights and Responsibilities Handbook
+      href: https://labor.alabama.gov/docs/guides/uc_brr.pdf

policyengine_us/parameters/gov/states/al/dol/unemployment_insurance/mba/bpw_fraction.yaml

@@ -0,0 +1,14 @@
+description: Alabama limits the maximum benefit amount to this share of base period wages under the Unemployment Compensation program.
+
+values:
+  2020-01-01: 0.25
+
+metadata:
+  unit: /1
+  period: year
+  label: Alabama UI maximum benefit base period wages fraction
+  reference:
+    - title: Code of Alabama § 25-4-74(a)
+      href: https://law.justia.com/codes/alabama/title-25/chapter-4/article-4/section-25-4-74/
+    - title: U.S. DOL Comparison of State UI Laws 2023, Table 3-11
+      href: https://oui.doleta.gov/unemploy/pdf/uilawcompar/2023/monetary.pdf#page=26

policyengine_us/parameters/gov/states/al/dol/unemployment_insurance/mba/duration_weeks.yaml

@@ -0,0 +1,45 @@
+description: Alabama provides this maximum number of weeks of regular benefits under the Unemployment Compensation program.
+
+brackets:
+  - threshold:
+      2020-01-01: 0
+    amount:
+      2020-01-01: 14
+  - threshold:
+      2020-01-01: 0.0651  # Above 6.5%
+    amount:
+      2020-01-01: 15
+  - threshold:
+      2020-01-01: 0.0701  # Above 7.0%
+    amount:
+      2020-01-01: 16
+  - threshold:
+      2020-01-01: 0.0751  # Above 7.5%
+    amount:
+      2020-01-01: 17
+  - threshold:
+      2020-01-01: 0.0801  # Above 8.0%
+    amount:
+      2020-01-01: 18
+  - threshold:
+      2020-01-01: 0.0851  # Above 8.5%
+    amount:
+      2020-01-01: 19
+  - threshold:
+      2020-01-01: 0.0901  # Above 9.0% (statute caps at 20 weeks for AAU >= 9.5%)
+    amount:
+      2020-01-01: 20
+
+metadata:
+  type: single_amount
+  threshold_unit: /1
+  amount_unit: week
+  period: year
+  label: Alabama UI maximum weeks of regular benefits by unemployment rate
+  reference:
+    - title: Code of Alabama § 25-4-74(a)
+      href: https://law.justia.com/codes/alabama/title-25/chapter-4/article-4/section-25-4-74/
+    - title: Alabama Act 2019-204 summary
+      href: https://alabamaretail.org/news/unemployment-comp-weeks-weekly-benefits/
+    - title: U.S. DOL Comparison of State UI Laws 2023, Table 3-12
+      href: https://oui.doleta.gov/unemploy/pdf/uilawcompar/2023/monetary.pdf#page=29

policyengine_us/parameters/gov/states/al/dol/unemployment_insurance/partial/disregard_rate.yaml

@@ -0,0 +1,16 @@
+description: Alabama excludes this share of the weekly benefit amount from countable earnings before reducing partial unemployment benefits under the Unemployment Compensation program.
+
+values:
+  2020-01-01: 0.3333333333  # One-third of WBA per § 25-4-73 (amended 2015).
+
+metadata:
+  unit: /1
+  period: year
+  label: Alabama UI partial unemployment earnings disregard rate
+  reference:
+    - title: Code of Alabama § 25-4-73
+      href: https://law.justia.com/codes/alabama/title-25/chapter-4/article-4/section-25-4-73/
+    - title: U.S. DOL Comparison of State UI Laws 2023, Table 3-8
+      href: https://oui.doleta.gov/unemploy/pdf/uilawcompar/2023/monetary.pdf#page=20
+    - title: NELP — New Alabama Unemployment Insurance Law Makes Work Pay
+      href: https://www.nelp.org/new-alabama-unemployment-insurance-law-makes-work-pay/

policyengine_us/parameters/gov/states/al/dol/unemployment_insurance/state_unemployment_rate.yaml

@@ -0,0 +1,89 @@
+description: Alabama uses this seasonally-adjusted statewide average unemployment rate under the Unemployment Compensation program.
+
+values:
+  2020-01-01: 0.028
+  2020-02-01: 0.030
+  2020-03-01: 0.031
+  2020-04-01: 0.138
+  2020-05-01: 0.111
+  2020-06-01: 0.087
+  2020-07-01: 0.079
+  2020-08-01: 0.067
+  2020-09-01: 0.059
+  2020-10-01: 0.045
+  2020-11-01: 0.041
+  2020-12-01: 0.038
+  2021-01-01: 0.036
+  2021-02-01: 0.034
+  2021-03-01: 0.033
+  2021-04-01: 0.032
+  2021-05-01: 0.031
+  2021-06-01: 0.030
+  2021-07-01: 0.029
+  2021-08-01: 0.029
+  2021-09-01: 0.029
+  2021-10-01: 0.030
+  2021-11-01: 0.030
+  2021-12-01: 0.030
+  2022-01-01: 0.029
+  2022-02-01: 0.028
+  2022-03-01: 0.027
+  2022-04-01: 0.026
+  2022-05-01: 0.026
+  2022-06-01: 0.026
+  2022-07-01: 0.026
+  2022-08-01: 0.026
+  2022-09-01: 0.026
+  2022-10-01: 0.026
+  2022-11-01: 0.026
+  2022-12-01: 0.026
+  2023-01-01: 0.025
+  2023-02-01: 0.024
+  2023-03-01: 0.023
+  2023-04-01: 0.023
+  2023-05-01: 0.023
+  2023-06-01: 0.023
+  2023-07-01: 0.024
+  2023-08-01: 0.025
+  2023-09-01: 0.025
+  2023-10-01: 0.026
+  2023-11-01: 0.027
+  2023-12-01: 0.028
+  2024-01-01: 0.029
+  2024-02-01: 0.029
+  2024-03-01: 0.029
+  2024-04-01: 0.029
+  2024-05-01: 0.030
+  2024-06-01: 0.030
+  2024-07-01: 0.031
+  2024-08-01: 0.032
+  2024-09-01: 0.032
+  2024-10-01: 0.032
+  2024-11-01: 0.033
+  2024-12-01: 0.033
+  2025-01-01: 0.033
+  2025-02-01: 0.033
+  2025-03-01: 0.033
+  2025-04-01: 0.033
+  2025-05-01: 0.033
+  2025-06-01: 0.034
+  2025-07-01: 0.034
+  2025-08-01: 0.035
+  2025-09-01: 0.035
+  2025-10-01: 0.035
+  2025-11-01: 0.035
+  2025-12-01: 0.035
+  2026-01-01: 0.035
+  2026-02-01: 0.035
+  2026-03-01: 0.035
+  2026-04-01: 0.035
+
+metadata:
+  unit: /1
+  period: month
+  label: Alabama UI state unemployment rate
+  reference:
+    - title: FRED — Unemployment Rate in Alabama (ALUR)
+      href: https://fred.stlouisfed.org/series/ALUR
+    - title: U.S. Bureau of Labor Statistics — Local Area Unemployment Statistics (LAUS)
+      href: https://www.bls.gov/lau/

policyengine_us/parameters/gov/states/al/dol/unemployment_insurance/waiting_weeks.yaml

@@ -0,0 +1,16 @@
+description: Alabama excludes this many initial weeks from compensability under the Unemployment Compensation program.
+
+values:
+  2020-01-01: 1
+
+metadata:
+  unit: week
+  period: year
+  label: Alabama UI waiting weeks
+  reference:
+    - title: Alabama UC Benefit Rights and Responsibilities Handbook
+      href: https://labor.alabama.gov/docs/guides/uc_brr.pdf#page=9
+    - title: Ala. Admin. Code Chapter 480-4-3 — Benefits
+      href: https://admincode.legislature.state.al.us/administrative-code/480-4-3
+    - title: U.S. DOL Comparison of State UI Laws 2023, Table 3-7
+      href: https://oui.doleta.gov/unemploy/pdf/uilawcompar/2023/monetary.pdf#page=17

policyengine_us/parameters/gov/states/al/dol/unemployment_insurance/wba/max.yaml

@@ -0,0 +1,16 @@
+description: Alabama provides this amount as the maximum weekly benefit under the Unemployment Compensation program.
+
+values:
+  2020-01-01: 275
+
+metadata:
+  unit: currency-USD
+  period: week
+  label: Alabama UI maximum weekly benefit amount
+  reference:
+    - title: Code of Alabama § 25-4-72(b)(5)
+      href: https://law.justia.com/codes/alabama/title-25/chapter-4/article-4/section-25-4-72/
+    - title: Alabama Act 2019-204 summary
+      href: https://alabamaretail.org/news/unemployment-comp-weeks-weekly-benefits/
+    - title: Alabama UC Benefit Rights and Responsibilities Handbook
+      href: https://labor.alabama.gov/docs/guides/uc_brr.pdf#page=8

policyengine_us/parameters/gov/states/al/dol/unemployment_insurance/wba/min_threshold.yaml

@@ -0,0 +1,14 @@
+description: Alabama sets this amount as the minimum unrounded weekly benefit threshold under the Unemployment Compensation program.
+
+values:
+  2020-01-01: 44.5
+
+metadata:
+  unit: currency-USD
+  period: week
+  label: Alabama UI minimum unrounded weekly benefit threshold
+  reference:
+    - title: Code of Alabama § 25-4-72(b)(2)
+      href: https://law.justia.com/codes/alabama/title-25/chapter-4/article-4/section-25-4-72/
+    - title: Alabama UC Benefit Rights and Responsibilities Handbook
+      href: https://labor.alabama.gov/docs/guides/uc_brr.pdf#page=8

policyengine_us/programs.yaml

@@ -906,6 +906,17 @@ programs:
     verified_start_year: 2023
 
   # --- State programs ---
+  - id: al_ui
+    name: Alabama UI
+    full_name: Alabama Unemployment Compensation
+    category: Benefits
+    agency: Alabama Department of Workforce
+    status: complete
+    coverage: AL
+    variable: al_ui
+    parameter_prefix: gov.states.al.dol.unemployment_insurance
+    verified_years: "2020-2025"
+
   - id: co_oap
     name: Colorado OAP
     full_name: Colorado Old Age Pension