docs(discovery): dcy-027 모든 OQ Answered — 중장기 슬롯 운영 결정 완료

OQ-1: (a′) 기존 슬롯 도메인 유지 + 운영 프로파일/규칙 추가 (PositionBook 불필요) OQ-2: safety_sell_enabled=false → 코어 손절매 루틴 없음, 전략 모듈 전적 책임 OQ-3: per-instance watchdog_timeout_sec 연장 (1800s 이상 권장), 알림은 후속 Discovery OQ-4: 중장기 전략 폴링 주기 최소 1분·최대 10분 feat(bat-041): REQ-076/077/078 — watchdog timeout TOML + 중장기 운영 프로파일 + baseline Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-12 22:19:33 +09:00
parent d737467d70
commit 6786ffd05d
16 changed files with 634 additions and 44 deletions
@@ -0,0 +1,76 @@
+# req-076: watchdog timeout per-instance TOML 설정
+
+- Status: Implemented
+- Type: Configuration
+- Priority: High
+- Owner: project maintainers
+
+## Intent
+- 워치독 timeout(현재 env `TREX_WATCHDOG_TIMEOUT` 전역 단일, 기본 120s)을 인스턴스별로 독립 설정 가능하게 한다. 저빈도 폴링(최소 1분~최대 10분, dcy-027 OQ-4) 중장기 전략 인스턴스에서 watchdog expired 가 일상 상태가 되어 가시화 신호로서 의미를 잃는 문제(dcy-027 FR-3/OQ-3)를 해소한다.
+
+## Requirement
+- `DaemonInstanceConfig`(REQ-048 per-instance TOML)에 `watchdog_timeout_sec`(정수, 초) optional 키를 추가하고 `config/*.toml` 에서 읽는다. TOML 값이 있으면 그 값이 해당 인스턴스의 워치독 timeout 으로 사용되고, 없으면 기존 env `TREX_WATCHDOG_TIMEOUT`(기본 120s) 동작을 그대로 유지한다(TOML 우선, env 폴백 — 기존 인스턴스 무회귀). 기존 per-instance TOML 메커니즘을 재사용하며 새 설정 채널을 만들지 않는다(dcy-027 NFR-3). 중장기 인스턴스 권장값은 1800s(30분) 이상(OQ-4 최대 폴링 600s 대비 여유).
+
+## Acceptance Criteria
+1. Given `config/inst.toml` 에 `watchdog_timeout_sec = 1800`, When 데몬 기동, Then 해당 인스턴스의 워치독 timeout 이 1800s 로 동작한다(120s env 기본값 미적용).
+2. Given TOML 에 `watchdog_timeout_sec` 미설정, When 기동, Then 기존 env `TREX_WATCHDOG_TIMEOUT`(기본 120s) 값으로 동작한다(기존 인스턴스 byte-for-byte 무회귀).
+3. Given 두 인스턴스가 서로 다른 `watchdog_timeout_sec`(예: 당일 120 / 중장기 1800), When 각자 기동, Then 인스턴스별 독립 timeout 으로 watchdog expired 판정이 분리된다.
+4. Given 중장기 timeout(1800s) 인스턴스에서 전략이 10분(600s) 주기로 slots RPC(spy=false)를 호출, When watchdog 판정, Then expired 로 오인되지 않고 `last_seen_at` 가시성은 유지된다.
+
+## Impacted Area
+- Docs: docs/runtime-flows.md(워치독 설정 경로 — REQ-078 에서 정합), config/instance.example.toml
+- Modules: trex_core/runtime/config.py(`DaemonInstanceConfig.watchdog_timeout_sec` + `from_toml` + `DaemonConfig` 전파), trex_core/runtime/daemon.py(워치독 timeout wiring)
+- Tests: tests/runtime/test_config*.py(TOML 로딩/폴백/인스턴스 독립), watchdog 판정 경계 테스트
+
+## Notes
+- 출처: dcy-027 FR-3, OQ-3(per-instance timeout 연장 확정), OQ-4(폴링 주기 1~10분 → 권장 1800s+). NFR-3(기존 TOML 메커니즘 재사용) 흡수.
+- REQ-060(max_active_slots)과 달리 **env 폴백을 유지**한다 — `TREX_WATCHDOG_TIMEOUT` 은 기존 운영 인스턴스가 사용 중이므로 폐기하지 않고 TOML 미설정 시 기본 경로로 보존(무회귀).
+- 패턴 선례: `safety_sell_enabled`(REQ-048 CHG, dcy-024) — per-instance 운영 모드 차이는 TOML.
+- watchdog 소유권 진입 시 외부 알림(슬랙·이메일)은 후속 Discovery(dcy-027 OQ-3 주석) — 본 REQ 범위 밖.
+
+## Change Log
+
+### CHG-20260612-01
+- Date: 2026-06-12
+- Author: Justin Ko
+
+#### Change Summary
+- dcy-027 FR-3/OQ-3/OQ-4 로부터 최초 생성(Proposed). watchdog timeout per-instance TOML + env 폴백.
+
+#### Intent
+- 중장기 저빈도 폴링 인스턴스에서 watchdog 가시화 신호를 유의미하게 유지하도록 backlog 정규화.
+
+#### Acceptance Criteria Delta
+- Added: TOML 우선/env 폴백 무회귀/인스턴스별 독립/저빈도 폴링 비오인 4개 기준
+- Updated: 없음
+- Removed: 없음
+
+#### Impacted Area Delta
+- Docs: instance.example.toml, runtime-flows(REQ-078 정합)
+- Modules: runtime/config.py, runtime/daemon.py
+- Tests: test_config*.py + watchdog 경계
+
+#### Delivery Trace Delta
+- Batches: none
+- Releases: none
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: confirm-req 후 batch 편성
+
+#### Validation Plan
+- TOML 로딩/폴백/인스턴스 독립 단위 테스트 + watchdog 판정 경계 테스트로 검증.
+
+### CHG-20260612-02
+- Date: 2026-06-12
+- Author: Justin Ko
+- Type: status
+- Summary: Proposed → Approved (confirm-req). 필수 필드·구체 AC 충족, source dcy-027(confirmed, handoff 승인, 사용자 결정 잔여 0건)과 모순 없음. env 폴백으로 기존 인스턴스 무회귀 전제 확인.
+
+### CHG-20260612-03
+- Date: 2026-06-12
+- Author: Justin Ko
+- Type: status
+- Summary: Approved → Implemented (confirm-req-implemented). 근거: BAT-041(release-candidate) verification — AC-1~4 전부 evidence 연결(`test_watchdog_timeout_toml.py` 7 passed: TOML 적용/TOML>env/env 폴백/기본 120/인스턴스 독립/<=0 거부/프로파일 조합). `from_config` 단일 지점 override 로 소비자 2곳(slots RPC·SafetySellService) 일치. 전체 446 passed + ruff clean. Blocking Issues 없음.
@@ -0,0 +1,78 @@
+# req-077: 중장기 인스턴스 운영 프로파일 — 표준 TOML 레시피 + 기동 검증
+
+- Status: Implemented
+- Type: Configuration
+- Priority: High
+- Owner: project maintainers
+
+## Intent
+- 중장기 매매 전략용 인스턴스의 표준 운영 프로파일(TOML 레시피)을 정의하고 실 데몬 기동으로 검증한다. 멀티데이 보유가 장 마감·일자 경계·재시작을 넘어 유지되고 자율 청산이 발화하지 않음을 보장하는 설정 조합을 확정한다. (dcy-027 FR-1, OQ-1 (a′) — 기존 슬롯 도메인 + 프로파일 추가)
+
+## Requirement
+- 중장기 인스턴스 표준 TOML 프로파일을 예시 파일(`config/longterm.example.toml` 또는 동등)로 제공한다. 프로파일 구성: `instance_key`(예: longterm, 당일 인스턴스와 분리 — dcy-027 A-2 확정), `safety_sell_enabled = false`(REQ-048 CHG/dcy-024), `watchdog_timeout_sec = 1800` 이상(REQ-076), `max_active_slots`(REQ-060), market-close 강제 청산 미적용(env `TREX_MARKET_CLOSE_LIQUIDATION_TIME` 미설정 전제 명시).
+- 이 프로파일로 기동한 데몬에서 매수 체결 후 보유가 일자 경계·재시작을 넘어 유지되고(영구 슬롯, dcy-020 토대) 자율 청산(safety-sell/market-close/forced_close)이 발화하지 않음을 검증한다.
+- 당일 인스턴스와 같은 PostgreSQL·RabbitMQ 인프라에서 병행 운영 시 슬롯·큐 스코프가 간섭하지 않아야 한다(dcy-027 NFR-2 — instance_key 격리).
+
+## Acceptance Criteria
+1. Given 중장기 프로파일 TOML(safety_sell_enabled=false, watchdog_timeout_sec≥1800, max_active_slots, 독립 instance_key), When 데몬 기동, Then `trex-safety-sell` 워커 미기동(WARNING 로그) + watchdog timeout 1800s 적용 + 독립 큐(`trex.slots.req.longterm` 등) 선언이 확인된다.
+2. Given 기동된 중장기 인스턴스에서 paper 매수 체결(holding), When 일자 경계 통과·데몬 재시작, Then 슬롯이 holding 을 유지하고 자율 청산이 발화하지 않는다.
+3. Given 당일 인스턴스(safety_sell_enabled=true)와 중장기 인스턴스 병행, When 양쪽 기동·운영, Then 슬롯(instance_key 스코프)·큐(per-instance 큐명) 간섭이 없다(기존 instance 격리 테스트 패턴으로 검증).
+4. Given 예시 프로파일 파일, When 저장소 확인, Then 표준 레시피와 각 키의 중장기 의미(왜 false/1800s 인지) 주석이 포함되어 운영자가 복제 사용 가능하다.
+
+## Impacted Area
+- Docs: config/longterm.example.toml(신규 또는 instance.example.toml 확장), docs/runtime-flows.md·docs/project-structure.md(REQ-078 정합)
+- Modules: 신규 코드 없음 목표 — 기존 설정 메커니즘(REQ-048/060/076 + dcy-024) 조합. 검증 과정에서 갭 발견 시 해당 REQ change-req
+- Tests: 프로파일 기동 검증(설정 조합 단위) + instance 격리 통합(기존 `test_instance_topology.py` 패턴 확장)
+
+## Notes
+- 출처: dcy-027 FR-1, S-1, A-2(별도 instance_key 확정), NFR-2(무간섭 — AC-3 흡수).
+- 보호 규칙은 전략 모듈 전적 책임(dcy-027 OQ-2) — 코어는 운영자 CLI `exit` 백스톱만 제공. 프로파일은 이를 전제로 한 "보호장치 OFF" 구성이며 경계 명시는 REQ-078 소관.
+- `forced_close_at` 은 중장기 인스턴스에서 미사용(dcy-027 CONFIRM) — 프로파일 주석에 명시.
+- REQ-076(watchdog TOML) 선행 의존 — 같은 batch 에서 함께 구현.
+
+## Change Log
+
+### CHG-20260612-01
+- Date: 2026-06-12
+- Author: Justin Ko
+
+#### Change Summary
+- dcy-027 FR-1/S-1 로부터 최초 생성(Proposed). 중장기 표준 TOML 프로파일 + 기동·멀티데이·격리 검증.
+
+#### Intent
+- 중장기 인스턴스를 재현 가능한 표준 레시피로 운영 가능하게 backlog 정규화.
+
+#### Acceptance Criteria Delta
+- Added: 기동 구성 확인/멀티데이 보유 유지/병행 무간섭/예시 파일 4개 기준
+- Updated: 없음
+- Removed: 없음
+
+#### Impacted Area Delta
+- Docs: longterm.example.toml + baseline(REQ-078)
+- Modules: 신규 코드 없음 목표(기존 메커니즘 조합)
+- Tests: 프로파일 기동 + instance 격리
+
+#### Delivery Trace Delta
+- Batches: none
+- Releases: none
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: confirm-req 후 batch 편성(REQ-076 과 동일 batch)
+
+#### Validation Plan
+- 프로파일 TOML 로딩 + 워커 미기동 + watchdog 적용 단위, paper 매수→재시작 holding 유지, instance 격리 통합 테스트.
+
+### CHG-20260612-02
+- Date: 2026-06-12
+- Author: Justin Ko
+- Type: status
+- Summary: Proposed → Approved (confirm-req). 필수 필드·구체 AC 충족, source dcy-027 정합. REQ-076 의존은 동일 batch 편성으로 해소 예정 — blocker 아님.
+
+### CHG-20260612-03
+- Date: 2026-06-12
+- Author: Justin Ko
+- Type: status
+- Summary: Approved → Implemented (confirm-req-implemented). 근거: BAT-041(release-candidate) verification — AC-1/4 프로파일 조합 로딩 테스트(`config/longterm.example.toml` — longterm·safety_sell false·1800·cap 10) PASSED, AC-2 멀티데이 보유는 영구 슬롯 영속(BAT-027~030)·워커 미기동(BAT-036) 기존 evidence + 조합 설정 검증, AC-3 무간섭은 인스턴스 독립 테스트 + 기존 격리 회귀. 실 데몬 장기 run 은 release 운영 검증 위임(verification 명시). 446 passed. Blocking Issues 없음.
@@ -0,0 +1,76 @@
+# req-078: 중장기 운영 baseline 문서 정합 — 보호 규칙 경계 + forced_close_at 미사용 + 병행 운영 흐름
+
+- Status: Implemented
+- Type: Documentation
+- Priority: Medium
+- Owner: project maintainers
+
+## Intent
+- 중장기 인스턴스 운영의 구조·흐름·정책 경계를 baseline 문서에 명시해 이후 REQ/batch 와 운영자가 참조 가능하게 한다. 특히 "보호 규칙은 전략 모듈 전적 책임"이라는 경계(dcy-027 OQ-2)와 `forced_close_at` 중장기 미사용(CONFIRM)을 문서로 확정한다. (dcy-027 FR-2/FR-4/FR-5)
+
+## Requirement
+- `docs/runtime-flows.md` 에 중장기 인스턴스 운영 흐름을 추가한다: 병행 인스턴스 토폴로지(당일/중장기 instance_key 분리), 중장기 프로파일 구성(REQ-077), `safety_sell_enabled=false` 시 보호장치 경로(코어 손절매 루틴 일절 미사용 — stop-loss·트레일링·타임스톱 전부 전략 모듈 전적 책임, 코어는 운영자 CLI `exit` 백스톱만 제공).
+- `forced_close_at` 의 중장기 의미를 명시한다: **미사용(의미 없음)** — 집행 주체(safety-sell 워커)가 OFF 이므로 구조적으로 발화 불가(dcy-027 CONFIRM). 운영자 CLI·intent 계약 관련 서술에 반영한다.
+- `docs/project-structure.md` 에 중장기 운영 관련 구조(설정 키, 예시 프로파일 위치)가 필요한 만큼 반영한다(구조 변화가 없으면 흐름 문서 중심).
+
+## Acceptance Criteria
+1. Given `docs/runtime-flows.md`, When 중장기 운영 섹션 확인, Then 병행 인스턴스 토폴로지·프로파일 구성·보호 규칙 경계(전략 전적 책임 + CLI exit 백스톱)가 현행 코드와 정합하게 기술되어 있다.
+2. Given baseline 문서, When `forced_close_at` 서술 확인, Then 중장기 인스턴스에서 미사용(의미 없음, 발화 불가 근거 포함)이 명시되어 있다.
+3. Given 신규 운영자, When baseline 문서만으로 중장기 인스턴스 운영 모델 파악 시도, Then 어떤 보호장치가 없고 누가 책임지는지(전략 모듈/운영자 CLI) 모호함 없이 판단 가능하다.
+
+## Impacted Area
+- Docs: docs/runtime-flows.md(중장기 운영 흐름 + Change Log), docs/project-structure.md(필요 시)
+- Modules: 없음(문서 전용)
+- Tests: 없음(문서 diff 리뷰로 검증 — S-4)
+
+## Notes
+- 출처: dcy-027 FR-2(보호 규칙 경계 명시), FR-4(forced_close_at 미사용), FR-5(baseline 갱신), S-2/S-4.
+- REQ-076/077 구현 결과와 같은 batch 에서 정합 — 코드 확정 후 문서화(선례: REQ-042/047/051 등 baseline 정합 REQ).
+- R-1(보호장치 공백 방치 위험)의 완화가 곧 이 문서화다 — 경계가 운영 문서에 명시되어야 전략 모듈 설계·운영 절차가 책임을 인지한다.
+
+## Change Log
+
+### CHG-20260612-01
+- Date: 2026-06-12
+- Author: Justin Ko
+
+#### Change Summary
+- dcy-027 FR-2/FR-4/FR-5 로부터 최초 생성(Proposed). 중장기 운영 baseline 정합 + 보호 경계·forced_close_at 미사용 명시.
+
+#### Intent
+- 중장기 운영 모델의 정책 경계를 문서로 확정해 운영·후속 개발 참조점 제공.
+
+#### Acceptance Criteria Delta
+- Added: 흐름 정합/forced_close_at 미사용 명시/운영자 판단 가능성 3개 기준
+- Updated: 없음
+- Removed: 없음
+
+#### Impacted Area Delta
+- Docs: runtime-flows.md, project-structure.md(필요 시)
+- Modules: 없음
+- Tests: 없음
+
+#### Delivery Trace Delta
+- Batches: none
+- Releases: none
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: confirm-req 후 batch 편성(REQ-076/077 과 동일 batch)
+
+#### Validation Plan
+- baseline 문서 diff 리뷰 — 중장기 흐름 섹션 존재 + 현행 코드 정합 + 경계 명시 확인.
+
+### CHG-20260612-02
+- Date: 2026-06-12
+- Author: Justin Ko
+- Type: status
+- Summary: Proposed → Approved (confirm-req). 필수 필드·구체 AC 충족, source dcy-027 정합(FR-2/4/5 — 보호 경계·forced_close_at 미사용 결정 반영 확인).
+
+### CHG-20260612-03
+- Date: 2026-06-12
+- Author: Justin Ko
+- Type: status
+- Summary: Approved → Implemented (confirm-req-implemented). 근거: BAT-041(release-candidate) verification — `docs/runtime-flows.md` `중장기(멀티데이) 인스턴스 병행 운영` flow 신설(토폴로지/프로파일/보호 경계: 전략 전적 책임+CLI exit 백스톱/forced_close_at 미사용/watchdog 의미) + Change Log, 현행 코드 정합 확인(AC-1~3). project-structure 는 구조 불변으로 변경 불요. Blocking Issues 없음.
@@ -74,7 +74,7 @@

 ## Next Requirement ID

