# Configuration reference

> JSON 키·기본값·필수/선택, INSTANCE_RUNTIME_CONFIG·DISPATCH_TIER_POLICY·WORKSPACE_DESCRIPTOR·MOGUI_* 환경 변수 해석 순서.

- Repository: local/mogui-ADE-orchestrator

- Human docs: https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac
- Complete Markdown: https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/llms-full.txt

## Source Files

- `config/instance-runtime.example.json`
- `config/model-tier-policy.example.json`
- `config/workspace-descriptor.example.json`
- `src/master_runtime/core/instance_runtime_config.py`
- `src/master_runtime/core/workspace_descriptor.py`
- `src/master_runtime/core/dispatch_gate.py`
- `master-ops/MANIFEST.json`

---

---
title: "Configuration reference"
description: "JSON 키·기본값·필수/선택, INSTANCE_RUNTIME_CONFIG·DISPATCH_TIER_POLICY·WORKSPACE_DESCRIPTOR·MOGUI_* 환경 변수 해석 순서."
---

인스턴스 설정은 세 개의 JSON 표면과 경로·값 오버라이드 환경 변수로 구성된다. 로더는 값을 추측하지 않고 **환경 → 인스턴스 파일 → 정직한 unconfigured**(티어 정책만 템플릿 폴백) 순으로 해석한다. 저장소에는 `config/*.example.json`만 커밋되며, 온보딩이 `config/instance-runtime.json`, `config/model-tier-policy.json`, `config/workspace-descriptor.json`을 작성한다.

## 설정 표면 요약

| 표면 | 기본 경로 | 경로 env | 값 오버라이드 env | 파일 없을 때 |
|------|-----------|----------|-------------------|--------------|
| Instance runtime | `config/instance-runtime.json` | `INSTANCE_RUNTIME_CONFIG` | `MOGUI_MASTER_HOST_RUNTIME`, `MASTER_HOST_RUNTIME`, `MOGUI_TRANSCRIPT_GLOB`, `MOGUI_PRODUCT_REPO` | unconfigured (에러 아님) |
| Model tier policy | `config/model-tier-policy.json` → `master-ops/model-tier-policy.json` | `DISPATCH_TIER_POLICY` (및 CLI `--tier-policy`) | 없음 (파일 전체 교체) | 인스턴스 없으면 템플릿 사용 |
| Workspace descriptor | `config/workspace-descriptor.json` | `WORKSPACE_DESCRIPTOR`, `MOGUI_WORKSPACE_DESCRIPTOR` | 없음 (파일 전체 교체) | 빈 inventory / unconfigured |

<Note>
`_`로 시작하는 JSON 키(`_docs`, `_notes` 등)는 문서용이며 파서가 무시한다. 예제 파일의 `_docs`는 커밋된 스키마 설명이다.
</Note>

## 공통 해석 순서

```text
명시 CLI 경로 (있는 경우)
        │
        ▼
환경 변수 경로 오버라이드
  INSTANCE_RUNTIME_CONFIG
  DISPATCH_TIER_POLICY
  WORKSPACE_DESCRIPTOR / MOGUI_WORKSPACE_DESCRIPTOR
        │
        ▼
인스턴스 파일 (config/*.json)
        │
        ├─ instance-runtime / workspace-descriptor
        │     → 값 env 오버라이드 (해당 시)
        │     → 없으면 unconfigured (require_* 가 실패)
        │
        └─ model-tier-policy
              → 인스턴스 파일 없음 → master-ops/model-tier-policy.json
```

원칙:

1. **경로 선택**과 **필드 값 선택**은 별층이다. 경로 env가 파일을 고르고, 값 env가 필드 단위로 덮는다.
2. Instance facts(`master_host_runtime`, transcript glob, `product_repo`)는 베이크된 기본값을 쓰지 않는다.
3. Tier policy만 측정된 템플릿 폴백(`master-ops/model-tier-policy.json`)을 허용한다.

