Make country package purely deterministic - read stochastic variables from dataset

.claude/agents/implementation-validator.md

@@ -23,11 +23,20 @@ Validates government benefit program implementations against quality standards,
 ## Critical Violations (Automatic Rejection)
 
 ### 1. Hard-Coded Numeric Values
-Any numeric literal (except 0, 1 for basic operations) must come from parameters:
-- Thresholds, limits, amounts
-- Percentages, rates, factors
-- Dates, months, periods
-- Ages, counts, sizes
+
+**Acceptable Hard-Coded Values:**
+- **Bootstrapping values**: `if month >= 10:` to determine parameter snapshot
+- **Mathematical baselines**: `income_ratio - 1` (100% FPG), `level = 1 + ...` (starts at 1)
+- **Structural constants**: `min_(size, 12)` (FPG table limit), `range(1, 13)` (months)
+- **Derived from parameter structure**: `num_children - 2` (first, second, then additional)
+- **Framework constants**: `MONTHS_IN_YEAR` for period conversions (NOT literal 12)
+- **Zero checks**: `max_(0, value)`, `== 0`, `> 0`
+
+**Must Be Parameters:**
+- Policy thresholds that could change
+- Percentages/rates from regulations
+- Program-specific age limits
+- Benefit amounts
 
 ### 2. Placeholder Implementations
 No TODO comments or placeholder returns:
@@ -77,14 +86,19 @@ Validate that:
 
 ### Numeric Literal Detection
 ```python
-# Scan for potential hard-coded values
-# Allowed: 0, 1, mathematical operations
-# Flagged: Any other numeric literal
-
-# Examples of violations:
-if age >= 65:  # Flag: 65 should be parameter
-benefit * 0.5   # Flag: 0.5 should be parameter  
-month >= 10     # Flag: 10 should be parameter
+# ACCEPTABLE (Don't Flag):
+if month >= 10:             # ✅ Bootstrapping - determines parameter snapshot
+income_ratio - 1            # ✅ Mathematical baseline (100% = 1)
+min_(family_size, 12)       # ✅ Structural constant (FPG table limit)
+num_children - 2            # ✅ Derived from parameter structure
+/ MONTHS_IN_YEAR            # ✅ Framework constant (NOT / 12)
+max_(0, value)              # ✅ Zero check
+
+# VIOLATIONS (Flag These):
+if age >= 65:               # ❌ Program age limit - should be parameter
+benefit * 0.5               # ❌ Rate from regulation - should be parameter
+if income < 50000:          # ❌ Policy threshold - should be parameter
+income / 12                 # ❌ Literal - should use MONTHS_IN_YEAR
 ```
 
 ### Parameter Organization Check

.claude/agents/policy-domain-validator.md

