QuantEngineByItz/spec/xref_matrix.yaml

meta:
  title: "은퇴자산포트폴리오 — 참조 허용 매트릭스"
  version: "2026-05-15-F10_fragmentation_guard"
  role: "governance"
  purpose: "파일 간 순환 참조와 책임 침범을 방지한다."

xref_matrix:
  "spec/08_scoring_rules.yaml":
    may_reference:
      - "spec/00_execution_contract.yaml"
      - "spec/12_field_dictionary.yaml"
      - "spec/13_formula_registry.yaml"
      - "spec/02_data_contract.yaml"
      - "spec/risk/aggregate_risk.yaml"
      - "spec/risk/market_risk_cash.yaml"
      - "spec/risk/portfolio_exposure.yaml"
      - "spec/strategy/sector_model.yaml"
      - "spec/07_output_schema.yaml"
    must_not_reference:
      - "examples/"
      - "prompts/"
  "spec/10_portfolio_rules.yaml":
    may_reference:
      - "spec/01_objective_profile.yaml"
      - "spec/12_field_dictionary.yaml"
      - "spec/13_formula_registry.yaml"
      - "spec/risk/portfolio_exposure.yaml"
      - "spec/risk/aggregate_risk.yaml"
      - "spec/risk/market_risk_cash.yaml"
    must_not_reference:
      - "schemas/output_schema.json"
  "spec/07_output_schema.yaml":
    may_reference:
      - "schemas/output_schema.json"
      - "RetirementAssetPortfolioReportTemplate.yaml"
      - "spec/00_execution_contract.yaml"
      - "spec/12_field_dictionary.yaml"
      - "spec/13_formula_registry.yaml"
    must_not_reference:
      - "examples/"
      - "prompts/"
  "schemas/output_schema.json":
    may_reference: []
    must_not_reference:
      - "spec/"
      - "examples/"
      - "prompts/"
  "examples/":
    may_reference:
      - "spec/"
      - "schemas/output_schema.json"
    must_not_reference: []
  "prompts/":
    may_reference:
      - "RetirementAssetPortfolio.yaml"
      - "spec/"
      - "schemas/output_schema.json"
    must_not_reference: []

  # ── 신규 계약 파일 xref ────────────────────────────────────────────────────
  "spec/53_factor_conflict_matrix.yaml":
    may_reference:
      - "spec/43_quant_factor_taxonomy.yaml"
      - "spec/00_execution_contract.yaml"
      - "spec/factor_lifecycle_registry.yaml"
    must_not_reference:
      - "examples/"
    conflict_resolution_note: >
      spec/53 conflict_precedence_rules rank 6 = market_regime (포지션 스케일 조정).
      spec/00 P3 = cash_floor·Total_Heat·hard_stop은 어떤 alpha/strategy 논리보다 우선.
      두 계약이 충돌하면 spec/00 P3가 우선한다 (spec/00 source_of_truth.priority=highest).
      spec/53의 rank 1(portfolio_risk_budget)이 사실상 spec/00 P3의 집행자이며,
      market_regime(rank 6)은 cash_floor를 완화하는 목적으로 사용될 수 없다.

  "spec/52_decision_trace_replay_contract.yaml":
    may_reference:
      - "spec/41_release_dag.yaml"
      - "spec/40_final_decision_packet_contract.yaml"
    must_not_reference:
      - "examples/"

  "spec/54_temporal_data_integrity.yaml":
    may_reference:
      - "spec/00_execution_contract.yaml"
      - "spec/exit/stop_loss.yaml"
    must_not_reference:
      - "examples/"
    temporal_note: >
      TIME_STOP 판단에 사용되는 hold_days는 반드시 entry_date 기준 실제 경과일 기반이어야 한다.
      미래 날짜 hold_days 사용은 LOOKAHEAD_BIAS로 분류된다.

  "spec/55_execution_simulator_contract.yaml":
    may_reference:
      - "spec/00_execution_contract.yaml"
      - "spec/13_formula_registry.yaml"
      - "spec/15_account_snapshot_contract.yaml"
    must_not_reference:
      - "examples/"

  "spec/56_renderer_copy_only_contract.yaml":
    may_reference:
      - "spec/00_execution_contract.yaml"
      - "spec/40_final_decision_packet_contract.yaml"
    must_not_reference:
      - "examples/"

  "spec/57_shadow_promotion_scorecard.yaml":
    may_reference:
      - "spec/44_live_replay_separation.yaml"
      - "spec/43_quant_factor_taxonomy.yaml"
    must_not_reference:
      - "examples/"

  "spec/58_llm_determinism_contract.yaml":
    may_reference:
      - "spec/46_low_capability_execution_pack.yaml"
      - "spec/00_execution_contract.yaml"
    must_not_reference:
      - "examples/"

# ── 충돌 해소 우선순위 선언 ────────────────────────────────────────────────
conflict_resolution_precedence:
  canonical_authority: "spec/00_execution_contract.yaml (source_of_truth.priority=highest)"
  rules:
    - id: "XREF_CR001"
      description: >
        spec/53 rank 6 market_regime vs spec/00 P3 cash_floor:
        spec/00 P3가 절대 우선한다. market_regime은 position_scale만 조정하며
        cash_floor·Total_Heat·hard_stop을 완화하는 목적으로 사용 금지.
      winner: "spec/00_execution_contract.yaml:P3_no_risk_block_override"
      loser: "spec/53_factor_conflict_matrix.yaml:rank=6_market_regime"

    - id: "XREF_CR002"
      description: >
        spec/54 temporal integrity vs spec/00 P4 intraday_lock:
        spec/00 P4가 상위 계약. spec/54는 backfill/lookahead를 차단하며,
        spec/00 P4는 장중 신규 매수·전량 매도를 차단한다. 두 계약은 서로 보완적.
      winner: "spec/00_execution_contract.yaml:P4_no_intraday_speculation"
      supplementary: "spec/54_temporal_data_integrity.yaml:NO_LOOKAHEAD"

policy:
  - "must_not_reference 위반은 검증 실패."
  - "may_reference 외 참조는 경고 대상. critical 파일은 실패 대상."
  - "schemas/output_schema.json은 어떤 spec도 참조하지 않는다."
  - "conflict_resolution_precedence는 spec 충돌 시 판단 순서를 명시한다. spec/00이 항상 최상위."