docs: restore onboarding context and clarify runtime-impact gaps

Reviewed-on: #130

README.md

@@ -1,154 +1,126 @@
 # The Ouroboros — 자가 진화형 AI 투자 시스템
 
-KIS(한국투자증권) API로 매매하고, Google Gemini로 판단하며, 자체 전략 코드를 TDD 기반으로 진화시키는 자율 주식 트레이딩 에이전트.
+KIS API 기반 자동매매 + Gemini 기반 장전 전략 생성 + 장중 로컬 시나리오 실행 + 장후 리뷰/진화 루프를 결합한 시스템입니다.
 
-## 아키텍처
+## 현재 상태 (2026-02-16)
 
-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│  KIS Broker │◄───►│    Main     │◄───►│ Gemini Brain│
-│  (매매 실행) │     │ (거래 루프)  │     │  (의사결정)  │
-└─────────────┘     └──────┬──────┘     └─────────────┘
-                           │
-                    ┌──────┴──────┐
-                    │Risk Manager │
-                    │  (안전장치)  │
-                    └──────┬──────┘
-                           │
-                    ┌──────┴──────┐
-                    │  Evolution  │
-                    │ (전략 진화)  │
-                    └─────────────┘
-```
+- V2 계획 기준 완료: **18/20**
+- 부분 완료: **1/20** (`1-7` 일부 항목)
+- 미완료: **1/20** (`4-1` Telegram 확장 명령어)
 
-## 핵심 모듈
+핵심 전환은 이미 반영되었습니다.
 
-| 모듈 | 파일 | 설명 |
-|------|------|------|
-| 설정 | `src/config.py` | Pydantic 기반 환경변수 로딩 및 타입 검증 |
-| 브로커 | `src/broker/kis_api.py` | KIS API 비동기 래퍼 (토큰 갱신, 레이트 리미터, 해시키) |
-| 두뇌 | `src/brain/gemini_client.py` | Gemini 프롬프트 구성 및 JSON 응답 파싱 |
-| 방패 | `src/core/risk_manager.py` | 서킷 브레이커 + 팻 핑거 체크 |
-| 알림 | `src/notifications/telegram_client.py` | 텔레그램 실시간 거래 알림 (선택사항) |
-| 진화 | `src/evolution/optimizer.py` | 실패 패턴 분석 → 새 전략 생성 → 테스트 → PR |
-| DB | `src/db.py` | SQLite 거래 로그 기록 |
+- 기존: 장중 `brain.decide()` 실시간 의존
+- 현재: 장전 `DayPlaybook` 생성 + 장중 `ScenarioEngine` 로컬 매칭
 
-## 안전장치
+## 핵심 구성
 
-| 규칙 | 내용 |
-|------|------|
-| 서킷 브레이커 | 일일 손실률 -3.0% 초과 시 전체 매매 중단 (`SystemExit`) |
-| 팻 핑거 방지 | 주문 금액이 보유 현금의 30% 초과 시 주문 거부 |
-| 신뢰도 임계값 | Gemini 신뢰도 80 미만이면 강제 HOLD |
-| 레이트 리미터 | Leaky Bucket 알고리즘으로 API 호출 제한 |
-| 토큰 자동 갱신 | 만료 1분 전 자동으로 Access Token 재발급 |
+- `src/main.py`: 시장 루프, 플레이북 생성/적용, EOD 집계, 리뷰/진화 연결
+- `src/strategy/`: `models`, `pre_market_planner`, `scenario_engine`, `playbook_store`
+- `src/context/`: `store`, `aggregator`, `scheduler` (L1~L7)
+- `src/evolution/daily_review.py`: 시장별 scorecard/lessons 생성
+- `src/dashboard/app.py`: FastAPI 관측 API
+- `src/notifications/telegram_client.py`: 알림 및 명령 핸들러
 
-## 빠른 시작
+## Quick Start
 
 ### 1. 환경 설정
 
 ```bash
 cp .env.example .env
-# .env 파일에 KIS API 키와 Gemini API 키 입력
 ```
 
+필수 값:
+
+- `KIS_APP_KEY`
+- `KIS_APP_SECRET`
+- `KIS_ACCOUNT_NO`
+- `GEMINI_API_KEY`
+
 ### 2. 의존성 설치
 
 ```bash
-pip install ".[dev]"
+pip install -e ".[dev]"
 ```
 
-### 3. 테스트 실행
+### 3. 테스트
 
 ```bash
-pytest -v --cov=src --cov-report=term-missing
+pytest -v --cov=src
+ruff check src/ tests/
+mypy src/ --strict
 ```
 
-### 4. 실행 (모의투자)
+## 실행
+
+### 기본 실행
 
 ```bash
 python -m src.main --mode=paper
 ```
 
-### 5. Docker 실행
+### 대시보드 포함 실행
 
 ```bash
-docker compose up -d ouroboros
+python -m src.main --mode=paper --dashboard
 ```
 
-## 텔레그램 알림 (선택사항)
+또는 환경변수:
 
-거래 실행, 서킷 브레이커 발동, 시스템 상태 등을 텔레그램으로 실시간 알림 받을 수 있습니다.
+```bash
+DASHBOARD_ENABLED=true
+DASHBOARD_HOST=127.0.0.1
+DASHBOARD_PORT=8080
+```
 
-### 빠른 설정
+## 주요 API/기능
 
-1. **봇 생성**: 텔레그램에서 [@BotFather](https://t.me/BotFather) 메시지 → `/newbot` 명령
-2. **채팅 ID 확인**: [@userinfobot](https://t.me/userinfobot) 메시지 → `/start` 명령
-3. **환경변수 설정**: `.env` 파일에 추가
-   ```bash
-   TELEGRAM_BOT_TOKEN=1234567890:ABCdefGHIjklMNOpqrsTUVwxyz
-   TELEGRAM_CHAT_ID=123456789
-   TELEGRAM_ENABLED=true
-   ```
-4. **테스트**: 봇과 대화 시작 (`/start` 전송) 후 에이전트 실행
+- 플레이북 저장: `playbooks` 테이블 (`date + market` UNIQUE)
+- 의사결정/결과 연결: `trades.decision_id` + `DecisionLogger.update_outcome()`
+- 시장별 scorecard 컨텍스트: `scorecard_KR`, `scorecard_US`
+- 컨텍스트 스케줄러: weekly/monthly/quarterly/annual/legacy + cleanup
+- 대시보드 API:
+- `/api/status`
+- `/api/playbook/{date}?market=KR`
+- `/api/scorecard/{date}?market=KR`
+- `/api/performance?market=all`
+- `/api/context/{layer}`
+- `/api/decisions?market=KR`
+- `/api/scenarios/active?market=US`
 
-**상세 문서**: [src/notifications/README.md](src/notifications/README.md)
+## 현재 갭 (코드 기준)
 
-### 알림 종류
-
-- 🟢 거래 체결 알림 (BUY/SELL + 신뢰도)
-- 🚨 서킷 브레이커 발동 (자동 거래 중단)
-- ⚠️ 팻 핑거 차단 (과도한 주문 차단)
-- ℹ️ 장 시작/종료 알림
-- 📝 시스템 시작/종료 상태
-
-**안전장치**: 알림 실패해도 거래는 계속 진행됩니다. 텔레그램 API 오류나 설정 누락이 있어도 거래 시스템은 정상 작동합니다.
+- `Issue 4-1` 미구현: `/report`, `/scenarios`, `/review`, `/dashboard` Telegram 명령 미등록
+- `Issue 1-7` 일부 미완:
+- `price_change_pct` 정규화 어댑터 명시 구현 없음
+- 영향: `price_change_pct_above/below` 조건을 사용하는 시나리오는 사실상 매칭 불가(dead path)
+- HOLD 시 별도 손절 모니터링 플래그 처리 분리 미흡
+- 시장 코드 정합성 이슈:
+- 설정 기본값은 `ENABLED_MARKETS="KR,US"`
+- 스케줄 정의는 `US_NASDAQ`, `US_NYSE` 중심
+- 영향: `get_open_markets(["KR", "US"])`에서 `US` 미정의로 US 시장이 누락될 수 있음(런타임 영향)
 
 ## 테스트
 
-35개 테스트가 TDD 방식으로 구현 전에 먼저 작성되었습니다.
+로컬 수집 기준:
 
-```
-tests/test_risk.py   — 서킷 브레이커, 팻 핑거, 통합 검증 (11개)
-tests/test_broker.py — 토큰 관리, 타임아웃, HTTP 에러, 해시키 (6개)
-tests/test_brain.py  — JSON 파싱, 신뢰도 임계값, 비정상 응답 처리 (15개)
+```bash
+pytest --collect-only -q
+# 538 tests collected
 ```
 
