Fix CPP formula, values, references, and rebase on master

- Cap benefit at maximum_monthly: min_(avg * factor, max) * 12
- Extract hard-coded 40 into max_contributory_years parameter
- Fix 2025 average monthly: $844.53 → $803.76 per canada.ca
- Add reference URLs to all 3 variable files
- Move tests to tests/gov/cra/benefits/cpp/ (correct path)
- Add changelog fragment
- Update parameter descriptions to active-voice format

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: PavelMakarchuk

changelog.d/525.added.md

@@ -0,0 +1 @@
+Added CPP retirement pension calculation with eligibility, contribution history, and benefit parameters.

policyengine_canada/parameters/gov/cra/benefits/cpp/retirement/average_monthly.yaml

@@ -1,15 +1,15 @@
-description: Average monthly CPP retirement pension at age 65
+description: The Canada Pension Plan applies this average monthly amount for retirement pension benefits at age 65.
 values:
   2020-01-01: 710.41
   2021-01-01: 702.77
   2022-01-01: 727.61
   2023-01-01: 758.32
   2024-01-01: 816.52
-  2025-01-01: 844.53
+  2025-01-01: 803.76
 metadata:
   unit: currency-CAD
   period: month
   label: CPP average monthly retirement pension
   reference:
     - title: CPP retirement pension amount
-      href: https://www.canada.ca/en/services/benefits/publicpensions/cpp/cpp-benefit/amount.html
+      href: https://www.canada.ca/en/services/benefits/publicpensions/cpp/cpp-benefit/amount.html

policyengine_canada/parameters/gov/cra/benefits/cpp/retirement/eligibility_age.yaml

@@ -1,4 +1,4 @@
-description: Minimum age for CPP retirement pension eligibility
+description: The Canada Pension Plan requires this minimum age for retirement pension eligibility.
 values:
   2020-01-01: 60
 metadata:
@@ -7,4 +7,4 @@ metadata:
   label: CPP retirement pension eligibility age
   reference:
     - title: CPP retirement pension eligibility
-      href: https://www.canada.ca/en/services/benefits/publicpensions/cpp/cpp-benefit/eligibility.html
+      href: https://www.canada.ca/en/services/benefits/publicpensions/cpp/cpp-benefit/eligibility.html

policyengine_canada/parameters/gov/cra/benefits/cpp/retirement/max_contributory_years.yaml

@@ -0,0 +1,10 @@
+description: The Canada Pension Plan sets this as the maximum number of contributory years used to calculate the retirement pension.
+values:
+  1966-01-01: 40
+metadata:
+  unit: year
+  period: year
+  label: CPP maximum contributory years
+  reference:
+    - title: Canada Pension Plan (R.S.C., 1985, c. C-8)
+      href: https://laws-lois.justice.gc.ca/eng/acts/c-8/page-5.html

policyengine_canada/parameters/gov/cra/benefits/cpp/retirement/maximum_monthly.yaml

@@ -1,4 +1,4 @@
-description: Maximum monthly CPP retirement pension at age 65
+description: The Canada Pension Plan sets this maximum monthly amount for retirement pension benefits at age 65.
 values:
   2020-01-01: 1_175.83
   2021-01-01: 1_203.75
@@ -12,4 +12,4 @@ metadata:
   label: CPP maximum monthly retirement pension
   reference:
     - title: CPP retirement pension amount
-      href: https://www.canada.ca/en/services/benefits/publicpensions/cpp/cpp-benefit/amount.html
+      href: https://www.canada.ca/en/services/benefits/publicpensions/cpp/cpp-benefit/amount.html

…benefits/cpp/cpp_retirement_pension.yaml …benefits/cpp/cpp_retirement_pension.yamlpolicyengine_canada/tests/benefits/cpp/cpp_retirement_pension.yaml renamed to policyengine_canada/tests/gov/cra/benefits/cpp/cpp_retirement_pension.yaml policyengine_canada/tests/benefits/cpp/cpp_retirement_pension.yaml renamed to policyengine_canada/tests/gov/cra/benefits/cpp/cpp_retirement_pension.yaml