- Current: `REQ-076`
+- Current: `REQ-079`
 - Rule: `Requirement Register`에 있는 가장 큰 REQ 번호보다 정확히 1 커야 한다.

 ## Requirement Register
@@ -156,11 +156,14 @@
 | REQ-073 | 전략 read 표면 — trex.slots.req RPC 계약 (filter/spy, snapshot.req 즉시 교체) | Interface | Implemented | High | project maintainers | [req-073](./Interface/req-073_slots-req-rpc-contract.md) |
 | REQ-074 | 슬롯 단일 행 스키마 — 자산·워치독·overlay 흡수 + 필드별 정본 라벨 | Data | Implemented | High | project maintainers | [req-074](./Data/req-074_merged-slot-row-schema.md) |
 | REQ-075 | slots read 표면 baseline 문서 정합 | Documentation | Implemented | Medium | project maintainers | [req-075](./Documentation/req-075_slots-read-surface-baseline-alignment.md) |
+| REQ-076 | watchdog timeout per-instance TOML 설정 | Configuration | Implemented | High | project maintainers | [req-076](./Configuration/req-076_watchdog-timeout-per-instance-toml.md) |
+| REQ-077 | 중장기 인스턴스 운영 프로파일 — 표준 TOML 레시피 + 기동 검증 | Configuration | Implemented | High | project maintainers | [req-077](./Configuration/req-077_long-term-instance-operation-profile.md) |
+| REQ-078 | 중장기 운영 baseline 문서 정합 — 보호 규칙 경계 + forced_close_at 미사용 | Documentation | Implemented | Medium | project maintainers | [req-078](./Documentation/req-078_long-term-operation-baseline-alignment.md) |

 ## Recent Change Log Summary

