# spec/29 — 백테스트 · Walk-forward 하네스 계약 (BACKTEST_HARNESS_V1)
#
# 목적: 전략이 과거 데이터에만 맞춰진 과최적화인지, 실제 운용 중 의미있는 예측력이 있는지
#       수치로 검증한다. 미충족 항목은 추정·날조하지 않고 insufficient_data로 표기한다.
#
# 계층: 감사·진단 계약(spec/28과 동급). GAS 런타임·주문 생성에 개입 없음.
# 구현: Python 계층(tools/*.py). 실측 누적 데이터가 없는 구간은 채울 수 없음을 명시.

meta:
  formula_id: BACKTEST_HARNESS_V1
  version: "2026-05-31"
  python_tool: "tools/build_yaml_code_coverage_v1.py (커버리지), tools/build_engine_audit_v1.py (집계)"
  sources:
    - Temp/prediction_accuracy_harness_v2.json    # T+1/T+5/T+20 정확도
    - Temp/outcome_quality_score_v1.json           # 운용 성과 질 점수
    - Temp/operational_alpha_calibration_v2.json   # 알파 보정
    - Temp/proposal_evaluation_history.json        # 제안-결과 이력

# ── 현재 실측 가능 지표 (2026-05-31 기준) ────────────────────────────────
current_metrics:
  direction_accuracy:
    t1_op_rate:
      value: 50.37
      n_sample: 546
      unit: percent
      interpretation: "동전던지기(50%) 수준 — 단기 방향 예측력 불충분"
    t5_op_rate:
      value: 73.24
      n_sample: 161
      unit: percent
      method: "decisive 케이스만(passive/ambiguous 제외). PREDICTION_ACCURACY_HARNESS_V2"
      interpretation: "T+5 능동 결정 케이스 73%. 전체 포함 레거시=31.94% — 표본 정의 혼용 금지"
    t5_legacy_rate:
      value: 31.94
      n_sample: "not_available"
      unit: percent
      interpretation: "전체 평가 윈도우 비율(거시이벤트 미제외). t5_op_rate와 다른 지표."
    t20_op_rate:
      value: insufficient_data
      n_sample: 0
      unit: percent
      interpretation: "T+20 실현 표본 0건 — 장기 예측력 검증 불가. t5_operational_proxy=73.24 사용 중(추정)"
    window_90d_rate:
      value: 31.94
      n_sample: "not_available"
      unit: percent
      interpretation: "최근 90일 창 일치율. 낮음."

  outcome_quality:
    score: 84.43
    gate: CAUTION_MODE
    t20_effective_rate: 73.24
    t20_source: t5_operational_proxy   # 실측 아님 — estimated=true
    t5_decisive_count: 161
    basis_note: "t20는 실측이 아니라 t5 proxy. 실측 T+20 누적 전까지 estimated."

  walk_forward:
    status: insufficient_data
    reason: >
      Walk-forward 검증을 위해 필요한 in-sample/out-of-sample 분리,
      기간별 성과 비교, slippage/cost 반영 데이터가 없음.
      backfill_eod_replay_history.py를 통해 이력 재현 시 채울 수 있음.

# ── 정의되어야 하나 현재 측정 불가한 지표 ─────────────────────────────────
missing_metrics:
  CAGR:
    status: insufficient_data
    required_data: "1년 이상 완전 실현 손익 이력"
  sharpe_ratio:
    status: insufficient_data
    required_data: "일별 수익률 시계열 + 무위험수익률"
  sortino_ratio:
    status: insufficient_data
    required_data: "일별 하락 편차 시계열"
  max_drawdown:
    status: insufficient_data
    required_data: "계좌 고점 추적 이력. portfolio_peak_krw 필드 존재하나 historical 없음"
  calmar_ratio:
    status: insufficient_data
    required_data: "CAGR / MDD"
  win_rate:
    status: insufficient_data
    required_data: "청산 완료 거래 이력. backdata에 MAE/MFE/pnl 모두 공란"
  profit_factor:
    status: insufficient_data
    required_data: "총 이익 / 총 손실 (실현 기준)"
  average_win_loss_ratio:
    status: insufficient_data
    required_data: "실현 수익/손실 건별 데이터"
  slippage_impact:
    status: insufficient_data
    required_data: "체결 가격 vs 지정가 괴리 이력"
  transaction_cost_impact:
    status: insufficient_data
    required_data: "수수료·세금 반영 순수익 이력"
  hit_rate_by_horizon:
    scalp: insufficient_data
    short_term: insufficient_data
    mid_term: insufficient_data
    long_term: insufficient_data