-## 기술 스택
+권장 검증:
 
-- **언어**: Python 3.11+ (asyncio 기반)
-- **브로커**: KIS Open API (REST)
-- **AI**: Google Gemini Pro
-- **DB**: SQLite
-- **검증**: pytest + coverage
-- **CI/CD**: GitHub Actions
-- **배포**: Docker + Docker Compose
-
-## 프로젝트 구조
-
-```
-The-Ouroboros/
-├── .github/workflows/ci.yml     # CI 파이프라인
-├── docs/
-│   ├── agents.md                # AI 에이전트 페르소나 정의
-│   └── skills.md                # 사용 가능한 도구 목록
-├── src/
-│   ├── config.py                      # Pydantic 설정
-│   ├── logging_config.py              # JSON 구조화 로깅
-│   ├── db.py                          # SQLite 거래 기록
-│   ├── main.py                        # 비동기 거래 루프
-│   ├── broker/kis_api.py              # KIS API 클라이언트
-│   ├── brain/gemini_client.py         # Gemini 의사결정 엔진
-│   ├── core/risk_manager.py           # 리스크 관리
-│   ├── notifications/telegram_client.py # 텔레그램 알림
-│   ├── evolution/optimizer.py         # 전략 진화 엔진
-│   └── strategies/base.py             # 전략 베이스 클래스
-├── tests/                       # TDD 테스트 스위트
-├── Dockerfile                   # 멀티스테이지 빌드
-├── docker-compose.yml           # 서비스 오케스트레이션
-└── pyproject.toml               # 의존성 및 도구 설정
+```bash
+pytest -v --cov=src
+ruff check src/ tests/
+mypy src/ --strict
 ```
 
-## 라이선스
+## 문서
 
-이 프로젝트의 라이선스는 [LICENSE](LICENSE) 파일을 참조하세요.
+- 아키텍처: `docs/architecture.md`
+- 컨텍스트 트리: `docs/context-tree.md`
+- 워크플로우: `docs/workflow.md`
+- 요구사항 로그: `docs/requirements-log.md`
+- 명령 레퍼런스: `docs/commands.md`

docs/architecture.md

@@ -2,342 +2,140 @@
 
 ## Overview
 
-Self-evolving AI trading agent for global stock markets via KIS (Korea Investment & Securities) API. The main loop in `src/main.py` orchestrates four components across multiple markets with two trading modes: daily (batch API calls) or realtime (per-stock decisions).
+The Ouroboros V2는 `Proactive` 구조를 중심으로 동작합니다.
 
-## Trading Modes
+- 장전: Gemini 1회 호출로 시장별 `DayPlaybook` 생성
+- 장중: `ScenarioEngine`이 로컬 조건 매칭으로 의사결정
+- 장후: `ContextAggregator` + `DailyReviewer`로 성과 집계/교훈 생성
 
-The system supports two trading frequency modes controlled by the `TRADE_MODE` environment variable:
+`main.py`가 아래 컴포넌트를 오케스트레이션합니다.
 
-### Daily Mode (default)
+- `KISBroker` / `OverseasBroker`
+- `PreMarketPlanner` / `ScenarioEngine` / `PlaybookStore`
+- `ContextStore` / `ContextAggregator` / `ContextScheduler`
+- `DailyReviewer` / `EvolutionOptimizer`
+- `TelegramClient` / `TelegramCommandHandler`
 
-Optimized for Gemini Free tier API limits (20 calls/day):
+안전/운영 컴포넌트도 핵심입니다.
 
-- **Batch decisions**: 1 API call per market per session
-- **Fixed schedule**: 4 sessions per day at 6-hour intervals (configurable)
-- **API efficiency**: Processes all stocks in a market simultaneously
-- **Use case**: Free tier users, cost-conscious deployments
-- **Configuration**:
-  ```bash
-  TRADE_MODE=daily
-  DAILY_SESSIONS=4        # Sessions per day (1-10)
-  SESSION_INTERVAL_HOURS=6  # Hours between sessions (1-24)
-  ```
+- `RiskManager`: circuit breaker, fat-finger 검증
+- `PriorityTaskQueue` + `CriticalityAssessor`: 우선순위/지연 제어
 
-**Example**: With 2 markets (US, KR) and 4 sessions/day = 8 API calls/day (within 20 call limit)
+## Market Scope
 
-### Realtime Mode
+V2 기본 설정은 `ENABLED_MARKETS="KR,US"` 입니다.
 
-High-frequency trading with individual stock analysis:
+현재 코드 기준 주의점(런타임 영향):
 
-- **Per-stock decisions**: 1 API call per stock per cycle
-- **60-second interval**: Continuous monitoring
-- **Use case**: Production deployments with Gemini paid tier
-- **Configuration**:
-  ```bash
-  TRADE_MODE=realtime
-  ```
+- 설정은 `KR,US`를 기본값으로 사용
+- 스케줄 레이어(`src/markets/schedule.py`)는 `US_NASDAQ`, `US_NYSE` 구조를 아직 유지
+- `US` 코드가 스케줄에 직접 정의되지 않아 US 시장 누락 가능성이 있음
 
-**Note**: Realtime mode requires Gemini API subscription due to high call volume.
+## Decision Flow
 
-## Core Components
+### 1) Pre-market
 
-### 1. Broker (`src/broker/`)
+1. `SmartVolatilityScanner.scan()`으로 후보 종목 수집
+2. `PreMarketPlanner.generate_playbook(market, candidates)` 호출
+3. 결과를 `PlaybookStore.save()`로 DB 저장
+4. 실패 시 empty/defensive playbook 사용
 
-**KISBroker** (`kis_api.py`) — Async KIS API client for domestic Korean market
+### 2) In-market
 
-- Automatic OAuth token refresh (valid for 24 hours)
-- Leaky-bucket rate limiter (10 requests per second)
-- POST body hash-key signing for order authentication
-- Custom SSL context with disabled hostname verification for VTS (virtual trading) endpoint due to known certificate mismatch
+1. 시장 데이터 + 스캐너 메트릭(`rsi`, `volume_ratio`) 구성
+2. `ScenarioEngine.evaluate(playbook, stock_code, market_data, portfolio_data)`
+3. `TradeDecision` 변환 후 주문/로그/알림 처리
+4. `decision_logs`와 `trades`를 `decision_id`로 연결
 
-**OverseasBroker** (`overseas.py`) — KIS overseas stock API wrapper
+### 3) End-of-day
 
-- Reuses KISBroker infrastructure (session, token, rate limiter) via composition
-- Supports 9 global markets: US (NASDAQ/NYSE/AMEX), Japan, Hong Kong, China (Shanghai/Shenzhen), Vietnam (Hanoi/HCM)
-- Different API endpoints for overseas price/balance/order operations
+1. `ContextAggregator.aggregate_daily_from_trades(date, market)`
+2. `DailyReviewer.generate_scorecard(date, market)`
+3. `store_scorecard_in_context()`로 `scorecard_{market}` 저장
+4. `generate_lessons()`로 장후 교훈 생성
+5. (US 종료 시) `EvolutionOptimizer.evolve()` 실행
 
-**Market Schedule** (`src/markets/schedule.py`) — Timezone-aware market management
+## Risk Policy
 
-- `MarketInfo` dataclass with timezone, trading hours, lunch breaks
-- Automatic DST handling via `zoneinfo.ZoneInfo`
-- `is_market_open()` checks weekends, trading hours, lunch breaks
-- `get_open_markets()` returns currently active markets
-- `get_next_market_open()` finds next market to open and when
+- `RiskManager`는 주문 전 검증을 강제합니다.
+- circuit breaker: 손실 임계치 하회 시 거래 중단
+- fat-finger: 주문 금액 과대 시 주문 차단
+- 실패 시 알림은 보내되, 예외 처리로 루프 안정성 유지
 
-**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
+## Error Handling Strategy
 
-### 2. Analysis (`src/analysis/`)
+- API 호출 실패: 재시도(지수 백오프) 후 종목/사이클 스킵
+- 시나리오/플래너 실패: empty 또는 defensive playbook으로 안전 폴백
+- Telegram 실패: warning 로깅 후 거래 루프 지속
+- 대시보드 스레드 실패: warning 로깅 후 메인 트레이딩 루프와 분리 유지
 
-**VolatilityAnalyzer** (`volatility.py`) — Technical indicator calculations
+## Configuration Reference
 
-- 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
-
-- Constructs structured prompts from market data
-- Parses JSON responses into `TradeDecision` objects (`action`, `confidence`, `rationale`)
-- Forces HOLD when confidence < threshold (default 80)
-- Falls back to safe HOLD on any parse/API error
-- Handles markdown-wrapped JSON, malformed responses, invalid actions
-
-### 4. Risk Manager (`src/core/risk_manager.py`)
-
-**RiskManager** — Safety circuit breaker and order validation
-
-⚠️ **READ-ONLY by policy** (see [`docs/agents.md`](./agents.md))
-
-- **Circuit Breaker**: Halts all trading via `SystemExit` when daily P&L drops below -3.0%
-  - Threshold may only be made stricter, never relaxed
-  - Calculated as `(total_eval - purchase_total) / purchase_total * 100`
-- **Fat-Finger Protection**: Rejects orders exceeding 30% of available cash
-  - Must always be enforced, cannot be disabled
-
-### 5. Notifications (`src/notifications/telegram_client.py`)
-
-**TelegramClient** — Real-time event notifications via Telegram Bot API
-
-- Sends alerts for trades, circuit breakers, fat-finger rejections, system events
-- Non-blocking: failures are logged but never crash trading
-- Rate-limited: 1 message/second default to respect Telegram API limits
-- Auto-disabled when credentials missing
-- Gracefully handles API errors, network timeouts, invalid tokens
-
-**Notification Types:**
-- Trade execution (BUY/SELL with confidence)
-- Circuit breaker trips (critical alert)
-- Fat-finger protection triggers (order rejection)
-- Market open/close events
-- System startup/shutdown status
-
-**Setup:** See [src/notifications/README.md](../src/notifications/README.md) for bot creation and configuration.
-
-### 6. Evolution (`src/evolution/optimizer.py`)
-
-**StrategyOptimizer** — Self-improvement loop
-
-- Analyzes high-confidence losing trades from SQLite
-- Asks Gemini to generate new `BaseStrategy` subclasses
-- Validates generated strategies by running full pytest suite
-- Simulates PR creation for human review
-- Only activates strategies that pass all tests
-
-## Data Flow
-
-### Realtime Mode (with Smart Scanner)
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ Main Loop (60s cycle per market)                           │
-└─────────────────────────────────────────────────────────────┘
-                           │
-                           ▼
-        ┌──────────────────────────────────┐
-        │ Market Schedule Check             │
-        │ - Get open markets                │
-        │ - Filter by enabled markets       │
-        │ - Wait if all closed              │
-        └──────────────────┬────────────────┘
-                           │
-                           ▼
-        ┌──────────────────────────────────┐
-        │ 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      │
-        └──────────────────┬────────────────┘
-                           │
-                           ▼
-        ┌──────────────────────────────────┐
-        │ Calculate P&L                     │
-        │ pnl_pct = (eval - cost) / cost   │
-        └──────────────────┬────────────────┘
-                           │
-                           ▼
-        ┌──────────────────────────────────┐
-        │ Brain: Get Decision (AI)          │
-        │ - Build prompt with market data   │
-        │ - Call Gemini API                 │
-        │ - Parse JSON response             │
-        │ - Return TradeDecision            │
-        └──────────────────┬────────────────┘
-                           │
-                           ▼
-        ┌──────────────────────────────────┐
-        │ Risk Manager: Validate Order      │
-        │ - Check circuit breaker           │
-        │ - Check fat-finger limit          │
-        │ - Raise if validation fails       │
-        └──────────────────┬────────────────┘
-                           │
-                           ▼
-        ┌──────────────────────────────────┐
-        │ Broker: Execute Order             │
-        │ - Domestic: send_order()          │
-        │ - Overseas: send_overseas_order() │
-        └──────────────────┬────────────────┘
-                           │
-                           ▼
-        ┌──────────────────────────────────┐
-        │ Notifications: Send Alert         │
-        │ - Trade execution notification    │
-        │ - Non-blocking (errors logged)    │
-        │ - Rate-limited to 1/sec           │
-        └──────────────────┬────────────────┘
-                           │
-                           ▼
-        ┌──────────────────────────────────┐
-        │ Database: Log Trade               │
-        │ - SQLite (data/trades.db)         │
-        │ - Track: action, confidence,      │
-        │   rationale, market, exchange     │
-        │ - NEW: selection_context (JSON)   │
-        │   - RSI, volume_ratio, signal     │
-        │   - For Evolution optimization    │
-        └───────────────────────────────────┘
-```
-
-## Database Schema
-
-**SQLite** (`src/db.py`)
-
-```sql
-CREATE TABLE trades (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    timestamp TEXT NOT NULL,
-    stock_code TEXT NOT NULL,
-    action TEXT NOT NULL,          -- BUY | SELL | HOLD
-    confidence INTEGER NOT NULL,   -- 0-100
-    rationale TEXT,
-    quantity INTEGER,
-    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.
-    selection_context TEXT          -- JSON: {rsi, volume_ratio, signal, score}
-);
-```
-
-**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
-
-**Pydantic Settings** (`src/config.py`)
-
-Loaded from `.env` file:
-
-```bash
-# Required
-KIS_APP_KEY=your_app_key
-KIS_APP_SECRET=your_app_secret
-KIS_ACCOUNT_NO=XXXXXXXX-XX
-GEMINI_API_KEY=your_gemini_key
-
-# Optional
-MODE=paper                    # paper | live
-DB_PATH=data/trades.db
-CONFIDENCE_THRESHOLD=80
-MAX_LOSS_PCT=3.0
-MAX_ORDER_PCT=30.0
-ENABLED_MARKETS=KR,US_NASDAQ  # Comma-separated market codes
-
-# Trading Mode (API efficiency)
-TRADE_MODE=daily              # daily | realtime
-DAILY_SESSIONS=4              # Sessions per day (daily mode only)
-SESSION_INTERVAL_HOURS=6      # Hours between sessions (daily mode only)
-
-# Telegram Notifications (optional)
-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`.
-
-## Error Handling
-
-### Connection Errors (Broker API)
-- Retry with exponential backoff (2^attempt seconds)
-- Max 3 retries per stock
-- After exhaustion, skip stock and continue with next
-
-### API Quota Errors (Gemini)
-- Return safe HOLD decision with confidence=0
-- Log error but don't crash
-- Agent continues trading on next cycle
-
-### Circuit Breaker Tripped
-- Immediately halt via `SystemExit`
-- Log critical message
-- Requires manual intervention to restart
-
-### Market Closed
-- Wait until next market opens
-- Use `get_next_market_open()` to calculate wait time
-- Sleep until market open time
-
-### Telegram API Errors
-- Log warning but continue trading
-- Missing credentials → auto-disable notifications
-- Network timeout → skip notification, no retry
-- Invalid token → log error, trading unaffected
-- Rate limit exceeded → queued via rate limiter
-
-**Guarantee**: Notification failures never interrupt trading operations.
+상세 설정은 `src/config.py`를 기준으로 합니다.
+
+- 거래 모드: `TRADE_MODE`, `DAILY_SESSIONS`, `SESSION_INTERVAL_HOURS`
+- 전략: `PRE_MARKET_MINUTES`, `MAX_SCENARIOS_PER_STOCK`, `RESCAN_INTERVAL_SECONDS`
+- 시장: `ENABLED_MARKETS`
+- 대시보드: `DASHBOARD_ENABLED`, `DASHBOARD_HOST`, `DASHBOARD_PORT`
+- 알림: `TELEGRAM_*`
+
+## Context Tree
+
+레이어 전략:
+
+- `L7~L5`: 시장별 키
+- `L4~L1`: 글로벌 통합 롤업
+
+구현 포인트:
+
+- `L7` 쓰기: `volatility_{market}_{stock}` 등
+- `L6` 집계: `total_pnl_KR`, `trade_count_US` 등
+- `ContextScheduler.run_if_due()`:
+- 주간/월간/분기/연간/legacy 집계
+- 일 1회 `cleanup_expired_contexts()` 호출
+
+## Data Model (핵심)
+
+### `trades`
+
+- `market`, `exchange_code`, `selection_context`, `decision_id` 포함
+- SELL 시 `get_latest_buy_trade()`를 통해 원본 BUY `decision_id`를 찾아 결과 업데이트
+
+### `decision_logs`
+
+- 의사결정 입력/컨텍스트 스냅샷 저장
+- `outcome_pnl`, `outcome_accuracy` 업데이트 가능
+
+### `playbooks`
+
+- `UNIQUE(date, market)`
+- `status`, `token_count`, `scenario_count`, `match_count` 관리
+
+## Dashboard
+
+`src/dashboard/app.py`의 FastAPI 앱이 SQLite를 직접 조회합니다.
+
+엔드포인트:
+
+- `GET /api/status`
+- `GET /api/playbook/{date}?market=KR`
+- `GET /api/scorecard/{date}?market=KR`
+- `GET /api/performance?market=all`
+- `GET /api/context/{layer}`
+- `GET /api/decisions?market=KR`
+- `GET /api/scenarios/active?market=US`
+
+실행 통합:
+
+- CLI `--dashboard`
+- 또는 `DASHBOARD_ENABLED=true`
+- `main.py`에서 daemon thread로 uvicorn 실행
+
+## Known Gaps (2026-02-16)
+
+- `Issue 4-1` Telegram 확장 명령 미구현 (`/report`, `/scenarios`, `/review`, `/dashboard`)
+- `Issue 1-7` 일부 미완:
+- `price_change_pct` 정규화 계층 명시 미흡
+- 영향: `price_change_pct` 기반 조건은 현재 사실상 매칭되지 않음
+- HOLD 시 별도 손절 모니터링 플래그 처리 미완
+- US 스캐닝 확장(`fetch_overseas_rankings`) 미구현

