# Milestone: Milestone Work Item Creation Sync

## 위치

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

## 목표

Plane-origin 경로로 Milestone을 생성하고, `develop` branch의 agent-roadmap Milestone을 source of truth로 삼아 Plane 상위 티켓과 같은 identity로 연결해 `Todo` 검토 상태까지 동기화한다. 이 마일스톤의 완료 지점은 사용자가 Plane Todo에서 `develop`에 반영된 Milestone 내용을 검토할 수 있는 상태이며, 여기서 멈춘다.

## 상태

[완료]

## 구현 잠금

- 상태: 해제
- 결정 필요: 없음
- 부분 잠금: 없음

## 범위

- Plane `Backlog + AGENT assignee` 상위 티켓을 Milestone 생성 trigger로 처리하는 흐름
- Plane project 단위 sync 설정 모델과 DB 저장 흐름
- Plane project 대상, git remote, 실제 작업 workspace를 project sync 기본 설정으로 관리하는 흐름
- NomadCode host 기준 workspace base path, repo별 project workspace root, `branches/main`, `branches/develop`, `slots/000+` 기반 workspace layout 정의
- 고정 branch workspace인 `branches/develop`과 `branches/main`을 항상 유지하되 agent authoring 쓰기 작업에는 배정하지 않는 흐름
- `branches/develop`은 roadmap source-of-truth scan, 테스트 동기화, Plane `Todo` projection 기준으로 사용하고, `branches/main`은 release/promote 기준으로 사용하는 흐름
- Workspace slot의 사용중 상태를 확인하고 비어 있는 slot만 병렬 작업에 할당하는 흐름
- 안정성을 우선해 slot별 독립 git checkout을 기본으로 두는 흐름
- Plane 티켓 원본 본문을 `사용자 요청:` 댓글로 보존하는 흐름
- `develop` branch의 agent-roadmap Milestone을 source of truth로 삼는 흐름
- Milestone sync 확정 시점을 `develop` branch commit/push 완료로 보는 흐름
- `develop` push 완료를 sync layer가 감지한 뒤 Plane 티켓을 갱신하고 `Todo`로 이동하는 흐름
- `develop`에 반영된 Milestone을 기준으로 Plane 본문을 Milestone 내용으로 치환하는 흐름
- Plane 제목을 `[milestone-id] 제목` 형식으로 바꾸고 `Todo`로 이동하는 흐름. 여기서 `milestone-id`는 `develop`의 Milestone 파일 slug를 기본값으로 쓴다.
- Plane 티켓 제목/본문을 입력으로 workspace agent가 Milestone 파일을 직접 작성하고 `develop`에 push하는 authoring 경계
- Workspace agent authoring run을 IOP Edge OpenAI-compatible HTTP로 실행하는 1차 통로와 실행 가능 여부 잠금 기준
- Plane 티켓과 pushed Milestone을 연결하는 provider/work item identity 매칭 기준
- Authoring run의 최소 실행 상태와 stale/failed 판단 기준
- Pushed commit에서 실제 Milestone 파일 변경과 Plane ticket identity를 검증한 뒤 Plane을 갱신하는 기준
- Milestone path와 Plane work item id의 identity map, Plane work item id 기반 idempotency, actor guard, 부분 실패 재시도 기준

## 기능

### Epic: [plane-nomad-iop-cycle] Plane-NomadCode-IOP One Cycle

Plane `Backlog + AGENT assignee` 상위 티켓 하나가 NomadCode project sync와 IOP Edge HTTP workspace agent 실행을 거쳐 `develop` source-of-truth에 Milestone 산출물을 만들고, 다시 Plane `Todo` 검토 상태로 투영되는 한 사이클을 최상위 실행 흐름으로 둔다.

- [x] [cycle-project-config] Plane project target, git remote, source-of-truth branch, workspace base/repo 설정을 project sync 기준으로 해석할 수 있다. 검증: `[project-config]` Epic의 완료 근거와 `workitempipeline` project binding/slot metadata 연결로 확인했다.
- [x] [cycle-workspace-topology] project workspace root 아래 `branches/main`, `branches/develop`, `slots/000+` 구조를 준비하고 branch workspace와 agent slot 상태를 분리한다. 검증: `branches/develop`은 source-of-truth scan 기준, `branches/main`은 release/promote 기준, `slots/<index>`는 authoring 쓰기 작업 기준으로만 사용된다.
- [x] [cycle-iop-http-ready] IOP Edge OpenAI-compatible HTTP(`/v1/responses`) workspace agent 실행 통로를 선행 조건으로 확인한다. 검증: NomadCode가 IOP CLI를 직접 실행하지 않고, `model`, `input`, `metadata.workspace` 요청만으로 workspace-bound agent target을 실행할 수 있다.
- [x] [cycle-authoring-run] Plane 티켓 제목/본문과 provider work item identity를 입력으로 `slots/<index>` workspace에서 1회 authoring run을 실행한다. 검증: agent가 slot 안에서 Milestone 파일을 작성/갱신하고 `develop`에 commit/push한다.
- [x] [cycle-develop-sync] sync layer가 `branches/develop` 또는 remote `develop`에서 pushed Milestone을 감지하고 원래 Plane 티켓 identity와 매칭한다. 검증: slot local 변경이나 push 실패 상태만으로 Plane `Todo` projection을 수행하지 않는다.
- [x] [cycle-plane-todo] 원본 Plane 본문을 `사용자 요청:` 댓글로 보존하고, `develop`의 Milestone 내용으로 Plane 본문/제목을 갱신한 뒤 `Todo`로 이동한다. 검증: 사용자에게 Plane Todo에서 `develop` 반영 결과를 검토할 수 있는 상태가 된다.
- [x] [cycle-idempotency] 같은 Plane 티켓 또는 같은 Milestone path 재처리 시 중복 생성 없이 남은 단계만 재시도한다. 검증: identity map, actor guard, provider revision, roadmap revision 기준으로 부분 실패를 복구한다.

