diff --git a/agent-roadmap/ROADMAP.md b/agent-roadmap/ROADMAP.md index 8d1f315..668a921 100644 --- a/agent-roadmap/ROADMAP.md +++ b/agent-roadmap/ROADMAP.md @@ -4,7 +4,7 @@ NomadCode는 Flutter 기반 앱, core 서비스, 공유 계약, agent-operation 규칙을 하나의 원레포로 묶어 AI-assisted development workflow를 조율하는 프로젝트다. -현재 로드맵은 `ROADMAP.md -> phase//PHASE.md -> phase//milestones/.md` scaffold를 기준으로 관리한다. React/Vite 웹 콘솔 제거, 서버/Plane/provider 기반 작업, Flutter-first 클라이언트 정리, Mattermost push plugin extraction, client integration 표준화, workspace 포트/환경 표준화, External Integration, Milestone Work Item Creation Sync, Plane Work Item Webhook Intake, Gito Branch Event Creation Sync Bridge, Gito proto-socket consumer wire readiness, Gito HTTP Webhook Consumer Readiness, Plane-Origin Authoring Roundtrip Sync는 완료되었다. Agent-Ops MCP Control Plane에서는 다음 활성 마일스톤인 Roadmap Driven Agent-Ops Automation으로 roadmap/action core와 provider sync domain의 상위 방향을 정리한다. 외부 agent 제어 표면은 현재 확정 범위가 아니라 후속 스케치에서 검토한다. +현재 로드맵은 `ROADMAP.md -> phase//PHASE.md -> phase//milestones/.md` scaffold를 기준으로 관리한다. React/Vite 웹 콘솔 제거, 서버/Plane/provider 기반 작업, Flutter-first 클라이언트 정리, Mattermost push plugin extraction, client integration 표준화, workspace 포트/환경 표준화, External Integration, Milestone Work Item Creation Sync, Plane Work Item Webhook Intake, Gito Branch Event Creation Sync Bridge, Gito proto-socket consumer wire readiness, Gito HTTP Webhook Consumer Readiness, Plane-Origin Authoring Roundtrip Sync, Roadmap Driven Agent-Ops Automation은 완료되었다. Agent-Ops MCP Control Plane에서는 다음 후보인 Milestone Execution Lifecycle Sync로 Todo 이후 실행 lifecycle을 다룬다. 외부 agent 제어 표면은 현재 확정 범위가 아니라 후속 스케치에서 검토한다. IOP 외부 실행 호출은 OpenAI-compatible Responses API 방식을 기본 계약으로 채택하고, NomadCode/IOP 고유의 task, workspace, session, approval, artifact, notification 문맥은 별도 `iop` wrapper field가 아니라 `metadata` 확장으로 전달한다. A2A는 agent-to-agent delegation이 명확히 필요할 때 재검토하며, IOP native protocol은 NomadCode의 기본 외부 실행 호출 표면으로 쓰지 않는다. @@ -37,7 +37,7 @@ IOP 외부 실행 호출은 OpenAI-compatible Responses API 방식을 기본 계 - 요약: Plane 확장, Jira-compatible provider 추상화, Mattermost, Agent Integrator, IOP OpenAI-compatible Responses 호출 경계를 실제 통합 adapter 흐름으로 확장했고, metadata 실행 문맥 전달, IOP Edge `/v1/responses`, NomadCode Core 원격 create/enqueue/poll smoke를 완료했다. - [진행중] Agent-Ops MCP Control Plane - 경로: `agent-roadmap/phase/agent-ops-mcp-control-plane/PHASE.md` - - 요약: 로드맵 기반 agent-ops 운영 자동화와 Plane/Jira 같은 work item provider와 Milestone item의 양방향 동기화 도메인을 다룬다. Plane-Origin Authoring Roundtrip Sync는 완료/archive했고, 현재 Roadmap Driven Agent-Ops Automation이 다음 활성 마일스톤이다. 외부 agent 제어 표면은 후속 스케치 항목으로 보류한다. + - 요약: 로드맵 기반 agent-ops 운영 자동화와 Plane/Jira 같은 work item provider와 Milestone item의 양방향 동기화 도메인을 다룬다. Roadmap Driven Agent-Ops Automation까지 완료/archive했고, 다음 후보는 Milestone Execution Lifecycle Sync다. 외부 agent 제어 표면은 후속 스케치 항목으로 보류한다. - [계획] Project Workspace Management UX - 경로: `agent-roadmap/phase/project-workspace-management-ux/PHASE.md` - 요약: client integration 표준화, core workflow, 외부 통합 기준 이후 프로젝트 단위 앱 UX를 다루며, provider slot 기반 외부 console composition은 계획 후보로 둔다. diff --git a/agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/roadmap-driven-agent-ops-automation.md b/agent-roadmap/archive/phase/agent-ops-mcp-control-plane/milestones/roadmap-driven-agent-ops-automation.md similarity index 83% rename from agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/roadmap-driven-agent-ops-automation.md rename to agent-roadmap/archive/phase/agent-ops-mcp-control-plane/milestones/roadmap-driven-agent-ops-automation.md index 1415480..c69a469 100644 --- a/agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/roadmap-driven-agent-ops-automation.md +++ b/agent-roadmap/archive/phase/agent-ops-mcp-control-plane/milestones/roadmap-driven-agent-ops-automation.md @@ -11,7 +11,7 @@ NomadCode가 로드맵을 중심으로 사용자 입력, 실행 상태, 출력 ## 상태 -[진행중] +[완료] ## 승격 조건 @@ -43,44 +43,44 @@ NomadCode가 로드맵을 중심으로 사용자 입력, 실행 상태, 출력 NomadCode 내부 core logic이 roadmap 기반 작업 운영을 소유하고, provider/UI/agent 입력을 검증 가능한 Core action으로 수렴시키는 구조를 정리한다. -- [ ] [core-state] roadmap, Phase, Milestone, plan, code-review, completion event, approval 상태를 Core가 다루는 state model과 revision/idempotency 계약으로 정리한다. -- [ ] [core-actions] validate, position, propose/apply change, transition, archive, dependency check, completion event ingest를 Core action 후보로 정의한다. -- [ ] [http-role] HTTP API는 Flutter UI, webhook, internal integration용 표면으로 유지하고, 실행 side effect는 Core action의 revision/idempotency 계약을 거치도록 하는 기준을 정한다. -- [ ] [review-gates] 사용자 입력, 출력 검토, `USER_REVIEW.md`, 완료 승인, archive 승인을 NomadCode workflow 안의 review gate로 처리하는 흐름을 정한다. +- [x] [core-state] roadmap, Phase, Milestone, plan, code-review, completion event, approval 상태를 Core가 다루는 state model과 revision/idempotency 계약으로 정리한다. +- [x] [core-actions] validate, position, propose/apply change, transition, archive, dependency check, completion event ingest를 Core action 후보로 정의한다. +- [x] [http-role] HTTP API는 Flutter UI, webhook, internal integration용 표면으로 유지하고, 실행 side effect는 Core action의 revision/idempotency 계약을 거치도록 하는 기준을 정한다. +- [x] [review-gates] 사용자 입력, 출력 검토, `USER_REVIEW.md`, 완료 승인, archive 승인을 NomadCode workflow 안의 review gate로 처리하는 흐름을 정한다. - [x] [plane-control-flow] Plane을 primary control UI로 쓰는 lifecycle을 정리한다. 검증: `Backlog + AGENT assignee -> Todo -> In Progress -> User Review -> Done/Cancelled` 상태가 Milestone 초안, 사용자 검토, 실행 시작, 사용자 검토, 완료/archive 또는 폐기로 어떻게 연결되는지 문서에서 일관되게 읽힌다. - [x] [plane-identity] Plane 상위 티켓을 Milestone, 하위 티켓을 Milestone 기능 Task로 매핑하는 id 계약을 정한다. 검증: Milestone id는 파일명으로 유지하고, Plane work item id는 외부 provider id로 보존하는 기준이 명확하다. - [x] [todo-draft-gate] `Backlog + AGENT assignee`를 Milestone 초안 생성/갱신 trigger로 정의하고, `develop` branch의 agent-roadmap에 반영된 뒤 Plane 티켓을 `Todo`로 이동하는 gate를 정한다. 검증: Todo 진입은 자동 실행이 아니라 `develop`에 존재하는 Milestone의 사용자 검토 단계임이 명확하다. -- [ ] [in-progress-exec-gate] 사용자가 Plane 상위 티켓을 `In Progress`로 옮길 때 실제 실행과 하위 티켓 전환을 시작하는 기준을 정한다. 검증: Milestone Task가 Plane 하위 티켓으로 생성되고 plan/code-review 루프로 들어가는 시점이 명확하다. -- [ ] [cancelled-discard] 사용자가 Plane 상위 티켓을 `Cancelled`로 옮길 때 Milestone 초안 폐기 또는 보류를 처리하는 기준을 정한다. 검증: Plane 폐기 상태가 agent-roadmap의 `[폐기]` 또는 `[보류]` 중 어느 상태로 연결되는지와 사용자 승인 없는 archive 이동 금지가 설명된다. -- [ ] [child-task-review-policy] Milestone에서 만들어진 하위 작업은 막혔을 때만 `User Review`로 보내고, 정상 PASS 시 기본적으로 `Done`으로 보내는 정책을 정한다. 검증: 하위 작업의 기본 완료 흐름과 blocker review 흐름이 구분된다. -- [ ] [milestone-review-loop] 모든 하위 작업이 완료되면 상위 Milestone 티켓을 `User Review`로 보내고, 사용자가 `Done`으로 옮기면 완료/archive, `Todo`로 되돌리면 보완 루프로 처리하는 기준을 정한다. -- [ ] [first-slice] 첫 구현 단위를 `roadmap.validate`, `roadmap.get_position`, `roadmap.ingest_completion_event` 중 어떤 순서로 자를지 정한다. +- [x] [in-progress-exec-gate] 사용자가 Plane 상위 티켓을 `In Progress`로 옮길 때 실제 실행과 하위 티켓 전환을 시작하는 기준을 정한다. 검증: Milestone Task가 Plane 하위 티켓으로 생성되고 plan/code-review 루프로 들어가는 시점이 명확하다. +- [x] [cancelled-discard] 사용자가 Plane 상위 티켓을 `Cancelled`로 옮길 때 Milestone 초안 폐기 또는 보류를 처리하는 기준을 정한다. 검증: Plane 폐기 상태가 agent-roadmap의 `[폐기]` 또는 `[보류]` 중 어느 상태로 연결되는지와 사용자 승인 없는 archive 이동 금지가 설명된다. +- [x] [child-task-review-policy] Milestone에서 만들어진 하위 작업은 막혔을 때만 `User Review`로 보내고, 정상 PASS 시 기본적으로 `Done`으로 보내는 정책을 정한다. 검증: 하위 작업의 기본 완료 흐름과 blocker review 흐름이 구분된다. +- [x] [milestone-review-loop] 모든 하위 작업이 완료되면 상위 Milestone 티켓을 `User Review`로 보내고, 사용자가 `Done`으로 옮기면 완료/archive, `Todo`로 되돌리면 보완 루프로 처리하는 기준을 정한다. +- [x] [first-slice] 첫 구현 단위를 `roadmap.validate`, `roadmap.get_position`, `roadmap.ingest_completion_event` 중 어떤 순서로 자를지 정한다. ### Epic: [sync-domain] Milestone/work item sync domain Plane/Jira 같은 provider work item과 agent-roadmap Milestone item을 동일한 작업 구조로 유지하는 별도 Core sync domain을 정의한다. - [x] [sync-owner] sync domain의 소유 책임을 정의한다. 검증: provider adapter는 native API read/write만 담당하고, Milestone/work item identity mapping, revision 비교, 수렴 적용은 Core sync domain 책임으로 읽힌다. -- [ ] [sync-identity] Milestone, Epic/Task item id, provider work item id, parent-child 관계, provider revision, roadmap revision을 묶는 identity 계약을 정한다. 검증: Plane/Jira 어느 쪽에서 시작해도 같은 Milestone item 구조로 매핑되는 기준이 명확하다. +- [x] [sync-identity] Milestone, Epic/Task item id, provider work item id, parent-child 관계, provider revision, roadmap revision을 묶는 identity 계약을 정한다. 검증: Plane/Jira 어느 쪽에서 시작해도 같은 Milestone item 구조로 매핑되는 기준이 명확하다. - [x] [sync-project-config] provider project 단위 sync 설정 모델과 저장 경계를 정한다. 검증: provider project target, git remote URL, source-of-truth branch, workspace id/path가 Core DB에 저장되는 project sync 설정으로 정의되고, 설정 누락 또는 중복 시 생성 동기화를 진행하지 않는 기준이 있다. -- [ ] [sync-detection] provider webhook, provider polling, roadmap file/index scan, agent-task completion event를 같은 변경 감지 입력으로 정리한다. 검증: 양쪽 중 어느 쪽에서 변경이 발생해도 sync event로 정규화되는 흐름이 문서화되어 있다. -- [ ] [sync-convergence] 한쪽 변경을 다른 쪽에 반영해 Milestone item과 work item이 동일 형태로 수렴하는 apply 정책을 정한다. 검증: 생성, 제목/설명, 상태, parent-child, 완료/검토 흐름이 양방향으로 어떻게 반영되는지 설명된다. -- [ ] [sync-conflict] 동시 수정, revision mismatch, 삭제/archive, 사용자 승인 필요 변경의 conflict 처리 정책을 정한다. 검증: Core가 조용히 덮어쓰지 않고 review gate 또는 dry-run proposal로 멈추는 기준이 있다. -- [ ] [sync-schedule] sync domain의 scheduler 책임을 정한다. 검증: webhook이 없는 provider나 누락 이벤트를 주기 polling으로 보정하고, 같은 idempotency/revision 계약을 쓰는 방향이 명확하다. -- [ ] [sync-contract] `packages/contracts`에 sync event/action 후보를 남긴다. 검증: `roadmap_sync.inspect`, `roadmap_sync.apply`, `roadmap_sync.changed` 같은 후보 표면과 필수 입력 필드가 compatibility note에 정리되어 있다. +- [x] [sync-detection] provider webhook, provider polling, roadmap file/index scan, agent-task completion event를 같은 변경 감지 입력으로 정리한다. 검증: 양쪽 중 어느 쪽에서 변경이 발생해도 sync event로 정규화되는 흐름이 문서화되어 있다. +- [x] [sync-convergence] 한쪽 변경을 다른 쪽에 반영해 Milestone item과 work item이 동일 형태로 수렴하는 apply 정책을 정한다. 검증: 생성, 제목/설명, 상태, parent-child, 완료/검토 흐름이 양방향으로 어떻게 반영되는지 설명된다. +- [x] [sync-conflict] 동시 수정, revision mismatch, 삭제/archive, 사용자 승인 필요 변경의 conflict 처리 정책을 정한다. 검증: Core가 조용히 덮어쓰지 않고 review gate 또는 dry-run proposal로 멈추는 기준이 있다. +- [x] [sync-schedule] sync domain의 scheduler 책임을 정한다. 검증: webhook이 없는 provider나 누락 이벤트를 주기 polling으로 보정하고, 같은 idempotency/revision 계약을 쓰는 방향이 명확하다. +- [x] [sync-contract] `packages/contracts`에 sync event/action 후보를 남긴다. 검증: `roadmap_sync.inspect`, `roadmap_sync.apply`, `roadmap_sync.changed` 같은 후보 표면과 필수 입력 필드가 compatibility note에 정리되어 있다. - [x] [plane-origin-flow] Plane-origin Milestone 생성 시나리오를 정한다. 검증: Backlog 티켓 본문을 입력으로 IOP CLI 1차 통로를 통해 실행된 workspace agent가 같은 Milestone 파일 작성/push 경로에서 roadmap skill로 Milestone 초안을 만들고, `develop` 반영 후 sync layer가 pushed Milestone의 provider/work item identity를 검증한 뒤 원본 본문은 `사용자 요청:` 댓글로 보존하며, Plane 본문은 `develop`의 Milestone 내용으로 치환하고, 제목은 `[milestone-id] 제목` 형식으로 바꾼 뒤 Todo로 이동하는 순서가 문서화되어 있다. -- [ ] [agent-origin-flow] Agent-origin Milestone 생성 시나리오를 정한다. 검증: 에이전트 대화로 생성된 Milestone이 `develop` branch에 반영되었을 때 Plane parent ticket을 Todo 상태로 생성하고 identity map을 연결하는 흐름이 문서화되어 있다. -- [ ] [sync-idempotency] Plane-origin과 Agent-origin 생성의 중복 방지와 부분 실패 복구 정책을 정한다. 검증: 같은 Plane 티켓 또는 같은 Milestone path가 재처리되어도 중복 Milestone/티켓을 만들지 않고, 댓글 보존/본문 치환/제목 변경/상태 이동 중 실패한 단계를 재시도할 수 있다. +- [x] [agent-origin-flow] Agent-origin Milestone 생성 시나리오를 정한다. 검증: 에이전트 대화로 생성된 Milestone이 `develop` branch에 반영되었을 때 Plane parent ticket을 Todo 상태로 생성하고 identity map을 연결하는 흐름이 문서화되어 있다. +- [x] [sync-idempotency] Plane-origin과 Agent-origin 생성의 중복 방지와 부분 실패 복구 정책을 정한다. 검증: 같은 Plane 티켓 또는 같은 Milestone path가 재처리되어도 중복 Milestone/티켓을 만들지 않고, 댓글 보존/본문 치환/제목 변경/상태 이동 중 실패한 단계를 재시도할 수 있다. ## 완료 리뷰 -- 상태: 없음 -- 요청일: 없음 -- 완료 근거: 없음 +- 상태: 통과 +- 요청일: 2026-06-23 +- 완료 근거: Roadmap Operations Control Plane과 Milestone/work item sync domain의 상위 계약 후보가 `packages/contracts/notes/flutter-core-api-candidates.md`에 compatibility note로 정리되었고, 관련 core sync 경계 테스트가 통과했다. 이 문서의 기능 Task가 모두 충족되었고, 구현 잠금은 해제 상태이며 SDD는 불필요로 판정되어 있다. - 리뷰 필요: - - [ ] 사용자가 완료 결과를 확인했다 - - [ ] archive 이동을 승인했다 -- 리뷰 코멘트: 없음 + - [x] 사용자가 완료 결과를 확인했다 + - [x] archive 이동을 승인했다 +- 리뷰 코멘트: 2026-06-23 코드 레벨 종료 검토에서 stale README 표현을 보정했고, 관련 core packages 테스트와 문서 diff 검증이 통과해 archive했다. ## 범위 제외 @@ -100,11 +100,15 @@ Plane/Jira 같은 provider work item과 agent-roadmap Milestone item을 동일 - 로컬 제어 표면 후보: `http://127.0.0.1:8080/v1` - 선행 작업: Workflow Core, External Integration, Project Workspace Management UX, 로드맵 스킬 운영 복잡도 평가 - 후속 작업: `Milestone Execution Lifecycle Sync`, 외부 agent 제어 표면 스케치 -- 현재 지점: 이 Phase의 `Milestone Work Item Creation Sync`, `Plane Work Item Webhook Intake`, Gito branch/webhook wakeup 연동은 완료되어 archive에 남아 있다. 이 마일스톤은 roadmap/action core 책임과 Milestone/work item sync domain을 구현 가능한 Core action 후보로 정리하는 상위 설계/계약 문서다. +- 현재 지점: 이 Phase의 `Milestone Work Item Creation Sync`, `Plane Work Item Webhook Intake`, Gito branch/webhook wakeup 연동은 완료되어 archive에 남아 있다. 이 마일스톤은 roadmap/action core 책임과 Milestone/work item sync domain을 구현 가능한 Core action 후보로 정리하는 상위 설계/계약 문서이며, Milestone/work item sync domain의 후보 계약은 `packages/contracts/notes/flutter-core-api-candidates.md`까지 반영되어 있다. - 완료 체크 근거: - `[plane-control-flow]`, `[plane-identity]`, `[todo-draft-gate]`, `[plane-origin-flow]`: Phase 흐름에 완료로 남은 `Milestone Work Item Creation Sync`와 `Plane Work Item Webhook Intake`가 Plane-origin Milestone 작성, Todo projection, provider identity 보존, Backlog+AGENT webhook intake까지 닫은 근거다. + - `[in-progress-exec-gate]`, `[cancelled-discard]`, `[child-task-review-policy]`, `[milestone-review-loop]`: 이 문서의 Plane 제어 플로우가 `Todo -> In Progress -> User Review -> Done/Cancelled` 이후 실행 시작, 하위 티켓 기본 완료/차단 리뷰, 상위 Milestone 완료/보완/폐기 루프를 설명한다. - `[sync-owner]`: 현재 문서의 동기화 도메인 방향이 provider adapter와 Core sync domain 책임을 분리하고, 완료된 Plane/Gito sync slice가 이 경계를 따라 구현되어 있다. - `[sync-project-config]`: project sync 설정 기준이 현재 문서에 남아 있고, Core 내부 경로 `services/core/internal/projectsync/`, `services/core/internal/roadmapsync/`, `services/core/internal/roadmapsyncpipeline/`가 provider project target, repository, workspace 기반 동기화 경계를 구현한다. + - `[core-state]`, `[core-actions]`, `[http-role]`, `[review-gates]`, `[first-slice]`: `packages/contracts/notes/flutter-core-api-candidates.md`의 `Roadmap Operations Control Plane 계약 후보`가 roadmap state model, `roadmap.validate/get_position/propose_change/apply_change/transition/archive/dependency_check/ingest_completion_event`, HTTP wrapper 원칙, review gate, 첫 구현 순서를 compatibility note로 정리한다. + - `[sync-identity]`, `[sync-detection]`, `[sync-convergence]`, `[sync-conflict]`, `[sync-schedule]`, `[sync-contract]`: `packages/contracts/notes/flutter-core-api-candidates.md`의 `Roadmap / Work Item Sync 계약 후보`가 identity field, `roadmap_sync.changed`, `roadmap_sync.inspect/apply/reconcile`, convergence, conflict, polling 보정 기준을 compatibility note로 정리한다. + - `[agent-origin-flow]`, `[sync-idempotency]`: 이 문서의 Agent-origin 생성 플로우와 시나리오 점검, contracts note의 idempotency/revision 원칙이 develop 반영 후 Plane Todo 생성, identity map 연결, 중복 적용 방지, 단계별 재시도 경계를 설명한다. - 실행 경계: 이 마일스톤은 상위 방향과 계약 정리용이다. 실제 구현은 `Milestone Work Item Creation Sync`부터 진행하고, `Milestone Execution Lifecycle Sync`는 사용자가 해제할 때까지 잠근다. - 동기화 도메인 방향: - Sync domain은 provider adapter보다 위에 위치하며, provider native DTO를 직접 소유하지 않는다. @@ -126,7 +130,7 @@ Plane/Jira 같은 provider work item과 agent-roadmap Milestone item을 동일 - 하위 티켓: Milestone에서 만들어진 작업은 정상 PASS 시 기본적으로 `Done`으로 이동한다. 작업 중 사용자 결정, 외부 환경, 범위 충돌처럼 자동 진행이 막힐 때만 `User Review`로 이동한다. - `User Review`: 상위 Milestone 티켓은 모든 하위 작업이 완료되었거나 사용자 판단이 필요한 경우 이동한다. 사용자가 `Done`으로 옮기면 `[완료]`와 archive를 수행하고, `Todo`로 되돌리면 내부 Milestone을 `[진행중]`/보완 필요로 되돌려 추가 요구사항을 반영하는 루프로 처리한다. - `Done`: 사용자 최종 완료 승인이다. - - `Cancelled`: 폐기 또는 중단 루트다. + - `Cancelled`: 기본적으로 폐기 후보 루트이며, 일시 중단으로 해석해야 하는 경우에는 `[보류]` 후보로 사용자 review gate에 올린다. archive 이동은 사용자의 명시 승인 전에는 수행하지 않는다. - Agent-origin 생성 플로우: - 에이전트와의 대화 중 사용자가 Milestone 생성을 요청하면 현재 roadmap 규칙에 따라 프로젝트 안에 Milestone 문서를 만든다. - 생성된 Milestone이 `develop` branch에 반영되면 sync domain은 해당 Milestone을 Plane 상위 티켓으로 생성하고 `Todo` 상태에 둔다. @@ -141,4 +145,5 @@ Plane/Jira 같은 provider work item과 agent-roadmap Milestone item을 동일 - Agent-origin sync는 feature branch 초안이 아니라 `develop` branch에 반영된 Milestone만 Plane에 Todo 티켓으로 만든다. - Plane-origin과 Agent-origin 모두 project sync 설정을 통해 provider project, git repository, workspace를 확정하며, 설정이 없거나 둘 이상이면 생성 동기화를 멈추고 사용자 설정 또는 운영자 조치를 요구한다. - Cancelled는 사용자 폐기 신호지만 archive 이동은 사용자 승인 경계를 지켜야 하므로, 우선 `[폐기]` 후보 또는 review gate로 처리한다. +- 남은 작업: 없음. - 확인 필요: 없음 diff --git a/agent-roadmap/phase/agent-ops-mcp-control-plane/PHASE.md b/agent-roadmap/phase/agent-ops-mcp-control-plane/PHASE.md index be0e7e1..1c12e40 100644 --- a/agent-roadmap/phase/agent-ops-mcp-control-plane/PHASE.md +++ b/agent-roadmap/phase/agent-ops-mcp-control-plane/PHASE.md @@ -6,7 +6,7 @@ ## 목표 -로드맵 기반 agent-ops 운영 루프와 Plane/Jira 같은 work item provider와 Milestone item의 양방향 동기화 도메인을 Core action 경계로 정리한다. 외부 agent 제어 표면은 현재 확정하지 않고 후속 스케치로 분리한다. 현재는 Plane-Origin Authoring Roundtrip Sync까지 완료/archive했고, Roadmap Driven Agent-Ops Automation을 상위 설계 Milestone으로 유지한다. +로드맵 기반 agent-ops 운영 루프와 Plane/Jira 같은 work item provider와 Milestone item의 양방향 동기화 도메인을 Core action 경계로 정리한다. 외부 agent 제어 표면은 현재 확정하지 않고 후속 스케치로 분리한다. 현재는 Roadmap Driven Agent-Ops Automation까지 완료/archive했고, 다음 후보는 Milestone Execution Lifecycle Sync다. ## Milestone 흐름 @@ -42,9 +42,9 @@ - 경로: `agent-roadmap/archive/phase/agent-ops-mcp-control-plane/milestones/plane-origin-authoring-roundtrip-sync.md` - 요약: 최신 dev IOP Responses, workspace slot, Gito HTTP webhook, filename slug canonical id, active Milestone reconcile, Plane 생성/갱신 기준의 기능 Task와 live 검증을 완료했고 코드 레벨 종료 감사 후 archive했다. -- [진행중] Roadmap Driven Agent-Ops Automation - - 경로: `agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/roadmap-driven-agent-ops-automation.md` - - 요약: roadmap/action core와 Plane/Jira 기반 Milestone item 동기화의 상위 방향과 계약을 정리하는 다음 활성 마일스톤이다. +- [완료] Roadmap Driven Agent-Ops Automation + - 경로: `agent-roadmap/archive/phase/agent-ops-mcp-control-plane/milestones/roadmap-driven-agent-ops-automation.md` + - 요약: roadmap/action core와 Plane/Jira 기반 Milestone item 동기화의 상위 방향과 계약 후보를 정리했고, 코드 레벨 종료 검토 후 archive했다. - [계획] Milestone Execution Lifecycle Sync - 경로: `agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/milestone-execution-lifecycle-sync.md` diff --git a/agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/mcp-control-surface-sketch.md b/agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/mcp-control-surface-sketch.md index 16bf985..4729411 100644 --- a/agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/mcp-control-surface-sketch.md +++ b/agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/mcp-control-surface-sketch.md @@ -66,7 +66,7 @@ ## 작업 컨텍스트 -- 이 항목은 현재 Roadmap Driven Agent-Ops Automation에서 제외한 MCP 관련 내용을 나중에 검토하기 위한 스케치다. +- 이 항목은 완료된 Roadmap Driven Agent-Ops Automation에서 제외한 MCP 관련 내용을 나중에 검토하기 위한 스케치다. - 선행 후보: Roadmap Driven Agent-Ops Automation, Milestone Execution Lifecycle Sync - 관련 경로 후보: `services/core/internal/http/`, `packages/contracts/`, `agent-roadmap/` - 확인 필요: 외부 agent 제어 표면이 실제로 필요한지, 필요하다면 MCP가 NomadCode의 기본 표면이어야 하는지 diff --git a/agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/milestone-execution-lifecycle-sync.md b/agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/milestone-execution-lifecycle-sync.md index 3f58758..366efb9 100644 --- a/agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/milestone-execution-lifecycle-sync.md +++ b/agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/milestone-execution-lifecycle-sync.md @@ -17,7 +17,7 @@ Plane `Todo` 검토 이후 사용자가 `In Progress`로 옮긴 상위 티켓을 - 상태: 잠금 - 결정 필요: - - [ ] 사용자가 `Milestone Work Item Creation Sync` 확인 후 이 마일스톤의 잠금 해제를 명시한다. + - [ ] 사용자가 `Roadmap Driven Agent-Ops Automation` 종료 확인 후 이 마일스톤의 잠금 해제를 명시한다. ## 범위 @@ -61,7 +61,7 @@ Todo 이후 실행 lifecycle을 Plane 하위 티켓, Milestone Task, agent-task ## 작업 컨텍스트 - 관련 경로: `services/core/internal/workitem/`, `services/core/internal/scheduler/`, `services/core/internal/workflow/`, `agent-task/`, `packages/contracts/`, `agent-roadmap/` -- 선행 작업: `Milestone Work Item Creation Sync` +- 선행 작업: `Roadmap Driven Agent-Ops Automation` - 잠금 해제 조건: 사용자가 명시적으로 이 마일스톤의 잠금 해제를 요청한다. - 현재 지점: 사용자 확인과 명시적 잠금 해제 전까지 실행하지 않는 후속 마일스톤이다. - 확인 필요: diff --git a/packages/contracts/notes/flutter-core-api-candidates.md b/packages/contracts/notes/flutter-core-api-candidates.md index 99c5447..97c175d 100644 --- a/packages/contracts/notes/flutter-core-api-candidates.md +++ b/packages/contracts/notes/flutter-core-api-candidates.md @@ -442,12 +442,81 @@ --- -## 6. Workspace / Project Metadata 계약 후보 +## 6. Roadmap Operations Control Plane 계약 후보 + +> [!IMPORTANT] +> 이 절은 Roadmap Operations Control Plane의 후보 계약입니다. 실제 source schema가 아니며, Core가 roadmap/action side effect를 소유하도록 만들 때의 compatibility note로만 사용합니다. + +### 6.1 Roadmap State Model 후보 +- **설명**: Core는 `agent-roadmap` 파일을 직접 덮어쓰는 도구가 아니라, roadmap state를 읽고 revision/idempotency 조건을 확인한 뒤 action 결과를 제안하거나 적용하는 소유자다. +- **상태 단위**: + - `roadmap`: 전체 Phase 흐름, source branch, current revision. + - `phase`: Phase 상태, Phase 문서 경로, Milestone 흐름, archive link. + - `milestone`: Milestone 상태, 구현 잠금, SDD gate, 기능 Task 상태, 완료 리뷰. + - `task_artifact`: `agent-task/m-`의 plan, code-review, `USER_REVIEW.md`, `complete.log`. + - `review_gate`: 사용자 입력, 출력 검토, 완료 승인, archive 승인처럼 자동 적용 전에 멈춰야 하는 판단 지점. +- **공통 revision 필드 후보**: + +| 필드 | 설명 | +|------|------| +| `roadmap_revision` | Core가 읽은 git commit SHA 또는 file/index revision | +| `document_path` | `ROADMAP.md`, `PHASE.md`, Milestone 문서, SDD 문서, task artifact 경로 | +| `document_hash` | 같은 commit 안에서 파일 단위 충돌을 확인하기 위한 content hash 후보 | +| `expected_revision` | caller가 적용을 기대하는 revision | +| `idempotency_key` | 같은 command 재시도 중복 적용 방지 키 | +| `actor` | 사용자, provider webhook, scheduler, agent, runtime event 같은 변경 주체 | +| `reason` | 사용자 요청, provider status change, completion event, reconciliation 등 적용 사유 | + +### 6.2 Roadmap Action 후보 +- **설명**: Flutter UI, provider webhook, scheduler, agent runtime은 같은 Core action shape를 통해 roadmap 변경을 검사하거나 적용한다. + +| action | request payload | response payload | +|--------|-----------------|------------------| +| `roadmap.validate` | `{ "scope?", "paths?", "strict": true }` | `{ "valid", "diagnostics", "revision" }` | +| `roadmap.get_position` | `{ "current_path?", "include_flow": true }` | `{ "roadmap", "phase", "milestones", "current_candidates" }` | +| `roadmap.propose_change` | `{ "target", "change", "actor", "reason", "dry_run": true }` | `{ "proposal", "affected_paths", "review_gate?" }` | +| `roadmap.apply_change` | `{ "proposal_id?", "target", "change", "expected_revision", "idempotency_key", "actor", "reason" }` | `{ "applied", "revision", "affected_paths", "review_gate?" }` | +| `roadmap.transition` | `{ "target", "to_status", "expected_revision", "idempotency_key", "actor", "reason" }` | `{ "transitioned", "from_status", "to_status", "revision", "review_gate?" }` | +| `roadmap.archive` | `{ "target", "expected_revision", "idempotency_key", "actor", "reason", "approved": false }` | `{ "archived", "archive_paths", "revision", "review_gate?" }` | +| `roadmap.dependency_check` | `{ "target", "direction": "both" }` | `{ "locks", "ready", "blocking_reasons" }` | +| `roadmap.ingest_completion_event` | `{ "origin_task", "complete_log", "roadmap_completion", "expected_revision?", "idempotency_key" }` | `{ "applied_tasks", "milestone_status?", "revision", "review_gate?" }` | + +- **공통 입력 원칙**: + - 상태 변경, archive, dependency lock 갱신, completion event ingest는 `expected_revision`과 `idempotency_key`를 받는다. + - destructive 변경과 archive는 사용자 승인 또는 `review_gate` 해소 없이 자동 적용하지 않는다. + - `roadmap.propose_change`는 문서 초안이나 dry-run proposal을 만들 수 있지만, 적용은 `roadmap.apply_change` 또는 더 구체적인 transition/archive action이 담당한다. + - `roadmap.ingest_completion_event`는 `complete.log`의 `Roadmap Completion`과 Milestone 기능 Task id가 매칭될 때만 Task 체크 후보를 만든다. + +### 6.3 Review Gate 후보 +- **설명**: Core는 자동 판단이 위험한 지점을 review gate로 올리고, gate가 해소되기 전까지 apply/archive side effect를 멈춘다. + +| gate | trigger | resolution | +|------|---------|------------| +| `user_input_required` | 제품 방향, 범위, 책임 경계처럼 에이전트가 확정할 수 없는 결정 | Milestone `구현 잠금 > 결정 필요` 또는 SDD `USER_REVIEW.md` | +| `task_user_review` | plan/code-review 루프가 사용자 결정 없이는 이어갈 수 없음 | `agent-task/.../USER_REVIEW.md` 해소 후 후속 completion event | +| `completion_review` | 모든 기능 Task가 충족되어 `[검토중]` 전환 후보 | 사용자 완료 확인 | +| `archive_approval` | `[완료]` 전환과 archive 이동 후보 | 사용자 archive 승인 | +| `conflict_review` | revision mismatch, provider/roadmap 동시 수정, destructive change | dry-run proposal 확인 후 명시 apply | + +- Plane `User Review`는 provider board state이고, `USER_REVIEW.md`는 agent-task 또는 SDD의 stop artifact다. Core는 둘을 같은 사용자 판단 신호로 정규화하되 저장 위치와 해소 조건은 분리한다. + +### 6.4 HTTP 역할과 첫 구현 순서 후보 +- HTTP API는 Flutter UI, provider webhook, internal integration, smoke/curl compatibility 표면으로 유지한다. +- HTTP handler는 roadmap 문서를 직접 변경하지 않고 Core action을 호출하며, action request에 `expected_revision`, `idempotency_key`, `actor`, `reason`, `dry_run`을 전달한다. +- 외부 provider webhook은 wakeup/input channel이고, roadmap mutation 여부는 Core action의 validation과 revision check 결과에 따른다. +- 첫 구현 순서는 `roadmap.validate` -> `roadmap.get_position` -> `roadmap.ingest_completion_event` 순서를 기본 후보로 둔다. + - `roadmap.validate`: side effect 없이 문서 구조와 lock/gate 상태를 확인한다. + - `roadmap.get_position`: Flutter UI와 agent runtime이 같은 current/flow 해석을 공유한다. + - `roadmap.ingest_completion_event`: 기존 plan/code-review 완료 이벤트를 Core action 경계로 끌어와 Milestone Task 체크 후보를 만든다. + +--- + +## 7. Workspace / Project Metadata 계약 후보 > [!IMPORTANT] > **Workspace/Project Metadata 상태**: 일반 Workspace/Project metadata는 아직 완전한 source schema가 없으며 아래는 후보 필드 목록입니다. 단, Milestone sync에 필요한 provider project, git remote, workspace 설정은 5.3의 Project Sync Configuration 후보로 분리하고 Core DB 저장 대상으로 본다. -### 6.1 Workspace Metadata 후보 스펙 +### 7.1 Workspace Metadata 후보 스펙 - **설명**: 에이전트 작업 공간(Workspace)에 대한 설정 및 상태 메타데이터. - **후보 필드**: - `workspace_id`: 작업 공간 고유 식별자 (UUID) @@ -459,7 +528,7 @@ - `status`: 현재 상태 (예: `active`, `archived`, `suspended`) - `settings`: 작업 공간에 특화된 동적 설정 JSON 오브젝트 (예: 자동 스케줄링 옵션, 알림 채널 정보 등) -### 6.2 Project Metadata 후보 스펙 +### 7.2 Project Metadata 후보 스펙 - **설명**: 작업 공간 내 세부 프로젝트(Project) 정보. - **후보 필드**: - `project_id`: 프로젝트 고유 식별자 (UUID) @@ -472,13 +541,13 @@ --- -## 7. 클라이언트 Integration 설정 계약 후보 +## 8. 클라이언트 Integration 설정 계약 후보 > [!IMPORTANT] > 이 절은 `apps/client`의 integration boundary에서 host/plugin/transport 사이에 교환되는 설정값을 후보로 모은 것이다. 실제 source schema는 소비하는 core/client 경계가 안정화된 뒤로 미룬다. > 관련 코드 경계: `apps/client/lib/src/integrations/proto_socket/` 와 `apps/client/lib/src/integrations/mattermost/`. -### 7.1 proto-socket Endpoint 설정 후보 +### 8.1 proto-socket Endpoint 설정 후보 - **설명**: `apps/client`가 proto-socket transport에 의존할 때 사용하는 연결/하트비트 설정. 현재 구현은 `proto_socket` Dart 패키지(local path)를 끌어 쓰며 bootstrap에서 자동 연결하지 않는다. - **후보 필드**: - `host`: 대상 서버 hostname @@ -489,7 +558,7 @@ - `heartbeat_wait_seconds`: heartbeat 응답 대기 한계 (기본 60) - `enabled`: bootstrap 시 자동 연결 활성화 여부 (기본 false) -### 7.2 Mattermost Push Host 책임 경계 후보 +### 8.2 Mattermost Push Host 책임 경계 후보 - **설명**: Mattermost push 통합에서 `apps/client` host가 plugin adapter에게 위임/공급해야 하는 데이터와 콜백. plugin adapter는 platform 측 plugin singleton에 격리되어 있고, 그 외 코드는 모두 `MattermostPushClient` 인터페이스에만 의존한다. - **호스트 소유 필드/콜백**: - `server_url`: Mattermost 서버 base URL (auth 핸드오프, signing key 저장에 함께 사용) diff --git a/services/core/README.md b/services/core/README.md index 9aa6400..4abe0df 100644 --- a/services/core/README.md +++ b/services/core/README.md @@ -2,7 +2,7 @@ NomadCode Core는 사용자 요청을 작업 단위로 받고, 작업 상태를 저장하며, 비동기 Agent 작업 흐름을 관리하기 위한 서버입니다. -초기 목표는 작업 생성과 조회, PostgreSQL 기반 작업 상태 저장, River 기반 비동기 작업 실행, Plane/Jira adapter, Mattermost REST post adapter 구성, IOP OpenAI-compatible Responses 호출 경로 확보입니다. NomadCode Core는 직접 모델 런타임, 모델 라우팅, RAG, 모델 실행용 MCP/tool policy, output validation, fallback 정책을 소유하지 않고 IOP를 실행/최적화 계층으로 사용합니다. Roadmap Operations Control Plane처럼 NomadCode 내부 상태/action을 외부 agent에게 여는 MCP 표면은 Core의 후속 제어 adapter 범위로 둡니다. +초기 목표는 작업 생성과 조회, PostgreSQL 기반 작업 상태 저장, River 기반 비동기 작업 실행, Plane/Jira adapter, Mattermost REST post adapter 구성, IOP OpenAI-compatible Responses 호출 경로 확보입니다. NomadCode Core는 직접 모델 런타임, 모델 라우팅, RAG, 모델 실행용 MCP/tool policy, output validation, fallback 정책을 소유하지 않고 IOP를 실행/최적화 계층으로 사용합니다. Roadmap Operations Control Plane은 NomadCode 내부 roadmap/action side effect의 Core action 경계를 먼저 정리하고, 외부 agent 제어 표면은 후속 제어 adapter 스케치에서 별도로 판단합니다. ## 현재 구현 범위 @@ -25,7 +25,7 @@ NomadCode Core는 사용자 요청을 작업 단위로 받고, 작업 상태를 - IOP native protocol 연동 - Agent Integrator 연동 또는 대체 여부 확정 - Outline / Forgejo / Nextcloud 연동 -- Roadmap Operations Control Plane MCP 서버 +- Roadmap Operations Control Plane의 외부 agent 제어 adapter - IOP 내부 MCP/tool policy - Web Agent UI - Flutter 앱