gito/README.md

# 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
- platformless `gitengine` 최소 테스트
- core domain DTO 후보
- provider-neutral `ChangeRequest` adapter 경계
- Postgres migration 초기안
- `agent-ops` 규칙/스킬 기반 작업 진입점

아직 구현 전인 범위:

- 실제 proto-socket channel/action
- 실제 PostgreSQL store wiring
- `agent_shell: path: ../agent-shell` package를 쓰는 Flutter host
  integration
- `../iop` backend/runtime 결과를 Gito operation/event 계약으로 수렴시키는
  연결
- GitHub/GitLab/Gitea provider adapter
- Flutter 화면 구성과 operation event 구독

## 빠른 시작

```sh
bin/test
bin/lint
bin/build
```

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

```text
bin/gito-server
bin/gito-worker
```

서버 scaffold 실행:

```sh
HTTP_ADDR=:8080 bin/gito-server
```

확인:

```sh
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로 시작하되, 실행 역할은 분리 가능하게 둔다.

```text
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](AGENTS.md)를 읽고, 변경 경로에 맞는 domain rule을 확인한다.

주요 문서:

- [Project rules](agent-ops/rules/project/rules.md)
- [Core domain rules](agent-ops/rules/project/domain/core/rules.md)
- [Client domain rules](agent-ops/rules/project/domain/client/rules.md)
- [Contracts domain rules](agent-ops/rules/project/domain/contracts/rules.md)
- [Workspace ops rules](agent-ops/rules/project/domain/workspace-ops/rules.md)
- [Local test rules](agent-test/local/rules.md)
- [Architecture](docs/architecture.md)
- [Control plane contract candidates](packages/contracts/notes/gito-control-plane.md)

## 개발 흐름

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 | 실제 storage wiring 이후 필요 |
| `REDIS_URL` | optional Redis endpoint | 아니오 |
| `PROTO_SOCKET_PATH` | proto-socket endpoint path, 기본값 `/proto-socket` | 아니오 |
| `WORKER_ENABLED` | worker 실행 여부, 기본값 `true` | 아니오 |

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

## 참고 문서

- [docs/architecture.md](docs/architecture.md)
- [packages/contracts/notes/gito-control-plane.md](packages/contracts/notes/gito-control-plane.md)
- [agent-ops/skills/common/create-readme/SKILL.md](agent-ops/skills/common/create-readme/SKILL.md)