### Epic: [project-config] Project sync configuration

Plane project 단위로 Milestone sync에 필요한 기본 설정을 저장하고 이후 UI/UX가 소비할 project settings 경계를 만든다.

- [x] [project-model] Plane project 단위 sync 설정 모델을 정의한다. 검증: 설정 모델이 provider project target, git remote URL, source-of-truth branch, workspace id/path를 필수 필드로 갖는다.
- [x] [project-store] Project sync 설정을 Core DB에 저장하는 persistence 경계를 정한다. 검증: Plane project별로 하나의 active sync 설정을 찾을 수 있고, Milestone 생성 동기화가 이 설정 없이는 진행되지 않는 기준이 문서화되어 있다.
- [x] [project-bind] Plane-origin 생성 동기화가 project sync 설정을 통해 Plane project, git repository, 작업 workspace를 해석하도록 한다. 검증: 같은 Plane project 안의 티켓은 같은 git/workspace 설정을 사용하며, 다른 Plane project와 섞이지 않는다.
- [x] [workspace-layout] NomadCode host 기준 workspace 경로 규칙의 초기 기준을 정의한다. 검증: `workspace_base_path=/home/user/workspace`, `repo_dir_name=nomadcode`이면 project workspace root는 `/home/user/workspace/nomadcode`이고, 후속 `workspace-topology` Epic에서 고정 branch workspace와 작업 slot 하위 경로를 분리한다.
- [x] [workspace-slot] 병렬 운용을 위한 workspace slot index 모델을 정의한다. 검증: 기본 작업공간은 `000`이고, 병렬 요청이 들어오면 `001`, `002`처럼 3자리 zero-padded index를 증가시키며 각 slot이 독립 작업공간으로 예약된다.
- [x] [workspace-slot-state] Workspace slot의 사용중 상태 모델을 정의한다. 검증: 각 slot은 `available`, `in_use`, `dirty`, `error` 같은 상태 후보를 갖고, 새 작업은 `available` slot만 선택하며, 동시에 들어온 요청이 같은 slot을 잡지 않도록 DB에서 원자적으로 `in_use`로 전환하는 기준이 있다.
- [x] [workspace-checkout] Git repository checkout 정책을 project sync 설정과 연결한다. 검증: git remote는 project sync 설정에서 읽고, 안정성을 우선해 각 slot은 같은 remote의 독립 checkout을 기본으로 확보하며, 일반 단일 운용에서는 `000`만 사용한다.
- [x] [settings-ui] Project sync 설정을 이후 프로젝트 설정 UI/UX에서 관리해야 하는 후보로 남긴다. 검증: 이번 마일스톤에서는 UI 구현을 하지 않고, 후속 Project settings 화면이 provider project target, git remote, workspace를 표시/수정해야 한다는 요구가 남아 있다.

### Epic: [workspace-topology] Branch workspace and slot topology

Project sync workspace를 고정 branch workspace와 agent 작업 slot으로 분리해 source-of-truth scan, 테스트 동기화, release 기준, 병렬 authoring 실행이 서로 섞이지 않도록 한다.

- [x] [branch-workspaces] repo별 project workspace root 아래 `branches/main`과 `branches/develop`을 항상 유지하는 기준을 정의한다. 검증: 두 workspace는 예약 가능한 agent 작업 slot이 아니며, `develop`은 roadmap/test sync 기준, `main`은 release/promote 기준으로만 사용된다.
- [x] [slot-layout] agent authoring 작업공간을 `slots/000`, `slots/001`, `slots/002`처럼 `slots/` 하위 3자리 index로 계산하도록 경로 규칙을 갱신한다. 검증: `workspace_base_path=/home/user/workspace`, `repo_dir_name=nomadcode`이면 `develop` 기준 workspace는 `/home/user/workspace/nomadcode/branches/develop`, 기본 작업 slot은 `/home/user/workspace/nomadcode/slots/000`이다.
- [x] [slot-source-branch] 새 agent slot은 source-of-truth branch인 `develop` 기준으로 checkout/branch 준비를 하되, Plane `Todo` projection은 slot local file이 아니라 `branches/develop` 또는 remote `develop` 반영 여부를 기준으로 판단한다. 검증: slot dirty 상태나 미push 변경만으로 Plane 본문 치환/`Todo` 이동을 하지 않는다.
- [x] [branch-sync-state] branch workspace와 slot workspace의 상태 모델을 분리한다. 검증: branch workspace는 `synced`, `stale`, `error` 같은 sync 상태 후보를 갖고, slot workspace는 기존 `available`, `in_use`, `dirty`, `error` 같은 배정 상태를 유지한다.
- [x] [workspace-provision] project sync 설정 저장 또는 첫 사용 시 `branches/main`, `branches/develop`, 최소 `slots/000`의 checkout 준비 기준을 남긴다. 검증: missing workspace를 조용히 임의 cwd로 대체하지 않고 준비 실패를 명시 오류로 반환한다.

