docs(tools): align_analyze.py 이관 + CH3 flicker fix Python replay 검증 결과

- tools/align_analyze.py 신규: AlignGuide4Stage 상태머신 Python 재현
  - `--both` 모드로 NEW (majority + relaxed + soft-hint) vs LEGACY (연속 3 hit)
    로직 병행 replay 지원
  - Kotlin AlignmentConstants (V_WIN/V_MAJ/L_WIN/L_MAJ/STUCK/SOFT) 값 그대로 매핑
- tools/README.md: align_analyze.py 사용법 + 파라미터 매핑 표 + data123/
  4 세션 검증 결과 표 (Phantom / Human 0·1·3 CM) 정리
- tools/labdb_upload.py 신규 추가 (기존 문서만 있고 실체 미커밋 상태였음)
- VesiScan_Android_Pipeline_Summary.md v7 patch (2026-07-13):
  align_analyze.py 도구 언급 + CH3 flicker fix 실측 검증 결과 요약

검증 결과 요약 (data123/ human 4 세션):
- Human 0CM (CH3 31.8%): LEGACY 즉시 회귀 → NEW flick 1/4 흡수 유지
- Human 1CM (CH3 77.3%): LEGACY idx15 oscillation → NEW idx13 조기 진입
- Human 3CM (CH3 97.2%): 양쪽 정상 (회귀 없음)
- Phantom: 양쪽 정상 (relaxed mode 오진입 없음)

tools/README.md

@@ -170,3 +170,81 @@ summary: 19 uploaded, 0 skipped, 1 failed (total 20)
 3. **다른 폰 → labdb 이관**: A 폰에서 측정 → `Downloads/VesiScan_Sessions/`
    폴더 → PC 로 복사 → 스크립트로 서버 반영.
 
+---
+
+## align_analyze.py — Alignment session Python replay
+
+`AlignGuide4Stage` (Kotlin) 의 상태머신 로직을 Python 으로 그대로 재현하여
+alignment 세션 JSON 을 오프라인 replay 한다. Method D 파이프라인
+(`vesiscan_test.library`) 을 통해 실제 앱과 동일한 검출 결과 위에서
+phase 전이 · action 시퀀스 · CH3 flicker 통계를 산출한다.
+
+### Setup
+
+```bash
+# piezophantomtest repo 경로 필요 (align_analyze.py 상단 sys.path.insert 참조)
+# 기본값: c:/Projects/piezophantomtest/piezo-phantom-test
+pip install numpy pandas
+```
+
+### Usage
+
+```bash
+# 세션 요약 (detection matrix + per-channel 통계)
+python tools/align_analyze.py session.json
+
+# NEW 로직 (majority + relaxed + soft-hint) 로 replay
+python tools/align_analyze.py session.json --replay
+
+# LEGACY 로직 (연속 3회 hit) 로 replay — 비교용
+python tools/align_analyze.py session.json --replay --legacy
+
+# NEW + LEGACY 동시 실행 (fix 전후 비교)
+python tools/align_analyze.py session.json --both
+
+# accum 조절 (기본 10 — BLE commit 주기 매칭)
+python tools/align_analyze.py session.json --both --accum 10 --no-summary
+
+# 여러 세션 일괄 (files 생략 시 c:/Projects/medilightv2android/data123/*.json 전체)
+python tools/align_analyze.py --both --no-summary
+```
+
+### 재현 파라미터 (Kotlin AlignmentConstants 매핑)
+
+| Python | Kotlin | 의미 |
+|---|---|---|
+| `V_WIN=6` | `VERTICAL_HIT_WINDOW` | VERTICAL_CLIMB 진입 sliding window |
+| `V_MAJ=3` | `VERTICAL_HIT_MAJORITY` | window 내 최소 hit |
+| `L_WIN=4` | `STABILIZE_LOST_WINDOW` | CH3 lost 판정 window |
+| `L_MAJ=3` | `STABILIZE_LOST_MAJORITY` | window 내 최소 lost |
+| `STUCK_TH=20` | `VERTICAL_STUCK_THRESHOLD` | relaxed mode 진입 threshold |
+| `SOFT_AFTER=12` | `VERTICAL_SOFT_HINT_AFTER` | soft hint 문구 전환 시점 |
+
+### 활용 예 (CH3 flicker fix 검증 2026-07-10)
+
+`data123/` 인체 임상 4 세션에 `--both` 로 NEW / LEGACY 병행 replay 실행.
+결과 요약:
+
+| 세션 | Records | LEGACY | NEW |
+|---|---|---|---|
+| Phantom 0CM | 62 | LR_BALANCE 도달 정상 | 동일 궤적, 회귀 없음 (false-positive 없음) |
+| Human 0CM (CH3 31.8%) | 22 | CH3_STAB 진입 즉시 회귀 | flick 1/4 흡수하며 유지 |
+| Human 1CM (CH3 77.3%) | 22 | idx 15 진입 + 2회 oscillation | idx 13 조기 진입 + 2 flick 흡수 |
+| Human 3CM (CH3 97.2%) | 36 | CENTER_OPTIMIZE 도달 정상 | 동일 궤적, 회귀 없음 |
+
+결론: sliding-window majority + soft-hint 조합만으로 human 0CM/1CM 회귀·조기
+진입 개선 확인. relaxed mode 는 팬텀·정상 케이스에서 트리거되지 않아 false
+positive 위험 없음.
+
+### 출력 (예)
+
+```
+--- RollingAligner replay NEW ---
+  window = 10
+  idx phase        relax chN CH3         ch0..3 chord     CV action
+   10 VERTICAL         .   6   Y   67.3 104.5 103.8 103.5   0.17 MOVE_UP (hit 1/6)
+   11 VERTICAL         .   6   Y   65.3 104.5 103.8 103.5   0.18 MOVE_UP (hit 2/6)
+   12 CH3_STAB         .   6   Y   67.3 104.5 103.8 103.5   0.17 STOP → CH3_STAB (hit 3/6)
+   ...
+```
+