docs(rel-010): M3 trex-core 릴리즈 문서 (dcy-034/035/036)

REL-010 draft — reconcile cold-start + WAC 리포트 + dcy-036 휴면배포 묶음.
배포 선결=PR #35 머지. 미푸시(사장님 결재 시 push).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHtM5Ws1HKCKQ4JGi6GRb5

docs/releases/index.md

@@ -17,3 +17,4 @@
 | REL-007 | app-service | feedback-captured | BAT-037, BAT-038, BAT-039, BAT-040, BAT-041 | dcy-025 (REQ-073 CHG — available_slots hint) + dcy-026/issue #24 (매도세 정정) + issue #4 (paper seq Redis) + issue #25 (slots RPC DB 필터) + dcy-027/issue #20 (중장기 인스턴스 프로파일) — 통합 릴리즈 | [rel-007](rel-007_20260612_slots-rpc-fee-paper-longterm.md) |
 | REL-008 | app-service | feedback-captured | BAT-042, BAT-043, BAT-044, BAT-045, BAT-046 | dcy-028/issue #26 (slot strategy-state) + issue #27 (sell retryable) + dcy-030/issue #28 (호가단위 스냅, P0 체결 복구) + dcy-029/issue #29 (운영 관측성 — 구조화 로깅·주문결과·거부ERROR·reason+actor·PnL CLI·런북) — 통합 릴리즈 | [rel-008](rel-008_20260616_tick-snap-and-observability.md) |
 | REL-009 | app-service | feedback-captured | BAT-047, BAT-048, BAT-049 | dcy-031/OPS-005 (이벤트 발행 신뢰성 — idle keepalive·재시도·DLQ 경보) + dcy-032 (체결가 0/None 백필 가드·WARN 로깅) + dcy-033 (알람 emitter + trex.alerts exchange 1단계) + dcy-017 후속(무데이터/죽은 종목 위생 런북 docs-only) — M2 통합 릴리즈. 환류: OPS-005 해소 확인, slot_filled NO_ROUTE/DLQ 신규 발견(M3 Discovery 입력) | [rel-009](rel-009_20260625_event-reliability-fill-guard-alarm-runbook.md) |
+| REL-010 | app-service | draft | BAT-050, BAT-051, BAT-052, BAT-053, BAT-054 | dcy-034 (차단형 reconcile + sync/verify cold-start) + dcy-035 (WAC 실현손익 운영리포트) + dcy-036 (KIS 인증정보 휴면 배포 — credential_fetch_enabled=OFF) — M3 통합 릴리즈. 배포 선결: PR #35 머지 + BAT-054 confirm-batch-verification | [rel-010](rel-010_20260629_reconcile-coldstart-wac-report-credential-dormant.md) |

docs/releases/rel-010_20260629_reconcile-coldstart-wac-report-credential-dormant.md

