feat: add playbook persistence with DB schema and CRUD store (issue #82)

- Add playbooks table to src/db.py with UNIQUE(date, market) constraint
- PlaybookStore: save/load/delete, status management, match_count tracking,
  list_recent with market filter, stats without full deserialization
- DayPlaybook JSON serialization via Pydantic model_dump_json/model_validate_json
- 23 tests, 100% coverage on playbook_store.py

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -45,6 +45,39 @@ Get real-time alerts for trades, circuit breakers, and system events via Telegra
 
 **Fail-safe**: Notifications never crash the trading system. Missing credentials or API errors are logged but trading continues normally.
 
+## Smart Volatility Scanner (Optional)
+
+Python-first filtering pipeline that reduces Gemini API calls by pre-filtering stocks using technical indicators.
+
+### How It Works
+
+1. **Fetch Rankings** — KIS API volume surge rankings (top 30 stocks)
+2. **Python Filter** — RSI + volume ratio calculations (no AI)
+   - Volume > 200% of previous day
+   - RSI(14) < 30 (oversold) OR RSI(14) > 70 (momentum)
+3. **AI Judgment** — Only qualified candidates (1-3 stocks) sent to Gemini
+
+### Configuration
+
+Add to `.env` (optional, has sensible defaults):
+```bash
+RSI_OVERSOLD_THRESHOLD=30    # 0-50, default 30
+RSI_MOMENTUM_THRESHOLD=70    # 50-100, default 70
+VOL_MULTIPLIER=2.0           # Volume threshold (2.0 = 200%)
+SCANNER_TOP_N=3              # Max candidates per scan
+```
+
+### Benefits
+
+- **Reduces API costs** — Process 1-3 stocks instead of 20-30
+- **Python-based filtering** — Fast technical analysis before AI
+- **Evolution-ready** — Selection context logged for strategy optimization
+- **Fault-tolerant** — Falls back to static watchlist on API failure
+
+### Realtime Mode Only
+
+Smart Scanner runs in `TRADE_MODE=realtime` only. Daily mode uses static watchlists for batch efficiency.
+
 ## Documentation
 
 - **[Workflow Guide](docs/workflow.md)** — Git workflow policy and agent-based development
@@ -75,6 +108,7 @@ User requirements and feedback are tracked in [docs/requirements-log.md](docs/re
 
 ```
 src/
+├── analysis/        # Technical analysis (RSI, volatility, smart scanner)
 ├── broker/          # KIS API client (domestic + overseas)
 ├── brain/           # Gemini AI decision engine
 ├── core/            # Risk manager (READ-ONLY)
@@ -85,7 +119,7 @@ src/
 ├── main.py          # Trading loop orchestrator
 └── config.py        # Settings (from .env)
 
-tests/               # 273 tests across 13 files
+tests/               # 343 tests across 14 files
 docs/                # Extended documentation
 ```
 

docs/agent-constraints.md

@@ -0,0 +1,45 @@
+# Agent Constraints
+
+This document records **persistent behavioral constraints** for agents working on this repository.
+It is distinct from `docs/requirements-log.md`, which records **project/product requirements**.
+
+## Scope
+
+- Applies to all AI agents and automation that modify this repo.
+- Supplements (does not replace) `docs/agents.md` and `docs/workflow.md`.
+
+## Persistent Rules
+
+1. **Workflow enforcement**
+   - Follow `docs/workflow.md` for all changes.
+   - 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`.
+
+2. **Document-first routing**
+   - When performing work, consult relevant `docs/` files *before* making changes.
+   - Route decisions to the documented policy whenever applicable.
+   - If guidance conflicts, prefer the stricter/safety-first rule and note it in the PR.
+
+3. **Docs with code**
+   - Any code change must be accompanied by relevant documentation updates.
+   - If no doc update is needed, state the reason explicitly in the PR.
+
+4. **Session-persistent user constraints**
+   - If the user requests that a behavior should persist across sessions, record it here
+     (or in a dedicated policy doc) and reference it when working.
+   - Keep entries short and concrete, with dates.
+
+## Change Control
+
+- Changes to this file follow the same workflow as code changes.
+- Keep the history chronological and minimize rewording of existing entries.
+
+## History
+
+### 2026-02-08
+
+- Always enforce Gitea workflow: issue -> feature branch -> PR before changes.
+- 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.

docs/architecture.md

@@ -64,7 +64,39 @@ High-frequency trading with individual stock analysis:
 - `get_open_markets()` returns currently active markets
 - `get_next_market_open()` finds next market to open and when
 
-### 2. Brain (`src/brain/gemini_client.py`)
+**New API Methods** (added in v0.9.0):
+- `fetch_market_rankings()` — Fetch volume surge rankings from KIS API
+- `get_daily_prices()` — Fetch OHLCV history for technical analysis
+
+### 2. Analysis (`src/analysis/`)
+
+**VolatilityAnalyzer** (`volatility.py`) — Technical indicator calculations
+
+- ATR (Average True Range) for volatility measurement
+- RSI (Relative Strength Index) using Wilder's smoothing method
+- Price change percentages across multiple timeframes
+- Volume surge ratios and price-volume divergence
+- Momentum scoring (0-100 scale)
+- Breakout/breakdown pattern detection
+
+**SmartVolatilityScanner** (`smart_scanner.py`) — Python-first filtering pipeline
+
+- **Step 1**: Fetch volume rankings from KIS API (top 30 stocks)
+- **Step 2**: Calculate RSI and volume ratio for each stock
+- **Step 3**: Apply filters:
+  - Volume ratio >= `VOL_MULTIPLIER` (default 2.0x previous day)
+  - RSI < `RSI_OVERSOLD_THRESHOLD` (30) OR RSI > `RSI_MOMENTUM_THRESHOLD` (70)
+- **Step 4**: Score candidates by RSI extremity (60%) + volume surge (40%)
+- **Step 5**: Return top N candidates (default 3) for AI analysis
+- **Fallback**: Uses static watchlist if ranking API unavailable
+- **Realtime mode only**: Daily mode uses batch processing for API efficiency
+
+**Benefits:**
+- Reduces Gemini API calls from 20-30 stocks to 1-3 qualified candidates
+- Fast Python-based filtering before expensive AI judgment
+- Logs selection context (RSI, volume_ratio, signal, score) for Evolution system
+
+### 3. Brain (`src/brain/gemini_client.py`)
 
 **GeminiClient** — AI decision engine powered by Google Gemini
 
@@ -74,7 +106,7 @@ High-frequency trading with individual stock analysis:
 - Falls back to safe HOLD on any parse/API error
 - Handles markdown-wrapped JSON, malformed responses, invalid actions
 
-### 3. Risk Manager (`src/core/risk_manager.py`)
+### 4. Risk Manager (`src/core/risk_manager.py`)
 
 **RiskManager** — Safety circuit breaker and order validation
 
@@ -86,7 +118,7 @@ High-frequency trading with individual stock analysis:
 - **Fat-Finger Protection**: Rejects orders exceeding 30% of available cash
   - Must always be enforced, cannot be disabled
 
-### 4. Notifications (`src/notifications/telegram_client.py`)
+### 5. Notifications (`src/notifications/telegram_client.py`)
 
 **TelegramClient** — Real-time event notifications via Telegram Bot API
 
@@ -105,7 +137,7 @@ High-frequency trading with individual stock analysis:
 
 **Setup:** See [src/notifications/README.md](../src/notifications/README.md) for bot creation and configuration.
 
-### 5. Evolution (`src/evolution/optimizer.py`)
+### 6. Evolution (`src/evolution/optimizer.py`)
 
 **StrategyOptimizer** — Self-improvement loop
 
@@ -117,9 +149,11 @@ High-frequency trading with individual stock analysis:
 
 ## Data Flow
 
+### Realtime Mode (with Smart Scanner)
+
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│ Main Loop (60s cycle per stock, per market)                │
+│ Main Loop (60s cycle per market)                           │
 └─────────────────────────────────────────────────────────────┘
                            │
                            ▼
@@ -132,6 +166,21 @@ High-frequency trading with individual stock analysis:
                            │
                            ▼
         ┌──────────────────────────────────┐
+        │ Smart Scanner (Python-first)      │
+        │ - Fetch volume rankings (KIS)    │
+        │ - Get 20d price history per stock│
+        │ - Calculate RSI(14) + vol ratio  │
+        │ - Filter: vol>2x AND RSI extreme │
+        │ - Return top 3 qualified stocks  │
+        └──────────────────┬────────────────┘
+                           │
+                           ▼
+        ┌──────────────────────────────────┐
+        │ For Each Qualified Candidate      │
+        └──────────────────┬────────────────┘
+                           │
+                           ▼
+        ┌──────────────────────────────────┐
         │ Broker: Fetch Market Data        │
         │ - Domestic: orderbook + balance  │
         │ - Overseas: price + balance      │
@@ -145,7 +194,7 @@ High-frequency trading with individual stock analysis:
                            │
                            ▼
         ┌──────────────────────────────────┐
-        │ Brain: Get Decision               │
+        │ Brain: Get Decision (AI)          │
         │ - Build prompt with market data   │
         │ - Call Gemini API                 │
         │ - Parse JSON response             │
@@ -181,6 +230,9 @@ High-frequency trading with individual stock analysis:
         │ - SQLite (data/trades.db)         │
         │ - Track: action, confidence,      │
         │   rationale, market, exchange     │
+        │ - NEW: selection_context (JSON)   │
+        │   - RSI, volume_ratio, signal     │
+        │   - For Evolution optimization    │
         └───────────────────────────────────┘
 ```
 
@@ -200,11 +252,24 @@ CREATE TABLE trades (
     price REAL,
     pnl REAL DEFAULT 0.0,
     market TEXT DEFAULT 'KR',       -- KR | US_NASDAQ | JP | etc.
-    exchange_code TEXT DEFAULT 'KRX' -- KRX | NASD | NYSE | etc.
+    exchange_code TEXT DEFAULT 'KRX', -- KRX | NASD | NYSE | etc.
+    selection_context TEXT          -- JSON: {rsi, volume_ratio, signal, score}
 );
 ```
 
-Auto-migration: Adds `market` and `exchange_code` columns if missing for backward compatibility.
+**Selection Context** (new in v0.9.0): Stores scanner selection criteria as JSON:
+```json
+{
+  "rsi": 28.5,
+  "volume_ratio": 2.7,
+  "signal": "oversold",
+  "score": 85.2
+}
+```
+
+Enables Evolution system to analyze correlation between selection criteria and trade outcomes.
+
+Auto-migration: Adds `market`, `exchange_code`, and `selection_context` columns if missing for backward compatibility.
 
 ## Configuration
 
@@ -236,6 +301,12 @@ SESSION_INTERVAL_HOURS=6      # Hours between sessions (daily mode only)
 TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
 TELEGRAM_CHAT_ID=123456789
 TELEGRAM_ENABLED=true
+
+# Smart Scanner (optional, realtime mode only)
+RSI_OVERSOLD_THRESHOLD=30    # 0-50, oversold threshold
+RSI_MOMENTUM_THRESHOLD=70    # 50-100, momentum threshold
+VOL_MULTIPLIER=2.0           # Minimum volume ratio (2.0 = 200%)
+SCANNER_TOP_N=3              # Max qualified candidates per scan
 ```
 
 Tests use in-memory SQLite (`DB_PATH=":memory:"`) and dummy credentials via `tests/conftest.py`.

docs/requirements-log.md

@@ -26,3 +26,41 @@
 ### 문서화
 - 시스템 구조, 기능별 설명 등 코드 문서화 항상 신경쓸 것
 - 새로운 기능 추가 시 관련 문서 업데이트 필수
+
+---
+
+## 2026-02-06
+
+### Smart Volatility Scanner (Python-First, AI-Last 파이프라인)
+
+**배경:**
+- 정적 종목 리스트를 순회하는 방식은 비효율적
+- KIS API 거래량 순위를 통해 시장 주도주를 자동 탐지해야 함
+- Gemini API 호출 전에 Python 기반 기술적 분석으로 필터링 필요
+
+**요구사항:**
+1. KIS API 거래량 순위 API 통합 (`fetch_market_rankings`)
+2. 일별 가격 히스토리 API 추가 (`get_daily_prices`)
+3. RSI(14) 계산 기능 구현 (Wilder's smoothing method)
+4. 필터 조건:
+   - 거래량 > 전일 대비 200% (VOL_MULTIPLIER)
+   - RSI < 30 (과매도) OR RSI > 70 (모멘텀)
+5. 상위 1-3개 적격 종목만 Gemini에 전달
+6. 종목 선정 배경(RSI, volume_ratio, signal, score) 데이터베이스 기록
+
+**구현 결과:**
+- `src/analysis/smart_scanner.py`: SmartVolatilityScanner 클래스
+- `src/analysis/volatility.py`: calculate_rsi() 메서드 추가
+- `src/broker/kis_api.py`: 2개 신규 API 메서드
+- `src/db.py`: selection_context 컬럼 추가
+- 설정 가능한 임계값: RSI_OVERSOLD_THRESHOLD, RSI_MOMENTUM_THRESHOLD, VOL_MULTIPLIER, SCANNER_TOP_N
+
+**효과:**
+- Gemini API 호출 20-30개 → 1-3개로 감소
+- Python 기반 빠른 필터링 → 비용 절감
+- 선정 기준 추적 → Evolution 시스템 최적화 가능
+- API 장애 시 정적 watchlist로 자동 전환
+
+**참고:** Realtime 모드 전용. Daily 모드는 배치 효율성을 위해 정적 watchlist 사용.
+
+**이슈/PR:** #76, #77

docs/workflow.md

@@ -6,6 +6,7 @@
 
 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)

src/analysis/__init__.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from src.analysis.scanner import MarketScanner
+from src.analysis.smart_scanner import ScanCandidate, SmartVolatilityScanner
 from src.analysis.volatility import VolatilityAnalyzer
 
-__all__ = ["VolatilityAnalyzer", "MarketScanner"]
+__all__ = ["VolatilityAnalyzer", "MarketScanner", "SmartVolatilityScanner", "ScanCandidate"]

src/analysis/smart_scanner.py

@@ -0,0 +1,192 @@
+"""Smart Volatility Scanner with RSI and volume filters.
+
+Fetches market rankings from KIS API and applies technical filters
+to identify high-probability trading candidates.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+from src.analysis.volatility import VolatilityAnalyzer
+from src.broker.kis_api import KISBroker
+from src.config import Settings
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ScanCandidate:
+    """A qualified candidate from the smart scanner."""
+
+    stock_code: str
+    name: str
+    price: float
+    volume: float
+    volume_ratio: float  # Current volume / previous day volume
+    rsi: float
+    signal: str  # "oversold" or "momentum"
+    score: float  # Composite score for ranking
+
+
+class SmartVolatilityScanner:
+    """Scans market rankings and applies RSI/volume filters.
+
+    Flow:
+    1. Fetch volume rankings from KIS API
+    2. For each ranked stock, fetch daily prices
+    3. Calculate RSI and volume ratio
+    4. Apply filters: volume > VOL_MULTIPLIER AND (RSI < 30 OR RSI > 70)
+    5. Return top N qualified candidates
+    """
+
+    def __init__(
+        self,
+        broker: KISBroker,
+        volatility_analyzer: VolatilityAnalyzer,
+        settings: Settings,
+    ) -> None:
+        """Initialize the smart scanner.
+
+        Args:
+            broker: KIS broker for API calls
+            volatility_analyzer: Analyzer for RSI calculation
+            settings: Application settings
+        """
+        self.broker = broker
+        self.analyzer = volatility_analyzer
+        self.settings = settings
+
+        # Extract scanner settings
+        self.rsi_oversold = settings.RSI_OVERSOLD_THRESHOLD
+        self.rsi_momentum = settings.RSI_MOMENTUM_THRESHOLD
+        self.vol_multiplier = settings.VOL_MULTIPLIER
+        self.top_n = settings.SCANNER_TOP_N
+
+    async def scan(
+        self,
+        fallback_stocks: list[str] | None = None,
+    ) -> list[ScanCandidate]:
+        """Execute smart scan and return qualified candidates.
+
+        Args:
+            fallback_stocks: Stock codes to use if ranking API fails
+
+        Returns:
+            List of ScanCandidate, sorted by score, up to top_n items
+        """
+        # Step 1: Fetch rankings
+        try:
+            rankings = await self.broker.fetch_market_rankings(
+                ranking_type="volume",
+                limit=30,  # Fetch more than needed for filtering
+            )
+            logger.info("Fetched %d stocks from volume rankings", len(rankings))
+        except ConnectionError as exc:
+            logger.warning("Ranking API failed, using fallback: %s", exc)
+            if fallback_stocks:
+                # Create minimal ranking data for fallback
+                rankings = [
+                    {
+                        "stock_code": code,
+                        "name": code,
+                        "price": 0,
+                        "volume": 0,
+                        "change_rate": 0,
+                        "volume_increase_rate": 0,
+                    }
+                    for code in fallback_stocks
+                ]
+            else:
+                return []
+
+        # Step 2: Analyze each stock
+        candidates: list[ScanCandidate] = []
+
+        for stock in rankings:
+            stock_code = stock["stock_code"]
+            if not stock_code:
+                continue
+
+            try:
+                # Fetch daily prices for RSI calculation
+                daily_prices = await self.broker.get_daily_prices(stock_code, days=20)
+
+                if len(daily_prices) < 15:  # Need at least 14+1 for RSI
+                    logger.debug("Insufficient price history for %s", stock_code)
+                    continue
+
+                # Calculate RSI
+                close_prices = [p["close"] for p in daily_prices]
+                rsi = self.analyzer.calculate_rsi(close_prices, period=14)
+
+                # Calculate volume ratio (today vs previous day avg)
+                if len(daily_prices) >= 2:
+                    prev_day_volume = daily_prices[-2]["volume"]
+                    current_volume = stock.get("volume", 0) or daily_prices[-1]["volume"]
+                    volume_ratio = (
+                        current_volume / prev_day_volume if prev_day_volume > 0 else 1.0
+                    )
+                else:
+                    volume_ratio = stock.get("volume_increase_rate", 0) / 100 + 1  # Fallback
+
+                # Apply filters
+                volume_qualified = volume_ratio >= self.vol_multiplier
+                rsi_oversold = rsi < self.rsi_oversold
+                rsi_momentum = rsi > self.rsi_momentum
+
+                if volume_qualified and (rsi_oversold or rsi_momentum):
+                    signal = "oversold" if rsi_oversold else "momentum"
+
+                    # Calculate composite score
+                    # Higher score for: extreme RSI + high volume
+                    rsi_extremity = abs(rsi - 50) / 50  # 0-1 scale
+                    volume_score = min(volume_ratio / 5, 1.0)  # Cap at 5x
+                    score = (rsi_extremity * 0.6 + volume_score * 0.4) * 100
+
+                    candidates.append(
+                        ScanCandidate(
+                            stock_code=stock_code,
+                            name=stock.get("name", stock_code),
+                            price=stock.get("price", daily_prices[-1]["close"]),
+                            volume=current_volume,
+                            volume_ratio=volume_ratio,
+                            rsi=rsi,
+                            signal=signal,
+                            score=score,
+                        )
+                    )
+
+                    logger.info(
+                        "Qualified: %s (%s) RSI=%.1f vol=%.1fx signal=%s score=%.1f",
+                        stock_code,
+                        stock.get("name", ""),
+                        rsi,
+                        volume_ratio,
+                        signal,
+                        score,
+                    )
+
+            except ConnectionError as exc:
+                logger.warning("Failed to analyze %s: %s", stock_code, exc)
+                continue
+            except Exception as exc:
+                logger.error("Unexpected error analyzing %s: %s", stock_code, exc)
+                continue
+
+        # Sort by score and return top N
+        candidates.sort(key=lambda c: c.score, reverse=True)
+        return candidates[: self.top_n]
+
+    def get_stock_codes(self, candidates: list[ScanCandidate]) -> list[str]:
+        """Extract stock codes from candidates for watchlist update.
+
+        Args:
+            candidates: List of scan candidates
+
+        Returns:
+            List of stock codes
+        """
+        return [c.stock_code for c in candidates]

src/analysis/volatility.py

@@ -124,6 +124,54 @@ class VolatilityAnalyzer:
             return 1.0
         return current_volume / avg_volume
 
+    def calculate_rsi(
+        self,
+        close_prices: list[float],
+        period: int = 14,
+    ) -> float:
+        """Calculate Relative Strength Index (RSI) using Wilder's smoothing.
+
+        Args:
+            close_prices: List of closing prices (oldest to newest, minimum period+1 values)
+            period: RSI period (default 14)
+
+        Returns:
+            RSI value between 0 and 100, or 50.0 (neutral) if insufficient data
+
+        Examples:
+            >>> analyzer = VolatilityAnalyzer()
+            >>> prices = [100 - i * 0.5 for i in range(20)]  # Downtrend
+            >>> rsi = analyzer.calculate_rsi(prices)
+            >>> assert rsi < 50  # Oversold territory
+        """
+        if len(close_prices) < period + 1:
+            return 50.0  # Neutral RSI if insufficient data
+
+        # Calculate price changes
+        changes = [close_prices[i] - close_prices[i - 1] for i in range(1, len(close_prices))]
+
+        # Separate gains and losses
+        gains = [max(0.0, change) for change in changes]
+        losses = [max(0.0, -change) for change in changes]
+
+        # Calculate initial average gain/loss (simple average for first period)
+        avg_gain = sum(gains[:period]) / period
+        avg_loss = sum(losses[:period]) / period
+
+        # Apply Wilder's smoothing for remaining periods
+        for i in range(period, len(changes)):
+            avg_gain = (avg_gain * (period - 1) + gains[i]) / period
+            avg_loss = (avg_loss * (period - 1) + losses[i]) / period
+
+        # Calculate RS and RSI
+        if avg_loss == 0:
+            return 100.0  # All gains, maximum RSI
+
+        rs = avg_gain / avg_loss
+        rsi = 100 - (100 / (1 + rs))
+
+        return rsi
+
     def calculate_pv_divergence(
         self,
         price_change: float,

src/broker/kis_api.py

@@ -280,3 +280,153 @@ class KISBroker:
                 return data
         except (TimeoutError, aiohttp.ClientError) as exc:
             raise ConnectionError(f"Network error sending order: {exc}") from exc
+
+    async def fetch_market_rankings(
+        self,
+        ranking_type: str = "volume",
+        limit: int = 30,
+    ) -> list[dict[str, Any]]:
+        """Fetch market rankings from KIS API.
+
+        Args:
+            ranking_type: Type of ranking ("volume" or "fluctuation")
+            limit: Maximum number of results to return
+
+        Returns:
+            List of stock data dicts with keys: stock_code, name, price, volume,
+            change_rate, volume_increase_rate
+
+        Raises:
+            ConnectionError: If API request fails
+        """
+        await self._rate_limiter.acquire()
+        session = self._get_session()
+
+        # TR_ID for volume ranking
+        tr_id = "FHPST01710000" if ranking_type == "volume" else "FHPST01710100"
+        headers = await self._auth_headers(tr_id)
+
+        params = {
+            "FID_COND_MRKT_DIV_CODE": "J",  # Stock/ETF/ETN
+            "FID_COND_SCR_DIV_CODE": "20001",  # Volume surge
+            "FID_INPUT_ISCD": "0000",  # All stocks
+            "FID_DIV_CLS_CODE": "0",  # All types
+            "FID_BLNG_CLS_CODE": "0",
+            "FID_TRGT_CLS_CODE": "111111111",
+            "FID_TRGT_EXLS_CLS_CODE": "000000",
+            "FID_INPUT_PRICE_1": "0",
+            "FID_INPUT_PRICE_2": "0",
+            "FID_VOL_CNT": "0",
+            "FID_INPUT_DATE_1": "",
+        }
+
+        url = f"{self._base_url}/uapi/domestic-stock/v1/quotations/volume-rank"
+
+        try:
+            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}"
+                    )
+                data = await resp.json()
+
+            # Parse response - output is a list of ranked stocks
+            def _safe_float(value: str | float | None, default: float = 0.0) -> float:
+                if value is None or value == "":
+                    return default
+                try:
+                    return float(value)
+                except (ValueError, TypeError):
+                    return default
+
+            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")),
+                })
+            return rankings
+
+        except (TimeoutError, aiohttp.ClientError) as exc:
+            raise ConnectionError(f"Network error fetching rankings: {exc}") from exc
+
+    async def get_daily_prices(
+        self,
+        stock_code: str,
+        days: int = 20,
+    ) -> list[dict[str, Any]]:
+        """Fetch daily OHLCV price history for a stock.
+
+        Args:
+            stock_code: 6-digit stock code
+            days: Number of trading days to fetch (default 20 for RSI calculation)
+
+        Returns:
+            List of daily price dicts with keys: date, open, high, low, close, volume
+            Sorted oldest to newest
+
+        Raises:
+            ConnectionError: If API request fails
+        """
+        await self._rate_limiter.acquire()
+        session = self._get_session()
+
+        headers = await self._auth_headers("FHKST03010100")
+
+        # 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")
+
+        params = {
+            "FID_COND_MRKT_DIV_CODE": "J",
+            "FID_INPUT_ISCD": stock_code,
+            "FID_INPUT_DATE_1": start_date,
+            "FID_INPUT_DATE_2": end_date,
+            "FID_PERIOD_DIV_CODE": "D",  # Daily
+            "FID_ORG_ADJ_PRC": "0",  # Adjusted price
+        }
+
+        url = f"{self._base_url}/uapi/domestic-stock/v1/quotations/inquire-daily-itemchartprice"
+
+        try:
+            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}"
+                    )
+                data = await resp.json()
+
+            # Parse response
+            def _safe_float(value: str | float | None, default: float = 0.0) -> float:
+                if value is None or value == "":
+                    return default
+                try:
+                    return float(value)
+                except (ValueError, TypeError):
+                    return default
+
+            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")),
+                })
+
+            # Sort oldest to newest (KIS returns newest first)
+            prices.reverse()
+
+            return prices[:days]  # Return only requested number of days
+
+        except (TimeoutError, aiohttp.ClientError) as exc:
+            raise ConnectionError(f"Network error fetching daily prices: {exc}") from exc

src/config.py

@@ -33,6 +33,12 @@ class Settings(BaseSettings):
     FAT_FINGER_PCT: float = Field(default=30.0, gt=0.0, le=100.0)
     CONFIDENCE_THRESHOLD: int = Field(default=80, ge=0, le=100)
 
+    # Smart Scanner Configuration
+    RSI_OVERSOLD_THRESHOLD: int = Field(default=30, ge=0, le=50)
+    RSI_MOMENTUM_THRESHOLD: int = Field(default=70, ge=50, le=100)
+    VOL_MULTIPLIER: float = Field(default=2.0, gt=1.0, le=10.0)
+    SCANNER_TOP_N: int = Field(default=3, ge=1, le=10)
+
     # Database
     DB_PATH: str = "data/trade_logs.db"
 
@@ -49,8 +55,15 @@ class Settings(BaseSettings):
     DAILY_SESSIONS: int = Field(default=4, ge=1, le=10)
     SESSION_INTERVAL_HOURS: int = Field(default=6, ge=1, le=24)
 
+    # Pre-Market Planner
+    PRE_MARKET_MINUTES: int = Field(default=30, ge=10, le=120)
+    MAX_SCENARIOS_PER_STOCK: int = Field(default=5, ge=1, le=10)
+    PLANNER_TIMEOUT_SECONDS: int = Field(default=60, ge=10, le=300)
+    DEFENSIVE_PLAYBOOK_ON_FAILURE: bool = True
+    RESCAN_INTERVAL_SECONDS: int = Field(default=300, ge=60, le=900)
+
     # Market selection (comma-separated market codes)
-    ENABLED_MARKETS: str = "KR"
+    ENABLED_MARKETS: str = "KR,US"
 
     # Backup and Disaster Recovery (optional)
     BACKUP_ENABLED: bool = True

src/db.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import json
 import sqlite3
 from datetime import UTC, datetime
 from pathlib import Path
@@ -38,6 +39,8 @@ def init_db(db_path: str) -> sqlite3.Connection:
         conn.execute("ALTER TABLE trades ADD COLUMN market TEXT DEFAULT 'KR'")
     if "exchange_code" not in columns:
         conn.execute("ALTER TABLE trades ADD COLUMN exchange_code TEXT DEFAULT 'KRX'")
+    if "selection_context" not in columns:
+        conn.execute("ALTER TABLE trades ADD COLUMN selection_context TEXT")
 
     # Context tree tables for multi-layered memory management
     conn.execute(
@@ -88,6 +91,27 @@ def init_db(db_path: str) -> sqlite3.Connection:
         """
     )
 
+    # Playbook storage for pre-market strategy persistence
+    conn.execute(
+        """
+        CREATE TABLE IF NOT EXISTS playbooks (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            date TEXT NOT NULL,
+            market TEXT NOT NULL,
+            status TEXT NOT NULL DEFAULT 'pending',
+            playbook_json TEXT NOT NULL,
+            generated_at TEXT NOT NULL,
+            token_count INTEGER DEFAULT 0,
+            scenario_count INTEGER DEFAULT 0,
+            match_count INTEGER DEFAULT 0,
+            UNIQUE(date, market)
+        )
+        """
+    )
+
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_playbooks_date ON playbooks(date)")
+    conn.execute("CREATE INDEX IF NOT EXISTS idx_playbooks_market ON playbooks(market)")
+
     # Create indices for efficient context queries
     conn.execute("CREATE INDEX IF NOT EXISTS idx_contexts_layer ON contexts(layer)")
     conn.execute("CREATE INDEX IF NOT EXISTS idx_contexts_timeframe ON contexts(timeframe)")
@@ -118,15 +142,33 @@ def log_trade(
     pnl: float = 0.0,
     market: str = "KR",
     exchange_code: str = "KRX",
+    selection_context: dict[str, any] | None = None,
 ) -> None:
-    """Insert a trade record into the database."""
+    """Insert a trade record into the database.
+
+    Args:
+        conn: Database connection
+        stock_code: Stock code
+        action: Trade action (BUY/SELL/HOLD)
+        confidence: Confidence level (0-100)
+        rationale: AI decision rationale
+        quantity: Number of shares
+        price: Trade price
+        pnl: Profit/loss
+        market: Market code
+        exchange_code: Exchange code
+        selection_context: Scanner selection data (RSI, volume_ratio, signal, score)
+    """
+    # Serialize selection context to JSON
+    context_json = json.dumps(selection_context) if selection_context else None
+
     conn.execute(
         """
         INSERT INTO trades (
             timestamp, stock_code, action, confidence, rationale,
-            quantity, price, pnl, market, exchange_code
+            quantity, price, pnl, market, exchange_code, selection_context
         )
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
         """,
         (
             datetime.now(UTC).isoformat(),
@@ -139,6 +181,7 @@ def log_trade(
             pnl,
             market,
             exchange_code,
+            context_json,
         ),
     )
     conn.commit()

src/main.py

@@ -15,6 +15,7 @@ from datetime import UTC, datetime
 from typing import Any
 
 from src.analysis.scanner import MarketScanner
+from src.analysis.smart_scanner import ScanCandidate, SmartVolatilityScanner
 from src.analysis.volatility import VolatilityAnalyzer
 from src.brain.gemini_client import GeminiClient
 from src.broker.kis_api import KISBroker
@@ -62,14 +63,6 @@ def safe_float(value: str | float | None, default: float = 0.0) -> float:
         return default
 
 
-# Target stock codes to monitor per market
-WATCHLISTS = {
-    "KR": ["005930", "000660", "035420"],  # Samsung, SK Hynix, NAVER
-    "US_NASDAQ": ["AAPL", "MSFT", "GOOGL"],  # Example US stocks
-    "US_NYSE": ["JPM", "BAC"],  # Example NYSE stocks
-    "JP": ["7203", "6758"],  # Toyota, Sony
-}
-
 TRADE_INTERVAL_SECONDS = 60
 SCAN_INTERVAL_SECONDS = 60  # Scan markets every 60 seconds
 MAX_CONNECTION_RETRIES = 3
@@ -78,15 +71,6 @@ MAX_CONNECTION_RETRIES = 3
 DAILY_TRADE_SESSIONS = 4  # Number of trading sessions per day
 TRADE_SESSION_INTERVAL_HOURS = 6  # Hours between sessions
 
-# Full stock universe per market (for scanning)
-# In production, this would be loaded from a database or API
-STOCK_UNIVERSE = {
-    "KR": ["005930", "000660", "035420", "051910", "005380", "005490"],
-    "US_NASDAQ": ["AAPL", "MSFT", "GOOGL", "AMZN", "NVDA", "TSLA"],
-    "US_NYSE": ["JPM", "BAC", "XOM", "JNJ", "V"],
-    "JP": ["7203", "6758", "9984", "6861"],
-}
-
 
 async def trading_cycle(
     broker: KISBroker,
@@ -100,6 +84,7 @@ async def trading_cycle(
     telegram: TelegramClient,
     market: MarketInfo,
     stock_code: str,
+    scan_candidates: dict[str, ScanCandidate],
 ) -> None:
     """Execute one trading cycle for a single stock."""
     cycle_start_time = asyncio.get_event_loop().time()
@@ -292,7 +277,17 @@ async def trading_cycle(
         except Exception as exc:
             logger.warning("Telegram notification failed: %s", exc)
 
-    # 6. Log trade
+    # 6. Log trade with selection context
+    selection_context = None
+    if stock_code in scan_candidates:
+        candidate = scan_candidates[stock_code]
+        selection_context = {
+            "rsi": candidate.rsi,
+            "volume_ratio": candidate.volume_ratio,
+            "signal": candidate.signal,
+            "score": candidate.score,
+        }
+
     log_trade(
         conn=db_conn,
         stock_code=stock_code,
@@ -301,6 +296,7 @@ async def trading_cycle(
         rationale=decision.rationale,
         market=market.code,
         exchange_code=market.exchange_code,
+        selection_context=selection_context,
     )
 
     # 7. Latency monitoring
@@ -336,6 +332,7 @@ async def run_daily_session(
     criticality_assessor: CriticalityAssessor,
     telegram: TelegramClient,
     settings: Settings,
+    smart_scanner: SmartVolatilityScanner | None = None,
 ) -> None:
     """Execute one daily trading session.
 
@@ -355,15 +352,21 @@ async def run_daily_session(
 
     # Process each open market
     for market in open_markets:
-        # Get watchlist for this market
-        watchlist = WATCHLISTS.get(market.code, [])
+        # Dynamic stock discovery via scanner (no static watchlists)
+        try:
+            candidates = await smart_scanner.scan()
+            watchlist = [c.stock_code for c in candidates] if candidates else []
+        except Exception as exc:
+            logger.error("Smart Scanner failed for %s: %s", market.name, exc)
+            watchlist = []
+
         if not watchlist:
-            logger.debug("No watchlist for market %s", market.code)
+            logger.info("No scanner candidates for market %s — skipping", market.code)
             continue
 
         logger.info("Processing market: %s (%d stocks)", market.name, len(watchlist))
 
-        # Collect market data for all stocks in the watchlist
+        # Collect market data for all stocks from scanner
         stocks_data = []
         for stock_code in watchlist:
             try:
@@ -579,25 +582,10 @@ async def run(settings: Settings) -> None:
     command_handler = TelegramCommandHandler(telegram)
 
     # Register basic commands
-    async def handle_start() -> None:
-        """Handle /start command."""
-        message = (
-            "<b>🤖 The Ouroboros Trading Bot</b>\n\n"
-            "AI-powered global stock trading agent with real-time notifications.\n\n"
-            "<b>Available commands:</b>\n"
-            "/help - Show this help message\n"
-            "/status - Current trading status\n"
-            "/positions - View holdings\n"
-            "/stop - Pause trading\n"
-            "/resume - Resume trading"
-        )
-        await telegram.send_message(message)
-
     async def handle_help() -> None:
         """Handle /help command."""
         message = (
             "<b>📖 Available Commands</b>\n\n"
-            "/start - Welcome message\n"
             "/help - Show available commands\n"
             "/status - Trading status (mode, markets, P&L)\n"
             "/positions - Current holdings\n"
@@ -639,11 +627,21 @@ async def run(settings: Settings) -> None:
             # Get trading status
             trading_status = "Active" if pause_trading.is_set() else "Paused"
 
-            # Get current P&L from risk manager
+            # Calculate P&L from balance data
             try:
                 balance = await broker.get_balance()
-                current_pnl = risk.calculate_pnl(balance)
-                pnl_str = f"{current_pnl:+.2f}%"
+                output2 = balance.get("output2", [{}])
+                if output2:
+                    total_eval = safe_float(output2[0].get("tot_evlu_amt", "0"))
+                    purchase_total = safe_float(output2[0].get("pchs_amt_smtl_amt", "0"))
+                    current_pnl = (
+                        ((total_eval - purchase_total) / purchase_total * 100)
+                        if purchase_total > 0
+                        else 0.0
+                    )
+                    pnl_str = f"{current_pnl:+.2f}%"
+                else:
+                    pnl_str = "N/A"
             except Exception as exc:
                 logger.warning("Failed to get P&L: %s", exc)
                 pnl_str = "N/A"
@@ -657,7 +655,7 @@ async def run(settings: Settings) -> None:
                 f"<b>Markets:</b> {markets_str}\n"
                 f"<b>Trading:</b> {trading_status}\n\n"
                 f"<b>Current P&L:</b> {pnl_str}\n"
-                f"<b>Circuit Breaker:</b> {risk.circuit_breaker_threshold:.1f}%"
+                f"<b>Circuit Breaker:</b> {risk._cb_threshold:.1f}%"
             )
             await telegram.send_message(message)
 
@@ -668,52 +666,40 @@ async def run(settings: Settings) -> None:
             )
 
     async def handle_positions() -> None:
-        """Handle /positions command - show current holdings."""
+        """Handle /positions command - show account summary."""
         try:
             # Get account balance
             balance = await broker.get_balance()
+            output2 = balance.get("output2", [{}])
 
-            # Check if there are any positions
-            if not balance.stocks:
+            if not output2:
                 await telegram.send_message(
-                    "<b>💼 Current Holdings</b>\n\n"
-                    "No positions currently held."
+                    "<b>💼 Account Summary</b>\n\n"
+                    "No balance information available."
                 )
                 return
 
-            # Group positions by market (domestic vs overseas)
-            domestic_positions = []
-            overseas_positions = []
+            # Extract account-level data
+            total_eval = safe_float(output2[0].get("tot_evlu_amt", "0"))
+            total_cash = safe_float(output2[0].get("dnca_tot_amt", "0"))
+            purchase_total = safe_float(output2[0].get("pchs_amt_smtl_amt", "0"))
 
-            for stock in balance.stocks:
-                position_str = (
-                    f"• {stock.code}: {stock.quantity} shares @ "
-                    f"{stock.avg_price:,.0f}"
-                )
-
-                # Simple heuristic: if code is 6 digits, it's domestic (Korea)
-                if len(stock.code) == 6 and stock.code.isdigit():
-                    domestic_positions.append(position_str)
-                else:
-                    overseas_positions.append(position_str)
-
-            # Build message
-            message_parts = ["<b>💼 Current Holdings</b>\n"]
-
-            if domestic_positions:
-                message_parts.append("\n🇰🇷 <b>Korea</b>")
-                message_parts.extend(domestic_positions)
-
-            if overseas_positions:
-                message_parts.append("\n🇺🇸 <b>Overseas</b>")
-                message_parts.extend(overseas_positions)
-
-            # Add total cash
-            message_parts.append(
-                f"\n<b>Cash:</b> ₩{balance.total_cash:,.0f}"
+            # Calculate P&L
+            pnl_pct = (
+                ((total_eval - purchase_total) / purchase_total * 100)
+                if purchase_total > 0
+                else 0.0
             )
+            pnl_sign = "+" if pnl_pct >= 0 else ""
 
-            message = "\n".join(message_parts)
+            message = (
+                "<b>💼 Account Summary</b>\n\n"
+                f"<b>Total Evaluation:</b> ₩{total_eval:,.0f}\n"
+                f"<b>Available Cash:</b> ₩{total_cash:,.0f}\n"
+                f"<b>Purchase Total:</b> ₩{purchase_total:,.0f}\n"
+                f"<b>P&L:</b> {pnl_sign}{pnl_pct:.2f}%\n\n"
+                "<i>Note: Individual position details require API enhancement</i>"
+            )
             await telegram.send_message(message)
 
         except Exception as exc:
@@ -722,7 +708,6 @@ async def run(settings: Settings) -> None:
                 "<b>⚠️ Error</b>\n\nFailed to retrieve positions."
             )
 
-    command_handler.register_command("start", handle_start)
     command_handler.register_command("help", handle_help)
     command_handler.register_command("stop", handle_stop)
     command_handler.register_command("resume", handle_resume)
@@ -740,6 +725,19 @@ async def run(settings: Settings) -> None:
         max_concurrent_scans=1,  # Fully serialized to avoid EGW00201
     )
 
+    # Initialize smart scanner (Python-first, AI-last pipeline)
+    smart_scanner = SmartVolatilityScanner(
+        broker=broker,
+        volatility_analyzer=volatility_analyzer,
+        settings=settings,
+    )
+
+    # Track scan candidates for selection context logging
+    scan_candidates: dict[str, ScanCandidate] = {}  # stock_code -> candidate
+
+    # Active stocks per market (dynamically discovered by scanner)
+    active_stocks: dict[str, list[str]] = {}  # market_code -> [stock_codes]
+
     # Initialize latency control system
     criticality_assessor = CriticalityAssessor(
         critical_pnl_threshold=-2.5,  # Near circuit breaker at -3.0%
@@ -812,6 +810,7 @@ async def run(settings: Settings) -> None:
                         criticality_assessor,
                         telegram,
                         settings,
+                        smart_scanner=smart_scanner,
                     )
                 except CircuitBreakerTripped:
                     logger.critical("Circuit breaker tripped — shutting down")
@@ -885,49 +884,52 @@ async def run(settings: Settings) -> None:
                             logger.warning("Market open notification failed: %s", exc)
                         _market_states[market.code] = True
 
-                    # Volatility Hunter: Scan market periodically to update watchlist
+                    # Smart Scanner: dynamic stock discovery (no static watchlists)
                     now_timestamp = asyncio.get_event_loop().time()
                     last_scan = last_scan_time.get(market.code, 0.0)
                     if now_timestamp - last_scan >= SCAN_INTERVAL_SECONDS:
                         try:
-                            # Scan all stocks in the universe
-                            stock_universe = STOCK_UNIVERSE.get(market.code, [])
-                            if stock_universe:
-                                logger.info("Volatility Hunter: Scanning %s market", market.name)
-                                scan_result = await market_scanner.scan_market(
-                                    market, stock_universe
+                            logger.info("Smart Scanner: Scanning %s market", market.name)
+
+                            candidates = await smart_scanner.scan()
+
+                            if candidates:
+                                # Use scanner results directly as trading candidates
+                                active_stocks[market.code] = smart_scanner.get_stock_codes(
+                                    candidates
                                 )
 
-                                # Update watchlist with top movers
-                                current_watchlist = WATCHLISTS.get(market.code, [])
-                                updated_watchlist = market_scanner.get_updated_watchlist(
-                                    current_watchlist,
-                                    scan_result,
-                                    max_replacements=2,
-                                )
-                                WATCHLISTS[market.code] = updated_watchlist
+                                # Store candidates for selection context logging
+                                for candidate in candidates:
+                                    scan_candidates[candidate.stock_code] = candidate
 
                                 logger.info(
-                                    "Volatility Hunter: Watchlist updated for %s (%d top movers, %d breakouts)",
+                                    "Smart Scanner: Found %d candidates for %s: %s",
+                                    len(candidates),
                                     market.name,
-                                    len(scan_result.top_movers),
-                                    len(scan_result.breakouts),
+                                    [f"{c.stock_code}(RSI={c.rsi:.0f})" for c in candidates],
                                 )
+                            else:
+                                logger.info(
+                                    "Smart Scanner: No candidates for %s — no trades", market.name
+                                )
+                                active_stocks[market.code] = []
 
                             last_scan_time[market.code] = now_timestamp
-                        except Exception as exc:
-                            logger.error("Volatility Hunter scan failed for %s: %s", market.name, exc)
 
-                    # Get watchlist for this market
-                    watchlist = WATCHLISTS.get(market.code, [])
-                    if not watchlist:
-                        logger.debug("No watchlist for market %s", market.code)
+                        except Exception as exc:
+                            logger.error("Smart Scanner failed for %s: %s", market.name, exc)
+
+                    # Get active stocks from scanner (dynamic, no static fallback)
+                    stock_codes = active_stocks.get(market.code, [])
+                    if not stock_codes:
+                        logger.debug("No active stocks for market %s", market.code)
                         continue
 
-                    logger.info("Processing market: %s (%d stocks)", market.name, len(watchlist))
+                    logger.info("Processing market: %s (%d stocks)", market.name, len(stock_codes))
 
-                    # Process each stock in the watchlist
-                    for stock_code in watchlist:
+                    # Process each stock from scanner results
+                    for stock_code in stock_codes:
                         if shutdown.is_set():
                             break
 
@@ -946,6 +948,7 @@ async def run(settings: Settings) -> None:
                                     telegram,
                                     market,
                                     stock_code,
+                                    scan_candidates,
                                 )
                                 break  # Success — exit retry loop
                             except CircuitBreakerTripped as exc:

src/notifications/telegram_client.py

@@ -492,7 +492,8 @@ class TelegramCommandHandler:
             if not command_parts:
                 return
 
-            command_name = command_parts[0]
+            # Remove @botname suffix if present (for group chats)
+            command_name = command_parts[0].split("@")[0]
 
             # Execute handler
             handler = self._commands.get(command_name)

src/strategy/models.py

@@ -0,0 +1,164 @@
+"""Pydantic models for pre-market scenario planning.
+
+Defines the data contracts for the proactive strategy system:
+- AI generates DayPlaybook before market open (structured JSON scenarios)
+- Local ScenarioEngine matches conditions during market hours (no API calls)
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, date, datetime
+from enum import Enum
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class ScenarioAction(str, Enum):
+    """Actions that can be taken by scenarios."""
+
+    BUY = "BUY"
+    SELL = "SELL"
+    HOLD = "HOLD"
+    REDUCE_ALL = "REDUCE_ALL"
+
+
+class MarketOutlook(str, Enum):
+    """AI's assessment of market direction."""
+
+    BULLISH = "bullish"
+    NEUTRAL_TO_BULLISH = "neutral_to_bullish"
+    NEUTRAL = "neutral"
+    NEUTRAL_TO_BEARISH = "neutral_to_bearish"
+    BEARISH = "bearish"
+
+
+class PlaybookStatus(str, Enum):
+    """Lifecycle status of a playbook."""
+
+    PENDING = "pending"
+    READY = "ready"
+    FAILED = "failed"
+    EXPIRED = "expired"
+
+
+class StockCondition(BaseModel):
+    """Condition fields for scenario matching (all optional, AND-combined).
+
+    The ScenarioEngine evaluates all non-None fields as AND conditions.
+    A condition matches only if ALL specified fields are satisfied.
+    """
+
+    rsi_below: float | None = None
+    rsi_above: float | None = None
+    volume_ratio_above: float | None = None
+    volume_ratio_below: float | None = None
+    price_above: float | None = None
+    price_below: float | None = None
+    price_change_pct_above: float | None = None
+    price_change_pct_below: float | None = None
+
+    def has_any_condition(self) -> bool:
+        """Check if at least one condition field is set."""
+        return any(
+            v is not None
+            for v in (
+                self.rsi_below,
+                self.rsi_above,
+                self.volume_ratio_above,
+                self.volume_ratio_below,
+                self.price_above,
+                self.price_below,
+                self.price_change_pct_above,
+                self.price_change_pct_below,
+            )
+        )
+
+
+class StockScenario(BaseModel):
+    """A single condition-action rule for one stock."""
+
+    condition: StockCondition
+    action: ScenarioAction
+    confidence: int = Field(ge=0, le=100)
+    allocation_pct: float = Field(ge=0, le=100, default=10.0)
+    stop_loss_pct: float = Field(le=0, default=-2.0)
+    take_profit_pct: float = Field(ge=0, default=3.0)
+    rationale: str = ""
+
+
+class StockPlaybook(BaseModel):
+    """All scenarios for a single stock (ordered by priority)."""
+
+    stock_code: str
+    stock_name: str = ""
+    scenarios: list[StockScenario] = Field(min_length=1)
+
+
+class GlobalRule(BaseModel):
+    """Portfolio-level rule (checked before stock-level scenarios)."""
+
+    condition: str  # e.g. "portfolio_pnl_pct < -2.0"
+    action: ScenarioAction
+    rationale: str = ""
+
+
+class CrossMarketContext(BaseModel):
+    """Summary of another market's state for cross-market awareness."""
+
+    market: str  # e.g. "US" or "KR"
+    date: str
+    total_pnl: float = 0.0
+    win_rate: float = 0.0
+    index_change_pct: float = 0.0  # e.g. KOSPI or S&P500 change
+    key_events: list[str] = Field(default_factory=list)
+    lessons: list[str] = Field(default_factory=list)
+
+
+class DayPlaybook(BaseModel):
+    """Complete playbook for a single trading day in a single market.
+
+    Generated by PreMarketPlanner (1 Gemini call per market per day).
+    Consumed by ScenarioEngine during market hours (0 API calls).
+    """
+
+    date: date
+    market: str  # "KR" or "US"
+    market_outlook: MarketOutlook = MarketOutlook.NEUTRAL
+    generated_at: str = ""  # ISO timestamp
+    gemini_model: str = ""
+    token_count: int = 0
+    global_rules: list[GlobalRule] = Field(default_factory=list)
+    stock_playbooks: list[StockPlaybook] = Field(default_factory=list)
+    default_action: ScenarioAction = ScenarioAction.HOLD
+    context_summary: dict = Field(default_factory=dict)
+    cross_market: CrossMarketContext | None = None
+
+    @field_validator("stock_playbooks")
+    @classmethod
+    def validate_unique_stocks(cls, v: list[StockPlaybook]) -> list[StockPlaybook]:
+        codes = [pb.stock_code for pb in v]
+        if len(codes) != len(set(codes)):
+            raise ValueError("Duplicate stock codes in playbook")
+        return v
+
+    def get_stock_playbook(self, stock_code: str) -> StockPlaybook | None:
+        """Find the playbook for a specific stock."""
+        for pb in self.stock_playbooks:
+            if pb.stock_code == stock_code:
+                return pb
+        return None
+
+    @property
+    def scenario_count(self) -> int:
+        """Total number of scenarios across all stocks."""
+        return sum(len(pb.scenarios) for pb in self.stock_playbooks)
+
+    @property
+    def stock_count(self) -> int:
+        """Number of stocks with scenarios."""
+        return len(self.stock_playbooks)
+
+    def model_post_init(self, __context: object) -> None:
+        """Set generated_at if not provided."""
+        if not self.generated_at:
+            self.generated_at = datetime.now(UTC).isoformat()

src/strategy/playbook_store.py

@@ -0,0 +1,184 @@
+"""Playbook persistence layer — CRUD for DayPlaybook in SQLite.
+
+Stores and retrieves market-specific daily playbooks with JSON serialization.
+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
+
+from src.strategy.models import DayPlaybook, PlaybookStatus
+
+logger = logging.getLogger(__name__)
+
+
+class PlaybookStore:
+    """CRUD operations for DayPlaybook persistence."""
+
+    def __init__(self, conn: sqlite3.Connection) -> None:
+        self._conn = conn
+
+    def save(self, playbook: DayPlaybook) -> int:
+        """Save or replace a playbook for a given date+market.
+
+        Uses INSERT OR REPLACE to enforce UNIQUE(date, market).
+
+        Returns:
+            The row id of the inserted/replaced record.
+        """
+        playbook_json = playbook.model_dump_json()
+        cursor = self._conn.execute(
+            """
+            INSERT OR REPLACE INTO playbooks
+                (date, market, status, playbook_json, generated_at,
+                 token_count, scenario_count, match_count)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                playbook.date.isoformat(),
+                playbook.market,
+                PlaybookStatus.READY.value,
+                playbook_json,
+                playbook.generated_at,
+                playbook.token_count,
+                playbook.scenario_count,
+                0,
+            ),
+        )
+        self._conn.commit()
+        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,
+        )
+        return row_id
+
+    def load(self, target_date: date, market: str) -> DayPlaybook | None:
+        """Load a playbook for a specific date and market.
+
+        Returns:
+            DayPlaybook if found, None otherwise.
+        """
+        row = self._conn.execute(
+            "SELECT playbook_json FROM playbooks WHERE date = ? AND market = ?",
+            (target_date.isoformat(), market),
+        ).fetchone()
+        if row is None:
+            return None
+        return DayPlaybook.model_validate_json(row[0])
+
+    def get_status(self, target_date: date, market: str) -> PlaybookStatus | None:
+        """Get the status of a playbook without deserializing the full JSON."""
+        row = self._conn.execute(
+            "SELECT status FROM playbooks WHERE date = ? AND market = ?",
+            (target_date.isoformat(), market),
+        ).fetchone()
+        if row is None:
+            return None
+        return PlaybookStatus(row[0])
+
+    def update_status(self, target_date: date, market: str, status: PlaybookStatus) -> bool:
+        """Update the status of a playbook.
+
+        Returns:
+            True if a row was updated, False if not found.
+        """
+        cursor = self._conn.execute(
+            "UPDATE playbooks SET status = ? WHERE date = ? AND market = ?",
+            (status.value, target_date.isoformat(), market),
+        )
+        self._conn.commit()
+        return cursor.rowcount > 0
+
+    def increment_match_count(self, target_date: date, market: str) -> bool:
+        """Increment the match_count for tracking scenario hits during the day.
+
+        Returns:
+            True if a row was updated, False if not found.
+        """
+        cursor = self._conn.execute(
+            "UPDATE playbooks SET match_count = match_count + 1 WHERE date = ? AND market = ?",
+            (target_date.isoformat(), market),
+        )
+        self._conn.commit()
+        return cursor.rowcount > 0
+
+    def get_stats(self, target_date: date, market: str) -> dict | None:
+        """Get playbook stats without full deserialization.
+
+        Returns:
+            Dict with status, token_count, scenario_count, match_count, or None.
+        """
+        row = self._conn.execute(
+            """
+            SELECT status, token_count, scenario_count, match_count, generated_at
+            FROM playbooks WHERE date = ? AND market = ?
+            """,
+            (target_date.isoformat(), market),
+        ).fetchone()
+        if row is None:
+            return None
+        return {
+            "status": row[0],
+            "token_count": row[1],
+            "scenario_count": row[2],
+            "match_count": row[3],
+            "generated_at": row[4],
+        }
+
+    def list_recent(self, market: str | None = None, limit: int = 7) -> list[dict]:
+        """List recent playbooks with summary info.
+
+        Args:
+            market: Filter by market code. None for all markets.
+            limit: Max number of results.
+
+        Returns:
+            List of dicts with date, market, status, scenario_count, match_count.
+        """
+        if market is not None:
+            rows = self._conn.execute(
+                """
+                SELECT date, market, status, scenario_count, match_count
+                FROM playbooks WHERE market = ?
+                ORDER BY date DESC LIMIT ?
+                """,
+                (market, limit),
+            ).fetchall()
+        else:
+            rows = self._conn.execute(
+                """
+                SELECT date, market, status, scenario_count, match_count
+                FROM playbooks
+                ORDER BY date DESC LIMIT ?
+                """,
+                (limit,),
+            ).fetchall()
+        return [
+            {
+                "date": row[0],
+                "market": row[1],
+                "status": row[2],
+                "scenario_count": row[3],
+                "match_count": row[4],
+            }
+            for row in rows
+        ]
+
+    def delete(self, target_date: date, market: str) -> bool:
+        """Delete a playbook.
+
+        Returns:
+            True if a row was deleted, False if not found.
+        """
+        cursor = self._conn.execute(
+            "DELETE FROM playbooks WHERE date = ? AND market = ?",
+            (target_date.isoformat(), market),
+        )
+        self._conn.commit()
+        return cursor.rowcount > 0

src/strategy/scenario_engine.py

@@ -0,0 +1,270 @@
+"""Local scenario engine for playbook execution.
+
+Matches real-time market conditions against pre-defined scenarios
+without any API calls. Designed for sub-100ms execution.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+from src.strategy.models import (
+    DayPlaybook,
+    GlobalRule,
+    ScenarioAction,
+    StockCondition,
+    StockScenario,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ScenarioMatch:
+    """Result of matching market conditions against scenarios."""
+
+    stock_code: str
+    matched_scenario: StockScenario | None
+    action: ScenarioAction
+    confidence: int
+    rationale: str
+    global_rule_triggered: GlobalRule | None = None
+    match_details: dict[str, Any] = field(default_factory=dict)
+
+
+class ScenarioEngine:
+    """Evaluates playbook scenarios against real-time market data.
+
+    No API calls — pure Python condition matching.
+
+    Expected market_data keys: "rsi", "volume_ratio", "current_price", "price_change_pct".
+    Callers must normalize data source keys to match this contract.
+    """
+
+    def __init__(self) -> None:
+        self._warned_keys: set[str] = set()
+
+    @staticmethod
+    def _safe_float(value: Any) -> float | None:
+        """Safely cast a value to float. Returns None on failure."""
+        if value is None:
+            return None
+        try:
+            return float(value)
+        except (ValueError, TypeError):
+            return None
+
+    def _warn_missing_key(self, key: str) -> None:
+        """Log a missing-key warning once per key per engine instance."""
+        if key not in self._warned_keys:
+            self._warned_keys.add(key)
+            logger.warning("Condition requires '%s' but key missing from market_data", key)
+
+    def evaluate(
+        self,
+        playbook: DayPlaybook,
+        stock_code: str,
+        market_data: dict[str, Any],
+        portfolio_data: dict[str, Any],
+    ) -> ScenarioMatch:
+        """Match market conditions to scenarios and return a decision.
+
+        Algorithm:
+        1. Check global rules first (portfolio-level circuit breakers)
+        2. Find the StockPlaybook for the given stock_code
+        3. Iterate scenarios in order (first match wins)
+        4. If no match, return playbook.default_action (HOLD)
+
+        Args:
+            playbook: Today's DayPlaybook for this market
+            stock_code: Stock ticker to evaluate
+            market_data: Real-time market data (price, rsi, volume_ratio, etc.)
+            portfolio_data: Portfolio state (pnl_pct, total_cash, etc.)
+
+        Returns:
+            ScenarioMatch with the decision
+        """
+        # 1. Check global rules
+        triggered_rule = self.check_global_rules(playbook, portfolio_data)
+        if triggered_rule is not None:
+            logger.info(
+                "Global rule triggered for %s: %s -> %s",
+                stock_code,
+                triggered_rule.condition,
+                triggered_rule.action.value,
+            )
+            return ScenarioMatch(
+                stock_code=stock_code,
+                matched_scenario=None,
+                action=triggered_rule.action,
+                confidence=100,
+                rationale=f"Global rule: {triggered_rule.rationale or triggered_rule.condition}",
+                global_rule_triggered=triggered_rule,
+            )
+
+        # 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)
+            return ScenarioMatch(
+                stock_code=stock_code,
+                matched_scenario=None,
+                action=playbook.default_action,
+                confidence=0,
+                rationale=f"No scenarios defined for {stock_code}",
+            )
+
+        # 3. Iterate scenarios (first match wins)
+        for scenario in stock_pb.scenarios:
+            if self.evaluate_condition(scenario.condition, market_data):
+                logger.info(
+                    "Scenario matched for %s: %s (confidence=%d)",
+                    stock_code,
+                    scenario.action.value,
+                    scenario.confidence,
+                )
+                return ScenarioMatch(
+                    stock_code=stock_code,
+                    matched_scenario=scenario,
+                    action=scenario.action,
+                    confidence=scenario.confidence,
+                    rationale=scenario.rationale,
+                    match_details=self._build_match_details(scenario.condition, market_data),
+                )
+
+        # 4. No match — 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,
+            action=playbook.default_action,
+            confidence=0,
+            rationale="No scenario conditions met — holding position",
+        )
+
+    def check_global_rules(
+        self,
+        playbook: DayPlaybook,
+        portfolio_data: dict[str, Any],
+    ) -> GlobalRule | None:
+        """Check portfolio-level rules. Returns first triggered rule or None."""
+        for rule in playbook.global_rules:
+            if self._evaluate_global_condition(rule.condition, portfolio_data):
+                return rule
+        return None
+
+    def evaluate_condition(
+        self,
+        condition: StockCondition,
+        market_data: dict[str, Any],
+    ) -> bool:
+        """Evaluate all non-None fields in condition as AND.
+
+        Returns True only if ALL specified conditions are met.
+        Empty condition (no fields set) returns False for safety.
+        """
+        if not condition.has_any_condition():
+            return False
+
+        checks: list[bool] = []
+
+        rsi = self._safe_float(market_data.get("rsi"))
+        if condition.rsi_below is not None or condition.rsi_above is not None:
+            if "rsi" not in market_data:
+                self._warn_missing_key("rsi")
+        if condition.rsi_below is not None:
+            checks.append(rsi is not None and rsi < condition.rsi_below)
+        if condition.rsi_above is not None:
+            checks.append(rsi is not None and rsi > condition.rsi_above)
+
+        volume_ratio = self._safe_float(market_data.get("volume_ratio"))
+        if condition.volume_ratio_above is not None or condition.volume_ratio_below is not None:
+            if "volume_ratio" not in market_data:
+                self._warn_missing_key("volume_ratio")
+        if condition.volume_ratio_above is not None:
+            checks.append(volume_ratio is not None and volume_ratio > condition.volume_ratio_above)
+        if condition.volume_ratio_below is not None:
+            checks.append(volume_ratio is not None and volume_ratio < condition.volume_ratio_below)
+
+        price = self._safe_float(market_data.get("current_price"))
+        if condition.price_above is not None or condition.price_below is not None:
+            if "current_price" not in market_data:
+                self._warn_missing_key("current_price")
+        if condition.price_above is not None:
+            checks.append(price is not None and price > condition.price_above)
+        if condition.price_below is not None:
+            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 "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)
+        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)
+
+        return len(checks) > 0 and all(checks)
+
+    def _evaluate_global_condition(
+        self,
+        condition_str: str,
+        portfolio_data: dict[str, Any],
+    ) -> bool:
+        """Evaluate a simple global condition string against portfolio data.
+
+        Supports: "field < value", "field > value", "field <= value", "field >= value"
+        """
+        parts = condition_str.strip().split()
+        if len(parts) != 3:
+            logger.warning("Invalid global condition format: %s", condition_str)
+            return False
+
+        field_name, operator, value_str = parts
+        try:
+            threshold = float(value_str)
+        except ValueError:
+            logger.warning("Invalid threshold in condition: %s", condition_str)
+            return False
+
+        actual = portfolio_data.get(field_name)
+        if actual is None:
+            return False
+
+        try:
+            actual_val = float(actual)
+        except (ValueError, TypeError):
+            return False
+
+        if operator == "<":
+            return actual_val < threshold
+        elif operator == ">":
+            return actual_val > threshold
+        elif operator == "<=":
+            return actual_val <= threshold
+        elif operator == ">=":
+            return actual_val >= threshold
+        else:
+            logger.warning("Unknown operator in condition: %s", operator)
+            return False
+
+    def _build_match_details(
+        self,
+        condition: StockCondition,
+        market_data: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Build a summary of which conditions matched and their normalized values."""
+        details: dict[str, Any] = {}
+
+        if condition.rsi_below is not None or condition.rsi_above is not None:
+            details["rsi"] = self._safe_float(market_data.get("rsi"))
+        if condition.volume_ratio_above is not None or condition.volume_ratio_below is not None:
+            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:
+            details["price_change_pct"] = self._safe_float(market_data.get("price_change_pct"))
+
+        return details

tests/test_main.py

@@ -174,6 +174,7 @@ class TestTradingCycleTelegramIntegration:
                 telegram=mock_telegram,
                 market=mock_market,
                 stock_code="005930",
+                scan_candidates={},
             )
 
         # Verify notification was sent
@@ -216,6 +217,7 @@ class TestTradingCycleTelegramIntegration:
                 telegram=mock_telegram,
                 market=mock_market,
                 stock_code="005930",
+                scan_candidates={},
             )
 
         # Verify notification was attempted
