---
test_env: dev
last_rule_updated_at: 2026-07-01
---

# dev 테스트 규칙

**현재 문서를 반드시 끝까지 정독하고 작업한다. 다 읽지 않고 즉각 작업은 금지한다.**
**dev 환경은 remote local profile과 같은 host에서 분리 운영하는 Gito/NomadCode 연동 검증용 profile이다.**

## 공통 규칙

- dev 테스트/검증은 이 파일을 기준으로 판단한다.
- 원격 host에서 local profile 포트와 dev profile 포트를 동시에 띄울 수 있어야 한다.
- 환경값, secret, private endpoint 원문은 tracked docs/roadmap/task log/최종 응답에 기록하지 않는다.
- raw token, password, webhook secret, provider credential, private key는 ignored local profile 또는 remote secret store에서만 주입한다.
- 컨테이너 내부 listen 포트는 제품 기본값을 우선 유지하고, workspace 충돌 관리는 host publish/direct smoke 포트로 처리한다.
- 테스트용 Docker subnet을 새로 만들 때는 `192.168.0.0/24` 대역을 사용하지 않는다.

## 기본 환경

- host: standard remote runner `toki@toki-labs.com`.
- checkout: dev profile은 `$HOME/agent-work/gito-dev`를 기준으로 둔다. 아직 없으면 현재 검증 대상 branch/commit으로 생성 또는 동기화한 뒤 사용한다.
- runtime: repo root helper(`bin/test`, `bin/lint`, `bin/build`)와 변경 범위별 Go, Flutter/Dart toolchain.
- package manager: Go modules, Flutter pub.
- docker: 별도 compose를 추가하거나 복제할 때는 project/network 이름을 local profile과 분리하고 host publish 기본값을 `GITO_CORE_HOST_PORT=18061`, `GITO_POSTGRES_HOST_PORT=15461`, `GITO_REDIS_HOST_PORT=16361` 계열로 둔다.
- external service: Forgejo/Gitea/GitHub/GitLab/Jira/IOP 같은 provider 또는 runner 연동은 도메인/검증 시나리오별 문서가 명시한 경우에만 사용한다.
- credential: ignored local file 또는 `credential_ref` only.

## 포트 매핑

| 용도 | local profile | dev profile |
| --- | ---: | ---: |
| Flutter/project preview | `13060` | `13061` |
| Gito Core HTTP host publish/direct smoke | `18060` | `18061` |
| optional proto-socket/agent transport | `19060` | `19061` |
| PostgreSQL host publish 후보 | `15460` | `15461` |
| Redis host publish 후보 | `16360` | `16361` |
| NomadCode webhook consumer target | `18010` | `18011` |

dev Gito의 NomadCode delivery target은 `http://127.0.0.1:18011/api/integrations/gito/webhook`이다. local profile target은 `http://127.0.0.1:18010/api/integrations/gito/webhook`으로 유지한다.

## Gito-NomadCode 연동 기준

- Gito provider intake는 dev profile에서 `http://127.0.0.1:18061/callbacks/forgejo/push`를 기준으로 검증한다.
- branch watch 등록은 `POST http://127.0.0.1:18061/api/listeners/branches`로 수행한다.
- webhook subscription은 event `branch.updated`, repo `nomadcode`, branch `develop`, target URL `http://127.0.0.1:18011/api/integrations/gito/webhook`을 기준으로 한다.
- signing secret 원문은 `secret_ref` 또는 ignored local profile에만 두고 tracked 문서에는 쓰지 않는다.
- 계약 원문은 `agent-contract/provided/gito-forgejo-branch-events-v1.md`를 따른다.

## 라우팅

- workspace-ops / smoke / root helpers, docs, agent rules, roadmap, local/dev test rules: `agent-test/local/workspace-ops-smoke.md`
- core / smoke / services/core backend, control plane, worker, shell baseline: `agent-test/local/core-smoke.md`
- contracts / smoke / packages/contracts and agent-contract notes baseline: `agent-test/local/contracts-smoke.md`
- client / smoke / apps/client Flutter control surface baseline: `agent-test/local/client-smoke.md`

## 라우팅 규칙

- 여러 항목이 맞으면 모두 읽는다.
- 도메인 매핑이나 domain rule이 있으면 각 도메인의 `<domain>-smoke` 문서를 기본 baseline으로 둔다.
- 도메인이 아직 없을 때만 `project-smoke`를 fallback baseline으로 둔다.
- 도메인/검증 시나리오별 문서는 다른 테스트 문서로 라우팅하지 않는다.
