trex/trex-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
94e148940adb008db0bbd215052a1e984f7c566b
trex-core/docs/srs/Documentation/req-122_operator-broker-truth-hotfix-baseline-alignment.md
T

6.0 KiB
Raw Blame History

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를 재검증한다.
Reference in New Issue View Git Blame Copy Permalink