From 4cb206a2697d96e17a47254e528aefc5c8d677c6 Mon Sep 17 00:00:00 2001 From: kjh2064 Date: Sun, 21 Jun 2026 20:04:44 +0900 Subject: [PATCH 01/10] =?UTF-8?q?KIS=20Open=20API=20=EC=A1=B0=ED=9A=8C?= =?UTF-8?q?=EC=A0=84=EC=9A=A9=20=EC=97=B0=EB=8F=99=20+=20=EC=A7=81?= =?UTF-8?q?=EC=A0=91=EB=A7=A4=EB=A7=A4=20=EC=A0=88=EB=8C=80=EA=B8=88?= =?UTF-8?q?=EC=A7=80=20=EC=95=88=EC=A0=84=EA=B2=8C=EC=9D=B4=ED=8A=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 매수/매도 주문 및 계좌 잔고조회를 API로 직접 실행하지 않는다는 원칙을 코드 레벨에서 강제하는 안전게이트(governance/rules/06, 07)와 함께, 시세/호가/공매도거래비중 등 조회전용 KIS Open API 연동 및 SQLite 수집 파이프라인을 추가한다. - kis_api_client_v1: 모든 요청이 _assert_read_only를 통과해야 하며 /trading/ 경로·주문 TR_ID는 RuntimeError로 즉시 차단 - kis_data_collection_v1: KIS 우선 + Naver 폴백, 네트워크 실패는 개별 ticker 단위로 흡수(배치 전체 중단 없음) - data_collection_store_v1 / storage_backend_v1: SQLite 캐노니컬 저장소, PostgreSQL 전환 대비 백엔드 추상화 - Gitea 영업일 스케줄(2시간 간격) + CI 강제 게이트 (validate_no_direct_api_trading_v1, validate_kis_api_credentials_v1) --- .gitea/workflows/kis_data_collection.yml | 131 ++++++ docs/GITEA_SECRETS_SETUP.md | 48 +++ governance/rules/00_core_locks.yaml | 7 + .../rules/06_no_direct_api_trading.yaml | 55 +++ .../07_no_kis_account_balance_query.yaml | 44 ++ .../data_collection_backend_v1.py | 18 + src/quant_engine/data_collection_store_v1.py | 370 +++++++++++++++++ src/quant_engine/kis_api_client_v1.py | 212 ++++++++++ src/quant_engine/kis_data_collection_v1.py | 378 ++++++++++++++++++ src/quant_engine/storage_backend_v1.py | 50 +++ tests/unit/test_data_collection_store_v1.py | 110 +++++ tests/unit/test_kis_api_client_v1.py | 98 +++++ tests/unit/test_storage_backend_v1.py | 32 ++ ...test_validate_gitea_secrets_contract_v1.py | 20 + .../test_validate_kis_api_credentials_v1.py | 52 +++ tools/generate_postgresql_upgrade_stub_v1.py | 115 ++++++ tools/run_kis_data_collection_v1.py | 15 + tools/validate_gitea_secrets_contract_v1.py | 61 +++ tools/validate_kis_api_credentials_v1.py | 106 +++++ tools/validate_no_direct_api_trading_v1.py | 112 ++++++ 20 files changed, 2034 insertions(+) create mode 100644 .gitea/workflows/kis_data_collection.yml create mode 100644 docs/GITEA_SECRETS_SETUP.md create mode 100644 governance/rules/06_no_direct_api_trading.yaml create mode 100644 governance/rules/07_no_kis_account_balance_query.yaml create mode 100644 src/quant_engine/data_collection_backend_v1.py create mode 100644 src/quant_engine/data_collection_store_v1.py create mode 100644 src/quant_engine/kis_api_client_v1.py create mode 100644 src/quant_engine/kis_data_collection_v1.py create mode 100644 src/quant_engine/storage_backend_v1.py create mode 100644 tests/unit/test_data_collection_store_v1.py create mode 100644 tests/unit/test_kis_api_client_v1.py create mode 100644 tests/unit/test_storage_backend_v1.py create mode 100644 tests/unit/test_validate_gitea_secrets_contract_v1.py create mode 100644 tests/unit/test_validate_kis_api_credentials_v1.py create mode 100644 tools/generate_postgresql_upgrade_stub_v1.py create mode 100644 tools/run_kis_data_collection_v1.py create mode 100644 tools/validate_gitea_secrets_contract_v1.py create mode 100644 tools/validate_kis_api_credentials_v1.py create mode 100644 tools/validate_no_direct_api_trading_v1.py diff --git a/.gitea/workflows/kis_data_collection.yml b/.gitea/workflows/kis_data_collection.yml new file mode 100644 index 00000000..5bccfc9c --- /dev/null +++ b/.gitea/workflows/kis_data_collection.yml @@ -0,0 +1,131 @@ +name: KIS Data Collection (SQLite Canonical Feed) + +# ───────────────────────────────────────────────────────────────── +# [중요] 이 워크플로우는 KIS Open API를 코어로 하는 read-only 데이터 수집만 수행한다. +# xlsx를 직접 읽지 않고 GatherTradingData.json + live read-only APIs를 통해 +# SQLite canonical store를 갱신한다. 매수/매도 주문은 어떤 경우에도 실행하지 않는다. +# +# 스케줄: 영업일(월~금) 08:00~17:00 KST, 2시간 간격(08/10/12/14/16시). +# Gitea Actions의 schedule cron은 UTC 기준으로 평가된다(서버 타임존이 별도 +# 설정되어 있지 않은 경우의 기본값). 아래 cron은 UTC로 작성했다: +# KST 08:00 = UTC 전날 23:00 → 요일은 "한국 기준 평일"에 맞춰 UTC 0-4(일~목)로 이동 +# KST 10/12/14/16:00 = UTC 01/03/05/07:00, 같은 날(UTC 월~금, 1-5) +# +# [실제 Gitea 서버 타임존이 Asia/Seoul로 설정되어 있다면] 아래 cron을 그대로 +# "0 8,10,12,14,16 * * 1-5" 한 줄로 교체하면 된다 — 첫 실행 후 Actions 실행 +# 기록의 타임스탬프를 확인해 KST 08시 전후로 도는지 검증할 것(추정하지 말고 확인). +# +# 스케줄 주기 변경: 아래 schedule 목록의 cron 줄을 추가/삭제/수정하면 된다. +# 예) 1시간 간격으로 바꾸려면 09,11,13,15시 슬롯을 추가. +# ───────────────────────────────────────────────────────────────── + +on: + schedule: + - cron: "0 23 * * 0-4" # KST 월~금 08:00 (UTC 일~목 23:00) + - cron: "0 1 * * 1-5" # KST 월~금 10:00 (UTC 01:00) + - cron: "0 3 * * 1-5" # KST 월~금 12:00 (UTC 03:00) + - cron: "0 5 * * 1-5" # KST 월~금 14:00 (UTC 05:00) + - cron: "0 7 * * 1-5" # KST 월~금 16:00 (UTC 07:00) + workflow_dispatch: # 수동 실행 — 스케줄 검증/즉시 재시도용 + +jobs: + collect-kis-data: + runs-on: self-hosted + + steps: + - name: Checkout Code + run: | + if [ -d .git ]; then + git remote set-url origin http://x-access-token:${{ secrets.GITHUB_TOKEN }}@192.168.123.100:8418/KimJaeHyun/myfinance.git + else + git init + git remote add origin http://x-access-token:${{ secrets.GITHUB_TOKEN }}@192.168.123.100:8418/KimJaeHyun/myfinance.git + fi + git fetch origin main --depth=1 + git reset --hard FETCH_HEAD + if [ ! -f GatherTradingData.json ]; then + echo "::error::GatherTradingData.json 없음 — canonical seed snapshot이 필요합니다." + exit 1 + fi + + - name: Configure Runtime Paths + run: | + export PATH=/usr/local/bin:$PATH + echo "/usr/local/bin" >> $GITHUB_PATH + /usr/bin/python3 --version + + - name: Setup Python Environment + run: | + VENV_BASE=/volume1/gitea/python_venv + REQ_HASH=$(md5sum tools/run_kis_data_collection_v1.py 2>/dev/null | cut -d' ' -f1 || echo "kis-default") + VENV="$VENV_BASE/$REQ_HASH" + + if [ ! -f "$VENV/bin/python" ]; then + mkdir -p "$VENV_BASE" + /usr/bin/python3 -m venv "$VENV" + if [ ! -f "$VENV/bin/pip" ]; then + curl -sS https://bootstrap.pypa.io/pip/3.8/get-pip.py -o get-pip.py + "$VENV/bin/python" get-pip.py --quiet + rm get-pip.py + fi + "$VENV/bin/pip" install --upgrade pip --quiet + "$VENV/bin/pip" install requests beautifulsoup4 pyyaml --quiet + ls -dt "$VENV_BASE"/*/ 2>/dev/null | tail -n +3 | xargs rm -rf 2>/dev/null || true + fi + echo "$VENV/bin" >> $GITHUB_PATH + + - name: "[CRITICAL] No Direct API Trading Gate" + run: python3 tools/validate_no_direct_api_trading_v1.py + + - name: "[CRITICAL] Validate KIS API Credentials (mock)" + env: + KIS_APP_Key_TEST: ${{ secrets.KIS_APP_KEY_TEST }} + KIS_APP_Secret_TEST: ${{ secrets.KIS_APP_SECRET_TEST }} + run: | + python3 tools/validate_kis_api_credentials_v1.py \ + --account mock \ + --ticker 005930 + + - name: Collect KIS Market Data to SQLite (read-only) + env: + KIS_APP_Key: ${{ secrets.KIS_APP_KEY }} + KIS_APP_Secret: ${{ secrets.KIS_APP_SECRET }} + run: | + python3 tools/run_kis_data_collection_v1.py \ + --input-json GatherTradingData.json \ + --sqlite-db outputs/kis_data_collection/kis_data_collection.db \ + --output-json Temp/kis_data_collection_v1.json \ + --kis-account real + + - name: Validate SQLite Artifact + run: | + python3 - <<'PY' + import json, sqlite3 + from pathlib import Path + db = Path("outputs/kis_data_collection/kis_data_collection.db") + report = Path("Temp/kis_data_collection_v1.json") + assert db.exists(), f"missing db: {db}" + assert report.exists(), f"missing report: {report}" + conn = sqlite3.connect(db) + try: + run_count = conn.execute("SELECT COUNT(*) FROM collection_runs").fetchone()[0] + snap_count = conn.execute("SELECT COUNT(*) FROM collection_snapshots").fetchone()[0] + print(json.dumps({"run_count": run_count, "snapshot_count": snap_count}, ensure_ascii=False)) + assert run_count >= 1 + assert snap_count >= 1 + finally: + conn.close() + PY + + - name: Notify Run Result + if: always() + run: | + STATUS="${{ job.status }}" + RUN_URL="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" + SUMMARY_FILE="Temp/kis_data_collection_v1.json" + SUMMARY_TEXT="(요약 파일 없음)" + [ -f "$SUMMARY_FILE" ] && SUMMARY_TEXT=$(cat "$SUMMARY_FILE") + echo "=== KIS Data Collection Result ===" + echo "status: $STATUS" + echo "summary: $SUMMARY_TEXT" + echo "run log: $RUN_URL" diff --git a/docs/GITEA_SECRETS_SETUP.md b/docs/GITEA_SECRETS_SETUP.md new file mode 100644 index 00000000..cc295c2c --- /dev/null +++ b/docs/GITEA_SECRETS_SETUP.md @@ -0,0 +1,48 @@ +# Gitea Secrets Setup + +이 저장소는 KIS Open API와 Gitea workflow를 분리해서 사용한다. +실제 시크릿 등록은 Gitea 관리자 권한이 있는 운영자가 수행해야 한다. + +## Required Secrets + +### Shared + +- `GITHUB_TOKEN` + +### KIS read-only validation + +- `KIS_APP_KEY_TEST` +- `KIS_APP_SECRET_TEST` + +### KIS real data collection + +- `KIS_APP_KEY` +- `KIS_APP_SECRET` + +## Workflow Mapping + +- `.gitea/workflows/kis_data_collection.yml` + - mock validation: `KIS_APP_KEY_TEST`, `KIS_APP_SECRET_TEST` + - real collection: `KIS_APP_KEY`, `KIS_APP_SECRET` +- `.gitea/workflows/qualitative_sell_strategy.yml` + - mock validation: `KIS_APP_KEY_TEST`, `KIS_APP_SECRET_TEST` + - real collection: `KIS_APP_KEY`, `KIS_APP_SECRET` +- `.gitea/workflows/ci.yml` + - mock validation: `KIS_APP_KEY_TEST`, `KIS_APP_SECRET_TEST` + +## Runtime Rule + +- mock 계정은 유효성 확인용이다. +- real 계정은 실제 데이터 수집용이다. +- 둘을 같은 단계에서 혼용하지 않는다. + +## Verification + +Run: + +```bash +python tools/validate_gitea_secrets_contract_v1.py +``` + +The validator checks that the workflows reference the required secret names +with the expected separation between mock and real usage. diff --git a/governance/rules/00_core_locks.yaml b/governance/rules/00_core_locks.yaml index 55697270..14b74914 100644 --- a/governance/rules/00_core_locks.yaml +++ b/governance/rules/00_core_locks.yaml @@ -2,6 +2,13 @@ schema_version: agents_rule.v1 rule_id: CORE_LOCKS_V1 title: Core locks and no-hallucination rules summary: + - "[NO_DIRECT_API_TRADING] 매수/매도 주문은 어떤 API(한국투자증권 KIS Open API 포함)를 통해서도 + 직접 실행하지 않는다. 이 엔진의 모든 산출물은 '제안'이며, 실제 주문 실행은 반드시 사람이 + HTS에서 수동으로 입력한다. 이 원칙을 어기면 엔진 전체가 의미를 잃는다(사용자 직접 지시, + 2026-06-21) — governance/rules/06_no_direct_api_trading.yaml 참조." + - "[NO_KIS_ACCOUNT_BALANCE_QUERY] KIS Open API로 계좌 보유종목/잔고를 조회하지 않는다. + 보유종목의 유일한 출처는 HTS 캡처 → account_snapshot이다(사용자 직접 지시, 2026-06-21) + — governance/rules/07_no_kis_account_balance_query.yaml 참조." - Use spec/13_formula_registry.yaml for all prices, stops, targets, quantities. - Do not invent prices, quantities, or formulas. - If harness data is missing, print DATA_MISSING — 하네스 업데이트 필요. diff --git a/governance/rules/06_no_direct_api_trading.yaml b/governance/rules/06_no_direct_api_trading.yaml new file mode 100644 index 00000000..7d91529b --- /dev/null +++ b/governance/rules/06_no_direct_api_trading.yaml @@ -0,0 +1,55 @@ +schema_version: agents_rule.v1 +rule_id: NO_DIRECT_API_TRADING_V1 +title: API를 통한 매수/매도 직접 실행 절대 금지 — 최상위 안전 규칙 +priority: CRITICAL +origin: "사용자 직접 지시 (2026-06-21): '반드시 지침에 가장 중요한 하네스인 매수/매도는 + API를 통해서 직접하지 않는다가 원칙이다. 이걸 지키지 않는다면 엔진으로서 의미는 없다.'" +has_code_implementation: true +code_path: + - "src/quant_engine/kis_api_client_v1.py" + - "tools/validate_no_direct_api_trading_v1.py" + +summary: + - "이 엔진(은퇴자산포트폴리오 퀀트엔진)은 어떤 외부 API를 통해서도 매수/매도 주문을 + 직접 실행하지 않는다. 한국투자증권 KIS Open API를 포함해, 향후 연동되는 모든 + 브로커/거래소 API에 동일하게 적용된다." + - "이 엔진의 모든 산출물(final_decision_packet, sell_priority, rebalance orders 등)은 + '제안(proposal)'이지 '주문 실행(execution)'이 아니다. 실제 매수/매도 주문은 반드시 + 사람이 HTS(홈트레이딩시스템)에서 직접 확인 후 수동으로 입력한다." + - "이 원칙은 데이터 수집(read-only) API 사용을 금지하지 않는다 — 시세/호가/공매도/ + 투자자별 매매동향 등 조회성 데이터 수집은 허용된다. 금지 대상은 주문 제출 + (order placement), 정정(modify), 취소(cancel) API 호출뿐이다." + +scope: + applies_to: + - "한국투자증권(KIS) Open API — https://apiportal.koreainvestment.com" + - "향후 추가되는 모든 브로커/거래소 Open API 연동" + prohibited_actions: + - "주문 제출(매수/매도 주문 전송) API 호출" + - "기존 주문 정정/취소 API 호출" + - "잔고를 변경시키는 모든 쓰기성(write) API 호출" + allowed_actions: + - "시세 조회(현재가, 호가, 일자별 시세)" + - "공매도 일별추이 조회" + - "투자자별 매매동향 조회" + - "계좌 잔고/평가 조회(읽기 전용)" + +enforcement: + code_level: + rule: "KIS API 클라이언트 모듈(src/quant_engine/kis_api_client_v1.py)의 모든 HTTP 요청은 + 단일 공유 함수를 통해서만 전송되며, 그 함수는 차단 목록(FORBIDDEN_TR_ID_PREFIXES, + FORBIDDEN_PATH_SUBSTRINGS)에 해당하는 TR_ID/경로를 만나면 즉시 RuntimeError를 + 발생시켜 요청을 중단한다. 주문 제출/정정/취소 함수는 이 코드베이스에 일체 작성하지 + 않는다(함수 자체가 존재하지 않음 — 가드는 방어적 2차 안전장치)." + test: "tests/unit/test_kis_api_client_v1.py — 차단 목록에 있는 TR_ID/경로로 요청 시 + RuntimeError가 발생하는지 검증 + 소스코드 전체에 주문 제출 엔드포인트 경로 + 문자열(/uapi/domestic-stock/v1/trading/order-cash 등)이 한 글자도 존재하지 않는지 + 정적 grep 검증." + review_level: + rule: "이 모듈에 새 함수를 추가할 때마다 반드시 KIS Open API 공식 문서에서 해당 + TR_ID가 조회(quotations)/순위(ranking)/계좌조회(read-only) 카테고리인지 확인하고, + trading(주문) 카테고리 함수는 어떤 이유로도 추가하지 않는다." + +violation_consequence: "이 규칙을 어기면 엔진 전체가 '제안 시스템'에서 '자동매매 시스템'으로 + 변질되어 프로젝트의 핵심 전제(사람이 최종 승인·입력)가 깨진다. 사용자가 명시적으로 + '엔진으로서 의미는 없다'고 표현한 절대 우선 규칙이다." diff --git a/governance/rules/07_no_kis_account_balance_query.yaml b/governance/rules/07_no_kis_account_balance_query.yaml new file mode 100644 index 00000000..d79fb9ab --- /dev/null +++ b/governance/rules/07_no_kis_account_balance_query.yaml @@ -0,0 +1,44 @@ +schema_version: agents_rule.v1 +rule_id: NO_KIS_ACCOUNT_BALANCE_QUERY_V1 +title: KIS Open API로 계좌 보유종목/잔고 정보를 조회하지 않는다 — 필수 지침 +priority: CRITICAL +origin: "사용자 직접 지시 (2026-06-21): 'OPEN API에 계좌 보유종목에 대한 정보는 사용하지 + 않는다. 필수 지침이다.'" +has_code_implementation: true +code_path: + - "src/quant_engine/kis_api_client_v1.py" + - "tools/validate_no_direct_api_trading_v1.py" + +summary: + - "한국투자증권(KIS) Open API는 시세/호가/공매도/투자자매매동향 등 시장 전체에 공개된 + 조회성 데이터 수집에만 사용한다. 계좌 보유종목·잔고·평가금액 조회(주식잔고조회 등) + API는 호출하지 않는다." + - "보유종목 정보의 유일한 출처(source of truth)는 기존 HTS 캡처 → ChatGPT 파싱 → GAS + account_snapshot 시트 워크플로우다. 이 원칙은 [[feedback_direction_a_no_manual_input]] + (positions 수동입력 금지)와 같은 계열의 데이터 출처 통제 규칙이며, KIS API가 그 + 경로를 대체하거나 보강하지 않는다." + - "이 규칙은 governance/rules/06_no_direct_api_trading.yaml(주문 미실행)과 별개의 + 독립적인 제약이다 — 06번 규칙은 '쓰기(주문)'를 금지하고, 이 규칙은 '계좌 식별 데이터 + 조회(읽기)'를 금지한다. 두 규칙 모두 충돌 없이 동시에 적용된다." + +scope: + prohibited_tr_ids: + - "TTTC8434R" # 주식잔고조회(실전) + - "VTTC8434R" # 주식잔고조회(모의) + prohibited_path_substrings: + - "/trading/inquire-balance" + rationale: > + 이미 governance/rules/06의 FORBIDDEN_PATH_SUBSTRINGS=("/trading/",)가 이 경로를 + 구조적으로 차단하지만(주식잔고조회도 /trading/ 하위 경로), 이 규칙은 그것이 + '주문 차단의 부수효과'가 아니라 '계좌정보 비조회'라는 독립적이고 의도적인 정책임을 + 명시한다. + +enforcement: + code_level: "src/quant_engine/kis_api_client_v1.py에 inquire-balance 관련 함수를 작성하지 + 않는다(함수 자체가 존재하지 않음). TTTC8434R/VTTC8434R을 FORBIDDEN_TR_ID_PREFIXES에 + 추가해 2차 방어." + test_level: "tests/unit/test_kis_api_client_v1.py — TTTC8434R/VTTC8434R 차단 검증 + + tools/validate_no_direct_api_trading_v1.py 정적 스캔에 동일 TR_ID/경로 포함." + +violation_consequence: "계좌 보유정보를 KIS API로 조회하면 HTS 캡처 기반 단일 진실원천 + 원칙이 깨지고, 두 개의 서로 다른 보유종목 데이터 경로가 생겨 정합성 검증이 불가능해진다." diff --git a/src/quant_engine/data_collection_backend_v1.py b/src/quant_engine/data_collection_backend_v1.py new file mode 100644 index 00000000..e998c296 --- /dev/null +++ b/src/quant_engine/data_collection_backend_v1.py @@ -0,0 +1,18 @@ +"""Storage backend selection for the collection pipeline. + +This module is a thin compatibility wrapper over the generic storage backend +contract. The collector is intentionally designed around a backend contract, +not a hard SQLite-only assumption. +""" +from __future__ import annotations + +from pathlib import Path + +from src.quant_engine.storage_backend_v1 import StoreSpec, default_sqlite_store_path, normalize_store_spec + + +CollectionStoreSpec = StoreSpec + + +def default_collection_store_path(root: Path) -> Path: + return default_sqlite_store_path(root, "kis_data_collection/kis_data_collection.db") diff --git a/src/quant_engine/data_collection_store_v1.py b/src/quant_engine/data_collection_store_v1.py new file mode 100644 index 00000000..81848b65 --- /dev/null +++ b/src/quant_engine/data_collection_store_v1.py @@ -0,0 +1,370 @@ +"""SQLite store for platform-transition data collection outputs. + +This store is intentionally small and backend-agnostic enough to be upgraded to +PostgreSQL later without changing the row contract. The canonical payload is the +normalized factor row plus provenance metadata. +""" +from __future__ import annotations + +import json +import sqlite3 +from dataclasses import dataclass +from pathlib import Path +from typing import Any, Iterable + + +SCHEMA = """ +PRAGMA journal_mode=WAL; + +CREATE TABLE IF NOT EXISTS collection_runs ( + run_id TEXT PRIMARY KEY, + collector_name TEXT NOT NULL, + started_at TEXT NOT NULL, + finished_at TEXT, + status TEXT NOT NULL, + input_source TEXT, + output_json_path TEXT, + output_db_path TEXT, + notes TEXT, + created_at TEXT DEFAULT (datetime('now')) +); + +CREATE TABLE IF NOT EXISTS collection_snapshots ( + run_id TEXT NOT NULL, + dataset_name TEXT NOT NULL, + ticker TEXT NOT NULL, + name TEXT, + sector TEXT, + as_of_date TEXT, + source_priority TEXT, + source_status TEXT, + payload_json TEXT NOT NULL, + provenance_json TEXT NOT NULL, + created_at TEXT DEFAULT (datetime('now')), + PRIMARY KEY (run_id, dataset_name, ticker) +); + +CREATE TABLE IF NOT EXISTS collection_source_errors ( + run_id TEXT NOT NULL, + ticker TEXT, + source_name TEXT NOT NULL, + error_kind TEXT NOT NULL, + error_message TEXT NOT NULL, + payload_json TEXT, + created_at TEXT DEFAULT (datetime('now')) +); + +CREATE INDEX IF NOT EXISTS idx_collection_snapshots_ticker_time + ON collection_snapshots(ticker, created_at DESC); + +CREATE INDEX IF NOT EXISTS idx_collection_source_errors_run + ON collection_source_errors(run_id, source_name); +""" + + +@dataclass(frozen=True) +class CollectionRun: + run_id: str + collector_name: str + started_at: str + status: str + input_source: str | None = None + output_json_path: str | None = None + output_db_path: str | None = None + notes: str | None = None + + +def init_db(db_path: Path) -> None: + db_path.parent.mkdir(parents=True, exist_ok=True) + conn = sqlite3.connect(db_path) + try: + conn.executescript(SCHEMA) + conn.commit() + finally: + conn.close() + + +def upsert_collection_run(db_path: Path, run: CollectionRun, finished_at: str | None = None) -> None: + init_db(db_path) + conn = sqlite3.connect(db_path) + try: + conn.execute( + """ + INSERT INTO collection_runs ( + run_id, collector_name, started_at, finished_at, status, + input_source, output_json_path, output_db_path, notes + ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?) + ON CONFLICT(run_id) DO UPDATE SET + collector_name=excluded.collector_name, + started_at=excluded.started_at, + finished_at=excluded.finished_at, + status=excluded.status, + input_source=excluded.input_source, + output_json_path=excluded.output_json_path, + output_db_path=excluded.output_db_path, + notes=excluded.notes + """, + ( + run.run_id, + run.collector_name, + run.started_at, + finished_at, + run.status, + run.input_source, + run.output_json_path, + run.output_db_path, + run.notes, + ), + ) + conn.commit() + finally: + conn.close() + + +def upsert_collection_snapshot( + db_path: Path, + *, + run_id: str, + dataset_name: str, + ticker: str, + name: str | None, + sector: str | None, + as_of_date: str | None, + source_priority: str, + source_status: str, + payload: dict[str, Any], + provenance: dict[str, Any], +) -> None: + init_db(db_path) + conn = sqlite3.connect(db_path) + try: + conn.execute( + """ + INSERT INTO collection_snapshots ( + run_id, dataset_name, ticker, name, sector, as_of_date, + source_priority, source_status, payload_json, provenance_json + ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?) + ON CONFLICT(run_id, dataset_name, ticker) DO UPDATE SET + name=excluded.name, + sector=excluded.sector, + as_of_date=excluded.as_of_date, + source_priority=excluded.source_priority, + source_status=excluded.source_status, + payload_json=excluded.payload_json, + provenance_json=excluded.provenance_json + """, + ( + run_id, + dataset_name, + ticker, + name, + sector, + as_of_date, + source_priority, + source_status, + json.dumps(payload, ensure_ascii=False, default=str), + json.dumps(provenance, ensure_ascii=False, default=str), + ), + ) + conn.commit() + finally: + conn.close() + + +def append_collection_error( + db_path: Path, + *, + run_id: str, + source_name: str, + error_kind: str, + error_message: str, + ticker: str | None = None, + payload: dict[str, Any] | None = None, +) -> None: + init_db(db_path) + conn = sqlite3.connect(db_path) + try: + conn.execute( + """ + INSERT INTO collection_source_errors ( + run_id, ticker, source_name, error_kind, error_message, payload_json + ) VALUES (?, ?, ?, ?, ?, ?) + """, + ( + run_id, + ticker, + source_name, + error_kind, + error_message, + json.dumps(payload or {}, ensure_ascii=False, default=str), + ), + ) + conn.commit() + finally: + conn.close() + + +def fetch_latest_snapshots(db_path: Path, ticker: str, dataset_name: str | None = None) -> list[dict[str, Any]]: + if not db_path.exists(): + return [] + conn = sqlite3.connect(db_path) + conn.row_factory = sqlite3.Row + try: + if dataset_name: + rows = conn.execute( + """ + SELECT * FROM collection_snapshots + WHERE ticker = ? AND dataset_name = ? + ORDER BY created_at DESC + """, + (ticker, dataset_name), + ).fetchall() + else: + rows = conn.execute( + """ + SELECT * FROM collection_snapshots + WHERE ticker = ? + ORDER BY created_at DESC + """, + (ticker,), + ).fetchall() + return [dict(row) for row in rows] + finally: + conn.close() + + +def iter_recent_snapshots(db_path: Path, limit: int = 50) -> Iterable[dict[str, Any]]: + if not db_path.exists(): + return [] + conn = sqlite3.connect(db_path) + conn.row_factory = sqlite3.Row + try: + rows = conn.execute( + "SELECT * FROM collection_snapshots ORDER BY created_at DESC LIMIT ?", + (limit,), + ).fetchall() + return [dict(row) for row in rows] + finally: + conn.close() + + +def load_collection_runs(db_path: Path, limit: int = 20) -> list[dict[str, Any]]: + if not db_path.exists(): + return [] + conn = sqlite3.connect(db_path) + conn.row_factory = sqlite3.Row + try: + rows = conn.execute( + """ + SELECT run_id, collector_name, started_at, finished_at, status, + input_source, output_json_path, output_db_path, notes, created_at + FROM collection_runs + ORDER BY started_at DESC, created_at DESC + LIMIT ? + """, + (int(limit),), + ).fetchall() + return [dict(row) for row in rows] + finally: + conn.close() + + +def load_collection_errors(db_path: Path, limit: int = 20) -> list[dict[str, Any]]: + if not db_path.exists(): + return [] + conn = sqlite3.connect(db_path) + conn.row_factory = sqlite3.Row + try: + rows = conn.execute( + """ + SELECT run_id, ticker, source_name, error_kind, error_message, payload_json, created_at + FROM collection_source_errors + ORDER BY created_at DESC + LIMIT ? + """, + (int(limit),), + ).fetchall() + return [dict(row) for row in rows] + finally: + conn.close() + + +def load_collection_dashboard_state( + db_path: Path | str | None = None, + output_json_path: Path | str | None = None, + *, + limit: int = 8, +) -> dict[str, Any]: + db = Path(db_path) if db_path else Path() + report = Path(output_json_path) if output_json_path else Path() + state: dict[str, Any] = { + "db_path": str(db), + "output_json_path": str(report) if output_json_path else "", + "runs": [], + "recent_snapshots": [], + "recent_errors": [], + "counts": { + "collection_runs": 0, + "collection_snapshots": 0, + "collection_source_errors": 0, + }, + "latest_run": {}, + "latest_report": {}, + } + if report.exists(): + try: + state["latest_report"] = json.loads(report.read_text(encoding="utf-8")) + except Exception: + state["latest_report"] = {} + if not db.exists(): + return state + conn = sqlite3.connect(db) + conn.row_factory = sqlite3.Row + try: + state["counts"] = { + "collection_runs": conn.execute("SELECT COUNT(*) FROM collection_runs").fetchone()[0], + "collection_snapshots": conn.execute("SELECT COUNT(*) FROM collection_snapshots").fetchone()[0], + "collection_source_errors": conn.execute("SELECT COUNT(*) FROM collection_source_errors").fetchone()[0], + } + run_row = conn.execute( + """ + SELECT run_id, collector_name, started_at, finished_at, status, + input_source, output_json_path, output_db_path, notes, created_at + FROM collection_runs + ORDER BY started_at DESC, created_at DESC + LIMIT 1 + """ + ).fetchone() + state["latest_run"] = dict(run_row) if run_row is not None else {} + state["runs"] = [dict(row) for row in conn.execute( + """ + SELECT run_id, collector_name, started_at, finished_at, status, + input_source, output_json_path, output_db_path, notes, created_at + FROM collection_runs + ORDER BY started_at DESC, created_at DESC + LIMIT ? + """, + (int(limit),), + ).fetchall()] + state["recent_snapshots"] = [dict(row) for row in conn.execute( + """ + SELECT run_id, dataset_name, ticker, name, sector, as_of_date, + source_priority, source_status, created_at + FROM collection_snapshots + ORDER BY created_at DESC + LIMIT ? + """, + (int(limit),), + ).fetchall()] + state["recent_errors"] = [dict(row) for row in conn.execute( + """ + SELECT run_id, ticker, source_name, error_kind, error_message, created_at + FROM collection_source_errors + ORDER BY created_at DESC + LIMIT ? + """, + (int(limit),), + ).fetchall()] + finally: + conn.close() + return state diff --git a/src/quant_engine/kis_api_client_v1.py b/src/quant_engine/kis_api_client_v1.py new file mode 100644 index 00000000..013d4e3f --- /dev/null +++ b/src/quant_engine/kis_api_client_v1.py @@ -0,0 +1,212 @@ +"""한국투자증권(KIS) Open API 클라이언트 — 조회(read-only) 전용. + +근거: https://apiportal.koreainvestment.com/apiservice-summary , + https://github.com/koreainvestment/open-trading-api (2026-06-21 실측 확인된 + api_url/tr_id만 사용 — 추정 금지). + +══════════════════════════════════════════════════════════════════════════════ +[CRITICAL] governance/rules/06_no_direct_api_trading.yaml — 절대 규칙 +이 모듈은 매수/매도 주문을 어떤 경로로도 제출하지 않는다. 주문 제출/정정/취소 +함수는 이 파일에 일체 작성하지 않으며, 공유 요청 함수(_send_request)는 주문 +관련 경로("/trading/")나 TR_ID(TTTC08*/VTTC08* 등)를 만나면 즉시 RuntimeError로 +요청을 차단한다(2차 방어). 이 원칙을 어기면 엔진 전체가 '제안 시스템'에서 +'자동매매 시스템'으로 변질되어 프로젝트 핵심 전제가 깨진다(사용자 직접 지시). +══════════════════════════════════════════════════════════════════════════════ + +인증 정보는 Windows 환경변수에서 읽는다(실제계좌: KIS_APP_Key/KIS_APP_Secret, +모의계좌: KIS_APP_Key_TEST/KIS_APP_Secret_TEST). 방금 setx로 설정된 값은 현재 +프로세스의 os.environ에 아직 반영되지 않을 수 있어, HKCU\\Environment 레지스트리 +폴백을 둔다(읽기만 함, 값을 로그에 남기지 않음). +""" +from __future__ import annotations + +import datetime as dt +import json +import sys +from pathlib import Path +from typing import Any + +import requests + +ROOT = Path(__file__).resolve().parents[2] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +REAL_DOMAIN = "https://openapi.koreainvestment.com:9443" +MOCK_DOMAIN = "https://openapivts.koreainvestment.com:29443" +TOKEN_CACHE_DIR = ROOT / "Temp" + +# ── [CRITICAL] 주문 차단 목록 — 절대 수정/완화 금지 (governance/rules/06_no_direct_api_trading.yaml) ── +# "/trading/" 하위 경로는 주문(order)뿐 아니라 계좌잔고조회(inquire-balance)도 포함한다. +# 계좌 보유종목/잔고는 governance/rules/07_no_kis_account_balance_query.yaml에 의해 +# 별도로도 금지된다 — HTS 캡처가 유일한 출처(사용자 직접 지시). +FORBIDDEN_PATH_SUBSTRINGS: tuple[str, ...] = ("/trading/",) +FORBIDDEN_TR_ID_PREFIXES: tuple[str, ...] = ( + "TTTC08", "VTTC08", "TTTC01", "VTTC01", # 현금/신용 매수·매도·정정·취소 + "TTTC8434R", "VTTC8434R", # 주식잔고조회 — 계좌 보유종목 조회 금지(07번 규칙) +) + + +class OrderEndpointBlockedError(RuntimeError): + """주문 제출/정정/취소 경로 호출 시도 — 절대 차단.""" + + +def _assert_read_only(path: str, tr_id: str) -> None: + for forbidden in FORBIDDEN_PATH_SUBSTRINGS: + if forbidden in path: + raise OrderEndpointBlockedError( + f"BLOCKED: 주문 관련 경로 호출 시도 차단 — path={path!r}. " + "이 엔진은 매수/매도를 API로 직접 실행하지 않는다(governance/rules/06_no_direct_api_trading.yaml)." + ) + for prefix in FORBIDDEN_TR_ID_PREFIXES: + if tr_id.upper().startswith(prefix): + raise OrderEndpointBlockedError( + f"BLOCKED: 주문 관련 TR_ID 호출 시도 차단 — tr_id={tr_id!r}. " + "이 엔진은 매수/매도를 API로 직접 실행하지 않는다(governance/rules/06_no_direct_api_trading.yaml)." + ) + + +def _read_env_var(name: str) -> str | None: + import os + + value = os.environ.get(name) + if value: + return value + if sys.platform != "win32": + return None + try: + import winreg + + with winreg.OpenKey(winreg.HKEY_CURRENT_USER, "Environment") as key: + value, _ = winreg.QueryValueEx(key, name) + return value or None + except OSError: + return None + + +class KisCredentials: + def __init__(self, app_key: str, app_secret: str, account: str): + self.app_key = app_key + self.app_secret = app_secret + self.account = account # "real" | "mock" + self.domain = REAL_DOMAIN if account == "real" else MOCK_DOMAIN + + @classmethod + def load(cls, account: str = "mock") -> "KisCredentials": + if account == "real": + key_name, secret_name = "KIS_APP_Key", "KIS_APP_Secret" + elif account == "mock": + key_name, secret_name = "KIS_APP_Key_TEST", "KIS_APP_Secret_TEST" + else: + raise ValueError("account must be 'real' or 'mock'") + app_key = _read_env_var(key_name) + app_secret = _read_env_var(secret_name) + if not app_key or not app_secret: + raise RuntimeError( + f"{key_name}/{secret_name} 환경변수를 찾을 수 없음 — Windows 환경변수 설정 후 " + "새 셸에서 재시도하거나 HKCU\\Environment 레지스트리 반영을 확인하세요." + ) + return cls(app_key=app_key, app_secret=app_secret, account=account) + + +def _token_cache_path(creds: KisCredentials) -> Path: + TOKEN_CACHE_DIR.mkdir(parents=True, exist_ok=True) + return TOKEN_CACHE_DIR / f"kis_token_cache_{creds.account}.json" + + +def _issue_or_reuse_token(creds: KisCredentials) -> str: + """KIS는 토큰 발급 빈도를 제한한다 — 만료 전까지 캐시 재사용 필수.""" + cache_path = _token_cache_path(creds) + if cache_path.exists(): + try: + cached = json.loads(cache_path.read_text(encoding="utf-8")) + expires_at = dt.datetime.fromisoformat(cached["expires_at"]) + if dt.datetime.now(dt.timezone.utc) < expires_at - dt.timedelta(minutes=10): + return cached["access_token"] + except (json.JSONDecodeError, KeyError, ValueError): + pass + + resp = requests.post( + f"{creds.domain}/oauth2/tokenP", + json={"grant_type": "client_credentials", "appkey": creds.app_key, "appsecret": creds.app_secret}, + timeout=15, + ) + resp.raise_for_status() + body = resp.json() + access_token = body["access_token"] + expires_in_sec = int(body.get("expires_in", 86400)) + expires_at = dt.datetime.now(dt.timezone.utc) + dt.timedelta(seconds=expires_in_sec) + cache_path.write_text( + json.dumps({"access_token": access_token, "expires_at": expires_at.isoformat()}, ensure_ascii=False), + encoding="utf-8", + ) + return access_token + + +def _send_request(creds: KisCredentials, path: str, tr_id: str, params: dict[str, Any]) -> dict[str, Any]: + """모든 KIS REST 호출의 단일 진입점 — 여기서만 가드가 작동하면 충분하다.""" + _assert_read_only(path, tr_id) # [CRITICAL] 절대 제거 금지 + access_token = _issue_or_reuse_token(creds) + headers = { + "content-type": "application/json; charset=utf-8", + "authorization": f"Bearer {access_token}", + "appkey": creds.app_key, + "appsecret": creds.app_secret, + "tr_id": tr_id, + "custtype": "P", + } + resp = requests.get(f"{creds.domain}{path}", headers=headers, params=params, timeout=15) + resp.raise_for_status() + return resp.json() + + +# ── 조회(read-only) 함수 — 전부 GET, 전부 quotations/ranking 카테고리 (실측 확인) ────────── + +def get_current_price(creds: KisCredentials, code: str) -> dict[str, Any]: + """주식현재가 시세. api_url=/uapi/domestic-stock/v1/quotations/inquire-price, tr_id=FHKST01010100.""" + return _send_request( + creds, "/uapi/domestic-stock/v1/quotations/inquire-price", "FHKST01010100", + {"FID_COND_MRKT_DIV_CODE": "J", "FID_INPUT_ISCD": code}, + ) + + +def get_asking_price_10_level(creds: KisCredentials, code: str) -> dict[str, Any]: + """주식현재가 호가/예상체결 — 10단계 매수/매도 호가. + api_url=/uapi/domestic-stock/v1/quotations/inquire-asking-price-exp-ccn, tr_id=FHKST01010200. + """ + return _send_request( + creds, "/uapi/domestic-stock/v1/quotations/inquire-asking-price-exp-ccn", "FHKST01010200", + {"FID_COND_MRKT_DIV_CODE": "J", "FID_INPUT_ISCD": code}, + ) + + +def get_daily_short_sale(creds: KisCredentials, code: str, start_date: str, end_date: str) -> dict[str, Any]: + """국내주식 공매도 일별추이. api_url=/uapi/domestic-stock/v1/quotations/daily-short-sale, + tr_id=FHPST04830000. start_date/end_date: YYYYMMDD.""" + return _send_request( + creds, "/uapi/domestic-stock/v1/quotations/daily-short-sale", "FHPST04830000", + {"FID_COND_MRKT_DIV_CODE": "J", "FID_INPUT_ISCD": code, + "FID_INPUT_DATE_1": start_date, "FID_INPUT_DATE_2": end_date}, + ) + + +def get_daily_item_chart_price( + creds: KisCredentials, code: str, start_date: str, end_date: str, period: str = "D", +) -> dict[str, Any]: + """주식현재가 일자별. api_url=/uapi/domestic-stock/v1/quotations/inquire-daily-itemchartprice, + tr_id=FHKST03010100.""" + return _send_request( + creds, "/uapi/domestic-stock/v1/quotations/inquire-daily-itemchartprice", "FHKST03010100", + {"FID_COND_MRKT_DIV_CODE": "J", "FID_INPUT_ISCD": code, + "FID_INPUT_DATE_1": start_date, "FID_INPUT_DATE_2": end_date, + "FID_PERIOD_DIV_CODE": period, "FID_ORG_ADJ_PRC": "0"}, + ) + + +def get_investor_trend(creds: KisCredentials, code: str) -> dict[str, Any]: + """주식현재가 투자자(개인/외국인/기관) 매매동향. + api_url=/uapi/domestic-stock/v1/quotations/inquire-investor, tr_id=FHKST01010900.""" + return _send_request( + creds, "/uapi/domestic-stock/v1/quotations/inquire-investor", "FHKST01010900", + {"FID_COND_MRKT_DIV_CODE": "J", "FID_INPUT_ISCD": code}, + ) diff --git a/src/quant_engine/kis_data_collection_v1.py b/src/quant_engine/kis_data_collection_v1.py new file mode 100644 index 00000000..5a18720e --- /dev/null +++ b/src/quant_engine/kis_data_collection_v1.py @@ -0,0 +1,378 @@ +"""KIS-first data collector for the CI scheduler. + +The collector uses the existing `GatherTradingData.json` snapshot as the seed +universe, then enriches Korean tickers with read-only KIS quotations and +orderbook data, while retaining Naver/Yahoo fallbacks when available. +The canonical persistence target is SQLite. +""" +from __future__ import annotations + +import argparse +import datetime as dt +import json +import os +import sys +import uuid +from pathlib import Path +from typing import Any + +ROOT = Path(__file__).resolve().parents[2] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +try: + from tools.fetch_naver_market_data_v1 import ( # type: ignore + _session as naver_session, + compute_relative_return_20d, + compute_volume_ratio_5d, + fetch_foreign_institution_flow, + fetch_price_history, + ) +except Exception: # pragma: no cover - optional adapter + naver_session = None + compute_relative_return_20d = None + compute_volume_ratio_5d = None + fetch_foreign_institution_flow = None + fetch_price_history = None + +try: + from src.quant_engine.kis_api_client_v1 import ( # type: ignore + KisCredentials, + get_asking_price_10_level, + get_current_price, + get_daily_short_sale, + ) +except Exception: # pragma: no cover - safe fallback in non-KIS environments + KisCredentials = None + get_asking_price_10_level = None + get_current_price = None + get_daily_short_sale = None + +from src.quant_engine.data_collection_store_v1 import ( + CollectionRun, + append_collection_error, + upsert_collection_run, + upsert_collection_snapshot, +) +from src.quant_engine.data_collection_backend_v1 import ( + CollectionStoreSpec, + normalize_store_spec, +) + + +def _kst_now_iso() -> str: + return dt.datetime.now(dt.timezone(dt.timedelta(hours=9))).isoformat() + + +def _load_json(path: Path) -> dict[str, Any]: + if not path.exists(): + return {} + try: + return json.loads(path.read_text(encoding="utf-8")) + except Exception: + return {} + + +def _coerce_float(value: Any) -> float | None: + if value is None or value == "": + return None + try: + if isinstance(value, str): + value = value.replace(",", "").replace("%", "") + return float(value) + except (TypeError, ValueError): + return None + + +def _find_first_value(payload: Any, keys: tuple[str, ...]) -> Any: + stack = [payload] + while stack: + item = stack.pop() + if isinstance(item, dict): + for key in keys: + value = item.get(key) + if value not in (None, ""): + return value + stack.extend(item.values()) + elif isinstance(item, list): + stack.extend(item) + return None + + +def _normalize_naver_price_history(code: str) -> dict[str, Any]: + if naver_session is None or fetch_price_history is None: + return {"status": "DISABLED"} + try: + session = naver_session() + price = fetch_price_history(session, code) + result: dict[str, Any] = {"status": price.get("status", "UNKNOWN"), "source_url": price.get("source_url")} + rows = price.get("rows") or [] + if rows: + result["close"] = rows[0].get("close") + result["open"] = rows[0].get("open") + result["high"] = rows[0].get("high") + result["low"] = rows[0].get("low") + result["volume"] = rows[0].get("volume") + if compute_relative_return_20d is not None: + benchmark = fetch_price_history(session, "069500") + result["relative_return_20d"] = compute_relative_return_20d(rows, benchmark.get("rows", [])) + if compute_volume_ratio_5d is not None: + result["volume_ratio_5d"] = compute_volume_ratio_5d(rows) + if fetch_foreign_institution_flow is not None: + result["foreign_institution_flow"] = fetch_foreign_institution_flow(session, code) + return result + except Exception as exc: # noqa: BLE001 - fallback source must not break the batch + return {"status": "ERROR", "error": str(exc)} + + +def _normalize_kis_fields(code: str, account: str) -> dict[str, Any]: + if KisCredentials is None or get_current_price is None or get_asking_price_10_level is None or get_daily_short_sale is None: + return {"status": "DISABLED"} + try: + creds = KisCredentials.load(account) + except Exception as exc: + return {"status": "ERROR", "error": str(exc)} + + result: dict[str, Any] = {"status": "OK", "account": account} + try: + price = get_current_price(creds, code) + result["current_price_raw"] = price + result["current_price"] = _coerce_float(_find_first_value(price, ("stck_prpr", "stck_clpr", "close", "close_price"))) + result["open"] = _coerce_float(_find_first_value(price, ("stck_oprc", "open", "open_price"))) + result["high"] = _coerce_float(_find_first_value(price, ("stck_hgpr", "high", "high_price"))) + result["low"] = _coerce_float(_find_first_value(price, ("stck_lwpr", "low", "low_price"))) + result["prev_close"] = _coerce_float(_find_first_value(price, ("prdy_vrss", "prev_close"))) + result["volume"] = _coerce_float(_find_first_value(price, ("acml_vol", "volume"))) + result["change_pct"] = _coerce_float(_find_first_value(price, ("prdy_ctrt", "change_pct"))) + except Exception as exc: + result["price_status"] = "ERROR" + result["price_error"] = str(exc) + + try: + orderbook = get_asking_price_10_level(creds, code) + output1 = orderbook.get("output1") or {} + result["orderbook_raw"] = orderbook + result["microstructure_pressure"] = _coerce_float( + _find_first_value(output1, ("total_askp_rsqn", "total_bidp_rsqn")) + ) + result["ask_1"] = _coerce_float(_find_first_value(output1, ("askp1",))) + result["bid_1"] = _coerce_float(_find_first_value(output1, ("bidp1",))) + result["orderbook_status"] = "OK" + except Exception as exc: + result["orderbook_status"] = "ERROR" + result["orderbook_error"] = str(exc) + + try: + start = (dt.date.today() - dt.timedelta(days=10)).strftime("%Y%m%d") + end = dt.date.today().strftime("%Y%m%d") + short_sale = get_daily_short_sale(creds, code, start, end) + result["short_sale_raw"] = short_sale + rows = short_sale.get("output2") or [] + if rows: + latest = rows[0] + result["short_turnover_share"] = _coerce_float(latest.get("ssts_vol_rlim")) + result["short_sale_status"] = "OK" + except Exception as exc: + result["short_sale_status"] = "ERROR" + result["short_sale_error"] = str(exc) + + return result + + +def _build_seed_rows(source_json: Path) -> list[dict[str, Any]]: + payload = _load_json(source_json) + data = payload.get("data") or {} + core_satellite = {str(row.get("Ticker") or row.get("ticker") or ""): row for row in data.get("core_satellite", [])} + sector_lookup = {str(row.get("Ticker") or row.get("ticker") or ""): row.get("Sector") for row in data.get("core_satellite", [])} + rows: list[dict[str, Any]] = [] + for row in data.get("data_feed", []): + ticker = str(row.get("Ticker") or row.get("ticker") or "").strip() + if not ticker: + continue + merged = dict(row) + core_row = core_satellite.get(ticker) or {} + if core_row: + for key, value in core_row.items(): + merged.setdefault(key, value) + merged["Sector"] = merged.get("Sector") or sector_lookup.get(ticker) + rows.append(merged) + return rows + + +def _collect_one(row: dict[str, Any], *, kis_account: str, include_naver: bool, include_live_kis: bool) -> tuple[dict[str, Any], dict[str, Any]]: + ticker = str(row.get("Ticker") or row.get("ticker") or "").strip() + name = str(row.get("Name") or row.get("name") or "").strip() + sector = str(row.get("Sector") or row.get("sector") or "").strip() or None + normalized = dict(row) + provenance: dict[str, Any] = { + "ticker": ticker, + "name": name, + "sector": sector, + "source_priority": ["gathertradingdata_json"], + } + + if include_live_kis and ticker.isdigit() and len(ticker) == 6: + kis = _normalize_kis_fields(ticker, kis_account) + provenance["kis"] = kis + normalized.update({k: v for k, v in kis.items() if k not in {"current_price_raw", "orderbook_raw", "short_sale_raw"}}) + if kis.get("status") == "OK": + provenance["source_priority"].insert(0, "kis_open_api") + + if include_naver and ticker.isdigit() and len(ticker) == 6: + naver = _normalize_naver_price_history(ticker) + provenance["naver"] = naver + if naver.get("status") in {"OK", "DATA_MISSING"}: + normalized.setdefault("relative_return_20d", naver.get("relative_return_20d")) + normalized.setdefault("volume_ratio_5d", naver.get("volume_ratio_5d")) + normalized.setdefault("naver_price_status", naver.get("status")) + provenance["source_priority"].append("naver_finance") + + normalized.setdefault("collection_as_of", _kst_now_iso()) + return normalized, provenance + + +def collect_to_sqlite( + *, + input_json: Path, + sqlite_db: Path, + output_json: Path, + kis_account: str, + include_naver: bool = True, + include_live_kis: bool = True, +) -> dict[str, Any]: + run_id = uuid.uuid4().hex + started_at = _kst_now_iso() + upsert_collection_run( + sqlite_db, + CollectionRun( + run_id=run_id, + collector_name="kis_data_collection_v1", + started_at=started_at, + status="RUNNING", + input_source=str(input_json), + output_json_path=str(output_json), + output_db_path=str(sqlite_db), + notes="KIS-first CI collection", + ), + ) + + seed_rows = _build_seed_rows(input_json) + summary = { + "formula_id": "KIS_DATA_COLLECTION_V1", + "run_id": run_id, + "started_at": started_at, + "input_json": str(input_json), + "sqlite_db": str(sqlite_db), + "row_count": len(seed_rows), + "source_counts": {}, + "errors": [], + "rows": [], + } + + for row in seed_rows: + ticker = str(row.get("Ticker") or row.get("ticker") or "").strip() + if not ticker: + continue + try: + normalized, provenance = _collect_one(row, kis_account=kis_account, include_naver=include_naver, include_live_kis=include_live_kis) + source_counts = summary["source_counts"] + for source_name in provenance.get("source_priority") or []: + source_counts[source_name] = source_counts.get(source_name, 0) + 1 + upsert_collection_snapshot( + sqlite_db, + run_id=run_id, + dataset_name="data_feed", + ticker=ticker, + name=str(normalized.get("Name") or normalized.get("name") or ""), + sector=normalized.get("Sector"), + as_of_date=str(normalized.get("Price_Date") or normalized.get("AsOfDate") or normalized.get("collection_as_of") or ""), + source_priority=">".join(provenance.get("source_priority") or []), + source_status="OK", + payload=normalized, + provenance=provenance, + ) + summary["rows"].append( + { + "ticker": ticker, + "name": normalized.get("Name") or normalized.get("name"), + "sector": normalized.get("Sector"), + "source_priority": provenance.get("source_priority"), + "current_price": normalized.get("current_price"), + "relative_return_20d": normalized.get("relative_return_20d"), + "volume_ratio_5d": normalized.get("volume_ratio_5d"), + } + ) + except Exception as exc: # noqa: BLE001 + error = {"ticker": ticker, "error": str(exc)} + summary["errors"].append(error) + append_collection_error( + sqlite_db, + run_id=run_id, + source_name="collector", + error_kind=type(exc).__name__, + error_message=str(exc), + ticker=ticker, + payload=row, + ) + + summary["finished_at"] = _kst_now_iso() + summary["status"] = "PASS" if not summary["errors"] else "PASS_WITH_WARNINGS" + output_json.parent.mkdir(parents=True, exist_ok=True) + output_json.write_text(json.dumps(summary, ensure_ascii=False, indent=2), encoding="utf-8") + upsert_collection_run( + sqlite_db, + CollectionRun( + run_id=run_id, + collector_name="kis_data_collection_v1", + started_at=started_at, + status=summary["status"], + input_source=str(input_json), + output_json_path=str(output_json), + output_db_path=str(sqlite_db), + notes="KIS-first CI collection", + ), + finished_at=summary["finished_at"], + ) + return summary + + +def main() -> int: + ap = argparse.ArgumentParser(description=__doc__) + ap.add_argument("--input-json", type=Path, default=ROOT / "GatherTradingData.json") + ap.add_argument("--sqlite-db", type=Path, default=ROOT / "outputs" / "kis_data_collection" / "kis_data_collection.db") + ap.add_argument("--store-backend", default="sqlite", help="Storage backend contract placeholder (sqlite today, postgresql planned)") + ap.add_argument("--store-location", default=None, help="Backend location/DSN. sqlite path or future postgres DSN.") + ap.add_argument("--output-json", type=Path, default=ROOT / "Temp" / "kis_data_collection_v1.json") + ap.add_argument("--kis-account", choices=["real", "mock"], default="real") + ap.add_argument("--no-naver", action="store_true") + ap.add_argument("--no-live-kis", action="store_true") + args = ap.parse_args() + + store_backend, store_location = normalize_store_spec( + CollectionStoreSpec( + backend=args.store_backend, + location=args.store_location or args.sqlite_db, + ), + ROOT, + ) + if store_backend != "sqlite": + raise SystemExit( + "현재 실행 backend는 sqlite만 지원합니다. " + "하지만 collector는 이미 backend contract로 분리되어 있어 " + "후속 PostgreSQL 구현을 같은 호출 지점에 붙일 수 있습니다." + ) + + summary = collect_to_sqlite( + input_json=args.input_json, + sqlite_db=Path(store_location), + output_json=args.output_json, + kis_account=args.kis_account, + include_naver=not args.no_naver, + include_live_kis=not args.no_live_kis, + ) + print(json.dumps(summary, ensure_ascii=False, indent=2)) + return 0 if summary.get("status") == "PASS" else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/src/quant_engine/storage_backend_v1.py b/src/quant_engine/storage_backend_v1.py new file mode 100644 index 00000000..5c3be474 --- /dev/null +++ b/src/quant_engine/storage_backend_v1.py @@ -0,0 +1,50 @@ +"""Generic storage backend contract for canonical time-series stores. + +The call sites use this as a small contract layer so SQLite is the executable +backend today while PostgreSQL can be added later without changing callers. +""" +from __future__ import annotations + +from dataclasses import dataclass +from pathlib import Path + + +@dataclass(frozen=True) +class StoreSpec: + backend: str = "sqlite" + location: str | Path | None = None + + def normalized_backend(self) -> str: + backend = (self.backend or "sqlite").strip().lower() + if backend in {"sqlite", "sqlite3"}: + return "sqlite" + if backend in {"postgres", "postgresql", "pg"}: + return "postgresql" + return backend + + +def default_sqlite_store_path(root: Path, default_name: str) -> Path: + return root / "outputs" / default_name + + +def normalize_store_spec( + spec: StoreSpec, + root: Path, + *, + default_sqlite_name: str = "store.db", +) -> tuple[str, Path | str]: + backend = spec.normalized_backend() + if backend == "sqlite": + if spec.location is None: + return backend, default_sqlite_store_path(root, default_sqlite_name) + if isinstance(spec.location, Path): + return backend, spec.location + location = str(spec.location).strip() + if location.startswith("sqlite:///"): + return backend, Path(location.removeprefix("sqlite:///")) + return backend, Path(location) + if backend == "postgresql": + if not spec.location: + raise ValueError("postgresql backend requires a DSN/location string") + return backend, str(spec.location) + raise ValueError(f"unsupported backend: {spec.backend!r}") diff --git a/tests/unit/test_data_collection_store_v1.py b/tests/unit/test_data_collection_store_v1.py new file mode 100644 index 00000000..6182b9e0 --- /dev/null +++ b/tests/unit/test_data_collection_store_v1.py @@ -0,0 +1,110 @@ +from __future__ import annotations + +import sqlite3 +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +from src.quant_engine.data_collection_store_v1 import ( + CollectionRun, + append_collection_error, + fetch_latest_snapshots, + init_db, + iter_recent_snapshots, + upsert_collection_run, + upsert_collection_snapshot, +) +from src.quant_engine.data_collection_backend_v1 import CollectionStoreSpec, normalize_store_spec + + +def test_store_writes_and_reads_snapshots(tmp_path): + db_path = tmp_path / "collector.db" + init_db(db_path) + upsert_collection_run( + db_path, + CollectionRun( + run_id="run-1", + collector_name="collector", + started_at="2026-06-21T12:00:00+09:00", + status="RUNNING", + input_source="GatherTradingData.json", + output_json_path="Temp/kis_data_collection_v1.json", + output_db_path=str(db_path), + ), + ) + upsert_collection_snapshot( + db_path, + run_id="run-1", + dataset_name="data_feed", + ticker="005930", + name="삼성전자", + sector="반도체", + as_of_date="2026-06-21", + source_priority="kis_open_api>gathertradingdata_json", + source_status="OK", + payload={"ticker": "005930", "close": 1000}, + provenance={"kis": {"status": "OK"}}, + ) + append_collection_error( + db_path, + run_id="run-1", + source_name="kis", + error_kind="TimeoutError", + error_message="timeout", + ticker="005930", + ) + + conn = sqlite3.connect(db_path) + try: + run_count = conn.execute("SELECT COUNT(*) FROM collection_runs").fetchone()[0] + snap_count = conn.execute("SELECT COUNT(*) FROM collection_snapshots").fetchone()[0] + err_count = conn.execute("SELECT COUNT(*) FROM collection_source_errors").fetchone()[0] + finally: + conn.close() + + assert run_count == 1 + assert snap_count == 1 + assert err_count == 1 + assert fetch_latest_snapshots(db_path, "005930")[0]["dataset_name"] == "data_feed" + assert len(list(iter_recent_snapshots(db_path, limit=5))) == 1 + + +def test_store_overwrites_same_run_and_ticker(tmp_path): + db_path = tmp_path / "collector.db" + upsert_collection_snapshot( + db_path, + run_id="run-1", + dataset_name="data_feed", + ticker="005930", + name="삼성전자", + sector="반도체", + as_of_date="2026-06-21", + source_priority="kis_open_api", + source_status="OK", + payload={"ticker": "005930", "close": 1000}, + provenance={"source_priority": ["kis_open_api"]}, + ) + upsert_collection_snapshot( + db_path, + run_id="run-1", + dataset_name="data_feed", + ticker="005930", + name="삼성전자", + sector="반도체", + as_of_date="2026-06-21", + source_priority="kis_open_api>naver_finance", + source_status="OK", + payload={"ticker": "005930", "close": 2000}, + provenance={"source_priority": ["kis_open_api", "naver_finance"]}, + ) + rows = fetch_latest_snapshots(db_path, "005930") + assert rows[0]["source_priority"] == "kis_open_api>naver_finance" + + +def test_store_backend_normalization_supports_sqlite_paths(tmp_path): + backend, location = normalize_store_spec(CollectionStoreSpec(location=tmp_path / "collector.db"), ROOT) + assert backend == "sqlite" + assert str(location).endswith("collector.db") diff --git a/tests/unit/test_kis_api_client_v1.py b/tests/unit/test_kis_api_client_v1.py new file mode 100644 index 00000000..62abf3e5 --- /dev/null +++ b/tests/unit/test_kis_api_client_v1.py @@ -0,0 +1,98 @@ +from __future__ import annotations + +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +import pytest + +from src.quant_engine.kis_api_client_v1 import ( + KisCredentials, + OrderEndpointBlockedError, + _assert_read_only, +) + +# governance/rules/06_no_direct_api_trading.yaml — 이 테스트는 절대 약화/삭제하지 않는다. + +FORBIDDEN_ORDER_PATHS = ( + "/uapi/domestic-stock/v1/trading/order-cash", + "/uapi/domestic-stock/v1/trading/order-rvsecncl", + "/uapi/domestic-stock/v1/trading/order-credit", + "/uapi/domestic-stock/v1/trading/order-resv", + "/uapi/domestic-stock/v1/trading/inquire-balance", # governance/rules/07 — 계좌 보유종목 조회 금지 +) +FORBIDDEN_ORDER_TR_IDS = ( + "TTTC0802U", "TTTC0801U", "VTTC0802U", "VTTC0801U", + "TTTC8434R", "VTTC8434R", # governance/rules/07 — 주식잔고조회 금지 +) + + +@pytest.mark.parametrize("path", FORBIDDEN_ORDER_PATHS) +def test_order_path_is_blocked(path: str): + with pytest.raises(OrderEndpointBlockedError): + _assert_read_only(path, "FHKST01010100") + + +@pytest.mark.parametrize("tr_id", FORBIDDEN_ORDER_TR_IDS) +def test_order_tr_id_is_blocked(tr_id: str): + with pytest.raises(OrderEndpointBlockedError): + _assert_read_only("/uapi/domestic-stock/v1/quotations/inquire-price", tr_id) + + +def test_known_readonly_endpoints_pass(): + _assert_read_only("/uapi/domestic-stock/v1/quotations/inquire-price", "FHKST01010100") + _assert_read_only("/uapi/domestic-stock/v1/quotations/inquire-asking-price-exp-ccn", "FHKST01010200") + _assert_read_only("/uapi/domestic-stock/v1/quotations/daily-short-sale", "FHPST04830000") + + +def test_no_order_endpoint_substring_anywhere_in_kis_client_source(): + """정적 검증 — 누군가 향후 주문 함수를 추가하더라도 경로 문자열이 소스에 남으면 즉시 탐지. + + TTTC8434R/VTTC8434R(주식잔고조회)는 FORBIDDEN_TR_ID_PREFIXES 차단목록 '데이터'로 + 이 파일에 의도적으로 존재한다(prefix가 아닌 전체 TR_ID라 prefix-매칭으로는 막을 수 + 없어 명시적으로 등재) — 이 두 개는 검사에서 제외한다. 전체 코드베이스 차원의 + "차단목록 외 파일에는 한 글자도 없어야 한다"는 보장은 + tools/validate_no_direct_api_trading_v1.py(ALLOWLISTED_FILES 제외 전체 스캔)가 맡는다. + """ + source = (ROOT / "src" / "quant_engine" / "kis_api_client_v1.py").read_text(encoding="utf-8") + blocklist_data_exceptions = {"TTTC8434R", "VTTC8434R"} + for forbidden_path in FORBIDDEN_ORDER_PATHS: + assert forbidden_path not in source, f"주문 엔드포인트 경로가 소스에 존재함: {forbidden_path}" + for forbidden_tr_id in FORBIDDEN_ORDER_TR_IDS: + if forbidden_tr_id in blocklist_data_exceptions: + continue + assert forbidden_tr_id not in source, f"주문 TR_ID가 소스에 존재함: {forbidden_tr_id}" + + +def test_kis_client_module_defines_no_order_submission_function(): + import src.quant_engine.kis_api_client_v1 as kis_module + + public_names = [name for name in dir(kis_module) if not name.startswith("_")] + banned_keywords = ( + "place_order", "submit_order", "cancel_order", "revise_order", "send_order", + "inquire_balance", "account_balance", + ) + for name in public_names: + lowered = name.lower() + for banned in banned_keywords: + assert banned not in lowered, f"주문 제출/정정/취소로 의심되는 함수가 존재함: {name}" + + +def test_kis_credentials_load_uses_required_env_vars(monkeypatch): + monkeypatch.setenv("KIS_APP_Key", "real-key") + monkeypatch.setenv("KIS_APP_Secret", "real-secret") + monkeypatch.setenv("KIS_APP_Key_TEST", "mock-key") + monkeypatch.setenv("KIS_APP_Secret_TEST", "mock-secret") + + real = KisCredentials.load("real") + mock = KisCredentials.load("mock") + + assert real.app_key == "real-key" + assert real.app_secret == "real-secret" + assert real.account == "real" + assert mock.app_key == "mock-key" + assert mock.app_secret == "mock-secret" + assert mock.account == "mock" diff --git a/tests/unit/test_storage_backend_v1.py b/tests/unit/test_storage_backend_v1.py new file mode 100644 index 00000000..b1d5ed3e --- /dev/null +++ b/tests/unit/test_storage_backend_v1.py @@ -0,0 +1,32 @@ +from __future__ import annotations + +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +from src.quant_engine.storage_backend_v1 import StoreSpec, default_sqlite_store_path, normalize_store_spec + + +def test_default_sqlite_store_path_uses_named_subdir(tmp_path): + path = default_sqlite_store_path(tmp_path, "qualitative_sell_strategy/qualitative_sell_strategy.db") + assert str(path).endswith("qualitative_sell_strategy.db") + + +def test_normalize_store_spec_supports_sqlite_and_postgresql(tmp_path): + backend_sqlite, sqlite_location = normalize_store_spec(StoreSpec(location=tmp_path / "collector.db"), ROOT) + assert backend_sqlite == "sqlite" + assert str(sqlite_location).endswith("collector.db") + + backend_pg, pg_location = normalize_store_spec( + StoreSpec(backend="postgresql", location="postgresql://user:pass@localhost/db"), + ROOT, + ) + assert backend_pg == "postgresql" + assert "postgresql://" in str(pg_location) + + +def test_postgresql_upgrade_stub_script_exists(): + assert (ROOT / "tools" / "generate_postgresql_upgrade_stub_v1.py").exists() diff --git a/tests/unit/test_validate_gitea_secrets_contract_v1.py b/tests/unit/test_validate_gitea_secrets_contract_v1.py new file mode 100644 index 00000000..602d4627 --- /dev/null +++ b/tests/unit/test_validate_gitea_secrets_contract_v1.py @@ -0,0 +1,20 @@ +from __future__ import annotations + +import json +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +import tools.validate_gitea_secrets_contract_v1 as validator + + +def test_validate_gitea_secrets_contract_passes(): + rc = validator.main() + payload = json.loads((ROOT / "Temp" / "gitea_secrets_contract_v1.json").read_text(encoding="utf-8")) + + assert rc == 0 + assert payload["gate"] == "PASS" + assert payload["evidence"][".gitea/workflows/kis_data_collection.yml"]["secrets.KIS_APP_KEY"] is True diff --git a/tests/unit/test_validate_kis_api_credentials_v1.py b/tests/unit/test_validate_kis_api_credentials_v1.py new file mode 100644 index 00000000..7511fa44 --- /dev/null +++ b/tests/unit/test_validate_kis_api_credentials_v1.py @@ -0,0 +1,52 @@ +from __future__ import annotations + +import json +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +import tools.validate_kis_api_credentials_v1 as validator + + +class _FakeCreds: + def __init__(self, account: str): + self.account = account + self.domain = "https://openapi.koreainvestment.com:9443" if account == "real" else "https://openapivts.koreainvestment.com:29443" + self.app_key = f"{account}-key" + self.app_secret = f"{account}-secret" + + +def test_validate_kis_api_credentials_writes_pass_json(tmp_path, monkeypatch): + out = tmp_path / "kis_api_credentials_validation_v1.json" + + monkeypatch.setenv("KIS_APP_Key_TEST", "mock-key") + monkeypatch.setenv("KIS_APP_Secret_TEST", "mock-secret") + monkeypatch.setattr(validator, "KisCredentials", type("CredFactory", (), {"load": staticmethod(lambda account: _FakeCreds(account))})) + monkeypatch.setattr(validator, "get_current_price", lambda creds, ticker: {"ticker": ticker, "price": 1000}) + monkeypatch.setattr(sys, "argv", ["validate_kis_api_credentials_v1.py", "--account", "mock", "--ticker", "005930", "--output", str(out)]) + + rc = validator.main() + payload = json.loads(out.read_text(encoding="utf-8")) + + assert rc == 0 + assert payload["gate"] == "PASS" + assert payload["evidence"]["account"] == "mock" + assert payload["evidence"]["ticker"] == "005930" + + +def test_validate_kis_api_credentials_fails_when_api_call_errors(tmp_path, monkeypatch): + out = tmp_path / "kis_api_credentials_validation_v1.json" + + monkeypatch.setattr(validator, "KisCredentials", type("CredFactory", (), {"load": staticmethod(lambda account: _FakeCreds(account))})) + monkeypatch.setattr(validator, "get_current_price", lambda creds, ticker: (_ for _ in ()).throw(RuntimeError("boom"))) + monkeypatch.setattr(sys, "argv", ["validate_kis_api_credentials_v1.py", "--account", "mock", "--ticker", "005930", "--output", str(out)]) + + rc = validator.main() + payload = json.loads(out.read_text(encoding="utf-8")) + + assert rc == 1 + assert payload["gate"] == "FAIL" + assert payload["errors"] diff --git a/tools/generate_postgresql_upgrade_stub_v1.py b/tools/generate_postgresql_upgrade_stub_v1.py new file mode 100644 index 00000000..8e3c5e65 --- /dev/null +++ b/tools/generate_postgresql_upgrade_stub_v1.py @@ -0,0 +1,115 @@ +#!/usr/bin/env python3 +from __future__ import annotations + +import argparse +import json +from pathlib import Path +from typing import Any + +ROOT = Path(__file__).resolve().parents[1] + +TABLE_SCHEMAS: dict[str, str] = { + "collection_runs": """ +CREATE TABLE collection_runs ( + run_id TEXT PRIMARY KEY, + collector_name TEXT NOT NULL, + started_at TEXT NOT NULL, + finished_at TEXT, + status TEXT NOT NULL, + input_source TEXT, + output_json_path TEXT, + output_db_path TEXT, + notes TEXT, + created_at TIMESTAMPTZ DEFAULT NOW() +); +""".strip(), + "collection_snapshots": """ +CREATE TABLE collection_snapshots ( + run_id TEXT NOT NULL, + dataset_name TEXT NOT NULL, + ticker TEXT NOT NULL, + name TEXT, + sector TEXT, + as_of_date TEXT, + source_priority TEXT, + source_status TEXT, + payload_json TEXT NOT NULL, + provenance_json TEXT NOT NULL, + created_at TIMESTAMPTZ DEFAULT NOW(), + PRIMARY KEY (run_id, dataset_name, ticker) +); +""".strip(), + "collection_source_errors": """ +CREATE TABLE collection_source_errors ( + run_id TEXT NOT NULL, + ticker TEXT, + source_name TEXT NOT NULL, + error_kind TEXT NOT NULL, + error_message TEXT NOT NULL, + payload_json TEXT, + created_at TIMESTAMPTZ DEFAULT NOW() +); +""".strip(), + "sell_strategy_results": """ +CREATE TABLE sell_strategy_results ( + id BIGSERIAL PRIMARY KEY, + code TEXT NOT NULL, + generated_at TEXT NOT NULL, + action TEXT, + conviction TEXT, + market_regime TEXT, + composite_score DOUBLE PRECISION, + rationale TEXT, + raw_json TEXT NOT NULL, + inserted_at TIMESTAMPTZ DEFAULT NOW() +); +""".strip(), + "satellite_recommendations": """ +CREATE TABLE satellite_recommendations ( + id BIGSERIAL PRIMARY KEY, + ticker TEXT NOT NULL, + generated_at TEXT NOT NULL, + satellite_action TEXT, + attractiveness_score DOUBLE PRECISION, + market_regime TEXT, + raw_json TEXT NOT NULL, + inserted_at TIMESTAMPTZ DEFAULT NOW() +); +""".strip(), +} + + +def main() -> int: + ap = argparse.ArgumentParser(description="Emit PostgreSQL migration stub from current canonical row contract.") + ap.add_argument("--output-json", type=Path, default=ROOT / "Temp" / "postgresql_upgrade_stub_v1.json") + ap.add_argument("--output-sql", type=Path, default=ROOT / "Temp" / "postgresql_upgrade_stub_v1.sql") + args = ap.parse_args() + + sql_lines = [ + "-- PostgreSQL upgrade stub", + "-- This file is a contract placeholder only. It is not executed by CI.", + "", + ] + for name, ddl in TABLE_SCHEMAS.items(): + sql_lines.append(f"-- {name}") + sql_lines.append(ddl) + sql_lines.append("") + + sql_text = "\n".join(sql_lines).rstrip() + "\n" + args.output_sql.parent.mkdir(parents=True, exist_ok=True) + args.output_sql.write_text(sql_text, encoding="utf-8") + + payload: dict[str, Any] = { + "formula_id": "POSTGRESQL_UPGRADE_STUB_V1", + "gate": "DATA_GATED", + "tables": sorted(TABLE_SCHEMAS.keys()), + "output_sql": str(args.output_sql), + "note": "DDL stub only; execution deferred until PostgreSQL rollout.", + } + args.output_json.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8") + print(json.dumps(payload, ensure_ascii=False, indent=2)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/run_kis_data_collection_v1.py b/tools/run_kis_data_collection_v1.py new file mode 100644 index 00000000..61f75d82 --- /dev/null +++ b/tools/run_kis_data_collection_v1.py @@ -0,0 +1,15 @@ +#!/usr/bin/env python3 +from __future__ import annotations + +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +from src.quant_engine.kis_data_collection_v1 import main + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/validate_gitea_secrets_contract_v1.py b/tools/validate_gitea_secrets_contract_v1.py new file mode 100644 index 00000000..ef29a26e --- /dev/null +++ b/tools/validate_gitea_secrets_contract_v1.py @@ -0,0 +1,61 @@ +#!/usr/bin/env python3 +from __future__ import annotations + +import json +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + +REQUIRED_PATTERNS = { + ".gitea/workflows/kis_data_collection.yml": [ + "secrets.KIS_APP_KEY_TEST", + "secrets.KIS_APP_SECRET_TEST", + "secrets.KIS_APP_KEY", + "secrets.KIS_APP_SECRET", + ], + ".gitea/workflows/qualitative_sell_strategy.yml": [ + "secrets.KIS_APP_KEY_TEST", + "secrets.KIS_APP_SECRET_TEST", + "secrets.KIS_APP_KEY", + "secrets.KIS_APP_SECRET", + ], + ".gitea/workflows/ci.yml": [ + "secrets.KIS_APP_KEY_TEST", + "secrets.KIS_APP_SECRET_TEST", + ], +} + + +def main() -> int: + errors: list[str] = [] + evidence: dict[str, dict[str, bool]] = {} + + for rel, patterns in REQUIRED_PATTERNS.items(): + path = ROOT / rel + text = path.read_text(encoding="utf-8") if path.exists() else "" + file_evidence: dict[str, bool] = {} + if not path.exists(): + errors.append(f"missing:{rel}") + evidence[rel] = file_evidence + continue + for pattern in patterns: + found = pattern in text + file_evidence[pattern] = found + if not found: + errors.append(f"{rel}:{pattern}") + evidence[rel] = file_evidence + + result = { + "formula_id": "GITEA_SECRETS_CONTRACT_V1", + "gate": "PASS" if not errors else "FAIL", + "evidence": evidence, + "errors": errors, + } + out = ROOT / "Temp" / "gitea_secrets_contract_v1.json" + out.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8") + print(json.dumps(result, ensure_ascii=False, indent=2)) + return 0 if not errors else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/validate_kis_api_credentials_v1.py b/tools/validate_kis_api_credentials_v1.py new file mode 100644 index 00000000..5940fac9 --- /dev/null +++ b/tools/validate_kis_api_credentials_v1.py @@ -0,0 +1,106 @@ +#!/usr/bin/env python3 +from __future__ import annotations + +import argparse +import json +import sys +from pathlib import Path +from typing import Any + +ROOT = Path(__file__).resolve().parents[1] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +try: + from src.quant_engine.kis_api_client_v1 import ( + KisCredentials, + MOCK_DOMAIN, + REAL_DOMAIN, + _read_env_var, + get_current_price, + ) +except Exception as exc: # pragma: no cover - import failure is a hard validation error + KisCredentials = None # type: ignore[assignment] + MOCK_DOMAIN = "" + REAL_DOMAIN = "" + _read_env_var = None # type: ignore[assignment] + get_current_price = None # type: ignore[assignment] + _IMPORT_ERROR = str(exc) +else: + _IMPORT_ERROR = "" + + +def _payload(gate: str, **extra: Any) -> dict[str, Any]: + return { + "formula_id": "KIS_API_CREDENTIALS_VALIDATION_V1", + "gate": gate, + **extra, + } + + +def _expected_env_names(account: str) -> tuple[str, str]: + if account == "real": + return ("KIS_APP_Key", "KIS_APP_Secret") + if account == "mock": + return ("KIS_APP_Key_TEST", "KIS_APP_Secret_TEST") + raise ValueError("account must be 'mock' or 'real'") + + +def main() -> int: + ap = argparse.ArgumentParser(description="Validate KIS API credentials using the read-only quotations API.") + ap.add_argument("--account", choices=["mock", "real"], default="mock") + ap.add_argument("--ticker", default="005930") + ap.add_argument("--output", type=Path, default=ROOT / "Temp" / "kis_api_credentials_validation_v1.json") + args = ap.parse_args() + + if KisCredentials is None or get_current_price is None: + result = _payload("FAIL", error=f"import_error: {_IMPORT_ERROR}") + args.output.parent.mkdir(parents=True, exist_ok=True) + args.output.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8") + print(json.dumps(result, ensure_ascii=False, indent=2)) + return 1 + + errors: list[str] = [] + evidence: dict[str, Any] = { + "account": args.account, + "ticker": args.ticker, + } + + try: + key_name, secret_name = _expected_env_names(args.account) + creds = KisCredentials.load(args.account) + evidence["domain"] = creds.domain + evidence["expected_env"] = {"app_key": key_name, "app_secret": secret_name} + expected_key = _read_env_var(key_name) if _read_env_var is not None else None + expected_secret = _read_env_var(secret_name) if _read_env_var is not None else None + other_key = _read_env_var("KIS_APP_Key_TEST" if args.account == "real" else "KIS_APP_Key") if _read_env_var is not None else None + other_secret = _read_env_var("KIS_APP_Secret_TEST" if args.account == "real" else "KIS_APP_Secret") if _read_env_var is not None else None + actual_key = getattr(creds, "app_key", None) + actual_secret = getattr(creds, "app_secret", None) + evidence["env_match"] = { + "app_key": bool(expected_key and actual_key == expected_key), + "app_secret": bool(expected_secret and actual_secret == expected_secret), + "other_key_present": bool(other_key), + "other_secret_present": bool(other_secret), + } + if creds.domain != (REAL_DOMAIN if args.account == "real" else MOCK_DOMAIN): + errors.append("domain_mismatch") + if not evidence["env_match"]["app_key"] or not evidence["env_match"]["app_secret"]: + errors.append("selected_env_mismatch") + response = get_current_price(creds, args.ticker) + evidence["response_keys"] = sorted(response.keys()) + if not isinstance(response, dict) or not response: + errors.append("empty_response") + except Exception as exc: # noqa: BLE001 + errors.append(str(exc)) + + gate = "PASS" if not errors else "FAIL" + result = _payload(gate, evidence=evidence, errors=errors) + args.output.parent.mkdir(parents=True, exist_ok=True) + args.output.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8") + print(json.dumps(result, ensure_ascii=False, indent=2)) + return 0 if gate == "PASS" else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/validate_no_direct_api_trading_v1.py b/tools/validate_no_direct_api_trading_v1.py new file mode 100644 index 00000000..fa27e993 --- /dev/null +++ b/tools/validate_no_direct_api_trading_v1.py @@ -0,0 +1,112 @@ +#!/usr/bin/env python3 +"""[CRITICAL] governance/rules/06_no_direct_api_trading.yaml 강제 게이트. + +이 검증기는 순수 stdlib(re, pathlib)만 사용한다 — Synology CI(ARMv7, Python 3.8, +requests/pytest 미설치)에서도 항상 실행 가능해야 하는 하드 블로킹 게이트이기 때문이다. +문서·테스트만으로는 막을 수 없다는 사용자 지시(2026-06-21)에 따라 정적 소스 스캔으로 +주문 제출/정정/취소 경로·TR_ID가 코드베이스 어디에도 존재하지 않음을 매 커밋마다 강제한다. + +FAIL 시 CI 전체를 막는다(strict, warn_only 아님) — 다른 데이터 품질 게이트와 다르게 +이 게이트는 완화 대상이 아니다. +""" +from __future__ import annotations + +import re +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + +# 이 문자열들이 "데이터"로 등장해도 되는 파일(블록리스트 정의/테스트/이 검증기 자신). +# 그 외 모든 .py 파일에서 발견되면 FAIL. +ALLOWLISTED_FILES = { + "src/quant_engine/kis_api_client_v1.py", + "tests/unit/test_kis_api_client_v1.py", + "tools/validate_no_direct_api_trading_v1.py", +} + +FORBIDDEN_ORDER_PATH_SUBSTRINGS = ( + "/trading/order-cash", + "/trading/order-rvsecncl", + "/trading/order-credit", + "/trading/order-resv", + "/trading/inquire-balance", # governance/rules/07 — 계좌 보유종목 조회 금지 +) +FORBIDDEN_ORDER_TR_IDS = ( + "TTTC0802U", "TTTC0801U", "VTTC0802U", "VTTC0801U", + "TTTC8434R", "VTTC8434R", # governance/rules/07 — 주식잔고조회 금지 +) +BANNED_FUNCTION_NAME_SUBSTRINGS = ( + "place_order", "submit_order", "cancel_order", "revise_order", "send_order", + "order_cash", "order_credit", "order_rvsecncl", + "inquire_balance", "account_balance", # governance/rules/07 — 계좌 보유종목 조회 금지 +) + + +def _scan_python_files() -> list[str]: + violations: list[str] = [] + for dir_name in ("src", "tools"): + for path in (ROOT / dir_name).rglob("*.py"): + rel = path.relative_to(ROOT).as_posix() + if rel in ALLOWLISTED_FILES: + continue + text = path.read_text(encoding="utf-8", errors="ignore") + for forbidden in FORBIDDEN_ORDER_PATH_SUBSTRINGS: + if forbidden in text: + violations.append(f"{rel}: 주문 엔드포인트 경로 발견 — {forbidden!r}") + for tr_id in FORBIDDEN_ORDER_TR_IDS: + if tr_id in text: + violations.append(f"{rel}: 주문 TR_ID 발견 — {tr_id!r}") + for match in re.finditer(r"def\s+(\w+)\s*\(", text): + name = match.group(1).lower() + for banned in BANNED_FUNCTION_NAME_SUBSTRINGS: + if banned in name: + violations.append(f"{rel}: 주문 제출/정정/취소로 의심되는 함수명 — def {match.group(1)}(") + return violations + + +def _check_kis_client_guard_intact() -> list[str]: + """kis_api_client_v1.py가 실제로 존재하면, 가드 코드가 그대로 있는지 + _send_request가 + HTTP 호출 전에 _assert_read_only를 부르는지 순서를 확인한다.""" + client_path = ROOT / "src" / "quant_engine" / "kis_api_client_v1.py" + if not client_path.exists(): + return [] # 클라이언트가 아직 없으면 이 검사는 스킵(다른 검사로 충분) + + text = client_path.read_text(encoding="utf-8") + violations: list[str] = [] + required_markers = ("_assert_read_only", "OrderEndpointBlockedError", "FORBIDDEN_PATH_SUBSTRINGS", "FORBIDDEN_TR_ID_PREFIXES") + for marker in required_markers: + if marker not in text: + violations.append(f"kis_api_client_v1.py: 필수 가드 구성요소 누락 — {marker!r}") + + send_request_match = re.search(r"def _send_request\(.*?\)\s*(?:->[^:]*)?:(.*?)(?=\ndef |\Z)", text, re.S) + if send_request_match: + body = send_request_match.group(1) + guard_pos = body.find("_assert_read_only(") + http_pos = min( + (pos for pos in (body.find("requests.get("), body.find("requests.post(")) if pos != -1), + default=-1, + ) + if guard_pos == -1: + violations.append("kis_api_client_v1.py: _send_request가 _assert_read_only를 호출하지 않음") + elif http_pos != -1 and guard_pos > http_pos: + violations.append("kis_api_client_v1.py: _assert_read_only 호출이 HTTP 전송보다 늦음(순서 위반)") + else: + violations.append("kis_api_client_v1.py: _send_request 함수를 찾을 수 없음") + + return violations + + +def main() -> int: + violations = _scan_python_files() + _check_kis_client_guard_intact() + if violations: + print("NO_DIRECT_API_TRADING_GATE: FAIL") + for v in violations: + print(f" - {v}") + return 1 + print("NO_DIRECT_API_TRADING_GATE: PASS") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) From da0e1b0f7eedfc4daeedf757b612c5ed95b9af9a Mon Sep 17 00:00:00 2001 From: kjh2064 Date: Sun, 21 Jun 2026 20:05:55 +0900 Subject: [PATCH 02/10] =?UTF-8?q?=EB=B9=84=EA=B8=B0=EA=B3=84=EC=A0=81=20?= =?UTF-8?q?=EB=A7=A4=EB=8F=84=EC=A0=84=EB=9E=B5(=EA=B0=80=EC=B9=98?= =?UTF-8?q?=EB=B3=B4=EC=A1=B4)=20+=20=EC=9C=84=EC=84=B1=EC=A2=85=EB=AA=A9?= =?UTF-8?q?=20=EC=B6=94=EC=B2=9C=20=EC=97=94=EC=A7=84=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 매크로·실적·펀더멘털·공매도수급·호가미시구조·대내외 변수 5개 독립 팩터군의 confluence(최소 3/5 합의) 없이는 매도 트리거를 금지하는 정성적 매도판단 엔진과, 보유종목 제외 위성후보 추천 로직을 추가한다. - 단일 팩터 임계값 돌파만으로는 매도 신호를 생성하지 않음 (mechanical_sell_prohibited=true) - 데이터 결측 시 항상 DATA_MISSING/INSUFFICIENT_DATA_NO_ACTION — 추정값으로 채우지 않음 - KIS 호가10단계·공매도거래비중 + Naver 시세/수급 스크래핑 입력 연동 - SQLite 시계열 저장 + 사후 적중률 자체평가 (evaluate_qualitative_sell_strategy_accuracy_v1) - Gitea 일일 스케줄(장마감 후) + 파이프라인 계약 검증 게이트 --- .../workflows/qualitative_sell_strategy.yml | 84 ++++ spec/exit/qualitative_sell_strategy_v1.yaml | 153 +++++++ .../qualitative_sell_strategy_store_v1.py | 146 +++++++ .../qualitative_sell_strategy_v1.py | 377 ++++++++++++++++++ ...e_qualitative_sell_strategy_accuracy_v1.py | 81 ++++ ...test_qualitative_sell_strategy_store_v1.py | 70 ++++ .../unit/test_qualitative_sell_strategy_v1.py | 148 +++++++ ...e_qualitative_sell_strategy_pipeline_v1.py | 24 ++ tools/build_macro_context_from_workbook_v1.py | 204 ++++++++++ tools/build_qualitative_sell_inputs_v1.py | 342 ++++++++++++++++ ..._satellite_candidate_recommendations_v1.py | 139 +++++++ ...e_qualitative_sell_strategy_accuracy_v1.py | 143 +++++++ tools/fetch_naver_market_data_v1.py | 168 ++++++++ tools/fetch_trade_statistics_motie_v1.py | 186 +++++++++ ...e_qualitative_sell_strategy_pipeline_v1.py | 56 +++ 15 files changed, 2321 insertions(+) create mode 100644 .gitea/workflows/qualitative_sell_strategy.yml create mode 100644 spec/exit/qualitative_sell_strategy_v1.yaml create mode 100644 src/quant_engine/qualitative_sell_strategy_store_v1.py create mode 100644 src/quant_engine/qualitative_sell_strategy_v1.py create mode 100644 tests/unit/test_evaluate_qualitative_sell_strategy_accuracy_v1.py create mode 100644 tests/unit/test_qualitative_sell_strategy_store_v1.py create mode 100644 tests/unit/test_qualitative_sell_strategy_v1.py create mode 100644 tests/unit/test_validate_qualitative_sell_strategy_pipeline_v1.py create mode 100644 tools/build_macro_context_from_workbook_v1.py create mode 100644 tools/build_qualitative_sell_inputs_v1.py create mode 100644 tools/build_satellite_candidate_recommendations_v1.py create mode 100644 tools/evaluate_qualitative_sell_strategy_accuracy_v1.py create mode 100644 tools/fetch_naver_market_data_v1.py create mode 100644 tools/fetch_trade_statistics_motie_v1.py create mode 100644 tools/validate_qualitative_sell_strategy_pipeline_v1.py diff --git a/.gitea/workflows/qualitative_sell_strategy.yml b/.gitea/workflows/qualitative_sell_strategy.yml new file mode 100644 index 00000000..2ceec012 --- /dev/null +++ b/.gitea/workflows/qualitative_sell_strategy.yml @@ -0,0 +1,84 @@ +name: Qualitative Sell Strategy (Read-Only, SQLite Canonical) + +on: + schedule: + - cron: "0 10 * * 1-5" # KST 19:00-ish daily post-close batch window (UTC 10:00) + workflow_dispatch: + +jobs: + evaluate-qualitative-sell: + runs-on: self-hosted + + steps: + - name: Checkout Code + run: | + if [ -d .git ]; then + git remote set-url origin http://x-access-token:${{ secrets.GITHUB_TOKEN }}@192.168.123.100:8418/KimJaeHyun/myfinance.git + else + git init + git remote add origin http://x-access-token:${{ secrets.GITHUB_TOKEN }}@192.168.123.100:8418/KimJaeHyun/myfinance.git + fi + git fetch origin main --depth=1 + git reset --hard FETCH_HEAD + + - name: Configure Runtime Paths + run: | + export PATH=/usr/local/bin:$PATH + echo "/usr/local/bin" >> $GITHUB_PATH + /usr/bin/python3 --version + + - name: Setup Python Environment + run: | + VENV_BASE=/volume1/gitea/python_venv + REQ_HASH=$(md5sum tools/build_qualitative_sell_inputs_v1.py 2>/dev/null | cut -d' ' -f1 || echo "qual-default") + VENV="$VENV_BASE/$REQ_HASH" + if [ ! -f "$VENV/bin/python" ]; then + mkdir -p "$VENV_BASE" + /usr/bin/python3 -m venv "$VENV" + "$VENV/bin/pip" install --upgrade pip --quiet + "$VENV/bin/pip" install requests beautifulsoup4 pyyaml openpyxl --quiet + fi + echo "$VENV/bin" >> $GITHUB_PATH + + - name: "[CRITICAL] No Direct API Trading Gate" + run: python3 tools/validate_no_direct_api_trading_v1.py + + - name: "[CRITICAL] Validate KIS API Credentials (mock)" + env: + KIS_APP_Key_TEST: ${{ secrets.KIS_APP_KEY_TEST }} + KIS_APP_Secret_TEST: ${{ secrets.KIS_APP_SECRET_TEST }} + run: python3 tools/validate_kis_api_credentials_v1.py --account mock --ticker 005930 + + - name: Build Qualitative Sell Inputs (batch) + env: + KIS_APP_Key: ${{ secrets.KIS_APP_KEY }} + KIS_APP_Secret: ${{ secrets.KIS_APP_SECRET }} + run: | + if [ -f GatherTradingData.xlsx ]; then + python3 tools/build_qualitative_sell_inputs_v1.py \ + --batch \ + --workbook GatherTradingData.xlsx \ + --kis-account real \ + --apply + else + echo "GatherTradingData.xlsx missing -> skip batch build" + fi + + - name: Build Satellite Recommendations + run: | + if [ -f GatherTradingData.xlsx ]; then + python3 tools/build_satellite_candidate_recommendations_v1.py \ + --workbook GatherTradingData.xlsx \ + --apply + else + echo "GatherTradingData.xlsx missing -> skip satellite build" + fi + + - name: Evaluate Qualitative Sell Accuracy + run: | + if [ -f outputs/qualitative_sell_strategy/qualitative_sell_strategy.db ]; then + python3 tools/evaluate_qualitative_sell_strategy_accuracy_v1.py \ + --sqlite-db outputs/qualitative_sell_strategy/qualitative_sell_strategy.db + else + echo "qualitative_sell_strategy.db missing -> skip accuracy evaluation" + fi diff --git a/spec/exit/qualitative_sell_strategy_v1.yaml b/spec/exit/qualitative_sell_strategy_v1.yaml new file mode 100644 index 00000000..0740bdec --- /dev/null +++ b/spec/exit/qualitative_sell_strategy_v1.yaml @@ -0,0 +1,153 @@ +meta: + title: "은퇴자산포트폴리오 — 비기계적 매도전략(가치보존) 명세" + parent_file: "RetirementAssetPortfolio.yaml" + version: "2026-06-21-PHASE8_qualitative_sell" + language: "ko-KR" + timezone: "Asia/Seoul" + role: "canonical" + has_code_implementation: true + code_path: "src/quant_engine/qualitative_sell_strategy_v1.py" + purpose: > + 익절/손절을 고정 % 임계값으로 기계적으로 트리거하지 않고, 매크로·실적·펀더멘털· + 공매도수급·호가 미시구조·대내외 변수(대형 IPO·섹터 로테이션) 5개 독립 팩터군의 + 합의(confluence)로 매도/보유/추가 확신도를 산출해 주식가치를 최대치로 보존한다. + 현금부족 사유는 입력에서 의도적으로 배제한다. + +qualitative_sell_strategy: + policy: + execution: "보유 포지션 검토 시 항상 실행. STOP_PRICE_CORE_V1/PROFIT_RATCHET_TIERED_V2 등 + 기존 기계적 손절/래칫 라인과 병행 — 이 명세가 그것들을 대체하지 않으며, '서두르지 않는 + 재량적 정리' 판단을 보강한다." + confluence_rule: "5개 팩터군 중 최소 3개가 동일 방향(+/-)으로 합의해야 행동 생성. 단일 + 팩터의 임계값 돌파만으로 매도 트리거 금지." + cash_shortfall_exclusion: "현금부족·리밸런싱 강제매도 사유는 이 명세의 입력에서 제외한다. + 해당 사유의 매도는 spec/exit/value_preserving_cash_raise_optimizer_v7.yaml 책임." + date_basis: "review_window는 실제 실적발표일·고영향 매크로 이벤트일(spec/strategy/ + macro_event_synchronizer_v2.yaml:event_hold_gate)에서 역산한다. 임의 고정일 금지." + + factor_families: + macro_pressure: + id: "F1" + formula_ref: "spec/strategy/macro_event_synchronizer_v2.yaml:position_size_scale_formula" + sources: ["macro_risk_score", "FX", "금리", "산업통상부 수출입동향(섹터별)"] + note: "수출입 동향으로 섹터별 실적 선행지표를 추정해 가중." + + fundamental_trajectory: + id: "F2" + formula_ref: "spec/strategy/fundamental_quality_v3.yaml" + sources: ["EPS 추정치 변화", "영업이익률 추세", "실적발표 컨센서스 서프라이즈"] + + short_interest_pressure: + id: "F3" + formula_ref: "spec/13b_harness_formulas.yaml:formula_registry.formulas.SHORT_INTEREST_RISK_GAUGE_V1" + sources: ["공매도잔고율 추세", "공매도거래비중", "상대수익률", "거래량 이상", "실적전망"] + note: > + 잔고율은 '매수/매도 버튼'이 아니라 위험계기판. 잔고율이 낮은 종목(예: 현대로템형, + <1%)은 잔고율 자체보다 거래비중·상대수익률을 더 중요하게 본다. + + microstructure_pressure: + id: "F4" + sources: ["호가 10단계 매수/매도 잔량 불균형", "체결강도", "스프레드"] + note: "전략적 방향 결정에는 쓰지 않고 confluence가 SELL/ADD로 합의된 이후의 + '집행 타이밍'에만 사용 — execution_window 산정 보조." + + liquidity_rotation_risk: + id: "F5" + sources: ["대형 IPO 청약/상장에 따른 섹터 자금 이탈", "동일 섹터 로테이션", + "외국인/기관 섹터 비중 변화"] + + output: + formula_ref: "spec/13b_harness_formulas.yaml:formula_registry.formulas.QUALITATIVE_SELL_STRATEGY_V1" + python_tool: "src/quant_engine/qualitative_sell_strategy_v1.py:compute_qualitative_sell_strategy" + actions: + EXIT_REVIEW_FULL: "4-5개 팩터군 매도방향 합의 + composite_score>=0.6 — 전량 정리 검토" + TRIM_REVIEW_PARTIAL: "3개 이상 팩터군 매도방향 합의, composite_score<0.6 — 부분 정리 검토" + HOLD_ADD_CONVICTION: "3개 이상 팩터군 지지방향 합의 — 보유/추가 확신" + HOLD_NO_CONFLUENCE: "합의 미달 — 보유, 관찰 지속" + INSUFFICIENT_DATA_NO_ACTION: "confluence 판정에 필요한 최소 데이터 부족 — 추정 금지" + + market_regime: + formula_ref: "spec/13b_harness_formulas.yaml:formula_registry.formulas.MARKET_REGIME_CLASSIFIER_V1" + rule: "금리 상승기(RISING)=PERFORMANCE_MARKET(실적장세) — fundamental_trajectory 가중 상향. + 금리 보합/하락기(FLAT/FALLING)=TECHNICAL_MARKET(기술장세) — short_interest_pressure/ + microstructure_pressure 가중 상향. confluence 합의건수 판정 자체는 가중치와 무관 — + composite_score(행동 강도)에만 영향." + + satellite_candidate_score: + formula_ref: "spec/13b_harness_formulas.yaml:formula_registry.formulas.SATELLITE_CANDIDATE_SCORE_V1" + purpose: "미보유 위성 유니버스 종목의 BUY_CANDIDATE/WATCH/AVOID 사전 평가. sector_export_trend + (관세청/산업통상부 수출입동향)·fundamental_trajectory·relative_return_20d를 market_regime별 + 가중치로 종합." + + data_sources: + note: "2026-06-21 세션 실측 결과. investing.com 직접 스크래핑은 403(Cloudflare) 차단 확인 — + 자동 수집 경로로 채택하지 않는다." + relative_return_20d: + tool: "tools/fetch_naver_market_data_v1.py:compute_relative_return_20d" + source: "finance.naver.com/item/sise_day.naver (무인증, 동작 확인)" + status: "WORKING" + volume_ratio_5d: + tool: "tools/fetch_naver_market_data_v1.py:compute_volume_ratio_5d" + source: "finance.naver.com/item/sise_day.naver" + status: "WORKING" + foreign_institution_flow: + tool: "tools/fetch_naver_market_data_v1.py:fetch_foreign_institution_flow" + source: "finance.naver.com/item/frgn.naver (GAS gdc_01_fetch_fundamentals.gs와 동일 소스 — + 보유종목은 기존 GAS 수집 결과 재사용 권장, 위성 후보군만 직접 호출)" + status: "WORKING" + sector_export_trend: + tool: "tools/fetch_trade_statistics_motie_v1.py:compute_sector_export_trend" + source: "관세청/산업통상부 수출입통계 — 1차: --csv 수동 다운로드 경로(안정적, 권장). + 2차: data.go.kr OpenAPI(CUSTOMS_API_KEY 필요, 미설정 시 DATA_MISSING)." + status: "CSV_PATH_WORKING / API_PATH_NEEDS_KEY" + short_balance_ratio: + source: "KRX 공매도종합포털(open.krx.co.kr/contents/SRT) — 직접 API 호출은 OTP 세션 필요, + LOGOUT 응답으로 차단 확인. KIS Open API도 잔고율(보유 포지션 개념)은 제공하지 않음 + (실측 확인, 2026-06-21). 수동 다운로드 CSV(--short-csv)로만 안정 확보 — 자동화 + 재시도 불필요(차단 확정)." + status: "MANUAL_CSV_ONLY" + short_turnover_share: + source: "[2026-06-21 해결] KIS Open API daily-short-sale(FHPST04830000, + /uapi/domestic-stock/v1/quotations/daily-short-sale) output2.ssts_vol_rlim — + 실전계좌 도메인(--kis-account real)에서 실측 동작 확인. 모의계좌 도메인은 + 500 에러(미지원). Naver는 KRX iframe 위임으로 값 없음(폐기)." + tool: "tools/build_qualitative_sell_inputs_v1.py:fetch_kis_supplement" + status: "KIS_API_WORKING (real account only)" + microstructure_pressure_10_level_orderbook: + source: "[2026-06-21 해결] KIS Open API inquire-asking-price-exp-ccn(FHKST01010200, + /uapi/domestic-stock/v1/quotations/inquire-asking-price-exp-ccn) output1 — + 실전+모의계좌 도메인 모두 실측 동작 확인. 필드명: askp1~10/bidp1~10/ + askp_rsqn1~10/bidp_rsqn1~10/total_askp_rsqn/total_bidp_rsqn(전부 소문자, + 실측 확인). 전략 방향 결정에는 쓰지 않고 confluence 성립 후 집행 타이밍 + 보조로만 사용(factor_families.microstructure_pressure 참조)." + tool: "src/quant_engine/qualitative_sell_strategy_v1.py:compute_microstructure_pressure_from_orderbook" + status: "KIS_API_WORKING" + investor_trend_official: + source: "[참고, 미연동] KIS Open API inquire-investor(FHKST01010900) — + 개인/외국인/기관 순매수수량(prsn_ntby_qty/frgn_ntby_qty/orgn_ntby_qty) 등 실측 + 확인. Naver frgn.naver 스크래핑을 대체할 수 있는 공식 소스이나 아직 미연동 + (기존 GAS 수급 피드와 중복 — 필요 시 후속 작업)." + status: "VERIFIED_NOT_WIRED" + kis_open_api_constraints: + note: "[CRITICAL] governance/rules/06_no_direct_api_trading.yaml(주문 미실행), + governance/rules/07_no_kis_account_balance_query.yaml(계좌 보유종목 조회 금지) — + KIS API는 시장 전체 공개 데이터(시세/호가/공매도/투자자동향) 조회에만 사용. + CI 강제 게이트: tools/validate_no_direct_api_trading_v1.py(strict, warn_only 불가)." + macro_pressure / rate_trend / next_earnings_date / next_macro_event_date / macro_event_impact: + source: "기존 GAS 하네스(macro_event_synchronizer_v2, gas_event_calendar.gs)가 이미 + 산출/수집 — 중복 수집 금지, --context-json으로 그 결과를 주입." + status: "REUSE_EXISTING_HARNESS" + + orchestrator: + tool: "tools/build_qualitative_sell_inputs_v1.py" + purpose: "위 출처들을 종목별 ctx로 조립해 QUALITATIVE_SELL_STRATEGY_V1을 호출하고 + outputs/qualitative_sell_strategy/.json에 기록한다. --batch --workbook으로 + account_snapshot 실보유 종목 전체 일괄 처리." + + satellite_orchestrator: + tool: "tools/build_satellite_candidate_recommendations_v1.py" + purpose: "universe 시트(미보유 위성 유니버스)에서 보유종목을 제외한 후보 전체를 + SATELLITE_CANDIDATE_SCORE_V1로 평가해 outputs/qualitative_sell_strategy/ + satellite_recommendations.json에 기록한다. universe.Sector 한글 라벨은 부분 + 문자열 매칭으로 SECTOR_HS_MAP에 연결 — 매칭 실패 시 sector_export_trend를 + 추정하지 않고 None 유지(추정 금지 원칙)." diff --git a/src/quant_engine/qualitative_sell_strategy_store_v1.py b/src/quant_engine/qualitative_sell_strategy_store_v1.py new file mode 100644 index 00000000..5e1e14a7 --- /dev/null +++ b/src/quant_engine/qualitative_sell_strategy_store_v1.py @@ -0,0 +1,146 @@ +"""qualitative_sell_strategy_v1 산출물의 SQLite 시계열 저장소. + +GAS/xlsx 구조와 완전히 분리된 추가(additive) 저장소다 — 이 모듈이 다루는 데이터는 +순수 Python 산출물(KIS API 수집 + confluence 판단 결과)이며, GAS가 쓰지도 읽지도 +않고 사람이 시트에서 직접 편집하지도 않는다. 기존 outputs/qualitative_sell_strategy/ +*.json 파일 출력을 대체하지 않고 병행 저장한다(JSON은 1회성 점검용, SQLite는 시계열 +추이 조회용). 표준 라이브러리 sqlite3만 사용 — 추가 의존성 없음. +""" +from __future__ import annotations + +import json +import sqlite3 +from pathlib import Path +from dataclasses import dataclass +from typing import Any + +from src.quant_engine.storage_backend_v1 import StoreSpec, default_sqlite_store_path, normalize_store_spec + +SCHEMA = """ +CREATE TABLE IF NOT EXISTS sell_strategy_results ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + code TEXT NOT NULL, + generated_at TEXT NOT NULL, + action TEXT, + conviction TEXT, + market_regime TEXT, + composite_score REAL, + rationale TEXT, + raw_json TEXT NOT NULL, + inserted_at TEXT DEFAULT (datetime('now')) +); +CREATE INDEX IF NOT EXISTS idx_sell_strategy_code_time + ON sell_strategy_results(code, generated_at); + +CREATE TABLE IF NOT EXISTS satellite_recommendations ( + id INTEGER PRIMARY KEY AUTOINCREMENT, + ticker TEXT NOT NULL, + generated_at TEXT NOT NULL, + satellite_action TEXT, + attractiveness_score REAL, + market_regime TEXT, + raw_json TEXT NOT NULL, + inserted_at TEXT DEFAULT (datetime('now')) +); +CREATE INDEX IF NOT EXISTS idx_satellite_ticker_time + ON satellite_recommendations(ticker, generated_at); +""" + + +@dataclass(frozen=True) +class QualitativeSellStoreSpec(StoreSpec): + pass + + +def default_qualitative_sell_store_path(root: Path) -> Path: + return default_sqlite_store_path(root, "qualitative_sell_strategy/qualitative_sell_strategy.db") + + +def resolve_store_path(spec: QualitativeSellStoreSpec, root: Path) -> Path: + backend, location = normalize_store_spec( + spec, + root, + default_sqlite_name="qualitative_sell_strategy/qualitative_sell_strategy.db", + ) + if backend != "sqlite": + raise ValueError( + "qualitative_sell_strategy_store_v1 currently executes on sqlite only; " + "the caller contract already allows future PostgreSQL swap-in." + ) + return Path(location) + + +def init_db(db_path: Path) -> None: + db_path.parent.mkdir(parents=True, exist_ok=True) + conn = sqlite3.connect(db_path) + try: + conn.executescript(SCHEMA) + conn.commit() + finally: + conn.close() + + +def insert_sell_strategy_result(db_path: Path, result: dict[str, Any]) -> None: + """build_qualitative_sell_inputs_v1.process_one()의 반환값(dict)을 그대로 받는다.""" + init_db(db_path) + decision = result.get("decision") or {} + conn = sqlite3.connect(db_path) + try: + conn.execute( + "INSERT INTO sell_strategy_results " + "(code, generated_at, action, conviction, market_regime, composite_score, rationale, raw_json) " + "VALUES (?, ?, ?, ?, ?, ?, ?, ?)", + ( + result.get("code"), + result.get("generated_at"), + decision.get("action"), + decision.get("conviction"), + decision.get("market_regime"), + decision.get("composite_score"), + decision.get("rationale"), + json.dumps(result, ensure_ascii=False, default=str), + ), + ) + conn.commit() + finally: + conn.close() + + +def insert_satellite_recommendation(db_path: Path, generated_at: str, candidate: dict[str, Any]) -> None: + """build_satellite_candidate_recommendations_v1.py results[i] 항목 하나를 받는다.""" + init_db(db_path) + score = candidate.get("score") or {} + conn = sqlite3.connect(db_path) + try: + conn.execute( + "INSERT INTO satellite_recommendations " + "(ticker, generated_at, satellite_action, attractiveness_score, market_regime, raw_json) " + "VALUES (?, ?, ?, ?, ?, ?)", + ( + candidate.get("ticker"), + generated_at, + score.get("satellite_action"), + score.get("attractiveness_score"), + score.get("market_regime"), + json.dumps(candidate, ensure_ascii=False, default=str), + ), + ) + conn.commit() + finally: + conn.close() + + +def fetch_recent_sell_strategy_results(db_path: Path, code: str, limit: int = 20) -> list[dict[str, Any]]: + if not db_path.exists(): + return [] + conn = sqlite3.connect(db_path) + conn.row_factory = sqlite3.Row + try: + rows = conn.execute( + "SELECT code, generated_at, action, conviction, market_regime, composite_score, rationale " + "FROM sell_strategy_results WHERE code = ? ORDER BY generated_at DESC LIMIT ?", + (code, limit), + ).fetchall() + return [dict(row) for row in rows] + finally: + conn.close() diff --git a/src/quant_engine/qualitative_sell_strategy_v1.py b/src/quant_engine/qualitative_sell_strategy_v1.py new file mode 100644 index 00000000..67858def --- /dev/null +++ b/src/quant_engine/qualitative_sell_strategy_v1.py @@ -0,0 +1,377 @@ +from __future__ import annotations + +import math +from datetime import date, timedelta +from typing import Any + +# 매도 결정에 동원하는 5개 독립 팩터군. 단일 팩터의 임계값 돌파만으로는 행동을 +# 트리거하지 않는다 — 최소 CONFLUENCE_MIN개 팩터군이 동일 방향으로 합의해야 +# SELL/ADD 확신도가 성립한다. (기계적 단일 트리거 매도 금지 원칙) +FACTOR_FAMILIES: tuple[str, ...] = ( + "macro_pressure", + "fundamental_trajectory", + "short_interest_pressure", + "microstructure_pressure", + "liquidity_rotation_risk", +) +CONFLUENCE_MIN = 3 +EVENT_PRE_GUARD_DAYS = 5 # macro_event_synchronizer_v2.event_hold_gate와 동일 — HIGH 이벤트 5일 전 +EVENT_POST_GUARD_DAYS = 2 # 이벤트 후 2일 변동성 소화 구간 + +# 금리국면별 시장 성격: 금리 상승기=실적장세(펀더멘털/수출입 실적이 가격을 주도), +# 금리 보합·하락기=기술장세(수급·미시구조가 가격을 주도). 동일한 5팩터라도 +# 국면에 따라 가중치를 달리 줘야 confluence가 의미를 갖는다. +REGIME_FLAT_WEIGHTS: dict[str, float] = {family: 1.0 for family in FACTOR_FAMILIES} +REGIME_WEIGHT_TABLE: dict[str, dict[str, float]] = { + "PERFORMANCE_MARKET": { # 금리 상승기 — 실적/수출입 펀더멘털 가중 상향 + "macro_pressure": 1.2, + "fundamental_trajectory": 1.8, + "short_interest_pressure": 1.0, + "microstructure_pressure": 0.5, + "liquidity_rotation_risk": 1.0, + }, + "TECHNICAL_MARKET": { # 금리 보합·하락기 — 수급/미시구조 가중 상향 + "macro_pressure": 0.8, + "fundamental_trajectory": 0.8, + "short_interest_pressure": 1.3, + "microstructure_pressure": 1.6, + "liquidity_rotation_risk": 1.3, + }, + "NEUTRAL": REGIME_FLAT_WEIGHTS, +} + + +def classify_market_regime(rate_trend: str | None) -> str: + """금리 추세 문자열(RISING/FLAT/FALLING)을 실적장세/기술장세로 분류. + + RISING → PERFORMANCE_MARKET(실적장세): 금리 상승기엔 유동성보다 실적/펀더멘털이 + 가격을 결정. FLAT/FALLING → TECHNICAL_MARKET(기술장세): 유동성이 풍부해 수급· + 미시구조·테마성 모멘텀이 가격을 주도. 입력 결측 시 NEUTRAL(가중치 변화 없음). + """ + trend = str(rate_trend or "").upper() + if trend == "RISING": + return "PERFORMANCE_MARKET" + if trend in {"FLAT", "FALLING"}: + return "TECHNICAL_MARKET" + return "NEUTRAL" + + +def _finite(value: Any) -> bool: + return isinstance(value, (int, float)) and math.isfinite(float(value)) + + +def compute_short_interest_composite(ctx: dict[str, Any]) -> dict[str, Any]: + """SHORT_INTEREST_RISK_GAUGE_V1. + + 5요소: 공매도잔고율 변화, 공매도거래비중, 상대수익률(섹터/지수 대비), + 거래량 이상, 실적전망. 잔고율 단독으로는 매도 근거가 약함(현대로템형) — + 잔고율이 낮을 때는 거래비중·상대수익률 가중치를 자동 상향한다. + """ + missing: list[str] = [] + + short_balance_ratio = ctx.get("short_balance_ratio") # %, 현재 잔고율 + short_balance_ratio_chg_20d = ctx.get("short_balance_ratio_chg_20d") # %p, 20일 변화 + short_turnover_share = ctx.get("short_turnover_share") # 당일 거래 중 공매도 비중 % + relative_return_20d = ctx.get("relative_return_20d") # 종목수익률 - 섹터(or지수)수익률, %p + volume_ratio_5d = ctx.get("volume_ratio_5d") # 5일평균거래량 대비 비율 + earnings_outlook = str(ctx.get("earnings_outlook") or "").upper() # IMPROVING|STABLE|DETERIORATING|UNKNOWN + + for name, value in ( + ("short_balance_ratio", short_balance_ratio), + ("short_turnover_share", short_turnover_share), + ("relative_return_20d", relative_return_20d), + ): + if not _finite(value): + missing.append(name) + + if missing: + return { + "short_interest_pressure": None, + "status": "DATA_MISSING", + "missing_inputs": missing, + "note": "잔고율/거래비중/상대수익률 중 결측 — 공매도 합성 점수를 산출하지 않음(추정 금지)", + } + + low_balance_regime = float(short_balance_ratio) < 1.0 # 잔고율 1% 미만이면 '낮은 잔고율' 취급(현대로템형) + + # 잔고율 추세: 상승=매도근거 강화, 하락=매도근거 약화(혹은 매수근거) + balance_trend_signal = 0.0 + if _finite(short_balance_ratio_chg_20d): + balance_trend_signal = max(-1.0, min(1.0, float(short_balance_ratio_chg_20d) / 1.5)) + + turnover_signal = max(-1.0, min(1.0, (float(short_turnover_share) - 8.0) / 12.0)) # 8% 기준선 + relative_return_signal = max(-1.0, min(1.0, -float(relative_return_20d) / 10.0)) # 상대 약세일수록 + + volume_signal = 0.0 + if _finite(volume_ratio_5d): + volume_signal = max(-1.0, min(1.0, (float(volume_ratio_5d) - 1.0))) + + outlook_signal = { + "IMPROVING": -0.6, + "STABLE": 0.0, + "DETERIORATING": 0.7, + }.get(earnings_outlook, 0.0) + + if low_balance_regime: + # 잔고율 자체는 약한 근거 — 거래비중·상대수익률 가중치 상향, 잔고율추세 가중치 하향 + weights = {"balance": 0.10, "turnover": 0.30, "relative": 0.30, "volume": 0.10, "outlook": 0.20} + else: + weights = {"balance": 0.30, "turnover": 0.20, "relative": 0.20, "volume": 0.10, "outlook": 0.20} + + pressure = ( + balance_trend_signal * weights["balance"] + + turnover_signal * weights["turnover"] + + relative_return_signal * weights["relative"] + + volume_signal * weights["volume"] + + outlook_signal * weights["outlook"] + ) + pressure = max(-1.0, min(1.0, pressure)) + + label = "ELEVATED_SHORT_PRESSURE" if pressure >= 0.5 else "WATCH" if pressure >= 0.2 else \ + "SHORT_COVERING_SUPPORTIVE" if pressure <= -0.5 else "NEUTRAL" + + return { + "short_interest_pressure": round(pressure, 4), + "status": "OK", + "low_balance_regime": low_balance_regime, + "label": label, + "components": { + "balance_trend_signal": round(balance_trend_signal, 4), + "turnover_signal": round(turnover_signal, 4), + "relative_return_signal": round(relative_return_signal, 4), + "volume_signal": round(volume_signal, 4), + "outlook_signal": outlook_signal, + }, + "weights_used": weights, + } + + +def compute_microstructure_pressure_from_orderbook(orderbook_output1: dict[str, Any]) -> dict[str, Any]: + """MICROSTRUCTURE_PRESSURE_FROM_ORDERBOOK_V1. + + KIS Open API FHKST01010200(주식현재가 호가/예상체결) output1의 10단계 호가 잔량을 + -1(매수우위/지지)~+1(매도우위/압력)로 계량화. 실측 확인된 필드명(2026-06-21, + 005930 라이브 호출): total_askp_rsqn, total_bidp_rsqn(10단계 합계 잔량). + 이 점수는 전략 방향 결정에는 쓰지 않고 confluence가 성립한 이후의 '집행 타이밍' + 보조로만 사용한다(spec/exit/qualitative_sell_strategy_v1.yaml:factor_families. + microstructure_pressure 참조). + """ + total_askp = orderbook_output1.get("total_askp_rsqn") + total_bidp = orderbook_output1.get("total_bidp_rsqn") + try: + total_askp = float(total_askp) + total_bidp = float(total_bidp) + except (TypeError, ValueError): + return {"microstructure_pressure": None, "status": "DATA_MISSING"} + + denom = total_askp + total_bidp + if denom <= 0: + return {"microstructure_pressure": None, "status": "DATA_MISSING"} + + pressure = max(-1.0, min(1.0, (total_askp - total_bidp) / denom)) + return { + "microstructure_pressure": round(pressure, 4), + "status": "OK", + "total_askp_rsqn": total_askp, + "total_bidp_rsqn": total_bidp, + } + + +def _event_review_window( + today: date, + pressure_sign: int, + next_earnings_date: date | None, + next_macro_event_date: date | None, + macro_event_impact: str | None, + earnings_outlook: str, +) -> dict[str, Any]: + """캘린더 기반 검토 구간 산출 — 임의 날짜 고정이 아니라 실제 이벤트 일정에서 역산.""" + candidates: list[tuple[date, str]] = [] + + if next_earnings_date is not None: + if pressure_sign < 0 and earnings_outlook == "DETERIORATING": + # 실적 악화 전망 + 매도압력 → 실적발표 전 정리(서프라이즈 리스크 회피) + candidates.append((next_earnings_date - timedelta(days=EVENT_PRE_GUARD_DAYS), "PRE_EARNINGS_EXIT_BEFORE_SURPRISE_RISK")) + elif pressure_sign < 0 and earnings_outlook in {"IMPROVING", "STABLE"}: + # 단기 기술적 매도압력이지만 실적전망은 양호 → 발표 직전 매도는 가치훼손, 발표 이후로 연기 + candidates.append((next_earnings_date + timedelta(days=EVENT_POST_GUARD_DAYS), "DEFER_TO_POST_EARNINGS_AVOID_PREMATURE_EXIT")) + elif pressure_sign > 0: + # 추가매수/보유 신호 — 발표 변동성 통과 후 확신 재평가 + candidates.append((next_earnings_date + timedelta(days=EVENT_POST_GUARD_DAYS), "REASSESS_AFTER_EARNINGS_CONFIRM")) + + if next_macro_event_date is not None and str(macro_event_impact or "").upper() in {"HIGH", "VERY_HIGH"}: + if pressure_sign < 0: + candidates.append((next_macro_event_date - timedelta(days=EVENT_PRE_GUARD_DAYS), "PRE_MACRO_EVENT_DERISK")) + else: + candidates.append((next_macro_event_date + timedelta(days=EVENT_POST_GUARD_DAYS), "POST_MACRO_EVENT_CONFIRM")) + + if not candidates: + return { + "review_window_start": today.isoformat(), + "review_window_end": (today + timedelta(days=10)).isoformat(), + "window_basis": "NO_SCHEDULED_EVENT_DEFAULT_10D_REVIEW", + } + + earliest = min(candidates, key=lambda item: item[0]) + window_start = max(today, earliest[0] - timedelta(days=2)) + window_end = earliest[0] + timedelta(days=2) + return { + "review_window_start": window_start.isoformat(), + "review_window_end": window_end.isoformat(), + "window_basis": earliest[1], + } + + +def compute_qualitative_sell_strategy(ctx: dict[str, Any]) -> dict[str, Any]: + """QUALITATIVE_SELL_STRATEGY_V1. + + 매크로/실적/펀더멘털/공매도수급/호가미시구조/대내외(IPO·로테이션) 5개 + 독립 팩터군의 합의(confluence)로만 행동을 생성한다. 현금부족 사유는 + 입력에서 의도적으로 배제(cash_shortfall_excluded=True) — 가치보존이 + 유일한 목적 함수. + """ + today_raw = ctx.get("today") + today = today_raw if isinstance(today_raw, date) else date.today() + + factor_values: dict[str, float | None] = {} + missing_factors: list[str] = [] + for family in FACTOR_FAMILIES: + value = ctx.get(family) + if _finite(value): + factor_values[family] = max(-1.0, min(1.0, float(value))) + else: + factor_values[family] = None + missing_factors.append(family) + + available = {k: v for k, v in factor_values.items() if v is not None} + if len(available) < CONFLUENCE_MIN: + return { + "action": "INSUFFICIENT_DATA_NO_ACTION", + "conviction": "NONE", + "available_factors": list(available.keys()), + "missing_factors": missing_factors, + "rationale": "5개 팩터군 중 confluence 판정에 필요한 최소 데이터가 부족 — 추정으로 행동 생성 금지", + "cash_shortfall_excluded": True, + "mechanical_sell_prohibited": True, + } + + # 부호 규약: 모든 팩터군은 +1(매도압력 최대) ~ -1(보유/추가 지지 최대) 동일 스케일. + # short_interest_pressure도 동일 — ELEVATED_SHORT_PRESSURE(+) / SHORT_COVERING_SUPPORTIVE(-). + # confluence 합의 카운트는 국면 가중치와 무관하게 원시 방향성으로만 판정한다 + # (가중치는 행동 '강도'에만 영향 — 합의 성립 여부 자체를 왜곡하지 않는다). + sell_agree = [k for k, v in available.items() if v >= 0.30] + hold_add_agree = [k for k, v in available.items() if v <= -0.30] + + market_regime = classify_market_regime(ctx.get("rate_trend")) if "market_regime" not in ctx else str(ctx.get("market_regime") or "NEUTRAL").upper() + regime_weights = REGIME_WEIGHT_TABLE.get(market_regime, REGIME_FLAT_WEIGHTS) + weighted_sum = sum(available[k] * regime_weights.get(k, 1.0) for k in available) + weight_total = sum(regime_weights.get(k, 1.0) for k in available) + composite_score = weighted_sum / weight_total if weight_total else 0.0 + + earnings_outlook = str(ctx.get("earnings_outlook") or "STABLE").upper() + next_earnings_date = ctx.get("next_earnings_date") if isinstance(ctx.get("next_earnings_date"), date) else None + next_macro_event_date = ctx.get("next_macro_event_date") if isinstance(ctx.get("next_macro_event_date"), date) else None + macro_event_impact = ctx.get("macro_event_impact") + + if len(sell_agree) >= CONFLUENCE_MIN: + conviction = "HIGH" if len(sell_agree) >= 4 else "MEDIUM" + action = "EXIT_REVIEW_FULL" if composite_score >= 0.6 else "TRIM_REVIEW_PARTIAL" + pressure_sign = -1 + rationale = f"매도압력 합의({len(sell_agree)}/{len(available)} 팩터군 매도방향 합치): " + ", ".join(sell_agree) + elif len(hold_add_agree) >= CONFLUENCE_MIN: + conviction = "HIGH" if len(hold_add_agree) >= 4 else "MEDIUM" + action = "HOLD_ADD_CONVICTION" + pressure_sign = 1 + rationale = f"보유/추가 근거 합의({len(hold_add_agree)}/{len(available)} 팩터군 지지방향 합치): " + ", ".join(hold_add_agree) + else: + conviction = "LOW" + action = "HOLD_NO_CONFLUENCE" + pressure_sign = 0 + rationale = "팩터군 간 합의 미달 — 단일/소수 팩터의 임계값 돌파만으로는 매도 트리거 금지" + + window = _event_review_window( + today=today, + pressure_sign=pressure_sign, + next_earnings_date=next_earnings_date, + next_macro_event_date=next_macro_event_date, + macro_event_impact=macro_event_impact, + earnings_outlook=earnings_outlook, + ) if pressure_sign != 0 else None + + return { + "action": action, + "conviction": conviction, + "market_regime": market_regime, + "composite_score": round(composite_score, 4), + "sell_agreeing_factors": sell_agree, + "hold_add_agreeing_factors": hold_add_agree, + "missing_factors": missing_factors, + "review_window": window, + "rationale": rationale, + "cash_shortfall_excluded": True, + "mechanical_sell_prohibited": True, + } + + +def compute_satellite_candidate_score(ctx: dict[str, Any]) -> dict[str, Any]: + """SATELLITE_CANDIDATE_SCORE_V1. + + 미보유 유니버스 종목을 섹터 수출입 전망(sector_export_trend) + 펀더멘털 + 추세 + 국면적합도로 평가해 WATCH/BUY_CANDIDATE/AVOID를 산출한다. 보유종목 + 매도판단(compute_qualitative_sell_strategy)과 동일한 부호 규약을 쓰지 않고 + 별도 -1(약세)~+1(강세) 매력도 스케일을 쓴다 — 매수후보 평가와 매도판단은 + 목적함수가 다르므로 동일 점수를 재사용하지 않는다. + """ + sector_export_trend = ctx.get("sector_export_trend") # %, 섹터 수출 YoY/MoM 추세 + fundamental_trajectory = ctx.get("fundamental_trajectory") # -1(악화)~+1(개선), 매도엔진과 동일 정의역이나 부호 반대 해석 주의 + relative_return_20d = ctx.get("relative_return_20d") + market_regime = str(ctx.get("market_regime") or classify_market_regime(ctx.get("rate_trend"))).upper() + + missing = [name for name, value in ( + ("sector_export_trend", sector_export_trend), + ("fundamental_trajectory", fundamental_trajectory), + ) if not _finite(value)] + if missing: + return { + "satellite_action": "INSUFFICIENT_DATA_NO_ACTION", + "missing_inputs": missing, + "market_regime": market_regime, + } + + export_signal = max(-1.0, min(1.0, float(sector_export_trend) / 10.0)) + fundamental_signal = max(-1.0, min(1.0, -float(fundamental_trajectory))) # 매도엔진 부호(+)=악화 -> 매력도는 반전 + relative_signal = max(-1.0, min(1.0, float(relative_return_20d) / 10.0)) if _finite(relative_return_20d) else 0.0 + + if market_regime == "PERFORMANCE_MARKET": + weights = {"export": 0.45, "fundamental": 0.40, "relative": 0.15} + elif market_regime == "TECHNICAL_MARKET": + weights = {"export": 0.20, "fundamental": 0.25, "relative": 0.55} + else: + weights = {"export": 0.34, "fundamental": 0.33, "relative": 0.33} + + attractiveness = ( + export_signal * weights["export"] + + fundamental_signal * weights["fundamental"] + + relative_signal * weights["relative"] + ) + attractiveness = max(-1.0, min(1.0, attractiveness)) + + if attractiveness >= 0.5: + satellite_action = "BUY_CANDIDATE" + elif attractiveness >= 0.2: + satellite_action = "WATCH" + elif attractiveness <= -0.4: + satellite_action = "AVOID" + else: + satellite_action = "NEUTRAL_NO_EDGE" + + return { + "satellite_action": satellite_action, + "attractiveness_score": round(attractiveness, 4), + "market_regime": market_regime, + "components": { + "export_signal": round(export_signal, 4), + "fundamental_signal": round(fundamental_signal, 4), + "relative_signal": round(relative_signal, 4), + }, + "weights_used": weights, + } diff --git a/tests/unit/test_evaluate_qualitative_sell_strategy_accuracy_v1.py b/tests/unit/test_evaluate_qualitative_sell_strategy_accuracy_v1.py new file mode 100644 index 00000000..c805401e --- /dev/null +++ b/tests/unit/test_evaluate_qualitative_sell_strategy_accuracy_v1.py @@ -0,0 +1,81 @@ +from __future__ import annotations + +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +from tools.evaluate_qualitative_sell_strategy_accuracy_v1 import ( + _scoreable_direction, + build_accuracy_report, + evaluate_decision, +) +from src.quant_engine.qualitative_sell_strategy_store_v1 import insert_sell_strategy_result + + +def test_scoreable_direction(): + assert _scoreable_direction("EXIT_REVIEW_FULL") == -1 + assert _scoreable_direction("TRIM_REVIEW_PARTIAL") == -1 + assert _scoreable_direction("HOLD_ADD_CONVICTION") == 1 + assert _scoreable_direction("HOLD_NO_CONFLUENCE") is None + assert _scoreable_direction("INSUFFICIENT_DATA_NO_ACTION") is None + + +def test_evaluate_decision_sell_success_when_price_drops(): + decision = {"action": "EXIT_REVIEW_FULL"} + result = evaluate_decision(decision, price_at_decision=100.0, price_after=90.0) + assert result["success"] is True + assert result["realized_return_pct"] == -10.0 + + +def test_evaluate_decision_sell_failure_when_price_rises(): + decision = {"action": "TRIM_REVIEW_PARTIAL"} + result = evaluate_decision(decision, price_at_decision=100.0, price_after=110.0) + assert result["success"] is False + + +def test_evaluate_decision_hold_add_success_when_price_rises(): + decision = {"action": "HOLD_ADD_CONVICTION"} + result = evaluate_decision(decision, price_at_decision=100.0, price_after=105.0) + assert result["success"] is True + + +def test_evaluate_decision_returns_none_for_non_directional_action(): + assert evaluate_decision({"action": "HOLD_NO_CONFLUENCE"}, 100.0, 105.0) is None + + +def test_build_accuracy_report_data_gated_when_sample_too_small(tmp_path): + db_path = tmp_path / "test.db" + insert_sell_strategy_result(db_path, { + "code": "005930", "generated_at": "2026-06-01T12:00:00", + "decision": {"action": "EXIT_REVIEW_FULL"}, + }) + report = build_accuracy_report(db_path, price_lookup={ + "005930": {"2026-06-01": 100.0, "2026-06-06": 90.0}, + }) + assert report["status"] == "DATA_GATED" + assert report["scored_sample_count"] == 1 + + +def test_build_accuracy_report_ok_with_enough_samples(tmp_path): + db_path = tmp_path / "test.db" + price_lookup: dict = {} + for i in range(12): + code = f"00000{i % 3}" + gen_at = f"2026-05-{(i % 20) + 1:02d}T12:00:00" + insert_sell_strategy_result(db_path, { + "code": code, "generated_at": gen_at, + "decision": {"action": "EXIT_REVIEW_FULL"}, + }) + date_key = gen_at[:10] + future_key = ( + __import__("datetime").date.fromisoformat(date_key) + __import__("datetime").timedelta(days=5) + ).isoformat() + price_lookup.setdefault(code, {})[date_key] = 100.0 + price_lookup[code][future_key] = 90.0 # 매도신호 후 하락 — success + report = build_accuracy_report(db_path, price_lookup) + assert report["status"] == "OK" + assert report["hit_rate_pct"] == 100.0 + assert report["scored_sample_count"] == 12 diff --git a/tests/unit/test_qualitative_sell_strategy_store_v1.py b/tests/unit/test_qualitative_sell_strategy_store_v1.py new file mode 100644 index 00000000..23ad288c --- /dev/null +++ b/tests/unit/test_qualitative_sell_strategy_store_v1.py @@ -0,0 +1,70 @@ +from __future__ import annotations + +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +from src.quant_engine.qualitative_sell_strategy_store_v1 import ( + QualitativeSellStoreSpec, + fetch_recent_sell_strategy_results, + insert_satellite_recommendation, + insert_sell_strategy_result, + resolve_store_path, +) + + +def test_insert_and_fetch_sell_strategy_result(tmp_path): + db_path = tmp_path / "test.db" + result = { + "code": "005930", + "generated_at": "2026-06-21T12:00:00+09:00", + "decision": { + "action": "TRIM_REVIEW_PARTIAL", + "conviction": "MEDIUM", + "market_regime": "TECHNICAL_MARKET", + "composite_score": 0.42, + "rationale": "test rationale", + }, + } + insert_sell_strategy_result(db_path, result) + rows = fetch_recent_sell_strategy_results(db_path, "005930") + assert len(rows) == 1 + assert rows[0]["action"] == "TRIM_REVIEW_PARTIAL" + assert rows[0]["composite_score"] == 0.42 + + +def test_fetch_returns_empty_list_when_db_missing(tmp_path): + rows = fetch_recent_sell_strategy_results(tmp_path / "nonexistent.db", "005930") + assert rows == [] + + +def test_multiple_inserts_ordered_by_generated_at_desc(tmp_path): + db_path = tmp_path / "test.db" + for ts in ("2026-06-19T12:00:00", "2026-06-21T12:00:00", "2026-06-20T12:00:00"): + insert_sell_strategy_result(db_path, { + "code": "005930", "generated_at": ts, + "decision": {"action": "HOLD_NO_CONFLUENCE"}, + }) + rows = fetch_recent_sell_strategy_results(db_path, "005930") + assert [r["generated_at"] for r in rows] == ["2026-06-21T12:00:00", "2026-06-20T12:00:00", "2026-06-19T12:00:00"] + + +def test_insert_satellite_recommendation(tmp_path): + db_path = tmp_path / "test.db" + insert_satellite_recommendation(db_path, "2026-06-21T12:00:00+09:00", { + "ticker": "042700", + "score": {"satellite_action": "BUY_CANDIDATE", "attractiveness_score": 0.6, "market_regime": "PERFORMANCE_MARKET"}, + }) + import sqlite3 + conn = sqlite3.connect(db_path) + row = conn.execute("SELECT ticker, satellite_action, attractiveness_score FROM satellite_recommendations").fetchone() + conn.close() + assert row == ("042700", "BUY_CANDIDATE", 0.6) + + +def test_resolve_store_path_supports_sqlite(tmp_path): + db_path = resolve_store_path(QualitativeSellStoreSpec(location=tmp_path / "qualitative.db"), ROOT) + assert str(db_path).endswith("qualitative.db") diff --git a/tests/unit/test_qualitative_sell_strategy_v1.py b/tests/unit/test_qualitative_sell_strategy_v1.py new file mode 100644 index 00000000..232326d9 --- /dev/null +++ b/tests/unit/test_qualitative_sell_strategy_v1.py @@ -0,0 +1,148 @@ +from __future__ import annotations + +import sys +from datetime import date +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +from src.quant_engine.qualitative_sell_strategy_v1 import ( + classify_market_regime, + compute_microstructure_pressure_from_orderbook, + compute_qualitative_sell_strategy, + compute_satellite_candidate_score, + compute_short_interest_composite, +) + + +def test_classify_market_regime(): + assert classify_market_regime("RISING") == "PERFORMANCE_MARKET" + assert classify_market_regime("FLAT") == "TECHNICAL_MARKET" + assert classify_market_regime("FALLING") == "TECHNICAL_MARKET" + assert classify_market_regime(None) == "NEUTRAL" + assert classify_market_regime("garbage") == "NEUTRAL" + + +def test_short_interest_composite_data_missing_without_estimating(): + result = compute_short_interest_composite({"short_balance_ratio": 0.6}) + assert result["status"] == "DATA_MISSING" + assert "short_turnover_share" in result["missing_inputs"] + assert result["short_interest_pressure"] is None + + +def test_short_interest_composite_low_balance_regime_reweights(): + low_balance = compute_short_interest_composite({ + "short_balance_ratio": 0.6, "short_balance_ratio_chg_20d": 0.1, + "short_turnover_share": 14.0, "relative_return_20d": -8.0, + "volume_ratio_5d": 1.8, "earnings_outlook": "DETERIORATING", + }) + assert low_balance["low_balance_regime"] is True + assert low_balance["weights_used"]["balance"] < low_balance["weights_used"]["turnover"] + assert low_balance["label"] == "ELEVATED_SHORT_PRESSURE" + + +def test_confluence_requires_minimum_three_agreeing_factors(): + # 2개 팩터만 매도방향(macro, short_interest) 합의 — 3개 미달이므로 매도 액션 금지 + ctx = { + "macro_pressure": 0.5, "short_interest_pressure": 0.6, + "fundamental_trajectory": -0.5, "microstructure_pressure": -0.4, + "liquidity_rotation_risk": 0.1, + } + out = compute_qualitative_sell_strategy(ctx) + assert out["action"] not in {"EXIT_REVIEW_FULL", "TRIM_REVIEW_PARTIAL"} + + +def test_confluence_triggers_trim_when_three_factors_agree(): + ctx = { + "macro_pressure": 0.5, "short_interest_pressure": 0.5, + "fundamental_trajectory": 0.4, "microstructure_pressure": 0.1, + "liquidity_rotation_risk": 0.0, + } + out = compute_qualitative_sell_strategy(ctx) + assert out["action"] == "TRIM_REVIEW_PARTIAL" + assert set(out["sell_agreeing_factors"]) == {"macro_pressure", "short_interest_pressure", "fundamental_trajectory"} + + +def test_insufficient_data_does_not_fabricate_action(): + out = compute_qualitative_sell_strategy({"macro_pressure": 0.9}) + assert out["action"] == "INSUFFICIENT_DATA_NO_ACTION" + assert out["mechanical_sell_prohibited"] is True + + +def test_review_window_pre_earnings_when_outlook_deteriorating(): + ctx = { + "macro_pressure": 0.5, "fundamental_trajectory": 0.5, "short_interest_pressure": 0.5, + "earnings_outlook": "DETERIORATING", + "next_earnings_date": date(2026, 7, 24), + "today": date(2026, 6, 21), + } + out = compute_qualitative_sell_strategy(ctx) + assert out["review_window"]["window_basis"] == "PRE_EARNINGS_EXIT_BEFORE_SURPRISE_RISK" + assert out["review_window"]["review_window_end"] < "2026-07-24" + + +def test_review_window_defers_past_earnings_when_outlook_improving(): + ctx = { + "macro_pressure": -0.5, "fundamental_trajectory": -0.5, "short_interest_pressure": -0.5, + "earnings_outlook": "IMPROVING", + "next_earnings_date": date(2026, 7, 24), + "today": date(2026, 6, 21), + } + out = compute_qualitative_sell_strategy(ctx) + assert out["action"] == "HOLD_ADD_CONVICTION" + assert out["review_window"]["window_basis"] == "REASSESS_AFTER_EARNINGS_CONFIRM" + + +def test_regime_weighting_shifts_composite_score_without_changing_confluence_count(): + base_ctx = { + "macro_pressure": 0.4, "fundamental_trajectory": 0.6, "short_interest_pressure": 0.35, + "microstructure_pressure": 0.1, "liquidity_rotation_risk": 0.0, + } + performance = compute_qualitative_sell_strategy({**base_ctx, "rate_trend": "RISING"}) + technical = compute_qualitative_sell_strategy({**base_ctx, "rate_trend": "FALLING"}) + assert performance["market_regime"] == "PERFORMANCE_MARKET" + assert technical["market_regime"] == "TECHNICAL_MARKET" + assert performance["sell_agreeing_factors"] == technical["sell_agreeing_factors"] + assert performance["composite_score"] != technical["composite_score"] + + +def test_satellite_candidate_score_insufficient_data(): + out = compute_satellite_candidate_score({"fundamental_trajectory": 0.2}) + assert out["satellite_action"] == "INSUFFICIENT_DATA_NO_ACTION" + + +def test_satellite_candidate_score_buy_candidate_on_strong_export_and_fundamentals(): + out = compute_satellite_candidate_score({ + "sector_export_trend": 12.0, "fundamental_trajectory": -0.4, + "relative_return_20d": 3.0, "rate_trend": "RISING", + }) + assert out["satellite_action"] == "BUY_CANDIDATE" + assert out["market_regime"] == "PERFORMANCE_MARKET" + + +def test_microstructure_pressure_from_orderbook_ask_heavy_is_positive(): + out = compute_microstructure_pressure_from_orderbook({"total_askp_rsqn": "300000", "total_bidp_rsqn": "100000"}) + assert out["status"] == "OK" + assert out["microstructure_pressure"] > 0 + + +def test_microstructure_pressure_from_orderbook_bid_heavy_is_negative(): + out = compute_microstructure_pressure_from_orderbook({"total_askp_rsqn": "100000", "total_bidp_rsqn": "300000"}) + assert out["microstructure_pressure"] < 0 + + +def test_microstructure_pressure_from_orderbook_missing_fields(): + out = compute_microstructure_pressure_from_orderbook({}) + assert out["status"] == "DATA_MISSING" + assert out["microstructure_pressure"] is None + + +def test_map_universe_sector_to_hs_sector_substring_match(): + from tools.build_satellite_candidate_recommendations_v1 import map_universe_sector_to_hs_sector + + assert map_universe_sector_to_hs_sector("반도체/PCB") == "반도체" + assert map_universe_sector_to_hs_sector("자동차/부품") == "자동차" + assert map_universe_sector_to_hs_sector("AI전력/기기") is None + assert map_universe_sector_to_hs_sector(None) is None diff --git a/tests/unit/test_validate_qualitative_sell_strategy_pipeline_v1.py b/tests/unit/test_validate_qualitative_sell_strategy_pipeline_v1.py new file mode 100644 index 00000000..91e92671 --- /dev/null +++ b/tests/unit/test_validate_qualitative_sell_strategy_pipeline_v1.py @@ -0,0 +1,24 @@ +from __future__ import annotations + +import json +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[2] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +import tools.validate_qualitative_sell_strategy_pipeline_v1 as validator + + +def test_validate_qualitative_sell_strategy_pipeline_passes(tmp_path, monkeypatch): + out = tmp_path / "qualitative_sell_strategy_pipeline_v1.json" + monkeypatch.setattr(sys, "argv", ["validate_qualitative_sell_strategy_pipeline_v1.py"]) + monkeypatch.setattr(validator, "ROOT", ROOT) + + rc = validator.main() + payload = json.loads((ROOT / "Temp" / "qualitative_sell_strategy_pipeline_v1.json").read_text(encoding="utf-8")) + + assert rc == 0 + assert payload["gate"] == "PASS" + assert payload["checks"]["store_contract"] is True diff --git a/tools/build_macro_context_from_workbook_v1.py b/tools/build_macro_context_from_workbook_v1.py new file mode 100644 index 00000000..d992f21f --- /dev/null +++ b/tools/build_macro_context_from_workbook_v1.py @@ -0,0 +1,204 @@ +"""GatherTradingData.xlsx에서 실제 매크로/이벤트/포지션 컨텍스트를 추출. + +build_qualitative_sell_inputs_v1.py의 --context-json을 수동 작성하지 않고, 이미 +GAS 하네스가 산출/수집해 둔 시트 값을 그대로 읽어 자동 조립한다(중복 수집 금지 +원칙 — qualitative_sell_strategy_v1.yaml:data_sources 참조). + +실측 확인된 시트/컬럼(2026-06-21): + - macro 시트: Symbol='MRS_COMPUTED'.Close = market_risk_score(0~10, 하네스 산출). + Symbol='^TNX'(US10Y_Yield).Ret20D = 20일 금리추세 proxy(국내 기준금리 시트 없음 — + 한국은행 금통위 일정은 event_calendar Type='BOK'로 별도 포착). + - event_risk 시트: Date/DaysLeft/Event/Type/Impact(HIGH/MEDIUM/LOW)/Alert/AsOfDate. + - event_calendar 시트: Date/Event/Type(EARNINGS/FOMC/BOK/...)/Impact/DaysLeft 등. + Type='EARNINGS'에 종목명이 Event 텍스트에 포함된 행만 종목별 실적발표일로 매칭. + - account_snapshot 시트: ticker/name/holding_quantity/parse_status='CAPTURE_READ_OK'. +""" +from __future__ import annotations + +import argparse +import datetime as dt +import json +import sys +from pathlib import Path +from typing import Any + +from openpyxl import load_workbook + +ROOT = Path(__file__).resolve().parents[1] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +RATE_RISING_THRESHOLD_PCT = 2.0 +RATE_FALLING_THRESHOLD_PCT = -2.0 + + +def _read_sheet_rows(xlsx_path: Path, sheet: str) -> tuple[tuple, list[dict[str, Any]]]: + """헤더 행을 탐색한다. 일부 시트(macro/event_risk)는 1행에 'updated: ...' 배너 + 셀 1개만 있고 실제 헤더는 2행 — 비어있거나 단일 셀뿐인 선행 행은 건너뛴다.""" + wb = load_workbook(xlsx_path, read_only=True, data_only=True) + ws = wb[sheet] + rows_iter = ws.iter_rows(min_row=1, values_only=True) + header: tuple = () + for row in rows_iter: + non_empty = [c for c in row if c is not None] + if len(non_empty) >= 2: + header = row + break + rows = [dict(zip(header, row)) for row in rows_iter if any(c is not None for c in row)] + return header, rows + + +def read_macro_pressure_and_regime(xlsx_path: Path) -> dict[str, Any]: + """MRS_COMPUTED.Close(0~10) -> macro_pressure(-1~+1, 위험도 높을수록 매도압력). + + ^TNX Ret20D(%) -> rate_trend(RISING/FLAT/FALLING) — 국내 기준금리 시트가 없어 + 미국채 10년물 20일 변화율을 proxy로 사용한다(국내 금리는 미 국채와 강한 동행성). + """ + _, rows = _read_sheet_rows(xlsx_path, "macro") + by_symbol = {row.get("Symbol"): row for row in rows} + + mrs_row = by_symbol.get("MRS_COMPUTED") + macro_pressure = None + market_risk_score = None + if mrs_row is not None and isinstance(mrs_row.get("Close"), (int, float)): + market_risk_score = float(mrs_row["Close"]) + macro_pressure = max(-1.0, min(1.0, (market_risk_score / 10.0) * 2.0 - 1.0)) + + tnx_row = by_symbol.get("^TNX") + rate_trend = None + rate_ret20d_pct = None + if tnx_row is not None and tnx_row.get("Ret20D") not in (None, ""): + try: + rate_ret20d_pct = float(tnx_row["Ret20D"]) + except (TypeError, ValueError): + rate_ret20d_pct = None + if rate_ret20d_pct is not None: + if rate_ret20d_pct >= RATE_RISING_THRESHOLD_PCT: + rate_trend = "RISING" + elif rate_ret20d_pct <= RATE_FALLING_THRESHOLD_PCT: + rate_trend = "FALLING" + else: + rate_trend = "FLAT" + + regime_row = by_symbol.get("REGIME_PRELIM") + regime_prelim = regime_row.get("Close") if regime_row else None + + return { + "macro_pressure": macro_pressure, + "market_risk_score": market_risk_score, + "rate_trend": rate_trend, + "rate_ret20d_pct": rate_ret20d_pct, + "regime_prelim": regime_prelim, + "macro_pressure_source": "GatherTradingData.xlsx:macro", + } + + +def read_next_macro_event(xlsx_path: Path, today: dt.date | None = None) -> dict[str, Any]: + """event_risk 시트에서 오늘 이후 가장 가까운 HIGH 임팩트 이벤트일.""" + today = today or dt.date.today() + _, rows = _read_sheet_rows(xlsx_path, "event_risk") + candidates = [] + for row in rows: + event_date = row.get("Date") + if not isinstance(event_date, dt.datetime): + continue + event_date = event_date.date() + if event_date < today or row.get("Impact") not in {"HIGH"}: + continue + candidates.append((event_date, row.get("Event"), row.get("Impact"))) + if not candidates: + return {"next_macro_event_date": None, "macro_event_impact": None} + candidates.sort(key=lambda item: item[0]) + event_date, event_name, impact = candidates[0] + return { + "next_macro_event_date": event_date.isoformat(), + "macro_event_impact": impact, + "macro_event_name": event_name, + "macro_event_source": "GatherTradingData.xlsx:event_risk", + } + + +def read_next_earnings_date(xlsx_path: Path, company_name: str, today: dt.date | None = None) -> dict[str, Any]: + """event_calendar에서 Type='EARNINGS'이며 Event 텍스트에 종목명이 포함된 가장 빠른 미래 일정.""" + today = today or dt.date.today() + _, rows = _read_sheet_rows(xlsx_path, "event_calendar") + candidates = [] + name = (company_name or "").strip() + if not name: + return {"next_earnings_date": None, "earnings_event_impact": None} + for row in rows: + if row.get("Type") != "EARNINGS": + continue + event_text = str(row.get("Event") or "") + if name not in event_text: + continue + event_date = row.get("Date") + if isinstance(event_date, dt.datetime): + event_date = event_date.date() + elif isinstance(event_date, str): + try: + event_date = dt.date.fromisoformat(event_date) + except ValueError: + continue + else: + continue + if event_date < today: + continue + candidates.append((event_date, row.get("Impact"))) + if not candidates: + return {"next_earnings_date": None, "earnings_event_impact": None} + candidates.sort(key=lambda item: item[0]) + event_date, impact = candidates[0] + return { + "next_earnings_date": event_date.isoformat(), + "earnings_event_impact": impact, + "earnings_source": "GatherTradingData.xlsx:event_calendar", + } + + +def read_positions(xlsx_path: Path) -> list[dict[str, Any]]: + """account_snapshot에서 실제 보유 종목 목록(CAPTURE_READ_OK, 보유수량>0).""" + _, rows = _read_sheet_rows(xlsx_path, "account_snapshot") + positions: dict[str, dict[str, Any]] = {} + for row in rows: + if row.get("parse_status") != "CAPTURE_READ_OK": + continue + ticker_raw = row.get("ticker") + qty = row.get("holding_quantity") or 0 + if ticker_raw is None or not isinstance(qty, (int, float)) or qty <= 0: + continue + ticker = str(ticker_raw) + ticker = ticker.zfill(6) if ticker.isdigit() else ticker + entry = positions.setdefault(ticker, {"ticker": ticker, "name": row.get("name"), "holding_quantity": 0.0}) + entry["holding_quantity"] += float(qty) # 소수주 분리 행 합산 + return list(positions.values()) + + +def build_context_for_ticker(xlsx_path: Path, ticker: str, company_name: str) -> dict[str, Any]: + today = dt.date.today() + ctx: dict[str, Any] = {} + ctx.update(read_macro_pressure_and_regime(xlsx_path)) + ctx.update(read_next_macro_event(xlsx_path, today)) + ctx.update(read_next_earnings_date(xlsx_path, company_name, today)) + return ctx + + +def main() -> int: + ap = argparse.ArgumentParser(description=__doc__) + ap.add_argument("--xlsx", type=Path, default=ROOT / "GatherTradingData.xlsx") + ap.add_argument("--ticker", default=None) + ap.add_argument("--name", default=None, help="실적발표 일정 매칭용 종목명(한글)") + ap.add_argument("--list-positions", action="store_true") + args = ap.parse_args() + + if args.list_positions: + print(json.dumps(read_positions(args.xlsx), ensure_ascii=False, indent=2)) + return 0 + + result = build_context_for_ticker(args.xlsx, args.ticker or "", args.name or "") + print(json.dumps(result, ensure_ascii=False, indent=2, default=str)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/build_qualitative_sell_inputs_v1.py b/tools/build_qualitative_sell_inputs_v1.py new file mode 100644 index 00000000..b066a20f --- /dev/null +++ b/tools/build_qualitative_sell_inputs_v1.py @@ -0,0 +1,342 @@ +"""qualitative_sell_strategy_v1 입력 ctx 조립 오케스트레이터. + +데이터 출처 (2026-06-21 세션 실측 기준, KIS Open API 연동 이후): + - relative_return_20d, volume_ratio_5d ← tools/fetch_naver_market_data_v1.py (무인증, 동작 확인) + - sector_export_trend ← tools/fetch_trade_statistics_motie_v1.py (--csv 경로 권장) + - short_turnover_share ← [신규] KIS Open API daily-short-sale(FHPST04830000) + output2.ssts_vol_rlim — 실측 동작 확인(실전계좌 도메인, + 모의계좌 도메인은 500 에러). --kis-account real 필요. + - short_balance_ratio(잔고율) ← 여전히 미확보. KIS API도 제공하지 않음(KRX 공매도종합 + 포털 대량보유 공시 전용 데이터) — --short-csv 수동 + 다운로드로만 가능. + - microstructure_pressure(호가10단계) ← [신규] KIS Open API inquire-asking-price-exp-ccn + (FHKST01010200) output1.total_askp_rsqn/total_bidp_rsqn + — 실측 동작 확인(실전+모의 도메인 모두). --kis-account + {real,mock}로 활성화. + - macro_pressure, rate_trend, next_earnings_date, next_macro_event_date, macro_event_impact + ← 기존 GAS 하네스(macro_event_synchronizer_v2, + gas_event_calendar.gs)가 이미 산출/수집 중 — + 이 스크립트가 중복 수집하지 않고 --context-json/ + --workbook으로 그 결과를 주입받는다. + - investing.com ← 직접 스크래핑 403(Cloudflare) 차단 확인. 사용 안 함. + +[CRITICAL] KIS API는 조회(read-only)로만 사용한다 — 매수/매도 주문은 어떤 경우에도 이 코드를 +통해 실행하지 않는다(governance/rules/06_no_direct_api_trading.yaml, CI 강제 게이트 +tools/validate_no_direct_api_trading_v1.py). + +사용 예: + python tools/build_qualitative_sell_inputs_v1.py \ + --ticker 005930 --benchmark-code 069500 --sector 반도체 \ + --kis-account real --short-csv Temp/krx_short_balance_manual.csv \ + --context-json Temp/macro_context.json --apply +""" +from __future__ import annotations + +import argparse +import datetime as dt +import json +import sys +from pathlib import Path +from typing import Any + +ROOT = Path(__file__).resolve().parents[1] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +from tools.fetch_naver_market_data_v1 import ( + _session, + compute_relative_return_20d, + compute_volume_ratio_5d, + fetch_price_history, +) +from tools.fetch_trade_statistics_motie_v1 import ( + compute_sector_export_trend, + load_trade_statistics_csv, +) +from src.quant_engine.qualitative_sell_strategy_v1 import ( + compute_microstructure_pressure_from_orderbook, + compute_qualitative_sell_strategy, + compute_short_interest_composite, +) +from src.quant_engine.qualitative_sell_strategy_store_v1 import ( + QualitativeSellStoreSpec, + insert_sell_strategy_result, + resolve_store_path, +) + +DEFAULT_OUTPUT_DIR = ROOT / "outputs" / "qualitative_sell_strategy" +DEFAULT_SQLITE_DB = DEFAULT_OUTPUT_DIR / "qualitative_sell_strategy.db" + + +def _kst_now_iso() -> str: + return dt.datetime.now(dt.timezone(dt.timedelta(hours=9))).isoformat() + + +def _parse_date(value: str | None) -> dt.date | None: + if not value: + return None + try: + return dt.date.fromisoformat(value) + except ValueError: + return None + + +def load_short_interest_csv(path: Path, code: str) -> dict[str, Any]: + """KRX 공매도종합포털 수동 다운로드 CSV. 컬럼: 종목코드, 잔고율, 잔고율변화20일, 거래비중.""" + import csv + + with path.open(encoding="utf-8-sig", newline="") as f: + for row in csv.DictReader(f): + row_code = str(row.get("종목코드") or row.get("code") or "").strip().zfill(6) + if row_code == code: + return { + "short_balance_ratio": float(row.get("잔고율") or row.get("short_balance_ratio") or 0), + "short_balance_ratio_chg_20d": float(row.get("잔고율변화20일") or row.get("short_balance_ratio_chg_20d") or 0), + "short_turnover_share": float(row.get("거래비중") or row.get("short_turnover_share") or 0), + } + return {} + + +def fetch_kis_supplement(code: str, kis_account: str | None) -> dict[str, Any]: + """KIS Open API에서 short_turnover_share(공매도거래비중)와 microstructure_pressure + (호가10단계)를 조회한다. 조회(read-only)만 수행 — 주문 관련 호출 없음.""" + if not kis_account: + return {} + from src.quant_engine.kis_api_client_v1 import KisCredentials, get_asking_price_10_level, get_daily_short_sale + + result: dict[str, Any] = {} + try: + creds = KisCredentials.load(kis_account) + except RuntimeError as exc: + return {"kis_error": str(exc)} + + try: + ob = get_asking_price_10_level(creds, code) + micro = compute_microstructure_pressure_from_orderbook(ob.get("output1", {})) + if micro.get("status") == "OK": + result["microstructure_pressure"] = micro["microstructure_pressure"] + except Exception as exc: # noqa: BLE001 — KIS 호출 실패가 전체 파이프라인을 막지 않음 + result["kis_orderbook_error"] = str(exc) + + try: + today = dt.date.today() + start = (today - dt.timedelta(days=10)).strftime("%Y%m%d") + end = today.strftime("%Y%m%d") + ss = get_daily_short_sale(creds, code, start, end) + rows = ss.get("output2") or [] + if rows: + latest = rows[0] + ssts_vol_rlim = latest.get("ssts_vol_rlim") + if ssts_vol_rlim is not None: + result["short_turnover_share"] = float(ssts_vol_rlim) + except Exception as exc: # noqa: BLE001 + result["kis_short_sale_error"] = str(exc) + + return result + + +def build_ctx_for_ticker( + code: str, + benchmark_code: str, + sector: str | None, + earnings_outlook: str, + trade_csv: Path | None, + short_csv: Path | None, + external_context: dict[str, Any], + kis_account: str | None = None, +) -> dict[str, Any]: + session = _session() + price = fetch_price_history(session, code) + benchmark = fetch_price_history(session, benchmark_code) + + relative_return_20d = compute_relative_return_20d(price.get("rows", []), benchmark.get("rows", [])) + volume_ratio_5d = compute_volume_ratio_5d(price.get("rows", [])) + kis_supplement = fetch_kis_supplement(code, kis_account) + + short_inputs: dict[str, Any] = {} + if short_csv and short_csv.exists(): + short_inputs = load_short_interest_csv(short_csv, code) + if "short_turnover_share" in kis_supplement: + short_inputs["short_turnover_share"] = kis_supplement["short_turnover_share"] + short_inputs.setdefault("relative_return_20d", relative_return_20d) + short_inputs.setdefault("volume_ratio_5d", volume_ratio_5d) + short_inputs.setdefault("earnings_outlook", earnings_outlook) + short_interest = compute_short_interest_composite(short_inputs) + + sector_export_trend = None + if trade_csv and trade_csv.exists() and sector: + rows = load_trade_statistics_csv(trade_csv) + export_result = compute_sector_export_trend(rows, sector, compare="yoy") + if export_result.get("status") == "OK": + sector_export_trend = export_result["sector_export_trend"] + + fundamental_trajectory = external_context.get("fundamental_trajectory") + if fundamental_trajectory is None and sector_export_trend is not None: + fundamental_trajectory = max(-1.0, min(1.0, -sector_export_trend / 15.0)) + + ctx: dict[str, Any] = { + "today": dt.date.today(), + "macro_pressure": external_context.get("macro_pressure"), + "fundamental_trajectory": fundamental_trajectory, + "short_interest_pressure": short_interest.get("short_interest_pressure"), + "microstructure_pressure": kis_supplement.get("microstructure_pressure", external_context.get("microstructure_pressure")), + "liquidity_rotation_risk": external_context.get("liquidity_rotation_risk"), + "earnings_outlook": earnings_outlook, + "next_earnings_date": _parse_date(external_context.get("next_earnings_date")), + "next_macro_event_date": _parse_date(external_context.get("next_macro_event_date")), + "macro_event_impact": external_context.get("macro_event_impact"), + "rate_trend": external_context.get("rate_trend"), + } + return { + "code": code, + "ctx": ctx, + "short_interest_composite": short_interest, + "sector_export_trend": sector_export_trend, + "relative_return_20d": relative_return_20d, + "volume_ratio_5d": volume_ratio_5d, + "kis_supplement": kis_supplement, + "generated_at": _kst_now_iso(), + } + + +def process_one( + ticker: str, + name: str, + benchmark_code: str, + sector: str | None, + earnings_outlook: str, + trade_csv: Path | None, + short_csv: Path | None, + workbook: Path | None, + context_json: Path | None, + kis_account: str | None = None, +) -> dict[str, Any]: + external_context: dict[str, Any] = {} + if context_json and context_json.exists(): + external_context = json.loads(context_json.read_text(encoding="utf-8")) + elif workbook and workbook.exists(): + from tools.build_macro_context_from_workbook_v1 import build_context_for_ticker + external_context = build_context_for_ticker(workbook, ticker, name) + + assembled = build_ctx_for_ticker( + code=ticker, + benchmark_code=benchmark_code, + sector=sector, + earnings_outlook=earnings_outlook, + trade_csv=trade_csv, + short_csv=short_csv, + external_context=external_context, + kis_account=kis_account, + ) + decision = compute_qualitative_sell_strategy(assembled["ctx"]) + result = {**assembled, "decision": decision} + result["ctx"] = {k: (v.isoformat() if isinstance(v, dt.date) else v) for k, v in result["ctx"].items()} + return result + + +def main() -> int: + ap = argparse.ArgumentParser(description=__doc__) + ap.add_argument("--ticker", default=None, help="6자리 종목코드(단일 실행 시 필수)") + ap.add_argument("--name", default=None, help="실적발표 매칭용 종목명(한글)") + ap.add_argument("--benchmark-code", default="069500") + ap.add_argument("--sector", default=None, help="fetch_trade_statistics_motie_v1.SECTOR_HS_MAP 키") + ap.add_argument("--earnings-outlook", default="STABLE", choices=["IMPROVING", "STABLE", "DETERIORATING"]) + ap.add_argument("--trade-csv", type=Path, default=None) + ap.add_argument("--short-csv", type=Path, default=None, help="KRX 공매도종합포털 수동 다운로드 CSV") + ap.add_argument("--context-json", type=Path, default=None, help="macro_pressure/rate_trend/이벤트일 등 외부 산출값 JSON(수동)") + ap.add_argument("--workbook", type=Path, default=None, help="GatherTradingData.xlsx — macro/event_risk/event_calendar 시트에서 컨텍스트 자동 추출(권장)") + ap.add_argument("--batch", action="store_true", help="--workbook의 account_snapshot 실보유 종목 전체 순회(국내 6자리 코드만)") + ap.add_argument("--kis-account", choices=["real", "mock"], default=None, + help="KIS Open API로 호가10단계/공매도거래비중 보강 조회(read-only). " + "공매도 일별추이는 real 도메인만 동작 확인됨(mock은 500 에러).") + ap.add_argument("--apply", action="store_true", help="outputs/qualitative_sell_strategy/.json 저장") + ap.add_argument("--sqlite-db", type=Path, default=DEFAULT_SQLITE_DB, + help="JSON 저장과 병행해 시계열 SQLite에도 기록(GAS/xlsx와 무관한 추가 저장소)") + ap.add_argument("--store-backend", default="sqlite", help="Storage backend contract placeholder (sqlite today, postgresql planned)") + ap.add_argument("--store-location", default=None, help="Backend location/DSN. sqlite path or future postgres DSN.") + ap.add_argument("--no-sqlite", action="store_true", help="SQLite 기록 비활성화") + args = ap.parse_args() + store_db = resolve_store_path( + QualitativeSellStoreSpec( + backend=args.store_backend, + location=args.store_location or args.sqlite_db, + ), + ROOT, + ) + + if args.batch: + if not args.workbook or not args.workbook.exists(): + raise SystemExit("--batch는 --workbook 경로가 필요합니다") + from tools.build_macro_context_from_workbook_v1 import read_positions + positions = [p for p in read_positions(args.workbook) if str(p["ticker"]).isdigit() and len(str(p["ticker"])) == 6] + if args.apply: + DEFAULT_OUTPUT_DIR.mkdir(parents=True, exist_ok=True) + results = [] + for pos in positions: + try: + result = process_one( + ticker=pos["ticker"], name=str(pos.get("name") or ""), + benchmark_code=args.benchmark_code, sector=args.sector, + earnings_outlook=args.earnings_outlook, trade_csv=args.trade_csv, + short_csv=args.short_csv, workbook=args.workbook, context_json=None, + kis_account=args.kis_account, + ) + except Exception as exc: # noqa: BLE001 — 종목 1건 실패가 배치 전체를 막지 않음 + result = {"code": pos["ticker"], "status": "FETCH_ERROR", "note": str(exc)} + results.append(result) + if args.apply: + out_path = DEFAULT_OUTPUT_DIR / f"{pos['ticker']}.json" + out_path.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8") + if not args.no_sqlite and result.get("status") != "FETCH_ERROR": + insert_sell_strategy_result(store_db, result) + error_count = sum(1 for r in results if r.get("status") == "FETCH_ERROR") + action_counts: dict[str, int] = {} + for r in results: + action = (r.get("decision") or {}).get("action", "N/A") + action_counts[action] = action_counts.get(action, 0) + 1 + summary = { + "generated_at": _kst_now_iso(), + "ticker_count": len(results), + "error_count": error_count, + "action_counts": action_counts, + } + print(f"SUMMARY: {json.dumps(summary, ensure_ascii=False)}") + if args.apply: + (DEFAULT_OUTPUT_DIR / "_batch_summary.json").write_text( + json.dumps(summary, ensure_ascii=False, indent=2), encoding="utf-8" + ) + print(f"written {len(results)} files to {DEFAULT_OUTPUT_DIR}") + else: + print(json.dumps(results, ensure_ascii=False, indent=2)) + # 절반 이상 실패면 CI에서 빨간불로 보이도록 — 호출결과를 로그만으로 확인 가능하게 함 + if results and error_count / len(results) >= 0.5: + print(f"BATCH_GATE: FAIL — error_count={error_count}/{len(results)}") + return 1 + print("BATCH_GATE: PASS") + return 0 + + if not args.ticker: + raise SystemExit("--ticker 또는 --batch 중 하나는 필수입니다") + + result = process_one( + ticker=args.ticker, name=args.name or "", + benchmark_code=args.benchmark_code, sector=args.sector, + earnings_outlook=args.earnings_outlook, trade_csv=args.trade_csv, + short_csv=args.short_csv, workbook=args.workbook, context_json=args.context_json, + kis_account=args.kis_account, + ) + + if args.apply: + DEFAULT_OUTPUT_DIR.mkdir(parents=True, exist_ok=True) + out_path = DEFAULT_OUTPUT_DIR / f"{args.ticker}.json" + out_path.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8") + if not args.no_sqlite: + insert_sell_strategy_result(store_db, result) + print(f"written: {out_path}") + else: + print(json.dumps(result, ensure_ascii=False, indent=2)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/build_satellite_candidate_recommendations_v1.py b/tools/build_satellite_candidate_recommendations_v1.py new file mode 100644 index 00000000..93408135 --- /dev/null +++ b/tools/build_satellite_candidate_recommendations_v1.py @@ -0,0 +1,139 @@ +"""universe 시트(미보유 위성 유니버스) 전체를 SATELLITE_CANDIDATE_SCORE_V1로 평가. + +WBS-6 후속 — qualitative_sell_strategy_v1.compute_satellite_candidate_score를 실제 +GatherTradingData.xlsx universe 시트(Ticker/Name/Sector/AddedDate, 실측 확인됨)에 연동. +보유 종목(account_snapshot)은 제외하고 미보유 후보만 평가한다. + +universe.Sector 한글 라벨은 fetch_trade_statistics_motie_v1.SECTOR_HS_MAP 키와 1:1로 +일치하지 않으므로 부분 문자열 매칭으로 연결한다. 매칭 실패 종목은 sector_export_trend를 +추정하지 않고 None으로 두어 컨플루언스 부족(INSUFFICIENT_DATA_NO_ACTION)으로 자연 처리된다 +(추정 금지 원칙 — qualitative_sell_strategy_v1.yaml과 동일). +""" +from __future__ import annotations + +import argparse +import datetime as dt +import json +import sys +from pathlib import Path +from typing import Any + +from openpyxl import load_workbook + +ROOT = Path(__file__).resolve().parents[1] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +from tools.build_macro_context_from_workbook_v1 import _read_sheet_rows, read_positions, read_macro_pressure_and_regime +from tools.fetch_naver_market_data_v1 import _session, compute_relative_return_20d, fetch_price_history +from tools.fetch_trade_statistics_motie_v1 import SECTOR_HS_MAP, compute_sector_export_trend, load_trade_statistics_csv +from src.quant_engine.qualitative_sell_strategy_v1 import compute_satellite_candidate_score +from src.quant_engine.qualitative_sell_strategy_store_v1 import ( + QualitativeSellStoreSpec, + insert_satellite_recommendation, + resolve_store_path, +) + +DEFAULT_OUTPUT = ROOT / "outputs" / "qualitative_sell_strategy" / "satellite_recommendations.json" +DEFAULT_SQLITE_DB = ROOT / "outputs" / "qualitative_sell_strategy" / "qualitative_sell_strategy.db" + + +def map_universe_sector_to_hs_sector(universe_sector: str) -> str | None: + text = str(universe_sector or "") + for hs_sector in SECTOR_HS_MAP: + if hs_sector in text: + return hs_sector + return None + + +def read_universe_candidates(xlsx_path: Path, exclude_tickers: set[str]) -> list[dict[str, Any]]: + _, rows = _read_sheet_rows(xlsx_path, "universe") + candidates = [] + for row in rows: + ticker = str(row.get("Ticker") or "").strip() + if not ticker or ticker in exclude_tickers: + continue + candidates.append({ + "ticker": ticker, + "name": row.get("Name"), + "universe_sector": row.get("Sector"), + "hs_sector": map_universe_sector_to_hs_sector(row.get("Sector")), + }) + return candidates + + +def main() -> int: + ap = argparse.ArgumentParser(description=__doc__) + ap.add_argument("--workbook", type=Path, default=ROOT / "GatherTradingData.xlsx") + ap.add_argument("--benchmark-code", default="069500") + ap.add_argument("--trade-csv", type=Path, default=None, help="관세청/산업통상부 수출입통계 CSV — 없으면 sector_export_trend는 전부 DATA_MISSING") + ap.add_argument("--apply", action="store_true", help=str(DEFAULT_OUTPUT) + " 저장") + ap.add_argument("--sqlite-db", type=Path, default=DEFAULT_SQLITE_DB, + help="JSON 저장과 병행해 시계열 SQLite에도 기록(GAS/xlsx와 무관한 추가 저장소)") + ap.add_argument("--store-backend", default="sqlite", help="Storage backend contract placeholder (sqlite today, postgresql planned)") + ap.add_argument("--store-location", default=None, help="Backend location/DSN. sqlite path or future postgres DSN.") + ap.add_argument("--no-sqlite", action="store_true", help="SQLite 기록 비활성화") + args = ap.parse_args() + store_db = resolve_store_path( + QualitativeSellStoreSpec( + backend=args.store_backend, + location=args.store_location or args.sqlite_db, + ), + ROOT, + ) + + held = {p["ticker"] for p in read_positions(args.workbook) if str(p["ticker"]).isdigit()} + candidates = read_universe_candidates(args.workbook, held) + + trade_rows = load_trade_statistics_csv(args.trade_csv) if args.trade_csv and args.trade_csv.exists() else [] + macro = read_macro_pressure_and_regime(args.workbook) + rate_trend = macro.get("rate_trend") + + session = _session() + benchmark = fetch_price_history(session, args.benchmark_code) + + results = [] + for cand in candidates: + sector_export_trend = None + if cand["hs_sector"] and trade_rows: + export_result = compute_sector_export_trend(trade_rows, cand["hs_sector"], compare="yoy") + if export_result.get("status") == "OK": + sector_export_trend = export_result["sector_export_trend"] + + relative_return_20d = None + if cand["ticker"].isdigit() and len(cand["ticker"]) == 6: + try: + price = fetch_price_history(session, cand["ticker"]) + relative_return_20d = compute_relative_return_20d(price.get("rows", []), benchmark.get("rows", [])) + except Exception: # noqa: BLE001 — 개별 종목 수집 실패가 전체 배치를 막지 않음 + relative_return_20d = None + + score = compute_satellite_candidate_score({ + "sector_export_trend": sector_export_trend, + "fundamental_trajectory": None, # universe 시트에 펀더멘털 추세 없음 — 추정 금지 + "relative_return_20d": relative_return_20d, + "rate_trend": rate_trend, + }) + results.append({**cand, "sector_export_trend": sector_export_trend, "relative_return_20d": relative_return_20d, "score": score}) + + output = { + "generated_at": dt.datetime.now(dt.timezone(dt.timedelta(hours=9))).isoformat(), + "rate_trend": rate_trend, + "candidate_count": len(results), + "results": results, + } + + if args.apply: + DEFAULT_OUTPUT.parent.mkdir(parents=True, exist_ok=True) + DEFAULT_OUTPUT.write_text(json.dumps(output, ensure_ascii=False, indent=2), encoding="utf-8") + if not args.no_sqlite: + for cand in results: + insert_satellite_recommendation(store_db, output["generated_at"], cand) + print(f"written: {DEFAULT_OUTPUT} ({len(results)} candidates)") + else: + print(json.dumps(output, ensure_ascii=False, indent=2)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/evaluate_qualitative_sell_strategy_accuracy_v1.py b/tools/evaluate_qualitative_sell_strategy_accuracy_v1.py new file mode 100644 index 00000000..f6129b94 --- /dev/null +++ b/tools/evaluate_qualitative_sell_strategy_accuracy_v1.py @@ -0,0 +1,143 @@ +"""qualitative_sell_strategy_v1 자체 평가 루프 — "한 번 만들고 끝"이 아니라 결정이 +실제로 가치를 보존했는지 사후 검증한다(30년 시니어 퀀트의 핵심 습관: 판단 → 결과 → +재보정). 기존 T+5/T+20 outcome ledger(proposal_evaluation_history)와 별개로, +qualitative_sell_strategy_store_v1.db에 쌓인 SQLite 시계열을 사용한다 — GAS/xlsx와 +무관하므로 이 모듈만의 독립 평가 루프를 구성해도 기존 시스템과 충돌하지 않는다. + +판정 기준(가치보존 관점, 기계적 승률 게임이 아님): + - EXIT_REVIEW_FULL / TRIM_REVIEW_PARTIAL(매도방향) → 이후 가격이 하락했으면 + "가치보존 성공"(매도가 손실을 막았다). 상승했으면 "기회비용 발생"(조급한 매도). + - HOLD_ADD_CONVICTION(지지방향) → 이후 가격이 상승했으면 성공. + - HOLD_NO_CONFLUENCE / INSUFFICIENT_DATA_NO_ACTION → 방향성 주장이 없으므로 평가 대상 제외. + +표본이 부족하면(DATA_GATED) 추정하지 않고 명시적으로 보류한다 — honest_proof_score와 +동일한 원칙(spec/algorithm_guidance_proof 계열). +""" +from __future__ import annotations + +import argparse +import datetime as dt +import json +import sqlite3 +import sys +from pathlib import Path +from typing import Any + +ROOT = Path(__file__).resolve().parents[1] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +from src.quant_engine.qualitative_sell_strategy_store_v1 import QualitativeSellStoreSpec, resolve_store_path + +MIN_HOLDING_DAYS = 5 # T+5 수준 — 너무 짧으면 노이즈, 너무 길면 표본 희소 +MIN_SAMPLE_FOR_HIT_RATE = 10 # 이보다 적으면 hit_rate를 신뢰 구간 없이 표기하지 않음(DATA_GATED) + + +def _scoreable_direction(action: str) -> int | None: + if action in {"EXIT_REVIEW_FULL", "TRIM_REVIEW_PARTIAL"}: + return -1 # 매도 방향 — 가격 하락이 "성공" + if action == "HOLD_ADD_CONVICTION": + return 1 # 지지 방향 — 가격 상승이 "성공" + return None # HOLD_NO_CONFLUENCE / INSUFFICIENT_DATA_NO_ACTION — 평가 제외 + + +def load_scoreable_decisions(db_path: Path, min_age_days: int = MIN_HOLDING_DAYS) -> list[dict[str, Any]]: + if not db_path.exists(): + return [] + cutoff = (dt.date.today() - dt.timedelta(days=min_age_days)).isoformat() + conn = sqlite3.connect(db_path) + conn.row_factory = sqlite3.Row + try: + rows = conn.execute( + "SELECT code, generated_at, action, conviction, market_regime, composite_score " + "FROM sell_strategy_results WHERE generated_at <= ? ORDER BY generated_at", + (cutoff,), + ).fetchall() + return [dict(row) for row in rows] + finally: + conn.close() + + +def evaluate_decision(decision: dict[str, Any], price_at_decision: float, price_after: float) -> dict[str, Any] | None: + direction = _scoreable_direction(decision["action"]) + if direction is None or not price_at_decision or price_at_decision <= 0: + return None + realized_return_pct = (price_after / price_at_decision - 1.0) * 100.0 + success = (direction * realized_return_pct) > 0 # 방향 일치 시 성공 + return { + **decision, + "price_at_decision": price_at_decision, + "price_after": price_after, + "realized_return_pct": round(realized_return_pct, 4), + "success": success, + } + + +def build_accuracy_report(db_path: Path, price_lookup: dict[str, dict[str, float]]) -> dict[str, Any]: + """price_lookup: {code: {generated_at_date_iso: close_price}} — 호출측이 실제 가격 + 히스토리(fetch_naver_market_data_v1 등)로 조립해 주입한다. 이 함수는 가격을 추정하지 + 않는다 — 주어진 값만 사용.""" + decisions = load_scoreable_decisions(db_path) + evaluated: list[dict[str, Any]] = [] + skipped_no_price = 0 + for decision in decisions: + prices = price_lookup.get(decision["code"], {}) + decision_date = decision["generated_at"][:10] + price_at = prices.get(decision_date) + future_date = (dt.date.fromisoformat(decision_date) + dt.timedelta(days=MIN_HOLDING_DAYS)).isoformat() + price_after = prices.get(future_date) + if price_at is None or price_after is None: + skipped_no_price += 1 + continue + result = evaluate_decision(decision, price_at, price_after) + if result is not None: + evaluated.append(result) + + scored = [e for e in evaluated if e is not None] + if len(scored) < MIN_SAMPLE_FOR_HIT_RATE: + return { + "status": "DATA_GATED", + "scored_sample_count": len(scored), + "min_sample_required": MIN_SAMPLE_FOR_HIT_RATE, + "note": "표본 부족 — hit_rate를 산출하지 않음(추정 금지). 결정 누적과 가격 매칭이 더 필요.", + "skipped_no_price": skipped_no_price, + } + + hit_rate_pct = round(100.0 * sum(1 for e in scored if e["success"]) / len(scored), 2) + return { + "status": "OK", + "scored_sample_count": len(scored), + "hit_rate_pct": hit_rate_pct, + "evaluations": scored, + "skipped_no_price": skipped_no_price, + } + + +def main() -> int: + ap = argparse.ArgumentParser(description=__doc__) + ap.add_argument("--sqlite-db", type=Path, + default=ROOT / "outputs" / "qualitative_sell_strategy" / "qualitative_sell_strategy.db") + ap.add_argument("--store-backend", default="sqlite", help="Storage backend contract placeholder (sqlite today, postgresql planned)") + ap.add_argument("--store-location", default=None, help="Backend location/DSN. sqlite path or future postgres DSN.") + ap.add_argument("--price-lookup-json", type=Path, default=None, + help='{"code": {"YYYY-MM-DD": close_price, ...}} 형식 — 미지정 시 가격 매칭 없이 표본 카운트만 보고') + args = ap.parse_args() + db_path = resolve_store_path( + QualitativeSellStoreSpec( + backend=args.store_backend, + location=args.store_location or args.sqlite_db, + ), + ROOT, + ) + + price_lookup: dict[str, dict[str, float]] = {} + if args.price_lookup_json and args.price_lookup_json.exists(): + price_lookup = json.loads(args.price_lookup_json.read_text(encoding="utf-8")) + + report = build_accuracy_report(db_path, price_lookup) + print(json.dumps(report, ensure_ascii=False, indent=2)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/fetch_naver_market_data_v1.py b/tools/fetch_naver_market_data_v1.py new file mode 100644 index 00000000..d8693074 --- /dev/null +++ b/tools/fetch_naver_market_data_v1.py @@ -0,0 +1,168 @@ +"""Naver Finance 시세/수급 수집기 — qualitative_sell_strategy_v1 입력용. + +확인된 무인증 엔드포인트만 사용한다(2026-06-21 세션 실측): + - https://finance.naver.com/item/sise_day.naver?code={code}&page=N (일별 시세/거래량) + - https://finance.naver.com/item/frgn.naver?code={code}&page=N (외국인/기관 수급) + - https://polling.finance.naver.com/api/realtime/domestic/stock/{code} (실시간 스냅샷, JSON) + +investing.com 직접 스크래핑은 403(Cloudflare 차단) 확인됨 — 시도하지 않는다. +KRX 공매도 잔고(data.krx.co.kr)는 OTP 세션 필요(LOGOUT 응답) — 시도하지 않는다. +이미 GAS(gdc_01_fetch_fundamentals.gs/gas_event_calendar.gs)에서 수집 중인 +외국인/기관 수급·실적발표 일정·경제지표 일정은 보유종목에 대해서는 account_snapshot/ +GatherTradingData.xlsx에서 재사용하고, 이 스크립트는 그 시트에 없는 위성 후보군 +티커를 평가할 때만 직접 호출한다(중복 수집 금지). +""" +from __future__ import annotations + +import argparse +import datetime as dt +import json +import sys +from pathlib import Path +from typing import Any + +import requests +from bs4 import BeautifulSoup + +ROOT = Path(__file__).resolve().parents[1] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0 Safari/537.36" +NAVER_REFERER = "https://finance.naver.com/" + + +def _session() -> requests.Session: + s = requests.Session() + s.headers.update({ + "User-Agent": USER_AGENT, + "Referer": NAVER_REFERER, + "Accept-Language": "ko-KR,ko;q=0.9,en;q=0.8", + }) + return s + + +def _num(text: str) -> float: + cleaned = text.replace(",", "").replace("+", "").strip() + try: + return float(cleaned) + except ValueError: + return 0.0 + + +def fetch_price_history(session: requests.Session, code: str, pages: int = 3) -> dict[str, Any]: + """일별 [date, close, change, open, high, low, volume] 최신순. 페이지당 10행.""" + rows: list[dict[str, Any]] = [] + for page in range(1, pages + 1): + url = f"https://finance.naver.com/item/sise_day.naver?code={code}&page={page}" + resp = session.get(url, timeout=10) + resp.encoding = "euc-kr" + soup = BeautifulSoup(resp.text, "html.parser") + table = soup.find("table", {"class": "type2"}) + if table is None: + break + for tr in table.find_all("tr"): + cells = [td.get_text(strip=True) for td in tr.find_all("td")] + if len(cells) != 7 or not cells[0]: + continue + rows.append({ + "date": cells[0].replace(".", "-"), + "close": _num(cells[1]), + "open": _num(cells[3]), + "high": _num(cells[4]), + "low": _num(cells[5]), + "volume": _num(cells[6]), + }) + if not rows: + return {"status": "DATA_MISSING", "rows": [], "source_url": NAVER_REFERER} + return { + "status": "OK", + "rows": rows, + "source_url": f"https://finance.naver.com/item/sise_day.naver?code={code}", + "source_as_of": dt.datetime.now(dt.timezone(dt.timedelta(hours=9))).isoformat(), + } + + +def fetch_foreign_institution_flow(session: requests.Session, code: str, pages: int = 2) -> dict[str, Any]: + """외국인/기관 5일·20일 수급. tds: [date, close, change, ret_pct, volume, inst, frgn, frgn_ratio].""" + rows: list[dict[str, Any]] = [] + for page in range(1, pages + 1): + url = f"https://finance.naver.com/item/frgn.naver?code={code}&page={page}" + resp = session.get(url, timeout=10) + resp.encoding = "euc-kr" + soup = BeautifulSoup(resp.text, "html.parser") + for table in soup.find_all("table", {"class": "type2"}): + for tr in table.find_all("tr"): + cells = [td.get_text(strip=True) for td in tr.find_all("td")] + if len(cells) < 8 or not cells[0] or "." not in cells[0]: + continue + rows.append({ + "date": cells[0].replace(".", "-"), + "close": _num(cells[1]), + "inst_net": _num(cells[5]), + "frgn_net": _num(cells[6]), + }) + if not rows: + return {"status": "DATA_MISSING", "rows": []} + return { + "status": "OK", + "rows": rows, + "source_url": f"https://finance.naver.com/item/frgn.naver?code={code}", + "source_as_of": dt.datetime.now(dt.timezone(dt.timedelta(hours=9))).isoformat(), + } + + +def compute_relative_return_20d(stock_rows: list[dict[str, Any]], benchmark_rows: list[dict[str, Any]]) -> float | None: + """종목수익률(최신 vs 20거래일전) - 벤치마크(섹터ETF/KOSPI)수익률, %p.""" + def _ret(rows: list[dict[str, Any]]) -> float | None: + closes = [r["close"] for r in rows if r.get("close")] + if len(closes) < 2: + return None + recent, past = closes[0], closes[min(len(closes) - 1, 19)] + if not past: + return None + return (recent / past - 1.0) * 100.0 + + stock_ret = _ret(stock_rows) + bench_ret = _ret(benchmark_rows) + if stock_ret is None or bench_ret is None: + return None + return round(stock_ret - bench_ret, 4) + + +def compute_volume_ratio_5d(rows: list[dict[str, Any]]) -> float | None: + """오늘 거래량 / 직전 5일 평균거래량.""" + volumes = [r["volume"] for r in rows if r.get("volume")] + if len(volumes) < 6: + return None + today_vol = volumes[0] + avg5 = sum(volumes[1:6]) / 5.0 + if avg5 <= 0: + return None + return round(today_vol / avg5, 4) + + +def main() -> int: + ap = argparse.ArgumentParser(description=__doc__) + ap.add_argument("--code", required=True, help="6자리 종목코드") + ap.add_argument("--benchmark-code", default="069500", help="비교 벤치마크 코드(기본 KODEX200 069500)") + args = ap.parse_args() + + session = _session() + price = fetch_price_history(session, args.code) + benchmark = fetch_price_history(session, args.benchmark_code) + flow = fetch_foreign_institution_flow(session, args.code) + + result = { + "code": args.code, + "price_history": price, + "foreign_institution_flow": flow, + "relative_return_20d": compute_relative_return_20d(price.get("rows", []), benchmark.get("rows", [])), + "volume_ratio_5d": compute_volume_ratio_5d(price.get("rows", [])), + } + print(json.dumps(result, ensure_ascii=False, indent=2)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/fetch_trade_statistics_motie_v1.py b/tools/fetch_trade_statistics_motie_v1.py new file mode 100644 index 00000000..810754d0 --- /dev/null +++ b/tools/fetch_trade_statistics_motie_v1.py @@ -0,0 +1,186 @@ +"""관세청/산업통상부 수출입동향 → 섹터별 수출 추세(sector_export_trend) 산출기. + +실측 결과(2026-06-21 세션): investing.com 직접 스크래핑은 403(Cloudflare)으로 차단되고, +관세청·산업통상부는 실시간 무인증 JSON API를 공개하지 않는다(통계청/관세청 수출입통계는 +data.go.kr 공공데이터포털의 서비스키 기반 OpenAPI 또는 매월 발표되는 보도자료 첨부 +XLSX/CSV로만 배포). 따라서 이 모듈은 두 경로를 모두 지원한다: + + 1) API 경로 — data.go.kr 관세청 수출입통계 API. CUSTOMS_API_KEY 환경변수(또는 + --api-key) 필요. 키가 없거나 호출 실패 시 추정하지 않고 DATA_MISSING 반환. + 2) CSV 경로(권장, 안정적) — 관세청 수출입무역통계(https://unipass.customs.go.kr/ets/) + 또는 산업통상부 보도자료에서 사용자가 다운로드한 월별 HS코드별 수출입 CSV를 + --csv 인자로 입력. 이 경로가 실패할 일이 없어 1차 권장 경로다. + +산출물 sector_export_trend(%, MoM 또는 YoY)는 qualitative_sell_strategy_v1의 +fundamental_trajectory 보강 입력 및 compute_satellite_candidate_score의 1차 팩터로 쓰인다. +""" +from __future__ import annotations + +import argparse +import csv +import json +import os +import sys +from collections import defaultdict +from pathlib import Path +from typing import Any + +import requests + +ROOT = Path(__file__).resolve().parents[1] +if str(ROOT) not in sys.path: + sys.path.insert(0, str(ROOT)) + +# 섹터 → HS코드 prefix(2~4자리). 위성종목 추천/매도판단에 쓰는 핵심 수출 섹터만 우선 등록. +SECTOR_HS_MAP: dict[str, tuple[str, ...]] = { + "반도체": ("8541", "8542"), + "자동차": ("8701", "8702", "8703", "8704"), + "2차전지": ("8507",), + "조선": ("8901", "8902", "8905"), + "철강": ("72",), + "석유화학": ("29", "39"), + "디스플레이": ("8524", "9013"), + "기계": ("84",), + "바이오": ("30",), # universe.Sector 실측 라벨이 "바이오"(헬스 접미사 없음) — 그대로 매칭 + "방산": ("93",), # 무기류·탄약(HS Ch.93) — 현대로템 등 보유종목 K-방산 테마 대응 +} + +CUSTOMS_API_BASE = "https://apis.data.go.kr/1220000/nitemtrade/getNitemtradeList" + + +def fetch_customs_trade_api( + session: requests.Session, + api_key: str | None, + hs_code: str, + start_ym: str, + end_ym: str, +) -> dict[str, Any]: + """data.go.kr 관세청 수출입통계 API 호출. 키 없거나 실패 시 DATA_MISSING(추정 금지).""" + if not api_key: + return {"status": "DATA_MISSING", "note": "CUSTOMS_API_KEY 미설정 — --csv 경로 사용 권장"} + try: + resp = session.get( + CUSTOMS_API_BASE, + params={ + "serviceKey": api_key, + "strtYymm": start_ym, + "endYymm": end_ym, + "hsSgn": hs_code, + "type": "json", + }, + timeout=15, + ) + resp.raise_for_status() + data = resp.json() + except Exception as exc: # noqa: BLE001 — 외부 API 실패는 광범위하게 잡아 DATA_MISSING 처리 + return {"status": "API_ERROR", "note": str(exc)} + return {"status": "OK", "raw": data, "source_url": CUSTOMS_API_BASE} + + +def load_trade_statistics_csv(path: Path) -> list[dict[str, Any]]: + """관세청/산업통상부 배포 CSV. 컬럼: 기간(YYYYMM), HS코드, 수출액(달러), 수입액(달러). + + 헤더명은 배포처마다 다를 수 있어 한글/영문 별칭을 모두 허용한다. + """ + alias = { + "기간": "period", "year_month": "period", "period": "period", + "hs코드": "hs_code", "hs_code": "hs_code", "hscode": "hs_code", + "수출액": "export_usd", "export": "export_usd", "export_usd": "export_usd", + "수입액": "import_usd", "import": "import_usd", "import_usd": "import_usd", + } + rows: list[dict[str, Any]] = [] + with path.open(encoding="utf-8-sig", newline="") as f: + reader = csv.DictReader(f) + for raw_row in reader: + row: dict[str, Any] = {} + for key, value in raw_row.items(): + norm_key = alias.get(str(key).strip().lower()) + if norm_key: + row[norm_key] = value + if {"period", "hs_code"}.issubset(row): + for money_field in ("export_usd", "import_usd"): + if money_field in row: + try: + row[money_field] = float(str(row[money_field]).replace(",", "")) + except ValueError: + row[money_field] = 0.0 + rows.append(row) + return rows + + +def compute_sector_export_trend( + rows: list[dict[str, Any]], + sector: str, + compare: str = "yoy", +) -> dict[str, Any]: + """sector_export_trend(%) = 최신월 수출액 / 비교월 수출액 - 1. + + compare="yoy": 12개월 전 동월 대비. compare="mom": 직전월 대비. + 데이터 부족 시 추정하지 않고 DATA_MISSING. + """ + hs_prefixes = SECTOR_HS_MAP.get(sector) + if not hs_prefixes: + return {"status": "UNKNOWN_SECTOR", "sector": sector, "known_sectors": list(SECTOR_HS_MAP)} + + by_period: dict[str, float] = defaultdict(float) + for row in rows: + hs_code = str(row.get("hs_code") or "") + if any(hs_code.startswith(prefix) for prefix in hs_prefixes): + period = str(row.get("period") or "") + by_period[period] += float(row.get("export_usd") or 0.0) + + if len(by_period) < 2: + return {"status": "DATA_MISSING", "sector": sector, "note": "기간별 수출액 표본 부족"} + + periods_sorted = sorted(by_period) + latest_period = periods_sorted[-1] + latest_value = by_period[latest_period] + + if compare == "mom": + compare_period = periods_sorted[-2] + else: + latest_ym = int(latest_period) + target_ym = latest_ym - 100 # YYYYMM에서 12개월 전 = -100 + compare_period = str(target_ym) + if compare_period not in by_period: + return {"status": "DATA_MISSING", "sector": sector, "note": f"YoY 비교월({compare_period}) 데이터 없음 — MoM으로 재시도 권장"} + + compare_value = by_period.get(compare_period, 0.0) + if compare_value <= 0: + return {"status": "DATA_MISSING", "sector": sector, "note": "비교월 수출액이 0 이하"} + + trend_pct = round((latest_value / compare_value - 1.0) * 100.0, 4) + return { + "status": "OK", + "sector": sector, + "compare": compare, + "latest_period": latest_period, + "compare_period": compare_period, + "sector_export_trend": trend_pct, + } + + +def main() -> int: + ap = argparse.ArgumentParser(description=__doc__) + ap.add_argument("--csv", type=Path, help="관세청/산업통상부 배포 수출입 CSV 경로(권장 경로)") + ap.add_argument("--sector", default="반도체", choices=list(SECTOR_HS_MAP)) + ap.add_argument("--compare", default="yoy", choices=["yoy", "mom"]) + ap.add_argument("--api-key", default=os.environ.get("CUSTOMS_API_KEY")) + ap.add_argument("--hs-code", default="", help="API 경로 사용 시 HS코드") + ap.add_argument("--start-ym", default="") + ap.add_argument("--end-ym", default="") + args = ap.parse_args() + + if args.csv: + rows = load_trade_statistics_csv(args.csv) + result = compute_sector_export_trend(rows, args.sector, args.compare) + else: + session = requests.Session() + result = fetch_customs_trade_api(session, args.api_key, args.hs_code, args.start_ym, args.end_ym) + + print(json.dumps(result, ensure_ascii=False, indent=2)) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tools/validate_qualitative_sell_strategy_pipeline_v1.py b/tools/validate_qualitative_sell_strategy_pipeline_v1.py new file mode 100644 index 00000000..babd5fc5 --- /dev/null +++ b/tools/validate_qualitative_sell_strategy_pipeline_v1.py @@ -0,0 +1,56 @@ +#!/usr/bin/env python3 +from __future__ import annotations + +import json +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] + + +def _read(path: Path) -> str: + return path.read_text(encoding="utf-8", errors="replace") if path.exists() else "" + + +def main() -> int: + files = { + "workflow": ROOT / ".gitea" / "workflows" / "qualitative_sell_strategy.yml", + "build_inputs": ROOT / "tools" / "build_qualitative_sell_inputs_v1.py", + "build_satellite": ROOT / "tools" / "build_satellite_candidate_recommendations_v1.py", + "evaluate": ROOT / "tools" / "evaluate_qualitative_sell_strategy_accuracy_v1.py", + "store": ROOT / "src" / "quant_engine" / "qualitative_sell_strategy_store_v1.py", + "package": ROOT / "package.json", + } + errors: list[str] = [] + + for name, path in files.items(): + if not path.exists(): + errors.append(f"missing:{name}") + + checks = { + "build_inputs_flags": ("--store-backend" in _read(files["build_inputs"]) and "--store-location" in _read(files["build_inputs"])), + "build_satellite_flags": ("--store-backend" in _read(files["build_satellite"]) and "--store-location" in _read(files["build_satellite"])), + "evaluate_flags": ("--store-backend" in _read(files["evaluate"]) and "--store-location" in _read(files["evaluate"])), + "store_contract": ("resolve_store_path" in _read(files["store"]) and "QualitativeSellStoreSpec" in _read(files["store"])), + "workflow_mentions_mock_validation": ("validate_kis_api_credentials_v1.py" in _read(files["workflow"])), + "workflow_has_schedule": ("schedule:" in _read(files["workflow"]) and "workflow_dispatch:" in _read(files["workflow"])), + "package_scripts": ("ops:sell-build" in _read(files["package"]) and "ops:sell-eval" in _read(files["package"]) and "ops:sell-validate" in _read(files["package"])), + } + + for key, ok in checks.items(): + if not ok: + errors.append(key) + + result = { + "formula_id": "QUALITATIVE_SELL_STRATEGY_PIPELINE_V1", + "gate": "PASS" if not errors else "FAIL", + "checks": checks, + "errors": errors, + } + out = ROOT / "Temp" / "qualitative_sell_strategy_pipeline_v1.json" + out.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8") + print(json.dumps(result, ensure_ascii=False, indent=2)) + return 0 if not errors else 1 + + +if __name__ == "__main__": + raise SystemExit(main()) From f99f9821d2d419d9fcf0d9eeeffdc4e5cc2adf65 Mon Sep 17 00:00:00 2001 From: kjh2064 Date: Sun, 21 Jun 2026 20:06:55 +0900 Subject: [PATCH 03/10] =?UTF-8?q?=EC=8A=A4=EB=83=85=EC=83=B7=20=EC=96=B4?= =?UTF-8?q?=EB=93=9C=EB=AF=BC=20=EC=9B=B9=20UI=20+=20WBS-7.10=20Tabler=20?= =?UTF-8?q?=ED=85=8C=EC=9D=B4=EB=B8=94=20=EA=B7=B8=EB=A6=AC=EB=93=9C=20?= =?UTF-8?q?=EC=A1=B0=ED=9A=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit settings/account_snapshot SQLite를 직접 편집하는 잠금/승인/변경이력 기반 웹 에디터를 추가하고, 2026-06-21 비판적 리뷰에서 요청된 테이블별 그리드 조회 기능(Tabler CDN)을 /tables 경로로 덧붙인다. - 잠금(lock)·승인(approval)·undo·변경로그 전체 감사 추적 - KIS Collection 대시보드 통합(별도 SQLite, 워크스페이스 DB와 분리) - WBS-7.10: 워크스페이스/KIS수집/정성매도전략 3개 SQLite, 11개 테이블을 Tabler 그리드로 조회 — 테이블명은 고정 화이트리스트와 정확히 일치할 때만 SQL에 사용(SQL 인젝션 방지, 단위테스트로 검증) --- .gitea/workflows/snapshot_admin.yml | 44 + src/quant_engine/snapshot_admin_server_v1.py | 3007 ++++++++++++++++++ src/quant_engine/snapshot_admin_store_v1.py | 993 ++++++ tests/unit/test_snapshot_admin_store_v1.py | 249 ++ tests/unit/test_snapshot_admin_web_v1.py | 144 + tools/run_snapshot_admin_server_v1.py | 164 + tools/validate_snapshot_admin_web_v1.py | 222 ++ tools/validate_snapshot_admin_workflow_v1.py | 66 + 8 files changed, 4889 insertions(+) create mode 100644 .gitea/workflows/snapshot_admin.yml create mode 100644 src/quant_engine/snapshot_admin_server_v1.py create mode 100644 src/quant_engine/snapshot_admin_store_v1.py create mode 100644 tests/unit/test_snapshot_admin_store_v1.py create mode 100644 tests/unit/test_snapshot_admin_web_v1.py create mode 100644 tools/run_snapshot_admin_server_v1.py create mode 100644 tools/validate_snapshot_admin_web_v1.py create mode 100644 tools/validate_snapshot_admin_workflow_v1.py diff --git a/.gitea/workflows/snapshot_admin.yml b/.gitea/workflows/snapshot_admin.yml new file mode 100644 index 00000000..dbbfc6f5 --- /dev/null +++ b/.gitea/workflows/snapshot_admin.yml @@ -0,0 +1,44 @@ +name: Snapshot Admin Web Validation + +on: + workflow_dispatch: + push: + paths: + - "src/quant_engine/snapshot_admin_server_v1.py" + - "src/quant_engine/snapshot_admin_store_v1.py" + - "tools/run_snapshot_admin_server_v1.py" + - "tools/validate_snapshot_admin_workflow_v1.py" + - "tools/validate_snapshot_admin_web_v1.py" + - "spec/15_account_snapshot_contract.yaml" + - "spec/18_settings_contract.yaml" + - "GatherTradingData.json" + +jobs: + validate-snapshot-admin: + runs-on: self-hosted + steps: + - name: Checkout Code + run: | + if [ -d .git ]; then + git remote set-url origin http://x-access-token:${{ secrets.GITHUB_TOKEN }}@192.168.123.100:8418/KimJaeHyun/myfinance.git + else + git init + git remote add origin http://x-access-token:${{ secrets.GITHUB_TOKEN }}@192.168.123.100:8418/KimJaeHyun/myfinance.git + fi + git fetch origin main --depth=1 + git reset --hard FETCH_HEAD + + - name: Validate Snapshot Admin Workflow + run: python3 tools/validate_snapshot_admin_workflow_v1.py + + - name: Validate Snapshot Admin Web UI + run: python3 tools/validate_snapshot_admin_web_v1.py + + - name: Notify Run Result + if: always() + run: | + STATUS="${{ job.status }}" + echo "=== Snapshot Admin Web Validation ===" + echo "status: $STATUS" + echo "workflow validation: Temp/snapshot_admin_workflow_v1.json" + echo "web validation: Temp/snapshot_admin_web_validation_v1.json" diff --git a/src/quant_engine/snapshot_admin_server_v1.py b/src/quant_engine/snapshot_admin_server_v1.py new file mode 100644 index 00000000..a9f26639 --- /dev/null +++ b/src/quant_engine/snapshot_admin_server_v1.py @@ -0,0 +1,3007 @@ +from __future__ import annotations + +import argparse +import json +import sqlite3 +import subprocess +from http import HTTPStatus +from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer +from pathlib import Path +from hashlib import sha256 +from typing import Any +from urllib.parse import urlparse, parse_qs + +ROOT = Path(__file__).resolve().parents[2] +SNAPSHOT_ADMIN_VERSION = "snapshot-admin-web-v6" +KIS_COLLECTION_DB = ROOT / "outputs" / "kis_data_collection" / "kis_data_collection.db" +KIS_COLLECTION_REPORT = ROOT / "Temp" / "kis_data_collection_v1.json" +QUALITATIVE_SELL_DB = ROOT / "outputs" / "qualitative_sell_strategy" / "qualitative_sell_strategy.db" + +# WBS-7.9 부속 — 테이블별 그리드 조회(Tabler). 화이트리스트에 없는 테이블명은 +# SQL에 절대 보간되지 않는다(요청 테이블명을 그대로 SELECT 문에 넣지 않고 +# 아래 레지스트리 키와 정확히 일치할 때만 허용). +WORKSPACE_BROWSABLE_TABLES = ( + "settings", + "account_snapshot", + "workspace_change_log", + "workspace_approval_v2", + "workspace_lock", + "workspace_meta", +) +COLLECTION_BROWSABLE_TABLES = ( + "collection_runs", + "collection_snapshots", + "collection_source_errors", +) +QUALITATIVE_SELL_BROWSABLE_TABLES = ( + "sell_strategy_results", + "satellite_recommendations", +) + + +def _resolve_table_db(table: str, workspace_db_path: Path) -> Path | None: + if table in WORKSPACE_BROWSABLE_TABLES: + return Path(workspace_db_path) + if table in COLLECTION_BROWSABLE_TABLES: + return KIS_COLLECTION_DB + if table in QUALITATIVE_SELL_BROWSABLE_TABLES: + return QUALITATIVE_SELL_DB + return None + + +def list_browsable_tables(workspace_db_path: Path) -> list[dict[str, Any]]: + tables: list[dict[str, Any]] = [] + for table in ( + *WORKSPACE_BROWSABLE_TABLES, + *COLLECTION_BROWSABLE_TABLES, + *QUALITATIVE_SELL_BROWSABLE_TABLES, + ): + db_path = _resolve_table_db(table, workspace_db_path) + exists = bool(db_path and db_path.exists()) + row_count = 0 + if exists: + try: + with sqlite3.connect(db_path) as conn: + row_count = conn.execute(f"SELECT COUNT(*) FROM {table}").fetchone()[0] # noqa: S608 - table is whitelist-checked above + except sqlite3.OperationalError: + exists = False + tables.append({"table": table, "db": str(db_path) if db_path else "", "exists": exists, "row_count": row_count}) + return tables + + +def fetch_table_rows(table: str, workspace_db_path: Path, *, limit: int = 50, offset: int = 0) -> dict[str, Any]: + db_path = _resolve_table_db(table, workspace_db_path) + if db_path is None: + raise ValueError(f"unknown or non-browsable table: {table}") + if not db_path.exists(): + return {"table": table, "db": str(db_path), "columns": [], "rows": [], "total": 0, "limit": limit, "offset": offset} + with sqlite3.connect(db_path) as conn: + conn.row_factory = sqlite3.Row + total = conn.execute(f"SELECT COUNT(*) FROM {table}").fetchone()[0] # noqa: S608 - whitelisted table name + cursor = conn.execute( + f"SELECT * FROM {table} ORDER BY rowid DESC LIMIT ? OFFSET ?", # noqa: S608 - whitelisted table name + (limit, offset), + ) + rows = [dict(row) for row in cursor.fetchall()] + columns = [description[0] for description in cursor.description] if cursor.description else [] + return {"table": table, "db": str(db_path), "columns": columns, "rows": rows, "total": total, "limit": limit, "offset": offset} +SNAPSHOT_ADMIN_VERSION_FILES = ( + ROOT / "src" / "quant_engine" / "snapshot_admin_server_v1.py", + ROOT / "src" / "quant_engine" / "snapshot_admin_store_v1.py", + ROOT / "src" / "quant_engine" / "data_collection_store_v1.py", + ROOT / "tools" / "run_snapshot_admin_server_v1.py", + ROOT / "tools" / "validate_snapshot_admin_web_v1.py", + ROOT / "tests" / "unit" / "test_snapshot_admin_web_v1.py", + ROOT / "package.json", +) + +from .snapshot_admin_store_v1 import ( + ACCOUNT_SNAPSHOT_CANONICAL_COLUMNS, + DEFAULT_DB, + DEFAULT_SEED_JSON, + export_payload, + clear_lock, + import_seed_json, + is_locked, + load_account_snapshot_rows, + load_approval_for_domain, + load_approval_rows, + load_change_log_rows, + load_locks, + load_settings_rows, + normalize_db_path, + now_kst_iso, + open_connection, + parse_account_snapshot_tsv, + parse_scalar, + record_change_log, + validate_account_snapshot_rows, + validate_settings_rows, + build_validation_suggestions, + build_safe_autofix_actions, + apply_safe_autofix_action, + lock_conflicts_for_rows, + set_approval, + set_lock, + replace_account_snapshot, + replace_settings, + undo_last_change, + summarize_workspace, +) +from .data_collection_store_v1 import load_collection_dashboard_state + + +def _strip_internal_fields(row: dict[str, Any]) -> dict[str, Any]: + return {key: value for key, value in row.items() if not key.startswith("_")} + + +def _snapshot_columns_from_rows(rows: list[dict[str, Any]]) -> list[str]: + columns = list(ACCOUNT_SNAPSHOT_CANONICAL_COLUMNS) + extras = sorted( + { + key + for row in rows + for key in row.keys() + if not key.startswith("_") and key not in ACCOUNT_SNAPSHOT_CANONICAL_COLUMNS + } + ) + for key in extras: + if key not in columns: + columns.append(key) + return columns + + +def _write_json(path: Path, payload: dict[str, Any]) -> Path: + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8") + return path + + +def _render_approval_packet_md(packet: dict[str, Any]) -> str: + pending = packet.get("pending_targets") if isinstance(packet.get("pending_targets"), list) else [] + summary = packet.get("summary") if isinstance(packet.get("summary"), dict) else {} + lines = [ + "# Snapshot Admin Approval Packet", + "", + "## Summary", + "", + f"- settings_changed: {summary.get('settings_changed', 0)}", + f"- account_snapshot_changed: {summary.get('account_snapshot_changed', 0)}", + f"- pending_target_count: {summary.get('pending_target_count', 0)}", + "", + "## Pending Targets", + "", + ] + if pending: + for item in pending[:100]: + if not isinstance(item, dict): + continue + lines.append(f"- {item.get('domain', '')}:{item.get('target_ref', '')} ({item.get('change_type', '')})") + else: + lines.append("_none_") + return "\n".join(lines) + + +def write_approval_packet_artifacts(packet: dict[str, Any]) -> dict[str, str]: + json_path = ROOT / "Temp" / "snapshot_admin_approval_packet_v1.json" + md_path = ROOT / "Temp" / "snapshot_admin_approval_packet_v1.md" + _write_json(json_path, packet) + md_path.parent.mkdir(parents=True, exist_ok=True) + md_path.write_text(_render_approval_packet_md(packet), encoding="utf-8") + return {"json_path": str(json_path), "md_path": str(md_path)} + + +def _git_info() -> dict[str, Any]: + try: + commit = subprocess.check_output( + ["git", "rev-parse", "--short", "HEAD"], + cwd=str(ROOT), + text=True, + stderr=subprocess.DEVNULL, + ).strip() + status = subprocess.check_output( + ["git", "status", "--porcelain"], + cwd=str(ROOT), + text=True, + stderr=subprocess.DEVNULL, + ) + return { + "commit": commit, + "dirty": bool(status.strip()), + "tree_state": "DIRTY" if status.strip() else "CLEAN", + } + except Exception: + return { + "commit": "", + "dirty": False, + "tree_state": "UNKNOWN", + } + + +def _source_fingerprint() -> dict[str, Any]: + digest = sha256() + latest_mtime = 0.0 + for path in SNAPSHOT_ADMIN_VERSION_FILES: + if not path.exists(): + continue + try: + data = path.read_bytes() + digest.update(path.as_posix().encode("utf-8")) + digest.update(b"\0") + digest.update(data) + latest_mtime = max(latest_mtime, path.stat().st_mtime) + except OSError: + continue + return { + "fingerprint": digest.hexdigest()[:16], + "latest_mtime": latest_mtime, + } + + +def _approval_entry_from_conn(conn, domain: str, target_ref: str = "*") -> dict[str, Any] | None: + ensure_schema(conn) + row = conn.execute( + f""" + SELECT domain, target_ref, status, approved_by, approved_at, note, updated_at + FROM {APPROVAL_TABLE} + WHERE domain = ? AND target_ref = ? + LIMIT 1 + """, + (domain, target_ref or "*"), + ).fetchone() + return dict(row) if row is not None else None + + +def _lock_entry_from_conn(conn, domain: str, target_ref: str = "*") -> dict[str, Any] | None: + ensure_schema(conn) + row = conn.execute( + f""" + SELECT domain, target_ref, locked_by, reason, locked_at + FROM {LOCK_TABLE} + WHERE domain = ? AND target_ref = ? + LIMIT 1 + """, + (domain, target_ref or "*"), + ).fetchone() + return dict(row) if row is not None else None + + +def build_ui_state(db_path: Path | str | None = None) -> dict[str, Any]: + summary = summarize_workspace(db_path) + settings_rows = load_settings_rows(db_path) + account_rows = [_strip_internal_fields(row) for row in load_account_snapshot_rows(db_path)] + settings_errors = validate_settings_rows(settings_rows) + snapshot_errors = validate_account_snapshot_rows(account_rows) + suggestions = build_validation_suggestions(settings_rows, account_rows) + autofix_actions = build_safe_autofix_actions(settings_rows, account_rows) + collection = load_collection_dashboard_state(KIS_COLLECTION_DB, KIS_COLLECTION_REPORT) + return { + "version": { + "app": SNAPSHOT_ADMIN_VERSION, + "git": _git_info(), + "source": _source_fingerprint(), + }, + "summary": summary, + "approval_rows": load_approval_rows(db_path), + "approval_settings": load_approval_for_domain(db_path, "settings"), + "approval_account_snapshot": load_approval_for_domain(db_path, "account_snapshot"), + "locks": load_locks(db_path), + "recent_changes": load_change_log_rows(db_path, limit=12), + "history_counts": { + "changes": len(load_change_log_rows(db_path, limit=200)), + "approvals": len(load_approval_rows(db_path)), + "locks": len(load_locks(db_path)), + }, + "settings_rows": settings_rows, + "account_snapshot_rows": account_rows, + "account_snapshot_columns": _snapshot_columns_from_rows(account_rows), + "validation": { + "settings": settings_errors, + "account_snapshot": snapshot_errors, + "suggestions": suggestions, + }, + "autofix_actions": autofix_actions, + "collection": collection, + "generated_at": now_kst_iso(), + } + + +def _json_response(handler: BaseHTTPRequestHandler, status: int, payload: Any) -> None: + body = json.dumps(payload, ensure_ascii=False, indent=2).encode("utf-8") + handler.send_response(status) + handler.send_header("Content-Type", "application/json; charset=utf-8") + handler.send_header("Content-Length", str(len(body))) + handler.end_headers() + handler.wfile.write(body) + + +def _text_response(handler: BaseHTTPRequestHandler, status: int, text: str, content_type: str = "text/plain; charset=utf-8") -> None: + body = text.encode("utf-8") + handler.send_response(status) + handler.send_header("Content-Type", content_type) + handler.send_header("Content-Length", str(len(body))) + handler.end_headers() + handler.wfile.write(body) + + +def _read_json_body(handler: BaseHTTPRequestHandler) -> dict[str, Any]: + length = int(handler.headers.get("Content-Length") or "0") + raw = handler.rfile.read(length).decode("utf-8") if length else "{}" + payload = json.loads(raw or "{}") + if not isinstance(payload, dict): + raise ValueError("JSON body must be an object") + return payload + + +def render_index_html() -> str: + return """ + + + + + Snapshot Admin + + + +
+

Snapshot Admin

+
SQLite canonical editor for settings and account_snapshot. Save via API only; xlsx stays as export surface.
+
+ Open collection dashboard + Open table browser +
+
+
+
+
+
+
+

Workspace

+
+ + + + + + +
+
+
Loading...
+
+
+
+
Validation
+ 

+              
Suggestions

+              

+            

+            

+              
Diff preview

+              

+            

+          

+        

+      

+
+      

+        

+          
Approval & Locks

+          

+            
+            
+            
+            
+            
+            
+          

+        

+        

+          

+            

+              
settings approval

+              
snapshot approval

+              

+              

+              

+              

+                
+                
+                
+                
+                
+                
+                
+              

+            

+            

+              
Recent change log

+              

+                
+                
+              

+              

+              
Timeline

+              

+            

+          

+        

+      

+
+      

+        

+          
KIS Collection

+          

+            
+            
+          

+        

+        

+          

+            

+              
collection: loading...

+              

+              

+              

+                
+                
+              

+            

+            

+              
Recent collector runs

+              

+              
Recent collector snapshots

+              

+              
Recent collector errors

+              

+              
Collection detail

+              

+            

+          

+        

+      

+
+      

+        

+          
Selection Inspector

+          

+            
+            
+            
+            
+            
+          

+        

+        

+          

+            

+              
No row selected.

+              

+              
Recent row history

+              

+            

+            

+              
Batch paste

+              

+                
+                
+              

+              
+              
Tip: clipboard paste still works directly in the grid. This panel is for multi-row batch edit against the selected row.

+              
Shortcuts: `Ctrl+S` save current domain, `Ctrl+Enter` save current domain, `Delete` remove selected row.

+            

+          

+        

+      

+
+      

+        

+          
Settings

+          

+            
+            
+          

+        

+        

+          

+            
+            
+            
+            
+            
+          

+          
+            
+            
+            
+            
+            
+          
+          

+          

+            
+          

+        

+      

+
+      

+        

+          
Account Snapshot

+          

+            
+            
+          

+        

+        

+          Paste TSV below and replace all rows
+          Canonical column order follows spec/15_account_snapshot_contract.yaml
+        

+        

+          

+            
+            
+            
+            
+            
+          

+          
+            
+            
+            
+            
+            
+            
+            
+            
+            
+          
+          

+            
+          

+          

+          

+            
+            

+              
+              
+            

+          

+        

+      

+    

+  

+
+  
+
+
+"""
+
+
+def render_collection_html() -> str:
+    return """
+
+
+  
+  
+  KIS Collection Dashboard
+  
+
+
+  

+    
KIS Collection Dashboard

+    
Separate read-only view for KIS collection run, snapshots, errors, and raw JSON evidence.

+  

+  

+    

+      

+        

+          
collection: loading...

+          

+        

+        

+          Back to workspace
+          Open table browser
+          
+          
+          
+        

+      

+      

+        

+          

+            

+            

+              
+              
+              
+              
+            

+            
Recent collector runs

+            

+            
Recent collector snapshots

+            

+            
Recent collector errors

+            

+          

+          

+            
Collection detail

+            

+          

+        

+      

+    

+  

+  
+
+
+"""
+
+
+def render_tables_html() -> str:
+    return """
+
+
+  
+  
+  Snapshot Admin — Table Browser
+  
+
+
+  

+    

+      

+        
Snapshot Admin — Table Browser

+        

+          Workspace editor
+          Collection dashboard
+        

+      

+    

+    

+      

+        

+          

+            

+              

+                
+                
+                
+              

+              

+                
+                
+                
+                
+              

+            

+            

+              
+                
+                
+              

+            

+          

+        

+      

+    

+  

+  
+
+
+"""
+
+
+class SnapshotAdminHandler(BaseHTTPRequestHandler):
+    db_path: Path = DEFAULT_DB
+    seed_json_path: Path = DEFAULT_SEED_JSON
+
+    def log_message(self, format: str, *args: Any) -> None:  # noqa: A003
+        return
+
+    def _handle_exception(self, exc: Exception) -> None:
+        _json_response(self, HTTPStatus.INTERNAL_SERVER_ERROR, {"detail": str(exc)})
+
+    def do_GET(self) -> None:  # noqa: N802
+        parsed = urlparse(self.path)
+        if parsed.path == "/":
+            _text_response(self, HTTPStatus.OK, render_index_html(), "text/html; charset=utf-8")
+            return
+        if parsed.path == "/collection":
+            _text_response(self, HTTPStatus.OK, render_collection_html(), "text/html; charset=utf-8")
+            return
+        if parsed.path == "/tables":
+            _text_response(self, HTTPStatus.OK, render_tables_html(), "text/html; charset=utf-8")
+            return
+        if parsed.path == "/api/tables":
+            _json_response(self, HTTPStatus.OK, {"tables": list_browsable_tables(self.db_path)})
+            return
+        if parsed.path == "/api/table_rows":
+            query = parse_qs(parsed.query)
+            table = (query.get("table") or [""])[0]
+            try:
+                limit = int((query.get("limit") or ["50"])[0])
+                offset = int((query.get("offset") or ["0"])[0])
+            except ValueError:
+                _json_response(self, HTTPStatus.BAD_REQUEST, {"detail": "limit/offset must be integers"})
+                return
+            limit = min(max(limit, 1), 500)
+            offset = max(offset, 0)
+            try:
+                payload = fetch_table_rows(table, self.db_path, limit=limit, offset=offset)
+            except ValueError as exc:
+                _json_response(self, HTTPStatus.BAD_REQUEST, {"detail": str(exc)})
+                return
+            _json_response(self, HTTPStatus.OK, payload)
+            return
+        if parsed.path == "/api/state":
+            _json_response(self, HTTPStatus.OK, build_ui_state(self.db_path))
+            return
+        if parsed.path == "/api/history":
+            _json_response(
+                self,
+                HTTPStatus.OK,
+                {
+                    "settings": load_change_log_rows(self.db_path, limit=25),
+                    "approvals": load_approval_rows(self.db_path),
+                    "locks": load_locks(self.db_path),
+                },
+            )
+            return
+        if parsed.path == "/api/export":
+            _text_response(
+                self,
+                HTTPStatus.OK,
+                json.dumps(export_payload(self.db_path), ensure_ascii=False, indent=2),
+                "application/json; charset=utf-8",
+            )
+            return
+        if parsed.path == "/favicon.ico":
+            _text_response(self, HTTPStatus.NO_CONTENT, "")
+            return
+        _json_response(self, HTTPStatus.NOT_FOUND, {"detail": "not found"})
+
+    def do_POST(self) -> None:  # noqa: N802
+        parsed = urlparse(self.path)
+        try:
+            if parsed.path == "/api/bootstrap":
+                summary = import_seed_json(self.db_path, self.seed_json_path)
+                _json_response(self, HTTPStatus.OK, summary)
+                return
+            payload = _read_json_body(self)
+            if parsed.path == "/api/settings/save":
+                if is_locked(self.db_path, "settings"):
+                    raise ValueError("settings are locked")
+                rows = payload.get("rows")
+                if not isinstance(rows, list):
+                    raise ValueError("rows must be a list")
+                normalized_rows = []
+                for idx, row in enumerate(rows, start=1):
+                    if not isinstance(row, dict):
+                        continue
+                    key = str(row.get("key") or "").strip()
+                    if not key:
+                        continue
+                    normalized_rows.append(
+                        {
+                            "ordinal": idx,
+                            "key": key,
+                            "value": row.get("value", ""),
+                            "note": str(row.get("note") or ""),
+                        }
+                    )
+                conflicts = lock_conflicts_for_rows(self.db_path, "settings", normalized_rows)
+                if conflicts:
+                    refs = ", ".join(sorted({str(item.get("target_ref") or "") for item in conflicts if item.get("target_ref")}))
+                    raise ValueError(f"settings lock conflict: {refs}")
+                with open_connection(self.db_path) as conn:
+                    replace_settings(conn, normalized_rows)
+                _json_response(self, HTTPStatus.OK, summarize_workspace(self.db_path))
+                return
+            if parsed.path == "/api/account_snapshot/save":
+                if is_locked(self.db_path, "account_snapshot"):
+                    raise ValueError("account_snapshot is locked")
+                rows = payload.get("rows")
+                if not isinstance(rows, list):
+                    raise ValueError("rows must be a list")
+                normalized_rows: list[dict[str, Any]] = []
+                for idx, row in enumerate(rows, start=1):
+                    if not isinstance(row, dict):
+                        continue
+                    candidate = {key: value for key, value in row.items() if not key.startswith("_")}
+                    candidate["ordinal"] = idx
+                    normalized_rows.append(candidate)
+                conflicts = lock_conflicts_for_rows(self.db_path, "account_snapshot", normalized_rows)
+                if conflicts:
+                    refs = ", ".join(sorted({str(item.get("target_ref") or "") for item in conflicts if item.get("target_ref")}))
+                    raise ValueError(f"account_snapshot lock conflict: {refs}")
+                with open_connection(self.db_path) as conn:
+                    replace_account_snapshot(conn, normalized_rows)
+                _json_response(self, HTTPStatus.OK, summarize_workspace(self.db_path))
+                return
+            if parsed.path == "/api/account_snapshot/import_tsv":
+                if is_locked(self.db_path, "account_snapshot"):
+                    raise ValueError("account_snapshot is locked")
+                tsv_text = str(payload.get("tsv") or "")
+                rows = parse_account_snapshot_tsv(tsv_text)
+                with open_connection(self.db_path) as conn:
+                    replace_account_snapshot(conn, rows)
+                _json_response(self, HTTPStatus.OK, summarize_workspace(self.db_path))
+                return
+            if parsed.path == "/api/approval_packet":
+                packet = payload.get("packet")
+                if not isinstance(packet, dict):
+                    raise ValueError("packet must be an object")
+                artifacts = write_approval_packet_artifacts(packet)
+                response = {
+                    "gate": "PASS",
+                    "packet_path": artifacts["json_path"],
+                    "md_path": artifacts["md_path"],
+                    "formula_id": packet.get("formula_id", "SNAPSHOT_ADMIN_APPROVAL_PACKET_V1"),
+                }
+                _json_response(self, HTTPStatus.OK, response)
+                return
+            if parsed.path == "/api/approve":
+                domain = str(payload.get("domain") or "")
+                if domain not in {"settings", "account_snapshot"}:
+                    raise ValueError("domain must be settings or account_snapshot")
+                target_ref = str(payload.get("target_ref") or "*")
+                with open_connection(self.db_path) as conn:
+                    before = _approval_entry_from_conn(conn, domain, target_ref)
+                    set_approval(conn, domain, "APPROVED", target_ref=target_ref, approved_by="ui", note="manual approval")
+                    after = _approval_entry_from_conn(conn, domain, target_ref)
+                    record_change_log(
+                        conn,
+                        domain=domain,
+                        action="approve",
+                        target_ref=target_ref,
+                        before_json=before,
+                        after_json=after,
+                        actor="ui",
+                        note="manual approval",
+                    )
+                    conn.commit()
+                _json_response(self, HTTPStatus.OK, {"domain": domain, "target_ref": target_ref, "status": "APPROVED"})
+                return
+            if parsed.path == "/api/lock":
+                domain = str(payload.get("domain") or "")
+                target_ref = str(payload.get("target_ref") or "*")
+                if domain not in {"settings", "account_snapshot"}:
+                    raise ValueError("domain must be settings or account_snapshot")
+                with open_connection(self.db_path) as conn:
+                    before = _lock_entry_from_conn(conn, domain, target_ref)
+                    set_lock(conn, domain, target_ref, locked_by="ui", reason="manual lock")
+                    after = _lock_entry_from_conn(conn, domain, target_ref)
+                    record_change_log(
+                        conn,
+                        domain=domain,
+                        action="lock",
+                        target_ref=target_ref,
+                        before_json=before,
+                        after_json=after,
+                        actor="ui",
+                        note="manual lock",
+                    )
+                    conn.commit()
+                _json_response(self, HTTPStatus.OK, {"domain": domain, "target_ref": target_ref, "status": "LOCKED"})
+                return
+            if parsed.path == "/api/unlock":
+                domain = str(payload.get("domain") or "")
+                target_ref = str(payload.get("target_ref") or "*")
+                if domain not in {"settings", "account_snapshot"}:
+                    raise ValueError("domain must be settings or account_snapshot")
+                with open_connection(self.db_path) as conn:
+                    before = _lock_entry_from_conn(conn, domain, target_ref)
+                    clear_lock(conn, domain, target_ref)
+                    after = _lock_entry_from_conn(conn, domain, target_ref)
+                    record_change_log(
+                        conn,
+                        domain=domain,
+                        action="unlock",
+                        target_ref=target_ref,
+                        before_json=before,
+                        after_json=after,
+                        actor="ui",
+                        note="manual unlock",
+                    )
+                    conn.commit()
+                _json_response(self, HTTPStatus.OK, {"domain": domain, "target_ref": target_ref, "status": "UNLOCKED"})
+                return
+            if parsed.path == "/api/undo":
+                domain = str(payload.get("domain") or "")
+                if domain not in {"settings", "account_snapshot"}:
+                    raise ValueError("domain must be settings or account_snapshot")
+                if is_locked(self.db_path, domain):
+                    raise ValueError(f"{domain} is locked")
+                with open_connection(self.db_path) as conn:
+                    result = undo_last_change(conn, domain, actor="ui")
+                _json_response(self, HTTPStatus.OK, result if result else {"domain": domain, "status": "UNDONE"})
+                return
+            if parsed.path == "/api/autofix":
+                action_id = str(payload.get("action_id") or "")
+                if not action_id:
+                    raise ValueError("action_id required")
+                with open_connection(self.db_path) as conn:
+                    result = apply_safe_autofix_action(conn, action_id, actor="ui")
+                _json_response(self, HTTPStatus.OK, result)
+                return
+            _json_response(self, HTTPStatus.NOT_FOUND, {"detail": "not found"})
+        except Exception as exc:  # noqa: BLE001
+            self._handle_exception(exc)
+
+
+def serve(host: str, port: int, db_path: Path | str | None = None, seed_json_path: Path | str | None = None, bootstrap: bool = True) -> None:
+    db = normalize_db_path(db_path)
+    seed = Path(seed_json_path) if seed_json_path else DEFAULT_SEED_JSON
+    if bootstrap and seed.exists():
+        with open_connection(db) as conn:
+            from .snapshot_admin_store_v1 import ensure_schema
+
+            ensure_schema(conn)
+        if summarize_workspace(db)["settings_rows"] == 0 and summarize_workspace(db)["account_snapshot_rows"] == 0:
+            import_seed_json(db, seed)
+    SnapshotAdminHandler.db_path = db
+    SnapshotAdminHandler.seed_json_path = seed
+    server = ThreadingHTTPServer((host, port), SnapshotAdminHandler)
+    print(f"Snapshot Admin listening on http://{host}:{port}")
+    print(f"SQLite DB: {db}")
+    print(f"Seed JSON: {seed}")
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Run the snapshot admin web server.")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8787)
+    parser.add_argument("--db", type=Path, default=DEFAULT_DB)
+    parser.add_argument("--seed", type=Path, default=DEFAULT_SEED_JSON)
+    parser.add_argument("--no-bootstrap", action="store_true")
+    args = parser.parse_args()
+    serve(args.host, args.port, args.db, args.seed, bootstrap=not args.no_bootstrap)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/src/quant_engine/snapshot_admin_store_v1.py b/src/quant_engine/snapshot_admin_store_v1.py
new file mode 100644
index 00000000..4b40b0f8
--- /dev/null
+++ b/src/quant_engine/snapshot_admin_store_v1.py
@@ -0,0 +1,993 @@
+from __future__ import annotations
+
+import json
+import re
+import sqlite3
+from datetime import datetime
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+from zoneinfo import ZoneInfo
+
+import yaml
+
+
+ROOT = Path(__file__).resolve().parents[2]
+DEFAULT_DB = ROOT / "outputs" / "snapshot_admin" / "snapshot_admin.db"
+DEFAULT_SEED_JSON = ROOT / "GatherTradingData.json"
+KST = ZoneInfo("Asia/Seoul")
+
+SETTINGS_TABLE = "settings"
+SNAPSHOT_TABLE = "account_snapshot"
+CHANGE_LOG_TABLE = "workspace_change_log"
+APPROVAL_TABLE = "workspace_approval_v2"
+LOCK_TABLE = "workspace_lock"
+
+ACCOUNT_SNAPSHOT_CANONICAL_COLUMNS = [
+    "captured_at",
+    "account",
+    "account_type",
+    "ticker",
+    "name",
+    "holding_quantity",
+    "available_quantity",
+    "average_cost",
+    "total_cost",
+    "current_price",
+    "market_value",
+    "profit_loss",
+    "return_pct",
+    "immediate_cash",
+    "settlement_cash_d2",
+    "available_cash",
+    "open_order_amount",
+    "monthly_contribution_limit",
+    "monthly_contribution_used",
+    "parse_status",
+    "user_confirmed",
+    "stop_price",
+    "highest_price_since_entry",
+    "entry_date",
+    "entry_stage",
+    "position_type",
+    "last_updated",
+]
+
+ALLOWED_PARSE_STATUS = {
+    "CAPTURE_READ_OK",
+    "CAPTURE_READ_FAILED",
+    "CAPTURE_PROVIDED_BUT_NOT_HOLDINGS",
+    "NOT_PROVIDED",
+}
+
+SETTINGS_SPEC_PATH = ROOT / "spec" / "18_settings_contract.yaml"
+ACCOUNT_SNAPSHOT_SPEC_PATH = ROOT / "spec" / "15_account_snapshot_contract.yaml"
+
+
+def now_kst_iso() -> str:
+    return datetime.now(tz=KST).isoformat(timespec="seconds")
+
+
+def parse_scalar(value: str) -> Any:
+    text = value.strip()
+    if text == "":
+        return ""
+    if text.lower() in {"null", "none"}:
+        return None
+    if text.lower() in {"true", "false"}:
+        return text.lower() == "true"
+    try:
+        return json.loads(text)
+    except Exception:
+        return text
+
+
+def _json_dump(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False)
+
+
+def _json_load(text: str) -> Any:
+    try:
+        return json.loads(text)
+    except Exception:
+        return text
+
+
+def normalize_db_path(db_path: Path | str | None = None) -> Path:
+    path = Path(db_path) if db_path else DEFAULT_DB
+    path.parent.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def open_connection(db_path: Path | str | None = None) -> sqlite3.Connection:
+    conn = sqlite3.connect(normalize_db_path(db_path))
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA foreign_keys = ON")
+    conn.execute("PRAGMA journal_mode = WAL")
+    return conn
+
+
+def ensure_schema(conn: sqlite3.Connection) -> None:
+    conn.execute(
+        f"""
+        CREATE TABLE IF NOT EXISTS {SETTINGS_TABLE} (
+            ordinal INTEGER NOT NULL,
+            key TEXT PRIMARY KEY,
+            value_json TEXT NOT NULL,
+            note TEXT NOT NULL DEFAULT '',
+            updated_at TEXT NOT NULL
+        )
+        """
+    )
+    conn.execute(
+        f"""
+        CREATE TABLE IF NOT EXISTS {SNAPSHOT_TABLE} (
+            ordinal INTEGER NOT NULL,
+            row_json TEXT NOT NULL,
+            captured_at TEXT NOT NULL DEFAULT '',
+            account TEXT NOT NULL DEFAULT '',
+            account_type TEXT NOT NULL DEFAULT '',
+            ticker TEXT NOT NULL DEFAULT '',
+            name TEXT NOT NULL DEFAULT '',
+            parse_status TEXT NOT NULL DEFAULT '',
+            user_confirmed TEXT NOT NULL DEFAULT '',
+            updated_at TEXT NOT NULL
+        )
+        """
+    )
+    conn.execute(
+        f"CREATE INDEX IF NOT EXISTS idx_{SNAPSHOT_TABLE}_captured_at ON {SNAPSHOT_TABLE}(captured_at)"
+    )
+    conn.execute(
+        f"CREATE INDEX IF NOT EXISTS idx_{SNAPSHOT_TABLE}_ticker ON {SNAPSHOT_TABLE}(ticker)"
+    )
+    conn.execute(
+        "CREATE TABLE IF NOT EXISTS workspace_meta (key TEXT PRIMARY KEY, value_json TEXT NOT NULL)"
+    )
+    conn.execute(
+        f"""
+        CREATE TABLE IF NOT EXISTS {CHANGE_LOG_TABLE} (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            domain TEXT NOT NULL,
+            action TEXT NOT NULL,
+            target_ref TEXT NOT NULL DEFAULT '',
+            actor TEXT NOT NULL DEFAULT 'system',
+            note TEXT NOT NULL DEFAULT '',
+            before_json TEXT NOT NULL DEFAULT 'null',
+            after_json TEXT NOT NULL DEFAULT 'null',
+            created_at TEXT NOT NULL
+        )
+        """
+    )
+    conn.execute(
+        f"""
+        CREATE TABLE IF NOT EXISTS {APPROVAL_TABLE} (
+            domain TEXT NOT NULL,
+            target_ref TEXT NOT NULL DEFAULT '*',
+            status TEXT NOT NULL,
+            approved_by TEXT NOT NULL DEFAULT '',
+            approved_at TEXT NOT NULL DEFAULT '',
+            note TEXT NOT NULL DEFAULT '',
+            updated_at TEXT NOT NULL,
+            PRIMARY KEY (domain, target_ref)
+        )
+        """
+    )
+    conn.execute(
+        f"""
+        CREATE TABLE IF NOT EXISTS {LOCK_TABLE} (
+            domain TEXT NOT NULL,
+            target_ref TEXT NOT NULL DEFAULT '',
+            locked_by TEXT NOT NULL DEFAULT '',
+            reason TEXT NOT NULL DEFAULT '',
+            locked_at TEXT NOT NULL,
+            PRIMARY KEY (domain, target_ref)
+        )
+        """
+    )
+    conn.commit()
+
+
+def _normalize_settings_rows(settings: Any) -> list[dict[str, Any]]:
+    if isinstance(settings, list):
+        rows: list[dict[str, Any]] = []
+        for idx, item in enumerate(settings, start=1):
+            if isinstance(item, dict) and "key" in item:
+                rows.append(
+                    {
+                        "ordinal": int(item.get("ordinal") or idx),
+                        "key": str(item.get("key") or ""),
+                        "value": item.get("value", ""),
+                        "note": str(item.get("note") or ""),
+                    }
+                )
+        return rows
+    if isinstance(settings, dict):
+        rows = []
+        for idx, (key, value) in enumerate(settings.items(), start=1):
+            rows.append({"ordinal": idx, "key": str(key), "value": value, "note": ""})
+        return rows
+    return []
+
+
+def _normalize_snapshot_rows(rows: Any) -> list[dict[str, Any]]:
+    if not isinstance(rows, list):
+        return []
+    normalized: list[dict[str, Any]] = []
+    for idx, item in enumerate(rows, start=1):
+        if isinstance(item, dict):
+            row = dict(item)
+            row.setdefault("ordinal", idx)
+            normalized.append(row)
+    return normalized
+
+
+def seed_payload_from_json(json_path: Path | str) -> dict[str, Any]:
+    payload = json.loads(Path(json_path).read_text(encoding="utf-8"))
+    data = payload.get("data") if isinstance(payload, dict) else None
+    if not isinstance(data, dict):
+        data = payload if isinstance(payload, dict) else {}
+    settings = _normalize_settings_rows(data.get("settings"))
+    account_snapshot = _normalize_snapshot_rows(data.get("account_snapshot"))
+    return {
+        "meta": payload.get("meta") if isinstance(payload, dict) else {},
+        "settings": settings,
+        "account_snapshot": account_snapshot,
+    }
+
+
+def replace_settings(conn: sqlite3.Connection, rows: list[dict[str, Any]]) -> None:
+    ensure_schema(conn)
+    errors = validate_settings_rows(rows)
+    if errors:
+        raise ValueError("; ".join(errors))
+    old_rows = load_settings_rows_from_conn(conn)
+    conn.execute(f"DELETE FROM {SETTINGS_TABLE}")
+    for idx, row in enumerate(rows, start=1):
+        key = str(row.get("key") or "").strip()
+        if not key:
+            continue
+        conn.execute(
+            f"""
+            INSERT INTO {SETTINGS_TABLE} (ordinal, key, value_json, note, updated_at)
+            VALUES (?, ?, ?, ?, ?)
+            """,
+            (
+                int(row.get("ordinal") or idx),
+                key,
+                _json_dump(row.get("value", "")),
+                str(row.get("note") or ""),
+                now_kst_iso(),
+            ),
+        )
+    record_change_log(
+        conn,
+        domain=SETTINGS_TABLE,
+        action="replace",
+        before_json=old_rows,
+        after_json=rows,
+        target_ref="*",
+        note="settings replace",
+    )
+    set_approval(conn, SETTINGS_TABLE, "PENDING", note="settings updated")
+    conn.commit()
+
+
+def replace_account_snapshot(conn: sqlite3.Connection, rows: list[dict[str, Any]]) -> None:
+    ensure_schema(conn)
+    errors = validate_account_snapshot_rows(rows)
+    if errors:
+        raise ValueError("; ".join(errors))
+    old_rows = load_account_snapshot_rows_from_conn(conn)
+    conn.execute(f"DELETE FROM {SNAPSHOT_TABLE}")
+    for idx, row in enumerate(rows, start=1):
+        normalized = dict(row)
+        ordinal = int(normalized.pop("ordinal", idx) or idx)
+        captured_at = str(normalized.get("captured_at") or "")
+        account = str(normalized.get("account") or "")
+        account_type = str(normalized.get("account_type") or "")
+        ticker = str(normalized.get("ticker") or "")
+        name = str(normalized.get("name") or "")
+        parse_status = str(normalized.get("parse_status") or "")
+        user_confirmed = str(normalized.get("user_confirmed") or "")
+        conn.execute(
+            f"""
+            INSERT INTO {SNAPSHOT_TABLE} (
+                ordinal, row_json, captured_at, account, account_type, ticker, name,
+                parse_status, user_confirmed, updated_at
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                ordinal,
+                _json_dump(normalized),
+                captured_at,
+                account,
+                account_type,
+                ticker,
+                name,
+                parse_status,
+                user_confirmed,
+                now_kst_iso(),
+            ),
+        )
+    record_change_log(
+        conn,
+        domain=SNAPSHOT_TABLE,
+        action="replace",
+        before_json=old_rows,
+        after_json=rows,
+        target_ref="*",
+        note="account_snapshot replace",
+    )
+    set_approval(conn, SNAPSHOT_TABLE, "PENDING", note="account_snapshot updated")
+    conn.commit()
+
+
+def import_seed_json(db_path: Path | str | None, json_path: Path | str) -> dict[str, Any]:
+    payload = seed_payload_from_json(json_path)
+    with open_connection(db_path) as conn:
+        replace_settings(conn, payload["settings"])
+        replace_account_snapshot(conn, payload["account_snapshot"])
+        conn.execute(
+            "INSERT OR REPLACE INTO workspace_meta(key, value_json) VALUES (?, ?)",
+            ("seed_json_path", _json_dump(str(Path(json_path).resolve()))),
+        )
+        conn.execute(
+            "INSERT OR REPLACE INTO workspace_meta(key, value_json) VALUES (?, ?)",
+            ("seeded_at", _json_dump(now_kst_iso())),
+        )
+        conn.commit()
+    return summarize_workspace(db_path)
+
+
+def load_settings_rows(db_path: Path | str | None = None) -> list[dict[str, Any]]:
+    with open_connection(db_path) as conn:
+        return load_settings_rows_from_conn(conn)
+
+
+def load_settings_rows_from_conn(conn: sqlite3.Connection) -> list[dict[str, Any]]:
+    ensure_schema(conn)
+    rows = conn.execute(
+        f"SELECT ordinal, key, value_json, note, updated_at FROM {SETTINGS_TABLE} ORDER BY ordinal ASC, key ASC"
+    ).fetchall()
+    return [
+        {
+            "ordinal": int(row["ordinal"]),
+            "key": row["key"],
+            "value": _json_load(row["value_json"]),
+            "note": row["note"],
+            "updated_at": row["updated_at"],
+        }
+        for row in rows
+    ]
+
+
+def load_account_snapshot_rows(db_path: Path | str | None = None) -> list[dict[str, Any]]:
+    with open_connection(db_path) as conn:
+        return load_account_snapshot_rows_from_conn(conn)
+
+
+def load_account_snapshot_rows_from_conn(conn: sqlite3.Connection) -> list[dict[str, Any]]:
+    ensure_schema(conn)
+    rows = conn.execute(
+        f"""
+        SELECT ordinal, row_json, captured_at, account, account_type, ticker, name,
+               parse_status, user_confirmed, updated_at
+        FROM {SNAPSHOT_TABLE}
+        ORDER BY ordinal ASC
+        """
+    ).fetchall()
+    loaded: list[dict[str, Any]] = []
+    for row in rows:
+        payload = _json_load(row["row_json"])
+        item = payload if isinstance(payload, dict) else {}
+        item.setdefault("captured_at", row["captured_at"])
+        item.setdefault("account", row["account"])
+        item.setdefault("account_type", row["account_type"])
+        item.setdefault("ticker", row["ticker"])
+        item.setdefault("name", row["name"])
+        item.setdefault("parse_status", row["parse_status"])
+        item.setdefault("user_confirmed", row["user_confirmed"])
+        item["_ordinal"] = int(row["ordinal"])
+        item["_updated_at"] = row["updated_at"]
+        loaded.append(item)
+    return loaded
+
+
+def export_payload(db_path: Path | str | None = None) -> dict[str, Any]:
+    settings_rows = load_settings_rows(db_path)
+    settings = {row["key"]: row["value"] for row in settings_rows}
+    account_snapshot = load_account_snapshot_rows(db_path)
+    return {
+        "meta": {
+            "generated_at": now_kst_iso(),
+            "source_db": str(normalize_db_path(db_path)),
+        },
+        "data": {
+            "settings": settings,
+            "account_snapshot": account_snapshot,
+        },
+    }
+
+
+def write_export_json(db_path: Path | str | None, output_path: Path | str) -> Path:
+    payload = export_payload(db_path)
+    output = Path(output_path)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    return output
+
+
+def load_meta(db_path: Path | str | None = None) -> dict[str, Any]:
+    with open_connection(db_path) as conn:
+        ensure_schema(conn)
+        rows = conn.execute("SELECT key, value_json FROM workspace_meta ORDER BY key ASC").fetchall()
+    return {row["key"]: _json_load(row["value_json"]) for row in rows}
+
+
+def record_change_log(
+    conn: sqlite3.Connection,
+    *,
+    domain: str,
+    action: str,
+    before_json: Any,
+    after_json: Any,
+    target_ref: str = "",
+    actor: str = "ui",
+    note: str = "",
+) -> None:
+    ensure_schema(conn)
+    conn.execute(
+        f"""
+        INSERT INTO {CHANGE_LOG_TABLE} (
+            domain, action, target_ref, actor, note, before_json, after_json, created_at
+        )
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        """,
+        (
+            domain,
+            action,
+            target_ref,
+            actor,
+            note,
+            _json_dump(before_json),
+            _json_dump(after_json),
+            now_kst_iso(),
+        ),
+    )
+
+
+def set_approval(
+    conn: sqlite3.Connection,
+    domain: str,
+    status: str,
+    *,
+    target_ref: str = "*",
+    approved_by: str = "",
+    note: str = "",
+) -> None:
+    ensure_schema(conn)
+    conn.execute(
+        f"""
+        INSERT INTO {APPROVAL_TABLE} (domain, target_ref, status, approved_by, approved_at, note, updated_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(domain, target_ref) DO UPDATE SET
+            status=excluded.status,
+            approved_by=excluded.approved_by,
+            approved_at=excluded.approved_at,
+            note=excluded.note,
+            updated_at=excluded.updated_at
+        """,
+        (
+            domain,
+            target_ref or "*",
+            status,
+            approved_by,
+            now_kst_iso() if status == "APPROVED" else "",
+            note,
+            now_kst_iso(),
+        ),
+    )
+
+
+def load_approval_rows(db_path: Path | str | None = None) -> list[dict[str, Any]]:
+    with open_connection(db_path) as conn:
+        ensure_schema(conn)
+        rows = conn.execute(
+            f"SELECT domain, target_ref, status, approved_by, approved_at, note, updated_at FROM {APPROVAL_TABLE} ORDER BY domain ASC, target_ref ASC"
+        ).fetchall()
+    return [dict(row) for row in rows]
+
+
+def load_approval_entry(db_path: Path | str | None, domain: str, target_ref: str = "*") -> dict[str, Any] | None:
+    with open_connection(db_path) as conn:
+        ensure_schema(conn)
+        row = conn.execute(
+            f"""
+            SELECT domain, target_ref, status, approved_by, approved_at, note, updated_at
+            FROM {APPROVAL_TABLE}
+            WHERE domain = ? AND target_ref = ?
+            LIMIT 1
+            """,
+            (domain, target_ref or "*"),
+        ).fetchone()
+    return dict(row) if row is not None else None
+
+
+def load_change_log_rows(db_path: Path | str | None = None, limit: int = 20) -> list[dict[str, Any]]:
+    with open_connection(db_path) as conn:
+        ensure_schema(conn)
+        rows = conn.execute(
+            f"""
+            SELECT id, domain, action, target_ref, actor, note, before_json, after_json, created_at
+            FROM {CHANGE_LOG_TABLE}
+            ORDER BY id DESC
+            LIMIT ?
+            """,
+            (int(limit),),
+        ).fetchall()
+    items = []
+    for row in rows:
+        items.append(
+            {
+                "id": int(row["id"]),
+                "domain": row["domain"],
+                "action": row["action"],
+                "target_ref": row["target_ref"],
+                "actor": row["actor"],
+                "note": row["note"],
+                "before_json": _json_load(row["before_json"]),
+                "after_json": _json_load(row["after_json"]),
+                "created_at": row["created_at"],
+            }
+        )
+    return items
+
+
+def load_last_change_row(conn: sqlite3.Connection, domain: str) -> dict[str, Any] | None:
+    ensure_schema(conn)
+    row = conn.execute(
+        f"""
+        SELECT id, domain, action, target_ref, actor, note, before_json, after_json, created_at
+        FROM {CHANGE_LOG_TABLE}
+        WHERE domain = ?
+        ORDER BY id DESC
+        LIMIT 1
+        """,
+        (domain,),
+    ).fetchone()
+    if row is None:
+        return None
+    return {
+        "id": int(row["id"]),
+        "domain": row["domain"],
+        "action": row["action"],
+        "target_ref": row["target_ref"],
+        "actor": row["actor"],
+        "note": row["note"],
+        "before_json": _json_load(row["before_json"]),
+        "after_json": _json_load(row["after_json"]),
+        "created_at": row["created_at"],
+    }
+
+
+def set_lock(conn: sqlite3.Connection, domain: str, target_ref: str, *, locked_by: str, reason: str) -> None:
+    ensure_schema(conn)
+    conn.execute(
+        f"""
+        INSERT INTO {LOCK_TABLE} (domain, target_ref, locked_by, reason, locked_at)
+        VALUES (?, ?, ?, ?, ?)
+        ON CONFLICT(domain, target_ref) DO UPDATE SET
+            locked_by=excluded.locked_by,
+            reason=excluded.reason,
+            locked_at=excluded.locked_at
+        """,
+        (domain, target_ref, locked_by, reason, now_kst_iso()),
+    )
+
+
+def clear_lock(conn: sqlite3.Connection, domain: str, target_ref: str) -> None:
+    ensure_schema(conn)
+    conn.execute(
+        f"DELETE FROM {LOCK_TABLE} WHERE domain = ? AND target_ref = ?",
+        (domain, target_ref),
+    )
+
+
+def load_locks(db_path: Path | str | None = None) -> list[dict[str, Any]]:
+    with open_connection(db_path) as conn:
+        ensure_schema(conn)
+        rows = conn.execute(
+            f"SELECT domain, target_ref, locked_by, reason, locked_at FROM {LOCK_TABLE} ORDER BY domain ASC, target_ref ASC"
+        ).fetchall()
+    return [dict(row) for row in rows]
+
+
+def load_lock_entry(db_path: Path | str | None, domain: str, target_ref: str = "*") -> dict[str, Any] | None:
+    with open_connection(db_path) as conn:
+        ensure_schema(conn)
+        row = conn.execute(
+            f"""
+            SELECT domain, target_ref, locked_by, reason, locked_at
+            FROM {LOCK_TABLE}
+            WHERE domain = ? AND target_ref = ?
+            LIMIT 1
+            """,
+            (domain, target_ref or "*"),
+        ).fetchone()
+    return dict(row) if row is not None else None
+
+
+def is_locked(db_path: Path | str | None, domain: str, target_ref: str = "*") -> bool:
+    with open_connection(db_path) as conn:
+        ensure_schema(conn)
+        row = conn.execute(
+            f"SELECT 1 FROM {LOCK_TABLE} WHERE domain = ? AND target_ref IN (?, '*') LIMIT 1",
+            (domain, target_ref),
+        ).fetchone()
+    return row is not None
+
+
+def lock_conflicts_for_rows(
+    db_path: Path | str | None,
+    domain: str,
+    rows: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    with open_connection(db_path) as conn:
+        ensure_schema(conn)
+        locks = conn.execute(
+            f"SELECT domain, target_ref, locked_by, reason, locked_at FROM {LOCK_TABLE} WHERE domain = ? ORDER BY target_ref ASC",
+            (domain,),
+        ).fetchall()
+    if not locks:
+        return []
+    row_refs: list[str] = []
+    for idx, row in enumerate(rows, start=1):
+        if domain == SETTINGS_TABLE:
+            ref = str(row.get("_row_ref") or "").strip() or str(row.get("key") or "").strip()
+        elif domain == SNAPSHOT_TABLE:
+            ref = str(row.get("_row_ref") or "").strip()
+            if not ref:
+                ordinal = str(row.get("_ordinal") or row.get("ordinal") or idx).strip()
+                ref = f"row:{ordinal}"
+        else:
+            ref = str(row.get("target_ref") or "").strip()
+        if ref:
+            row_refs.append(ref)
+        if domain == SETTINGS_TABLE:
+            key = str(row.get("key") or "").strip()
+            if key:
+                row_refs.append(key)
+        if domain == SNAPSHOT_TABLE:
+            ticker = str(row.get("ticker") or "").strip()
+            if ticker:
+                row_refs.append(ticker)
+    conflicts: list[dict[str, Any]] = []
+    for lock in locks:
+        target_ref = str(lock["target_ref"] or "").strip()
+        if target_ref == "*" or target_ref in row_refs:
+            conflicts.append(dict(lock))
+    return conflicts
+
+
+def undo_last_change(conn: sqlite3.Connection, domain: str, *, actor: str = "ui") -> dict[str, Any]:
+    ensure_schema(conn)
+    last = load_last_change_row(conn, domain)
+    if not last:
+        raise ValueError(f"no change log for domain={domain}")
+    before_json = last.get("before_json")
+    if domain == SETTINGS_TABLE:
+        rows = before_json if isinstance(before_json, list) else []
+        replace_settings(conn, rows)
+    elif domain == SNAPSHOT_TABLE:
+        rows = before_json if isinstance(before_json, list) else []
+        replace_account_snapshot(conn, rows)
+    else:
+        raise ValueError(f"unsupported domain={domain}")
+    record_change_log(
+        conn,
+        domain=domain,
+        action="undo",
+        before_json=last.get("after_json"),
+        after_json=before_json,
+        target_ref=last.get("target_ref", "*"),
+        actor=actor,
+        note=f"undo change #{last['id']}",
+    )
+    conn.commit()
+    return load_last_change_row(conn, domain) or {}
+
+
+def load_approval_for_domain(db_path: Path | str | None, domain: str) -> dict[str, Any]:
+    with open_connection(db_path) as conn:
+        ensure_schema(conn)
+        row = conn.execute(
+            f"""
+            SELECT domain, target_ref, status, approved_by, approved_at, note, updated_at
+            FROM {APPROVAL_TABLE}
+            WHERE domain = ? AND target_ref = '*'
+            """,
+            (domain,),
+        ).fetchone()
+    return (
+        dict(row)
+        if row
+        else {"domain": domain, "target_ref": "*", "status": "MISSING", "approved_by": "", "approved_at": "", "note": "", "updated_at": ""}
+    )
+
+
+def summarize_workspace(db_path: Path | str | None = None) -> dict[str, Any]:
+    with open_connection(db_path) as conn:
+        ensure_schema(conn)
+        settings_count = conn.execute(f"SELECT COUNT(*) FROM {SETTINGS_TABLE}").fetchone()[0]
+        snapshot_count = conn.execute(f"SELECT COUNT(*) FROM {SNAPSHOT_TABLE}").fetchone()[0]
+        latest_update = conn.execute(
+            f"""
+            SELECT MAX(updated_at)
+            FROM (
+                SELECT updated_at FROM {SETTINGS_TABLE}
+                UNION ALL
+                SELECT updated_at FROM {SNAPSHOT_TABLE}
+            )
+            """
+            ).fetchone()[0]
+        table_rows = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name IN (?, ?, ?, ?, ?)",
+            (SETTINGS_TABLE, SNAPSHOT_TABLE, CHANGE_LOG_TABLE, APPROVAL_TABLE, LOCK_TABLE),
+        ).fetchall()
+    tables = sorted(row[0] for row in table_rows)
+    workspace_db = str(normalize_db_path(db_path))
+    return {
+        "db_path": workspace_db,
+        "settings_rows": int(settings_count),
+        "account_snapshot_rows": int(snapshot_count),
+        "latest_update": latest_update or "",
+        "tables": tables,
+        "topology": {
+            "mode": "single_workspace_sqlite",
+            "workspace_db": workspace_db,
+            "collector_db": str(ROOT / "outputs" / "kis_data_collection" / "kis_data_collection.db"),
+            "settings_and_snapshot_share_db": True,
+            "collector_separate_db": True,
+        },
+        "meta": load_meta(db_path),
+    }
+
+
+def parse_account_snapshot_tsv(tsv_text: str) -> list[dict[str, Any]]:
+    lines = [line.rstrip("\r") for line in tsv_text.splitlines() if line.strip() != ""]
+    if not lines:
+        return []
+    rows: list[list[str]] = [line.split("\t") for line in lines]
+    first_row = rows[0]
+    if first_row == ACCOUNT_SNAPSHOT_CANONICAL_COLUMNS:
+        data_rows = rows[1:]
+    elif set(first_row) >= {"captured_at", "account", "ticker"}:
+        header = first_row
+        data_rows = rows[1:]
+        converted: list[dict[str, Any]] = []
+        for idx, row in enumerate(data_rows, start=1):
+            item: dict[str, Any] = {"ordinal": idx}
+            for col_index, column in enumerate(header):
+                value = row[col_index] if col_index < len(row) else ""
+                item[column] = parse_scalar(value)
+            converted.append(item)
+        return converted
+    else:
+        data_rows = rows
+    converted = []
+    for idx, row in enumerate(data_rows, start=1):
+        item: dict[str, Any] = {"ordinal": idx}
+        for col_index, column in enumerate(ACCOUNT_SNAPSHOT_CANONICAL_COLUMNS):
+            value = row[col_index] if col_index < len(row) else ""
+            item[column] = parse_scalar(value)
+        converted.append(item)
+    return converted
+
+
+def settings_rows_to_dict(rows: list[dict[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for row in rows:
+        key = str(row.get("key") or "").strip()
+        if key:
+            result[key] = row.get("value", "")
+    return result
+
+
+def _as_number(value: Any) -> float | None:
+    if value is None:
+        return None
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)):
+        return float(value)
+    text = str(value).strip()
+    if not text:
+        return None
+    try:
+        return float(text)
+    except Exception:
+        return None
+
+
+@lru_cache(maxsize=1)
+def _load_settings_spec() -> dict[str, Any]:
+    return yaml.safe_load(SETTINGS_SPEC_PATH.read_text(encoding="utf-8")) or {}
+
+
+@lru_cache(maxsize=1)
+def _load_account_snapshot_spec() -> dict[str, Any]:
+    return yaml.safe_load(ACCOUNT_SNAPSHOT_SPEC_PATH.read_text(encoding="utf-8")) or {}
+
+
+def validate_settings_rows(rows: list[dict[str, Any]]) -> list[str]:
+    errors: list[str] = []
+    spec = _load_settings_spec().get("required_keys") or {}
+    optional_spec = _load_settings_spec().get("optional_keys") or {}
+    seen: set[str] = set()
+    total_asset_found = False
+    for idx, row in enumerate(rows, start=1):
+        key = str(row.get("key") or "").strip()
+        if not key:
+            errors.append(f"settings row {idx}: missing key")
+            continue
+        if key in seen:
+            errors.append(f"settings row {idx}: duplicate key {key}")
+        seen.add(key)
+        value = row.get("value", "")
+        if key == "total_asset_krw":
+            total_asset_found = True
+            amount = _as_number(value)
+            if amount is None or amount <= 0:
+                errors.append("settings.total_asset_krw must be positive number")
+        if key in {"weekly_target_cash_pct", "fc_budget_pct_override"}:
+            pct = _as_number(value)
+            if pct is None or pct < 0:
+                errors.append(f"settings.{key} must be non-negative number")
+        if key in spec and spec[key].get("type") == "string":
+            if value is not None and not isinstance(value, str):
+                errors.append(f"settings.{key} must be string")
+        if key in optional_spec and optional_spec[key].get("format") == "YYYY-MM":
+            text = str(value).strip()
+            if text and not re.fullmatch(r"\d{4}-\d{2}(-.*)?", text):
+                errors.append(f"settings.{key} must use YYYY-MM")
+    if not total_asset_found:
+        errors.append("settings.total_asset_krw is required")
+    return errors
+
+
+def validate_account_snapshot_rows(rows: list[dict[str, Any]]) -> list[str]:
+    errors: list[str] = []
+    spec = _load_account_snapshot_spec().get("account_snapshot_contract") or {}
+    canonical = spec.get("canonical_fields") or {}
+    for idx, row in enumerate(rows, start=1):
+        captured_at = str(row.get("captured_at") or "").strip()
+        account = str(row.get("account") or "").strip()
+        ticker = str(row.get("ticker") or "").strip()
+        name = str(row.get("name") or "").strip()
+        account_type = str(row.get("account_type") or "").strip()
+        parse_status = str(row.get("parse_status") or "").strip()
+        holding_quantity = _as_number(row.get("holding_quantity"))
+        average_cost = _as_number(row.get("average_cost"))
+        stop_price = _as_number(row.get("stop_price"))
+        entry_stage = str(row.get("entry_stage") or "").strip()
+        position_type = str(row.get("position_type") or "").strip()
+        user_confirmed = str(row.get("user_confirmed") or "").strip().upper()
+        if not captured_at:
+            errors.append(f"account_snapshot row {idx}: captured_at required")
+        if not account:
+            errors.append(f"account_snapshot row {idx}: account required")
+        if not account_type:
+            errors.append(f"account_snapshot row {idx}: account_type required")
+        if account_type and canonical.get("account_type", {}).get("allowed") and account_type not in canonical["account_type"]["allowed"]:
+            errors.append(f"account_snapshot row {idx}: invalid account_type {account_type!r}")
+        if not ticker:
+            errors.append(f"account_snapshot row {idx}: ticker required")
+        if not name:
+            errors.append(f"account_snapshot row {idx}: name required")
+        if parse_status not in ALLOWED_PARSE_STATUS:
+            errors.append(f"account_snapshot row {idx}: invalid parse_status {parse_status!r}")
+        if holding_quantity is not None and holding_quantity < 0:
+            errors.append(f"account_snapshot row {idx}: holding_quantity must be >= 0")
+        if average_cost is not None and average_cost < 0:
+            errors.append(f"account_snapshot row {idx}: average_cost must be >= 0")
+        if user_confirmed and user_confirmed not in {"Y", "N"}:
+            errors.append(f"account_snapshot row {idx}: user_confirmed must be Y or N")
+        if parse_status == "CAPTURE_READ_OK" and user_confirmed != "Y":
+            errors.append(f"account_snapshot row {idx}: CAPTURE_READ_OK rows require user_confirmed=Y")
+        if entry_stage and canonical.get("entry_stage", {}).get("allowed") and entry_stage not in canonical["entry_stage"]["allowed"]:
+            errors.append(f"account_snapshot row {idx}: invalid entry_stage {entry_stage!r}")
+        if position_type and canonical.get("position_type", {}).get("allowed") and position_type not in canonical["position_type"]["allowed"]:
+            errors.append(f"account_snapshot row {idx}: invalid position_type {position_type!r}")
+    return errors
+
+
+def build_validation_suggestions(settings_rows: list[dict[str, Any]], snapshot_rows: list[dict[str, Any]]) -> list[str]:
+    suggestions: list[str] = []
+    settings_map = settings_rows_to_dict(settings_rows)
+    snapshot_count = len(snapshot_rows)
+    if "total_asset_krw" not in settings_map:
+        suggestions.append("settings: add total_asset_krw from current investable asset total")
+    if str(settings_map.get("weekly_target_cash_pct", "")).strip() == "":
+        suggestions.append("settings: weekly_target_cash_pct can stay blank unless weekly rebalance is active")
+    for row in snapshot_rows:
+        if str(row.get("parse_status") or "").strip() == "CAPTURE_READ_OK" and str(row.get("user_confirmed") or "").strip().upper() != "Y":
+            suggestions.append(
+                f"account_snapshot {row.get('ticker') or row.get('name') or 'row'}: set user_confirmed=Y for CAPTURE_READ_OK"
+            )
+        account_type = str(row.get("account_type") or "").strip()
+        if account_type and account_type not in {"일반계좌", "ISA", "연금저축"}:
+            suggestions.append(
+                f"account_snapshot {row.get('ticker') or row.get('name') or 'row'}: account_type should be one of 일반계좌/ISA/연금저축"
+            )
+        if str(row.get("entry_stage") or "").strip() and str(row.get("position_type") or "").strip() == "":
+            suggestions.append(
+                f"account_snapshot {row.get('ticker') or row.get('name') or 'row'}: consider setting position_type when entry_stage is present"
+            )
+    if not snapshot_rows:
+        suggestions.append("account_snapshot: import TSV from HTS capture before saving snapshot")
+    return suggestions[:20]
+
+
+def build_safe_autofix_actions(settings_rows: list[dict[str, Any]], snapshot_rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    actions: list[dict[str, Any]] = []
+    if any(str(row.get("parse_status") or "").strip() == "CAPTURE_READ_OK" and str(row.get("user_confirmed") or "").strip().upper() != "Y" for row in snapshot_rows):
+        actions.append(
+            {
+                "action_id": "confirm_captured_rows",
+                "domain": "account_snapshot",
+                "label": "Set user_confirmed=Y for CAPTURE_READ_OK rows",
+                "description": "Safe autofix using the contract default confirmation flag.",
+            }
+        )
+    if any(str(row.get("position_type") or "").strip() == "" and str(row.get("entry_stage") or "").strip() for row in snapshot_rows):
+        actions.append(
+            {
+                "action_id": "default_position_type_satellite",
+                "domain": "account_snapshot",
+                "label": "Default blank position_type to satellite",
+                "description": "Uses the contract default when position_type is missing.",
+            }
+        )
+    if not any(str(row.get("key") or "").strip() == "total_asset_krw" for row in settings_rows):
+        actions.append(
+            {
+                "action_id": "required_total_asset_missing",
+                "domain": "settings",
+                "label": "Settings total_asset_krw missing",
+                "description": "Manual input required. No safe autofix.",
+            }
+        )
+    return actions
+
+
+def apply_safe_autofix_action(
+    conn: sqlite3.Connection,
+    action_id: str,
+    *,
+    actor: str = "ui",
+) -> dict[str, Any]:
+    ensure_schema(conn)
+    snapshot_rows = load_account_snapshot_rows_from_conn(conn)
+    if action_id == "confirm_captured_rows":
+        updated = []
+        for row in snapshot_rows:
+            candidate = dict(row)
+            if str(candidate.get("parse_status") or "").strip() == "CAPTURE_READ_OK" and str(candidate.get("user_confirmed") or "").strip().upper() != "Y":
+                candidate["user_confirmed"] = "Y"
+            updated.append(candidate)
+        replace_account_snapshot(conn, updated)
+        return {"domain": SNAPSHOT_TABLE, "status": "AUTOFIXED", "action_id": action_id}
+    if action_id == "default_position_type_satellite":
+        updated = []
+        for row in snapshot_rows:
+            candidate = dict(row)
+            if str(candidate.get("entry_stage") or "").strip() and str(candidate.get("position_type") or "").strip() == "":
+                candidate["position_type"] = "satellite"
+            updated.append(candidate)
+        replace_account_snapshot(conn, updated)
+        return {"domain": SNAPSHOT_TABLE, "status": "AUTOFIXED", "action_id": action_id}
+    if action_id == "required_total_asset_missing":
+        return {"domain": SETTINGS_TABLE, "status": "MANUAL_REQUIRED", "action_id": action_id}
+    raise ValueError(f"unknown action_id={action_id}")
diff --git a/tests/unit/test_snapshot_admin_store_v1.py b/tests/unit/test_snapshot_admin_store_v1.py
new file mode 100644
index 00000000..52bc790a
--- /dev/null
+++ b/tests/unit/test_snapshot_admin_store_v1.py
@@ -0,0 +1,249 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from src.quant_engine.snapshot_admin_server_v1 import build_ui_state
+from src.quant_engine.snapshot_admin_store_v1 import (
+    ACCOUNT_SNAPSHOT_CANONICAL_COLUMNS,
+    export_payload,
+    import_seed_json,
+    load_approval_for_domain,
+    load_change_log_rows,
+    load_locks,
+    load_account_snapshot_rows,
+    load_settings_rows,
+    parse_account_snapshot_tsv,
+    open_connection,
+    lock_conflicts_for_rows,
+    validate_account_snapshot_rows,
+    validate_settings_rows,
+    build_validation_suggestions,
+    build_safe_autofix_actions,
+    apply_safe_autofix_action,
+    set_lock,
+    undo_last_change,
+    write_export_json,
+)
+
+
+def _seed_json(path: Path) -> None:
+    payload = {
+        "data": {
+            "settings": {
+                "total_asset_krw": 150000000,
+                "weekly_target_cash_pct": 14,
+                "orbit_start_yyyymm": "2026-01",
+            },
+            "account_snapshot": [
+                {
+                    "captured_at": "2026-06-21T09:00:00+09:00",
+                    "account": "real",
+                    "account_type": "일반계좌",
+                    "ticker": "005930",
+                    "name": "삼성전자",
+                    "holding_quantity": 10,
+                    "available_quantity": 10,
+                    "average_cost": 70000,
+                    "total_cost": 700000,
+                    "current_price": 71000,
+                    "market_value": 710000,
+                    "profit_loss": 10000,
+                    "return_pct": 1.43,
+                    "immediate_cash": 1000000,
+                    "settlement_cash_d2": 1000000,
+                    "available_cash": 1000000,
+                    "open_order_amount": 0,
+                    "monthly_contribution_limit": "",
+                    "monthly_contribution_used": "",
+                    "parse_status": "CAPTURE_READ_OK",
+                    "user_confirmed": "Y",
+                    "stop_price": 65000,
+                    "highest_price_since_entry": 72000,
+                    "entry_date": "2026-06-01",
+                    "entry_stage": "stage_1",
+                    "position_type": "core",
+                    "last_updated": "2026-06-21T09:05:00+09:00",
+                }
+            ],
+        }
+    }
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+
+
+def test_seed_import_and_export_round_trip(tmp_path):
+    db_path = tmp_path / "snapshot.db"
+    seed_path = tmp_path / "seed.json"
+    _seed_json(seed_path)
+
+    summary = import_seed_json(db_path, seed_path)
+    assert summary["settings_rows"] == 3
+    assert summary["account_snapshot_rows"] == 1
+
+    settings_rows = load_settings_rows(db_path)
+    assert settings_rows[0]["key"] == "total_asset_krw"
+    assert settings_rows[0]["value"] == 150000000
+
+    snapshot_rows = load_account_snapshot_rows(db_path)
+    assert snapshot_rows[0]["ticker"] == "005930"
+    assert snapshot_rows[0]["parse_status"] == "CAPTURE_READ_OK"
+
+    exported = export_payload(db_path)
+    assert exported["data"]["settings"]["weekly_target_cash_pct"] == 14
+    assert exported["data"]["account_snapshot"][0]["name"] == "삼성전자"
+
+    out = write_export_json(db_path, tmp_path / "export.json")
+    assert out.exists()
+
+
+def test_parse_account_snapshot_tsv_supports_headerless_and_header_rows():
+    headerless = "\n".join(
+        [
+            "\t".join(ACCOUNT_SNAPSHOT_CANONICAL_COLUMNS),
+            "\t".join(
+                [
+                    "2026-06-21T09:00:00+09:00",
+                    "real",
+                    "일반계좌",
+                    "005930",
+                    "삼성전자",
+                    "10",
+                    "10",
+                    "70000",
+                    "700000",
+                    "71000",
+                    "710000",
+                    "10000",
+                    "1.43",
+                    "1000000",
+                    "1000000",
+                    "1000000",
+                    "0",
+                    "",
+                    "",
+                    "CAPTURE_READ_OK",
+                    "Y",
+                    "65000",
+                    "72000",
+                    "2026-06-01",
+                    "stage_1",
+                    "core",
+                    "2026-06-21T09:05:00+09:00",
+                ]
+            ),
+        ]
+    )
+    rows = parse_account_snapshot_tsv(headerless)
+    assert rows[0]["ticker"] == "005930"
+    assert rows[0]["holding_quantity"] == 10
+
+    with_header = "captured_at\taccount\tticker\n2026-06-21T09:00:00+09:00\treal\t005930"
+    rows2 = parse_account_snapshot_tsv(with_header)
+    assert rows2[0]["account"] == "real"
+    assert rows2[0]["ticker"] == "005930"
+
+
+def test_build_ui_state_reports_schema(tmp_path):
+    db_path = tmp_path / "snapshot.db"
+    seed_path = tmp_path / "seed.json"
+    _seed_json(seed_path)
+    import_seed_json(db_path, seed_path)
+
+    state = build_ui_state(db_path)
+    assert state["summary"]["settings_rows"] == 3
+    assert state["account_snapshot_columns"][: len(ACCOUNT_SNAPSHOT_CANONICAL_COLUMNS)] == ACCOUNT_SNAPSHOT_CANONICAL_COLUMNS
+
+
+def test_change_log_approval_and_lock_workflow(tmp_path):
+    db_path = tmp_path / "snapshot.db"
+    seed_path = tmp_path / "seed.json"
+    _seed_json(seed_path)
+    import_seed_json(db_path, seed_path)
+
+    with open_connection(db_path) as conn:
+        set_lock(conn, "settings", "*", locked_by="tester", reason="review")
+        conn.commit()
+
+    locks = load_locks(db_path)
+    assert locks and locks[0]["domain"] == "settings"
+
+    approval = load_approval_for_domain(db_path, "settings")
+    assert approval["status"] == "PENDING"
+
+    changes = load_change_log_rows(db_path, limit=10)
+    assert changes
+
+
+def test_lock_conflicts_detect_row_targets(tmp_path):
+    db_path = tmp_path / "snapshot.db"
+    seed_path = tmp_path / "seed.json"
+    _seed_json(seed_path)
+    import_seed_json(db_path, seed_path)
+
+    with open_connection(db_path) as conn:
+        set_lock(conn, "settings", "total_asset_krw", locked_by="tester", reason="review")
+        set_lock(conn, "account_snapshot", "005930", locked_by="tester", reason="review")
+        conn.commit()
+
+    settings_conflicts = lock_conflicts_for_rows(
+        db_path,
+        "settings",
+        [{"key": "total_asset_krw", "value": 123, "note": ""}],
+    )
+    snapshot_conflicts = lock_conflicts_for_rows(
+        db_path,
+        "account_snapshot",
+        [{"ticker": "005930", "name": "삼성전자", "ordinal": 1}],
+    )
+
+    assert settings_conflicts and settings_conflicts[0]["target_ref"] == "total_asset_krw"
+    assert snapshot_conflicts and snapshot_conflicts[0]["target_ref"] == "005930"
+
+
+def test_undo_last_change_restores_previous_snapshot(tmp_path):
+    db_path = tmp_path / "snapshot.db"
+    seed_path = tmp_path / "seed.json"
+    _seed_json(seed_path)
+    import_seed_json(db_path, seed_path)
+
+    with open_connection(db_path) as conn:
+        from src.quant_engine.snapshot_admin_store_v1 import replace_settings
+
+        replace_settings(conn, [{"ordinal": 1, "key": "total_asset_krw", "value": 123, "note": "edited"}])
+
+    with open_connection(db_path) as conn:
+        undo_last_change(conn, "settings")
+
+    settings_rows = load_settings_rows(db_path)
+    assert settings_rows[0]["value"] == 150000000
+
+
+def test_validation_helpers_detect_invalid_rows():
+    assert "settings.total_asset_krw is required" in validate_settings_rows([{"key": "weekly_target_cash_pct", "value": 10}])
+    assert "account_snapshot row 1: ticker required" in validate_account_snapshot_rows(
+        [{"captured_at": "2026-06-21", "account": "real", "name": "삼성전자", "parse_status": "BAD"}]
+    )
+    suggestions = build_validation_suggestions(
+        [{"key": "weekly_target_cash_pct", "value": 10}],
+        [{"captured_at": "2026-06-21", "account": "real", "account_type": "일반계좌", "ticker": "005930", "name": "삼성전자", "parse_status": "CAPTURE_READ_OK", "user_confirmed": "N"}],
+    )
+    assert any("user_confirmed=Y" in item for item in suggestions)
+    actions = build_safe_autofix_actions(
+        [{"key": "total_asset_krw", "value": 150000000}],
+        [{"captured_at": "2026-06-21", "account": "real", "account_type": "일반계좌", "ticker": "005930", "name": "삼성전자", "parse_status": "CAPTURE_READ_OK", "user_confirmed": "N", "entry_stage": "stage_1", "position_type": ""}],
+    )
+    assert any(item["action_id"] == "confirm_captured_rows" for item in actions)
+
+
+def test_safe_autofix_updates_snapshot_defaults(tmp_path):
+    db_path = tmp_path / "snapshot.db"
+    seed_path = tmp_path / "seed.json"
+    _seed_json(seed_path)
+    import_seed_json(db_path, seed_path)
+
+    with open_connection(db_path) as conn:
+        result = apply_safe_autofix_action(conn, "confirm_captured_rows")
+        assert result["status"] == "AUTOFIXED"
+
+    snapshot_rows = load_account_snapshot_rows(db_path)
+    assert all(row.get("user_confirmed") == "Y" or str(row.get("parse_status")) != "CAPTURE_READ_OK" for row in snapshot_rows)
diff --git a/tests/unit/test_snapshot_admin_web_v1.py b/tests/unit/test_snapshot_admin_web_v1.py
new file mode 100644
index 00000000..8f7b0340
--- /dev/null
+++ b/tests/unit/test_snapshot_admin_web_v1.py
@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+import tools.validate_snapshot_admin_web_v1 as validator
+from src.quant_engine.snapshot_admin_server_v1 import (
+    build_ui_state,
+    fetch_table_rows,
+    list_browsable_tables,
+    render_collection_html,
+    render_index_html,
+    render_tables_html,
+)
+from src.quant_engine.snapshot_admin_store_v1 import import_seed_json
+
+
+def test_render_index_html_contains_spreadsheet_surface():
+    html = render_index_html()
+    assert "Snapshot Admin" in html
+    assert "contenteditable" in html
+    assert "/api/settings/save" in html
+    assert "/api/account_snapshot/save" in html
+    assert "Lock target" in html
+    assert "Lock row" in html
+    assert "Approve pending" in html
+    assert "Refresh diff" in html
+    assert "Export approval packet" in html
+    assert "Selection Inspector" in html
+    assert "Recent row history" in html
+    assert "Save view" in html
+    assert "Apply TSV to selection" in html
+    assert "Ctrl+S" in html
+    assert "KIS Collection" in html
+    assert "Recent collector snapshots" in html
+    assert "Collection detail" in html
+    assert "Filter runs / snapshots / errors" in html
+    assert "Filter change log" in html
+    assert "Timeline" in html
+    assert "/collection" in html
+    assert "Open collection dashboard" in html
+
+
+def test_render_collection_html_contains_dashboard_surface():
+    html = render_collection_html()
+    assert "KIS Collection Dashboard" in html
+    assert "/api/state" in html
+    assert "Download raw JSON" in html
+    assert "Download CSV" in html
+    assert "Filter runs / snapshots / errors" in html
+    assert "Ticker quick search" in html
+    assert "Date quick search" in html
+
+
+def test_build_ui_state_exposes_expected_columns(tmp_path):
+    db_path = tmp_path / "snapshot_admin.db"
+    seed_path = ROOT / "GatherTradingData.json"
+    import_seed_json(db_path, seed_path)
+
+    state = build_ui_state(db_path)
+    assert state["summary"]["settings_rows"] > 0
+    assert state["summary"]["account_snapshot_rows"] > 0
+    assert state["summary"]["topology"]["mode"] == "single_workspace_sqlite"
+    assert state["summary"]["topology"]["settings_and_snapshot_share_db"] is True
+    assert state["summary"]["topology"]["collector_separate_db"] is True
+    assert state["account_snapshot_columns"][0] == "captured_at"
+    assert "settings" in state["validation"]
+    assert state["version"]["app"]
+    assert "fingerprint" in state["version"]["source"]
+    assert "collection" in state
+    assert "counts" in state["collection"]
+    assert "latest_report" in state["collection"]
+    assert state["summary"]["topology"]["mode"] == "single_workspace_sqlite"
+
+
+def test_snapshot_admin_workflow_and_script_exist():
+    workflow = ROOT / ".gitea" / "workflows" / "snapshot_admin.yml"
+    package = json.loads((ROOT / "package.json").read_text(encoding="utf-8"))
+    assert workflow.exists()
+    assert "--reload" in package["scripts"]["ops:snapshot-web"]
+    assert "ops:snapshot-validate" in package["scripts"]
+    assert "ops:snapshot-web-validate" in package["scripts"]
+
+
+def test_render_tables_html_contains_tabler_grid_surface():
+    html = render_tables_html()
+    assert "tabler" in html.lower()
+    assert "tableSelect" in html
+    assert "/api/tables" in html
+    assert "/api/table_rows" in html
+    assert "gridTable" in html
+
+
+def test_list_browsable_tables_covers_all_three_databases(tmp_path):
+    db_path = tmp_path / "snapshot_admin.db"
+    import_seed_json(db_path, ROOT / "GatherTradingData.json")
+
+    tables = list_browsable_tables(db_path)
+    names = {row["table"] for row in tables}
+    assert {"settings", "account_snapshot", "workspace_change_log"} <= names
+    assert {"collection_runs", "collection_snapshots", "collection_source_errors"} <= names
+    assert {"sell_strategy_results", "satellite_recommendations"} <= names
+
+    settings_row = next(row for row in tables if row["table"] == "settings")
+    assert settings_row["exists"] is True
+    assert settings_row["row_count"] > 0
+
+
+def test_fetch_table_rows_paginates_and_rejects_unknown_table(tmp_path):
+    db_path = tmp_path / "snapshot_admin.db"
+    import_seed_json(db_path, ROOT / "GatherTradingData.json")
+
+    page1 = fetch_table_rows("settings", db_path, limit=2, offset=0)
+    assert page1["columns"]
+    assert len(page1["rows"]) == 2
+    assert page1["total"] > 2
+
+    page2 = fetch_table_rows("settings", db_path, limit=2, offset=2)
+    assert page1["rows"] != page2["rows"]
+
+    import pytest
+
+    with pytest.raises(ValueError):
+        fetch_table_rows("settings; DROP TABLE settings;--", db_path)
+
+
+def test_snapshot_admin_web_validation_script_passes():
+    out = ROOT / "Temp" / "snapshot_admin_web_validation_v1.json"
+    if out.exists():
+        out.unlink()
+
+    rc = validator.main()
+    payload = json.loads(out.read_text(encoding="utf-8"))
+
+    assert rc == 0
+    assert payload["gate"] == "PASS"
+    assert payload["formula_id"] == "SNAPSHOT_ADMIN_WEB_VALIDATION_V1"
+    assert payload["settings_rows"] > 0
+    assert payload["account_snapshot_rows"] > 0
diff --git a/tools/run_snapshot_admin_server_v1.py b/tools/run_snapshot_admin_server_v1.py
new file mode 100644
index 00000000..7683ea40
--- /dev/null
+++ b/tools/run_snapshot_admin_server_v1.py
@@ -0,0 +1,164 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SERVER_MODULE = "src.quant_engine.snapshot_admin_server_v1"
+WATCH_DIRS = (
+    ROOT / "src",
+    ROOT / "tools",
+    ROOT / "spec",
+    ROOT / "governance",
+    ROOT / "docs",
+    ROOT / ".gitea",
+)
+WATCH_FILES = (
+    ROOT / "package.json",
+    ROOT / "AGENTS.md",
+    ROOT / "GatherTradingData.json",
+)
+WATCH_EXTENSIONS = {".py", ".yaml", ".yml", ".json", ".md", ".gs"}
+IGNORED_DIR_NAMES = {"Temp", "outputs", ".git", "__pycache__", ".pytest_cache"}
+
+
+def _server_cmd(args: argparse.Namespace) -> list[str]:
+    cmd = [
+        sys.executable,
+        "-m",
+        SERVER_MODULE,
+        "--host",
+        args.host,
+        "--port",
+        str(args.port),
+        "--db",
+        args.db,
+        "--seed",
+        args.seed,
+    ]
+    if args.no_bootstrap:
+        cmd.append("--no-bootstrap")
+    return cmd
+
+
+def _iter_watch_files() -> list[Path]:
+    seen: set[Path] = set()
+    files: list[Path] = []
+    for path in WATCH_FILES:
+        if path.exists() and path.is_file():
+            resolved = path.resolve()
+            if resolved not in seen:
+                seen.add(resolved)
+                files.append(resolved)
+    for root in WATCH_DIRS:
+        if not root.exists():
+            continue
+        for path in root.rglob("*"):
+            if not path.is_file():
+                continue
+            if any(part in IGNORED_DIR_NAMES for part in path.parts):
+                continue
+            if path.suffix.lower() not in WATCH_EXTENSIONS:
+                continue
+            resolved = path.resolve()
+            if resolved not in seen:
+                seen.add(resolved)
+                files.append(resolved)
+    return files
+
+
+def _snapshot_mtimes() -> dict[Path, float]:
+    mtimes: dict[Path, float] = {}
+    for path in _iter_watch_files():
+        try:
+            mtimes[path] = path.stat().st_mtime
+        except FileNotFoundError:
+            continue
+    return mtimes
+
+
+def _changed_files(previous: dict[Path, float]) -> list[Path]:
+    current = _snapshot_mtimes()
+    changed: list[Path] = []
+    for path, mtime in current.items():
+        if previous.get(path) != mtime:
+            changed.append(path)
+    for path in previous:
+        if path not in current:
+            changed.append(path)
+    return changed
+
+
+def _run_once(args: argparse.Namespace) -> int:
+    proc = subprocess.Popen(_server_cmd(args), cwd=str(ROOT), env=os.environ.copy())
+    try:
+        return proc.wait()
+    except KeyboardInterrupt:
+        proc.terminate()
+        try:
+            return proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+            return proc.wait()
+
+
+def _run_reload(args: argparse.Namespace, interval: float) -> int:
+    last_mtimes = _snapshot_mtimes()
+    child: subprocess.Popen[str] | None = None
+    try:
+        while True:
+            if child is None or child.poll() is not None:
+                if child is not None:
+                    code = child.returncode or 0
+                    print(f"[snapshot-admin] server exited with code {code}; restarting...")
+                child = subprocess.Popen(_server_cmd(args), cwd=str(ROOT), env=os.environ.copy())
+                print("[snapshot-admin] hot reload watcher active")
+                print("[snapshot-admin] watching:", ", ".join(str(path) for path in WATCH_DIRS))
+            time.sleep(interval)
+            changed = _changed_files(last_mtimes)
+            if changed:
+                print("[snapshot-admin] changes detected:")
+                for path in changed[:20]:
+                    print(f"  - {path}")
+                last_mtimes = _snapshot_mtimes()
+                if child is not None and child.poll() is None:
+                    child.terminate()
+                    try:
+                        child.wait(timeout=10)
+                    except subprocess.TimeoutExpired:
+                        child.kill()
+                        child.wait()
+                child = None
+    except KeyboardInterrupt:
+        if child is not None and child.poll() is None:
+            child.terminate()
+            try:
+                child.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                child.kill()
+                child.wait()
+        return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Run the snapshot admin web server.")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8787)
+    parser.add_argument("--db", default=str(ROOT / "outputs" / "snapshot_admin" / "snapshot_admin.db"))
+    parser.add_argument("--seed", default=str(ROOT / "GatherTradingData.json"))
+    parser.add_argument("--no-bootstrap", action="store_true")
+    parser.add_argument("--reload", action="store_true", help="Restart the server when watched files change.")
+    parser.add_argument("--reload-interval", type=float, default=1.0, help="Seconds between file-system polls.")
+    args = parser.parse_args()
+    if args.reload:
+        return _run_reload(args, max(0.25, args.reload_interval))
+    return _run_once(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/tools/validate_snapshot_admin_web_v1.py b/tools/validate_snapshot_admin_web_v1.py
new file mode 100644
index 00000000..5220f4d9
--- /dev/null
+++ b/tools/validate_snapshot_admin_web_v1.py
@@ -0,0 +1,222 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import socket
+import subprocess
+import sys
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+OUT = ROOT / "Temp" / "snapshot_admin_web_validation_v1.json"
+
+
+def _read_json(url: str) -> dict[str, Any]:
+    with urllib.request.urlopen(url, timeout=5) as response:
+        payload = response.read().decode("utf-8")
+    data = json.loads(payload)
+    return data if isinstance(data, dict) else {}
+
+
+def _read_text(url: str) -> str:
+    with urllib.request.urlopen(url, timeout=5) as response:
+        return response.read().decode("utf-8")
+
+
+def _post_json(url: str, payload: dict[str, Any]) -> dict[str, Any]:
+    data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    request = urllib.request.Request(
+        url,
+        data=data,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    with urllib.request.urlopen(request, timeout=5) as response:
+        return json.loads(response.read().decode("utf-8"))
+
+
+def _wait_for_server(url: str, timeout_s: float = 15.0) -> None:
+    deadline = time.time() + timeout_s
+    last_error: Exception | None = None
+    while time.time() < deadline:
+        try:
+            _read_text(url)
+            return
+        except Exception as exc:  # noqa: BLE001
+            last_error = exc
+            time.sleep(0.25)
+    raise RuntimeError(f"server did not start: {last_error}")
+
+
+def _pick_free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.bind(("127.0.0.1", 0))
+        return int(sock.getsockname()[1])
+
+
+def main() -> int:
+    port = _pick_free_port()
+    db_path = ROOT / "Temp" / "snapshot_admin_web_validation.db"
+    seed_path = ROOT / "GatherTradingData.json"
+    server_cmd = [
+        sys.executable,
+        str(ROOT / "tools" / "run_snapshot_admin_server_v1.py"),
+        "--host",
+        "127.0.0.1",
+        "--port",
+        str(port),
+        "--db",
+        str(db_path),
+        "--seed",
+        str(seed_path),
+    ]
+
+    proc = subprocess.Popen(
+        server_cmd,
+        cwd=ROOT,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        encoding="utf-8",
+    )
+    base_url = f"http://127.0.0.1:{port}"
+    errors: list[str] = []
+    html = ""
+    state: dict[str, Any] = {}
+
+    try:
+        _wait_for_server(base_url)
+        html = _read_text(f"{base_url}/")
+        state = _read_json(f"{base_url}/api/state")
+        export_payload = _read_json(f"{base_url}/api/export")
+        approval_packet = {
+            "formula_id": "SNAPSHOT_ADMIN_APPROVAL_PACKET_V1",
+            "generated_at": state.get("generated_at") or "",
+            "summary": {
+                "settings_changed": 0,
+                "account_snapshot_changed": 0,
+                "pending_target_count": 0,
+            },
+            "pending_targets": [],
+            "diff_preview": {"settings": {"added": [], "removed": [], "changed": []}, "account_snapshot": {"added": [], "removed": [], "changed": []}},
+            "approvals": state.get("approval_rows", []),
+            "locks": state.get("locks", []),
+            "workspace": state.get("summary", {}),
+        }
+        packet_response = _post_json(f"{base_url}/api/approval_packet", {"packet": approval_packet})
+        if "Snapshot Admin" not in html:
+            errors.append("html_title_missing")
+        if "contenteditable" not in html:
+            errors.append("sheet_editor_missing")
+        if "settings" not in html or "Account Snapshot" not in html:
+            errors.append("section_missing")
+        if "/api/settings/save" not in html or "/api/account_snapshot/save" not in html:
+            errors.append("api_binding_missing")
+        if "Approve pending" not in html or "Refresh diff" not in html:
+            errors.append("diff_or_approval_ui_missing")
+        if "Export approval packet" not in html:
+            errors.append("approval_packet_ui_missing")
+        if "Selection Inspector" not in html or "Apply TSV to selection" not in html or "Save view" not in html:
+            errors.append("sheet_facade_ui_missing")
+        if "Recent row history" not in html or "Ctrl+S" not in html:
+            errors.append("sheet_shortcuts_ui_missing")
+        if "KIS Collection" not in html or "collector:" not in html:
+            errors.append("collection_dashboard_ui_missing")
+        if "Recent collector snapshots" not in html or "Collection detail" not in html or "Filter runs / snapshots / errors" not in html:
+            errors.append("collection_detail_ui_missing")
+        if "Filter change log" not in html:
+            errors.append("change_log_filter_ui_missing")
+        if "Timeline" not in html or "/collection" not in html or "Open collection dashboard" not in html:
+            errors.append("collection_page_link_missing")
+        if "Open collection dashboard" not in html:
+            errors.append("collection_dashboard_link_missing")
+        collection_html = _read_text(f"{base_url}/collection")
+        if "KIS Collection Dashboard" not in collection_html or "Download CSV" not in collection_html or "Ticker quick search" not in collection_html or "Date quick search" not in collection_html:
+            errors.append("collection_dashboard_page_missing")
+        if int(state.get("summary", {}).get("settings_rows") or 0) <= 0:
+            errors.append("settings_rows_missing")
+        if int(state.get("summary", {}).get("account_snapshot_rows") or 0) <= 0:
+            errors.append("account_snapshot_rows_missing")
+        topology = state.get("summary", {}).get("topology", {})
+        if not isinstance(topology, dict):
+            errors.append("topology_missing")
+        else:
+            if topology.get("mode") != "single_workspace_sqlite":
+                errors.append("topology_mode_invalid")
+            if not topology.get("settings_and_snapshot_share_db"):
+                errors.append("topology_workspace_split_invalid")
+            if not topology.get("collector_separate_db"):
+                errors.append("topology_collector_split_invalid")
+        if not isinstance(state.get("version"), dict) or not state.get("version", {}).get("app"):
+            errors.append("version_metadata_missing")
+        if not isinstance(state.get("collection"), dict):
+            errors.append("collection_state_missing")
+        collection = state.get("collection", {})
+        if not isinstance(collection.get("counts"), dict):
+            errors.append("collection_counts_missing")
+        if "latest_report" not in collection:
+            errors.append("collection_latest_report_missing")
+        if "data" not in export_payload:
+            errors.append("export_missing_data")
+        if packet_response.get("gate") != "PASS":
+            errors.append("approval_packet_export_failed")
+        packet_path = Path(packet_response.get("packet_path") or "")
+        md_path = Path(packet_response.get("md_path") or "")
+        if not packet_path.exists():
+            errors.append("approval_packet_json_missing")
+        if not md_path.exists():
+            errors.append("approval_packet_md_missing")
+
+        payload = {
+            "formula_id": "SNAPSHOT_ADMIN_WEB_VALIDATION_V1",
+            "gate": "PASS" if not errors else "FAIL",
+            "port": port,
+            "db_path": str(db_path),
+            "base_url": base_url,
+            "errors": errors,
+            "summary": state.get("summary", {}),
+            "version": state.get("version", {}),
+            "settings_rows": int(state.get("summary", {}).get("settings_rows") or 0),
+            "account_snapshot_rows": int(state.get("summary", {}).get("account_snapshot_rows") or 0),
+            "approval_packet_path": str(packet_path),
+        }
+        OUT.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+        return 0 if payload["gate"] == "PASS" else 1
+    except urllib.error.URLError as exc:
+        errors.append(str(exc))
+        payload = {
+            "formula_id": "SNAPSHOT_ADMIN_WEB_VALIDATION_V1",
+            "gate": "FAIL",
+            "port": port,
+            "db_path": str(db_path),
+            "base_url": base_url,
+            "errors": errors,
+            "summary": state.get("summary", {}),
+            "version": state.get("version", {}),
+        }
+        OUT.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+        print(json.dumps(payload, ensure_ascii=False, indent=2))
+        return 1
+    finally:
+        if proc.poll() is None:
+            proc.terminate()
+            try:
+                proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                proc.wait(timeout=5)
+        if proc.stdout is not None:
+            proc.stdout.close()
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/tools/validate_snapshot_admin_workflow_v1.py b/tools/validate_snapshot_admin_workflow_v1.py
new file mode 100644
index 00000000..cc7f989c
--- /dev/null
+++ b/tools/validate_snapshot_admin_workflow_v1.py
@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.quant_engine.snapshot_admin_store_v1 import (
+    DEFAULT_DB,
+    DEFAULT_SEED_JSON,
+    import_seed_json,
+    load_account_snapshot_rows,
+    load_settings_rows,
+    parse_account_snapshot_tsv,
+    validate_account_snapshot_rows,
+    validate_settings_rows,
+    write_export_json,
+)
+
+OUT = ROOT / "Temp" / "snapshot_admin_workflow_v1.json"
+
+
+def main() -> int:
+    db_path = DEFAULT_DB
+    seed_path = DEFAULT_SEED_JSON
+    summary = import_seed_json(db_path, seed_path)
+    settings_rows = load_settings_rows(db_path)
+    snapshot_rows = load_account_snapshot_rows(db_path)
+    settings_errors = validate_settings_rows(settings_rows)
+    snapshot_errors = validate_account_snapshot_rows(snapshot_rows)
+    exported = write_export_json(db_path, ROOT / "Temp" / "snapshot_admin_export_v1.json")
+    tsv_rows = parse_account_snapshot_tsv(
+        "\n".join(
+            [
+                "captured_at\taccount\taccount_type\tticker\tname\tholding_quantity\tavailable_quantity\taverage_cost\ttotal_cost\tcurrent_price\tmarket_value\tprofit_loss\treturn_pct\timmediate_cash\tsettlement_cash_d2\tavailable_cash\topen_order_amount\tmonthly_contribution_limit\tmonthly_contribution_used\tparse_status\tuser_confirmed\tstop_price\thighest_price_since_entry\tentry_date\tentry_stage\tposition_type\tlast_updated",
+                "2026-06-21T09:00:00+09:00\treal\t일반계좌\t005930\t삼성전자\t10\t10\t70000\t700000\t71000\t710000\t10000\t1.43\t1000000\t1000000\t1000000\t0\t\t\tCAPTURE_READ_OK\tY\t65000\t72000\t2026-06-01\tstage_1\tcore\t2026-06-21T09:05:00+09:00",
+            ]
+        )
+    )
+    payload = {
+        "status": "PASS",
+        "db_path": str(db_path),
+        "seed_path": str(seed_path),
+        "summary": summary,
+        "settings_rows": len(settings_rows),
+        "account_snapshot_rows": len(snapshot_rows),
+        "settings_errors": settings_errors,
+        "snapshot_errors": snapshot_errors,
+        "export_path": str(exported),
+        "tsv_parse_rows": len(tsv_rows),
+    }
+    OUT.parent.mkdir(parents=True, exist_ok=True)
+    OUT.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    if settings_errors or snapshot_errors:
+        print("FAIL")
+        return 1
+    print("PASS")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

From ee4d1fdab8824703679f6397add9c2eb64f67e1f Mon Sep 17 00:00:00 2001
From: kjh2064 
Date: Sun, 21 Jun 2026 20:07:32 +0900
Subject: [PATCH 04/10] =?UTF-8?q?=EC=BA=98=EB=A6=AC=EB=B8=8C=EB=A0=88?=
 =?UTF-8?q?=EC=9D=B4=EC=85=98=20=EA=B1=B0=EB=B2=84=EB=84=8C=EC=8A=A4=20?=
 =?UTF-8?q?=EB=8F=84=EA=B5=AC=20+=20WBS-7.1/7.2=20=EC=8B=A4=EC=A6=9D=20?=
 =?UTF-8?q?=EA=B2=A9=EC=B0=A8=20=EA=B0=80=EC=8B=9C=ED=99=94?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

캘리브레이션 백로그 → 우선순위 → 검토리포트 → 승인목록 → 결정초안으로
이어지는 임계값 보정 거버넌스 파이프라인을 추가하고, 2026-06-21
비판적 리뷰에서 발견한 두 가지 stale-수치 문제를 도구 차원에서 해소한다.

- registry_health(): 190여 개 임계값의 source별(SPEC_DERIVED/EXPERT_PRIOR/
  PROVISIONAL/CALIBRATED) 분포를 매 실행마다 자동 집계 — 수동 grep 불필요
- live_t5_status(): T+5 적중률을 하드코딩(35.86 리터럴) 대신
  Temp/prediction_accuracy_harness_v2.json에서 항상 최신값으로 읽음
- spec/calibration_registry.yaml: SEMI_CLUSTER_CAP_RISK_OFF 중복 id로
  인한 조용한 무시 버그 수정(SEMI_CLUSTER_CAP_RISK_OFF_MWA로 분리)
- spec/27_bch_calibration_runbook.yaml: current_status_2026_06_21 블록
  신설(단일 진실원천), 기존 05-30 스냅샷은 "역사적, 현재로 인용 금지"로 명시
---
 .gitea/workflows/calibration_backlog.yml     |  80 ++++++++
 spec/27_bch_calibration_runbook.yaml         |  39 +++-
 spec/calibration_registry.yaml               |  29 ++-
 tests/unit/test_calibration_priority_v1.py   | 107 ++++++++++
 tools/build_calibration_approval_list_v1.py  | 136 ++++++++++++
 tools/build_calibration_decision_draft_v1.py | 152 ++++++++++++++
 tools/build_calibration_priority_v1.py       | 149 ++++++++++----
 tools/build_calibration_review_report_v1.py  | 205 +++++++++++++++++++
 8 files changed, 855 insertions(+), 42 deletions(-)
 create mode 100644 .gitea/workflows/calibration_backlog.yml
 create mode 100644 tests/unit/test_calibration_priority_v1.py
 create mode 100644 tools/build_calibration_approval_list_v1.py
 create mode 100644 tools/build_calibration_decision_draft_v1.py
 create mode 100644 tools/build_calibration_review_report_v1.py

diff --git a/.gitea/workflows/calibration_backlog.yml b/.gitea/workflows/calibration_backlog.yml
new file mode 100644
index 00000000..8c063773
--- /dev/null
+++ b/.gitea/workflows/calibration_backlog.yml
@@ -0,0 +1,80 @@
+name: Calibration Backlog (Registry Drift Watch)
+
+on:
+  schedule:
+    - cron: "15 2 * * 1-5"   # UTC 02:15 = KST 11:15, weekday backlog update
+  workflow_dispatch:
+
+jobs:
+  build-calibration-backlog:
+    runs-on: self-hosted
+
+    steps:
+    - name: Checkout Code
+      run: |
+        if [ -d .git ]; then
+          git remote set-url origin http://x-access-token:${{ secrets.GITHUB_TOKEN }}@192.168.123.100:8418/KimJaeHyun/myfinance.git
+        else
+          git init
+          git remote add origin http://x-access-token:${{ secrets.GITHUB_TOKEN }}@192.168.123.100:8418/KimJaeHyun/myfinance.git
+        fi
+        git fetch origin main --depth=1
+        git reset --hard FETCH_HEAD
+
+    - name: Configure Runtime Paths
+      run: |
+        export PATH=/usr/local/bin:$PATH
+        echo "/usr/local/bin" >> $GITHUB_PATH
+        /usr/bin/python3 --version
+
+    - name: Setup Python Environment
+      run: |
+        VENV_BASE=/volume1/gitea/python_venv
+        REQ_HASH=$(md5sum tools/build_calibration_priority_v1.py 2>/dev/null | cut -d' ' -f1 || echo "calib-default")
+        VENV="$VENV_BASE/$REQ_HASH"
+
+        if [ ! -f "$VENV/bin/python" ]; then
+          mkdir -p "$VENV_BASE"
+          /usr/bin/python3 -m venv "$VENV"
+          if [ ! -f "$VENV/bin/pip" ]; then
+            curl -sS https://bootstrap.pypa.io/pip/3.8/get-pip.py -o get-pip.py
+            "$VENV/bin/python" get-pip.py --quiet
+            rm get-pip.py
+          fi
+          "$VENV/bin/pip" install --upgrade pip --quiet
+          "$VENV/bin/pip" install pyyaml --quiet
+        fi
+        echo "$VENV/bin" >> $GITHUB_PATH
+
+    - name: Validate Calibration Registry
+      run: python3 tools/validate_calibration_registry_v1.py
+
+    - name: Build Calibration Priority Backlog
+      run: python3 tools/build_calibration_priority_v1.py
+
+    - name: Build Calibration Change Ledger
+      run: python3 tools/build_calibration_change_ledger_v4.py
+
+    - name: Build Calibration Review Report
+      run: python3 tools/build_calibration_review_report_v1.py
+
+    - name: Build Calibration Approval List
+      run: python3 tools/build_calibration_approval_list_v1.py
+
+    - name: Build Calibration Decision Draft
+      run: python3 tools/build_calibration_decision_draft_v1.py
+
+    - name: Validate Calibration Change Ledger
+      run: python3 tools/validate_calibration_change_ledger_v1.py
+
+    - name: Summarize Backlog
+      if: always()
+      run: |
+        STATUS="${{ job.status }}"
+        echo "=== Calibration Backlog Result ==="
+        echo "status: $STATUS"
+        echo "priority: Temp/calibration_priority_v1.json"
+        echo "ledger: Temp/calibration_change_ledger_v4.json"
+        echo "review: Temp/calibration_review_report_v1.md"
+        echo "approval: Temp/calibration_approval_list_v1.md"
+        echo "decision: Temp/calibration_decision_draft_v1.md"
diff --git a/spec/27_bch_calibration_runbook.yaml b/spec/27_bch_calibration_runbook.yaml
index e735c856..d5e6df72 100644
--- a/spec/27_bch_calibration_runbook.yaml
+++ b/spec/27_bch_calibration_runbook.yaml
@@ -451,7 +451,30 @@ reject_conditions:
   - "sample_n < 30인 임계값을 '보정완료'로 처리"
 
 # ════════════════════════════════════════════════════════════════════════════
-# 현재 달성 현황 (2026-05-30)
+# 현재 달성 현황 (2026-06-21 재검증 — WBS-7.2)
+# ════════════════════════════════════════════════════════════════════════════
+# 주의: 아래 current_status_2026_05_30 블록은 그 날짜 기준 정적 스냅샷이며,
+# 이후 갱신되지 않은 채 docs/ROADMAP_WBS.md 등에서 "현재 상태"로 인용되어
+# 서로 다른 시점의 T+5 수치(54.76%/35.86%)가 혼재하는 문제를 일으켰다.
+# Temp/honest_performance_guard_v1.json(생성: 2026-06-14)과
+# Temp/prediction_accuracy_harness_v2.json(생성: 2026-06-21, 7일 더 최신)을
+# 직접 재확인한 결과는 다음과 같다 — 이 블록을 단일 진실원천으로 삼는다.
+current_status_2026_06_21:
+  source_of_truth: "Temp/prediction_accuracy_harness_v2.json (as_of_date=2026-06-21, 가장 최신)"
+  t1_match_rate_pct: 52.94   # sample=68, decisive_sample=53, rate_decisive=67.92
+  t5_match_rate_pct: null    # sample=0 — INSUFFICIENT_SAMPLES. honest_performance_guard_v1.json(2026-06-14)의
+                             # 35.86%는 7일 전 스냅샷이며 표본이 0으로 줄어 더 이상 유효하지 않음.
+  t5_sample_regression_note: >
+    cases_analyzed가 141건(2026-05-30 기준)에서 t5_sample=0(2026-06-21)으로 감소했다.
+    evaluation_methodology가 ACTIVE_PASSIVE_SPLIT_V1_INCONCLUSIVE_EXCLUDED로 변경되며
+    inconclusive/replay 표본이 제외된 것으로 추정 — 근본 원인은 별도 조사 필요(WBS-7.2 잔여 항목).
+  calibration_registry_total_thresholds: 190  # spec/calibration_registry.yaml 직접 집계 (구문서의 70은 stale)
+  calibration_registry_expert_prior_count: 59
+  calibration_registry_calibrated_count: 0
+  rule: "이 문서를 인용할 때는 항상 as_of_date를 동반 표기하고, 아래 5/30 스냅샷을 '현재'로 인용하지 않는다."
+
+# ════════════════════════════════════════════════════════════════════════════
+# 과거 달성 현황 (2026-05-30, 역사적 스냅샷 — "현재"로 인용 금지)
 # ════════════════════════════════════════════════════════════════════════════
 current_status_2026_05_30:
   phase_1_bch: COMPLETE
@@ -489,3 +512,17 @@ current_status_2026_05_30:
   cases_analyzed: 141
   miss5_count: 51
   next_milestone: "cases_analyzed=30 달성 후 ALEG_V2_GATE1_BLOCK_PCT 보정 심사"
+  automation_entrypoints:
+    gitea_schedule: ".gitea/workflows/calibration_backlog.yml"
+    npm_script: "npm run ops:calibration-backlog"
+    generated_artifacts:
+      - Temp/calibration_priority_v1.json
+      - Temp/calibration_change_ledger_v4.json
+      - Temp/calibration_review_report_v1.json
+      - Temp/calibration_review_report_v1.md
+      - Temp/calibration_approval_list_v1.json
+      - Temp/calibration_approval_list_v1.md
+      - Temp/calibration_registry_v1.json
+    promotion_rules:
+      provisional: "sample_n >= 10 AND direction confirmed AND change_ledger entry exists"
+      calibrated: "sample_n >= 30 AND backtest_doc exists AND validator overclaimed_count == 0"
diff --git a/spec/calibration_registry.yaml b/spec/calibration_registry.yaml
index 392a1d20..0f2a9bb6 100644
--- a/spec/calibration_registry.yaml
+++ b/spec/calibration_registry.yaml
@@ -1,3 +1,7 @@
+has_code_implementation: true
+code_path:
+  - "tools/build_calibration_priority_v1.py"
+  - "tools/validate_calibration_registry_v1.py"
 thresholds:
 - id: ALEG_V2_GATE1_BLOCK_PCT
   value: 3.0
@@ -913,7 +917,7 @@ thresholds:
   notes: '이벤트 충격 방어: 20% 고정. KOSPI 비중 제공 시 max(20, weight×0.60).'
   live_sample_requirement: 30
   sunset_date: '2026-09-30'
-- id: SEMI_CLUSTER_CAP_RISK_OFF
+- id: SEMI_CLUSTER_CAP_RISK_OFF_MWA
   value: 25.0
   unit: pct
   source: EXPERT_PRIOR
@@ -921,7 +925,12 @@ thresholds:
   last_calibrated: null
   owner_formula: MARKET_WEIGHT_AWARE_CLUSTER_GATE_V1
   gs_location: gas_data_feed.gs:3858
-  notes: '하락장: 25%. KOSPI 비중 제공 시 max(25, weight×0.80).'
+  notes: >
+    하락장: 25%. KOSPI 비중 제공 시 max(25, weight×0.80).
+    WBS-7.1(2026-06-21): 원래 id가 SEMI_CLUSTER_CAP_RISK_OFF였으나
+    SEMICONDUCTOR_CLUSTER_GATE_V1 소유의 동명 entry(value=20.0)와 id가 충돌해
+    dict 기반 조회 시 한쪽이 조용히 무시되는 버그가 있었다. 외부 참조 0건 확인 후
+    이 entry(MARKET_WEIGHT_AWARE_CLUSTER_GATE_V1 소유)만 _MWA suffix로 분리했다.
   live_sample_requirement: 30
   sunset_date: '2026-09-30'
 - id: SEMI_CLUSTER_CAP_NEUTRAL
@@ -1803,6 +1812,22 @@ thresholds:
   gs_location: gas_data_feed.gs:2164
   notes: Base take-profit score used in profit-lock computation. Migrated from GAS SP constant to registry (P5-T01 wave2).
 
+- id: OVERHANG_PRESSURE_V1_FALLBACK_MULT
+  value: 1.5
+  unit: multiplier_of_avg_volume_5d
+  source: EXPERT_PRIOR
+  sample_n: 0
+  last_calibrated: null
+  owner_formula: OVERHANG_PRESSURE_V1
+  py_location: spec/13_formula_registry.yaml:OVERHANG_PRESSURE_V1.derived_flags.selling_acceleration.without_20d_fallback
+  notes: >
+    WBS-7.5(2026-06-21) — frg_20d_sh 미존재 시 selling_acceleration 폴백을
+    "frg_5d_sh < -500000"(절대 주식수, 임시) 에서 "frg_5d_sh < -1.5 * avg_volume_5d"
+    (해당 종목 평균거래량 비례) 로 교체. 1.5 배수는 with_20d 분기에서 동일 공식이
+    이미 사용하는 가속 임계(frg_20d_sh/4 × 1.5)를 그대로 재사용한 것이며, 새로
+    추정한 값이 아니다. 단, 실거래 표본으로 검증되지 않았으므로 EXPERT_PRIOR로
+    등록한다 — CALIBRATED 승격은 sample_n≥30 확보 후 검토.
+
 calibration_policy:
   honest_disclosure_required: true
   overclaimed_calibration_definition: 'source=CALIBRATED 이면서 sample_n < 30 → OVERCLAIMED_CALIBRATION.
diff --git a/tests/unit/test_calibration_priority_v1.py b/tests/unit/test_calibration_priority_v1.py
new file mode 100644
index 00000000..6696a195
--- /dev/null
+++ b/tests/unit/test_calibration_priority_v1.py
@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def _run(script: str) -> None:
+    subprocess.run(
+        [sys.executable, script],
+        cwd=ROOT,
+        check=True,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+    )
+
+
+def test_build_calibration_priority_and_change_ledger(tmp_path):
+    _run("tools/build_calibration_priority_v1.py")
+    _run("tools/build_calibration_change_ledger_v4.py")
+    _run("tools/validate_calibration_change_ledger_v1.py")
+
+    priority_path = ROOT / "Temp" / "calibration_priority_v1.json"
+    ledger_path = ROOT / "Temp" / "calibration_change_ledger_v4.json"
+
+    priority = json.loads(priority_path.read_text(encoding="utf-8"))
+    ledger = json.loads(ledger_path.read_text(encoding="utf-8"))
+
+    assert priority["status"] == "CALIBRATION_PRIORITY_OK"
+    assert priority["priority_count"] >= 5
+    assert priority["priority_list"]
+    assert priority["priority_basis"] in {"alpha_feedback_loop_v2", "registry_warning_fallback"}
+
+    assert ledger["formula_id"] == "CALIBRATION_CHANGE_LEDGER_V4"
+    assert ledger["threshold_change_without_ledger_count"] == 0
+    assert len(ledger["changes"]) >= 5
+
+
+def test_calibration_backlog_workflow_and_script_exist():
+    workflow = ROOT / ".gitea" / "workflows" / "calibration_backlog.yml"
+    package = json.loads((ROOT / "package.json").read_text(encoding="utf-8"))
+    assert workflow.exists()
+    assert "ops:calibration-backlog" in package["scripts"]
+    assert "ops:calibration-review-report" in package["scripts"]
+    assert "ops:calibration-approval-list" in package["scripts"]
+    assert "ops:calibration-decision-draft" in package["scripts"]
+
+
+def test_build_calibration_review_report(tmp_path):
+    _run("tools/build_calibration_priority_v1.py")
+    _run("tools/build_calibration_change_ledger_v4.py")
+    _run("tools/build_calibration_review_report_v1.py")
+
+    report_json = ROOT / "Temp" / "calibration_review_report_v1.json"
+    report_md = ROOT / "Temp" / "calibration_review_report_v1.md"
+    payload = json.loads(report_json.read_text(encoding="utf-8"))
+    text = report_md.read_text(encoding="utf-8")
+
+    assert payload["formula_id"] == "CALIBRATION_REVIEW_REPORT_V1"
+    assert payload["summary"]["total_thresholds"] >= 1
+    assert payload["top_priority_rows"]
+    assert "Calibration Review Report" in text
+    assert "Review Candidates" in text
+
+
+def test_build_calibration_approval_list(tmp_path):
+    _run("tools/build_calibration_priority_v1.py")
+    _run("tools/build_calibration_change_ledger_v4.py")
+    _run("tools/build_calibration_review_report_v1.py")
+    _run("tools/build_calibration_approval_list_v1.py")
+
+    approval_json = ROOT / "Temp" / "calibration_approval_list_v1.json"
+    approval_md = ROOT / "Temp" / "calibration_approval_list_v1.md"
+    payload = json.loads(approval_json.read_text(encoding="utf-8"))
+    text = approval_md.read_text(encoding="utf-8")
+
+    assert payload["formula_id"] == "CALIBRATION_APPROVAL_LIST_V1"
+    assert payload["approval_candidate_count"] >= 1
+    assert payload["approval_candidates"]
+    assert "Calibration Approval List" in text
+    assert "Approval Candidates" in text
+
+
+def test_build_calibration_decision_draft(tmp_path):
+    _run("tools/build_calibration_priority_v1.py")
+    _run("tools/build_calibration_change_ledger_v4.py")
+    _run("tools/build_calibration_review_report_v1.py")
+    _run("tools/build_calibration_approval_list_v1.py")
+    _run("tools/build_calibration_decision_draft_v1.py")
+
+    decision_json = ROOT / "Temp" / "calibration_decision_draft_v1.json"
+    decision_md = ROOT / "Temp" / "calibration_decision_draft_v1.md"
+    payload = json.loads(decision_json.read_text(encoding="utf-8"))
+    text = decision_md.read_text(encoding="utf-8")
+
+    assert payload["formula_id"] == "CALIBRATION_DECISION_DRAFT_V1"
+    assert payload["decision_count"] >= 1
+    assert payload["summary"]["APPROVE"] >= 1
+    assert payload["summary"]["HOLD"] >= 1
+    assert payload["summary"]["REJECT"] >= 0
+    assert "Calibration Decision Draft" in text
+    assert "Decision Table" in text
diff --git a/tools/build_calibration_approval_list_v1.py b/tools/build_calibration_approval_list_v1.py
new file mode 100644
index 00000000..c8332502
--- /dev/null
+++ b/tools/build_calibration_approval_list_v1.py
@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""
+build_calibration_approval_list_v1.py
+───────────────────────────────────────────────────────────────────────────────
+calibration_review_report_v1.json을 읽어 PROVISIONAL 승격 승인 리스트를 만든다.
+
+목적:
+  - source=PROVISIONAL 인 임계값을 별도 승인 대상 리스트로 분리
+  - reviewer가 바로 볼 수 있는 Markdown/JSON 산출물 생성
+  - PROVISIONAL 승격과 provisional review를 분리해 운영 책임을 명확화
+
+출력:
+  Temp/calibration_approval_list_v1.json
+  Temp/calibration_approval_list_v1.md
+
+사용법:
+  python tools/build_calibration_approval_list_v1.py
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).resolve().parent.parent
+REVIEW = ROOT / "Temp" / "calibration_review_report_v1.json"
+OUT_JSON = ROOT / "Temp" / "calibration_approval_list_v1.json"
+OUT_MD = ROOT / "Temp" / "calibration_approval_list_v1.md"
+
+if sys.stdout.encoding and sys.stdout.encoding.lower() not in ("utf-8", "utf8"):
+    sys.stdout = open(sys.stdout.fileno(), mode="w", encoding="utf-8", buffering=1)
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _table(rows: list[dict[str, Any]], keys: list[str], max_rows: int = 25) -> str:
+    if not rows:
+        return "_데이터 없음_"
+    header = "| " + " | ".join(keys) + " |"
+    sep = "| " + " | ".join(["---"] * len(keys)) + " |"
+    body = []
+    for row in rows[:max_rows]:
+        body.append("| " + " | ".join(str(row.get(k, "")).replace("|", "ㅣ") for k in keys) + " |")
+    suffix = f"\n\n_...총 {len(rows)}행 중 {max_rows}행 표시_" if len(rows) > max_rows else ""
+    return "\n".join([header, sep, *body]) + suffix
+
+
+def main() -> int:
+    review = _load_json(REVIEW)
+    rows = review.get("review_rows") if isinstance(review.get("review_rows"), list) else []
+
+    approval_candidates: list[dict[str, Any]] = []
+    provisional_review_candidates: list[dict[str, Any]] = []
+
+    for row in rows:
+        if not isinstance(row, dict):
+            continue
+        source = str(row.get("source") or "")
+        readiness = str(row.get("readiness") or "")
+        sample_n = int(row.get("sample_n") or 0)
+        base = {
+            "id": row.get("id", ""),
+            "source": source,
+            "sample_n": sample_n,
+            "value": row.get("value"),
+            "unit": row.get("unit", ""),
+            "owner_formula": row.get("owner_formula", ""),
+            "readiness": readiness,
+            "reason": row.get("reason", ""),
+        }
+        if source == "PROVISIONAL":
+            approval_candidates.append(base)
+        elif readiness == "PROVISIONAL_CANDIDATE":
+            provisional_review_candidates.append(base)
+
+    approval_candidates.sort(key=lambda item: (-int(item.get("sample_n") or 0), str(item.get("id") or "")))
+    provisional_review_candidates.sort(key=lambda item: (-int(item.get("sample_n") or 0), str(item.get("id") or "")))
+
+    report = {
+        "formula_id": "CALIBRATION_APPROVAL_LIST_V1",
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "review_report_path": str(REVIEW),
+        "approval_candidate_count": len(approval_candidates),
+        "provisional_review_candidate_count": len(provisional_review_candidates),
+        "approval_candidates": approval_candidates,
+        "provisional_review_candidates": provisional_review_candidates,
+    }
+
+    OUT_JSON.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    md_lines = [
+        "# Calibration Approval List",
+        "",
+        "## Summary",
+        "",
+        f"- approval candidates: {len(approval_candidates)}",
+        f"- provisional review candidates: {len(provisional_review_candidates)}",
+        "",
+        "## Approval Candidates",
+        "",
+        _table(approval_candidates, ["id", "source", "sample_n", "value", "unit", "owner_formula", "readiness", "reason"]),
+        "",
+        "## Provisional Review Candidates",
+        "",
+        _table(provisional_review_candidates, ["id", "source", "sample_n", "value", "unit", "owner_formula", "readiness", "reason"]),
+        "",
+        "## Evidence",
+        "",
+        f"- review report: {REVIEW}",
+    ]
+    OUT_MD.write_text("\n".join(md_lines), encoding="utf-8")
+
+    print(json.dumps({
+        "formula_id": report["formula_id"],
+        "gate": "PASS" if approval_candidates else "WARN",
+        "approval_candidate_count": len(approval_candidates),
+        "provisional_review_candidate_count": len(provisional_review_candidates),
+        "json_path": str(OUT_JSON),
+        "md_path": str(OUT_MD),
+    }, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/tools/build_calibration_decision_draft_v1.py b/tools/build_calibration_decision_draft_v1.py
new file mode 100644
index 00000000..e25d86e9
--- /dev/null
+++ b/tools/build_calibration_decision_draft_v1.py
@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+"""
+build_calibration_decision_draft_v1.py
+───────────────────────────────────────────────────────────────────────────────
+calibration_review_report_v1.json / calibration_approval_list_v1.json을 바탕으로
+운영 승인 초안(APPROVE / HOLD / REJECT)을 만든다.
+
+목적:
+  - 사람 검토 전 단계에서 결정 초안을 자동 생성
+  - source=PROVISIONAL은 원칙적으로 APPROVE
+  - PROVISIONAL_CANDIDATE는 HOLD
+  - 나머지는 REJECT 또는 HOLD로 사유를 명시
+
+출력:
+  Temp/calibration_decision_draft_v1.json
+  Temp/calibration_decision_draft_v1.md
+
+사용법:
+  python tools/build_calibration_decision_draft_v1.py
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+ROOT = Path(__file__).resolve().parent.parent
+REVIEW = ROOT / "Temp" / "calibration_review_report_v1.json"
+APPROVAL = ROOT / "Temp" / "calibration_approval_list_v1.json"
+OUT_JSON = ROOT / "Temp" / "calibration_decision_draft_v1.json"
+OUT_MD = ROOT / "Temp" / "calibration_decision_draft_v1.md"
+
+if sys.stdout.encoding and sys.stdout.encoding.lower() not in ("utf-8", "utf8"):
+    sys.stdout = open(sys.stdout.fileno(), mode="w", encoding="utf-8", buffering=1)
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _table(rows: list[dict[str, Any]], keys: list[str], max_rows: int = 25) -> str:
+    if not rows:
+        return "_데이터 없음_"
+    header = "| " + " | ".join(keys) + " |"
+    sep = "| " + " | ".join(["---"] * len(keys)) + " |"
+    body = []
+    for row in rows[:max_rows]:
+        body.append("| " + " | ".join(str(row.get(k, "")).replace("|", "ㅣ") for k in keys) + " |")
+    suffix = f"\n\n_...총 {len(rows)}행 중 {max_rows}행 표시_" if len(rows) > max_rows else ""
+    return "\n".join([header, sep, *body]) + suffix
+
+
+def _decide(row: dict[str, Any]) -> tuple[str, str]:
+    source = str(row.get("source") or "")
+    readiness = str(row.get("readiness") or "")
+    sample_n = int(row.get("sample_n") or 0)
+    if source == "PROVISIONAL" and sample_n >= 30:
+        return "APPROVE", "source=PROVISIONAL and sample_n>=30"
+    if source == "PROVISIONAL":
+        return "APPROVE", "source=PROVISIONAL"
+    if readiness == "PROVISIONAL_CANDIDATE":
+        return "HOLD", "Needs provisional review"
+    if sample_n >= 10:
+        return "HOLD", "Sample present but not provisional"
+    return "REJECT", "Insufficient evidence"
+
+
+def main() -> int:
+    review = _load_json(REVIEW)
+    approval = _load_json(APPROVAL)
+
+    review_rows = review.get("review_rows") if isinstance(review.get("review_rows"), list) else []
+    decisions: list[dict[str, Any]] = []
+    summary = {"APPROVE": 0, "HOLD": 0, "REJECT": 0}
+
+    for row in review_rows:
+        if not isinstance(row, dict):
+            continue
+        decision, reason = _decide(row)
+        item = {
+            "id": row.get("id", ""),
+            "source": row.get("source", ""),
+            "sample_n": int(row.get("sample_n") or 0),
+            "value": row.get("value"),
+            "unit": row.get("unit", ""),
+            "owner_formula": row.get("owner_formula", ""),
+            "readiness": row.get("readiness", ""),
+            "decision": decision,
+            "reason": reason,
+        }
+        decisions.append(item)
+        summary[decision] += 1
+
+    decisions.sort(key=lambda item: ({"APPROVE": 0, "HOLD": 1, "REJECT": 2}.get(str(item.get("decision") or ""), 3), -int(item.get("sample_n") or 0), str(item.get("id") or "")))
+
+    report = {
+        "formula_id": "CALIBRATION_DECISION_DRAFT_V1",
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "review_report_path": str(REVIEW),
+        "approval_list_path": str(APPROVAL),
+        "summary": summary,
+        "decision_count": len(decisions),
+        "decisions": decisions,
+        "approval_candidate_count": int(approval.get("approval_candidate_count") or 0),
+    }
+
+    OUT_JSON.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    md_lines = [
+        "# Calibration Decision Draft",
+        "",
+        "## Summary",
+        "",
+        f"- APPROVE: {summary['APPROVE']}",
+        f"- HOLD: {summary['HOLD']}",
+        f"- REJECT: {summary['REJECT']}",
+        f"- decision_count: {len(decisions)}",
+        "",
+        "## Decision Table",
+        "",
+        _table(decisions, ["id", "source", "sample_n", "decision", "reason", "owner_formula", "readiness"]),
+        "",
+        "## Evidence",
+        "",
+        f"- review report: {REVIEW}",
+        f"- approval list: {APPROVAL}",
+    ]
+    OUT_MD.write_text("\n".join(md_lines), encoding="utf-8")
+
+    print(json.dumps({
+        "formula_id": report["formula_id"],
+        "gate": "PASS" if summary["APPROVE"] else "WARN",
+        "approve_count": summary["APPROVE"],
+        "hold_count": summary["HOLD"],
+        "reject_count": summary["REJECT"],
+        "json_path": str(OUT_JSON),
+        "md_path": str(OUT_MD),
+    }, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/tools/build_calibration_priority_v1.py b/tools/build_calibration_priority_v1.py
index d2e355aa..c0b794c9 100644
--- a/tools/build_calibration_priority_v1.py
+++ b/tools/build_calibration_priority_v1.py
@@ -29,6 +29,41 @@ ROOT   = Path(__file__).resolve().parent.parent
 AFL    = ROOT / "Temp" / "alpha_feedback_loop_v2.json"
 REG    = ROOT / "spec" / "calibration_registry.yaml"
 OUTPUT = ROOT / "Temp" / "calibration_priority_v1.json"
+PREDICTION_ACCURACY = ROOT / "Temp" / "prediction_accuracy_harness_v2.json"
+
+
+def registry_source_breakdown(reg_index: dict[str, dict]) -> dict:
+    """WBS-7.1(2026-06-21) — calibration_registry.yaml 전체의 source별 분포를 매 실행마다
+    집계해 'CALIBRATED 비율이 실제로 몇 %인가'를 사람이 grep으로 직접 세지 않아도
+    항상 최신 상태로 노출한다(2026-06-21 비판적 리뷰 0c절에서 0/190 발견 당시 수동 집계 필요했던 문제 해소)."""
+    counts: dict[str, int] = {"SPEC_DERIVED": 0, "EXPERT_PRIOR": 0, "PROVISIONAL": 0, "CALIBRATED": 0}
+    for entry in reg_index.values():
+        source = str(entry.get("source", "")).upper()
+        if source in counts:
+            counts[source] += 1
+    total = sum(counts.values())
+    return {
+        "total_thresholds": total,
+        "counts": counts,
+        "calibrated_pct": round(100.0 * counts["CALIBRATED"] / total, 2) if total else 0.0,
+        "unvalidated_pct": round(100.0 * (counts["SPEC_DERIVED"] + counts["EXPERT_PRIOR"]) / total, 2) if total else 0.0,
+    }
+
+
+def live_t5_status() -> dict:
+    """WBS-7.2/7.1(2026-06-21) — T+5 수치를 하드코딩하지 않고 항상 최신 산출물에서 읽는다.
+    Temp/prediction_accuracy_harness_v2.json이 없거나 sample=0이면 정직하게 DATA_GATED로 보고한다."""
+    if not PREDICTION_ACCURACY.exists():
+        return {"status": "ARTIFACT_MISSING", "t5_sample": 0, "t5_match_rate_pct": None}
+    data = load_json(PREDICTION_ACCURACY)
+    t5_sample = int(data.get("t5_sample") or 0)
+    t5_rate = data.get("t5_op_rate")
+    return {
+        "status": "DATA_GATED" if t5_sample == 0 else "OK",
+        "as_of_date": data.get("as_of_date"),
+        "t5_sample": t5_sample,
+        "t5_match_rate_pct": t5_rate,
+    }
 
 if sys.stdout.encoding and sys.stdout.encoding.lower() not in ("utf-8", "utf8"):
     sys.stdout = open(sys.stdout.fileno(), mode="w", encoding="utf-8", buffering=1)
@@ -90,6 +125,42 @@ def load_registry(p: Path) -> dict[str, dict]:
     return {t["id"]: t for t in data.get("thresholds", []) if "id" in t}
 
 
+def _priority_from_registry_entry(entry: dict, source_tag: str, urgency_bias: int) -> dict:
+    sample_n = int(entry.get("sample_n", 0) or 0)
+    source = str(entry.get("source", "EXPERT_PRIOR"))
+    threshold_class = str(entry.get("threshold_class", "standard"))
+    urgency = urgency_bias
+    if source == "EXPERT_PRIOR":
+        urgency += 10
+    if source == "PROVISIONAL":
+        urgency += 20
+    if threshold_class == "live_critical":
+        urgency += 15
+    if sample_n == 0:
+        urgency += 5
+    if sample_n > 0:
+        urgency += max(0, 30 - sample_n)
+    return {
+        "calibration_id": entry.get("id", ""),
+        "current_value": entry.get("value"),
+        "owner_formula": entry.get("owner_formula", ""),
+        "source": source,
+        "sample_n": sample_n,
+        "linked_factor": source_tag,
+        "alpha_action": "registry_review",
+        "urgency_score": urgency,
+        "calibration_path": (
+            (
+                "표본 30건 이상 확보 후 PROVISIONAL 승격 → "
+                if sample_n >= 30
+                else f"표본 {30 - sample_n}건 추가 수집 후 PROVISIONAL 승격 → "
+            )
+            + "실측 T+5 승률 기반 최적값 backtest → CALIBRATED 확정"
+        ),
+        "rationale": f"source={source}, class={threshold_class}, sample_n={sample_n}",
+    }
+
+
 def main() -> int:
     afl_data  = load_json(AFL)
     reg_index = load_registry(REG)
@@ -112,48 +183,32 @@ def main() -> int:
     priority_list: list[dict] = []
 
     for adj in adjustments:
-        factor   = adj.get("factor", "")
-        action   = adj.get("action", "")
-        rationale = adj.get("rationale", "")
-        reg_ids  = FACTOR_TO_REGISTRY.get(factor, [])
+        factor = str(adj.get("factor", ""))
+        action = str(adj.get("action", ""))
+        rationale = str(adj.get("rationale", ""))
+        reg_ids = FACTOR_TO_REGISTRY.get(factor, [])
 
         for rid in reg_ids:
             reg_entry = reg_index.get(rid)
             if not reg_entry:
                 continue
-            source   = reg_entry.get("source", "EXPERT_PRIOR")
-            sample_n = int(reg_entry.get("sample_n", 0) or 0)
-            value    = reg_entry.get("value")
-            formula  = reg_entry.get("owner_formula", "")
+            item = _priority_from_registry_entry(reg_entry, factor, miss5_count if factor == "passive_signal_quality" else 0)
+            item["alpha_action"] = action or "feedback_review"
+            if rationale:
+                item["rationale"] = rationale[:200]
+            priority_list.append(item)
 
-            # 보정 우선도 점수: miss5_count 기여 + 미보정 가중
-            urgency = 0
-            if factor == "passive_signal_quality":
-                urgency += miss5_count  # miss가 많을수록 높은 urgency
-            if source == "EXPERT_PRIOR":
-                urgency += 10
-            if sample_n == 0:
-                urgency += 5
-
-            priority_list.append({
-                "calibration_id":   rid,
-                "current_value":    value,
-                "owner_formula":    formula,
-                "source":           source,
-                "sample_n":         sample_n,
-                "linked_factor":    factor,
-                "alpha_action":     action,
-                "urgency_score":    urgency,
-                "calibration_path": (
-                    (
-                        "표본 30건 이상 확보 후 PROVISIONAL 승격 → "
-                        if sample_n >= 30
-                        else f"표본 {30 - sample_n}건 추가 수집 후 PROVISIONAL 승격 → "
-                    )
-                    + "실측 T+5 승률 기반 최적값 backtest → CALIBRATED 확정"
-                ),
-                "rationale":        rationale[:200] if rationale else "",
-            })
+    if not priority_list:
+        # alpha_feedback_loop가 비어 있어도 registry 자체의 보정 debt를 추적할 수 있게 한다.
+        for reg_id, reg_entry in reg_index.items():
+            source = str(reg_entry.get("source", "EXPERT_PRIOR"))
+            if source not in {"EXPERT_PRIOR", "PROVISIONAL"}:
+                continue
+            tag = f"registry:{source.lower()}"
+            item = _priority_from_registry_entry(reg_entry, tag, 0)
+            if source == "PROVISIONAL":
+                item["urgency_score"] += 5
+            priority_list.append(item)
 
     # 중복 제거 (같은 rid, 높은 urgency 유지)
     seen: dict[str, dict] = {}
@@ -177,7 +232,19 @@ def main() -> int:
     print(f"  Step 2 (30건 후): ALEG_V2_GATE1_BLOCK_PCT 3.0% → 실측 최적값으로 PROVISIONAL 승격")
     print(f"  Step 3 (50건 후): DSD_V1 가중치 logistic regression 최적화")
     print(f"  Step 4 (100건 후): K2_SPLIT_RATIO backtest 비교 → CALIBRATED 확정")
-    print(f"  miss5_count={miss5_count}건 → passive_signal_quality 개선이 T+5 35.86%→50%+ 핵심")
+    registry_health = registry_source_breakdown(reg_index)
+    t5_status = live_t5_status()
+
+    print(f"\n  [캘리브레이션 레지스트리 건강도] (WBS-7.1)")
+    print(f"  total={registry_health['total_thresholds']} {registry_health['counts']}")
+    print(f"  CALIBRATED={registry_health['calibrated_pct']}%  미검증(SPEC_DERIVED+EXPERT_PRIOR)={registry_health['unvalidated_pct']}%")
+
+    if t5_status["status"] == "DATA_GATED":
+        print(f"  miss5_count={miss5_count}건 → T+5 현재 DATA_GATED(sample=0) — passive_signal_quality 개선 영향은 표본 누적 후 측정 가능")
+    elif t5_status["status"] == "ARTIFACT_MISSING":
+        print(f"  miss5_count={miss5_count}건 → T+5 산출물 없음(Temp/prediction_accuracy_harness_v2.json) — 먼저 생성 필요")
+    else:
+        print(f"  miss5_count={miss5_count}건 → T+5={t5_status['t5_match_rate_pct']}% (as_of={t5_status.get('as_of_date')}) → passive_signal_quality 개선 핵심")
 
     result = {
         "status": "CALIBRATION_PRIORITY_OK",
@@ -191,10 +258,14 @@ def main() -> int:
             "step3": "50건 후: DSD_V1 가중치 logistic regression 최적화",
             "step4": "100건 후: K2_SPLIT_RATIO 30/70~60/40 backtest → CALIBRATED",
         },
+        "priority_basis": "alpha_feedback_loop_v2" if adjustments else "registry_warning_fallback",
+        "registry_health": registry_health,
         "target_improvement": {
-            "current_t5_pct": 35.86,
+            "t5_status": t5_status["status"],
+            "current_t5_pct": t5_status["t5_match_rate_pct"],
+            "t5_as_of_date": t5_status.get("as_of_date"),
             "target_t5_pct": 55.0,
-            "key_lever": "passive_signal_quality (miss5_count=51건 개선)",
+            "key_lever": f"passive_signal_quality (miss5_count={miss5_count}건 개선)",
         },
     }
 
diff --git a/tools/build_calibration_review_report_v1.py b/tools/build_calibration_review_report_v1.py
new file mode 100644
index 00000000..6be6442e
--- /dev/null
+++ b/tools/build_calibration_review_report_v1.py
@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""
+build_calibration_review_report_v1.py
+───────────────────────────────────────────────────────────────────────────────
+calibration_registry.yaml + calibration_priority_v1.json + calibration_change_ledger_v4.json
+을 묶어 운영용 보정 리뷰 리포트를 만든다.
+
+목적:
+  - PROVISIONAL / CALIBRATED 승격 후보를 사람이 읽을 수 있게 정리
+  - registry warning fallback 상태를 숨기지 않고 그대로 공시
+  - 월간 보정 운영에서 바로 참고 가능한 Markdown + JSON 산출물 생성
+
+출력:
+  Temp/calibration_review_report_v1.json
+  Temp/calibration_review_report_v1.md
+
+사용법:
+  python tools/build_calibration_review_report_v1.py
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+ROOT = Path(__file__).resolve().parent.parent
+REGISTRY = ROOT / "spec" / "calibration_registry.yaml"
+PRIORITY = ROOT / "Temp" / "calibration_priority_v1.json"
+LEDGER = ROOT / "Temp" / "calibration_change_ledger_v4.json"
+OUT_JSON = ROOT / "Temp" / "calibration_review_report_v1.json"
+OUT_MD = ROOT / "Temp" / "calibration_review_report_v1.md"
+
+if sys.stdout.encoding and sys.stdout.encoding.lower() not in ("utf-8", "utf8"):
+    sys.stdout = open(sys.stdout.fileno(), mode="w", encoding="utf-8", buffering=1)
+
+
+def _load_json(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _load_registry(path: Path) -> list[dict[str, Any]]:
+    if not path.exists():
+        return []
+    data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    thresholds = data.get("thresholds", [])
+    return [t for t in thresholds if isinstance(t, dict)]
+
+
+def _readiness(entry: dict[str, Any]) -> tuple[str, str]:
+    source = str(entry.get("source") or "EXPERT_PRIOR")
+    sample_n = int(entry.get("sample_n") or 0)
+    if source == "CALIBRATED":
+        return "CALIBRATED", "Already calibrated"
+    if source == "PROVISIONAL" and sample_n >= 30:
+        return "CALIBRATION_READY", "Ready for calibrated review"
+    if source == "PROVISIONAL":
+        return "PROVISIONAL_ACTIVE", "Provisional with live samples"
+    if sample_n >= 10:
+        return "PROVISIONAL_CANDIDATE", "Candidate for provisional review"
+    return "WATCH", "Keep under watch"
+
+
+def _table(rows: list[dict[str, Any]], keys: list[str], max_rows: int = 25) -> str:
+    if not rows:
+        return "_데이터 없음_"
+    header = "| " + " | ".join(keys) + " |"
+    sep = "| " + " | ".join(["---"] * len(keys)) + " |"
+    body = []
+    for row in rows[:max_rows]:
+        body.append("| " + " | ".join(str(row.get(k, "")).replace("|", "ㅣ") for k in keys) + " |")
+    suffix = f"\n\n_...총 {len(rows)}행 중 {max_rows}행 표시_" if len(rows) > max_rows else ""
+    return "\n".join([header, sep, *body]) + suffix
+
+
+def main() -> int:
+    registry = _load_registry(REGISTRY)
+    priority = _load_json(PRIORITY)
+    ledger = _load_json(LEDGER)
+
+    source_counts: dict[str, int] = {}
+    readiness_counts: dict[str, int] = {}
+    reviewed_rows: list[dict[str, Any]] = []
+
+    for entry in registry:
+        source = str(entry.get("source") or "EXPERT_PRIOR")
+        source_counts[source] = source_counts.get(source, 0) + 1
+        readiness, reason = _readiness(entry)
+        readiness_counts[readiness] = readiness_counts.get(readiness, 0) + 1
+        if readiness in {"PROVISIONAL_CANDIDATE", "CALIBRATION_READY", "PROVISIONAL_ACTIVE"}:
+            reviewed_rows.append(
+                {
+                    "id": entry.get("id", ""),
+                    "source": source,
+                    "sample_n": int(entry.get("sample_n") or 0),
+                    "value": entry.get("value"),
+                    "unit": entry.get("unit", ""),
+                    "owner_formula": entry.get("owner_formula", ""),
+                    "readiness": readiness,
+                    "reason": reason,
+                    "notes": str(entry.get("notes") or "")[:120],
+                }
+            )
+
+    priority_list = priority.get("priority_list") if isinstance(priority.get("priority_list"), list) else []
+    priority_rows = []
+    for item in priority_list[:20]:
+        if not isinstance(item, dict):
+            continue
+        priority_rows.append(
+            {
+                "calibration_id": item.get("calibration_id", ""),
+                "source": item.get("source", ""),
+                "sample_n": item.get("sample_n", 0),
+                "urgency_score": item.get("urgency_score", 0),
+                "linked_factor": item.get("linked_factor", ""),
+                "owner_formula": item.get("owner_formula", ""),
+            }
+        )
+
+    report = {
+        "formula_id": "CALIBRATION_REVIEW_REPORT_V1",
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+        "registry_path": str(REGISTRY),
+        "priority_path": str(PRIORITY),
+        "ledger_path": str(LEDGER),
+        "summary": {
+            "total_thresholds": len(registry),
+            "source_counts": source_counts,
+            "readiness_counts": readiness_counts,
+            "priority_count": int(priority.get("priority_count") or len(priority_rows)),
+            "ledger_change_count": len(ledger.get("changes", [])) if isinstance(ledger.get("changes"), list) else 0,
+            "ledger_without_change_count": int(ledger.get("threshold_change_without_ledger_count") or 0),
+        },
+        "top_priority_rows": priority_rows,
+        "review_rows": reviewed_rows,
+    }
+
+    OUT_JSON.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    md_lines = [
+        "# Calibration Review Report",
+        "",
+        "## Summary",
+        "",
+        f"- total thresholds: {report['summary']['total_thresholds']}",
+        f"- priority count: {report['summary']['priority_count']}",
+        f"- ledger change count: {report['summary']['ledger_change_count']}",
+        f"- ledger without change count: {report['summary']['ledger_without_change_count']}",
+        "",
+        "### Source Counts",
+        "",
+        _table(
+            [{"source": k, "count": v} for k, v in sorted(source_counts.items())],
+            ["source", "count"],
+            max_rows=50,
+        ),
+        "",
+        "### Readiness Counts",
+        "",
+        _table(
+            [{"readiness": k, "count": v} for k, v in sorted(readiness_counts.items())],
+            ["readiness", "count"],
+            max_rows=50,
+        ),
+        "",
+        "## Top Priority Rows",
+        "",
+        _table(priority_rows, ["calibration_id", "source", "sample_n", "urgency_score", "linked_factor", "owner_formula"]),
+        "",
+        "## Review Candidates",
+        "",
+        _table(reviewed_rows, ["id", "source", "sample_n", "value", "unit", "owner_formula", "readiness", "reason"]),
+        "",
+        "## Evidence",
+        "",
+        f"- registry: {REGISTRY}",
+        f"- priority: {PRIORITY}",
+        f"- ledger: {LEDGER}",
+    ]
+    OUT_MD.write_text("\n".join(md_lines), encoding="utf-8")
+
+    print(json.dumps({
+        "formula_id": report["formula_id"],
+        "gate": "PASS" if reviewed_rows or priority_rows else "WARN",
+        "review_rows": len(reviewed_rows),
+        "priority_rows": len(priority_rows),
+        "json_path": str(OUT_JSON),
+        "md_path": str(OUT_MD),
+    }, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

From 5166750b536264bede5f84f160843024c0efbadd Mon Sep 17 00:00:00 2001
From: kjh2064 
Date: Sun, 21 Jun 2026 20:08:48 +0900
Subject: [PATCH 05/10] =?UTF-8?q?WBS-7.3/7.4/7.5/7.11:=20=EA=B1=B0?=
 =?UTF-8?q?=EB=B2=84=EB=84=8C=EC=8A=A4=20=EB=AC=B8=EC=84=9C=20=EC=A0=95?=
 =?UTF-8?q?=ED=95=A9=EC=84=B1=20=EC=A0=95=EB=A6=AC=20+=20spec-=EC=BD=94?=
 =?UTF-8?q?=EB=93=9C=20=EB=8F=99=EA=B8=B0=ED=99=94=20=EA=B2=8C=EC=9D=B4?=
 =?UTF-8?q?=ED=8A=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

2026-06-21 비판적 리뷰에서 spec/governance YAML이 코드 상태와 어긋난
채로 방치되던 3개 구체적 사례를 발견하고 정정했다. 근본 원인(동기화를
보장하는 장치 없음)에 대응하는 신규 CI 게이트도 함께 추가한다.

- spec/aliases.yaml: deprecated alias 17건 제거(활성 참조 0건 확인 후,
  2026-06-30 데드라인 전). role: deprecated_redirect인 spec/03_risk_policy.yaml,
  spec/04_strategy_rules.yaml 2개만 실삭제 — spec/06_exit_policy.yaml은
  role: compatibility_index(영구유지 설계)였음을 재확인해 보존
- governance/gas_logic_migration_ledger_v1.yaml: 존재하지 않는 파일을
  canonical 구현으로 인용하던 오류 2건 발견·정정, parity 테스트 부재로
  GAS 코드 삭제 보류(F12/F13/F14)
- spec/13_formula_registry.yaml: OVERHANG_PRESSURE_V1의 "-500000"
  절대값 폴백을 avg_volume_5d 비례식으로 교체(EXPERT_PRIOR 등록)
- tools/validate_specs.py: validate_spec_code_sync() 신규 — has_code_implementation/
  code_path 필드가 있는 spec만 검사(점진적 롤아웃, 기존 PASS 상태 비파괴),
  12개 파일 1차 태깅
---
 RetirementAssetPortfolio.yaml                 |   4 +-
 governance/gas_logic_migration_ledger_v1.yaml |  41 ++++++-
 spec/03_risk_policy.yaml                      |  28 -----
 spec/04_strategy_rules.yaml                   |  32 -----
 spec/06_exit_policy.yaml                      |   2 +
 spec/13_formula_registry.yaml                 |  23 +++-
 spec/15_account_snapshot_contract.yaml        |   2 +
 spec/18_settings_contract.yaml                |   2 +
 spec/19_harness_contract.yaml                 |   2 +
 spec/41_release_dag.yaml                      | 114 +++++++++++++++++-
 spec/55_execution_simulator_contract.yaml     |   2 +
 spec/aliases.yaml                             |  86 +++----------
 spec/ownership_map.yaml                       |  13 +-
 spec/risk/README.md                           |   5 +-
 spec/risk/factor_risk.yaml                    |   2 +-
 spec/risk/portfolio_exposure.yaml             |   2 +-
 spec/risk/quality_control.yaml                |   2 +-
 spec/risk/risk_control.yaml                   |   4 +-
 spec/strategy/README.md                       |   5 +-
 spec/strategy/entry_gates.yaml                |   4 +-
 spec/strategy/rebalancing_trigger.yaml        |   2 +-
 spec/strategy/sector_model.yaml               |   2 +-
 spec/strategy/stock_model.yaml                |   2 +-
 tests/unit/test_validate_spec_code_sync_v1.py |  69 +++++++++++
 tools/validate_specs.py                       |  66 +++++++++-
 25 files changed, 351 insertions(+), 165 deletions(-)
 delete mode 100644 spec/03_risk_policy.yaml
 delete mode 100644 spec/04_strategy_rules.yaml
 create mode 100644 tests/unit/test_validate_spec_code_sync_v1.py

diff --git a/RetirementAssetPortfolio.yaml b/RetirementAssetPortfolio.yaml
index c7e11610..8f722758 100644
--- a/RetirementAssetPortfolio.yaml
+++ b/RetirementAssetPortfolio.yaml
@@ -246,7 +246,6 @@ spec_files:
   data_gaps_roadmap: "spec/16_data_gaps_roadmap.yaml"
   performance_contract: "spec/17_performance_contract.yaml"
   settings_contract: "spec/18_settings_contract.yaml"
-  risk_policy_index: "spec/03_risk_policy.yaml"
   risk_control_index: "spec/risk/risk_control.yaml"
   aggregate_risk: "spec/risk/aggregate_risk.yaml"
   circuit_breakers: "spec/risk/circuit_breakers.yaml"
@@ -254,7 +253,6 @@ spec_files:
   portfolio_exposure: "spec/risk/portfolio_exposure.yaml"
   risk_quality_control: "spec/risk/quality_control.yaml"
   factor_risk: "spec/risk/factor_risk.yaml"
-  strategy_rules_index: "spec/04_strategy_rules.yaml"
   sector_model: "spec/strategy/sector_model.yaml"
   entry_gates_index: "spec/strategy/entry_gates.yaml"
   entry_core: "spec/strategy/entry_core.yaml"
@@ -297,6 +295,7 @@ spec_files:
   event_response: "spec/exit/event_response.yaml"
   position_review: "spec/exit/position_review.yaml"
   dynamic_value_preservation_sell_v3: "spec/exit/dynamic_value_preservation_sell_v3.yaml"
+  qualitative_sell_strategy_v1: "spec/exit/qualitative_sell_strategy_v1.yaml"
   output_schema: "spec/07_output_schema.yaml"
   machine_output_schema: "schemas/output_schema.json"
   report_templates: "RetirementAssetPortfolioReportTemplate.yaml"
@@ -337,6 +336,7 @@ spec_files:
       - "spec/exit/event_response.yaml"
       - "spec/exit/position_review.yaml"
       - "spec/exit/dynamic_value_preservation_sell_v3.yaml"
+      - "spec/exit/qualitative_sell_strategy_v1.yaml"
     strategy:
       - "spec/strategy/sector_model.yaml"
       - "spec/strategy/entry_gates.yaml"
diff --git a/governance/gas_logic_migration_ledger_v1.yaml b/governance/gas_logic_migration_ledger_v1.yaml
index e34cf8a4..5776902c 100644
--- a/governance/gas_logic_migration_ledger_v1.yaml
+++ b/governance/gas_logic_migration_ledger_v1.yaml
@@ -10,6 +10,23 @@ classification_summary:
   display_text: 1
 unclassified_findings: 0
 
+# WBS-7.3 재검토 (2026-06-21):
+# - F01/F09 (REGISTER_*): DONE으로 정정 — spec/calibration_registry.yaml에 이미
+#   등록되어 있었음(P5-T01 wave1). 레저 상태가 stale했을 뿐 실작업 불필요.
+# - F12/F13 (DELETE_DISTRIBUTION_RISK_GAS): ledger의 "build_distribution_risk_v1.py"
+#   인용은 오류(존재하지 않는 파일) — 실제는 build_distribution_risk_score_v2.py가
+#   동일 필드를 산출하나, GAS-Python parity 테스트가 전혀 없어 삭제를 보류.
+# - F14 (DELETE_LATE_CHASE_RISK_GAS): ledger의 전제 자체가 잘못됨 — late_chase_risk_score를
+#   "산출"하는 Python 캐노니컬이 존재하지 않는다(소비하는 도구만 있음). GAS가 유일한
+#   산출 경로일 가능성이 높아 삭제 시도하지 않음. migration_action 재검증 필요.
+# - F02~F06, F07, F10, F11, F15 (MEDIUM/HIGH priority MIGRATE_*): 전용 parity 테스트
+#   인프라(GAS 함수와 동일 입력으로 Python 포트 출력을 대조)가 없는 상태에서 결정론적
+#   매매엔진의 가격/수량/정지손실/라우팅 로직을 포팅하는 것은 silent correctness bug
+#   위험이 크다고 판단해 이번 세션에서는 착수하지 않았다(advisor 권고에 따른 보류).
+#   특히 F11(stop_loss_gate)은 ledger 자체가 "critical path — must match
+#   validate_stop_loss_policy_v1 spec"로 명시한 항목이다. 후속 전용 스프린트에서
+#   parity 테스트를 먼저 구축한 뒤 착수해야 한다.
+
 # Canonical classification of GAS thin-adapter findings identified by
 # validate_gas_thin_adapter_v1.py. Each finding is classified by what type
 # of logic it contains and paired with a migration_action.
@@ -21,7 +38,8 @@ findings:
     classification: score_logic
     migration_action: REGISTER_SP_TAKE_PROFIT
     target_file: formulas/score_thresholds_v1.py
-    status: TODO
+    status: DONE
+    resolved_2026_06_21: "이미 spec/calibration_registry.yaml에 id=SP_TAKE_PROFIT(gs_location=gas_data_feed.gs:186, 'P5-T01 wave1'에서 등록)으로 등록되어 있음을 재확인. 별도 formulas/score_thresholds_v1.py 신규 작성 불필요 — 레저 상태만 stale했음."
 
   - id: F02
     file: src/gas_adapter_parts/gdf_01_price_metrics.gs
@@ -95,7 +113,8 @@ findings:
     classification: score_logic
     migration_action: REGISTER_TAKE_PROFIT_BASE
     target_file: formulas/score_thresholds_v1.py
-    status: TODO
+    status: DONE
+    resolved_2026_06_21: "이미 spec/calibration_registry.yaml에 id=TAKE_PROFIT_BASE(gs_location=gas_data_feed.gs:2164)로 등록되어 있음을 재확인. F01과 동일 사유로 레저 상태만 stale했음."
 
   - id: F10
     file: src/gas_adapter_parts/gdf_03_portfolio_gates.gs
@@ -124,6 +143,14 @@ findings:
     target_file: formulas/distribution_risk_v1.py
     status: TODO
     notes: Python canonical (build_distribution_risk_v1.py) already exists; GAS version is duplicate
+    reviewed_2026_06_21: >
+      원본 인용("build_distribution_risk_v1.py")은 존재하지 않는 파일이다 — 실제로는
+      tools/build_distribution_risk_score_v2.py가 동일 필드명(distribution_risk_score,
+      formula_id=DISTRIBUTION_RISK_SCORE_V2)을 산출한다. 다만 GAS gdf_03 라인 2128과
+      이 Python 산출값을 같은 입력에서 직접 대조하는 parity 테스트가 tests/ 어디에도
+      없다(tests/parity, tests/regression 전수 검색 결과 0건). "verify parity before
+      delete" 조건이 충족되지 않아 GAS 삭제를 보류한다 — 전용 parity 테스트 작성이
+      선행되어야 한다(WBS-7.3 후속 스프린트).
 
   - id: F13
     file: src/gas_adapter_parts/gdf_03_portfolio_gates.gs
@@ -133,6 +160,7 @@ findings:
     migration_action: DELETE_DISTRIBUTION_RISK_GAS
     status: TODO
     notes: formula_id tag stays with Python canonical; remove from GAS
+    reviewed_2026_06_21: "F12와 동일 사유로 보류 — parity 테스트 선행 필요."
 
   - id: F14
     file: src/gas_adapter_parts/gdf_03_portfolio_gates.gs
@@ -143,6 +171,15 @@ findings:
     target_file: formulas/late_chase_risk_v1.py
     status: TODO
     notes: Python canonical (build_alpha_lead_table_v1.py) computes late_chase_risk; GAS version is duplicate
+    reviewed_2026_06_21: >
+      원본 인용("build_alpha_lead_table_v1.py")은 존재하지 않는 파일이며, 이 ledger의
+      claim 자체가 잘못되었다 — 재조사 결과 late_chase_risk_score를 "산출"하는 Python
+      캐노니컬은 존재하지 않는다. tools/build_late_chase_attribution_v1.py는 이 필드를
+      입력에서 "소비"만 할 뿐(r.get("late_chase_risk_score")) 직접 계산하지 않으며,
+      build_anti_late_chase_v5/v6.py도 별도 산출 로직이다. 즉 GAS gdf_03이 현재 이
+      점수의 유일한 산출 경로일 가능성이 높다 — DELETE_LATE_CHASE_RISK_GAS는
+      migration_action 자체가 전제(Python 중복)부터 재검증이 필요하며, 지금 삭제하면
+      이 점수의 유일한 산출처를 제거하는 사고로 이어질 수 있다. 삭제 금지, 후속 조사 필요.
 
   - id: F15
     file: src/gas_adapter_parts/gdf_04_execution_quality.gs
diff --git a/spec/03_risk_policy.yaml b/spec/03_risk_policy.yaml
deleted file mode 100644
index 04dc1b75..00000000
--- a/spec/03_risk_policy.yaml
+++ /dev/null
@@ -1,28 +0,0 @@
-meta:
-  title: "은퇴자산포트폴리오 — 리스크 정책 호환 인덱스 (redirect-only)"
-  parent_file: "RetirementAssetPortfolio.yaml"
-  version: "2026-05-17-phase3_redirect_clarified"
-  language: "ko-KR"
-  timezone: "Asia/Seoul"
-  role: "deprecated_redirect"
-  warning: >
-    이 파일은 경로 호환성 유지 전용입니다. 새 규칙·임계값 추가 금지.
-    실제 리스크 규칙은 아래 canonical_split_files를 직접 참조하십시오.
-
-canonical_split_files:
-  portfolio_exposure_framework: "spec/risk/portfolio_exposure.yaml"
-  risk_control: "spec/risk/risk_control.yaml"
-  quality_control: "spec/risk/quality_control.yaml"
-
-legacy_path_aliases:
-  "spec/03_risk_policy.yaml:portfolio_exposure_framework": "spec/risk/portfolio_exposure.yaml:portfolio_exposure_framework"
-  "spec/03_risk_policy.yaml:risk_control": "spec/risk/risk_control.yaml:risk_control"
-  "spec/03_risk_policy.yaml:quality_control": "spec/risk/quality_control.yaml:quality_control"
-
-migration_rule:
-  - "신규 참조는 반드시 canonical_split_files의 경로를 사용한다."
-  - "기존 문서/예시에서 legacy path가 남아 있으면 alias로 해석하되, 수정 시 새 경로로 교체한다."
-  - "이 파일에는 수치 임계값을 추가하지 않는다."
-
-validation:
-  - "python tools/validate_specs.py"
diff --git a/spec/04_strategy_rules.yaml b/spec/04_strategy_rules.yaml
deleted file mode 100644
index b65210cb..00000000
--- a/spec/04_strategy_rules.yaml
+++ /dev/null
@@ -1,32 +0,0 @@
-meta:
-  title: "은퇴자산포트폴리오 — 전략 규칙 호환 인덱스 (redirect-only)"
-  parent_file: "RetirementAssetPortfolio.yaml"
-  version: "2026-05-17-phase3_redirect_clarified"
-  language: "ko-KR"
-  timezone: "Asia/Seoul"
-  role: "deprecated_redirect"
-  warning: >
-    이 파일은 경로 호환성 유지 전용입니다. 새 규칙·임계값 추가 금지.
-    실제 전략 규칙은 아래 canonical_split_files를 직접 참조하십시오.
-
-canonical_split_files:
-  sector_model: "spec/strategy/sector_model.yaml"
-  entry_timing_guardrails: "spec/strategy/entry_gates.yaml"
-  anti_late_trade_rule: "spec/strategy/entry_gates.yaml"
-  stock_model: "spec/strategy/stock_model.yaml"
-  rebalancing_trigger: "spec/strategy/rebalancing_trigger.yaml"
-
-legacy_path_aliases:
-  "spec/04_strategy_rules.yaml:sector_model": "spec/strategy/sector_model.yaml:sector_model"
-  "spec/04_strategy_rules.yaml:entry_timing_guardrails": "spec/strategy/entry_gates.yaml:entry_timing_guardrails"
-  "spec/04_strategy_rules.yaml:anti_late_trade_rule": "spec/strategy/entry_gates.yaml:anti_late_trade_rule"
-  "spec/04_strategy_rules.yaml:stock_model": "spec/strategy/stock_model.yaml:stock_model"
-  "spec/04_strategy_rules.yaml:rebalancing_trigger": "spec/strategy/rebalancing_trigger.yaml:rebalancing_trigger"
-
-migration_rule:
-  - "신규 참조는 반드시 canonical_split_files의 경로를 사용한다."
-  - "기존 문서/예시에서 legacy path가 남아 있으면 alias로 해석하되, 수정 시 새 경로로 교체한다."
-  - "이 파일에는 수치 임계값을 추가하지 않는다."
-
-validation:
-  - "python tools/validate_specs.py"
diff --git a/spec/06_exit_policy.yaml b/spec/06_exit_policy.yaml
index 2f0b3ea0..c556da2d 100644
--- a/spec/06_exit_policy.yaml
+++ b/spec/06_exit_policy.yaml
@@ -5,6 +5,8 @@ meta:
   language: "ko-KR"
   timezone: "Asia/Seoul"
   role: "compatibility_index"
+  has_code_implementation: false
+  redirect_only: true
   purpose: "기존 spec/06_exit_policy.yaml 경로를 보존하기 위한 인덱스 파일."
 
 canonical_split_files:
diff --git a/spec/13_formula_registry.yaml b/spec/13_formula_registry.yaml
index 6e64990a..18a5ad17 100644
--- a/spec/13_formula_registry.yaml
+++ b/spec/13_formula_registry.yaml
@@ -119,6 +119,11 @@ formula_registry:
       - CONSECUTIVE_STREAK_V1
       - BREAKOUT_FAILURE_STOP_V1
       - TREND_FILTER_GATE_V1
+      - SHORT_INTEREST_RISK_GAUGE_V1
+      - QUALITATIVE_SELL_STRATEGY_V1
+      - MARKET_REGIME_CLASSIFIER_V1
+      - SATELLITE_CANDIDATE_SCORE_V1
+      - MICROSTRUCTURE_PRESSURE_FROM_ORDERBOOK_V1
       implementation_map:
         REGIME_CONDITIONAL_MACRO_FACTOR_V1: tools/build_predictive_alpha_dialectic_engine_v2.py:NF1
         REBOUND_CAPTURE_THESIS_FACTOR_V1: tools/build_predictive_alpha_dialectic_engine_v2.py:NF2
@@ -165,6 +170,11 @@ formula_registry:
         CONSECUTIVE_STREAK_V1: tools/build_consecutive_streak_v1.py
         BREAKOUT_FAILURE_STOP_V1: tools/build_breakout_failure_stop_v1.py
         TREND_FILTER_GATE_V1: tools/build_trend_filter_gate_v1.py
+        SHORT_INTEREST_RISK_GAUGE_V1: src/quant_engine/qualitative_sell_strategy_v1.py:compute_short_interest_composite
+        QUALITATIVE_SELL_STRATEGY_V1: src/quant_engine/qualitative_sell_strategy_v1.py:compute_qualitative_sell_strategy
+        MARKET_REGIME_CLASSIFIER_V1: src/quant_engine/qualitative_sell_strategy_v1.py:classify_market_regime
+        SATELLITE_CANDIDATE_SCORE_V1: src/quant_engine/qualitative_sell_strategy_v1.py:compute_satellite_candidate_score
+        MICROSTRUCTURE_PRESSURE_FROM_ORDERBOOK_V1: src/quant_engine/qualitative_sell_strategy_v1.py:compute_microstructure_pressure_from_orderbook
   formulas:
     FLOW_CREDIT_V1:
       owner: engine_owner
@@ -1209,8 +1219,11 @@ formula_registry:
             / 4) * (-1.5)
 
             '
-          without_20d_fallback: 'frg_5d_sh < -500000  # 절대값 기준 임시 적용 OR flow_credit
-            < 0.30
+          without_20d_fallback: 'avg_volume_5d IS NOT NULL AND frg_5d_sh < -1.5 * avg_volume_5d
+            OR flow_credit < 0.30  # 2026-06-21 WBS-7.5: 절대값(-500000) 폐기, avg_volume_5d
+            비례식으로 교체. 1.5배수는 with_20d 분기와 동일 계수 재사용(추정 아님).
+            calibration_ref: spec/calibration_registry.yaml:OVERHANG_PRESSURE_V1_FALLBACK_MULT (EXPERT_PRIOR)
+            avg_volume_5d 결측 시 이 항목은 false로 처리(추정 금지, missing_policy 참조)
 
             '
         volume_weakness: volume < avg_volume_5d * 0.80
@@ -1231,8 +1244,10 @@ formula_registry:
         status: PASS
       missing_policy:
         frg_5d_sh: W2 DATA_MISSING. 레이더 결과 무효.
-        avg_volume_5d: volume_weakness=false 처리 (보수적)
-        frg_20d_sh: DATA_MISSING 시 fallback 기준 적용
+        avg_volume_5d: volume_weakness=false 처리 (보수적). frg_20d_sh도 없는 경우
+          selling_acceleration의 without_20d_fallback 비례식도 계산 불가하므로
+          동일하게 false 처리(추정 금지) — flow_credit < 0.30만 단독 평가.
+        frg_20d_sh: DATA_MISSING 시 fallback(avg_volume_5d 비례식, 2026-06-21 WBS-7.5) 기준 적용
       cross_alert:
         rule: W1_DIVERGENCE_ALERT + W2_OVERHANG_ALERT 동시 → CRITICAL_ALERT 상향
         output_tag: '[W1+W2_CRITICAL_ALERT]'
diff --git a/spec/15_account_snapshot_contract.yaml b/spec/15_account_snapshot_contract.yaml
index 0a9c4b6e..88263c1e 100644
--- a/spec/15_account_snapshot_contract.yaml
+++ b/spec/15_account_snapshot_contract.yaml
@@ -5,6 +5,8 @@ meta:
   language: "ko-KR"
   timezone: "Asia/Seoul"
   role: "canonical"
+  has_code_implementation: true
+  code_path: "src/quant_engine/snapshot_admin_store_v1.py"
   purpose: >
     이미지 캡처로 제공되는 계좌·잔고·현금 데이터를 구조화하는 계약.
     HTS 입력 가능 주문수량은 이 계약을 통과한 account_snapshot 없이는 산출 금지.
diff --git a/spec/18_settings_contract.yaml b/spec/18_settings_contract.yaml
index 075b5635..0d28669a 100644
--- a/spec/18_settings_contract.yaml
+++ b/spec/18_settings_contract.yaml
@@ -5,6 +5,8 @@ meta:
   language: "ko-KR"
   timezone: "Asia/Seoul"
   role: "canonical"
+  has_code_implementation: true
+  code_path: "src/quant_engine/snapshot_admin_store_v1.py"
   purpose: >
     Google Sheets 'settings' 탭의 구조를 정의한다.
     GAS 함수 readSettingsTab_()이 이 탭을 읽어 파라미터를 공급한다.
diff --git a/spec/19_harness_contract.yaml b/spec/19_harness_contract.yaml
index bf4d9830..5b7838d2 100644
--- a/spec/19_harness_contract.yaml
+++ b/spec/19_harness_contract.yaml
@@ -2,6 +2,8 @@ meta:
   title: "은퇴자산포트폴리오 — 결정론적 실행 하네스 계약 (QEH)"
   parent_file: "RetirementAssetPortfolio.yaml"
   version: "2026-05-23-QEH-V5.0-PROPOSAL46"
+  has_code_implementation: true
+  code_path: "tools/validate_harness_context.py"
   purpose: >
     LLM의 자의적 해석 및 주관적 계산을 원천 배제하고, 전문사(Analyst, Trader, Quant) 수준의 
     정밀한 판단을 강제하기 위한 결정론적 하네스(Deterministic Harness)의 
diff --git a/spec/41_release_dag.yaml b/spec/41_release_dag.yaml
index afad1b44..06eb46fe 100644
--- a/spec/41_release_dag.yaml
+++ b/spec/41_release_dag.yaml
@@ -1,6 +1,8 @@
 schema_version: release_dag.v3
 step_count: 99
 goal: Linearize package.json scripts into a validated DAG execution graph.
+has_code_implementation: true
+code_path: "tools/run_release_dag_v3.py"
 execution_order:
   # 토폴로지 정렬 기준 병렬 실행 wave (의존성 없는 노드들을 동시에 실행 가능)
   wave_0:
@@ -86,6 +88,11 @@ execution_order:
   wave_6:
     - build_algorithm_guidance_proof
     - build_artifact_chain_hash
+    - build_calibration_priority
+    - build_calibration_change_ledger
+    - build_calibration_review_report
+    - build_calibration_approval_list
+    - build_calibration_decision_draft
     - build_alpha_feedback_loop
     - build_honest_proof_gap_analyzer
     - build_operational_alpha_calibration
@@ -220,6 +227,66 @@ dag:
       artifact_policy: "keep"
       note: "WBS-4.3 alpha feedback loop — non-blocking diagnostic"
 
+    build_calibration_priority:
+      id: build_calibration_priority
+      command: ["python", "tools/build_calibration_priority_v1.py"]
+      inputs: ["tools/build_calibration_priority_v1.py", "Temp/alpha_feedback_loop_v2.json", "spec/calibration_registry.yaml"]
+      outputs: ["Temp/calibration_priority_v1.json"]
+      depends_on: ["build_alpha_feedback_loop"]
+      timeout_sec: 30
+      cache_key: "build_calibration_priority_v1"
+      strict: false
+      artifact_policy: "keep"
+      note: "CALIBRATION_PRIORITY_V1 — registry warning fallback 포함 보정 우선순위 리포트"
+
+    build_calibration_change_ledger:
+      id: build_calibration_change_ledger
+      command: ["python", "tools/build_calibration_change_ledger_v4.py"]
+      inputs: ["tools/build_calibration_change_ledger_v4.py", "Temp/calibration_priority_v1.json", "Temp/outcome_ledger_v1.json", "Temp/calibration_registry_v1.json"]
+      outputs: ["Temp/calibration_change_ledger_v4.json"]
+      depends_on: ["build_calibration_priority", "build_realized_performance"]
+      timeout_sec: 30
+      cache_key: "build_calibration_change_ledger_v4"
+      strict: false
+      artifact_policy: "keep"
+      note: "CALIBRATION_CHANGE_LEDGER_V4 — change ledger linkage 유지"
+
+    build_calibration_review_report:
+      id: build_calibration_review_report
+      command: ["python", "tools/build_calibration_review_report_v1.py"]
+      inputs: ["tools/build_calibration_review_report_v1.py", "Temp/calibration_priority_v1.json", "Temp/calibration_change_ledger_v4.json", "spec/calibration_registry.yaml"]
+      outputs: ["Temp/calibration_review_report_v1.json", "Temp/calibration_review_report_v1.md"]
+      depends_on: ["build_calibration_change_ledger"]
+      timeout_sec: 30
+      cache_key: "build_calibration_review_report_v1"
+      strict: false
+      artifact_policy: "keep"
+      note: "CALIBRATION_REVIEW_REPORT_V1 — 월간 운영용 읽기 쉬운 보정 리포트"
+
+    build_calibration_approval_list:
+      id: build_calibration_approval_list
+      command: ["python", "tools/build_calibration_approval_list_v1.py"]
+      inputs: ["tools/build_calibration_approval_list_v1.py", "Temp/calibration_review_report_v1.json"]
+      outputs: ["Temp/calibration_approval_list_v1.json", "Temp/calibration_approval_list_v1.md"]
+      depends_on: ["build_calibration_review_report"]
+      timeout_sec: 30
+      cache_key: "build_calibration_approval_list_v1"
+      strict: false
+      artifact_policy: "keep"
+      note: "CALIBRATION_APPROVAL_LIST_V1 — PROVISIONAL 승인/검토 분리"
+
+    build_calibration_decision_draft:
+      id: build_calibration_decision_draft
+      command: ["python", "tools/build_calibration_decision_draft_v1.py"]
+      inputs: ["tools/build_calibration_decision_draft_v1.py", "Temp/calibration_review_report_v1.json", "Temp/calibration_approval_list_v1.json"]
+      outputs: ["Temp/calibration_decision_draft_v1.json", "Temp/calibration_decision_draft_v1.md"]
+      depends_on: ["build_calibration_approval_list"]
+      timeout_sec: 30
+      cache_key: "build_calibration_decision_draft_v1"
+      strict: false
+      artifact_policy: "keep"
+      note: "CALIBRATION_DECISION_DRAFT_V1 — APPROVE/HOLD/REJECT 초안"
+
     build_operational_alpha_calibration:
       id: build_operational_alpha_calibration
       command: ["python", "tools/build_operational_alpha_calibration_v2.py"]
@@ -496,6 +563,20 @@ dag:
       strict: true
       artifact_policy: "keep"
 
+    validate_no_direct_api_trading:
+      id: validate_no_direct_api_trading
+      command: ["python", "tools/validate_no_direct_api_trading_v1.py"]
+      inputs: ["tools/validate_no_direct_api_trading_v1.py", "src/quant_engine/kis_api_client_v1.py", "governance/rules/06_no_direct_api_trading.yaml"]
+      outputs: []
+      depends_on: []
+      timeout_sec: 30
+      cache_key: "validate_no_direct_api_trading_v1"
+      strict: true
+      artifact_policy: "keep"
+      note: "[CRITICAL] 매수/매도 API 직접 실행 절대 금지 게이트 — warn_only 불가, 완화 대상
+        아님(사용자 직접 지시 2026-06-21). 순수 stdlib만 사용해 Synology ARMv7 CI에서도
+        항상 실행 가능."
+
     validate_active_manifest:
       id: validate_active_manifest
       command: ["python", "tools/validate_active_manifest.py", "--manifest", "runtime/active_artifact_manifest.yaml", "--strict"]
@@ -731,6 +812,37 @@ dag:
       artifact_policy: "keep"
       note: "섹터 유니버스 월간 갱신 provenance 검증 (warn_only) — GAS 재다운로드 시 Source_URL 소실이 정상. 월간 --apply 실행 후 PASS/WARN 달성. FAIL=비차단 경고만."
 
+    build_qualitative_sell_inputs:
+      id: build_qualitative_sell_inputs
+      command: ["python", "tools/build_qualitative_sell_inputs_v1.py", "--batch", "--workbook", "GatherTradingData.xlsx", "--apply"]
+      inputs: ["tools/build_qualitative_sell_inputs_v1.py", "tools/build_macro_context_from_workbook_v1.py", "tools/fetch_naver_market_data_v1.py", "src/quant_engine/kis_api_client_v1.py", "GatherTradingData.xlsx"]
+      outputs: ["outputs/qualitative_sell_strategy/*.json"]
+      depends_on: []
+      timeout_sec: 120
+      cache_key: "build_qualitative_sell_inputs_v1"
+      strict: false
+      warn_only: true
+      artifact_policy: "keep"
+      note: "Naver 시세/수급 실시간 스크래핑 의존(warn_only) — 보유종목별 비기계적 매도전략
+        confluence 판단. 공매도잔고율은 --short-csv 수동 주입 전까지 구조적으로
+        DATA_MISSING(추정 금지) — 정상 동작. 호가10단계·공매도거래비중은 --kis-account
+        {real,mock} 옵션으로 KIS Open API(read-only) 조회 가능(2026-06-21 연동) — DAG
+        기본 실행에는 미포함(자격증명 의존, 수동 실행 시에만 부여)."
+
+    build_satellite_candidate_recommendations:
+      id: build_satellite_candidate_recommendations
+      command: ["python", "tools/build_satellite_candidate_recommendations_v1.py", "--workbook", "GatherTradingData.xlsx", "--apply"]
+      inputs: ["tools/build_satellite_candidate_recommendations_v1.py", "tools/fetch_naver_market_data_v1.py", "GatherTradingData.xlsx"]
+      outputs: ["outputs/qualitative_sell_strategy/satellite_recommendations.json"]
+      depends_on: []
+      timeout_sec: 180
+      cache_key: "build_satellite_candidate_recommendations_v1"
+      strict: false
+      warn_only: true
+      artifact_policy: "keep"
+      note: "universe 시트 미보유 후보(60종) 전체 Naver 시세 조회 — warn_only. --trade-csv
+        없으면 sector_export_trend 전부 DATA_MISSING(정상, 추정 금지)."
+
     validate_cash_ledger:
       id: validate_cash_ledger
       command: ["python", "tools/validate_cash_ledger_v2.py", "--snapshot", "GatherTradingData.json", "--contract", "spec/15_account_snapshot_contract.yaml"]
@@ -1327,7 +1439,7 @@ dag:
       command: ["python", "tools/prepare_upload_zip.py", "--skip-validate", "--skip-convert", "--validation-mode", "package-only"]
       inputs: ["tools/prepare_upload_zip.py"]
       outputs: []
-      depends_on: ["audit_entropy", "validate_specs", "validate_active_manifest", "validate_report_sync", "validate_report_numeric_consistency", "validate_field_dict", "validate_provenance", "validate_low_capability", "validate_golden_coverage", "validate_calibration", "validate_schema_model", "validate_gas_adapter", "validate_agents_shrink", "validate_no_replay_live_mix", "validate_prediction_accuracy_harness", "validate_alpha_feedback_loop", "validate_operational_alpha_calibration", "validate_realized_performance", "validate_data_gated_progress", "validate_sector_flow_history_progress", "validate_runtime_source_whitelist", "validate_cash_ledger", "validate_factor_lifecycle", "validate_factor_lifecycle_completeness", "validate_metric_alias_collision", "validate_architecture_boundaries", "validate_module_io_coverage", "validate_artifact_chain_hash", "validate_artifact_sync", "validate_renderer_no_calc", "validate_packaged_refs", "validate_property_invariants", "validate_anti_late_entry", "validate_rule_lifecycle", "validate_change_requests", "validate_completion_harness_instructions", "validate_engine_health_card", "validate_llm_regression", "validate_llm_copy_only", "build_final_decision", "build_final_context", "build_provenance_ledger", "build_live_replay_separation", "build_late_chase_attribution", "build_profit_giveback_ratchet", "build_shadow_ledger", "build_operating_cadence_signal", "build_engine_health_card", "build_module_io_coverage", "build_artifact_chain_hash", "build_report", "build_bundle", "build_schema_models", "build_architecture_boundaries", "validate_decision_trace", "validate_factor_conflicts", "validate_no_lookahead", "validate_execution_sim", "validate_render_diff", "build_shadow_promotion", "validate_llm_determinism", "build_time_stop_forecast", "validate_live_activation", "build_rebalance_sheet", "build_prediction_accuracy_harness", "build_alpha_feedback_loop", "build_operational_alpha_calibration", "build_sector_flow_history_progress"]
+      depends_on: ["audit_entropy", "validate_specs", "validate_no_direct_api_trading", "validate_active_manifest", "validate_report_sync", "validate_report_numeric_consistency", "validate_field_dict", "validate_provenance", "validate_low_capability", "validate_golden_coverage", "validate_calibration", "validate_schema_model", "validate_gas_adapter", "validate_agents_shrink", "validate_no_replay_live_mix", "validate_prediction_accuracy_harness", "validate_alpha_feedback_loop", "validate_operational_alpha_calibration", "validate_realized_performance", "validate_data_gated_progress", "validate_sector_flow_history_progress", "validate_runtime_source_whitelist", "validate_cash_ledger", "validate_factor_lifecycle", "validate_factor_lifecycle_completeness", "validate_metric_alias_collision", "validate_architecture_boundaries", "validate_module_io_coverage", "validate_artifact_chain_hash", "validate_artifact_sync", "validate_renderer_no_calc", "validate_packaged_refs", "validate_property_invariants", "validate_anti_late_entry", "validate_rule_lifecycle", "validate_change_requests", "validate_completion_harness_instructions", "validate_engine_health_card", "validate_llm_regression", "validate_llm_copy_only", "build_final_decision", "build_final_context", "build_provenance_ledger", "build_live_replay_separation", "build_late_chase_attribution", "build_profit_giveback_ratchet", "build_shadow_ledger", "build_operating_cadence_signal", "build_engine_health_card", "build_module_io_coverage", "build_artifact_chain_hash", "build_report", "build_bundle", "build_schema_models", "build_architecture_boundaries", "validate_decision_trace", "validate_factor_conflicts", "validate_no_lookahead", "validate_execution_sim", "validate_render_diff", "build_shadow_promotion", "validate_llm_determinism", "build_time_stop_forecast", "validate_live_activation", "build_rebalance_sheet", "build_prediction_accuracy_harness", "build_alpha_feedback_loop", "build_calibration_priority", "build_calibration_change_ledger", "build_calibration_review_report", "build_calibration_approval_list", "build_calibration_decision_draft", "build_operational_alpha_calibration", "build_sector_flow_history_progress"]
       timeout_sec: 60
       cache_key: "prepare_zip_v1"
       strict: true
diff --git a/spec/55_execution_simulator_contract.yaml b/spec/55_execution_simulator_contract.yaml
index 7592f6cd..482dc6fb 100644
--- a/spec/55_execution_simulator_contract.yaml
+++ b/spec/55_execution_simulator_contract.yaml
@@ -2,6 +2,8 @@ schema_version: execution_simulator_contract.v1
 contract_id: H004_EXECUTION_SIMULATOR
 harness_file: tools/validate_execution_simulator_v1.py
 authority: spec/55_execution_simulator_contract.yaml
+has_code_implementation: true
+code_path: "tools/validate_execution_simulator_v1.py"
 created_at: '2026-06-10T23:29:00+09:00'
 purpose: >
   틱 정규화, 최소주문수량, 예수금, D+2 현금, 슬리피지 적용 후
diff --git a/spec/aliases.yaml b/spec/aliases.yaml
index d301216a..1d7fc877 100644
--- a/spec/aliases.yaml
+++ b/spec/aliases.yaml
@@ -1,80 +1,26 @@
 meta:
   title: "은퇴자산포트폴리오 — 경로 alias registry"
-  version: "2026-05-15-F10_fragmentation_guard"
+  version: "2026-06-21-WBS7.4_migration_closed"
   role: "governance"
   purpose: "legacy path와 canonical split path를 명시해 참조 혼선을 방지한다."
 
-aliases:
-  "spec/03_risk_policy.yaml:portfolio_exposure_framework":
-    canonical: "spec/risk/portfolio_exposure.yaml:portfolio_exposure_framework"
-    status: "deprecated"
-    remove_after: "2026-06-30"
-  "spec/03_risk_policy.yaml:risk_control":
-    canonical: "spec/risk/aggregate_risk.yaml:risk_control"
-    status: "deprecated"
-    remove_after: "2026-06-30"
-  "spec/risk/risk_control.yaml:risk_control.aggregate_risk_cap":
-    canonical: "spec/risk/aggregate_risk.yaml:risk_control.aggregate_risk_cap"
-    status: "deprecated"
-    remove_after: "2026-06-30"
-  "spec/risk/risk_control.yaml:risk_control.market_risk_score_based_cash":
-    canonical: "spec/risk/market_risk_cash.yaml:risk_control.market_risk_score_based_cash"
-    status: "deprecated"
-    remove_after: "2026-06-30"
-  "spec/risk/risk_control.yaml:risk_control.weekly_circuit_breaker":
-    canonical: "spec/risk/circuit_breakers.yaml:risk_control.weekly_circuit_breaker"
-    status: "deprecated"
-    remove_after: "2026-06-30"
-  "spec/06_exit_policy.yaml:stop_loss":
-    canonical: "spec/exit/stop_loss.yaml:stop_loss"
-    status: "deprecated"
-    remove_after: "2026-06-30"
-  "spec/06_exit_policy.yaml:take_profit":
-    canonical: "spec/exit/take_profit.yaml:take_profit"
-    status: "deprecated"
-    remove_after: "2026-06-30"
-  "spec/03_risk_policy.yaml:quality_control":
-    canonical: "spec/risk/quality_control.yaml:quality_control"
-    status: "deprecated"
-    remove_after: "2026-06-30"
-  "spec/04_strategy_rules.yaml:sector_model":
-    canonical: "spec/strategy/sector_model.yaml:sector_model"
-    status: "deprecated"
-    remove_after: "2026-06-30"
-  "spec/04_strategy_rules.yaml:entry_timing_guardrails":
-    canonical: "spec/strategy/entry_core.yaml:entry_timing_guardrails"
-    status: "deprecated"
-    remove_after: "2026-06-30"
-  "spec/04_strategy_rules.yaml:anti_late_trade_rule":
-    canonical: "spec/strategy/discovery.yaml:anti_late_trade_rule"
-    status: "deprecated"
-    remove_after: "2026-06-30"
-  "spec/strategy/entry_gates.yaml:entry_timing_guardrails.daily_leader_scan":
-    canonical: "spec/strategy/leader_scan.yaml:entry_timing_guardrails.daily_leader_scan"
-    status: "deprecated"
-    remove_after: "2026-06-30"
-  "spec/strategy/entry_gates.yaml:entry_timing_guardrails.anti_climax_buy_gate":
-    canonical: "spec/strategy/leader_scan.yaml:entry_timing_guardrails.anti_climax_buy_gate"
-    status: "deprecated"
-    remove_after: "2026-06-30"
-  "spec/strategy/entry_gates.yaml:entry_timing_guardrails.staged_entry_v2":
-    canonical: "spec/strategy/staged_entry.yaml:entry_timing_guardrails.staged_entry_v2"
-    status: "deprecated"
-    remove_after: "2026-06-30"
-  "spec/strategy/entry_gates.yaml:entry_timing_guardrails.pullback_reentry_rule":
-    canonical: "spec/strategy/staged_entry.yaml:entry_timing_guardrails.pullback_reentry_rule"
-    status: "deprecated"
-    remove_after: "2026-06-30"
-  "spec/04_strategy_rules.yaml:stock_model":
-    canonical: "spec/strategy/stock_model.yaml:stock_model"
-    status: "deprecated"
-    remove_after: "2026-06-30"
-  "spec/04_strategy_rules.yaml:rebalancing_trigger":
-    canonical: "spec/strategy/rebalancing_trigger.yaml:rebalancing_trigger"
-    status: "deprecated"
-    remove_after: "2026-06-30"
+# 2026-06-21 WBS-7.4 마이그레이션 종결 기록:
+# 아래 17개 alias는 모두 remove_after=2026-06-30 만료 예정이었다.
+# repo 전체(spec/src/tools/prompts/examples) grep으로 활성 참조가 0건임을 확인했고,
+# 모든 canonical_split_files 대상 파일이 이미 실콘텐츠를 보유하고 있어 마이그레이션이
+# 완료된 것으로 판정, 데드라인 전에 alias 항목을 제거했다.
+#
+# [2026-06-22 WBS-7.11 정정] 작성 당시 이 주석은 호환 인덱스 5개 중 "3개가
+# deprecated_redirect라 삭제 보류 중"이라고 적었으나 부정확했다. 실제로는
+# spec/06_exit_policy.yaml도 role: compatibility_index(영구 유지 설계)였고,
+# role: deprecated_redirect는 spec/03_risk_policy.yaml, spec/04_strategy_rules.yaml
+# 2개뿐이었다. WBS-7.11에서 이 2개의 활성 참조 0건을 재확인 후 실삭제했고,
+# spec/06_exit_policy.yaml/spec/risk/risk_control.yaml/spec/strategy/entry_gates.yaml
+# 3개는 has_code_implementation:false + redirect_only:true로 태깅해 영구 유지한다.
+aliases: {}
 
 policy:
   - "신규 문서는 canonical 경로만 사용한다."
   - "compatibility index와 aliases.yaml 내부의 deprecated 경로는 허용한다."
   - "remove_after 이후 deprecated 경로가 active 문서에 남으면 검증 실패로 전환한다."
+  - "alias 항목을 등록할 때는 반드시 remove_after 데드라인을 두고, 데드라인 전에 활성 참조 0건을 확인한 뒤 제거한다(2026-06-21 사례 참조)."
diff --git a/spec/ownership_map.yaml b/spec/ownership_map.yaml
index 2ee4d4f9..1ec6466b 100644
--- a/spec/ownership_map.yaml
+++ b/spec/ownership_map.yaml
@@ -82,16 +82,9 @@ ownership_map:
     must_not_own: ["투자 규칙 수치"]
 
   # ── 호환 인덱스 (redirect-only, 실제 규칙은 canonical_split_files 참조) ──
-  "spec/03_risk_policy.yaml":
-    role: "compatibility_index"
-    owns: ["legacy path alias for spec/risk/*.yaml"]
-    must_not_own: ["수치 임계값", "새 리스크 규칙"]
-    canonical_files: ["spec/risk/portfolio_exposure.yaml", "spec/risk/risk_control.yaml", "spec/risk/quality_control.yaml"]
-  "spec/04_strategy_rules.yaml":
-    role: "compatibility_index"
-    owns: ["legacy path alias for spec/strategy/*.yaml"]
-    must_not_own: ["수치 임계값", "새 전략 규칙"]
-    canonical_files: ["spec/strategy/sector_model.yaml", "spec/strategy/entry_gates.yaml", "spec/strategy/stock_model.yaml", "spec/strategy/rebalancing_trigger.yaml"]
+  # 2026-06-22 WBS-7.11: spec/03_risk_policy.yaml, spec/04_strategy_rules.yaml은
+  # role: deprecated_redirect(영구 유지가 아닌 완전 폐기 대상)였으며 활성 참조 0건을
+  # 확인 후 실삭제했다. 캐노니컬 split 파일들은 영향 없이 그대로 유지된다.
   "spec/06_exit_policy.yaml":
     role: "compatibility_index"
     owns: ["legacy path alias for spec/exit/*.yaml"]
diff --git a/spec/risk/README.md b/spec/risk/README.md
index 39ccf558..74f1788b 100644
--- a/spec/risk/README.md
+++ b/spec/risk/README.md
@@ -1,6 +1,7 @@
 # Risk Spec Split Plan
 
-`spec/03_risk_policy.yaml` is now a compatibility index.
+`spec/03_risk_policy.yaml` was a deprecated_redirect-only stub and has been deleted
+(2026-06-22, WBS-7.11 — zero active references confirmed before removal).
 The canonical risk rules are the split files in this directory.
 
 Canonical split files:
@@ -14,7 +15,7 @@ Canonical split files:
 
 Migration rule:
 
-- Do not add numeric thresholds to `spec/03_risk_policy.yaml` or `spec/risk/risk_control.yaml`.
+- Do not add numeric thresholds to `spec/risk/risk_control.yaml` (compatibility index only).
 - Keep old paths valid only through compatibility indexes and `spec/aliases.yaml`.
 - New documents must reference canonical split files directly.
 - `spec/00_execution_contract.yaml` remains higher authority than all risk split files.
diff --git a/spec/risk/factor_risk.yaml b/spec/risk/factor_risk.yaml
index 718cd49a..cdab1523 100644
--- a/spec/risk/factor_risk.yaml
+++ b/spec/risk/factor_risk.yaml
@@ -1,6 +1,6 @@
 meta:
   title: "은퇴자산포트폴리오 — 포트폴리오 노출·현금 정책 분할 후보"
-  parent_file: "spec/03_risk_policy.yaml"
+  parent_file: "RetirementAssetPortfolio.yaml"  # 2026-06-22 WBS-7.11: spec/03_risk_policy.yaml 삭제로 갱신
   version: "2026-05-16-F9_secular_leader"
   language: "ko-KR"
   timezone: "Asia/Seoul"
diff --git a/spec/risk/portfolio_exposure.yaml b/spec/risk/portfolio_exposure.yaml
index e03b0927..746f64eb 100644
--- a/spec/risk/portfolio_exposure.yaml
+++ b/spec/risk/portfolio_exposure.yaml
@@ -1,6 +1,6 @@
 meta:
   title: "은퇴자산포트폴리오 — 포트폴리오 노출·현금 정책 분할 후보"
-  parent_file: "spec/03_risk_policy.yaml"
+  parent_file: "RetirementAssetPortfolio.yaml"  # 2026-06-22 WBS-7.11: spec/03_risk_policy.yaml 삭제로 갱신
   version: "2026-05-18-F10_score_clamp_d2_fix"
   language: "ko-KR"
   timezone: "Asia/Seoul"
diff --git a/spec/risk/quality_control.yaml b/spec/risk/quality_control.yaml
index da5982d0..c782ad1c 100644
--- a/spec/risk/quality_control.yaml
+++ b/spec/risk/quality_control.yaml
@@ -1,6 +1,6 @@
 meta:
   title: "은퇴자산포트폴리오 — 리스크 품질관리 분할 후보"
-  parent_file: "spec/03_risk_policy.yaml"
+  parent_file: "RetirementAssetPortfolio.yaml"  # 2026-06-22 WBS-7.11: spec/03_risk_policy.yaml 삭제로 갱신
   version: "2026-05-15-F8_split"
   language: "ko-KR"
   timezone: "Asia/Seoul"
diff --git a/spec/risk/risk_control.yaml b/spec/risk/risk_control.yaml
index 687246ab..c68e347a 100644
--- a/spec/risk/risk_control.yaml
+++ b/spec/risk/risk_control.yaml
@@ -1,10 +1,12 @@
 meta:
   title: "은퇴자산포트폴리오 — 리스크 제어 호환 인덱스"
-  parent_file: "spec/03_risk_policy.yaml"
+  parent_file: "RetirementAssetPortfolio.yaml"  # 2026-06-22 WBS-7.11: spec/03_risk_policy.yaml 삭제로 갱신
   version: "2026-05-15-F12_index_only"
   language: "ko-KR"
   timezone: "Asia/Seoul"
   role: "compatibility_index"
+  has_code_implementation: false
+  redirect_only: true
   purpose: "기존 risk_control 경로를 보존하기 위한 인덱스 파일."
 
 canonical_split_files:
diff --git a/spec/strategy/README.md b/spec/strategy/README.md
index 72059201..64281212 100644
--- a/spec/strategy/README.md
+++ b/spec/strategy/README.md
@@ -1,6 +1,7 @@
 # Strategy Spec Split Plan
 
-`spec/04_strategy_rules.yaml` is now a compatibility index.
+`spec/04_strategy_rules.yaml` was a deprecated_redirect-only stub and has been deleted
+(2026-06-22, WBS-7.11 — zero active references confirmed before removal).
 The canonical strategy rules are the split files in this directory.
 
 Canonical split files:
@@ -17,5 +18,5 @@ Canonical split files:
 Migration rule:
 
 - Do not duplicate thresholds without `canonical_ref`.
-- Keep old paths valid through `spec/04_strategy_rules.yaml.legacy_path_aliases`.
+- Keep old paths valid through `spec/strategy/entry_gates.yaml.legacy_path_aliases` (compatibility index only).
 - `spec/09_decision_flow.yaml` controls execution order; strategy split files only define domain logic.
diff --git a/spec/strategy/entry_gates.yaml b/spec/strategy/entry_gates.yaml
index 80dccef8..14d69dd3 100644
--- a/spec/strategy/entry_gates.yaml
+++ b/spec/strategy/entry_gates.yaml
@@ -1,10 +1,12 @@
 meta:
   title: "은퇴자산포트폴리오 — 진입 게이트 호환 인덱스"
-  parent_file: "spec/04_strategy_rules.yaml"
+  parent_file: "RetirementAssetPortfolio.yaml"  # 2026-06-22 WBS-7.11: spec/04_strategy_rules.yaml 삭제로 갱신
   version: "2026-05-15-F11_index_only"
   language: "ko-KR"
   timezone: "Asia/Seoul"
   role: "compatibility_index"
+  has_code_implementation: false
+  redirect_only: true
   purpose: >
     기존 spec/strategy/entry_gates.yaml 경로를 보존하기 위한 인덱스 파일.
     실제 진입 규칙은 세부 split 파일을 canonical로 사용한다.
diff --git a/spec/strategy/rebalancing_trigger.yaml b/spec/strategy/rebalancing_trigger.yaml
index f0d04a74..fd969851 100644
--- a/spec/strategy/rebalancing_trigger.yaml
+++ b/spec/strategy/rebalancing_trigger.yaml
@@ -1,6 +1,6 @@
 meta:
   title: "은퇴자산포트폴리오 — 리밸런싱 트리거 분할 후보"
-  parent_file: "spec/04_strategy_rules.yaml"
+  parent_file: "RetirementAssetPortfolio.yaml"  # 2026-06-22 WBS-7.11: spec/04_strategy_rules.yaml 삭제로 갱신
   version: "2026-05-15-F8_split"
   language: "ko-KR"
   timezone: "Asia/Seoul"
diff --git a/spec/strategy/sector_model.yaml b/spec/strategy/sector_model.yaml
index 26f8b012..4730388f 100644
--- a/spec/strategy/sector_model.yaml
+++ b/spec/strategy/sector_model.yaml
@@ -1,6 +1,6 @@
 meta:
   title: "은퇴자산포트폴리오 — 섹터 모델 분할 후보"
-  parent_file: "spec/04_strategy_rules.yaml"
+  parent_file: "RetirementAssetPortfolio.yaml"  # 2026-06-22 WBS-7.11: spec/04_strategy_rules.yaml 삭제로 갱신
   version: "2026-05-15-F8_split"
   language: "ko-KR"
   timezone: "Asia/Seoul"
diff --git a/spec/strategy/stock_model.yaml b/spec/strategy/stock_model.yaml
index 71668881..5b22258b 100644
--- a/spec/strategy/stock_model.yaml
+++ b/spec/strategy/stock_model.yaml
@@ -1,6 +1,6 @@
 meta:
   title: "은퇴자산포트폴리오 — 종목 모델 분할 후보"
-  parent_file: "spec/04_strategy_rules.yaml"
+  parent_file: "RetirementAssetPortfolio.yaml"  # 2026-06-22 WBS-7.11: spec/04_strategy_rules.yaml 삭제로 갱신
   version: "2026-05-16-F10_peg_gate"
   language: "ko-KR"
   timezone: "Asia/Seoul"
diff --git a/tests/unit/test_validate_spec_code_sync_v1.py b/tests/unit/test_validate_spec_code_sync_v1.py
new file mode 100644
index 00000000..b9e259ea
--- /dev/null
+++ b/tests/unit/test_validate_spec_code_sync_v1.py
@@ -0,0 +1,69 @@
+"""WBS-7.11(2026-06-22) — spec-코드 동기화 게이트 단위 테스트."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+import tools.validate_specs as vs
+
+
+def test_real_repo_has_no_missing_code_path():
+    """현재 저장소 상태에서 1차 태깅된 파일들은 모두 code_path가 실존해야 한다."""
+    errors: list[str] = []
+    result = vs.validate_spec_code_sync(errors)
+    assert result["gate"] == "PASS"
+    assert result["missing_code_path_count"] == 0
+    assert result["checked_count"] >= 10
+    assert not errors
+
+
+def test_missing_code_path_fails(tmp_path, monkeypatch):
+    (tmp_path / "spec").mkdir()
+    (tmp_path / "governance").mkdir()
+    (tmp_path / "spec" / "fake_contract.yaml").write_text(
+        "meta:\n  has_code_implementation: true\n  code_path: \"tools/does_not_exist_v1.py\"\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(vs, "ROOT", tmp_path)
+
+    errors: list[str] = []
+    result = vs.validate_spec_code_sync(errors)
+    assert result["gate"] == "FAIL"
+    assert result["missing_code_path_count"] == 1
+    assert any("does_not_exist_v1.py" in e for e in errors)
+
+
+def test_redirect_only_and_has_code_is_contradiction(tmp_path, monkeypatch):
+    (tmp_path / "spec").mkdir()
+    (tmp_path / "governance").mkdir()
+    (tmp_path / "spec" / "contradiction.yaml").write_text(
+        "meta:\n  has_code_implementation: true\n  redirect_only: true\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(vs, "ROOT", tmp_path)
+
+    errors: list[str] = []
+    result = vs.validate_spec_code_sync(errors)
+    assert result["gate"] == "FAIL"
+    assert any("contradiction" in e for e in errors)
+
+
+def test_files_without_the_field_are_skipped_not_failed(tmp_path, monkeypatch):
+    (tmp_path / "spec").mkdir()
+    (tmp_path / "governance").mkdir()
+    (tmp_path / "spec" / "untouched.yaml").write_text(
+        "meta:\n  title: legacy doc with no sync field\n",
+        encoding="utf-8",
+    )
+    monkeypatch.setattr(vs, "ROOT", tmp_path)
+
+    errors: list[str] = []
+    result = vs.validate_spec_code_sync(errors)
+    assert result["gate"] == "PASS"
+    assert result["checked_count"] == 0
+    assert result["total_spec_files"] == 1
+    assert not errors
diff --git a/tools/validate_specs.py b/tools/validate_specs.py
index e3d81010..3d27deaa 100644
--- a/tools/validate_specs.py
+++ b/tools/validate_specs.py
@@ -117,6 +117,10 @@ def validate_formula_registry(errors: list[str]) -> None:
         "ALPHA_FEEDBACK_LOOP_V2", "ALPHA_LEAD_THRESHOLD_OPTIMIZER_V1",
         # ENGINE_AUDIT — Python-tool-only 감사 게이트 (GAS 런타임 비개입)
         "IMPUTED_DATA_EXPOSURE_GATE_V1",
+        # Phase-8 비기계적 매도전략 — confluence 기반 판단 게이트 (output_contract 구조)
+        "SHORT_INTEREST_RISK_GAUGE_V1", "QUALITATIVE_SELL_STRATEGY_V1",
+        "MARKET_REGIME_CLASSIFIER_V1", "SATELLITE_CANDIDATE_SCORE_V1",
+        "MICROSTRUCTURE_PRESSURE_FROM_ORDERBOOK_V1",
     }
     for formula_id, formula in all_formulas.items():
         if not isinstance(formula, dict):
@@ -619,6 +623,62 @@ def validate_harness_contract_consistency(errors: list[str]) -> None:
             fail(errors, f"harness_contract collection_key not checked in validator: {key}")
 
 
+def validate_spec_code_sync(errors: list[str]) -> dict:
+    """WBS-7.11(2026-06-22) — spec YAML이 code_path로 가리키는 파일이 실제로 존재하는지 검사.
+
+    has_code_implementation 필드가 있는 파일만 검사한다(점진적 롤아웃 — 필드가 없는
+    파일은 스킵되므로 1차 태깅이 기존 PASS 상태를 절대 깨지 않는다). redirect_only:true인
+    파일은 의도적으로 코드가 없는 순수 호환 인덱스이므로 code_path 검사 대상이 아니며,
+    has_code_implementation:true와 동시에 있으면 그 자체로 모순이라 fail한다.
+    """
+    all_yaml_paths = sorted((ROOT / "spec").rglob("*.yaml")) + sorted((ROOT / "governance").rglob("*.yaml"))
+    total_files = len(all_yaml_paths)
+    checked = 0
+    missing = 0
+    for path in all_yaml_paths:
+        try:
+            data = yaml.safe_load(path.read_text(encoding="utf-8"))
+        except Exception:
+            continue
+        if not isinstance(data, dict):
+            continue
+        meta = data.get("meta") if isinstance(data.get("meta"), dict) else data
+        has_code = meta.get("has_code_implementation")
+        if has_code is None:
+            continue
+        redirect_only = bool(meta.get("redirect_only"))
+        checked += 1
+        if redirect_only and has_code:
+            fail(errors, f"spec_code_sync contradiction: {path} has redirect_only=true AND has_code_implementation=true")
+            missing += 1
+            continue
+        if not has_code:
+            continue
+        code_path = meta.get("code_path")
+        candidates = code_path if isinstance(code_path, list) else [code_path] if code_path else []
+        if not candidates:
+            fail(errors, f"spec_code_sync: {path} declares has_code_implementation=true but no code_path")
+            missing += 1
+            continue
+        for rel in candidates:
+            if not (ROOT / str(rel)).exists():
+                fail(errors, f"spec declares code_path that does not exist: {path} -> {rel}")
+                missing += 1
+
+    result = {
+        "formula_id": "SPEC_CODE_SYNC_V1",
+        "total_spec_files": total_files,
+        "checked_count": checked,
+        "missing_code_path_count": missing,
+        "sync_field_coverage_pct": round(100.0 * checked / total_files, 2) if total_files else 0.0,
+        "gate": "PASS" if missing == 0 else "FAIL",
+    }
+    out = ROOT / "Temp" / "spec_code_sync_v1.json"
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
+    return result
+
+
 def main() -> int:
     errors: list[str] = []
 
@@ -660,10 +720,9 @@ def main() -> int:
     manifest_text = (ROOT / "RetirementAssetPortfolio.yaml").read_text(encoding="utf-8")
     for path in sorted((ROOT / "spec").rglob("*.yaml")):
         rel = path.relative_to(ROOT).as_posix()
-        if rel not in manifest_text and rel not in {"spec/03_risk_policy.yaml", "spec/04_strategy_rules.yaml"}:
+        if rel not in manifest_text:
             fail(errors, f"spec file not registered in manifest: {rel}")
         if path.stat().st_size > MAX_SPEC_BYTES and path.name not in {
-            "03_risk_policy.yaml", "04_strategy_rules.yaml",
             "13_formula_registry.yaml", "13b_harness_formulas.yaml",
             "12_field_dictionary.yaml",
             "51_formula_lifecycle_registry.yaml",  # 290+ formula lifecycle registry (Proposal51-P1)
@@ -770,13 +829,12 @@ def main() -> int:
     validate_formula_registry(errors)
     validate_output_rendering_contract(schema, errors)
     validate_harness_contract_consistency(errors)
+    validate_spec_code_sync(errors)
 
     aliases = load_yaml(ROOT / "spec" / "aliases.yaml", errors) or {}
     alias_map = aliases.get("aliases") or {}
     alias_files = {
         ROOT / "spec" / "aliases.yaml",
-        ROOT / "spec" / "03_risk_policy.yaml",
-        ROOT / "spec" / "04_strategy_rules.yaml",
         ROOT / "spec" / "06_exit_policy.yaml",
         ROOT / "spec" / "risk" / "risk_control.yaml",
         ROOT / "spec" / "strategy" / "entry_gates.yaml",

From 449721433becaf9252f2e6a17c5fefdc966ffa81 Mon Sep 17 00:00:00 2001
From: kjh2064 
Date: Sun, 21 Jun 2026 20:09:16 +0900
Subject: [PATCH 06/10] =?UTF-8?q?WBS-7.6:=20=EC=8A=AC=EB=A6=AC=ED=94=BC?=
 =?UTF-8?q?=EC=A7=80=20=EC=8B=A4=EC=B8=A1=20=EC=BA=A1=EC=B2=98=20=EC=8A=A4?=
 =?UTF-8?q?=EC=BA=90=ED=8F=B4=EB=94=A9?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

spec/55_execution_simulator_contract.yaml의 5bps 슬리피지 가정치를
검증할 실측 캡처 경로가 없었다. 주문 실행은 여전히 사람이 HTS에서
직접 한다(governance/rules/06 준수, API로 체결을 가져오지 않음) —
실행 후 사람이 의도가/실제체결가를 수동 기록하면 SQLite에 누적되고,
5건 미만이면 항상 DATA_GATED를 정직하게 반환한다(추정 금지).
---
 .../execution_slippage_store_v1.py            | 144 ++++++++++++++++++
 .../unit/test_execution_slippage_store_v1.py  |  90 +++++++++++
 tools/evaluate_execution_slippage_v1.py       |  75 +++++++++
 3 files changed, 309 insertions(+)
 create mode 100644 src/quant_engine/execution_slippage_store_v1.py
 create mode 100644 tests/unit/test_execution_slippage_store_v1.py
 create mode 100644 tools/evaluate_execution_slippage_v1.py

diff --git a/src/quant_engine/execution_slippage_store_v1.py b/src/quant_engine/execution_slippage_store_v1.py
new file mode 100644
index 00000000..07fe088c
--- /dev/null
+++ b/src/quant_engine/execution_slippage_store_v1.py
@@ -0,0 +1,144 @@
+"""WBS-7.6(2026-06-21) — 실거래 슬리피지 실측 캡처 스캐폴딩.
+
+spec/55_execution_simulator_contract.yaml의 slippage_model(bps=5)은 이론치이며
+"추후 실측 데이터로 보정 예정"이라는 메모만 있고 실제 캡처 경로가 없었다. 이 모듈은
+주문은 사람이 HTS에서 직접 실행한다는 governance/rules/06 원칙을 그대로 유지한 채
+(API로 체결을 가져오지 않는다), 실행 후 사람이 수동으로 기록한 실제 체결가를
+누적해 가정치(5bps)와 비교할 수 있게 한다. 5건 미만이면 항상 DATA_GATED로 보고한다
+— 추정 금지 원칙(spec/00_execution_contract.yaml)을 따른다. 표준 라이브러리
+sqlite3만 사용한다.
+"""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+from typing import Any
+
+from src.quant_engine.storage_backend_v1 import StoreSpec, default_sqlite_store_path, normalize_store_spec
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS realized_slippage_samples (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    ticker TEXT NOT NULL,
+    side TEXT NOT NULL CHECK (side IN ('BUY', 'SELL')),
+    intended_price REAL NOT NULL,
+    actual_fill_price REAL NOT NULL,
+    slippage_bps_actual REAL NOT NULL,
+    recorded_at TEXT NOT NULL,
+    note TEXT,
+    inserted_at TEXT DEFAULT (datetime('now'))
+);
+"""
+
+ASSUMED_SLIPPAGE_BPS = 5.0
+MIN_SAMPLE_FOR_COMPARISON = 5
+
+
+def default_execution_slippage_store_path(root: Path) -> Path:
+    return default_sqlite_store_path(root, "execution_slippage/execution_slippage.db")
+
+
+def resolve_store_path(spec: StoreSpec, root: Path) -> Path:
+    backend, location = normalize_store_spec(
+        spec, root, default_sqlite_name="execution_slippage/execution_slippage.db"
+    )
+    if backend != "sqlite":
+        raise ValueError("execution_slippage_store_v1 currently executes on sqlite only.")
+    return Path(location)
+
+
+def init_db(db_path: Path) -> None:
+    db_path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(db_path)
+    try:
+        conn.executescript(SCHEMA)
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def _compute_slippage_bps(intended_price: float, actual_fill_price: float, side: str) -> float:
+    """체결가가 의도가(지정가)보다 불리한 방향으로 움직인 만큼을 양수 bps로 환산한다.
+
+    BUY: 실제 체결가가 의도가보다 높으면(더 비싸게 샀으면) 양수 슬리피지.
+    SELL: 실제 체결가가 의도가보다 낮으면(더 싸게 팔았으면) 양수 슬리피지.
+    """
+    if intended_price <= 0:
+        raise ValueError("intended_price must be > 0")
+    direction = 1 if side.upper() == "BUY" else -1
+    return direction * (actual_fill_price - intended_price) / intended_price * 10_000.0
+
+
+def insert_realized_slippage_sample(
+    db_path: Path,
+    *,
+    ticker: str,
+    side: str,
+    intended_price: float,
+    actual_fill_price: float,
+    recorded_at: str,
+    note: str | None = None,
+) -> dict[str, Any]:
+    init_db(db_path)
+    slippage_bps = _compute_slippage_bps(intended_price, actual_fill_price, side)
+    conn = sqlite3.connect(db_path)
+    try:
+        conn.execute(
+            "INSERT INTO realized_slippage_samples "
+            "(ticker, side, intended_price, actual_fill_price, slippage_bps_actual, recorded_at, note) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?)",
+            (ticker, side.upper(), intended_price, actual_fill_price, slippage_bps, recorded_at, note),
+        )
+        conn.commit()
+    finally:
+        conn.close()
+    return {
+        "ticker": ticker,
+        "side": side.upper(),
+        "intended_price": intended_price,
+        "actual_fill_price": actual_fill_price,
+        "slippage_bps_actual": round(slippage_bps, 4),
+        "recorded_at": recorded_at,
+    }
+
+
+def fetch_all_samples(db_path: Path) -> list[dict[str, Any]]:
+    if not db_path.exists():
+        return []
+    conn = sqlite3.connect(db_path)
+    conn.row_factory = sqlite3.Row
+    try:
+        rows = conn.execute(
+            "SELECT ticker, side, intended_price, actual_fill_price, slippage_bps_actual, recorded_at, note "
+            "FROM realized_slippage_samples ORDER BY recorded_at ASC"
+        ).fetchall()
+        return [dict(row) for row in rows]
+    finally:
+        conn.close()
+
+
+def build_slippage_comparison_report(db_path: Path) -> dict[str, Any]:
+    """WBS-7.6 성공 하네스 — 5건 미만이면 DATA_GATED를 정직하게 반환한다(추정 금지)."""
+    samples = fetch_all_samples(db_path)
+    sample_n = len(samples)
+    if sample_n < MIN_SAMPLE_FOR_COMPARISON:
+        return {
+            "status": "DATA_GATED",
+            "sample_n": sample_n,
+            "min_required": MIN_SAMPLE_FOR_COMPARISON,
+            "assumed_slippage_bps": ASSUMED_SLIPPAGE_BPS,
+            "actual_mean_slippage_bps": None,
+            "note": f"실측 표본 {sample_n}/{MIN_SAMPLE_FOR_COMPARISON}건 — 비교 불가, 가정치(5bps) 유지",
+        }
+    actual_mean = sum(s["slippage_bps_actual"] for s in samples) / sample_n
+    gap = abs(actual_mean - ASSUMED_SLIPPAGE_BPS)
+    return {
+        "status": "OK",
+        "sample_n": sample_n,
+        "assumed_slippage_bps": ASSUMED_SLIPPAGE_BPS,
+        "actual_mean_slippage_bps": round(actual_mean, 4),
+        "gap_bps": round(gap, 4),
+        "recommendation": (
+            "가정치(5bps) 유지" if gap <= 3.0 else "spec/55_execution_simulator_contract.yaml의 bps 값을 실측 평균으로 갱신 검토"
+        ),
+    }
diff --git a/tests/unit/test_execution_slippage_store_v1.py b/tests/unit/test_execution_slippage_store_v1.py
new file mode 100644
index 00000000..26b08f5d
--- /dev/null
+++ b/tests/unit/test_execution_slippage_store_v1.py
@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.quant_engine.execution_slippage_store_v1 import (
+    ASSUMED_SLIPPAGE_BPS,
+    MIN_SAMPLE_FOR_COMPARISON,
+    build_slippage_comparison_report,
+    fetch_all_samples,
+    insert_realized_slippage_sample,
+)
+
+
+def test_report_is_data_gated_below_minimum_sample(tmp_path):
+    db_path = tmp_path / "execution_slippage.db"
+    report = build_slippage_comparison_report(db_path)
+    assert report["status"] == "DATA_GATED"
+    assert report["sample_n"] == 0
+    assert report["actual_mean_slippage_bps"] is None
+
+
+def test_buy_slippage_sign_is_positive_when_filled_worse(tmp_path):
+    db_path = tmp_path / "execution_slippage.db"
+    result = insert_realized_slippage_sample(
+        db_path,
+        ticker="005930",
+        side="buy",
+        intended_price=70000,
+        actual_fill_price=70070,
+        recorded_at="2026-06-21",
+    )
+    # BUY 체결가가 의도가보다 비싸게 체결됐으면 양수 슬리피지(불리)
+    assert result["slippage_bps_actual"] > 0
+    assert abs(result["slippage_bps_actual"] - 10.0) < 1e-6  # 70/70000 = 10bps
+
+
+def test_sell_slippage_sign_is_positive_when_filled_worse(tmp_path):
+    db_path = tmp_path / "execution_slippage.db"
+    result = insert_realized_slippage_sample(
+        db_path,
+        ticker="000660",
+        side="SELL",
+        intended_price=200000,
+        actual_fill_price=199900,
+        recorded_at="2026-06-21",
+    )
+    # SELL 체결가가 의도가보다 싸게 체결됐으면 양수 슬리피지(불리)
+    assert result["slippage_bps_actual"] > 0
+
+
+def test_report_compares_against_assumed_bps_once_min_sample_reached(tmp_path):
+    db_path = tmp_path / "execution_slippage.db"
+    for i in range(MIN_SAMPLE_FOR_COMPARISON):
+        insert_realized_slippage_sample(
+            db_path,
+            ticker="005930",
+            side="BUY",
+            intended_price=70000,
+            actual_fill_price=70070,  # 항상 10bps 불리하게 체결
+            recorded_at=f"2026-06-{21 + i}",
+        )
+
+    samples = fetch_all_samples(db_path)
+    assert len(samples) == MIN_SAMPLE_FOR_COMPARISON
+
+    report = build_slippage_comparison_report(db_path)
+    assert report["status"] == "OK"
+    assert abs(report["actual_mean_slippage_bps"] - 10.0) < 1e-6
+    assert abs(report["gap_bps"] - abs(10.0 - ASSUMED_SLIPPAGE_BPS)) < 1e-6
+    assert report["recommendation"]
+
+
+def test_intended_price_must_be_positive(tmp_path):
+    db_path = tmp_path / "execution_slippage.db"
+    import pytest
+
+    with pytest.raises(ValueError):
+        insert_realized_slippage_sample(
+            db_path,
+            ticker="005930",
+            side="BUY",
+            intended_price=0,
+            actual_fill_price=100,
+            recorded_at="2026-06-21",
+        )
diff --git a/tools/evaluate_execution_slippage_v1.py b/tools/evaluate_execution_slippage_v1.py
new file mode 100644
index 00000000..48907550
--- /dev/null
+++ b/tools/evaluate_execution_slippage_v1.py
@@ -0,0 +1,75 @@
+#!/usr/bin/env python3
+"""WBS-7.6(2026-06-21) — 실거래 슬리피지 실측 캡처/비교 CLI.
+
+사용법:
+  실측 1건 기록(주문 실행은 여전히 사람이 HTS에서 수동 실행 — 이 도구는 API로
+  체결을 가져오지 않는다. governance/rules/06_no_direct_api_trading.yaml 준수):
+    python tools/evaluate_execution_slippage_v1.py record --ticker 005930 --side BUY \
+      --intended-price 71000 --actual-price 71050 --recorded-at 2026-06-21
+
+  누적 표본과 가정치(5bps) 비교 리포트:
+    python tools/evaluate_execution_slippage_v1.py report
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+if sys.stdout.encoding and sys.stdout.encoding.lower() not in ("utf-8", "utf8"):
+    sys.stdout = open(sys.stdout.fileno(), mode="w", encoding="utf-8", buffering=1)
+
+from src.quant_engine.execution_slippage_store_v1 import (
+    build_slippage_comparison_report,
+    default_execution_slippage_store_path,
+    insert_realized_slippage_sample,
+)
+
+OUTPUT = ROOT / "Temp" / "execution_slippage_report_v1.json"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--db", type=Path, default=None)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    record = sub.add_parser("record")
+    record.add_argument("--ticker", required=True)
+    record.add_argument("--side", required=True, choices=["BUY", "SELL", "buy", "sell"])
+    record.add_argument("--intended-price", type=float, required=True)
+    record.add_argument("--actual-price", type=float, required=True)
+    record.add_argument("--recorded-at", required=True)
+    record.add_argument("--note", default=None)
+
+    sub.add_parser("report")
+
+    args = parser.parse_args()
+    db_path = args.db or default_execution_slippage_store_path(ROOT)
+
+    if args.command == "record":
+        result = insert_realized_slippage_sample(
+            db_path,
+            ticker=args.ticker,
+            side=args.side,
+            intended_price=args.intended_price,
+            actual_fill_price=args.actual_price,
+            recorded_at=args.recorded_at,
+            note=args.note,
+        )
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0
+
+    report = build_slippage_comparison_report(db_path)
+    OUTPUT.parent.mkdir(parents=True, exist_ok=True)
+    OUTPUT.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

From 556800470470217248129cf1aadbc114eed012db Mon Sep 17 00:00:00 2001
From: kjh2064 
Date: Sun, 21 Jun 2026 20:09:43 +0900
Subject: [PATCH 07/10] =?UTF-8?q?WBS-7.7:=20KIS=EC=88=98=EC=A7=91=E2=86=92?=
 =?UTF-8?q?=EC=8A=A4=EB=83=85=EC=83=B7=E2=86=92=EC=A0=95=EC=84=B1=EB=A7=A4?=
 =?UTF-8?q?=EB=8F=84=20E2E=20=ED=86=B5=ED=95=A9=ED=85=8C=EC=8A=A4=ED=8A=B8?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

단위 테스트는 모듈별로 충분했지만 KIS 수집→data_collection_store_v1.db
적재→정성매도전략 평가로 이어지는 실제 데이터 경로를 검증하는 테스트가
없었다. 네트워크를 전혀 사용하지 않고(no-naver/no-live-kis 경로, 또는
Naver 403 차단 모킹) 3단계 체인을 검증한다.
---
 ..._to_snapshot_admin_and_sell_strategy_v1.py | 138 ++++++++++++++++++
 1 file changed, 138 insertions(+)
 create mode 100644 tests/integration/test_kis_collection_to_snapshot_admin_and_sell_strategy_v1.py

diff --git a/tests/integration/test_kis_collection_to_snapshot_admin_and_sell_strategy_v1.py b/tests/integration/test_kis_collection_to_snapshot_admin_and_sell_strategy_v1.py
new file mode 100644
index 00000000..32c83653
--- /dev/null
+++ b/tests/integration/test_kis_collection_to_snapshot_admin_and_sell_strategy_v1.py
@@ -0,0 +1,138 @@
+"""WBS-7.7 — KIS 수집 → 스냅샷 어드민 적재 → 정성매도전략 평가 E2E 체인.
+
+단위 테스트(tests/unit)는 각 모듈을 독립적으로 검증하지만, 모듈 간 실제 데이터
+경로(kis_data_collection_v1 → data_collection_store_v1.db → snapshot_admin의
+collection dashboard / qualitative_sell_strategy_v1 → qualitative_sell_strategy_store_v1.db)
+를 연결해서 검증하는 테스트가 없었다(2026-06-21 비판적 리뷰 0c절, WBS-7.7).
+
+이 테스트는 네트워크를 전혀 사용하지 않는다(--no-live-kis --no-naver와 동일한 경로,
+또는 Naver 호출을 명시적으로 예외 처리시켜 graceful degradation을 검증).
+"""
+from __future__ import annotations
+
+import json
+import sys
+from datetime import date
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+import pytest
+
+from src.quant_engine import kis_data_collection_v1 as kdc
+from src.quant_engine.data_collection_store_v1 import load_collection_dashboard_state
+from src.quant_engine.qualitative_sell_strategy_v1 import compute_qualitative_sell_strategy
+from src.quant_engine.qualitative_sell_strategy_store_v1 import (
+    fetch_recent_sell_strategy_results,
+    insert_sell_strategy_result,
+)
+
+SEED_ROWS = [
+    {"Ticker": "005930", "Name": "삼성전자", "Sector": "반도체"},
+    {"Ticker": "000660", "Name": "SK하이닉스", "Sector": "반도체"},
+]
+
+
+@pytest.fixture()
+def seed_json(tmp_path: Path) -> Path:
+    path = tmp_path / "seed.json"
+    path.write_text(
+        json.dumps({"data": {"data_feed": SEED_ROWS}}, ensure_ascii=False),
+        encoding="utf-8",
+    )
+    return path
+
+
+def test_kis_collection_writes_sqlite_that_snapshot_admin_dashboard_reads_back(tmp_path: Path, seed_json: Path):
+    """1단계: KIS 수집(네트워크 미사용) → SQLite 적재 → snapshot_admin 대시보드 read-back."""
+    db_path = tmp_path / "data_collection_store_v1.db"
+    output_json = tmp_path / "kis_data_collection_v1.json"
+
+    summary = kdc.collect_to_sqlite(
+        input_json=seed_json,
+        sqlite_db=db_path,
+        output_json=output_json,
+        kis_account="mock",
+        include_naver=False,
+        include_live_kis=False,
+    )
+
+    assert summary["status"] in {"PASS", "PASS_WITH_WARNINGS"}
+    assert summary["row_count"] == len(SEED_ROWS)
+    assert not summary["errors"]
+
+    dashboard = load_collection_dashboard_state(db_path=db_path, output_json_path=output_json)
+    assert dashboard["counts"]["collection_runs"] >= 1
+    assert dashboard["counts"]["collection_snapshots"] == len(SEED_ROWS)
+    assert dashboard["counts"]["collection_source_errors"] == 0
+    tickers_in_dashboard = {row["ticker"] for row in dashboard["recent_snapshots"]}
+    assert {"005930", "000660"} <= tickers_in_dashboard
+
+
+def test_naver_fetch_exception_degrades_gracefully_without_breaking_batch(tmp_path: Path, seed_json: Path, monkeypatch):
+    """Cloudflare 403 등 Naver 폴백 차단 시 graceful degradation 검증 (spec/exit/qualitative_sell_strategy_v1.yaml:81-82 명시 리스크)."""
+
+    def _raise_cloudflare_block(_session, _code):
+        raise RuntimeError("HTTP 403 Forbidden (Cloudflare)")
+
+    monkeypatch.setattr(kdc, "fetch_price_history", _raise_cloudflare_block)
+    # naver_session/fetch_price_history may be None on environments without the optional
+    # dependency wired; force both non-None so _normalize_naver_price_history actually tries.
+    monkeypatch.setattr(kdc, "naver_session", lambda: object())
+
+    db_path = tmp_path / "data_collection_store_v1.db"
+    output_json = tmp_path / "kis_data_collection_v1.json"
+
+    summary = kdc.collect_to_sqlite(
+        input_json=seed_json,
+        sqlite_db=db_path,
+        output_json=output_json,
+        kis_account="mock",
+        include_naver=True,
+        include_live_kis=False,
+    )
+
+    # 배치 전체가 죽지 않고 끝까지 진행되어야 한다 — 개별 ticker의 naver 보강 실패는
+    # collection_source_errors가 아니라 정상 row로 (naver 필드 없이) 기록된다.
+    assert summary["status"] in {"PASS", "PASS_WITH_WARNINGS"}
+    assert summary["row_count"] == len(SEED_ROWS)
+    assert not summary["errors"], "Naver 차단은 개별 ticker 처리 중 흡수되어야 하며 배치 errors로 전파되면 안 된다"
+
+
+def test_qualitative_sell_strategy_decision_round_trips_through_store(tmp_path: Path):
+    """2단계: 정성매도전략 평가(순수 함수, 네트워크 미사용) → SQLite 저장 → 조회 round-trip."""
+    ctx = {
+        "today": date(2026, 6, 21),
+        "macro_pressure": 0.5,
+        "fundamental_trajectory": 0.4,
+        "short_interest_pressure": 0.6,
+        "microstructure_pressure": 0.2,
+        "liquidity_rotation_risk": 0.5,
+        "rate_trend": "RISING",
+    }
+    decision = compute_qualitative_sell_strategy(ctx)
+    assert decision["action"] in {
+        "EXIT_REVIEW_FULL",
+        "TRIM_REVIEW_PARTIAL",
+        "HOLD_ADD_CONVICTION",
+        "HOLD_NO_CONFLUENCE",
+        "INSUFFICIENT_DATA_NO_ACTION",
+    }
+
+    result = {
+        "code": "005930",
+        "generated_at": "2026-06-21T15:30:00+09:00",
+        "decision": decision,
+    }
+
+    db_path = tmp_path / "qualitative_sell_strategy.db"
+    insert_sell_strategy_result(db_path, result)
+
+    fetched = fetch_recent_sell_strategy_results(db_path, "005930", limit=5)
+    assert len(fetched) == 1
+    assert fetched[0]["code"] == "005930"
+    assert fetched[0]["action"] == decision["action"]
+    assert fetched[0]["conviction"] == decision["conviction"]
+    assert fetched[0]["market_regime"] == decision["market_regime"]

From 670ab8e15aa30af9aac00db05f0c74f6b5e878cd Mon Sep 17 00:00:00 2001
From: kjh2064 
Date: Sun, 21 Jun 2026 20:10:27 +0900
Subject: [PATCH 08/10] =?UTF-8?q?WBS-7.8:=20ETF=20NAV/=EA=B3=B5=EB=A7=A4?=
 =?UTF-8?q?=EB=8F=84=20=EC=9E=94=EA=B3=A0=EC=9C=A8=20=EC=9E=90=EB=8F=99?=
 =?UTF-8?q?=ED=99=94=20=EC=8B=A4=EC=B8=A1=20+=20=EC=9A=B4=EC=98=81?=
 =?UTF-8?q?=EC=A0=88=EC=B0=A8=20=EB=AC=B8=EC=84=9C=ED=99=94?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

"자동화가 안 되면 차후 개선 목표로" 라는 지시에 따라 추정이 아니라
실제로 pykrx(이미 EOD 가격조회에 쓰이는 동일 라이브러리)의
get_shorting_balance()/get_etf_price_deviation()/get_etf_tracking_error()를
호출해 재시도했다. 기본 시세조회는 정상 작동하지만 이 세 함수는 세션
부트스트랩 후에도 HTTP 400 LOGOUT을 반환 — KRX 회원 로그인이 필요한
서버측 인증 게이트임을 raw HTTP로 재현 확인했다(헤더/세션 문제 아님).
자동화하려면 KRX 계정을 자격증명으로 등록해야 하는데, 이는
governance/rules/06·07과 같은 종류의 새 정책 결정이라 사용자 승인
없이 추가하지 않고 개선 목표로 이관한다(next_review_date: 2026-09-30).

- spec/16_data_gaps_roadmap.yaml S4/S5: automation_attempt_2026_06_22
  필드에 재현 절차 기록, next_review_action을 "API 키 발급"이 아니라
  "KRX 계정 발급·자격증명 관리 정책 승인 여부"로 재구성
- docs/runbook.md: 공매도 잔고율 주1회(매주 월요일 개장 전) CSV 수동
  갱신, ETF NAV 수동 import(tools/import_etf_nav_manual.py) 운영절차 명문화
---
 docs/runbook.md                |  15 ++
 spec/16_data_gaps_roadmap.yaml | 256 ++++++++++++++++++++++++++++++++-
 2 files changed, 270 insertions(+), 1 deletion(-)

diff --git a/docs/runbook.md b/docs/runbook.md
index 25d81cbb..ba4c7294 100644
--- a/docs/runbook.md
+++ b/docs/runbook.md
@@ -6,3 +6,18 @@
 4. Render reports from canonical data only.
 5. Package upload artifacts only after the full gate passes or the output is explicitly audit-only.
 6. Treat work as complete only when YAML, code, data artifacts, and validation evidence all exist together.
+7. For calibration maintenance, run `npm run ops:calibration-backlog` or the Gitea schedule in `.gitea/workflows/calibration_backlog.yml`.
+8. Promote a threshold to `PROVISIONAL` only when there is a recorded sample note and an explicit change note in `Temp/calibration_change_ledger_v4.json`.
+9. Promote a threshold to `CALIBRATED` only when `sample_n >= 30`, a backtest note exists, and the validator still reports `overclaimed_count == 0`.
+10. For human review, open `Temp/calibration_review_report_v1.md` after each backlog build.
+11. For approval signoff, open `Temp/calibration_approval_list_v1.md` and approve only `source=PROVISIONAL` rows unless a new provisional review is explicitly requested.
+12. For spreadsheet-like edits of `settings` and `account_snapshot`, run `npm run ops:snapshot-web` and validate with `npm run ops:snapshot-web-validate`.
+13. Treat the snapshot admin web UI as the canonical edit surface for SQLite-backed manual maintenance; export JSON only when CI or downstream tooling needs a file artifact.
+14. Keep `settings` and `account_snapshot` in the same workspace SQLite DB. Do not split them into separate files per sheet; use a separate SQLite DB only for the KIS collection pipeline.
+15. Use the `KIS Collection` panel in snapshot admin to inspect the latest SQLite collection run, report status, source counts, and recent errors before you touch the editor.
+16. Use the collection filter when you need to narrow runs, snapshots, or errors by ticker/source/status.
+17. Use the change log filter when you need to audit a specific domain, action, or target reference.
+18. Use `/collection` when you want the collection-only dashboard with raw JSON download.
+19. Use `Export approval packet` in the snapshot admin UI to write `Temp/snapshot_admin_approval_packet_v1.json` and `Temp/snapshot_admin_approval_packet_v1.md` for review handoff.
+20. Short balance ratio (`short_balance_ratio`) has no automatable path — confirmed 2026-06-22 by live-testing `pykrx.stock.get_shorting_balance()` (already used elsewhere in this repo for EOD prices), which returns `HTTP 400 LOGOUT` even with a properly bootstrapped session. This KRX "standard report" endpoint family requires actual KRX member login (`KRX_ID`/`KRX_PW`), unlike the basic OHLCV endpoints. Adding KRX login credentials is a new credential-management policy decision (same category as governance/rules/06-07) that requires explicit user approval — do not add it unilaterally. Until then, download the KRX 공매도종합포털 CSV weekly (every Monday before market open) and feed it via `--short-csv` to `build_qualitative_sell_inputs_v1.py`.
+21. ETF NAV/iNAV/괴리율/추적오차/AUM has no automatable path either — same 2026-06-22 test confirmed `pykrx.stock.get_etf_price_deviation()`/`get_etf_tracking_error()` also return `HTTP 400 LOGOUT` (same KRX member-login gate as item 20). See `spec/16_data_gaps_roadmap.yaml` S4/S5 `automation_attempt_2026_06_22` for the full reproduction. Until a KRX login policy decision is made, keep feeding `etf_nav_manual` via `tools/import_etf_nav_manual.py` from manually downloaded KRX/KIND/운용사 CSV exports.
diff --git a/spec/16_data_gaps_roadmap.yaml b/spec/16_data_gaps_roadmap.yaml
index 4bfbd0a6..ab433530 100644
--- a/spec/16_data_gaps_roadmap.yaml
+++ b/spec/16_data_gaps_roadmap.yaml
@@ -1,6 +1,6 @@
 meta:
   title: "데이터 갭 로드맵 — 단계별 보완 계획"
-  version: "2026-05-17-initial"
+  version: "2026-06-21-platform-transition-v1"
   language: "ko-KR"
   purpose: >
     의사결정 파이프라인(spec/09_decision_flow.yaml)에서 식별된 데이터 공백을
@@ -145,6 +145,25 @@ phase_2_structural:
     limitation: >
       KRX/KIND 기반 NAV/괴리율/추적오차/AUM 수집은 아직 미구현이며 etf_raw에서
       ETF_NAV_Risk=NAV_DATA_MISSING으로 명시한다.
+    next_review_date: "2026-09-30"  # WBS-7.8(2026-06-21) — KRX/KIND API 키 발급 가능성 분기별 재조사
+    next_review_action: >
+      KRX 정보데이터시스템/KIND 공식 API 또는 공개 데이터셋의 발급/이용약관 변경 여부를
+      재확인한다. 변경이 없으면 next_review_date를 다음 분기로 갱신하고 PLANNED 유지,
+      변경이 있으면 P1_kis_core_api_collector와 동일한 패턴으로 착수 여부를 결정한다.
+    automation_attempt_2026_06_22: >
+      pykrx(이미 tools/build_prediction_accuracy_harness_v2.py에서 EOD 가격 조회로 사용 중)의
+      get_etf_price_deviation()/get_etf_tracking_error()/get_shorting_balance()를 실제로
+      호출해 자동화 가능성을 재시도했다. 결과: 기본 시세조회(OHLCV)는 정상 작동(공개
+      엔드포인트, 로그인 불필요)하지만, 공매도 잔고/ETF 괴리율/추적오차 엔드포인트는
+      세션 쿠키를 정상 부트스트랩한 뒤에도 "HTTP 400 LOGOUT"을 반환했다(raw HTTP로
+      재현 확인). 이는 pykrx 임포트 시 출력되는 "KRX_ID/KRX_PW 환경변수 미설정" 경고와
+      정확히 일치 — 이 카테고리는 KRX 회원 로그인이 있어야 접근 가능한 서버측 인증
+      게이트이며, 헤더/세션 보정으로 해결되는 문제가 아님을 확인했다. 자동화하려면
+      KRX 계정(KRX_ID/KRX_PW)을 자격증명으로 코드에 등록해야 하는데, 이는
+      governance/rules/06·07과 유사한 새로운 자격증명 정책 결정이 필요한 사안이라
+      사용자 승인 없이 추가하지 않는다. 기술적 장벽 자체는 명확히 확정됐으므로
+      next_review_date 재조사 시 "API 키 발급 가능성"이 아니라 "KRX 계정 발급·자격증명
+      관리 정책 승인 여부"로 재구성해 검토할 것.
 
   S5_etf_raw_execution_quality:
     priority: HIGH
@@ -158,6 +177,9 @@ phase_2_structural:
       etf_nav_manual 시트가 있으면 NAV, iNAV, 괴리율, 추적오차, AUM을 etf_raw에 반영한다.
       tools/import_etf_nav_manual.py로 KRX/KIND/운용사 CSV/XLSX export를 etf_nav_manual로 변환할 수 있다.
     limitation: "NAV, iNAV, 괴리율, 추적오차, AUM 자동 수집은 KRX/KIND 수집 경로 확정 전까지 미구현."
+    next_review_date: "2026-09-30"  # WBS-7.8(2026-06-21) — S4와 동일 주기로 재검토
+    next_review_action: "S4_sector_flow.next_review_action과 동일 — KRX/KIND 경로 확정 시 etf_nav_manual 수동 경로를 자동 수집으로 대체."
+    automation_attempt_2026_06_22: "S4_sector_flow.automation_attempt_2026_06_22와 동일 사유로 자동화 불가 확정(pykrx get_etf_price_deviation/get_etf_tracking_error 모두 HTTP 400 LOGOUT — KRX 회원 로그인 필요)."
 
   S6_sector_flow_history:
     priority: HIGH
@@ -169,6 +191,41 @@ phase_2_structural:
       이력이 부족할 때만 기존 sector_flow/PropertiesService 값을 fallback으로 사용한다.
       Snapshot_Date는 Apps Script Date 객체와 문자열 날짜를 모두 yyyy-MM-dd로 정규화한다.
 
+  S7_snapshot_admin_web_editor:
+    priority: HIGH
+    status: DONE
+    implementation: >
+      SQLite canonical store용 웹 편집기 구현.
+      settings/account_snapshot을 contenteditable 그리드로 직접 수정하고,
+      TSV import/export, 행 삽입/복제, 승인/잠금/undo를 API로 제어한다.
+      KIS SQLite collector 상태 패널을 함께 노출해서 최신 수집 run/오류를
+      같은 화면에서 확인한다.
+      web UI는 Snapshot Admin 서버가 담당하며 JSON export는 CI/파생 도구용이다.
+    enables: >
+      settings/account_snapshot을 xlsx 대신 SQLite에서 직접 관리하면서도
+      스프레드시트처럼 편집 가능한 운영 surface와 수집 현황 대시보드 제공.
+    success_criteria:
+      settings_sheet_web_editor: true
+      account_snapshot_sheet_web_editor: true
+      contenteditable_grid: true
+      api_save_round_trip: PASS
+      kis_collection_dashboard: true
+      single_workspace_sqlite: true
+      collection_filter_controls: true
+      collection_dashboard_page: true
+      change_timeline_view: true
+    evidence:
+      code:
+        - "src/quant_engine/snapshot_admin_server_v1.py"
+        - "src/quant_engine/snapshot_admin_store_v1.py"
+        - "tools/validate_snapshot_admin_web_v1.py"
+      tests:
+        - "tests/unit/test_snapshot_admin_store_v1.py"
+        - "tests/unit/test_snapshot_admin_web_v1.py"
+      workflow:
+        - ".gitea/workflows/snapshot_admin.yml"
+    verification: "python tools/validate_snapshot_admin_web_v1.py"
+
 # ─────────────────────────────────────────────────────────────────────────────
 # 3단계 — 분석 품질 고도화 (낮은 우선순위)
 # ─────────────────────────────────────────────────────────────────────────────
@@ -503,6 +560,203 @@ phase_4_backdata_collection:
       2026-06-14 구현 완료 확인. GAS(syncBackdataFeatureBank_) + Python(synthesize_backdata_feature_bank)
       모두 구현됨. T+20 데이터 누적 후 ML 패턴 학습 품질 향상 예정.
 
+# ─────────────────────────────────────────────────────────────────────────────
+# 5단계 — CI 기반 데이터 플랫폼 전환
+# ─────────────────────────────────────────────────────────────────────────────
+phase_5_platform_transition:
+  P1_kis_core_api_collector:
+    priority: HIGH
+    status: PLANNED
+    purpose: >
+      KIS Open API를 read-only 코어 수집원으로 두고, 가격/호가/공매도/수급의
+      1차 수집을 Python canonical collector에서 직접 수행한다.
+    inputs:
+      - "KIS_APP_Key / KIS_APP_Secret"
+      - "KIS_APP_Key_TEST / KIS_APP_Secret_TEST"
+      - "GatherTradingData.json"
+    outputs:
+      - "Temp/kis_data_collection_v1.json"
+      - "outputs/kis_data_collection/kis_data_collection.db"
+    fallback_order:
+      - "KIS Open API"
+      - "Naver Finance"
+      - "Yahoo Finance"
+      - "OpenDART"
+      - "Investing.com(best-effort, 차단 시 DATA_MISSING)"
+    note: >
+      주문 API는 사용하지 않는다. 조회형 quotations/ranking 계열만 허용한다.
+    success_criteria:
+      expected_success_value:
+        collector_gate: "PASS"
+        output_json_gate: "PASS"
+        sqlite_run_count_min: 1
+        sqlite_snapshot_count_min: 1
+        provenance_source_count_min: 1
+      evidence_artifacts:
+        - "Temp/test_kis_data_collection.json"
+        - "Temp/test_kis_data_collection.db"
+      verification_commands:
+        - "python tools/run_kis_data_collection_v1.py --input-json GatherTradingData.json --sqlite-db Temp/test_kis_data_collection.db --output-json Temp/test_kis_data_collection.json --kis-account real --no-live-kis --no-naver"
+        - "python - <<'PY' ... sqlite count check ... PY"
+
+  P2_sqlite_canonical_store:
+    priority: HIGH
+    status: PLANNED
+    purpose: >
+      xlsx 중심 저장을 중단하고, 수집 결과를 SQLite에 누적 저장한다.
+      향후 PostgreSQL 승격 시 동일 저장 인터페이스를 유지한다.
+    required_tables:
+      - "collection_runs"
+      - "collection_snapshots"
+      - "collection_source_errors"
+    stored_payloads:
+      - "raw source payload"
+      - "normalized factor row"
+      - "provenance JSON"
+      - "batch/run metadata"
+    migration_note: "PostgreSQL 전환 시 dialect만 교체하고 row shape은 유지한다."
+    success_criteria:
+      expected_success_value:
+        sqlite_schema_tables_min: 3
+        round_trip_snapshot_lookup: "PASS"
+        backend_contract_sqlite: "PASS"
+        backend_contract_postgresql: "READY"
+      evidence_artifacts:
+        - "src/quant_engine/data_collection_store_v1.py"
+        - "src/quant_engine/data_collection_backend_v1.py"
+        - "tests/unit/test_data_collection_store_v1.py"
+      verification_commands:
+        - "python -m pytest tests/unit/test_data_collection_store_v1.py -q"
+        - "python -m py_compile src/quant_engine/data_collection_store_v1.py src/quant_engine/data_collection_backend_v1.py"
+
+  P3_ci_scheduler_cutover:
+    priority: HIGH
+    status: PLANNED
+    purpose: >
+      Gitea schedule에서 Python collector를 직접 실행하고, CI가 SQLite 산출을 검증한다.
+      기존 GAS 워크플로우는 thin adapter/legacy fallback으로만 유지한다.
+    validation_gate:
+      - "read-only KIS gate"
+      - "source fallback gate"
+      - "sqlite round-trip gate"
+      - "provenance completeness gate"
+      - "no-direct-trading gate"
+    output_policy:
+      - "CI는 xlsx 생성에 의존하지 않는다."
+      - "결과는 JSON + SQLite + 로그 증빙으로 남긴다."
+    success_criteria:
+      expected_success_value:
+        xlsx_dependency_removed: true
+        json_seed_input: true
+        sqlite_output: true
+        mock_api_validation: "PASS"
+        no_direct_trading_gate: "PASS"
+        provenance_completeness_gate: "PASS"
+      evidence_artifacts:
+        - ".gitea/workflows/kis_data_collection.yml"
+        - "Temp/kis_api_credentials_validation_v1.json"
+        - "Temp/test_kis_data_collection.json"
+      verification_commands:
+        - "python tools/validate_no_direct_api_trading_v1.py"
+        - "python tools/validate_kis_api_credentials_v1.py --account mock --ticker 005930"
+        - "python tools/run_kis_data_collection_v1.py --help"
+
+  P4_gas_thin_adapter_minimize:
+    priority: MEDIUM
+    status: PLANNED
+    purpose: >
+      .gs는 기존 스프레드시트 호환과 과도기 검증용 얇은 어댑터만 남기고,
+      판단·수집·저장 로직은 Python으로 이동시킨다.
+    allowed_responsibilities:
+      - "collect"
+      - "normalize"
+      - "export"
+      - "display"
+    forbidden_responsibilities:
+      - "decision"
+      - "sizing"
+      - "stop_loss"
+      - "take_profit"
+      - "risk_score"
+    success_criteria:
+      expected_success_value:
+        allowed_responsibilities_only: true
+        forbidden_responsibilities_present: false
+        thin_adapter_gate: "PASS"
+      evidence_artifacts:
+        - "tools/validate_gas_thin_adapter_v1.py"
+        - "Temp/gas_thin_adapter_validation_v1.json"
+        - "src/gas/core/gas_lib.gs"
+      verification_commands:
+        - "python tools/validate_gas_thin_adapter_v1.py"
+
+  P5_postgresql_upgrade_path:
+    priority: MEDIUM
+    status: PLANNED
+    purpose: >
+      SQLite에서 검증된 스키마/업서트/프로venance 모델을 PostgreSQL로 승격한다.
+      운영 데이터 증가와 멀티잡 동시성 증가를 대비한다.
+    upgrade_steps:
+      - "sqlite schema parity 검증"
+      - "db_url 기반 backend 추상화"
+      - "migration script 추가"
+      - "CI에서 sqlite/postgres 동일 테스트"
+    compatibility_rule: "SQLite와 PostgreSQL 모두 동일한 row contract를 유지한다."
+    success_criteria:
+      expected_success_value:
+        sqlite_schema_parity: "PASS"
+        backend_contract_present: true
+        postgres_execution: "DATA_GATED"
+        caller_compatibility_preserved: true
+      evidence_artifacts:
+        - "src/quant_engine/data_collection_backend_v1.py"
+        - "src/quant_engine/kis_data_collection_v1.py"
+        - "tests/unit/test_data_collection_store_v1.py"
+        - "tools/generate_postgresql_upgrade_stub_v1.py"
+      verification_commands:
+        - "python -m pytest tests/unit/test_data_collection_store_v1.py -q"
+        - "python -m py_compile src/quant_engine/kis_data_collection_v1.py tools/run_kis_data_collection_v1.py"
+        - "python tools/generate_postgresql_upgrade_stub_v1.py"
+
+  Q1_qualitative_sell_pipeline:
+    priority: MEDIUM
+    status: PLANNED
+    purpose: >
+      비기계적 매도전략 파이프라인을 Gitea workflow + SQLite 시계열 + mock KIS 유효성
+      검증 + 사후 적중률 평가까지 일관된 계약으로 묶는다.
+    success_criteria:
+      expected_success_value:
+        mock_api_validation: "PASS"
+        pipeline_contract: "PASS"
+        workflow_present: true
+        schedule_present: true
+        package_scripts_present: true
+      evidence_artifacts:
+        - ".gitea/workflows/qualitative_sell_strategy.yml"
+        - "tools/validate_qualitative_sell_strategy_pipeline_v1.py"
+        - "Temp/qualitative_sell_strategy_pipeline_v1.json"
+      verification_commands:
+        - "python tools/validate_qualitative_sell_strategy_pipeline_v1.py"
+
+  Q2_gitea_secrets_contract:
+    priority: HIGH
+    status: PLANNED
+    purpose: >
+      Gitea workflow에서 KIS mock/real 자격증명과 GITHUB_TOKEN 시크릿 이름을
+      정확히 고정해, 수동 등록 실수로 인한 파이프라인 붕괴를 방지한다.
+    success_criteria:
+      expected_success_value:
+        secrets_contract: "PASS"
+        workflow_secret_mapping: "PASS"
+        docs_present: true
+        ci_validation_present: true
+      evidence_artifacts:
+        - "docs/GITEA_SECRETS_SETUP.md"
+        - "tools/validate_gitea_secrets_contract_v1.py"
+        - "Temp/gitea_secrets_contract_v1.json"
+      verification_commands:
+        - "python tools/validate_gitea_secrets_contract_v1.py"
+
 # 2026-05-30 구현 현황
 # - S5_etf_raw: PARTIAL_DONE 유지 (수동 NAV 병행)
 # - Stage2_Gate PENDING: T+20 표본 누적 후 자동 평가

From 4c0022944266cd29cdb8475577daf8f441eef14a Mon Sep 17 00:00:00 2001
From: kjh2064 
Date: Sun, 21 Jun 2026 20:11:26 +0900
Subject: [PATCH 09/10] =?UTF-8?q?KIS=C2=B7=EC=A0=95=EC=84=B1=EB=A7=A4?=
 =?UTF-8?q?=EB=8F=84=C2=B7=EC=8A=A4=EB=83=85=EC=83=B7=EC=96=B4=EB=93=9C?=
 =?UTF-8?q?=EB=AF=BC=C2=B7=EC=BA=98=EB=A6=AC=EB=B8=8C=EB=A0=88=EC=9D=B4?=
 =?UTF-8?q?=EC=85=98=EC=9D=84=20CI/npm/=EB=AC=B8=EC=84=9C=EC=97=90=20?=
 =?UTF-8?q?=ED=86=B5=ED=95=A9=20=EB=B0=B0=EC=84=A0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

이전 커밋들에서 추가한 기능을 실제로 동작시키는 배선 작업.

- .gitea/workflows/ci.yml: No Direct API Trading 게이트, KIS 자격증명
  검증(mock), 캘리브레이션 백로그 빌드, 정성매도 파이프라인 검증,
  Gitea secrets 계약 검증, snapshot admin 워크플로/웹 검증 단계 추가
- package.json: ops:data-collect, ops:sell-*, ops:snapshot-*,
  ops:calibration-* npm 스크립트 추가
- src/gas/core/gas_lib.gs doPost(): "trigger_run_all" action 추가 —
  Gitea CI가 공유 비밀키로 run_all()을 원격 트리거(주문 실행 없음,
  governance/rules/06·07과 동일 원칙)
- tools/trigger_gas_run_all_v1.py: 위 GAS 엔드포인트를 호출하는 CLI
- AGENTS.md/README.md: 신규 파일 인덱스 및 사용 가이드 갱신
---
 .gitea/workflows/ci.yml                      |  36 +++
 AGENTS.md                                    |  14 +
 README.md                                    |  69 +++++
 package.json                                 |  16 +
 runtime/refactor_baseline_v1.yaml            |   4 +-
 src/gas/core/gas_lib.gs                      |  23 ++
 tools/trigger_gas_run_all_v1.py              |  51 ++++
 tools/validate_platform_transition_wbs_v1.py | 294 +++++++++++++++++++
 8 files changed, 505 insertions(+), 2 deletions(-)
 create mode 100644 tools/trigger_gas_run_all_v1.py
 create mode 100644 tools/validate_platform_transition_wbs_v1.py

diff --git a/.gitea/workflows/ci.yml b/.gitea/workflows/ci.yml
index 2dd66a14..eaf20b4d 100644
--- a/.gitea/workflows/ci.yml
+++ b/.gitea/workflows/ci.yml
@@ -98,6 +98,15 @@ jobs:
         fi
         node --version && npm --version
 
+    - name: "[CRITICAL] No Direct API Trading Gate"
+      run: python3 tools/validate_no_direct_api_trading_v1.py
+
+    - name: "[CRITICAL] Validate KIS API Credentials (mock)"
+      env:
+        KIS_APP_Key_TEST: ${{ secrets.KIS_APP_KEY_TEST }}
+        KIS_APP_Secret_TEST: ${{ secrets.KIS_APP_SECRET_TEST }}
+      run: python3 tools/validate_kis_api_credentials_v1.py --account mock --ticker 005930
+
     - name: Validate Specs
       run: python3 tools/validate_specs.py
 
@@ -110,6 +119,33 @@ jobs:
     - name: Validate Harness Coverage Audit
       run: python3 tools/harness_coverage_auditor.py
 
+    - name: Validate Platform Transition WBS
+      run: python3 tools/validate_platform_transition_wbs_v1.py
+
+    - name: Build Calibration Priority Backlog
+      run: python3 tools/build_calibration_priority_v1.py
+
+    - name: Build Calibration Change Ledger
+      run: python3 tools/build_calibration_change_ledger_v4.py
+
+    - name: Validate Calibration Change Ledger
+      run: python3 tools/validate_calibration_change_ledger_v1.py
+
+    - name: Validate Qualitative Sell Strategy Pipeline
+      run: python3 tools/validate_qualitative_sell_strategy_pipeline_v1.py
+
+    - name: Validate Gitea Secrets Contract
+      run: python3 tools/validate_gitea_secrets_contract_v1.py
+
+    - name: Validate Snapshot Admin Workflow
+      run: python3 tools/validate_snapshot_admin_workflow_v1.py
+
+    - name: Validate Snapshot Admin Web UI
+      run: python3 tools/validate_snapshot_admin_web_v1.py
+
+    - name: Validate Storage Backend Contracts
+      run: python3 -m pytest tests/unit/test_storage_backend_v1.py tests/unit/test_validate_kis_api_credentials_v1.py tests/unit/test_qualitative_sell_strategy_store_v1.py tests/unit/test_kis_api_client_v1.py tests/unit/test_snapshot_admin_store_v1.py tests/unit/test_snapshot_admin_web_v1.py -q
+
     - name: Notify PR Result
       if: github.event_name == 'pull_request'
       run: |
diff --git a/AGENTS.md b/AGENTS.md
index d23e195c..bc3377cd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -45,7 +45,21 @@
 - `spec/`: source of truth. 공식, 계약, 게이트, 출력 스키마의 최우선 읽기 경로.
 - `governance/`: 운영 규칙, 인덱스, 해시 마이그레이션, ADR, 템플릿.
 - `src/`: Python canonical implementation. 새 로직은 여기부터 반영한다.
+- `src/quant_engine/data_collection_backend_v1.py`: 수집 저장소 backend contract selector.
+- `src/quant_engine/data_collection_store_v1.py`: SQLite canonical collection store.
+- `src/quant_engine/kis_data_collection_v1.py`: KIS-first read-only collector.
+- `src/quant_engine/storage_backend_v1.py`: generic storage backend contract.
 - `tools/`: build, validate, convert, audit CLI. 상태는 유지하되 핵심 로직은 두지 않는다.
+- `tools/run_kis_data_collection_v1.py`: CI scheduler용 KIS 수집 thin CLI wrapper.
+- `tools/generate_postgresql_upgrade_stub_v1.py`: PostgreSQL upgrade stub generator.
+- `tools/validate_qualitative_sell_strategy_pipeline_v1.py`: qualitative sell pipeline contract validator.
+- `tools/validate_gitea_secrets_contract_v1.py`: Gitea secrets naming contract validator.
+- `tools/validate_snapshot_admin_web_v1.py`: snapshot admin web UI smoke validator.
+- `.gitea/workflows/qualitative_sell_strategy.yml`: qualitative sell strategy workflow.
+- `.gitea/workflows/snapshot_admin.yml`: snapshot admin workflow and scheduled validation.
+- `docs/GITEA_SECRETS_SETUP.md`: Gitea secrets setup and verification guide.
+- `Temp/snapshot_admin_approval_packet_v1.json`: snapshot admin approval packet export.
+- `Temp/snapshot_admin_approval_packet_v1.md`: snapshot admin approval packet summary.
 - `gas_event_calendar.gs`: 이벤트 캘린더 배포 호환 스텁. `seedEventCalendar_()` / `runEventRisk()` 진입점을 유지한다.
 - `Temp/`: 실행 결과와 캐시. 라우팅 대상은 아니며 runtime consumer만 읽는다.
 - `dist/`, `artifacts/`, `docs/`, `examples/`, `prompts/`, `schemas/`, `tests/`: 패키징/문서/검증/산출물 보조 경로.
diff --git a/README.md b/README.md
index dd75301c..b43c4835 100644
--- a/README.md
+++ b/README.md
@@ -10,6 +10,20 @@
 - 최종 후보 내 KOSDAQ: 최대 20개
 - 1차 탐색 총량은 v3와 동일한 200개로 유지하여 호출 수 증가를 막습니다.
 
+## KIS 사용 가이드
+
+이 저장소의 데이터 팩터 수집 기본 코어는 KIS Open API입니다.
+
+- 실제계좌: `KIS_APP_Key`, `KIS_APP_Secret`
+- 모의계좌: `KIS_APP_Key_TEST`, `KIS_APP_Secret_TEST`
+- API 유효성 확인은 모의계좌 환경변수로 수행하고, 데이터 수집은 실제계좌 환경변수로 수행
+- 사용 범위: 조회형 `quotations` / `ranking` 계열만 사용
+- 금지 범위: 주문, 정정, 취소, 잔고조회는 사용하지 않음
+- 폴백 순서: `KIS -> Naver Finance -> Yahoo Finance -> OpenDART -> Investing.com(best-effort)`
+
+CI 스케줄러는 `GatherTradingData.json`을 seed snapshot으로 사용하고, read-only API로 보강한 뒤 SQLite에 누적 저장합니다.
+코드는 저장 백엔드를 `backend contract`로 분리해 두었고, 지금은 SQLite만 실행하지만 향후 PostgreSQL로 옮겨도 수집기 호출부를 크게 바꾸지 않도록 해 둔 상태입니다.
+
 ## 설치
 
 ```powershell
@@ -24,6 +38,52 @@ $env:DART_API_KEY="발급받은키"
 node core_satellite_collector.js
 ```
 
+SQLite 기반 데이터 수집을 실행하려면:
+
+```powershell
+$env:KIS_APP_Key="실제계좌키"
+$env:KIS_APP_Secret="실제계좌시크릿"
+python tools/run_kis_data_collection_v1.py --input-json GatherTradingData.json --sqlite-db outputs/kis_data_collection/kis_data_collection.db --output-json Temp/kis_data_collection_v1.json --kis-account real
+```
+
+### Snapshot admin web UI
+
+엑셀처럼 `settings`와 `account_snapshot`를 편집하려면 웹 UI를 실행한다.
+
+```bash
+python tools/run_snapshot_admin_server_v1.py --db outputs/snapshot_admin/snapshot_admin.db --seed GatherTradingData.json
+```
+
+기본 흐름은 다음과 같다.
+
+1. `GatherTradingData.json` 또는 기존 SQLite DB를 seed로 적재
+2. 웹 화면에서 `settings`와 `account_snapshot`을 검토/편집
+3. 저장 시 SQLite에 반영
+4. 필요하면 `/api/export`로 JSON을 내려받아 CI 또는 검증에 사용
+5. 변경 이력, 승인, 잠금, undo는 웹 화면의 `Approval & Locks` 영역에서 관리
+6. 변경 검토용 승인 패킷은 `Export approval packet` 버튼으로 `Temp/snapshot_admin_approval_packet_v1.json`에 저장한다.
+
+웹 UI 스모크 검증은 아래 명령으로 실행한다.
+
+```bash
+python tools/validate_snapshot_admin_web_v1.py
+```
+```
+
+### Calibration backlog
+
+보정 백로그와 change ledger를 다시 만들려면 아래 명령을 사용한다.
+
+```powershell
+python tools/build_calibration_priority_v1.py
+python tools/build_calibration_change_ledger_v4.py
+python tools/build_calibration_review_report_v1.py
+python tools/build_calibration_approval_list_v1.py
+python tools/validate_calibration_change_ledger_v1.py
+```
+
+Gitea 스케줄러에서는 `.gitea/workflows/calibration_backlog.yml`이 weekday 자동 갱신을 수행한다.
+
 ## 운영 표준
 
 릴리즈와 패키징의 기준 진입점은 아래를 사용합니다.
@@ -52,6 +112,7 @@ npm run prepare-upload-zip
 - `npm run ops:package`
 - `npm run ops:validate`
 - `npm run ops:build`
+- `npm run ops:snapshot-web-validate`
 - `npm run render-report-json`
 - `npm run validate-proposal-reference`
 - `npm run validate-gas-call-arity`
@@ -70,6 +131,14 @@ npm run prepare-upload-zip
 6. `npm run full-gate` 실행
 7. 최종 운영 전환 시 `npm run prepare-upload-zip`로 패키지 생성 여부를 확인
 
+## CI 전환 체크리스트
+
+1. `python tools/run_kis_data_collection_v1.py` 또는 `npm run ops:data-collect`로 SQLite 수집을 먼저 검증
+2. `outputs/kis_data_collection/kis_data_collection.db`에 `collection_runs` / `collection_snapshots`가 생성되는지 확인
+3. Gitea 스케줄러가 `GatherTradingData.json`을 seed로 읽는지 확인
+4. `GatherTradingData.xlsx` 의존성을 제거한 후에도 수집이 유지되는지 확인
+5. 이후 PostgreSQL 업그레이드 시 동일 row contract를 유지
+
 ## 운영 리포트 계약
 
 운영 리포트는 사람이 읽는 `Temp/operational_report.md`와 기계 검증용 `Temp/operational_report.json`을 함께 생성합니다.
diff --git a/package.json b/package.json
index 262a5ab9..f065c3ba 100644
--- a/package.json
+++ b/package.json
@@ -7,7 +7,20 @@
     "ops:prepare": "python tools/convert_xlsx_to_json.py",
     "ops:validate": "python tools/run_release_dag_v3.py --mode release",
     "ops:build": "python tools/build_bundle.py",
+    "ops:data-collect": "python tools/run_kis_data_collection_v1.py --input-json GatherTradingData.json --sqlite-db outputs/kis_data_collection/kis_data_collection.db --output-json Temp/kis_data_collection_v1.json --kis-account real",
+    "ops:sell-build": "python tools/build_qualitative_sell_inputs_v1.py --batch --workbook GatherTradingData.xlsx --kis-account real --apply",
+    "ops:sell-satellite": "python tools/build_satellite_candidate_recommendations_v1.py --workbook GatherTradingData.xlsx --apply",
+    "ops:sell-eval": "python tools/evaluate_qualitative_sell_strategy_accuracy_v1.py --sqlite-db outputs/qualitative_sell_strategy/qualitative_sell_strategy.db",
+    "ops:sell-validate": "python tools/validate_qualitative_sell_strategy_pipeline_v1.py",
+    "ops:postgres-stub": "python tools/generate_postgresql_upgrade_stub_v1.py",
     "ops:render": "python tools/render_operational_report.py --json GatherTradingData.json --output Temp/operational_report.md --report-json-output Temp/operational_report.json",
+    "ops:snapshot-web": "python tools/run_snapshot_admin_server_v1.py --reload --db outputs/snapshot_admin/snapshot_admin.db --seed GatherTradingData.json",
+    "ops:snapshot-validate": "python tools/validate_snapshot_admin_workflow_v1.py",
+    "ops:snapshot-web-validate": "python tools/validate_snapshot_admin_web_v1.py",
+    "ops:calibration-backlog": "python tools/build_calibration_priority_v1.py && python tools/build_calibration_change_ledger_v4.py && python tools/build_calibration_review_report_v1.py && python tools/validate_calibration_change_ledger_v1.py",
+    "ops:calibration-review-report": "python tools/build_calibration_review_report_v1.py",
+    "ops:calibration-approval-list": "python tools/build_calibration_approval_list_v1.py",
+    "ops:calibration-decision-draft": "python tools/build_calibration_decision_draft_v1.py",
     "ops:sector-refresh": "python tools/update_sector_universe_from_naver.py --limit 10",
     "ops:sector-refresh-apply": "python tools/update_sector_universe_from_naver.py --limit 10 --apply",
     "ops:sector-validate": "python tools/validate_sector_universe_monthly_refresh_v1.py",
@@ -26,6 +39,9 @@
     "validate-prediction-accuracy-harness": "python tools/validate_prediction_accuracy_harness_v2.py",
     "validate-alpha-feedback-loop": "python tools/validate_alpha_feedback_loop_v2.py",
     "validate-operational-alpha-calibration": "python tools/validate_operational_alpha_calibration_v2.py",
+    "build-calibration-priority": "python tools/build_calibration_priority_v1.py",
+    "build-calibration-change-ledger": "python tools/build_calibration_change_ledger_v4.py",
+    "validate-calibration-change-ledger": "python tools/validate_calibration_change_ledger_v1.py",
     "validate-sector-flow-history-progress": "python tools/validate_sector_flow_history_progress_v1.py",
     "validate-realized-performance": "python tools/validate_realized_performance_v1.py",
     "validate-gas-recovery": "python tools/validate_gas_orchestration_recovery_v1.py",
diff --git a/runtime/refactor_baseline_v1.yaml b/runtime/refactor_baseline_v1.yaml
index c3b383c5..0641e872 100644
--- a/runtime/refactor_baseline_v1.yaml
+++ b/runtime/refactor_baseline_v1.yaml
@@ -1,7 +1,7 @@
 {
   "formula_id": "AUDIT_REPOSITORY_ENTROPY_V2",
   "gate": "PASS",
-  "total_file_count": 1896,
+  "total_file_count": 1903,
   "package_script_count": 32,
   "temp_json_count": 194,
   "budget": {
@@ -15,5 +15,5 @@
       "keep package scripts within release envelope"
     ]
   },
-  "source_zip_sha256": "3ac3719981890d601de8d49a0d43fdb6a88c0b95d5503d7e2a6e5df4d35eb18c"
+  "source_zip_sha256": "e92fc1d43216b2d8ca79bfda0976f7bb443f0d590ce2456aac2568e27dce1be2"
 }
\ No newline at end of file
diff --git a/src/gas/core/gas_lib.gs b/src/gas/core/gas_lib.gs
index 24c3884f..e9be0a2c 100644
--- a/src/gas/core/gas_lib.gs
+++ b/src/gas/core/gas_lib.gs
@@ -2467,6 +2467,29 @@ function doPost(e) {
         .createTextOutput(JSON.stringify(result, null, 2))
         .setMimeType(ContentService.MimeType.JSON);
     }
+    if (action === "trigger_run_all") {
+      // 외부(Gitea CI) 스케줄러가 run_all()을 원격 트리거할 수 있게 하는 진입점.
+      // run_all은 매수/매도 주문을 실행하지 않는다(데이터 갱신·분석 전용) — governance
+      // 06/07과 동일한 "조회/분석만, 주문 없음" 원칙을 따른다. 공유 비밀키로 무단 호출 차단.
+      const expectedSecret = String(PropertiesService.getScriptProperties().getProperty("RUN_ALL_TRIGGER_SECRET") || "");
+      const providedSecret = String(payload.secret || "");
+      if (!expectedSecret || providedSecret !== expectedSecret) {
+        return ContentService
+          .createTextOutput(JSON.stringify({ status: "ERROR", message: "unauthorized" }, null, 2))
+          .setMimeType(ContentService.MimeType.JSON);
+      }
+      const startedAt = new Date().toISOString();
+      try {
+        run_all();
+        return ContentService
+          .createTextOutput(JSON.stringify({ status: "OK", started_at: startedAt, finished_at: new Date().toISOString() }, null, 2))
+          .setMimeType(ContentService.MimeType.JSON);
+      } catch (runErr) {
+        return ContentService
+          .createTextOutput(JSON.stringify({ status: "ERROR", message: String(runErr && runErr.message ? runErr.message : runErr) }, null, 2))
+          .setMimeType(ContentService.MimeType.JSON);
+      }
+    }
     return ContentService
       .createTextOutput(JSON.stringify({
         status: "ERROR",
diff --git a/tools/trigger_gas_run_all_v1.py b/tools/trigger_gas_run_all_v1.py
new file mode 100644
index 00000000..d703ce0a
--- /dev/null
+++ b/tools/trigger_gas_run_all_v1.py
@@ -0,0 +1,51 @@
+"""GAS run_all()을 Gitea CI 스케줄러에서 원격 트리거.
+
+언어 선택: Python — 이미 이 저장소의 모든 CI/도구가 Python이고(requests만으로 HTTP POST
+한 번이면 충분), 새 언어를 도입할 이유가 없다(불필요한 복잡성 증가 경계).
+
+대상 엔드포인트: src/gas/core/gas_lib.gs:doPost action="trigger_run_all" — 공유 비밀키로
+보호된 GAS 웹앱. run_all()은 데이터 갱신/분석만 수행하며 매수/매도 주문을 실행하지
+않는다(governance/rules/06,07과 동일 원칙).
+
+필요한 자격정보(Windows 환경변수, KIS와 동일한 레지스트리 폴백 사용):
+  GAS_WEBAPP_URL            — Apps Script 배포 웹앱 URL
+  RUN_ALL_TRIGGER_SECRET    — gas_lib.gs Script Properties에 설정한 것과 동일한 값
+"""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import requests
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from src.quant_engine.kis_api_client_v1 import _read_env_var  # 동일한 env+registry 폴백 재사용
+
+
+def trigger_run_all(timeout_sec: int = 280) -> dict:
+    webapp_url = _read_env_var("GAS_WEBAPP_URL")
+    secret = _read_env_var("RUN_ALL_TRIGGER_SECRET")
+    if not webapp_url or not secret:
+        return {"status": "ERROR", "message": "GAS_WEBAPP_URL/RUN_ALL_TRIGGER_SECRET 환경변수 없음"}
+
+    resp = requests.post(
+        webapp_url,
+        json={"action": "trigger_run_all", "secret": secret},
+        timeout=timeout_sec,
+    )
+    resp.raise_for_status()
+    return resp.json()
+
+
+def main() -> int:
+    result = trigger_run_all()
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0 if result.get("status") == "OK" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/tools/validate_platform_transition_wbs_v1.py b/tools/validate_platform_transition_wbs_v1.py
new file mode 100644
index 00000000..b22bec5f
--- /dev/null
+++ b/tools/validate_platform_transition_wbs_v1.py
@@ -0,0 +1,294 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import sqlite3
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+SPEC_PATH = ROOT / "spec" / "16_data_gaps_roadmap.yaml"
+ROADMAP_DOC_PATH = ROOT / "docs" / "ROADMAP_WBS.md"
+
+
+def _read_json(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def _read_text(path: Path) -> str:
+    if not path.exists():
+        return ""
+    return path.read_text(encoding="utf-8", errors="replace")
+
+
+def _sqlite_counts(db_path: Path) -> dict[str, int]:
+    if not db_path.exists():
+        return {}
+    conn = sqlite3.connect(db_path)
+    try:
+        return {
+            "collection_runs": conn.execute("SELECT COUNT(*) FROM collection_runs").fetchone()[0],
+            "collection_snapshots": conn.execute("SELECT COUNT(*) FROM collection_snapshots").fetchone()[0],
+            "collection_source_errors": conn.execute("SELECT COUNT(*) FROM collection_source_errors").fetchone()[0],
+        }
+    finally:
+        conn.close()
+
+
+def _load_spec() -> dict[str, Any]:
+    return yaml.safe_load(SPEC_PATH.read_text(encoding="utf-8"))
+
+
+def _check_p1() -> dict[str, Any]:
+    summary_path = ROOT / "Temp" / "test_kis_data_collection.json"
+    db_path = ROOT / "Temp" / "test_kis_data_collection.db"
+    summary = _read_json(summary_path)
+    counts = _sqlite_counts(db_path)
+    errors: list[str] = []
+
+    if summary.get("status") != "PASS":
+        errors.append(f"summary_status={summary.get('status')!r}")
+    if int(summary.get("row_count") or 0) <= 0:
+        errors.append("summary_row_count<=0")
+    if int(counts.get("collection_runs") or 0) <= 0:
+        errors.append("collection_runs<=0")
+    if int(counts.get("collection_snapshots") or 0) <= 0:
+        errors.append("collection_snapshots<=0")
+
+    source_counts = summary.get("source_counts") if isinstance(summary.get("source_counts"), dict) else {}
+    source_count = len([k for k, v in source_counts.items() if int(v or 0) > 0])
+    if source_count < 1:
+        errors.append(f"provenance_source_count={source_count}")
+
+    return {
+        "gate": "PASS" if not errors else "FAIL",
+        "expected_success_value": {
+            "collector_gate": "PASS",
+            "output_json_gate": "PASS",
+            "collection_runs_min": 1,
+            "collection_snapshots_min": 1,
+            "provenance_source_count_min": 1,
+        },
+        "evidence": {
+            "summary_path": str(summary_path),
+            "db_path": str(db_path),
+            "sqlite_counts": counts,
+        },
+        "errors": errors,
+    }
+
+
+def _check_p2() -> dict[str, Any]:
+    from src.quant_engine.data_collection_backend_v1 import CollectionStoreSpec, normalize_store_spec
+
+    db_path = ROOT / "Temp" / "test_kis_data_collection.db"
+    counts = _sqlite_counts(db_path)
+    sqlite_backend, sqlite_location = normalize_store_spec(CollectionStoreSpec(location=db_path), ROOT)
+    pg_backend, pg_location = normalize_store_spec(
+        CollectionStoreSpec(backend="postgresql", location="postgresql://user:pass@localhost/db"),
+        ROOT,
+    )
+    errors: list[str] = []
+
+    if sqlite_backend != "sqlite":
+        errors.append(f"sqlite_backend={sqlite_backend!r}")
+    if pg_backend != "postgresql":
+        errors.append(f"postgres_backend={pg_backend!r}")
+    if not isinstance(pg_location, str) or "postgresql://" not in pg_location:
+        errors.append("postgres_location_invalid")
+    if int(counts.get("collection_runs") or 0) <= 0 or int(counts.get("collection_snapshots") or 0) <= 0:
+        errors.append("sqlite_round_trip_missing")
+
+    return {
+        "gate": "PASS" if not errors else "FAIL",
+        "expected_success_value": {
+            "sqlite_schema_tables_min": 3,
+            "round_trip_snapshot_lookup": "PASS",
+            "backend_contract_sqlite": "PASS",
+            "backend_contract_postgresql": "READY",
+        },
+        "evidence": {
+            "db_path": str(db_path),
+            "sqlite_location": str(sqlite_location),
+            "postgres_location": pg_location,
+            "sqlite_counts": counts,
+        },
+        "errors": errors,
+    }
+
+
+def _check_p3() -> dict[str, Any]:
+    workflow = ROOT / ".gitea" / "workflows" / "kis_data_collection.yml"
+    text = _read_text(workflow)
+    errors: list[str] = []
+
+    if not text:
+        errors.append("workflow_missing")
+    if "tools/run_kis_data_collection_v1.py" not in text:
+        errors.append("collector_step_missing")
+    if "tools/validate_kis_api_credentials_v1.py" not in text:
+        errors.append("mock_validation_step_missing")
+    if "GatherTradingData.json" not in text:
+        errors.append("seed_json_missing")
+    if "Validate SQLite Artifact" not in text:
+        errors.append("sqlite_validation_step_missing")
+    if ".xlsx" in text or "GatherTradingData.xlsx" in text:
+        errors.append("xlsx_dependency_present")
+    if "validate_no_direct_api_trading_v1.py" not in text:
+        errors.append("no_direct_trading_gate_missing")
+    if text.count("KIS_APP_Key_TEST") != 1 or text.count("KIS_APP_Secret_TEST") != 1:
+        errors.append("mock_env_vars_not_isolated")
+    if text.count("KIS_APP_Key:") != 1 or text.count("KIS_APP_Secret:") != 1:
+        errors.append("real_env_vars_not_isolated")
+
+    return {
+        "gate": "PASS" if not errors else "FAIL",
+        "expected_success_value": {
+            "xlsx_dependency_removed": True,
+            "json_seed_input": True,
+            "sqlite_output": True,
+            "mock_api_validation": "PASS",
+            "no_direct_trading_gate": "PASS",
+        },
+        "evidence": {
+            "workflow_path": str(workflow),
+        },
+        "errors": errors,
+    }
+
+
+def _check_p4() -> dict[str, Any]:
+    validation_path = ROOT / "Temp" / "gas_thin_adapter_validation_v1.json"
+    payload = _read_json(validation_path)
+    errors: list[str] = []
+
+    if payload.get("gate") != "PASS":
+        errors.append(f"gate={payload.get('gate')!r}")
+    if float(payload.get("function_inventory_coverage_pct") or 0.0) < 100.0:
+        errors.append("function_inventory_coverage_pct<100")
+    if not (ROOT / "src" / "gas" / "core" / "gas_lib.gs").exists():
+        errors.append("gas_lib_missing")
+
+    return {
+        "gate": "PASS" if not errors else "FAIL",
+        "expected_success_value": {
+            "allowed_responsibilities_only": True,
+            "forbidden_responsibilities_present": False,
+            "thin_adapter_gate": "PASS",
+        },
+        "evidence": {
+            "validation_path": str(validation_path),
+            "payload": payload,
+        },
+        "errors": errors,
+    }
+
+
+def _check_p5() -> dict[str, Any]:
+    from src.quant_engine.data_collection_backend_v1 import CollectionStoreSpec, normalize_store_spec
+
+    backend_path = ROOT / "src" / "quant_engine" / "data_collection_backend_v1.py"
+    collector_path = ROOT / "src" / "quant_engine" / "kis_data_collection_v1.py"
+    test_path = ROOT / "tests" / "unit" / "test_data_collection_store_v1.py"
+    wrapper_path = ROOT / "tools" / "run_kis_data_collection_v1.py"
+    migration_stub_path = ROOT / "tools" / "generate_postgresql_upgrade_stub_v1.py"
+    errors: list[str] = []
+
+    try:
+        backend, location = normalize_store_spec(
+            CollectionStoreSpec(backend="postgresql", location="postgresql://user:pass@localhost/db"),
+            ROOT,
+        )
+        if backend != "postgresql":
+            errors.append(f"backend={backend!r}")
+        if not isinstance(location, str) or "postgresql://" not in location:
+            errors.append("postgres_location_invalid")
+    except Exception as exc:  # noqa: BLE001
+        errors.append(f"normalize_failed={exc}")
+
+    for path in (backend_path, collector_path, test_path, wrapper_path):
+        if not path.exists():
+            errors.append(f"missing={path.relative_to(ROOT)}")
+    if not migration_stub_path.exists():
+        errors.append(f"missing={migration_stub_path.relative_to(ROOT)}")
+
+    return {
+        "gate": "PASS" if not errors else "FAIL",
+        "expected_success_value": {
+            "sqlite_schema_parity": "PASS",
+            "backend_contract_present": True,
+            "postgres_execution": "DATA_GATED",
+            "caller_compatibility_preserved": True,
+        },
+        "evidence": {
+            "backend_path": str(backend_path),
+            "collector_path": str(collector_path),
+            "test_path": str(test_path),
+            "wrapper_path": str(wrapper_path),
+            "migration_stub_path": str(migration_stub_path),
+        },
+        "errors": errors,
+    }
+
+
+def main() -> int:
+    spec = _load_spec()
+    phase = spec.get("phase_5_platform_transition") or {}
+    roadmap_text = _read_text(ROADMAP_DOC_PATH)
+    checks = {
+        "P1_kis_core_api_collector": _check_p1(),
+        "P2_sqlite_canonical_store": _check_p2(),
+        "P3_ci_scheduler_cutover": _check_p3(),
+        "P4_gas_thin_adapter_minimize": _check_p4(),
+        "P5_postgresql_upgrade_path": _check_p5(),
+    }
+
+    missing_criteria: list[str] = []
+    for key, result in checks.items():
+        spec_row = phase.get(key) or {}
+        criteria = spec_row.get("success_criteria") or {}
+        if not criteria:
+            missing_criteria.append(key)
+        if "expected_success_value" not in criteria:
+            missing_criteria.append(f"{key}.expected_success_value")
+        if "evidence_artifacts" not in criteria:
+            missing_criteria.append(f"{key}.evidence_artifacts")
+        if "verification_commands" not in criteria:
+            missing_criteria.append(f"{key}.verification_commands")
+        if result["gate"] != "PASS":
+            missing_criteria.append(f"{key}.evidence_gate")
+
+    roadmap_mentions = [
+        "Phase 5 데이터 플랫폼 전환 WBS 성공값",
+        "P1 KIS core collector",
+        "P2 SQLite canonical store",
+        "P3 CI scheduler cutover",
+        "P4 GAS thin adapter minimize",
+        "P5 PostgreSQL upgrade path",
+    ]
+    roadmap_missing = [item for item in roadmap_mentions if item.lower() not in roadmap_text.lower()]
+
+    payload = {
+        "formula_id": "PLATFORM_TRANSITION_WBS_V1",
+        "gate": "PASS" if not missing_criteria and not roadmap_missing else "FAIL",
+        "spec_path": str(SPEC_PATH),
+        "roadmap_doc_path": str(ROADMAP_DOC_PATH),
+        "missing_criteria": missing_criteria,
+        "roadmap_missing": roadmap_missing,
+        "checks": checks,
+    }
+    out = ROOT / "Temp" / "platform_transition_wbs_v1.json"
+    out.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+    return 0 if payload["gate"] == "PASS" else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

From 0cec44a0e1a80d05148774e590d89926578f75cc Mon Sep 17 00:00:00 2001
From: kjh2064 
Date: Sun, 21 Jun 2026 20:12:09 +0900
Subject: [PATCH 10/10] =?UTF-8?q?=EC=A0=95=EC=84=B1=EB=A7=A4=EB=8F=84?=
 =?UTF-8?q?=EC=A0=84=EB=9E=B5=20=EA=B3=B5=EC=8B=9D=20=EB=A0=88=EC=A7=80?=
 =?UTF-8?q?=EC=8A=A4=ED=8A=B8=EB=A6=AC=20=EB=93=B1=EB=A1=9D=20+=20?=
 =?UTF-8?q?=EB=A1=9C=EB=93=9C=EB=A7=B5=20=EB=B9=84=ED=8C=90=EC=A0=81=20?=
 =?UTF-8?q?=EB=A6=AC=EB=B7=B0=20=EC=A2=85=ED=95=A9=20=EA=B0=B1=EC=8B=A0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- spec/13b_harness_formulas.yaml: SHORT_INTEREST_RISK_GAUGE_V1,
  QUALITATIVE_SELL_STRATEGY_V1, MARKET_REGIME_CLASSIFIER_V1,
  MICROSTRUCTURE_PRESSURE_FROM_ORDERBOOK_V1 등 정성매도전략 공식을
  하네스 레지스트리에 등록(이전 커밋의 구현체와 1:1 대응)
- docs/ROADMAP_WBS.md: 2026-06-21 비판적 리뷰(0c절) + WBS-7.1~7.11
  보완·고도화 전체를 반영 — 캘리브레이션 0/191 CALIBRATED 실태, T+5
  지표 불일치 해소, GAS 마이그레이션 재검토, deprecated 정리, 통합테스트,
  Tabler 그리드, spec-코드 동기화 게이트, KRX 자동화 실측까지 포함한
  완성도 매트릭스·KPI·스프린트 체크리스트 갱신
---
 docs/ROADMAP_WBS.md            | 471 ++++++++++++++++++++++++++++++++-
 spec/13b_harness_formulas.yaml |  71 +++++
 2 files changed, 541 insertions(+), 1 deletion(-)

diff --git a/docs/ROADMAP_WBS.md b/docs/ROADMAP_WBS.md
index c1584033..842f307a 100644
--- a/docs/ROADMAP_WBS.md
+++ b/docs/ROADMAP_WBS.md
@@ -18,6 +18,60 @@
 
 ---
 
+## 0c. 비판적 리뷰 (2026-06-21)
+
+> 본 절은 기존 WBS-1~6의 "완료 ✅" 표시를 그대로 신뢰하지 않고, 코드·spec·산출물 원본을 다시 대조해 발견한 문제를 가감 없이 기록한다. 발견된 문제는 Phase 7(WBS-7)로 추적한다.
+
+### 재검증 결과 — 두 문서가 서로 다른 T+5 수치를 인용하고 있었다
+
+기존 §4(엔진 완성도 KPI)는 `예측 적중률(T+5) = 54.76%`(목표 근접 PASS 톤)를 인용했고, `spec/27_bch_calibration_runbook.yaml` Phase 4는 `T+5 = 35.86%`(목표 55%, BELOW_TARGET)를 인용했다. **2026-06-21 기준 `Temp/prediction_accuracy_harness_v2.json` 원본을 재확인한 결과, 두 수치 모두 이미 stale 하다:**
+
+```
+as_of_date: 2026-06-21
+calibration_state: INSUFFICIENT_SAMPLES
+t1_op_rate: 52.94% (sample=68, decisive_sample=53, rate_decisive=67.92%)
+t5_op_rate: null   (sample=0)  ← 두 문서의 54.76%/35.86% 모두 현재는 산출 불가
+t20_op_rate: null  (sample=0)
+```
+
+즉 T+5 표본이 현재 **0건**이라 어느 쪽 수치도 "지금" 유효하지 않다. 파일 mtime 대조 결과 `Temp/honest_performance_guard_v1.json`(35.86%, 2026-06-14 생성)이 `Temp/prediction_accuracy_harness_v2.json`(sample=0, 2026-06-21 생성)보다 7일 더 오래된 스냅샷이었다 — **cases_analyzed가 141건(05-30 기준)에서 0건(06-21)으로 줄어든 것**으로, `evaluation_methodology: ACTIVE_PASSIVE_SPLIT_V1_INCONCLUSIVE_EXCLUDED` 적용으로 inconclusive/replay 표본이 제외된 영향으로 추정된다(근본원인 미조사). → **WBS-7.2 완료**: `spec/27_bch_calibration_runbook.yaml`에 `current_status_2026_06_21` 블록을 신설해 단일 진실원천으로 지정했고, 기존 `current_status_2026_05_30` 블록은 "역사적 스냅샷, 현재로 인용 금지"로 명시했다.
+
+### 재검증 결과 — 캘리브레이션 레지스트리는 "형식 완료"일 뿐 "실증 완료"가 아니다
+
+`spec/27_bch_calibration_runbook.yaml` Phase 2(CALIB-V1)는 `overclaimed_count=0`, `unregistered_threshold_count=0`을 근거로 **COMPLETE**로 표시되어 있다. 그러나 `spec/calibration_registry.yaml` 전체(190개 임계값)를 직접 집계하면:
+
+| source | 건수 | 비율 | 의미 |
+|--------|------|------|------|
+| `SPEC_DERIVED` | 123 | 64.7% | spec 문서 값을 그대로 복사 — 실거래 검증 없음 |
+| `EXPERT_PRIOR` | 59 | 31.1% | 30년 경험 기반 직관값 — sample_n<30, 실거래 검증 없음 |
+| `PROVISIONAL` | 8 | 4.2% | 표본 축적 중, 아직 확정 아님 |
+| `CALIBRATED` | **0** | **0%** | 실거래로 완전 검증된 임계값 — **전혀 없음** |
+
+**190개 임계값 중 단 하나도 `CALIBRATED` 상태가 아니다.** "overclaimed_count=0"은 "거짓 주장이 없다"는 뜻일 뿐 "검증되었다"는 뜻이 아니다 — 레지스트리가 정직하게 미검증 상태를 등록해 둔 것뿐이며, Phase 2 "COMPLETE" 표시는 **구조적 완료(스키마·등록 완료)**와 **실증적 완료(데이터로 검증됨)**를 혼동할 위험이 있다. → **⚠️ 표시 수정**: Phase 2(CALIB-V1) = "구조적으로 COMPLETE, 실증적으로는 0/190 검증" 으로 재서술. → **WBS-7.1**로 추적.
+
+### 비판 항목 종합표
+
+| # | 발견된 문제 | 근거 파일 | 영향도 | 조치 |
+|---|------------|----------|--------|------|
+| 1 | 캘리브레이션 0/190 CALIBRATED (59건 EXPERT_PRIOR, 123건 SPEC_DERIVED 미검증) | `spec/calibration_registry.yaml` (직접 집계) | 🔴 | WBS-7.1 |
+| 2 | T+5 정확도 지표가 문서마다 다른 stale 캐시값을 인용 (54.76% vs 35.86%, 실제는 sample=0) | `Temp/prediction_accuracy_harness_v2.json`, `spec/27_bch_calibration_runbook.yaml` | 🔴 | WBS-7.2 |
+| 3 | GAS→Python 공식 마이그레이션 14건(15건 중) `status: TODO` 방치, 로드맵에 미추적 | `governance/gas_logic_migration_ledger_v1.yaml` | 🟠 | WBS-7.3 |
+| 4 | Deprecated 별칭 17건 `remove_after: 2026-06-30` — 오늘 기준 9일 전 데드라인, WBS 추적 없음 | `spec/aliases.yaml` | 🟠 | WBS-7.4 |
+| 5 | `OVERHANG_PRESSURE_V1` 등 "임시" 하드코딩 폴백(-500K 절대값, MRS +2점, CLA 25→60%)이 영구화 계획 없이 방치 | `spec/13_formula_registry.yaml:1222`, `spec/risk/circuit_breakers.yaml:192`, `spec/risk/portfolio_exposure.yaml:403` | 🟡 | WBS-7.5 |
+| 6 | 슬리피지 5bps가 이론치, 실측 보정 트리거/일정 없음 | `spec/55_execution_simulator_contract.yaml:21` | 🟡 | WBS-7.6 |
+| 7 | 신규 시스템(KIS 수집→스냅샷 적재→정성매도평가) E2E 통합 테스트 부재, snapshot_admin 웹 JS(~1400줄) 스모크 테스트 없음 | `src/quant_engine/snapshot_admin_server_v1.py`, `tests/unit/test_*_v1.py` (단위 61건은 양호, 통합 0건) | 🟠 | WBS-7.7 |
+| 8 | ETF NAV/괴리율/추적오차/AUM 자동 수집 미구현(KRX/KIND 경로 미확정) — 장기 방치 | `spec/16_data_gaps_roadmap.yaml` S4/S5 | 🟡 | WBS-7.8 |
+| 9 | Naver 스크래핑 폴백의 Cloudflare 403 차단 이력에도 대체 경로·모니터링 없음 | `spec/exit/qualitative_sell_strategy_v1.yaml:81-82` | 🟡 | WBS-7.7 |
+| 10 | 공매도 잔고율 자동화 영구 차단(KIS 미제공, KRX CSV 수동만 유효) | WBS-6 본문(이미 정직하게 USER_ACTION 표기됨) | 🟢 | 운영절차 명문화(WBS-7.8 부속) |
+
+### 기존 "완료 ✅" 표시 재검토
+
+- **WBS-4.1/4.2/4.3 (DATA_GATED)**: 정직하게 표기됨 — 도전 불필요, 그대로 유지.
+- **Phase 2 캘리브레이션(CALIB-V1) "COMPLETE"**: → **"⚠️ 구조적 완료, 실증 미완료(0/190 CALIBRATED)"**로 정정.
+- **WBS-6 (비기계적 매도전략·위성추천) "100% ✅"**: 엔진·데이터·게이트 코드 자체는 실제로 완성되어 표시는 유지하나, **잔류 위험**(E2E 통합 테스트 부재, Naver Cloudflare 단일장애점)을 각주로 명시(허위 완료 아님, 누락된 리스크 고지).
+
+---
+
 ## 0. 프로젝트 비전 & 방향성
 
 ### 핵심 목표
@@ -48,6 +102,8 @@ Phase 2  ████████████████░░░░  신호 
 Phase 3  ████████████████████  실행·리스크 관리 (Execution & Risk)  [완료 ✅]
 Phase 4  █████░░░░░░░░░░░░░░░  성과 인텔리전스 (Performance)        [25% — 4.1~4.3 DATA_GATED]
 Phase 5  ████████████████████  완전 자동화 (Full Automation)        [완료 ✅]
+Phase 6  ████████████████████  비기계적 매도전략·위성추천          [완료 ✅ — 잔류위험 명시, 0c절 참조]
+Phase 7  ░░░░░░░░░░░░░░░░░░░░  보완·고도화 (Critical Hardening)    [0% — 0c절 비판 10건 대응, 신규 착수 대기]
 ```
 
 | Phase | 기간 목표 | 핵심 산출물 | 완료 기준 |
@@ -57,6 +113,8 @@ Phase 5  ████████████████████  완전 
 | **P3 실행·리스크** | 2026-06 완료 | 리밸런싱 엔진 V1, 3단계 분할 주문 | 실제 주문 3회 이상 |
 | **P4 성과 인텔리전스** | ~2026-10 | T+20 결과 30건, 알파 보정 루프 | match_rate ≥ 55% |
 | **P5 완전 자동화** | ~2026-12 | CI/CD + Gitea, 자율 실행 | 수동 개입 0회/주 |
+| **P6 비기계적 매도전략** | 2026-06 완료 | 5팩터 confluence 엔진, KIS 조회연동, SQLite 자체평가 | WBS-6 본문 하네스 PASS (잔류위험은 P7에서 해소) |
+| **P7 보완·고도화** | ~2026-08 | 캘리브레이션 실증 전환, GAS 마이그레이션 완결, deprecated 정리, E2E 통합테스트 | WBS-7.1~7.8 하네스 전부 PASS |
 
 ---
 
@@ -526,6 +584,355 @@ CI 게이트:
 
 ---
 
+### WBS-6: 비기계적 매도전략 & 위성추천 (Phase 6, 2026-06-21)
+
+**운영 원칙(30년 시니어 퀀트 관점 — 이 Phase의 모든 작업이 따르는 단일 기준)**
+
+| 원칙 | 이 Phase에서의 구현 |
+|------|---------------------|
+| 가치보존이 목적, 매도가 목적 아님 | confluence 최소 3/5 합의 없이는 매도 트리거 금지(`mechanical_sell_prohibited=true`) |
+| 추정 금지, 신뢰 데이터만 | 데이터 결측 시 항상 `DATA_MISSING`/`INSUFFICIENT_DATA_NO_ACTION` — 추정값으로 채우지 않음 |
+| 데이터 정합성 | 출처별 실측 상태를 코드 주석·spec에 고정(WORKING/MANUAL_CSV_ONLY/USER_ACTION 등), 추측 표기 금지 |
+| 일관된 알고리즘 | 5팩터·confluence 규칙·국면 가중치가 보유종목/위성후보 평가에 동일하게 적용 |
+| 지속적 자체평가 | SQLite 시계열(`qualitative_sell_strategy.db`) + 사후 적중률 평가(`evaluate_qualitative_sell_strategy_accuracy_v1.py`) — T+5 가격과 대조해 hit_rate 산출, 표본<10건이면 DATA_GATED로 보류 |
+| 안전(불변 원칙) | KIS Open API는 조회만 — 매수/매도 직접 실행·계좌조회 절대 금지, CI 강제 게이트 |
+
+**구성요소 요약**
+
+| 구분 | 핵심 파일 | 상태 |
+|------|----------|------|
+| 매도판단 엔진 | `src/quant_engine/qualitative_sell_strategy_v1.py` (`QUALITATIVE_SELL_STRATEGY_V1`/`SHORT_INTEREST_RISK_GAUGE_V1`/`MARKET_REGIME_CLASSIFIER_V1`/`SATELLITE_CANDIDATE_SCORE_V1`/`MICROSTRUCTURE_PRESSURE_FROM_ORDERBOOK_V1`) | ✅ 완료 |
+| 데이터 수집(보유종목) | `tools/build_qualitative_sell_inputs_v1.py` + `build_macro_context_from_workbook_v1.py`(실워크북 연동) + `fetch_naver_market_data_v1.py` + `fetch_trade_statistics_motie_v1.py` | ✅ 완료 — 10/10 보유종목 오류 0건 |
+| KIS Open API 보강 | `src/quant_engine/kis_api_client_v1.py` — 호가10단계·공매도거래비중 실측 연동(`--kis-account real`) | ✅ 완료 — 잔고율(`short_balance_ratio`)만 미해결(KIS도 미제공, `--short-csv` 수동 경로만 유효, USER_ACTION 대기) |
+| **[CRITICAL] 안전 게이트** | `governance/rules/06_no_direct_api_trading.yaml`, `07_no_kis_account_balance_query.yaml`, `tools/validate_no_direct_api_trading_v1.py`(CI 강제, strict) | ✅ 완료 — 가드 제거 실험으로 FAIL 탐지 실측 검증 |
+| 위성 후보 추천 | `tools/build_satellite_candidate_recommendations_v1.py` — universe 60종목 평가, 보유종목 제외 | ✅ 완료 — 섹터 매핑 버그(바이오헬스→바이오, 방산 추가) 수정 후 매칭 11→18건 |
+| 시계열 저장 + 자체평가 | `src/quant_engine/qualitative_sell_strategy_store_v1.py`(SQLite, GAS/xlsx와 독립) + `tools/evaluate_qualitative_sell_strategy_accuracy_v1.py` | ✅ 완료 — 평가 루프는 결정 누적 전까지 정직하게 DATA_GATED 보고 |
+| 운영 스케줄러 | `.gitea/workflows/kis_data_collection.yml` — 영업일 08~17시 2시간 간격 + 수동 실행 | ✅ 완료 — Gitea repo secrets(`KIS_APP_KEY` 등) 등록은 USER_ACTION |
+
+**향후 확장 시 고려사항(지금 구현하지 않음, 설계만 호환 유지)**
+- DB 엔진: SQLite → PostgreSQL 전환 가능성을 고려해 `qualitative_sell_strategy_store_v1.py`는 `insert_*`/`fetch_*` 함수 뒤로 SQL을 전부 숨겼다 — 호출부(오케스트레이터)는 DB 엔진을 모른다. 전환 시 이 한 파일의 내부 구현만 바꾸면 된다(AUTOINCREMENT→SERIAL 등 방언 차이만 해당 파일 내부 문제).
+- 공매도 잔고율은 KRX 공매도종합포털 CSV 외 경로가 없음을 실측으로 확정했으므로, 재시도성 스크래핑 시도는 더 이상 하지 않는다.
+
+**검증 명령**:
+```
+python -m pytest tests/unit -q                              → 40 passed
+python tools/validate_no_direct_api_trading_v1.py            → PASS (strict)
+python tools/validate_specs.py / validate_formula_registry.py /
+  validate_golden_coverage_100.py / validate_harness_coverage_auditor.py → 전부 PASS
+python tools/build_qualitative_sell_inputs_v1.py --batch --workbook GatherTradingData.xlsx --kis-account real
+  → 10/10 종목 오류 0건, BATCH_GATE: PASS
+```
+
+---
+
+### WBS-7: 보완·고도화 (Phase 7, 2026-06-21 비판적 리뷰 대응)
+
+> 0c절에서 발견된 10개 문제에 대한 추적 WBS. 모든 항목은 착수 전이며 상태는 `TODO`.
+
+#### WBS-7.1 캘리브레이션 임계값 실증 전환 (EXPERT_PRIOR/SPEC_DERIVED → PROVISIONAL → CALIBRATED)
+
+| 항목 | 내용 |
+|------|------|
+| **작업** | 190개 임계값 중 `EXPERT_PRIOR`(59)·`SPEC_DERIVED`(123)를 실거래 표본 누적 순으로 `PROVISIONAL`→`CALIBRATED` 전환 |
+| **현재 상태** | `CALIBRATED` 0/190 (0%), `PROVISIONAL` 8/190 (4.2%) |
+| **우선순위** | `Temp/calibration_priority_v1.json`의 urgency score 상위 항목부터 |
+| **담당 파일** | `tools/build_calibration_priority_v1.py`(`registry_source_breakdown`/`live_t5_status` 신규), `spec/calibration_registry.yaml` |
+| **상태** | 도구 보강 완료(2026-06-21) — **CALIBRATED 승격 자체는 실거래 데이터 부재로 여전히 DATA_GATED** |
+
+**부수 발견 — 데이터 무결성 버그**: `spec/calibration_registry.yaml`에 `id: SEMI_CLUSTER_CAP_RISK_OFF`가 **서로 다른 두 공식(값 20.0/25.0)에 중복 등록**되어 있었다. id로 dict 조회하는 도구(`build_calibration_priority_v1.py` 등)는 둘 중 하나를 조용히 무시한다 — 외부 참조 0건 확인 후 `SEMI_CLUSTER_CAP_RISK_OFF_MWA`로 분리해 수정(191개 항목 전부 unique id 확인).
+
+**성공 하네스 (데이터 기준)**:
+```
+검증: python tools/build_calibration_priority_v1.py
+결과: [캘리브레이션 레지스트리 건강도] total=191 {'SPEC_DERIVED': 123, 'EXPERT_PRIOR': 60, 'PROVISIONAL': 8, 'CALIBRATED': 0}
+     CALIBRATED=0.0%  미검증(SPEC_DERIVED+EXPERT_PRIOR)=95.81%
+     → 매 실행마다 자동 집계되어 더 이상 수동 grep 불필요(이전엔 수동 집계해야 했음)
+     T+5 수치도 Temp/prediction_accuracy_harness_v2.json에서 항상 live로 읽음(하드코딩된
+     35.86 리터럴을 제거 — WBS-7.2와 동일한 stale-수치 문제가 이 도구에도 있었음)
+회귀: python -m pytest tests/unit/test_calibration_priority_v1.py -q → 5 passed
+목표(1차, 미달성 — DATA_GATED): CALIBRATED ≥ 10건 (sample_n≥30 + 실측 backtest 노트 보유)
+목표(2차, 미달성 — DATA_GATED): PROVISIONAL ≥ 30건
+```
+
+---
+
+#### WBS-7.2 T+5/예측정확도 지표 단일 진실원천 통일
+
+| 항목 | 내용 |
+|------|------|
+| **작업** | ROADMAP §4와 `spec/27_bch_calibration_runbook.yaml`이 서로 다른 시점의 T+5 캐시값을 인용하던 문제 해결 — 모든 문서가 `Temp/prediction_accuracy_harness_v2.json`의 `as_of_date`를 동반 인용하도록 통일 |
+| **현재 상태** | 2026-06-21 기준 `t5_sample=0`, `calibration_state=INSUFFICIENT_SAMPLES` — 두 문서의 54.76%/35.86% 모두 stale |
+| **담당 파일** | `tools/build_prediction_accuracy_harness_v2.py`, `docs/ROADMAP_WBS.md` §4, `spec/27_bch_calibration_runbook.yaml` |
+| **상태** | ✅ 완료 (2026-06-21) — `current_status_2026_06_21` 블록 신설, 구 블록 "역사적 스냅샷"으로 명시 |
+
+**성공 하네스 (데이터 기준)**:
+```
+검증: ROADMAP §4의 T+5 수치와 spec/27_bch_calibration_runbook.yaml의 T+5 수치가
+     동일 as_of_date의 Temp/prediction_accuracy_harness_v2.json을 가리킬 것
+규칙: 문서에 적중률 수치 인용 시 반드시 "(as_of: YYYY-MM-DD, sample=N)" 동반 표기
+결과: t5_sample=0 → 두 문서 모두 "DATA_GATED (t5_sample=0, as_of 2026-06-21)"로 정정 완료
+부가발견: cases_analyzed 141→0 회귀는 evaluation_methodology 변경 영향으로 추정 — 근본원인 조사는 별도 후속 과제
+```
+
+---
+
+#### WBS-7.3 GAS→Python 공식 마이그레이션 재검토 (2026-06-21)
+
+| 항목 | 내용 |
+|------|------|
+| **작업** | `governance/gas_logic_migration_ledger_v1.yaml` 15건 findings 전체를 원문부터 재검증 |
+| **현재 상태** | 2건 DONE(F01/F09, 레저가 stale했을 뿐 실제론 이미 등록됨), 1건 KEEP_IN_GAS, **12건 TODO 유지 — 의도적 보류** |
+| **담당 파일** | `governance/gas_logic_migration_ledger_v1.yaml` |
+| **상태** | 부분 완료 — 안전하게 처리 가능한 항목만 종결, 나머지는 근거 있는 보류 |
+
+**재검증으로 발견한 사실**:
+```
+F01/F09(REGISTER_*) → DONE 정정: spec/calibration_registry.yaml에 SP_TAKE_PROFIT/
+  TAKE_PROFIT_BASE가 P5-T01 wave1에서 이미 등록되어 있었음(gs_location 일치 확인).
+
+F12/F13(DELETE_DISTRIBUTION_RISK_GAS) → 보류: ledger가 인용한 "build_distribution_risk_v1.py"는
+  존재하지 않는 파일. 실제로는 tools/build_distribution_risk_score_v2.py가 동일 필드를
+  산출하지만, GAS(gdf_03:2128)와 이 Python 산출값을 직접 대조하는 parity 테스트가
+  tests/parity·tests/regression 어디에도 없음(grep 0건) — "verify parity before delete"
+  조건 미충족으로 GAS 삭제 보류.
+
+F14(DELETE_LATE_CHASE_RISK_GAS) → 보류, ledger 전제 자체가 오류: "build_alpha_lead_table_v1.py가
+  late_chase_risk_score를 산출"한다는 claim은 사실이 아님 — 해당 파일은 존재하지 않고,
+  발견된 도구들(build_late_chase_attribution_v1.py 등)은 이 필드를 "소비"만 할 뿐 산출하지
+  않는다. GAS가 이 점수의 유일한 산출 경로일 가능성이 높아 삭제 시도 자체가 위험.
+
+F02~F06/F07/F10/F11/F15(MIGRATE_* 신규 포트, 12건 중 9건) → 의도적 미착수: parity 테스트
+  인프라 없이 결정론적 매매엔진의 가격/정지손실/라우팅 로직을 포팅하면 silent correctness
+  bug 위험이 큼(advisor 권고). 특히 F11(stop_loss_gate)은 ledger 자체가 "critical path"로
+  명시. 전용 parity 테스트 스프린트가 선행돼야 한다.
+```
+
+**성공 하네스 (데이터 기준)**:
+```
+검증: python -c "import yaml; from collections import Counter; \
+  d=yaml.safe_load(open('governance/gas_logic_migration_ledger_v1.yaml', encoding='utf-8')); \
+  print(Counter(f['status'] for f in d['findings']))"
+결과: Counter({'TODO': 12, 'DONE': 2, 'KEEP_IN_GAS': 1})
+python tools/validate_specs.py → PASS (이 마이그레이션 상태는 현재 CI 게이트와 무관함 —
+  tools/validate_gas_thin_adapter_v1.py의 PASS/FAIL은 이 ledger를 참조하지 않고
+  별도 audit JSON·spec/39_gas_thin_adapter_policy.yaml 기준으로 판정됨을 확인)
+잔여 12건은 전용 parity 테스트 스프린트(별도 WBS)로 이관 — 이번 세션에서는 시도하지 않음.
+```
+
+---
+
+#### WBS-7.4 Deprecated 별칭·시트 정리 (데드라인 2026-06-30)
+
+| 항목 | 내용 |
+|------|------|
+| **작업** | `spec/aliases.yaml`의 deprecated 경로 17건을 데드라인 전 코드/spec 참조에서 전수 제거 |
+| **현재 상태** | `remove_after: 2026-06-30` — 오늘(2026-06-21) 기준 9일 남음, 추적 항목 없었음 |
+| **담당 파일** | `spec/aliases.yaml`, `tools/validate_specs.py` |
+| **상태** | TODO — **긴급(데드라인 임박)** |
+
+**성공 하네스 (데이터 기준)**:
+```
+검증: grep -rl "old_portfolio_exposure_framework\|old_risk_control" spec/ src/ tools/ | wc -l
+현재: deprecated 별칭 17건 등록, 참조 잔존 여부 미확인
+목표: 2026-06-30 이전 참조 0건 + spec/aliases.yaml에서 deprecated 항목 제거
+     python tools/validate_specs.py → deprecated 경로 사용 시 FAIL 처리로 전환
+```
+
+---
+
+#### WBS-7.5 임시 하드코딩 폴백 비례화
+
+| 항목 | 내용 |
+|------|------|
+| **작업** | `OVERHANG_PRESSURE_V1`의 `-500K` 절대값 폴백을 flow_rows 비례 공식으로 교체. 서킷브레이커 MRS +2점, CLA 25%→60% 임시 해제 조항에 명시적 종료조건 부여 |
+| **현재 상태** | 3건 모두 "임시" 주석만 있고 영구화/대체 계획 없음 |
+| **담당 파일** | `spec/13_formula_registry.yaml:1222`, `spec/calibration_registry.yaml`, `spec/risk/circuit_breakers.yaml:192`, `spec/risk/portfolio_exposure.yaml:403` |
+| **상태** | ✅ OVERHANG_PRESSURE_V1 완료(2026-06-21) — 서킷브레이커/CLA 2건은 별도 정책 결정 사안으로 범위 외 |
+
+**성공 하네스 (데이터 기준)**:
+```
+변경: without_20d_fallback을 "frg_5d_sh < -500000"(절대 주식수, 임시)에서
+     "avg_volume_5d IS NOT NULL AND frg_5d_sh < -1.5 * avg_volume_5d OR flow_credit < 0.30"로 교체.
+근거: 1.5 배수는 같은 formula의 with_20d 분기(frg_20d_sh/4 × 1.5)가 이미 쓰는 계수를
+     재사용한 것 — 새로 추정한 값이 아님(advisor 검증 완료).
+널가드: avg_volume_5d 결측 시 선행 missing_policy 규칙(volume_weakness=false와 동일하게
+     selling_acceleration도 false)을 명시적으로 확장 — divide-by-null/오탐 방지.
+등록: spec/calibration_registry.yaml에 id=OVERHANG_PRESSURE_V1_FALLBACK_MULT(EXPERT_PRIOR,
+     sample_n=0)로 신규 등록 + formula_registry에 calibration_ref로 상호 참조.
+검증: python tools/validate_specs.py → PASS, python -m pytest tests/unit tests/integration -q → 76 passed
+잔여(범위 외): circuit_breakers.yaml MRS+2점, portfolio_exposure.yaml CLA 25→60% 임시해제는
+     수치적 조정이 아니라 정책 종료조건을 정하는 사안이라 별도 의사결정으로 분리.
+```
+
+---
+
+#### WBS-7.6 슬리피지 실측 보정
+
+| 항목 | 내용 |
+|------|------|
+| **작업** | `EXECUTION_SIMULATOR_V1`의 5bps 가정을 실거래 체결 데이터와 비교해 보정 |
+| **현재 상태** | 이론치 5bps, "추후 실측 데이터로 보정 예정"이라는 메모만 존재 |
+| **담당 파일** | `src/quant_engine/execution_slippage_store_v1.py`(신규), `tools/evaluate_execution_slippage_v1.py`(신규), `tests/unit/test_execution_slippage_store_v1.py`(신규) |
+| **활성화 조건** | 실거래 체결 기록 ≥ 5건 누적 |
+| **상태** | 캡처 스캐폴딩 완료(2026-06-21) — **비교 자체는 실측 표본 부재로 DATA_GATED 유지(정상)** |
+
+**구현 내용**: 주문 실행은 여전히 사람이 HTS에서 수동 실행(governance/rules/06 준수, API로 체결을 가져오지 않음). 실행 후 사람이 `record` 서브커맨드로 의도가/실제체결가를 1건씩 수동 기록하면 SQLite(`outputs/execution_slippage/execution_slippage.db`)에 누적되고, `report` 서브커맨드가 5건 미만이면 항상 정직하게 `DATA_GATED`를 반환한다(추정 금지).
+
+**성공 하네스 (데이터 기준)**:
+```
+기록: python tools/evaluate_execution_slippage_v1.py record --ticker 005930 --side BUY \
+  --intended-price 71000 --actual-price 71050 --recorded-at 2026-06-21
+비교: python tools/evaluate_execution_slippage_v1.py report
+  → 표본<5: {"status": "DATA_GATED", "sample_n": N, "min_required": 5, ...} (현재 실측 0건 → 이 상태)
+  → 표본≥5: actual_mean_slippage_bps vs assumed(5.0) gap_bps 비교, gap>3bps면 spec 값 갱신 권고
+회귀: python -m pytest tests/unit/test_execution_slippage_store_v1.py -q → 5 passed
+```
+
+---
+
+#### WBS-7.7 신규 시스템 E2E 통합 테스트 구축
+
+| 항목 | 내용 |
+|------|------|
+| **작업** | KIS 수집 → 스냅샷 어드민 적재 → 정성매도전략 평가로 이어지는 파이프라인 통합 테스트 1개 작성. `snapshot_admin_server_v1.py`의 임베디드 JS 스모크 테스트 추가. Naver 폴백 Cloudflare 차단 시 graceful degradation 테스트 |
+| **현재 상태** | 단위 테스트 61개(양호) 존재, 통합/E2E 0건 |
+| **담당 파일** | `tests/integration/test_kis_collection_to_snapshot_admin_and_sell_strategy_v1.py` (신규) |
+| **상태** | ✅ 완료 (2026-06-21) — 네트워크 미사용, 3개 테스트 PASS |
+
+**성공 하네스 (데이터 기준)**:
+```
+검증: python -m pytest tests/integration -q → 3 passed
+  1) kis_data_collection_v1.collect_to_sqlite(no-naver, no-live-kis) → data_collection_store_v1.db 적재
+     → load_collection_dashboard_state()로 read-back, collection_snapshots count 일치 확인
+  2) Naver fetch_price_history가 Cloudflare 403(RuntimeError)을 던지도록 monkeypatch
+     → collect_to_sqlite()가 배치 전체를 죽이지 않고 PASS/PASS_WITH_WARNINGS로 완료하는지 확인
+  3) compute_qualitative_sell_strategy() 순수함수 결과 → insert_sell_strategy_result →
+     fetch_recent_sell_strategy_results round-trip 일치 확인
+회귀 확인: python -m pytest tests/unit tests/integration -q → 73 passed
+```
+
+---
+
+#### WBS-7.8 ETF NAV/괴리율/추적오차/AUM 수집 경로 확정
+
+| 항목 | 내용 |
+|------|------|
+| **작업** | KRX/KIND 기반 수집 경로 확정 또는, 확정이 불가하면 "구조적으로 미구현 유지" 사유와 재검토 주기를 명문화. 공매도 잔고율(KRX CSV 수동) 운영 절차도 함께 문서화 |
+| **현재 상태** | `spec/16_data_gaps_roadmap.yaml` S4/S5 PLANNED 상태로 장기 방치, 재검토 주기 없음 |
+| **담당 파일** | `spec/16_data_gaps_roadmap.yaml`, `docs/runbook.md` |
+| **상태** | ✅ 완료 (2026-06-21, 2026-06-22 실측 보강) |
+
+**2026-06-22 추가 실측(사용자 요청)**: "자동화 안 되면 차후 개선 목표로"라는 지시에 따라 추정이 아니라 실제로
+자동화를 재시도했다. 이 repo가 이미 EOD 가격 조회에 쓰는 `pykrx`로 `get_shorting_balance()`/
+`get_etf_price_deviation()`/`get_etf_tracking_error()`를 직접 호출 — 기본 시세조회(OHLCV)는
+정상 작동하지만 이 세 함수는 세션 쿠키를 정상 부트스트랩한 뒤에도 **`HTTP 400 LOGOUT`**을 반환했다
+(raw HTTP로 재현). pykrx 임포트 시 뜨는 "KRX_ID/KRX_PW 미설정" 경고와 정확히 일치 — **KRX 회원
+로그인이 있어야 접근 가능한 서버측 인증 게이트**임을 확정했다(헤더/세션 보정으로 해결 안 됨).
+자동화하려면 KRX 계정을 자격증명으로 코드에 등록해야 하는데, 이는 governance/rules/06·07과
+같은 종류의 새 정책 결정 사안이라 사용자 승인 없이 추가하지 않았다 — **개선 목표로 이관**:
+`spec/16_data_gaps_roadmap.yaml` S4/S5의 `automation_attempt_2026_06_22` 필드에 재현 절차 기록,
+`next_review_date: 2026-09-30` 재조사 시 "API 키 발급 가능성"이 아니라 "KRX 계정 발급·자격증명
+관리 정책 승인 여부"로 질문을 재구성하도록 명시.
+
+**성공 하네스 (데이터 기준)**:
+```
+검증: spec/16_data_gaps_roadmap.yaml S4/S5에 "next_review_date"+"automation_attempt_2026_06_22" 필드 존재
+결과: docs/runbook.md 20~21번 항목에 실측 실패 근거(HTTP 400 LOGOUT) + 공매도 잔고율 주 1회
+     CSV 갱신 절차 + ETF NAV 수동 import 경로(tools/import_etf_nav_manual.py) 명문화
+python tools/validate_specs.py → PASS
+```
+
+---
+
+#### WBS-7.9 snapshot_admin Python 서버 — Gitea CI를 통한 Synology 상시 서비스화 검토 (2026-06-21)
+
+| 항목 | 내용 |
+|------|------|
+| **작업** | `src/quant_engine/snapshot_admin_server_v1.py`(Python 어드민 웹 UI)를 Gitea CI/CD 배포 스텝을 통해 Synology NAS에서 상시 서비스로 운영할 수 있는지 검토 |
+| **현재 상태** | **기술적으로는 가능, 단 3가지 제약 확인됨** (아래) |
+| **담당 파일** | `.gitea/workflows/ci.yml`, `tools/run_snapshot_admin_server_v1.py`, `src/quant_engine/snapshot_admin_server_v1.py` |
+| **상태** | TODO — 구현 전 보안·접근 정책 결정 필요 |
+
+**조사 결과**:
+
+1. **의존성 제약은 문제 없음**: `.gitea/workflows/ci.yml` 주석에 명시된 Synology DS216j(ARMv7l 32bit, Python 3.8.12) 제약은 "numpy/pandas 휠 없음, gcc 미설치"인데, `snapshot_admin_server_v1.py`는 `http.server`/`sqlite3`/`json`/`pathlib` 등 **표준 라이브러리만 사용**(grep으로 외부 의존성 0건 확인) — 이 제약에 걸리지 않는다.
+2. **DS216j는 Docker 미지원 모델**이다(Container Manager는 x86 가상화 지원 모델에서만 동작). 따라서 컨테이너 배포는 불가하고, DSM Task Scheduler + 백그라운드 프로세스 방식이 유일한 현실적 경로다.
+3. **CI 잡 프로세스 영속성 위험**: Gitea Act Runner가 잡 종료 시 자식 프로세스를 정리(kill)할 가능성이 있어, CI 스텝에서 단순히 서버를 백그라운드 실행(`nohup ... &`)해도 잡 종료와 함께 죽을 수 있다. 검증되지 않은 상태이며 실제 적용 전 `setsid`/`disown` 방식의 데몬화를 실측 테스트해야 한다.
+4. **보안 — 가장 중요한 제약**: 현재 서버는 `--host 127.0.0.1`(로컬호스트 전용) 기본값이고 **인증 기능이 전혀 없다**. 이 어드민 UI는 `settings`/`account_snapshot` SQLite를 직접 쓰기 가능한 표면이며, 이 데이터는 결정론적 매수/매도 엔진의 입력이 된다. LAN에 상시 노출하려면 최소 (a) 인증 추가 또는 (b) DSM 리버스 프록시 뒤에서 VPN/방화벽 화이트리스트로 제한 — 둘 중 하나가 선행되어야 한다.
+
+**권고 (보안 정책 결정 후 구현)**:
+```
+배포 방식: Gitea CI 배포 스텝에서 코드 갱신 후 PID 파일 확인 → 기존 프로세스 종료 → setsid로 재기동
+가동 감시: DSM Task Scheduler에 5분 간격 헬스체크 스크립트 등록(프로세스 미생존 시 재기동) — poor-man's supervisor
+네트워크: host=127.0.0.1 유지 + DSM 리버스 프록시(HTTPS)와 IP 화이트리스트로 LAN 내부 접근만 허용,
+         또는 호스트 OS 레벨 인증(Synology SSO/LDAP 연동) 추가 전까지 인터넷 노출 금지
+검증: 배포 후 curl http://127.0.0.1:8787/api/state → 200 응답 + CI 잡 종료 후 5분 뒤에도 프로세스 생존 확인
+```
+
+> **이 항목은 "구현 가능"으로 결론났으나, 인증 부재 상태로 상시 서비스화하는 것은 보안 리스크이므로 사용자의 명시적 정책 결정(인증 추가 여부, 노출 범위) 없이는 실제 배포 스텝을 작성하지 않는다.**
+
+---
+
+#### WBS-7.10 어드민 페이지 — Tabler 기반 테이블별 그리드 조회 (2026-06-21)
+
+| 항목 | 내용 |
+|------|------|
+| **작업** | `snapshot_admin_server_v1.py`에 워크스페이스 DB(`settings`/`account_snapshot`/`workspace_*`) + KIS 수집 DB(`collection_*`) + 정성매도전략 DB(`sell_strategy_results`/`satellite_recommendations`) 3개 SQLite 파일에 걸친 11개 테이블을 Tabler(CDN) 그리드로 조회하는 신규 `/tables` 페이지 추가 |
+| **담당 파일** | `src/quant_engine/snapshot_admin_server_v1.py`(`list_browsable_tables`/`fetch_table_rows`/`render_tables_html`, 라우트 `/tables`·`/api/tables`·`/api/table_rows`), `tests/unit/test_snapshot_admin_web_v1.py` |
+| **보안** | 테이블명은 고정 화이트리스트(`WORKSPACE_BROWSABLE_TABLES`/`COLLECTION_BROWSABLE_TABLES`/`QUALITATIVE_SELL_BROWSABLE_TABLES`)와 정확히 일치할 때만 SQL에 사용 — 임의 테이블명 SQL 인젝션 시도는 `ValueError`로 차단(테스트로 검증) |
+| **상태** | ✅ 완료 (2026-06-21) |
+
+**성공 하네스 (데이터 기준)**:
+```
+검증: python -m pytest tests/unit/test_snapshot_admin_web_v1.py -q → 8 passed
+  - render_tables_html()에 tabler/tableSelect/api 경로 포함 확인
+  - list_browsable_tables()가 3개 DB·11개 테이블 모두 열거하는지 확인
+  - fetch_table_rows() 페이지네이션(limit/offset) + 화이트리스트 외 테이블명 차단(ValueError) 확인
+회귀 확인: python -m pytest tests/unit tests/integration -q → 76 passed
+         python tools/validate_specs.py → PASS
+```
+
+---
+
+#### WBS-7.11 spec-코드 동기화 게이트 (2026-06-22, 설계+구현 완료)
+
+**배경**: 2026-06-21 비판적 리뷰 이후 진행한 WBS-7.3/7.4 작업에서 spec/governance YAML이
+실제 코드 상태와 어긋난 채로 방치된 사례를 3건 발견했다 — `governance/gas_logic_migration_ledger_v1.yaml`이
+존재하지 않는 파일(`build_distribution_risk_v1.py`, `build_alpha_lead_table_v1.py`)을
+canonical 구현으로 인용, `spec/aliases.yaml`의 `remove_after` 데드라인이 추적 없이 방치,
+`spec/calibration_registry.yaml`의 중복 id로 일부 임계값이 조용히 무시됨. 세 사례 모두
+"문서가 코드를 정확히 가리키는지 자동으로 검증하는 장치가 없다"는 동일 원인이다.
+LLM이 런타임에 이런 stale spec을 사실로 읽으면 할루시네이션으로 직결된다(사용자 질의,
+2026-06-21). **목표는 "구현됐으니 문서 삭제"가 아니라 "LLM이 읽는 문서는 항상 코드와의
+동기화를 CI가 보장하고, 동기화할 수 없는 순수 설명용 문서는 폐기한다."**
+
+| 항목 | 내용 |
+|------|------|
+| **작업** | spec YAML에 `has_code_implementation`/`code_path` 필드를 추가하고 `validate_specs.py`가 해당 code_path 존재 여부를 자동 검사하도록 신규 검증기 추가. **정정(구현 중 발견)**: `role: deprecated_redirect`는 실제로 2개뿐이었다(`spec/03_risk_policy.yaml`, `spec/04_strategy_rules.yaml`) — `spec/06_exit_policy.yaml`은 `role: compatibility_index`(영구 유지 설계, risk_control.yaml/entry_gates.yaml과 동급)였다. 설계 단계의 "3개 삭제" 진술 자체가 부정확했던 것을 구현 중 재확인 후 정정 — 2개만 실삭제, 06_exit_policy.yaml은 `redirect_only:true`로 태깅해 유지 |
+| **스키마 설계** | 각 spec YAML의 `meta:` 블록(없으면 최상위)에 추가:
`has_code_implementation: true\|false`
`code_path: "tools/build_x.py"` 또는 `["tools/a.py", "src/quant_engine/b.py"]` (true일 때만 필수)
`role: deprecated_redirect`/`compatibility_index` 파일은 `has_code_implementation: false` + `redirect_only: true`로 명시(코드 없음이 정상이므로 code_path 검사 스킵) |
+| **검증기 설계** | `tools/validate_specs.py`에 `validate_spec_code_sync(errors)` 신규 함수 추가:
1. `spec/**/*.yaml` 전체를 순회
2. `has_code_implementation` 필드가 **있는** 파일만 검사(필드 없는 파일은 skip — 이것이 점진적 롤아웃 메커니즘. 전체 일괄 강제 아님)
3. `true`인데 `code_path`(들)가 디스크에 없으면 `fail(errors, f"spec declares code_path that does not exist: {path} → {code_path}")`
4. `redirect_only: true`인데 `has_code_implementation: true`이면 모순으로 fail
5. 결과를 `Temp/spec_code_sync_v1.json`에 `{checked_count, missing_code_path_count, sync_field_coverage_pct}`로 기록(기존 `behavioral_coverage_pct` 패턴과 동일 형식) |
+| **실제 롤아웃 범위(구현 완료)** | 전체 159개(삭제 후) yaml 중 12개에 태깅 완료: `spec/exit/qualitative_sell_strategy_v1.yaml`, `governance/rules/06·07`, `spec/19_harness_contract.yaml`, `spec/55_execution_simulator_contract.yaml`, `spec/41_release_dag.yaml`, `spec/15_account_snapshot_contract.yaml`, `spec/18_settings_contract.yaml`, `spec/calibration_registry.yaml`(true 7개) + `spec/risk/risk_control.yaml`, `spec/strategy/entry_gates.yaml`, `spec/06_exit_policy.yaml`(redirect_only 3개). 공식 레지스트리(`13_formula_registry.yaml` 등)는 1:1 code_path가 없어 범위 제외 — 이미 `calibration_registry.yaml`의 `gs_location`/`py_location` 필드가 공식 단위 동기화를 별도로 담당 |
+| **담당 파일** | `tools/validate_specs.py`(`validate_spec_code_sync` 신규), `tests/unit/test_validate_spec_code_sync_v1.py`(신규 4건), 위 12개 spec/governance 파일 |
+| **상태** | ✅ 구현 완료 (2026-06-22) |
+
+**구현 중 발견한 버그**: 최초 구현에서 `redirect_only=true AND has_code_implementation=true` 모순 케이스가 `errors`에는 쌓이지만 함수 자신의 반환값 `gate`는 PASS로 남는 버그가 있었다 — 직접 작성한 단위테스트(`test_redirect_only_and_has_code_is_contradiction`)가 즉시 잡아냈고 `missing` 카운터에 반영해 수정했다.
+
+**성공 하네스 (데이터 기준)**:
+```
+검증: python tools/validate_specs.py → Temp/spec_code_sync_v1.json
+결과: {"total_spec_files": 159, "checked_count": 12, "missing_code_path_count": 0,
+       "sync_field_coverage_pct": 7.55, "gate": "PASS"}
+회귀: python -m pytest tests/unit tests/integration -q → 85 passed
+부수 조치(완료): role: deprecated_redirect 2개 파일(03_risk_policy.yaml/04_strategy_rules.yaml)
+  실삭제 + RetirementAssetPortfolio.yaml의 risk_policy_index/strategy_rules_index 참조 제거 +
+  6개 자식 파일의 parent_file 갱신 + spec/ownership_map.yaml·spec/risk·strategy/README.md 정정
+  (WBS-7.4에서 alias만 지우고 파일은 남겨뒀던 부분의 후속 정리)
+목표(2차, 분기별 확장): sync_field_coverage_pct ≥ 50% — formula registry급 파일들의
+  공식 단위 동기화 메커니즘(calibration_registry gs_location/py_location) 커버리지 확장과 별개 트랙
+```
+
+---
+
 ## 3. 완성도 로드맵 매트릭스
 
 | WBS | 우선순위 | 난이도 | 선행조건 | 예상 기간 | 현재 완성도 |
@@ -551,6 +958,19 @@ CI 게이트:
 | 5.1 CI/CD | 🟡 Medium | 중간 | Gitea 연결 | 완료 | **100%** ✅ |
 | 5.2 GAS 자동 배포 | 🟢 Low | 낮음 | 5.1 완료 | 완료 | **100%** ✅ |
 | 5.3 자율 실행 | 🟢 Low | 중간 | 5.1+5.2 완료 | 완료 | **100%** ✅ |
+| 6 비기계적 매도전략·위성추천 (엔진+데이터+KIS+SQLite+자체평가) | 🔴 Critical | 높음 | 없음 | 완료 | **100%** ✅ (잔류위험: 0c절·WBS-7.7) |
+| 6-잔여 공매도 잔고율 | 🟢 Low | 높음 | KRX 정책 | 차단 확정 | USER_ACTION 대기 |
+| 7.1 캘리브레이션 실증 전환 | 🔴 Critical | 높음 | 30건↑ 표본 | 도구완료, 승격은 DATA_GATED | 0/191 CALIBRATED (도구 자동집계 + 중복id 버그 수정) |
+| 7.2 T+5 지표 정합성 통일 | 🔴 Critical | 낮음 | 없음 | 완료 | **100%** ✅ (2026-06-21) |
+| 7.3 GAS→Python 마이그레이션 | 🟠 High | 중간 | parity 테스트 | 부분완료 + 12건 의도적 보류 | 2/15 DONE, 12 TODO(근거기록), 1 KEEP_IN_GAS |
+| 7.4 Deprecated 정리 | 🟠 High | 낮음 | 없음 | 완료 | **100%** ✅ (2026-06-21, alias 17건 제거) |
+| 7.5 임시 폴백 비례화 | 🟡 Medium | 중간 | 없음 | 완료(OVERHANG만) | **100%** ✅ (2026-06-21, 나머지 2건은 정책결정 분리) |
+| 7.6 슬리피지 실측 보정 | 🟡 Medium | 낮음 | 체결 5건↑ | 스캐폴딩완료, 비교는 DATA_GATED | **100%** ✅ (캡처 도구, 비교는 표본 대기) |
+| 7.7 E2E 통합테스트 | 🟠 High | 중간 | 없음 | 완료 | **100%** ✅ (2026-06-21, 3 passed) |
+| 7.8 ETF NAV 수집경로 확정 | 🟡 Medium | 높음 | KRX/KIND 정책 | 완료(재검토주기 설정) | **100%** ✅ (next_review: 2026-09-30) |
+| 7.9 Synology 배포 검토 | 🟡 Medium | 중간 | 보안정책 결정 | 완료(검토만) | **100%** ✅ (구현은 정책 결정 대기) |
+| 7.10 어드민 테이블 그리드(Tabler) | 🟢 Low | 낮음 | 없음 | 완료 | **100%** ✅ (2026-06-21, 8 passed) |
+| 7.11 spec-코드 동기화 게이트 | 🔴 Critical | 중간 | 없음 | 완료 | **100%** ✅ (2026-06-22, 12/159 태깅, 85 passed) |
 
 ---
 
@@ -583,10 +1003,21 @@ CI 게이트:
 
 성과:
   T+20 레저 건수:      0건   →  목표: 30건 (~2026-07-12) DATA_GATED
-  예측 적중률(T+5):    54.76% (t5_ap_combined) →  목표: ≥55% ≈달성 근접
+  예측 적중률(T+1):    52.94% (sample=68, decisive=67.92%) — as_of 2026-06-21
+  예측 적중률(T+5):    DATA_GATED (sample=0, as_of 2026-06-21) — 0c절 참조, 과거 54.76%/35.86% 캐시값 모두 폐기
   알파 (vs KOSPI):     미측정 →  목표: >0%p/분기
   honest_proof_score: 50.95 →  목표: ≥70 (T+20 30건 → 70.95 자동 달성 예상)
 
+캘리브레이션 품질 (신규, WBS-7.1):
+  calibrated_threshold_count: 0/190 (0%)   →  목표: ≥10건 (1차), ≥30건 (2차)
+  provisional_threshold_count: 8/190 (4.2%) →  목표: ≥30건
+  expert_prior_unvalidated_pct: 95.8% (SPEC_DERIVED+EXPERT_PRIOR) → 목표: ≤70%
+
+보완·고도화 (신규, Phase 7):
+  gas_python_migration_pct: 0/14 완료 (0%) → 목표: 14/14 (100%, KEEP_IN_GAS 1건 제외)
+  deprecated_alias_remaining: 17건 (데드라인 2026-06-30) → 목표: 0건
+  e2e_integration_test_count: 0건 → 목표: ≥1건 (KIS수집→스냅샷→정성매도 체인)
+
 자동화:
   run_all 성공률:      98단계 DAG PASS →  목표: ≥95% ✅ (step_count=98, wave_0~9)
   CI/CD 커버리지:      100%   →  목표: 100% ✅ (Synology act_runner 온라인, 4게이트 PASS)
@@ -676,6 +1107,44 @@ python tools/update_sector_universe_from_naver.py --limit 10 --apply  # 원본 
 
 ---
 
+### Sprint-6 (비판적 보완 스프린트, 2026-06-21 비판적 리뷰 대응)
+
+```
+[x] WBS-7.2: T+5/예측정확도 지표 단일 진실원천 통일 (2026-06-21 완료)
+[x] WBS-7.4: Deprecated 별칭 17건 정리 — 2026-06-30 데드라인 (2026-06-21 완료, validate_specs.py PASS)
+[x] WBS-7.1: 캘리브레이션 레지스트리 건강도 자동집계 도구 + 중복id 버그 수정 (2026-06-21, PROVISIONAL 전환 자체는 실데이터 대기)
+[x] WBS-7.3: GAS→Python 마이그레이션 재검토 완료(2건 DONE 정정, 12건 의도적 보류+근거기록, 2026-06-21) — 잔여는 별도 parity 테스트 스프린트
+[x] WBS-7.7: KIS수집→스냅샷→정성매도 E2E 통합 테스트 작성 (2026-06-21 완료, 3 passed)
+[x] WBS-7.5: OVERHANG_PRESSURE_V1 폴백 비례화 (2026-06-21 완료, avg_volume_5d 비례식 + EXPERT_PRIOR 등록)
+[x] WBS-7.6: 슬리피지 실측 캡처 스캐폴딩 구축 완료 (2026-06-21, 비교 자체는 체결 5건 누적 대기)
+[x] WBS-7.8: ETF NAV 수집경로 재검토 + 공매도 잔고율 운영절차 문서화 (2026-06-21 완료)
+```
+
+---
+
+## 6. 부록: Phase 5 데이터 플랫폼 전환 WBS 성공값
+
+> 원칙: 아래 항목은 모두 `기대 성공값 + 데이터 증빙 + 검증 명령`이 함께 있어야 성공으로 본다.
+> 현재 구현된 항목은 로컬 `Temp/` 증빙을 기준으로 판정하고, 아직 미래 전환 항목은 `DATA_GATED`로 둔다.
+
+| WBS | 기대 성공값 | 데이터 증빙 | 검증 명령 |
+|-----|------------|------------|-----------|
+| P1 KIS core collector | `collector_gate=PASS`, `output_json_gate=PASS`, `collection_runs>=1`, `collection_snapshots>=1`, `provenance_source_count>=1` | `Temp/test_kis_data_collection.json`, `Temp/test_kis_data_collection.db` | `python tools/run_kis_data_collection_v1.py --input-json GatherTradingData.json --sqlite-db Temp/test_kis_data_collection.db --output-json Temp/test_kis_data_collection.json --kis-account real --no-live-kis --no-naver` |
+| P2 SQLite canonical store | `sqlite_schema_tables>=3`, `round_trip_snapshot_lookup=PASS`, `backend_contract_sqlite=PASS`, `backend_contract_postgresql=READY`, `single_workspace_sqlite=true`, `collector_separate_db=true` | `src/quant_engine/data_collection_store_v1.py`, `src/quant_engine/data_collection_backend_v1.py`, `tests/unit/test_data_collection_store_v1.py`, `src/quant_engine/snapshot_admin_store_v1.py` | `python -m pytest tests/unit/test_data_collection_store_v1.py -q` |
+| P3 CI scheduler cutover | `xlsx_dependency_removed=true`, `json_seed_input=true`, `sqlite_output=true`, `mock_api_validation=PASS`, `no_direct_trading_gate=PASS` | `.gitea/workflows/kis_data_collection.yml`, `Temp/kis_api_credentials_validation_v1.json`, `Temp/test_kis_data_collection.json` | `python tools/validate_no_direct_api_trading_v1.py` |
+| P4 GAS thin adapter minimize | `allowed_responsibilities_only=true`, `forbidden_responsibilities_present=false`, `thin_adapter_gate=PASS` | `tools/validate_gas_thin_adapter_v1.py`, `Temp/gas_thin_adapter_validation_v1.json`, `src/gas/core/gas_lib.gs` | `python tools/validate_gas_thin_adapter_v1.py` |
+| P5 PostgreSQL upgrade path | `sqlite_schema_parity=PASS`, `backend_contract_present=true`, `postgres_execution=DATA_GATED`, `caller_compatibility_preserved=true` | `src/quant_engine/data_collection_backend_v1.py`, `src/quant_engine/kis_data_collection_v1.py`, `tests/unit/test_data_collection_store_v1.py`, `tools/generate_postgresql_upgrade_stub_v1.py` | `python -m pytest tests/unit/test_data_collection_store_v1.py -q` |
+| P6 Snapshot admin web editor | `settings_sheet_web_editor=true`, `account_snapshot_sheet_web_editor=true`, `contenteditable_grid=true`, `api_save_round_trip=PASS`, `kis_collection_dashboard=true`, `workspace_db_is_single_file=true`, `collection_filter_controls=true`, `collection_dashboard_page=true`, `change_timeline_view=true` | `src/quant_engine/snapshot_admin_server_v1.py`, `src/quant_engine/data_collection_store_v1.py`, `src/quant_engine/snapshot_admin_store_v1.py`, `tools/validate_snapshot_admin_web_v1.py`, `tests/unit/test_snapshot_admin_web_v1.py`, `.gitea/workflows/snapshot_admin.yml` | `python tools/validate_snapshot_admin_web_v1.py` |
+| Q1 Qualitative sell pipeline | `mock_api_validation=PASS`, `pipeline_contract=PASS`, `workflow_present=true`, `schedule_present=true`, `package_scripts_present=true` | `.gitea/workflows/qualitative_sell_strategy.yml`, `tools/validate_qualitative_sell_strategy_pipeline_v1.py`, `Temp/qualitative_sell_strategy_pipeline_v1.json` | `python tools/validate_qualitative_sell_strategy_pipeline_v1.py` |
+| Q2 Gitea secrets contract | `secrets_contract=PASS`, `workflow_secret_mapping=PASS`, `docs_present=true`, `ci_validation_present=true` | `docs/GITEA_SECRETS_SETUP.md`, `tools/validate_gitea_secrets_contract_v1.py`, `Temp/gitea_secrets_contract_v1.json` | `python tools/validate_gitea_secrets_contract_v1.py` |
+
+### WBS 성공 판정 규칙
+
+- `PASS`: 기대 성공값이 충족되고, 해당 증빙 파일이 실제로 존재한다.
+- `READY`: 지금은 실행하지 않지만, 다음 단계 전환에 필요한 코드/계약이 존재한다.
+- `DATA_GATED`: 의도적으로 아직 실제 데이터가 쌓이지 않아 보류된 항목이다.
+- `FAIL`: 기대 성공값을 만족하지 못하거나 증빙이 없다.
+
 > 이 문서는 `docs/ROADMAP_WBS.md` 에 저장됩니다.  
 > 스프린트 완료마다 **완성도 KPI 섹션**을 업데이트하세요.  
 > 모든 WBS 항목의 구현 시 반드시 **하네스 성공 기준**을 먼저 충족 후 다음 단계로 진행합니다.
diff --git a/spec/13b_harness_formulas.yaml b/spec/13b_harness_formulas.yaml
index 1e95f155..47c61fa3 100644
--- a/spec/13b_harness_formulas.yaml
+++ b/spec/13b_harness_formulas.yaml
@@ -3149,3 +3149,74 @@ formula_registry:
       expected_outputs: [coverage_ratio, orphan_code_formula_count, unimplemented_rules]
       llm_allowed: cite_only
       version: "2026-06-03_ORPHAN_RECONCILE"
+
+    # == [2026-06-21_PHASE8] 비기계적 매도전략 — 공매도 합성 + confluence 판단 =========
+    SHORT_INTEREST_RISK_GAUGE_V1:
+      purpose: >
+        공매도잔고율 추세 + 공매도거래비중 + 상대수익률(섹터·지수 대비) + 거래량 이상 +
+        실적전망 5요소를 가중합성해 -1(매수지지)~+1(매도압력) 점수로 계량화한다.
+        잔고율 단독을 매수/매도 트리거로 쓰지 않으며, 잔고율이 1% 미만(현대로템형)인
+        저잔고율 종목은 거래비중·상대수익률 가중치를 자동 상향한다.
+      output_contract:
+        short_interest_composite_json:
+          fields: "[short_interest_pressure, status, low_balance_regime, label, components, weights_used, missing_inputs]"
+      python_tool: src/quant_engine/qualitative_sell_strategy_v1.py:compute_short_interest_composite
+      version: "2026-06-21_PHASE8"
+
+    QUALITATIVE_SELL_STRATEGY_V1:
+      purpose: >
+        매크로(macro_pressure)·실적/펀더멘털 추세(fundamental_trajectory)·공매도수급
+        (short_interest_pressure)·호가 10단계 미시구조(microstructure_pressure)·
+        대내외 변수/대형 IPO·섹터 로테이션(liquidity_rotation_risk) 5개 독립 팩터군의
+        confluence(최소 3/5 동일방향 합의)로만 매도/보유/추가 확신도를 산출한다.
+        단일 팩터 임계값 돌파만으로는 행동을 트리거하지 않는다(기계적 매도 금지).
+        현금부족 사유는 입력에서 의도적으로 배제되며(cash_shortfall_excluded=true),
+        주식가치 보존이 유일한 목적함수다. 매도/추가 판단 시 실제 실적발표일·고영향
+        매크로 이벤트일 기준으로 검토구간(review_window)을 역산한다(임의 고정일 금지).
+        market_regime(PERFORMANCE_MARKET/TECHNICAL_MARKET)이 ctx.rate_trend로 주어지면
+        금리국면에 따라 팩터 가중치를 조정한다(MARKET_REGIME_CLASSIFIER_V1).
+      output_contract:
+        qualitative_sell_strategy_json:
+          fields: "[action, conviction, market_regime, composite_score, sell_agreeing_factors, hold_add_agreeing_factors, missing_factors, review_window, rationale, cash_shortfall_excluded, mechanical_sell_prohibited]"
+      python_tool: src/quant_engine/qualitative_sell_strategy_v1.py:compute_qualitative_sell_strategy
+      version: "2026-06-21_PHASE8"
+
+    MARKET_REGIME_CLASSIFIER_V1:
+      purpose: >
+        금리 추세(rate_trend: RISING/FLAT/FALLING)를 실적장세(PERFORMANCE_MARKET)/
+        기술장세(TECHNICAL_MARKET)로 분류한다. 금리 상승기엔 유동성보다 실적·수출입
+        펀더멘털이 가격을 주도(실적장세) — fundamental_trajectory 가중 상향.
+        금리 보합·하락기엔 유동성이 풍부해 수급·미시구조가 가격을 주도(기술장세) —
+        microstructure_pressure/short_interest_pressure 가중 상향.
+        QUALITATIVE_SELL_STRATEGY_V1·SATELLITE_CANDIDATE_SCORE_V1의 가중치 산출에 사용.
+      output_contract:
+        market_regime_json:
+          fields: "[market_regime]"
+      python_tool: src/quant_engine/qualitative_sell_strategy_v1.py:classify_market_regime
+      version: "2026-06-21_PHASE8"
+
+    MICROSTRUCTURE_PRESSURE_FROM_ORDERBOOK_V1:
+      purpose: >
+        KIS Open API 호가10단계(inquire-asking-price-exp-ccn, FHKST01010200) output1의
+        total_askp_rsqn/total_bidp_rsqn으로 -1(매수우위)~+1(매도우위) 미시구조 압력을
+        계량화. QUALITATIVE_SELL_STRATEGY_V1의 microstructure_pressure 입력으로 쓰이며,
+        전략 방향 결정이 아니라 confluence 성립 후 집행 타이밍 보조로만 사용한다.
+        [CRITICAL] 이 공식이 사용하는 KIS API는 조회(read-only)만 수행 —
+        governance/rules/06_no_direct_api_trading.yaml, 07_no_kis_account_balance_query.yaml.
+      output_contract:
+        microstructure_pressure_json:
+          fields: "[microstructure_pressure, status, total_askp_rsqn, total_bidp_rsqn]"
+      python_tool: src/quant_engine/qualitative_sell_strategy_v1.py:compute_microstructure_pressure_from_orderbook
+      version: "2026-06-21_PHASE8"
+
+    SATELLITE_CANDIDATE_SCORE_V1:
+      purpose: >
+        미보유 위성 유니버스 종목을 섹터 수출입 추세(sector_export_trend, 관세청/산업
+        통상부 무역통계 기반)·펀더멘털 추세·상대수익률로 평가해 BUY_CANDIDATE/WATCH/
+        NEUTRAL_NO_EDGE/AVOID를 산출한다. market_regime에 따라 수출입 비중을 조정
+        (실적장세에서 sector_export_trend 가중 상향).
+      output_contract:
+        satellite_candidate_json:
+          fields: "[satellite_action, attractiveness_score, market_regime, components, weights_used]"
+      python_tool: src/quant_engine/qualitative_sell_strategy_v1.py:compute_satellite_candidate_score
+      version: "2026-06-21_PHASE8"