@@ -257,6 +259,7 @@ class TestTradingCycleTelegramIntegration:
                     telegram=mock_telegram,
                     market=mock_market,
                     stock_code="005930",
+                    scan_candidates={},
                 )
 
         # Verify notification was sent
@@ -305,6 +308,7 @@ class TestTradingCycleTelegramIntegration:
                     telegram=mock_telegram,
                     market=mock_market,
                     stock_code="005930",
+                    scan_candidates={},
                 )
 
         # Verify notification was attempted
@@ -345,6 +349,7 @@ class TestTradingCycleTelegramIntegration:
                 telegram=mock_telegram,
                 market=mock_market,
                 stock_code="005930",
+                scan_candidates={},
             )
 
         # Verify no trade notification sent
@@ -543,6 +548,7 @@ class TestOverseasBalanceParsing:
                 telegram=mock_telegram,
                 market=mock_overseas_market,
                 stock_code="AAPL",
+                scan_candidates={},
             )
 
         # Verify balance API was called
@@ -577,6 +583,7 @@ class TestOverseasBalanceParsing:
                 telegram=mock_telegram,
                 market=mock_overseas_market,
                 stock_code="AAPL",
+                scan_candidates={},
             )
 
         # Verify balance API was called
@@ -611,6 +618,7 @@ class TestOverseasBalanceParsing:
                 telegram=mock_telegram,
                 market=mock_overseas_market,
                 stock_code="AAPL",
