iop/agent-ops/rules/project/domain/agent/rules.md

domain	last_rule_review_commit	last_rule_updated_at
agent	none	2026-07-29

agent

목적 / 책임

개인 장비의 소유 OS 사용자 범위에서 독립 실행되는 agent daemon/CLI 애플리케이션 영역이다. apps/agent는 독립 호스트 구성과 호스트 소유 어댑터, 커맨드 프레젠테이션, 로컬 소켓/클라이언트 프로세스 제어, 프로젝트 로그 기록을 담당하며 공유 런타임 알고리즘을 재구현하거나 소유하지 않는다. 공통 프로바이더 실행, 셀렉터/쿼터/계속성 정책, AgentTaskManager Orchestration, guardrail 가드, 작업 공간/오버레이 관리, 리뷰/통합 및 영구 상태는 packages/go/ 이하 공통 패키지가 소유하고, Node protobuf 변환은 apps/node/internal/node/runtime_bridge.go가 소유한다.

포함 경로

• apps/agent/cmd/agent/ — agent CLI 진입점과 서브커맨드 프레젠테이션
• apps/agent/internal/command/ — 호스트 커맨드 파싱, 서브커맨드 라우팅, 프레젠테이션 포맷터 어댑터
• apps/agent/internal/host/ — 호스트 프로세스 설정, 환경 바인딩, 호스트 레벨 초기화 어댑터
• apps/agent/internal/bootstrap/ — fx 의존성 주입과 독립 daemon/host 시작 및 종료 lifecycle 어댑터
• apps/agent/internal/taskloop/ — 공통 런타임 포트와 프로젝트 아티팩트를 조립하는 standalone task loop 어댑터
• apps/agent/internal/projectlog/ — 호스트 소유 프레젠테이션 로그 및 디스플레이 스트림 어댑터
• apps/agent/internal/localcontrol/ — same-OS-user local proto-socket server 어댑터 및 로컬 제어 엔드포인트
• apps/agent/internal/clientprocess/ — Flutter·Unity subprocess lifecycle, crash auto-restart, UI relay 호스트 어댑터
• apps/agent/README.md — agent daemon 실행 흐름과 경계 설명

제외 경로

