<!-- task=m-paper-trading-command-workflow/01_loop_smoke plan=1 tag=REVIEW_PAPER_LOOP -->

# Plan - REVIEW_PAPER_LOOP

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

`CODE_REVIEW-cloud-G07.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채워야 구현이 끝난다. 구현 후 active 파일을 유지하고 리뷰 준비를 보고한다. 사용자 결정, 사용자 소유 외부 환경, 또는 범위 충돌로 막히면 `사용자 리뷰 요청`에 근거를 기록하고 멈춘다. 구현 중 사용자에게 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 증거 공백은 후속 에이전트가 명령 재실행으로 닫을 수 있으면 사용자 리뷰 요청이 아니다. 최종 archive, `complete.log`, roadmap 반영은 code-review 책임이다.

## 배경

첫 리뷰에서 `apps/cli` paper loop summary 구현과 focused unit test는 통과했다. 하지만 최종 검증으로 요구된 `bin/test`는 `bin/contracts-check` generated drift에서 실패했고, 그 drift가 active worktree에 남아 있어 검증 신뢰성이 닫히지 않았다. 이 후속은 앱 로직을 넓히지 않고 generated output 상태와 전체 검증 증거만 회복한다.

## 사용자 리뷰 요청 흐름

구현 중 사용자 전용 결정이나 외부 환경 준비가 필요하면 active review stub의 `사용자 리뷰 요청` 섹션을 채우고 중단한다. 직접 사용자 프롬프트는 금지이며, code-review가 `USER_REVIEW.md` 작성 여부를 판단한다. header-only drift가 아닌 의미 있는 contract 변경이 발견되면 사용자 소유 변경 가능성이 있으므로 그 증거를 `사용자 리뷰 요청`에 기록한다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/trading-expansion/milestones/paper-trading-command-workflow.md`
- Task ids:
  - `paper-loop-smoke`: paper execution loop smoke