+                scan_candidates={},
             )
 
         # Verify balance API was called
@@ -645,6 +653,7 @@ class TestOverseasBalanceParsing:
                 telegram=mock_telegram,
                 market=mock_overseas_market,
                 stock_code="AAPL",
+                scan_candidates={},
             )
 
         # Verify price API was called

tests/test_playbook_store.py

@@ -0,0 +1,289 @@
+"""Tests for playbook persistence (PlaybookStore + DB schema)."""
+
+from __future__ import annotations
+
+from datetime import date
+
+import pytest
+
+from src.db import init_db
+from src.strategy.models import (
+    DayPlaybook,
+    GlobalRule,
+    MarketOutlook,
+    PlaybookStatus,
+    ScenarioAction,
+    StockCondition,
+    StockPlaybook,
+    StockScenario,
+)
+from src.strategy.playbook_store import PlaybookStore
+
+
+@pytest.fixture
+def conn():
+    """Create an in-memory DB with schema."""
+    connection = init_db(":memory:")
+    yield connection
+    connection.close()
+
+
+@pytest.fixture
+def store(conn) -> PlaybookStore:
+    return PlaybookStore(conn)
+
+
+def _make_playbook(
+    target_date: date = date(2026, 2, 8),
+    market: str = "KR",
+    outlook: MarketOutlook = MarketOutlook.NEUTRAL,
+    stock_codes: list[str] | None = None,
+) -> DayPlaybook:
+    """Create a test playbook with sensible defaults."""
+    if stock_codes is None:
+        stock_codes = ["005930"]
+    return DayPlaybook(
+        date=target_date,
+        market=market,
+        market_outlook=outlook,
+        token_count=150,
+        stock_playbooks=[
+            StockPlaybook(
+                stock_code=code,
+                scenarios=[
+                    StockScenario(
+                        condition=StockCondition(rsi_below=30.0),
+                        action=ScenarioAction.BUY,
+                        confidence=85,
+                        rationale=f"Oversold bounce for {code}",
+                    ),
+                ],
+            )
+            for code in stock_codes
+        ],
+        global_rules=[
+            GlobalRule(
+                condition="portfolio_pnl_pct < -2.0",
+                action=ScenarioAction.REDUCE_ALL,
+                rationale="Near circuit breaker",
+            ),
+        ],
+    )
+
+
+# ---------------------------------------------------------------------------
+# Schema
+# ---------------------------------------------------------------------------
+
+
+class TestSchema:
+    def test_playbooks_table_exists(self, conn) -> None:
+        row = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name='playbooks'"
+        ).fetchone()
+        assert row is not None
+
+    def test_unique_constraint(self, store: PlaybookStore) -> None:
+        pb = _make_playbook()
+        store.save(pb)
+        # Saving again for same date+market should replace, not error
+        pb2 = _make_playbook(stock_codes=["005930", "000660"])
+        store.save(pb2)
+        loaded = store.load(date(2026, 2, 8), "KR")
+        assert loaded is not None
+        assert loaded.stock_count == 2
+
+
+# ---------------------------------------------------------------------------
+# Save / Load
+# ---------------------------------------------------------------------------
+
+
+class TestSaveLoad:
+    def test_save_and_load(self, store: PlaybookStore) -> None:
+        pb = _make_playbook()
+        row_id = store.save(pb)
+        assert row_id > 0
+
+        loaded = store.load(date(2026, 2, 8), "KR")
+        assert loaded is not None
+        assert loaded.date == date(2026, 2, 8)
+        assert loaded.market == "KR"
+        assert loaded.stock_count == 1
+        assert loaded.scenario_count == 1
+
+    def test_load_not_found(self, store: PlaybookStore) -> None:
+        result = store.load(date(2026, 1, 1), "KR")
+        assert result is None
+
+    def test_save_preserves_all_fields(self, store: PlaybookStore) -> None:
+        pb = _make_playbook(
+            outlook=MarketOutlook.BULLISH,
+            stock_codes=["005930", "AAPL"],
+        )
+        store.save(pb)
+        loaded = store.load(date(2026, 2, 8), "KR")
+        assert loaded is not None
+        assert loaded.market_outlook == MarketOutlook.BULLISH
+        assert loaded.stock_count == 2
+        assert loaded.global_rules[0].action == ScenarioAction.REDUCE_ALL
+        assert loaded.token_count == 150
+
+    def test_save_different_markets(self, store: PlaybookStore) -> None:
+        kr = _make_playbook(market="KR")
+        us = _make_playbook(market="US", stock_codes=["AAPL"])
+        store.save(kr)
+        store.save(us)
+
+        kr_loaded = store.load(date(2026, 2, 8), "KR")
+        us_loaded = store.load(date(2026, 2, 8), "US")
+        assert kr_loaded is not None
+        assert us_loaded is not None
+        assert kr_loaded.market == "KR"
+        assert us_loaded.market == "US"
+        assert kr_loaded.stock_playbooks[0].stock_code == "005930"
+        assert us_loaded.stock_playbooks[0].stock_code == "AAPL"
+
+    def test_save_different_dates(self, store: PlaybookStore) -> None:
+        d1 = _make_playbook(target_date=date(2026, 2, 7))
+        d2 = _make_playbook(target_date=date(2026, 2, 8))
+        store.save(d1)
+        store.save(d2)
+
+        assert store.load(date(2026, 2, 7), "KR") is not None
+        assert store.load(date(2026, 2, 8), "KR") is not None
+
+    def test_replace_updates_data(self, store: PlaybookStore) -> None:
+        pb1 = _make_playbook(outlook=MarketOutlook.BEARISH)
+        store.save(pb1)
+
+        pb2 = _make_playbook(outlook=MarketOutlook.BULLISH)
+        store.save(pb2)
+
+        loaded = store.load(date(2026, 2, 8), "KR")
+        assert loaded is not None
+        assert loaded.market_outlook == MarketOutlook.BULLISH
+
+
+# ---------------------------------------------------------------------------
+# Status
+# ---------------------------------------------------------------------------
+
+
+class TestStatus:
+    def test_get_status(self, store: PlaybookStore) -> None:
+        store.save(_make_playbook())
+        status = store.get_status(date(2026, 2, 8), "KR")
+        assert status == PlaybookStatus.READY
+
+    def test_get_status_not_found(self, store: PlaybookStore) -> None:
+        assert store.get_status(date(2026, 1, 1), "KR") is None
+
+    def test_update_status(self, store: PlaybookStore) -> None:
+        store.save(_make_playbook())
+        updated = store.update_status(date(2026, 2, 8), "KR", PlaybookStatus.EXPIRED)
+        assert updated is True
+
+        status = store.get_status(date(2026, 2, 8), "KR")
+        assert status == PlaybookStatus.EXPIRED
+
+    def test_update_status_not_found(self, store: PlaybookStore) -> None:
+        updated = store.update_status(date(2026, 1, 1), "KR", PlaybookStatus.FAILED)
+        assert updated is False
+
+
+# ---------------------------------------------------------------------------
+# Match count
+# ---------------------------------------------------------------------------
+
+
+class TestMatchCount:
+    def test_increment_match_count(self, store: PlaybookStore) -> None:
+        store.save(_make_playbook())
+        store.increment_match_count(date(2026, 2, 8), "KR")
+        store.increment_match_count(date(2026, 2, 8), "KR")
+
+        stats = store.get_stats(date(2026, 2, 8), "KR")
+        assert stats is not None
+        assert stats["match_count"] == 2
+
+    def test_increment_not_found(self, store: PlaybookStore) -> None:
+        result = store.increment_match_count(date(2026, 1, 1), "KR")
+        assert result is False
+
+
+# ---------------------------------------------------------------------------
+# Stats
+# ---------------------------------------------------------------------------
+
+
+class TestStats:
+    def test_get_stats(self, store: PlaybookStore) -> None:
+        store.save(_make_playbook())
+        stats = store.get_stats(date(2026, 2, 8), "KR")
+        assert stats is not None
+        assert stats["status"] == "ready"
+        assert stats["token_count"] == 150
+        assert stats["scenario_count"] == 1
+        assert stats["match_count"] == 0
+        assert stats["generated_at"] != ""
+
+    def test_get_stats_not_found(self, store: PlaybookStore) -> None:
+        assert store.get_stats(date(2026, 1, 1), "KR") is None
+
+
+# ---------------------------------------------------------------------------
+# List recent
+# ---------------------------------------------------------------------------
+
+
+class TestListRecent:
+    def test_list_recent(self, store: PlaybookStore) -> None:
+        for day in range(5, 10):
+            store.save(_make_playbook(target_date=date(2026, 2, day)))
+        results = store.list_recent(market="KR", limit=3)
+        assert len(results) == 3
+        # Most recent first
+        assert results[0]["date"] == "2026-02-09"
+        assert results[2]["date"] == "2026-02-07"
+
+    def test_list_recent_all_markets(self, store: PlaybookStore) -> None:
+        store.save(_make_playbook(market="KR"))
+        store.save(_make_playbook(market="US", stock_codes=["AAPL"]))
+        results = store.list_recent(market=None, limit=10)
+        assert len(results) == 2
+
+    def test_list_recent_empty(self, store: PlaybookStore) -> None:
+        results = store.list_recent(market="KR")
+        assert results == []
+
+    def test_list_recent_filter_by_market(self, store: PlaybookStore) -> None:
+        store.save(_make_playbook(market="KR"))
+        store.save(_make_playbook(market="US", stock_codes=["AAPL"]))
+        kr_only = store.list_recent(market="KR")
+        assert len(kr_only) == 1
+        assert kr_only[0]["market"] == "KR"
+
+
+# ---------------------------------------------------------------------------
+# Delete
+# ---------------------------------------------------------------------------
+
+
+class TestDelete:
+    def test_delete(self, store: PlaybookStore) -> None:
+        store.save(_make_playbook())
+        deleted = store.delete(date(2026, 2, 8), "KR")
+        assert deleted is True
+        assert store.load(date(2026, 2, 8), "KR") is None
+
+    def test_delete_not_found(self, store: PlaybookStore) -> None:
+        deleted = store.delete(date(2026, 1, 1), "KR")
+        assert deleted is False
+
+    def test_delete_one_market_keeps_other(self, store: PlaybookStore) -> None:
+        store.save(_make_playbook(market="KR"))
+        store.save(_make_playbook(market="US", stock_codes=["AAPL"]))
+        store.delete(date(2026, 2, 8), "KR")
+        assert store.load(date(2026, 2, 8), "KR") is None
+        assert store.load(date(2026, 2, 8), "US") is not None

