<!-- task=m-command-first-operator-workflow/05+03,04_operator_handoff plan=0 tag=DOCS -->

# Plan - Operator Handoff

## 이 파일을 읽는 구현 에이전트에게

이 plan은 구현 지시서이며, 구현 완료 전 active `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 실제 내용과 검증 출력으로 채운다. 이 task는 `03+02_market_status_scenario`와 `04+02_backtest_runtime_flow` 완료 뒤 구현한다. 최종 판정, archive 이동, `complete.log` 작성은 code-review-skill 전용이다. 사용자-only blocker가 있으면 review stub의 `사용자 리뷰 요청`을 채우고 멈춘다.

## 배경

사용자는 화면 작업을 뒤로 미루고 기능이 표면화될 때까지 command-first 운영을 유지하려고 한다. 따라서 UI MVP로 넘길 후보는 command, expected output key, 반복 운영 여부, defer 사유가 충분히 정리된 뒤에만 올라가야 한다. 이 작업은 기존 headless validation handoff를 현재 마일스톤의 import/status/backtest 흐름 기준으로 갱신한다.

## 사용자 리뷰 요청 흐름

구현 중 사용자-only blocker는 active review stub의 `사용자 리뷰 요청` 섹션에 기록한다. code-review가 이를 검증하고 실제 `USER_REVIEW.md` 작성 여부를 결정한다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/operator-surface/milestones/command-first-operator-workflow.md`
- Task ids:
  - `operator-handoff`: command-first workflow가 UI MVP로 넘길 화면 후보와 아직 화면으로 올리지 않을 항목을 분리한다.
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-test/local/rules.md`
- `agent-test/local/operations-smoke.md`
- `agent-ops/rules/project/domain/operations/rules.md`
- `agent-roadmap/current.md`
- `agent-roadmap/phase/operator-surface/PHASE.md`
- `agent-roadmap/phase/operator-surface/milestones/command-first-operator-workflow.md`
- `apps/cli/testdata/operator/headless_validation.md`
- `apps/cli/internal/operator/handoff_test.go`
- `apps/cli/testdata/operator/expected/market_data_status_query.jsonl`
- `apps/cli/testdata/operator/expected/backtest_run_polling.jsonl`
- `apps/cli/testdata/operator/expected/backtest_result_summary.jsonl`
- `agent-task/archive/2026/06/m-command-first-operator-workflow/03+02_market_status_scenario/complete.log`
- `agent-task/archive/2026/06/m-command-first-operator-workflow/04+02_backtest_runtime_flow/complete.log`
- `bin/dev`
- `docs/kis-live-secret-handoff.md`
- `docs/kis-live-secret-guide.md`

### 테스트 환경 규칙

- test_env: `local`.
- Matched profile: `operations-smoke`.
- Applied commands: `go test ./apps/cli/...`, optional scenario validate commands if fixture paths are changed, and `git diff --check`.

### 테스트 커버리지 공백

- Current handoff tests require scenario names and JSONL validity, but do not verify UI candidate/defer reason fields.
- Handoff doc currently has a `Remaining Flutter wireframe dependency` column, but not explicit `repeatable operation` or `UI candidate/defer reason` separation for newly surfaced workflows.

### 심볼 참조

- Renamed/removed symbols: none.

### 분할 판단

- Shared task group: `agent-task/m-command-first-operator-workflow/`.
- This subtask directory is `05+03,04_operator_handoff`.
- Predecessor index `03`: `03+02_market_status_scenario`; complete log present.
- Predecessor index `04`: `04+02_backtest_runtime_flow`; complete log present.
- Implementation can proceed using the completed status/backtest scenario evidence.

### 범위 결정 근거

- Excludes Flutter UI, wireframes, navigation, charts, and widgets.
- Excludes changing command behavior; predecessors own behavior.
- Excludes roadmap archive movement; code-review/runtime own completion handling.

### 빌드 등급

- build=`local-G05`, review=`local-G05`: bounded docs/test update with explicit fixtures and no runtime code changes expected.

## 의존 관계 및 구현 순서

- Use the completed `03+02_market_status_scenario` and `04+02_backtest_runtime_flow` complete logs as predecessor evidence.
- Read only their completed review/complete evidence if further detail is needed through the active/archive complete.log dependency exception.
- Update handoff doc and tests.

## 구현 체크리스트

- [ ] [DOCS-1] Update handoff matrix with command, expected output key, repeatability, UI candidate, and UI defer reason for import/status/backtest workflows.
- [ ] [DOCS-2] Add tests that guard required scenarios and handoff columns/keys. 검증: handoff 문서가 command, expected output key, 반복 운영 여부, UI defer 사유를 함께 기록하고, 충분히 표면화되지 않은 기능은 화면 후보에서 제외한다.
- [ ] [DOCS-3] Run docs/CLI verification and `git diff --check`.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## [DOCS-1] Handoff Matrix

### 문제

[apps/cli/testdata/operator/headless_validation.md](/config/workspace/alt/apps/cli/testdata/operator/headless_validation.md:24) is the existing UI handoff matrix, but it only has a broad remaining wireframe dependency column. The current milestone needs explicit separation between UI candidates and items still deferred.

### 해결 방법

Keep the existing file instead of creating a new doc. Update the matrix columns to include:

- command,
- input fixture,
- expected output fixture,
- expected output keys,
- repeatable operation (`yes/no/manual-only`),
- UI candidate,
- UI defer reason.

Do not describe actual UI layout or build a screen.

### 수정 파일 및 체크리스트

- [ ] `apps/cli/testdata/operator/headless_validation.md`: update matrix and notes.
- [ ] `bin/dev`: update short hint only if scenario names changed in predecessors.

### 테스트 작성

No direct code test for prose, but DOCS-2 must assert required columns/key text to avoid silent drift.

### 중간 검증

```bash
rg --sort path -n 'UI defer reason|repeatable|expected output' apps/cli/testdata/operator/headless_validation.md
```

Expected: updated column/section text is present.

## [DOCS-2] Handoff Guard Tests

### 문제

[apps/cli/internal/operator/handoff_test.go](/config/workspace/alt/apps/cli/internal/operator/handoff_test.go:12) guards scenario names and JSONL shape, but not the new handoff decisions.

### 해결 방법

Extend tests to assert:

- required scenarios include import/status/backtest scenarios produced by predecessors,
- each required scenario row references input and expected output fixtures,
- matrix contains the new handoff columns,
- expected JSONL fixtures contain the keys promised by each row where feasible (`provider`, `instrument_count`, `bar_count`, `count`, `run_id`, `run_status`, `starting_cash`, `ending_equity`, `total_return`, `trade_count`).

### 수정 파일 및 체크리스트

- [ ] `apps/cli/internal/operator/handoff_test.go`: add column/key coverage.
- [ ] `apps/cli/testdata/operator/expected/*.jsonl`: no content changes unless predecessor fixtures require final alignment.

### 테스트 작성

Add `TestHandoffMatrixDocumentsCommandFirstColumns` and `TestExpectedFixturesContainPromisedKeys`.

### 중간 검증

```bash
go test ./apps/cli/internal/operator -run Handoff -count=1
```

Expected: handoff guard tests pass.

## [DOCS-3] Verification

### 문제

Docs-only changes can still break CLI fixture tests if paths or scenario names drift.

### 해결 방법

Run CLI package tests and diff check.

### 수정 파일 및 체크리스트

- [ ] No extra files.

### 테스트 작성

No additional tests.

### 중간 검증

```bash
git diff --check
```

Expected: no warnings.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `apps/cli/testdata/operator/headless_validation.md` | DOCS-1 |
| `bin/dev` | DOCS-1 |
| `apps/cli/internal/operator/handoff_test.go` | DOCS-2 |
| `apps/cli/testdata/operator/expected/*.jsonl` | DOCS-2 |

## 최종 검증

```bash
go test ./apps/cli/... -count=1
rg --sort path -n 'UI defer reason|repeatable|expected output' apps/cli/testdata/operator/headless_validation.md
git diff --check
```

Expected: all commands exit 0.

모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
