# Milestone: Roadmap Driven Agent-Ops Automation

## 위치

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

## 목표

NomadCode가 로드맵을 중심으로 사용자 입력, 실행 상태, 출력 검토, 완료 승인까지 한 흐름에서 운영하도록 Roadmap Operations Control Plane의 방향을 정한다. Plane/Jira 같은 work item provider는 사용자가 작업 상태를 움직이는 primary control UI가 될 수 있으며, NomadCode Core는 provider command와 agent-roadmap 변경을 같은 sync domain에서 검증해 Milestone item과 work item이 동일한 구조로 수렴하도록 한다. agent-roadmap은 장기 원장으로 유지하고, agent-ops 스킬은 문서 작성, 의미 해석, 변경 제안 계층으로 낮춘다. 외부 agent 제어 표면은 이 마일스톤의 확정 범위가 아니며 후속 스케치에서 별도로 검토한다.

## 상태

[완료]

## 승격 조건

- 없음

## 구현 잠금

- 상태: 해제
- SDD: 불필요 - 상위 방향과 계약 정리용 문서 마일스톤이며, 기능 Task의 문서/계약 산출물 검증으로 닫는다.
- 결정 필요: 없음

## 범위

- NomadCode Core가 품을 roadmap/action core 책임 정의
- HTTP API, provider webhook, internal integration의 역할 경계 정의
- 사용자 입력, 출력 검토, 승인, 보완, archive 확인을 NomadCode 라인에서 처리하는 흐름 정의
- Plane 상위 티켓 1개를 Milestone 1개로 보고, Plane 하위 티켓을 Milestone 기능 Task로 투영하는 사용자 플로우 계약 정의
- Plane/Jira 같은 provider work item과 agent-roadmap Milestone item 사이의 양방향 동기화 도메인 책임, 변경 감지, 수렴 정책 정의
- Plane/Jira provider project 단위로 sync를 묶고 provider project target, git remote, 실제 작업 workspace 설정을 Core DB 모델로 관리하는 기준 정의
- Plane-origin authoring에서 workspace agent를 IOP CLI 1차 통로로 실행하는 기준 정의
- Plane 상태 `Backlog`, `Todo`, `In Progress`, `User Review`, `Done`, `Cancelled`를 roadmap/agent-task lifecycle command로 해석하는 기준 정의
- `Backlog + AGENT assignee`에서 Milestone 초안을 작성하고 Plane 티켓을 `Todo` 검토 상태로 옮긴 뒤, 사용자가 `In Progress`로 옮길 때 실제 실행과 하위 티켓 생성을 시작하는 gate 정의
- agent-ops roadmap skills를 작성/제안 계층으로 낮추는 방향 정의
- completion event, `USER_REVIEW.md`, 완료 리뷰, dependency lock을 Core action으로 다루는 기준 정의

## 기능

### Epic: [control-plane] Roadmap operations control plane

NomadCode 내부 core logic이 roadmap 기반 작업 운영을 소유하고, provider/UI/agent 입력을 검증 가능한 Core action으로 수렴시키는 구조를 정리한다.

- [x] [core-state] roadmap, Phase, Milestone, plan, code-review, completion event, approval 상태를 Core가 다루는 state model과 revision/idempotency 계약으로 정리한다.
- [x] [core-actions] validate, position, propose/apply change, transition, archive, dependency check, completion event ingest를 Core action 후보로 정의한다.
- [x] [http-role] HTTP API는 Flutter UI, webhook, internal integration용 표면으로 유지하고, 실행 side effect는 Core action의 revision/idempotency 계약을 거치도록 하는 기준을 정한다.
- [x] [review-gates] 사용자 입력, 출력 검토, `USER_REVIEW.md`, 완료 승인, archive 승인을 NomadCode workflow 안의 review gate로 처리하는 흐름을 정한다.
- [x] [plane-control-flow] Plane을 primary control UI로 쓰는 lifecycle을 정리한다. 검증: `Backlog + AGENT assignee -> Todo -> In Progress -> User Review -> Done/Cancelled` 상태가 Milestone 초안, 사용자 검토, 실행 시작, 사용자 검토, 완료/archive 또는 폐기로 어떻게 연결되는지 문서에서 일관되게 읽힌다.
- [x] [plane-identity] Plane 상위 티켓을 Milestone, 하위 티켓을 Milestone 기능 Task로 매핑하는 id 계약을 정한다. 검증: Milestone id는 파일명으로 유지하고, Plane work item id는 외부 provider id로 보존하는 기준이 명확하다.
- [x] [todo-draft-gate] `Backlog + AGENT assignee`를 Milestone 초안 생성/갱신 trigger로 정의하고, `develop` branch의 agent-roadmap에 반영된 뒤 Plane 티켓을 `Todo`로 이동하는 gate를 정한다. 검증: Todo 진입은 자동 실행이 아니라 `develop`에 존재하는 Milestone의 사용자 검토 단계임이 명확하다.
- [x] [in-progress-exec-gate] 사용자가 Plane 상위 티켓을 `In Progress`로 옮길 때 실제 실행과 하위 티켓 전환을 시작하는 기준을 정한다. 검증: Milestone Task가 Plane 하위 티켓으로 생성되고 plan/code-review 루프로 들어가는 시점이 명확하다.
- [x] [cancelled-discard] 사용자가 Plane 상위 티켓을 `Cancelled`로 옮길 때 Milestone 초안 폐기 또는 보류를 처리하는 기준을 정한다. 검증: Plane 폐기 상태가 agent-roadmap의 `[폐기]` 또는 `[보류]` 중 어느 상태로 연결되는지와 사용자 승인 없는 archive 이동 금지가 설명된다.
- [x] [child-task-review-policy] Milestone에서 만들어진 하위 작업은 막혔을 때만 `User Review`로 보내고, 정상 PASS 시 기본적으로 `Done`으로 보내는 정책을 정한다. 검증: 하위 작업의 기본 완료 흐름과 blocker review 흐름이 구분된다.
- [x] [milestone-review-loop] 모든 하위 작업이 완료되면 상위 Milestone 티켓을 `User Review`로 보내고, 사용자가 `Done`으로 옮기면 완료/archive, `Todo`로 되돌리면 보완 루프로 처리하는 기준을 정한다.
- [x] [first-slice] 첫 구현 단위를 `roadmap.validate`, `roadmap.get_position`, `roadmap.ingest_completion_event` 중 어떤 순서로 자를지 정한다.

### Epic: [sync-domain] Milestone/work item sync domain

Plane/Jira 같은 provider work item과 agent-roadmap Milestone item을 동일한 작업 구조로 유지하는 별도 Core sync domain을 정의한다.

