docs: approve dcy-037 emergency requirements

2026-07-14 22:40:38 +09:00
parent 48b2af148e
commit c1e67c7055
6 changed files with 476 additions and 3 deletions
@@ -0,0 +1,118 @@
+# REQ-121: managed non-holding divergence 분류와 slot 존재 조회 계약
+
+- Status: Approved
+- Type: Data
+- Priority: High
+- Owner: trex-core-dev
+
+## Intent
+- broker-held symbol을 holding slot만으로 비교하면 동일 instance에 `inactive` 또는 `error` managed slot이 존재하는 경우도 true unmanaged position으로 잘못 분류된다.
+- holding 수량 대조의 기존 의미론을 보존하면서, unmatched broker holding의 managed slot 존재 여부를 repository parity로 확인해 안전한 triage classification을 제공한다.
+
+## Requirement
+- 시스템은 `reconcile_core_holdings()`에서 broker-held symbol이 holding slot에 매칭되지 않을 때 동일 instance의 관리 slot 존재 여부를 조회해야 한다.
+- slot이 전혀 없으면 기존 `unmanaged_position` 분류를 유지하고, slot은 존재하지만 non-holding 상태이면 `managed_non_holding_divergence`로 별도 분류해야 한다.
+- 이 분류는 slot 상태 전이, warning 자동 해제, 자동 매매, 자동 청산 또는 unmanaged holding의 자동 slot 생성을 유발하지 않아야 하며, 상태 수렴은 기존 승인 gate의 검증된 `sync` 경로에만 맡겨야 한다.
+- SlotRepository Protocol과 PostgreSQL/InMemory 구현은 instance-scoped managed-slot existence query에 대해 동등한 결과를 제공해야 한다.
+
+## Acceptance Criteria
+1. Given broker-held symbol에 대해 대상 instance에 어떤 slot도 없음, When `reconcile_core_holdings()`를 실행하면, Then `unmanaged_position` decision code와 기존 safe warning semantics가 유지된다.
+2. Given broker-held symbol에 대해 같은 instance의 slot이 `inactive` 또는 `error`이고 holding slot은 없음, When `reconcile_core_holdings()`를 실행하면, Then `managed_non_holding_divergence` decision code와 `slot_id`, `portfolio_id`, `symbol`, `status`, `instance_key`의 구조화·비밀 없는 triage context가 남는다.
+3. Given matching holding slot 또는 holding qty mismatch, When `reconcile_core_holdings()`를 실행하면, Then 각각 기존 match 및 mismatch path가 유지되고 non-holding divergence로 재분류되지 않는다.
+4. Given AC-1~3 fixture, When reconciliation 후 slot 및 warning persistence를 검사하면, Then managed non-holding 분류만으로 slot state write, warning 자동 해제, 자동 매매, 자동 청산 또는 unmanaged slot 생성이 발생하지 않는다.
+5. Given PostgreSQL 및 InMemory SlotRepository, When 같은 instance/symbol/portfolio fixture로 managed-slot existence query를 실행하면, Then 두 구현이 같은 존재 여부와 instance isolation 결과를 반환한다.
+6. Given 다른 instance에만 같은 symbol 또는 portfolio_id slot이 존재함, When reconciliation을 실행하면, Then 그것은 대상 instance의 managed slot으로 취급되지 않는다.
+
+## Impacted Area
+- Docs: `docs/runtime-flows.md`, `docs/interface-contract.md`, `docs/operations.md`, `docs/srs/Integration/req-103_blocking-reconcile-b-c-cases.md`, `docs/srs/Interface/req-105_sync-cli-command.md`
+- Modules: `trex_core/application/reconciliation.py`, `trex_core/domain/slot/repository.py`, `trex_core/adapters/persistence/postgresql.py`, `trex_core/domain/slot/in_memory_repository.py`
+- Tests: reconciliation 4-case regression matrix; PostgreSQL/InMemory repository parity; instance isolation; no-auto-write/no-auto-remediation assertions
+
+## Notes
+- Source Discovery: `docs/discovery/dcy-037_20260714_operator-broker-truth-and-managed-slot-divergence-hotfix.md` (FR-4~5, NFR-2~4; GitHub #41).
+- Existing `list_holding_slots(instance_key)` is holding-only evidence; this REQ adds the separate managed-slot existence decision needed only after an unmatched broker holding.
+- This is additive classification. `sync --live` target selection and execution remain release-gated and out of scope.
+
+## Change Log
+
+### CHG-20260714-01
+- Date: 2026-07-14
+- Author: delivery-runner
+
+#### Change Summary
+- dcy-037 #41의 managed non-holding divergence와 repository query parity를 Proposed REQ로 초안화했다.
+
+#### Intent
+- 진짜 unmanaged broker holding과 이미 관리되는 non-holding slot divergence를 혼동하지 않도록 한다.
+
+#### Acceptance Criteria Delta
+- Added:
+  - 4-case reconciliation matrix, repository parity/instance isolation, additive no-auto-remediation constraints.
+- Updated:
+  - 없음.
+- Removed:
+  - 없음.
+
+#### Impacted Area Delta
+- Docs:
+  - reconcile decision 및 operator triage baseline.
+- Modules:
+  - reconciliation 및 slot repository protocol/implementations.
+- Tests:
+  - application classification 및 DB/in-memory parity regression.
+
+#### Delivery Trace Delta
+- Batches:
+  - none (draft only; dcy-037 emergency scope의 향후 입력).
+- Releases:
+  - none (production read/write 또는 live sync 실행 없음).
+
+#### Revalidation Impact
+- Reverification Needed: yes
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: confirm-req 전 decision-code naming과 existing warning/alert inventory compatibility를 검토한다.
+
+#### Validation Plan
+- isolated four-case fixture와 PostgreSQL/InMemory parity suite에서 classification, structured context, instance scope 및 no-write invariant를 검증한다.
+
+### CHG-20260714-02
+- Date: 2026-07-14
+- Author: Justin (TREX lead)
+
+#### Change Summary
+- Proposed에서 Approved로 승인했다.
+
+#### Intent
+- dcy-037 #41의 additive classification을 기존 holding mismatch와 unmanaged semantics를 보존하는 delivery input으로 확정한다.
+
+#### Acceptance Criteria Delta
+- Added:
+  - 없음.
+- Updated:
+  - 없음.
+- Removed:
+  - 없음.
+
+#### Impacted Area Delta
+- Docs:
+  - 없음.
+- Modules:
+  - 없음.
+- Tests:
+  - 없음.
+
+#### Delivery Trace Delta
+- Batches:
+  - dcy-037의 #39/#40/#41 단일 emergency batch (아직 미생성).
+- Releases:
+  - none; `sync --live`는 별도 release approval gate 유지.
+
+#### Revalidation Impact
+- Reverification Needed: yes
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: suggest-batch-reqs에서 REQ-119/120과 함께 emergency batch로 편성한다.
+
+#### Validation Plan
+- batch verification과 독립 QC에서 4-case matrix, repository parity, instance isolation 및 no-auto-remediation AC를 재검증한다.