# 설정 참조

> `instance-runtime.json`, `workspace-descriptor.json`, `model-tier-policy.json`, 환경 변수 override, schema field, default, fail-closed 동작을 정리합니다.

- Repository: local/master-ops-with-local-mogui-ADE-orchestrator

- Human docs: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3
- Complete Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/llms-full.txt

## Source Files

- `local-mogui-ade-orchestrator:config/instance-runtime.example.json`
- `local-mogui-ade-orchestrator:config/workspace-descriptor.example.json`
- `local-mogui-ade-orchestrator:config/model-tier-policy.example.json`
- `local-mogui-ade-orchestrator:src/master_runtime/core/instance_runtime_config.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/workspace_descriptor.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/dispatch_gate.py`
- `local-mogui-ade-orchestrator:tests/test_instance_runtime_config.py`
- `local-mogui-ade-orchestrator:tests/test_workspace_descriptor.py`

---

---
title: "설정 참조"
description: "`instance-runtime.json`, `workspace-descriptor.json`, `model-tier-policy.json`, 환경 변수 override, schema field, default, fail-closed 동작을 정리합니다."
---

런타임 설정은 인스턴스 소유 JSON 파일과 환경 변수 override로 해석된다. 템플릿은 `*.example.json`만 제공하고, 실제 설치 값은 `config/instance-runtime.json`, `config/workspace-descriptor.json`, `config/model-tier-policy.json`에 기록한다.

## 설정 파일

| 파일 | 소유 주체 | 주요 소비자 | 기본 경로 동작 |
| --- | --- | --- | --- |
| `config/instance-runtime.json` | 설치 인스턴스 | `model-identity-probe`, master-ops dispatch wrapper | 없으면 값별 `require_*` 호출에서 `unconfigured` 오류 |
| `config/workspace-descriptor.json` | 설치 인스턴스 | `workspace-descriptor-check`, 작업 라우팅 guard | 없으면 descriptor는 비어 있고 판단 API는 exit `2` |
| `config/model-tier-policy.json` | 설치 인스턴스 | `dispatch-gate`, `master-ops/scripts/dispatch` | 있으면 템플릿 정책보다 우선 |
| `master-ops/model-tier-policy.json` | 템플릿/ops 저장소 | tier policy fallback | 인스턴스 정책이 없을 때 fallback |

<Warning>
채워진 인스턴스 설정 파일은 이 머신의 절대 경로, transcript glob, owner consent 상태를 담을 수 있다. 예제 파일은 버전 관리 대상이지만 채워진 인스턴스 파일은 커밋하지 않는 전제다.
</Warning>

## `instance-runtime.json`

`instance-runtime.json`은 마스터가 어떤 agent CLI 위에서 실행되는지, 각 runtime의 transcript JSONL을 어디서 찾는지, 선택적 primary product repo가 무엇인지 기록한다.

### 필드

| 필드 | 타입 | 기본값 | 필수성 | 동작 |
| --- | --- | --- | --- | --- |
| `master_host_runtime` | `string \| null` | 없음 | 필요한 소비자에서 필수 | 비어 있으면 `require_master_host_runtime()`이 오류 |
| `transcript_globs` | `object<string,string>` | `{}` | model probe에서 필요 | runtime 이름별 glob. `_`로 시작하는 키는 문서 키로 무시 |
| `product_repo` | `string \| null` | 없음 | product-path guard 등에서 필요 | 비어 있으면 `require_product_repo()`가 오류 |
| `_docs` | `object` | 없음 | 선택 | parser가 무시하는 문서용 키 |

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

### 해석 순서

1. 명시적 config path 인자
2. `INSTANCE_RUNTIME_CONFIG`
3. `<runtime repo>/config/instance-runtime.json`

값 자체는 환경 변수가 파일보다 우선한다.

| 값 | 환경 변수 우선순위 | 파일 fallback | 미설정 동작 |
| --- | --- | --- | --- |
| 마스터 runtime | `MOGUI_MASTER_HOST_RUNTIME`, 그 다음 `MASTER_HOST_RUNTIME` | `master_host_runtime` | `InstanceRuntimeConfigError` |
| transcript glob | `MOGUI_TRANSCRIPT_GLOB` | `transcript_globs.<runtime>` | `InstanceRuntimeConfigError` |
| product repo | `MOGUI_PRODUCT_REPO` | `product_repo` | `InstanceRuntimeConfigError` |

<Note>
`MOGUI_TRANSCRIPT_GLOB`는 runtime별 변수가 아니라 현재 probe에 적용되는 단일 override다. `model-identity-probe --transcript`가 있으면 이 모든 해석보다 우선한다.
</Note>

## `workspace-descriptor.json`

`workspace-descriptor.json`은 plain folder workspace 아래 sibling repository 목록을 선언한다. 이 런타임은 `workspace_root_is_plain_folder: true`만 허용하며 submodule parent나 non-plain workspace root를 거부한다.