### Epic: [agent-bridge] Workspace agent IOP bridge

Plane-origin sync가 workspace agent를 실행할 수 있도록 IOP Edge OpenAI-compatible HTTP 기반 1차 실행 통로를 선행으로 둔다.

- [x] [iop-http-channel] Core/runtime이 IOP Edge OpenAI-compatible HTTP를 통해 workspace-bound agent authoring run을 시작하는 최소 통로를 정의한다. 검증: `authoring.BuildAuthoringGenerateInput`이 Plane 티켓 본문, provider work item id, slot workspace path를 `model.GenerateInput`으로 만들고, scheduler가 Plane-origin authoring task를 A2A가 아니라 OpenAI-compatible model bridge로 라우팅한다.
- [x] [authoring-state] Workspace agent authoring run의 최소 상태 모델을 정의한다. 검증: 첫 구현은 `in_progress`, `succeeded`, `failed`만 상태로 저장하고, stale/timeout은 별도 상태가 아니라 `updated_at` 기준으로 판정한다.
- [x] [provider-identity] Plane 티켓과 workspace agent 결과를 연결하는 최소 identity를 정의한다. 검증: `ExternalProvider`/`ExternalID` 또는 payload `work_item`의 provider/work item id가 workspace metadata에 남고, pushed Milestone matching은 provider + work item id + Milestone path를 쓰며 별도 `authoring_run_id`를 필수 매칭 키로 쓰지 않는다.
- [x] [agent-run-result] Workspace agent authoring run의 성공/실패 판정 기준을 정의한다. 검증: authoring 성공은 별도 구조화 응답이 아니라 `develop` branch에 Milestone 파일 변경이 commit/push된 상태로 판정하며, sync layer의 Plane work item id 검증은 `pushed-milestone-match` 단계에서 처리한다. 실패는 exit code, push 실패, dirty workspace, 충돌 상태로 구분된다. 계획: `agent-task/m-milestone-work-item-creation-sync/08_agent_run_result_gate/`
- [x] [agent-bridge-lock] Plane authoring 실행 단계의 선행 잠금을 정의한다. 검증: IOP Edge OpenAI-compatible HTTP bridge가 Plane-origin authoring task의 실행 통로가 되었고, authoring 조건이 없거나 workspace checkout metadata가 없으면 일반 실행/준비 흐름으로 남는다.

### Epic: [creation-sync] Milestone creation sync

Plane-origin 생성 경로를 `develop` agent-roadmap 기준의 `Todo` 검토 상태까지 수렴시킨다.

