# BAT-029 Planning

- Status: confirmed
- Batch: BAT-029
- Profile: standard

## Included REQ
- REQ-061 (Interface, Approved): intent 자산(portfolio_id) 키 통일 + sell-by-slot_id 폐기(점진) + already_active/not_holding.
- REQ-062 (Integration, Approved): 수량 hub 정본+미러·청산=브로커·holding↔broker/hub 불일치 해소.
- REQ-063 (Interface, Approved): 운영자 slots 자산 포지션 단일 뷰.

## Delivery Plan
1. REQ-061: `SellIntent.portfolio_id: Optional[str]` 추가(slot_id Optional 로 완화). messaging_handlers sell 파싱이 portfolio_id|slot_id dual-accept. `_admit_sell` 자산 중심 분기 — portfolio_id 면 `find_slot_by_portfolio` → holding 이면 pending_sell, 아니면 `not_holding`. legacy slot_id 경로 유지. CLI `exit` 가 portfolio_id 수용(+slot_id 호환).
2. REQ-062: `reconcile_positions` 확장 — 코어 슬롯 holding 집합을 broker/hub 와 3자 비교. A(코어 holding/broker 0)=슬롯 error+warning, B(코어 flat/broker 보유)=warning/alert(운영자), C(수량만)=미러 갱신+warning, D(hub만)=기존 write-back. 청산 경로(safety_sell/execution)가 매도 수량을 브로커 잔고에서 조회(이미 그렇다면 확인). 자동 청산/편입 금지.
3. REQ-063: snapshot envelope slot dict 에 `universe_detached`(retired_at not null)·symbol 추가, `trex-core slots` 단일 뷰(자산 포지션·tombstone 표시).
4. runtime-flows.md 부분(intent 자산 키·불일치 해소).
5. 단위(sell 자산 키/dual-accept/divergence/slots 뷰) + 회귀 + ruff (+ test DSN).

## Dependencies
- Internal: BAT-028(find_slot_by_portfolio·count_active·reconcile), BAT-027(상태머신). dcy-005 reconcile_positions(REQ-031)·snapshot envelope.
- External: 전략 모듈(외부 repo) — dual-accept 로 무중단, portfolio_id 전환은 전략 측 후속.

## Design Gate
- Design Required Before Implementation: yes
- Reason: (a) sell 계약 변경은 **외부 전략 모듈** 영향(NFR-4) — dual-accept vs hard-switch 를 설계에서 확정해 무중단 보장. (b) divergence 해소(A/B/C/D)는 기존 reconcile_positions·error 상태·safety-sell 과 교차하고 자동 청산 금지 경계를 못박아야 안전. (c) 청산 수량 브로커 정본 경로가 이미 그러한지/바꿔야 하는지 확인. → design.md 확정 후 구현 전 체크포인트.

## Milestones
1. M1 — REQ-061 sell 자산 키 dual-accept + admission 분기 + CLI
2. M2 — REQ-062 reconcile divergence 확장 + 청산 브로커 정본
3. M3 — REQ-063 slots 단일 뷰 + runtime-flows + 회귀/ruff

## Risks
- R-contract (High): sell 계약 변경으로 라이브 전략 매도 불능. 대응: dual-accept(slot_id 유지), 전환은 BAT-δ.
- R-divergence (Medium): 불일치 해소가 자동 청산/오격리. 대응: 표면화만(warning/error/operator), 자동 청산 금지(issue #15), 회귀 테스트.

## Notes
- 자산 중심 모드(max_active_slots 설정)에서 자산 키 admission 활성; legacy 모드는 기존 slot_id sell 유지.
- 본 배치 green 기준: 단위 전체 회귀(legacy sell 무파손) + 신규 자산 키 sell/divergence/slots 단위.