toki/gito
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
gito/agent-task/m-webhook-revision-reconcile/01_http_delivery/CODE_REVIEW-local-G05.md

16 KiB
Raw Blame History

Code Review Reference - REVIEW_REVIEW_API

[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-17 task=m-webhook-revision-reconcile/01_http_delivery, plan=2, tag=REVIEW_REVIEW_API

Roadmap Targets

  • Milestone: agent-roadmap/phase/provider-change-request-integration/milestones/webhook-revision-reconcile.md
  • Task ids:
    • deliver: branch.updated 같은 normalized event를 signed HTTP POST로 전달한다.
    • nomadcode-wakeup: NomadCode dev consumer가 generic branch.updated HTTP webhook delivery를 wakeup으로 매핑할 수 있는 interop path를 검증한다.
  • Completion mode: check-on-pass

Spec Targets

  • SDD: agent-roadmap/sdd/provider-change-request-integration/webhook-revision-reconcile/SDD.md
  • Acceptance scenarios:
    • S02: task=deliver; evidence=cd services/core && go test -run TestWebhookDeliveryBranchUpdated ./internal/controlplane/ -v -count=1
    • S03: task=nomadcode-wakeup; evidence=fake NomadCode consumer test receives generic branch.updated without NomadCode-only required fields
  • Completion mode: spec-check-on-pass

Archive Evidence Snapshot

  • Current archived plan: agent-task/m-webhook-revision-reconcile/01_http_delivery/plan_cloud_G06_1.log
  • Current archived review: agent-task/m-webhook-revision-reconcile/01_http_delivery/code_review_cloud_G06_1.log
  • Prior loop history:
    • agent-task/m-webhook-revision-reconcile/01_http_delivery/plan_local_G05_0.log + agent-task/m-webhook-revision-reconcile/01_http_delivery/code_review_local_G05_0.log - FAIL; original HMAC/secret_ref/fallback/retry Required set.
    • agent-task/m-webhook-revision-reconcile/01_http_delivery/plan_cloud_G06_1.log + agent-task/m-webhook-revision-reconcile/01_http_delivery/code_review_cloud_G06_1.log - FAIL; fallback id is non-empty but not stable across empty-provider retry.
  • Verdict: FAIL
  • Required summary:
    • services/core/internal/controlplane/runtime.go:535: fallback X-Gito-Delivery uses random record.ID when provider delivery id is empty, so the same revision retry can get different consumer delivery ids.
  • Suggested summary: 없음
  • Nit summary: 없음
  • Affected files:
    • services/core/internal/controlplane/runtime.go
    • services/core/internal/controlplane/runtime_test.go
  • Verification evidence:
    • go test -run TestWebhookDeliveryBranchUpdated ./internal/controlplane/ -v -count=1 from services/core - PASS.
    • go test -run 'TestWebhookDeliveryBranchUpdated|TestRuntime_WebhookDeliveryWithSecret|TestRuntime_WebhookDeliveryUnsignedSecretRefFails|TestRuntime_WebhookDeliveryFallbackDeliveryID|TestRuntime_WebhookDeliveryFailureAllowsRetry' ./internal/controlplane/ -v -count=1 from services/core - PASS.
    • go test ./... from services/core - PASS.
    • git diff --check - PASS.
  • Roadmap carryover: deliver, nomadcode-wakeup
  • Spec carryover: S02, S03
  • Narrow archive reread allowed: the two current archived log paths above only if details are needed.

이 파일을 읽는 리뷰 에이전트에게

[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-webhook-revision-reconcile/01_http_delivery/로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 USER_REVIEW.md를 작성한다.
  4. PASS이고 task group이 m-<milestone-slug>이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 update-roadmap 호출은 런타임 책임이다.
  5. 적용 가능한 코드리뷰 전용 체크리스트 항목을 최종 .log 위치에서 체크한 뒤 보고한다.

구현 항목별 완료 여부

항목 완료 여부
[REVIEW_REVIEW_API-1] Stable Fallback Delivery ID Across Empty-Provider Retry [x]

구현 체크리스트

  • provider delivery id가 비어 있을 때 consumerDeliveryID가 random record.ID 대신 revision identity에서 결정적으로 파생한 stable non-empty id를 반환하도록 고친다.
  • header X-Gito-Delivery와 payload delivery_id가 같은 stable consumer delivery id를 쓰는지 유지한다.
  • 빈 provider delivery id에서 첫 webhook delivery가 5xx로 실패하고 같은 revision을 재시도할 때 두 요청의 X-Gito-Delivery와 body delivery_id가 모두 동일한지 검증하는 테스트를 추가하거나 기존 retry 테스트를 확장한다.
  • cd services/core && go test -run 'TestRuntime_WebhookDeliveryFallbackDeliveryID|TestRuntime_WebhookDeliveryFailureAllowsRetry' ./internal/controlplane/ -v -count=1를 실행한다.
  • cd services/core && go test -run TestWebhookDeliveryBranchUpdated ./internal/controlplane/ -v -count=1를 실행한다.
  • cd services/core && go test ./...를 실행한다.
  • CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다. 686,917.5

코드리뷰 전용 체크리스트

[REVIEW AGENT ONLY] 이 체크리스트는 코드리뷰 에이전트만 사용한다. 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.

  • 코드리뷰 결과에 PASS, WARN, FAIL 중 하나의 판정을 append한다.
  • 판정과 차원별 평가, Required/Suggested/Nit 분류가 서로 일치한다.
  • active CODE_REVIEW-*-G??.md를 code_review_local_G05_N.log로 아카이브한다.
  • active PLAN-*-G??.md를 plan_local_G05_M.log로 아카이브한다.
  • .gitignore의 Agent-Ops 관리 block이 agent-task/**/*.md와 agent-task/**/*.log를 unignore하고 agent-roadmap/current.md를 ignore하는지 확인한다.
  • PASS이면 agent-ops/skills/common/code-review/templates/complete-log-template.md 기준으로 complete.log를 작성하고 active .md 파일을 남기지 않는다.
  • PASS이면 active task 디렉터리 agent-task/m-webhook-revision-reconcile/01_http_delivery/를 agent-task/archive/YYYY/MM/m-webhook-revision-reconcile/01_http_delivery/로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
  • PASS이고 task group이 m-<milestone-slug>이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 update-roadmap 직접 호출을 하지 않는다.
  • PASS split 작업이면 이동 후 빈 active parent agent-task/m-webhook-revision-reconcile/를 제거하거나, 남은 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로 이동한다.

계획 대비 변경 사항

계획의 required summary에 명시된 문제(랜덤 fallback)를 해결하기 위해 consumerDeliveryID 함수를 revision identity 기반 deterministic fallback으로 변경했다. 계획과 다른 점은 별도 consumerDeliveryIDFromRevision helper 함수를 새로 만들어 fallback 로직을 분리한 것이며, 기존 record.ID 사용 경로를 완전히 제거했다.

주요 설계 결정

deterministic fallback ID 파생 방식

provider delivery id가 비어있을 때 record.ID 대신 revision identity(RepoID, Branch, Before, After)를 해시하지 않고 fallback:{repo}:{branch}:{before}:{after} 형태의 결정적 문자열을 그대로 사용한다. 이 방식은:

  • 같은 revision identity에 대해 항상 같은 값을 반환
  • human-readable하여 디버깅 용이
  • external system과의 id 매핑이 필요할 경우 직관적

consumerDeliveryIDFromRevision helper는 repoID와 branch가 모두 비어있을 때 empty string을 반환하여 최종 consumerDeliveryID가 "unknown"으로 떨어질 수 있도록 한다.

테스트 확장

기존 TestRuntime_WebhookDeliveryFailureAllowsRetry를 새 구현으로 교체하여:

  • 빈 provider delivery id(deliveryID="")로 두 번 호출
  • 첫 호출은 500 error로 실패
  • 두 번째 호출은 성공
  • 두 호출 모두 X-Gito-Delivery header와 body delivery_id가 동일한지 검증
  • deterministic fallback format이 맞는지 검증

사용자 리뷰 요청

기본값은 없음이다. 구현 중 새 결정이 필요해 보여도 직접 질문하거나 선택지를 제시하거나 request_user_input을 호출하지 않는다. 이 섹션은 선택된 SDD 결정 또는 선택된 Milestone 구현 잠금 > 결정 필요 항목이 실구현을 차단할 때만 채운다. 외부 환경/secret/서비스 준비, 검증 증거 공백, 반복 실패, 일반 범위 조정은 사용자 리뷰 요청이 아니며 검증 결과, 계획 대비 변경 사항, 또는 code-review의 일반 follow-up plan으로 처리한다.

  • 상태: 없음
  • 사유 유형: 없음
  • 연결 대상: 없음
  • 결정 필요: 없음
  • 차단 근거: 없음
  • 실행한 검증/명령: 없음
  • 자동 후속 불가 이유: 없음
  • 재개 조건: 없음

리뷰어를 위한 체크포인트

  • provider delivery id가 없을 때 fallback consumer delivery id가 random event id가 아니라 revision identity 기반으로 결정적인지 확인한다.
  • 빈 provider delivery id에서 실패 후 재시도해도 X-Gito-Delivery가 동일하고 body delivery_id도 같은 값인지 확인한다.
  • 기존 HMAC, secret_ref unsigned 차단, provider delivery id 존재 시 retry 동작이 회귀하지 않았는지 확인한다.
  • Roadmap Targets와 Spec Targets의 S02/S03 증거가 최신 검증 출력으로 충족되는지 확인한다.

검증 결과

구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다.

필수 규칙:

  • 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
  • 대체가 필요하면 계획 대비 변경 사항에 이유와 대체 명령을 기록한다.
  • 검증 결과에는 실제 stdout/stderr를 붙여 넣는다.
  • 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 사용자 리뷰 요청에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다.
  • mobile/UI hang, timeout, 또는 2분 무진행은 blind retry를 중단하고 focused rerun 명령과 screenshot/window/UI-tree evidence path를 남기며, 불가능하면 정확한 사유를 남긴다.

REVIEW_REVIEW_API-1 중간 검증

$ cd services/core && go test -run 'TestRuntime_WebhookDeliveryFallbackDeliveryID|TestRuntime_WebhookDeliveryFailureAllowsRetry' ./internal/controlplane/ -v -count=1
=== RUN   TestRuntime_WebhookDeliveryFallbackDeliveryID
--- PASS: TestRuntime_WebhookDeliveryFallbackDeliveryID (0.00s)
=== RUN   TestRuntime_WebhookDeliveryFailureAllowsRetry
--- PASS: TestRuntime_WebhookDeliveryFailureAllowsRetry (0.00s)
PASS
ok  	git.toki-labs.com/toki/gito/services/core/internal/controlplane	0.010s

최종 검증

$ cd services/core && go test -run TestWebhookDeliveryBranchUpdated ./internal/controlplane/ -v -count=1
=== RUN   TestWebhookDeliveryBranchUpdated
--- PASS: TestWebhookDeliveryBranchUpdated (0.00s)
PASS
ok  	git.toki-labs.com/toki/gito/services/core/internal/controlplane	0.010s

$ cd services/core && go test ./...
?   	git.toki-labs.com/toki/gito/services/core/cmd/server	[no test files]
?   	git.toki-labs.com/toki/gito/services/core/cmd/worker	[no test files]
ok  	git.toki-labs.com/toki/gito/services/core/internal/config	(cached)
ok  	git.toki-labs.com/toki/gito/services/core/internal/controlplane	0.876s
ok  	git.toki-labs.com/toki/gito/services/core/internal/core	(cached)
?   	git.toki-labs.com/toki/gito/services/core/internal/events	[no test files]
ok  	git.toki-labs.com/toki/gito/services/core/internal/gitengine	(cached)
ok  	git.toki-labs.com/toki/gito/services/core/internal/protosocket	(cached)
?   	git.toki-labs.com/toki/gito/services/core/internal/provider	[no test files]
ok  	git.toki-labs.com/toki/gito/services/core/internal/provider/forgejo	(cached)
ok  	git.toki-labs.com/toki/gito/services/core/internal/storage	(cached)
ok  	git.toki-labs.com/toki/gito/services/core/internal/worker	(cached)

모든 검증 명령이 exit code 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.

Sections and Ownership

Section Owner Note
Header comment, 개요, 리뷰 에이전트 지시 Fixed at stub creation Implementing agent must not modify or execute archive/finalization
Roadmap Targets Fixed at stub creation Code-review copies it into complete.log only on PASS
Spec Targets Fixed at stub creation Code-review copies it into complete.log only on PASS
Archive Evidence Snapshot Fixed at stub creation Implementer can reread only the named archived logs if needed
구현 항목별 완료 여부 Implementing agent checks boxes only Item names stay fixed
구현 체크리스트 Implementing agent checks boxes only Text/order stay fixed
코드리뷰 전용 체크리스트 Review agent only Implementing agent must not modify
계획 대비 변경 사항, 주요 설계 결정 Implementing agent Replace placeholders with actual content
사용자 리뷰 요청 Implementing agent Keep 상태: 없음 unless selected SDD/Milestone lock decision blocks
리뷰어를 위한 체크포인트 Fixed at stub creation Reviewer focus
검증 결과 Implementing agent Fill command output only

코드리뷰 결과

  • 종합 판정: PASS
  • 차원별 평가:
    • correctness: Pass
    • completeness: Pass
    • test coverage: Pass
    • API contract: Pass
    • code quality: Pass
    • plan deviation: Pass
    • verification trust: Pass
    • spec conformance: Pass
  • 발견된 문제: 없음
  • 다음 단계: PASS 종결로 complete.log를 작성하고 task directory를 archive로 이동한다.