# BAT-021 Planning

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

## Included REQ
- REQ-034 (Interface, change-req): `WatchdogStore.last_seen` + snapshot 워치독 상태 노출.
- REQ-021 (Integration, change-req): snapshot 응답 `watchdog[]` 필드.
- REQ-037 (Integration, change-req): 워치독 소유 진입/이탈 + forced_close 발동 가시화.
- REQ-038 (Integration, change-req): stop_loss(WARN)/take_profit(INFO) 발동 가시화.
- REQ-039 (Integration, change-req): market_close 발동 가시화.
- REQ-032 (Interface, change-req): `trex-core slots` 워치독 소유 표시.
- REQ-042 (Documentation, change-req): runtime-flows/interface-contract 정합.

## Delivery Plan
1. REQ-034/021(서버): `watchdog.py` `last_seen` getter; `messaging_handlers.py` `_attach_watchdog`(best-effort) + `watchdog_timeout_sec` 파라미터; daemon 배선.
2. REQ-037/038/039(가시화): `safety_sell.py` `instance_key`/`counters`/`_log_fire`(phase 차등)/`_update_ownership`(소유 진입·이탈) + check_*·run_once 배선; daemon instance_key 배선.
3. REQ-032(CLI): `cli.py` `_cmd_slots` 가 watchdog 필드로 WATCHDOG-OWNED 표시.
4. REQ-042(문서): runtime-flows(워치독 노출 + safety-sell 가시화 flow), interface-contract(snapshot watchdog 필드).
5. 테스트: safety-sell 가시화 + snapshot watchdog 필드 + CLI 표시 + 전체 회귀 + ruff + 인프라 게이트.

## Dependencies
- Internal:
  - dcy-007/BAT-010·011 safety-sell/워치독(REQ-034/037/038/039) — 가시화 대상.
  - dcy-016/BAT-020 운영자 CLI `slots`·워치독 억제 읽기(REQ-032/021) — 비침습 관측 기반(A-1).
  - dcy-011/dcy-013 의 WARN+카운터 가시화 패턴 정합(NFR-3).
- External:
  - 없음(Redis 미채택). in-process 카운터.

## Design Gate
- Design Required Before Implementation: yes
- Reason: (a) 가시화 부수효과가 워치독 판정·safety-sell 청산을 절대 막으면 안 됨(R-1/NFR-1) — best-effort 격리 경계를 설계에서 못박아야 안전 기능 회귀를 막는다. (b) 워치독 소유 진입/이탈 diff 의 grace 처리·상태 보관(재시작 소실, R-3)·phase별 로그 레벨 매트릭스(OQ-2)를 설계에서 고정. (c) snapshot 응답에 watchdog 필드 추가가 REQ-028 strict envelope 와 충돌하지 않도록 additive top-level 필드 경계 확정. → design.md 동일 턴 scaffold.

## Milestones
1. M1 — REQ-034/021 watchdog last_seen + snapshot 필드, 핸들러 테스트 green
2. M2 — REQ-037/038/039 safety-sell 소유/발동 가시화 + 카운터, 가시화 테스트 green
3. M3 — REQ-032 CLI 표시
4. M4 — REQ-042 문서 정합
5. M5 — 전체 회귀 + ruff + 인프라 게이트

## Risks
- R-1 (High): 가시화가 실패/지연해 워치독 판정·청산을 막음. 대응: _attach_watchdog/_update_ownership/_log_fire 예외 격리, source of truth(in-memory) 불변. (NFR-1)
- R-2 (Low, OQ-1): 메커니즘 과잉. 대응: Redis 미채택, CLI/RPC 노출 + 로깅으로 한정.
- R-3 (Low): WatchdogStore in-memory → 재시작 시 소유 상태 소실. 대응: live 반영임을 문서화, 발동 로그는 이력 유지.

## Notes
- 1차 게이트: 전체 회귀 green(워치독 판정·safety-sell 트리거 무회귀 — 관측만 추가).
- 가시화 테스트는 caplog(WARN/INFO) + counters 단언으로 결정론.
- snapshot watchdog 필드는 operator(touch_watchdog=false) 요청으로 비침습 검증(폴링이 last_seen 갱신 안 함).