tests/test_scenario_engine.py

@@ -0,0 +1,442 @@
+"""Tests for the local scenario engine."""
+
+from __future__ import annotations
+
+from datetime import date
+
+import pytest
+
+from src.strategy.models import (
+    DayPlaybook,
+    GlobalRule,
+    ScenarioAction,
+    StockCondition,
+    StockPlaybook,
+    StockScenario,
+)
+from src.strategy.scenario_engine import ScenarioEngine, ScenarioMatch
+
+
+@pytest.fixture
+def engine() -> ScenarioEngine:
+    return ScenarioEngine()
+
+
+def _scenario(
+    rsi_below: float | None = None,
+    rsi_above: float | None = None,
+    volume_ratio_above: float | None = None,
+    action: ScenarioAction = ScenarioAction.BUY,
+    confidence: int = 85,
+    **kwargs,
+) -> StockScenario:
+    return StockScenario(
+        condition=StockCondition(
+            rsi_below=rsi_below,
+            rsi_above=rsi_above,
+            volume_ratio_above=volume_ratio_above,
+            **kwargs,
+        ),
+        action=action,
+        confidence=confidence,
+        rationale=f"Test scenario: {action.value}",
+    )
+
+
+def _playbook(
+    stock_code: str = "005930",
+    scenarios: list[StockScenario] | None = None,
+    global_rules: list[GlobalRule] | None = None,
+    default_action: ScenarioAction = ScenarioAction.HOLD,
+) -> DayPlaybook:
+    if scenarios is None:
+        scenarios = [_scenario(rsi_below=30.0)]
+    return DayPlaybook(
+        date=date(2026, 2, 7),
+        market="KR",
+        stock_playbooks=[StockPlaybook(stock_code=stock_code, scenarios=scenarios)],
+        global_rules=global_rules or [],
+        default_action=default_action,
+    )
+
+
+# ---------------------------------------------------------------------------
+# evaluate_condition
+# ---------------------------------------------------------------------------
+
+
+class TestEvaluateCondition:
+    def test_rsi_below_match(self, engine: ScenarioEngine) -> None:
+        cond = StockCondition(rsi_below=30.0)
+        assert engine.evaluate_condition(cond, {"rsi": 25.0})
+
+    def test_rsi_below_no_match(self, engine: ScenarioEngine) -> None:
+        cond = StockCondition(rsi_below=30.0)
+        assert not engine.evaluate_condition(cond, {"rsi": 35.0})
+
+    def test_rsi_above_match(self, engine: ScenarioEngine) -> None:
+        cond = StockCondition(rsi_above=70.0)
+        assert engine.evaluate_condition(cond, {"rsi": 75.0})
+
+    def test_rsi_above_no_match(self, engine: ScenarioEngine) -> None:
+        cond = StockCondition(rsi_above=70.0)
+        assert not engine.evaluate_condition(cond, {"rsi": 65.0})
+
+    def test_volume_ratio_above_match(self, engine: ScenarioEngine) -> None:
+        cond = StockCondition(volume_ratio_above=3.0)
+        assert engine.evaluate_condition(cond, {"volume_ratio": 4.5})
+
+    def test_volume_ratio_below_match(self, engine: ScenarioEngine) -> None:
+        cond = StockCondition(volume_ratio_below=1.0)
+        assert engine.evaluate_condition(cond, {"volume_ratio": 0.5})
+
+    def test_price_above_match(self, engine: ScenarioEngine) -> None:
+        cond = StockCondition(price_above=50000)
+        assert engine.evaluate_condition(cond, {"current_price": 55000})
+
+    def test_price_below_match(self, engine: ScenarioEngine) -> None:
+        cond = StockCondition(price_below=50000)
+        assert engine.evaluate_condition(cond, {"current_price": 45000})
+
+    def test_price_change_pct_above_match(self, engine: ScenarioEngine) -> None:
+        cond = StockCondition(price_change_pct_above=2.0)
+        assert engine.evaluate_condition(cond, {"price_change_pct": 3.5})
+
+    def test_price_change_pct_below_match(self, engine: ScenarioEngine) -> None:
+        cond = StockCondition(price_change_pct_below=-3.0)
+        assert engine.evaluate_condition(cond, {"price_change_pct": -4.0})
+
+    def test_multiple_conditions_and_logic(self, engine: ScenarioEngine) -> None:
+        cond = StockCondition(rsi_below=30.0, volume_ratio_above=3.0)
+        # Both met
+        assert engine.evaluate_condition(cond, {"rsi": 25.0, "volume_ratio": 4.0})
+        # Only RSI met
+        assert not engine.evaluate_condition(cond, {"rsi": 25.0, "volume_ratio": 2.0})
+        # Only volume met
+        assert not engine.evaluate_condition(cond, {"rsi": 35.0, "volume_ratio": 4.0})
+        # Neither met
+        assert not engine.evaluate_condition(cond, {"rsi": 35.0, "volume_ratio": 2.0})
+
+    def test_empty_condition_returns_false(self, engine: ScenarioEngine) -> None:
+        cond = StockCondition()
+        assert not engine.evaluate_condition(cond, {"rsi": 25.0})
+
+    def test_missing_data_returns_false(self, engine: ScenarioEngine) -> None:
+        cond = StockCondition(rsi_below=30.0)
+        assert not engine.evaluate_condition(cond, {})
+
+    def test_none_data_returns_false(self, engine: ScenarioEngine) -> None:
+        cond = StockCondition(rsi_below=30.0)
+        assert not engine.evaluate_condition(cond, {"rsi": None})
+
+    def test_boundary_value_not_matched(self, engine: ScenarioEngine) -> None:
+        """rsi_below=30 should NOT match rsi=30 (strict less than)."""
+        cond = StockCondition(rsi_below=30.0)
+        assert not engine.evaluate_condition(cond, {"rsi": 30.0})
+
+    def test_boundary_value_above_not_matched(self, engine: ScenarioEngine) -> None:
+        """rsi_above=70 should NOT match rsi=70 (strict greater than)."""
+        cond = StockCondition(rsi_above=70.0)
+        assert not engine.evaluate_condition(cond, {"rsi": 70.0})
+
+    def test_string_value_no_exception(self, engine: ScenarioEngine) -> None:
+        """String numeric value should not raise TypeError."""
+        cond = StockCondition(rsi_below=30.0)
+        # "25" can be cast to float → should match
+        assert engine.evaluate_condition(cond, {"rsi": "25"})
+        # "35" → should not match
+        assert not engine.evaluate_condition(cond, {"rsi": "35"})
+
+    def test_percent_string_returns_false(self, engine: ScenarioEngine) -> None:
+        """Percent string like '30%' cannot be cast to float → False, no exception."""
+        cond = StockCondition(rsi_below=30.0)
+        assert not engine.evaluate_condition(cond, {"rsi": "30%"})
+
+    def test_decimal_value_no_exception(self, engine: ScenarioEngine) -> None:
+        """Decimal values should be safely handled."""
+        from decimal import Decimal
+
+        cond = StockCondition(rsi_below=30.0)
+        assert engine.evaluate_condition(cond, {"rsi": Decimal("25.0")})
+
+    def test_mixed_invalid_types_no_exception(self, engine: ScenarioEngine) -> None:
+        """Various invalid types should not raise exceptions."""
+        cond = StockCondition(
+            rsi_below=30.0, volume_ratio_above=2.0,
+            price_above=100, price_change_pct_below=-1.0,
+        )
+        data = {
+            "rsi": [25],           # list
+            "volume_ratio": "bad",  # non-numeric string
+            "current_price": {},    # dict
+            "price_change_pct": object(),  # arbitrary object
+        }
+        # Should return False (invalid types → None → False), never raise
+        assert not engine.evaluate_condition(cond, data)
+
+    def test_missing_key_logs_warning_once(self, caplog) -> None:
+        """Missing key warning should fire only once per key per engine instance."""
+        import logging
+
+        eng = ScenarioEngine()
+        cond = StockCondition(rsi_below=30.0)
+        with caplog.at_level(logging.WARNING):
+            eng.evaluate_condition(cond, {})
+            eng.evaluate_condition(cond, {})
+            eng.evaluate_condition(cond, {})
+        # Warning should appear exactly once despite 3 calls
+        assert caplog.text.count("'rsi' but key missing") == 1
+
+
+# ---------------------------------------------------------------------------
+# check_global_rules
+# ---------------------------------------------------------------------------
+
+
+class TestCheckGlobalRules:
+    def test_no_rules(self, engine: ScenarioEngine) -> None:
+        pb = _playbook(global_rules=[])
+        result = engine.check_global_rules(pb, {"portfolio_pnl_pct": -1.0})
+        assert result is None
+
+    def test_rule_triggered(self, engine: ScenarioEngine) -> None:
+        pb = _playbook(
+            global_rules=[
+                GlobalRule(
+                    condition="portfolio_pnl_pct < -2.0",
+                    action=ScenarioAction.REDUCE_ALL,
+                    rationale="Near circuit breaker",
+                ),
+            ]
+        )
+        result = engine.check_global_rules(pb, {"portfolio_pnl_pct": -2.5})
+        assert result is not None
+        assert result.action == ScenarioAction.REDUCE_ALL
+
+    def test_rule_not_triggered(self, engine: ScenarioEngine) -> None:
+        pb = _playbook(
+            global_rules=[
+                GlobalRule(
+                    condition="portfolio_pnl_pct < -2.0",
+                    action=ScenarioAction.REDUCE_ALL,
+                ),
+            ]
+        )
+        result = engine.check_global_rules(pb, {"portfolio_pnl_pct": -1.0})
+        assert result is None
+
+    def test_first_rule_wins(self, engine: ScenarioEngine) -> None:
+        pb = _playbook(
+            global_rules=[
+                GlobalRule(condition="portfolio_pnl_pct < -2.0", action=ScenarioAction.REDUCE_ALL),
+                GlobalRule(condition="portfolio_pnl_pct < -1.0", action=ScenarioAction.HOLD),
+            ]
+        )
+        result = engine.check_global_rules(pb, {"portfolio_pnl_pct": -2.5})
+        assert result is not None
+        assert result.action == ScenarioAction.REDUCE_ALL
+
+    def test_greater_than_operator(self, engine: ScenarioEngine) -> None:
+        pb = _playbook(
+            global_rules=[
+                GlobalRule(condition="volatility_index > 30", action=ScenarioAction.HOLD),
+            ]
+        )
+        result = engine.check_global_rules(pb, {"volatility_index": 35})
+        assert result is not None
+
+    def test_missing_field_not_triggered(self, engine: ScenarioEngine) -> None:
+        pb = _playbook(
+            global_rules=[
+                GlobalRule(condition="unknown_field < -2.0", action=ScenarioAction.REDUCE_ALL),
+            ]
+        )
+        result = engine.check_global_rules(pb, {"portfolio_pnl_pct": -5.0})
+        assert result is None
+
+    def test_invalid_condition_format(self, engine: ScenarioEngine) -> None:
+        pb = _playbook(
+            global_rules=[
+                GlobalRule(condition="bad format", action=ScenarioAction.HOLD),
+            ]
+        )
+        result = engine.check_global_rules(pb, {})
+        assert result is None
+
+    def test_le_operator(self, engine: ScenarioEngine) -> None:
+        pb = _playbook(
+            global_rules=[
+                GlobalRule(condition="portfolio_pnl_pct <= -2.0", action=ScenarioAction.REDUCE_ALL),
+            ]
+        )
+        assert engine.check_global_rules(pb, {"portfolio_pnl_pct": -2.0}) is not None
+        assert engine.check_global_rules(pb, {"portfolio_pnl_pct": -1.9}) is None
+
+    def test_ge_operator(self, engine: ScenarioEngine) -> None:
+        pb = _playbook(
+            global_rules=[
+                GlobalRule(condition="volatility >= 80.0", action=ScenarioAction.HOLD),
+            ]
+        )
+        assert engine.check_global_rules(pb, {"volatility": 80.0}) is not None
+        assert engine.check_global_rules(pb, {"volatility": 79.9}) is None
+
+
+# ---------------------------------------------------------------------------
+# evaluate (full pipeline)
+# ---------------------------------------------------------------------------
+
+
+class TestEvaluate:
+    def test_scenario_match(self, engine: ScenarioEngine) -> None:
+        pb = _playbook(scenarios=[_scenario(rsi_below=30.0)])
+        result = engine.evaluate(pb, "005930", {"rsi": 25.0}, {})
+        assert result.action == ScenarioAction.BUY
+        assert result.confidence == 85
+        assert result.matched_scenario is not None
+
+    def test_no_scenario_match_returns_default(self, engine: ScenarioEngine) -> None:
+        pb = _playbook(scenarios=[_scenario(rsi_below=30.0)])
+        result = engine.evaluate(pb, "005930", {"rsi": 50.0}, {})
+        assert result.action == ScenarioAction.HOLD
+        assert result.confidence == 0
+        assert result.matched_scenario is None
+
+    def test_stock_not_in_playbook(self, engine: ScenarioEngine) -> None:
+        pb = _playbook(stock_code="005930")
+        result = engine.evaluate(pb, "AAPL", {"rsi": 25.0}, {})
+        assert result.action == ScenarioAction.HOLD
+        assert result.confidence == 0
+
+    def test_global_rule_takes_priority(self, engine: ScenarioEngine) -> None:
+        pb = _playbook(
+            scenarios=[_scenario(rsi_below=30.0)],
+            global_rules=[
+                GlobalRule(
+                    condition="portfolio_pnl_pct < -2.0",
+                    action=ScenarioAction.REDUCE_ALL,
+                    rationale="Loss limit",
+                ),
+            ],
+        )
+        result = engine.evaluate(
+            pb,
+            "005930",
+            {"rsi": 25.0},  # Would match scenario
+            {"portfolio_pnl_pct": -2.5},  # But global rule triggers first
+        )
+        assert result.action == ScenarioAction.REDUCE_ALL
+        assert result.global_rule_triggered is not None
+        assert result.matched_scenario is None
+
+    def test_first_scenario_wins(self, engine: ScenarioEngine) -> None:
+        pb = _playbook(
+            scenarios=[
+                _scenario(rsi_below=30.0, action=ScenarioAction.BUY, confidence=90),
+                _scenario(rsi_below=25.0, action=ScenarioAction.BUY, confidence=95),
+            ]
+        )
+        result = engine.evaluate(pb, "005930", {"rsi": 20.0}, {})
+        # Both match, but first wins
+        assert result.confidence == 90
+
+    def test_sell_scenario(self, engine: ScenarioEngine) -> None:
+        pb = _playbook(
+            scenarios=[
+                _scenario(rsi_above=75.0, action=ScenarioAction.SELL, confidence=80),
+            ]
+        )
+        result = engine.evaluate(pb, "005930", {"rsi": 80.0}, {})
+        assert result.action == ScenarioAction.SELL
+
+    def test_empty_playbook(self, engine: ScenarioEngine) -> None:
+        pb = DayPlaybook(date=date(2026, 2, 7), market="KR", stock_playbooks=[])
+        result = engine.evaluate(pb, "005930", {"rsi": 25.0}, {})
+        assert result.action == ScenarioAction.HOLD
+
+    def test_match_details_populated(self, engine: ScenarioEngine) -> None:
+        pb = _playbook(scenarios=[_scenario(rsi_below=30.0, volume_ratio_above=2.0)])
+        result = engine.evaluate(
+            pb, "005930", {"rsi": 25.0, "volume_ratio": 3.0}, {}
+        )
+        assert result.match_details.get("rsi") == 25.0
+        assert result.match_details.get("volume_ratio") == 3.0
+
+    def test_custom_default_action(self, engine: ScenarioEngine) -> None:
+        pb = _playbook(
+            scenarios=[_scenario(rsi_below=10.0)],  # Very unlikely to match
+            default_action=ScenarioAction.SELL,
+        )
+        result = engine.evaluate(pb, "005930", {"rsi": 50.0}, {})
+        assert result.action == ScenarioAction.SELL
+
+    def test_multiple_stocks_in_playbook(self, engine: ScenarioEngine) -> None:
+        pb = DayPlaybook(
+            date=date(2026, 2, 7),
+            market="US",
+            stock_playbooks=[
+                StockPlaybook(
+                    stock_code="AAPL",
+                    scenarios=[_scenario(rsi_below=25.0, confidence=90)],
+                ),
+                StockPlaybook(
+                    stock_code="MSFT",
+                    scenarios=[_scenario(rsi_above=75.0, action=ScenarioAction.SELL, confidence=80)],
+                ),
+            ],
+        )
+        aapl = engine.evaluate(pb, "AAPL", {"rsi": 20.0}, {})
+        assert aapl.action == ScenarioAction.BUY
+        assert aapl.confidence == 90
+
+        msft = engine.evaluate(pb, "MSFT", {"rsi": 80.0}, {})
+        assert msft.action == ScenarioAction.SELL
+
+    def test_complex_multi_condition(self, engine: ScenarioEngine) -> None:
+        pb = _playbook(
+            scenarios=[
+                _scenario(
+                    rsi_below=30.0,
+                    volume_ratio_above=3.0,
+                    price_change_pct_below=-2.0,
+                    confidence=95,
+                ),
+            ]
+        )
+        # All conditions met
+        result = engine.evaluate(
+            pb,
+            "005930",
+            {"rsi": 22.0, "volume_ratio": 4.0, "price_change_pct": -3.0},
+            {},
+        )
+        assert result.action == ScenarioAction.BUY
+        assert result.confidence == 95
+
+        # One condition not met
+        result2 = engine.evaluate(
+            pb,
+            "005930",
+            {"rsi": 22.0, "volume_ratio": 4.0, "price_change_pct": -1.0},
+            {},
+        )
+        assert result2.action == ScenarioAction.HOLD
+
+    def test_scenario_match_returns_rationale(self, engine: ScenarioEngine) -> None:
+        pb = _playbook(scenarios=[_scenario(rsi_below=30.0)])
+        result = engine.evaluate(pb, "005930", {"rsi": 25.0}, {})
+        assert result.rationale != ""
+
+    def test_result_stock_code(self, engine: ScenarioEngine) -> None:
+        pb = _playbook()
+        result = engine.evaluate(pb, "005930", {"rsi": 25.0}, {})
+        assert result.stock_code == "005930"
+
+    def test_match_details_normalized(self, engine: ScenarioEngine) -> None:
+        """match_details should contain _safe_float normalized values, not raw."""
+        pb = _playbook(scenarios=[_scenario(rsi_below=30.0)])
+        # Pass string value — should be normalized to float in match_details
+        result = engine.evaluate(pb, "005930", {"rsi": "25.0"}, {})
+        assert result.action == ScenarioAction.BUY
+        assert result.match_details["rsi"] == 25.0
+        assert isinstance(result.match_details["rsi"], float)

