<!-- task=m-operator-headless-workflow-validation/04+02,03_evidence_handoff plan=0 tag=OPS -->

# Plan - OPS Evidence Handoff

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

`CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채우는 것이 필수다. 구현 후 검증을 실행하고 실제 stdout/stderr를 붙여 넣은 뒤 active 파일을 그대로 두고 리뷰 준비를 보고한다. 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 충돌로 막히면 review stub의 `사용자 리뷰 요청` 섹션에 근거를 채우고 멈춘다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백은 사용자 리뷰 요청이 아니다.

## 배경

마일스톤의 마지막 task는 Flutter 화면 MVP로 넘길 검증 evidence와 남은 wireframe 의존성을 정리하는 것이다. `agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md:69`의 handoff table은 scenario별 command/input/output/exit code/protobuf field evidence를 요구한다. 이 작업은 구현된 CLI fixtures와 expected output을 정리해 후속 Flutter Operator Console MVP가 화면 구현 전에 검증할 수 있는 산출물을 남긴다.

## 사용자 리뷰 요청 흐름

구현 중 blocker는 active review stub의 `사용자 리뷰 요청` 섹션에 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md` 형식으로 기록한다. code-review가 해당 요청을 검증하고 실제 `USER_REVIEW.md` 작성 여부를 결정한다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md`
- Task ids:
  - `handoff`: Flutter 화면 MVP로 넘길 수 있는 검증 evidence와 남은 wireframe 의존성을 정리한다.
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-ops/rules/project/rules.md`
- `agent-ops/rules/project/domain/operations/rules.md`
- `agent-ops/rules/project/domain/api/rules.md`
- `agent-ops/rules/project/domain/worker/rules.md`
- `agent-ops/rules/project/domain/contracts/rules.md`
- `agent-ops/skills/common/plan/SKILL.md`
- `agent-roadmap/current.md`
- `agent-roadmap/phase/operator-surface/PHASE.md`
- `agent-roadmap/phase/operator-surface/milestones/operator-headless-workflow-validation.md`
- `agent-test/local/rules.md`
- `agent-test/local/operations-smoke.md`
- `agent-test/local/api-smoke.md`
- `agent-test/local/worker-smoke.md`
- `agent-test/local/contracts-smoke.md`
- `bin/dev`
- `bin/test`
- `bin/build`
- `apps/cli/go.mod`
- `apps/cli/cmd/alt/main.go`
- `packages/contracts/proto/alt/v1/common.proto`
- `packages/contracts/proto/alt/v1/market.proto`
- `packages/contracts/proto/alt/v1/backtest.proto`
- `services/api/internal/socket/handlers.go`
- `services/api/internal/socket/market.go`
- `services/api/internal/socket/backtest.go`
- `services/worker/internal/socket/market.go`
- `services/worker/internal/socket/backtest.go`

### 테스트 환경 규칙

- `test_env=local`.
- `agent-test/local/rules.md`는 존재하고 전문을 읽었다. 현재 shell 직접 테스트 금지, 원격 ALT checkout root에서 실행한다.
- 적용 profile: `agent-test/local/operations-smoke.md` because `apps/cli/testdata/**` and `bin/dev` are operations surface.
- focused fixture command는 `bin/test`의 CLI module subset fallback이다.

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

- Handoff artifact completeness has no existing test. Add a test or deterministic check that each scenario listed in milestone lines 73-80 has fixture, expected output, and command record.
- `bin/dev` currently lists only generic CLI command at `bin/dev:17`; it does not show scenario validate/run entrypoints.

### 심볼 참조

- renamed/removed symbol: none.

### 분할 판단

- split decision policy를 plan 파일 선택 전에 평가했다.
- shared task group: `agent-task/m-operator-headless-workflow-validation/`.
- 이 plan의 directory `04+02,03_evidence_handoff`는 predecessor indices `02`, `03`을 요구한다.
- predecessor `02`: active `agent-task/m-operator-headless-workflow-validation/02+01_api_market/complete.log` 없음, archive complete.log 없음.
- predecessor `03`: active `agent-task/m-operator-headless-workflow-validation/03+02_backtest_workflows/complete.log` 없음, archive complete.log 없음.
- runtime은 `02+01_api_market`와 `03+02_backtest_workflows` PASS 후 이 plan을 구현해야 한다.

### 범위 결정 근거

- Roadmap/milestone 문서는 이 plan에서 직접 수정하지 않는다. PASS 완료 이벤트 후 roadmap 업데이트는 runtime 책임이다.
- tracked `docs/`는 사람용 최신 가이드만 두는 규칙이 있으므로 handoff 산출물은 CLI fixture 영역인 `apps/cli/testdata/operator/` 아래에 둔다.
- Flutter 화면 wireframe 자체는 제외하고, 남은 wireframe 의존성만 handoff에 기록한다.

### 빌드 등급

- build lane: `cloud-G07`, review lane: `cloud-G07`.
- 이유: terminal smoke evidence, expected output, exit-status contract를 후속 UI 구현 gate로 넘기는 작업이다.

## 구현 체크리스트

- [ ] `02+01_api_market`와 `03+02_backtest_workflows`의 `complete.log`가 active 또는 archive에 있는지 확인하고, 없으면 구현을 시작하지 않고 review stub에 blocker를 기록한다.
- [ ] `apps/cli/testdata/operator/` 아래에 scenario별 command/input/expected output/exit code/protobuf field handoff artifact를 추가한다.
- [ ] `bin/dev`에 headless scenario validate/run entrypoint를 추가하되 secret, remote path, personal endpoint를 쓰지 않는다.
- [ ] Handoff artifact completeness를 검증하는 focused test 또는 deterministic shell check를 추가한다.
- [ ] 원격 ALT checkout root에서 focused CLI test와 operations smoke 검증을 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

