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

35 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 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을 시작하는 최소 통로를 정의한다. 검증: authoring.BuildAuthoringGenerateInput이 Plane 티켓 본문, provider work item id, slot workspace path를 model.GenerateInput으로 만들고, scheduler가 Plane-origin authoring task를 A2A가 아니라 OpenAI-compatible model bridge로 라우팅한다.
  • [authoring-state] Workspace agent authoring run의 최소 상태 모델을 정의한다. 검증: 첫 구현은 in_progress, succeeded, failed만 상태로 저장하고, stale/timeout은 별도 상태가 아니라 updated_at 기준으로 판정한다.
  • [provider-identity] Plane 티켓과 workspace agent 결과를 연결하는 최소 identity를 정의한다. 검증: ExternalProvider/ExternalID 또는 payload work_item의 provider/work item id가 workspace metadata에 남고, pushed Milestone matching은 provider + work item id + Milestone path를 쓰며 별도 authoring_run_id를 필수 매칭 키로 쓰지 않는다.
  • [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-task/m-milestone-work-item-creation-sync/08_agent_run_result_gate/
  • [agent-bridge-lock] Plane authoring 실행 단계의 선행 잠금을 정의한다. 검증: IOP Edge OpenAI-compatible HTTP bridge가 Plane-origin authoring task의 실행 통로가 되었고, authoring 조건이 없거나 workspace checkout metadata가 없으면 일반 실행/준비 흐름으로 남는다.

Epic: [creation-sync] Milestone creation sync

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

  • [plane-trigger] Plane Backlog + AGENT assignee 상위 티켓을 Milestone 생성 trigger로 처리한다. 검증: NomadCode가 자신이 만든 후속 변경을 다시 사용자 trigger로 오인하지 않는 actor guard가 설명되어 있다. 계획: agent-task/m-milestone-work-item-creation-sync/09_creation_trigger_gate/
  • [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 경로를 쓴다. 계획: agent-task/m-milestone-work-item-creation-sync/10+09_plane_draft_authoring/
  • [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 이동 중 일부만 성공해도 재시도 시 중복 생성 없이 남은 단계만 적용된다.
  • [creation-sync-orchestrator] develop Milestone match, identity/step ledger, Plane 원문 보존/본문·제목 갱신/Todo 이동을 하나의 runtime sync orchestrator로 연결한다. 검증: provider fake와 store fake 기반 테스트에서 not-ready는 provider 호출 없음, ready는 ledger 단계별 재시도와 Plane projection 순서를 보장한다. 계획: agent-task/m-milestone-work-item-creation-sync/11_creation_sync_orchestrator/

Epic: [live-cycle-gate] Live cycle verification gate

검토 결과, 단위 테스트와 fake provider/store 기반 runtime seam 검증만으로는 이 Milestone의 완료 지점인 Plane Todo 검토 상태까지 실제 원격 흐름이 수렴한다고 보기 어렵다. Archive 전에는 최소한 live smoke 또는 runtime-equivalent smoke로 webhook, authoring, develop 반영, Plane projection, slot 회수 경계를 확인한다.

  • [live-webhook-task] 원격 dev Plane에서 Backlog + AGENT assignee 상위 티켓을 만들거나 갱신하면 webhook만으로 Core task가 생성되고 checkout metadata가 남는다. 검증: Plane webhook log 202, Core task external ref, checkout.develop_branch_path/checkout.slot_path, workspace slot reservation을 secret redaction 상태로 확인한다.
  • [webhook-auto-enqueue] webhook-dispatched creation task가 별도 수동 API 호출 없이 authoring queue로 이어진다. 검증: 같은 Plane work item event에서 task 생성 이후 queued/running 또는 authoring run 시작 로그가 확인되고, 중복 webhook은 중복 task나 중복 queue를 만들지 않는다.
  • [authoring-develop-gate] IOP authoring 응답만으로 task 완료를 단정하지 않고, develop Milestone push와 provider identity match가 확인될 때 authoring 성공 또는 sync-ready로 판정된다. 검증: model response-only, slot-local dirty, push 실패는 Plane Todo projection으로 넘어가지 않고, develop match가 있을 때만 다음 단계로 수렴한다.
  • [live-creation-projection] matched develop scan/job 입력이 roadmapsyncpipeline.Service와 RoadmapCreationSyncWorker를 통해 실제 Plane 원문 댓글 보존, 본문/제목 갱신, Todo 이동으로 수렴한다. 검증: roadmap_sync_steps에 develop_matched, original_comment_preserved, plane_body_updated, plane_todo_moved가 기록되고 Plane UI에서 Todo 상태와 [milestone-id] 제목을 확인한다.
  • [slot-terminal-state] authoring 또는 projection이 terminal outcome에 도달하면 reserved workspace slot이 정책에 따라 available, dirty, error 중 하나로 전환된다. 검증: 성공 smoke 이후 다음 Plane-origin smoke가 수동 DB reset 없이 slot을 확보할 수 있고, 실패 smoke는 원인에 맞는 slot state를 남긴다.

완료 리뷰

  • 상태: 보완 필요
  • 요청일: 2026-06-14
  • 보완 전 완료 근거:
    • agent-task/archive/2026/06/m-milestone-work-item-creation-sync/11_creation_sync_orchestrator/complete.log의 Roadmap Completion 근거로 [creation-sync-orchestrator]를 완료 처리했다.
    • 검증 근거는 roadmapsyncpipeline.Service의 develop match -> identity/step ledger -> Plane projection 연결, optional RoadmapCreationSyncWorker, EnqueueRoadmapCreationSync seam, cd services/core && go test -count=1 ./..., cd services/core && go vet ./..., git diff --check PASS다.
    • Gito proto-socket branch.updated backend bridge는 후속 Gito Branch Event Creation Sync Bridge Milestone으로 분리했다.
  • 보완 필요 근거:
    • 2026-06-15 원격 preflight 결과, Core는 healthz/readyz, Plane webhook secret/API env, project sync 설정, smoke workspace checkout, available slot까지 준비할 수 있으나 현재 live로 확인 가능한 범위는 webhook 수신과 Core task 생성까지다.
    • 현재 webhook receiver는 task 생성 후 202 accepted로 종료하며, 생성 task를 자동 enqueue해 authoring run으로 넘기는 runtime 연결은 확인되지 않았다.
    • authoring worker는 IOP model response를 받으면 task를 complete 처리할 수 있으나, develop push/provider identity match를 runtime success gate로 닫는 live 경로와 slot terminal state 회수 정책은 아직 검증되지 않았다.
    • RoadmapCreationSyncWorker는 존재하지만 public trigger가 없고, Gito/develop event consumer runtime env와 wire smoke는 후속 Milestone에 남아 있어 Plane Todo projection까지 실제 원격 한 사이클로 증명되지 않았다.
  • 리뷰 필요:
    • creation-sync-orchestrator 계획이 PASS되고 runtime caller가 검증되었다
    • [live-cycle-gate] 보완 Task가 live smoke 또는 runtime-equivalent smoke evidence로 완료되었다
    • 사용자가 보완 결과를 확인했다
    • archive 이동을 승인했다
  • 리뷰 코멘트: 기존 unit/fake 기반 완료 근거는 보존하되, 실제 원격 흐름이 Plane Todo projection까지 자동 수렴한다는 증거가 부족해 [진행중]으로 되돌린다. Archive는 [live-cycle-gate] 보완 Task 완료 전까지 승인하지 않는다.

범위 제외

  • Gito /proto-socket의 branch.updated를 NomadCode core가 구독하고 target branch를 재검증/스캔해 creation sync job을 enqueue하는 backend bridge 구현. 이 범위는 후속 Gito Branch Event Creation Sync Bridge Milestone으로 분리한다.
  • 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-14): Gito는 Forgejo/webhook 기반 branch.updated event producer이고, NomadCode core는 이를 proto-socket으로 소비해 target branch를 재검증/스캔한 뒤 EnqueueRoadmapCreationSync를 호출해야 한다. 이 backend consumer/bridge는 Gito Branch Event Creation Sync Bridge Milestone으로 분리했다. 현재 creation-sync-orchestrator task는 matched scan/job 입력 이후의 orchestrator, worker, enqueue seam을 닫는 범위로 본다.
  • 현재 지점: 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를 완료 처리했다.
  • 현황 동기화(2026-06-14): agent-task/archive/2026/06/m-milestone-work-item-creation-sync/05+03,04_idempotency_retry/complete.log의 Roadmap Completion 근거로 cycle-idempotency를 완료 처리했다. 검증 근거는 identity map의 원자적 conflict 처리, strict retry identity key, cd services/core && go test -count=1 ./internal/storage ./internal/roadmapsync ./internal/adapters/plane, cd services/core && go test ./..., git diff --check PASS다. ./bin/sqlc는 기존 queries/workspace_slots.sql:19:11 ambiguity로 차단되어 완료 로그에 별도 기록되어 있다.
  • Workspace topology 세부 동기화(2026-06-14): agent-task/archive/2026/06/m-milestone-work-item-creation-sync/01_workspace_topology/complete.log, 02+01_workspace_slot_store/complete.log, 03+01,02_project_binding_checkout/complete.log, 03+02_develop_match/complete.log, 04+03_plane_todo_projection/complete.log와 현재 projectsync/workitempipeline 테스트 근거로 [branch-workspaces], [slot-layout], [slot-source-branch], [branch-sync-state]를 완료 처리했다. [workspace-provision]은 실제 first-use checkout 준비 검증과 기본 slot 등록, missing workspace 명시 오류 연결이 남아 agent-task/m-milestone-work-item-creation-sync/06_workspace_provision/ 및 agent-task/m-milestone-work-item-creation-sync/07+06_workspace_provision_pipeline/ 계획으로 분리했다.
  • Workspace provision pipeline 동기화(2026-06-14): agent-task/archive/2026/06/m-milestone-work-item-creation-sync/07+06_workspace_provision_pipeline/complete.log의 Roadmap Completion 근거로 [workspace-provision]을 완료 처리했다. 검증 근거는 workspace provision hook의 slot 예약/provider fetch/task creation 이전 실행, HTTP binder의 default slots/000 등록, ErrWorkspaceProvisionNotReady 409 매핑, cd services/core && go test -count=1 ./internal/projectsync ./internal/workitempipeline ./internal/http, cd services/core && go test ./..., cd services/core && go vet ./..., git diff --check PASS다.
  • Agent bridge 소형 항목 동기화(2026-06-14): 현재 Core 코드의 authoring.BuildAuthoringGenerateInput, OpenAI-compatible /v1/responses adapter, scheduler authoring route/state metadata, roadmapsync identity/develop match 기준을 근거로 [iop-http-channel], [authoring-state], [provider-identity], [agent-bridge-lock]을 완료 처리했다. 검증: cd services/core && go test -count=1 ./internal/authoring ./internal/scheduler ./internal/roadmapsync PASS. [agent-run-result]는 model bridge 응답 성공과 develop push 검증 사이의 성공 판정 경계를 보강해야 하므로 agent-task/m-milestone-work-item-creation-sync/08_agent_run_result_gate/ 계획으로 분리했다.
  • Agent run result gate 동기화(2026-06-14): agent-task/archive/2026/06/m-milestone-work-item-creation-sync/08_agent_run_result_gate/complete.log의 Roadmap Completion 근거로 [agent-run-result]를 완료 처리했다. 검증 근거는 DecideAuthoringResult helper, authoring failure category metadata, scheduler authoring state 보정, cd services/core && go test ./..., cd services/core && go vet ./..., git diff --check PASS다.
  • Creation sync 소형 항목 동기화(2026-06-14): 현재 Core 코드의 workitem.BuildCreateTaskInput, authoring.BuildAuthoringGenerateInput, scheduler authoring route, roadmapsync.MatchDevelopMilestone, ParseMilestoneIdentity, ProjectPlaneTodo, FormatPlaneProjection, roadmap sync identity/step store, ReconcileCreationCycle 근거로 [plane-agent-authoring], [develop-truth], [pushed-milestone-match], [plane-preserve], [plane-todo], [creation-idmap], [creation-retry]를 완료 처리했다. 검증: cd services/core && go test -count=1 ./internal/workitem ./internal/workitempipeline ./internal/authoring ./internal/roadmapsync ./internal/adapters/plane ./internal/storage ./internal/http ./internal/scheduler PASS, git diff --check PASS. 당시 남은 [plane-trigger], [plane-draft]는 후속 완료 로그 기준으로 아래 현황 동기화에서 닫았다.
  • Creation trigger/draft 현황 동기화(2026-06-14): agent-task/archive/2026/06/m-milestone-work-item-creation-sync/09_creation_trigger_gate/complete.log의 Roadmap Completion 근거로 [plane-trigger]를 완료 처리했다. 검증 근거는 ignored trigger를 workspace provision/slot reservation 전에 판정하는 gate, legacy Plane route trigger 전달 테스트, cd services/core && go test -count=1 ./internal/workitempipeline ./internal/http, cd services/core && go test ./..., git diff --check PASS다. agent-task/archive/2026/06/m-milestone-work-item-creation-sync/10+09_plane_draft_authoring/complete.log의 Roadmap Completion 근거로 [plane-draft]를 완료 처리했다. 검증 근거는 full provider identity context 보존, idempotent Milestone draft instructions, scheduler authoring route regression, cd services/core && go test -count=1 ./internal/authoring ./internal/roadmapsync ./internal/adapters/openai ./internal/scheduler, cd services/core && go test -count=1 ./..., git diff --check PASS다.
  • 완료 보완 리뷰(2026-06-14): 현재 Core 코드에는 roadmapsync helper와 저장소는 있으나 이를 호출해 develop scan 결과를 identity/step ledger와 Plane Todo projection에 연결하는 runtime sync orchestrator가 없다. 보완 계획: agent-task/m-milestone-work-item-creation-sync/11_creation_sync_orchestrator/.
  • Creation sync orchestrator 동기화(2026-06-14): agent-task/archive/2026/06/m-milestone-work-item-creation-sync/11_creation_sync_orchestrator/complete.log의 Roadmap Completion 근거로 [creation-sync-orchestrator]를 완료 처리했다. 검증 근거는 roadmapsyncpipeline.Service, optional RoadmapCreationSyncWorker, EnqueueRoadmapCreationSync seam, cd services/core && go test -count=1 ./..., cd services/core && go vet ./..., git diff --check PASS다.
  • 보완 리뷰(2026-06-15): 원격 Core dev 환경은 healthz/readyz, Plane secret/API env, active project sync 설정, branches/main, branches/develop, slots/000, available slot까지 준비 가능함을 확인했다. 그러나 현재 live로 바로 검증 가능한 범위는 Plane webhook 수신, trigger gate, Core task 생성, checkout metadata 기록까지다. Webhook task 자동 enqueue, authoring result와 develop push match의 runtime 연결, Plane Todo projection live smoke, slot terminal state 회수는 완료 전 보강 Task로 남긴다.
  • 검토 지점: project sync 설정, workspace topology, IOP Edge HTTP authoring run 경계, authoring run 성공/실패 판정, pushed Milestone identity match, Plane 원문 댓글 보존/본문·제목 갱신/Todo 이동 projection, identity map 기반 idempotency/retry, runtime orchestrator 연결은 unit/fake 기반 근거가 있으나, live/runtime-equivalent smoke evidence가 부족하다. [live-cycle-gate] 보완 전까지 [진행중]으로 유지한다.
  • 루프 목표: 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로 이동하는 지점까지다. 최상위 plane-nomad-iop-cycle 실행 단위는 아직 live completion 후보가 아니며, In Progress 이후 실행은 후속 잠금 범위다.
  • 후속 잠금: Todo -> In Progress 이후 실행 lifecycle은 사용자가 명시적으로 잠금을 해제할 때까지 진행하지 않는다.
  • Plane work item 경계: 이 마일스톤에서 말하는 Plane Milestone은 Plane native milestone object가 아니라 1상위 티켓 = 1 agent-roadmap Milestone으로 보는 work item mapping이다.
  • 확인 필요: 없음