tests/test_smart_scanner.py

@@ -0,0 +1,377 @@
+"""Tests for SmartVolatilityScanner."""
+
+from __future__ import annotations
+
+import pytest
+from unittest.mock import AsyncMock, MagicMock
+
+from src.analysis.smart_scanner import ScanCandidate, SmartVolatilityScanner
+from src.analysis.volatility import VolatilityAnalyzer
+from src.broker.kis_api import KISBroker
+from src.config import Settings
+
+
+@pytest.fixture
+def mock_settings() -> Settings:
+    """Create test settings."""
+    return Settings(
+        KIS_APP_KEY="test",
+        KIS_APP_SECRET="test",
+        KIS_ACCOUNT_NO="12345678-01",
+        GEMINI_API_KEY="test",
+        RSI_OVERSOLD_THRESHOLD=30,
+        RSI_MOMENTUM_THRESHOLD=70,
+        VOL_MULTIPLIER=2.0,
+        SCANNER_TOP_N=3,
+        DB_PATH=":memory:",
+    )
+
+
+@pytest.fixture
+def mock_broker(mock_settings: Settings) -> MagicMock:
+    """Create mock broker."""
+    broker = MagicMock(spec=KISBroker)
+    broker._settings = mock_settings
+    broker.fetch_market_rankings = AsyncMock()
+    broker.get_daily_prices = AsyncMock()
+    return broker
+
+
+@pytest.fixture
+def scanner(mock_broker: MagicMock, mock_settings: Settings) -> SmartVolatilityScanner:
+    """Create smart scanner instance."""
+    analyzer = VolatilityAnalyzer()
+    return SmartVolatilityScanner(
+        broker=mock_broker,
+        volatility_analyzer=analyzer,
+        settings=mock_settings,
+    )
+
+
+class TestSmartVolatilityScanner:
+    """Test suite for SmartVolatilityScanner."""
+
+    @pytest.mark.asyncio
+    async def test_scan_finds_oversold_candidates(
+        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
+    ) -> None:
+        """Test that scanner identifies oversold stocks with high volume."""
+        # Mock rankings
+        mock_broker.fetch_market_rankings.return_value = [
+            {
+                "stock_code": "005930",
+                "name": "Samsung",
+                "price": 70000,
+                "volume": 5000000,
+                "change_rate": -3.5,
+                "volume_increase_rate": 250,
+            },
+        ]
+
+        # Mock daily prices - trending down (oversold)
+        prices = []
+        for i in range(20):
+            prices.append({
+                "date": f"2026020{i:02d}",
+                "open": 75000 - i * 200,
+                "high": 75500 - i * 200,
+                "low": 74500 - i * 200,
+                "close": 75000 - i * 250,  # Steady decline
+                "volume": 2000000,
+            })
+        mock_broker.get_daily_prices.return_value = prices
+
+        candidates = await scanner.scan()
+
+        # Should find at least one candidate (depending on exact RSI calculation)
+        mock_broker.fetch_market_rankings.assert_called_once()
+        mock_broker.get_daily_prices.assert_called_once_with("005930", days=20)
+
+        # If qualified, should have oversold signal
+        if candidates:
+            assert candidates[0].signal in ["oversold", "momentum"]
+            assert candidates[0].volume_ratio >= scanner.vol_multiplier
+
+    @pytest.mark.asyncio
+    async def test_scan_finds_momentum_candidates(
+        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
+    ) -> None:
+        """Test that scanner identifies momentum stocks with high volume."""
+        mock_broker.fetch_market_rankings.return_value = [
+            {
+                "stock_code": "035420",
+                "name": "NAVER",
+                "price": 250000,
+                "volume": 3000000,
+                "change_rate": 5.0,
+                "volume_increase_rate": 300,
+            },
+        ]
+
+        # Mock daily prices - trending up (momentum)
+        prices = []
+        for i in range(20):
+            prices.append({
+                "date": f"2026020{i:02d}",
+                "open": 230000 + i * 500,
+                "high": 231000 + i * 500,
+                "low": 229000 + i * 500,
+                "close": 230500 + i * 500,  # Steady rise
+                "volume": 1000000,
+            })
+        mock_broker.get_daily_prices.return_value = prices
+
+        candidates = await scanner.scan()
+
+        mock_broker.fetch_market_rankings.assert_called_once()
+
+    @pytest.mark.asyncio
+    async def test_scan_filters_low_volume(
+        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
+    ) -> None:
+        """Test that stocks with low volume ratio are filtered out."""
+        mock_broker.fetch_market_rankings.return_value = [
+            {
+                "stock_code": "000660",
+                "name": "SK Hynix",
+                "price": 150000,
+                "volume": 500000,
+                "change_rate": -5.0,
+                "volume_increase_rate": 50,  # Only 50% increase (< 200%)
+            },
+        ]
+
+        # Low volume
+        prices = []
+        for i in range(20):
+            prices.append({
+                "date": f"2026020{i:02d}",
+                "open": 150000 - i * 100,
+                "high": 151000 - i * 100,
+                "low": 149000 - i * 100,
+                "close": 150000 - i * 150,  # Declining (would be oversold)
+                "volume": 1000000,  # Current 500k < 2x prev day 1M
+            })
+        mock_broker.get_daily_prices.return_value = prices
+
+        candidates = await scanner.scan()
+
+        # Should be filtered out due to low volume ratio
+        assert len(candidates) == 0
+
+    @pytest.mark.asyncio
+    async def test_scan_filters_neutral_rsi(
+        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
+    ) -> None:
+        """Test that stocks with neutral RSI are filtered out."""
+        mock_broker.fetch_market_rankings.return_value = [
+            {
+                "stock_code": "051910",
+                "name": "LG Chem",
+                "price": 500000,
+                "volume": 3000000,
+                "change_rate": 0.5,
+                "volume_increase_rate": 300,  # High volume
+            },
+        ]
+
+        # Flat prices (neutral RSI ~50)
+        prices = []
+        for i in range(20):
+            prices.append({
+                "date": f"2026020{i:02d}",
+                "open": 500000 + (i % 2) * 100,  # Small oscillation
+                "high": 500500,
+                "low": 499500,
+                "close": 500000 + (i % 2) * 50,
+                "volume": 1000000,
+            })
+        mock_broker.get_daily_prices.return_value = prices
+
+        candidates = await scanner.scan()
+
+        # Should be filtered out (RSI ~50, not < 30 or > 70)
+        assert len(candidates) == 0
+
+    @pytest.mark.asyncio
+    async def test_scan_uses_fallback_on_api_error(
+        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
+    ) -> None:
+        """Test fallback to static list when ranking API fails."""
+        mock_broker.fetch_market_rankings.side_effect = ConnectionError("API unavailable")
+
+        # Fallback stocks should still be analyzed
+        prices = []
+        for i in range(20):
+            prices.append({
+                "date": f"2026020{i:02d}",
+                "open": 50000 - i * 50,
+                "high": 51000 - i * 50,
+                "low": 49000 - i * 50,
+                "close": 50000 - i * 75,  # Declining
+                "volume": 1000000,
+            })
+        mock_broker.get_daily_prices.return_value = prices
+
+        candidates = await scanner.scan(fallback_stocks=["005930", "000660"])
+
+        # Should not crash
+        assert isinstance(candidates, list)
+
+    @pytest.mark.asyncio
+    async def test_scan_returns_top_n_only(
+        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
+    ) -> None:
+        """Test that scan returns at most top_n candidates."""
+        # Return many stocks
+        mock_broker.fetch_market_rankings.return_value = [
+            {
+                "stock_code": f"00{i}000",
+                "name": f"Stock{i}",
+                "price": 10000 * i,
+                "volume": 5000000,
+                "change_rate": -10,
+                "volume_increase_rate": 500,
+            }
+            for i in range(1, 10)
+        ]
+
+        # All oversold with high volume
+        def make_prices(code: str) -> list[dict]:
+            prices = []
+            for i in range(20):
+                prices.append({
+                    "date": f"2026020{i:02d}",
+                    "open": 10000 - i * 100,
+                    "high": 10500 - i * 100,
+                    "low": 9500 - i * 100,
+                    "close": 10000 - i * 150,
+                    "volume": 1000000,
+                })
+            return prices
+
+        mock_broker.get_daily_prices.side_effect = make_prices
+
+        candidates = await scanner.scan()
+
+        # Should respect top_n limit (3)
+        assert len(candidates) <= scanner.top_n
+
+    @pytest.mark.asyncio
+    async def test_scan_skips_insufficient_price_history(
+        self, scanner: SmartVolatilityScanner, mock_broker: MagicMock
+    ) -> None:
+        """Test that stocks with insufficient history are skipped."""
+        mock_broker.fetch_market_rankings.return_value = [
+            {
+                "stock_code": "005930",
+                "name": "Samsung",
+                "price": 70000,
+                "volume": 5000000,
+                "change_rate": -5.0,
+                "volume_increase_rate": 300,
+            },
+        ]
+
+        # Only 5 days of data (need 15+ for RSI)
+        mock_broker.get_daily_prices.return_value = [
+            {
+                "date": f"2026020{i:02d}",
+                "open": 70000,
+                "high": 71000,
+                "low": 69000,
+                "close": 70000,
+                "volume": 2000000,
+            }
+            for i in range(5)
+        ]
+
+        candidates = await scanner.scan()
+
+        # Should skip due to insufficient data
+        assert len(candidates) == 0
+
+    @pytest.mark.asyncio
+    async def test_get_stock_codes(
+        self, scanner: SmartVolatilityScanner
+    ) -> None:
+        """Test extraction of stock codes from candidates."""
+        candidates = [
+            ScanCandidate(
+                stock_code="005930",
+                name="Samsung",
+                price=70000,
+                volume=5000000,
+                volume_ratio=2.5,
+                rsi=28,
+                signal="oversold",
+                score=85.0,
+            ),
+            ScanCandidate(
+                stock_code="035420",
+                name="NAVER",
+                price=250000,
+                volume=3000000,
+                volume_ratio=3.0,
+                rsi=75,
+                signal="momentum",
+                score=88.0,
+            ),
+        ]
+
+        codes = scanner.get_stock_codes(candidates)
+
+        assert codes == ["005930", "035420"]
+
+
+class TestRSICalculation:
+    """Test RSI calculation in VolatilityAnalyzer."""
+
+    def test_rsi_oversold(self) -> None:
+        """Test RSI calculation for downtrending prices."""
+        analyzer = VolatilityAnalyzer()
+
+        # Steadily declining prices
+        prices = [100 - i * 0.5 for i in range(20)]
+        rsi = analyzer.calculate_rsi(prices, period=14)
+
+        assert rsi < 50  # Should be oversold territory
+
+    def test_rsi_overbought(self) -> None:
+        """Test RSI calculation for uptrending prices."""
+        analyzer = VolatilityAnalyzer()
+
+        # Steadily rising prices
+        prices = [100 + i * 0.5 for i in range(20)]
+        rsi = analyzer.calculate_rsi(prices, period=14)
+
+        assert rsi > 50  # Should be overbought territory
+
+    def test_rsi_neutral(self) -> None:
+        """Test RSI calculation for flat prices."""
+        analyzer = VolatilityAnalyzer()
+
+        # Flat prices with small oscillation
+        prices = [100 + (i % 2) * 0.1 for i in range(20)]
+        rsi = analyzer.calculate_rsi(prices, period=14)
+
+        assert 40 < rsi < 60  # Should be near neutral
+
+    def test_rsi_insufficient_data(self) -> None:
+        """Test RSI returns neutral when insufficient data."""
+        analyzer = VolatilityAnalyzer()
+
+        prices = [100, 101, 102]  # Only 3 prices, need 15+
+        rsi = analyzer.calculate_rsi(prices, period=14)
+
+        assert rsi == 50.0  # Default neutral
+
+    def test_rsi_all_gains(self) -> None:
+        """Test RSI returns 100 when all gains (no losses)."""
+        analyzer = VolatilityAnalyzer()
+
+        # Monotonic increase
+        prices = [100 + i for i in range(20)]
+        rsi = analyzer.calculate_rsi(prices, period=14)
+
+        assert rsi == 100.0  # Maximum RSI

