# 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이다.
- 잠금 해제 조건:
  - [x] SDD 잠금이 해제되어 있다
  - [x] SDD 사용자 리뷰가 없거나 승인/해결되었다
  - [x] Acceptance Scenario가 Milestone 기능 Task와 연결되어 있다
  - [x] 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까지 수렴시킨다.

- [x] [scan-diff] Gito webhook의 `before..after` 변경 목록을 wakeup 힌트로 사용하되, `after` SHA를 fetch/검증한 뒤 active Milestone diff와 전체 active index를 함께 스캔한다. 검증: `changed_files`만 신뢰하지 않고 `origin/develop`의 `after` SHA가 일치할 때만 sync job이 enqueue된다.
- [x] [missing-create] provider identity가 없는 active Milestone을 agent-origin 생성 후보로 판별하고 Plane work item을 생성한다. 검증: 같은 milestone slug와 revision을 재처리해도 중복 Plane work item을 만들지 않는다.
- [x] [identity-ledger] 생성된 Plane work item id를 `roadmap_sync_identities`에 filename slug 기준으로 upsert하고 revision/idempotency conflict를 구분한다. 검증: 기존 slug가 다른 provider work item에 묶여 있으면 provider mutation 없이 conflict로 멈춘다.
- [x] [identity-backfill] Plane 생성 직후 Milestone markdown에 `Provider identity` block을 주입하고 Core-authored backfill commit을 `develop`에 push한다. 검증: backfill commit에는 identity block 외의 unrelated roadmap 변경이 포함되지 않는다.
- [x] [self-loop] Core-authored identity backfill webhook은 provider 생성/갱신을 반복하지 않고 ledger와 markdown identity 일치 여부만 확인한다. 검증: backfill commit 재전달과 Core 재시작 후 재전달 모두 no-op 또는 complete로 수렴한다.
- [x] [identity-update] provider identity가 이미 있는 Milestone의 agent-origin 본문/제목 변경은 Plane 본문/제목 갱신으로 수렴한다. 검증: `develop` revision guard와 completed-step ledger로 부분 실패를 재시도할 수 있다.
- [x] [conflict-policy] rename, filename slug reuse, provider identity mismatch, stale Plane work item, duplicate active slug를 안전하게 분류한다. 검증: destructive overwrite 없이 conflict/not-ready/skip 결과와 로그가 구분된다.
- [x] [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 ./...` 통과.
- 검토 항목:
  - [x] 모든 기능 Task와 검증이 `Roadmap Completion` evidence로 충족되었다
  - [x] SDD Evidence Map이 최종 검증 evidence와 일치한다
  - [x] 사용자가 완료 결과를 확인했다
  - [x] 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
- 확인 필요: 없음