docs/commands.md

@@ -1,156 +1,82 @@
 # Command Reference
 
-## Common Command Failures
-
-**Critical: Learn from failures. Never repeat the same failed command without modification.**
-
-### tea CLI (Gitea Command Line Tool)
-
-#### ❌ TTY Error - Interactive Confirmation Fails
-```bash
-~/bin/tea issues create --repo X --title "Y" --description "Z"
-# Error: huh: could not open a new TTY: open /dev/tty: no such device or address
-```
-**💡 Reason:** tea tries to open `/dev/tty` for interactive confirmation prompts, which is unavailable in non-interactive environments.
-
-**✅ Solution:** Use `YES=""` environment variable to bypass confirmation
-```bash
-YES="" ~/bin/tea issues create --repo jihoson/The-Ouroboros --title "Title" --description "Body"
-YES="" ~/bin/tea issues edit <number> --repo jihoson/The-Ouroboros --description "Updated body"
-YES="" ~/bin/tea pulls create --repo jihoson/The-Ouroboros --head feature-branch --base main --title "Title" --description "Body"
-```
-
-**📝 Notes:**
-- Always set default login: `~/bin/tea login default local`
-- Use `--repo jihoson/The-Ouroboros` when outside repo directory
-- tea is preferred over direct Gitea API calls for consistency
-
-#### ❌ Wrong Parameter Name
-```bash
-tea issues create --body "text"
-# Error: flag provided but not defined: -body
-```
-**💡 Reason:** Parameter is `--description`, not `--body`.
-
-**✅ Solution:** Use correct parameter name
-```bash
-YES="" ~/bin/tea issues create --description "text"
-```
-
-### Gitea API (Direct HTTP Calls)
-
-#### ❌ Wrong Hostname
-```bash
-curl http://gitea.local:3000/api/v1/...
-# Error: Could not resolve host: gitea.local
-```
-**💡 Reason:** Gitea instance runs on `localhost:3000`, not `gitea.local`.
-
-**✅ Solution:** Use correct hostname (but prefer tea CLI)
-```bash
-curl http://localhost:3000/api/v1/repos/jihoson/The-Ouroboros/issues \
-  -H "Authorization: token $GITEA_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"title":"...", "body":"..."}'
-```
-
-**📝 Notes:**
-- Prefer `tea` CLI over direct API calls
-- Only use curl for operations tea doesn't support
-
-### Git Commands
-
-#### ❌ User Not Configured
-```bash
-git commit -m "message"
-# Error: Author identity unknown
-```
-**💡 Reason:** Git user.name and user.email not set.
-
-**✅ Solution:** Configure git user
-```bash
-git config user.name "agentson"
-git config user.email "agentson@localhost"
-```
-
-#### ❌ Permission Denied on Push
-```bash
-git push origin branch
-# Error: User permission denied for writing
-```
-**💡 Reason:** Repository access token lacks write permissions or user lacks repo write access.
-
-**✅ Solution:**
-1. Verify user has write access to repository (admin grants this)
-2. Ensure git credential has correct token with `write:repository` scope
-3. Check remote URL uses correct authentication
-
-### Python/Pytest
-
-#### ❌ Module Import Error
-```bash
-pytest tests/test_foo.py
-# ModuleNotFoundError: No module named 'src'
-```
-**💡 Reason:** Package not installed in development mode.
-
-**✅ Solution:** Install package with dev dependencies
-```bash
-pip install -e ".[dev]"
-```
-
-#### ❌ Async Test Hangs
-```python
-async def test_something():  # Hangs forever
-    result = await async_function()
-```
-**💡 Reason:** Missing pytest-asyncio or wrong configuration.
-
-**✅ Solution:** Already configured in pyproject.toml
-```toml
-[tool.pytest.ini_options]
-asyncio_mode = "auto"
-```
-No decorator needed for async tests.
-
-## Build & Test Commands
+## Core Runtime Commands
 
 ```bash
-# Install all dependencies (production + dev)
-pip install -e ".[dev]"
-
-# Run full test suite with coverage
-pytest -v --cov=src --cov-report=term-missing
-
-# Run a single test file
-pytest tests/test_risk.py -v
-
-# Run a single test by name
-pytest tests/test_brain.py -k "test_parse_valid_json" -v
-
-# Lint
-ruff check src/ tests/
-
-# Type check (strict mode, non-blocking in CI)
-mypy src/ --strict
-
-# Run the trading agent
+# run (paper)
 python -m src.main --mode=paper
 
-# Docker
-docker compose up -d ouroboros          # Run agent
-docker compose --profile test up test   # Run tests in container
+# run with dashboard thread
+python -m src.main --mode=paper --dashboard
+
+# tests
+pytest -v --cov=src
+
+# lint
+ruff check src/ tests/
+
+# type-check
+mypy src/ --strict
 ```
 