tests/test_strategy_models.py

@@ -0,0 +1,366 @@
+"""Tests for strategy/playbook Pydantic models."""
+
+from __future__ import annotations
+
+from datetime import date
+
+import pytest
+from pydantic import ValidationError
+
+from src.strategy.models import (
+    CrossMarketContext,
+    DayPlaybook,
+    GlobalRule,
+    MarketOutlook,
+    PlaybookStatus,
+    ScenarioAction,
+    StockCondition,
+    StockPlaybook,
+    StockScenario,
+)
+
+
+# ---------------------------------------------------------------------------
+# StockCondition
+# ---------------------------------------------------------------------------
+
+
+class TestStockCondition:
+    def test_empty_condition(self) -> None:
+        cond = StockCondition()
+        assert not cond.has_any_condition()
+
+    def test_single_field(self) -> None:
+        cond = StockCondition(rsi_below=30.0)
+        assert cond.has_any_condition()
+
+    def test_multiple_fields(self) -> None:
+        cond = StockCondition(rsi_below=25.0, volume_ratio_above=3.0)
+        assert cond.has_any_condition()
+
+    def test_all_fields(self) -> None:
+        cond = StockCondition(
+            rsi_below=30,
+            rsi_above=10,
+            volume_ratio_above=2.0,
+            volume_ratio_below=10.0,
+            price_above=1000,
+            price_below=50000,
+            price_change_pct_above=-5.0,
+            price_change_pct_below=5.0,
+        )
+        assert cond.has_any_condition()
+
+
+# ---------------------------------------------------------------------------
+# StockScenario
+# ---------------------------------------------------------------------------
+
+
+class TestStockScenario:
+    def test_valid_scenario(self) -> None:
+        s = StockScenario(
+            condition=StockCondition(rsi_below=25.0),
+            action=ScenarioAction.BUY,
+            confidence=85,
+            allocation_pct=15.0,
+            stop_loss_pct=-2.0,
+            take_profit_pct=3.0,
+            rationale="Oversold bounce expected",
+        )
+        assert s.action == ScenarioAction.BUY
+        assert s.confidence == 85
+
+    def test_confidence_too_high(self) -> None:
+        with pytest.raises(ValidationError):
+            StockScenario(
+                condition=StockCondition(),
+                action=ScenarioAction.BUY,
+                confidence=101,
+            )
+
+    def test_confidence_too_low(self) -> None:
+        with pytest.raises(ValidationError):
+            StockScenario(
+                condition=StockCondition(),
+                action=ScenarioAction.BUY,
+                confidence=-1,
+            )
+
+    def test_allocation_too_high(self) -> None:
+        with pytest.raises(ValidationError):
+            StockScenario(
+                condition=StockCondition(),
+                action=ScenarioAction.BUY,
+                confidence=80,
+                allocation_pct=101.0,
+            )
+
+    def test_stop_loss_must_be_negative(self) -> None:
+        with pytest.raises(ValidationError):
+            StockScenario(
+                condition=StockCondition(),
+                action=ScenarioAction.BUY,
+                confidence=80,
+                stop_loss_pct=1.0,
+            )
+
+    def test_take_profit_must_be_positive(self) -> None:
+        with pytest.raises(ValidationError):
+            StockScenario(
+                condition=StockCondition(),
+                action=ScenarioAction.BUY,
+                confidence=80,
+                take_profit_pct=-1.0,
+            )
+
+    def test_defaults(self) -> None:
+        s = StockScenario(
+            condition=StockCondition(),
+            action=ScenarioAction.HOLD,
+            confidence=50,
+        )
+        assert s.allocation_pct == 10.0
+        assert s.stop_loss_pct == -2.0
+        assert s.take_profit_pct == 3.0
+        assert s.rationale == ""
+
+
+# ---------------------------------------------------------------------------
+# StockPlaybook
+# ---------------------------------------------------------------------------
+
+
+class TestStockPlaybook:
+    def test_valid_playbook(self) -> None:
+        pb = StockPlaybook(
+            stock_code="005930",
+            stock_name="Samsung Electronics",
+            scenarios=[
+                StockScenario(
+                    condition=StockCondition(rsi_below=25.0),
+                    action=ScenarioAction.BUY,
+                    confidence=85,
+                ),
+            ],
+        )
+        assert pb.stock_code == "005930"
+        assert len(pb.scenarios) == 1
+
+    def test_empty_scenarios_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            StockPlaybook(
+                stock_code="005930",
+                scenarios=[],
+            )
+
+    def test_multiple_scenarios(self) -> None:
+        pb = StockPlaybook(
+            stock_code="AAPL",
+            scenarios=[
+                StockScenario(
+                    condition=StockCondition(rsi_below=25.0),
+                    action=ScenarioAction.BUY,
+                    confidence=85,
+                ),
+                StockScenario(
+                    condition=StockCondition(rsi_above=75.0),
+                    action=ScenarioAction.SELL,
+                    confidence=80,
+                ),
+            ],
+        )
+        assert len(pb.scenarios) == 2
+
+
+# ---------------------------------------------------------------------------
+# GlobalRule
+# ---------------------------------------------------------------------------
+
+
+class TestGlobalRule:
+    def test_valid_rule(self) -> None:
+        rule = GlobalRule(
+            condition="portfolio_pnl_pct < -2.0",
+            action=ScenarioAction.REDUCE_ALL,
+            rationale="Risk limit approaching",
+        )
+        assert rule.action == ScenarioAction.REDUCE_ALL
+
+    def test_hold_rule(self) -> None:
+        rule = GlobalRule(
+            condition="volatility_index > 30",
+            action=ScenarioAction.HOLD,
+        )
+        assert rule.rationale == ""
+
+
+# ---------------------------------------------------------------------------
+# CrossMarketContext
+# ---------------------------------------------------------------------------
+
+
+class TestCrossMarketContext:
+    def test_valid_context(self) -> None:
+        ctx = CrossMarketContext(
+            market="US",
+            date="2026-02-07",
+            total_pnl=-1.5,
+            win_rate=40.0,
+            index_change_pct=-2.3,
+            key_events=["Fed rate decision"],
+            lessons=["Avoid tech sector on rate hike days"],
+        )
+        assert ctx.market == "US"
+        assert len(ctx.key_events) == 1
+
+    def test_defaults(self) -> None:
+        ctx = CrossMarketContext(market="KR", date="2026-02-07")
+        assert ctx.total_pnl == 0.0
+        assert ctx.key_events == []
+        assert ctx.lessons == []
+
+
+# ---------------------------------------------------------------------------
+# DayPlaybook
+# ---------------------------------------------------------------------------
+
+
+def _make_scenario(rsi_below: float = 25.0) -> StockScenario:
+    return StockScenario(
+        condition=StockCondition(rsi_below=rsi_below),
+        action=ScenarioAction.BUY,
+        confidence=85,
+    )
+
+
+def _make_playbook(**kwargs) -> DayPlaybook:
+    defaults = {
+        "date": date(2026, 2, 7),
+        "market": "KR",
+        "stock_playbooks": [
+            StockPlaybook(stock_code="005930", scenarios=[_make_scenario()]),
+        ],
+    }
+    defaults.update(kwargs)
+    return DayPlaybook(**defaults)
+
+
+class TestDayPlaybook:
+    def test_valid_playbook(self) -> None:
+        pb = _make_playbook()
+        assert pb.market == "KR"
+        assert pb.date == date(2026, 2, 7)
+        assert pb.default_action == ScenarioAction.HOLD
+        assert pb.scenario_count == 1
+        assert pb.stock_count == 1
+
+    def test_generated_at_auto_set(self) -> None:
+        pb = _make_playbook()
+        assert pb.generated_at != ""
+
+    def test_explicit_generated_at(self) -> None:
+        pb = _make_playbook(generated_at="2026-02-07T08:30:00")
+        assert pb.generated_at == "2026-02-07T08:30:00"
+
+    def test_duplicate_stocks_rejected(self) -> None:
+        with pytest.raises(ValidationError):
+            DayPlaybook(
+                date=date(2026, 2, 7),
+                market="KR",
+                stock_playbooks=[
+                    StockPlaybook(stock_code="005930", scenarios=[_make_scenario()]),
+                    StockPlaybook(stock_code="005930", scenarios=[_make_scenario(30)]),
+                ],
+            )
+
+    def test_empty_stock_playbooks_allowed(self) -> None:
+        pb = DayPlaybook(
+            date=date(2026, 2, 7),
+            market="KR",
+            stock_playbooks=[],
+        )
+        assert pb.stock_count == 0
+        assert pb.scenario_count == 0
+
+    def test_get_stock_playbook_found(self) -> None:
+        pb = _make_playbook()
+        result = pb.get_stock_playbook("005930")
+        assert result is not None
+        assert result.stock_code == "005930"
+
+    def test_get_stock_playbook_not_found(self) -> None:
+        pb = _make_playbook()
+        result = pb.get_stock_playbook("AAPL")
+        assert result is None
+
+    def test_with_global_rules(self) -> None:
+        pb = _make_playbook(
+            global_rules=[
+                GlobalRule(
+                    condition="portfolio_pnl_pct < -2.0",
+                    action=ScenarioAction.REDUCE_ALL,
+                ),
+            ],
+        )
+        assert len(pb.global_rules) == 1
+
+    def test_with_cross_market_context(self) -> None:
+        ctx = CrossMarketContext(market="US", date="2026-02-07", total_pnl=-1.5)
+        pb = _make_playbook(cross_market=ctx)
+        assert pb.cross_market is not None
+        assert pb.cross_market.market == "US"
+
+    def test_market_outlook(self) -> None:
+        pb = _make_playbook(market_outlook=MarketOutlook.BEARISH)
+        assert pb.market_outlook == MarketOutlook.BEARISH
+
+    def test_multiple_stocks_multiple_scenarios(self) -> None:
+        pb = DayPlaybook(
+            date=date(2026, 2, 7),
+            market="US",
+            stock_playbooks=[
+                StockPlaybook(
+                    stock_code="AAPL",
+                    scenarios=[_make_scenario(), _make_scenario(30)],
+                ),
+                StockPlaybook(
+                    stock_code="MSFT",
+                    scenarios=[_make_scenario()],
+                ),
+            ],
+        )
+        assert pb.stock_count == 2
+        assert pb.scenario_count == 3
+
+    def test_serialization_roundtrip(self) -> None:
+        pb = _make_playbook(
+            market_outlook=MarketOutlook.BULLISH,
+            cross_market=CrossMarketContext(market="US", date="2026-02-07"),
+        )
+        json_str = pb.model_dump_json()
+        restored = DayPlaybook.model_validate_json(json_str)
+        assert restored.market == pb.market
+        assert restored.date == pb.date
+        assert restored.scenario_count == pb.scenario_count
+        assert restored.cross_market is not None
+
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+
+class TestEnums:
+    def test_scenario_action_values(self) -> None:
+        assert ScenarioAction.BUY.value == "BUY"
+        assert ScenarioAction.SELL.value == "SELL"
+        assert ScenarioAction.HOLD.value == "HOLD"
+        assert ScenarioAction.REDUCE_ALL.value == "REDUCE_ALL"
+
+    def test_market_outlook_values(self) -> None:
+        assert len(MarketOutlook) == 5
+
+    def test_playbook_status_values(self) -> None:
+        assert PlaybookStatus.READY.value == "ready"
+        assert PlaybookStatus.EXPIRED.value == "expired"

