fix: canonicalize score brackets and assessments

scoring/engine.py

@@ -4,6 +4,8 @@ import json
 import os
 import logging
 
+from scoring.policy import SCORE_VERSION, assessment_for_score
+
 log = logging.getLogger(__name__)
 
 THRESHOLDS_PATH = os.path.join(
@@ -544,19 +546,7 @@ def score_all(metrics):
     else:
         composite = 0
 
-    # Assessment text — calibrated for cycle-aware scoring
-    if composite >= 80:
-        assessment = "EXTREME ACCUMULATION ZONE"
-    elif composite >= 65:
-        assessment = "STRONG ACCUMULATION ZONE"
-    elif composite >= 50:
-        assessment = "MODERATE OPPORTUNITY"
-    elif composite >= 35:
-        assessment = "NEUTRAL"
-    elif composite >= 20:
-        assessment = "CAUTION — OVERHEATED"
-    else:
-        assessment = "EXTREME CAUTION"
+    assessment = assessment_for_score(composite)
 
     return {
         "metrics": results,
@@ -564,6 +554,7 @@ def score_all(metrics):
         "assessment": assessment,
         "scored_count": len(valid_scores),
         "total_count": len(results),
+        "score_version": SCORE_VERSION,
     }
 
 
@@ -646,19 +637,7 @@ def score_all_ml(metrics):
         m["ml_weight"] = round(effective_weight, 4)
         m["ml_contribution"] = round(m["score"] * effective_weight * 10, 2)
 
-    # Assessment text (same thresholds as classic)
-    if composite >= 80:
-        assessment = "EXTREME ACCUMULATION ZONE"
-    elif composite >= 65:
-        assessment = "STRONG ACCUMULATION ZONE"
-    elif composite >= 50:
-        assessment = "MODERATE OPPORTUNITY"
-    elif composite >= 35:
-        assessment = "NEUTRAL"
-    elif composite >= 20:
-        assessment = "CAUTION — OVERHEATED"
-    else:
-        assessment = "EXTREME CAUTION"
+    assessment = assessment_for_score(composite)
 
     return {
         "metrics": results,
@@ -669,4 +648,5 @@ def score_all_ml(metrics):
         "ml_mode": True,
         "classic_score": classic["composite_score"],
         "ml_weight_total": round(weight_total, 4),
+        "score_version": SCORE_VERSION,
     }

scoring/policy.py

@@ -0,0 +1,35 @@
+"""Canonical score version, brackets, and assessment semantics."""
+
+SCORE_VERSION = "accumulation-score-v2"
+
+# Half-open intervals [low, high), except the final bracket includes 100.
+# Keep labels canonical because they are persisted in live and backtest output.
+SCORE_BRACKETS = [
+    (0, 20, "EXTREME CAUTION"),
+    (20, 35, "CAUTION — OVERHEATED"),
+    (35, 50, "NEUTRAL"),
+    (50, 65, "MODERATE OPPORTUNITY"),
+    (65, 80, "STRONG ACCUMULATION ZONE"),
+    (80, 100, "EXTREME ACCUMULATION ZONE"),
+]
+
+
+def score_in_bracket(score, bracket):
+    """Return whether a 0-100 score belongs to a canonical bracket."""
+    low, high, _ = bracket
+    if not 0 <= score <= 100:
+        return False
+    return low <= score < high or (high == 100 and score == 100)
+
+
+def bracket_for_score(score):
+    """Return the one canonical bracket for a 0-100 score."""
+    for bracket in SCORE_BRACKETS:
+        if score_in_bracket(score, bracket):
+            return bracket
+    raise ValueError(f"score must be between 0 and 100, got {score!r}")
+
+
+def assessment_for_score(score):
+    """Return the canonical assessment label for a score."""
+    return bracket_for_score(score)[2]