feat(vol_breakout): 15m 현물 롱 라이브·모니터·cron 운영 추가

vol_breakout 멀티종목 tick, vol_live HTML 모니터, 마감 봉만 저장하는 캔들 다운로드, 텔레그램 체결 알림, cron/watch 감시 스크립트 및 테스트를 포함한다. Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-29 08:31:14 +09:00
parent 8413bbd536
commit 72de8d534e
58 changed files with 6008 additions and 1286 deletions
--- a/README.md
+++ b/README.md
@@ -1,262 +1,459 @@
 # Bithumb

-빗썸 KRW 마켓 암호화폐 캔들 수집 및 **현물** 매매 전략 파이프라인.
+빗썸 KRW 마켓 암호화폐 캔들 수집 및 **현물(spot)** 매매 전략 파이프라인.

- **기본 축:** 3분봉 현물 BTC, 최근 **10년** 캔들 (`DOWNLOAD_DAYS=3650`)
- **데이터·문서 분류:** `common` (공유) · `spot` (현물)
- **현재 운영 전략:** `fractal_swing` + MTF off — paper/live tick 운영 구현 완료
-
-## 주요 기능
-
- 빗썸 Public API(v1) 분·일·주·월봉 캔들 수집 (11개 TF, 1분봉 포함)
- SQLite 공유 DB (`data/common/coins.db`) — 현물·MTF 공용
- Ground Truth(GT) 벤치마크 → 39종 인과 기법 분석 → **실거래 운영(paper/live)**
- 운영 tick: 캔들 증분 sync, 신호 tail 갱신, 슬리피지·일 체결 상한, 텔레그램 체결 알림
-
-## 요구사항
-
- Python 3.10+
- Conda 환경 `ncue` 또는 `xavis`
-
-## 설치
-
-```bash
-cd Bithumb
-conda activate ncue   # 또는 xavis
-pip install -r requirements.txt
-cp .env.example .env   # API 키·텔레그램 등 로컬 설정
-```
-
-`.env` 핵심값 (현물 3분봉·10년·fractal 운영):
-
-```env
-SYMBOL=BTC
-DB_PATH=data/common/coins.db
-DOWNLOAD_DAYS=3650
-GT_INTERVAL_MIN=3
-GT_LOOKBACK_DAYS=3650
-GT_INITIAL_CASH_KRW=200000
-GT_SIM_LOOKBACK_DAYS=1095
-OPS_TECHNIQUE_ID=fractal_swing
-OPS_MTF_ENABLED=false
-OPS_SLIPPAGE_RATE=0.0005
-OPS_DAILY_MAX_TRADES=100
-```
+- **기본 축:** 3분봉 BTC, 최근 **10년** 캔들 (`DOWNLOAD_DAYS=3650`)
+- **데이터·문서:** `data/common` (공유 DB) · `data/spot` / `docs/spot` (현물)
+- **현재 live 운영:** `fractal_swing`, MTF off, ledger + exchange reconcile + 5분 watch

 ---

-## 설계 개요
+## 목차

