update agent-ops roadmap and milestones

agent-ops/roadmap/ROADMAP.md

@@ -19,7 +19,7 @@ NomadCode는 모바일 앱, 웹 콘솔, core 서비스, 공유 계약, agent-ope
 
 ### Work Item Provider Pipeline Design
 
-- [Work Item Provider Pipeline Design](milestones/plane-task-pipeline-design.md) - 상태: 진행 중; 목표: Plane/Jira 등 work item provider와 core task 사이의 생성, enqueue, 상태 투영, 결과 발행 계약을 provider-neutral하게 정리한다.
+- [Work Item Provider Pipeline Design](milestones/plane-task-pipeline-design.md) - 상태: 완료; 목표: Plane/Jira 등 work item provider와 core task 사이의 생성, enqueue, 상태 투영, 결과 발행 계약을 provider-neutral하게 정리한다.
 
 ### Workflow Core
 

agent-ops/roadmap/current.md

@@ -2,7 +2,7 @@
 
 ## 활성 Milestone
 
-- Work Item Provider Pipeline Design: agent-ops/roadmap/milestones/plane-task-pipeline-design.md
+- Workflow Core: agent-ops/roadmap/milestones/workflow-core.md
 
 ## 선택 규칙
 

agent-ops/roadmap/milestones/plane-task-pipeline-design.md

@@ -10,13 +10,12 @@ Work Item Provider Pipeline Design
 
 ## 상태
 
-진행 중
+완료
 
 ## 구현 잠금
 
-- 상태: 잠금
-- 결정 필요:
-  - [ ] generic pipeline service 이후 provider registry/generic endpoint를 별도 작업으로 둘지, compatibility endpoint 유지 상태로 이번 Milestone 범위를 닫을지 결정한다.
+- 상태: 해제
+- 결정 필요: 없음
 
 ## 범위
 
@@ -55,7 +54,7 @@ Work Item Provider Pipeline Design
   - [x] [route-service] `POST /api/integrations/plane/tasks`의 Plane 전용 흐름을 generic pipeline service 아래로 옮긴다.
   - [x] [handler-dto] HTTP handler가 Plane 타입과 직접 결합하지 않도록 요청 DTO와 변환 책임을 분리한다.
   - [x] [task-mapper] `buildPlaneCreateTaskInput`의 core task 생성 로직을 provider-neutral mapper로 분리한다.
-  - [x] [compat-route] 기존 Plane endpoint는 compatibility entrypoint로 유지하거나 generic endpoint로 대체할지 결정한다.
+  - [x] [compat-route] 기존 Plane endpoint는 compatibility entrypoint로 유지하고 generic endpoint/provider registry는 후속 별도 작업으로 분리한다.
 - [x] [projection-contract] provider-neutral 상태와 projection 계약을 확정한다.
   - [x] [board-states] board state는 `backlog`, `todo`, `in_progress`, `testing`, `complete`, `cancel`로 둔다.
   - [x] [agent-metadata] `in_progress` 내부 agent 상태는 core task metadata를 canonical source로 둔다.
@@ -67,26 +66,33 @@ Work Item Provider Pipeline Design
     - [x] [label-map] provider label mapping은 `agent:*`, `phase:*`, `worker:*` 공통 prefix를 우선 사용한다.
     - [x] [label-index] phase label은 작업별 phase index와 맞춰 `phase:0`부터 증가시키고, 최신 phase는 core metadata의 `agent_phase`를 canonical 값으로 둔다.
     - [x] [provider-delta] provider 공통 projection 계약을 먼저 맞추고 Plane/Jira 차이는 adapter별 capability와 mapping 설정으로 분리한다.
-- [ ] [result-policy] 완료/실패 결과의 provider comment/status update 정책을 정한다.
+- [x] [result-policy] 완료/실패 결과의 provider comment/status update 정책을 정한다.
   - [x] [comment-prefix-sample] agent 단계 완료 기록은 prefix와 이모지가 있는 comment로 남기는 방향을 샘플 검증한다.
