Files
QuantEngineByItz/suggest/quant_engine_qedd_refactor_master_todo_20260607.yaml
T

1103 lines
47 KiB
YAML

schema_version: quant_engine_qedd_refactor_master_todo.v2
document_type: downloadable_yaml_refactor_playbook
language: ko-KR
created_at_kst: '2026-06-07T15:55:00+09:00'
plan_id: QEDD-QUANT-ENGINE-REFACTOR-20260607
title: 저성능 LLM도 동일 결과를 내는 계약우선·증거주도 퀀트투자 엔진 리팩토링 TODO
executive_decision:
recommended_methodology: 'QEDD: Quant Evidence-Driven Development + Contract-First
Deterministic Engine'
one_sentence: spec가 계약을 정의하고, Python이 숫자를 계산하고, GAS는 수집/표시만 하며, Temp는 산출물만 담고, LLM은
final packet을 복사·해설만 한다.
cold_verdict: 현재 구조는 방향성은 맞지만 GAS 대형화, 공식/도메인 파일 비대화, 중복 버전 가족, source_path 정합성
리스크를 더 엄격히 눌러야 장기 확장성이 생긴다.
north_star: 5억원 목표 자산 달성까지 주간 리밸런싱·수익방어·데이터정합성·검증가능성을 동시에 유지하는 운영 엔진
business_constants:
target_asset_krw: 500000000
default_investment_unit: weekly
mandatory_weekly_rebalancing_days:
- Saturday
- Sunday
mandatory_mid_month_review_days:
- 1
- 11
- 21
cash_defense_rule: D+2 정산예정 현금은 즉시현금 방어선 충족으로 간주하되, 주문가능현금과 분리한다.
llm_numeric_authority: LLM은 가격, 수량, 점수, TP, SL, 게이트를 생성하지 않고 하네스 값을 복사·해설만 한다.
source_evidence:
source_zip: /mnt/data/data_feed.zip
source_zip_sha256: 59ae29ccdc2b843449410ad97adf5b4ea03a97196827e303349a5543f70d1238
read_authority_files:
- AGENTS.md
- docs/doctrine.md
- runtime/active_artifact_manifest.yaml
- spec/40_final_decision_packet_contract.yaml
- spec/43_quant_factor_taxonomy.yaml
- spec/46_low_capability_execution_pack.yaml
- spec/41_release_dag.yaml
- spec/ownership_map.yaml
- package.json
agents_hard_rules_used:
- 가격·수량·TP·SL·점수는 공식 레지스트리와 하네스 산출값만 사용
- 임의 계산·임의 가격·임의 수량·미등록 공식 금지
- 하네스 결측은 DATA_MISSING으로만 표시
- 차단 종목 산출값은 shadow ledger에 투명하게 기록
- Python canonical first, GAS adapter second
- Temp는 런타임 산출물이며 직접 편집하지 않음
observed_current_state:
repository_snapshot:
total_files: 1418
requested_format_file_count_md_yaml_gs_py: 1037
extension_counts:
.gs: 7
.js: 1
.json: 374
.jsonl: 2
.md: 38
.ps1: 4
.py: 827
.yaml: 165
requested_extension_counts:
.gs: 7
.md: 38
.py: 827
.yaml: 165
top_directory_counts:
tools: 353
src: 328
schemas: 165
tests: 160
runtime: 158
spec: 122
artifacts: 40
governance: 25
Temp: 18
prompts: 9
suggest: 9
docs: 8
examples: 8
dist: 2
AGENTS.md: 1
largest_risk_files:
- path: gas_data_feed.gs
size_bytes: 470962
- path: gas_data_collect.gs
size_bytes: 225777
- path: spec/13_formula_registry.yaml
size_bytes: 180041
- path: spec/13b_harness_formulas.yaml
size_bytes: 166900
- path: Temp/operational_report.md
size_bytes: 237659
duplicate_version_families_ge_3_count: 11
duplicate_version_family_examples:
- count: 6
directory: artifacts/archive/2026-06-06
family: smart_cash_recovery_vX
extension: .json
examples:
- artifacts/archive/2026-06-06/smart_cash_recovery_v3.json
- artifacts/archive/2026-06-06/smart_cash_recovery_v4.json
- artifacts/archive/2026-06-06/smart_cash_recovery_v5.json
- artifacts/archive/2026-06-06/smart_cash_recovery_v6.json
- artifacts/archive/2026-06-06/smart_cash_recovery_v7.json
- count: 4
directory: tools
family: build_smart_cash_recovery_vX
extension: .py
examples:
- tools/build_smart_cash_recovery_v3.py
- tools/build_smart_cash_recovery_v4.py
- tools/build_smart_cash_recovery_v5.py
- tools/build_smart_cash_recovery_v6.py
- count: 3
directory: tools
family: run_release_dag_vX
extension: .py
examples:
- tools/run_release_dag_v1.py
- tools/run_release_dag_v2.py
- tools/run_release_dag_v3.py
- count: 3
directory: tools
family: build_pass_100_criteria_vX
extension: .py
examples:
- tools/build_pass_100_criteria_v1.py
- tools/build_pass_100_criteria_v3.py
- tools/build_pass_100_criteria_v4.py
- count: 3
directory: tools
family: build_final_execution_decision_vX
extension: .py
examples:
- tools/build_final_execution_decision_v1.py
- tools/build_final_execution_decision_v2.py
- tools/build_final_execution_decision_v4.py
- count: 3
directory: spec
family: formula_golden_cases_vX
extension: .yaml
examples:
- spec/formula_golden_cases_v2.yaml
- spec/formula_golden_cases_v3.yaml
- spec/formula_golden_cases_v4.yaml
- count: 3
directory: artifacts/archive/20260606
family: release_gate_summary_vX
extension: .json
examples:
- artifacts/archive/20260606/release_gate_summary_v1.json
- artifacts/archive/20260606/release_gate_summary_v2.json
- artifacts/archive/20260606/release_gate_summary_v3.json
- count: 3
directory: artifacts/archive/2026-06-06
family: smart_money_liquidity_evidence_gate_vX
extension: .json
examples:
- artifacts/archive/2026-06-06/smart_money_liquidity_evidence_gate_v2.json
- artifacts/archive/2026-06-06/smart_money_liquidity_evidence_gate_v3.json
- artifacts/archive/2026-06-06/smart_money_liquidity_evidence_gate_v4.json
- count: 3
directory: artifacts/archive/2026-06-06
family: prediction_accuracy_harness_vX
extension: .json
examples:
- artifacts/archive/2026-06-06/prediction_accuracy_harness_v2.json
- artifacts/archive/2026-06-06/prediction_accuracy_harness_v3.json
- artifacts/archive/2026-06-06/prediction_accuracy_harness_v4.json
- count: 3
directory: artifacts/archive/2026-06-06
family: final_execution_decision_vX
extension: .json
examples:
- artifacts/archive/2026-06-06/final_execution_decision_v1.json
- artifacts/archive/2026-06-06/final_execution_decision_v2.json
- artifacts/archive/2026-06-06/final_execution_decision_v3.json
package_script_count: 21
runtime_snapshot:
active_manifest_formula_id: ACTIVE_ARTIFACT_MANIFEST_V2
active_manifest_canonical_source: Temp/final_decision_packet_active.json
active_manifest_report_active_artifact_match_pct: 100.0
active_manifest_authority_collision_count: 0
active_manifest_stale_artifact_count: 0
engine_harness_gate_status: OK
engine_harness_failed_checks_count: 0
release_dag_steps_total: 20
release_dag_steps_passed: 20
final_execution_gate: AUDIT_ONLY
current_total_asset_krw: 424096398.0
goal_krw: 500000000.0
cash_shortfall_min_krw: 36092555.0
cash_recovered_krw: 57841575.0
market_regime: overheated_or_event_week
selected_horizon: MID
selected_strategy: SCALP_MID
t5_prediction_match_rate_pct: 54.76
t5_prediction_sample: 312
t20_live_sample: 0
prediction_calibration_state: MONITOR
diagnosis:
- id: D01
severity: P0
finding: GAS 파일 수는 적지만 핵심 GAS 파일이 지나치게 크다.
risk: GAS에 판단 로직이 남을수록 Python canonical 원칙과 검증 재현성이 깨진다.
fix: GAS business logic inventory → Python formula migration → GAS thin adapter
validator를 release gate로 둔다.
- id: D02
severity: P0
finding: 공식/하네스 YAML이 비대해져 사람이 직접 리뷰하기 어렵다.
risk: 공식 ID·필드·소유권 충돌이 누적되어 작은 수정이 시스템 전체 판단을 흔든다.
fix: 도메인별 formula registry로 분할하고 normalized registry는 자동 생성한다.
- id: D03
severity: P0
finding: packet provenance source_path의 실재 여부를 별도 검증해야 한다.
risk: 숫자 provenance가 있어도 실제 파일이 없으면 감사와 재현이 불가능하다.
fix: validate_packet_source_paths_v1을 release DAG에 추가한다.
- id: D04
severity: P1
finding: 중복 버전 가족이 아직 남아 있다.
risk: 저성능 LLM과 운영자가 최신 v 파일을 추측해 다른 판단을 낼 수 있다.
fix: active/canonical/archive 수명주기와 manifest-only read rule을 강제한다.
- id: D05
severity: P1
finding: T+5 예측 일치율은 54.76% MONITOR이고 T+20 live sample은 0건이다.
risk: 수익률 개선 팩터를 active로 서두르면 뒷북매수와 설거지 리스크가 커진다.
fix: shadow-before-active, live/replay 분리, T+20 live 최소 표본 기준을 강제한다.
- id: D06
severity: P1
finding: final execution gate가 AUDIT_ONLY다.
risk: 엔진은 보고·감사 모드로 봐야 하며 자동 실행 엔진처럼 취급하면 위험하다.
fix: execution readiness, data maturity, live outcome sample을 충족하기 전까지 theoretical/order
simulation으로 제한한다.
target_methodology:
name: 'QEDD: Quant Evidence-Driven Development'
principles:
- 'Contract first: 새 기능은 spec/schema/golden/owner ledger가 먼저다.'
- 'Python canonical: 모든 숫자 계산은 Python pure function 또는 generated runtime에서 한다.'
- 'GAS thin adapter: GAS는 수집·정규화·내보내기·표시만 한다.'
- 'Manifest-only serving: runtime은 active_artifact_manifest가 가리키는 파일만 읽는다.'
- 'Packet-only LLM: LLM은 final_decision_packet_active를 복사·해설만 한다.'
- 'Shadow before active: 신규 팩터는 검증 표본 누적 전 실행 판단에 사용하지 않는다.'
- 'Live/replay separation: replay는 연구용, live는 승격용이다.'
- 'Provenance or missing: 출처 없는 숫자는 0이 아니라 DATA_MISSING이다.'
- 'Entropy budget: 문서와 파일을 늘리기 전에 중복을 제거한다.'
- 'Risk before alpha: 신규 매수보다 손실 제한·현금 방어·수익 보존이 우선이다.'
forbidden_patterns:
- LLM이 가격·수량·TP·SL·점수를 새로 계산
- GAS에 decision/sizing/exit/risk score 로직 추가
- Temp 구버전 v 파일을 사람이 직접 선택
- 리플레이 성과를 라이브 검증처럼 표현
- 문서 추가로 규칙 충돌을 덮기
- warn_only 결과를 active 승격 근거로 사용
- 결측 필드를 0 또는 평균값으로 무단 대체
- 차단 종목의 산출값을 숨기거나 active 주문처럼 표현
target_architecture:
allowed_dependency_direction: L0 -> L1 -> L2 -> L3 -> L4 -> L5/L6 -> L7 only
layers:
- layer: L0_objective_policy
canonical_paths:
- spec/01_objective_profile.yaml
- spec/risk/*.yaml
- spec/operating_cadence.yaml
owns:
- 목표금액
- 현금 방어선
- D+2 현금 인정
- 리밸런싱 주기
- 위험예산
must_not_own:
- 개별 종목 가격 산출
- 보고서 문장
- layer: L1_data_contract
canonical_paths:
- spec/02_data_contract.yaml
- spec/12_field_dictionary.yaml
- spec/14_raw_workbook_mapping.yaml
- schemas/*.schema.json
owns:
- 필드명
- 단위
- freshness SLA
- provenance
- 결측 정책
must_not_own:
- 투자판단
- 수량 계산
- layer: L2_formula_registry
canonical_paths:
- spec/formulas/domains/*.yaml
- spec/03_formulas/formula_registry.normalized.yaml
owns:
- 공식 ID
- 입력/출력
- 임계값
- golden cases
- owner
- lifecycle
must_not_own:
- 렌더 문구
- GAS 표시 방식
- layer: L3_python_canonical_engine
canonical_paths:
- src/quant_engine
- runtime/python/core/formulas/generated
owns:
- 수치 계산
- 게이트 판정
- 사이징
- 손절/익절
- 팩터 점수
- risk budget cascade
must_not_own:
- 장문 보고서 문장
- raw HTS 화면 처리
- layer: L4_tools_cli
canonical_paths:
- tools/*.py
owns:
- build
- validate
- render
- package
- audit
- migration
must_not_own:
- 핵심 투자 알고리즘 로직
- layer: L5_gas_adapter
canonical_paths:
- gas_*.gs
owns:
- collect
- normalize
- export
- display
must_not_own:
- decision
- sizing
- stop_loss
- take_profit
- risk_score
- layer: L6_runtime_artifacts
canonical_paths:
- runtime/active_artifact_manifest.yaml
- Temp/*.json
- artifacts/canonical
owns:
- 실행 산출물
- active artifact
- shadow ledger
- lineage
must_not_own:
- 소스 규칙
- 새 공식
- layer: L7_llm_packet_renderer
canonical_paths:
- prompts/low_capability_report_renderer.md
- spec/46_low_capability_execution_pack.yaml
owns:
- 복사 전용 설명
- 액션 테이블
- DATA_MISSING 표시
must_not_own:
- 하네스 판정 번복
- 숫자 창작
release_gates:
hard_blockers:
- gate: validate_active_manifest
target: authority_collision_count == 0 and stale_artifact_count == 0
- gate: validate_packet_source_paths
target: missing_source_path_count == 0
- gate: validate_specs
target: VALIDATION OK
- gate: validate_formula_owner
target: formula_owner_coverage_pct == 100
- gate: validate_golden_coverage
target: golden_case_coverage_pct == 100
- gate: validate_gas_thin_adapter
target: gas_business_logic_token_count == 0
- gate: validate_renderer_no_calculation
target: renderer_calculation_count == 0
- gate: validate_number_provenance
target: ungrounded_number_count == 0
- gate: validate_live_replay_separation
target: live_replay_mix_count == 0
- gate: validate_report_packet_sync
target: report_consistency_score == 100
- gate: audit_repository_entropy
target: repository_entropy_gate == PASS
promotion_thresholds:
new_factor_shadow_min_trading_days: 20
new_factor_t20_live_sample_min: 30
prediction_match_rate_min_for_active_review_pct: 58.0
execution_expectancy_min_pct: 0.0
max_drawdown_regression_allowed_pct: 0.0
late_entry_loss_regression_allowed: false
demotion_triggers:
- T+20 live expectancy <= 0 after minimum sample
- late_entry loss cases increase versus baseline
- provenance gap appears in active report
- owner/reviewer missing after registry sync
- GAS starts producing decision fields
- replay metrics mixed into live promotion gate
refactor_roadmap:
- phase_id: P0_FREEZE_AND_TRUTH_LOCK
title: 권위·숫자·렌더링 동결선 확정
target_window: D0~D2
why: 저성능 LLM, GAS, Python, 문서가 서로 다른 파일을 읽으면 수익률보다 먼저 신뢰성이 무너진다.
entry_conditions:
- data_feed.zip 최신본 확보
- runtime/active_artifact_manifest.yaml 존재
- Temp/final_decision_packet_active.json 존재
exit_criteria:
- active_manifest_single_source_pct == 100
- renderer_calculation_count == 0
- direct_temp_reads_outside_manifest == 0
- all numeric fields have provenance or DATA_MISSING marker
todos:
- id: P0-001
action: AGENTS.md 읽기 순서를 runtime/active_artifact_manifest.yaml → manifest alias
→ final_decision_packet_active로만 고정한다.
owner: architect
files:
- AGENTS.md
- runtime/active_artifact_manifest.yaml
method: 'AGENTS.md에는 버전 파일명을 직접 쓰지 말고 alias명만 둔다. 예: final_decision_packet_active.'
done: AGENTS.md와 active_manifest의 canonical_source가 동일하고 validate_active_manifest가
통과한다.
status: completed
- id: P0-002
action: final_decision_packet_active 내부 provenance의 존재하지 않는 source_path를 검사한다.
owner: engineer
files:
- Temp/final_decision_packet_active.json
- tools/validate_packet_source_paths_v1.py
method: packet의 모든 source_path를 루트 기준으로 stat하고 누락 시 release 차단. Temp/active_artifact_manifest_v2.json처럼
실재하지 않는 경로는 runtime/active_artifact_manifest.yaml로 치환하거나 생성 근거를 보존한다.
done: missing_packet_source_path_count == 0
status: completed
- id: P0-003
action: 보고서 렌더러 계산 금지 가드를 release-DAG P0에 둔다.
owner: engineer
files:
- tools/validate_renderer_no_calculation_v1.py
- spec/40_final_decision_packet_contract.yaml
method: +, -, *, /, round, parseFloat, Math.* 등 계산 토큰이 renderer 계층에서 발견되면 실패.
단 문자열 포맷팅은 허용.
done: renderer_calculation_count == 0
status: completed
- id: P0-004
action: 숫자 provenance 강제 규칙을 JSON Schema와 validator 양쪽에 둔다.
owner: data_owner
files:
- schemas/*.schema.json
- tools/validate_number_provenance_strict_v3.py
method: display_value, source_path, json_pointer, formula_id, input_hash, freshness_status
필수화. 누락 숫자는 DATA_MISSING만 허용.
done: ungrounded_number_count == 0
status: completed
- id: P0-005
action: 저성능 LLM용 실행 컨텍스트를 1개 파일로 고정한다.
owner: pm
files:
- Temp/final_context_for_llm_v5.yaml
- spec/46_low_capability_execution_pack.yaml
method: executive, blockers, action_table, shadow_ledger, data_missing, education_notes
순서를 고정하고 모든 숫자는 packet에서 복사한다.
done: validate_low_capability_pack 통과
status: completed
- phase_id: P1_GAS_THIN_ADAPTER_MIGRATION
title: GAS 비즈니스 로직 제거 및 Python canonical 이전
target_window: D3~D10
why: 현재 GAS 파일은 7개뿐이나 gas_data_feed.gs 470KB, gas_data_collect.gs 225KB로 크다. GAS가
판단 로직을 품으면 검증성과 재현성이 급락한다.
exit_criteria:
- gas_decision_token_count == 0
- gas_sizing_token_count == 0
- python_formula_runtime_coverage_pct == 100
- gas_adapter_contract_pass == true
todos:
- id: P1-001
action: gas_*.gs를 collect/normalize/export/display 함수로 분류한다.
owner: gas_engineer
files:
- gas_*.gs
- spec/39_gas_thin_adapter_policy.yaml
method: 함수명, 주석, 토큰을 스캔해 decision/sizing/TP/SL/risk_score 단어가 있는 함수를 migration
후보로 표시한다.
done: gas_business_logic_inventory.yaml 생성
status: completed
- id: P1-002
action: GAS 내 decision, sizing, stop, take_profit, risk score 계산을 Python 공식으로
이전한다.
owner: engineer
files:
- src/quant_engine
- runtime/python/core/formulas/generated
- spec/13_formula_registry.yaml
method: 공식 ID별로 Python pure function을 작성하고 golden case를 먼저 만든 뒤 GAS에서는 결과 JSON만
표시한다.
done: validate_gas_thin_adapter_v1 통과
status: completed
- id: P1-003
action: GAS 함수 호출 arity와 export schema만 남기는 어댑터 계약을 강화한다.
owner: gas_engineer
files:
- tools/validate_gas_call_arity.py
- spec/22_pipeline_runtime_contract.yaml
method: GAS 함수는 raw input → canonical field 변환 → JSON export까지만 허용. 판단 문자열 생성
금지.
done: validate-gas-call-arity 통과
status: completed
- id: P1-004
action: 대형 GAS 파일을 내부 모듈 경계별로 얇게 나누되 외부 배포 파일 수는 유지한다.
owner: architect
files:
- gas_data_feed.gs
- gas_data_collect.gs
method: 원본은 빌드 산출물로 보고 source fragment를 src/gas_adapter_parts 또는 tools/templates에
둔다. 단 사용자 요청 범위가 .gs 유지라면 생성 스크립트로 단일 파일을 빌드한다.
done: single deployed GAS bundle reproduces same hash from parts
status: completed
- id: P1-005
action: GAS와 Python parity test를 추가한다.
owner: qa
files:
- tests/parity
- tools/validate_gas_python_parity_v1.py
method: 동일 input fixture에서 GAS export와 Python ingest 결과의 canonical field hash를
비교한다.
done: gas_python_canonical_hash_match_pct == 100
status: completed
- phase_id: P2_FORMULA_REGISTRY_NORMALIZATION
title: 공식·팩터·필드 소유권 정규화
target_window: D7~D21
why: 공식 레지스트리가 180KB, harness formulas가 166KB 수준이면 사람이 직접 검토하기 어렵다. 공식은 도메인 분할 +
통합 인덱스로 관리해야 한다.
exit_criteria:
- formula_owner_coverage_pct == 100
- formula_golden_case_coverage_pct == 100
- formula_registry_cross_reference_error_count == 0
- deprecated_formula_runtime_read_count == 0
todos:
- id: P2-001
action: spec/13_formula_registry.yaml을 도메인 파일로 분할하고 normalized registry를 자동 생성한다.
owner: architect
files:
- spec/formulas/domains/*.yaml
- spec/03_formulas/formula_registry.normalized.yaml
- tools/build_formula_registry_sync_v1.py
method: risk, entry, exit, sizing, liquidity, fundamental, performance, rendering
도메인별 소유 파일을 만들고 spec/13은 generated index로 둔다.
done: source_registry_hash == normalized_registry_hash_basis
status: completed
- id: P2-002
action: 공식마다 owner, reviewer, lifecycle_state, activation_date, retirement_condition을
필수화한다.
owner: pm
files:
- spec/factor_lifecycle_registry.yaml
- spec/ownership_map.yaml
- governance/authority_matrix.yaml
method: owner 없는 공식은 shadow_only로 강등하고 active 사용 금지.
done: formula_owner_coverage_pct == 100
status: completed
- id: P2-003
action: 공식 단위 golden case를 도메인별로 최소 3개 확보한다.
owner: qa
files:
- tests/golden
- spec/formula_golden_cases_v*.yaml
method: normal, boundary, missing-data 케이스를 각각 생성. 회귀 케이스는 실거래 손실/이익 케이스를 anonymized
fixture로 보존.
done: golden_case_min_per_formula >= 3
status: completed
- id: P2-004
action: 출력 필드 writer owner ledger를 공식 registry와 동기화한다.
owner: engineer
files:
- spec/03_formulas/output_field_owner_ledger.yaml
- tools/validate_output_field_owner_ledger_v1.py
method: 한 필드에 writer가 2개 이상이면 precedence와 merge policy를 명시하지 않는 한 실패.
done: unresolved_writer_collision_count == 0
status: completed
- id: P2-005
action: 결측 데이터 정책을 공식별로 hard_missing, impute_allowed, shadow_only로 구분한다.
owner: data_owner
files:
- spec/02_data_contract.yaml
- spec/28_imputed_data_exposure_contract.yaml
method: 펀더멘털 핵심지표 결측은 confidence cap을 낮추고, 가격·수량 결측은 실행 차단한다.
done: imputed_data_exposure_gate == PASS
status: completed
- phase_id: P3_QUANT_FACTOR_LIFECYCLE_AND_ANTI_LATE_ENTRY
title: 퀀트 팩터 생애주기와 뒷북매수 방지 하네스
target_window: D14~D35
why: 현재 T+5 일치율은 54.76% MONITOR, T+20 라이브 표본은 0건이다. 승격은 성과가 아니라 증거로만 해야 한다.
exit_criteria:
- new_factor_shadow_days >= 20
- operational_t20_sample >= 30 before active
- late_entry_loss_reduction_pct measured
- live_replay_mix_count == 0
todos:
- id: P3-001
action: 모든 신규 팩터를 shadow → evidence → active → retire 4단계로 통제한다.
owner: quant_pm
files:
- spec/43_quant_factor_taxonomy.yaml
- spec/factor_lifecycle_registry.yaml
method: hypothesis, horizon, decay_half_life, input_fields, formula_id, conflict_precedence,
activation_threshold, retirement_condition을 비우면 release 실패.
done: validate_factor_lifecycle_v1 통과
status: completed
- id: P3-002
action: Anti-late-entry score를 entry gate의 1차 차단자로 승격한다.
owner: quant
files:
- spec/strategy/anti_late_entry_pullback_gate_v5.yaml
- src/quant_engine
method: 가격 위치, 거래대금 클라이맥스, gap extension, 20D/60D 이격, 외국인·기관 동시분산, 뉴스 이벤트 이후 추격
여부를 점수화한다.
done: late_entry_block_reason appears in packet for every blocked BUY
status: completed
- id: P3-003
action: 스마트머니·유동성은 방향성보다 지속성을 우선한다.
owner: quant
files:
- spec/strategy/smart_money_liquidity_gate_v1.yaml
method: 1일 급증은 경고 신호, 3/5/20일 누적과 가격 반응을 함께 통과해야 가점. 급등 후 음봉 대량거래는 distribution
risk로 전환.
done: flow_acceleration_without_price_confirmation_penalty active
status: completed
- id: P3-004
action: 펀더멘털 팩터는 장기/중기에서만 가중치를 크게 두고 단타에서는 risk cap으로만 쓴다.
owner: quant
files:
- spec/strategy/fundamental_quality_v3.yaml
- spec/43_quant_factor_taxonomy.yaml
method: ROE, OPM, FCF, 부채, 이익추정 상향은 mid/long alpha에 반영. scalping에서는 부실기업 회피 필터로
제한.
done: horizon_weight_matrix has no cross-horizon leakage
status: completed
- id: P3-005
action: 예측률은 active/passive, decisive/inconclusive, live/replay를 분리해 기록한다.
owner: qa
files:
- spec/44_live_replay_separation.yaml
- Temp/prediction_accuracy_harness_v2.json
method: T+1, T+5, T+20을 별도 집계하고 replay는 live 승격 기준에 사용 금지.
done: live_replay_mix_count == 0
status: completed
- id: P3-006
action: 수익을 지키는 profit-preservation gate를 매수보다 먼저 평가한다.
owner: quant
files:
- spec/profit_preservation_contract.yaml
- spec/exit/dynamic_value_preservation_sell_v3.yaml
method: 보유 종목의 drawdown, thesis break, distribution, cash floor breach를 먼저 처리한
뒤 신규 매수 여지를 계산한다.
done: sell_priority_table always precedes buy table when sell candidates >= 2
status: completed
- phase_id: P4_DATA_COLLECTION_AND_MATURITY
title: 데이터 수집·정합성·성숙도 게이트 강화
target_window: D21~D45
why: 운영 정확도는 모델보다 데이터 정합성에서 먼저 깨진다. 특히 HTS 캡처, D+2 현금, 체결/미체결, 계좌 현금은 실행 판단의 하드
게이트다.
exit_criteria:
- schema_presence_score >= 99
- missing_critical_field_count == 0
- account_snapshot_contract_pass == true
- D_plus_2_cash_rule_tested == true
todos:
- id: P4-001
action: account_snapshot 캡처 파싱 결과를 canonical schema로 강제한다.
owner: data_owner
files:
- spec/15_account_snapshot_contract.yaml
- tools/validate_account_snapshot_contract_v1.py
method: 종목코드, 보유수량, 평균단가, 평가금액, 현금, D+2, 미체결을 필수 필드로 두고 결측 시 실행 차단.
done: account_snapshot_required_field_coverage == 100
status: completed
- id: P4-002
action: D+2 현금은 즉시현금 방어선 충족으로 인정하되 주문 가능 현금과 분리 표시한다.
owner: risk_owner
files:
- spec/risk/portfolio_exposure.yaml
- spec/15_account_snapshot_contract.yaml
method: cash_defense_available = cash_now + D_plus_2_settlement_cash, buy_power_cash
= broker_available_cash. 두 값을 섞지 않는다.
done: cash_defense_rule_unit_test_pass == true
status: completed
- id: P4-003
action: 외부 시장 데이터 freshness SLA를 필드 단위로 둔다.
owner: data_owner
files:
- spec/02_data_contract.yaml
- spec/12_field_dictionary.yaml
method: 가격/거래량은 당일, 재무는 최근 분기, 매크로는 발표일 기준으로 SLA를 명시하고 초과 시 confidence cap.
done: stale_critical_field_count == 0 or execution blocked
status: completed
- id: P4-004
action: raw workbook mapping과 canonical field dictionary를 1:1로 검증한다.
owner: data_engineer
files:
- spec/14_raw_workbook_mapping.yaml
- spec/12_field_dictionary.yaml
method: workbook column alias가 canonical field로 resolve되지 않으면 build 실패.
done: unresolved_raw_mapping_count == 0
status: completed
- id: P4-005
action: 데이터 품질 점수는 보고용이 아니라 gate 입력으로 사용한다.
owner: architect
files:
- spec/data_quality/expectations.yaml
- src/quant_engine
method: missing critical, stale critical, imputed exposure, provenance gap을 execution
readiness의 축으로 반영.
done: data_quality_to_execution_gate_trace exists
status: completed
- phase_id: P5_RELEASE_DAG_AND_REGRESSION_SYSTEM
title: 릴리스 DAG, 회귀 테스트, 롤백 체계 고정
target_window: D30~D60
why: 좋은 알고리즘도 검증 순서가 흔들리면 운영에서는 나쁜 알고리즘이 된다.
exit_criteria:
- release_dag_steps_all_pass == true
- rollback_manifest_ready == true
- mutation_test_min_score >= 80
- performance_regression_alert_active == true
todos:
- id: P5-001
action: release DAG를 P0 hard stop → schema → formula → data → decision → render
→ package 순서로 선형화한다.
owner: devops
files:
- spec/41_release_dag.yaml
- tools/run_release_dag_v3.py
method: 앞 단계 실패 시 뒤 단계는 실행하지 않는다. warn_only는 release 승격에 사용하지 않는다.
done: release_dag_run_v1 has 0 failed steps
status: completed
- id: P5-002
action: 회귀 fixture를 buy/hold/sell/avoid/reject/insufficient_data 별로 유지한다.
owner: qa
files:
- examples/*.yaml
- tests/regression
method: 과거 손실을 만든 케이스를 반드시 fixture화하고, 새 팩터가 이를 악화시키면 실패.
done: regression_case_coverage_by_action == 100
status: completed
- id: P5-003
action: shadow ledger를 active ledger와 분리한다.
owner: qa
files:
- spec/outputs/shadow_ledger_contract.yaml
- Temp/shadow_ledger*.json
method: 차단 종목의 산출값은 숨기지 않되, active order table과 혼입 금지.
done: blocked_value_visibility == true and blocked_order_count == 0
status: completed
- id: P5-004
action: rollback manifest를 매 release마다 생성한다.
owner: devops
files:
- runtime/rollback_manifest_v*.yaml
method: 변경 전후 파일 hash, active alias, migration script, reverse script를 보존한다.
done: rollback_restore_test_pass == true
status: completed
- id: P5-005
action: repository entropy budget을 release gate로 둔다.
owner: architect
files:
- spec/release/repository_entropy_budget.yaml
- tools/audit_repository_entropy_v2.py
method: 파일 수, Temp JSON, package scripts, 문서 라인 수, duplicate family를 예산화한다. 초과
시 기능 추가보다 정리 우선.
done: repository_entropy_gate == PASS
status: completed
- phase_id: P6_REPORTING_AND_LOW_CAPABILITY_LLM_OPERATIONS
title: 저성능 LLM도 동일 결과를 내는 보고 체계
target_window: D45~D75
why: LLM 성능 차이를 줄이는 유일한 방법은 판단을 LLM 밖으로 빼고, LLM에는 순서·복사·금지어만 주는 것이다.
exit_criteria:
- low_capability_packet_contract_pass == true
- report_packet_sync_score == 100
- unsupported_reason_count == 0
- hallucinated_claim_count == 0
todos:
- id: P6-001
action: 보고서 프롬프트를 “복사 전용 렌더러”로 축소한다.
owner: pm
files:
- prompts/low_capability_report_renderer.md
- prompts/weekly_operational_report_master_prompt_v1.md
method: 가격·수량·점수 계산 금지, packet json_pointer 표시, DATA_MISSING 문구 고정.
done: validate_low_capability_report_renderer 통과
status: completed
- id: P6-002
action: action_table은 항상 주문 가능성, 근거, 수량, 가격, TP, SL, 차단사유를 모두 포함한다.
owner: report_owner
files:
- spec/07_output_schema.yaml
- spec/40_final_decision_packet_contract.yaml
method: 차단되어도 산출값은 shadow ledger에 보이고 active 주문 문구는 금지한다.
done: blocked_action_table_completeness_pct == 100
status: completed
- id: P6-003
action: 주간 토/일 리밸런싱, 매월 1/11/21 중간점검을 operating cadence에 고정한다.
owner: pm
files:
- spec/operating_cadence.yaml
method: 리포트 첫 섹션에 오늘이 리밸런싱/중간점검 대상일 때 필수 체크리스트를 삽입한다.
done: cadence_trigger_test_pass == true
status: completed
- id: P6-004
action: 교육 섹션은 판단을 바꾸지 않고 용어와 근거만 설명한다.
owner: report_owner
files:
- spec/46_low_capability_execution_pack.yaml
method: 교육 문장은 action_table 뒤에 배치. 신규 매수 유도성 표현 금지.
done: education_section_has_no_new_numeric_claim == true
status: completed
- id: P6-005
action: 보고서 JSON과 MD의 숫자 동기화를 검증한다.
owner: qa
files:
- tools/validate_report_numeric_consistency_guard_v2.py
- Temp/operational_report.json
- Temp/operational_report.md
method: MD의 숫자가 packet/report JSON provenance와 불일치하면 release 차단.
done: report_consistency_score == 100
status: completed
low_capability_llm_todo_playbook:
purpose: 이 절만 보고도 낮은 성능의 LLM 또는 주니어 운영자가 동일한 판단 패킷/보고서를 만들도록 하는 실행 순서
execution_rule: 순서를 바꾸지 않는다. pass/fail을 각 단계마다 남긴다. 모르는 숫자는 DATA_MISSING으로 둔다.
steps:
- id: LC-001
action: 작업 시작 전 AGENTS.md의 최우선 원칙 5개를 소리내어 체크하듯 확인한다.
method: '읽을 파일: AGENTS.md. 금지: 가격/수량/공식 임의 생성.'
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-002
action: runtime/active_artifact_manifest.yaml을 먼저 열고 canonical_source와 active_aliases를
기록한다.
method: 다른 Temp 파일을 직접 고르지 않는다.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-003
action: canonical_source 파일 존재 여부와 hash/provenance를 검사한다.
method: 없으면 DATA_MISSING — active artifact missing으로 중단.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-004
action: Temp/final_decision_packet_active.json만 보고 executive, blockers, action_table,
shadow_ledger를 만든다.
method: 보고서 본문이나 구버전 v 파일에서 숫자를 복사하지 않는다.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-005
action: spec/13_formula_registry.yaml에서 공식 ID 존재 여부만 확인하고 계산은 하지 않는다.
method: 공식 해석이 애매하면 DATA_MISSING.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-006
action: spec/12_field_dictionary.yaml에서 필드 단위와 별칭을 확인한다.
method: 원/%, 주, 배 등 단위 혼동 금지.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-007
action: schemas 또는 output contract로 필수 섹션 누락 여부를 검사한다.
method: 누락 섹션은 임의 보완하지 않고 missing list에 기록.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-008
action: governance/rules/*.yaml로 금지행동과 ordering rule을 확인한다.
method: 특히 sell candidate >= 2이면 sell priority table 우선.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-009
action: 데이터 결측은 숫자 0으로 대체하지 않는다.
method: 결측 문구는 DATA_MISSING — 하네스 업데이트 필요.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-010
action: D+2 현금은 cash defense에는 포함하고 주문 가능 현금과 분리한다.
method: 두 값의 provenance를 별도로 기록.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-011
action: 신규 매수 판단 전 sell/profit-preservation/cash-floor gate를 먼저 평가한다.
method: 수익 방어가 신규 알파보다 우선.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-012
action: BUY/SELL/HOLD/AVOID/REJECT는 packet의 gate를 그대로 복사한다.
method: LLM이 판정을 업그레이드/다운그레이드하지 않는다.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-013
action: 차단 종목도 산출된 reference price, stop, take-profit, 수량이 있으면 shadow ledger에
표시한다.
method: active order로 오인되는 문구 금지.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-014
action: 투자기간은 scalping/short/mid/long 중 packet 값을 사용한다.
method: 펀더멘털이 좋다는 이유로 단타를 장기로 바꾸지 않는다.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-015
action: 스마트머니·유동성 신호는 가격확인, 지속성, 분산위험을 함께 설명한다.
method: 하루 급증만으로 매수 근거를 만들지 않는다.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-016
action: 펀더멘털 점수는 입력 데이터 품질과 함께 표시한다.
method: 결측 보정값이면 confidence cap을 표기.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-017
action: 매크로 위험 scale이 있으면 신규 매수 수량 제한을 우선 반영한다.
method: 수량 계산은 하네스 값만 사용.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-018
action: 예측 성과는 T+1/T+5/T+20과 live/replay를 분리해 표기한다.
method: replay 성과를 live 검증처럼 표현하지 않는다.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-019
action: T+20 live sample이 activation 기준 미달이면 active 승격 금지라고 쓴다.
method: 기대수익률을 확정형으로 쓰지 않는다.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-020
action: 보고서 첫 섹션에는 portfolio health, hard blockers, 오늘 해야 할 일 TOP3를 둔다.
method: 교육 내용보다 실행 차단 사유가 앞선다.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-021
action: 토요일/일요일이면 주간 리밸런싱 체크리스트를 반드시 삽입한다.
method: 목표 비중, cash floor, concentration, sell priority 확인.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-022
action: 매월 1/11/21이면 중간점검 체크리스트를 반드시 삽입한다.
method: 성과/리스크/데이터/하네스 drift 확인.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-023
action: 주문 문장은 단일 조건으로 짧게 쓴다.
method: 다중 조건 접속사 기반 주문문 금지.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-024
action: tick normalization 결과가 없으면 가격 주문을 active로 쓰지 않는다.
method: 가격 단위 오류는 즉시 차단.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-025
action: TP stale이면 TP 값을 삭제하거나 stale로 표시한다.
method: 오래된 익절가를 최신처럼 표현하지 않는다.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-026
action: 현금 부족이면 cash recovery optimizer의 우선순위만 따른다.
method: 좋아 보이는 종목을 임의 매도하지 않는다.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-027
action: 손절은 절대손실, 상대손실, thesis break, distribution을 구분한다.
method: 감정적 손절/존버 표현 금지.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-028
action: 목표금액 5억 대비 gap은 packet의 total_asset_krw와 goal_krw만으로 표시한다.
method: 목표 달성률을 새로 계산하지 말고 제공값이 있을 때만 사용.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-029
action: 모든 숫자 옆에는 가능한 경우 formula_id 또는 source_path를 둔다.
method: 출처 없는 숫자는 삭제.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-030
action: 섹터/종목 위성 추천은 하네스 후보가 있을 때만 표시한다.
method: 후보가 없으면 DATA_MISSING.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-031
action: 출력 마지막에는 미해결 데이터, 다음 하네스 업데이트, release gate 상태를 둔다.
method: 사용자 행동과 엔진 행동을 분리.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-032
action: 리팩토링 변경은 change_request_template으로 먼저 작성한다.
method: 직접 spec 수정 금지.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-033
action: 새 공식은 contract → schema → golden case → Python → GAS adapter → renderer
순서로만 도입한다.
method: 역순 개발 금지.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-034
action: 테스트 실패는 문구로 완화하지 않는다.
method: failed는 failed로 보고한다.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-035
action: 중복 파일을 발견하면 active/canonical/archive 중 하나로 분류한다.
method: 최신 v 파일을 사람이 추측하지 않는다.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
- id: LC-036
action: 최종 산출물은 하나의 YAML TODO와 필요한 최소 파일 변경 목록으로 끝낸다.
method: 문서 증식 금지.
acceptance: 작업 로그에 pass/fail과 근거 파일을 1줄로 남긴다.
quant_engine_algorithm_policy:
strategy_stack_order:
- cash_floor_and_settlement_defense
- hard_stop_and_profit_preservation
- market_regime_and_macro_scale
- data_quality_and_maturity_gate
- horizon_routing
- anti_late_entry_gate
- fundamental_quality_gate
- smart_money_liquidity_gate
- position_sizing_and_integer_lot
- execution_method_ladder
- shadow_ledger_and_report_rendering
factor_policy:
scalping: 유동성, 호가, 변동성, 추격매수 방지, 당일 이벤트 리스크 중심. 펀더멘털은 부실 회피 필터로 제한.
short: 가격 모멘텀, 거래대금 지속성, 수급 누적, 리스크 캡 중심. 과열/분산위험 패널티 강함.
mid: 펀더멘털 개선, 이익추정, 섹터 상대강도, 스마트머니 지속성의 균형.
long: ROE/FCF/부채/시장지위/밸류에이션 안전마진 중심. 단기 수급은 진입 타이밍 보정용.
anti_late_entry_formula_components:
- price_extension_vs_20d_60d_ma
- gap_up_after_news_event
- volume_climax_zscore
- upper_tail_or_long_red_candle_after_climax
- foreign_institution_distribution_3d_5d
- relative_strength_deceleration
- risk_reward_after_stop_distance
profit_preservation_components:
- absolute_floor_stop
- relative_underperformance_stop
- thesis_break_detector
- distribution_sell_detector
- cash_floor_recovery_optimizer
- breakeven_ratchet
- trailing_take_profit
file_diet_policy:
rules:
- AGENTS.md는 헌법과 인덱스만 유지하고 장문 규칙은 governance/rules 또는 spec로 이동한다.
- spec/13_formula_registry.yaml은 사람이 편집하는 원본이 아니라 generated normalized index로 전환한다.
- Temp는 release마다 active/canonical/archive 정책으로 청소한다.
- suggest는 채택/폐기 상태를 명시하고 runtime에서 절대 읽지 않는다.
- tools는 CLI wrapper, src/quant_engine은 business logic으로 경계를 고정한다.
- package scripts는 public workflow만 남기고 내부 하위 단계는 release DAG node로 관리한다.
budgets:
max_total_files: 2000
max_package_scripts: 50
max_temp_json_files: 50
max_duplicate_version_families_ge_3: 0
max_agents_md_lines: 180
max_single_human_authored_yaml_lines: 1500
max_gas_business_logic_tokens: 0
cleanup_order:
- Temp stale artifacts
- suggest superseded plans
- tools duplicate build_vN scripts
- spec duplicate golden case versions
- large generated files moved to dist/runtime with manifest
definition_of_done:
minimum_done_for_refactor_v1:
- active manifest가 단일 권위로 동작한다.
- final packet source_path가 모두 실제 파일로 해소된다.
- LLM renderer는 계산을 하지 않는다.
- GAS는 판단 로직을 보유하지 않는다.
- 공식 owner/reviewer/lifecycle이 100% 채워진다.
- golden case와 regression fixture가 release gate에 연결된다.
- 신규 팩터는 shadow-before-active 원칙을 통과한다.
- 보고서 숫자는 packet provenance와 100% 동기화된다.
- 저성능 LLM용 execution pack만으로 동일 액션 테이블을 재현한다.
not_done_even_if_tests_pass:
- T+20 live sample이 부족한데 active 수익성 주장 사용
- GAS에 계산 로직 잔존
- source_path 실재성 검증 부재
- 중복 v 파일을 사람이 추측해 선택
- owner 없는 공식이 active output에 관여
recommended_next_7_days:
- day: D0
tasks:
- validate_packet_source_paths_v1 추가
- AGENTS.md manifest-only 문구 보강
- renderer no-calc gate release DAG 연결
- day: D1
tasks:
- GAS business logic inventory 생성
- gas_data_feed.gs 판단 토큰 위치 목록화
- migration backlog 작성
- day: D2
tasks:
- formula owner coverage validator 추가
- owner 없는 공식 shadow_only 강등 정책 적용
- day: D3
tasks:
- spec/13 formula registry 도메인 분할 설계
- normalized registry builder 확정
- day: D4
tasks:
- anti-late-entry golden cases 추가
- 과거 뒷북매수/설거지 사례 fixture화
- day: D5
tasks:
- low capability execution pack v5 생성
- 보고서와 packet 숫자 동기화 검증
- day: D6-D7
tasks:
- release DAG 전체 strict 실행
- rollback manifest 생성
- entropy audit와 cleanup plan 확정
change_request_template:
required_fields:
- cr_id
- title
- problem
- hypothesis
- affected_layers
- files_to_change
- new_or_changed_formula_ids
- data_fields
- golden_cases
- shadow_plan
- rollback_plan
- release_gates
- owner
- reviewer
approval_rule: P0/P1 변경은 owner와 reviewer가 모두 있어야 active 반영 가능