Improve Tax-Free Childcare income test (#1602)

Author: MaxGhenis

changelog.d/1043.md

@@ -0,0 +1 @@
+- Improved Tax-Free Childcare expected income and self-employment start-up period handling.

policyengine_uk/parameters/gov/hmrc/tax_free_childcare/income/declaration_period_weeks.yaml

@@ -0,0 +1,10 @@
+description: The expected income test for Tax-Free Childcare uses this many weeks in a declaration period.
+metadata:
+  period: year
+  unit: week
+  label: Tax-Free Childcare declaration period weeks
+  reference:
+    - title: The Childcare Payments (Eligibility) Regulations 2015 - Regulation 9(4)
+      href: https://www.legislation.gov.uk/uksi/2015/448/regulation/9
+values:
+  2015-01-01: 13

policyengine_uk/tests/policy/baseline/gov/hmrc/tax_free_childcare/tax_free_childcare_expected_declaration_period_income.yaml

@@ -0,0 +1,7 @@
+- name: Expected declaration-period income defaults to annual countable income prorated by declaration weeks
+  period: 2025
+  input:
+    employment_income: 8_000
+    self_employment_income: 4_000
+  output:
+    tax_free_childcare_expected_declaration_period_income: 3_000

policyengine_uk/tests/policy/baseline/gov/hmrc/tax_free_childcare/tax_free_childcare_income_condition.yaml

@@ -22,10 +22,10 @@
   period: 2025
   input:
     age: 18
-    employment_income: 4_152
+    tax_free_childcare_expected_declaration_period_income: 2_080
     self_employment_income: 0
   output:
-    tax_free_childcare_meets_income_requirements: false
+    tax_free_childcare_meets_income_requirements: true
 
 # Tests for age 21+ bracket (threshold: £2,379 quarterly)
 - name: Under threshold for age 22 - ineligible
@@ -65,4 +65,22 @@
     self_employment_income: 17_152
     adjusted_net_income: 217_152
   output:
-    tax_free_childcare_meets_income_requirements: false
+    tax_free_childcare_meets_income_requirements: false
+
+- name: At income limit
+  period: 2025
+  input:
+    age: 22
+    tax_free_childcare_expected_declaration_period_income: 10_000
+    adjusted_net_income: 100_000
+  output:
+    tax_free_childcare_meets_income_requirements: true
+
+- name: Self-employment start-up period waives minimum income threshold
+  period: 2025
+  input:
+    age: 22
+    tax_free_childcare_expected_declaration_period_income: 0
+    tax_free_childcare_self_employment_start_up_period: true
+  output:
+    tax_free_childcare_meets_income_requirements: true

policyengine_uk/variables/gov/hmrc/tax_free_childcare/conditions/tax_free_childcare_expected_declaration_period_income.py

@@ -0,0 +1,18 @@
+from policyengine_uk.model_api import *
+
+
+class tax_free_childcare_expected_declaration_period_income(Variable):
+    value_type = float
+    entity = Person
+    label = "expected income in the Tax-Free Childcare declaration period"
+    definition_period = YEAR
+    unit = GBP
+    reference = [
+        "https://www.legislation.gov.uk/uksi/2015/448/regulation/9",
+        "https://www.legislation.gov.uk/uksi/2015/448/regulation/10",
+    ]
+
+    def formula(person, period, parameters):
+        p = parameters(period).gov.hmrc.tax_free_childcare.income
+        annual_countable_income = add(person, period, p.countable_sources)
+        return annual_countable_income * p.declaration_period_weeks / WEEKS_IN_YEAR

policyengine_uk/variables/gov/hmrc/tax_free_childcare/conditions/tax_free_childcare_meets_income_requirements.py

@@ -7,24 +7,29 @@ class tax_free_childcare_meets_income_requirements(Variable):
     label = "income eligible for the tax-free childcare"
     definition_period = YEAR
 
-    # Legislation: https://www.legislation.gov.uk/ukdsi/2015/9780111127063 , part 9 and 10
-    # Also, you can check here: https://www.gov.uk/tax-free-childcare
-
     def formula(person, period, parameters):
         p = parameters(period).gov.hmrc.tax_free_childcare
 
-        # Calculate eligible income by summing countable sources
-        yearly_eligible_income = add(person, period, p.income.countable_sources)
-        quarterly_income = yearly_eligible_income / 4
+        expected_income = person(
+            "tax_free_childcare_expected_declaration_period_income",
+            period,
+        )
 
         # Get minimum wage rate using existing variable
         min_wage_rate = person("minimum_wage", period)
 
-        # Calculate required threshold (weekly hours * 13 weeks (a quarter) * minimum wage)
-        # Reference for the quarterly logic: part 9.3 in https://www.legislation.gov.uk/uksi/2015/448/regulation/9
-        required_threshold = min_wage_rate * p.minimum_weekly_hours * 13
+        required_threshold = (
+            min_wage_rate * p.minimum_weekly_hours * p.income.declaration_period_weeks
+        )
+        meets_minimum_income = expected_income >= required_threshold
+        in_start_up_period = person(
+            "tax_free_childcare_self_employment_start_up_period",
+            period,
+        )
 
         # Get adjusted net income and check against max threshold
         ani = person("adjusted_net_income", period)
 
-        return (quarterly_income > required_threshold) & (ani < p.income.income_limit)
+        return (meets_minimum_income | in_start_up_period) & (
+            ani <= p.income.income_limit
+        )

policyengine_uk/variables/gov/hmrc/tax_free_childcare/conditions/tax_free_childcare_self_employment_start_up_period.py

@@ -0,0 +1,10 @@
+from policyengine_uk.model_api import *
+
+
+class tax_free_childcare_self_employment_start_up_period(Variable):
+    value_type = bool
+    entity = Person
+    label = "in a self-employment start-up period for Tax-Free Childcare"
+    definition_period = YEAR
+    default_value = False
+    reference = "https://www.legislation.gov.uk/uksi/2015/448/regulation/11"