docs: add runtime verifier role and replan escalation protocol (#273 )

docs: add repository enforcement checklist for strict governance (#273 )
docs: add PM/TPM governance artifacts for multi-agent control (#273 )
2026-02-26 23:16:44 +09:00 · 2026-02-26 23:08:16 +09:00 · 2026-02-26 23:06:51 +09:00 · 2026-02-26 22:56:17 +09:00 · 2026-02-26 22:52:56 +09:00 · 2026-02-26 22:49:21 +09:00
34 changed files with 2424 additions and 383 deletions
--- a/docs/ouroboros/00_validation_system.md
+++ b/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)과 모순 없음
--- a/docs/ouroboros/01_requirements_registry.md
+++ b/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`: 구현 태스크는 반드시 테스트 태스크를 동반한다.
--- a/docs/ouroboros/10_phase_v2_execution.md
+++ b/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)
--- a/docs/ouroboros/20_phase_v3_execution.md
+++ b/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)
--- a/docs/ouroboros/30_code_level_work_orders.md
+++ b/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개 테스트 연결
--- a/docs/ouroboros/40_acceptance_and_test_plan.md
+++ b/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-*` 변경 후 테스트 매핑 누락 시 병합 금지
 - 회귀 실패 시 원인 모듈 분리 후 재검증
--- a/docs/ouroboros/50_scenario_matrix_and_issue_taxonomy.md
+++ b/docs/ouroboros/50_scenario_matrix_and_issue_taxonomy.md
@@ -0,0 +1,68 @@
 <!--
 Doc-ID: DOC-PM-001
 Version: 1.0.0
 Status: active
 Owner: strategy
 Updated: 2026-02-26
 -->
 # 실전 시나리오 매트릭스 + 이슈 분류 체계
 목표: 운영에서 바로 사용할 수 있는 형태로 Happy Path / Failure Path / Ops Incident를 추적 가능한 ID 체계(`REQ-*`, `TASK-*`, `TEST-*`)에 매핑한다.
 ## 1) 시나리오 매트릭스
 | Scenario ID | Type | Trigger | Expected System Behavior | Primary IDs (REQ/TASK/TEST) | Ticket Priority |
 |---|---|---|---|---|---|
 | `SCN-HAPPY-001` | Happy Path | KR 정규 세션에서 진입 신호 발생, 블랙아웃 아님 | 주문/로그에 `session_id` 저장 후 정책에 맞는 주문 전송 | `REQ-V3-001`, `TASK-V3-001`, `TASK-V3-003`, `TEST-ACC-015` | P1 |
 | `SCN-HAPPY-002` | Happy Path | 보유 포지션에서 BE/ATR/Hard Stop 조건 순차 도달 | 상태가 즉시 상위 단계로 승격, `EXITED` 우선 평가 보장 | `REQ-V2-002`, `REQ-V2-003`, `TASK-V2-004`, `TEST-ACC-001`, `TEST-ACC-010` | P0 |
 | `SCN-HAPPY-003` | Happy Path | 세션 전환(KR->US) 이벤트 발생 | 리스크 파라미터 자동 재로딩, 새 세션 정책으로 즉시 전환 | `REQ-V3-002`, `TASK-V3-002`, `TEST-ACC-016` | P0 |
 | `SCN-HAPPY-004` | Happy Path | 백테스트 실행 요청 | 비용/슬리피지/체결실패 옵션 누락 시 실행 거부, 포함 시 실행 | `REQ-V2-007`, `TASK-V2-012`, `TEST-ACC-014` | P1 |
 | `SCN-FAIL-001` | Failure Path | 블랙아웃 중 신규 주문 신호 발생 | 신규 주문 차단 + 주문 의도 큐 적재, API 직접 호출 금지 | `REQ-V3-003`, `REQ-V3-004`, `TASK-V3-005`, `TEST-ACC-003`, `TEST-ACC-017` | P0 |
 | `SCN-FAIL-002` | Failure Path | 저유동 세션에 시장가 주문 요청 | 시장가 하드 거부, 지정가 대체 또는 주문 취소 | `REQ-V3-005`, `TASK-V3-007`, `TASK-V3-008`, `TEST-ACC-004` | P0 |
 | `SCN-FAIL-003` | Failure Path | Kill Switch 트리거(손실/연결/리스크 한도) | 신규주문차단->미체결취소->재조회->리스크축소->스냅샷 순서 강제 | `REQ-V2-008`, `TASK-V2-013`, `TEST-ACC-002` | P0 |
 | `SCN-FAIL-004` | Failure Path | FX 버퍼 부족 상태에서 US 진입 신호 | 전략 PnL/FX PnL 분리 집계 유지, 신규 진입 제한 | `REQ-V3-007`, `TASK-V3-013`, `TASK-V3-014`, `TEST-ACC-006` | P1 |
 | `SCN-OPS-001` | Ops Incident | 브로커 점검/블랙아웃 종료 직후 | 잔고/미체결/체결 동기화 후 큐 재검증 통과 주문만 집행 | `REQ-V3-004`, `TASK-V3-006`, `TEST-ACC-017` | P0 |
 | `SCN-OPS-002` | Ops Incident | 정책 수치가 코드에만 반영되고 원장 미수정 | 문서 검증에서 실패 처리, PR 병합 차단 | `REQ-OPS-002`, `TASK-OPS-002`, `TEST-ACC-008` | P0 |
 | `SCN-OPS-003` | Ops Incident | 타임존 누락 로그/스케줄 데이터 유입 | KST/UTC 미표기 레코드 검증 실패 처리 | `REQ-OPS-001`, `TASK-OPS-001`, `TEST-ACC-007` | P1 |
 | `SCN-OPS-004` | Ops Incident | 신규 REQ 추가 후 TASK/TEST 누락 | 추적성 게이트 실패, 구현 PR 병합 차단 | `REQ-OPS-003`, `TASK-OPS-003`, `TEST-ACC-009` | P0 |
 | `SCN-OPS-005` | Ops Incident | 배포 후 런타임 이상 동작(주문오류/상태전이오류/정책위반) 탐지 | Runtime Verifier가 즉시 이슈 발행, Dev 수정 후 재관측으로 클로즈 판정 | `REQ-V2-008`, `REQ-V3-003`, `REQ-V3-005`, `TEST-ACC-002`, `TEST-ACC-003`, `TEST-ACC-004` | P0 |
 ## 2) 이슈 분류 체계 (Issue Taxonomy)
 | Taxonomy | Definition | Typical Symptoms | Default Owner | Mapping Baseline |
 |---|---|---|---|---|
 | `EXEC-STATE` | 상태기계/청산 우선순위 위반 | EXIT 우선순위 깨짐, 상태 역행, 갭 대응 실패 | Strategy | `REQ-V2-001`~`REQ-V2-004`, `TASK-V2-004`~`TASK-V2-006`, `TEST-ACC-000`,`001`,`010`,`011` |
 | `EXEC-POLICY` | 세션/주문 정책 위반 | 블랙아웃 주문 전송, 저유동 시장가 허용 | Broker/Execution | `REQ-V3-003`~`REQ-V3-005`, `TASK-V3-004`~`TASK-V3-009`, `TEST-ACC-003`,`004`,`017` |
 | `BACKTEST-MODEL` | 백테스트 현실성/검증 무결성 위반 | 비용 옵션 off로 실행, 체결가 과낙관 | Research | `REQ-V2-006`,`REQ-V2-007`,`REQ-V3-006`, `TASK-V2-010`~`012`, `TASK-V3-010`~`012`, `TEST-ACC-013`,`014`,`005` |
 | `RISK-EMERGENCY` | Kill Switch/리스크 비상 대응 실패 | 순서 위반, 차단 누락, 복구 절차 누락 | Risk | `REQ-V2-008`,`REQ-V3-008`, `TASK-V2-013`~`015`, `TASK-V3-015`, `TEST-ACC-002`,`018` |
 | `FX-ACCOUNTING` | 환율/통화 버퍼 정책 위반 | 전략손익/환차손익 혼합 집계, 버퍼 미적용 | Risk + Data | `REQ-V3-007`, `TASK-V3-013`,`014`, `TEST-ACC-006` |
 | `OPS-GOVERNANCE` | 문서/추적성/타임존 거버넌스 위반 | 원장 미수정, TEST 누락, 타임존 미표기 | PM + QA | `REQ-OPS-001`~`003`, `TASK-OPS-001`~`003`, `TEST-ACC-007`~`009` |
 | `RUNTIME-VERIFY` | 실동작 모니터링 검증 | 배포 후 이상 현상, 간헐 오류, 테스트 미포착 회귀 | Runtime Verifier + TPM | 관련 `REQ/TASK/TEST`와 런타임 로그 증적 필수 |
 ## 3) 티켓 생성 규칙 (Implementable)
 1. 모든 이슈는 `taxonomy + scenario_id`를 제목에 포함한다.  
   예: `[EXEC-POLICY][SCN-FAIL-001] blackout 주문 차단 누락`
 2. 본문 필수 항목: 재현절차, 기대결과, 실제결과, 영향범위, 롤백/완화책.
 3. 본문에 최소 1개 `REQ-*`, 1개 `TASK-*`, 1개 `TEST-*`를 명시한다.
 4. 우선순위 기준:
 - P0: 실주문 위험, Kill Switch, 블랙아웃/시장가 정책, 추적성 게이트 실패
 - P1: 손익 왜곡 가능성(체결/FX/시간대), 운영 리스크 증가
 - P2: 보고서/관측성 품질 이슈(거래 안전성 영향 없음)
 5. Runtime Verifier가 발행한 `RUNTIME-VERIFY` 이슈는 Main Agent 확인 전 클로즈 금지.
 ## 4) 즉시 생성 권장 티켓 (초기 백로그)
 - `TKT-P0-001`: `[EXEC-POLICY][SCN-FAIL-001]` 블랙아웃 차단 + 큐적재 + 복구 재검증 e2e 점검 (`REQ-V3-003`,`REQ-V3-004`)
 - `TKT-P0-002`: `[RISK-EMERGENCY][SCN-FAIL-003]` Kill Switch 순서 강제 검증 자동화 (`REQ-V2-008`)
 - `TKT-P0-003`: `[OPS-GOVERNANCE][SCN-OPS-004]` REQ/TASK/TEST 누락 시 PR 차단 게이트 상시 점검 (`REQ-OPS-003`)
 - `TKT-P1-001`: `[FX-ACCOUNTING][SCN-FAIL-004]` FX 버퍼 위반 시 진입 제한 회귀 케이스 보강 (`REQ-V3-007`)
 - `TKT-P1-002`: `[BACKTEST-MODEL][SCN-HAPPY-004]` 비용/슬리피지 미설정 백테스트 거부 UX 명확화 (`REQ-V2-007`)
 - `TKT-P0-004`: `[RUNTIME-VERIFY][SCN-OPS-005]` 배포 후 런타임 이상 탐지/재현/클로즈 판정 절차 자동화
 ## 5) 운영 체크포인트
 - 스프린트 계획 시 `P0` 시나리오 100% 테스트 통과를 출발 조건으로 둔다.
 - 배포 승인 시 `SCN-FAIL-*`, `SCN-OPS-*` 관련 `TEST-ACC-*`를 우선 확인한다.
 - 정책 변경 PR은 반드시 원장(`01_requirements_registry.md`) 선수정 후 진행한다.
--- a/docs/ouroboros/50_tpm_control_protocol.md
+++ b/docs/ouroboros/50_tpm_control_protocol.md
@@ -0,0 +1,176 @@
 <!--
 Doc-ID: DOC-TPM-001
 Version: 1.0.0
 Status: active
 Owner: tpm
 Updated: 2026-02-26
 -->
 # TPM Control Protocol (Main <-> PM <-> TPM <-> Dev <-> Verifier <-> Runtime Verifier)
 목적:
 - PM 시나리오가 구현 가능한 단위로 분해되고, 개발/검증이 동일 ID 체계(`REQ-*`, `TASK-*`, `TEST-*`)로 닫히도록 강제한다.
 - 각 단계는 Entry/Exit gate를 통과해야 다음 단계로 이동 가능하다.
 - 주요 의사결정 포인트마다 Main Agent의 승인/의견 확인을 강제한다.
 ## Team Roles
 - Main Agent: 최종 취합/우선순위/승인 게이트 오너
 - PM Agent: 시나리오/요구사항/티켓 관리
 - TPM Agent: PM-Dev-검증 간 구현 가능성/달성률 통제
 - Dev Agent: 구현 수행, 블로커 발생 시 재계획 요청
 - Verifier Agent: 문서/코드/테스트 산출물 검증
 - Runtime Verifier Agent: 실제 동작 모니터링, 이상 징후 이슈 발행, 수정 후 이슈 클로즈 판정
 ## Main Decision Checkpoints (Mandatory)
 - DCP-01 범위 확정: Phase 0 종료 전 Main Agent 승인 필수
 - DCP-02 요구사항 확정: Phase 1 종료 전 Main Agent 승인 필수
 - DCP-03 구현 착수: Phase 2 종료 전 Main Agent 승인 필수
 - DCP-04 배포 승인: Phase 4 종료 후 Main Agent 최종 승인 필수
 ## Phase Control Gates
 ### Phase 0: Scenario Intake and Scope Lock
 Entry criteria:
 - PM 시나리오가 사용자 가치, 실패 모드, 우선순위를 포함해 제출됨
 - 영향 범위(모듈/세션/KR-US 시장)가 명시됨
 Exit criteria:
 - 시나리오가 `REQ-*` 후보에 1:1 또는 1:N 매핑됨
 - 모호한 표현("개선", "최적화")은 측정 가능한 조건으로 치환됨
 - 비범위 항목(out-of-scope) 명시
 Control checks:
 - PM/TPM 합의 완료
 - Main Agent 승인(DCP-01)
 - 산출물: 시나리오 카드, 초기 매핑 메모
 ### Phase 1: Requirement Registry Gate
 Entry criteria:
 - Phase 0 산출물 승인
 - 변경 대상 요구사항 문서 식별 완료
 Exit criteria:
 - [01_requirements_registry.md](./01_requirements_registry.md)에 `REQ-*` 정의/수정 반영
 - 각 `REQ-*`가 최소 1개 `TASK-*`, 1개 `TEST-*`와 연결 가능 상태
 - 시간/정책 수치는 원장 단일 소스로 확정(`REQ-OPS-001`,`REQ-OPS-002`)
 Control checks:
 - `python3 scripts/validate_ouroboros_docs.py` 통과
 - Main Agent 승인(DCP-02)
 - 산출물: 업데이트된 요구사항 원장
 ### Phase 2: Design and Work-Order Gate
 Entry criteria:
 - 요구사항 원장 갱신 완료
 - 영향 모듈 분석 완료(상태기계, 주문정책, 백테스트, 세션)
 Exit criteria:
 - [10_phase_v2_execution.md](./10_phase_v2_execution.md), [20_phase_v3_execution.md](./20_phase_v3_execution.md), [30_code_level_work_orders.md](./30_code_level_work_orders.md)에 작업 분해 완료
 - 각 작업은 구현 위치/제약/완료 조건을 가짐
 - 위험 작업(Kill Switch, blackout, session transition)은 별도 롤백 절차 포함
 Control checks:
 - TPM이 `REQ -> TASK` 누락 여부 검토
 - Main Agent 승인(DCP-03)
 - 산출물: 승인된 Work Order 세트
 ### Phase 3: Implementation Gate
 Entry criteria:
 - 승인된 `TASK-*`가 브랜치 작업 단위로 분리됨
 - 변경 범위별 테스트 계획이 PR 본문에 링크됨
 Exit criteria:
 - 코드 변경이 `TASK-*`에 대응되어 추적 가능
 - 제약 준수(`src/core/risk_manager.py` 직접 수정 금지 등) 확인
 - 신규 로직마다 최소 1개 테스트 추가 또는 기존 테스트 확장
 Control checks:
 - PR 템플릿 내 `REQ-*`/`TASK-*`/`TEST-*` 매핑 확인
 - 산출물: 리뷰 가능한 PR
 ### Phase 4: Verification and Acceptance Gate
 Entry criteria:
 - 구현 PR ready 상태
 - 테스트 케이스/픽스처 준비 완료
 Exit criteria:
 - [40_acceptance_and_test_plan.md](./40_acceptance_and_test_plan.md)의 해당 `TEST-ACC-*` 전부 통과
 - 회귀 테스트 통과(`pytest -q`)
 - 문서 검증 통과(`python3 scripts/validate_ouroboros_docs.py`)
 Control checks:
 - Verifier가 테스트 증적(로그/리포트/실행 커맨드) 첨부
 - Runtime Verifier가 스테이징/실운영 모니터링 계획 승인
 - 산출물: 수용 승인 레코드
 ### Phase 5: Release and Post-Release Control
 Entry criteria:
 - Phase 4 승인
 - 운영 체크리스트 준비(세션 전환, 블랙아웃, Kill Switch)
 Exit criteria:
 - 배포 후 초기 관찰 윈도우에서 치명 경보 없음
 - 신규 시나리오/회귀 이슈는 다음 Cycle의 Phase 0 입력으로 환류
 - 요구사항/테스트 문서 버전 동기화 완료
 Control checks:
 - PM/TPM/Dev 3자 종료 확인
 - Runtime Verifier가 운영 모니터링 이슈 상태(신규/진행/해결)를 리포트
 - Main Agent 최종 승인(DCP-04)
 - 산출물: 릴리즈 노트 + 후속 액션 목록
 ## Replan Protocol (Dev -> TPM)
 - 트리거:
  - 구현 불가능(기술적 제약/외부 API 제약)
  - 예상 대비 개발 리소스 과다(공수/인력/의존성 급증)
 - 절차:
  1) Dev Agent가 `REPLAN-REQUEST` 발행(영향 REQ/TASK, 원인, 대안, 추가 공수 포함)
  2) TPM Agent가 1차 심사(범위 축소/단계 분할/요구사항 조정안)
  3) Verifier/PM 의견 수렴 후 Main Agent 승인으로 재계획 확정
 - 규칙:
  - Main Agent 승인 없는 재계획은 실행 금지
  - 재계획 반영 시 문서(`REQ/TASK/TEST`) 동시 갱신 필수
 ## Runtime Verification Protocol
 - Runtime Verifier는 테스트 통과 이후 실제 동작(스테이징/실운영)을 모니터링한다.
 - 이상 동작/현상 발견 시 즉시 이슈 발행:
  - 제목 규칙: `[RUNTIME-VERIFY][SCN-*] ...`
  - 본문 필수: 재현조건, 관측 로그, 영향 범위, 임시 완화책, 관련 `REQ/TASK/TEST`
 - 이슈 클로즈 규칙:
  - Dev 수정 완료 + Verifier 재검증 통과 + Runtime Verifier 재관측 정상
  - 최종 클로즈 승인자는 Main Agent
 ## Acceptance Matrix (PM Scenario -> Dev Tasks -> Verifier Checks)
 | PM Scenario | Requirement Coverage | Dev Tasks (Primary) | Verifier Checks (Must Pass) |
 |---|---|---|---|
 | 갭 급락/급등에서 청산 우선 처리 필요 | `REQ-V2-001`,`REQ-V2-002`,`REQ-V2-003` | `TASK-V2-004`,`TASK-CODE-001` | `TEST-ACC-000`,`TEST-ACC-001`,`TEST-ACC-010`,`TEST-CODE-001`,`TEST-CODE-002` |
 | 하드스탑 + BE락 + ATR + 모델보조를 한 엔진으로 통합 | `REQ-V2-004` | `TASK-V2-005`,`TASK-V2-006`,`TASK-CODE-002` | `TEST-ACC-011` |
 | 라벨 누수 없는 학습데이터 생성 | `REQ-V2-005` | `TASK-V2-007`,`TASK-CODE-004` | `TEST-ACC-012`,`TEST-CODE-003` |
 | 검증 프레임워크를 시계열 누수 방지 구조로 강제 | `REQ-V2-006` | `TASK-V2-010`,`TASK-CODE-005` | `TEST-ACC-013`,`TEST-CODE-004` |
 | 과낙관 백테스트 방지(비용/슬리피지/실패 강제) | `REQ-V2-007` | `TASK-V2-012`,`TASK-CODE-006` | `TEST-ACC-014` |
 | 장애 시 Kill Switch 실행 순서 고정 | `REQ-V2-008` | `TASK-V2-013`,`TASK-V2-014`,`TASK-V2-015`,`TASK-CODE-003` | `TEST-ACC-002`,`TEST-ACC-018` |
 | 세션 전환 단위 리스크/로그 추적 일관화 | `REQ-V3-001`,`REQ-V3-002` | `TASK-V3-001`,`TASK-V3-002`,`TASK-V3-003`,`TASK-CODE-007` | `TEST-ACC-015`,`TEST-ACC-016` |
 | 블랙아웃 중 주문 차단 + 복구 후 재검증 실행 | `REQ-V3-003`,`REQ-V3-004` | `TASK-V3-004`,`TASK-V3-005`,`TASK-V3-006`,`TASK-CODE-008` | `TEST-ACC-003`,`TEST-ACC-017`,`TEST-CODE-005` |
 | 저유동 세션 시장가 주문 금지 | `REQ-V3-005` | `TASK-V3-007`,`TASK-V3-008`,`TASK-CODE-009` | `TEST-ACC-004`,`TEST-CODE-006` |
 | 보수적 체결 모델을 백테스트 기본으로 설정 | `REQ-V3-006` | `TASK-V3-010`,`TASK-V3-011`,`TASK-V3-012`,`TASK-CODE-010` | `TEST-ACC-005`,`TEST-CODE-007` |
 | 전략손익/환율손익 분리 + 통화 버퍼 통제 | `REQ-V3-007` | `TASK-V3-013`,`TASK-V3-014`,`TASK-CODE-011` | `TEST-ACC-006`,`TEST-CODE-008` |
 | 오버나잇 규칙과 Kill Switch 충돌 방지 | `REQ-V3-008` | `TASK-V3-015`,`TASK-CODE-012` | `TEST-ACC-018` |
 | 타임존/정책변경/추적성 문서 거버넌스 | `REQ-OPS-001`,`REQ-OPS-002`,`REQ-OPS-003` | `TASK-OPS-001`,`TASK-OPS-002`,`TASK-OPS-003` | `TEST-ACC-007`,`TEST-ACC-008`,`TEST-ACC-009` |
 ## 운영 규율 (TPM Enforcement Rules)
 - 어떤 PM 시나리오도 `REQ-*` 없는 구현 착수 금지.
 - 어떤 `REQ-*`도 `TASK-*`,`TEST-*` 없는 승인 금지.
 - Verifier는 "코드 리뷰 통과"만으로 승인 불가, 반드시 `TEST-ACC-*` 증적 필요.
 - 배포 승인권자는 Phase 4 체크리스트 미충족 시 릴리즈 보류 권한을 행사해야 한다.
