feat: 성과 귀속 자동화 — 실행 격차/구성 격차 분해

[easygap]

무엇

한 달 운영 리뷰(docs/PAPER_MONTH1_REVIEW_AND_PLAN.md P1-4·§2)의 성과 귀속 분해를 자동화합니다. 리뷰에서 손으로 계산했던 "실행 격차 vs 구성 격차"를 평가 도구가 매 실행 자동 산출합니다.

왜

-5.47%라는 벤치마크 대비 격차가 내 실행 실수(통제 가능) 때문인지, 균등가중 설계의 성격(수용된 변동) 때문인지 구분되지 않으면 "프로그램이 못 번다"로 오독됩니다. 이 분해가 그 질문에 매 실행 답합니다:

• 실행 격차 = 실제 NAV − 설계 NAV (미체결 슬롯·진입 타이밍·비용 → 0에 가까워야 정상)
• 구성 격차 = 설계 NAV − KS11 (균등가중 vs 시총지수 → 전략 성격)
• 항등식: 실행 격차 + 구성 격차 = 총 격차(실제 − 벤치)

무엇을 했나

• core/basket_evaluation.py
  • 순수 decompose_return_gap(nav, design, benchmark) — 세 격차 산출(None 전파).
  • compute_design_portfolio_return(holdings, stock_fraction, start, end, fetch=None) — 종목별 구간 수익 가중평균 × 주식비중(현금 슬리브 0%), 조회 실패 종목은 재정규화. fetch 주입 가능(테스트).
  • collect_basket_paper_evaluation(..., include_attribution=False) — True일 때만 설계 수익·분해를 계산해 metrics에 주입. 기본 off → 일일 사이클은 종목별 조회(네트워크) 부담 없음.
  • format_evaluation_report가 분해를 출력.
• tools/basket_paper_evaluation.py — 기본 ON(--no-attribution로 생략).

실CLI 스모크 + 적대적 리뷰

• 실데이터: 설계 NAV -3.55% / 실행 -1.92%p + 구성 -5.62%p(합 = 총 격차, 항등식 일치).
• 다중 에이전트 리뷰(6건 제기 → 1 확정 medium + 1 uncertain[by-design]) 반영:
  • [medium] 창 불일치 — NAV는 마지막 스냅샷 시점 값인데 벤치마크·설계는 오늘 종가까지 조회 → 하루치 시장 변동이 실행 격차로 오귀속될 수 있었음. 세 값의 종료일을 NAV 스냅샷 시점으로 정합(기존 벤치마크 창 불일치도 함께 해소).
  • uncertain(구성 격차 라벨이 설계 현금 드래그 포함) — 오너 문서(§2)의 채택 방식을 그대로 반영한 것이라 by-design, 변경 없음.

테스트

• tests/test_return_attribution.py — 분해 항등식·가중평균·현금 슬리브·조회실패 재정규화·None 전파(월1 실측 숫자 포함).
• 전체 스위트 통과.