meta:
  title: 은퇴자산포트폴리오 — 참조 허용 매트릭스
  version: 2026-05-15-F10_fragmentation_guard
  role: governance
  purpose: 파일 간 순환 참조와 책임 침범을 방지한다.
  has_code_implementation: true
  code_path:
  - spec\xref_matrix.yaml
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: []
  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이 항상 최상위.