- [x] [sync-owner] sync domain의 소유 책임을 정의한다. 검증: provider adapter는 native API read/write만 담당하고, Milestone/work item identity mapping, revision 비교, 수렴 적용은 Core sync domain 책임으로 읽힌다.
- [x] [sync-identity] Milestone, Epic/Task item id, provider work item id, parent-child 관계, provider revision, roadmap revision을 묶는 identity 계약을 정한다. 검증: Plane/Jira 어느 쪽에서 시작해도 같은 Milestone item 구조로 매핑되는 기준이 명확하다.
- [x] [sync-project-config] provider project 단위 sync 설정 모델과 저장 경계를 정한다. 검증: provider project target, git remote URL, source-of-truth branch, workspace id/path가 Core DB에 저장되는 project sync 설정으로 정의되고, 설정 누락 또는 중복 시 생성 동기화를 진행하지 않는 기준이 있다.
- [x] [sync-detection] provider webhook, provider polling, roadmap file/index scan, agent-task completion event를 같은 변경 감지 입력으로 정리한다. 검증: 양쪽 중 어느 쪽에서 변경이 발생해도 sync event로 정규화되는 흐름이 문서화되어 있다.
- [x] [sync-convergence] 한쪽 변경을 다른 쪽에 반영해 Milestone item과 work item이 동일 형태로 수렴하는 apply 정책을 정한다. 검증: 생성, 제목/설명, 상태, parent-child, 완료/검토 흐름이 양방향으로 어떻게 반영되는지 설명된다.
- [x] [sync-conflict] 동시 수정, revision mismatch, 삭제/archive, 사용자 승인 필요 변경의 conflict 처리 정책을 정한다. 검증: Core가 조용히 덮어쓰지 않고 review gate 또는 dry-run proposal로 멈추는 기준이 있다.
- [x] [sync-schedule] sync domain의 scheduler 책임을 정한다. 검증: webhook이 없는 provider나 누락 이벤트를 주기 polling으로 보정하고, 같은 idempotency/revision 계약을 쓰는 방향이 명확하다.
- [x] [sync-contract] `packages/contracts`에 sync event/action 후보를 남긴다. 검증: `roadmap_sync.inspect`, `roadmap_sync.apply`, `roadmap_sync.changed` 같은 후보 표면과 필수 입력 필드가 compatibility note에 정리되어 있다.
- [x] [plane-origin-flow] Plane-origin Milestone 생성 시나리오를 정한다. 검증: Backlog 티켓 본문을 입력으로 IOP CLI 1차 통로를 통해 실행된 workspace agent가 같은 Milestone 파일 작성/push 경로에서 roadmap skill로 Milestone 초안을 만들고, `develop` 반영 후 sync layer가 pushed Milestone의 provider/work item identity를 검증한 뒤 원본 본문은 `사용자 요청:` 댓글로 보존하며, Plane 본문은 `develop`의 Milestone 내용으로 치환하고, 제목은 `[milestone-id] 제목` 형식으로 바꾼 뒤 Todo로 이동하는 순서가 문서화되어 있다.
- [x] [agent-origin-flow] Agent-origin Milestone 생성 시나리오를 정한다. 검증: 에이전트 대화로 생성된 Milestone이 `develop` branch에 반영되었을 때 Plane parent ticket을 Todo 상태로 생성하고 identity map을 연결하는 흐름이 문서화되어 있다.
- [x] [sync-idempotency] Plane-origin과 Agent-origin 생성의 중복 방지와 부분 실패 복구 정책을 정한다. 검증: 같은 Plane 티켓 또는 같은 Milestone path가 재처리되어도 중복 Milestone/티켓을 만들지 않고, 댓글 보존/본문 치환/제목 변경/상태 이동 중 실패한 단계를 재시도할 수 있다.

## 완료 리뷰

- 상태: 통과
- 요청일: 2026-06-23
- 완료 근거: Roadmap Operations Control Plane과 Milestone/work item sync domain의 상위 계약 후보가 `packages/contracts/notes/flutter-core-api-candidates.md`에 compatibility note로 정리되었고, 관련 core sync 경계 테스트가 통과했다. 이 문서의 기능 Task가 모두 충족되었고, 구현 잠금은 해제 상태이며 SDD는 불필요로 판정되어 있다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 2026-06-23 코드 레벨 종료 검토에서 stale README 표현을 보정했고, 관련 core packages 테스트와 문서 diff 검증이 통과해 archive했다.

## 범위 제외

- IOP 내부 모델 라우팅, output validation, RAG, context compression 구현
- 외부 agent 제어 표면과 tool policy 확정 또는 구현
- 전체 Flutter UI 구현
- Project sync 설정 관리 UI/UX 실제 구현
- Plane/Jira/Mattermost provider projection 세부 구현, Plane webhook/하위 티켓 생성 adapter 실제 구현. 단, Milestone/work item sync domain의 provider-neutral 책임과 계약 후보 정의는 포함한다.
- 사용자 승인 없는 자동 archive 이동
- agentic-framework 공통 스킬의 실제 개편

## 작업 컨텍스트

