toki/nomadcode
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
nomadcode/agent-roadmap/phase/agent-ops-mcp-control-plane/milestones/milestone-work-item-creation-sync.md
toki fad5627ae6 feat: milestone work item creation/sync 구현 및 roadmap sync 기능 추가 
- Plane Todo projection 및 idempotency/retry 메커니즘 구현
- Roadmap sync identity 및 step 모델/DB 마이그레이션/쿼리 추가
- OpenAI 및 Plane adapter 개선
- roadmaps sync package: plane_format, plane_projection, retry 모듈 추가
- Storage layer: roadmap_sync_identities, roadmap_sync_steps 추가
- agent-task 아카이브 정리
2026-06-14 04:08:15 +09:00

23 KiB
Raw Blame History

Milestone: Milestone Work Item Creation Sync

위치

  • Roadmap: agent-roadmap/ROADMAP.md
  • Phase: agent-roadmap/phase/agent-ops-mcp-control-plane/PHASE.md

목표

Plane-origin 경로로 Milestone을 생성하고, develop branch의 agent-roadmap Milestone을 source of truth로 삼아 Plane 상위 티켓과 같은 identity로 연결해 Todo 검토 상태까지 동기화한다. 이 마일스톤의 완료 지점은 사용자가 Plane Todo에서 develop에 반영된 Milestone 내용을 검토할 수 있는 상태이며, 여기서 멈춘다.

상태

[진행중]

구현 잠금

  • 상태: 해제
  • 결정 필요: 없음
  • 부분 잠금:
    • plane-agent-authoring: IOP Edge OpenAI-compatible HTTP 통로로 workspace-bound agent run을 실행할 수 있을 때까지 실행 잠금

범위

  • Plane Backlog + AGENT assignee 상위 티켓을 Milestone 생성 trigger로 처리하는 흐름
  • Plane project 단위 sync 설정 모델과 DB 저장 흐름
  • Plane project 대상, git remote, 실제 작업 workspace를 project sync 기본 설정으로 관리하는 흐름
  • NomadCode host 기준 workspace base path, repo별 project workspace root, branches/main, branches/develop, slots/000+ 기반 workspace layout 정의
  • 고정 branch workspace인 branches/develop과 branches/main을 항상 유지하되 agent authoring 쓰기 작업에는 배정하지 않는 흐름
  • branches/develop은 roadmap source-of-truth scan, 테스트 동기화, Plane Todo projection 기준으로 사용하고, branches/main은 release/promote 기준으로 사용하는 흐름
  • Workspace slot의 사용중 상태를 확인하고 비어 있는 slot만 병렬 작업에 할당하는 흐름
  • 안정성을 우선해 slot별 독립 git checkout을 기본으로 두는 흐름
  • Plane 티켓 원본 본문을 사용자 요청: 댓글로 보존하는 흐름
  • develop branch의 agent-roadmap Milestone을 source of truth로 삼는 흐름
  • Milestone sync 확정 시점을 develop branch commit/push 완료로 보는 흐름
  • develop push 완료를 sync layer가 감지한 뒤 Plane 티켓을 갱신하고 Todo로 이동하는 흐름
  • develop에 반영된 Milestone을 기준으로 Plane 본문을 Milestone 내용으로 치환하는 흐름
  • Plane 제목을 [milestone-id] 제목 형식으로 바꾸고 Todo로 이동하는 흐름. 여기서 milestone-id는 develop의 Milestone 파일 slug를 기본값으로 쓴다.
  • Plane 티켓 제목/본문을 입력으로 workspace agent가 Milestone 파일을 직접 작성하고 develop에 push하는 authoring 경계
  • Workspace agent authoring run을 IOP Edge OpenAI-compatible HTTP로 실행하는 1차 통로와 실행 가능 여부 잠금 기준
  • Plane 티켓과 pushed Milestone을 연결하는 provider/work item identity 매칭 기준
  • Authoring run의 최소 실행 상태와 stale/failed 판단 기준
  • Pushed commit에서 실제 Milestone 파일 변경과 Plane ticket identity를 검증한 뒤 Plane을 갱신하는 기준
  • Milestone path와 Plane work item id의 identity map, Plane work item id 기반 idempotency, actor guard, 부분 실패 재시도 기준

기능

