# Overview

> 공개 표면, Orca 런타임 전제, 마스터/워커 역할, 네트워크·API 키 없음 제약, 그리고 다음에 읽어야 할 문서 경로.

- 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

- `README.md`
- `docs/public/overview.md`
- `docs/README.md`
- `AGENTS.md`
- `src/master_runtime/core/__init__.py`
- `INSTALL-PROMPT.txt`

---

---
title: "Overview"
description: "공개 표면, Orca 런타임 전제, 마스터/워커 역할, 네트워크·API 키 없음 제약, 그리고 다음에 읽어야 할 문서 경로."
---

`mogui-ADE-orchestrator`는 멀티 저장소 워크스페이스에서 장수명 에이전트 세션을 조율하는 **워크스페이스 마스터 런타임**이다. 모델 API를 호출하지 않으며 in-process 에이전트 프레임워크가 아니다. 실행 단위는 Orca ADE의 실제 터미널·worktree·orchestration task/mailbox이고, 의사결정 로직은 `src/master_runtime/core/`의 stdlib-only Python과 `scripts/` CLI에 있다.

## 공개 표면

설치·운영·기여가 만나는 표면은 네 층으로 나뉜다.

| 표면 | 경로 | 역할 |
| --- | --- | --- |
| 공개 CLI | `scripts/` | 부트, succession, dispatch gate, acceptance, redaction, descriptor, worker reap |
| 코어 라이브러리 | `src/master_runtime/core/` | 순수/주입 가능한 유닛 로직 (bootstrap, succession, lineage, dispatch_gate, acceptance, …) |
| 공개 설명 문서 | `docs/public/` | 문제·개념·수명주기·위임·레퍼런스 (이 저장소에 고정) |
| 운영 템플릿 | `master-ops/` | 온보딩이 복사·치환해 별도 ops 저장소를 만드는 Stage 2 템플릿 |

```text
mogui-ADE-orchestrator/
├── scripts/                 # 공개 명령 표면
├── src/master_runtime/core/ # U1–U12에 대응하는 런타임 유닛
├── config/                  # instance-runtime·tier-policy·descriptor 예제
├── docs/public/             # 인간/에이전트용 설명
├── master-ops/              # 온보딩 라우터 + 치환 템플릿
└── tests/                   # 유닛·CLI·게이트 계약 테스트
```

`docs/internal/`은 기여자 메모·스펙이며 코드와 어긋나면 **코드와 테스트가 우선**이다. `master-ops/`의 `{{PLACEHOLDER}}`는 이 저장소 안에서 채우지 않는다. Stage 1 온보딩이 새 ops 저장소로 복사한 뒤에만 치환한다.

### 공개 CLI (요약)

| 명령 | 목적 |
| --- | --- |
| `scripts/master-bootstrap` / `master-bootstrap-live` | 경계 있는 L0/L1 부트 블록 생성, session-start 훅 |
| `scripts/master-succeed` | succession detect · handoff · spawn · verify · retire · duplicates |
| `scripts/dispatch-gate` | worker dispatch `check` → `register` · `watch` · `report` |
| `scripts/acceptance-loop` | casebook 기반 독립 수락 루프 |
| `scripts/worker-reap` | settled worker terminal/worktree 정리 |
| `scripts/model-identity-probe` / `model-drift-audit` | transcript 기반 모델 신원·드리프트 |
| `scripts/workspace-descriptor-check` | sibling repo 금지 액션 조회 |
| `scripts/redaction-scan.sh` / `redaction-inventory` | 게시 전 redaction 게이트 |
| `scripts/onboarding-preflight.sh` | founding 전 도구·런타임 측정 |
| `scripts/adapter doctor` | 어댑터 계층 로컬 도구 존재 여부 |

전체 하위 명령·플래그·exit 코드는 [CLI 레퍼런스](/cli-reference)를 본다. 표 행은 `tests/test_reference_command_table.py`가 `scripts/* --help`와 동기화한다.

## Orca 런타임 전제

Orca는 이 시스템이 추상화하지 않는 **필수 실행 기판**이다. `master-ops/ONBOARDING.md`는 “Orca is REQUIRED infrastructure. Supervised dispatch = orca orchestration only.”로 고정한다. Step 0 preflight(`scripts/onboarding-preflight.sh`)는 사용 가능한 `orca`와 ready 런타임이 없으면 founding을 `BLOCKED`로 막는다.

| 능력 | Orca 없이 | Orca 와 함께 |
| --- | --- | --- |
| 세션 수명 | 창/탭에 묶임 | 창을 닫아도 handle로 주소 지정 가능 |
| 완료 감지 | 화면 폴링 | Run mailbox (`worker_done` 등) |
| 배치(placement) | 추론·cwd 추측 | worktree/folder workspace selector로 검증 |
| 마스터 세션 | 지원하지 않음 | founding spawn → Gen-1 master |

