v2.2.0 — Threshold-provenance review + 6 numeric refinements

v2.2.0 — Threshold-provenance review (issue #3) + 6 numeric refinements

Behavior change. Severity output (the none/low/high bucket) changes for six species. Existing entities may flip state on upgrade; entity_ids are preserved (verified by the cleanroom-pretag harness: Gate B PASS, A/C/D PASS). Closes #3.

What's new

Per-species evidence-tier — the threshold_status attribute (additive)

Every raw and consensus sensor now exposes a threshold_status string attribute classifying the species's threshold-evidence basis into one of five tiers:

Tier	What it means	Species
species_specific	peer-reviewed per-species cutoff exists (numbers may disagree across studies)	birch, ash, alder, hazel, olive, plane_tree, mugwort, ragweed, grass, plantago, urtica, nettle_family, carpinus — 13
family_eaaci	EAACI's actual family group; no species refinement, but the bracket is real	rye, oak, holm_oak, beech, cypress_family — 5
established_no_threshold	clinically-established allergen with no published numeric cutoff; working bracket carried	chenopodium, juglans, elm — 3
family_analogy	family not in EAACI's scheme; analogy-only, weakest	rumex, asteraceae — 2
fungal	spore allergen, separate evidence base	alternaria — 1

The tier reflects evidence provenance, not clinical certainty (the review's honest caveat: Tier-2 "numbers" are ranges across studies, not points; the threshold concept itself is contested per recent EJACI; per-spore allergen content varies up to 15× day-to-day for alternaria).

This retires the contested three-way disagreement that prompted #3 — analytics.py code comments, README, and species_registry.ThresholdStatus are now all reconciled to the approved literature review (threshold-provenance-review-FINAL.md, shipped in the repo as the citation source-of-truth).

Six numeric threshold refinements

Per the same review, six species' (onset, peak) grains/m³ brackets changed:

Species	v2.1	v2.2	Why
ragweed	(3, 50)	(5, 20)	PMC5357339 / PMC2868868 / Nature s41598-022-20069-y. Was under-warning (clinical threshold <20, sensitive 1–5). Fraunhofer UBAMBI (NCT05346718) ragweed arm remains unpublished as of mid-2026 — revisit if it appears.
olive	(10, 100)	(10, 200)	Spanish operational scale (PMC7349006): low 1–50 / high >200. Was over-warning regionally.
birch	(10, 100)	(20, 100)	Aerobiologia 2021 low ~20; peak VALIDATED by Struß 2025 controlled chamber (doi:10.1159/000545509, PMID 40328230).
alder	(10, 100)	(45, 80)	Rapiejko 2007 (PMC6245103): 45 = first symptoms, 80 = all alder-allergics symptomatic. Cited peak below the EAACI Fagales bracket.
hazel	(10, 100)	(35, 80)	Rapiejko 2007 (PMC4996891). Same per-species-over-family reasoning as alder.
mugwort	(10, 100)	(3, 50)	Class-error fix — mugwort is SpeciesClass.HERB in the registry but was sitting at the tree bracket. Moved to the herb-class default. No mugwort-specific cited cutoff; evidence graded limited per Aerobiologia 2021.

Behavior change examples your dashboard may show on upgrade:

• olive at 150 grains/m³: was high → becomes low (de-escalation per FINAL review)
• ragweed at 30 grains/m³: was low → becomes high (sensitivity correction per FINAL review)
• alder/hazel at 80–99: was low → becomes high (per-species peak below family bracket)
• mugwort at 60: was low → becomes high (class-error fix; herb species was at tree bracket)

What is not in v2.2

• Ash refinement to ~18 onset (the strongest single evidence in the 24-species set per the review) — explicitly scoped out for this release, deferred. The analytics.py ash row comment names the deferred refinement.
• No registry / config-entry migration — additive metadata + boundary-value changes only.
• No entity_id changes — your existing dashboards and automations continue to point at the same entities. Only state values may flip.

Citation audit

Every DOI / PMID / PMC / NCT / author-year / percentage / Thermo code in the threshold comments of analytics.py and species_registry.py was grep'd against threshold-provenance-review-FINAL.md. 57/57 trace. The review document is now committed to the repo as the canonical citation source-of-truth; future edits introducing an unsourced citation will be flagged by re-running the same grep.

Compatibility

• Minimum Home Assistant 2024.11.0 (unchanged).
• HACS custom repository — https://github.com/TheDave94/pollenwatch (unchanged).
• Lovelace card auto-registered on install (unchanged).

Upgrading from v2.1 — no action required

Pure refresh. New threshold_status attribute appears on first sensor update after restart. Six species' severity buckets shift per the table above; if you have automations keyed off raw severity values, scan for those six species. No config-entry migration runs.