tests/test_telegram_commands.py

@@ -230,6 +230,31 @@ class TestUpdateHandling:
         await handler._handle_update(update)
         assert executed is False
 
+    @pytest.mark.asyncio
+    async def test_handle_command_with_botname(self) -> None:
+        """Commands with @botname suffix are handled correctly."""
+        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
+        handler = TelegramCommandHandler(client)
+
+        executed = False
+
+        async def test_command() -> None:
+            nonlocal executed
+            executed = True
+
+        handler.register_command("start", test_command)
+
+        update = {
+            "update_id": 1,
+            "message": {
+                "chat": {"id": 456},
+                "text": "/start@mybot",
+            },
+        }
+
+        await handler._handle_update(update)
+        assert executed is True
+
     @pytest.mark.asyncio
     async def test_handle_update_error_isolation(self) -> None:
         """Errors in handlers don't crash the system."""
@@ -524,7 +549,7 @@ class TestStatusCommands:
 
     @pytest.mark.asyncio
     async def test_positions_command_shows_holdings(self) -> None:
-        """Positions command displays current holdings."""
+        """Positions command displays account summary."""
         client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
         handler = TelegramCommandHandler(client)
 
@@ -536,12 +561,12 @@ class TestStatusCommands:
         async def mock_positions() -> None:
             """Mock /positions handler."""
             message = (
-                "<b>💼 Current Holdings</b>\n"
-                "\n🇰🇷 <b>Korea</b>\n"
-                "• 005930: 10 shares @ 70,000\n"
-                "\n🇺🇸 <b>Overseas</b>\n"
-                "• AAPL: 15 shares @ 175\n"
-                "\n<b>Cash:</b> ₩5,000,000"
+                "<b>💼 Account Summary</b>\n\n"
+                "<b>Total Evaluation:</b> ₩10,500,000\n"
+                "<b>Available Cash:</b> ₩5,000,000\n"
+                "<b>Purchase Total:</b> ₩10,000,000\n"
+                "<b>P&L:</b> +5.00%\n\n"
+                "<i>Note: Individual position details require API enhancement</i>"
             )
             await client.send_message(message)
 
