meta:
  title: "은퇴자산포트폴리오 — 시장국면 전용 명세"
  parent_file: "RetirementAssetPortfolio.yaml"
  version: "2026-05-16-F6_kosdaq_strict"
  language: "ko-KR"
  timezone: "Asia/Seoul"
  role: "derived_adapter"
  purpose: >
    흩어진 Risk-On/Neutral/Risk-Off 판정을 단일 명세로 고정한다.
    이 파일은 국면 판정만 담당하며, 개별 종목 매수 결론은 strategy/scoring/portfolio/sizing을 추가 통과해야 한다.
  authority_rule: "이 파일은 시장국면 판정 adapter다. MRS 현금 수치와 리스크 차단은 spec/risk/market_risk_cash.yaml, spec/risk/aggregate_risk.yaml, spec/risk/portfolio_exposure.yaml을 우선한다."

market_regime:
  canonical_for: "market_regime_classification_only"
  output_field: "market_regime_state"
  allowed_states:
    - "RISK_ON"
    - "LEADER_CONCENTRATION"
    - "SECULAR_LEADER_RISK_ON"
    - "CONCENTRATED_LEADER_ADVANCE"
    - "NEUTRAL"
    - "RISK_OFF"
    - "EVENT_SHOCK"
    - "UNKNOWN"
  required_inputs:
    - "KOSPI close and MA20/MA60"
    - "KOSDAQ close and MA20 where available"
    - "VIX close"
    - "USD/KRW"
    - "US10Y"
    - "sector_flow.Rotation_Score"
    - "foreign/institution 5D/20D flow"
    - "event_risk high impact calendar"
  data_sources:
    primary:
      - "spec/02_data_contract.yaml:quant_feed_contract.source_priority"
      - "Google Sheets macro, sector_flow, data_feed, event_risk"
    fallback:
      - "KRX"
      - "Naver Finance"
      - "Yahoo Finance"
      - "official central bank / exchange data"
  missing_policy:
    rule: "핵심 거시 입력 2개 이상 누락 시 UNKNOWN으로 판정하고 신규 BUY는 최대 B-조건부 또는 WATCH."
    prohibition:
      - "거시 데이터 누락 상태에서 Risk-On으로 추정 금지"
      - "뉴스 헤드라인만으로 EVENT_SHOCK 판정 금지"

