QuantEngineByItz/suggest/archive/quant_engine_refactor_methodology_todo_v1.yaml

meta:
  title: Quant Engine Deterministic Architecture Refactor Methodology TODO
  version: 2026-06-06.v1
  language: ko-KR
  author_role:
  - 30y_quant_investor
  - senior_developer
  - systems_architect
  - senior_pm
  input_basis:
    archive: data_feed.zip
    primary_instruction: data_feed/AGENTS.md
    source_file_scope:
    - '*.md'
    - '*.yaml'
    - '*.gs'
    - '*.py'
    runtime_artifact_scope:
    - '*.json'
    - '*.jsonl'
    - dist/*.yaml
    inspected_inventory:
      md_files: 16
      yaml_files: 104
      gs_files: 7
      py_files: 376
      json_artifacts: 511
      large_files_observed:
        AGENTS.md: 119KB / 1067 lines
        spec/13_formula_registry.yaml: 176KB / 4638 lines
        gas_data_feed.gs: 459KB / 10271 lines
        gas_data_collect.gs: 215KB / 4429 lines
        tools/validate_engine_harness_gate.py: 91KB / 1841 lines
        Temp/operational_report.json: 202KB / 550 lines
  non_investment_note: 이 문서는 투자 매수/매도 지시가 아니라 퀀트투자 엔진 개발·검증·운영 방법론 리팩토링 지침이다.
executive_decision:
  adopt_methodology_name: 'QEDA-DM: Quant Engine Deterministic Architecture Development Methodology'
  one_sentence: LLM 판단을 제거하고, 수치·공식·데이터·권위 소스·검증 게이트를 코드와 계약으로 고정한 뒤 LLM은 검증된 패킷을 렌더링만 하게 만드는 개발 방법론.
  core_thesis:
  - 현재 엔진의 병목은 알파 아이디어 부족이 아니라 권위 소스 충돌, 산출 공식 중복, 임시 산출물 난립, 대형 GAS/검증 스크립트의 응집도 붕괴다.
  - 최고 성능 LLM과 저성능 LLM의 결과 차이를 줄이는 유일한 방법은 LLM의 자유도를 줄이고 deterministic packet, schema, golden case, formula registry, renderer
    contract로 결과 공간을 닫는 것이다.
  - AGENTS.md는 운영 헌법/인덱스로 축소하고, 공식·필드·게이트·출력·실행은 yaml 계약과 py/gs 구현의 parity test로 강제한다.
  target_state:
    llm_freedom_pct: 0.0
    runtime_adjusted_formula_coverage_pct: 100.0
    unmapped_formula_count: 0
    ungrounded_number_count: 0
    authority_collision_count: 0
    golden_case_decision_critical_coverage_pct: 100.0
    gas_python_formula_parity_fail_count: 0
    operational_report_schema_valid: true
    human_override_transparency_required: true
problem_diagnosis:
  P01_authority_sprawl:
    symptom: AGENTS.md, spec yaml, Temp json, GAS, Python validators가 모두 판단 근거처럼 사용될 위험.
    risk: 동일 필드/공식/게이트가 여러 파일에서 다른 의미로 해석되면 매수·매도 판단이 뒷북/설거지로 변질된다.
    required_fix: authority matrix와 active_manifest만 읽게 하고, 나머지는 build input 또는 audit output으로 격리한다.
  P02_version_fragmentation:
    symptom: Temp에 v1~v8 계열 산출물이 다수 존재한다.
    risk: 저성능 LLM 또는 스크립트가 최신이 아닌 산출물을 읽어 잘못된 수량·가격·게이트를 렌더링할 수 있다.
    required_fix: 'canonical_artifact_resolver와 artifact_status: active|superseded|archived|forbidden_read를 강제한다.'
  P03_document_bloat:
    symptom: AGENTS.md 1000라인+, formula_registry 4600라인+, gas_data_feed 10000라인+.
    risk: 사람과 LLM 모두 전체 규칙을 일관되게 적용하기 어렵고, 리팩토링 단위가 커져 회귀버그가 늘어난다.
    required_fix: 도메인별 모듈화, ADR, rule lifecycle, owner ledger, max file size gate를 도입한다.
  P04_hallucination_surface:
    symptom: LLM이 문서와 산출물 사이에서 누락 숫자를 보완하려는 유혹이 생긴다.
    risk: 임의 가격, 임의 TP/SL, 임의 수량 산출이 발생한다.
    required_fix: number_provenance_self_audit, output_field_owner_ledger, renderer-only LLM contract를 강화한다.
  P05_methodology_gap:
    symptom: 기능 추가 TODO는 많지만 제품형 엔진의 architecture governance, release train, observability, lineage, calibration loop가 하나의
      방법론으로 닫혀 있지 않다.
    risk: 개선은 계속되나 방향성이 누적되지 않고, 성과 검증보다 문서 추가가 선행된다.
    required_fix: QEDA-DM 9단계 lifecycle을 표준 개발 프로세스로 채택한다.
methodology:
  name: QEDA-DM
  principles:
  - id: PR01
    name: Contract first
    rule: 새 기능은 구현보다 먼저 YAML contract, JSON schema, golden cases, output owner를 등록한다.
  - id: PR02
    name: Deterministic core
    rule: 가격·수량·점수·게이트는 Python/GAS 공식으로만 산출하고 LLM 산출을 금지한다.
  - id: PR03
    name: LLM renderer only
    rule: LLM은 final_decision_packet을 해석·표시만 하며 숫자를 생성하거나 수정하지 않는다.
  - id: PR04
    name: One active artifact
    rule: 동일 목적 산출물은 active_manifest가 지정한 1개만 runtime source로 허용한다.
  - id: PR05
    name: Evidence before recommendation
    rule: 투자 제안은 formula_id, input_fields, timestamp, source_artifact, confidence를 가진 evidence ledger 없이는 출력하지 않는다.
  - id: PR06
    name: No false 100%
    rule: 100% 완료는 gate result, failed_checks=0, sample maturity 충족, parity pass가 있을 때만 선언한다.
  - id: PR07
    name: Separate policy and implementation
    rule: AGENTS/MD는 정책·해설, YAML은 계약, PY는 canonical engine, GS는 sheet adapter, JSON은 runtime artifact로 제한한다.
  - id: PR08
    name: Small files, strong interfaces
    rule: 대형 파일은 도메인 모듈로 쪼개고 public function/import boundary를 고정한다.
  - id: PR09
    name: Replayability
    rule: 모든 판단은 동일 input snapshot으로 재실행 시 동일 output hash가 나와야 한다.
  - id: PR10
    name: Outcome-calibrated evolution
    rule: 룰 추가는 실제 outcome ledger와 calibration registry의 개선 근거가 있어야 승격한다.
  lifecycle:
  - stage: S0_intake
    owner: PM/quant
    output: proposal_ticket.yaml
    exit_gate: business_hypothesis, risk, affected_fields 명시
  - stage: S1_contract
    owner: architect
    output: spec/contracts/*.yaml + schemas/*.json
    exit_gate: field owner, formula owner, artifact owner 등록
  - stage: S2_formula
    owner: quant
    output: spec/formulas/*.yaml + golden_cases.yaml
    exit_gate: manual expected result and edge cases complete
  - stage: S3_canonical_python
    owner: developer
    output: src/quant_engine/**/*.py
    exit_gate: pytest golden pass
  - stage: S4_gas_adapter
    owner: GAS maintainer
    output: gas/**/*.gs
    exit_gate: GAS-Python parity pass
  - stage: S5_pipeline
    owner: platform
    output: Temp/*.json via build commands
    exit_gate: schema validation and lineage event recorded
  - stage: S6_render
    owner: LLM/reporting
    output: operational_report.md/json
    exit_gate: no ungrounded number, narrative lock pass
  - stage: S7_release
    owner: release manager
    output: dist + zip
    exit_gate: full-gate status OK and failed_checks_count=0
  - stage: S8_feedback
    owner: quant/PM
    output: outcome_ledger + calibration backlog
    exit_gate: sample maturity and real outcome attribution complete
authority_model:
  read_order_highest_to_lowest:
  - rank: 1
    source: active_artifact_manifest.yaml
    authority: runtime에서 읽을 산출물 1개를 지정하는 최상위 resolver
  - rank: 2
    source: final_decision_packet.json
    authority: 렌더링 가능한 최종 숫자·수량·게이트 패킷
  - rank: 3
    source: spec/formulas/*.yaml
    authority: 공식 정의와 formula_id의 단일 원장
  - rank: 4
    source: spec/field_dictionary.yaml
    authority: 필드명·단위·nullable·owner 정의
  - rank: 5
    source: schemas/*.schema.json
    authority: artifact shape validation
  - rank: 6
    source: AGENTS.md
    authority: 운영 금지사항·보고서 인덱스·사람용 헌법
  - rank: 7
    source: README.md/prompts/*.md
    authority: 사용법·렌더링 프롬프트. 숫자 권위 없음
  - rank: 8
    source: Temp/superseded/*
    authority: 감사·재현용. runtime read 금지
  file_type_contract:
    .md: 정책, 설명, 프롬프트, ADR 요약만 허용. 숫자 산출 공식의 원본 권위 금지.
    .yaml: spec, formula, data contract, TODO, lifecycle, owner ledger의 원본 권위.
    .py: canonical deterministic implementation, validator, test runner, migration script.
    .gs: Google Sheets/App Script adapter. canonical 계산을 복제할 때는 반드시 parity test 필요.
    .json: runtime artifact. 사람이 직접 편집하지 않는다.
  conflict_resolution:
  - 동일 필드 정의가 두 곳 이상이면 output_field_owner_ledger.yaml의 owner가 우선한다.
  - AGENTS.md와 spec yaml이 충돌하면 spec yaml을 우선하고 AGENTS.md를 인덱스로 정정한다.
  - GAS와 Python 결과가 다르면 release 차단. Python canonical이 우선이며 GAS adapter를 수정한다.
  - 외부 시장 데이터와 harness 가격이 다르면 harness 가격을 주문 판단에 사용하고 외부 데이터는 CONTEXT_ONLY로 격리한다.
  - Temp에 복수 버전이 있으면 active_manifest가 active로 지정한 파일만 사용한다.
target_repository_architecture:
  proposed_tree:
    governance/:
    - AGENTS.md 축소본
    - adr/*.md
    - rule_lifecycle.yaml
    - authority_matrix.yaml
    spec/:
    - contracts/*.yaml
    - formulas/*.yaml
    - fields/*.yaml
    - outputs/*.yaml
    - risk/*.yaml
    - strategy/*.yaml
    schemas/:
    - '*.schema.json'
    - generated/
    src/quant_engine/:
    - data/
    - features/
    - formulas/
    - gates/
    - routing/
    - sizing/
    - execution/
    - portfolio/
    - reporting/
    - observability/
    gas/:
    - adapters/
    - sheets/
    - render_bridge/
    - legacy/
    tools/:
    - build_*.py
    - validate_*.py
    - migrate_*.py
    - audit_*.py
    tests/:
    - golden/
    - parity/
    - regression/
    - property/
    - integration/
    runtime/:
    - active_artifact_manifest.yaml
    - lineage_events.jsonl
    - run_profiles/
    Temp/:
    - generated artifacts only; no manual edit; no direct LLM read except manifest-approved artifacts
    dist/:
    - packaged compact yaml bundles
  max_file_size_policy:
    AGENTS.md:
      max_lines: 350
      action_if_exceeded: move detailed rules into spec/governance/*.yaml and keep index links
    single_formula_yaml:
      max_lines: 800
      action_if_exceeded: 'split by domain: risk, entry, exit, cash, portfolio, report'
    single_gs_file:
      max_lines: 1500
      action_if_exceeded: move functions to gas/adapters/domain_*.gs
    single_py_file:
      max_lines: 800
      action_if_exceeded: split into package modules and shared validation utilities
    prompt_md:
      max_lines: 250
      action_if_exceeded: convert output constraints to machine-readable render_contract.yaml
canonical_engine_layers:
  L0_data_ingest:
    responsibility: 수집, 정규화, source timestamp, freshness, unit validation
    must_not: 투자 판단 산출 금지
    artifacts:
    - raw_snapshot
    - normalized_snapshot
    - data_quality_report
  L1_feature_store:
    responsibility: 가격/거래대금/펀더멘털/스마트머니/섹터/거시/계좌 피처 생성
    must_not: 매수/매도 verdict 생성 금지
    artifacts:
    - feature_matrix
    - feature_lineage
  L2_formula_engine:
    responsibility: formula_registry 기반 deterministic score/threshold 산출
    must_not: 렌더링 문장 생성 금지
    artifacts:
    - formula_outputs
    - formula_trace
  L3_gate_engine:
    responsibility: cash, heat, risk, data maturity, anti-chase, stop/tp, sector, beta, portfolio health gate 판정
    must_not: 게이트 실패를 문장으로 완화 금지
    artifacts:
    - gate_results
    - blocked_reason_ledger
  L4_router:
    responsibility: 단타/단기/중기/장기, BUY/HOLD/TRIM/SELL/WATCH/BLOCKED 라우팅
    must_not: 수량/가격 재산출 금지
    artifacts:
    - routing_trace
    - decision_path
  L5_position_execution:
    responsibility: position sizing, tranche, sell priority, HTS order blueprint, shadow ledger 산출
    must_not: HTS 단일 조건 위반, tick 미정규화 가격 출력 금지
    artifacts:
    - order_blueprint
    - shadow_ledger
  L6_report_renderer:
    responsibility: final_decision_packet을 사람이 읽는 보고서로 렌더링
    must_not: 새 숫자 생성, 누락 필드 보완, softening narrative 생성 금지
    artifacts:
    - operational_report.json
    - operational_report.md
  L7_outcome_feedback:
    responsibility: 실행/미실행 결과, slippage, late chase, value damage, hit ratio, alpha decay 추적
    must_not: 표본 미성숙 상태에서 PASS 또는 100% 주장 금지
    artifacts:
    - outcome_ledger
    - calibration_registry_update_queue
numeric_governance_formulas:
  data_integrity_score:
    formula: 100 * (1 - weighted_error_count / weighted_required_check_count)
    hard_floor_for_release: 100.0
    error_classes:
    - missing_required_field
    - stale_timestamp
    - unit_mismatch
    - source_conflict
    - schema_invalid
  authority_collision_score:
    formula: 100 * (1 - collision_count / max(1, owned_field_count))
    release_condition: collision_count == 0
  hallucination_risk_score:
    formula: 100 * (ungrounded_number_count + unsupported_claim_count + llm_modified_field_count) / max(1, output_number_count
      + output_claim_count)
    release_condition: score == 0 and ungrounded_number_count == 0
  determinism_score:
    formula: 100 * deterministic_hash_match_count / replay_case_count
    release_condition: score == 100 and replay_case_count >= minimum_replay_cases
  formula_parity_score:
    formula: 100 * (1 - abs(py_result - gas_result) / tolerance_denominator) averaged across golden cases
    release_condition: all cases pass exact or tolerance-specific checks
  sample_maturity_score:
    formula: min(100, 100 * effective_sample_n / required_sample_n)
    rule: effective_sample_n < required_sample_n이면 PASS 금지, WATCH_PENDING_SAMPLE로 강등
  engine_maturity_score:
    formula: 0.20*data_integrity + 0.20*formula_coverage + 0.15*parity + 0.15*determinism + 0.15*outcome_maturity + 0.10*lineage
      + 0.05*docs_hygiene
    interpretation:
      '90_100': release_ready
      '75_89': limited_release
      '60_74': shadow_only
      below_60: development_only
todo_backlog:
- phase: P0_freeze_and_inventory
  id: P0_T01_ACTIVE_MANIFEST
  priority: P0
  title: 런타임 권위 산출물 active manifest 단일화
  owner: architect/platform
  rationale: Temp 산출물이 500개 이상이며 버전이 다수 존재하므로 runtime에서 읽을 파일을 1개씩 잠그지 않으면 구버전 오독 가능성이 크다.
  target_files:
  - runtime/active_artifact_manifest.yaml
  - tools/validate_active_manifest.py
  - Temp/active_artifact_manifest_v*.json
  implementation_steps:
  - runtime/active_artifact_manifest.yaml 생성
  - artifact_key별 active_path, schema_path, freshness_sla_min, status, produced_by, consumed_by를 명시
  - Temp의 구버전 artifact는 superseded로 태깅
  - LLM/report renderer는 manifest active_path 외 직접 Temp 읽기 금지
  commands:
  - python tools/validate_active_manifest.py --manifest runtime/active_artifact_manifest.yaml --strict
  acceptance_criteria:
  - 모든 artifact_key가 active_path exactly 1개 보유
  - status in [active,superseded,archived,forbidden_read]
  - forbidden_read artifact를 참조하는 코드/프롬프트 0건
  low_capability_llm_instruction: Temp 폴더에서 최신처럼 보이는 파일을 직접 고르지 말고 manifest에 등록된 active_path만 사용하라.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P0_freeze_and_inventory
  id: P0_T02_AUTHORITY_MATRIX
  priority: P0
  title: 필드·공식·출력 owner authority matrix 작성
  owner: architect/quant
  rationale: 필드 정의/공식/렌더링 책임이 분산되면 동일 숫자가 다른 곳에서 재정의된다.
  target_files:
  - governance/authority_matrix.yaml
  - spec/03_formulas/output_field_owner_ledger.yaml
  - spec/12_field_dictionary.yaml
  implementation_steps:
  - 모든 output field에 owner_type(formula|data|renderer|manual), owner_file, owner_formula_id를 매핑
  - 중복 owner를 collision으로 기록
  - AGENTS.md에 있는 숫자 규칙은 matrix에 링크만 남김
  commands:
  - python tools/build_authority_matrix.py --spec spec --out governance/authority_matrix.yaml
  - python tools/validate_authority_matrix.py --strict
  acceptance_criteria:
  - owned_output_field_pct == 100
  - authority_collision_count == 0
  - manual_override_field는 override_reason과 audit_required=true 보유
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P0_freeze_and_inventory
  id: P0_T03_BASELINE_METRICS
  priority: P0
  title: 현재 엔진 구조 부채 baseline metrics 고정
  owner: platform
  rationale: 개선 전 기준선을 수치화하지 않으면 리팩토링 성과를 증빙할 수 없다.
  target_files:
  - Temp/refactor_baseline_metrics_v1.json
  - tools/build_refactor_baseline_metrics.py
  implementation_steps:
  - 파일 타입별 수량, 대형 파일 수, duplicate formula_id, duplicate artifact_key, deprecated read reference, test coverage를 측정
  - 결과를 refactor_baseline_metrics_v1.json으로 저장
  - 향후 PR마다 delta를 비교
  commands:
  - python tools/build_refactor_baseline_metrics.py --root . --out Temp/refactor_baseline_metrics_v1.json
  acceptance_criteria:
  - baseline json schema valid
  - large_file_count, duplicate_formula_count, authority_collision_count 필드 존재
  - 다음 release에서 개선/악화 delta 출력
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P1_document_refactor
  id: P1_T01_AGENTS_SHRINK
  priority: P0
  title: AGENTS.md를 헌법/인덱스로 축소
  owner: architect/PM
  rationale: 1000라인 이상의 AGENTS.md는 저성능 LLM이 일관되게 적용하기 어렵고, rule source와 commentary가 섞인다.
  target_files:
  - AGENTS.md
  - governance/agents_index.yaml
  - governance/rules/*.yaml
  implementation_steps:
  - AGENTS.md를 300~350라인 이하로 축소
  - 상위 금지사항, source-of-truth, required decision flow, output standard만 유지
  - 세부 Direction은 governance/rules/*.yaml로 이동하고 ID별 링크 유지
  - 이동 전후 rule_id hash 비교
  commands:
  - python tools/split_agents_rules.py --in AGENTS.md --out governance/rules --index governance/agents_index.yaml
  - python tools/validate_agents_index.py --strict
  acceptance_criteria:
  - AGENTS.md lines <= 350
  - rule_id_count_before == rule_id_count_after
  - missing_rule_id_count == 0
  - AGENTS.md에 산출 공식 원문 없음
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P1_document_refactor
  id: P1_T02_ADR_SYSTEM
  priority: P0
  title: ADR 기반 의사결정 기록 체계 도입
  owner: PM/architect
  rationale: 리팩토링/룰 변경의 이유와 부작용을 기록하지 않으면 같은 논쟁과 같은 패치가 반복된다.
  target_files:
  - governance/adr/0001-adopt-qeda-dm.md
  - governance/adr_index.yaml
  implementation_steps:
  - 'ADR 템플릿 생성: context, decision, alternatives, consequences, rollback, affected_files'
  - 주요 결정 10개를 ADR로 등록
  - 새 formula/gate 도입 PR에는 ADR 또는 rule lifecycle ticket 필수
  commands:
  - python tools/validate_adr_index.py --index governance/adr_index.yaml
  acceptance_criteria:
  - adr_index.yaml에 모든 ADR 등록
  - 각 ADR status in [proposed,accepted,superseded,deprecated]
  - accepted ADR의 consequences와 rollback 존재
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P1_document_refactor
  id: P1_T03_RULE_LIFECYCLE
  priority: P0
  title: 룰 생명주기 정책 등록
  owner: quant/architect
  rationale: 새 룰이 계속 누적되면 엔진은 고도화가 아니라 규칙 부채가 된다.
  target_files:
  - governance/rule_lifecycle.yaml
  - tools/validate_rule_lifecycle.py
  implementation_steps:
  - rule status를 proposed->shadow->active->deprecated->removed로 정의
  - 'active 승격 조건: golden case, parity, outcome hypothesis, kill switch'
  - deprecated 룰은 active router에서 참조 금지
  commands:
  - python tools/validate_rule_lifecycle.py --strict
  acceptance_criteria:
  - active rule은 owner, formula_id, schema, tests, rollback 모두 존재
  - deprecated active reference count == 0
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P2_formula_contract
  id: P2_T01_FORMULA_DOMAIN_SPLIT
  priority: P0
  title: formula registry를 도메인별로 분할하고 normalized registry를 빌드 산출물로 전환
  owner: quant/developer
  rationale: 단일 4600라인 formula registry는 충돌 탐지와 리뷰가 어렵다.
  target_files:
  - spec/formulas/risk.yaml
  - spec/formulas/entry.yaml
  - spec/formulas/exit.yaml
  - spec/formulas/cash.yaml
  - spec/formulas/portfolio.yaml
  - spec/formulas/reporting.yaml
  - spec/03_formulas/formula_registry.normalized.yaml
  implementation_steps:
  - 기존 spec/13_formula_registry.yaml을 domain별 yaml로 분할
  - 각 formula에 formula_id, version, inputs, outputs, units, null_policy, tick_policy, precision, owner, golden_cases를 명시
  - normalized registry는 빌드 산출물로만 생성
  commands:
  - python tools/split_formula_registry.py --in spec/13_formula_registry.yaml --out spec/formulas
  - python tools/build_formula_registry_normalized.py --in spec/formulas --out spec/03_formulas/formula_registry.normalized.yaml
  - python tools/validate_formula_registry.py --strict
  acceptance_criteria:
  - formula_id unique
  - all input fields exist in field_dictionary
  - all outputs have owner ledger entry
  - normalized registry deterministic hash stable
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P2_formula_contract
  id: P2_T02_GOLDEN_CASE_EXPANSION
  priority: P0
  title: 의사결정 핵심 공식 golden case 100% 확대
  owner: quant/QA
  rationale: 저성능 LLM에게 자세히 지시해도 공식 검증이 없으면 잘못된 계산을 감지할 수 없다.
  target_files:
  - tests/golden/formula_golden_cases.yaml
  - tools/run_golden_cases_py.py
  - tools/run_gas_golden_parity.js
  implementation_steps:
  - 모든 decision critical formula에 normal/edge/missing/stale/extreme case 작성
  - 손계산 expected_result와 provenance를 기록
  - Python canonical과 GAS adapter를 같은 case로 검증
  commands:
  - python tools/run_golden_cases_py.py --cases tests/golden/formula_golden_cases.yaml
  - node tools/run_gas_golden_parity.js --cases tests/golden/formula_golden_cases.yaml
  acceptance_criteria:
  - decision_critical_formula_coverage_pct == 100
  - python_fail_count == 0
  - gas_parity_fail_count == 0
  - expected_result 없는 case 0건
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P2_formula_contract
  id: P2_T03_THRESHOLD_CALIBRATION_LEDGER
  priority: P0
  title: 임계값 보정 레지스트리와 outcome 근거 연결
  owner: quant
  rationale: 임계값이 많아질수록 주관적 튜닝이 성과로 오인될 위험이 커진다.
  target_files:
  - spec/calibration/calibration_registry.yaml
  - Temp/calibration_change_ledger_v*.json
  - Temp/outcome_ledger_v1.json
  implementation_steps:
  - 각 threshold에 source_type(backtest|live_outcome|expert_default), sample_n, valid_from, review_after, expected_effect를 등록
  - sample_n 부족 시 expert_default로 표시하고 PASS 증빙에 사용 금지
  - 변경마다 before/after 예상효과와 실제효과 추적
  commands:
  - python tools/validate_calibration_registry_v1.py --strict
  - python tools/build_calibration_priority_v1.py
  acceptance_criteria:
  - unregistered_threshold_count == 0
  - overclaimed_calibration_count == 0
  - sample_n < 30 threshold는 active 승격 금지 또는 WATCH_PENDING_SAMPLE
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P3_data_contract
  id: P3_T01_FIELD_DICTIONARY_STRICT
  priority: P0
  title: field dictionary를 데이터 정합성의 단일 권위로 승격
  owner: data architect
  rationale: 필드명/단위/null 정책이 흔들리면 모든 공식이 오염된다.
  target_files:
  - spec/fields/field_dictionary.yaml
  - spec/12_field_dictionary.yaml
  - tools/validate_field_dictionary.py
  implementation_steps:
  - 필드마다 canonical_name, aliases, dtype, unit, nullable, freshness_sla, source_system, owner_formula를 정의
  - alias는 ingest 단계에서만 허용하고 formula engine 내부는 canonical_name만 허용
  - unknown field는 경고가 아니라 build fail
  commands:
  - python tools/validate_field_dictionary.py --strict
  acceptance_criteria:
  - canonical field coverage 100%
  - unknown_field_count == 0
  - unit_mismatch_count == 0
  - nullable_violation_count == 0
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P3_data_contract
  id: P3_T02_DATA_QUALITY_EXPECTATIONS
  priority: P0
  title: 데이터 품질 expectation suite 도입
  owner: data/QA
  rationale: 신선도, 결측, 범위, 단위, cross-field consistency를 코드화해야 데이터 정합성을 지속 관리할 수 있다.
  target_files:
  - spec/data_quality/expectations.yaml
  - tools/validate_data_quality_expectations.py
  - Temp/data_quality_reconciliation_v1.json
  implementation_steps:
  - 필드별 not_null, in_range, freshness, allowed_values, cross_field_rule 작성
  - 계좌/가격/펀더멘털/외부컨텍스트를 expectation group으로 분리
  - 위반은 severity critical|warning|info로 구분
  commands:
  - python tools/validate_data_quality_expectations.py --snapshot GatherTradingData.json --expect spec/data_quality/expectations.yaml
  acceptance_criteria:
  - critical expectation fail_count == 0
  - warning은 report에 노출
  - expectation coverage over required fields == 100
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P3_data_contract
  id: P3_T03_LINEAGE_EVENTS
  priority: P0
  title: artifact lineage 이벤트 원장 생성
  owner: platform
  rationale: 어떤 input이 어떤 output 숫자를 만들었는지 추적할 수 없으면 오류 원인 분석이 느리다.
  target_files:
  - runtime/lineage_events.jsonl
  - tools/emit_lineage_event.py
  - tools/validate_lineage.py
  implementation_steps:
  - 모든 build_*.py는 input_artifacts, output_artifacts, code_version_hash, started_at, ended_at, status를 lineage event로 기록
  - report의 각 숫자는 source_artifact와 formula_id를 역추적 가능해야 함
  - lineage 누락 시 release fail
  commands:
  - python tools/validate_lineage.py --manifest runtime/active_artifact_manifest.yaml --events runtime/lineage_events.jsonl
    --strict
  acceptance_criteria:
  - lineage_coverage_pct == 100 for active artifacts
  - orphan_artifact_count == 0
  - missing_code_hash_count == 0
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P4_code_refactor
  id: P4_T01_PYTHON_CANONICAL_PACKAGE
  priority: P0
  title: Python canonical engine 패키지화
  owner: senior developer
  rationale: tools/*.py에 기능이 분산되면 재사용성/테스트/타입 안정성이 낮아진다.
  target_files:
  - src/quant_engine/
  - pyproject.toml
  - tools/*.py
  implementation_steps:
  - src/quant_engine 패키지 생성
  - formulas, gates, routing, sizing, execution, reporting, validation 모듈 분리
  - tools/*.py는 CLI wrapper만 남기고 core logic은 src로 이동
  - 공통 load/validate/hash/logging utility 통합
  commands:
  - python -m pytest tests/unit tests/golden
  - python tools/validate_runtime_type_edges.py
  acceptance_criteria:
  - tools file average lines 감소
  - src unit test pass
  - CLI backward compatibility pass
  - mypy 또는 pyright strict subset pass 가능
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P4_code_refactor
  id: P4_T02_GAS_ADAPTER_SPLIT
  priority: P0
  title: 대형 GAS 파일을 adapter 계층으로 분할
  owner: GAS maintainer
  rationale: gas_data_feed.gs 1만 라인 구조는 단일 변경의 회귀 영향이 너무 크다.
  target_files:
  - gas/adapters/*.gs
  - gas/sheets/*.gs
  - gas/legacy/*.gs
  - gas_data_feed.gs
  implementation_steps:
  - GAS 함수를 data collect, normalization, formula adapter, sheet write, report bridge로 분리
  - legacy wrapper는 기존 함수명을 유지해 호환성 확보
  - 모든 복제 공식에 formula_id 주석과 Python canonical reference를 달기
  - GAS는 가능한 한 read/write adapter로 축소
  commands:
  - npm run validate-gas-call-arity
  - node tools/run_gas_golden_parity.js
  acceptance_criteria:
  - single gs file lines <= 1500
  - validate-gas-call-arity pass
  - gas golden parity pass
  - legacy public function missing 0건
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P4_code_refactor
  id: P4_T03_SCHEMA_MODEL_GENERATION
  priority: P0
  title: YAML/JSON schema에서 Pydantic model 자동 생성
  owner: developer/QA
  rationale: 스키마와 Python 타입이 따로 놀면 런타임 오류를 늦게 발견한다.
  target_files:
  - schemas/*.schema.json
  - schemas/generated/*.py
  - src/quant_engine/models/
  implementation_steps:
  - 스키마에서 Pydantic model 생성 또는 수동 model과 schema parity 검증
  - strict type, unit, optional policy 적용
  - artifact 로딩은 model validation을 통과해야만 허용
  commands:
  - python tools/generate_models_from_schema.py --schemas schemas --out src/quant_engine/models/generated
  - python tools/validate_runtime_type_edges.py
  acceptance_criteria:
  - all active artifacts validate with generated models
  - model/schema drift count == 0
  - runtime type edge validation pass
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P5_decision_harness
  id: P5_T01_DECISION_GRAPH_DAG
  priority: P0
  title: 11단계 라우팅을 DAG로 명시하고 결정 경로를 로그화
  owner: architect/quant
  rationale: 결정 순서가 문서/코드마다 다르면 같은 데이터에서 다른 verdict가 나온다.
  target_files:
  - spec/routing/decision_graph.yaml
  - src/quant_engine/routing/decision_graph.py
  - Temp/routing_execution_log_table_v1.json
  implementation_steps:
  - '노드: data_quality -> portfolio_health -> cash -> heat -> stop/tp -> anti_chase -> regime -> sector/beta -> style -> sizing
    -> execution'
  - 각 노드의 inputs, outputs, preconditions, fail_action, priority를 YAML로 작성
  - router는 YAML DAG를 읽어 실행하고 trace를 남김
  commands:
  - python tools/validate_decision_graph.py --graph spec/routing/decision_graph.yaml --strict
  - python tools/build_routing_execution_log_v1.py
  acceptance_criteria:
  - routing path deterministic hash stable
  - all verdicts have decision_path
  - unreachable node count == 0
  - priority conflict count == 0
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P5_decision_harness
  id: P5_T02_FINAL_PACKET_CONTRACT
  priority: P0
  title: final_decision_packet을 LLM 입력의 유일한 계약으로 고정
  owner: reporting/architect
  rationale: 저성능 LLM은 입력이 많으면 임의 선택을 하므로 final packet 하나만 읽게 해야 한다.
  target_files:
  - schemas/final_decision_packet_v3.schema.json
  - Temp/final_decision_packet_v3.json
  - prompts/report_renderer_prompt.md
  implementation_steps:
  - packet에 account_summary, portfolio_health, gate_summary, order_blueprint, shadow_ledger, evidence_ledger, forbidden_actions를
    포함
  - 모든 숫자 필드에는 source_ref와 formula_id를 붙임
  - LLM prompt는 packet 외 파일 참조 금지
  commands:
  - python tools/build_final_decision_packet_v3.py --manifest runtime/active_artifact_manifest.yaml --out Temp/final_decision_packet_v3.json
  - python tools/validate_final_decision_packet.py --strict
  acceptance_criteria:
  - final packet schema valid
  - all numeric fields have provenance
  - renderer direct Temp read count == 0
  - unsupported number count == 0
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P5_decision_harness
  id: P5_T03_SHADOW_LEDGER_MANDATORY
  priority: P0
  title: 차단 종목도 산출 지표를 감추지 않는 shadow ledger 강화
  owner: reporting/QA
  rationale: 사용자 판단권과 사후 평가를 위해 BLOCKED/WATCH도 산출 수명 지표가 보여야 한다.
  target_files:
  - spec/outputs/shadow_ledger_contract.yaml
  - schemas/shadow_ledger.schema.json
  - src/quant_engine/reporting/shadow_ledger.py
  implementation_steps:
  - BLOCKED, WATCH, HOLD, BUY, SELL 모두 산출 지정가/손절가/익절가/이론수량/차단사유를 보존
  - HTS 가능 주문표와 shadow ledger를 물리적으로 분리
  - 차단 사유는 formula_id 기반 단답으로 제한
  commands:
  - python tools/validate_shadow_ledger.py --strict
  acceptance_criteria:
  - blocked item shadow coverage == 100%
  - HTS order table contains only executable orders
  - shadow ledger numeric provenance == 100%
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P6_llm_serving
  id: P6_T01_LOW_CAPABILITY_RENDER_CONTRACT
  priority: P0
  title: 저성능 LLM용 renderer contract를 폐쇄형으로 작성
  owner: LLM/reporting
  rationale: 저성능 LLM이 최고 LLM과 같은 결과를 내게 하려면 자유서술이 아니라 slot filling만 허용해야 한다.
  target_files:
  - prompts/low_capability_report_renderer.md
  - spec/render/renderer_contract.yaml
  - tools/validate_llm_response.py
  implementation_steps:
  - 입력은 final_decision_packet_v3.json만 허용
  - 출력 섹션 순서와 테이블 컬럼을 고정
  - 숫자는 {{source_ref.value}} 형태로만 복사
  - 없는 값은 MISSING_SOURCE로 표시하고 추정 금지
  - 금지 어휘와 softening narrative 목록 적용
  commands:
  - python tools/validate_llm_response.py --packet Temp/final_decision_packet_v3.json --report Temp/operational_report.md
    --strict
  acceptance_criteria:
  - llm_freedom_pct == 0
  - ungrounded_number_count == 0
  - required_section_missing_count == 0
  - narrative_softening_violation_count == 0
  low_capability_llm_instruction: final_decision_packet_v3.json 이외의 파일을 읽지 마라. 표 컬럼을 변경하지 마라. 숫자는 복사만 하라. 누락은 누락이라고 써라.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P6_llm_serving
  id: P6_T02_NUMBER_PROVENANCE_AUDIT
  priority: P0
  title: 모든 수치 출처 자기감사 mandatory
  owner: QA
  rationale: 숫자 하나라도 근거 없이 출력되면 투자 엔진 신뢰성이 무너진다.
  target_files:
  - Temp/number_provenance_audit_v3.json
  - tools/validate_number_provenance_v2.py
  implementation_steps:
  - 보고서의 모든 숫자 token을 추출
  - packet/evidence ledger에 존재하는지 매칭
  - '허용 형식: 날짜, 순번, 섹션 번호 등 non-investment number whitelist 분리'
  - 불일치 시 release fail
  commands:
  - python tools/validate_number_provenance_v2.py --report Temp/operational_report.md --packet Temp/final_decision_packet_v3.json
    --strict
  acceptance_criteria:
  - investment_number_coverage_pct == 100
  - ungrounded_investment_number_count == 0
  - whitelist_abuse_count == 0
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P7_testing_release
  id: P7_T01_TEST_PYRAMID
  priority: P0
  title: 테스트 피라미드 재구성
  owner: QA/developer
  rationale: 검증 스크립트는 많지만 테스트 계층이 명확하지 않으면 누락과 중복이 동시에 발생한다.
  target_files:
  - tests/unit
  - tests/golden
  - tests/parity
  - tests/regression
  - tests/integration
  - tests/e2e
  implementation_steps:
  - 'unit: pure formula/gate'
  - 'golden: 손계산 기대값'
  - 'parity: Python vs GAS'
  - 'regression: 과거 실패 케이스'
  - 'integration: pipeline artifacts'
  - 'e2e: report quality와 deterministic replay'
  commands:
  - python -m pytest tests/unit tests/golden tests/regression
  - npm run validate-determinism
  - npm run full-gate
  acceptance_criteria:
  - decision critical formula unit coverage == 100
  - golden pass == 100
  - regression fail recurrence == 0
  - e2e deterministic replay pass
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P7_testing_release
  id: P7_T02_RELEASE_TRAIN
  priority: P0
  title: release train과 promotion gate 고정
  owner: release manager
  rationale: 임의 수동 패키징과 부분 검증은 운영 신뢰도를 떨어뜨린다.
  target_files:
  - spec/release/release_train.yaml
  - package.json
  - tools/release_gate.py
  implementation_steps:
  - dev -> shadow -> limited -> release 4단계 승격 정의
  - shadow는 주문표를 생성하되 실행권고 금지
  - limited는 일부 섹션만 운영 반영
  - release는 full-gate와 outcome feedback 필수
  - rollback command와 이전 manifest 보존
  commands:
  - npm run validate-engine-strict
  - npm run full-gate
  - npm run prepare-upload-zip -- --validation-mode release --profile
  acceptance_criteria:
  - release package requires gate_status OK
  - failed_checks_count == 0
  - rollback_manifest exists
  - skip_validate usage count == 0
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P7_testing_release
  id: P7_T03_DETERMINISM_REPLAY
  priority: P0
  title: 결정론 replay pack 확대
  owner: QA/platform
  rationale: 동일 데이터에서 매번 다른 보고서가 나오면 LLM/엔진 모두 운영 불가다.
  target_files:
  - tests/replay/*.yaml
  - Temp/audit_replay_snapshot_v2.json
  - tools/validate_determinism.py
  implementation_steps:
  - 대표 국면 12개와 실패 사례 30개를 replay case로 고정
  - input hash, expected packet hash, expected gate summary 기록
  - 문장 표현은 바뀌어도 numeric packet hash는 동일해야 함
  commands:
  - npm run validate-determinism
  - python tools/validate_replay_pack.py --strict
  acceptance_criteria:
  - packet_hash_match_pct == 100
  - gate_summary_match_pct == 100
  - numeric_diff_count == 0
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P8_observability_feedback
  id: P8_T01_OBSERVABILITY_RUN_PROFILE
  priority: P0
  title: 파이프라인 실행 관측성 표준화
  owner: platform
  rationale: 검증이 느려지고 실패 원인이 불명확해지면 개발 속도가 떨어진다.
  target_files:
  - runtime/run_profiles/*.json
  - src/quant_engine/observability/
  - tools/profile_pipeline_runtime.py
  implementation_steps:
  - 모든 npm script와 build tool은 elapsed_ms, input_count, output_count, status, error_code를 기록
  - heavy/quick/package-only 모드별 SLA 지정
  - 이상 소요시간과 중복 실행을 검출
  commands:
  - npm run profile-pipeline-runtime
  - python tools/validate_pipeline_runtime_anomaly.py
  acceptance_criteria:
  - profile coverage for required scripts == 100
  - release elapsed <= target or justified
  - duplicate heavy validation count == 0
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P8_observability_feedback
  id: P8_T02_OUTCOME_ATTRIBUTION
  priority: P0
  title: 실거래/미실행 결과 귀속 원장 강화
  owner: quant/PM
  rationale: 룰이 성과를 개선했는지 모르고 계속 추가하면 과최적화된다.
  target_files:
  - Temp/outcome_ledger_v2.json
  - Temp/live_vs_replay_performance_audit_v2.json
  - tools/build_outcome_attribution.py
  implementation_steps:
  - 추천 당시 packet과 이후 가격/체결/미체결 결과 연결
  - alpha lead, late chase, value damage, slippage, opportunity cost를 분해
  - 룰별 contribution과 false positive/negative 집계
  - sample_n 미달은 개선 증거로 사용 금지
  commands:
  - python tools/build_outcome_attribution.py --packet-history Temp --out Temp/outcome_ledger_v2.json
  - python tools/validate_outcome_eval_window.py --strict
  acceptance_criteria:
  - each recommendation has outcome_id or pending_reason
  - rule_attribution coverage >= 95%
  - sample_maturity labels present
  - no design_score_as_real_performance
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P9_operating_model
  id: P9_T01_WEEKLY_ENGINE_REVIEW
  priority: P0
  title: 주간 엔진 리뷰 프로토콜 정착
  owner: PM/quant
  rationale: 투자 엔진은 코드 품질과 투자성과를 같이 리뷰해야 한다.
  target_files:
  - governance/weekly_engine_review_template.md
  - Temp/continuous_evaluation_dashboard_v2.json
  implementation_steps:
  - 매주 토/일 리밸런싱 전 engine health, data quality, formula parity, outcome drift, active rule changes를 1페이지로 리뷰
  - 투자 제안과 엔진 변경 제안을 분리
  - 긴급 패치와 정규 패치를 구분
  commands:
  - python tools/build_continuous_evaluation_dashboard_v2.py
  - python tools/render_weekly_engine_review.py
  acceptance_criteria:
  - weekly review generated
  - critical engine issue count reported
  - new rule without outcome hypothesis count == 0
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
- phase: P9_operating_model
  id: P9_T02_CHANGE_REQUEST_TEMPLATE
  priority: P0
  title: 룰/공식 변경 요청 템플릿 표준화
  owner: PM/architect
  rationale: 변경 요청이 산발적이면 개발자가 문맥을 추정하게 되고 설계가 흔들린다.
  target_files:
  - governance/change_request_template.yaml
  - governance/change_requests/*.yaml
  implementation_steps:
  - '변경 요청 필수 필드: problem, evidence, target_metric, affected_formula, affected_output, expected_side_effect, rollback_plan,
    test_cases'
  - 승인 없는 변경은 active 승격 금지
  - 긴급 hotfix는 72시간 내 ADR로 정리
  commands:
  - python tools/validate_change_requests.py --strict
  acceptance_criteria:
  - all active changes have request_id
  - rollback_plan missing 0건
  - test_case missing 0건
  low_capability_llm_instruction: 입력 파일을 열고 implementation_steps를 순서대로 수행한다. 판단하거나 생략하지 않는다. 숫자는 target_files 또는 산출 artifact에
    있는 값만 사용한다.
  reject_if:
  - 근거 artifact 없이 완료 선언
  - 공식/수치를 임의 생성
  - 검증 명령 실패를 무시
low_capability_llm_master_runbook:
  purpose: 저성능 LLM 또는 주니어 작업자가 TODO만 보고도 동일한 리팩토링 결과물을 만들도록 하는 폐쇄형 작업 절차
  global_rules:
  - 절대 추정하지 않는다. 파일에 없으면 MISSING_SOURCE로 표시한다.
  - 숫자·공식·threshold·가격·수량을 새로 만들지 않는다.
  - 한 번에 한 phase만 수행한다. phase acceptance가 PASS가 아니면 다음 phase로 가지 않는다.
  - Temp의 v숫자 파일을 임의 최신으로 선택하지 않는다. active manifest만 따른다.
  - 문서 변경은 반드시 대응 validator 또는 grep check를 추가한다.
  - 대형 파일에서 내용을 삭제하지 말고 먼저 split script로 이동 후 hash/count 검증을 한다.
  - 완료 보고는 PASS/WARN/FAIL 중 하나로만 한다. 100%라는 표현은 completion gate가 증명할 때만 쓴다.
  execution_order:
  - P0_T01_ACTIVE_MANIFEST
  - P0_T02_AUTHORITY_MATRIX
  - P0_T03_BASELINE_METRICS
  - P1_T01_AGENTS_SHRINK
  - P1_T02_ADR_SYSTEM
  - P1_T03_RULE_LIFECYCLE
  - P2_T01_FORMULA_DOMAIN_SPLIT
  - P2_T02_GOLDEN_CASE_EXPANSION
  - P2_T03_THRESHOLD_CALIBRATION_LEDGER
  - P3_T01_FIELD_DICTIONARY_STRICT
  - P3_T02_DATA_QUALITY_EXPECTATIONS
  - P3_T03_LINEAGE_EVENTS
  - P4_T01_PYTHON_CANONICAL_PACKAGE
  - P4_T02_GAS_ADAPTER_SPLIT
  - P4_T03_SCHEMA_MODEL_GENERATION
  - P5_T01_DECISION_GRAPH_DAG
  - P5_T02_FINAL_PACKET_CONTRACT
  - P5_T03_SHADOW_LEDGER_MANDATORY
  - P6_T01_LOW_CAPABILITY_RENDER_CONTRACT
  - P6_T02_NUMBER_PROVENANCE_AUDIT
  - P7_T01_TEST_PYRAMID
  - P7_T02_RELEASE_TRAIN
  - P7_T03_DETERMINISM_REPLAY
  - P8_T01_OBSERVABILITY_RUN_PROFILE
  - P8_T02_OUTCOME_ATTRIBUTION
  - P9_T01_WEEKLY_ENGINE_REVIEW
  - P9_T02_CHANGE_REQUEST_TEMPLATE
  per_task_required_output_format:
    status: PASS|WARN|FAIL
    changed_files:
    - path1
    - path2
    commands_run:
    - command: string
      exit_code: integer
      summary: string
    metrics_before_after:
    - metric: string
      before: number|string
      after: number|string
      target: number|string
    remaining_risks:
    - risk1
    next_task_id: string
  stop_conditions:
  - schema validation failure
  - golden case failure
  - gas/python parity failure
  - authority collision count > 0 after P0
  - ungrounded number count > 0 after P6
  - release gate failed_checks_count > 0
minimal_new_files_to_add_first:
- path: runtime/active_artifact_manifest.yaml
  why: Temp 산출물 버전 오독 차단
- path: governance/authority_matrix.yaml
  why: 필드/공식/출력 권위 충돌 차단
- path: governance/rule_lifecycle.yaml
  why: 룰 누적 부채 차단
- path: governance/adr/0001-adopt-qeda-dm.md
  why: 방법론 채택 의사결정 기록
- path: spec/routing/decision_graph.yaml
  why: 결정 순서와 우선순위 고정
- path: spec/render/renderer_contract.yaml
  why: LLM renderer 자유도 0% 강제
- path: spec/data_quality/expectations.yaml
  why: 데이터 정합성 기대값 코드화
- path: tests/golden/formula_golden_cases.yaml
  why: 공식 회귀 방지
- path: runtime/lineage_events.jsonl
  why: 원인 추적과 영향 분석
- path: Temp/refactor_baseline_metrics_v1.json
  why: 리팩토링 효과 수치 증빙
first_10_commands_after_files_exist:
- python tools/build_refactor_baseline_metrics.py --root . --out Temp/refactor_baseline_metrics_v1.json
- python tools/validate_active_manifest.py --manifest runtime/active_artifact_manifest.yaml --strict
- python tools/validate_authority_matrix.py --strict
- python tools/validate_field_dictionary.py --strict
- python tools/validate_formula_registry.py --strict
- python tools/run_golden_cases_py.py --cases tests/golden/formula_golden_cases.yaml
- node tools/run_gas_golden_parity.js --cases tests/golden/formula_golden_cases.yaml
- python tools/validate_decision_graph.py --graph spec/routing/decision_graph.yaml --strict
- python tools/validate_llm_response.py --packet Temp/final_decision_packet_v3.json --report Temp/operational_report.md --strict
- npm run full-gate
definition_of_done:
  phase_0_done:
  - active_manifest exists
  - authority_collision_count == 0
  - baseline metrics generated
  phase_1_done:
  - AGENTS.md <= 350 lines
  - all rules preserved by ID hash
  - ADR index valid
  phase_2_done:
  - formula registry split
  - normalized build deterministic
  - golden/parity pass
  phase_3_done:
  - field dictionary strict pass
  - data quality expectations pass
  - lineage coverage 100
  phase_4_done:
  - Python canonical package test pass
  - GAS adapters split and parity pass
  - schema model drift 0
  phase_5_done:
  - decision graph deterministic
  - final packet valid
  - shadow ledger coverage 100
  phase_6_done:
  - LLM freedom 0
  - ungrounded numbers 0
  - narrative lock pass
  phase_7_done:
  - test pyramid pass
  - release train gate pass
  - replay hash match 100
  phase_8_done:
  - run profiles complete
  - outcome attribution coverage >= 95
  phase_9_done:
  - weekly review generated
  - all active changes have request/ADR/rollback
recommended_pm_cadence:
  daily:
  - data freshness check
  - failed gate triage
  - lineage missing check
  weekly_sat_sun:
  - portfolio rebalance report
  - engine health review
  - rule outcome review
  - new TODO reprioritization
  monthly_1_11_21:
  - mid-cycle checkpoint
  - calibration registry review
  - sample maturity review
  - data source SLA review
  release:
  - ADR review
  - golden/parity/replay pass
  - full-gate pass
  - rollback manifest prepared
anti_patterns_forbidden:
- AGENTS.md에 새 상세 공식을 계속 붙여넣기
- Temp 파일명에 v숫자가 높다는 이유로 최신으로 간주하기
- GAS와 Python에 같은 공식을 복붙하고 parity test를 생략하기
- schema 없이 JSON artifact를 추가하기
- sample_n 부족인데 PASS 또는 성능 개선으로 주장하기
- 보고서 품질 개선을 위해 LLM에게 수치 보완을 허용하기
- 검증 실패를 skip 옵션으로 통과시키기
- 대형 파일에 새 함수를 계속 추가하기
- 룰 추가를 성능 개선으로 간주하고 outcome ledger를 생략하기
- 외부 뉴스/가격을 주문 판단 숫자에 직접 혼입하기
external_method_basis:
  ADR: 아키텍처 의사결정은 ADR로 context/decision/consequence를 기록한다.
  JSON_Schema: artifact shape와 validation vocabulary는 schema로 고정한다.
  Data_Quality_Expectation: 데이터 품질 규칙은 expectation/test로 코드화한다.
  Data_Lineage: dataset/job/run 수준 lineage로 오류 원인과 변경 영향 분석을 가능하게 한다.
  Type_Validation: Python 타입/모델 validation으로 artifact drift를 조기 차단한다.
  Testing: pytest 기반 unit/golden/regression 테스트를 CI 게이트화한다.
  Observability: trace/metric/log 기반으로 pipeline run의 상태와 병목을 관측한다.
task_execution_status:
  summary:
    implemented: 27
    validated: 0
    completed: 27
    blocked: 0
    operational_ready: false
  items:
    - id: P0_T01_ACTIVE_MANIFEST
      status: completed
      evidence:
        - runtime/active_artifact_manifest.yaml
        - tools/validate_active_manifest.py
        - Temp/active_artifact_manifest_v2.json
    - id: P0_T02_AUTHORITY_MATRIX
      status: completed
      evidence:
        - governance/authority_matrix.yaml
        - spec/03_formulas/output_field_owner_ledger.yaml
        - spec/12_field_dictionary.yaml
        - tools/build_authority_matrix.py
        - tools/validate_authority_matrix.py
    - id: P0_T03_BASELINE_METRICS
      status: completed
      evidence:
        - Temp/refactor_baseline_metrics_v1.json
        - tools/build_refactor_baseline_metrics.py
    - id: P1_T01_AGENTS_SHRINK
      status: completed
      evidence:
        - AGENTS.md
        - governance/agents_index.yaml
        - governance/agents_rule_hashes.yaml
        - governance/rules/00_core_locks.yaml
        - governance/rules/01_harness_contract.yaml
        - governance/rules/02_portfolio_policy.yaml
        - governance/rules/03_order_grammar.yaml
        - governance/rules/04_reporting_contract.yaml
        - governance/rules/05_migration_hashes.yaml
        - tools/validate_agents_shrink_v1.py
        - tools/build_agents_rule_hashes_v1.py
        - tools/validate_agents_rule_hashes_v1.py
    - id: P1_T02_ADR_SYSTEM
      status: completed
      evidence:
        - governance/adr_index.yaml
        - governance/adr/*.md
        - tools/validate_adr_index.py
    - id: P1_T03_RULE_LIFECYCLE
      status: completed
      evidence:
        - governance/rule_lifecycle.yaml
        - tools/validate_rule_lifecycle.py
    - id: P2_T01_FORMULA_DOMAIN_SPLIT
      status: completed
      evidence:
        - spec/formulas/risk.yaml
        - spec/formulas/entry.yaml
        - spec/formulas/exit.yaml
        - spec/formulas/cash.yaml
        - spec/formulas/portfolio.yaml
        - spec/formulas/reporting.yaml
        - spec/formulas/manifest.yaml
        - spec/03_formulas/formula_registry.normalized.yaml
        - tools/split_formula_registry.py
        - tools/build_formula_registry_normalized.py
        - tools/validate_formula_registry.py
    - id: P2_T02_GOLDEN_CASE_EXPANSION
      status: completed
      evidence:
        - spec/formula_golden_cases_v4.yaml
        - Temp/yaml_code_coverage_v1.json
        - tools/build_yaml_code_coverage_v1.py
        - tools/validate_golden_coverage_100.py
    - id: P2_T03_THRESHOLD_CALIBRATION_LEDGER
      status: completed
      evidence:
        - Temp/calibration_change_ledger_v4.json
        - Temp/calibration_priority_v1.json
        - Temp/outcome_ledger_v1.json
        - tools/build_calibration_change_ledger_v4.py
        - tools/validate_calibration_change_ledger_v1.py
    - id: P3_T01_FIELD_DICTIONARY_STRICT
      status: completed
      evidence:
        - spec/fields/field_dictionary.yaml
        - spec/12_field_dictionary.yaml
        - tools/validate_field_dictionary.py
    - id: P3_T02_DATA_QUALITY_EXPECTATIONS
      status: completed
      evidence:
        - spec/data_quality/expectations.yaml
        - tools/validate_data_quality_expectations.py
    - id: P3_T03_LINEAGE_EVENTS
      status: completed
      evidence:
        - runtime/lineage_events.jsonl
        - tools/emit_lineage_event.py
        - tools/validate_lineage.py
    - id: P4_T01_PYTHON_CANONICAL_PACKAGE
      status: completed
      evidence:
        - src/quant_engine/__init__.py
        - src/quant_engine/models/__init__.py
        - src/quant_engine/models/generated/__init__.py
        - tools/generate_models_from_schema.py
        - tools/validate_schema_model_generation_v1.py
        - Temp/schema_model_generation_v1.json
    - id: P4_T02_GAS_ADAPTER_SPLIT
      status: completed
      evidence:
        - spec/39_gas_thin_adapter_policy.yaml
        - tools/validate_gas_thin_adapter_v1.py
        - Temp/gas_business_logic_audit_v1.json
    - id: P4_T03_SCHEMA_MODEL_GENERATION
      status: completed
      evidence:
        - schemas/generated/*.schema.json
        - src/quant_engine/models/generated/*.py
        - tools/generate_models_from_schema.py
        - tools/validate_schema_model_generation_v1.py
    - id: P5_T01_DECISION_GRAPH_DAG
      status: completed
      evidence:
        - spec/routing/decision_graph.yaml
        - tools/validate_decision_graph.py
        - tools/build_routing_execution_log_v1.py
    - id: P5_T02_FINAL_PACKET_CONTRACT
      status: completed
      evidence:
        - schemas/final_decision_packet_v3.schema.json
        - Temp/final_decision_packet_v3.json
        - tools/build_final_decision_packet_v3.py
        - tools/validate_final_decision_packet.py
    - id: P5_T03_SHADOW_LEDGER_MANDATORY
      status: completed
      evidence:
        - spec/outputs/shadow_ledger_contract.yaml
        - schemas/shadow_ledger.schema.json
        - src/quant_engine/reporting/shadow_ledger.py
        - Temp/shadow_ledger_v1.json
        - tools/validate_shadow_ledger.py
    - id: P6_T01_LOW_CAPABILITY_RENDER_CONTRACT
      status: completed
      evidence:
        - prompts/low_capability_report_renderer.md
        - spec/render/renderer_contract.yaml
        - tools/validate_llm_response.py
    - id: P6_T02_NUMBER_PROVENANCE_AUDIT
      status: completed
      evidence:
        - Temp/number_provenance_audit_v3.json
        - tools/build_number_provenance_audit_v2.py
        - tools/validate_number_provenance_v2.py
    - id: P7_T01_TEST_PYRAMID
      status: completed
      evidence:
        - tests/unit
        - tests/golden
        - tests/parity
        - tests/regression
        - tests/integration
        - tests/e2e
        - tools/validate_test_pyramid.py
    - id: P7_T02_RELEASE_TRAIN
      status: completed
      evidence:
        - spec/release/release_train.yaml
        - tools/validate_release_train.py
        - tools/release_gate.py
    - id: P7_T03_DETERMINISM_REPLAY
      status: completed
      evidence:
        - tests/replay/README.yaml
        - tools/validate_replay_pack.py
        - tools/validate_determinism.py
    - id: P8_T01_OBSERVABILITY_RUN_PROFILE
      status: completed
      evidence:
        - runtime/run_profiles/profile_pipeline_runtime.json
        - tools/profile_pipeline_runtime.py
        - tools/validate_pipeline_runtime_anomaly.py
    - id: P8_T02_OUTCOME_ATTRIBUTION
      status: completed
      evidence:
        - Temp/outcome_ledger_v2.json
        - Temp/live_vs_replay_performance_audit_v2.json
        - tools/build_outcome_attribution.py
        - tools/validate_outcome_eval_window.py
    - id: P9_T01_WEEKLY_ENGINE_REVIEW
      status: completed
      evidence:
        - governance/weekly_engine_review_template.md
        - Temp/continuous_evaluation_dashboard_v2.json
        - Temp/weekly_engine_review.md
        - tools/build_continuous_evaluation_dashboard_v2.py
        - tools/render_weekly_engine_review.py
    - id: P9_T02_CHANGE_REQUEST_TEMPLATE
      status: completed
      evidence:
        - governance/change_request_template.yaml
        - governance/change_requests/0001-example.yaml
        - tools/validate_change_requests.py