- [x] [plane-trigger] Plane `Backlog + AGENT assignee` 상위 티켓을 Milestone 생성 trigger로 처리한다. 검증: NomadCode가 자신이 만든 후속 변경을 다시 사용자 trigger로 오인하지 않는 actor guard가 설명되어 있다. 계획: `agent-task/m-milestone-work-item-creation-sync/09_creation_trigger_gate/`
- [x] [plane-agent-authoring] Plane 티켓 제목/본문을 workspace agent authoring run의 입력으로 전달하는 경계를 정의한다. 검증: 정상 happy path에서 필수 agent/model 개입은 1회이며, 결과물은 별도 변환 응답이 아니라 `slots/<index>` workspace 안의 `agent-roadmap` Milestone 파일 작성/갱신과 `develop` commit/push다. 이 단계는 IOP Edge OpenAI-compatible HTTP 통로가 준비된 뒤에만 실행된다.
- [x] [plane-draft] Plane 티켓 본문을 읽어 workspace agent가 roadmap skill로 Milestone 초안을 생성하거나 갱신하고 `develop`에 반영한다. 검증: 1상위 티켓은 1마일스톤으로 매핑되고 같은 Plane 티켓 재처리 시 중복 Milestone을 만들지 않는다. 이번 범위는 Plane-origin에 한정하되, Milestone 파일 작성과 push는 IDE-origin과 같은 workspace agent 경로를 쓴다. 계획: `agent-task/m-milestone-work-item-creation-sync/10+09_plane_draft_authoring/`
- [x] [develop-truth] `develop` branch의 agent-roadmap을 sync source of truth로 정의한다. 검증: feature branch나 로컬 초안은 Plane `Todo` projection 대상이 아니며, Plane `Todo` 티켓은 `develop`에 Milestone 변경이 commit/push된 뒤에만 생성/갱신된다.
- [x] [pushed-milestone-match] Sync layer가 pushed commit과 Plane 티켓을 매칭하는 규칙을 정의한다. 검증: pushed commit 또는 roadmap scan에서 실제 `agent-roadmap/phase/*/milestones/*.md` 변경이 있고, 해당 Milestone에 provider와 Plane work item id가 확인될 때만 Plane 갱신 단계로 넘어간다.
- [x] [plane-preserve] 원본 Plane 본문을 `사용자 요청:` 댓글로 보존한 뒤, `develop`에 반영된 Milestone 내용을 기준으로 Plane 본문을 치환한다. 검증: 댓글 보존 실패 시 본문 치환으로 넘어가지 않고, develop 반영 전에는 Todo 이동을 하지 않는다.
- [x] [plane-todo] sync layer가 `develop` push 완료 또는 roadmap scan으로 감지한 Milestone을 기준으로 Plane 제목을 `[milestone-id] 제목` 형식으로 바꾸고 티켓을 `Todo`로 이동한다. 검증: milestone id는 `develop`의 Milestone 파일 slug를 기본값으로 쓰고, 실제 identity는 제목이 아니라 identity map의 Milestone path와 provider work item id로 추적된다.
- [x] [creation-idmap] Milestone path, Milestone id, provider, work item id, provider revision, roadmap revision을 identity map으로 연결한다. 검증: 같은 Plane 티켓 또는 같은 Milestone path가 재처리되어도 같은 Milestone/work item pair를 찾을 수 있다.
- [x] [creation-retry] 생성 동기화의 idempotency와 부분 실패 재시도 정책을 정한다. 검증: develop 반영, 댓글 보존, 본문 치환, 제목 변경, Todo 이동 중 일부만 성공해도 재시도 시 중복 생성 없이 남은 단계만 적용된다.
- [x] [creation-sync-orchestrator] develop Milestone match, identity/step ledger, Plane 원문 보존/본문·제목 갱신/`Todo` 이동을 하나의 runtime sync orchestrator로 연결한다. 검증: provider fake와 store fake 기반 테스트에서 not-ready는 provider 호출 없음, ready는 ledger 단계별 재시도와 Plane projection 순서를 보장한다. 계획: `agent-task/m-milestone-work-item-creation-sync/11_creation_sync_orchestrator/`

### Epic: [live-cycle-gate] Live cycle verification gate

검토 결과, 단위 테스트와 fake provider/store 기반 runtime seam 검증만으로는 이 Milestone의 완료 지점인 Plane `Todo` 검토 상태까지 실제 원격 흐름이 수렴한다고 보기 어렵다. Archive 전에는 최소한 live smoke 또는 runtime-equivalent smoke로 webhook, authoring, develop 반영, Plane projection, slot 회수 경계를 확인한다.

- [x] [live-webhook-task] 원격 dev Plane에서 `Backlog + AGENT assignee` 상위 티켓을 만들거나 갱신하면 webhook만으로 Core task가 생성되고 checkout metadata가 남는다. 검증: Plane webhook log 202, Core task external ref, `checkout.develop_branch_path`/`checkout.slot_path`, workspace slot reservation을 secret redaction 상태로 확인한다.
- [x] [webhook-auto-enqueue] webhook-dispatched creation task가 별도 수동 API 호출 없이 authoring queue로 이어진다. 검증: 같은 Plane work item event에서 task 생성 이후 `queued`/`running` 또는 authoring run 시작 로그가 확인되고, 중복 webhook은 중복 task나 중복 queue를 만들지 않는다.
- [x] [authoring-develop-gate] IOP authoring 응답만으로 task 완료를 단정하지 않고, `develop` Milestone push와 provider identity match가 확인될 때 authoring 성공 또는 sync-ready로 판정된다. 검증: model response-only, slot-local dirty, push 실패는 Plane `Todo` projection으로 넘어가지 않고, `develop` match가 있을 때만 다음 단계로 수렴한다.
- [x] [live-creation-projection] matched develop scan/job 입력이 `roadmapsyncpipeline.Service`와 `RoadmapCreationSyncWorker`를 통해 실제 Plane 원문 댓글 보존, 본문/제목 갱신, `Todo` 이동으로 수렴한다. 검증: `roadmap_sync_steps`에 `develop_matched`, `original_comment_preserved`, `plane_body_updated`, `plane_todo_moved`가 기록되고 Plane UI에서 `Todo` 상태와 `[milestone-id]` 제목을 확인한다.
- [x] [slot-terminal-state] authoring 또는 projection이 terminal outcome에 도달하면 reserved workspace slot이 정책에 따라 `available`, `dirty`, `error` 중 하나로 전환된다. 검증: 성공 smoke 이후 다음 Plane-origin smoke가 수동 DB reset 없이 slot을 확보할 수 있고, 실패 smoke는 원인에 맞는 slot state를 남긴다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-06-16
- 보완 전 완료 근거:
  - `agent-task/archive/2026/06/m-milestone-work-item-creation-sync/11_creation_sync_orchestrator/complete.log`의 `Roadmap Completion` 근거로 `[creation-sync-orchestrator]`를 완료 처리했다.
  - 검증 근거는 `roadmapsyncpipeline.Service`의 develop match -> identity/step ledger -> Plane projection 연결, optional `RoadmapCreationSyncWorker`, `EnqueueRoadmapCreationSync` seam, `cd services/core && go test -count=1 ./...`, `cd services/core && go vet ./...`, `git diff --check` PASS다.
  - Gito proto-socket `branch.updated` backend bridge는 후속 `Gito Branch Event Creation Sync Bridge` Milestone으로 분리했다.
