Refine THI method guidance and caveats

[peetmate]

Summary

Refines livestock THI method guidance, source-support notes, and user-facing caveats across code, docs, and CLI/report output.

Problem / Motivation

Issue #30 was no longer a blank method-design issue, but repo still lacked a clean public THI method description, explicit threshold caveats, and consistent output wording about what THI results do and do not mean.

Without this, users could read THI summaries as more certain or more breed-resolved than toolkit can currently support.

Scope

• In scope:
  • add public THI method metadata helper
  • add dedicated THI workflow doc
  • tighten source-support wording, especially era_5 and projected humidity limits
  • propagate THI method/threshold caveats into season/stats/period/hazard output
  • add tests for helper metadata and output propagation
  • add internal issue notes for threshold/method review
• Out of scope:
  • changing default THI formula family
  • promoting max-temperature THI as default workflow
  • breed-resolved physiology or genetics-aware threshold selection
  • new humidity fetch implementation for era_5

Implementation Notes

• Keeps current default THI workflow as daily mean temperature + daily RH.
• Keeps Thornton et al. (2021)-anchored thresholds as operational defaults.
• Adds describe_thi_method() to expose formula, threshold basis, climate-profile logic, interpretation caveats, and source-support status.
• Adds explicit wording that current livestock profiles are species-group screening defaults, not breed-resolved physiology.
• Adds compact THI note lines to user-facing outputs so results carry caveat context, not only raw values.
• Keeps era_5 marked uncertain because current operational fetch config does not define humidity band for THI workflow.

Data / Access / Runtime Notes

• No new external service added.
• No new auth requirement added.
• nex_gddp THI remains conditional on hurs availability.
• era_5 THI still not promoted to supported default path.
• No cache format change.

Testing

• Tests added/updated:
  • tests/test_thi.py
  • tests/test_statistics_source_policy.py
• Commands run:
  • .venv/bin/python -m pytest -q tests/test_thi.py tests/test_statistics_source_policy.py tests/test_compare_periods_baseline.py tests/test_hazard_thresholds.py
• Manual checks:
  • reviewed THI helper/doc/output wording consistency
• Not tested:
  • live external dataset fetch runs in this PR slice

Reviewer Guidance

Focus review on:

• climate_tookit/climatology/heat_stress.py
  • method metadata, source-support wording, interpretation caveats
• climate_tookit/climate_statistics/statistics.py
• climate_tookit/season_analysis/seasons.py
• climate_tookit/compare_periods/periods.py
• climate_tookit/calculate_hazards/hazards.py
  • note propagation into user-facing output
• docs/thi_workflow.md
  • method wording and threshold override guidance

Related Issues

• Closes / advances #30
• Related: #9

Checklist

• I reviewed my own diff for unrelated changes.
• I used a dedicated branch for this work.
• I added or updated tests where needed.
• I documented any auth, data, cache, or runtime implications.
• I included reviewer test steps or validation notes.
• I linked the relevant issue(s).