@@ -41,8 +41,8 @@
     cpp_years_of_contribution: 45
   output:
     # Capped at 40 years = full average benefit
-    # $844.53 * 12 = $10,134.36
-    cpp_retirement_pension: 10_134.36
+    # $803.76 * 12 = $9,645.12
+    cpp_retirement_pension: 9_645.12
 
 - name: Minimum contribution scenario
   period: 2024
@@ -52,4 +52,4 @@
   output:
     # 1/40 years = 2.5% of average benefit
     # $816.52 * 0.025 * 12 = $244.956
-    cpp_retirement_pension: 244.956
+    cpp_retirement_pension: 244.956

policyengine_canada/variables/gov/cra/benefits/cpp/cpp_retirement_eligible.py

@@ -7,16 +7,17 @@ class cpp_retirement_eligible(Variable):
     label = "Eligible for CPP retirement pension"
     definition_period = YEAR
     documentation = "Whether person is eligible for CPP retirement pension"
-    
+    reference = "https://www.canada.ca/en/services/benefits/publicpensions/cpp/cpp-benefit/eligibility.html"
+
     def formula(person, period, parameters):
         p = parameters(period).gov.cra.benefits.cpp.retirement
-        
+
         # Check age requirement (60+)
         age = person("age", period)
         meets_age = age >= p.eligibility_age
-        
+
         # Check contribution requirement (simplified - at least 1 year)
         years_contributed = person("cpp_years_of_contribution", period)
         has_contributions = years_contributed > 0
-        
-        return meets_age & has_contributions
+
+        return meets_age & has_contributions

policyengine_canada/variables/gov/cra/benefits/cpp/cpp_retirement_pension.py

@@ -8,25 +8,22 @@ class cpp_retirement_pension(Variable):
     definition_period = YEAR
     unit = CAD
     documentation = "Annual CPP retirement pension amount"
-    
+    reference = "https://www.canada.ca/en/services/benefits/publicpensions/cpp/cpp-benefit/amount.html"
+
     def formula(person, period, parameters):
         p = parameters(period).gov.cra.benefits.cpp.retirement
-        
-        # Check eligibility
         eligible = person("cpp_retirement_eligible", period)
-        
-        # Simplified calculation based on years of contribution
-        # Use average between 0 and maximum based on contribution years
         years_contributed = person("cpp_years_of_contribution", period)
-        
-        # Assume full contributions after 40 years
-        contribution_factor = min_(years_contributed / 40, 1)
-        
-        # Calculate monthly amount between 0 and maximum
-        # For simplicity, use average as midpoint
-        monthly_amount = contribution_factor * p.average_monthly
-        
-        # Convert to annual
+
+        # Contribution factor: ratio of years contributed to maximum contributory period
+        max_years = p.max_contributory_years
+        contribution_factor = min_(years_contributed / max_years, 1)
+
+        # Scale average monthly by contribution factor, cap at maximum monthly
+        monthly_amount = min_(
+            p.average_monthly * contribution_factor,
+            p.maximum_monthly,
+        )
         annual_amount = monthly_amount * 12
-        
-        return where(eligible, annual_amount, 0)
+
+        return where(eligible, annual_amount, 0)

policyengine_canada/variables/gov/cra/benefits/cpp/cpp_years_of_contribution.py

@@ -7,4 +7,5 @@ class cpp_years_of_contribution(Variable):
     label = "Years of CPP contributions"
     definition_period = YEAR
     unit = "year"
-    documentation = "Number of years person has contributed to CPP"
+    documentation = "Number of years person has contributed to CPP"
+    reference = "https://www.canada.ca/en/services/benefits/publicpensions/cpp/cpp-benefit/amount.html"