--- a/docs/ouroboros/60_repo_enforcement_checklist.md
+++ b/docs/ouroboros/60_repo_enforcement_checklist.md
@@ -0,0 +1,88 @@
 <!--
 Doc-ID: DOC-OPS-002
 Version: 1.0.0
 Status: active
 Owner: tpm
 Updated: 2026-02-26
 -->
 # 저장소 강제 설정 체크리스트
 목표: "엄격 검증 운영"을 문서가 아니라 저장소 설정으로 강제한다.
 ## 1) main 브랜치 보호 (필수)
 적용 항목:
 - direct push 금지
 - force push 금지
 - branch 삭제 금지
 - merge는 PR 경로만 허용
 검증:
 - `main`에 대해 직접 `git push origin main` 시 거부되는지 확인
 ## 2) 필수 상태 체크 (필수)
 필수 CI 항목:
 - `validate_ouroboros_docs` (명령: `python3 scripts/validate_ouroboros_docs.py`)
 - `test` (명령: `pytest -q`)
 설정 기준:
 - 위 2개 체크가 `success` 아니면 머지 금지
 - 체크 스킵/중립 상태 허용 금지
 ## 3) 필수 리뷰어 규칙 (권장 -> 필수)
 역할 기반 승인:
 - Verifier 1명 승인 필수
 - TPM 또는 PM 1명 승인 필수
 - Runtime Verifier 관련 변경(PR 본문에 runtime 영향 있음) 시 Runtime Verifier 승인 필수
 설정 기준:
 - 최소 승인 수: 2
 - 작성자 self-approval 불가
 - 새 커밋 푸시 시 기존 승인 재검토 요구
 ## 4) 워크플로우 게이트
 병합 전 체크리스트:
 - 이슈 연결(`Closes #N`) 존재
 - PR 본문에 `REQ-*`, `TASK-*`, `TEST-*` 매핑 표 존재
 - `src/core/risk_manager.py` 변경 없음
 - 주요 의사결정 체크포인트(DCP-01~04) 중 해당 단계 Main Agent 확인 기록 존재
 자동 점검:
 - 문서 검증 스크립트 통과
 - 테스트 통과
 ## 5) 감사 추적
 필수 보존 증적:
 - CI 실행 로그 링크
 - 검증 실패/복구 기록
 - 머지 승인 코멘트(Verifier/TPM)
 분기별 점검:
 - 브랜치 보호 규칙 drift 여부
 - 필수 CI 이름 변경/누락 여부
 ## 6) 적용 순서 (운영 절차)
 1. 브랜치 보호 활성화
 2. 필수 CI 체크 연결
 3. 리뷰어 규칙 적용
 4. 샘플 PR로 거부 시나리오 테스트
 5. 정상 머지 시나리오 테스트
 ## 7) 실패 시 조치
 - 브랜치 보호 미적용 발견 시: 즉시 릴리즈 중지
 - 필수 CI 우회 발견 시: 관리자 권한 점검 및 감사 이슈 발행
 - 리뷰 규칙 무효화 발견 시: 규칙 복구 후 재머지 정책 시행
 - Runtime 이상 이슈 미해결 상태에서 클로즈 시도 발견 시: 즉시 이슈 재오픈 + 릴리즈 중지
 ## 8) 재계획(Dev Replan) 운영 규칙
 - Dev가 `REPLAN-REQUEST` 발행 시 TPM 심사 없이는 스코프/일정 변경 금지
 - `REPLAN-REQUEST`는 Main Agent 승인 전 \"제안\" 상태로 유지
 - 승인된 재계획은 `REQ/TASK/TEST` 문서를 동시 갱신해야 유효
--- a/docs/ouroboros/README.md
+++ b/docs/ouroboros/README.md
@@ -0,0 +1,39 @@
 <!--
 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)
 7. PM 시나리오/이슈 분류: [50_scenario_matrix_and_issue_taxonomy.md](./50_scenario_matrix_and_issue_taxonomy.md)
 8. TPM 제어 프로토콜/수용 매트릭스: [50_tpm_control_protocol.md](./50_tpm_control_protocol.md)
 9. 저장소 강제 설정 체크리스트: [60_repo_enforcement_checklist.md](./60_repo_enforcement_checklist.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)
--- a/docs/requirements-log.md
+++ b/docs/requirements-log.md
@@ -322,3 +322,36 @@ Order result: 모의투자 매수주문이 완료 되었습니다.  ✓
   - `TestHandleDomesticPendingOrders` (4), `TestDomesticLimitOrderPrice` (2)
 **이슈/PR:** #232, PR #233
 ---
 ## 2026-02-24
 ### 해외잔고 ghost position 수정 — '모의투자 잔고내역이 없습니다' 반복 방지 (#235)
 **배경:**
 - 모의투자 실행 시 MLECW, KNRX, NBY, SNSE 등 만료/정지된 종목에 대해
  `모의투자 잔고내역이 없습니다` 오류가 매 사이클 반복됨
 **근본 원인:**
 1. `ovrs_cblc_qty` (해외잔고수량, 총 보유) vs `ord_psbl_qty` (주문가능수량, 실제 매도 가능)
   - 기존 코드: `ovrs_cblc_qty` 우선 사용 → 만료 Warrant가 `ovrs_cblc_qty=289456`이지만 실제 `ord_psbl_qty=0`
   - startup sync / build_overseas_symbol_universe가 이 종목들을 포지션으로 기록
 2. SELL 실패 시 DB 포지션이 닫히지 않아 다음 사이클에서도 재시도 (무한 반복)
 **구현 내용:**
 1. `src/main.py` — `_extract_held_codes_from_balance`, `_extract_held_qty_from_balance`
   - 해외 잔고 필드 우선순위 변경: `ord_psbl_qty` → `ovrs_cblc_qty` → `hldg_qty` (fallback 유지)
   - KIS 공식 문서(VTTS3012R) 기준: `ord_psbl_qty`가 실제 매도 가능 수량
 2. `src/main.py` — `trading_cycle` ghost-close 처리
   - 해외 SELL이 `잔고내역이 없습니다`로 실패 시 DB 포지션을 `[ghost-close]` SELL로 종료
   - exchange code 불일치 등 예외 상황에서 무한 반복 방지
 3. 테스트 7개 추가:
   - `TestExtractHeldQtyFromBalance` 3개: ord_psbl_qty 우선, 0이면 0 반환, fallback
   - `TestExtractHeldCodesFromBalance` 2개: ord_psbl_qty=0인 종목 제외, fallback
   - `TestOverseasGhostPositionClose` 2개: ghost-close 로그 확인, 일반 오류 무시
 **이슈/PR:** #235, PR #236