-  - [ ] [comment-timing] comment prefix 세트와 작성 타이밍을 확정한다.
-- [ ] [idempotency] 중복 생성 방지와 재시도 시 식별 기준을 정한다.
-- [ ] [workflow-handoff] Workflow Core에서 처리할 lifecycle, retry, timeout, notification 요구사항을 정리한다.
+  - [x] [comment-timing] comment prefix 세트와 작성 타이밍을 확정한다.
+- [x] [idempotency] 중복 생성 방지와 재시도 시 식별 기준을 정한다.
+  - [x] [dedupe-key] provider-neutral idempotency key는 `provider`, `tenant`, `project`, `id` 조합으로 둔다.
+  - [x] [active-dedupe] webhook, polling, 수동 entrypoint는 같은 active task가 있으면 새 task를 만들지 않는다.
+  - [x] [retry-attempt] terminal task 이후 재시도는 명시적 retry intent와 `attempt` 증가로 구분한다.
+- [x] [workflow-handoff] Workflow Core에서 처리할 lifecycle, retry, timeout, notification 요구사항을 정리한다.
+  - [x] [lifecycle-owner] task lifecycle, retry, timeout은 Workflow Core 소유로 둔다.
+  - [x] [projection-owner] provider comment/status/label 반영은 workflow 상태 변화의 projection으로 처리한다.
+  - [x] [notification-scope] notification은 core 상태 변화 event 발행까지를 최소 범위로 두고 외부 협업 도구 발송은 후속 통합으로 넘긴다.
 
 ## 완료 기준
 
-- [ ] Plane/Jira work item에서 core task로 이어지는 provider-neutral pipeline entrypoint와 계약이 문서화되어 있다.
+- [x] Plane/Jira work item에서 core task로 이어지는 provider-neutral pipeline entrypoint와 계약이 문서화되어 있다.
 - [x] core workflow/pipeline 계층이 Plane package 타입에 직접 의존하지 않는다.
 - [x] Plane 직접 접속부는 adapter 구현에 격리되고, Jira adapter 추가 지점이 명확하다.
-- [ ] enqueue 조건, idempotency 기준, 실패 표시 방식이 결정되어 있다.
-- [ ] provider board state, core canonical state, label/comment projection 계약이 문서화되어 있다.
-- [ ] completed/failed/cancelled 결과를 provider에 반영하는 최소 정책이 결정되어 있다.
-- [ ] Workflow Core가 pipeline 계약 질문 없이 상태 전이 구현을 시작할 수 있다.
+- [x] enqueue 조건, idempotency 기준, 실패 표시 방식이 결정되어 있다.
+- [x] provider board state, core canonical state, label/comment projection 계약이 문서화되어 있다.
+- [x] completed/failed/cancelled 결과를 provider에 반영하는 최소 정책이 결정되어 있다.
+- [x] Workflow Core가 pipeline 계약 질문 없이 상태 전이 구현을 시작할 수 있다.
 
 ## 범위 제외
 
 - Plane webhook 구현
 - Jira adapter 실제 구현
+- provider registry와 generic work item endpoint 실제 구현
 - Plane 전체 양방향 동기화
 - Plane custom property 또는 work item type Pro 기능 의존
 - task lifecycle, retry, timeout의 실제 구현
@@ -110,6 +116,7 @@ Work Item Provider Pipeline Design
   - DB schema는 `external_provider`, `external_id`, `external_url`, `external_metadata`로 provider-neutral 토대를 유지하고, agent 실행 상태 snapshot은 `metadata jsonb`로 분리한다.
   - `services/core/internal/workitempipeline`은 provider-neutral reader, task mapper, `workflow.CreateTask` 호출을 묶는 generic pipeline service를 제공한다.
   - compatibility HTTP handler는 Plane request를 `workitem.Ref`로 변환한 뒤 `workitempipeline.Service`에 생성 흐름을 위임한다.
+  - 이번 Milestone은 기존 `POST /api/integrations/plane/tasks` compatibility endpoint를 유지한 상태로 범위를 닫고, provider registry와 generic work item endpoint는 후속 별도 작업으로 분리한다.
 - 초기 생성/연결 흐름:
   - 운영자 또는 상위 자동화가 `POST /api/integrations/plane/tasks`를 호출한다.
   - 요청 필수값은 `workspace_slug`, `project_id`, `work_item_id`이고, `state_id`, `external_url`, `comment`는 선택값으로 받는다.
