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,116 @@
+# REQ-122: operator broker truth HOTFIX baseline 및 remediation 문서 정합
+
+- Status: Approved
+- Type: Documentation
+- Priority: High
+- Owner: trex-core-dev
+
+## Intent
+- fetched credential source, balance failure semantics 및 managed/non-managed divergence의 의미가 runtime, interface, operations baseline에 없으면 운영자가 dry-run 결과를 잘못 해석하거나 승인 없는 live sync를 실행할 수 있다.
+- 구현된 계약을 기준으로 operator triage와 release gate를 문서화하되, production live sync 실행 자체는 이 REQ에 포함하지 않는다.
+
+## Requirement
+- 시스템 문서는 구현 완료 후 daemon/operator fetched credential source parity, sanitized broker-read failure semantics, token/broker lifecycle 운영 제약, reconciliation decision code 및 managed non-holding triage 절차를 실제 구현과 일치하게 기술해야 한다.
+- 운영 문서는 dry-run → broker/ledger/slot cross-check → 사장님 명시 approval → single-target `sync --live --yes` → re-reconcile 순서를 release gate로 명시하고, live sync 실행 명령이나 특정 production target을 승인·자동화하지 않아야 한다.
+- 문서의 예시, 로그 키 및 fixture 설명은 credential, token, app secret, raw account number 및 raw credential payload를 포함하지 않아야 한다.
+
+## Acceptance Criteria
+1. Given REQ-119~121 구현과 검증 evidence, When `docs/runtime-flows.md`를 갱신하면, Then daemon/operator broker-read 공통 provider, failure가 empty balance가 아님, reconciliation의 `unmanaged_position`/`managed_non_holding_divergence` 분기와 no-auto-remediation 경계가 구현과 일치한다.
+2. Given REQ-119~121 구현과 검증 evidence, When `docs/interface-contract.md`를 갱신하면, Then operator CLI의 broker-read failure exit semantics, safe observable fields 및 repository/reconciliation 계약 변화가 구현과 일치하고 외부 wire 계약의 변경 여부가 명시된다.
+3. Given 운영자 remediation 문서, When `docs/operations.md`를 갱신하면, Then dry-run evidence, source/account reference masking, failure hold, broker/ledger/slot cross-check 및 explicit release approval gate가 순서대로 제시되고 승인 없는 `sync --live` 실행을 지시하지 않는다.
+4. Given 문서 예시와 로그/JSON 샘플, When secret scan 또는 리뷰를 수행하면, Then token, authorization header, app key/app secret, raw credential payload 및 raw account number가 없다.
+5. Given 문서의 명령/decision code/reference, When implementation tests 및 CLI help와 대조하면, Then 존재하지 않는 명령·code·source mode를 사실처럼 기술하지 않고, unresolved lifecycle implementation choice는 검증된 정책으로 확정된 뒤에만 구체화한다.
+
+## Impacted Area
+- Docs: `docs/runtime-flows.md`, `docs/interface-contract.md`, `docs/operations.md`, `docs/project-structure.md`, `docs/srs/index.md`, REQ-119~121
+- Modules: none (documentation-only requirement; implementation facts are supplied by REQ-119~121)
+- Tests: markdown link/reference check; documented CLI/help and decision-code review; secret scan; implementation-evidence cross-check
+
+## Notes
+- Source Discovery: `docs/discovery/dcy-037_20260714_operator-broker-truth-and-managed-slot-divergence-hotfix.md` (FR-6, S-4; GitHub #39/#40/#41).
+- OQ-2 lifecycle mechanism is documented only after an evidence-backed implementation decision; this REQ does not mandate process-local reuse, shared cache, or another mechanism.
+- OQ-3 production live sync target is a release approval record, not a documentation authorization or execution task.
+
+## Change Log
+
+### CHG-20260714-01
+- Date: 2026-07-14
+- Author: delivery-runner
+
+#### Change Summary
+- dcy-037 #39/#40/#41 HOTFIX의 baseline/운영 정합 문서를 독립 Proposed REQ로 초안화했다.
+
+#### Intent
+- 안전한 broker truth triage를 구현 사실 및 release gate와 동기화한다.
+
+#### Acceptance Criteria Delta
+- Added:
+  - runtime/interface/operations alignment, approval-gated remediation, secret-safe examples 및 evidence-only lifecycle documentation.
+- Updated:
+  - 없음.
+- Removed:
+  - 없음.
+
+#### Impacted Area Delta
+- Docs:
+  - runtime, interface, operations, project structure 및 SRS traceability.
+- Modules:
+  - none.
+- Tests:
+  - markdown/reference, CLI/code evidence 및 secret scan review.
+
+#### Delivery Trace Delta
+- Batches:
+  - none (draft only; dcy-037 emergency scope의 향후 입력).
+- Releases:
+  - none (release gate 문서화만 포함; production live sync 실행 없음).
+
+#### Revalidation Impact
+- Reverification Needed: yes
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: REQ-119~121 구현 verification evidence가 준비된 뒤 baseline 문서를 갱신하고 cross-check한다.
+
+#### Validation Plan
+- implemented CLI/help, structured decision codes, test evidence 및 markdown 링크를 대조하고 secret scan을 통과시킨다.
+
+### CHG-20260714-02
+- Date: 2026-07-14
+- Author: Justin (TREX lead)
+
+#### Change Summary
+- Proposed에서 Approved로 승인했다.
+
+#### Intent
+- dcy-037의 runtime/interface/operations alignment와 release-gated remediation 경계를 implementation evidence 이후 갱신할 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; documentation은 live sync 실행을 승인하지 않는다.
+
+#### Revalidation Impact
+- Reverification Needed: yes
+- Existing Implementation Invalidated: no
+- Status Recommendation: keep-current
+- Follow-up Action: implementation/verification evidence가 준비된 뒤 baseline과 runbook을 갱신한다.
+
+#### Validation Plan
+- batch verification과 독립 QC에서 actual CLI/help, decision code, tests, markdown links 및 secret scan으로 AC를 재검증한다.