### workspace 필드

| 필드 | 타입 | 기본값 | 제약 |
| --- | --- | --- | --- |
| `workspace_root_is_plain_folder` | `boolean` | `true` | 반드시 `true` |
| `workspace_root` | `string \| null` | `null` | 절대 경로 lookup을 쓰려면 설정 |
| `master_seat` | `string` | `""` | null은 빈 문자열로 처리 |
| `repositories` | `array` | `[]` | 필요한 소비자에서는 비어 있으면 unconfigured |
| `_docs` | `object` | 없음 | parser가 무시 |

### repository 필드

| 필드 | 타입 | 기본값 | 제약 |
| --- | --- | --- | --- |
| `name` | `string` | 없음 | non-empty, 중복 불가 |
| `path` | `string` | 없음 | workspace-root-relative, 단일 repo 예외는 `.` |
| `remote` | `string` | `""` | null이면 빈 문자열 |
| `role` | `string` | 없음 | `product` 또는 `ops` |
| `capabilities` | `array<string>` | `[]` | open set. 예: `pr`, `dispatch-target` |
| `prohibited` | `array<string>` | 없음 | 반드시 존재. 빈 배열은 owner-confirmed no prohibition 의미 |

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

### prohibition 판단

`workspace-descriptor-check`는 repository path와 action을 받아 허용 여부를 판단한다.

```bash
scripts/workspace-descriptor-check \
  --path product-app \
  --action direct-main-commit \
  --json
```

| exit code | 의미 |
| --- | --- |
| `0` | action 허용 |
| `1` | action 금지 |
| `2` | descriptor 미설정, invalid, bad usage. 판단 불가이므로 fail-closed |

경로 매칭은 선언된 `path`, 단일 segment `name`, 또는 `workspace_root` 아래의 절대 경로를 사용한다. 같은 basename이 다른 부모 아래에 있는 상대 경로는 suffix match하지 않는다. 알 수 없는 repo는 기본적으로 금지로 취급하며, CLI에서만 `--allow-unknown-repo`로 이 기본값을 바꿀 수 있다.

## `model-tier-policy.json`

현재 예제와 템플릿 정책은 version `2` 형식이다. dispatch gate는 version `1`도 legacy로 읽지만, tier와 fan-out cap을 문서화할 때 기준은 version `2`다.

### v2 필드

| 필드 | 타입 | 기본값 | 제약 |
| --- | --- | --- | --- |
| `version` | `integer` | 없음 | `2` |
| `tiers` | `object<string,array<string>>` | 없음 | non-empty object. `unknown` tier 이름은 예약어라 선언 불가 |
| `fanout_caps` | `object<string,integer>` | 없음 | 반드시 object. tier 이름 또는 `unknown`만 허용. 값은 0 이상 정수 |
| `window_seconds` | `integer` | `86400` | 양의 정수 |
| `agents` | `array` | 없음 | gate parser가 소비하지 않는 설치 inventory |
| `consent` | `string` | 없음 | gate parser가 소비하지 않는 owner consent 기록 |
| `_docs`, `_notes` | `object/string` | 없음 | gate parser가 소비하지 않는 문서 메타데이터 |

```json title="config/model-tier-policy.json"
{
  "version": 2,
  "consent": "no",
  "agents": [
    {
      "runtime": "claude",
      "version": "unknown",
      "model_ids": ["unknown"]
    }
  ],
  "tiers": {
    "top": [],
    "efficient": ["claude-sonnet-5"]
  },
  "fanout_caps": {
    "unknown": 8
  },
  "window_seconds": 86400
}
```

### tier 해석

| 상태 | 결과 |
| --- | --- |
| model id가 `tiers.<tier>` 목록에 있음 | 해당 tier로 기록 |
| model id가 어떤 tier에도 없음 | 예약 tier `unknown`으로 기록하고 `TIER_UNKNOWN_MODEL` warning |
| `fanout_caps.<tier>`가 있음 | window 안의 allowed dispatch agent 수가 cap을 넘으면 deny |
| `fanout_caps.<tier>`가 없음 | uncapped |
| policy 파일이 없거나 invalid | `TIER_POLICY_UNAVAILABLE` deny |

`unknown`도 일반 tier처럼 cap을 갖는다. `fanout_caps.unknown`이 없으면 `unknown`도 uncapped이며, 템플릿 정책은 `unknown: 8`을 둔다. 템플릿의 `top`과 `efficient`는 cap이 없어 gate 차원에서는 uncapped다.

<Info>
top-tier 제어는 gate의 `fanout_caps.top`보다 `master-ops/scripts/dispatch --top-approved "<reason>"`에서 처리한다. wrapper는 top tier 요청에 owner approval 문자열이 없으면 gate check 전에 exit `2`로 중단한다.
</Info>