@@ -61,27 +61,73 @@ existing_patterns = [
 
 ### 3. Hard-Coded Value Detection
 
-**Patterns to Flag:**
-```python
-# Numeric literals that should be parameters
-suspicious_patterns = [
-    r'\b0\.\d+\b',  # Decimals like 0.5, 0.33
-    r'\b\d{2,}\b',   # Numbers >= 10 (except common like 12 for months)
-    r'return \d+',   # Direct numeric returns
-    r'= \d+\.?\d*[^)]',  # Numeric assignments not in function calls
-    r'\* \d+\.?\d*',  # Multiplication by literals
-    r'/ \d+\.?\d*',   # Division by literals (except 12 for monthly)
-]
-
-# Exceptions (OK to have literals)
-ok_literals = [
-    'range(', 'np.array([', 'np.zeros(', 'np.ones(',
-    '== 0', '> 0', '< 0', '>= 0', '<= 0',  # Zero comparisons
-    '== 1', '== 2',  # Small integer comparisons
-    '/ 12',  # Monthly conversion
-    '* 12',  # Annual conversion
-]
-```
+**Acceptable Hard-Coded Values (Don't Flag):**
+
+1. **Bootstrapping values** - values needed to access parameters:
+   ```python
+   if month >= 10:  # ✅ OK - needed to determine which FPG snapshot to use
+       instant_str = f"{year}-10-01"
+   ```
+
+2. **Mathematical baselines** - representing 100%, starting at 1, etc:
+   ```python
+   income_ratio - 1  # ✅ OK - means "income above 100% FPG"
+   fee_level = 1 + ...  # ✅ OK - fee levels start at 1
+   ```
+
+3. **Structural constants** from external systems:
+   ```python
+   min_(size, 12)  # ✅ OK - FPG tables only go to 12 people
+   range(1, 13)  # ✅ OK - 12 months in a year
+   ```
+
+4. **Derived from parameter structure**:
+   ```python
+   num_children - 2  # ✅ OK - reflects parameter structure (first, second, additional)
+   ```
+
+5. **Period conversions** (use framework constants):
+   ```python
+   / MONTHS_IN_YEAR  # ✅ CORRECT - use framework constant
+   * MONTHS_IN_YEAR  # ✅ CORRECT - use framework constant
+   / 12  # ❌ HARD-CODED - use MONTHS_IN_YEAR instead
+   * 12  # ❌ HARD-CODED - use MONTHS_IN_YEAR instead
+   ```
+   Note: MONTHS_IN_YEAR is imported from model_api
+
+6. **Comparisons and zero-checks**:
+   ```python
+   == 0, > 0, >= 1, == 1, == 2  # ✅ OK
+   max_(0, value)  # ✅ OK - prevent negative
+   ```
+
+**Problematic Hard-Coded Values (DO Flag):**
+
+1. **Policy-specific thresholds** that could change:
+   ```python
+   if income < 50000:  # ❌ Should be parameter
+   ```
+
+2. **Percentages/rates** from regulations:
+   ```python
+   benefit = income * 0.65  # ❌ Should be parameter
+   ```
+
+3. **Age limits** specific to programs:
+   ```python
+   if age < 18:  # ❌ Should be parameter (unless universal definition)
+   ```
+
+4. **Benefit amounts**:
+   ```python
+   return 1000  # ❌ Should be parameter
+   ```
+
+**When in Doubt:**
+- If the value appears in regulations → parameter
+- If the value could differ across states → parameter
+- If it's a mathematical constant or structural limit → OK to hard-code
+- If it's needed to bootstrap parameter access → OK to hard-code
 
 ### 4. Reference Validation
 
@@ -169,6 +215,49 @@ child_age = p.child_age_limit
 elderly_age = p.elderly_age_limit
 ```
 
+### 9. Vectorization Rules
+
+**IMPORTANT: `if` statements are context-dependent**
+
+`if` statements are **FINE** for scalar values:
+- ✅ Period attributes: `if period.start.month >= 10:`
+- ✅ Parameter values: `if parameters(period).threshold > 0:`
+- ✅ Scalar calculations: `if year >= 2024:`
+
+`if` statements are **PROBLEMATIC** for vectorized arrays:
+- ❌ Person/household data: `if income > 1000:` (use `where(income > 1000, ...)`)
+- ❌ Array checks: `if income.any():` (prevents vectorization)
+- ❌ Conditional on arrays: `if eligible:` where `eligible` is an array
+
+**Correct Pattern:**
+```python
+# BAD - if on vectorized data
+def formula(person, period, parameters):
+    income = person("income", period)
+    if income > 10000:  # ❌ income is an array!
+        return 100
+    else:
+        return 0
+
+# GOOD - where() for vectorized data
+def formula(person, period, parameters):
+    income = person("income", period)
+    return where(income > 10000, 100, 0)  # ✅
+
+# ALSO GOOD - if on scalar period data
+def formula(person, period, parameters):
+    month = period.start.month  # scalar value
+    if month >= 10:  # ✅ month is a scalar!
+        param = parameters(f"{year}-10-01")
+    else:
+        param = parameters(f"{year-1}-10-01")
+```
+
+**When Validating:**
+- Don't flag `if` statements on `period.start.*`, `year`, `month`, or parameter values
+- DO flag `if` statements on person/household/entity calculations
+- Look for context: is the value being tested a scalar or an array?
+
 ## Validation Process
 
 1. **Scan all changed files** in the PR