# ── 측정 가능한 회귀 지표 (현재 구현됨) ──────────────────────────────────
measurable_now:
  yaml_to_code_coverage_ratio:
    value: 1.0
    source: Temp/yaml_code_coverage_v1.json
  golden_test_coverage_ratio:
    value: 0.2337
    source: Temp/yaml_code_coverage_v1.json
    note: "43/184 공식 — golden 테스트 확대 필요"
  decision_reproducibility_score:
    value: 1.0
    method: "build_engine_audit_v1.py 10회 실행 byte-identical"
  llm_dependency_ratio:
    value: 0.0
    source: Temp/llm_freedom_v1.json
  schema_validity_score:
    value: 95.5
    source: Temp/data_quality_reconciliation_v1.json

# ── 목표치 (충족 시 PASS 판정) ──────────────────────────────────────────
targets:
  t1_op_rate_min: 55          # 현재 50.37 — 미달
  t5_op_rate_min: 60          # 현재 73.24 — 충족(주의: decisive 케이스 기준)
  t20_op_rate_min: 55         # 현재 insufficient_data
  win_rate_min: 50            # 현재 insufficient_data
  max_drawdown_max_pct: 20    # 현재 측정 불가
  yaml_to_code_coverage: 1.0  # 충족
  golden_coverage_min: 0.5    # 현재 0.23 — 미달

# ── 과최적화 경계 지표 ────────────────────────────────────────────────────
overfit_risk:
  in_sample_vs_oos_gap:
    status: insufficient_data
    note: "in-sample / out-of-sample 분리 없음"
  regime_dependency:
    note: >
      현재 포트폴리오는 RISK_ON 국면에 집중(SHORT 71.4% vs 25% 한도 위반).
      단일 국면 의존도 과다 — regime 다양화 필요.
  sample_size_warning:
    t1: "n=546 — 통계적으로 유의하나 변동 큼"
    t5: "n=161 — 최소 수준. 더 많은 누적 필요"
    t20: "n=0 — 미충족"

# ── 실측 표본 백필 의무화 (OPERATIONAL_SAMPLE_BACKFILL_V1) ─────────────────
# [SCAFFOLDED_PENDING_LIVE_DATA: operational_t5_sample_count=0, target>=30]
operational_sample_backfill:
  formula_id: OPERATIONAL_SAMPLE_BACKFILL_V1
  status: SCAFFOLDED_PENDING_LIVE_DATA
  current_live_sample_count: 0
  current_paper_sample_count: 0
  current_replay_sample_count: 510
  target_operational_t5_sample: 30
  target_operational_t20_sample: 30
  rationale: >
    live=0, paper=0, op_t20=0. REPLAY 510건은 예측력 증거가 못 된다(미래정보 누수 위험).
    실제 제안→실측 결과 연결 고리가 끊겨 있다.
  implementation_steps:
    - step: 1
      desc: "proposal_evaluation_history.json의 각 과거 제안(BUY/SELL/TRIM)에 entry_date, entry_price를 고정 기록"
      status: NOT_STARTED
    - step: 2
      desc: "T+5/T+20 경과 시 data_feed의 종가로 realized_return_pct 채움 (미래 데이터 사용 금지: 평가일 ≤ 오늘)"
      status: NOT_STARTED
    - step: 3
      desc: "origin 태그를 LIVE/PAPER/REPLAY로 명확히 분리. 예측력 지표는 LIVE+PAPER만 집계"
      status: NOT_STARTED
    - step: 4
      desc: "operational_t5_sample_count, operational_t20_sample_count 매 사이클 갱신"
      status: NOT_STARTED
    - step: 5
      desc: "표본 < 30인 동안 모든 예측력 지표에 '[UNVALIDATED_LIVE: n={n}]' 라벨 부착, PASS 금지(WATCH)"
      status: ACTIVE_GUARD
  outputs:
    - live_trade_outcome_ledger_v1.json  # LIVE/PAPER 채움
    - prediction_accuracy_harness_v5.json.operational_t5_sample
  numeric_acceptance:
    operational_t5_sample_count: {op: ">=", target: 30, current: 0, blocking: true}
    replay_contamination: {op: "==", target: 0, current: 0, note: "REPLAY 표본 예측지표 집계 혼입 금지"}
    future_leak: {op: "==", target: 0, note: "모든 realized_return 평가일 <= capture_date"}
  python_tools:
    - tools/backfill_eod_replay_history.py
    - tools/build_live_trade_outcome_ledger_v1.py
  gs_coverage: "gas_apex_runtime_core.gs:evaluateOperationalOutcomeBatch_()"
  validator: "tools/validate_outcome_eval_window.py --no-future-leak --min-live 30"
  unvalidated_label: "[UNVALIDATED_LIVE: n=0 < 30]"

# ── 금지 사항 ─────────────────────────────────────────────────────────────
prohibitions:
  - "insufficient_data 지표를 추정값으로 대체해 투자 판단에 사용 금지(AGENTS.md §0.3)"
  - "t5_op_rate(73%)와 window_90d_rate(31%)를 동일 지표로 혼용 금지"
  - "t20_op_rate=t5_operational_proxy를 실측 T+20으로 표기 금지 (estimated=true 필수)"
  - "CAGR/Sharpe/MDD가 없는 상태에서 '검증된 전략' 단정 금지"