update docs and archive task files

PORTING_GUIDE.md

@@ -17,7 +17,7 @@
 |------|---------|------|
 | Transport 분리 | `Transport` interface | WritePacket과 Close만 있으면 됨. 소켓 종류(TCP/WS)에 무관하게 Communicator가 동작 |
 | typeName 라우팅 | `TypeNameOf()` | protobuf full message name 기반. 언어마다 추출 방식이 다르므로 PROTOCOL.md의 언어별 표 확인 |
-| nonce 단조 증가 | `atomic.Int32` | 연결당 1에서 시작, 송신마다 +1. thread-safe하게 구현 |
+| nonce 단조 증가 + 충돌 회피 | `atomic.Int32` + pending-correlation 조회 | 연결당 1에서 시작, 송신마다 +1. 송신 전 candidate nonce가 active pending request의 key(`sendRequest` 대기 중 nonce)와 충돌하면 건너뛴다. candidate 선택과 pending 조회는 같은 임계구역 또는 동등한 동시성 안전성을 가져야 한다. 충돌 없는 값이 없으면 오류로 실패 |
 | connCloseOnce | `sync.Once` | Close가 여러 번 불려도 한 번만 수행되어야 함 |
 | addListener / addRequestListener 상호 배타 | panic or throw | 같은 typeName에 두 가지 동시 등록 금지. 프로토콜 계약 |
 | heartbeat 자동 처리 | `baseClient` 내부 | 앱 코드에서 HeartBeat를 직접 등록하거나 처리하지 않음 |

PROTOCOL.md

@@ -160,6 +160,8 @@ Changing the proto package or `typeName` derivation rule is a breaking protocol
 
 - Starts at `1` per connection
 - Increments by `1` on every send call (including requests and responses)
+- If a candidate nonce matches a currently pending request correlation key (`sendRequest` in-flight `nonce`), implementations must skip the candidate and try the next nonce.
+- If every positive `int32` nonce value is currently pending, outbound send should fail with an explicit error instead of reusing an active pending nonce.
 - Maximum nonce is `2,147,483,647` (`int32` max), the lowest common signed integer max across supported protocol fields
 - After issuing `2,147,483,647`, implementations reset the internal counter to `0`; the next emitted packet nonce is `1`
 - `0` is reserved and must not be emitted as `PacketBase.nonce`, because `responseNonce == 0` means "not a response"

VERSIONING.md

@@ -92,6 +92,8 @@ The maximum emitted nonce is `2,147,483,647` (`int32` max).
 Current policy:
 
 - Implementations start at `1` and increment by `1` on every send call, including requests and responses.
+- When selecting the next nonce to emit, implementations must skip any value that is currently used by an active pending request (`sendRequest` correlation map). This keeps nonce reuse from colliding with in-flight requests after wrap.
+- If all positive `int32` nonce values are currently pending, `sendRequest`/`send` must fail explicitly rather than emit a duplicate correlation nonce.
 - After issuing `2,147,483,647`, implementations reset the internal counter to `0`; the next emitted `PacketBase.nonce` is `1`.
 - `0` is reserved and must not be emitted as `PacketBase.nonce`, because `responseNonce == 0` means "not a response".
 

agent-task/archive/2026/06/m-protocol-evolution-compatibility/04+03_nonce_contract/code_review_local_G04_0.log

@@ -40,42 +40,44 @@ task=m-protocol-evolution-compatibility/04+03_nonce_contract, plan=0, tag=API
 
 | 항목 | 완료 여부 |
 |------|---------|
-| [API-1] Nonce Contract 문서화 | [ ] |
-| [API-2] Porting 기준 정렬 | [ ] |
+| [API-1] Nonce Contract 문서화 | [x] |
+| [API-2] Porting 기준 정렬 | [x] |
 
 ## 구현 체크리스트
 
