feat: proto-socket infrastructure communication milestone update and diagnostics
This commit is contained in:
parent
b07e61af92
commit
d0a0da8157
13 changed files with 1533 additions and 5 deletions
|
|
@ -53,9 +53,9 @@ Core가 내부 런타임 통신용 proto-socket endpoint와 task channel을 제
|
||||||
|
|
||||||
Flutter client가 no-op proto-socket facade를 실제 Core 연결 레일로 전환한다.
|
Flutter client가 no-op proto-socket facade를 실제 Core 연결 레일로 전환한다.
|
||||||
|
|
||||||
- [ ] [client-connector] `apps/client`의 `NoopProtoSocketConnector`를 대체할 concrete connector를 추가한다. 검증: 설정된 endpoint로 연결 상태가 `connected`까지 전이된다.
|
- [x] [client-connector] `apps/client`의 `NoopProtoSocketConnector`를 대체할 concrete connector를 추가한다. 검증: 설정된 endpoint로 연결 상태가 `connected`까지 전이된다.
|
||||||
- [ ] [client-task-api] workspace/task 화면이 mock 데이터 대신 Core proto-socket task channel을 소비할 수 있는 client service 경계를 만든다.
|
- [x] [client-task-api] workspace/task 화면이 mock 데이터 대신 Core proto-socket task channel을 소비할 수 있는 client service 경계를 만든다.
|
||||||
- [ ] [client-tests] proto-socket endpoint 설정, reconnect/failure lifecycle, client task service를 Flutter test로 검증한다.
|
- [x] [client-tests] proto-socket endpoint 설정, reconnect/failure lifecycle, client task service를 Flutter test로 검증한다.
|
||||||
|
|
||||||
### Epic: [ops] Observability and rollout
|
### Epic: [ops] Observability and rollout
|
||||||
|
|
||||||
|
|
@ -88,8 +88,10 @@ Flutter client가 no-op proto-socket facade를 실제 Core 연결 레일로 전
|
||||||
- 표준선(선택): 내부 런타임 간 신규 통신은 `proto-socket`을 기본 표준으로 삼고, REST/HTTP는 명시된 예외 조건에서만 유지한다.
|
- 표준선(선택): 내부 런타임 간 신규 통신은 `proto-socket`을 기본 표준으로 삼고, REST/HTTP는 명시된 예외 조건에서만 유지한다.
|
||||||
- 선행 작업: Mattermost Nexo Messaging Alignment, Client Integration Standardization, 프로젝트 룰의 proto-socket 표준 규약
|
- 선행 작업: Mattermost Nexo Messaging Alignment, Client Integration Standardization, 프로젝트 룰의 proto-socket 표준 규약
|
||||||
- 후속 작업: Workflow Core, External Integration, Project Workspace Management UX
|
- 후속 작업: Workflow Core, External Integration, Project Workspace Management UX
|
||||||
- 현재 지점: Core proto-socket endpoint와 task channel은 반영되었고, 다음 작업은 Flutter client connector와 workspace/task 화면의 Core proto-socket 소비 경계를 여는 것이다.
|
- 현재 지점: Core proto-socket endpoint, task channel, Flutter concrete connector, client task service boundary, workspace/task 화면 소비 경계는 반영되었고, 다음 작업은 diagnostics 로그와 디버그 표면을 여는 것이다.
|
||||||
- 반영 근거: `packages/contracts/notes/flutter-core-api-candidates.md`에 내부 통신 원칙, proto-socket semantic envelope 후보, REST compatibility map 후보를 추가했다.
|
- 반영 근거: `packages/contracts/notes/flutter-core-api-candidates.md`에 내부 통신 원칙, proto-socket semantic envelope 후보, REST compatibility map 후보를 추가했다.
|
||||||
- Core 반영 근거: `services/core/internal/protosocket/`, `services/core/internal/http/router.go`, `services/core/cmd/server/main.go`에 proto-socket server, task channel, task status event broadcaster, authenticated route 연결과 contract tests가 추가되었다.
|
- Core 반영 근거: `services/core/internal/protosocket/`, `services/core/internal/http/router.go`, `services/core/cmd/server/main.go`에 proto-socket server, task channel, task status event broadcaster, authenticated route 연결과 contract tests가 추가되었다.
|
||||||
|
- Client connector 반영 근거: `apps/client/lib/src/integrations/proto_socket/proto_socket_client.dart`, `apps/client/lib/src/app/bootstrap.dart`, `apps/client/lib/src/app/nomadcode_client_app.dart`에 `RealProtoSocketConnector`, endpoint-config 기반 connect, task service wiring이 추가되었다.
|
||||||
|
- Client task/test 반영 근거: `apps/client/lib/src/integrations/proto_socket/proto_socket_task_service.dart`, `apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart`, `apps/client/test/integrations/proto_socket_*_test.dart`, `apps/client/test/widget_test.dart`에 task channel 소비 경계와 endpoint/lifecycle/task service/widget 검증이 추가되었다.
|
||||||
- 운영 체크 근거: `packages/contracts/notes/flutter-core-api-candidates.md`에 새 내부 통신 추가 시 proto-socket 우선 여부, REST/HTTP 예외 기록, channel/action 문서화, 검증 항목을 확인하는 운영 체크를 추가했다.
|
- 운영 체크 근거: `packages/contracts/notes/flutter-core-api-candidates.md`에 새 내부 통신 추가 시 proto-socket 우선 여부, REST/HTTP 예외 기록, channel/action 문서화, 검증 항목을 확인하는 운영 체크를 추가했다.
|
||||||
- 확인 필요: 없음
|
- 확인 필요: 없음
|
||||||
|
|
|
||||||
|
|
@ -0,0 +1,134 @@
|
||||||
|
<!-- task=m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics plan=0 tag=API -->
|
||||||
|
|
||||||
|
# Code Review Reference - API
|
||||||
|
|
||||||
|
> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
|
||||||
|
> The task is NOT complete until every implementation-owned section below is filled in.
|
||||||
|
> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
|
||||||
|
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
|
||||||
|
> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Evidence gaps that a follow-up agent can close by rerunning commands or collecting artifacts are normal follow-up issues, not user-review blockers by themselves.
|
||||||
|
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
|
||||||
|
> Follow the ownership table at the bottom of this file for which sections you own.
|
||||||
|
|
||||||
|
## 개요
|
||||||
|
|
||||||
|
date=2026-05-30
|
||||||
|
task=m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics, plan=0, tag=API
|
||||||
|
|
||||||
|
## 이 파일을 읽는 리뷰 에이전트에게
|
||||||
|
|
||||||
|
> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
|
||||||
|
|
||||||
|
각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
|
||||||
|
리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.
|
||||||
|
|
||||||
|
1. 판정을 append한다.
|
||||||
|
2. `CODE_REVIEW-cloud-G06.md` → `code_review_cloud_G06_N.log`, `PLAN-cloud-G06.md` → `plan_cloud_G06_M.log`로 아카이브한다.
|
||||||
|
3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 사용자 결정으로 완료/PASS 해소되면 code-review가 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다.
|
||||||
|
4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
|
||||||
|
5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 구현 항목별 완료 여부
|
||||||
|
|
||||||
|
| 항목 | 완료 여부 |
|
||||||
|
|------|---------|
|
||||||
|
| [API-1] Diagnostics contract note | [x] |
|
||||||
|
|
||||||
|
## 구현 체크리스트
|
||||||
|
|
||||||
|
- [x] `packages/contracts/notes/flutter-core-api-candidates.md`에 diagnostics meta 필드, 로그 필드, client debug surface 소비 기준을 additive 후보로 정리한다.
|
||||||
|
- [ ] `git diff --check`를 허용된 원격/검증 환경에서 실행해 Markdown/whitespace 오류가 없는지 확인한다. (미실행: `agent-test/local/rules.md`가 로컬 테스트/검증을 금지한다.)
|
||||||
|
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
|
||||||
|
|
||||||
|
## 코드리뷰 전용 체크리스트
|
||||||
|
|
||||||
|
> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
|
||||||
|
> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.
|
||||||
|
|
||||||
|
- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
|
||||||
|
- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
|
||||||
|
- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G06_N.log`로 아카이브한다.
|
||||||
|
- [x] active `PLAN-*-G??.md`를 `plan_cloud_G06_M.log`로 아카이브한다.
|
||||||
|
- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하여 plan/review/archive 산출물이 추적 가능한지 확인한다.
|
||||||
|
- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
|
||||||
|
- [ ] PASS이면 active task 디렉터리 `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/`를 `agent-task/archive/YYYY/MM/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
|
||||||
|
- [ ] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
|
||||||
|
- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-proto-socket-infrastructure-communication-rail/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
|
||||||
|
- [x] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-cloud-G07.md`와 `CODE_REVIEW-cloud-G07.md`를 작성하고 `complete.log`를 작성하지 않는다.
|
||||||
|
- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
|
||||||
|
- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
|
||||||
|
|
||||||
|
## 계획 대비 변경 사항
|
||||||
|
|
||||||
|
- 구현 범위 변경 없음.
|
||||||
|
- `git diff --check`는 계획의 "허용된 원격/검증 환경" 조건에 맞는 실행 환경이 아니므로 로컬에서 실행하지 않았다.
|
||||||
|
|
||||||
|
## 주요 설계 결정
|
||||||
|
|
||||||
|
- Diagnostics 항목은 확정 schema가 아니라 기존 compatibility note의 additive 후보로 기록했다.
|
||||||
|
- `connection_id`, `protocol_version`, `channel`, `action`, `error.code`/`error_code`, `timestamp`를 최소 공통 diagnostics 필드로 분리하고 위치, 필수성, 소비자 책임을 표로 정리했다.
|
||||||
|
- Core log와 Client debug surface에는 추적 가능한 요약 필드만 허용하고 auth token, Basic Auth header, secret, payload/result 원문, provider credential은 노출 금지로 명시했다.
|
||||||
|
|
||||||
|
## 사용자 리뷰 요청
|
||||||
|
|
||||||
|
_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._
|
||||||
|
|
||||||
|
- 상태: 없음
|
||||||
|
- 사유 유형: 없음
|
||||||
|
- 결정 필요: 없음
|
||||||
|
- 차단 근거: 없음
|
||||||
|
- 실행한 검증/명령: 없음
|
||||||
|
- 자동 후속 불가 이유: 없음
|
||||||
|
- 재개 조건: 없음
|
||||||
|
|
||||||
|
## 리뷰어를 위한 체크포인트
|
||||||
|
|
||||||
|
- Diagnostics note가 additive 후보로만 기록되어 있고 확정 schema처럼 쓰이지 않았는가.
|
||||||
|
- 로그/디버그 표면 금지 대상에 auth token, payload 원문, secret이 포함되어 있는가.
|
||||||
|
- 후속 Core/Client plan이 사용할 필드명이 일관적인가.
|
||||||
|
|
||||||
|
## 검증 결과
|
||||||
|
|
||||||
|
_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._
|
||||||
|
|
||||||
|
필수 규칙:
|
||||||
|
- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
|
||||||
|
- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
|
||||||
|
- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.
|
||||||
|
- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다.
|
||||||
|
|
||||||
|
### API-1 중간 검증
|
||||||
|
```
|
||||||
|
$ git diff --check
|
||||||
|
미실행: `agent-test/local/rules.md`가 로컬 테스트/검증을 금지한다. 허용된 원격/검증 환경에서 재실행 필요.
|
||||||
|
```
|
||||||
|
|
||||||
|
### 최종 검증
|
||||||
|
```
|
||||||
|
$ git diff --check
|
||||||
|
미실행: `agent-test/local/rules.md`가 로컬 테스트/검증을 금지한다. 허용된 원격/검증 환경에서 재실행 필요.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
|
||||||
|
> If anything is blank, go back and fill it in before saving this file.
|
||||||
|
> Leave review-agent-only sections unchanged.
|
||||||
|
|
||||||
|
## 코드리뷰 결과
|
||||||
|
|
||||||
|
- 종합 판정: FAIL
|
||||||
|
- 차원별 평가:
|
||||||
|
- correctness: Pass
|
||||||
|
- completeness: Fail
|
||||||
|
- test coverage: Fail
|
||||||
|
- API contract: Pass
|
||||||
|
- code quality: Pass
|
||||||
|
- plan deviation: Fail
|
||||||
|
- verification trust: Fail
|
||||||
|
- 발견된 문제:
|
||||||
|
- Required: `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G06_0.log:42`에서 계획의 필수 검증 항목인 `git diff --check`가 미실행 상태로 남아 있고 체크리스트도 완료되지 않았습니다. `agent-test/local/rules.md` 때문에 이 세션에서 로컬 검증을 실행하지 않은 판단은 맞지만, 코드리뷰 루프의 완료 조건은 허용된 원격/검증 환경에서 실제 stdout/stderr를 남기는 것입니다. 후속 구현은 허용된 검증 환경에서 `git diff --check`를 실행하고, 성공한 실제 출력 또는 무출력 성공 사실을 `검증 결과`에 기록한 뒤 체크해야 합니다.
|
||||||
|
- Required: `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G06_0.log:42`의 구현 체크리스트 문구가 `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/plan_cloud_G06_0.log`의 동일 항목에 없는 미실행 설명을 덧붙여 원 계획과 정확히 일치하지 않습니다. 후속 구현은 체크리스트 텍스트를 계획과 동일하게 복원하고, 미실행/실행 근거는 `계획 대비 변경 사항`과 `검증 결과`에만 기록해야 합니다.
|
||||||
|
- 다음 단계: FAIL 후속으로 동일 task directory에 `PLAN-cloud-G07.md`와 `CODE_REVIEW-cloud-G07.md`를 작성한다.
|
||||||
|
|
@ -0,0 +1,133 @@
|
||||||
|
<!-- task=m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics plan=1 tag=REVIEW_API -->
|
||||||
|
|
||||||
|
# Code Review Reference - REVIEW_API
|
||||||
|
|
||||||
|
> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
|
||||||
|
> The task is NOT complete until every implementation-owned section below is filled in.
|
||||||
|
> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
|
||||||
|
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
|
||||||
|
> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Evidence gaps that a follow-up agent can close by rerunning commands or collecting artifacts are normal follow-up issues, not user-review blockers by themselves.
|
||||||
|
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
|
||||||
|
> Follow the ownership table at the bottom of this file for which sections you own.
|
||||||
|
|
||||||
|
## 개요
|
||||||
|
|
||||||
|
date=2026-05-30
|
||||||
|
task=m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics, plan=1, tag=REVIEW_API
|
||||||
|
|
||||||
|
## 이 파일을 읽는 리뷰 에이전트에게
|
||||||
|
|
||||||
|
> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
|
||||||
|
|
||||||
|
각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
|
||||||
|
리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.
|
||||||
|
|
||||||
|
1. 판정을 append한다.
|
||||||
|
2. `CODE_REVIEW-cloud-G07.md` -> `code_review_cloud_G07_N.log`, `PLAN-cloud-G07.md` -> `plan_cloud_G07_M.log`로 아카이브한다.
|
||||||
|
3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 사용자 결정으로 완료/PASS 해소되면 code-review가 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다.
|
||||||
|
4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
|
||||||
|
5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 구현 항목별 완료 여부
|
||||||
|
|
||||||
|
| 항목 | 완료 여부 |
|
||||||
|
|------|---------|
|
||||||
|
| [REVIEW_API-1] Verification trust recovery | [ ] |
|
||||||
|
|
||||||
|
## 구현 체크리스트
|
||||||
|
|
||||||
|
- [ ] `CODE_REVIEW-cloud-G07.md`의 구현 체크리스트가 이 계획과 같은 문구와 순서를 유지하는지 확인하고, 체크박스 외의 문구를 수정하지 않는다.
|
||||||
|
- [ ] 허용된 원격/검증 환경에서 `git diff --check`를 실행하고 실제 stdout/stderr 또는 무출력 성공 사실을 `CODE_REVIEW-cloud-G07.md`의 `검증 결과`에 기록한다.
|
||||||
|
- [ ] `git diff --check`가 Markdown/whitespace 문제를 보고하면 `packages/contracts/notes/flutter-core-api-candidates.md`의 해당 문제만 최소 수정하고 diagnostics 후보의 의미 범위는 바꾸지 않는다.
|
||||||
|
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
|
||||||
|
|
||||||
|
## 코드리뷰 전용 체크리스트
|
||||||
|
|
||||||
|
> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
|
||||||
|
> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.
|
||||||
|
|
||||||
|
- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
|
||||||
|
- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
|
||||||
|
- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G07_N.log`로 아카이브한다.
|
||||||
|
- [x] active `PLAN-*-G??.md`를 `plan_cloud_G07_M.log`로 아카이브한다.
|
||||||
|
- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하여 plan/review/archive 산출물이 추적 가능한지 확인한다.
|
||||||
|
- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
|
||||||
|
- [ ] PASS이면 active task 디렉터리 `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/`를 `agent-task/archive/YYYY/MM/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
|
||||||
|
- [ ] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
|
||||||
|
- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-proto-socket-infrastructure-communication-rail/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
|
||||||
|
- [x] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-cloud-G07.md`와 `CODE_REVIEW-cloud-G07.md`를 작성하고 `complete.log`를 작성하지 않는다.
|
||||||
|
- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
|
||||||
|
- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
|
||||||
|
|
||||||
|
## 계획 대비 변경 사항
|
||||||
|
|
||||||
|
_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._
|
||||||
|
|
||||||
|
## 주요 설계 결정
|
||||||
|
|
||||||
|
_구현 에이전트가 주요 설계 결정 사항을 기록한다._
|
||||||
|
|
||||||
|
## 사용자 리뷰 요청
|
||||||
|
|
||||||
|
_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._
|
||||||
|
|
||||||
|
- 상태: 없음
|
||||||
|
- 사유 유형: 없음
|
||||||
|
- 결정 필요: 없음
|
||||||
|
- 차단 근거: 없음
|
||||||
|
- 실행한 검증/명령: 없음
|
||||||
|
- 자동 후속 불가 이유: 없음
|
||||||
|
- 재개 조건: 없음
|
||||||
|
|
||||||
|
## 리뷰어를 위한 체크포인트
|
||||||
|
|
||||||
|
- 구현 체크리스트 문구와 순서가 `PLAN-cloud-G07.md`와 정확히 일치하는가.
|
||||||
|
- `git diff --check`의 실제 stdout/stderr 또는 무출력 성공 사실이 허용된 검증 환경에서 기록되었는가.
|
||||||
|
- `packages/contracts/notes/flutter-core-api-candidates.md`가 수정되었다면 Markdown/whitespace 최소 수정만 이루어졌는가.
|
||||||
|
|
||||||
|
## 검증 결과
|
||||||
|
|
||||||
|
_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._
|
||||||
|
|
||||||
|
필수 규칙:
|
||||||
|
- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
|
||||||
|
- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
|
||||||
|
- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.
|
||||||
|
- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다.
|
||||||
|
|
||||||
|
### REVIEW_API-1 중간 검증
|
||||||
|
```
|
||||||
|
$ git diff --check
|
||||||
|
(output)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 최종 검증
|
||||||
|
```
|
||||||
|
$ git diff --check
|
||||||
|
(output)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
|
||||||
|
> If anything is blank, go back and fill it in before saving this file.
|
||||||
|
> Leave review-agent-only sections unchanged.
|
||||||
|
|
||||||
|
## 코드리뷰 결과
|
||||||
|
|
||||||
|
- 종합 판정: FAIL
|
||||||
|
- 차원별 평가:
|
||||||
|
- correctness: Pass
|
||||||
|
- completeness: Fail
|
||||||
|
- test coverage: Fail
|
||||||
|
- API contract: Pass
|
||||||
|
- code quality: Pass
|
||||||
|
- plan deviation: Fail
|
||||||
|
- verification trust: Fail
|
||||||
|
- 발견된 문제:
|
||||||
|
- Required: `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G07_1.log:37`에서 구현 항목 완료 여부가 미체크 상태이고, `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G07_1.log:41`부터 `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G07_1.log:44`까지의 구현 체크리스트도 전부 미완료입니다. 후속 구현은 계획된 항목을 실제로 수행한 뒤 각 체크박스를 완료해야 합니다.
|
||||||
|
- Required: `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G07_1.log:66`과 `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G07_1.log:70`의 구현자 소유 섹션이 placeholder 그대로 남아 있습니다. 후속 구현은 계획 대비 변경 사항과 주요 설계 결정을 실제 수행 내용으로 교체해야 합니다.
|
||||||
|
- Required: `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G07_1.log:100`부터 `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G07_1.log:109`까지 `git diff --check` 검증 출력이 `(output)` placeholder 그대로라 필수 검증 증거가 없습니다. 후속 구현은 허용된 원격/검증 환경에서 `git diff --check`를 실행하고 실제 stdout/stderr 또는 무출력 성공과 exit 0을 기록해야 합니다.
|
||||||
|
- 다음 단계: FAIL 후속으로 동일 task directory에 `PLAN-cloud-G07.md`와 `CODE_REVIEW-cloud-G07.md`를 작성한다.
|
||||||
|
|
@ -0,0 +1,135 @@
|
||||||
|
<!-- task=m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics plan=2 tag=REVIEW_REVIEW_API -->
|
||||||
|
|
||||||
|
# Code Review Reference - REVIEW_REVIEW_API
|
||||||
|
|
||||||
|
> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
|
||||||
|
> The task is NOT complete until every implementation-owned section below is filled in.
|
||||||
|
> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
|
||||||
|
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
|
||||||
|
> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Evidence gaps that a follow-up agent can close by rerunning commands or collecting artifacts are normal follow-up issues, not user-review blockers by themselves.
|
||||||
|
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
|
||||||
|
> Follow the ownership table at the bottom of this file for which sections you own.
|
||||||
|
|
||||||
|
## 개요
|
||||||
|
|
||||||
|
date=2026-05-30
|
||||||
|
task=m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics, plan=2, tag=REVIEW_REVIEW_API
|
||||||
|
|
||||||
|
## 이 파일을 읽는 리뷰 에이전트에게
|
||||||
|
|
||||||
|
> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
|
||||||
|
|
||||||
|
각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
|
||||||
|
리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.
|
||||||
|
|
||||||
|
1. 판정을 append한다.
|
||||||
|
2. `CODE_REVIEW-cloud-G07.md` -> `code_review_cloud_G07_N.log`, `PLAN-cloud-G07.md` -> `plan_cloud_G07_M.log`로 아카이브한다.
|
||||||
|
3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 사용자 결정으로 완료/PASS 해소되면 code-review가 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다.
|
||||||
|
4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
|
||||||
|
5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 구현 항목별 완료 여부
|
||||||
|
|
||||||
|
| 항목 | 완료 여부 |
|
||||||
|
|------|---------|
|
||||||
|
| [REVIEW_REVIEW_API-1] Complete review stub and verification evidence | [x] |
|
||||||
|
|
||||||
|
## 구현 체크리스트
|
||||||
|
|
||||||
|
- [x] `CODE_REVIEW-cloud-G07.md`의 구현 체크리스트가 이 계획과 같은 문구와 순서를 유지하는지 확인하고, 체크박스 외의 문구를 수정하지 않는다.
|
||||||
|
- [x] 허용된 원격/검증 환경에서 `git diff --check`를 실행하고 실제 stdout/stderr 또는 무출력 성공 사실과 exit 0을 `CODE_REVIEW-cloud-G07.md`의 `검증 결과`에 기록한다.
|
||||||
|
- [x] `git diff --check`가 Markdown/whitespace 문제를 보고하면 `packages/contracts/notes/flutter-core-api-candidates.md`의 해당 문제만 최소 수정하고 diagnostics 후보의 의미 범위는 바꾸지 않는다.
|
||||||
|
- [x] `CODE_REVIEW-cloud-G07.md`의 구현 항목별 완료 여부, 구현 체크리스트, 계획 대비 변경 사항, 주요 설계 결정, 검증 결과를 placeholder 없이 실제 내용으로 채운다.
|
||||||
|
- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
|
||||||
|
|
||||||
|
## 코드리뷰 전용 체크리스트
|
||||||
|
|
||||||
|
> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
|
||||||
|
> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.
|
||||||
|
|
||||||
|
- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
|
||||||
|
- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
|
||||||
|
- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G07_N.log`로 아카이브한다.
|
||||||
|
- [x] active `PLAN-*-G??.md`를 `plan_cloud_G07_M.log`로 아카이브한다.
|
||||||
|
- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하여 plan/review/archive 산출물이 추적 가능한지 확인한다.
|
||||||
|
- [x] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
|
||||||
|
- [x] PASS이면 active task 디렉터리 `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/`를 `agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
|
||||||
|
- [x] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
|
||||||
|
- [x] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-proto-socket-infrastructure-communication-rail/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
|
||||||
|
- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-cloud-G07.md`와 `CODE_REVIEW-cloud-G07.md`를 작성하고 `complete.log`를 작성하지 않는다.
|
||||||
|
- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
|
||||||
|
- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
|
||||||
|
|
||||||
|
## 계획 대비 변경 사항
|
||||||
|
|
||||||
|
- 계획 대비 변경 없음.
|
||||||
|
- `git diff --check`가 출력 없이 exit 0으로 통과했으므로 `packages/contracts/notes/flutter-core-api-candidates.md`의 Markdown/whitespace 수정은 하지 않았다.
|
||||||
|
|
||||||
|
## 주요 설계 결정
|
||||||
|
|
||||||
|
- G07 범위는 review stub completion과 verification evidence 회복으로 제한했다.
|
||||||
|
- diagnostics 후보 계약의 의미는 G06 구현 그대로 유지했고, 계약 문서의 의미 변경은 하지 않았다.
|
||||||
|
- 구현 체크리스트는 `PLAN-cloud-G07.md`와 같은 문구와 순서를 유지하고 체크박스만 완료 상태로 바꿨다.
|
||||||
|
|
||||||
|
## 사용자 리뷰 요청
|
||||||
|
|
||||||
|
_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._
|
||||||
|
|
||||||
|
- 상태: 없음
|
||||||
|
- 사유 유형: 없음
|
||||||
|
- 결정 필요: 없음
|
||||||
|
- 차단 근거: 없음
|
||||||
|
- 실행한 검증/명령: 없음
|
||||||
|
- 자동 후속 불가 이유: 없음
|
||||||
|
- 재개 조건: 없음
|
||||||
|
|
||||||
|
## 리뷰어를 위한 체크포인트
|
||||||
|
|
||||||
|
- 구현 체크리스트 문구와 순서가 `PLAN-cloud-G07.md`와 정확히 일치하는가.
|
||||||
|
- 구현 항목별 완료 여부, 구현 체크리스트, 계획 대비 변경 사항, 주요 설계 결정, 검증 결과가 placeholder 없이 채워졌는가.
|
||||||
|
- `git diff --check`의 실제 stdout/stderr 또는 무출력 성공과 exit 0이 허용된 검증 환경에서 기록되었는가.
|
||||||
|
- `packages/contracts/notes/flutter-core-api-candidates.md`가 수정되었다면 Markdown/whitespace 최소 수정만 이루어졌는가.
|
||||||
|
|
||||||
|
## 검증 결과
|
||||||
|
|
||||||
|
_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._
|
||||||
|
|
||||||
|
필수 규칙:
|
||||||
|
- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
|
||||||
|
- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
|
||||||
|
- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.
|
||||||
|
- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다.
|
||||||
|
|
||||||
|
### REVIEW_REVIEW_API-1 중간 검증
|
||||||
|
```
|
||||||
|
$ git diff --check
|
||||||
|
출력 없음, exit 0
|
||||||
|
```
|
||||||
|
|
||||||
|
### 최종 검증
|
||||||
|
```
|
||||||
|
$ git diff --check
|
||||||
|
출력 없음, exit 0
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
|
||||||
|
> If anything is blank, go back and fill it in before saving this file.
|
||||||
|
> Leave review-agent-only sections unchanged.
|
||||||
|
|
||||||
|
## 코드리뷰 결과
|
||||||
|
|
||||||
|
- 종합 판정: PASS
|
||||||
|
- 차원별 평가:
|
||||||
|
- correctness: Pass
|
||||||
|
- completeness: Pass
|
||||||
|
- test coverage: Pass
|
||||||
|
- API contract: Pass
|
||||||
|
- code quality: Pass
|
||||||
|
- plan deviation: Pass
|
||||||
|
- verification trust: Pass
|
||||||
|
- 발견된 문제: 없음
|
||||||
|
- 다음 단계: PASS로 `complete.log` 작성 후 active task directory를 archive로 이동한다.
|
||||||
|
|
@ -0,0 +1,36 @@
|
||||||
|
# Complete - m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics
|
||||||
|
|
||||||
|
## 완료 일시
|
||||||
|
|
||||||
|
2026-05-30
|
||||||
|
|
||||||
|
## 요약
|
||||||
|
|
||||||
|
Diagnostics contract note 작업을 3회 리뷰 루프 끝에 PASS로 종결했다.
|
||||||
|
|
||||||
|
## 루프 이력
|
||||||
|
|
||||||
|
| Plan | Review | Verdict | 메모 |
|
||||||
|
|------|--------|---------|------|
|
||||||
|
| `plan_cloud_G06_0.log` | `code_review_cloud_G06_0.log` | FAIL | `git diff --check` 검증 증거 누락과 plan/review 체크리스트 불일치로 follow-up 생성 |
|
||||||
|
| `plan_cloud_G07_1.log` | `code_review_cloud_G07_1.log` | FAIL | 구현자 소유 섹션과 검증 결과가 placeholder 상태로 남아 follow-up 생성 |
|
||||||
|
| `plan_cloud_G07_2.log` | `code_review_cloud_G07_2.log` | PASS | 구현자 소유 섹션, 체크리스트, 검증 증거가 완료되어 PASS |
|
||||||
|
|
||||||
|
## 구현/정리 내용
|
||||||
|
|
||||||
|
- `packages/contracts/notes/flutter-core-api-candidates.md`에 proto-socket diagnostics 필드 후보를 additive compatibility note로 추가했다.
|
||||||
|
- `connection_id`, `protocol_version`, `channel`, `action`, `error.code`/`error_code`, `timestamp`의 위치, 필수성, 소비자 책임을 정리했다.
|
||||||
|
- Core log와 Client debug surface에서 auth token, Basic Auth header, secret, payload/result 원문, provider credential을 노출하지 않도록 명시했다.
|
||||||
|
- follow-up 루프에서 review stub completion과 `git diff --check` 검증 증거를 회복했다.
|
||||||
|
|
||||||
|
## 최종 검증
|
||||||
|
|
||||||
|
- `git diff --check` - PASS; `code_review_cloud_G07_2.log`에 출력 없음, exit 0으로 기록됨.
|
||||||
|
|
||||||
|
## 잔여 Nit
|
||||||
|
|
||||||
|
- 없음
|
||||||
|
|
||||||
|
## 후속 작업
|
||||||
|
|
||||||
|
- 없음
|
||||||
|
|
@ -0,0 +1,162 @@
|
||||||
|
<!-- task=m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics plan=0 tag=API -->
|
||||||
|
|
||||||
|
# Plan - API Diagnostics Contract
|
||||||
|
|
||||||
|
## 이 파일을 읽는 구현 에이전트에게
|
||||||
|
|
||||||
|
`CODE_REVIEW-cloud-G06.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 반드시 채운다. 구현 후 검증을 실행하고 active 파일은 그대로 둔 채 리뷰 준비를 보고한다. 최종 판정, log rename, `complete.log`, archive 이동은 code-review-skill 전용이다. 사용자 결정, 사용자 소유 외부 환경, 범위 충돌로 막히면 review stub의 `사용자 리뷰 요청` 섹션에 정확한 근거와 재개 조건을 채우고 멈춘다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 닫을 수 있는 증거 공백은 사용자 리뷰 요청이 아니다.
|
||||||
|
|
||||||
|
## 배경
|
||||||
|
|
||||||
|
`diagnostics` 작업은 connection id, protocol version, channel name, error code를 로그와 디버그 표면에서 확인 가능하게 해야 한다. 현재 contracts note에는 envelope meta 예시만 있고, diagnostics 필드의 필수/선택 의미와 consumer 책임이 분리되어 있지 않다. Core와 Client 구현 전에 문서 후보를 먼저 고정해 후속 split 작업의 기준으로 삼는다.
|
||||||
|
|
||||||
|
## 사용자 리뷰 요청 흐름
|
||||||
|
|
||||||
|
구현 중 차단 사유는 active review stub의 `사용자 리뷰 요청` 섹션에 기록한다. 이 섹션은 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`를 기준으로 하며, code-review가 검증 후 실제 `USER_REVIEW.md` 작성 여부를 결정한다.
|
||||||
|
|
||||||
|
## 분석 결과
|
||||||
|
|
||||||
|
### 읽은 파일
|
||||||
|
|
||||||
|
- `agent-ops/rules/project/rules.md`
|
||||||
|
- `agent-ops/rules/private/rules.md`
|
||||||
|
- `agent-ops/rules/common/rules-roadmap.md`
|
||||||
|
- `agent-ops/skills/common/router.md`
|
||||||
|
- `agent-ops/skills/common/plan/SKILL.md`
|
||||||
|
- `agent-ops/skills/common/update-roadmap/SKILL.md`
|
||||||
|
- `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`
|
||||||
|
- `agent-roadmap/current.md`
|
||||||
|
- `agent-roadmap/phase/workflow-core/PHASE.md`
|
||||||
|
- `agent-roadmap/phase/external-integration/PHASE.md`
|
||||||
|
- `agent-roadmap/phase/workflow-core/milestones/proto-socket-infrastructure-communication-rail.md`
|
||||||
|
- `agent-ops/rules/project/domain/workspace-ops/rules.md`
|
||||||
|
- `agent-ops/rules/project/domain/mobile/rules.md`
|
||||||
|
- `agent-ops/rules/project/domain/core/rules.md`
|
||||||
|
- `agent-ops/rules/project/domain/contracts/rules.md`
|
||||||
|
- `agent-test/local/rules.md`
|
||||||
|
- `agent-test/local/contracts-smoke.md`
|
||||||
|
- `agent-test/local/core-smoke.md`
|
||||||
|
- `agent-test/local/mobile-smoke.md`
|
||||||
|
- `agent-test/local/workspace-ops-smoke.md`
|
||||||
|
- `packages/contracts/README.md`
|
||||||
|
- `packages/contracts/notes/flutter-core-api-candidates.md`
|
||||||
|
- `services/core/internal/protosocket/server.go`
|
||||||
|
- `services/core/internal/protosocket/dispatcher.go`
|
||||||
|
- `services/core/internal/protosocket/envelope.go`
|
||||||
|
- `services/core/internal/protosocket/events.go`
|
||||||
|
- `services/core/internal/protosocket/tasks.go`
|
||||||
|
- `services/core/internal/http/router.go`
|
||||||
|
- `services/core/internal/protosocket/server_test.go`
|
||||||
|
- `services/core/internal/protosocket/tasks_test.go`
|
||||||
|
- `services/core/internal/protosocket/envelope_test.go`
|
||||||
|
- `apps/client/pubspec.yaml`
|
||||||
|
- `apps/client/analysis_options.yaml`
|
||||||
|
- `apps/client/lib/src/app/bootstrap.dart`
|
||||||
|
- `apps/client/lib/src/app/nomadcode_client_app.dart`
|
||||||
|
- `apps/client/lib/src/integrations/proto_socket/proto_socket_client.dart`
|
||||||
|
- `apps/client/lib/src/integrations/proto_socket/proto_socket_endpoint_config.dart`
|
||||||
|
- `apps/client/lib/src/integrations/proto_socket/proto_socket_envelope.dart`
|
||||||
|
- `apps/client/lib/src/integrations/proto_socket/proto_socket_lifecycle.dart`
|
||||||
|
- `apps/client/lib/src/integrations/proto_socket/proto_socket_task_service.dart`
|
||||||
|
- `apps/client/lib/src/features/workspaces/domain/project_workspace.dart`
|
||||||
|
- `apps/client/lib/src/features/workspaces/domain/workspace_task.dart`
|
||||||
|
- `apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart`
|
||||||
|
- `apps/client/test/integrations/proto_socket_endpoint_config_test.dart`
|
||||||
|
- `apps/client/test/integrations/proto_socket_envelope_test.dart`
|
||||||
|
- `apps/client/test/integrations/proto_socket_lifecycle_test.dart`
|
||||||
|
- `apps/client/test/integrations/proto_socket_task_service_test.dart`
|
||||||
|
- `apps/client/test/widget_test.dart`
|
||||||
|
|
||||||
|
### 테스트 환경 규칙
|
||||||
|
|
||||||
|
`test_env=local`로 판단했고 `agent-test/local/rules.md`를 읽었다. 이 파일은 로컬 테스트 금지를 명시하므로 현 세션에서는 검증 명령을 실행하지 않는다. 적용 profile은 `contracts-smoke`, `workspace-ops-smoke`이며, contracts 변경의 자동 test command는 없고 문서 링크/경로 수동 확인과 `git diff --check`가 보조 검증이다. 후속 구현/리뷰 에이전트는 사용자 또는 런타임이 허용한 원격/검증 환경에서 명령을 실행해야 한다.
|
||||||
|
|
||||||
|
### 테스트 커버리지 공백
|
||||||
|
|
||||||
|
- Diagnostics contract note 보강: 자동 테스트 없음. `git diff --check`와 후속 Core/Client plan의 테스트가 소비자 검증을 담당한다.
|
||||||
|
|
||||||
|
### 심볼 참조
|
||||||
|
|
||||||
|
none. 이 subtask는 symbol rename/remove를 하지 않는다.
|
||||||
|
|
||||||
|
### 분할 판단
|
||||||
|
|
||||||
|
split decision policy를 먼저 평가했다. 전체 diagnostics 작업은 contracts, core, mobile 경계를 동시에 건드리고 protocol/schema 및 UI debug surface 리스크가 달라 multi-plan으로 분할한다. 공유 task group은 `m-proto-socket-infrastructure-communication-rail`이다.
|
||||||
|
|
||||||
|
- `11_contracts_diagnostics`: 선행 diagnostics field 계약 정리, dependency 없음.
|
||||||
|
- `12+11_core_diagnostics`: Core 로그/meta 구현, `11` 완료 필요. 현재 predecessor `11`은 active/archive `complete.log` 없음.
|
||||||
|
- `13+11,12_client_diagnostics`: Client 디버그 표면 구현, `11`, `12` 완료 필요. 현재 predecessor `11`, `12`는 active/archive `complete.log` 없음.
|
||||||
|
|
||||||
|
### 범위 결정 근거
|
||||||
|
|
||||||
|
이 subtask는 `packages/contracts/notes/flutter-core-api-candidates.md`만 수정한다. Go core 구현, Flutter client 구현, generated schema 도입은 후속 subtasks로 분리한다. 실제 source schema가 아직 없으므로 후보 note에만 additive로 기록한다.
|
||||||
|
|
||||||
|
### 빌드 등급
|
||||||
|
|
||||||
|
`cloud-G06`: 문서 변경이지만 protocol/schema 후보를 고정하고 후속 core/client 구현의 기준이 되므로 cloud review가 적합하다.
|
||||||
|
|
||||||
|
## 구현 체크리스트
|
||||||
|
|
||||||
|
- [ ] `packages/contracts/notes/flutter-core-api-candidates.md`에 diagnostics meta 필드, 로그 필드, client debug surface 소비 기준을 additive 후보로 정리한다.
|
||||||
|
- [ ] `git diff --check`를 허용된 원격/검증 환경에서 실행해 Markdown/whitespace 오류가 없는지 확인한다.
|
||||||
|
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
|
||||||
|
|
||||||
|
### [API-1] Diagnostics Contract Note
|
||||||
|
|
||||||
|
#### 문제
|
||||||
|
|
||||||
|
[packages/contracts/notes/flutter-core-api-candidates.md](/config/workspace/nomadcode/packages/contracts/notes/flutter-core-api-candidates.md:49)는 `meta.connection_id` 예시만 있고 protocol version, channel, action, error code를 로그/디버그 표면에서 어떻게 다룰지 명시하지 않는다.
|
||||||
|
|
||||||
|
Before:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
49 "meta": {
|
||||||
|
50 "connection_id": "conn-id",
|
||||||
|
51 "timestamp": "2026-05-30T00:00:00Z"
|
||||||
|
52 }
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 해결 방법
|
||||||
|
|
||||||
|
`1.2 proto-socket Semantic Envelope 후보` 뒤 또는 `1.5 Task Channel Actions` 뒤에 `Diagnostics 필드 후보` subsection을 추가한다. 최소 필드는 `connection_id`, `protocol_version`, `channel`, `action`, `error.code`, `timestamp`로 두고, secret/token/payload 원문은 로그와 UI debug surface에 노출하지 않는다고 적는다.
|
||||||
|
|
||||||
|
After:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
### 1.x Diagnostics 필드 후보
|
||||||
|
- Core log attributes: `connection_id`, `protocol_version`, `channel`, `action`, `error_code`.
|
||||||
|
- Envelope meta: response/event는 가능한 경우 `connection_id`, `protocol_version`, `channel`, `action`을 포함한다.
|
||||||
|
- Client debug surface: 연결 상태, connection id, protocol version, 최근 channel/action/error code만 표시하고 auth/payload 원문은 표시하지 않는다.
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 수정 파일 및 체크리스트
|
||||||
|
|
||||||
|
- [ ] `packages/contracts/notes/flutter-core-api-candidates.md`: diagnostics subsection 추가.
|
||||||
|
|
||||||
|
#### 테스트 작성
|
||||||
|
|
||||||
|
자동 테스트는 작성하지 않는다. contracts 도메인은 현재 README/compatibility note 중심이고 `agent-test/local/contracts-smoke.md`에도 확인된 자동 test command가 없다.
|
||||||
|
|
||||||
|
#### 중간 검증
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git diff --check
|
||||||
|
```
|
||||||
|
|
||||||
|
기대 결과: 출력 없이 종료한다. 현 세션에서는 local 테스트 금지 규칙 때문에 실행하지 않는다.
|
||||||
|
|
||||||
|
## 수정 파일 요약
|
||||||
|
|
||||||
|
| 파일 | 항목 |
|
||||||
|
|------|------|
|
||||||
|
| `packages/contracts/notes/flutter-core-api-candidates.md` | API-1 |
|
||||||
|
|
||||||
|
## 최종 검증
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git diff --check
|
||||||
|
```
|
||||||
|
|
||||||
|
기대 결과: 출력 없이 종료한다. 명령은 허용된 원격/검증 환경에서 실행한다.
|
||||||
|
|
||||||
|
모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
|
||||||
|
|
@ -0,0 +1,86 @@
|
||||||
|
<!-- task=m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics plan=1 tag=REVIEW_API -->
|
||||||
|
|
||||||
|
# Plan - REVIEW_API Verification Trust Recovery
|
||||||
|
|
||||||
|
## 이 파일을 읽는 구현 에이전트에게
|
||||||
|
|
||||||
|
`CODE_REVIEW-cloud-G07.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 반드시 채운다. 구현 후 검증을 실행하고 active 파일은 그대로 둔 채 리뷰 준비를 보고한다. 최종 판정, log rename, `complete.log`, archive 이동은 code-review-skill 전용이다. 사용자 결정, 사용자 소유 외부 환경, 범위 충돌로 막히면 review stub의 `사용자 리뷰 요청` 섹션에 정확한 근거와 재개 조건을 채우고 멈춘다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 닫을 수 있는 증거 공백은 사용자 리뷰 요청이 아니다.
|
||||||
|
|
||||||
|
## 배경
|
||||||
|
|
||||||
|
G06 구현은 `packages/contracts/notes/flutter-core-api-candidates.md`에 diagnostics 후보를 additive로 추가했지만, 필수 검증인 `git diff --check`를 허용된 원격/검증 환경에서 실행한 실제 stdout/stderr를 남기지 못했다. 또한 active review stub의 `구현 체크리스트` 항목 문구가 원 계획과 다르게 수정되어 plan/review 체크리스트 일치 규칙을 깨뜨렸다.
|
||||||
|
|
||||||
|
## 사용자 리뷰 요청 흐름
|
||||||
|
|
||||||
|
구현 중 차단 사유는 active review stub의 `사용자 리뷰 요청` 섹션에 기록한다. 이 섹션은 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`를 기준으로 하며, code-review가 검증 후 실제 `USER_REVIEW.md` 작성 여부를 결정한다.
|
||||||
|
|
||||||
|
## 이전 리뷰 결과
|
||||||
|
|
||||||
|
- Archived plan: `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/plan_cloud_G06_0.log`
|
||||||
|
- Archived review: `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G06_0.log`
|
||||||
|
- Verdict: FAIL
|
||||||
|
- Required:
|
||||||
|
- `CODE_REVIEW-cloud-G06.md`의 `git diff --check` 검증 항목이 미실행/미완료 상태였다.
|
||||||
|
- `CODE_REVIEW-cloud-G06.md`의 구현 체크리스트 문구가 `PLAN-cloud-G06.md`와 정확히 일치하지 않았다.
|
||||||
|
|
||||||
|
## 범위 결정 근거
|
||||||
|
|
||||||
|
이 follow-up은 verification trust와 loop completeness만 회복한다. `packages/contracts/notes/flutter-core-api-candidates.md`의 diagnostics 후보 내용은 G06 리뷰에서 범위와 계약 의도에 맞는 것으로 확인되었으므로, `git diff --check`가 지적하는 Markdown/whitespace 문제가 없으면 source 문서를 수정하지 않는다. 문제가 있으면 해당 Markdown/whitespace만 최소 수정한다.
|
||||||
|
|
||||||
|
## 빌드 등급
|
||||||
|
|
||||||
|
`cloud-G07`: G06의 실패 원인이 누락된 검증 증거와 체크리스트 신뢰 문제이며, 후속 성공 조건이 실제 명령 stdout/stderr 기록에 의존한다. verification trust recovery 규칙에 따라 `cloud-G07`로 승격한다.
|
||||||
|
|
||||||
|
## 구현 체크리스트
|
||||||
|
|
||||||
|
- [ ] `CODE_REVIEW-cloud-G07.md`의 구현 체크리스트가 이 계획과 같은 문구와 순서를 유지하는지 확인하고, 체크박스 외의 문구를 수정하지 않는다.
|
||||||
|
- [ ] 허용된 원격/검증 환경에서 `git diff --check`를 실행하고 실제 stdout/stderr 또는 무출력 성공 사실을 `CODE_REVIEW-cloud-G07.md`의 `검증 결과`에 기록한다.
|
||||||
|
- [ ] `git diff --check`가 Markdown/whitespace 문제를 보고하면 `packages/contracts/notes/flutter-core-api-candidates.md`의 해당 문제만 최소 수정하고 diagnostics 후보의 의미 범위는 바꾸지 않는다.
|
||||||
|
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
|
||||||
|
|
||||||
|
### [REVIEW_API-1] Verification Trust Recovery
|
||||||
|
|
||||||
|
#### 문제
|
||||||
|
|
||||||
|
`code_review_cloud_G06_0.log`에는 `git diff --check`가 미실행으로 기록되어 있고, 구현 체크리스트 두 번째 항목도 미완료 상태였다. 코드리뷰 루프는 필수 검증 항목의 실제 stdout/stderr 또는 무출력 성공 증거 없이는 PASS할 수 없다.
|
||||||
|
|
||||||
|
#### 해결 방법
|
||||||
|
|
||||||
|
1. `CODE_REVIEW-cloud-G07.md`의 `구현 체크리스트` 텍스트가 이 plan의 체크리스트와 정확히 같은지 먼저 확인한다.
|
||||||
|
2. 허용된 원격/검증 환경에서 repo root 기준으로 `git diff --check`를 실행한다.
|
||||||
|
3. 명령이 성공하고 출력이 없으면 "출력 없음, exit 0"처럼 무출력 성공 사실을 `검증 결과`에 기록한다.
|
||||||
|
4. 명령이 whitespace/Markdown diff 문제를 보고하면 해당 파일의 문제만 최소 수정한 뒤 같은 명령을 재실행하고 최종 성공 출력을 기록한다.
|
||||||
|
|
||||||
|
#### 수정 파일 및 체크리스트
|
||||||
|
|
||||||
|
- [ ] `CODE_REVIEW-cloud-G07.md`: 구현 체크리스트 텍스트 유지, 검증 출력 기록.
|
||||||
|
- [ ] `packages/contracts/notes/flutter-core-api-candidates.md`: `git diff --check`가 지적한 경우에만 Markdown/whitespace 최소 수정.
|
||||||
|
|
||||||
|
#### 테스트 작성
|
||||||
|
|
||||||
|
자동 테스트는 작성하지 않는다. contracts 도메인의 현재 확인된 자동 test command는 없으며, 이번 follow-up의 목적은 문서 변경에 대한 `git diff --check` 증거 회복이다.
|
||||||
|
|
||||||
|
#### 중간 검증
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git diff --check
|
||||||
|
```
|
||||||
|
|
||||||
|
기대 결과: 출력 없이 종료한다. 출력이 없으면 review stub에 무출력 성공과 exit 0을 명시한다.
|
||||||
|
|
||||||
|
## 수정 파일 요약
|
||||||
|
|
||||||
|
| 파일 | 항목 |
|
||||||
|
|------|------|
|
||||||
|
| `CODE_REVIEW-cloud-G07.md` | REVIEW_API-1 |
|
||||||
|
| `packages/contracts/notes/flutter-core-api-candidates.md` | REVIEW_API-1, 필요 시에만 |
|
||||||
|
|
||||||
|
## 최종 검증
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git diff --check
|
||||||
|
```
|
||||||
|
|
||||||
|
기대 결과: 출력 없이 종료한다.
|
||||||
|
|
||||||
|
모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
|
||||||
|
|
@ -0,0 +1,91 @@
|
||||||
|
<!-- task=m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics plan=2 tag=REVIEW_REVIEW_API -->
|
||||||
|
|
||||||
|
# Plan - REVIEW_REVIEW_API Complete Verification Evidence
|
||||||
|
|
||||||
|
## 이 파일을 읽는 구현 에이전트에게
|
||||||
|
|
||||||
|
`CODE_REVIEW-cloud-G07.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 반드시 채운다. 구현 후 검증을 실행하고 active 파일은 그대로 둔 채 리뷰 준비를 보고한다. 최종 판정, log rename, `complete.log`, archive 이동은 code-review-skill 전용이다. 사용자 결정, 사용자 소유 외부 환경, 범위 충돌로 막히면 review stub의 `사용자 리뷰 요청` 섹션에 정확한 근거와 재개 조건을 채우고 멈춘다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 닫을 수 있는 증거 공백은 사용자 리뷰 요청이 아니다.
|
||||||
|
|
||||||
|
## 배경
|
||||||
|
|
||||||
|
G06은 diagnostics contract note를 추가했지만 `git diff --check` 검증 증거가 없어 FAIL이었다. G07 follow-up은 같은 검증 신뢰 회복 작업을 수행해야 했으나, active review stub이 미작성 상태로 남아 구현 항목, 구현 체크리스트, 계획 대비 변경 사항, 주요 설계 결정, 검증 결과가 모두 완료되지 않았다.
|
||||||
|
|
||||||
|
## 사용자 리뷰 요청 흐름
|
||||||
|
|
||||||
|
구현 중 차단 사유는 active review stub의 `사용자 리뷰 요청` 섹션에 기록한다. 이 섹션은 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`를 기준으로 하며, code-review가 검증 후 실제 `USER_REVIEW.md` 작성 여부를 결정한다.
|
||||||
|
|
||||||
|
## 이전 리뷰 결과
|
||||||
|
|
||||||
|
- Archived plan: `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/plan_cloud_G06_0.log`
|
||||||
|
- Archived review: `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G06_0.log`
|
||||||
|
- Archived follow-up plan: `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/plan_cloud_G07_1.log`
|
||||||
|
- Archived follow-up review: `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G07_1.log`
|
||||||
|
- Latest verdict: FAIL
|
||||||
|
- Required:
|
||||||
|
- G07 implementation-owned sections were not filled.
|
||||||
|
- G07 checklist items remained unchecked.
|
||||||
|
- `git diff --check` output remained `(output)` placeholder instead of actual stdout/stderr or explicit no-output success.
|
||||||
|
|
||||||
|
## 범위 결정 근거
|
||||||
|
|
||||||
|
이 follow-up은 active review stub completion과 verification evidence 회복만 다룬다. `packages/contracts/notes/flutter-core-api-candidates.md`의 diagnostics 후보 내용은 기존 리뷰에서 계약 의도에 맞는 것으로 판단되었으므로, `git diff --check`가 실제 문제를 보고하지 않는 한 문서 의미를 수정하지 않는다.
|
||||||
|
|
||||||
|
## 빌드 등급
|
||||||
|
|
||||||
|
`cloud-G07`: 반복된 검증 신뢰 실패와 review stub completeness 실패를 닫아야 하므로 cloud review와 실제 명령 출력 기록이 필요하다.
|
||||||
|
|
||||||
|
## 구현 체크리스트
|
||||||
|
|
||||||
|
- [ ] `CODE_REVIEW-cloud-G07.md`의 구현 체크리스트가 이 계획과 같은 문구와 순서를 유지하는지 확인하고, 체크박스 외의 문구를 수정하지 않는다.
|
||||||
|
- [ ] 허용된 원격/검증 환경에서 `git diff --check`를 실행하고 실제 stdout/stderr 또는 무출력 성공 사실과 exit 0을 `CODE_REVIEW-cloud-G07.md`의 `검증 결과`에 기록한다.
|
||||||
|
- [ ] `git diff --check`가 Markdown/whitespace 문제를 보고하면 `packages/contracts/notes/flutter-core-api-candidates.md`의 해당 문제만 최소 수정하고 diagnostics 후보의 의미 범위는 바꾸지 않는다.
|
||||||
|
- [ ] `CODE_REVIEW-cloud-G07.md`의 구현 항목별 완료 여부, 구현 체크리스트, 계획 대비 변경 사항, 주요 설계 결정, 검증 결과를 placeholder 없이 실제 내용으로 채운다.
|
||||||
|
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
|
||||||
|
|
||||||
|
### [REVIEW_REVIEW_API-1] Complete Review Stub And Verification Evidence
|
||||||
|
|
||||||
|
#### 문제
|
||||||
|
|
||||||
|
`code_review_cloud_G07_1.log`는 구현 항목 완료 여부와 구현 체크리스트가 미체크 상태였고, 계획 대비 변경 사항/주요 설계 결정이 placeholder 그대로였으며, `git diff --check` 검증 결과도 `(output)` placeholder였다. 이 상태에서는 문서 변경 자체가 맞더라도 코드리뷰 루프 완료 조건을 충족하지 못한다.
|
||||||
|
|
||||||
|
#### 해결 방법
|
||||||
|
|
||||||
|
1. `CODE_REVIEW-cloud-G07.md`의 체크리스트 텍스트와 순서를 이 plan과 정확히 일치시킨다.
|
||||||
|
2. 허용된 원격/검증 환경에서 repo root 기준으로 `git diff --check`를 실행한다.
|
||||||
|
3. 출력이 없고 exit code가 0이면 `검증 결과`에 실제로 "출력 없음, exit 0"을 기록한다.
|
||||||
|
4. 출력이 있으면 해당 Markdown/whitespace 문제만 최소 수정하고, 같은 명령을 다시 실행해 최종 성공 증거를 기록한다.
|
||||||
|
5. 구현 항목별 완료 여부, 구현 체크리스트, 계획 대비 변경 사항, 주요 설계 결정, 검증 결과를 모두 실제 내용으로 채운다.
|
||||||
|
|
||||||
|
#### 수정 파일 및 체크리스트
|
||||||
|
|
||||||
|
- [ ] `CODE_REVIEW-cloud-G07.md`: 구현자 소유 섹션 완성, 검증 출력 기록.
|
||||||
|
- [ ] `packages/contracts/notes/flutter-core-api-candidates.md`: `git diff --check`가 지적한 경우에만 Markdown/whitespace 최소 수정.
|
||||||
|
|
||||||
|
#### 테스트 작성
|
||||||
|
|
||||||
|
자동 테스트는 작성하지 않는다. contracts 도메인의 현재 확인된 자동 test command는 없으며, 이번 follow-up은 문서 변경에 대한 `git diff --check` 검증 증거 회복이다.
|
||||||
|
|
||||||
|
#### 중간 검증
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git diff --check
|
||||||
|
```
|
||||||
|
|
||||||
|
기대 결과: 출력 없이 exit 0으로 종료한다.
|
||||||
|
|
||||||
|
## 수정 파일 요약
|
||||||
|
|
||||||
|
| 파일 | 항목 |
|
||||||
|
|------|------|
|
||||||
|
| `CODE_REVIEW-cloud-G07.md` | REVIEW_REVIEW_API-1 |
|
||||||
|
| `packages/contracts/notes/flutter-core-api-candidates.md` | REVIEW_REVIEW_API-1, 필요 시에만 |
|
||||||
|
|
||||||
|
## 최종 검증
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git diff --check
|
||||||
|
```
|
||||||
|
|
||||||
|
기대 결과: 출력 없이 exit 0으로 종료한다.
|
||||||
|
|
||||||
|
모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
|
||||||
|
|
@ -0,0 +1,130 @@
|
||||||
|
<!-- task=m-proto-socket-infrastructure-communication-rail/12+11_core_diagnostics plan=0 tag=API -->
|
||||||
|
|
||||||
|
# Code Review Reference - API
|
||||||
|
|
||||||
|
> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
|
||||||
|
> The task is NOT complete until every implementation-owned section below is filled in.
|
||||||
|
> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
|
||||||
|
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
|
||||||
|
> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Evidence gaps that a follow-up agent can close by rerunning commands or collecting artifacts are normal follow-up issues, not user-review blockers by themselves.
|
||||||
|
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
|
||||||
|
> Follow the ownership table at the bottom of this file for which sections you own.
|
||||||
|
|
||||||
|
## 개요
|
||||||
|
|
||||||
|
date=2026-05-30
|
||||||
|
task=m-proto-socket-infrastructure-communication-rail/12+11_core_diagnostics, plan=0, tag=API
|
||||||
|
|
||||||
|
## 이 파일을 읽는 리뷰 에이전트에게
|
||||||
|
|
||||||
|
> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
|
||||||
|
|
||||||
|
각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
|
||||||
|
리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.
|
||||||
|
|
||||||
|
1. 판정을 append한다.
|
||||||
|
2. `CODE_REVIEW-cloud-G07.md` → `code_review_cloud_G07_N.log`, `PLAN-cloud-G07.md` → `plan_cloud_G07_M.log`로 아카이브한다.
|
||||||
|
3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-proto-socket-infrastructure-communication-rail/12+11_core_diagnostics/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 사용자 결정으로 완료/PASS 해소되면 code-review가 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다.
|
||||||
|
4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
|
||||||
|
5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 구현 항목별 완료 여부
|
||||||
|
|
||||||
|
| 항목 | 완료 여부 |
|
||||||
|
|------|---------|
|
||||||
|
| [API-1] Core connection diagnostics | [ ] |
|
||||||
|
| [API-2] Core envelope meta and error logs | [ ] |
|
||||||
|
|
||||||
|
## 구현 체크리스트
|
||||||
|
|
||||||
|
- [ ] `11_contracts_diagnostics`가 PASS되어 `complete.log`가 생겼는지 확인하고 경로를 review stub에 기록한다.
|
||||||
|
- [ ] Core proto-socket 연결마다 stable `connection_id`를 만들고 연결/해제/request/broadcast 로그에 `connection_id`, `protocol_version`, `channel`, `action`, `error_code`를 구조화 속성으로 남긴다.
|
||||||
|
- [ ] response/event envelope `meta`에 diagnostics 필드를 additive로 채운다.
|
||||||
|
- [ ] Core 테스트로 diagnostics meta와 구조화 로그를 검증한다.
|
||||||
|
- [ ] `cd services/core && go test ./...`를 허용된 원격/검증 환경에서 실행한다.
|
||||||
|
- [ ] `cd services/core && go vet ./...`를 허용된 원격/검증 환경에서 실행한다.
|
||||||
|
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
|
||||||
|
|
||||||
|
## 코드리뷰 전용 체크리스트
|
||||||
|
|
||||||
|
> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
|
||||||
|
> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.
|
||||||
|
|
||||||
|
- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
|
||||||
|
- [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
|
||||||
|
- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G07_N.log`로 아카이브한다.
|
||||||
|
- [ ] active `PLAN-*-G??.md`를 `plan_cloud_G07_M.log`로 아카이브한다.
|
||||||
|
- [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하여 plan/review/archive 산출물이 추적 가능한지 확인한다.
|
||||||
|
- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
|
||||||
|
- [ ] PASS이면 active task 디렉터리 `agent-task/m-proto-socket-infrastructure-communication-rail/12+11_core_diagnostics/`를 `agent-task/archive/YYYY/MM/m-proto-socket-infrastructure-communication-rail/12+11_core_diagnostics/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
|
||||||
|
- [ ] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
|
||||||
|
- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-proto-socket-infrastructure-communication-rail/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
|
||||||
|
- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-cloud-G07.md`와 `CODE_REVIEW-cloud-G07.md`를 작성하고 `complete.log`를 작성하지 않는다.
|
||||||
|
- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
|
||||||
|
- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
|
||||||
|
|
||||||
|
## 계획 대비 변경 사항
|
||||||
|
|
||||||
|
_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._
|
||||||
|
|
||||||
|
## 주요 설계 결정
|
||||||
|
|
||||||
|
_구현 에이전트가 주요 설계 결정 사항을 기록한다._
|
||||||
|
|
||||||
|
## 사용자 리뷰 요청
|
||||||
|
|
||||||
|
_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._
|
||||||
|
|
||||||
|
- 상태: 없음
|
||||||
|
- 사유 유형: 없음
|
||||||
|
- 결정 필요: 없음
|
||||||
|
- 차단 근거: 없음
|
||||||
|
- 실행한 검증/명령: 없음
|
||||||
|
- 자동 후속 불가 이유: 없음
|
||||||
|
- 재개 조건: 없음
|
||||||
|
|
||||||
|
## 리뷰어를 위한 체크포인트
|
||||||
|
|
||||||
|
- `connection_id` 생성과 clients map 변경이 race 없이 mutex 보호 아래 있는가.
|
||||||
|
- response/event meta가 기존 payload shape와 REST compatibility를 깨지 않는 additive 변경인가.
|
||||||
|
- 로그에 auth token, payload 원문, secret이 출력되지 않는가.
|
||||||
|
- predecessor `11_contracts_diagnostics` complete evidence가 기록되었는가.
|
||||||
|
|
||||||
|
## 검증 결과
|
||||||
|
|
||||||
|
_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._
|
||||||
|
|
||||||
|
필수 규칙:
|
||||||
|
- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
|
||||||
|
- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
|
||||||
|
- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.
|
||||||
|
- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다.
|
||||||
|
|
||||||
|
### API-1 중간 검증
|
||||||
|
```
|
||||||
|
$ cd services/core && go test ./internal/protosocket -run 'TestServer.*Diagnostics|TestServerRespondsWithErrorEnvelopeForUnsupportedAction' -count=1
|
||||||
|
(output)
|
||||||
|
```
|
||||||
|
|
||||||
|
### API-2 중간 검증
|
||||||
|
```
|
||||||
|
$ cd services/core && go test ./internal/protosocket -run 'TestRouterProtoSocketTaskListRequiresAuth|TestProtoSocketTaskErrorEnvelopeCodes|Test.*Broadcast.*' -count=1
|
||||||
|
(output)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 최종 검증
|
||||||
|
```
|
||||||
|
$ cd services/core && go test ./...
|
||||||
|
(output)
|
||||||
|
|
||||||
|
$ cd services/core && go vet ./...
|
||||||
|
(output)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
|
||||||
|
> If anything is blank, go back and fill it in before saving this file.
|
||||||
|
> Leave review-agent-only sections unchanged.
|
||||||
|
|
@ -0,0 +1,223 @@
|
||||||
|
<!-- task=m-proto-socket-infrastructure-communication-rail/12+11_core_diagnostics plan=0 tag=API -->
|
||||||
|
|
||||||
|
# Plan - API Core Proto-Socket Diagnostics
|
||||||
|
|
||||||
|
## 이 파일을 읽는 구현 에이전트에게
|
||||||
|
|
||||||
|
`CODE_REVIEW-cloud-G07.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 반드시 채운다. 구현 후 검증을 실행하고 active 파일은 그대로 둔 채 리뷰 준비를 보고한다. 최종 판정, log rename, `complete.log`, archive 이동은 code-review-skill 전용이다. 사용자 결정, 사용자 소유 외부 환경, 범위 충돌로 막히면 review stub의 `사용자 리뷰 요청` 섹션에 정확한 근거와 재개 조건을 채우고 멈춘다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 닫을 수 있는 증거 공백은 사용자 리뷰 요청이 아니다.
|
||||||
|
|
||||||
|
## 배경
|
||||||
|
|
||||||
|
Core proto-socket server는 연결과 broadcast 실패를 로그로 남기지만 connection id, protocol version, channel, action, error code를 구조화된 속성으로 남기지 않는다. Client debug surface도 Core가 보내는 response/event meta를 소비해야 하므로 먼저 Core가 안정적인 diagnostics meta와 로그를 제공해야 한다. 이 subtask는 계약 문서 subtask 완료 후 진행한다.
|
||||||
|
|
||||||
|
## 사용자 리뷰 요청 흐름
|
||||||
|
|
||||||
|
구현 중 차단 사유는 active review stub의 `사용자 리뷰 요청` 섹션에 기록한다. 이 섹션은 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`를 기준으로 하며, code-review가 검증 후 실제 `USER_REVIEW.md` 작성 여부를 결정한다.
|
||||||
|
|
||||||
|
## 분석 결과
|
||||||
|
|
||||||
|
### 읽은 파일
|
||||||
|
|
||||||
|
- `agent-ops/rules/project/rules.md`
|
||||||
|
- `agent-ops/rules/private/rules.md`
|
||||||
|
- `agent-ops/rules/common/rules-roadmap.md`
|
||||||
|
- `agent-ops/skills/common/router.md`
|
||||||
|
- `agent-ops/skills/common/plan/SKILL.md`
|
||||||
|
- `agent-roadmap/current.md`
|
||||||
|
- `agent-roadmap/phase/workflow-core/PHASE.md`
|
||||||
|
- `agent-roadmap/phase/workflow-core/milestones/proto-socket-infrastructure-communication-rail.md`
|
||||||
|
- `agent-ops/rules/project/domain/core/rules.md`
|
||||||
|
- `agent-ops/rules/project/domain/contracts/rules.md`
|
||||||
|
- `agent-test/local/rules.md`
|
||||||
|
- `agent-test/local/core-smoke.md`
|
||||||
|
- `agent-test/local/contracts-smoke.md`
|
||||||
|
- `services/core/internal/protosocket/server.go`
|
||||||
|
- `services/core/internal/protosocket/dispatcher.go`
|
||||||
|
- `services/core/internal/protosocket/envelope.go`
|
||||||
|
- `services/core/internal/protosocket/events.go`
|
||||||
|
- `services/core/internal/protosocket/tasks.go`
|
||||||
|
- `services/core/internal/http/router.go`
|
||||||
|
- `services/core/internal/protosocket/server_test.go`
|
||||||
|
- `services/core/internal/protosocket/tasks_test.go`
|
||||||
|
- `services/core/internal/protosocket/envelope_test.go`
|
||||||
|
- `packages/contracts/notes/flutter-core-api-candidates.md`
|
||||||
|
|
||||||
|
### 테스트 환경 규칙
|
||||||
|
|
||||||
|
`test_env=local`로 판단했고 `agent-test/local/rules.md`를 읽었다. 이 파일은 로컬 테스트 금지를 명시하므로 현 세션에서는 검증 명령을 실행하지 않는다. 적용 profile은 `core-smoke`이며 core 변경의 필수 검증은 `cd services/core && go test ./...`, 보조 검증은 `cd services/core && go vet ./...`다. 명령은 후속 구현/리뷰 에이전트가 허용된 원격/검증 환경에서 실행한다.
|
||||||
|
|
||||||
|
### 테스트 커버리지 공백
|
||||||
|
|
||||||
|
- connection id가 response/event meta에 들어가는 동작: 기존 테스트 없음. `server_test.go` 또는 `tasks_test.go`에 추가 필요.
|
||||||
|
- protocol/channel/action/error_code 구조화 로그: 기존 테스트 없음. `slog` buffer 기반 테스트 추가 필요.
|
||||||
|
- 기존 task action 의미 보존: `tasks_test.go`가 create/list/get/enqueue, auth, error code를 이미 검증한다.
|
||||||
|
|
||||||
|
### 심볼 참조
|
||||||
|
|
||||||
|
none. 기존 public symbol rename/remove 없이 server 내부 struct/helper를 추가한다.
|
||||||
|
|
||||||
|
### 분할 판단
|
||||||
|
|
||||||
|
split decision policy를 평가했다. 이 subtask는 `12+11_core_diagnostics`이며 predecessor `11_contracts_diagnostics`의 `complete.log`가 필요하다. 현재 active/archive predecessor completion은 없음으로 확인했다. 구현은 `11` PASS 후 시작해야 한다.
|
||||||
|
|
||||||
|
### 범위 결정 근거
|
||||||
|
|
||||||
|
Core proto-socket server, dispatcher/event helper, core tests만 수정한다. Flutter debug UI와 contracts note 수정은 각각 `13+11,12_client_diagnostics`, `11_contracts_diagnostics` 범위다. REST task API shape, auth policy, workflow service behavior, DB schema는 변경하지 않는다.
|
||||||
|
|
||||||
|
### 빌드 등급
|
||||||
|
|
||||||
|
`cloud-G07`: protocol diagnostics, websocket connection lifecycle, structured logging, concurrency-safe client registry를 건드리므로 cloud lane과 높은 등급이 필요하다.
|
||||||
|
|
||||||
|
## 구현 체크리스트
|
||||||
|
|
||||||
|
- [ ] `11_contracts_diagnostics`가 PASS되어 `complete.log`가 생겼는지 확인하고 경로를 review stub에 기록한다.
|
||||||
|
- [ ] Core proto-socket 연결마다 stable `connection_id`를 만들고 연결/해제/request/broadcast 로그에 `connection_id`, `protocol_version`, `channel`, `action`, `error_code`를 구조화 속성으로 남긴다.
|
||||||
|
- [ ] response/event envelope `meta`에 diagnostics 필드를 additive로 채운다.
|
||||||
|
- [ ] Core 테스트로 diagnostics meta와 구조화 로그를 검증한다.
|
||||||
|
- [ ] `cd services/core && go test ./...`를 허용된 원격/검증 환경에서 실행한다.
|
||||||
|
- [ ] `cd services/core && go vet ./...`를 허용된 원격/검증 환경에서 실행한다.
|
||||||
|
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
|
||||||
|
|
||||||
|
## 의존 관계 및 구현 순서
|
||||||
|
|
||||||
|
이 directory name은 `12+11_core_diagnostics`이므로 predecessor는 같은 task group의 `11_*` subtask뿐이다. `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/complete.log` 또는 matching archive `complete.log`가 생기기 전에는 구현을 시작하지 않는다.
|
||||||
|
|
||||||
|
### [API-1] Core Connection Diagnostics
|
||||||
|
|
||||||
|
#### 문제
|
||||||
|
|
||||||
|
[services/core/internal/protosocket/server.go](/config/workspace/nomadcode/services/core/internal/protosocket/server.go:20)는 clients map에 client pointer만 저장하고 connection id가 없다. 연결/해제 로그도 [server.go](/config/workspace/nomadcode/services/core/internal/protosocket/server.go:58)와 [server.go](/config/workspace/nomadcode/services/core/internal/protosocket/server.go:102)에서 generic message만 남긴다.
|
||||||
|
|
||||||
|
Before:
|
||||||
|
|
||||||
|
```go
|
||||||
|
20 type Server struct {
|
||||||
|
21 cfg Config
|
||||||
|
22 dispatcher *Dispatcher
|
||||||
|
23 logger *slog.Logger
|
||||||
|
24 mu sync.Mutex
|
||||||
|
25 clients map[*toki.WsClient]struct{}
|
||||||
|
26 }
|
||||||
|
...
|
||||||
|
58 client.AddDisconnectListener(func(c *toki.WsClient) {
|
||||||
|
59 s.mu.Lock()
|
||||||
|
60 delete(s.clients, c)
|
||||||
|
61 s.mu.Unlock()
|
||||||
|
62 s.logger.Info("websocket client disconnected")
|
||||||
|
63 })
|
||||||
|
...
|
||||||
|
102 s.logger.Info("websocket client connected successfully")
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 해결 방법
|
||||||
|
|
||||||
|
client registry 값을 diagnostics struct로 바꾸고 accept 시 `connection_id`를 생성한다. nil logger 가능성도 방어한다. 연결/해제/request 로그에는 contract subtask의 필드명을 사용한다.
|
||||||
|
|
||||||
|
After:
|
||||||
|
|
||||||
|
```go
|
||||||
|
type clientDiagnostics struct {
|
||||||
|
connectionID string
|
||||||
|
}
|
||||||
|
|
||||||
|
type Server struct {
|
||||||
|
...
|
||||||
|
clients map[*toki.WsClient]clientDiagnostics
|
||||||
|
}
|
||||||
|
|
||||||
|
connectionID := "conn-" + generateID()
|
||||||
|
s.clients[client] = clientDiagnostics{connectionID: connectionID}
|
||||||
|
s.logInfo("proto-socket client connected", "connection_id", connectionID, "protocol_version", ProtocolVersion)
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 수정 파일 및 체크리스트
|
||||||
|
|
||||||
|
- [ ] `services/core/internal/protosocket/server.go`: client diagnostics registry와 log helper 추가.
|
||||||
|
- [ ] `services/core/internal/protosocket/server_test.go`: connection id가 response meta 또는 logs에 남는지 검증.
|
||||||
|
|
||||||
|
#### 테스트 작성
|
||||||
|
|
||||||
|
`server_test.go`에 `slog.NewJSONHandler(&bytes.Buffer, nil)` 기반 테스트를 추가한다. 연결 성공/해제 또는 request 처리 후 JSON log에 `connection_id`, `protocol_version`이 포함되는지 assertion한다.
|
||||||
|
|
||||||
|
#### 중간 검증
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd services/core && go test ./internal/protosocket -run 'TestServer.*Diagnostics|TestServerRespondsWithErrorEnvelopeForUnsupportedAction' -count=1
|
||||||
|
```
|
||||||
|
|
||||||
|
기대 결과: 관련 tests PASS. 명령은 허용된 원격/검증 환경에서 실행한다.
|
||||||
|
|
||||||
|
### [API-2] Core Envelope Meta And Error Logs
|
||||||
|
|
||||||
|
#### 문제
|
||||||
|
|
||||||
|
[services/core/internal/protosocket/server.go](/config/workspace/nomadcode/services/core/internal/protosocket/server.go:65)는 request를 dispatch하지만 request/response diagnostics를 남기지 않는다. [services/core/internal/protosocket/events.go](/config/workspace/nomadcode/services/core/internal/protosocket/events.go:22)의 error response에는 code가 있지만 meta에는 diagnostics가 없다.
|
||||||
|
|
||||||
|
Before:
|
||||||
|
|
||||||
|
```go
|
||||||
|
65 toki.AddRequestListenerTyped[*structpb.Struct, *structpb.Struct](&client.Communicator, func(req *structpb.Struct) (*structpb.Struct, error) {
|
||||||
|
66 env, err := EnvelopeFromStruct(req)
|
||||||
|
...
|
||||||
|
82 resEnv := s.dispatcher.Dispatch(r.Context(), env)
|
||||||
|
83 resStruct, err := resEnv.ToStruct()
|
||||||
|
...
|
||||||
|
99 return resStruct, nil
|
||||||
|
100 })
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 해결 방법
|
||||||
|
|
||||||
|
`withDiagnosticsMeta(env Envelope, connectionID string) Envelope`와 `errorCode(env Envelope) string` helper를 추가한다. 모든 response/event 직전 meta에 `connection_id`, `protocol_version`, `channel`, `action`, `error_code`를 additive로 넣고, request 처리 로그도 같은 값을 남긴다. Broadcast는 client별 clone에 connection id를 채운 뒤 전송한다.
|
||||||
|
|
||||||
|
After:
|
||||||
|
|
||||||
|
```go
|
||||||
|
resEnv := withDiagnosticsMeta(s.dispatcher.Dispatch(r.Context(), env), connectionID)
|
||||||
|
s.logInfo("proto-socket request handled",
|
||||||
|
"connection_id", connectionID,
|
||||||
|
"protocol_version", resEnv.ProtocolVersion,
|
||||||
|
"channel", resEnv.Channel,
|
||||||
|
"action", resEnv.Action,
|
||||||
|
"error_code", errorCode(resEnv),
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 수정 파일 및 체크리스트
|
||||||
|
|
||||||
|
- [ ] `services/core/internal/protosocket/server.go`: response/event meta 주입, request/broadcast log 추가.
|
||||||
|
- [ ] `services/core/internal/protosocket/events.go`: error/success response helper와 meta 주입 방식 충돌 여부 확인.
|
||||||
|
- [ ] `services/core/internal/protosocket/tasks_test.go`: task response/error envelope meta assertions 추가.
|
||||||
|
- [ ] `services/core/internal/protosocket/server_test.go`: broadcast meta/log assertions 추가.
|
||||||
|
|
||||||
|
#### 테스트 작성
|
||||||
|
|
||||||
|
`tasks_test.go` route-level tests에서 `task.list` response와 error response의 `Meta["connection_id"]`, `Meta["protocol_version"]`, `Meta["channel"]`, `Meta["action"]`, `Meta["error_code"]`를 검증한다. `server_test.go` broadcast test는 client별 event meta에 connection id가 들어가는지 검증한다.
|
||||||
|
|
||||||
|
#### 중간 검증
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd services/core && go test ./internal/protosocket -run 'TestRouterProtoSocketTaskListRequiresAuth|TestProtoSocketTaskErrorEnvelopeCodes|Test.*Broadcast.*' -count=1
|
||||||
|
```
|
||||||
|
|
||||||
|
기대 결과: 관련 tests PASS. 명령은 허용된 원격/검증 환경에서 실행한다.
|
||||||
|
|
||||||
|
## 수정 파일 요약
|
||||||
|
|
||||||
|
| 파일 | 항목 |
|
||||||
|
|------|------|
|
||||||
|
| `services/core/internal/protosocket/server.go` | API-1, API-2 |
|
||||||
|
| `services/core/internal/protosocket/events.go` | API-2 |
|
||||||
|
| `services/core/internal/protosocket/server_test.go` | API-1, API-2 |
|
||||||
|
| `services/core/internal/protosocket/tasks_test.go` | API-2 |
|
||||||
|
|
||||||
|
## 최종 검증
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd services/core && go test ./...
|
||||||
|
cd services/core && go vet ./...
|
||||||
|
```
|
||||||
|
|
||||||
|
기대 결과: 두 명령 모두 실패 없이 종료한다. Go test cache는 diagnostics 변경 확인에는 충분하지 않으므로 필요한 targeted tests는 `-count=1`로 중간 검증에서 fresh 실행한다. 명령은 허용된 원격/검증 환경에서 실행한다.
|
||||||
|
|
||||||
|
모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
|
||||||
|
|
@ -0,0 +1,138 @@
|
||||||
|
<!-- task=m-proto-socket-infrastructure-communication-rail/13+11,12_client_diagnostics plan=0 tag=API -->
|
||||||
|
|
||||||
|
# Code Review Reference - API
|
||||||
|
|
||||||
|
> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
|
||||||
|
> The task is NOT complete until every implementation-owned section below is filled in.
|
||||||
|
> Complete the `구현 체크리스트`; the final checklist item is mandatory before saving.
|
||||||
|
> Fill implementation-owned sections, then stop with active files in place and report ready for review.
|
||||||
|
> If implementation is blocked by a user-only decision, user-owned external environment prerequisite, or scope conflict, fill `사용자 리뷰 요청` with evidence and stop with active files in place; code-review decides whether to write `USER_REVIEW.md`. Evidence gaps that a follow-up agent can close by rerunning commands or collecting artifacts are normal follow-up issues, not user-review blockers by themselves.
|
||||||
|
> Finalization (`코드리뷰 결과`, log rename, `complete.log`, archive moves, `코드리뷰 전용 체크리스트`) is review-agent-only, even after compaction/resume.
|
||||||
|
> Follow the ownership table at the bottom of this file for which sections you own.
|
||||||
|
|
||||||
|
## 개요
|
||||||
|
|
||||||
|
date=2026-05-30
|
||||||
|
task=m-proto-socket-infrastructure-communication-rail/13+11,12_client_diagnostics, plan=0, tag=API
|
||||||
|
|
||||||
|
## Roadmap Targets
|
||||||
|
|
||||||
|
- Milestone: `agent-roadmap/phase/workflow-core/milestones/proto-socket-infrastructure-communication-rail.md`
|
||||||
|
- Task ids:
|
||||||
|
- `diagnostics`: connection id, protocol version, channel name, error code를 로그와 디버그 표면에서 확인할 수 있게 한다.
|
||||||
|
- Completion mode: check-on-pass
|
||||||
|
|
||||||
|
## 이 파일을 읽는 리뷰 에이전트에게
|
||||||
|
|
||||||
|
> **[REVIEW AGENT ONLY]** 아래 종결 절차는 코드리뷰 에이전트 전용이다. 구현 에이전트는 이 섹션을 실행하지 않는다.
|
||||||
|
|
||||||
|
각 항목의 구현을 실제 소스 파일과 대조하고, `검증 결과` 섹션의 출력이 코드와 일치하는지 확인하세요.
|
||||||
|
리뷰 완료는 아래 순서까지 끝난 상태를 의미합니다.
|
||||||
|
|
||||||
|
1. 판정을 append한다.
|
||||||
|
2. `CODE_REVIEW-cloud-G07.md` → `code_review_cloud_G07_N.log`, `PLAN-cloud-G07.md` → `plan_cloud_G07_M.log`로 아카이브한다.
|
||||||
|
3. PASS이면 `complete.log` 작성 후 active task 디렉터리를 `agent-task/archive/YYYY/MM/m-proto-socket-infrastructure-communication-rail/13+11,12_client_diagnostics/`로 이동한다. WARN/FAIL이면 user-review gate를 확인한 뒤 다음 active plan/review 파일 또는 `USER_REVIEW.md`를 작성한다. `USER_REVIEW.md`가 사용자 결정으로 완료/PASS 해소되면 code-review가 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log` 작성 후 archive 이동한다.
|
||||||
|
4. PASS이고 task group이 `m-<milestone-slug>`이면 완료 이벤트 메타데이터를 보고한다. roadmap 상태 체크와 `update-roadmap` 호출은 런타임 책임이다.
|
||||||
|
5. 적용 가능한 `코드리뷰 전용 체크리스트` 항목을 최종 `.log` 위치에서 체크한 뒤 보고한다.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 구현 항목별 완료 여부
|
||||||
|
|
||||||
|
| 항목 | 완료 여부 |
|
||||||
|
|------|---------|
|
||||||
|
| [API-1] Client diagnostics state | [ ] |
|
||||||
|
| [API-2] Workspace debug surface | [ ] |
|
||||||
|
|
||||||
|
## 구현 체크리스트
|
||||||
|
|
||||||
|
- [ ] `11_contracts_diagnostics`와 `12+11_core_diagnostics`가 PASS되어 각 `complete.log`가 생겼는지 확인하고 경로를 review stub에 기록한다.
|
||||||
|
- [ ] `ProtoSocketLifecycle` 또는 dedicated diagnostics controller가 connection state, connection id, protocol version, recent channel/action/error code를 비밀 없이 유지하게 한다.
|
||||||
|
- [ ] `ProtoSocketTaskService`가 response/error envelope meta를 diagnostics sink에 전달하고 기존 error mapping을 유지한다.
|
||||||
|
- [ ] `WorkspaceHomePage` 또는 app shell에 compact debug surface를 추가해 connection id, protocol version, channel, error code를 확인할 수 있게 한다.
|
||||||
|
- [ ] Flutter tests로 endpoint 설정, reconnect/failure lifecycle, task service diagnostics, widget debug surface를 검증한다.
|
||||||
|
- [ ] `cd apps/client && flutter test`를 허용된 원격/검증 환경에서 실행한다.
|
||||||
|
- [ ] `cd apps/client && flutter analyze --no-fatal-infos`를 허용된 원격/검증 환경에서 실행한다.
|
||||||
|
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
|
||||||
|
|
||||||
|
## 코드리뷰 전용 체크리스트
|
||||||
|
|
||||||
|
> **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
|
||||||
|
> 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.
|
||||||
|
|
||||||
|
- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
|
||||||
|
- [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
|
||||||
|
- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_cloud_G07_N.log`로 아카이브한다.
|
||||||
|
- [ ] active `PLAN-*-G??.md`를 `plan_cloud_G07_M.log`로 아카이브한다.
|
||||||
|
- [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하여 plan/review/archive 산출물이 추적 가능한지 확인한다.
|
||||||
|
- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
|
||||||
|
- [ ] PASS이면 active task 디렉터리 `agent-task/m-proto-socket-infrastructure-communication-rail/13+11,12_client_diagnostics/`를 `agent-task/archive/YYYY/MM/m-proto-socket-infrastructure-communication-rail/13+11,12_client_diagnostics/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
|
||||||
|
- [ ] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
|
||||||
|
- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/m-proto-socket-infrastructure-communication-rail/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
|
||||||
|
- [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-cloud-G07.md`와 `CODE_REVIEW-cloud-G07.md`를 작성하고 `complete.log`를 작성하지 않는다.
|
||||||
|
- [ ] USER_REVIEW이면 `agent-ops/skills/common/code-review/templates/user-review-template.md` 기준으로 `USER_REVIEW.md`를 작성하고 active `PLAN-*.md`, `CODE_REVIEW-*.md`, `complete.log`를 남기지 않는다.
|
||||||
|
- [ ] USER_REVIEW가 사용자 결정으로 완료/PASS 해소되면 `USER_REVIEW.md`를 해소 상태로 갱신하고 `complete.log`를 작성한 뒤 task directory를 archive로 이동한다.
|
||||||
|
|
||||||
|
## 계획 대비 변경 사항
|
||||||
|
|
||||||
|
_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._
|
||||||
|
|
||||||
|
## 주요 설계 결정
|
||||||
|
|
||||||
|
_구현 에이전트가 주요 설계 결정 사항을 기록한다._
|
||||||
|
|
||||||
|
## 사용자 리뷰 요청
|
||||||
|
|
||||||
|
_기본값은 `없음`이다. 구현 중 사용자 결정, 사용자 소유 외부 환경/secret/서비스 준비, 또는 계획 범위 변경 없이는 안전하게 진행할 수 없으면 아래 항목을 실제 내용으로 교체하고, 구현을 중단한 뒤 active 파일을 그대로 둔 채 리뷰를 요청한다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 해소할 수 있는 검증 증거 공백만으로는 사용자 리뷰 요청을 작성하지 않는다._
|
||||||
|
|
||||||
|
- 상태: 없음
|
||||||
|
- 사유 유형: 없음
|
||||||
|
- 결정 필요: 없음
|
||||||
|
- 차단 근거: 없음
|
||||||
|
- 실행한 검증/명령: 없음
|
||||||
|
- 자동 후속 불가 이유: 없음
|
||||||
|
- 재개 조건: 없음
|
||||||
|
|
||||||
|
## 리뷰어를 위한 체크포인트
|
||||||
|
|
||||||
|
- predecessor `11`, `12` complete evidence가 기록되었는가.
|
||||||
|
- UI debug surface가 auth, payload, secret, raw error message를 노출하지 않는가.
|
||||||
|
- diagnostics state가 reconnect/failure/disconnect lifecycle에서 stale connection id/error code를 잘 정리하는가.
|
||||||
|
- `Roadmap Targets`가 final diagnostics completion에만 존재하고 predecessor plans에는 없는가.
|
||||||
|
|
||||||
|
## 검증 결과
|
||||||
|
|
||||||
|
_구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후 출력을 여기에 붙여 넣는다._
|
||||||
|
|
||||||
|
필수 규칙:
|
||||||
|
- 검증 명령은 고정된 계약이다. 임의로 대체하지 않는다.
|
||||||
|
- 대체가 필요하면 `계획 대비 변경 사항`에 이유와 대체 명령을 기록한다.
|
||||||
|
- `검증 결과`에는 실제 stdout/stderr를 붙여 넣는다.
|
||||||
|
- 사용자 리뷰 요청으로 명령을 끝까지 실행하지 못했다면 `사용자 리뷰 요청`에 실행한 명령, 실제 출력, 미실행 명령의 사유를 기록한다.
|
||||||
|
|
||||||
|
### API-1 중간 검증
|
||||||
|
```
|
||||||
|
$ cd apps/client && flutter test test/integrations/proto_socket_lifecycle_test.dart test/integrations/proto_socket_task_service_test.dart
|
||||||
|
(output)
|
||||||
|
```
|
||||||
|
|
||||||
|
### API-2 중간 검증
|
||||||
|
```
|
||||||
|
$ cd apps/client && flutter test test/widget_test.dart
|
||||||
|
(output)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 최종 검증
|
||||||
|
```
|
||||||
|
$ cd apps/client && flutter test
|
||||||
|
(output)
|
||||||
|
|
||||||
|
$ cd apps/client && flutter analyze --no-fatal-infos
|
||||||
|
(output)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every implementation-owned section: completion table, implementation checklist, changes from plan, design decisions, and verification output?**
|
||||||
|
> If anything is blank, go back and fill it in before saving this file.
|
||||||
|
> Leave review-agent-only sections unchanged.
|
||||||
|
|
@ -0,0 +1,239 @@
|
||||||
|
<!-- task=m-proto-socket-infrastructure-communication-rail/13+11,12_client_diagnostics plan=0 tag=API -->
|
||||||
|
|
||||||
|
# Plan - API Client Proto-Socket Diagnostics
|
||||||
|
|
||||||
|
## 이 파일을 읽는 구현 에이전트에게
|
||||||
|
|
||||||
|
`CODE_REVIEW-cloud-G07.md`의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 반드시 채운다. 구현 후 검증을 실행하고 active 파일은 그대로 둔 채 리뷰 준비를 보고한다. 최종 판정, log rename, `complete.log`, archive 이동은 code-review-skill 전용이다. 사용자 결정, 사용자 소유 외부 환경, 범위 충돌로 막히면 review stub의 `사용자 리뷰 요청` 섹션에 정확한 근거와 재개 조건을 채우고 멈춘다. 후속 에이전트가 명령 재실행이나 산출물 수집으로 닫을 수 있는 증거 공백은 사용자 리뷰 요청이 아니다.
|
||||||
|
|
||||||
|
## 배경
|
||||||
|
|
||||||
|
마일스톤의 마지막 남은 기능 Task는 connection id, protocol version, channel name, error code를 로그와 디버그 표면에서 확인 가능하게 하는 것이다. Core가 diagnostics meta를 보내면 Flutter client는 연결 상태와 최근 channel/error 정보를 비밀 없이 보여줘야 한다. 이 subtask는 contracts와 core diagnostics가 완료된 뒤 client lifecycle, task service, workspace 화면, Flutter tests를 닫는다.
|
||||||
|
|
||||||
|
## 사용자 리뷰 요청 흐름
|
||||||
|
|
||||||
|
구현 중 차단 사유는 active review stub의 `사용자 리뷰 요청` 섹션에 기록한다. 이 섹션은 `agent-ops/skills/common/_templates/implementation-user-review-request-section.md`를 기준으로 하며, code-review가 검증 후 실제 `USER_REVIEW.md` 작성 여부를 결정한다.
|
||||||
|
|
||||||
|
## Roadmap Targets
|
||||||
|
|
||||||
|
- Milestone: `agent-roadmap/phase/workflow-core/milestones/proto-socket-infrastructure-communication-rail.md`
|
||||||
|
- Task ids:
|
||||||
|
- `diagnostics`: connection id, protocol version, channel name, error code를 로그와 디버그 표면에서 확인할 수 있게 한다.
|
||||||
|
- Completion mode: check-on-pass
|
||||||
|
|
||||||
|
## 분석 결과
|
||||||
|
|
||||||
|
### 읽은 파일
|
||||||
|
|
||||||
|
- `agent-ops/rules/project/rules.md`
|
||||||
|
- `agent-ops/rules/private/rules.md`
|
||||||
|
- `agent-ops/rules/common/rules-roadmap.md`
|
||||||
|
- `agent-ops/skills/common/router.md`
|
||||||
|
- `agent-ops/skills/common/plan/SKILL.md`
|
||||||
|
- `agent-roadmap/current.md`
|
||||||
|
- `agent-roadmap/phase/workflow-core/PHASE.md`
|
||||||
|
- `agent-roadmap/phase/workflow-core/milestones/proto-socket-infrastructure-communication-rail.md`
|
||||||
|
- `agent-ops/rules/project/domain/mobile/rules.md`
|
||||||
|
- `agent-ops/rules/project/domain/core/rules.md`
|
||||||
|
- `agent-ops/rules/project/domain/contracts/rules.md`
|
||||||
|
- `agent-test/local/rules.md`
|
||||||
|
- `agent-test/local/mobile-smoke.md`
|
||||||
|
- `agent-test/local/core-smoke.md`
|
||||||
|
- `agent-test/local/contracts-smoke.md`
|
||||||
|
- `apps/client/pubspec.yaml`
|
||||||
|
- `apps/client/analysis_options.yaml`
|
||||||
|
- `apps/client/lib/src/app/bootstrap.dart`
|
||||||
|
- `apps/client/lib/src/app/nomadcode_client_app.dart`
|
||||||
|
- `apps/client/lib/src/integrations/proto_socket/proto_socket_client.dart`
|
||||||
|
- `apps/client/lib/src/integrations/proto_socket/proto_socket_endpoint_config.dart`
|
||||||
|
- `apps/client/lib/src/integrations/proto_socket/proto_socket_envelope.dart`
|
||||||
|
- `apps/client/lib/src/integrations/proto_socket/proto_socket_lifecycle.dart`
|
||||||
|
- `apps/client/lib/src/integrations/proto_socket/proto_socket_task_service.dart`
|
||||||
|
- `apps/client/lib/src/features/workspaces/domain/project_workspace.dart`
|
||||||
|
- `apps/client/lib/src/features/workspaces/domain/workspace_task.dart`
|
||||||
|
- `apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart`
|
||||||
|
- `apps/client/test/integrations/proto_socket_endpoint_config_test.dart`
|
||||||
|
- `apps/client/test/integrations/proto_socket_envelope_test.dart`
|
||||||
|
- `apps/client/test/integrations/proto_socket_lifecycle_test.dart`
|
||||||
|
- `apps/client/test/integrations/proto_socket_task_service_test.dart`
|
||||||
|
- `apps/client/test/widget_test.dart`
|
||||||
|
- `packages/contracts/notes/flutter-core-api-candidates.md`
|
||||||
|
- `services/core/internal/protosocket/server.go`
|
||||||
|
- `services/core/internal/protosocket/events.go`
|
||||||
|
- `services/core/internal/protosocket/tasks_test.go`
|
||||||
|
|
||||||
|
### 테스트 환경 규칙
|
||||||
|
|
||||||
|
`test_env=local`로 판단했고 `agent-test/local/rules.md`를 읽었다. 이 파일은 로컬 테스트 금지를 명시하므로 현 세션에서는 검증 명령을 실행하지 않는다. 적용 profile은 `mobile-smoke`이며 mobile 변경의 필수 검증은 `cd apps/client && flutter test`, analyzer 영향이 있으므로 `cd apps/client && flutter analyze --no-fatal-infos`도 필요하다. `apps/client`는 `../../../proto-socket/dart`와 `../../../nexo/packages/messaging_flutter` path dependency가 있어 후속 환경에 sibling workspace가 필요하다.
|
||||||
|
|
||||||
|
### 테스트 커버리지 공백
|
||||||
|
|
||||||
|
- lifecycle diagnostics stream/snapshot: 기존 `proto_socket_lifecycle_test.dart`는 state와 lastError만 검증한다. diagnostics snapshot 테스트 추가 필요.
|
||||||
|
- task response/error diagnostics capture: 기존 `proto_socket_task_service_test.dart`는 error mapping만 검증한다. response meta/error code를 diagnostics sink에 기록하는 테스트 추가 필요.
|
||||||
|
- UI debug surface: 기존 `widget_test.dart`는 service task rendering과 connection lifecycle만 검증한다. connection id/protocol/channel/error code display 테스트 추가 필요.
|
||||||
|
|
||||||
|
### 심볼 참조
|
||||||
|
|
||||||
|
none. 기존 public symbol rename/remove 없이 optional diagnostics API를 추가한다.
|
||||||
|
|
||||||
|
### 분할 판단
|
||||||
|
|
||||||
|
split decision policy를 평가했다. 이 subtask는 `13+11,12_client_diagnostics`이며 predecessor는 `11_contracts_diagnostics`, `12+11_core_diagnostics`다. 현재 두 predecessor 모두 아직 `complete.log`가 없으므로 구현은 둘 다 PASS된 뒤 시작해야 한다.
|
||||||
|
|
||||||
|
### 범위 결정 근거
|
||||||
|
|
||||||
|
Flutter client diagnostics, debug surface, Flutter tests만 수정한다. Core response/event meta 구현은 `12+11_core_diagnostics` 범위다. Project Workspace Management UX 전체 완성, workspace metadata API, external provider integration, Mattermost push native 로직은 범위에서 제외한다.
|
||||||
|
|
||||||
|
### 빌드 등급
|
||||||
|
|
||||||
|
`cloud-G07`: client lifecycle, service boundary, UI rendering, protocol diagnostics를 함께 다루고 predecessor output에 의존하므로 cloud lane이 적합하다.
|
||||||
|
|
||||||
|
## 구현 체크리스트
|
||||||
|
|
||||||
|
- [ ] `11_contracts_diagnostics`와 `12+11_core_diagnostics`가 PASS되어 각 `complete.log`가 생겼는지 확인하고 경로를 review stub에 기록한다.
|
||||||
|
- [ ] `ProtoSocketLifecycle` 또는 dedicated diagnostics controller가 connection state, connection id, protocol version, recent channel/action/error code를 비밀 없이 유지하게 한다.
|
||||||
|
- [ ] `ProtoSocketTaskService`가 response/error envelope meta를 diagnostics sink에 전달하고 기존 error mapping을 유지한다.
|
||||||
|
- [ ] `WorkspaceHomePage` 또는 app shell에 compact debug surface를 추가해 connection id, protocol version, channel, error code를 확인할 수 있게 한다.
|
||||||
|
- [ ] Flutter tests로 endpoint 설정, reconnect/failure lifecycle, task service diagnostics, widget debug surface를 검증한다.
|
||||||
|
- [ ] `cd apps/client && flutter test`를 허용된 원격/검증 환경에서 실행한다.
|
||||||
|
- [ ] `cd apps/client && flutter analyze --no-fatal-infos`를 허용된 원격/검증 환경에서 실행한다.
|
||||||
|
- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
|
||||||
|
|
||||||
|
## 의존 관계 및 구현 순서
|
||||||
|
|
||||||
|
이 directory name은 `13+11,12_client_diagnostics`이므로 predecessor는 같은 task group의 `11_*`, `12+11_*` subtasks다. `agent-task/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/complete.log`와 `agent-task/m-proto-socket-infrastructure-communication-rail/12+11_core_diagnostics/complete.log` 또는 matching archive `complete.log`가 모두 생긴 뒤 구현을 시작한다.
|
||||||
|
|
||||||
|
### [API-1] Client Diagnostics State
|
||||||
|
|
||||||
|
#### 문제
|
||||||
|
|
||||||
|
[apps/client/lib/src/integrations/proto_socket/proto_socket_lifecycle.dart](/config/workspace/nomadcode/apps/client/lib/src/integrations/proto_socket/proto_socket_lifecycle.dart:31)는 state와 lastError만 보관하고, connection id/protocol/channel/error code를 소비할 diagnostics state가 없다. [apps/client/lib/src/integrations/proto_socket/proto_socket_task_service.dart](/config/workspace/nomadcode/apps/client/lib/src/integrations/proto_socket/proto_socket_task_service.dart:45)는 response/error envelope를 받은 뒤 diagnostics sink에 전달하지 않는다.
|
||||||
|
|
||||||
|
Before:
|
||||||
|
|
||||||
|
```dart
|
||||||
|
31 class ProtoSocketLifecycle {
|
||||||
|
32 final ProtoSocketConnector _connector;
|
||||||
|
33 final StreamController<ProtoSocketConnectionState> _stateController =
|
||||||
|
34 StreamController<ProtoSocketConnectionState>.broadcast();
|
||||||
|
...
|
||||||
|
43 ProtoSocketConnectionState get state => _state;
|
||||||
|
44 Stream<ProtoSocketConnectionState> get stateStream => _stateController.stream;
|
||||||
|
45 Object? get lastError => _lastError;
|
||||||
|
46 ProtoSocketTransport? get transport => _transport;
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 해결 방법
|
||||||
|
|
||||||
|
작은 value object를 추가한다. 새 파일을 만들 경우 `apps/client/lib/src/integrations/proto_socket/proto_socket_diagnostics.dart`에 두고, lifecycle은 `diagnostics` getter와 broadcast stream을 제공한다. Task service에는 optional `void Function(ProtoSocketEnvelope envelope) onEnvelope` 또는 diagnostics sink를 주입해 response/error meta를 기록한다.
|
||||||
|
|
||||||
|
After:
|
||||||
|
|
||||||
|
```dart
|
||||||
|
class ProtoSocketDiagnostics {
|
||||||
|
final ProtoSocketConnectionState state;
|
||||||
|
final String? connectionId;
|
||||||
|
final String? protocolVersion;
|
||||||
|
final String? channel;
|
||||||
|
final String? action;
|
||||||
|
final String? errorCode;
|
||||||
|
}
|
||||||
|
|
||||||
|
Stream<ProtoSocketDiagnostics> get diagnosticsStream => _diagnosticsController.stream;
|
||||||
|
void recordEnvelope(ProtoSocketEnvelope envelope) { ... }
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 수정 파일 및 체크리스트
|
||||||
|
|
||||||
|
- [ ] `apps/client/lib/src/integrations/proto_socket/proto_socket_diagnostics.dart`: diagnostics value/sanitizer 추가.
|
||||||
|
- [ ] `apps/client/lib/src/integrations/proto_socket/proto_socket_lifecycle.dart`: diagnostics state/stream/recording 추가.
|
||||||
|
- [ ] `apps/client/lib/src/integrations/proto_socket/proto_socket_task_service.dart`: response/error envelope를 diagnostics sink에 전달.
|
||||||
|
- [ ] `apps/client/test/integrations/proto_socket_lifecycle_test.dart`: state/failure/envelope diagnostics 테스트 추가.
|
||||||
|
- [ ] `apps/client/test/integrations/proto_socket_task_service_test.dart`: meta/error code recording 테스트 추가.
|
||||||
|
|
||||||
|
#### 테스트 작성
|
||||||
|
|
||||||
|
`proto_socket_lifecycle_test.dart`는 connect/fail/disconnect 시 diagnostics state가 바뀌는지 검증한다. `proto_socket_task_service_test.dart`는 response meta의 `connection_id`, `protocol_version`, `channel`, `action`과 error envelope의 `error.code`가 sink에 전달되는지 검증한다.
|
||||||
|
|
||||||
|
#### 중간 검증
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd apps/client && flutter test test/integrations/proto_socket_lifecycle_test.dart test/integrations/proto_socket_task_service_test.dart
|
||||||
|
```
|
||||||
|
|
||||||
|
기대 결과: 관련 Flutter tests PASS. 명령은 허용된 원격/검증 환경에서 실행한다.
|
||||||
|
|
||||||
|
### [API-2] Workspace Debug Surface
|
||||||
|
|
||||||
|
#### 문제
|
||||||
|
|
||||||
|
[apps/client/lib/src/app/nomadcode_client_app.dart](/config/workspace/nomadcode/apps/client/lib/src/app/nomadcode_client_app.dart:121)는 task service만 page에 연결하고 diagnostics는 전달하지 않는다. [apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart](/config/workspace/nomadcode/apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart:374)는 task section과 error UI만 있고 connection diagnostics surface가 없다.
|
||||||
|
|
||||||
|
Before:
|
||||||
|
|
||||||
|
```dart
|
||||||
|
121 final taskService = ProtoSocketTaskService(transport);
|
||||||
|
122 setState(() {
|
||||||
|
123 _taskLoader = (_) => taskService.listTasks();
|
||||||
|
124 _connectedByThisWidget = startedHere;
|
||||||
|
125 });
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 해결 방법
|
||||||
|
|
||||||
|
App state가 lifecycle diagnostics stream을 구독해 `WorkspaceHomePage`에 snapshot을 넘긴다. Workspace details 상단 또는 ACTIVE TASKS 근처에 compact diagnostics row를 추가한다. 화면에는 `connected/failed`, `conn-*`, protocol version, recent `channel/action`, optional `error_code`만 표시하고 payload/auth/error message 원문은 표시하지 않는다.
|
||||||
|
|
||||||
|
After:
|
||||||
|
|
||||||
|
```dart
|
||||||
|
_diagnosticsSub = lifecycle.diagnosticsStream.listen((next) {
|
||||||
|
if (mounted) setState(() => _protoSocketDiagnostics = next);
|
||||||
|
});
|
||||||
|
|
||||||
|
return WorkspaceHomePage(
|
||||||
|
loadTasks: _taskLoader,
|
||||||
|
protoSocketDiagnostics: _protoSocketDiagnostics,
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 수정 파일 및 체크리스트
|
||||||
|
|
||||||
|
- [ ] `apps/client/lib/src/app/nomadcode_client_app.dart`: diagnostics stream 구독/해제와 page 전달 추가.
|
||||||
|
- [ ] `apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart`: compact debug surface 추가.
|
||||||
|
- [ ] `apps/client/test/widget_test.dart`: connected diagnostics와 error code surface 테스트 추가.
|
||||||
|
|
||||||
|
#### 테스트 작성
|
||||||
|
|
||||||
|
`widget_test.dart`에 lifecycle diagnostics fake 또는 direct diagnostics prop을 사용해 connection id/protocol/channel/error code가 보이고 secret/payload text는 보이지 않는지 검증한다.
|
||||||
|
|
||||||
|
#### 중간 검증
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd apps/client && flutter test test/widget_test.dart
|
||||||
|
```
|
||||||
|
|
||||||
|
기대 결과: widget tests PASS. 명령은 허용된 원격/검증 환경에서 실행한다.
|
||||||
|
|
||||||
|
## 수정 파일 요약
|
||||||
|
|
||||||
|
| 파일 | 항목 |
|
||||||
|
|------|------|
|
||||||
|
| `apps/client/lib/src/integrations/proto_socket/proto_socket_diagnostics.dart` | API-1 |
|
||||||
|
| `apps/client/lib/src/integrations/proto_socket/proto_socket_lifecycle.dart` | API-1 |
|
||||||
|
| `apps/client/lib/src/integrations/proto_socket/proto_socket_task_service.dart` | API-1 |
|
||||||
|
| `apps/client/lib/src/app/nomadcode_client_app.dart` | API-2 |
|
||||||
|
| `apps/client/lib/src/features/workspaces/presentation/workspace_home_page.dart` | API-2 |
|
||||||
|
| `apps/client/test/integrations/proto_socket_lifecycle_test.dart` | API-1 |
|
||||||
|
| `apps/client/test/integrations/proto_socket_task_service_test.dart` | API-1 |
|
||||||
|
| `apps/client/test/widget_test.dart` | API-2 |
|
||||||
|
|
||||||
|
## 최종 검증
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd apps/client && flutter test
|
||||||
|
cd apps/client && flutter analyze --no-fatal-infos
|
||||||
|
```
|
||||||
|
|
||||||
|
기대 결과: Flutter tests PASS, analyzer는 fatal 없이 종료한다. path dependency가 없으면 review stub에 실제 차단 출력을 기록한다. 명령은 허용된 원격/검증 환경에서 실행한다.
|
||||||
|
|
||||||
|
모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다.
|
||||||
|
|
@ -120,7 +120,26 @@
|
||||||
| `internal.error` | 그 외 내부 오류 | true | 500 |
|
| `internal.error` | 그 외 내부 오류 | true | 500 |
|
||||||
| `UNSUPPORTED_ACTION` | dispatcher에 등록되지 않은 action | false | (REST 없음) |
|
| `UNSUPPORTED_ACTION` | dispatcher에 등록되지 않은 action | false | (REST 없음) |
|
||||||
|
|
||||||
### 1.6 새 내부 통신 추가 운영 체크
|
### 1.6 Diagnostics 필드 후보
|
||||||
|
- **설명**: proto-socket 로그와 클라이언트 디버그 표면에서 연결과 메시지 흐름을 추적하기 위한 공통 diagnostics 필드 후보다. 확정 schema가 아니라 Core/Client 구현을 맞추기 위한 compatibility note로만 사용한다.
|
||||||
|
- **안정성 수준**: 후보 (Candidate)
|
||||||
|
- **최소 공통 필드**:
|
||||||
|
|
||||||
|
| 필드 | 위치 | 필수성 | 소비자 책임 |
|
||||||
|
|------|------|--------|-------------|
|
||||||
|
| `connection_id` | envelope `meta.connection_id`, Core log attribute, Client debug surface | 연결이 확립된 response/event/error에서 가능하면 포함 | Core는 연결별 안정 식별자를 부여하고, Client는 표시/필터링에만 사용한다. |
|
||||||
|
| `protocol_version` | envelope top-level, Core log attribute, Client debug surface | 모든 proto-socket envelope에 포함 | Core와 Client는 지원하지 않는 version을 compatibility 문제로 보고하되, secret이나 payload 원문을 함께 출력하지 않는다. |
|
||||||
|
| `channel` | envelope top-level, Core log attribute, Client debug surface | request/response/event/error에서 포함 | dispatcher와 Client debug surface는 channel name을 그대로 노출하되 business payload를 함께 노출하지 않는다. |
|
||||||
|
| `action` | envelope top-level, Core log attribute, Client debug surface | request/response/event/error에서 포함 | request 흐름과 최근 event/error를 추적하는 용도로만 사용한다. |
|
||||||
|
| `error.code` / `error_code` | envelope `error.code`, Core log attribute, Client debug surface | error envelope에서 포함, 성공 envelope에서는 생략 또는 null | Core는 error code를 안정적인 문자열로 기록하고, Client는 최근 오류 요약에만 사용한다. |
|
||||||
|
| `timestamp` | envelope `meta.timestamp`, Core log timestamp, Client debug surface | Core가 발행하는 response/event/error에서 가능하면 포함 | 소비자는 시간 정렬과 최근 상태 표시에 사용하고 clock 차이를 프로토콜 오류로 단정하지 않는다. |
|
||||||
|
|
||||||
|
- **Core log attributes**: `connection_id`, `protocol_version`, `channel`, `action`, `error_code`, `timestamp`를 structured log attribute로 남긴다. error가 없으면 `error_code`는 생략하거나 null로 둔다.
|
||||||
|
- **Envelope meta**: response/event/error는 가능한 경우 `meta.connection_id`, `meta.timestamp`를 포함하고, top-level `protocol_version`, `channel`, `action`과 함께 diagnostics 기준으로 소비된다.
|
||||||
|
- **Client debug surface**: 연결 상태, connection id, protocol version, 최근 channel/action/error code/timestamp만 표시한다.
|
||||||
|
- **노출 금지**: auth token, Basic Auth header, secret, `token_ref`가 가리키는 실제 값, payload/result 원문, 외부 provider credential은 Core log와 Client debug surface에 기록하거나 표시하지 않는다.
|
||||||
|
|
||||||
|
### 1.7 새 내부 통신 추가 운영 체크
|
||||||
- 신규 `apps/client` ↔ `services/core` 또는 내부 runtime 간 통신은 먼저 proto-socket channel/action으로 표현 가능한지 확인한다.
|
- 신규 `apps/client` ↔ `services/core` 또는 내부 runtime 간 통신은 먼저 proto-socket channel/action으로 표현 가능한지 확인한다.
|
||||||
- REST/HTTP를 새로 추가하거나 유지해야 하면 health/readiness, 외부 provider 호환 API, 운영 smoke/curl, public callback, 단순 정적 조회 중 어느 예외인지 이 문서 또는 관련 domain rule에 기록한다.
|
- REST/HTTP를 새로 추가하거나 유지해야 하면 health/readiness, 외부 provider 호환 API, 운영 smoke/curl, public callback, 단순 정적 조회 중 어느 예외인지 이 문서 또는 관련 domain rule에 기록한다.
|
||||||
- 새 channel/action은 envelope의 `protocol_version`, `type`, `channel`, `action`, `correlation_id`, `payload`, `error.retryable` 의미를 이 문서에 추가한다.
|
- 새 channel/action은 envelope의 `protocol_version`, `type`, `channel`, `action`, `correlation_id`, `payload`, `error.retryable` 의미를 이 문서에 추가한다.
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue