# Milestone: Gito Proto-Socket Consumer Wire Readiness

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/agent-ops-mcp-control-plane/PHASE.md`

## 목표

NomadCode core의 Gito branch event consumer를 실제 Gito `/proto-socket` wire protocol과 맞춘다. Gito event schema를 NomadCode 전용으로 좁히지 않고, consumer-neutral `branch.updated` base payload를 받아 NomadCode 내부 wakeup과 creation sync enqueue로 매핑하는 MVP 운영 연결 기준을 닫는다.

## 상태

[계획]

## 승격 조건

- 없음

## 구현 잠금

- 상태: 해제
- 결정 필요: 없음

## 범위

- Gito `/proto-socket` binary protobuf transport를 소비하는 NomadCode production transport
- `event.subscribe` request와 `branch.updated` event envelope의 struct payload 변환
- Gito base schema는 다중 consumer용 범용 규약으로 소비하고, NomadCode 전용 힌트가 필요하면 optional metadata/custom field만 사용
- 기존 `gitoevents` decode/filter, `gitosync` scan/enqueue 의미 로직과 wire transport의 결합
- Gito dev server 또는 fixture와 연결하는 cross-project integration smoke
- Gito consumer runtime env와 local/deploy 설정 문서화

## 기능

### Epic: [wire-consumer] Gito wire-compatible consumer

NomadCode가 Gito branch event를 논리 DTO가 아니라 실제 proto-socket wire frame으로 소비하되, Gito의 base event schema를 NomadCode 내부 모델로 오염시키지 않는다.

- [ ] [transport-adapter] JSON text websocket transport를 실제 proto-socket binary/protobuf transport 또는 동등 adapter로 교체한다. 검증: 실제 proto-socket test server가 `event.subscribe`를 받고 `branch.updated`를 binary frame으로 돌려주는 테스트가 통과한다.
- [ ] [schema-boundary] Gito `branch.updated` base payload를 repo/branch/revision/change hint 중심으로 해석하고 NomadCode 전용 값은 optional metadata/custom field가 있을 때만 소비한다. 검증: NomadCode 전용 필드 없이도 branch scan/enqueue wakeup이 동작한다.
- [ ] [envelope-decode] binary frame에서 받은 `structpb.Struct` envelope을 기존 `gitoevents.DecodeBranchUpdatedEnvelope` 입력으로 안전하게 변환한다. 검증: malformed frame, 다른 channel/action, payload 누락, 알 수 없는 metadata/custom field가 side effect 없이 drop 또는 ignore된다.
- [ ] [bridge-e2e] wire-compatible consumer, branch scan, `EnqueueRoadmapCreationSync`까지 이어지는 integration test 또는 dev smoke를 추가한다. 검증: Gito `branch.updated` 한 건이 target branch 재검증 후 정확히 하나의 creation sync job으로 수렴한다.
- [ ] [config-docs] `GITO_PROTO_SOCKET_URL`, `GITO_REPO_ID`, `GITO_DEVELOP_REPO_PATH`, `GITO_BRANCH`, `GITO_REMOTE_NAME`, `ROADMAP_CREATION_TODO_STATE_ID` 또는 `PLANE_TODO_STATE_ID` 설정을 README, compose, env sample 중 적절한 위치에 문서화한다. 검증: secret 없이 local/dev consumer를 켤 수 있는 설정 경로가 남는다.
- [ ] [failure-ops] reconnect, not-ready revision, duplicate event, malformed frame 처리와 로그 기준을 정리한다. 검증: 장애 입력이 core server shutdown이나 중복 Plane mutation으로 이어지지 않는다.

## 완료 리뷰

- 상태: 없음
- 요청일: 없음
- 완료 근거: 없음
- 리뷰 필요:
  - [ ] 사용자가 완료 결과를 확인했다
  - [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음

## 범위 제외

- Gito의 Forgejo webhook producer 구현
- Gito base event schema를 NomadCode 전용 필드로 확장하는 작업
- Gito provider event dedupe와 listener persistence 고도화
- Plane `Todo -> In Progress` 실행 lifecycle
- Milestone Task와 Plane 하위 티켓 동기화
- Flutter UI에서 branch event 상태를 표시하는 기능

## 작업 컨텍스트

- 관련 경로: `services/core/internal/gitoevents/`, `services/core/internal/gitosync/`, `services/core/cmd/server/main.go`, `services/core/internal/config/`, `services/core/docker-compose.yml`, `README.md`, `packages/contracts/notes/flutter-core-api-candidates.md`
- 외부 계약: Gito `agent-contract/provided/gito-forgejo-branch-events-v1.md`
- 관련 Gito Milestone: `Branch Event Proto-Socket Interop Readiness`
- 표준선(선택): NomadCode는 Gito event payload를 wakeup signal로만 사용하고, 최종 판단은 target branch fetch/scan과 provider identity 재검증으로 수행한다. Gito schema는 여러 consumer를 위한 범용 규약으로 보고, NomadCode 전용 정보는 optional metadata/custom field가 있을 때만 소비한다.
- 선행 작업: Gito Branch Event Creation Sync Bridge의 semantic consumer/scan/enqueue 경계
- 후속 작업: Milestone Execution Lifecycle Sync
- 확인 필요: 없음