fix: gate recommendation review by horizon maturity (#20)

* fix: gate recommendation review by horizon maturity

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

* fix: require report-date price coverage

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

* fix: bound review start price delay

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

* fix: tighten review date and maturity boundaries

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

---------

Co-authored-by: Codex <noreply@openai.com>

Author: Pigbibi

docs/advisory_contract.md

@@ -226,7 +226,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
@@ -240,12 +240,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,8 @@
     "medium": "中线",
     "long": "长线",
 }
+MIN_MATURITY_TRADING_DAYS = {"short": 10, "medium": 10, "long": 252}
+MAX_START_BAR_DELAY_DAYS = 7
 
 
 def utc_now_iso() -> str:
@@ -46,10 +49,23 @@ def final_recommendations(report: dict[str, Any]) -> list[dict[str, Any]]:
 def first_bar_on_or_after(bars: list[PriceBar], target: dt.date) -> PriceBar | None:
     for bar in sorted(bars, key=lambda item: item.date):
         if bar.date >= target:
-            return bar
+            if (bar.date - target).days <= MAX_START_BAR_DELAY_DAYS:
+                return bar
+            return None
     return None
 
 
+def start_bar_for_report(bars: list[PriceBar], target: dt.date) -> PriceBar | None:
+    ordered = sorted(bars, key=lambda item: item.date)
+    exact = next((bar for bar in ordered if bar.date == target), None)
+    if exact:
+        return exact
+    previous = last_bar_on_or_before(ordered, target)
+    if previous and (target - previous.date).days <= MAX_START_BAR_DELAY_DAYS:
+        return previous
+    return first_bar_on_or_after(ordered, target)
+
+
 def last_bar_on_or_before(bars: list[PriceBar], target: dt.date) -> PriceBar | None:
     candidates = [bar for bar in bars if bar.date <= target]
     return max(candidates, key=lambda item: item.date) if candidates else None
@@ -61,11 +77,20 @@ 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_intervals: int,
+) -> str:
     if elapsed_days <= 0:
         return "pending"
     if not has_price_data:
         return "insufficient_price_data"
+    if trading_intervals < MIN_MATURITY_TRADING_DAYS.get(horizon, MIN_MATURITY_TRADING_DAYS["medium"]):
+        return "in_progress"
     if relative_return is None:
         return "insufficient_price_data"
     if relative_return >= 0.02:
@@ -109,9 +134,9 @@ def build_review_item(
     data_source: str,
 ) -> dict[str, Any]:
     symbol = str(pick.get("symbol", "")).upper()
-    start_bar = first_bar_on_or_after(symbol_bars, report_as_of)
+    start_bar = start_bar_for_report(symbol_bars, report_as_of)
     end_bar = last_bar_on_or_before(symbol_bars, review_as_of)
-    benchmark_start = first_bar_on_or_after(benchmark_bars, report_as_of)
+    benchmark_start = start_bar_for_report(benchmark_bars, report_as_of)
     benchmark_end = last_bar_on_or_before(benchmark_bars, review_as_of)
     has_price_data = bool(start_bar and end_bar and start_bar.date <= end_bar.date)
 
@@ -131,21 +156,41 @@ 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"])
+    trading_intervals = max(trading_observations - 1, 0)
+    if elapsed_days <= 0:
+        maturity_status = "pending"
+    elif not has_price_data:
+        maturity_status = "insufficient_price_data"
+    elif trading_intervals < 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,
+        "trading_intervals": trading_intervals,
+        "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_intervals=trading_intervals,
+        ),
         "market_data_source": data_source if has_price_data else "",
         "combined_score": pick.get("combined_score"),
         "source_score": pick.get("source_score"),
@@ -157,24 +202,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 +253,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 +327,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 +356,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 +368,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 +386,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')}",
                 "",
             ]