diff --git a/README.md b/README.md index 0d19651..c6bdefe 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,22 @@ Built on Protocol Buffers with TCP length-prefixed framing, WebSocket binary fra --- +## Current Status + +Proto Socket currently treats the Dart, Go, Kotlin, Python, and TypeScript implementations as the available compatibility set for protocol `0.1`. + +The project is in a stabilization and maintenance pass before adding more language targets or publishing package registry releases. Git-based consumption from this repository is the primary supported workflow for now. C# and Swift remain planned targets, but implementation work is deferred until there is concrete demand. + +Use the local validation matrix as the stability gate for protocol or implementation changes: + +```bash +bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all +``` + +Protocol or public API changes should be treated as compatibility work: update the relevant docs, regenerate protobuf bindings when needed, and keep the full validation matrix passing. + +--- + ## Design Principles - Keep the core transport layer thin and stable @@ -36,16 +52,47 @@ Protocol compatibility is tracked separately from language package versions. See | Language | Status | Path | Use case | |----------|--------|------|----------| | Dart | Available | [dart/](dart/) | Flutter, Dart server | -| C# | Planned | `csharp/` | Unity, .NET | -| Kotlin | Available | kotlin/ | Android, JVM | -| Swift | Planned | `swift/` | iOS, macOS | +| Kotlin | Available | [kotlin/](kotlin/) | Android, JVM | | Go | Available | [go/](go/) | Server, tooling, scripting | | TypeScript | Available | [typescript/](typescript/) | Browser, Node.js | | Python | Available | [python/](python/) | Server, tooling, scripting | +| C# | Planned / deferred | `csharp/` | Unity, .NET | +| Swift | Planned / deferred | `swift/` | iOS, macOS | New language implementations should start from [PORTING_GUIDE.md](PORTING_GUIDE.md) and the templates in [agent-ops/skills/project/add-proto-socket-crosstest-language/templates/](agent-ops/skills/project/add-proto-socket-crosstest-language/templates/). Mark an implementation available only after its same-language tests and cross-language tests pass. -Detailed planning now lives in [agent-ops/roadmap/ROADMAP.md](agent-ops/roadmap/ROADMAP.md). Keep implementation status here as the public snapshot; roadmap direction, CI automation, and future C#/Swift work are tracked in the roadmap. +Keep implementation status here as the public snapshot. Current work context is selected through [agent-ops/roadmap/current.md](agent-ops/roadmap/current.md), and broader roadmap direction lives in [agent-ops/roadmap/ROADMAP.md](agent-ops/roadmap/ROADMAP.md). + +--- + +## Common Commands + +| Purpose | Command | Notes | +|---------|---------|-------| +| Full local validation | `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all` | Proto sync, same-language tests, and all available cross-language checks | +| Proto schema sync check | `tools/check_proto_sync.sh` | Verifies language proto copies match `proto/message_common.proto` except allowed language options | +| Regenerate protobuf bindings | `tools/generate_proto.sh` | Run after changing the canonical proto schema | +| Dart tests | `cd dart && dart pub get && dart test` | Dart same-language checks | +| Go tests | `cd go && go test ./...` | Go same-language checks | +| Kotlin tests | `cd kotlin && ./gradlew test` | Kotlin same-language checks | +| Python tests | `cd python && python3 -m pytest -q` | Python same-language checks | +| TypeScript checks | `cd typescript && npm run check && npm test` | TypeScript type check and tests | + +--- + +## Repository Structure + +| Path | Role | +|------|------| +| [proto/](proto/) | Canonical protobuf schema source | +| [dart/](dart/) | Dart / Flutter implementation and tests | +| [go/](go/) | Go implementation, tests, and Go-led crosstests | +| [kotlin/](kotlin/) | Kotlin / JVM implementation and crosstests | +| [python/](python/) | Python implementation and crosstests | +| [typescript/](typescript/) | TypeScript implementation and crosstests | +| [tools/](tools/) | Proto generation and sync helpers | +| [examples/](examples/) | Consumer-oriented examples | +| [agent-ops/](agent-ops/) | Project rules, roadmap, and repeatable agent workflows | --- @@ -180,7 +227,7 @@ bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh It runs proto schema sync, same-language tests, and cross-language checks, then prints PASS/FAIL tables with reproduction commands for failures. Use `--proto`, `--unit`, or `--cross` to run a smaller slice. -Continuous verification runner integration is tracked in [agent-ops/roadmap/ROADMAP.md](agent-ops/roadmap/ROADMAP.md). +External CI runner integration is deferred until the parent `../oto` project standardizes its execution path. Until then, the local matrix above is the project stability gate. Proto schema sync: @@ -258,3 +305,16 @@ cd typescript ./node_modules/.bin/tsx crosstest/typescript_kotlin.ts ./node_modules/.bin/tsx crosstest/typescript_python.ts ``` + +--- + +## Work Context + +Before making code or protocol changes, check the project rules in [agent-ops/rules/project/rules.md](agent-ops/rules/project/rules.md) and any matching domain rule listed there. The active roadmap window is in [agent-ops/roadmap/current.md](agent-ops/roadmap/current.md). + +Stabilization boundaries: + +- Keep protocol `0.1` behavior stable unless compatibility work is explicitly requested. +- Do not start C# or Swift implementation work as part of stabilization. +- Do not start package registry release work as part of stabilization. +- Do not connect external CI/CD runners from this repository until the parent `../oto` workflow is decided. diff --git a/agent-ops/roadmap/ROADMAP.md b/agent-ops/roadmap/ROADMAP.md index de3b4db..18cb711 100644 --- a/agent-ops/roadmap/ROADMAP.md +++ b/agent-ops/roadmap/ROADMAP.md @@ -1,4 +1,4 @@ -# Proto Socket 로드맵 +# 로드맵 ## 전체 목표 @@ -6,51 +6,47 @@ Proto Socket은 여러 언어와 플랫폼에서 일관되게 동작하는 얇 코어는 작게 유지한다. 인증, 세션, 채팅, 게임 규칙, 룸 로직, 에이전트 워크플로 같은 애플리케이션 의미는 이 프로토콜 계층 위에서 다룬다. -## 활성 창 +## Phase 흐름 -현재 일반 작업에서 우선 확인할 활성 Milestone 후보는 `agent-ops/roadmap/current.md`에 둔다. 이 문서는 전체 방향, 단계 흐름, Milestone 순서를 갱신할 때만 읽는다. - -## 마이그레이션 메모 - -이 로드맵은 기존 상위 문서에 흩어져 있던 로드맵성 계획을 분리한 것이다. - -- `README.md` 구현 상태 표: 사용 가능/계획 언어 작업으로 Milestone 목록에 요약했다. -- `README.md` 로드맵 방향 문단: 사용 가능 언어 parity, C# Unity/.NET 포트, Swift Apple 플랫폼 포트의 의존성 및 native platform 방향으로 옮겼다. -- `README.md` 지속 검증 계획 메모: 지속 검증으로 옮겼다. -- `PORTING_GUIDE.md` C# 및 Swift 가이드: 계획된 포팅 Milestone에 연결했다. -- 이전 로드맵의 순번 붙은 단계명, Milestone 이름, Milestone 파일명은 순번 없는 이름과 slug로 정리했다. - -## 단계 개요 - -| 단계 | 상태 | 목표 | -|-------|--------|------| -| 프로토콜 기반 | 완료 | 프로토콜 버전 `0.1`, 와이어 포맷, 버전 정책, canonical proto 원본, 레퍼런스 구현 패턴을 정의한다. | -| 검증과 호환성 | 완료 | 동일 언어 테스트, 크로스 언어 테스트, proto 동기화 검사, 지속 검증으로 사용 가능한 구현체들을 정렬한다. | -| 안정화와 유지 | 진행 중 | 현재 5개 언어 구현을 완성형 후보로 보고 안정성 판단, 문서 정합성, 유지 기준을 정리한다. | -| 남은 native platform 포팅 | 보류 | 실제 수요가 생기기 전까지 C# 및 Swift 구현 추가를 보류한다. | -| 릴리즈 준비 | 보류 | Git 기반 사용으로 충분한 동안 외부 package registry 릴리즈 준비를 보류한다. | +- 프로토콜 기반: 프로토콜 버전 `0.1`, 와이어 포맷, 버전 정책, canonical proto 원본, 레퍼런스 구현 패턴을 정의한다. +- 검증과 호환성: 동일 언어 테스트, 크로스 언어 테스트, proto 동기화 검사, 지속 검증으로 사용 가능한 구현체들을 정렬한다. +- 안정화와 유지: 현재 5개 언어 구현을 완성형 후보로 보고 안정성 판단, 문서 정합성, 유지 기준을 정리한다. +- 남은 native platform 포팅: 실제 수요가 생기기 전까지 C# 및 Swift 구현 추가를 보류한다. +- 릴리즈 준비: Git 기반 사용으로 충분한 동안 외부 package registry 릴리즈 준비를 보류한다. ## Milestone 목록 -| Milestone | 단계 | 상태 | 파일 | 요약 | -|-----------|-------|--------|------|---------| -| 프로토콜 기준선 | 프로토콜 기반 | 완료 | agent-ops/roadmap/milestones/protocol-baseline.md | 프로토콜 `0.1`, canonical proto, 프레이밍, 하트비트, nonce, 버전 정책을 문서화했다. | -| 사용 가능 언어 parity | 검증과 호환성 | 완료 | agent-ops/roadmap/milestones/available-language-parity.md | Dart, Go, Kotlin, Python, TypeScript가 사용 가능 상태이며 동일 언어 및 크로스 언어 테스트 진입점이 있다. | -| 지속 검증 | 검증과 호환성 | 완료 | agent-ops/roadmap/milestones/continuous-verification.md | 지원 언어, 크로스 언어 테스트, proto 동기화 검사를 저장소 로컬 검증 진입점으로 자동화했다. 외부 실행기는 상위 `../oto` 프로젝트의 표준 CI/CD 실행 방식이 확정된 뒤 연결한다. | -| 안정화 기준선 | 안정화와 유지 | 진행 중 | agent-ops/roadmap/milestones/stability-baseline.md | 현재 5개 언어 구현을 완성형 후보로 보고 안정성 판단과 유지 기준을 정리한다. | -| C# Unity/.NET 포트 | 남은 native platform 포팅 | 보류 | 실제 Unity/.NET 소비 수요가 생길 때까지 C# 구현 추가를 보류한다. | -| Swift Apple 플랫폼 포트 | 남은 native platform 포팅 | 보류 | 실제 iOS/macOS 소비 수요가 생길 때까지 Swift 구현 추가를 보류한다. | -| 릴리즈 준비 | 릴리즈 준비 | 보류 | Git 기반 사용으로 충분한 동안 package registry 릴리즈 준비를 보류한다. | +### 프로토콜 기반 + +- [프로토콜 기준선](milestones/protocol-baseline.md) - 상태: 완료; 목표: 프로토콜 `0.1`, canonical proto, 프레이밍, 하트비트, nonce, 버전 정책을 문서화한다. + +### 검증과 호환성 + +- [사용 가능 언어 parity](milestones/available-language-parity.md) - 상태: 완료; 목표: Dart, Go, Kotlin, Python, TypeScript가 사용 가능 상태이며 동일 언어 및 크로스 언어 테스트 진입점을 갖춘다. +- [지속 검증](milestones/continuous-verification.md) - 상태: 완료; 목표: 지원 언어, 크로스 언어 테스트, proto 동기화 검사를 저장소 로컬 검증 진입점으로 자동화한다. + +### 안정화와 유지 + +- [안정화 기준선](milestones/stability-baseline.md) - 상태: 진행 중; 목표: 현재 5개 언어 구현을 완성형 후보로 보고 안정성 판단과 유지 기준을 정리한다. + +### 남은 native platform 포팅 + +- [C# Unity/.NET 포트](milestones/csharp-port.md) - 상태: 보류; 목표: 실제 Unity/.NET 소비 수요가 생길 때까지 C# 구현 추가를 보류한다. +- [Swift Apple 플랫폼 포트](milestones/swift-port.md) - 상태: 보류; 목표: 실제 iOS/macOS 소비 수요가 생길 때까지 Swift 구현 추가를 보류한다. + +### 릴리즈 준비 + +- [릴리즈 준비](milestones/release-readiness.md) - 상태: 보류; 목표: Git 기반 사용으로 충분한 동안 package registry 릴리즈 준비를 보류한다. ## 로딩 정책 -- 일반 구현 작업은 `agent-ops/roadmap/current.md`와 관련 활성 Milestone 파일만 읽는다. -- 전체 `ROADMAP.md`는 로드맵 생성/갱신, 단계 전환, Milestone 추가, Milestone 재구성 요청에서만 읽는다. -- 요청된 작업이 선택한 Milestone의 목표 또는 범위 제외 항목과 충돌하면 구현 전에 멈추고 방향을 확인한다. - -## 확인 필요 - -- 안정화 기준선에서 현재 5개 언어 구현을 완성형으로 유지할지 판단한다. -- 실제 소비 수요가 생기면 C# 또는 Swift 포팅 보류를 해제할 수 있다. -- 외부 package registry 릴리즈 필요성이 생기면 릴리즈 준비 보류를 해제한다. -- 상위 `../oto` 프로젝트의 표준 CI/CD 실행 방식과 Proto Socket 검증 진입점의 연결 계약은 아직 확정되지 않았다. +- 일반 작업에서는 `agent-ops/roadmap/ROADMAP.md`를 매번 읽지 않는다. +- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-ops/roadmap/current.md`를 먼저 읽는다. +- `current.md`는 현재 작업 위치가 아니라 활성 Milestone 후보 목록이다. +- `current.md`에는 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다. +- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Milestone 문서를 같은 세션에서 1회 읽는다. +- 활성 Milestone 밖의 작업이면 이 문서의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다. +- 이 문서는 로드맵 생성/갱신, Phase 전환, Milestone 추가/수정 요청이 있을 때만 읽는다. +- 상세 작업과 완료 기준은 각 Milestone 문서의 체크리스트로 관리한다. +- 이 로드맵은 기존 `README.md`의 구현 상태, 로드맵 방향, 지속 검증 메모와 `PORTING_GUIDE.md`의 C#/Swift 포팅 가이드를 Milestone 문서로 분리한 것이다. +- 이전 로드맵의 순번 붙은 단계명, Milestone 이름, Milestone 파일명은 순번 없는 이름과 slug로 정리했다. diff --git a/agent-ops/roadmap/current.md b/agent-ops/roadmap/current.md index 5baf2d6..30d4a71 100644 --- a/agent-ops/roadmap/current.md +++ b/agent-ops/roadmap/current.md @@ -6,6 +6,7 @@ ## 선택 규칙 -- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 Milestone을 선택한다. +- 이 문서는 활성 Milestone 후보 목록이며, 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다. +- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 Milestone을 선택하고 같은 세션에서 1회 읽는다. - 활성 Milestone 둘 이상에 걸치면 필요한 Milestone 문서를 모두 읽고 작업 범위를 좁힌다. - 활성 Milestone 밖의 작업이면 `agent-ops/roadmap/ROADMAP.md`의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다. diff --git a/agent-ops/roadmap/milestones/available-language-parity.md b/agent-ops/roadmap/milestones/available-language-parity.md index 97104a6..5bf7396 100644 --- a/agent-ops/roadmap/milestones/available-language-parity.md +++ b/agent-ops/roadmap/milestones/available-language-parity.md @@ -31,9 +31,9 @@ ## 완료 기준 -- 유지보수자는 상위 문서에서 사용 가능 구현체와 계획 구현체를 식별할 수 있다. -- 새 언어 작업은 `PORTING_GUIDE.md`와 프로젝트 crosstest 템플릿에서 시작할 수 있다. -- 사용 가능 구현체들은 문서화된 프로토콜 계약을 유지한다. +- [x] 유지보수자는 상위 문서에서 사용 가능 구현체와 계획 구현체를 식별할 수 있다. +- [x] 새 언어 작업은 `PORTING_GUIDE.md`와 프로젝트 crosstest 템플릿에서 시작할 수 있다. +- [x] 사용 가능 구현체들은 문서화된 프로토콜 계약을 유지한다. ## 범위 제외 @@ -43,4 +43,7 @@ ## 작업 컨텍스트 -언어 구현을 추가하거나 변경할 때는 `PORTING_GUIDE.md`와 프로젝트 스킬 `agent-ops/skills/project/add-proto-socket-crosstest-language/SKILL.md`를 사용한다. 프로토콜 파일을 변경하기 전에는 protocol domain rule을 읽는다. +- 관련 경로: `README.md`, `PROTOCOL.md`, `PORTING_GUIDE.md`, `agent-ops/skills/project/add-proto-socket-crosstest-language/SKILL.md` +- 선행 작업: 프로토콜 기준선 +- 후속 작업: 지속 검증 +- 확인 필요: 없음 diff --git a/agent-ops/roadmap/milestones/continuous-verification.md b/agent-ops/roadmap/milestones/continuous-verification.md index 7f9a59f..c80a9c2 100644 --- a/agent-ops/roadmap/milestones/continuous-verification.md +++ b/agent-ops/roadmap/milestones/continuous-verification.md @@ -35,10 +35,10 @@ ## 완료 기준 -- 단일 로컬 검증 명령이 proto 동기화, 전체 지원 언어, 크로스 언어 매트릭스를 검증할 수 있다. -- 실패가 proto 동기화, 실패한 언어 쌍, 또는 동일 언어 package를 명확히 식별한다. -- `README.md`의 로컬 명령이 프로젝트 test-matrix 스킬과 일치한다. -- 외부 CI/CD 실행기 연결은 상위 `../oto` 프로젝트와의 실행 계약이 확정될 때 별도 작업으로 진행할 수 있다. +- [x] 단일 로컬 검증 명령이 proto 동기화, 전체 지원 언어, 크로스 언어 매트릭스를 검증할 수 있다. +- [x] 실패가 proto 동기화, 실패한 언어 쌍, 또는 동일 언어 package를 명확히 식별한다. +- [x] `README.md`의 로컬 명령이 프로젝트 test-matrix 스킬과 일치한다. +- [x] 외부 CI/CD 실행기 연결은 상위 `../oto` 프로젝트와의 실행 계약이 확정될 때 별도 작업으로 진행할 수 있다. ## 범위 제외 @@ -50,12 +50,8 @@ ## 작업 컨텍스트 -가장 가까운 기존 자동화 맥락으로 `agent-ops/skills/project/run-proto-socket-test-matrix/SKILL.md`와 `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh`를 사용한다. Jenkins는 후보에서 제외하고, 외부 실행기는 상위 `../oto` 프로젝트의 표준 CI/CD 실행 방식이 정해진 뒤 연결한다. - -## 검증 기록 - -- 2026-05-21: `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all` 통과. Proto 동기화, Dart/Go/Kotlin/Python/TypeScript 동일 언어 테스트, 20개 크로스 언어 방향이 모두 `PASS`. - -## 확인 필요 - -- 상위 `../oto` 프로젝트의 표준 CI/CD 실행 방식이 확정되면 이 저장소의 로컬 검증 진입점을 외부 실행기로 연결한다. +- 관련 경로: `agent-ops/skills/project/run-proto-socket-test-matrix/SKILL.md`, `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh`, `README.md` +- 선행 작업: 사용 가능 언어 parity +- 후속 작업: 안정화 기준선 +- 검증 기록: 2026-05-21에 `bash agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh --all` 통과. Proto 동기화, Dart/Go/Kotlin/Python/TypeScript 동일 언어 테스트, 20개 크로스 언어 방향이 모두 `PASS`. +- 확인 필요: 상위 `../oto` 프로젝트의 표준 CI/CD 실행 방식이 확정되면 이 저장소의 로컬 검증 진입점을 외부 실행기로 연결한다. diff --git a/agent-ops/roadmap/milestones/csharp-port.md b/agent-ops/roadmap/milestones/csharp-port.md index da2f492..0db0285 100644 --- a/agent-ops/roadmap/milestones/csharp-port.md +++ b/agent-ops/roadmap/milestones/csharp-port.md @@ -32,9 +32,9 @@ ## 완료 기준 -- C# peer가 문서화된 프로토콜을 통해 최소 하나의 사용 가능 구현체와 상호 운용된다. -- C# 구현체는 `PORTING_GUIDE.md`를 따르며 Unity main-thread concern을 프로토콜 core 밖에 둔다. -- 런타임 의존성 선택은 문서화되어 있고 protocol-relevant하다. +- [ ] C# peer가 문서화된 프로토콜을 통해 최소 하나의 사용 가능 구현체와 상호 운용된다. +- [ ] C# 구현체는 `PORTING_GUIDE.md`를 따르며 Unity main-thread concern을 프로토콜 core 밖에 둔다. +- [ ] 런타임 의존성 선택은 문서화되어 있고 protocol-relevant하다. ## 범위 제외 @@ -44,4 +44,8 @@ ## 작업 컨텍스트 -현재는 새 언어 확장 필요성이 낮아 보류한다. 실제 Unity/.NET 소비 수요가 생기면 `PORTING_GUIDE.md`의 C# 섹션을 사용한다. 동시성과 close-once 패턴은 Go를, public API 형태와 parser map 예시는 Dart를 참고한다. +- 관련 경로: `PORTING_GUIDE.md`, `PROTOCOL.md`, `VERSIONING.md` +- 선행 작업: 안정화 기준선 완료 또는 실제 Unity/.NET 소비 수요 확인 +- 후속 작업: 릴리즈 준비 +- 참고 구현: 동시성과 close-once 패턴은 Go를, public API 형태와 parser map 예시는 Dart를 참고한다. +- 확인 필요: 지원할 .NET 및 Unity version target diff --git a/agent-ops/roadmap/milestones/protocol-baseline.md b/agent-ops/roadmap/milestones/protocol-baseline.md index ad9ee78..9cc26c1 100644 --- a/agent-ops/roadmap/milestones/protocol-baseline.md +++ b/agent-ops/roadmap/milestones/protocol-baseline.md @@ -30,9 +30,9 @@ ## 완료 기준 -- 구현자는 `PROTOCOL.md`, `VERSIONING.md`, `PORTING_GUIDE.md`를 기준으로 호환되는 언어 포트를 만들 수 있다. -- 프로토콜 수준 변경에는 명시적인 호환성 검토 경로가 있다. -- 생성된 언어별 proto 사본은 canonical schema와 대조할 수 있다. +- [x] 구현자는 `PROTOCOL.md`, `VERSIONING.md`, `PORTING_GUIDE.md`를 기준으로 호환되는 언어 포트를 만들 수 있다. +- [x] 프로토콜 수준 변경에는 명시적인 호환성 검토 경로가 있다. +- [x] 생성된 언어별 proto 사본은 canonical schema와 대조할 수 있다. ## 범위 제외 @@ -42,4 +42,7 @@ ## 작업 컨텍스트 -와이어 포맷의 기준 문서는 `PROTOCOL.md`, 호환성 정책의 기준 문서는 `VERSIONING.md`다. Proto schema가 바뀌면 binding을 재생성하고 `tools/check_proto_sync.sh`를 실행한다. +- 관련 경로: `PROTOCOL.md`, `VERSIONING.md`, `PORTING_GUIDE.md`, `proto/message_common.proto`, `tools/check_proto_sync.sh` +- 선행 작업: 없음 +- 후속 작업: 사용 가능 언어 parity +- 확인 필요: 없음 diff --git a/agent-ops/roadmap/milestones/release-readiness.md b/agent-ops/roadmap/milestones/release-readiness.md index bc56a08..127e677 100644 --- a/agent-ops/roadmap/milestones/release-readiness.md +++ b/agent-ops/roadmap/milestones/release-readiness.md @@ -29,9 +29,9 @@ ## 완료 기준 -- 유지보수자는 호환성 checklist를 추측하지 않고 언어 package를 릴리즈할 수 있다. -- Package release는 package version 변경과 별도로 protocol version 지원을 전달한다. -- 릴리즈 문서는 wire format 또는 required behavior가 바뀌지 않는 한 protocol bump를 암시하지 않는다. +- [ ] 유지보수자는 호환성 checklist를 추측하지 않고 언어 package를 릴리즈할 수 있다. +- [ ] Package release는 package version 변경과 별도로 protocol version 지원을 전달한다. +- [ ] 릴리즈 문서는 wire format 또는 required behavior가 바뀌지 않는 한 protocol bump를 암시하지 않는다. ## 범위 제외 @@ -41,4 +41,7 @@ ## 작업 컨텍스트 -현재는 Git 기반 사용으로 충분하고 package registry 릴리즈 필요성이 낮아 보류한다. 릴리즈 호환성 기준 문서는 `VERSIONING.md`다. README는 package가 아직 배포되지 않았더라도 저장소에 포함된 구현체가 문서화된 프로토콜 계약을 유지해야 한다고 설명한다. +- 관련 경로: `VERSIONING.md`, `README.md` +- 선행 작업: 안정화 기준선 완료 또는 package registry 릴리즈 수요 확인 +- 후속 작업: 없음 +- 확인 필요: 사용 가능 언어별 package registry target과 릴리즈 순서 diff --git a/agent-ops/roadmap/milestones/stability-baseline.md b/agent-ops/roadmap/milestones/stability-baseline.md index 6fb4073..9dcc513 100644 --- a/agent-ops/roadmap/milestones/stability-baseline.md +++ b/agent-ops/roadmap/milestones/stability-baseline.md @@ -30,9 +30,9 @@ ## 완료 기준 -- 현재 5개 언어 구현을 당분간 완성형으로 유지할지 판단할 수 있는 근거가 정리되어 있다. -- 전체 검증 매트릭스와 proto 동기화 검사가 안정성 판단 기준으로 문서화되어 있다. -- 새 언어 확장, package 릴리즈, 프로토콜 변경을 언제 재개할지 기준이 명확하다. +- [ ] 현재 5개 언어 구현을 당분간 완성형으로 유지할지 판단할 수 있는 근거가 정리되어 있다. +- [ ] 전체 검증 매트릭스와 proto 동기화 검사가 안정성 판단 기준으로 문서화되어 있다. +- [ ] 새 언어 확장, package 릴리즈, 프로토콜 변경을 언제 재개할지 기준이 명확하다. ## 범위 제외 @@ -43,4 +43,8 @@ ## 작업 컨텍스트 -가장 가까운 검증 근거는 `agent-ops/roadmap/milestones/continuous-verification.md`의 검증 기록과 `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh`다. 새 언어 포팅과 릴리즈 준비는 실제 필요가 생길 때 보류를 해제한다. +- 관련 경로: `README.md`, `PROTOCOL.md`, `VERSIONING.md`, `PORTING_GUIDE.md`, `agent-ops/roadmap/milestones/continuous-verification.md`, `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh` +- 선행 작업: 지속 검증 +- 후속 작업: C# Unity/.NET 포트, Swift Apple 플랫폼 포트, 릴리즈 준비 +- 검증 근거: 가장 가까운 검증 근거는 지속 검증 Milestone의 2026-05-21 전체 매트릭스 통과 기록이다. +- 확인 필요: 현재 5개 언어 구현을 완성형으로 유지할지, 새 언어 포팅과 릴리즈 준비 보류를 언제 해제할지 판단한다. diff --git a/agent-ops/roadmap/milestones/swift-port.md b/agent-ops/roadmap/milestones/swift-port.md index 6267e73..5d7113d 100644 --- a/agent-ops/roadmap/milestones/swift-port.md +++ b/agent-ops/roadmap/milestones/swift-port.md @@ -32,9 +32,9 @@ ## 완료 기준 -- Swift peer가 문서화된 프로토콜을 통해 최소 하나의 사용 가능 구현체와 상호 운용된다. -- Swift 구현체는 `PORTING_GUIDE.md`를 따르며 platform UI/threading concern을 프로토콜 core 밖에 둔다. -- 런타임 의존성 선택은 문서화되어 있고 protocol-relevant하다. +- [ ] Swift peer가 문서화된 프로토콜을 통해 최소 하나의 사용 가능 구현체와 상호 운용된다. +- [ ] Swift 구현체는 `PORTING_GUIDE.md`를 따르며 platform UI/threading concern을 프로토콜 core 밖에 둔다. +- [ ] 런타임 의존성 선택은 문서화되어 있고 protocol-relevant하다. ## 범위 제외 @@ -44,4 +44,8 @@ ## 작업 컨텍스트 -현재는 새 언어 확장 필요성이 낮아 보류한다. 실제 iOS/macOS 소비 수요가 생기면 `PORTING_GUIDE.md`의 Swift 섹션을 사용한다. 공유 상태와 cancellation 동작이 프로토콜 core에 맞는 곳에서는 actor isolation과 Swift concurrency를 우선한다. +- 관련 경로: `PORTING_GUIDE.md`, `PROTOCOL.md`, `VERSIONING.md` +- 선행 작업: 안정화 기준선 완료 또는 실제 iOS/macOS 소비 수요 확인 +- 후속 작업: 릴리즈 준비 +- 참고 구현: 공유 상태와 cancellation 동작이 프로토콜 core에 맞는 곳에서는 actor isolation과 Swift concurrency를 우선한다. +- 확인 필요: 지원할 Swift 및 Apple platform target diff --git a/agent-ops/rules/project/rules.md b/agent-ops/rules/project/rules.md index aa5a8a2..19d03ac 100644 --- a/agent-ops/rules/project/rules.md +++ b/agent-ops/rules/project/rules.md @@ -52,10 +52,12 @@ VERSIONING.md — 프로토콜/패키지 버전 정책 - 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-ops/roadmap/current.md`를 먼저 읽는다. - `current.md`는 현재 작업 위치가 아니라 활성 Milestone 후보 목록이다. +- `current.md`에는 개인별 현재 작업 위치나 완료 상태를 기록하지 않는다. - 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Milestone 문서를 같은 세션에서 1회 읽는다. - 요청이 활성 Milestone 둘 이상에 걸치면 필요한 Milestone 문서를 모두 읽고 작업 범위를 좁힌다. - `agent-ops/roadmap/ROADMAP.md`는 로드맵 생성/갱신, 단계 전환, Milestone 추가/수정 요청이 있을 때만 읽는다. - 활성 Milestone 밖의 작업이면 `agent-ops/roadmap/ROADMAP.md`의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다. +- 상세 작업과 완료 기준은 각 Milestone 문서의 체크리스트로 관리한다. - 작업 요청이 선택된 Milestone의 목표 또는 범위 제외 항목과 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다. ## 도메인 매핑