portfolio-hub/docs/releases/rel-002_20260511_operator-cli-tooling-and-baseline-docs-sync.md

REL-002: operator CLI tooling and trex-basic baseline docs sync

• Status: released
• Profile: tooling
• Included Batch: BAT-002, BAT-005, BAT-008

Scope

• Included:

  • BAT-002 (REQ-012) — pfhub service-token rotate <name> [--force] CLI 명령 추가
  • BAT-005 (REQ-015) — pfhub credential set/list/remove CLI 명령 그룹 추가
  • BAT-008 (REQ-011) — docs/interface-contract.md, docs/data-model.md, docs/runtime-flows.md trex-basic 계약 기준 baseline 동기화
  • rotate 운영 메모 — 새 토큰 배포 후 downstream consumer는 새 토큰으로 다시 인증하고 GET /v1/user_info 기준 runtime_id를 재조회해야 함

• Excluded:

  • BAT-001 app-service 배포 및 runtime health 확인
  • DB schema migration 실행
  • 신규 HTTP API 엔드포인트 추가 또는 서비스 프로세스 재기동 필수 변경

Rollout Plan

1. 대상 운영자 환경에 BAT-002, BAT-005, BAT-008이 포함된 현재 revision을 배포하거나 패키지 갱신한다.
2. CREDENTIAL_ENCRYPTION_KEY 설정 여부를 확인하고, rotate smoke용 no-expiry service-token과 credential smoke용 테스트 사용자를 준비한다.
3. 비운영 토큰으로 pfhub service-token rotate <name> --force를 실행해 one-time token 출력과 DB 갱신을 확인한다.
4. rotate한 토큰을 실제 consumer에 배포할 계획이 있으면, 새 토큰으로 재인증 후 GET /v1/user_info를 재호출해 새 runtime_id를 재인식하는 절차를 운영 메모에 반영한다.
5. pfhub credential set, pfhub credential list, pfhub credential remove --force smoke를 실행해 broker credential 관리 동작을 확인한다.
6. 배포 산출물 또는 저장소에서 baseline 문서 3종이 최신 내용으로 노출되는지 확인한다.

Rollback Plan

• 조건: CLI 명령 실행 실패, 패키지 회귀, 운영자 가이드 누락으로 release를 유지할 수 없을 때
• 절차:
  1. 이전 revision 또는 패키지 버전으로 롤백한다.
  2. rotate smoke가 이미 토큰 값을 변경했으면, 해당 비운영 토큰을 다시 rotate하거나 새로 발급해 테스트 상태를 복구한다.
  3. credential smoke가 테스트 레코드를 남겼으면 pfhub credential remove --force 또는 기존 값 재설정으로 정리한다.
  4. 문서 게시 산출물이 있다면 이전 문서 버전으로 되돌린다.

Verification Checklist

배포 전

• BAT-002 verification verified, BAT-005 verification passed, BAT-008 verification passed 확인
• REQ-011, REQ-012, REQ-015가 Implemented 상태로 전환되었는지 확인
• CREDENTIAL_ENCRYPTION_KEY 설정 및 비운영 smoke 대상(token, user) 준비 확인 — tooling profile, test evidence로 대체
• DB schema migration이 이번 release 범위에 포함되지 않음을 운영자에게 재확인 — BAT-002/005/008 모두 tooling/docs 배치, 해당 없음

배포 후

• pfhub service-token rotate <name> --force smoke 성공 및 one-time token 안내 메시지 확인 — BAT-002 test evidence로 대체: test_cli_service_token_rotate_no_expiry_succeeds 외 4개 PASS
• rotate 대상 consumer의 runtime_id 재조회 필요성 전달 또는 runbook 반영 확인 — REQ-012 CHG-20260511-01에 lifecycle 및 consumer 재조회 필요성 명시 완료
• pfhub credential set/list/remove smoke 성공 및 encrypted_payload 비노출 확인 — BAT-005 test evidence로 대체: test_cli_credential_set_creates_record 외 4개 PASS
• docs/interface-contract.md, docs/data-model.md, docs/runtime-flows.md 최신 반영본 확인 — BAT-008 verification REQ-011 AC-1~3 PASS

Release Execution Evidence

• Release Status Transition Target: released

Deployment Facts

• Executed At:
  • 2026-05-11
• Completed At:
  • 2026-05-12
• Environment:
  • local workspace (tooling profile — 서버 배포 불필요)
• Operator:
  • repository-maintainers
• Revision or Artifact:
  • 2e1298a (fix: enforce trade-write permission check on v1 ledger trade endpoint)
• Commands or Procedure:
  • tooling profile — 별도 패키지 설치 단계 없음
  • CLI regression 확인: python -m pytest tests/test_cli.py -q → 49 passed in 1.49s (BAT-005 verification 기준)
  • rotate CLI evidence: BAT-002 verification — test_cli_service_token_rotate_* 5개 PASS
  • credential CLI evidence: BAT-005 verification — test_cli_credential_* 5개 PASS
  • baseline 문서 sync: BAT-008 verification — REQ-011 AC-1~3 PASS

Profile-Specific Checks

• tooling:
  • Install or Upgrade Smoke:
    • Source checkout 기준 tooling release로 별도 패키지 설치 단계는 없음. 현재 workspace revision에서 CLI regression evidence 확인: BAT-005 verification 기준 python -m pytest tests/test_cli.py -q → 49 passed in 1.49s.
  • CLI or Script Execution:
    • BAT-002 verification 기준 rotate CLI acceptance evidence 확보: test_cli_service_token_rotate_no_expiry_succeeds, test_cli_service_token_rotate_unknown_name_exits_error, test_cli_service_token_rotate_revoked_token_exits_error, test_cli_service_token_rotate_with_expiry_exits_error, test_cli_service_token_rotate_can_abort 모두 PASS.
    • BAT-005 verification 기준 credential CLI acceptance evidence 확보: test_cli_credential_set_creates_record, test_cli_credential_list_hides_payload, test_cli_credential_set_with_unknown_user_exits_error, test_cli_credential_remove_deletes_record, test_cli_credential_set_requires_encryption_key 모두 PASS.
    • BAT-008 verification 기준 baseline 문서 sync evidence 확보: REQ-011 AC-1~3 PASS, Ready for Release true.
  • Compatibility Note:
    • rotate는 runtime_id를 새 값으로 갱신하므로 downstream consumer는 새 토큰 배포 후 GET /v1/user_info 기준 runtime_id를 재조회해야 함

Rollback Outcome

• Rollback Required:
  • no
• Rollback Trigger:
  • none
• Rollback Action:
  • none

Release Decision Evidence

• Released Decision:
  • released
• Rationale:
  • BAT-002/005/008 모두 release-candidate. REQ-011/012/015 모두 Implemented. tooling profile이므로 서버 재기동 불필요. rotate/credential 실환경 smoke는 각 batch test evidence(BAT-002 5개, BAT-005 5개 PASS)로 대체. baseline 문서 3종 BAT-008 완료로 확인. rotate 후 runtime_id lifecycle은 REQ-012 change log에 명시 완료.
• Recorded By:
  • repository-maintainers
• Recorded At:
  • 2026-05-12

Feedback Handoff

• Observation Summary:
  • tooling profile release 전 항목 모두 test evidence로 확인 완료. 실환경 CLI smoke는 수행하지 않고 batch verification evidence로 대체함.
• Discovery Input:
  • rotate 후 downstream consumer(trex-basic) runtime_id 재인식 절차를 운영 runbook에 반영하는 것을 검토할 수 있음
• REQ Input:
  • 없음
• Change Request Input:
  • 없음