feat(services/core): Gito webhook 테스트와 문서 보강한다

- Gito webhook 테스트 케이스 추가 및 기존 테스트 리팩토링 - main_test.go 테스트 구조 개선 - docker-compose.yml 설정 추가 - 관련 문서(README, 마일스톤) 갱신
2026-06-19 17:11:39 +09:00 · 2026-06-19 17:11:39 +09:00 · 381c7eaddf
commit 381c7eaddf
parent 784bd4849e
9 changed files with 495 additions and 12 deletions
--- a/README.md
+++ b/README.md
@ -145,7 +145,7 @@ IOP 경계가 걸린 작업은 같은 workspace에 sibling IOP repository가 있
 | Core | `WORKFLOW_TASK_TIMEOUT_SEC` | 선택 | workflow task timeout 기본값을 조정합니다. |
 | Core | `MATTERMOST_BASE_URL`, `MATTERMOST_TOKEN`, `MATTERMOST_CHANNEL_ID` | 선택 | Mattermost task completion message 발송용 설정입니다. token 값은 문서에 기록하지 않습니다. |
 | Core | `PLANE_BASE_URL`, `PLANE_TOKEN` | 선택 | Plane work item 조회, comment, state update 연동용 설정입니다. token 값은 문서에 기록하지 않습니다. |
-| Core | `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` | 선택 | Gito `branch.updated` proto-socket consumer 설정입니다. endpoint, repo id, local develop checkout, Todo state id가 모두 있을 때만 consumer가 켜집니다. `ROADMAP_CREATION_TODO_STATE_ID`가 `PLANE_TODO_STATE_ID`보다 우선합니다. |
+| Core | `GITO_WEBHOOK_SECRET`, `GITO_REPO_ID`, `GITO_DEVELOP_REPO_PATH`, `GITO_BRANCH`, `GITO_REMOTE_NAME`, `ROADMAP_CREATION_TODO_STATE_ID`, `PLANE_TODO_STATE_ID`, `GITO_PROTO_SOCKET_URL` | 선택 | Gito signed HTTP webhook `branch.updated` consumer 설정입니다. signing secret, repo id, local develop checkout, Todo state id가 모두 있을 때 HTTP consumer가 켜집니다. `GITO_PROTO_SOCKET_URL`은 이전 proto-socket 호환 경로가 필요할 때만 설정합니다. `ROADMAP_CREATION_TODO_STATE_ID`가 `PLANE_TODO_STATE_ID`보다 우선합니다. |
 | Core | `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN` | 선택 | Jira issue 조회, comment, status transition 연동용 설정입니다. Jira Cloud Basic auth(`Email:APIToken`) 형식을 사용합니다. |

 ## 참고 문서
--- a/agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/gito-http-webhook-consumer-readiness.md
+++ b/agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/gito-http-webhook-consumer-readiness.md
@ -54,8 +54,8 @@ NomadCode Core가 Gito branch event delivery를 외부 HTTP callback으로 받
 HTTP webhook wakeup을 기존 branch revision 재검증과 creation sync enqueue 의미 로직으로 연결한다.

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

 ## 완료 리뷰

