docs: add requirements log entry for overseas limit order fix (#149)

KIS VTS (paper trading) rejects overseas market orders with:
  "모의투자 주문처리가 안되었습니다(지정가만 가능한 상품입니다)"

Root cause: send_overseas_order() was called with price=0.0 (market order)
in both trading_cycle() and run_daily_session(), even though current_price
was already computed correctly by Fix #147 (exchange code mapping).

Fix: pass current_price as the limit order price in both call sites.
Domestic broker send_order() keeps price=0 (market orders are fine on KRX).

Adds regression test TestOverseasBalanceParsing::test_overseas_buy_order_uses_limit_price
verifying price=182.5 is passed, not 0.0.

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

docs/requirements-log.md

@@ -201,3 +201,68 @@
 - `tests/test_brain.py`: 3개 테스트 추가 (override 전달, optimization 우회, 미지정 시 기존 동작 유지)
 
 **이슈/PR:** #143
+
+### 미국장 거래 미실행 근본 원인 분석 및 수정 (자율 실행 세션)
+
+**배경:**
+- 사용자 요청: "미국장 열면 프로그램 돌려서 거래 한 번도 못 한 거 꼭 원인 찾아서 해결해줘"
+- 프로그램을 미국장 개장(9:30 AM EST) 전부터 실행하여 실시간 로그를 분석
+
+**발견된 근본 원인 #1: Defensive Playbook — BUY 조건 없음**
+
+- Gemini free tier (20 RPD) 소진 → `generate_playbook()` 실패 → `_defensive_playbook()` 폴백
+- Defensive playbook은 `price_change_pct_below: -3.0 → SELL` 조건만 존재, BUY 조건 없음
+- ScenarioEngine이 항상 HOLD 반환 → 거래 0건
+
+**수정 #1 (PR #146, Issue #145):**
+- `src/strategy/pre_market_planner.py`: `_smart_fallback_playbook()` 메서드 추가
+  - 스캐너 signal 기반 BUY 조건 생성: `momentum → volume_ratio_above`, `oversold → rsi_below`
+  - 기존 defensive stop-loss SELL 조건 유지
+- Gemini 실패 시 defensive → smart fallback으로 전환
+- 테스트 10개 추가
+
+**발견된 근본 원인 #2: 가격 API 거래소 코드 불일치 + VTS 잔고 API 오류**
+
+실제 로그:
+```
+Scenario matched for MRNX: BUY (confidence=80)  ✓
+Decision for EWUS (NYSE American): BUY (confidence=80)  ✓
+Skip BUY APLZ (NYSE American): no affordable quantity (cash=0.00, price=0.00)  ✗
+```
+
+- `get_overseas_price()`: `NASD`/`NYSE`/`AMEX` 전송 → API가 `NAS`/`NYS`/`AMS` 기대 → 빈 응답 → `price=0`
+- `VTTS3012R` 잔고 API: "ERROR : INPUT INVALID_CHECK_ACNO" → `total_cash=0`
+- 결과: `_determine_order_quantity()` 가 0 반환 → 주문 건너뜀
+
+**수정 #2 (PR #148, Issue #147):**
+- `src/broker/overseas.py`: `_PRICE_EXCHANGE_MAP = _RANKING_EXCHANGE_MAP` 추가, 가격 API에 매핑 적용
+- `src/config.py`: `PAPER_OVERSEAS_CASH: float = Field(default=50000.0)` — paper 모드 시뮬레이션 잔고
+- `src/main.py`: 잔고 0일 때 PAPER_OVERSEAS_CASH 폴백, 가격 0일 때 candidate.price 폴백
+- 테스트 8개 추가
+
+**효과:**
+- BUY 결정 → 실제 주문 전송까지의 파이프라인이 완전히 동작
+- Paper 모드에서 KIS VTS 해외 잔고 API 오류에 관계없이 시뮬레이션 거래 가능
+
+**이슈/PR:** #145, #146, #147, #148
+
+### 해외주식 시장가 주문 거부 수정 (Fix #3, 연속 발견)
+
+**배경:**
+- Fix #147 적용 후 주문 전송 시작 → KIS VTS가 거부: "지정가만 가능한 상품입니다"
+
+**근본 원인:**
+- `trading_cycle()`, `run_daily_session()` 양쪽에서 `send_overseas_order(price=0.0)` 하드코딩
+- `price=0` → `ORD_DVSN="01"` (시장가) 전송 → KIS VTS 거부
+- Fix #147에서 이미 `current_price`를 올바르게 계산했으나 주문 시 미사용
+
+**구현 결과:**
+- `src/main.py`: 두 곳에서 `price=0.0` → `price=current_price`/`price=stock_data["current_price"]`
+- `tests/test_main.py`: 회귀 테스트 `test_overseas_buy_order_uses_limit_price` 추가
+
+**최종 확인 로그:**
+```
+Order result: 모의투자 매수주문이 완료 되었습니다.  ✓
+```
+
+**이슈/PR:** #149, #150

src/broker/overseas.py

@@ -25,6 +25,10 @@ _RANKING_EXCHANGE_MAP: dict[str, str] = {
     "TSE": "TSE",
 }
 
+# Price inquiry API (HHDFS00000300) uses the same short exchange codes as rankings.
+# NASD → NAS, NYSE → NYS, AMEX → AMS (confirmed: AMEX returns empty, AMS returns price).
+_PRICE_EXCHANGE_MAP: dict[str, str] = _RANKING_EXCHANGE_MAP
+
 
 class OverseasBroker:
     """KIS Overseas Stock API wrapper that reuses KISBroker infrastructure."""
@@ -58,9 +62,11 @@ class OverseasBroker:
         session = self._broker._get_session()
 
         headers = await self._broker._auth_headers("HHDFS00000300")
+        # Map internal exchange codes to the short form expected by the price API.
+        price_excd = _PRICE_EXCHANGE_MAP.get(exchange_code, exchange_code)
         params = {
             "AUTH": "",
-            "EXCD": exchange_code,
+            "EXCD": price_excd,
             "SYMB": stock_code,
         }
         url = f"{self._broker._base_url}/uapi/overseas-price/v1/quotations/price"

src/config.py

@@ -55,6 +55,11 @@ class Settings(BaseSettings):
     # Trading mode
     MODE: str = Field(default="paper", pattern="^(paper|live)$")
 
+    # Simulated USD cash for VTS (paper) overseas trading.
+    # KIS VTS overseas balance API returns errors for most accounts.
+    # This value is used as a fallback when the balance API returns 0 in paper mode.
+    PAPER_OVERSEAS_CASH: float = Field(default=50000.0, ge=0.0)
+
     # Trading frequency mode (daily = batch API calls, realtime = per-stock calls)
     TRADE_MODE: str = Field(default="daily", pattern="^(daily|realtime)$")
     DAILY_SESSIONS: int = Field(default=4, ge=1, le=10)

src/main.py

@@ -239,10 +239,33 @@ async def trading_cycle(
         total_cash = safe_float(balance_info.get("frcr_dncl_amt_2", "0") or "0")
         purchase_total = safe_float(balance_info.get("frcr_buy_amt_smtl", "0") or "0")
 
+        # VTS (paper trading) overseas balance API often returns 0 or errors.
+        # Fall back to configured paper cash so BUY orders can be sized.
+        if total_cash <= 0 and settings and settings.PAPER_OVERSEAS_CASH > 0:
+            logger.debug(
+                "Overseas cash balance is 0 for %s; using paper fallback %.2f",
+                stock_code,
+                settings.PAPER_OVERSEAS_CASH,
+            )
+            total_cash = settings.PAPER_OVERSEAS_CASH
+
         current_price = safe_float(price_data.get("output", {}).get("last", "0"))
         foreigner_net = 0.0  # Not available for overseas
         price_change_pct = safe_float(price_data.get("output", {}).get("rate", "0"))
 
+        # Price API may return 0/empty for certain VTS exchange codes.
+        # Fall back to the scanner candidate's price so order sizing still works.
+        if current_price <= 0:
+            market_candidates_lookup = scan_candidates.get(market.code, {})
+            cand_lookup = market_candidates_lookup.get(stock_code)
+            if cand_lookup and cand_lookup.price > 0:
+                current_price = cand_lookup.price
+                logger.debug(
+                    "Price API returned 0 for %s; using scanner price %.4f",
+                    stock_code,
+                    current_price,
+                )
+
     # Calculate daily P&L %
     pnl_pct = (
         ((total_eval - purchase_total) / purchase_total * 100)
@@ -487,7 +510,7 @@ async def trading_cycle(
                 stock_code=stock_code,
                 order_type=decision.action,
                 quantity=quantity,
-                price=0.0,  # market order
+                price=current_price,  # limit order — KIS VTS rejects market orders
             )
         logger.info("Order result: %s", result.get("msg1", "OK"))
 
@@ -692,6 +715,16 @@ async def run_daily_session(
                     price_change_pct = safe_float(
                         price_data.get("output", {}).get("rate", "0")
                     )
+                    # Fall back to scanner candidate price if API returns 0.
+                    if current_price <= 0:
+                        cand_lookup = candidate_map.get(stock_code)
+                        if cand_lookup and cand_lookup.price > 0:
+                            current_price = cand_lookup.price
+                            logger.debug(
+                                "Price API returned 0 for %s; using scanner price %.4f",
+                                stock_code,
+                                current_price,
+                            )
 
                 stock_data: dict[str, Any] = {
                     "stock_code": stock_code,
@@ -743,6 +776,10 @@ async def run_daily_session(
                 balance_info.get("frcr_buy_amt_smtl", "0") or "0"
             )
 
+            # VTS overseas balance API often returns 0; use paper fallback.
+            if total_cash <= 0 and settings.PAPER_OVERSEAS_CASH > 0:
+                total_cash = settings.PAPER_OVERSEAS_CASH
+
         # Calculate daily P&L %
         pnl_pct = (
             ((total_eval - purchase_total) / purchase_total * 100)
@@ -882,7 +919,7 @@ async def run_daily_session(
                             stock_code=stock_code,
                             order_type=decision.action,
                             quantity=quantity,
-                            price=0.0,  # market order
+                            price=stock_data["current_price"],  # limit order — KIS VTS rejects market orders
                         )
                     logger.info("Order result: %s", result.get("msg1", "OK"))
 

src/strategy/pre_market_planner.py

@@ -1,7 +1,8 @@
 """Pre-market planner — generates DayPlaybook via Gemini before market open.
 
 One Gemini API call per market per day. Candidates come from SmartVolatilityScanner.
-On failure, returns a defensive playbook (all HOLD, no trades).
+On failure, returns a smart rule-based fallback playbook that uses scanner signals
+(momentum/oversold) to generate BUY conditions, avoiding the all-HOLD problem.
 """
 
 from __future__ import annotations
@@ -134,7 +135,7 @@ class PreMarketPlanner:
         except Exception:
             logger.exception("Playbook generation failed for %s", market)
             if self._settings.DEFENSIVE_PLAYBOOK_ON_FAILURE:
-                return self._defensive_playbook(today, market, candidates)
+                return self._smart_fallback_playbook(today, market, candidates, self._settings)
             return self._empty_playbook(today, market)
 
     def build_cross_market_context(
@@ -470,3 +471,99 @@ class PreMarketPlanner:
                 ),
             ],
         )
+
+    @staticmethod
+    def _smart_fallback_playbook(
+        today: date,
+        market: str,
+        candidates: list[ScanCandidate],
+        settings: Settings,
+    ) -> DayPlaybook:
+        """Rule-based fallback playbook when Gemini is unavailable.
+
+        Uses scanner signals (RSI, volume_ratio) to generate meaningful BUY
+        conditions instead of the all-SELL defensive playbook.  Candidates are
+        already pre-qualified by SmartVolatilityScanner, so we trust their
+        signals and build actionable scenarios from them.
+
+        Scenario logic per candidate:
+        - momentum signal: BUY when volume_ratio exceeds scanner threshold
+        - oversold signal: BUY when RSI is below oversold threshold
+        - always: SELL stop-loss at -3.0% as guard
+        """
+        stock_playbooks = []
+        for c in candidates:
+            scenarios: list[StockScenario] = []
+
+            if c.signal == "momentum":
+                scenarios.append(
+                    StockScenario(
+                        condition=StockCondition(
+                            volume_ratio_above=settings.VOL_MULTIPLIER,
+                        ),
+                        action=ScenarioAction.BUY,
+                        confidence=80,
+                        allocation_pct=10.0,
+                        stop_loss_pct=-3.0,
+                        take_profit_pct=5.0,
+                        rationale=(
+                            f"Rule-based BUY: momentum signal, "
+                            f"volume={c.volume_ratio:.1f}x (fallback planner)"
+                        ),
+                    )
+                )
+            elif c.signal == "oversold":
+                scenarios.append(
+                    StockScenario(
+                        condition=StockCondition(
+                            rsi_below=settings.RSI_OVERSOLD_THRESHOLD,
+                        ),
+                        action=ScenarioAction.BUY,
+                        confidence=80,
+                        allocation_pct=10.0,
+                        stop_loss_pct=-3.0,
+                        take_profit_pct=5.0,
+                        rationale=(
+                            f"Rule-based BUY: oversold signal, "
+                            f"RSI={c.rsi:.0f} (fallback planner)"
+                        ),
+                    )
+                )
+
+            # Always add stop-loss guard
+            scenarios.append(
+                StockScenario(
+                    condition=StockCondition(price_change_pct_below=-3.0),
+                    action=ScenarioAction.SELL,
+                    confidence=90,
+                    stop_loss_pct=-3.0,
+                    rationale="Rule-based stop-loss (fallback planner)",
+                )
+            )
+
+            stock_playbooks.append(
+                StockPlaybook(
+                    stock_code=c.stock_code,
+                    scenarios=scenarios,
+                )
+            )
+
+        logger.info(
+            "Smart fallback playbook for %s: %d stocks with rule-based BUY/SELL conditions",
+            market,
+            len(stock_playbooks),
+        )
+        return DayPlaybook(
+            date=today,
+            market=market,
+            market_outlook=MarketOutlook.NEUTRAL,
+            default_action=ScenarioAction.HOLD,
+            stock_playbooks=stock_playbooks,
+            global_rules=[
+                GlobalRule(
+                    condition="portfolio_pnl_pct < -2.0",
+                    action=ScenarioAction.REDUCE_ALL,
+                    rationale="Defensive: reduce on loss threshold",
+                ),
+            ],
+        )

tests/test_main.py

@@ -738,6 +738,82 @@ class TestOverseasBalanceParsing:
         # Verify price API was called
         mock_overseas_broker_with_empty_price.get_overseas_price.assert_called_once()
 
+    @pytest.fixture
+    def mock_overseas_broker_with_buy_scenario(self) -> MagicMock:
+        """Create mock overseas broker that returns a valid price for BUY orders."""
+        broker = MagicMock()
+        broker.get_overseas_price = AsyncMock(
+            return_value={"output": {"last": "182.50"}}
+        )
+        broker.get_overseas_balance = AsyncMock(
+            return_value={
+                "output2": [
+                    {
+                        "frcr_evlu_tota": "100000.00",
+                        "frcr_dncl_amt_2": "50000.00",
+                        "frcr_buy_amt_smtl": "50000.00",
+                    }
+                ]
+            }
+        )
+        broker.send_overseas_order = AsyncMock(return_value={"msg1": "주문접수"})
+        return broker
+
+    @pytest.fixture
+    def mock_scenario_engine_buy(self) -> MagicMock:
+        """Create mock scenario engine that returns BUY."""
+        engine = MagicMock(spec=ScenarioEngine)
+        engine.evaluate = MagicMock(return_value=_make_buy_match("AAPL"))
+        return engine
+
+    @pytest.mark.asyncio
+    async def test_overseas_buy_order_uses_limit_price(
+        self,
+        mock_domestic_broker: MagicMock,
+        mock_overseas_broker_with_buy_scenario: MagicMock,
+        mock_scenario_engine_buy: MagicMock,
+        mock_playbook: DayPlaybook,
+        mock_risk: MagicMock,
+        mock_db: MagicMock,
+        mock_decision_logger: MagicMock,
+        mock_context_store: MagicMock,
+        mock_criticality_assessor: MagicMock,
+        mock_telegram: MagicMock,
+        mock_overseas_market: MagicMock,
+    ) -> None:
+        """Overseas BUY order must use current_price (limit), not 0 (market).
+
+        KIS VTS rejects market orders for overseas paper trading.
+        Regression test for issue #149.
+        """
+        mock_telegram.notify_trade_execution = AsyncMock()
+
+        with patch("src.main.log_trade"):
+            await trading_cycle(
+                broker=mock_domestic_broker,
+                overseas_broker=mock_overseas_broker_with_buy_scenario,
+                scenario_engine=mock_scenario_engine_buy,
+                playbook=mock_playbook,
+                risk=mock_risk,
+                db_conn=mock_db,
+                decision_logger=mock_decision_logger,
+                context_store=mock_context_store,
+                criticality_assessor=mock_criticality_assessor,
+                telegram=mock_telegram,
+                market=mock_overseas_market,
+                stock_code="AAPL",
+                scan_candidates={},
+            )
+
+        # Verify limit order was sent with actual price, not 0.0
+        mock_overseas_broker_with_buy_scenario.send_overseas_order.assert_called_once()
+        call_kwargs = mock_overseas_broker_with_buy_scenario.send_overseas_order.call_args
+        sent_price = call_kwargs[1].get("price") or call_kwargs[0][4]
+        assert sent_price == 182.5, (
+            f"Expected limit price 182.5 but got {sent_price}. "
+            "KIS VTS only accepts limit orders for overseas paper trading."
+        )
+
 
 class TestScenarioEngineIntegration:
     """Test scenario engine integration in trading_cycle."""

tests/test_overseas_broker.py

@@ -8,7 +8,7 @@ import aiohttp
 import pytest
 
 from src.broker.kis_api import KISBroker
-from src.broker.overseas import OverseasBroker, _RANKING_EXCHANGE_MAP
+from src.broker.overseas import OverseasBroker, _PRICE_EXCHANGE_MAP, _RANKING_EXCHANGE_MAP
 from src.config import Settings
 
 
@@ -302,7 +302,8 @@ class TestGetOverseasPrice:
 
         call_args = mock_session.get.call_args
         params = call_args[1]["params"]
-        assert params["EXCD"] == "NASD"
+        # NASD is mapped to NAS for the price inquiry API (same as ranking API).
+        assert params["EXCD"] == "NAS"
         assert params["SYMB"] == "AAPL"
 
     @pytest.mark.asyncio
@@ -519,3 +520,98 @@ class TestExtractRankingRows:
     def test_filters_non_dict_rows(self, overseas_broker: OverseasBroker) -> None:
         data = {"output": [{"a": 1}, "invalid", {"b": 2}]}
         assert overseas_broker._extract_ranking_rows(data) == [{"a": 1}, {"b": 2}]
+
+
+# ---------------------------------------------------------------------------
+# Price exchange code mapping
+# ---------------------------------------------------------------------------
+
+
+class TestPriceExchangeMap:
+    """Test that get_overseas_price uses the short exchange codes."""
+
+    def test_price_map_equals_ranking_map(self) -> None:
+        assert _PRICE_EXCHANGE_MAP is _RANKING_EXCHANGE_MAP
+
+    def test_nasd_maps_to_nas(self) -> None:
+        assert _PRICE_EXCHANGE_MAP["NASD"] == "NAS"
+
+    def test_amex_maps_to_ams(self) -> None:
+        assert _PRICE_EXCHANGE_MAP["AMEX"] == "AMS"
+
+    def test_nyse_maps_to_nys(self) -> None:
+        assert _PRICE_EXCHANGE_MAP["NYSE"] == "NYS"
+
+    @pytest.mark.asyncio
+    async def test_get_overseas_price_uses_mapped_excd(
+        self, overseas_broker: OverseasBroker
+    ) -> None:
+        """AMEX should be sent as AMS to the price API."""
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"output": {"last": "44.30"}})
+
+        mock_session = MagicMock()
+        mock_session.get = MagicMock(return_value=_make_async_cm(mock_resp))
+        _setup_broker_mocks(overseas_broker, mock_session)
+        overseas_broker._broker._auth_headers = AsyncMock(return_value={})
+
+        await overseas_broker.get_overseas_price("AMEX", "EWUS")
+
+        params = mock_session.get.call_args[1]["params"]
+        assert params["EXCD"] == "AMS"  # mapped, not raw "AMEX"
+        assert params["SYMB"] == "EWUS"
+
+    @pytest.mark.asyncio
+    async def test_get_overseas_price_nasd_uses_nas(
+        self, overseas_broker: OverseasBroker
+    ) -> None:
+        mock_resp = AsyncMock()
+        mock_resp.status = 200
+        mock_resp.json = AsyncMock(return_value={"output": {"last": "220.00"}})
+
+        mock_session = MagicMock()
+        mock_session.get = MagicMock(return_value=_make_async_cm(mock_resp))
+        _setup_broker_mocks(overseas_broker, mock_session)
+        overseas_broker._broker._auth_headers = AsyncMock(return_value={})
+
+        await overseas_broker.get_overseas_price("NASD", "AAPL")
+
+        params = mock_session.get.call_args[1]["params"]
+        assert params["EXCD"] == "NAS"
+
+
+# ---------------------------------------------------------------------------
+# PAPER_OVERSEAS_CASH config default
+# ---------------------------------------------------------------------------
+
+
+class TestPaperOverseasCash:
+    def test_default_value(self) -> None:
+        settings = Settings(
+            KIS_APP_KEY="x",
+            KIS_APP_SECRET="x",
+            KIS_ACCOUNT_NO="12345678-01",
+            GEMINI_API_KEY="x",
+        )
+        assert settings.PAPER_OVERSEAS_CASH == 50000.0
+
+    def test_can_be_set_via_env(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("PAPER_OVERSEAS_CASH", "100000.0")
+        settings = Settings(
+            KIS_APP_KEY="x",
+            KIS_APP_SECRET="x",
+            KIS_ACCOUNT_NO="12345678-01",
+            GEMINI_API_KEY="x",
+        )
+        assert settings.PAPER_OVERSEAS_CASH == 100000.0
+
+    def test_zero_disables_fallback(self) -> None:
+        settings = Settings(
+            KIS_APP_KEY="x",
+            KIS_APP_SECRET="x",
+            KIS_ACCOUNT_NO="12345678-01",
+            GEMINI_API_KEY="x",
+            PAPER_OVERSEAS_CASH=0.0,
+        )
+        assert settings.PAPER_OVERSEAS_CASH == 0.0

tests/test_pre_market_planner.py

@@ -164,18 +164,23 @@ class TestGeneratePlaybook:
         assert pb.market_outlook == MarketOutlook.NEUTRAL
 
     @pytest.mark.asyncio
-    async def test_gemini_failure_returns_defensive(self) -> None:
+    async def test_gemini_failure_returns_smart_fallback(self) -> None:
         planner = _make_planner()
         planner._gemini.decide = AsyncMock(side_effect=RuntimeError("API timeout"))
+        # oversold candidate (signal="oversold", rsi=28.5)
         candidates = [_candidate()]
 
         pb = await planner.generate_playbook("KR", candidates, today=date(2026, 2, 8))
 
         assert pb.default_action == ScenarioAction.HOLD
-        assert pb.market_outlook == MarketOutlook.NEUTRAL_TO_BEARISH
+        # Smart fallback uses NEUTRAL outlook (not NEUTRAL_TO_BEARISH)
+        assert pb.market_outlook == MarketOutlook.NEUTRAL
         assert pb.stock_count == 1
-        # Defensive playbook has stop-loss scenarios
-        assert pb.stock_playbooks[0].scenarios[0].action == ScenarioAction.SELL
+        # Oversold candidate → first scenario is BUY, second is SELL stop-loss
+        scenarios = pb.stock_playbooks[0].scenarios
+        assert scenarios[0].action == ScenarioAction.BUY
+        assert scenarios[0].condition.rsi_below == 30
+        assert scenarios[1].action == ScenarioAction.SELL
 
     @pytest.mark.asyncio
     async def test_gemini_failure_empty_when_defensive_disabled(self) -> None:
@@ -657,3 +662,171 @@ class TestDefensivePlaybook:
         assert pb.stock_count == 0
         assert pb.market == "US"
         assert pb.market_outlook == MarketOutlook.NEUTRAL
+
+
+# ---------------------------------------------------------------------------
+# Smart fallback playbook
+# ---------------------------------------------------------------------------
+
+
+class TestSmartFallbackPlaybook:
+    """Tests for _smart_fallback_playbook — rule-based BUY/SELL on Gemini failure."""
+
+    def _make_settings(self) -> Settings:
+        return Settings(
+            KIS_APP_KEY="test",
+            KIS_APP_SECRET="test",
+            KIS_ACCOUNT_NO="12345678-01",
+            GEMINI_API_KEY="test",
+            RSI_OVERSOLD_THRESHOLD=30,
+            VOL_MULTIPLIER=2.0,
+        )
+
+    def test_momentum_candidate_gets_buy_on_volume(self) -> None:
+        candidates = [
+            _candidate(code="CHOW", signal="momentum", volume_ratio=13.64, rsi=100.0)
+        ]
+        settings = self._make_settings()
+
+        pb = PreMarketPlanner._smart_fallback_playbook(
+            date(2026, 2, 17), "US_AMEX", candidates, settings
+        )
+
+        assert pb.stock_count == 1
+        sp = pb.stock_playbooks[0]
+        assert sp.stock_code == "CHOW"
+        # First scenario: BUY with volume_ratio_above
+        buy_sc = sp.scenarios[0]
+        assert buy_sc.action == ScenarioAction.BUY
+        assert buy_sc.condition.volume_ratio_above == 2.0
+        assert buy_sc.condition.rsi_below is None
+        assert buy_sc.confidence == 80
+        # Second scenario: stop-loss SELL
+        sell_sc = sp.scenarios[1]
+        assert sell_sc.action == ScenarioAction.SELL
+        assert sell_sc.condition.price_change_pct_below == -3.0
+
+    def test_oversold_candidate_gets_buy_on_rsi(self) -> None:
+        candidates = [
+            _candidate(code="005930", signal="oversold", rsi=22.0, volume_ratio=3.5)
+        ]
+        settings = self._make_settings()
+
+        pb = PreMarketPlanner._smart_fallback_playbook(
+            date(2026, 2, 17), "KR", candidates, settings
+        )
+
+        sp = pb.stock_playbooks[0]
+        buy_sc = sp.scenarios[0]
+        assert buy_sc.action == ScenarioAction.BUY
+        assert buy_sc.condition.rsi_below == 30
+        assert buy_sc.condition.volume_ratio_above is None
+
+    def test_all_candidates_have_stop_loss_sell(self) -> None:
+        candidates = [
+            _candidate(code="AAA", signal="momentum", volume_ratio=5.0),
+            _candidate(code="BBB", signal="oversold", rsi=25.0),
+        ]
+        settings = self._make_settings()
+
+        pb = PreMarketPlanner._smart_fallback_playbook(
+            date(2026, 2, 17), "US_NASDAQ", candidates, settings
+        )
+
+        assert pb.stock_count == 2
+        for sp in pb.stock_playbooks:
+            sell_scenarios = [s for s in sp.scenarios if s.action == ScenarioAction.SELL]
+            assert len(sell_scenarios) == 1
+            assert sell_scenarios[0].condition.price_change_pct_below == -3.0
+            assert sell_scenarios[0].condition.price_change_pct_below == -3.0
+
+    def test_market_outlook_is_neutral(self) -> None:
+        candidates = [_candidate(signal="momentum", volume_ratio=5.0)]
+        settings = self._make_settings()
+
+        pb = PreMarketPlanner._smart_fallback_playbook(
+            date(2026, 2, 17), "US_AMEX", candidates, settings
+        )
+
+        assert pb.market_outlook == MarketOutlook.NEUTRAL
+
+    def test_default_action_is_hold(self) -> None:
+        candidates = [_candidate(signal="momentum", volume_ratio=5.0)]
+        settings = self._make_settings()
+
+        pb = PreMarketPlanner._smart_fallback_playbook(
+            date(2026, 2, 17), "US_AMEX", candidates, settings
+        )
+
+        assert pb.default_action == ScenarioAction.HOLD
+
+    def test_has_global_reduce_all_rule(self) -> None:
+        candidates = [_candidate(signal="momentum", volume_ratio=5.0)]
+        settings = self._make_settings()
+
+        pb = PreMarketPlanner._smart_fallback_playbook(
+            date(2026, 2, 17), "US_AMEX", candidates, settings
+        )
+
+        assert len(pb.global_rules) == 1
+        rule = pb.global_rules[0]
+        assert rule.action == ScenarioAction.REDUCE_ALL
+        assert "portfolio_pnl_pct" in rule.condition
+
+    def test_empty_candidates_returns_empty_playbook(self) -> None:
+        settings = self._make_settings()
+
+        pb = PreMarketPlanner._smart_fallback_playbook(
+            date(2026, 2, 17), "US_AMEX", [], settings
+        )
+
+        assert pb.stock_count == 0
+
+    def test_vol_multiplier_applied_from_settings(self) -> None:
+        """VOL_MULTIPLIER=3.0 should set volume_ratio_above=3.0 for momentum."""
+        candidates = [_candidate(signal="momentum", volume_ratio=5.0)]
+        settings = self._make_settings()
+        settings = settings.model_copy(update={"VOL_MULTIPLIER": 3.0})
+
+        pb = PreMarketPlanner._smart_fallback_playbook(
+            date(2026, 2, 17), "US_AMEX", candidates, settings
+        )
+
+        buy_sc = pb.stock_playbooks[0].scenarios[0]
+        assert buy_sc.condition.volume_ratio_above == 3.0
+
+    def test_rsi_oversold_threshold_applied_from_settings(self) -> None:
+        """RSI_OVERSOLD_THRESHOLD=25 should set rsi_below=25 for oversold."""
+        candidates = [_candidate(signal="oversold", rsi=22.0)]
+        settings = self._make_settings()
+        settings = settings.model_copy(update={"RSI_OVERSOLD_THRESHOLD": 25})
+
+        pb = PreMarketPlanner._smart_fallback_playbook(
+            date(2026, 2, 17), "KR", candidates, settings
+        )
+
+        buy_sc = pb.stock_playbooks[0].scenarios[0]
+        assert buy_sc.condition.rsi_below == 25
+
+    @pytest.mark.asyncio
+    async def test_generate_playbook_uses_smart_fallback_on_gemini_error(self) -> None:
+        """generate_playbook() should use smart fallback (not defensive) on API failure."""
+        planner = _make_planner()
+        planner._gemini.decide = AsyncMock(side_effect=ConnectionError("429 quota exceeded"))
+        # momentum candidate
+        candidates = [
+            _candidate(code="CHOW", signal="momentum", volume_ratio=13.64, rsi=100.0)
+        ]
+
+        pb = await planner.generate_playbook(
+            "US_AMEX", candidates, today=date(2026, 2, 18)
+        )
+
+        # Should NOT be all-SELL defensive; should have BUY for momentum
+        assert pb.stock_count == 1
+        buy_scenarios = [
+            s for s in pb.stock_playbooks[0].scenarios
+            if s.action == ScenarioAction.BUY
+        ]
+        assert len(buy_scenarios) == 1
+        assert buy_scenarios[0].condition.volume_ratio_above == 2.0  # VOL_MULTIPLIER default