# Milestone: Command-First Operator Workflow

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/operator-surface/PHASE.md`

## 목표

Flutter 실화면을 보류한 상태에서 KIS live data, worker storage, market status, backtest 실행/결과 확인을 CLI/YAML/로그 중심의 반복 가능한 operator workflow로 묶는다. 화면에 올릴 기능이 충분히 표면화될 때까지 command-first 운영을 기본 경로로 유지하고, 나중에 UI MVP가 가져갈 contract와 evidence key를 축적한다.

## 상태

[완료]

## 구현 잠금

- 상태: 해제
- 결정 필요: 없음

## 범위

- KIS paper/real daily smoke와 provider readiness command handoff
- KIS live daily import를 worker storage까지 연결하는 command 또는 scenario 경계
- storage 기반 market data status 조회 command/YAML scenario
- imported daily bars를 사용한 backtest start/poll/result command workflow
- command output의 machine-readable status/evidence key 정리
- UI MVP로 넘길 operator workflow handoff 갱신

## 기능

### Epic: [cmd-operator] Command-first operator workflow

화면 없이도 운영자가 KIS 데이터 수집, 상태 조회, 백테스트 실행/결과 확인을 반복할 수 있는 command path를 만든다.

- [x] [kis-smoke-runbook] KIS paper/real daily smoke와 Go live-provider smoke 실행 경로가 command runbook으로 정리되어 있다. 검증: secret 원문 없이 readiness/smoke/evidence key가 문서화되고 smoke command가 dry failure와 live-gated success 경로를 구분한다.
- [x] [live-import-command] KIS live daily bars를 worker storage에 import하는 command 또는 YAML scenario가 있다. 검증: fake/provider test와 필요한 integration smoke가 import result와 storage upsert를 확인한다.
- [x] [market-status-scenario] imported market data를 CLI/YAML로 조회할 수 있다. 검증: `alt operator scenario validate/run` 또는 동등한 command가 instrument/bar count와 typed unavailable/error key를 출력한다.
- [x] [backtest-command-flow] imported daily bars를 입력으로 backtest start/poll/result를 command workflow에서 확인할 수 있다. 검증: start/poll/result scenario가 run id, terminal status, result summary key를 출력한다.
- [x] [operator-handoff] command-first workflow가 UI MVP로 넘길 화면 후보와 아직 화면으로 올리지 않을 항목을 분리한다. 검증: handoff 문서가 command, expected output key, 반복 운영 여부, UI defer 사유를 함께 기록하고, 충분히 표면화되지 않은 기능은 화면 후보에서 제외한다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-06-04
- 완료 근거: 모든 기능 Task가 PASS evidence와 함께 완료 처리되었고, `operator-handoff`는 `agent-task/archive/2026/06/m-command-first-operator-workflow/05+03,04_operator_handoff/complete.log`의 `Roadmap Completion`이 검증 명령 통과를 기록한다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 2026-06-04 사용자 요청으로 완료 승인 및 archive 이동을 수행한다.

## 범위 제외

- Flutter 실화면 구현
- wireframe 확정
- push notification
- paper trading 주문/포지션 모델
- 실거래 주문 API
- production 자동 수집 스케줄링
- secret 원문, 계좌번호, token의 tracked 문서 기록

## 작업 컨텍스트

- 관련 경로: `apps/cli/`, `apps/cli/testdata/operator/`, `bin/`, `services/api/`, `services/worker/`, `docs/`
- 표준선(선택): 현재 운영은 화면보다 CLI/YAML/log/test fixture를 우선한다. Flutter MVP는 command workflow에서 반복 운영 항목, 상태 key, 우선순위가 충분히 표면화되어 정리 가능한 뒤에 다시 연다.
- 표준선(선택): command output은 사람이 읽을 수 있으면서도 `jsonl`/status key처럼 script가 grep 가능한 형태를 유지한다.
- 표준선(선택): KIS secret은 SOPS + age command-lifetime env 주입 경계만 사용하고 tracked 문서에는 sanitized evidence만 남긴다.
- 최근 evidence: `docs/kis-live-secret-handoff.md`와 `docs/kis-live-secret-guide.md`에 paper/real readiness, 일봉 smoke, Go live-provider smoke 명령과 sanitized evidence key가 정리되어 있다.
- 최근 evidence: `bin/kis-paper-daily-smoke`는 `KIS_ACTIVE_ENV=paper|real`을 명시하지 않거나 필수 env가 없으면 외부 호출 전에 실패하고, SOPS 주입 live 경로에서는 `env`, `provider`, `endpoint`, `symbol`, `bar_count`, `msg_cd` 요약만 출력한다.
- 최근 evidence: `agent-task/archive/2026/06/m-command-first-operator-workflow/02+01_import_cli_scenario/complete.log`의 `Roadmap Completion`이 `live-import-command` PASS와 `go test ./apps/cli/... -count=1`, import scenario validate, `git diff --check` 검증을 기록한다.
- 최근 evidence: `agent-task/archive/2026/06/m-command-first-operator-workflow/03+02_market_status_scenario/complete.log`의 `Roadmap Completion`이 `market-status-scenario` PASS와 CLI 테스트, market status scenario validate, `git diff --check` 검증을 기록한다.
- 최근 evidence: `agent-task/archive/2026/06/m-command-first-operator-workflow/04+02_backtest_runtime_flow/complete.log`의 `Roadmap Completion`이 `backtest-command-flow` PASS와 API/worker/CLI 테스트, backtest polling/result scenario validate, `git diff --check` 검증을 기록한다.
- 최근 evidence: `agent-task/archive/2026/06/m-command-first-operator-workflow/05+03,04_operator_handoff/complete.log`의 `Roadmap Completion`이 `operator-handoff` PASS와 handoff focused suite, CLI package test, promised-key guard 확인, `git diff --check` 검증을 기록한다.
- 현재 작업 지점: 모든 기능 Task가 완료되었고 2026-06-04 사용자 승인으로 archive 대상이 되었다.
- 현재 작업 지점: active `agent-task/m-command-first-operator-workflow/` 작업 디렉터리는 비어 있고, 마지막 작업은 `agent-task/archive/2026/06/m-command-first-operator-workflow/05+03,04_operator_handoff/`에 보관되어 있다.
- 선행 작업: Operator Headless Workflow Validation, Operator Client API/Core Integration Validation, KIS Live Data Collection Pipeline
- 후속 작업: Paper Trading Readiness, Paper Trading Command Workflow, US Market Expansion, Live Trading Boundary, Flutter Operator Console MVP
- 확인 필요: 없음
