# Milestone: External Integration

## 위치

- Roadmap: `agent-roadmap/ROADMAP.md`
- Phase: `agent-roadmap/phase/external-integration/PHASE.md`

## 목표

Work Item Provider Pipeline Design과 workflow core 이후 남은 Plane/Jira 확장, Mattermost, Agent Integrator, IOP 연결을 stub 또는 호환 호출 경로에서 실제 통합 흐름으로 확장한다. IOP 호출은 현재 단계에서 OpenAI API Responses-compatible 경로를 기본으로 하며, NomadCode가 직접 모델 런타임을 호출하거나 IOP native protocol을 외부 호출 표면으로 사용하지 않는다.

## 상태

[계획]

## 구현 잠금

- 상태: 잠금
- 결정 필요:
  - [ ] Mattermost와 Plane/Jira 결과 발행의 책임 경계를 결정한다.
  - [ ] Agent Integrator를 유지할지 IOP/A2A 또는 다른 연결 지점으로 대체할지 결정한다.
  - [ ] A2A 도입 시점을 이 Milestone 범위로 둘지 후속으로 미룰지 결정한다.

## 범위

- Plane issue 생성 / comment / status update 확장
- Jira issue 조회 / comment / status transition adapter 구현
- Mattermost 메시지 발송 구현
- Agent Integrator 호출 구조 추가
- IOP OpenAI API Responses-compatible 호출 구조 추가
- IOP 외부 호출 표면은 OpenAI API 호환과 A2A만 전제하되, 현재 단계의 기본 호출은 OpenAI API Responses-compatible 경로로 한정
- NomadCode core가 직접 모델 endpoint 또는 Ollama fallback을 기본 실행 경로로 전제하지 않도록 전환 기준 정리

## 기능

### Epic: [external-integration] Provider and execution adapters

외부 work item provider, 협업 도구, 실행 표면을 adapter 경계 안에서 실제 통합 흐름으로 확장한다.

- [ ] [plane-adapter-expand] Plane issue 생성, comment, status update adapter 확장. 검증: core가 Plane에 issue, comment, status update를 요청할 수 있다.
- [ ] [jira-adapter] Jira issue 조회, comment, status transition adapter 구현. 검증: core가 Jira에 issue 조회, comment, status transition을 요청할 수 있다.
- [ ] [mattermost-adapter] Mattermost 메시지 발송 adapter 구현과 `../nexo/packages/messaging_flutter` host notification boundary 정합성 유지. 검증: core가 Mattermost에 메시지를 발송하고, server-generated signed push smoke가 `agent-test/local/mattermost-server-generated-push-smoke.md` 기준으로 FCM/ACK/opened/reply/dismiss evidence를 남긴다.
- [ ] [agent-integrator] Agent Integrator 호출 경계 정의. 검증: Agent Integrator 또는 그 대체 연결 지점이 명확히 정의되어 있다.
- [x] [iop-responses] IOP OpenAI API Responses-compatible 경로를 NomadCode의 기본 실행 호출 경로로 정리. 검증: IOP OpenAI API Responses-compatible 호출 경로가 core workflow와 연결된다.
- [x] [model-reclass] direct model endpoint / Ollama fallback 표현과 설정을 IOP 경유 호출 기준으로 재분류. 검증: NomadCode의 기본 실행 경로가 직접 모델 호출이 아니라 IOP 경유 호출임이 로드맵과 운영 문서에서 일관되게 읽힌다.
- [ ] [adapter-boundary] 외부 provider별 구현 경계 점검. 검증: provider 세부 구현이 adapter 경계 밖으로 새지 않는다.

## 완료 리뷰

- 상태: 없음
- 요청일: 없음
- 완료 근거: 없음
- 리뷰 필요:
  - [ ] 사용자가 완료 결과를 확인했다
  - [ ] archive 이동을 승인했다
- 리뷰 코멘트: 없음

## 범위 제외

- Outline / Forgejo / Nextcloud 연동
- MCP 서버
- Web Agent UI
- Flutter 앱 기능 구현
- IOP A2A JSON-RPC 기반 외부 agent 추가, task 상태, artifact, cancel 흐름 공유
- NomadCode가 IOP native protocol을 직접 외부 호출 경로로 사용하는 것
- IOP 내부 모델 라우팅, 모델 프로파일, RAG, MCP, output validation, fallback 정책 구현

## 작업 컨텍스트

- 이전 출처: `services/core/README.md`의 `## 단계별 다음 작업`
- 주요 작업 영역: `services/core/internal/adapters/`, `services/core/internal/scheduler/`, `services/core/internal/workflow/`
- 선행 작업: Work Item Provider Pipeline Design, Workflow Core, Mattermost Nexo Messaging Alignment
- 후속 작업: Project Workspace Management UX
- Mattermost signed push smoke 재현 가이드: `agent-test/local/mattermost-server-generated-push-smoke.md`
- private 환경값 router: `agent-test/local/mattermost-server-generated-push-smoke.md` (ignored local file)
- Mattermost 책임 경계: core는 Mattermost REST 메시지 발송과 task notification 발행을 담당하고, `../nexo/packages/messaging_flutter`는 client-side FCM 수신, signature 검증, ACK, notification display, opened-routing, inline reply, dismiss를 담당한다.
- Nexo host 정합성: NomadCode host는 Firebase 설정, Mattermost credential handoff, signing key, optional server identifier, navigation callback만 `MattermostPushClient` 경계로 전달한다. native push 처리 로직은 `apps/client/android`에 복제하지 않는다.
- 선행 순서: Mattermost 메시지/알림 경계 정합성은 `agent-roadmap/phase/external-integration/milestones/mattermost-nexo-messaging-alignment.md`에서 먼저 닫고, 이후 `[mattermost-adapter]`는 core의 Mattermost REST 메시지 발송 구현에 집중한다.
- 현재 반영 근거:
  - `services/core/internal/adapters/openai/client.go`는 non-streaming `POST /v1/responses` 호출 경로를 사용한다.
  - `services/core/cmd/server/main.go`는 `MODEL_BASE_URL`, `MODEL_API_KEY`, `MODEL_NAME`, `MODEL_CONTEXT_SIZE`, `MODEL_TIMEOUT_SEC` 설정으로 OpenAI-compatible model client를 구성해 scheduler에 연결한다.
  - `services/core/internal/scheduler/jobs.go`는 model client 결과를 task completion 결과로 저장한다.
  - `README.md`와 `services/core/README.md`는 NomadCode의 기본 실행 호출을 IOP Edge OpenAI-compatible Responses 경로로 정리하고, direct Ollama/model endpoint는 local development compatibility로 재분류한다.
  - sibling IOP repository의 로드맵은 OpenAI-compatible API를 외부 모델 기반 호출 표면으로, A2A를 외부 agent 작업 위임 표면으로, IOP native protocol을 운영 제어 표면으로 분리한다.
- 확인 필요: `구현 잠금`의 결정 필요 항목 참고.