@@ -154,16 +161,39 @@ Work Item Provider Pipeline Design
   - provider별 API 인증, URL, workspace/project/issue 식별자, status id, label id는 adapter 설정과 metadata로만 다룬다.
   - core의 canonical 상태와 agent 실행 metadata는 provider에서 읽어온 값이 아니라 NomadCode task 상태의 진실로 둔다.
   - provider별 차이는 공통 `workitem` projection DTO와 capability를 먼저 통과시킨 뒤, Plane/Jira adapter 내부 mapping과 optional facet 구현으로 분리한다.
+  - public generic endpoint와 provider registry는 idempotency, result projection, webhook/polling 경계가 닫힌 뒤 별도 작업에서 설계/구현한다.
 - comment 기록 규칙 후보:
   - `🧭 PLAN | <요약>`: plan 작성 또는 계획 검토 단계 완료 기록
   - `🛠️ WORK | <요약>`: 구현 또는 문서 반영 단계 완료 기록
   - `🔎 REVIEW | <요약>`: 코드리뷰/self-review 단계 완료 기록
   - `✅ VERIFY | <요약>`: 테스트/검증 완료 기록
   - 각 comment 본문은 1~2줄 요약을 기본으로 하며, 자세한 실행 로그나 상태 metadata는 core에 남긴다.
+- result projection 정책:
+  - provider comment는 사람이 볼 가치가 있는 전환점에만 남긴다. heartbeat, 내부 metadata update, polling reconciliation 같은 잦은 변화는 comment로 남기지 않는다.
+  - comment prefix는 `PLAN`, `WORK`, `REVIEW`, `VERIFY`, `BLOCKED`, `FAILED`, `COMPLETE`, `CANCELLED`를 기본 세트로 둔다.
+  - `PLAN`, `WORK`, `REVIEW`, `VERIFY` comment는 해당 단계가 성공적으로 끝났을 때 1회 남긴다.
+  - `BLOCKED` comment는 `agent_run_state=waiting_for_user` 또는 provider/API 차단처럼 사람 조치가 필요한 상태로 전환될 때 남긴다.
+  - `FAILED`, `COMPLETE`, `CANCELLED` comment는 terminal 상태가 확정될 때 남긴다.
+  - provider board state update는 canonical task 상태를 투영한다. `completed`는 `complete`, `canceled`는 `cancel`로 보낸다.
+  - `failed`는 work item 자체가 끝난 것이 아니므로 기본 board state를 `in_progress`에 두고 `agent:failed` label과 `FAILED` comment로 실패를 표시한다. 명시적 cancel은 `cancel` state로 보낸다.
+  - provider comment 중복 방지는 `external_source=nomadcode`와 `external_id=<task-id>:<attempt>:<prefix>` 조합을 우선 사용한다.
+- idempotency/retry 기준:
+  - provider-neutral idempotency key는 `provider`, `tenant`, `project`, `id` 조합이다. 현재 Plane compatibility route에서는 `plane`, `workspace_slug`, `project_id`, `work_item_id`에 해당한다.
+  - `pending`, `queued`, `running` task가 같은 idempotency key로 이미 있으면 webhook, polling, 수동 entrypoint 모두 새 task를 만들지 않고 기존 active task를 반환하거나 no-op으로 처리한다.
+  - `completed` task는 기본적으로 자동 재생성하지 않는다. provider work item이 reopen되거나 사용자가 명시적 retry intent를 준 경우에만 새 attempt를 만든다.
+  - `failed`, `canceled` task 이후 자동 재시도는 하지 않는다. retry는 명시적 intent가 있을 때 `metadata.attempt`를 증가시키고 같은 idempotency key에 새 attempt를 연결한다.
+  - webhook과 polling은 provider payload만 신뢰하지 않고 provider API 재조회 후 실행 조건과 idempotency를 다시 확인한다.
+- Workflow Core handoff:
+  - work item pipeline은 provider lookup, task 생성 입력 조립, idempotency 판단, provider projection DTO 구성까지만 책임진다.
+  - task lifecycle 전이는 Workflow Core가 소유한다. 기본 전이는 `pending -> queued -> running -> completed|failed|canceled`다.
+  - retry, timeout, heartbeat, terminal 상태 확정은 Workflow Core가 소유하고, provider에는 그 결과만 projection한다.
+  - IOP/A2A/model runtime은 외부 실행 표면이며, NomadCode Workflow Core는 외부 호출의 timeout, retry envelope, 결과 정규화, 상태 기록을 책임진다. 외부 런타임 내부 retry 정책은 IOP/A2A/model adapter의 책임으로 둔다.
+  - notification의 최소 범위는 core 내부 상태 변화 event 발행이다. Mattermost 같은 외부 협업 도구 발송은 External Integration에서 별도로 구현한다.
+  - provider projection 실패는 task terminal 상태를 되돌리지 않는다. projection 작업은 retry 가능한 부수 효과로 기록하고 재시도한다.
 - 현재 지점 / 착수 상태:
-  - 현재 상태는 `진행 중`이며, provider adapter interface 설계, Plane adapter facet 검증, provider-neutral task mapper, generic pipeline service 추출, HTTP compatibility endpoint의 Plane DTO 의존 제거가 완료됐다.
+  - 현재 상태는 `완료`이며, provider adapter interface 설계, Plane adapter facet 검증, provider-neutral task mapper, generic pipeline service 추출, HTTP compatibility endpoint의 Plane DTO 의존 제거가 완료됐다.
   - `agent-task/archive/2026/05/provider_neutral_plane_entrypoint/01_pipeline_mapper/complete.log`에서 `workitem.TaskCreateInput`과 `workitem.BuildCreateTaskInput` 추가 및 whitespace fallback 회귀 수정이 PASS로 정리됐다.
   - `agent-task/archive/2026/05/provider_neutral_plane_entrypoint/02+01_http_plane_entrypoint/complete.log`에서 HTTP handler의 provider-neutral reader/mapper 전환과 compatibility route 유지가 PASS로 정리됐다.
-  - 다음 진행 후보는 comment prefix 작성 타이밍, idempotency/retry 기준 정리다.
-  - 이후 남은 큰 결정은 comment prefix 작성 타이밍, idempotency/retry 기준이다.
-- 확인 필요: `구현 잠금`의 결정 필요 항목 참고.
+  - comment prefix 작성 타이밍, idempotency/retry 기준, Workflow Core handoff가 문서로 확정됐다.
+  - 다음 진행 후보는 Workflow Core 구현 계획이다.
+- 확인 필요: 없음

agent-ops/roadmap/milestones/workflow-core.md

@@ -14,10 +14,8 @@ Workflow Core
 
 ## 구현 잠금
 
-- 상태: 잠금
-- 결정 필요:
-  - [ ] NomadCode workflow retry/timeout과 IOP 실행 정책의 책임 경계를 결정한다.
-  - [ ] notification event의 소비자와 최소 발행 범위를 결정한다.
+- 상태: 해제
+- 결정 필요: 없음
 
 ## 범위
 
@@ -55,5 +53,13 @@ Workflow Core
 - 주요 작업 영역: `services/core/internal/workflow/`, `services/core/internal/scheduler/`, `services/core/internal/notification/`
 - 선행 작업: Plane Communication Foundation, Work Item Provider Pipeline Design
 - 후속 작업: External Integration
+- 책임 경계:
+  - NomadCode Workflow Core는 task lifecycle 전이, retry/timeout envelope, heartbeat, terminal 상태 기록을 소유한다.
+  - IOP/A2A/model runtime은 외부 실행 표면이며, 내부 실행 정책과 런타임 세부 retry는 각 adapter 또는 외부 런타임 책임으로 둔다.
+  - Workflow Core는 외부 호출 결과를 `completed`, `failed`, `canceled`, `waiting_for_user` 같은 canonical 상태/metadata로 정규화한다.
+- notification 최소 범위:
+  - 이번 Milestone에서는 core 내부 상태 변화 event 모델과 발행 지점까지만 정한다.
+  - Mattermost 등 외부 협업 도구 발송은 External Integration 범위로 넘긴다.
+  - provider comment/status/label projection은 workflow 상태 변화의 부수 효과로 재시도 가능해야 하며, projection 실패가 canonical task 상태를 되돌리지는 않는다.
 - 검증 기준: scheduler, persistence, adapter behavior를 크게 바꾸면 관련 테스트를 함께 갱신한다.
-- 확인 필요: `구현 잠금`의 결정 필요 항목 참고.
+- 확인 필요: 없음