From e747784a9d59c2f28267c439b68721787e411639 Mon Sep 17 00:00:00 2001 From: toki Date: Thu, 21 May 2026 20:49:57 +0900 Subject: [PATCH] refactor: rename roadmap milestones and update project rules --- agent-ops/roadmap/ROADMAP.md | 51 +++++++++---------- agent-ops/roadmap/current.md | 14 +++-- ...parity.md => available-language-parity.md} | 22 ++++---- ...fication.md => continuous-verification.md} | 22 ++++---- .../{M04-csharp-port.md => csharp-port.md} | 22 ++++---- ...tocol-baseline.md => protocol-baseline.md} | 22 ++++---- ...ease-readiness.md => release-readiness.md} | 22 ++++---- .../{M05-swift-port.md => swift-port.md} | 22 ++++---- agent-ops/rules/project/rules.md | 12 +++-- 9 files changed, 109 insertions(+), 100 deletions(-) rename agent-ops/roadmap/milestones/{M02-available-language-parity.md => available-language-parity.md} (91%) rename agent-ops/roadmap/milestones/{M03-continuous-verification.md => continuous-verification.md} (92%) rename agent-ops/roadmap/milestones/{M04-csharp-port.md => csharp-port.md} (91%) rename agent-ops/roadmap/milestones/{M01-protocol-baseline.md => protocol-baseline.md} (90%) rename agent-ops/roadmap/milestones/{M06-release-readiness.md => release-readiness.md} (90%) rename agent-ops/roadmap/milestones/{M05-swift-port.md => swift-port.md} (90%) diff --git a/agent-ops/roadmap/ROADMAP.md b/agent-ops/roadmap/ROADMAP.md index 9576f3c..70f4aa4 100644 --- a/agent-ops/roadmap/ROADMAP.md +++ b/agent-ops/roadmap/ROADMAP.md @@ -6,49 +6,48 @@ Proto Socket은 여러 언어와 플랫폼에서 일관되게 동작하는 얇 코어는 작게 유지한다. 인증, 세션, 채팅, 게임 규칙, 룸 로직, 에이전트 워크플로 같은 애플리케이션 의미는 이 프로토콜 계층 위에서 다룬다. -## 현재 위치 +## 활성 창 -- Active Phase: Phase 2 - 검증과 호환성 -- Active Milestone: M03 지속 검증 -- Active Milestone File: agent-ops/roadmap/milestones/M03-continuous-verification.md +현재 일반 작업에서 우선 확인할 활성 Milestone 후보는 `agent-ops/roadmap/current.md`에 둔다. 이 문서는 전체 방향, 단계 흐름, Milestone 순서를 갱신할 때만 읽는다. ## 마이그레이션 메모 이 로드맵은 기존 상위 문서에 흩어져 있던 로드맵성 계획을 분리한 것이다. -- `README.md` 구현 상태 표: 사용 가능/계획 언어 작업으로 마일스톤 인덱스에 요약했다. -- `README.md` 로드맵 방향 문단: M02, M04, M05의 의존성 및 native platform 방향으로 옮겼다. -- `README.md` Jenkins 계획 메모: M03 지속 검증으로 옮겼다. -- `PORTING_GUIDE.md` C# 및 Swift 가이드: 계획된 포팅 마일스톤 M04, M05에 연결했다. +- `README.md` 구현 상태 표: 사용 가능/계획 언어 작업으로 Milestone 목록에 요약했다. +- `README.md` 로드맵 방향 문단: 사용 가능 언어 parity, C# Unity/.NET 포트, Swift Apple 플랫폼 포트의 의존성 및 native platform 방향으로 옮겼다. +- `README.md` Jenkins 계획 메모: 지속 검증으로 옮겼다. +- `PORTING_GUIDE.md` C# 및 Swift 가이드: 계획된 포팅 Milestone에 연결했다. +- 이전 로드맵의 순번 붙은 단계명, Milestone 이름, Milestone 파일명은 순번 없는 이름과 slug로 정리했다. -## Phase 개요 +## 단계 개요 -| Phase | Status | 목표 | +| 단계 | 상태 | 목표 | |-------|--------|------| -| Phase 1 - 프로토콜 기반 | Done | 프로토콜 버전 `0.1`, 와이어 포맷, 버전 정책, canonical proto 원본, 레퍼런스 구현 패턴을 정의한다. | -| Phase 2 - 검증과 호환성 | Active | 동일 언어 테스트, 크로스 언어 테스트, proto 동기화 검사, 지속 검증으로 사용 가능한 구현체들을 정렬한다. | -| Phase 3 - 남은 native platform 포팅 | Planned | 프로토콜 계약과 native-first 런타임 방향을 유지하면서 C# 및 Swift 구현을 추가한다. | -| Phase 4 - 릴리즈 준비 | Planned | 외부 사용을 위한 언어 패키지, 릴리즈 문서, 호환성 설명을 준비한다. | +| 프로토콜 기반 | 완료 | 프로토콜 버전 `0.1`, 와이어 포맷, 버전 정책, canonical proto 원본, 레퍼런스 구현 패턴을 정의한다. | +| 검증과 호환성 | 진행 중 | 동일 언어 테스트, 크로스 언어 테스트, proto 동기화 검사, 지속 검증으로 사용 가능한 구현체들을 정렬한다. | +| 남은 native platform 포팅 | 계획 | 프로토콜 계약과 native-first 런타임 방향을 유지하면서 C# 및 Swift 구현을 추가한다. | +| 릴리즈 준비 | 계획 | 외부 사용을 위한 언어 패키지, 릴리즈 문서, 호환성 설명을 준비한다. | -## 마일스톤 인덱스 +## Milestone 목록 -| Milestone | Phase | Status | File | 요약 | +| Milestone | 단계 | 상태 | 파일 | 요약 | |-----------|-------|--------|------|---------| -| M01 프로토콜 기준선 | Phase 1 | Done | agent-ops/roadmap/milestones/M01-protocol-baseline.md | 프로토콜 `0.1`, canonical proto, 프레이밍, 하트비트, nonce, 버전 정책을 문서화했다. | -| M02 사용 가능 언어 parity | Phase 2 | Done | agent-ops/roadmap/milestones/M02-available-language-parity.md | Dart, Go, Kotlin, Python, TypeScript가 사용 가능 상태이며 동일 언어 및 크로스 언어 테스트 진입점이 있다. | -| M03 지속 검증 | Phase 2 | Active | agent-ops/roadmap/milestones/M03-continuous-verification.md | 지원 언어 및 크로스 언어 테스트 매트릭스를 자동화한다. 현재 외부 실행 후보는 Jenkins다. | -| M04 C# Unity/.NET 포트 | Phase 3 | Planned | agent-ops/roadmap/milestones/M04-csharp-port.md | 가능한 곳에서는 native 런타임 패턴을 사용해 Unity와 .NET용 C# 구현을 추가한다. | -| M05 Swift Apple 플랫폼 포트 | Phase 3 | Planned | agent-ops/roadmap/milestones/M05-swift-port.md | 가능한 곳에서는 Swift concurrency와 Apple native transport API를 사용해 iOS/macOS용 Swift 구현을 추가한다. | -| M06 릴리즈 준비 | Phase 4 | Planned | agent-ops/roadmap/milestones/M06-release-readiness.md | 언어별 패키지 배포, 호환성 메모, 릴리즈 검증을 준비한다. | +| 프로토콜 기준선 | 프로토콜 기반 | 완료 | 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 | 지원 언어 및 크로스 언어 테스트 매트릭스를 자동화한다. 현재 외부 실행 후보는 Jenkins다. | +| C# Unity/.NET 포트 | 남은 native platform 포팅 | 계획 | agent-ops/roadmap/milestones/csharp-port.md | 가능한 곳에서는 native 런타임 패턴을 사용해 Unity와 .NET용 C# 구현을 추가한다. | +| Swift Apple 플랫폼 포트 | 남은 native platform 포팅 | 계획 | agent-ops/roadmap/milestones/swift-port.md | 가능한 곳에서는 Swift concurrency와 Apple native transport API를 사용해 iOS/macOS용 Swift 구현을 추가한다. | +| 릴리즈 준비 | 릴리즈 준비 | 계획 | agent-ops/roadmap/milestones/release-readiness.md | 언어별 패키지 배포, 호환성 메모, 릴리즈 검증을 준비한다. | ## 로딩 정책 -- 일반 구현 작업은 `agent-ops/roadmap/current.md`와 Active Milestone 파일만 읽는다. -- 전체 `ROADMAP.md`는 로드맵 생성/갱신, Phase 전환, Milestone 추가, Milestone 재구성 요청에서만 읽는다. -- 요청된 작업이 Active Milestone의 Goal 또는 Non-Goals와 충돌하면 구현 전에 멈추고 방향을 확인한다. +- 일반 구현 작업은 `agent-ops/roadmap/current.md`와 관련 활성 Milestone 파일만 읽는다. +- 전체 `ROADMAP.md`는 로드맵 생성/갱신, 단계 전환, Milestone 추가, Milestone 재구성 요청에서만 읽는다. +- 요청된 작업이 선택한 Milestone의 목표 또는 범위 제외 항목과 충돌하면 구현 전에 멈추고 방향을 확인한다. ## 확인 필요 -- Active Milestone은 전체 지원 언어 및 크로스 언어 검증에 Jenkins를 계획했던 기존 README 메모에서 추론했다. +- 활성 Milestone은 전체 지원 언어 및 크로스 언어 검증에 Jenkins를 계획했던 기존 README 메모에서 추론했다. - 제품 우선순위가 바뀌면 C#과 Swift의 순서는 달라질 수 있다. - 릴리즈 대상 registry와 패키지 배포 순서는 아직 확정되지 않았다. diff --git a/agent-ops/roadmap/current.md b/agent-ops/roadmap/current.md index 309e79c..b52985a 100644 --- a/agent-ops/roadmap/current.md +++ b/agent-ops/roadmap/current.md @@ -1,5 +1,11 @@ -# Current Roadmap Context +# 현재 로드맵 컨텍스트 -- Active Phase: Phase 2 - 검증과 호환성 -- Active Milestone: M03 지속 검증 -- Active Milestone File: agent-ops/roadmap/milestones/M03-continuous-verification.md +## 활성 Milestone + +- 지속 검증: agent-ops/roadmap/milestones/continuous-verification.md + +## 선택 규칙 + +- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 Milestone을 선택한다. +- 활성 Milestone 둘 이상에 걸치면 필요한 Milestone 문서를 모두 읽고 작업 범위를 좁힌다. +- 활성 Milestone 밖의 작업이면 `agent-ops/roadmap/ROADMAP.md`의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다. diff --git a/agent-ops/roadmap/milestones/M02-available-language-parity.md b/agent-ops/roadmap/milestones/available-language-parity.md similarity index 91% rename from agent-ops/roadmap/milestones/M02-available-language-parity.md rename to agent-ops/roadmap/milestones/available-language-parity.md index 602f027..97104a6 100644 --- a/agent-ops/roadmap/milestones/M02-available-language-parity.md +++ b/agent-ops/roadmap/milestones/available-language-parity.md @@ -1,25 +1,25 @@ -# M02 사용 가능 언어 parity +# 사용 가능 언어 parity -## Goal +## 목표 저장소에 포함된 사용 가능 구현체들을 동일 언어 테스트와 크로스 언어 테스트 진입점을 갖춘 공통 프로토콜 표면으로 맞춘다. -## Phase +## 단계 -Phase 2 - 검증과 호환성 +검증과 호환성 -## Status +## 상태 -Done +완료 -## Scope +## 범위 - `README.md`와 `PROTOCOL.md`에 표시된 사용 가능 구현체 목록을 유지한다. - Dart, Go, Kotlin, Python, TypeScript를 프로토콜 버전 `0.1`에 맞춘다. - protobuf 외 런타임 의존성은 native-first이며 좁은 범위로 유지한다. - 지원 언어 매트릭스를 위한 크로스 언어 테스트 runner를 유지한다. -## Required Features +## 필수 기능 - [x] Dart 구현체가 `dart/`에 있다. - [x] Go 구현체가 `go/`에 있다. @@ -29,18 +29,18 @@ Done - [x] 사용 가능 구현체 간 크로스 언어 테스트 진입점이 있다. - [x] 의존성 방향을 문서화한다. protobuf는 핵심 프로토콜 의존성이며, 다른 런타임 의존성은 native-first, protocol-relevant, minimal이어야 한다. -## Success Criteria +## 완료 기준 - 유지보수자는 상위 문서에서 사용 가능 구현체와 계획 구현체를 식별할 수 있다. - 새 언어 작업은 `PORTING_GUIDE.md`와 프로젝트 crosstest 템플릿에서 시작할 수 있다. - 사용 가능 구현체들은 문서화된 프로토콜 계약을 유지한다. -## Non-Goals +## 범위 제외 - 구현, 동일 언어 테스트, 크로스 언어 테스트가 통과하기 전에 C# 또는 Swift를 Available로 표시하지 않는다. - 좁은 프로토콜 요구를 처리하기 위해 넓은 framework나 runtime layer를 도입하지 않는다. - transport-level 계약을 넘어 프로토콜 의미를 확장하지 않는다. -## Context for Work +## 작업 컨텍스트 언어 구현을 추가하거나 변경할 때는 `PORTING_GUIDE.md`와 프로젝트 스킬 `agent-ops/skills/project/add-proto-socket-crosstest-language/SKILL.md`를 사용한다. 프로토콜 파일을 변경하기 전에는 protocol domain rule을 읽는다. diff --git a/agent-ops/roadmap/milestones/M03-continuous-verification.md b/agent-ops/roadmap/milestones/continuous-verification.md similarity index 92% rename from agent-ops/roadmap/milestones/M03-continuous-verification.md rename to agent-ops/roadmap/milestones/continuous-verification.md index d4ca06e..32ae249 100644 --- a/agent-ops/roadmap/milestones/M03-continuous-verification.md +++ b/agent-ops/roadmap/milestones/continuous-verification.md @@ -1,18 +1,18 @@ -# M03 지속 검증 +# 지속 검증 -## Goal +## 목표 외부 CI runner에서 동일 언어 테스트, 크로스 언어 테스트, proto 동기화 검사를 실행해 모든 사용 가능 구현체에 대한 신뢰도를 자동화한다. -## Phase +## 단계 -Phase 2 - 검증과 호환성 +검증과 호환성 -## Status +## 상태 -Active +진행 중 -## Scope +## 범위 - README의 테스트 명령 매트릭스를 반복 가능한 CI workflow로 만든다. - Dart, Go, Kotlin, Python, TypeScript 동일 언어 테스트를 포함한다. @@ -20,7 +20,7 @@ Active - proto 파일 변경 시 proto 동기화 검사를 포함한다. - 기존 로컬 명령 및 프로젝트 test-matrix 스킬과 workflow를 맞춘다. -## Required Features +## 필수 기능 - [ ] 외부 CI 진입점을 확정한다. 변경 전까지는 마이그레이션된 로드맵 맥락상 Jenkins를 현재 후보로 유지한다. - [ ] Dart unit test를 실행한다. @@ -32,18 +32,18 @@ Active - [ ] Proto binding에 영향이 있을 때 `tools/check_proto_sync.sh`를 실행한다. - [ ] 실패를 확인하고 매트릭스를 로컬에서 다시 실행하는 방법을 문서화한다. -## Success Criteria +## 완료 기준 - 단일 CI job 또는 pipeline이 전체 지원 언어 및 크로스 언어 매트릭스를 검증할 수 있다. - CI 실패가 실패한 언어 쌍 또는 동일 언어 package를 명확히 식별한다. - `README.md`의 로컬 명령이 자동화 workflow와 일치한다. -## Non-Goals +## 범위 제외 - 이 마일스톤에서 C# 또는 Swift 구현 작업을 추가하지 않는다. - CI 편의를 위해 프로토콜 동작이나 package API를 변경하지 않는다. - 모든 일반 개발 작업에서 전체 로드맵을 읽도록 요구하지 않는다. -## Context for Work +## 작업 컨텍스트 가장 가까운 기존 자동화 맥락으로 `agent-ops/skills/project/run-proto-socket-test-matrix/SKILL.md`와 `agent-ops/skills/project/run-proto-socket-test-matrix/scripts/run_matrix.sh`를 사용한다. 사용자가 다른 runner를 선택하기 전까지 Jenkins를 현재 문서화된 후보로 본다. diff --git a/agent-ops/roadmap/milestones/M04-csharp-port.md b/agent-ops/roadmap/milestones/csharp-port.md similarity index 91% rename from agent-ops/roadmap/milestones/M04-csharp-port.md rename to agent-ops/roadmap/milestones/csharp-port.md index cad5185..26bc888 100644 --- a/agent-ops/roadmap/milestones/M04-csharp-port.md +++ b/agent-ops/roadmap/milestones/csharp-port.md @@ -1,25 +1,25 @@ -# M04 C# Unity/.NET 포트 +# C# Unity/.NET 포트 -## Goal +## 목표 프로토콜 `0.1` 계약과 native-first 런타임 방향을 유지하면서 Unity 및 .NET 소비자를 지원하는 C# 구현을 추가한다. -## Phase +## 단계 -Phase 3 - 남은 native platform 포팅 +남은 native platform 포팅 -## Status +## 상태 -Planned +계획 -## Scope +## 범위 - 핵심 transport 추상화, communicator, nonce 처리, 요청-응답 상관관계, 하트비트, close-once 동작을 구현한다. - 대상 런타임에서 실용적인 범위로 TCP/TLS 및 WebSocket/WSS 지원을 구현한다. - 구현체를 Available로 표시하기 전에 동일 언어 테스트와 크로스 언어 테스트를 추가한다. - protobuf 외 런타임 의존성이 있다면 native API가 충분하지 않은 이유를 문서화한다. -## Required Features +## 필수 기능 - [ ] 지원할 .NET 및 Unity version target을 선택한다. - [ ] Canonical schema에서 C# protobuf binding을 생성하거나 유지한다. @@ -30,18 +30,18 @@ Planned - [ ] 크로스 언어 테스트 runner를 추가한다. - [ ] 테스트 통과 후에만 상위 구현 상태를 갱신한다. -## Success Criteria +## 완료 기준 - C# peer가 문서화된 프로토콜을 통해 최소 하나의 사용 가능 구현체와 상호 운용된다. - C# 구현체는 `PORTING_GUIDE.md`를 따르며 Unity main-thread concern을 프로토콜 core 밖에 둔다. - 런타임 의존성 선택은 문서화되어 있고 protocol-relevant하다. -## Non-Goals +## 범위 제외 - Unity 전용 gameplay, room, auth, session, chat 의미를 추가하지 않는다. - C# 전용 API에 맞추기 위해 프로토콜을 변경하지 않는다. - 동일 언어 및 크로스 언어 검사를 통과하지 않은 상태에서 C#을 Available로 표시하지 않는다. -## Context for Work +## 작업 컨텍스트 구현 전 `PORTING_GUIDE.md`의 C# 섹션을 사용한다. 동시성과 close-once 패턴은 Go를, public API 형태와 parser map 예시는 Dart를 참고한다. diff --git a/agent-ops/roadmap/milestones/M01-protocol-baseline.md b/agent-ops/roadmap/milestones/protocol-baseline.md similarity index 90% rename from agent-ops/roadmap/milestones/M01-protocol-baseline.md rename to agent-ops/roadmap/milestones/protocol-baseline.md index af21e10..ad9ee78 100644 --- a/agent-ops/roadmap/milestones/M01-protocol-baseline.md +++ b/agent-ops/roadmap/milestones/protocol-baseline.md @@ -1,18 +1,18 @@ -# M01 프로토콜 기준선 +# 프로토콜 기준선 -## Goal +## 목표 각 구현체가 애플리케이션별 동작을 코어에 넣지 않고도 상호 운용될 수 있도록 Proto Socket의 공유 프로토콜 계약을 확립한다. -## Phase +## 단계 -Phase 1 - 프로토콜 기반 +프로토콜 기반 -## Status +## 상태 -Done +완료 -## Scope +## 범위 - TCP 4바이트 빅엔디안 길이 프리픽스 프레이밍을 문서화한다. - WebSocket/WSS 바이너리 프레임 전송을 문서화한다. @@ -20,7 +20,7 @@ Done - 프로토콜 버전과 패키지 버전의 분리 정책을 정의한다. - `proto/message_common.proto`를 canonical proto 원본으로 둔다. -## Required Features +## 필수 기능 - [x] 프로토콜 버전 `0.1`을 `PROTOCOL.md`와 `VERSIONING.md`에 문서화한다. - [x] Canonical proto 원본이 `proto/message_common.proto`임을 문서화한다. @@ -28,18 +28,18 @@ Done - [x] 하트비트 생명주기와 요청-응답 상관관계를 문서화한다. - [x] breaking / non-breaking 프로토콜 변경 정책을 문서화한다. -## Success Criteria +## 완료 기준 - 구현자는 `PROTOCOL.md`, `VERSIONING.md`, `PORTING_GUIDE.md`를 기준으로 호환되는 언어 포트를 만들 수 있다. - 프로토콜 수준 변경에는 명시적인 호환성 검토 경로가 있다. - 생성된 언어별 proto 사본은 canonical schema와 대조할 수 있다. -## Non-Goals +## 범위 제외 - 애플리케이션 수준 인증, 세션, 채팅, 게임, 룸, 에이전트 워크플로 의미를 정의하지 않는다. - 언어 패키지를 배포하지 않는다. - TCP/TLS 및 WebSocket/WSS 외의 새 transport 계열을 추가하지 않는다. -## Context for Work +## 작업 컨텍스트 와이어 포맷의 기준 문서는 `PROTOCOL.md`, 호환성 정책의 기준 문서는 `VERSIONING.md`다. Proto schema가 바뀌면 binding을 재생성하고 `tools/check_proto_sync.sh`를 실행한다. diff --git a/agent-ops/roadmap/milestones/M06-release-readiness.md b/agent-ops/roadmap/milestones/release-readiness.md similarity index 90% rename from agent-ops/roadmap/milestones/M06-release-readiness.md rename to agent-ops/roadmap/milestones/release-readiness.md index 54ef2fb..b40aa0e 100644 --- a/agent-ops/roadmap/milestones/M06-release-readiness.md +++ b/agent-ops/roadmap/milestones/release-readiness.md @@ -1,25 +1,25 @@ -# M06 릴리즈 준비 +# 릴리즈 준비 -## Goal +## 목표 명확한 package version, 프로토콜 호환성 설명, 언어별 릴리즈 검사를 갖춰 프로젝트를 반복 가능한 외부 사용 상태로 준비한다. -## Phase +## 단계 -Phase 4 - 릴리즈 준비 +릴리즈 준비 -## Status +## 상태 -Planned +계획 -## Scope +## 범위 - 언어별 package publication target과 릴리즈 순서를 명확히 한다. - 배포된 각 package가 구현하는 프로토콜 version을 명시하게 한다. - Package version은 프로토콜 호환성 version과 독립적으로 유지한다. - 릴리즈 검사와 호환성 메모를 문서화한다. -## Required Features +## 필수 기능 - [ ] 사용 가능 언어별 package registry target을 확정한다. - [ ] 언어별 릴리즈 checklist를 정의한다. @@ -27,18 +27,18 @@ Planned - [ ] Changelog 또는 release notes를 `VERSIONING.md`와 맞춘다. - [ ] 릴리즈 전 동일 언어 및 크로스 언어 테스트를 검증한다. -## Success Criteria +## 완료 기준 - 유지보수자는 호환성 checklist를 추측하지 않고 언어 package를 릴리즈할 수 있다. - Package release는 package version 변경과 별도로 protocol version 지원을 전달한다. - 릴리즈 문서는 wire format 또는 required behavior가 바뀌지 않는 한 protocol bump를 암시하지 않는다. -## Non-Goals +## 범위 제외 - 프로토콜 호환성 정책을 변경하지 않는다. - 새 언어 구현을 추가하지 않는다. - 검증 마일스톤이 완료되지 않은 상태에서 package를 배포하지 않는다. -## Context for Work +## 작업 컨텍스트 릴리즈 호환성 기준 문서는 `VERSIONING.md`다. README는 package가 아직 배포되지 않았더라도 저장소에 포함된 구현체가 문서화된 프로토콜 계약을 유지해야 한다고 설명한다. diff --git a/agent-ops/roadmap/milestones/M05-swift-port.md b/agent-ops/roadmap/milestones/swift-port.md similarity index 90% rename from agent-ops/roadmap/milestones/M05-swift-port.md rename to agent-ops/roadmap/milestones/swift-port.md index 2d85cdd..518fdcc 100644 --- a/agent-ops/roadmap/milestones/M05-swift-port.md +++ b/agent-ops/roadmap/milestones/swift-port.md @@ -1,25 +1,25 @@ -# M05 Swift Apple 플랫폼 포트 +# Swift Apple 플랫폼 포트 -## Goal +## 목표 프로토콜 `0.1` 계약과 Apple-native 런타임 방향을 유지하면서 iOS 및 macOS용 Swift 구현을 추가한다. -## Phase +## 단계 -Phase 3 - 남은 native platform 포팅 +남은 native platform 포팅 -## Status +## 상태 -Planned +계획 -## Scope +## 범위 - 핵심 transport 추상화, communicator, nonce 처리, 요청-응답 상관관계, 하트비트, close-once 동작을 구현한다. - 실용적인 곳에서는 Swift concurrency, actor, `URLSessionWebSocketTask`, Apple platform API를 사용한다. - 구현체를 Available로 표시하기 전에 동일 언어 테스트와 크로스 언어 테스트를 추가한다. - protobuf 외 런타임 의존성이 있다면 native API가 충분하지 않은 이유를 문서화한다. -## Required Features +## 필수 기능 - [ ] 지원할 Swift 및 Apple platform target을 선택한다. - [ ] Canonical schema에서 Swift protobuf binding을 생성한다. @@ -30,18 +30,18 @@ Planned - [ ] 크로스 언어 테스트 runner를 추가한다. - [ ] 테스트 통과 후에만 상위 구현 상태를 갱신한다. -## Success Criteria +## 완료 기준 - Swift peer가 문서화된 프로토콜을 통해 최소 하나의 사용 가능 구현체와 상호 운용된다. - Swift 구현체는 `PORTING_GUIDE.md`를 따르며 platform UI/threading concern을 프로토콜 core 밖에 둔다. - 런타임 의존성 선택은 문서화되어 있고 protocol-relevant하다. -## Non-Goals +## 범위 제외 - 앱 전용 auth, session, chat, game, Apple UI abstraction을 추가하지 않는다. - Swift 전용 API에 맞추기 위해 프로토콜을 변경하지 않는다. - 동일 언어 및 크로스 언어 검사를 통과하지 않은 상태에서 Swift를 Available로 표시하지 않는다. -## Context for Work +## 작업 컨텍스트 구현 전 `PORTING_GUIDE.md`의 Swift 섹션을 사용한다. 공유 상태와 cancellation 동작이 프로토콜 core에 맞는 곳에서는 actor isolation과 Swift concurrency를 우선한다. diff --git a/agent-ops/rules/project/rules.md b/agent-ops/rules/project/rules.md index 944c75d..aa5a8a2 100644 --- a/agent-ops/rules/project/rules.md +++ b/agent-ops/rules/project/rules.md @@ -22,7 +22,7 @@ kotlin/ — Kotlin/Android 구현체 (src/, crosstest/) python/ — Python 구현체 (proto_socket/, test/, crosstest/) typescript/ — TypeScript 구현체 (src/, test/, crosstest/) tools/ — proto 생성/동기화 스크립트 -agent-ops/roadmap/ — Goal / Phase / Milestone 기반 로드맵과 현재 마일스톤 포인터 +agent-ops/roadmap/ — 전체 목표 / 단계 / Milestone 기반 로드맵과 현재 마일스톤 포인터 PROTOCOL.md — 와이어 포맷 명세 (정식 스펙) PORTING_GUIDE.md — 새 언어 구현 가이드 VERSIONING.md — 프로토콜/패키지 버전 정책 @@ -50,9 +50,13 @@ VERSIONING.md — 프로토콜/패키지 버전 정책 ## 마일스톤 컨텍스트 로딩 -- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-ops/roadmap/current.md`를 읽고, 그 안의 Active Milestone 문서를 같은 세션에서 1회 읽는다. -- `agent-ops/roadmap/ROADMAP.md`는 로드맵 생성/갱신, Phase 전환, Milestone 추가/수정 요청이 있을 때만 읽는다. -- 작업 요청이 Active Milestone의 Goal 또는 Non-Goals와 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다. +- 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-ops/roadmap/current.md`를 먼저 읽는다. +- `current.md`는 현재 작업 위치가 아니라 활성 Milestone 후보 목록이다. +- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Milestone 문서를 같은 세션에서 1회 읽는다. +- 요청이 활성 Milestone 둘 이상에 걸치면 필요한 Milestone 문서를 모두 읽고 작업 범위를 좁힌다. +- `agent-ops/roadmap/ROADMAP.md`는 로드맵 생성/갱신, 단계 전환, Milestone 추가/수정 요청이 있을 때만 읽는다. +- 활성 Milestone 밖의 작업이면 `agent-ops/roadmap/ROADMAP.md`의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다. +- 작업 요청이 선택된 Milestone의 목표 또는 범위 제외 항목과 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다. ## 도메인 매핑