## 의존 관계 및 구현 순서

- 이 directory 이름의 runtime dependencies는 `04+02,03_evidence_handoff`이다.
- 구현 시작 전 `agent-task/m-operator-headless-workflow-validation/02+01_api_market/complete.log`와 `agent-task/m-operator-headless-workflow-validation/03+02_backtest_workflows/complete.log`, 또는 대응 archive complete.log가 있어야 한다.
- 추가 hidden dependency를 만들지 않는다.

### [OPS-1] Fixture Evidence Matrix

#### 문제

Milestone handoff 기준은 `api_connection_smoke`, `market_data_status_query`, `backtest_run_request`, `backtest_run_polling`, `backtest_result_summary`, `invalid_request_matrix` 각각의 command/input/output/exit code/protobuf field evidence를 요구한다. Prior subtasks add fixtures, but no single artifact proves matrix completeness.

#### 해결 방법

- `apps/cli/testdata/operator/headless_validation.md`를 추가한다.
- 각 scenario마다:
  - command
  - input fixture path
  - expected output fixture path
  - expected exit code
  - checked protobuf/view-model field
  - remaining Flutter wireframe dependency
  를 기록한다.
- `apps/cli/testdata/operator/expected/*.jsonl` expected output fixtures를 추가한다.

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

- [ ] `apps/cli/testdata/operator/headless_validation.md`: scenario evidence matrix 추가.
- [ ] `apps/cli/testdata/operator/expected/api_connection_smoke.jsonl`: expected output 추가.
- [ ] `apps/cli/testdata/operator/expected/market_data_status_query.jsonl`: expected output 추가.
- [ ] `apps/cli/testdata/operator/expected/backtest_run_request.jsonl`: expected output 추가.
- [ ] `apps/cli/testdata/operator/expected/backtest_run_polling.jsonl`: expected output 추가.
- [ ] `apps/cli/testdata/operator/expected/backtest_result_summary.jsonl`: expected output 추가.
- [ ] `apps/cli/testdata/operator/expected/invalid_request_matrix.jsonl`: expected output 추가.
- [ ] `apps/cli/internal/operator/handoff_test.go`: matrix references all required scenario fixture and expected output paths.

#### 테스트 작성

- 작성: `apps/cli/internal/operator/handoff_test.go`
  - `TestHeadlessValidationHandoffCoversRequiredScenarios`: six required scenarios present.
  - `TestExpectedOutputFixturesAreValidJSONLines`: expected output fixtures parse as JSON lines and include scenario/status/action fields.

#### 중간 검증

원격 ALT checkout root 기준:

```bash
(cd apps/cli && go test -count=1 ./internal/operator -run 'TestHeadlessValidationHandoff|TestExpectedOutputFixtures')
```

기대 결과: exit code 0.

### [OPS-2] Developer Entrypoint Notes

#### 문제

`bin/dev:17` currently only shows `cd apps/cli && go run ./cmd/alt`. It does not reveal scenario validate/run commands, so the headless gate remains hard to rediscover.

Before:

```bash
# bin/dev:17
  CLI:
    cd apps/cli && go run ./cmd/alt
```

#### 해결 방법

- `bin/dev` CLI block에 scenario validate/run examples를 추가한다.
- Examples use localhost defaults and fixture paths only; no remote checkout path, secret, account, provider credential, or personal endpoint.

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

- [ ] `bin/dev`: CLI section에 `operator scenario validate`와 `operator scenario run` examples 추가.
- [ ] `apps/cli/internal/cli/cli_test.go` 또는 `apps/cli/internal/operator/handoff_test.go`: documented fixture path가 존재하는지 확인.

#### 테스트 작성

- 작성 또는 확장: `apps/cli/internal/operator/handoff_test.go`
  - `TestHandoffDocumentedScenarioFixturesExist`.
- 별도 shell test는 만들지 않는다. `bin/dev`는 static output script이고 operations smoke `bin/test`가 workspace baseline이다.

#### 중간 검증

원격 ALT checkout root 기준:

```bash
bin/dev
(cd apps/cli && go test -count=1 ./...)
```

기대 결과: `bin/dev` exit code 0 and output includes `operator scenario validate`. CLI tests exit code 0.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `apps/cli/testdata/operator/headless_validation.md` | OPS-1 |
| `apps/cli/testdata/operator/expected/api_connection_smoke.jsonl` | OPS-1 |
| `apps/cli/testdata/operator/expected/market_data_status_query.jsonl` | OPS-1 |
| `apps/cli/testdata/operator/expected/backtest_run_request.jsonl` | OPS-1 |
| `apps/cli/testdata/operator/expected/backtest_run_polling.jsonl` | OPS-1 |
| `apps/cli/testdata/operator/expected/backtest_result_summary.jsonl` | OPS-1 |
| `apps/cli/testdata/operator/expected/invalid_request_matrix.jsonl` | OPS-1 |
| `apps/cli/internal/operator/handoff_test.go` | OPS-1, OPS-2 |
| `bin/dev` | OPS-2 |

## 최종 검증

원격 ALT checkout root 기준으로 실행한다. Handoff fixture checks should be fresh; use `-count=1`.

```bash
bin/dev
(cd apps/cli && go test -count=1 ./...)
bin/test
bin/build
```

기대 결과: 모든 명령 exit code 0. `bin/dev` output includes scenario validate/run examples. 원격 host나 checkout 접근 불가 시 pass가 아니라 차단 사유와 미실행 명령을 review stub에 남긴다.

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