QuantEngineByItz/spec/29_backtest_harness_contract.yaml

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
  - Temp/outcome_quality_score_v1.json
  - Temp/operational_alpha_calibration_v2.json
  - Temp/proposal_evaluation_history.json
  has_code_implementation: true
  code_path:
  - spec\29_backtest_harness_contract.yaml
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
    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
targets:
  t1_op_rate_min: 55
  t5_op_rate_min: 60
  t20_op_rate_min: 55
  win_rate_min: 50
  max_drawdown_max_pct: 20
  yaml_to_code_coverage: 1.0
  golden_coverage_min: 0.5
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:
  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
  - 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가 없는 상태에서 '검증된 전략' 단정 금지