fix: gate recommendation review by horizon maturity

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

Author: Pigbibi

docs/advisory_contract.md

@@ -214,7 +214,7 @@ Recommendation follow-up reviews are separate audit artifacts generated from
 past final recommendations and cached point-in-time prices:
 
 ```text
-schema_version = 1
+schema_version = 2
 mode = recommendation_review
 as_of
 generated_at
@@ -228,12 +228,15 @@ policy
 
 Each `review_items[]` row carries the original report date, review date, symbol,
 primary horizon, price interval, absolute return, benchmark return,
-benchmark-relative return, outcome label, market data source, and original
-selection scores when present.
+benchmark-relative return, trading-observation count, maturity status, outcome
+label, market data source, and original selection scores when present. The
+minimum maturity is 10 trading days for short/medium and 252 trading days for
+long. Summary performance metrics are reported separately for each horizon.
 
 Allowed outcome labels:
 
 - `pending`
+- `in_progress`
 - `insufficient_price_data`
 - `outperforming`
 - `inline`

docs/system_design.md

@@ -116,8 +116,13 @@ price source without turning the repository into a paid market-data store.
 
 Recommendation follow-up review is a separate artifact. It reads past final
 recommendations, cached prices, and a benchmark, then reports absolute and
-relative returns by horizon. It is used for research accountability and data
-quality checks; it does not create new recommendations or execution targets.
+relative returns by horizon. Maturity is measured in trading observations:
+short and medium horizons require at least 10 trading days, while long requires
+252. Before maturity, an item remains `pending` or `in_progress` and cannot be
+labeled `outperforming` or `lagging`. Summary metrics (sample size, mean,
+median, and hit rate) stay within each horizon, and top symbols are
+de-duplicated. It is used for research accountability and data quality checks;
+it does not create new recommendations or execution targets.
 
 A separate no-network smoke command validates the three-repository contract:
 

docs/system_design.zh-CN.md

@@ -105,7 +105,7 @@ scripts/build_advisory_artifacts.py
 
 市场确认现在在 Yahoo chart 免费入口外面加了一层轻量价格缓存。线上 workflow 会用 GitHub Actions cache 恢复和保存 `.cache/market-data`。这样 Yahoo 临时不可用时，公开报告仍可以尽量用近期缓存继续生成；推荐跟踪复盘也可以使用 point-in-time 价格来源，而不把本仓库变成付费行情存储仓库。
 
-推荐跟踪复盘是单独 artifact。它读取历史最终推荐、缓存价格和基准指数，按周期计算绝对收益、相对收益和结果状态。它只用于研究问责和数据质量检查，不生成新的推荐，也不输出执行目标。
+推荐跟踪复盘是单独 artifact。它读取历史最终推荐、缓存价格和基准指数，按周期计算绝对收益、相对收益和结果状态。复盘按交易日判断成熟度：短线和中线至少 10 个交易日、长线至少 252 个交易日；未达到门槛只能是 `pending` 或 `in_progress`，不得提前标记为 `outperforming`/`lagging`。汇总只在各周期内部计算样本量、平均值、中位数和命中率，领先标的去重。它只用于研究问责和数据质量检查，不生成新的推荐，也不输出执行目标。
 
 跨仓库契约用 no-network smoke 命令验证：
 

src/quant_advisor_research/recommendation_review.py

@@ -3,6 +3,7 @@
 import argparse
 import datetime as dt
 import json
+import statistics
 from pathlib import Path
 from typing import Any
 
@@ -20,6 +21,7 @@
     "medium": "中线",
     "long": "长线",
 }
+MIN_MATURITY_TRADING_DAYS = {"short": 10, "medium": 10, "long": 252}
 
 
 def utc_now_iso() -> str:
@@ -61,13 +63,22 @@ def return_between(start: PriceBar, end: PriceBar) -> float:
     return round(end.close / start.close - 1, 6)
 
 
-def outcome_label(relative_return: float | None, *, elapsed_days: int, has_price_data: bool) -> str:
+def outcome_label(
+    relative_return: float | None,
+    *,
+    elapsed_days: int,
+    has_price_data: bool,
+    horizon: str,
+    trading_observations: int,
+) -> str:
     if elapsed_days <= 0:
         return "pending"
     if not has_price_data:
         return "insufficient_price_data"
     if relative_return is None:
         return "insufficient_price_data"
+    if trading_observations < MIN_MATURITY_TRADING_DAYS.get(horizon, MIN_MATURITY_TRADING_DAYS["medium"]):
+        return "in_progress"
     if relative_return >= 0.02:
         return "outperforming"
     if relative_return <= -0.02:
@@ -131,21 +142,39 @@ def build_review_item(
             relative_return = round(absolute_return - benchmark_return, 6)
 
     elapsed_days = (review_as_of - report_as_of).days
+    horizon = str(pick.get("primary_horizon", ""))
+    maturity_days = MIN_MATURITY_TRADING_DAYS.get(horizon, MIN_MATURITY_TRADING_DAYS["medium"])
+    if elapsed_days <= 0:
+        maturity_status = "pending"
+    elif not has_price_data:
+        maturity_status = "insufficient_price_data"
+    elif trading_observations < maturity_days:
+        maturity_status = "in_progress"
+    else:
+        maturity_status = "matured"
     return {
         "report_as_of": report_as_of.isoformat(),
         "review_as_of": review_as_of.isoformat(),
         "symbol": symbol,
         "name": str(pick.get("name", "")),
-        "primary_horizon": str(pick.get("primary_horizon", "")),
+        "primary_horizon": horizon,
         "primary_horizon_label": str(pick.get("primary_horizon_label", "")),
         "start_price_date": start_date,
         "end_price_date": end_date,
         "elapsed_calendar_days": elapsed_days,
         "trading_observations": trading_observations,
+        "maturity_required_trading_days": maturity_days,
+        "maturity_status": maturity_status,
         "absolute_return": absolute_return,
         "benchmark_return": benchmark_return,
         "relative_return": relative_return,
-        "outcome": outcome_label(relative_return, elapsed_days=elapsed_days, has_price_data=has_price_data),
+        "outcome": outcome_label(
+            relative_return,
+            elapsed_days=elapsed_days,
+            has_price_data=has_price_data,
+            horizon=horizon,
+            trading_observations=trading_observations,
+        ),
         "market_data_source": data_source if has_price_data else "",
         "combined_score": pick.get("combined_score"),
         "source_score": pick.get("source_score"),
@@ -157,24 +186,49 @@ def average(values: list[float]) -> float | None:
     return round(sum(values) / len(values), 6) if values else None
 
 
+def median(values: list[float]) -> float | None:
+    return round(float(statistics.median(values)), 6) if values else None
+
+
 def summarize_items(items: list[dict[str, Any]]) -> dict[str, Any]:
-    evaluated = [item for item in items if isinstance(item.get("relative_return"), (int, float))]
+    evaluated = [
+        item
+        for item in items
+        if item.get("maturity_status") == "matured" and isinstance(item.get("relative_return"), (int, float))
+    ]
     by_horizon: dict[str, dict[str, Any]] = {}
     for horizon in ("short", "medium", "long"):
         horizon_items = [item for item in items if item.get("primary_horizon") == horizon]
-        horizon_evaluated = [item for item in horizon_items if isinstance(item.get("relative_return"), (int, float))]
+        horizon_evaluated = [item for item in evaluated if item.get("primary_horizon") == horizon]
+        horizon_returns = [float(item["relative_return"]) for item in horizon_evaluated]
+        horizon_ranked = sorted(
+            [item for item in horizon_evaluated if item.get("outcome") == "outperforming"],
+            key=lambda item: (float(item.get("relative_return", 0)), str(item.get("symbol", ""))),
+            reverse=True,
+        )
         by_horizon[horizon] = {
             "label": HORIZON_LABELS_ZH[horizon],
             "item_count": len(horizon_items),
             "evaluated_count": len(horizon_evaluated),
+            "sample_size": len(horizon_evaluated),
             "pending_count": sum(1 for item in horizon_items if item.get("outcome") == "pending"),
+            "in_progress_count": sum(1 for item in horizon_items if item.get("outcome") == "in_progress"),
+            "matured_count": sum(1 for item in horizon_items if item.get("maturity_status") == "matured"),
             "insufficient_price_data_count": sum(
                 1 for item in horizon_items if item.get("outcome") == "insufficient_price_data"
             ),
-            "average_relative_return": average([float(item["relative_return"]) for item in horizon_evaluated]),
+            "average_relative_return": average(horizon_returns),
+            "median_relative_return": median(horizon_returns),
+            "hit_rate": round(
+                sum(1 for item in horizon_evaluated if item.get("outcome") == "outperforming") / len(horizon_evaluated),
+                6,
+            )
+            if horizon_evaluated
+            else None,
+            "top_outperformers": unique_symbols(horizon_ranked),
         }
     ranked = sorted(
-        evaluated,
+        [item for item in evaluated if item.get("outcome") == "outperforming"],
         key=lambda item: (float(item.get("relative_return", 0)), str(item.get("symbol", ""))),
         reverse=True,
     )
@@ -183,12 +237,24 @@ def summarize_items(items: list[dict[str, Any]]) -> dict[str, Any]:
         "evaluated_count": len(evaluated),
         "pending_count": sum(1 for item in items if item.get("outcome") == "pending"),
         "insufficient_price_data_count": sum(1 for item in items if item.get("outcome") == "insufficient_price_data"),
-        "average_relative_return": average([float(item["relative_return"]) for item in evaluated]),
+        # Do not pool short-, medium-, and long-horizon performance into one statistic.
+        "average_relative_return": None,
+        "median_relative_return": None,
+        "hit_rate": None,
         "by_horizon": by_horizon,
-        "top_outperformers": [item["symbol"] for item in ranked[:5]],
+        "top_outperformers": unique_symbols(ranked)[:5],
     }
 
 
+def unique_symbols(items: list[dict[str, Any]]) -> list[str]:
+    symbols: list[str] = []
+    for item in items:
+        symbol = str(item.get("symbol", ""))
+        if symbol and symbol not in symbols:
+            symbols.append(symbol)
+    return symbols[:5]
+
+
 def build_recommendation_review(
     *,
     report_paths: list[str | Path],
@@ -245,7 +311,7 @@ def build_recommendation_review(
             )
 
     return {
-        "schema_version": "1",
+        "schema_version": "2",
         "mode": "recommendation_review",
         "as_of": as_of.isoformat(),
         "generated_at": utc_now_iso(),
@@ -274,9 +340,9 @@ def render_recommendation_review_markdown(review: dict[str, Any]) -> str:
             f"- 复盘条目：{summary.get('item_count', 0)}",
             f"- 已可评估：{summary.get('evaluated_count', 0)}",
             f"- 待观察：{summary.get('pending_count', 0)}",
+            f"- 进行中：{sum(item.get('in_progress_count', 0) for item in summary.get('by_horizon', {}).values())}",
             f"- 缺少价格数据：{summary.get('insufficient_price_data_count', 0)}",
-            f"- 平均相对收益：{display_percent(summary.get('average_relative_return'))}",
-            f"- 领先标的：{', '.join(summary.get('top_outperformers', [])) or '暂无'}",
+            "- 不同持有期不合并计算平均收益；以下按周期分别统计。",
             "",
             "## 周期分布",
             "",
@@ -286,7 +352,9 @@ def render_recommendation_review_markdown(review: dict[str, Any]) -> str:
         item = summary.get("by_horizon", {}).get(horizon, {})
         lines.append(
             f"- {item.get('label', horizon)}：{item.get('evaluated_count', 0)}/{item.get('item_count', 0)} 已评估，"
-            f"平均相对收益 {display_percent(item.get('average_relative_return'))}"
+            f"样本量 {item.get('sample_size', 0)}，平均 {display_percent(item.get('average_relative_return'))}，"
+            f"中位数 {display_percent(item.get('median_relative_return'))}，命中率 {display_percent(item.get('hit_rate'))}，"
+            f"领先标的 {', '.join(item.get('top_outperformers', [])) or '暂无'}"
         )
     warnings = review.get("data_quality_warnings", [])
     if warnings:
@@ -302,6 +370,8 @@ def render_recommendation_review_markdown(review: dict[str, Any]) -> str:
                 f"- 价格区间：{item.get('start_price_date') or '无'} 到 {item.get('end_price_date') or '无'}",
                 f"- 绝对收益：{display_percent(item.get('absolute_return'))}",
                 f"- 相对 {review.get('benchmark')}：{display_percent(item.get('relative_return'))}",
+                f"- 成熟度：{item.get('maturity_status')}（需要 {item.get('maturity_required_trading_days', 0)} 个交易日，"
+                f"当前 {item.get('trading_observations', 0)} 个）",
                 f"- 状态：{item.get('outcome')}",
                 "",
             ]

tests/test_recommendation_review.py

@@ -18,7 +18,7 @@ def make_bars(start: dt.date, prices: list[float]) -> list[PriceBar]:
     ]
 
 
-def write_report(path: Path, *, as_of: str = "2026-01-05") -> None:
+def write_report(path: Path, *, as_of: str = "2026-01-05", horizon: str = "medium", symbol: str = "MU") -> None:
     path.write_text(
         json.dumps(
             {
@@ -27,9 +27,9 @@ def write_report(path: Path, *, as_of: str = "2026-01-05") -> None:
                 "final_decisions": {
                     "recommendations": [
                         {
-                            "symbol": "MU",
+                            "symbol": symbol,
                             "name": "Micron Technology",
-                            "primary_horizon": "medium",
+                            "primary_horizon": horizon,
                             "primary_horizon_label": "中线",
                             "combined_score": 0.84,
                             "source_score": 0.2,
@@ -43,12 +43,12 @@ def write_report(path: Path, *, as_of: str = "2026-01-05") -> None:
     )
 
 
-def test_recommendation_review_calculates_forward_relative_return_from_cache(tmp_path: Path) -> None:
+def test_recommendation_review_keeps_short_review_in_progress_until_ten_trading_days(tmp_path: Path) -> None:
     cache_dir = tmp_path / "market-cache"
     write_cached_bars("MU", make_bars(dt.date(2026, 1, 5), [100, 102, 105, 108, 112, 116]), cache_dir=cache_dir)
     write_cached_bars("SPY", make_bars(dt.date(2026, 1, 5), [100, 101, 102, 103, 104, 105]), cache_dir=cache_dir)
     report_path = tmp_path / "advisory_report_2026-01-05.json"
-    write_report(report_path)
+    write_report(report_path, horizon="short")
 
     review = build_recommendation_review(
         report_paths=[report_path],
@@ -64,12 +64,73 @@ def test_recommendation_review_calculates_forward_relative_return_from_cache(tmp
     assert item["absolute_return"] == 0.16
     assert item["benchmark_return"] == 0.05
     assert item["relative_return"] == 0.11
-    assert item["outcome"] == "outperforming"
-    assert review["summary"]["evaluated_count"] == 1
-    assert review["summary"]["top_outperformers"] == ["MU"]
+    assert item["maturity_status"] == "in_progress"
+    assert item["outcome"] == "in_progress"
+    assert review["summary"]["evaluated_count"] == 0
+    assert review["summary"]["by_horizon"]["short"]["evaluated_count"] == 0
     assert "MU" in render_recommendation_review_markdown(review)
 
 
+def test_recommendation_review_reports_matured_metrics_by_horizon(tmp_path: Path) -> None:
+    cache_dir = tmp_path / "market-cache"
+    prices = [100 + index for index in range(12)]
+    write_cached_bars("MU", make_bars(dt.date(2026, 1, 5), prices), cache_dir=cache_dir)
+    write_cached_bars("SPY", make_bars(dt.date(2026, 1, 5), [100] * 12), cache_dir=cache_dir)
+    report_path = tmp_path / "advisory_report_2026-01-05.json"
+    write_report(report_path, horizon="short")
+
+    review = build_recommendation_review(
+        report_paths=[report_path], as_of=dt.date(2026, 1, 20), benchmark="SPY",
+        cache_dir=cache_dir, cache_max_age_days=30, use_network=False,
+    )
+
+    item = review["review_items"][0]
+    assert item["maturity_status"] == "matured"
+    assert item["outcome"] == "outperforming"
+    short_summary = review["summary"]["by_horizon"]["short"]
+    assert short_summary["sample_size"] == 1
+    assert short_summary["median_relative_return"] == short_summary["average_relative_return"]
+    assert short_summary["hit_rate"] == 1.0
+
+
+def test_top_outperformers_are_unique_and_grouped_by_horizon(tmp_path: Path) -> None:
+    cache_dir = tmp_path / "market-cache"
+    write_cached_bars("MU", make_bars(dt.date(2026, 1, 5), [100] * 15), cache_dir=cache_dir)
+    write_cached_bars("AMD", make_bars(dt.date(2026, 1, 5), [100 + index for index in range(15)]), cache_dir=cache_dir)
+    write_cached_bars("SPY", make_bars(dt.date(2026, 1, 5), [100] * 15), cache_dir=cache_dir)
+    reports = []
+    for index, (symbol, horizon) in enumerate((("AMD", "short"), ("AMD", "short"), ("MU", "medium"))):
+        path = tmp_path / f"report-{index}.json"
+        write_report(path, horizon=horizon, symbol=symbol)
+        reports.append(path)
+
+    review = build_recommendation_review(
+        report_paths=reports, as_of=dt.date(2026, 1, 25), benchmark="SPY",
+        cache_dir=cache_dir, cache_max_age_days=14, use_network=False,
+    )
+
+    assert review["summary"]["top_outperformers"] == ["AMD"]
+    assert review["summary"]["by_horizon"]["short"]["top_outperformers"] == ["AMD"]
+
+
+def test_long_horizon_cannot_be_labeled_lagging_after_a_few_weeks(tmp_path: Path) -> None:
+    cache_dir = tmp_path / "market-cache"
+    write_cached_bars("TSM", make_bars(dt.date(2026, 1, 5), [100, 90, 80, 70, 60]), cache_dir=cache_dir)
+    write_cached_bars("SPY", make_bars(dt.date(2026, 1, 5), [100] * 5), cache_dir=cache_dir)
+    report_path = tmp_path / "advisory_report_2026-01-05.json"
+    write_report(report_path, horizon="long", symbol="TSM")
+
+    review = build_recommendation_review(
+        report_paths=[report_path], as_of=dt.date(2026, 1, 30), benchmark="SPY",
+        cache_dir=cache_dir, cache_max_age_days=30, use_network=False,
+    )
+
+    item = review["review_items"][0]
+    assert item["elapsed_calendar_days"] > 14
+    assert item["maturity_status"] == "in_progress"
+    assert item["outcome"] == "in_progress"
+
+
 def test_recommendation_review_marks_same_day_report_as_pending(tmp_path: Path) -> None:
     report_path = tmp_path / "advisory_report_2026-01-05.json"
     write_report(report_path)