<!-- task=m-backtest-analysis-surface/01_contract_surface plan=1 tag=REVIEW_BAS-CONTRACT -->

# Plan - REVIEW_BAS-CONTRACT

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

이 계획은 이전 리뷰 `code_review_cloud_G07_0.log`의 Required 이슈만 처리한다. `CODE_REVIEW-cloud-G07.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채우는 것이 필수다. 구현 후 검증을 실행하고, active 파일은 그대로 둔 채 리뷰 준비를 보고한다. 사용자 결정, 외부 환경 준비, 범위 충돌이 없이는 안전하게 진행할 수 없으면 review stub의 `사용자 리뷰 요청` 섹션에 정확한 근거를 남기고 멈춘다. archive, `complete.log`, 최종 판정은 code-review 전용이다.

## 배경

첫 리뷰에서 protobuf schema, parser map, parser tests의 기능 형태는 계획과 맞는 것으로 확인됐다. 다만 필수 검증인 `bin/contracts-check`를 리뷰 환경에서 재실행하자 generated Go output drift가 감지되어 exit 1로 종료했다. drift는 generated Go 파일 header의 `protoc` 버전 주석이며, 현재 로컬 `bin/contracts-gen`은 `protoc v5.29.3` 결과를 만든다.

## 사용자 리뷰 요청 흐름

구현 중 차단 조건은 active `CODE_REVIEW-cloud-G07.md`의 `사용자 리뷰 요청` 섹션에 기록한다. code-review가 이를 검증하고 실제 `USER_REVIEW.md` 작성 여부를 결정한다.

## 분석 결과

### 읽은 파일

- `agent-task/m-backtest-analysis-surface/01_contract_surface/plan_cloud_G07_0.log`
- `agent-task/m-backtest-analysis-surface/01_contract_surface/code_review_cloud_G07_0.log`
- `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`
- `bin/contracts-gen`
- `bin/contracts-check`

### 실패 근거

리뷰 재실행:

```text
$ bin/contracts-check
contracts-check: Go generated output drift detected under /config/workspace/alt/packages/contracts/gen/go
...
-//  protoc        v3.21.12
+//  protoc        v5.29.3
contracts-check: run bin/contracts-gen and commit the regenerated output
```

### 범위 결정 근거

- 포함: 현재 toolchain으로 generated Go output drift를 반영하고, 검증 출력 신뢰를 회복한다.
- 제외: protobuf schema shape, parser map registration, parser tests, worker/API runtime behavior의 추가 설계 변경.
- generated files는 직접 편집하지 말고 `bin/contracts-gen`으로 갱신한다.

### 빌드 등급

- build lane: `cloud-G07`; review lane: `cloud-G07`.
- Rationale: 직전 리뷰에서 필수 검증 출력이 재실행 결과와 불일치했으므로 verification trust recovery가 필요하다. 기존 protocol/schema 작업과 같은 route를 유지한다.

## 구현 체크리스트

- [ ] [REVIEW_BAS-CONTRACT-1] 현재 toolchain으로 generated Go output drift를 반영하고 `bin/contracts-check` 재실행 출력을 갱신한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [REVIEW_BAS-CONTRACT-1] Regenerate with current toolchain and recover verification trust

문제: 이전 구현 기록은 `bin/contracts-check`가 `CC_EXIT=0`이라고 했지만, 리뷰 재실행에서는 `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`의 `protoc v3.21.12` header가 현재 generator 결과인 `protoc v5.29.3`와 달라 drift로 판정됐다.

해결 방법:

Before:

```go
//  protoc        v3.21.12
```

After:

```go
//  protoc        v5.29.3
```

수정 파일 및 체크리스트:

- [ ] `command -v protoc`, `protoc --version`, `command -v protoc-gen-go`, `protoc-gen-go --version` 출력으로 사용 toolchain을 기록한다.
- [ ] `bin/contracts-gen`을 실행해 generated output을 갱신한다.
- [ ] `packages/contracts/gen/go/alt/v1/backtest.pb.go`, `common.pb.go`, `market.pb.go`의 generated drift가 현재 generator 결과와 일치하는지 확인한다.
- [ ] `bin/contracts-check`를 재실행하고 exit 0 출력을 기록한다.
- [ ] 이전 계획의 focused 검증을 다시 실행해 contract/parser 변경이 여전히 통과하는지 확인한다.

테스트 작성: 새 테스트는 필요 없다. 기존 drift check와 focused parser tests가 이 follow-up의 검증이다.

중간 검증:

```bash
command -v protoc
protoc --version
command -v protoc-gen-go
protoc-gen-go --version
bin/contracts-gen
bin/contracts-check
```

Expected: toolchain path/version이 출력되고, `bin/contracts-check`가 exit 0으로 종료한다.

## 의존 관계 및 구현 순서

이 follow-up은 `01_contract_surface` 내부에서만 진행한다. 후속 split task인 `02+01_worker_analysis_store`, `03+01,02_api_client_boundary`는 이 task가 PASS된 뒤 진행한다.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `packages/contracts/gen/go/alt/v1/backtest.pb.go` | REVIEW_BAS-CONTRACT-1 |
| `packages/contracts/gen/go/alt/v1/common.pb.go` | REVIEW_BAS-CONTRACT-1 |
| `packages/contracts/gen/go/alt/v1/market.pb.go` | REVIEW_BAS-CONTRACT-1 |

## 최종 검증

```bash
bin/contracts-check
go test ./packages/contracts/gen/go/...
go test ./services/api/...
cd apps/client && flutter test test/contracts/alt_contracts_test.dart
git diff --check
```

Expected: all commands exit 0; generated output has no drift. Go test cache output is acceptable after `bin/contracts-check` passes.

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