- 관련 경로: `services/core/internal/workflow/`, `services/core/internal/scheduler/`, `services/core/internal/http/`, `services/core/internal/workitem/`, `services/core/internal/db/`, `services/core/migrations/`, `services/core/queries/`, `packages/contracts/`, `agent-roadmap/`, `agent-ops/skills/common/update-roadmap/SKILL.md`, `agent-ops/skills/common/plan/SKILL.md`, `agent-ops/skills/common/code-review/SKILL.md`
- 표준선(선택): `develop` branch의 `agent-roadmap`을 Milestone sync의 source of truth로 둔다. Plane/Jira 같은 work item provider는 사용자의 primary control UI와 projection 표면이 될 수 있고, provider 상태 변화와 agent-roadmap 변경은 NomadCode Core sync domain이 검증해 실행하는 command로 본다. NomadCode Core는 roadmap/action side effect, Milestone/work item identity mapping, idempotency/revision 검증, conflict review gate를 소유하고, agent-ops 스킬은 사용자의 자연어와 문서 초안을 Core action 제안 입력으로 정리한다.
- 프로젝트 설정 기준: Sync는 Plane/Jira provider project 단위로 묶으며, 각 project sync 설정은 provider project target, git remote URL, source-of-truth branch, 실제 작업 workspace를 Core DB에 저장한다. 이 설정은 이후 Project settings UI/UX에서 확인/수정할 수 있어야 한다.
- 로컬 제어 표면 후보: `http://127.0.0.1:8080/v1`
- 선행 작업: Workflow Core, External Integration, Project Workspace Management UX, 로드맵 스킬 운영 복잡도 평가
- 후속 작업: `Milestone Execution Lifecycle Sync`, 외부 agent 제어 표면 스케치
- 현재 지점: 이 Phase의 `Milestone Work Item Creation Sync`, `Plane Work Item Webhook Intake`, Gito branch/webhook wakeup 연동은 완료되어 archive에 남아 있다. 이 마일스톤은 roadmap/action core 책임과 Milestone/work item sync domain을 구현 가능한 Core action 후보로 정리하는 상위 설계/계약 문서이며, Milestone/work item sync domain의 후보 계약은 `packages/contracts/notes/flutter-core-api-candidates.md`까지 반영되어 있다.
- 완료 체크 근거:
  - `[plane-control-flow]`, `[plane-identity]`, `[todo-draft-gate]`, `[plane-origin-flow]`: Phase 흐름에 완료로 남은 `Milestone Work Item Creation Sync`와 `Plane Work Item Webhook Intake`가 Plane-origin Milestone 작성, Todo projection, provider identity 보존, Backlog+AGENT webhook intake까지 닫은 근거다.
  - `[in-progress-exec-gate]`, `[cancelled-discard]`, `[child-task-review-policy]`, `[milestone-review-loop]`: 이 문서의 Plane 제어 플로우가 `Todo -> In Progress -> User Review -> Done/Cancelled` 이후 실행 시작, 하위 티켓 기본 완료/차단 리뷰, 상위 Milestone 완료/보완/폐기 루프를 설명한다.
  - `[sync-owner]`: 현재 문서의 동기화 도메인 방향이 provider adapter와 Core sync domain 책임을 분리하고, 완료된 Plane/Gito sync slice가 이 경계를 따라 구현되어 있다.
  - `[sync-project-config]`: project sync 설정 기준이 현재 문서에 남아 있고, Core 내부 경로 `services/core/internal/projectsync/`, `services/core/internal/roadmapsync/`, `services/core/internal/roadmapsyncpipeline/`가 provider project target, repository, workspace 기반 동기화 경계를 구현한다.
  - `[core-state]`, `[core-actions]`, `[http-role]`, `[review-gates]`, `[first-slice]`: `packages/contracts/notes/flutter-core-api-candidates.md`의 `Roadmap Operations Control Plane 계약 후보`가 roadmap state model, `roadmap.validate/get_position/propose_change/apply_change/transition/archive/dependency_check/ingest_completion_event`, HTTP wrapper 원칙, review gate, 첫 구현 순서를 compatibility note로 정리한다.
  - `[sync-identity]`, `[sync-detection]`, `[sync-convergence]`, `[sync-conflict]`, `[sync-schedule]`, `[sync-contract]`: `packages/contracts/notes/flutter-core-api-candidates.md`의 `Roadmap / Work Item Sync 계약 후보`가 identity field, `roadmap_sync.changed`, `roadmap_sync.inspect/apply/reconcile`, convergence, conflict, polling 보정 기준을 compatibility note로 정리한다.
  - `[agent-origin-flow]`, `[sync-idempotency]`: 이 문서의 Agent-origin 생성 플로우와 시나리오 점검, contracts note의 idempotency/revision 원칙이 develop 반영 후 Plane Todo 생성, identity map 연결, 중복 적용 방지, 단계별 재시도 경계를 설명한다.