-## Environment Setup
+## Dashboard Runtime Controls
+
+`Issue 4-3` 기준 반영:
+
+- CLI: `--dashboard`
+- ENV: `DASHBOARD_ENABLED=true`
+- Host/Port:
+- `DASHBOARD_HOST` (default `127.0.0.1`)
+- `DASHBOARD_PORT` (default `8080`)
+
+## Telegram Commands (현재 구현)
+
+`main.py` 등록 기준:
+
+- `/help`
+- `/status`
+- `/positions`
+- `/stop`
+- `/resume`
+
+## Telegram Commands (미구현 상태)
+
+V2 플랜 `Issue 4-1` 항목은 아직 미구현:
+
+- `/report [KR|US]`
+- `/scenarios [KR|US]`
+- `/review [KR|US]`
+- `/dashboard`
+
+## Gitea / tea Workflow Commands
+
+이슈 선등록 후 작업 시작:
 
 ```bash
-# Create .env file from example
-cp .env.example .env
-
-# Edit .env with your credentials
-# Required: KIS_APP_KEY, KIS_APP_SECRET, KIS_ACCOUNT_NO, GEMINI_API_KEY
-
-# Verify configuration
-python -c "from src.config import Settings; print(Settings())"
+YES="" ~/bin/tea issues create \
+  --repo jihoson/The-Ouroboros \
+  --title "..." \
+  --description "..."
 ```
+
+작업은 `worktree` 기준 권장:
+
+```bash
+git worktree add ../The-Ouroboros-issue-<N> feature/issue-<N>-<slug>
+```
+
+PR 생성:
+
+```bash
+YES="" ~/bin/tea pulls create \
+  --repo jihoson/The-Ouroboros \
+  --head feature/issue-<N>-<slug> \
+  --base main \
+  --title "..." \
+  --description "..."
+```
+
+## Known tea CLI Gotcha
+
+TTY 없는 환경에서는 `tea` 확인 프롬프트가 실패할 수 있습니다.
+항상 `YES=""`를 붙여 비대화식으로 실행하세요.

docs/context-tree.md

@@ -1,243 +1,81 @@
 # Context Tree: Multi-Layered Memory Management
 
-The context tree implements **Pillar 2** of The Ouroboros: hierarchical memory management across 7 time horizons, from real-time market data to generational trading wisdom.
+## Summary
 