-### 파이프라인 단계
+1. [파이프라인 개요](#파이프라인-개요)
+2. [단계별 요약 (0~3단계)](#단계별-요약-03단계)
+3. [수익률 정리](#수익률-정리)
+4. [3단계 live 운영](#3단계-live-운영)
+5. [설치·실행](#설치실행)
+6. [폴더 구조](#폴더-구조)
+7. [환경 변수](#환경-변수)
+8. [소스 모듈](#소스-모듈)
+9. [39종 인과 기법](#39종-인과-기법)
+10. [변경 이력](#변경-이력)
+
+---
+
+## 파이프라인 개요
+
+```mermaid
+flowchart LR
+    A[common<br/>캔들 수집] --> B[0단계 GT]
+    B --> C[1단계 GT sim]
+    C --> D[2단계 39종 기법]
+    D --> E[3단계 paper/live]
+    F[watch 5분] -.->|감시·조치| E
+```

 | 단계 | 목적 | 미래 데이터 | 실거래 |
 |------|------|-------------|--------|
-| **common** | 캔들 DB 구축 | — | — |
+| **common** | SQLite 캔들 DB 구축·증분 갱신 | — | — |
 | **spot 0단계** | GT v3 사후 최적 타점 (정답지) | 사용 (연구용) | 불가 |
 | **spot 1단계** | GT 타점 완벽 추종 sim 상한선 | GT 자체가 사후 | 불가 |
 | **spot 2단계** | 39종 인과 기법 평가·MTF 규칙 | 미사용 | 불가 |
 | **spot 3단계** | paper/live tick 운영 | 미사용 | **가능** |

-### 현물 3단계 운영 아키텍처 (fractal_swing)
+**핵심 원칙**
+
+- 0~1단계는 **연구·벤치마크** (사후 GT 포함).
+- 2단계는 **인과 기법**만으로 GT 재현도·sim을 비교.
+- 3단계는 2단계에서 선택한 기법을 **실시간 tick**으로 체결. 백테스트와 **동일 sim 엔진**(`ground_truth/pnl.py`) 사용.
+
+---
+
+## 단계별 요약 (0~3단계)
+
+### common — 캔들 수집
+
+| 항목 | 내용 |
+|------|------|
+| 스크립트 | `scripts/00_download.py` (별칭 `00_download_candles.py`) |
+| DB | `data/common/coins.db` |
+| TF | 11개 (1,3,5,10,15,30,60,240,1440,10080,43200분) |
+| 모드 | 증분(기본) / `--full` 전체 재수집 |
+| 테이블 | `{SYMBOL}_{분}` (예: `BTC_3`, `BTC_1440`) |
+
+3단계 tick에서는 `sync_ops_candles()`가 in-process로 동일 DB에 증분 INSERT (`OPS_SYNC_CANDLES=true`).
+
+---
+
+### spot 0단계 — Ground Truth (GT) 타점
+
+**목적:** 10년 3분봉에서 **사후적으로** 도출한 “이론적 최적” 매수·매도 타점. 이후 단계의 **정답지·벤치마크**.
+
+| 스크립트 | `scripts/0_ground_truth.py` |
+|----------|----------------------------|
+| 기간 | `GT_LOOKBACK_DAYS=3650` (10년) |
+| 봉 | `GT_INTERVAL_MIN=3` |
+
+**GT v3 신호 체계**
+
+| 코드 | 유형 | 10년 GT 건수(대략) |
+|------|------|-------------------|
+| B | 스윙 저점 매수 | 944 |
+| B* | 눌림목 | 406 |
+| B^ | 돌파 | 122 |
+| Bd | 상승 다이버전스 | 115 |
+| S | 스윙 고점 매도 | 944 |
+| Sd | 하락 다이버전스 | 144 |
+
+**티어**
+
+| 티어 | 포함 신호 |
+|------|-----------|
+| v1 | B / S |
+| v2 | + B* |
+| v3 | + B^ / Bd / Sd |
+
+**산출물**
+
+- `data/spot/ground_truth/ground_truth_trades_v{1,2,3}.json`
+- `docs/spot/0_ground_truth/ground_truth_chart_v*.html`
+
+---
+
+### spot 1단계 — GT sim (수익 상한선)
+
+**목적:** GT v3 타점을 **그대로** sim했을 때 3년 수익률. “이론적 상한” 벤치마크.
+
+| 스크립트 | `scripts/1_ground_truth_sim.py` |
+|----------|--------------------------------|
+| sim 기간 | `GT_SIM_LOOKBACK_DAYS=1095` (3년) |
+| 초기 자본 | `GT_INITIAL_CASH_KRW=200,000` |
+| 엔진 | `simulate_gt_signals_pnl` (슬리피지 없음) |
+
+**산출물:** `docs/spot/1_simulation/ground_truth_chart_sim_v*.html`
+
+**참고:** GT는 사후 타점이므로 **실거래 불가**. 1단계 수익률은 “최적 타점을 보수적으로 따라갔을 때”의 기준선.
+
+---
+
+### spot 2단계 — 인과 기법 분석 (39종)
+
+**목적:** 미래 데이터 **없이** GT v3를 얼마나 재현하는지 39종 기법을 평가. 3단계 전략 선택 근거.
+
+| 순서 | 스크립트 | 산출물 |
+|------|----------|--------|
+| 2-1 | `2_run_techniques.py` | `data/spot/techniques/*.json`, `comparison_report.html` |
+| 2-2 | `2_run_causal_sim.py` | `causal_sim_report.html` |
+| 2-3 | `2_run_signal_type_align.py` | `signal_type_report.html` |
+| 2-4 | `2_run_mtf_analysis.py` | `mtf_rules_v3.json`, `mtf_correlation_report.html` |
+| 일괄 | `bash scripts/2_run_stage2_all.sh` | 위 전체 |
+
+**GT 정합 score 상위 (10년, ±480봉 허용)**
+
+| 순위 | 기법 | score | 비고 |
+|------|------|-------|------|
+| 1 | **fractal_swing** | 0.914 | buy/sell recall 100%, **현재 live 운영** |
+| 2 | pivot_swing | 0.911 | |
+| 3 | minor_swing | 0.864 | |
+| 4 | local_extrema | 0.839 | |
+| 5 | zigzag_causal | 0.776 | 스윙 특화, 저빈도 |
+| … | composite_v3 | 0.546 | leg recall 22.9% |
+
+**문서**
+
+- 설계: [`docs/spot/2_analysis/stage2_design_guide.md`](docs/spot/2_analysis/stage2_design_guide.md)
+- 결과 해석: [`docs/spot/2_analysis/stage2_final_summary.md`](docs/spot/2_analysis/stage2_final_summary.md)
+
+---
+
+### spot 3단계 — paper / live 운영
+
+**목적:** 선택 기법(`fractal_swing`)을 3분봉 tick으로 paper 또는 live 체결.
+
+| 스크립트 | 역할 |
+|----------|------|
+| `3_run_filtered_backtest.py` | 운영 조건 3년 sim |
+| `3_run_fractal_realistic_backtest.py` | 슬리피지·일 상한 시나리오 |
+| `3_render_live_chart.py` | `docs/live/` 매매 차트 |
+| `3_run_operations.py` | paper/live tick (loop 180초) |
+| `3_preflight_live.py` / `3_init_live_state.py` | live 사전 점검·상태 초기화 |
+| `3_reconcile_signals.py` | backlog inspect / execute |
+| `3_audit_ops_safety.py` | 놓침·중복 종합 점검 |
+| `3_watch_ops.py` | read-only 감시 + 불일치 조치 |
+| `3_run_watch_cron.sh` | cron 5분용 래퍼 |
+| `bash scripts/3_run_fractal_live.sh` | preflight → init → live loop |
+
+**설계:** [`docs/spot/3_operations/stage3_design_guide.md`](docs/spot/3_operations/stage3_design_guide.md)  
+(초版은 composite_v3 중심 — **현재 `.env` 기본은 fractal_swing**)
+
+---
+
+## 수익률 정리
+
+**공통 조건:** BTC · 3분봉 · sim 기간 **최근 3년(1095일)** · 초기 자본 **200,000원** · 편도 수수료 **0.05%** (`GT_TRADING_FEE_RATE`)
+
+> sim 수익률은 **과거 데이터 재생** 결과입니다. live는 슬리피지·체결 지연·유동성·운영 오류로 **달라질 수 있으며**, 특히 고빈도 전략은 슬리피지에 극도로 민감합니다.
+
+### 1단계 — GT v3 벤치마크
+
+| 항목 | 값 |
+|------|-----|
+| 3년 수익률 | **+94,154%** |
+| 최종 평가 | 약 1.89억 원 |
+| 매수/매도 체결 | 239 / 151 |
+| 의미 | 사후 최적 타점을 보수적으로 sim |
+
+### 2단계 — 인과 sim (슬리피지 0, 일 상한 없음)
+
+| 기법 | 3년 수익률 | 최종 평가(약) | 매수/매도 체결 | 일평균 매수 |
+|------|-----------|--------------|---------------|------------|
+| **fractal_swing** | **+7,560,826%** | 151억 | 56,893 / 56,892 | **~52회** |
+| pivot_swing | +4,687,495% | 94억 | 12,656 / 12,658 | ~12회 |
+| minor_swing | +286,537% | 5.7억 | 831 / 887 | ~0.8회 |
+| zigzag_causal | +92,711% | 1.86억 | 97 / 97 | ~0.09회 |
+| composite_v3 | **-97.5%** | ~5,000원 | 1,885 / 1,237 | — |
+| composite_v3 + MTF (3단계 필터) | +3.37% | — | — | — |
+
+출처: `docs/spot/2_analysis/stage2_final_summary.md`, `stage2_parity_sweep.json`
+
+### 3단계 — fractal_swing 운영 백테스트 (슬리피지 반영)
+
+| 시나리오 | 슬리피지 | 일 체결 상한 | 3년 수익률 | 매수 체결 | 비고 |
+|----------|---------|-------------|-----------|----------|------|
+| **stage2 ideal** | 0% | 없음 | **+7,560,826%** | 56,893 | 2단계와 동일 |
+| **ops_default** | 0.05% | 100 | **+1,873,140%** | 53,589 | sizing_rules 100% (cluster1) |
+| **ops + sizing 튜닝** | 0.05% | 10,000 | **+2,307,905%** | 56,773 | cluster 100% (`sizing_rules.json`) |
+| slippage 0.1% | 0.1% | 100 | **-97.5%** | 3,964 | **실거래 리스크** |
+| slippage 0.1% (상한 없음) | 0.1% | 없음 | -97.5% | 3,962 | 동일 |
+
+출처: `fractal_realistic_backtest.json`, `fractal_filtered_backtest_report.json` (2026-06-14)
+
+**해석**
+
+- 2단계 ideal 대비 ops_default는 약 **24.8%** 수준 (`fractal_ops_vs_stage2.json`) — 슬리피지·일 상한·분할 매매 반영.
+- 슬리피지 **0.05% → 0.1%**만 올려도 sim은 **-97.5%**로 붕괴 → live에서 체결가·수수료 관리가 핵심.
+- `1_tune_order_sizing.py`로 cluster별 100% sizing 튜닝 시 sim **+2,307,905%** (`sizing_rules.json` + `.env` `OPS_*_PCT=1.0`).
+
+### live vs 백테스트
+
+| 구분 | 백테스트 | live |
+|------|---------|------|
+| 실행 | 3년 일괄 재생 | 180초 tick 누적 |
+| 체결가 | 모델 슬리피지 | 빗썸 시장가 + 실제 스프레드 |
+| 신호 | 캐시+tail | 동일 파이프라인 + ledger |
+| 기대 | sim 수치 | sim **이하**가 정상 |
+
+---
+
+## 3단계 live 운영
+
+### tick 아키텍처

 ```mermaid
 flowchart TD
-    subgraph tick["3_run_operations.py tick (권장 180초)"]
-        A[sync_ops_candles<br/>전 TF 증분 INSERT] --> B[generate_raw_signals<br/>캐시 + tail 800봉 갱신]
-        B --> C[filter_signals_for_ops<br/>MTF·TrendGate 선택]
-        C --> D[OperationsRunner<br/>bar 단위 클러스터 체결]
-        D --> E{paper / live}
-        E -->|paper| F[PaperExecutor<br/>모델 슬리피지 체결]
-        E -->|live| G[LiveExecutor<br/>빗썸 시장가]
-        F --> H[TelegramNotifier<br/>체결 알림]
-        G --> H
-        H --> I[state.json + ops_report.json]
+    subgraph loop["3_run_operations.py --loop 180"]
+        A[sync_ops_candles] --> B[generate_raw_signals<br/>force_tail_refresh]
+        B --> C[filter_signals_for_ops]
+        C --> D[exchange reconcile]
+        D --> E[stale backlog 정산]
+        E --> F[ledger pending 체결]
+        F --> G[state.json + report]
    end
-    J[3_run_filtered_backtest.py] --> K[simulate_gt_signals_pnl<br/>동일 체결 규칙 3년 sim]
+    subgraph watch["3_watch_ops.py (cron 5분)"]
+        H[불일치 감지] --> I{조치}
+        I -->|lock 획득| J[remediation tick]
+        I -->|tick stale| K[loop 재시작]
+        I --> T[텔레그램]
+    end
+    L[ops.tick.lock] --- loop
+    L --- watch
 ```

-**백테스트 vs live 정합:** 슬리피지·수수료·일 체결 상한·매수 상한(`max_buy_from_cash`)·클러스터 분할이 `pnl.py` ↔ `trade_engine` ↔ `executor`에서 동일 규칙을 사용합니다.
+### 신호 누락·중복 방어 (2026-06-14)

-### 운영 전략 비교 (2단계 결론 반영)
+| 기능 | 설명 |
+|------|------|
+| **ledger pending** | `trade_history` 기준 미정산 신호 추적 (커서와 분리) |
+| **force_tail_refresh** | live에서 tail 800봉 신호 재계산 |
+| **catchup 480봉** | 최근 구간 재시도 |
+| **max_age 45분** | 과거 backlog 현재가 재체결 차단 (수수료 churn 방지) |
+| **exchange reconcile** | 거래소 done 주문 ↔ 신호 대조, **재주문 없이** 원장 반영 |
+| **ops.tick.lock** | loop·watch tick 동시 실행 방지 |
+| **watch 5분** | 불일치 시 remediation tick 또는 loop 재시작 + 텔레그램 |

-| 전략 | 3년 sim (운영 조건) | 체결 빈도 | 현재 `.env` |
-|------|---------------------|-----------|-------------|
-| **fractal_swing** (MTF off) | **+1,873,140%** (슬리피지 0.05%, 일 100회) | 일 ~50회 매수 | **기본값** |
-| fractal_swing ideal (2단계) | +7,560,826% (슬리피지 0, 상한 없음) | 일 ~52회 | 연구용 |
-| composite_v3 + MTF on | +3.37% | 낮음 | `.env.example` 주석 참고 |
+### live 시작

-상세 해석: [`docs/spot/2_analysis/stage2_final_summary.md`](docs/spot/2_analysis/stage2_final_summary.md)
+```bash
+conda activate ncue   # 또는 xavis
+export PYTHONPATH=src
+
+# 1) 백테스트 확인
+python scripts/3_run_filtered_backtest.py
+
+# 2) live (preflight + init + loop)
+bash scripts/3_run_fractal_live.sh
+
+# 또는 직접
+python scripts/3_run_operations.py --mode live --loop 180
+```
+
+### watch cron (5분)
+
+```bash
+crontab -e
+# 추가:
+*/5 * * * * /Users/dsyoon/workspace/bithumb/scripts/3_run_watch_cron.sh >> /Users/dsyoon/workspace/bithumb/data/spot/operations/watch_cron.log 2>&1
+```
+
+### vol_breakout cron (다운로드 + tick + 모니터)
+
+TRX/NEAR/WLD 15m flip 운영용. 한 번에 등록:
+
+```bash
+bash scripts/install_crontab.sh --apply
+crontab -l   # 확인
+```
+
+| cron | 주기 | 스크립트 | 로그 |
+|------|------|----------|------|
+| 캔들 증분 | 1분 | `00_run_download_cron.sh` | `data/common/download_cron.log` |
+| vol tick | 1분 | `3_run_vol_breakout_cron.sh` | `data/spot/operations/vol_breakout_cron.log` |
+| 모니터 JSON | 5분 | `3_run_vol_monitor_cron.sh` | `data/spot/operations/vol_monitor_cron.log` |
+
+- hung 프로세스: 다운로드 20분·vol tick 10분 초과 시 자동 종료 후 lock 정리 (`scripts/_cron_env.sh`)
+- Python: `coin` / `ncue` conda 우선. 다른 환경이면 `.env` 또는 crontab에 `BITHUMB_PYTHON=...` 설정
+- 모니터 UI (8766):
+  ```bash
+  bash scripts/install_vol_monitor_launchd.sh --install   # 권장 — 로그인·재부팅 후 자동 기동
+  bash scripts/3_run_vol_monitor_serve.sh                   # 수동 1회 기동
+  bash scripts/install_vol_monitor_launchd.sh --status    # 상태 확인
+  ```
+  → http://127.0.0.1:8766/vol_live_monitor.html  
+  Binance 모니터는 **8765** — 포트가 다릅니다.  
+  HTTP 서버(8766)는 **별도 터미널에서 수동 실행**:
+  ```bash
+  python scripts/3_run_vol_monitor.py
+  ```
+
+점검:
+
+```bash
+tail -f data/common/download_cron.log
+tail -f data/spot/operations/vol_breakout_cron.log
+bash scripts/00_run_download_cron.sh    # 수동 1회
+bash scripts/3_run_vol_breakout_cron.sh
+```
+
+### fractal watch 점검
+
+```bash
+python scripts/3_audit_ops_safety.py      # PASS 목표
+python scripts/3_reconcile_signals.py --dry-run   # pending 0 목표
+python scripts/3_watch_ops.py --inspect-only
+```
+
+### live 체크리스트
+
+1. `.env`: `OPS_MODE=live`, API 키, `OPS_EXCHANGE_RECONCILE=true`
+2. `3_run_filtered_backtest.py` 수익률 확인
+3. paper 1~2일 또는 소액 live 모니터링
+4. `fractal_ops_report.json` — tick duration, `ledger_pending_count`, `exchange_reconciled_count`
+5. 텔레그램 체결·WATCH 알림 확인
+
+---
+
+## 설치·실행
+
+### 요구사항
+
+- Python 3.10+
+- Conda `ncue` 또는 `xavis`
+
+### 설치
+
+```bash
+cd bithumb
+conda activate ncue
+pip install -r requirements.txt
+cp .env.example .env   # API 키·텔레그램 등
+```
+
+### 전체 파이프라인 (최초 1회)
+
+```bash
+export PYTHONPATH=src
+
+python scripts/00_download.py --full
+python scripts/0_ground_truth.py --interval 3 --days 3650 --tier all
+python scripts/1_ground_truth_sim.py --tier all
+bash scripts/2_run_stage2_all.sh
+python scripts/3_run_filtered_backtest.py
+python scripts/3_render_live_chart.py
+```
+
+### fractal 운영 (일상)
+
+```bash
+bash scripts/3_run_fractal_ops.sh          # backtest + paper loop
+python scripts/3_run_operations.py --loop 180 --mode live
+bash scripts/3_run_watch_cron.sh           # 감시 1회 (또는 cron)
+```

 ---

 ## 폴더 구조

 ```text
-Bithumb/
+bithumb/
 ├── src/bithumb/
-│   ├── api/                   # 빗썸 Public·Private REST
-│   ├── data/                  # 캔들 수집·DB·로더
-│   ├── ground_truth/          # GT 타점·sim·차트
-│   ├── techniques/            # 39종 인과 기법
-│   ├── mtf/                   # MTF 피처·필터·규칙
-│   ├── evaluation/            # 2단계 리포트·인과 sim
-│   ├── operations/            # 3단계 운영 (runner·executor·sync·backtest)
-│   └── notifications/         # 텔레그램 체결 알림
-├── scripts/                   # 단계별 CLI
-│
+│   ├── api/              # Public·Private REST
+│   ├── data/             # 캔들 수집·DB
+│   ├── ground_truth/     # GT·sim·pnl 엔진
+│   ├── techniques/       # 39종 인과 기법
+│   ├── mtf/              # MTF 필터·규칙
+│   ├── evaluation/       # 2단계 리포트
+│   ├── operations/       # runner·executor·ledger·watch·reconcile
+│   └── notifications/    # 텔레그램
+├── scripts/              # 단계별 CLI·shell
 ├── data/
-│   ├── common/coins.db        # 공유 캔들 OHLCV
-│   ├── spot/
-│   │   ├── ground_truth/      # 0단계 GT JSON
-│   │   ├── techniques/        # 2단계 기법 결과 (fractal_swing.json 등)
-│   │   ├── mtf/               # mtf_rules_v3.json
-│   │   └── operations/        # fractal_ops_state.json
-│
+│   ├── common/coins.db
+│   └── spot/
+│       ├── ground_truth/
+│       ├── techniques/
+│       ├── mtf/
+│       └── operations/   # state·sizing·lock·pid
 └── docs/
-    ├── live/                  # 운영 백테스트 매매 차트 (index.html)
+    ├── live/             # 운영 백테스트 차트
    └── spot/
-        ├── 0_ground_truth/    # GT 차트 HTML
-        ├── 1_simulation/      # 1단계 sim 차트
-        ├── 2_analysis/        # 2단계 리포트·설계 가이드
-        └── 3_operations/      # 운영·백테스트 JSON 리포트
-```
-
-테이블명: `{SYMBOL}_{인터벌분}` (예: `BTC_3`, `BTC_1440`). 인터벌: 분봉=분 숫자, 일=`1440`, 주=`10080`, 월=`43200`.
-
---
-
-## 파이프라인 실행 순서
-
-```mermaid
-flowchart LR
-    A[00_download] --> B[0_ground_truth]
-    B --> C[1_ground_truth_sim]
-    C --> D[2_run_stage2_all]
-    D --> E[3_run_operations]
-```
-
-| 순서 | 단계 | 스크립트 | 산출물 |
-|------|------|----------|--------|
-| 0 | common | `00_download.py` | `data/common/coins.db` |
-| 1 | spot 0단계 | `0_ground_truth.py` | `data/spot/ground_truth/`, `docs/spot/0_ground_truth/` |
-| 2 | spot 1단계 | `1_ground_truth_sim.py` | `docs/spot/1_simulation/` |
-| 3 | spot 2단계 | `2_run_*.py`, `2_run_stage2_all.sh` | `data/spot/techniques/`, `docs/spot/2_analysis/` |
-| 4 | spot 3단계 | `3_run_*.py`, `3_run_fractal_ops.sh` | `data/spot/operations/`, `docs/spot/3_operations/` |
-
-### 권장 명령
-
-```bash
-conda activate ncue
-export PYTHONPATH=src
-
-# common
-python scripts/00_download.py              # 증분 갱신
-python scripts/00_download.py --full         # 최초·재구축
-
-# spot 0~2단계 (분석·기법 캐시 생성)
-python scripts/0_ground_truth.py --interval 3 --days 3650 --tier all
-python scripts/1_ground_truth_sim.py --tier all
-bash scripts/2_run_stage2_all.sh
-
-# spot 3단계 — fractal_swing 운영
-python scripts/3_run_filtered_backtest.py       # 운영 조건 3년 sim 검증
-python scripts/3_render_live_chart.py           # docs/live 매매 차트
-python scripts/3_run_fractal_realistic_backtest.py  # 슬리피지 시나리오
-bash scripts/3_run_fractal_ops.sh                 # 백테스트 + paper 180초 loop
-python scripts/3_run_operations.py --loop 180 --mode live  # live (API 키 필요)
+        ├── 0_ground_truth/
+        ├── 1_simulation/
+        ├── 2_analysis/
+        └── 3_operations/
 ```

 ---

-## 단계별 상세
+## 환경 변수

-### common — 캔들 수집
+전체: `.env.example`. 카테고리별 요약.

-| 항목 | 내용 |
-|------|------|
-| DB | `data/common/coins.db` (`DB_PATH`) |
-| 증분 갱신 | DB 최신 시각 이후만 API 조회·INSERT |
-| 전체 재수집 | `--full` |
-| TF | `DOWNLOAD_INTERVALS` (기본 11개) |
+### 공통·GT

-운영 tick에서는 `sync_ops_candles()`가 subprocess 대신 **in-process** 증분 sync를 수행합니다 (`OPS_SYNC_CANDLES=true`).
+| 변수 | 설명 | 기본 |
+|------|------|------|
+| `SYMBOL` | 코인 | `BTC` |
+| `DB_PATH` | 캔들 DB | `data/common/coins.db` |
+| `DOWNLOAD_DAYS` | 수집·GT 기간(일) | `3650` |
+| `GT_INTERVAL_MIN` | GT·운영 봉(분) | `3` |
+| `GT_SIM_LOOKBACK_DAYS` | sim·백테스트(일) | `1095` |
+| `GT_INITIAL_CASH_KRW` | sim 초기 자본 | `200000` |
+| `GT_TRADING_FEE_RATE` | 편도 수수료 | `0.0005` |

-### spot 0단계 — GT 타점
+### 3단계 운영 (fractal live)

-사후 최적 매매 타점. 실거래 불가, 이후 단계의 벤치마크.
+| 변수 | 설명 | 기본 |
+|------|------|------|
+| `OPS_MODE` | `paper` / `live` | `paper` |
+| `OPS_TECHNIQUE_ID` | 기법 | `fractal_swing` |
+| `OPS_MTF_ENABLED` | MTF 필터 | `false` |
+| `OPS_SLIPPAGE_RATE` | 편도 슬리피지 | `0.0005` |
+| `OPS_DAILY_MAX_TRADES` | 일 체결 상한 | `100` (live `.env`는 10000) |
+| `OPS_CATCHUP_BARS` | catchup 봉 | `480` |
+| `OPS_LEDGER_LOOKBACK_DAYS` | ledger 스캔 | `1` |
+| `OPS_LEDGER_EXECUTE_MAX_AGE_MINUTES` | backlog API 허용 | `45` |
+| `OPS_LIVE_FORCE_TAIL_REFRESH` | live tail 재계산 | `true` |
+| `OPS_EXCHANGE_RECONCILE` | 거래소 대조 | `true` |
+| `OPS_TICK_LOCK_PATH` | tick flock | `ops.tick.lock` |
+| `OPS_LOOP_PID_FILE` | loop PID | `ops_loop.pid` |
+| `OPS_WATCH_SIGNAL_GRACE_MIN` | 감시 grace | `5` |
+| `OPS_WATCH_TICK_STALE_MIN` | tick stale → 재시작 | `12` |
+| `OPS_WATCH_AUTO_REMEDIATE` | 조치 tick | `true` |
+| `OPS_WATCH_AUTO_RESTART` | loop 재시작 | `true` |
+| `COIN_TELEGRAM_*` | 체결·WATCH 알림 | — |
+| `BITHUMB_ACCESS_KEY` / `SECRET` | live API | — |

-| 티어 | 신호 |
-|------|------|
-| v1 | 스윙 B/S |
-| v2 | + 눌림목 B* |
-| v3 | + 돌파 B^ + 다이버전스 Bd/Sd |
-
-산출: `data/spot/ground_truth/ground_truth_trades_v{1,2,3}.json`, `docs/spot/0_ground_truth/ground_truth_chart_v*.html`
-
-### spot 1단계 — GT sim
-
-GT 타점 완벽 추종 시 3년 수익 상한선. 초기 20만 원, `GT_SIM_LOOKBACK_DAYS=1095`.
-
-산출: `docs/spot/1_simulation/ground_truth_chart_sim_v*.html`
-
-### spot 2단계 — 인과 기법 분석
-
-39종 기법의 GT 정합·3년 sim·신호 유형·MTF 상관 분석.
-
-| 스크립트 | 산출물 |
-|----------|--------|
-| `2_run_techniques.py` | `data/spot/techniques/`, `comparison_report.html` |
-| `2_run_causal_sim.py` | `causal_sim_report.html`, `technique_chart_sim_*.html` |
-| `2_run_signal_type_align.py` | `signal_type_report.html` |
-| `2_run_mtf_analysis.py` | `mtf_rules_v3.json`, `mtf_correlation_report.html` |
-
-설계: [`docs/spot/2_analysis/stage2_design_guide.md`](docs/spot/2_analysis/stage2_design_guide.md)  
-결과 정리: [`docs/spot/2_analysis/stage2_final_summary.md`](docs/spot/2_analysis/stage2_final_summary.md)
-
-### spot 3단계 — fractal_swing live 운영
-
-설계 가이드: [`docs/spot/3_operations/stage3_design_guide.md`](docs/spot/3_operations/stage3_design_guide.md)  
-(가이드 초版은 composite_v3 중심 — **현재 운영 기본값은 fractal_swing**)
-
-#### 백테스트 실적 (BTC, 3년, 초기 20만원)
-
-| 조건 | 수익률 | 매수 체결 | 비고 |
-|------|--------|-----------|------|
-| 운영 백테스트 | **+1,873,140%** | ~53,500 | 슬리피지 0.05%, 일 100회, MTF off |
-| 2단계 ideal | +7,560,826% | ~56,893 | 슬리피지 0, 상한 없음 |
-
-#### 스크립트·산출물
-
-| 스크립트 | 산출물 |
-|----------|--------|
-| `3_run_filtered_backtest.py` | `fractal_filtered_backtest_report.json` |
-| `3_render_live_chart.py` | `docs/live/index.html`, `fractal_swing_ops_chart.html` |
-| `3_run_fractal_realistic_backtest.py` | `fractal_realistic_backtest.json` |
-| `3_run_operations.py` | `fractal_ops_report.json`, `fractal_ops_state.json` |
-| `3_run_fractal_ops.sh` | 백테스트 + paper 180초 loop |
-
-#### 운영 tick 동작
-
-1. **캔들 sync** — `OPS_SYNC_INTERVALS` 비우면 `DOWNLOAD_INTERVALS` 전체 TF, `db_max` 이후만 INSERT
-2. **신호** — 2단계 캐시 JSON 로드; DB 최신 봉 > 캐시 max bar 시 **tail 800봉** fractal 재계산·병합 (`OPS_SIGNAL_TAIL_BARS`)
-3. **필터** — tick당 **최신 봉** 신호만 MTF 평가 (`OPS_MTF_ENABLED=false` 시 스킵)
-4. **체결** — bar 단위 클러스터 분할, 일 `OPS_DAILY_MAX_TRADES` 상한
-5. **알림** — 체결 성공 시 텔레그램; live 실패 시 사유 포함 알림
-6. **저장** — `OPS_STATE_JSON`, `OPS_REPORT_JSON`
-
-#### live 전환 체크리스트
-
-1. `python scripts/3_run_filtered_backtest.py` → **약 +1,873,140%** 확인
-2. `.env`: `OPS_MODE=live`, `BITHUMB_ACCESS_KEY` / `BITHUMB_SECRET_KEY`
-3. `python scripts/3_run_operations.py --loop 180` (paper 1~2일 모니터링 권장)
-4. `fractal_ops_report.json` — `candle_sync`, `signal_refresh`, 체결 건수 확인
-5. 텔레그램 체결 알림 동작 확인 (`COIN_TELEGRAM_*`)
-
-**주의:** 백테스트는 3년 **일괄 재생** sim, live는 **tick 누적**. 실거래 체결가는 모델 슬리피지보다 불리할 수 있습니다.
-
-#### composite_v3 + MTF (대안 운영 프로필)
-
-`.env.example` 주석 참고:
+### composite_v3 대안 프로필

 ```env
 OPS_TECHNIQUE_ID=composite_v3
@@ -268,148 +465,46 @@ OPS_DAILY_MAX_TRADES=20

 ---

-## 환경 변수
-
-전체 목록: `.env.example`. 주요 항목만 정리합니다.
-
-### 공통·GT
-
-| 변수 | 설명 | 기본값 |
-|------|------|--------|
-| `SYMBOL` | 코인 심볼 | `BTC` |
-| `DB_PATH` | 캔들 DB | `data/common/coins.db` |
-| `DOWNLOAD_DAYS` | 수집·GT 기간(일) | `3650` |
-| `DOWNLOAD_INTERVALS` | 수집 TF 목록 | 11개 TF |
-| `GT_INTERVAL_MIN` | GT·기법·운영 기준 봉(분) | `3` |
-| `GT_LOOKBACK_DAYS` | GT·기법 lookback | `3650` |
-| `GT_SIM_LOOKBACK_DAYS` | sim·백테스트 기간 | `1095` (3년) |
-| `GT_INITIAL_CASH_KRW` | sim·paper 초기 자본 | `200000` |
-| `GT_TRADING_FEE_RATE` | 편도 수수료 | `0.0005` |
-
-### spot 3단계 운영 (fractal 기본)
-
-| 변수 | 설명 | 기본값 |
-|------|------|--------|
-| `OPS_MODE` | `paper` / `live` | `paper` |
-| `OPS_TECHNIQUE_ID` | 운영 기법 | `fractal_swing` |
-| `OPS_MTF_ENABLED` | MTF 필터 | `false` |
-| `OPS_TREND_GATE_ENABLED` | 고TF trend gate | `false` |
-| `OPS_DAILY_MAX_TRADES` | 일일 체결 상한 | `100` |
-| `OPS_MIN_ORDER_KRW` | 최소 주문(원) | `5000` |
-| `OPS_SLIPPAGE_RATE` | 편도 슬리피지 | `0.0005` (0.05%) |
-| `OPS_ORDER_INTERVAL_SEC` | live 주문 간격(초) | `0.35` |
-| `OPS_SYNC_CANDLES` | tick 캔들 증분 sync | `true` |
-| `OPS_SYNC_INTERVALS` | sync TF (비우면 전체) | 전체 |
-| `OPS_SIGNAL_TAIL_BARS` | 신호 tail 재계산 봉 | `800` |
-| `OPS_PERSIST_SIGNAL_CACHE` | tail 후 JSON 저장 | `false` |
-| `OPS_STATE_JSON` | 운영 상태 | `fractal_ops_state.json` |
-| `OPS_REPORT_JSON` | tick 리포트 | `fractal_ops_report.json` |
-| `OPS_FILTERED_BACKTEST_JSON` | 백테스트 리포트 | `fractal_filtered_backtest_report.json` |
-| `COIN_TELEGRAM_BOT_TOKEN` | 텔레그램 Bot | (비우면 알림 off) |
-| `COIN_TELEGRAM_CHAT_ID` | 텔레그램 chat ID | |
-| `OPS_TELEGRAM_ENABLED` | 체결 알림 | 토큰·chat_id 있으면 자동 on |
-| `BITHUMB_ACCESS_KEY` | live API | — |
-| `BITHUMB_SECRET_KEY` | live API | — |
-
-### 경로 변수 요약
-
-| 용도 | 변수 | 기본 경로 |
-|------|------|-----------|
-| spot GT | `GROUND_TRUTH_FILE` | `data/spot/ground_truth/...` |
-| spot 기법 | `TECHNIQUES_DIR` | `data/spot/techniques/` |
-| spot MTF | `MTF_RULES_JSON` | `data/spot/mtf/mtf_rules_v3.json` |
-| spot 운영 상태 | `OPS_STATE_JSON` | `data/spot/operations/fractal_ops_state.json` |
-| spot 운영 리포트 | `OPS_REPORT_JSON` | `docs/spot/3_operations/fractal_ops_report.json` |
-| live 차트 | `3_render_live_chart.py` | `docs/live/` |
-
---
-
-## 소스 모듈 (spot 3단계)
+## 소스 모듈

 | 모듈 | 역할 |
 |------|------|
-| `operations/runner.py` | tick 오케스트레이션 |
-| `operations/candle_sync.py` | 전 TF 증분 캔들 sync |
-| `operations/signal_pipeline.py` | 신호 생성·캐시·tail 갱신·MTF 필터 |
+| `operations/runner.py` | tick·ledger·stale·watchdog |
+| `operations/exchange_reconcile.py` | 거래소 체결 ↔ 원장 |
+| `operations/watch_ops.py` | 5분 감시·조치 |
+| `operations/ops_lock.py` | flock |
+| `operations/candle_sync.py` | 증분 캔들 sync |
+| `operations/signal_pipeline.py` | 신호 tail·MTF |
 | `operations/executor.py` | paper/live 체결 |
-| `operations/execution.py` | 슬리피지 `fill_price` |
-| `operations/trade_engine.py` | 매수·매도 사이징·포트폴리오 |
-| `operations/backtest.py` | 운영 조건 3년 sim |
-| `operations/chart.py` | `docs/live` 백테스트 차트 |
-| `operations/state_store.py` | 운영 상태 JSON |
-| `ground_truth/pnl.py` | sim 엔진 (백테스트·2단계 공용) |
-| `api/bithumb_private.py` | live 잔고·시장가 주문 |
-| `notifications/telegram.py` | 체결 텔레그램 알림 |
+| `operations/trade_engine.py` | 사이징·포트폴리오 |
+| `operations/backtest.py` | 3년 sim |
+| `ground_truth/pnl.py` | sim 엔진 (2·3단계 공용) |
+| `api/bithumb_private.py` | 잔고·주문·done 조회 |
+| `notifications/telegram.py` | 체결·오류·WATCH |

 ---

-## 현물 2단계 인과 기법 (39종)
+## 39종 인과 기법

-`src/bithumb/techniques/` — 단일 33 + 복합 6, 미래 데이터 미사용.
+`src/bithumb/techniques/` — 단일 33 + 복합 6, **미래 데이터 미사용**.

 | ID | 기법 | 유형 |
 |----|------|------|
-| `zigzag_causal` | 인과 ZigZag | 스윙 B/S |
-| `minor_swing` | 소형 스윙 하이브리드 | 하이브리드 |
-| `local_extrema` | 국소 극값 | 스윙 B/S |
-| `pivot_swing` | 피벗 스윙 | 스윙 B/S |
-| `fractal_swing` | 프랙탈 스윙 | 스윙 B/S |
-| `swing_failure` | 스윙 실패 | 스윙 B/S |
-| `donchian` | 돈치안 채널 | 스윙 B/S |
-| `ema_pullback` | EMA 눌림목 | 눌림목 B* |
-| `fib_pullback` | 피보나치 눌림목 | 눌림목 B* |
-| `support_bounce` | 지지·저항 반등 | 눌림목 B* |
-| `keltner_breakout` | Keltner 돌파 | 돌파 B^ |
-| `range_breakout` | 레인지 돌파 | 돌파 B^ |
-| `volume_breakout` | 거래량 돌파 | 돌파 B^ |
-| `bb_squeeze_breakout` | BB 스퀴즈 돌파 | 돌파 B^ |
-| `rsi_divergence` | RSI 다이버전스 | Bd/Sd |
-| `macd_divergence` | MACD 다이버전스 | Bd/Sd |
-| `obv_divergence` | OBV 다이버전스 | Bd/Sd |
-| `bb_reversal` | 볼린저 역추세 | 지표 |
-| `ma_cross` | EMA 크로스 | 지표 |
-| `rsi_swing` | RSI 스윙 | 지표 |
-| `macd_cross` | MACD 크로스 | 지표 |
-| `supertrend` | Supertrend | 추세 |
-| `adx_trend` | ADX 추세 | 추세 |
-| `ichimoku_trend` | 일목 추세 | 추세 |
-| `parabolic_sar` | Parabolic SAR | 추세 |
-| `stochastic_cross` | Stochastic 크로스 | 모멘텀 |
-| `cci_extreme` | CCI 극값 | 모멘텀 |
-| `roc_reversal` | ROC 반전 | 모멘텀 |
-| `keltner_reversal` | Keltner 역추세 | 변동성 |
-| `atr_channel` | ATR 채널 | 변동성 |
-| `pivot_points` | 피벗 포인트 | 구조 |
-| `support_resistance` | 구조적 지지·저항 | 구조 |
-| `volume_spike` | 거래량 스파이크 | 거래량 |
-| `composite_swing` | 스윙 복합 | 복합 |
-| `composite_pullback` | 눌림목 복합 | 복합 |
-| `composite_breakout` | 돌파 복합 | 복합 |
-| `composite_divergence` | 다이버전스 복합 | 복합 |
-| `composite_v3` | v3 통합 스코어링 | 복합 |
-| `composite_full` | 전체 통합 복합 | 복합 |
-
---
-
-## 구현 현황
-
-| 유형 | 단계 | 상태 |
-|------|------|------|
-| common | 캔들 수집·증분 sync | 구현됨 |
-| spot | 0~2단계 (GT·기법·MTF) | 구현됨 |
-| spot | 3단계 (fractal paper/live·백테스트·텔레그램) | **구현됨** |
+| `fractal_swing` | 프랙탈 스윙 | 스윙 (**live**) |
+| `zigzag_causal` | 인과 ZigZag | 스윙 |
+| `pivot_swing` | 피벗 스윙 | 스윙 |
+| `minor_swing` | 소형 스윙 | 하이브리드 |
+| `local_extrema` | 국소 극값 | 스윙 |
+| `composite_v3` | v3 통합 | 복합 |
+| … | (전체 39종) | `techniques/registry.py` 참고 |

 ---

 ## 변경 이력

- 2026-06-13: 프로젝트명 **Bithumb**으로 변경, 선물(futures) 파이프라인 제거
- 2026-06-13: 텔레그램 매수·매도 체결 알림 (`notifications/telegram.py`)
- 2026-06-13: `docs/live/` 운영 백테스트 매매 차트 (`3_render_live_chart.py`)
- 2026-06-13: fractal_swing live 운영 — 슬리피지·일 체결 상한·전 TF 증분 sync·신호 tail 갱신
- 2026-06-13: 운영 백테스트 **+1,873,140%** (3년, 슬리피지 0.05%, 일 100회) 검증
- 2026-06-12: `data/`·`docs/` common/spot 구조 재편
- 2026-06-12: 3단계 운영 파이프라인 초기 구현 (composite_v3 + MTF paper/live)
- 2026-06-12: 2단계 인과 기법 분석 파이프라인 완료
- 2026-06-08: Ground Truth v1/v2/v3
- 2026-06-07: 캔들 수집 모듈 초기 구현
+- **2026-06-14:** ledger pending, exchange reconcile, max_age backlog, watch 5분 감시·조치, ops.tick.lock, README 전면 갱신
+- **2026-06-13:** fractal_swing live — 슬리피지·sync·tail·텔레그램; ops_default sim **+1,873,140%**
+- **2026-06-13:** 프로젝트명 Bithumb, 선물 파이프라인 제거
+- **2026-06-12:** data/docs common·spot 구조, 2단계 39종 완료, 3단계 초기 (composite_v3)
+- **2026-06-08:** GT v1/v2/v3
+- **2026-06-07:** 캔들 수집 모듈