Cite NZ spec sources by symbol or stable record, never by a drifting line

changelog.d/nz-spec-line-citations.fixed.md

@@ -0,0 +1,3 @@
+Replace drifting New Zealand spec citations with Python symbols, JSON Pointers,
+and a documentation heading. Guard every NZ JSON/YAML resource against local
+file line citations and require commit pins for foreign file line citations.

packages/microcosm-build/src/microcosm/build/nz/benefit_unit_rule.json

@@ -2,7 +2,7 @@
   "version": 1,
   "country": "nz",
   "method_card_row": "MC7",
-  "description": "The New Zealand benefit unit (engine Family entity): an adult, their co-resident partner, and their dependent children; every other adult forms their own unit. An adult for unit construction is any person excluded from the declared dependent-child rule, including a financially independent young person or an independent teen parent. The unit id family.family_id and membership person.person_family_id are structural graph columns (microcosm.graph.executor._structural_columns, executor.py:638-645); a non-structural node cannot own either (executor.py:1549-1554). family.family_household_id is the ordinary family column linking each unit to its household. The shared transport CREATE kernel (G4/G5a; transport/population_kernels.py:208-232) builds units from donor concept pointers under this spec. Family weights are inherited from the household through the Frame.",
+  "description": "The New Zealand benefit unit (engine Family entity): an adult, their co-resident partner, and their dependent children; every other adult forms their own unit. An adult for unit construction is any person excluded from the declared dependent-child rule, including a financially independent young person or an independent teen parent. The unit id family.family_id and membership person.person_family_id are structural graph columns (microcosm.graph.executor._structural_columns); a non-structural node cannot own either (microcosm.graph.executor._validate_population_declaration). family.family_household_id is the ordinary family column linking each unit to its household. The shared transport CREATE kernel (G4/G5a; microcosm.build.transport.population_kernels.TransportCreateKernel) builds units from donor concept pointers under this spec. Family weights are inherited from the household through the Frame.",
   "status": "settled by the NZ hub on 2026-10-12 under G8 method addendum B8 (MC7)",
   "entity": "family",
   "engine_entity": "Family",
@@ -19,7 +19,7 @@
       "parent_2_person_id"
     ],
     "household_reference_person": "reference_person_id",
-    "citation": "packages/microcosm-frame/src/microcosm/frame/concepts.py:889-928"
+    "citation": "packages/microcosm-frame/src/microcosm/frame/concepts.py, the \"# --- Relationships\" block: _pointer(\"partner_person_id\") through _pointer(\"reference_person_id\")"
   },
   "source_household_lineage": {
     "concept": "fact:household.source_household_id",
@@ -37,7 +37,7 @@
     },
     {
       "member": "dependent_child",
-      "rule": "A dependent child joins the unit of its co-resident parent parent_1_person_id; if that parent is itself dependent, follow the parent chain to that parent's unit. A lone co-resident parent is always parent 1 (concepts.py:900-907), so parent_2_person_id never chooses the unit."
+      "rule": "A dependent child joins the unit of its co-resident parent parent_1_person_id; if that parent is itself dependent, follow the parent chain to that parent's unit. A lone co-resident parent is always parent 1 (concepts.py _pointer(\"parent_1_person_id\")), so parent_2_person_id never chooses the unit."
     },
     {
       "member": "other_adult",
@@ -55,7 +55,7 @@
       "hours_concept": "fact:person.usual_weekly_hours",
       "donor_variable": "weekly_hours_worked_before_lsr",
       "basis": "Social Security Act 2018, Schedule 2, financially independent (DLM6784504, limb a) and full employment (DLM6784514, limbs a and b), as at 1 April 2026; G8 method addendum B8. The test applies only while below age_limit_years.",
-      "concept_evidence": "concepts.py:1069-1083 declares usual weekly hours across all jobs and self-employment in worked weeks in the donor reference year, with transport CARRY. adapters/policyengine_us_concepts.py:352-362 maps weekly_hours_worked_before_lsr through Identity to this concept; transport.py:843-849 decodes the donor through that mapping. docs/concept-coverage/policyengine-us.md:31 records the same binding.",
+      "concept_evidence": "concepts.py concept(\"fact:person.usual_weekly_hours\") declares usual weekly hours across all jobs and self-employment in worked weeks in the donor reference year, with transport CARRY. microcosm.frame.adapters.policyengine_us_concepts.POLICYENGINE_US_CONCEPT_MAPPING maps weekly_hours_worked_before_lsr through Identity to this concept; microcosm.frame.transport.read_populace_us_donor decodes the donor through that mapping. docs/concept-coverage/policyengine-us.md#inputs-each-concept-feeds records the same binding.",
       "approximation": "The donor usual rate in worked weeks is used for the statutory average weekly employment test; employment contracts and the averaging interval are not observed."
     },
     "parent_independence_min_age": 16,

