# Milestone: Branch Event Proto-Socket Interop Readiness

## 위치

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

## 목표

Forgejo push webhook에서 정규화된 `branch.updated` event를 여러 외부 consumer가 실제 Gito `/proto-socket` wire protocol로 구독하고 수신할 수 있음을 증명한다. 논리 JSON envelope 예시와 실제 proto-socket binary/protobuf frame 경계를 계약에 분리해 기록하고, base schema는 consumer-neutral하게 유지하며 consumer별 확장은 `metadata` 같은 optional custom field로만 다루는 기준을 남긴다.

## 상태

[완료]

## 승격 조건

- 없음

## 구현 잠금

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

## 범위

- `gito.forgejo-branch-events.v1` 계약의 실제 `/proto-socket` wire format 명시
- `event.subscribe` request와 `branch.updated` broadcast의 channel/action/payload shape 고정
- NomadCode 전용 payload가 아닌 branch event 범용 base schema와 optional metadata/custom extension 경계
- proto-socket binary/protobuf client fixture로 Gito server producer 호환성 검증
- Forgejo webhook, branch listener, event fanout을 묶은 producer-side smoke 경로
- NomadCode를 초기 consumer smoke 대상으로 쓰되, 다른 consumer가 같은 schema를 재사용할 수 있는 운영 확인 절차

## 기능

### Epic: [branch-wire] Branch event wire interop

Gito가 제공하는 branch event producer 표면을 문서상 계약이 아니라 실제 proto-socket wire 호환 기준으로 고정하되, base event schema를 특정 consumer에 종속시키지 않는다.

- [x] [wire-contract] `gito.forgejo-branch-events.v1`에 `/proto-socket`이 binary protobuf frame을 사용하고 JSON은 논리 envelope 예시임을 명시한다. 검증: 계약 문서가 frame type, channel/action, payload 필드와 optional metadata/custom field 경계를 함께 설명한다.
- [x] [schema-neutrality] `branch.updated` base payload를 repo, branch, revision, changed files 같은 범용 Git event 정보로 유지하고 consumer-specific field는 optional metadata/custom 영역으로만 허용한다. 검증: 계약 fixture에 NomadCode 전용 필수 필드가 없다.
- [x] [producer-fixture] 실제 proto-socket Go client 또는 동등한 binary fixture로 `event.subscribe`를 보내고 `branch.updated`를 수신하는 producer-side 테스트를 추가한다. 검증: text JSON websocket client가 아니라 binary proto-socket 경로로 test가 통과한다.
- [x] [webhook-smoke] Forgejo push webhook, watched branch listener, event outbox/fanout을 이어 `branch.updated`가 발행되는 smoke 절차를 남긴다. 검증: test 또는 dev smoke에서 `before`, `after`, `changed_files`가 consumer payload로 도달한다.
- [x] [consumer-interop] NomadCode를 첫 smoke consumer로 사용하되 schema가 NomadCode 전용으로 좁아지지 않는 최소 interop 확인 절차를 기록한다. 검증: NomadCode dev consumer가 generic `branch.updated`를 받아 자기 내부 wakeup으로 매핑하고, base payload에는 NomadCode 전용 필수 필드가 없다.
- [x] [ops-docs] listener bootstrap, `/proto-socket`, `/api/listeners/branches`, `/api/events` 운영 확인 절차를 README 또는 contract note에 보강한다. 검증: 필요한 endpoint와 env가 secret 없이 재현 가능하게 적힌다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-06-15
- 완료 근거:
  - `services/core/internal/controlplane/binary_interop_test.go`가 branch watch 등록, binary proto-socket `event.subscribe`, Forgejo push callback, `branch.updated` 수신을 한 경로로 검증한다.
  - `agent-contract/provided/gito-forgejo-branch-events-v1.md`에 binary protobuf frame, consumer-neutral base payload, 운영 smoke 절차가 정리되어 있다.
  - `cd services/core && go test -run TestBinaryProtoSocketBranchUpdated ./internal/controlplane -count=1` 통과.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 2026-06-16 코드레벨 종료 검토에서 producer-side binary proto-socket interop, consumer-neutral payload, smoke 문서, core test가 확인되어 완료 승인 후 archive 이동한다.

## 범위 제외

- NomadCode core consumer transport 구현
- NomadCode 전용 event schema 또는 필수 payload field 추가
- Plane creation sync enqueue 구현
- Forgejo provider delivery dedupe의 고도화
- provider PR/MR ChangeRequest adapter
- Flutter control surface 표시 기능

## 작업 컨텍스트

- 관련 경로: `agent-contract/provided/gito-forgejo-branch-events-v1.md`, `services/core/internal/protosocket/`, `services/core/internal/controlplane/`, `services/core/internal/provider/forgejo/`, `services/core/internal/events/`
- 표준선(선택): Gito `/proto-socket`의 source of truth는 proto-socket binary/protobuf transport이며, JSON envelope는 계약 이해를 돕는 논리 표현으로만 둔다. Event base schema는 consumer-neutral하게 유지하고, 특정 consumer에만 필요한 값은 optional `metadata` 또는 custom extension에만 둔다.
- 선행 작업: Forgejo Branch Event MVP
- 우선순위: NomadCode 연동 MVP의 Gito-side 최우선 slice로, IOP Agent Run Bridge보다 먼저 닫는다.
- 후속 작업: NomadCode `Gito Proto-Socket Consumer Wire Readiness`, 이후 `Gito Branch Event Creation Sync Bridge`의 남은 semantic bridge 완료/검토
- 확인 필요: 없음