- 실행 경계: 이 마일스톤은 상위 방향과 계약 정리용이다. 실제 구현은 `Milestone Work Item Creation Sync`부터 진행하고, `Milestone Execution Lifecycle Sync`는 사용자가 해제할 때까지 잠근다.
- 동기화 도메인 방향:
  - Sync domain은 provider adapter보다 위에 위치하며, provider native DTO를 직접 소유하지 않는다.
  - Sync domain의 Milestone source of truth는 `develop` branch의 `agent-roadmap`이다. Plane/Jira work item은 intake/projection/review UI로 본다.
  - Sync domain은 provider project 단위 project sync 설정을 먼저 해석한 뒤 git repository와 workspace를 선택한다.
  - Plane-origin authoring은 IOP CLI 1차 통로로 workspace agent를 실행하며, 이 통로가 없으면 Plane authoring 단계는 잠긴다.
  - Sync domain은 `Milestone <-> provider parent work item`, `Milestone Task <-> provider child work item` 관계를 같은 identity map으로 관리한다.
  - 변경 감지는 provider webhook을 우선하되, 누락/미지원 provider는 scheduler polling으로 보정한다.
  - agent-roadmap 문서 변경, provider work item 변경, agent-task completion event는 모두 같은 provider-neutral sync event로 정규화한다.
  - 양쪽 변경이 충돌하면 조용히 덮어쓰지 않고 expected revision mismatch로 멈춘 뒤 사용자 review gate 또는 dry-run proposal로 올린다.
- 용어 경계: Plane `User Review`는 provider board state이고, agent-task `USER_REVIEW.md`는 자동 plan/code-review 루프를 멈추는 내부 stop artifact다. 둘은 모두 사용자 판단 신호지만 저장 위치와 트리거가 다르다.
- Plane 제어 플로우:
  - `Backlog`: 사용자가 해야 할 일을 Plane 상위 티켓으로 작성하는 아이디어/요청 상태다.
  - `Backlog + AGENT assignee`: 실제 등록된 agent user에게 티켓이 할당되면 NomadCode가 Plane 티켓 본문을 읽고, project sync 설정으로 선택한 workspace slot 안에서 IOP CLI 1차 통로로 workspace agent를 실행해 roadmap skill로 Milestone 파일을 생성하거나 갱신한다.
  - Milestone 초안 생성 후: NomadCode는 Plane 티켓 본문을 기반으로 workspace agent가 Milestone 파일을 만들게 하되, `develop` branch의 agent-roadmap에 commit/push되기 전까지 Plane `Todo` projection 대상으로 보지 않는다.
  - `develop` 반영 후: NomadCode는 원본 사용자 본문을 Plane 댓글에 `사용자 요청:` prefix로 보존하고, Plane 본문을 `develop`에 반영된 Milestone 내용으로 치환하며, 제목을 `[milestone-id] 제목` 형식으로 바꾼 뒤 티켓을 `Todo`로 옮긴다. 여기서 `milestone-id`는 `develop`의 Milestone 파일 slug를 기본값으로 쓴다.
  - `Todo`: 사용자가 `develop`에 존재하는 Milestone 내용을 Plane에서 검토하는 상태다. 자동 실행 gate가 아니며, 사용자는 작업 착수 시 `In Progress`, 폐기 시 `Cancelled`로 옮긴다.
  - `In Progress`: 사용자가 Milestone 초안을 검토한 뒤 실행을 승인한 상태다. NomadCode는 Milestone 기능 Task를 Plane 하위 티켓으로 전환하고 `agent-task/m-<milestone-id>` plan/code-review 루프를 시작한다.
  - 하위 티켓: Milestone에서 만들어진 작업은 정상 PASS 시 기본적으로 `Done`으로 이동한다. 작업 중 사용자 결정, 외부 환경, 범위 충돌처럼 자동 진행이 막힐 때만 `User Review`로 이동한다.
  - `User Review`: 상위 Milestone 티켓은 모든 하위 작업이 완료되었거나 사용자 판단이 필요한 경우 이동한다. 사용자가 `Done`으로 옮기면 `[완료]`와 archive를 수행하고, `Todo`로 되돌리면 내부 Milestone을 `[진행중]`/보완 필요로 되돌려 추가 요구사항을 반영하는 루프로 처리한다.
  - `Done`: 사용자 최종 완료 승인이다.
  - `Cancelled`: 기본적으로 폐기 후보 루트이며, 일시 중단으로 해석해야 하는 경우에는 `[보류]` 후보로 사용자 review gate에 올린다. archive 이동은 사용자의 명시 승인 전에는 수행하지 않는다.