## 파일 레이아웃

:::files
config/
  instance-runtime.example.json      # 템플릿 (커밋)
  model-tier-policy.example.json     # 템플릿 (커밋)
  workspace-descriptor.example.json  # 템플릿 (커밋)
  gitleaks.toml                      # 공개 redaction 엔진 규칙
  instance-runtime.json              # 인스턴스 전용 (온보딩 작성, 보통 비커밋)
  model-tier-policy.json             # 인스턴스 전용
  workspace-descriptor.json          # 인스턴스 전용
master-ops/
  model-tier-policy.json             # 게이트 템플릿 폴백 (version 2)
  MANIFEST.json                      # master-ops 템플릿 파일 목록
:::

## Instance runtime (`config/instance-runtime.json`)

로더: `load_instance_runtime_config` → `InstanceRuntimeConfig`.  
기본 상대 경로: `config/instance-runtime.json`. 모듈 위치 기준으로 repo root를 찾으므로 cwd와 무관하다.

### 경로 해석

1. 호출자가 넘긴 명시 `path`
2. `INSTANCE_RUNTIME_CONFIG` (비어 있지 않은 문자열; `~` 확장)
3. `<repo>/config/instance-runtime.json`

파일이 없어도 로드는 성공한다. `source_path`는 실제 파일이 있을 때만 설정된다.

### JSON 필드

<ParamField body="master_host_runtime" type="string | null" required={false}>
마스터 세션이 돌아가는 에이전트 CLI 이름(예: `claude`, `codex`, `grok`). 공백 문자열은 unset. 잘못된 타입(비-string)은 `InstanceRuntimeConfigError`.
</ParamField>

<ParamField body="transcript_globs" type="object" required={false}>
런타임 이름 → 세션 JSONL glob 맵. 모델 identity probe가 transcript 위치를 찾을 때 사용. 키·값 모두 비어 있지 않은 문자열. `_` 접두 키는 무시.
</ParamField>

<ParamField body="product_repo" type="string | null" required={false}>
이 마스터가 서비스하는 primary product 저장소 절대 경로. 단일 primary가 없으면 omit/`null`.
</ParamField>

### 값 해석 순서 (필드별)

| 필드 | 1순위 | 2순위 | 3순위 |
|------|--------|--------|--------|
| `master_host_runtime` | `MOGUI_MASTER_HOST_RUNTIME` | `MASTER_HOST_RUNTIME` | 파일 |
| `product_repo` | `MOGUI_PRODUCT_REPO` | 파일 | unconfigured |
| transcript glob | `MOGUI_TRANSCRIPT_GLOB` (런타임 무관 단일 오버라이드) | `transcript_globs.<runtime>` | unconfigured |

`require_master_host_runtime()`, `require_transcript_glob(runtime?)`, `require_product_repo()`는 값이 없으면 `InstanceRuntimeConfigError`를 발생시킨다. CLI 소비자는 보통 exit 2.

### 예제 골격

```json
{
  "master_host_runtime": "claude",
  "transcript_globs": {
    "claude": "~/.claude/projects/-Users-example-workspace/*.jsonl",
    "codex": "~/.codex/sessions/**/*.jsonl",
    "grok": "~/.grok/sessions/**/*.jsonl"
  },
  "product_repo": "/absolute/path/to/primary-product-repo"
}
```

### 관련 CLI

| 명령 | 설정 사용 |
|------|-----------|
| `scripts/model-identity-probe` | `--transcript` 생략 시: 명시 → `MOGUI_TRANSCRIPT_GLOB` → 파일 → unconfigured. `--config`로 경로 지정 가능 |

## Model tier policy (`config/model-tier-policy.json`)

디스패치 게이트(`DispatchGate`)가 worker 모델 티어와 rolling fan-out 캡을 적용한다. 인스턴스 파일은 온보딩에서 agent-inventory 동의 후 작성한다. 예제: `config/model-tier-policy.example.json`. 템플릿 폴백: `master-ops/model-tier-policy.json`.

