Merge pull request #6650 from MaxGhenis/fix-good-first-issues-clean

Fix good first issues: parameterize MT deduction rate and remove confusing comment

Author: PavelMakarchuk

.claude/agents/parameter-architect.md

@@ -192,17 +192,40 @@ values:
 ```yaml
 description: [Active voice sentence describing what this parameter does]
 metadata:
+  label: [Short display name - REQUIRED, always include]
   unit: [currency-USD | /1 | month | year | bool]
   period: [year | month | day | eternity]
   reference:
-    - title: [Specific document name and section]
+    - title: [Specific document name and section/subsection]
       href: [Direct URL to source]
       publication_date: [YYYY-MM-DD]
-  label: [Short display name]
 values:
   [date]: [value]
 ```
 
+### Description and Label Standards
+
+**Description (REQUIRED):**
+- Must exist and describe what the parameter does
+- RECOMMENDED: Use active voice for clarity
+- RECOMMENDED: End with a period
+
+**Examples:**
+- ✅ "Montana allocates itemized deductions to each spouse at this rate when filing separately."
+- ✅ "Montana caps the federal income tax deduction to this amount, based on filing status."
+- ⚠️ "Rate at which itemized deductions are allocated" (passive voice, but still acceptable)
+
+**Label (RECOMMENDED):**
+- Should be included in metadata for better UI/documentation
+- Be concise (2-6 words) and descriptive
+- Missing label won't break functionality but reduces discoverability
+
+**Reference (REQUIRED):**
+- MUST have at least one reference with title and href
+- RECOMMENDED: Cite specific statute subsections (§ 15-30-2131(2) vs § 15-30-2131)
+- RECOMMENDED: Include document section/page numbers when available
+- RECOMMENDED: Prefer official statutory citations over secondary sources
+
 ### Unit Types
 - `currency-USD`: Dollar amounts
 - `/1`: Ratios, percentages, factors

.claude/agents/reference-validator.md

@@ -27,7 +27,24 @@ class variable_name(Variable):
     reference = "Specific regulation citation (e.g., 42 USC 601, 7 CFR 273.9)"
 ```
 
-### 2. Reference-Value Corroboration
+### 2. Reference-Value Corroboration (CRITICAL)
+
+**⚠️ THE REFERENCE MUST ACTUALLY CORROBORATE THE VALUE ⚠️**
+
+This is the most critical validation. A reference that doesn't support the value is worse than no reference.
+
+**MANDATORY CHECKS:**
+1. **Fetch the referenced document** (if accessible via WebFetch)
+2. **Read the cited section/subsection**
+3. **Verify it explicitly states the value** (not just related content)
+4. **Flag if subsection citation is wrong** even if general section is correct
+
+**Example of what went wrong:**
+- Parameter value: 0.5 (spouse allocation rate)
+- Citation: "Montana Code § 15-30-2131(2)"
+- Actual statute § 15-30-2131(2): About day-care home deductions (WRONG SUBSECTION!)
+- Correct subsection: § 15-30-2131(1)(c)(vi)(D): "deduction...must be divided equally"
+- **This MUST be flagged as non-corroborating even though the statute number is related**
 
 **The reference must explicitly support the value:**
 

.github/update_api.py

@@ -7,7 +7,7 @@ def main():
     # First, find the current package version number from the pyproject.toml file
     with open("pyproject.toml", "rb") as f:
         data = tomllib.load(f)
-        version = data["project"]["version"]  # Would give us "1.358.0"
+        version = data["project"]["version"]
     # Then, clone the https://github.com/policyengine/policyengine-api repo using the GitHub CLI
     pat = os.environ["GITHUB_TOKEN"]
     os.system(

changelog_entry.yaml

@@ -0,0 +1,6 @@
+- bump: patch
+  changes:
+    changed:
+    - Parameterized Montana spouse allocation factor for itemized deductions (was hardcoded 0.5)
+    removed:
+    - Unhelpful comment from .github/update_api.py

policyengine_us/parameters/gov/states/mt/tax/income/deductions/itemized/spouse_allocation_rate.yaml

@@ -0,0 +1,13 @@
+description: Share of tax unit itemized deductions allocated to each spouse when married filing separately on the same form. This is not a policy parameter but a mathematical representation of "divided equally".
+values:
+  # 0.5 means each spouse gets 50% of joint deductions
+  2021-01-01: 0.5
+metadata:
+  label: Montana itemized deductions spouse allocation rate
+  period: year
+  unit: /1
+  reference:
+    - title: Montana Administrative Rule 42.15.524 - Itemized Deductions of Married Taxpayers
+      href: https://rules.mt.gov/gateway/ruleno.asp?RN=42.15.524
+    - title: Montana Form 2 Instructions
+      href: https://revenue.mt.gov/publications/montana-form-2-individual-income-tax-return-forms-and-instructions-includes-form-2ec

policyengine_us/variables/gov/states/mt/tax/income/deductions/itemized/general/mt_itemized_deductions_indiv.py

@@ -15,11 +15,12 @@ class mt_itemized_deductions_indiv(Variable):
     defined_for = StateCode.MT
 
     def formula(person, period, parameters):
-        p = parameters(period).gov.irs.deductions
+        p = parameters(period).gov.states.mt.tax.income.deductions.itemized
         # Since we only compute the federal charitable deduction at the tax unit level,
         # we will split the value between each spouse
         charitable_deduction = (
-            person.tax_unit("charitable_deduction", period) * 0.5
+            person.tax_unit("charitable_deduction", period)
+            * p.spouse_allocation_rate
         )
         head_or_spouse = person("is_tax_unit_head_or_spouse", period)
         # The interest deduction is the sum of mortagage and investment interest expenses