-## Overview
+컨텍스트 트리는 L7(실시간)부터 L1(레거시)까지 계층화된 메모리 구조입니다.
 
-Instead of a flat memory structure, The Ouroboros maintains a **7-tier context tree** where each layer represents a different time horizon and level of abstraction:
+- L7~L5: 시장별 독립 데이터 중심
+- L4~L1: 글로벌 포트폴리오 통합 데이터
 
-```
-L1 (Legacy)      ←  Cumulative wisdom across generations
-  ↑
-L2 (Annual)      ←  Yearly performance metrics
-  ↑
-L3 (Quarterly)   ←  Quarterly strategy adjustments
-  ↑
-L4 (Monthly)     ←  Monthly portfolio rebalancing
-  ↑
-L5 (Weekly)      ←  Weekly stock selection
-  ↑
-L6 (Daily)       ←  Daily trade logs
-  ↑
-L7 (Real-time)   ←  Live market data
-```
+## Layer Policy
 
-Data flows **bottom-up**: real-time trades aggregate into daily summaries, which roll up to weekly, then monthly, quarterly, annual, and finally into permanent legacy knowledge.
+### L7_REALTIME (시장+종목 스코프)
 
-## The 7 Layers
+- 주요 키 패턴:
+- `volatility_{market}_{stock_code}`
+- `price_{market}_{stock_code}`
+- `rsi_{market}_{stock_code}`
+- `volume_ratio_{market}_{stock_code}`
 
-### L7: Real-time
-**Retention**: 7 days
-**Timeframe format**: `YYYY-MM-DD` (same-day)
-**Content**: Current positions, live quotes, orderbook snapshots, tick-by-tick volatility
+`trading_cycle()`에서 실시간으로 기록합니다.
 
-**Use cases**:
-- Immediate execution decisions
-- Stop-loss triggers
-- Real-time P&L tracking
+### L6_DAILY (시장 스코프)
 
-**Example keys**:
-- `current_position_{stock_code}`: Current holdings
-- `live_price_{stock_code}`: Latest quote
-- `volatility_5m_{stock_code}`: 5-minute rolling volatility
+EOD 집계 결과를 시장별 키로 저장합니다.
 
-### L6: Daily
-**Retention**: 90 days
-**Timeframe format**: `YYYY-MM-DD`
-**Content**: Daily trade logs, end-of-day P&L, market summaries, decision accuracy
+- `trade_count_KR`, `buys_KR`, `sells_KR`, `holds_KR`
+- `avg_confidence_US`, `total_pnl_US`, `win_rate_US`
+- scorecard 저장 키: `scorecard_KR`, `scorecard_US`
 
-**Use cases**:
-- Daily performance review
-- Identify patterns in recent trading
-- Backtest strategy adjustments
+### L5_WEEKLY
 
-**Example keys**:
-- `total_pnl`: Daily profit/loss
-- `trade_count`: Number of trades
-- `win_rate`: Percentage of profitable trades
-- `avg_confidence`: Average Gemini confidence
+L6 일일 데이터에서 시장별 주간 합계를 생성합니다.
 
-### L5: Weekly
-**Retention**: 1 year
-**Timeframe format**: `YYYY-Www` (ISO week, e.g., `2026-W06`)
-**Content**: Weekly stock selection, sector rotation, volatility regime classification
+- `weekly_pnl_KR`, `weekly_pnl_US`
+- `avg_confidence_KR`, `avg_confidence_US`
 
-**Use cases**:
-- Weekly strategy adjustment
-- Sector momentum tracking
-- Identify hot/cold markets
+### L4_MONTHLY 이상
 
-**Example keys**:
-- `weekly_pnl`: Week's total P&L
-- `top_performers`: Best-performing stocks
-- `sector_focus`: Dominant sectors
-- `avg_confidence`: Weekly average confidence
+글로벌 통합 롤업입니다.
 
-### L4: Monthly
-**Retention**: 2 years
-**Timeframe format**: `YYYY-MM`
-**Content**: Monthly portfolio rebalancing, risk exposure analysis, drawdown recovery
+- L5 → L4: `monthly_pnl`
+- L4 → L3: `quarterly_pnl`
+- L3 → L2: `annual_pnl`
+- L2 → L1: `total_pnl`, `years_traded`, `avg_annual_pnl`
 
-**Use cases**:
-- Monthly performance reporting
-- Risk exposure adjustment
-- Correlation analysis
+## Aggregation Flow
 
-**Example keys**:
-- `monthly_pnl`: Month's total P&L
-- `sharpe_ratio`: Risk-adjusted return
-- `max_drawdown`: Largest peak-to-trough decline
-- `rebalancing_notes`: Manual insights
+- EOD: `ContextAggregator.aggregate_daily_from_trades(date, market)`
+- 주기 롤업: `ContextScheduler.run_if_due()`
 
-### L3: Quarterly
-**Retention**: 3 years
-**Timeframe format**: `YYYY-Qn` (e.g., `2026-Q1`)
-**Content**: Quarterly strategy pivots, market phase detection (bull/bear/sideways), macro regime changes
+`ContextScheduler`는 다음을 처리합니다.
 
-**Use cases**:
-- Strategic pivots (e.g., growth → value)
-- Macro regime classification
-- Long-term pattern recognition
-
-**Example keys**:
-- `quarterly_pnl`: Quarter's total P&L
-- `market_phase`: Bull/Bear/Sideways
-- `strategy_adjustments`: Major changes made
-- `lessons_learned`: Key insights
-
-### L2: Annual
-**Retention**: 10 years
-**Timeframe format**: `YYYY`
-**Content**: Yearly returns, Sharpe ratio, max drawdown, win rate, strategy effectiveness
-
-**Use cases**:
-- Annual performance review
-- Multi-year trend analysis
-- Strategy benchmarking
-
-**Example keys**:
-- `annual_pnl`: Year's total P&L
-- `sharpe_ratio`: Annual risk-adjusted return
-- `win_rate`: Yearly win percentage
-- `best_strategy`: Most successful strategy
-- `worst_mistake`: Biggest lesson learned
-
-### L1: Legacy
-**Retention**: Forever
-**Timeframe format**: `LEGACY` (single timeframe)
-**Content**: Cumulative trading history, core principles, generational wisdom
-
-**Use cases**:
-- Long-term philosophy
-- Foundational rules
-- Lessons that transcend market cycles
-
-**Example keys**:
-- `total_pnl`: All-time profit/loss
-- `years_traded`: Trading longevity
-- `avg_annual_pnl`: Long-term average return
-- `core_principles`: Immutable trading rules
-- `greatest_trades`: Hall of fame
-- `never_again`: Permanent warnings
+- weekly/monthly/quarterly/annual/legacy 집계
+- 일 1회 `ContextStore.cleanup_expired_contexts()` 실행
+- 동일 날짜 중복 실행 방지(`_last_run`)
 
 ## Usage
 
-### Setting Context
-
 ```python
-from src.context import ContextLayer, ContextStore
-from src.db import init_db
+from datetime import UTC, datetime
 
-conn = init_db("data/ouroboros.db")
-store = ContextStore(conn)
-
-# Store daily P&L
-store.set_context(
-    layer=ContextLayer.L6_DAILY,
-    timeframe="2026-02-04",
-    key="total_pnl",
-    value=1234.56
-)
-
-# Store weekly insight
-store.set_context(
-    layer=ContextLayer.L5_WEEKLY,
-    timeframe="2026-W06",
-    key="top_performers",
-    value=["005930", "000660", "035720"]  # JSON-serializable
-)
-
-# Store legacy wisdom
-store.set_context(
-    layer=ContextLayer.L1_LEGACY,
-    timeframe="LEGACY",
-    key="core_principles",
-    value=[
-        "Cut losses fast",
-        "Let winners run",
-        "Never average down on losing positions"
-    ]
-)
-```
-
-### Retrieving Context
-
-```python
-# Get a specific value
-pnl = store.get_context(ContextLayer.L6_DAILY, "2026-02-04", "total_pnl")
-# Returns: 1234.56
-
-# Get all keys for a timeframe
-daily_summary = store.get_all_contexts(ContextLayer.L6_DAILY, "2026-02-04")
-# Returns: {"total_pnl": 1234.56, "trade_count": 10, "win_rate": 60.0, ...}
-
-# Get all data for a layer (any timeframe)
-all_daily = store.get_all_contexts(ContextLayer.L6_DAILY)
-# Returns: {"total_pnl": 1234.56, "trade_count": 10, ...} (latest timeframes first)
-
-# Get the latest timeframe
-latest = store.get_latest_timeframe(ContextLayer.L6_DAILY)
-# Returns: "2026-02-04"
-```
-
-### Automatic Aggregation
-
-The `ContextAggregator` rolls up data from lower to higher layers:
-
-```python
 from src.context.aggregator import ContextAggregator
+from src.context.scheduler import ContextScheduler
 
 aggregator = ContextAggregator(conn)
+scheduler = ContextScheduler(aggregator=aggregator, store=context_store)
 
-# Aggregate daily metrics from trades
-aggregator.aggregate_daily_from_trades("2026-02-04")
+# EOD market-scoped daily aggregation
+aggregator.aggregate_daily_from_trades(date="2026-02-16", market="KR")
 
-# Roll up weekly from daily
-aggregator.aggregate_weekly_from_daily("2026-W06")
-
-# Roll up all layers at once (bottom-up)
-aggregator.run_all_aggregations()
+# Run scheduled rollups when due
+scheduler.run_if_due(now=datetime.now(UTC))
 ```
 