### 경로 해석

1. CLI `--tier-policy` (호출자가 `DispatchGateConfig.tier_policy_path` 설정)
2. `DISPATCH_TIER_POLICY`
3. 존재하면 `<repo>/config/model-tier-policy.json`
4. `<repo>/master-ops/model-tier-policy.json`

### Version 2 (권장, 게이트 소비 필드)

| 키 | 필수 | 기본 | 규칙 |
|----|------|------|------|
| `version` | 예 | — | 반드시 `2` |
| `tiers` | 예 | — | 비어 있지 않은 object. 티어 이름 → model id 배열. model id는 casefold 후 멤버십. 한 model은 한 티어만. 티어 이름 `unknown`은 예약 |
| `fanout_caps` | 예 (object) | — | 티어 → 비음수 정수. **키가 없으면 uncapped** (`top`·`unknown` 포함). 존재하지 않는 티어 이름 금지 (`unknown`만 예외로 허용) |
| `window_seconds` | 아니오 | `86400` | 양의 정수. rolling window(초) |
| `agents` | 아니오 | — | 게이트 무시. 측정 인벤토리 문서용 |
| `consent` | 아니오 | 예제 `"no"` | 게이트 무시. `yes` / `no` / `manual-only` 기록용 |

미등재 model id → 예약 티어 `unknown`. `cap_for(tier)`가 `None`이면 해당 티어 캡 없음. Owner 지시(2026-08-05): top 티어 fan-out 캡은 제거하고, top 디스패치는 `master-ops/scripts/dispatch --top-approved`로 소유자 승인.

### Version 1 (레거시)

| 키 | 필수 | 규칙 |
|----|------|------|
| `version` | 예 | `1` |
| `worker_allowed` | 예 | model id 배열 |
| `worker_denied_tiers` | 예 | model id 배열; allowed와 겹치면 로드 실패 |
| `unknown_model` | 예 | `"deny"` 또는 `"warn"` |

버전 1 동작은 유지되어, 런타임만 올려도 기존 설치의 판정이 바뀌지 않는다.

### 예제 (인스턴스 시작점)

```json
{
  "version": 2,
  "consent": "no",
  "agents": [
    { "runtime": "claude", "version": "unknown", "model_ids": ["unknown"] }
  ],
  "tiers": {
    "top": [],
    "efficient": []
  },
  "fanout_caps": {
    "unknown": 8
  },
  "window_seconds": 86400
}
```

model id를 추측하지 않는다. 측정 불가 필드는 문자열 `unknown`을 쓴다.

### 게이트 기본값 (정책 파일 밖)

| 설정 | 기본 | env / 비고 |
|------|------|------------|
| Ledger path | `.dispatch-gate-ledger.jsonl` | `DISPATCH_GATE_LEDGER` |
| Ticket dir | `~/.mogui/dispatch-tickets` | config 필드 |
| Known roots | `~/.mogui/known-roots.json` | config 필드 |
| Single dispatch char limit | `500000` | |
| Batch dispatch char limit | `1000000` | |
| Duplicate window | `1800` 초 | |
| Ticket TTL | `600` 초 | |
| Expired ticket GC grace | `86400` 초 | |
| High-cost runtimes | `{"fable"}` | |

정책 로드 실패 시 reason `TIER_POLICY_UNAVAILABLE`. 캡 초과 시 `TIER_FANOUT_CAP`. 결정은 ledger에 `tier_policy_path`와 `tier_policy_sha256`을 남긴다.

## Workspace descriptor (`config/workspace-descriptor.json`)

로더: `load_workspace_descriptor` → `WorkspaceDescriptor`. 워크스페이스 루트는 **sibling 저장소가 있는 plain folder**이며 submodule parent가 아니다.

### 경로 해석