- Agent-origin 생성 플로우:
  - 에이전트와의 대화 중 사용자가 Milestone 생성을 요청하면 현재 roadmap 규칙에 따라 프로젝트 안에 Milestone 문서를 만든다.
  - 생성된 Milestone이 `develop` branch에 반영되면 sync domain은 해당 Milestone을 Plane 상위 티켓으로 생성하고 `Todo` 상태에 둔다.
  - Plane 티켓 제목은 `[milestone-id] 제목` 형식을 사용하고, 본문은 Milestone 내용으로 채우며, identity map에는 Milestone path와 Plane work item id를 함께 저장한다. 여기서 `milestone-id`는 Milestone 파일 slug를 기본값으로 쓴다.
- 시나리오 점검:
  - Agent user assignment가 trigger이므로 NomadCode가 자기 자신이 만든 상태/본문 변경을 다시 trigger로 오인하지 않도록 actor guard와 idempotency key가 필요하다.
  - 원본 본문을 댓글로 보존한 뒤 본문을 치환하므로, 댓글 생성 실패 후 본문 치환이 진행되지 않게 단계별 apply 순서와 재시도 정책이 필요하다.
  - Plane-origin은 별도 구조화 응답을 받아 적용하는 방식이 아니라, IDE-origin과 같은 workspace agent 파일 작성 및 push 경로를 사용한다.
  - Plane `Todo` 이동은 workspace agent 실행 직후가 아니라 `develop` push 완료를 sync layer가 감지한 뒤 수행한다.
  - Sync layer는 push 성공만으로 Plane을 갱신하지 않고, pushed Milestone의 provider/work item identity가 원래 Plane 티켓과 매칭되는지 확인한다.
  - `[milestone-id] 제목`의 milestone id는 `develop`의 Milestone 파일 slug를 기본값으로 고정한다. 제목 변경만으로 identity를 추적하지 않는다.
  - Agent-origin sync는 feature branch 초안이 아니라 `develop` branch에 반영된 Milestone만 Plane에 Todo 티켓으로 만든다.
  - Plane-origin과 Agent-origin 모두 project sync 설정을 통해 provider project, git repository, workspace를 확정하며, 설정이 없거나 둘 이상이면 생성 동기화를 멈추고 사용자 설정 또는 운영자 조치를 요구한다.
  - Cancelled는 사용자 폐기 신호지만 archive 이동은 사용자 승인 경계를 지켜야 하므로, 우선 `[폐기]` 후보 또는 review gate로 처리한다.
- 남은 작업: 없음.
- 확인 필요: 없음