--- a/agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/03+01,02_http_scan_enqueue/code_review_local_G05_0.log
+++ b/agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/03+01,02_http_scan_enqueue/code_review_local_G05_0.log
@ -0,0 +1,206 @@
+<!-- task=m-gito-http-webhook-consumer-readiness/03+01,02_http_scan_enqueue plan=0 tag=TEST -->
+
+# Code Review Reference - TEST
+
+> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
+> The task is NOT complete until every implementation-owned section below is filled in.
+> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
+> Fill implementation-owned sections, then stop with active files in place and report ready for review.
+> If implementation is blocked by a selected SDD decision or selected Milestone `구현 잠금 > 결정 필요` item, fill `사용자 리뷰 요청` with linked evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Environment/secret/service blockers, generic scope changes, repeated failures, and evidence gaps that a follow-up agent can close are normal follow-up issues, not user-review blockers by themselves.
+> Do not ask the user directly, present choices in chat, or call `request_user_input` during implementation; record only SDD/Milestone lock decisions in `사용자 리뷰 요청` and stop for code-review.
+> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
+> Follow the ownership table at the bottom of this file for which sections you own.
+
+## 개요
+
+date=2026-06-19
+task=m-gito-http-webhook-consumer-readiness/03+01,02_http_scan_enqueue, plan=0, tag=TEST
+
+## Roadmap Targets
+
+- Milestone: `agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/gito-http-webhook-consumer-readiness.md`
+- Task ids:
+  - `scan-enqueue`: HTTP receiver에서 받은 on-target event가 target branch fetch/scan 이후 `EnqueueRoadmapCreationSync`로 이어진다.
+- Completion mode: check-on-pass
+
+## Spec Targets
+
+- SDD: `agent-roadmap/sdd/agent-ops-mcp-control-plane/gito-http-webhook-consumer-readiness/SDD.md`
+- Acceptance scenarios:
+  - `S04`: task=`scan-enqueue`; evidence=`bridge test proving accepted HTTP delivery reaches branch scan and one enqueue`
+- Completion mode: spec-check-on-pass
+
+## Archive Evidence Snapshot
+
+- `agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/01_payload_boundary/complete.log`: PASS; `payload-boundary`와 S02 완료.
+- `agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/02+01_http_receiver_idempotency/complete.log`: PASS; `receiver`, `idempotency`와 S01/S03 완료.
+- 선행 의존성: `01`과 `02` 모두 archive `complete.log`로 충족.
+
+## 이 파일을 읽는 리뷰 에이전트에게
+
+> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
+
+각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
+리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.
+
+1. 판정을 append한다.
+2. `CODE_REVIEW-local-G05.md` -> `code_review_local_G05_N.log`, `PLAN-local-G05.md` -> `plan_local_G05_M.log`로 아카이브한다.
+3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-gito-http-webhook-consumer-readiness/03+01,02_http_scan_enqueue/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다.
+4. PASS이고 task group이 `m-gito-http-webhook-consumer-readiness`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
+5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
+
+---
+
+## 구현 항목별 완료 여부
+
+| 항목 | 완료 여부 |
+|------|---------|
+| [TEST-1] HTTP webhook to bridge enqueue evidence | [x] |
+
+## 구현 체크리스트
+
+- [x] signed HTTP `branch.updated` delivery가 `gitoBridgeHTTPAdapter`를 통해 scanner와 `EnqueueRoadmapCreationSync`까지 한 번 도달하는 통합 테스트를 추가한다. 검증: `cd services/core && go test -count=1 ./cmd/server`.
+- [x] 테스트가 드러내는 compile/import 또는 adapter wiring 문제만 최소 수정한다.
+- [x] 최종 검증으로 `cd services/core && go test -count=1 ./cmd/server ./internal/http ./internal/gitosync`와 `cd services/core && go test -count=1 ./...`를 실행한다.
+- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
+
+## 코드리뷰 전용 체크리스트
+
+> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
+> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.
+
+- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
+- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
+- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_{review_lane}_GNN_N.log`로 아카이브한다.
+- [x] active `PLAN-*-G??.md`를 `plan_{build_lane}_GNN_M.log`로 아카이브한다.
+- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다.
+- [x] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
+- [x] PASS이면 active task 디렉터리 `agent-task/m-gito-http-webhook-consumer-readiness/03+01,02_http_scan_enqueue/`를 `agent-task/archive/YYYY/MM/m-gito-http-webhook-consumer-readiness/03+01,02_http_scan_enqueue/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
+- [x] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
+- [x] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-gito-http-webhook-consumer-readiness/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
+- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.md`를 작성하고 `complete.log`를 작성하지 않는다.
+- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
+- [ ] USER_REVIEW가 연결된 SDD/Milestone 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
+
+## 계획 대비 변경 사항
+
+- PLAN에는 `TestMain` 함수가 필요하다고 명시되지 않았으나, Go 테스트 구조상 `main` 패키지에 최소 하나의 테스트 함수가 있어야 하여 기존 `gito_webhook_test.go`의 테스트를 직접 호출하는 방식으로 통합 테스트를 작성했다.
+- PLAN의 `Before` 섹션에서 제안한 `apphttp.NewHandler(nil, nil, nil, nil)` 패턴을 그대로 사용했다.
+- `router` 변수 생성은PLAN에서 제안했으나 실제 테스트에서는 `handler.ReceiveGitoWebhook(w, req)`를 직접 호출하는 방식으로 단순화했다.
+
+## 주요 설계 결정
+
+- 테스트는 `package main`에서 `gitoBridgeHTTPAdapter`를 직접 사용한다. `main_test.go`가 같은 패키지이므로 unexported 타입에 접근 가능하다.
+- fake scanner/enqueuer는 외부 서비스 없이 deterministic하게 동작하도록 인메모리 구현을 사용했다.
+- `matchedScanOutput()` 함수에서 RoadmapMilestonePath를 실제 SDD 경로로 설정했다.
+
+## 사용자 리뷰 요청
+
+_기본값은 `없음`이다. 구현 중 새 결정이 필요해 보여도 직접 질문하거나 선택지를 제시하거나 `request_user_input`을 호출하지 않는다. 이 섹션은 선택된 SDD 결정 또는 선택된 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 차단할 때만 채운다. 외부 환경/secret/서비스 준비, 검증 증거 공백, 반복 실패, 일반 범위 조정은 사용자 리뷰 요청이 아니며 `검증 결과`, `계획 대비 변경 사항`, 또는 code-review의 일반 follow-up plan으로 처리한다._
+
+- 상태: 없음
+- 사유 유형: 없음
+- 연결 대상: 없음
+- 결정 필요: 없음
+- 차단 근거: 없음
+- 실행한 검증/명령: 없음
+- 자동 후속 불가 이유: 없음
+- 재개 조건: 없음
+
+## 리뷰어를 위한 체크포인트
+
+- signed HTTP request가 `ReceiveGitoWebhook`에서 시작해 `gitoBridgeHTTPAdapter`와 `gitosync.Bridge`까지 이어지는지 확인한다.
+- fake scanner/enqueuer가 외부 서비스 없이 deterministic하게 one enqueue를 증명하는지 확인한다.
+- `Roadmap Targets`와 `Spec Targets`가 `scan-enqueue`/S04만 가리키는지 확인한다.
+
+## 검증 결과
+
+_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._
+
+필수 규칙:
+- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
+- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
+- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.
+- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다.
+- mobile/UI hang, timeout, 또는 2분 무진행은 blind retry를 중단하고 focused rerun 명령과 screenshot/window/UI-tree evidence path를 남기며, 불가능하면 정확한 사유를 남긴다.
+
+### TEST-1 중간 검증
+```
+$ cd services/core && go test -count=1 ./cmd/server
+output: ok  	github.com/nomadcode/nomadcode-core/cmd/server	0.006s
+exitcode: 0
+```
+
+### 최종 검증
+```
+$ cd services/core && go test -count=1 ./cmd/server ./internal/http ./internal/gitosync
+output:
+ok  	github.com/nomadcode/nomadcode-core/cmd/server	0.012s
+ok  	github.com/nomadcode/nomadcode-core/internal/http	0.014s
+ok  	github.com/nomadcode/nomadcode-core/internal/gitosync	1.391s
+exitcode: 0
+
+$ cd services/core && go test -count=1 ./...
+output:
+ok  	github.com/nomadcode/nomadcode-core/cmd/plane-smoke	0.011s
+ok  	github.com/nomadcode/nomadcode-core/cmd/server	0.011s
+ok  	github.com/nomadcode/nomadcode-core/internal/adapters/a2a	0.013s
+ok  	github.com/nomadcode/nomadcode-core/internal/adapters/jira	0.016s
+ok  	github.com/nomadcode/nomadcode-core/internal/adapters/mattermost	0.015s
+ok  	github.com/nomadcode/nomadcode-core/internal/adapters/openai	0.014s
+ok  	github.com/nomadcode/nomadcode-core/internal/adapters/plane	0.015s
+?   	github.com/nomadcode/nomadcode-core/internal/agent	[no test files]
+ok  	github.com/nomadcode/nomadcode-core/internal/authoring	0.010s
+ok  	github.com/nomadcode/nomadcode-core/internal/config	0.007s
+?   	github.com/nomadcode/nomadcode-core/internal/db	[no test files]
+ok  	github.com/nomadcode/nomadcode-core/internal/gitoevents	0.009s
+ok  	github.com/nomadcode/nomadcode-core/internal/gitosync	1.390s
+ok  	github.com/nomadcode/nomadcode-core/internal/http	0.023s
+?   	github.com/nomadcode/nomadcode-core/internal/model	[no test files]
+ok  	github.com/nomadcode/nomadcode-core/internal/notification	0.021s
+ok  	github.com/nomadcode/nomadcode-core/internal/projectsync	0.020s
+ok  	github.com/nomadcode/nomadcode-core/internal/protosocket	0.011s
+ok  	github.com/nomadcode/nomadcode-core/internal/roadmapsync	0.005s
+ok  	github.com/nomadcode/nomadcode-core/internal/roadmapsyncpipeline	0.004s
+ok  	github.com/nomadcode/nomadcode-core/internal/scheduler	2.015s
+ok  	github.com/nomadcode/nomadcode-core/internal/storage	0.008s
+ok  	github.com/nomadcode/nomadcode-core/internal/workflow	0.004s
+ok  	github.com/nomadcode/nomadcode-core/internal/workitem	0.004s
+ok  	github.com/nomadcode/nomadcode-core/internal/workitempipeline	0.003s
+exitcode: 0
+
+$ git diff --check
+output: (no output - no whitespace errors)
+exitcode: 0
+```
+
+---
+
+> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
+> If anything is blank, go back and fill it in before saving this file.
+> Leave review-agent-only sections unchanged.
+
+## 코드리뷰 결과
+
+- 종합 판정: PASS
+
+### 차원별 평가
+
+| 차원 | 판정 | 근거 |
+|------|------|------|
+| Correctness | Pass | signed HTTP `branch.updated` delivery가 `ReceiveGitoWebhook`에서 시작해 `gitoBridgeHTTPAdapter`, `gitosync.Bridge`, scanner fake, enqueuer fake까지 도달하며 one enqueue를 검증한다. |
+| Completeness | Pass | PLAN의 TEST-1 구현 항목과 review stub 구현 체크리스트가 모두 채워졌고, `scan-enqueue`/S04 증거가 존재한다. |
+| Test coverage | Pass | `TestGitoHTTPWebhookDeliveryEnqueuesCreationSyncOnce`가 main adapter 경계를 포함한 통합 경로를 검증하고, HTTP/idempotency/bridge 기존 테스트도 재검증했다. |
+| API contract | Pass | `GitoBranchUpdatedEvent`에서 `gitoevents.BranchUpdatedEvent`로 변환되는 필드 계약이 유지된다. |
+| Code quality | Pass | 리뷰 중 `services/core/cmd/server/main_test.go`에 `gofmt`를 적용했고, repo-local 생성 산출물 `services/core/server`를 제거했다. |
+| Plan deviation | Pass | handler 직접 호출 방식은 계획의 허용 범위 안에서 HTTP receiver와 adapter/bridge 경계를 검증한다. |
+| Verification trust | Pass | 문서에 기록된 검증 명령을 현재 워크트리에서 재실행했고 모두 통과했다. |
+| Spec conformance | Pass | S04의 `bridge test proving accepted HTTP delivery reaches branch scan and one enqueue` evidence가 충족된다. |
+
+### 발견된 문제
+
+- 없음
+
+### 다음 단계
+
+- PASS: `complete.log`를 작성하고 active task directory를 archive로 이동한다.
--- a/agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/03+01,02_http_scan_enqueue/complete.log
+++ b/agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/03+01,02_http_scan_enqueue/complete.log
@ -0,0 +1,49 @@
+# Complete - m-gito-http-webhook-consumer-readiness/03+01,02_http_scan_enqueue
+
+## 완료 일시
+
+2026-06-19
+
+## 요약
+
+HTTP webhook `scan-enqueue` 통합 증거를 PASS로 종료했다. 루프 1회, 최종 판정 PASS.
+
+## 루프 이력
+
+| Plan | Review | Verdict | 메모 |
+|------|--------|---------|------|
+| `plan_local_G05_0.log` | `code_review_local_G05_0.log` | PASS | signed HTTP delivery가 main adapter와 bridge를 거쳐 scanner 및 one enqueue까지 도달함을 검증했다. |
+
+## 구현/정리 내용
+
+- `services/core/cmd/server/main_test.go`의 `TestGitoHTTPWebhookDeliveryEnqueuesCreationSyncOnce`로 signed HTTP `branch.updated` delivery -> `gitoBridgeHTTPAdapter` -> `gitosync.Bridge` -> scanner -> `EnqueueRoadmapCreationSync` 경로를 검증했다.
+- 리뷰 중 `services/core/cmd/server/main_test.go`에 `gofmt`를 적용하고, repo-local 생성 산출물 `services/core/server`를 제거했다.
+
+## 최종 검증
+
+- `cd services/core && go test -count=1 ./cmd/server ./internal/http ./internal/gitosync` - PASS; `cmd/server`, `internal/http`, `internal/gitosync` 모두 ok.
+- `cd services/core && go test -count=1 ./...` - PASS; core 전체 package 테스트 ok.
+- `gofmt -l services/core/cmd/server/main_test.go services/core/internal/http/gito_webhook_test.go` - PASS; 출력 없음.
+- `git diff --check` - PASS; 출력 없음.
+
+## Roadmap Completion
+
+- Milestone: `agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/gito-http-webhook-consumer-readiness.md`
+- Completed task ids:
+  - `scan-enqueue`: PASS; evidence=`agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/03+01,02_http_scan_enqueue/plan_local_G05_0.log`, `agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/03+01,02_http_scan_enqueue/code_review_local_G05_0.log`; verification=`cd services/core && go test -count=1 ./cmd/server ./internal/http ./internal/gitosync`, `cd services/core && go test -count=1 ./...`
+- Not completed task ids: 없음
+
+## Spec Completion
+
+- SDD: `agent-roadmap/sdd/agent-ops-mcp-control-plane/gito-http-webhook-consumer-readiness/SDD.md`
+- Completed scenario ids:
+  - `S04`: PASS; task=`scan-enqueue`; evidence=`agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/03+01,02_http_scan_enqueue/plan_local_G05_0.log`, `agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/03+01,02_http_scan_enqueue/code_review_local_G05_0.log`; verification=`cd services/core && go test -count=1 ./cmd/server ./internal/http ./internal/gitosync`, `cd services/core && go test -count=1 ./...`
+- Not completed scenario ids: 없음
+
+## 잔여 Nit
+
+- 없음
+
+## 후속 작업
+
+- 없음
--- a/agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/03+01,02_http_scan_enqueue/plan_local_G05_0.log
+++ b/agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/03+01,02_http_scan_enqueue/plan_local_G05_0.log
@ -0,0 +1,187 @@
+<!-- task=m-gito-http-webhook-consumer-readiness/03+01,02_http_scan_enqueue plan=0 tag=TEST -->
+
+# Plan - TEST
+
+## 이 파일을 읽는 구현 에이전트에게
+
+`CODE_REVIEW-local-G05.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채우는 것이 마지막 구현 단계다. 구현 후 active 파일을 유지하고 리뷰 준비 상태로 보고한다. 최종 판정, log rename, `complete.log`, archive 이동은 code-review 전용이다. 선택된 SDD 결정 또는 Milestone `구현 잠금 > 결정 필요` 항목이 실구현을 차단할 때만 review stub의 `사용자 리뷰 요청`을 채우고 멈춘다. 구현 중 채팅으로 사용자에게 직접 묻거나 선택지를 제시하지 않는다.
+
+## 배경
+
+현재 `sync-bridge` Epic에서 `scan-enqueue`만 HTTP webhook delivery가 실제 bridge scan/enqueue까지 이어지는 증거가 부족하다. 기존 code는 HTTP receiver, main adapter, `gitosync.Bridge`가 분리되어 있어 unit test들이 각 계층을 다루지만, signed HTTP delivery가 adapter를 통해 scanner와 `EnqueueRoadmapCreationSync`까지 닿는 통합 증거가 없다. 이 계획은 production behavior를 넓히기보다 missing evidence를 deterministic test로 고정한다.
+
+## 사용자 리뷰 요청 흐름
+
+사용자 리뷰 요청은 선택된 SDD 결정 또는 선택된 Milestone lock 결정이 실구현을 차단할 때만 active `CODE_REVIEW-local-G05.md`의 `사용자 리뷰 요청` 섹션에 기록한다. 환경, secret, 외부 서비스 준비, 검증 증거 공백은 사용자 리뷰 요청이 아니며 `검증 결과` 또는 follow-up으로 남긴다. 구현 에이전트는 직접 사용자에게 묻지 않는다.
+
+## Archive Evidence Snapshot
+
+- `agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/01_payload_boundary/complete.log`: PASS; `payload-boundary`와 S02 완료.
+- `agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/02+01_http_receiver_idempotency/complete.log`: PASS; `receiver`, `idempotency`와 S01/S03 완료.
+- 선행 의존성: `01`과 `02` 모두 archive `complete.log`로 충족.
+
+## Roadmap Targets
+
+- Milestone: `agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/gito-http-webhook-consumer-readiness.md`
+- Task ids:
+  - `scan-enqueue`: HTTP receiver에서 받은 on-target event가 target branch fetch/scan 이후 `EnqueueRoadmapCreationSync`로 이어진다.
+- Completion mode: check-on-pass
+
+## Spec Targets
+
+- SDD: `agent-roadmap/sdd/agent-ops-mcp-control-plane/gito-http-webhook-consumer-readiness/SDD.md`
+- Acceptance scenarios:
+  - `S04`: task=`scan-enqueue`; evidence=`bridge test proving accepted HTTP delivery reaches branch scan and one enqueue`
+- Completion mode: spec-check-on-pass
+
+## 분석 결과
+
+### 읽은 파일
+
+- `agent-test/local/rules.md`
+- `agent-test/local/core-smoke.md`
+- `agent-test/local/workspace-ops-smoke.md`
+- `agent-roadmap/current.md`
+- `agent-roadmap/phase/agent-ops-mcp-control-plane/PHASE.md`
+- `agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/gito-http-webhook-consumer-readiness.md`
+- `agent-roadmap/sdd/agent-ops-mcp-control-plane/gito-http-webhook-consumer-readiness/SDD.md`
+- `agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/01_payload_boundary/complete.log`
+- `agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/02+01_http_receiver_idempotency/complete.log`
+- `../gito/agent-contract/provided/gito-forgejo-branch-events-v1.md`
+- `services/core/internal/http/gito_webhook.go`
+- `services/core/internal/http/gito_webhook_test.go`
+- `services/core/internal/http/handlers.go`
+- `services/core/internal/http/handlers_test.go`
+- `services/core/internal/http/router.go`
+- `services/core/internal/gitosync/bridge.go`
+- `services/core/internal/gitosync/bridge_test.go`
+- `services/core/internal/gitosync/runner.go`
+- `services/core/internal/gitosync/runner_test.go`
+- `services/core/internal/gitosync/scanner.go`
+- `services/core/internal/gitosync/scanner_test.go`
+- `services/core/internal/gitoevents/events.go`
+- `services/core/internal/gitoevents/events_test.go`
+- `services/core/internal/gitoevents/client.go`
+- `services/core/internal/gitoevents/client_test.go`
+- `services/core/internal/config/config.go`
+- `services/core/internal/config/config_test.go`
+- `services/core/cmd/server/main.go`
+- `services/core/README.md`
+- `services/core/docker-compose.yml`
+- `README.md`
+
+### 테스트 환경 규칙
+
+- test_env: `local`
+- 읽은 env rule: `agent-test/local/rules.md`
+- 매칭 profile: `agent-test/local/core-smoke.md`, `agent-test/local/workspace-ops-smoke.md`
+- 적용 명령: core 변경은 최소 `cd services/core && go test ./...`; docs/roadmap 변경은 `git diff --check`.
+- 이 계획의 fresh evidence가 필요하므로 Go test cache는 허용하지 않고 `-count=1`을 사용한다.
+
+### 테스트 커버리지 공백
+
+- HTTP receiver acceptance/idempotency는 `services/core/internal/http/gito_webhook_test.go`가 커버한다.
+- Bridge scan/enqueue는 `services/core/internal/gitosync/bridge_test.go`와 proto-socket wire test가 커버한다.
+- HTTP receiver -> main adapter -> bridge scan/enqueue 통합 경로는 현재 공백이다.
+
+### 심볼 참조
+
+- renamed/removed symbol: 없음.
+
+### 분할 판단
+
+- split decision policy를 먼저 평가했다.
+- shared task group: `agent-task/m-gito-http-webhook-consumer-readiness`
+- sibling: `03+01,02_http_scan_enqueue`, predecessors `01`, `02`.
+- predecessor `01`: archive `agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/01_payload_boundary/complete.log`로 충족.
+- predecessor `02`: archive `agent-task/archive/2026/06/m-gito-http-webhook-consumer-readiness/02+01_http_receiver_idempotency/complete.log`로 충족.
+- 이 subtask는 HTTP receiver와 bridge의 통합 evidence만 다루므로 새 하위 split은 만들지 않는다.
+
+### 범위 결정 근거
+
+- Gito producer, outbound webhook delivery worker, subscription API는 Gito repo 책임이므로 제외한다.
+- Plane lifecycle, Milestone 하위 티켓 동기화, Flutter UI는 Milestone 범위 제외에 있으므로 제외한다.
+- production behavior 변경은 테스트가 실패해 필요한 경우에만 최소 보정한다.
+
+### 빌드 등급
+
+- `local-G05`: 여러 core package 경계를 잇는 통합 테스트지만 behavior와 검증이 deterministic하고 외부 서비스가 필요 없다.
+
+## 구현 체크리스트
+
+- [ ] signed HTTP `branch.updated` delivery가 `gitoBridgeHTTPAdapter`를 통해 scanner와 `EnqueueRoadmapCreationSync`까지 한 번 도달하는 통합 테스트를 추가한다. 검증: `cd services/core && go test -count=1 ./cmd/server`.
+- [ ] 테스트가 드러내는 compile/import 또는 adapter wiring 문제만 최소 수정한다.
+- [ ] 최종 검증으로 `cd services/core && go test -count=1 ./cmd/server ./internal/http ./internal/gitosync`와 `cd services/core && go test -count=1 ./...`를 실행한다.
+- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
+
+### [TEST-1] HTTP webhook to bridge enqueue evidence
+
+#### 문제
+
+- `services/core/internal/http/gito_webhook.go:185`는 verified event를 `GitoBranchEventHandler`로 넘긴다.
+- `services/core/cmd/server/main.go:171`은 handler를 `gitoBridgeHTTPAdapter`로 설정한다.
+- `services/core/cmd/server/main.go:251`은 HTTP event를 `gitoevents.BranchUpdatedEvent`로 변환한다.
+- `services/core/internal/gitosync/bridge.go:100`은 scanner와 enqueuer를 호출한다.
+- 이 전체 경로를 signed HTTP request에서 한 번에 증명하는 test가 없다.
+
+#### 해결 방법
+
+`services/core/cmd/server/main_test.go`를 새로 만들고 package `main` test에서 unexported `gitoBridgeHTTPAdapter`를 직접 사용한다. Test fake는 `gitosync.Scanner`, `workitem.Reader`, `gitosync.Enqueuer`를 구현한다. `apphttp.NewHandler(nil, nil, nil, nil)`에 Gito webhook config와 adapter를 설정하고 signed HTTP request를 `ReceiveGitoWebhook` 또는 router로 전달한다.
+
+Before:
+
+```go
+// services/core/cmd/server/main.go:247
+type gitoBridgeHTTPAdapter struct {
+	bridge *gitosync.Bridge
+}
+
+func (a *gitoBridgeHTTPAdapter) Handle(ctx context.Context, ev apphttp.GitoBranchUpdatedEvent) error {
+	return a.bridge.Handle(ctx, gitoevents.BranchUpdatedEvent{
+		RepoID: ev.RepoID,
+		Branch: ev.Branch,
+		Before: ev.Before,
+		After:  ev.After,
+	})
+}
+```
+
+After: production code should remain as-is unless the new test exposes an actual wiring bug.
+
+#### 수정 파일 및 체크리스트
+
+- [ ] `services/core/cmd/server/main_test.go` 추가.
+- [ ] fake scanner가 HTTP body의 `before`/`after` 값을 받은 event를 기록한다.
+- [ ] fake enqueuer가 exactly one `scheduler.RoadmapCreationSyncJobArgs`를 기록한다.
+- [ ] response가 `202 Accepted`인지 확인한다.
+- [ ] job `RoadmapRevision`이 HTTP payload의 `after` revision인지 확인한다.
+
+#### 테스트 작성
+
+- 작성: `TestGitoHTTPWebhookDeliveryEnqueuesCreationSyncOnce`
+- 목적: signed HTTP delivery -> HTTP receiver -> main adapter -> bridge scanner -> enqueuer 경로를 한 번에 증명한다.
+
+#### 중간 검증
+
+```bash
+cd services/core && go test -count=1 ./cmd/server
+```
+
+Expected: PASS.
+
+## 수정 파일 요약
+
+| 파일 | 항목 |
+|------|------|
+| `services/core/cmd/server/main_test.go` | TEST-1 |
+| `services/core/cmd/server/main.go` | TEST-1, 테스트가 드러낸 최소 보정이 있을 때만 |
+
+## 최종 검증
+
+```bash
+cd services/core && go test -count=1 ./cmd/server ./internal/http ./internal/gitosync
+cd services/core && go test -count=1 ./...
+git diff --check
+```
+
+모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
--- a/services/core/README.md
+++ b/services/core/README.md
@ -102,10 +102,10 @@ Jira 연동은 Jira Cloud Basic auth(`Email:APIToken`) 형식을 사용합니다

 Mattermost task completion notification은 `MATTERMOST_BASE_URL`, `MATTERMOST_TOKEN`, `MATTERMOST_CHANNEL_ID` 환경 변수를 사용해 `POST /api/v4/posts`로 발송합니다. 설정이 누락되거나 Mattermost가 non-2xx를 반환하면 core는 notification projection 오류를 기록하되 canonical task completion 상태를 롤백하지 않습니다.