1. 명시 `path`
2. `WORKSPACE_DESCRIPTOR`
3. `MOGUI_WORKSPACE_DESCRIPTOR`
4. `<repo>/config/workspace-descriptor.json`

파일 없음 → `repositories=()`, `source_path=None`, `master_seat=""`, `workspace_root_is_plain_folder=True`.  
`action_is_prohibited` 헬퍼는 파일이 없으면 `WorkspaceDescriptorError`(unconfigured).

### 루트 필드

<ParamField body="workspace_root_is_plain_folder" type="boolean" required={false}>
기본 `true`. `true`가 아니면 로드 실패. submodule parent 거부.
</ParamField>

<ParamField body="workspace_root" type="string | null" required={false}>
워크스페이스 루트 절대 경로. 절대 경로 매칭에 필요. omit/`null`/빈 문자열이면 절대 후보 매칭 불가.
</ParamField>

<ParamField body="master_seat" type="string" required={false}>
마스터 세션 좌석 설명/selector 메모. 타입은 string; 기본 `""`.
</ParamField>

<ParamField body="repositories" type="array" required={false}>
멤버 저장소 인벤토리. omit 시 빈 목록. `require_repositories()`는 비어 있으면 오류.
</ParamField>

### `repositories[]` 항목

| 키 | 필수 | 규칙 |
|----|------|------|
| `name` | 예 | 비어 있지 않은 string. 인벤토리 내 유일 |
| `path` | 예 | 워크스페이스 루트 상대 경로. 단일 저장소면 `"."` 허용. 경로 유일 |
| `remote` | 아니오 | string; 기본 `""` |
| `role` | 예 | `product` 또는 `ops`만 |
| `capabilities` | 아니오 | string 배열; omit → `()`. open set. 문서화된 바닥: `pr`, `dispatch-target` |
| `prohibited` | **예** | 반드시 배열 존재. `null`/누락 무효. 소유자가 금지 없음으로 확인한 경우만 `[]`. open set. 문서화된 바닥: `direct-main-commit`, `force-push` |

### 경로 매칭

`repository_for_path`:

- 선언 `path` 정확 일치 (`.` 포함)
- 경로 구분자가 없는 후보는 `name` 정확 일치
- 절대 경로: `workspace_root` 하위일 때만 상대 나머지로 매칭
- 복수 매칭 → `WorkspaceDescriptorError`
- 미매칭 + `is_prohibited(..., default_when_unknown_repo=True)` → fail-closed (금지 취급)

### 예제 골격

```json
{
  "workspace_root_is_plain_folder": true,
  "workspace_root": "/absolute/path/to/workspace-root",
  "master_seat": "folder-workspace-of-workspace-root",
  "repositories": [
    {
      "name": "example-product",
      "path": "example-product",
      "remote": "https://github.com/example/example-product.git",
      "role": "product",
      "capabilities": ["pr", "dispatch-target"],
      "prohibited": ["direct-main-commit", "force-push"]
    }
  ]
}
```

### 관련 CLI

| 명령 | exit |
|------|------|
| `scripts/workspace-descriptor-check --path … --action …` | 0 허용, 1 금지, 2 unconfigured/invalid |

## 환경 변수 카탈로그

### 경로 선택

| 변수 | 대상 |
|------|------|
| `INSTANCE_RUNTIME_CONFIG` | instance-runtime JSON 경로 |
| `DISPATCH_TIER_POLICY` | model-tier-policy JSON 경로 |
| `WORKSPACE_DESCRIPTOR` | workspace-descriptor JSON 경로 (우선) |
| `MOGUI_WORKSPACE_DESCRIPTOR` | workspace-descriptor 대체 경로 |
| `DISPATCH_GATE_LEDGER` | dispatch gate ledger JSONL 경로 |

### Instance 값 오버라이드 (`MOGUI_*` 및 별칭)