- 보완 완료 근거:
  - `agent-task/archive/2026/06/m-milestone-work-item-creation-sync/12+11_authoring_develop_gate/complete.log`의 `Roadmap Completion` 근거로 `[authoring-develop-gate]`를 완료 처리했다.
  - `agent-task/archive/2026/06/m-milestone-work-item-creation-sync/13+12_slot_terminal_state/complete.log`의 `Roadmap Completion` 근거로 `[slot-terminal-state]`를 완료 처리했다.
  - `agent-task/archive/2026/06/m-milestone-work-item-creation-sync/14+12,13_live_cycle_smoke/complete.log`의 `Roadmap Completion` 근거로 `[live-webhook-task]`, `[webhook-auto-enqueue]`, `[live-creation-projection]`을 완료 처리했다.
- 리뷰 필요:
  - [x] `creation-sync-orchestrator` 계획이 PASS되고 runtime caller가 검증되었다
  - [x] `[live-cycle-gate]` 보완 Task가 live smoke 또는 runtime-equivalent smoke evidence로 완료되었다
  - [x] 사용자가 보완 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 기존 unit/fake 기반 완료 근거에 12/13/14번 task group의 PASS 근거가 더해져 기능 Task와 보완 Task가 모두 완료되었다. 사용자 승인에 따라 Milestone을 `[완료]`로 전환하고 archive했다.

## 범위 제외

- Gito `/proto-socket`의 `branch.updated`를 NomadCode core가 구독하고 target branch를 재검증/스캔해 creation sync job을 enqueue하는 backend bridge 구현. 이 범위는 후속 `Gito Branch Event Creation Sync Bridge` Milestone으로 분리한다.
- Plane `Todo -> In Progress` 실행 시작
- Milestone Task를 Plane 하위 티켓으로 생성하거나 동기화하는 구현
- `agent-task/m-<milestone-id>` plan/code-review 실행 lifecycle
- 상위 티켓 `User Review`, `Done`, `Cancelled` 완료/폐기 처리
- 에이전트 챗 또는 IDE-origin Milestone 생성 후 Plane `Todo`로 projection하는 흐름
- Project sync 설정 관리 UI/UX 구현
- 사용자 승인 없는 archive 이동

## 작업 컨텍스트