state_rules:
  RISK_ON:
    condition_all:
      - "VIX_Close < 18"
      - "KOSPI_Close > KOSPI_MA20"
      - "KOSPI_MA20 >= KOSPI_MA60 OR KOSPI_Ret20D > 0"
    condition_one:
      - "foreign_20d_flow > 0"
      - "institution_20d_flow > 0"
      - "sector_flow top2_rotation_sum >= 100"
    portfolio_implication:
      - "A/B 후보 정상 검토"
      - "단, anti_climax_buy_gate와 Total_Heat는 계속 우선"
      - "선행형 시범진입 허용 가능"
    canonical_refs:
      - "spec/strategy/entry_core.yaml:entry_timing_guardrails.regime_based_entry.risk_on"
      - "spec/risk/market_risk_cash.yaml:risk_control.market_risk_score_based_cash"
  LEADER_CONCENTRATION:
    condition_all:
      - "top2_rotation_sum >= 100"
      - "top1_rotation_score >= 55"
      - "top1_alert_score >= 2"
      - "leader_sector_flag == 1"
      - "KOSPI_Ret20D > 0"
      - "VIX_Close < 25"
    portfolio_implication:
      - "주도 섹터 후보 우선 점검"
      - "pilot_tranche만 허용 후 확인 매수"
      - "중복노출·현금·Total_Heat 통과 필수"
    canonical_refs:
      - "spec/strategy/entry_core.yaml:entry_timing_guardrails.regime_based_entry.leader_concentration"
  SECULAR_LEADER_RISK_ON:  # [proposal_83 / 2026-05-16] LEADER_CONCENTRATION 상위 공격 모드 — 반도체 주도주 집중 강세장
    prerequisite: "LEADER_CONCENTRATION 조건을 모두 충족한 상태에서 추가 조건을 만족할 때만 판정"
    activation_required_all:
      - "LEADER_CONCENTRATION 판정 기준 전부 충족 (top2_rotation_sum>=100, top1_rotation_score>=55, leader_sector_flag==1, KOSPI_Ret20D>0)"
      - "top1_sector == 반도체 OR top2 섹터 중 반도체 포함"
      - "삼성전자 OR SK하이닉스 중 1개 이상: Price_Status=PRICE_OK AND Flow_OK=Y AND Flow_Rows>=20"
      - "VIX_Close < 22"
      - "KOSPI_Close > KOSPI_MA20"
      - "event_risk.Alert != HIGH"
    deactivation_any_one:
      - "KOSPI 종가 MA20 이탈"
      - "VIX_Close >= 25"
      - "외국인+기관 5D 동반 순매도 (foreign_5d_flow < 0 AND institution_5d_flow < 0)"
      - "반도체 sector_flow Rotation_Score 순위 3위 이하로 하락"
      - "event_risk.Alert == HIGH"
    portfolio_implication:
      - "staged_entry_v2 stage_1→2 전환 확인 기간 3~5거래일→2~3거래일 단축 허용"
      - "주도주 직접보유 우선. 동일 섹터 ETF 신규매수보다 삼성전자·SK하이닉스 직접보유 우선 검토"
      - "offensive_risk_budget_ladder 활성화 허용 (spec/05_position_sizing.yaml 참조)"
      - "dynamic_cash_floor_secular 적용 가능 — 즉시현금 하한 7% (spec/risk/portfolio_exposure.yaml 참조)"
      - "leader_quality_switch 발동 가능 — ETF→직접주 전환 가속 (spec/risk/portfolio_exposure.yaml 참조)"
      - "secular_leader_profit_lock 적용 — 주도주 이익 잠금 우선 (spec/exit/take_profit.yaml 참조)"
      - "단, Total_Heat/cash_floor/anti_climax_buy_gate/ATR20/보유수량 미확인 제약은 그대로 적용"
    priority_over_lower_states:
      - "EVENT_SHOCK 또는 RISK_OFF 발동 즉시 SECULAR_LEADER_RISK_ON 비활성화 — 이 두 상태가 항상 우선"
      - "SECULAR_LEADER_RISK_ON은 RISK_ON·LEADER_CONCENTRATION보다 강한 공격 허용 상태이며 RISK_OFF/EVENT_SHOCK보다는 항상 낮음"
    canonical_refs:
      - "spec/05_position_sizing.yaml:position_sizing.offensive_risk_budget_ladder"
      - "spec/risk/portfolio_exposure.yaml:portfolio_exposure_framework.cash_fc_bucket.dynamic_cash_floor_secular"
      - "spec/risk/portfolio_exposure.yaml:portfolio_exposure_framework.duplicate_exposure_rule.leader_quality_switch"
      - "spec/exit/take_profit.yaml:take_profit.secular_leader_profit_lock"
  CONCENTRATED_LEADER_ADVANCE:  # [proposal_CLA / 2026-05-21] 반도체 주도주 집중 강세 — 위성 설거지 방지
    code: CLA
    description: >
      반도체(삼성전자·SK하이닉스·KODEX반도체) 클러스터가 포트폴리오 50% 이상을 차지하고
      20일 수익률 +15% 이상이면서 위성 평균 수익률이 +5% 미만인 극단적 집중 랠리 국면.
      코어 매도 및 위성 신규 추가매수를 원천 차단해 '리더 팔고 설거지' 오판 방지.
    prerequisite: "LEADER_CONCENTRATION 또는 SECULAR_LEADER_RISK_ON 조건 일부 충족 상태에서 포트폴리오 레벨 조건 추가 충족"
    activation_required_all:
      - "cluster_20d_return >= 15% (삼성+하이닉스+KODEX반도체 합산 20일 수익률)"
      - "cluster_weight_pct >= 50% (클러스터 합산 포트폴리오 비중)"
      - "satellite_avg_20d_return < 5% (위성 평균 20일 수익률)"
      - "cluster_rs_slope_20d > 0 (클러스터 RS선 기울기 양수)"
    deactivation_any_one:
      - "cluster_weight_pct < 40%"
      - "cluster_20d_return < 5%"
      - "RISK_OFF 또는 EVENT_SHOCK 발동 — 이 두 상태가 항상 우선"
    portfolio_implication:
      - "REGIME_CLA-1: 코어(반도체 클러스터) allowed_action에서 SELL 제거 — F4 trailingStop 또는 SS001≤D등급 예외만 허용"
      - "REGIME_CLA-2: 위성 신규 BUY는 CLUSTER_HOLD_ONLY 상태로 전환 — RAG_V1 PASS 조건 추가 필요"
      - "REGIME_CLA-3: 현금확보 매도 시 rs_verdict=LAGGARD/BROKEN 위성 우선 — 코어 매도 금지"
      - "REGIME_CLA-4: cluster_state=CLUSTER_HOLD_ONLY를 calcApexExecutionHarness_ harness_context에 기록"
    cluster_gate_override:
      semiconductor_cap_rule: "O2(반도체 25% 상한)는 CLUSTER_OPEN 상태에서만 적용. CLA 발동 시 CLUSTER_HOLD_ONLY로 전환."
      new_buy_conditions:
        - "rag_v1: PASS"
        - "cluster_combined_pct < 60%"
    priority_over_lower_states:
      - "RISK_OFF / EVENT_SHOCK가 항상 CLA보다 우선"
      - "CLA는 SECULAR_LEADER_RISK_ON보다 포트폴리오 비중 기반 조건이 추가된 상태"
    canonical_refs:
      - "spec/risk/portfolio_exposure.yaml:cluster_states.CLUSTER_HOLD_ONLY"
      - "spec/13_formula_registry.yaml:REPLACEMENT_ALPHA_GATE_V1"
      - "spec/13_formula_registry.yaml:RS_VERDICT_V1"
      - "spec/13_formula_registry.yaml:SATELLITE_FAILURE_GATE_V1"

  NEUTRAL:
    condition_any:
      - "RISK_ON and RISK_OFF conditions both false"
      - "VIX_Close between 18 and 25"
      - "KOSPI near MA20 without decisive trend"
    portfolio_implication:
      - "돌파 단독 매수보다 눌림·확인 후 진입"
      - "B/C 후보 중심"
      - "현금 하한 유지"
    canonical_refs:
      - "spec/strategy/entry_core.yaml:entry_timing_guardrails.regime_based_entry.neutral"
  RISK_OFF:
    condition_any:
      - "VIX_Close > 25"
      - "KOSPI_Close < KOSPI_MA20 AND KOSPI_Close < KOSPI_MA60"
      - "foreign_20d_flow < 0 AND institution_20d_flow < 0"
      - "USD/KRW 급등 + US10Y shock"
    portfolio_implication:
      - "신규 위험자산 축소 또는 중단"
      - "현금 목표 상향"
      - "반등 확인 전 본진입 금지"
    canonical_refs:
      - "spec/risk/aggregate_risk.yaml:risk_control.aggregate_risk_cap"
      - "spec/risk/market_risk_cash.yaml:risk_control.market_risk_score_based_cash"
      - "spec/strategy/entry_core.yaml:entry_timing_guardrails.regime_based_entry.risk_off"
  EVENT_SHOCK:
    condition_any:
      - "event_risk.Alert == HIGH and DaysLeft <= 3"
      - "policy/geopolitical/credit shock confirmed by data source"
      - "sector_crash_intraday_protocol tier_B or higher"
    portfolio_implication:
      - "신규매수 보류 또는 수량 축소"
      - "cash_floor event week escalation 확인"
      - "보유주 손절/익절 조건 재검산"
    canonical_refs:
      - "spec/risk/portfolio_exposure.yaml:portfolio_exposure_framework.cash_floor.policy_event_week_escalation"
      - "spec/risk/circuit_breakers.yaml:risk_control.sector_crash_intraday_protocol"
  UNKNOWN:
    condition_any:
      - "required macro inputs missing"
      - "data conflict across primary sources"
      - "freshness mismatch across macro/sector/price data"
    portfolio_implication:
      - "A등급·즉시매수 금지"
      - "WATCH 또는 INSUFFICIENT_DATA"
      - "다음 확인 출처 출력"

  # [proposal_95 / 2026-05-16] 코스닥 보유 비중에 따른 MRS 보조 가중치
  kosdaq_regime_supplement:
    purpose: "코스닥 종목 합산 비중이 일정 수준 이상일 때 KOSDAQ_Close vs KOSDAQ_MA20를 MRS 보조 지표로 추가. 코스피 안정 중에도 코스닥만 이탈할 경우의 위험 보정."
    trigger_condition: "포트폴리오 내 코스닥 종목 합산 비중 >= 10%"
    supplemental_rule:
      if: "KOSDAQ_Close < KOSDAQ_MA20 AND KOSPI_Close >= KOSPI_MA20"
      then:
        - "MRS에 +1점 가산 (코스닥 특화 위험 보정)"
        - "target_cash_pct 1%p 추가 상향"
        - "보고서 MRS 항목에 [KOSDAQ_이탈_보정_+1] 표기"
      note: "KOSPI·KOSDAQ 동시 이탈 시 이 규칙은 중복 적용하지 않음 — 기존 KOSPI_vs_MA20 점수(+2)로 이미 반영됨"
    data_source:
      kosdaq_close: "macro 탭 KOSDAQ_Close 또는 KRX 공식 데이터"
      kosdaq_ma20:  "직접 계산(최근 20거래일 KOSDAQ_Close 단순평균) 또는 Naver Finance 확인"
      missing_policy: "KOSDAQ_MA20 미확인 시 이 보정 규칙 미발동 (0점 처리). 추정 금지."
    prohibition:
      - "KOSDAQ 보조 지표가 KOSPI 기반 시장국면(RISK_ON/RISK_OFF) 판정을 override하는 것 금지"
      - "KOSDAQ 이탈만으로 RISK_OFF 판정 금지 — MRS +1점 보조 가중치 역할만 허용"
      - "코스닥 합산 비중 10% 미만 시 이 규칙 적용 금지"

calculation_outputs:
  required_table_columns:
    - "지표"
    - "값"
    - "상태"
    - "국면기여"
    - "출처"
    - "기준시각"
  required_summary_fields:
    - "market_regime_state"
    - "confidence"
    - "blocked_actions"
    - "allowed_actions"
    - "next_check_time"
  confidence_rule:
    HIGH: "필수 입력 모두 OK, 출처 간 충돌 없음"
    MEDIUM: "필수 입력 1개 PARTIAL 또는 일부 지연"
    LOW: "필수 입력 2개 이상 PARTIAL/DATA_MISSING"

integration:
  decision_flow_state: "spec/09_decision_flow.yaml:decision_flow.states.MARKET_REGIME_CHECK"
  scoring_component: "spec/08_scoring_rules.yaml:strategy_score.components.macro_regime"
  output_schema_extension_note: "market_regime_state는 summary 또는 rules_used explanation에 포함한다. JSON schema 개정 시 top-level field로 승격 가능."
  prohibition:
    - "시장국면만으로 BUY 확정 금지"
    - "Risk-On이라도 hard_filters, portfolio_rules, position_sizing 미통과 시 주문 금지"
    - "Risk-Off에서 목표수익률 압박을 이유로 현금 규칙 완화 금지"