## 환경 변수 override

| 변수 | 적용 범위 | 우선순위/효과 |
| --- | --- | --- |
| `INSTANCE_RUNTIME_CONFIG` | runtime core, `model-identity-probe` | `instance-runtime.json` 경로 override |
| `MOGUI_MASTER_HOST_RUNTIME` | runtime core, master-ops dispatch wrapper | master host runtime 값 override |
| `MASTER_HOST_RUNTIME` | runtime core | `MOGUI_MASTER_HOST_RUNTIME` 다음 fallback |
| `MOGUI_TRANSCRIPT_GLOB` | runtime core, `model-identity-probe` | transcript glob 값 override |
| `MOGUI_PRODUCT_REPO` | runtime core, 일부 ops script | primary product repo 값 override |
| `WORKSPACE_DESCRIPTOR` | workspace descriptor loader | descriptor 경로 override |
| `MOGUI_WORKSPACE_DESCRIPTOR` | workspace descriptor loader | `WORKSPACE_DESCRIPTOR` 다음 경로 override |
| `DISPATCH_TIER_POLICY` | dispatch gate, master-ops dispatch wrapper | tier policy 경로 override |
| `DISPATCH_GATE_LEDGER` | dispatch gate 기본 config | ledger path override |
| `MOGUI_INSTANCE_RUNTIME_CONFIG` | master-ops dispatch wrapper, hooks | ops wrapper가 읽을 instance runtime config 경로. wrapper가 이후 `INSTANCE_RUNTIME_CONFIG`로 export |

## Fail-closed 동작

| 표면 | 조건 | 결과 |
| --- | --- | --- |
| `instance-runtime.json` | 파일 없음 | load는 성공하지만 필요한 값의 `require_*`에서 unconfigured 오류 |
| `instance-runtime.json` | invalid JSON, root non-object, 잘못된 필드 타입 | `InstanceRuntimeConfigError` |
| `transcript_globs` | object가 아니거나 key/value가 빈 문자열 | `InstanceRuntimeConfigError` |
| `model-identity-probe` | transcript 위치 미설정, glob match 없음, invalid transcript, drift | exit `2` |
| `workspace-descriptor.json` | 파일 없음 | `workspace-descriptor-check` exit `2` |
| `workspace-descriptor.json` | invalid UTF-8/JSON, root non-object, non-plain flag, invalid role, duplicate identity | `WorkspaceDescriptorError` |
| repository lookup | 알 수 없는 repo | 기본 금지. CLI `--allow-unknown-repo` 사용 시에만 허용 취급 |
| `model-tier-policy.json` | 파일 없음, invalid JSON, invalid schema | dispatch gate deny `TIER_POLICY_UNAVAILABLE` |
| dispatch request | `model` 없음 | deny `NO_MODEL` |
| dispatch request | `completion_channel` 없음 또는 허용값 아님 | deny `NO_COMPLETION_CHANNEL` |
| contract | 크기 측정 실패 또는 파일 없음 | deny `CONTRACT_UNREADABLE` |
| model verification | 측정 model이 선언 model보다 더 엄격한 tier | register deny `MODEL_TIER_ESCALATION` |
| model verification | 측정 불가 또는 probe 실패 | allow + `MODEL_UNVERIFIED` 또는 `MODEL_PROBE_FAILED` warning |

## 검증 명령

```bash
python3 -m pytest \
  tests/test_instance_runtime_config.py \
  tests/test_workspace_descriptor.py \
  tests/test_dispatch_gate.py
```

```bash
scripts/model-identity-probe \
  --config config/instance-runtime.json \
  --runtime claude \
  --expect claude-fable-5
```

```bash
scripts/workspace-descriptor-check \
  --config config/workspace-descriptor.json \
  --path product-app \
  --action force-push \
  --json
```

```bash
scripts/dispatch-gate \
  --ledger ~/.mogui/dispatch-ledger.jsonl \
  check \
  --runtime codex \
  --model gpt-5.6-luna \
  --tier-policy config/model-tier-policy.json \
  --contract /path/to/contract.md \
  --agents 1 \
  --est-chars 3000 \
  --completion-channel orchestration
```

## Related pages

<CardGroup>
  <Card title="설치" href="/installation">
    인스턴스 설정 파일을 생성하고 검증하는 설치 전후 절차.
  </Card>
  <Card title="작업자 위임" href="/dispatch-workers">
    dispatch gate, contract, register probe, completion channel의 실행 흐름.
  </Card>
  <Card title="모델 식별과 drift 감사" href="/model-identity">
    transcript glob과 expected model을 사용한 모델 검증 경로.
  </Card>
  <Card title="CLI 참조" href="/cli-reference">
    `dispatch-gate`, `model-identity-probe`, `workspace-descriptor-check`의 옵션과 exit code.
  </Card>
</CardGroup>