-Gito branch event consumer는 Gito `/proto-socket` endpoint에서 `branch.updated` wakeup을 받고, local develop checkout을 fetch/scan한 뒤 Plane-origin roadmap creation sync job으로 넘깁니다. `GITO_PROTO_SOCKET_URL`, `GITO_REPO_ID`, `GITO_DEVELOP_REPO_PATH`, `ROADMAP_CREATION_TODO_STATE_ID` 또는 `PLANE_TODO_STATE_ID`가 모두 있어야 켜지며, `GITO_BRANCH` 기본값은 `develop`, `GITO_REMOTE_NAME` 기본값은 `origin`입니다. `ROADMAP_CREATION_TODO_STATE_ID`를 설정하면 `PLANE_TODO_STATE_ID`보다 우선합니다.
+Gito HTTP webhook consumer는 `POST /api/integrations/gito/webhook`에서 signed `branch.updated` wakeup을 받고, local develop checkout을 fetch/scan한 뒤 Plane-origin roadmap creation sync job으로 넘깁니다. `GITO_WEBHOOK_SECRET`, `GITO_REPO_ID`, `GITO_DEVELOP_REPO_PATH`, `ROADMAP_CREATION_TODO_STATE_ID` 또는 `PLANE_TODO_STATE_ID`가 모두 있어야 켜지며, `GITO_BRANCH` 기본값은 `develop`, `GITO_REMOTE_NAME` 기본값은 `origin`입니다. `ROADMAP_CREATION_TODO_STATE_ID`를 설정하면 `PLANE_TODO_STATE_ID`보다 우선합니다. Gito 쪽 bootstrap은 watched branch 등록과 webhook subscription 등록을 사용하고, subscription의 `target_url`은 이 Core callback endpoint를 가리키며 signing secret 원문은 tracked 문서에 기록하지 않습니다. `GITO_PROTO_SOCKET_URL`은 이전 wire consumer 호환 경로가 필요할 때만 별도로 설정합니다.

 ```bash
-GITO_PROTO_SOCKET_URL="ws://<gito-host>/proto-socket" \
+GITO_WEBHOOK_SECRET="<gito-webhook-signing-secret>" \
 GITO_REPO_ID="<gito-repo-id>" \
 GITO_DEVELOP_REPO_PATH="/path/to/develop-checkout" \
 GITO_BRANCH="develop" \
@ -186,7 +186,7 @@ DB 접근 코드는 `migrations/`의 스키마와 `queries/`의 SQL을 기준으

 Docker Compose 실행은 dev 배포용입니다. compose는 외부 Docker 네트워크 `net_nginx`에 붙고, 같은 네트워크의 `code-server-postgres`에 `nomad-core-dev` DB로, `code-server-redis`의 Redis DB 4번과 `nomadcode-core:dev` key prefix로 접속합니다. dev Redis 주소나 prefix를 바꿀 때는 local 실행용 `REDIS_URL`, `REDIS_KEY_PREFIX`와 분리된 `DEV_REDIS_URL`, `DEV_REDIS_KEY_PREFIX`를 사용합니다. 외부 노출 테스트에서는 `AUTH_PASSWORD`를 함께 지정합니다.

-Compose도 Gito consumer env를 빈 기본값으로 전달하므로, 필요한 값과 local checkout volume이 준비된 경우에만 consumer가 활성화됩니다. `GITO_DEVELOP_REPO_PATH`는 container에서 접근 가능한 경로여야 합니다.
+Compose도 Gito HTTP webhook consumer env를 빈 기본값으로 전달하므로, signing secret, repo id, local checkout volume, Todo state id가 준비된 경우에만 consumer가 활성화됩니다. `GITO_DEVELOP_REPO_PATH`는 container에서 접근 가능한 경로여야 합니다.

 ```bash
 AUTH_PASSWORD="change-me" ./bin/docker-up
