Changes in version 0.4.0 (2026-08-07)                  

ESG Reporting Layer (new)

MineSDG is now a reporting engine as well as a KPI calculator. One call
produces a framework report; internally every number comes from the
existing KPI engine via the new disclosure bundle -- no calculation is
duplicated anywhere in the reporting layer.

  - compile_site_disclosures() builds a minesdg_disclosure_bundle, the
    single interface between the scoring engine and reporting.
    Accessors: bundle_kpi(), bundle_raw(), bundle_score();
    as_disclosure_bundle() coerces site data.frames.
  - Framework mappings ship as data: gri_crosswalk, icmm_crosswalk,
    brsr_crosswalk (common schema, versioned via a crosswalk_version
    attribute) plus icmm_recommendation_rules. framework_crosswalk() is
    the accessor; map_bundle_to_framework() is the single generic mapper
    with honest statuses (reported, partial, narrative_provided,
    narrative_required, not_in_scope).
  - GRI: generate_gri_report() (GRI 302/303/304/305/306/403/413) and
    gri_content_index().
  - ICMM: generate_icmm_report() with board scorecard, traffic-light
    assessment (reclassification of existing 0-100 KPI scores;
    thresholds via icmm_default_params()) and data-driven
    recommendations.
  - BRSR: generate_brsr_report(), generate_brsr_sectionA(),
    generate_brsr_sectionB(), generate_brsr_kpis(); monetary lines
    convert to INR lakh via entity_meta$fx_usd_inr or degrade honestly.
  - Rendering: render_minesdg_report() (HTML/PDF/DOCX via packaged
    Quarto templates, rendered in tempdir()) and write_report_xlsx()
    (via openxlsx2). Both are Suggests-gated with informative errors;
    report objects are always constructible offline.
  - Transform registry (internal): identity, sum_fields,
    musd_to_inr_lakh. Transforms are presentation-level reshaping only;
    new quantitative logic must enter through the KPI registry.

Dashboard

  - New Benchmark tab: portfolio comparison with a highlighted focus
    site and ranking table, powered by the new score_portfolio_sdg().
  - New Radar tab: SDG goal and mining-domain radar charts
    (plot_sdg_radar(), plot_domain_radar(), also exported for standalone
    use).
  - Existing tabs unchanged.

Internal modules

  - Logical file-level modules: R/report-*.R (Reporting),
    R/ai-placeholder.R (AI placeholder infrastructure only -- no LLM
    integration, no APIs), dashboard under inst/shiny/. SASB, ISSB and
    CSRD plug in later as new crosswalk datasets + thin generators with
    no architecture changes.

Compatibility

  - 100% backward compatible: no existing exported function changes
    signature, defaults, return class or behavior; v0.3.0 golden values
    are locked by tests.
  - Suggests gains quarto and openxlsx2; Imports unchanged.

                        Changes in version 0.3.0                        

Major features: production-readiness release

Site-level KPI engine

  - New calculators: calculate_ghg_intensity() (SDG 13, GHG Protocol),
    calculate_energy_intensity() (SDG 7), calculate_safety_performance()
    (SDG 8.8, TRIFR/LTIFR/fatality rate per ICMM 1M-hours convention),
    calculate_workforce_diversity() (SDG 5/8),
    calculate_community_investment() (SDG 1/17),
    calculate_waste_intensity() (SDG 12, tailings and strip ratios).
  - score_site_sdg(): normalises any site-year of raw data into a 0-100
    SDG scorecard with goal-level aggregation, materiality-weighted
    composite, and A-E grade. Ships with print() method.

Ontology & KPI registry

  - sdg_mining_ontology dataset: all 17 SDGs mapped to mining domains,
    materiality ratings, material topics, and GRI 11 / ICMM / SASB EM-MM
    / BRSR references. Query with explore_sdg_ontology().
  - mining_kpi_registry dataset: 18 site KPIs with units, SDG targets,
    directions and scoring thresholds. Query with list_mining_kpis().

Demo data (offline-first)

  - demo_mine_sites: synthetic 6-site x 2019-2024 operational ESG panel.
  - demo_sdg_country: offline snapshot shaped like
    fetch_sdg_country_data() output — the analytics layer now works
    without network access.
  - Reproducible generation scripts in data-raw/.

Shiny dashboard

  - run_minesdg_dashboard() launches a 5-tab interactive dashboard
    (portfolio scores, site deep-dive, ontology explorer, KPI registry,
    CSV upload). shiny/DT added to Suggests.

Documentation

  - Two new tutorial vignettes: site-level-kpis and
    sdg-ontology-and-scorecard.
  - PROJECT_HANDOFF.md audit and handoff document added to the repo.

Bug fixes

  - generate_mining_risk_profile() failed at runtime: it read a
    non-existent volatility_class field and matched wrong labels from
    compute_sdg_stability(). Now reads stability_category correctly.
  - Removed phantom jsonlite dependency check in
    fetch_sdg_country_data().
  - Added missing tests/testthat.R runner; new offline test suite for
    calculators, scorecard, datasets and helpers.
  - Added print() method for minesdg_domain_mapping objects.

Housekeeping

  - LazyData: true; Depends: R (>= 4.1.0) (native pipe).
  - Version 0.3.0.

                        Changes in version 0.1.0                        

Major Features

  - SDG data retrieval from UN API
  - Metadata caching layer
  - Indicator validation
  - Trend analysis (CAGR, slope, direction)
  - Stability & volatility metrics
  - Benchmark comparison
  - Convergence analysis
  - Executive summary generation
  - Visualization functions (trend, benchmark, volatility, convergence)

Initial formal release of the MineSDG analytics engine.