--- 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.**
--- a/ouroboros_plan_v2.txt
+++ 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 처리 일관성 확인
 - 모델 버전/설정 해시/실험 로그 재현성 확보
 끝.
--- a/ouroboros_plan_v3.txt
+++ 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 구현(코드)로 이동.
 끝.
--- a/scripts/run_overnight.sh
+++ b/scripts/run_overnight.sh
@@ -23,7 +23,7 @@ if [ -z "${APP_CMD:-}" ]; then
    dashboard_port="${DASHBOARD_PORT:-8080}"
-    APP_CMD="DASHBOARD_PORT=$dashboard_port $PYTHON_BIN -m src.main --mode=paper --dashboard"
+    APP_CMD="DASHBOARD_PORT=$dashboard_port $PYTHON_BIN -m src.main --mode=live --dashboard"
 fi
 mkdir -p "$LOG_DIR"
--- a/scripts/validate_ouroboros_docs.py
+++ 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"<!--\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())
--- a/src/brain/gemini_client.py
+++ b/src/brain/gemini_client.py
@@ -346,8 +346,10 @@ class GeminiClient:
        # Validate required fields
        if not all(k in data for k in ("action", "confidence", "rationale")):
            logger.warning("Missing fields in Gemini response — defaulting to HOLD")
            # Preserve raw text in rationale so prompt_override callers (e.g. pre_market_planner)
            # can extract their own JSON format from decision.rationale (#245)
            return TradeDecision(
-                action="HOLD", confidence=0, rationale="Missing required fields"
+                action="HOLD", confidence=0, rationale=raw
            )
        action = str(data["action"]).upper()
@@ -439,6 +441,18 @@ class GeminiClient:
                action="HOLD", confidence=0, rationale=f"API error: {exc}", token_count=token_count
            )
        # prompt_override callers (e.g. pre_market_planner) expect raw text back,
        # not a parsed TradeDecision. Skip parse_response to avoid spurious
        # "Missing fields" warnings and return the raw response directly. (#247)
        if "prompt_override" in market_data:
            logger.info(
                "Gemini raw response received (prompt_override, tokens=%d)", token_count
            )
            # Not a trade decision — don't inflate _total_decisions metrics
            return TradeDecision(
                action="HOLD", confidence=0, rationale=raw, token_count=token_count
            )
        decision = self.parse_response(raw)
        self._total_decisions += 1
--- a/src/brain/prompt_optimizer.py
+++ b/src/brain/prompt_optimizer.py
@@ -179,8 +179,8 @@ class PromptOptimizer:
            # Minimal instructions
            prompt = (
                f"{market_name} trader. Analyze:\n{data_str}\n\n"
-                'Return JSON: {"act":"BUY"|"SELL"|"HOLD","conf":<0-100>,"reason":"<text>"}\n'
+                'Return JSON: {"action":"BUY"|"SELL"|"HOLD","confidence":<0-100>,"rationale":"<text>"}\n'
-                "Rules: act=BUY/SELL/HOLD, conf=0-100, reason=concise. No markdown."
+                "Rules: action=BUY/SELL/HOLD, confidence=0-100, rationale=concise. No markdown."
            )
        else:
            # Data only (for cached contexts where instructions are known)
--- a/src/broker/kis_api.py
+++ b/src/broker/kis_api.py
@@ -430,7 +430,7 @@ class KISBroker:
                "fid_cond_mrkt_div_code": "J",
                "fid_cond_scr_div_code": "20170",
                "fid_input_iscd": "0000",
-                "fid_rank_sort_cls_code": "0000",
+                "fid_rank_sort_cls_code": "0",
                "fid_input_cnt_1": str(limit),
                "fid_prc_cls_code": "0",
                "fid_input_price_1": "0",