<Warning>
stdlib 순수 함수(`dispatch-gate check`, `master-succeed detect` 등)는 Orca 없이 호출 가능하다. 라이브 마스터 세션·supervised dispatch·retire/spawn은 Orca 없이 지원하지 않는다.
</Warning>

Orca 객체 모델의 최소 어휘:

| 객체 | 의미 |
| --- | --- |
| Project | Orca에 등록한 폴더(단일 저장소, sibling 다수 저장소 루트, 빈 폴더) |
| Folder workspace / repository worktree | 세션이 앉는 seat. 마스터는 보통 workspace-level folder workspace |
| Terminal | 에이전트가 돌아가는 라이브 세션 |
| Run | task·dispatch·mailbox를 담는 내구성 orchestration 컨텍스트 |

선택자 형식·“Unavailable worktree” 라벨 오해는 [Orca 객체 모델](/orca-object-model)에 정리한다.

## 마스터와 워커

### 마스터 (임시 역할)

마스터는 프로세스 이름이 아니라 **운영 역할**이다. 온보딩 시 callsign을 고른다(문서·UI 라벨 “master”는 역할 표기). 책임:

- 계획·작업 분해·크로스 저장소 라우팅
- 계약 기반 worker dispatch와 예산/티어 게이트
- worker self-report와 **독립된** 증거 검증·수락
- context pressure 시 clean succession (advisory는 제안만, auto-succeed 없음)
- Role State·charter·tracker/git 기록 유지

부트는 `bootstrap` / `bootstrap_live`가 charter·handoff·Role State로 경계 있는 L0/L1 블록을 만든다. compaction 시 Role State/active-tracks를 의도적으로 생략해 recall probe를 건다.

### 워커

워커는 Orca pane 안의 **실제 CLI 세션**이다(Claude, Codex, Cursor, Grok, Gemini 등). 플러그인 없이 터미널에서 기동한 바이너리 그대로다. 워커는 좁은 **계약 파일**을 받고 artifact+증거를 반환한다. 격리 단위는 git worktree이며 가상 파일시스템이 아니다.

```text
check  →  dispatch  →  register  →  독립 검증  →  acceptance
 (gate)   (Orca)       (probe)      (master)      (casebook/리뷰)
```

`dispatch_gate`의 `ReasonCode` 예: `OK`, `BUDGET_EXCEEDED`, `TIER_FANOUT_CAP`, `NO_COMPLETION_CHANNEL`, `CONTRACT_UNREADABLE`, `PATH_OUTSIDE_KNOWN_ROOTS`, `MODEL_PROBE_FAILED`, …

### 역할 경계 (형제 프로젝트)

| | 이 저장소 | mogui-agent-harness (형제) |
| --- | --- | --- |
| 계층 | Workspace Master Runtime | Repository Harness |
| 단위 | 다수 저장소 워크스페이스 | 단일 저장소 |
| 소유 | 조율 상태, 역할, succession, lineage, dispatch | repo-local rules, hooks, wiki, runbooks |
| 결합 | **계약만** — 소스 트리 결합 없음 | 동일 |

```mermaid
flowchart TB
  subgraph WS["워크스페이스 계층"]
    M["master session<br/>plan · gate · verify · succeed"]
  end
  subgraph Orca["Orca"]
    WT1["worker worktree / CLI"]
    WT2["worker worktree / CLI"]
    M2["successor master"]
  end
  subgraph Durable["내구성 상태"]
    T[("tracker / ledger")]
    G[("git: charter · decisions · lineage")]
  end
  You(["operator"]) -->|"지시"| M
  M -->|"contract"| WT1
  M -->|"contract"| WT2
  WT1 -->|"artifact + evidence claim"| M
  WT2 -->|"artifact + evidence claim"| M
  M --> T
  M --> G
  M -->|"verified handoff"| M2
  G -.->|"boot"| M2
```

## 네트워크·API 키 없음 제약

이 런타임은 **로컬 전용**으로 설계되었다.

| 제약 | 측정/구현 |
| --- | --- |
| 네트워크 import 없음 | `src/`·`scripts/`에 `urllib`/`http`/`socket`/`ssl`/`requests` import 없음 |
| API 키·모델 엔드포인트·텔레메트리 없음 | 코어가 프로바이더를 호출하지 않음 |
| 읽기 범위 | 지정한 폴더·config 경로. 홈 디렉터리 전역 스캔 없음 |
| Redaction | 추적 파일은 `git ls-files` 경유; gitleaks + 선택 조직 규칙 |
| 에이전트 CLI 트래픽 | 각 CLI가 기존 구독/엔드포인트로 통신 — 이 저장소가 키를 추가하지 않음 |

스택 채택 5문항 기준(README / CONTRIBUTING): API 키 강제 여부, 불필요 텔레메트리, 관리 지점 추가 여부, 1인 이상 확장, “에이전트 컨텍스트” 외에 실제로 푸는 문제.