• apps/node/internal/node/runtime_bridge.go — Node가 공통 runtime을 소비하는 protobuf runtime bridge 위치
• apps/node/** — Edge에 연결되어 adapter execution을 수행하는 Node 에이전트 영역
• apps/edge/** — 여러 Node를 묶는 백엔드 실행 그룹 컨트롤러 영역
• apps/control-plane/** — 여러 Edge 연결 관리와 운영 제어 API 제공 영역
• apps/client/** — Control Plane을 통해 Edge/Node 운영 상태를 보여주는 Flutter client
• packages/go/agentconfig/ — repo-global read-only YAML 및 local override 공유 패키지
• packages/go/agentprovider/ — 공유 프로바이더 discovery, catalog, readiness 및 CLI 실행 구현
• packages/go/agentpolicy/ — 공유 selector evaluator, quota observation, continuation decision 정책 구현
• packages/go/agenttask/ — 공유 AgentTaskManager implementation, state transition, dispatch, review, integration orchestration
• packages/go/agentguard/ — 공유 workspace grant, containment, permit admission 및 executable confinement proof
• packages/go/agentworkspace/ — 공유 OverlayWorkspace, Snapshot, isolation backend 구현
• packages/go/agentstate/ — 공유 lease, checkpoint, durable store 및 state recovery 구현
• packages/go/agentruntime/ — Node와 standalone host가 공유하는 host-neutral agent runtime contract/interface
• packages/go/의 나머지 영역 — 여러 앱이 공유하는 Go 공통 패키지
• proto/ — 앱 간 메시지 계약
• scripts/dev/**, scripts/e2e-*.sh, scripts/fixtures/** — 테스트/진단 영역

주요 구성 요소

• command.Runner — 서브커맨드 입출력 해석 및 런타임 포트 바인딩 어댑터
• host.Config — 호스트 환경 레벨 초기화 설정 및 디바이스 바인딩
• bootstrap.Container — DI 주입 및 독립 daemon 시작/종료 호스트 wire
• taskloop.Adapter — 공통 agenttask.Manager 포트와 프로젝트 아티팩트를 조립하는 호스트 런타임 루프
• projectlog.Writer — 프로젝트 프레젠테이션 로그 기록 및 디스플레이 이벤트 전달 어댑터
• localcontrol.Server — same-OS-user local proto-socket server 어댑터 및 호스트 제어 경계
• clientprocess.Manager — Flutter·Unity subprocess lifecycle 관리, crash auto-restart, UI 명령 중계 호스트 구현

유지할 패턴

• agent는 독립 daemon/host 애플리케이션이다. 호스트 진입점으로 시작하고 device singleton lease를 획득한 뒤 project watcher와 provider discovery를 활성화한다.
• repo-global 설정 (configs/ 아님, runtime이 읽기만 하는 versioned YAML)은 비밀정보 없는 provider/default/selection policy template의 source of truth이다. runtime은 repo-global 설정을 쓰지 않으며, local override와 checkpoint만 갱신한다.
• user-local config/state root은 소유 OS 사용자의 local config/state 디렉터리에 위치한다. project registry, canonical workspace grant, 장비 경로, provider 실행 참조, project override, 자동 재개, client launch 설정과 versioned checkpoint/lease가 여기에 저장된다.
• 같은 OS 사용자 local proto-socket client는 별도 app token 없이 신뢰한다. 다른 사용자 접근은 거부한다.
• Flutter·Unity는 agent 호스트가 소유 subprocess로 시작·중단·복구한다. Flutter·Unity는 서로 직접 통신하거나 host를 직접 시작·종료하지 않는다. Unity의 상세 UI 요청은 Flutter start/focus command로 중계한다.
• Node는 공통 library consumer이지 두 번째 supervisor가 아니다. Node 내부에서 provider 또는 AgentTaskManager 구현을 복사하지 않는다.
• provider authentication과 credential은 각 CLI가 소유한다. agent는 discovery, status, unattended/approval-bypass capability, 실행과 cancel만 확인하며 인증을 소유하지 않는다.
• 새 Milestone 선택·최초 시작은 항상 수동이다. 시작 기록이 있는 중단 작업의 자동 재개만 기본 on이며 auto_resume_interrupted local 설정으로 조정한다.
• explicit predecessor만 dependency로 사용한다. 숫자 순서에서 의존성을 추론하지 않는다.
• dependency-ready task는 동일 pinned base 위의 독립 COW writable layer에서 실행한다. canonical base를 직접 쓰지 않으며, build/temp/cache 출력을 공용 mutable path에 기록해 다른 실행과 섞지 않는다.
• review PASS change set은 dispatch ordinal 순서로 serial integration한다. clean three-way merge는 자동 승인하고 conflict·검증 실패·관리되지 않은 base drift는 overlay를 보존한 task-local blocker가 된다.
• shared-checkout write claim은 worker·selfcheck·official review·follow-up 전체 lifecycle 동안 원자적으로 유지·이관·해제한다. verified completion 또는 task mutation의 안전한 정리와 live owner 부재 전에는 release하지 않는다.
• file claim은 disjoint target의 build/test 격리를 보장하지 않는다. final verification은 다른 active mutation이 없는 stable source 또는 격리 workspace에서 다시 수행한다.
• workspace grant의 mutation 범위는 canonical project root과 명시된 VCS metadata root뿐이다. 외부 서비스 mutation이나 다른 project 권한을 포함하지 않는다.
• provider별 session/conversation 상태는 packages/go/agentprovider/cli 내부에 두고 공통 agentruntime interface에는 host-neutral 의미만 노출한다.
• config refresh는 현재 실행 snapshot을 유지하고 다음 agent 호출부터 새 revision을 적용한다.
• malformed checkpoint/route/locator를 빈 상태나 현재 정책으로 조용히 초기화·재선택하지 않는다. 추정 복구 없이 blocker/error로 처리한다.
• RuntimeEvent는 execution/attempt, project/work-unit/stage, overlay/change-set/integration lifecycle, stream/heartbeat, config/quota reference와 terminal result를 유지한다.
• PlanWriteSet은 active PLAN의 정확히 하나인 Modified Files Summary 첫 번째 column에서 읽은 backtick file path 집합이다. glob, workspace root·directory와 containment 밖 경로를 거부한다.
• Node bridge는 기존 Edge-Node wire 의미(RunRequest/RunEvent, cancel, command)와 provider behavior를 보존한다. Node 내부에 duplicate provider를 만들지 않는다.
• 내 변경은 가능한 대상 패키지 테스트를 먼저 추가하거나 갱신한다.
• apps/agent/internal/localcontrol/**의 same-user/other-user 경계를 바꾼 뒤에는 testing domain rule의 작업 후 검증 기준을 따른다.

다른 도메인과의 경계

• node: node는 Edge에 연결되어 adapter execution을 수행한다. node는 packages/go/agentruntime과 packages/go/agentprovider/cli를 소비하는 얇은 bridge일 뿐이며, provider 또는 AgentTaskManager 구현을 자체적으로 소유하지 않는다. Node protobuf 변환은 apps/node/internal/node/runtime_bridge.go가 소유한다.
• edge: edge는 node 연결 등록, adapter/runtime 설정 전달, 라우팅 진입, stream relay를 담당한다. agent는 edge를 직접 연결/스케줄링하지 않으며, edge의 설정/상태 원본을 참조하지 않는다.
• platform-common: packages/go/agentruntime, packages/go/agentprovider/cli, packages/go/agentconfig, packages/go/agentprovider, packages/go/agentpolicy, packages/go/agenttask, packages/go/agentguard, packages/go/agentworkspace, packages/go/agentstate, config/events/observability와 proto 생성물은 여러 앱이 공유하는 공통 패키지이다. agent는 이 공통 구현을 소비하고 host-specific wire, command, lifecycle adapter만 소유한다.
• client: client는 Control Plane을 통해 Edge/Node 운영 상태를 보여주는 Flutter client이다. agent는 Flutter를 subprocess로 소유하지만 client UI 로직을 소유하지 않는다.

금지 사항

• node 또는 edge에 provider 또는 AgentTaskManager 구현을 복사하지 않는다.
• Python process, function name, marker와 persisted key를 production 계약으로 가져오지 않는다.
• parity matrix와 Go 대체 evidence가 고정되기 전에 Python 참조 구현을 폐기하거나, Milestone 완료 뒤 production/fallback 경로로 남기지 않는다.
• malformed checkpoint/route/locator를 빈 상태나 현재 정책으로 조용히 초기화·재선택하지 않는다.
• Flutter·Unity가 provider 선택, task scheduling, retry/failover 또는 project state를 다시 소유하지 않도록 한다.
• worker exit code나 완료 문구만으로 review-ready/completed를 확정하지 않는다.
• runtime이 repo-global 설정이나 project 작업 파일에 장비 경로·checkpoint·client process 상태를 기록하지 않는다.
• Flutter·Unity가 daemon이나 서로를 직접 시작·종료하지 않는다.
• 같은 OS 사용자 밖의 client를 app token 없이 신뢰하지 않는다.
• runtime WORK_LOG/heartbeat 변화만 review progress로 세지 않는다.
• 등록되지 않았거나 canonical containment를 벗어난 workspace에서 agent를 호출하지 않는다.
• unattended/approval-bypass와 workspace scope guardrail 중 하나라도 검증되지 않은 provider/profile을 대화형 승인 fallback으로 호출하지 않는다.
• workspace grant를 외부 서비스 mutation, 다른 project 또는 임의 장비 경로의 포괄 승인으로 확장하지 않는다.
• 병렬 task process가 canonical workspace file, 공용 Git index/ref 또는 다른 task writable layer를 직접 변경하지 않는다.
• review PASS와 change-set validation 전 결과를 canonical base에 적용하거나, 완료 속도에 따라 integration 순서를 바꾸지 않는다.
• 관리되지 않은 base drift에 blind apply하거나 merge conflict를 자동 overwrite하지 않는다.
• durable IntegrationRecord와 blocker evidence 전에 overlay를 삭제하지 않는다.
• 한 change set의 terminal-deferred blocker로 뒤의 independent integration queue를 멈추지 않는다.
• shared checkout에서 valid write claim 전체를 얻기 전에 worker/selfcheck/official review를 시작하거나, Modified Files Summary의 교집합을 명시 predecessor나 roadmap dependency로 변환하지 않는다.
• PLAN target을 LLM으로 추출·보정하거나 누락·중복·빈 값·glob·workspace 밖·directory target을 empty/disjoint write-set으로 간주하지 않는다.
• model process 종료, WARN/FAIL review 또는 dispatcher restart만으로 claim을 해제하지 않는다.
• shared-checkout compatibility claim을 독립 COW writable layer, 격리 worktree 또는 full clone 사이의 논리적 dependency나 병렬 실행 금지로 확장하지 않는다.
• file write-set이 disjoint하다는 이유만으로 shared checkout의 build/test 결과를 task-isolated evidence로 간주하지 않는다.
• gRPC, WebSocket 기본 transport, actor/FSM/plugin framework를 새 기본 구조로 도입하지 않는다.
• proto/gen/iop/*.pb.go 생성 파일을 직접 수정하지 않는다.