| 변수 | 효과 |
|------|------|
| `MOGUI_MASTER_HOST_RUNTIME` | `master_host_runtime` 최우선 |
| `MASTER_HOST_RUNTIME` | 위 변수가 없을 때 대체 |
| `MOGUI_TRANSCRIPT_GLOB` | 활성 런타임 transcript glob 단일 오버라이드 |
| `MOGUI_PRODUCT_REPO` | `product_repo` |

### Redaction (인접 설정)

| 변수 | 효과 |
|------|------|
| `REDACTION_EXTRA_PATTERNS` | org 규칙 파일 (`id\|description\|regex` 라인). 기본 preflight 후보: `~/.config/redaction-extra.txt` |
| `REDACTION_REQUIRE_EXTRA` | `1`이면 extra 규칙 없거나 비어 있으면 exit 2 |
| `REDACTION_ALLOWLIST` | 레거시; 항목이 남아 있으면 scan exit 2 |
| `GITLEAKS_CONFIG` | gitleaks 설정 경로 (공개 규칙 밖 org 패턴용; 저장소 `config/gitleaks.toml`은 extend defaults) |

## 오류·검증 신호

| 증상 | 원인 | 신호 |
|------|------|------|
| `master_host_runtime is unconfigured` | env·파일 모두 없음 | `InstanceRuntimeConfigError` / probe exit 2 |
| `transcript_glob for runtime '…' is unconfigured` | `MOGUI_TRANSCRIPT_GLOB` 없고 map 키 없음 | 동일 |
| `instance runtime config is not valid JSON` | 손상된 파일 | 로드 즉시 실패 |
| `workspace descriptor is unconfigured` | 파일·경로 env 없음 | `WorkspaceDescriptorError` / check exit 2 |
| `repositories[i].prohibited must be present` | prohibited 누락 | 파싱 실패 |
| `workspace_root_is_plain_folder must be true` | false 또는 non-bool | 파싱 실패 |
| `duplicate repository path/name` | 인벤토리 중복 identity | 파싱 실패 |
| `tier policy version must be 1 or 2` | 잘못된 version | 게이트 `TIER_POLICY_UNAVAILABLE` |
| `fanout_caps names a tier that does not exist` | 캡 키 오타 | 로드 실패 |
| `a model may not appear in two tiers` | 교차 등재 | 로드 실패 |

## 온보딩·커밋 경계

- 템플릿 저장소는 `*.example.json`만 공개 스키마로 유지한다.
- 채워진 `config/instance-runtime.json` / `model-tier-policy.json` / `workspace-descriptor.json`은 인스턴스 소유이며, 예제를 git에서 덮어쓰지 않는다.
- `master-ops/MANIFEST.json`의 `template_version`과 파일 목록은 master-ops 배포 표면이며, `config/` 인스턴스 파일과 분리된다.
- model id·transcript path·product path는 측정 또는 소유자 명명으로만 채운다.

## Related pages

<CardGroup cols={2}>
  <Card title="인스턴스 설정" href="/configure-instance">
    instance-runtime·model-tier-policy 작성 절차, transcript glob, 티어×fan-out 캡 운영.
  </Card>
  <Card title="Workspace descriptor" href="/workspace-descriptor">
    sibling 인벤토리, role·capabilities·prohibited, master_seat, check 액션.
  </Card>
  <Card title="dispatch-gate 레퍼런스" href="/dispatch-gate-reference">
    check·register 플래그, ledger, reason code, 티켓 TTL.
  </Card>
  <Card title="Supervised dispatch" href="/supervised-dispatch">
    check → dispatch → register와 계약 해시·model probe.
  </Card>
  <Card title="Redaction gates" href="/redaction-gates">
    REDACTION_*·gitleaks·pre-push 게이트.
  </Card>
  <Card title="Troubleshooting" href="/troubleshooting">
    unconfigured, MODEL_PROBE_FAILED, placement·preflight 복구.
  </Card>
</CardGroup>