<Note>
in-process 하네스(예: API 키를 들고 그래프를 소유하는 라이브러리)와 비교하면, 여기서 subagent는 프로세스 내부 actor가 아니라 **계약 아래 실제 CLI 세션**이고, 파일시스템은 worktree이며, 인터럽트는 사람이 쥐는 approval gate다. 오케스트레이터 세션 자체를 교체하는 succession은 in-process 그래프 모델에 대응물이 없다.
</Note>

### 호스트·플랫폼 한계 (정직한 상태)

- 기본 master spawn 경로는 Claude Code(`claude`)를 호출한다. 설계상 필수 벤더는 아니나, 실측·권장은 Claude Code 쪽이다.
- Codex를 master로 쓰는 경로는 미실측(unsupported가 아니라 untested).
- 실측 OS는 macOS. Orca는 Linux/Windows 빌드를 제공하나 이 저장소에서 전부 검증하지 않았다.
- U4(Repository Runtime Loader) 등 일부 런타임 유닛은 설계 어휘만 있거나 부분 구현이다 — [런타임 유닛](/runtime-units).

## 핵심 메커니즘 (한 페이지 맵)

| 영역 | 메커니즘 | 공개 진입점 |
| --- | --- | --- |
| Execution | Orca terminal · worktree · Run | host CLI + seat 규칙 |
| Context | L0/L1 bootstrap, Role State, compaction probe | `master-bootstrap`, `master-bootstrap-live` |
| Delegation | contract hash, tier×fan-out, ledger, model probe | `dispatch-gate check/register` |
| Steering | Proposal → Approval → Execution, Role State | `approval/`, 운영 정책 |
| Succession | IMMEDIATE/ADVISORY detect, handoff, placement spawn, verify, retire | `master-succeed` |
| Lineage | 고정 스키마 append-only ledger (결정 입력 아님) | `lineage.py` + ops 문서 |
| Acceptance | casebook · holdout · scorecard (self-report ≠ proof) | `acceptance-loop` |
| Defense | placement mismatch exit 26, empty-seat, redaction, revival | [방어 인벤토리](/defense-inventory) |

운영 규칙 한 줄: **worker의 `worker_done`은 claim**이다. 수락은 재검증·diff·artifact·redaction·(해당 시) acceptance suite로 한다.

## 문서 세트와 읽는 순서

| 세트 | 독자 | 수명 |
| --- | --- | --- |
| `docs/public/` | 시스템 설명 독자 | 이 저장소에 고정 |
| `master-ops/` | 설치자 + 이후 master 에이전트 | 새 ops 저장소로 복사·치환 |
| `docs/internal/` | 기여자 | 빠르게 낡음; 코드가 우선 |

에이전트 세션이 구체 작업 없이 클론만 열리면 `AGENTS.md` / `CLAUDE.md` / `INSTALL-PROMPT.txt`가 `master-ops/ONBOARDING.md` 라우터로 보낸다. 단계 파일은 **한 턴에 하나**, Verify 통과 후에만 다음 파일을 연다.

## 첫 검증 신호 (Orca 없이도 가능)

```console
$ scripts/master-succeed detect "routine status update" --context-ratio 0.7 --json
$ scripts/dispatch-gate --ledger /tmp/gate.jsonl check \
  --runtime codex --model grok-4.5 --contract README.md \
  --agents 1 --est-chars 1000 --completion-channel orchestration
$ scripts/adapter doctor
```

라이브 경로(클론 → Orca shell command → wake-up → Gen-1 → 첫 supervised worker)는 [Installation](/installation)과 [Quickstart](/quickstart)를 따른다.

## Next

<CardGroup>
  <Card title="Installation" href="/installation">
    Orca·에이전트 CLI·git·gh·python3·bd·skills 전제조건, preflight FAIL/WARN, 셸 명령 등록.
  </Card>
  <Card title="Quickstart" href="/quickstart">
    wake-up 온보딩부터 Generation 1 부트·첫 supervised worker까지 최단 성공 경로.
  </Card>
  <Card title="런타임 유닛" href="/runtime-units">
    U1–U12 책임 경계, L0/L1, bootstrap·dispatch·succession·lineage 대응표.
  </Card>
  <Card title="Orca 객체 모델" href="/orca-object-model">
    project·folder workspace·worktree·terminal·Run, 마스터 좌석, selector 형식.
  </Card>
  <Card title="마스터 라이프사이클" href="/master-lifecycle">
    founding spawn → steady state → clean succession → lineage 루프.
  </Card>
  <Card title="Supervised dispatch" href="/supervised-dispatch">
    check → dispatch → register, 계약 해시·ledger, model probe, orchestration 완료 채널.
  </Card>
  <Card title="온보딩" href="/onboarding">
    ONBOARDING 라우터, 1회 1단계 로드, Stage 1/2, founding spawn.
  </Card>
  <Card title="CLI 레퍼런스" href="/cli-reference">
    scripts/ 공개 명령 표와 비공개 표면 경계.
  </Card>
</CardGroup>