# Milestone: Gito Branch Event Creation Sync Bridge

## 위치

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

## 목표

Gito가 제공하는 proto-socket `branch.updated` wakeup을 NomadCode core가 소비하고, `develop` target branch를 재검증/스캔한 뒤 Plane-origin creation sync job으로 enqueue한다. 이 Milestone이 끝나면 Forgejo/Gito branch event가 단순 UI wakeup에 머물지 않고 NomadCode backend sync loop의 결정적 입력으로 연결된다.

## 상태

[완료]

## 구현 잠금

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

## 범위

- Gito 제공 계약 `gito.forgejo-branch-events.v1`의 `event.subscribe` / `branch.updated` 소비
- NomadCode core runtime에서 Gito `/proto-socket` endpoint에 연결하는 client/runner
- `repo_id=nomadcode`, `branch=develop` 구독과 reconnect/error handling의 최소 기준
- `branch.updated` payload의 `changed_files`를 wakeup signal로만 사용하고 target branch revision을 별도 검증/스캔하는 흐름
- `agent-roadmap/phase/*/milestones/*.md` 변경과 provider identity를 확인해 `roadmapsync.ScanResult`와 `RoadmapCreationSyncJobArgs`를 구성하는 흐름
- 기존 `scheduler.EnqueueRoadmapCreationSync` seam으로 creation sync worker를 깨우는 흐름
- 중복 event, 동일 revision, not-ready scan의 idempotency 기준

## 기능

### Epic: [gito-wakeup] Gito branch event wakeup bridge

Gito가 provider webhook과 branch watch를 정규화해 `branch.updated`를 발행하면, NomadCode core가 이를 backend sync wakeup으로 받아 Plane creation sync orchestrator에 전달한다.

- [x] [contract-consume] Gito 제공 계약 `gito.forgejo-branch-events.v1`을 NomadCode core 소비 계약으로 반영한다. 검증: `event.subscribe` 요청과 `branch.updated` payload 필드가 계약 fixture 또는 테스트에 고정된다.
- [x] [core-client] NomadCode core에 Gito proto-socket event client/runner를 추가한다. 검증: fake proto-socket server 또는 transport로 `event.subscribe`를 보내고 `branch.updated`를 수신한다.
- [x] [branch-filter] `repo_id`, `branch`, `changed_files` 기준으로 roadmap Milestone 후보 event만 선별한다. 검증: 다른 repo/branch/path event는 creation sync enqueue를 만들지 않는다.
- [x] [revision-scan] 이벤트 payload를 최종 증거로 단정하지 않고 target branch revision을 fetch/scan해 `roadmapsync.ScanResult`를 만든다. 검증: scanned Milestone identity가 원래 Plane work item identity와 맞을 때만 ready 후보가 된다.
- [x] [creation-enqueue] scan 결과와 provider identity를 `RoadmapCreationSyncJobArgs`로 변환해 `scheduler.EnqueueRoadmapCreationSync`를 호출한다. 검증: fake scheduler가 정확한 job args를 받으며 duplicate/retry 입력이 중복 side effect를 만들지 않는다.
- [x] [runtime-wiring] server/scheduler lifecycle에 Gito event consumer를 선택적으로 wiring한다. 검증: Gito endpoint 미설정 시 기존 core 동작은 유지되고, 설정 시 runner가 시작/종료된다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-06-16
- 승인일: 2026-06-16
- 완료 근거:
  - `agent-task/archive/2026/06/m-gito-branch-event-creation-sync-bridge/01_event_client/complete.log`의 `Roadmap Completion` 근거로 `[contract-consume]`, `[core-client]`, `[branch-filter]`를 완료 처리했다.
  - `agent-task/archive/2026/06/m-gito-branch-event-creation-sync-bridge/02+01_creation_enqueue_bridge/complete.log`의 `Roadmap Completion` 근거로 `[revision-scan]`, `[creation-enqueue]`, `[runtime-wiring]`을 완료 처리했다.
  - 검증 근거는 `go test -count=1 ./internal/gitoevents ./internal/config ./internal/protosocket`, `cd services/core && go test -count=1 ./internal/gitosync ./internal/roadmapsync ./internal/roadmapsyncpipeline ./internal/scheduler`, `cd services/core && go test -count=1 ./...`, `cd services/core && go vet ./...`, `git diff --check` PASS다.
  - 2026-06-16 코드 레벨 종료 검토에서 repo/branch가 맞더라도 roadmap milestone 변경이 없는 `changed_files` event가 handler까지 전달되는 작은 누락을 확인했고, `gitoevents.Client`가 `MilestoneChangedFiles()` 기준으로 drop하도록 수정했다.
  - 2026-06-16 재검증 근거는 `cd services/core && go test -count=1 ./internal/gitoevents ./internal/config ./internal/protosocket`, `cd services/core && go test -count=1 ./internal/gitosync ./internal/roadmapsync ./internal/roadmapsyncpipeline ./internal/scheduler`, `cd services/core && go test -count=1 ./...`, `cd services/core && go vet ./...`, `git diff --check` PASS다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 코드 레벨 종료 검토에서 작은 branch-filter 누락을 바로 수정했고, 남은 실제 proto-socket wire/reconnect 운영 기준은 후속 `Gito Proto-Socket Consumer Wire Readiness` 범위로 넘긴다.

## 범위 제외

- Gito의 Forgejo webhook 수신/branch watch 제공 구현
- Gito provider delivery dedupe, branch watch persistence 구현
- Plane `Todo -> In Progress` 이후 실행 lifecycle
- Milestone Task와 Plane 하위 티켓 동기화
- Flutter UI에서 branch event를 표시하거나 수동 재시도 버튼을 제공하는 작업

## 작업 컨텍스트

- 관련 경로: `services/core/internal/protosocket/`, `services/core/internal/roadmapsync/`, `services/core/internal/roadmapsyncpipeline/`, `services/core/internal/scheduler/`, `services/core/cmd/server/main.go`, `packages/contracts/notes/flutter-core-api-candidates.md`
- 외부 계약: Gito `agent-contract/provided/gito-forgejo-branch-events-v1.md`
- 표준선(선택): Gito는 branch event producer이고, NomadCode core는 이 event를 wakeup signal로 소비한 뒤 target branch를 재검증/스캔해 Plane mutation 여부를 결정한다.
- 우선순위: NomadCode/Gito 연동 MVP의 semantic bridge 범위로, 실제 한 사이클 병목인 `Gito Proto-Socket Consumer Wire Readiness`와 함께 Plane Work Item Webhook Intake보다 먼저 닫는다.
- 선행 작업: `Milestone Work Item Creation Sync`의 `creation-sync-orchestrator`
- 후속 작업: `Milestone Execution Lifecycle Sync`
- 현황 동기화(2026-06-16): `agent-task/archive/2026/06/m-gito-branch-event-creation-sync-bridge/01_event_client/complete.log`의 `Roadmap Completion` 근거로 `[contract-consume]`, `[core-client]`, `[branch-filter]`를 완료 처리했다.
- 현황 동기화(2026-06-16): `agent-task/archive/2026/06/m-gito-branch-event-creation-sync-bridge/02+01_creation_enqueue_bridge/complete.log`의 `Roadmap Completion` 근거로 `[revision-scan]`, `[creation-enqueue]`, `[runtime-wiring]`을 완료 처리했다.
- 현황 동기화(2026-06-16): 코드 레벨 종료 검토에서 roadmap milestone path가 없는 `changed_files` event drop을 보강하고 검증을 재통과해 archive했다.
- 확인 필요: 없음
