nomadcode/agent-roadmap/archive/phase/agent-ops-mcp-control-plane/milestones/gito-protosocket-consumer-wire-readiness.md

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 운영 연결 기준을 닫는다.

상태

[완료]

승격 조건

• 없음

구현 잠금

• 상태: 해제
• SDD: 불필요 - 외부 이벤트 계약은 agent-contract/provided/gito-forgejo-branch-events-v1.md를 참조하고, 이 마일스톤은 기존 Gito base event consumer wire-readiness 구현/검증 slice로 닫는다.
• 결정 필요: 없음

범위

• 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으로 이어지지 않는다.

완료 리뷰

• 상태: 승인됨
• 요청일: 2026-06-17
• 완료 근거:
  • agent-task/archive/2026/06/m-gito-protosocket-consumer-wire-readiness/03+01_failure_ops/complete.log의 Roadmap Completion에서 failure-ops PASS를 확인했다.
  • 최종 검증은 git diff --check, targeted gitosync/gitoevents tests, race test, cd services/core && go test ./... PASS로 기록되었다.
• 리뷰 필요:
  • 사용자가 완료 결과를 확인했다
  • archive 이동을 승인했다
• 리뷰 코멘트: 2026-06-17 사용자 완료 및 archive 지시로 승인되었다. 방향성 전환에 따라 이 MVP wire-readiness slice는 완료 스냅샷으로 보존한다.

범위 제외

• 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가 있을 때만 소비한다.
• 우선순위: NomadCode/Gito 연동 MVP의 다음 구현 slice로, Plane Work Item Webhook Intake보다 먼저 닫는다.
• 선행 작업: Gito Branch Event Proto-Socket Interop Readiness producer fixture와 기존 gitoevents/gitosync semantic consumer/scan/enqueue 경계
• 후속 작업: Milestone Execution Lifecycle Sync
• 확인 필요: 없음