feat(P7b): explainable aggregate scores — expose denominator + formula

Matter readiness, the completeness grade and command/status coverage each now
carry a `math` block: numerator, denominator, the exact formula that reproduces
the percentage, and (for Matter) the functions excluded from the denominator
because their category has no Matter cluster — previously a silent skip and the
biggest "why is this number what it is?" gap. Completeness also states its band
thresholds. Report-only, additive; scores unchanged, only now auditable.
Raised by external review. tests/test_explainable_aggregates.py (12/12 green).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Nikolay1
2026-07-15 10:15:40 +02:00
co-authored by Claude Opus 4.8
parent f68c85bb48
commit 1a60264c78
4 changed files with 138 additions and 5 deletions
+8
View File
@@ -22,6 +22,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
- **Explainable aggregate scores** (`advanced.py`, `handover.py`). Every headline percentage now ships
the numbers behind it instead of a bare figure: Matter readiness, the completeness grade and
command/status coverage each carry a `math` block with the numerator, denominator, the exact formula
(that reproduces the percentage) and, for Matter, the functions **excluded** from the denominator
because their category has no Matter cluster (previously a silent skip — the biggest source of "why is
this number what it is?"). The completeness grade also states its band thresholds. A reviewer can now
audit or reproduce any score. Report-only, additive. Raised by external review. `tests/test_explainable_aggregates.py`.
- **Provenance / confidence** (`explain.py`, new MCP tool `explain_ga`). The enriched model mixes ETS
facts, DPT-derived structure and name heuristics; downstream tools then treat the result almost like a
fact. `explain_ga(address)` makes the reasoning auditable for one GA: per decision (category / kind /