-- [ ] `PROTOCOL.md`의 `nonce` 섹션에 active pending nonce skip 정책과 all-positive-nonces-pending 예외를 명시한다.
-- [ ] `VERSIONING.md`의 `nonce Overflow` 정책에 pending 충돌 회피와 호환성 기준을 반영한다.
-- [ ] `PORTING_GUIDE.md`의 nonce 공통 구조 설명을 pending skip 기준으로 보강한다.
-- [ ] `tools/check_proto_sync.sh`와 `git diff --check`를 실행한다.
-- [ ] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채운다. 이 항목이 완료되기 전에는 구현이 완료된 것이 아니다.
+- [x] `PROTOCOL.md`의 `nonce` 섹션에 active pending nonce skip 정책과 all-positive-nonces-pending 예외를 명시했다.
+- [x] `VERSIONING.md`의 `nonce Overflow` 정책에 pending 충돌 회피와 호환성 기준을 반영했다.
+- [x] `PORTING_GUIDE.md`의 nonce 공통 구조 설명을 pending skip 기준으로 보강했다.
+- [x] `tools/check_proto_sync.sh`와 `git diff --check`를 실행해 PASS/정상 결과를 확인했다.
+- [x] CODE_REVIEW-*-G??.md의 구현 에이전트 소유 섹션을 실제 구현 내용과 검증 출력으로 채웠다.
 
 ## 코드리뷰 전용 체크리스트
 
 > **[REVIEW AGENT ONLY]** 이 체크리스트는 코드리뷰 에이전트만 사용한다.
 > 구현 에이전트는 이 섹션을 수정하거나 체크하지 않는다.
 
-- [ ] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
-- [ ] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
-- [ ] active `CODE_REVIEW-*-G??.md`를 `code_review_{review_lane}_GNN_N.log`로 아카이브한다.
-- [ ] active `PLAN-*-G??.md`를 `plan_{build_lane}_GNN_M.log`로 아카이브한다.
-- [ ] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다.
-- [ ] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
-- [ ] PASS이면 active task 디렉터리 `agent-task/{task_name}/`를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
-- [ ] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
-- [ ] PASS split 작업이면 이동 후 빈 active parent `agent-task/{task_group}/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
+- [x] `코드리뷰 결과`에 `PASS`, `WARN`, `FAIL` 중 하나의 판정을 append한다.
+- [x] 판정과 `차원별 평가`, Required/Suggested/Nit 분류가 서로 일치한다.
+- [x] active `CODE_REVIEW-*-G??.md`를 `code_review_{review_lane}_GNN_N.log`로 아카이브한다.
+- [x] active `PLAN-*-G??.md`를 `plan_{build_lane}_GNN_M.log`로 아카이브한다.
+- [x] `.gitignore`의 Agent-Ops 관리 block이 `agent-task/**/*.md`와 `agent-task/**/*.log`를 unignore하고 `agent-roadmap/current.md`를 ignore하는지 확인한다.
+- [x] PASS이면 `agent-ops/skills/common/code-review/templates/complete-log-template.md` 기준으로 `complete.log`를 작성하고 active `.md` 파일을 남기지 않는다.
+- [x] PASS이면 active task 디렉터리 `agent-task/{task_name}/`를 `agent-task/archive/YYYY/MM/{task_name}/`로 이동하고 최종 archive 경로에서 이 체크리스트를 갱신한다.
+- [x] PASS이고 task group이 `m-<milestone-slug>`이면 런타임이 읽을 완료 이벤트 메타데이터를 보고하고, roadmap 수정이나 `update-roadmap` 직접 호출을 하지 않는다.
+- [x] PASS split 작업이면 이동 후 빈 active parent `agent-task/{task_group}/`를 제거하거나, 남은 sibling/file이 있어 유지했다고 확인한다.
 - [ ] WARN/FAIL이고 user-review gate가 트리거되지 않았으면 다음 active `PLAN-{build_lane}-GNN.md`와 `CODE_REVIEW-{review_lane}-GNN.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로 이동한다.
 
 ## 계획 대비 변경 사항
 
-_구현 에이전트가 계획과 다르게 구현한 부분을 이유와 함께 기록한다._
+계획과 동일하게 문서 계약 3개 파일(PROTOCOL, VERSIONING, PORTING_GUIDE)만 수정했다.
 
 ## 주요 설계 결정
 