-**Aggregation schedule** (recommended):
-- **L7 → L6**: Every midnight (daily rollup)
-- **L6 → L5**: Every Sunday (weekly rollup)
-- **L5 → L4**: First day of each month (monthly rollup)
-- **L4 → L3**: First day of quarter (quarterly rollup)
-- **L3 → L2**: January 1st (annual rollup)
-- **L2 → L1**: On demand (major milestones)
+## Retention
 
-### Context Cleanup
+`src/context/layer.py` 기준:
 
-Expired contexts are automatically deleted based on retention policies:
-
-```python
-# Manual cleanup
-deleted = store.cleanup_expired_contexts()
-# Returns: {ContextLayer.L7_REALTIME: 42, ContextLayer.L6_DAILY: 15, ...}
-```
-
-**Retention policies** (defined in `src/context/layer.py`):
 - L1: Forever
 - L2: 10 years
 - L3: 3 years
@@ -246,93 +84,8 @@ deleted = store.cleanup_expired_contexts()
 - L6: 90 days
 - L7: 7 days
 
-## Integration with Gemini Brain
+## Current Notes (2026-02-16)
 
-The context tree provides hierarchical memory for decision-making:
-
-```python
-from src.brain.gemini_client import GeminiClient
-
-# Build prompt with multi-layer context
-def build_enhanced_prompt(stock_code: str, store: ContextStore) -> str:
-    # L7: Real-time data
-    current_price = store.get_context(ContextLayer.L7_REALTIME, "2026-02-04", f"live_price_{stock_code}")
-
-    # L6: Recent daily performance
-    yesterday_pnl = store.get_context(ContextLayer.L6_DAILY, "2026-02-03", "total_pnl")
-
-    # L5: Weekly trend
-    weekly_data = store.get_all_contexts(ContextLayer.L5_WEEKLY, "2026-W06")
-
-    # L1: Core principles
-    principles = store.get_context(ContextLayer.L1_LEGACY, "LEGACY", "core_principles")
-
-    return f"""
-    Analyze {stock_code} for trading decision.
-
-    Current price: {current_price}
-    Yesterday's P&L: {yesterday_pnl}
-    This week: {weekly_data}
-
-    Core principles:
-    {chr(10).join(f'- {p}' for p in principles)}
-
-    Decision (BUY/SELL/HOLD):
-    """
-```
-
-## Database Schema
-
-```sql
--- Context storage
-CREATE TABLE contexts (
-    id INTEGER PRIMARY KEY AUTOINCREMENT,
-    layer TEXT NOT NULL,          -- L1_LEGACY, L2_ANNUAL, ..., L7_REALTIME
-    timeframe TEXT NOT NULL,      -- "LEGACY", "2026", "2026-Q1", "2026-02", "2026-W06", "2026-02-04"
-    key TEXT NOT NULL,            -- "total_pnl", "win_rate", "core_principles", etc.
-    value TEXT NOT NULL,          -- JSON-serialized value
-    created_at TEXT NOT NULL,     -- ISO 8601 timestamp
-    updated_at TEXT NOT NULL,     -- ISO 8601 timestamp
-    UNIQUE(layer, timeframe, key)
-);
-
--- Layer metadata
-CREATE TABLE context_metadata (
-    layer TEXT PRIMARY KEY,
-    description TEXT NOT NULL,
-    retention_days INTEGER,       -- NULL = keep forever
-    aggregation_source TEXT       -- Parent layer for rollup
-);
-
--- Indices for fast queries
-CREATE INDEX idx_contexts_layer ON contexts(layer);
-CREATE INDEX idx_contexts_timeframe ON contexts(timeframe);
-CREATE INDEX idx_contexts_updated ON contexts(updated_at);
-```
-
-## Best Practices
-
-1. **Write to leaf layers only** — Never manually write to L1-L5; let aggregation populate them
-2. **Aggregate regularly** — Schedule aggregation jobs to keep higher layers fresh
-3. **Query specific timeframes** — Use `get_context(layer, timeframe, key)` for precise retrieval
-4. **Clean up periodically** — Run `cleanup_expired_contexts()` weekly to free space
-5. **Preserve L1 forever** — Legacy wisdom should never expire
-6. **Use JSON-serializable values** — Store dicts, lists, strings, numbers (not custom objects)
-
-## Testing
-
-See `tests/test_context.py` for comprehensive test coverage (18 tests, 100% coverage on context modules).
-
-```bash
-pytest tests/test_context.py -v
-```
-
-## References
-
-- **Implementation**: `src/context/`
-  - `layer.py`: Layer definitions and metadata
-  - `store.py`: CRUD operations
-  - `aggregator.py`: Bottom-up aggregation logic
-- **Database**: `src/db.py` (table initialization)
-- **Tests**: `tests/test_context.py`
-- **Related**: Pillar 2 (Multi-layered Context Management)
+- L7 쓰기와 L6 시장별 집계는 `main.py`에 연결됨
+- scheduler 기반 cleanup/rollup도 연결됨
+- cross-market scorecard 조회는 `PreMarketPlanner`에서 사용 중

docs/requirements-log.md

@@ -86,3 +86,48 @@
   - Plan Consistency (필수), Safety & Constraints, Quality, Workflow 4개 카테고리
 
 **이슈/PR:** #114
+
+---
+
+## 2026-02-16
+
+### V2 진행상태 재정렬 + 문서 동기화
+
+**배경:**
+- V2 이슈 다수가 병렬로 진행되며 구현/문서 간 상태 불일치가 발생
+- 사용자 요청으로 "현재 코드 기준 사실"에 맞춘 전면 문서 갱신 필요
+
+**확인된 상태(코드 기준):**
+- 완료: 18/20
+- 부분 완료: `1-7`
+- 미완료: `4-1`
+
+**핵심 반영 사항:**
+1. 대시보드 실행 통합(`Issue 4-3`) 반영
+   - `--dashboard` 플래그
+   - `DASHBOARD_ENABLED`, `DASHBOARD_HOST`, `DASHBOARD_PORT`
+2. 컨텍스트 스케줄러 및 시장 스코프 키 정책 반영
+3. scorecard/review/evolution 연결 상태 반영
+4. 미완료 갭 명시
+   - Telegram 확장 명령어(`4-1`) 미구현
+   - `1-7` 잔여 항목(키 정규화/HOLD 손절 모니터링/US 코드 정합성)
+
+**프로세스 요구사항 강화:**
+- 모든 문서 작업도 Gitea 이슈 선등록 후 진행
+- 병렬 작업 후 상태 정합성 점검 결과를 `requirements-log`에 기록
+
+**이슈/브랜치:**
+- Issue: #131
+- Branch(worktree): `feature/issue-131-docs-v2-status-sync`
+
+### 문서 보강 2차 (리뷰 반영)
+
+**리뷰 피드백 반영:**
+- README에 Quick Start(환경설정/설치/검증) 복원
+- architecture에 RiskManager/에러 처리/설정 레퍼런스 복원
+- testing 문서에 기존 핵심 테스트 파일 설명 복원
+- 시장 코드 불일치(`KR,US` vs `US_NASDAQ/US_NYSE`)를 "런타임 영향"으로 격상 명시
+- `price_change_pct` 누락 영향(조건 dead path)을 명시
+
+**의도:**
+- V2 상태 반영과 기존 온보딩/운영 문서 가치를 동시에 유지

docs/testing.md

@@ -1,213 +1,63 @@
 # Testing Guidelines
 
-## Test Structure
+## Current Test Baseline (2026-02-16)
 
