docs(dcy-034): confirm-req REQ-102~108 Approved — 차단형 reconcile + sync/verify

dcy-034 confirm-req 완료(팀장 2026-06-25): REQ-102(warning store)/103(차단 reconcile)/104(pause∨warning 게이트)/105(sync)/106(verify)/107(로깅·알람)/108(NFR) Approved. OQ-A(INACTIVE→HOLDING actor제한 전이)/OQ-B(안전망 차단예외)/OQ-C(verify C전용) 반영. FR-7→portfolio-hub dcy-008/REQ-043 교차참조. .claude/worktrees gitignore. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VHtM5Ws1HKCKQ4JGi6GRb5
2026-06-26 00:16:21 +09:00
parent e052e70619
commit 35f3147250
10 changed files with 797 additions and 4 deletions
@@ -0,0 +1,111 @@
+# req-106: trex-core verify 명령 — C 불일치 슬롯 재대조 + warning 해제
+
+- Status: Approved
+- Type: Interface
+- Priority: High
+- Owner: trex-core-dev
+
+## Intent
+- 운영자가 portfolio-hub CLI로 원장을 정정한 뒤 `trex-core verify [--portfolio-id <pid>]` 명령으로 **C 불일치(원장↔슬롯) 차단 슬롯을 재대조**하여, 일치 시 warning을 해제하고 불일치 시 사유와 함께 해제를 거부한다.
+- dcy-034 FR-4, OQ-2/5, **OQ-C 확정** 반영: read-중심 명령(슬롯 수량 변경 없음), 강제 해제(force-clear) 없음.
+- 재대조 로직은 현행 `reconcile_positions`(브로커 경유 2-대조)를 재사용한다(OQ-5).
+- **verify는 C 케이스(원장↔슬롯 수량 불일치) 전용**이다. B 케이스(슬롯↔브로커 수량 불일치)는 sync 명령(REQ-105)이 해소 경로이며 verify 범위에 포함되지 않는다(OQ-C 확정).
+
+## Requirement
+- 시스템은 `trex-core verify [--portfolio-id <pid>]` 서브커맨드를 제공해야 한다.
+- verify는 대상 슬롯(portfolio_id 기반)에 대해 `reconcile_positions`를 다시 실행해(브로커=정본, 원장↔브로커 대조) 일치 여부를 판정해야 한다.
+- 대조 결과 일치(원장 수량 == 브로커 수량)이면 `ReconcileWarningStore.clear_warned(slot_id)` 로 reconcile-warning을 해제하고 "해제됨" 메시지를 출력해야 한다.
+- 대조 결과 불일치이면 warning을 해제하지 않고 불일치 사유(원장 수량, 브로커 수량, 차이)를 출력하고 비-0 종료코드를 반환해야 한다(강제 해제 경로 없음).
+- verify는 슬롯 qty를 변경하지 않는다(read-중심 — 슬롯 수량 변경 없음).
+- verify는 C 케이스(case_code='C')로 warned된 슬롯만을 대상으로 한다. **B 케이스(슬롯↔브로커 수량 불일치)에 대한 해소는 sync 명령(REQ-105) 책임이며, verify는 B 케이스에 적용하지 않는다(OQ-C 확정, C 전용).**
+
+## Acceptance Criteria
+1. Given C 불일치로 차단된 슬롯에서 운영자가 portfolio-hub CLI로 원장을 정정하고 `trex-core verify --portfolio-id <pid>` 실행 시, When 원장 수량 == 브로커 수량이면, Then reconcile-warning이 해제되고 "해제됨" 메시지가 출력된다(S-3 1차).
+2. Given C 불일치로 차단된 슬롯에서 `trex-core verify` 실행 시, When 원장 수량 ≠ 브로커 수량이면, Then reconcile-warning이 해제되지 않고 불일치 사유(원장qty, 브로커qty, 차이)가 출력되며 비-0 종료코드를 반환한다(S-3 2차, 강제 해제 없음).
+3. Given verify 실행 시, When 어떤 경우에도, Then 슬롯 qty가 변경되지 않는다(read-중심 불변식).
+4. Given reconcile-warning이 없는 슬롯에 대해 verify 실행 시, When 명령이 실행되면, Then 이미 해제 상태임을 알리는 메시지 출력 후 0 종료코드로 반환한다(idempotent).
+5. Given `--json` 플래그로 verify 실행 시, When 명령이 실행되면, Then `{portfolio_id, slot_id, result: "cleared"|"rejected", hub_qty, broker_qty, reason?}` JSON이 stdout에 출력된다.
+6. Given `trex-core verify` (--portfolio-id 없이) 실행 시, When 명령이 실행되면, Then 인스턴스의 모든 C-warned 슬롯에 대해 재대조를 수행하고 결과를 슬롯별로 출력한다.
+
+## Impacted Area
+- Docs: `docs/operations.md` (원장 정정 후 verify 절차 추가), `docs/runtime-flows.md` (verify 흐름 추가)
+- Modules:
+  - `trex_core/runtime/cli.py` (`verify` 서브커맨드 추가)
+  - `trex_core/application/reconciliation.py` (`reconcile_positions` 재사용 또는 호출 래퍼 — batch design에서 결정)
+- Tests:
+  - `tests/runtime/test_cli.py` (verify 서브커맨드 인수 파싱)
+  - `tests/application/test_verify.py` 또는 `tests/integration/test_verify.py` (일치→해제, 불일치→거부, read-중심 불변식, idempotent)
+
+## Notes
+- OQ-5 확정: verify의 재대조는 `reconcile_positions`(원장↔브로커 2-대조, 브로커=정본)를 재사용한다. 별도 대조 로직을 만들지 않는다.
+- verify는 read-중심이므로 pause/resume의 live double-ack 게이트는 불필요하다. --yes, --live 옵션이 필요 없다.
+- **OQ-C 확정: verify는 C 전용**. B 케이스(슬롯↔브로커 수량 불일치)는 sync(REQ-105)로 해소한다. verify가 B-warned 슬롯 ID로 호출되면 "C 케이스 대상 아님" 안내 후 0 종료코드를 반환한다(batch design에서 메시지 확정).
+- dcy-034 FR-4, OQ-2/5, OQ-C(팀장 2026-06-25 confirm), S-3 대응.
+
+## Change Log
+
+### CHG-20260625-02
+- Date: 2026-06-25
+- Author: trex-core-dev
+
+#### Change Summary
+- REQ-106 **Proposed → Approved** (confirm-req, 팀장 2026-06-25).
+- OQ-C 결정 반영: verify = C 케이스(원장↔슬롯) 전용 확정. B 케이스는 sync(REQ-105) 책임. Intent, Requirement, Notes에 "C 전용, B는 sync 책임" 명시.
+
+#### Intent
+- 팀장 confirm-req 결정(OQ-C 확정: verify는 C 전용)을 REQ에 반영.
+
+#### Acceptance Criteria Delta
+- Added: 없음.
+- Updated: 없음(기존 AC는 이미 C 케이스 중심으로 작성됨).
+- Removed: 없음.
+
+#### Impacted Area Delta
+- Notes: OQ-C 확정 및 B-warned 슬롯 호출 시 처리 방침 추가.
+- Modules: cli.py verify 서브커맨드 — B-warned 슬롯 필터링 로직 추가 필요.
+
+#### Delivery Trace Delta
+- Batches: 미정 (suggest-batch-reqs 이후)
+- Releases: 미정
+
+#### Revalidation Impact
+- Reverification Needed: no
+- Existing Implementation Invalidated: no
+- Status Recommendation: Approved
+- Follow-up Action: batch design에서 B-warned 슬롯 필터링 메시지 확정.
+
+#### Validation Plan
+- 일치→해제, 불일치→거부 시나리오(C 케이스) 테스트 pass / B-warned 슬롯에 verify 적용 시 "대상 아님" 처리 테스트 pass / 슬롯 qty 불변 검증 / 기존 reconcile_positions 회귀 pass.
+
+### CHG-20260625-01
+- Date: 2026-06-25
+- Author: trex-core-dev
+
+#### Change Summary
+- REQ-106 신규 생성 (Proposed) — dcy-034 FR-4 대응, draft-req 단계.
+
+#### Intent
+- C 불일치 차단 해소를 위한 운영자 read-중심 재대조 경로 신설. 강제 해제 없이 재대조 일치 시에만 차단 해제.
+
+#### Acceptance Criteria Delta
+- Added: AC-1~6 전부 신규.
+- Updated: 없음.
+- Removed: 없음.
+
+#### Impacted Area Delta
+- Docs: operations.md, runtime-flows.md 갱신.
+- Modules: cli.py, reconciliation.py.
+- Tests: verify 시나리오 테스트 신규.
+
+#### Delivery Trace Delta
+- Batches: 미정
+- Releases: 미정
+
+#### Revalidation Impact
+- Reverification Needed: no (신규 REQ)
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: confirm-req 후 batch design.
+
+#### Validation Plan
+- 일치→해제, 불일치→거부 시나리오 테스트 pass / 슬롯 qty 불변 검증 / 기존 reconcile_positions 회귀 pass.