diff --git a/agent-ops/rules/project/domain/contracts/rules.md b/agent-ops/rules/project/domain/contracts/rules.md index 0daba9b..600363f 100644 --- a/agent-ops/rules/project/domain/contracts/rules.md +++ b/agent-ops/rules/project/domain/contracts/rules.md @@ -1,7 +1,7 @@ --- domain: contracts -last_rule_review_commit: e3b5dae725db62dd7a47c563abcce557e0557551 -last_rule_updated_at: 2026-05-21 +last_rule_review_commit: 03187a4be3d9864419221d14bb44b8bc6645e6f1 +last_rule_updated_at: 2026-05-31 --- # contracts @@ -13,6 +13,7 @@ NomadCode 런타임 사이의 공유 계약 도메인이다. API schema, event s ## 포함 경로 - `packages/contracts/` — OpenAPI/protobuf/schema, generated clients, fixtures, compatibility notes. +- `packages/contracts/notes/` — source schema 승격 전 core/client 계약 후보와 compatibility note. ## 제외 경로 @@ -23,6 +24,7 @@ NomadCode 런타임 사이의 공유 계약 도메인이다. API schema, event s ## 주요 구성 요소 - `packages/contracts/README.md` — 현재 contracts 도메인의 역할과 사용 방향. +- `packages/contracts/notes/flutter-core-api-candidates.md` — Flutter/Core REST compatibility map, proto-socket semantic envelope, task channel, diagnostics, workspace metadata, client integration 설정 후보. ## 유지할 패턴 @@ -30,11 +32,13 @@ NomadCode 런타임 사이의 공유 계약 도메인이다. API schema, event s - breaking change는 core와 Flutter 앱 반영을 같은 branch에서 조율한다. - schema가 추가되면 sample payload나 compatibility note를 함께 둔다. - generated client가 생기면 생성 명령과 source schema를 문서화한다. +- 내부 런타임 통신은 `proto-socket` channel/action을 우선 기준으로 삼고, REST/HTTP 유지나 신규 추가는 health/readiness, 외부 provider compatibility, smoke/curl, public callback, 단순 정적 조회 같은 예외 사유를 기록한다. +- source schema가 아직 없는 계약은 compatibility note로 표시하고, 실제 schema/generator 도입 전까지 단일 source-of-truth인 것처럼 다루지 않는다. ## 다른 도메인과의 경계 -- **core**: contracts는 API shape의 source-of-truth이고 core는 이를 구현한다. -- **mobile**: mobile은 contracts를 소비하되 platform behavior는 mobile 도메인에서 다룬다. +- **core**: contracts는 API/proto-socket 의미 계약의 source-of-truth 후보를 관리하고 core는 이를 구현한다. +- **mobile**: mobile은 contracts를 소비하되 platform behavior와 connector lifecycle은 mobile 도메인에서 다룬다. - **web**: [Legacy/Retired] React web 도메인은 완전히 제거되었습니다. - **workspace-ops**: contracts 생성/검증 명령이 root script가 되면 workspace-ops와 함께 갱신한다. @@ -43,3 +47,4 @@ NomadCode 런타임 사이의 공유 계약 도메인이다. API schema, event s - 구현 코드의 임시 type을 contracts로 승격하지 않는다. - 실제 소비자가 없는 schema를 과도하게 선행 설계하지 않는다. - generated output만 수정하고 source schema를 누락하지 않는다. +- compatibility note의 후보 계약을 실제 source schema와 혼동하지 않는다. diff --git a/agent-ops/rules/project/domain/core/rules.md b/agent-ops/rules/project/domain/core/rules.md index 18ec00b..e226895 100644 --- a/agent-ops/rules/project/domain/core/rules.md +++ b/agent-ops/rules/project/domain/core/rules.md @@ -1,6 +1,6 @@ --- domain: core -last_rule_review_commit: 092be9dad94f22e497cf4c083681581ab52ffdc1 +last_rule_review_commit: 03187a4be3d9864419221d14bb44b8bc6645e6f1 last_rule_updated_at: 2026-05-31 --- @@ -8,11 +8,11 @@ last_rule_updated_at: 2026-05-31 ## 목적 / 책임 -NomadCode의 백엔드 오케스트레이션 도메인이다. workflow, scheduling, persistence, HTTP API, 외부 서비스 adapter를 통해 AI 작업 실행 상태와 자동화 흐름을 관리한다. +NomadCode의 백엔드 오케스트레이션 도메인이다. workflow, scheduling, persistence, HTTP/proto-socket API, work item intake, 외부 서비스 adapter를 통해 AI 작업 실행 상태와 자동화 흐름을 관리한다. ## 포함 경로 -- `services/core/cmd/` — 서버 실행 entrypoint. +- `services/core/cmd/` — 서버와 Plane smoke 실행 entrypoint. - `services/core/internal/agent/` — agent 모델과 실행 단위. - `services/core/internal/config/` — 환경 변수 기반 core 설정 로딩. - `services/core/internal/model/` — 모델 호출 추상 인터페이스와 입출력 타입. @@ -20,6 +20,9 @@ NomadCode의 백엔드 오케스트레이션 도메인이다. workflow, scheduli - `services/core/internal/scheduler/` — River 기반 작업 스케줄링과 job 정의. - `services/core/internal/notification/` — task notification 모델과 발행 서비스. - `services/core/internal/http/` — HTTP router, handlers, middleware. +- `services/core/internal/protosocket/` — proto-socket envelope, dispatcher, server, task channel, event broadcaster. +- `services/core/internal/workitem/` — provider-neutral work item reference, capability, projection, task input mapping. +- `services/core/internal/workitempipeline/` — 외부 work item을 core task로 변환하는 pipeline service. - `services/core/internal/db/` — SQLC 생성 코드, DB pool, persistence 모델. - `services/core/internal/storage/` — 저장소 abstraction. - `services/core/internal/adapters/` — OpenAI, A2A, Mattermost, Plane 등 외부 통합. @@ -36,16 +39,26 @@ NomadCode의 백엔드 오케스트레이션 도메인이다. workflow, scheduli ## 주요 구성 요소 +- `cmd/server/main.go` — core server wiring과 adapter/proto-socket 조립. +- `cmd/plane-smoke/main.go` — Plane lookup/comment/status projection smoke runner. - `internal/http/router.go` — HTTP route 조립. -- `internal/http/handlers.go` — API handler. +- `internal/http/handlers.go` — task API와 Plane work item intake handler. - `internal/config/config.go` — 환경 변수 기반 설정 로딩. - `internal/model/model.go` — 모델 client interface와 generation DTO. - `internal/scheduler/river.go` — River scheduler 연결. - `internal/scheduler/jobs.go` — background job 정의. - `internal/notification/service.go` — task 완료 notification 발행. +- `internal/protosocket/server.go` — proto-socket WebSocket server, heartbeat, diagnostics logging, broadcast. +- `internal/protosocket/dispatcher.go` — channel/action dispatch registry. +- `internal/protosocket/envelope.go` — `nomadcode.proto-socket.v1` semantic envelope 변환. +- `internal/protosocket/tasks.go` — `task.create/list/get/enqueue` proto-socket channel handlers. +- `internal/protosocket/events.go` — notification event를 `task.status.changed` event로 투영. - `internal/adapters/openai/client.go` — OpenAI integration. - `internal/adapters/a2a/client.go` — A2A integration. +- `internal/adapters/mattermost/client.go` — Mattermost task notification integration. - `internal/adapters/plane/client.go` — Plane work item 조회, comment 생성, state update integration. +- `internal/workitem/provider.go` — provider-neutral work item abstraction과 task input mapping. +- `internal/workitempipeline/service.go` — work item reader와 workflow task creator 연결. - `internal/db/tasks.sql.go` — SQLC generated query boundary. ## Plane dev 작업 메모 @@ -71,6 +84,10 @@ NomadCode의 백엔드 오케스트레이션 도메인이다. workflow, scheduli - Go package 경계는 `internal/` 단위로 유지한다. - DB 변경은 migration, query, generated code, test를 함께 갱신한다. - 외부 서비스 호출은 `internal/adapters/` 아래에 격리한다. +- provider-neutral work item 계약은 `internal/workitem`에 두고, Plane/Jira 같은 provider별 HTTP/DTO 세부는 adapter 아래에 둔다. +- work item을 core task로 만드는 흐름은 `internal/workitempipeline`에서 조립하고, workflow service에 provider별 DTO를 직접 넣지 않는다. +- 신규 내부 런타임 통신은 `proto-socket` channel/action을 우선 검토하고, REST/HTTP 예외는 health/readiness, smoke/curl, 외부 provider 호환 API처럼 사유가 분명할 때 contracts 또는 domain rule에 남긴다. +- proto-socket envelope diagnostics에는 connection id, protocol version, channel/action, error code, timestamp 같은 운영 필드만 남기고 secret이나 payload 원문을 로그에 싣지 않는다. - 환경 변수 기본값과 alias는 `internal/config`에서 관리하고 README의 실행 예시와 어긋나지 않게 유지한다. - scheduler 변경은 가능한 한 job 단위 테스트를 추가한다. - HTTP API 변경은 Flutter 앱 영향과 contracts 반영 필요성을 함께 판단한다. @@ -79,8 +96,8 @@ NomadCode의 백엔드 오케스트레이션 도메인이다. workflow, scheduli ## 다른 도메인과의 경계 -- **contracts**: API shape가 클라이언트와 공유되면 contracts에 먼저 표현하거나 문서화한다. -- **mobile**: mobile은 public API와 notification/auth 계약만 의존한다. +- **contracts**: API, proto-socket envelope/channel/action, diagnostics 의미가 클라이언트와 공유되면 contracts에 먼저 표현하거나 compatibility note로 문서화한다. +- **mobile**: mobile은 public API, proto-socket semantic envelope, notification/auth 계약만 의존하며 core 내부 패키지를 직접 참조하지 않는다. - **web**: [Legacy/Retired] React web 도메인은 완전히 제거되었습니다. - **workspace-ops**: root helper 변경은 workspace-ops 소유이고, core-local bin 변경만 core 소유다. @@ -88,5 +105,6 @@ NomadCode의 백엔드 오케스트레이션 도메인이다. workflow, scheduli - `apps/**`의 UI 상태나 라우팅을 core 변경에 끼워 넣지 않는다. - 외부 provider별 세부 구현을 workflow/service 레이어에 직접 흘리지 않는다. +- proto-socket payload를 임의 map indexing으로 여기저기 해석하지 말고 envelope/channel boundary에서 typed DTO로 변환한다. - SQLC 생성 파일만 수동 수정하지 않는다. - 테스트 없이 scheduler, persistence, adapter behavior를 크게 바꾸지 않는다. diff --git a/agent-ops/rules/project/domain/mobile/rules.md b/agent-ops/rules/project/domain/mobile/rules.md index d30de31..81824e3 100644 --- a/agent-ops/rules/project/domain/mobile/rules.md +++ b/agent-ops/rules/project/domain/mobile/rules.md @@ -1,6 +1,6 @@ --- domain: mobile -last_rule_review_commit: 092be9dad94f22e497cf4c083681581ab52ffdc1 +last_rule_review_commit: 03187a4be3d9864419221d14bb44b8bc6645e6f1 last_rule_updated_at: 2026-05-31 --- @@ -17,6 +17,7 @@ NomadCode의 Flutter-first 제품 UI 도메인이다. 모바일/데스크톱/선 - `apps/client/lib/src/features/` — product feature UI and local feature state. - `apps/client/lib/src/integrations/` — Mattermost, proto-socket, workspace launcher 같은 외부 경계 adapter. - `apps/client/test/` — Flutter widget/service tests. +- `apps/client/assets/` — Flutter asset bundle과 ignored local smoke credential 위치. - `apps/client/android/`, `apps/client/ios/`, `apps/client/macos/`, `apps/client/linux/`, `apps/client/windows/`, `apps/client/web/` — platform-specific runner/config. - `apps/client/pubspec.yaml`, `apps/client/pubspec.lock`, `apps/client/analysis_options.yaml` — Dart/Flutter dependencies and analysis. - `apps/client/README.md`, `apps/client/push-notification-todo.md` — mobile 운영 메모와 push notification 작업 메모. @@ -34,7 +35,11 @@ NomadCode의 Flutter-first 제품 UI 도메인이다. 모바일/데스크톱/선 - `lib/src/app/nomadcode_workbench_shell.dart` — top titlebar, 우측 activity rail, 중앙 content 전환, 우측 Agent dock panel, 하단 IOP slot을 가진 workbench shell. - `lib/src/features/workspaces/presentation/workspace_home_page.dart` — workspace project/task UI. workbench mount 시 `showAppBar: false`로 내부 app bar를 숨길 수 있다. - `lib/src/integrations/mattermost/mattermost_auth_service.dart` — Mattermost auth flow. +- `lib/src/integrations/mattermost/mattermost_push_client.dart` — Mattermost-compatible push interface. +- `lib/src/integrations/mattermost/mattermost_push_plugin_client.dart` — production-only `NexoMessagingPlugin.instance` adapter. - `lib/src/integrations/mattermost/mattermost_push_host_integration.dart` — Mattermost push host initialization, auth handoff, notification navigation. +- `lib/src/integrations/proto_socket/proto_socket_client.dart` — local `proto_socket` package 기반 real connector/transport. +- `lib/src/integrations/proto_socket/proto_socket_envelope.dart` — core와 공유하는 semantic envelope DTO. - `lib/src/integrations/proto_socket/proto_socket_lifecycle.dart` — proto-socket connection lifecycle facade. - `lib/src/integrations/proto_socket/proto_socket_task_service.dart` — workspace task loading over proto-socket transport. - `lib/src/integrations/workspace/workspace_launcher.dart` — workspace/code-server launch boundary. @@ -51,13 +56,16 @@ NomadCode의 Flutter-first 제품 UI 도메인이다. 모바일/데스크톱/선 - NomadCode app shell은 top titlebar와 우측 activity rail을 가진 workbench 구조를 기준으로 한다. 우측 Agent dock은 rail에 붙는 panel로 열고 닫으며, 중앙 영역은 workspace/workflow/terminal/review/web context/settings 같은 product section을 전환한다. - IOP entry는 우측 rail 하단에 둔다. IOP-specific 운영 화면은 `iopContent` 같은 선택적 widget slot으로 mount하고, IOP package가 없는 기본 빌드에서는 placeholder로 유지한다. - 공통 agent interaction UI는 sibling `agent_shell` package를 사용한다. NomadCode-specific workflow/web context capability는 NomadCode mobile domain이 소유하고, IOP-specific 운영 화면은 향후 IOP-owned package/widget을 선택적으로 mount한다. +- proto-socket 연결은 `ProtoSocketLifecycle`과 connector/transport interface 뒤에 두고, bootstrap은 안전한 no-op 기본값으로 시작한다. +- production code에서 `NexoMessagingPlugin.instance` 직접 참조는 `MattermostPushPluginClient`에만 둔다. +- `assets/mattermost_credentials.json`은 local smoke credential로만 쓰며 ignored file 상태를 유지한다. - `flutter test`를 기본 검증으로 사용한다. - 현재 baseline의 `avoid_print` info는 별도 cleanup 작업으로 다루고, 기능 변경과 섞지 않는다. ## 다른 도메인과의 경계 - **core**: mobile은 core API/notification 계약에 의존하되 core 내부 구현을 알지 않는다. -- **contracts**: mobile이 사용하는 API/event shape는 contracts 후보로 올린다. +- **contracts**: mobile이 사용하는 API/event/proto-socket envelope shape는 contracts 후보로 올린다. - **agent-shell**: common chat/agent shell widget과 message model만 제공하는 sibling package다. Product routing, workbench section, web context 조작, IOP mount 결정은 mobile domain에서 조립한다. - **IOP**: IOP는 runtime/operation/agent capability와 IOP console widget/package 경계를 소유한다. mobile은 IOP 기능을 직접 복제하지 않고 선택적 section으로 mount한다. - **web**: [Legacy/Retired] React web 도메인은 완전히 제거되었습니다. @@ -70,5 +78,7 @@ NomadCode의 Flutter-first 제품 UI 도메인이다. 모바일/데스크톱/선 - Firebase 초기화/handler 변경을 테스트나 수동 검증 메모 없이 마무리하지 않는다. - IOP client UI나 runtime/operation semantics를 NomadCode mobile code에 직접 복제하지 않는다. - `agent_shell` package에 NomadCode 전용 workflow/web context/IOP product logic을 밀어 넣지 않는다. +- `nexo_messaging` plugin singleton을 host UI나 auth service에서 직접 호출하지 않는다. +- local smoke credential 파일을 tracked asset으로 커밋하지 않는다. - generated/platform build output을 의도 없이 커밋하지 않는다. - mobile 내부에 별도 `agent-ops` scaffold를 다시 만들지 않는다. diff --git a/agent-ops/rules/project/domain/workspace-ops/rules.md b/agent-ops/rules/project/domain/workspace-ops/rules.md index 6e6af9e..6cd5c85 100644 --- a/agent-ops/rules/project/domain/workspace-ops/rules.md +++ b/agent-ops/rules/project/domain/workspace-ops/rules.md @@ -1,7 +1,7 @@ --- domain: workspace-ops -last_rule_review_commit: bf8eed5b45752c2a62c038819878dce92220bda2 -last_rule_updated_at: 2026-05-30 +last_rule_review_commit: 03187a4be3d9864419221d14bb44b8bc6645e6f1 +last_rule_updated_at: 2026-05-31 --- # workspace-ops @@ -22,7 +22,7 @@ NomadCode 원레포 운영 도메인이다. 루트 helper, 문서, ignore 정책 - `agent-ops/bin/` — agent-ops 초기화, sync, entry file helper. - `agent-ops/rules/project/` — project/domain rules. - `agent-roadmap/` — project roadmap, current milestone pointer, milestone documents. -- `agent-test/` — local-only test rules and run artifacts. +- `agent-test/` — local-only test rules, smoke scenario docs, run artifacts. ## 제외 경로 @@ -42,18 +42,23 @@ NomadCode 원레포 운영 도메인이다. 루트 helper, 문서, ignore 정책 - `agent-roadmap/ROADMAP.md` — 전체 Phase와 Milestone index. - `agent-roadmap/current.md` — 현재 Phase와 기본 Milestone pointer. - `agent-ops/bin/sync.sh` — agent-ops 동기화 helper. +- `agent-ops/bin/roadmap-dependency-checker.sh` — roadmap 외부 의존 lock 판별 helper. +- `agent-test/local/*-smoke.md` — 도메인별 local smoke routing 문서. +- `agent-roadmap/phase/*/PHASE.md`, `agent-roadmap/phase/*/milestones/*.md` — 활성 Phase/Milestone 문서. ## 유지할 패턴 - root helper는 누락된 도구를 친절하게 skip하거나 명확히 실패한다. - 공통 agent-ops 영역과 프로젝트 특화 영역을 섞지 않는다. - roadmap은 `agent-roadmap/`에 두고, 서비스별 README에 Phase 계획을 중복 유지하지 않는다. +- 일반 작업에서 `agent-roadmap/archive/**`와 `agent-task/archive/**`는 사용자가 명시하거나 규칙이 허용한 경우에만 읽는다. - `.gitignore`에는 private rules와 local-only `agent-test/local/`, `agent-test/runs/`만 제외하고, `agent-task/archive/**`는 AI ignore/permission 파일에서 제어한다. - 원레포 구조 설명은 README를 기준으로 갱신하고, 별도 운영/아키텍처 세부가 있을 때만 docs에 분리한다. ## 다른 도메인과의 경계 -- **core/web/mobile/contracts**: workspace-ops는 실행/검증 흐름을 연결하지만 각 도메인 내부 구현을 소유하지 않는다. +- **core/mobile/contracts**: workspace-ops는 실행/검증 흐름을 연결하지만 각 도메인 내부 구현을 소유하지 않는다. +- **web**: [Legacy/Retired] React web 도메인은 완전히 제거되었으며 새 작업 대상으로 되살리지 않는다. - **agentic-framework**: common rules/skills/bin은 framework 동기화 결과물로 취급한다. ## 금지 사항 @@ -61,3 +66,4 @@ NomadCode 원레포 운영 도메인이다. 루트 helper, 문서, ignore 정책 - 하위 앱/서비스에 별도 agent entry 파일이나 agent-ops scaffold를 복제하지 않는다. - framework 공통 파일을 프로젝트 요구에 맞춰 직접 수정하지 않는다. - root helper에 특정 개발자 로컬 절대경로를 넣지 않는다. +- roadmap이나 agent-task archive 문서를 최신 템플릿에 맞춘다는 이유만으로 재포맷하지 않는다.