# 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를 재검증한다.