nomadcode/agent-roadmap/archive/phase/agent-ops-mcp-control-plane/milestones/agent-origin-milestone-creation-sync.md

Milestone: Agent-Origin Milestone Creation Sync

위치

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

목표

agent 또는 사람이 agent-roadmap active Milestone을 직접 수정해 develop에 push한 경우에도 NomadCode가 Gito branch revision을 검증한 뒤 Plane work item을 생성하거나 갱신하고, 생성된 provider identity를 다시 roadmap 파일에 backfill commit으로 남긴다. Plane-origin 흐름과 같은 identity ledger, revision guard, retry/idempotency 기준을 사용해 양방향 생성 동기화의 빈 경로를 닫는다.

상태

[완료]

구현 잠금

• 상태: 해제
• SDD: 필요
• SDD 문서: agent-roadmap/archive/sdd/agent-ops-mcp-control-plane/agent-origin-milestone-creation-sync/SDD.md
• SDD 사유: Gito webhook, Plane provider 쓰기, git identity backfill push, revision/idempotency/identity map을 함께 다루는 sync state machine이다.
• 잠금 해제 조건:
  • SDD 잠금이 해제되어 있다
  • SDD 사용자 리뷰가 없거나 승인/해결되었다
  • Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다
  • Evidence Map이 완료 시 Roadmap Completion과 최종 검증 evidence로 검증 가능하게 연결되어 있다
• 결정 필요: 없음

범위

• Gito branch.updated webhook을 wakeup으로 받아 develop branch의 target revision을 fetch/scan하는 agent-origin sync 경로
• active Milestone 파일 중 provider identity가 없는 신규/변경 Milestone을 Plane work item 생성 대상으로 판별하는 기준
• Plane work item 생성 후 roadmap_sync_identities ledger에 canonical filename slug와 provider work item id를 저장하는 흐름
• 생성된 provider identity block을 원래 Milestone markdown에 backfill하고 별도 commit/push로 develop에 반영하는 흐름
• Core가 만든 identity-only backfill commit이 다시 들어왔을 때 self-loop와 중복 provider mutation을 막는 idempotency guard
• 기존 provider identity가 있는 Milestone 변경은 Plane 본문/제목 갱신으로 수렴하고, identity 충돌/rename/reuse는 conflict로 멈추는 정책

기능

Epic: [agent-origin-sync] Agent-origin Milestone creation sync

agent-origin roadmap push를 Plane work item 생성/갱신과 provider identity backfill까지 수렴시킨다.

• [scan-diff] Gito webhook의 before..after 변경 목록을 wakeup 힌트로 사용하되, after SHA를 fetch/검증한 뒤 active Milestone diff와 전체 active index를 함께 스캔한다. 검증: changed_files만 신뢰하지 않고 origin/develop의 after SHA가 일치할 때만 sync job이 enqueue된다.
• [missing-create] provider identity가 없는 active Milestone을 agent-origin 생성 후보로 판별하고 Plane work item을 생성한다. 검증: 같은 milestone slug와 revision을 재처리해도 중복 Plane work item을 만들지 않는다.
• [identity-ledger] 생성된 Plane work item id를 roadmap_sync_identities에 filename slug 기준으로 upsert하고 revision/idempotency conflict를 구분한다. 검증: 기존 slug가 다른 provider work item에 묶여 있으면 provider mutation 없이 conflict로 멈춘다.
• [identity-backfill] Plane 생성 직후 Milestone markdown에 Provider identity block을 주입하고 Core-authored backfill commit을 develop에 push한다. 검증: backfill commit에는 identity block 외의 unrelated roadmap 변경이 포함되지 않는다.
• [self-loop] Core-authored identity backfill webhook은 provider 생성/갱신을 반복하지 않고 ledger와 markdown identity 일치 여부만 확인한다. 검증: backfill commit 재전달과 Core 재시작 후 재전달 모두 no-op 또는 complete로 수렴한다.
• [identity-update] provider identity가 이미 있는 Milestone의 agent-origin 본문/제목 변경은 Plane 본문/제목 갱신으로 수렴한다. 검증: develop revision guard와 completed-step ledger로 부분 실패를 재시도할 수 있다.
• [conflict-policy] rename, filename slug reuse, provider identity mismatch, stale Plane work item, duplicate active slug를 안전하게 분류한다. 검증: destructive overwrite 없이 conflict/not-ready/skip 결과와 로그가 구분된다.
• [field-smoke] dev 환경에서 agent가 active Milestone을 직접 추가해 push한 뒤 Plane ticket 생성, identity backfill commit, 재전달 no-op까지 확인한다. 검증: secret을 남기지 않은 DB/log/Plane/git evidence가 complete.log에 기록된다.

완료 리뷰

• 상태: 통과
• 요청일: 2026-07-03
• 완료 근거: agent-task/archive/2026/07/m-agent-origin-milestone-creation-sync/ 아래 4개 complete.log의 Roadmap Completion이 S01-S08 Task id와 정확히 일치하고 모두 PASS다.
• 추가 확인: 핵심 파일 sanity pass에서 gitosync changed_files hint scan, roadmapsyncpipeline GitBackfiller/identity_backfilled/self-loop, storage/scheduler retry evidence가 현재 코드와 최근 커밋에 남아 있음을 확인했다.
• 추가 확인: 코드 레벨 종료 감사에서 Scan이 trim 검증한 revision을 실제 git show에도 쓰도록 보강했고, TestScanUsesTrimmedVerifiedRevisionForShow를 추가했다. go test -count=1 ./..., go vet ./... 통과.
• 검토 항목:
  • 모든 기능 Task와 검증이 Roadmap Completion evidence로 충족되었다
  • SDD Evidence Map이 최종 검증 evidence와 일치한다
  • 사용자가 완료 결과를 확인했다
  • archive 이동을 승인했다
• agent-ui 상태 반영: 해당 없음
• 리뷰 코멘트: 종료 차단 항목 없음. 코드 레벨 감사와 최종 검증 통과 후 archive 이동한다.

범위 제외

• Plane Todo -> In Progress 이후 실행 lifecycle과 하위 티켓 생성
• agent-task plan/code-review 결과를 Plane 하위 티켓 상태로 동기화하는 흐름
• MCP control surface와 외부 agent tool permission 정책
• 사용자 승인 없는 자동 archive 이동
• provider native API schema 일반화 또는 Jira 구현

작업 컨텍스트

• 관련 경로: services/core/internal/gitosync/, services/core/internal/roadmapsync/, services/core/internal/roadmapsyncpipeline/, services/core/internal/authoring/, services/core/internal/workitem/, services/core/internal/scheduler/, agent-contract/outer/gito-branch-webhook-consumer-v1.md, agent-roadmap/
• 표준선: Gito webhook은 wakeup signal이며, Plane/roadmap mutation 전에는 반드시 origin/develop의 target SHA를 fetch/scan해 검증한다. filename slug가 canonical milestone id이고, provider identity block은 repo portable anchor로 유지한다.
• 선행 작업: Plane-Origin Authoring Roundtrip Sync, Roadmap Driven Agent-Ops Automation
• 후속 작업: Milestone Execution Lifecycle Sync
• 확인 필요: 없음