docs: bump requirements registry version for policy change sync

Reviewed-on: #386

.env.example

@@ -1,36 +1,82 @@
+# ============================================================
+# The Ouroboros — Environment Configuration
+# ============================================================
+# Copy this file to .env and fill in your values.
+# Lines starting with # are comments.
+
+# ============================================================
 # Korea Investment Securities API
+# ============================================================
 KIS_APP_KEY=your_app_key_here
 KIS_APP_SECRET=your_app_secret_here
 KIS_ACCOUNT_NO=12345678-01
-KIS_BASE_URL=https://openapivts.koreainvestment.com:9443
 
+# Paper trading (VTS): https://openapivts.koreainvestment.com:29443
+# Live trading:        https://openapi.koreainvestment.com:9443
+KIS_BASE_URL=https://openapivts.koreainvestment.com:29443
+
+# ============================================================
+# Trading Mode
+# ============================================================
+# paper = 모의투자 (safe for testing), live = 실전투자 (real money)
+MODE=paper
+
+# daily = batch per session, realtime = per-stock continuous scan
+TRADE_MODE=daily
+
+# Comma-separated market codes: KR, US, JP, HK, CN, VN
+ENABLED_MARKETS=KR,US
+
+# Simulated USD cash for paper (VTS) overseas trading.
+# VTS overseas balance API often returns 0; this value is used as fallback.
+# Set to 0 to disable fallback (not used in live mode).
+PAPER_OVERSEAS_CASH=50000.0
+
+# ============================================================
 # Google Gemini
+# ============================================================
 GEMINI_API_KEY=your_gemini_api_key_here
-GEMINI_MODEL=gemini-pro
+# Recommended: gemini-2.0-flash-exp or gemini-1.5-pro
+GEMINI_MODEL=gemini-2.0-flash-exp
 
+# ============================================================
 # Risk Management
+# ============================================================
 CIRCUIT_BREAKER_PCT=-3.0
 FAT_FINGER_PCT=30.0
 CONFIDENCE_THRESHOLD=80
 
+# ============================================================
 # Database
+# ============================================================
 DB_PATH=data/trade_logs.db
 
-# Rate Limiting (requests per second for KIS API)
-# Reduced to 5.0 to avoid "초당 거래건수 초과" errors (EGW00201)
-RATE_LIMIT_RPS=5.0
+# ============================================================
+# Rate Limiting
+# ============================================================
+# KIS API real limit is ~2 RPS. Keep at 2.0 for maximum safety.
+# Increasing this risks EGW00201 "초당 거래건수 초과" errors.
+RATE_LIMIT_RPS=2.0
 
-# Trading Mode (paper / live)
-MODE=paper
-
-# External Data APIs (optional — for enhanced decision-making)
+# ============================================================
+# External Data APIs (optional)
+# ============================================================
 # NEWS_API_KEY=your_news_api_key_here
 # NEWS_API_PROVIDER=alphavantage
 # MARKET_DATA_API_KEY=your_market_data_key_here
 
+# ============================================================
 # Telegram Notifications (optional)
+# ============================================================
 # Get bot token from @BotFather on Telegram
 # Get chat ID from @userinfobot or your chat
 # TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
 # TELEGRAM_CHAT_ID=123456789
 # TELEGRAM_ENABLED=true
+
+# ============================================================
+# Dashboard (optional)
+# ============================================================
+# DASHBOARD_ENABLED=false
+# DASHBOARD_HOST=127.0.0.1
+# DASHBOARD_PORT=8080

.gitea/ISSUE_TEMPLATE/runtime_verification.md

@@ -0,0 +1,41 @@
+---
+name: Runtime Verification Incident
+about: 실운영/스테이징 동작 검증 중 발견된 이상 징후 등록
+title: "[RUNTIME-VERIFY][SCN-XXX] "
+labels: runtime, verification
+---
+
+## Summary
+
+- 현상:
+- 최초 관측 시각(UTC):
+
+## Reproduction / Observation
+
+- 실행 모드(`live`/`paper`):
+- 세션(`NXT`, `US_PRE`, `US_DAY`, `US_AFTER`, ...):
+- 실행 커맨드:
+- 로그 경로:
+
+## Expected vs Actual
+
+- Expected:
+- Actual:
+
+## Requirement Mapping
+
+- REQ:
+- TASK:
+- TEST:
+
+## Temporary Mitigation
+
+- 즉시 완화책:
+
+## Close Criteria
+
+- [ ] Dev 수정 반영
+- [ ] Verifier 재검증 PASS
+- [ ] Runtime Verifier 재관측 PASS
+- [ ] `NOT_OBSERVED = 0`
+

.gitea/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,64 @@
+## Linked Issue
+
+- Closes #N
+
+## Scope
+
+- REQ: `REQ-...`
+- TASK: `TASK-...`
+- TEST: `TEST-...`
+
+## Ticket Stage
+
+- Current stage: `Implemented` / `Integrated` / `Observed` / `Accepted`
+- Previous stage evidence link:
+
+## Main -> Verifier Directive Contract
+
+- Scope: 대상 요구사항/코드/로그 경로
+- Method: 실행 커맨드 + 관측 포인트
+- PASS criteria:
+- FAIL criteria:
+- NOT_OBSERVED criteria:
+- Evidence format: PR 코멘트 `Coverage Matrix`
+
+## Verifier Coverage Matrix (Required)
+
+| Item | Evidence | Status (PASS/FAIL/NOT_OBSERVED) |
+|---|---|---|
+| REQ-... | 링크/로그 | PASS |
+
+`NOT_OBSERVED`가 1개라도 있으면 승인/머지 금지.
+
+## Gitea Preflight
+
+- [ ] `docs/commands.md`와 `docs/workflow.md` 트러블슈팅 선확인
+- [ ] `tea` 사용 (`gh` 미사용)
+
+## Session Handover Gate
+
+- [ ] `python3 scripts/session_handover_check.py --strict` 통과
+- [ ] `workflow/session-handover.md` 최신 엔트리가 현재 브랜치/당일(UTC) 기준으로 갱신됨
+- 최신 handover 엔트리 heading:
+
+## Docs Sync Gate (docs 파일 변경 시 필수)
+
+- [ ] `python3 scripts/validate_docs_sync.py` 통과 (`docs` 미변경 PR은 N/A 기재)
+
+## Runtime Evidence
+
+- 시스템 실제 구동 커맨드:
+- 모니터링 로그 경로:
+- 이상 징후/이슈 링크:
+
+## READ-ONLY Approval (Required when touching READ-ONLY files)
+
+- Touched READ-ONLY files:
+- Human approval:
+- Test suite 1:
+- Test suite 2:
+
+## Approval Gate
+
+- [ ] Static Verifier approval comment linked
+- [ ] Runtime Verifier approval comment linked

.gitea/workflows/ci.yml

@@ -0,0 +1,57 @@
+name: Gitea CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - feature/**
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: pip install ".[dev]"
+
+      - name: Session handover gate
+        run: python3 scripts/session_handover_check.py --strict --ci
+
+      - name: Validate governance assets
+        env:
+          GOVERNANCE_PR_TITLE: ${{ github.event.pull_request.title }}
+          GOVERNANCE_PR_BODY: ${{ github.event.pull_request.body }}
+        run: |
+          RANGE=""
+          if [ "${{ github.event_name }}" = "pull_request" ] && [ -n "${{ github.event.pull_request.base.sha }}" ]; then
+            RANGE="${{ github.event.pull_request.base.sha }}...${{ github.sha }}"
+          elif [ -n "${{ github.event.before }}" ] && [ "${{ github.event.before }}" != "0000000000000000000000000000000000000000" ]; then
+            RANGE="${{ github.event.before }}...${{ github.sha }}"
+          fi
+          if [ -n "$RANGE" ]; then
+            python3 scripts/validate_governance_assets.py "$RANGE"
+          else
+            python3 scripts/validate_governance_assets.py
+          fi
+
+      - name: Validate Ouroboros docs
+        run: python3 scripts/validate_ouroboros_docs.py
+
+      - name: Validate docs sync
+        run: python3 scripts/validate_docs_sync.py
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Run tests with coverage
+        run: pytest -v --cov=src --cov-report=term-missing --cov-fail-under=80

.github/workflows/backtest-gate.yml

@@ -0,0 +1,66 @@
+name: Backtest Gate
+
+on:
+  pull_request:
+    branches: ["**"]
+  push:
+    branches:
+      - "feature/**"
+  schedule:
+    # Daily scheduled gate (KST 01:20)
+    - cron: "20 16 * * *"
+  workflow_dispatch:
+    inputs:
+      mode:
+        description: "backtest mode (auto|smoke|full)"
+        required: false
+        default: "auto"
+      base_ref:
+        description: "git base ref for changed-file diff"
+        required: false
+        default: "origin/main"
+
+jobs:
+  backtest-gate:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: backtest-gate-${{ github.ref }}
+      cancel-in-progress: true
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: pip install ".[dev]"
+
+      - name: Resolve base ref
+        id: base
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            echo "ref=origin/${{ github.base_ref }}" >> "$GITHUB_OUTPUT"
+          elif [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ -n "${{ github.event.inputs.base_ref }}" ]; then
+            echo "ref=${{ github.event.inputs.base_ref }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "ref=origin/main" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Run backtest gate
+        env:
+          BASE_REF: ${{ steps.base.outputs.ref }}
+          BACKTEST_MODE: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.mode || 'auto' }}
+          FORCE_FULL_BACKTEST: ${{ github.event_name == 'schedule' && 'true' || 'false' }}
+        run: bash scripts/backtest_gate.sh
+
+      - name: Upload backtest logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: backtest-gate-logs
+          path: data/backtest-gate/*.log

.github/workflows/ci.yml

@@ -21,6 +21,32 @@ jobs:
       - name: Install dependencies
         run: pip install ".[dev]"
 
+      - name: Session handover gate
+        run: python3 scripts/session_handover_check.py --strict --ci
+
+      - name: Validate governance assets
+        env:
+          GOVERNANCE_PR_TITLE: ${{ github.event.pull_request.title }}
+          GOVERNANCE_PR_BODY: ${{ github.event.pull_request.body }}
+        run: |
+          RANGE=""
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            RANGE="${{ github.event.pull_request.base.sha }}...${{ github.sha }}"
+          elif [ "${{ github.event_name }}" = "push" ] && [ "${{ github.event.before }}" != "0000000000000000000000000000000000000000" ]; then
+            RANGE="${{ github.event.before }}...${{ github.sha }}"
+          fi
+          if [ -n "$RANGE" ]; then
+            python3 scripts/validate_governance_assets.py "$RANGE"
+          else
+            python3 scripts/validate_governance_assets.py
+          fi
+
+      - name: Validate Ouroboros docs
+        run: python3 scripts/validate_ouroboros_docs.py
+
+      - name: Validate docs sync
+        run: python3 scripts/validate_docs_sync.py
+
       - name: Lint
         run: ruff check src/ tests/
 

CLAUDE.md

@@ -81,12 +81,13 @@ SCANNER_TOP_N=3              # Max candidates per scan
 - **Evolution-ready** — Selection context logged for strategy optimization
 - **Fault-tolerant** — Falls back to static watchlist on API failure
 
-### Realtime Mode Only
+### Trading Mode Integration
 
-Smart Scanner runs in `TRADE_MODE=realtime` only. Daily mode uses static watchlists for batch efficiency.
+Smart Scanner runs in both `TRADE_MODE=realtime` and `daily` paths. On API failure, domestic stocks fall back to a static watchlist; overseas stocks fall back to a dynamic universe (active positions, recent holdings).
 
 ## Documentation
 
+- **[Documentation Hub](docs/README.md)** — Top-level doc routing and reading order
 - **[Workflow Guide](docs/workflow.md)** — Git workflow policy and agent-based development
 - **[Command Reference](docs/commands.md)** — Common failures, build commands, troubleshooting
 - **[Architecture](docs/architecture.md)** — System design, components, data flow
@@ -94,6 +95,7 @@ Smart Scanner runs in `TRADE_MODE=realtime` only. Daily mode uses static watchli
 - **[Testing](docs/testing.md)** — Test structure, coverage requirements, writing tests
 - **[Agent Policies](docs/agents.md)** — Prime directives, constraints, prohibited actions
 - **[Requirements Log](docs/requirements-log.md)** — User requirements and feedback tracking
+- **[Live Trading Checklist](docs/live-trading-checklist.md)** — 모의→실전 전환 체크리스트
 
 ## Core Principles
 
@@ -121,7 +123,7 @@ src/
 ├── broker/          # KIS API client (domestic + overseas)
 ├── context/         # L1-L7 hierarchical memory system
 ├── core/            # Risk manager (READ-ONLY)
-├── dashboard/       # FastAPI read-only monitoring (8 API endpoints)
+├── dashboard/       # FastAPI read-only monitoring (10 API endpoints)
 ├── data/            # External data integration (news, market data, calendar)
 ├── evolution/       # Self-improvement (optimizer, daily review, scorecard)
 ├── logging/         # Decision logger (audit trail)
@@ -132,7 +134,7 @@ src/
 ├── main.py          # Trading loop orchestrator
 └── config.py        # Settings (from .env)
 
-tests/               # 551 tests across 25 files
+tests/               # 998 tests across 41 files
 docs/                # Extended documentation
 ```
 
@@ -170,7 +172,7 @@ Markets auto-detected based on timezone and enabled in `ENABLED_MARKETS` env var
 - `src/core/risk_manager.py` is **READ-ONLY** — changes require human approval
 - Circuit breaker at -3.0% P&L — may only be made **stricter**
 - Fat-finger protection: max 30% of cash per order — always enforced
-- Confidence < 80 → force HOLD — cannot be weakened
+- Confidence 임계값 (market_outlook별, 낮출 수 없음): BEARISH ≥ 90, NEUTRAL/기본 ≥ 80, BULLISH ≥ 75
 - All code changes → corresponding tests → coverage ≥ 80%
 
 ## Contributing

README.md

@@ -39,7 +39,7 @@ KIS(한국투자증권) API로 매매하고, Google Gemini로 판단하며, 자
 | 컨텍스트 | `src/context/` | L1-L7 계층형 메모리 시스템 |
 | 분석 | `src/analysis/` | RSI, ATR, Smart Volatility Scanner |
 | 알림 | `src/notifications/` | 텔레그램 양방향 (알림 + 9개 명령어) |
-| 대시보드 | `src/dashboard/` | FastAPI 읽기 전용 모니터링 (8개 API) |
+| 대시보드 | `src/dashboard/` | FastAPI 읽기 전용 모니터링 (10개 API) |
 | 진화 | `src/evolution/` | 전략 진화 + Daily Review + Scorecard |
 | 의사결정 로그 | `src/logging/` | 전체 거래 결정 감사 추적 |
 | 데이터 | `src/data/` | 뉴스, 시장 데이터, 경제 캘린더 연동 |
@@ -153,19 +153,16 @@ docker compose up -d ouroboros
 
 ## 테스트
 
-551개 테스트가 25개 파일에 걸쳐 구현되어 있습니다. 최소 커버리지 80%.
+998개 테스트가 41개 파일에 걸쳐 구현되어 있습니다. 최소 커버리지 80%.
 
 ```
-tests/test_scenario_engine.py    — 시나리오 매칭 (44개)
-tests/test_data_integration.py   — 외부 데이터 연동 (38개)
-tests/test_pre_market_planner.py — 플레이북 생성 (37개)
-tests/test_main.py               — 거래 루프 통합 (37개)
-tests/test_token_efficiency.py   — 토큰 최적화 (34개)
-tests/test_strategy_models.py    — 전략 모델 검증 (33개)
-tests/test_telegram_commands.py  — 텔레그램 명령어 (31개)
-tests/test_latency_control.py    — 지연시간 제어 (30개)
-tests/test_telegram.py           — 텔레그램 알림 (25개)
-... 외 16개 파일
+tests/test_main.py               — 거래 루프 통합
+tests/test_scenario_engine.py    — 시나리오 매칭
+tests/test_pre_market_planner.py — 플레이북 생성
+tests/test_overseas_broker.py    — 해외 브로커
+tests/test_telegram_commands.py  — 텔레그램 명령어
+tests/test_telegram.py           — 텔레그램 알림
+... 외 35개 파일  ※ 파일별 수치는 CI 기준으로 변동 가능
 ```
 
 **상세**: [docs/testing.md](docs/testing.md)
@@ -177,8 +174,8 @@ tests/test_telegram.py           — 텔레그램 알림 (25개)
 - **AI**: Google Gemini Pro
 - **DB**: SQLite (5개 테이블: trades, contexts, decision_logs, playbooks, context_metadata)
 - **대시보드**: FastAPI + uvicorn
-- **검증**: pytest + coverage (551 tests)
-- **CI/CD**: GitHub Actions
+- **검증**: pytest + coverage (998 tests)
+- **CI/CD**: Gitea CI (`.gitea/workflows/ci.yml`)
 - **배포**: Docker + Docker Compose
 
 ## 프로젝트 구조
@@ -212,7 +209,7 @@ The-Ouroboros/
 │   ├── config.py                # Pydantic 설정
 │   ├── db.py                    # SQLite 데이터베이스
 │   └── main.py                  # 비동기 거래 루프
-├── tests/                       # 551개 테스트 (25개 파일)
+├── tests/                       # 998개 테스트 (41개 파일)
 ├── Dockerfile                   # 멀티스테이지 빌드
 ├── docker-compose.yml           # 서비스 오케스트레이션
 └── pyproject.toml               # 의존성 및 도구 설정
@@ -220,6 +217,7 @@ The-Ouroboros/
 
 ## 문서
 
+- **[문서 허브](docs/README.md)** — 전체 문서 라우팅, 우선순위, 읽기 순서
 - **[아키텍처](docs/architecture.md)** — 시스템 설계, 컴포넌트, 데이터 흐름
 - **[테스트](docs/testing.md)** — 테스트 구조, 커버리지, 작성 가이드
 - **[명령어](docs/commands.md)** — CLI, Dashboard, Telegram 명령어

docs/README.md

@@ -0,0 +1,48 @@
+# Documentation Hub
+
+이 문서는 저장소 전체 문서의 상위 라우팅 허브입니다.
+세부 문서로 바로 들어가기 전에 아래 우선순위와 읽기 순서를 기준으로 이동하세요.
+
+## Priority (SSOT)
+
+1. 실행/협업 규칙 SSOT: [workflow.md](./workflow.md)
+2. 명령/장애 대응 SSOT: [commands.md](./commands.md)
+3. 테스트/검증 SSOT: [testing.md](./testing.md)
+4. 에이전트 제약 SSOT: [agents.md](./agents.md)
+5. 요구사항 추적 SSOT: [requirements-log.md](./requirements-log.md)
+6. Ouroboros 실행 문서 허브: [ouroboros/README.md](./ouroboros/README.md)
+
+## Recommended Reading Order
+
+1. [workflow.md](./workflow.md)
+2. [commands.md](./commands.md)
+3. [testing.md](./testing.md)
+4. [agents.md](./agents.md)
+5. [architecture.md](./architecture.md)
+6. [context-tree.md](./context-tree.md)
+7. [disaster_recovery.md](./disaster_recovery.md)
+8. [live-trading-checklist.md](./live-trading-checklist.md)
+9. [ouroboros/README.md](./ouroboros/README.md)
+
+## Document Map
+
+- Core
+  - [workflow.md](./workflow.md): 브랜치/PR/리뷰/세션 handover 정책
+  - [commands.md](./commands.md): 실행 커맨드, 실패 사례, 트러블슈팅
+  - [testing.md](./testing.md): 테스트 구조, 작성 규칙, 검증 명령
+  - [agents.md](./agents.md): 에이전트 작업 제약과 금지 행위
+  - [agent-constraints.md](./agent-constraints.md): 영속 제약/운영 불변식(agents.md 보완)
+  - [skills.md](./skills.md): 설치/사용 가능한 스킬 목록과 활용 가이드
+- Design and Operations
+  - [architecture.md](./architecture.md): 시스템 구조와 컴포넌트 책임
+  - [context-tree.md](./context-tree.md): L1-L7 컨텍스트 계층 설계
+  - [disaster_recovery.md](./disaster_recovery.md): 백업/복구 절차
+  - [live-trading-checklist.md](./live-trading-checklist.md): 실전 전환 체크리스트
+- Governance and Planning
+  - [requirements-log.md](./requirements-log.md): 요구사항/피드백 히스토리
+  - [ouroboros/README.md](./ouroboros/README.md): v2/v3 실행 문서 라우팅
+
+## Change Rule
+
+- 문서 신규/이동/대규모 개편 시 이 파일의 링크와 분류를 함께 갱신합니다.
+- 링크는 상대경로만 사용합니다.

docs/agent-constraints.md

@@ -12,6 +12,8 @@ It is distinct from `docs/requirements-log.md`, which records **project/product
 
 1. **Workflow enforcement**
    - Follow `docs/workflow.md` for all changes.
+   - Before any Gitea issue/PR/comment operation, read `docs/commands.md` and `docs/workflow.md` troubleshooting section.
+   - Use `tea` for Gitea operations; do not use GitHub CLI (`gh`) in this repository workflow.
    - Create a Gitea issue before any code or documentation change.
    - Work on a feature branch `feature/issue-{N}-{short-description}` and open a PR.
    - Never commit directly to `main`.
@@ -30,6 +32,16 @@ It is distinct from `docs/requirements-log.md`, which records **project/product
      (or in a dedicated policy doc) and reference it when working.
    - Keep entries short and concrete, with dates.
 
+5. **Session start handover gate**
+   - Before implementation/verification work, run `python3 scripts/session_handover_check.py --strict`.
+   - Keep `workflow/session-handover.md` updated with a same-day entry for the active branch.
+   - If the check fails, stop and fix handover artifacts first.
+
+6. **Process-change-first execution gate**
+   - If process/governance change is required, merge the process ticket to the feature branch first.
+   - Do not start code/test edits for implementation tickets until process merge evidence is confirmed.
+   - Subagents must be constrained to read-only exploration until the process gate is satisfied.
+
 ## Change Control
 
 - Changes to this file follow the same workflow as code changes.
@@ -43,3 +55,15 @@ It is distinct from `docs/requirements-log.md`, which records **project/product
 - When work requires guidance, consult the relevant `docs/` policies first.
 - Any code change must be accompanied by relevant documentation updates.
 - Persist user constraints across sessions by recording them in this document.
+
+### 2026-02-27
+
+- All agents must pre-read `docs/commands.md` and `docs/workflow.md` troubleshooting before running Gitea issue/PR/comment commands.
+- `gh` CLI is prohibited for repository ticket/PR operations; use `tea` (or documented Gitea API fallback only).
+- Session start must pass `python3 scripts/session_handover_check.py --strict`, with branch-matched entry in `workflow/session-handover.md`.
+
+### 2026-02-27
+
+- Apply process-change-first as an execution gate: process ticket must be merged before implementation ticket coding.
+- Handover entry must record concrete `next_ticket` and `process_gate_checked`; placeholders are not allowed in strict gate.
+- Before process merge confirmation, all subagent tasks must remain read-only (analysis only).

docs/architecture.md

@@ -84,6 +84,37 @@ High-frequency trading with individual stock analysis:
 - Momentum scoring (0-100 scale)
 - Breakout/breakdown pattern detection
 
+**TripleBarrierLabeler** (`triple_barrier.py`) — Financial time-series labeling (v2)
+
+- Triple Barrier method: upper (take-profit), lower (stop-loss), time barrier
+- First-touch labeling: labels confirmed by whichever barrier is breached first
+- `max_holding_minutes` (calendar-minute) time barrier — session-aware, bar-period independent
+- Tie-break mode: `"stop_first"` (conservative) or `"take_first"`
+- Feature-label strict separation to prevent look-ahead bias
+
+**BacktestPipeline** (`backtest_pipeline.py`) — End-to-end validation pipeline (v2)
+
+- `run_v2_backtest_pipeline()`: cost guard → triple barrier labeling → walk-forward splits → fold scoring
+- `BacktestPipelineResult`: artifact contract for reproducible output
+- `fold_has_leakage()`: leakage detection utility
+
+**WalkForwardSplit** (`walk_forward_split.py`) — Time-series validation (v2)
+
+- Fold-based walk-forward splits (no random shuffling)
+- Purge/Embargo: excludes N bars before/after fold boundaries to prevent data leakage
+
+**BacktestExecutionModel** (`backtest_execution_model.py`) — Conservative fill simulation (v2/v3)
+
+- Session-aware slippage: KRX_REG 5bps, NXT_AFTER 15bps, US_REG 3bps, US_PRE/DAY 30-50bps
+- Order failure rate simulation per session
+- Partial fill rate simulation with min/max ratio bounds
+- Unfavorable-direction fill assumption (no simple close-price fill)
+
+**BacktestCostGuard** (`backtest_cost_guard.py`) — Cost model validator (v2)
+
+- `validate_backtest_cost_model()`: fail-fast check that session cost assumptions are present
+- Enforces realistic cost assumptions before any backtest run proceeds
+
 **SmartVolatilityScanner** (`smart_scanner.py`) — Python-first filtering pipeline
 
 - **Domestic (KR)**:
@@ -98,7 +129,7 @@ High-frequency trading with individual stock analysis:
   - **Step 4**: Return top N candidates (default 3)
 - **Fallback (overseas only)**: If ranking API is unavailable, uses dynamic universe
   from runtime active symbols + recent traded symbols + current holdings (no static watchlist)
-- **Realtime mode only**: Daily mode uses batch processing for API efficiency
+- **Both modes**: Realtime 중심이지만 Daily 경로(`run_daily_session()`)에서도 후보 선별에 사용
 
 **Benefits:**
 - Reduces Gemini API calls from 20-30 stocks to 1-3 qualified candidates
@@ -124,9 +155,9 @@ High-frequency trading with individual stock analysis:
 
 - Selects appropriate context layers for current market conditions
 
-### 4. Risk Manager (`src/core/risk_manager.py`)
+### 4. Risk Manager & Session Policy (`src/core/`)
 
-**RiskManager** — Safety circuit breaker and order validation
+**RiskManager** (`risk_manager.py`) — Safety circuit breaker and order validation
 
 > **READ-ONLY by policy** (see [`docs/agents.md`](./agents.md))
 
@@ -136,8 +167,59 @@ High-frequency trading with individual stock analysis:
 - **Fat-Finger Protection**: Rejects orders exceeding 30% of available cash
   - Must always be enforced, cannot be disabled
 
+**OrderPolicy** (`order_policy.py`) — Session classification and order type enforcement (v3)
+
+- `classify_session_id()`: Classifies current KR/US session from KST clock
+  - KR: `NXT_PRE` (08:00-08:50), `KRX_REG` (09:00-15:30), `NXT_AFTER` (15:30-20:00)
+  - US: `US_DAY` (10:00-18:00), `US_PRE` (18:00-23:30), `US_REG` (23:30-06:00), `US_AFTER` (06:00-07:00)
+- Low-liquidity session detection: `NXT_AFTER`, `US_PRE`, `US_DAY`, `US_AFTER`
+- Market order forbidden in low-liquidity sessions (`OrderPolicyRejected` raised)
+- Limit/IOC/FOK orders always allowed
+
+**KillSwitch** (`kill_switch.py`) — Emergency trading halt orchestration (v2)
+
+- Fixed 5-step atomic sequence:
+  1. Block new orders (`new_orders_blocked = True`)
+  2. Cancel all unfilled orders
+  3. Refresh order state (query final status)
+  4. Reduce risk (force-close or reduce positions)
+  5. Snapshot state + send Telegram alert
+- Async, injectable step callables — each step individually testable
+- Highest priority: overrides overnight exception and all other rules
+
+**BlackoutManager** (`blackout_manager.py`) — KIS maintenance window handling (v3)
+
+- Configurable blackout windows (e.g., `23:30-00:10 KST`)
+- `queue_order()`: Queues order intent during blackout, enforces max queue size
+- `pop_recovery_batch()`: Returns queued intents after recovery
+- Recovery revalidation path (in `src/main.py`):
+  - Stale BUY drop (position already exists)
+  - Stale SELL drop (position absent)
+  - `validate_order_policy()` rechecked
+  - Price drift check (>5% → drop, configurable via `BLACKOUT_RECOVERY_MAX_PRICE_DRIFT_PCT`)
+
 ### 5. Strategy (`src/strategy/`)
 
+**PositionStateMachine** (`position_state_machine.py`) — 4-state sell state machine (v2)
+
+- States: `HOLDING` → `BE_LOCK` → `ARMED` → `EXITED`
+  - `HOLDING`: Normal holding
+  - `BE_LOCK`: Profit ≥ `be_arm_pct` — stop-loss elevated to break-even
+  - `ARMED`: Profit ≥ `arm_pct` — peak-tracking trailing stop active
+  - `EXITED`: Position closed
+- `promote_state()`: Immediately elevates to highest admissible state (handles gaps/skips)
+- `evaluate_exit_first()`: EXITED conditions checked before state promotion
+- Monotonic: states only move up, never down
+
+**ExitRules** (`exit_rules.py`) — 4-layer composite exit logic (v2)
+
+- **Hard Stop**: `unrealized <= hard_stop_pct` (always enforced, ATR-adaptive for KR)
+- **Break-Even Lock**: Once in BE_LOCK/ARMED, exit if price falls to entry price
+- **ATR Trailing Stop**: `trailing_stop_price = peak_price - (atr_multiplier_k × ATR)`
+- **Model Signal**: Exit if `pred_down_prob >= model_prob_threshold AND liquidity_weak`
+- `evaluate_exit()`: Returns `ExitEvaluation` with next state, exit flag, reason, trailing price
+- `ExitRuleConfig`: Frozen dataclass with all tunable parameters
+
 **Pre-Market Planner** (`pre_market_planner.py`) — AI playbook generation
 
 - Runs before market open (configurable `PRE_MARKET_MINUTES`, default 30)
@@ -195,7 +277,7 @@ High-frequency trading with individual stock analysis:
 - Configurable host/port (`DASHBOARD_HOST`, `DASHBOARD_PORT`, default `127.0.0.1:8080`)
 - Serves static HTML frontend
 
-**8 API Endpoints:**
+**10 API Endpoints:**
 
 | Endpoint | Method | Description |
 |----------|--------|-------------|
@@ -207,6 +289,8 @@ High-frequency trading with individual stock analysis:
 | `/api/context/{layer}` | GET | Query context by layer (L1-L7) |
 | `/api/decisions` | GET | Decision log entries with outcomes |
 | `/api/scenarios/active` | GET | Today's matched scenarios |
+| `/api/pnl/history` | GET | P&L history time series |
+| `/api/positions` | GET | Current open positions |
 
 ### 8. Notifications (`src/notifications/telegram_client.py`)
 
@@ -448,8 +532,12 @@ CREATE TABLE trades (
     pnl REAL DEFAULT 0.0,
     market TEXT DEFAULT 'KR',
     exchange_code TEXT DEFAULT 'KRX',
+    session_id TEXT DEFAULT 'UNKNOWN',  -- v3: KRX_REG | NXT_AFTER | US_REG | US_PRE | ...
     selection_context TEXT,        -- JSON: {rsi, volume_ratio, signal, score}
-    decision_id TEXT              -- Links to decision_logs
+    decision_id TEXT,             -- Links to decision_logs
+    strategy_pnl REAL,            -- v3: Core strategy P&L (separated from FX)
+    fx_pnl REAL DEFAULT 0.0,      -- v3: FX gain/loss for USD trades (schema ready, activation pending)
+    mode TEXT                     -- paper | live
 );
 ```
 
@@ -475,13 +563,14 @@ CREATE TABLE decision_logs (
     stock_code TEXT,
     market TEXT,
     exchange_code TEXT,
+    session_id TEXT DEFAULT 'UNKNOWN',  -- v3: session when decision was made
     action TEXT,
     confidence INTEGER,
     rationale TEXT,
     context_snapshot TEXT,         -- JSON: full context at decision time
     input_data TEXT,              -- JSON: market data used
     outcome_pnl REAL,
-    outcome_accuracy REAL,
+    outcome_accuracy INTEGER,
     reviewed INTEGER DEFAULT 0,
     review_notes TEXT
 );
@@ -494,7 +583,7 @@ CREATE TABLE playbooks (
     id INTEGER PRIMARY KEY AUTOINCREMENT,
     date TEXT NOT NULL,
     market TEXT NOT NULL,
-    status TEXT DEFAULT 'generated',
+    status TEXT NOT NULL DEFAULT 'pending',  -- pending → generated → active → expired
     playbook_json TEXT NOT NULL,   -- Full playbook with scenarios
     generated_at TEXT NOT NULL,
     token_count INTEGER,
@@ -552,6 +641,29 @@ PLANNER_TIMEOUT_SECONDS=60    # Timeout for playbook generation
 DEFENSIVE_PLAYBOOK_ON_FAILURE=true  # Fallback on AI failure
 RESCAN_INTERVAL_SECONDS=300   # Scenario rescan interval during trading
 
+# Optional — v2 Exit Rules (State Machine)
+STAGED_EXIT_BE_ARM_PCT=1.2    # Break-even lock threshold (%)
+STAGED_EXIT_ARM_PCT=3.0       # Armed state threshold (%)
+KR_ATR_STOP_MULTIPLIER_K=2.0  # ATR multiplier for KR dynamic hard stop
+KR_ATR_STOP_MIN_PCT=-2.0      # KR hard stop floor (must tighten, negative)
+KR_ATR_STOP_MAX_PCT=-7.0      # KR hard stop ceiling (loosest, negative)
+
+# Optional — v2 Trade Filters
+STOP_LOSS_COOLDOWN_MINUTES=120  # Cooldown after stop-loss before re-entry (same ticker)
+US_MIN_PRICE=5.0              # Minimum US stock price for BUY ($)
+
+# Optional — v3 Session Risk Management
+SESSION_RISK_RELOAD_ENABLED=true   # Reload risk params at session boundaries
+SESSION_RISK_PROFILES_JSON="{}"    # Per-session overrides JSON: {"KRX_REG": {"be_arm_pct": 1.0}}
+OVERNIGHT_EXCEPTION_ENABLED=true   # Allow holding through session close (conditions apply)
+
+# Optional — v3 Blackout (KIS maintenance windows)
+ORDER_BLACKOUT_ENABLED=true
+ORDER_BLACKOUT_WINDOWS_KST=23:30-00:10   # Comma-separated: "HH:MM-HH:MM"
+ORDER_BLACKOUT_QUEUE_MAX=500             # Max queued orders during blackout
+BLACKOUT_RECOVERY_PRICE_REVALIDATION_ENABLED=true
+BLACKOUT_RECOVERY_MAX_PRICE_DRIFT_PCT=5.0  # Drop recovery order if price drifted >5%
+
 # Optional — Smart Scanner (realtime mode only)
 RSI_OVERSOLD_THRESHOLD=30     # 0-50, oversold threshold
 RSI_MOMENTUM_THRESHOLD=70     # 50-100, momentum threshold

docs/commands.md

@@ -4,8 +4,61 @@
 
 **Critical: Learn from failures. Never repeat the same failed command without modification.**
 
+## Repository VCS Rule (Mandatory)
+
+- 이 저장소의 티켓/PR/코멘트 작업은 Gitea 기준으로 수행한다.
+- `gh`(GitHub CLI) 명령 사용은 금지한다.
+- 기본 도구는 `tea`이며, `tea` 미지원 케이스만 Gitea API를 fallback으로 사용한다.
+- 실행 전 `docs/workflow.md`의 `Gitea CLI Formatting Troubleshooting`을 반드시 확인한다.
+
+## Session Handover Preflight (Mandatory)
+
+- 세션 시작 직후(코드 변경 전) 아래 명령을 먼저 실행한다.
+
+```bash
+python3 scripts/session_handover_check.py --strict
+```
+
+- 실패 시 `workflow/session-handover.md` 최신 엔트리를 보강한 뒤 재실행한다.
+
+## Docs Sync Validator (Mandatory for docs changes)
+
+- 문서 변경 PR에서는 아래 명령으로 동기화 검증을 먼저 실행한다.
+
+```bash
+python3 scripts/validate_docs_sync.py
+```
+
+- 검증 실패 시 메시지 기준으로 즉시 수정한다.
+  - `absolute link is forbidden`: 문서 링크에 절대경로(`/...`) 사용
+  - `broken link`: 상대경로 링크 대상 파일/앵커 누락
+  - `missing core doc link reference`: `README.md`/`CLAUDE.md` 핵심 링크 누락
+  - `duplicated API endpoint row`: `docs/commands.md` API endpoint 표 중복 행
+  - `missing dynamic test count guidance`: `docs/testing.md`에 `pytest --collect-only -q` 가이드 누락
+
 ### tea CLI (Gitea Command Line Tool)
 
+#### ❌ Comment Newline Escaping (`\n` rendered literally)
+```bash
+YES="" ~/bin/tea comment 374 "line1\nline2"
+# Web UI shows "\n" as text instead of line breaks
+```
+**💡 Reason:** Inline string escaping is interpreted literally before comment submission.
+
+**✅ Solution:** Use file-based helper to preserve multiline text
+```bash
+cat > /tmp/comment.md <<'EOF'
+line1
+line2
+EOF
+
+scripts/tea_comment.sh 374 /tmp/comment.md
+```
+
+**📝 Notes:**
+- `scripts/tea_comment.sh` accepts stdin with `-` as body source.
+- The helper fails fast when body looks like escaped-newline text only.
+
 #### ❌ TTY Error - Interactive Confirmation Fails
 ```bash
 ~/bin/tea issues create --repo X --title "Y" --description "Z"
@@ -119,7 +172,7 @@ No decorator needed for async tests.
 # Install all dependencies (production + dev)
 pip install -e ".[dev]"
 
-# Run full test suite with coverage (551 tests across 25 files)
+# Run full test suite with coverage (998 tests across 41 files)
 pytest -v --cov=src --cov-report=term-missing
 
 # Run a single test file
@@ -140,6 +193,18 @@ python -m src.main --mode=paper
 # Run with dashboard enabled
 python -m src.main --mode=paper --dashboard
 
+# Runtime verification monitor (coverage + forbidden invariants)
+bash scripts/runtime_verify_monitor.sh
+
+# Runtime monitor with explicit policy timezone (example: KST)
+POLICY_TZ=Asia/Seoul bash scripts/runtime_verify_monitor.sh
+
+# Session handover gate (must pass before implementation)
+python3 scripts/session_handover_check.py --strict
+
+# Follow runtime verification log
+tail -f data/overnight/runtime_verify_*.log
+
 # Docker
 docker compose up -d ouroboros          # Run agent
 docker compose --profile test up test   # Run tests in container
@@ -173,6 +238,8 @@ Dashboard runs as a daemon thread on `DASHBOARD_HOST:DASHBOARD_PORT` (default: `
 | `GET /api/context/{layer}` | Context data by layer L1-L7 (query: `timeframe`) |
 | `GET /api/decisions` | Decision log entries (query: `limit`, `market`) |
 | `GET /api/scenarios/active` | Today's matched scenarios |
+| `GET /api/pnl/history` | P&L history over time |
+| `GET /api/positions` | Current open positions |
 
 ## Telegram Commands
 

docs/live-trading-checklist.md

@@ -0,0 +1,131 @@
+# 실전 전환 체크리스트
+
+모의 거래(paper)에서 실전(live)으로 전환하기 전에 아래 항목을 **순서대로** 모두 확인하세요.
+
+---
+
+## 1. 사전 조건
+
+### 1-1. KIS OpenAPI 실전 계좌 준비
+- [ ] 한국투자증권 계좌 개설 완료 (일반 위탁 계좌)
+- [ ] OpenAPI 실전 사용 신청 (KIS 홈페이지 → Open API → 서비스 신청)
+- [ ] 실전용 APP_KEY / APP_SECRET 발급 완료
+- [ ] KIS_ACCOUNT_NO 형식 확인: `XXXXXXXX-XX` (8자리-2자리)
+
+### 1-2. 리스크 파라미터 검토
+- [ ] `CIRCUIT_BREAKER_PCT` 확인: 기본값 -3.0% (더 엄격하게 조정 권장)
+- [ ] `FAT_FINGER_PCT` 확인: 기본값 30.0% (1회 주문 최대 잔고 대비 %)
+- [ ] `CONFIDENCE_THRESHOLD` 확인: BEARISH ≥ 90, NEUTRAL ≥ 80, BULLISH ≥ 75
+- [ ] 초기 투자금 결정 및 해외 주식 운용 한도 설정
+
+### 1-3. 시스템 요건
+- [ ] 커버리지 80% 이상 유지 확인: `pytest --cov=src`
+- [ ] 타입 체크 통과: `mypy src/ --strict`
+- [ ] Lint 통과: `ruff check src/ tests/`
+
+---
+
+## 2. 환경 설정
+
+### 2-1. `.env` 파일 수정
+
+```bash
+# 1. KIS 실전 URL로 변경 (모의: openapivts 포트 29443)
+KIS_BASE_URL=https://openapi.koreainvestment.com:9443
+
+# 2. 실전 APP_KEY / APP_SECRET으로 교체
+KIS_APP_KEY=<실전_APP_KEY>
+KIS_APP_SECRET=<실전_APP_SECRET>
+KIS_ACCOUNT_NO=<실전_계좌번호>
+
+# 3. 모드를 live로 변경
+MODE=live
+
+# 4. PAPER_OVERSEAS_CASH 비활성화 (live 모드에선 무시되지만 명시적으로 0 설정)
+PAPER_OVERSEAS_CASH=0
+```
+
+> ⚠️ `KIS_BASE_URL` 포트 주의:
+> - **모의(VTS)**: `https://openapivts.koreainvestment.com:29443`
+> - **실전**: `https://openapi.koreainvestment.com:9443`
+
+### 2-2. TR_ID 자동 분기 확인
+
+아래 TR_ID는 `MODE` 값에 따라 코드에서 **자동으로 선택**됩니다.
+별도 설정 불필요하나, 문제 발생 시 아래 표를 참조하세요.
+
+| 구분 | 모의 TR_ID | 실전 TR_ID |
+|------|-----------|-----------|
+| 국내 잔고 조회 | `VTTC8434R` | `TTTC8434R` |
+| 국내 현금 매수 | `VTTC0012U` | `TTTC0012U` |
+| 국내 현금 매도 | `VTTC0011U` | `TTTC0011U` |
+| 해외 잔고 조회 | `VTTS3012R` | `TTTS3012R` |
+| 해외 매수 | `VTTT1002U` | `TTTT1002U` |
+| 해외 매도 | `VTTT1001U` | `TTTT1006U` |
+
+> **출처**: `docs/한국투자증권_오픈API_전체문서_20260221_030000.xlsx` (공식 문서 기준)
+
+---
+
+## 3. 최종 확인
+
+### 3-1. 실전 시작 전 점검
+- [ ] DB 백업 완료: `data/trade_logs.db` → `data/backups/`
+- [ ] Telegram 알림 설정 확인 (실전에서는 알림이 더욱 중요)
+- [ ] 소액으로 첫 거래 진행 후 TR_ID/계좌 정상 동작 확인
+
+### 3-2. 실행 명령
+
+```bash
+# 실전 모드로 실행
+python -m src.main --mode=live
+
+# 대시보드 함께 실행 (별도 터미널에서 모니터링)
+python -m src.main --mode=live --dashboard
+```
+
+### 3-3. 실전 시작 직후 확인 사항
+- [ ] 로그에 `MODE=live` 출력 확인
+- [ ] 첫 잔고 조회 성공 (ConnectionError 없음)
+- [ ] Telegram 알림 수신 확인 ("System started")
+- [ ] 첫 주문 후 KIS 앱에서 체결 내역 확인
+
+---
+
+## 4. 비상 정지 방법
+
+### 즉각 정지
+```bash
+# 터미널에서 Ctrl+C (정상 종료 트리거)
+# 또는 Telegram 봇 명령:
+/stop
+```
+
+### Circuit Breaker 발동 시
+- CB가 발동되면 자동으로 거래 중단 및 Telegram 알림 전송
+- CB 임계값: `CIRCUIT_BREAKER_PCT` (기본 -3.0%)
+- **임계값은 엄격하게만 조정 가능** (더 낮은 음수 값으로만 변경)
+
+---
+
+## 5. 롤백 절차
+
+실전 전환 후 문제 발생 시:
+
+```bash
+# 1. 즉시 .env에서 MODE=paper로 복원
+# 2. 재시작
+python -m src.main --mode=paper
+
+# 3. DB에서 최근 거래 확인
+sqlite3 data/trade_logs.db "SELECT * FROM trades ORDER BY id DESC LIMIT 20;"
+```
+
+---
+
+## 관련 문서
+
+- [시스템 아키텍처](architecture.md)
+- [워크플로우 가이드](workflow.md)
+- [재해 복구](disaster_recovery.md)
+- [Agent 제약 조건](agents.md)

docs/ouroboros/00_validation_system.md

@@ -0,0 +1,56 @@
+<!--
+Doc-ID: DOC-VAL-001
+Version: 1.0.0
+Status: active
+Owner: strategy
+Updated: 2026-02-26
+-->
+
+# 문서 검증 시스템
+
+본 문서는 문서 간 허위 내용, 수치 충돌, 구현 불가능 지시를 사전에 제거하기 위한 검증 규칙이다.
+
+## 검증 목표
+
+- 단일 진실원장 기준으로 모든 지시서의 수치/규칙 정합성 보장
+- 설계 문장과 코드 작업 지시 간 추적성 보장
+- 테스트 미정의 상태에서 구현 착수 금지
+
+## 불일치 유형 정의
+
+- `RULE-DOC-001`: 정의되지 않은 요구사항 ID 사용
+- `RULE-DOC-002`: 동일 요구사항 ID에 상충되는 값(예: 슬리피지 수치) 기술
+- `RULE-DOC-003`: 시간대 미표기 또는 KST/UTC 혼용 지시
+- `RULE-DOC-004`: 주문 정책과 리스크 정책 충돌(예: 저유동 세션 시장가 허용)
+- `RULE-DOC-005`: 구현 태스크에 테스트 ID 미연결
+- `RULE-DOC-006`: 문서 라우팅 링크 깨짐
+
+## 검증 파이프라인
+
+1. 정적 검사 (자동)
+- 대상: `docs/ouroboros/*.md`
+- 검사: 메타데이터, 링크 유효성, ID 정의/참조 일치, REQ-추적성 매핑
+- 도구: `scripts/validate_ouroboros_docs.py`
+
+2. 추적성 검사 (자동 + 수동)
+- 자동: `REQ-*`가 최소 1개 `TASK-*`와 1개 `TEST-*`에 연결되었는지 확인
+- 수동: 정책 충돌 후보를 PR 체크리스트로 검토
+
+3. 도메인 무결성 검사 (수동)
+- KIS 점검시간 회피, 주문 유형 강제, Kill Switch 순서, 환율 정책이 동시에 존재하는지 점검
+- 백테스트 체결가가 보수 가정인지 점검
+
+## 변경 통제 규칙
+
+- `REQ-*` 추가/수정 시 반드시 `01_requirements_registry.md` 먼저 변경
+- `TASK-*` 수정 시 반드시 `40_acceptance_and_test_plan.md`의 대응 테스트를 동시 수정
+- 충돌 발생 시 우선순위: `requirements_registry > phase execution > code work order`
+
+적용 룰셋:
+- `RULE-DOC-001` `RULE-DOC-002` `RULE-DOC-003` `RULE-DOC-004` `RULE-DOC-005` `RULE-DOC-006`
+
+## PR 게이트
+
+- `python3 scripts/validate_ouroboros_docs.py` 성공
+- 신규/변경 `REQ-*`가 테스트 기준(`TEST-*`)과 연결됨
+- 원본 계획(v2/v3)과 모순 없음

docs/ouroboros/01_requirements_registry.md

@@ -0,0 +1,40 @@
+<!--
+Doc-ID: DOC-REQ-001
+Version: 1.0.8
+Status: active
+Owner: strategy
+Updated: 2026-03-02
+-->
+
+# 요구사항 원장 (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`: 블랙아웃 중 신호는 bounded Queue에 적재되며, 포화 시 oldest-drop 정책으로 최신 intent를 보존하고 복구 후 유효성 재검증을 거친다.
+- `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`: 구현 태스크는 반드시 테스트 태스크를 동반한다.
+- `REQ-OPS-004`: 원본 계획 문서(`v2`, `v3`)는 `docs/ouroboros/source/` 경로를 단일 기준으로 사용한다.

docs/ouroboros/10_phase_v2_execution.md

@@ -0,0 +1,63 @@
+<!--
+Doc-ID: DOC-PHASE-V2-001
+Version: 1.0.0
+Status: active
+Owner: strategy
+Updated: 2026-02-26
+-->
+
+# v2 실행 지시서 (설계 -> 코드)
+
+참조 요구사항: `REQ-V2-001` `REQ-V2-002` `REQ-V2-003` `REQ-V2-004` `REQ-V2-005` `REQ-V2-006` `REQ-V2-007` `REQ-V2-008` `REQ-OPS-001` `REQ-OPS-002` `REQ-OPS-003`
+
+## 단계 1: 도메인 모델 확정
+
+- `TASK-V2-001`: 상태머신 enum/전이 이벤트/전이 사유 스키마 설계
+- `TASK-V2-002`: `position_state` 스냅샷 구조(현재상태, peak, stops, last_reason) 정의
+- `TASK-V2-003`: 청산 판단 입력 DTO(가격, ATR, pred_prob, liquidity_signal) 정의
+
+완료 기준:
+- 상태와 전이 사유가 로그/DB에서 재현 가능
+- `REQ-V2-001`~`003`을 코드 타입 수준에서 강제
+
+## 단계 2: 청산 엔진 구현
+
+- `TASK-V2-004`: 우선순위 기반 전이 함수 구현(`evaluate_exit_first` -> `promote_state`)
+- `TASK-V2-005`: Hard Stop/BE Lock/ATR Trailing 결합 로직 구현
+- `TASK-V2-006`: 모델 확률 신호를 보조 트리거로 결합(단독 청산 금지)
+
+완료 기준:
+- 갭 상황에서 다중 조건 동시 충족 시 최상위 상태로 단번 전이
+- `REQ-V2-004` 준수
+
+## 단계 3: 라벨링/학습 데이터 파이프라인
+
+- `TASK-V2-007`: Triple Barrier 라벨러 구현(장벽 선터치 우선)
+- `TASK-V2-008`: 피처 구간/라벨 구간 분리 검증 유틸 구현
+- `TASK-V2-009`: 라벨 생성 로그(진입시각, 터치장벽, 만기장벽) 기록
+
+완료 기준:
+- look-ahead 차단 증빙 로그 확보
+- `REQ-V2-005` 충족
+
+## 단계 4: 검증 프레임워크
+
+- `TASK-V2-010`: Walk-forward split + Purge/Embargo 분할기 구현
+- `TASK-V2-011`: 베이스라인(`B0`,`B1`,`M1`) 비교 리포트 포맷 구현
+- `TASK-V2-012`: 체결 비용/슬리피지/실패 반영 백테스트 옵션 강제
+
+완료 기준:
+- `REQ-V2-006`, `REQ-V2-007` 충족
+
+## 단계 5: Kill Switch 통합
+
+- `TASK-V2-013`: Kill Switch 순차 실행 오케스트레이터 구현 (`src/core/risk_manager.py` 수정 금지)
+- `TASK-V2-014`: 주문 차단 플래그/미체결 취소/재조회 재시도 로직 구현
+- `TASK-V2-015`: 스냅샷/알림/복구 진입 절차 구현
+
+완료 기준:
+- `REQ-V2-008` 순서 일치
+
+라우팅:
+- 코드 지시 상세: [30_code_level_work_orders.md](./30_code_level_work_orders.md)
+- 테스트 상세: [40_acceptance_and_test_plan.md](./40_acceptance_and_test_plan.md)

docs/ouroboros/20_phase_v3_execution.md

@@ -0,0 +1,60 @@
+<!--
+Doc-ID: DOC-PHASE-V3-001
+Version: 1.0.0
+Status: active
+Owner: strategy
+Updated: 2026-02-26
+-->
+
+# v3 실행 지시서 (세션 확장)
+
+참조 요구사항: `REQ-V3-001` `REQ-V3-002` `REQ-V3-003` `REQ-V3-004` `REQ-V3-005` `REQ-V3-006` `REQ-V3-007` `REQ-V3-008` `REQ-OPS-001` `REQ-OPS-002` `REQ-OPS-003`
+
+## 단계 1: 세션 엔진
+
+- `TASK-V3-001`: `session_id` 분류기 구현(KR/US 확장 세션)
+- `TASK-V3-002`: 세션 전환 훅에서 리스크 파라미터 재로딩 구현
+- `TASK-V3-003`: 로그/DB 스키마에 `session_id` 필드 강제
+
+완료 기준:
+- `REQ-V3-001`, `REQ-V3-002` 충족
+
+## 단계 2: 블랙아웃/복구 제어
+
+- `TASK-V3-004`: 블랙아웃 윈도우 정책 로더 구현(설정 기반)
+- `TASK-V3-005`: 블랙아웃 중 신규 주문 차단 + 의도 큐 적재 구현
+- `TASK-V3-006`: 복구 시 동기화(잔고/미체결/체결) 후 큐 재검증 실행
+
+완료 기준:
+- `REQ-V3-003`, `REQ-V3-004` 충족
+
+## 단계 3: 주문 정책 강화
+
+- `TASK-V3-007`: 세션별 주문 타입 매트릭스 구현
+- `TASK-V3-008`: 저유동 세션 시장가 주문 하드 차단
+- `TASK-V3-009`: 재호가 간격/횟수 제한 및 주문 철회 조건 구현
+
+완료 기준:
+- `REQ-V3-005` 충족
+
+## 단계 4: 비용/체결 모델 정교화
+
+- `TASK-V3-010`: 세션별 슬리피지/비용 테이블 엔진 반영
+- `TASK-V3-011`: 불리한 체결 가정(상대 호가 방향) 체결기 구현
+- `TASK-V3-012`: 시나리오별 체결 실패/부분체결 모델 반영
+
+완료 기준:
+- `REQ-V3-006` 충족
+
+## 단계 5: 환율/오버나잇/Kill Switch 연동
+
+- `TASK-V3-013`: 전략 PnL과 FX PnL 분리 회계 구현
+- `TASK-V3-014`: USD/KRW 버퍼 규칙 위반 시 신규 진입 제한 구현
+- `TASK-V3-015`: 오버나잇 예외와 Kill Switch 우선순위 통합
+
+완료 기준:
+- `REQ-V3-007`, `REQ-V3-008` 충족
+
+라우팅:
+- 코드 지시 상세: [30_code_level_work_orders.md](./30_code_level_work_orders.md)
+- 테스트 상세: [40_acceptance_and_test_plan.md](./40_acceptance_and_test_plan.md)

docs/ouroboros/30_code_level_work_orders.md

@@ -0,0 +1,60 @@
+<!--
+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`,`TEST-CODE-001`,`TEST-CODE-002`): `src/strategy/`에 상태기계 모듈 추가
+- `TASK-CODE-002` (`REQ-V2-004`,`TEST-ACC-011`): ATR/BE/Hard Stop 결합 청산 함수 추가
+- `TASK-CODE-003` (`REQ-V2-008`,`TEST-ACC-002`): Kill Switch 오케스트레이터를 `src/core/kill_switch.py`에 추가
+- `TEST-CODE-001`: 갭 점프 시 최고상태 승격 테스트
+- `TEST-CODE-002`: EXIT 우선순위 테스트
+
+## 구현 단위 B: 라벨링/검증
+
+- `TASK-CODE-004` (`REQ-V2-005`,`TEST-CODE-003`,`TEST-ACC-012`): Triple Barrier 라벨러 모듈 추가(`src/analysis/` 또는 `src/strategy/`)
+- `TASK-CODE-005` (`REQ-V2-006`,`TEST-CODE-004`,`TEST-ACC-013`): Walk-forward + Purge/Embargo 분할 유틸 추가
+- `TASK-CODE-006` (`REQ-V2-007`,`TEST-ACC-014`): 백테스트 실행기에서 비용/슬리피지 옵션 필수화
+- `TEST-CODE-003`: 라벨 선터치 우선 테스트
+- `TEST-CODE-004`: 누수 차단 테스트
+
+## 구현 단위 C: 세션/주문 정책
+
+- `TASK-CODE-007` (`REQ-V3-001`,`REQ-V3-002`,`TEST-ACC-015`,`TEST-ACC-016`): 세션 분류/전환 훅을 `src/markets/schedule.py` 연동
+- `TASK-CODE-008` (`REQ-V3-003`,`REQ-V3-004`,`TEST-CODE-005`,`TEST-ACC-017`): 블랙아웃 큐 처리기를 `src/broker/`에 추가
+- `TASK-CODE-009` (`REQ-V3-005`,`TEST-CODE-006`,`TEST-ACC-004`): 세션별 주문 타입 검증기 추가
+- `TEST-CODE-005`: 블랙아웃 신규주문 차단 테스트
+- `TEST-CODE-006`: 저유동 세션 시장가 거부 테스트
+
+## 구현 단위 D: 체결/환율/오버나잇
+
+- `TASK-CODE-010` (`REQ-V3-006`,`TEST-CODE-007`,`TEST-ACC-005`): 불리한 체결가 모델을 백테스트 체결기로 구현
+- `TASK-CODE-011` (`REQ-V3-007`,`TEST-CODE-008`,`TEST-ACC-006`): FX PnL 분리 회계 테이블/컬럼 추가
+- `TASK-CODE-012` (`REQ-V3-008`,`TEST-ACC-018`): 오버나잇 예외와 Kill Switch 충돌 해소 로직 구현
+- `TEST-CODE-007`: 불리한 체결가 모델 테스트
+- `TEST-CODE-008`: FX 버퍼 위반 시 신규진입 제한 테스트
+
+## 구현 단위 E: 운영/문서 거버넌스
+
+- `TASK-OPS-001` (`REQ-OPS-001`,`TEST-ACC-007`): 시간 필드/로그 스키마의 타임존(KST/UTC) 표기 강제 규칙 구현
+- `TASK-OPS-002` (`REQ-OPS-002`,`TEST-ACC-008`): 정책 수치 변경 시 `01_requirements_registry.md` 선수정 CI 체크 추가
+- `TASK-OPS-003` (`REQ-OPS-003`,`TEST-ACC-009`): `TASK-*` 없는 `REQ-*` 또는 `TEST-*` 없는 `REQ-*`를 차단하는 문서 검증 게이트 유지
+- `TASK-OPS-004` (`REQ-OPS-004`,`TEST-ACC-019`): v2/v3 원본 계획 문서 위치를 `docs/ouroboros/source/`로 표준화하고 링크 일관성 검증
+
+## 커밋 규칙
+
+- 커밋 메시지에 `TASK-*` 포함
+- PR 본문에 `REQ-*`, `TEST-*` 매핑 표 포함
+- 변경 파일마다 최소 1개 테스트 연결

docs/ouroboros/40_acceptance_and_test_plan.md

@@ -0,0 +1,64 @@
+<!--
+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-*` 매핑 없이 존재하면 검증 실패한다.
+- `TEST-ACC-019` (`REQ-OPS-004`): v2/v3 원본 계획 문서 링크는 `docs/ouroboros/source/` 경로 기준으로만 통과한다.
+
+## 테스트 계층
+
+1. 단위 테스트
+- 상태 전이, 주문타입 검증, 큐 복구 로직, 체결가 모델
+
+2. 통합 테스트
+- 세션 전환 -> 주문 정책 -> 리스크 엔진 연동
+- 블랙아웃 시작/해제 이벤트 연동
+
+3. 회귀 테스트
+- 기존 `tests/` 스위트 전량 실행
+- 신규 기능 플래그 ON/OFF 비교
+
+4. 구동/모니터링 검증 (필수)
+- 개발 완료 후 시스템을 실제 구동해 핵심 경로를 관찰
+- 필수 관찰 항목: 주문 차단 정책, Kill Switch 동작, 경보/예외 로그, 세션 전환 로그
+- Runtime Verifier 코멘트로 증적(실행 명령/요약 로그) 첨부
+
+## 실행 명령
+
+```bash
+pytest -q
+python3 scripts/validate_ouroboros_docs.py
+```
+
+## 실패 처리 규칙
+
+- 문서 검증 실패 시 구현 PR 병합 금지
+- `REQ-*` 변경 후 테스트 매핑 누락 시 병합 금지
+- 회귀 실패 시 원인 모듈 분리 후 재검증
+- 구동/모니터링 증적 누락 시 검증 승인 금지

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`) 선수정 후 진행한다.

docs/ouroboros/50_tpm_control_protocol.md

@@ -0,0 +1,223 @@
+<!--
+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 Agent 아이디에이션 책임:
+- 진행 중 신규 구현 아이디어를 별도 문서에 누적 기록한다.
+- 기록 위치: [70_main_agent_ideation.md](./70_main_agent_ideation.md)
+- 각 항목은 `IDEA-*` 식별자, 배경, 기대효과, 리스크, 후속 티켓 후보를 포함해야 한다.
+
+## 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 최종 승인 필수
+
+Main/Verifier 사고 재발 방지 규칙:
+- Main Agent는 검증 위임 시 `Directive Contract`를 충족하지 않으면 검증 착수 금지
+- Verifier Agent는 지시 누락/모호성 발견 시 즉시 `BLOCKED`를 선언하고 보완 요청
+- Verifier Agent는 `미관측(NOT_OBSERVED)` 항목을 PASS로 보고할 수 없다
+- Runtime 검증에서 요구 세션 증적이 없으면 "정상"이 아니라 `미검증 이상`으로 이슈화한다
+
+## 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가 테스트 증적(로그/리포트/실행 커맨드) 첨부
+- Verifier가 `Coverage Matrix`(`REQ/TASK/TEST` x `PASS/FAIL/NOT_OBSERVED`) 첨부
+- `NOT_OBSERVED` 항목 수가 0인지 확인(0이 아니면 Gate 실패)
+- Runtime Verifier가 스테이징/실운영 모니터링 계획 승인
+- 정적 Verifier 승인 + Runtime Verifier 승인 2개 모두 확인
+- 산출물: 수용 승인 레코드
+
+### 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`) 동시 갱신 필수
+
+TPM 티켓 운영 규칙:
+- TPM은 합의된 변경을 이슈로 등록하고 우선순위(`P0/P1/P2`)를 지정한다.
+- PR 본문에는 TPM이 지정한 우선순위와 범위가 그대로 반영되어야 한다.
+- 우선순위 변경은 TPM 제안 + Main Agent 승인으로만 가능하다.
+- PM/TPM/Dev/Reviewer/Verifier/Runtime Verifier는 주요 의사결정 시점마다 PR 코멘트를 남겨 결정 근거를 추적 가능 상태로 유지한다.
+- PM/TPM/Dev/Reviewer/Verifier/Runtime Verifier는 이슈/PR/코멘트 조작 전에 `docs/commands.md`와 `docs/workflow.md`의 Gitea 트러블슈팅 섹션을 선참조해야 한다.
+- 저장소 협업에서 GitHub CLI(`gh`) 사용은 금지하며, Gitea 작업은 `tea`(필요 시 문서화된 API fallback)만 허용한다.
+- 재발 방지/운영 규칙 변경이 합의되면, 기능 구현 이전에 process 티켓을 먼저 생성/머지해야 한다.
+- process 티켓 미반영 상태에서 구현 티켓 진행 시 TPM이 즉시 `BLOCKED` 처리한다.
+
+티켓 성숙도 단계 (Mandatory):
+- `Implemented`: 코드/문서 변경 완료
+- `Integrated`: 호출 경로/파이프라인 연결 확인
+- `Observed`: 런타임/실행 증적 확보
+- `Accepted`: Verifier + Runtime Verifier 승인 완료
+- 단계는 순차 전진만 허용되며, 단계 점프는 허용되지 않는다.
+
+브랜치 운영 규칙:
+- TPM은 각 티켓에 대해 `ticket temp branch -> program feature branch` PR 경로를 지정한다.
+- 티켓 머지 대상은 항상 program feature branch이며, `main`은 최종 통합 단계에서만 사용한다.
+
+## Runtime Verification Protocol
+
+- Runtime Verifier는 테스트 통과 이후 실제 동작(스테이징/실운영)을 모니터링한다.
+- 이상 동작/현상 발견 시 즉시 이슈 발행:
+  - 제목 규칙: `[RUNTIME-VERIFY][SCN-*] ...`
+  - 본문 필수: 재현조건, 관측 로그, 영향 범위, 임시 완화책, 관련 `REQ/TASK/TEST`
+- 이슈 클로즈 규칙:
+  - Dev 수정 완료 + Verifier 재검증 통과 + Runtime Verifier 재관측 정상
+  - 최종 클로즈 승인자는 Main Agent
+- 개발 완료 필수 절차:
+  - 시스템 실제 구동(스테이징/로컬 실운영 모드) 실행
+  - 모니터링 체크리스트(핵심 경보/주문 경로/예외 로그) 수행
+  - 결과를 티켓/PR 코멘트에 증적으로 첨부하지 않으면 완료로 간주하지 않음
+  - 세션별 필수 관측 포인트(`NXT`, `US_PRE`, `US_DAY`, `US_AFTER` 등) 중 미관측 항목은 `NOT_OBSERVED`로 기록
+  - `NOT_OBSERVED` 존재 시 승인 금지 + Runtime 이슈 발행
+
+## Server Reflection Rule
+
+- `ticket temp branch -> program feature branch` 머지는 검증 승인 후 자동/수동 진행 가능하다.
+- `program feature branch -> main` 머지는 사용자 명시 승인 시에만 허용한다.
+- Main 병합 시 Main Agent가 승인 근거를 PR 코멘트에 기록한다.
+
+## 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 체크리스트 미충족 시 릴리즈 보류 권한을 행사해야 한다.

docs/ouroboros/60_repo_enforcement_checklist.md

@@ -0,0 +1,118 @@
+<!--
+Doc-ID: DOC-OPS-002
+Version: 1.0.0
+Status: active
+Owner: tpm
+Updated: 2026-02-27
+-->
+
+# 저장소 강제 설정 체크리스트
+
+목표: "엄격 검증 운영"을 문서가 아니라 저장소 설정으로 강제한다.
+
+## 1) main 브랜치 보호 (필수)
+
+적용 항목:
+- direct push 금지
+- force push 금지
+- branch 삭제 금지
+- merge는 PR 경로만 허용
+
+검증:
+- `main`에 대해 직접 `git push origin main` 시 거부되는지 확인
+
+## 2) 필수 상태 체크 (필수)
+
+필수 CI 항목:
+
+| 참조 기준 | 이름 | 설명 |
+|-----------|------|------|
+| **job 단위** (브랜치 보호 설정 시 사용) | `test` | 전체 CI job (문서 검증 + 테스트 포함) |
+| **step 단위** (로그 확인 시 참조) | `validate_ouroboros_docs` | `python3 scripts/validate_ouroboros_docs.py` 실행 step |
+| **step 단위** | `run_tests` | `pytest -q` 실행 step |
+
+> **주의**: Gitea 브랜치 보호의 Required Status Checks는 **job 이름** 기준으로 설정한다 (`test`). step 이름은 UI 로그 탐색용이며 보호 규칙에 직접 입력하지 않는다.
+
+설정 기준:
+- `test` job이 `success` 아니면 머지 금지
+- 체크 스킵/중립 상태 허용 금지
+
+## 3) 필수 리뷰어 규칙 (권장 -> 필수)
+
+역할 기반 승인:
+- Verifier 1명 승인 필수
+- TPM 또는 PM 1명 승인 필수
+- Runtime Verifier 관련 변경(PR 본문에 runtime 영향 있음) 시 Runtime Verifier 승인 필수
+
+설정 기준:
+- 최소 승인 수: 2
+- 작성자 self-approval 불가
+- 새 커밋 푸시 시 기존 승인 재검토 요구
+
+## 4) 워크플로우 게이트
+
+병합 전 체크리스트:
+- 이슈 연결(`Closes #N`) 존재
+- PR 본문에 `REQ-*`, `TASK-*`, `TEST-*` 매핑 표 존재
+- Main -> Verifier Directive Contract(범위/방법/합격/실패/미관측/증적 형식) 기재
+- process-change-first 대상이면 process 티켓 PR이 선머지됨
+- `src/core/risk_manager.py` 변경 없음
+- 주요 의사결정 체크포인트(DCP-01~04) 중 해당 단계 Main Agent 확인 기록 존재
+- 주요 의사결정(리뷰 지적/수정 합의/검증 승인)에 대한 에이전트 PR 코멘트 존재
+- 티켓 PR의 base가 `main`이 아닌 program feature branch인지 확인
+
+자동 점검:
+- 문서 검증 스크립트 통과
+- 테스트 통과
+- `python3 scripts/session_handover_check.py --strict` 통과
+- 개발 완료 시 시스템 구동/모니터링 증적 코멘트 존재
+- 이슈/PR 조작 전에 `docs/commands.md` 및 `docs/workflow.md` 트러블슈팅 확인 코멘트 존재
+- `gh` CLI 미사용, `tea` 사용 증적 존재
+- Verifier `Coverage Matrix` 첨부(PASS/FAIL/NOT_OBSERVED)
+- `NOT_OBSERVED` 항목 0 확인(0이 아니면 머지 금지)
+- 티켓 단계 기록(`Implemented` -> `Integrated` -> `Observed` -> `Accepted`) 존재
+- 정적 Verifier 승인 + Runtime Verifier 승인 2개 확인
+
+## 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` 문서를 동시 갱신해야 유효
+
+## 9) 서버 반영 규칙
+
+- 티켓 PR(`feature/issue-* -> feature/{stream}`)은 검증 승인 후 머지 가능하다.
+- 최종 통합 PR(`feature/{stream} -> main`)은 사용자 명시 승인 전 `tea pulls merge` 실행 금지.
+- Main 병합 시 승인 근거 코멘트 필수.
+
+## 10) 최종 main 병합 조건
+
+- 모든 티켓이 program feature branch로 병합 완료
+- Runtime Verifier의 구동/모니터링 검증 완료
+- 사용자 최종 승인 코멘트 확인 후에만 `feature -> main` PR 머지 허용

docs/ouroboros/70_main_agent_ideation.md

@@ -0,0 +1,48 @@
+<!--
+Doc-ID: DOC-IDEA-001
+Version: 1.0.0
+Status: active
+Owner: main-agent
+Updated: 2026-02-26
+-->
+
+# 메인 에이전트 아이디에이션 백로그
+
+목적:
+- 구현 진행 중 떠오른 신규 구현 아이디어를 계획 반영 전 임시 저장한다.
+- 본 문서는 사용자 검토 후 다음 계획 포함 여부를 결정하기 위한 검토 큐다.
+
+운영 규칙:
+- 각 아이디어는 `IDEA-*` 식별자를 사용한다.
+- 필수 필드: 배경, 기대효과, 리스크, 후속 티켓 후보.
+- 상태는 `proposed`, `under-review`, `accepted`, `rejected` 중 하나를 사용한다.
+
+## 아이디어 목록
+
+- `IDEA-001` (status: proposed)
+  - 제목: Kill-Switch 전역 상태를 프로세스 단일 전역에서 시장/세션 단위 상태로 분리
+  - 배경: 현재는 전역 block 플래그 기반이라 시장별 분리 제어가 제한될 수 있음
+  - 기대효과: KR/US 병행 운용 시 한 시장 장애가 다른 시장 주문을 불필요하게 막는 리스크 축소
+  - 리스크: 상태 동기화 복잡도 증가, 테스트 케이스 확장 필요
+  - 후속 티켓 후보: `TKT-P1-KS-SCOPE-SPLIT`
+
+- `IDEA-002` (status: proposed)
+  - 제목: Exit Engine 입력 계약(ATR/peak/model_prob/liquidity) 표준 DTO를 데이터 파이프라인에 고정
+  - 배경: 현재 ATR/모델확률 일부가 fallback 기반이라 운영 일관성이 약함
+  - 기대효과: 백테스트-실거래 입력 동형성 강화, 회귀 분석 용이
+  - 리스크: 기존 스캐너/시나리오 엔진 연동 작업량 증가
+  - 후속 티켓 후보: `TKT-P1-EXIT-CONTRACT`
+
+- `IDEA-003` (status: proposed)
+  - 제목: Runtime Verifier 자동 이슈 생성기(로그 패턴 -> 이슈 템플릿 자동화)
+  - 배경: 런타임 이상 리포트가 수동 작성 중심이라 누락 가능성 존재
+  - 기대효과: 이상 탐지 후 이슈 등록 리드타임 단축, 증적 표준화
+  - 리스크: 오탐 이슈 폭증 가능성, 필터링 룰 필요
+  - 후속 티켓 후보: `TKT-P1-RUNTIME-AUTO-ISSUE`
+
+- `IDEA-004` (status: proposed)
+  - 제목: PR 코멘트 워크플로우 자동 점검(리뷰어->개발논의->검증승인 누락 차단)
+  - 배경: 현재 절차는 강력하지만 수행 확인이 수동
+  - 기대효과: 절차 누락 방지, 감사 추적 자동화
+  - 리스크: CLI/API 연동 유지보수 비용
+  - 후속 티켓 후보: `TKT-P0-WORKFLOW-GUARD`

docs/ouroboros/80_implementation_audit.md

@@ -0,0 +1,410 @@
+<!--
+Doc-ID: DOC-AUDIT-001
+Version: 1.2.0
+Status: active
+Owner: strategy
+Updated: 2026-03-02
+-->
+
+# v2/v3 구현 감사 및 수익률 분석 보고서
+
+작성일: 2026-02-28
+최종 업데이트: 2026-03-02 (#373 상태표 정합화 반영)
+대상 기간: 2026-02-25 ~ 2026-02-28 (실거래)
+분석 브랜치: `feature/v3-session-policy-stream`
+
+---
+
+## 1. 계획 대비 구현 감사
+
+### 1.1 완료 판정 기준 (Definition of Done)
+
+아래 3가지를 모두 만족할 때만 `✅ 완료`로 표기한다.
+
+1. 코드 경로 존재: 요구사항을 수행하는 실행 경로가 코드에 존재한다.
+2. 효과 검증 통과: 요구사항 효과를 검증하는 테스트/런타임 증적이 존재한다.
+3. 추적성 일치: 요구사항 상태와 열린 갭 이슈가 모순되지 않는다.
+
+### 1.2 v2 구현 상태: 부분 완료 (핵심 갭 잔존)
+
+| REQ-ID | 요구사항 | 구현 파일 | 상태 |
+|--------|----------|-----------|------|
+| REQ-V2-001 | 4-상태 매도 상태기계 (HOLDING→BE_LOCK→ARMED→EXITED) | `src/strategy/position_state_machine.py` | ✅ 완료 |
+| REQ-V2-002 | 즉시 최상위 상태 승격 (갭 대응) | `position_state_machine.py:51-70` | ✅ 완료 |
+| REQ-V2-003 | EXITED 우선 평가 | `position_state_machine.py:38-48` | ✅ 완료 |
+| REQ-V2-004 | 4중 청산 로직 (Hard/BE/ATR Trailing/Model) | `src/strategy/exit_rules.py` | ⚠️ 부분 (`#369`) |
+| REQ-V2-005 | Triple Barrier 라벨링 | `src/analysis/triple_barrier.py` | ✅ 완료 |
+| REQ-V2-006 | Walk-Forward + Purge/Embargo 검증 | `src/analysis/walk_forward_split.py` | ✅ 완료 |
+| REQ-V2-007 | 비용/슬리피지/체결실패 모델 필수 | `src/analysis/backtest_cost_guard.py`, `src/analysis/backtest_pipeline.py` | ✅ 완료 |
+| REQ-V2-008 | Kill Switch 실행 순서 (Block→Cancel→Refresh→Reduce→Snapshot) | `src/core/kill_switch.py` | ⚠️ 부분 (`#377`) |
+
+### 1.3 v3 구현 상태: 부분 완료 (2026-03-02 기준)
+
+| REQ-ID | 요구사항 | 상태 | 비고 |
+|--------|----------|------|------|
+| REQ-V3-001 | 모든 신호/주문/로그에 session_id 포함 | ⚠️ 부분 | 큐 intent에 `session_id` 누락 (`#375`) |
+| REQ-V3-002 | 세션 전환 훅 + 리스크 파라미터 재로딩 | ✅ 완료 | 세션 경계 E2E 회귀(override 적용/해제 + 재로딩 실패 폴백) 보강 (`#376`) |
+| REQ-V3-003 | 블랙아웃 윈도우 정책 | ✅ 완료 | `src/core/blackout_manager.py` |
+| REQ-V3-004 | 블랙아웃 큐 + 복구 시 재검증 | ⚠️ 부분 | 큐 포화는 oldest-drop 정책으로 정합화 (`#371`), 재검증 강화는 `#328` 추적 |
+| REQ-V3-005 | 저유동 세션 시장가 금지 | ✅ 완료 | `src/core/order_policy.py` |
+| REQ-V3-006 | 보수적 백테스트 체결 (불리 방향) | ✅ 완료 | `src/analysis/backtest_execution_model.py` |
+| REQ-V3-007 | FX 손익 분리 (전략 PnL vs 환율 PnL) | ⚠️ 부분 | 런타임 분리 계산/전달 적용 (`#370`), buy-side `fx_rate` 미관측 시 `fx_pnl=0` fallback |
+| REQ-V3-008 | 오버나잇 예외 vs Kill Switch 우선순위 | ✅ 완료 | `src/main.py` — `_should_force_exit_for_overnight()`, `_apply_staged_exit_override_for_hold()` |
+
+### 1.4 운영 거버넌스: 부분 완료 (2026-03-02 재평가)
+
+| REQ-ID | 요구사항 | 상태 | 비고 |
+|--------|----------|------|------|
+| REQ-OPS-001 | 타임존 명시 (KST/UTC) | ⚠️ 부분 | 문서 토큰 fail-fast 추가, 필드 수준 검증은 `#372` 잔여 |
+| REQ-OPS-002 | 정책 변경 시 레지스트리 업데이트 강제 | ⚠️ 부분 | 파일 단위 강제는 구현, 정책 수치 단위 정밀 검증은 `#372` 잔여 |
+| REQ-OPS-003 | TASK-REQ 매핑 강제 | ⚠️ 부분 | TASK-REQ/TASK-TEST 강제는 구현, 우회 케이스 추가 점검은 `#372` 잔여 |
+| REQ-OPS-004 | source 경로 표준화 검증 | ✅ 완료 | `scripts/validate_ouroboros_docs.py`의 canonical source path 검증 |
+
+---
+
+## 2. 구현 갭 상세
+
+> **2026-03-02 업데이트**: 기존 해소 표기를 재검증했고, 열려 있는 갭 이슈 기준으로 상태를 재분류함.
+
+### GAP-1: DecisionLogger에 session_id 미포함 → ✅ 해소 (#326)
+
+- **위치**: `src/logging/decision_logger.py`
+- ~~문제: `log_decision()` 함수에 `session_id` 파라미터가 없음~~
+- **해소**: #326 머지 — `log_decision()` 파라미터에 `session_id` 추가, DB 기록 포함
+- **요구사항**: REQ-V3-001
+
+### GAP-2: src/main.py 거래 로그에 session_id 미전달 → ✅ 해소 (#326)
+
+- **위치**: `src/main.py`
+- ~~문제: `log_trade()` 호출 시 `session_id` 파라미터를 전달하지 않음~~
+- **해소**: #326 머지 — `log_trade()` 호출 시 런타임 `session_id` 명시적 전달
+- **요구사항**: REQ-V3-001
+
+### GAP-3: 세션 전환 시 리스크 파라미터 재로딩 없음 → ✅ 해소 (#327, #376)
+
+- **위치**: `src/main.py`, `src/config.py`
+- **해소 내용**: #327 머지 — `SESSION_RISK_PROFILES_JSON` 기반 세션별 파라미터 재로딩 메커니즘 구현
+  - `SESSION_RISK_RELOAD_ENABLED=true` 시 세션 경계에서 파라미터 재로딩
+  - 재로딩 실패 시 기존 파라미터 유지 (안전 폴백)
+- **해소**: 세션 경계 E2E 회귀 테스트를 추가해 override 적용/해제, 재로딩 실패 시 폴백 유지를 검증함 (`#376`)
+- **요구사항**: REQ-V3-002
+
+### GAP-4: 블랙아웃 복구 DB 기록 + 재검증 → ⚠️ 부분 해소 (#324, #328, #371)
+
+- **위치**: `src/core/blackout_manager.py`, `src/main.py`
+- **현 상태**:
+  - #324 추적 범위(DB 기록)는 구현 경로가 존재
+  - #328 범위(가격/세션 재검증 강화)는 추적 이슈 오픈 상태
+  - #371: 큐 포화 정책을 oldest-drop으로 명시/구현해 최신 intent 유실 경로를 제거
+- **요구사항**: REQ-V3-004
+
+### GAP-5: 시간장벽이 봉 개수 고정 → ✅ 해소 (#329)
+
+- **위치**: `src/analysis/triple_barrier.py`
+- ~~문제: `max_holding_bars` (고정 봉 수) 사용~~
+- **해소**: #329 머지 — `max_holding_minutes` (캘린더 분) 기반 시간장벽 전환
+  - 봉 주기 무관하게 일정 시간 경과 시 장벽 도달
+  - `max_holding_bars` deprecated 경고 유지 (하위 호환)
+- **요구사항**: REQ-V2-005 / v3 확장
+
+### GAP-6 (신규): FX PnL 분리 부분 해소 (MEDIUM)
+
+- **위치**: `src/db.py` (`fx_pnl`, `strategy_pnl` 컬럼 존재)
+- **현 상태**: 런타임 SELL 경로에서 `strategy_pnl`/`fx_pnl` 분리 계산 및 전달을 적용함 (`#370`).
+- **운영 메모**: `trading_cycle`은 scanner 기반 `selection_context`에 `fx_rate`를 추가하고, `run_daily_session`은 scanner 컨텍스트 없이 `fx_rate` 스냅샷만 기록한다.
+- **잔여**: 과거 BUY 레코드에 `fx_rate`가 없으면 해외 구간도 `fx_pnl=0` fallback으로 기록됨.
+- **영향**: USD 거래에서 환율 손익과 전략 손익이 분리되지 않아 성과 분석 부정확
+- **요구사항**: REQ-V3-007
+
+---
+
+## 3. 실거래 수익률 분석
+
+### 3.1 종합 성적
+
+| 지표 | 값 |
+|------|-----|
+| 총 실현 손익 | **-52,481** (KRW + USD 혼합, 통화 분리 집계는 3.4 참조) |
+| 총 거래 기록 | 19,130건 (BUY 121, SELL 46, HOLD 18,963) |
+| 집계 기준 | UTC `2026-02-25T00:00:00` ~ `2026-02-28T00:00:00`, SELL 45건 (기간 외 1건 제외) |
+| 승률 | **39.1%** (18승 / 46매도, 0손익 포함 기준) |
+| 평균 수익 거래 | +6,107 |
+| 평균 손실 거래 | -7,382 |
+| 최대 수익 거래 | +46,350 KRW (452260 KR) |
+| 최대 손실 거래 | -26,400 KRW (000370 KR) |
+| 운영 모드 | LIVE (실계좌) |
+
+### 3.2 일별 손익
+
+| 날짜 | 매도 수 | 승 | 패 | 일간 손익 |
+|------|---------|----|----|-----------|
+| 02-25 | 9 | 8 | 1 | +63.21 (USD, 미세 수익) |
+| 02-26 | 14 | 5 | 5 | **-32,083.40** (KR 대량 손실) |
+| 02-27 | 22 | 5 | 16 | **-20,461.11** (고빈도 매매, 대부분 손실) |
+
+> 정확한 재현: `scripts/audit_queries.sql` 참조.
+
+### 3.3 시장별 손익
+
+| 시장 | 매도 수 | 승률 | 총 손익 |
+|------|---------|------|---------|
+| **KR** | 17 | 38.5% (0손익 제외, 5/13) | **-56,735 KRW** |
+| US_AMEX | 12 | 75% | +4,476 USD |
+| US_NASDAQ | 4 | 0% | -177 USD |
+| US_NYSE | 13 | 30.8% | -45 USD |
+
+**KR 시장이 손실의 주 원인.** US는 AMEX 제외 시 대체로 손실 또는 보합.
+
+### 3.4 재계산 주석 반영 (통화 분리)
+
+> 산식 주석: 기존 표의 `총 실현 손익 -52,481`은 KRW/USD를 단순 합산한 값으로, 회계적으로 해석 불가.
+> 아래는 같은 기간(2026-02-25~2026-02-27, SELL 45건)을 통화별로 분리한 결과.
+
+| 통화 | 매도 수 | 승/패 | 실현 손익 |
+|------|---------|-------|-----------|
+| KRW | 17 | 5승 / 8패 (4건 0손익) | **-56,735 KRW** |
+| USD | 28 | 13승 / 14패 (1건 0손익) | **+4,253.70 USD** |
+
+### 3.5 재계산 주석 반영 (기존 보유 청산 성과 분리)
+
+> 분리 기준: 각 SELL의 직전 BUY가 `rationale LIKE '[startup-sync]%'` 인 경우를
+> `기존 보유(시작 시점 동기화 포지션) 청산`으로 분류.
+
+| 구분 | 통화 | 매도 수 | 손익 |
+|------|------|---------|------|
+| 기존 보유 청산분 | KRW | 10 | **+12,230 KRW** |
+| 기존 보유 청산분 | USD | 2 | **+21.03 USD** |
+| 신규/전략 진입분만 | KRW | 7 | **-68,965 KRW** |
+| 신규/전략 진입분만 | USD | 26 | **+4,232.67 USD** |
+
+추가로, 요청 취지(“기존 보유 수익 종목 정리 수익 제외”)에 맞춰 **기존 보유 청산 중 수익(+PnL)만 제외**하면:
+
+- KRW: `-56,735` → **-113,885 KRW** (기존 보유 수익 +57,150 KRW 제거)
+- USD: `+4,253.70` → **+4,232.67 USD** (기존 보유 수익 +21.03 USD 제거)
+
+즉, 기존 성과표는 기보유 청산 이익(특히 KR 452260 +46,350 KRW)을 전략 성과에 포함해
+전략 자체 손익을 과대평가한 상태다.
+
+### 3.6 데이터 무결성 점검 (모의투자 혼합 여부 + USD 과대수익 원인)
+
+- `mode` 점검 결과: `live` 19,130건, `paper` 0건  
+  → **모의투자 혼합은 확인되지 않음**.
+- 다만 USD 손익에는 **체결 매칭 이상치 1건**이 존재:
+  - `CRCA` SELL(15주, $35.14, +4,612.15 USD) vs 직전 BUY(146주, $3.5499)
+  - BUY/SELL 수량 불일치(146→15) 상태에서 PnL이 계산되어, 역분할/동기화 이슈 가능성이 큼.
+
+보수적 재집계(2026-02-25~2026-02-27, USD SELL 28건):
+
+| 집계 기준 | USD 손익 | 환산 KRW (참고) | KRW 합산 참고값 |
+|-----------|----------|-----------------|-----------------|
+| 원집계 | **+4,253.70 USD** | +6,167,865 | -56,735 + 6,167,865 = **+6,111,130** |
+| 기존보유(startup-sync) 제외 | **+4,232.67 USD** | +6,137,372 | -68,965 + 6,137,372 = **+6,068,407** |
+| 수량 일치 체결만 포함 | **-358.45 USD** | -519,753 | -56,735 + (-519,753) = **-576,488** |
+| 기존보유 제외 + 수량 일치 체결만 포함 | **-379.48 USD** | -550,246 | -68,965 + (-550,246) = **-619,211** |
+
+> 가정 환율: **1 USD = 1,450 KRW** (2026-02-28 기준 참고 환율).
+> 환산 KRW 및 합산값은 비교용 보조지표이며, 회계/정산 기준값과는 분리해 해석해야 한다.
+
+결론적으로 USD 구간의 플러스 성과는 실질적으로 `CRCA` 이상치 1건 영향이 지배적이며,
+해당 거래를 무결성 필터로 제외하면 USD 성과는 손실 구간으로 전환된다.
+
+### 3.7 데이터 품질 이슈 요약
+
+- **startup-sync 중복**: BUY 76건 반복 동기화, price=0 38건 → PnL 매칭 왜곡 가능. 분리 집계는 3.5 참조.
+- **티커-거래소 드리프트**: 동일 티커가 다중 거래소에 혼재 기록 → ROOT-7 참조.
+- **FX PnL 미활성**: 스키마 존재, 운영 데이터 전부 0 → REQ-V3-007 참조.
+
+### 3.8 표준 집계 SQL (재현용)
+
+성과표 재현을 위한 기준 쿼리는 [`scripts/audit_queries.sql`](../../scripts/audit_queries.sql)에 분리되어 있다.
+
+- **Base**: 기간 + LIVE + SELL + 직전 BUY 메타 매칭
+- **Q1**: 통화 분리 손익 (KRW/USD 혼합 금지)
+- **Q2**: 기존 보유(startup-sync) 제외 성과
+- **Q3**: 수량 일치 체결만 포함 (무결성 필터)
+- **Q4**: 이상치 목록 (수량 불일치)
+
+---
+
+## 4. 수익률 저조 근본 원인 분석
+
+### ROOT-1: hard_stop_pct 기본값(-2%)이 KR 소형주 변동성 대비 과소
+
+- **현재 설정**: `stop_loss_threshold = -2.0` (`src/main.py:511`), staged exit의 `hard_stop_pct`로 전달
+- **v2 계획**: ATR 기반 동적 trailing stop (ExitPrice = PeakPrice - k × ATR)
+- **실제 동작**: staged exit는 호출되나, `atr_value`/`pred_down_prob` 등 피처가 0.0으로 공급되어 hard_stop 편향 발동 (ROOT-5 참조)
+- **증거**:
+  - 000370: 매수 8,040 → 24분 후 -2.74% 손절
+  - 033340: 매수 2,080 → 18분 후 -3.13% 손절
+  - 229000: -3.7%, -3.25%, -3.2% 반복 손절
+
+### ROOT-2: 동일 종목 반복 매매 (재진입 쿨다운 미구현)
+
+- **문제**: 손절 후 동일 종목 즉시 재매수 → 고가 재진입 → 재손절 반복
+- **최악 사례**: 종목 229000
+  | 매수가 | 매도가 | 손익 | 보유 시간 |
+  |--------|--------|------|-----------|
+  | 5,670 | 5,460 | -24,780 | 0.5h |
+  | 5,540 | 5,360 | -21,780 | 0.7h |
+  | 5,310 | 5,580 | +34,020 (승) | 0.8h |
+  | 5,620 | 5,440 | -21,420 | 1.5h |
+- **순손실**: 하루 한 종목에서 **-33,960 KRW**
+
+### ROOT-3: 미국 페니스탁/마이크로캡 무분별 진입
+
+- **문제**: $2 이하 종목에 confidence 85~90으로 진입, 오버나잇 대폭락
+- **사례**:
+  | 종목 | 손실률 | 보유시간 |
+  |------|--------|----------|
+  | ALBT | -27.7% | ~23h |
+  | SMJF | -15.9% | ~23h |
+  | KAPA | -18.2% | ~23h |
+  | CURX | -10.6% | ~23h |
+  | CELT | -8.3% | ~23h |
+
+### ROOT-4: 진화 전략 코드 생성기 문법 오류
+
+- **위치**: `src/strategies/v20260227_*_evolved.py`
+- **문제**: 중첩 `def evaluate` 정의 (들여쓰기 오류)
+- **영향**: 런타임 실패 → 기본 전략으로 폴백 → 진화 시스템 사실상 무효
+
+### ROOT-5: v2 청산 로직이 부분 통합되었으나 실효성 부족 → ⚠️ 부분 해소 (#325)
+
+**초기 진단 (2026-02-28 감사 기준):**
+- `hard_stop_pct`에 고정 `-2.0`이 기본값으로 들어가 v2 계획의 ATR 적응형 의도와 괴리
+- `be_arm_pct`/`arm_pct`가 playbook의 `take_profit_pct`에서 기계적 파생(`* 0.4`)되어 v2 계획의 독립 파라미터 튜닝 불가
+- `atr_value`, `pred_down_prob` 등 런타임 피처가 0.0으로 공급되어 사실상 hard stop만 발동
+
+**현재 상태 (#325 머지 후):**
+- `STAGED_EXIT_BE_ARM_PCT`, `STAGED_EXIT_ARM_PCT` 환경변수로 독립 파라미터 설정 가능
+- `_inject_staged_exit_features()`: KR 시장 ATR 실시간 계산 주입, RSI 기반 `pred_down_prob` 공급
+- KR ATR dynamic hard stop (#318)으로 `-2.0` 고정값 문제 해소
+
+**잔여 리스크:**
+- KR 외 시장(US 등)에서 `atr_value` 공급 경로 불완전 — hard stop 편향 잔존 가능
+- `pred_down_prob`가 RSI 프록시 수준 — 추후 실제 ML 모델 대체 권장
+
+### ROOT-6: SELL 손익 계산이 부분청산/수량 불일치에 취약 (CRITICAL) → ✅ 해소 (#322)
+
+> **현재 상태**: #322 머지로 해소됨. 아래는 원인 발견 시점(2026-02-28) 진단 기록.
+
+- **위치**: `src/main.py:1658-1663`, `src/main.py:2755-2760`
+- **문제**: PnL 계산이 실제 매도 수량(`sell_qty`)이 아닌 직전 BUY의 `buy_qty`를 사용
+  - `trade_pnl = (trade_price - buy_price) * buy_qty`
+- **영향**: 부분청산, 역분할/액분할, startup-sync 후 수량 드리프트 시 손익 과대/과소 계상
+- **실증**: CRCA 이상치(BUY 146주 → SELL 15주에서 PnL +4,612 USD) 가 이 버그와 정합
+
+### ROOT-7: BUY 매칭 키에 exchange_code 미포함 — 잠재 오매칭 리스크 (HIGH) → ✅ 해소 (#323)
+
+> **현재 상태**: #323 머지로 해소됨. 아래는 원인 발견 시점(2026-02-28) 진단 기록.
+
+- **위치**: `src/db.py:292-313`
+- **문제**: `get_latest_buy_trade()`가 `(stock_code, market)`만으로 매칭, `exchange_code` 미사용
+- **성격**: 현재 즉시 발생하는 확정 버그가 아닌, 동일 티커가 다중 거래소에 혼재 기록될 때 증폭되는 구조 리스크
+- **영향**: 데이터 드리프트 조건(예: CCUP/CRCA 등 다중 exchange 기록)에서 오매칭 → 손익 왜곡 가능
+
+---
+
+## 5. 수익률 개선 방안
+
+### 5.1 즉시 적용 가능 (파라미터/로직 수정)
+
+| 우선순위 | 방안 | 예상 효과 | 난이도 |
+|----------|------|-----------|--------|
+| P0 | KR 손절선 확대: -2% → -4~5% 또는 ATR 기반 | 노이즈 손절 대폭 감소 | 낮음 |
+| P0 | 재진입 쿨다운: 손절 후 동일 종목 1~2시간 매수 차단 | churn & burn 패턴 제거 | 낮음 |
+| P1 | US 최소 가격 필터: $5 이하 종목 진입 차단 | 페니스탁 대폭락 방지 | 낮음 |
+| P1 | 진화 전략 코드 생성 시 syntax 검증 추가 | 진화 시스템 정상화 | 낮음 |
+
+### 5.2 구조적 개선 현황 (2026-03-01 기준)
+
+**완료 항목 (모니터링 단계):**
+
+| 항목 | 이슈 | 상태 |
+|------|------|------|
+| SELL PnL 계산을 sell_qty 기준으로 수정 (ROOT-6) | #322 | ✅ 머지 |
+| v2 staged exit 피처 공급 + 독립 파라미터 설정 (ROOT-5) | #325 | ✅ 머지 |
+| BUY 매칭 키에 exchange_code 추가 (ROOT-7) | #323 | ✅ 머지 |
+| 블랙아웃 복구 주문 `log_trade()` 추가 (GAP-4) | #324 | ✅ 머지 |
+| 세션 전환 리스크 파라미터 동적 재로딩 (GAP-3) | #327 | ✅ 머지 |
+| session_id 거래/의사결정 로그 명시 전달 (GAP-1, GAP-2) | #326 | ✅ 머지 |
+| 블랙아웃 복구 가격/세션 재검증 강화 (GAP-4 잔여) | #328 | ✅ 머지 |
+
+**잔여 개선 항목:**
+
+| 우선순위 | 방안 | 난이도 |
+|----------|------|--------|
+| P1 | US 시장 ATR 공급 경로 완성 (ROOT-5 잔여) | 중간 |
+| P1 | FX PnL 운영 활성화 (REQ-V3-007) | 낮음 |
+| P2 | pred_down_prob ML 모델 대체 (ROOT-5 잔여) | 높음 |
+| P2 | 세션 경계 E2E 통합 테스트 보강 (GAP-3 잔여) | 낮음 |
+
+### 5.3 권장 실행 순서
+
+```
+Phase 1 (즉시): 파라미터 조정
+  → KR 손절 확대 + 재진입 쿨다운 + US 가격 필터
+  → 예상: 가장 큰 손실 패턴 2개(노이즈 손절, 반복 매매) 즉시 제거
+
+Phase 2 (단기): 데이터 정합성 + v2 실효화
+  → SELL PnL을 sell_qty 기준으로 수정
+  → BUY 매칭 키에 exchange_code 추가
+  → 블랙아웃 복구 주문 DB 기록 추가
+  → v2 staged exit에 실제 피처(ATR, pred_down_prob) 공급 + 독립 파라미터 설정
+  → session_id 명시적 전달
+  → 예상: 손익 정확도 확보 + 수익 구간 보호 메커니즘 실효화
+
+Phase 3 (중기): v3 세션 최적화
+  → 세션 전환 훅 + 파라미터 재로딩
+  → 블랙아웃 재검증
+  → 운영 거버넌스 CI 자동화
+```
+
+---
+
+## 6. 테스트 커버리지 현황
+
+### 테스트 존재 (통과)
+
+- ✅ 상태기계 승격 (`test_strategy_state_machine.py`)
+- ✅ 4중 청산 규칙 (`test_strategy_exit_rules.py`)
+- ✅ Triple Barrier 라벨링 (`test_triple_barrier.py`)
+- ✅ Walk-Forward + Purge/Embargo (`test_walk_forward_split.py`)
+- ✅ 백테스트 비용 검증 (`test_backtest_cost_guard.py`)
+- ✅ Kill Switch 순서 (`test_kill_switch.py`)
+- ✅ 블랙아웃 관리 (`test_blackout_manager.py`)
+- ✅ 주문 정책 저유동 거부 (`test_order_policy.py`)
+- ✅ FX 손익 분리 (`test_db.py`)
+- ✅ 블랙아웃 복구 후 유효 intent 실행 (`tests/test_main.py:5811`)
+- ✅ 블랙아웃 복구 후 정책 거부 intent 드롭 (`tests/test_main.py:5851`)
+
+### 테스트 추가됨 (Phase 1~3, 2026-03-01)
+
+- ✅ KR ATR 기반 동적 hard stop (`test_main.py` — #318)
+- ✅ 재진입 쿨다운 (손절 후 동일 종목 매수 차단) (`test_main.py` — #319)
+- ✅ US 최소 가격 필터 ($5 이하 차단) (`test_main.py` — #320)
+- ✅ 진화 전략 syntax 검증 (`test_evolution.py` — #321)
+- ✅ SELL PnL sell_qty 기준 계산 (`test_main.py` — #322)
+- ✅ BUY 매칭 키 exchange_code 포함 (`test_db.py` — #323)
+- ✅ 블랙아웃 복구 주문 DB 기록 (`test_main.py` — #324)
+- ✅ staged exit에 실제 ATR/RSI 피처 공급 (`test_main.py` — #325)
+- ✅ session_id 거래/의사결정 로그 명시적 전달 (`test_main.py`, `test_decision_logger.py` — #326)
+- ✅ 블랙아웃 복구 후 유효 intent 실행 (`tests/test_main.py:5811`)
+- ✅ 블랙아웃 복구 후 정책 거부 intent 드롭 (`tests/test_main.py:5851`)
+
+### 테스트 미존재 (잔여)
+
+- ✅ 세션 전환 훅 콜백/세션 경계 리스크 재로딩 E2E 회귀 (`#376`)
+- ❌ 실거래 경로 ↔ v2 상태기계 통합 테스트 (피처 공급 포함)
+- ❌ FX PnL 운영 활성화 검증 (GAP-6)
+
+---
+
+## 7. 후속 문서
+
+- **실행 계획**: [85_loss_recovery_action_plan.md](./85_loss_recovery_action_plan.md) — ROOT/GAP 해소를 위한 Phase별 작업 분해 및 Gitea 이슈 연결
+- **표준 집계 SQL**: [scripts/audit_queries.sql](../../scripts/audit_queries.sql)
+
+---
+
+*끝.*

docs/ouroboros/82_doc_restructure_plan.md

@@ -0,0 +1,96 @@
+<!--
+Doc-ID: DOC-PLAN-082
+Version: 1.0.0
+Status: draft
+Owner: strategy
+Updated: 2026-02-28
+-->
+
+# 문서 재구조화 계획: 감사 → 실행 파이프라인
+
+## Context
+
+80_implementation_audit.md는 v2/v3 구현 감사와 수익률 분석을 수행했으나, 여러 차례 리뷰를 거치면서 리뷰 이력/데이터 품질 논의/SQL 쿼리 등이 혼재되어 **실행 문서로 사용하기 어려운 상태**다.
+
+목표: 이 감사 결과를 바탕으로 **티켓 생성 → 개발 설계 → 구현/리뷰 → 검증 → 실환경 테스트**까지 일관되게 진행할 수 있는 문서 체계를 만든다.
+
+## 변경 사항
+
+### 1. 80_implementation_audit.md 정리 (감사 기록 문서)
+
+**역할**: 현재 상태의 팩트 기록. "무엇이 문제인가"에만 집중.
+
+정리 내용:
+- Section 3: P&L 분석을 핵심 수치만 남기고 간결화
+  - 3.1(종합), 3.3(시장별), 3.4(통화 분리), 3.5(전략 진입분 분리), 3.6(무결성 결론) 유지
+  - 3.2 일별 손익: 주의 문구 제거, 본문으로 통합
+  - 3.7 데이터 품질: 핵심 결론만 남기고 세부 항목 제거
+  - 3.8 SQL: 별도 파일(`scripts/audit_queries.sql`)로 분리, 본문에서 참조만
+- Section 6.1, 6.2 리뷰 반영 이력: 전부 제거 (git history로 추적 가능)
+- Section 6 테스트: "재점검으로 확인" 항목을 "테스트 존재" 항목에 통합
+- 신규 Section 7: 후속 문서 링크 (85_ 참조)
+
+### 2. 85_loss_recovery_action_plan.md 신규 작성 (실행 계획 문서)
+
+**역할**: "어떻게 고칠 것인가". 티켓 생성부터 실환경 검증까지의 실행 청사진.
+
+구조:
+```
+## 1. 요약
+- 목표: 손실 구간 탈출을 위한 7개 ROOT/5개 GAP 해소
+- 성공 기준 (정량)
+
+## 2. Phase별 작업 분해
+### Phase 1: 즉시 파라미터/로직 수정 (손실 출혈 차단)
+  각 항목마다:
+  - ROOT/GAP 참조
+  - Gitea 이슈 제목/설명 템플릿
+  - 변경 대상 파일 + 현재 동작 + 목표 동작
+  - 수용 기준 (acceptance criteria)
+  - 테스트 계획
+  - 의존성/차단 관계
+
+### Phase 2: 데이터 정합성 + v2 실효화
+  (동일 형식)
+
+### Phase 3: v3 세션 최적화
+  (동일 형식)
+
+## 3. 검증 계획
+- 단위 테스트 기준
+- 통합 테스트 시나리오 (백테스트 파이프라인 활용)
+- 실환경 검증: 소액 live 운용으로 직접 검증
+  (paper trading 제외 — 실환경과 괴리가 커 검증 신뢰도 부족)
+- Phase별 실환경 투입 기준:
+  단위/통합 테스트 통과 → 소액 live → 모니터링 → 정상 확인 후 본운용
+
+## 4. 의존성 그래프
+- Phase 간 blocking 관계
+- Phase 내 작업 순서
+
+## 5. 롤백 계획
+- 각 Phase 실패 시 롤백 절차
+```
+
+### 3. README.md 업데이트
+
+- 85_ 문서 링크 추가
+
+## 작업 순서
+
+1. 80_ 정리 (노이즈 제거, SQL 분리, 리뷰 이력 삭제)
+2. `scripts/audit_queries.sql` 작성 (80_에서 분리한 SQL)
+3. 85_ 신규 작성 (실행 계획)
+4. README.md 업데이트
+
+## 작성하지 않는 것
+
+- 30_code_level_work_orders.md, 40_acceptance_and_test_plan.md 업데이트: 85_를 기반으로 실제 구현 시점에 업데이트 (지금은 실행 계획 수립까지만)
+- 01_requirements_registry.md: ROOT/GAP에서 파생되는 신규 REQ는 구현 착수 시 등록
+- Gitea 이슈 생성: 85_ 문서 확정 후 별도 진행
+
+## 검증
+
+- 80_: 감사 팩트만 남았는지, 리뷰 이력이 제거되었는지 확인
+- 85_: Phase별 작업이 Gitea 이슈로 바로 전환 가능한 수준인지 확인
+- 85_ 각 항목에 수용 기준과 테스트 계획이 포함되었는지 확인

docs/ouroboros/85_loss_recovery_action_plan.md

@@ -0,0 +1,417 @@
+<!--
+Doc-ID: DOC-ACTION-085
+Version: 1.1.0
+Status: active
+Owner: strategy
+Updated: 2026-03-01
+-->
+
+# 손실 복구 실행 계획
+
+작성일: 2026-02-28
+최종 업데이트: 2026-03-01 (Phase 1~3 완료 상태 반영)
+기반 문서: [80_implementation_audit.md](./80_implementation_audit.md) (ROOT 7개 + GAP 5개)
+
+> **2026-03-01 현황**: Phase 1 ✅ 완료, Phase 2 ✅ 완료, Phase 3 ✅ 기본 완료 (ACT-13 고도화 잔여)
+
+---
+
+## 1. 요약
+
+### 1.1 목표
+
+80_implementation_audit.md에서 식별된 7개 근본 원인(ROOT-1~7)과 5개 구현 갭(GAP-1~5)을 해소하여 실거래 손실 구간에서 탈출한다.
+
+### 1.2 성공 기준 (정량)
+
+| 지표 | 현재 | 목표 |
+|------|------|------|
+| KR 시장 승률 | 38.5% | >= 50% |
+| 동일 종목 반복 매매 (일간) | 최대 4회 | <= 2회 |
+| US 페니스탁($5 이하) 진입 | 무제한 | 0건 |
+| SELL PnL 수량 불일치 건 | 존재 | 0건 |
+| 블랙아웃 복구 주문 DB 누락 | 존재 | 0건 |
+| session_id 누락 거래 로그 | 다수 | 0건 |
+| 진화 전략 syntax 오류율 | 100% (확인된 3건 모두) | 0% |
+
+---
+
+## 2. Phase별 작업 분해
+
+### Phase 1: 즉시 — 손실 출혈 차단 ✅ 완료
+
+가장 큰 손실 패턴(노이즈 손절, 반복 매매, 페니스탁)을 즉시 제거한다.
+
+---
+
+#### ACT-01: KR 손절선 ATR 기반 동적 확대 ✅ 머지
+
+- **ROOT 참조**: ROOT-1 (hard_stop_pct -2%가 KR 소형주 변동성 대비 과소)
+- **Gitea 이슈**: feat: KR 손절선 ATR 기반 동적 확대 (-2% → ATR 적응형)
+- **Gitea 이슈 번호**: #318
+- **변경 대상 파일**: `src/main.py`, `src/strategy/exit_rules.py`, `src/config.py`
+- **현재 동작**: `hard_stop_pct = -2.0` 고정값으로 모든 시장에 동일 적용
+- **목표 동작**: KR 시장은 ATR(14) 기반 동적 손절선 적용. 최소 -2%, 최대 -7%, 기본값은 `k * ATR / entry_price * 100` (k=2.0)
+- **수용 기준**:
+  - ATR 값이 존재할 때 동적 손절선이 계산됨
+  - ATR 미제공 시 기존 -2% 폴백
+  - KR 이외 시장은 기존 동작 유지
+- **테스트 계획**:
+  - 단위: ATR 기반 손절선 계산 로직 테스트 (경계값: ATR=0, ATR=극단값)
+  - 통합: 백테스트 파이프라인에서 KR 종목 손절 빈도 비교
+- **의존성**: 없음
+
+---
+
+#### ACT-02: 손절 후 동일 종목 재진입 쿨다운 ✅ 머지
+
+- **ROOT 참조**: ROOT-2 (동일 종목 반복 매매)
+- **Gitea 이슈**: feat: 손절 후 동일 종목 재진입 쿨다운 (1~2시간)
+- **Gitea 이슈 번호**: #319
+- **변경 대상 파일**: `src/main.py`, `src/config.py`
+- **현재 동작**: 손절 후 동일 종목 즉시 재매수 가능
+- **목표 동작**: 손절(SELL with pnl < 0) 후 동일 종목은 `COOLDOWN_MINUTES` (기본 120분) 동안 매수 차단
+- **수용 기준**:
+  - 손절 기록이 있는 종목에 대해 쿨다운 시간 내 BUY 시도 시 거부
+  - 쿨다운 경과 후 정상 진입 허용
+  - 익절(pnl >= 0)에는 쿨다운 미적용
+- **테스트 계획**:
+  - 단위: 쿨다운 시간 내/외 매수 시도 테스트
+  - 통합: 229000 유사 패턴 백테스트 시나리오
+- **의존성**: 없음
+
+---
+
+#### ACT-03: US $5 이하 종목 진입 차단 필터 ✅ 머지
+
+- **ROOT 참조**: ROOT-3 (미국 페니스탁 무분별 진입)
+- **Gitea 이슈**: feat: US $5 이하 종목 진입 차단 필터
+- **Gitea 이슈 번호**: #320
+- **변경 대상 파일**: `src/main.py`, `src/config.py`
+- **현재 동작**: 가격 제한 없이 모든 US 종목 진입 가능
+- **목표 동작**: US 시장 BUY 시 현재가 $5 이하이면 진입 차단. 임계값은 `US_MIN_PRICE` 환경변수로 설정 가능
+- **수용 기준**:
+  - $5 이하 종목 BUY 시도 시 거부 + 로그 기록
+  - $5 초과 종목은 기존 동작 유지
+  - KR 등 다른 시장에는 미적용
+- **테스트 계획**:
+  - 단위: 가격별 필터 동작 테스트 (경계값: $4.99, $5.00, $5.01)
+- **의존성**: 없음
+
+---
+
+#### ACT-04: 진화 전략 코드 생성 시 syntax 검증 추가 ✅ 머지
+
+- **ROOT 참조**: ROOT-4 (진화 전략 문법 오류)
+- **Gitea 이슈**: fix: 진화 전략 코드 생성 시 syntax 검증 추가
+- **Gitea 이슈 번호**: #321
+- **변경 대상 파일**: `src/evolution/optimizer.py`
+- **현재 동작**: 생성된 Python 코드를 검증 없이 파일로 저장
+- **목표 동작**: `ast.parse()` + `compile()` 로 syntax 검증 후 통과한 코드만 저장. 실패 시 로그 경고 + 기존 전략 유지
+- **수용 기준**:
+  - syntax 오류가 있는 코드는 저장되지 않음
+  - 검증 실패 시 기존 전략으로 폴백
+  - 검증 실패 로그가 기록됨
+- **테스트 계획**:
+  - 단위: 정상 코드/오류 코드 검증 테스트
+  - 기존 `v20260227_*_evolved.py` 파일로 회귀 테스트
+- **의존성**: 없음
+
+---
+
+### Phase 2: 단기 — 데이터 정합성 + v2 실효화 ✅ 완료
+
+손익 계산 정확도를 확보하고, v2 청산 로직을 실효화한다.
+
+---
+
+#### ACT-05: SELL PnL 계산을 sell_qty 기준으로 수정 ✅ 머지
+
+- **ROOT 참조**: ROOT-6 (CRITICAL — PnL 계산이 buy_qty 사용)
+- **Gitea 이슈**: fix(critical): SELL PnL 계산을 sell_qty 기준으로 수정
+- **Gitea 이슈 번호**: #322
+- **변경 대상 파일**: `src/main.py` (line 1658-1663, 2755-2760)
+- **현재 동작**: `trade_pnl = (trade_price - buy_price) * buy_qty` — 직전 BUY 수량 사용
+- **목표 동작**: `trade_pnl = (trade_price - buy_price) * sell_qty` — 실제 매도 수량 사용
+- **수용 기준**:
+  - 부분청산 시 매도 수량 기준 PnL 계산
+  - 기존 전량 매도(buy_qty == sell_qty) 케이스는 동일 결과
+  - CRCA 유사 이상치 재발 불가
+- **테스트 계획**:
+  - 단위: 전량 매도, 부분 매도, 수량 불일치 케이스별 PnL 검증
+  - DB: Q4 쿼리(`scripts/audit_queries.sql`)로 이상치 0건 확인
+- **의존성**: 없음
+
+---
+
+#### ACT-06: BUY 매칭 키에 exchange_code 추가 ✅ 머지
+
+- **ROOT 참조**: ROOT-7 (BUY 매칭 키에 exchange_code 미포함)
+- **Gitea 이슈**: fix: BUY 매칭 키에 exchange_code 추가
+- **Gitea 이슈 번호**: #323
+- **변경 대상 파일**: `src/db.py` (line 292-313)
+- **현재 동작**: `get_latest_buy_trade()`가 `(stock_code, market)`만으로 매칭
+- **목표 동작**: `exchange_code`가 존재할 때 매칭 키에 포함. NULL인 경우 기존 동작 유지 (하위 호환)
+- **수용 기준**:
+  - 동일 티커 다중 거래소 기록 시 정확한 BUY 매칭
+  - exchange_code가 NULL인 레거시 데이터에서도 정상 동작
+- **테스트 계획**:
+  - 단위: 동일 티커 다중 exchange 매칭 테스트
+  - 단위: exchange_code NULL 하위 호환 테스트
+- **의존성**: 없음
+
+---
+
+#### ACT-07: 블랙아웃 복구 주문에 log_trade() 추가 ✅ 머지
+
+- **ROOT 참조**: GAP-4 (블랙아웃 복구 주문 DB 미기록)
+- **Gitea 이슈**: fix: 블랙아웃 복구 주문에 log_trade() 추가
+- **Gitea 이슈 번호**: #324
+- **변경 대상 파일**: `src/main.py` — `process_blackout_recovery_orders()` 함수 내 복구 주문 실행 경로
+- **현재 동작**: 블랙아웃 복구 주문이 실행되나 `log_trade()` 호출 없음 → DB에 기록 안 됨
+- **목표 동작**: 복구 주문 실행 후 `log_trade()` 호출하여 DB에 기록. rationale에 `[blackout-recovery]` prefix 추가
+- **수용 기준**:
+  - 블랙아웃 복구 주문이 trades 테이블에 기록됨
+  - rationale로 복구 주문 식별 가능
+  - 성과 리포트에 복구 주문 포함
+- **테스트 계획**:
+  - 단위: 복구 주문 실행 후 DB 기록 존재 확인
+  - 통합: 블랙아웃 시나리오 end-to-end 테스트
+- **의존성**: 없음
+
+---
+
+#### ACT-08: v2 staged exit에 실제 피처 공급 ✅ 머지
+
+- **ROOT 참조**: ROOT-5 (v2 청산 로직 실효성 부족)
+- **Gitea 이슈**: feat: v2 staged exit에 실제 피처(ATR, pred_down_prob) 공급
+- **Gitea 이슈 번호**: #325
+- **변경 대상 파일**: `src/main.py` (line 500-583), `src/strategy/exit_rules.py`, `src/analysis/technical.py`
+- **현재 동작**: `atr_value=0.0`, `pred_down_prob=0.0`으로 공급 → hard stop만 발동
+- **목표 동작**:
+  - `atr_value`: 보유 종목의 ATR(14) 실시간 계산하여 공급
+  - `pred_down_prob`: 최소한 RSI 기반 하락 확률 추정값 공급 (추후 ML 모델로 대체 가능)
+  - `be_arm_pct`/`arm_pct`: 독립 파라미터로 설정 가능 (take_profit_pct * 0.4 기계적 파생 제거)
+- **수용 기준**:
+  - `evaluate_exit()` 호출 시 atr_value > 0 (ATR 계산 가능한 종목)
+  - ATR trailing stop이 실제 발동 가능
+  - be_arm_pct/arm_pct 독립 설정 가능
+- **테스트 계획**:
+  - 단위: 피처 공급 경로별 값 검증
+  - 통합: 상태기계 전이 시나리오 (HOLDING→BE_LOCK→ARMED→EXITED)
+- **의존성**: ACT-01 (ATR 계산 인프라 공유)
+
+---
+
+#### ACT-09: session_id를 거래/의사결정 로그에 명시적 전달 ✅ 머지
+
+- **ROOT 참조**: GAP-1 (DecisionLogger session_id 미포함), GAP-2 (log_trade session_id 미전달)
+- **Gitea 이슈**: feat: session_id를 거래/의사결정 로그에 명시적 전달
+- **Gitea 이슈 번호**: #326
+- **변경 대상 파일**: `src/logging/decision_logger.py`, `src/main.py` (line 1625, 1682, 2769), `src/db.py`
+- **현재 동작**:
+  - `log_decision()`: session_id 파라미터 없음
+  - `log_trade()`: session_id 미전달, 시장 코드 기반 자동 추론에 의존
+- **목표 동작**:
+  - `log_decision()`: session_id 파라미터 추가, 로그에 기록
+  - `log_trade()` 호출 시 런타임 session_id 명시적 전달
+- **수용 기준**:
+  - 모든 SELL/BUY 로그에 session_id 필드 존재
+  - 의사결정 로그에 session_id 필드 존재
+  - session_id가 실제 런타임 세션과 일치
+- **테스트 계획**:
+  - 단위: log_decision() session_id 캡처 테스트
+  - 단위: log_trade() session_id 전달 테스트
+- **의존성**: 없음
+
+---
+
+### Phase 3: 중기 — v3 세션 최적화 ✅ 기본 완료 (ACT-13 고도화 잔여)
+
+세션 경계 처리와 운영 거버넌스를 강화한다.
+
+---
+
+#### ACT-10: 세션 전환 시 리스크 파라미터 동적 재로딩 ✅ 머지
+
+- **ROOT 참조**: GAP-3 (세션 전환 시 리스크 파라미터 재로딩 없음)
+- **Gitea 이슈**: feat: 세션 전환 시 리스크 파라미터 동적 재로딩
+- **Gitea 이슈 번호**: #327
+- **변경 대상 파일**: `src/main.py`, `src/config.py`
+- **현재 동작**: 리스크 파라미터가 시작 시 한 번만 로딩
+- **목표 동작**: 세션 경계 변경 이벤트 시 해당 세션의 리스크 파라미터를 재로딩. 세션별 프로파일 지원
+- **수용 기준**:
+  - NXT_AFTER → KRX_REG 전환 시 파라미터 재로딩 확인
+  - 재로딩 이벤트 로그 기록
+  - 재로딩 실패 시 기존 파라미터 유지 (안전 폴백)
+- **테스트**: `test_main.py`에 설정 오버라이드/리로드/폴백 단위 테스트 포함. **잔여**: 세션 경계 실시간 전환 E2E 보강
+- **의존성**: ACT-09 (session_id 인프라)
+
+---
+
+#### ACT-11: 블랙아웃 복구 시 가격/세션 재검증 강화 ✅ 머지
+
+- **ROOT 참조**: GAP-4 잔여 (가격 유효성, 세션 변경 재적용 미구현)
+- **Gitea 이슈**: feat: 블랙아웃 복구 시 가격/세션 재검증 강화
+- **Gitea 이슈 번호**: #328
+- **변경 대상 파일**: `src/main.py` (line 694-791), `src/core/blackout_manager.py`
+- **현재 동작**: stale BUY/SELL 드롭 + order_policy 검증만 수행
+- **목표 동작**:
+  - 복구 시 현재 시세 조회하여 가격 유효성 검증 (진입가 대비 급등/급락 시 드롭)
+  - 세션 변경 시 새 세션의 파라미터로 재검증
+- **수용 기준**:
+  - 블랙아웃 전후 가격 변동 > 임계값(예: 5%) 시 주문 드롭
+  - 세션 변경 시 새 세션 파라미터로 재평가
+- **테스트 계획**:
+  - 단위: 가격 변동 시나리오별 드롭/실행 테스트
+  - 통합: 블랙아웃 + 세션 전환 복합 시나리오
+- **의존성**: ACT-07 (복구 주문 DB 기록), ACT-10 (세션 파라미터 재로딩)
+
+---
+
+#### ACT-12: Triple Barrier 시간장벽을 캘린더 시간(분) 기반으로 전환 ✅ 머지
+
+- **ROOT 참조**: GAP-5 (시간장벽이 봉 개수 고정)
+- **Gitea 이슈**: feat: Triple Barrier 시간장벽을 캘린더 시간(분) 기반으로 전환
+- **Gitea 이슈 번호**: #329
+- **변경 대상 파일**: `src/analysis/triple_barrier.py`
+- **현재 동작**: `max_holding_bars` (고정 봉 수) 사용
+- **목표 동작**: `max_holding_minutes` (캘린더 시간) 기반으로 전환. 봉 주기와 무관하게 일정 시간 경과 시 장벽 도달
+- **수용 기준**:
+  - 분 단위 시간장벽이 봉 주기 변경에도 일관 동작
+  - 기존 max_holding_bars 하위 호환 (deprecated 경고)
+- **테스트 계획**:
+  - 단위: 다양한 봉 주기(1분, 5분, 15분)에서 시간장벽 일관성 테스트
+  - 기존 triple_barrier 테스트 회귀 확인
+- **의존성**: 없음
+
+---
+
+#### ACT-13: CI 자동 검증 (정책 레지스트리 + TASK-REQ 매핑) ✅ 기본 구현 완료, 고도화 잔여
+
+- **ROOT 참조**: REQ-OPS-002 (정책 변경 시 레지스트리 업데이트 강제), REQ-OPS-003 (TASK-REQ 매핑 강제)
+- **Gitea 이슈**: infra: CI 자동 검증 (정책 레지스트리 + TASK-REQ 매핑)
+- **Gitea 이슈 번호**: #330
+- **현재 동작**: `.gitea/workflows/ci.yml`에서 `scripts/validate_governance_assets.py` + `scripts/validate_ouroboros_docs.py` 자동 실행
+- **잔여 고도화**: PR 본문 REQ/TASK/TEST 강제 레벨 상향, 정책 파일 미업데이트 시 CI 실패 기준 강화
+- **의존성**: 없음
+
+---
+
+## 3. 검증 계획
+
+### 3.1 단위 테스트
+
+- 모든 ACT 항목에 대해 개별 테스트 작성
+- 커버리지 >= 80% 유지
+- 현재 CI 기준 전체 테스트 통과 확인 (2026-03-01 기준 998 tests collected)
+
+### 3.2 통합 테스트
+
+- 백테스트 파이프라인: Phase 1 적용 전후 KR 시장 손절 빈도, 반복 매매 횟수, 승률 비교
+- 상태기계 통합: Phase 2 피처 공급 후 4중 청산 로직 end-to-end 시나리오
+- 블랙아웃 복합: Phase 3 세션 전환 + 블랙아웃 복구 시나리오
+
+### 3.3 실환경 검증
+
+- Paper trading은 실환경과 괴리가 커 검증 신뢰도 부족 → **소액 live 운용**으로 검증
+- Phase별 투입 기준: 단위/통합 테스트 통과 → 소액 live (1~2일) → 모니터링 → 정상 확인 후 본운용
+
+---
+
+## 4. 의존성 그래프
+
+```
+Phase 1 (병렬 실행 가능)
+  ACT-01 #318 ─┐
+  ACT-02 #319  │  (모두 독립)
+  ACT-03 #320  │
+  ACT-04 #321 ─┘
+
+Phase 2
+  ACT-05 #322 ─┐
+  ACT-06 #323  │  (대부분 독립)
+  ACT-07 #324  │
+  ACT-09 #326 ─┘
+  ACT-08 #325 ←── ACT-01 #318 (ATR 인프라 공유)
+
+Phase 3
+  ACT-10 #327 ←── ACT-09 #326 (session_id 인프라)
+  ACT-11 #328 ←── ACT-07 #324, ACT-10 #327
+  ACT-12 #329     (독립)
+  ACT-13 #330     (독립)
+```
+
+### Phase 간 관계
+
+- Phase 1 → Phase 2: Phase 1 완료가 Phase 2의 전제 조건은 아니나, Phase 1로 출혈 차단 후 Phase 2 진행 권장
+- Phase 2 → Phase 3: ACT-09(session_id)가 ACT-10(세션 재로딩)의 전제, ACT-07+ACT-10이 ACT-11의 전제
+
+---
+
+## 5. 롤백 계획
+
+### Phase 1 롤백
+
+- 각 ACT는 독립적이므로 개별 revert 가능
+- 손절선(ACT-01): 기존 -2% 고정값으로 복원
+- 쿨다운(ACT-02): 쿨다운 체크 제거
+- 가격 필터(ACT-03): 필터 조건 제거
+- syntax 검증(ACT-04): 검증 스킵, 기존 저장 로직 복원
+
+### Phase 2 롤백
+
+- PnL 수정(ACT-05): buy_qty 기준으로 복원 (단, 데이터 정합성 후퇴 감수)
+- exchange_code(ACT-06): 매칭 키에서 제거
+- 블랙아웃 DB(ACT-07): log_trade() 호출 제거
+- 피처 공급(ACT-08): 0.0 공급으로 복원
+- session_id(ACT-09): 파라미터 제거, 자동 추론 복원
+
+### Phase 3 롤백
+
+- 세션 재로딩(ACT-10): 시작 시 1회 로딩으로 복원
+- 블랙아웃 재검증(ACT-11): 기존 stale 드롭만 유지
+- 시간장벽(ACT-12): max_holding_bars로 복원
+- CI(ACT-13): CI 워크플로우 제거
+
+### 롤백 절차
+
+1. 해당 ACT의 PR branch에서 `git revert` 수행
+2. 기존 테스트 전체 통과 확인
+3. 실환경 투입 전 소액 live 검증
+
+---
+
+## 6. 미진 사항 (2026-03-01 기준)
+
+Phase 1~3 구현 완료 후에도 다음 항목이 운영상 미완료 상태이다.
+
+### 6.1 운영 검증 필요
+
+| 항목 | 설명 | 우선순위 |
+|------|------|----------|
+| FX PnL 운영 활성화 | `fx_pnl`/`strategy_pnl` 컬럼 존재하나 모든 운영 데이터 값이 0 | P1 |
+| 세션 경계 E2E 통합 테스트 보강 | `test_main.py`에 단위 테스트 존재; 세션 경계 실시간 전환 E2E 미작성 | P2 |
+| v2 상태기계 통합 end-to-end | 실거래 경로에서 HOLDING→BE_LOCK→ARMED→EXITED 전체 시나리오 테스트 미작성 | P2 |
+
+### 6.2 아키텍처 수준 잔여 갭
+
+| 항목 | 설명 | 배경 문서 |
+|------|------|-----------|
+| CI 자동 검증 고도화 (#330) | 기본 구현 완료(`validate_governance_assets.py` CI 연동); 규칙/강제수준 고도화 필요 | REQ-OPS-002, REQ-OPS-003 |
+| pred_down_prob ML 모델 대체 | 현재 RSI 프록시 사용 — 추후 실제 GBDT/ML 모델로 대체 권장 | ROOT-5, ouroboros_plan_v2.txt §3.D |
+| KR/US 파라미터 민감도 분석 | v2 계획의 be_arm_pct/arm_pct/atr_k 최적값 탐색 미수행 | ouroboros_plan_v2.txt §8 |
+
+### 6.3 v3 실험 매트릭스 미착수
+
+ouroboros_plan_v3.txt §9에 정의된 3개 실험이 아직 시작되지 않았다.
+
+| 실험 ID | 시장 | 포커스 | 상태 |
+|---------|------|--------|------|
+| EXP-KR-01 | KR | NXT 야간 특화 (p_thresh 0.65) | ❌ 미착수 |
+| EXP-US-01 | US | 21h 준연속 운용 (atr_k 2.5) | ❌ 미착수 |
+| EXP-HYB-01 | Global | KR 낮 + US 밤 연계 레짐 자산배분 | ❌ 미착수 |
+
+---
+
+*끝.*

docs/ouroboros/README.md

@@ -0,0 +1,44 @@
+<!--
+Doc-ID: DOC-ROOT-001
+Version: 1.0.1
+Status: active
+Owner: strategy
+Updated: 2026-03-01
+-->
+
+# The Ouroboros 실행 문서 허브
+
+이 폴더는 `source/ouroboros_plan_v2.txt`, `source/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 시나리오/이슈 분류 **(A)**: [50_scenario_matrix_and_issue_taxonomy.md](./50_scenario_matrix_and_issue_taxonomy.md)
+8. TPM 제어 프로토콜/수용 매트릭스 **(B)**: [50_tpm_control_protocol.md](./50_tpm_control_protocol.md)
+9. 저장소 강제 설정 체크리스트: [60_repo_enforcement_checklist.md](./60_repo_enforcement_checklist.md)
+10. 메인 에이전트 아이디에이션 백로그: [70_main_agent_ideation.md](./70_main_agent_ideation.md)
+11. v2/v3 구현 감사 및 수익률 분석: [80_implementation_audit.md](./80_implementation_audit.md)
+12. 손실 복구 실행 계획: [85_loss_recovery_action_plan.md](./85_loss_recovery_action_plan.md)
+
+> **참고**: 7번·8번은 `50_` 프리픽스를 공유합니다. (A) = 시나리오/이슈 분류, (B) = TPM 제어 프로토콜.
+
+## 운영 규칙
+
+- 계획 변경은 반드시 `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](./source/ouroboros_plan_v2.txt)
+- [v3](./source/ouroboros_plan_v3.txt)

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

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

docs/requirements-log.md

@@ -87,7 +87,7 @@
 - 선정 기준 추적 → Evolution 시스템 최적화 가능
 - API 장애 시 정적 watchlist로 자동 전환
 
-**참고:** Realtime 모드 전용. Daily 모드는 배치 효율성을 위해 정적 watchlist 사용.
+**참고 (당시 구현 기준):** Realtime 모드 전용으로 설계되었으나, 이후 Daily 경로에서도 스캐너를 사용하도록 변경됨. 해외 fallback도 정적 watchlist → 동적 유니버스(active/recent/holdings)로 전환 (2026-02-16 참조).
 
 **이슈/PR:** #76, #77
 
@@ -292,3 +292,222 @@ Order result: 모의투자 매수주문이 완료 되었습니다.  ✓
 ```
 
 **이슈/PR:** #149, #150
+
+---
+
+## 2026-02-23
+
+### 국내주식 지정가 전환 및 미체결 처리 (#232)
+
+**배경:**
+- 해외주식은 #211에서 지정가로 전환했으나 국내주식은 여전히 `price=0` (시장가)
+- KRX도 지정가 주문 사용 시 동일한 미체결 위험이 존재
+- 지정가 전환 + 미체결 처리를 함께 구현
+
+**구현 내용:**
+
+1. `src/broker/kis_api.py`
+   - `get_domestic_pending_orders()`: 모의 즉시 `[]`, 실전 `TTTC0084R` GET
+   - `cancel_domestic_order()`: 실전 `TTTC0013U` / 모의 `VTTC0013U`, hashkey 필수
+
+2. `src/main.py`
+   - import `kr_round_down` 추가
+   - `trading_cycle`, `run_daily_session` 국내 주문 `price=0` → 지정가:
+     BUY +0.2% / SELL -0.2%, `kr_round_down` KRX 틱 반올림 적용
+   - `handle_domestic_pending_orders` 함수: BUY→취소+쿨다운, SELL→취소+재주문(-0.4%, 최대1회)
+   - daily/realtime 두 모드에서 domestic pending 체크 호출 추가
+
+3. 테스트 14개 추가:
+   - `TestGetDomesticPendingOrders` (3), `TestCancelDomesticOrder` (5)
+   - `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
+
+---
+
+## 2026-02-27
+
+### v2 백테스트 파이프라인 통합 (#305)
+
+**배경:**
+- `TripleBarrier`, `WalkForward`, `BacktestCostGuard`는 개별 모듈로 존재했으나,
+  하나의 실행 경로로 연결된 파이프라인이 없어 통합 검증이 불가능했다.
+
+**구현 내용:**
+
+1. `src/analysis/backtest_pipeline.py`
+   - `run_v2_backtest_pipeline()` 추가:
+     - `validate_backtest_cost_model()` 선검증(fail-fast)
+     - `label_with_triple_barrier()`로 entry 라벨 생성
+     - `generate_walk_forward_splits()`로 fold 생성
+     - fold별 baseline(`B0`, `B1`, `M1`) score 산출
+   - 결과 아티팩트 계약 구조(`BacktestPipelineResult`) 정의
+   - leakage 검사 유틸 `fold_has_leakage()` 제공
+
+2. `tests/test_backtest_pipeline_integration.py` 신규
+   - happy path 통합 검증
+   - cost guard 실패 fail-fast 검증
+   - purge/embargo 기반 누수 방지 검증
+   - 동일 입력 재실행 결정성 검증
+
+**검증:**
+- `pytest -q tests/test_backtest_pipeline_integration.py tests/test_triple_barrier.py tests/test_walk_forward_split.py tests/test_backtest_cost_guard.py tests/test_backtest_execution_model.py`
+- `ruff check src/analysis/backtest_pipeline.py tests/test_backtest_pipeline_integration.py`
+
+**이슈/PR:** #305
+
+---
+
+## 2026-02-28 ~ 2026-03-01
+
+### v2/v3 손실 복구 실행 계획 — Phase 1 완료 (#318~#321)
+
+**배경:**
+- `docs/ouroboros/80_implementation_audit.md` 감사 결과 식별된 7개 근본 원인(ROOT) 및 5개 구현 갭(GAP) 중
+  가장 큰 손실 패턴 4개를 Phase 1로 즉시 제거.
+
+**구현 내용:**
+
+1. **ACT-01: KR 손절선 ATR 기반 동적 확대** (#318)
+   - `src/main.py`, `src/config.py`
+   - KR 시장: ATR(14) 기반 동적 hard stop (`k=2.0`, 범위 -2%~-7%)
+   - ATR 미제공 시 기존 -2% 폴백
+   - ROOT-1 (hard_stop_pct 고정값 과소) 해소
+
+2. **ACT-02: 손절 후 동일 종목 재진입 쿨다운** (#319)
+   - `src/main.py`, `src/config.py`
+   - 손절(pnl<0) 후 동일 종목 `COOLDOWN_MINUTES`(기본 120분) 동안 BUY 차단
+   - 익절에는 미적용
+   - ROOT-2 (동일 종목 반복 매매) 해소
+
+3. **ACT-03: US $5 이하 종목 진입 차단 필터** (#320)
+   - `src/main.py`, `src/config.py`
+   - US 시장 BUY 시 현재가 `US_MIN_PRICE`(기본 $5) 이하 차단
+   - ROOT-3 (미국 페니스탁 무분별 진입) 해소
+
+4. **ACT-04: 진화 전략 코드 syntax 검증** (#321)
+   - `src/evolution/optimizer.py`
+   - `ast.parse()` + `compile()` 선검증 후 통과한 코드만 저장
+   - ROOT-4 (진화 전략 문법 오류) 해소
+
+**이슈/PR:** #318, #319, #320, #321
+
+---
+
+### v2/v3 손실 복구 실행 계획 — Phase 2 완료 (#322~#326)
+
+**배경:**
+- 손익 계산 정확도 확보 및 v2 청산 로직 실효화.
+
+**구현 내용:**
+
+1. **ACT-05: SELL PnL 계산을 sell_qty 기준으로 수정** (#322)
+   - `src/main.py` (line 1658-1663, 2755-2760)
+   - `trade_pnl = (trade_price - buy_price) * sell_qty`로 변경
+   - ROOT-6 (PnL 계산 buy_qty 사용 CRITICAL) 해소
+
+2. **ACT-06: BUY 매칭 키에 exchange_code 추가** (#323)
+   - `src/db.py`
+   - `get_latest_buy_trade()`가 `(stock_code, market, exchange_code)` 기준 매칭
+   - exchange_code NULL인 레거시 데이터 하위 호환 유지
+   - ROOT-7 (오매칭 리스크) 해소
+
+3. **ACT-07: 블랙아웃 복구 주문에 log_trade() 추가** (#324)
+   - `src/main.py` (블랙아웃 복구 실행 경로)
+   - 복구 주문 실행 후 `log_trade()` 호출, rationale에 `[blackout-recovery]` prefix
+   - GAP-4 (블랙아웃 복구 주문 DB 미기록) 해소
+
+4. **ACT-08: v2 staged exit에 실제 피처 공급** (#325)
+   - `src/main.py`, `src/strategy/exit_rules.py`
+   - `atr_value`: ATR(14) 실시간 계산 공급
+   - `pred_down_prob`: RSI 기반 하락 확률 추정값 공급 (ML 모델 대체 가능)
+   - `be_arm_pct`/`arm_pct` 독립 파라미터 설정 가능 (take_profit_pct * 0.4 파생 제거)
+   - ROOT-5 (v2 청산 로직 실효성 부족) 해소
+
+5. **ACT-09: session_id를 거래/의사결정 로그에 명시적 전달** (#326)
+   - `src/logging/decision_logger.py`, `src/main.py`, `src/db.py`
+   - `log_decision()`: session_id 파라미터 추가
+   - `log_trade()`: 런타임 session_id 명시적 전달
+   - GAP-1, GAP-2 (session_id 미포함) 부분 해소
+
+**이슈/PR:** #322, #323, #324, #325, #326
+
+---
+
+### v2/v3 손실 복구 실행 계획 — Phase 3 부분 완료 (#327~#329)
+
+**배경:**
+- 세션 경계 처리 및 시간장벽 캘린더 기반 전환.
+
+**구현 내용:**
+
+1. **ACT-10: 세션 전환 시 리스크 파라미터 동적 재로딩** (#327)
+   - `src/main.py`, `src/config.py`
+   - 세션 경계 변경 이벤트 시 `SESSION_RISK_PROFILES_JSON` 기반 재로딩
+   - 재로딩 실패 시 기존 파라미터 유지 (안전 폴백)
+   - GAP-3 (세션 전환 시 파라미터 재로딩 없음) 부분 해소
+
+2. **ACT-11: 블랙아웃 복구 시 가격/세션 재검증 강화** (#328)
+   - `src/main.py`, `src/core/blackout_manager.py`
+   - 복구 시 현재 시세 조회하여 가격 유효성 검증 (진입가 대비 급등/급락 시 드롭)
+   - 세션 변경 시 새 세션의 파라미터로 재검증
+   - GAP-4 잔여 (가격/세션 재검증) 부분 해소
+
+3. **ACT-12: Triple Barrier 시간장벽을 캘린더 시간(분) 기반으로 전환** (#329)
+   - `src/analysis/triple_barrier.py`
+   - `max_holding_minutes` (캘린더 분) 기반 전환, 봉 주기 무관 일관 동작
+   - 기존 `max_holding_bars` deprecated 경고 유지 (하위 호환)
+   - GAP-5 (시간장벽 봉 개수 고정) 해소
+
+**미완료 (ACT-13):**
+- **#330: CI 자동 검증 (정책 레지스트리 + TASK-REQ 매핑)** — 문서 구조화 작업으로 대체 진행 중
+
+**이슈/PR:** #327, #328, #329
+
+---
+
+### v2/v3 문서 구조화 및 감사 문서 작성 (#331)
+
+**배경:**
+- Phase 1~3 구현 완료 후 감사 결과와 실행 계획을 문서화
+- 기존 감사 문서가 산발적으로 관리되어 통합 정리 필요
+
+**구현 내용:**
+- `docs/ouroboros/80_implementation_audit.md` 신규 작성: v2/v3 구현 감사 + 실거래 수익률 분석
+- `docs/ouroboros/85_loss_recovery_action_plan.md` 신규 작성: ROOT/GAP 해소 Phase별 실행 계획
+- `scripts/audit_queries.sql` 신규 작성: 성과 재현용 표준 집계 SQL
+
+**이슈/PR:** #331

docs/testing.md

@@ -2,7 +2,7 @@
 
 ## Test Structure
 
-**551 tests** across **25 files**. `asyncio_mode = "auto"` in pyproject.toml — async tests need no special decorator.
+**998 tests** across **41 files**. `asyncio_mode = "auto"` in pyproject.toml — async tests need no special decorator.
 
 The `settings` fixture in `conftest.py` provides safe defaults with test credentials and in-memory DB.
 
@@ -23,6 +23,8 @@ The `settings` fixture in `conftest.py` provides safe defaults with test credent
 - Network error handling
 - SSL context configuration
 
+> **Note**: 아래 파일별 테스트 수는 릴리즈 시점 스냅샷이며 실제 수치와 다를 수 있습니다. 현재 정확한 수치는 `pytest --collect-only -q`로 확인하세요.
+
 ##### `tests/test_brain.py` (24 tests)
 - Valid JSON parsing and markdown-wrapped JSON handling
 - Malformed JSON fallback
@@ -90,7 +92,7 @@ The `settings` fixture in `conftest.py` provides safe defaults with test credent
 - Python-first filtering pipeline
 - RSI and volume ratio filter logic
 - Candidate scoring and ranking
-- Fallback to static watchlist
+- Fallback to static watchlist (domestic) or dynamic universe (overseas)
 
 #### Context & Memory
 
@@ -138,8 +140,8 @@ The `settings` fixture in `conftest.py` provides safe defaults with test credent
 #### Dashboard
 
 ##### `tests/test_dashboard.py` (14 tests)
-- FastAPI endpoint responses (8 API routes)
-- Status, playbook, scorecard, performance, context, decisions, scenarios
+- FastAPI endpoint responses (10 API routes)
+- Status, playbook, scorecard, performance, context, decisions, scenarios, pnl/history, positions
 - Query parameter handling (market, date, limit)
 
 #### Performance & Quality
@@ -181,6 +183,29 @@ pytest -v --cov=src --cov-report=term-missing
 
 **Note:** `main.py` has lower coverage as it contains the main loop which is tested via integration/manual testing.
 
+## Backtest Automation Gate
+
+백테스트 관련 검증은 `scripts/backtest_gate.sh`와 `.github/workflows/backtest-gate.yml`로 자동 실행된다.
+
+- PR: 변경 파일 기준 `auto` 모드
+- `feature/**` push: 변경 파일 기준 `auto` 모드
+- Daily schedule: `full` 강제 실행
+- Manual dispatch: `mode`(`auto|smoke|full`) 지정 가능
+
+실행 기준:
+- `src/analysis/`, `src/strategy/`, `src/strategies/`, `src/main.py`, `src/markets/`, `src/broker/`
+- 백테스트 핵심 테스트 파일 변경
+- `docs/ouroboros/` 변경
+
+`auto` 모드에서 백테스트 민감 영역 변경이 없으면 게이트는 `skip` 처리되며 실패로 간주하지 않는다.
+
+로컬 수동 실행:
+```bash
+bash scripts/backtest_gate.sh
+BACKTEST_MODE=full bash scripts/backtest_gate.sh
+BASE_REF=origin/feature/v3-session-policy-stream BACKTEST_MODE=auto bash scripts/backtest_gate.sh
+```
+
 ## Test Configuration
 
 ### `pyproject.toml`

docs/workflow.md

@@ -5,14 +5,134 @@
 **CRITICAL: All code changes MUST follow this workflow. Direct pushes to `main` are ABSOLUTELY PROHIBITED.**
 
 1. **Create Gitea Issue First** — All features, bug fixes, and policy changes require a Gitea issue before any code is written
-2. **Create Feature Branch** — Branch from `main` using format `feature/issue-{N}-{short-description}`
-   - After creating the branch, run `git pull origin main` and rebase to ensure the branch is up to date
-3. **Implement Changes** — Write code, tests, and documentation on the feature branch
-4. **Create Pull Request** — Submit PR to `main` branch referencing the issue number
-5. **Review & Merge** — After approval, merge via PR (squash or merge commit)
+2. **Create Program Feature Branch** — Branch from `main` for the whole development stream
+   - Format: `feature/{epic-or-stream-name}`
+3. **Create Ticket Temp Branch** — Branch from the program feature branch per ticket
+   - Format: `feature/issue-{N}-{short-description}`
+4. **Implement Per Ticket** — Write code, tests, and documentation on the ticket temp branch
+5. **Create Pull Request to Program Feature Branch** — `feature/issue-N-* -> feature/{stream}`
+6. **Review/Verify and Merge into Program Feature Branch** — user approval not required
+7. **Final Integration PR to main** — Only after all ticket stages complete and explicit user approval
 
 **Never commit directly to `main`.** This policy applies to all changes, no exceptions.
 
+## Agent Gitea Preflight (Mandatory)
+
+Gitea 이슈/PR/코멘트 작업 전에 모든 에이전트는 아래를 먼저 확인해야 한다.
+
+1. `docs/commands.md`의 `tea CLI` 실패 사례/해결 패턴 확인
+2. 본 문서의 `Gitea CLI Formatting Troubleshooting` 확인
+3. 명령 실행 전 `gh`(GitHub CLI) 사용 금지 확인
+
+강제 규칙:
+- 이 저장소 협업 명령은 `tea`를 기본으로 사용한다.
+- `gh issue`, `gh pr` 등 GitHub CLI 명령은 사용 금지다.
+- `tea` 실패 시 동일 명령 재시도 전에 원인/수정사항을 PR 코멘트에 남긴다.
+- 필요한 경우에만 Gitea API(`localhost:3000`)를 fallback으로 사용한다.
+
+## Session Handover Gate (Mandatory)
+
+새 세션에서 구현/검증을 시작하기 전에 아래를 선행해야 한다.
+
+1. `docs/workflow.md`, `docs/commands.md`, `docs/agent-constraints.md` 재확인
+2. `workflow/session-handover.md`에 최신 세션 엔트리 추가
+3. `python3 scripts/session_handover_check.py --strict` 통과 확인
+
+강제 규칙:
+- handover check 실패 상태에서 코드 수정/이슈 상태 전이/PR 생성 금지
+- 최신 handover 엔트리는 현재 작업 브랜치를 명시해야 한다
+- 최신 handover 엔트리는 당일(UTC) 날짜를 포함해야 한다
+
+## Branch Strategy (Mandatory)
+
+- Team operation default branch is the **program feature branch**, not `main`.
+- Ticket-level development happens only on **ticket temp branches** cut from the program feature branch.
+- Ticket PR merges into program feature branch are allowed after verifier approval.
+- Until final user sign-off, `main` merge is prohibited.
+- 각 에이전트는 주요 의사결정(리뷰 지적, 수정 방향, 검증 승인)마다 PR 코멘트를 적극 작성해 의사결정 과정을 남긴다.
+
+## Backtest Gate Policy (Mandatory)
+
+사람 의존도를 줄이기 위해 백테스트 검증은 자동 게이트를 기본으로 한다.
+
+- 워크플로우: `.github/workflows/backtest-gate.yml`
+- 실행 스크립트: `scripts/backtest_gate.sh`
+- 기본 모드: `auto` (변경 파일 기반 실행/skip 판정)
+- 정기 스케줄: daily `full` 강제 실행
+- 수동 재실행: workflow dispatch + `mode` 지정
+
+강제 규칙:
+- 백테스트 민감 변경(PR/feature push)에서 게이트 실패 시 머지 금지
+- 스케줄 게이트 실패 시 이슈 등록 후 원인/복구 계획 기록
+- `python` 대신 `python3` 기준으로 실행한다
+
+## Gitea CLI Formatting Troubleshooting
+
+Issue/PR 본문 작성 시 줄바꿈(`\n`)이 문자열 그대로 저장되는 문제가 반복될 수 있다. 원인은 `-d "...\n..."` 형태에서 쉘/CLI가 이스케이프를 실제 개행으로 해석하지 않기 때문이다.
+
+코멘트도 동일한 문제가 자주 발생하므로, 코멘트는 파일 기반 래퍼를 표준으로 사용한다.
+
+```bash
+# 권장: 파일/STDIN 기반 코멘트 등록 (줄바꿈 보존)
+cat > /tmp/review.md <<'EOF'
+리뷰 반영 완료했습니다.
+
+- 항목 1
+- 항목 2
+EOF
+
+scripts/tea_comment.sh 374 /tmp/review.md
+# 또는
+cat /tmp/review.md | scripts/tea_comment.sh 374 -
+```
+
+권장 패턴:
+
+```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.**
@@ -75,6 +195,62 @@ task_tool(
 
 Use `run_in_background=True` for independent tasks that don't block subsequent work.
 
+### Main -> Verifier Directive Contract (Mandatory)
+
+메인 에이전트가 검증 에이전트에 작업을 위임할 때, 아래 6개를 누락하면 지시가 무효다.
+
+1. 검증 대상 범위: `REQ-*`, `TASK-*`, 코드/로그 경로
+2. 검증 방법: 실행 커맨드와 관측 포인트(예: 세션별 로그 키워드)
+3. 합격 기준: PASS 조건을 수치/문구로 명시
+4. 실패 기준: FAIL 조건을 수치/문구로 명시
+5. 미관측 기준: `NOT_OBSERVED` 조건과 즉시 에스컬레이션 규칙
+6. 증적 형식: PR 코멘트에 `Coverage Matrix` 표로 제출
+
+`NOT_OBSERVED` 처리 규칙:
+- 요구사항 항목이 관측되지 않았으면 PASS로 간주 금지
+- `NOT_OBSERVED`는 운영상 `FAIL`과 동일하게 처리
+- `NOT_OBSERVED`가 하나라도 있으면 승인/머지 금지
+
+`FORBIDDEN` 처리 규칙:
+- 정책 위반 신호(예: 주말 `session=KRX_REG`)는 `FORBIDDEN=HIT`으로 별도 기록한다
+- `FORBIDDEN=HIT`은 즉시 `P0 FAIL`로 간주하고 모니터링 승인 불가
+- 실시간 모니터는 `alive`만으로 정상 판정하지 않는다(정책 불변식 통과가 필수)
+
+### Process-Change-First Rule (Mandatory)
+
+재발 방지/운영 규칙 변경이 결정되면, 기능 구현 티켓보다 먼저 서버(feature branch)에 반영해야 한다.
+
+- 순서: `process ticket merge` -> `implementation ticket start`
+- process ticket 미반영 상태에서 기능 티켓 코딩/머지 금지
+- 세션 전환 시에도 동일 규칙 유지
+
+### Implementation Start Gate (Mandatory)
+
+구현 티켓을 시작하기 전에 아래 3개를 모두 만족해야 한다.
+
+1. `process ticket merge` 증적 확인 (feature branch 반영 커밋/PR)
+2. `workflow/session-handover.md` 최신 엔트리에 `next_ticket`과 `process_gate_checked` 기록
+3. `python3 scripts/session_handover_check.py --strict` 통과
+
+강제 규칙:
+- 위 3개 중 하나라도 불충족이면 코드/테스트 수정 금지
+- 서브에이전트 지시도 동일하게 제한한다 (`process merged 확인 전 read-only 탐색만 허용`)
+- 성급 착수 발견 시 구현 작업을 즉시 중단하고 handover/proces gate부터 복구한다
+
+### Ticket Maturity Stages (Mandatory)
+
+모든 티켓은 아래 4단계를 순서대로 통과해야 한다.
+
+1. `Implemented`: 코드/문서 변경 완료
+2. `Integrated`: 호출 경로/파이프라인 연결 완료
+3. `Observed`: 런타임/실행 증적 확보 완료
+4. `Accepted`: 정적 Verifier + Runtime Verifier 승인 완료
+
+강제 규칙:
+- 단계 점프 금지 (예: Implemented -> Accepted 금지)
+- `Observed` 전에는 완료 선언 금지
+- `Accepted` 전에는 머지 금지
+
 ## Code Review Checklist
 
 **CRITICAL: Every PR review MUST verify plan-implementation consistency.**
@@ -108,3 +284,10 @@ Before approving any PR, the reviewer (human or agent) must check ALL of the fol
 - [ ] PR references the Gitea issue number
 - [ ] Feature branch follows naming convention (`feature/issue-N-description`)
 - [ ] Commit messages are clear and descriptive
+- [ ] 이슈/PR 작업 전에 `docs/commands.md`와 본 문서 트러블슈팅 섹션을 확인했다
+- [ ] `gh` 명령을 사용하지 않고 `tea`(또는 허용된 Gitea API fallback)만 사용했다
+- [ ] Main -> Verifier 지시가 Directive Contract 6개 항목을 모두 포함한다
+- [ ] Verifier 결과에 `Coverage Matrix`(PASS/FAIL/NOT_OBSERVED)가 있고, `NOT_OBSERVED=0`이다
+- [ ] Process-change-first 대상이면 해당 process PR이 먼저 머지되었다
+- [ ] 티켓 단계가 `Implemented -> Integrated -> Observed -> Accepted` 순서로 기록되었다
+- [ ] 정적 Verifier와 Runtime Verifier 승인 코멘트가 모두 존재한다

scripts/audit_queries.sql

@@ -0,0 +1,184 @@
+-- audit_queries.sql
+-- 용도: 80_implementation_audit.md 성과표 재현을 위한 표준 집계 SQL
+-- 대상 DB: trading.db (SQLite)
+-- 기간: 2026-02-25 ~ 2026-02-28 (UTC)
+-- 참조: docs/ouroboros/80_implementation_audit.md Section 3
+
+------------------------------------------------------------------------
+-- Base: 기간 + LIVE + SELL + 직전 BUY 메타 매칭
+------------------------------------------------------------------------
+-- 모든 후속 쿼리의 기반이 되는 CTE.
+-- prev_buy_rationale: 직전 BUY의 rationale (startup-sync 분류용)
+-- prev_buy_qty: 직전 BUY 수량 (수량 일치 무결성 필터용)
+------------------------------------------------------------------------
+
+WITH base AS (
+  SELECT *
+  FROM trades
+  WHERE mode='live'
+    AND action='SELL'
+    AND timestamp >= '2026-02-25T00:00:00+00:00'
+    AND timestamp <  '2026-02-28T00:00:00+00:00'
+),
+labeled AS (
+  SELECT
+    s.id,
+    s.timestamp,
+    s.stock_code,
+    s.market,
+    s.exchange_code,
+    s.quantity AS sell_qty,
+    s.price AS sell_price,
+    s.pnl,
+    COALESCE((
+      SELECT b.rationale
+      FROM trades b
+      WHERE b.mode='live'
+        AND b.action='BUY'
+        AND b.stock_code=s.stock_code
+        AND b.market=s.market
+        AND b.timestamp < s.timestamp
+      ORDER BY b.timestamp DESC, b.id DESC
+      LIMIT 1
+    ), '') AS prev_buy_rationale,
+    (
+      SELECT b.quantity
+      FROM trades b
+      WHERE b.mode='live'
+        AND b.action='BUY'
+        AND b.stock_code=s.stock_code
+        AND b.market=s.market
+        AND b.timestamp < s.timestamp
+      ORDER BY b.timestamp DESC, b.id DESC
+      LIMIT 1
+    ) AS prev_buy_qty
+  FROM base s
+)
+SELECT * FROM labeled;
+
+------------------------------------------------------------------------
+-- Q1) 통화 분리 손익 (KRW/USD 혼합 금지)
+------------------------------------------------------------------------
+
+WITH base AS (
+  SELECT * FROM trades
+  WHERE mode='live' AND action='SELL'
+    AND timestamp >= '2026-02-25T00:00:00+00:00'
+    AND timestamp <  '2026-02-28T00:00:00+00:00'
+),
+labeled AS (
+  SELECT s.*,
+         s.quantity AS sell_qty,
+         COALESCE((SELECT b.rationale FROM trades b
+                   WHERE b.mode='live' AND b.action='BUY'
+                     AND b.stock_code=s.stock_code AND b.market=s.market
+                     AND b.timestamp < s.timestamp
+                   ORDER BY b.timestamp DESC, b.id DESC LIMIT 1), '') AS prev_buy_rationale,
+         (SELECT b.quantity FROM trades b
+          WHERE b.mode='live' AND b.action='BUY'
+            AND b.stock_code=s.stock_code AND b.market=s.market
+            AND b.timestamp < s.timestamp
+          ORDER BY b.timestamp DESC, b.id DESC LIMIT 1) AS prev_buy_qty
+  FROM base s
+)
+SELECT
+  CASE WHEN market='KR' THEN 'KRW' ELSE 'USD' END AS ccy,
+  COUNT(*) AS sells,
+  ROUND(SUM(pnl),2) AS pnl_sum
+FROM labeled
+GROUP BY ccy
+ORDER BY ccy;
+
+------------------------------------------------------------------------
+-- Q2) 기존 보유(startup-sync) 제외 성과
+------------------------------------------------------------------------
+
+WITH base AS (
+  SELECT * FROM trades
+  WHERE mode='live' AND action='SELL'
+    AND timestamp >= '2026-02-25T00:00:00+00:00'
+    AND timestamp <  '2026-02-28T00:00:00+00:00'
+),
+labeled AS (
+  SELECT s.*,
+         s.quantity AS sell_qty,
+         COALESCE((SELECT b.rationale FROM trades b
+                   WHERE b.mode='live' AND b.action='BUY'
+                     AND b.stock_code=s.stock_code AND b.market=s.market
+                     AND b.timestamp < s.timestamp
+                   ORDER BY b.timestamp DESC, b.id DESC LIMIT 1), '') AS prev_buy_rationale,
+         (SELECT b.quantity FROM trades b
+          WHERE b.mode='live' AND b.action='BUY'
+            AND b.stock_code=s.stock_code AND b.market=s.market
+            AND b.timestamp < s.timestamp
+          ORDER BY b.timestamp DESC, b.id DESC LIMIT 1) AS prev_buy_qty
+  FROM base s
+)
+SELECT
+  CASE WHEN market='KR' THEN 'KRW' ELSE 'USD' END AS ccy,
+  COUNT(*) AS sells,
+  ROUND(SUM(pnl),2) AS pnl_sum
+FROM labeled
+WHERE prev_buy_rationale NOT LIKE '[startup-sync]%'
+GROUP BY ccy
+ORDER BY ccy;
+
+------------------------------------------------------------------------
+-- Q3) 수량 일치 체결만 포함 (무결성 필터)
+------------------------------------------------------------------------
+
+WITH base AS (
+  SELECT * FROM trades
+  WHERE mode='live' AND action='SELL'
+    AND timestamp >= '2026-02-25T00:00:00+00:00'
+    AND timestamp <  '2026-02-28T00:00:00+00:00'
+),
+labeled AS (
+  SELECT s.*,
+         s.quantity AS sell_qty,
+         COALESCE((SELECT b.rationale FROM trades b
+                   WHERE b.mode='live' AND b.action='BUY'
+                     AND b.stock_code=s.stock_code AND b.market=s.market
+                     AND b.timestamp < s.timestamp
+                   ORDER BY b.timestamp DESC, b.id DESC LIMIT 1), '') AS prev_buy_rationale,
+         (SELECT b.quantity FROM trades b
+          WHERE b.mode='live' AND b.action='BUY'
+            AND b.stock_code=s.stock_code AND b.market=s.market
+            AND b.timestamp < s.timestamp
+          ORDER BY b.timestamp DESC, b.id DESC LIMIT 1) AS prev_buy_qty
+  FROM base s
+)
+SELECT
+  CASE WHEN market='KR' THEN 'KRW' ELSE 'USD' END AS ccy,
+  COUNT(*) AS sells,
+  ROUND(SUM(pnl),2) AS pnl_sum
+FROM labeled
+WHERE prev_buy_qty = sell_qty
+GROUP BY ccy
+ORDER BY ccy;
+
+------------------------------------------------------------------------
+-- Q4) 이상치 목록 (수량 불일치)
+------------------------------------------------------------------------
+
+WITH base AS (
+  SELECT * FROM trades
+  WHERE mode='live' AND action='SELL'
+    AND timestamp >= '2026-02-25T00:00:00+00:00'
+    AND timestamp <  '2026-02-28T00:00:00+00:00'
+),
+labeled AS (
+  SELECT s.id, s.timestamp, s.stock_code, s.market, s.quantity AS sell_qty, s.pnl,
+         (SELECT b.quantity FROM trades b
+          WHERE b.mode='live' AND b.action='BUY'
+            AND b.stock_code=s.stock_code AND b.market=s.market
+            AND b.timestamp < s.timestamp
+          ORDER BY b.timestamp DESC, b.id DESC LIMIT 1) AS prev_buy_qty
+  FROM base s
+)
+SELECT
+  id, timestamp, stock_code, market, sell_qty, prev_buy_qty, ROUND(pnl,2) AS pnl
+FROM labeled
+WHERE prev_buy_qty IS NOT NULL
+  AND prev_buy_qty != sell_qty
+ORDER BY ABS(pnl) DESC;

scripts/backtest_gate.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# Backtest gate for PR/push/scheduled verification.
+
+set -euo pipefail
+
+MODE="${BACKTEST_MODE:-auto}"          # auto | smoke | full
+BASE_REF="${BASE_REF:-origin/main}"    # used when MODE=auto
+FORCE_FULL="${FORCE_FULL_BACKTEST:-false}"
+LOG_DIR="${LOG_DIR:-data/backtest-gate}"
+
+mkdir -p "$LOG_DIR"
+STAMP="$(date -u +%Y%m%d_%H%M%S)"
+LOG_FILE="$LOG_DIR/backtest_gate_${STAMP}.log"
+
+log() {
+  printf '%s %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$1" | tee -a "$LOG_FILE"
+}
+
+run_cmd() {
+  log "[RUN] $*"
+  "$@" 2>&1 | tee -a "$LOG_FILE"
+}
+
+resolve_mode_from_changes() {
+  if [ "$FORCE_FULL" = "true" ]; then
+    echo "full"
+    return
+  fi
+
+  if ! git rev-parse --verify "$BASE_REF" >/dev/null 2>&1; then
+    log "[WARN] BASE_REF not found: $BASE_REF; fallback to full"
+    echo "full"
+    return
+  fi
+
+  changed_files="$(git diff --name-only "$BASE_REF"...HEAD || true)"
+  if [ -z "$changed_files" ]; then
+    log "[INFO] no changed files between $BASE_REF...HEAD; skip backtest gate"
+    echo "skip"
+    return
+  fi
+
+  log "[INFO] changed files from $BASE_REF...HEAD:"
+  while IFS= read -r line; do
+    [ -n "$line" ] && log "  - $line"
+  done <<< "$changed_files"
+
+  # Backtest-sensitive areas: analysis/strategy/runtime execution semantics.
+  if printf '%s\n' "$changed_files" | rg -q \
+    '^(src/analysis/|src/strategy/|src/strategies/|src/main.py|src/markets/|src/broker/|tests/test_backtest_|tests/test_triple_barrier.py|tests/test_walk_forward_split.py|tests/test_main.py|docs/ouroboros/)'
+  then
+    echo "full"
+  else
+    echo "skip"
+  fi
+}
+
+SMOKE_TESTS=(
+  tests/test_backtest_pipeline_integration.py
+  tests/test_triple_barrier.py
+  tests/test_walk_forward_split.py
+  tests/test_backtest_cost_guard.py
+  tests/test_backtest_execution_model.py
+)
+
+FULL_TESTS=(
+  tests/test_backtest_pipeline_integration.py
+  tests/test_triple_barrier.py
+  tests/test_walk_forward_split.py
+  tests/test_backtest_cost_guard.py
+  tests/test_backtest_execution_model.py
+  tests/test_main.py
+)
+
+main() {
+  log "[INFO] backtest gate started mode=$MODE base_ref=$BASE_REF force_full=$FORCE_FULL"
+
+  selected_mode="$MODE"
+  if [ "$MODE" = "auto" ]; then
+    selected_mode="$(resolve_mode_from_changes)"
+  fi
+
+  case "$selected_mode" in
+    skip)
+      log "[PASS] backtest gate skipped (no backtest-sensitive changes)"
+      exit 0
+      ;;
+    smoke)
+      run_cmd python3 -m pytest -q "${SMOKE_TESTS[@]}"
+      log "[PASS] smoke backtest gate passed"
+      ;;
+    full)
+      run_cmd python3 -m pytest -q "${SMOKE_TESTS[@]}"
+      # Runtime semantics tied to v2 staged-exit must remain covered in full gate.
+      run_cmd python3 -m pytest -q tests/test_main.py -k \
+        "staged_exit_override or runtime_exit_cache_cleared or run_daily_session_applies_staged_exit_override_on_hold"
+      log "[PASS] full backtest gate passed"
+      ;;
+    *)
+      log "[FAIL] invalid BACKTEST_MODE=$selected_mode (expected auto|smoke|full)"
+      exit 2
+      ;;
+  esac
+}
+
+main "$@"

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"

scripts/runtime_verify_monitor.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# Runtime verification monitor with coverage + forbidden invariant checks.
+
+set -euo pipefail
+
+ROOT_DIR="${ROOT_DIR:-/home/agentson/repos/The-Ouroboros}"
+LOG_DIR="${LOG_DIR:-$ROOT_DIR/data/overnight}"
+INTERVAL_SEC="${INTERVAL_SEC:-60}"
+MAX_HOURS="${MAX_HOURS:-24}"
+POLICY_TZ="${POLICY_TZ:-Asia/Seoul}"
+
+cd "$ROOT_DIR"
+
+OUT_LOG="$LOG_DIR/runtime_verify_$(date +%Y%m%d_%H%M%S).log"
+END_TS=$(( $(date +%s) + MAX_HOURS*3600 ))
+
+log() {
+  printf '%s %s\n' "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$1" | tee -a "$OUT_LOG" >/dev/null
+}
+
+check_signal() {
+  local name="$1"
+  local pattern="$2"
+  local run_log="$3"
+
+  if rg -q "$pattern" "$run_log"; then
+    log "[COVERAGE] ${name}=PASS pattern=${pattern}"
+    return 0
+  fi
+  log "[COVERAGE] ${name}=NOT_OBSERVED pattern=${pattern}"
+  return 1
+}
+
+check_forbidden() {
+  local name="$1"
+  local pattern="$2"
+  local run_log="$3"
+
+  if rg -q "$pattern" "$run_log"; then
+    log "[FORBIDDEN] ${name}=HIT pattern=${pattern}"
+    return 1
+  fi
+  log "[FORBIDDEN] ${name}=CLEAR pattern=${pattern}"
+  return 0
+}
+
+log "[INFO] runtime verify monitor started interval=${INTERVAL_SEC}s max_hours=${MAX_HOURS} policy_tz=${POLICY_TZ}"
+
+while true; do
+  now=$(date +%s)
+  if [ "$now" -ge "$END_TS" ]; then
+    log "[INFO] monitor completed (time window reached)"
+    exit 0
+  fi
+
+  latest_run="$(ls -t "$LOG_DIR"/run_*.log 2>/dev/null | head -n1 || true)"
+  if [ -z "$latest_run" ]; then
+    log "[ANOMALY] no run log found"
+    sleep "$INTERVAL_SEC"
+    continue
+  fi
+
+  # Basic liveness hints.
+  app_pid="$(cat "$LOG_DIR/app.pid" 2>/dev/null || true)"
+  wd_pid="$(cat "$LOG_DIR/watchdog.pid" 2>/dev/null || true)"
+  app_alive=0
+  wd_alive=0
+  port_alive=0
+  [ -n "$app_pid" ] && kill -0 "$app_pid" 2>/dev/null && app_alive=1
+  [ -n "$wd_pid" ] && kill -0 "$wd_pid" 2>/dev/null && wd_alive=1
+  ss -ltnp 2>/dev/null | rg -q ':8080' && port_alive=1
+  log "[HEARTBEAT] run_log=$latest_run app_alive=$app_alive watchdog_alive=$wd_alive port8080=$port_alive"
+
+  # Coverage matrix rows (session paths and policy gate evidence).
+  not_observed=0
+  check_signal "LIVE_MODE" "Mode: live" "$latest_run" || not_observed=$((not_observed+1))
+  check_signal "KR_LOOP" "Processing market: Korea Exchange" "$latest_run" || not_observed=$((not_observed+1))
+  check_signal "NXT_PATH" "NXT_PRE|NXT_AFTER|session=NXT_" "$latest_run" || not_observed=$((not_observed+1))
+  check_signal "US_PRE_PATH" "US_PRE|session=US_PRE" "$latest_run" || not_observed=$((not_observed+1))
+  check_signal "US_DAY_PATH" "US_DAY|session=US_DAY|Processing market: .*NASDAQ|Processing market: .*NYSE|Processing market: .*AMEX" "$latest_run" || not_observed=$((not_observed+1))
+  check_signal "US_AFTER_PATH" "US_AFTER|session=US_AFTER" "$latest_run" || not_observed=$((not_observed+1))
+  check_signal "ORDER_POLICY_SESSION" "Order policy rejected .*\\[session=" "$latest_run" || not_observed=$((not_observed+1))
+
+  if [ "$not_observed" -gt 0 ]; then
+    log "[ANOMALY] coverage_not_observed=$not_observed (treat as FAIL)"
+  else
+    log "[OK] coverage complete (NOT_OBSERVED=0)"
+  fi
+
+  # Forbidden invariants: must never happen under given policy context.
+  forbidden_hits=0
+  policy_dow="$(TZ="$POLICY_TZ" date +%u)" # 1..7 (Mon..Sun)
+  is_weekend=0
+  if [ "$policy_dow" -ge 6 ]; then
+    is_weekend=1
+  fi
+
+  if [ "$is_weekend" -eq 1 ]; then
+    # Weekend policy: KR regular session loop must never appear.
+    check_forbidden "WEEKEND_KR_SESSION_ACTIVE" \
+      "Market session active: KR|session=KRX_REG|Processing market: Korea Exchange" \
+      "$latest_run" || forbidden_hits=$((forbidden_hits+1))
+  else
+    log "[FORBIDDEN] WEEKEND_KR_SESSION_ACTIVE=SKIP reason=weekday"
+  fi
+
+  if [ "$forbidden_hits" -gt 0 ]; then
+    log "[P0] forbidden_invariant_hits=$forbidden_hits (treat as immediate FAIL)"
+  else
+    log "[OK] forbidden invariants clear"
+  fi
+
+  sleep "$INTERVAL_SEC"
+done

scripts/session_handover_check.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""Session handover preflight gate.
+
+This script enforces a minimal handover record per working branch so that
+new sessions cannot start implementation without reading the required docs
+and recording current intent.
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+
+REQUIRED_DOCS = (
+    Path("docs/workflow.md"),
+    Path("docs/commands.md"),
+    Path("docs/agent-constraints.md"),
+)
+HANDOVER_LOG = Path("workflow/session-handover.md")
+
+
+def _run_git(*args: str) -> str:
+    try:
+        return (
+            subprocess.check_output(["git", *args], stderr=subprocess.DEVNULL)
+            .decode("utf-8")
+            .strip()
+        )
+    except Exception:
+        return ""
+
+
+def _current_branch() -> str:
+    branch = _run_git("branch", "--show-current")
+    if branch:
+        return branch
+    return _run_git("rev-parse", "--abbrev-ref", "HEAD")
+
+
+def _latest_entry(text: str) -> str:
+    chunks = text.split("\n### ")
+    if not chunks:
+        return ""
+    if chunks[0].startswith("### "):
+        chunks[0] = chunks[0][4:]
+    latest = chunks[-1].strip()
+    if not latest:
+        return ""
+    if not latest.startswith("### "):
+        latest = f"### {latest}"
+    return latest
+
+
+def _check_required_files(errors: list[str]) -> None:
+    for path in REQUIRED_DOCS:
+        if not path.exists():
+            errors.append(f"missing required document: {path}")
+    if not HANDOVER_LOG.exists():
+        errors.append(f"missing handover log: {HANDOVER_LOG}")
+
+
+def _check_handover_entry(
+    *,
+    branch: str,
+    strict: bool,
+    ci_mode: bool,
+    errors: list[str],
+) -> None:
+    if not HANDOVER_LOG.exists():
+        return
+    text = HANDOVER_LOG.read_text(encoding="utf-8")
+    latest = _latest_entry(text)
+    if not latest:
+        errors.append("handover log has no session entry")
+        return
+
+    required_tokens = (
+        "- branch:",
+        "- docs_checked:",
+        "- open_issues_reviewed:",
+        "- next_ticket:",
+        "- process_gate_checked:",
+    )
+    for token in required_tokens:
+        if token not in latest:
+            errors.append(f"latest handover entry missing token: {token}")
+
+    if strict:
+        if "- next_ticket: #TBD" in latest:
+            errors.append("latest handover entry must not use placeholder next_ticket (#TBD)")
+
+    if strict and not ci_mode:
+        today_utc = datetime.now(UTC).date().isoformat()
+        if today_utc not in latest:
+            errors.append(
+                f"latest handover entry must contain today's UTC date ({today_utc})"
+            )
+        branch_token = f"- branch: {branch}"
+        if branch_token not in latest:
+            errors.append(
+                "latest handover entry must target current branch "
+                f"({branch_token})"
+            )
+        if "merged_to_feature_branch=no" in latest:
+            errors.append(
+                "process gate indicates not merged; implementation must stay blocked "
+                "(merged_to_feature_branch=no)"
+            )
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Validate session handover gate requirements."
+    )
+    parser.add_argument(
+        "--strict",
+        action="store_true",
+        help="Enforce today-date and current-branch match on latest handover entry.",
+    )
+    parser.add_argument(
+        "--ci",
+        action="store_true",
+        help=(
+            "CI mode: keep structural/token checks and placeholder guard, "
+            "but skip strict today-date/current-branch/merge-gate checks."
+        ),
+    )
+    args = parser.parse_args()
+
+    errors: list[str] = []
+    _check_required_files(errors)
+
+    branch = _current_branch()
+    if not branch:
+        errors.append("cannot resolve current git branch")
+    elif not args.ci and branch in {"main", "master"}:
+        errors.append(f"working branch must not be {branch}")
+
+    _check_handover_entry(
+        branch=branch,
+        strict=args.strict,
+        ci_mode=args.ci,
+        errors=errors,
+    )
+
+    if errors:
+        print("[FAIL] session handover check failed")
+        for err in errors:
+            print(f"- {err}")
+        return 1
+
+    print("[OK] session handover check passed")
+    print(f"[OK] branch={branch}")
+    print(f"[OK] handover_log={HANDOVER_LOG}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/tea_comment.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# Safe helper for posting multiline Gitea comments without escaped-newline artifacts.
+
+set -euo pipefail
+
+if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ] || [ "$#" -lt 2 ]; then
+  cat <<'EOF'
+Usage:
+  scripts/tea_comment.sh <issue_or_pr_index> <body_file|-> [repo]
+
+Examples:
+  scripts/tea_comment.sh 374 /tmp/comment.md
+  cat /tmp/comment.md | scripts/tea_comment.sh 374 - jihoson/The-Ouroboros
+
+Notes:
+  - Use file/stdin input to preserve real newlines.
+  - Passing inline strings with "\n" is intentionally avoided by this helper.
+EOF
+  exit 1
+fi
+
+INDEX="$1"
+BODY_SOURCE="$2"
+REPO="${3:-jihoson/The-Ouroboros}"
+
+if [ "$BODY_SOURCE" = "-" ]; then
+  BODY="$(cat)"
+else
+  if [ ! -f "$BODY_SOURCE" ]; then
+    echo "[FAIL] body file not found: $BODY_SOURCE" >&2
+    exit 1
+  fi
+  BODY="$(cat "$BODY_SOURCE")"
+fi
+
+if [ -z "$BODY" ]; then
+  echo "[FAIL] empty comment body" >&2
+  exit 1
+fi
+
+# Guard against the common escaped-newline mistake.
+if [[ "$BODY" == *"\\n"* ]] && [[ "$BODY" != *$'\n'* ]]; then
+  echo "[FAIL] body appears to contain escaped newlines (\\n) instead of real line breaks" >&2
+  echo "Use a multiline file/heredoc and pass that file to scripts/tea_comment.sh" >&2
+  exit 1
+fi
+
+YES="" ~/bin/tea comment "$INDEX" --repo "$REPO" "$BODY"
+

scripts/validate_docs_sync.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Validate top-level docs synchronization invariants."""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(".")
+REQUIRED_FILES = {
+    "README.md": REPO_ROOT / "README.md",
+    "CLAUDE.md": REPO_ROOT / "CLAUDE.md",
+    "commands": REPO_ROOT / "docs" / "commands.md",
+    "testing": REPO_ROOT / "docs" / "testing.md",
+    "workflow": REPO_ROOT / "docs" / "workflow.md",
+}
+
+LINK_PATTERN = re.compile(r"\[[^\]]+\]\((?P<link>[^)]+)\)")
+ENDPOINT_ROW_PATTERN = re.compile(
+    r"^\|\s*`(?P<endpoint>(?:GET|POST|PUT|PATCH|DELETE)\s+/[^`]*)`\s*\|"
+)
+
+
+def _read(path: Path) -> str:
+    return path.read_text(encoding="utf-8")
+
+
+def validate_required_files_exist(errors: list[str]) -> None:
+    for name, path in REQUIRED_FILES.items():
+        if not path.exists():
+            errors.append(f"missing required doc file ({name}): {path}")
+
+
+def validate_links_resolve(doc_path: Path, text: str, errors: list[str]) -> None:
+    for match in LINK_PATTERN.finditer(text):
+        raw_link = match.group("link").strip()
+        if not raw_link or raw_link.startswith("#") or raw_link.startswith("http"):
+            continue
+        link_path = raw_link.split("#", 1)[0].strip()
+        if not link_path:
+            continue
+        if link_path.startswith("/"):
+            errors.append(f"{doc_path}: absolute link is forbidden -> {raw_link}")
+            continue
+        target = (doc_path.parent / link_path).resolve()
+        if not target.exists():
+            errors.append(f"{doc_path}: broken link -> {raw_link}")
+
+
+def validate_summary_docs_reference_core_docs(errors: list[str]) -> None:
+    required_links = {
+        "README.md": ("docs/workflow.md", "docs/commands.md", "docs/testing.md"),
+        "CLAUDE.md": ("docs/workflow.md", "docs/commands.md"),
+    }
+    for file_name, links in required_links.items():
+        doc_path = REQUIRED_FILES[file_name]
+        text = _read(doc_path)
+        for link in links:
+            if link not in text:
+                errors.append(f"{doc_path}: missing core doc link reference -> {link}")
+
+
+def collect_command_endpoints(text: str) -> list[str]:
+    endpoints: list[str] = []
+    for line in text.splitlines():
+        match = ENDPOINT_ROW_PATTERN.match(line.strip())
+        if match:
+            endpoints.append(match.group("endpoint"))
+    return endpoints
+
+
+def validate_commands_endpoint_duplicates(errors: list[str]) -> None:
+    text = _read(REQUIRED_FILES["commands"])
+    endpoints = collect_command_endpoints(text)
+    seen: set[str] = set()
+    duplicates: set[str] = set()
+    for endpoint in endpoints:
+        if endpoint in seen:
+            duplicates.add(endpoint)
+        seen.add(endpoint)
+    for endpoint in sorted(duplicates):
+        errors.append(f"docs/commands.md: duplicated API endpoint row -> {endpoint}")
+
+
+def validate_testing_doc_has_dynamic_count_guidance(errors: list[str]) -> None:
+    text = _read(REQUIRED_FILES["testing"])
+    if "pytest --collect-only -q" not in text:
+        errors.append(
+            "docs/testing.md: missing dynamic test count guidance "
+            "(pytest --collect-only -q)"
+        )
+
+
+def main() -> int:
+    errors: list[str] = []
+
+    validate_required_files_exist(errors)
+    if errors:
+        print("[FAIL] docs sync validation failed")
+        for err in errors:
+            print(f"- {err}")
+        return 1
+
+    readme_text = _read(REQUIRED_FILES["README.md"])
+    claude_text = _read(REQUIRED_FILES["CLAUDE.md"])
+    validate_links_resolve(REQUIRED_FILES["README.md"], readme_text, errors)
+    validate_links_resolve(REQUIRED_FILES["CLAUDE.md"], claude_text, errors)
+    validate_links_resolve(
+        REQUIRED_FILES["commands"], _read(REQUIRED_FILES["commands"]), errors
+    )
+    validate_links_resolve(REQUIRED_FILES["testing"], _read(REQUIRED_FILES["testing"]), errors)
+    validate_links_resolve(
+        REQUIRED_FILES["workflow"], _read(REQUIRED_FILES["workflow"]), errors
+    )
+
+    validate_summary_docs_reference_core_docs(errors)
+    validate_commands_endpoint_duplicates(errors)
+    validate_testing_doc_has_dynamic_count_guidance(errors)
+
+    if errors:
+        print("[FAIL] docs sync validation failed")
+        for err in errors:
+            print(f"- {err}")
+        return 1
+
+    print("[OK] docs sync validated")
+    print("[OK] summary docs link to core docs and links resolve")
+    print("[OK] commands endpoint rows have no duplicates")
+    print("[OK] testing doc includes dynamic count guidance")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/validate_governance_assets.py

@@ -0,0 +1,305 @@
+#!/usr/bin/env python3
+"""Validate persistent governance assets for agent workflow safety."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+REQUIREMENTS_REGISTRY = "docs/ouroboros/01_requirements_registry.md"
+TASK_WORK_ORDERS_DOC = "docs/ouroboros/30_code_level_work_orders.md"
+TASK_DEF_LINE = re.compile(r"^-\s+`(?P<task_id>TASK-[A-Z0-9-]+-\d{3})`(?P<body>.*)$")
+REQ_ID_IN_LINE = re.compile(r"\bREQ-[A-Z0-9-]+-\d{3}\b")
+TASK_ID_IN_TEXT = re.compile(r"\bTASK-[A-Z0-9-]+-\d{3}\b")
+TEST_ID_IN_TEXT = re.compile(r"\bTEST-[A-Z0-9-]+-\d{3}\b")
+READ_ONLY_FILES = {"src/core/risk_manager.py"}
+PLACEHOLDER_VALUES = {"", "tbd", "n/a", "na", "none", "<link>", "<required>"}
+TIMEZONE_TOKEN_PATTERN = re.compile(r"\b(?:KST|UTC)\b")
+
+
+def must_contain(path: Path, required: list[str], errors: list[str]) -> None:
+    if not path.exists():
+        errors.append(f"missing file: {path}")
+        return
+    text = path.read_text(encoding="utf-8")
+    for token in required:
+        if token not in text:
+            errors.append(f"{path}: missing required token -> {token}")
+
+
+def normalize_changed_path(path: str) -> str:
+    normalized = path.strip().replace("\\", "/")
+    if normalized.startswith("./"):
+        normalized = normalized[2:]
+    return normalized
+
+
+def is_policy_file(path: str) -> bool:
+    normalized = normalize_changed_path(path)
+    if not normalized.endswith(".md"):
+        return False
+    if not normalized.startswith("docs/ouroboros/"):
+        return False
+    return normalized != REQUIREMENTS_REGISTRY
+
+
+def load_changed_files(args: list[str], errors: list[str]) -> list[str]:
+    if not args:
+        return []
+
+    # Single range input (e.g. BASE..HEAD or BASE...HEAD)
+    if len(args) == 1 and ".." in args[0]:
+        range_spec = args[0]
+        try:
+            completed = subprocess.run(
+                ["git", "diff", "--name-only", range_spec],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+        except (subprocess.CalledProcessError, FileNotFoundError) as exc:
+            errors.append(f"failed to load changed files from range '{range_spec}': {exc}")
+            return []
+        return [
+            normalize_changed_path(line)
+            for line in completed.stdout.splitlines()
+            if line.strip()
+        ]
+
+    return [normalize_changed_path(path) for path in args if path.strip()]
+
+
+def validate_registry_sync(changed_files: list[str], errors: list[str]) -> None:
+    if not changed_files:
+        return
+
+    changed_set = set(changed_files)
+    policy_changed = any(is_policy_file(path) for path in changed_set)
+    registry_changed = REQUIREMENTS_REGISTRY in changed_set
+    if policy_changed and not registry_changed:
+        errors.append(
+            "policy file changed without updating docs/ouroboros/01_requirements_registry.md"
+        )
+
+
+def validate_task_req_mapping(errors: list[str], *, task_doc: Path | None = None) -> None:
+    path = task_doc or Path(TASK_WORK_ORDERS_DOC)
+    if not path.exists():
+        errors.append(f"missing file: {path}")
+        return
+
+    text = path.read_text(encoding="utf-8")
+    found_task = False
+    for line in text.splitlines():
+        m = TASK_DEF_LINE.match(line.strip())
+        if not m:
+            continue
+        found_task = True
+        if not REQ_ID_IN_LINE.search(m.group("body")):
+            errors.append(
+                f"{path}: TASK without REQ mapping -> {m.group('task_id')}"
+            )
+    if not found_task:
+        errors.append(f"{path}: no TASK definitions found")
+
+
+def validate_task_test_pairing(errors: list[str], *, task_doc: Path | None = None) -> None:
+    """Fail when TASK definitions are not linked to at least one TEST id."""
+    path = task_doc or Path(TASK_WORK_ORDERS_DOC)
+    if not path.exists():
+        errors.append(f"missing file: {path}")
+        return
+
+    text = path.read_text(encoding="utf-8")
+    found_task = False
+    for line in text.splitlines():
+        m = TASK_DEF_LINE.match(line.strip())
+        if not m:
+            continue
+        found_task = True
+        if not TEST_ID_IN_TEXT.search(m.group("body")):
+            errors.append(f"{path}: TASK without TEST mapping -> {m.group('task_id')}")
+    if not found_task:
+        errors.append(f"{path}: no TASK definitions found")
+
+
+def validate_timezone_policy_tokens(errors: list[str]) -> None:
+    """Fail-fast check for REQ-OPS-001 governance tokens."""
+    required_docs = [
+        Path("docs/ouroboros/01_requirements_registry.md"),
+        Path("docs/ouroboros/30_code_level_work_orders.md"),
+        Path("docs/workflow.md"),
+    ]
+    for path in required_docs:
+        if not path.exists():
+            errors.append(f"missing file: {path}")
+            continue
+        text = path.read_text(encoding="utf-8")
+        if not TIMEZONE_TOKEN_PATTERN.search(text):
+            errors.append(f"{path}: missing timezone policy token (KST/UTC)")
+
+
+def validate_pr_traceability(errors: list[str]) -> None:
+    title = os.getenv("GOVERNANCE_PR_TITLE", "").strip()
+    body = os.getenv("GOVERNANCE_PR_BODY", "").strip()
+    if not title and not body:
+        return
+
+    text = f"{title}\n{body}"
+    if not REQ_ID_IN_LINE.search(text):
+        errors.append("PR text missing REQ-ID reference")
+    if not TASK_ID_IN_TEXT.search(text):
+        errors.append("PR text missing TASK-ID reference")
+    if not TEST_ID_IN_TEXT.search(text):
+        errors.append("PR text missing TEST-ID reference")
+
+
+def _parse_pr_evidence_line(text: str, field: str) -> str | None:
+    pattern = re.compile(rf"^\s*-\s*{re.escape(field)}:\s*(?P<value>.+?)\s*$", re.MULTILINE)
+    match = pattern.search(text)
+    if not match:
+        return None
+    return match.group("value").strip()
+
+
+def _is_placeholder(value: str | None) -> bool:
+    if value is None:
+        return True
+    normalized = value.strip().lower()
+    return normalized in PLACEHOLDER_VALUES
+
+
+def validate_read_only_approval(
+    changed_files: list[str], errors: list[str], warnings: list[str]
+) -> None:
+    changed_set = set(changed_files)
+    touched = sorted(path for path in READ_ONLY_FILES if path in changed_set)
+    if not touched:
+        return
+
+    body = os.getenv("GOVERNANCE_PR_BODY", "").strip()
+    if not body:
+        errors.append(
+            "READ-ONLY file changed but PR body is unavailable; approval evidence is required"
+        )
+        return
+
+    if "READ-ONLY Approval" not in body:
+        errors.append("READ-ONLY file changed without 'READ-ONLY Approval' section in PR body")
+        return
+
+    touched_field = _parse_pr_evidence_line(body, "Touched READ-ONLY files")
+    human_approval = _parse_pr_evidence_line(body, "Human approval")
+    test_suite_1 = _parse_pr_evidence_line(body, "Test suite 1")
+    test_suite_2 = _parse_pr_evidence_line(body, "Test suite 2")
+
+    if _is_placeholder(touched_field):
+        errors.append("READ-ONLY Approval section missing 'Touched READ-ONLY files' evidence")
+    if _is_placeholder(human_approval):
+        errors.append("READ-ONLY Approval section missing 'Human approval' evidence")
+    if _is_placeholder(test_suite_1):
+        errors.append("READ-ONLY Approval section missing 'Test suite 1' evidence")
+    if _is_placeholder(test_suite_2):
+        errors.append("READ-ONLY Approval section missing 'Test suite 2' evidence")
+
+
+def main() -> int:
+    errors: list[str] = []
+    warnings: list[str] = []
+    changed_files = load_changed_files(sys.argv[1:], errors)
+
+    pr_template = Path(".gitea/PULL_REQUEST_TEMPLATE.md")
+    issue_template = Path(".gitea/ISSUE_TEMPLATE/runtime_verification.md")
+    workflow_doc = Path("docs/workflow.md")
+    commands_doc = Path("docs/commands.md")
+    handover_script = Path("scripts/session_handover_check.py")
+    handover_log = Path("workflow/session-handover.md")
+
+    must_contain(
+        pr_template,
+        [
+            "Closes #N",
+            "Main -> Verifier Directive Contract",
+            "Coverage Matrix",
+            "NOT_OBSERVED",
+            "tea",
+            "gh",
+            "Session Handover Gate",
+            "session_handover_check.py --strict",
+            "READ-ONLY Approval",
+            "Touched READ-ONLY files",
+            "Human approval",
+            "Test suite 1",
+            "Test suite 2",
+        ],
+        errors,
+    )
+    must_contain(
+        issue_template,
+        [
+            "[RUNTIME-VERIFY][SCN-XXX]",
+            "Requirement Mapping",
+            "Close Criteria",
+            "NOT_OBSERVED = 0",
+        ],
+        errors,
+    )
+    must_contain(
+        workflow_doc,
+        [
+            "Session Handover Gate (Mandatory)",
+            "session_handover_check.py --strict",
+            "scripts/tea_comment.sh",
+        ],
+        errors,
+    )
+    must_contain(
+        commands_doc,
+        [
+            "Session Handover Preflight (Mandatory)",
+            "session_handover_check.py --strict",
+            "Comment Newline Escaping",
+            "scripts/tea_comment.sh",
+        ],
+        errors,
+    )
+    must_contain(
+        handover_log,
+        [
+            "Session Handover Log",
+            "- branch:",
+            "- docs_checked:",
+            "- open_issues_reviewed:",
+            "- next_ticket:",
+        ],
+        errors,
+    )
+    if not handover_script.exists():
+        errors.append(f"missing file: {handover_script}")
+
+    validate_registry_sync(changed_files, errors)
+    validate_task_req_mapping(errors)
+    validate_task_test_pairing(errors)
+    validate_timezone_policy_tokens(errors)
+    validate_pr_traceability(errors)
+    validate_read_only_approval(changed_files, errors, warnings)
+
+    if errors:
+        print("[FAIL] governance asset validation failed")
+        for err in errors:
+            print(f"- {err}")
+        return 1
+
+    print("[OK] governance assets validated")
+    if warnings:
+        print(f"[WARN] governance advisory: {len(warnings)}")
+        for warn in warnings:
+            print(f"- {warn}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

scripts/validate_ouroboros_docs.py

@@ -0,0 +1,185 @@
+#!/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,
+)
+PLAN_LINK_PATTERN = re.compile(r"ouroboros_plan_v(?P<version>[23])\.txt$")
+ALLOWED_PLAN_TARGETS = {
+    "2": (DOC_DIR / "source" / "ouroboros_plan_v2.txt").resolve(),
+    "3": (DOC_DIR / "source" / "ouroboros_plan_v3.txt").resolve(),
+}
+
+
+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_plan_source_link(path: Path, link: str, errors: list[str]) -> bool:
+    normalized = link.strip()
+    # Ignore in-page anchors and parse the filesystem part for validation.
+    link_path = normalized.split("#", 1)[0].strip()
+    if not link_path:
+        return False
+    match = PLAN_LINK_PATTERN.search(link_path)
+    if not match:
+        return False
+
+    version = match.group("version")
+    expected_target = ALLOWED_PLAN_TARGETS[version]
+    if link_path.startswith("/"):
+        errors.append(
+            f"{path}: invalid plan link path -> {link} "
+            f"(use ./source/ouroboros_plan_v{version}.txt)"
+        )
+        return True
+
+    resolved_target = (path.parent / link_path).resolve()
+    if resolved_target != expected_target:
+        errors.append(
+            f"{path}: invalid plan link path -> {link} "
+            f"(must resolve to docs/ouroboros/source/ouroboros_plan_v{version}.txt)"
+        )
+        return True
+    return False
+
+
+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 validate_plan_source_link(path, link, errors):
+            continue
+        link_path = link.split("#", 1)[0].strip()
+        if link_path.startswith("/"):
+            target = Path(link_path)
+        else:
+            target = (path.parent / link_path).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())

src/analysis/backtest_cost_guard.py

@@ -0,0 +1,64 @@
+"""Backtest cost/slippage/failure validation guard."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class BacktestCostModel:
+    commission_bps: float | None = None
+    slippage_bps_by_session: dict[str, float] | None = None
+    failure_rate_by_session: dict[str, float] | None = None
+    partial_fill_rate_by_session: dict[str, float] | None = None
+    unfavorable_fill_required: bool = True
+
+
+def validate_backtest_cost_model(
+    *,
+    model: BacktestCostModel,
+    required_sessions: list[str],
+) -> None:
+    """Raise ValueError when required cost assumptions are missing/invalid."""
+    if (
+        model.commission_bps is None
+        or not math.isfinite(model.commission_bps)
+        or model.commission_bps < 0
+    ):
+        raise ValueError("commission_bps must be provided and >= 0")
+    if not model.unfavorable_fill_required:
+        raise ValueError("unfavorable_fill_required must be True")
+
+    slippage = model.slippage_bps_by_session or {}
+    failure = model.failure_rate_by_session or {}
+    partial_fill = model.partial_fill_rate_by_session or {}
+
+    missing_slippage = [s for s in required_sessions if s not in slippage]
+    if missing_slippage:
+        raise ValueError(
+            f"missing slippage_bps_by_session for sessions: {', '.join(missing_slippage)}"
+        )
+
+    missing_failure = [s for s in required_sessions if s not in failure]
+    if missing_failure:
+        raise ValueError(
+            f"missing failure_rate_by_session for sessions: {', '.join(missing_failure)}"
+        )
+
+    missing_partial_fill = [s for s in required_sessions if s not in partial_fill]
+    if missing_partial_fill:
+        raise ValueError(
+            "missing partial_fill_rate_by_session for sessions: "
+            f"{', '.join(missing_partial_fill)}"
+        )
+
+    for sess, bps in slippage.items():
+        if not math.isfinite(bps) or bps < 0:
+            raise ValueError(f"slippage bps must be >= 0 for session={sess}")
+    for sess, rate in failure.items():
+        if not math.isfinite(rate) or rate < 0 or rate > 1:
+            raise ValueError(f"failure rate must be within [0,1] for session={sess}")
+    for sess, rate in partial_fill.items():
+        if not math.isfinite(rate) or rate < 0 or rate > 1:
+            raise ValueError(f"partial fill rate must be within [0,1] for session={sess}")

src/analysis/backtest_execution_model.py

@@ -0,0 +1,104 @@
+"""Conservative backtest execution model."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from random import Random
+from typing import Literal
+
+OrderSide = Literal["BUY", "SELL"]
+
+
+@dataclass(frozen=True)
+class ExecutionRequest:
+    side: OrderSide
+    session_id: str
+    qty: int
+    reference_price: float
+
+
+@dataclass(frozen=True)
+class ExecutionAssumptions:
+    slippage_bps_by_session: dict[str, float]
+    failure_rate_by_session: dict[str, float]
+    partial_fill_rate_by_session: dict[str, float]
+    partial_fill_min_ratio: float = 0.3
+    partial_fill_max_ratio: float = 0.8
+    seed: int = 0
+
+
+@dataclass(frozen=True)
+class ExecutionResult:
+    status: Literal["FILLED", "PARTIAL", "REJECTED"]
+    filled_qty: int
+    avg_price: float
+    slippage_bps: float
+    reason: str
+
+
+class BacktestExecutionModel:
+    """Execution simulator with conservative unfavorable fill assumptions."""
+
+    def __init__(self, assumptions: ExecutionAssumptions) -> None:
+        self.assumptions = assumptions
+        self._rng = Random(assumptions.seed)
+        if assumptions.partial_fill_min_ratio <= 0 or assumptions.partial_fill_max_ratio > 1:
+            raise ValueError("partial fill ratios must be within (0,1]")
+        if assumptions.partial_fill_min_ratio > assumptions.partial_fill_max_ratio:
+            raise ValueError("partial_fill_min_ratio must be <= partial_fill_max_ratio")
+        for sess, bps in assumptions.slippage_bps_by_session.items():
+            if not math.isfinite(bps) or bps < 0:
+                raise ValueError(f"slippage_bps must be finite and >= 0 for session={sess}")
+        for sess, rate in assumptions.failure_rate_by_session.items():
+            if not math.isfinite(rate) or rate < 0 or rate > 1:
+                raise ValueError(f"failure_rate must be in [0,1] for session={sess}")
+        for sess, rate in assumptions.partial_fill_rate_by_session.items():
+            if not math.isfinite(rate) or rate < 0 or rate > 1:
+                raise ValueError(f"partial_fill_rate must be in [0,1] for session={sess}")
+
+    def simulate(self, request: ExecutionRequest) -> ExecutionResult:
+        if request.qty <= 0:
+            raise ValueError("qty must be positive")
+        if request.reference_price <= 0:
+            raise ValueError("reference_price must be positive")
+
+        slippage_bps = self.assumptions.slippage_bps_by_session.get(request.session_id, 0.0)
+        failure_rate = self.assumptions.failure_rate_by_session.get(request.session_id, 0.0)
+        partial_rate = self.assumptions.partial_fill_rate_by_session.get(request.session_id, 0.0)
+
+        if self._rng.random() < failure_rate:
+            return ExecutionResult(
+                status="REJECTED",
+                filled_qty=0,
+                avg_price=0.0,
+                slippage_bps=slippage_bps,
+                reason="execution_failure",
+            )
+
+        slip_mult = 1.0 + (
+            slippage_bps / 10000.0 if request.side == "BUY" else -slippage_bps / 10000.0
+        )
+        exec_price = request.reference_price * slip_mult
+
+        if self._rng.random() < partial_rate:
+            ratio = self._rng.uniform(
+                self.assumptions.partial_fill_min_ratio,
+                self.assumptions.partial_fill_max_ratio,
+            )
+            filled = max(1, min(request.qty - 1, int(request.qty * ratio)))
+            return ExecutionResult(
+                status="PARTIAL",
+                filled_qty=filled,
+                avg_price=exec_price,
+                slippage_bps=slippage_bps,
+                reason="partial_fill",
+            )
+
+        return ExecutionResult(
+            status="FILLED",
+            filled_qty=request.qty,
+            avg_price=exec_price,
+            slippage_bps=slippage_bps,
+            reason="filled",
+        )

src/analysis/backtest_pipeline.py

@@ -0,0 +1,393 @@
+"""Integrated v2 backtest pipeline.
+
+Wires TripleBarrier labeling + WalkForward split + CostGuard validation
+into a single deterministic orchestration path.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import datetime
+from statistics import mean
+from typing import Literal, cast
+
+from src.analysis.backtest_cost_guard import BacktestCostModel, validate_backtest_cost_model
+from src.analysis.backtest_execution_model import (
+    BacktestExecutionModel,
+    ExecutionAssumptions,
+    ExecutionRequest,
+)
+from src.analysis.triple_barrier import TripleBarrierSpec, label_with_triple_barrier
+from src.analysis.walk_forward_split import WalkForwardFold, generate_walk_forward_splits
+
+
+@dataclass(frozen=True)
+class BacktestBar:
+    high: float
+    low: float
+    close: float
+    session_id: str
+    timestamp: datetime | None = None
+
+
+@dataclass(frozen=True)
+class WalkForwardConfig:
+    train_size: int
+    test_size: int
+    step_size: int | None = None
+    purge_size: int = 0
+    embargo_size: int = 0
+    min_train_size: int = 1
+
+
+@dataclass(frozen=True)
+class BaselineScore:
+    name: Literal["B0", "B1", "M1"]
+    accuracy: float
+    cost_adjusted_accuracy: float
+
+
+@dataclass(frozen=True)
+class BacktestFoldResult:
+    fold_index: int
+    train_indices: list[int]
+    test_indices: list[int]
+    train_label_distribution: dict[int, int]
+    test_label_distribution: dict[int, int]
+    baseline_scores: list[BaselineScore]
+    execution_adjusted_avg_return_bps: float
+    execution_adjusted_trade_count: int
+    execution_rejected_count: int
+    execution_partial_count: int
+
+
+@dataclass(frozen=True)
+class BacktestPipelineResult:
+    run_id: str
+    n_bars: int
+    n_entries: int
+    required_sessions: list[str]
+    label_distribution: dict[int, int]
+    folds: list[BacktestFoldResult]
+
+
+def run_v2_backtest_pipeline(
+    *,
+    bars: Sequence[BacktestBar],
+    entry_indices: Sequence[int],
+    side: int,
+    triple_barrier_spec: TripleBarrierSpec,
+    walk_forward: WalkForwardConfig,
+    cost_model: BacktestCostModel,
+    required_sessions: list[str] | None = None,
+) -> BacktestPipelineResult:
+    """Run v2 integrated pipeline (cost guard -> labels -> walk-forward baselines)."""
+    if not bars:
+        raise ValueError("bars must not be empty")
+    if not entry_indices:
+        raise ValueError("entry_indices must not be empty")
+
+    resolved_sessions = (
+        sorted(set(required_sessions))
+        if required_sessions is not None
+        else sorted({bar.session_id for bar in bars})
+    )
+    validate_backtest_cost_model(model=cost_model, required_sessions=resolved_sessions)
+    execution_model = BacktestExecutionModel(
+        ExecutionAssumptions(
+            slippage_bps_by_session=cost_model.slippage_bps_by_session or {},
+            failure_rate_by_session=cost_model.failure_rate_by_session or {},
+            partial_fill_rate_by_session=cost_model.partial_fill_rate_by_session or {},
+            seed=0,
+        )
+    )
+
+    highs = [float(bar.high) for bar in bars]
+    lows = [float(bar.low) for bar in bars]
+    closes = [float(bar.close) for bar in bars]
+    timestamps = [bar.timestamp for bar in bars]
+    normalized_entries = sorted(set(int(i) for i in entry_indices))
+    if normalized_entries[0] < 0 or normalized_entries[-1] >= len(bars):
+        raise IndexError("entry index out of range")
+
+    resolved_timestamps: list[datetime] | None = None
+    if triple_barrier_spec.max_holding_minutes is not None:
+        if any(ts is None for ts in timestamps):
+            raise ValueError(
+                "BacktestBar.timestamp is required for all bars when "
+                "triple_barrier_spec.max_holding_minutes is set"
+            )
+        resolved_timestamps = cast(list[datetime], timestamps)
+
+    labels_by_bar_index: dict[int, int] = {}
+    for idx in normalized_entries:
+        labels_by_bar_index[idx] = label_with_triple_barrier(
+            highs=highs,
+            lows=lows,
+            closes=closes,
+            timestamps=resolved_timestamps,
+            entry_index=idx,
+            side=side,
+            spec=triple_barrier_spec,
+        ).label
+
+    ordered_labels = [labels_by_bar_index[idx] for idx in normalized_entries]
+    ordered_sessions = [bars[idx].session_id for idx in normalized_entries]
+    ordered_prices = [bars[idx].close for idx in normalized_entries]
+    folds = generate_walk_forward_splits(
+        n_samples=len(normalized_entries),
+        train_size=walk_forward.train_size,
+        test_size=walk_forward.test_size,
+        step_size=walk_forward.step_size,
+        purge_size=walk_forward.purge_size,
+        embargo_size=walk_forward.embargo_size,
+        min_train_size=walk_forward.min_train_size,
+    )
+
+    fold_results: list[BacktestFoldResult] = []
+    for fold_idx, fold in enumerate(folds):
+        train_labels = [ordered_labels[i] for i in fold.train_indices]
+        test_labels = [ordered_labels[i] for i in fold.test_indices]
+        test_sessions = [ordered_sessions[i] for i in fold.test_indices]
+        test_prices = [ordered_prices[i] for i in fold.test_indices]
+        if not test_labels:
+            continue
+        execution_model = _build_execution_model(cost_model=cost_model, fold_seed=fold_idx)
+        execution_return_model = _build_execution_model(
+            cost_model=cost_model,
+            fold_seed=fold_idx,
+        )
+        b0_pred = _baseline_b0_pred(train_labels)
+        m1_pred = _m1_pred(train_labels)
+        execution_returns_bps: list[float] = []
+        execution_rejected = 0
+        execution_partial = 0
+        for rel_idx in fold.test_indices:
+            entry_bar_index = normalized_entries[rel_idx]
+            bar = bars[entry_bar_index]
+            trade = _simulate_execution_adjusted_return_bps(
+                execution_model=execution_return_model,
+                bar=bar,
+                label=ordered_labels[rel_idx],
+                side=side,
+                spec=triple_barrier_spec,
+                commission_bps=float(cost_model.commission_bps or 0.0),
+            )
+            if trade["status"] == "REJECTED":
+                execution_rejected += 1
+                continue
+            execution_returns_bps.append(float(trade["return_bps"]))
+            if trade["status"] == "PARTIAL":
+                execution_partial += 1
+        fold_results.append(
+            BacktestFoldResult(
+                fold_index=fold_idx,
+                train_indices=fold.train_indices,
+                test_indices=fold.test_indices,
+                train_label_distribution=_label_dist(train_labels),
+                test_label_distribution=_label_dist(test_labels),
+                baseline_scores=[
+                    BaselineScore(
+                        name="B0",
+                        accuracy=_score_constant(b0_pred, test_labels),
+                        cost_adjusted_accuracy=_score_with_execution(
+                            prediction=b0_pred,
+                            actual=test_labels,
+                            sessions=test_sessions,
+                            reference_prices=test_prices,
+                            execution_model=execution_model,
+                            commission_bps=float(cost_model.commission_bps or 0.0),
+                        ),
+                    ),
+                    BaselineScore(
+                        name="B1",
+                        accuracy=_score_constant(1, test_labels),
+                        cost_adjusted_accuracy=_score_with_execution(
+                            prediction=1,
+                            actual=test_labels,
+                            sessions=test_sessions,
+                            reference_prices=test_prices,
+                            execution_model=execution_model,
+                            commission_bps=float(cost_model.commission_bps or 0.0),
+                        ),
+                    ),
+                    BaselineScore(
+                        name="M1",
+                        accuracy=_score_constant(m1_pred, test_labels),
+                        cost_adjusted_accuracy=_score_with_execution(
+                            prediction=m1_pred,
+                            actual=test_labels,
+                            sessions=test_sessions,
+                            reference_prices=test_prices,
+                            execution_model=execution_model,
+                            commission_bps=float(cost_model.commission_bps or 0.0),
+                        ),
+                    ),
+                ],
+                execution_adjusted_avg_return_bps=(
+                    mean(execution_returns_bps) if execution_returns_bps else 0.0
+                ),
+                execution_adjusted_trade_count=len(execution_returns_bps),
+                execution_rejected_count=execution_rejected,
+                execution_partial_count=execution_partial,
+            )
+        )
+
+    return BacktestPipelineResult(
+        run_id=_build_run_id(
+            n_entries=len(normalized_entries),
+            n_folds=len(fold_results),
+            sessions=resolved_sessions,
+        ),
+        n_bars=len(bars),
+        n_entries=len(normalized_entries),
+        required_sessions=resolved_sessions,
+        label_distribution=_label_dist(ordered_labels),
+        folds=fold_results,
+    )
+
+
+def _label_dist(labels: Sequence[int]) -> dict[int, int]:
+    dist: dict[int, int] = {-1: 0, 0: 0, 1: 0}
+    for val in labels:
+        if val in dist:
+            dist[val] += 1
+    return dist
+
+
+def _score_constant(pred: int, actual: Sequence[int]) -> float:
+    return mean(1.0 if pred == label else 0.0 for label in actual)
+
+
+def _baseline_b0(train_labels: Sequence[int], test_labels: Sequence[int]) -> float:
+    return _score_constant(_baseline_b0_pred(train_labels), test_labels)
+
+
+def _baseline_b0_pred(train_labels: Sequence[int]) -> int:
+    if not train_labels:
+        return 0
+    # Majority-class baseline from training fold.
+    choices = (-1, 0, 1)
+    return max(choices, key=lambda c: train_labels.count(c))
+
+
+def _m1_pred(train_labels: Sequence[int]) -> int:
+    if not train_labels:
+        return 0
+    return train_labels[-1]
+
+
+def _build_execution_model(
+    *,
+    cost_model: BacktestCostModel,
+    fold_seed: int,
+) -> BacktestExecutionModel:
+    return BacktestExecutionModel(
+        ExecutionAssumptions(
+            slippage_bps_by_session=dict(cost_model.slippage_bps_by_session or {}),
+            failure_rate_by_session=dict(cost_model.failure_rate_by_session or {}),
+            partial_fill_rate_by_session=dict(cost_model.partial_fill_rate_by_session or {}),
+            seed=fold_seed,
+        )
+    )
+
+
+def _score_with_execution(
+    *,
+    prediction: int,
+    actual: Sequence[int],
+    sessions: Sequence[str],
+    reference_prices: Sequence[float],
+    execution_model: BacktestExecutionModel,
+    commission_bps: float,
+) -> float:
+    if not actual:
+        return 0.0
+    contributions: list[float] = []
+    for label, session_id, reference_price in zip(actual, sessions, reference_prices, strict=True):
+        if prediction == 0:
+            contributions.append(1.0 if label == 0 else 0.0)
+            continue
+        side = "BUY" if prediction > 0 else "SELL"
+        execution = execution_model.simulate(
+            ExecutionRequest(
+                side=side,
+                session_id=session_id,
+                qty=100,
+                reference_price=reference_price,
+            )
+        )
+        if execution.status == "REJECTED":
+            contributions.append(0.0)
+            continue
+        fill_ratio = execution.filled_qty / 100.0
+        cost_penalty = min(0.99, (commission_bps + execution.slippage_bps) / 10000.0)
+        correctness = 1.0 if prediction == label else 0.0
+        contributions.append(correctness * fill_ratio * (1.0 - cost_penalty))
+    return mean(contributions)
+
+
+def _build_run_id(*, n_entries: int, n_folds: int, sessions: Sequence[str]) -> str:
+    sess_key = "_".join(sessions)
+    return f"v2p-e{n_entries}-f{n_folds}-s{sess_key}"
+
+
+def fold_has_leakage(fold: WalkForwardFold) -> bool:
+    """Utility for tests/verification: True when train/test overlap exists."""
+    return bool(set(fold.train_indices).intersection(fold.test_indices))
+
+
+def _simulate_execution_adjusted_return_bps(
+    *,
+    execution_model: BacktestExecutionModel,
+    bar: BacktestBar,
+    label: int,
+    side: int,
+    spec: TripleBarrierSpec,
+    commission_bps: float,
+) -> dict[str, float | str]:
+    qty = 100
+    entry_req = ExecutionRequest(
+        side="BUY" if side == 1 else "SELL",
+        session_id=bar.session_id,
+        qty=qty,
+        reference_price=float(bar.close),
+    )
+    entry_fill = execution_model.simulate(entry_req)
+    if entry_fill.status == "REJECTED":
+        return {"status": "REJECTED", "return_bps": 0.0}
+
+    exit_qty = entry_fill.filled_qty
+    if label == 1:
+        gross_return_bps = spec.take_profit_pct * 10000.0
+    elif label == -1:
+        gross_return_bps = -spec.stop_loss_pct * 10000.0
+    else:
+        gross_return_bps = 0.0
+
+    if side == 1:
+        exit_price = float(bar.close) * (1.0 + gross_return_bps / 10000.0)
+    else:
+        exit_price = float(bar.close) * (1.0 - gross_return_bps / 10000.0)
+
+    exit_req = ExecutionRequest(
+        side="SELL" if side == 1 else "BUY",
+        session_id=bar.session_id,
+        qty=exit_qty,
+        reference_price=max(0.01, exit_price),
+    )
+    exit_fill = execution_model.simulate(exit_req)
+    if exit_fill.status == "REJECTED":
+        return {"status": "REJECTED", "return_bps": 0.0}
+
+    fill_ratio = min(entry_fill.filled_qty, exit_fill.filled_qty) / qty
+    cost_bps = (
+        float(entry_fill.slippage_bps)
+        + float(exit_fill.slippage_bps)
+        + (2.0 * float(commission_bps))
+    )
+    net_return_bps = (gross_return_bps * fill_ratio) - cost_bps
+    is_partial = entry_fill.status == "PARTIAL" or exit_fill.status == "PARTIAL"
+    status = "PARTIAL" if is_partial else "FILLED"
+    return {"status": status, "return_bps": net_return_bps}

src/analysis/scanner.py

@@ -104,6 +104,7 @@ class MarketScanner:
 
             # Store in L7 real-time layer
             from datetime import UTC, datetime
+
             timeframe = datetime.now(UTC).isoformat()
             self.context_store.set_context(
                 ContextLayer.L7_REALTIME,
@@ -158,12 +159,8 @@ class MarketScanner:
         top_movers = valid_metrics[: self.top_n]
 
         # Detect breakouts and breakdowns
-        breakouts = [
-            m.stock_code for m in valid_metrics if self.analyzer.is_breakout(m)
-        ]
-        breakdowns = [
-            m.stock_code for m in valid_metrics if self.analyzer.is_breakdown(m)
-        ]
+        breakouts = [m.stock_code for m in valid_metrics if self.analyzer.is_breakout(m)]
+        breakdowns = [m.stock_code for m in valid_metrics if self.analyzer.is_breakdown(m)]
 
         logger.info(
             "%s scan complete: %d scanned, top momentum=%.1f, %d breakouts, %d breakdowns",
@@ -228,10 +225,9 @@ class MarketScanner:
 
         # If we removed too many, backfill from current watchlist
         if len(updated) < len(current_watchlist):
-            backfill = [
-                code for code in current_watchlist
-                if code not in updated
-            ][: len(current_watchlist) - len(updated)]
+            backfill = [code for code in current_watchlist if code not in updated][
+                : len(current_watchlist) - len(updated)
+            ]
             updated.extend(backfill)
 
         logger.info(

src/analysis/smart_scanner.py

@@ -158,7 +158,12 @@ class SmartVolatilityScanner:
                         price = latest_close
                     latest_high = _safe_float(latest.get("high"))
                     latest_low = _safe_float(latest.get("low"))
-                    if latest_close > 0 and latest_high > 0 and latest_low > 0 and latest_high >= latest_low:
+                    if (
+                        latest_close > 0
+                        and latest_high > 0
+                        and latest_low > 0
+                        and latest_high >= latest_low
+                    ):
                         intraday_range_pct = (latest_high - latest_low) / latest_close * 100.0
                     if volume <= 0:
                         volume = _safe_float(latest.get("volume"))
@@ -234,9 +239,7 @@ class SmartVolatilityScanner:
                 limit=50,
             )
         except Exception as exc:
-            logger.warning(
-                "Overseas fluctuation ranking failed for %s: %s", market.code, exc
-            )
+            logger.warning("Overseas fluctuation ranking failed for %s: %s", market.code, exc)
             fluct_rows = []
 
         if not fluct_rows:
@@ -250,9 +253,7 @@ class SmartVolatilityScanner:
                 limit=50,
             )
         except Exception as exc:
-            logger.warning(
-                "Overseas volume ranking failed for %s: %s", market.code, exc
-            )
+            logger.warning("Overseas volume ranking failed for %s: %s", market.code, exc)
             volume_rows = []
 
         for idx, row in enumerate(volume_rows):
@@ -433,16 +434,10 @@ def _extract_intraday_range_pct(row: dict[str, Any], price: float) -> float:
     if price <= 0:
         return 0.0
     high = _safe_float(
-        row.get("high")
-        or row.get("ovrs_hgpr")
-        or row.get("stck_hgpr")
-        or row.get("day_hgpr")
+        row.get("high") or row.get("ovrs_hgpr") or row.get("stck_hgpr") or row.get("day_hgpr")
     )
     low = _safe_float(
-        row.get("low")
-        or row.get("ovrs_lwpr")
-        or row.get("stck_lwpr")
-        or row.get("day_lwpr")
+        row.get("low") or row.get("ovrs_lwpr") or row.get("stck_lwpr") or row.get("day_lwpr")
     )
     if high <= 0 or low <= 0 or high < low:
         return 0.0

src/analysis/triple_barrier.py

@@ -0,0 +1,142 @@
+"""Triple barrier labeler utilities.
+
+Implements first-touch labeling with upper/lower/time barriers.
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Sequence
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Literal
+
+TieBreakMode = Literal["stop_first", "take_first"]
+
+
+@dataclass(frozen=True)
+class TripleBarrierSpec:
+    take_profit_pct: float
+    stop_loss_pct: float
+    max_holding_bars: int | None = None
+    max_holding_minutes: int | None = None
+    tie_break: TieBreakMode = "stop_first"
+
+    def __post_init__(self) -> None:
+        if self.max_holding_minutes is None and self.max_holding_bars is None:
+            raise ValueError("one of max_holding_minutes or max_holding_bars must be set")
+        if self.max_holding_minutes is not None and self.max_holding_minutes <= 0:
+            raise ValueError("max_holding_minutes must be positive")
+        if self.max_holding_bars is not None and self.max_holding_bars <= 0:
+            raise ValueError("max_holding_bars must be positive")
+
+
+@dataclass(frozen=True)
+class TripleBarrierLabel:
+    label: int  # +1 take-profit first, -1 stop-loss first, 0 timeout
+    touched: Literal["take_profit", "stop_loss", "time"]
+    touch_bar: int
+    entry_price: float
+    upper_barrier: float
+    lower_barrier: float
+
+
+def label_with_triple_barrier(
+    *,
+    highs: Sequence[float],
+    lows: Sequence[float],
+    closes: Sequence[float],
+    timestamps: Sequence[datetime] | None = None,
+    entry_index: int,
+    side: int,
+    spec: TripleBarrierSpec,
+) -> TripleBarrierLabel:
+    """Label one entry using triple-barrier first-touch rule.
+
+    Args:
+        highs/lows/closes: OHLC components with identical length.
+        entry_index: Entry bar index in the sequences.
+        side: +1 for long, -1 for short.
+        spec: Barrier specification.
+    """
+    if side not in {1, -1}:
+        raise ValueError("side must be +1 or -1")
+    if len(highs) != len(lows) or len(highs) != len(closes):
+        raise ValueError("highs, lows, closes lengths must match")
+    if entry_index < 0 or entry_index >= len(closes):
+        raise IndexError("entry_index out of range")
+
+    entry_price = float(closes[entry_index])
+    if entry_price <= 0:
+        raise ValueError("entry price must be positive")
+
+    if side == 1:
+        upper = entry_price * (1.0 + spec.take_profit_pct)
+        lower = entry_price * (1.0 - spec.stop_loss_pct)
+    else:
+        # For short side, favorable move is down.
+        upper = entry_price * (1.0 + spec.stop_loss_pct)
+        lower = entry_price * (1.0 - spec.take_profit_pct)
+
+    if spec.max_holding_minutes is not None:
+        if timestamps is None:
+            raise ValueError("timestamps are required when max_holding_minutes is set")
+        if len(timestamps) != len(closes):
+            raise ValueError("timestamps length must match OHLC lengths")
+        expiry_timestamp = timestamps[entry_index] + timedelta(minutes=spec.max_holding_minutes)
+        last_index = entry_index
+        for idx in range(entry_index + 1, len(closes)):
+            if timestamps[idx] > expiry_timestamp:
+                break
+            last_index = idx
+    else:
+        assert spec.max_holding_bars is not None
+        warnings.warn(
+            (
+                "TripleBarrierSpec.max_holding_bars is deprecated; "
+                "use max_holding_minutes with timestamps instead."
+            ),
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        last_index = min(len(closes) - 1, entry_index + spec.max_holding_bars)
+    for idx in range(entry_index + 1, last_index + 1):
+        high_price = float(highs[idx])
+        low_price = float(lows[idx])
+
+        up_touch = high_price >= upper
+        down_touch = low_price <= lower
+        if not up_touch and not down_touch:
+            continue
+
+        if up_touch and down_touch:
+            if spec.tie_break == "stop_first":
+                touched = "stop_loss"
+                label = -1
+            else:
+                touched = "take_profit"
+                label = 1
+        elif up_touch:
+            touched = "take_profit" if side == 1 else "stop_loss"
+            label = 1 if side == 1 else -1
+        else:
+            touched = "stop_loss" if side == 1 else "take_profit"
+            label = -1 if side == 1 else 1
+
+        return TripleBarrierLabel(
+            label=label,
+            touched=touched,
+            touch_bar=idx,
+            entry_price=entry_price,
+            upper_barrier=upper,
+            lower_barrier=lower,
+        )
+
+    return TripleBarrierLabel(
+        label=0,
+        touched="time",
+        touch_bar=last_index,
+        entry_price=entry_price,
+        upper_barrier=upper,
+        lower_barrier=lower,
+    )

src/analysis/volatility.py

@@ -92,9 +92,7 @@ class VolatilityAnalyzer:
         recent_tr = true_ranges[-period:]
         return sum(recent_tr) / len(recent_tr)
 
-    def calculate_price_change(
-        self, current_price: float, past_price: float
-    ) -> float:
+    def calculate_price_change(self, current_price: float, past_price: float) -> float:
         """Calculate price change percentage.
 
         Args:
@@ -108,9 +106,7 @@ class VolatilityAnalyzer:
             return 0.0
         return ((current_price - past_price) / past_price) * 100
 
-    def calculate_volume_surge(
-        self, current_volume: float, avg_volume: float
-    ) -> float:
+    def calculate_volume_surge(self, current_volume: float, avg_volume: float) -> float:
         """Calculate volume surge ratio.
 
         Args:
@@ -240,11 +236,7 @@ class VolatilityAnalyzer:
             Momentum score (0-100)
         """
         # Weight recent changes more heavily
-        weighted_change = (
-            price_change_1m * 0.4 +
-            price_change_5m * 0.3 +
-            price_change_15m * 0.2
-        )
+        weighted_change = price_change_1m * 0.4 + price_change_5m * 0.3 + price_change_15m * 0.2
 
         # Volume contribution (normalized to 0-10 scale)
         volume_contribution = min(10.0, (volume_surge - 1.0) * 5.0)
@@ -301,17 +293,11 @@ class VolatilityAnalyzer:
 
         if len(close_prices) > 0:
             if len(close_prices) >= 1:
-                price_change_1m = self.calculate_price_change(
-                    current_price, close_prices[-1]
-                )
+                price_change_1m = self.calculate_price_change(current_price, close_prices[-1])
             if len(close_prices) >= 5:
-                price_change_5m = self.calculate_price_change(
-                    current_price, close_prices[-5]
-                )
+                price_change_5m = self.calculate_price_change(current_price, close_prices[-5])
             if len(close_prices) >= 15:
-                price_change_15m = self.calculate_price_change(
-                    current_price, close_prices[-15]
-                )
+                price_change_15m = self.calculate_price_change(current_price, close_prices[-15])
 
         # Calculate volume surge
         avg_volume = sum(volumes) / len(volumes) if volumes else current_volume

src/analysis/walk_forward_split.py

@@ -0,0 +1,74 @@
+"""Walk-forward splitter with purge/embargo controls."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class WalkForwardFold:
+    train_indices: list[int]
+    test_indices: list[int]
+
+    @property
+    def train_size(self) -> int:
+        return len(self.train_indices)
+
+    @property
+    def test_size(self) -> int:
+        return len(self.test_indices)
+
+
+def generate_walk_forward_splits(
+    *,
+    n_samples: int,
+    train_size: int,
+    test_size: int,
+    step_size: int | None = None,
+    purge_size: int = 0,
+    embargo_size: int = 0,
+    min_train_size: int = 1,
+) -> list[WalkForwardFold]:
+    """Generate chronological folds with purge/embargo leakage controls."""
+    if n_samples <= 0:
+        raise ValueError("n_samples must be positive")
+    if train_size <= 0 or test_size <= 0:
+        raise ValueError("train_size and test_size must be positive")
+    if purge_size < 0 or embargo_size < 0:
+        raise ValueError("purge_size and embargo_size must be >= 0")
+    if min_train_size <= 0:
+        raise ValueError("min_train_size must be positive")
+
+    step = step_size if step_size is not None else test_size
+    if step <= 0:
+        raise ValueError("step_size must be positive")
+
+    folds: list[WalkForwardFold] = []
+    prev_test_end: int | None = None
+    test_start = train_size + purge_size
+
+    while test_start + test_size <= n_samples:
+        test_end = test_start + test_size - 1
+        train_end = test_start - purge_size - 1
+        if train_end < 0:
+            break
+
+        train_start = max(0, train_end - train_size + 1)
+        train_indices = list(range(train_start, train_end + 1))
+
+        if prev_test_end is not None and embargo_size > 0:
+            emb_from = prev_test_end + 1
+            emb_to = prev_test_end + embargo_size
+            train_indices = [i for i in train_indices if i < emb_from or i > emb_to]
+
+        if len(train_indices) >= min_train_size:
+            folds.append(
+                WalkForwardFold(
+                    train_indices=train_indices,
+                    test_indices=list(range(test_start, test_end + 1)),
+                )
+            )
+            prev_test_end = test_end
+        test_start += step
+
+    return folds

src/backup/__init__.py

@@ -7,9 +7,9 @@ This module provides:
 - Health monitoring and alerts
 """
 
-from src.backup.exporter import BackupExporter, ExportFormat
-from src.backup.scheduler import BackupScheduler, BackupPolicy
 from src.backup.cloud_storage import CloudStorage, S3Config
+from src.backup.exporter import BackupExporter, ExportFormat
+from src.backup.scheduler import BackupPolicy, BackupScheduler
 
 __all__ = [
     "BackupExporter",

src/backup/cloud_storage.py

@@ -94,7 +94,9 @@ class CloudStorage:
         if metadata:
             extra_args["Metadata"] = metadata
 
-        logger.info("Uploading %s to s3://%s/%s", file_path.name, self.config.bucket_name, object_key)
+        logger.info(
+            "Uploading %s to s3://%s/%s", file_path.name, self.config.bucket_name, object_key
+        )
 
         try:
             self.client.upload_file(

src/backup/exporter.py

@@ -14,14 +14,14 @@ import json
 import logging
 import sqlite3
 from datetime import UTC, datetime
-from enum import Enum
+from enum import StrEnum
 from pathlib import Path
 from typing import Any
 
 logger = logging.getLogger(__name__)
 
 
-class ExportFormat(str, Enum):
+class ExportFormat(StrEnum):
     """Supported export formats."""
 
     JSON = "json"
@@ -103,15 +103,11 @@ class BackupExporter:
         elif fmt == ExportFormat.CSV:
             return self._export_csv(output_dir, timestamp, compress, incremental_since)
         elif fmt == ExportFormat.PARQUET:
-            return self._export_parquet(
-                output_dir, timestamp, compress, incremental_since
-            )
+            return self._export_parquet(output_dir, timestamp, compress, incremental_since)
         else:
             raise ValueError(f"Unsupported format: {fmt}")
 
-    def _get_trades(
-        self, incremental_since: datetime | None = None
-    ) -> list[dict[str, Any]]:
+    def _get_trades(self, incremental_since: datetime | None = None) -> list[dict[str, Any]]:
         """Fetch trades from database.
 
         Args:
@@ -164,9 +160,7 @@ class BackupExporter:
 
         data = {
             "export_timestamp": datetime.now(UTC).isoformat(),
-            "incremental_since": (
-                incremental_since.isoformat() if incremental_since else None
-            ),
+            "incremental_since": (incremental_since.isoformat() if incremental_since else None),
             "record_count": len(trades),
             "trades": trades,
         }
@@ -284,8 +278,7 @@ class BackupExporter:
             import pyarrow.parquet as pq
         except ImportError:
             raise ImportError(
-                "pyarrow is required for Parquet export. "
-                "Install with: pip install pyarrow"
+                "pyarrow is required for Parquet export. Install with: pip install pyarrow"
             )
 
         # Convert to pyarrow table

src/backup/health_monitor.py

@@ -14,14 +14,14 @@ import shutil
 import sqlite3
 from dataclasses import dataclass
 from datetime import UTC, datetime, timedelta
-from enum import Enum
+from enum import StrEnum
 from pathlib import Path
 from typing import Any
 
 logger = logging.getLogger(__name__)
 
 
-class HealthStatus(str, Enum):
+class HealthStatus(StrEnum):
     """Health check status."""
 
     HEALTHY = "healthy"
@@ -137,9 +137,13 @@ class HealthMonitor:
             used_percent = (stat.used / stat.total) * 100
 
             if stat.free < self.min_disk_space_bytes:
+                min_disk_gb = self.min_disk_space_bytes / 1024 / 1024 / 1024
                 return HealthCheckResult(
                     status=HealthStatus.UNHEALTHY,
-                    message=f"Low disk space: {free_gb:.2f} GB free (minimum: {self.min_disk_space_bytes / 1024 / 1024 / 1024:.2f} GB)",
+                    message=(
+                        f"Low disk space: {free_gb:.2f} GB free "
+                        f"(minimum: {min_disk_gb:.2f} GB)"
+                    ),
                     details={
                         "free_gb": free_gb,
                         "total_gb": total_gb,

src/backup/scheduler.py

@@ -12,14 +12,14 @@ import logging
 import shutil
 from dataclasses import dataclass
 from datetime import UTC, datetime, timedelta
-from enum import Enum
+from enum import StrEnum
 from pathlib import Path
 from typing import Any
 
 logger = logging.getLogger(__name__)
 
 
-class BackupPolicy(str, Enum):
+class BackupPolicy(StrEnum):
     """Backup retention policies."""
 
     DAILY = "daily"
@@ -69,9 +69,7 @@ class BackupScheduler:
         for d in [self.daily_dir, self.weekly_dir, self.monthly_dir]:
             d.mkdir(parents=True, exist_ok=True)
 
-    def create_backup(
-        self, policy: BackupPolicy, verify: bool = True
-    ) -> BackupMetadata:
+    def create_backup(self, policy: BackupPolicy, verify: bool = True) -> BackupMetadata:
         """Create a database backup.
 
         Args:
@@ -229,9 +227,7 @@ class BackupScheduler:
 
         return removed
 
-    def list_backups(
-        self, policy: BackupPolicy | None = None
-    ) -> list[BackupMetadata]:
+    def list_backups(self, policy: BackupPolicy | None = None) -> list[BackupMetadata]:
         """List available backups.
 
         Args:

src/brain/cache.py

@@ -13,8 +13,8 @@ import hashlib
 import json
 import logging
 import time
-from dataclasses import dataclass, field
-from typing import Any, TYPE_CHECKING
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
     from src.brain.gemini_client import TradeDecision
@@ -26,7 +26,7 @@ logger = logging.getLogger(__name__)
 class CacheEntry:
     """Cached decision with metadata."""
 
-    decision: "TradeDecision"
+    decision: TradeDecision
     cached_at: float  # Unix timestamp
     hit_count: int = 0
     market_data_hash: str = ""
@@ -239,9 +239,7 @@ class DecisionCache:
         """
         current_time = time.time()
         expired_keys = [
-            k
-            for k, v in self._cache.items()
-            if current_time - v.cached_at > self.ttl_seconds
+            k for k, v in self._cache.items() if current_time - v.cached_at > self.ttl_seconds
         ]
 
         count = len(expired_keys)

src/brain/context_selector.py

@@ -11,14 +11,14 @@ from __future__ import annotations
 
 from dataclasses import dataclass
 from datetime import UTC, datetime
-from enum import Enum
+from enum import StrEnum
 from typing import Any
 
 from src.context.layer import ContextLayer
 from src.context.store import ContextStore
 
 
-class DecisionType(str, Enum):
+class DecisionType(StrEnum):
     """Type of trading decision being made."""
 
     NORMAL = "normal"  # Regular trade decision
@@ -183,9 +183,7 @@ class ContextSelector:
             ContextLayer.L1_LEGACY,
         ]
 
-        scores = {
-            layer: self.score_layer_relevance(layer, decision_type) for layer in all_layers
-        }
+        scores = {layer: self.score_layer_relevance(layer, decision_type) for layer in all_layers}
 
         # Filter by minimum score
         selected_layers = [layer for layer, score in scores.items() if score >= min_score]

src/brain/gemini_client.py

@@ -25,12 +25,12 @@ from typing import Any
 
 from google import genai
 
-from src.config import Settings
-from src.data.news_api import NewsAPI, NewsSentiment
-from src.data.economic_calendar import EconomicCalendar
-from src.data.market_data import MarketData
 from src.brain.cache import DecisionCache
 from src.brain.prompt_optimizer import PromptOptimizer
+from src.config import Settings
+from src.data.economic_calendar import EconomicCalendar
+from src.data.market_data import MarketData
+from src.data.news_api import NewsAPI, NewsSentiment
 
 logger = logging.getLogger(__name__)
 
@@ -159,16 +159,12 @@ class GeminiClient:
             return ""
 
         # Check for upcoming high-impact events
-        upcoming = self._economic_calendar.get_upcoming_events(
-            days_ahead=7, min_impact="HIGH"
-        )
+        upcoming = self._economic_calendar.get_upcoming_events(days_ahead=7, min_impact="HIGH")
 
         if upcoming.high_impact_count == 0:
             return ""
 
-        lines = [
-            f"Upcoming High-Impact Events: {upcoming.high_impact_count} in next 7 days"
-        ]
+        lines = [f"Upcoming High-Impact Events: {upcoming.high_impact_count} in next 7 days"]
 
         if upcoming.next_major_event is not None:
             event = upcoming.next_major_event
@@ -180,9 +176,7 @@ class GeminiClient:
         # Check for earnings
         earnings_date = self._economic_calendar.get_earnings_date(stock_code)
         if earnings_date is not None:
-            lines.append(
-                f"  Earnings: {stock_code} on {earnings_date.strftime('%Y-%m-%d')}"
-            )
+            lines.append(f"  Earnings: {stock_code} on {earnings_date.strftime('%Y-%m-%d')}")
 
         return "\n".join(lines)
 
@@ -235,9 +229,7 @@ class GeminiClient:
 
         # Add foreigner net if non-zero
         if market_data.get("foreigner_net", 0) != 0:
-            market_info_lines.append(
-                f"Foreigner Net Buy/Sell: {market_data['foreigner_net']}"
-            )
+            market_info_lines.append(f"Foreigner Net Buy/Sell: {market_data['foreigner_net']}")
 
         market_info = "\n".join(market_info_lines)
 
@@ -249,8 +241,7 @@ class GeminiClient:
             market_info += f"\n\n{external_context}"
 
         json_format = (
-            '{"action": "BUY"|"SELL"|"HOLD", '
-            '"confidence": <int 0-100>, "rationale": "<string>"}'
+            '{"action": "BUY"|"SELL"|"HOLD", "confidence": <int 0-100>, "rationale": "<string>"}'
         )
         return (
             f"You are a professional {market_name} trading analyst.\n"
@@ -289,15 +280,12 @@ class GeminiClient:
 
         # Add foreigner net if non-zero
         if market_data.get("foreigner_net", 0) != 0:
-            market_info_lines.append(
-                f"Foreigner Net Buy/Sell: {market_data['foreigner_net']}"
-            )
+            market_info_lines.append(f"Foreigner Net Buy/Sell: {market_data['foreigner_net']}")
 
         market_info = "\n".join(market_info_lines)
 
         json_format = (
-            '{"action": "BUY"|"SELL"|"HOLD", '
-            '"confidence": <int 0-100>, "rationale": "<string>"}'
+            '{"action": "BUY"|"SELL"|"HOLD", "confidence": <int 0-100>, "rationale": "<string>"}'
         )
         return (
             f"You are a professional {market_name} trading analyst.\n"
@@ -339,23 +327,19 @@ class GeminiClient:
             data = json.loads(cleaned)
         except json.JSONDecodeError:
             logger.warning("Malformed JSON from Gemini — defaulting to HOLD")
-            return TradeDecision(
-                action="HOLD", confidence=0, rationale="Malformed JSON response"
-            )
+            return TradeDecision(action="HOLD", confidence=0, rationale="Malformed JSON response")
 
         # 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")
-            return TradeDecision(
-                action="HOLD", confidence=0, rationale="Missing required fields"
-            )
+            # 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=raw)
 
         action = str(data["action"]).upper()
         if action not in VALID_ACTIONS:
             logger.warning("Invalid action '%s' from Gemini — defaulting to HOLD", action)
-            return TradeDecision(
-                action="HOLD", confidence=0, rationale=f"Invalid action: {action}"
-            )
+            return TradeDecision(action="HOLD", confidence=0, rationale=f"Invalid action: {action}")
 
         confidence = int(data["confidence"])
         rationale = str(data["rationale"])
@@ -439,6 +423,16 @@ 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
 
@@ -532,9 +526,7 @@ class GeminiClient:
     # Batch Decision Making (for daily trading mode)
     # ------------------------------------------------------------------
 
-    async def decide_batch(
-        self, stocks_data: list[dict[str, Any]]
-    ) -> dict[str, TradeDecision]:
+    async def decide_batch(self, stocks_data: list[dict[str, Any]]) -> dict[str, TradeDecision]:
         """Make decisions for multiple stocks in a single API call.
 
         This is designed for daily trading mode to minimize API usage

src/brain/prompt_optimizer.py

@@ -179,8 +179,9 @@ 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'
-                "Rules: act=BUY/SELL/HOLD, conf=0-100, reason=concise. No markdown."
+                "Return JSON: "
+                '{"action":"BUY"|"SELL"|"HOLD","confidence":<0-100>,"rationale":"<text>"}\n'
+                "Rules: action=BUY/SELL/HOLD, confidence=0-100, rationale=concise. No markdown."
             )
         else:
             # Data only (for cached contexts where instructions are known)

src/broker/kis_api.py

@@ -8,7 +8,7 @@ from __future__ import annotations
 import asyncio
 import logging
 import ssl
-from typing import Any
+from typing import Any, cast
 
 import aiohttp
 
@@ -58,7 +58,7 @@ class LeakyBucket:
 
     def __init__(self, rate: float) -> None:
         """Args:
-            rate: Maximum requests per second.
+        rate: Maximum requests per second.
         """
         self._rate = rate
         self._interval = 1.0 / rate
@@ -103,7 +103,8 @@ class KISBroker:
                 ssl_ctx.verify_mode = ssl.CERT_NONE
                 connector = aiohttp.TCPConnector(ssl=ssl_ctx)
             self._session = aiohttp.ClientSession(
-                timeout=timeout, connector=connector,
+                timeout=timeout,
+                connector=connector,
             )
         return self._session
 
@@ -224,16 +225,12 @@ class KISBroker:
             async with session.get(url, headers=headers, params=params) as resp:
                 if resp.status != 200:
                     text = await resp.text()
-                    raise ConnectionError(
-                        f"get_orderbook failed ({resp.status}): {text}"
-                    )
+                    raise ConnectionError(f"get_orderbook failed ({resp.status}): {text}")
                 return await resp.json()
         except (TimeoutError, aiohttp.ClientError) as exc:
             raise ConnectionError(f"Network error fetching orderbook: {exc}") from exc
 
-    async def get_current_price(
-        self, stock_code: str
-    ) -> tuple[float, float, float]:
+    async def get_current_price(self, stock_code: str) -> tuple[float, float, float]:
         """Fetch current price data for a domestic stock.
 
         Uses the ``inquire-price`` API (FHKST01010100), which works in both
@@ -265,9 +262,7 @@ class KISBroker:
             async with session.get(url, headers=headers, params=params) as resp:
                 if resp.status != 200:
                     text = await resp.text()
-                    raise ConnectionError(
-                        f"get_current_price failed ({resp.status}): {text}"
-                    )
+                    raise ConnectionError(f"get_current_price failed ({resp.status}): {text}")
                 data = await resp.json()
                 out = data.get("output", {})
                 return (
@@ -276,16 +271,17 @@ class KISBroker:
                     _f(out.get("frgn_ntby_qty")),
                 )
         except (TimeoutError, aiohttp.ClientError) as exc:
-            raise ConnectionError(
-                f"Network error fetching current price: {exc}"
-            ) from exc
+            raise ConnectionError(f"Network error fetching current price: {exc}") from exc
 
     async def get_balance(self) -> dict[str, Any]:
         """Fetch current account balance and holdings."""
         await self._rate_limiter.acquire()
         session = self._get_session()
 
-        headers = await self._auth_headers("VTTC8434R")  # 모의투자 잔고조회
+        # TR_ID: 실전 TTTC8434R, 모의 VTTC8434R
+        # Source: 한국투자증권 오픈API 전체문서 (20260221) — '국내주식 잔고조회' 시트
+        tr_id = "TTTC8434R" if self._settings.MODE == "live" else "VTTC8434R"
+        headers = await self._auth_headers(tr_id)
         params = {
             "CANO": self._account_no,
             "ACNT_PRDT_CD": self._product_cd,
@@ -305,9 +301,7 @@ class KISBroker:
             async with session.get(url, headers=headers, params=params) as resp:
                 if resp.status != 200:
                     text = await resp.text()
-                    raise ConnectionError(
-                        f"get_balance failed ({resp.status}): {text}"
-                    )
+                    raise ConnectionError(f"get_balance failed ({resp.status}): {text}")
                 return await resp.json()
         except (TimeoutError, aiohttp.ClientError) as exc:
             raise ConnectionError(f"Network error fetching balance: {exc}") from exc
@@ -330,7 +324,13 @@ class KISBroker:
         await self._rate_limiter.acquire()
         session = self._get_session()
 
-        tr_id = "VTTC0802U" if order_type == "BUY" else "VTTC0801U"
+        # TR_ID: 실전 BUY=TTTC0012U SELL=TTTC0011U, 모의 BUY=VTTC0012U SELL=VTTC0011U
+        # Source: 한국투자증권 오픈API 전체문서 (20260221) — '주식주문(현금)' 시트
+        # ※ TTTC0802U/VTTC0802U는 미수매수(증거금40% 계좌 전용) — 현금주문에 사용 금지
+        if self._settings.MODE == "live":
+            tr_id = "TTTC0012U" if order_type == "BUY" else "TTTC0011U"
+        else:
+            tr_id = "VTTC0012U" if order_type == "BUY" else "VTTC0011U"
 
         # KRX requires limit orders to be rounded down to the tick unit.
         # ORD_DVSN: "00"=지정가, "01"=시장가
@@ -360,9 +360,7 @@ class KISBroker:
             async with session.post(url, headers=headers, json=body) as resp:
                 if resp.status != 200:
                     text = await resp.text()
-                    raise ConnectionError(
-                        f"send_order failed ({resp.status}): {text}"
-                    )
+                    raise ConnectionError(f"send_order failed ({resp.status}): {text}")
                 data = await resp.json()
                 logger.info(
                     "Order submitted",
@@ -421,7 +419,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",
@@ -440,9 +438,7 @@ class KISBroker:
             async with session.get(url, headers=headers, params=params) as resp:
                 if resp.status != 200:
                     text = await resp.text()
-                    raise ConnectionError(
-                        f"fetch_market_rankings failed ({resp.status}): {text}"
-                    )
+                    raise ConnectionError(f"fetch_market_rankings failed ({resp.status}): {text}")
                 data = await resp.json()
 
             # Parse response - output is a list of ranked stocks
@@ -456,19 +452,121 @@ class KISBroker:
 
             rankings = []
             for item in data.get("output", [])[:limit]:
-                rankings.append({
-                    "stock_code": 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")),
-                    "change_rate": _safe_float(item.get("prdy_ctrt", "0")),
-                    "volume_increase_rate": _safe_float(item.get("vol_inrt", "0")),
-                })
+                rankings.append(
+                    {
+                        "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")),
+                        "change_rate": _safe_float(item.get("prdy_ctrt", "0")),
+                        "volume_increase_rate": _safe_float(item.get("vol_inrt", "0")),
+                    }
+                )
             return rankings
 
         except (TimeoutError, aiohttp.ClientError) as exc:
             raise ConnectionError(f"Network error fetching rankings: {exc}") from exc
 
+    async def get_domestic_pending_orders(self) -> list[dict[str, Any]]:
+        """Fetch unfilled (pending) domestic limit orders.
+
+        The KIS pending-orders API (TTTC0084R) is unsupported in paper (VTS)
+        mode, so this method returns an empty list immediately when MODE is
+        not "live".
+
+        Returns:
+            List of pending order dicts from the KIS ``output`` field.
+            Each dict includes keys such as ``odno``, ``orgn_odno``,
+            ``ord_gno_brno``, ``psbl_qty``, ``sll_buy_dvsn_cd``, ``pdno``.
+        """
+        if self._settings.MODE != "live":
+            logger.debug(
+                "get_domestic_pending_orders: paper mode — TTTC0084R unsupported, returning []"
+            )
+            return []
+
+        await self._rate_limiter.acquire()
+        session = self._get_session()
+
+        # TR_ID: 실전 TTTC0084R (모의 미지원)
+        # Source: 한국투자증권 오픈API 전체문서 (20260221) — '주식 미체결조회' 시트
+        headers = await self._auth_headers("TTTC0084R")
+        params = {
+            "CANO": self._account_no,
+            "ACNT_PRDT_CD": self._product_cd,
+            "INQR_DVSN_1": "0",
+            "INQR_DVSN_2": "0",
+            "CTX_AREA_FK100": "",
+            "CTX_AREA_NK100": "",
+        }
+        url = f"{self._base_url}/uapi/domestic-stock/v1/trading/inquire-psbl-rvsecncl"
+
+        try:
+            async with session.get(url, headers=headers, params=params) as resp:
+                if resp.status != 200:
+                    text = await resp.text()
+                    raise ConnectionError(
+                        f"get_domestic_pending_orders failed ({resp.status}): {text}"
+                    )
+                data = await resp.json()
+                return data.get("output", []) or []
+        except (TimeoutError, aiohttp.ClientError) as exc:
+            raise ConnectionError(f"Network error fetching domestic pending orders: {exc}") from exc
+
+    async def cancel_domestic_order(
+        self,
+        stock_code: str,
+        orgn_odno: str,
+        krx_fwdg_ord_orgno: str,
+        qty: int,
+    ) -> dict[str, Any]:
+        """Cancel an unfilled domestic limit order.
+
+        Args:
+            stock_code: 6-digit domestic stock code (``pdno``).
+            orgn_odno: Original order number from pending-orders response
+                (``orgn_odno`` field).
+            krx_fwdg_ord_orgno: KRX forwarding order branch number from
+                pending-orders response (``ord_gno_brno`` field).
+            qty: Quantity to cancel (use ``psbl_qty`` from pending order).
+
+        Returns:
+            Raw KIS API response dict (check ``rt_cd == "0"`` for success).
+        """
+        await self._rate_limiter.acquire()
+        session = self._get_session()
+
+        # TR_ID: 실전 TTTC0013U, 모의 VTTC0013U
+        # Source: 한국투자증권 오픈API 전체문서 (20260221) — '주식주문(정정취소)' 시트
+        tr_id = "TTTC0013U" if self._settings.MODE == "live" else "VTTC0013U"
+
+        body = {
+            "CANO": self._account_no,
+            "ACNT_PRDT_CD": self._product_cd,
+            "KRX_FWDG_ORD_ORGNO": krx_fwdg_ord_orgno,
+            "ORGN_ODNO": orgn_odno,
+            "ORD_DVSN": "00",
+            "ORD_QTY": str(qty),
+            "ORD_UNPR": "0",
+            "RVSE_CNCL_DVSN_CD": "02",
+            "QTY_ALL_ORD_YN": "Y",
+        }
+
+        hash_key = await self._get_hash_key(body)
+        headers = await self._auth_headers(tr_id)
+        headers["hashkey"] = hash_key
+
+        url = f"{self._base_url}/uapi/domestic-stock/v1/trading/order-rvsecncl"
+
+        try:
+            async with session.post(url, headers=headers, json=body) as resp:
+                if resp.status != 200:
+                    text = await resp.text()
+                    raise ConnectionError(f"cancel_domestic_order failed ({resp.status}): {text}")
+                return cast(dict[str, Any], await resp.json())
+        except (TimeoutError, aiohttp.ClientError) as exc:
+            raise ConnectionError(f"Network error cancelling domestic order: {exc}") from exc
+
     async def get_daily_prices(
         self,
         stock_code: str,
@@ -494,6 +592,7 @@ class KISBroker:
 
         # Calculate date range (today and N days ago)
         from datetime import datetime, timedelta
+
         end_date = datetime.now().strftime("%Y%m%d")
         start_date = (datetime.now() - timedelta(days=days + 10)).strftime("%Y%m%d")
 
@@ -512,9 +611,7 @@ class KISBroker:
             async with session.get(url, headers=headers, params=params) as resp:
                 if resp.status != 200:
                     text = await resp.text()
-                    raise ConnectionError(
-                        f"get_daily_prices failed ({resp.status}): {text}"
-                    )
+                    raise ConnectionError(f"get_daily_prices failed ({resp.status}): {text}")
                 data = await resp.json()
 
             # Parse response
@@ -528,14 +625,16 @@ class KISBroker:
 
             prices = []
             for item in data.get("output2", []):
-                prices.append({
-                    "date": item.get("stck_bsop_date", ""),
-                    "open": _safe_float(item.get("stck_oprc", "0")),
-                    "high": _safe_float(item.get("stck_hgpr", "0")),
-                    "low": _safe_float(item.get("stck_lwpr", "0")),
-                    "close": _safe_float(item.get("stck_clpr", "0")),
-                    "volume": _safe_float(item.get("acml_vol", "0")),
-                })
+                prices.append(
+                    {
+                        "date": item.get("stck_bsop_date", ""),
+                        "open": _safe_float(item.get("stck_oprc", "0")),
+                        "high": _safe_float(item.get("stck_hgpr", "0")),
+                        "low": _safe_float(item.get("stck_lwpr", "0")),
+                        "close": _safe_float(item.get("stck_clpr", "0")),
+                        "volume": _safe_float(item.get("acml_vol", "0")),
+                    }
+                )
 
             # Sort oldest to newest (KIS returns newest first)
             prices.reverse()

src/broker/overseas.py

@@ -29,6 +29,20 @@ _RANKING_EXCHANGE_MAP: dict[str, str] = {
 # NASD → NAS, NYSE → NYS, AMEX → AMS (confirmed: AMEX returns empty, AMS returns price).
 _PRICE_EXCHANGE_MAP: dict[str, str] = _RANKING_EXCHANGE_MAP
 
+# Cancel order TR_IDs per exchange code — (live_tr_id, paper_tr_id).
+# Source: 한국투자증권 오픈API 전체문서 (20260221) — '해외주식 주문취소' 시트
+_CANCEL_TR_ID_MAP: dict[str, tuple[str, str]] = {
+    "NASD": ("TTTT1004U", "VTTT1004U"),
+    "NYSE": ("TTTT1004U", "VTTT1004U"),
+    "AMEX": ("TTTT1004U", "VTTT1004U"),
+    "SEHK": ("TTTS1003U", "VTTS1003U"),
+    "TSE": ("TTTS0309U", "VTTS0309U"),
+    "SHAA": ("TTTS0302U", "VTTS0302U"),
+    "SZAA": ("TTTS0306U", "VTTS0306U"),
+    "HNX": ("TTTS0312U", "VTTS0312U"),
+    "HSX": ("TTTS0312U", "VTTS0312U"),
+}
+
 
 class OverseasBroker:
     """KIS Overseas Stock API wrapper that reuses KISBroker infrastructure."""
@@ -42,9 +56,7 @@ class OverseasBroker:
         """
         self._broker = kis_broker
 
-    async def get_overseas_price(
-        self, exchange_code: str, stock_code: str
-    ) -> dict[str, Any]:
+    async def get_overseas_price(self, exchange_code: str, stock_code: str) -> dict[str, Any]:
         """
         Fetch overseas stock price.
 
@@ -75,14 +87,10 @@ class OverseasBroker:
             async with session.get(url, headers=headers, params=params) as resp:
                 if resp.status != 200:
                     text = await resp.text()
-                    raise ConnectionError(
-                        f"get_overseas_price failed ({resp.status}): {text}"
-                    )
+                    raise ConnectionError(f"get_overseas_price failed ({resp.status}): {text}")
                 return await resp.json()
         except (TimeoutError, aiohttp.ClientError) as exc:
-            raise ConnectionError(
-                f"Network error fetching overseas price: {exc}"
-            ) from exc
+            raise ConnectionError(f"Network error fetching overseas price: {exc}") from exc
 
     async def fetch_overseas_rankings(
         self,
@@ -107,6 +115,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",
@@ -116,10 +125,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",
             }
 
@@ -138,9 +148,7 @@ class OverseasBroker:
                             ranking_type,
                         )
                         return []
-                    raise ConnectionError(
-                        f"fetch_overseas_rankings failed ({resp.status}): {text}"
-                    )
+                    raise ConnectionError(f"fetch_overseas_rankings failed ({resp.status}): {text}")
 
                 data = await resp.json()
                 rows = self._extract_ranking_rows(data)
@@ -155,9 +163,7 @@ class OverseasBroker:
                 )
                 return []
         except (TimeoutError, aiohttp.ClientError) as exc:
-            raise ConnectionError(
-                f"Network error fetching overseas rankings: {exc}"
-            ) from exc
+            raise ConnectionError(f"Network error fetching overseas rankings: {exc}") from exc
 
     async def get_overseas_balance(self, exchange_code: str) -> dict[str, Any]:
         """
@@ -175,8 +181,10 @@ class OverseasBroker:
         await self._broker._rate_limiter.acquire()
         session = self._broker._get_session()
 
-        # Virtual trading TR_ID for overseas balance inquiry
-        headers = await self._broker._auth_headers("VTTS3012R")
+        # TR_ID: 실전 TTTS3012R, 모의 VTTS3012R
+        # Source: 한국투자증권 오픈API 전체문서 (20260221) — '해외주식 잔고조회' 시트
+        balance_tr_id = "TTTS3012R" if self._broker._settings.MODE == "live" else "VTTS3012R"
+        headers = await self._broker._auth_headers(balance_tr_id)
         params = {
             "CANO": self._broker._account_no,
             "ACNT_PRDT_CD": self._broker._product_cd,
@@ -185,22 +193,63 @@ class OverseasBroker:
             "CTX_AREA_FK200": "",
             "CTX_AREA_NK200": "",
         }
-        url = (
-            f"{self._broker._base_url}/uapi/overseas-stock/v1/trading/inquire-balance"
-        )
+        url = f"{self._broker._base_url}/uapi/overseas-stock/v1/trading/inquire-balance"
+
+        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_balance failed ({resp.status}): {text}")
+                return await resp.json()
+        except (TimeoutError, aiohttp.ClientError) as exc:
+            raise ConnectionError(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_balance failed ({resp.status}): {text}"
+                        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 balance: {exc}"
-            ) from exc
+            raise ConnectionError(f"Network error fetching overseas buying power: {exc}") from exc
 
     async def send_overseas_order(
         self,
@@ -229,10 +278,12 @@ class OverseasBroker:
         await self._broker._rate_limiter.acquire()
         session = self._broker._get_session()
 
-        # Virtual trading TR_IDs for overseas orders
+        # TR_ID: 실전 BUY=TTTT1002U SELL=TTTT1006U, 모의 BUY=VTTT1002U SELL=VTTT1001U
         # Source: 한국투자증권 오픈API 전체문서 (20260221) — '해외주식 주문' 시트
-        # VTTT1002U: 모의투자 미국 매수, VTTT1001U: 모의투자 미국 매도
-        tr_id = "VTTT1002U" if order_type == "BUY" else "VTTT1001U"
+        if self._broker._settings.MODE == "live":
+            tr_id = "TTTT1002U" if order_type == "BUY" else "TTTT1006U"
+        else:
+            tr_id = "VTTT1002U" if order_type == "BUY" else "VTTT1001U"
 
         body = {
             "CANO": self._broker._account_no,
@@ -255,9 +306,7 @@ class OverseasBroker:
             async with session.post(url, headers=headers, json=body) as resp:
                 if resp.status != 200:
                     text = await resp.text()
-                    raise ConnectionError(
-                        f"send_overseas_order failed ({resp.status}): {text}"
-                    )
+                    raise ConnectionError(f"send_overseas_order failed ({resp.status}): {text}")
                 data = await resp.json()
                 rt_cd = data.get("rt_cd", "")
                 msg1 = data.get("msg1", "")
@@ -282,9 +331,118 @@ class OverseasBroker:
                     )
                 return data
         except (TimeoutError, aiohttp.ClientError) as exc:
-            raise ConnectionError(
-                f"Network error sending overseas order: {exc}"
-            ) from exc
+            raise ConnectionError(f"Network error sending overseas order: {exc}") from exc
+
+    async def get_overseas_pending_orders(self, exchange_code: str) -> list[dict[str, Any]]:
+        """Fetch unfilled (pending) overseas orders for a given exchange.
+
+        Args:
+            exchange_code: Exchange code (e.g., "NASD", "SEHK").
+                For US markets, NASD returns all US pending orders (NASD/NYSE/AMEX).
+
+        Returns:
+            List of pending order dicts with fields: odno, pdno, sll_buy_dvsn_cd,
+            ft_ord_qty, nccs_qty, ft_ord_unpr3, ovrs_excg_cd.
+            Always returns [] in paper mode (TTTS3018R is live-only).
+
+        Raises:
+            ConnectionError: On network or API errors (live mode only).
+        """
+        if self._broker._settings.MODE != "live":
+            logger.debug("Pending orders API (TTTS3018R) not supported in paper mode; returning []")
+            return []
+
+        await self._broker._rate_limiter.acquire()
+        session = self._broker._get_session()
+
+        # TTTS3018R: 해외주식 미체결내역조회 (실전 전용)
+        # Source: 한국투자증권 오픈API 전체문서 (20260221) — '해외주식 미체결조회' 시트
+        headers = await self._broker._auth_headers("TTTS3018R")
+        params = {
+            "CANO": self._broker._account_no,
+            "ACNT_PRDT_CD": self._broker._product_cd,
+            "OVRS_EXCG_CD": exchange_code,
+            "SORT_SQN": "DS",
+            "CTX_AREA_FK200": "",
+            "CTX_AREA_NK200": "",
+        }
+        url = f"{self._broker._base_url}/uapi/overseas-stock/v1/trading/inquire-nccs"
+
+        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_pending_orders failed ({resp.status}): {text}"
+                    )
+                data = await resp.json()
+                output = data.get("output", [])
+                if isinstance(output, list):
+                    return output
+                return []
+        except (TimeoutError, aiohttp.ClientError) as exc:
+            raise ConnectionError(f"Network error fetching pending orders: {exc}") from exc
+
+    async def cancel_overseas_order(
+        self,
+        exchange_code: str,
+        stock_code: str,
+        odno: str,
+        qty: int,
+    ) -> dict[str, Any]:
+        """Cancel an overseas limit order.
+
+        Args:
+            exchange_code: Exchange code (e.g., "NASD", "SEHK").
+            stock_code: Stock ticker symbol.
+            odno: Original order number to cancel.
+            qty: Unfilled quantity to cancel.
+
+        Returns:
+            API response dict containing rt_cd and msg1.
+
+        Raises:
+            ValueError: If exchange_code has no cancel TR_ID mapping.
+            ConnectionError: On network or API errors.
+        """
+        tr_ids = _CANCEL_TR_ID_MAP.get(exchange_code)
+        if tr_ids is None:
+            raise ValueError(f"No cancel TR_ID mapping for exchange: {exchange_code}")
+        live_tr_id, paper_tr_id = tr_ids
+        tr_id = live_tr_id if self._broker._settings.MODE == "live" else paper_tr_id
+
+        await self._broker._rate_limiter.acquire()
+        session = self._broker._get_session()
+
+        # RVSE_CNCL_DVSN_CD="02" means cancel (not revision).
+        # OVRS_ORD_UNPR must be "0" for cancellations.
+        # Source: 한국투자증권 오픈API 전체문서 (20260221) — '해외주식 정정취소주문' 시트
+        body = {
+            "CANO": self._broker._account_no,
+            "ACNT_PRDT_CD": self._broker._product_cd,
+            "OVRS_EXCG_CD": exchange_code,
+            "PDNO": stock_code,
+            "ORGN_ODNO": odno,
+            "RVSE_CNCL_DVSN_CD": "02",
+            "ORD_QTY": str(qty),
+            "OVRS_ORD_UNPR": "0",
+            "ORD_SVR_DVSN_CD": "0",
+        }
+
+        hash_key = await self._broker._get_hash_key(body)
+        headers = await self._broker._auth_headers(tr_id)
+        headers["hashkey"] = hash_key
+
+        url = f"{self._broker._base_url}/uapi/overseas-stock/v1/trading/order-rvsecncl"
+
+        try:
+            async with session.post(url, headers=headers, json=body) as resp:
+                if resp.status != 200:
+                    text = await resp.text()
+                    raise ConnectionError(f"cancel_overseas_order failed ({resp.status}): {text}")
+                return await resp.json()
+        except (TimeoutError, aiohttp.ClientError) as exc:
+            raise ConnectionError(f"Network error cancelling overseas order: {exc}") from exc
 
     def _get_currency_code(self, exchange_code: str) -> str:
         """

src/config.py

@@ -13,11 +13,11 @@ class Settings(BaseSettings):
     KIS_APP_KEY: str
     KIS_APP_SECRET: str
     KIS_ACCOUNT_NO: str  # format: "XXXXXXXX-XX"
-    KIS_BASE_URL: str = "https://openapivts.koreainvestment.com:9443"
+    KIS_BASE_URL: str = "https://openapivts.koreainvestment.com:29443"
 
     # Google Gemini
     GEMINI_API_KEY: str
-    GEMINI_MODEL: str = "gemini-pro"
+    GEMINI_MODEL: str = "gemini-2.0-flash"
 
     # External Data APIs (optional — for data-driven decisions)
     NEWS_API_KEY: str | None = None
@@ -59,11 +59,27 @@ class Settings(BaseSettings):
     # KIS VTS overseas balance API returns errors for most accounts.
     # This value is used as a fallback when the balance API returns 0 in paper mode.
     PAPER_OVERSEAS_CASH: float = Field(default=50000.0, ge=0.0)
+    USD_BUFFER_MIN: float = Field(default=1000.0, ge=0.0)
+    US_MIN_PRICE: float = Field(default=5.0, ge=0.0)
+    STAGED_EXIT_BE_ARM_PCT: float = Field(default=1.2, gt=0.0, le=30.0)
+    STAGED_EXIT_ARM_PCT: float = Field(default=3.0, gt=0.0, le=100.0)
+    STOPLOSS_REENTRY_COOLDOWN_MINUTES: int = Field(default=120, ge=1, le=1440)
+    KR_ATR_STOP_MULTIPLIER_K: float = Field(default=2.0, ge=0.1, le=10.0)
+    KR_ATR_STOP_MIN_PCT: float = Field(default=-2.0, le=0.0)
+    KR_ATR_STOP_MAX_PCT: float = Field(default=-7.0, le=0.0)
+    OVERNIGHT_EXCEPTION_ENABLED: bool = True
+    SESSION_RISK_RELOAD_ENABLED: bool = True
+    SESSION_RISK_PROFILES_JSON: str = "{}"
 
     # Trading frequency mode (daily = batch API calls, realtime = per-stock calls)
     TRADE_MODE: str = Field(default="daily", pattern="^(daily|realtime)$")
     DAILY_SESSIONS: int = Field(default=4, ge=1, le=10)
     SESSION_INTERVAL_HOURS: int = Field(default=6, ge=1, le=24)
+    ORDER_BLACKOUT_ENABLED: bool = True
+    ORDER_BLACKOUT_WINDOWS_KST: str = "23:30-00:10"
+    ORDER_BLACKOUT_QUEUE_MAX: int = Field(default=500, ge=10, le=5000)
+    BLACKOUT_RECOVERY_PRICE_REVALIDATION_ENABLED: bool = True
+    BLACKOUT_RECOVERY_MAX_PRICE_DRIFT_PCT: float = Field(default=5.0, ge=0.0, le=100.0)
 
     # Pre-Market Planner
     PRE_MARKET_MINUTES: int = Field(default=30, ge=10, le=120)
@@ -95,25 +111,21 @@ class Settings(BaseSettings):
 
     # Telegram notification type filters (granular control)
     # circuit_breaker is always sent regardless — safety-critical
-    TELEGRAM_NOTIFY_TRADES: bool = True           # BUY/SELL execution alerts
+    TELEGRAM_NOTIFY_TRADES: bool = True  # BUY/SELL execution alerts
     TELEGRAM_NOTIFY_MARKET_OPEN_CLOSE: bool = True  # Market open/close alerts
-    TELEGRAM_NOTIFY_FAT_FINGER: bool = True       # Fat-finger rejection alerts
-    TELEGRAM_NOTIFY_SYSTEM_EVENTS: bool = True    # System start/shutdown alerts
-    TELEGRAM_NOTIFY_PLAYBOOK: bool = True         # Playbook generated/failed alerts
-    TELEGRAM_NOTIFY_SCENARIO_MATCH: bool = True   # Scenario matched alerts (most frequent)
-    TELEGRAM_NOTIFY_ERRORS: bool = True           # Error alerts
+    TELEGRAM_NOTIFY_FAT_FINGER: bool = True  # Fat-finger rejection alerts
+    TELEGRAM_NOTIFY_SYSTEM_EVENTS: bool = True  # System start/shutdown alerts
+    TELEGRAM_NOTIFY_PLAYBOOK: bool = True  # Playbook generated/failed alerts
+    TELEGRAM_NOTIFY_SCENARIO_MATCH: bool = True  # Scenario matched alerts (most frequent)
+    TELEGRAM_NOTIFY_ERRORS: bool = True  # Error alerts
 
     # Overseas ranking API (KIS endpoint/TR_ID may vary by account/product)
     # Override these from .env if your account uses different specs.
     OVERSEAS_RANKING_ENABLED: bool = True
     OVERSEAS_RANKING_FLUCT_TR_ID: str = "HHDFS76290000"
     OVERSEAS_RANKING_VOLUME_TR_ID: str = "HHDFS76270000"
-    OVERSEAS_RANKING_FLUCT_PATH: str = (
-        "/uapi/overseas-stock/v1/ranking/updown-rate"
-    )
-    OVERSEAS_RANKING_VOLUME_PATH: str = (
-        "/uapi/overseas-stock/v1/ranking/volume-surge"
-    )
+    OVERSEAS_RANKING_FLUCT_PATH: str = "/uapi/overseas-stock/v1/ranking/updown-rate"
+    OVERSEAS_RANKING_VOLUME_PATH: str = "/uapi/overseas-stock/v1/ranking/volume-surge"
 
     # Dashboard (optional)
     DASHBOARD_ENABLED: bool = False

src/context/aggregator.py

@@ -222,9 +222,7 @@ class ContextAggregator:
 
         total_pnl = 0.0
         for month in months:
-            monthly_pnl = self.store.get_context(
-                ContextLayer.L4_MONTHLY, month, "monthly_pnl"
-            )
+            monthly_pnl = self.store.get_context(ContextLayer.L4_MONTHLY, month, "monthly_pnl")
             if monthly_pnl is not None:
                 total_pnl += monthly_pnl
 
@@ -251,9 +249,7 @@ class ContextAggregator:
             if quarterly_pnl is not None:
                 total_pnl += quarterly_pnl
 
-        self.store.set_context(
-            ContextLayer.L2_ANNUAL, year, "annual_pnl", round(total_pnl, 2)
-        )
+        self.store.set_context(ContextLayer.L2_ANNUAL, year, "annual_pnl", round(total_pnl, 2))
 
     def aggregate_legacy_from_annual(self) -> None:
         """Aggregate L1 (legacy) context from all L2 (annual) data."""
@@ -280,9 +276,7 @@ class ContextAggregator:
             self.store.set_context(
                 ContextLayer.L1_LEGACY, "LEGACY", "total_pnl", round(total_pnl, 2)
             )
-            self.store.set_context(
-                ContextLayer.L1_LEGACY, "LEGACY", "years_traded", years_traded
-            )
+            self.store.set_context(ContextLayer.L1_LEGACY, "LEGACY", "years_traded", years_traded)
             self.store.set_context(
                 ContextLayer.L1_LEGACY,
                 "LEGACY",

src/context/layer.py

@@ -3,10 +3,10 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from enum import Enum
+from enum import StrEnum
 
 
-class ContextLayer(str, Enum):
+class ContextLayer(StrEnum):
     """7-tier context hierarchy from real-time to generational."""
 
     L1_LEGACY = "L1_LEGACY"  # Cumulative/generational wisdom

src/context/summarizer.py

@@ -9,7 +9,7 @@ This module summarizes old context data instead of including raw details:
 from __future__ import annotations
 
 from dataclasses import dataclass
-from datetime import UTC, datetime, timedelta
+from datetime import UTC, datetime
 from typing import Any
 
 from src.context.layer import ContextLayer

src/core/blackout_manager.py

@@ -0,0 +1,114 @@
+"""Blackout policy and queued order-intent manager."""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from datetime import UTC, datetime, time
+from zoneinfo import ZoneInfo
+
+
+@dataclass(frozen=True)
+class BlackoutWindow:
+    start: time
+    end: time
+
+    def contains(self, kst_time: time) -> bool:
+        if self.start <= self.end:
+            return self.start <= kst_time < self.end
+        return kst_time >= self.start or kst_time < self.end
+
+
+@dataclass
+class QueuedOrderIntent:
+    market_code: str
+    exchange_code: str
+    session_id: str
+    stock_code: str
+    order_type: str
+    quantity: int
+    price: float
+    source: str
+    queued_at: datetime
+    attempts: int = 0
+
+
+def parse_blackout_windows_kst(raw: str) -> list[BlackoutWindow]:
+    """Parse comma-separated KST windows like '23:30-00:10,11:20-11:30'."""
+    windows: list[BlackoutWindow] = []
+    for token in raw.split(","):
+        span = token.strip()
+        if not span or "-" not in span:
+            continue
+        start_raw, end_raw = [part.strip() for part in span.split("-", 1)]
+        try:
+            start_h, start_m = [int(v) for v in start_raw.split(":", 1)]
+            end_h, end_m = [int(v) for v in end_raw.split(":", 1)]
+        except (ValueError, TypeError):
+            continue
+        if not (0 <= start_h <= 23 and 0 <= end_h <= 23):
+            continue
+        if not (0 <= start_m <= 59 and 0 <= end_m <= 59):
+            continue
+        windows.append(BlackoutWindow(start=time(start_h, start_m), end=time(end_h, end_m)))
+    return windows
+
+
+class BlackoutOrderManager:
+    """Tracks blackout mode and queues order intents until recovery."""
+
+    def __init__(
+        self,
+        *,
+        enabled: bool,
+        windows: list[BlackoutWindow],
+        max_queue_size: int = 500,
+    ) -> None:
+        self.enabled = enabled
+        self._windows = windows
+        self._queue: deque[QueuedOrderIntent] = deque()
+        self._was_blackout = False
+        self._max_queue_size = max_queue_size
+        self._overflow_drop_count = 0
+
+    @property
+    def pending_count(self) -> int:
+        return len(self._queue)
+
+    @property
+    def overflow_drop_count(self) -> int:
+        return self._overflow_drop_count
+
+    def in_blackout(self, now: datetime | None = None) -> bool:
+        if not self.enabled or not self._windows:
+            return False
+        now = now or datetime.now(UTC)
+        kst_now = now.astimezone(ZoneInfo("Asia/Seoul")).timetz().replace(tzinfo=None)
+        return any(window.contains(kst_now) for window in self._windows)
+
+    def enqueue(self, intent: QueuedOrderIntent) -> bool:
+        if self._max_queue_size <= 0:
+            return False
+        if len(self._queue) >= self._max_queue_size:
+            self._queue.popleft()
+            self._overflow_drop_count += 1
+        self._queue.append(intent)
+        return True
+
+    def pop_recovery_batch(self, now: datetime | None = None) -> list[QueuedOrderIntent]:
+        in_blackout_now = self.in_blackout(now)
+        batch: list[QueuedOrderIntent] = []
+        if not in_blackout_now and self._queue:
+            while self._queue:
+                batch.append(self._queue.popleft())
+        self._was_blackout = in_blackout_now
+        return batch
+
+    def requeue(self, intent: QueuedOrderIntent) -> None:
+        if len(self._queue) < self._max_queue_size:
+            self._queue.append(intent)
+
+    def clear(self) -> int:
+        count = len(self._queue)
+        self._queue.clear()
+        return count

src/core/kill_switch.py

@@ -0,0 +1,72 @@
+"""Kill switch orchestration for emergency risk actions.
+
+Order is fixed:
+1) block new orders
+2) cancel pending orders
+3) refresh order state
+4) reduce risk
+5) snapshot and notify
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+StepCallable = Callable[[], Any | Awaitable[Any]]
+
+
+@dataclass
+class KillSwitchReport:
+    reason: str
+    steps: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+
+class KillSwitchOrchestrator:
+    def __init__(self) -> None:
+        self.new_orders_blocked = False
+
+    async def _run_step(
+        self,
+        report: KillSwitchReport,
+        name: str,
+        fn: StepCallable | None,
+    ) -> None:
+        report.steps.append(name)
+        if fn is None:
+            return
+        try:
+            result = fn()
+            if inspect.isawaitable(result):
+                await result
+        except Exception as exc:  # pragma: no cover - intentionally resilient
+            report.errors.append(f"{name}: {exc}")
+
+    async def trigger(
+        self,
+        *,
+        reason: str,
+        cancel_pending_orders: StepCallable | None = None,
+        refresh_order_state: StepCallable | None = None,
+        reduce_risk: StepCallable | None = None,
+        snapshot_state: StepCallable | None = None,
+        notify: StepCallable | None = None,
+    ) -> KillSwitchReport:
+        report = KillSwitchReport(reason=reason)
+
+        self.new_orders_blocked = True
+        report.steps.append("block_new_orders")
+
+        await self._run_step(report, "cancel_pending_orders", cancel_pending_orders)
+        await self._run_step(report, "refresh_order_state", refresh_order_state)
+        await self._run_step(report, "reduce_risk", reduce_risk)
+        await self._run_step(report, "snapshot_state", snapshot_state)
+        await self._run_step(report, "notify", notify)
+
+        return report
+
+    def clear_block(self) -> None:
+        self.new_orders_blocked = False

src/core/order_policy.py

@@ -0,0 +1,99 @@
+"""Session-aware order policy guards.
+
+Default policy:
+- Low-liquidity sessions must reject market orders (price <= 0).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime, time
+from zoneinfo import ZoneInfo
+
+from src.markets.schedule import MarketInfo
+
+_LOW_LIQUIDITY_SESSIONS = {"NXT_AFTER", "US_PRE", "US_DAY", "US_AFTER"}
+
+
+class OrderPolicyRejectedError(Exception):
+    """Raised when an order violates session policy."""
+
+    def __init__(self, message: str, *, session_id: str, market_code: str) -> None:
+        super().__init__(message)
+        self.session_id = session_id
+        self.market_code = market_code
+
+
+@dataclass(frozen=True)
+class SessionInfo:
+    session_id: str
+    is_low_liquidity: bool
+
+
+def classify_session_id(market: MarketInfo, now: datetime | None = None) -> str:
+    """Classify current session by KST schedule used in v3 docs."""
+    now = now or datetime.now(UTC)
+    # v3 session tables are explicitly defined in KST perspective.
+    kst_time = now.astimezone(ZoneInfo("Asia/Seoul")).timetz().replace(tzinfo=None)
+
+    if market.code == "KR":
+        if time(8, 0) <= kst_time < time(8, 50):
+            return "NXT_PRE"
+        if time(9, 0) <= kst_time < time(15, 30):
+            return "KRX_REG"
+        if time(15, 30) <= kst_time < time(20, 0):
+            return "NXT_AFTER"
+        return "KR_OFF"
+
+    if market.code.startswith("US"):
+        if time(10, 0) <= kst_time < time(18, 0):
+            return "US_DAY"
+        if time(18, 0) <= kst_time < time(23, 30):
+            return "US_PRE"
+        if time(23, 30) <= kst_time or kst_time < time(6, 0):
+            return "US_REG"
+        if time(6, 0) <= kst_time < time(7, 0):
+            return "US_AFTER"
+        return "US_OFF"
+
+    return "GENERIC_REG"
+
+
+def get_session_info(market: MarketInfo, now: datetime | None = None) -> SessionInfo:
+    session_id = classify_session_id(market, now)
+    return SessionInfo(
+        session_id=session_id, is_low_liquidity=session_id in _LOW_LIQUIDITY_SESSIONS
+    )
+
+
+def validate_order_policy(
+    *,
+    market: MarketInfo,
+    order_type: str,
+    price: float,
+    now: datetime | None = None,
+) -> SessionInfo:
+    """Validate order against session policy and return resolved session info."""
+    info = get_session_info(market, now)
+
+    is_market_order = price <= 0
+    if info.is_low_liquidity and is_market_order:
+        raise OrderPolicyRejectedError(
+            f"Market order is forbidden in low-liquidity session ({info.session_id})",
+            session_id=info.session_id,
+            market_code=market.code,
+        )
+
+    # Guard against accidental unsupported actions.
+    if order_type not in {"BUY", "SELL"}:
+        raise OrderPolicyRejectedError(
+            f"Unsupported order_type={order_type}",
+            session_id=info.session_id,
+            market_code=market.code,
+        )
+
+    return info
+
+
+# Backward compatibility alias
+OrderPolicyRejected = OrderPolicyRejectedError

src/core/priority_queue.py

@@ -28,9 +28,7 @@ class PriorityTask:
     # Task data not used in comparison
     task_id: str = field(compare=False)
     task_data: dict[str, Any] = field(compare=False, default_factory=dict)
-    callback: Callable[[], Coroutine[Any, Any, Any]] | None = field(
-        compare=False, default=None
-    )
+    callback: Callable[[], Coroutine[Any, Any, Any]] | None = field(compare=False, default=None)
 
 
 @dataclass

src/core/risk_manager.py

@@ -25,7 +25,7 @@ class CircuitBreakerTripped(SystemExit):
         )
 
 
-class FatFingerRejected(Exception):
+class FatFingerRejectedError(Exception):
     """Raised when an order exceeds the maximum allowed proportion of cash."""
 
     def __init__(self, order_amount: float, total_cash: float, max_pct: float) -> None:
@@ -61,7 +61,7 @@ class RiskManager:
     def check_fat_finger(self, order_amount: float, total_cash: float) -> None:
         """Reject orders that exceed the maximum proportion of available cash."""
         if total_cash <= 0:
-            raise FatFingerRejected(order_amount, total_cash, self._ff_max_pct)
+            raise FatFingerRejectedError(order_amount, total_cash, self._ff_max_pct)
 
         ratio_pct = (order_amount / total_cash) * 100
         if ratio_pct > self._ff_max_pct:
@@ -69,7 +69,7 @@ class RiskManager:
                 "Fat finger check failed",
                 extra={"order_amount": order_amount},
             )
-            raise FatFingerRejected(order_amount, total_cash, self._ff_max_pct)
+            raise FatFingerRejectedError(order_amount, total_cash, self._ff_max_pct)
 
     def validate_order(
         self,
@@ -81,3 +81,7 @@ class RiskManager:
         self.check_circuit_breaker(current_pnl_pct)
         self.check_fat_finger(order_amount, total_cash)
         logger.info("Order passed risk validation")
+
+
+# Backward compatibility alias
+FatFingerRejected = FatFingerRejectedError

src/dashboard/app.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import json
 import os
 import sqlite3
-from datetime import UTC, datetime, timezone
+from datetime import UTC, datetime
 from pathlib import Path
 from typing import Any
 
@@ -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,
@@ -186,10 +188,7 @@ def create_dashboard_app(db_path: str) -> FastAPI:
                 return {
                     "market": "all",
                     "combined": combined,
-                    "by_market": [
-                        _row_to_performance(row)
-                        for row in by_market_rows
-                    ],
+                    "by_market": [_row_to_performance(row) for row in by_market_rows],
                 }
 
             row = conn.execute(
@@ -399,7 +398,7 @@ def create_dashboard_app(db_path: str) -> FastAPI:
                 """
             ).fetchall()
 
-            now = datetime.now(timezone.utc)
+            now = datetime.now(UTC)
             positions = []
             for row in rows:
                 entry_time_str = row["entry_time"]

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 {
@@ -172,6 +185,51 @@
       /* Spinner */
       .spinner { display: inline-block; width: 12px; height: 12px; border: 2px solid var(--border); border-top-color: var(--accent); border-radius: 50%; animation: spin 0.8s linear infinite; }
       @keyframes spin { to { transform: rotate(360deg); } }
+
+      /* Generic panel */
+      .panel {
+        background: var(--panel);
+        border: 1px solid var(--border);
+        border-radius: 10px;
+        padding: 16px;
+        margin-top: 20px;
+      }
+
+      /* Playbook panel - details/summary accordion */
+      .playbook-panel details { border: 1px solid var(--border); border-radius: 4px; margin-bottom: 6px; }
+      .playbook-panel summary { padding: 8px 12px; cursor: pointer; font-weight: 600; background: var(--bg); color: var(--fg); }
+      .playbook-panel summary:hover { color: var(--accent); }
+      .playbook-panel pre { margin: 0; padding: 12px; background: var(--bg); overflow-x: auto;
+                            font-size: 11px; color: #a0c4ff; white-space: pre-wrap; }
+
+      /* Scorecard KPI card grid */
+      .scorecard-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(140px, 1fr)); gap: 10px; }
+      .kpi-card { background: var(--bg); border: 1px solid var(--border); border-radius: 6px; padding: 12px; text-align: center; }
+      .kpi-card .kpi-label { font-size: 11px; color: var(--muted); margin-bottom: 4px; }
+      .kpi-card .kpi-value { font-size: 20px; font-weight: 700; color: var(--fg); }
+
+      /* Scenarios table */
+      .scenarios-table { width: 100%; border-collapse: collapse; font-size: 13px; }
+      .scenarios-table th { background: var(--bg); padding: 8px; text-align: left; border-bottom: 1px solid var(--border);
+                            color: var(--muted); font-size: 11px; font-weight: 600; white-space: nowrap; }
+      .scenarios-table td { padding: 7px 8px; border-bottom: 1px solid rgba(40,69,95,0.5); }
+      .scenarios-table tr:hover td { background: rgba(255,255,255,0.02); }
+
+      /* Context table */
+      .context-table { width: 100%; border-collapse: collapse; font-size: 12px; }
+      .context-table th { background: var(--bg); padding: 8px; text-align: left; border-bottom: 1px solid var(--border);
+                          color: var(--muted); font-size: 11px; font-weight: 600; white-space: nowrap; }
+      .context-table td { padding: 6px 8px; border-bottom: 1px solid rgba(40,69,95,0.5); vertical-align: top; }
+      .context-value { max-height: 60px; overflow-y: auto; color: #a0c4ff; word-break: break-all; }
+
+      /* Common panel select controls */
+      .panel-controls { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; }
+      .panel-controls select, .panel-controls input[type="number"] {
+        background: var(--bg); color: var(--fg); border: 1px solid var(--border);
+        border-radius: 4px; padding: 4px 8px; font-size: 13px; font-family: inherit;
+      }
+      .panel-date { color: var(--muted); font-size: 12px; }
+      .empty-msg { color: var(--muted); text-align: center; padding: 20px 0; font-size: 12px; }
     </style>
   </head>
   <body>
@@ -180,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>
@@ -283,6 +342,72 @@
           </tbody>
         </table>
       </div>
+
+      <!-- playbook panel -->
+      <div class="panel playbook-panel">
+        <div class="panel-header">
+          <span class="panel-title">&#x1F4CB; 프리마켓 플레이북</span>
+          <div class="panel-controls">
+            <select id="pb-market-select" onchange="fetchPlaybook()">
+              <option value="KR">KR</option>
+              <option value="US_NASDAQ">US_NASDAQ</option>
+              <option value="US_NYSE">US_NYSE</option>
+            </select>
+            <span id="pb-date" class="panel-date"></span>
+          </div>
+        </div>
+        <div id="playbook-content"><p class="empty-msg">데이터 없음</p></div>
+      </div>
+
+      <!-- scorecard panel -->
+      <div class="panel">
+        <div class="panel-header">
+          <span class="panel-title">&#x1F4CA; 일간 스코어카드</span>
+          <div class="panel-controls">
+            <select id="sc-market-select" onchange="fetchScorecard()">
+              <option value="KR">KR</option>
+              <option value="US_NASDAQ">US_NASDAQ</option>
+            </select>
+            <span id="sc-date" class="panel-date"></span>
+          </div>
+        </div>
+        <div id="scorecard-grid" class="scorecard-grid"><p class="empty-msg">데이터 없음</p></div>
+      </div>
+
+      <!-- scenarios panel -->
+      <div class="panel">
+        <div class="panel-header">
+          <span class="panel-title">&#x1F3AF; 활성 시나리오 매칭</span>
+          <div class="panel-controls">
+            <select id="scen-market-select" onchange="fetchScenarios()">
+              <option value="KR">KR</option>
+              <option value="US_NASDAQ">US_NASDAQ</option>
+            </select>
+          </div>
+        </div>
+        <div id="scenarios-content"><p class="empty-msg">데이터 없음</p></div>
+      </div>
+
+      <!-- context layer panel -->
+      <div class="panel">
+        <div class="panel-header">
+          <span class="panel-title">&#x1F9E0; 컨텍스트 트리</span>
+          <div class="panel-controls">
+            <select id="ctx-layer-select" onchange="fetchContext()">
+              <option value="L7_REALTIME">L7_REALTIME</option>
+              <option value="L6_DAILY">L6_DAILY</option>
+              <option value="L5_WEEKLY">L5_WEEKLY</option>
+              <option value="L4_MONTHLY">L4_MONTHLY</option>
+              <option value="L3_QUARTERLY">L3_QUARTERLY</option>
+              <option value="L2_YEARLY">L2_YEARLY</option>
+              <option value="L1_LIFETIME">L1_LIFETIME</option>
+            </select>
+            <input id="ctx-limit" type="number" value="20" min="1" max="200"
+                   style="width:60px;" onchange="fetchContext()">
+          </div>
+        </div>
+        <div id="context-content"><p class="empty-msg">데이터 없음</p></div>
+      </div>
     </div>
 
     <script>
@@ -401,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');
@@ -521,6 +659,117 @@
         fetchDecisions(currentMarket);
       }
 
+      function todayStr() {
+        return new Date().toISOString().slice(0, 10);
+      }
+
+      function esc(s) {
+        return String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+      }
+
+      async function fetchJSON(url) {
+        const r = await fetch(url);
+        if (!r.ok) throw new Error(`HTTP ${r.status}`);
+        return r.json();
+      }
+
+      async function fetchPlaybook() {
+        const market = document.getElementById('pb-market-select').value;
+        const date = todayStr();
+        document.getElementById('pb-date').textContent = date;
+        const el = document.getElementById('playbook-content');
+        try {
+          const data = await fetchJSON(`/api/playbook/${date}?market=${market}`);
+          const stocks = data.stock_playbooks ?? [];
+          if (stocks.length === 0) {
+            el.innerHTML = '<p class="empty-msg">오늘 플레이북 없음</p>';
+            return;
+          }
+          el.innerHTML = stocks.map(sp =>
+            `<details><summary>${esc(sp.stock_code ?? '?')} — ${esc(sp.signal ?? '')}</summary>` +
+            `<pre>${esc(JSON.stringify(sp, null, 2))}</pre></details>`
+          ).join('');
+        } catch {
+          el.innerHTML = '<p class="empty-msg">플레이북 없음 (오늘 미생성 또는 API 오류)</p>';
+        }
+      }
+
+      async function fetchScorecard() {
+        const market = document.getElementById('sc-market-select').value;
+        const date = todayStr();
+        document.getElementById('sc-date').textContent = date;
+        const el = document.getElementById('scorecard-grid');
+        try {
+          const data = await fetchJSON(`/api/scorecard/${date}?market=${market}`);
+          const sc = data.scorecard ?? {};
+          const entries = Object.entries(sc);
+          if (entries.length === 0) {
+            el.innerHTML = '<p class="empty-msg">스코어카드 없음</p>';
+            return;
+          }
+          el.className = 'scorecard-grid';
+          el.innerHTML = entries.map(([k, v]) => `
+            <div class="kpi-card">
+              <div class="kpi-label">${esc(k)}</div>
+              <div class="kpi-value">${typeof v === 'number' ? v.toFixed(2) : esc(String(v))}</div>
+            </div>`).join('');
+        } catch {
+          el.innerHTML = '<p class="empty-msg">스코어카드 없음 (오늘 미생성 또는 API 오류)</p>';
+        }
+      }
+
+      async function fetchScenarios() {
+        const market = document.getElementById('scen-market-select').value;
+        const date = todayStr();
+        const el = document.getElementById('scenarios-content');
+        try {
+          const data = await fetchJSON(`/api/scenarios/active?market=${market}&date_str=${date}&limit=50`);
+          const matches = data.matches ?? [];
+          if (matches.length === 0) {
+            el.innerHTML = '<p class="empty-msg">활성 시나리오 없음</p>';
+            return;
+          }
+          el.innerHTML = `<table class="scenarios-table">
+            <thead><tr><th>종목</th><th>신호</th><th>신뢰도</th><th>매칭 조건</th></tr></thead>
+            <tbody>${matches.map(m => `
+              <tr>
+                <td>${esc(m.stock_code)}</td>
+                <td>${esc(m.signal ?? '-')}</td>
+                <td>${esc(m.confidence ?? '-')}</td>
+                <td><code style="font-size:11px">${esc(JSON.stringify(m.scenario_match ?? {}))}</code></td>
+              </tr>`).join('')}
+            </tbody></table>`;
+        } catch {
+          el.innerHTML = '<p class="empty-msg">데이터 없음</p>';
+        }
+      }
+
+      async function fetchContext() {
+        const layer = document.getElementById('ctx-layer-select').value;
+        const limit = Math.min(Math.max(parseInt(document.getElementById('ctx-limit').value, 10) || 20, 1), 200);
+        const el = document.getElementById('context-content');
+        try {
+          const data = await fetchJSON(`/api/context/${layer}?limit=${limit}`);
+          const entries = data.entries ?? [];
+          if (entries.length === 0) {
+            el.innerHTML = '<p class="empty-msg">컨텍스트 없음</p>';
+            return;
+          }
+          el.innerHTML = `<table class="context-table">
+            <thead><tr><th>timeframe</th><th>key</th><th>value</th><th>updated</th></tr></thead>
+            <tbody>${entries.map(e => `
+              <tr>
+                <td>${esc(e.timeframe)}</td>
+                <td>${esc(e.key)}</td>
+                <td><div class="context-value">${esc(JSON.stringify(e.value ?? e.raw_value))}</div></td>
+                <td style="font-size:11px;color:var(--muted)">${esc((e.updated_at ?? '').slice(0, 16))}</td>
+              </tr>`).join('')}
+            </tbody></table>`;
+        } catch {
+          el.innerHTML = '<p class="empty-msg">데이터 없음</p>';
+        }
+      }
+
       async function refreshAll() {
         document.getElementById('last-updated').textContent = '업데이트 중...';
         await Promise.all([
@@ -529,6 +778,10 @@
           fetchPositions(),
           fetchPnlHistory(currentDays),
           fetchDecisions(currentMarket),
+          fetchPlaybook(),
+          fetchScorecard(),
+          fetchScenarios(),
+          fetchContext(),
         ]);
         const now = new Date();
         const timeStr = now.toLocaleTimeString('ko-KR', { hour: '2-digit', minute: '2-digit', second: '2-digit', hour12: false });

src/data/economic_calendar.py

@@ -9,7 +9,6 @@ from __future__ import annotations
 import logging
 from dataclasses import dataclass
 from datetime import datetime, timedelta
-from typing import Any
 
 logger = logging.getLogger(__name__)
 

src/db.py

@@ -14,6 +14,11 @@ def init_db(db_path: str) -> sqlite3.Connection:
     if db_path != ":memory:":
         Path(db_path).parent.mkdir(parents=True, exist_ok=True)
     conn = sqlite3.connect(db_path)
+    # Enable WAL mode for concurrent read/write (dashboard + trading loop).
+    # WAL does not apply to in-memory databases.
+    if db_path != ":memory:":
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA busy_timeout=5000")
     conn.execute(
         """
         CREATE TABLE IF NOT EXISTS trades (
@@ -26,14 +31,19 @@ def init_db(db_path: str) -> sqlite3.Connection:
             quantity INTEGER,
             price REAL,
             pnl REAL DEFAULT 0.0,
+            strategy_pnl REAL DEFAULT 0.0,
+            fx_pnl REAL DEFAULT 0.0,
             market TEXT DEFAULT 'KR',
             exchange_code TEXT DEFAULT 'KRX',
-            decision_id TEXT
+            session_id TEXT DEFAULT 'UNKNOWN',
+            selection_context TEXT,
+            decision_id TEXT,
+            mode TEXT DEFAULT 'paper'
         )
         """
     )
 
-    # Migration: Add market and exchange_code columns if they don't exist
+    # Migration: Add columns if they don't exist (backward-compatible schema upgrades)
     cursor = conn.execute("PRAGMA table_info(trades)")
     columns = {row[1] for row in cursor.fetchall()}
 
@@ -45,6 +55,34 @@ def init_db(db_path: str) -> sqlite3.Connection:
         conn.execute("ALTER TABLE trades ADD COLUMN selection_context TEXT")
     if "decision_id" not in columns:
         conn.execute("ALTER TABLE trades ADD COLUMN decision_id TEXT")
+    if "mode" not in columns:
+        conn.execute("ALTER TABLE trades ADD COLUMN mode TEXT DEFAULT 'paper'")
+    session_id_added = False
+    if "session_id" not in columns:
+        conn.execute("ALTER TABLE trades ADD COLUMN session_id TEXT DEFAULT 'UNKNOWN'")
+        session_id_added = True
+    if "strategy_pnl" not in columns:
+        conn.execute("ALTER TABLE trades ADD COLUMN strategy_pnl REAL DEFAULT 0.0")
+    if "fx_pnl" not in columns:
+        conn.execute("ALTER TABLE trades ADD COLUMN fx_pnl REAL DEFAULT 0.0")
+    # Backfill legacy rows where only pnl existed before split accounting columns.
+    conn.execute(
+        """
+        UPDATE trades
+        SET strategy_pnl = pnl, fx_pnl = 0.0
+        WHERE pnl != 0.0
+          AND strategy_pnl = 0.0
+          AND fx_pnl = 0.0
+        """
+    )
+    if session_id_added:
+        conn.execute(
+            """
+            UPDATE trades
+            SET session_id = 'UNKNOWN'
+            WHERE session_id IS NULL OR session_id = ''
+            """
+        )
 
     # Context tree tables for multi-layered memory management
     conn.execute(
@@ -71,6 +109,7 @@ def init_db(db_path: str) -> sqlite3.Connection:
             stock_code TEXT NOT NULL,
             market TEXT NOT NULL,
             exchange_code TEXT NOT NULL,
+            session_id TEXT DEFAULT 'UNKNOWN',
             action TEXT NOT NULL,
             confidence INTEGER NOT NULL,
             rationale TEXT NOT NULL,
@@ -83,6 +122,26 @@ def init_db(db_path: str) -> sqlite3.Connection:
         )
         """
     )
+    decision_columns = {
+        row[1] for row in conn.execute("PRAGMA table_info(decision_logs)").fetchall()
+    }
+    if "session_id" not in decision_columns:
+        conn.execute("ALTER TABLE decision_logs ADD COLUMN session_id TEXT DEFAULT 'UNKNOWN'")
+        conn.execute(
+            """
+            UPDATE decision_logs
+            SET session_id = 'UNKNOWN'
+            WHERE session_id IS NULL OR session_id = ''
+            """
+        )
+    if "outcome_pnl" not in decision_columns:
+        conn.execute("ALTER TABLE decision_logs ADD COLUMN outcome_pnl REAL")
+    if "outcome_accuracy" not in decision_columns:
+        conn.execute("ALTER TABLE decision_logs ADD COLUMN outcome_accuracy INTEGER")
+    if "reviewed" not in decision_columns:
+        conn.execute("ALTER TABLE decision_logs ADD COLUMN reviewed INTEGER DEFAULT 0")
+    if "review_notes" not in decision_columns:
+        conn.execute("ALTER TABLE decision_logs ADD COLUMN review_notes TEXT")
 
     conn.execute(
         """
@@ -125,9 +184,7 @@ def init_db(db_path: str) -> sqlite3.Connection:
     conn.execute(
         "CREATE INDEX IF NOT EXISTS idx_decision_logs_timestamp ON decision_logs(timestamp)"
     )
-    conn.execute(
-        "CREATE INDEX IF NOT EXISTS idx_decision_logs_reviewed ON decision_logs(reviewed)"
-    )
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_decision_logs_reviewed ON decision_logs(reviewed)")
     conn.execute(
         "CREATE INDEX IF NOT EXISTS idx_decision_logs_confidence ON decision_logs(confidence)"
     )
@@ -163,10 +220,14 @@ def log_trade(
     quantity: int = 0,
     price: float = 0.0,
     pnl: float = 0.0,
+    strategy_pnl: float | None = None,
+    fx_pnl: float | None = None,
     market: str = "KR",
     exchange_code: str = "KRX",
+    session_id: str | None = None,
     selection_context: dict[str, any] | None = None,
     decision_id: str | None = None,
+    mode: str = "paper",
 ) -> None:
     """Insert a trade record into the database.
 
@@ -178,21 +239,37 @@ def log_trade(
         rationale: AI decision rationale
         quantity: Number of shares
         price: Trade price
-        pnl: Profit/loss
+        pnl: Total profit/loss (backward compatibility)
+        strategy_pnl: Strategy PnL component
+        fx_pnl: FX PnL component
         market: Market code
         exchange_code: Exchange code
+        session_id: Session identifier (if omitted, auto-derived from market)
         selection_context: Scanner selection data (RSI, volume_ratio, signal, score)
+        decision_id: Unique decision identifier for audit linking
+        mode: Trading mode ('paper' or 'live') for data separation
     """
     # Serialize selection context to JSON
     context_json = json.dumps(selection_context) if selection_context else None
+    resolved_session_id = _resolve_session_id(market=market, session_id=session_id)
+    if strategy_pnl is None and fx_pnl is None:
+        strategy_pnl = pnl
+        fx_pnl = 0.0
+    elif strategy_pnl is None:
+        strategy_pnl = pnl - float(fx_pnl or 0.0) if pnl != 0.0 else 0.0
+    elif fx_pnl is None:
+        fx_pnl = pnl - float(strategy_pnl) if pnl != 0.0 else 0.0
+    if pnl == 0.0 and (strategy_pnl or fx_pnl):
+        pnl = float(strategy_pnl) + float(fx_pnl)
 
     conn.execute(
         """
         INSERT INTO trades (
             timestamp, stock_code, action, confidence, rationale,
-            quantity, price, pnl, market, exchange_code, selection_context, decision_id
+            quantity, price, pnl, strategy_pnl, fx_pnl,
+            market, exchange_code, session_id, selection_context, decision_id, mode
         )
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
         """,
         (
             datetime.now(UTC).isoformat(),
@@ -203,32 +280,76 @@ def log_trade(
             quantity,
             price,
             pnl,
+            strategy_pnl,
+            fx_pnl,
             market,
             exchange_code,
+            resolved_session_id,
             context_json,
             decision_id,
+            mode,
         ),
     )
     conn.commit()
 
 
+def _resolve_session_id(*, market: str, session_id: str | None) -> str:
+    if session_id:
+        return session_id
+    try:
+        from src.core.order_policy import classify_session_id
+        from src.markets.schedule import MARKETS
+
+        market_info = MARKETS.get(market)
+        if market_info is not None:
+            return classify_session_id(market_info)
+    except Exception:
+        pass
+    return "UNKNOWN"
+
+
 def get_latest_buy_trade(
-    conn: sqlite3.Connection, stock_code: str, market: str
+    conn: sqlite3.Connection,
+    stock_code: str,
+    market: str,
+    exchange_code: str | None = None,
 ) -> dict[str, Any] | None:
     """Fetch the most recent BUY trade for a stock and market."""
-    cursor = conn.execute(
-        """
-        SELECT decision_id, price, quantity
-        FROM trades
-        WHERE stock_code = ?
-          AND market = ?
-          AND action = 'BUY'
-          AND decision_id IS NOT NULL
-        ORDER BY timestamp DESC
-        LIMIT 1
-        """,
-        (stock_code, market),
-    )
+    if exchange_code:
+        cursor = conn.execute(
+            """
+            SELECT decision_id, price, quantity, selection_context
+            FROM trades
+            WHERE stock_code = ?
+              AND market = ?
+              AND action = 'BUY'
+              AND decision_id IS NOT NULL
+              AND (
+                  exchange_code = ?
+                  OR exchange_code IS NULL
+                  OR exchange_code = ''
+              )
+            ORDER BY
+              CASE WHEN exchange_code = ? THEN 0 ELSE 1 END,
+              timestamp DESC
+            LIMIT 1
+            """,
+            (stock_code, market, exchange_code, exchange_code),
+        )
+    else:
+        cursor = conn.execute(
+            """
+            SELECT decision_id, price, quantity, selection_context
+            FROM trades
+            WHERE stock_code = ?
+              AND market = ?
+              AND action = 'BUY'
+              AND decision_id IS NOT NULL
+            ORDER BY timestamp DESC
+            LIMIT 1
+            """,
+            (stock_code, market),
+        )
     row = cursor.fetchone()
     if not row:
         return None
@@ -241,10 +362,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
         """,
@@ -253,12 +375,10 @@ 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(
-    conn: sqlite3.Connection, market: str, limit: int = 30
-) -> list[str]:
+def get_recent_symbols(conn: sqlite3.Connection, market: str, limit: int = 30) -> list[str]:
     """Return recent unique symbols for a market, newest first."""
     cursor = conn.execute(
         """

src/evolution/ab_test.py

@@ -90,9 +90,7 @@ class ABTester:
         sharpe_ratio = None
         if len(pnls) > 1:
             mean_return = avg_pnl
-            std_return = (
-                sum((p - mean_return) ** 2 for p in pnls) / (len(pnls) - 1)
-            ) ** 0.5
+            std_return = (sum((p - mean_return) ** 2 for p in pnls) / (len(pnls) - 1)) ** 0.5
             if std_return > 0:
                 sharpe_ratio = mean_return / std_return
 
@@ -198,8 +196,7 @@ class ABTester:
 
         if meets_criteria:
             logger.info(
-                "Strategy '%s' meets deployment criteria: "
-                "win_rate=%.2f%%, trades=%d, avg_pnl=%.2f",
+                "Strategy '%s' meets deployment criteria: win_rate=%.2f%%, trades=%d, avg_pnl=%.2f",
                 result.winner,
                 winning_perf.win_rate,
                 winning_perf.total_trades,

src/evolution/daily_review.py

@@ -60,9 +60,7 @@ class DailyReviewer:
             if isinstance(scenario_match, dict) and scenario_match:
                 matched += 1
         scenario_match_rate = (
-            round((matched / total_decisions) * 100, 2)
-            if total_decisions
-            else 0.0
+            round((matched / total_decisions) * 100, 2) if total_decisions else 0.0
         )
 
         trade_stats = self._conn.execute(

src/evolution/optimizer.py

@@ -9,6 +9,7 @@ This module:
 
 from __future__ import annotations
 
+import ast
 import json
 import logging
 import sqlite3
@@ -28,24 +29,24 @@ from src.logging.decision_logger import DecisionLogger
 logger = logging.getLogger(__name__)
 
 STRATEGIES_DIR = Path("src/strategies")
-STRATEGY_TEMPLATE = textwrap.dedent("""\
-    \"\"\"Auto-generated strategy: {name}
+STRATEGY_TEMPLATE = """\
+\"\"\"Auto-generated strategy: {name}
 
-    Generated at: {timestamp}
-    Rationale: {rationale}
-    \"\"\"
+Generated at: {timestamp}
+Rationale: {rationale}
+\"\"\"
 
-    from __future__ import annotations
-    from typing import Any
-    from src.strategies.base import BaseStrategy
+from __future__ import annotations
+from typing import Any
+from src.strategies.base import BaseStrategy
 
 
-    class {class_name}(BaseStrategy):
-        \"\"\"Strategy: {name}\"\"\"
+class {class_name}(BaseStrategy):
+    \"\"\"Strategy: {name}\"\"\"
 
-        def evaluate(self, market_data: dict[str, Any]) -> dict[str, Any]:
-            {body}
-""")
+    def evaluate(self, market_data: dict[str, Any]) -> dict[str, Any]:
+{body}
+"""
 
 
 class EvolutionOptimizer:
@@ -79,26 +80,26 @@ class EvolutionOptimizer:
         # Convert to dict format for analysis
         failures = []
         for decision in losing_decisions:
-            failures.append({
-                "decision_id": decision.decision_id,
-                "timestamp": decision.timestamp,
-                "stock_code": decision.stock_code,
-                "market": decision.market,
-                "exchange_code": decision.exchange_code,
-                "action": decision.action,
-                "confidence": decision.confidence,
-                "rationale": decision.rationale,
-                "outcome_pnl": decision.outcome_pnl,
-                "outcome_accuracy": decision.outcome_accuracy,
-                "context_snapshot": decision.context_snapshot,
-                "input_data": decision.input_data,
-            })
+            failures.append(
+                {
+                    "decision_id": decision.decision_id,
+                    "timestamp": decision.timestamp,
+                    "stock_code": decision.stock_code,
+                    "market": decision.market,
+                    "exchange_code": decision.exchange_code,
+                    "action": decision.action,
+                    "confidence": decision.confidence,
+                    "rationale": decision.rationale,
+                    "outcome_pnl": decision.outcome_pnl,
+                    "outcome_accuracy": decision.outcome_accuracy,
+                    "context_snapshot": decision.context_snapshot,
+                    "input_data": decision.input_data,
+                }
+            )
 
         return failures
 
-    def identify_failure_patterns(
-        self, failures: list[dict[str, Any]]
-    ) -> dict[str, Any]:
+    def identify_failure_patterns(self, failures: list[dict[str, Any]]) -> dict[str, Any]:
         """Identify patterns in losing decisions.
 
         Analyzes:
@@ -142,12 +143,8 @@ class EvolutionOptimizer:
             total_confidence += failure.get("confidence", 0)
             total_loss += failure.get("outcome_pnl", 0.0)
 
-        patterns["avg_confidence"] = (
-            round(total_confidence / len(failures), 2) if failures else 0.0
-        )
-        patterns["avg_loss"] = (
-            round(total_loss / len(failures), 2) if failures else 0.0
-        )
+        patterns["avg_confidence"] = round(total_confidence / len(failures), 2) if failures else 0.0
+        patterns["avg_loss"] = round(total_loss / len(failures), 2) if failures else 0.0
 
         # Convert Counters to regular dicts for JSON serialization
         patterns["markets"] = dict(patterns["markets"])
@@ -196,7 +193,8 @@ class EvolutionOptimizer:
 
         prompt = (
             "You are a quantitative trading strategy developer.\n"
-            "Analyze these failed trades and their patterns, then generate an improved strategy.\n\n"
+            "Analyze these failed trades and their patterns, "
+            "then generate an improved strategy.\n\n"
             f"Failure Patterns:\n{json.dumps(patterns, indent=2)}\n\n"
             f"Sample Failed Trades (first 5):\n"
             f"{json.dumps(failures[:5], indent=2, default=str)}\n\n"
@@ -213,7 +211,8 @@ class EvolutionOptimizer:
 
         try:
             response = await self._client.aio.models.generate_content(
-                model=self._model_name, contents=prompt,
+                model=self._model_name,
+                contents=prompt,
             )
             body = response.text.strip()
         except Exception as exc:
@@ -235,7 +234,8 @@ class EvolutionOptimizer:
         file_path = STRATEGIES_DIR / file_name
 
         # Indent the body for the class method
-        indented_body = textwrap.indent(body, "            ")
+        normalized_body = textwrap.dedent(body).strip()
+        indented_body = textwrap.indent(normalized_body, "            ")
 
         # Generate rationale from patterns
         rationale = f"Auto-evolved from {len(failures)} failures. "
@@ -247,9 +247,16 @@ class EvolutionOptimizer:
             timestamp=datetime.now(UTC).isoformat(),
             rationale=rationale,
             class_name=class_name,
-            body=indented_body.strip(),
+            body=indented_body.rstrip(),
         )
 
+        try:
+            parsed = ast.parse(content, filename=str(file_path))
+            compile(parsed, filename=str(file_path), mode="exec")
+        except SyntaxError as exc:
+            logger.warning("Generated strategy failed syntax validation: %s", exc)
+            return None
+
         file_path.write_text(content)
         logger.info("Generated strategy file: %s", file_path)
         return file_path
@@ -271,9 +278,7 @@ class EvolutionOptimizer:
             logger.info("Strategy validation PASSED")
             return True
         else:
-            logger.warning(
-                "Strategy validation FAILED:\n%s", result.stdout + result.stderr
-            )
+            logger.warning("Strategy validation FAILED:\n%s", result.stdout + result.stderr)
             # Clean up failing strategy
             strategy_path.unlink(missing_ok=True)
             return False

src/evolution/performance_tracker.py

@@ -187,9 +187,7 @@ class PerformanceTracker:
 
         return metrics
 
-    def calculate_improvement_trend(
-        self, metrics_history: list[StrategyMetrics]
-    ) -> dict[str, Any]:
+    def calculate_improvement_trend(self, metrics_history: list[StrategyMetrics]) -> dict[str, Any]:
         """Calculate improvement trend from historical metrics.
 
         Args:
@@ -229,9 +227,7 @@ class PerformanceTracker:
             "period_count": len(metrics_history),
         }
 
-    def generate_dashboard(
-        self, strategy_name: str | None = None
-    ) -> PerformanceDashboard:
+    def generate_dashboard(self, strategy_name: str | None = None) -> PerformanceDashboard:
         """Generate a comprehensive performance dashboard.
 
         Args:
@@ -260,9 +256,7 @@ class PerformanceTracker:
             improvement_trend=improvement_trend,
         )
 
-    def export_dashboard_json(
-        self, dashboard: PerformanceDashboard
-    ) -> str:
+    def export_dashboard_json(self, dashboard: PerformanceDashboard) -> str:
         """Export dashboard as JSON string.
 
         Args:

src/logging/decision_logger.py

@@ -19,6 +19,7 @@ class DecisionLog:
     stock_code: str
     market: str
     exchange_code: str
+    session_id: str
     action: str
     confidence: int
     rationale: str
@@ -47,6 +48,7 @@ class DecisionLogger:
         rationale: str,
         context_snapshot: dict[str, Any],
         input_data: dict[str, Any],
+        session_id: str | None = None,
     ) -> str:
         """Log a trading decision with full context.
 
@@ -59,20 +61,22 @@ class DecisionLogger:
             rationale: Reasoning for the decision
             context_snapshot: L1-L7 context snapshot at decision time
             input_data: Market data inputs (price, volume, orderbook, etc.)
+            session_id: Runtime session identifier
 
         Returns:
             decision_id: Unique identifier for this decision
         """
         decision_id = str(uuid.uuid4())
         timestamp = datetime.now(UTC).isoformat()
+        resolved_session = session_id or "UNKNOWN"
 
         self.conn.execute(
             """
             INSERT INTO decision_logs (
                 decision_id, timestamp, stock_code, market, exchange_code,
-                action, confidence, rationale, context_snapshot, input_data
+                session_id, action, confidence, rationale, context_snapshot, input_data
             )
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
             """,
             (
                 decision_id,
@@ -80,6 +84,7 @@ class DecisionLogger:
                 stock_code,
                 market,
                 exchange_code,
+                resolved_session,
                 action,
                 confidence,
                 rationale,
@@ -106,7 +111,7 @@ class DecisionLogger:
         query = """
             SELECT
                 decision_id, timestamp, stock_code, market, exchange_code,
-                action, confidence, rationale, context_snapshot, input_data,
+                session_id, action, confidence, rationale, context_snapshot, input_data,
                 outcome_pnl, outcome_accuracy, reviewed, review_notes
             FROM decision_logs
             WHERE reviewed = 0 AND confidence >= ?
@@ -135,9 +140,7 @@ class DecisionLogger:
         )
         self.conn.commit()
 
-    def update_outcome(
-        self, decision_id: str, pnl: float, accuracy: int
-    ) -> None:
+    def update_outcome(self, decision_id: str, pnl: float, accuracy: int) -> None:
         """Update the outcome of a decision after trade execution.
 
         Args:
@@ -168,7 +171,7 @@ class DecisionLogger:
             """
             SELECT
                 decision_id, timestamp, stock_code, market, exchange_code,
-                action, confidence, rationale, context_snapshot, input_data,
+                session_id, action, confidence, rationale, context_snapshot, input_data,
                 outcome_pnl, outcome_accuracy, reviewed, review_notes
             FROM decision_logs
             WHERE decision_id = ?
@@ -196,7 +199,7 @@ class DecisionLogger:
             """
             SELECT
                 decision_id, timestamp, stock_code, market, exchange_code,
-                action, confidence, rationale, context_snapshot, input_data,
+                session_id, action, confidence, rationale, context_snapshot, input_data,
                 outcome_pnl, outcome_accuracy, reviewed, review_notes
             FROM decision_logs
             WHERE confidence >= ?
@@ -223,13 +226,14 @@ class DecisionLogger:
             stock_code=row[2],
             market=row[3],
             exchange_code=row[4],
-            action=row[5],
-            confidence=row[6],
-            rationale=row[7],
-            context_snapshot=json.loads(row[8]),
-            input_data=json.loads(row[9]),
-            outcome_pnl=row[10],
-            outcome_accuracy=row[11],
-            reviewed=bool(row[12]),
-            review_notes=row[13],
+            session_id=row[5] or "UNKNOWN",
+            action=row[6],
+            confidence=row[7],
+            rationale=row[8],
+            context_snapshot=json.loads(row[9]),
+            input_data=json.loads(row[10]),
+            outcome_pnl=row[11],
+            outcome_accuracy=row[12],
+            reviewed=bool(row[13]),
+            review_notes=row[14],
         )

src/markets/schedule.py

@@ -1,7 +1,7 @@
 """Market schedule management with timezone support."""
 
 from dataclasses import dataclass
-from datetime import datetime, time, timedelta
+from datetime import UTC, datetime, time, timedelta
 from zoneinfo import ZoneInfo
 
 
@@ -181,7 +181,10 @@ def is_market_open(market: MarketInfo, now: datetime | None = None) -> bool:
 
 
 def get_open_markets(
-    enabled_markets: list[str] | None = None, now: datetime | None = None
+    enabled_markets: list[str] | None = None,
+    now: datetime | None = None,
+    *,
+    include_extended_sessions: bool = False,
 ) -> list[MarketInfo]:
     """
     Get list of currently open markets.
@@ -196,17 +199,29 @@ def get_open_markets(
     if enabled_markets is None:
         enabled_markets = list(MARKETS.keys())
 
+    def is_available(market: MarketInfo) -> bool:
+        if not include_extended_sessions:
+            return is_market_open(market, now)
+        if market.code == "KR" or market.code.startswith("US"):
+            # Import lazily to avoid module cycle at import-time.
+            from src.core.order_policy import classify_session_id
+
+            session_id = classify_session_id(market, now)
+            return session_id not in {"KR_OFF", "US_OFF"}
+        return is_market_open(market, now)
+
     open_markets = [
-        MARKETS[code]
-        for code in enabled_markets
-        if code in MARKETS and is_market_open(MARKETS[code], now)
+        MARKETS[code] for code in enabled_markets if code in MARKETS and is_available(MARKETS[code])
     ]
 
     return sorted(open_markets, key=lambda m: m.code)
 
 
 def get_next_market_open(
-    enabled_markets: list[str] | None = None, now: datetime | None = None
+    enabled_markets: list[str] | None = None,
+    now: datetime | None = None,
+    *,
+    include_extended_sessions: bool = False,
 ) -> tuple[MarketInfo, datetime]:
     """
     Find the next market that will open and when.
@@ -233,6 +248,21 @@ def get_next_market_open(
     next_open_time: datetime | None = None
     next_market: MarketInfo | None = None
 
+    def first_extended_open_after(market: MarketInfo, start_utc: datetime) -> datetime | None:
+        # Search minute-by-minute for KR/US session transition into active window.
+        # Bounded to 7 days to match existing behavior.
+        from src.core.order_policy import classify_session_id
+
+        ts = start_utc.astimezone(ZoneInfo("UTC")).replace(second=0, microsecond=0)
+        prev_active = classify_session_id(market, ts) not in {"KR_OFF", "US_OFF"}
+        for _ in range(7 * 24 * 60):
+            ts = ts + timedelta(minutes=1)
+            active = classify_session_id(market, ts) not in {"KR_OFF", "US_OFF"}
+            if active and not prev_active:
+                return ts
+            prev_active = active
+        return None
+
     for code in enabled_markets:
         if code not in MARKETS:
             continue
@@ -240,12 +270,17 @@ def get_next_market_open(
         market = MARKETS[code]
         market_now = now.astimezone(market.timezone)
 
+        if include_extended_sessions and (market.code == "KR" or market.code.startswith("US")):
+            ext_open = first_extended_open_after(market, now.astimezone(UTC))
+            if ext_open and (next_open_time is None or ext_open < next_open_time):
+                next_open_time = ext_open
+                next_market = market
+            continue
+
         # Calculate next open time for this market
         for days_ahead in range(7):  # Check next 7 days
             check_date = market_now.date() + timedelta(days=days_ahead)
-            check_datetime = datetime.combine(
-                check_date, market.open_time, tzinfo=market.timezone
-            )
+            check_datetime = datetime.combine(check_date, market.open_time, tzinfo=market.timezone)
 
             # Skip weekends
             if check_datetime.weekday() >= 5:

src/notifications/telegram_client.py

@@ -4,7 +4,7 @@ import asyncio
 import logging
 import time
 from collections.abc import Awaitable, Callable
-from dataclasses import dataclass, fields
+from dataclasses import dataclass
 from enum import Enum
 from typing import ClassVar
 
@@ -136,14 +136,14 @@ class TelegramClient:
         self._enabled = enabled
         self._rate_limiter = LeakyBucket(rate=rate_limit)
         self._session: aiohttp.ClientSession | None = None
-        self._filter = notification_filter if notification_filter is not None else NotificationFilter()
+        self._filter = (
+            notification_filter if notification_filter is not None else NotificationFilter()
+        )
 
         if not enabled:
             logger.info("Telegram notifications disabled via configuration")
         elif bot_token is None or chat_id is None:
-            logger.warning(
-                "Telegram notifications disabled (missing bot_token or chat_id)"
-            )
+            logger.warning("Telegram notifications disabled (missing bot_token or chat_id)")
             self._enabled = False
         else:
             logger.info("Telegram notifications enabled for chat_id=%s", chat_id)
@@ -209,14 +209,12 @@ class TelegramClient:
             async with session.post(url, json=payload) as resp:
                 if resp.status != 200:
                     error_text = await resp.text()
-                    logger.error(
-                        "Telegram API error (status=%d): %s", resp.status, error_text
-                    )
+                    logger.error("Telegram API error (status=%d): %s", resp.status, error_text)
                     return False
                 logger.debug("Telegram message sent: %s", text[:50])
                 return True
 
-        except asyncio.TimeoutError:
+        except TimeoutError:
             logger.error("Telegram message timeout")
             return False
         except aiohttp.ClientError as exc:
@@ -305,9 +303,7 @@ class TelegramClient:
             NotificationMessage(priority=NotificationPriority.LOW, message=message)
         )
 
-    async def notify_circuit_breaker(
-        self, pnl_pct: float, threshold: float
-    ) -> None:
+    async def notify_circuit_breaker(self, pnl_pct: float, threshold: float) -> None:
         """
         Notify circuit breaker activation.
 
@@ -354,9 +350,7 @@ class TelegramClient:
             NotificationMessage(priority=NotificationPriority.HIGH, message=message)
         )
 
-    async def notify_system_start(
-        self, mode: str, enabled_markets: list[str]
-    ) -> None:
+    async def notify_system_start(self, mode: str, enabled_markets: list[str]) -> None:
         """
         Notify system startup.
 
@@ -369,9 +363,7 @@ class TelegramClient:
         mode_emoji = "📝" if mode == "paper" else "💰"
         markets_str = ", ".join(enabled_markets)
         message = (
-            f"<b>{mode_emoji} System Started</b>\n"
-            f"Mode: {mode.upper()}\n"
-            f"Markets: {markets_str}"
+            f"<b>{mode_emoji} System Started</b>\nMode: {mode.upper()}\nMarkets: {markets_str}"
         )
         await self._send_notification(
             NotificationMessage(priority=NotificationPriority.MEDIUM, message=message)
@@ -445,11 +437,7 @@ class TelegramClient:
         """
         if not self._filter.playbook:
             return
-        message = (
-            f"<b>Playbook Failed</b>\n"
-            f"Market: {market}\n"
-            f"Reason: {reason[:200]}"
-        )
+        message = f"<b>Playbook Failed</b>\nMarket: {market}\nReason: {reason[:200]}"
         await self._send_notification(
             NotificationMessage(priority=NotificationPriority.HIGH, message=message)
         )
@@ -469,13 +457,47 @@ class TelegramClient:
             if "circuit breaker" in reason.lower()
             else NotificationPriority.MEDIUM
         )
-        await self._send_notification(
-            NotificationMessage(priority=priority, message=message)
-        )
+        await self._send_notification(NotificationMessage(priority=priority, message=message))
 
-    async def notify_error(
-        self, error_type: str, error_msg: str, context: str
+    async def notify_unfilled_order(
+        self,
+        stock_code: str,
+        market: str,
+        action: str,
+        quantity: int,
+        outcome: str,
+        new_price: float | None = None,
     ) -> None:
+        """Notify about an unfilled overseas order that was cancelled or resubmitted.
+
+        Args:
+            stock_code: Stock ticker symbol.
+            market: Exchange/market code (e.g., "NASD", "SEHK").
+            action: "BUY" or "SELL".
+            quantity: Unfilled quantity.
+            outcome: "cancelled" or "resubmitted".
+            new_price: New order price if resubmitted (None if only cancelled).
+        """
+        if not self._filter.trades:
+            return
+        # SELL resubmit is high priority — position liquidation at risk.
+        # BUY cancel is medium priority — only cash is freed.
+        priority = NotificationPriority.HIGH if action == "SELL" else NotificationPriority.MEDIUM
+        outcome_emoji = "🔄" if outcome == "resubmitted" else "❌"
+        outcome_label = "재주문" if outcome == "resubmitted" else "취소됨"
+        action_emoji = "🔴" if action == "SELL" else "🟢"
+        lines = [
+            f"<b>{outcome_emoji} 미체결 주문 {outcome_label}</b>",
+            f"Symbol: <code>{stock_code}</code> ({market})",
+            f"Action: {action_emoji} {action}",
+            f"Quantity: {quantity:,} shares",
+        ]
+        if new_price is not None:
+            lines.append(f"New Price: {new_price:.4f}")
+        message = "\n".join(lines)
+        await self._send_notification(NotificationMessage(priority=priority, message=message))
+
+    async def notify_error(self, error_type: str, error_msg: str, context: str) -> None:
         """
         Notify system error.
 
@@ -499,9 +521,7 @@ class TelegramClient:
 class TelegramCommandHandler:
     """Handles incoming Telegram commands via long polling."""
 
-    def __init__(
-        self, client: TelegramClient, polling_interval: float = 1.0
-    ) -> None:
+    def __init__(self, client: TelegramClient, polling_interval: float = 1.0) -> None:
         """
         Initialize command handler.
 
@@ -517,9 +537,7 @@ class TelegramCommandHandler:
         self._polling_task: asyncio.Task[None] | None = None
         self._running = False
 
-    def register_command(
-        self, command: str, handler: Callable[[], Awaitable[None]]
-    ) -> None:
+    def register_command(self, command: str, handler: Callable[[], Awaitable[None]]) -> None:
         """
         Register a command handler (no arguments).
 
@@ -630,7 +648,7 @@ class TelegramCommandHandler:
 
                 return updates
 
-        except asyncio.TimeoutError:
+        except TimeoutError:
             logger.debug("getUpdates timeout (normal)")
             return []
         except aiohttp.ClientError as exc:
@@ -655,9 +673,7 @@ class TelegramCommandHandler:
             # Verify chat_id matches configured chat
             chat_id = str(message.get("chat", {}).get("id", ""))
             if chat_id != self._client._chat_id:
-                logger.warning(
-                    "Ignoring command from unauthorized chat_id: %s", chat_id
-                )
+                logger.warning("Ignoring command from unauthorized chat_id: %s", chat_id)
                 return
 
             # Extract command text

src/strategy/exit_rules.py

@@ -0,0 +1,104 @@
+"""Composite exit rules: hard stop, break-even lock, ATR trailing, model assist."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from src.strategy.position_state_machine import PositionState, StateTransitionInput, promote_state
+
+
+@dataclass(frozen=True)
+class ExitRuleConfig:
+    hard_stop_pct: float = -2.0
+    be_arm_pct: float = 1.2
+    arm_pct: float = 3.0
+    atr_multiplier_k: float = 2.2
+    model_prob_threshold: float = 0.62
+
+
+@dataclass(frozen=True)
+class ExitRuleInput:
+    current_price: float
+    entry_price: float
+    peak_price: float
+    atr_value: float = 0.0
+    pred_down_prob: float = 0.0
+    liquidity_weak: bool = False
+
+
+@dataclass(frozen=True)
+class ExitEvaluation:
+    state: PositionState
+    should_exit: bool
+    reason: str
+    unrealized_pnl_pct: float
+    trailing_stop_price: float | None
+
+
+def evaluate_exit(
+    *,
+    current_state: PositionState,
+    config: ExitRuleConfig,
+    inp: ExitRuleInput,
+) -> ExitEvaluation:
+    """Evaluate composite exit logic and return updated state."""
+    if inp.entry_price <= 0 or inp.current_price <= 0:
+        return ExitEvaluation(
+            state=current_state,
+            should_exit=False,
+            reason="invalid_price",
+            unrealized_pnl_pct=0.0,
+            trailing_stop_price=None,
+        )
+
+    unrealized = (inp.current_price - inp.entry_price) / inp.entry_price * 100.0
+    hard_stop_hit = unrealized <= config.hard_stop_pct
+    take_profit_hit = unrealized >= config.arm_pct
+
+    trailing_stop_price: float | None = None
+    trailing_stop_hit = False
+    if inp.atr_value > 0 and inp.peak_price > 0:
+        trailing_stop_price = inp.peak_price - (config.atr_multiplier_k * inp.atr_value)
+        trailing_stop_hit = inp.current_price <= trailing_stop_price
+
+    be_lock_threat = current_state in (PositionState.BE_LOCK, PositionState.ARMED) and (
+        inp.current_price <= inp.entry_price
+    )
+    model_exit_signal = inp.pred_down_prob >= config.model_prob_threshold and inp.liquidity_weak
+
+    next_state = promote_state(
+        current=current_state,
+        inp=StateTransitionInput(
+            unrealized_pnl_pct=unrealized,
+            be_arm_pct=config.be_arm_pct,
+            arm_pct=config.arm_pct,
+            hard_stop_hit=hard_stop_hit,
+            trailing_stop_hit=trailing_stop_hit,
+            model_exit_signal=model_exit_signal,
+            be_lock_threat=be_lock_threat,
+        ),
+    )
+
+    if hard_stop_hit:
+        reason = "hard_stop"
+    elif trailing_stop_hit:
+        reason = "atr_trailing_stop"
+    elif be_lock_threat:
+        reason = "be_lock_threat"
+    elif model_exit_signal:
+        reason = "model_liquidity_exit"
+    elif take_profit_hit:
+        # Backward-compatible immediate profit-taking path.
+        reason = "arm_take_profit"
+    else:
+        reason = "hold"
+
+    should_exit = next_state == PositionState.EXITED or take_profit_hit
+
+    return ExitEvaluation(
+        state=next_state,
+        should_exit=should_exit,
+        reason=reason,
+        unrealized_pnl_pct=unrealized,
+        trailing_stop_price=trailing_stop_price,
+    )

src/strategy/models.py

@@ -8,12 +8,12 @@ Defines the data contracts for the proactive strategy system:
 from __future__ import annotations
 
 from datetime import UTC, date, datetime
-from enum import Enum
+from enum import StrEnum
 
 from pydantic import BaseModel, Field, field_validator
 
 
-class ScenarioAction(str, Enum):
+class ScenarioAction(StrEnum):
     """Actions that can be taken by scenarios."""
 
     BUY = "BUY"
@@ -22,7 +22,7 @@ class ScenarioAction(str, Enum):
     REDUCE_ALL = "REDUCE_ALL"
 
 
-class MarketOutlook(str, Enum):
+class MarketOutlook(StrEnum):
     """AI's assessment of market direction."""
 
     BULLISH = "bullish"
@@ -32,7 +32,7 @@ class MarketOutlook(str, Enum):
     BEARISH = "bearish"
 
 
-class PlaybookStatus(str, Enum):
+class PlaybookStatus(StrEnum):
     """Lifecycle status of a playbook."""
 
     PENDING = "pending"

src/strategy/playbook_store.py

@@ -6,7 +6,6 @@ Designed for the pre-market strategy system (one playbook per market per day).
 
 from __future__ import annotations
 
-import json
 import logging
 import sqlite3
 from datetime import date
@@ -53,8 +52,10 @@ class PlaybookStore:
         row_id = cursor.lastrowid or 0
         logger.info(
             "Saved playbook for %s/%s (%d stocks, %d scenarios)",
-            playbook.date, playbook.market,
-            playbook.stock_count, playbook.scenario_count,
+            playbook.date,
+            playbook.market,
+            playbook.stock_count,
+            playbook.scenario_count,
         )
         return row_id
 

src/strategy/position_state_machine.py

@@ -0,0 +1,65 @@
+"""Position state machine for staged exit control.
+
+State progression is monotonic (promotion-only) except terminal EXITED.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class PositionState(StrEnum):
+    HOLDING = "HOLDING"
+    BE_LOCK = "BE_LOCK"
+    ARMED = "ARMED"
+    EXITED = "EXITED"
+
+
+_STATE_RANK: dict[PositionState, int] = {
+    PositionState.HOLDING: 0,
+    PositionState.BE_LOCK: 1,
+    PositionState.ARMED: 2,
+    PositionState.EXITED: 3,
+}
+
+
+@dataclass(frozen=True)
+class StateTransitionInput:
+    unrealized_pnl_pct: float
+    be_arm_pct: float
+    arm_pct: float
+    hard_stop_hit: bool = False
+    trailing_stop_hit: bool = False
+    model_exit_signal: bool = False
+    be_lock_threat: bool = False
+
+
+def evaluate_exit_first(inp: StateTransitionInput) -> bool:
+    """Return True when terminal exit conditions are met.
+
+    EXITED must be evaluated before any promotion.
+    """
+    return inp.hard_stop_hit or inp.trailing_stop_hit or inp.model_exit_signal or inp.be_lock_threat
+
+
+def promote_state(current: PositionState, inp: StateTransitionInput) -> PositionState:
+    """Promote to highest admissible state for current tick/bar.
+
+    Rules:
+    - EXITED has highest precedence and is terminal.
+    - Promotions are monotonic (no downgrade).
+    """
+    if current == PositionState.EXITED:
+        return PositionState.EXITED
+
+    if evaluate_exit_first(inp):
+        return PositionState.EXITED
+
+    target = PositionState.HOLDING
+    if inp.unrealized_pnl_pct >= inp.arm_pct:
+        target = PositionState.ARMED
+    elif inp.unrealized_pnl_pct >= inp.be_arm_pct:
+        target = PositionState.BE_LOCK
+
+    return target if _STATE_RANK[target] > _STATE_RANK[current] else current

src/strategy/pre_market_planner.py

@@ -124,12 +124,14 @@ class PreMarketPlanner:
 
             # 4. Parse response
             playbook = self._parse_response(
-                decision.rationale, today, market, candidates, cross_market,
+                decision.rationale,
+                today,
+                market,
+                candidates,
+                cross_market,
                 current_holdings=current_holdings,
             )
-            playbook_with_tokens = playbook.model_copy(
-                update={"token_count": decision.token_count}
-            )
+            playbook_with_tokens = playbook.model_copy(update={"token_count": decision.token_count})
             logger.info(
                 "Generated playbook for %s: %d stocks, %d scenarios, %d tokens",
                 market,
@@ -146,7 +148,9 @@ class PreMarketPlanner:
             return self._empty_playbook(today, market)
 
     def build_cross_market_context(
-        self, target_market: str, today: date | None = None,
+        self,
+        target_market: str,
+        today: date | None = None,
     ) -> CrossMarketContext | None:
         """Build cross-market context from the other market's L6 data.
 
@@ -192,7 +196,9 @@ class PreMarketPlanner:
         )
 
     def build_self_market_scorecard(
-        self, market: str, today: date | None = None,
+        self,
+        market: str,
+        today: date | None = None,
     ) -> dict[str, Any] | None:
         """Build previous-day scorecard for the same market."""
         if today is None:
@@ -320,18 +326,18 @@ class PreMarketPlanner:
             f"{context_text}\n"
             f"## Instructions\n"
             f"Return a JSON object with this exact structure:\n"
-            f'{{\n'
+            f"{{\n"
             f'  "market_outlook": "bullish|neutral_to_bullish|neutral'
             f'|neutral_to_bearish|bearish",\n'
             f'  "global_rules": [\n'
             f'    {{"condition": "portfolio_pnl_pct < -2.0",'
             f' "action": "REDUCE_ALL", "rationale": "..."}}\n'
-            f'  ],\n'
+            f"  ],\n"
             f'  "stocks": [\n'
-            f'    {{\n'
+            f"    {{\n"
             f'      "stock_code": "...",\n'
             f'      "scenarios": [\n'
-            f'        {{\n'
+            f"        {{\n"
             f'          "condition": {{"rsi_below": 30, "volume_ratio_above": 2.0,'
             f' "unrealized_pnl_pct_above": 3.0, "holding_days_above": 5}},\n'
             f'          "action": "BUY|SELL|HOLD",\n'
@@ -340,11 +346,11 @@ class PreMarketPlanner:
             f'          "stop_loss_pct": -2.0,\n'
             f'          "take_profit_pct": 3.0,\n'
             f'          "rationale": "..."\n'
-            f'        }}\n'
-            f'      ]\n'
-            f'    }}\n'
-            f'  ]\n'
-            f'}}\n\n'
+            f"        }}\n"
+            f"      ]\n"
+            f"    }}\n"
+            f"  ]\n"
+            f"}}\n\n"
             f"Rules:\n"
             f"- Max {max_scenarios} scenarios per stock\n"
             f"- Candidates list is the primary source for BUY candidates\n"
@@ -575,8 +581,7 @@ class PreMarketPlanner:
                         stop_loss_pct=-3.0,
                         take_profit_pct=5.0,
                         rationale=(
-                            f"Rule-based BUY: oversold signal, "
-                            f"RSI={c.rsi:.0f} (fallback planner)"
+                            f"Rule-based BUY: oversold signal, RSI={c.rsi:.0f} (fallback planner)"
                         ),
                     )
                 )

src/strategy/scenario_engine.py

@@ -107,7 +107,9 @@ class ScenarioEngine:
         # 2. Find stock playbook
         stock_pb = playbook.get_stock_playbook(stock_code)
         if stock_pb is None:
-            logger.debug("No playbook for %s — defaulting to %s", stock_code, playbook.default_action)
+            logger.debug(
+                "No playbook for %s — defaulting to %s", stock_code, playbook.default_action
+            )
             return ScenarioMatch(
                 stock_code=stock_code,
                 matched_scenario=None,
@@ -135,7 +137,9 @@ class ScenarioEngine:
                 )
 
         # 4. No match — default action
-        logger.debug("No scenario matched for %s — defaulting to %s", stock_code, playbook.default_action)
+        logger.debug(
+            "No scenario matched for %s — defaulting to %s", stock_code, playbook.default_action
+        )
         return ScenarioMatch(
             stock_code=stock_code,
             matched_scenario=None,
@@ -198,17 +202,27 @@ class ScenarioEngine:
             checks.append(price is not None and price < condition.price_below)
 
         price_change_pct = self._safe_float(market_data.get("price_change_pct"))
-        if condition.price_change_pct_above is not None or condition.price_change_pct_below is not None:
+        if (
+            condition.price_change_pct_above is not None
+            or condition.price_change_pct_below is not None
+        ):
             if "price_change_pct" not in market_data:
                 self._warn_missing_key("price_change_pct")
         if condition.price_change_pct_above is not None:
-            checks.append(price_change_pct is not None and price_change_pct > condition.price_change_pct_above)
+            checks.append(
+                price_change_pct is not None and price_change_pct > condition.price_change_pct_above
+            )
         if condition.price_change_pct_below is not None:
-            checks.append(price_change_pct is not None and price_change_pct < condition.price_change_pct_below)
+            checks.append(
+                price_change_pct is not None and price_change_pct < condition.price_change_pct_below
+            )
 
         # Position-aware conditions
         unrealized_pnl_pct = self._safe_float(market_data.get("unrealized_pnl_pct"))
-        if condition.unrealized_pnl_pct_above is not None or condition.unrealized_pnl_pct_below is not None:
+        if (
+            condition.unrealized_pnl_pct_above is not None
+            or condition.unrealized_pnl_pct_below is not None
+        ):
             if "unrealized_pnl_pct" not in market_data:
                 self._warn_missing_key("unrealized_pnl_pct")
         if condition.unrealized_pnl_pct_above is not None:
@@ -227,15 +241,9 @@ class ScenarioEngine:
             if "holding_days" not in market_data:
                 self._warn_missing_key("holding_days")
         if condition.holding_days_above is not None:
-            checks.append(
-                holding_days is not None
-                and holding_days > condition.holding_days_above
-            )
+            checks.append(holding_days is not None and holding_days > condition.holding_days_above)
         if condition.holding_days_below is not None:
-            checks.append(
-                holding_days is not None
-                and holding_days < condition.holding_days_below
-            )
+            checks.append(holding_days is not None and holding_days < condition.holding_days_below)
 
         return len(checks) > 0 and all(checks)
 
@@ -295,9 +303,15 @@ class ScenarioEngine:
             details["volume_ratio"] = self._safe_float(market_data.get("volume_ratio"))
         if condition.price_above is not None or condition.price_below is not None:
             details["current_price"] = self._safe_float(market_data.get("current_price"))
-        if condition.price_change_pct_above is not None or condition.price_change_pct_below is not None:
+        if (
+            condition.price_change_pct_above is not None
+            or condition.price_change_pct_below is not None
+        ):
             details["price_change_pct"] = self._safe_float(market_data.get("price_change_pct"))
-        if condition.unrealized_pnl_pct_above is not None or condition.unrealized_pnl_pct_below is not None:
+        if (
+            condition.unrealized_pnl_pct_above is not None
+            or condition.unrealized_pnl_pct_below is not None
+        ):
             details["unrealized_pnl_pct"] = self._safe_float(market_data.get("unrealized_pnl_pct"))
         if condition.holding_days_above is not None or condition.holding_days_below is not None:
             details["holding_days"] = self._safe_float(market_data.get("holding_days"))

tests/test_backtest_cost_guard.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import pytest
+
+from src.analysis.backtest_cost_guard import BacktestCostModel, validate_backtest_cost_model
+
+
+def test_valid_backtest_cost_model_passes() -> None:
+    model = BacktestCostModel(
+        commission_bps=5.0,
+        slippage_bps_by_session={"KRX_REG": 10.0, "US_PRE": 50.0},
+        failure_rate_by_session={"KRX_REG": 0.01, "US_PRE": 0.08},
+        partial_fill_rate_by_session={"KRX_REG": 0.1, "US_PRE": 0.2},
+        unfavorable_fill_required=True,
+    )
+    validate_backtest_cost_model(model=model, required_sessions=["KRX_REG", "US_PRE"])
+
+
+def test_missing_required_slippage_session_raises() -> None:
+    model = BacktestCostModel(
+        commission_bps=5.0,
+        slippage_bps_by_session={"KRX_REG": 10.0},
+        failure_rate_by_session={"KRX_REG": 0.01, "US_PRE": 0.08},
+        partial_fill_rate_by_session={"KRX_REG": 0.1, "US_PRE": 0.2},
+        unfavorable_fill_required=True,
+    )
+    with pytest.raises(ValueError, match="missing slippage_bps_by_session.*US_PRE"):
+        validate_backtest_cost_model(model=model, required_sessions=["KRX_REG", "US_PRE"])
+
+
+def test_missing_required_failure_rate_session_raises() -> None:
+    model = BacktestCostModel(
+        commission_bps=5.0,
+        slippage_bps_by_session={"KRX_REG": 10.0, "US_PRE": 50.0},
+        failure_rate_by_session={"KRX_REG": 0.01},
+        partial_fill_rate_by_session={"KRX_REG": 0.1, "US_PRE": 0.2},
+        unfavorable_fill_required=True,
+    )
+    with pytest.raises(ValueError, match="missing failure_rate_by_session.*US_PRE"):
+        validate_backtest_cost_model(model=model, required_sessions=["KRX_REG", "US_PRE"])
+
+
+def test_invalid_failure_rate_range_raises() -> None:
+    model = BacktestCostModel(
+        commission_bps=5.0,
+        slippage_bps_by_session={"KRX_REG": 10.0},
+        failure_rate_by_session={"KRX_REG": 1.2},
+        partial_fill_rate_by_session={"KRX_REG": 0.2},
+        unfavorable_fill_required=True,
+    )
+    with pytest.raises(ValueError, match="failure rate must be within"):
+        validate_backtest_cost_model(model=model, required_sessions=["KRX_REG"])
+
+
+def test_unfavorable_fill_requirement_cannot_be_disabled() -> None:
+    model = BacktestCostModel(
+        commission_bps=5.0,
+        slippage_bps_by_session={"KRX_REG": 10.0},
+        failure_rate_by_session={"KRX_REG": 0.02},
+        partial_fill_rate_by_session={"KRX_REG": 0.2},
+        unfavorable_fill_required=False,
+    )
+    with pytest.raises(ValueError, match="unfavorable_fill_required must be True"):
+        validate_backtest_cost_model(model=model, required_sessions=["KRX_REG"])
+
+
+@pytest.mark.parametrize("bad_commission", [float("nan"), float("inf"), float("-inf")])
+def test_non_finite_commission_rejected(bad_commission: float) -> None:
+    model = BacktestCostModel(
+        commission_bps=bad_commission,
+        slippage_bps_by_session={"KRX_REG": 10.0},
+        failure_rate_by_session={"KRX_REG": 0.02},
+        partial_fill_rate_by_session={"KRX_REG": 0.2},
+        unfavorable_fill_required=True,
+    )
+    with pytest.raises(ValueError, match="commission_bps"):
+        validate_backtest_cost_model(model=model, required_sessions=["KRX_REG"])
+
+
+@pytest.mark.parametrize("bad_slippage", [float("nan"), float("inf"), float("-inf")])
+def test_non_finite_slippage_rejected(bad_slippage: float) -> None:
+    model = BacktestCostModel(
+        commission_bps=5.0,
+        slippage_bps_by_session={"KRX_REG": bad_slippage},
+        failure_rate_by_session={"KRX_REG": 0.02},
+        partial_fill_rate_by_session={"KRX_REG": 0.2},
+        unfavorable_fill_required=True,
+    )
+    with pytest.raises(ValueError, match="slippage bps"):
+        validate_backtest_cost_model(model=model, required_sessions=["KRX_REG"])
+
+
+def test_missing_required_partial_fill_session_raises() -> None:
+    model = BacktestCostModel(
+        commission_bps=5.0,
+        slippage_bps_by_session={"KRX_REG": 10.0, "US_PRE": 50.0},
+        failure_rate_by_session={"KRX_REG": 0.01, "US_PRE": 0.08},
+        partial_fill_rate_by_session={"KRX_REG": 0.1},
+        unfavorable_fill_required=True,
+    )
+    with pytest.raises(ValueError, match="missing partial_fill_rate_by_session.*US_PRE"):
+        validate_backtest_cost_model(model=model, required_sessions=["KRX_REG", "US_PRE"])
+
+
+@pytest.mark.parametrize("bad_partial_fill", [float("nan"), float("inf"), float("-inf"), -0.1, 1.1])
+def test_invalid_partial_fill_rate_rejected(bad_partial_fill: float) -> None:
+    model = BacktestCostModel(
+        commission_bps=5.0,
+        slippage_bps_by_session={"KRX_REG": 10.0},
+        failure_rate_by_session={"KRX_REG": 0.02},
+        partial_fill_rate_by_session={"KRX_REG": bad_partial_fill},
+        unfavorable_fill_required=True,
+    )
+    with pytest.raises(ValueError, match="partial fill rate must be within"):
+        validate_backtest_cost_model(model=model, required_sessions=["KRX_REG"])

tests/test_backtest_execution_model.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import pytest
+
+from src.analysis.backtest_execution_model import (
+    BacktestExecutionModel,
+    ExecutionAssumptions,
+    ExecutionRequest,
+)
+
+
+def test_buy_uses_unfavorable_slippage_direction() -> None:
+    model = BacktestExecutionModel(
+        ExecutionAssumptions(
+            slippage_bps_by_session={"US_PRE": 50.0},
+            failure_rate_by_session={"US_PRE": 0.0},
+            partial_fill_rate_by_session={"US_PRE": 0.0},
+            seed=1,
+        )
+    )
+    out = model.simulate(
+        ExecutionRequest(side="BUY", session_id="US_PRE", qty=10, reference_price=100.0)
+    )
+    assert out.status == "FILLED"
+    assert out.avg_price == pytest.approx(100.5)
+
+
+def test_sell_uses_unfavorable_slippage_direction() -> None:
+    model = BacktestExecutionModel(
+        ExecutionAssumptions(
+            slippage_bps_by_session={"US_PRE": 50.0},
+            failure_rate_by_session={"US_PRE": 0.0},
+            partial_fill_rate_by_session={"US_PRE": 0.0},
+            seed=1,
+        )
+    )
+    out = model.simulate(
+        ExecutionRequest(side="SELL", session_id="US_PRE", qty=10, reference_price=100.0)
+    )
+    assert out.status == "FILLED"
+    assert out.avg_price == pytest.approx(99.5)
+
+
+def test_failure_rate_can_reject_order() -> None:
+    model = BacktestExecutionModel(
+        ExecutionAssumptions(
+            slippage_bps_by_session={"KRX_REG": 10.0},
+            failure_rate_by_session={"KRX_REG": 1.0},
+            partial_fill_rate_by_session={"KRX_REG": 0.0},
+            seed=42,
+        )
+    )
+    out = model.simulate(
+        ExecutionRequest(side="BUY", session_id="KRX_REG", qty=10, reference_price=100.0)
+    )
+    assert out.status == "REJECTED"
+    assert out.filled_qty == 0
+
+
+def test_partial_fill_applies_when_rate_is_one() -> None:
+    model = BacktestExecutionModel(
+        ExecutionAssumptions(
+            slippage_bps_by_session={"KRX_REG": 0.0},
+            failure_rate_by_session={"KRX_REG": 0.0},
+            partial_fill_rate_by_session={"KRX_REG": 1.0},
+            partial_fill_min_ratio=0.4,
+            partial_fill_max_ratio=0.4,
+            seed=0,
+        )
+    )
+    out = model.simulate(
+        ExecutionRequest(side="BUY", session_id="KRX_REG", qty=10, reference_price=100.0)
+    )
+    assert out.status == "PARTIAL"
+    assert out.filled_qty == 4
+    assert out.avg_price == 100.0
+
+
+@pytest.mark.parametrize("bad_slip", [-1.0, float("nan"), float("inf")])
+def test_invalid_slippage_is_rejected(bad_slip: float) -> None:
+    with pytest.raises(ValueError, match="slippage_bps"):
+        BacktestExecutionModel(
+            ExecutionAssumptions(
+                slippage_bps_by_session={"US_PRE": bad_slip},
+                failure_rate_by_session={"US_PRE": 0.0},
+                partial_fill_rate_by_session={"US_PRE": 0.0},
+            )
+        )
+
+
+@pytest.mark.parametrize("bad_rate", [-0.1, 1.1, float("nan")])
+def test_invalid_failure_or_partial_rates_are_rejected(bad_rate: float) -> None:
+    with pytest.raises(ValueError, match="failure_rate"):
+        BacktestExecutionModel(
+            ExecutionAssumptions(
+                slippage_bps_by_session={"US_PRE": 10.0},
+                failure_rate_by_session={"US_PRE": bad_rate},
+                partial_fill_rate_by_session={"US_PRE": 0.0},
+            )
+        )
+    with pytest.raises(ValueError, match="partial_fill_rate"):
+        BacktestExecutionModel(
+            ExecutionAssumptions(
+                slippage_bps_by_session={"US_PRE": 10.0},
+                failure_rate_by_session={"US_PRE": 0.0},
+                partial_fill_rate_by_session={"US_PRE": bad_rate},
+            )
+        )

tests/test_backtest_pipeline_integration.py

@@ -0,0 +1,220 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+
+from src.analysis.backtest_cost_guard import BacktestCostModel
+from src.analysis.backtest_pipeline import (
+    BacktestBar,
+    WalkForwardConfig,
+    fold_has_leakage,
+    run_v2_backtest_pipeline,
+)
+from src.analysis.triple_barrier import TripleBarrierSpec
+from src.analysis.walk_forward_split import generate_walk_forward_splits
+
+
+def _bars() -> list[BacktestBar]:
+    base_ts = datetime(2026, 2, 28, 0, 0, tzinfo=UTC)
+    closes = [100.0, 101.0, 102.0, 101.5, 103.0, 102.5, 104.0, 103.5, 105.0, 104.5, 106.0, 105.5]
+    bars: list[BacktestBar] = []
+    for i, close in enumerate(closes):
+        bars.append(
+            BacktestBar(
+                high=close + 1.0,
+                low=close - 1.0,
+                close=close,
+                session_id="KRX_REG" if i % 2 == 0 else "US_PRE",
+                timestamp=base_ts + timedelta(minutes=i),
+            )
+        )
+    return bars
+
+
+def _cost_model() -> BacktestCostModel:
+    return BacktestCostModel(
+        commission_bps=3.0,
+        slippage_bps_by_session={"KRX_REG": 10.0, "US_PRE": 50.0},
+        failure_rate_by_session={"KRX_REG": 0.01, "US_PRE": 0.08},
+        partial_fill_rate_by_session={"KRX_REG": 0.05, "US_PRE": 0.2},
+        unfavorable_fill_required=True,
+    )
+
+
+def test_pipeline_happy_path_returns_fold_and_artifact_contract() -> None:
+    out = run_v2_backtest_pipeline(
+        bars=_bars(),
+        entry_indices=[0, 1, 2, 3, 4, 5, 6, 7],
+        side=1,
+        triple_barrier_spec=TripleBarrierSpec(
+            take_profit_pct=0.02,
+            stop_loss_pct=0.01,
+            max_holding_minutes=3,
+        ),
+        walk_forward=WalkForwardConfig(
+            train_size=4,
+            test_size=2,
+            step_size=2,
+            purge_size=1,
+            embargo_size=1,
+            min_train_size=3,
+        ),
+        cost_model=_cost_model(),
+    )
+
+    assert out.run_id.startswith("v2p-e8-f")
+    assert out.n_bars == 12
+    assert out.n_entries == 8
+    assert out.required_sessions == ["KRX_REG", "US_PRE"]
+    assert len(out.folds) > 0
+    assert set(out.label_distribution) == {-1, 0, 1}
+    for fold in out.folds:
+        names = {score.name for score in fold.baseline_scores}
+        assert names == {"B0", "B1", "M1"}
+        for score in fold.baseline_scores:
+            assert 0.0 <= score.accuracy <= 1.0
+            assert 0.0 <= score.cost_adjusted_accuracy <= 1.0
+        assert fold.execution_adjusted_trade_count >= 0
+        assert fold.execution_rejected_count >= 0
+        assert fold.execution_partial_count >= 0
+
+
+def test_pipeline_cost_guard_fail_fast() -> None:
+    bad = BacktestCostModel(
+        commission_bps=3.0,
+        slippage_bps_by_session={"KRX_REG": 10.0},
+        failure_rate_by_session={"KRX_REG": 0.01},
+        partial_fill_rate_by_session={"KRX_REG": 0.05},
+        unfavorable_fill_required=True,
+    )
+    try:
+        run_v2_backtest_pipeline(
+            bars=_bars(),
+            entry_indices=[0, 1, 2, 3],
+            side=1,
+            triple_barrier_spec=TripleBarrierSpec(
+                take_profit_pct=0.02,
+                stop_loss_pct=0.01,
+                max_holding_minutes=3,
+            ),
+            walk_forward=WalkForwardConfig(train_size=2, test_size=1),
+            cost_model=bad,
+            required_sessions=["KRX_REG", "US_PRE"],
+        )
+    except ValueError as exc:
+        assert "missing slippage_bps_by_session" in str(exc)
+    else:
+        raise AssertionError("expected cost guard validation error")
+
+
+def test_pipeline_fold_leakage_guard() -> None:
+    folds = generate_walk_forward_splits(
+        n_samples=12,
+        train_size=6,
+        test_size=2,
+        step_size=2,
+        purge_size=1,
+        embargo_size=1,
+        min_train_size=5,
+    )
+    assert folds
+    for fold in folds:
+        assert not fold_has_leakage(fold)
+
+
+def test_pipeline_deterministic_seed_free_deterministic_result() -> None:
+    cfg = dict(
+        bars=_bars(),
+        entry_indices=[0, 1, 2, 3, 4, 5, 6, 7],
+        side=1,
+        triple_barrier_spec=TripleBarrierSpec(
+            take_profit_pct=0.02,
+            stop_loss_pct=0.01,
+            max_holding_minutes=3,
+        ),
+        walk_forward=WalkForwardConfig(
+            train_size=4,
+            test_size=2,
+            step_size=2,
+            purge_size=1,
+            embargo_size=1,
+            min_train_size=3,
+        ),
+        cost_model=_cost_model(),
+    )
+    out1 = run_v2_backtest_pipeline(**cfg)
+    out2 = run_v2_backtest_pipeline(**cfg)
+    assert out1 == out2
+
+
+def test_pipeline_rejects_minutes_spec_when_timestamp_missing() -> None:
+    bars = _bars()
+    bars[2] = BacktestBar(
+        high=bars[2].high,
+        low=bars[2].low,
+        close=bars[2].close,
+        session_id=bars[2].session_id,
+        timestamp=None,
+    )
+    try:
+        run_v2_backtest_pipeline(
+            bars=bars,
+            entry_indices=[0, 1, 2, 3],
+            side=1,
+            triple_barrier_spec=TripleBarrierSpec(
+                take_profit_pct=0.02,
+                stop_loss_pct=0.01,
+                max_holding_minutes=3,
+            ),
+            walk_forward=WalkForwardConfig(train_size=2, test_size=1),
+            cost_model=_cost_model(),
+        )
+    except ValueError as exc:
+        assert "BacktestBar.timestamp is required" in str(exc)
+    else:
+        raise AssertionError("expected timestamp validation error")
+
+
+def test_pipeline_fold_scores_reflect_cost_and_execution_effects() -> None:
+    cfg = dict(
+        bars=_bars(),
+        entry_indices=[0, 1, 2, 3, 4, 5, 6, 7],
+        side=1,
+        triple_barrier_spec=TripleBarrierSpec(
+            take_profit_pct=0.02,
+            stop_loss_pct=0.01,
+            max_holding_minutes=3,
+        ),
+        walk_forward=WalkForwardConfig(
+            train_size=4,
+            test_size=2,
+            step_size=2,
+            purge_size=1,
+            embargo_size=1,
+            min_train_size=3,
+        ),
+    )
+    optimistic = BacktestCostModel(
+        commission_bps=0.0,
+        slippage_bps_by_session={"KRX_REG": 0.0, "US_PRE": 0.0},
+        failure_rate_by_session={"KRX_REG": 0.0, "US_PRE": 0.0},
+        partial_fill_rate_by_session={"KRX_REG": 0.0, "US_PRE": 0.0},
+        unfavorable_fill_required=True,
+    )
+    conservative = BacktestCostModel(
+        commission_bps=10.0,
+        slippage_bps_by_session={"KRX_REG": 30.0, "US_PRE": 80.0},
+        failure_rate_by_session={"KRX_REG": 0.2, "US_PRE": 0.4},
+        partial_fill_rate_by_session={"KRX_REG": 0.5, "US_PRE": 0.7},
+        unfavorable_fill_required=True,
+    )
+    optimistic_out = run_v2_backtest_pipeline(cost_model=optimistic, **cfg)
+    conservative_out = run_v2_backtest_pipeline(cost_model=conservative, **cfg)
+
+    assert optimistic_out.folds and conservative_out.folds
+    optimistic_score = optimistic_out.folds[0].baseline_scores[1].cost_adjusted_accuracy
+    conservative_score = conservative_out.folds[0].baseline_scores[1].cost_adjusted_accuracy
+    assert conservative_score < optimistic_score
+
+    optimistic_avg_return = optimistic_out.folds[0].execution_adjusted_avg_return_bps
+    conservative_avg_return = conservative_out.folds[0].execution_adjusted_avg_return_bps
+    assert conservative_avg_return < optimistic_avg_return

tests/test_backup.py

@@ -3,9 +3,10 @@
 from __future__ import annotations
 
 import sqlite3
-import tempfile
-from datetime import UTC, datetime, timedelta
+import sys
+from datetime import UTC, datetime
 from pathlib import Path
+from unittest.mock import MagicMock, patch
 
 import pytest
 
@@ -46,7 +47,9 @@ def temp_db(tmp_path: Path) -> Path:
 
     cursor.executemany(
         """
-        INSERT INTO trades (timestamp, stock_code, action, quantity, price, confidence, rationale, pnl)
+        INSERT INTO trades (
+            timestamp, stock_code, action, quantity, price, confidence, rationale, pnl
+        )
         VALUES (?, ?, ?, ?, ?, ?, ?, ?)
         """,
         test_trades,
@@ -71,9 +74,7 @@ class TestBackupExporter:
         exporter = BackupExporter(str(temp_db))
         output_dir = tmp_path / "exports"
 
-        results = exporter.export_all(
-            output_dir, formats=[ExportFormat.JSON], compress=False
-        )
+        results = exporter.export_all(output_dir, formats=[ExportFormat.JSON], compress=False)
 
         assert ExportFormat.JSON in results
         assert results[ExportFormat.JSON].exists()
@@ -84,9 +85,7 @@ class TestBackupExporter:
         exporter = BackupExporter(str(temp_db))
         output_dir = tmp_path / "exports"
 
-        results = exporter.export_all(
-            output_dir, formats=[ExportFormat.JSON], compress=True
-        )
+        results = exporter.export_all(output_dir, formats=[ExportFormat.JSON], compress=True)
 
         assert ExportFormat.JSON in results
         assert results[ExportFormat.JSON].suffix == ".gz"
@@ -96,15 +95,13 @@ class TestBackupExporter:
         exporter = BackupExporter(str(temp_db))
         output_dir = tmp_path / "exports"
 
-        results = exporter.export_all(
-            output_dir, formats=[ExportFormat.CSV], compress=False
-        )
+        results = exporter.export_all(output_dir, formats=[ExportFormat.CSV], compress=False)
 
         assert ExportFormat.CSV in results
         assert results[ExportFormat.CSV].exists()
 
         # Verify CSV content
-        with open(results[ExportFormat.CSV], "r") as f:
+        with open(results[ExportFormat.CSV]) as f:
             lines = f.readlines()
             assert len(lines) == 4  # Header + 3 rows
 
@@ -144,7 +141,7 @@ class TestBackupExporter:
         # Should only have 1 trade (AAPL on Jan 2)
         import json
 
-        with open(results[ExportFormat.JSON], "r") as f:
+        with open(results[ExportFormat.JSON]) as f:
             data = json.load(f)
             assert data["record_count"] == 1
             assert data["trades"][0]["stock_code"] == "AAPL"
@@ -363,3 +360,396 @@ class TestHealthMonitor:
         assert "timestamp" in report
         assert "checks" in report
         assert len(report["checks"]) == 3
+
+
+# ---------------------------------------------------------------------------
+# BackupExporter — additional coverage for previously uncovered branches
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def empty_db(tmp_path: Path) -> Path:
+    """Create a temporary database with NO trade records."""
+    db_path = tmp_path / "empty_trades.db"
+    conn = sqlite3.connect(str(db_path))
+    conn.execute(
+        """CREATE TABLE trades (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            timestamp TEXT NOT NULL,
+            stock_code TEXT NOT NULL,
+            action TEXT NOT NULL,
+            quantity INTEGER NOT NULL,
+            price REAL NOT NULL,
+            confidence INTEGER NOT NULL,
+            rationale TEXT,
+            pnl REAL DEFAULT 0.0
+        )"""
+    )
+    conn.commit()
+    conn.close()
+    return db_path
+
+
+class TestBackupExporterAdditional:
+    """Cover branches missed in the original TestBackupExporter suite."""
+
+    def test_export_all_default_formats(self, temp_db: Path, tmp_path: Path) -> None:
+        """export_all with formats=None must default to JSON+CSV+Parquet path."""
+        exporter = BackupExporter(str(temp_db))
+        # formats=None triggers the default list assignment (line 62)
+        results = exporter.export_all(tmp_path / "out", formats=None, compress=False)
+        # JSON and CSV must always succeed; Parquet needs pyarrow
+        assert ExportFormat.JSON in results
+        assert ExportFormat.CSV in results
+
+    def test_export_all_logs_error_on_failure(self, temp_db: Path, tmp_path: Path) -> None:
+        """export_all must log an error and continue when one format fails."""
+        exporter = BackupExporter(str(temp_db))
+        # Patch _export_format to raise on JSON, succeed on CSV
+        original = exporter._export_format
+
+        def failing_export(fmt, *args, **kwargs):  # type: ignore[no-untyped-def]
+            if fmt == ExportFormat.JSON:
+                raise RuntimeError("simulated failure")
+            return original(fmt, *args, **kwargs)
+
+        exporter._export_format = failing_export  # type: ignore[method-assign]
+        results = exporter.export_all(
+            tmp_path / "out",
+            formats=[ExportFormat.JSON, ExportFormat.CSV],
+            compress=False,
+        )
+        # JSON failed → not in results; CSV succeeded → in results
+        assert ExportFormat.JSON not in results
+        assert ExportFormat.CSV in results
+
+    def test_export_csv_empty_trades_no_compress(self, empty_db: Path, tmp_path: Path) -> None:
+        """CSV export with no trades and compress=False must write header row only."""
+        exporter = BackupExporter(str(empty_db))
+        results = exporter.export_all(
+            tmp_path / "out",
+            formats=[ExportFormat.CSV],
+            compress=False,
+        )
+        assert ExportFormat.CSV in results
+        out = results[ExportFormat.CSV]
+        assert out.exists()
+        content = out.read_text()
+        assert "timestamp" in content
+
+    def test_export_csv_empty_trades_compressed(self, empty_db: Path, tmp_path: Path) -> None:
+        """CSV export with no trades and compress=True must write gzipped header."""
+        import gzip
+
+        exporter = BackupExporter(str(empty_db))
+        results = exporter.export_all(
+            tmp_path / "out",
+            formats=[ExportFormat.CSV],
+            compress=True,
+        )
+        assert ExportFormat.CSV in results
+        out = results[ExportFormat.CSV]
+        assert out.suffix == ".gz"
+        with gzip.open(out, "rt", encoding="utf-8") as f:
+            content = f.read()
+        assert "timestamp" in content
+
+    def test_export_csv_with_data_compressed(self, temp_db: Path, tmp_path: Path) -> None:
+        """CSV export with data and compress=True must write gzipped rows."""
+        import gzip
+
+        exporter = BackupExporter(str(temp_db))
+        results = exporter.export_all(
+            tmp_path / "out",
+            formats=[ExportFormat.CSV],
+            compress=True,
+        )
+        assert ExportFormat.CSV in results
+        out = results[ExportFormat.CSV]
+        with gzip.open(out, "rt", encoding="utf-8") as f:
+            lines = f.readlines()
+        # Header + 3 data rows
+        assert len(lines) == 4
+
+    def test_export_parquet_raises_import_error_without_pyarrow(
+        self, temp_db: Path, tmp_path: Path
+    ) -> None:
+        """Parquet export must raise ImportError when pyarrow is not installed."""
+        exporter = BackupExporter(str(temp_db))
+        with patch.dict(sys.modules, {"pyarrow": None, "pyarrow.parquet": None}):
+            try:
+                import pyarrow  # noqa: F401
+
+                pytest.skip("pyarrow is installed; cannot test ImportError path")
+            except ImportError:
+                pass
+            results = exporter.export_all(
+                tmp_path / "out",
+                formats=[ExportFormat.PARQUET],
+                compress=False,
+            )
+            # Parquet export fails gracefully; result dict should not contain it
+            assert ExportFormat.PARQUET not in results
+
+
+# ---------------------------------------------------------------------------
+# CloudStorage — mocked boto3 tests
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def mock_boto3_module():
+    """Inject a fake boto3 into sys.modules for the duration of the test."""
+    mock = MagicMock()
+    with patch.dict(sys.modules, {"boto3": mock}):
+        yield mock
+
+
+@pytest.fixture
+def s3_config():
+    """Minimal S3Config for tests."""
+    from src.backup.cloud_storage import S3Config
+
+    return S3Config(
+        endpoint_url="http://localhost:9000",
+        access_key="minioadmin",
+        secret_key="minioadmin",
+        bucket_name="test-bucket",
+        region="us-east-1",
+    )
+
+
+class TestCloudStorage:
+    """Test CloudStorage using mocked boto3."""
+
+    def test_init_creates_s3_client(self, mock_boto3_module, s3_config) -> None:
+        """CloudStorage.__init__ must call boto3.client with the correct args."""
+        from src.backup.cloud_storage import CloudStorage
+
+        storage = CloudStorage(s3_config)
+        mock_boto3_module.client.assert_called_once()
+        call_kwargs = mock_boto3_module.client.call_args[1]
+        assert call_kwargs["aws_access_key_id"] == "minioadmin"
+        assert call_kwargs["aws_secret_access_key"] == "minioadmin"
+        assert storage.config == s3_config
+
+    def test_init_raises_if_boto3_missing(self, s3_config) -> None:
+        """CloudStorage.__init__ must raise ImportError when boto3 is absent."""
+        with patch.dict(sys.modules, {"boto3": None}):  # type: ignore[dict-item]
+            with pytest.raises((ImportError, TypeError)):
+                # Re-import to trigger the try/except inside __init__
+                import importlib
+
+                import src.backup.cloud_storage as m
+
+                importlib.reload(m)
+                m.CloudStorage(s3_config)
+
+    def test_upload_file_success(self, mock_boto3_module, s3_config, tmp_path: Path) -> None:
+        """upload_file must call client.upload_file and return the object key."""
+        from src.backup.cloud_storage import CloudStorage
+
+        test_file = tmp_path / "backup.json.gz"
+        test_file.write_bytes(b"data")
+
+        storage = CloudStorage(s3_config)
+        key = storage.upload_file(test_file, object_key="backups/backup.json.gz")
+
+        assert key == "backups/backup.json.gz"
+        storage.client.upload_file.assert_called_once()
+
+    def test_upload_file_default_key(self, mock_boto3_module, s3_config, tmp_path: Path) -> None:
+        """upload_file without object_key must use the filename as key."""
+        from src.backup.cloud_storage import CloudStorage
+
+        test_file = tmp_path / "myfile.gz"
+        test_file.write_bytes(b"data")
+
+        storage = CloudStorage(s3_config)
+        key = storage.upload_file(test_file)
+
+        assert key == "myfile.gz"
+
+    def test_upload_file_not_found(self, mock_boto3_module, s3_config, tmp_path: Path) -> None:
+        """upload_file must raise FileNotFoundError for missing files."""
+        from src.backup.cloud_storage import CloudStorage
+
+        storage = CloudStorage(s3_config)
+        with pytest.raises(FileNotFoundError):
+            storage.upload_file(tmp_path / "nonexistent.gz")
+
+    def test_upload_file_propagates_client_error(
+        self, mock_boto3_module, s3_config, tmp_path: Path
+    ) -> None:
+        """upload_file must re-raise exceptions from the boto3 client."""
+        from src.backup.cloud_storage import CloudStorage
+
+        test_file = tmp_path / "backup.gz"
+        test_file.write_bytes(b"data")
+
+        storage = CloudStorage(s3_config)
+        storage.client.upload_file.side_effect = RuntimeError("network error")
+
+        with pytest.raises(RuntimeError, match="network error"):
+            storage.upload_file(test_file)
+
+    def test_download_file_success(self, mock_boto3_module, s3_config, tmp_path: Path) -> None:
+        """download_file must call client.download_file and return local path."""
+        from src.backup.cloud_storage import CloudStorage
+
+        storage = CloudStorage(s3_config)
+        dest = tmp_path / "downloads" / "backup.gz"
+
+        result = storage.download_file("backups/backup.gz", dest)
+
+        assert result == dest
+        storage.client.download_file.assert_called_once()
+
+    def test_download_file_propagates_error(
+        self, mock_boto3_module, s3_config, tmp_path: Path
+    ) -> None:
+        """download_file must re-raise exceptions from the boto3 client."""
+        from src.backup.cloud_storage import CloudStorage
+
+        storage = CloudStorage(s3_config)
+        storage.client.download_file.side_effect = RuntimeError("timeout")
+
+        with pytest.raises(RuntimeError, match="timeout"):
+            storage.download_file("key", tmp_path / "dest.gz")
+
+    def test_list_files_returns_objects(self, mock_boto3_module, s3_config) -> None:
+        """list_files must return parsed file metadata from S3 response."""
+
+        from src.backup.cloud_storage import CloudStorage
+
+        storage = CloudStorage(s3_config)
+        storage.client.list_objects_v2.return_value = {
+            "Contents": [
+                {
+                    "Key": "backups/a.gz",
+                    "Size": 1024,
+                    "LastModified": datetime(2026, 1, 1, tzinfo=UTC),
+                    "ETag": '"abc123"',
+                }
+            ]
+        }
+
+        files = storage.list_files(prefix="backups/")
+        assert len(files) == 1
+        assert files[0]["key"] == "backups/a.gz"
+        assert files[0]["size_bytes"] == 1024
+
+    def test_list_files_empty_bucket(self, mock_boto3_module, s3_config) -> None:
+        """list_files must return empty list when bucket has no objects."""
+        from src.backup.cloud_storage import CloudStorage
+
+        storage = CloudStorage(s3_config)
+        storage.client.list_objects_v2.return_value = {}
+
+        files = storage.list_files()
+        assert files == []
+
+    def test_list_files_propagates_error(self, mock_boto3_module, s3_config) -> None:
+        """list_files must re-raise exceptions from the boto3 client."""
+        from src.backup.cloud_storage import CloudStorage
+
+        storage = CloudStorage(s3_config)
+        storage.client.list_objects_v2.side_effect = RuntimeError("auth error")
+
+        with pytest.raises(RuntimeError):
+            storage.list_files()
+
+    def test_delete_file_success(self, mock_boto3_module, s3_config) -> None:
+        """delete_file must call client.delete_object with the correct key."""
+        from src.backup.cloud_storage import CloudStorage
+
+        storage = CloudStorage(s3_config)
+        storage.delete_file("backups/old.gz")
+        storage.client.delete_object.assert_called_once_with(
+            Bucket="test-bucket", Key="backups/old.gz"
+        )
+
+    def test_delete_file_propagates_error(self, mock_boto3_module, s3_config) -> None:
+        """delete_file must re-raise exceptions from the boto3 client."""
+        from src.backup.cloud_storage import CloudStorage
+
+        storage = CloudStorage(s3_config)
+        storage.client.delete_object.side_effect = RuntimeError("permission denied")
+
+        with pytest.raises(RuntimeError):
+            storage.delete_file("backups/old.gz")
+
+    def test_get_storage_stats_success(self, mock_boto3_module, s3_config) -> None:
+        """get_storage_stats must aggregate file sizes correctly."""
+
+        from src.backup.cloud_storage import CloudStorage
+
+        storage = CloudStorage(s3_config)
+        storage.client.list_objects_v2.return_value = {
+            "Contents": [
+                {
+                    "Key": "a.gz",
+                    "Size": 1024 * 1024,
+                    "LastModified": datetime(2026, 1, 1, tzinfo=UTC),
+                    "ETag": '"x"',
+                },
+                {
+                    "Key": "b.gz",
+                    "Size": 1024 * 1024,
+                    "LastModified": datetime(2026, 1, 2, tzinfo=UTC),
+                    "ETag": '"y"',
+                },
+            ]
+        }
+
+        stats = storage.get_storage_stats()
+        assert stats["total_files"] == 2
+        assert stats["total_size_bytes"] == 2 * 1024 * 1024
+        assert stats["total_size_mb"] == pytest.approx(2.0)
+
+    def test_get_storage_stats_on_error(self, mock_boto3_module, s3_config) -> None:
+        """get_storage_stats must return error dict without raising on failure."""
+        from src.backup.cloud_storage import CloudStorage
+
+        storage = CloudStorage(s3_config)
+        storage.client.list_objects_v2.side_effect = RuntimeError("no connection")
+
+        stats = storage.get_storage_stats()
+        assert "error" in stats
+        assert stats["total_files"] == 0
+
+    def test_verify_connection_success(self, mock_boto3_module, s3_config) -> None:
+        """verify_connection must return True when head_bucket succeeds."""
+        from src.backup.cloud_storage import CloudStorage
+
+        storage = CloudStorage(s3_config)
+        result = storage.verify_connection()
+        assert result is True
+
+    def test_verify_connection_failure(self, mock_boto3_module, s3_config) -> None:
+        """verify_connection must return False when head_bucket raises."""
+        from src.backup.cloud_storage import CloudStorage
+
+        storage = CloudStorage(s3_config)
+        storage.client.head_bucket.side_effect = RuntimeError("no such bucket")
+
+        result = storage.verify_connection()
+        assert result is False
+
+    def test_enable_versioning(self, mock_boto3_module, s3_config) -> None:
+        """enable_versioning must call put_bucket_versioning."""
+        from src.backup.cloud_storage import CloudStorage
+
+        storage = CloudStorage(s3_config)
+        storage.enable_versioning()
+        storage.client.put_bucket_versioning.assert_called_once()
+
+    def test_enable_versioning_propagates_error(self, mock_boto3_module, s3_config) -> None:
+        """enable_versioning must re-raise exceptions from the boto3 client."""
+        from src.backup.cloud_storage import CloudStorage
+
+        storage = CloudStorage(s3_config)
+        storage.client.put_bucket_versioning.side_effect = RuntimeError("denied")
+
+        with pytest.raises(RuntimeError):
+            storage.enable_versioning()

tests/test_blackout_manager.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from src.core.blackout_manager import (
+    BlackoutOrderManager,
+    QueuedOrderIntent,
+    parse_blackout_windows_kst,
+)
+
+
+def test_parse_blackout_windows_kst() -> None:
+    windows = parse_blackout_windows_kst("23:30-00:10,11:20-11:30,invalid")
+    assert len(windows) == 2
+
+
+def test_blackout_manager_handles_cross_midnight_window() -> None:
+    manager = BlackoutOrderManager(
+        enabled=True,
+        windows=parse_blackout_windows_kst("23:30-00:10"),
+        max_queue_size=10,
+    )
+    # 2026-01-01 23:40 KST = 2026-01-01 14:40 UTC
+    assert manager.in_blackout(datetime(2026, 1, 1, 14, 40, tzinfo=UTC))
+    # 2026-01-02 00:20 KST = 2026-01-01 15:20 UTC
+    assert not manager.in_blackout(datetime(2026, 1, 1, 15, 20, tzinfo=UTC))
+
+
+def test_recovery_batch_only_after_blackout_exit() -> None:
+    manager = BlackoutOrderManager(
+        enabled=True,
+        windows=parse_blackout_windows_kst("23:30-00:10"),
+        max_queue_size=10,
+    )
+    intent = QueuedOrderIntent(
+        market_code="KR",
+        exchange_code="KRX",
+        session_id="KRX_REG",
+        stock_code="005930",
+        order_type="BUY",
+        quantity=1,
+        price=100.0,
+        source="test",
+        queued_at=datetime.now(UTC),
+    )
+    assert manager.enqueue(intent)
+
+    # Inside blackout: no pop yet
+    inside_blackout = datetime(2026, 1, 1, 14, 40, tzinfo=UTC)
+    assert manager.pop_recovery_batch(inside_blackout) == []
+
+    # Outside blackout: pop full batch once
+    outside_blackout = datetime(2026, 1, 1, 15, 20, tzinfo=UTC)
+    batch = manager.pop_recovery_batch(outside_blackout)
+    assert len(batch) == 1
+    assert manager.pending_count == 0
+
+
+def test_requeued_intent_is_processed_next_non_blackout_cycle() -> None:
+    manager = BlackoutOrderManager(
+        enabled=True,
+        windows=parse_blackout_windows_kst("23:30-00:10"),
+        max_queue_size=10,
+    )
+    intent = QueuedOrderIntent(
+        market_code="KR",
+        exchange_code="KRX",
+        session_id="KRX_REG",
+        stock_code="005930",
+        order_type="BUY",
+        quantity=1,
+        price=100.0,
+        source="test",
+        queued_at=datetime.now(UTC),
+    )
+    manager.enqueue(intent)
+    outside_blackout = datetime(2026, 1, 1, 15, 20, tzinfo=UTC)
+    first_batch = manager.pop_recovery_batch(outside_blackout)
+    assert len(first_batch) == 1
+
+    manager.requeue(first_batch[0])
+    second_batch = manager.pop_recovery_batch(outside_blackout)
+    assert len(second_batch) == 1
+
+
+def test_queue_overflow_drops_oldest_and_keeps_latest() -> None:
+    manager = BlackoutOrderManager(
+        enabled=True,
+        windows=parse_blackout_windows_kst("23:30-00:10"),
+        max_queue_size=2,
+    )
+    first = QueuedOrderIntent(
+        market_code="KR",
+        exchange_code="KRX",
+        session_id="KRX_REG",
+        stock_code="000001",
+        order_type="BUY",
+        quantity=1,
+        price=100.0,
+        source="first",
+        queued_at=datetime.now(UTC),
+    )
+    second = QueuedOrderIntent(
+        market_code="KR",
+        exchange_code="KRX",
+        session_id="KRX_REG",
+        stock_code="000002",
+        order_type="BUY",
+        quantity=1,
+        price=101.0,
+        source="second",
+        queued_at=datetime.now(UTC),
+    )
+    third = QueuedOrderIntent(
+        market_code="KR",
+        exchange_code="KRX",
+        session_id="KRX_REG",
+        stock_code="000003",
+        order_type="SELL",
+        quantity=2,
+        price=102.0,
+        source="third",
+        queued_at=datetime.now(UTC),
+    )
+
+    assert manager.enqueue(first)
+    assert manager.enqueue(second)
+    assert manager.enqueue(third)
+    assert manager.pending_count == 2
+    assert manager.overflow_drop_count == 1
+
+    outside_blackout = datetime(2026, 1, 1, 15, 20, tzinfo=UTC)
+    batch = manager.pop_recovery_batch(outside_blackout)
+    assert [intent.stock_code for intent in batch] == ["000002", "000003"]

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,25 +318,59 @@ 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()
             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
+                "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):
-        """prompt_override should bypass prompt optimization."""
+    async def test_prompt_override_skips_parse_response(self, settings):
+        """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,
@@ -339,8 +386,10 @@ class TestPromptOverride:
             await client.decide(market_data)
 
             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
+                "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
@@ -364,7 +413,8 @@ class TestPromptOverride:
             await client.decide(market_data)
 
             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
+                "contents",
+                mock_generate.call_args[0][1] if len(mock_generate.call_args[0]) > 1 else None,
             )
             # Should contain stock code from build_prompt, not be a custom override
             assert "005930" in actual_prompt

tests/test_broker.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import asyncio
-from unittest.mock import AsyncMock, MagicMock, patch
+from unittest.mock import AsyncMock, patch
 
 import pytest
 
@@ -99,7 +99,10 @@ class TestTokenManagement:
         mock_resp_403 = AsyncMock()
         mock_resp_403.status = 403
         mock_resp_403.text = AsyncMock(
-            return_value='{"error_code":"EGW00133","error_description":"접근토큰 발급 잠시 후 다시 시도하세요(1분당 1회)"}'
+            return_value=(
+                '{"error_code":"EGW00133","error_description":'
+                '"접근토큰 발급 잠시 후 다시 시도하세요(1분당 1회)"}'
+            )
         )
         mock_resp_403.__aenter__ = AsyncMock(return_value=mock_resp_403)
         mock_resp_403.__aexit__ = AsyncMock(return_value=False)
@@ -232,9 +235,7 @@ class TestRateLimiter:
         mock_order_resp.__aenter__ = AsyncMock(return_value=mock_order_resp)
         mock_order_resp.__aexit__ = AsyncMock(return_value=False)
 
-        with patch(
-            "aiohttp.ClientSession.post", side_effect=[mock_hash_resp, mock_order_resp]
-        ):
+        with patch("aiohttp.ClientSession.post", side_effect=[mock_hash_resp, mock_order_resp]):
             with patch.object(
                 broker._rate_limiter, "acquire", new_callable=AsyncMock
             ) as mock_acquire:
@@ -354,6 +355,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,13 +379,34 @@ 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)
 # ---------------------------------------------------------------------------
 
 
-from src.broker.kis_api import kr_tick_unit, kr_round_down  # noqa: E402
+from src.broker.kis_api import kr_round_down, kr_tick_unit  # noqa: E402
 
 
 class TestKrTickUnit:
@@ -412,13 +436,13 @@ class TestKrTickUnit:
     @pytest.mark.parametrize(
         "price, expected_rounded",
         [
-            (188150, 188100),   # 100원 단위, 50원 잔여 → 내림
-            (188100, 188100),   # 이미 정렬됨
-            (75050, 75000),     # 100원 단위, 50원 잔여 → 내림
-            (49950, 49950),     # 50원 단위 정렬됨
-            (49960, 49950),     # 50원 단위, 10원 잔여 → 내림
-            (1999, 1999),       # 1원 단위 → 그대로
-            (5003, 5000),       # 10원 단위, 3원 잔여 → 내림
+            (188150, 188100),  # 100원 단위, 50원 잔여 → 내림
+            (188100, 188100),  # 이미 정렬됨
+            (75050, 75000),  # 100원 단위, 50원 잔여 → 내림
+            (49950, 49950),  # 50원 단위 정렬됨
+            (49960, 49950),  # 50원 단위, 10원 잔여 → 내림
+            (1999, 1999),  # 1원 단위 → 그대로
+            (5003, 5000),  # 10원 단위, 3원 잔여 → 내림
         ],
     )
     def test_round_down_to_tick(self, price: int, expected_rounded: int) -> None:
@@ -515,15 +539,13 @@ class TestSendOrderTickRounding:
         mock_order.__aenter__ = AsyncMock(return_value=mock_order)
         mock_order.__aexit__ = AsyncMock(return_value=False)
 
-        with patch(
-            "aiohttp.ClientSession.post", side_effect=[mock_hash, mock_order]
-        ) as mock_post:
+        with patch("aiohttp.ClientSession.post", side_effect=[mock_hash, mock_order]) as mock_post:
             await broker.send_order("005930", "BUY", 1, price=188150)
 
         order_call = mock_post.call_args_list[1]
         body = order_call[1].get("json", {})
         assert body["ORD_UNPR"] == "188100"  # rounded down
-        assert body["ORD_DVSN"] == "00"       # 지정가
+        assert body["ORD_DVSN"] == "00"  # 지정가
 
     @pytest.mark.asyncio
     async def test_limit_order_ord_dvsn_is_00(self, broker: KISBroker) -> None:
@@ -540,9 +562,7 @@ class TestSendOrderTickRounding:
         mock_order.__aenter__ = AsyncMock(return_value=mock_order)
         mock_order.__aexit__ = AsyncMock(return_value=False)
 
-        with patch(
-            "aiohttp.ClientSession.post", side_effect=[mock_hash, mock_order]
-        ) as mock_post:
+        with patch("aiohttp.ClientSession.post", side_effect=[mock_hash, mock_order]) as mock_post:
             await broker.send_order("005930", "BUY", 1, price=50000)
 
         order_call = mock_post.call_args_list[1]
@@ -564,12 +584,330 @@ class TestSendOrderTickRounding:
         mock_order.__aenter__ = AsyncMock(return_value=mock_order)
         mock_order.__aexit__ = AsyncMock(return_value=False)
 
-        with patch(
-            "aiohttp.ClientSession.post", side_effect=[mock_hash, mock_order]
-        ) as mock_post:
+        with patch("aiohttp.ClientSession.post", side_effect=[mock_hash, mock_order]) as mock_post:
             await broker.send_order("005930", "SELL", 1, price=0)
 
         order_call = mock_post.call_args_list[1]
         body = order_call[1].get("json", {})
         assert body["ORD_DVSN"] == "01"
+
+
+# ---------------------------------------------------------------------------
+# TR_ID live/paper branching (issues #201, #202, #203)
+# ---------------------------------------------------------------------------
+
+
+class TestTRIDBranchingDomestic:
+    """get_balance and send_order must use correct TR_ID for live vs paper mode."""
+
+    def _make_broker(self, settings, mode: str) -> KISBroker:
+        from src.config import Settings
+
+        s = Settings(
+            KIS_APP_KEY=settings.KIS_APP_KEY,
+            KIS_APP_SECRET=settings.KIS_APP_SECRET,
+            KIS_ACCOUNT_NO=settings.KIS_ACCOUNT_NO,
+            GEMINI_API_KEY=settings.GEMINI_API_KEY,
+            DB_PATH=":memory:",
+            ENABLED_MARKETS="KR",
+            MODE=mode,
+        )
+        b = KISBroker(s)
+        b._access_token = "tok"
+        b._token_expires_at = float("inf")
+        b._rate_limiter.acquire = AsyncMock()
+        return b
+
+    @pytest.mark.asyncio
+    async def test_get_balance_paper_uses_vttc8434r(self, settings) -> None:
+        broker = self._make_broker(settings, "paper")
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"output1": [], "output2": {}})
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.get", return_value=mock_resp) as mock_get:
+            await broker.get_balance()
+
+        headers = mock_get.call_args[1].get("headers", {})
+        assert headers["tr_id"] == "VTTC8434R"
+
+    @pytest.mark.asyncio
+    async def test_get_balance_live_uses_tttc8434r(self, settings) -> None:
+        broker = self._make_broker(settings, "live")
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"output1": [], "output2": {}})
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.get", return_value=mock_resp) as mock_get:
+            await broker.get_balance()
+
+        headers = mock_get.call_args[1].get("headers", {})
+        assert headers["tr_id"] == "TTTC8434R"
+
+    @pytest.mark.asyncio
+    async def test_send_order_buy_paper_uses_vttc0012u(self, settings) -> None:
+        broker = self._make_broker(settings, "paper")
+        mock_hash = AsyncMock()
+        mock_hash.status = 200
+        mock_hash.json = AsyncMock(return_value={"HASH": "h"})
+        mock_hash.__aenter__ = AsyncMock(return_value=mock_hash)
+        mock_hash.__aexit__ = AsyncMock(return_value=False)
+
+        mock_order = AsyncMock()
+        mock_order.status = 200
+        mock_order.json = AsyncMock(return_value={"rt_cd": "0"})
+        mock_order.__aenter__ = AsyncMock(return_value=mock_order)
+        mock_order.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", side_effect=[mock_hash, mock_order]) as mock_post:
+            await broker.send_order("005930", "BUY", 1)
+
+        order_headers = mock_post.call_args_list[1][1].get("headers", {})
+        assert order_headers["tr_id"] == "VTTC0012U"
+
+    @pytest.mark.asyncio
+    async def test_send_order_buy_live_uses_tttc0012u(self, settings) -> None:
+        broker = self._make_broker(settings, "live")
+        mock_hash = AsyncMock()
+        mock_hash.status = 200
+        mock_hash.json = AsyncMock(return_value={"HASH": "h"})
+        mock_hash.__aenter__ = AsyncMock(return_value=mock_hash)
+        mock_hash.__aexit__ = AsyncMock(return_value=False)
+
+        mock_order = AsyncMock()
+        mock_order.status = 200
+        mock_order.json = AsyncMock(return_value={"rt_cd": "0"})
+        mock_order.__aenter__ = AsyncMock(return_value=mock_order)
+        mock_order.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", side_effect=[mock_hash, mock_order]) as mock_post:
+            await broker.send_order("005930", "BUY", 1)
+
+        order_headers = mock_post.call_args_list[1][1].get("headers", {})
+        assert order_headers["tr_id"] == "TTTC0012U"
+
+    @pytest.mark.asyncio
+    async def test_send_order_sell_paper_uses_vttc0011u(self, settings) -> None:
+        broker = self._make_broker(settings, "paper")
+        mock_hash = AsyncMock()
+        mock_hash.status = 200
+        mock_hash.json = AsyncMock(return_value={"HASH": "h"})
+        mock_hash.__aenter__ = AsyncMock(return_value=mock_hash)
+        mock_hash.__aexit__ = AsyncMock(return_value=False)
+
+        mock_order = AsyncMock()
+        mock_order.status = 200
+        mock_order.json = AsyncMock(return_value={"rt_cd": "0"})
+        mock_order.__aenter__ = AsyncMock(return_value=mock_order)
+        mock_order.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", side_effect=[mock_hash, mock_order]) as mock_post:
+            await broker.send_order("005930", "SELL", 1)
+
+        order_headers = mock_post.call_args_list[1][1].get("headers", {})
+        assert order_headers["tr_id"] == "VTTC0011U"
+
+    @pytest.mark.asyncio
+    async def test_send_order_sell_live_uses_tttc0011u(self, settings) -> None:
+        broker = self._make_broker(settings, "live")
+        mock_hash = AsyncMock()
+        mock_hash.status = 200
+        mock_hash.json = AsyncMock(return_value={"HASH": "h"})
+        mock_hash.__aenter__ = AsyncMock(return_value=mock_hash)
+        mock_hash.__aexit__ = AsyncMock(return_value=False)
+
+        mock_order = AsyncMock()
+        mock_order.status = 200
+        mock_order.json = AsyncMock(return_value={"rt_cd": "0"})
+        mock_order.__aenter__ = AsyncMock(return_value=mock_order)
+        mock_order.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.post", side_effect=[mock_hash, mock_order]) as mock_post:
+            await broker.send_order("005930", "SELL", 1)
+
+        order_headers = mock_post.call_args_list[1][1].get("headers", {})
+        assert order_headers["tr_id"] == "TTTC0011U"
+
+
+# ---------------------------------------------------------------------------
+# Domestic Pending Orders (get_domestic_pending_orders)
+# ---------------------------------------------------------------------------
+
+
+class TestGetDomesticPendingOrders:
+    """get_domestic_pending_orders must return [] in paper mode and call TTTC0084R in live."""
+
+    def _make_broker(self, settings, mode: str) -> KISBroker:
+        from src.config import Settings
+
+        s = Settings(
+            KIS_APP_KEY=settings.KIS_APP_KEY,
+            KIS_APP_SECRET=settings.KIS_APP_SECRET,
+            KIS_ACCOUNT_NO=settings.KIS_ACCOUNT_NO,
+            GEMINI_API_KEY=settings.GEMINI_API_KEY,
+            DB_PATH=":memory:",
+            ENABLED_MARKETS="KR",
+            MODE=mode,
+        )
+        b = KISBroker(s)
+        b._access_token = "tok"
+        b._token_expires_at = float("inf")
+        b._rate_limiter.acquire = AsyncMock()
+        return b
+
+    @pytest.mark.asyncio
+    async def test_paper_mode_returns_empty(self, settings) -> None:
+        """Paper mode must return [] immediately without any API call."""
+        broker = self._make_broker(settings, "paper")
+
+        with patch("aiohttp.ClientSession.get") as mock_get:
+            result = await broker.get_domestic_pending_orders()
+
+        assert result == []
+        mock_get.assert_not_called()
+
+    @pytest.mark.asyncio
+    async def test_live_mode_calls_tttc0084r_with_correct_params(self, settings) -> None:
+        """Live mode must call TTTC0084R with INQR_DVSN_1/2 and paging params."""
+        broker = self._make_broker(settings, "live")
+        pending = [{"odno": "001", "pdno": "005930", "psbl_qty": "10"}]
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"output": pending})
+        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
+        mock_resp.__aexit__ = AsyncMock(return_value=False)
+
+        with patch("aiohttp.ClientSession.get", return_value=mock_resp) as mock_get:
+            result = await broker.get_domestic_pending_orders()
+
+        assert result == pending
+        headers = mock_get.call_args[1].get("headers", {})
+        assert headers["tr_id"] == "TTTC0084R"
+        params = mock_get.call_args[1].get("params", {})
+        assert params["INQR_DVSN_1"] == "0"
+        assert params["INQR_DVSN_2"] == "0"
+
+    @pytest.mark.asyncio
+    async def test_live_mode_connection_error(self, settings) -> None:
+        """Network error must raise ConnectionError."""
+        import aiohttp as _aiohttp
+
+        broker = self._make_broker(settings, "live")
+
+        with patch(
+            "aiohttp.ClientSession.get",
+            side_effect=_aiohttp.ClientError("timeout"),
+        ):
+            with pytest.raises(ConnectionError):
+                await broker.get_domestic_pending_orders()
+
+
+# ---------------------------------------------------------------------------
+# Domestic Order Cancellation (cancel_domestic_order)
+# ---------------------------------------------------------------------------
+
+
+class TestCancelDomesticOrder:
+    """cancel_domestic_order must use correct TR_ID and build body correctly."""
+
+    def _make_broker(self, settings, mode: str) -> KISBroker:
+        from src.config import Settings
+
+        s = Settings(
+            KIS_APP_KEY=settings.KIS_APP_KEY,
+            KIS_APP_SECRET=settings.KIS_APP_SECRET,
+            KIS_ACCOUNT_NO=settings.KIS_ACCOUNT_NO,
+            GEMINI_API_KEY=settings.GEMINI_API_KEY,
+            DB_PATH=":memory:",
+            ENABLED_MARKETS="KR",
+            MODE=mode,
+        )
+        b = KISBroker(s)
+        b._access_token = "tok"
+        b._token_expires_at = float("inf")
+        b._rate_limiter.acquire = AsyncMock()
+        return b
+
+    def _make_post_mocks(self, order_payload: dict) -> tuple:
+        mock_hash = AsyncMock()
+        mock_hash.status = 200
+        mock_hash.json = AsyncMock(return_value={"HASH": "h"})
+        mock_hash.__aenter__ = AsyncMock(return_value=mock_hash)
+        mock_hash.__aexit__ = AsyncMock(return_value=False)
+
+        mock_order = AsyncMock()
+        mock_order.status = 200
+        mock_order.json = AsyncMock(return_value=order_payload)
+        mock_order.__aenter__ = AsyncMock(return_value=mock_order)
+        mock_order.__aexit__ = AsyncMock(return_value=False)
+
+        return mock_hash, mock_order
+
+    @pytest.mark.asyncio
+    async def test_live_uses_tttc0013u(self, settings) -> None:
+        """Live mode must use TR_ID TTTC0013U."""
+        broker = self._make_broker(settings, "live")
+        mock_hash, mock_order = self._make_post_mocks({"rt_cd": "0"})
+
+        with patch("aiohttp.ClientSession.post", side_effect=[mock_hash, mock_order]) as mock_post:
+            await broker.cancel_domestic_order("005930", "ORD001", "BRNO01", 5)
+
+        order_headers = mock_post.call_args_list[1][1].get("headers", {})
+        assert order_headers["tr_id"] == "TTTC0013U"
+
+    @pytest.mark.asyncio
+    async def test_paper_uses_vttc0013u(self, settings) -> None:
+        """Paper mode must use TR_ID VTTC0013U."""
+        broker = self._make_broker(settings, "paper")
+        mock_hash, mock_order = self._make_post_mocks({"rt_cd": "0"})
+
+        with patch("aiohttp.ClientSession.post", side_effect=[mock_hash, mock_order]) as mock_post:
+            await broker.cancel_domestic_order("005930", "ORD001", "BRNO01", 5)
+
+        order_headers = mock_post.call_args_list[1][1].get("headers", {})
+        assert order_headers["tr_id"] == "VTTC0013U"
+
+    @pytest.mark.asyncio
+    async def test_cancel_sets_rvse_cncl_dvsn_cd_02(self, settings) -> None:
+        """Body must have RVSE_CNCL_DVSN_CD='02' (취소) and QTY_ALL_ORD_YN='Y'."""
+        broker = self._make_broker(settings, "live")
+        mock_hash, mock_order = self._make_post_mocks({"rt_cd": "0"})
+
+        with patch("aiohttp.ClientSession.post", side_effect=[mock_hash, mock_order]) as mock_post:
+            await broker.cancel_domestic_order("005930", "ORD001", "BRNO01", 5)
+
+        body = mock_post.call_args_list[1][1].get("json", {})
+        assert body["RVSE_CNCL_DVSN_CD"] == "02"
+        assert body["QTY_ALL_ORD_YN"] == "Y"
         assert body["ORD_UNPR"] == "0"
+
+    @pytest.mark.asyncio
+    async def test_cancel_sets_krx_fwdg_ord_orgno_in_body(self, settings) -> None:
+        """Body must include KRX_FWDG_ORD_ORGNO and ORGN_ODNO from arguments."""
+        broker = self._make_broker(settings, "live")
+        mock_hash, mock_order = self._make_post_mocks({"rt_cd": "0"})
+
+        with patch("aiohttp.ClientSession.post", side_effect=[mock_hash, mock_order]) as mock_post:
+            await broker.cancel_domestic_order("005930", "ORD123", "BRN456", 3)
+
+        body = mock_post.call_args_list[1][1].get("json", {})
+        assert body["KRX_FWDG_ORD_ORGNO"] == "BRN456"
+        assert body["ORGN_ODNO"] == "ORD123"
+        assert body["ORD_QTY"] == "3"
+
+    @pytest.mark.asyncio
+    async def test_cancel_sets_hashkey_header(self, settings) -> None:
+        """Request must include hashkey header (same pattern as send_order)."""
+        broker = self._make_broker(settings, "live")
+        mock_hash, mock_order = self._make_post_mocks({"rt_cd": "0"})
+
+        with patch("aiohttp.ClientSession.post", side_effect=[mock_hash, mock_order]) as mock_post:
+            await broker.cancel_domestic_order("005930", "ORD001", "BRNO01", 2)
+
+        order_headers = mock_post.call_args_list[1][1].get("headers", {})
+        assert "hashkey" in order_headers
+        assert order_headers["hashkey"] == "h"

tests/test_context.py

@@ -10,6 +10,7 @@ import pytest
 from src.context.aggregator import ContextAggregator
 from src.context.layer import LAYER_CONFIG, ContextLayer
 from src.context.store import ContextStore
+from src.context.summarizer import ContextSummarizer
 from src.db import init_db, log_trade
 
 
@@ -76,9 +77,7 @@ class TestContextStore:
         # Latest by updated_at, which should be the last one set
         assert latest == "2026-02-02"
 
-    def test_delete_old_contexts(
-        self, store: ContextStore, db_conn: sqlite3.Connection
-    ) -> None:
+    def test_delete_old_contexts(self, store: ContextStore, db_conn: sqlite3.Connection) -> None:
         """Test deleting contexts older than a cutoff date."""
         # Insert contexts with specific old timestamps
         # (bypassing set_context which uses current time)
@@ -169,9 +168,7 @@ class TestContextAggregator:
         log_trade(db_conn, "035720", "HOLD", 75, "Wait", quantity=0, price=0, pnl=0)
 
         # Manually set timestamps to the target date
-        db_conn.execute(
-            f"UPDATE trades SET timestamp = '{date}T10:00:00+00:00'"
-        )
+        db_conn.execute(f"UPDATE trades SET timestamp = '{date}T10:00:00+00:00'")
         db_conn.commit()
 
         # Aggregate
@@ -193,18 +190,10 @@ class TestContextAggregator:
         week = "2026-W06"
 
         # Set daily contexts
-        aggregator.store.set_context(
-            ContextLayer.L6_DAILY, "2026-02-02", "total_pnl_KR", 100.0
-        )
-        aggregator.store.set_context(
-            ContextLayer.L6_DAILY, "2026-02-03", "total_pnl_KR", 200.0
-        )
-        aggregator.store.set_context(
-            ContextLayer.L6_DAILY, "2026-02-02", "avg_confidence_KR", 80.0
-        )
-        aggregator.store.set_context(
-            ContextLayer.L6_DAILY, "2026-02-03", "avg_confidence_KR", 85.0
-        )
+        aggregator.store.set_context(ContextLayer.L6_DAILY, "2026-02-02", "total_pnl_KR", 100.0)
+        aggregator.store.set_context(ContextLayer.L6_DAILY, "2026-02-03", "total_pnl_KR", 200.0)
+        aggregator.store.set_context(ContextLayer.L6_DAILY, "2026-02-02", "avg_confidence_KR", 80.0)
+        aggregator.store.set_context(ContextLayer.L6_DAILY, "2026-02-03", "avg_confidence_KR", 85.0)
 
         # Aggregate
         aggregator.aggregate_weekly_from_daily(week)
@@ -222,15 +211,9 @@ class TestContextAggregator:
         month = "2026-02"
 
         # Set weekly contexts
-        aggregator.store.set_context(
-            ContextLayer.L5_WEEKLY, "2026-W05", "weekly_pnl_KR", 100.0
-        )
-        aggregator.store.set_context(
-            ContextLayer.L5_WEEKLY, "2026-W06", "weekly_pnl_KR", 200.0
-        )
-        aggregator.store.set_context(
-            ContextLayer.L5_WEEKLY, "2026-W07", "weekly_pnl_KR", 150.0
-        )
+        aggregator.store.set_context(ContextLayer.L5_WEEKLY, "2026-W05", "weekly_pnl_KR", 100.0)
+        aggregator.store.set_context(ContextLayer.L5_WEEKLY, "2026-W06", "weekly_pnl_KR", 200.0)
+        aggregator.store.set_context(ContextLayer.L5_WEEKLY, "2026-W07", "weekly_pnl_KR", 150.0)
 
         # Aggregate
         aggregator.aggregate_monthly_from_weekly(month)
@@ -315,6 +298,7 @@ class TestContextAggregator:
         store = aggregator.store
         assert store.get_context(ContextLayer.L6_DAILY, date, "total_pnl_KR") == 1000.0
         from datetime import date as date_cls
+
         trade_date = date_cls.fromisoformat(date)
         iso_year, iso_week, _ = trade_date.isocalendar()
         trade_week = f"{iso_year}-W{iso_week:02d}"
@@ -323,7 +307,9 @@ class TestContextAggregator:
         trade_quarter = f"{trade_date.year}-Q{(trade_date.month - 1) // 3 + 1}"
         trade_year = str(trade_date.year)
         assert store.get_context(ContextLayer.L4_MONTHLY, trade_month, "monthly_pnl") == 1000.0
-        assert store.get_context(ContextLayer.L3_QUARTERLY, trade_quarter, "quarterly_pnl") == 1000.0
+        assert (
+            store.get_context(ContextLayer.L3_QUARTERLY, trade_quarter, "quarterly_pnl") == 1000.0
+        )
         assert store.get_context(ContextLayer.L2_ANNUAL, trade_year, "annual_pnl") == 1000.0
 
 
@@ -370,3 +356,232 @@ class TestLayerMetadata:
 
         # L1 aggregates from L2
         assert LAYER_CONFIG[ContextLayer.L1_LEGACY].aggregation_source == ContextLayer.L2_ANNUAL
+
+
+# ---------------------------------------------------------------------------
+# ContextSummarizer tests
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture
+def summarizer(db_conn: sqlite3.Connection) -> ContextSummarizer:
+    """Provide a ContextSummarizer backed by an in-memory store."""
+    return ContextSummarizer(ContextStore(db_conn))
+
+
+class TestContextSummarizer:
+    """Test suite for ContextSummarizer."""
+
+    # ------------------------------------------------------------------
+    # summarize_numeric_values
+    # ------------------------------------------------------------------
+
+    def test_summarize_empty_values(self, summarizer: ContextSummarizer) -> None:
+        """Empty list must return SummaryStats with count=0 and no other fields."""
+        stats = summarizer.summarize_numeric_values([])
+        assert stats.count == 0
+        assert stats.mean is None
+        assert stats.min is None
+        assert stats.max is None
+
+    def test_summarize_single_value(self, summarizer: ContextSummarizer) -> None:
+        """Single-element list must return correct stats with std=0 and trend=flat."""
+        stats = summarizer.summarize_numeric_values([42.0])
+        assert stats.count == 1
+        assert stats.mean == 42.0
+        assert stats.std == 0.0
+        assert stats.trend == "flat"
+
+    def test_summarize_upward_trend(self, summarizer: ContextSummarizer) -> None:
+        """Increasing values must produce trend='up'."""
+        values = [1.0, 2.0, 3.0, 10.0, 20.0, 30.0]
+        stats = summarizer.summarize_numeric_values(values)
+        assert stats.trend == "up"
+
+    def test_summarize_downward_trend(self, summarizer: ContextSummarizer) -> None:
+        """Decreasing values must produce trend='down'."""
+        values = [30.0, 20.0, 10.0, 3.0, 2.0, 1.0]
+        stats = summarizer.summarize_numeric_values(values)
+        assert stats.trend == "down"
+
+    def test_summarize_flat_trend(self, summarizer: ContextSummarizer) -> None:
+        """Stable values must produce trend='flat'."""
+        values = [100.0, 100.1, 99.9, 100.0, 100.2, 99.8]
+        stats = summarizer.summarize_numeric_values(values)
+        assert stats.trend == "flat"
+
+    # ------------------------------------------------------------------
+    # summarize_layer
+    # ------------------------------------------------------------------
+
+    def test_summarize_layer_no_data(self, summarizer: ContextSummarizer) -> None:
+        """summarize_layer with no data must return the 'No data' sentinel."""
+        result = summarizer.summarize_layer(ContextLayer.L6_DAILY)
+        assert result["count"] == 0
+        assert "No data" in result["summary"]
+
+    def test_summarize_layer_numeric(
+        self, summarizer: ContextSummarizer, db_conn: sqlite3.Connection
+    ) -> None:
+        """summarize_layer must collect numeric values and produce stats."""
+        store = summarizer.store
+        store.set_context(ContextLayer.L6_DAILY, "2026-02-01", "total_pnl", 100.0)
+        store.set_context(ContextLayer.L6_DAILY, "2026-02-02", "total_pnl", 200.0)
+
+        result = summarizer.summarize_layer(ContextLayer.L6_DAILY)
+        assert "total_entries" in result
+
+    def test_summarize_layer_with_dict_values(self, summarizer: ContextSummarizer) -> None:
+        """summarize_layer must handle dict values by extracting numeric subkeys."""
+        store = summarizer.store
+        # set_context serialises the value as JSON, so passing a dict works
+        store.set_context(
+            ContextLayer.L6_DAILY, "2026-02-01", "metrics", {"win_rate": 65.0, "label": "good"}
+        )
+
+        result = summarizer.summarize_layer(ContextLayer.L6_DAILY)
+        assert "total_entries" in result
+        # numeric subkey "win_rate" should appear as "metrics.win_rate"
+        assert "metrics.win_rate" in result
+
+    def test_summarize_layer_with_string_values(self, summarizer: ContextSummarizer) -> None:
+        """summarize_layer must count string values separately."""
+        store = summarizer.store
+        # set_context stores string values as JSON-encoded strings
+        store.set_context(ContextLayer.L6_DAILY, "2026-02-01", "outlook", "BULLISH")
+
+        result = summarizer.summarize_layer(ContextLayer.L6_DAILY)
+        # String fields contribute a `<key>_count` entry
+        assert "outlook_count" in result
+
+    # ------------------------------------------------------------------
+    # rolling_window_summary
+    # ------------------------------------------------------------------
+
+    def test_rolling_window_summary_basic(self, summarizer: ContextSummarizer) -> None:
+        """rolling_window_summary must return the expected structure."""
+        store = summarizer.store
+        store.set_context(ContextLayer.L6_DAILY, "2026-02-01", "pnl", 500.0)
+
+        result = summarizer.rolling_window_summary(ContextLayer.L6_DAILY)
+        assert "window_days" in result
+        assert "recent_data" in result
+        assert "historical_summary" in result
+
+    def test_rolling_window_summary_no_older_data(self, summarizer: ContextSummarizer) -> None:
+        """rolling_window_summary with summarize_older=False skips history."""
+        result = summarizer.rolling_window_summary(ContextLayer.L6_DAILY, summarize_older=False)
+        assert result["historical_summary"] == {}
+
+    # ------------------------------------------------------------------
+    # aggregate_to_higher_layer
+    # ------------------------------------------------------------------
+
+    def test_aggregate_to_higher_layer_mean(self, summarizer: ContextSummarizer) -> None:
+        """aggregate_to_higher_layer with 'mean' via dict subkeys returns average."""
+        store = summarizer.store
+        # Use different outer keys but same inner metric key so get_all_contexts
+        # returns multiple rows with the target subkey.
+        store.set_context(ContextLayer.L6_DAILY, "2026-02-01", "day1", {"pnl": 100.0})
+        store.set_context(ContextLayer.L6_DAILY, "2026-02-01", "day2", {"pnl": 200.0})
+
+        result = summarizer.aggregate_to_higher_layer(
+            ContextLayer.L6_DAILY, ContextLayer.L5_WEEKLY, "pnl", "mean"
+        )
+        assert result == pytest.approx(150.0)
+
+    def test_aggregate_to_higher_layer_sum(self, summarizer: ContextSummarizer) -> None:
+        """aggregate_to_higher_layer with 'sum' must return the total."""
+        store = summarizer.store
+        store.set_context(ContextLayer.L6_DAILY, "2026-02-01", "day1", {"pnl": 100.0})
+        store.set_context(ContextLayer.L6_DAILY, "2026-02-01", "day2", {"pnl": 200.0})
+
+        result = summarizer.aggregate_to_higher_layer(
+            ContextLayer.L6_DAILY, ContextLayer.L5_WEEKLY, "pnl", "sum"
+        )
+        assert result == pytest.approx(300.0)
+
+    def test_aggregate_to_higher_layer_max(self, summarizer: ContextSummarizer) -> None:
+        """aggregate_to_higher_layer with 'max' must return the maximum."""
+        store = summarizer.store
+        store.set_context(ContextLayer.L6_DAILY, "2026-02-01", "day1", {"pnl": 100.0})
+        store.set_context(ContextLayer.L6_DAILY, "2026-02-01", "day2", {"pnl": 200.0})
+
+        result = summarizer.aggregate_to_higher_layer(
+            ContextLayer.L6_DAILY, ContextLayer.L5_WEEKLY, "pnl", "max"
+        )
+        assert result == pytest.approx(200.0)
+
+    def test_aggregate_to_higher_layer_min(self, summarizer: ContextSummarizer) -> None:
+        """aggregate_to_higher_layer with 'min' must return the minimum."""
+        store = summarizer.store
+        store.set_context(ContextLayer.L6_DAILY, "2026-02-01", "day1", {"pnl": 100.0})
+        store.set_context(ContextLayer.L6_DAILY, "2026-02-01", "day2", {"pnl": 200.0})
+
+        result = summarizer.aggregate_to_higher_layer(
+            ContextLayer.L6_DAILY, ContextLayer.L5_WEEKLY, "pnl", "min"
+        )
+        assert result == pytest.approx(100.0)
+
+    def test_aggregate_to_higher_layer_no_data(self, summarizer: ContextSummarizer) -> None:
+        """aggregate_to_higher_layer with no matching key must return None."""
+        result = summarizer.aggregate_to_higher_layer(
+            ContextLayer.L6_DAILY, ContextLayer.L5_WEEKLY, "nonexistent", "mean"
+        )
+        assert result is None
+
+    def test_aggregate_to_higher_layer_unknown_func_defaults_to_mean(
+        self, summarizer: ContextSummarizer
+    ) -> None:
+        """Unknown aggregation function must fall back to mean."""
+        store = summarizer.store
+        store.set_context(ContextLayer.L6_DAILY, "2026-02-01", "day1", {"pnl": 100.0})
+        store.set_context(ContextLayer.L6_DAILY, "2026-02-01", "day2", {"pnl": 200.0})
+
+        result = summarizer.aggregate_to_higher_layer(
+            ContextLayer.L6_DAILY, ContextLayer.L5_WEEKLY, "pnl", "unknown_func"
+        )
+        assert result == pytest.approx(150.0)
+
+    # ------------------------------------------------------------------
+    # create_compact_summary + format_summary_for_prompt
+    # ------------------------------------------------------------------
+
+    def test_create_compact_summary(self, summarizer: ContextSummarizer) -> None:
+        """create_compact_summary must produce a dict keyed by layer value."""
+        store = summarizer.store
+        store.set_context(ContextLayer.L6_DAILY, "2026-02-01", "pnl", 100.0)
+
+        result = summarizer.create_compact_summary([ContextLayer.L6_DAILY])
+        assert ContextLayer.L6_DAILY.value in result
+
+    def test_format_summary_for_prompt_with_numeric_metrics(
+        self, summarizer: ContextSummarizer
+    ) -> None:
+        """format_summary_for_prompt must render avg/trend fields."""
+        store = summarizer.store
+        store.set_context(ContextLayer.L6_DAILY, "2026-02-01", "pnl", 100.0)
+        store.set_context(ContextLayer.L6_DAILY, "2026-02-02", "pnl", 200.0)
+
+        compact = summarizer.create_compact_summary([ContextLayer.L6_DAILY])
+        text = summarizer.format_summary_for_prompt(compact)
+        assert isinstance(text, str)
+
+    def test_format_summary_for_prompt_skips_empty_layers(
+        self, summarizer: ContextSummarizer
+    ) -> None:
+        """format_summary_for_prompt must skip layers with no metrics."""
+        summary = {ContextLayer.L6_DAILY.value: {}}
+        text = summarizer.format_summary_for_prompt(summary)
+        assert text == ""
+
+    def test_format_summary_non_dict_value(self, summarizer: ContextSummarizer) -> None:
+        """format_summary_for_prompt must render non-dict values as plain text."""
+        summary = {
+            "daily": {
+                "plain_count": 42,
+            }
+        }
+        text = summarizer.format_summary_for_prompt(summary)
+        assert "plain_count" in text
+        assert "42" in text

tests/test_daily_review.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import json
 import sqlite3
+from datetime import UTC, datetime
 from types import SimpleNamespace
 from unittest.mock import AsyncMock, MagicMock
 
@@ -16,8 +17,6 @@ from src.evolution.daily_review import DailyReviewer
 from src.evolution.scorecard import DailyScorecard
 from src.logging.decision_logger import DecisionLogger
 
-from datetime import UTC, datetime
-
 TODAY = datetime.now(UTC).strftime("%Y-%m-%d")
 
 
@@ -53,7 +52,8 @@ def _log_decision(
 
 
 def test_generate_scorecard_market_scoped(
-    db_conn: sqlite3.Connection, context_store: ContextStore,
+    db_conn: sqlite3.Connection,
+    context_store: ContextStore,
 ) -> None:
     reviewer = DailyReviewer(db_conn, context_store)
     logger = DecisionLogger(db_conn)
@@ -134,7 +134,8 @@ def test_generate_scorecard_market_scoped(
 
 
 def test_generate_scorecard_top_winners_and_losers(
-    db_conn: sqlite3.Connection, context_store: ContextStore,
+    db_conn: sqlite3.Connection,
+    context_store: ContextStore,
 ) -> None:
     reviewer = DailyReviewer(db_conn, context_store)
     logger = DecisionLogger(db_conn)
@@ -168,7 +169,8 @@ def test_generate_scorecard_top_winners_and_losers(
 
 
 def test_generate_scorecard_empty_day(
-    db_conn: sqlite3.Connection, context_store: ContextStore,
+    db_conn: sqlite3.Connection,
+    context_store: ContextStore,
 ) -> None:
     reviewer = DailyReviewer(db_conn, context_store)
     scorecard = reviewer.generate_scorecard(TODAY, "KR")
@@ -184,7 +186,8 @@ def test_generate_scorecard_empty_day(
 
 @pytest.mark.asyncio
 async def test_generate_lessons_without_gemini_returns_empty(
-    db_conn: sqlite3.Connection, context_store: ContextStore,
+    db_conn: sqlite3.Connection,
+    context_store: ContextStore,
 ) -> None:
     reviewer = DailyReviewer(db_conn, context_store, gemini_client=None)
     lessons = await reviewer.generate_lessons(
@@ -206,7 +209,8 @@ async def test_generate_lessons_without_gemini_returns_empty(
 
 @pytest.mark.asyncio
 async def test_generate_lessons_parses_json_array(
-    db_conn: sqlite3.Connection, context_store: ContextStore,
+    db_conn: sqlite3.Connection,
+    context_store: ContextStore,
 ) -> None:
     mock_gemini = MagicMock()
     mock_gemini.decide = AsyncMock(
@@ -233,7 +237,8 @@ async def test_generate_lessons_parses_json_array(
 
 @pytest.mark.asyncio
 async def test_generate_lessons_fallback_to_lines(
-    db_conn: sqlite3.Connection, context_store: ContextStore,
+    db_conn: sqlite3.Connection,
+    context_store: ContextStore,
 ) -> None:
     mock_gemini = MagicMock()
     mock_gemini.decide = AsyncMock(
@@ -260,7 +265,8 @@ async def test_generate_lessons_fallback_to_lines(
 
 @pytest.mark.asyncio
 async def test_generate_lessons_handles_gemini_error(
-    db_conn: sqlite3.Connection, context_store: ContextStore,
+    db_conn: sqlite3.Connection,
+    context_store: ContextStore,
 ) -> None:
     mock_gemini = MagicMock()
     mock_gemini.decide = AsyncMock(side_effect=RuntimeError("boom"))
@@ -284,7 +290,8 @@ async def test_generate_lessons_handles_gemini_error(
 
 
 def test_store_scorecard_in_context(
-    db_conn: sqlite3.Connection, context_store: ContextStore,
+    db_conn: sqlite3.Connection,
+    context_store: ContextStore,
 ) -> None:
     reviewer = DailyReviewer(db_conn, context_store)
     scorecard = DailyScorecard(
@@ -316,7 +323,8 @@ def test_store_scorecard_in_context(
 
 
 def test_store_scorecard_key_is_market_scoped(
-    db_conn: sqlite3.Connection, context_store: ContextStore,
+    db_conn: sqlite3.Connection,
+    context_store: ContextStore,
 ) -> None:
     reviewer = DailyReviewer(db_conn, context_store)
     kr = DailyScorecard(
@@ -357,7 +365,8 @@ def test_store_scorecard_key_is_market_scoped(
 
 
 def test_generate_scorecard_handles_invalid_context_snapshot(
-    db_conn: sqlite3.Connection, context_store: ContextStore,
+    db_conn: sqlite3.Connection,
+    context_store: ContextStore,
 ) -> None:
     reviewer = DailyReviewer(db_conn, context_store)
     db_conn.execute(

tests/test_dashboard.py

@@ -355,6 +355,7 @@ def test_positions_empty_when_no_trades(tmp_path: Path) -> None:
 
 def _seed_cb_context(conn: sqlite3.Connection, pnl_pct: float, market: str = "KR") -> None:
     import json as _json
+
     conn.execute(
         "INSERT OR REPLACE INTO system_metrics (key, value, updated_at) VALUES (?, ?, ?)",
         (
@@ -413,3 +414,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"

tests/test_data_integration.py

@@ -79,7 +79,7 @@ class TestNewsAPI:
         # Mock the fetch to avoid real API call
         with patch.object(api, "_fetch_news", new_callable=AsyncMock) as mock_fetch:
             mock_fetch.return_value = None
-            result = await api.get_news_sentiment("AAPL")
+            await api.get_news_sentiment("AAPL")
 
             # Should have attempted refetch since cache expired
             mock_fetch.assert_called_once_with("AAPL")
@@ -111,9 +111,7 @@ class TestNewsAPI:
                     "source": "Reuters",
                     "time_published": "2026-02-04T10:00:00",
                     "url": "https://example.com/1",
-                    "ticker_sentiment": [
-                        {"ticker": "AAPL", "ticker_sentiment_score": "0.85"}
-                    ],
+                    "ticker_sentiment": [{"ticker": "AAPL", "ticker_sentiment_score": "0.85"}],
                     "overall_sentiment_score": "0.75",
                 },
                 {
@@ -122,9 +120,7 @@ class TestNewsAPI:
                     "source": "Bloomberg",
                     "time_published": "2026-02-04T09:00:00",
                     "url": "https://example.com/2",
-                    "ticker_sentiment": [
-                        {"ticker": "AAPL", "ticker_sentiment_score": "-0.3"}
-                    ],
+                    "ticker_sentiment": [{"ticker": "AAPL", "ticker_sentiment_score": "-0.3"}],
                     "overall_sentiment_score": "-0.2",
                 },
             ]
@@ -661,7 +657,9 @@ class TestGeminiClientWithExternalData:
         )
 
         # Mock the Gemini API call
-        with patch.object(client._client.aio.models, "generate_content", new_callable=AsyncMock) as mock_gen:
+        with patch.object(
+            client._client.aio.models, "generate_content", new_callable=AsyncMock
+        ) as mock_gen:
             mock_response = MagicMock()
             mock_response.text = '{"action": "BUY", "confidence": 85, "rationale": "Good news"}'
             mock_gen.return_value = mock_response

tests/test_db.py

@@ -1,6 +1,9 @@
 """Tests for database helper functions."""
 
-from src.db import get_open_position, init_db, log_trade
+import os
+import tempfile
+
+from src.db import get_latest_buy_trade, get_open_position, init_db, log_trade
 
 
 def test_get_open_position_returns_latest_buy() -> None:
@@ -58,3 +61,356 @@ def test_get_open_position_returns_none_when_latest_is_sell() -> None:
 def test_get_open_position_returns_none_when_no_trades() -> None:
     conn = init_db(":memory:")
     assert get_open_position(conn, "AAPL", "US_NASDAQ") is None
+
+
+# ---------------------------------------------------------------------------
+# WAL mode tests (issue #210)
+# ---------------------------------------------------------------------------
+
+
+def test_wal_mode_applied_to_file_db() -> None:
+    """File-based DB must use WAL journal mode for dashboard concurrent reads."""
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+        db_path = f.name
+    try:
+        conn = init_db(db_path)
+        cursor = conn.execute("PRAGMA journal_mode")
+        mode = cursor.fetchone()[0]
+        assert mode == "wal", f"Expected WAL mode, got {mode}"
+        conn.close()
+    finally:
+        os.unlink(db_path)
+        # Clean up WAL auxiliary files if they exist
+        for ext in ("-wal", "-shm"):
+            path = db_path + ext
+            if os.path.exists(path):
+                os.unlink(path)
+
+
+def test_wal_mode_not_applied_to_memory_db() -> None:
+    """:memory: DB must not apply WAL (SQLite does not support WAL for in-memory)."""
+    conn = init_db(":memory:")
+    cursor = conn.execute("PRAGMA journal_mode")
+    mode = cursor.fetchone()[0]
+    # In-memory DBs default to 'memory' journal mode
+    assert mode != "wal", "WAL should not be set on in-memory database"
+    conn.close()
+
+
+# ---------------------------------------------------------------------------
+# mode column tests (issue #212)
+# ---------------------------------------------------------------------------
+
+
+def test_log_trade_stores_mode_paper() -> None:
+    """log_trade must persist mode='paper' in the trades table."""
+    conn = init_db(":memory:")
+    log_trade(
+        conn=conn,
+        stock_code="005930",
+        action="BUY",
+        confidence=85,
+        rationale="test",
+        mode="paper",
+    )
+    row = conn.execute("SELECT mode FROM trades ORDER BY id DESC LIMIT 1").fetchone()
+    assert row is not None
+    assert row[0] == "paper"
+
+
+def test_log_trade_stores_mode_live() -> None:
+    """log_trade must persist mode='live' in the trades table."""
+    conn = init_db(":memory:")
+    log_trade(
+        conn=conn,
+        stock_code="005930",
+        action="BUY",
+        confidence=85,
+        rationale="test",
+        mode="live",
+    )
+    row = conn.execute("SELECT mode FROM trades ORDER BY id DESC LIMIT 1").fetchone()
+    assert row is not None
+    assert row[0] == "live"
+
+
+def test_log_trade_default_mode_is_paper() -> None:
+    """log_trade without explicit mode must default to 'paper'."""
+    conn = init_db(":memory:")
+    log_trade(
+        conn=conn,
+        stock_code="005930",
+        action="HOLD",
+        confidence=50,
+        rationale="test",
+    )
+    row = conn.execute("SELECT mode FROM trades ORDER BY id DESC LIMIT 1").fetchone()
+    assert row is not None
+    assert row[0] == "paper"
+
+
+def test_mode_column_exists_in_schema() -> None:
+    """trades table must have a mode column after init_db."""
+    conn = init_db(":memory:")
+    cursor = conn.execute("PRAGMA table_info(trades)")
+    columns = {row[1] for row in cursor.fetchall()}
+    assert "mode" in columns
+    assert "session_id" in columns
+    assert "strategy_pnl" in columns
+    assert "fx_pnl" in columns
+
+
+def test_mode_migration_adds_column_to_existing_db() -> None:
+    """init_db must add mode column to existing DBs that lack it (migration)."""
+    import sqlite3
+
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+        db_path = f.name
+    try:
+        # Create DB without mode column (simulate old schema)
+        old_conn = sqlite3.connect(db_path)
+        old_conn.execute(
+            """CREATE TABLE trades (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                timestamp TEXT NOT NULL,
+                stock_code TEXT NOT NULL,
+                action TEXT NOT NULL,
+                confidence INTEGER NOT NULL,
+                rationale TEXT,
+                quantity INTEGER,
+                price REAL,
+                pnl REAL DEFAULT 0.0,
+                market TEXT DEFAULT 'KR',
+                exchange_code TEXT DEFAULT 'KRX',
+                decision_id TEXT
+            )"""
+        )
+        old_conn.execute(
+            """
+            INSERT INTO trades (
+                timestamp, stock_code, action, confidence, rationale, quantity, price, pnl
+            ) VALUES ('2026-01-01T00:00:00+00:00', 'AAPL', 'SELL', 90, 'legacy', 1, 100.0, 123.45)
+            """
+        )
+        old_conn.commit()
+        old_conn.close()
+
+        # Run init_db — should add mode column via migration
+        conn = init_db(db_path)
+        cursor = conn.execute("PRAGMA table_info(trades)")
+        columns = {row[1] for row in cursor.fetchall()}
+        assert "mode" in columns
+        assert "session_id" in columns
+        assert "strategy_pnl" in columns
+        assert "fx_pnl" in columns
+        migrated = conn.execute(
+            "SELECT pnl, strategy_pnl, fx_pnl, session_id "
+            "FROM trades WHERE stock_code='AAPL' LIMIT 1"
+        ).fetchone()
+        assert migrated is not None
+        assert migrated[0] == 123.45
+        assert migrated[1] == 123.45
+        assert migrated[2] == 0.0
+        assert migrated[3] == "UNKNOWN"
+        conn.close()
+    finally:
+        os.unlink(db_path)
+
+
+def test_log_trade_stores_strategy_and_fx_pnl_separately() -> None:
+    conn = init_db(":memory:")
+    log_trade(
+        conn=conn,
+        stock_code="AAPL",
+        action="SELL",
+        confidence=90,
+        rationale="fx split",
+        pnl=120.0,
+        strategy_pnl=100.0,
+        fx_pnl=20.0,
+        market="US_NASDAQ",
+        exchange_code="NASD",
+    )
+    row = conn.execute(
+        "SELECT pnl, strategy_pnl, fx_pnl FROM trades ORDER BY id DESC LIMIT 1"
+    ).fetchone()
+    assert row is not None
+    assert row[0] == 120.0
+    assert row[1] == 100.0
+    assert row[2] == 20.0
+
+
+def test_log_trade_backward_compat_sets_strategy_pnl_from_pnl() -> None:
+    conn = init_db(":memory:")
+    log_trade(
+        conn=conn,
+        stock_code="005930",
+        action="SELL",
+        confidence=80,
+        rationale="legacy",
+        pnl=50.0,
+        market="KR",
+        exchange_code="KRX",
+    )
+    row = conn.execute(
+        "SELECT pnl, strategy_pnl, fx_pnl FROM trades ORDER BY id DESC LIMIT 1"
+    ).fetchone()
+    assert row is not None
+    assert row[0] == 50.0
+    assert row[1] == 50.0
+    assert row[2] == 0.0
+
+
+def test_log_trade_partial_fx_input_does_not_infer_negative_strategy_pnl() -> None:
+    conn = init_db(":memory:")
+    log_trade(
+        conn=conn,
+        stock_code="AAPL",
+        action="SELL",
+        confidence=70,
+        rationale="fx only",
+        pnl=0.0,
+        fx_pnl=10.0,
+        market="US_NASDAQ",
+        exchange_code="NASD",
+    )
+    row = conn.execute(
+        "SELECT pnl, strategy_pnl, fx_pnl FROM trades ORDER BY id DESC LIMIT 1"
+    ).fetchone()
+    assert row is not None
+    assert row[0] == 10.0
+    assert row[1] == 0.0
+    assert row[2] == 10.0
+
+
+def test_log_trade_persists_explicit_session_id() -> None:
+    conn = init_db(":memory:")
+    log_trade(
+        conn=conn,
+        stock_code="AAPL",
+        action="BUY",
+        confidence=70,
+        rationale="session test",
+        market="US_NASDAQ",
+        exchange_code="NASD",
+        session_id="US_PRE",
+    )
+    row = conn.execute("SELECT session_id FROM trades ORDER BY id DESC LIMIT 1").fetchone()
+    assert row is not None
+    assert row[0] == "US_PRE"
+
+
+def test_log_trade_auto_derives_session_id_when_not_provided() -> None:
+    conn = init_db(":memory:")
+    log_trade(
+        conn=conn,
+        stock_code="005930",
+        action="BUY",
+        confidence=70,
+        rationale="auto session",
+        market="KR",
+        exchange_code="KRX",
+    )
+    row = conn.execute("SELECT session_id FROM trades ORDER BY id DESC LIMIT 1").fetchone()
+    assert row is not None
+    assert row[0] != "UNKNOWN"
+
+
+def test_log_trade_unknown_market_falls_back_to_unknown_session() -> None:
+    conn = init_db(":memory:")
+    log_trade(
+        conn=conn,
+        stock_code="X",
+        action="BUY",
+        confidence=70,
+        rationale="unknown market",
+        market="MARS",
+        exchange_code="MARS",
+    )
+    row = conn.execute("SELECT session_id FROM trades ORDER BY id DESC LIMIT 1").fetchone()
+    assert row is not None
+    assert row[0] == "UNKNOWN"
+
+
+def test_get_latest_buy_trade_prefers_exchange_code_match() -> None:
+    conn = init_db(":memory:")
+    log_trade(
+        conn=conn,
+        stock_code="AAPL",
+        action="BUY",
+        confidence=80,
+        rationale="legacy",
+        quantity=10,
+        price=120.0,
+        market="US_NASDAQ",
+        exchange_code="",
+        decision_id="legacy-buy",
+    )
+    log_trade(
+        conn=conn,
+        stock_code="AAPL",
+        action="BUY",
+        confidence=85,
+        rationale="matched",
+        quantity=5,
+        price=125.0,
+        market="US_NASDAQ",
+        exchange_code="NASD",
+        decision_id="matched-buy",
+    )
+    matched = get_latest_buy_trade(
+        conn,
+        stock_code="AAPL",
+        market="US_NASDAQ",
+        exchange_code="NASD",
+    )
+    assert matched is not None
+    assert matched["decision_id"] == "matched-buy"
+
+
+def test_decision_logs_session_id_migration_backfills_unknown() -> None:
+    import sqlite3
+
+    with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+        db_path = f.name
+    try:
+        old_conn = sqlite3.connect(db_path)
+        old_conn.execute(
+            """
+            CREATE TABLE decision_logs (
+                decision_id TEXT PRIMARY KEY,
+                timestamp TEXT NOT NULL,
+                stock_code TEXT NOT NULL,
+                market TEXT NOT NULL,
+                exchange_code TEXT NOT NULL,
+                action TEXT NOT NULL,
+                confidence INTEGER NOT NULL,
+                rationale TEXT NOT NULL,
+                context_snapshot TEXT NOT NULL,
+                input_data TEXT NOT NULL
+            )
+            """
+        )
+        old_conn.execute(
+            """
+            INSERT INTO decision_logs (
+                decision_id, timestamp, stock_code, market, exchange_code,
+                action, confidence, rationale, context_snapshot, input_data
+            ) VALUES (
+                'd1', '2026-01-01T00:00:00+00:00', 'AAPL', 'US_NASDAQ', 'NASD',
+                'BUY', 80, 'legacy row', '{}', '{}'
+            )
+            """
+        )
+        old_conn.commit()
+        old_conn.close()
+
+        conn = init_db(db_path)
+        columns = {row[1] for row in conn.execute("PRAGMA table_info(decision_logs)").fetchall()}
+        assert "session_id" in columns
+        row = conn.execute("SELECT session_id FROM decision_logs WHERE decision_id='d1'").fetchone()
+        assert row is not None
+        assert row[0] == "UNKNOWN"
+        conn.close()
+    finally:
+        os.unlink(db_path)

tests/test_decision_logger.py

@@ -49,7 +49,10 @@ def test_log_decision_creates_record(logger: DecisionLogger, db_conn: sqlite3.Co
 
     # Verify record exists in database
     cursor = db_conn.execute(
-        "SELECT decision_id, action, confidence FROM decision_logs WHERE decision_id = ?",
+        (
+            "SELECT decision_id, action, confidence, session_id "
+            "FROM decision_logs WHERE decision_id = ?"
+        ),
         (decision_id,),
     )
     row = cursor.fetchone()
@@ -57,6 +60,7 @@ def test_log_decision_creates_record(logger: DecisionLogger, db_conn: sqlite3.Co
     assert row[0] == decision_id
     assert row[1] == "BUY"
     assert row[2] == 85
+    assert row[3] == "UNKNOWN"
 
 
 def test_log_decision_stores_context_snapshot(logger: DecisionLogger) -> None:
@@ -84,6 +88,24 @@ def test_log_decision_stores_context_snapshot(logger: DecisionLogger) -> None:
     assert decision is not None
     assert decision.context_snapshot == context_snapshot
     assert decision.input_data == input_data
+    assert decision.session_id == "UNKNOWN"
+
+
+def test_log_decision_stores_explicit_session_id(logger: DecisionLogger) -> None:
+    decision_id = logger.log_decision(
+        stock_code="AAPL",
+        market="US_NASDAQ",
+        exchange_code="NASD",
+        action="BUY",
+        confidence=88,
+        rationale="session check",
+        context_snapshot={},
+        input_data={},
+        session_id="US_PRE",
+    )
+    decision = logger.get_decision_by_id(decision_id)
+    assert decision is not None
+    assert decision.session_id == "US_PRE"
 
 
 def test_get_unreviewed_decisions(logger: DecisionLogger) -> None:
@@ -278,6 +300,7 @@ def test_decision_log_dataclass() -> None:
         stock_code="005930",
         market="KR",
         exchange_code="KRX",
+        session_id="KRX_REG",
         action="BUY",
         confidence=85,
         rationale="Test",
@@ -286,6 +309,7 @@ def test_decision_log_dataclass() -> None:
     )
 
     assert log.decision_id == "test-uuid"
+    assert log.session_id == "KRX_REG"
     assert log.action == "BUY"
     assert log.confidence == 85
     assert log.reviewed is False