-_구현 에이전트가 주요 설계 결정 사항을 기록한다._
+- Nonce wrap는 더 이상 단순 `현재값+1`이 아닌, 발신 전 active pending request nonce 충돌 검사 후 건너뛰기(skip)로 보강한다.
+- 충돌 회피를 문서화하되, 구현 방식(구체적인 조회 자료구조/알고리즘)은 언어별 구현 단계로 넘겨서 일관된 동작 기준만 고정했다.
+- 모든 양수 nonce가 pending 상태일 때는 새로운 발신을 에러로 실패하도록 명시해, 기존 동작(`0`으로 wrap 후 즉시 1 사용)의 회피 경로를 계약화했다.
 
 ## 사용자 리뷰 요청
 
@@ -107,20 +109,21 @@ _구현 에이전트가 각 중간 검증 및 최종 검증 명령 실행 후
 ### API-1 중간 검증
 ```bash
 $ tools/check_proto_sync.sh
-(output)
+Proto schemas are in sync.
 ```
 
 ### API-2 중간 검증
 ```bash
 $ git diff --check
-(output)
+(no output)
 ```
 
 ### 최종 검증
 ```bash
 $ tools/check_proto_sync.sh
 $ git diff --check
-(output)
+Proto schemas are in sync.
+(no output)
 ```
 
 ---
@@ -142,3 +145,21 @@ $ git diff --check
 | 사용자 리뷰 요청 | Implementing agent | Keep `상태: 없음` unless user input is required to proceed |
 | 리뷰어를 위한 체크포인트 | Fixed at stub creation | Review focus areas |
 | 검증 결과 | Implementing agent | Fill command output only |
+
+## 코드리뷰 결과
+
+- 종합 판정: PASS
+- 차원별 평가:
+  - Correctness: Pass
+  - Completeness: Pass
+  - Test coverage: Pass
+  - API contract: Pass
+  - Code quality: Pass
+  - Plan deviation: Pass
+  - Verification trust: Pass
+- 발견된 문제: 없음
+- 리뷰 중 직접 보정:
+  - `PORTING_GUIDE.md`의 nonce 포팅 기준에 candidate 선택과 pending 조회의 동시성 안전성 문장을 보강했다. 계획의 API-2 해결 방법에 포함된 문구이며, 문서-only 범위 안의 비동작 보정이다.
+- PASS split 정리:
+  - active parent `agent-task/m-protocol-evolution-compatibility/`는 sibling `05+04_nonce_dart_go`, `06+04,05_nonce_kotlin_python_ts`가 남아 있어 유지했다.
+- 다음 단계: PASS 절차에 따라 `complete.log` 작성 후 task directory를 archive로 이동한다.

agent-task/archive/2026/06/m-protocol-evolution-compatibility/04+03_nonce_contract/complete.log

@@ -0,0 +1,34 @@
+# Complete - m-protocol-evolution-compatibility/04+03_nonce_contract
+
+## 완료 일시
+
+2026-06-17
+
+## 요약
+
+Nonce contract 문서화 task를 1회 리뷰 루프로 완료했으며 최종 판정은 PASS다.
+
+## 루프 이력
+
+| Plan | Review | Verdict | 메모 |
+|------|--------|---------|------|
+| `plan_local_G04_0.log` | `code_review_local_G04_0.log` | PASS | nonce pending collision skip 계약과 porting 기준이 문서에 반영됨 |
+
+## 구현/정리 내용
+
+- `PROTOCOL.md`에 active pending request nonce와 충돌하는 candidate nonce skip 및 all-positive-nonces-pending 실패 정책을 추가했다.
+- `VERSIONING.md`의 nonce overflow 정책에 pending 충돌 회피와 wrap 호환성 기준을 반영했다.
+- `PORTING_GUIDE.md`의 nonce 공통 구조 설명을 pending skip 기준과 동시성 안전성 기준으로 보강했다.
+
+## 최종 검증
+
+- `tools/check_proto_sync.sh` - PASS; `Proto schemas are in sync.`
+- `git diff --check` - PASS; 출력 없음
+
+## 잔여 Nit
+
+- 없음
+
+## 후속 작업
+
+- 없음