trex-core/docs/srs/Documentation/req-042_safety-sell-baseline-alignment.md

req-042: safety-sell baseline 문서 정합

• Status: Implemented
• Type: Documentation
• Priority: Medium
• Owner: project maintainers

Intent

dcy-007에서 정의된 자율 안전 매도 기능(REQ-034~041)의 구현 완료 후 docs/interface-contract.md, docs/runtime-flows.md, docs/project-structure.md 세 baseline 문서를 최신 아키텍처와 정합시킨다.

Requirement

• docs/interface-contract.md에 아래 항목을 반영해야 한다:
  • intent RPC payload에 stop_loss_price, take_profit_price 선택 필드 추가
  • update_thresholds action 계약 (payload 구조, 응답 구조, holding-only 제약)
  • snapshot RPC가 워치독 last_seen_at 갱신 신호임을 명시
• docs/runtime-flows.md에 아래 흐름을 추가해야 한다:
  • per-slot 워치독 갱신 흐름 (snapshot RPC handler → last_seen_at 갱신)
  • forced_close_at 만기 자동 매도 흐름 (safety-sell worker → forced_close_at 체크 → sell())
  • stop-loss·take-profit 가격 체크 흐름 (KIS polling → 조건 평가 → sell())
  • 장 마감 강제 청산 흐름 (TREX_MARKET_CLOSE_LIQUIDATION_TIME → 전체 holding 매도)
  • runtime-flows.md:114의 "A-5 미구현" 주석을 dcy-007 REQ 목록 참조로 갱신
• docs/project-structure.md에 아래 항목을 반영해야 한다:
  • Primary Runtime 스레드 목록에 trex-safety-sell 추가
  • 신규 5종 env var(TREX_WATCHDOG_TIMEOUT 등) 목록 추가
  • 신규 어댑터/모듈(KIS 현재가 polling, watchdog store) 반영

Acceptance Criteria

1. Given docs/interface-contract.md를 읽을 때, When update_thresholds action을 찾으면, Then payload 구조(slot_id, stop_loss_price?, take_profit_price?, forced_close_at?)와 응답(status: updated|ignored)이 명시되어 있다.
2. Given docs/interface-contract.md를 읽을 때, When intent RPC payload 예시를 찾으면, Then stop_loss_price와 take_profit_price가 선택 필드로 포함되어 있다.
3. Given docs/runtime-flows.md를 읽을 때, When safety-sell 관련 흐름을 찾으면, Then 워치독 갱신·forced_close_at 체크·가격 체크·장 마감 청산 흐름이 각각 서술되어 있다.
4. Given docs/runtime-flows.md:114(또는 이에 해당하는 broker degrade 흐름)을 읽을 때, When "A-5 미구현" 주석을 찾으면, Then 해당 주석이 dcy-007 구현 REQ 참조로 갱신되어 있다.
5. Given docs/project-structure.md를 읽을 때, When Primary Runtime 스레드 목록을 찾으면, Then trex-safety-sell이 포함되어 있다.

Impacted Area

• Docs:
  • docs/interface-contract.md
  • docs/runtime-flows.md
  • docs/project-structure.md
• Modules: 없음 (문서 전용)
• Tests: 없음

Notes

• 이 REQ는 REQ-034~041 구현이 완료된 후 실행해야 한다. batch verification 단계에서 최신 구현 상태를 반영해 문서를 갱신한다.
• runtime-flows.md:114의 "A-5 미구현" 문구는 dcy-007 confirmed 시점에 이미 근거가 확보됐으므로, 구현 완료 전에도 "dcy-007 REQ-034~041로 트래킹" 형태로 미리 갱신할 수 있다.
• NFR-2(outbox retry) 관련 흐름은 기존 runtime-flows.md의 outbox 섹션에 흡수되어 있으므로 별도 추가 불필요.

Change Log

CHG-20260607-01

• Date: 2026-06-07
• Author: Justin Ko

Change Summary

• dcy-007 confirmed → REQ-042 초안 생성

Intent

• safety-sell 구현 후 세 baseline 문서 정합을 Documentation REQ로 정규화

Acceptance Criteria Delta

• Added: AC-1~5 전체

Impacted Area Delta

• Docs: interface-contract.md, runtime-flows.md, project-structure.md

Delivery Trace Delta

• Batches: none (미할당)
• Releases: none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: suggest-batch-reqs 후 batch 배정 (REQ-034~041 구현 batch 이후 연계)

CHG-20260607-02

• Date: 2026-06-07
• Author: Justin Ko

Change Summary

• Proposed → Approved (confirm-req)

Intent

• 승인 게이트 통과: 필수 필드·AC·Impacted Area·Change Log 완비 확인. dcy-007(confirmed) 범위 및 결정 사항과 모순 없음.

Acceptance Criteria Delta

• (변경 없음)

Impacted Area Delta

• (변경 없음)

Delivery Trace Delta

• Batches: none (미할당)
• Releases: none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: suggest-batch-reqs 후 batch 배정

CHG-20260607-03

• Date: 2026-06-07
• Author: Justin Ko

Change Summary

• Status Approved → Implemented (confirm-req-implemented, 근거 batch BAT-011 release-candidate).

Intent

• BAT-011 에서 세 baseline 문서 정합 완료(interface-contract: update_thresholds 계약 + price 선택 필드 + 워치독 신호; runtime-flows: 워치독 갱신/forced_close/가격 체크/장 마감 4종 흐름 + A-5 주석 갱신; project-structure: trex-safety-sell 스레드 + watchdog.py/safety_sell.py 모듈). AC-1~5 충족 → 구현 완료 동기화.

Acceptance Criteria Delta

• (변경 없음)

Impacted Area Delta

• (변경 없음)

Delivery Trace Delta

• Batches: BAT-011 (release-candidate)
• Releases: none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current (Implemented)
• Follow-up Action: draft-release 로 BAT-011 배포 편성.

CHG-20260608-01

• Date: 2026-06-08
• Author: Justin Ko

Change Summary

• (change-req, dcy-017) baseline 문서를 워치독 가시화에 맞춰 정합: docs/runtime-flows.md(워치독 상태 노출 + safety-sell 가시화 flow), docs/interface-contract.md(snapshot 응답 watchdog 필드). BAT-021 정합 완료 → Implemented 유지.

Intent

• 코드(watchdog/messaging_handlers/safety_sell/cli) 변경과 baseline 문서를 일치시켜 운영자 참조 정합 유지.

Acceptance Criteria Delta

• Updated:
  • runtime-flows/interface-contract 의 워치독 가시화·safety-sell 발동 가시화 기술 정합.

Impacted Area Delta

• Docs: docs/runtime-flows.md, docs/interface-contract.md

Delivery Trace Delta

• Batches: BAT-021
• Releases: none

Revalidation Impact

• Reverification Needed: no (문서 정합)
• Existing Implementation Invalidated: no
• Status Recommendation: Implemented (change-req → BAT-021 정합)
• Follow-up Action: confirm-req-implemented(BAT-021).

Validation Plan

• BAT-021: 코드-문서 diff 대조.