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

- Status: confirmed
- 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) 준비 확인
- [ ] DB schema migration이 이번 release 범위에 포함되지 않음을 운영자에게 재확인

### 배포 후

- [ ] `pfhub service-token rotate <name> --force` smoke 성공 및 one-time token 안내 메시지 확인
- [ ] rotate 대상 consumer의 `runtime_id` 재조회 필요성 전달 또는 runbook 반영 확인
- [ ] `pfhub credential set/list/remove` smoke 성공 및 `encrypted_payload` 비노출 확인
- [ ] `docs/interface-contract.md`, `docs/data-model.md`, `docs/runtime-flows.md` 최신 반영본 확인

## Release Execution Evidence

- Release Status Transition Target: released

### Deployment Facts

- Executed At:
  - (미기록 — 배포 미수행)
- Completed At:
  - (미기록)
- Environment:
  - (미기록)
- Operator:
  - (미기록)
- Revision or Artifact:
  - (미기록 — 배포 후 기록)
- Commands or Procedure:
  - (미기록)

### 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:
  - (미기록)
- Rollback Trigger:
  - none
- Rollback Action:
  - none

### Release Decision Evidence

- Released Decision:
  - (미기록)
- Rationale:
  - (미기록)
- Recorded By:
  - (미기록)
- Recorded At:
  - (미기록)

## Feedback Handoff

- Observation Summary:
  - (배포 후 기록)
- Discovery Input:
  - (배포 후 기록)
- REQ Input:
  - (배포 후 기록)
- Change Request Input:
  - (배포 후 기록)