Merge pull request #49 from easygap/feature/research-가격최신성검증

연구 백테스트 가격 최신성 검증 보강

Author: easygap

README.md

@@ -231,6 +231,6 @@ Target-weight pilot 승인/재시도 보강: `tools/paper_pilot_control.py --ena
 
 Target-weight 실행 차단 기록: `--execute`가 pilot cap validation에서 막히면 주문·체결·증거 수집 없이 session JSON artifact에 차단 사유를 남깁니다. runtime pilot session은 쓰지 않아 cap을 고친 뒤 같은 거래일 계획을 다시 점검할 수 있습니다. 또한 `plan.trade_day`와 KST 기준 실제 실행일이 다르거나, 현재 시간이 KRX 정규장 주문 가능 시간이 아니거나, 활성 pilot auth의 승인 snapshot이 현재 plan의 `params_hash`/trade day/targets/수량 장부와 다르면 주문, idempotency, 포지션 조회, 체결 대조, session 저장, 승격 증거 수집 전에 fail-closed로 차단합니다. no-order `--readiness-audit`와 `--daily-ops-summary`도 실행일 check, 장 시간 check, 승인 snapshot check를 blocker로 표시해 오래되었거나 장 외 실행 명령을 READY 상태로 노출하지 않습니다.
 
-Target-weight 가격 최신성 guard: 목표비중 plan 생성 시 종목별 마지막 실제 종가 날짜(`price_last_dates`)와 벤치마크 최신 날짜(`benchmark_last_date`)를 diagnostics에 남깁니다. ffill로 보정된 낡은 종목 가격이 `trade_day` 최신 가격처럼 쓰이면 `target_weight_stale_price_data`로 차단하고, `benchmark_excess` 점수나 benchmark risk overlay에 필요한 벤치마크 가격이 score day보다 오래되면 `target_weight_benchmark_price_stale`로 plan 생성 자체를 중단합니다. stale 가격으로 만든 수량·리스크·승격 증거가 pilot 흐름에 섞이지 않게 하는 운영 안전장치입니다.
+Target-weight 가격 최신성 guard: 목표비중 plan 생성 시 종목별 마지막 실제 종가 날짜(`price_last_dates`)와 벤치마크 최신 날짜(`benchmark_last_date`)를 diagnostics에 남깁니다. ffill로 보정된 낡은 종목 가격이 `trade_day` 최신 가격처럼 쓰이면 `target_weight_stale_price_data`로 차단하고, `benchmark_excess` 점수나 benchmark risk overlay에 필요한 벤치마크 가격이 score day보다 오래되면 `target_weight_benchmark_price_stale`로 plan 생성 자체를 중단합니다. research target-weight backtest도 원본 close panel을 보존해 평가일별 종목 가격 ffill 여부를 검증하고, 벤치마크 기반 점수/리스크 모드에서는 리밸런싱 score day의 실제 벤치마크 가격이 없으면 `target_weight_research_stale_price_data` 또는 `target_weight_research_benchmark_price_stale`로 fail-closed 중단합니다. stale 가격으로 만든 수량·리스크·승격 증거와 과대평가된 연구 성과가 pilot 흐름에 섞이지 않게 하는 안전장치입니다.
 
 Target-weight 승격 증거 보강: target-weight 계열 전략은 일반 `execution_backed=True` paper record만으로 promotion evidence day를 채우지 않습니다. `pilot_paper`/authorized record가 target-weight plan과 execution proof를 포함하고, record date와 plan trade day가 일치하며, `execution_trade_day_allowed=True`, `execution_market_session_allowed=True`, `pilot_authorization_snapshot_allowed=True`, liquidity/pre-trade risk/order result/fill/position reconciliation complete 및 plan/execution params hash 일치를 만족한 날만 승격 카운트에 들어갑니다. 60영업일 전체 verified pilot evidence는 하나의 params hash로 고정되어야 하며, live gate도 canonical metadata의 params hash와 paper evidence params hash가 다르면 target-weight live 전환을 차단합니다.

docs/BACKTEST_IMPROVEMENT.md

@@ -101,7 +101,7 @@
 | **방어형 후보 raw benchmark 해석** | cash-switch처럼 평균 노출이 낮은 후보는 full B&H 대비 excess가 과도하게 나빠 보일 수 있음 | **진단 추가** — research sweep에 exposure-matched B&H return/sharpe/MDD/excess 기록. 단, promotion gate는 raw benchmark excess 유지 |
 | **회전 전략의 sparse signal 한계** | 월간 상대강도 후보가 BUY/SELL 신호만 내면 목표 top-N을 지속적으로 채우지 못해 평균 노출이 낮게 측정될 수 있음 | **검증 완료** — target-weight top-N research backtester로 avg exposure 85%대까지 개선. 5종목 smoke는 raw excess 음수였지만 canonical top-20 full sweep은 alpha 후보 확인. `hold_rank_buffer` 적용 후 turnover gate 통과, `benchmark_risk` overlay 적용 후 best=`target_weight_rotation_top5_60_120_floor0_hold3_risk60_35`가 return=+210.24%, raw excess=+60.85%p, Sharpe=1.60, MDD=-19.24%, turnover/year=858.0%, WF positive/Sh+ 100%로 research sweep 기준 provisional gate 통과 |
 | **target-weight 후보의 paper 연결 부재** | research-only evaluator에서 provisional 후보가 나와도 기존 canonical/paper 경로는 등록 전략만 평가 | **대부분 해결** — canonical bundle 재현 완료 + `core/target_weight_rotation.py`, `tools/target_weight_rotation_pilot.py`로 전용 paper/pilot adapter 추가. dry-run은 `--record-shadow-evidence`, `--shadow-days 3`, 또는 `--shadow-start-date/--shadow-end-date`로 non-promotable shadow readiness evidence, launch readiness artifact, pilot runbook을 남기고 cap preview와 plan 기반 최소/추천 cap + enable 명령으로 pilot 승인 전 캡 적합성을 확인. 이후 `--readiness-audit`가 주문 제출, evidence 기록, pilot session 저장 없이 clean shadow/launch readiness, active pilot auth와 cap validation, 중복 session idempotency, 실행일/장 시간, 실행 전 position drift, 추천 cap 충족 여부, 유동성 preflight, 비용 반영 pre-trade risk를 JSON artifact와 Markdown 운영 리포트로 판정한다. 유동성 preflight는 최근 20일 평균 거래대금 대비 주문 notional 비율을 계산하고 기본 5%(`--max-order-adv-pct`) 초과 주문은 readiness와 실행을 fail-closed 차단한다. pre-trade risk는 `RiskManager.calculate_transaction_costs()`의 수수료/세금/동적 슬리피지 예상 체결가를 재사용해 현금 부족, 최소 현금비중, 총투자비중, 종목별 비중, 보유 종목 수 위반을 주문 제출 전에 차단한다. Markdown 리포트는 shadow 수집, audit 재실행, 추천 cap 승인, capped paper 실행 명령을 함께 남긴다. `--shadow-days N`은 휴장/데이터 공백으로 같은 거래일에 매핑될 때 과거 평일을 추가 스캔해 N개 고유 resolved trade_day 충족을 목표로 하며, 목표 미달이나 날짜별 실패는 non-zero 종료로 fail-closed 처리한다. 실행형 `pilot_paper` evidence는 같은 candidate/trade_day의 기존 pilot session artifact가 없고, 주문 제출 직전 실제 paper position이 계획 입력 장부 `position_quantities_before`와 일치하고, KST 실행일과 KRX 정규장 주문 가능 시간을 통과하고, 유동성 preflight와 pre-trade risk를 통과하고, 계획 주문 전부 성공 및 주문 결과 payload와 당일 `TradeHistory` fill 집계가 plan과 일치하며, 실행 후 실제 paper position 전체가 리밸런싱 후 `target_quantities_after` 장부와 일치하고 계획 밖 양수 포지션이 없을 때만 수집한다. 같은 날짜가 이미 기록된 경우에도 기존 canonical evidence가 `pilot_paper`/authorized/execution-backed이고 target-weight plan hash와 complete/execution-market-session/liquidity/pre-trade-risk/order/fill/position 검증을 통과해야 재사용해 중복 실행/stale plan/장 외 실행/부분 실행/중단/주문 결과 불일치/체결 기록 불일치/기존 evidence 검증 실패/포지션 불일치일이 승격 증거로 섞이지 않게 한다. 명시 재시도는 `--allow-rerun`으로만 허용한다. 다음 과제는 shadow clean days 충족 후 정규장 capped pilot_paper execution-backed evidence 축적 |
-| **target-weight stale 가격 ffill 위험** | 일부 종목 또는 벤치마크의 최신 데이터가 비었는데 panel ffill로 오래된 종가가 `trade_day` 최신 가격처럼 쓰이면 목표 수량·리스크·승격 증거가 왜곡될 수 있음 | **수정 완료** — `build_target_weight_plan()`이 종목별 `price_last_dates`와 `benchmark_last_date`를 diagnostics에 기록하고, stale 종목 가격은 `target_weight_stale_price_data`, stale benchmark는 `target_weight_benchmark_price_stale`로 plan 생성 전 fail-closed 차단 |
+| **target-weight stale 가격 ffill 위험** | 일부 종목 또는 벤치마크의 최신 데이터가 비었는데 panel ffill로 오래된 종가가 `trade_day`/research 평가일 최신 가격처럼 쓰이면 목표 수량·리스크·승격 증거·연구 성과가 왜곡될 수 있음 | **수정 완료** — `build_target_weight_plan()`이 종목별 `price_last_dates`와 `benchmark_last_date`를 diagnostics에 기록하고, stale 종목 가격은 `target_weight_stale_price_data`, stale benchmark는 `target_weight_benchmark_price_stale`로 plan 생성 전 fail-closed 차단. `run_target_weight_rotation_backtest()`도 원본 close panel 기준 평가일별 stale ffill과 리밸런싱 score day 벤치마크 누락을 `target_weight_research_stale_price_data`/`target_weight_research_benchmark_price_stale`로 중단 |
 | **백테스트 BlackSwan/어닝/갭 필터 미적용** | backtester에 BlackSwan, 어닝 필터, 갭 리스크 체크 미포함. paper/live에만 존재 | 백테스트-live 성과 차이 원인. 문서화됨 |
 
 ---
@@ -141,7 +141,7 @@
 | Paper 운영 도구 (tools/) | 높음 | **완료 — evidence pipeline, pilot control, bootstrap, preflight, launch readiness CLI** |
 | Entry filter 탐색 (market filter, abs momentum, cooling) | 중간 | **완료 — 모두 NO_MEANINGFUL_IMPROVEMENT 또는 ADVERSE EFFECT. 현행 유지** |
 | Research sweep exposure-matched benchmark | 중간 | **완료 — 후보별 평균 노출/현금비중과 exposure-matched B&H excess 진단 추가. promotion gate는 raw benchmark 기준 유지** |
-| Target-weight top-N rotation backtester | 높음 | **완료 — 월간 직전일 점수 기준 top-N 목표비중 리밸런싱, delta 거래비용, 노출 진단 구현. 5종목 smoke best +128.44%/Sharpe 1.13/avg exposure 85.3%지만 raw excess=-45.19%p. canonical top-20 full sweep best 기존 후보는 +212.21%/raw excess=+62.82%p였으나 turnover/year=1412.1%로 research-only** |
+| Target-weight top-N rotation backtester | 높음 | **완료 — 월간 직전일 점수 기준 top-N 목표비중 리밸런싱, delta 거래비용, 노출 진단 구현. 원본 close panel 기준 가격 최신성 검증을 포함해 ffill된 stale 종목/벤치마크 가격이 연구 성과에 섞이면 fail-closed 중단. 5종목 smoke best +128.44%/Sharpe 1.13/avg exposure 85.3%지만 raw excess=-45.19%p. canonical top-20 full sweep best 기존 후보는 +212.21%/raw excess=+62.82%p였으나 turnover/year=1412.1%로 research-only** |
 | Target-weight score-floor 후보 | 중간 | **완료 — `min_score_floor_pct`로 약한 초과 모멘텀 슬롯을 현금으로 남김. best=`target_weight_rotation_top5_60_120_floor0`, +210.21%/Sharpe 1.41/WF positive 100%였으나 turnover/year=1081.5%라 다음 과제는 turnover-aware 리밸런싱** |
 | Target-weight rank-hysteresis 후보 | 높음 | **완료 — `hold_rank_buffer`로 보유 종목이 top-N 밖으로 소폭 밀려도 버퍼 안이면 유지. best=`target_weight_rotation_top5_60_120_floor0_hold3`, +278.57%/Sharpe 1.65/WF positive 100%/turnover 807.8%. 남은 병목은 MDD=-28.25%** |
 | Target-weight shadow proof | 높음 | **완료 — dry-run plan을 `shadow_bootstrap` evidence로 기록하되 `execution_backed=False`, excess=null로 유지해 promotion을 오염시키지 않음. `--shadow-days` 기반 자동 날짜 선택은 N개 평일이 아니라 N개 고유 resolved trade_day를 목표로 과거 평일을 보충 스캔하며, 명시적 날짜 범위 batch도 지원. 목표 미달/날짜별 실패는 CLI non-zero 종료로 자동화가 불완전한 shadow proof를 성공 처리하지 못하게 차단. artifact와 runbook에 cap preview, plan 기반 최소/추천 cap, enable 명령, launch artifact 경로를 기록해 기본 pilot cap 부족(주문 수/포지션/1건 금액/총노출), clean day 부족, notifier/auth 누락을 사전 확인** |

tests/test_target_weight_rotation.py

@@ -209,6 +209,67 @@ def test_target_weight_plan_blocks_stale_benchmark_price_for_excess_scores():
     assert "benchmark_latest=2025-03-06" in message
 
 
+def test_target_weight_rotation_backtest_blocks_stale_symbol_price_after_ffill():
+    from tools.research_candidate_sweep import run_target_weight_rotation_backtest
+
+    frames = _frames_for_rotation()
+    frames["BBB"] = frames["BBB"][frames["BBB"]["date"] != pd.Timestamp("2025-02-03")]
+
+    with pytest.raises(ValueError, match="target_weight_research_stale_price_data") as exc:
+        run_target_weight_rotation_backtest(
+            symbols=["AAA", "BBB", "CCC"],
+            start="2025-02-03",
+            end="2025-02-05",
+            capital=100_000.0,
+            params={
+                "target_top_n": 2,
+                "target_exposure": 0.80,
+                "short_lookback": 2,
+                "long_lookback": 3,
+                "short_weight": 0.5,
+                "score_mode": "benchmark_excess",
+                "benchmark_symbol": "KS11",
+            },
+            collector=FakeCollector(frames),
+            risk_manager=NoCostRiskManager(),
+        )
+
+    message = str(exc.value)
+    assert "trade_day=2025-02-03" in message
+    assert "BBB=2025-01-31" in message
+
+
+def test_target_weight_rotation_backtest_blocks_stale_benchmark_price_for_excess_scores():
+    from tools.research_candidate_sweep import run_target_weight_rotation_backtest
+
+    frames = _frames_for_rotation()
+    frames["KS11"] = frames["KS11"][frames["KS11"]["date"] != pd.Timestamp("2025-01-31")]
+
+    with pytest.raises(ValueError, match="target_weight_research_benchmark_price_stale") as exc:
+        run_target_weight_rotation_backtest(
+            symbols=["AAA", "BBB", "CCC"],
+            start="2025-02-03",
+            end="2025-02-05",
+            capital=100_000.0,
+            params={
+                "target_top_n": 2,
+                "target_exposure": 0.80,
+                "short_lookback": 2,
+                "long_lookback": 3,
+                "short_weight": 0.5,
+                "score_mode": "benchmark_excess",
+                "benchmark_symbol": "KS11",
+            },
+            collector=FakeCollector(frames),
+            risk_manager=NoCostRiskManager(),
+        )
+
+    message = str(exc.value)
+    assert "trade_day=2025-02-03" in message
+    assert "score_day=2025-01-31" in message
+    assert "benchmark_latest=2025-01-30" in message
+
+
 def test_target_weight_rotation_uses_prior_day_scores_for_rebalance():
     from tools.research_candidate_sweep import run_target_weight_rotation_backtest
 

tools/research_candidate_sweep.py

@@ -1106,6 +1106,12 @@ def _score_date_before(index: pd.Index, day: pd.Timestamp) -> pd.Timestamp | Non
     return pd.Timestamp(prior[-1]).normalize()
 
 
+def _benchmark_required_for_target_weight(params: dict[str, Any]) -> bool:
+    score_mode = str(params.get("score_mode", "absolute")).lower().strip()
+    exposure_mode = str(params.get("market_exposure_mode", "fixed")).lower().strip()
+    return score_mode == "benchmark_excess" or exposure_mode.startswith("benchmark_")
+
+
 def _target_weight_score_panel(
     close_panel: pd.DataFrame,
     benchmark_close: pd.Series,
@@ -1389,12 +1395,14 @@ def run_target_weight_rotation_backtest(
                 },
             }
 
-        close_panel = pd.concat(close_parts, axis=1).sort_index().ffill()
-        close_panel = close_panel[~close_panel.index.duplicated(keep="last")]
+        raw_close_panel = pd.concat(close_parts, axis=1).sort_index()
+        raw_close_panel = raw_close_panel[~raw_close_panel.index.duplicated(keep="last")]
+        close_panel = raw_close_panel.ffill()
         benchmark_symbol = str(params.get("benchmark_symbol", "KS11"))
         benchmark_close = close_series_from_ohlcv(
             collector.fetch_korean_stock(benchmark_symbol, fetch_start, end)
         )
+        benchmark_close = benchmark_close[benchmark_close.index <= pd.Timestamp(end)]
         score_panel = _target_weight_score_panel(close_panel, benchmark_close, params)
 
         eval_index = close_panel.loc[
@@ -1403,10 +1411,62 @@ def run_target_weight_rotation_backtest(
         if len(eval_index) == 0:
             return {"equity_curve": pd.DataFrame(), "trades": [], "target_weight_metrics": {}}
 
+        eval_raw_prices = raw_close_panel.reindex(eval_index)
+        eval_filled_prices = close_panel.reindex(eval_index)
+        stale_price_mask = eval_raw_prices.isna() & eval_filled_prices.notna()
+        stale_price_mask = stale_price_mask.reindex(columns=valid_symbols).fillna(False)
+        stale_price_days = stale_price_mask.index[stale_price_mask.any(axis=1)]
+        if len(stale_price_days) > 0:
+            stale_day = pd.Timestamp(stale_price_days[0]).normalize()
+            stale_symbols = [
+                sym
+                for sym in valid_symbols
+                if sym in stale_price_mask.columns and bool(stale_price_mask.loc[stale_day, sym])
+            ]
+            stale_details = []
+            for sym in stale_symbols:
+                history = raw_close_panel.loc[
+                    raw_close_panel.index <= stale_day,
+                    sym,
+                ].dropna()
+                latest = (
+                    pd.Timestamp(history.index[-1]).strftime("%Y-%m-%d")
+                    if not history.empty
+                    else "missing"
+                )
+                stale_details.append(f"{sym}={latest}")
+            stale_text = ", ".join(stale_details[:10])
+            raise ValueError(
+                "target_weight_research_stale_price_data: "
+                f"trade_day={stale_day.strftime('%Y-%m-%d')} stale_symbols={stale_text}; "
+                "refresh market data before target-weight research backtest"
+            )
+
         top_n = max(1, int(params.get("target_top_n", 3)))
         tolerance = max(0.0, float(params.get("target_tolerance_pct", 0.0)) / 100.0)
         hold_rank_buffer = max(0, int(params.get("hold_rank_buffer", 0) or 0))
         rebalance_days = set(monthly_rebalance_days(eval_index))
+        benchmark_freshness_checked = _benchmark_required_for_target_weight(params)
+        if benchmark_freshness_checked:
+            benchmark_actual_days = pd.DatetimeIndex(benchmark_close.dropna().index).normalize()
+            for rebalance_day in sorted(rebalance_days):
+                score_day = _score_date_before(score_panel.index, rebalance_day)
+                if score_day is None or score_day in benchmark_actual_days:
+                    continue
+                history = benchmark_close.loc[benchmark_close.index <= score_day].dropna()
+                latest = (
+                    pd.Timestamp(history.index[-1]).strftime("%Y-%m-%d")
+                    if not history.empty
+                    else "missing"
+                )
+                raise ValueError(
+                    "target_weight_research_benchmark_price_stale: "
+                    f"benchmark_symbol={benchmark_symbol} "
+                    f"trade_day={pd.Timestamp(rebalance_day).strftime('%Y-%m-%d')} "
+                    f"score_day={pd.Timestamp(score_day).strftime('%Y-%m-%d')} "
+                    f"benchmark_latest={latest}; "
+                    "refresh benchmark data before target-weight research backtest"
+                )
         cash = float(capital)
         positions: dict[str, dict[str, float]] = {}
         trades: list[dict[str, Any]] = []
@@ -1498,6 +1558,8 @@ def run_target_weight_rotation_backtest(
                 "risk_off_rebalance_pct": round(
                     risk_off_rebalance_count / rebalance_count * 100, 1
                 ) if rebalance_count else 0,
+                "price_freshness_checked": True,
+                "benchmark_freshness_checked": benchmark_freshness_checked,
                 "target_weight_turnover_per_year": round(
                     total_turnover / capital / years * 100, 1
                 ) if capital > 0 else 0,