nomadcode/agent-roadmap/archive/phase/agent-ops-mcp-control-plane/milestones/gito-branch-event-creation-sync-bridge.md

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에 전달한다.

• [contract-consume] Gito 제공 계약 gito.forgejo-branch-events.v1을 NomadCode core 소비 계약으로 반영한다. 검증: event.subscribe 요청과 branch.updated payload 필드가 계약 fixture 또는 테스트에 고정된다.
• [core-client] NomadCode core에 Gito proto-socket event client/runner를 추가한다. 검증: fake proto-socket server 또는 transport로 event.subscribe를 보내고 branch.updated를 수신한다.
• [branch-filter] repo_id, branch, changed_files 기준으로 roadmap Milestone 후보 event만 선별한다. 검증: 다른 repo/branch/path event는 creation sync enqueue를 만들지 않는다.
• [revision-scan] 이벤트 payload를 최종 증거로 단정하지 않고 target branch revision을 fetch/scan해 roadmapsync.ScanResult를 만든다. 검증: scanned Milestone identity가 원래 Plane work item identity와 맞을 때만 ready 후보가 된다.
• [creation-enqueue] scan 결과와 provider identity를 RoadmapCreationSyncJobArgs로 변환해 scheduler.EnqueueRoadmapCreationSync를 호출한다. 검증: fake scheduler가 정확한 job args를 받으며 duplicate/retry 입력이 중복 side effect를 만들지 않는다.
• [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다.
• 리뷰 필요:
  • 사용자가 완료 결과를 확인했다
  • 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했다.
• 확인 필요: 없음