# Milestone: Gito HTTP Webhook Consumer Readiness

## 위치

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

## 목표

NomadCode Core의 Gito branch event consumer를 Gito 제공 계약 `gito.forgejo-branch-events.v1`의 signed HTTP webhook delivery와 맞춘다. Gito는 외부/인접 consumer에게 `/proto-socket` binary transport를 요구하지 않으며, NomadCode는 `branch.updated` JSON delivery를 wakeup signal로 받아 target branch revision을 재검증한 뒤 기존 creation sync enqueue 흐름으로 수렴한다.

## 상태

[완료]

## 승격 조건

- 없음

## 구현 잠금

- 상태: 해제
- SDD: 필요
- SDD 문서: `agent-roadmap/sdd/agent-ops-mcp-control-plane/gito-http-webhook-consumer-readiness/SDD.md`
- 잠금 해제 조건:
  - [x] SDD 잠금이 해제되어 있다
  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다
  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다
  - [x] Evidence Map이 plan의 `Spec Targets`와 완료 시 `Spec Completion`으로 검증 가능하게 연결되어 있다
  - [x] Workspace lock `nomadcode:gito-http-webhook-consumer-readiness`의 모든 `rely-on.status`가 `enable`이다
- 결정 필요: 없음

## 범위

- Gito -> NomadCode signed HTTP webhook callback endpoint
- `X-Gito-Event`, `X-Gito-Delivery`, `X-Gito-Signature` 기준의 delivery 검증과 idempotency 경계
- Gito `branch.updated` base payload를 NomadCode 전용 필수 필드 없이 소비하는 schema boundary
- 기존 `gitoevents` decode/filter와 `gitosync` branch scan/enqueue 의미 로직의 HTTP transport 재연결
- Gito webhook subscription bootstrap과 NomadCode callback/secret 설정 문서화
- invalid signature, malformed payload, duplicate delivery, not-ready revision, Gito retry에 대한 운영 로그와 실패 처리

## 기능

### Epic: [webhook-consumer] Gito HTTP webhook intake

NomadCode Core가 Gito branch event delivery를 외부 HTTP callback으로 받고, Gito 원문 계약을 source of truth로 소비한다.

- [x] [receiver] Gito `branch.updated` HTTP callback endpoint를 추가한다. 검증: signed `branch.updated` delivery는 수락되고, wrong event와 invalid signature는 side effect 없이 거부된다.
- [x] [payload-boundary] Gito base payload를 repo/branch/revision/change hint 중심으로 해석하고 NomadCode 전용 필드를 요구하지 않는다. 검증: NomadCode 전용 필드 없이도 on-target event가 decode된다.
- [x] [idempotency] `X-Gito-Delivery`와 revision key 기준으로 duplicate delivery를 중복 enqueue 없이 처리한다. 검증: 같은 delivery 또는 같은 revision 재전달이 정확히 한 번의 sync 후보로 수렴한다.

### Epic: [sync-bridge] Revision verification and creation sync

HTTP webhook wakeup을 기존 branch revision 재검증과 creation sync enqueue 의미 로직으로 연결한다.

- [x] [scan-enqueue] HTTP receiver에서 받은 on-target event가 target branch fetch/scan 이후 `EnqueueRoadmapCreationSync`로 이어진다. 검증: 한 건의 Gito webhook delivery가 target branch 재검증 후 정확히 하나의 creation sync job으로 수렴한다.
- [x] [config-docs] `GITO_PROTO_SOCKET_URL` 중심의 소비자 설정을 webhook callback endpoint, signing secret, Gito subscription bootstrap 기준으로 교체한다. 검증: secret 원문 없이 local/dev webhook consumer 설정 경로가 문서화된다.
- [x] [failure-ops] invalid signature, malformed payload, not-ready revision, duplicate delivery, Gito retry가 core server shutdown이나 중복 Plane mutation으로 이어지지 않는다. 검증: 장애 입력이 안전하게 reject/drop/retry 후보로 기록된다.

## 완료 리뷰

- 상태: 통과
- 요청일: 2026-06-19
- 완료 근거:
  - `scan-enqueue`가 `agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/03+01,02_http_scan_enqueue/complete.log`의 Roadmap Completion과 Spec Completion(S04) PASS 근거로 완료되었다.
  - 모든 기능 Task가 체크되었고 SDD는 `[승인됨]`/잠금 해제, workspace lock은 `agent-ops/bin/roadmap-dependency-checker.sh` 결과 `true`로 확인했다.
  - 코드 레벨 종료 감사에서 Gito 제공 계약에 맞춰 `X-Gito-Delivery` 누락 delivery를 side effect 없이 `400`으로 거부하도록 보강했고, 관련 테스트를 갱신했다.
  - 최종 검증은 `cd services/core && go test -count=1 ./cmd/server ./internal/http ./internal/gitosync ./internal/config`, `cd services/core && go test -count=1 ./...`, `git diff --check` PASS로 확인했다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 코드 레벨 종료 감사와 소규모 계약 보강 후 완료/archive 대상으로 확정했다.

## 범위 제외

- Gito Forgejo webhook producer와 outbound webhook delivery worker 구현
- Gito 제공 계약 `gito.forgejo-branch-events.v1` 원문 변경
- Gito event schema를 NomadCode 전용 필드로 확장하는 작업
- Plane `Todo -> In Progress` 실행 lifecycle
- Milestone Task와 Plane 하위 티켓 동기화
- Flutter UI에서 branch event 상태를 표시하는 기능

## 작업 컨텍스트

- 관련 경로: `services/core/internal/gitoevents/`, `services/core/internal/gitosync/`, `services/core/internal/http/`, `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.forgejo-branch-events.v1`)
- 관련 Gito Milestone: `Forgejo Branch Event MVP`, `Webhook Revision Reconcile`
- 표준선(선택): NomadCode는 Gito `branch.updated` delivery를 wakeup signal로만 사용하고, 최종 판단은 target branch fetch/scan과 provider identity 재검증으로 수행한다. Gito schema는 여러 consumer를 위한 범용 규약이며, Gito -> external consumer delivery는 HTTP webhook/callback이고 `/proto-socket`은 Gito 내부 control/runtime transport로 본다.
- 이전 방향 정리: `Gito Proto-Socket Consumer Wire Readiness`는 archive된 완료 기록으로 보존하되, 현재 프로젝트 방향에서는 NomadCode/Gito 외부 소비 표면으로 재사용하지 않는다.
- 우선순위: 최우선 - `Roadmap Driven Agent-Ops Automation`과 `Milestone Execution Lifecycle Sync`보다 먼저 SDD gate와 Gito 외부 의존 잠금 상태를 정리한다.
- 선행 작업: Gito 제공 계약 `gito.forgejo-branch-events.v1`의 HTTP webhook delivery 경계 확인
- 외부 의존 잠금: Gito `agent-roadmap/phase/provider-change-request-integration/milestones/webhook-revision-reconcile.md`의 consumer webhook subscription과 signed HTTP delivery 구현이 완료되어야 실제 연동 구현/검증을 닫을 수 있다.
- 후속 작업: Milestone Execution Lifecycle Sync
- 확인 필요:
  - [x] SDD 작성과 gate 확인 후 구현 잠금을 해제한다.