Epic: [plane-nomad-iop-cycle] Plane-NomadCode-IOP One Cycle

Plane Backlog + AGENT assignee 상위 티켓 하나가 NomadCode project sync와 IOP Edge HTTP workspace agent 실행을 거쳐 develop source-of-truth에 Milestone 산출물을 만들고, 다시 Plane Todo 검토 상태로 투영되는 한 사이클을 최상위 실행 흐름으로 둔다.

  • [cycle-project-config] Plane project target, git remote, source-of-truth branch, workspace base/repo 설정을 project sync 기준으로 해석할 수 있다. 검증: [project-config] Epic의 완료 근거와 workitempipeline project binding/slot metadata 연결로 확인했다.
  • [cycle-workspace-topology] project workspace root 아래 branches/main, branches/develop, slots/000+ 구조를 준비하고 branch workspace와 agent slot 상태를 분리한다. 검증: branches/develop은 source-of-truth scan 기준, branches/main은 release/promote 기준, slots/<index>는 authoring 쓰기 작업 기준으로만 사용된다.
  • [cycle-iop-http-ready] IOP Edge OpenAI-compatible HTTP(/v1/responses) workspace agent 실행 통로를 선행 조건으로 확인한다. 검증: NomadCode가 IOP CLI를 직접 실행하지 않고, model, input, metadata.workspace 요청만으로 workspace-bound agent target을 실행할 수 있다.
  • [cycle-authoring-run] Plane 티켓 제목/본문과 provider work item identity를 입력으로 slots/<index> workspace에서 1회 authoring run을 실행한다. 검증: agent가 slot 안에서 Milestone 파일을 작성/갱신하고 develop에 commit/push한다.
  • [cycle-develop-sync] sync layer가 branches/develop 또는 remote develop에서 pushed Milestone을 감지하고 원래 Plane 티켓 identity와 매칭한다. 검증: slot local 변경이나 push 실패 상태만으로 Plane Todo projection을 수행하지 않는다.
  • [cycle-plane-todo] 원본 Plane 본문을 사용자 요청: 댓글로 보존하고, develop의 Milestone 내용으로 Plane 본문/제목을 갱신한 뒤 Todo로 이동한다. 검증: 사용자에게 Plane Todo에서 develop 반영 결과를 검토할 수 있는 상태가 된다.
  • [cycle-idempotency] 같은 Plane 티켓 또는 같은 Milestone path 재처리 시 중복 생성 없이 남은 단계만 재시도한다. 검증: identity map, actor guard, provider revision, roadmap revision 기준으로 부분 실패를 복구한다.

Epic: [project-config] Project sync configuration

Plane project 단위로 Milestone sync에 필요한 기본 설정을 저장하고 이후 UI/UX가 소비할 project settings 경계를 만든다.

  • [project-model] Plane project 단위 sync 설정 모델을 정의한다. 검증: 설정 모델이 provider project target, git remote URL, source-of-truth branch, workspace id/path를 필수 필드로 갖는다.
  • [project-store] Project sync 설정을 Core DB에 저장하는 persistence 경계를 정한다. 검증: Plane project별로 하나의 active sync 설정을 찾을 수 있고, Milestone 생성 동기화가 이 설정 없이는 진행되지 않는 기준이 문서화되어 있다.
  • [project-bind] Plane-origin 생성 동기화가 project sync 설정을 통해 Plane project, git repository, 작업 workspace를 해석하도록 한다. 검증: 같은 Plane project 안의 티켓은 같은 git/workspace 설정을 사용하며, 다른 Plane project와 섞이지 않는다.
  • [workspace-layout] NomadCode host 기준 workspace 경로 규칙의 초기 기준을 정의한다. 검증: workspace_base_path=/home/user/workspace, repo_dir_name=nomadcode이면 project workspace root는 /home/user/workspace/nomadcode이고, 후속 workspace-topology Epic에서 고정 branch workspace와 작업 slot 하위 경로를 분리한다.
  • [workspace-slot] 병렬 운용을 위한 workspace slot index 모델을 정의한다. 검증: 기본 작업공간은 000이고, 병렬 요청이 들어오면 001, 002처럼 3자리 zero-padded index를 증가시키며 각 slot이 독립 작업공간으로 예약된다.
  • [workspace-slot-state] Workspace slot의 사용중 상태 모델을 정의한다. 검증: 각 slot은 available, in_use, dirty, error 같은 상태 후보를 갖고, 새 작업은 available slot만 선택하며, 동시에 들어온 요청이 같은 slot을 잡지 않도록 DB에서 원자적으로 in_use로 전환하는 기준이 있다.
  • [workspace-checkout] Git repository checkout 정책을 project sync 설정과 연결한다. 검증: git remote는 project sync 설정에서 읽고, 안정성을 우선해 각 slot은 같은 remote의 독립 checkout을 기본으로 확보하며, 일반 단일 운용에서는 000만 사용한다.
  • [settings-ui] Project sync 설정을 이후 프로젝트 설정 UI/UX에서 관리해야 하는 후보로 남긴다. 검증: 이번 마일스톤에서는 UI 구현을 하지 않고, 후속 Project settings 화면이 provider project target, git remote, workspace를 표시/수정해야 한다는 요구가 남아 있다.

