<!-- task=m-external-integration/02+01_adapter_boundary plan=0 tag=TEST -->

# Adapter Boundary Audit Plan

## 이 파일을 읽는 구현 에이전트에게

`CODE_REVIEW-local-G04.md`의 구현 에이전트 소유 섹션을 채우는 것이 구현의 마지막 단계다. 이 dependent task는 `01_provider_intake_registry`가 PASS되어 `complete.log`를 만든 뒤에만 구현한다. code-review 전용 종결 절차는 실행하지 않는다. 사용자 결정이나 외부 환경이 필요한 차단만 `사용자 리뷰 요청`에 기록한다.

## 배경

`provider-intake-registry`가 끝난 뒤에는 provider 세부 구현이 adapter 경계 밖으로 새지 않는지 별도로 확인해야 한다. 이 작업은 새 기능 추가보다 경계 검증과 회귀 방지에 초점을 둔다.

## 사용자 리뷰 요청 흐름

구현 중 차단이 생기면 active `CODE_REVIEW-local-G04.md`의 `사용자 리뷰 요청` 섹션에 기록한다. code-review가 그 요청을 검증하고 실제 `USER_REVIEW.md` 작성 여부를 결정한다.

## Roadmap Targets

- Milestone: `agent-roadmap/phase/external-integration/milestones/external-integration.md`
- Task ids:
  - `adapter-boundary`: 외부 provider별 구현 경계 점검
- Completion mode: check-on-pass

## 분석 결과

### 읽은 파일

- `agent-ops/skills/common/plan/SKILL.md`
- `agent-ops/rules/project/domain/core/rules.md`
- `agent-test/local/rules.md`
- `agent-test/local/core-smoke.md`
- `agent-roadmap/current.md`
- `agent-roadmap/phase/external-integration/milestones/external-integration.md`
- `services/core/cmd/server/main.go`
- `services/core/internal/http/handlers.go`
- `services/core/internal/http/router.go`
- `services/core/internal/workitem/provider.go`
- `services/core/internal/workitempipeline/service.go`
- `services/core/internal/adapters/plane/client.go`
- `services/core/internal/adapters/jira/client.go`
- `services/core/internal/adapters/mattermost/client.go`
- `services/core/internal/adapters/mattermost/task_notification_sink.go`
- `services/core/internal/http/handlers_test.go`
- `services/core/internal/workitempipeline/service_test.go`

### 테스트 환경 규칙

- test_env: `local`.
- `agent-test/local/rules.md`와 `agent-test/local/core-smoke.md`를 읽었다.
- 적용 명령: `cd services/core && go test ./...`, 보조로 deterministic `rg --sort path` boundary checks.
- 사전 확인: `cd services/core && go test ./...` 실행 가능함을 확인했다.

### 테스트 커버리지 공백

- 현재 테스트는 adapter별 unit behavior와 handler delegation을 검증하지만, provider-specific imports/names가 workflow/workitem/workitempipeline/http 경계로 새지 않는지 직접 검증하지 않는다.
- `01_provider_intake_registry` 완료 전에는 최종 boundary 상태를 판단할 수 없다.

### 심볼 참조

- 제거/이름 변경 예정 없음. 이 작업은 audit/follow-up correction이다.
- 점검 대상 문자열: `internal/adapters/plane`, `internal/adapters/jira`, `internal/adapters/mattermost`, `planeWorkItemTasks`, `jiraWorkItemTasks`, `createPlaneTaskRequest`.

### 분할 판단

- split policy 평가 완료. 이 task는 `02+01_adapter_boundary`이며 predecessor index `01`에 의존한다.
- predecessor status: active `agent-task/m-external-integration/01_provider_intake_registry/complete.log` 없음. 구현 시작 전 active 또는 archived `complete.log`로 충족해야 한다.
- archive lookup 후보는 구현 시작 시에만 확인한다: `agent-task/archive/*/*/m-external-integration/01_*/complete.log`, `agent-task/archive/*/*/m-external-integration/01+*/complete.log`.

### 범위 결정 근거

- 새 provider feature나 adapter live API 동작은 추가하지 않는다.
- Plane/Jira/Mattermost client internals는 boundary 누수 수정이 필요한 경우에만 건드린다.
- mobile/FCM smoke는 이미 `mattermost-adapter` 완료 증거로 쓰였고 이 audit의 필수 범위가 아니다.

### 빌드 등급

- build: `local-G04`, review: `local-G04`.
- 이유: predecessor 이후의 경계 검증과 작은 follow-up correction 중심이며 deterministic grep/test로 판단 가능하다.

## 의존 관계 및 구현 순서

- 이 디렉터리명 `02+01_adapter_boundary`의 source of truth는 depends_on=[01]이다.
- 구현 시작 전 `agent-task/m-external-integration/01_provider_intake_registry/complete.log` 또는 matching archive `complete.log`가 정확히 하나 있는지 확인한다.
- predecessor가 없거나 ambiguous하면 코드 수정하지 말고 review stub의 `사용자 리뷰 요청`이 아니라 계획 대비 변경 사항/검증 결과에 missing predecessor를 기록하고 멈춘다.

