fix: use smart rule-based fallback playbook when Gemini fails (issue #145)

When gemini-2.5-flash quota is exhausted (20 RPD free tier), generate_playbook()
fell back to _defensive_playbook() which only had price_change_pct_below: -3.0 SELL
conditions — no BUY conditions — causing zero trades on US market despite scanner
finding strong momentum/oversold candidates.

Changes:
- Add _smart_fallback_playbook() that uses scanner signals to build BUY conditions:
  - momentum signal: BUY when volume_ratio_above=VOL_MULTIPLIER
  - oversold signal: BUY when rsi_below=RSI_OVERSOLD_THRESHOLD
  - always: SELL stop-loss at price_change_pct_below=-3.0
- Use _smart_fallback_playbook() instead of _defensive_playbook() on Gemini failure
- Add 10 new tests for _smart_fallback_playbook() covering momentum/oversold/empty cases
- Update existing test_gemini_failure_returns_defensive to match new behavior

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

docs/requirements-log.md

@@ -184,3 +184,20 @@
 
 **효과:**
 - 해외 시장 랭킹 스캔이 정상 동작하여 Smart Scanner가 후보 종목 탐지 가능
+
+### Gemini prompt_override 미적용 버그 수정
+
+**배경:**
+- `run_overnight` 실행 시 모든 시장에서 Playbook 생성 실패 (`JSONDecodeError`)
+- defensive playbook으로 폴백되어 모든 종목이 HOLD 처리
+
+**근본 원인:**
+- `pre_market_planner.py`가 `market_data["prompt_override"]`에 Playbook 전용 프롬프트를 넣어 `gemini.decide()` 호출
+- `gemini_client.py`의 `decide()` 메서드가 `prompt_override` 키를 전혀 확인하지 않고 항상 일반 트레이드 결정 프롬프트 생성
+- Gemini가 Playbook JSON 대신 일반 트레이드 결정을 반환하여 파싱 실패
+
+**구현 결과:**
+- `src/brain/gemini_client.py`: `decide()` 메서드에서 `prompt_override` 우선 사용 로직 추가
+- `tests/test_brain.py`: 3개 테스트 추가 (override 전달, optimization 우회, 미지정 시 기존 동작 유지)
+
+**이슈/PR:** #143

src/brain/gemini_client.py

@@ -410,8 +410,10 @@ class GeminiClient:
                     cached=True,
                 )
 
-        # Build optimized prompt
+        # Build prompt (prompt_override takes priority for callers like pre_market_planner)
-        if self._enable_optimization:
+        if "prompt_override" in market_data:
+            prompt = market_data["prompt_override"]
+        elif self._enable_optimization:
             prompt = self._optimizer.build_compressed_prompt(market_data)
         else:
             prompt = await self.build_prompt(market_data, news_sentiment)

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_brain.py

@@ -2,6 +2,10 @@
 
 from __future__ import annotations
 
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
 from src.brain.gemini_client import GeminiClient
 
 # ---------------------------------------------------------------------------
@@ -270,3 +274,97 @@ class TestBatchDecisionParsing:
 
         assert decisions["AAPL"].action == "HOLD"
         assert decisions["AAPL"].confidence == 0
+
+
+# ---------------------------------------------------------------------------
+# Prompt Override (used by pre_market_planner)
+# ---------------------------------------------------------------------------
+
+
+class TestPromptOverride:
+    """decide() must use prompt_override when present in market_data."""
+
+    @pytest.mark.asyncio
+    async def test_prompt_override_is_sent_to_gemini(self, settings):
+        """When prompt_override is in market_data, it should be used as the prompt."""
+        client = GeminiClient(settings)
+
+        custom_prompt = "You are a playbook generator. Return JSON with scenarios."
+
+        mock_response = MagicMock()
+        mock_response.text = '{"action": "HOLD", "confidence": 50, "rationale": "test"}'
+
+        with patch.object(
+            client._client.aio.models,
+            "generate_content",
+            new_callable=AsyncMock,
+            return_value=mock_response,
+        ) as mock_generate:
+            market_data = {
+                "stock_code": "PLANNER",
+                "current_price": 0,
+                "prompt_override": custom_prompt,
+            }
+            await client.decide(market_data)
+
+            # Verify the custom prompt was sent, not a built prompt
+            mock_generate.assert_called_once()
+            actual_prompt = mock_generate.call_args[1].get(
+                "contents", mock_generate.call_args[0][1] if len(mock_generate.call_args[0]) > 1 else None
+            )
+            assert actual_prompt == custom_prompt
+
+    @pytest.mark.asyncio
+    async def test_prompt_override_skips_optimization(self, settings):
+        """prompt_override should bypass prompt optimization."""
+        client = GeminiClient(settings)
+        client._enable_optimization = True
+
+        custom_prompt = "Custom playbook prompt"
+
+        mock_response = MagicMock()
+        mock_response.text = '{"action": "HOLD", "confidence": 50, "rationale": "ok"}'
+
+        with patch.object(
+            client._client.aio.models,
+            "generate_content",
+            new_callable=AsyncMock,
+            return_value=mock_response,
+        ) as mock_generate:
+            market_data = {
+                "stock_code": "PLANNER",
+                "current_price": 0,
+                "prompt_override": custom_prompt,
+            }
+            await client.decide(market_data)
+
+            actual_prompt = mock_generate.call_args[1].get(
+                "contents", mock_generate.call_args[0][1] if len(mock_generate.call_args[0]) > 1 else None
+            )
+            assert actual_prompt == custom_prompt
+
+    @pytest.mark.asyncio
+    async def test_without_prompt_override_uses_build_prompt(self, settings):
+        """Without prompt_override, decide() should use build_prompt as before."""
+        client = GeminiClient(settings)
+
+        mock_response = MagicMock()
+        mock_response.text = '{"action": "HOLD", "confidence": 50, "rationale": "ok"}'
+
+        with patch.object(
+            client._client.aio.models,
+            "generate_content",
+            new_callable=AsyncMock,
+            return_value=mock_response,
+        ) as mock_generate:
+            market_data = {
+                "stock_code": "005930",
+                "current_price": 72000,
+            }
+            await client.decide(market_data)
+
+            actual_prompt = mock_generate.call_args[1].get(
+                "contents", mock_generate.call_args[0][1] if len(mock_generate.call_args[0]) > 1 else None
+            )
+            # Should contain stock code from build_prompt, not be a custom override
+            assert "005930" in actual_prompt

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
+        # Oversold candidate → first scenario is BUY, second is SELL stop-loss
-        assert pb.stock_playbooks[0].scenarios[0].action == ScenarioAction.SELL
+        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