@@ -466,7 +466,7 @@ class KISBroker:
            rankings = []
            for item in data.get("output", [])[:limit]:
                rankings.append({
-                    "stock_code": item.get("mksc_shrn_iscd", ""),
+                    "stock_code": item.get("stck_shrn_iscd") or item.get("mksc_shrn_iscd", ""),
                    "name": item.get("hts_kor_isnm", ""),
                    "price": _safe_float(item.get("stck_prpr", "0")),
                    "volume": _safe_float(item.get("acml_vol", "0")),
--- a/src/broker/overseas.py
+++ b/src/broker/overseas.py
@@ -121,6 +121,7 @@ class OverseasBroker:
            tr_id = self._broker._settings.OVERSEAS_RANKING_VOLUME_TR_ID
            path = self._broker._settings.OVERSEAS_RANKING_VOLUME_PATH
            params: dict[str, str] = {
                "KEYB": "",  # NEXT KEY BUFF — Required, 공백
                "AUTH": "",
                "EXCD": ranking_excd,
                "MIXN": "0",
@@ -130,10 +131,11 @@ class OverseasBroker:
            tr_id = self._broker._settings.OVERSEAS_RANKING_FLUCT_TR_ID
            path = self._broker._settings.OVERSEAS_RANKING_FLUCT_PATH
            params = {
                "KEYB": "",  # NEXT KEY BUFF — Required, 공백
                "AUTH": "",
                "EXCD": ranking_excd,
                "NDAY": "0",
-                "GUBN": "1",
+                "GUBN": "1",  # 0=하락율, 1=상승율 — 변동성 스캐너는 급등 종목 우선
                "VOL_RANG": "0",
            }
@@ -220,6 +222,59 @@ class OverseasBroker:
                f"Network error fetching overseas balance: {exc}"
            ) from exc
    async def get_overseas_buying_power(
        self,
        exchange_code: str,
        stock_code: str,
        price: float,
    ) -> dict[str, Any]:
        """
        Fetch overseas buying power for a specific stock and price.
        Args:
            exchange_code: Exchange code (e.g., "NASD", "NYSE")
            stock_code: Stock ticker symbol
            price: Current stock price (used for quantity calculation)
        Returns:
            API response; key field: output.ord_psbl_frcr_amt (주문가능외화금액)
        Raises:
            ConnectionError: On network or API errors
        """
        await self._broker._rate_limiter.acquire()
        session = self._broker._get_session()
        # TR_ID: 실전 TTTS3007R, 모의 VTTS3007R
        # Source: 한국투자증권 오픈API 전체문서 (20260221) — '해외주식 매수가능금액조회' 시트
        ps_tr_id = (
            "TTTS3007R" if self._broker._settings.MODE == "live" else "VTTS3007R"
        )
        headers = await self._broker._auth_headers(ps_tr_id)
        params = {
            "CANO": self._broker._account_no,
            "ACNT_PRDT_CD": self._broker._product_cd,
            "OVRS_EXCG_CD": exchange_code,
            "OVRS_ORD_UNPR": f"{price:.2f}",
            "ITEM_CD": stock_code,
        }
        url = (
            f"{self._broker._base_url}/uapi/overseas-stock/v1/trading/inquire-psamount"
        )
        try:
            async with session.get(url, headers=headers, params=params) as resp:
                if resp.status != 200:
                    text = await resp.text()
                    raise ConnectionError(
                        f"get_overseas_buying_power failed ({resp.status}): {text}"
                    )
                return await resp.json()
        except (TimeoutError, aiohttp.ClientError) as exc:
            raise ConnectionError(
                f"Network error fetching overseas buying power: {exc}"
            ) from exc
    async def send_overseas_order(
        self,
        exchange_code: str,
--- a/src/dashboard/app.py
+++ b/src/dashboard/app.py
@@ -13,10 +13,11 @@ from fastapi import FastAPI, HTTPException, Query
 from fastapi.responses import FileResponse
-def create_dashboard_app(db_path: str) -> FastAPI:
+def create_dashboard_app(db_path: str, mode: str = "paper") -> FastAPI:
    """Create dashboard FastAPI app bound to a SQLite database path."""
    app = FastAPI(title="The Ouroboros Dashboard", version="1.0.0")
    app.state.db_path = db_path
    app.state.mode = mode
    @app.get("/")
    def index() -> FileResponse:
@@ -111,6 +112,7 @@ def create_dashboard_app(db_path: str) -> FastAPI:
            return {
                "date": today,
                "mode": mode,
                "markets": market_status,
                "totals": {
                    "trade_count": total_trades,
--- a/src/dashboard/static/index.html
+++ b/src/dashboard/static/index.html
@@ -43,6 +43,19 @@
        font-size: 12px; transition: border-color 0.2s;
      }
      .refresh-btn:hover { border-color: var(--accent); color: var(--accent); }
      .mode-badge {
        padding: 3px 10px; border-radius: 5px; font-size: 12px; font-weight: 700;
        letter-spacing: 0.5px;
      }
      .mode-badge.live {
        background: rgba(224, 85, 85, 0.15); color: var(--red);
        border: 1px solid rgba(224, 85, 85, 0.4);
        animation: pulse-warn 2s ease-in-out infinite;
      }
      .mode-badge.paper {
        background: rgba(232, 160, 64, 0.15); color: var(--warn);
        border: 1px solid rgba(232, 160, 64, 0.4);
      }
      /* CB Gauge */
      .cb-gauge-wrap {
@@ -225,6 +238,7 @@
      <header>
        <h1>&#x1F40D; The Ouroboros</h1>
        <div class="header-right">
          <span class="mode-badge" id="mode-badge">--</span>
          <div class="cb-gauge-wrap" id="cb-gauge" title="Circuit Breaker">
            <span class="cb-dot unknown" id="cb-dot"></span>
            <span id="cb-label">CB --</span>
@@ -512,9 +526,22 @@
          }
          document.getElementById('card-pnl-sub').textContent = `결정 ${t.decision_count ?? 0}건`;
          renderCbGauge(d.circuit_breaker);
          renderModeBadge(d.mode);
        } catch {}
      }
      function renderModeBadge(mode) {
        const el = document.getElementById('mode-badge');
        if (!el) return;
        if (mode === 'live') {
          el.textContent = '🔴 실전투자';
          el.className = 'mode-badge live';
        } else {
          el.textContent = '🟡 모의투자';
          el.className = 'mode-badge paper';
        }
      }
      async function fetchPerformance() {
        try {
          const r = await fetch('/api/performance?market=all');
--- a/src/db.py
+++ b/src/db.py
@@ -254,10 +254,11 @@ def get_open_position(
    """Return open position if latest trade is BUY, else None."""
    cursor = conn.execute(
        """
-        SELECT action, decision_id, price, quantity
+        SELECT action, decision_id, price, quantity, timestamp
        FROM trades
        WHERE stock_code = ?
          AND market = ?
          AND action IN ('BUY', 'SELL')
        ORDER BY timestamp DESC
        LIMIT 1
        """,
@@ -266,7 +267,7 @@ def get_open_position(
    row = cursor.fetchone()
    if not row or row[0] != "BUY":
        return None
-    return {"decision_id": row[1], "price": row[2], "quantity": row[3]}
+    return {"decision_id": row[1], "price": row[2], "quantity": row[3], "timestamp": row[4]}
 def get_recent_symbols(
--- a/src/main.py
+++ b/src/main.py
@@ -182,6 +182,9 @@ async def sync_positions_from_broker(
            qty = _extract_held_qty_from_balance(
                balance_data, stock_code, is_domestic=market.is_domestic
            )
            avg_price = _extract_avg_price_from_balance(
                balance_data, stock_code, is_domestic=market.is_domestic
            )
            log_trade(
                conn=db_conn,
                stock_code=stock_code,
@@ -189,7 +192,7 @@ async def sync_positions_from_broker(
                confidence=0,
                rationale="[startup-sync] Position detected from broker at startup",
                quantity=qty,
-                price=0.0,
+                price=avg_price,
                market=log_market,
                exchange_code=market.exchange_code,
                mode=settings.MODE,
@@ -257,7 +260,15 @@ def _extract_held_codes_from_balance(
        if is_domestic:
            qty = int(holding.get("ord_psbl_qty") or holding.get("hldg_qty") or 0)
        else:
-            qty = int(holding.get("ovrs_cblc_qty") or holding.get("hldg_qty") or 0)
+            # ord_psbl_qty (주문가능수량) is the actual sellable quantity.
            # ovrs_cblc_qty (해외잔고수량) includes unsettled/expired holdings
            # that cannot actually be sold (e.g. expired warrants).
            qty = int(
                holding.get("ord_psbl_qty")
                or holding.get("ovrs_cblc_qty")
                or holding.get("hldg_qty")
                or 0
            )
        if qty > 0:
            codes.append(code)
    return codes
@@ -280,10 +291,12 @@ def _extract_held_qty_from_balance(
        ord_psbl_qty  — 주문가능수량 (preferred: excludes unsettled)
        hldg_qty      — 보유수량 (fallback)
-    Overseas fields (output1):
+    Overseas fields (VTTS3012R / TTTS3012R output1):
        ovrs_pdno     — 종목코드
-        ovrs_cblc_qty — 해외잔고수량 (preferred)
+        ord_psbl_qty  — 주문가능수량 (preferred: actual sellable qty)
-        hldg_qty      — 보유수량 (fallback)
+        ovrs_cblc_qty — 해외잔고수량 (fallback: total holding, may include
                        unsettled or expired positions with ord_psbl_qty=0)
        hldg_qty      — 보유수량 (last-resort fallback)
    """
    output1 = balance_data.get("output1", [])
    if isinstance(output1, dict):
@@ -301,11 +314,47 @@ def _extract_held_qty_from_balance(
        if is_domestic:
            qty = int(holding.get("ord_psbl_qty") or holding.get("hldg_qty") or 0)
        else:
-            qty = int(holding.get("ovrs_cblc_qty") or holding.get("hldg_qty") or 0)
+            qty = int(
                holding.get("ord_psbl_qty")
                or holding.get("ovrs_cblc_qty")
                or holding.get("hldg_qty")
                or 0
            )
        return qty
    return 0
 def _extract_avg_price_from_balance(
    balance_data: dict[str, Any],
    stock_code: str,
    *,
    is_domestic: bool,
 ) -> float:
    """Extract the broker-reported average purchase price for a stock.
    Uses ``pchs_avg_pric`` (매입평균가격) from the balance response (output1).
    Returns 0.0 when absent so callers can use ``if price > 0`` as sentinel.
    Domestic fields (VTTC8434R output1):  pdno, pchs_avg_pric
    Overseas fields (VTTS3012R output1):  ovrs_pdno, pchs_avg_pric
    """
    output1 = balance_data.get("output1", [])
    if isinstance(output1, dict):
        output1 = [output1]
    if not isinstance(output1, list):
        return 0.0
    for holding in output1:
        if not isinstance(holding, dict):
            continue
        code_key = "pdno" if is_domestic else "ovrs_pdno"
        held_code = str(holding.get(code_key, "")).strip().upper()
        if held_code != stock_code.strip().upper():
            continue
        return safe_float(holding.get("pchs_avg_pric"), 0.0)
    return 0.0
 def _determine_order_quantity(
    *,
    action: str,
@@ -428,6 +477,7 @@ async def trading_cycle(
    cycle_start_time = asyncio.get_event_loop().time()
    # 1. Fetch market data
    price_output: dict[str, Any] = {}  # Populated for overseas markets; used for fallback metrics
    if market.is_domestic:
        current_price, price_change_pct, foreigner_net = await broker.get_current_price(
            stock_code
@@ -459,9 +509,44 @@ async def trading_cycle(
            balance_info = {}
        total_eval = safe_float(balance_info.get("frcr_evlu_tota", "0") or "0")
        total_cash = safe_float(balance_info.get("frcr_dncl_amt_2", "0") or "0")
        purchase_total = safe_float(balance_info.get("frcr_buy_amt_smtl", "0") or "0")
        # Resolve current price first (needed for buying power API)
        price_output = price_data.get("output", {})
        current_price = safe_float(price_output.get("last", "0"))
        if current_price <= 0:
            market_candidates_lookup = scan_candidates.get(market.code, {})
            cand_lookup = market_candidates_lookup.get(stock_code)
            if cand_lookup and cand_lookup.price > 0:
                logger.debug(
                    "Price API returned 0 for %s; using scanner candidate price %.4f",
                    stock_code,
                    cand_lookup.price,
                )
                current_price = cand_lookup.price
        foreigner_net = 0.0  # Not available for overseas
        price_change_pct = safe_float(price_output.get("rate", "0"))
        # Fetch available foreign currency cash via inquire-psamount (TTTS3007R/VTTS3007R).
        # TTTS3012R output2 does not include a cash/deposit field — frcr_dncl_amt_2 does not exist.
        # Source: 한국투자증권 오픈API 전체문서 (20260221) — '해외주식 매수가능금액조회' 시트
        total_cash = 0.0
        if current_price > 0:
            try:
                ps_data = await overseas_broker.get_overseas_buying_power(
                    market.exchange_code, stock_code, current_price
                )
                total_cash = safe_float(
                    ps_data.get("output", {}).get("ovrs_ord_psbl_amt", "0") or "0"
                )
            except ConnectionError as exc:
                logger.warning(
                    "Could not fetch overseas buying power for %s/%s: %s",
                    market.exchange_code,
                    stock_code,
                    exc,
                )
        # Paper mode fallback: VTS overseas balance API often fails for many accounts.
        # Only activate in paper mode — live mode must use real balance from KIS.
        if (
@@ -477,34 +562,6 @@ async def trading_cycle(
            )
            total_cash = settings.PAPER_OVERSEAS_CASH
        current_price = safe_float(price_data.get("output", {}).get("last", "0"))
        # Fallback: if price API returns 0, use scanner candidate price
        if current_price <= 0:
            market_candidates_lookup = scan_candidates.get(market.code, {})
            cand_lookup = market_candidates_lookup.get(stock_code)
            if cand_lookup and cand_lookup.price > 0:
                logger.debug(
                    "Price API returned 0 for %s; using scanner candidate price %.4f",
                    stock_code,
                    cand_lookup.price,
                )
                current_price = cand_lookup.price
        foreigner_net = 0.0  # Not available for overseas
        price_change_pct = safe_float(price_data.get("output", {}).get("rate", "0"))
        # Price API may return 0/empty for certain VTS exchange codes.
        # Fall back to the scanner candidate's price so order sizing still works.
        if current_price <= 0:
            market_candidates_lookup = scan_candidates.get(market.code, {})
            cand_lookup = market_candidates_lookup.get(stock_code)
            if cand_lookup and cand_lookup.price > 0:
                current_price = cand_lookup.price
                logger.debug(
                    "Price API returned 0 for %s; using scanner price %.4f",
                    stock_code,
                    current_price,
                )
    # Calculate daily P&L %
    pnl_pct = (
        ((total_eval - purchase_total) / purchase_total * 100)
@@ -526,6 +583,44 @@ async def trading_cycle(
    if candidate:
        market_data["rsi"] = candidate.rsi
        market_data["volume_ratio"] = candidate.volume_ratio
    else:
        # Holding stocks not in scanner: derive metrics from price API data already fetched.
        # For overseas stocks, price_output contains high/low/rate from get_overseas_price.
        # For domestic stocks, only price_change_pct is available from get_current_price.
        market_data["rsi"] = max(0.0, min(100.0, 50.0 + price_change_pct * 2.0))
        if price_output and current_price > 0:
            pr_high = safe_float(
                price_output.get("high") or price_output.get("ovrs_hgpr")
                or price_output.get("stck_hgpr")
            )
            pr_low = safe_float(
                price_output.get("low") or price_output.get("ovrs_lwpr")
                or price_output.get("stck_lwpr")
            )
            if pr_high > 0 and pr_low > 0 and pr_high >= pr_low:
                intraday_range_pct = (pr_high - pr_low) / current_price * 100.0
                volatility_pct = max(abs(price_change_pct), intraday_range_pct)
                market_data["volume_ratio"] = max(1.0, volatility_pct / 2.0)
            else:
                market_data["volume_ratio"] = 1.0
        else:
            market_data["volume_ratio"] = 1.0
    # Enrich market_data with holding info for SELL/HOLD scenario conditions
    open_pos = get_open_position(db_conn, stock_code, market.code)
    if open_pos and current_price > 0:
        entry_price = safe_float(open_pos.get("price"), 0.0)
        if entry_price > 0:
            market_data["unrealized_pnl_pct"] = (
                (current_price - entry_price) / entry_price * 100
            )
        entry_ts = open_pos.get("timestamp")
        if entry_ts:
            try:
                entry_date = datetime.fromisoformat(entry_ts).date()
                market_data["holding_days"] = (datetime.now(UTC).date() - entry_date).days
            except (ValueError, TypeError):
                pass
    # 1.3. Record L7 real-time context (market-scoped keys)
    timeframe = datetime.now(UTC).isoformat()
@@ -681,7 +776,7 @@ async def trading_cycle(
        open_position = get_open_position(db_conn, stock_code, market.code)
        if open_position:
            entry_price = safe_float(open_position.get("price"), 0.0)
-            if entry_price > 0:
+            if entry_price > 0 and current_price > 0:
                loss_pct = (current_price - entry_price) / entry_price * 100
                stop_loss_threshold = -2.0
                take_profit_threshold = 3.0
@@ -876,10 +971,13 @@ async def trading_cycle(
            # - SELL: -0.2% below last price — ensures fill even when price dips slightly
            #   (placing at exact last price risks no-fill if the bid is just below).
            overseas_price: float
            # KIS requires at most 2 decimal places for prices >= $1 (≥1달러 소수점 2자리 제한).
            # Penny stocks (< $1) keep 4 decimal places to preserve price precision.
            _price_decimals = 2 if current_price >= 1.0 else 4
            if decision.action == "BUY":
-                overseas_price = round(current_price * 1.002, 4)
+                overseas_price = round(current_price * 1.002, _price_decimals)
            else:
-                overseas_price = round(current_price * 0.998, 4)
+                overseas_price = round(current_price * 0.998, _price_decimals)
            result = await overseas_broker.send_overseas_order(
                exchange_code=market.exchange_code,
                stock_code=stock_code,
@@ -908,6 +1006,33 @@ async def trading_cycle(
                        stock_code,
                        _BUY_COOLDOWN_SECONDS,
                    )
                # Close ghost position when broker has no matching balance.
                # This prevents infinite SELL retry cycles for positions that
                # exist in the DB (from startup sync) but are no longer
                # sellable at the broker (expired warrants, delisted stocks, etc.)
                if decision.action == "SELL" and "잔고내역이 없습니다" in msg1:
                    logger.warning(
                        "Ghost position detected for %s (%s): broker reports no balance."
                        " Closing DB position to prevent infinite retry.",
                        stock_code,
                        market.exchange_code,
                    )
                    log_trade(
                        conn=db_conn,
                        stock_code=stock_code,
                        action="SELL",
                        confidence=0,
                        rationale=(
                            "[ghost-close] Broker reported no balance;"
                            " position closed without fill"
                        ),
                        quantity=0,
                        price=0.0,
                        pnl=0.0,
                        market=market.code,
                        exchange_code=market.exchange_code,
                        mode=settings.MODE if settings else "paper",
                    )
        logger.info("Order result: %s", result.get("msg1", "OK"))
        # 5.5. Notify trade execution (only on success)
@@ -1398,8 +1523,9 @@ async def run_daily_session(
                active_stocks={},
            )
            if not fallback_stocks:
-                logger.warning(
+                logger.debug(
-                    "No dynamic overseas symbol universe for %s; scanner cannot run",
+                    "No dynamic overseas symbol universe for %s;"
                    " scanner will use overseas ranking API",
                    market.code,
                )
        try:
@@ -1564,10 +1690,35 @@ async def run_daily_session(
                balance_info = {}
            total_eval = safe_float(balance_info.get("frcr_evlu_tota", "0") or "0")
            total_cash = safe_float(balance_info.get("frcr_dncl_amt_2", "0") or "0")
            purchase_total = safe_float(
                balance_info.get("frcr_buy_amt_smtl", "0") or "0"
            )
            # Fetch available foreign currency cash via inquire-psamount (TTTS3007R/VTTS3007R).
            # TTTS3012R output2 does not include a cash/deposit field — frcr_dncl_amt_2 does not exist.
            # Use the first stock with a valid price as the reference for the buying power query.
            # Source: 한국투자증권 오픈API 전체문서 (20260221) — '해외주식 매수가능금액조회' 시트
            total_cash = 0.0
            ref_stock = next(
                (s for s in stocks_data if s.get("current_price", 0) > 0), None
            )
            if ref_stock:
                try:
                    ps_data = await overseas_broker.get_overseas_buying_power(
                        market.exchange_code,
                        ref_stock["stock_code"],
                        ref_stock["current_price"],
                    )
                    total_cash = safe_float(
                        ps_data.get("output", {}).get("ovrs_ord_psbl_amt", "0") or "0"
                    )
                except ConnectionError as exc:
                    logger.warning(
                        "Could not fetch overseas buying power for %s: %s",
                        market.exchange_code,
                        exc,
                    )
            # Paper mode fallback: VTS overseas balance API often fails for many accounts.
            # Only activate in paper mode — live mode must use real balance from KIS.
            if (
@@ -2003,7 +2154,7 @@ def _start_dashboard_server(settings: Settings) -> threading.Thread | None:
            import uvicorn
            from src.dashboard import create_dashboard_app
-            app = create_dashboard_app(settings.DB_PATH)
+            app = create_dashboard_app(settings.DB_PATH, mode=settings.MODE)
            uvicorn.run(
                app,
                host=settings.DASHBOARD_HOST,
@@ -2686,9 +2837,9 @@ async def run(settings: Settings) -> None:
                                    active_stocks=active_stocks,
                                )
                                if not fallback_stocks:
-                                    logger.warning(
+                                    logger.debug(
                                        "No dynamic overseas symbol universe for %s;"
-                                        " scanner cannot run",
+                                        " scanner will use overseas ranking API",
                                        market.code,
                                    )
--- a/src/strategies/v20260220_210124_evolved.py
+++ b/src/strategies/v20260220_210124_evolved.py
@@ -1,114 +0,0 @@
 """Auto-generated strategy: v20260220_210124
 Generated at: 2026-02-20T21:01:24.706847+00:00
 Rationale: Auto-evolved from 6 failures. Primary failure markets: ['US_AMEX', 'US_NYSE', 'US_NASDAQ']. Average loss: -194.69
 """
 from __future__ import annotations
 from typing import Any
 from src.strategies.base import BaseStrategy
 class Strategy_v20260220_210124(BaseStrategy):
    """Strategy: v20260220_210124"""
    def evaluate(self, market_data: dict[str, Any]) -> dict[str, Any]:
        import datetime
        # --- Strategy Constants ---
        # Minimum price for a stock to be considered for trading (avoids penny stocks)
        MIN_PRICE = 5.0
        # Momentum signal thresholds (stricter than previous failures)
        MOMENTUM_PRICE_CHANGE_THRESHOLD = 7.0  # % price change
        MOMENTUM_VOLUME_RATIO_THRESHOLD = 4.0  # X times average volume
        # Oversold signal thresholds (more conservative)
        OVERSOLD_RSI_THRESHOLD = 25.0  # RSI value (lower means more oversold)
        # Confidence levels
        CONFIDENCE_HOLD = 30
        CONFIDENCE_BUY_OVERSOLD = 65
        CONFIDENCE_BUY_MOMENTUM = 85
        CONFIDENCE_BUY_STRONG_MOMENTUM = 90  # For higher-priced stocks with strong momentum
        # Market hours in UTC (9:30 AM ET to 4:00 PM ET)
        MARKET_OPEN_UTC = datetime.time(14, 30)
        MARKET_CLOSE_UTC = datetime.time(21, 0)
        # Volatile periods within market hours (UTC) to avoid
        # First hour after open (14:30 UTC - 15:30 UTC)
        VOLATILE_OPEN_END_UTC = datetime.time(15, 30)
        # Last 30 minutes before close (20:30 UTC - 21:00 UTC)
        VOLATILE_CLOSE_START_UTC = datetime.time(20, 30)
        current_price = market_data.get('current_price')
        price_change_pct = market_data.get('price_change_pct')
        volume_ratio = market_data.get('volume_ratio')  # Assumed pre-computed indicator
        rsi = market_data.get('rsi')                    # Assumed pre-computed indicator
        timestamp_str = market_data.get('timestamp')
        action = "HOLD"
        confidence = CONFIDENCE_HOLD
        rationale = "Initial HOLD: No clear signal or conditions not met."
        # --- 1. Basic Data Validation ---
        if current_price is None or price_change_pct is None:
            return {"action": "HOLD", "confidence": CONFIDENCE_HOLD,
                    "rationale": "Insufficient core data (price or price change) to evaluate."}
        # --- 2. Price Filter: Avoid low-priced/penny stocks ---
        if current_price < MIN_PRICE:
            return {"action": "HOLD", "confidence": CONFIDENCE_HOLD,
                    "rationale": f"Avoiding low-priced stock (${current_price:.2f} < ${MIN_PRICE:.2f})."}
        # --- 3. Time Filter: Only trade during core market hours ---
        if timestamp_str:
            try:
                dt_object = datetime.datetime.fromisoformat(timestamp_str)
                current_time_utc = dt_object.time()
                if not (MARKET_OPEN_UTC <= current_time_utc < MARKET_CLOSE_UTC):
                    return {"action": "HOLD", "confidence": CONFIDENCE_HOLD,
                            "rationale": f"Avoiding trade outside core market hours ({current_time_utc} UTC)."}
                if (MARKET_OPEN_UTC <= current_time_utc < VOLATILE_OPEN_END_UTC) or \
                   (VOLATILE_CLOSE_START_UTC <= current_time_utc < MARKET_CLOSE_UTC):
                    return {"action": "HOLD", "confidence": CONFIDENCE_HOLD,
                            "rationale": f"Avoiding trade during volatile market open/close periods ({current_time_utc} UTC)."}
            except ValueError:
                rationale += " (Warning: Malformed timestamp, time filters skipped)"
        # --- Initialize signal states ---
        has_momentum_buy_signal = False
        has_oversold_buy_signal = False
        # --- 4. Evaluate Enhanced Buy Signals ---
        # Momentum Buy Signal
        if volume_ratio is not None and \
           price_change_pct > MOMENTUM_PRICE_CHANGE_THRESHOLD and \
           volume_ratio > MOMENTUM_VOLUME_RATIO_THRESHOLD:
            has_momentum_buy_signal = True
            rationale = f"Momentum BUY: Price change {price_change_pct:.2f}%, Volume {volume_ratio:.2f}x."
            confidence = CONFIDENCE_BUY_MOMENTUM
            if current_price >= 10.0:
                confidence = CONFIDENCE_BUY_STRONG_MOMENTUM
        # Oversold Buy Signal
        if rsi is not None and rsi < OVERSOLD_RSI_THRESHOLD:
            has_oversold_buy_signal = True
            if not has_momentum_buy_signal:
                rationale = f"Oversold BUY: RSI {rsi:.2f}."
                confidence = CONFIDENCE_BUY_OVERSOLD
                if current_price >= 10.0:
                    confidence = min(CONFIDENCE_BUY_OVERSOLD + 5, 80)
        # --- 5. Decision Logic ---
        if has_momentum_buy_signal:
            action = "BUY"
        elif has_oversold_buy_signal:
            action = "BUY"
        return {"action": action, "confidence": confidence, "rationale": rationale}
--- a/src/strategies/v20260220_210159_evolved.py
+++ b/src/strategies/v20260220_210159_evolved.py
@@ -1,97 +0,0 @@
 """Auto-generated strategy: v20260220_210159
 Generated at: 2026-02-20T21:01:59.391523+00:00
 Rationale: Auto-evolved from 6 failures. Primary failure markets: ['US_AMEX', 'US_NYSE', 'US_NASDAQ']. Average loss: -194.69
 """
 from __future__ import annotations
 from typing import Any
 from src.strategies.base import BaseStrategy
 class Strategy_v20260220_210159(BaseStrategy):
    """Strategy: v20260220_210159"""
    def evaluate(self, market_data: dict[str, Any]) -> dict[str, Any]:
        import datetime
        current_price = market_data.get('current_price')
        price_change_pct = market_data.get('price_change_pct')
        volume_ratio = market_data.get('volume_ratio')
        rsi = market_data.get('rsi')
        timestamp_str = market_data.get('timestamp')
        market_name = market_data.get('market')
        # Default action
        action = "HOLD"
        confidence = 0
        rationale = "No strong signal or conditions not met."
        # --- FAILURE PATTERN AVOIDANCE ---
        # 1. Avoid low-priced/penny stocks
        MIN_PRICE_THRESHOLD = 5.0  # USD
        if current_price is not None and current_price < MIN_PRICE_THRESHOLD:
            rationale = (
                f"HOLD: Stock price (${current_price:.2f}) is below minimum threshold "
                f"(${MIN_PRICE_THRESHOLD:.2f}). Past failures consistently involved low-priced stocks."
            )
            return {"action": action, "confidence": confidence, "rationale": rationale}
        # 2. Avoid early market hour volatility
        if timestamp_str:
            try:
                dt_obj = datetime.datetime.fromisoformat(timestamp_str)
                utc_hour = dt_obj.hour
                utc_minute = dt_obj.minute
                if (utc_hour == 14 and utc_minute < 45) or (utc_hour == 13 and utc_minute >= 30):
                    rationale = (
                        f"HOLD: Trading during early market hours (UTC {utc_hour}:{utc_minute}), "
                        f"a period identified with past failures due to high volatility."
                    )
                    return {"action": action, "confidence": confidence, "rationale": rationale}
            except ValueError:
                pass
        # --- IMPROVED BUY STRATEGY ---
        # Momentum BUY signal
        if volume_ratio is not None and price_change_pct is not None:
            if price_change_pct > 7.0 and volume_ratio > 3.0:
                action = "BUY"
                confidence = 70
                rationale = "Improved BUY: Momentum signal with high volume and above price threshold."
                if market_name == 'US_AMEX':
                    confidence = max(55, confidence - 5)
                    rationale += " (Adjusted lower for AMEX market's higher risk profile)."
                elif market_name == 'US_NASDAQ' and price_change_pct > 20:
                    confidence = max(50, confidence - 10)
                    rationale += " (Adjusted lower for aggressive NASDAQ momentum volatility)."
                if price_change_pct > 15.0:
                    confidence = max(50, confidence - 5)
                    rationale += " (Caution: Very high daily price change, potential for reversal)."
                return {"action": action, "confidence": confidence, "rationale": rationale}
        # Oversold BUY signal
        if rsi is not None and price_change_pct is not None:
            if rsi < 30 and price_change_pct < -3.0:
                action = "BUY"
                confidence = 65
                rationale = "Improved BUY: Oversold signal with recent decline and above price threshold."
                if market_name == 'US_AMEX':
                    confidence = max(50, confidence - 5)
                    rationale += " (Adjusted lower for AMEX market's higher risk on oversold assets)."
                if price_change_pct < -10.0:
                    confidence = max(45, confidence - 10)
                    rationale += " (Caution: Very steep decline, potential falling knife)."
                return {"action": action, "confidence": confidence, "rationale": rationale}
        # If no specific BUY signal, default to HOLD
        return {"action": action, "confidence": confidence, "rationale": rationale}
--- a/src/strategies/v20260220_210244_evolved.py
+++ b/src/strategies/v20260220_210244_evolved.py
@@ -1,88 +0,0 @@
 """Auto-generated strategy: v20260220_210244
 Generated at: 2026-02-20T21:02:44.387355+00:00
 Rationale: Auto-evolved from 6 failures. Primary failure markets: ['US_AMEX', 'US_NYSE', 'US_NASDAQ']. Average loss: -194.69
 """
 from __future__ import annotations
 from typing import Any
 from src.strategies.base import BaseStrategy
 class Strategy_v20260220_210244(BaseStrategy):
    """Strategy: v20260220_210244"""
    def evaluate(self, market_data: dict[str, Any]) -> dict[str, Any]:
        from datetime import datetime
        # Extract required data points safely
        current_price = market_data.get("current_price")
        price_change_pct = market_data.get("price_change_pct")
        volume_ratio = market_data.get("volume_ratio")
        rsi = market_data.get("rsi")
        timestamp_str = market_data.get("timestamp")
        market_name = market_data.get("market")
        stock_code = market_data.get("stock_code", "UNKNOWN")
        # Default action is HOLD with conservative confidence and rationale
        action = "HOLD"
        confidence = 50
        rationale = f"No strong BUY signal for {stock_code} or awaiting more favorable conditions after avoiding known failure patterns."
        # --- 1. Failure Pattern Avoidance Filters ---
        # A. Avoid low-priced (penny) stocks
        if current_price is not None and current_price < 5.0:
            return {
                "action": "HOLD",
                "confidence": 50,
                "rationale": f"AVOID {stock_code}: Stock price (${current_price:.2f}) is below minimum threshold ($5.00) for BUY action. Identified past failures on highly volatile, low-priced stocks."
            }
        # B. Avoid initiating BUY trades during identified high-volatility hours
        if timestamp_str:
            try:
                trade_hour = datetime.fromisoformat(timestamp_str).hour
                if trade_hour in [14, 20]:
                    return {
                        "action": "HOLD",
                        "confidence": 50,
                        "rationale": f"AVOID {stock_code}: Trading during historically volatile hour ({trade_hour} UTC) where previous BUYs resulted in losses. Prefer to observe market stability."
                    }
            except ValueError:
                pass
        # C. Be cautious with extreme momentum spikes
        if volume_ratio is not None and price_change_pct is not None:
            if volume_ratio >= 9.0 and price_change_pct >= 15.0:
                return {
                    "action": "HOLD",
                    "confidence": 50,
                    "rationale": f"AVOID {stock_code}: Extreme short-term momentum detected (price change: +{price_change_pct:.2f}%, volume ratio: {volume_ratio:.1f}x). Historical failures indicate buying into such rapid spikes often leads to reversals."
                }
        # D. Be cautious with "oversold" signals without further confirmation
        if rsi is not None and rsi < 30:
            return {
                "action": "HOLD",
                "confidence": 50,
                "rationale": f"AVOID {stock_code}: Oversold signal (RSI={rsi:.1f}) detected. While often a BUY signal, historical failures on similar 'oversold' trades suggest waiting for stronger confirmation."
            }
        # --- 2. Improved BUY Signal Generation ---
        if volume_ratio is not None and 2.0 <= volume_ratio < 9.0 and \
           price_change_pct is not None and 2.0 <= price_change_pct < 15.0:
            action = "BUY"
            confidence = 70
            rationale = f"BUY {stock_code}: Moderate momentum detected (price change: +{price_change_pct:.2f}%, volume ratio: {volume_ratio:.1f}x). Passed filters for price and extreme momentum, avoiding past failure patterns."
            if market_name in ["US_AMEX", "US_NASDAQ"]:
                confidence = max(60, confidence - 5)
                rationale += f" Adjusted confidence for {market_name} market characteristics."
            elif market_name == "US_NYSE":
                confidence = max(65, confidence)
            confidence = max(50, min(85, confidence))
        return {"action": action, "confidence": confidence, "rationale": rationale}
--- a/tests/test_brain.py
+++ b/tests/test_brain.py
@@ -93,9 +93,21 @@ class TestMalformedJsonHandling:
    def test_json_with_missing_fields_returns_hold(self, settings):
        client = GeminiClient(settings)
-        decision = client.parse_response('{"action": "BUY"}')
+        raw = '{"action": "BUY"}'
        decision = client.parse_response(raw)
        assert decision.action == "HOLD"
        assert decision.confidence == 0
        # rationale preserves raw so prompt_override callers (e.g. pre_market_planner)
        # can extract non-TradeDecision JSON from decision.rationale (#245)
        assert decision.rationale == raw
    def test_non_trade_decision_json_preserves_raw_in_rationale(self, settings):
        """Playbook JSON (no action/confidence/rationale) must be preserved for planner."""
        client = GeminiClient(settings)
        playbook_json = '{"market_outlook": "neutral", "stocks": []}'
        decision = client.parse_response(playbook_json)
        assert decision.action == "HOLD"
        assert decision.rationale == playbook_json
    def test_json_with_invalid_action_returns_hold(self, settings):
        client = GeminiClient(settings)
@@ -290,9 +302,10 @@ class TestPromptOverride:
        client = GeminiClient(settings)
        custom_prompt = "You are a playbook generator. Return JSON with scenarios."
        playbook_json = '{"market_outlook": "neutral", "stocks": []}'
        mock_response = MagicMock()
-        mock_response.text = '{"action": "HOLD", "confidence": 50, "rationale": "test"}'
+        mock_response.text = playbook_json
        with patch.object(
            client._client.aio.models,
@@ -305,7 +318,7 @@ class TestPromptOverride:
                "current_price": 0,
                "prompt_override": custom_prompt,
            }
-            await client.decide(market_data)
+            decision = await client.decide(market_data)
            # Verify the custom prompt was sent, not a built prompt
            mock_generate.assert_called_once()
@@ -313,17 +326,50 @@ class TestPromptOverride:
                "contents", mock_generate.call_args[0][1] if len(mock_generate.call_args[0]) > 1 else None
            )
            assert actual_prompt == custom_prompt
            # Raw response preserved in rationale without parse_response (#247)
            assert decision.rationale == playbook_json
    @pytest.mark.asyncio
-    async def test_prompt_override_skips_optimization(self, settings):
+    async def test_prompt_override_skips_parse_response(self, settings):
-        """prompt_override should bypass prompt optimization."""
+        """prompt_override bypasses parse_response — no Missing fields warning, raw preserved."""
        client = GeminiClient(settings)
        client._enable_optimization = True
        custom_prompt = "Custom playbook prompt"
        playbook_json = '{"market_outlook": "bullish", "stocks": [{"stock_code": "AAPL"}]}'
        mock_response = MagicMock()
-        mock_response.text = '{"action": "HOLD", "confidence": 50, "rationale": "ok"}'
+        mock_response.text = playbook_json
        with patch.object(
            client._client.aio.models,
            "generate_content",
            new_callable=AsyncMock,
            return_value=mock_response,
        ):
            with patch.object(client, "parse_response") as mock_parse:
                market_data = {
                    "stock_code": "PLANNER",
                    "current_price": 0,
                    "prompt_override": custom_prompt,
                }
                decision = await client.decide(market_data)
                # parse_response must NOT be called for prompt_override
                mock_parse.assert_not_called()
                # Raw playbook JSON preserved in rationale
                assert decision.rationale == playbook_json
    @pytest.mark.asyncio
    async def test_prompt_override_takes_priority_over_optimization(self, settings):
        """prompt_override must win over enable_optimization=True."""
        client = GeminiClient(settings)
        client._enable_optimization = True
        custom_prompt = "Explicit playbook prompt"
        mock_response = MagicMock()
        mock_response.text = '{"market_outlook": "neutral", "stocks": []}'
        with patch.object(
            client._client.aio.models,
@@ -341,6 +387,7 @@ class TestPromptOverride:
            actual_prompt = mock_generate.call_args[1].get(
                "contents", mock_generate.call_args[0][1] if len(mock_generate.call_args[0]) > 1 else None
            )
            # The custom prompt must be used, not the compressed prompt
            assert actual_prompt == custom_prompt
    @pytest.mark.asyncio
--- a/tests/test_broker.py
+++ b/tests/test_broker.py
@@ -354,6 +354,8 @@ class TestFetchMarketRankings:
        assert "ranking/fluctuation" in url
        assert headers.get("tr_id") == "FHPST01700000"
        assert params.get("fid_cond_scr_div_code") == "20170"
        # 실전 API는 4자리("0000") 거부 — 1자리("0")여야 한다 (#240)
        assert params.get("fid_rank_sort_cls_code") == "0"
    @pytest.mark.asyncio
    async def test_volume_returns_parsed_rows(self, broker: KISBroker) -> None:
@@ -376,6 +378,27 @@ class TestFetchMarketRankings:
        assert result[0]["price"] == 75000.0
        assert result[0]["change_rate"] == 2.5
    @pytest.mark.asyncio
    async def test_fluctuation_parses_stck_shrn_iscd(self, broker: KISBroker) -> None:
        """실전 API는 mksc_shrn_iscd 대신 stck_shrn_iscd를 반환한다 (#240)."""
        items = [
            {
                "stck_shrn_iscd": "015260",
                "hts_kor_isnm": "에이엔피",
                "stck_prpr": "794",
                "acml_vol": "4896196",
                "prdy_ctrt": "29.74",
                "vol_inrt": "0",
            }
        ]
        mock_resp = _make_ranking_mock(items)
        with patch("aiohttp.ClientSession.get", return_value=mock_resp):
            result = await broker.fetch_market_rankings(ranking_type="fluctuation")
        assert len(result) == 1
        assert result[0]["stock_code"] == "015260"
        assert result[0]["change_rate"] == 29.74
 # ---------------------------------------------------------------------------
 # KRX tick unit / round-down helpers (issue #157)
--- a/tests/test_dashboard.py
+++ b/tests/test_dashboard.py
@@ -413,3 +413,39 @@ def test_status_circuit_breaker_unknown_when_no_data(tmp_path: Path) -> None:
    cb = body["circuit_breaker"]
    assert cb["status"] == "unknown"
    assert cb["current_pnl_pct"] is None
 def test_status_mode_paper(tmp_path: Path) -> None:
    """mode=paper로 생성하면 status 응답에 mode=paper가 포함돼야 한다."""
    db_path = tmp_path / "dashboard_test.db"
    conn = init_db(str(db_path))
    _seed_db(conn)
    conn.close()
    app = create_dashboard_app(str(db_path), mode="paper")
    get_status = _endpoint(app, "/api/status")
    body = get_status()
    assert body["mode"] == "paper"
 def test_status_mode_live(tmp_path: Path) -> None:
    """mode=live로 생성하면 status 응답에 mode=live가 포함돼야 한다."""
    db_path = tmp_path / "dashboard_test.db"
    conn = init_db(str(db_path))
    _seed_db(conn)
    conn.close()
    app = create_dashboard_app(str(db_path), mode="live")
    get_status = _endpoint(app, "/api/status")
    body = get_status()
    assert body["mode"] == "live"
 def test_status_mode_default_paper(tmp_path: Path) -> None:
    """mode 파라미터 미전달 시 기본값은 paper여야 한다."""
    db_path = tmp_path / "dashboard_test.db"
    conn = init_db(str(db_path))
    _seed_db(conn)
    conn.close()
    app = create_dashboard_app(str(db_path))
    get_status = _endpoint(app, "/api/status")
    body = get_status()
    assert body["mode"] == "paper"
--- a/tests/test_main.py
+++ b/tests/test_main.py
@@ -15,6 +15,7 @@ from src.logging.decision_logger import DecisionLogger
 from src.main import (
    _apply_dashboard_flag,
    _determine_order_quantity,
    _extract_avg_price_from_balance,
    _extract_held_codes_from_balance,
    _extract_held_qty_from_balance,
    _handle_market_close,
@@ -76,6 +77,81 @@ def _make_sell_match(stock_code: str = "005930") -> ScenarioMatch:
    )
 class TestExtractAvgPriceFromBalance:
    """Tests for _extract_avg_price_from_balance() (issue #249)."""
    def test_domestic_returns_pchs_avg_pric(self) -> None:
        """Domestic balance with pchs_avg_pric returns the correct float."""
        balance = {"output1": [{"pdno": "005930", "pchs_avg_pric": "68000.00"}]}
        result = _extract_avg_price_from_balance(balance, "005930", is_domestic=True)
        assert result == 68000.0
    def test_overseas_returns_pchs_avg_pric(self) -> None:
        """Overseas balance with pchs_avg_pric returns the correct float."""
        balance = {"output1": [{"ovrs_pdno": "AAPL", "pchs_avg_pric": "170.50"}]}
        result = _extract_avg_price_from_balance(balance, "AAPL", is_domestic=False)
        assert result == 170.5
    def test_returns_zero_when_field_absent(self) -> None:
        """Returns 0.0 when pchs_avg_pric key is missing entirely."""
        balance = {"output1": [{"pdno": "005930", "ord_psbl_qty": "5"}]}
        result = _extract_avg_price_from_balance(balance, "005930", is_domestic=True)
        assert result == 0.0
    def test_returns_zero_when_field_empty_string(self) -> None:
        """Returns 0.0 when pchs_avg_pric is an empty string."""
        balance = {"output1": [{"pdno": "005930", "pchs_avg_pric": ""}]}
        result = _extract_avg_price_from_balance(balance, "005930", is_domestic=True)
        assert result == 0.0
    def test_returns_zero_when_stock_not_found(self) -> None:
        """Returns 0.0 when the requested stock_code is not in output1."""
        balance = {"output1": [{"pdno": "000660", "pchs_avg_pric": "100000.0"}]}
        result = _extract_avg_price_from_balance(balance, "005930", is_domestic=True)
        assert result == 0.0
    def test_returns_zero_when_output1_empty(self) -> None:
        """Returns 0.0 when output1 is an empty list."""
        balance = {"output1": []}
        result = _extract_avg_price_from_balance(balance, "005930", is_domestic=True)
        assert result == 0.0
    def test_returns_zero_when_output1_key_absent(self) -> None:
        """Returns 0.0 when output1 key is missing from balance_data."""
        balance: dict = {}
        result = _extract_avg_price_from_balance(balance, "005930", is_domestic=True)
        assert result == 0.0
    def test_handles_output1_as_dict(self) -> None:
        """Handles the edge case where output1 is a dict instead of a list."""
        balance = {"output1": {"pdno": "005930", "pchs_avg_pric": "55000.0"}}
        result = _extract_avg_price_from_balance(balance, "005930", is_domestic=True)
        assert result == 55000.0
    def test_case_insensitive_code_matching(self) -> None:
        """Stock code comparison is case-insensitive."""
        balance = {"output1": [{"ovrs_pdno": "aapl", "pchs_avg_pric": "170.0"}]}
        result = _extract_avg_price_from_balance(balance, "AAPL", is_domestic=False)
        assert result == 170.0
    def test_returns_zero_for_non_numeric_string(self) -> None:
        """Returns 0.0 when pchs_avg_pric contains a non-numeric value."""
        balance = {"output1": [{"pdno": "005930", "pchs_avg_pric": "N/A"}]}
        result = _extract_avg_price_from_balance(balance, "005930", is_domestic=True)
        assert result == 0.0
    def test_returns_correct_stock_among_multiple(self) -> None:
        """Returns only the avg price of the requested stock when output1 has multiple holdings."""
        balance = {
            "output1": [
                {"pdno": "000660", "pchs_avg_pric": "150000.0"},
                {"pdno": "005930", "pchs_avg_pric": "68000.0"},
            ]
        }
        result = _extract_avg_price_from_balance(balance, "005930", is_domestic=True)
        assert result == 68000.0
 class TestExtractHeldQtyFromBalance:
    """Tests for _extract_held_qty_from_balance()."""
@@ -101,10 +177,24 @@ class TestExtractHeldQtyFromBalance:
        balance = {"output1": [], "output2": [{}]}
        assert _extract_held_qty_from_balance(balance, "005930", is_domestic=True) == 0
-    def test_overseas_returns_ovrs_cblc_qty(self) -> None:
+    def test_overseas_returns_ord_psbl_qty_first(self) -> None:
        """ord_psbl_qty (주문가능수량) takes priority over ovrs_cblc_qty."""
        balance = {
            "output1": [{"ovrs_pdno": "AAPL", "ord_psbl_qty": "8", "ovrs_cblc_qty": "10"}]
        }
        assert _extract_held_qty_from_balance(balance, "AAPL", is_domestic=False) == 8
    def test_overseas_fallback_to_ovrs_cblc_qty_when_ord_psbl_qty_absent(self) -> None:
        balance = {"output1": [{"ovrs_pdno": "AAPL", "ovrs_cblc_qty": "10"}]}
        assert _extract_held_qty_from_balance(balance, "AAPL", is_domestic=False) == 10
    def test_overseas_returns_zero_when_ord_psbl_qty_zero(self) -> None:
        """Expired/delisted securities: ovrs_cblc_qty large but ord_psbl_qty=0."""
        balance = {
            "output1": [{"ovrs_pdno": "MLECW", "ord_psbl_qty": "0", "ovrs_cblc_qty": "289456"}]
        }
        assert _extract_held_qty_from_balance(balance, "MLECW", is_domestic=False) == 0
    def test_overseas_fallback_to_hldg_qty(self) -> None:
        balance = {"output1": [{"ovrs_pdno": "AAPL", "hldg_qty": "4"}]}
        assert _extract_held_qty_from_balance(balance, "AAPL", is_domestic=False) == 4
@@ -147,6 +237,26 @@ class TestExtractHeldCodesFromBalance:
        result = _extract_held_codes_from_balance(balance, is_domestic=False)
        assert result == ["AAPL"]
    def test_overseas_uses_ord_psbl_qty_to_filter(self) -> None:
        """ord_psbl_qty=0 should exclude stock even if ovrs_cblc_qty is large."""
        balance = {
            "output1": [
                {"ovrs_pdno": "MLECW", "ord_psbl_qty": "0", "ovrs_cblc_qty": "289456"},
                {"ovrs_pdno": "AAPL", "ord_psbl_qty": "5", "ovrs_cblc_qty": "5"},
            ]
        }
        result = _extract_held_codes_from_balance(balance, is_domestic=False)
        assert "MLECW" not in result
        assert "AAPL" in result
    def test_overseas_includes_stock_when_ord_psbl_qty_absent_and_ovrs_cblc_qty_positive(
        self,
    ) -> None:
        """Fallback to ovrs_cblc_qty when ord_psbl_qty field is missing."""
        balance = {"output1": [{"ovrs_pdno": "TSLA", "ovrs_cblc_qty": "3"}]}
        result = _extract_held_codes_from_balance(balance, is_domestic=False)
        assert "TSLA" in result
 class TestDetermineOrderQuantity:
    """Test _determine_order_quantity() — SELL uses broker_held_qty."""
@@ -793,12 +903,14 @@ class TestOverseasBalanceParsing:
                "output2": [
                    {
                        "frcr_evlu_tota": "10000.00",
                        "frcr_dncl_amt_2": "5000.00",
                        "frcr_buy_amt_smtl": "4500.00",
                    }
                ]
            }
        )
        broker.get_overseas_buying_power = AsyncMock(
            return_value={"output": {"ovrs_ord_psbl_amt": "5000.00"}}
        )
        return broker
    @pytest.fixture
@@ -812,11 +924,13 @@ class TestOverseasBalanceParsing:
            return_value={
                "output2": {
                    "frcr_evlu_tota": "10000.00",
                    "frcr_dncl_amt_2": "5000.00",
                    "frcr_buy_amt_smtl": "4500.00",
                }
            }
        )
        broker.get_overseas_buying_power = AsyncMock(
            return_value={"output": {"ovrs_ord_psbl_amt": "5000.00"}}
        )
        return broker
    @pytest.fixture
@@ -827,6 +941,9 @@ class TestOverseasBalanceParsing:
            return_value={"output": {"last": "150.50"}}
        )
        broker.get_overseas_balance = AsyncMock(return_value={"output2": []})
        broker.get_overseas_buying_power = AsyncMock(
            return_value={"output": {"ovrs_ord_psbl_amt": "0.00"}}
        )
        return broker
    @pytest.fixture
@@ -841,12 +958,15 @@ class TestOverseasBalanceParsing:
                "output2": [
                    {
                        "frcr_evlu_tota": "10000.00",
                        "frcr_dncl_amt_2": "5000.00",
                        "frcr_buy_amt_smtl": "4500.00",
                    }
                ]
            }
        )
        # get_overseas_buying_power not called when price=0, but mock for safety
        broker.get_overseas_buying_power = AsyncMock(
            return_value={"output": {"ovrs_ord_psbl_amt": "5000.00"}}
        )
        return broker
    @pytest.fixture
@@ -1076,12 +1196,14 @@ class TestOverseasBalanceParsing:
                "output2": [
                    {
                        "frcr_evlu_tota": "100000.00",
                        "frcr_dncl_amt_2": "50000.00",
                        "frcr_buy_amt_smtl": "50000.00",
                    }
                ]
            }
        )
        broker.get_overseas_buying_power = AsyncMock(
            return_value={"output": {"ovrs_ord_psbl_amt": "50000.00"}}
        )
        broker.send_overseas_order = AsyncMock(return_value={"msg1": "주문접수"})
        return broker
@@ -1136,7 +1258,8 @@ class TestOverseasBalanceParsing:
        mock_overseas_broker_with_buy_scenario.send_overseas_order.assert_called_once()
        call_kwargs = mock_overseas_broker_with_buy_scenario.send_overseas_order.call_args
        sent_price = call_kwargs[1].get("price") or call_kwargs[0][4]
-        expected_price = round(182.5 * 1.002, 4)  # 0.2% premium for BUY limit orders
+        # KIS requires max 2 decimal places for prices >= $1 (#252)
        expected_price = round(182.5 * 1.002, 2)  # 0.2% premium for BUY limit orders
        assert sent_price == expected_price, (
            f"Expected limit price {expected_price} (182.5 * 1.002) but got {sent_price}. "
            "BUY uses +0.2% to improve fill rate while minimising overpayment (#211)."
@@ -1180,12 +1303,14 @@ class TestOverseasBalanceParsing:
                "output2": [
                    {
                        "frcr_evlu_tota": "100000.00",
                        "frcr_dncl_amt_2": "50000.00",
                        "frcr_buy_amt_smtl": "50000.00",
                    }
                ],
            }
        )
        overseas_broker.get_overseas_buying_power = AsyncMock(
            return_value={"output": {"ovrs_ord_psbl_amt": "50000.00"}}
        )
        overseas_broker.send_overseas_order = AsyncMock(
            return_value={"rt_cd": "0", "msg1": "OK"}
        )
@@ -1215,12 +1340,139 @@ class TestOverseasBalanceParsing:
        overseas_broker.send_overseas_order.assert_called_once()
        call_kwargs = overseas_broker.send_overseas_order.call_args
        sent_price = call_kwargs[1].get("price") or call_kwargs[0][4]
-        expected_price = round(sell_price * 0.998, 4)  # -0.2% for SELL limit orders
+        # KIS requires max 2 decimal places for prices >= $1 (#252)
        expected_price = round(sell_price * 0.998, 2)  # -0.2% for SELL limit orders
        assert sent_price == expected_price, (
            f"Expected SELL limit price {expected_price} (182.5 * 0.998) but got {sent_price}. "
            "SELL uses -0.2% to ensure fill even when price dips slightly (#211)."
        )
    @pytest.mark.asyncio
    async def test_overseas_buy_price_rounded_to_2_decimals_for_dollar_plus_stock(
        self,
        mock_domestic_broker: MagicMock,
        mock_playbook: DayPlaybook,
        mock_risk: MagicMock,
        mock_db: MagicMock,
        mock_decision_logger: MagicMock,
        mock_context_store: MagicMock,
        mock_criticality_assessor: MagicMock,
        mock_telegram: MagicMock,
        mock_overseas_market: MagicMock,
    ) -> None:
        """BUY price for $1+ stocks is rounded to 2 decimal places (issue #252).
        KIS rejects prices with more than 2 decimal places for stocks priced >= $1.
        current_price=50.1234 * 1.002 = 50.22... should be sent as 50.22, not 50.2236.
        """
        overseas_broker = MagicMock()
        overseas_broker.get_overseas_balance = AsyncMock(
            return_value={
                "output1": [],
                "output2": [{"frcr_evlu_tota": "0", "frcr_buy_amt_smtl": "0"}],
            }
        )
        overseas_broker.get_overseas_buying_power = AsyncMock(
            return_value={"output": {"ovrs_ord_psbl_amt": "10000"}}
        )
        overseas_broker.get_overseas_price = AsyncMock(
            return_value={"output": {"last": "50.1234", "rate": "0"}}
        )
        overseas_broker.send_overseas_order = AsyncMock(
            return_value={"rt_cd": None, "msg1": "주문접수"}
        )
        db_conn = init_db(":memory:")
        decision_logger = DecisionLogger(db_conn)
        engine = MagicMock(spec=ScenarioEngine)
        engine.evaluate = MagicMock(return_value=_make_buy_match())
        await trading_cycle(
            broker=mock_domestic_broker,
            overseas_broker=overseas_broker,
            scenario_engine=engine,
            playbook=mock_playbook,
            risk=mock_risk,
            db_conn=db_conn,
            decision_logger=decision_logger,
            context_store=mock_context_store,
            criticality_assessor=mock_criticality_assessor,
            telegram=mock_telegram,
            market=mock_overseas_market,
            stock_code="TQQQ",
            scan_candidates={},
        )
        overseas_broker.send_overseas_order.assert_called_once()
        sent_price = overseas_broker.send_overseas_order.call_args[1].get("price") or \
            overseas_broker.send_overseas_order.call_args[0][4]
        # 50.1234 * 1.002 = 50.2235... rounded to 2 decimals = 50.22
        assert sent_price == round(50.1234 * 1.002, 2), (
            f"Expected 2-decimal price {round(50.1234 * 1.002, 2)} but got {sent_price} (#252)"
        )
    @pytest.mark.asyncio
    async def test_overseas_penny_stock_price_keeps_4_decimals(
        self,
        mock_domestic_broker: MagicMock,
        mock_playbook: DayPlaybook,
        mock_risk: MagicMock,
        mock_db: MagicMock,
        mock_decision_logger: MagicMock,
        mock_context_store: MagicMock,
        mock_criticality_assessor: MagicMock,
        mock_telegram: MagicMock,
        mock_overseas_market: MagicMock,
    ) -> None:
        """BUY price for penny stocks (< $1) uses 4 decimal places (issue #252)."""
        overseas_broker = MagicMock()
        overseas_broker.get_overseas_balance = AsyncMock(
            return_value={
                "output1": [],
                "output2": [{"frcr_evlu_tota": "0", "frcr_buy_amt_smtl": "0"}],
            }
        )
        overseas_broker.get_overseas_buying_power = AsyncMock(
            return_value={"output": {"ovrs_ord_psbl_amt": "10000"}}
        )
        overseas_broker.get_overseas_price = AsyncMock(
            return_value={"output": {"last": "0.5678", "rate": "0"}}
        )
        overseas_broker.send_overseas_order = AsyncMock(
            return_value={"rt_cd": None, "msg1": "주문접수"}
        )
        db_conn = init_db(":memory:")
        decision_logger = DecisionLogger(db_conn)
        engine = MagicMock(spec=ScenarioEngine)
        engine.evaluate = MagicMock(return_value=_make_buy_match())
        await trading_cycle(
            broker=mock_domestic_broker,
            overseas_broker=overseas_broker,
            scenario_engine=engine,
            playbook=mock_playbook,
            risk=mock_risk,
            db_conn=db_conn,
            decision_logger=decision_logger,
            context_store=mock_context_store,
            criticality_assessor=mock_criticality_assessor,
            telegram=mock_telegram,
            market=mock_overseas_market,
            stock_code="PENNYX",
            scan_candidates={},
        )
        overseas_broker.send_overseas_order.assert_called_once()
        sent_price = overseas_broker.send_overseas_order.call_args[1].get("price") or \
            overseas_broker.send_overseas_order.call_args[0][4]
        # 0.5678 * 1.002 = 0.56893... rounded to 4 decimals = 0.5689
        assert sent_price == round(0.5678 * 1.002, 4), (
            f"Expected 4-decimal price {round(0.5678 * 1.002, 4)} but got {sent_price} (#252)"
        )
 class TestScenarioEngineIntegration:
    """Test scenario engine integration in trading_cycle."""
@@ -1416,10 +1668,10 @@ class TestScenarioEngineIntegration:
                scan_candidates={"US": {"005930": us_candidate}},  # Wrong market
            )
-        # Should NOT have rsi/volume_ratio because candidate is under US, not KR
+        # Should NOT use US candidate's rsi (=15.0); fallback implied_rsi used instead
        market_data = engine.evaluate.call_args[0][2]
-        assert "rsi" not in market_data
+        assert market_data["rsi"] != 15.0  # US candidate's rsi must be ignored
-        assert "volume_ratio" not in market_data
+        assert market_data["volume_ratio"] == 1.0  # Fallback default
    @pytest.mark.asyncio
    async def test_scenario_engine_called_without_scanner_data(
@@ -1450,13 +1702,70 @@ class TestScenarioEngineIntegration:
                scan_candidates={},  # No scanner data
            )
-        # Should still work, just without rsi/volume_ratio
+        # Holding stocks without scanner data use implied_rsi (from price_change_pct)
        # and volume_ratio=1.0 as fallback, so rsi/volume_ratio are always present.
        engine.evaluate.assert_called_once()
        market_data = engine.evaluate.call_args[0][2]
-        assert "rsi" not in market_data
+        assert "rsi" in market_data  # Implied RSI from price_change_pct=2.5 → 55.0
-        assert "volume_ratio" not in market_data
+        assert market_data["rsi"] == pytest.approx(55.0)
        assert market_data["volume_ratio"] == 1.0
        assert market_data["current_price"] == 50000.0
    @pytest.mark.asyncio
    async def test_holding_overseas_stock_derives_volume_ratio_from_price_api(
        self, mock_broker: MagicMock, mock_telegram: MagicMock,
    ) -> None:
        """Test overseas holding stocks derive volume_ratio from get_overseas_price high/low."""
        engine = MagicMock(spec=ScenarioEngine)
        engine.evaluate = MagicMock(return_value=_make_hold_match())
        os_market = MagicMock()
        os_market.name = "NASDAQ"
        os_market.code = "US_NASDAQ"
        os_market.exchange_code = "NAS"
        os_market.is_domestic = False
        os_market.timezone = UTC
        os_broker = MagicMock()
        # price_change_pct=5.0, high=106, low=94 → intraday_range=12% → volume_ratio=max(1,6)=6
        os_broker.get_overseas_price = AsyncMock(return_value={
            "output": {"last": "100.0", "rate": "5.0", "high": "106.0", "low": "94.0"}
        })
        os_broker.get_overseas_balance = AsyncMock(return_value={
            "output2": [{"frcr_evlu_tota": "10000", "frcr_buy_amt_smtl": "9000"}]
        })
        os_broker.get_overseas_buying_power = AsyncMock(return_value={
            "output": {"ovrs_ord_psbl_amt": "500"}
        })
        with patch("src.main.log_trade"):
            await trading_cycle(
                broker=mock_broker,
                overseas_broker=os_broker,
                scenario_engine=engine,
                playbook=_make_playbook(),
                risk=MagicMock(),
                db_conn=MagicMock(),
                decision_logger=MagicMock(),
                context_store=MagicMock(get_latest_timeframe=MagicMock(return_value=None)),
                criticality_assessor=MagicMock(
                    assess_market_conditions=MagicMock(return_value=MagicMock(value="NORMAL")),
                    get_timeout=MagicMock(return_value=5.0),
                ),
                telegram=mock_telegram,
                market=os_market,
                stock_code="NVDA",
                scan_candidates={},  # Not in scanner — holding stock
            )
        market_data = engine.evaluate.call_args[0][2]
        # rsi: 50.0 + 5.0 * 2.0 = 60.0
        assert market_data["rsi"] == pytest.approx(60.0)
        # intraday_range = (106-94)/100 * 100 = 12.0%
        # volatility_pct = max(abs(5.0), 12.0) = 12.0
        # volume_ratio = max(1.0, 12.0 / 2.0) = 6.0
        assert market_data["volume_ratio"] == pytest.approx(6.0)
    @pytest.mark.asyncio
    async def test_scenario_matched_notification_sent(
        self, mock_broker: MagicMock, mock_market: MagicMock, mock_telegram: MagicMock,
@@ -2014,6 +2323,92 @@ async def test_hold_not_overridden_when_between_stop_loss_and_take_profit() -> N
    broker.send_order.assert_not_called()
@pytest.mark.asyncio
 async def test_stop_loss_not_triggered_when_current_price_is_zero() -> None:
    """HOLD must stay HOLD when current_price=0 even if entry_price is set (issue #251).
    A price API failure that returns 0.0 must not cause a false -100% stop-loss.
    """
    db_conn = init_db(":memory:")
    decision_logger = DecisionLogger(db_conn)
    buy_decision_id = decision_logger.log_decision(
        stock_code="005930",
        market="KR",
        exchange_code="KRX",
        action="BUY",
        confidence=90,
        rationale="entry",
        context_snapshot={},
        input_data={},
    )
    log_trade(
        conn=db_conn,
        stock_code="005930",
        action="BUY",
        confidence=90,
        rationale="entry",
        quantity=1,
        price=100.0,  # valid entry price
        market="KR",
        exchange_code="KRX",
        decision_id=buy_decision_id,
    )
    broker = MagicMock()
    # Price API returns 0.0 — simulates API failure or pre-market unavailability
    broker.get_current_price = AsyncMock(return_value=(0.0, 0.0, 0.0))
    broker.get_balance = AsyncMock(
        return_value={
            "output2": [
                {
                    "tot_evlu_amt": "100000",
                    "dnca_tot_amt": "10000",
                    "pchs_amt_smtl_amt": "90000",
                }
            ]
        }
    )
    broker.send_order = AsyncMock(return_value={"msg1": "OK"})
    market = MagicMock()
    market.name = "Korea"
    market.code = "KR"
    market.exchange_code = "KRX"
    market.is_domestic = True
    telegram = MagicMock()
    telegram.notify_trade_execution = AsyncMock()
    telegram.notify_fat_finger = AsyncMock()
    telegram.notify_circuit_breaker = AsyncMock()
    telegram.notify_scenario_matched = AsyncMock()
    await trading_cycle(
        broker=broker,
        overseas_broker=MagicMock(),
        scenario_engine=MagicMock(evaluate=MagicMock(return_value=_make_hold_match())),
        playbook=_make_playbook("KR"),
        risk=MagicMock(),
        db_conn=db_conn,
        decision_logger=decision_logger,
        context_store=MagicMock(
            get_latest_timeframe=MagicMock(return_value=None),
            set_context=MagicMock(),
        ),
        criticality_assessor=MagicMock(
            assess_market_conditions=MagicMock(return_value=MagicMock(value="NORMAL")),
            get_timeout=MagicMock(return_value=5.0),
        ),
        telegram=telegram,
        market=market,
        stock_code="005930",
        scan_candidates={},
    )
    # No SELL order must be placed — current_price=0 must suppress stop-loss
    broker.send_order.assert_not_called()
@pytest.mark.asyncio
 async def test_sell_order_uses_broker_balance_qty_not_db() -> None:
    """SELL quantity must come from broker balance output1, not DB.
@@ -2463,9 +2858,11 @@ class TestBuyCooldown:
        )
        broker.get_overseas_balance = AsyncMock(return_value={
            "output1": [],
-            "output2": [{"frcr_dncl_amt_2": "50000", "frcr_evlu_tota": "50000",
+            "output2": [{"frcr_evlu_tota": "50000", "frcr_buy_amt_smtl": "0"}],
                         "frcr_buy_amt_smtl": "0"}],
        })
        broker.get_overseas_buying_power = AsyncMock(
            return_value={"output": {"ovrs_ord_psbl_amt": "50000"}}
        )
        broker.send_overseas_order = AsyncMock(
            return_value={"rt_cd": "1", "msg1": "모의투자 주문가능금액이 부족합니다."}
        )
@@ -2578,9 +2975,11 @@ class TestBuyCooldown:
        )
        overseas_broker.get_overseas_balance = AsyncMock(return_value={
            "output1": [],
-            "output2": [{"frcr_dncl_amt_2": "50000", "frcr_evlu_tota": "50000",
+            "output2": [{"frcr_evlu_tota": "50000", "frcr_buy_amt_smtl": "0"}],
                         "frcr_buy_amt_smtl": "0"}],
        })
        overseas_broker.get_overseas_buying_power = AsyncMock(
            return_value={"output": {"ovrs_ord_psbl_amt": "50000"}}
        )
        overseas_broker.send_overseas_order = AsyncMock(
            return_value={"rt_cd": "1", "msg1": "기타 오류 메시지"}
        )
@@ -2975,9 +3374,12 @@ async def test_buy_suppressed_when_open_position_exists() -> None:
    overseas_broker.get_overseas_balance = AsyncMock(
        return_value={
            "output1": [],
-            "output2": [{"frcr_dncl_amt_2": "10000", "frcr_evlu_tota": "10000", "frcr_buy_amt_smtl": "0"}],
+            "output2": [{"frcr_evlu_tota": "10000", "frcr_buy_amt_smtl": "0"}],
        }
    )
    overseas_broker.get_overseas_buying_power = AsyncMock(
        return_value={"output": {"ovrs_ord_psbl_amt": "10000"}}
    )
    overseas_broker.send_overseas_order = AsyncMock(return_value={"msg1": "OK"})
    engine = MagicMock(spec=ScenarioEngine)
@@ -3039,9 +3441,12 @@ async def test_buy_proceeds_when_no_open_position() -> None:
    overseas_broker.get_overseas_balance = AsyncMock(
        return_value={
            "output1": [],
-            "output2": [{"frcr_dncl_amt_2": "50000", "frcr_evlu_tota": "50000", "frcr_buy_amt_smtl": "0"}],
+            "output2": [{"frcr_evlu_tota": "50000", "frcr_buy_amt_smtl": "0"}],
        }
    )
    overseas_broker.get_overseas_buying_power = AsyncMock(
        return_value={"output": {"ovrs_ord_psbl_amt": "50000"}}
    )
    overseas_broker.send_overseas_order = AsyncMock(return_value={"msg1": "OK"})
    engine = MagicMock(spec=ScenarioEngine)
@@ -3142,13 +3547,15 @@ class TestOverseasBrokerIntegration:
                "output1": [{"ovrs_pdno": "AAPL", "ovrs_cblc_qty": "10"}],
                "output2": [
                    {
                        "frcr_dncl_amt_2": "50000.00",
                        "frcr_evlu_tota": "60000.00",
                        "frcr_buy_amt_smtl": "50000.00",
                    }
                ],
            }
        )
        overseas_broker.get_overseas_buying_power = AsyncMock(
            return_value={"output": {"ovrs_ord_psbl_amt": "50000.00"}}
        )
        overseas_broker.send_overseas_order = AsyncMock(return_value={"msg1": "주문접수"})
        engine = MagicMock(spec=ScenarioEngine)
@@ -3216,13 +3623,15 @@ class TestOverseasBrokerIntegration:
                "output1": [],
                "output2": [
                    {
                        "frcr_dncl_amt_2": "50000.00",
                        "frcr_evlu_tota": "50000.00",
                        "frcr_buy_amt_smtl": "0.00",
                    }
                ],
            }
        )
        overseas_broker.get_overseas_buying_power = AsyncMock(
            return_value={"output": {"ovrs_ord_psbl_amt": "50000.00"}}
        )
        overseas_broker.send_overseas_order = AsyncMock(return_value={"msg1": "주문접수"})
        engine = MagicMock(spec=ScenarioEngine)
@@ -3645,7 +4054,6 @@ class TestSyncPositionsFromBroker:
            "output2": [
                {
                    "frcr_evlu_tota": "50000",
                    "frcr_dncl_amt_2": "10000",
                    "frcr_buy_amt_smtl": "40000",
                }
            ],
@@ -3784,6 +4192,70 @@ class TestSyncPositionsFromBroker:
        # Two distinct exchange codes (NASD, NYSE) → 2 calls
        assert overseas_broker.get_overseas_balance.call_count == 2
    @pytest.mark.asyncio
    async def test_syncs_domestic_position_with_correct_avg_price(self) -> None:
        """Domestic position is stored with pchs_avg_pric as price (issue #249)."""
        settings = self._make_settings("KR")
        db_conn = init_db(":memory:")
        balance = {
            "output1": [{"pdno": "005930", "ord_psbl_qty": "5", "pchs_avg_pric": "68000.0"}],
            "output2": [{"tot_evlu_amt": "1000000", "dnca_tot_amt": "500000", "pchs_amt_smtl_amt": "500000"}],
        }
        broker = MagicMock()
        broker.get_balance = AsyncMock(return_value=balance)
        overseas_broker = MagicMock()
        await sync_positions_from_broker(broker, overseas_broker, db_conn, settings)
        from src.db import get_open_position
        pos = get_open_position(db_conn, "005930", "KR")
        assert pos is not None
        assert pos["price"] == 68000.0
    @pytest.mark.asyncio
    async def test_syncs_overseas_position_with_correct_avg_price(self) -> None:
        """Overseas position is stored with pchs_avg_pric as price (issue #249)."""
        settings = self._make_settings("US_NASDAQ")
        db_conn = init_db(":memory:")
        balance = {
            "output1": [{"ovrs_pdno": "AAPL", "ovrs_cblc_qty": "10", "pchs_avg_pric": "170.0"}],
            "output2": [{"frcr_evlu_tota": "50000", "frcr_buy_amt_smtl": "40000"}],
        }
        broker = MagicMock()
        overseas_broker = MagicMock()
        overseas_broker.get_overseas_balance = AsyncMock(return_value=balance)
        await sync_positions_from_broker(broker, overseas_broker, db_conn, settings)
        from src.db import get_open_position
        pos = get_open_position(db_conn, "AAPL", "US_NASDAQ")
        assert pos is not None
        assert pos["price"] == 170.0
    @pytest.mark.asyncio
    async def test_syncs_position_with_zero_price_when_pchs_avg_pric_absent(self) -> None:
        """Fallback to price=0.0 when pchs_avg_pric is absent (issue #249)."""
        settings = self._make_settings("KR")
        db_conn = init_db(":memory:")
        # No pchs_avg_pric in output1
        balance = {
            "output1": [{"pdno": "005930", "ord_psbl_qty": "5"}],
            "output2": [{"tot_evlu_amt": "1000000", "dnca_tot_amt": "500000", "pchs_amt_smtl_amt": "500000"}],
        }
        broker = MagicMock()
        broker.get_balance = AsyncMock(return_value=balance)
        overseas_broker = MagicMock()
        await sync_positions_from_broker(broker, overseas_broker, db_conn, settings)
        from src.db import get_open_position
        pos = get_open_position(db_conn, "005930", "KR")
        assert pos is not None
        assert pos["price"] == 0.0
 # ---------------------------------------------------------------------------
 # Domestic BUY double-prevention (issue #206) — trading_cycle integration
@@ -4378,3 +4850,192 @@ class TestDomesticLimitOrderPrice:
        expected_price = kr_round_down(current_price * 0.998)
        assert call_kwargs["price"] == expected_price
        assert call_kwargs["order_type"] == "SELL"
 # ---------------------------------------------------------------------------
 # Ghost position — overseas SELL "잔고내역이 없습니다" handling
 # ---------------------------------------------------------------------------
 class TestOverseasGhostPositionClose:
    """trading_cycle must close ghost DB position when broker returns 잔고없음."""
    def _make_overseas_market(self) -> MagicMock:
        market = MagicMock()
        market.name = "NASDAQ"
        market.code = "US_NASDAQ"
        market.exchange_code = "NASD"
        market.is_domestic = False
        return market
    def _make_overseas_broker(
        self,
        current_price: float,
        balance_data: dict,
        sell_result: dict,
    ) -> MagicMock:
        ob = MagicMock()
        ob.get_overseas_price = AsyncMock(
            return_value={"output": {"last": str(current_price), "rate": "0.0"}}
        )
        ob.get_overseas_balance = AsyncMock(return_value=balance_data)
        ob.get_overseas_buying_power = AsyncMock(
            return_value={"output": {"ovrs_ord_psbl_amt": "0.00"}}
        )
        ob.send_overseas_order = AsyncMock(return_value=sell_result)
        return ob
    @pytest.mark.asyncio
    async def test_ghost_position_closes_db_on_no_balance_error(self) -> None:
        """When SELL fails with '잔고내역이 없습니다', log_trade is called to close the ghost.
        This can happen when exchange code recorded at startup differs from the
        exchange code used in the SELL cycle (e.g. KNRX recorded as NASD but
        actually traded on AMEX), causing the broker to see no matching balance.
        The position has ord_psbl_qty > 0 (so a SELL is attempted), but KIS
        rejects it with '잔고내역이 없습니다'.
        """
        from src.strategy.models import ScenarioAction
        stock_code = "KNRX"
        current_price = 1.5
        # ord_psbl_qty=5 means the code passes the qty check and a SELL is sent
        balance_data = {
            "output1": [
                {"ovrs_pdno": stock_code, "ord_psbl_qty": "5", "ovrs_cblc_qty": "5"}
            ],
            "output2": [{"tot_evlu_amt": "10000"}],
        }
        sell_result = {"rt_cd": "1", "msg1": "모의투자 잔고내역이 없습니다"}
        domestic_broker = MagicMock()
        domestic_broker.get_balance = AsyncMock(return_value={"output1": [], "output2": [{}]})
        overseas_broker = self._make_overseas_broker(current_price, balance_data, sell_result)
        market = self._make_overseas_market()
        sell_match = ScenarioMatch(
            stock_code=stock_code,
            matched_scenario=None,
            action=ScenarioAction.SELL,
            confidence=85,
            rationale="test ghost KNRX",
        )
        engine = MagicMock(spec=ScenarioEngine)
        engine.evaluate = MagicMock(return_value=sell_match)
        risk = MagicMock()
        risk.validate_order = MagicMock()
        risk.check_circuit_breaker = MagicMock()
        telegram = MagicMock()
        telegram.notify_trade_execution = AsyncMock()
        telegram.notify_fat_finger = AsyncMock()
        telegram.notify_circuit_breaker = AsyncMock()
        telegram.notify_scenario_matched = AsyncMock()
        db_conn = MagicMock()
        settings = MagicMock(spec=Settings)
        settings.MODE = "paper"
        settings.POSITION_SIZING_ENABLED = False
        settings.PAPER_OVERSEAS_CASH = 0
        with patch("src.main.log_trade") as mock_log_trade, patch(
            "src.main.get_open_position", return_value=None
        ), patch("src.main.get_latest_buy_trade", return_value=None):
            await trading_cycle(
                broker=domestic_broker,
                overseas_broker=overseas_broker,
                scenario_engine=engine,
                playbook=_make_playbook(market="US_NASDAQ"),
                risk=risk,
                db_conn=db_conn,
                decision_logger=MagicMock(),
                context_store=MagicMock(get_latest_timeframe=MagicMock(return_value=None)),
                criticality_assessor=MagicMock(
                    assess_market_conditions=MagicMock(return_value=MagicMock(value="NORMAL")),
                    get_timeout=MagicMock(return_value=5.0),
                ),
                telegram=telegram,
                market=market,
                stock_code=stock_code,
                scan_candidates={},
                settings=settings,
            )
        # log_trade must be called with action="SELL" to close the ghost position
        ghost_close_calls = [
            c
            for c in mock_log_trade.call_args_list
            if c.kwargs.get("action") == "SELL"
            and "[ghost-close]" in (c.kwargs.get("rationale") or "")
        ]
        assert ghost_close_calls, "Expected ghost-close log_trade call was not made"
    @pytest.mark.asyncio
    async def test_normal_sell_failure_does_not_close_db(self) -> None:
        """Non-잔고없음 SELL failures must NOT close the DB position."""
        from src.strategy.models import ScenarioAction
        stock_code = "TSLA"
        current_price = 250.0
        balance_data = {
            "output1": [{"ovrs_pdno": stock_code, "ord_psbl_qty": "5", "ovrs_cblc_qty": "5"}],
            "output2": [{"tot_evlu_amt": "100000"}],
        }
        sell_result = {"rt_cd": "1", "msg1": "일시적 오류가 발생했습니다"}
        domestic_broker = MagicMock()
        domestic_broker.get_balance = AsyncMock(return_value={"output1": [], "output2": [{}]})
        overseas_broker = self._make_overseas_broker(current_price, balance_data, sell_result)
        market = self._make_overseas_market()
        sell_match = ScenarioMatch(
            stock_code=stock_code,
            matched_scenario=None,
            action=ScenarioAction.SELL,
            confidence=85,
            rationale="test",
        )
        engine = MagicMock(spec=ScenarioEngine)
        engine.evaluate = MagicMock(return_value=sell_match)
        risk = MagicMock()
        risk.validate_order = MagicMock()
        risk.check_circuit_breaker = MagicMock()
        telegram = MagicMock()
        telegram.notify_trade_execution = AsyncMock()
        telegram.notify_fat_finger = AsyncMock()
        telegram.notify_circuit_breaker = AsyncMock()
        telegram.notify_scenario_matched = AsyncMock()
        db_conn = MagicMock()
        with patch("src.main.log_trade") as mock_log_trade, patch(
            "src.main.get_open_position", return_value=None
        ):
            await trading_cycle(
                broker=domestic_broker,
                overseas_broker=overseas_broker,
                scenario_engine=engine,
                playbook=_make_playbook(market="US_NASDAQ"),
                risk=risk,
                db_conn=db_conn,
                decision_logger=MagicMock(),
                context_store=MagicMock(get_latest_timeframe=MagicMock(return_value=None)),
                criticality_assessor=MagicMock(
                    assess_market_conditions=MagicMock(return_value=MagicMock(value="NORMAL")),
                    get_timeout=MagicMock(return_value=5.0),
                ),
                telegram=telegram,
                market=market,
                stock_code=stock_code,
                scan_candidates={},
            )
        ghost_close_calls = [
            c
            for c in mock_log_trade.call_args_list
            if c.kwargs.get("action") == "SELL"
            and "[ghost-close]" in (c.kwargs.get("rationale") or "")
        ]
        assert not ghost_close_calls, "Ghost-close must NOT be triggered for non-잔고없음 errors"
--- a/tests/test_overseas_broker.py
+++ b/tests/test_overseas_broker.py
@@ -28,6 +28,7 @@ def mock_settings() -> Settings:
        KIS_APP_SECRET="test_secret",
        KIS_ACCOUNT_NO="12345678-01",
        GEMINI_API_KEY="test_gemini_key",
        MODE="paper",  # Explicitly set to avoid .env MODE=live override
    )
@@ -122,9 +123,10 @@ class TestFetchOverseasRankings:
        params = call_args[1]["params"]
        assert "/uapi/overseas-stock/v1/ranking/updown-rate" in url
        assert params["KEYB"] == ""  # Required by KIS API spec
        assert params["EXCD"] == "NAS"
        assert params["NDAY"] == "0"
-        assert params["GUBN"] == "1"
+        assert params["GUBN"] == "1"  # 1=상승율 — 변동성 스캐너는 급등 종목 우선
        assert params["VOL_RANG"] == "0"
        overseas_broker._broker._auth_headers.assert_called_with("HHDFS76290000")
@@ -157,6 +159,7 @@ class TestFetchOverseasRankings:
        params = call_args[1]["params"]
        assert "/uapi/overseas-stock/v1/ranking/volume-surge" in url
        assert params["KEYB"] == ""  # Required by KIS API spec
        assert params["EXCD"] == "NYS"
        assert params["MIXN"] == "0"
        assert params["VOL_RANG"] == "0"
--- a/tests/test_token_efficiency.py
+++ b/tests/test_token_efficiency.py
@@ -124,6 +124,10 @@ class TestPromptOptimizer:
        assert len(prompt) < 300
        assert "005930" in prompt
        assert "75000" in prompt
        # Keys must match parse_response expectations (#242)
        assert '"action"' in prompt
        assert '"confidence"' in prompt
        assert '"rationale"' in prompt
    def test_build_compressed_prompt_no_instructions(self):
        """Test compressed prompt without instructions."""
--- a/workflow/issue-271-runlog.md
+++ 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"
 ```