docs: add ouroboros execution routing and validation system (#271)

docs/ouroboros/00_validation_system.md

@@ -0,0 +1,56 @@
+<!--
+Doc-ID: DOC-VAL-001
+Version: 1.0.0
+Status: active
+Owner: strategy
+Updated: 2026-02-26
+-->
+
+# 문서 검증 시스템
+
+본 문서는 문서 간 허위 내용, 수치 충돌, 구현 불가능 지시를 사전에 제거하기 위한 검증 규칙이다.
+
+## 검증 목표
+
+- 단일 진실원장 기준으로 모든 지시서의 수치/규칙 정합성 보장
+- 설계 문장과 코드 작업 지시 간 추적성 보장
+- 테스트 미정의 상태에서 구현 착수 금지
+
+## 불일치 유형 정의
+
+- `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)과 모순 없음

docs/ouroboros/01_requirements_registry.md

@@ -0,0 +1,39 @@
+<!--
+Doc-ID: DOC-REQ-001
+Version: 1.0.0
+Status: active
+Owner: strategy
+Updated: 2026-02-26
+-->
+
+# 요구사항 원장 (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`: 구현 태스크는 반드시 테스트 태스크를 동반한다.

docs/ouroboros/10_phase_v2_execution.md

@@ -0,0 +1,63 @@
+<!--
+Doc-ID: DOC-PHASE-V2-001
+Version: 1.0.0
+Status: active
+Owner: strategy
+Updated: 2026-02-26
+-->
+
+# 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)

docs/ouroboros/20_phase_v3_execution.md

@@ -0,0 +1,60 @@
+<!--
+Doc-ID: DOC-PHASE-V3-001
+Version: 1.0.0
+Status: active
+Owner: strategy
+Updated: 2026-02-26
+-->
+
+# 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)

docs/ouroboros/30_code_level_work_orders.md

@@ -0,0 +1,59 @@
+<!--
+Doc-ID: DOC-CODE-001
+Version: 1.0.0
+Status: active
+Owner: strategy
+Updated: 2026-02-26
+-->
+
+# 코드 레벨 작업 지시서
+
+본 문서는 파일 단위 구현 지시서다. 모든 작업은 요구사항 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개 테스트 연결

docs/ouroboros/40_acceptance_and_test_plan.md

@@ -0,0 +1,57 @@
+<!--
+Doc-ID: DOC-TEST-001
+Version: 1.0.0
+Status: active
+Owner: strategy
+Updated: 2026-02-26
+-->
+
+# 수용 기준 및 테스트 계획
+
+## 수용 기준
+
+- `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-*` 변경 후 테스트 매핑 누락 시 병합 금지
+- 회귀 실패 시 원인 모듈 분리 후 재검증

docs/ouroboros/README.md

@@ -0,0 +1,36 @@
+<!--
+Doc-ID: DOC-ROOT-001
+Version: 1.0.0
+Status: active
+Owner: strategy
+Updated: 2026-02-26
+-->
+
+# 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)

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 처리 일관성 확인
+- 모델 버전/설정 해시/실험 로그 재현성 확보
+
+끝.

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 구현(코드)로 이동.
+
+끝.

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"<!--\n"
+    r"Doc-ID: (?P<doc_id>[^\n]+)\n"
+    r"Version: (?P<version>[^\n]+)\n"
+    r"Status: (?P<status>[^\n]+)\n"
+    r"Owner: (?P<owner>[^\n]+)\n"
+    r"Updated: (?P<updated>\d{4}-\d{2}-\d{2})\n"
+    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<id>(?:REQ|RULE|TASK|TEST|DOC)-[A-Z0-9-]+-\d{3})`", re.MULTILINE)
+LINK_PATTERN = re.compile(r"\[[^\]]+\]\((?P<link>[^)]+)\)")
+LINE_DEF_PATTERN = re.compile(r"^-\s+`(?P<id>(?: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())