- 관련 경로: `services/core/internal/workitem/`, `services/core/internal/scheduler/`, `services/core/internal/http/`, `services/core/internal/db/`, `services/core/migrations/`, `services/core/queries/`, `packages/contracts/`, `agent-roadmap/`
- 선행 작업: Roadmap Driven Agent-Ops Automation의 sync domain 방향 정리
- 후속 작업: `Milestone Execution Lifecycle Sync`
- 후속 분리(2026-06-14): Gito는 Forgejo/webhook 기반 `branch.updated` event producer이고, NomadCode core는 이를 proto-socket으로 소비해 target branch를 재검증/스캔한 뒤 `EnqueueRoadmapCreationSync`를 호출해야 한다. 이 backend consumer/bridge는 `Gito Branch Event Creation Sync Bridge` Milestone으로 분리했다. 현재 `creation-sync-orchestrator` task는 matched scan/job 입력 이후의 orchestrator, worker, enqueue seam을 닫는 범위로 본다.
- 현재 지점: 2026-06-08부터 이 마일스톤을 활성 진행 대상으로 둔다. 우선 Plane-origin Milestone 생성 sync를 `Todo` 검토 상태까지 수렴시키는 범위에서 확인한다.
- Source of truth: `develop` branch의 `agent-roadmap`을 Milestone sync의 source of truth로 둔다. Plane은 이 마일스톤의 intake/projection/review UI이며, agent chat/IDE-origin 생성은 이번 범위에서 제외한다.
- Develop 반영 기준: 이 마일스톤에서 `develop`에 반영되었다는 말은 PR 요청이나 PR 생성이 아니라 `develop` branch에 Milestone 변경 commit/push가 완료된 상태를 뜻한다.
- Agent authoring 기준: Plane-origin 정상 흐름에서 필수 agent/model 개입은 Plane 티켓 제목/본문을 입력으로 `slots/<index>` workspace 안에서 Milestone 파일을 작성/갱신하고 `develop`에 commit/push하는 1회 authoring run이다. 이 단계의 결과물은 별도 응답 구조가 아니라 git에 반영된 roadmap 파일 변경이다.
- IOP 통로 기준: workspace agent authoring run은 IOP Edge OpenAI-compatible HTTP(`/v1/responses`)를 통해 실행하는 것을 1차 통로로 둔다. 이 통로가 준비되기 전에는 Plane authoring 실행 단계가 잠기며, project 설정/branch workspace/slot 준비와 계약 정리까지만 진행한다.
- Runtime 기준: Core/runtime은 project 설정 조회, branch workspace sync, slot 할당, checkout 준비, IOP Edge HTTP 실행 요청, actor guard, identity/idempotency, push 완료 감지, Plane 댓글/본문/제목/status 변경을 결정적으로 처리한다. 이번 범위는 Plane-origin에 한정하되, Milestone 파일 작성과 push는 IDE-origin과 같은 workspace agent 경로를 쓴다.
- Sync layer 기준: Plane `Backlog + AGENT assignee`는 authoring run 시작 trigger이고, Plane `Todo` 이동은 `develop` push 완료가 확인된 뒤 sync layer가 수행한다.
- Matching 기준: sync layer는 push 성공만으로 Plane을 갱신하지 않는다. pushed diff 또는 roadmap scan에서 Milestone 파일 변경을 확인하고, Milestone 작업 컨텍스트의 provider와 Plane work item id가 원래 Plane 티켓과 매칭된 뒤에만 댓글 보존/본문 치환/제목 변경/`Todo` 이동을 수행한다.
- Authoring 상태 기준: 첫 구현에서는 authoring run 상태를 `in_progress`, `succeeded`, `failed`로만 둔다. stale/timeout은 `updated_at`으로 판정하고, 별도 attempt 모델은 만들지 않는다.
- Project 설정: sync는 Plane project 단위로 묶으며, 각 project 설정은 Plane project target, git remote URL, source-of-truth branch, workspace base path, repo dir name을 DB에 저장한다. branch workspace와 slot workspace path는 이 설정에서 파생한다.
- Workspace 경로 기준: workspace base path는 NomadCode host 기준 절대 경로로 해석한다. 예를 들어 `/home/user/workspace`를 base로 두고 git repo 이름이 `nomadcode`이면 project workspace root는 `/home/user/workspace/nomadcode`다.
- Branch workspace 기준: project workspace root 아래 `branches/main`, `branches/develop`을 고정 checkout으로 유지한다. `branches/develop`은 roadmap source-of-truth scan, 테스트 동기화, Plane `Todo` projection 기준이고, `branches/main`은 release/promote 기준이다. 둘 다 agent authoring 작업에 예약하지 않는다.
- Workspace slot 기준: 실제 agent 작업공간은 project workspace root 아래 `slots/000`, `slots/001`, `slots/002` 같은 3자리 slot index로 둔다. 일반 상황에서는 `/home/user/workspace/nomadcode/slots/000` 하나로 운영하고, 병렬 요청이 들어오면 `/home/user/workspace/nomadcode/slots/001`, `/home/user/workspace/nomadcode/slots/002`처럼 늘린다.
- Slot 사용 상태: slot은 Core DB에서 `available` 또는 `in_use` 같은 사용 상태를 추적한다. 여기서 사용 상태는 해당 slot이 현재 작업에 배정되어 다른 병렬 작업이 잡으면 안 되는지를 나타낸다.
- Checkout 기준: 안정성을 우선해 branch workspace와 각 slot은 같은 git remote를 기준으로 독립 checkout을 갖는 작업공간으로 둔다. 초기 workspace 생성 때 clone 비용이 들지만 이후 branch sync와 agent 작업은 각 checkout 안에서 분리되므로 운영 리스크를 낮춘다.
- 후속 UI/UX: project settings 화면에서 Plane project target, git remote, workspace 설정을 확인하고 수정하는 UX가 필요하다.
- 완료 근거(2026-06-07): `[project-config]`는 `services/core/internal/projectsync/`, `services/core/migrations/00004_create_project_sync_settings.sql`, `services/core/migrations/00005_create_workspace_slots.sql`, `services/core/queries/project_sync_settings.sql`, `services/core/queries/workspace_slots.sql`, `packages/contracts/notes/flutter-core-api-candidates.md`의 모델/저장/slot/UI 후보 경계와 테스트로 확인했다. 검증: `cd services/core && go test ./...` PASS.
- 현황 동기화(2026-06-13): `agent-task/archive/2026/06/m-milestone-work-item-creation-sync/*/complete.log`의 `Roadmap Completion` 근거로 `cycle-workspace-topology`, `cycle-iop-http-ready`, `cycle-authoring-run`, `cycle-develop-sync`, `cycle-plane-todo`를 완료 처리했다.
- 현황 동기화(2026-06-14): `agent-task/archive/2026/06/m-milestone-work-item-creation-sync/05+03,04_idempotency_retry/complete.log`의 `Roadmap Completion` 근거로 `cycle-idempotency`를 완료 처리했다. 검증 근거는 identity map의 원자적 conflict 처리, strict retry identity key, `cd services/core && go test -count=1 ./internal/storage ./internal/roadmapsync ./internal/adapters/plane`, `cd services/core && go test ./...`, `git diff --check` PASS다. `./bin/sqlc`는 기존 `queries/workspace_slots.sql:19:11` ambiguity로 차단되어 완료 로그에 별도 기록되어 있다.
- Workspace topology 세부 동기화(2026-06-14): `agent-task/archive/2026/06/m-milestone-work-item-creation-sync/01_workspace_topology/complete.log`, `02+01_workspace_slot_store/complete.log`, `03+01,02_project_binding_checkout/complete.log`, `03+02_develop_match/complete.log`, `04+03_plane_todo_projection/complete.log`와 현재 `projectsync`/`workitempipeline` 테스트 근거로 `[branch-workspaces]`, `[slot-layout]`, `[slot-source-branch]`, `[branch-sync-state]`를 완료 처리했다. `[workspace-provision]`은 실제 first-use checkout 준비 검증과 기본 slot 등록, missing workspace 명시 오류 연결이 남아 `agent-task/m-milestone-work-item-creation-sync/06_workspace_provision/` 및 `agent-task/m-milestone-work-item-creation-sync/07+06_workspace_provision_pipeline/` 계획으로 분리했다.
- Workspace provision pipeline 동기화(2026-06-14): `agent-task/archive/2026/06/m-milestone-work-item-creation-sync/07+06_workspace_provision_pipeline/complete.log`의 `Roadmap Completion` 근거로 `[workspace-provision]`을 완료 처리했다. 검증 근거는 workspace provision hook의 slot 예약/provider fetch/task creation 이전 실행, HTTP binder의 default `slots/000` 등록, `ErrWorkspaceProvisionNotReady` 409 매핑, `cd services/core && go test -count=1 ./internal/projectsync ./internal/workitempipeline ./internal/http`, `cd services/core && go test ./...`, `cd services/core && go vet ./...`, `git diff --check` PASS다.
- Agent bridge 소형 항목 동기화(2026-06-14): 현재 Core 코드의 `authoring.BuildAuthoringGenerateInput`, OpenAI-compatible `/v1/responses` adapter, scheduler authoring route/state metadata, `roadmapsync` identity/develop match 기준을 근거로 `[iop-http-channel]`, `[authoring-state]`, `[provider-identity]`, `[agent-bridge-lock]`을 완료 처리했다. 검증: `cd services/core && go test -count=1 ./internal/authoring ./internal/scheduler ./internal/roadmapsync` PASS. `[agent-run-result]`는 model bridge 응답 성공과 `develop` push 검증 사이의 성공 판정 경계를 보강해야 하므로 `agent-task/m-milestone-work-item-creation-sync/08_agent_run_result_gate/` 계획으로 분리했다.
- Agent run result gate 동기화(2026-06-14): `agent-task/archive/2026/06/m-milestone-work-item-creation-sync/08_agent_run_result_gate/complete.log`의 `Roadmap Completion` 근거로 `[agent-run-result]`를 완료 처리했다. 검증 근거는 `DecideAuthoringResult` helper, authoring failure category metadata, scheduler authoring state 보정, `cd services/core && go test ./...`, `cd services/core && go vet ./...`, `git diff --check` PASS다.
- Creation sync 소형 항목 동기화(2026-06-14): 현재 Core 코드의 `workitem.BuildCreateTaskInput`, `authoring.BuildAuthoringGenerateInput`, scheduler authoring route, `roadmapsync.MatchDevelopMilestone`, `ParseMilestoneIdentity`, `ProjectPlaneTodo`, `FormatPlaneProjection`, roadmap sync identity/step store, `ReconcileCreationCycle` 근거로 `[plane-agent-authoring]`, `[develop-truth]`, `[pushed-milestone-match]`, `[plane-preserve]`, `[plane-todo]`, `[creation-idmap]`, `[creation-retry]`를 완료 처리했다. 검증: `cd services/core && go test -count=1 ./internal/workitem ./internal/workitempipeline ./internal/authoring ./internal/roadmapsync ./internal/adapters/plane ./internal/storage ./internal/http ./internal/scheduler` PASS, `git diff --check` PASS. 당시 남은 `[plane-trigger]`, `[plane-draft]`는 후속 완료 로그 기준으로 아래 현황 동기화에서 닫았다.
- Creation trigger/draft 현황 동기화(2026-06-14): `agent-task/archive/2026/06/m-milestone-work-item-creation-sync/09_creation_trigger_gate/complete.log`의 `Roadmap Completion` 근거로 `[plane-trigger]`를 완료 처리했다. 검증 근거는 ignored trigger를 workspace provision/slot reservation 전에 판정하는 gate, legacy Plane route trigger 전달 테스트, `cd services/core && go test -count=1 ./internal/workitempipeline ./internal/http`, `cd services/core && go test ./...`, `git diff --check` PASS다. `agent-task/archive/2026/06/m-milestone-work-item-creation-sync/10+09_plane_draft_authoring/complete.log`의 `Roadmap Completion` 근거로 `[plane-draft]`를 완료 처리했다. 검증 근거는 full provider identity context 보존, idempotent Milestone draft instructions, scheduler authoring route regression, `cd services/core && go test -count=1 ./internal/authoring ./internal/roadmapsync ./internal/adapters/openai ./internal/scheduler`, `cd services/core && go test -count=1 ./...`, `git diff --check` PASS다.
- 완료 보완 리뷰(2026-06-14): 현재 Core 코드에는 `roadmapsync` helper와 저장소는 있으나 이를 호출해 develop scan 결과를 identity/step ledger와 Plane `Todo` projection에 연결하는 runtime sync orchestrator가 없다. 보완 계획: `agent-task/m-milestone-work-item-creation-sync/11_creation_sync_orchestrator/`.
- Creation sync orchestrator 동기화(2026-06-14): `agent-task/archive/2026/06/m-milestone-work-item-creation-sync/11_creation_sync_orchestrator/complete.log`의 `Roadmap Completion` 근거로 `[creation-sync-orchestrator]`를 완료 처리했다. 검증 근거는 `roadmapsyncpipeline.Service`, optional `RoadmapCreationSyncWorker`, `EnqueueRoadmapCreationSync` seam, `cd services/core && go test -count=1 ./...`, `cd services/core && go vet ./...`, `git diff --check` PASS다.
- 보완 리뷰(2026-06-15): 원격 Core dev 환경은 `healthz`/`readyz`, Plane secret/API env, active project sync 설정, `branches/main`, `branches/develop`, `slots/000`, available slot까지 준비 가능함을 확인했다. 그러나 현재 live로 바로 검증 가능한 범위는 Plane webhook 수신, trigger gate, Core task 생성, checkout metadata 기록까지다. Webhook task 자동 enqueue, authoring result와 `develop` push match의 runtime 연결, Plane `Todo` projection live smoke, slot terminal state 회수는 완료 전 보강 Task로 남긴다.
- 현황 동기화(2026-06-16): `agent-task/archive/2026/06/m-milestone-work-item-creation-sync/12+11_authoring_develop_gate/complete.log`의 `Roadmap Completion` 근거로 `[authoring-develop-gate]`를 완료 처리했다. 검증 근거는 scheduler/workflow/authoring/roadmapsyncpipeline/gitosync focused test, `go test ./...`, `go vet ./...`, `git diff --check` PASS다.
- 현황 동기화(2026-06-16): `agent-task/archive/2026/06/m-milestone-work-item-creation-sync/13+12_slot_terminal_state/complete.log`의 `Roadmap Completion` 근거로 `[slot-terminal-state]`를 완료 처리했다. 검증 근거는 slot terminal policy helper, scheduler/roadmap sync worker finalizer wiring, focused core package tests, `go test ./...`, `go vet ./...`, `git diff --check` PASS다.
- 현황 동기화(2026-06-16): `agent-task/archive/2026/06/m-milestone-work-item-creation-sync/14+12,13_live_cycle_smoke/complete.log`의 `Roadmap Completion` 근거로 `[live-webhook-task]`, `[webhook-auto-enqueue]`, `[live-creation-projection]`을 완료 처리했다. 검증 근거는 live evidence 보강, duplicate/already-complete slot finalization guard, scheduler/workflow/roadmapsyncpipeline tests, `go test ./...`, `git diff --check` PASS다.
- 검토 지점: project sync 설정, workspace topology, IOP Edge HTTP authoring run 경계, authoring run 성공/실패 판정, pushed Milestone identity match, Plane 원문 댓글 보존/본문·제목 갱신/`Todo` 이동 projection, identity map 기반 idempotency/retry, runtime orchestrator 연결, live-cycle gate 보완 Task가 모두 완료 후보가 되었다. 사용자 보완 결과 확인과 archive 승인 전까지 `[검토중]`으로 유지한다.
- 루프 목표: Plane `Backlog + AGENT assignee` -> `slots/<index>` workspace 예약/준비 -> IOP Edge HTTP로 workspace agent authoring run 실행 -> agent가 Milestone 파일 작성/갱신 후 `develop` push -> sync layer가 `branches/develop` 또는 remote `develop`에서 push 완료/roadmap scan을 감지 -> Plane 원문 댓글 보존/본문 치환/제목 변경/`Todo` 이동 -> 사용자가 확인 후 `In Progress`로 이동하는 지점까지 완료 후보로 둔다. `In Progress` 이후 실행은 후속 잠금 범위다.
- 후속 잠금: `Todo -> In Progress` 이후 실행 lifecycle은 사용자가 명시적으로 잠금을 해제할 때까지 진행하지 않는다.
- Plane work item 경계: 이 마일스톤에서 말하는 Plane Milestone은 Plane native milestone object가 아니라 1상위 티켓 = 1 agent-roadmap Milestone으로 보는 work item mapping이다.
- 종료 처리(2026-06-16): 사용자 요청에 따라 Milestone을 `[완료]`로 전환하고 archive했다. 다음 활성 후보는 `Plane Work Item Webhook Intake`로 둔다.
- 확인 필요: 없음