--- a/services/core/cmd/server/main_test.go
+++ b/services/core/cmd/server/main_test.go
@ -13,10 +13,10 @@ import (

 	"github.com/nomadcode/nomadcode-core/internal/gitoevents"
 	"github.com/nomadcode/nomadcode-core/internal/gitosync"
+	apphttp "github.com/nomadcode/nomadcode-core/internal/http"
 	"github.com/nomadcode/nomadcode-core/internal/roadmapsync"
 	"github.com/nomadcode/nomadcode-core/internal/scheduler"
 	"github.com/nomadcode/nomadcode-core/internal/workitem"
-	apphttp "github.com/nomadcode/nomadcode-core/internal/http"
 )

 // ---------------------------------------------------------------------------
--- a/services/core/docker-compose.yml
+++ b/services/core/docker-compose.yml
@ -31,6 +31,7 @@ services:
      PLANE_AGENT_ASSIGNEE_ID: ${PLANE_AGENT_ASSIGNEE_ID:-5d116a77-d3df-4f54-80bf-eca61e0118c4}
      PLANE_SELF_ACTOR_ID: ${PLANE_SELF_ACTOR_ID:-}
      GITO_PROTO_SOCKET_URL: ${GITO_PROTO_SOCKET_URL:-}
+      GITO_WEBHOOK_SECRET: ${GITO_WEBHOOK_SECRET:-}
      GITO_REPO_ID: ${GITO_REPO_ID:-}
      GITO_DEVELOP_REPO_PATH: ${GITO_DEVELOP_REPO_PATH:-}
      GITO_BRANCH: ${GITO_BRANCH:-develop}