- 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-ops/rules/private/testing-env.md`
- `agent-task/m-paper-trading-command-workflow/01_loop_smoke/plan_cloud_G07_0.log`
- `agent-task/m-paper-trading-command-workflow/01_loop_smoke/code_review_cloud_G07_0.log`
- `apps/cli/internal/operator/output.go`
- `apps/cli/internal/operator/runner.go`
- `apps/cli/internal/operator/runner_paper_test.go`
- `apps/cli/internal/operator/client_test.go`
- `apps/cli/internal/operator/scenario_test.go`
- `apps/cli/internal/operator/handoff_test.go`
- `apps/cli/testdata/operator/paper_trading_state.yaml`
- `apps/cli/testdata/operator/expected/paper_trading_state.jsonl`
- `apps/cli/testdata/operator/headless_validation.md`
- `packages/contracts/gen/go/alt/v1/backtest.pb.go`
- `packages/contracts/gen/go/alt/v1/common.pb.go`
- `packages/contracts/gen/go/alt/v1/market.pb.go`
- `packages/contracts/gen/go/alt/v1/paper_trading.pb.go`
- `bin/test`
- `bin/contracts-check`
- `bin/contracts-gen`

### 테스트 환경 규칙

`test_env=local`. `agent-test/local/rules.md`와 `agent-test/local/operations-smoke.md`를 읽었다. `apps/cli`는 operations 도메인이고 focused check는 `go test -count=1 ./apps/cli/internal/operator`, 전체 smoke는 `bin/test`다. `bin/contracts-check`는 `bin/contracts-gen`을 실행한 뒤 generated output drift를 비교하므로 실행 전후 `git diff` 확인이 필요하다.

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

- paper loop summary text output과 expected JSONL key 존재는 `runner_paper_test.go`와 fixture로 커버된다.
- 공백: `bin/test` 전체 통과 증거가 없다. 현재 `packages/contracts/gen/go/alt/v1/*.pb.go`의 `protoc` 헤더 drift가 계획 범위 밖 변경으로 남아 있어 contract/generated drift 검증이 신뢰 불가 상태다.

### 심볼 참조

rename/remove 없음. `StepEvent`, `WriteStep`, `evaluatePaper` call site를 확인했고 새 필드는 paper `AccountID` 출력 블록 안에서만 렌더링된다.

### 분할 판단

기존 split subtask `01_loop_smoke` 안의 후속 검증 1건이다. 새 subtask로 분리하지 않고 같은 active task directory에서 plan 1로 이어간다.

### 범위 결정 근거

허용 범위는 generated contract drift 확인/정리와 검증 재실행뿐이다. `.proto` schema, worker/API behavior, Flutter UI, roadmap 문서는 수정하지 않는다. `apps/cli` 로직은 검증 재실행 중 실패가 재현될 때만 해당 실패를 최소 수정한다.

### 빌드 등급

`cloud-G07`: unit test 통과 뒤 real `bin/test`/generated-output drift가 남은 terminal verification trust 회복 작업이다.

## 구현 체크리스트

- [ ] [REVIEW_PAPER_LOOP-1] generated contract drift가 header-only인지 확인하고 정리한 뒤 focused CLI test와 `bin/test` 전체 통과 증거를 남긴다. 검증: `git diff --name-only -- packages/contracts/gen/go/alt/v1/backtest.pb.go packages/contracts/gen/go/alt/v1/common.pb.go packages/contracts/gen/go/alt/v1/market.pb.go packages/contracts/gen/go/alt/v1/paper_trading.pb.go`에서 해당 파일들이 나오지 않고 `bin/test`가 exit 0이어야 한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### REVIEW_PAPER_LOOP-1

#### 문제

`code_review_cloud_G07_0.log:113`는 `bin/test`가 `bin/contracts-check`에서 멈췄다고 기록한다. 실제 worktree도 `packages/contracts/gen/go/alt/v1/backtest.pb.go:4`, `packages/contracts/gen/go/alt/v1/common.pb.go:4`, `packages/contracts/gen/go/alt/v1/market.pb.go:4`, `packages/contracts/gen/go/alt/v1/paper_trading.pb.go:4`에 계획 범위 밖 `protoc v3.21.12` header drift가 남아 있다.

#### 해결 방법

먼저 아래 diff가 네 파일의 `protoc` header-only 변경인지 확인한다.

```bash
git diff -- packages/contracts/gen/go/alt/v1/backtest.pb.go packages/contracts/gen/go/alt/v1/common.pb.go packages/contracts/gen/go/alt/v1/market.pb.go packages/contracts/gen/go/alt/v1/paper_trading.pb.go
```

header-only drift가 맞으면 현재 checkout의 generator로 정리한다.

```bash
bin/contracts-gen
```

그 다음 generated contract 파일이 더 이상 diff에 나오지 않는지 확인한다. 만약 diff가 header-only가 아니거나 `.proto` 의미 변경으로 보이면 임의로 정리하지 말고 `사용자 리뷰 요청`에 차단 근거를 기록한다.

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

- [ ] `packages/contracts/gen/go/alt/v1/backtest.pb.go` header drift 정리
- [ ] `packages/contracts/gen/go/alt/v1/common.pb.go` header drift 정리
- [ ] `packages/contracts/gen/go/alt/v1/market.pb.go` header drift 정리
- [ ] `packages/contracts/gen/go/alt/v1/paper_trading.pb.go` header drift 정리
- [ ] `CODE_REVIEW-cloud-G07.md`에 `git diff`, `go test -count=1 ./apps/cli/internal/operator`, `bin/test`의 실제 stdout/stderr 기록

#### 테스트 작성

새 테스트는 작성하지 않는다. 이 후속은 검증 신뢰 회복이며 기존 focused CLI test와 `bin/test`가 충분한 회귀 경계다.

#### 중간 검증

```bash
git diff --name-only -- packages/contracts/gen/go/alt/v1/backtest.pb.go packages/contracts/gen/go/alt/v1/common.pb.go packages/contracts/gen/go/alt/v1/market.pb.go packages/contracts/gen/go/alt/v1/paper_trading.pb.go
go test -count=1 ./apps/cli/internal/operator
```

## 수정 파일 요약

| 파일 | 항목 |
|---|---|
| `packages/contracts/gen/go/alt/v1/backtest.pb.go` | REVIEW_PAPER_LOOP-1 |
| `packages/contracts/gen/go/alt/v1/common.pb.go` | REVIEW_PAPER_LOOP-1 |
| `packages/contracts/gen/go/alt/v1/market.pb.go` | REVIEW_PAPER_LOOP-1 |
| `packages/contracts/gen/go/alt/v1/paper_trading.pb.go` | REVIEW_PAPER_LOOP-1 |
| `agent-task/m-paper-trading-command-workflow/01_loop_smoke/CODE_REVIEW-cloud-G07.md` | REVIEW_PAPER_LOOP-1 |

## 최종 검증

```bash
git diff --name-only -- packages/contracts/gen/go/alt/v1/backtest.pb.go packages/contracts/gen/go/alt/v1/common.pb.go packages/contracts/gen/go/alt/v1/market.pb.go packages/contracts/gen/go/alt/v1/paper_trading.pb.go
go test -count=1 ./apps/cli/internal/operator
bin/test
```

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