Add local employee taxes

[MaxGhenis]

Summary

• add employee-side local wage and earnings taxes for Philadelphia, Kansas City, and St. Louis
• add employee-side Colorado occupational privilege taxes for Denver, Glendale, Greenwood Village, and Sheridan
• wire local income and occupational taxes into household tax so they affect household net income

Testing

• uv run pytest policyengine_us/tests/core/test_local_employee_taxes.py
• uv run pytest policyengine_us/tests/code_health/variable_names.py
• uv run python -m policyengine_core.scripts.policyengine_command test policyengine_us/tests/policy/baseline/gov/local/ny/nyc/tax/income -c policyengine_us
• uv run python -m policyengine_core.scripts.policyengine_command test policyengine_us/tests/policy/baseline/gov/irs/income/taxable_income/deductions/tax_unit_itemizes.yaml -c policyengine_us

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (85aa4ed) to head (6ae34d7).
⚠️ Report is 38 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##              main     #7843    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files            1        22    +21     
  Lines            8       236   +228     
  Branches         0         1     +1     
==========================================
+ Hits             8       236   +228     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[DTrim99]

PR Review

🔴 Critical (Must Fix)

1. Vectorization Bug in pa_philadelphia_wage_tax.py:22-23 - The early return pattern if not np.any(taxable_wages): return 0 returns a scalar instead of an array, which will cause silent failures in microsimulation. Remove this early return entirely - vectorized operations handle zeros correctly.

🟡 Should Address

1. Reference Issue - greenwood_village/.../employee_amount.yaml links to a broken 2010 PDF newsletter. Replace with: https://www.greenwoodvillage.com/1220/Occupational-Privilege-Tax-OPT

2. Reference URL Inaccessible - kansas_city/.../rate.yaml reference URL returns HTTP 403. Consider finding an alternative official source.

3. Deprecated documentation field - All 8 formula variables use documentation instead of relying on label + reference. Consider removing the redundant documentation fields.

4. Missing period metadata - Rate parameters (Kansas City, St. Louis, Philadelphia rates) should include period: year in metadata.

5. Missing unit attribute - The 4 Colorado _months input variables should have unit = "month".

6. No YAML tests - Only Python tests exist. Consider adding YAML tests in tests/policy/baseline/gov/local/ for standard test coverage.

🟢 Suggestions

1. Test coverage gaps - Consider adding tests for:

   • Zero income/wages/months scenarios
   • Negative value handling
   • Multiple people in a tax unit with different localities
   • Philadelphia resident + reduced rate combination
   • Historical rates for years 2022-2025 (only 2024 tested)
   • Partial months (1-11) for occupational taxes

2. Parameter descriptions - Could follow standard verb pattern (e.g., "Kansas City sets this rate for the municipal earnings tax.")

3. Effective date convention - 0000-01-01 is unconventional; consider 1900-01-01 or a realistic enactment date.

---

Validation Summary

Check	Result
Regulatory Accuracy	✅ All verified rates match official sources
Reference Quality	⚠️ 2 issues (Greenwood Village broken, Kansas City inaccessible)
Code Patterns	❌ 1 critical (vectorization bug), 5 moderate
Formatting (params & vars)	⚠️ 12 minor issues
Test Coverage	⚠️ Good basic coverage, gaps in edge cases
CI Status	✅ All checks passing

Verified Values

All tax rates were independently verified against official sources:

• ✅ Philadelphia resident: 3.79%→3.75%→3.74% (2022-2025)
• ✅ Philadelphia nonresident: 3.44%→3.43% (2022-2025)
• ✅ Philadelphia reduced: 1.5%
• ✅ Kansas City: 1%
• ✅ St. Louis: 1%
• ✅ Denver OPT: $5.75/month
• ✅ Glendale OPT: $5/month
• ✅ Greenwood Village OPT: $2/month
• ✅ Sheridan OPT: $3/month

What's Done Well

• ✅ Correct use of adds pattern for aggregation variables
• ✅ Consistent naming convention ({state}_{locality}_{program})
• ✅ Proper entity hierarchy (TaxUnit for taxes, Person for inputs)
• ✅ No hard-coded values in formulas
• ✅ Correct wiring into household_tax_before_refundable_credits
• ✅ Good integration test verifying taxes affect household net income

Next Steps

To auto-fix issues: /fix-pr 7843

Or address manually and re-request review.