feat: add quant engine WBS verification harness

2026-07-12 10:58:22 +09:00
parent a274ef448a
commit e7d1069222
39 changed files with 2888 additions and 287 deletions
@@ -2271,3 +2271,17 @@ python tools/validate_snapshot_admin_web_v1.py
 > 이 문서는 `docs/ROADMAP_WBS.md` 에 저장됩니다.  
 > 스프린트 완료마다 **완성도 KPI 섹션**을 업데이트하세요.  
 > 모든 WBS 항목의 구현 시 반드시 **하네스 성공 기준**을 먼저 충족 후 다음 단계로 진행합니다.
+
+---
+
+## 차세대 퀀트 엔진 로드맵/WBS 포인터 (2026-07-12)
+
+이후의 퀀트 엔진 진화 로드맵(M0–M5: 실증 하네스 → 수집 배선 → 시계열 저장소 →
+실데이터 팩터 → 백테스팅 → 포트폴리오/레짐)과 상세 WBS는 **기계 판정 YAML**로 관리한다:
+
+- **스펙(단일 진실 원천)**: `spec/60_quant_engine_wbs.yaml` (formula_id: `QUANT_ENGINE_WBS_V1`)
+- **단일 작업 검증**: `python tools/verify_wbs_task_v1.py --task <TASK_ID>` → `Temp/evidence/<TASK_ID>/verdict.json`
+- **전체 WBS 게이트**: `python tools/validate_quant_engine_wbs_v1.py` → `Temp/quant_engine_wbs_v1.json`
+
+완료 판정 원칙: 작업은 게이트 실행(PASS)으로만 `DONE` 이 될 수 있다.
+BE = PostgreSQL 쿼리 + Serilog 로그 패턴 + JSON 아티팩트, FE = Playwright(DOM assert + API 기대값 대조 + 스크린샷).
@@ -0,0 +1,392 @@
+// =============================================================================
+// QuantEngine Database Schema (DBML)
+// DbUp 마이그레이션(V1~V3)과 1:1 동기화 — 마이그레이션 추가 시 이 파일도 반드시 갱신
+// (CLAUDE.md 규칙: schema 변경 → DBML + 문서 동기화)
+//
+// 참고: Hangfire 스키마는 Hangfire.PostgreSql 라이브러리가 자동 생성
+// (DbUp 마이그레이션으로 관리하지 않음, 여기서도 제외)
+// =============================================================================
+
+Project quantengine {
+  database_type: 'PostgreSQL'
+  Note: '''
+    QuantEngine v0.1 데이터베이스 스키마.
+    세 개 스키마로 구성:
+    - quantengine: 핵심 KIS API 토큰, 사용자 계정, 수집 파이프라인 데이터
+    - engine_history: 팩터 계산 이력, 시장 데이터 이력, 의사결정 이력
+    - (생략) hangfire: Hangfire 백그라운드 잡 관리 (auto-created)
+  '''
+}
+
+// =============================================================================
+// Schema: quantengine (V1 + V2)
+// =============================================================================
+
+TableGroup "quantengine" {
+  kis_tokens
+  workspace_account
+  workspace_session
+  collection_runs
+  collection_snapshots
+  collection_source_errors
+  settings
+  account_snapshot
+  workspace_meta
+  workspace_change_log
+  workspace_approval_v2
+  workspace_lock
+  kis_collection_runs
+  kis_collection_snapshots
+  kis_collection_errors
+}
+
+Table quantengine.kis_tokens {
+  account TEXT [pk, note: "KIS 계정 모드 (real/mock)"]
+  access_token TEXT [not null, note: "KIS 토큰"]
+  expires_at TEXT [not null, note: "만료 시각 (ISO 8601)"]
+  updated_at TEXT [not null, note: "마지막 갱신 시각 (ISO 8601)"]
+
+  Note: "KIS Open API 인증 토큰 캐시"
+}
+
+Table quantengine.workspace_account {
+  ordinal INT [not null, note: "순서 인덱스"]
+  username TEXT [pk, note: "로그인 ID"]
+  password_hash TEXT [not null, note: "BCrypt 또는 SHA-256 해시 (자동 마이그레이션 가능)"]
+  role TEXT [not null, default: "'Admin'", note: "역할 (Admin)"]
+  is_active TEXT [not null, default: "'true'", note: "활성 상태 (true/false)"]
+  created_at TEXT [not null, note: "생성 시각 (ISO 8601)"]
+  updated_at TEXT [not null, note: "갱신 시각 (ISO 8601)"]
+
+  indexes {
+    (is_active, username) [name: "idx_workspace_account_active"]
+  }
+
+  Note: "Admin UI 사용자 계정"
+}
+
+Table quantengine.workspace_session {
+  session_token_hash TEXT [pk, note: "세션 토큰 해시"]
+  username TEXT [not null, note: "사용자명"]
+  role TEXT [not null, default: "'Admin'", note: "역할"]
+  created_at TEXT [not null, note: "세션 생성 시각 (ISO 8601)"]
+  expires_at TEXT [not null, note: "만료 시각 (ISO 8601)"]
+  revoked_at TEXT [note: "취소 시각 (ISO 8601), NULL이면 활성"]
+
+  indexes {
+    (username, expires_at) [name: "idx_workspace_session_username"]
+  }
+
+  Note: "세션 관리 (쿠키 기반 인증)"
+}
+
+Table quantengine.collection_runs {
+  run_id TEXT [pk, note: "수집 실행 ID (예: api-20260712-120000)"]
+  collector_name TEXT [not null, note: "수집기 이름"]
+  started_at TEXT [not null, note: "시작 시각 (ISO 8601)"]
+  finished_at TEXT [note: "종료 시각 (ISO 8601)"]
+  status TEXT [not null, note: "상태 (RUNNING/COMPLETED/FAILED)"]
+  input_source TEXT [note: "입력 소스 경로"]
+  output_json_path TEXT [note: "출력 JSON 파일 경로"]
+  output_db_path TEXT [note: "출력 DB 경로"]
+  notes TEXT [note: "메모"]
+  created_at TIMESTAMP [default: "CURRENT_TIMESTAMP", note: "DB 기록 시각"]
+
+  Note: "데이터 수집 실행 기록 (레거시, V2의 kis_collection_runs 참조)"
+}
+
+Table quantengine.collection_snapshots {
+  run_id TEXT [not null, note: "수집 실행 ID"]
+  dataset_name TEXT [not null, note: "데이터셋명"]
+  ticker TEXT [not null, note: "종목코드 (예: 005930)"]
+  name TEXT [note: "종목명"]
+  sector TEXT [note: "업종"]
+  as_of_date TEXT [note: "기준 일자"]
+  source_priority TEXT [note: "소스 우선순위"]
+  source_status TEXT [note: "소스 상태"]
+  payload_json TEXT [not null, note: "정규화된 데이터 (JSON)"]
+  provenance_json TEXT [not null, note: "출처 정보 (JSON)"]
+  created_at TIMESTAMP [default: "CURRENT_TIMESTAMP", note: "DB 기록 시각"]
+
+  indexes {
+    (run_id, dataset_name, ticker) [pk]
+    (ticker, created_at) [name: "idx_collection_snapshots_ticker_time"]
+  }
+
+  Note: "수집 스냅샷 (레거시, V2의 kis_collection_snapshots 참조)"
+}
+
+Table quantengine.collection_source_errors {
+  run_id TEXT [not null, note: "수집 실행 ID"]
+  ticker TEXT [note: "종목코드"]
+  source_name TEXT [not null, note: "소스명"]
+  error_kind TEXT [not null, note: "에러 타입"]
+  error_message TEXT [not null, note: "에러 메시지"]
+  payload_json TEXT [note: "에러 상세 (JSON)"]
+  created_at TIMESTAMP [default: "CURRENT_TIMESTAMP", note: "DB 기록 시각"]
+
+  indexes {
+    (run_id, source_name) [name: "idx_collection_source_errors_run"]
+  }
+
+  Note: "수집 중 발생한 에러 기록 (레거시)"
+}
+
+Table quantengine.settings {
+  ordinal INT [not null, note: "순서 인덱스"]
+  key TEXT [pk, note: "설정 키"]
+  value_json TEXT [not null, note: "값 (JSON)"]
+  note TEXT [not null, default: "''", note: "설명"]
+  updated_at TEXT [not null, note: "갱신 시각 (ISO 8601)"]
+
+  Note: "애플리케이션 설정 저장소"
+}
+
+Table quantengine.account_snapshot {
+  ordinal INT [not null, note: "순서 인덱스"]
+  row_json TEXT [not null, note: "계정 데이터 (JSON)"]
+  captured_at TEXT [not null, default: "''", note: "캡처 시각 (ISO 8601)"]
+  account TEXT [not null, default: "''", note: "계정"]
+  account_type TEXT [not null, default: "''", note: "계정 타입"]
+  ticker TEXT [not null, default: "''", note: "종목코드"]
+  name TEXT [not null, default: "''", note: "이름"]
+  parse_status TEXT [not null, default: "''", note: "파싱 상태"]
+  user_confirmed TEXT [not null, default: "''", note: "사용자 확인 여부"]
+  updated_at TEXT [not null, note: "갱신 시각 (ISO 8601)"]
+
+  indexes {
+    (captured_at) [name: "idx_account_snapshot_captured_at"]
+    (ticker) [name: "idx_account_snapshot_ticker"]
+  }
+
+  Note: "계정 스냅샷 저장소"
+}
+
+Table quantengine.workspace_meta {
+  key TEXT [pk, note: "메타 키"]
+  value_json TEXT [not null, note: "값 (JSON)"]
+
+  Note: "워크스페이스 메타데이터"
+}
+
+Table quantengine.workspace_change_log {
+  id SERIAL [pk, note: "자동 증가 ID"]
+  domain TEXT [not null, note: "도메인"]
+  action TEXT [not null, note: "액션 (create/update/delete)"]
+  target_ref TEXT [not null, default: "''", note: "대상 참조"]
+  actor TEXT [not null, default: "'system'", note: "액터 (사용자/시스템)"]
+  note TEXT [not null, default: "''", note: "메모"]
+  before_json TEXT [not null, default: "'null'", note: "변경 전 값 (JSON)"]
+  after_json TEXT [not null, default: "'null'", note: "변경 후 값 (JSON)"]
+  created_at TEXT [not null, note: "기록 시각 (ISO 8601)"]
+
+  Note: "변경 로그"
+}
+
+Table quantengine.workspace_approval_v2 {
+  domain TEXT [not null, note: "도메인"]
+  target_ref TEXT [not null, default: "'*'", note: "대상 참조"]
+  status TEXT [not null, note: "승인 상태"]
+  approved_by TEXT [not null, default: "''", note: "승인자"]
+  approved_at TEXT [not null, default: "''", note: "승인 시각 (ISO 8601)"]
+  note TEXT [not null, default: "''", note: "메모"]
+  updated_at TEXT [not null, note: "갱신 시각 (ISO 8601)"]
+
+  indexes {
+    (domain, target_ref) [pk]
+  }
+
+  Note: "승인 워크플로우"
+}
+
+Table quantengine.workspace_lock {
+  domain TEXT [not null, note: "도메인"]
+  target_ref TEXT [not null, default: "''", note: "대상 참조"]
+  locked_by TEXT [not null, default: "''", note: "잠금 사용자"]
+  reason TEXT [not null, default: "''", note: "잠금 사유"]
+  locked_at TEXT [not null, note: "잠금 시각 (ISO 8601)"]
+
+  indexes {
+    (domain, target_ref) [pk]
+  }
+
+  Note: "동시성 제어용 잠금"
+}
+
+// =============================================================================
+// V2: KIS 수집 파이프라인 (kis_collection_*)
+// =============================================================================
+
+Table quantengine.kis_collection_runs {
+  run_id TEXT [pk, note: "수집 실행 ID"]
+  status TEXT [not null, note: "상태: RUNNING / COMPLETED / COMPLETED_WITH_ERRORS / FAILED"]
+  started_at TEXT [not null, note: "시작 시각 (ISO 8601 KST)"]
+  finished_at TEXT [note: "종료 시각 (ISO 8601 KST)"]
+  total_snapshots INTEGER [note: "성공한 스냅샷 수"]
+  total_errors INTEGER [note: "발생한 에러 수"]
+  updated_at TEXT [not null, note: "마지막 갱신 시각 (ISO 8601)"]
+
+  indexes {
+    (started_at) [name: "idx_kis_runs_started_at"]
+  }
+
+  Note: "KIS API 수집 실행 기록"
+}
+
+Table quantengine.kis_collection_snapshots {
+  run_id TEXT [not null, note: "수집 실행 ID"]
+  dataset_name TEXT [note: "데이터셋명 (예: data_feed)"]
+  ticker TEXT [not null, note: "종목코드 (예: 005930)"]
+  source_name TEXT [not null, note: "데이터 소스 (kis_open_api 등)"]
+  payload_json TEXT [not null, note: "정규화된 수집 데이터 (JSON)"]
+  captured_at TEXT [not null, note: "캡처 시각 (ISO 8601 KST)"]
+  created_at TEXT [not null, note: "DB 기록 시각 (ISO 8601)"]
+
+  indexes {
+    (run_id, ticker, source_name) [pk]
+    (ticker) [name: "idx_kis_snapshots_ticker"]
+    (captured_at) [name: "idx_kis_snapshots_captured_at"]
+  }
+
+  Note: "KIS API 수집 스냅샷 (시계열 데이터)"
+}
+
+Table quantengine.kis_collection_errors {
+  id SERIAL [pk, note: "자동 증가 ID"]
+  run_id TEXT [not null, note: "수집 실행 ID"]
+  source_name TEXT [not null, note: "데이터 소스"]
+  error_kind TEXT [not null, note: "에러 타입 (예: HttpRequestException)"]
+  error_message TEXT [note: "에러 메시지"]
+  ticker TEXT [note: "종목코드 (해당하면)"]
+  created_at TEXT [not null, note: "DB 기록 시각 (ISO 8601)"]
+
+  indexes {
+    (run_id) [name: "idx_kis_errors_run_id"]
+  }
+
+  Note: "KIS API 수집 중 발생한 에러"
+}
+
+// =============================================================================
+// Schema: engine_history (V3)
+// =============================================================================
+
+TableGroup "engine_history" {
+  market_raw_history
+  factor_version_history
+  factor_output_history
+  decision_result_history
+  market_vs_engine_gap_history
+}
+
+Table engine_history.market_raw_history {
+  id BIGSERIAL [pk, note: "자동 증가 ID"]
+  source_id TEXT [not null, note: "소스 ID"]
+  observed_at TEXT [not null, note: "관측 시각 (ISO 8601)"]
+  source_name TEXT [not null, note: "소스명 (kis_open_api 등)"]
+  instrument_id TEXT [not null, note: "상품 ID (종목코드 등)"]
+  field_name TEXT [not null, note: "필드명 (현재가, 종가 등)"]
+  field_value TEXT [not null, note: "필드값 (문자열)"]
+  unit TEXT [not null, note: "단위 (원, % 등)"]
+  provenance JSONB [not null, default: "'{}'::jsonb", note: "출처 메타데이터 (JSON)"]
+  created_at TIMESTAMPTZ [not null, default: "NOW()", note: "DB 기록 시각 (UTC)"]
+
+  indexes {
+    (created_at) [name: "idx_market_raw_history_created_at"]
+  }
+
+  Note: "시장 데이터 원본 이력 (정규화 전)"
+}
+
+Table engine_history.factor_version_history {
+  id BIGSERIAL [pk, note: "자동 증가 ID"]
+  factor_id TEXT [not null, note: "팩터 ID (예: momentum_ss001)"]
+  factor_version TEXT [not null, note: "팩터 버전 (예: v1.0.0)"]
+  effective_from TEXT [not null, note: "유효 시작 일자 (YYYYMMDD)"]
+  effective_to TEXT [not null, note: "유효 종료 일자 (YYYYMMDD)"]
+  formula_id TEXT [not null, note: "계산식 ID"]
+  source_version TEXT [not null, note: "소스 버전"]
+  provenance JSONB [not null, default: "'{}'::jsonb", note: "출처 메타데이터 (JSON)"]
+  created_at TIMESTAMPTZ [not null, default: "NOW()", note: "DB 기록 시각 (UTC)"]
+
+  indexes {
+    (created_at) [name: "idx_factor_version_history_created_at"]
+  }
+
+  Note: "팩터 버전 관리 이력"
+}
+
+Table engine_history.factor_output_history {
+  id BIGSERIAL [pk, note: "자동 증가 ID"]
+  factor_output_id TEXT [not null, note: "팩터 출력 ID"]
+  observed_at TEXT [not null, note: "관측 일자 (YYYYMMDD)"]
+  factor_id TEXT [not null, note: "팩터 ID"]
+  factor_version TEXT [not null, note: "팩터 버전"]
+  output_value TEXT [not null, note: "출력값 (문자열)"]
+  output_gate TEXT [not null, note: "게이트 (PASS/FAIL/WARN)"]
+  source_version TEXT [not null, note: "소스 버전"]
+  provenance JSONB [not null, default: "'{}'::jsonb", note: "출처 메타데이터 (JSON)"]
+  created_at TIMESTAMPTZ [not null, default: "NOW()", note: "DB 기록 시각 (UTC)"]
+
+  indexes {
+    (created_at) [name: "idx_factor_output_history_created_at"]
+  }
+
+  Note: "팩터 계산 결과 이력"
+}
+
+Table engine_history.decision_result_history {
+  id BIGSERIAL [pk, note: "자동 증가 ID"]
+  decision_id TEXT [not null, note: "의사결정 ID"]
+  decided_at TEXT [not null, note: "의사결정 일자 (YYYYMMDD)"]
+  instrument_id TEXT [not null, note: "상품 ID (종목코드 등)"]
+  action TEXT [not null, note: "액션 (BUY/SELL/HOLD)"]
+  gate TEXT [not null, note: "게이트 (PASS/FAIL)"]
+  score TEXT [not null, note: "스코어 (문자열)"]
+  source_version TEXT [not null, note: "소스 버전"]
+  provenance JSONB [not null, default: "'{}'::jsonb", note: "출처 메타데이터 (JSON)"]
+  created_at TIMESTAMPTZ [not null, default: "NOW()", note: "DB 기록 시각 (UTC)"]
+
+  indexes {
+    (created_at) [name: "idx_decision_result_history_created_at"]
+  }
+
+  Note: "의사결정 결과 이력"
+}
+
+Table engine_history.market_vs_engine_gap_history {
+  id BIGSERIAL [pk, note: "자동 증가 ID"]
+  gap_id TEXT [not null, note: "갭 ID"]
+  observed_at TEXT [not null, note: "관측 일자 (YYYYMMDD)"]
+  instrument_id TEXT [not null, note: "상품 ID"]
+  metric_name TEXT [not null, note: "지표명"]
+  market_value TEXT [not null, note: "시장값"]
+  engine_value TEXT [not null, note: "엔진값"]
+  gap_value TEXT [not null, note: "갭값 (절대값)"]
+  gap_pct TEXT [not null, note: "갭 백분율 (%)"]
+  source_version TEXT [not null, note: "소스 버전"]
+  provenance JSONB [not null, default: "'{}'::jsonb", note: "출처 메타데이터 (JSON)"]
+  created_at TIMESTAMPTZ [not null, default: "NOW()", note: "DB 기록 시각 (UTC)"]
+
+  indexes {
+    (created_at) [name: "idx_market_vs_engine_gap_history_created_at"]
+  }
+
+  Note: "시장 데이터 vs 엔진 계산 갭 분석 이력"
+}
+
+// =============================================================================
+// Relationships (Logical, not enforced as FKs in DDL)
+// =============================================================================
+
+Ref: quantengine.kis_collection_snapshots.run_id > quantengine.kis_collection_runs.run_id {
+  // logical relationship: snapshots belong to a run
+}
+
+Ref: quantengine.kis_collection_errors.run_id > quantengine.kis_collection_runs.run_id {
+  // logical relationship: errors belong to a run
+}
+
+Ref: quantengine.workspace_session.username > quantengine.workspace_account.username {
+  // logical relationship: session belongs to a user
+}
@@ -0,0 +1,167 @@
+# QuantEngine 수집 파이프라인 (KIS API)
+
+## 1. 수집 실행 상태 전이도 (State Diagram)
+
+KIS 데이터 수집 실행(kis_collection_runs)의 상태 흐름. 상태값은 KisDataCollectionOrchestrator 에서 정의:
+- `RUNNING`: 수집 진행 중
+- `COMPLETED`: 모든 스냅샷 수집 완료 (에러 없음, `total_errors == 0`)
+- `COMPLETED_WITH_ERRORS`: 부분 수집 완료 (에러 발생, `total_errors > 0`이지만 일부 성공)
+- `FAILED`: 전체 실패 (예외 발생, 데이터 미적재)
+
+```mermaid
+stateDiagram-v2
+  [*] --> RUNNING: 수집 시작<br/>(RunCollectionAsync)
+  RUNNING --> COMPLETED: 완료 & error_count==0
+  RUNNING --> COMPLETED_WITH_ERRORS: 완료 & error_count>0
+  RUNNING --> FAILED: 예외 발생
+  COMPLETED --> [*]
+  COMPLETED_WITH_ERRORS --> [*]
+  FAILED --> [*]
+```
+
+**상태 전이 조건** (KisDataCollectionOrchestrator.cs 라인 104-105):
+- `error_count == 0` → `COMPLETED`
+- `error_count > 0` → `COMPLETED_WITH_ERRORS`
+- 예외(Exception) → `FAILED`
+
+**성공 기준** (CLAUDE.md "Collection Run Success Criteria"):
+- Success: `status == "COMPLETED"` (NOT failed)
+- Partial Success: `status == "COMPLETED"` + `total_snapshots > 0` + `total_errors > 0`
+- Failure: `status == "FAILED"` OR `total_snapshots == 0`
+
+---
+
+## 2. 수집 파이프라인 흐름도 (Flowchart)
+
+KIS API 데이터 수집의 전체 흐름. 두 개의 트리거:
+1. **Hangfire 정기 작업**: 매일 09:00 에 자동 실행
+2. **API 수동 트리거**: POST /api/collection/run (쿠키 기반 인증)
+
+```mermaid
+flowchart TD
+    A["Hangfire daily-collection<br/>(09:00 KST)"]
+    B["POST /api/collection/run<br/>(Cookie Auth)"]
+    
+    A --> C["IServiceScopeFactory.CreateScope<br/>(resolve ICollectionOrchestrator)"]
+    B --> C
+    
+    C --> D["KisDataCollectionOrchestrator.RunCollectionAsync<br/>(tickers: [005930, 000660, ...])"]
+    
+    D --> E["Per-ticker 루프"]
+    E --> F["KisApiPriceSource.GetPriceDataAsync<br/>(ticker, account)"]
+    F --> G["PriceDataNormalizer.NormalizeCollectionRow<br/>(seedRow, kisResult)"]
+    G --> H["CollectionRepository.SaveSnapshot<br/>(kis_collection_snapshots)"]
+    G --> I["CollectionRepository.SaveError<br/>(kis_collection_errors, on exception)"]
+    
+    H --> J{루프 끝?}
+    I --> J
+    J -->|Yes| K["CollectionRepository.SaveRun<br/>(kis_collection_runs)"]
+    J -->|No| E
+    
+    K --> L["파일 출력:<br/>Temp/kis_dotnet_collection_v1.json"]
+    L --> M["Serilog 로그:<br/>src/dotnet/.../logs/"]
+    
+    M --> N["Admin UI: /Admin/Collection<br/>(CollectionRepository 읽기)"]
+    N --> O["대시보드 표시:<br/>상태, 스냅샷 수, 에러"]
+```
+
+**데이터 흐름**:
+1. **입력**: Hangfire 스케줄 or API 수동 요청
+2. **오케스트레이션**: ICollectionOrchestrator 스코프 생성
+3. **수집**: KIS Open API 호출 → PriceDataNormalizer → DB 저장
+4. **출력**:
+   - kis_collection_runs: 실행 메타데이터 (run_id, status, total_snapshots, total_errors)
+   - kis_collection_snapshots: 종목별 가격 데이터 (JSON payload)
+   - kis_collection_errors: 에러 기록
+   - Temp/kis_dotnet_collection_v1.json: 수집 결과 요약 (formula_id, gate, run_id, summary)
+   - Serilog 로그: 런타임 로그 (src/dotnet/QuantEngine.Web/logs/)
+5. **표시**: Admin UI에서 CollectionRepository API 호출 → kis_collection_* 읽기 → Dashboard 렌더링
+
+---
+
+## 3. WBS 증거 검증 시퀀스도 (Sequence Diagram)
+
+작업 완료 증거를 자동 검증하는 파이프라인. 도구: `verify_wbs_task_v1.py` (증거 수집) + `validate_quant_engine_wbs_v1.py` (CI에서 재검증).
+
+```mermaid
+sequenceDiagram
+    Developer->>verify_wbs_task_v1.py: python verify_wbs_task_v1.py --task QE-M1-01<br/>(또는 --run-commands)
+    verify_wbs_task_v1.py->>+spec/60_quant_engine_wbs.yaml: load spec
+    spec/60_quant_engine_wbs.yaml-->>-verify_wbs_task_v1.py: meta + tasks[QE-M1-01]
+    
+    Note over verify_wbs_task_v1.py: evidence_checks 선언형 해석
+    
+    alt pg_query 체크
+      verify_wbs_task_v1.py->>+PostgreSQL: SELECT ... (WHERE 절)
+      PostgreSQL-->>-verify_wbs_task_v1.py: 스칼라 결과 또는 행
+      verify_wbs_task_v1.py->>verify_wbs_task_v1.py: expect{min,max,equals} 비교
+    end
+    
+    alt log_pattern 체크
+      verify_wbs_task_v1.py->>+src/dotnet/.../logs/: file_glob 매칭
+      src/dotnet/.../logs/-->>-verify_wbs_task_v1.py: 로그 라인
+      verify_wbs_task_v1.py->>verify_wbs_task_v1.py: 정규식 패턴 검사<br/>(min_matches, max_age_hours)
+    end
+    
+    alt json_gate 체크
+      verify_wbs_task_v1.py->>+Temp/kis_dotnet_collection_v1.json: read JSON
+      Temp/kis_dotnet_collection_v1.json-->>-verify_wbs_task_v1.py: payload
+      verify_wbs_task_v1.py->>verify_wbs_task_v1.py: 점 표기 경로(dot notation)<br/>+ 값 비교 (>=N 지원)
+    end
+    
+    alt file_exists 체크
+      verify_wbs_task_v1.py->>verify_wbs_task_v1.py: paths[] 존재 확인<br/>(min_bytes 검증)
+    end
+    
+    alt playwright_report 체크
+      verify_wbs_task_v1.py->>+tests/e2e/playwright-report.json: read report
+      tests/e2e/playwright-report.json-->>-verify_wbs_task_v1.py: suites[].specs[]
+      verify_wbs_task_v1.py->>verify_wbs_task_v1.py: spec_file 매칭<br/>(passed_min, failed)
+    end
+    
+    verify_wbs_task_v1.py->>verify_wbs_task_v1.py: 모든 체크 결과 종합<br/>(gate = ALL PASS? → PASS : FAIL)
+    
+    verify_wbs_task_v1.py->>+Temp/evidence/QE-M1-01/: mkdir
+    verify_wbs_task_v1.py->>Temp/evidence/QE-M1-01/verdict.json: write verdict<br/>(task_id, gate, checks[])
+    verify_wbs_task_v1.py->>Temp/evidence/QE-M1-01/: save raw evidence<br/>(pg_query_n.json, log_excerpt.txt, ...)
+    
+    verify_wbs_task_v1.py->>+runtime/lineage_events.jsonl: append event<br/>(node_id, gate, timestamp)
+    
+    Developer<<--verify_wbs_task_v1.py: exit 0 (gate=PASS)<br/>or exit 1 (gate=FAIL)
+    
+    Note over Developer: 선택: --run-commands 플래그<br/>verification_commands[] 실행
+    
+    Developer->>+validate_quant_engine_wbs_v1.py: (CI) python validate_quant_engine_wbs_v1.py
+    validate_quant_engine_wbs_v1.py->>validate_quant_engine_wbs_v1.py: spec load
+    validate_quant_engine_wbs_v1.py->>validate_quant_engine_wbs_v1.py: tasks[status==DONE] 필터
+    validate_quant_engine_wbs_v1.py->>+Temp/evidence/*/verdict.json: load all verdicts
+    Temp/evidence/*/verdict.json-->>-validate_quant_engine_wbs_v1.py: gate 값
+    validate_quant_engine_wbs_v1.py->>validate_quant_engine_wbs_v1.py: gate=FAIL? → CI FAIL
+    validate_quant_engine_wbs_v1.py->>+Temp/quant_engine_wbs_v1.json: write summary
+    Developer<<--validate_quant_engine_wbs_v1.py: exit 0 (모두 PASS)<br/>or exit 1 (일부 FAIL)
+```
+
+**검증 프로세스 상세**:
+
+| 단계 | 역할 | 산출물 |
+|------|------|--------|
+| **1. 스펙 로드** | verify_wbs_task_v1.py | spec/60_quant_engine_wbs.yaml |
+| **2. 증거 체크 실행** | 선언형 evidence_checks[] | pg_query / log_pattern / json_gate / file_exists / playwright_report |
+| **3. 게이트 결정** | 모든 체크 PASS? | gate = PASS or FAIL |
+| **4. 증거 저장** | Temp/evidence/<TASK_ID>/ | verdict.json + 원시 증거 |
+| **5. 계보 로깅** | runtime/lineage_events.jsonl | node_id, gate, timestamp |
+| **6. CI 재검증** | validate_quant_engine_wbs_v1.py | status=DONE 작업만 재검증 |
+
+**주요 특징**:
+- **선언형 검증**: 체크 로직을 YAML에 기술 (하드코딩 최소화)
+- **원시 증거 보존**: 각 체크의 상세 결과를 JSON/텍스트로 저장
+- **완료 주장 차단**: "완료했다"는 수동 선언 불가 → verdict.json gate=PASS만 인정
+- **CI 편입**: validate_quant_engine_wbs_v1.py가 release DAG의 노드로 동작
+- **멀티 트리거**: 단일 작업 검증 (--task) 또는 전체 검증 (CI)
+
+**검증 체크 타입 참고** (spec/60_quant_engine_wbs.yaml "evidence_check_types"):
+- **pg_query**: PostgreSQL 스칼라 결과 비교 (min/max/equals)
+- **log_pattern**: 로그 파일 정규식 매칭 (min_matches, max_age_hours)
+- **json_gate**: JSON 아티팩트 키-값 검사 (점 표기 경로, >=N 비교)
+- **file_exists**: 파일 존재 + 크기 검증 (min_bytes)
+- **playwright_report**: Playwright 리포트 테스트 결과 (passed_min, failed)