packages/microcosm-build/src/microcosm/build/nz/reporting_classifiers.json

@@ -192,8 +192,8 @@
     "stability": "Same pinned donor and unit rule preserve person ids across rebuilds; each family id is its head person id. Units sharing source household lineage remain distinct units.",
     "implementation": [
       "packages/microcosm-frame/src/microcosm/frame/unit_construction.py build_benefit_units (each family id is its head person's id)",
-      "packages/microcosm-build/src/microcosm/build/transport/population_kernels.py:209-228",
-      "packages/microcosm-frame/src/microcosm/frame/transport.py:843-856"
+      "microcosm.build.transport.population_kernels.TransportCreateKernel",
+      "microcosm.frame.transport.read_populace_us_donor"
     ],
     "citation": {
       "item": "A1",
@@ -260,15 +260,15 @@
   "disclosures": [
     {
       "note": "NZ Super is overstated for single people who share a home because the shares-residence input defaults false; this moves their deciles upward.",
-      "evidence": "axiom_input_closure.json:1045-1052",
+      "evidence": "axiom_input_closure.json#/entries[input=nz_super_shares_residence_with_person_at_least_adult_age]",
       "citation": {
         "item": "A1",
         "source": "docs/nz-reporting-classifiers-method.md#a1-income-decile-provisional"
       }
     },
     {
       "note": "Market-income components follow the existing family gross-income concept mapping. Rental income is after business expenses. The rental and private-pension concept descriptions do not explicitly say before tax; their before-tax transport interpretation must be verified before activation.",
-      "evidence": "packages/microcosm-frame/src/microcosm/frame/adapters/axiom_concept_mappings/nz.json:670-688; packages/microcosm-frame/src/microcosm/frame/concepts.py:990-1000,1040-1051",
+      "evidence": "packages/microcosm-frame/src/microcosm/frame/adapters/axiom_concept_mappings/nz.json#/bindings[canonical_input=nz:statutes~1social_security~1accommodation_supplement~1core#input.accommodation_supplement_relevant_weekly_income]; packages/microcosm-frame/src/microcosm/frame/concepts.py _amount(\"rental_income\") and _amount(\"private_pension_income\")",
       "citation": {
         "item": "A1",
         "source": "docs/nz-reporting-classifiers-method.md#a1-income-decile-provisional"
@@ -734,7 +734,7 @@
   "as_non_beneficiary_audit": {
     "nz_super": "The existing accommodation_supplement_non_beneficiary state binding negates any_true over assigned member receipt flags, including NZ Super. A unit with any assigned NZ Super receipt is therefore not a non-beneficiary.",
     "veterans_pension": "The same binding omits the unsupported Veterans Pension flag, so it must be extended when that receipt input is activated. A missing Veterans Pension flag continues to block reporting rather than classify its recipients as other.",
-    "evidence": "axiom_input_closure.json:1183-1204",
+    "evidence": "axiom_input_closure.json#/entries[input=accommodation_supplement_non_beneficiary]",
     "citation": {
       "item": "A2",
       "source": "docs/nz-reporting-classifiers-method.md#a2-receipt-group"

packages/microcosm-build/src/microcosm/build/nz/scenarios.json

@@ -150,7 +150,7 @@
     "annualisation": {
       "weeks_per_year": 52,
       "method_card_row": "MC12",
-      "note": "the conformance harness uses 365/7 weeks (ops main run.py:168); the model states and uses 52"
+      "note": "the conformance harness uses 365/7 weeks (WEEKS_IN_MODEL_YEAR in TheAxiomFoundation/ops nz-lane/emtr_reproduction/run.py at ba6e7d6e); the model states and uses 52"
     },
     "groupings": {
       "method_card_row": "MC3",