-**54 tests** across four files. `asyncio_mode = "auto"` in pyproject.toml — async tests need no special decorator.
-
-The `settings` fixture in `conftest.py` provides safe defaults with test credentials and in-memory DB.
-
-### Test Files
-
-#### `tests/test_risk.py` (11 tests)
-- Circuit breaker boundaries
-- Fat-finger edge cases
-- P&L calculation edge cases
-- Order validation logic
-
-**Example:**
-```python
-def test_circuit_breaker_exact_threshold(risk_manager):
-    """Circuit breaker should trip at exactly -3.0%."""
-    with pytest.raises(CircuitBreakerTripped):
-        risk_manager.validate_order(
-            current_pnl_pct=-3.0,
-            order_amount=1000,
-            total_cash=10000
-        )
-```
-
-#### `tests/test_broker.py` (6 tests)
-- OAuth token lifecycle
-- Rate limiting enforcement
-- Hash key generation
-- Network error handling
-- SSL context configuration
-
-**Example:**
-```python
-async def test_rate_limiter(broker):
-    """Rate limiter should delay requests to stay under 10 RPS."""
-    start = time.monotonic()
-    for _ in range(15):  # 15 requests
-        await broker._rate_limiter.acquire()
-    elapsed = time.monotonic() - start
-    assert elapsed >= 1.0  # Should take at least 1 second
-```
-
-#### `tests/test_brain.py` (18 tests)
-- Valid JSON parsing
-- Markdown-wrapped JSON handling
-- Malformed JSON fallback
-- Missing fields handling
-- Invalid action validation
-- Confidence threshold enforcement
-- Empty response handling
-- Prompt construction for different markets
-
-**Example:**
-```python
-async def test_confidence_below_threshold_forces_hold(brain):
-    """Decisions below confidence threshold should force HOLD."""
-    decision = brain.parse_response('{"action":"BUY","confidence":70,"rationale":"test"}')
-    assert decision.action == "HOLD"
-    assert decision.confidence == 70
-```
-
-#### `tests/test_market_schedule.py` (19 tests)
-- Market open/close logic
-- Timezone handling (UTC, Asia/Seoul, America/New_York, etc.)
-- DST (Daylight Saving Time) transitions
-- Weekend handling
-- Lunch break logic
-- Multiple market filtering
-- Next market open calculation
-
-**Example:**
-```python
-def test_is_market_open_during_trading_hours():
-    """Market should be open during regular trading hours."""
-    # KRX: 9:00-15:30 KST, no lunch break
-    market = MARKETS["KR"]
-    trading_time = datetime(2026, 2, 3, 10, 0, tzinfo=ZoneInfo("Asia/Seoul"))  # Monday 10:00
-    assert is_market_open(market, trading_time) is True
-```
-
-## Coverage Requirements
-
-**Minimum coverage: 80%**
-
-Check coverage:
-```bash
-pytest -v --cov=src --cov-report=term-missing
-```
-
-Expected output:
-```
-Name                          Stmts   Miss  Cover   Missing
------------------------------------------------------------
-src/brain/gemini_client.py       85      5    94%   165-169
-src/broker/kis_api.py           120     12    90%   ...
-src/core/risk_manager.py         35      2    94%   ...
-src/db.py                        25      1    96%   ...
-src/main.py                     150     80    47%   (excluded from CI)
-src/markets/schedule.py          95      3    97%   ...
------------------------------------------------------------
-TOTAL                           510     103   80%
-```
-
-**Note:** `main.py` has lower coverage as it contains the main loop which is tested via integration/manual testing.
-
-## Test Configuration
-
-### `pyproject.toml`
-```toml
-[tool.pytest.ini_options]
-asyncio_mode = "auto"
-testpaths = ["tests"]
-python_files = ["test_*.py"]
-```
-
-### `tests/conftest.py`
-```python
-@pytest.fixture
-def settings() -> Settings:
-    """Provide test settings with safe defaults."""
-    return Settings(
-        KIS_APP_KEY="test_key",
-        KIS_APP_SECRET="test_secret",
-        KIS_ACCOUNT_NO="12345678-01",
-        GEMINI_API_KEY="test_gemini_key",
-        MODE="paper",
-        DB_PATH=":memory:",  # In-memory SQLite
-        CONFIDENCE_THRESHOLD=80,
-        ENABLED_MARKETS="KR",
-    )
-```
-
-## Writing New Tests
-
-### Naming Convention
-- Test files: `test_<module>.py`
-- Test functions: `test_<feature>_<scenario>()`
-- Use descriptive names that explain what is being tested
-
-### Good Test Example
-```python
-async def test_send_order_with_market_price(broker, settings):
-    """Market orders should use price=0 and ORD_DVSN='01'."""
-    # Arrange
-    stock_code = "005930"
-    order_type = "BUY"
-    quantity = 10
-
-    # Act
-    with patch.object(broker._session, 'post') as mock_post:
-        mock_post.return_value.__aenter__.return_value.status = 200
-        mock_post.return_value.__aenter__.return_value.json = AsyncMock(
-            return_value={"rt_cd": "0", "msg1": "OK"}
-        )
-
-        await broker.send_order(stock_code, order_type, quantity, price=0)
-
-    # Assert
-    call_args = mock_post.call_args
-    body = call_args.kwargs['json']
-    assert body['ORD_DVSN'] == '01'  # Market order
-    assert body['ORD_UNPR'] == '0'   # Price 0
-```
-
-### Test Checklist
-- [ ] Test passes in isolation (`pytest tests/test_foo.py::test_bar -v`)
-- [ ] Test has clear docstring explaining what it tests
-- [ ] Arrange-Act-Assert structure
-- [ ] Uses appropriate fixtures from conftest.py
-- [ ] Mocks external dependencies (API calls, network)
-- [ ] Tests edge cases and error conditions
-- [ ] Doesn't rely on test execution order
-
-## Running Tests
+수집 기준:
 
 ```bash
-# All tests
-pytest -v
-
-# Specific file
-pytest tests/test_risk.py -v
-
-# Specific test
-pytest tests/test_brain.py::test_parse_valid_json -v
-
-# With coverage
-pytest -v --cov=src --cov-report=term-missing
-
-# Stop on first failure
-pytest -x
-
-# Verbose output with print statements
-pytest -v -s
+pytest --collect-only -q
+# 538 tests collected
 ```
 
-## CI/CD Integration
+V2 핵심 영역 테스트가 포함되어 있습니다.
 
-Tests run automatically on:
-- Every commit to feature branches
-- Every PR to main
-- Scheduled daily runs
+- `tests/test_strategy_models.py`
+- `tests/test_pre_market_planner.py`
+- `tests/test_scenario_engine.py`
+- `tests/test_playbook_store.py`
+- `tests/test_context_scheduler.py`
+- `tests/test_daily_review.py`
+- `tests/test_scorecard.py`
+- `tests/test_dashboard.py`
+- `tests/test_main.py`
 
-**Blocking conditions:**
-- Test failures → PR blocked
-- Coverage < 80% → PR blocked (warning only for main.py)
+기존 핵심 영역 테스트도 유지됩니다.
 
-**Non-blocking:**
-- `mypy --strict` errors (type hints encouraged but not enforced)
-- `ruff check` warnings (must be acknowledged)
+- `tests/test_risk.py`: circuit breaker/fat-finger 안전장치 검증
+- `tests/test_broker.py`: KIS API 호출/에러 처리/인증 흐름 검증
+- `tests/test_brain.py`: Gemini 응답 파싱/신뢰도 게이트 검증
+- `tests/test_market_schedule.py`: 시장 오픈/클로즈/타임존 로직 검증
+
+## Required Checks
+
+```bash
+pytest -v --cov=src
+ruff check src/ tests/
+mypy src/ --strict
+```
+
+## FastAPI Note
+
+대시보드 테스트(`tests/test_dashboard.py`)는 `fastapi`가 환경에 없으면 skip될 수 있습니다.
+의도된 동작이며 CI/개발환경에서 의존성 설치 여부를 확인하세요.
+
+## Targeted Smoke Commands
+
+```bash
+# dashboard integration
+pytest -q tests/test_main.py -k "dashboard"
+
+# planner/scenario/review paths
+pytest -q tests/test_pre_market_planner.py tests/test_scenario_engine.py tests/test_daily_review.py
+
+# context rollup/scheduler
+pytest -q tests/test_context.py tests/test_context_scheduler.py
+```
+
+## Review Checklist (테스트 관점)
+
+- 플랜 항목별 테스트 존재 여부 확인
+- 시장 스코프 키(`*_KR`, `*_US`) 검증 확인
+- EOD 흐름(`aggregate_daily_from_trades`, `scorecard_{market}` 저장) 검증
+- decision outcome 연결(`decision_id`) 검증
+- 대시보드 API market filter 검증

