schema_version: qedd_refactor_todo.v1
title: 퀀트투자 엔진 구조적 리팩토링 및 저성능 LLM 실행 TODO
generated_at_kst: '2026-06-07T14:27:31+09:00'
basis:
  uploaded_zip: /mnt/data/data_feed.zip
  required_authority: data_feed/AGENTS.md
  read_order_from_agents:
  - runtime/active_artifact_manifest.yaml
  - Temp/final_decision_packet_active.json
  - spec/13_formula_registry.yaml
  - spec/12_field_dictionary.yaml
  - schemas/*.schema.json
  - governance/rules/*.yaml
  - spec/*.yaml
  hard_constraints:
  - 가격, 수량, TP, SL, 점수는 등록 공식과 하네스 산출값만 사용한다.
  - LLM은 계산기가 아니라 renderer이며 하네스 판정을 번복하지 않는다.
  - GAS는 thin adapter, Python/src는 canonical implementation이다.
  - Temp는 실행 산출물이며 직접 편집하지 않는다.
  - 문서/규칙/공식/스키마는 변경요청과 golden case 없이 활성화하지 않는다.
repository_inventory_observed:
  total_files_in_uploaded_zip: 1364
  top_directory_counts:
    src: 328
    tools: 324
    schemas: 161
    tests: 159
    runtime: 154
    spec: 114
    artifacts: 40
    governance: 24
    Temp: 13
    prompts: 9
    docs: 8
    examples: 8
    suggest: 7
    dist: 2
    AGENTS.md: 1
    gas_apex_alpha_watch.gs: 1
    gas_apex_runtime_core.gs: 1
    gas_data_collect.gs: 1
    gas_data_feed.gs: 1
    gas_harness_rows.gs: 1
    gas_lib.gs: 1
    gas_report.gs: 1
    GatherTradingData.json: 1
    package.json: 1
    README.md: 1
    RetirementAssetPortfolio.yaml: 1
    RetirementAssetPortfolioReportTemplate.yaml: 1
  extension_counts:
    .py: 798
    .json: 364
    .yaml: 150
    .md: 38
    .gs: 7
    .ps1: 4
    .jsonl: 2
    .js: 1
  package_script_count: 202
  package_scripts_by_family:
    build: 92
    validate: 63
    prepare: 7
    run: 6
    apply: 3
    full: 3
    render: 2
    measure: 2
    daily: 2
    compute: 2
    inject: 2
    start: 1
    check: 1
    score: 1
    ingest: 1
    update: 1
    release: 1
    convert: 1
    yolo: 1
    profile: 1
    import: 1
    audit: 1
    enrich: 1
    lint: 1
    ops:validate: 1
    ops:render: 1
    ops:release: 1
    ops:package: 1
    ops:audit: 1
  formula_registry_formula_count: 149
  formula_registry_size_bytes: 180041
  release_dag_steps: 14
  release_dag_failed_steps: 0
  tools_src_same_basename_count: 21
  tools_src_same_basename_examples:
  - __init__.py
  - apply_engine_upgrade_v4.py
  - apply_engine_upgrade_v7.py
  - compile_formula_registry_v1.py
  - compute_formula_outputs.py
  - convert_xlsx_to_json.py
  - generate_models_from_schema.py
  - import_etf_nav_manual.py
  - inject_computed_harness.py
  - lib_trading_calendar.py
  - measure_harness_coverage.py
  - measure_yaml_gs_ps_coverage.py
  - orchestration_harness_v1.py
  - pipeline_runtime_anomaly_lib_v1.py
  - prepare_upload_zip.py
  - refactor_master_helpers.py
  - run_engine_audit_golden_cases_v1.py
  - run_formula_golden_cases_v2.py
  - run_integration_test_v1.py
  - update_proposal_evaluation_history.py
  - v7_hardening_common.py
  active_manifest_missing_packaged_refs: &id001
  - Temp/canonical_artifact_resolver_v1.json
  - Temp/final_execution_decision_v2.json
  - Temp/prediction_accuracy_harness_v2.json
  - Temp/single_truth_ledger_v2.json
  - Temp/smart_cash_recovery_v7.json
  current_hardening_snapshot:
    overall_hardening_score: 68.22
    truth_hardening_score: 68.22
    readiness_gate: WATCH_PENDING_SAMPLE
    prediction_match_rate_pct: 45.68
    algorithm_guidance_proof: 56.4
    operational_t20_count: 0.0
    value_damage_pct_avg: 12.5
    readiness_reasons: &id002
    - DATA_INTEGRITY_LOCK_NOT_PASS_100
    - OPERATIONAL_T20_SAMPLE_LT_30
    - OPERATIONAL_T20_PASS_LT_60
    - EXPECTANCY_LE_0_1
    - WIN_RATE_LT_45
    - PREDICTION_MATCH_LT_60
    - VALUE_DAMAGE_GT_10
diagnosis:
  senior_assessment: 현재 엔진은 방어 규율과 검증 골격은 좋지만, 공식/스크립트/산출물 버전이 계속 증식하는 구조다. 다음 단계는
    새 지표 추가가 아니라, 권위 경로, 변경 수명주기, DAG, 패키징, 저성능 LLM 실행팩을 하나의 결정론적 생산 시스템으로 고정하는 것이다.
  strengths:
  - AGENTS.md가 운영 인덱스로 축소되어 있고 세부 규칙을 governance/rules 및 spec으로 위임한다.
  - release_dag_run_v1 기준 14개 릴리즈 게이트가 모두 returncode 0으로 통과한다.
  - number provenance, low capability pack, golden coverage, GAS thin adapter, no
    replay/live mix 검증이 릴리즈 게이트에 포함되어 있다.
  - spec/43_quant_factor_taxonomy.yaml에 factor lifecycle 필드가 이미 정의되어 있다.
  - spec/46_low_capability_execution_pack.yaml에 저성능 LLM용 고정 섹션 계약이 이미 존재한다.
  critical_gaps:
  - gap: active_artifact_manifest가 패키지에 없는 Temp 산출물을 참조한다.
    evidence: *id001
    risk: 검증 환경에서는 PASS라도 업로드 패키지 소비자는 참조 불능이 발생할 수 있다.
    fix: validate_packaged_artifact_references_v1.py를 P0 게이트로 승격한다.
  - gap: package.json 스크립트가 202개로 orchestration entropy가 높다.
    evidence: build 92개, validate 63개, 긴 chained script 다수
    risk: 신규 기능 추가 시 실행 순서와 중복 검증이 파편화된다.
    fix: release_dag.yaml 중심으로 스크립트를 8~12개 top-level entrypoint로 축소한다.
  - gap: tools와 src/quant_engine 간 동일 basename Python 파일이 21개 존재한다.
    evidence:
    - __init__.py
    - apply_engine_upgrade_v4.py
    - apply_engine_upgrade_v7.py
    - compile_formula_registry_v1.py
    - compute_formula_outputs.py
    - convert_xlsx_to_json.py
    - generate_models_from_schema.py
    - import_etf_nav_manual.py
    - inject_computed_harness.py
    - lib_trading_calendar.py
    risk: canonical logic이 wrapper와 runtime 사이에서 갈라질 수 있다.
    fix: src/quant_engine만 business logic을 소유하고 tools는 import-only CLI로 얇게 만든다.
  - gap: formula registry가 153KB 단일 파일에 149개 공식으로 비대하다.
    evidence: spec/13_formula_registry.yaml
    risk: 저성능 LLM과 사람이 모두 충돌/중복/권위 경로를 추적하기 어렵다.
    fix: domain shard를 원본으로 두고 normalized registry는 생성물로 전환한다.
  - gap: 성과 활성화 조건은 아직 미달이다.
    evidence: *id002
    risk: 실전 활성화 전환이 서사에 의해 앞당겨질 수 있다.
    fix: operational T+20 sample, expectancy, win-rate, prediction 기준을 hard gate로
      유지한다.
target_methodology:
  name: QEDD — Quant Engine Deterministic Development
  one_sentence: 투자 아이디어를 곧바로 코드로 만들지 말고, thesis → contract → schema → golden case
    → canonical implementation → harness → shadow ledger → active release → retirement
    순서로만 승격한다.
  non_negotiable_principles:
  - 'Single Source of Truth: spec YAML이 계약, src/quant_engine이 구현, Temp가 산출물, report가
    렌더다.'
  - 'Formula First, Narrative Last: 수치 판단은 등록 공식과 하네스가 만들고 LLM은 복사/정리만 한다.'
  - 'No Silent Override: 수동 보정, 미등록 공식, 추정값은 모두 차단한다.'
  - 'Shadow Before Active: 새 팩터/게이트는 최소 표본과 성과 조건을 만족하기 전까지 주문 판단에 반영하지 않는다.'
  - 'One Owner Per Output Field: 모든 출력 필드는 owner formula와 source path가 하나여야 한다.'
  - 'Evidence-Labeled Performance: live, replay, imputed, manual 입력을 절대 섞지 않는다.'
  - 'Repository Entropy Budget: 파일/문서/스크립트/버전 산출물은 예산을 초과하면 기능 추가를 중단하고 정리한다.'
  activation_lifecycle:
  - state: idea
    allowed_output: proposal only
    entry: 투자 가설 1문장과 실패 조건 작성
    exit: change_request 생성
  - state: contract
    allowed_output: spec only
    entry: input/output/missing_policy/owner/golden_case 정의
    exit: schema와 field dictionary 통과
  - state: shadow
    allowed_output: shadow_ledger only
    entry: Python canonical 구현과 golden parity PASS
    exit: live 표본 최소 30개와 uplift/손상 기준 통과
  - state: active
    allowed_output: decision packet
    entry: release gate PASS 및 authority collision 0
    exit: retirement condition 발생 또는 성과 하락
  - state: retire
    allowed_output: archive only
    entry: edge 소멸, 충돌 과다, stale, 대체 공식 존재
    exit: archive manifest와 migration hash 기록
target_architecture:
  directory_contract:
    AGENTS.md: 운영 헌법과 읽기 순서만 보유한다. 200라인 이하 유지.
    spec/: 모든 공식, 데이터 계약, decision flow, risk policy, factor taxonomy의 유일한 권위.
    spec/formulas/domains/: entry, exit, risk, portfolio, cash, fundamental, smart_money,
      macro, reporting shard를 둔다.
    src/quant_engine/: canonical Python package. business logic은 여기만 허용한다.
    tools/: CLI wrapper. argparse, file I/O, src import 호출만 허용한다.
    gas_*.gs: Google Sheet/Apps Script thin adapter. 계산 로직 금지.
    schemas/: JSON/YAML schema와 생성 모델의 권위.
    tests/golden/: 공식별 golden input/output. 새 공식의 필수 통과 조건.
    tests/parity/: Python-GAS, schema-model parity, renderer-packet sync.
    runtime/: active manifest, baseline manifest, lineage ledger.
    Temp/: 실행 산출물. 직접 편집 금지, 패키징 전 참조 존재성 검증 필수.
    artifacts/canonical/: 현재 active canonical snapshot만 둔다.
    artifacts/archive/: retired/stale/versioned artifact만 둔다.
    docs/: ADR, doctrine, runbook만 유지. 중복 설명 금지.
    prompts/: renderer prompt와 audit prompt만 보유. 계산 지시 금지.
  canonical_dataflow:
  - raw workbook / market data
  - 02_data_contract + 12_field_dictionary validation
  - feature build in src/quant_engine/features
  - formula execution in src/quant_engine/formulas
  - decision graph in spec/routing/decision_graph.yaml
  - risk/execution gates
  - final_decision_packet_active.json
  - final_context_for_llm.yaml
  - operational_report.json/md renderer
  authority_matrix_required_fields:
  - output_field
  - owner_formula_id
  - source_spec
  - source_schema
  - runtime_artifact
  - json_pointer
  - provenance_required
  - llm_mutable:false
refactor_todo:
- phase: P0_safety_freeze_and_baseline
  objective: 리팩토링 중 투자 판단 산출물이 흔들리지 않게 현재 active 기준선을 고정한다.
  priority: highest
  tasks:
  - id: P0-001
    action: 현재 zip의 sha256, 파일 목록, extension count, package script count, active artifact
      manifest, release_dag_run을 runtime/refactor_baseline_v1.yaml로 기록한다.
    method: python tools/audit_repository_entropy_v2.py --out runtime/refactor_baseline_v1.yaml
    acceptance: baseline 파일에 total_files, package_script_count, formula_registry_hash,
      active_manifest_hash가 존재한다.
    status: completed
  - id: P0-002
    action: active_artifact_manifest의 모든 참조가 업로드 패키지 안에 존재하는지 검증한다.
    method: '새 validator: tools/validate_packaged_artifact_references_v1.py --manifest
      runtime/active_artifact_manifest.yaml --root . --strict'
    acceptance: missing_ref_count == 0. 현재 관측 missing refs는 Temp/canonical_artifact_resolver_v1.json,
      Temp/final_execution_decision_v2.json, Temp/prediction_accuracy_harness_v2.json,
      Temp/single_truth_ledger_v2.json, Temp/smart_cash_recovery_v7.json 이므로 반드시 해소한다.
    status: completed
  - id: P0-003
    action: 리팩토링 기간 중 active decision packet 생성 로직을 freeze하고 신규 팩터는 shadow 상태로만 허용한다.
    method: governance/change_requests/0002-refactor-freeze.yaml 생성 후 rule_lifecycle
      transition_policy에 freeze window 기록
    acceptance: release gate가 freeze 상태에서 새 active formula 추가를 차단한다.
    status: completed
  - id: P0-004
    action: 보고서 렌더러 계산 0 원칙을 재검증한다.
    method: python tools/validate_renderer_no_calculation_v1.py && python tools/validate_number_provenance_strict_v3.py
      --ledger Temp/number_provenance_ledger_v4.json --report Temp/operational_report.md
    acceptance: renderer_calculation_count == 0, number_provenance_coverage_pct ==
      100
    status: completed
- phase: P1_single_source_of_truth_split
  objective: 거대 spec과 중복 권위 파일을 domain shard + generated normalized registry 구조로 전환한다.
  tasks:
  - id: P1-001
    action: spec/13_formula_registry.yaml를 직접 편집 금지 generated file로 강등하고, 원본 shard를
      spec/formulas/domains/*.yaml로 분리한다.
    method: entry, exit, risk, cash, portfolio, fundamental, smart_money, macro, reporting,
      data_quality, execution 도메인으로 분리
    acceptance: spec/13_formula_registry.yaml 상단에 generated_from 목록과 source_hashes가
      기록된다.
    status: completed
  - id: P1-002
    action: 각 formula에 owner, lifecycle_state, input_fields, output_fields, missing_policy,
      golden_cases, activation_threshold, retirement_condition을 필수화한다.
    method: schemas/formula_contract.schema.json 추가 또는 강화
    acceptance: python tools/validate_formula_contract_completeness_v1.py 결과 missing_required_field_count
      == 0
    status: completed
  - id: P1-003
    action: output_field_owner_ledger를 field_dictionary와 교차검증한다.
    method: python tools/validate_output_owner_uniqueness_v1.py --ledger spec/03_formulas/output_field_owner_ledger.yaml
      --fields spec/12_field_dictionary.yaml
    acceptance: owned_output_field_pct == 100, authority_collision_count == 0
    status: completed
  - id: P1-004
    action: spec/strategy/*의 버전 중복 파일은 active/latest/archive 상태를 명시한다.
    method: governance/rule_lifecycle.yaml과 artifacts/canonical_manifest.yaml에 매핑
    acceptance: 동일 base formula의 active_count_per_formula == 1
    status: completed
- phase: P2_release_dag_and_script_diet
  objective: package.json을 명령 저장소가 아니라 최소 엔트리포인트로 축소한다.
  tasks:
  - id: P2-001
    action: package.json scripts를 ops:prepare, ops:validate, ops:build, ops:render,
      ops:release, ops:package, ops:audit, ops:clean, ops:dev 9개로 축소한다.
    method: 모든 세부 단계는 spec/41_release_dag.yaml과 tools/run_release_dag_v2.py에서 읽는다.
    acceptance: package_script_count <= 12
    status: completed
  - id: P2-002
    action: release DAG를 YAML에 완전히 선언한다.
    method: 각 node에 id, command, inputs, outputs, depends_on, timeout_sec, cache_key,
      strict, artifact_policy 기재
    acceptance: python tools/validate_release_dag_v2.py --dag spec/41_release_dag.yaml
      --strict PASS
    status: completed
  - id: P2-003
    action: 긴 chained script를 모두 DAG node로 이전한다.
    method: render-report-json처럼 18단계 이상 연결된 script 금지
    acceptance: package.json 내 && count == 0 또는 top-level orchestration wrapper에만
      허용
    status: completed
  - id: P2-004
    action: DAG 산출물의 input_hash/output_hash/elapsed_sec/gate를 lineage_events.jsonl에
      기록한다.
    method: tools/run_release_dag_v2.py가 공통 기록 담당
    acceptance: 각 node 실행 후 runtime/lineage_events.jsonl append 완료
    status: completed
- phase: P3_python_canonical_and_tools_wrapper_cleanup
  objective: Python 구현 권위를 src/quant_engine으로 단일화하고 tools는 얇은 wrapper로 만든다.
  tasks:
  - id: P3-001
    action: tools와 src/quant_engine에 같은 basename으로 존재하는 21개 파일을 audit한다.
    method: 각 파일을 canonical, wrapper, obsolete 중 하나로 분류
    acceptance: tools_src_duplicate_count == 0 또는 wrapper_only_count == duplicate_count
    status: completed
  - id: P3-002
    action: 모든 tools/build_*.py와 tools/validate_*.py에서 business logic을 src/quant_engine/*로
      이전한다.
    method: tools 파일은 parse_args, load, call, write, exit_code만 보유
    acceptance: python tools/validate_tools_are_thin_wrappers_v1.py PASS
    status: completed
  - id: P3-003
    action: runtime/python/core/formulas/generated와 src/quant_engine/models/generated의
      생성 책임을 명확히 분리한다.
    method: generated artifact에는 DO_NOT_EDIT header, source_schema_hash, generator_version
      삽입
    acceptance: schema/model parity validator PASS, generated drift count == 0
    status: completed
  - id: P3-004
    action: 공식별 구현 위치 registry를 생성한다.
    method: Temp/formula_runtime_registry_v2.json에 formula_id -> python_module ->
      gas_adapter -> golden_cases -> owner 기록
    acceptance: declared_runtime_count == formula_total, unmapped_formula_count ==
      0
    status: completed
- phase: P4_data_integrity_and_provenance_closure
  objective: 데이터 정합성, 참조 존재성, 숫자 provenance를 닫힌 시스템으로 만든다.
  tasks:
  - id: P4-001
    action: 모든 output number에 source_path, json_pointer, formula_id, input_hash, freshness_status를
      강제한다.
    method: schemas/number_provenance.schema.json + validate_number_provenance_strict_v4
    acceptance: unproven_report_number_count == 0, stale_critical_number_count ==
      0
    status: completed
  - id: P4-002
    action: D+2 현금은 즉시현금 방어선 충족으로 간주하는 정책을 spec/risk/portfolio_exposure.yaml와 cash
      formula shard에 명시한다.
    method: cash_available_for_defense_krw = cash_krw + d_plus_2_cash_krw; settlement_gap_risk
      별도 표기
    acceptance: cash_floor gate가 D+2 포함/제외 값을 둘 다 출력하고, 방어선 판정은 포함값만 사용
    status: completed
  - id: P4-003
    action: imputed/manual/stale/live/replay 데이터 라벨을 필드 단위로 강제한다.
    method: spec/02_data_contract.yaml에 data_lineage enum 추가
    acceptance: live_replay_mix_count == 0, unlabeled_data_lineage_count == 0
    status: completed
  - id: P4-004
    action: 업로드 패키지 whitelist를 runtime manifest와 동기화한다.
    method: tools/prepare_upload_zip.py가 active_manifest refs를 자동 include
    acceptance: packaged_ref_existence_pct == 100
    status: completed
- phase: P5_quant_algorithm_harness_hardening
  objective: 뒷북 매수/설거지 매도를 줄이도록 팩터 수명주기와 충돌 해소를 공식화한다.
  tasks:
  - id: P5-001
    action: '팩터는 horizon별로 분리한다: scalping, short, mid, long. 서로 다른 horizon 신호를 하나의
      점수로 무리하게 합산하지 않는다.'
    method: spec/43_quant_factor_taxonomy.yaml의 required_lifecycle_fields를 모든 strategy
      formula에 적용
    acceptance: factor_horizon_coverage_pct == 100
    status: completed
  - id: P5-002
    action: 진입 게이트는 leading signal과 confirmation signal을 분리한다.
    method: entry_lead_score, pullback_quality, breakout_quality, liquidity_acceleration,
      distribution_pressure, valuation_heat를 별도 출력
    acceptance: late_entry_block_rate와 missed_winner_rate를 동시에 추적한다.
    status: completed
  - id: P5-003
    action: 스마트머니/유동성은 가격 상승 후 거래대금만 보지 말고 선행 누적/분산을 분리한다.
    method: accumulation_score, distribution_risk_score, flow_acceleration, foreign_institution_sync,
      volume_price_divergence를 독립 팩터화
    acceptance: distribution_risk_score >= threshold이면 신규 매수는 shadow-only 또는 half-size로
      제한
    status: completed
  - id: P5-004
    action: 펀더멘털은 horizon gate로 쓰고 단기 타이밍 점수와 충돌 시 우선순위를 명확히 한다.
    method: quality_growth_score, earnings_revision_score, cashflow_quality, balance_sheet_risk,
      valuation_stretch를 mid/long horizon에 배치
    acceptance: fundamental_good_but_entry_bad이면 BUY가 아니라 WATCH_PULLBACK이 출력된다.
    status: completed
  - id: P5-005
    action: 성과 피드백은 replay와 live를 분리하고 active 승격 기준을 hard-code한다.
    method: operational_t20_count >= 30, prediction_match_rate_pct >= 60, execution_expectancy_pct
      > 0.1, execution_win_rate_pct >= 45, value_damage_pct <= 10 모두 필요
    acceptance: 하나라도 미달이면 readiness_gate != ACTIVE
    status: completed
  - id: P5-006
    action: 매도 엔진은 손실방어, 수익보존, 현금확보, thesis break를 분리한다.
    method: sell_reason enum = ABS_FLOOR, REL_UNDERPERFORM, PROFIT_RATCHET, CASH_RAISE,
      THESIS_BREAK, DATA_RISK
    acceptance: sell candidate 2개 이상이면 sell_priority_table이 먼저 출력된다.
    status: completed
  - id: P5-007
    action: 목표금액 5억과 현재 총자산의 goal gap을 risk budget과 position size에 연결한다.
    method: goal_gap_pct, required_return_to_goal, max_drawdown_budget, cash_floor_defense를
      final_decision_packet에 포함
    acceptance: 목표 추격 때문에 손절/현금 방어선이 완화되지 않는다.
    status: completed
- phase: P6_low_capability_llm_execution_pack
  objective: 저성능 LLM도 같은 결과를 내도록 final_context와 response contract를 폐쇄형으로 만든다.
  tasks:
  - id: P6-001
    action: final_context_for_llm.yaml을 report 생성의 유일 입력으로 만든다.
    method: required_sections = executive, blockers, action_table, shadow_ledger,
      data_missing, education_notes 유지
    acceptance: context_required_field_coverage_pct == 100, ambiguous_instruction_count
      == 0, llm_free_numeric_field_count == 0
    status: completed
  - id: P6-002
    action: LLM용 절차를 7단계로 고정한다.
    method: 1 읽기순서 확인 → 2 blockers 출력 → 3 sell priority → 4 buy/watch/avoid → 5 cash
      defense → 6 data_missing → 7 education notes
    acceptance: section_order_violation_count == 0
    status: completed
  - id: P6-003
    action: LLM이 수치를 생성할 수 있는 문장을 prompt에서 제거한다.
    method: '금지어: 계산해라, 추정해라, 적정가를 산출해라, 임의 보정해라. 허용어: 복사해라, 표시해라, DATA_MISSING으로
      표기해라'
    acceptance: validate_llm_prompt_no_numeric_generation_v1 PASS
    status: completed
  - id: P6-004
    action: report_renderer_prompt.md를 compact renderer와 audit renderer로 분리한다.
    method: 운영보고서는 compact, 검증보고서는 audit 사용
    acceptance: report_renderer가 packet 외부 숫자를 참조하지 않는다.
    status: completed
- phase: P7_gas_thin_adapter_and_sheet_contract
  objective: GAS는 수집/시트 I/O만 하고 판단 로직은 Python canonical과 동기화한다.
  tasks:
  - id: P7-001
    action: gas_*.gs에서 공식 계산 로직을 탐지해 제거한다.
    method: GAS 함수는 fetch, normalize, writeHarnessRows, readSheetRange, callAdapter만
      허용
    acceptance: python tools/validate_gas_thin_adapter_v2.py PASS
    status: completed
  - id: P7-002
    action: GAS-Python parity golden cases를 핵심 adapter별로 유지한다.
    method: tests/parity/gas_python/*.yaml 생성
    acceptance: node tools/run_gas_golden_parity.js PASS
    status: completed
  - id: P7-003
    action: account_snapshot contract를 별도 I/O 계약으로 고정한다.
    method: spec/15_account_snapshot_contract.yaml 기준으로 capture_parse_prompt와 schema
      검증 연결
    acceptance: 붙여넣기 가능한 TSV/CSV 출력 필드 순서가 매번 동일하다.
    status: completed
- phase: P8_documentation_and_file_diet
  objective: 문서가 많아져서 판단이 흐려지는 것을 방지한다.
  tasks:
  - id: P8-001
    action: 문서는 AGENTS.md, doctrine.md, runbook.md, ADR, spec만 남기고 중복 설명은 제거한다.
    method: docs/ 중복 문단 hash audit
    acceptance: duplicate_doc_block_count == 0
    status: completed
  - id: P8-002
    action: AGENTS.md는 운영 인덱스만 유지하고 상세 규칙은 governance/rules 및 spec로 이동한다.
    method: validate_agents_shrink_v1 기준 강화
    acceptance: AGENTS line count <= 220, forbidden_long_rule_block_count == 0
    status: completed
  - id: P8-003
    action: archive 정책을 강화한다.
    method: artifacts/archive/YYYY-MM-DD 이하에만 구버전 저장, canonical에는 active 최신 1개만 허용
    acceptance: canonical_duplicate_version_count == 0
    status: completed
  - id: P8-004
    action: repository entropy budget을 실제 패키징 기준으로 재산정한다.
    method: spec/release/repository_entropy_budget.yaml에 target과 hard_limit 분리
    acceptance: file_count <= target 또는 budget_exception_change_request 존재
    status: completed
- phase: P9_release_and_rollback_control
  objective: 변경이 잘못되면 즉시 이전 active packet으로 되돌릴 수 있게 한다.
  tasks:
  - id: P9-001
    action: release train을 daily, weekly, emergency 세 가지로 분리한다.
    method: spec/release/release_train.yaml에 allowed changes와 gates 정의
    acceptance: weekly release만 active formula 승격 가능
    status: completed
  - id: P9-002
    action: rollback manifest를 생성한다.
    method: runtime/rollback_manifest_v1.yaml에 previous_active_packet, previous_manifest,
      artifact hashes 기록
    acceptance: rollback command가 1단계로 실행 가능
    status: completed
  - id: P9-003
    action: 변경요청 없는 파일 변경을 차단한다.
    method: tools/validate_change_request_coverage_v2.py --changed-files runtime/changed_files.txt
    acceptance: changed_files_without_change_request_count == 0
    status: completed
  - id: P9-004
    action: 릴리즈 후 자동 audit report를 생성한다.
    method: Temp/refactor_release_audit_v1.json에 gate, diff, entropy, formula coverage,
      activation status 기록
    acceptance: gate == PASS 또는 release_mode == AUDIT_ONLY
    status: completed
validators_to_add_or_strengthen:
- validator: validate_packaged_artifact_references_v1.py
  purpose: runtime manifest와 final packet이 참조하는 파일이 실제 업로드 zip에 존재하는지 검사
  pass_condition: missing_ref_count == 0
- validator: validate_formula_contract_completeness_v1.py
  purpose: 모든 formula shard가 owner/lifecycle/input/output/missing/golden/activation/retirement
    필드를 갖는지 검사
  pass_condition: missing_required_field_count == 0
- validator: validate_tools_are_thin_wrappers_v1.py
  purpose: tools/*.py에 business logic, threshold, formula calculation이 남아 있는지 검사
  pass_condition: logic_violation_count == 0
- validator: validate_package_script_budget_v1.py
  purpose: package.json script count와 chained command를 예산화
  pass_condition: script_count <= 12 and chained_script_count == 0
- validator: validate_factor_lifecycle_coverage_v1.py
  purpose: 모든 팩터가 horizon, decay, conflict, activation, retirement를 갖는지 검사
  pass_condition: factor_lifecycle_coverage_pct == 100
- validator: validate_performance_activation_gate_v1.py
  purpose: 성과 미달 팩터가 active로 승격되는 것을 차단
  pass_condition: active_factor_with_failed_performance_count == 0
- validator: validate_low_capability_context_closure_v2.py
  purpose: 저성능 LLM context가 외부 숫자 생성 없이 보고서 작성 가능한지 검사
  pass_condition: llm_free_numeric_field_count == 0 and missing_required_section_count
    == 0
- validator: validate_doc_entropy_v1.py
  purpose: 문서 중복, AGENTS 비대화, stale ADR를 검사
  pass_condition: duplicate_doc_block_count == 0 and agents_line_count <= 220
- validator: validate_active_artifact_presence_in_canonical_v1.py
  purpose: active artifact가 canonical/artifacts 또는 Temp final packet과 일치하는지 검사
  pass_condition: active_artifact_match_pct == 100
low_capability_llm_operating_procedure:
  role: renderer_only
  forbidden:
  - 숫자 계산
  - 가격 추정
  - 수량 추정
  - 하네스 verdict 번복
  - missing data 보정
  - 외부 시장 데이터로 harness 교체
  allowed:
  - final_context_for_llm.yaml 값 복사
  - DATA_MISSING 표기
  - blocker 설명
  - action_table를 사람이 읽게 정리
  - 교육용 설명
  fixed_steps:
  - step: 1
    name: read_required_files
    instruction: AGENTS.md 읽기 순서를 따른다. 파일이 없으면 DATA_MISSING으로 쓰고 추정하지 않는다.
  - step: 2
    name: print_executive_gate
    instruction: engine_gate, blockers, readiness_gate를 먼저 출력한다.
  - step: 3
    name: print_sell_priority
    instruction: sell candidate가 2개 이상이면 sell priority table을 action table보다 먼저 출력한다.
  - step: 4
    name: print_actions
    instruction: BUY/SELL/HOLD/WATCH/AVOID는 packet의 action만 사용한다.
  - step: 5
    name: print_cash_defense
    instruction: D+2 현금을 즉시현금 방어선 충족으로 포함하되 결제갭 리스크는 별도 표시한다.
  - step: 6
    name: print_shadow_ledger
    instruction: blocked/limited 항목의 산출값을 숨기지 않는다.
  - step: 7
    name: print_data_missing
    instruction: 하네스 결측은 DATA_MISSING — 하네스 업데이트 필요 문구로만 표기한다.
  response_quality_checklist:
  - 모든 숫자에 provenance가 있거나 packet에서 온 값이다.
  - 매수/매도 가격과 수량을 LLM이 생성하지 않았다.
  - live와 replay 성과를 섞지 않았다.
  - 하네스 차단 신호를 문장으로 완화하지 않았다.
  - 보고서 섹션 순서가 계약과 일치한다.
quant_decision_policy_to_lock:
  entry_policy:
  - 신규 매수는 macro/risk/cash/data/integrity gate가 모두 통과해야 한다.
  - 상승률 후행 추격 신호만 존재하면 BUY가 아니라 WATCH_PULLBACK 또는 AVOID_CHASE로 둔다.
  - fundamental 우수 + 단기 과열이면 분할진입 또는 대기이며 전량 BUY 금지.
  - distribution risk가 높으면 breakout score가 좋아도 size cap 또는 block.
  exit_policy:
  - ABS_FLOOR는 다른 서사보다 우선한다.
  - 수익 보유 종목은 trailing/profit ratchet으로 수익금 방어를 먼저 한다.
  - 현금 부족은 가치 훼손 최소화 optimizer로 해결하고, 임의 매도 금지.
  - sell priority table 없이 복수 매도 후보를 나열하지 않는다.
  activation_policy:
  - operational_t20_count < 30이면 live 성과 기반 active 승격 금지.
  - prediction_match_rate_pct < 60이면 alpha confidence를 확대하지 않는다.
  - cash_recovery_value_damage_pct > 10이면 현금확보 알고리즘을 active 확대하지 않는다.
  - algorithm_guidance_proof < 80이면 guidance wording을 강화하고 shadow ledger를 확대한다.
target_metrics_after_refactor:
  hard_gates:
    authority_collision_count: 0
    single_truth_conflict_count: 0
    missing_packaged_artifact_refs: 0
    unproven_report_number_count: 0
    renderer_calculation_count: 0
    llm_free_numeric_field_count: 0
    changed_files_without_change_request_count: 0
    active_formula_without_golden_case_count: 0
    replay_used_as_live_count: 0
  repository_entropy_targets:
    package_script_count_target: 12
    tools_business_logic_violation_count: 0
    agents_md_line_count_max: 220
    formula_registry_direct_edit_allowed: false
    canonical_active_artifact_per_formula: 1
  performance_targets_for_active_trading_upgrade:
    operational_t20_sample_min: 30
    prediction_match_rate_pct_min: 60
    execution_expectancy_pct_min: 0.1
    execution_win_rate_pct_min: 45
    cash_recovery_value_damage_pct_max: 10
    overall_hardening_score_min: 80
    algorithm_guidance_proof_min: 80
recommended_file_changes:
  create:
  - runtime/refactor_baseline_v1.yaml
  - tools/validate_packaged_artifact_references_v1.py
  - tools/validate_package_script_budget_v1.py
  - tools/validate_tools_are_thin_wrappers_v1.py
  - tools/validate_formula_contract_completeness_v1.py
  - tools/run_release_dag_v2.py
  - schemas/formula_contract.schema.json
  - schemas/release_dag.schema.json
  - spec/formulas/domains/entry.yaml
  - spec/formulas/domains/exit.yaml
  - spec/formulas/domains/risk.yaml
  - spec/formulas/domains/cash.yaml
  - spec/formulas/domains/portfolio.yaml
  - spec/formulas/domains/fundamental.yaml
  - spec/formulas/domains/smart_money.yaml
  - spec/formulas/domains/macro.yaml
  - spec/formulas/domains/reporting.yaml
  - runtime/rollback_manifest_v1.yaml
  modify:
  - AGENTS.md
  - package.json
  - spec/13_formula_registry.yaml
  - spec/41_release_dag.yaml
  - spec/43_quant_factor_taxonomy.yaml
  - spec/46_low_capability_execution_pack.yaml
  - spec/release/repository_entropy_budget.yaml
  - runtime/active_artifact_manifest.yaml
  - tools/prepare_upload_zip.py
  archive_or_generate_only:
  - 구버전 Temp 산출물 참조
  - artifacts/canonical 내 중복 active 버전
  - tools와 src에 동시에 존재하는 business logic 파일
  - 직접 편집되는 generated schema/model/formula 파일
implementation_sequence_for_a_low_capability_agent:
- 1. 절대 투자 공식부터 수정하지 말고 P0 validator를 먼저 만든다.
- 2. validate_packaged_artifact_references_v1.py를 실행해 missing refs를 0으로 만든다.
- 3. package.json script count를 줄이기 전 현재 scripts를 release_dag.yaml로 그대로 옮긴다.
- 4. DAG가 기존 full-gate와 동일한 결과를 낸 뒤 package.json을 축소한다.
- 5. formula registry를 domain shard로 복사 분할하되, normalized 13_formula_registry는 generator로
  재생성한다.
- 6. tools/src 중복 파일을 하나씩 wrapper화하고 매번 golden/parity/release gate를 실행한다.
- 7. 저성능 LLM final_context를 먼저 닫고, 보고서 prompt는 context 외부 숫자 접근을 금지한다.
- 8. 성과 개선 알고리즘은 전부 shadow로 추가하고 operational sample 조건 충족 전 active 승격하지 않는다.
- 9. 모든 변경은 change_request yaml에 rationale, touched_files, expected_metric, rollback_plan을
  적는다.
- 10. 마지막에 release_dag_run_v2.json, refactor_release_audit_v1.json, rollback_manifest_v1.yaml을
  생성한다.
definition_of_done:
- 업로드 zip만 받아도 active manifest의 모든 참조를 열 수 있다.
- package.json은 12개 이하의 top-level command만 가진다.
- spec domain shard가 원본이고 normalized registry는 생성물이다.
- tools는 얇은 CLI wrapper이며 계산 로직은 src/quant_engine에만 있다.
- 새 공식은 contract/schema/golden/owner/activation/retirement 없이는 merge되지 않는다.
- 저성능 LLM은 final_context_for_llm.yaml만 보고도 동일한 action table을 출력한다.
- 리포트의 모든 숫자는 provenance 100%를 유지한다.
- live/replay/imputed/manual 데이터가 분리되어 표시된다.
- 투자 활성화는 성과 게이트 미달 시 항상 WATCH/AUDIT_ONLY로 남는다.
- rollback이 단일 명령 또는 단일 manifest 교체로 가능하다.