Epic: [workspace-topology] Branch workspace and slot topology

Project sync workspace를 고정 branch workspace와 agent 작업 slot으로 분리해 source-of-truth scan, 테스트 동기화, release 기준, 병렬 authoring 실행이 서로 섞이지 않도록 한다.

  • [branch-workspaces] repo별 project workspace root 아래 branches/main과 branches/develop을 항상 유지하는 기준을 정의한다. 검증: 두 workspace는 예약 가능한 agent 작업 slot이 아니며, develop은 roadmap/test sync 기준, main은 release/promote 기준으로만 사용된다.
  • [slot-layout] agent authoring 작업공간을 slots/000, slots/001, slots/002처럼 slots/ 하위 3자리 index로 계산하도록 경로 규칙을 갱신한다. 검증: workspace_base_path=/home/user/workspace, repo_dir_name=nomadcode이면 develop 기준 workspace는 /home/user/workspace/nomadcode/branches/develop, 기본 작업 slot은 /home/user/workspace/nomadcode/slots/000이다.
  • [slot-source-branch] 새 agent slot은 source-of-truth branch인 develop 기준으로 checkout/branch 준비를 하되, Plane Todo projection은 slot local file이 아니라 branches/develop 또는 remote develop 반영 여부를 기준으로 판단한다. 검증: slot dirty 상태나 미push 변경만으로 Plane 본문 치환/Todo 이동을 하지 않는다.
  • [branch-sync-state] branch workspace와 slot workspace의 상태 모델을 분리한다. 검증: branch workspace는 synced, stale, error 같은 sync 상태 후보를 갖고, slot workspace는 기존 available, in_use, dirty, error 같은 배정 상태를 유지한다.
  • [workspace-provision] project sync 설정 저장 또는 첫 사용 시 branches/main, branches/develop, 최소 slots/000의 checkout 준비 기준을 남긴다. 검증: missing workspace를 조용히 임의 cwd로 대체하지 않고 준비 실패를 명시 오류로 반환한다.

Epic: [agent-bridge] Workspace agent IOP bridge

Plane-origin sync가 workspace agent를 실행할 수 있도록 IOP Edge OpenAI-compatible HTTP 기반 1차 실행 통로를 선행으로 둔다.

  • [iop-http-channel] Core/runtime이 IOP Edge OpenAI-compatible HTTP를 통해 workspace-bound agent authoring run을 시작하는 최소 통로를 정의한다. 검증: runtime이 slots/<index> workspace path, Plane 티켓 제목/본문, provider work item id, project sync 설정, roadmap 작성 지시를 /v1/responses 요청의 input과 metadata.workspace로 전달할 수 있다.
  • [authoring-state] Workspace agent authoring run의 최소 상태 모델을 정의한다. 검증: 첫 구현은 in_progress, succeeded, failed만 상태로 저장하고, stale/timeout은 별도 상태가 아니라 updated_at 기준으로 판정한다.
  • [provider-identity] Plane 티켓과 workspace agent 결과를 연결하는 최소 identity를 정의한다. 검증: agent가 작성한 Milestone 작업 컨텍스트에 provider와 Plane work item id가 남고, sync layer는 이 identity로 pushed Milestone을 원래 Plane 티켓과 매칭한다. 별도 authoring_run_id는 첫 slice의 필수 매칭 키로 만들지 않는다.
  • [agent-run-result] Workspace agent authoring run의 성공/실패 판정 기준을 정의한다. 검증: authoring 성공은 별도 구조화 응답이 아니라 develop branch에 Milestone 파일 변경이 commit/push된 상태로 판정하며, sync layer의 Plane work item id 검증은 pushed-milestone-match 단계에서 처리한다. 실패는 exit code, push 실패, dirty workspace, 충돌 상태로 구분된다.
  • [agent-bridge-lock] Plane authoring 실행 단계의 선행 잠금을 정의한다. 검증: IOP Edge OpenAI-compatible HTTP workspace agent 실행 통로가 없으면 plane-agent-authoring 단계는 실행하지 않고, project sync 설정과 branch/slot workspace 준비까지만 진행할 수 있다.

