# mogui-ADE-orchestrator 문서
> Orca ADE 위에서 장기 마스터 세션, 워커 디스패치, 승계, 라인지를 운영하는 워크스페이스 오케스트레이션 런타임의 공개 표면, 설치, CLI, 설정, 운영 절차를 정리한 기술 문서입니다. 설치·운영자, 마스터 에이전트, 기여자가 스크립트·스키마·가드 경계를 그대로 참조할 때 사용합니다.
## Context Links
- [Agent index](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/llms.txt)
- [Human interactive docs](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac)
## Repository Metadata
- Repository: local/mogui-ADE-orchestrator
- Generated: 2026-08-07T07:09:27.222Z
- Updated: 2026-08-07T08:06:25.549Z
- Runtime: Grok CLI
- Format: Documentation
- Pages: 22
## Page Index
- 01. [Overview](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/01-overview.md) - 공개 표면, Orca 런타임 전제, 마스터/워커 역할, 네트워크·API 키 없음 제약, 그리고 다음에 읽어야 할 문서 경로.
- 02. [Installation](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/02-installation.md) - Orca·에이전트 CLI·git·gh·python3·bd·skills 전제조건, preflight FAIL/WARN, 셸 명령 등록, 클론 후 측정 신호.
- 03. [Quickstart](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/03-quickstart.md) - 클론 → Orca 준비 → wake-up 온보딩 → Generation 1 부트 → 첫 supervised worker까지 최단 성공 경로와 검증 신호.
- 04. [런타임 유닛](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/04-page-4.md) - U1–U12 책임 경계, L0/L1 컨텍스트, 부분 구현 유닛, bootstrap·dispatch·succession·lineage 모듈 대응표.
- 05. [Orca 객체 모델](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/05-orca.md) - project·folder workspace·worktree·terminal·Run, 마스터 좌석 규칙, 검증된 selector 형식, 오해하기 쉬운 UI 라벨.
- 06. [마스터 라이프사이클](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/06-page-6.md) - founding spawn → boot measurement → steady state → clean succession → lineage 기록 루프와 Role State·compaction 규칙.
- 07. [증거와 수락](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/07-page-7.md) - 워커 self-report와 독립 검증 구분, 계약 필드, 리뷰 렌즈, acceptance 판정 규칙과 측정 가능한 증거 형태.
- 08. [프로그레시브 온보딩](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/08-page-8.md) - ONBOARDING 라우터, 단계 파일 1회 1로드·Verify 후 진행, Stage 1/2, founding spawn, 템플릿 치환 경계.
- 09. [Supervised dispatch](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/09-supervised-dispatch.md) - check → dispatch → register 흐름, 계약 해시·ledger, model probe, Codex/Cursor pretrust, 완료 채널 orchestration.
- 10. [Clean succession](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/10-clean-succession.md) - handoff 작성, placement 검증 spawn, successor 검증, predecessor retire, revival 측정, lineage 스키마 필드.
- 11. [인스턴스 설정](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/11-page-11.md) - instance-runtime·model-tier-policy 작성, env 우선순위, transcript glob, master host runtime, 티어×fan-out 캡.
- 12. [Workspace descriptor](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/12-workspace-descriptor.md) - sibling 저장소 인벤토리, role·capabilities·prohibited, master_seat, workspace-descriptor-check 액션과 해석 순서.
- 13. [Redaction gates](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/13-redaction-gates.md) - redaction-scan 범위·exit, REDACTION_REQUIRE_EXTRA, inventory 역검사, gitleaks 설정, 스테이징 전제와 pre-push 훅.
- 14. [CLI 레퍼런스](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/14-cli.md) - scripts/ 공개 명령 표, 하위 명령 목적, 주요 옵션, --help 동기화 테스트 계약과 비공개 표면 경계.
- 15. [Configuration reference](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/15-configuration-reference.md) - JSON 키·기본값·필수/선택, INSTANCE_RUNTIME_CONFIG·DISPATCH_TIER_POLICY·WORKSPACE_DESCRIPTOR·MOGUI_* 환경 변수 해석 순서.
- 16. [dispatch-gate 레퍼런스](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/16-dispatch-gate.md) - check·register·watch·report 플래그, ledger 스키마, reason code, 티어 정책 해석, 티켓 TTL, 기본 문자 한도.
- 17. [master-succeed 레퍼런스](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/17-master-succeed.md) - detect·handoff·verify-successor·check-duplicates·retire·spawn 옵션, exit 코드, SPAWN_PLACEMENT_MISMATCH, JSON 출력.
- 18. [acceptance-loop 레퍼런스](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/18-acceptance-loop.md) - validate·split·run·inspect 하위 명령, 스위트 구조, holdout, max-iterations, baseline/restore, 판정 산출물.
- 19. [방어 인벤토리](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/19-page-19.md) - 디스패치 게이트, 모델 신원 프로브, placement·empty-seat·duplicate, redaction, revival, progressive onboarding 가드 표.
- 20. [Worker reap](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/20-worker-reap.md) - lease 상태 issued→reaped, settled 검증, terminal close, worktree 정리, --dry-run·--ledger, 거부 exit 코드.
- 21. [Troubleshooting](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/21-troubleshooting.md) - preflight BLOCKED, placement mismatch, MODEL_PROBE_FAILED, undecidable exit 2, seat 중복, revival, 복구 프로브.
- 22. [Contributing](https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/22-contributing.md) - 5문항 스택 기준, pytest 실행, exit 코드 규약, redaction 게이트, master-ops 템플릿 경계, 릴리스 cut·CHANGELOG.
## Source File Index
- `.github/workflows/gates.yml`
- `AGENTS.md`
- `CHANGELOG.md`
- `config/gitleaks.toml`
- `config/instance-runtime.example.json`
- `config/model-tier-policy.example.json`
- `config/workspace-descriptor.example.json`
- `CONTRIBUTING.md`
- `docs/internal/release-runbook.md`
- `docs/internal/tooling/redaction-scan.md`
- `docs/public/concepts.md`
- `docs/public/defense-inventory.md`
- `docs/public/delegation-and-review.md`
- `docs/public/getting-started.md`
- `docs/public/master-lifecycle.md`
- `docs/public/orca-concepts.md`
- `docs/public/overview.md`
- `docs/public/reference.md`
- `docs/README.md`
- `docs/runbooks/worker-reap.md`
- `hooks/pre-push`
- `INSTALL-PROMPT.txt`
- `master-ops/docs/charter/04-worker-routing-review.md`
- `master-ops/docs/charter/05-dispatch-gate.md`
- `master-ops/docs/charter/06-succession.md`
- `master-ops/docs/MASTER-OPERATIONS.md`
- `master-ops/docs/runbooks/contract-conventions.md`
- `master-ops/docs/runbooks/error-and-logging.md`
- `master-ops/docs/runbooks/role-state.md`
- `master-ops/docs/runbooks/succession-boot-card.md`
- `master-ops/MANIFEST.json`
- `master-ops/model-tier-policy.json`
- `master-ops/ONBOARDING.md`
- `master-ops/onboarding/00-orientation.md`
- `master-ops/onboarding/01-preflight.md`
- `master-ops/onboarding/02-workspace-facts.md`
- `master-ops/onboarding/04-seat.md`
- `master-ops/onboarding/09-spawn.md`
- `master-ops/onboarding/10-card-and-retire.md`
- `master-ops/scripts/dispatch`
- `README.md`
- `scripts/acceptance-loop`
- `scripts/adapter`
- `scripts/codex-worker-pretrust`
- `scripts/cursor-worker-pretrust`
- `scripts/dispatch-gate`
- `scripts/generate-manifest`
- `scripts/l1-digest`
- `scripts/master-bootstrap`
- `scripts/master-bootstrap-live`
- `scripts/master-recover`
- `scripts/master-succeed`
- `scripts/model-drift-audit`
- `scripts/model-identity-probe`
- `scripts/next-version`
- `scripts/onboarding-preflight.sh`
- `scripts/redaction-allowlist.txt`
- `scripts/redaction-inventory`
- `scripts/redaction-scan.sh`
- `scripts/worker-reap`
- `scripts/workspace-descriptor-check`
- `SECURITY.md`
- `src/master_runtime/core/__init__.py`
- `src/master_runtime/core/acceptance/casebook.py`
- `src/master_runtime/core/acceptance/config.py`
- `src/master_runtime/core/acceptance/loop.py`
- `src/master_runtime/core/acceptance/verdict.py`
- `src/master_runtime/core/adapter/doctor.py`
- `src/master_runtime/core/approval/gates.py`
- `src/master_runtime/core/bootstrap_live.py`
- `src/master_runtime/core/bootstrap.py`
- `src/master_runtime/core/context/resolver.py`
- `src/master_runtime/core/dispatch_gate.py`
- `src/master_runtime/core/instance_runtime_config.py`
- `src/master_runtime/core/lineage.py`
- `src/master_runtime/core/recovery.py`
- `src/master_runtime/core/succession.py`
- `src/master_runtime/core/work_ledger.py`
- `src/master_runtime/core/worker_reap.py`
- `src/master_runtime/core/workspace_descriptor.py`
- `tests/conftest.py`
- `tests/test_acceptance_loop.py`
- `tests/test_dispatch_gate.py`
- `tests/test_documented_reason_codes.py`
- `tests/test_instance_runtime_config.py`
- `tests/test_onboarding_preflight.py`
- `tests/test_onboarding_structure.py`
- `tests/test_recovery.py`
- `tests/test_redaction_scan_native_script.py`
- `tests/test_reference_command_table.py`
- `tests/test_succession.py`
- `tests/test_worker_reap.py`
- `tests/test_workspace_descriptor.py`
---
## 01. Overview
> 공개 표면, Orca 런타임 전제, 마스터/워커 역할, 네트워크·API 키 없음 제약, 그리고 다음에 읽어야 할 문서 경로.
- Page Markdown: https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/01-overview.md
- Generated: 2026-08-07T07:02:12.892Z
### 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 |
stdlib 순수 함수(`dispatch-gate check`, `master-succeed detect` 등)는 Orca 없이 호출 가능하다. 라이브 마스터 세션·supervised dispatch·retire/spawn은 Orca 없이 지원하지 않는다.
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
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인 이상 확장, “에이전트 컨텍스트” 외에 실제로 푸는 문제.
in-process 하네스(예: API 키를 들고 그래프를 소유하는 라이브러리)와 비교하면, 여기서 subagent는 프로세스 내부 actor가 아니라 **계약 아래 실제 CLI 세션**이고, 파일시스템은 worktree이며, 인터럽트는 사람이 쥐는 approval gate다. 오케스트레이터 세션 자체를 교체하는 succession은 in-process 그래프 모델에 대응물이 없다.
### 호스트·플랫폼 한계 (정직한 상태)
- 기본 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
Orca·에이전트 CLI·git·gh·python3·bd·skills 전제조건, preflight FAIL/WARN, 셸 명령 등록.
wake-up 온보딩부터 Generation 1 부트·첫 supervised worker까지 최단 성공 경로.
U1–U12 책임 경계, L0/L1, bootstrap·dispatch·succession·lineage 대응표.
project·folder workspace·worktree·terminal·Run, 마스터 좌석, selector 형식.
founding spawn → steady state → clean succession → lineage 루프.
check → dispatch → register, 계약 해시·ledger, model probe, orchestration 완료 채널.
ONBOARDING 라우터, 1회 1단계 로드, Stage 1/2, founding spawn.
scripts/ 공개 명령 표와 비공개 표면 경계.
---
## 02. Installation
> Orca·에이전트 CLI·git·gh·python3·bd·skills 전제조건, preflight FAIL/WARN, 셸 명령 등록, 클론 후 측정 신호.
- Page Markdown: https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/02-installation.md
- Generated: 2026-08-07T07:02:16.815Z
### Source Files
- `docs/public/getting-started.md`
- `scripts/onboarding-preflight.sh`
- `README.md`
- `tests/test_onboarding_preflight.py`
- `INSTALL-PROMPT.txt`
- `master-ops/ONBOARDING.md`
---
title: "Installation"
description: "Orca·에이전트 CLI·git·gh·python3·bd·skills 전제조건, preflight FAIL/WARN, 셸 명령 등록, 클론 후 측정 신호."
---
설치 게이트는 `scripts/onboarding-preflight.sh`다. 클론 후 이 스크립트가 호스트 도구, Orca 런타임·orchestration Run, skills 아티팩트, 조직 redaction 규칙, 에이전트/워커 CLI, 디스패치 레저 경로를 한 번에 측정하고, 필수 항목이 비면 exit 1과 `BLOCKED`로 founding을 막는다. 애플리케이션 설치는 수동이며, `--fix`는 전역 Orca skills 추가·갱신만 수행한다.
## 설치 경계
| 구분 | 내용 |
| --- | --- |
| 런타임 기판 | Orca 앱 + 셸에 등록된 CLI (`orca` / `orca-dev` / `orca-ide`) |
| 측정 게이트 | `bash scripts/onboarding-preflight.sh` (Step 0, `master-ops/onboarding/01-preflight.md`) |
| 에이전트 경로 | 클론 루트에서 태스크 없이 wake-up → `master-ops/ONBOARDING.md` 라우터 |
| 비대상 | 제품 코드 배포, 네트워크 API 키, CI 설치 파이프라인 |
이 저장소는 workspace/orchestrator 런타임과 ops 템플릿이다. 마스터 세션은 Orca 터미널에서 살고, preflight 없이 라이브 마스터를 띄우는 경로는 지원되지 않는다.
## 전제조건 (FAIL / WARN)
판정은 preflight 출력 라벨을 따른다.
- **FAIL** → `FAIL` 인쇄, failures 카운트, 종료 요약 `BLOCKED`, exit **1** (또는 `PREFLIGHT_WAIVE`로 명시 면제)
- **WARN** → `WARN` 인쇄, 단독으로는 exit 1을 만들지 않음. `ESSENTIAL_LABELS`에 속하면 요약의 essential 블록에 재강조
### FAIL — founding 차단
| 라벨 | 요구 | 부재 시 신호 |
| --- | --- | --- |
| `orca` | CLI 존재, basename이 `orca`·`orca-dev`·`orca-ide`, `status --json`에 `"ok": true` | 설치/셸 등록 힌트 포함 FAIL |
| `orchestration` | Orca ready 후 `orchestration run-current --json`: RPC ok, 비-legacy Run 바인딩, `legacy_read_only` 아님 | `run-create` 안내; 앱 재시작만으로는 legacy coordinator 미해결 |
| `skills` | 디스크에 `orca-cli`+`orchestration` 스킬 디렉터리, 또는 skills 패키지 전역 목록에 둘 다 존재 | 설치 명령 안내; `--fix`로 전역 추가 가능 |
| `agent-cli` | `ORCA_AGENT_CLI` 설정 + 해당 바이너리 `PATH` | unset이면 agent-specific 검사가 조용히 빠지므로 FAIL |
| `worker-runtime` | `codex` 또는 `cursor-agent` 중 **하나 이상** | 둘 다 없으면 FAIL; 하나만 있으면 나머지는 WARN |
| `bd` | `bd` 바이너리; ops 레포가 있으면 `bd where`가 그 안을 가리켜야 함 | 바이너리 없음 또는 ops 밖 해석 시 FAIL |
| `python3` | `PATH`의 `python3` | 버전 하한 없음; 엔트리포인트가 python3 스크립트 |
| `git` / `gh` | 바이너리 존재 | PR 관리 전제로 FAIL |
| `redaction-extra` | `REDACTION_EXTRA_PATTERNS` 또는 `~/.config/redaction-extra.txt`에 **컴파일 가능한 규칙 ≥1** | 내용 미인쇄, 개수만 보고; publish 게이트 2개가 거부 |
| `gate-ledger` | `DISPATCH_GATE_LEDGER`(기본 `.mogui/dispatch-ledger.jsonl`) 상위 디렉터리 생성·쓰기 가능 | 쓰기 불가 시 FAIL |
### WARN — 단독 비차단
| 라벨 | 조건 | 결과/비용 |
| --- | --- | --- |
| `gitleaks` | PATH 없음 | redaction 스캔이 결정 불가로 exit 2; 퍼블리시 전 설치 |
| `ctx` | 없거나 `ctx status` 실패 | 크로스-프로바이더 히스토리 조회 불가; 마스터 자체는 동작 |
| `skill-stack` | `superpowers` / `ponytail` 없음 | 마스터는 동작하나 방법론·절제 레이어 없이 다르게 동작 |
| `gh-auth` | `gh` 미인증, 또는 `workflow` 스코프 없음 | 푸시/PR 또는 Actions 워크플로 편집 실패 |
| `worker-runtime` | 나열된 런타임 중 일부만 없음 (다른 하나는 있음) | 단일 실행기로 라우팅하는 정상 구성 |
| `pytest` | 3.11+ pytest도 `uv`도 없음 | 테스트 게이트를 돌릴 에이전트에 둘 중 하나 필요 |
| `codex-plugin` | `ORCA_AGENT_CLI`가 claude/claude-code일 때만, Codex 플러그인 미설치 | Codex 워커 디스패치 호스트에 필요; 그 외 INFO skip |
### Essential 라벨
요약 끝 `!! ESSENTIAL COMPONENTS MISSING` 블록에 다시 찍히는 라벨:
`orca`, `orchestration`, `skills`, `agent-cli`, `worker-runtime`, `bd`, `python3`, `gitleaks`, `ctx`, `redaction-extra`, `skill-stack`
WARN이어도 essential이면 여기 반복된다. 마스터 spawn 전에 설치하거나, 거부와 수용 동작을 기록로 남겨야 한다.
## Orca 설치와 셸 명령 등록
Orca는 추상화 대상이 아니다. 세션 수명, 핸들, supervised dispatch 메일박스가 여기서만 성립한다.
### 플랫폼별 설치
```console
$ brew install --cask stablyai/orca/orca
```
앱과 번들 CLI 바이너리를 설치한다. Homebrew `--cask`는 macOS 전용이다.
[공식 다운로드](https://www.onorca.dev/download)를 사용한다. 유지자 보고: AppImage/`.deb`, Arch `yay -S stably-orca-bin`. Linux에서는 GNOME 스크린 리더 `orca`와 충돌을 피하기 위해 바이너리 이름이 `orca-ide`일 수 있다. 그 경우 preflight가 허용하는 basename을 쓰거나 `ORCA_CLI_COMMAND`로 경로를 지정한다.
### Shell command
앱을 연 뒤:
1. **Settings → Orca CLI**
2. **Shell command** 켜기
측정 성공 조건:
```console
$ command -v orca # 또는 orca-dev / orca-ide
$ orca status
# 기대: appRunning: true, runtimeState: ready
$ orca status --json
# 기대: "ok": true
```
앱이 닫혀 있으면 `orca open`이 런타임이 닿을 때까지 대기한다. UI 라벨이 빌드마다 바뀌어도 성공 판정은 위 측정이다.
### Orca CLI 해석 순서
preflight(및 동일 패턴을 쓰는 런북) 해석:
1. `ORCA_CLI_COMMAND` — 명시 경로/이름
2. `ORCA_DEV_REPO_ROOT` 설정 시 → `orca-dev`
3. 기본 → `orca`
지원 basename 외 이름은 `orca` FAIL이다.
## 저장소 클론과 Orca 등록
```console
$ git clone https://github.com/baksohyeon/mogui-ADE-orchestrator
$ cd mogui-ADE-orchestrator
```
두 개념을 섞지 않는다.
| 개념 | 역할 |
| --- | --- |
| 폴더 workspace root | 여러 레포를 묶는 절대 경로. 마스터 좌석 |
| 이 오케스트레이터 클론 | 설치 세션 자리 + 런타임/템플릿 소스. 마스터가 영구 거주하는 곳이 아님 |
```console
$ orca repo add --path
```
Orca UI에서 프로젝트를 추가해도 된다. 이후 **해당 프로젝트 안** 터미널에서 작업 디렉터리가 클론(또는 의도한 install seat)인지 `pwd`로 확인한다. 프로젝트 밖 셸에서 시작하면 placement/spawn이 잘못된 좌석을 측정한다.
## 클론 후 측정 신호
### Preflight 실행
```console
$ cd
$ ORCA_AGENT_CLI=claude bash scripts/onboarding-preflight.sh
```
| 옵션/환경 | 의미 |
| --- | --- |
| (인자 없음) | 읽기 전용 측정. 상태 변경 없음 |
| `--fix` | 승인 후: `skills add stablyai/orca -g --skill orca-cli --skill orchestration` 및 `update orchestration -g`. 앱 설치는 하지 않음 |
| 잘못된 인자 | `Usage: … [--fix]`, exit **2** |
#### 환경 변수
| 변수 | 역할 |
| --- | --- |
| `ORCA_AGENT_CLI` | 마스터 호스트 CLI 이름. unset → `agent-cli` FAIL |
| `ORCA_CLI_COMMAND` | Orca CLI 경로 오버라이드 |
| `ORCA_DEV_REPO_ROOT` | 설정 시 `orca-dev` 선택 |
| `ORCA_SKILLS_DIRS` | `:` 구분 skills 루트 오버라이드 (미설정 시 `~/.claude/skills`, `~/.agents/skills`, `~/.codex/skills` 등) |
| `REDACTION_EXTRA_PATTERNS` | 조직 규칙 파일 경로 (기본 `~/.config/redaction-extra.txt`) |
| `DISPATCH_GATE_LEDGER` | 디스패치 레저 경로 (기본 `.mogui/dispatch-ledger.jsonl`) |
| `PREFLIGHT_WAIVE` | 쉼표 구분 라벨. 해당 FAIL을 인쇄·카운트되는 `WAIVED`로 강등 |
규칙 파일 한 줄 형식: `id|description|regex` (빈 줄·`#` 주석 무시, 정규식 컴파일 필수). preflight는 규칙 본문을 절대 출력하지 않는다.
### 요약 판정
| 출력 | exit | 의미 |
| --- | --- | --- |
| `READY: all required checks passed` | 0 | 필수 전부 PASS |
| `READY WITH WAIVERS: … downgraded, not satisfied` | 0 | 일부 FAIL이 면제됨. 충족이 아님 |
| `BLOCKED: fix every FAIL before onboarding` | 1 | 면제되지 않은 FAIL 존재 |
| `NOTE: PREFLIGHT_WAIVE named checks that did not run: … still enforced` | (해당 FAIL 유지) | 오타 면제 — 검사는 그대로 강제 |
| `!! ESSENTIAL COMPONENTS MISSING` | — | essential 갭 재나열 + 결과 문구 |
예시 (성공 요약 형태):
```text
INFO resolved Orca CLI: orca
PASS orca orca status --json returned ok:true
PASS orchestration RPC reachable and a non-legacy Run is bound to this terminal
…
Preflight summary
PASS: N
WARN: M
FAIL: 0
WAIVED: 0
READY: all required checks passed
```
### 세션 상태 신호 (도구 설치 외에 필요한 것)
| 신호 | 측정 | 복구 |
| --- | --- | --- |
| Orca runtime ready | `orca status` / `--json` ok | 앱 실행, Shell command, `orca open` |
| non-legacy Run 바인딩 | `orca orchestration run-current --json` | `orca orchestration run-create` |
| legacy coordinator | `legacy_read_only` / `effectsApplied:false` | 새 Run 생성 (앱 재시작만으로는 미해결) |
| Run null | `"run": null` | 동일하게 `run-create`; 바인딩 소실 후 empty mailbox와 구분 어려움 |
| agent CLI 선택 | `ORCA_AGENT_CLI` + `command -v` | onboarding이 설정; 바이너리는 그 전에 설치 |
### 조직 redaction 규칙 최소 스캐폴드
```console
$ mkdir -p ~/.config
$ printf '%s\n' 'org-example|example pattern only|EXAMPLE_SECRET_[0-9]+' > ~/.config/redaction-extra.txt
```
실제 조직 패턴으로 교체한다. 버전 관리에 올리지 않는다.
### Skills 수동 설치 (preflight 힌트와 동일)
아티팩트가 없고 skills 실행기가 있을 때:
```console
$ skills add stablyai/orca -g --skill orca-cli --skill orchestration
$ skills update orchestration -g
```
또는 `bash scripts/onboarding-preflight.sh --fix` (skills 명령이 가용할 때).
## 설치 절차 (사람 경로)
플랫폼에 맞게 Orca를 설치하고 앱을 연다. **Settings → Orca CLI → Shell command**를 켠 뒤 `orca status`가 ready/`ok:true`인지 확인한다.
마스터용 에이전트 CLI, 워커 런타임(`codex` 및/또는 `cursor-agent`), `git`, `gh`, `python3`, `bd`를 PATH에 둔다. 퍼블리시 예정이면 `gitleaks`, 히스토리 조회면 `ctx`. 조직 redaction 규칙 파일을 만든다.
이 저장소를 클론하고, workspace root(또는 임시 install seat)를 `orca repo add --path`로 등록한다. Orca 터미널을 그 프로젝트 안에서 연다.
`ORCA_AGENT_CLI= bash scripts/onboarding-preflight.sh`를 실행한다. `BLOCKED`면 FAIL을 고친다. 정당한 불가 항목만 `PREFLIGHT_WAIVE=
같은 터미널에서 에이전트 CLI를 시작하고, 구체 태스크 없이 wake-up 문구만 준다. 에이전트는 `master-ops/ONBOARDING.md`만 라우터로 읽고 세션 모드(Founding / Reverify / Upgrade / Template improve)를 묻는다. Founding은 ops 레포·lineage가 없을 때만.
에이전트 호스트가 루트 `CLAUDE.md`/`AGENTS.md`를 자동 로드하지 않으면 `INSTALL-PROMPT.txt` 문구로 동일 라우터 경로를 강제한다. Orca가 준비되지 않았으면 설치·기동 안내 후 중단한다.
## Preflight 이후 onboarding이 남기는 인스턴스 파일
Step 0 Verify는 다음을 요구한다 (커밋하지 않는 인스턴스 소유 파일; 템플릿은 `*.example.json`만 선적).
```console
$ test -f config/instance-runtime.json || cp config/instance-runtime.example.json config/instance-runtime.json
# master_host_runtime = 확인된 ORCA_AGENT_CLI
$ test -f config/model-tier-policy.json || cp config/model-tier-policy.example.json config/model-tier-policy.json
# version 2, consent, tiers / fanout_caps — 모델 id 추측 금지
```
해석 순서(소비자): 환경 오버라이드 → 인스턴스 파일 → unconfigured (하드코딩 기본값 없음).
## 첫 장애 대응
| 관측 | 확인 | 조치 |
| --- | --- | --- |
| spawn이 호스트를 못 부름 | `command -v orca`; `orca status` | Shell command 등록 |
| `BLOCKED` | FAIL 줄 전체 | 항목 수리 또는 의도적 `PREFLIGHT_WAIVE` |
| orchestration FAIL, legacy | 출력의 `legacy_read_only` / inspect-only | `orca orchestration run-create` 후 preflight 재실행 |
| orchestration FAIL, no Run | `"run": null` | 동일 `run-create` |
| `agent-cli` FAIL | `echo $ORCA_AGENT_CLI`; `command -v …` | 변수 설정 + 바이너리 설치 |
| `redaction-extra` FAIL | 파일 존재·유효 규칙 개수(내용 비공개) | 형식 `id\|description\|regex`로 재작성 |
| 면제했는데 여전히 FAIL | `named checks that did not run` | 라벨 철자 수정 (예: `redaction-extra` not `redaction-extras`) |
| Orca 없이 에이전트가 계속 진행 | 런타임 ready 여부 | 중단. 완료 감지가 스크린 폴링으로 degenerates — 실사고 기록됨 |
## 범위 밖 (이 페이지에서 끝내지 않는 것)
- Generation 1 spawn, boot smoke, 첫 supervised worker 검증 → [Quickstart](/quickstart), [온보딩](/onboarding)
- 인스턴스·티어 정책 상세 → [인스턴스 설정](/configure-instance)
- preflight 이후 장애 카탈로그 → [Troubleshooting](/troubleshooting)
## Next
클론 → Orca 준비 → wake-up → Gen-1 부트 → 첫 supervised worker까지 최단 경로
ONBOARDING 라우터, 1단계 1파일, Founding/Reverify/Upgrade
BLOCKED, placement, MODEL_PROBE_FAILED, seat 중복, revival
공개 표면, Orca 전제, 마스터/워커 역할, 네트워크·API 키 없음 제약
---
## 03. Quickstart
> 클론 → Orca 준비 → wake-up 온보딩 → Generation 1 부트 → 첫 supervised worker까지 최단 성공 경로와 검증 신호.
- Page Markdown: https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/03-quickstart.md
- Generated: 2026-08-07T07:02:16.006Z
### Source Files
- `docs/public/getting-started.md`
- `README.md`
- `master-ops/ONBOARDING.md`
- `master-ops/onboarding/09-spawn.md`
- `scripts/master-succeed`
- `scripts/dispatch-gate`
- `scripts/adapter`
---
title: "Quickstart"
description: "클론 → Orca 준비 → wake-up 온보딩 → Generation 1 부트 → 첫 supervised worker까지 최단 성공 경로와 검증 신호."
---
첫 실행 경로는 `docs/public/getting-started.md`의 인간 경로와 `master-ops/ONBOARDING.md` 라우터(단계 파일 1회 1로드)가 합쳐진 설치 인터뷰다. Orca 런타임이 준비된 뒤 이 저장소 클론 안에서 에이전트를 깨우면 Founding 모드가 ops 저장소를 만들고, `scripts/master-succeed spawn`으로 Generation 1 마스터를 좌석 검증 후 띄우며, 첫 작업은 `scripts/dispatch-gate check` → Orca orchestration dispatch → `register` → `worker_done` 수락 순으로 끝난다.
Orca 없이 마스터를 돌리면 완료 감지가 화면 폴링으로 떨어지고 감독이 사라진다. Step 0 preflight는 준비된 런타임 없이 founding을 진행하지 않는다.
## 성공 경로 한눈에
| 단계 | 행위자 | 핵심 명령 / 표면 | 통과 신호 |
| --- | --- | --- | --- |
| 1. Orca 설치·CLI 등록 | 사람 | `brew install --cask stablyai/orca/orca` 또는 [download](https://www.onorca.dev/download); Settings → Orca CLI → Shell command | `orca status` → `appRunning: true`, `runtimeState: ready` (또는 `--json` `"ok": true`) |
| 2. 클론·프로젝트 등록 | 사람 | `git clone` …; `orca repo add --path ` | Orca 프로젝트 안 터미널에서 `pwd`가 클론/워크스페이스 경로 |
| 3. Wake-up 온보딩 | 설치 에이전트 | 에이전트 CLI 기동 후 구체 작업 없는 짧은 문구 | `master-ops/ONBOARDING.md` 라우터 로드, 세션 모드 질문 |
| 4. Preflight (Step 0) | 설치 에이전트 | `ORCA_AGENT_CLI= bash scripts/onboarding-preflight.sh` | exit 0, 요약 `READY` 또는 `READY WITH WAIVERS` |
| 5. Founding → Gen-1 | 설치 에이전트 + 신생 마스터 | `master-succeed spawn` + orchestration Run/Task/Dispatch | placement `MATCH` 또는 `MATCH_REISSUED`; seat에 마스터 1개; boot smoke `worker_done` |
| 6. 첫 supervised worker | 마스터 | `dispatch-gate check` → dispatch → `register` → mailbox wait | 게이트 `allow: true`; 마스터가 증거를 재검증 후 수락 |
```text
[사람] Orca ready + clone in project terminal
│
▼
[설치 에이전트] wake-up → ONBOARDING router → Founding
│ 00…08 prepare ops seat rules
▼
[Gen-1 마스터] spawn (empty-seat + placement) → boot smoke → installer retire
│
▼
[사람] 작은 계약 승인 → [마스터] gate/dispatch/register → [워커] worker_done
│
▼
[마스터] 독립 증거 수락 (self-report ≠ proof)
```
## 전제조건 (측정)
분류는 `scripts/onboarding-preflight.sh` 기준이다. `FAIL`은 exit 1 `BLOCKED`에 합산되어 founding을 막는다. `WARN`만으로는 exit 1이 되지 않지만, essential로 표시된 항목은 요약에서 반복된다. 만족할 수 없는 필수 검사만 `PREFLIGHT_WAIVE=`로 명시 면제한다(미일치 라벨은 그대로 강제).
| 필요 | 확인 | 부재 시 |
| --- | --- | --- |
| Orca 앱 + 준비된 런타임 | `orca status` / `orca status --json` | `orca` FAIL |
| `orca` on `PATH` | `command -v orca` (지원 basename: `orca`, `orca-dev`, `orca-ide`) | 동일 FAIL |
| 마스터 에이전트 CLI | `command -v claude` 등; 온보딩이 `ORCA_AGENT_CLI` 설정 | `agent-cli` FAIL |
| 워커 런타임 ≥1 | `command -v codex` 및/또는 `cursor-agent` | 둘 다 없으면 `worker-runtime` FAIL |
| `git`, `gh`, `python3`, `bd` | 각 `--version` / `command -v` | 각 FAIL (`gh` 미인증은 WARN) |
| skills `orca-cli`, `orchestration` | 에이전트 skills root 또는 전역 목록 | `skills` FAIL |
| 조직 redaction 규칙 파일 | 기본 `~/.config/redaction-extra.txt` 또는 `REDACTION_EXTRA_PATTERNS` (id\|desc\|regex ≥1) | `redaction-extra` FAIL |
WARN 예: `gitleaks`, `ctx`, skill-stack(`superpowers`/`ponytail`), `gh-auth` / `workflow` scope.
클론 루트에서 세션 상태 포함 전체 측정:
```console
$ bash scripts/onboarding-preflight.sh
```
`--fix`는 승인 후에만: 전역 Orca skills 보강 가능, 앱 설치는 수동.
## 최단 절차
macOS(검증된 경로):
```console
$ brew install --cask stablyai/orca/orca
```
Linux/Windows: [Orca download](https://www.onorca.dev/download). Linux에서는 GNOME 스크린 리더와 충돌을 피하려고 바이너리명이 `orca-ide`일 수 있다.
Orca 앱을 연 뒤 **Settings → Orca CLI → Shell command**를 켠다. 성공 조건:
```console
$ command -v orca
$ orca status
```
앱이 꺼져 있으면 `orca open`이 런타임이 닿을 때까지 기다린다.
두 계층을 혼동하지 않는다.
1. **폴더 워크스페이스 루트** — 여러 저장소를 묶는 디렉터리(자체 git이 아닐 수 있음). 마스터 좌석.
2. **이 오케스트레이터 클론** — 설치기·런타임 소스. 마스터는 여기에 영구 거주하지 않는다.
```console
$ git clone https://github.com/baksohyeon/mogui-ADE-orchestrator
$ cd mogui-ADE-orchestrator
$ orca repo add --path
```
Orca에서 **해당 프로젝트 안** 터미널을 연다. `pwd`가 설치 세션 체크아웃이어야 한다. 프로젝트 밖 임의 cwd는 이후 placement/spawn이 잘못된 좌석을 측정한다.
워크스페이스 루트는 나중에 **절대 경로**로 붙여넣는다. 상대 경로와 bare `~`는 불충분하다.
프로젝트 터미널에서 마스터로 쓸 에이전트 CLI를 켠다(`claude`가 하드 런 검증된 조합; 다른 CLI는 워커로 검증됨, Codex 마스터는 미테스트).
구체 작업 없이 짧게 깨운다. 문구 예:
```text
Wake the master.
```
라우터 키는 의식 문구가 아니라 **구체 태스크 부재**다. 에이전트는 `master-ops/ONBOARDING.md`만 먼저 읽고 세션 모드를 묻는다.
| 모드 | 의미 | 스폰 |
| --- | --- | --- |
| **Founding** | 새 워크스페이스: ops 저장소 구축 + Gen-1 | 허용 (`00`→`10`) |
| **Reverify** | 이미 ops+마스터 있음: 건강 점검만 | 차단 |
| **Upgrade** | 템플릿 드리프트 적용 | 차단 |
| **Template improve** | 이 오케스트레이터 자체 수정 | 온보딩 중단 |
기존 ops 저장소·lineage 파일이 있으면 Founding이 아니다. 반쯤 끝난 설치에 Founding을 다시 돌리면 lineage/거버넌스가 깨진다. 죽은 마스터·반쯤 끝난 Gen-1은 ops의 `docs/runbooks/succession-boot-card.md` 경로다.
설치 에이전트(Herald)는 한 번에 한 단계 파일을 읽고, 해당 Verify가 통과하기 전에는 다음 파일을 열지 않는다. Founding에서 사람이 답해야 하는 결정:
| 결정 | 이유 |
| --- | --- |
| 워크스페이스 루트(절대 경로 붙여넣기) | 이후 측정·마스터 좌석 기준. 홈 스캔/후보 목록 없음 |
| 목적·소속 저장소 인벤토리 | 마스터가 조정할 허용 표면 |
| ops 저장소 이름·위치 | 거버넌스용 **별도** git (제품 코드 아님) |
| 마스터 callsign | 문서의 “master”는 임시 역할 라벨; 살아 있는 세션 호칭 |
| 이슈 트래커·선택 스킬 스택 | 실행 상태; 선택 스킬 거부는 정상 |
| Gen-1 스폰 확인 | 기록된 좌석에 터미널 1개 생성·킥오프·boot smoke. smoke 중 해당 패인에 타이핑하지 말 것 |
설치 인터뷰 세션 ≠ 마스터. Founding 스폰 후 설치기는 은퇴하고, 마스터는 워크스페이스 좌석의 **새** 세션이다.
에이전트가 `{{RUNTIME_ROOT}}`에서 실행한다(서술은 `$` 프롬프트):
```console
$ cd "{{RUNTIME_ROOT}}"
$ ORCA_AGENT_CLI="" bash scripts/onboarding-preflight.sh
```
통과 후 인스턴스 전용(커밋하지 않음) 파일:
```console
$ test -f config/instance-runtime.json || cp config/instance-runtime.example.json config/instance-runtime.json
# master_host_runtime = 확인된 에이전트 CLI
$ test -f config/model-tier-policy.json || cp config/model-tier-policy.example.json config/model-tier-policy.json
# version: 2, agents/tiers/fanout_caps/window_seconds, consent
```
- `instance-runtime.json`: `master_host_runtime`, `transcript_globs`, optional `product_repo`. 해석: env 오버라이드 → 파일 → unconfigured(추측 금지).
- `model-tier-policy.json`: 게이트 소비 필드 `version`/`tiers`/`fanout_caps`/`window_seconds`. 해석: `DISPATCH_TIER_POLICY` → `config/model-tier-policy.json` → 템플릿 `master-ops/model-tier-policy.json`.
오케스트레이션이 unbound/`run_required`이거나 legacy coordinator가 write를 떨어뜨리면 `orca orchestration run-create`로 새 Run을 묶고 재측정한다. 앱 재시작만으로는 legacy가 안 지워질 수 있다.
Step 8 전에 좌석 empty-gate: `ORCA terminal list --worktree --json`이 **해당 좌석 터미널 0개**. 잔여 seat-check/이전 스폰이 있으면 하드 스톱(두 번째 마스터 금지).
에이전트 전용 감독 경로(소유자에게 붙여넣지 않음; `ORCA`는 해석된 실행 파일):
```bash
G={{RUNTIME_ROOT}}/scripts/dispatch-gate
L=~/.mogui/dispatch-ledger.jsonl
"$G" --ledger "$L" check \
--runtime \
--model "{{MODEL_ID}}" \
--contract \
--agents 1 \
--est-chars \
--completion-channel orchestration
ORCA orchestration run-create --objective "Found and verify the Generation 1 master" --json
ORCA orchestration task-create --spec "Run the byte-identical founding kickoff file and complete Step 9 boot smoke" --json
"{{RUNTIME_ROOT}}/scripts/master-succeed" spawn \
--workspace-selector \
--kickoff-file \
--root "{{WORKSPACE_ROOT}}" \
--model "{{MODEL_ID}}" \
--title "Gen-1 founding boot" \
--json
ORCA terminal wait --terminal --for tui-idle --timeout-ms 60000 --json
ORCA orchestration dispatch --task --to --inject --json
"$G" --ledger "$L" register \
--job-id \
--probe-cmd "" \
--orchestration-task
ORCA orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json
```
`master-succeed spawn` 주요 플래그:
| 플래그 | 역할 |
| --- | --- |
| `--workspace-selector` | 내구 좌석 선택자 (`id:…` 등) |
| `--kickoff-file` / `--kickoff-text` | 부트 킥오프 (파일 바이트 동일 전달 검증) |
| `--root` | 워크스페이스 루트 |
| `--model` / `--agent` | 모델·런타임 CLI (`claude`/`grok`/`codex`/커스텀) |
| `--title` | 터미널 제목 |
| `--expected-placement` | 독립 기대 worktree; 불일치 시 fail-closed **exit 26** `SPAWN_PLACEMENT_MISMATCH` |
| `--dry-run` / `--json` | 시뮬레이션·JSON 출력 |
게이트 `check`가 `allow: true`여야 스폰/부착. placement 결과는 `MATCH` 또는 유효 `MATCH_REISSUED`(`handle_reissued: true` + 채택 핸들). Codex 워커 전 `scripts/codex-worker-pretrust `.
Step 9(신생 마스터 안): Role State·callsign 선언, 설정/실측 모델 분리 보고, placement 증거, `docs/lineage/MASTER-LINEAGE.md` Gen-1 append, founding Task에 `worker_done` 1회.
boot smoke 통과 후 Step 10이 운영 카드를 출력하고(Role State / Propose / Approved execute / Dispatch / succession 문구), 신생 마스터가 설치기 핸들·pty/session 신원 재확인 후 `ORCA terminal close --terminal --json`으로 설치기를 닫는다. 신원 모호·불일치 시 아무 터미널도 닫지 않고 보고한다. 마스터 터미널은 유지한다.
설치만으로는 긴 채팅과 같다. 시스템이 보이는 지점은 좁은 계약 → 승인 → 워커 → 증거 수락이다.
계약 예시 형태:
```text
In the repository , open README.md and list the top-level section headings.
Do not edit any file. Return the heading list as the artifact.
```
관찰 순서:
1. **Proposal** — 대상 저장소/체크아웃, 허용 표면, 수락 기준, 증거, 커밋 규칙.
2. **Approval** — 비사소 작업은 제안 → 승인 → 실행.
3. **Dispatch** — 보통 저장소 worktree 브랜치 워커; 완료는 orchestration 메일박스(`worker_done` 등), 화면 스크레이프 아님.
4. **Acceptance** — 워커 “done”은 주장; 마스터가 아티팩트·diff·게이트를 재검증.
정상 디스패치 상태 객체 순서(README 측정 경로):
1. 계약 파일 해시가 게이트 결정·태스크와 함께 기록
2. `scripts/dispatch-gate check` → 티어×fan-out 정책, JSONL ledger (`--ledger`, dry-run은 `--no-record`)
3. `orca orchestration task-create`
4. worktree + terminal 격리
5. `orca orchestration dispatch --task … --to … --inject`
6. `scripts/dispatch-gate register` (모델 probe: 선언 대비 실측; 더 비싼 모델이면 deny)
7. `orca orchestration check --wait` (mailbox)
8. 마스터 독립 수락
`dispatch-gate` 하위 명령: `check`, `register`, `watch`, `report`. `check`의 `--completion-channel`은 `orchestration` 또는 `sentinel-log`(라이브 마스터 경로는 orchestration).
## 검증 신호 체크리스트
Founding이 “done” 한 줄에 의존하지 않는다.
| # | 검사 | 기대 |
| --- | --- | --- |
| 1 | Orca UI / `orca terminal list` | Gen-1 세션이 **워크스페이스 루트 폴더 워크스페이스**(또는 단일 저장소면 primary worktree)에 있음. 멀티 레포에서 제품 레포 worktree에만 걸리면 misplacement |
| 2 | 마스터 트랜스크립트 boot smoke | Role State(+ callsign); configured vs measured 모델 분리; placement 증거가 의도 좌석과 일치 |
| 3 | 좌석 유일성 | 해당 워크스페이스 마스터 정확히 1. `master-succeed check-duplicates` |
| 4 | 폴더 좌석 라벨 | worktree 경로 비어 있음 / “Unavailable worktree” 칩 → **정상**(git worktree가 아님) |
| 5 | 설치기 | 카드 출력 후 설치 터미널 종료; 마스터 터미널 생존 |
| 6 | 첫 워커 | 게이트 allow → mailbox `worker_done` → 마스터 수락(self-report만으로 종료 금지) |
```console
$ orca terminal list
$ scripts/master-succeed check-duplicates --help # 실제 호출은 ops 마커/셀프 핸들로
```
## 빠른 순수 함수 스모크 (선택)
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
```
`adapter doctor`는 런타임 presence JSON 리포트만 반환한다.
## 실패 형태
| 증상 | 확인 | 조치 |
| --- | --- | --- |
| 스폰이 호스트를 못 부름 | `command -v orca`; `orca status` | Shell command 등록 |
| Preflight `BLOCKED` | `FAIL` 줄 | 필수 갭 수정; 의도된 경우만 `PREFLIGHT_WAIVE` |
| 마스터가 제품 레포 아래에만 있음 | 사이드바 vs 워크스페이스 루트 | misplacement. 두 번째 Founding 금지 → succession/recovery |
| Orca 없이 에이전트가 오류에 계속 진행 | 세션 전 `orca status` | 중단. 감독 경로 불가 |
| “Unavailable worktree” | 폴더 워크스페이스 여부 | 예상 동작 |
| 두 번째 세션이 master 주장 | `orca terminal list`; lineage / check-duplicates | 사고. Reverify는 스폰 안 함 |
| `SPAWN_PLACEMENT_MISMATCH` (exit 26) | `--expected-placement` vs 실제 좌석 | 경로 selector로 재시도 금지; 설정 후 **새** 세션 |
| 빈 mailbox / binding 상실 | orchestration Run 바인딩 | `run-create` 후 재측정; empty mailbox ≠ 완료 |
| inject “dispatched”인데 워커가 시작 화면 | Dispatch 상태 vs 셸 프롬프트 도착 | task ready 리셋 후 `orca terminal send`로 브리프 재전달, 프롬프트 착지 확인 |
## 제약 (이 경로에 해당하는 것)
- 로컬 전용: `src/`·`scripts/` 네트워킹 import 없음, API 키 없음. 에이전트 CLI가 각자 제공자에 연결하는 것은 기존 동작.
- 라이브 세션은 Orca 필수. 순수 함수 CLI는 Orca 없이 동작.
- 마스터 기본 스폰 경로는 Claude Code 검증 조합; 워커는 터미널 바이너리 무엇이든 계약 하에 가능.
## Next
Orca·CLI·preflight FAIL/WARN·셸 명령 등록 상세.
라우터, 1회 1단계·Verify, Founding/Reverify/Upgrade.
project·folder workspace·worktree·terminal·selector·UI 라벨.
check → dispatch → register, ledger, model probe, mailbox.
founding → steady state → succession → lineage.
BLOCKED, placement, MODEL_PROBE_FAILED, seat 중복, revival.
---
## 04. 런타임 유닛
> U1–U12 책임 경계, L0/L1 컨텍스트, 부분 구현 유닛, bootstrap·dispatch·succession·lineage 모듈 대응표.
- Page Markdown: https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/04-page-4.md
- Generated: 2026-08-07T07:02:16.207Z
### Source Files
- `docs/public/concepts.md`
- `src/master_runtime/core/bootstrap.py`
- `src/master_runtime/core/bootstrap_live.py`
- `src/master_runtime/core/context/resolver.py`
- `src/master_runtime/core/work_ledger.py`
- `src/master_runtime/core/approval/gates.py`
- `src/master_runtime/core/adapter/doctor.py`
---
title: "런타임 유닛"
description: "U1–U12 책임 경계, L0/L1 컨텍스트, 부분 구현 유닛, bootstrap·dispatch·succession·lineage 모듈 대응표."
---
마스터 런타임은 단일 프로세스가 아니라 **U1–U12 책임 단위**로 나뉜다. 유닛 번호는 설계 어휘이고, 실제 구현은 `src/master_runtime/core/` 모듈과 `scripts/` 엔트리포인트에 붙는다. 유닛이 있다고 해서 전부 모듈이 완성된 것은 아니며, U4는 설계만, U5·U7·U11은 부분 구현이다.
## 유닛 개요
| Unit | 이름 | 책임 | 모듈 / 스크립트 | 상태 |
| --- | --- | --- | --- | --- |
| U1 | Bootstrap | 안전 기동에 필요한 최소 L0/L1 로드 | `bootstrap.py`, `bootstrap_live.py` → `scripts/master-bootstrap`, `scripts/master-bootstrap-live` | 구현 |
| U2 | Context Resolver | 경로가 workspace / repo / worktree / folder 중 어디에 속하는지 판정 | `context/` (`resolver.py`, `descriptor.py`, `manifest.py`) | 구현 |
| U3 | Workspace Runtime | 트랙·교차 저장소 상태·장기 실행 기록 | `work_ledger.py` (`JsonlWorkLedger`, `WorkspaceRuntime`) | 구현 |
| U4 | Repository Runtime Loader | 대상 저장소에 필요한 harness만 로드 | 없음 | 설계 전용 |
| U5 | Worker Scheduler | 리스 발급, 격리 선택, dispatch, 예산, reap | 부분: `dispatch_gate.py`, `worker_reap.py` → `scripts/dispatch-gate`, `scripts/worker-reap` | 부분 |
| U6 | Approval Manager | 액션 위험 분류와 승인 상태 바인딩 | `approval/` (`gates.py`, `registry.py`) | 구현 |
| U7 | Role Runtime | 활성 역할 1개, role lock, 전이 상태 | 부분: `RoleState` 파싱은 `bootstrap.py`; lock 자체는 정책 | 부분 |
| U8 | Recovery Manager | reattach / 1회 resume / 상태 재구성 (읽기 전용) | `recovery.py` → `scripts/master-recover` | 구현 |
| U9 | Succession Manager | freeze, thin handoff, successor 검증, predecessor retire | `succession.py` → `scripts/master-succeed` | 구현 |
| U10 | Lineage Recorder | succession 품질 메타데이터 append-only 기록 (부트 소스 아님) | `lineage.py` | 구현 |
| U11 | Observability | 프로브·알림·컨텍스트 품질·모델 신원·acceptance 증거 | 부분: `digest_loop.py`, `watchdog.py`, `acceptance/`, 모델 프로브 스크립트 | 부분 |
| U12 | Adapter Layer | 제품별 CLI·포맷을 공통 계약 뒤로 격리 | `adapter/` → `scripts/adapter` | 구현 (launch 래핑 제거 후 doctor 중심) |
유닛 번호는 책임 자리표이다. “U5가 있다”는 말은 리스 발급·격리·launch·예산·reap이 전부 한 모듈에 있다는 뜻이 아니다.
## L0 / L1 컨텍스트
### 정의
| 계층 | 내용 | 대표 소스 |
| --- | --- | --- |
| **L0** | 안정 운영 프레임: charter, 역할 규칙, 상시 조정 규칙 | charter 파일 (`scripts/master-bootstrap --charter`) |
| **L1** | 활성 작업 컨텍스트: 트랙, handoff, digest 관측, 최근 운영 증거 | handoff, work ledger, live bootstrap 블록, `scripts/l1-digest` |
`bootstrap()`은 L0(charter)을 예산 안에서 먼저 채우고, 남은 예산으로 L1(handoff)을 붙인다. 기본 예산은 `DEFAULT_BUDGET_CHARS = 24_000`이다. 초과 시 마커:
- L0: `[TRUNCATED:BOOTSTRAP_BUDGET_EXCEEDED]` → warning `BUDGET_TRUNCATED:L0`
- L1: `[TRUNCATED:L1_BUDGET_EXCEEDED]` → warning `BUDGET_TRUNCATED:L1`
### Role State (L0 경계에 걸친 상속 상태)
handoff에 `## Role State` 블록이 있으면 파싱한다. 필수 필드:
| 필드 | 의미 |
| --- | --- |
| `Current Role` | `VALID_ROLES` 집합 안 값만 허용 |
| `Role Lock` | `ENABLED` / `DISABLED` |
| `Frozen` | 동결된 역할/작업 설명 |
| `Unlock` | 잠금 해제 조건 |
허용 역할: `Architecture`, `Research`, `Reference Implementation`, `Feature Implementation`, `Release / Operations`, `Incident Response`, `Maintenance`.
### Live bootstrap (`bootstrap_live.py`)
세션 시작용 동적 블록(~1KB 목표, `SELF_BLOCK_CAP = 1_000`). 메모리 본문을 재발행하지 않고 `bd prime --memories-only`를 L0/L1/untagged로 **감사**만 한다.
고정 섹션 순서:
```text
[MASTER-BOOTSTRAP v1]
## Role State
## Active tracks
## Charter
[BD-PRIME-AUDIT] ...
[DUAL-INSTANCE] ...
## Alerts (있을 때만)
```
내부 예외는 전부 잡아 `[BOOTSTRAP-FALLBACK] ` 한 줄로 낮춘다. boot가 죽지 않는 것이 계약이다.
### L1 관측 루프
`scripts/l1-digest tick --config ...`는 설정된 repo·ledger tail·job log·process 패턴을 읽고 digest를 쓴다. 작업 실행과 acceptance는 digest 밖에 있다.
## 모듈 대응표 (bootstrap · dispatch · succession · lineage)
### Bootstrap (U1 + Role 파싱)
| 표면 | 역할 |
| --- | --- |
| `bootstrap.py` | charter + handoff → budgeted L0/L1, Role State, dual-instance 경고 |
| `bootstrap_live.py` | SessionStart 블록: Role State, tracks, memory audit, dual-instance |
| `scripts/master-bootstrap` | CLI; `--charter`, `--handoff`, `--budget`, `--session-id`, `--strict-lease`, `--json` |
| `scripts/master-bootstrap-live` | CLI; `--handoff-dir`, `--role-state-file`, `--budget`, `--charter-pointer` |
`strict_lease=True`이고 dual-instance 경고가 있으면 `BootstrapError`로 실패한다.
### Dispatch / Worker path (U5 부분 + U11 watchdog)
```text
check -> (host dispatch) -> register -> independent verification -> acceptance
```
| 표면 | 역할 |
| --- | --- |
| `dispatch_gate.py` | 계약 가독성, 문자 예산, tier fan-out, reason code, JSONL ledger, ticket TTL |
| `scripts/dispatch-gate check` | allow/deny 기록 |
| `scripts/dispatch-gate register` | probe exit 0 + job id 출현 후에만 등록 |
| `scripts/dispatch-gate watch` | stall 검사 (`watchdog.check_stall`) |
| `scripts/dispatch-gate report` | ledger 집계 |
| `worker_reap.py` / `scripts/worker-reap` | settled dispatch 터미널 close, worktree 정리, reap ledger |
| `work_ledger.ReapObservability` | unreaped settled lease 탐지 |
**의도적 공백:** typed adapter launch 경로는 제거되었다. 워커 시작은 호스트(Orca 터미널)가 한다. 게이트는 그 단계를 **괄호로 감싸** 기록·검증한다. isolation 선택·전체 lease 발급기는 이 저장소에 없다.
리스 수명 (운영 runbook):
```text
issued → running → submitted → accepted → reaped
```
`scripts/worker-reap`는 settled(`COMPLETED`/`ACCEPTED`/`FAILED`/`ABANDONED`)가 아니면 exit 3으로 거절한다. 잘못된 reap은 비용이 크고, 건너뛴 reap은 싸다.
### Succession (U9) + Recovery (U8)
| 표면 | 역할 |
| --- | --- |
| `succession.py` | trigger 분류, handoff 작성, successor 검증, duplicate 탐지, retire, spawn placement 검증 |
| `scripts/master-succeed` | `detect`, `handoff`, `verify-successor`, `check-duplicates`, `retire`, `spawn` |
| `recovery.py` | Recovery Flow 0–6 **읽기 전용** (파일/프로세스 변경 없음) |
| `scripts/master-recover` | recovery 리포트 CLI |
라이프사이클:
```text
founding spawn → boot measurement → steady state → clean succession → lineage record
```
Successor 검증 상태: `PASS` | `PARTIAL` | `FAILED`.
Predecessor retire: process/pane/tty 측정; 부분 소멸은 `CLOSED_PARTIAL`로 기록해 full close와 혼동하지 않는다.
### Lineage (U10)
`lineage.append_entry`는 마크다운 원장에 **append-only**로 한 generation을 붙인다. lineage는 런타임 결정을 먹이지 않는다 (부트 소스 금지).
필수 필드:
| 필드 | 제약 |
| --- | --- |
| `generation` | 정수; 이미 있으면 `LineageValidationError` |
| `parent_session`, `successor_session` | 텍스트 |
| `timestamp` | 텍스트 |
| `inherited_role` | 텍스트 |
| `succession_reason` | 텍스트 |
| `recovery_sources` | 텍스트 |
| `inherited_open_tracks` | 텍스트 |
| `verification` | `PASS` \| `PARTIAL` \| `FAILED` |
| `repeated_question_count`, `reopened_decision_count` | 카운트 |
| `context_loss_summary` | 텍스트 |
| `predecessor_retirement_verified` | 텍스트 |
| `notes` | 선택 |
### Context / Workspace (U2 · U3)
| 표면 | 역할 |
| --- | --- |
| `context/resolver.resolve` | manifest 선언 + 파일시스템 관찰 → `ContextDescriptor` |
| `ContextKind` | `folder`, `git-repo`, `git-worktree`, `multi-repo-workspace`, `nested-repo` |
| `JsonlWorkLedger` | track `register` / `update` / `close` JSONL 이벤트 |
| `WorkspaceRuntime` | ledger 위 세션 L1 캐시 |
경로 재귀 스캔은 non-goal이다. 관찰 범위: 선언된 repo, workspace root 직계 자식, 질의 경로의 조상.
### Approval (U6)
`classify(ActionSpec)` → `GateClass`:
| Class | 조건 |
| --- | --- |
| `G0_READ_ONLY` | 읽기 전용 |
| `G1_REVERSIBLE_LOCAL` | 로컬 가역 쓰기 |
| `G2_SHARED_STATE` | 공유 상태 쓰기 (또는 비-read_only 기본) |
| `G3_IRREVERSIBLE` | 비가역 |
`approval/registry.py`는 proposal lifecycle `PENDING → APPROVED|REJECTED → CONSUMED`를 강제한다. 승인 없는 gated 실행은 `ApprovalRequired`.
### Adapter (U12)
| 표면 | 역할 |
| --- | --- |
| `adapter/doctor.py` | git / node / orca / bd 존재 프로브 (`orca status --json` — `--version` 아님) |
| `adapter/profile.py` | sync CLI argv 프로파일 (Claude / Codex / Cursor) |
| `scripts/adapter doctor` | JSON 리포트 |
워커 launch 래핑은 공개 표면에 없다. pretrust 보조: `scripts/codex-worker-pretrust`, `scripts/cursor-worker-pretrust`.
## 부분 구현 유닛 — 정직한 경계
### U4 Repository Runtime Loader
모듈 없음. 저장소별 harness lazy-load는 설계 어휘로만 남아 있다. 현재는 U2 descriptor와 호스트 worktree가 그 자리를 대체한다.
### U5 Worker Scheduler
| 있음 | 없음 / 호스트 |
| --- | --- |
| 계약 check/register, 예산·tier 캡, ledger | 워커 프로세스 launch (Orca) |
| settled reap + unreaped 탐지 | 전체 lease 발급기·격리 정책 엔진 |
| stall watch | “모든 생성 경로가 게이트를 통과한다”는 workspace wiring 증명 |
공개 문서의 “no lease or reap module” 표현은 이후 `worker_reap` 추가로 완화되었다. 그래도 U5 전체 스펙(리스 발급·격리 선택·launch 래핑)은 미완성이다.
### U7 Role Runtime
`RoleState` 파싱·유효 역할 검증·live 블록 주입은 코드에 있다. role lock 강제, 역할 전이 상태 머신, “한 활성 역할” 런타임 락은 **운영 정책**(Role State 파일 + 마스터 규약)이다.
### U11 Observability
| 구현 조각 | 스크립트 |
| --- | --- |
| L1 digest | `scripts/l1-digest` |
| stall watchdog | `dispatch-gate watch` |
| acceptance loop | `scripts/acceptance-loop` |
| model identity / drift | `scripts/model-identity-probe`, `scripts/model-drift-audit` |
통합 observability bus나 중앙 알림 서비스는 없다. 각 프로브가 독립 exit 코드 계약을 가진다 (스크립트마다 0/1/2 의미가 다름).
## 능력 영역 ↔ 유닛
| 능력 영역 | 주 유닛 | 메커니즘 |
| --- | --- | --- |
| Execution environment | 호스트 + 스크립트 | Orca 터미널, worktree, `scripts/*` |
| Context management | U1, U2, U3, U11(부분) | bootstrap L0/L1, resolver, ledger, digest |
| Delegation | U5(부분), U12, U11 acceptance | dispatch-gate, host launch, acceptance-loop |
| Steering | U6, U7(부분) | approval registry, Role State 정책 |
| Filesystem model | U2 | real git paths; sensitive-lane 차단은 워크스페이스 호스트 훅 |
## 라이프사이클에서 유닛이 붙는 지점
```mermaid
flowchart LR
A[U1 Bootstrap] --> B[Steady state]
B --> C[U5 Dispatch gate]
C --> D[Host worker]
D --> E[U5 Register / Reap]
E --> F[U11 Acceptance]
B --> G[U8 Recovery read-only]
B --> H[U9 Succession]
H --> I[U10 Lineage append]
I --> A
```
1. **Boot:** U1 (+ U7 Role State 파싱), 선택적 model probe (U11).
2. **Operate:** U2 경로 판정, U3 트랙, U5 check/register/reap, U6 승인, U11 digest/probe.
3. **Recover:** U8 Flow 0–6 읽기 전용 리포트.
4. **Succeed:** U9 handoff → spawn → verify → retire → U10 lineage. 다음 세대는 다시 U1.
## 검증 신호
| 신호 | 의미 |
| --- | --- |
| `scripts/master-bootstrap --json` | L0/L1 길이, role_state, warnings |
| `scripts/master-bootstrap-live` 출력에 `[MASTER-BOOTSTRAP v1]` | live 블록 조립 성공 |
| `[BOOTSTRAP-FALLBACK]` | live 경로 내부 실패, boot은 계속 |
| `dispatch-gate check` ledger 행 | allow/deny + reason code |
| `dispatch-gate register` 실패 `UNVERIFIED_JOB` | probe가 job id를 증명하지 못함 |
| `worker-reap` exit 3 | dispatch not settled |
| `master-succeed spawn` placement mismatch | successor 좌석이 요청 selector와 불일치 |
| lineage generation 중복 예외 | 같은 generation 재기록 시도 |
단위 테스트 통과는 해당 유닛의 **로컬 실행 증거**일 뿐, 운영 workspace가 모든 경로를 그 유닛으로 강제한다는 증명은 아니다.
## 구현 상태 라벨 (문서 어휘)
| 라벨 | 의미 |
| --- | --- |
| Configured | 파일·스크립트·훅·정적 계약이 repo에 존재 |
| Intended | 설계 계약은 문서화, 라이브 런타임 증거 주장 안 함 |
| Observed | git/로컬 실행/로그/ledger/프로브로 self-report와 독립 관측 |
| Unknown | 현재 증거로 증명 불가, 또는 공개 표면 밖 |
Configured ≠ operating. 훅 파일이나 유닛 번호만으로 “동작 중”이라 쓰지 않는다.
## Related pages
공개 표면, Orca 전제, 마스터/워커 역할
founding spawn → boot → steady → succession → lineage
project·workspace·worktree·terminal·Run 좌석 규칙
check → dispatch → register, ledger, model probe
handoff, placement spawn, retire, lineage 필드
self-report vs 독립 검증, acceptance 판정
issued→reaped, settled 검증, dry-run·ledger
디스패치·placement·redaction·revival 가드 표
scripts/ 공개 명령 표
---
## 05. Orca 객체 모델
> project·folder workspace·worktree·terminal·Run, 마스터 좌석 규칙, 검증된 selector 형식, 오해하기 쉬운 UI 라벨.
- Page Markdown: https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/05-orca.md
- Generated: 2026-08-07T07:02:10.538Z
### Source Files
- `docs/public/orca-concepts.md`
- `src/master_runtime/core/succession.py`
- `master-ops/docs/runbooks/succession-boot-card.md`
- `master-ops/onboarding/04-seat.md`
- `config/workspace-descriptor.example.json`
- `docs/public/master-lifecycle.md`
---
title: "Orca 객체 모델"
description: "project·folder workspace·worktree·terminal·Run, 마스터 좌석 규칙, 검증된 selector 형식, 오해하기 쉬운 UI 라벨."
---
이 런타임은 모든 에이전트를 Orca 안에 앉힌다. project·workspace(worktree/folder)·terminal·Run 계층과 마스터 좌석 규칙이 어긋나면 코드가 정상인데도 실측 misplacement가 난다. 공개 개념 문서는 `docs/public/orca-concepts.md`, 좌석 측정 절차는 `master-ops/onboarding/04-seat.md`, 배치 fail-closed 검증은 `scripts/master-succeed spawn`과 `src/master_runtime/core/succession.py`가 담당한다.
## 객체 계층
Orca가 추적하는 세 층과, 이 런타임이 그 위에 두는 오케스트레이션 문맥은 다음과 같다.
| 객체 | 의미 | 이 런타임에서의 역할 |
| --- | --- | --- |
| **Project** | Orca에 등록한 폴더(단일 Git repo, 여러 repo를 담은 plain folder, 빈 폴더 모두 project가 됨) | 사이드바 그룹은 표시용일 뿐 객체가 아님 |
| **Workspace** | project 안의 seat. terminal·에이전트가 사는 자리 | 종류가 첫 명령의 가능 범위를 결정함 |
| **Terminal** | workspace 안의 라이브 세션 | 마스터·워커 모두 terminal |
| **Run** | terminal에 묶인 내구성 오케스트레이션 문맥 | task·dispatch·mailbox를 세션 재시작 너머로 유지 |
```text
Project (Orca 등록 단위)
├── repository worktree … Git checkout 1개, 워커 seat
└── folder workspace … plain folder seat, 보통 마스터 seat
└── Terminal … 에이전트/셸 세션
└── Run … 디스패치·mailbox 바인딩
```
### Workspace 두 종류
프로젝트 형태가 어떤 workspace를 만들 수 있는지 결정한다.
| 종류 | 생성 경로 | 시작 cwd | 판정 필드 |
| --- | --- | --- | --- |
| **Repository worktree** | Create worktree 대화 / 저장소 project | checkout 안. git 즉시 가능 | `worktreeId` = `id:::` 계열 |
| **Folder workspace** | Create Folder Workspace / folder project | checkout 밖. git은 먼저 cd 필요 | `worktreeId` = `folder:`, `worktreePath` 비어 있음(정상) |
워크스페이스 루트가 plain folder이고 멤버 저장소가 sibling으로 늘어선 형태가 이 런타임의 기본 모델이다. 서브모듈 부모는 지원하지 않는다. 선언형 인벤토리는 `config/workspace-descriptor.json`(예시는 `config/workspace-descriptor.example.json`)에 둔다.
## 마스터 좌석 규칙
마스터는 워크스페이스 전체 저장소를 조율하므로 **workspace-level seat**에 앉는다.
| 워크스페이스 형태 | 마스터 seat | selector 형태(권장 기록) |
| --- | --- | --- |
| multi-repo, root = plain folder project | 그 root의 **folder workspace** | `id:folder:` |
| single-repo workspace | 그 저장소의 **primary worktree** | `id:::` |
multi-repo 워크스페이스에서 마스터를 개별 저장소 worktree에 앉히면 cwd·hooks·session 파일이 맞아 보여도 misplacement다. 사이드바에서는 그 저장소 아래에 걸리고, 워커용 seat를 점유한다. 2026-08-03 실측 사고가 이 형태였다.
온보딩 Step 3.5(`master-ops/onboarding/04-seat.md`) 절차 요약:
1. ops 저장소를 `orca repo add`로 등록(워커 worktree 소스).
2. `{{WORKSPACE_ROOT}}`를 project로 두고 folder workspace를 연다(단일 저장소여도 parent folder seat).
3. **임시 plain terminal**로 seat id만 측정한다. 마스터를 이 단계에서 만들지 않는다.
4. `orca terminal show --terminal --json`으로 `worktreeId`를 읽고, durable 기록에는 **`id:` 접두 형태**만 남긴다.
5. 임시 terminal을 닫아 좌석을 비운 뒤 founding spawn(`scripts/master-succeed spawn`)이 유일한 마스터 terminal이 되게 한다.
durable identity는 terminal handle이 아니다. handle은 앱 런타임 스코프이며 재시작과 함께 죽는다. 남는 것은 selector다.
descriptor의 `master_seat` 필드는 보통 `folder-workspace-of-workspace-root` 같은 서술 문자열이며, 실측 selector 문자열과 1:1이 아닐 수 있다. 실행 경로의 권위는 측정된 selector와 spawn 검증이다.
## 워커 좌석
마스터와 반대다.
| 역할 | seat | 금지 |
| --- | --- | --- |
| 마스터 | folder workspace(또는 single-repo primary worktree) | multi-repo에서 개별 product worktree에 안착 |
| 워커(git 필요) | 대상 저장소의 **isolated repository worktree**, 자체 브랜치 | folder workspace 공유, 마스터 checkout 공유 |
folder seat에 워커를 두는 것은 첫 명령이 checkout으로 `cd`할 때만 허용된다. 그렇지 않으면 첫 git 호출에서 실패한다. 생성만 하고 prompt/cwd를 확인하지 않으면 “만든 terminal”과 “동작 중인 worker”를 혼동한다.
워커 수명 끝에서는 `scripts/worker-reap`이 terminal close와 clean/merged worktree 정리를 담당한다. dirty·unmerged·접근 불가 worktree는 제거하지 않고 사유를 남긴다.
## 검증된 selector 형식
placement 명령(`orca terminal create --worktree`, `scripts/master-succeed spawn --workspace-selector`)은 selector 문자열을 받는다. 2026-08-03 실측과 `succession.py` 정규화 규칙이 합쳐진 동작은 다음과 같다.
| Selector | 동작 | 권장 |
| --- | --- | --- |
| `id:::` | repository worktree end-to-end | 기본. `orca worktree list --json`의 full `id` 복사 |
| `id:folder:` | folder workspace: list precheck·create·spawn match 통과 | durable 기록 표준 |
| `folder:` (bare) | `terminal create`는 수용, `terminal list --worktree`는 `selector_not_found`로 거부(하위명령 비대칭). spawn 코드는 list 시 `id:`를 붙인다 | 한 문자열이 모든 소비자에서 통해야 하면 `id:` 형태 |
| `path:/abs/dir` | Orca는 `::`로 해석. spawn 비교기가 거부하거나 경로 해석 매칭에만 부분 성공 | durable/요청 문자열로 쓰지 말 것 |
`succession.py`의 정규화:
- `_normalize_worktree_selector`: 선행 `id:`를 벗겨 비교한다. 응답의 `repoId::path`와 요청의 `id:repoId::path`를 동일 좌석으로 본다.
- `_terminal_list_worktree_selector`: bare `folder:`이면 list 전에 `id:`를 붙인다.
- `_path_worktree_matches`: 요청이 `path:`일 때만 actual `repoId::path`와 realpath 비교한다. folder seat에는 해당 없음.
두 규칙:
1. **Selector는 추론하지 말고 측정한다.** `orca terminal show` 또는 `orca worktree list --json`. `--worktree` 생략 시 cwd 추론이 misplacement 원인이 된다.
2. **placement match는 “요청한 것과 같은가”만 본다.** “요청 자체가 올바른 자리인가”는 lineage/descriptor 기대값과 별도로 비교해야 한다. 요청을 녹색이 될 때까지 고쳐 통과시킨 것이 2026-08-03 misplacement 경로였다.
## Spawn placement 검증
`scripts/master-succeed spawn`은 호스트 terminal을 만들고 응답 `worktreeId`를 요청 selector와 대조한다.
```bash
scripts/master-succeed spawn \
--workspace-selector "id:folder:" \
--kickoff-text "Founding master boot" \
--root . \
--model example-model \
--title "Founding master boot" \
--expected-placement "id:folder:" \
--json \
--dry-run
```
| 플래그/필드 | 의미 |
| --- | --- |
| `--workspace-selector` | create에 넘기는 요청 좌석(필수) |
| `--expected-placement` | 독립 기대 `worktreeId`. 불일치 시 fail-closed, exit **26** (`SPAWN_PLACEMENT_MISMATCH`) |
| 요청 vs 응답 worktree 불일치 | exit **22** (`SPAWN_WORKTREE_MISMATCH`), 가능하면 생성 terminal close |
| create 명령 | `orca terminal create --worktree --title … --command … --json` |
| liveness | create 전 snapshot → 후 list. handle이 live·new·요청 worktree 안이어야 함. 아니면 동일 title 후보 1개만 `MATCH_REISSUED`로 채택 |
```text
requested selector ──create──► worktreeId
│ │
├─ _worktrees_match? ─────┤
│ │
└─ expected_placement? ───┘
fail-closed → close terminal when safe
```
힌트 문자열(오류 메시지 꼬리):
`Accepted selector forms are full id:::, id:folder: for folder workspaces; path: is matched by resolved directory.`
placement 증거 three-set(승계 부트 카드):
1. host pane / worktree selector가 의도 workspace와 일치
2. process cwd가 `{{WORKSPACE_ROOT}}` 아래
3. session artifact/log 경로가 기대 namespace
UI pane title·status line은 힌트이지 placement 증거가 아니다.
## 오해하기 쉬운 UI·CLI 라벨
| 표시 | 실제 의미 | 조치 |
| --- | --- | --- |
| **Unavailable worktree** (Agent Session History) | 세션 seat가 Git worktree가 아님 | folder-workspace 마스터에서 **정상**. 크래시 아님 |
| **빈 `worktreePath`** (`orca terminal list --json`) | folder workspace 형태 | `worktreeId`(`folder:`)로 판정. path로 기각하지 말 것 |
| **Not a valid worktree folder** (workspace root) | root가 git repo/worktree가 아님 | plain folder 그룹 루트에서 **의도된 경고**. submodule 부모로 만들지 말 것 |
| pane status의 저장소 이름 | shell cwd 반영 | seat identity가 아님 |
| `process_id: null` (folder-workspace pane) | 호스트 list가 pid를 안 줌 | retire 시 pid/tty를 호출자가 실측해 전달 |
## Workspace descriptor와의 관계
| 키 | 값/제약 |
| --- | --- |
| `workspace_root_is_plain_folder` | 이 런타임에서 항상 true로 해석 |
| `workspace_root` | 절대 경로. absolute path lookup용 |
| `master_seat` | 마스터 seat 서술(보통 folder-workspace-of-workspace-root) |
| `repositories[].path` | workspace root 상대 경로 |
| `repositories[].role` | `product` \| `ops` |
| `capabilities` / `prohibited` | 워커 레인 허용·하드 스톱(open set) |
소비자는 `scripts/workspace-descriptor-check`와 워커 라우팅이다. 해석 순서: 환경 오버라이드 → 파일 → unconfigured. submodule shape는 없다.
## 원격·모바일 함의
Orca 세션은 시작한 책상에 묶이지 않는다(SSH remote worktree, headless `orca serve`, mobile companion). 이 런타임에 직접 닿는 결과:
- frozen 마스터는 폰에서도 재개 가능 → retirement 완료는 process·pane·tty **세 소멸 실측** 후에만.
- boot에 lineage session id revival 스캔이 있다(2026-08-03: 은퇴 마스터 4개가 동시 부활).
- 원격 머신 저장소에 대한 주장은 git remote·forge 상태로 따로 측정한다.
Orca 플래그를 추측하지 않는다. `orca --help`, `orca skills get`, `master-ops/docs/orca-docs-grounding.md` 스냅샷 순으로 측정한다.
## 검증 신호
좌석이 맞으면 다음이 동시에 성립한다.
- `orca terminal show`의 `worktreeId`가 workspace-level seat(`folder:` 또는 단일 repo primary worktree)
- durable ops 기록의 selector가 `id:` 접두
- 마스터 founding/successor spawn 전 해당 seat에 임시 terminal이 없음
- `scripts/master-succeed spawn … --json`이 `verified: true`, 요청과 `worktreeId` 일치
- folder 마스터의 빈 `worktreePath` / Unavailable worktree chip을 오류로 취급하지 않음
## 트러블슈팅
| 증상 | 원인 | 대응 |
| --- | --- | --- |
| `terminal list`가 selector 거부 | bare `folder:` | `id:folder:`로 재기록 |
| spawn 비교 거부 / exit 22 | 요청·응답 worktree 불일치 | 기대 seat 재측정, path 치환 금지 |
| exit 26 `SPAWN_PLACEMENT_MISMATCH` | `--expected-placement`와 실제 `worktreeId` 불일치 | lineage 기대값과 요청을 각각 수정; “통과할 때까지 요청 변경” 금지 |
| `selector_not_found` on create | project 미등록·잘못된 id | `orca repo add`, `worktree list --json` |
| 마스터가 product repo 아래 표시 | repository worktree에 착석 | folder workspace로 재측정·재spawn |
| folder seat 워커 git 실패 | checkout 없는 cwd | repository worktree로 재배치 |
## Related pages
founding spawn부터 succession·lineage까지의 세대 루프.
handoff, placement 검증 spawn, retire, revival 측정.
sibling 저장소 인벤토리, role·prohibited, master_seat.
spawn 플래그, exit 코드, SPAWN_PLACEMENT_MISMATCH.
seat 측정(Step 3.5)과 founding spawn 경계.
placement mismatch, seat 중복, revival 복구.
---
## 06. 마스터 라이프사이클
> founding spawn → boot measurement → steady state → clean succession → lineage 기록 루프와 Role State·compaction 규칙.
- Page Markdown: https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/06-page-6.md
- Generated: 2026-08-07T07:02:38.852Z
### Source Files
- `docs/public/master-lifecycle.md`
- `src/master_runtime/core/bootstrap.py`
- `src/master_runtime/core/bootstrap_live.py`
- `src/master_runtime/core/succession.py`
- `src/master_runtime/core/lineage.py`
- `src/master_runtime/core/recovery.py`
- `master-ops/docs/runbooks/role-state.md`
---
title: "마스터 라이프사이클"
description: "founding spawn → boot measurement → steady state → clean succession → lineage 기록 루프와 Role State·compaction 규칙."
---
마스터 세션은 장수(long-lived)하지만 불멸이 아니다. 이 런타임은 마스터를 **운영 lineage의 한 generation**으로 취급한다. 공개 표면은 `scripts/master-succeed`, `scripts/master-bootstrap`, `scripts/master-bootstrap-live`, `scripts/master-recover`, `scripts/model-identity-probe`, `scripts/model-drift-audit`이며, 핵심 구현은 `src/master_runtime/core/`의 bootstrap·succession·recovery·lineage 모듈이다.
## 루프 한눈에
```text
founding spawn → boot measurement → steady state → clean succession → lineage record
```
| 단계 | 목적 | 주 명령 |
| --- | --- | --- |
| Founding spawn | 설치 대화와 Gen 1 세션 분리, 좌석 placement 검증 | `scripts/master-succeed spawn` |
| Boot measurement | charter·handoff·Role State·budget·dual-instance 측정 | `scripts/master-bootstrap`, `scripts/master-bootstrap-live` |
| Steady state | continue-and-compact, 수락 상태 내구성 승격 | `scripts/l1-digest tick`, issue tracker / Git |
| Clean succession | 명시 트리거 → handoff → successor 검증 → retire | `scripts/master-succeed *` |
| Lineage | generation 메타 append-only 기록 (결정 권한 없음) | `append_entry` → `docs/lineage/MASTER-LINEAGE.md` |
```mermaid
flowchart LR
A[Founding spawn] --> B[Boot measurement]
B --> C[Steady state]
C --> D{Succession trigger}
D -->|NONE / ADVISORY only| C
D -->|IMMEDIATE + owner path| E[Thin handoff]
E --> F[Successor verify]
F --> G[Predecessor retire]
G --> H[Lineage append]
H --> B
```
자동 succession은 허용되지 않는다. `detect`가 `ADVISORY`를 내도 spawn을 시작하지 않으며, 명시 지시(`IMMEDIATE`)와 운영 절차가 있어야 한다.
## Founding spawn
첫 실행 절차의 전체 소유권은 온보딩 가이드에 있다. 인스톨러 대화와 Generation 1 마스터 세션을 분리해, 마스터가 **깨끗한 컨텍스트**와 **감사 가능한 placement**로 시작하도록 한다.
### Placement
| 워크스페이스 형태 | 마스터 좌석 | Selector 형태 |
| --- | --- | --- |
| Multi-repository | workspace root의 folder workspace | `id:folder:` |
| Single repository | primary worktree | 해당 worktree selector |
Multi-repository 안의 repository worktree는 **워커 좌석**이다. 마스터를 그 자리에 두면 placement 사고다.
### Spawn 진입점
실제 spawn 진입점은 `scripts/master-succeed spawn`이다. dry-run으로 호스트 명령을 먼저 확인한다.
```bash
scripts/master-succeed spawn \
--workspace-selector "id:folder:" \
--kickoff-text "Founding master boot" \
--root . \
--model example-model \
--title "Founding master boot" \
--json \
--dry-run
```
| 옵션 | 역할 |
| --- | --- |
| `--workspace-selector` | 생성 대상 worktree / folder workspace (필수) |
| `--kickoff-text` / `--kickoff-file` | 상호 배타, 하나 필수 |
| `--root` | 에이전트 cwd (필수) |
| `--title` | pane title (필수) |
| `--model` | 런치 모델 플래그 |
| `--agent` | 기본 `claude`; `grok`, `codex`, 커스텀 실행 파일명 가능 |
| `--expected-placement` | 독립 기대 worktree id; 불일치 시 exit **26** (`SPAWN_PLACEMENT_MISMATCH`) |
| `--dry-run` | 생성 없이 명령 스냅샷만 |
### Fail-closed 검증
호스트가 managed terminal 생성을 지원하면 non-dry-run spawn은:
1. 반환 worktree id가 요청 selector와 일치하는지 확인한다. 불일치 시 fail-closed이며, 가능하면 방금 만든 터미널을 닫는다.
2. 반환 handle이 **live**인지 확인한다. 생성 전 terminal list 스냅샷 → 생성 → 재조회.
3. 보고된 handle이 live·new·요청 worktree 안이면 `MATCH`.
4. 그렇지 않으면 요청 worktree에서 **요청 pane title을 가진 새 터미널이 정확히 하나**일 때만 대체 handle을 채택하고 `MATCH_REISSUED` / `handle_reissued=true`로 보고한다.
5. 후보 0개 또는 2개 이상은 fail-closed. 이때 생성된 터미널이 관리되지 않은 채 남을 수 있으므로, 재시도 전 호스트 terminal list로 조정한다.
관련 exit 상수: `SPAWN_CREATE_ERROR` 20, `SPAWN_PARSE_ERROR` 21, `SPAWN_WORKTREE_MISMATCH` 22, `SPAWN_CLOSE_ERROR` 23, `SPAWN_HANDLE_STALE` 24, `SPAWN_LIST_ERROR` 25, `SPAWN_PLACEMENT_MISMATCH` 26.
## Boot measurement
Boot는 추측이 아니라 **측정**이다. Charter(필수), optional handoff, Role State, budget 사용량, dual-instance 경고를 한 스냅샷으로 읽는다.
### `master-bootstrap` (측정 스냅샷)
```bash
scripts/master-bootstrap \
--charter master-ops/docs/MASTER-OPERATIONS.md \
--handoff ./handoffs/latest.md \
--session-id example-session \
--json
```
| 플래그 | 기본 | 의미 |
| --- | --- | --- |
| `--charter` | (필수) | L0 본문 소스 |
| `--handoff` | 없음 | L1 + Role State 소스 |
| `--budget` | `24000` | L0 우선 적재 후 잔여를 L1에 |
| `--session-id` | 없음 | dual-instance 프로브 키 |
| `--strict-lease` | off | `DUAL_INSTANCE:*` 있으면 `BootstrapError` (exit 2) |
| `--json` | off | `BootstrapResult` 직렬화 |
적재 순서:
1. Charter 전체 읽기 (없으면 fail).
2. Handoff가 있으면 Role State 파싱; 블록 없으면 `ROLE_STATE_MISSING`, 파일 없으면 `HANDOFF_MISSING`.
3. L0 = charter를 budget에 맞춤. 잘리면 `BUDGET_TRUNCATED:L0` + `[TRUNCATED:BOOTSTRAP_BUDGET_EXCEEDED]`.
4. 잔여 budget으로 L1 = handoff. 잘리면 `BUDGET_TRUNCATED:L1` + `[TRUNCATED:L1_BUDGET_EXCEEDED]`.
5. `session_id`가 있으면 프로세스 목록에서 동일 session id를 담은 `claude` 명령을 찾고, 자기 PID를 제외한 중복에 `DUAL_INSTANCE:`를 붙인다.
### `master-bootstrap-live` (SessionStart 배선)
라이브 부트는 세션 시작 훅용이다. 메모리 본문을 재발행하지 않고, ~1KB self-block과 audit 라인만 낸다. 내부 예외는 `[BOOTSTRAP-FALLBACK] …` 한 줄로 접어 **부트를 죽이지 않는다**.
```bash
scripts/master-bootstrap-live \
--handoff-dir ./handoffs \
--role-state-file master-ops/docs/runbooks/role-state.md
```
| 동작 | 규칙 |
| --- | --- |
| Role State 로드 | `--role-state-file` 우선, 실패 시 handoff dir의 사전순 최대 `*.md` |
| Tracks | `bd` 수집, self-block cap **1000** chars (tracks 우선 절단) |
| `bd prime --memories-only` | 본문 재출력 금지; L0/L1/untagged 카운트 audit만 |
| Dual-instance | 동일 프로브, `[DUAL-INSTANCE] none` 또는 경고 목록 |
| Charter pointer | `--charter-pointer` → `CHARTER_POINTER` env → 워크스페이스 중립 기본 문구 |
| Memory budget 기본 | **12000** chars |
### 모델 신원 측정
런치 플래그의 모델과 **세션이 실제로 쓰는 모델**은 분리한다. 측정 불가면 unavailable로 보고하고, 플래그로 추론하지 않는다.
```bash
# 최근 턴 샘플 — 지금 무엇인가
scripts/model-identity-probe \
--transcript ./sessions/example-session.jsonl \
--expect example-model
# 전체 트랜스크립트 — 중간에 바뀌었는가
scripts/model-drift-audit \
--transcript ./sessions/example-session.jsonl \
--expect example-model
```
| Exit | 의미 |
| --- | --- |
| 0 | 전이 없음 / 기대와 일치 (도구별 계약) |
| 1 | 전이 또는 기대 불일치 |
| 2 | undecidable (파싱 불가·스키마 불명) — pass로 접지 말 것 |
트랜스크립트 워커가 읽는 스키마는 빌드 대상(예: Claude Code JSONL)에 묶인다. Codex 등 다른 저장 형태는 exit 2 → **unsupported**로 보고한다. CLI 간 portable 키는 process argv의 **session id**이며, revival 스캔도 이 키를 쓴다.
Boot 측정은 **한 순간의 스냅샷**이다. 재측정 시점은 workspace master-operations 문서가 정한다. 현장 원인에는 미전파 런치 플래그뿐 아니라 quota·credit 소진 중 모델 전환이 포함되며, 선언 모델과 측정 모델이 어긋난 generation이 succession 감사에서야 발견된 사례가 있다. 안전한 대응: 측정값을 기록하고, 필요 시 민감 레인에서 마스터를 빼고, 신뢰할 수 없으면 clean successor를 연다.
## Role State
Role State는 handoff(또는 `role-state.md`)의 고정 필드 블록이다. Bootstrap 파서는 `## Role State` 근처 fenced block 또는 `Current Role:`…`Unlock:` 폴백을 읽는다.
캐논 템플릿 (`master-ops/docs/runbooks/role-state.md`):
```text
Current Role: (not booted; declare on first master start)
Role Lock: ENABLED
Frozen: all other roles
Unlock: explicit user instruction only
```
| 필드 | 허용 값 / 규칙 |
| --- | --- |
| `Current Role` | `Architecture`, `Research`, `Reference Implementation`, `Feature Implementation`, `Release / Operations`, `Incident Response`, `Maintenance` 만 |
| `Role Lock` | `ENABLED` / `DISABLED` (그 외 `BootstrapError`) |
| `Frozen` | 보통 `all other roles` |
| `Unlock` | 보통 `explicit user instruction only` |
| Generation | 0 → 첫 부트 시 1; 역할 전환은 Proposal→Approval 직후 또는 succession boot 때만 |
| 감사 | Git history가 transition audit trail |
Succession handoff 작성 시 `freeze_roles`가 현재 역할만 남기고 lock을 `ENABLED`로 고정한다. 필수 필드 누락·알 수 없는 역할은 bootstrap이 예외로 거부한다.
**역할 침식 함정:** 마스터가 대상 저장소의 agent instruction 파일을 읽은 뒤 그 저장소의 paired developer 역할을 함께 주장하는 구조적 유인. 대상 repo 지침은 **조정 대상에 대한 지식**이며, 그 역할 채택은 금지. 운영 규칙은 workspace master-operations에 둔다.
## Steady state (continue-and-compact)
정상 운영은 continue-and-compact다. 컨텍스트 압력이 급해지기 **전에** 수락된 지식, active tracks, open decisions를 issue tracker 또는 Git 등 **내구성 저장소**로 승격한다. Compaction·clear 직후에는 issue-tracker 컨텍스트를 다시 읽고 active tracks를 재확인한다.
| 표면 | 역할 |
| --- | --- |
| `scripts/master-bootstrap-live` | 세션 시작 시 bounded Role State / tracks / audit |
| `scripts/l1-digest tick --config …` | repo·ledger·job log·process pattern 관찰 후 digest 기록 (작업·acceptance 자체는 외부) |
| issue tracker / Git | 승격된 SSOT; 휘발 context만 잃도록 |
의도적 context-limit 실험에서 마스터는 한도 근처까지 조정을 이어갔지만, 다음 compacted 턴에서 회상·훅 커버 공백이 드러났다. 교훈: full window가 안전하다는 뜻이 아니라, 압력은 측정하고, 수락 상태는 이미 내구성 저장소에 있어야 하며, compaction vs succession은 낙관이 아니라 증거로 고른다.
사고 복구(프로세스 사망, 호스트 재시작, stale UI handle, 실수 pane 닫힘)는 succession이 아니다. 동일 session의 중복 live 프로세스가 없음을 증명한 뒤 same-session resume을 먼저 시도한다 (`master-ops/docs/runbooks/succession-boot-card.md`).
## Clean succession
### 트리거 분류
```bash
scripts/master-succeed detect \
"succession now" \
--context-ratio 0.65 \
--json
```
| Status | 조건 | 자동 spawn |
| --- | --- | --- |
| `IMMEDIATE` | 문구 포함: `succession now`, `handoff to successor`, `승계해줘`, `다음 마스터로 넘기자`, `승계 진행해` | 아니오 — 절차 시작 신호일 뿐 |
| `ADVISORY` | `context_ratio >= 0.60` 또는 `milestone` 비어 있지 않음 | 아니오 — propose only |
| `NONE` | 위 아님 | — |
### 절차
현재 마스터가 수락 지식·active tracks·open decisions·미해결 acceptance 증거를 내구성 저장소로 올린다. audit 없이 successor를 spawn하지 않는다.
```bash
scripts/master-succeed handoff --spec ./ops/handoff-spec.json --json
```
출력 섹션: Role State (frozen), Current Objective, Active/Open Tracks, Accepted Artifacts, Deferred Work, Open Questions, Recommended Next Role, Observed Baseline.
founding과 동일하게 `spawn` + placement 검증. kickoff·model·root·title 명시. Boot card: successor cwd는 workspace root 또는 승인된 orchestrator root.
`scripts/master-recover`가 Recovery Flow 0–6을 **읽기 전용**으로 실행한다 (파일 쓰기·프로세스 변이 없음). 보고 형태를 검증:
```bash
scripts/master-succeed verify-successor \
--report ./ops/recovery-report.json \
--json
```
| 판정 | 조건 |
| --- | --- |
| `FAILED` | 어떤 step status라도 `MISS` |
| `PASS` | open tracks 낭독(step 6 OK) + baseline(step 2-3 OK/없음) + monitors rearmed(step 5 OK) 세 체크 |
| `PARTIAL` | 일부 체크만 |
검증 후에만 retire. Freeze ≠ retirement. `scripts/master-succeed retire`는 후보 정확히 1개, self-handle 거부, 기본 dry-run, pane 생존 시 거부.
검증·retirement 결과를 `docs/lineage/MASTER-LINEAGE.md`에 append. lineage로 다음 행동을 결정하지 않는다.
### Placement evidence three-set (boot card)
1. host pane / worktree selector가 의도 workspace와 일치
2. process cwd가 workspace root 아래
3. session artifact / log path가 기대 namespace
UI pane title·status line은 **힌트**이지 placement 증거가 아니다.
## Retirement handshake
Retirement는 두 live 에이전트 사이의 teardown이다. 도구의 `close`만 호출하는 것은 TCP `RST`에 가깝다 — 에이전트 합의 없이 unflushed 작업을 잃는 경로이며, owner 승인 없이 쓰지 않는다.
| TCP | Master retirement | 행위자 |
| --- | --- | --- |
| `FIN →` | 작업 수락 중지·flush 지시 | successor |
| `← ACK` | 인지 후 CLOSE_WAIT | predecessor |
| half-close | send 측 유지: commit·보고 가능 | predecessor |
| `← FIN` | 합의된 FIN 한 줄, 이후 무출력 | predecessor |
| `ACK →` | 수신 확인 | successor |
| TIME_WAIT | 호스트 last-output + pane read로 quiet 측정 | successor |
| `CLOSED` | `retire --execute` + 삼중 disappearance | successor |
| `RST` | 합의 없는 abortive close | successor (owner 승인) |
CLOSE_WAIT에서 predecessor는:
1. 신규 dispatch 없음
2. successor가 drain할 peer-mailbox ack 없음 (또는 양쪽 이중 drain)
3. orchestration에 추가 송신 없음 — pane close가 Run binding 해제
4. uncommitted 상태 commit, 불가 시 경로·내용 보고
5. 소유 live worker와 미완료 track 이름 나열
6. 합의 FIN 한 줄만 출력
FIN은 idle 상태 live prompt에 전달한다. mailbox만 쓰고 idle 에이전트가 안 읽으면 배달이 아니다. send 성공 ≠ 소비 — pane 읽기로 확인. FIN 마커는 successor 지시 문자열에 그대로 들어가면 안 된다(또는 출현 횟수 ≥ 2 요구).
TIME_WAIT: handle 회전·transcript replay 중 dual process가 있을 수 있다. FIN 직후 즉시 close하면 재생성 중인 pane을 닫을 수 있다.
```bash
scripts/master-succeed retire \
--self-handle \
--target-handle \
--target-pid \
--target-tty \
--json \
--execute
```
Folder-workspace pane은 host list에서 `process_id: null`인 경우가 많다. pid·tty는 호출자가 측정해 넘긴다. 도구가 null 레코드에서 pid를 지어내지 않는다.
| `disappearances` 값 | 의미 |
| --- | --- |
| `measured` | 해당 축 소멸 확인 |
| `still_present` | 잔존 → 전체 `REFUSED` |
| `skipped:…` | 측정 입력 없음 |
| Status | 조건 |
| --- | --- |
| `DRY_RUN` | `--execute` 없음 |
| `REFUSED` | 후보 0/다수, self match, still_present, pane 미측정 |
| `CLOSED` | pane·process·tty 모두 `measured` |
| `CLOSED_PARTIAL` | pane `measured`, still_present 없음, process/tty 중 skip |
CLOSE 명령 반환값만으로 완료를 판단하지 않는다. Full `CLOSED` 전 predecessor scratchpad를 비-git 내구성 위치에 복사하고 trunk와 diff 판정을 남긴다.
### Revival
동결된 세션은 에이전트 CLI가 도는 어떤 터미널(폰·원격 포함)에서도 resume 가능하다. 측정 사고: 은퇴 마스터 4개가 모바일 resume으로 동시 부활. Boot card 규칙:
1. boot 시 및 owner가 stray를 보고할 때, `MASTER-LINEAGE.md`의 session id를 **process argv**에서 스캔
2. hit 시: 동결 이후 활동 읽기 → 미응답 owner 지시 회수 → 에이전트 종료 → host terminal chain hangup → tty 소멸 확인
3. 동일 삼중 disappearance로 닫기
Handoff 문구의 “predecessor gone”과 runtime state를 분리한다. 클린 succession = handoff 읽기만이 아니라 role·track·process ownership·verification 책임의 측정된 이전.
## Lineage
Lineage는 **append-only observability**다. bootstrap 소스가 아니고 runtime 결정 입력이 아니다. 공개 규칙: 검증 후 append, 다음 행동 권한으로 쓰지 않음.
`append_entry(path, entry)` 필수 필드:
| 필드 | 타입 / 제약 |
| --- | --- |
| `generation` | non-negative int; 동일 generation 재기록 거부 |
| `parent_session` | str |
| `successor_session` | str |
| `timestamp` | str |
| `inherited_role` | str |
| `succession_reason` | str |
| `recovery_sources` | str |
| `inherited_open_tracks` | str |
| `verification` | `PASS` \| `PARTIAL` \| `FAILED` |
| `repeated_question_count` | non-negative int |
| `reopened_decision_count` | non-negative int |
| `context_loss_summary` | str |
| `predecessor_retirement_verified` | str |
| `notes` | optional str |
쓰기는 원본 bytes + 새 섹션 동등성 검사; 실패 시 원본 복구 후 `LineageAppendError`. 렌더 형태: `## Gen — ` 마크다운 섹션.
## 공개 CLI 요약
| 명령 | 하위 명령 / 용도 |
| --- | --- |
| `scripts/master-succeed` | `detect`, `handoff`, `verify-successor`, `check-duplicates`, `retire`, `spawn` |
| `scripts/master-bootstrap` | L0/L1 budgeted snapshot + Role State + dual-instance |
| `scripts/master-bootstrap-live` | SessionStart bounded block, fail-open fallback |
| `scripts/master-recover` | Recovery Flow 0–6 read-only report |
| `scripts/model-identity-probe` | 최근 턴 모델 측정 |
| `scripts/model-drift-audit` | 전체 트랜스크립트 모델 전이 감사 |
| `scripts/l1-digest` | 관찰 전용 L1 digest loop |
공통: 대부분 `--json` 지원. 하드 가드 위반은 exit **2** 계열 (`SuccessionError`, `BootstrapError`). Spawn placement mismatch는 **26**.
## 실패 모드 체크리스트
| 증상 | 우선 확인 |
| --- | --- |
| `SPAWN_PLACEMENT_MISMATCH` / exit 26 | selector vs 생성 worktree; multi-repo에서 worker worktree에 앉혔는지 |
| `MATCH_REISSUED` / 미해결 handle | title 유일성; orphan terminal list 정리 후 재시도 |
| `DUAL_INSTANCE:*` / strict-lease fail | 동일 session id 프로세스; `check-duplicates` |
| `ROLE_STATE_MISSING` / step 0 WARN | handoff Role State 블록 필드 네 개 |
| model probe exit 2 | 에이전트 transcript 스키마 unsupported → unavailable 보고, 추측 금지 |
| `CLOSED_PARTIAL` | `--target-pid` / `--target-tty` 측정 후 재실행 |
| `still_present` after retire | TIME_WAIT·동의 경로 재확인; RST는 owner 승인 |
| 은퇴 후 세션 재개 | lineage session id revival 스캔 |
| 역할 이중 주장 | 대상 repo AGENTS/Claude 지침을 역할로 채택했는지 |
## Related pages
ONBOARDING 라우터, founding spawn, Stage 1/2, 1회 1로드 Verify
project·folder workspace·worktree·terminal·Run, 마스터 좌석, selector
handoff·placement·verify-successor·retire·revival·lineage 필드 상세
하위 명령 옵션, exit 코드, SPAWN_PLACEMENT_MISMATCH, JSON 출력
U1–U12, L0/L1, bootstrap·dispatch·succession·lineage 대응
placement·empty-seat·duplicate·revival·onboarding 가드 표
placement mismatch, undecidable exit 2, seat 중복, revival 복구
Gen 1 부트부터 첫 supervised worker까지 최단 경로
---
## 07. 증거와 수락
> 워커 self-report와 독립 검증 구분, 계약 필드, 리뷰 렌즈, acceptance 판정 규칙과 측정 가능한 증거 형태.
- Page Markdown: https://grok-wiki.com/public/docs/local-mogui-ade-orchestrator-97afe791d5ac/pages/07-page-7.md
- Generated: 2026-08-07T07:02:57.909Z
### Source Files
- `docs/public/delegation-and-review.md`
- `docs/public/concepts.md`
- `src/master_runtime/core/acceptance/loop.py`
- `src/master_runtime/core/acceptance/verdict.py`
- `src/master_runtime/core/approval/gates.py`
- `master-ops/docs/runbooks/contract-conventions.md`
- `master-ops/docs/charter/04-worker-routing-review.md`
---
title: "증거와 수락"
description: "워커 self-report와 독립 검증 구분, 계약 필드, 리뷰 렌즈, acceptance 판정 규칙과 측정 가능한 증거 형태."
---
수락(acceptance)은 워커 완료 보고와 별개의 마스터 결정이다. 운영 경로에서는 계약·디스패치 게이트·독립 검증이 선행되고, 기계 경로는 `scripts/acceptance-loop`와 `src/master_runtime/core/acceptance/`가 casebook 대비 pass count를 순수 비교한다. 워커 self-report는 증거가 아니다.
## Self-report와 독립 검증
마스터는 위임 산출을 신뢰하지 않는다. 채터 규칙(`master-ops/docs/charter/03-execution-principles.md`)과 공개 가이드(`docs/public/delegation-and-review.md`)가 같은 경계선을 고정한다.
| 구분 | 의미 | 수락 기여 |
| --- | --- | --- |
| Worker self-report | "완료", "통과", "READY" 등 워커가 쓴 주장 | 없음 — 조사 시작 신호만 됨 |
| Independent verification | 마스터가 재실행·재검사한 결과 | 있음 — 수락 전제 |
| Configured | 파일·훅·스크립트·정적 계약이 존재 | 배선 증거 아님 |
| Observed | git·로컬 실행·로그·ledger·프로브가 self-report 밖에서 확인 | 운영 증거 |
공개 문서의 증거 라벨(`Configured` / `Intended` / `Observed` / `Unknown`)은 "파일이 있다"를 "동작한다"로 승격하지 않는다. 통과한 테스트 스위트는 **그 유닛의 로컬 실행 증거**일 뿐, 워크스페이스가 실경로에서 그 유닛을 강제한다는 증명은 아니다.
### 측정 가능한 증거 형태
마스터가 직접 검사할 수 있는 것만 증거다.
| 형태 | 예 | 비고 |
| --- | --- | --- |
| Diff / 변경 표면 | `git diff`, 워커가 선언한 `surfaces` | 계약 허용 표면과 대조 |
| 테스트·게이트 실행 | pytest 전체 스위트, redaction scan exit | **숫자 + 명령** 쌍으로 기록 |
| 로그·프로브 | dispatch ledger, probe stdout, model probe | 파이프 exit가 아닌 명령 자체 exit |
| 생성 파일 | 리포트, 산출 아티팩트 | 경로·해시 또는 내용 대조 |
| 권위 문서 | 승인된 스펙, 핸드오프, Role State | 채팅 기억보다 우선 |
| 배치 판정 | `in_expected_worktree` / `is_master_checkout` / `branch` | 절대 경로는 하향만, 상향은 boolean |
표면(surface)이 초록이어도 사물(the thing)이 아닐 수 있다. 파이프의 exit, 잘못된 Run의 mailbox, 디스패치 기록의 주입 플래그는 각각 "보고"이지 본체가 아니다. 초록 신호를 믿기 전에 **무엇을 읽었는지**를 먼저 확인한다.
검증 절(`contract-conventions` §8) 규칙:
- 형용사 금지 — `"Gates pass"` 대신 `"448 passed, redaction scan OK, inventory exit 1 with baseline 445"`.
- 카운트 옆에 **실행한 명령**을 붙인다. 명령 없는 숫자는 검증 불가.
- empty check conclusion은 pending이지 pass가 아니다.
- 파이프를 끼우면 exit는 파이프 것일 수 있다. 명령 자체의 exit를 읽는다.
## 계약 필드 (worker contract)
계약은 워커의 전체 세계다. 침묵한 자리에서 워커는 합리적이지만 마스터와 다른 선택을 한다. 재사용 절은 `master-ops/docs/runbooks/contract-conventions.md`에 있으며, 가능하면 **복붙**하고 의역하지 않는다.
공개 가이드가 요구하는 관찰 가능 축:
| 필드 | 역할 |
| --- | --- |
| target repository / checkout | 어느 트리에서 작업하는지 |
| allowed work surface | 편집·조회 허용 범위 |
| acceptance criteria | 마스터가 재현할 통과 조건 |
| required evidence | 어떤 측정 산출을 제출할지 |
| commit / push / branch rules | 커밋·푸시·브랜치 권한 (추론 금지) |
| known exclusions / forbidden edits | 금지 표면과 제외 |
### 필수에 가까운 운영 절
계약 **하향**에는 절대 경로를 명시한다. 워커 **상향 보고**는 경로 대신 판정만:
```text
FIRST ACTION (report these three, and no absolute path):
- in_expected_worktree: yes|no
- is_master_checkout: yes|no # yes stops immediately
- branch: `git branch --show-current`
```
`is_master_checkout: yes`면 즉시 중단. 마스터 체크아웃 오염을 막기 위한 비대칭(경로는 아래, 판정은 위)이다.
계약에 없으면 보수적으로 uncommitted 상태로 보고한다. 예:
```text
Local commit allowed. Push forbidden. Commit only files changed for this job.
Evidence file stays uncommitted.
```
워커가 PR을 열면 merge-ready까지 보유한다. 보고 시점 네 측정:
1. 모든 체크 non-empty conclusion
2. unresolved review thread 0 (스레드별 개별 회신)
3. `origin/main` fetch·merge, conflict 없음
4. merge 후 게이트 재실행 + 카운트
`READY` 또는 정확한 블로커. **머지 자체는 마스터**.
- takeover는 **새 계약 파일** — `dispatch-gate`는 contract hash ledger로 최근 동일 해시를 중복으로 거절할 수 있다.
- Writing 블록(conventional commits, PR 템플릿 섹션명, 절대 경로·username 금지)은 계약에 그대로 싣는다.
- 공개 forge 표면에는 absolute path / identity string 금지; 인용은 `~/path`, `` 형태.
계약 해석이 갈리면 부분 수락하지 않는다. 마스터가 리스를 수정하고, 개정 이유를 기록한 뒤 redispatch하거나 변경을 요청한다. 워커 완료와 수락은 분리된 상태로 남긴다.
## 디스패치 경계와 수락 순서
```text
check -> dispatch -> register -> independent verification -> acceptance
```
| 단계 | 역할 | 증거 |
| --- | --- | --- |
| `check` | 계약 읽기, ledger에 허가 기록 | dispatch ledger 결정 |
| `dispatch` | 런타임에 워커 기동 (게이트가 래핑하지 않음) | 호스트/세션 배치 |
| `register` | job id가 기대 아티팩트에 있는지 **probe** | probe exit 0 + stdout에 id |
| independent verification | 계약 기준 재검사 | 마스터 실행 결과 |
| acceptance | 마스터 판정 | 수락 리포트 / 게이트 결정 |
`register`의 probe는 예시처럼 `grep ./worker.log`처럼 exit 0과 id 출력을 동시에 만족해야 한다. 경고 부재를 허가로 읽지 않는다.
## 리뷰 렌즈
비중대한 머지·직접 shared-state 변경의 기본은 **세 렌즈 분할**이다 (charter §4, `delegation-and-review`).
| 렌즈 | 질문 |
| --- | --- |
| general correctness | 결과가 동작하는가 |
| regression disproof | 기존 동작이 깨지지 않았음을 반증할 수 있는가 |
| contract and scope | 워커가 계약을 지켰는가 |
규칙:
- **다수 판결**을 쓰되, 소수 **P1 `FIX_FIRST`** 는 처리하거나 증거와 함께 명시 기각한다.
- 인기 투표가 아니다. contract/regression 렌즈의 blocking 이슈는 다른 렌즈가 긍정적이어도 수락 전에 처리한다.
- 렌즈 분리는 **운영 규율**이다. 현재 코드에 별도 합의 엔진은 없다 (`concepts.md` Steering: Intended).
PR review-bot 스레드는 라운드마다 오너 지시 없이 워커가 처리하고, 마스터가 검증·기각만 판정한다. bot finding은 코드 대비 재측정한 뒤 행동한다. 읽지 않고 resolve한 스레드는 리뷰가 아니다.
머지 직전 재측정: `review_measured_at` 이후 `submittedAt`이 더 늦은 bot review가 있으면 전량 읽고 나서 머지한다. 깨끗한 워커 보고는 이후 bot review가 생기는 순간 소모된다.
## Approval 게이트 (steering)
`src/master_runtime/core/approval/gates.py`와 `registry.py`는 **Proposal → Approval → Execution** 을 강제한다.
### GateClass
| 클래스 | 조건 |
| --- | --- |
| `G0_READ_ONLY` | 읽기만 |
| `G1_REVERSIBLE_LOCAL` | 로컬 가역 쓰기 |
| `G2_SHARED_STATE` | 공유 상태 쓰기 |
| `G3_IRREVERSIBLE` | 비가역 |
`classify(ActionSpec)`는 가장 엄격한 게이트를 고른다. `read_only`이면서 write/irreversible이면 `ValueError`.
### ProposalRegistry
- `propose` → `proposal-N` id
- `decision(verdict, authority)` — 한 번만 (`AlreadyDecided`)
- `guard(action, proposal_id)` — G0 제외 시 승인된 동일 `ActionSpec` 필요; 성공 시 `CONSUMED`
- G2/G3 **승인**은 `ApprovalAuthority.HUMAN` 필수 (`POLICY` 불가)
이 레지스트리는 수락 루프와 직교한다: 위험 행동 실행 권한과, 산출물 품질 수락은 다른 축이다.
## 기계적 acceptance loop
Deterministic loop: `scripts/acceptance-loop` → `run_acceptance_loop` / `decide`. **모델 판단·휴리스틱 점수·자연어 근거는 판정에 참여하지 않는다.** 비교 단위는 gated split의 **combined pass count** 뿐이다.
### Case split
| Split | 별칭 | 가시성 | 역할 |
| --- | --- | --- | --- |
| `train` | `visible` | proposer 가시 | 수정 대상 실패 목록 |
| `holdout` | `private` | 비공개 | overfitting 방지 게이트 |
| `scorecard` | `acceptance` | 비공개 메타 | 게이트 외 참고 점수 |
- `GATED_SPLITS = (train, holdout)` — `combined_passed` / `decide` 비교 대상
- 가시성 단일 술어: `is_visible_split` (`VISIBLE_SPLITS = {train}`)
- casebook validation: 최소 1 case, train·holdout 각각 1+, **seed strata 집합 동일**, `case_id` 중복 금지
- 누락 case 결과는 fail-closed (`MISSING_RESULT_DETAIL`) — evaluator skip으로 pass count 상승 불가
- split/stratum 소유권은 **casebook**, evaluator 아님
### 판정 규칙 (`decide`)
| `AcceptanceReason` | 조건 | `accepted` |
| --- | --- | --- |
| `PASS_COUNT_INCREASED` | `candidate_combined > current_combined` 이고 surface 변경 | `true` |
| `NO_PASS_COUNT_INCREASE` | 변경했으나 combined pass 증가 없음 | `false` |
| `NO_CANDIDATE_CHANGE` | `surfaces` 비어 변경 없음 (`candidate.changed == false`) | `false` |
동일 pass면 거부. "아무 것도 안 바꿨다"도 `decision.json`에 남겨 감사 추적을 유지한다.
### 루프 동작 요약
1. baseline 평가 → 현재 scorecard
2. 완전 통과(`is_complete`)면 중단
3. proposer workspace에 **visible failures만** 기록 (`visible_failures.json`, `casebook_visible.json`, `task.md`)
4. proposer가 `candidate.json` (`surfaces`, `summary`) 작성; 없으면 iteration 종료
5. 변경 시 gated 재평가 → `decide` → 수락 시 current 교체, 거부 시 `on_reject` restore
6. in-place mutator + `max_iterations >= 2` 이면 restore hook 필수 (`--restore-cmd`)
7. `report.json` / `report.md` 기록
### 산출물 레이아웃
```text
/
manifest.json
split.json
split.md
report.json
report.md
history/
visible/ # proposer에 복사 가능
iterations/NNN/decision.json|md
iterations/NNN/proposer_workspace/
train/