trex-core/docs/srs/Interface/req-106_verify-cli-command.md

req-106: trex-core verify 명령 — C 불일치 슬롯 재대조 + warning 해제

• Status: Implemented
• 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-20260630-01

• Date: 2026-06-30
• Author: 팀장(Claude) — change-req (라이브 릴리즈 핫픽스 + postmortem)

Change Summary

• REL-010 STEP2 배포 스모크서 trex-core verify ImportError 핫픽스. Status Implemented 유지(구현 결함 수정, AC 불변).

Intent / 증상·근본원인 (핫픽스 예외 경로)

• 증상: 운영 배포(ababf80) 후 trex-core verify --config ... --portfolio-id ... 실행 시 ImportError: cannot import name 'make_broker' from 'trex_core.adapters.broker'.
• 근본원인: runtime/cli.py _cmd_verify()가 코드베이스에 존재하지 않는 trex_core.adapters.broker.make_broker를 import(정의 0건, 참조는 verify 한 곳뿐). 형제 명령 _cmd_sync()는 올바르게 trex_core.runtime.daemon._build_broker를 사용. → verify 경로에만 잘못된 import가 박혀 있었음.
• 수정: _cmd_verify를 from trex_core.runtime.daemon import _build_broker / _build_broker(cfg)로 교체(sync와 동일, 검증된 경로). 커밋 51cc3cc.

Acceptance Criteria Delta

• Added/Updated/Removed: 없음 (기존 AC 동일 — 깨진 구현을 정정)

Delivery Trace Delta

• 핫픽스 커밋 51cc3cc(main 직접, fast-path). 회귀 테스트 2종 추가(tests/runtime/test_cli_operator.py): test_verify_cmd_broker_import_does_not_raise(paper config+DB stub로 verify 경로 import 통과 검증), test_verify_cmd_uses_build_broker_not_make_broker(make_broker 심볼 부재 구조검증).

Verification

• 전체 스위트 747 passed / 47 skipped / 0 failed(회귀 0). 운영 재검증(2026-06-30, 51cc3cc): verify OK(slot already cleared) · sync --dry-run OK(broker_qty_zero guard SKIP) · report OK.

Postmortem (테스트 갭)

• 왜 미검출: BAT-051 verification이 verify의 broker import 경로를 런타임 실행하지 않음(import가 함수 내부라 호출 시에만 트리거). 단위 테스트가 verify 명령을 끝까지 돌리지 않아 phantom import가 통과됨.
• 재발 방지: 위 회귀 테스트 2종으로 import 경로를 실제 실행/구조검증. 후속 권고 — operator CLI 명령들의 lazy import를 스모크 수준으로 한 번씩 실행하는 테스트 추가 검토.

Revalidation Impact

• Reverification Needed: no (회귀테스트+운영 재검증 완료) / Existing Implementation Invalidated: no
• Status Recommendation: implemented
• Rollback: git revert 51cc3cc (CLI 전용, trading/wire/daemon 무관 — 실행 중 데몬 무영향).
• ⚠️ 거버넌스 노트: 라이브 블로커 해소를 위해 main 직접 푸시(사전 결재 게이트 절차 생략) — 사장님 사후 추인.

CHG-20260626-01

• Date: 2026-06-26
• Author: trex-core-dev
• Status: Approved → Implemented
• Summary: BAT-051(PR #32, 07b393d) origin/main 머지 완료. QC(opus) PASS + 팀장 confirm-batch-verification. verify CLI(--portfolio-id/--json), C케이스 재대조+warning 해제, B케이스 거부+sync 안내, 전 AC 검증 완료.

Acceptance Criteria Delta

• 없음

Impacted Area Delta

• 없음

Delivery Trace Delta

• Batches: BAT-051 (core-B)
• Releases: M3 (배포 대기)

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: Implemented
• Follow-up Action: 없음.

Validation Plan

• BAT-051 verification.md AC 매핑 전항목 PASS 확인됨.

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.