Add Social Security retirement benefit calculation chain

[MaxGhenis]

Summary

Implements the full Social Security retirement benefit formula chain, transforming social_security_retirement from an input-only variable to a computed variable with 14 new variables and 20 new parameter files.

Variable chain

employment_income, self_employment_income (existing)
    → ss_covered_earnings_this_year (min(earnings, wage_base))
    → ss_aime (45-year lookback, NAWI indexing, highest 35 / 420)
    → ss_pia (90/32/15% bend point formula)
    → ss_retirement_age_adjustment_factor (early/delayed credits)
    → ss_retirement_benefit_before_earnings_test (PIA × factor × 12)
    → ss_earnings_test_reduction (excess earnings × rate)
    → social_security_retirement (benefit - reduction)

Key design decisions

• Microsim compatibility: social_security_retirement branches between reported (CPS) and computed values via reported_social_security_retirement simulation parameter. CPS input values override the formula automatically.
• AIME is input-overridable: ss_aime_input lets users enter their AIME from their SSA statement, bypassing the 45-year lookback.
• Claiming age vs current age: ss_claiming_age defaults to age but can be set independently to model e.g. a 70-year-old who claimed at 62.
• Full longitudinal lookback: AIME computation loops over 45 years with period.offset(), indexing each year's earnings by NAWI ratio.
• All parameters are reformable: bend point factors, FRA, wage base, earnings test thresholds/rates, early/delayed retirement rates, minimum retirement age.

Files changed

• 14 new variable files under variables/gov/ssa/social_security/
• 1 modified variable: social_security_retirement.py (added formula with reported/computed branching)
• 20 new parameter files under parameters/gov/ssa/social_security/ and parameters/gov/simulation/
• 12 test files with 78 YAML tests (unit, integration, multi-year earnings history)

Test plan

• 78 YAML tests pass: policyengine-core test .../gov/ssa/social_security/ -c policyengine_us
• Microsim backward compatibility verified (SS retirement total ~$1T)
• make format passes
• CI passes

🤖 Generated with Claude Code