toki
e7ddbcdfed
- Add migration for task metadata column (00003) - Update workflow model and service with metadata support - Update database layer (models, queries) for metadata field - Update storage store to handle metadata - Update roadmap documents and milestones
169 lines
16 KiB
Markdown
169 lines
16 KiB
Markdown
# Work Item Provider Pipeline Design
|
|
|
|
## 목표
|
|
|
|
Plane Communication Foundation 다음 단계로 Plane/Jira 등 work item provider와 core task pipeline 사이의 최소 제품 흐름을 확정한다. 자동 실행 구현에 들어가기 전에 provider-neutral 생성, enqueue, 상태 투영, 중복 방지, 결과 발행 경계를 정리해 Workflow Core가 참조할 상태 변화와 실패 케이스를 명확히 한다.
|
|
|
|
## 단계
|
|
|
|
Work Item Provider Pipeline Design
|
|
|
|
## 상태
|
|
|
|
진행 중
|
|
|
|
## 구현 잠금
|
|
|
|
- 상태: 잠금
|
|
- 결정 필요:
|
|
- [ ] generic pipeline service 이후 provider registry/generic endpoint를 별도 작업으로 둘지, compatibility endpoint 유지 상태로 이번 Milestone 범위를 닫을지 결정한다.
|
|
|
|
## 범위
|
|
|
|
- Plane/Jira 같은 work item provider에서 core task를 생성하고 연결하는 entrypoint 후보 정리
|
|
- 수동 endpoint, webhook, polling 등 trigger 방식의 다음 구현 경로 결정
|
|
- core task enqueue 조건과 중복 생성 방지 기준 정리
|
|
- provider별 직접 접속부와 core 내부 pipeline 계약을 분리하는 adapter interface 정리
|
|
- provider board state와 agent 내부 실행 상태의 분리 계약 정리
|
|
- Plane/Jira에서 공통으로 읽히는 label/comment 기반 상태 투영 방식 정리
|
|
- task 완료/실패 결과를 provider comment/status로 발행하는 최소 정책 정리
|
|
- provider별 workspace/project/work item/state metadata 사용 방식 확정
|
|
- Workflow Core에 넘길 상태 변화, 실패 케이스, notification 요구사항 정리
|
|
|
|
## 필수 기능
|
|
|
|
- [x] [create-flow] Plane work item -> core task 생성/연결 흐름을 현재 구현 기준으로 문서화한다.
|
|
- [x] [create-entrypoint] 초기 entrypoint는 기존 `POST /api/integrations/plane/tasks`를 기준선으로 삼는다.
|
|
- [x] [create-scope] 생성 단계는 Plane work item 조회와 core task 저장까지만 담당한다.
|
|
- [x] [create-pending] 생성된 task는 `pending` 상태로 남기고 enqueue는 별도 단계에서 처리한다.
|
|
- [x] [create-metadata] Plane 연결 정보는 provider-neutral external ref와 work item metadata에 함께 저장한다.
|
|
- [x] [enqueue-trigger] 자동 enqueue 여부와 사용자/운영 트리거 경계를 결정한다.
|
|
- [x] [user-todo] `backlog`에서 `todo`로 옮기는 주체는 사용자로 둔다.
|
|
- [x] [todo-assignee] `todo` 상태여도 agent 작업자가 지정된 work item만 자동 실행 후보로 본다.
|
|
- [x] [service-token] provider API 인증은 일반 사용자형 service account token을 기본으로 둔다.
|
|
- [x] [token-local] Plane dev service account token은 ignored local file `.env.plane.local`에 저장하고, NomadCode project Admin 권한으로 검증한다.
|
|
- [x] [assignee-agent] agent 작업자 지정 신호는 provider assignee가 `AGENT` 일반 사용자형 service account인 경우로 확정한다.
|
|
- [x] [profile-metadata] worker profile과 실행 단계는 core metadata와 label/comment prefix로 표현한다.
|
|
- [x] [trigger-webhook] webhook-first trigger와 polling fallback의 세부 조건을 확정한다.
|
|
- [x] [labels-display] `worker:*`, `agent:*`, `phase:*` label은 실행 조건이 아니라 worker profile/실행 상태 표시용으로 둔다.
|
|
- [x] [adapter-interface] work item provider adapter interface를 설계한다.
|
|
- [x] [dto-contract] core pipeline이 사용할 provider-neutral DTO를 정의한다.
|
|
- [x] [provider-facets] work item 조회, comment 작성, status/state 변경, label projection 경계를 interface로 분리한다.
|
|
- [x] [adapter-mapping] Plane adapter와 Jira adapter가 같은 interface를 구현할 수 있는지 검증한다.
|
|
- [x] [provider-config] provider별 상태/라벨/comment 매핑은 adapter 설정으로 분리한다.
|
|
- [x] [generic-pipeline] 현재 Plane 고정 진입부를 provider-neutral 구조로 리팩토링한다.
|
|
- [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] [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로 둔다.
|
|
- [x] [label-first] Plane/Jira provider projection은 label-first로 둔다.
|
|
- [x] [desc-readonly] provider 본문(description)은 agent 실행 상태 저장소로 쓰지 않는다.
|
|
- [x] [metadata-schema] core task metadata schema와 provider label mapping을 구현 대상으로 확정한다.
|
|
- [x] [metadata-keys] canonical metadata key는 `agent_run_state`, `agent_phase`, `wait_type`, `status_reason`, `last_heartbeat_at`, `plan_ref`, `attempt`를 기본값으로 둔다.
|
|
- [x] [metadata-storage] canonical metadata 저장 위치는 신규 `tasks.metadata jsonb`로 확정한다.
|
|
- [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] [comment-prefix-sample] agent 단계 완료 기록은 prefix와 이모지가 있는 comment로 남기는 방향을 샘플 검증한다.
|
|
- [ ] [comment-timing] comment prefix 세트와 작성 타이밍을 확정한다.
|
|
- [ ] [idempotency] 중복 생성 방지와 재시도 시 식별 기준을 정한다.
|
|
- [ ] [workflow-handoff] Workflow Core에서 처리할 lifecycle, retry, timeout, notification 요구사항을 정리한다.
|
|
|
|
## 완료 기준
|
|
|
|
- [ ] 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 계약 질문 없이 상태 전이 구현을 시작할 수 있다.
|
|
|
|
## 범위 제외
|
|
|
|
- Plane webhook 구현
|
|
- Jira adapter 실제 구현
|
|
- Plane 전체 양방향 동기화
|
|
- Plane custom property 또는 work item type Pro 기능 의존
|
|
- task lifecycle, retry, timeout의 실제 구현
|
|
- 외부 협업 도구로 notification 발송
|
|
- Mattermost 메시지 발송 구현
|
|
- 복잡한 workflow DSL
|
|
- Plane token 생성/보관/교체 운영 절차
|
|
|
|
## 작업 컨텍스트
|
|
|
|
- 관련 경로: `services/core/internal/adapters/plane/`, `services/core/internal/http/`, `services/core/internal/storage/`, `services/core/internal/scheduler/`, `services/core/internal/workflow/`, `services/core/internal/workitem/`, `services/core/internal/workitempipeline/`, `services/core/README.md`
|
|
- 파일명 메모: 기존 Plane 중심 파일명 `plane-task-pipeline-design.md`는 대규모 rename을 피하기 위해 유지하되, 마일스톤 이름과 내용은 Work Item Provider Pipeline Design으로 일반화한다.
|
|
- 선행 작업: Plane Communication Foundation
|
|
- 후속 작업: Workflow Core
|
|
- 현재 코드 결합 상태:
|
|
- HTTP router는 기존 compatibility route인 `POST /api/integrations/plane/tasks`를 유지한다.
|
|
- handler는 Plane adapter package나 Plane DTO를 직접 import하지 않고, 로컬 `WorkItemReader` interface와 `workitem.Ref`, `workitem.WorkItem`으로 조회 결과를 다룬다.
|
|
- `buildPlaneCreateTaskInput`은 HTTP package 안에서 core task payload/external ref를 직접 조립하지 않고 `workitem.BuildCreateTaskInput`에 위임한다.
|
|
- `services/core/internal/workitem`은 provider-neutral DTO, optional facet interface, projection mapping, task create mapper를 제공한다.
|
|
- Plane adapter는 `workitem.Provider`, `Reader`, `Commenter`, `StatusProjector`를 구현하며 `LabelProjector`는 capability false로 남긴다.
|
|
- 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`에 생성 흐름을 위임한다.
|
|
- 초기 생성/연결 흐름:
|
|
- 운영자 또는 상위 자동화가 `POST /api/integrations/plane/tasks`를 호출한다.
|
|
- 요청 필수값은 `workspace_slug`, `project_id`, `work_item_id`이고, `state_id`, `external_url`, `comment`는 선택값으로 받는다.
|
|
- core는 Plane adapter의 `workitem.Reader` 구현으로 work item detail을 조회해 provider-neutral title과 description 후보를 얻는다.
|
|
- task title은 provider work item title을 우선하고, 비어 있으면 `work_item_id`를 사용한다.
|
|
- task payload의 `message`는 요청 `comment`, provider text description, HTML description, title 순서로 선택하며 공백-only 후보는 건너뛴다.
|
|
- task source는 `plane`, external provider는 `plane`, external id는 `work_item_id`로 저장한다.
|
|
- provider-neutral metadata key `provider`, `tenant`, `project`, `id`, `state_id`, `external_url`은 `payload.work_item`과 `external_metadata`에 저장한다.
|
|
- 생성 직후 task 상태는 `pending`이며, 이 entrypoint는 enqueue, Plane 상태 변경, 결과 comment 발행을 수행하지 않는다.
|
|
- 상태 설계 결정:
|
|
- provider board state는 `backlog`, `todo`, `in_progress`, `testing`, `complete`, `cancel`의 소유권/검증 단계로 유지한다.
|
|
- `in_progress`를 planning, implementing, review 같은 board state로 쪼개지 않고, agent 내부 실행 상태는 core task metadata에 canonical 값으로 저장한다.
|
|
- agent 내부 실행 상태의 기본 canonical metadata key는 `agent_run_state`, `agent_phase`, `wait_type`, `status_reason`, `last_heartbeat_at`, `plan_ref`, `attempt`다.
|
|
- agent가 작업 중 사용자 판단을 기다릴 때는 board state를 `in_progress`로 유지하고 `agent_run_state=waiting_for_user`와 `wait_type`으로 멈춤 이유를 표현한다.
|
|
- `testing`은 agent가 plan, 구현, 자체 테스트, 자체 리뷰 루프를 끝낸 뒤 사용자가 직접 테스트하는 단계다.
|
|
- provider projection은 라벨을 우선 사용한다. 예: `agent:waiting-user`, `agent:blocked`, `agent:failed`, `phase:0`, `phase:1`.
|
|
- phase label은 `agent-task/archive`의 작업별 loop index처럼 0부터 증가시키며, provider label은 외부 표시/검색용이고 최신 phase의 canonical source는 core metadata의 `agent_phase`로 둔다.
|
|
- provider 본문(description)은 작업 요구사항과 맥락의 원본으로 보고, agent 실행 상태를 매번 갱신하는 저장소로 쓰지 않는다.
|
|
- Plane custom property는 현재 NomadCode dev project에서 `is_issue_type_enabled=False`라 기본 경로로 전제하지 않는다.
|
|
- Plane 샘플 work item `NOMAD-13`은 `In Progress` state와 `agent:waiting-user`, `phase:planning` 라벨로 board state와 agent 내부 실행 상태 분리 방식을 보여준다. 신규 projection 계약에서는 phase label을 `phase:0`부터의 index형 label로 전환한다.
|
|
- canonical metadata 저장 위치는 신규 `tasks.metadata jsonb`로 확정한다. `payload`는 task 생성 입력/요구사항, `external_metadata`는 provider 연결 정보, `metadata`는 agent 실행 상태의 최신 snapshot으로 분리한다.
|
|
- `services/core/migrations/00003_add_task_metadata.sql`은 `tasks.metadata jsonb NOT NULL DEFAULT '{}'`를 추가한다.
|
|
- workflow create/update 경계는 invalid metadata JSON을 거부하고 빈 값 또는 `null`은 `{}`로 정규화한다.
|
|
- trigger/auth 결정:
|
|
- 사용자가 `backlog`에서 `todo`로 이동시키는 행위가 AI 작업 위임 의사로 간주될 수 있는 첫 관문이다.
|
|
- core는 `todo` 상태와 agent 작업자 지정 신호가 함께 있을 때만 자동 실행 후보로 본다.
|
|
- agent 작업자 지정 신호는 provider assignee가 `AGENT` display name을 가진 일반 사용자형 service account인 경우다.
|
|
- 사용자가 `todo`로 작업을 옮기거나 `todo` 상태로 바로 생성하고, assignee를 `AGENT`로 지정하면 자동 실행 후보가 된다.
|
|
- provider webhook을 우선 trigger로 사용한다.
|
|
- polling은 webhook 누락, delivery 장애, core downtime 복구를 위한 fallback/reconciliation 경로로만 둔다.
|
|
- webhook 수신 시 payload만 신뢰하지 않고 provider API로 work item을 다시 조회한 뒤 실행 조건을 재검증한다.
|
|
- webhook과 polling 모두 동일한 idempotency 검사와 active task 중복 방지 로직을 통과해야 한다.
|
|
- fallback polling 대상은 전체 provider item이 아니라 `todo` 상태와 agent 작업자 지정 신호가 있는 후보로 좁힌다.
|
|
- provider API 호출과 댓글 작성은 일반 사용자형 service account token으로 수행한다.
|
|
- Plane dev token은 repo root의 ignored `.env.plane.local`에서 로드하며, 해당 token 계정은 NomadCode project Admin 권한으로 API 조회/댓글 작성 smoke가 성공했다.
|
|
- worker assignment identity는 `AGENT` assignee로 판단한다. 실제 worker profile과 agent 실행 단계는 core metadata, provider label, comment prefix에 남긴다.
|
|
- Plane bot user는 UI 필터와 내장 agent trigger 경로가 있어 1차 작업자 모델로 전제하지 않는다.
|
|
- provider abstraction 결정:
|
|
- Plane은 첫 구현 provider일 뿐이며 core pipeline의 도메인 모델이 되어서는 안 된다.
|
|
- Jira도 같은 workflow state, label/comment projection, idempotency 계약을 공유할 수 있어야 한다.
|
|
- provider-neutral adapter contract는 `workitem.Ref`, `WorkItem`, `CommentInput`, `StatusProjection`, `LabelProjection`, `Mapping`으로 둔다.
|
|
- 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 구현으로 분리한다.
|
|
- comment 기록 규칙 후보:
|
|
- `🧭 PLAN | <요약>`: plan 작성 또는 계획 검토 단계 완료 기록
|
|
- `🛠️ WORK | <요약>`: 구현 또는 문서 반영 단계 완료 기록
|
|
- `🔎 REVIEW | <요약>`: 코드리뷰/self-review 단계 완료 기록
|
|
- `✅ VERIFY | <요약>`: 테스트/검증 완료 기록
|
|
- 각 comment 본문은 1~2줄 요약을 기본으로 하며, 자세한 실행 로그나 상태 metadata는 core에 남긴다.
|
|
- 현재 지점 / 착수 상태:
|
|
- 현재 상태는 `진행 중`이며, 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 기준이다.
|
|
- 확인 필요: `구현 잠금`의 결정 필요 항목 참고.
|