From 1282c75815b046660b0dcc996d15a3963c95670a Mon Sep 17 00:00:00 2001 From: toki Date: Thu, 21 May 2026 20:48:40 +0900 Subject: [PATCH] =?UTF-8?q?refactor:=20agent-ops=20=EB=A1=9C=EB=93=9C?= =?UTF-8?q?=EB=A7=B5=20=EB=A7=88=EC=9D=BC=EC=8A=A4=ED=86=A4=20=ED=8C=8C?= =?UTF-8?q?=EC=9D=BC=EB=AA=85=20=EB=B3=80=EA=B2=BD=20=EB=B0=8F=20=EA=B5=AC?= =?UTF-8?q?=EC=A1=B0=20=EC=A0=95=EB=A6=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - milestones 디렉토리 파일명 M01- prefix에서 이름 중심 구조로 변경 - CLI automation baseline, structured automation surface 등 7개 마일스톤 파일 재구성 - ROADMAP.md, current.md, project rules.md 업데이트 - README.md 동기화 --- README.md | 8 ++-- agent-ops/roadmap/ROADMAP.md | 46 +++++++++---------- agent-ops/roadmap/current.md | 12 +++-- ...-protocol.md => agent-message-protocol.md} | 24 +++++----- ...baseline.md => cli-automation-baseline.md} | 26 +++++------ ...contract.md => edge-bootstrap-contract.md} | 22 ++++----- ...y.md => jenkins-compatibility-boundary.md} | 22 ++++----- ...istration.md => oto-agent-registration.md} | 24 +++++----- ...n-lifecycle.md => remote-run-lifecycle.md} | 24 +++++----- ...ce.md => structured-automation-surface.md} | 24 +++++----- agent-ops/rules/project/rules.md | 11 ++--- 11 files changed, 122 insertions(+), 121 deletions(-) rename agent-ops/roadmap/milestones/{M06-agent-message-protocol.md => agent-message-protocol.md} (82%) rename agent-ops/roadmap/milestones/{M01-cli-automation-baseline.md => cli-automation-baseline.md} (77%) rename agent-ops/roadmap/milestones/{M04-edge-bootstrap-contract.md => edge-bootstrap-contract.md} (90%) rename agent-ops/roadmap/milestones/{M03-jenkins-compatibility-boundary.md => jenkins-compatibility-boundary.md} (89%) rename agent-ops/roadmap/milestones/{M05-oto-agent-registration.md => oto-agent-registration.md} (83%) rename agent-ops/roadmap/milestones/{M07-remote-run-lifecycle.md => remote-run-lifecycle.md} (83%) rename agent-ops/roadmap/milestones/{M02-structured-automation-surface.md => structured-automation-surface.md} (92%) diff --git a/README.md b/README.md index 56e194e..bc058ae 100644 --- a/README.md +++ b/README.md @@ -243,10 +243,10 @@ README에는 장기 방향과 현재 위치만 유지한다. OTO의 장기 방향은 Jenkins 안에서 실행되는 CLI에 머물지 않고, Edge에 직접 붙는 가벼운 build/deploy agent까지 확장하는 것이다. -- 현재 위치: Phase 1. CLI 자동화 표면 정리 / M01 CLI 자동화 기준선 정리 -- Phase 1: 기존 CLI 실행 모드와 YAML 파이프라인, 커맨드 확장, 단일 바이너리 배포 구조를 장기 호환 표면으로 정리한다. -- Phase 2: Jenkins node 연결식 UX를 Edge bootstrap 기반 `oto-agent` 설치와 등록 계약으로 재해석한다. -- Phase 3: 메시지 기반 빌드 에이전트로 확장해 Edge가 OTO 파이프라인을 원격 제어할 수 있게 한다. +- 현재 위치: CLI 자동화 표면 정리 / CLI 자동화 기준선 정리 +- CLI 자동화 표면 정리: 기존 CLI 실행 모드와 YAML 파이프라인, 커맨드 확장, 단일 바이너리 배포 구조를 장기 호환 표면으로 정리한다. +- Edge bootstrap 기반 `oto-agent`: Jenkins node 연결식 UX를 Edge bootstrap 기반 `oto-agent` 설치와 등록 계약으로 재해석한다. +- 메시지 기반 빌드 에이전트: Edge가 OTO 파이프라인을 원격 제어할 수 있게 한다. --- diff --git a/agent-ops/roadmap/ROADMAP.md b/agent-ops/roadmap/ROADMAP.md index 8790f6c..bf74ca5 100644 --- a/agent-ops/roadmap/ROADMAP.md +++ b/agent-ops/roadmap/ROADMAP.md @@ -1,50 +1,50 @@ -# OTO Roadmap +# OTO 로드맵 -## Overall Goal +## 전체 목표 OTO는 YAML 기반 빌드/배포 파이프라인을 실행하는 Dart CLI에서 출발해, Jenkins 내부 실행 도구에 머물지 않고 Edge에 직접 연결되는 가벼운 build/deploy agent로 확장한다. 기존 CLI, YAML 파이프라인, 커맨드 확장 모델은 유지하면서 외부 자동화와 원격 제어가 다루기 쉬운 실행 표면을 만든다. -## Current Position +## 현재 활성 창 -- Active Phase: Phase 1. CLI 자동화 표면 정리 -- Active Milestone: M01 CLI 자동화 기준선 정리 -- Active Milestone File: `agent-ops/roadmap/milestones/M01-cli-automation-baseline.md` +- 활성 단계: CLI 자동화 표면 정리 +- 활성 Milestone: CLI 자동화 기준선 정리 +- 활성 Milestone 문서: `agent-ops/roadmap/milestones/cli-automation-baseline.md` -## Phase Overview +## 단계 개요 -### Phase 1. CLI 자동화 표면 정리 +### CLI 자동화 표면 정리 Jenkins, 파일 실행, 스케줄러로 동작하는 현재 CLI 표면을 장기 호환 경계로 정리한다. YAML 파이프라인, 커맨드 확장, 단일 바이너리 배포 구조를 OTO의 핵심 경계로 유지하면서 기존 command catalog와 YAML validation 기반을 외부 자동화용 계약으로 확장하고, 실행 결과와 step event를 구조화한다. Jenkins는 호환 실행 경로로 남기되 장기 제어면은 Jenkins 전용 환경 변수에 종속시키지 않는다. -### Phase 2. Edge bootstrap 기반 `oto-agent` +### Edge bootstrap 기반 `oto-agent` Edge에서 OTO agent를 생성하고 대상 머신에 bootstrap command를 발급하는 흐름을 설계한다. Jenkins node 연결식 UX를 Edge 중심 bootstrap 경험으로 재해석해, 대상 머신이 짧은 명령 하나로 agent 설치와 등록을 시작할 수 있게 한다. 대상 머신은 bootstrap command 실행만으로 OS/arch에 맞는 OTO 바이너리를 설치하고 agent 설정을 생성한다. HTTPS를 기본 권장하되 폐쇄망과 개발망을 위해 HTTP local/insecure 모드를 명시적으로 지원하고, TLS를 강제하지 않는 환경의 등록 보안 계약을 정의한다. -### Phase 3. 메시지 기반 빌드 에이전트 +### 메시지 기반 빌드 에이전트 `oto agent` 또는 `oto daemon` 모드에서 Edge와 proto-socket 기반 양방향 메시지 통신을 사용한다. OTO는 Edge 입장에서 build/deploy 전용 domain agent로 동작하며, YAML 파이프라인과 커맨드 확장 모델을 원격 제어 가능한 실행 표면으로 노출한다. -## Milestone Index +## Milestone 목록 -| ID | Phase | Status | File | Goal | -|----|-------|--------|------|------| -| M01 | Phase 1 | Active | `milestones/M01-cli-automation-baseline.md` | 현재 CLI 실행 모드와 핵심 호환 경계를 명확히 정리한다 | -| M02 | Phase 1 | Planned | `milestones/M02-structured-automation-surface.md` | 기존 catalog와 validation 기반을 외부 자동화용 출력 계약으로 확장한다 | -| M03 | Phase 1 | Planned | `milestones/M03-jenkins-compatibility-boundary.md` | Jenkins 호환 경로를 유지하면서 Jenkins 전용 환경 변수 의존을 제어한다 | -| M04 | Phase 2 | Planned | `milestones/M04-edge-bootstrap-contract.md` | Jenkins node 연결식 UX를 Edge bootstrap 설치/등록 계약으로 정리한다 | -| M05 | Phase 2 | Planned | `milestones/M05-oto-agent-registration.md` | `oto-agent` 설치 후 Edge 직접 outbound 등록 흐름을 구현 가능한 단위로 정리한다 | -| M06 | Phase 3 | Planned | `milestones/M06-agent-message-protocol.md` | agent register, capabilities, run request 등 기본 메시지 프로토콜을 정의한다 | -| M07 | Phase 3 | Planned | `milestones/M07-remote-run-lifecycle.md` | 원격 실행, 로그, artifact, cancel, status, self-update 생명주기를 완성한다 | +| 단계 | Milestone | 상태 | 문서 | 목표 | +|-------|-----------|------|------|------| +| CLI 자동화 표면 정리 | CLI 자동화 기준선 정리 | 진행 중 | `milestones/cli-automation-baseline.md` | 현재 CLI 실행 모드와 핵심 호환 경계를 명확히 정리한다 | +| CLI 자동화 표면 정리 | 구조화된 자동화 표면 | 계획 | `milestones/structured-automation-surface.md` | 기존 catalog와 validation 기반을 외부 자동화용 출력 계약으로 확장한다 | +| CLI 자동화 표면 정리 | Jenkins 호환 경계 정리 | 계획 | `milestones/jenkins-compatibility-boundary.md` | Jenkins 호환 경로를 유지하면서 Jenkins 전용 환경 변수 의존을 제어한다 | +| Edge bootstrap 기반 `oto-agent` | Edge bootstrap 계약 | 계획 | `milestones/edge-bootstrap-contract.md` | Jenkins node 연결식 UX를 Edge bootstrap 설치/등록 계약으로 정리한다 | +| Edge bootstrap 기반 `oto-agent` | `oto-agent` 등록 흐름 | 계획 | `milestones/oto-agent-registration.md` | `oto-agent` 설치 후 Edge 직접 outbound 등록 흐름을 구현 가능한 단위로 정리한다 | +| 메시지 기반 빌드 에이전트 | agent 메시지 프로토콜 | 계획 | `milestones/agent-message-protocol.md` | agent register, capabilities, run request 등 기본 메시지 프로토콜을 정의한다 | +| 메시지 기반 빌드 에이전트 | 원격 실행 생명주기 | 계획 | `milestones/remote-run-lifecycle.md` | 원격 실행, 로그, artifact, cancel, status, self-update 생명주기를 완성한다 | -## Loading Policy +## 로딩 정책 -- 일반 기능 추가, 구조 변경, 문서 구조 변경 작업에서는 `agent-ops/roadmap/current.md`를 먼저 읽고, 그 안의 Active Milestone 문서를 같은 세션에서 1회 읽는다. +- 일반 기능 추가, 구조 변경, 문서 구조 변경 작업에서는 `agent-ops/roadmap/current.md`를 먼저 읽고, 그 안의 활성 Milestone 문서를 같은 세션에서 1회 읽는다. - `agent-ops/roadmap/ROADMAP.md`는 로드맵 생성/갱신, Phase 전환, Milestone 추가/수정 요청이 있을 때만 읽는다. -- 작업 요청이 Active Milestone의 Goal 또는 Non-Goals와 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다. +- 작업 요청이 활성 Milestone의 목표 또는 범위 제외 항목과 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다. diff --git a/agent-ops/roadmap/current.md b/agent-ops/roadmap/current.md index 16c2d7e..873c6f3 100644 --- a/agent-ops/roadmap/current.md +++ b/agent-ops/roadmap/current.md @@ -1,9 +1,11 @@ # 현재 로드맵 컨텍스트 -- 현재 Phase: Phase 1. CLI 자동화 표면 정리 -- 기본 Milestone: M01 CLI 자동화 기준선 정리 -- 기본 Milestone 파일: agent-ops/roadmap/milestones/M01-cli-automation-baseline.md +## 활성 Milestone -## 진행 중인 Milestone +- CLI 자동화 기준선 정리: agent-ops/roadmap/milestones/cli-automation-baseline.md -- M01 CLI 자동화 기준선 정리: agent-ops/roadmap/milestones/M01-cli-automation-baseline.md +## 선택 규칙 + +- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 Milestone을 선택한다. +- 활성 Milestone 둘 이상에 걸치면 필요한 Milestone 문서를 모두 읽고 작업 범위를 좁힌다. +- 활성 Milestone 밖의 작업이면 `agent-ops/roadmap/ROADMAP.md`의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다. diff --git a/agent-ops/roadmap/milestones/M06-agent-message-protocol.md b/agent-ops/roadmap/milestones/agent-message-protocol.md similarity index 82% rename from agent-ops/roadmap/milestones/M06-agent-message-protocol.md rename to agent-ops/roadmap/milestones/agent-message-protocol.md index 1c385f7..6b5e573 100644 --- a/agent-ops/roadmap/milestones/M06-agent-message-protocol.md +++ b/agent-ops/roadmap/milestones/agent-message-protocol.md @@ -1,43 +1,43 @@ -# M06 agent 메시지 프로토콜 +# agent 메시지 프로토콜 -## Goal +## 목표 `oto agent` 또는 `oto daemon` 모드에서 Edge와 proto-socket 기반 양방향 메시지 통신을 하기 위한 기본 메시지 범위와 계약을 정의한다. -## Phase +## 단계 -Phase 3. 메시지 기반 빌드 에이전트 +메시지 기반 빌드 에이전트 -## Status +## 상태 -Planned +계획 -## Scope +## 범위 - agent register, capabilities, run request, step event, log stream, artifact event, cancel, status, self-update 메시지의 최소 필드를 정의한다. - 메시지 버전, 호환성, 에러 표현 방식을 정리한다. - OTO가 Edge의 build/deploy 전용 domain agent라는 경계를 명시한다. -## Required Features +## 필수 기능 - [ ] 기본 메시지 목록과 방향성이 정의되어 있다. - [ ] 각 메시지의 최소 필드와 실패 응답 형식이 정의되어 있다. - [ ] 프로토콜 버전과 capability 협상 기준이 정의되어 있다. - [ ] generic node 하위 실행물이 아니라는 제품 경계가 문서화되어 있다. -## Success Criteria +## 완료 기준 - Edge와 agent 구현자가 같은 메시지 계약을 기준으로 병렬 작업을 시작할 수 있다. - YAML 파이프라인과 커맨드 모델이 메시지 위에서 어떻게 호출되는지 설명된다. - 메시지 추가가 기존 CLI 실행 경로를 깨지 않는다는 경계가 명확하다. -## Non-Goals +## 범위 제외 - 웹 UI 또는 Edge 관리 화면을 구현하지 않는다. - 기존 YAML 파이프라인 형식을 대체하지 않는다. - 모든 운영 보안 정책을 완성하지 않는다. -## Context for Work +## 작업 컨텍스트 -- Phase 1의 구조화 실행 결과와 step event 기준을 먼저 확인한다. +- CLI 자동화 표면 정리 단계의 구조화 실행 결과와 step event 기준을 먼저 확인한다. - 프로토콜 파일이나 생성 코드가 추가되면 관련 도메인 rule 또는 새 도메인 rule 필요 여부를 검토한다. diff --git a/agent-ops/roadmap/milestones/M01-cli-automation-baseline.md b/agent-ops/roadmap/milestones/cli-automation-baseline.md similarity index 77% rename from agent-ops/roadmap/milestones/M01-cli-automation-baseline.md rename to agent-ops/roadmap/milestones/cli-automation-baseline.md index a2992d5..f33de98 100644 --- a/agent-ops/roadmap/milestones/M01-cli-automation-baseline.md +++ b/agent-ops/roadmap/milestones/cli-automation-baseline.md @@ -1,45 +1,45 @@ -# M01 CLI 자동화 기준선 정리 +# CLI 자동화 기준선 정리 -## Goal +## 목표 현재 OTO CLI가 제공하는 실행 모드와 핵심 확장 경계를 장기 호환 기준선으로 정리한다. -Phase 1의 나머지 작업이 기존 `-j`, `-f`, `scheduler` 흐름을 깨지 않고 구조화 출력과 검증 기능을 추가할 수 있게 만든다. +같은 단계의 나머지 작업이 기존 `-j`, `-f`, `scheduler` 흐름을 깨지 않고 구조화 출력과 검증 기능을 추가할 수 있게 만든다. -## Phase +## 단계 -Phase 1. CLI 자동화 표면 정리 +CLI 자동화 표면 정리 -## Status +## 상태 -Active +진행 중 -## Scope +## 범위 - 기존 `-j`, `-f`, `scheduler` 모드를 유지할 호환 표면으로 정리한다. - YAML 파이프라인, 커맨드 확장, 단일 바이너리 배포 구조를 OTO의 핵심 경계로 유지한다. - Jenkins는 현재 호환 실행 경로로 남기되, 이후 작업에서 제어면을 Jenkins 전용 환경 변수에 고정하지 않도록 기준을 세운다. - 현재 코드와 문서에 흩어진 실행 모드 설명을 기준선으로 삼아, 이후 구조화 출력과 agent 확장 작업의 변경 허용 범위를 정리한다. -## Required Features +## 필수 기능 - [ ] CLI 실행 모드별 책임과 호환 기준이 문서화되어 있다. - [ ] YAML 파이프라인과 커맨드 확장 모델이 핵심 경계로 명시되어 있다. - [ ] 단일 바이너리 배포 구조가 장기 유지 대상인지 확인되어 있다. - [ ] Jenkins 전용 환경 변수 의존을 확장 지점과 분리할 기준이 정리되어 있다. -## Success Criteria +## 완료 기준 - 새 기능을 추가할 때 어떤 CLI 동작을 깨면 안 되는지 빠르게 판단할 수 있다. -- Phase 1의 구조화 출력, YAML validation, Jenkins 의존성 완화 작업이 이 기준선을 참조해 진행될 수 있다. +- CLI 자동화 표면 정리 단계의 구조화 출력, YAML validation, Jenkins 의존성 완화 작업이 이 기준선을 참조해 진행될 수 있다. - README의 사용법 설명, CLI 구현, `agent-ops/roadmap/`의 상세 로드맵이 같은 실행 모드 경계를 가리킨다. -## Non-Goals +## 범위 제외 - `oto-agent` 프로세스나 Edge bootstrap 흐름을 구현하지 않는다. - proto-socket 메시지 프로토콜을 설계하거나 구현하지 않는다. - Jenkins 지원을 제거하지 않는다. -## Context for Work +## 작업 컨텍스트 - 먼저 `README.md`, `agent-ops/rules/project/rules.md`, `lib/oto/application.dart`, `lib/cli/**`의 현재 실행 모드 설명을 확인한다. - 코드 변경이 필요하면 관련 도메인 rule을 먼저 읽고, 변경 범위를 CLI 호환 경계 정리에 맞춘다. diff --git a/agent-ops/roadmap/milestones/M04-edge-bootstrap-contract.md b/agent-ops/roadmap/milestones/edge-bootstrap-contract.md similarity index 90% rename from agent-ops/roadmap/milestones/M04-edge-bootstrap-contract.md rename to agent-ops/roadmap/milestones/edge-bootstrap-contract.md index 5ae3b19..489c53b 100644 --- a/agent-ops/roadmap/milestones/M04-edge-bootstrap-contract.md +++ b/agent-ops/roadmap/milestones/edge-bootstrap-contract.md @@ -1,19 +1,19 @@ -# M04 Edge bootstrap 계약 +# Edge bootstrap 계약 -## Goal +## 목표 Jenkins node 연결식 UX를 Edge 중심 bootstrap 경험으로 재해석한다. Edge에서 OTO agent를 생성하고 대상 머신에서 실행할 bootstrap command를 발급하는 UX와 설치/등록 계약을 정의한다. -## Phase +## 단계 -Phase 2. Edge bootstrap 기반 `oto-agent` +Edge bootstrap 기반 `oto-agent` -## Status +## 상태 -Planned +계획 -## Scope +## 범위 - Jenkins node를 연결하듯 Edge에서 agent 생성과 bootstrap command 발급을 시작하는 사용자 흐름을 정의한다. - Edge가 발급하는 bootstrap command의 입력, 출력, 만료, 재시도 정책을 정의한다. @@ -21,7 +21,7 @@ Planned - agent 설정 파일 생성 위치와 최소 설정 값을 정의한다. - HTTPS 기본 권장, HTTP local/insecure 허용 범위, 폐쇄망 사용 조건을 구분한다. -## Required Features +## 필수 기능 - [ ] Edge에서 agent 생성 후 bootstrap command를 발급하는 사용자 흐름이 정의되어 있다. - [ ] bootstrap command 형식과 필수 인자가 정의되어 있다. @@ -29,20 +29,20 @@ Planned - [ ] agent 설정 생성 경로와 필수 설정 값이 정의되어 있다. - [ ] HTTPS, HTTP local, insecure 모드의 허용 조건이 문서화되어 있다. -## Success Criteria +## 완료 기준 - Jenkins node 연결식 경험과 비교해 사용자가 Edge bootstrap 흐름을 이해할 수 있다. - 사용자가 Edge에서 발급받은 command 하나로 대상 머신에 OTO agent 설치를 시작할 수 있는 흐름이 설명된다. - 보안 모드별 요구 사항과 위험이 구분되어 구현 전에 검토 가능하다. - 폐쇄망 배포와 개발망 테스트가 같은 계약 안에서 설명된다. -## Non-Goals +## 범위 제외 - 실제 Edge 서버 API를 구현하지 않는다. - 메시지 기반 run request 프로토콜을 구현하지 않는다. - iop-node 연동을 추가하지 않는다. -## Context for Work +## 작업 컨텍스트 - 기존 packaging 자료와 설치 스크립트(`assets/package/**`, `assets/script/**`)를 먼저 확인한다. - framework, cli 도메인 rule이 관련될 수 있다. diff --git a/agent-ops/roadmap/milestones/M03-jenkins-compatibility-boundary.md b/agent-ops/roadmap/milestones/jenkins-compatibility-boundary.md similarity index 89% rename from agent-ops/roadmap/milestones/M03-jenkins-compatibility-boundary.md rename to agent-ops/roadmap/milestones/jenkins-compatibility-boundary.md index 0dd68f4..d4b391e 100644 --- a/agent-ops/roadmap/milestones/M03-jenkins-compatibility-boundary.md +++ b/agent-ops/roadmap/milestones/jenkins-compatibility-boundary.md @@ -1,43 +1,43 @@ -# M03 Jenkins 호환 경계 정리 +# Jenkins 호환 경계 정리 -## Goal +## 목표 Jenkins 실행 경로를 유지하면서도 OTO의 장기 제어면이 Jenkins 전용 환경 변수와 실행 환경에 종속되지 않도록 경계를 정리한다. -## Phase +## 단계 -Phase 1. CLI 자동화 표면 정리 +CLI 자동화 표면 정리 -## Status +## 상태 -Planned +계획 -## Scope +## 범위 - Jenkins 환경 변수 파싱과 일반 파일 기반 실행 경로의 경계를 명확히 한다. - Jenkins는 호환 adapter로 유지하고, core pipeline 실행은 Jenkins 밖에서도 동일하게 동작하도록 정리한다. - scheduler와 file 모드가 장기 제어면의 기준 실행 경로로 쓰일 수 있는지 확인한다. -## Required Features +## 필수 기능 - [ ] Jenkins 환경 데이터 수집 책임이 분리되어 있다. - [ ] file 모드와 scheduler 모드가 Jenkins 없이 실행 가능한 경로로 검증되어 있다. - [ ] Jenkins 호환 유지 항목과 장기 의존 제거 후보가 구분되어 있다. - [ ] 문서에서 Jenkins 전용 경로와 일반 실행 경로가 혼동되지 않는다. -## Success Criteria +## 완료 기준 - Jenkins 없이도 OTO 파이프라인 실행 경로를 설명하고 테스트할 수 있다. - Jenkins 관련 변경이 core pipeline, command model, structured output에 불필요하게 전파되지 않는다. - Jenkins 지원을 제거하지 않고도 Edge agent 방향으로 확장할 수 있다. -## Non-Goals +## 범위 제외 - Jenkins 모드를 제거하지 않는다. - Jenkins plugin 또는 Jenkins UI 통합을 새로 만들지 않는다. - Edge bootstrap 구현을 포함하지 않는다. -## Context for Work +## 작업 컨텍스트 - `lib/oto/core/data_composer.dart`, `lib/oto/data/command_data.dart`, `lib/oto/application.dart`, `lib/cli/**`, Jenkins 샘플 YAML을 확인한다. - core, cli, sample 도메인 rule이 관련될 수 있다. diff --git a/agent-ops/roadmap/milestones/M05-oto-agent-registration.md b/agent-ops/roadmap/milestones/oto-agent-registration.md similarity index 83% rename from agent-ops/roadmap/milestones/M05-oto-agent-registration.md rename to agent-ops/roadmap/milestones/oto-agent-registration.md index 9b6e870..8123fd4 100644 --- a/agent-ops/roadmap/milestones/M05-oto-agent-registration.md +++ b/agent-ops/roadmap/milestones/oto-agent-registration.md @@ -1,44 +1,44 @@ -# M05 `oto-agent` 등록 흐름 +# `oto-agent` 등록 흐름 -## Goal +## 목표 설치된 `oto-agent`가 `iop-node`를 거치지 않고 Edge에 직접 outbound 연결하는 등록 흐름을 구현 가능한 단위로 정리한다. -## Phase +## 단계 -Phase 2. Edge bootstrap 기반 `oto-agent` +Edge bootstrap 기반 `oto-agent` -## Status +## 상태 -Planned +계획 -## Scope +## 범위 - one-time bootstrap token 검증 흐름을 정의한다. - Edge fingerprint 또는 public key pinning 기준을 정리한다. - 바이너리 checksum/signature 검증을 agent 등록 계약에 포함한다. - 설치 후 agent가 Edge에 직접 outbound 연결하는 최소 상태 전이를 정의한다. -## Required Features +## 필수 기능 - [ ] bootstrap token의 생성, 전달, 사용, 만료 흐름이 정의되어 있다. - [ ] Edge identity 검증 방식 후보가 정리되어 있다. - [ ] 바이너리 무결성 검증 기준이 정의되어 있다. - [ ] agent 등록 성공/실패 상태와 재시도 기준이 정의되어 있다. -## Success Criteria +## 완료 기준 - agent 등록 보안 계약이 TLS 강제 환경과 local/insecure 환경 모두에서 설명된다. - 설치 완료 후 Edge 직접 연결까지의 상태 전이가 구현 가능한 수준으로 분해되어 있다. - `iop-node`를 경유하지 않는다는 제품 경계가 명확하다. -## Non-Goals +## 범위 제외 - generic node agent 기능을 포함하지 않는다. - 원격 파이프라인 실행 메시지 전체를 구현하지 않는다. - 운영용 인증서 관리 시스템을 구현하지 않는다. -## Context for Work +## 작업 컨텍스트 -- Phase 2 작업 전에는 M04의 bootstrap 계약을 먼저 확인한다. +- Edge bootstrap 기반 `oto-agent` 작업 전에는 Edge bootstrap 계약을 먼저 확인한다. - 네트워크, 설치, packaging 관련 코드나 문서가 추가될 경우 관련 도메인 rule을 먼저 확인한다. diff --git a/agent-ops/roadmap/milestones/M07-remote-run-lifecycle.md b/agent-ops/roadmap/milestones/remote-run-lifecycle.md similarity index 83% rename from agent-ops/roadmap/milestones/M07-remote-run-lifecycle.md rename to agent-ops/roadmap/milestones/remote-run-lifecycle.md index a06d59e..e7a91b9 100644 --- a/agent-ops/roadmap/milestones/M07-remote-run-lifecycle.md +++ b/agent-ops/roadmap/milestones/remote-run-lifecycle.md @@ -1,44 +1,44 @@ -# M07 원격 실행 생명주기 +# 원격 실행 생명주기 -## Goal +## 목표 Edge가 OTO agent에 파이프라인 실행을 요청하고, agent가 실행 진행 상황과 산출물을 보고하며, 취소와 상태 조회, self-update까지 이어지는 원격 실행 생명주기를 완성한다. -## Phase +## 단계 -Phase 3. 메시지 기반 빌드 에이전트 +메시지 기반 빌드 에이전트 -## Status +## 상태 -Planned +계획 -## Scope +## 범위 - run request를 기존 YAML 파이프라인과 커맨드 확장 모델에 연결한다. - step event, log stream, artifact event를 원격 실행 흐름에 연결한다. - cancel, status, self-update의 최소 동작과 실패 기준을 정의한다. - agent 모드가 기존 CLI 실행 모델을 원격 제어 가능한 실행 표면으로 노출하게 한다. -## Required Features +## 필수 기능 - [ ] run request가 pipeline 실행 입력으로 변환되는 기준이 정의되어 있다. - [ ] step event와 log stream이 원격 소비자에게 전달되는 흐름이 정의되어 있다. - [ ] artifact event의 메타데이터와 전달 책임이 정의되어 있다. - [ ] cancel, status, self-update 동작 기준이 정의되어 있다. -## Success Criteria +## 완료 기준 - Edge에서 요청한 빌드/배포 작업의 시작, 진행, 완료, 실패, 취소 상태를 추적할 수 있다. - 기존 YAML 파이프라인과 커맨드 확장 모델을 유지하면서 원격 제어가 가능하다. - self-update가 agent 안정성을 해치지 않도록 최소 실패 기준이 있다. -## Non-Goals +## 범위 제외 - YAML 파이프라인 언어를 새 DSL로 교체하지 않는다. - generic remote shell agent로 확장하지 않는다. - Edge 서버의 전체 스케줄링 정책을 구현하지 않는다. -## Context for Work +## 작업 컨텍스트 -- M06 메시지 프로토콜과 Phase 1의 구조화 출력 기준을 먼저 확인한다. +- agent 메시지 프로토콜과 CLI 자동화 표면 정리 단계의 구조화 출력 기준을 먼저 확인한다. - pipeline, command, core 도메인 rule이 관련될 수 있다. diff --git a/agent-ops/roadmap/milestones/M02-structured-automation-surface.md b/agent-ops/roadmap/milestones/structured-automation-surface.md similarity index 92% rename from agent-ops/roadmap/milestones/M02-structured-automation-surface.md rename to agent-ops/roadmap/milestones/structured-automation-surface.md index fde6c9d..20b78bf 100644 --- a/agent-ops/roadmap/milestones/M02-structured-automation-surface.md +++ b/agent-ops/roadmap/milestones/structured-automation-surface.md @@ -1,52 +1,52 @@ -# M02 구조화된 자동화 표면 +# 구조화된 자동화 표면 -## Goal +## 목표 외부 자동화가 OTO를 안정적으로 호출하고 결과를 해석할 수 있도록, 이미 존재하는 command catalog와 YAML validation 기반을 외부 소비 가능한 출력 계약으로 확장한다. 아직 명확하지 않은 구조화된 실행 결과와 step event 계약을 함께 정리한다. -## Phase +## 단계 -Phase 1. CLI 자동화 표면 정리 +CLI 자동화 표면 정리 -## Status +## 상태 -Planned +계획 -## Scope +## 범위 - `Command.specs`와 `Command.catalogRows`를 command catalog의 내부 단일 진실 소스로 유지한다. - 기존 YAML build/pipeline validation 흐름을 외부 자동화가 호출하고 해석할 수 있는 계약으로 정리한다. - 실행 결과와 step event를 외부 도구가 파싱하기 쉬운 형태로 구조화한다. - 기존 사람이 읽는 로그 출력과 자동화용 구조화 출력의 관계를 정리한다. -## Existing Baseline +## 기존 기준선 - `Command.specs`와 `Command.catalogRows`가 등록된 커맨드의 내부 catalog 소스로 존재한다. - `Application.build()`와 `Pipeline.pipelineInitialize()` 경로에 YAML build/pipeline validation 흐름이 존재한다. - `BuildResult`는 성공 여부와 exit code를 표현하지만, 외부 자동화용 출력 envelope는 아직 별도 계약으로 정리되지 않았다. -## Required Features +## 필수 기능 - [ ] command catalog를 CLI 또는 다른 안정된 조회 경로로 노출하는 방식이 정의되어 있다. - [ ] YAML validation의 입력, 출력, 실패 기준이 외부 자동화용 계약으로 정의되어 있다. - [ ] 실행 결과의 성공/실패, exit code, 에러 정보 표현이 출력 envelope로 구조화되어 있다. - [ ] step event의 최소 필드와 발생 시점이 정의되어 있다. -## Success Criteria +## 완료 기준 - 외부 자동화가 내부 Dart API에 직접 의존하지 않고 command catalog를 조회할 수 있다. - 외부 자동화가 실행 전에 파이프라인 구성을 검증하고 실패 원인을 해석할 수 있다. - 외부 자동화가 실행 후 성공/실패와 실패 원인을 안정적으로 해석할 수 있다. - step 단위 진행 상황을 사람이 읽는 로그에만 의존하지 않고 소비할 수 있다. -## Non-Goals +## 범위 제외 - Edge agent 네트워크 프로토콜을 구현하지 않는다. - 웹 UI나 대시보드를 만들지 않는다. - 기존 YAML 커맨드 모델을 대체하지 않는다. -## Context for Work +## 작업 컨텍스트 - `lib/oto/commands/command.dart`, `lib/oto/commands/command_registry.dart`, `lib/oto/core/build_result.dart`, `lib/oto/pipeline/**`, `assets/yaml/sample/**`를 우선 확인한다. - 기존 구현 근거는 `Command.specs`, `Command.catalogRows`, `Application.build()`의 validation 흐름, `BuildResult`다. diff --git a/agent-ops/rules/project/rules.md b/agent-ops/rules/project/rules.md index 5b13f7a..16729e2 100644 --- a/agent-ops/rules/project/rules.md +++ b/agent-ops/rules/project/rules.md @@ -97,13 +97,12 @@ lib/ ## 마일스톤 컨텍스트 로딩 - 기능 추가, 구조 변경, 스킬 추가/수정, 문서 구조 변경 작업을 수행할 때는 `agent-ops/roadmap/current.md`를 먼저 읽는다. -- 요청이 기본 Milestone 범위에 맞으면 기본 Milestone 문서를 같은 세션에서 1회 읽는다. -- 요청이 기본 Milestone과 맞지 않으면 `current.md`의 진행 중인 Milestone 목록에서 가장 관련 있는 Milestone 문서를 같은 세션에서 1회 읽는다. -- 진행 중인 Milestone에도 맞지 않는 요청은 무리하게 Milestone에 끼워 넣지 않는다. - - 버그 수정, 테스트 보강, 작은 문서 수정, 기존 기능 유지보수처럼 제품 방향을 바꾸지 않는 작업은 관련 domain rule만 적용하고 진행한다. - - 새 기능, 구조 변경, 장기 방향에 영향을 주는 작업이면 `agent-ops/roadmap/ROADMAP.md`의 Milestone 인덱스를 확인하고, 로드맵 밖 작업으로 진행할지 또는 로드맵을 갱신할지 사용자에게 확인한다. +- `current.md`는 현재 작업 위치가 아니라 활성 Milestone 후보 목록이다. +- 요청 내용, 현재 브랜치, 변경 파일, 관련 코드 경로를 보고 가장 관련 있는 활성 Milestone 문서를 같은 세션에서 1회 읽는다. +- 요청이 활성 Milestone 둘 이상에 걸치면 필요한 Milestone 문서를 모두 읽고 작업 범위를 좁힌다. +- 활성 Milestone 밖의 작업이면 `agent-ops/roadmap/ROADMAP.md`의 Milestone 목록을 확인하고 사용자에게 진행 또는 전환 여부를 확인한다. - `agent-ops/roadmap/ROADMAP.md`는 로드맵 생성/갱신, Phase 전환, Milestone 추가/수정 요청이 있을 때만 읽는다. -- 작업 요청이 선택된 Milestone의 Goal 또는 Non-Goals와 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다. +- 작업 요청이 선택된 Milestone의 목표 또는 범위 제외 항목과 충돌하면 구현 전에 사용자에게 알리고 방향을 확인한다. ## 도메인 매핑