# Milestone: Workflow Core

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/workflow-core/PHASE.md`

## 목표

Plane 통신 토대와 별도 pipeline 설계가 정리된 뒤 실제 상태 변화를 기준으로 task 상태 전이를 정리하고 enqueue / running / completed / failed 흐름을 안정화한다. retry, timeout, notification event의 기본 구조를 추가해 core workflow의 운영 기준을 만든다.

## 상태

[완료]

## 구현 잠금

- 상태: 해제
- 결정 필요: 없음

## 범위

- task 상태 전이 정리
- enqueue / running / completed / failed 흐름 안정화
- retry / timeout 기본 구조 추가
- notification event 구조 정리
- Plane 통신 토대와 후속 pipeline 설계에서 확인된 상태 변화와 실패 케이스 반영
- Proto-Socket Infrastructure Communication Rail에서 정리한 client-core 통신 레일과 내부 통신 예외 경계 반영

## 기능

### Epic: [workflow-core] Workflow lifecycle stability

Core task lifecycle과 상태 전이 책임, 실패/재시도/timeout/notification event 기준을 안정화한다.

- [x] [lifecycle-model] task lifecycle 상태 모델 점검. 검증: task가 enqueue 이후 running, completed, failed 상태로 일관되게 전이된다.
- [x] [transition-ownership] scheduler와 workflow service의 상태 전이 책임 정리. 검증: 상태 전이 책임이 code/docs/tests에서 중복 없이 읽힌다.
- [x] [failure-policy] 실패 task 처리 기준. 검증: 실패와 timeout이 관찰 가능한 상태, metadata, error로 남는다.
- [x] [retry-timeout] retry와 timeout의 최소 정책. 검증: retry 정책의 최소 동작 방식이 구현되거나 명확히 문서화된다.
- [x] [notification-model] notification event 모델과 발행 지점. 검증: notification event가 workflow 상태 변화와 연결된다.

## 완료 리뷰

- 상태: 승인됨
- 요청일: 2026-06-01
- 완료 근거:
  - `workflow.Lifecycle`가 queue/start/complete/fail/cancel 상태 전이와 canonical metadata 병합을 소유하고, enqueue 실패도 lifecycle 실패 전이로 정규화한다.
  - `scheduler.TaskWorker`가 `StartTask` -> 실행 -> `CompleteTask`/`FailTaskWithMetadata` 흐름을 사용하며 timeout, attempt, retryable, failure_type, status_reason을 남긴다.
  - `notification.TaskEvent`와 proto-socket `task.status.changed` event가 running/completed/failed 상태 변화와 attempt/reason/occurred_at 컨텍스트를 전달한다.
- 리뷰 필요:
  - [x] 사용자가 완료 결과를 확인했다
  - [x] archive 이동을 승인했다
- 리뷰 코멘트: 최근 workflow-core 커밋 기준으로 문서와 체크리스트를 동기화했고, 사용자 요청에 따라 완료 처리 후 archive로 이동했다. 현재 환경의 local 테스트 실행은 `agent-test/local/rules.md`의 테스트 금지 규칙 때문에 생략했으며, 코드상 관련 테스트는 `services/core/internal/workflow/service_test.go`, `services/core/internal/scheduler/jobs_test.go`, `services/core/internal/notification/service_test.go`, `services/core/internal/protosocket/tasks_test.go`에 반영되어 있다.

## 범위 제외

- 실제 외부 협업 도구로 notification 발송
- 복잡한 workflow DSL
- 고급 권한 정책
- multi-tenant 운영 정책

## 작업 컨텍스트

- 이전 출처: `services/core/README.md`의 `## 단계별 다음 작업`
- 주요 작업 영역: `services/core/internal/workflow/`, `services/core/internal/scheduler/`, `services/core/internal/notification/`
- 선행 작업: Plane Communication Foundation, Work Item Provider Pipeline Design, Proto-Socket Infrastructure Communication Rail
- 선행 조건: Proto-Socket Infrastructure Communication Rail이 client-core task 요청과 상태 이벤트가 오갈 수 있는 내부 통신 기준선을 제공한다.
- 후속 작업: External Integration
- 현재 지점: workflow 상태 전이, scheduler 실행 책임, 실패/timeout metadata, retry/attempt 정책, notification/proto-socket 상태 이벤트 모델이 최근 workflow-core 작업으로 반영되어 완료되었다.
- 책임 경계:
  - NomadCode Workflow Core는 task lifecycle 전이, retry/timeout envelope, heartbeat, terminal 상태 기록을 소유한다.
  - Roadmap Operations Control Plane과 MCP 외부 agent 제어 표면은 `Agent-Ops MCP Control Plane` Phase에서 후속으로 다룬다.
  - 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를 크게 바꾸면 관련 테스트를 함께 갱신한다.
- 확인 필요: 없음