docs/workflow.md

@@ -8,8 +8,9 @@
 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)
+4. **Sync Status Docs** — Before PR, update `README.md` and relevant `docs/*.md` so implementation status/gaps are explicit
+5. **Create Pull Request** — Submit PR to `main` branch referencing the issue number
+6. **Review & Merge** — After approval, merge via PR (squash or merge commit)
 
 **Never commit directly to `main`.** This policy applies to all changes, no exceptions.
 

pyproject.toml

@@ -10,6 +10,7 @@ dependencies = [
     "google-genai>=1.0,<2",
     "scipy>=1.11,<2",
     "fastapi>=0.110,<1",
+    "uvicorn>=0.29,<1",
 ]
 
 [project.optional-dependencies]

src/config.py

@@ -83,6 +83,11 @@ class Settings(BaseSettings):
     TELEGRAM_COMMANDS_ENABLED: bool = True
     TELEGRAM_POLLING_INTERVAL: float = 1.0  # seconds
 
+    # Dashboard (optional)
+    DASHBOARD_ENABLED: bool = False
+    DASHBOARD_HOST: str = "127.0.0.1"
+    DASHBOARD_PORT: int = Field(default=8080, ge=1, le=65535)
+
     model_config = {"env_file": ".env", "env_file_encoding": "utf-8"}
 
     @property

src/main.py

@@ -10,6 +10,7 @@ import argparse
 import asyncio
 import logging
 import signal
+import threading
 from datetime import UTC, datetime
 from typing import Any
 
@@ -844,6 +845,48 @@ async def _run_evolution_loop(
         logger.warning("Evolution notification failed on %s: %s", market_date, exc)
 
 
+def _start_dashboard_server(settings: Settings) -> threading.Thread | None:
+    """Start FastAPI dashboard in a daemon thread when enabled."""
+    if not settings.DASHBOARD_ENABLED:
+        return None
+
+    def _serve() -> None:
+        try:
+            import uvicorn
+
+            from src.dashboard import create_dashboard_app
+
+            app = create_dashboard_app(settings.DB_PATH)
+            uvicorn.run(
+                app,
+                host=settings.DASHBOARD_HOST,
+                port=settings.DASHBOARD_PORT,
+                log_level="info",
+            )
+        except Exception as exc:
+            logger.warning("Dashboard server failed to start: %s", exc)
+
+    thread = threading.Thread(
+        target=_serve,
+        name="dashboard-server",
+        daemon=True,
+    )
+    thread.start()
+    logger.info(
+        "Dashboard server started at http://%s:%d",
+        settings.DASHBOARD_HOST,
+        settings.DASHBOARD_PORT,
+    )
+    return thread
+
+
+def _apply_dashboard_flag(settings: Settings, dashboard_flag: bool) -> Settings:
+    """Apply CLI dashboard flag over environment settings."""
+    if dashboard_flag and not settings.DASHBOARD_ENABLED:
+        return settings.model_copy(update={"DASHBOARD_ENABLED": True})
+    return settings
+
+
 async def run(settings: Settings) -> None:
     """Main async loop — iterate over open markets on a timer."""
     broker = KISBroker(settings)
@@ -1042,6 +1085,7 @@ async def run(settings: Settings) -> None:
         low_volatility_threshold=30.0,
     )
     priority_queue = PriorityTaskQueue(max_size=1000)
+    _start_dashboard_server(settings)
 
     # Track last scan time for each market
     last_scan_time: dict[str, float] = {}
@@ -1395,10 +1439,16 @@ def main() -> None:
         default="paper",
         help="Trading mode (default: paper)",
     )
+    parser.add_argument(
+        "--dashboard",
+        action="store_true",
+        help="Enable FastAPI dashboard server in background thread",
+    )
     args = parser.parse_args()
 
     setup_logging()
     settings = Settings(MODE=args.mode)  # type: ignore[call-arg]
+    settings = _apply_dashboard_flag(settings, args.dashboard)
     asyncio.run(run(settings))
 
 

tests/test_daily_review.py

@@ -16,6 +16,10 @@ from src.evolution.daily_review import DailyReviewer
 from src.evolution.scorecard import DailyScorecard
 from src.logging.decision_logger import DecisionLogger
 
+from datetime import UTC, datetime
+
+TODAY = datetime.now(UTC).strftime("%Y-%m-%d")
+
 
 @pytest.fixture
 def db_conn() -> sqlite3.Connection:
@@ -116,7 +120,7 @@ def test_generate_scorecard_market_scoped(
         exchange_code="NASDAQ",
     )
 
-    scorecard = reviewer.generate_scorecard("2026-02-14", "KR")
+    scorecard = reviewer.generate_scorecard(TODAY, "KR")
 
     assert scorecard.market == "KR"
     assert scorecard.total_decisions == 2
@@ -158,7 +162,7 @@ def test_generate_scorecard_top_winners_and_losers(
             decision_id=decision_id,
         )
 
-    scorecard = reviewer.generate_scorecard("2026-02-14", "KR")
+    scorecard = reviewer.generate_scorecard(TODAY, "KR")
     assert scorecard.top_winners == ["005930", "000660"]
     assert scorecard.top_losers == ["035420", "051910"]
 
@@ -167,7 +171,7 @@ def test_generate_scorecard_empty_day(
     db_conn: sqlite3.Connection, context_store: ContextStore,
 ) -> None:
     reviewer = DailyReviewer(db_conn, context_store)
-    scorecard = reviewer.generate_scorecard("2026-02-14", "KR")
+    scorecard = reviewer.generate_scorecard(TODAY, "KR")
 
     assert scorecard.total_decisions == 0
     assert scorecard.total_pnl == 0.0

tests/test_main.py

@@ -5,6 +5,7 @@ from unittest.mock import ANY, AsyncMock, MagicMock, patch
 
 import pytest
 
+from src.config import Settings
 from src.context.layer import ContextLayer
 from src.context.scheduler import ScheduleResult
 from src.core.risk_manager import CircuitBreakerTripped, FatFingerRejected
@@ -12,9 +13,11 @@ from src.db import init_db, log_trade
 from src.evolution.scorecard import DailyScorecard
 from src.logging.decision_logger import DecisionLogger
 from src.main import (
+    _apply_dashboard_flag,
     _handle_market_close,
     _run_context_scheduler,
     _run_evolution_loop,
+    _start_dashboard_server,
     safe_float,
     trading_cycle,
 )
@@ -1454,3 +1457,44 @@ async def test_run_evolution_loop_notification_error_is_ignored() -> None:
 
     optimizer.evolve.assert_called_once()
     telegram.send_message.assert_called_once()
+
+
+def test_apply_dashboard_flag_enables_dashboard() -> None:
+    settings = Settings(
+        KIS_APP_KEY="test_key",
+        KIS_APP_SECRET="test_secret",
+        KIS_ACCOUNT_NO="12345678-01",
+        GEMINI_API_KEY="test_gemini_key",
+        DASHBOARD_ENABLED=False,
+    )
+    updated = _apply_dashboard_flag(settings, dashboard_flag=True)
+    assert updated.DASHBOARD_ENABLED is True
+
+
+def test_start_dashboard_server_disabled_returns_none() -> None:
+    settings = Settings(
+        KIS_APP_KEY="test_key",
+        KIS_APP_SECRET="test_secret",
+        KIS_ACCOUNT_NO="12345678-01",
+        GEMINI_API_KEY="test_gemini_key",
+        DASHBOARD_ENABLED=False,
+    )
+    thread = _start_dashboard_server(settings)
+    assert thread is None
+
+
+def test_start_dashboard_server_enabled_starts_thread() -> None:
+    settings = Settings(
+        KIS_APP_KEY="test_key",
+        KIS_APP_SECRET="test_secret",
+        KIS_ACCOUNT_NO="12345678-01",
+        GEMINI_API_KEY="test_gemini_key",
+        DASHBOARD_ENABLED=True,
+    )
+    mock_thread = MagicMock()
+    with patch("src.main.threading.Thread", return_value=mock_thread) as mock_thread_cls:
+        thread = _start_dashboard_server(settings)
+
+    assert thread == mock_thread
+    mock_thread_cls.assert_called_once()
+    mock_thread.start.assert_called_once()