@@ -561,8 +586,9 @@ class TestStatusCommands:
             # Verify message was sent
             assert mock_post.call_count == 1
             payload = mock_post.call_args.kwargs["json"]
-            assert "Current Holdings" in payload["text"]
-            assert "shares" in payload["text"]
+            assert "Account Summary" in payload["text"]
+            assert "Total Evaluation" in payload["text"]
+            assert "P&L" in payload["text"]
 
     @pytest.mark.asyncio
     async def test_positions_command_empty_holdings(self) -> None:
@@ -578,8 +604,8 @@ class TestStatusCommands:
         async def mock_positions_empty() -> None:
             """Mock /positions handler with no positions."""
             message = (
-                "<b>💼 Current Holdings</b>\n\n"
-                "No positions currently held."
+                "<b>💼 Account Summary</b>\n\n"
+                "No balance information available."
             )
             await client.send_message(message)
 
@@ -598,7 +624,7 @@ class TestStatusCommands:
 
             # Verify message was sent
             payload = mock_post.call_args.kwargs["json"]
-            assert "No positions" in payload["text"]
+            assert "No balance information available" in payload["text"]
 
     @pytest.mark.asyncio
     async def test_positions_command_error_handling(self) -> None:
@@ -638,51 +664,6 @@ class TestStatusCommands:
 class TestBasicCommands:
     """Test basic command implementations."""
 
-    @pytest.mark.asyncio
-    async def test_start_command_content(self) -> None:
-        """Start command contains welcome message and command list."""
-        client = TelegramClient(bot_token="123:abc", chat_id="456", enabled=True)
-        handler = TelegramCommandHandler(client)
-
-        mock_resp = AsyncMock()
-        mock_resp.status = 200
-        mock_resp.__aenter__ = AsyncMock(return_value=mock_resp)
-        mock_resp.__aexit__ = AsyncMock(return_value=False)
-
-        async def mock_start() -> None:
-            """Mock /start handler."""
-            message = (
-                "<b>🤖 The Ouroboros Trading Bot</b>\n\n"
-                "AI-powered global stock trading agent with real-time notifications.\n\n"
-                "<b>Available commands:</b>\n"
-                "/help - Show this help message\n"
-                "/status - Current trading status\n"
-                "/positions - View holdings\n"
-                "/stop - Pause trading\n"
-                "/resume - Resume trading"
-            )
-            await client.send_message(message)
-
-        handler.register_command("start", mock_start)
-
-        with patch("aiohttp.ClientSession.post", return_value=mock_resp) as mock_post:
-            update = {
-                "update_id": 1,
-                "message": {
-                    "chat": {"id": 456},
-                    "text": "/start",
-                },
-            }
-
-            await handler._handle_update(update)
-
-            # Verify message was sent
-            assert mock_post.call_count == 1
-            payload = mock_post.call_args.kwargs["json"]
-            assert "Ouroboros Trading Bot" in payload["text"]
-            assert "/help" in payload["text"]
-            assert "/status" in payload["text"]
-
     @pytest.mark.asyncio
     async def test_help_command_content(self) -> None:
         """Help command lists all available commands."""
@@ -698,7 +679,6 @@ class TestBasicCommands:
             """Mock /help handler."""
             message = (
                 "<b>📖 Available Commands</b>\n\n"
-                "/start - Welcome message\n"
                 "/help - Show available commands\n"
                 "/status - Trading status (mode, markets, P&L)\n"
                 "/positions - Current holdings\n"
@@ -724,7 +704,6 @@ class TestBasicCommands:
             assert mock_post.call_count == 1
             payload = mock_post.call_args.kwargs["json"]
             assert "Available Commands" in payload["text"]
-            assert "/start" in payload["text"]
             assert "/help" in payload["text"]
             assert "/status" in payload["text"]
             assert "/positions" in payload["text"]