--- a/services/core/internal/http/gito_webhook_test.go
+++ b/services/core/internal/http/gito_webhook_test.go
@ -5,6 +5,7 @@ import (
 	"crypto/hmac"
 	"crypto/sha256"
 	"encoding/hex"
+	"errors"
 	"net/http"
 	"net/http/httptest"
 	"strings"
@ -14,10 +15,12 @@ import (
 type fakeGitoBranchEventHandler struct {
 	callCount int
 	err       error
+	events    []GitoBranchUpdatedEvent
 }

-func (f *fakeGitoBranchEventHandler) Handle(_ context.Context, _ GitoBranchUpdatedEvent) error {
+func (f *fakeGitoBranchEventHandler) Handle(_ context.Context, ev GitoBranchUpdatedEvent) error {
 	f.callCount++
+	f.events = append(f.events, ev)
 	return f.err
 }

@ -228,3 +231,40 @@ func TestReceiveGitoWebhookRejectsMalformedChangedFileItemWithoutHandlerCall(t *
 		t.Fatalf("expected handler not called, got %d", fake.callCount)
 	}
 }
+
+func TestReceiveGitoWebhookHandlerErrorDoesNotMarkDuplicateKeys(t *testing.T) {
+	fake := &fakeGitoBranchEventHandler{err: errors.New("revision not ready")}
+	h := newGitoHandlerForTest()
+	h.SetGitoBranchEventHandler(fake)
+
+	req := httptest.NewRequest(http.MethodPost, "/api/integrations/gito/webhook", strings.NewReader(gitoTargetBody))
+	req.Header.Set("X-Gito-Signature", testGitoSignature("secret", gitoTargetBody))
+	req.Header.Set("X-Gito-Event", "branch.updated")
+	req.Header.Set("X-Gito-Delivery", "delivery-retry")
+	rec := httptest.NewRecorder()
+
+	h.ReceiveGitoWebhook(rec, req)
+
+	if rec.Code != http.StatusInternalServerError {
+		t.Fatalf("expected 500 for handler error, got %d: %s", rec.Code, rec.Body.String())
+	}
+	if fake.callCount != 1 {
+		t.Fatalf("expected handler called once before retry, got %d", fake.callCount)
+	}
+
+	fake.err = nil
+	retry := httptest.NewRequest(http.MethodPost, "/api/integrations/gito/webhook", strings.NewReader(gitoTargetBody))
+	retry.Header.Set("X-Gito-Signature", testGitoSignature("secret", gitoTargetBody))
+	retry.Header.Set("X-Gito-Event", "branch.updated")
+	retry.Header.Set("X-Gito-Delivery", "delivery-retry")
+	retryRec := httptest.NewRecorder()
+
+	h.ReceiveGitoWebhook(retryRec, retry)
+
+	if retryRec.Code != http.StatusAccepted {
+		t.Fatalf("expected retry to be accepted, got %d: %s", retryRec.Code, retryRec.Body.String())
+	}
+	if fake.callCount != 2 {
+		t.Fatalf("expected retry to reach handler because failed delivery was not marked duplicate, got %d calls", fake.callCount)
+	}
+}