Gito

Gito는 agent-driven development를 위한 platformless Git control plane이다. 여러 Git repository를 등록하고, workspace lease, Git operation, provider adapter, normalized event를 하나의 제어 흐름으로 묶는다. Agent interaction UI는 sibling ../agent-shell Flutter package를 사용하고, 그 UI를 구동하는 backend/runtime은 sibling ../iop 프로젝트가 맡는 방향으로 둔다.

Git 자체 작업은 GitHub/GitLab/Gitea 같은 플랫폼을 몰라도 동작해야 한다. PR/MR, review, checks, webhook 같은 플랫폼 기능은 provider adapter 뒤에 둔다.

현재 상태

초기 scaffold 단계다. Go core는 build/test 가능한 최소 골격을 갖고 있고, Flutter client는 control surface 경계만 잡혀 있다.

현재 가능한 범위:

• Go server, worker command build
• health/readiness REST placeholder
• proto-socket registry와 binary event.subscribe / branch.updated event path
• Forgejo push callback, watched branch listener, branch event smoke/debug surface
• PostgreSQL-backed repo, workspace lease, operation, event, branch watch, revision cursor, provider delivery baseline
• platformless gitengine 최소 테스트
• core domain DTO 후보
• provider-neutral ChangeRequest adapter 경계
• Postgres migration 초기안
• agent-ops 규칙/스킬 기반 작업 진입점

아직 구현 전인 범위:

• event 외 proto-socket channel/action의 실제 command behavior
• agent_shell: path: ../agent-shell package를 쓰는 Flutter host integration
• ../iop backend/runtime 결과를 Gito operation/event 계약으로 수렴시키는 연결
• GitHub/GitLab/Gitea provider adapter와 Forgejo PR/MR adapter
• Flutter 화면 구성과 operation event 구독

빠른 시작

bin/test
bin/lint
bin/build

빌드가 끝나면 root bin/ 아래에 아래 실행 파일이 생성된다.

bin/gito-server
bin/gito-worker

서버 scaffold 실행:

HTTP_ADDR=:8080 bin/gito-server

확인:

curl http://127.0.0.1:8080/healthz
curl http://127.0.0.1:8080/readyz

주요 명령

목적	명령	비고
전체 테스트	bin/test	Go test 실행, Flutter test scaffold가 없으면 client test는 skip
lint	bin/lint	go vet ./..., Flutter가 있으면 flutter analyze --no-fatal-infos
build	bin/build	gito-server, gito-worker 생성
Core test	cd services/core && go test ./...	Go module 기준 직접 실행
Core lint	cd services/core && go vet ./...	Go vet 직접 실행

구조

경로	역할
services/core/cmd/server/	control plane server entrypoint
services/core/cmd/worker/	operation worker entrypoint
services/core/internal/controlplane/	REST/proto-socket surface, auth/policy gate 후보
services/core/internal/core/	provider-neutral domain model
services/core/internal/gitengine/	platformless Git operation layer
services/core/internal/worker/	operation 실행 orchestration 후보
services/core/internal/provider/	GitHub/GitLab/Gitea/Plane/Jira adapter boundary
services/core/internal/events/	normalized event model
services/core/internal/storage/	PostgreSQL store boundary
services/core/migrations/	database schema migration
apps/client/	Flutter control surface scaffold
packages/contracts/	proto-socket, REST, event, DTO contract notes
docs/	사람용 architecture/operation 문서
agent-ops/	agent rules, skills, roadmap helper
agent-test/	local validation rules

설계 방향

Gito는 처음에는 modular monolith로 시작하되, 실행 역할은 분리 가능하게 둔다.

Flutter UI / gitoctl
        |
Control Plane
        |
Core Domain
        |
Worker / Scheduler
        |
IOP backend/runtime + Git Engine
        |
Provider Adapters

원칙:

• controlplane은 요청, 정책, 관찰, event stream을 소유한다.
• core는 repo, workspace lease, operation, revision cursor, event 원장을 소유한다.
• worker는 operation 실행과 외부 runtime 결과 수렴을 조율한다.
• Flutter host는 agent_shell: path: ../agent-shell dependency로 agent interaction UI/domain package를 붙인다.
• ../agent-shell은 Flutter agent UI/package이며 Gito backend가 아니다.
• ../iop는 agent backend/runtime을 맡고, Gito는 그 결과를 Git operation과 event 원장으로 수렴한다.
• gitengine은 platformless여야 하며 local bare repo만으로 테스트 가능해야 한다.
• provider는 PR/MR/review/checks/webhook 같은 플랫폼 기능만 맡는다.
• PostgreSQL은 source of truth이고, Redis는 필요할 때 fanout/stream 가속 계층으로만 둔다.

통신 정책

• 내부 runtime 통신은 proto-socket을 우선한다.
• REST는 health/readiness, provider callback, smoke/curl, 단순 bootstrap에만 둔다.
• gRPC는 초기 설계에서 제외한다.
• webhook은 빠른 wakeup signal로만 보고, 최종 판정은 Git revision/diff 또는 provider read API로 재검증한다.

작업 맥락

작업을 시작할 때는 먼저 AGENTS.md를 읽고, 변경 경로에 맞는 domain rule을 확인한다.

주요 문서:

• Project rules
• Core domain rules
• Client domain rules
• Contracts domain rules
• Workspace ops rules
• Local test rules
• Architecture
• Control plane contract candidates

개발 흐름

1. 변경 전에 관련 domain rule을 읽는다.
2. core 변경은 cd services/core && go test ./... 또는 bin/test로 확인한다.
3. contracts 변경은 README/notes의 transport 정책과 맞는지 확인한다.
4. client 변경은 Flutter toolchain이 있으면 flutter analyze --no-fatal-infos와 flutter test를 실행한다.
5. 생성된 binary, .dart_tool/, local secret 파일은 commit하지 않는다.

환경 변수

이름	설명	필수
APP_ENV	runtime 환경 이름, 기본값 local	아니오
HTTP_ADDR	server listen address, 기본값 :8080	아니오
DATABASE_URL	PostgreSQL connection string, 없으면 in-memory runtime 사용	아니오
REDIS_URL	optional Redis endpoint	아니오
PROTO_SOCKET_PATH	proto-socket endpoint path, 기본값 /proto-socket	아니오
FORGEJO_WEBHOOK_SECRET	Forgejo push callback HMAC-SHA256 서명 키, 없으면 검증 생략	아니오
WORKER_ENABLED	worker 실행 여부, 기본값 true	아니오

Credential 값은 tracked 파일에 쓰지 않는다. 필요한 경우 credential_ref나 ignored local secret file로 연결한다.

참고 문서

• docs/architecture.md
• packages/contracts/notes/gito-control-plane.md
• agent-ops/skills/common/create-readme/SKILL.md