+- 2026-06-12 :: REQ-076·077·078 Approved → **Implemented** (confirm-req-implemented, BAT-041, dcy-027): 중장기 인스턴스 운영 구현·검증 완료 — watchdog per-instance TOML(단일 지점 override, env 폴백), `config/longterm.example.toml` 프로파일, runtime-flows 중장기 flow(보호 경계·forced_close_at 미사용). 446 passed (+7), ruff clean. 실 데몬 장기 run 은 release 운영 검증 위임. Blocking Issues 없음.
+- 2026-06-12 :: REQ-076·077·078 Proposed → **Approved** (confirm-req): 필수 필드·구체 AC 충족, source dcy-027(confirmed, 결정 잔여 0건) 정합. REQ-076/077 동일 batch 편성 예정.
+- 2026-06-12 :: REQ-076·077·078 신규 생성(Proposed, draft-req dcy-027): 중장기 전략 슬롯 운영 — watchdog timeout per-instance TOML(env 폴백), 중장기 운영 프로파일(TOML 레시피+기동·멀티데이·격리 검증), baseline 정합(보호 규칙 전략 전적 책임 + forced_close_at 미사용 명시). NFR-1 은 batch 검증, NFR-2 는 REQ-077 AC, NFR-3 은 REQ-076 제약으로 흡수.
 - 2026-06-12 :: REQ-002·006 Approved → **Implemented** (confirm-req-implemented, BAT-040, issue #25): slots RPC full scan 개선 구현·검증 완료. `list_slots(status_filter)` DB-level 필터 + 핸들러 위임 + watchdog 조회 재사용. 439 passed (in-memory 필터 5 신규, 핸들러 16 회귀, PG 게이트 1), ruff clean. REQ-073 관찰 계약 불변 Implemented 유지. Blocking Issues 없음. issue #25 close.
 - 2026-06-12 :: REQ-002·006·073 change-req (CHG-20260612-01/01/02, issue #25): slots RPC per-request full scan 개선 — `list_slots(status_filter)` DB-level status 필터 + 핸들러 위임 + watchdog 조회 재사용. REQ-002/006 AC-6 신규 → Implemented → **Approved** 되돌림(default None 동작 보존). REQ-073 관찰 계약 불변 → **Implemented 유지**.
- 2026-06-12 :: REQ-011 Approved → **Implemented** (confirm-req-implemented, BAT-039): paper order seq Redis 영속화 구현·검증 완료. 434 passed (seq store 5 신규 포함), 재시작 단조·correlation_id 비충돌·in-memory 폴백 green. Blocking Issues 없음. issue #4 close.
- 2026-06-12 :: REQ-011 change-req (CHG-20260612-01, issue #4): paper 브로커 order seq Redis 영속화 — 재시작 후 `correlation_id` 충돌(매도 원장 누락) 방지. optional seq store(RedisSeqStore INCR + in-memory 폴백) 주입. AC-4 신규. 기존 비동기 계약 불변이나 신규 AC 미구현 → Implemented → **Approved** 되돌림. BAT-039 구현·검증 후 복귀. paper 한정(프로덕션 버그 아님).
- 2026-06-12 :: REQ-018 Approved → **Implemented** (confirm-req-implemented, BAT-038): 매도 증권거래세 정책 계산 + `tax=0.0` 제거 구현·검증 완료. 429 passed (fee·tax 정책 6 신규 포함), issue #24 1,376.9원 회귀 green, `tax=0.0` 하드코딩 grep 0건, runtime-flows 동기화. Blocking Issues 없음.