oto/agent-ops/roadmap/milestones/structured-automation-surface.md

구조화된 자동화 표면

목표

외부 자동화가 OTO를 안정적으로 호출하고 결과를 해석할 수 있도록, 이미 존재하는 command catalog와 YAML validation 기반을 외부 소비 가능한 출력 계약으로 확장한다. 아직 명확하지 않은 구조화된 실행 결과와 step event 계약을 함께 정리한다.

단계

CLI 자동화 표면 정리

상태

진행 중

범위

• Command.specs와 Command.catalogRows를 command catalog의 내부 단일 진실 소스로 유지한다.
• 기존 YAML build/pipeline validation 흐름을 외부 자동화가 호출하고 해석할 수 있는 계약으로 정리한다.
• 실행 결과와 step event를 외부 도구가 파싱하기 쉬운 형태로 구조화한다.
• 기존 사람이 읽는 로그 출력과 자동화용 구조화 출력의 관계를 정리한다.

필수 기능

• command catalog를 CLI 또는 다른 안정된 조회 경로로 노출하는 방식이 정의되어 있다. (oto catalog CLI 추가로 달성)
• YAML validation의 입력, 출력, 실패 기준이 외부 자동화용 계약으로 정의되어 있다.
• 실행 결과의 성공/실패, exit code, 에러 정보 표현이 출력 envelope로 구조화되어 있다.
• step event의 최소 필드와 발생 시점이 정의되어 있다.

완료 기준

• 외부 자동화가 내부 Dart API에 직접 의존하지 않고 command catalog를 조회할 수 있다.
• 외부 자동화가 실행 전에 파이프라인 구성을 검증하고 실패 원인을 해석할 수 있다.
• 외부 자동화가 실행 후 성공/실패와 실패 원인을 안정적으로 해석할 수 있다.
• step 단위 진행 상황을 사람이 읽는 로그에만 의존하지 않고 소비할 수 있다.

범위 제외

• Edge agent 네트워크 프로토콜을 구현하지 않는다.
• 웹 UI나 대시보드를 만들지 않는다.
• 기존 YAML 커맨드 모델을 대체하지 않는다.

작업 컨텍스트

• 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다.
• command, pipeline, sample 도메인 rule이 관련될 수 있다.
• 기존 기준선:
  • Command.specs와 Command.catalogRows가 등록된 커맨드의 내부 catalog 소스로 존재한다.
  • Application.build()와 Pipeline.pipelineInitialize() 경로에 YAML build/pipeline validation 흐름이 존재한다.
  • BuildResult는 성공 여부와 exit code를 표현하지만, 외부 자동화용 출력 envelope는 아직 별도 계약으로 정리되지 않았다.