fix: separate source score from final decision tiers

Co-Authored-By: Codex <noreply@openai.com>

Author: Pigbibi

docs/advisory_contract.md

@@ -154,6 +154,7 @@ list while preserving audit details in JSON:
 ```text
 recommendations[]
 watchlist[]
+overflow_recommendations[]
 horizon_buckets.short | medium | long
 horizon_rankings.short | medium | long
 horizon_action_buckets.short | medium | long
@@ -177,6 +178,17 @@ why_selected[]
 risk_summary
 ```
 
+Section semantics are strict: `recommendations[]` and
+`overflow_recommendations[]` contain only items with `action = "recommend"`;
+`watchlist[]` contains only items with `action = "watch"`.
+`overflow_recommendations[]` preserves valid recommendations outside the public
+top-N list without relabeling them as watchlist items.
+
+For compatibility, `summary.recommendation_count` remains the base-layer
+`recommendations[]` count. The final layer separately reports
+`base_recommendation_count`, `final_recommendation_count`,
+`final_watchlist_count`, and `final_overflow_recommendation_count`.
+
 Scoring and gate intent by horizon:
 
 - short: recent market confirmation is required; event/news evidence and momentum

src/quant_advisor_research/advisory_report.py

@@ -886,18 +886,12 @@ def normalize_source_score(rec: dict[str, Any] | None) -> float:
         "unknown": 0.1,
         "no_event": 0.0,
     }
-    tier_scores = {
-        "tier_1": 1.0,
-        "tier_2": 0.85,
-        "watchlist": 0.6,
-        "source_check": 0.25,
-        "defer": 0.0,
-        "monitor": 0.0,
-    }
+    if str(rec.get("source_confidence", "")) == "no_event":
+        return 0.0
     evidence_component = clamp(as_float(rec.get("evidence_score")) / 18, 0, 1)
     confidence_component = confidence_scores.get(str(rec.get("source_confidence", "")), 0.0)
     blended = evidence_component * 0.65 + confidence_component * 0.35
-    return round(max(blended, tier_scores.get(str(rec.get("recommendation_tier", "")), 0.0)), 3)
+    return round(blended, 3)
 
 
 def theme_symbol_context(theme_momentum: dict[str, Any] | None) -> dict[str, dict[str, Any]]:
@@ -1328,10 +1322,13 @@ def build_final_decisions(
     recommendation_candidates = [item for item in picks if item["action"] == "recommend"]
     recommendations_out = recommendation_candidates[:max_recommendations]
     recommendation_symbols = {item["symbol"] for item in recommendations_out}
+    overflow_recommendations = [
+        item for item in recommendation_candidates if item["symbol"] not in recommendation_symbols
+    ]
     watchlist_out = [
         item
         for item in picks
-        if item["action"] == "watch" or (item["action"] == "recommend" and item["symbol"] not in recommendation_symbols)
+        if item["action"] == "watch"
     ][:max_watchlist]
     horizon_buckets = {
         horizon: [item["symbol"] for item in recommendations_out if item.get("primary_horizon") == horizon]
@@ -1373,6 +1370,7 @@ def build_final_decisions(
         "method": "Final recommendation blend for model scoring.",
         "recommendations": recommendations_out,
         "watchlist": watchlist_out,
+        "overflow_recommendations": overflow_recommendations,
         "horizon_buckets": horizon_buckets,
         "horizon_rankings": horizon_rankings,
         "horizon_action_buckets": horizon_action_buckets,
@@ -1488,7 +1486,12 @@ def build_advisory_report(
             "market_confirmation": str(market_confirmation_path) if market_confirmation_path else "",
         },
         "summary": {
+            # Keep recommendation_count as the historical base-layer count.
             "recommendation_count": len(recommendations),
+            "base_recommendation_count": len(recommendations),
+            "final_recommendation_count": len(final_decisions["recommendations"]),
+            "final_watchlist_count": len(final_decisions["watchlist"]),
+            "final_overflow_recommendation_count": len(final_decisions["overflow_recommendations"]),
             "candidate_universe_count": len(all_recommendations),
             "source_event_count": len(events),
             "ai_regime": ai_signal.get("regime", "not_available") if ai_signal else "not_available",

src/quant_advisor_research/contracts.py

@@ -198,7 +198,12 @@ def validate_advisory_report(payload: Mapping[str, Any]) -> None:
 
     if "final_decisions" in payload:
         final_decisions = _require_mapping(payload["final_decisions"], "final_decisions")
-        for section in ("recommendations", "watchlist"):
+        section_actions = {
+            "recommendations": "recommend",
+            "watchlist": "watch",
+            "overflow_recommendations": "recommend",
+        }
+        for section, expected_action in section_actions.items():
             for index, pick in enumerate(_require_sequence(final_decisions.get(section, []), f"final_decisions.{section}")):
                 item = _require_mapping(pick, f"final_decisions.{section}[{index}]")
                 account_keys = sorted(DISALLOWED_ACCOUNT_ACTION_KEYS & set(item))
@@ -207,6 +212,10 @@ def validate_advisory_report(payload: Mapping[str, Any]) -> None:
                         f"final_decisions.{section}[{index}] contains account-action fields: {', '.join(account_keys)}"
                     )
                 _require_string(item.get("symbol"), f"final_decisions.{section}[{index}].symbol")
+                if item.get("action") != expected_action:
+                    raise AdvisoryValidationError(
+                        f"final_decisions.{section}[{index}].action must be {expected_action}"
+                    )
                 if "horizon_scores" in item:
                     horizon_scores = _require_mapping(
                         item["horizon_scores"], f"final_decisions.{section}[{index}].horizon_scores"

tests/test_advisory_report.py

@@ -5,7 +5,14 @@
 
 import pytest
 
-from quant_advisor_research.advisory_report import build_advisory_report, primary_horizon_from_actions, render_markdown
+from quant_advisor_research.advisory_report import (
+    build_advisory_report,
+    build_final_decisions,
+    load_theme_momentum,
+    normalize_source_score,
+    primary_horizon_from_actions,
+    render_markdown,
+)
 from quant_advisor_research.artifacts import write_report_manifest
 from quant_advisor_research.contracts import AdvisoryValidationError, validate_advisory_report
 
@@ -307,10 +314,10 @@ def test_theme_bias_can_lift_static_watchlist_item_without_direct_symbol_bias(tm
     assert rec["rating"] == "watch"
     assert rec["evidence_score"] > 4
     assert any("主题=hbm_memory" in reason for reason in rec["reasons"])
-    assert report["summary"]["long_context_available"] is True
-    assert report["summary"]["long_context_missing_reason"] == ""
-    assert "MU" in report["summary"]["long_context_symbols"]
-    assert report["final_decisions"]["horizon_action_buckets"]["long"]["watch"][:1] == ["MU"]
+    assert report["summary"]["long_context_available"] is False
+    assert report["summary"]["long_context_missing_reason"] == "current_candidates_do_not_meet_long_context_gate"
+    assert "MU" not in report["summary"]["long_context_symbols"]
+    assert report["final_decisions"]["horizon_action_buckets"]["long"]["watch"] == []
 
 
 def test_theme_momentum_snapshot_is_display_context_not_rating_input(tmp_path: Path) -> None:
@@ -443,3 +450,53 @@ def test_contract_rejects_final_decision_account_action_fields() -> None:
 
     with pytest.raises(AdvisoryValidationError):
         validate_advisory_report(report)
+
+
+def test_source_score_does_not_use_recommendation_tier_prior() -> None:
+    assert normalize_source_score(
+        {
+            "evidence_score": 5,
+            "source_confidence": "no_event",
+            "recommendation_tier": "watchlist",
+        }
+    ) == 0.0
+
+
+def test_final_decision_sections_keep_action_semantics_and_overflow() -> None:
+    report = build_advisory_report(
+        as_of="2026-05-30",
+        cadence="weekly",
+        political_events_path=ROOT / "examples/political_events.example.csv",
+        political_watchlist_path=ROOT / "examples/political_watchlist.example.csv",
+        ai_signal_path=ROOT / "examples/research_signal_context.example.json",
+        theme_momentum_path=ROOT / "examples/theme_momentum_snapshot.example.json",
+    )
+    decisions = build_final_decisions(
+        report["recommendations"],
+        load_theme_momentum(ROOT / "examples/theme_momentum_snapshot.example.json"),
+        max_recommendations=1,
+        max_watchlist=1,
+    )
+
+    assert all(item["action"] == "recommend" for item in decisions["recommendations"])
+    assert all(item["action"] == "watch" for item in decisions["watchlist"])
+    assert all(item["action"] == "recommend" for item in decisions["overflow_recommendations"])
+    assert decisions["overflow_recommendations"]
+    assert report["summary"]["recommendation_count"] == report["summary"]["base_recommendation_count"]
+    assert report["summary"]["final_recommendation_count"] == len(report["final_decisions"]["recommendations"])
+    assert report["summary"]["final_watchlist_count"] == len(report["final_decisions"]["watchlist"])
+
+
+def test_contract_rejects_final_decision_section_action_mismatch() -> None:
+    report = build_advisory_report(
+        as_of="2026-05-30",
+        cadence="weekly",
+        political_events_path=ROOT / "examples/political_events.example.csv",
+        political_watchlist_path=ROOT / "examples/political_watchlist.example.csv",
+        ai_signal_path=ROOT / "examples/research_signal_context.example.json",
+        theme_momentum_path=ROOT / "examples/theme_momentum_snapshot.example.json",
+    )
+    report["final_decisions"]["watchlist"][0]["action"] = "recommend"
+
+    with pytest.raises(AdvisoryValidationError, match="watchlist.*action must be watch"):
+        validate_advisory_report(report)