diff --git a/agent-roadmap/phase/workflow-core/milestones/proto-socket-infrastructure-communication-rail.md b/agent-roadmap/phase/workflow-core/milestones/proto-socket-infrastructure-communication-rail.md index 1a8bc95..36d0fa8 100644 --- a/agent-roadmap/phase/workflow-core/milestones/proto-socket-infrastructure-communication-rail.md +++ b/agent-roadmap/phase/workflow-core/milestones/proto-socket-infrastructure-communication-rail.md @@ -53,9 +53,9 @@ Core가 내부 런타임 통신용 proto-socket endpoint와 task channel을 제 Flutter client가 no-op proto-socket facade를 실제 Core 연결 레일로 전환한다. -- [ ] [client-connector] `apps/client`의 `NoopProtoSocketConnector`를 대체할 concrete connector를 추가한다. 검증: 설정된 endpoint로 연결 상태가 `connected`까지 전이된다. -- [ ] [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-connector] `apps/client`의 `NoopProtoSocketConnector`를 대체할 concrete connector를 추가한다. 검증: 설정된 endpoint로 연결 상태가 `connected`까지 전이된다. +- [x] [client-task-api] workspace/task 화면이 mock 데이터 대신 Core proto-socket task channel을 소비할 수 있는 client service 경계를 만든다. +- [x] [client-tests] proto-socket endpoint 설정, reconnect/failure lifecycle, client task service를 Flutter test로 검증한다. ### Epic: [ops] Observability and rollout @@ -88,8 +88,10 @@ Flutter client가 no-op proto-socket facade를 실제 Core 연결 레일로 전 - 표준선(선택): 내부 런타임 간 신규 통신은 `proto-socket`을 기본 표준으로 삼고, REST/HTTP는 명시된 예외 조건에서만 유지한다. - 선행 작업: Mattermost Nexo Messaging Alignment, Client Integration Standardization, 프로젝트 룰의 proto-socket 표준 규약 - 후속 작업: 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 후보를 추가했다. - 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 문서화, 검증 항목을 확인하는 운영 체크를 추가했다. - 확인 필요: 없음 diff --git a/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G06_0.log b/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G06_0.log new file mode 100644 index 0000000..0d99757 --- /dev/null +++ b/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G06_0.log @@ -0,0 +1,134 @@ + + +# 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-`이면 완료 이벤트 메타데이터를 보고한다. 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-`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, 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`를 작성한다. diff --git a/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G07_1.log b/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G07_1.log new file mode 100644 index 0000000..5fbbb10 --- /dev/null +++ b/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G07_1.log @@ -0,0 +1,133 @@ + + +# 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-`이면 완료 이벤트 메타데이터를 보고한다. 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-`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, 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`를 작성한다. diff --git a/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G07_2.log b/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G07_2.log new file mode 100644 index 0000000..0944e95 --- /dev/null +++ b/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/code_review_cloud_G07_2.log @@ -0,0 +1,135 @@ + + +# 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-`이면 완료 이벤트 메타데이터를 보고한다. 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-`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, 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로 이동한다. diff --git a/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/complete.log b/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/complete.log new file mode 100644 index 0000000..b68cf45 --- /dev/null +++ b/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/complete.log @@ -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 + +- 없음 + +## 후속 작업 + +- 없음 diff --git a/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/plan_cloud_G06_0.log b/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/plan_cloud_G06_0.log new file mode 100644 index 0000000..bdb3258 --- /dev/null +++ b/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/plan_cloud_G06_0.log @@ -0,0 +1,162 @@ + + +# 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`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다. diff --git a/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/plan_cloud_G07_1.log b/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/plan_cloud_G07_1.log new file mode 100644 index 0000000..7a97e99 --- /dev/null +++ b/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/plan_cloud_G07_1.log @@ -0,0 +1,86 @@ + + +# 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`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다. diff --git a/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/plan_cloud_G07_2.log b/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/plan_cloud_G07_2.log new file mode 100644 index 0000000..0297625 --- /dev/null +++ b/agent-task/archive/2026/05/m-proto-socket-infrastructure-communication-rail/11_contracts_diagnostics/plan_cloud_G07_2.log @@ -0,0 +1,91 @@ + + +# 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`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다. diff --git a/agent-task/m-proto-socket-infrastructure-communication-rail/12+11_core_diagnostics/CODE_REVIEW-cloud-G07.md b/agent-task/m-proto-socket-infrastructure-communication-rail/12+11_core_diagnostics/CODE_REVIEW-cloud-G07.md new file mode 100644 index 0000000..c8abf44 --- /dev/null +++ b/agent-task/m-proto-socket-infrastructure-communication-rail/12+11_core_diagnostics/CODE_REVIEW-cloud-G07.md @@ -0,0 +1,130 @@ + + +# 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-`이면 완료 이벤트 메타데이터를 보고한다. 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-`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, 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. diff --git a/agent-task/m-proto-socket-infrastructure-communication-rail/12+11_core_diagnostics/PLAN-cloud-G07.md b/agent-task/m-proto-socket-infrastructure-communication-rail/12+11_core_diagnostics/PLAN-cloud-G07.md new file mode 100644 index 0000000..ff92105 --- /dev/null +++ b/agent-task/m-proto-socket-infrastructure-communication-rail/12+11_core_diagnostics/PLAN-cloud-G07.md @@ -0,0 +1,223 @@ + + +# 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`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다. diff --git a/agent-task/m-proto-socket-infrastructure-communication-rail/13+11,12_client_diagnostics/CODE_REVIEW-cloud-G07.md b/agent-task/m-proto-socket-infrastructure-communication-rail/13+11,12_client_diagnostics/CODE_REVIEW-cloud-G07.md new file mode 100644 index 0000000..e59d626 --- /dev/null +++ b/agent-task/m-proto-socket-infrastructure-communication-rail/13+11,12_client_diagnostics/CODE_REVIEW-cloud-G07.md @@ -0,0 +1,138 @@ + + +# 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-`이면 완료 이벤트 메타데이터를 보고한다. 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-`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, 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. diff --git a/agent-task/m-proto-socket-infrastructure-communication-rail/13+11,12_client_diagnostics/PLAN-cloud-G07.md b/agent-task/m-proto-socket-infrastructure-communication-rail/13+11,12_client_diagnostics/PLAN-cloud-G07.md new file mode 100644 index 0000000..26a83a0 --- /dev/null +++ b/agent-task/m-proto-socket-infrastructure-communication-rail/13+11,12_client_diagnostics/PLAN-cloud-G07.md @@ -0,0 +1,239 @@ + + +# 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 _stateController = +34 StreamController.broadcast(); +... +43 ProtoSocketConnectionState get state => _state; +44 Stream 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 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`의 구현 에이전트 소유 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다. diff --git a/packages/contracts/notes/flutter-core-api-candidates.md b/packages/contracts/notes/flutter-core-api-candidates.md index 6b51ef7..70e25d4 100644 --- a/packages/contracts/notes/flutter-core-api-candidates.md +++ b/packages/contracts/notes/flutter-core-api-candidates.md @@ -120,7 +120,26 @@ | `internal.error` | 그 외 내부 오류 | true | 500 | | `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으로 표현 가능한지 확인한다. - 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` 의미를 이 문서에 추가한다.