Epic: [creation-sync] Milestone creation sync

Plane-origin 생성 경로를 develop agent-roadmap 기준의 Todo 검토 상태까지 수렴시킨다.

  • [plane-trigger] Plane Backlog + AGENT assignee 상위 티켓을 Milestone 생성 trigger로 처리한다. 검증: NomadCode가 자신이 만든 후속 변경을 다시 사용자 trigger로 오인하지 않는 actor guard가 설명되어 있다.
  • [plane-agent-authoring] Plane 티켓 제목/본문을 workspace agent authoring run의 입력으로 전달하는 경계를 정의한다. 검증: 정상 happy path에서 필수 agent/model 개입은 1회이며, 결과물은 별도 변환 응답이 아니라 slots/<index> workspace 안의 agent-roadmap Milestone 파일 작성/갱신과 develop commit/push다. 이 단계는 IOP Edge OpenAI-compatible HTTP 통로가 준비된 뒤에만 실행된다.
  • [plane-draft] Plane 티켓 본문을 읽어 workspace agent가 roadmap skill로 Milestone 초안을 생성하거나 갱신하고 develop에 반영한다. 검증: 1상위 티켓은 1마일스톤으로 매핑되고 같은 Plane 티켓 재처리 시 중복 Milestone을 만들지 않는다. 이번 범위는 Plane-origin에 한정하되, Milestone 파일 작성과 push는 IDE-origin과 같은 workspace agent 경로를 쓴다.
  • [develop-truth] develop branch의 agent-roadmap을 sync source of truth로 정의한다. 검증: feature branch나 로컬 초안은 Plane Todo projection 대상이 아니며, Plane Todo 티켓은 develop에 Milestone 변경이 commit/push된 뒤에만 생성/갱신된다.
  • [pushed-milestone-match] Sync layer가 pushed commit과 Plane 티켓을 매칭하는 규칙을 정의한다. 검증: pushed commit 또는 roadmap scan에서 실제 agent-roadmap/phase/*/milestones/*.md 변경이 있고, 해당 Milestone에 provider와 Plane work item id가 확인될 때만 Plane 갱신 단계로 넘어간다.
  • [plane-preserve] 원본 Plane 본문을 사용자 요청: 댓글로 보존한 뒤, develop에 반영된 Milestone 내용을 기준으로 Plane 본문을 치환한다. 검증: 댓글 보존 실패 시 본문 치환으로 넘어가지 않고, develop 반영 전에는 Todo 이동을 하지 않는다.
  • [plane-todo] sync layer가 develop push 완료 또는 roadmap scan으로 감지한 Milestone을 기준으로 Plane 제목을 [milestone-id] 제목 형식으로 바꾸고 티켓을 Todo로 이동한다. 검증: milestone id는 develop의 Milestone 파일 slug를 기본값으로 쓰고, 실제 identity는 제목이 아니라 identity map의 Milestone path와 provider work item id로 추적된다.
  • [creation-idmap] Milestone path, Milestone id, provider, work item id, provider revision, roadmap revision을 identity map으로 연결한다. 검증: 같은 Plane 티켓 또는 같은 Milestone path가 재처리되어도 같은 Milestone/work item pair를 찾을 수 있다.
  • [creation-retry] 생성 동기화의 idempotency와 부분 실패 재시도 정책을 정한다. 검증: develop 반영, 댓글 보존, 본문 치환, 제목 변경, Todo 이동 중 일부만 성공해도 재시도 시 중복 생성 없이 남은 단계만 적용된다.

완료 리뷰

  • 상태: 없음
  • 요청일: 없음
  • 완료 근거: 없음
  • 리뷰 필요:
    • 사용자가 완료 결과를 확인했다
    • archive 이동을 승인했다
  • 리뷰 코멘트: 없음

범위 제외

  • Plane Todo -> In Progress 실행 시작
  • Milestone Task를 Plane 하위 티켓으로 생성하거나 동기화하는 구현
  • agent-task/m-<milestone-id> plan/code-review 실행 lifecycle
  • 상위 티켓 User Review, Done, Cancelled 완료/폐기 처리
  • 에이전트 챗 또는 IDE-origin Milestone 생성 후 Plane Todo로 projection하는 흐름
  • Project sync 설정 관리 UI/UX 구현
  • 사용자 승인 없는 archive 이동

작업 컨텍스트

  • 관련 경로: services/core/internal/workitem/, services/core/internal/scheduler/, services/core/internal/http/, services/core/internal/db/, services/core/migrations/, services/core/queries/, packages/contracts/, agent-roadmap/
  • 선행 작업: Roadmap Driven Agent-Ops Automation의 sync domain 방향 정리
  • 후속 작업: Milestone Execution Lifecycle Sync
  • 현재 지점: 2026-06-08부터 이 마일스톤을 활성 진행 대상으로 둔다. 우선 Plane-origin Milestone 생성 sync를 Todo 검토 상태까지 수렴시키는 범위에서 확인한다.
  • Source of truth: develop branch의 agent-roadmap을 Milestone sync의 source of truth로 둔다. Plane은 이 마일스톤의 intake/projection/review UI이며, agent chat/IDE-origin 생성은 이번 범위에서 제외한다.
  • Develop 반영 기준: 이 마일스톤에서 develop에 반영되었다는 말은 PR 요청이나 PR 생성이 아니라 develop branch에 Milestone 변경 commit/push가 완료된 상태를 뜻한다.
  • Agent authoring 기준: Plane-origin 정상 흐름에서 필수 agent/model 개입은 Plane 티켓 제목/본문을 입력으로 slots/<index> workspace 안에서 Milestone 파일을 작성/갱신하고 develop에 commit/push하는 1회 authoring run이다. 이 단계의 결과물은 별도 응답 구조가 아니라 git에 반영된 roadmap 파일 변경이다.
  • IOP 통로 기준: workspace agent authoring run은 IOP Edge OpenAI-compatible HTTP(/v1/responses)를 통해 실행하는 것을 1차 통로로 둔다. 이 통로가 준비되기 전에는 Plane authoring 실행 단계가 잠기며, project 설정/branch workspace/slot 준비와 계약 정리까지만 진행한다.
  • Runtime 기준: Core/runtime은 project 설정 조회, branch workspace sync, slot 할당, checkout 준비, IOP Edge HTTP 실행 요청, actor guard, identity/idempotency, push 완료 감지, Plane 댓글/본문/제목/status 변경을 결정적으로 처리한다. 이번 범위는 Plane-origin에 한정하되, Milestone 파일 작성과 push는 IDE-origin과 같은 workspace agent 경로를 쓴다.
  • Sync layer 기준: Plane Backlog + AGENT assignee는 authoring run 시작 trigger이고, Plane Todo 이동은 develop push 완료가 확인된 뒤 sync layer가 수행한다.
  • Matching 기준: sync layer는 push 성공만으로 Plane을 갱신하지 않는다. pushed diff 또는 roadmap scan에서 Milestone 파일 변경을 확인하고, Milestone 작업 컨텍스트의 provider와 Plane work item id가 원래 Plane 티켓과 매칭된 뒤에만 댓글 보존/본문 치환/제목 변경/Todo 이동을 수행한다.
  • Authoring 상태 기준: 첫 구현에서는 authoring run 상태를 in_progress, succeeded, failed로만 둔다. stale/timeout은 updated_at으로 판정하고, 별도 attempt 모델은 만들지 않는다.
  • Project 설정: sync는 Plane project 단위로 묶으며, 각 project 설정은 Plane project target, git remote URL, source-of-truth branch, workspace base path, repo dir name을 DB에 저장한다. branch workspace와 slot workspace path는 이 설정에서 파생한다.
  • Workspace 경로 기준: workspace base path는 NomadCode host 기준 절대 경로로 해석한다. 예를 들어 /home/user/workspace를 base로 두고 git repo 이름이 nomadcode이면 project workspace root는 /home/user/workspace/nomadcode다.
  • Branch workspace 기준: project workspace root 아래 branches/main, branches/develop을 고정 checkout으로 유지한다. branches/develop은 roadmap source-of-truth scan, 테스트 동기화, Plane Todo projection 기준이고, branches/main은 release/promote 기준이다. 둘 다 agent authoring 작업에 예약하지 않는다.
  • Workspace slot 기준: 실제 agent 작업공간은 project workspace root 아래 slots/000, slots/001, slots/002 같은 3자리 slot index로 둔다. 일반 상황에서는 /home/user/workspace/nomadcode/slots/000 하나로 운영하고, 병렬 요청이 들어오면 /home/user/workspace/nomadcode/slots/001, /home/user/workspace/nomadcode/slots/002처럼 늘린다.
  • Slot 사용 상태: slot은 Core DB에서 available 또는 in_use 같은 사용 상태를 추적한다. 여기서 사용 상태는 해당 slot이 현재 작업에 배정되어 다른 병렬 작업이 잡으면 안 되는지를 나타낸다.
  • Checkout 기준: 안정성을 우선해 branch workspace와 각 slot은 같은 git remote를 기준으로 독립 checkout을 갖는 작업공간으로 둔다. 초기 workspace 생성 때 clone 비용이 들지만 이후 branch sync와 agent 작업은 각 checkout 안에서 분리되므로 운영 리스크를 낮춘다.
  • 후속 UI/UX: project settings 화면에서 Plane project target, git remote, workspace 설정을 확인하고 수정하는 UX가 필요하다.
  • 완료 근거(2026-06-07): [project-config]는 services/core/internal/projectsync/, services/core/migrations/00004_create_project_sync_settings.sql, services/core/migrations/00005_create_workspace_slots.sql, services/core/queries/project_sync_settings.sql, services/core/queries/workspace_slots.sql, packages/contracts/notes/flutter-core-api-candidates.md의 모델/저장/slot/UI 후보 경계와 테스트로 확인했다. 검증: cd services/core && go test ./... PASS.
  • 현황 동기화(2026-06-13): agent-task/archive/2026/06/m-milestone-work-item-creation-sync/*/complete.log의 Roadmap Completion 근거로 cycle-workspace-topology, cycle-iop-http-ready, cycle-authoring-run, cycle-develop-sync, cycle-plane-todo를 완료 처리했다. 현재 active 작업은 agent-task/m-milestone-work-item-creation-sync/05+03,04_idempotency_retry(cycle-idempotency)이며, 이 Task는 완료 evidence가 없어 미완료로 유지한다.
  • 중지 지점: project sync 설정, workspace topology, IOP Edge HTTP authoring run 경계, pushed Milestone identity match, Plane 원문 댓글 보존/본문·제목 갱신/Todo 이동 projection은 완료 근거가 있다. 다음 실행 단위는 identity map 기반 idempotency/retry다.
  • 루프 목표: Plane Backlog + AGENT assignee -> slots/<index> workspace 예약/준비 -> IOP Edge HTTP로 workspace agent authoring run 실행 -> agent가 Milestone 파일 작성/갱신 후 develop push -> sync layer가 branches/develop 또는 remote develop에서 push 완료/roadmap scan을 감지 -> Plane 원문 댓글 보존/본문 치환/제목 변경/Todo 이동 -> 사용자가 확인 후 In Progress로 이동하는 지점까지다. 현재 최상위 사이클에서 남은 실행 단위는 cycle-idempotency이며, In Progress 이후 실행은 후속 잠금 범위다.
  • 후속 잠금: Todo -> In Progress 이후 실행 lifecycle은 사용자가 명시적으로 잠금을 해제할 때까지 진행하지 않는다.
  • Plane work item 경계: 이 마일스톤에서 말하는 Plane Milestone은 Plane native milestone object가 아니라 1상위 티켓 = 1 agent-roadmap Milestone으로 보는 work item mapping이다.
  • 확인 필요: 없음