<!-- task=flutter_first_client_consolidation/02_contract_boundary plan=0 tag=API -->

# Flutter/Core Contract Boundary Plan

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

`CODE_REVIEW-cloud-G05.md`의 구현 에이전트 소유 섹션을 반드시 채우세요. 구현 후 검증 명령의 실제 stdout/stderr를 기록하고 active 파일을 그대로 둔 채 리뷰 준비 상태로 보고하세요. 종결 처리와 archive 이동은 code-review-skill 전용입니다.

## 배경

React web을 걷어내면 Flutter 앱이 core API의 주요 클라이언트가 된다. 현재 `packages/contracts/README.md`는 역할만 있고 `/api/tasks` 응답, create/enqueue shape, workspace metadata 후보가 문서화되어 있지 않다. 이 작업은 실제 schema 생성 전 계약 후보와 호환성 기준을 작게 고정한다.

## 분석 결과

### 읽은 파일

- `agent-ops/roadmap/current.md`
- `agent-ops/roadmap/milestones/flutter-first-client-consolidation.md`
- `packages/contracts/README.md`
- `services/core/internal/http/router.go`
- `services/core/internal/http/handlers.go`
- `services/core/internal/workflow/model.go`
- `services/core/internal/workflow/service.go`
- `services/core/internal/storage/store.go`
- `services/core/internal/db/models.go`
- `services/core/internal/db/tasks.sql.go`
- `apps/mobile/pubspec.yaml`
- `apps/mobile/lib/main.dart`
- `apps/mobile/test/widget_test.dart`

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

- 계약 후보 문서화: automated test 없음. deterministic search와 `bin/test`로 repo consistency만 확인한다.
- API behavior 변경 없음. core handler tests는 추가하지 않는다.

### 심볼 참조

- renamed/removed symbol 없음.
- 현재 route는 `services/core/internal/http/router.go:29-35`에 있다.
- task request type은 `services/core/internal/workflow/model.go:16-29`, task response shape는 `services/core/internal/db/models.go:12-27`에서 확인했다.

### 분할 판단

split decision policy를 먼저 평가했다. 이 task group은 세 subtask로 나뉜다.
- `01_react_retire`: React scaffold 처리.
- `02_contract_boundary`: contracts 후보 문서화. 독립 실행 가능.
- `03+02_app_workspace_surface`: Flutter surface 구현. 이 계약 후보가 끝난 뒤 시작한다.

### 범위 결정 근거

이 작업은 `packages/contracts` 안의 후보 문서와 README만 다룬다. OpenAPI/protobuf generator 도입, generated client, core handler 변경, Flutter HTTP client 구현은 제외한다.

### 빌드 등급

build lane: `cloud-G05`, review lane: `cloud-G05`. API 경계 문서이지만 코드 동작 변경은 없고, 후속 Flutter 구현의 기준이 되므로 cloud review가 필요하다.

## 구현 체크리스트

- [ ] `packages/contracts`에 Flutter/core 계약 후보 문서를 추가한다.
- [ ] `/healthz`, `/readyz`, `/api/tasks`, `/api/tasks/{id}`, `/api/tasks/{id}/enqueue`, `/api/integrations/plane/tasks`의 현재 shape와 안정성 수준을 기록한다.
- [ ] workspace/project metadata는 아직 core source-of-truth가 없음을 명시하고 후보 필드만 둔다.
- [ ] 중간 검증과 최종 검증을 실행한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [API-1] 계약 후보 문서 추가

문제: `packages/contracts/README.md:1-5`는 contracts의 역할만 설명하고, Flutter 앱이 소비할 API 후보를 찾을 수 없다. `services/core/internal/http/router.go:29-35`에는 task API가 이미 있지만 contracts에 반영되어 있지 않다.

해결 방법: `packages/contracts/notes/flutter-core-api-candidates.md`를 추가한다. 문서는 source-of-truth가 아니라 candidate임을 명확히 하고, 현재 HTTP route와 JSON fields를 표로 기록한다.

Before:

```markdown
1 # Contracts
2
3 Shared API contracts live here.
4
5 Use this package for OpenAPI specs, protobuf files, generated clients, fixtures, and compatibility notes that need to be consumed by more than one NomadCode runtime.
```

After:

```markdown
# Flutter/Core API Contract Candidates

이 문서는 source schema가 아니라 Flutter-first 전환 중 공유 계약 후보를 모으는 compatibility note다.
```

수정 파일 및 체크리스트:
- [ ] `packages/contracts/notes/flutter-core-api-candidates.md`

테스트 작성: skip. 문서-only 후보 정리이며 동작 변경이 없다.

중간 검증:

```bash
test -f packages/contracts/notes/flutter-core-api-candidates.md
rg --sort path -n "/api/tasks|CreateTaskInput|external_provider|workspace" packages/contracts/notes/flutter-core-api-candidates.md
```

예상 결과: 새 note가 존재하고 task/workspace 후보가 검색된다.

### [API-2] contracts README 갱신

문제: `packages/contracts/README.md:1-5`는 새 후보 note를 안내하지 않는다.

해결 방법: README에 `notes/flutter-core-api-candidates.md` 링크와 "실제 schema/generator 전 후보"라는 기준을 추가한다.

수정 파일 및 체크리스트:
- [ ] `packages/contracts/README.md`

테스트 작성: skip. 문서-only 변경이다.

중간 검증:

```bash
rg --sort path -n "flutter-core-api-candidates|candidate|Flutter" packages/contracts/README.md packages/contracts/notes/flutter-core-api-candidates.md
```

예상 결과: README가 후보 note를 가리킨다.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `packages/contracts/notes/flutter-core-api-candidates.md` | API-1 |
| `packages/contracts/README.md` | API-2 |

## 최종 검증

```bash
rg --sort path -n "/api/tasks|CreateTaskInput|external_provider|workspace|flutter-core-api-candidates" packages/contracts
bin/test
```

예상 결과: contracts 문서에 현재 task API와 Flutter 후보 경계가 검색되고, `bin/test`는 설치된 toolchain 기준으로 통과 또는 명시적 skip만 출력한다.

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