QuantEngineByItz/spec/26_behavioral_coverage_contract.yaml

behavioral_coverage_contract:
  behavioral_coverage_definition:
    denominator: 숫자·enum 출력을 가진 decision-critical 공식 수
    formula: behavioral_coverage_pct = (numerator / denominator) * 100
    numerator: ≥1개 golden case가 PASS인 decision-critical 공식 수
    pass_threshold: 100.0
  code_path: tools/validate_behavioral_coverage_v1.py
  completion_gate:
    behavioral_coverage_pct_min: 100.0
    golden_case_min_per_formula: 1
    implementation_divergence_count_max: 0
    provenance_allowed:
    - HAND_COMPUTED
    - SPEC_DERIVED
  decision_critical_formulas:
  - category: price
    gas_file: gas_lib.gs
    gas_function: tickNormalize_
    id: TICK_NORMALIZER_V1
    known_divergence: GAS=Math.floor, Python=round → 비정확 배수에서 결과 상이
    milestone: 1
    python_mirror: compute_formula_outputs.normalize_tick
    spec_intent: KRX HTS 입력용 floor-to-tick (GAS 동작이 spec 의도에 부합)
  - category: price
    gas_file: gas_data_feed.gs
    gas_function: calcSellPriceSanityV2_
    id: SELL_PRICE_SANITY_V1
    milestone: 1
    note: GAS V2 함수명 상이 — 로직 일치 여부 검증 필요
    python_mirror: compute_formula_outputs.check_sell_price_sanity
  - category: price
    gas_file: gas_data_feed.gs
    gas_function: null
    id: PULLBACK_ENTRY_TRIGGER_V1
    milestone: 1
    note: GAS에서 calcPullbackTrigger_ 독립 함수 미확인 — calcAntiLateEntryGateV2Impl_ 내부 로직으로
      통합
    python_mirror: compute_formula_outputs.compute_pullback_trigger
  - category: price
    gas_file: gas_data_feed.gs
    gas_function: null
    id: PROFIT_RATCHET_TIERED_V2
    milestone: 1
    note: GAS calcPrices_ 내부에 인라인 — 독립 함수 미확인
    python_mirror: compute_formula_outputs.compute_trailing_stop_v2
  - category: price
    gas_file: gas_data_feed.gs
    gas_function: null
    id: PROFIT_LOCK_STAGE_V1
    known_divergence: 'Python: APEX_SUPER(>=60),APEX_TRAILING(>=40),PROFIT_LOCK_30,PROFIT_LOCK_20,PROFIT_LOCK_10,BREAKEVEN_RATCHET,NORMAL

      GAS calcPrices_: PROFIT_LOCK_STAGE_50(>=50),PROFIT_LOCK_STAGE_30,PROFIT_LOCK_STAGE_20,PROFIT_LOCK_STAGE_10,NORMAL

      stage 명칭·임계값 모두 불일치 — B06 정정 필수

      '
    milestone: 1
    python_mirror: compute_formula_outputs.classify_profit_lock_stage
  - category: price
    gas_file: gas_data_feed.gs
    gas_function: calcStopAdequacyRows_
    id: STOP_PRICE_ADEQUACY_V1
    milestone: 1
    note: Python 미러 미구현 — run_formula_golden_cases_v2.py에 추가 필요
    python_mirror: null
  - category: sizing
    gas_file: gas_data_feed.gs
    gas_function: calcRegimeSizeScale_
    id: POSITION_SIZE_REGIME_SCALE_V1
    milestone: 1
    note: Python 미러 미구현 — run_formula_golden_cases_v2.py에 추가
    python_mirror: null
  - category: sizing
    gas_file: gas_data_feed.gs
    gas_function: calcDrawdownGuard_
    id: DRAWDOWN_GUARD_V1
    milestone: 1
    note: Python 미러 미구현 — run_formula_golden_cases_v2.py에 추가
    python_mirror: null
  - category: sizing
    gas_file: null
    gas_function: null
    id: CASH_RECOVERY_OPTIMIZER_V1
    milestone: 1
    note: Python-only formula. GAS 미러 없음(Python tool 전용).
    python_mirror: compute_formula_outputs.compute_cash_recovery_optimizer
  - category: sizing
    gas_function: null
    id: VALUE_PRESERVATION_SCORER_V1
    milestone: 1
    note: tools/build_value_preservation_scorer_v1.py 전용 — Python 미러 추출 필요
    python_mirror: null
  - category: sizing
    gas_file: gas_data_feed.gs
    gas_function: calcTpQuantityLadder_
    id: TP_QUANTITY_LADDER_V1
    milestone: 2
  - category: entry_gate
    gas_function: inline_calcAntiLateEntryGateV2Impl_
    id: VELOCITY_V1
    milestone: 1
    note: velocity_1d = (close-prevClose)/prevClose*100 — 양측 인라인 계산
    python_mirror: inline
  - category: entry_gate
    gas_file: gas_apex_alpha_watch.gs
    gas_function: calcAntiLateEntryGateV2Impl_
    id: ANTI_LATE_ENTRY_GATE_V2
    milestone: 1
    note: Python에서 gate1만 compute_anti_chasing으로 분리됨 — 전체 3-gate 검증은 GAS 위주
    python_mirror: null
  - category: entry_gate
    gas_function: null
    id: ANTI_CHASING_VELOCITY_V1
    milestone: 1
    note: ANTI_LATE_ENTRY_GATE_V2의 gate1 서브셋 — Python 독립 구현
    python_mirror: compute_formula_outputs.compute_anti_chasing
  - category: entry_gate
    gas_function: null
    id: FLOW_CREDIT_V1
    milestone: 2
    note: GAS 내부 인라인 — spec/13_formula_registry.yaml expression 존재
  - category: entry_gate
    gas_file: gas_data_feed.gs
    gas_function: calcBreakoutQualityGate_
    id: BREAKOUT_QUALITY_GATE_V2
    milestone: 2
  - category: entry_gate
    gas_file: gas_data_feed.gs
    gas_function: calcAntiWhipsawGate_
    id: ANTI_WHIPSAW_GATE_V1
    milestone: 2
  - category: entry_gate
    gas_file: gas_data_feed.gs
    gas_function: calcPositionCountLimit_
    id: POSITION_COUNT_LIMIT_V1
    milestone: 1
    note: Python 미러 미구현 — run_formula_golden_cases_v2.py에 추가
    python_mirror: null
  - category: entry_gate
    gas_file: gas_data_feed.gs
    gas_function: calcWinLossStreakGuard_
    id: WIN_LOSS_STREAK_GUARD_V1
    milestone: 2
  - category: distribution
    gas_file: gas_data_feed.gs
    gas_function: calcDistributionRiskRow_
    id: DISTRIBUTION_SELL_DETECTOR_V1
    milestone: 2
    note: 6+2 신호 가중합산. SIG_5(OBV기울기) GAS 구현 확인 필요
  - category: distribution
    gas_file: gas_data_feed.gs
    gas_function: calcDistributionRiskRow_
    id: PRE_DISTRIBUTION_EARLY_WARNING_V1
    milestone: 2
    note: calcDistributionRiskRow_ 내 pre_distribution_warning 필드로 출력
  - category: distribution
    gas_file: gas_data_feed.gs
    gas_function: calcSectorRotationMomentum_
    id: SECTOR_ROTATION_MOMENTUM_V1
    milestone: 2
  - category: cash_sell
    gas_file: gas_data_feed.gs
    gas_function: calcDynamicHeatThresholds_
    id: DYNAMIC_HEAT_GATE_V1
    milestone: 1
    note: Python 미러 미구현 — run_formula_golden_cases_v2.py에 추가
    python_mirror: null
  - category: cash_sell
    gas_file: gas_data_feed.gs
    gas_function: calcCashFloor_
    id: CASH_FLOOR_V1
    milestone: 1
    note: Python 미러 미구현 — run_formula_golden_cases_v2.py에 추가
    python_mirror: null
  - category: cash_sell
    gas_file: gas_data_feed.gs
    gas_function: calcCashShortfallHarness_
    id: CASH_SHORTFALL_V1
    milestone: 2
  - category: cash_sell
    gas_function: null
    id: K2_STAGED_REBOUND_SELL_V1
    milestone: 2
    note: spec/13b_harness_formulas.yaml에 정의. GAS calcApexTradePlan_ 내부
  - category: cash_sell
    id: SELL_WATERFALL_ENGINE_V2
    milestone: 2
    note: tools/build_sell_waterfall_engine_v2.py 전용
    python_mirror: null
  - category: cash_sell
    gas_file: gas_data_feed.gs
    gas_function: calcRegimeTrimGuidance_
    id: REGIME_TRIM_GUIDANCE_V1
    milestone: 2
  - category: portfolio_gate
    gas_file: gas_data_feed.gs
    gas_function: calcRegimeCashUplift_
    id: REGIME_CASH_UPLIFT_V1
    milestone: 1
    note: Python 미러 미구현 — run_formula_golden_cases_v2.py에 추가
    python_mirror: null
  - category: portfolio_gate
    gas_file: gas_data_feed.gs
    gas_function: calcSemiconductorClusterGate_
    id: SEMICONDUCTOR_CLUSTER_GATE_V1
    milestone: 1
    note: Python 미러 미구현
    python_mirror: null
  - category: portfolio_gate
    gas_file: gas_data_feed.gs
    gas_function: calcSinglePositionWeightCap_
    id: SINGLE_POSITION_WEIGHT_CAP_V1
    milestone: 2
  - category: portfolio_gate
    gas_file: gas_data_feed.gs
    gas_function: calcPortfolioBetaGate_
    id: PORTFOLIO_BETA_GATE_V1
    milestone: 2
  - category: portfolio_gate
    gas_file: gas_data_feed.gs
    gas_function: calcSectorConcentrationGate_
    id: SECTOR_CONCENTRATION_LIMIT_V1
    milestone: 2
  - category: portfolio_gate
    gas_file: gas_data_feed.gs
    gas_function: calcPortfolioDrawdownGate_
    id: PORTFOLIO_DRAWDOWN_GATE_V1
    milestone: 2
  - category: portfolio_gate
    id: FINAL_JUDGMENT_GATE_V1
    milestone: 2
    note: tools/build_final_judgment_gate_v1.py 전용 — AND-11 복합 게이트
    python_mirror: null
  - category: portfolio_gate
    gas_file: gas_data_feed.gs
    gas_function: calcStopBreachAlert_
    id: STOP_BREACH_ALERT_V1
    milestone: 2
  - category: portfolio_gate
    gas_file: gas_data_feed.gs
    gas_function: calcTpTriggerAlert_
    id: TP_TRIGGER_ALERT_V1
    milestone: 2
  - category: portfolio_gate
    gas_file: gas_data_feed.gs
    gas_function: calcHeatConcentrationAlert_
    id: HEAT_CONCENTRATION_ALERT_V1
    milestone: 2
  - category: portfolio_gate
    gas_file: gas_data_feed.gs
    gas_function: calcPortfolioHealthScore_
    id: PORTFOLIO_HEALTH_SCORE_V1
    milestone: 2
  - category: portfolio_gate
    gas_file: gas_data_feed.gs
    gas_function: calcProfitPreservationRow_
    id: BREAKEVEN_RATCHET_V1
    milestone: 2
  evidence_artifacts:
  - Temp/formula_behavioral_coverage_v1.json
  - Temp/formula_gas_parity_v1.json
  formula_id: BEHAVIORAL_COVERAGE_CONTRACT_V1
  has_code_implementation: true
  milestone_1_count: 37
  milestone_1_target_formulas:
  - TICK_NORMALIZER_V1
  - SELL_PRICE_SANITY_V1
  - PULLBACK_ENTRY_TRIGGER_V1
  - PROFIT_RATCHET_TIERED_V2
  - PROFIT_LOCK_STAGE_V1
  - STOP_PRICE_ADEQUACY_V1
  - POSITION_SIZE_REGIME_SCALE_V1
  - DRAWDOWN_GUARD_V1
  - CASH_RECOVERY_OPTIMIZER_V1
  - VALUE_PRESERVATION_SCORER_V1
  - VELOCITY_V1
  - ANTI_LATE_ENTRY_GATE_V2
  - ANTI_CHASING_VELOCITY_V1
  - POSITION_COUNT_LIMIT_V1
  - DYNAMIC_HEAT_GATE_V1
  - CASH_FLOOR_V1
  - REGIME_CASH_UPLIFT_V1
  - SEMICONDUCTOR_CLUSTER_GATE_V1
  - WIN_LOSS_STREAK_GUARD_V1
  - SINGLE_POSITION_WEIGHT_CAP_V1
  - REGIME_TRIM_GUIDANCE_V1
  - HEAT_CONCENTRATION_ALERT_V1
  - SECTOR_CONCENTRATION_LIMIT_V1
  - CASH_SHORTFALL_V1
  - K2_STAGED_REBOUND_SELL_V1
  - PORTFOLIO_DRAWDOWN_GATE_V1
  - PROFIT_LOCK_STAGE_V1
  - MARKET_WEIGHT_AWARE_CLUSTER_GATE_V1
  - LEADER_POSITION_WEIGHT_CAP_V1
  objective: '"formula_id 문자열이 .gs 텍스트에 등장한다" 는 문자열 커버리지(presence-based)를 폐기하고

    "주어진 입력에 대해 golden(손계산 정답) == Python미러 == GAS미러 가 허용오차 내 일치한다"

    는 행위기반 커버리지(behavioral coverage)로 전환한다.

    구조적 거짓(결함 1)을 제거하기 위한 근본 측정 기반.

    '
  ordered_commands:
  - command: '# 이 파일 생성 완료'
    expect:
      file_exists: spec/26_behavioral_coverage_contract.yaml
    id: B01
  - command: '# spec/formula_golden_cases_v2.yaml 작성'
    expect:
      cases_total_min: 18
      provenance: HAND_COMPUTED or SPEC_DERIVED only
    id: B02
  - command: python tools/run_formula_golden_cases_v2.py
    expect:
      output: Temp/formula_behavioral_coverage_v1.json
      python_fail: 0
    fail_code: BCH_PY_MIRROR_FAIL
    id: B03
  - command: node tools/run_gas_golden_parity.js
    expect:
      gas_pass_min: 1
      output: Temp/formula_gas_parity_v1.json
    fail_code: BCH_GAS_PARITY_FAIL
    id: B04
  - command: python tools/validate_behavioral_coverage_v1.py
    expect:
      behavioral_coverage_pct: 100.0
      implementation_divergence_count: 0
      status_token: BEHAVIORAL_COVERAGE_V1_OK
    fail_code: BEHAVIORAL_COVERAGE_V1_FAIL
    id: B05
  - command: '# divergence 발견 시 spec/13 기준으로 GAS 또는 Python 수정'
    expect:
      divergence_count: 0
    fail_code: BCH_DIVERGENCE_OPEN
    id: B06
  - command: npm run validate-behavioral-coverage
    expect:
      exit_code: 0
    fail_code: BCH_WIRING_FAIL
    id: B07
  reject_conditions:
  - implementation_divergence_count > 0 인데 '완료' 선언
  - golden expected 값을 .gs 출력에서 역복사 (순환논리 — spec/13 expression에서 독립 계산해야 함)
  - 예측 정확도를 '100% 달성'으로 서술 (truthfulness_guard 위반)
  - 임계값·가격·수량을 LLM 추정으로 생성
  three_way_gate:
    divergence_definition: 'python_output ≠ gas_output (허용오차 초과) 이면 IMPLEMENTATION_DIVERGENCE.

      이는 "yaml 지침과 구현이 다른 숫자를 낸다"는 직접 증거이며 B06에서 근본 정정 필요.

      '
    divergence_resolution: 'spec/13_formula_registry.yaml 의 expression이 기준.

      GAS 또는 Python 중 spec에서 벗어난 쪽을 수정한다.

      LLM 추정으로 수정 금지. spec expression 기계적 적용.

      '
    gas_vs_golden_tolerance: 동일
    python_vs_golden_tolerance: 각 공식 케이스 yaml의 tolerance 필드 기준
  version: '2026-05-30'
meta:
  has_code_implementation: false