@@ -0,0 +1,196 @@
+# REL-010: 차단형 reconcile + cold-start + WAC 운영리포트 + KIS 인증정보 휴면 배포 (M3 통합 릴리즈)
+
+- Status: draft
+- Profile: app-service
+- Included Batch: BAT-050, BAT-051, BAT-052, BAT-053, BAT-054
+
+## Scope
+
+- Included:
+  - **BAT-050** (dcy-034 / core-A): 차단형 reconcile 게이트 — reconcile-warning durable store(`slot_reconcile_warning` 테이블, REQ-102), B/C 불일치 슬롯 → warning 전이(REQ-103), 전략 차단 게이트(pause ∨ reconcile-warning 중 하나 → buy/외부sell 차단, 안전망 우회 보장, REQ-104), 차단/해제 전이 구조화 로깅 + 고영향 알람(REQ-107), 비기능 요건 — 내구성·회귀 방지·자동 정정 금지·wire 계약 최소 침습(REQ-108).
+  - **BAT-051** (dcy-034 / core-B): sync/verify CLI cold-start onboarding — `trex-core sync` 명령(INACTIVE→HOLDING 전이 + WAC seed + reconcile-warning 해제, REQ-105), `trex-core verify` 명령(C-case 슬롯 재대조 + warning 해제, REQ-106). INACTIVE→HOLDING 전이 엣지 도메인 추가.
+  - **BAT-052** (dcy-035): WAC 실현손익 운영리포트 통합 — portfolio-hub `/pnl/realized` read 포트+어댑터+stub(REQ-109), `trex-core report`에 WAC 실현손익 섹션 통합(REQ-110), portfolio-hub 미가용 시 degrade(폴백 없음, REQ-111). **매수 수수료를 WAC에 편입(CHG-20260626-02)**. 전일매수+당일매도 시나리오에서 운영리포트가 portfolio-hub WAC 정확값을 표시.
+  - **BAT-053** (dcy-036): 그날-시작 KIS 인증정보 fetch + fail-safe 로드 스캐폴드 — portfolio-hub broker credential read 포트+어댑터+stub(REQ-112), KISConfig 소스 우선순위 opt-in(`credential_fetch_enabled`) + break-glass 환경변수(REQ-113), fail-closed 신규 진입 차단 + CRITICAL 알람(REQ-114), 그날 고정 캐시 + portfolio-hub 장애 비중단(REQ-115). **`credential_fetch_enabled` 기본값 = `false` — opt-in OFF 시 기존 동작 byte-for-byte 보존.**
+  - **BAT-054** (dcy-036): 그날-시작 KIS 인증정보 양의 경로 주입 — KISBroker `reinitialize(cred)` 메서드(REQ-113 AC-2, REQ-115 AC-1), break-glass 로그 content assert 보강(REQ-113 AC-4). **`credential_fetch_enabled = false`(기본) 경로 완전 보존 — 코드는 배포되나 비활성(휴면). 실거래 KIS 인증정보 경로 미전환.**
+
+- Excluded:
+  - **dcy-036 실거래 활성화(credential_fetch_enabled = true 플립)**: 이번 릴리즈에서 비활성 배포. 플립 전환은 별도 절차(사장님 결재 + pf-hub dcy-010 배포 선행 + 실 KIS 통합검증 포함) 필요 — 아래 "후속 플립 선결 조건" 참조.
+  - reconcile 비차단 거버넌스 후속(AC-9 change-req 등): M3 백로그.
+  - 실 portfolio-hub 통합 E2E 검증(dcy-010 배포 후 가능): REL-010 go 조건 아님.
+  - INFO·WARN 알람 code 배선: dcy-033 범위 경계 밖, M3 이후.
+
+- Scope Note:
+  - **dcy-036 휴면 배포**: BAT-053/BAT-054 코드는 `credential_fetch_enabled = false`(기본값) 경로에서 완전히 비활성. QC가 opt-in OFF 경로에서 byte-for-byte 회귀 보존 확인. 라이브 실거래 무영향 보장.
+  - **PR #35 머지 선결**: BAT-054는 현재 `feat/dcy-036-kis-credential-inject` 브랜치(commit `6b066e1`)에 있으며 main 미머지 상태. 이 릴리즈 배포 전 PR #35 사장님 결재·머지가 선결 조건.
+  - **배포 대상 revision**: PR #35 머지 후의 main HEAD. 현재 main HEAD는 `a50b5e3`(BAT-054 SDLC 문서까지 포함).
+  - **REL-010 구성**: dcy-034(BAT-050+051 = core-A+B) + dcy-035(BAT-052) + dcy-036(BAT-053+054 = 휴면).
+
+## 배포 선결 조건 (필독)
+
+1. **PR #35 사장님 결재·머지** (BAT-054 `feat/dcy-036-kis-credential-inject` → main). 미머지 시 배포 불가.
+2. **QC confirm-batch-verification** (BAT-054): BAT-054 `verification.md` Status = draft. 팀장 및 qc-reviewer 확인 후 release-candidate 전환 필요.
+3. **전체 테스트 green 확인**: PR #35 머지 후 main HEAD에서 `pytest -q` → 0 fail. 현재 BAT-054 단계 기준 757 passed, 47 skipped.
+
+## 후속 플립 선결 조건 (이번 릴리즈 go 조건 아님, 별도 기재)
+
+`credential_fetch_enabled = true` 전환(실거래 KIS 인증정보 경로 활성화)은 이 릴리즈와 **분리**된 별도 절차다. 활성화 전 아래 조건이 모두 충족되어야 한다.
+
+- portfolio-hub dcy-010 배포 완료 및 `/v1/user_info` broker credential 엔드포인트 정상 응답 확인.
+- 실 portfolio-hub + 실 KIS mock(또는 openapivts) 환경에서 그날-시작 fetch → KISBroker reinitialize → 장중 주문 처리까지 end-to-end 통합 검증(REQ-115 AC-1 완전 충족).
+- REQ-113 AC-1 실 KIS 통합검증 통과.
+- 사장님 결재.
+
+## Rollout Plan
+
+1. **배포 전 준비**
+   - PR #35 머지 확인 — main HEAD가 BAT-054 구현 커밋 포함인지 git log로 검증.
+   - 전체 테스트 green 확인: PR #35 머지 후 main에서 `python3 -m pytest -q` → 0 fail (기준: 757 passed, 47 skipped).
+   - BAT-050 Status = release-candidate / BAT-051 Status = release-candidate / BAT-052 Status = release-candidate / BAT-053 Status = release-candidate 확인.
+   - BAT-054 Status = release-candidate 전환 확인 (QC confirm 완료 후).
+   - DB 마이그레이션 확인: BAT-050이 `slot_reconcile_warning` 테이블 신규 마이그레이션(`016_...sql`) 추가. 기동 시 `apply_migrations` 자동 실행 — 신규 테이블 생성 정상 완료 확인 필요.
+   - 의존성 변경 확인: `git diff 5bdd720 HEAD -- pyproject.toml` → 변경 없으면 `pip install -e .` 생략 가능(BAT-050~054 범위 기준 의존성 추가 없음).
+
+2. **배포 실행** (운영 환경 — `/root/release/trex-core`, instance_key=`trex-admin-daily-trading`, PID 849009 기준)
+   - 대상 커밋으로 체크아웃: `git fetch origin && git checkout main && git pull` (PR #35 머지 완료 후).
+   - 의존성 변경 시: `pip install -e .`
+   - 마이그레이션: `trex-core-daemon` 기동 시 `apply_migrations` 자동 실행 (001~016 idempotent, `slot_reconcile_warning` 신규 생성 포함).
+   - `trex-core-daemon` 재시작 (기존 PID 종료 → 신규 기동).
+   - 기동 로그에서 마이그레이션 완료(`apply_migrations` success) 및 워커 스레드 정상 기동 확인.
+   - tsl instance_key 데몬 동일 절차 반복 (동일 코드베이스 공유).
+
+3. **배포 후 검증** (아래 Verification Checklist 참조)
+
+4. **저녁 장외 윈도우 메모**: 장외 배포이므로 orb/tsl 전략 데몬 일시 연결 단절 허용. 무중단 절차 불필요. 배포 완료 후 reconcile sync/verify 동작 스모크 먼저 수행.
+
+## Rollback Plan
+
+- **트리거**: 데몬 기동 실패 / `slot_reconcile_warning` 마이그레이션 오류 / reconcile 차단 오발동(정상 슬롯 차단) / INACTIVE→HOLDING 전이 에러 / 운영리포트 이상(WAC 섹션 오류로 리포트 전체 불렌더) / 기존 AMQP wire 연동 장애 / credential_fetch_enabled OFF 경로에서 예상치 못한 fetch 시도 로그.
+- **절차**:
+  1. 데몬 정지.
+  2. 이전 커밋 체크아웃: `git checkout 5bdd720` (REL-009 배포본).
+  3. `pip install -e .` (필요 시).
+  4. `trex-core-daemon` 재기동.
+  5. **마이그레이션 롤백 주의**: `slot_reconcile_warning` 테이블은 자동 롤백 없음. 롤백 후에도 테이블이 DB에 잔존하나, 이전 코드에서 참조하지 않아 무해. 수동 삭제 필요 시:
+     ```sql
+     DROP TABLE IF EXISTS slot_reconcile_warning;
+     ```
+  6. **데이터 무손실**: 기존 slots / pause_store 스키마 불변. reconcile_warning 테이블만 가산. 롤백 후 운영 상태 정합 유지됨.
+- **부분 완화**: credential_fetch_enabled=OFF(기본값) 배포이므로 BAT-053/054 코드 경로가 실행되지 않아, 해당 코드 관련 트리거는 이 릴리즈에서 사실상 발생 불가.
+
+## Verification Checklist
+
+### 배포 전
+
+- [ ] PR #35 머지 완료 확인 (BAT-054 `feat/dcy-036-kis-credential-inject` → main).
+- [ ] BAT-054 confirm-batch-verification 완료 확인 (Status = release-candidate).
+- [ ] 전체 테스트 green: PR #35 머지 후 main HEAD에서 `python3 -m pytest -q` → 0 fail (기준: 757 passed, 47 skipped).
+- [ ] BAT-050 / BAT-051 / BAT-052 / BAT-053 / BAT-054 모두 Status = release-candidate 확인.
+- [ ] DB 마이그레이션 파일 확인: `trex_core/adapters/persistence/migrations/016_*.sql` 존재 여부.
+- [ ] `pyproject.toml` 의존성 변경 유무 확인 (`git diff 5bdd720 HEAD -- pyproject.toml`).
+- [ ] `docs/interface-contract.md` 변경 범위 확인: BAT-050~054 범위에서 AMQP wire 계약 변경 없음(기존 섹션 diff=0) 재확인.
+- [ ] **credential_fetch_enabled 기본값 = false 확인**: `trex_core/runtime/config.py` 또는 TOML 기본값이 false인지 재확인.
+
+### 배포 후 — 스모크
+
+- [ ] **데몬 기동 로그**: `apply_migrations` 완료(016번 포함) / 워커 스레드 정상 / ERROR/CRITICAL/Traceback 0.
+- [ ] **`slot_reconcile_warning` 테이블 생성 확인**: DB에서 `SELECT COUNT(*) FROM slot_reconcile_warning;` → 0 rows (초기 상태, 에러 없음).
+- [ ] **dcy-034 reconcile sync 동작 확인 (BAT-051 핵심)**: `trex-core sync --portfolio-id <pid> --dry-run` 명령이 에러 없이 before/after 프리뷰를 출력하는지 확인 (cold-start 시나리오).
+- [ ] **dcy-034 reconcile verify 동작 확인 (BAT-051 핵심)**: `trex-core verify --portfolio-id <pid>` 명령이 에러 없이 응답하는지 확인 (C-case 슬롯 대조).
+- [ ] **dcy-035 WAC 운영리포트 정합 확인 (BAT-052 핵심)**: `trex-core report` 실행 → WAC 실현손익 섹션 출력 확인. `PORTFOLIO_HUB_BASE_URL` 미설정 환경에서는 degrade(섹션 에러 출력, 타 섹션 정상) 확인.
+- [ ] **dcy-036 휴면 확인 (BAT-053/054 핵심)**: 기동 로그에서 `credential_fetch_enabled = false`(또는 부재) 경로로 동작하는지 확인. portfolio-hub fetch 시도 로그 미발생 확인.
+- [ ] **AMQP wire 무회귀**: orb/tsl 연동 상태 확인 — 기존 `trex.events`, `trex.intent.req`, `trex.slots.req`, `trex.control.req` 정상 동작. `slot_filled` NO_ROUTE 건수 급증 없음(REL-009 환류 항목).
+- [ ] **reconcile 차단 오발동 없음**: 정상 운영 중인 슬롯이 `reconcile_warned` 상태로 잘못 전이되지 않는지 장 시작 후 reconcile 주기 1회 경과 후 확인.
+- [ ] `trex-core report` 정상 동작 (REL-009 기능 회귀 없음).
+
+## AMQP Wire 계약 무회귀 체크포인트
+
+| 항목 | 변경 여부 | 근거 |
+|---|---|---|
+| `trex.events` exchange/토폴로지 | 불변 | BAT-050~054 전체 Out of Scope 명시 |
+| `trex.intent.req` 큐/라우팅 | 불변 | BAT-050 REQ-108 NFR-4 PASS |
+| `trex.slots.req` 큐/스키마 | `reconcile_warned` 필드 **additive 추가** | BAT-050 REQ-104 AC-4~8. 기존 클라이언트 무시 가능 (JSON extra key). orb/tsl 영향 없음. |
+| `trex.control.req` 큐 | 불변 | 변경 없음 |
+| `trex.alerts` exchange | 불변(REL-009에서 이미 추가됨) | BAT-053 CRITICAL 알람 사용(기존 경로 활용) |
+| 슬롯 이벤트 페이로드 스키마 | 불변 | BAT-050 `test_slot_state_enum_unchanged` PASS |
+| SlotState enum 값 | 불변(5개) | BAT-050 `test_slot_state_enum_unchanged` PASS |
+| ALLOWED_TRANSITIONS | **14개** (13→14: INACTIVE→HOLDING 추가) | BAT-051 sync-only 엣지. 일반 전략 경로(INACTIVE→PENDING_BUY) 무영향. `test_normal_strategy_path_unchanged` PASS |
+
+## Release Execution Evidence
+
+- Release Status Transition Target: released
+
+### Deployment Facts
+
+- Executed At:
+  - (미기입 — 배포 후 기록)
+- Completed At:
+  - (미기입 — 배포 후 기록)
+- Environment:
+  - 운영 (`/root/release/trex-core`, instance_key=`trex-admin-daily-trading`, 실거래 KIS 계좌 91254), bare .venv
+- Operator:
+  - (미기입 — 배포 후 기록)
+- Revision or Artifact:
+  - `5bdd720`(REL-009 배포본 = 현재 프로덕션) → **PR #35 머지 후 main HEAD** (BAT-050~054 전체 포함)
+  - BAT-050: commit `c193388`, BAT-051: commit `07b393d`, BAT-052: commit `73d3b35`+`d3e4af5`, BAT-053: commit `e4e5c70`, BAT-054: commit `6b066e1`
+- Commands or Procedure:
+  - `git fetch origin && git checkout main && git pull` (PR #35 머지 완료 후)
+  - 의존성 변경 시: `pip install -e .`
+  - 마이그레이션: `trex-core-daemon` 기동 시 `apply_migrations` 자동 실행 (001~016 idempotent, 016번 신규)
+  - `trex-core-daemon` 재시작 (기존 PID 종료 → 신규 기동)
+
+### Profile-Specific Checks
+
+- app-service:
+  - Health Endpoint:
+    - N/A (데몬은 HTTP 표면 없음). "ready" = 워커 스레드 + RabbitMQ 토폴로지 선언 완료 + 016번 마이그레이션 완료, 로그 ERROR/Traceback 0.
+  - Startup Log Fields:
+    - (미기입 — 배포 후 기록)
+  - Request Log Fields:
+    - (미기입 — 배포 후 기록)
+  - Smoke or Manual Verification:
+    - (미기입 — 배포 후 기록)
+
+### Rollback Outcome
+
+- Rollback Required:
+  - (미기입 — 배포 후 기록)
+- Rollback Trigger:
+  - (미기입 — 배포 후 기록)
+- Rollback Action:
+  - (미기입 — 배포 후 기록)
+
+### Release Decision Evidence
+
+- Released Decision:
+  - (미기입 — 배포 후 기록)
+- Rationale:
+  - (미기입 — 배포 후 기록)
+- Recorded By:
+  - (미기입 — 배포 후 기록)
+- Recorded At:
+  - (미기입 — 배포 후 기록)
+
+## Feedback Handoff
+
+- Observation Summary:
+  - (미기입 — 배포 후 기록)
+- Discovery Input:
+  - **dcy-036 실거래 활성화**: `credential_fetch_enabled = true` 플립 — portfolio-hub dcy-010 배포 + 실 KIS 통합검증 선행 후 별도 릴리즈. REQ-115 AC-1 완전 충족 선결.
+  - **slot_filled NO_ROUTE / fill→strategy 라우팅 재설계** (REL-009 환류 이월): M3 P1. fill 이벤트 라우팅키 strategy_id 미참조 문제.
+  - **reconcile 비차단 거버넌스 후속**: AC-9 change-req 등 M3 백로그.
+- REQ Input:
+  - none
+- Change Request Input:
+  - none
+
+## 알려진 리스크
+
+| 항목 | 수준 | 설명 | 해소 방안 |
+|---|---|---|---|
+| BAT-054 PR #35 미머지 | Critical | 배포 선결 조건 미충족 — 이 릴리즈 go 불가 | PR #35 사장님 결재·머지 선행 |
+| BAT-054 confirm-batch-verification 미완료 | High | verification.md Status=draft — QC 확인 선행 필요 | 팀장 검수 + qc-reviewer PASS 후 release-candidate 전환 |
+| slot_reconcile_warning 마이그레이션 실패 | Medium | DB 권한 부족 또는 기존 테이블 충돌 시 기동 실패 | 배포 전 DB 연결 권한 확인. 충돌 시 수동 DROP 후 재기동 |
+| reconcile 차단 오발동 | Medium | B/C 케이스 오탐 시 정상 슬롯 차단 가능 | 배포 후 장 시작 1 reconcile 주기 집중 모니터링. 오발동 확인 시 `trex-core verify` 또는 롤백 |
+| WAC 리포트 degrade | Low | portfolio-hub BASE_URL 미설정 또는 미가용 시 WAC 섹션만 에러 표시 | 타 섹션 정상 — 비치명적. BASE_URL 환경변수 점검 |
+| dcy-036 휴면 — byte-for-byte 회귀 보존 의존 | Low | opt-in OFF 경로에서 KIS fetch 로직 완전 비활성 의존. QC 확인 필요 | BAT-053/054 verification: credential_fetch_enabled=False 전체 스위트 PASS (757/47/0). 기동 로그에서 fetch 시도 미발생 재확인 |
+| REQ-115 AC-1 통합 검증 미완 | Low | 실 portfolio-hub + KIS mock 환경 미확보 — stub 기반만 검증. 이번 릴리즈 go 조건 아님 | 후속 플립 절차에서 선결 조건으로 관리 |