proto-socket/agent-task/quality_improvements/PLAN.md

Quality Improvements — VERSIONING.md 구조 수정

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

plan=0 리뷰에서 WARN이 발생했습니다. 단일 항목만 수정합니다. 완료 후 CODE_REVIEW.md 검증 결과를 채우고 완료 표를 [x]로 갱신하세요.

배경

plan=0 코드 리뷰 결과, REFACTOR-4(VERSIONING.md)에서 ## nonce Overflow 섹션이 ## Non-breaking Protocol Changes 헤더 바로 아래에 삽입되어 구조가 깨졌습니다.

현재 구조:

## Non-breaking Protocol Changes
                          ← 내용 없음
## nonce Overflow
...

Examples of non-breaking changes:   ← nonce Overflow 섹션 아래에 위치 (의미상 오류)

의도한 구조:

## Non-breaking Protocol Changes

Examples of non-breaking changes:
...

Backward-compatible message additions ...

## nonce Overflow
...

---

[DOC-FIX-1] VERSIONING.md ## nonce Overflow 위치 이동

문제

## nonce Overflow가 ## Non-breaking Protocol Changes 바디(Examples 목록, 후속 단락)보다 앞에 위치해 "Examples of non-breaking changes:" 목록이 nonce Overflow 섹션에 속한 것처럼 렌더링됩니다.

해결 방법

## nonce Overflow 블록 전체를 Backward-compatible message additions require ... 단락 뒤로 이동합니다.

목표 구조 (VERSIONING.md 하단):

## Non-breaking Protocol Changes

Examples of non-breaking changes:

- Adding a new protobuf message type.
- Adding optional fields to application messages when older peers can ignore them.
- Adding a new language implementation that passes the existing protocol and cross-language tests.
- Tightening tests or documentation without changing wire behavior.

Backward-compatible message additions require updated parser maps and cross-language tests before release.

## nonce Overflow

`nonce` and `responseNonce` fields are protobuf `int32` values (signed 32-bit).
Overflow occurs after about 2.1 billion sends on a single connection.

Current policy:

- The protocol does not define overflow behavior. Reaching the int32 limit on a single connection is not realistic.
- Implementations do not add recovery logic for overflow.
- If overflow handling is needed in the future, the protocol version will be bumped and wrap-around behavior will be specified.

수정 파일 및 체크리스트

• VERSIONING.md — ## nonce Overflow 섹션을 ## Non-breaking Protocol Changes 바디 아래로 이동

테스트 작성

문서 전용 변경이므로 테스트 불필요.

중간 검증

grep -n "^##" VERSIONING.md
# Non-breaking Protocol Changes가 nonce Overflow보다 먼저 나와야 하고
# Examples of non-breaking changes: 가 Non-breaking Protocol Changes 섹션 안에 있어야 함
grep -n "Examples of non-breaking" VERSIONING.md
grep -n "nonce Overflow" VERSIONING.md
# Examples 줄 번호 < nonce Overflow 줄 번호

---

수정 파일 요약

파일	항목
VERSIONING.md	DOC-FIX-1

최종 검증

grep -n "^##" VERSIONING.md
# 섹션 순서 확인: Non-breaking Protocol Changes → nonce Overflow → New Language Compatibility
grep -A 5 "Non-breaking Protocol Changes" VERSIONING.md
# 바로 아래에 Examples 또는 설명이 와야 함 (nonce Overflow 아님)