## 구현 체크리스트

- [ ] `01_provider_intake_registry` predecessor `complete.log` 충족 여부를 확인한다.
- [ ] provider-specific adapter imports가 `workflow`, `workitem`, `workitempipeline`, `http` 경계로 새지 않는지 deterministic search로 점검한다.
- [ ] registry 전환 뒤 남은 Plane/Jira 전용 handler field, request DTO, branch가 있으면 provider-neutral 명칭으로 정리한다.
- [ ] 필요한 경우 boundary regression test를 추가해 generic route와 adapter package 격리가 유지되게 한다.
- [ ] `cd services/core && go test -count=1 ./internal/http ./internal/workitem ./internal/workitempipeline`를 통과시킨다.
- [ ] boundary grep checks와 `cd services/core && go test ./...`를 통과시킨다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [TEST-1] Predecessor Gate

문제: boundary audit는 registry 전환 결과를 검토해야 하므로 01번 PASS 전에는 의미 있는 완료 판정을 할 수 없다.

해결 방법: 구현 시작 시 active/archived predecessor `complete.log`를 확인한다.

수정 파일 및 체크리스트:

- [ ] source 변경 전 predecessor `complete.log` path를 기록한다.

테스트 작성: 없음. runtime dependency는 directory name과 `complete.log` 존재로 검증한다.

중간 검증:

```bash
test -f agent-task/m-external-integration/01_provider_intake_registry/complete.log || find agent-task/archive -path '*/m-external-integration/01_*/*' -name complete.log -print
```

### [TEST-2] Adapter Boundary Search And Correction

문제: provider-specific 구현이 adapter package 밖으로 새면 새 provider마다 core service/http/workitem code가 provider별 세부를 알게 된다.

해결 방법: deterministic `rg --sort path` checks를 실행하고, 허용되지 않는 import/name이 있으면 provider-neutral registry naming으로 수정한다. Compatibility route `/api/integrations/plane/tasks`는 public backward compatibility로 허용하되, handler 내부 필드/DTO/branch 명칭은 provider-neutral이어야 한다.

수정 파일 및 체크리스트:

- [ ] `services/core/internal/http/handlers.go`: 남은 provider-specific field/DTO 제거 또는 허용 사유 기록.
- [ ] `services/core/internal/http/router.go`: compatibility route는 허용, generic route는 필수.
- [ ] `services/core/internal/workitempipeline/service.go`: adapter imports 없어야 함.
- [ ] `services/core/internal/workitem/provider.go`: adapter imports 없어야 함.

테스트 작성: boundary 누수 수정이 필요하면 `services/core/internal/http/handlers_test.go`에 regression test를 추가한다. 수정 없이 search evidence만으로 충분하면 test 추가를 생략하고 그 사유를 review stub에 기록한다.

중간 검증:

```bash
rg --sort path -n 'internal/adapters/(plane|jira|mattermost)' services/core/internal/workflow services/core/internal/workitem services/core/internal/workitempipeline services/core/internal/http
rg --sort path -n 'planeWorkItemTasks|jiraWorkItemTasks|createPlaneTaskRequest' services/core/internal/http services/core/cmd/server/main.go
```

### [TEST-3] Boundary Regression Verification

문제: boundary search만으로는 runtime behavior가 유지되는지 확인할 수 없다.

해결 방법: handler/workitem/workitempipeline package tests와 full core test를 실행한다.

수정 파일 및 체크리스트:

- [ ] `services/core/internal/http/handlers_test.go`: 필요 시 boundary regression 추가.
- [ ] `services/core/README.md`: provider-neutral endpoint 문서가 adapter 내부 detail을 노출하지 않는지 확인.

테스트 작성: 필요 시만 추가. 01번 계획에서 generic route tests가 충분히 들어갔다면 추가 테스트 없이 검증 명령으로 닫는다.

중간 검증:

```bash
cd services/core && go test -count=1 ./internal/http ./internal/workitem ./internal/workitempipeline
```

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `services/core/internal/http/handlers.go` | TEST-2 |
| `services/core/internal/http/router.go` | TEST-2 |
| `services/core/internal/http/handlers_test.go` | TEST-2, TEST-3 |
| `services/core/README.md` | TEST-3 |

## 최종 검증

```bash
test -f agent-task/m-external-integration/01_provider_intake_registry/complete.log || find agent-task/archive -path '*/m-external-integration/01_*/*' -name complete.log -print
rg --sort path -n 'internal/adapters/(plane|jira|mattermost)' services/core/internal/workflow services/core/internal/workitem services/core/internal/workitempipeline services/core/internal/http
rg --sort path -n 'planeWorkItemTasks|jiraWorkItemTasks|createPlaneTaskRequest' services/core/internal/http services/core/cmd/server/main.go
cd services/core && go test -count=1 ./internal/http ./internal/workitem ./internal/workitempipeline
cd services/core && go test ./...
git diff --check
```

`rg` 명령은 no-output 또는 documented intentional exception만 PASS로 본다. `go test ./...`의 cached output은 전체 회귀 스윕에서는 허용하고, 변경 패키지는 `-count=1`로 fresh 실행한다.

모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
