<!-- task=m-client-integration-standardization/04+03_clone_handoff_docs plan=0 tag=CIS-DOC -->

# Plan - CIS-DOC

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

`CODE_REVIEW-local-G04.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채우는 것이 필수다. 구현 후 검증 명령을 실행하고 실제 stdout/stderr를 붙여 넣은 뒤 active 파일을 그대로 두고 리뷰 준비를 보고한다. 판정, log rename, `complete.log`, archive 이동은 code-review-skill 전용이다.

## 배경

앞선 tasks가 `apps/client`, bootstrap skeleton, proto-socket, Mattermost host integration 경계를 코드로 만든 뒤에는 clone handoff를 사람이 따라갈 수 있어야 한다. Milestone은 `../iop`와 `../alt`에 전달할 checklist, IOP naming 기준, ALT alignment 기준을 완료 조건으로 둔다. 이 작업은 구현 결과를 문서화하고 Web/Android/iOS target 상태를 명확히 남긴다.

## 분석 결과

### 읽은 파일

- `agent-ops/roadmap/phase/project-workspace-management-ux/milestones/client-integration-standardization.md`
- `agent-ops/rules/project/domain/mobile/rules.md`
- `agent-ops/rules/project/domain/workspace-ops/rules.md`
- `README.md`
- `docs/monorepo.md`
- `apps/mobile/README.md`
- `apps/mobile/push-notification-todo.md`
- `packages/contracts/README.md`
- `packages/contracts/notes/flutter-core-api-candidates.md`
- `../alt/apps/client/README.md`
- `../alt/apps/client/pubspec.yaml`
- `../alt/apps/client/lib/main.dart`
- `../alt/apps/client/lib/src/app/app.dart`
- `../alt/apps/client/lib/src/app/router.dart`
- `../iop/README.md`
- `../mattermost-push-plugin/README.md`
- `../proto-socket/README.md`

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

- Documentation checklist coverage: no automated doc tests. Use deterministic `rg --sort path` checks for required headings/terms.
- Handoff accuracy: no direct clone execution in `../iop` or `../alt` because milestone scope excludes sibling repo code changes. Record exact inspection facts and replacement items.
- App runtime: docs-only task should still run `flutter test` to catch accidental code/doc path edits if docs references include examples imported by tooling.

### 심볼 참조

- No Dart symbol rename.
- Documentation terms to verify: `apps/client`, `proto_socket`, `mattermost_push_plugin`, `../iop`, `../alt`, `Web`, `Android`, `iOS`.

### 분할 판단

split decision policy를 계획 파일 선택 전에 평가했다. 이 task는 `m-client-integration-standardization/04+03_clone_handoff_docs`이며 predecessor는 `03+02_integration_boundaries`다. Docs handoff depends on final code paths and integration facts, so it is not safe to run before the integration task completes.

### 범위 결정 근거

- Do not modify `../iop` or `../alt`. Milestone explicitly asks for handoff checklist in NomadCode, not direct sibling code changes.
- Do not archive or update roadmap status. PASS completion event routing handles milestone state checks later.
- Do not create a new docs file unless existing `apps/client/README.md` and `apps/client/push-notification-todo.md` cannot carry the information. Existing files are preferred.

### 빌드 등급

- build lane: `local-G04`, review lane: `local-G04`. 이유: docs-focused task with deterministic search checks and low code risk, dependent on prior code tasks.

## 의존 관계 및 구현 순서

`03+02_integration_boundaries`가 PASS되어 `complete.log`를 만든 뒤 시작한다. 이 dependency는 directory name `04+03_clone_handoff_docs`의 source of truth와 일치한다.

## 구현 체크리스트

- [ ] [CIS-DOC-1] `apps/client` README에 client standard와 platform target status를 정리한다.
- [ ] [CIS-DOC-2] push/integration handoff notes를 host/plugin/proto-socket boundary 기준으로 갱신한다.
- [ ] [CIS-DOC-3] `../iop`와 `../alt` clone checklist와 replacement 기준을 문서화한다.
- [ ] 중간 검증과 최종 검증 명령을 실행하고 실제 출력을 기록한다.
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.

### [CIS-DOC-1] client README 표준화

#### 문제

현재 `apps/mobile/README.md:1-3`은 짧은 app 설명만 있고 client skeleton, bootstrap, Web/Android/iOS target status를 설명하지 않는다.

Before:

```markdown
# apps/mobile/README.md:1-3
# nomadcode-app

