# Plane Communication Foundation

## 목표

core가 실제 Plane 인스턴스와 안정적으로 통신할 수 있는 최소 기반을 만든다. 현재 단계는 파이프라인 설계나 자동 실행 흐름을 확정하지 않고, 인증, endpoint 계약, work item 조회, comment/status update, 외부 참조 저장, 수동 smoke 검증에 집중한다.

## 단계

Plane Communication Foundation

## 상태

완료

## 구현 잠금

- 상태: 해제
- 이유: 완료된 Milestone의 기록 보정이며, 새 구현 작업을 시작하는 문서가 아니다.
- 해제 조건:
  - [x] Plane 통신 기반과 smoke 검증 결과가 문서화되어 있다.
  - [x] 후속 task pipeline 설계는 Work Item Provider Pipeline Design에서 다룬다.
  - [x] 사용자가 기존 마일스톤 잠금 보정을 승인했다.
- 잠금 중 금지:
  - 해당 없음

## 범위

- Plane self-hosted 인스턴스 연결 정보와 API 계약 확인
- Plane API token 주입 방식 정리
- Plane work item 조회, comment 생성, status update adapter 구현
- core task와 Plane work item을 연결할 외부 참조 저장 토대 구성
- 실제 Plane 인스턴스를 대상으로 한 수동 smoke 검증 절차 정리

## 필수 기능

- [x] Plane 연결 설정과 인증 계약을 정한다.
  - [x] `PLANE_BASE_URL=https://plane.toki-labs.com` 기준 endpoint prefix를 확인한다.
  - [x] Plane API key를 `PLANE_TOKEN`으로 주입하고 `X-Api-Key` header로 호출한다.
- [x] Plane adapter의 최소 통신 기능을 구현한다.
  - [x] work item detail 조회
  - [x] work item comment 생성
  - [x] work item state update
  - [x] non-2xx 응답과 설정 누락 오류를 진단 가능하게 반환
- [x] core task에 외부 참조 저장 토대를 둔다.
  - [x] `external_provider`, `external_id`, `external_url`, `external_metadata` 등 provider-neutral 필드를 둔다.
  - [x] Plane workspace/project/work item id와 external URL을 metadata에 보존할 수 있게 한다.
  - [x] Plane state id를 metadata에 보존할 수 있게 한다.
- [x] 실제 Plane 통신 smoke를 검증한다.
  - [x] 인증 성공/실패를 구분해 확인한다.
  - [x] 테스트용 Plane work item에 comment를 남길 수 있다.
  - [x] 테스트용 Plane work item state를 변경할 수 있다.
- [x] 문서에 현재 통신 토대의 사용법과 한계를 정리한다.
  - [x] `services/core/README.md`에 Plane 설정, 수동 task 생성 예시, 현재 endpoint 한계를 정리한다.
  - [x] 실제 smoke 절차를 운영 문서에 보강한다.

## 완료 기준

- [x] 유효한 `PLANE_TOKEN`으로 `https://plane.toki-labs.com/api/v1/...` work item API가 200 응답을 반환한다.
- [x] core Plane adapter 테스트가 request path, `X-Api-Key`, request body, error response를 검증한다.
- [x] core task가 Plane work item id와 관련 metadata를 저장할 수 있다.
- [x] 실제 Plane work item 하나에 comment 생성과 state update smoke가 성공한다.
- [x] README 또는 운영 문서에 Plane 설정과 smoke 절차가 남아 있다.

## 범위 제외

- task pipeline 설계와 agent 실행 orchestration 확정
- Plane issue에서 core task를 자동 생성하고 enqueue하는 제품 흐름 확정
- task 완료/실패 결과를 Plane으로 자동 발행하는 정책 확정
- retry, timeout, notification event 정책
- Plane webhook 기반 자동 수집
- Plane 전체 양방향 동기화
- Mattermost 메시지 발송 구현
- Agent Integrator와 IOP의 추가 통합
- 복잡한 workflow DSL
- Plane token 생성/보관/교체 운영 절차

## 작업 컨텍스트

- 관련 경로: `services/core/internal/adapters/plane/`, `services/core/internal/storage/`, `services/core/internal/workflow/`, `services/core/migrations/`, `services/core/queries/`, `services/core/README.md`
- 선행 작업: Server Skeleton
- 후속 작업: Plane Task Pipeline Design, Workflow Core
- 확인된 dev Plane:
  - Base URL: `https://plane.toki-labs.com`
  - workspace slug: `general`
  - NomadCode project id: `a6beb42f-7a8a-410c-b50f-ea3ca94828f3`
  - Done state id: `ea2e5b48-8bf1-4723-b749-de7723be41e9`
  - Cancelled state id: `f29c06c2-d70c-4b56-a83c-fccc4db60ae4`
- 완료 근거:
  - Plane adapter는 work item 조회, comment 생성, state update, `X-Api-Key`, non-2xx/error body, 설정 누락 오류 테스트를 포함한다.
  - core task는 provider-neutral external ref 컬럼과 Plane workspace/project/work item metadata 저장 경로를 포함한다.
  - HTTP endpoint는 Plane work item 조회 후 pending task와 external ref를 수동 생성하는 얇은 경로만 제공한다.
  - 실제 Plane smoke 절차와 설정 예시는 `services/core/README.md`에 남아 있다.

## 메모

- 이 마일스톤은 Plane과의 통신 경계와 데이터 토대만 안정화한다.
- pipeline 설계가 정리되기 전까지 scheduler/workflow에 Plane 자동 발행 정책을 더 넣지 않는다.
- 이미 구현된 코드가 이 범위를 넘어간 경우, 리뷰 단계에서 유지/축소/후속 분리 여부를 판단한다.