diff --git a/docs/ouroboros/00_validation_system.md b/docs/ouroboros/00_validation_system.md new file mode 100644 index 0000000..10e037c --- /dev/null +++ b/docs/ouroboros/00_validation_system.md @@ -0,0 +1,56 @@ + + +# 문서 검증 시스템 + +본 문서는 문서 간 허위 내용, 수치 충돌, 구현 불가능 지시를 사전에 제거하기 위한 검증 규칙이다. + +## 검증 목표 + +- 단일 진실원장 기준으로 모든 지시서의 수치/규칙 정합성 보장 +- 설계 문장과 코드 작업 지시 간 추적성 보장 +- 테스트 미정의 상태에서 구현 착수 금지 + +## 불일치 유형 정의 + +- `RULE-DOC-001`: 정의되지 않은 요구사항 ID 사용 +- `RULE-DOC-002`: 동일 요구사항 ID에 상충되는 값(예: 슬리피지 수치) 기술 +- `RULE-DOC-003`: 시간대 미표기 또는 KST/UTC 혼용 지시 +- `RULE-DOC-004`: 주문 정책과 리스크 정책 충돌(예: 저유동 세션 시장가 허용) +- `RULE-DOC-005`: 구현 태스크에 테스트 ID 미연결 +- `RULE-DOC-006`: 문서 라우팅 링크 깨짐 + +## 검증 파이프라인 + +1. 정적 검사 (자동) +- 대상: `docs/ouroboros/*.md` +- 검사: 메타데이터, 링크 유효성, ID 정의/참조 일치, REQ-추적성 매핑 +- 도구: `scripts/validate_ouroboros_docs.py` + +2. 추적성 검사 (자동 + 수동) +- 자동: `REQ-*`가 최소 1개 `TASK-*`와 1개 `TEST-*`에 연결되었는지 확인 +- 수동: 정책 충돌 후보를 PR 체크리스트로 검토 + +3. 도메인 무결성 검사 (수동) +- KIS 점검시간 회피, 주문 유형 강제, Kill Switch 순서, 환율 정책이 동시에 존재하는지 점검 +- 백테스트 체결가가 보수 가정인지 점검 + +## 변경 통제 규칙 + +- `REQ-*` 추가/수정 시 반드시 `01_requirements_registry.md` 먼저 변경 +- `TASK-*` 수정 시 반드시 `40_acceptance_and_test_plan.md`의 대응 테스트를 동시 수정 +- 충돌 발생 시 우선순위: `requirements_registry > phase execution > code work order` + +적용 룰셋: +- `RULE-DOC-001` `RULE-DOC-002` `RULE-DOC-003` `RULE-DOC-004` `RULE-DOC-005` `RULE-DOC-006` + +## PR 게이트 + +- `python3 scripts/validate_ouroboros_docs.py` 성공 +- 신규/변경 `REQ-*`가 테스트 기준(`TEST-*`)과 연결됨 +- 원본 계획(v2/v3)과 모순 없음 diff --git a/docs/ouroboros/01_requirements_registry.md b/docs/ouroboros/01_requirements_registry.md new file mode 100644 index 0000000..d01269e --- /dev/null +++ b/docs/ouroboros/01_requirements_registry.md @@ -0,0 +1,39 @@ + + +# 요구사항 원장 (Single Source of Truth) + +이 문서의 ID가 계획/구현/테스트 전 문서에서 참조되는 유일한 요구사항 집합이다. + +## v2 핵심 요구사항 + +- `REQ-V2-001`: 상태는 `HOLDING`, `BE_LOCK`, `ARMED`, `EXITED` 4단계여야 한다. +- `REQ-V2-002`: 상태 전이는 매 틱/바 평가 시 최상위 상태로 즉시 승격되어야 한다. +- `REQ-V2-003`: `EXITED` 조건은 모든 상태보다 우선 평가되어야 한다. +- `REQ-V2-004`: 청산 로직은 Hard Stop, BE Lock, ATR Trailing, 모델 확률 보조 트리거를 포함해야 한다. +- `REQ-V2-005`: 라벨링은 Triple Barrier(Upper/Lower/Time) 방식이어야 한다. +- `REQ-V2-006`: 검증은 Walk-forward + Purge/Embargo를 강제한다. +- `REQ-V2-007`: 백테스트는 비용/슬리피지/체결실패를 반영하지 않으면 채택 불가다. +- `REQ-V2-008`: Kill Switch는 신규주문차단 -> 미체결취소 -> 재조회 -> 리스크축소 -> 스냅샷 순서다. + +## v3 핵심 요구사항 + +- `REQ-V3-001`: 모든 신호/주문/로그는 `session_id`를 포함해야 한다. +- `REQ-V3-002`: 세션 전환 시 리스크 파라미터 재로딩이 수행되어야 한다. +- `REQ-V3-003`: 브로커 블랙아웃 시간대에는 신규 주문이 금지되어야 한다. +- `REQ-V3-004`: 블랙아웃 중 신호는 Queue에 적재되고, 복구 후 유효성 재검증을 거친다. +- `REQ-V3-005`: 저유동 세션(`NXT_AFTER`, `US_PRE`, `US_DAY`, `US_AFTER`)은 시장가 주문 금지다. +- `REQ-V3-006`: 백테스트 체결가는 불리한 방향 체결 가정을 기본으로 한다. +- `REQ-V3-007`: US 운용은 환율 손익 분리 추적과 통화 버퍼 정책을 포함해야 한다. +- `REQ-V3-008`: 마감/오버나잇 규칙은 Kill Switch와 충돌 없이 연동되어야 한다. + +## 공통 운영 요구사항 + +- `REQ-OPS-001`: 타임존은 모든 시간 필드에 명시(KST/UTC)되어야 한다. +- `REQ-OPS-002`: 문서의 수치 정책은 원장에서만 변경한다. +- `REQ-OPS-003`: 구현 태스크는 반드시 테스트 태스크를 동반한다. diff --git a/docs/ouroboros/10_phase_v2_execution.md b/docs/ouroboros/10_phase_v2_execution.md new file mode 100644 index 0000000..118f6f9 --- /dev/null +++ b/docs/ouroboros/10_phase_v2_execution.md @@ -0,0 +1,63 @@ + + +# v2 실행 지시서 (설계 -> 코드) + +참조 요구사항: `REQ-V2-001` `REQ-V2-002` `REQ-V2-003` `REQ-V2-004` `REQ-V2-005` `REQ-V2-006` `REQ-V2-007` `REQ-V2-008` `REQ-OPS-001` `REQ-OPS-002` `REQ-OPS-003` + +## 단계 1: 도메인 모델 확정 + +- `TASK-V2-001`: 상태머신 enum/전이 이벤트/전이 사유 스키마 설계 +- `TASK-V2-002`: `position_state` 스냅샷 구조(현재상태, peak, stops, last_reason) 정의 +- `TASK-V2-003`: 청산 판단 입력 DTO(가격, ATR, pred_prob, liquidity_signal) 정의 + +완료 기준: +- 상태와 전이 사유가 로그/DB에서 재현 가능 +- `REQ-V2-001`~`003`을 코드 타입 수준에서 강제 + +## 단계 2: 청산 엔진 구현 + +- `TASK-V2-004`: 우선순위 기반 전이 함수 구현(`evaluate_exit_first` -> `promote_state`) +- `TASK-V2-005`: Hard Stop/BE Lock/ATR Trailing 결합 로직 구현 +- `TASK-V2-006`: 모델 확률 신호를 보조 트리거로 결합(단독 청산 금지) + +완료 기준: +- 갭 상황에서 다중 조건 동시 충족 시 최상위 상태로 단번 전이 +- `REQ-V2-004` 준수 + +## 단계 3: 라벨링/학습 데이터 파이프라인 + +- `TASK-V2-007`: Triple Barrier 라벨러 구현(장벽 선터치 우선) +- `TASK-V2-008`: 피처 구간/라벨 구간 분리 검증 유틸 구현 +- `TASK-V2-009`: 라벨 생성 로그(진입시각, 터치장벽, 만기장벽) 기록 + +완료 기준: +- look-ahead 차단 증빙 로그 확보 +- `REQ-V2-005` 충족 + +## 단계 4: 검증 프레임워크 + +- `TASK-V2-010`: Walk-forward split + Purge/Embargo 분할기 구현 +- `TASK-V2-011`: 베이스라인(`B0`,`B1`,`M1`) 비교 리포트 포맷 구현 +- `TASK-V2-012`: 체결 비용/슬리피지/실패 반영 백테스트 옵션 강제 + +완료 기준: +- `REQ-V2-006`, `REQ-V2-007` 충족 + +## 단계 5: Kill Switch 통합 + +- `TASK-V2-013`: Kill Switch 순차 실행 오케스트레이터 구현 (`src/core/risk_manager.py` 수정 금지) +- `TASK-V2-014`: 주문 차단 플래그/미체결 취소/재조회 재시도 로직 구현 +- `TASK-V2-015`: 스냅샷/알림/복구 진입 절차 구현 + +완료 기준: +- `REQ-V2-008` 순서 일치 + +라우팅: +- 코드 지시 상세: [30_code_level_work_orders.md](./30_code_level_work_orders.md) +- 테스트 상세: [40_acceptance_and_test_plan.md](./40_acceptance_and_test_plan.md) diff --git a/docs/ouroboros/20_phase_v3_execution.md b/docs/ouroboros/20_phase_v3_execution.md new file mode 100644 index 0000000..5cfaaba --- /dev/null +++ b/docs/ouroboros/20_phase_v3_execution.md @@ -0,0 +1,60 @@ + + +# v3 실행 지시서 (세션 확장) + +참조 요구사항: `REQ-V3-001` `REQ-V3-002` `REQ-V3-003` `REQ-V3-004` `REQ-V3-005` `REQ-V3-006` `REQ-V3-007` `REQ-V3-008` `REQ-OPS-001` `REQ-OPS-002` `REQ-OPS-003` + +## 단계 1: 세션 엔진 + +- `TASK-V3-001`: `session_id` 분류기 구현(KR/US 확장 세션) +- `TASK-V3-002`: 세션 전환 훅에서 리스크 파라미터 재로딩 구현 +- `TASK-V3-003`: 로그/DB 스키마에 `session_id` 필드 강제 + +완료 기준: +- `REQ-V3-001`, `REQ-V3-002` 충족 + +## 단계 2: 블랙아웃/복구 제어 + +- `TASK-V3-004`: 블랙아웃 윈도우 정책 로더 구현(설정 기반) +- `TASK-V3-005`: 블랙아웃 중 신규 주문 차단 + 의도 큐 적재 구현 +- `TASK-V3-006`: 복구 시 동기화(잔고/미체결/체결) 후 큐 재검증 실행 + +완료 기준: +- `REQ-V3-003`, `REQ-V3-004` 충족 + +## 단계 3: 주문 정책 강화 + +- `TASK-V3-007`: 세션별 주문 타입 매트릭스 구현 +- `TASK-V3-008`: 저유동 세션 시장가 주문 하드 차단 +- `TASK-V3-009`: 재호가 간격/횟수 제한 및 주문 철회 조건 구현 + +완료 기준: +- `REQ-V3-005` 충족 + +## 단계 4: 비용/체결 모델 정교화 + +- `TASK-V3-010`: 세션별 슬리피지/비용 테이블 엔진 반영 +- `TASK-V3-011`: 불리한 체결 가정(상대 호가 방향) 체결기 구현 +- `TASK-V3-012`: 시나리오별 체결 실패/부분체결 모델 반영 + +완료 기준: +- `REQ-V3-006` 충족 + +## 단계 5: 환율/오버나잇/Kill Switch 연동 + +- `TASK-V3-013`: 전략 PnL과 FX PnL 분리 회계 구현 +- `TASK-V3-014`: USD/KRW 버퍼 규칙 위반 시 신규 진입 제한 구현 +- `TASK-V3-015`: 오버나잇 예외와 Kill Switch 우선순위 통합 + +완료 기준: +- `REQ-V3-007`, `REQ-V3-008` 충족 + +라우팅: +- 코드 지시 상세: [30_code_level_work_orders.md](./30_code_level_work_orders.md) +- 테스트 상세: [40_acceptance_and_test_plan.md](./40_acceptance_and_test_plan.md) diff --git a/docs/ouroboros/30_code_level_work_orders.md b/docs/ouroboros/30_code_level_work_orders.md new file mode 100644 index 0000000..3333e27 --- /dev/null +++ b/docs/ouroboros/30_code_level_work_orders.md @@ -0,0 +1,59 @@ + + +# 코드 레벨 작업 지시서 + +본 문서는 파일 단위 구현 지시서다. 모든 작업은 요구사항 ID와 테스트 ID를 포함해야 한다. + +제약: +- `src/core/risk_manager.py`는 READ-ONLY로 간주하고 수정하지 않는다. +- Kill Switch는 별도 모듈(예: `src/core/kill_switch.py`)로 추가하고 상위 실행 루프에서 연동한다. + +## 구현 단위 A: 상태기계/청산 + +- `TASK-CODE-001` (`REQ-V2-001`,`REQ-V2-002`,`REQ-V2-003`): `src/strategy/`에 상태기계 모듈 추가 +- `TASK-CODE-002` (`REQ-V2-004`): ATR/BE/Hard Stop 결합 청산 함수 추가 +- `TASK-CODE-003` (`REQ-V2-008`): Kill Switch 오케스트레이터를 `src/core/kill_switch.py`에 추가 +- `TEST-CODE-001`: 갭 점프 시 최고상태 승격 테스트 +- `TEST-CODE-002`: EXIT 우선순위 테스트 + +## 구현 단위 B: 라벨링/검증 + +- `TASK-CODE-004` (`REQ-V2-005`): Triple Barrier 라벨러 모듈 추가(`src/analysis/` 또는 `src/strategy/`) +- `TASK-CODE-005` (`REQ-V2-006`): Walk-forward + Purge/Embargo 분할 유틸 추가 +- `TASK-CODE-006` (`REQ-V2-007`): 백테스트 실행기에서 비용/슬리피지 옵션 필수화 +- `TEST-CODE-003`: 라벨 선터치 우선 테스트 +- `TEST-CODE-004`: 누수 차단 테스트 + +## 구현 단위 C: 세션/주문 정책 + +- `TASK-CODE-007` (`REQ-V3-001`,`REQ-V3-002`): 세션 분류/전환 훅을 `src/markets/schedule.py` 연동 +- `TASK-CODE-008` (`REQ-V3-003`,`REQ-V3-004`): 블랙아웃 큐 처리기를 `src/broker/`에 추가 +- `TASK-CODE-009` (`REQ-V3-005`): 세션별 주문 타입 검증기 추가 +- `TEST-CODE-005`: 블랙아웃 신규주문 차단 테스트 +- `TEST-CODE-006`: 저유동 세션 시장가 거부 테스트 + +## 구현 단위 D: 체결/환율/오버나잇 + +- `TASK-CODE-010` (`REQ-V3-006`): 불리한 체결가 모델을 백테스트 체결기로 구현 +- `TASK-CODE-011` (`REQ-V3-007`): FX PnL 분리 회계 테이블/컬럼 추가 +- `TASK-CODE-012` (`REQ-V3-008`): 오버나잇 예외와 Kill Switch 충돌 해소 로직 구현 +- `TEST-CODE-007`: 불리한 체결가 모델 테스트 +- `TEST-CODE-008`: FX 버퍼 위반 시 신규진입 제한 테스트 + +## 구현 단위 E: 운영/문서 거버넌스 + +- `TASK-OPS-001` (`REQ-OPS-001`): 시간 필드/로그 스키마의 타임존 표기 강제 규칙 구현 +- `TASK-OPS-002` (`REQ-OPS-002`): 정책 수치 변경 시 `01_requirements_registry.md` 선수정 CI 체크 추가 +- `TASK-OPS-003` (`REQ-OPS-003`): `TASK-*` 없는 `REQ-*` 또는 `TEST-*` 없는 `REQ-*`를 차단하는 문서 검증 게이트 유지 + +## 커밋 규칙 + +- 커밋 메시지에 `TASK-*` 포함 +- PR 본문에 `REQ-*`, `TEST-*` 매핑 표 포함 +- 변경 파일마다 최소 1개 테스트 연결 diff --git a/docs/ouroboros/40_acceptance_and_test_plan.md b/docs/ouroboros/40_acceptance_and_test_plan.md new file mode 100644 index 0000000..182d344 --- /dev/null +++ b/docs/ouroboros/40_acceptance_and_test_plan.md @@ -0,0 +1,57 @@ + + +# 수용 기준 및 테스트 계획 + +## 수용 기준 + +- `TEST-ACC-000` (`REQ-V2-001`): 상태 enum은 4개(`HOLDING`,`BE_LOCK`,`ARMED`,`EXITED`)만 허용한다. +- `TEST-ACC-001` (`REQ-V2-002`): 상태 전이는 순차 if-else가 아닌 우선순위 승격으로 동작한다. +- `TEST-ACC-010` (`REQ-V2-003`): `EXITED` 조건은 어떤 상태보다 먼저 평가된다. +- `TEST-ACC-011` (`REQ-V2-004`): 청산 판단은 Hard Stop/BE Lock/ATR/모델보조 4요소를 모두 포함한다. +- `TEST-ACC-012` (`REQ-V2-005`): Triple Barrier 라벨은 first-touch 규칙으로 결정된다. +- `TEST-ACC-013` (`REQ-V2-006`): 학습/검증 분할은 Walk-forward + Purge/Embargo를 적용한다. +- `TEST-ACC-014` (`REQ-V2-007`): 비용/슬리피지/체결실패 옵션 비활성 시 백테스트 실행을 거부한다. +- `TEST-ACC-002` (`REQ-V2-008`): Kill Switch 실행 순서가 고정 순서를 위반하지 않는다. +- `TEST-ACC-015` (`REQ-V3-001`): 모든 주문/로그 레코드에 `session_id`가 저장된다. +- `TEST-ACC-016` (`REQ-V3-002`): 세션 전환 이벤트 시 리스크 파라미터가 재로딩된다. +- `TEST-ACC-003` (`REQ-V3-003`): 블랙아웃 중 신규 주문 API 호출이 발생하지 않는다. +- `TEST-ACC-017` (`REQ-V3-004`): 블랙아웃 큐는 복구 후 재검증을 통과한 주문만 실행한다. +- `TEST-ACC-004` (`REQ-V3-005`): 저유동 세션 시장가 주문은 항상 거부된다. +- `TEST-ACC-005` (`REQ-V3-006`): 백테스트 체결가가 단순 종가 체결보다 보수적 손익을 낸다. +- `TEST-ACC-006` (`REQ-V3-007`): 전략 손익과 환율 손익이 별도 집계된다. +- `TEST-ACC-018` (`REQ-V3-008`): 오버나잇 예외 상태에서도 Kill Switch 우선순위가 유지된다. +- `TEST-ACC-007` (`REQ-OPS-001`): 시간 관련 필드는 타임존(KST/UTC)이 누락되면 검증 실패한다. +- `TEST-ACC-008` (`REQ-OPS-002`): 정책 수치 변경이 원장 미반영이면 검증 실패한다. +- `TEST-ACC-009` (`REQ-OPS-003`): `REQ-*`가 `TASK-*`/`TEST-*` 매핑 없이 존재하면 검증 실패한다. + +## 테스트 계층 + +1. 단위 테스트 +- 상태 전이, 주문타입 검증, 큐 복구 로직, 체결가 모델 + +2. 통합 테스트 +- 세션 전환 -> 주문 정책 -> 리스크 엔진 연동 +- 블랙아웃 시작/해제 이벤트 연동 + +3. 회귀 테스트 +- 기존 `tests/` 스위트 전량 실행 +- 신규 기능 플래그 ON/OFF 비교 + +## 실행 명령 + +```bash +pytest -q +python3 scripts/validate_ouroboros_docs.py +``` + +## 실패 처리 규칙 + +- 문서 검증 실패 시 구현 PR 병합 금지 +- `REQ-*` 변경 후 테스트 매핑 누락 시 병합 금지 +- 회귀 실패 시 원인 모듈 분리 후 재검증 diff --git a/docs/ouroboros/README.md b/docs/ouroboros/README.md new file mode 100644 index 0000000..3b252ca --- /dev/null +++ b/docs/ouroboros/README.md @@ -0,0 +1,36 @@ + + +# The Ouroboros 실행 문서 허브 + +이 폴더는 `ouroboros_plan_v2.txt`, `ouroboros_plan_v3.txt`를 구현 가능한 작업 지시서 수준으로 분해한 문서 허브다. + +## 읽기 순서 (Routing) + +1. 검증 체계부터 확정: [00_validation_system.md](./00_validation_system.md) +2. 단일 진실원장(요구사항): [01_requirements_registry.md](./01_requirements_registry.md) +3. v2 실행 지시서: [10_phase_v2_execution.md](./10_phase_v2_execution.md) +4. v3 실행 지시서: [20_phase_v3_execution.md](./20_phase_v3_execution.md) +5. 코드 레벨 작업 지시: [30_code_level_work_orders.md](./30_code_level_work_orders.md) +6. 수용 기준/테스트 계획: [40_acceptance_and_test_plan.md](./40_acceptance_and_test_plan.md) + +## 운영 규칙 + +- 계획 변경은 반드시 `01_requirements_registry.md`의 ID 정의부터 수정한다. +- 구현 문서는 원장 ID만 참조하고 자체 숫자/정책을 새로 만들지 않는다. +- 문서 품질 룰셋(`RULE-DOC-001` `RULE-DOC-002` `RULE-DOC-003` `RULE-DOC-004` `RULE-DOC-005` `RULE-DOC-006`)은 [00_validation_system.md](./00_validation_system.md)를 기준으로 적용한다. +- 문서 병합 전 아래 검증을 통과해야 한다. + +```bash +python3 scripts/validate_ouroboros_docs.py +``` + +## 원본 계획 문서 + +- [v2](/home/agentson/repos/The-Ouroboros/ouroboros_plan_v2.txt) +- [v3](/home/agentson/repos/The-Ouroboros/ouroboros_plan_v3.txt) diff --git a/docs/workflow.md b/docs/workflow.md index 0183368..7d446ee 100644 --- a/docs/workflow.md +++ b/docs/workflow.md @@ -13,6 +13,57 @@ **Never commit directly to `main`.** This policy applies to all changes, no exceptions. +## Gitea CLI Formatting Troubleshooting + +Issue/PR 본문 작성 시 줄바꿈(`\n`)이 문자열 그대로 저장되는 문제가 반복될 수 있다. 원인은 `-d "...\n..."` 형태에서 쉘/CLI가 이스케이프를 실제 개행으로 해석하지 않기 때문이다. + +권장 패턴: + +```bash +ISSUE_BODY=$(cat <<'EOF' +## Summary +- 변경 내용 1 +- 변경 내용 2 + +## Why +- 배경 1 +- 배경 2 + +## Scope +- 포함 범위 +- 제외 범위 +EOF +) + +tea issues create \ + -t "docs: 제목" \ + -d "$ISSUE_BODY" +``` + +PR도 동일하게 적용: + +```bash +PR_BODY=$(cat <<'EOF' +## Summary +- ... + +## Validation +- python3 scripts/validate_ouroboros_docs.py +EOF +) + +tea pr create \ + --base main \ + --head feature/issue-N-something \ + --title "docs: ... (#N)" \ + --description "$PR_BODY" +``` + +금지 패턴: + +- `-d "line1\nline2"` (웹 UI에 `\n` 문자 그대로 노출될 수 있음) +- 본문에 백틱/괄호를 인라인로 넣고 적절한 quoting 없이 즉시 실행 + ## Agent Workflow **Modern AI development leverages specialized agents for concurrent, efficient task execution.** diff --git a/ouroboros_plan_v2.txt b/ouroboros_plan_v2.txt new file mode 100644 index 0000000..b5c760b --- /dev/null +++ b/ouroboros_plan_v2.txt @@ -0,0 +1,165 @@ +[The Ouroboros] 운영/전략 계획서 v2 +작성일: 2026-02-26 +상태: 코드 구현 전 설계안(전략/검증 중심) + +================================================== +0) 목적 +================================================== +고정 익절(+3%) 중심 로직에서 벗어나, 다음을 만족하는 실전형 청산 체계로 전환한다. +- 수익 구간 보호 (손익 역전 방지) +- 변동성 적응형 청산 +- 예측 모델의 확률 신호를 보조적으로 결합 +- 과적합 방지를 최우선으로 한 검증 프레임워크 + +================================================== +1) 핵심 설계 원칙 +================================================== +1. 예측 성능과 전략 성능을 분리 평가 +- 예측 성능: PR-AUC, Brier, Calibration +- 전략 성능: Net PnL, Sharpe, MDD, Profit Factor, Turnover + +2. 시계열 검증 규율 강제 +- Walk-forward 분할 +- Purge/Embargo 적용 +- Random split 금지 + +3. 실거래 리얼리즘 우선 +- 거래비용/슬리피지/체결실패 반영 없는 백테스트 결과는 채택 금지 + +================================================== +2) 매도 상태기계 (State Machine) +================================================== +상태: +- HOLDING +- BE_LOCK +- ARMED +- EXITED + +정의: +- HOLDING: 일반 보유 상태 +- BE_LOCK: 일정 수익권 진입 시 손절선을 본전(또는 비용 반영 본전)으로 상향 +- ARMED: 추세 추적(피크 추적) 기반 청산 준비 상태 +- EXITED: 청산 완료 + +전이 규칙(개념): +- HOLDING -> BE_LOCK: unrealized_pnl_pct >= be_arm_pct +- BE_LOCK -> ARMED: unrealized_pnl_pct >= arm_pct +- ARMED -> EXITED: 아래 조건 중 하나 충족 + 1) hard stop 도달 + 2) trailing stop 도달 (peak 대비 하락) + 3) 모델 하락확률 + 유동성 약화 조건 충족 + +상태 전이 구현 규칙(필수): +- 매 틱/바 평가 시 "현재 조건이 허용하는 최상위 상태"로 즉시 승격 +- 순차 if-else로 인한 전이 누락 금지 (예: 갭으로 BE_LOCK/ARMED 동시 충족) +- EXITED 조건은 모든 상태보다 우선 평가 +- 상태 전이 로그에 이전/이후 상태, 전이 사유, 기준 가격/수익률 기록 + +================================================== +3) 청산 로직 구성 (4중 안전장치) +================================================== +A. Hard Stop +- 계좌/포지션 보호용 절대 하한 +- 항상 활성화 + +B. Dynamic Stop (Break-even Lock) +- BE_LOCK 진입 시 손절선을 본전 이상으로 상향 +- "수익 포지션이 손실로 반전"되는 구조적 리스크 차단 + +C. ATR 기반 Trailing Stop +- 고정 trail_pct 대신 변동성 적응형 사용 +- 예시: ExitPrice = PeakPrice - (k * ATR) + +D. 모델 확률 신호 +- 하락전환 확률(pred_prob)이 임계값 이상일 때 청산 가중 +- 단독 트리거가 아닌 trailing/리스크 룰 보조 트리거로 사용 + +================================================== +4) 라벨링 체계 (Triple Barrier) +================================================== +목표: +고정 H-window 라벨 편향을 줄이고, 금융 시계열의 경로 의존성을 반영한다. + +라벨 정의: +- Upper barrier (익절) +- Lower barrier (손절) +- Time barrier (만기) + +규칙: +- 세 장벽 중 "먼저 터치한 장벽"으로 라벨 확정 +- 라벨은 entry 시점 이후 데이터만 사용해 생성 +- 피처 생성 구간과 라벨 구간을 엄격 분리해 look-ahead bias 방지 + +================================================== +5) 검증 프레임워크 +================================================== +5.1 분할 방식 +- Fold 단위 Walk-forward +- Purge/Embargo로 인접 샘플 누수 차단 + +5.2 비교군(Baseline) 구조 +- B0: 기존 고정 손절/익절 +- B1: 모델 없는 trailing only +- M1: trailing + 모델 확률 결합 + +5.3 채택 기준 +- M1이 B0/B1 대비 OOS(Out-of-sample)에서 일관된 우위 +- 단일 구간 성과가 아닌 fold 분포 기준으로 판단 + +================================================== +6) 실행 아키텍처 원칙 +================================================== +1. 저지연 실행 경로 +- 실시간 청산 판단은 경량 엔진(룰/GBDT) 담당 +- LLM은 레짐 판단/비중 조절/상위 의사결정 보조 + +2. 체결 현실 반영 +- 세션 유동성에 따른 슬리피지 페널티 차등 적용 +- 미체결/재호가/재접수 시나리오를 백테스트에 반영 + +================================================== +7) 운영 리스크 관리 +================================================== +승격 단계: +- Offline backtest -> Paper shadow -> Small-capital live + +중단(Kill Switch): +- rolling Sharpe 악화 +- MDD 한도 초과 +- 체결 실패율/슬리피지 급등 + +Kill Switch 실행 순서(원자적): +1) 모든 신규 주문 차단 플래그 ON +2) 모든 미체결 주문 취소 요청 +3) 취소 결과 재조회(실패 건 재시도) +4) 포지션 리스크 재계산 후 강제 축소/청산 판단 +5) 상태/로그 스냅샷 저장 및 운영 경보 발송 + +원칙: +- 모델이 실패해도 hard stop 기반 보수 모드로 즉시 디그레이드 가능해야 함 + +================================================== +8) 고정 파라미터(초기안) +================================================== +(15분봉 단기 스윙 기준 제안) +- KR: be_arm_pct=1.2, arm_pct=2.8, atr_period=14, atr_multiplier_k=2.2, + time_barrier_bars=26, p_thresh=0.62 +- US: be_arm_pct=1.0, arm_pct=2.4, atr_period=14, atr_multiplier_k=2.0, + time_barrier_bars=32, p_thresh=0.60 + +민감도 범위(초기 탐색): +- be_arm_pct: KR 0.9~1.8 / US 0.7~1.5 +- arm_pct: KR 2.2~3.8 / US 1.8~3.2 +- atr_multiplier_k: KR 1.8~2.8 / US 1.6~2.4 +- time_barrier_bars: KR 20~36 / US 24~48 +- p_thresh: 0.55~0.70 + +================================================== +9) 구현 전 체크리스트 +================================================== +- 파라미터 튜닝 시 nested leakage 방지 +- 수수료/세금/슬리피지 전부 반영 여부 확인 +- 세션/타임존/DST 처리 일관성 확인 +- 모델 버전/설정 해시/실험 로그 재현성 확보 + +끝. diff --git a/ouroboros_plan_v3.txt b/ouroboros_plan_v3.txt new file mode 100644 index 0000000..47b85d4 --- /dev/null +++ b/ouroboros_plan_v3.txt @@ -0,0 +1,185 @@ +[The Ouroboros] 운영확장 v3 +작성일: 2026-02-26 +상태: v2 확장판 / 야간·프리마켓 포함 글로벌 세션 운영 설계안 + +================================================== +0) 목적 +================================================== +"24시간 무중단 자산 증식" 비전을 위해 거래 세션 범위를 KR 정규장 중심에서 +NXT/미국 확장 세션까지 확대한다. 핵심은 다음 3가지다. +- 세션 인지형 의사결정 +- 세션별 리스크/비용 차등 적용 +- 시간장벽의 현실적 재정의 + +================================================== +1) 세션 모델 (Session-aware Engine) +================================================== +KR 세션: +- NXT_PRE : 08:00 ~ 08:50 (KST) +- KRX_REG : 09:00 ~ 15:30 (KST) +- NXT_AFTER : 15:30 ~ 20:00 (KST) + +US 세션(KST 관점 운영): +- US_DAY : 10:00 ~ 18:00 +- US_PRE : 18:00 ~ 23:30 +- US_REG : 23:30 ~ 06:00 +- US_AFTER : 06:00 ~ 07:00 + +원칙: +- 모든 피처/신호/주문/로그에 session_id를 명시적으로 포함 +- 세션 전환 시 상태 업데이트 및 리스크 파라미터 재로딩 + +================================================== +2) 캘린더/휴장/DST 고정 소스 +================================================== +KR: +- 기본: pykrx 또는 FinanceDataReader (KRX 기준) +- 예외: 연휴/임시 휴장/NXT 특이 운영은 KIS 공지 기반 보완 + +US: +- pandas_market_calendars (NYSE 기준) +- 2026 DST: + - 시작: 2026-03-08 + - 종료: 2026-11-01 + +정합성 규칙: +- 스케줄 충돌 시 "거래소 캘린더 > 로컬 추정" 우선 +- 시장 상태(open/close/half-day)는 주문 엔진 진입 전 최종 검증 + +KIS 점검시간 회피 정책(필수): +- 브로커 점검/장애 블랙아웃 윈도우는 운영 설정으로 별도 관리 +- 블랙아웃 구간에는 신규 주문 전송 금지, 취소/정정도 정책적으로 제한 +- 신호는 유지하되 주문 의도는 Queue에 적재, 복구 후 유효성 재검증 뒤 실행 +- 복구 직후에는 잔고/미체결/체결내역을 우선 동기화한 뒤 주문 엔진 재가동 + +================================================== +3) 시간장벽 재정의 +================================================== +v2의 time_barrier_bars 고정값을 v3에서 다음으로 확장: +- max_holding_minutes (시장별 기본 만기) +- 봉 개수는 세션 길이/간격으로 동적 계산 + +기본값: +- KR: max_holding_minutes = 2160 (약 3거래일, NXT 포함 관점) +- US: max_holding_minutes = 4320 (약 72시간) + +운영 주의: +- 고정 "일중 청산"보다 "포지션 유지 시간" 기준 만기 적용 +- 세션 종료 강제청산 규칙과 충돌 시 우선순위 명시 필요 + +================================================== +4) 세션별 비용/슬리피지 모델 (보수적) +================================================== +KRX_REG: +- 슬리피지: 2~3틱 (약 0.05%) +- 수수료+세금: 0.20% ~ 0.23% + +NXT_AFTER: +- 슬리피지: 5~8틱 (약 0.15%) +- 수수료+세금: 0.20% ~ 0.23% + +US_REG: +- 슬리피지: 2~3틱 (약 0.03%) +- 수수료+기타 비용: 0.07% ~ 0.15% + +US_PRE / US_DAY: +- 슬리피지: 10틱+ (약 0.3% ~ 0.5%) +- 수수료+기타 비용: 0.07% ~ 0.15% + +원칙: +- 백테스트 체결가는 세션별 보수 가정 적용 +- 저유동 세션은 자동 보수 모드(p_thresh 상향, atr_k 상향) 권장 +- 백테스트 체결가 기본은 "불리한 방향 체결" 가정 (단순 close 체결 금지) + +세션별 주문 유형 강제(필수): +- KRX_REG / US_REG: 지정가 우선, 시장가 제한적 허용 +- NXT_AFTER / US_PRE / US_DAY / US_AFTER: 시장가 금지 +- 저유동 세션은 최우선 지정가 또는 IOC/FOK(가격 보호 한도 포함)만 허용 +- 주문 실패 시 재호가 간격/횟수 상한을 두고, 초과 시 주문 철회 + +================================================== +5) 포지션/잔고 통합 규칙 (KIS 특성 반영) +================================================== +문제: +- KRX/NXT 잔고 조회가 venue 단위로 분리되거나 반영 지연 가능 + +규칙: +- 종목 식별은 동일 종목코드(또는 ISIN) 기준 통합 포지션으로 관리 +- 다만 주문 가능 수량은 venue별 API 응답을 최종 기준으로 사용 +- 매도 가능 수량 검증은 주문 직전 재조회로 확정 + +================================================== +6) 마감 강제청산/오버나잇 예외 규칙 +================================================== +기본 원칙: +- 모든 포지션에 대해 세션 종료 10분 전 REDUCE_ALL 검토 + +오버나잇 예외 허용 (모두 충족 시): +1) ARMED 상태 (예: +2.8% 이상) +2) 모델 하락확률 < 0.30 +3) 포트폴리오 현금 비중 >= 50% + +갭 리스크 통제: +- 다음 개장 시 hard stop를 시가 기준으로 재산정 +- 조건 위반 시 즉시 청산 우선 + +Kill Switch 연동: +- MDD/실패율 임계치 초과 시 "미체결 전량 취소 -> 신규 주문 차단 -> 리스크 축소" 순서 강제 + +================================================== +7) 데이터 저장/용량 정책 +================================================== +핵심 테이블(계획): +- feature_snapshots +- position_states +- model_predictions + +저장 규칙: +- feature_hash 기반 중복 제거 +- 가격 변화가 작아도 session_id 변경 시 강제 스냅샷 +- 월 단위 DB 로테이션 권장 (예: trading_YYYY_MM.db) + +================================================== +8) 환율/정산 리스크 정책 (US 필수) +================================================== +원칙: +- USD 노출은 전략 손익과 별도로 환율 손익을 분리 추적 +- 원화 주문 서비스 사용 시 가환율 체결/익일 정산 리스크를 예수금 규칙에 반영 + +운영 규칙: +- 환전 시점 정책(사전 환전/수시 환전)을 고정하고 로그에 기록 +- 최소 USD 버퍼와 KRW 버퍼를 각각 설정해 주문 가능금 부족 리스크 완화 +- 환율 급변 구간에는 포지션 한도 축소 또는 신규 진입 제한 + +================================================== +9) v3 실험 매트릭스 (우선 3선) +================================================== +EXP-KR-01: +- 시장: KR +- 포커스: NXT 야간 특화 +- 제안: time barrier 확장(예: 48 bars 상당), p_thresh 상향(0.65) + +EXP-US-01: +- 시장: US +- 포커스: 21h 준연속 운용 +- 제안: time barrier 확장(예: 80 bars 상당), atr_k 상향(2.5) + +EXP-HYB-01: +- 시장: Global +- 포커스: KR 낮 + US 밤 연계 +- 제안: 레짐 기반 자산배분 자동조절 + +================================================== +10) 코드 착수 전 최종 확정 체크 +================================================== +1) 세션별 공식 캘린더 소스/우선순위 +2) 세션별 슬리피지/비용 테이블 수치 +3) 시장별 max_holding_minutes +4) 마감 강제청산 예외 조건 임계값 +5) 블랙아웃(점검/장애) 시간대와 주문 큐 처리 규칙 +6) 세션별 허용 주문 유형(시장가 허용 범위 포함) +7) 환전/정산 정책 및 통화 버퍼 임계값 + +모든 항목 확정 후 Step 1 구현(코드)로 이동. + +끝. diff --git a/scripts/validate_ouroboros_docs.py b/scripts/validate_ouroboros_docs.py new file mode 100755 index 0000000..2cbeb7f --- /dev/null +++ b/scripts/validate_ouroboros_docs.py @@ -0,0 +1,140 @@ +#!/usr/bin/env python3 +"""Validate Ouroboros planning docs for metadata, links, and ID consistency.""" + +from __future__ import annotations + +import re +import sys +from pathlib import Path + +DOC_DIR = Path("docs/ouroboros") +META_PATTERN = re.compile( + r"", + re.MULTILINE, +) +ID_PATTERN = re.compile(r"\b(?:REQ|RULE|TASK|TEST|DOC)-[A-Z0-9-]+-\d{3}\b") +DEF_PATTERN = re.compile(r"^-\s+`(?P(?:REQ|RULE|TASK|TEST|DOC)-[A-Z0-9-]+-\d{3})`", re.MULTILINE) +LINK_PATTERN = re.compile(r"\[[^\]]+\]\((?P[^)]+)\)") +LINE_DEF_PATTERN = re.compile(r"^-\s+`(?P(?:REQ|RULE|TASK|TEST|DOC)-[A-Z0-9-]+-\d{3})`.*$", re.MULTILINE) + + +def iter_docs() -> list[Path]: + return sorted([p for p in DOC_DIR.glob("*.md") if p.is_file()]) + + +def validate_metadata(path: Path, text: str, errors: list[str], doc_ids: dict[str, Path]) -> None: + match = META_PATTERN.search(text) + if not match: + errors.append(f"{path}: missing or malformed metadata block") + return + doc_id = match.group("doc_id").strip() + if doc_id in doc_ids: + errors.append(f"{path}: duplicate Doc-ID {doc_id} (already in {doc_ids[doc_id]})") + else: + doc_ids[doc_id] = path + + +def validate_links(path: Path, text: str, errors: list[str]) -> None: + for m in LINK_PATTERN.finditer(text): + link = m.group("link").strip() + if not link or link.startswith("http") or link.startswith("#"): + continue + if link.startswith("/"): + target = Path(link) + else: + target = (path.parent / link).resolve() + if not target.exists(): + errors.append(f"{path}: broken link -> {link}") + + +def collect_ids(path: Path, text: str, defs: dict[str, Path], refs: dict[str, set[Path]]) -> None: + for m in DEF_PATTERN.finditer(text): + defs[m.group("id")] = path + for m in ID_PATTERN.finditer(text): + idv = m.group(0) + refs.setdefault(idv, set()).add(path) + + +def collect_req_traceability(text: str, req_to_task: dict[str, set[str]], req_to_test: dict[str, set[str]]) -> None: + for m in LINE_DEF_PATTERN.finditer(text): + line = m.group(0) + item_id = m.group("id") + req_ids = [rid for rid in ID_PATTERN.findall(line) if rid.startswith("REQ-")] + if item_id.startswith("TASK-"): + for req_id in req_ids: + req_to_task.setdefault(req_id, set()).add(item_id) + if item_id.startswith("TEST-"): + for req_id in req_ids: + req_to_test.setdefault(req_id, set()).add(item_id) + + +def main() -> int: + if not DOC_DIR.exists(): + print(f"ERROR: missing directory {DOC_DIR}") + return 1 + + docs = iter_docs() + if not docs: + print(f"ERROR: no markdown docs found in {DOC_DIR}") + return 1 + + errors: list[str] = [] + doc_ids: dict[str, Path] = {} + defs: dict[str, Path] = {} + refs: dict[str, set[Path]] = {} + req_to_task: dict[str, set[str]] = {} + req_to_test: dict[str, set[str]] = {} + + for path in docs: + text = path.read_text(encoding="utf-8") + validate_metadata(path, text, errors, doc_ids) + validate_links(path, text, errors) + collect_ids(path, text, defs, refs) + collect_req_traceability(text, req_to_task, req_to_test) + + for idv, where_used in sorted(refs.items()): + if idv.startswith("DOC-"): + continue + if idv not in defs: + files = ", ".join(str(p) for p in sorted(where_used)) + errors.append(f"undefined ID {idv}, used in: {files}") + + for idv in sorted(defs): + if not idv.startswith("REQ-"): + continue + if idv not in req_to_task: + errors.append(f"REQ without TASK mapping: {idv}") + if idv not in req_to_test: + errors.append(f"REQ without TEST mapping: {idv}") + + warnings: list[str] = [] + for idv, where_def in sorted(defs.items()): + if len(refs.get(idv, set())) <= 1 and (idv.startswith("REQ-") or idv.startswith("RULE-")): + warnings.append(f"orphan ID {idv} defined in {where_def} (not referenced elsewhere)") + + if errors: + print("[FAIL] Ouroboros docs validation failed") + for err in errors: + print(f"- {err}") + return 1 + + print(f"[OK] validated {len(docs)} docs in {DOC_DIR}") + print(f"[OK] unique Doc-ID: {len(doc_ids)}") + print(f"[OK] definitions: {len(defs)}, references: {len(refs)}") + print(f"[OK] req->task mappings: {len(req_to_task)}") + print(f"[OK] req->test mappings: {len(req_to_test)}") + if warnings: + print(f"[WARN] orphan IDs: {len(warnings)}") + for w in warnings: + print(f"- {w}") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/workflow/issue-271-runlog.md b/workflow/issue-271-runlog.md new file mode 100644 index 0000000..c3f8072 --- /dev/null +++ b/workflow/issue-271-runlog.md @@ -0,0 +1,37 @@ +# Issue #271 Workflow Run Log + +## 2026-02-26 + +### Step 1: Gitea issue creation +- Attempt 1: Succeeded, but formatting degraded + - Command style: `tea issues create -t ... -d "...\n..."` + - Symptom: Issue body rendered literal `\n` text in web UI instead of line breaks +- Root cause + - `tea` does not provide `--description-file` + - Shell-escaped `\n` inside double quotes is passed as backslash+n text +- Resolution + - Build body with heredoc and pass as variable (`-d "$ISSUE_BODY"`) + +### Step 2: PR description creation +- Attempt 1: Succeeded, but same newline rendering risk detected +- Resolution + - Same heredoc variable pattern applied for PR body (`--description "$PR_BODY"`) + +### Preventive Action +- `docs/workflow.md` updated with "Gitea CLI Formatting Troubleshooting" section +- Standard command templates added for issues and PRs + +### Reusable Safe Template +```bash +ISSUE_BODY=$(cat <<'EOF' +## Summary +- item A +- item B + +## Scope +- docs only +EOF +) + +tea issues create -t "title" -d "$ISSUE_BODY" +```