The Flutter-first NomadCode client application.
```

#### 해결 방법

predecessor 후 `apps/client/README.md`를 기준으로 다음 섹션을 추가한다:

- `Client Module Standard`: `apps/client`, Dart package name 유지, `src/app`, `src/features`, `src/integrations`.
- `Bootstrap`: common Dart bootstrap과 platform-specific guard.
- `Platform Targets`: Web, Android primary; iOS same Dart API with native follow-up.
- `Verification`: `flutter test`, `flutter analyze --no-fatal-infos`, 필요 시 `flutter build web`.

#### 수정 파일 및 체크리스트

- [ ] `apps/client/README.md`

#### 테스트 작성

새 테스트는 작성하지 않는다. README 문서 검증은 deterministic search로 한다.

#### 중간 검증

```bash
rg --sort path -n "Client Module Standard|Platform Targets|apps/client|src/app|src/features|src/integrations" apps/client/README.md
```

예상: required headings/terms 출력.

### [CIS-DOC-2] push/proto integration handoff notes 갱신

#### 문제

`apps/mobile/push-notification-todo.md:7-14`는 host app path를 `apps/mobile`로 쓰고 Mattermost push만 다룬다. Proto-socket integration boundary와 iOS follow-up status가 빠져 있다.

Before:

```markdown
# apps/mobile/push-notification-todo.md:7-14
**Do NOT edit native push files directly inside this host app repository (`apps/mobile/android`).**
...
1. **Firebase Manifest & Metadata**:
   - `google-services.json` inside `apps/mobile/android/app/`
```

#### 해결 방법

기존 파일을 historical note가 아니라 `Client Integration Handoff Notes`로 정리한다. Mattermost push는 plugin runtime owned, host owns Firebase config/auth token/signing key/routing callback/device token sync로 유지한다. Proto-socket은 `proto_socket` local dependency, endpoint config, lifecycle facade, no automatic connection by default를 기록한다.

#### 수정 파일 및 체크리스트

- [ ] `apps/client/push-notification-todo.md`
- [ ] `packages/contracts/notes/flutter-core-api-candidates.md`에 문서 링크 또는 compatibility note consistency가 필요한 경우만 갱신한다.

#### 테스트 작성

새 테스트는 작성하지 않는다. Search check로 required terms를 확인한다.

#### 중간 검증

```bash
rg --sort path -n "Client Integration Handoff|proto_socket|mattermost_push_plugin|Firebase|signing key|iOS" apps/client/push-notification-todo.md packages/contracts/notes/flutter-core-api-candidates.md
```

예상: required terms 출력.

### [CIS-DOC-3] clone handoff checklist

#### 문제

Milestone은 `../iop`와 `../alt`에 전달할 clone checklist를 요구한다. Current inspection shows `../alt/apps/client` already has `lib/src/app`, Riverpod, and go_router, while `../iop` currently documents `apps/portal` rather than `apps/client`.

Before:

```markdown
# ../alt/apps/client/README.md
This app uses Riverpod for state and dependency boundaries, and `go_router` for navigation.
```

#### 해결 방법

NomadCode docs에 sibling repo를 수정하지 않는 checklist를 남긴다.

- `../iop`: Portal naming을 강조하지 않고 `apps/client` or IOP product surface 기준으로 복제할지 별도 repo 작업에서 결정하게 한다. NomadCode에서는 "copy skeleton, not product screens"로 제한한다.
- `../alt`: existing `apps/client`, Riverpod, go_router를 유지하고 integration skeleton만 맞춘다.
- 공통 replacement: package name, app title, Firebase config, proto-socket endpoint defaults, Mattermost server/auth config, icons/display names.

#### 수정 파일 및 체크리스트

- [ ] `apps/client/README.md`
- [ ] `README.md`는 root overview link/path가 어긋난 경우만 수정한다.
- [ ] `docs/monorepo.md`는 root layout statement가 어긋난 경우만 수정한다.

#### 테스트 작성

새 테스트는 작성하지 않는다. Handoff doc search와 Flutter tests로 검증한다.

#### 중간 검증

```bash
rg --sort path -n "../iop|../alt|Riverpod|go_router|clone|checklist|replacement" apps/client/README.md apps/client/push-notification-todo.md README.md docs/monorepo.md
```

예상: required clone handoff terms 출력.

## 수정 파일 요약

| 파일 | 항목 |
|------|------|
| `apps/client/README.md` | CIS-DOC-1, CIS-DOC-3 |
| `apps/client/push-notification-todo.md` | CIS-DOC-2, CIS-DOC-3 |
| `packages/contracts/notes/flutter-core-api-candidates.md` | CIS-DOC-2 |
| `README.md` | CIS-DOC-3 if stale links remain |
| `docs/monorepo.md` | CIS-DOC-3 if stale links remain |

## 최종 검증

```bash
rg --sort path -n "Client Module Standard|Platform Targets|apps/client|src/app|src/features|src/integrations" apps/client/README.md
rg --sort path -n "Client Integration Handoff|proto_socket|mattermost_push_plugin|Firebase|signing key|iOS" apps/client/push-notification-todo.md packages/contracts/notes/flutter-core-api-candidates.md
rg --sort path -n "../iop|../alt|Riverpod|go_router|clone|checklist|replacement" apps/client/README.md apps/client/push-notification-todo.md README.md docs/monorepo.md
git diff --check
cd apps/client && flutter test
```

Go test cache 정책: 해당 없음. Flutter test cache 출력은 허용하지 않는다.

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