# Mogui ADE Orchestrator 문서
> Mogui ADE Orchestrator와 master-ops 운영 템플릿이 제공하는 Orca 기반 마스터 세션, 작업자 위임, 승계, 게이트, 설정, 검증 표면을 다루는 기술 문서입니다. 런타임 구현 저장소와 설치 후 운영 저장소의 관계를 함께 설명합니다.
## Context Links
- [Agent index](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/llms.txt)
- [Human interactive docs](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3)
## Repository Metadata
- Repository: local/master-ops-with-local-mogui-ADE-orchestrator
- Generated: 2026-08-10T07:43:39.423Z
- Updated: 2026-08-10T08:10:47.117Z
- Runtime: Codex CLI
- Format: Documentation
- Pages: 21
## Page Index
- 01. [개요](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/01-page-1.md) - 워크스페이스 오케스트레이터가 노출하는 공개 진입점, 두 저장소의 역할, 가장 짧은 성공 경로, 주요 문서 라우트를 정리합니다.
- 02. [설치](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/02-page-2.md) - Orca, agent CLI, git, gh, python3, bd, redaction rules, 선택 skill stack을 설치 전 측정하는 경로와 실패 신호를 설명합니다.
- 03. [Quickstart](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/03-quickstart.md) - 저장소 clone, Orca 프로젝트 등록, 에이전트 시작, wake-up 문장, 첫 작은 작업까지의 최소 실행 경로를 문서화합니다.
- 04. [온보딩 모드](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/04-page-4.md) - Founding, Reverify, Upgrade, Template improve 모드의 진입 조건, 금지된 spawn 경로, 단계별 파일 라우팅을 설명합니다.
- 05. [워크스페이스와 제품 저장소 관계](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/05-page-5.md) - 오케스트레이터 저장소, 설치 후 생성되는 ops 저장소, 제품 저장소, sibling checkout 모델, 단일 저장소 예외를 구분합니다.
- 06. [Orca 객체 모델](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/06-orca.md) - Project, workspace, worktree, terminal, Run, selector 형식, folder workspace의 정상 라벨과 misplacement 실패 조건을 설명합니다.
- 07. [런타임 유닛](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/07-page-7.md) - Bootstrap, Context Resolver, Workspace Runtime, Worker Scheduler, Approval Manager, Recovery, Succession, Lineage, Adapter Layer의 구현 상태와 경계를 정리합니다.
- 08. [증거 라벨](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/08-page-8.md) - Configured, Intended, Observed, Unknown 라벨과 테스트, 로그, ledger, self-report의 증거 강도를 운영 문서 규칙으로 정리합니다.
- 09. [워크스페이스 Founding](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/09-founding.md) - workspace root 선택, ops 저장소 생성, seat 기록, placeholder 치환, tracker 연결, Gen-1 spawn, boot smoke 검증 절차를 다룹니다.
- 10. [작업자 위임](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/10-page-10.md) - contract 파일, `dispatch-gate check`, Orca task-create와 dispatch, register probe, completion channel, acceptance 전 재검증 흐름을 설명합니다.
- 11. [마스터 승계](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/11-page-11.md) - trigger 감지, role freeze, thin handoff, successor verify, predecessor retirement, lineage append, revival check의 실행 순서를 설명합니다.
- 12. [Acceptance loop 실행](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/12-acceptance-loop.md) - acceptance suite 구조, train과 holdout 분리, proposer runtime, 반복 실행, scorecard, regression log를 다룹니다.
- 13. [작업자 정리](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/13-page-13.md) - settled dispatch 확인, terminal close, worktree clean과 merge 포함 여부 검사, dry-run, reap ledger 기록을 설명합니다.
- 14. [방어 인벤토리](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/14-page-14.md) - dispatch gate, ledgered decisions, model verification, placement, duplicate master, redaction, revival, progressive onboarding guard를 표로 정리합니다.
- 15. [모델 식별과 drift 감사](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/15-drift.md) - `model-identity-probe`, `model-drift-audit`, transcript glob 해석, expected model, undecidable 상태와 register-time 검증을 설명합니다.
- 16. [Redaction 게이트](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/16-redaction.md) - `redaction-scan.sh`, `redaction-inventory`, 조직 규칙 파일, commit message scan, pre-push hook, release gate의 범위와 exit code를 정리합니다.
- 17. [문제 해결](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/17-page-17.md) - preflight BLOCKED, Orca CLI 미등록, misplacement, duplicate master, Unavailable worktree, model probe undecidable, redaction cannot decide를 증상별로 다룹니다.
- 18. [CLI 참조](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/18-cli.md) - 공개 `scripts/` 명령, subcommand, 주요 option, exit code 차이, 문서 표와 실제 실행 파일 surface를 검증하는 테스트를 정리합니다.
- 19. [설정 참조](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/19-page-19.md) - `instance-runtime.json`, `workspace-descriptor.json`, `model-tier-policy.json`, 환경 변수 override, schema field, default, fail-closed 동작을 정리합니다.
- 20. [master-ops 템플릿 참조](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/20-master-ops.md) - 템플릿 manifest, template version, placeholder, workspace card, charter, runbook, hook, upgrade와 template-check surface를 정리합니다.
- 21. [기여와 릴리스](https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/21-page-21.md) - stdlib-only runtime, pytest gate, redaction scan, pre-push hook, version 산출, changelog, tag owner approval, Conventional Commits를 설명합니다.
## Source File Index
- `local-master-ops:CHANGELOG.md`
- `local-master-ops:docs/blame/BLAME-2026-08-04-status-blind-reporting.md`
- `local-master-ops:docs/blame/BLAME-2026-08-04-succession-misseat.md`
- `local-master-ops:docs/charter/01-document-map.md`
- `local-master-ops:docs/charter/05-dispatch-gate.md`
- `local-master-ops:docs/lineage/MASTER-LINEAGE.md`
- `local-master-ops:docs/MASTER-OPERATIONS.md`
- `local-master-ops:docs/observability/README.md`
- `local-master-ops:docs/runbooks/error-and-logging.md`
- `local-master-ops:docs/runbooks/orca-wait.md`
- `local-master-ops:docs/runbooks/succession-boot-card.md`
- `local-master-ops:MANIFEST.json`
- `local-master-ops:ONBOARDING.md`
- `local-master-ops:onboarding/00-orientation.md`
- `local-master-ops:onboarding/01-preflight.md`
- `local-master-ops:onboarding/02-workspace-facts.md`
- `local-master-ops:onboarding/03-ops-repo.md`
- `local-master-ops:onboarding/04-seat.md`
- `local-master-ops:onboarding/05-placeholders.md`
- `local-master-ops:onboarding/09-spawn.md`
- `local-master-ops:onboarding/10-card-and-retire.md`
- `local-master-ops:onboarding/reverify.md`
- `local-master-ops:onboarding/upgrade.md`
- `local-master-ops:scripts/dispatch`
- `local-master-ops:scripts/template-apply`
- `local-master-ops:scripts/template-check`
- `local-master-ops:scripts/worker-pane-sweep`
- `local-master-ops:TEMPLATE-VERSION`
- `local-master-ops:workspace-card/README.md`
- `local-mogui-ade-orchestrator:CHANGELOG.md`
- `local-mogui-ade-orchestrator:config/gitleaks.toml`
- `local-mogui-ade-orchestrator:config/instance-runtime.example.json`
- `local-mogui-ade-orchestrator:config/model-tier-policy.example.json`
- `local-mogui-ade-orchestrator:config/workspace-descriptor.example.json`
- `local-mogui-ade-orchestrator:CONTRIBUTING.md`
- `local-mogui-ade-orchestrator:docs/assets/wake-up-master.png`
- `local-mogui-ade-orchestrator:docs/internal/release-runbook.md`
- `local-mogui-ade-orchestrator:docs/public/concepts.md`
- `local-mogui-ade-orchestrator:docs/public/defense-inventory.md`
- `local-mogui-ade-orchestrator:docs/public/delegation-and-review.md`
- `local-mogui-ade-orchestrator:docs/public/getting-started.md`
- `local-mogui-ade-orchestrator:docs/public/master-lifecycle.md`
- `local-mogui-ade-orchestrator:docs/public/orca-concepts.md`
- `local-mogui-ade-orchestrator:docs/public/overview.md`
- `local-mogui-ade-orchestrator:docs/public/reference.md`
- `local-mogui-ade-orchestrator:docs/runbooks/worker-reap.md`
- `local-mogui-ade-orchestrator:hooks/pre-push`
- `local-mogui-ade-orchestrator:README.md`
- `local-mogui-ade-orchestrator:scripts/acceptance-loop`
- `local-mogui-ade-orchestrator:scripts/dispatch-gate`
- `local-mogui-ade-orchestrator:scripts/generate-manifest`
- `local-mogui-ade-orchestrator:scripts/master-bootstrap-live`
- `local-mogui-ade-orchestrator:scripts/master-succeed`
- `local-mogui-ade-orchestrator:scripts/model-drift-audit`
- `local-mogui-ade-orchestrator:scripts/model-identity-probe`
- `local-mogui-ade-orchestrator:scripts/next-version`
- `local-mogui-ade-orchestrator:scripts/onboarding-preflight.sh`
- `local-mogui-ade-orchestrator:scripts/redaction-inventory`
- `local-mogui-ade-orchestrator:scripts/redaction-scan.sh`
- `local-mogui-ade-orchestrator:scripts/worker-reap`
- `local-mogui-ade-orchestrator:scripts/workspace-descriptor-check`
- `local-mogui-ade-orchestrator:src/master_runtime/core/acceptance/casebook.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/acceptance/config.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/acceptance/loop.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/acceptance/report.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/adapter/doctor.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/bootstrap.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/context/resolver.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/dispatch_gate.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/instance_runtime_config.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/lineage.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/recovery.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/succession.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/work_ledger.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/worker_reap.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/workspace_descriptor.py`
- `local-mogui-ade-orchestrator:tests/test_acceptance_loop.py`
- `local-mogui-ade-orchestrator:tests/test_dispatch_gate.py`
- `local-mogui-ade-orchestrator:tests/test_instance_runtime_config.py`
- `local-mogui-ade-orchestrator:tests/test_model_drift_audit.py`
- `local-mogui-ade-orchestrator:tests/test_model_identity_probe.py`
- `local-mogui-ade-orchestrator:tests/test_onboarding_preflight.py`
- `local-mogui-ade-orchestrator:tests/test_onboarding_structure.py`
- `local-mogui-ade-orchestrator:tests/test_redaction_inventory.py`
- `local-mogui-ade-orchestrator:tests/test_redaction_scan_commit_messages.py`
- `local-mogui-ade-orchestrator:tests/test_reference_command_table.py`
- `local-mogui-ade-orchestrator:tests/test_succession_scenario.py`
- `local-mogui-ade-orchestrator:tests/test_succession.py`
- `local-mogui-ade-orchestrator:tests/test_template_check_apply.py`
- `local-mogui-ade-orchestrator:tests/test_worker_reap.py`
- `local-mogui-ade-orchestrator:tests/test_workspace_descriptor.py`
---
## 01. 개요
> 워크스페이스 오케스트레이터가 노출하는 공개 진입점, 두 저장소의 역할, 가장 짧은 성공 경로, 주요 문서 라우트를 정리합니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/01-page-1.md
- Generated: 2026-08-10T07:37:33.178Z
### Source Files
- `local-mogui-ade-orchestrator:README.md`
- `local-mogui-ade-orchestrator:docs/public/overview.md`
- `local-mogui-ade-orchestrator:docs/public/getting-started.md`
- `local-master-ops:ONBOARDING.md`
- `local-master-ops:docs/MASTER-OPERATIONS.md`
---
title: "개요"
description: "워크스페이스 오케스트레이터가 노출하는 공개 진입점, 두 저장소의 역할, 가장 짧은 성공 경로, 주요 문서 라우트를 정리합니다."
---
`mogui-ADE-orchestrator`는 Orca terminal, git worktree, 로컬 `scripts/` CLI, `master-ops/` 템플릿을 조합해 장기 실행 master 세션과 worker 세션을 운영하는 워크스페이스 오케스트레이터다. 런타임은 모델 API를 직접 호출하지 않으며, 실제 실행 단위는 Orca 안의 agent CLI 터미널과 저장소 checkout이다.
## 공개 진입점
| 표면 | 위치 | 역할 |
| --- | --- | --- |
| 설치 시작 | `local-mogui-ade-orchestrator:README.md` | clone, Orca 등록, agent CLI 시작, wake-up 문장까지의 최소 경로 |
| 사람용 시작 문서 | `local-mogui-ade-orchestrator:docs/public/getting-started.md` | 도구 측정, Orca CLI 등록, 첫 founding 흐름 |
| 에이전트 온보딩 라우터 | `local-master-ops:ONBOARDING.md` | Founding, Reverify, Upgrade, Template improve 모드 분기 |
| 운영 헌장 | `local-master-ops:docs/MASTER-OPERATIONS.md` | role, 실행 원칙, dispatch, succession, record, observability 문서 라우터 |
| 런타임 CLI | `local-mogui-ade-orchestrator:scripts/` | `master-succeed`, `dispatch-gate`, `master-bootstrap-live`, `acceptance-loop`, `redaction-scan.sh` 등 |
| 설치 템플릿 | `local-master-ops:MANIFEST.json` | ops 저장소에 복사될 템플릿 파일 목록과 `template_version` |
Orca는 live master 운영의 필수 substrate다. 순수 함수와 일부 CLI 검사는 Orca 없이 실행할 수 있지만, supervised dispatch, terminal placement, master spawn, worker completion mailbox는 Orca 런타임에 의존한다.
## 두 저장소의 역할
| 저장소 | 소유 범위 | 설치 후 위치 |
| --- | --- | --- |
| `local-mogui-ade-orchestrator` | Python stdlib 기반 runtime, 공개 문서, config example, redaction gate, succession/dispatch/acceptance CLI | installer와 runtime source |
| `local-master-ops` | workspace 운영 템플릿, onboarding step, charter, lineage/runbook/card skeleton, model tier policy template | 새 workspace의 ops repository로 복사 및 치환 |
`master-ops/`는 제품 저장소가 아니다. 설치가 끝나면 workspace root 아래에 별도 ops repository가 생기고, 제품 repository들은 sibling checkout으로 남는다. Workspace root 자체는 보통 git repository가 아닌 plain folder이며, master seat는 그 folder workspace에 놓인다. 단일 저장소 workspace만 예외적으로 primary worktree를 master seat로 쓸 수 있다.
```text
workspace-root/
CLAUDE.md # 배포된 workspace session card
AGENTS.md # 배포된 workspace session card
product-repo-a/ # worker 대상 제품 저장소
product-repo-b/ # worker 대상 제품 저장소
workspace-ops/ # master-ops 템플릿에서 생성된 운영 저장소
```
## 가장 짧은 성공 경로
```console
$ git clone https://github.com/baksohyeon/mogui-ADE-orchestrator
$ cd mogui-ADE-orchestrator
```
Orca UI에서 workspace root 또는 이 clone을 project로 추가한다. CLI가 등록되어 있으면 다음 형태도 쓸 수 있다.
```console
$ orca repo add --path
$ orca status
```
성공 조건은 Orca CLI가 `PATH`에 있고 runtime이 ready 상태인 것이다.
```console
$ claude
```
`claude`는 가장 많이 검증된 master host다. 다른 agent CLI는 worker로 쓸 수 있으며, master host runtime은 onboarding에서 측정하거나 기록한다.
```text
Wake the master.
```
또는
```text
일어나라 마스터여
```
구체 작업이 없으면 agent는 installer 역할로 `master-ops/ONBOARDING.md`를 읽고 mode classification부터 시작한다.
```console
$ bash scripts/onboarding-preflight.sh
```
preflight는 Orca, orchestration Run, agent CLI, worker runtime, `git`, `gh`, `python3`, `bd`, skills, redaction rules를 측정한다. `FAIL`은 founding을 막고, `WARN`은 단독으로 exit 1을 만들지 않는다.
## 온보딩 모드
`ONBOARDING.md`는 설치 절차 전체를 한 번에 읽는 문서가 아니라 mode router다. 각 step은 별도 파일로 분리되어 있고, 이전 step의 Verify가 통과해야 다음 파일을 연다.
| 모드 | 진입 조건 | spawn 여부 |
| --- | --- | --- |
| Founding | 새 workspace에 ops repository와 Generation 1 master를 만든다 | 허용 |
| Reverify | 이미 founded된 workspace의 상태를 점검한다 | 차단 |
| Upgrade | 기존 ops repository의 template drift를 확인하고 template-layer 파일만 갱신한다 | 차단 |
| Template improve | 오케스트레이터 저장소 자체의 문서나 코드를 수정한다 | 설치 흐름 중단 |
기존 ops repository나 lineage 파일이 있으면 Founding으로 재진입하지 않는다. 죽은 master, 중단된 Gen-1 boot, 살아 있는 master의 succession은 설치 재실행이 아니라 ops repository의 recovery/succession 경로가 처리한다.
## 런타임 경계
`src/master_runtime/core/`는 orchestration 판단을 담당하고, 실제 terminal 생성과 host 조작은 Orca CLI와 adapter layer를 통해 일어난다.
| 런타임 유닛 | 대표 표면 | 동작 |
| --- | --- | --- |
| Bootstrap | `scripts/master-bootstrap`, `scripts/master-bootstrap-live` | charter, handoff, Role State, active-track context를 bounded block으로 만든다 |
| Dispatch gate | `scripts/dispatch-gate check/register/watch/report` | contract, model tier, fan-out, completion channel, job probe를 gate ledger에 기록한다 |
| Succession | `scripts/master-succeed detect/handoff/spawn/verify-successor/check-duplicates/retire` | master handoff, successor spawn, duplicate detection, predecessor retirement를 분리한다 |
| Workspace descriptor | `config/workspace-descriptor.json` | sibling repository inventory, role, capability, prohibition을 instance config로 기록한다 |
| Redaction gate | `scripts/redaction-scan.sh`, `scripts/redaction-inventory` | tracked content, commit message, organization rule loading 범위를 명시하고 fail-closed한다 |
Provider-neutral 경계는 “모델을 추상 API로 감싼다”가 아니라 “로컬 agent CLI 터미널을 Orca가 관리한다”에 있다. Skill pack, repository file, catalog source는 portable source로 취급할 수 있지만, 이 runtime은 특정 hosted model provider나 proprietary connector를 요구하지 않는다.
## Dispatch의 최소 형태
Worker에게 일을 넘기기 전에는 contract 파일이 먼저 있어야 한다. Gate는 contract를 읽고 hash를 기록하며, 허용된 dispatch만 ticket과 JSONL ledger에 남긴다.
```console
$ scripts/dispatch-gate --ledger ~/.mogui/dispatch-ledger.jsonl check \
--runtime codex \
--model \
--contract \
--agents 1 \
--est-chars \
--completion-channel orchestration
```
Founding spawn 절차도 같은 원칙을 따른다. Run과 Task를 만들고, `master-succeed spawn`으로 placement-verified terminal을 만든 뒤, Orca orchestration dispatch와 `dispatch-gate register`로 job identity를 다시 확인한다. Worker의 `done` 문장은 completion evidence가 아니라 claim이며, master가 별도로 acceptance를 수행한다.
## 주요 설정 파일
| 파일 | 필드 예시 | 비고 |
| --- | --- | --- |
| `config/instance-runtime.json` | `master_host_runtime`, `transcript_globs`, `product_repo` | master host와 transcript probe 위치를 instance가 소유한다 |
| `config/workspace-descriptor.json` | `workspace_root`, `master_seat`, `repositories[]` | repository role은 `product` 또는 `ops`; prohibition은 fail-closed 판단에 쓰인다 |
| `config/model-tier-policy.json` | `version`, `tiers`, `fanout_caps`, `window_seconds` | instance policy가 있으면 template fallback보다 우선한다 |
| `master-ops/MANIFEST.json` | `template_version`, `files[]` | ops repository 생성과 template drift 판단의 기준이다 |
## 문서 라우트
설치 전 도구, redaction rules, Orca CLI, Beads, 선택 skill stack의 측정 경로를 확인한다.
clone부터 Orca 등록, wake-up 문장, 첫 작은 작업까지의 최소 실행 경로를 따른다.
Founding, Reverify, Upgrade, Template improve의 진입 조건과 spawn 금지 조건을 구분한다.
orchestrator, ops repository, product repository, sibling checkout 모델을 분리해서 본다.
contract, dispatch gate, Orca task, register probe, completion channel, acceptance 재검증 흐름을 확인한다.
공개 `scripts/` 명령, option, exit code, drift test 기준을 확인한다.
---
## 02. 설치
> Orca, agent CLI, git, gh, python3, bd, redaction rules, 선택 skill stack을 설치 전 측정하는 경로와 실패 신호를 설명합니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/02-page-2.md
- Generated: 2026-08-10T07:37:42.285Z
### Source Files
- `local-mogui-ade-orchestrator:docs/public/getting-started.md`
- `local-mogui-ade-orchestrator:scripts/onboarding-preflight.sh`
- `local-mogui-ade-orchestrator:tests/test_onboarding_preflight.py`
- `local-mogui-ade-orchestrator:README.md`
- `local-master-ops:onboarding/01-preflight.md`
---
title: "설치"
description: "Orca, agent CLI, git, gh, python3, bd, redaction rules, 선택 skill stack을 설치 전 측정하는 경로와 실패 신호를 설명합니다."
---
`scripts/onboarding-preflight.sh`가 설치 전 필수 표면을 측정한다. no-flag 실행은 읽기 전용이며, `--fix`는 승인된 알려진 설치 명령을 실행한 뒤 결과물을 다시 측정한다. `FAIL`은 founding을 막고 `BLOCKED`로 종료하며, `WARN`은 단독으로 exit 1을 만들지 않지만 필수 성격의 경고는 요약에서 다시 출력된다.
## 실행 위치와 기본 명령
preflight는 오케스트레이터 런타임 저장소 루트에서 실행한다. 이 스크립트는 Orca 앱 상태만 보지 않고, 현재 터미널에 non-legacy orchestration Run이 바인딩되어 있는지도 확인한다.
```console
$ cd
$ ORCA_AGENT_CLI="" bash scripts/onboarding-preflight.sh
```
`ORCA_AGENT_CLI`가 비어 있으면 `agent-cli`가 `FAIL`이다. 예: `claude`, `codex`, `grok`처럼 실제 master 세션을 실행할 CLI 이름을 넣는다.
승인된 의존성 설치까지 맡길 때만 `--fix`를 사용한다.
```console
$ ORCA_AGENT_CLI="" bash scripts/onboarding-preflight.sh --fix
```
`--fix`가 다루는 범위는 제한적이다. 알려진 경로가 있는 Orca, `ctx`, `gitleaks`, 전역 Orca skills 설치 또는 갱신을 시도하고, 설치 명령의 exit code만 믿지 않고 다시 측정한다.
## 필수 설치 표면
| 항목 | 측정 방법 | 실패 신호 |
| --- | --- | --- |
| Orca CLI | `orca status --json` 또는 선택된 `ORCA_CLI_COMMAND` | CLI 없음, 지원되지 않는 basename, `ok:true` 아님 |
| Orca orchestration Run | `orca orchestration run-current --json` | legacy read-only, Run 미바인딩, legacy Run |
| Orca skills | skill root의 `orca-cli`, `orchestration` 또는 `skills list -g` | 둘 중 하나라도 없음 |
| master agent CLI | `ORCA_AGENT_CLI`와 `command -v` | unset 또는 PATH 미해결 |
| worker runtime | `codex`, `cursor-agent` | 둘 다 없으면 `FAIL`; 하나만 없으면 `WARN` |
| `git` | `command -v git` | PR 기반 저장소 운영 불가 |
| `gh` | `command -v gh`, `gh auth status` | binary 없음은 `FAIL`; auth 또는 `workflow` scope 부족은 `WARN` |
| `python3` | `python3` 존재와 버전 문자열 | binary 없음 |
| `bd` | `bd where` | binary 없음, ops repo 밖으로 resolve, `.beads` marker는 있는데 `bd where` 실패 |
| redaction rules | `REDACTION_EXTRA_PATTERNS` 또는 `~/.config/redaction-extra.txt` | 파일 없음, usable rule 0개, malformed rule 존재 |
| dispatch ledger | `DISPATCH_GATE_LEDGER` 디렉터리 쓰기 가능성 | ledger 디렉터리 생성 또는 쓰기 불가 |
Python은 preflight에서 별도 version floor를 강제하지 않는다. 도구별 더 높은 interpreter 요구사항은 각 도구가 런타임에서 처리한다.
## Orca 설치와 CLI 등록
macOS에서 알려진 설치 명령은 Homebrew cask다.
```console
$ brew install --cask stablyai/orca/orca
```
Linux와 Windows는 Orca 공식 다운로드 경로를 사용한다. Linux에서는 binary 이름이 `orca-ide`일 수 있다. preflight가 지원하는 basename은 `orca`, `orca-dev`, `orca-ide`다.
설치 후 Orca 앱에서 Shell command를 등록해야 터미널의 `orca` 호출이 동작한다. 성공 조건은 UI 라벨이 아니라 이 명령의 결과다.
```console
$ command -v orca
$ orca status --json
```
Run이 바인딩되지 않았거나 legacy라면 새 Run을 만든 뒤 다시 측정한다.
```console
$ orca orchestration run-create
$ bash scripts/onboarding-preflight.sh
```
## Beads와 ops 저장소
`bd`는 execution state를 저장하는 tracker 표면이다. preflight는 단순히 binary만 보지 않는다. `bd where`가 `.beads` 경로를 반환하면 그 상위가 ops 저장소인지 확인하고, `docs/MASTER-OPERATIONS.md`가 없으면 ops repo 밖으로 resolve된 것으로 본다.
```console
$ command -v bd
$ bd where
```
ops repository가 아직 만들어지지 않은 위치에서는 `bd` binary present만으로 통과할 수 있다. 하지만 `.beads` marker가 감지되는데 `bd where`가 실패하면 fix 대상이다.
## Redaction rules 설치
조직별 redaction 규칙은 저장소에 커밋하지 않는다. 기본 위치는 `~/.config/redaction-extra.txt`이고, 다른 위치를 쓰려면 `REDACTION_EXTRA_PATTERNS`를 지정한다.
```text
id|description|regex
```
규칙 파일 제약은 다음과 같다.
| 규칙 | 의미 |
| --- | --- |
| 빈 줄과 `#` 주석 | 무시 |
| 첫 두 `|` | `id`, `description`, `regex` 구분자 |
| regex | Python `re.compile` 가능해야 함 |
| 출력 | 규칙 내용은 출력하지 않고 count만 출력 |
예시는 형식만 보여준다. 실제 조직명, 제품명, 개인 식별자는 로컬 파일에만 둔다.
```console
$ export REDACTION_EXTRA_PATTERNS="$HOME/.config/redaction-extra.txt"
$ bash scripts/onboarding-preflight.sh
```
publish-time scan은 `gitleaks`를 엔진으로 사용한다.
```console
$ bash scripts/redaction-scan.sh
$ bash scripts/redaction-scan.sh --staged
$ bash scripts/redaction-scan.sh --range A..B
$ bash scripts/redaction-scan.sh --commit-messages A..B
$ REDACTION_REQUIRE_EXTRA=1 bash scripts/redaction-scan.sh
```
| exit code | 의미 |
| --- | --- |
| `0` | clean |
| `1` | finding 있음 |
| `2` | 판단 불가: `gitleaks` 없음, 필수 org rules 없음, range 오류, retired allowlist entry, engine error 등 |
`redaction-scan.sh`는 repository tracked content와 선택된 commit message 범위를 읽는다. PR title, PR body, review comment, release note, issue text, forge 웹 UI에 직접 입력한 문장은 스캔하지 않는다.
## 선택 skill stack
선택 skill stack은 기본 실행 가능성과 별개로 master의 행동을 바꾸는 층이다. preflight는 `superpowers`와 `ponytail`을 `skill-stack`으로 측정한다.
| pack | 역할 | 없을 때 |
| --- | --- | --- |
| `superpowers` | 방법론과 절차 discipline | charter가 절차보다 조언처럼 읽힐 수 있음 |
| `ponytail` | restraint와 scope control | diff가 커지고 speculative structure가 늘 수 있음 |
탐지는 agent-neutral이다. skill directory가 알려진 root 아래에 있거나, agent plugin manifest에 pack이 있으면 통과한다. Claude Code가 선택된 host이면 `/plugin install ...` 계열 안내를 출력하고, 다른 agent이면 해당 agent의 skill pack 경로나 skill root 설치 안내를 출력한다.
이 stack은 특정 model provider에 묶인 필수 런타임이 아니다. 파일, 저장소, catalog 또는 agent별 plugin packaging으로 배포될 수 있는 portable skill layer로 취급한다.
## Waiver와 요약 판정
필수 체크를 정말 만족시킬 수 없을 때만 `PREFLIGHT_WAIVE`로 label을 지정한다.
```console
$ PREFLIGHT_WAIVE=redaction-extra ORCA_AGENT_CLI=claude bash scripts/onboarding-preflight.sh
```
waive는 조용히 통과시키지 않는다. 해당 label은 `WAIVED`로 출력되고, summary는 `READY WITH WAIVERS`라고 말한다. 오타난 waiver는 적용되지 않고 “named checks that did not run”으로 출력되며 원래 check는 계속 enforced 상태다.
정상 종료 메시지는 세 가지 형태다.
| summary | 의미 |
| --- | --- |
| `READY: all required checks passed` | 필수 체크 만족 |
| `READY WITH WAIVERS` | 일부 필수 체크가 downgrade되었지만 만족된 것은 아님 |
| `BLOCKED: fix every FAIL before onboarding` | founding 진행 금지 |
## Instance config에 남기는 값
preflight로 확인한 master CLI는 instance-owned config에 기록한다. template example은 커밋용 예시이고, 채워진 config는 설치 인스턴스 소유다.
```console
$ test -f config/instance-runtime.json || cp config/instance-runtime.example.json config/instance-runtime.json
```
주요 필드는 다음과 같다.
| 필드 | 의미 |
| --- | --- |
| `master_host_runtime` | master session을 실행하는 agent CLI 이름 |
| `transcript_globs` | runtime 이름별 session JSONL glob |
| `product_repo` | 선택 primary product repository의 절대 경로 |
model tier policy도 instance-owned 파일이다.
```console
$ test -f config/model-tier-policy.json || cp config/model-tier-policy.example.json config/model-tier-policy.json
```
`version`은 `2`여야 한다. `agents`는 측정되었거나 사용자가 직접 명명한 runtime/model inventory이고, `tiers`는 model id 목록이다. 측정 불가 값은 추측하지 않고 `unknown`으로 둔다. `fanout_caps`에서 누락된 tier는 uncapped로 해석된다.
## 설치 실패 신호
| 증상 | 우선 확인 | 조치 |
| --- | --- | --- |
| `orca`는 있는데 orchestration이 `FAIL` | `run-current --json`의 Run 상태 | `orca orchestration run-create` 후 재실행 |
| preflight가 `BLOCKED` | `FAIL` label | 각 label을 수리; waiver는 의도와 비용을 기록할 때만 사용 |
| `gitleaks` 없음 | `WARN gitleaks` | publish 전 설치; master 실행만으로는 block 아님 |
| redaction rules 없음 | `FAIL redaction-extra` | 로컬 org rules 파일 작성, 최소 1개 usable rule 유지 |
| `bd where`가 ops repo 밖 | 반환된 `.beads` 경로 | ops repo에서 실행하거나 Beads 설정 수리 |
| worker runtime 없음 | `FAIL worker-runtime` | `codex` 또는 `cursor-agent` 중 하나 이상 설치 |
| `gh` auth warning | `gh auth status` | push/PR 작업 전 `gh auth login` 또는 `gh auth refresh -h github.com -s workflow` |
## Next
clone, Orca 프로젝트 등록, agent 시작, wake-up 문장까지의 최소 실행 경로.
`redaction-scan.sh`, `redaction-inventory`, pre-push hook, release gate 범위.
preflight `BLOCKED`, Orca CLI 미등록, misplacement, redaction 판단 불가 증상별 대응.
`instance-runtime.json`, `model-tier-policy.json`, 환경 변수 override와 fail-closed 동작.
---
## 03. Quickstart
> 저장소 clone, Orca 프로젝트 등록, 에이전트 시작, wake-up 문장, 첫 작은 작업까지의 최소 실행 경로를 문서화합니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/03-quickstart.md
- Generated: 2026-08-10T07:37:29.174Z
### Source Files
- `local-mogui-ade-orchestrator:README.md`
- `local-mogui-ade-orchestrator:docs/public/getting-started.md`
- `local-mogui-ade-orchestrator:docs/assets/wake-up-master.png`
- `local-master-ops:ONBOARDING.md`
- `local-master-ops:onboarding/00-orientation.md`
---
title: "Quickstart"
description: "저장소 clone, Orca 프로젝트 등록, 에이전트 시작, wake-up 문장, 첫 작은 작업까지의 최소 실행 경로를 문서화합니다."
---
`mogui-ADE-orchestrator`의 최소 시작 경로는 런타임 저장소를 clone하고, 그 폴더를 Orca 프로젝트로 등록한 뒤, Orca 터미널 안에서 선택한 agent CLI를 실행해 `master-ops/ONBOARDING.md` 라우터로 진입하는 흐름이다. 설치 인터뷰는 별도 ops 저장소를 만들고, workspace seat를 기록하며, Generation 1 Master를 Orca orchestration 경로로 spawn한다.
## 전제 조건
첫 실행 전에 모든 항목을 완성할 필요는 없지만, Step 0 preflight가 아래 표면을 실제로 측정한다. `FAIL`은 founding 진행을 막고, `WARN`은 실행은 가능하지만 비용이나 제한을 명시한다.
| 항목 | 확인 명령 또는 신호 | 실패 시 의미 |
| --- | --- | --- |
| Orca CLI | `orca status --json` | Orca runtime이 준비되지 않아 Master seat와 orchestration을 만들 수 없다. |
| Orca orchestration Run | `orca orchestration run-current --json` | 현재 터미널에 non-legacy Run이 바인딩되지 않아 task family가 동작하지 않는다. |
| Master agent CLI | `ORCA_AGENT_CLI= bash scripts/onboarding-preflight.sh` | Master를 실행할 CLI가 `PATH`에 없다. |
| Worker runtime | `command -v codex` 또는 `command -v cursor-agent` | 위임할 executor가 없다. 하나만 있어도 시작은 가능하다. |
| `git`, `gh`, `python3`, `bd` | 각 `--version` 또는 `bd where` | 저장소 운영, PR 경로, Python entrypoint, issue tracker 연결이 불완전하다. |
| Orca skills | `orca-cli`, `orchestration` skill artifact | agent가 Orca 표면을 안정적으로 호출할 수 없다. |
| Redaction rules | `REDACTION_EXTRA_PATTERNS` 또는 `~/.config/redaction-extra.txt` | publish gate가 조직별 민감정보 규칙을 판단할 수 없다. |
`bash scripts/onboarding-preflight.sh --fix`는 설치 가능한 일부 의존성 설치와 `ctx` local history index 설정을 시도할 수 있다. 처음에는 no-flag preflight로 측정한 뒤, 설치 동의를 별도로 결정한다.
## 최소 실행 경로
```console
$ git clone https://github.com/baksohyeon/mogui-ADE-orchestrator
$ cd mogui-ADE-orchestrator
```
이 clone은 installer이자 runtime source다. Founding이 끝나면 workspace governance는 새 ops 저장소에 기록되고, 이 clone 자체가 영구 Master seat가 되는 것은 아니다.
Orca UI에서 프로젝트를 추가하고 workspace root 또는 이 clone 폴더를 선택한다. CLI가 등록되어 있으면 같은 작업을 터미널에서도 실행할 수 있다.
```console
$ orca repo add --path
```
등록 후 Orca 안에서 터미널을 열고 `pwd`가 installer를 시작할 checkout인지 확인한다. multi-repo workspace에서는 Master가 개별 제품 저장소 worktree가 아니라 workspace root의 folder workspace에 앉아야 한다.
선택한 Master host CLI를 실행한다. 가장 많이 검증된 host는 `claude`지만, onboarding은 `ORCA_AGENT_CLI`로 선택한 CLI를 기록한다.
```console
$ claude
```
다른 CLI를 쓰는 경우에도 실제로 계속 사용할 binary 이름을 선택해야 한다. preflight는 그 이름이 `PATH`에서 해석되는지 확인한다.
구체적인 작업을 주지 말고 짧은 wake-up 문장만 입력한다.
```text
일어나라 마스터여
```
```text
Wake the master.
```
라우터가 의존하는 것은 문장의 의식적 표현보다 “아직 구체 작업이 없다”는 상태다. agent는 installer로 동작하며 `master-ops/ONBOARDING.md`를 읽고 session mode부터 분류한다.
## Onboarding에서 선택하는 것
처음 질문은 session mode다. 새 workspace라면 `Founding`을 선택한다. 이미 ops 저장소나 lineage가 있으면 `Reverify` 또는 `Upgrade` 경로로 가야 하며, Founding을 다시 실행해 두 번째 Master를 만들면 안 된다.
| 결정 | 기록되는 내용 |
| --- | --- |
| Workspace root | Master가 관리할 absolute root path. agent가 후보를 스캔해 대신 고르지 않는다. |
| Repository inventory | workspace root 바로 아래의 Git 저장소 목록. 기본은 측정된 모든 child repository 포함이다. |
| Ops repository | workspace governance, lineage, runbook, tracker 상태를 담는 별도 저장소다. |
| Master callsign | 살아 있는 Master session을 부를 짧은 이름이다. `Master`는 역할명이다. |
| Model and runtime config | `config/instance-runtime.json`, `config/model-tier-policy.json`에 instance-owned 값으로 기록된다. |
| Gen-1 spawn 승인 | Orca Run, Task, Dispatch를 만들고, placement 검증된 터미널 하나를 생성한다. |
## 성공 판정
Founding 성공은 “installer가 완료라고 말했다”가 아니라 다음 신호로 판단한다.
| 신호 | 기대 상태 |
| --- | --- |
| Master pane | Orca에서 workspace seat에 정확히 하나의 Generation 1 Master terminal이 있다. |
| Role State | 새 Master가 callsign, active role, Role Lock 상태를 선언한다. |
| Model identity | 측정 가능, unavailable, unsupported 중 하나로 보고된다. 추측값으로 채우지 않는다. |
| Placement evidence | host pane/worktree selector, cwd, session artifact namespace가 workspace root와 맞는다. |
| Lineage | `docs/lineage/MASTER-LINEAGE.md`에 Generation 1 항목이 append된다. |
| Completion | founding Task와 Dispatch가 `worker_done`으로 완료된다. |
multi-repo workspace의 Master가 제품 저장소 worktree 아래에 보이면 misplacement로 다룬다. 새 Founding을 반복하지 말고 ops 저장소의 recovery 또는 succession 경로를 사용한다.
## 첫 작은 작업
첫 작업은 편집 없는 확인 작업으로 시작한다. 목적은 Master가 proposal, approval, dispatch, evidence acceptance를 분리하는지 보는 것이다.
```text
저장소에서 README.md를 열고 최상위 section heading만 나열해 주세요.
파일은 수정하지 마세요. 결과물은 heading 목록입니다.
```
정상 흐름은 다음과 같다.
1. Master가 대상 저장소, 허용 surface, acceptance criteria, evidence를 좁은 contract로 다시 쓴다.
2. 사용자가 contract를 확인하고 실행을 승인한다.
3. Master가 Orca orchestration으로 Task를 만들고 worker terminal에 Dispatch를 attach한다.
4. worker가 artifact와 evidence를 반환한다.
5. Master가 worker의 `done` 주장을 직접 검증한 뒤 accept 또는 reject를 말한다.
이 경로는 provider-specific plugin 호출이 아니라 Orca Run, Task, Dispatch, `worker_done` mailbox를 사용하는 vendor-neutral orchestration 표면이다. 선택한 agent CLI와 skill pack은 교체 가능한 실행 계층이며, workspace 사실과 governance는 파일, Git 저장소, issue tracker에 남는다.
## 자주 막히는 지점
| 증상 | 먼저 확인할 것 | 처리 |
| --- | --- | --- |
| `orca` 명령이 없다 | Orca Settings의 CLI 등록 | `Settings → Orca CLI → Shell command`를 켠다. |
| preflight가 `BLOCKED`로 끝난다 | `FAIL` label | 각 label을 고친다. `PREFLIGHT_WAIVE=`은 의미를 이해한 경우에만 쓴다. |
| Run이 없다고 나온다 | `orca orchestration run-current --json` | `orca orchestration run-create`로 현재 터미널에 Run을 바인딩한다. |
| `Unavailable worktree`가 보인다 | Master가 folder workspace에 있는지 | folder workspace Master에서는 정상 label일 수 있다. path 대신 `worktreeId`를 본다. |
| 두 번째 Master가 보인다 | `orca terminal list`와 lineage | duplicate Master incident로 처리한다. Founding을 반복하지 않는다. |
| 첫 worker가 완료를 말했지만 Master가 accept하지 않는다 | artifact와 evidence | worker의 완료 보고는 claim이다. acceptance는 Master의 재검증 결과다. |
## Next
preflight 의존성, Orca CLI 등록, agent CLI, Beads, redaction rules를 먼저 점검한다.
Founding, Reverify, Upgrade, Template improve의 진입 조건과 spawn 금지 조건을 구분한다.
Project, workspace, worktree, terminal, Run, selector와 placement 실패 조건을 확인한다.
contract, dispatch gate, Orca task-create, worker completion, acceptance 재검증 흐름을 따라간다.
preflight `BLOCKED`, Orca CLI 미등록, duplicate master, model probe undecidable 같은 증상별 조치를 본다.
---
## 04. 온보딩 모드
> Founding, Reverify, Upgrade, Template improve 모드의 진입 조건, 금지된 spawn 경로, 단계별 파일 라우팅을 설명합니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/04-page-4.md
- Generated: 2026-08-10T07:37:16.589Z
### Source Files
- `local-master-ops:ONBOARDING.md`
- `local-master-ops:onboarding/reverify.md`
- `local-master-ops:onboarding/upgrade.md`
- `local-master-ops:onboarding/09-spawn.md`
- `local-mogui-ade-orchestrator:tests/test_onboarding_structure.py`
---
title: "온보딩 모드"
description: "Founding, Reverify, Upgrade, Template improve 모드의 진입 조건, 금지된 spawn 경로, 단계별 파일 라우팅을 설명합니다."
---
`local-master-ops:ONBOARDING.md`는 온보딩을 네 가지 모드로 먼저 분류한 뒤, Founding만 번호가 붙은 단계 파일 `00`부터 `10`까지 진행하게 한다. Reverify와 Upgrade는 각각 단일 모드 파일만 읽고 끝나며, Template improve는 설치 흐름이 아니라 오케스트레이터 저장소의 일반 작업으로 라우팅된다.
## 모드 선택 규칙
온보딩 세션은 측정이나 orientation 전에 모드를 먼저 확정한다. 선택한 모드와 실제 증거가 충돌하면 하이브리드 흐름을 만들지 않고 중단한 뒤 증거와 함께 다시 묻는다.
| 모드 | 진입 조건 | 파일 라우팅 | 쓰기 범위 | spawn |
|---|---|---|---|---|
| Founding | 진짜 새 workspace이고 ops repository 또는 lineage가 없음 | `00-orientation.md` → `10-card-and-retire.md` | 새 ops repository 생성, placeholder 치환, tracker 연결, Gen-1 기록 | Step 8에서만 허용 |
| Reverify | 이미 ops repository와 master가 있음 | `reverify.md` 단독 | 원칙적으로 read-only, 분실한 operating card 재출력만 예외 | 금지 |
| Upgrade | 이미 founded workspace이고 template layer가 뒤처짐 | `upgrade.md` 단독 | owner 확인 후 template manifest가 주장하는 파일만 적용 | 금지 |
| Template improve | 이 orchestrator repository 자체의 문서나 코드 수정 | 온보딩 중단, 일반 master/worker 작업 | 작업 성격에 따름 | 온보딩 spawn 아님 |
기존 ops repository 또는 `docs/lineage/MASTER-LINEAGE.md`가 보이면 Founding으로 계속 진행하지 않는다. master가 죽었거나 Gen-1 boot가 반쯤 끝난 상태도 Founding이 아니며, recovery는 설치 재실행이 아니라 ops repository의 `docs/runbooks/succession-boot-card.md`가 소유한다.
## Founding 파일 라우팅
Founding은 progressive loading을 강제한다. installer는 현재 단계 파일 하나만 읽고, 해당 단계의 Verify가 통과하기 전에는 다음 파일을 열지 않는다.
| 순서 | 파일 | 산출물 |
|---|---|---|
| 00 | `local-master-ops:onboarding/00-orientation.md` | orchestrator, ops, session 세 계층 설명 |
| 01 | `local-master-ops:onboarding/01-preflight.md` | 필수 CLI와 host 조건 확인 |
| 02 | `local-master-ops:onboarding/02-workspace-facts.md` | workspace root, 이름, inventory, model 후보 |
| 03 | `local-master-ops:onboarding/03-ops-repo.md` | ops repository 선택 또는 생성 |
| 04 | `local-master-ops:onboarding/04-seat.md` | Orca workspace seat 등록과 durable selector |
| 05 | `local-master-ops:onboarding/05-placeholders.md` | template placeholder 치환, root session card 배포 |
| 06 | `local-master-ops:onboarding/06-tracker.md` | workspace root에서 tracker 확인 |
| 07 | `local-master-ops:onboarding/07-user-rules.md` | owner rules와 master callsign |
| 08 | `local-master-ops:onboarding/08-settings-and-skills.md` | hook owner, skill stack, publish gate 범위 |
| 09 | `local-master-ops:onboarding/09-spawn.md` | Generation 1 master spawn, boot smoke |
| 10 | `local-master-ops:onboarding/10-card-and-retire.md` | operating card 출력, installer retirement |
`local-mogui-ade-orchestrator:tests/test_onboarding_structure.py`는 이 구조를 테스트로 고정한다. router index와 실제 `onboarding/*.md` 목록이 달라지면 실패하고, numbered step은 `Owner script`와 `Verify` 섹션을 가져야 한다. `reverify.md`와 `upgrade.md`는 numbered step이 아니라 `Checklist`와 `Report` 구조를 가진 모드 파일로 검사된다.
## Founding에서만 허용되는 spawn
Founding의 spawn은 Step 8에서만 실행한다. 이 단계는 workspace 준비가 끝난 뒤 Orca orchestration Run과 Task를 만들고, durable placement selector로 검증된 새 terminal 하나를 생성한 뒤 Dispatch를 붙여 `worker_done`을 기다린다.
```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
```
Spawn 전 gate 조건은 fail-closed다.
| 조건 | 필요한 판정 |
|---|---|
| seat listing | selector가 host에서 resolve되고 seat terminal 수가 0 |
| dispatch gate | `allow: true` |
| placement verification | `MATCH` 또는 `MATCH_REISSUED` |
| session count | 새 master process/session 정확히 1개 |
| kickoff | master가 받은 content가 kickoff file과 byte-identical |
| completion | active Dispatch가 `worker_done`으로 완료 |
실패 시 filesystem path selector로 재시도하지 않는다. installer 안에서 master boot를 대신 수행하지 않고, 두 번째 session도 만들지 않는다. 설정을 고친 뒤에는 기존 실패 spawn을 재사용하지 않고 fresh session으로 다시 시작한다.
## 금지된 spawn 경로
Reverify와 Upgrade는 모두 standing block을 가진다.
| 금지 항목 | 적용 모드 | 이유 |
|---|---|---|
| 새 master terminal 생성 | Reverify, Upgrade | 두 번째 master는 편의가 아니라 incident |
| `master-succeed spawn` | Reverify, Upgrade | spawn은 Founding Step 8 또는 succession 소유 |
| founding kickoff 작성 | Reverify, Upgrade | 기존 workspace를 다시 founding하면 lineage와 governance record가 오염됨 |
| raw terminal polling 또는 vendor-direct CLI dispatch | Founding spawn 포함 전체 | supervised dispatch는 Orca orchestration만 허용 |
| dead master를 Founding으로 복구 | 전체 | recovery는 `docs/runbooks/succession-boot-card.md` 경로 |
## Reverify 체크리스트
Reverify는 이미 founded workspace를 검사하고 보고한 뒤 멈춘다. workspace root와 ops repository path는 owner가 제공한 operating card 또는 명시 답변에서 가져오며, disk를 scan해 후보 workspace를 추측하지 않는다.
`{{WORKSPACE_ROOT}}`, `{{OPS_REPO}}`, durable placement selector를 기존 ops repository에서 읽는다. 이 모드는 workspace facts 단계 파일을 로드하지 않는다.
`orca terminal list --worktree --json` 결과에 live master terminal이 정확히 하나 있어야 한다. `{{WORKSPACE_ROOT}}`에서 `bd where`가 ops repository로 resolve되어야 하며, 상위 directory의 tracker database가 shadowing하면 실패다.
`docs/runbooks/role-state.md`에는 active role이 하나여야 하고 Role Lock state가 있어야 한다. Generation은 `docs/lineage/MASTER-LINEAGE.md`의 마지막 entry와 맞아야 한다.
template path가 있으면 `template-check --ops ... --template ...`를 실행한다. 없으면 installed `template-check --ops ...`만 실행하고 `report_set: install-manifest`로 기록한다. Reverify는 behind 상태를 고치지 않고 Upgrade로 라우팅한다.
허용되는 유일한 write는 operating card가 분실되었을 때 `10-card-and-retire.md`를 read-only로 열어 현재 값으로 재출력하는 것이다. placeholder 잔존, root session card drift, template behind는 모두 보고 대상이며 이 모드에서 수정하지 않는다.
## Upgrade 체크리스트
Upgrade는 founded ops repository를 현재 template manifest와 비교하고, owner가 명시적으로 승인한 뒤 template-layer 파일만 적용한다. lineage, role state, tracker data, local config, contracts는 이름으로 거부된다.
```console
"{{RUNTIME_ROOT}}/master-ops/scripts/template-check" --ops "{{OPS_REPO}}" --template "{{RUNTIME_ROOT}}/master-ops"
```
`template-check` report는 두 종류다.
| `report_set` | 의미 |
|---|---|
| `install-manifest` | installed `MANIFEST.json` 기준으로 required path 누락과 unknown path를 보고 |
| `template-compare` | template version, installed version, changelog adoption note까지 포함 |
Exit code는 `0`이 current 또는 drift 없음, `1`이 check 가능하지만 drift 또는 behind 있음, `2`가 missing/malformed input으로 check 불가다.
적용은 항상 dry-run이 먼저다.
```console
"{{RUNTIME_ROOT}}/master-ops/scripts/template-apply" --ops "{{OPS_REPO}}" --template "{{RUNTIME_ROOT}}/master-ops"
```
쓰기 pass는 `--write`와 확인 phrase가 필요하다. `--yes` 경로는 없다. placeholder 치환은 allowlist에 있는 값만 받는다.
```console
"{{RUNTIME_ROOT}}/master-ops/scripts/template-apply" \
--ops "{{OPS_REPO}}" \
--template "{{RUNTIME_ROOT}}/master-ops" \
--write \
--placeholder WORKSPACE_NAME="{{WORKSPACE_NAME}}" \
--placeholder WORKSPACE_ROOT="{{WORKSPACE_ROOT}}" \
--placeholder OPS_REPO="{{OPS_REPO}}" \
--placeholder MONITOR_NS="{{MONITOR_NS}}" \
--placeholder MODEL_ID="{{MODEL_ID}}" \
--placeholder REPO_LIST="{{REPO_LIST}}" \
--placeholder RUNTIME_ROOT="{{RUNTIME_ROOT}}" \
--placeholder TEMPLATE_VERSION="{{TEMPLATE_VERSION}}"
```
## Placeholder와 instance-owned 경계
허용 placeholder는 다음 여덟 개뿐이다.
| placeholder |
|---|
| `{{WORKSPACE_NAME}}` |
| `{{WORKSPACE_ROOT}}` |
| `{{OPS_REPO}}` |
| `{{MONITOR_NS}}` |
| `{{MODEL_ID}}` |
| `{{REPO_LIST}}` |
| `{{RUNTIME_ROOT}}` |
| `{{TEMPLATE_VERSION}}` |
Upgrade apply가 이름으로 instance-owned 처리하는 경로는 다음과 같다.
| 경로 | 처리 |
|---|---|
| `docs/lineage/` | `skipped-as-instance-owned` |
| `docs/runbooks/role-state.md` | `skipped-as-instance-owned` |
| `.beads/` | `skipped-as-instance-owned` |
| `config/` | `skipped-as-instance-owned` |
| `contracts/` | `skipped-as-instance-owned` |
| manifest가 주장하지 않는 경로 | `refused-not-in-manifest` |
Per-file outcome은 `planned`, `written`, `skipped-as-instance-owned`, `refused-not-in-manifest`, `error-invalid-path`, `error-missing-template-file` 중 하나다. `error-*`가 있으면 write confirmation 전에 plan이 실패한다.
## Template improve 라우팅
Template improve는 installation mode가 아니다. 대상이 `local-master-ops`의 router, onboarding step, template scripts, tests, docs, manifest 또는 orchestrator runtime이면 온보딩 절차를 중단하고 일반 작업으로 다룬다. 이 경로에서 Gen-1 master를 만들거나 기존 workspace를 reverify하지 않는다.
일반 작업으로 라우팅한 뒤에는 해당 repository의 작업 규칙을 따른다. 작업이 온보딩 문서 구조를 바꾸면 `local-mogui-ade-orchestrator:tests/test_onboarding_structure.py`가 고정하는 router index, next-file pointer, placeholder allowlist, no-spawn block을 함께 갱신해야 한다.
## Related pages
새 workspace root 선택부터 Gen-1 spawn과 boot smoke까지의 Founding 절차.
dead master, long session, successor spawn은 Founding이 아니라 succession 경로에서 처리한다.
`MANIFEST.json`, template version, placeholder, `template-check`, `template-apply`의 template-layer surface.
misplacement, duplicate master, unavailable worktree, model probe undecidable 같은 실패 신호별 대응.
---
## 05. 워크스페이스와 제품 저장소 관계
> 오케스트레이터 저장소, 설치 후 생성되는 ops 저장소, 제품 저장소, sibling checkout 모델, 단일 저장소 예외를 구분합니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/05-page-5.md
- Generated: 2026-08-10T07:37:03.616Z
### Source Files
- `local-mogui-ade-orchestrator:README.md`
- `local-mogui-ade-orchestrator:docs/public/concepts.md`
- `local-mogui-ade-orchestrator:config/workspace-descriptor.example.json`
- `local-mogui-ade-orchestrator:src/master_runtime/core/workspace_descriptor.py`
- `local-master-ops:onboarding/02-workspace-facts.md`
- `local-master-ops:docs/charter/01-document-map.md`
---
title: "워크스페이스와 제품 저장소 관계"
description: "오케스트레이터 저장소, 설치 후 생성되는 ops 저장소, 제품 저장소, sibling checkout 모델, 단일 저장소 예외를 구분합니다."
---
`mogui-ADE-orchestrator`는 워크스페이스 런타임과 `master-ops/` 템플릿을 함께 보관하고, 설치 과정은 확인된 워크스페이스 루트 아래의 sibling Git checkout 목록을 `config/workspace-descriptor.json` 인벤토리로 고정한다. 제품 저장소는 이 인벤토리의 `role: "product"` 항목이고, 설치 후 생성되거나 재사용되는 ops 저장소는 `role: "ops"` 항목이다.
## 저장소 경계
| 구분 | 위치 | 역할 | 커밋 대상 |
| --- | --- | --- | --- |
| 오케스트레이터 저장소 | `mogui-ADE-orchestrator/` | 런타임 코드, 공개 `scripts/`, 설정 예시, `master-ops/` 템플릿을 제공한다. | 런타임과 템플릿 변경 |
| 템플릿 `master-ops/` | `mogui-ADE-orchestrator/master-ops/` | 설치 시 복사되는 운영 골격이다. `MANIFEST.json`과 `TEMPLATE-VERSION`이 템플릿 표면을 정의한다. | 템플릿 개선 |
| 설치된 ops 저장소 | 워크스페이스 루트 아래의 승인된 `{{OPS_REPO}}` | 차터, lineage, decisions, runbooks, workspace card, tracker 상태를 보관한다. | 워크스페이스 운영 기록 |
| 제품 저장소 | 워크스페이스 루트 아래의 일반 sibling checkout | 작업자가 PR, 검증, 구현 대상으로 다루는 실제 제품 코드다. | 제품 변경 |
`{{OPS_REPO}}` 선택은 `{{WORKSPACE_ROOT}}` 선택과 별개다. ops 저장소는 제품 코드와 혼동되지 않는 작은 governance 저장소로 만들거나 기존 운영 저장소를 재사용한다.
## 기본 파일 시스템 모델
워크스페이스 루트는 Git 상위 저장소나 submodule parent가 아니라 “여러 저장소를 묶는 일반 폴더”다. 설치 과정은 사용자가 붙여넣은 절대 경로만 검증하고, 에이전트가 주변 디렉터리를 스캔해 후보를 대신 고르지 않는다.
```text
{{WORKSPACE_ROOT}}/
product-api/ # role: product
product-web/ # role: product
{{OPS_REPO}}/ # role: ops
CLAUDE.md # ops 저장소 workspace-card에서 배포된 세션 카드
AGENTS.md # ops 저장소 workspace-card에서 배포된 세션 카드
```
일반 다중 저장소 모델에서 `master_seat`는 보통 워크스페이스 루트의 folder workspace다. Orca가 이 plain folder를 “not a valid worktree folder”처럼 표시할 수 있지만, 이 런타임에서는 folder project의 정상 조건일 수 있다.
## `workspace-descriptor.json`
확인된 저장소 목록은 런타임 clone의 `config/workspace-descriptor.json`에 기록된다. 저장소는 workspace-root-relative `path`로 식별하며, 절대 경로 매칭은 `workspace_root`가 설정된 경우에만 그 루트 아래 상대 경로로 변환해 처리한다.
```json title="config/workspace-descriptor.json"
{
"workspace_root_is_plain_folder": true,
"workspace_root": "/absolute/path/to/workspace-root",
"master_seat": "folder-workspace-of-workspace-root",
"repositories": [
{
"name": "product-api",
"path": "product-api",
"remote": "https://github.com/example/product-api.git",
"role": "product",
"capabilities": ["pr", "dispatch-target"],
"prohibited": ["direct-main-commit", "force-push"]
},
{
"name": "workspace-ops",
"path": "workspace-ops",
"remote": "",
"role": "ops",
"capabilities": ["pr", "dispatch-target"],
"prohibited": ["force-push"]
}
]
}
```
항상 `true`다. `false`이면 런타임은 submodule parent 또는 non-plain workspace root로 보고 거부한다.
절대 경로 매칭을 워크스페이스 루트 아래로 묶는 값이다. 없으면 절대 경로 후보는 저장소 항목과 매칭되지 않는다.
마스터 세션이 앉을 Orca seat 라벨이다. 다중 저장소는 보통 folder workspace, 단일 저장소 예외는 primary worktree를 쓴다.
제품 코드 저장소와 운영 저장소를 구분한다. 다른 role 값은 유효하지 않다.
하드 블록할 action 목록이다. 누락은 오류이며, 금지가 없다는 뜻은 owner-confirmed `[]`로만 표현한다.
## 해석 순서와 실패 기본값
descriptor 소비자는 같은 우선순위로 설정을 찾는다.
1. 명시 경로 또는 환경 변수: `WORKSPACE_DESCRIPTOR`, `MOGUI_WORKSPACE_DESCRIPTOR`
2. 기본 파일: `config/workspace-descriptor.json`
3. 정직한 unconfigured 상태
`scripts/workspace-descriptor-check`는 repository path와 action을 받아 허용 여부를 반환한다.
```bash
scripts/workspace-descriptor-check \
--path product-api \
--action direct-main-commit \
--json
```
| 종료 코드 | 의미 | 운영 판단 |
| --- | --- | --- |
| `0` | descriptor가 해당 action을 금지하지 않음 | 계속 진행 가능 |
| `1` | 해당 저장소에서 action이 금지됨 | 중단 |
| `2` | descriptor가 없거나 유효하지 않아 판단 불가 | fail closed |
알 수 없는 저장소는 기본적으로 금지로 취급한다. `--allow-unknown-repo`는 이 기본값을 바꾸지만, 워크스페이스 경계가 불명확한 작업에는 쓰지 않는다.
## 제품 저장소와 ops 저장소의 기본 금지
설치 단계의 기본값은 제품 저장소와 ops 저장소를 다르게 취급한다.
| role | 기본 capabilities | 기본 prohibited |
| --- | --- | --- |
| `product` | `["pr", "dispatch-target"]` | `["direct-main-commit", "force-push"]` |
| `ops` | `["pr", "dispatch-target"]` | `["force-push"]` |
제품 저장소의 직접 main commit과 force push는 기본 금지다. ops 저장소는 운영 기록을 보관하므로 force push가 기본 금지지만, 직접 커밋 금지는 제품 저장소 기본값처럼 자동 적용되지 않는다. owner가 descriptor를 확인한 뒤 instance 파일에서 조정한 값이 우선한다.
## 단일 저장소 예외
워크스페이스가 실제로 하나의 저장소 자체인 경우에만 `path: "."`를 사용한다. 이때 워크스페이스 루트와 제품 checkout이 같은 디렉터리이고, `master_seat`는 primary worktree가 된다.
```json title="단일 저장소 workspace-descriptor.json"
{
"workspace_root_is_plain_folder": true,
"workspace_root": "/absolute/path/to/single-repo",
"master_seat": "primary-worktree",
"repositories": [
{
"name": "single-repo",
"path": ".",
"remote": "",
"role": "product",
"capabilities": ["pr"],
"prohibited": ["direct-main-commit"]
}
]
}
```
이 예외는 “한 제품 저장소만 있다”는 이유만으로 자동 선택하지 않는다. 일반 규칙은 한 저장소만 있더라도 그 부모 폴더를 workspace root로 두는 것이다. `path: "."`는 workspace root 자체가 그 단일 저장소라는 owner-confirmed 구조에서만 쓴다.
## 워크스페이스 밖 저장소
사용자가 워크스페이스 밖의 저장소를 작업 대상으로 지정하면 기본 처리 방향은 move 또는 clone이다. 저장소가 `{{WORKSPACE_ROOT}}` 아래 sibling checkout으로 들어와야 인벤토리, Orca sidebar, 작업 측정이 같은 경계 안에서 동작한다.
외부 경로를 유지해야 하는 경우에는 일반 repository 항목처럼 암묵적으로 추가하지 않는다. 별도 external lane으로 절대 경로, 쓰기 권한, push 전 gate를 기록하고, 각 주장마다 따로 측정한다.
## 설치된 ops 저장소가 받는 파일
새 ops 저장소는 템플릿의 `MANIFEST.json`에 있는 Stage 1 skeleton을 복사해 만든다. 생성된 ops 저장소에는 `CLAUDE.md`, `AGENTS.md`, `docs/MASTER-OPERATIONS.md`, `docs/charter/`, `docs/runbooks/`, `docs/lineage/`, `workspace-card/`, `scripts/` 등이 들어간다.
템플릿 전용 파일은 설치된 ops 저장소에 남기지 않는다.
| 템플릿 전용 | 이유 |
| --- | --- |
| `TEMPLATE-VERSION` | 템플릿 stamp이며 설치된 ops는 `MANIFEST.json.template_version`으로 기록한다. |
| `CHANGELOG.md` | 템플릿 변경 이력이다. |
| `ONBOARDING.md` | 설치 라우터다. |
| `onboarding/` | 설치 절차 파일 묶음이다. |
`workspace-card/CLAUDE.md`와 `workspace-card/AGENTS.md`는 워크스페이스 루트의 세션 카드로 배포된다. ops 저장소 루트의 `CLAUDE.md` / `AGENTS.md`와는 다른 문서 쌍이다.
## 관련 pages
설치 전 도구 측정, preflight, instance config, redaction rules를 확인합니다.
workspace root 선택, ops 저장소 생성, descriptor 작성, Gen-1 spawn 절차를 봅니다.
Project, workspace, worktree, terminal, folder workspace 라벨과 misplacement 조건을 구분합니다.
`workspace-descriptor.json`, `instance-runtime.json`, 환경 변수 override, fail-closed 동작을 확인합니다.
---
## 06. Orca 객체 모델
> Project, workspace, worktree, terminal, Run, selector 형식, folder workspace의 정상 라벨과 misplacement 실패 조건을 설명합니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/06-orca.md
- Generated: 2026-08-10T07:37:13.789Z
### Source Files
- `local-mogui-ade-orchestrator:docs/public/orca-concepts.md`
- `local-mogui-ade-orchestrator:docs/public/getting-started.md`
- `local-mogui-ade-orchestrator:src/master_runtime/core/succession.py`
- `local-mogui-ade-orchestrator:tests/test_succession.py`
- `local-master-ops:docs/runbooks/succession-boot-card.md`
---
title: "Orca 객체 모델"
description: "Project, workspace, worktree, terminal, Run, selector 형식, folder workspace의 정상 라벨과 misplacement 실패 조건을 설명합니다."
---
Orca 런타임은 master와 worker를 모두 Orca terminal에 앉히며, `worktreeId`, `worktreePath`, terminal handle, orchestration Run을 서로 다른 식별자로 취급한다. multi-repository workspace에서 master의 정상 좌석은 workspace root의 folder workspace이고, worker의 정상 좌석은 작업 대상 repository worktree이다.
## 객체 경계
| 객체 | 의미 | 정상 소유자 | 주요 식별자 |
| --- | --- | --- | --- |
| Project | Orca에 등록된 폴더 단위 | Orca sidebar | 등록된 folder 또는 repository |
| Workspace | terminal이 생성되는 좌석 | Project | repository worktree 또는 folder workspace |
| Worktree | Git checkout이 있는 repository workspace | worker | `repoId::path`, `id:::` |
| Folder workspace | Git checkout이 없는 folder project 좌석 | master | `folder:`, 권장 기록형은 `id:folder:` |
| Terminal | Orca가 관리하는 live session | master 또는 worker | `handle`, `ptyId`, `sessionId` |
| Run | terminal에 묶인 durable orchestration context | coordinator | task, dispatch, mailbox 상태 |
folder workspace는 Git checkout이 아니다. 따라서 `worktreePath`가 빈 문자열이어도 정상이며, placement 판단은 `worktreeId`로 한다.
## master와 worker 좌석
multi-repository workspace에서 master는 repository 하나의 worktree 안에 있으면 안 된다. master는 여러 repository를 조정하므로 workspace root의 folder workspace에 앉아야 한다. 단일 repository workspace에서는 그 repository의 primary worktree가 workspace-level seat가 될 수 있다.
worker는 반대다. Git 작업을 해야 하는 worker는 대상 repository의 독립 worktree에서 시작해야 한다. folder workspace에 worker를 만들면 첫 명령이 checkout으로 이동하지 않는 한 `git` 작업이 실패하거나 잘못된 위치에서 실행된다.
```text
workspace root/
product-a/ <- worker worktree 대상 repository
product-b/ <- worker worktree 대상 repository
master-ops/ <- 운영 기록과 runbook
[folder workspace] <- master seat
```
## selector 형식
좌석은 terminal handle이 아니라 selector로 기록한다. handle은 live app runtime 안의 terminal 주소이고, 재시작이나 close 이후 durable seat identity가 아니다.
| selector | 용도 | 운영 판단 |
| --- | --- | --- |
| `id:::` | repository worktree | repository worker 좌석에 사용 |
| `id:folder:` | folder workspace | master seat의 권장 durable 형식 |
| `folder:` | folder workspace | `terminal create`에서는 동작할 수 있으나 `terminal list --worktree`와 비대칭이 있어 기록형으로 쓰지 않는다 |
| `path:/abs/dir` | filesystem path selector | Orca가 resolve할 수 있어도 placement 비교에서 mismatch를 만들 수 있으므로 master seat 기록에 쓰지 않는다 |
`orca terminal create --worktree`에 selector를 생략하면 현재 shell cwd에서 Orca가 좌석을 추론할 수 있다. 이 경로는 misplacement 원인이므로 founding, succession, reverify에서는 durable selector를 명시한다.
## 정상 라벨
folder workspace master에는 UI나 CLI에서 Git worktree가 없다는 신호가 나타난다. 이 신호는 장애가 아니다.
| 표시 | 의미 | 조치 |
| --- | --- | --- |
| `Unavailable worktree` | session이 Git worktree가 아닌 folder workspace에 있음 | master가 folder workspace에 있으면 정상 |
| 빈 `worktreePath` | folder workspace에는 checkout path가 없음 | `worktreeId`가 `folder:`인지 확인 |
| workspace root에서 `not a valid worktree folder` 계열 메시지 | workspace root가 plain folder임 | submodule parent나 Git repository로 바꾸지 않는다 |
## misplacement 실패 조건
misplacement는 terminal 생성이 실패한 상태만 뜻하지 않는다. terminal이 살아 있고 cwd, hook, session artifact가 모두 그럴듯해도 좌석이 틀리면 실패다.
다음 조건이면 master placement 실패로 본다.
| 조건 | 실패 이유 |
| --- | --- |
| multi-repo workspace의 master가 product repository worktree 아래에 표시됨 | master가 worker용 좌석에 앉아 workspace 전체를 대표하지 못함 |
| `worktreePath`만 보고 folder workspace를 실패로 판단함 | folder workspace의 정상 shape를 Git worktree 기준으로 오판함 |
| `path:` selector로 green 상태를 만든 뒤 durable selector로 기록함 | request 자체가 의도한 seat인지 검증하지 않음 |
| temporary seat-check terminal이 남아 있는데 founding spawn을 진행함 | master seat가 비어 있지 않아 duplicate master 위험이 있음 |
| Reverify에서 master 부재를 보고 Founding을 다시 실행함 | 기존 workspace에는 recovery 또는 succession 경로를 써야 함 |
## 검증 명령
좌석 검증은 Orca의 terminal metadata에서 시작한다.
```console
$ orca terminal show --terminal --json
```
folder workspace의 기대 shape:
```json
{
"worktreeId": "folder:",
"worktreePath": "",
"handle": "",
"connected": true
}
```
durable selector가 여전히 host에서 해석되는지 확인한다.
```console
$ orca terminal list --worktree id:folder: --json
```
founding spawn 전에는 이 목록이 비어 있어야 한다. reverify에서는 같은 selector에 live master terminal이 정확히 하나 있어야 한다.
## succession과 Run
succession은 기존 master가 새 terminal을 만들고, 새 terminal이 같은 workspace-level seat에 있는지 확인한 뒤 role state와 lineage를 이어받는 절차다. spawn 검증은 다음 값을 분리해서 본다.
| 값 | 역할 |
| --- | --- |
| `requested_worktree` | spawn 요청에 사용한 selector |
| `worktreeId` | Orca create/list 응답의 실제 seat |
| `expected_placement` | ops 기록이 기대하는 durable seat |
| `handle` | 새 terminal을 조작하기 위한 live 주소 |
| Run | task, dispatch, completion mailbox를 보존하는 orchestration context |
검증 결과는 `MATCH` 또는 `MATCH_REISSUED`만 성공으로 취급한다. `MATCH_REISSUED`는 create 응답의 handle이 stale일 때, 같은 selector 안의 새 live terminal을 title과 연결 상태로 재확인해 채택한 경우다. selector mismatch, expected placement mismatch, stale handle ambiguity는 fail-closed다.
## workspace descriptor
workspace inventory는 instance-owned `config/workspace-descriptor.json`에 둔다. template은 example만 제공하고, 실제 파일은 설치 환경의 absolute `workspace_root`와 repository 목록을 담을 수 있으므로 커밋 대상이 아니다.
핵심 필드:
| 필드 | 값 |
| --- | --- |
| `workspace_root_is_plain_folder` | 항상 `true` |
| `workspace_root` | owner가 확인한 absolute workspace root |
| `master_seat` | `id:folder:` 또는 단일 repository 예외의 primary seat |
| `repositories[].path` | workspace-root-relative path |
| `repositories[].role` | `product` 또는 `ops` |
| `repositories[].prohibited` | 예: `direct-main-commit`, `force-push` |
이 모델은 특정 agent CLI나 model provider에 종속되지 않는다. Orca의 project, workspace, terminal, Run 식별자를 기준으로 좌석과 dispatch를 검증하고, agent CLI는 terminal 안에서 실행되는 runtime으로 취급한다.
## Related pages
workspace root, ops repository, product repository의 경계를 구분한다.
folder workspace seat 측정과 founding spawn 절차를 실행 순서로 확인한다.
successor spawn, placement 검증, predecessor retirement 흐름을 다룬다.
misplacement, duplicate master, Unavailable worktree 증상을 진단한다.
---
## 07. 런타임 유닛
> Bootstrap, Context Resolver, Workspace Runtime, Worker Scheduler, Approval Manager, Recovery, Succession, Lineage, Adapter Layer의 구현 상태와 경계를 정리합니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/07-page-7.md
- Generated: 2026-08-10T07:38:51.076Z
### Source Files
- `local-mogui-ade-orchestrator:docs/public/concepts.md`
- `local-mogui-ade-orchestrator:src/master_runtime/core/bootstrap.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/context/resolver.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/work_ledger.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/recovery.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/adapter/doctor.py`
---
title: "런타임 유닛"
description: "Bootstrap, Context Resolver, Workspace Runtime, Worker Scheduler, Approval Manager, Recovery, Succession, Lineage, Adapter Layer의 구현 상태와 경계를 정리합니다."
---
`local-mogui-ade-orchestrator`의 런타임은 `src/master_runtime/core/` 아래 Python 모듈과 `scripts/` CLI 래퍼로 구현된다. 설치 후 운영 규칙과 역할 상태는 `local-master-ops`의 문서 템플릿에 남고, 실제 판단은 bootstrap, resolver, ledger, dispatch gate, approval registry, recovery, succession, lineage, adapter 모듈이 각자 맡은 범위에서 수행한다.
## 구현 상태 표
| 유닛 | 현재 표면 | 상태 | 경계 |
| --- | --- | --- | --- |
| Bootstrap | `local-mogui-ade-orchestrator:src/master_runtime/core/bootstrap.py`, `scripts/master-bootstrap` | `Observed` | charter와 선택 handoff를 읽고 L0/L1 예산, Role State, 중복 세션 경고를 산출한다. |
| Context Resolver | `context/resolver.py`, `context/manifest.py`, `context/descriptor.py` | `Observed` | manifest 선언, workspace 직계 하위 디렉터리, 요청 path 조상만 관찰한다. 임의 하위 트리 재귀 탐색은 비목표다. |
| Workspace Runtime | `work_ledger.py` | `Observed` | JSONL work ledger를 replay해 active track 캐시를 만든다. 트랙 상태 저장소이지 worker 실행기가 아니다. |
| Repository Runtime Loader | 공개 모듈 없음 | `Intended` | 개념상 저장소별 harness 로딩 자리만 있다. 현재 구현 claims로 문서화하지 않는다. |
| Worker Scheduler | `dispatch_gate.py`, `scripts/dispatch-gate`, `worker_reap.py` | `Partial` | gate는 dispatch 전후를 bracket하고 ledger/ticket을 남긴다. 실제 worker launch와 Orca pane 생성은 host/runtime 쪽 경계다. |
| Approval Manager | `approval/gates.py`, `approval/registry.py` | `Observed` | action risk를 gate class로 분류하고 승인된 proposal과 정확히 일치하는 실행만 통과시킨다. registry는 in-memory다. |
| Recovery | `recovery.py`, `scripts/master-recover` | `Observed` | charter, handoff, ledger, git 상태, monitor process를 read-only로 점검하고 successor checklist를 만든다. |
| Succession | `succession.py`, `scripts/master-succeed` | `Observed` | trigger 감지, thin handoff 생성, successor 검증, duplicate 감지, predecessor retire/spawn을 Orca terminal 표면으로 수행한다. |
| Lineage | `lineage.py` | `Observed` | append-only Markdown ledger를 검증해 추가한다. 런타임 의사결정 입력으로 쓰지 않는다. |
| Adapter Layer | `adapter/doctor.py`, `scripts/adapter doctor` | `Observed` | `git`, `node`, `orca status --json`, `bd --version` 같은 설치 표면을 측정한다. 제품별 adapter 실행 추상화는 현재 doctor 중심이다. |
상태 라벨은 구현 claim의 강도를 나타낸다. `Configured`는 파일이나 설정이 있다는 뜻이고, `Observed`는 코드 또는 테스트 가능한 실행 표면이 있다는 뜻이다. `Partial`과 `Intended`는 구현과 운영 규칙을 분리해서 읽어야 한다.
## Bootstrap
Bootstrap은 master session이 시작될 때 durable context를 작은 결과 객체로 줄인다.
```bash
local-mogui-ade-orchestrator/scripts/master-bootstrap \
--charter local-master-ops/docs/MASTER-OPERATIONS.md \
--handoff ./handoffs/latest.md \
--budget 24000 \
--session-id \
--json
```
입력은 `BootstrapConfig`다.
필수 charter 파일이다. 없으면 `BootstrapError`가 발생한다.
존재하면 L1 입력으로 읽고 `Role State` block을 파싱한다. 없으면 `HANDOFF_MISSING` warning만 남긴다.
기본값은 `24000`이다. L0부터 채우고 남은 예산에 L1을 넣는다.
주어지면 process list에서 같은 session id를 가진 다른 `claude` process를 찾아 `DUAL_INSTANCE:` warning을 낸다.
중복 instance warning이 있으면 warning 대신 `BootstrapError`로 실패한다.
출력은 `BootstrapResult`이며 `role_state`, `l0_text`, `l1_text`, `budget_used`, `warnings`를 포함한다. Role State는 `Current Role`, `Role Lock`, `Frozen`, `Unlock` 필드를 요구하고, role 값은 runtime의 허용 role 집합에 있어야 한다.
`local-master-ops:docs/runbooks/role-state.md`는 설치 후 운영 저장소의 role-state SSOT다. bootstrap은 이 문서를 직접 강제하는 정책 엔진이 아니라 handoff나 지정 파일에서 role-state 형식을 회수하는 로더다.
## Context Resolver
Context Resolver는 workspace manifest와 실제 filesystem marker를 결합해 `ContextDescriptor`를 반환한다.
```python
resolve(path, workspace_manifest) -> ContextDescriptor
```
반환 가능한 `kind`는 다음 값이다.
| `ContextKind` | 의미 |
| --- | --- |
| `folder` | Git marker가 없는 일반 폴더 |
| `git-repo` | `.git` 디렉터리가 있는 repository |
| `git-worktree` | `gitdir:` marker 파일을 가진 worktree |
| `multi-repo-workspace` | 요청 path가 workspace root이고 repository marker가 없는 multi-repo workspace |
| `nested-repo` | 관찰된 repository가 다른 repository 안에 들어간 상태 |
Resolver는 세 종류의 repository entry를 구분한다.
| `RepoStatus` | 조건 |
| --- | --- |
| `declared+observed` | manifest 선언 path가 disk에서 Git repository 또는 worktree로 확인됨 |
| `declared-missing` | manifest에는 있으나 disk marker가 없음 |
| `observed-undeclared` | workspace 직계 child 또는 요청 path 조상에서 관찰됐지만 manifest에는 없음 |
충돌 규칙은 fail-closed에 가깝다. 서로 다른 identity가 같은 정규화 path로 선언되면 `ManifestError`가 발생한다. 반대로 누락 repository와 undeclared repository는 exception이 아니라 descriptor warning으로 유지된다.
## Workspace Runtime과 ledger
Workspace Runtime은 long-lived process state를 직접 저장하지 않는다. `JsonlWorkLedger`가 append-only JSONL event를 읽고 replay한 상태를 `WorkspaceRuntime`이 session L1 cache로 보관한다.
| Event | 필수 필드 | 효과 |
| --- | --- | --- |
| `register` | `ts`, `track_id`, `title`, `refs` | 새 `TrackState` 생성 |
| `update` | `ts`, `track_id`, `status`, `note` | active track 상태와 note 갱신 |
| `close` | `ts`, `track_id`, `resolution` | status를 `CLOSED`로 바꾸고 active set에서 제외 |
잘못된 JSONL line, unknown event, unknown track update/close는 replay warning으로 남기고 건너뛴다. `WorkspaceRuntime.refresh()`는 ledger를 다시 읽어 active cache를 맞춘다.
## Worker Scheduler 경계
Worker Scheduler의 구현 표면은 dispatch 자체가 아니라 dispatch gate다. `DispatchGate.check()`는 계약 파일, runtime 이름, model, estimated chars, agent 수, completion channel, tier policy를 평가하고 JSONL ledger와 dispatch ticket을 남긴다.
```bash
local-mogui-ade-orchestrator/scripts/dispatch-gate check \
--runtime codex \
--model gpt-5.6-sol \
--contract ./contracts/example.md \
--agents 1 \
--completion-channel orchestration
```
주요 deny reason은 `CONTRACT_UNREADABLE`, `INVALID_REQUEST`, `TIER_POLICY_UNAVAILABLE`, `TIER_FANOUT_CAP`, `BUDGET_EXCEEDED`, `ROUTING_VIOLATION`, `NO_COMPLETION_CHANNEL`, `NO_MODEL`이다. 허용된 dispatch는 contract SHA 기반 ticket을 발행하고, register 단계는 job id가 독립 probe 결과에 실제로 포함될 때만 통과한다.
```bash
local-mogui-ade-orchestrator/scripts/dispatch-gate register \
--job-id \
--probe-cmd "cat ./worker-result.json" \
--contract-sha \
--runtime codex \
--orchestration-task
```
현재 gate는 worker 실행 전후의 검문과 기록을 담당한다. Orca terminal 생성, CLI agent 실행, worktree 배치 자체를 모두 이 모듈이 소유한다고 해석하면 안 된다.
## Approval Manager
Approval Manager는 두 층이다.
| 층 | 구현 | 동작 |
| --- | --- | --- |
| 분류 | `classify(ActionSpec)` | `read_only`, `writes_local`, `writes_shared`, `irreversible` 조합을 `G0`부터 `G3`까지 분류 |
| 집행 | `ProposalRegistry.guard()` | `G0_READ_ONLY` 외 action은 approved proposal이 필요하고, proposal의 action spec이 실행 action과 정확히 같아야 함 |
`G2_SHARED_STATE`와 `G3_IRREVERSIBLE`의 승인 authority는 `HUMAN`이어야 한다. 승인된 proposal은 guard 통과 후 `CONSUMED`가 되어 재사용되지 않는다. registry는 durable store가 아니라 deterministic in-memory registry이므로, 운영 감사 기록은 별도 ledger나 문서 표면에 남겨야 한다.
## Recovery
Recovery는 read-only Flow 0-6 executor다.
```bash
local-mogui-ade-orchestrator/scripts/master-recover \
--charter local-master-ops/docs/MASTER-OPERATIONS.md \
--handoff ./handoffs/latest.md \
--ledger ./.work-ledger.jsonl \
--repo ./local-mogui-ade-orchestrator \
--monitor-pattern l1-digest \
--session-id \
--json
```
| Step | 검사 |
| --- | --- |
| `0` | charter 존재, bootstrap 가능 여부, Role State 회수, duplicate instance warning |
| `1` | handoff 존재, Role State block/body 존재 |
| `1-ledger` | ledger path가 있으면 active tracks replay |
| `2-3` | 지정 repository의 `git rev-parse`, branch, dirty 상태 |
| `4` | 누락 정보 요약과 Trace Archive 수동 검색 action |
| `5` | monitor process pattern 관찰과 takeover 후 re-arm action |
| `6` | successor가 active tracks를 recite하고 predecessor PID command line을 비교하라는 checklist |
Step 0이 `MISS`면 이후 repo/monitor 검사는 skip되고 fail-closed recovery report가 생성된다. Recovery는 파일을 수정하거나 process를 종료하지 않는다.
## Succession
Succession은 자동 교체가 아니라 명시적 전환 절차다. `detect_trigger()`는 explicit instruction만 `IMMEDIATE`로 분류하고, context ratio나 milestone은 `ADVISORY`로만 반환한다.
```bash
local-mogui-ade-orchestrator/scripts/master-succeed detect \
"succession now" \
--context-ratio 0.65 \
--json
```
주요 subcommand는 다음과 같다.
| Command | 역할 |
| --- | --- |
| `detect` | trigger text와 context pressure 분류 |
| `handoff` | JSON spec에서 Role State, objective, active tracks, accepted artifacts를 포함한 thin handoff 생성 |
| `verify-successor` | recovery report의 `MISS`, step `6`, step `2-3`, step `5`를 보고 `PASS`, `PARTIAL`, `FAILED` 산출 |
| `check-duplicates` | Orca terminal list에서 같은 marker를 가진 master session 탐지 |
| `spawn` | Orca terminal을 만들고 반환 handle/worktree 배치를 검증 |
| `retire` | predecessor 후보를 정확히 하나로 좁히고, `--execute`가 있을 때만 close 후 disappearance를 재측정 |
`spawn`은 agent별 기본 model을 일부만 가진다. unknown agent에 `--model`이 없으면 실패한다. 이는 provider-neutral 경계다. runtime은 특정 모델 공급자를 가정하지 않고, CLI 이름과 측정된 model id를 입력값으로 취급한다.
## Lineage
Lineage는 succession 결과의 append-only 관측 기록이다. `append_entry(path, entry)`는 required field, integer count, text field, verification value를 검증하고 Markdown section을 파일 끝에만 추가한다. 같은 generation이 이미 있으면 거부하고, append 검증 실패나 validation 실패 시 기존 bytes를 복원한다.
필수 필드는 `generation`, `parent_session`, `successor_session`, `timestamp`, `inherited_role`, `succession_reason`, `recovery_sources`, `inherited_open_tracks`, `verification`, `repeated_question_count`, `reopened_decision_count`, `context_loss_summary`, `predecessor_retirement_verified`이다. `verification` 값은 `PASS`, `PARTIAL`, `FAILED` 중 하나다.
Lineage는 bootstrap source가 아니며 runtime decision에도 쓰이지 않는다. 다음 generation의 실제 상태는 bootstrap, recovery, ledger, host 관찰 결과로 다시 확인한다.
## Adapter Layer
현재 Adapter Layer의 공개 CLI는 `adapter doctor`다.
```bash
local-mogui-ade-orchestrator/scripts/adapter doctor
```
기본 check는 `git --version`, `node --version`, `orca status --json`, `bd --version`이다. `orca --version`을 쓰지 않는 이유는 host별로 usage banner나 GUI launch처럼 측정 의미가 다른 결과가 나올 수 있기 때문이다. doctor 결과는 `present`, `missing`, 개별 `detail`을 JSON으로 출력한다.
이 계층은 BYOC/BYOK 친화적으로 유지된다. 특정 hosted connector나 모델 공급자에 runtime을 묶지 않고, 설치된 로컬 CLI, 파일, repository 설정, catalog/skill source를 측정 가능한 입력으로 취급한다.
## 운영 저장소와 제품 저장소 경계
`local-master-ops`는 설치 후 생성되는 operations repository template이다. `docs/MASTER-OPERATIONS.md`는 charter section map과 change rule을 보관하고, `docs/runbooks/role-state.md`는 role lock과 allowed roles를 보관한다. 반면 runtime code와 CLI 구현은 `local-mogui-ade-orchestrator`에 있다.
```text
local-master-ops
docs/MASTER-OPERATIONS.md 운영 SSOT와 charter map
docs/runbooks/role-state.md role-state 운영 파일
local-mogui-ade-orchestrator
src/master_runtime/core/ 런타임 모듈
scripts/ 공개 CLI entrypoint
config/*.example.json 설치 instance 설정 예시
tests/ 구현 경계 회귀 테스트
```
## 설정 표면
| 파일 | 런타임에서 쓰는 의미 |
| --- | --- |
| `config/instance-runtime.example.json` | master host runtime, transcript glob, optional product repo 예시 |
| `config/workspace-descriptor.example.json` | workspace root, master seat, repository inventory, repository별 prohibited action 예시 |
| `config/model-tier-policy.example.json` | dispatch gate가 소비하는 instance-owned tier policy 예시 |
`dispatch_gate.py`의 tier policy resolution은 환경 변수 `DISPATCH_TIER_POLICY`를 먼저 보고, 그다음 `config/model-tier-policy.json`, 마지막으로 `master-ops/model-tier-policy.json` fallback을 본다. 예시 파일은 template이며, 채워진 instance policy를 commit하는 규칙은 별도 운영 정책의 영역이다.
## Related pages
ops 저장소, 제품 저장소, sibling checkout 모델의 경계를 확인합니다.
dispatch gate, contract, register probe, acceptance 전 재검증 흐름을 확인합니다.
trigger, handoff, successor verify, predecessor retirement, lineage append 순서를 확인합니다.
instance runtime, workspace descriptor, model tier policy의 필드와 fail-closed 동작을 확인합니다.
---
## 08. 증거 라벨
> Configured, Intended, Observed, Unknown 라벨과 테스트, 로그, ledger, self-report의 증거 강도를 운영 문서 규칙으로 정리합니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/08-page-8.md
- Generated: 2026-08-10T07:37:48.048Z
### Source Files
- `local-mogui-ade-orchestrator:docs/public/concepts.md`
- `local-mogui-ade-orchestrator:docs/public/defense-inventory.md`
- `local-master-ops:docs/runbooks/error-and-logging.md`
- `local-master-ops:docs/observability/README.md`
- `local-master-ops:docs/blame/BLAME-2026-08-04-status-blind-reporting.md`
---
title: "증거 라벨"
description: "Configured, Intended, Observed, Unknown 라벨과 테스트, 로그, ledger, self-report의 증거 강도를 운영 문서 규칙으로 정리합니다."
---
공개 문서의 구현 상태는 `Configured`, `Intended`, `Observed`, `Unknown` 네 라벨로만 표시한다. 운영 저장소는 이 라벨을 `scripts/measure`, `dispatch-gate` JSONL ledger, `hook-fire-log.jsonl`, `event-log.jsonl`, blame/retro/travelog 기록에 적용하며, 에이전트 self-report만으로는 동작을 `Observed`로 승격하지 않는다.
## 라벨 기준
| 라벨 | 의미 | 허용되는 문장 |
| --- | --- | --- |
| `Configured` | 파일, 스크립트, hook, 설정, 정적 contract가 존재한다. | "`scripts/hooks/.sh`가 있다", "`model-tier-policy.json`이 설정되어 있다" |
| `Intended` | 설계 계약이나 운영 규칙은 문서화되어 있지만 현재 문서가 live runtime 증거를 주장하지 않는다. | "민감 lane은 dedicated session으로 라우팅해야 한다" |
| `Observed` | git 상태, 로컬 실행, 로그, ledger, 프로세스 상태, probe가 self-report 밖에서 동작을 보였다. | "`check`가 `TIER_FANOUT_CAP`으로 deny했고 ledger에 기록됐다" |
| `Unknown` | 현재 증거가 동작을 증명하지 못하거나 public surface 밖에 있다. | "모든 worker 생성 경로가 gate를 통과하는지는 이 저장소만으로 알 수 없다" |
`Configured`는 작동 증거가 아니다. hook 파일이나 descriptor가 있어도 실제 세션에서 fire 되었는지, 모든 경로가 그 hook을 통과했는지는 별도 측정이 필요하다.
## 증거 강도
| 증거 | 기본 강도 | 라벨 판정 규칙 | 한계 |
| --- | --- | --- | --- |
| 로컬 테스트 | 중간 | 테스트 대상 unit에는 `Observed`를 줄 수 있다. | 운영 workspace가 그 unit을 실제 경로에 연결했다는 증거는 아니다. |
| `scripts/measure` 출력 | 높음 | 첫 줄 `exit=`와 출력 본문을 함께 기록한 command 실행은 `Observed` 근거가 된다. | 명령이 질문에 맞는 instrument인지 별도 확인해야 한다. |
| Dispatch ledger | 높음 | `decision`, `reason`, `contract_sha`, `tier_policy_path`, `tier_policy_sha256`, model 검증 필드는 gate 판정의 `Observed` 근거다. | ledger append 실패나 우회 실행은 ledger 밖 행동을 증명하지 못한다. |
| Hook fire log | 중간 | hook이 특정 runtime/session kind에서 실행됐다는 근거다. | decision logic이 맞았는지는 증명하지 않는다. zero entry는 고장 증거가 아니라 측정 대상이다. |
| Event log | 중간 | `outcome`, `evidence`, `reason`, `command_class`, `target_scope`가 decision event를 구조화한다. | fail-open 로그이므로 append 성공 여부가 guard 판정을 바꾸지 않는다. raw command나 절대 경로는 기록하지 않는다. |
| Blame/retro/travelog | 보조 | 관측 공백, 판단, 실행 흔적을 분리해 사후 감사에 쓴다. | interpretive record다. primary artifact와 충돌하면 artifact가 우선한다. |
| Agent self-report | 낮음 | 독립 probe, 로그, ledger, artifact와 맞을 때만 보조 근거로 쓴다. | 단독으로 `Observed`를 만들 수 없다. |
## 명령 출력 규칙
명령 결과를 사실로 보고할 때는 `scripts/measure` 형태가 기본이다.
```bash
scripts/measure git ls-remote --heads origin
```
유효한 측정은 첫 줄에 종료 코드를 둔다.
```text
exit=0
```
빈 출력도 상태와 함께 읽는다.
```text
exit=1
(no output)
```
```text
exit=0
(no output)
```
두 출력은 같은 뜻이 아니다. 실패한 명령의 빈 출력은 "대상 없음"이 아니라 "측정 실패"다. 종료 코드를 보지 못했거나 명령이 필요한 질문과 다른 것을 측정했다면 `Unknown`으로 보고한다.
## Ledger 판정 규칙
`dispatch-gate check`는 dispatch 전 contract, runtime, model, fan-out, estimated input size, completion channel, tier policy를 판정한다. 기록되는 decision은 append-only JSONL이다.
주요 필드:
| 필드 | 의미 |
| --- | --- |
| `decision` | `ALLOW` 또는 `DENY` |
| `reason` | `OK`, `NO_MODEL`, `CONTRACT_UNREADABLE`, `TIER_POLICY_UNAVAILABLE`, `TIER_FANOUT_CAP` 같은 안정 reason code |
| `contract_sha` | dispatch contract 내용 hash |
| `completion_channel` | `orchestration` 또는 `sentinel-log` |
| `model` | check 시점의 declared model |
| `tier` | tier policy가 계산한 model tier |
| `tier_policy_path` | 판정에 사용한 policy 경로 |
| `tier_policy_sha256` | 판정에 사용한 policy 내용 digest |
| `warnings` | deny는 아니지만 조용히 통과시키면 안 되는 상태 |
`register`는 worker가 생긴 뒤 job id를 독립 probe로 확인하고 model 증거를 추가한다.
| 필드 | 의미 |
| --- | --- |
| `job_id` | 등록 대상 worker/job 식별자 |
| `model_declared` | dispatch 시 선언한 model |
| `model_measured` | transcript probe 등으로 측정한 model |
| `model_verified` | declared와 measured가 모두 있고 probe 실패가 없을 때 `true` |
| `warnings` | `MODEL_UNVERIFIED`, `MODEL_PROBE_FAILED`, `MODEL_MISMATCH` 등 |
`MODEL_UNVERIFIED`와 `MODEL_PROBE_FAILED`는 조용한 성공이 아니다. 일부 runtime에서 model 보고가 불가능하면 register는 계속될 수 있지만, 문서에서는 해당 model 실행을 `Observed`로 쓰지 않는다.
## 로그 판정 규칙
`~/.mogui/hook-fire-log.jsonl`과 `~/.mogui/event-log.jsonl`은 다른 질문에 답한다.
| 로그 | 답하는 질문 | 대표 필드 |
| --- | --- | --- |
| `hook-fire-log.jsonl` | hook이 언제, 어디서, 어떤 runtime/session kind에서 fire 되었는가 | `ts`, `hook`, `event`, `cwd`, `runtime_hint`, `session_kind` |
| `event-log.jsonl` | guard나 decision emitter가 어떤 분류와 결과를 냈는가 | `ts`, `level`, `event`, `component`, `outcome`, `evidence`, `reason`, `command_class`, `target_scope`, `tool_kind` |
`event-log`는 값 없는 metadata만 기록한다. raw command, credential, absolute path는 기록하지 않고 command name이나 target classification만 남긴다. 로그 append 실패는 guard decision을 바꾸면 안 된다.
## Self-report 처리
Worker나 master의 완료 보고는 acceptance 입력일 뿐이다. 문서화할 때는 다음 순서로 판정한다.
"worker가 완료했다", "model X로 실행했다", "테스트가 통과했다", "PR이 merge 가능하다"를 한 문장으로 묶지 않는다.
테스트 claim은 test output, dispatch claim은 ledger, hook claim은 fire log, model claim은 transcript probe, filesystem claim은 git/process/path 측정으로 확인한다.
artifact가 없거나 instrument가 다른 질문에 답하면 `Unknown`이다. 운영 규칙만 있으면 `Intended`, 파일만 있으면 `Configured`다.
서로 다른 시점의 측정을 비교해 원인을 쓰지 않는다. 같은 턴 또는 명시된 timestamp로 재측정하기 전에는 "차이 있음"까지만 기록한다.
## 문서 작성 규칙
운영 문서에서 claim을 쓸 때는 가장 강한 라벨 하나만 붙인다. 문장 안에서 라벨을 섞어야 하면 claim을 분리한다.
| 잘못된 문장 | 수정 |
| --- | --- |
| "dispatch gate가 모든 worker 생성을 막는다." | "`dispatch-gate check/register`와 JSONL ledger는 구현되어 있고 테스트된다. 모든 workspace worker 생성 경로가 이를 통과하는지는 workspace wiring 증거가 필요하다." |
| "hook이 설치되어 있으므로 보호가 활성이다." | "hook 파일은 `Configured`다. fire log entry가 있으면 해당 session kind에서 fire 된 것은 `Observed`다." |
| "테스트가 통과했으므로 운영에서 동작한다." | "테스트 대상 unit은 local execution에서 `Observed`다. 운영 라우팅은 별도 증거가 필요하다." |
| "worker가 완료했다고 했으므로 완료다." | "worker self-report를 받았다. acceptance artifact 또는 completion channel probe 전까지 완료 여부는 `Unknown`이다." |
## 실패 시 표현
`exit 2`, undecidable probe, malformed log, missing transcript, unreadable policy는 실패가 아니라 "판정 불가"일 수 있다. 이 경우 초록불로 쓰지 않는다.
권장 표현:
```text
model probe: undecidable
label: Unknown
reason: transcript substrate unavailable; no measured model
next check: rerun with scoped transcript glob or record MODEL_PROBE_FAILED in dispatch ledger
```
```text
redaction scan: exit=2
label: Unknown
reason: required organization rules missing
next check: provide REDACTION_EXTRA_PATTERNS or remove the release claim
```
## Related pages
gate, ledger, model probe, redaction scan의 방어 표면과 failure mode를 확인한다.
`dispatch-gate check`, worker dispatch, `register`, completion evidence 흐름을 확인한다.
declared model과 measured model을 분리하고 undecidable 상태를 처리한다.
undecidable, unverified, missing hook entry, redaction cannot decide 상태를 증상별로 처리한다.
---
## 09. 워크스페이스 Founding
> workspace root 선택, ops 저장소 생성, seat 기록, placeholder 치환, tracker 연결, Gen-1 spawn, boot smoke 검증 절차를 다룹니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/09-founding.md
- Generated: 2026-08-10T07:39:40.069Z
### Source Files
- `local-master-ops:ONBOARDING.md`
- `local-master-ops:onboarding/02-workspace-facts.md`
- `local-master-ops:onboarding/03-ops-repo.md`
- `local-master-ops:onboarding/04-seat.md`
- `local-master-ops:onboarding/05-placeholders.md`
- `local-master-ops:onboarding/09-spawn.md`
- `local-master-ops:onboarding/10-card-and-retire.md`
---
title: "워크스페이스 Founding"
description: "workspace root 선택, ops 저장소 생성, seat 기록, placeholder 치환, tracker 연결, Gen-1 spawn, boot smoke 검증 절차를 다룹니다."
---
Founding은 새 workspace에 `master-ops` 템플릿을 설치하고, Orca folder workspace seat에 Generation 1 master를 정확히 하나 생성한 뒤, boot smoke와 운영 카드 전달까지 완료하는 온보딩 경로다. 이미 ops 저장소나 lineage가 있는 workspace는 Founding 대상이 아니며, 재검증은 Reverify, 템플릿 갱신은 Upgrade, 죽은 master 복구는 ops 저장소의 succession boot card로 라우팅한다.
## 진입 조건
| 조건 | Founding 처리 |
| --- | --- |
| 새 workspace | `onboarding/00`부터 `10`까지 순서대로 진행 |
| ops 저장소 존재 | Founding 중단, Upgrade 또는 succession 경로로 전환 |
| master가 이미 존재 | Founding 중단, Reverify 또는 succession 경로로 전환 |
| 템플릿 자체 수정 | 온보딩이 아니라 일반 개발 작업으로 처리 |
Founding은 중복 master를 만들면 안 된다. 기존 ops tree, lineage, half-finished Gen-1 boot 흔적이 있으면 새 세션을 만들지 말고 현재 상태를 먼저 분류한다.
## 생성되는 주요 표면
| 표면 | 위치 | 성격 |
| --- | --- | --- |
| ops 저장소 | `{{OPS_REPO}}` | governance, runbook, tracker, dispatch contract 보관소 |
| workspace descriptor | `{{RUNTIME_ROOT}}/config/workspace-descriptor.json` | workspace inventory와 guard 입력 |
| instance runtime config | `{{RUNTIME_ROOT}}/config/instance-runtime.json` | master host runtime, transcript glob, product repo |
| workspace session card | `{{OPS_REPO}}/workspace-card/{CLAUDE.md,AGENTS.md}` | workspace root에 배포되는 canonical card |
| root session card | `{{WORKSPACE_ROOT}}/{CLAUDE.md,AGENTS.md}` | agent host가 읽는 배포본 |
| lineage | `{{OPS_REPO}}/docs/lineage/MASTER-LINEAGE.md` | Gen-1 boot smoke 후 master가 append |
| role state | `{{OPS_REPO}}/docs/runbooks/role-state.md` | Gen-1 active role과 Role Lock 기록 |
| tracker | `{{OPS_REPO}}/.beads` | 실행 상태 저장소, workspace root에서 resolve되어야 함 |
## Founding 절차
workspace root는 사용자가 고른 절대 경로여야 한다. 에이전트는 후보를 스캔해 추천하지 않고, 전달받은 경로가 absolute path이며 directory인지 검증한다.
```console
$ test "${WORKSPACE_ROOT#/}" != "$WORKSPACE_ROOT" && test -d "$WORKSPACE_ROOT"
$ ls -la "$WORKSPACE_ROOT"
```
확정 후 immediate child Git repository를 측정해 `{{REPO_LIST}}` 기본값으로 삼는다. workspace 밖의 저장소는 먼저 root 아래로 이동하거나 clone하도록 안내하고, 거부된 경우에만 external lane으로 기록한다.
`config/workspace-descriptor.json`은 template example에서 복사한 instance-owned 파일이다. `workspace_root_is_plain_folder`는 항상 `true`이며, `repositories`에는 측정된 member repository가 들어간다.
```json
{
"workspace_root_is_plain_folder": true,
"workspace_root": "/absolute/path/to/workspace-root",
"master_seat": "id:folder:",
"repositories": [
{
"name": "product-app",
"path": "product-app",
"remote": "https://example.invalid/product-app.git",
"role": "product",
"capabilities": ["pr", "dispatch-target"],
"prohibited": ["direct-main-commit", "force-push"]
}
]
}
```
`config/instance-runtime.json`은 `master_host_runtime`, 측정 가능한 경우 `transcript_globs`, 단일 primary product가 owner-confirmed인 경우 `product_repo`를 갖는다. 값이 없으면 기본 추정값을 만들지 않고 unconfigured 상태로 남긴다.
ops repository 이름은 product repository와 혼동되지 않아야 하며, 보통 `-ops`가 기본 후보가 된다. 새 저장소이거나 비어 있으면 `{{RUNTIME_ROOT}}/master-ops/MANIFEST.json`에 등재된 Stage 1 skeleton만 복사한다.
설치된 ops 저장소에는 `MANIFEST.json`, `CLAUDE.md`, `AGENTS.md`, `docs/MASTER-OPERATIONS.md`, `workspace-card/`, runbook, script가 포함된다. `TEMPLATE-VERSION`, `CHANGELOG.md`, `ONBOARDING.md`, `onboarding/`은 template side에 남는다.
ops repository를 Orca에 등록하고, 사용자가 workspace root의 folder workspace에서 임시 terminal을 열게 한 뒤 `terminal show`로 seat metadata를 측정한다.
```console
$ ORCA repo add --path "{{OPS_REPO}}" --json
$ ORCA terminal show --terminal --json
```
durable seat는 terminal handle이 아니라 `id:folder:` 형식 selector다. folder workspace는 `worktreeId`가 `folder:`이고 `worktreePath`가 비어 있는 형태로 보일 수 있다. 기록할 때는 모든 consumer가 받는 `id:` prefixed form을 사용한다. 임시 seat-check terminal은 spawn 전에 닫혀 있어야 한다.
허용 placeholder는 다음 8개뿐이다: `{{WORKSPACE_NAME}}`, `{{WORKSPACE_ROOT}}`, `{{OPS_REPO}}`, `{{MONITOR_NS}}`, `{{MODEL_ID}}`, `{{REPO_LIST}}`, `{{RUNTIME_ROOT}}`, `{{TEMPLATE_VERSION}}`.
모든 `{{...}}` token은 이 단계에서 confirmed 또는 measured 값으로 치환한다. deferral list는 없다.
```console
$ cp "{{OPS_REPO}}/workspace-card/CLAUDE.md" "{{WORKSPACE_ROOT}}/CLAUDE.md" \
&& cp "{{OPS_REPO}}/workspace-card/AGENTS.md" "{{WORKSPACE_ROOT}}/AGENTS.md" \
&& echo deployed
deployed
```
검증은 세 가지다: ops 저장소 전체에 placeholder가 없어야 하고, ops root의 `CLAUDE.md`와 `AGENTS.md`가 byte-identical이어야 하며, `workspace-card` canonical pair와 workspace root 배포본이 각각 일치해야 한다.
지원 tracker는 Beads다. owner 승인 후 ops repository에서 초기화하고, workspace root의 `.beads`가 ops repository의 `.beads`를 가리키게 한다.
```console
$ cd "{{OPS_REPO}}" && bd init --prefix
$ { [ -e "{{WORKSPACE_ROOT}}/.beads" ] || [ -L "{{WORKSPACE_ROOT}}/.beads" ]; } \
&& echo "already exists, inspect before linking" \
|| ln -s "$(cd "{{OPS_REPO}}" && pwd)/.beads" "{{WORKSPACE_ROOT}}/.beads"
$ cd "{{WORKSPACE_ROOT}}" && bd where
```
`bd where`는 workspace root에서 ops repository로 resolve되어야 한다. 상위 directory나 product repository의 tracker DB가 선택되면 pass가 아니다.
spawn 전 durable selector로 `ORCA terminal list --worktree --json`를 실행해 seat가 비어 있는지 확인한다. 하나라도 terminal이 있으면 hard stop이다.
spawn은 Orca orchestration을 통해서만 진행한다. raw terminal polling이나 vendor-direct CLI dispatch는 compliant path가 아니다.
```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
```
`dispatch-gate check`가 `allow: true`를 반환해야 spawn 또는 worker attach를 진행한다. `master-succeed spawn`은 created terminal의 `worktreeId`와 expected placement를 비교하고, mismatch 시 fail-closed한다.
boot smoke는 새 master session 안에서 실행된다. master는 Role State를 선언하고, model identity를 measured/unavailable/unsupported 중 하나로 보고하며, placement evidence를 남기고, Generation 1을 lineage에 append한 뒤 `worker_done`을 한 번만 보낸다.
마지막 단계에서 installer는 owner에게 operating card를 출력한다. 이후 newborn master가 Step 8에서 받은 kill switch로 installer terminal을 닫고, pane/process/tty disappearance를 가능한 범위에서 재확인한다. master terminal은 계속 실행 상태로 남는다.
## 검증 신호
| 단계 | pass 신호 |
| --- | --- |
| workspace root | owner-provided absolute directory, measured repository inventory |
| descriptor | `workspace_root_is_plain_folder: true`, repository별 `role`, `capabilities`, `prohibited` 존재 |
| ops skeleton | `MANIFEST.json` 존재, template version 일치, required files 존재 |
| seat | durable selector가 `id:folder:` form, 임시 terminal 닫힘 |
| placeholder | `rg '\{\{[^}]+\}\}' "{{OPS_REPO}}"` 결과 없음 |
| card | ops pair, workspace-card pair, root 배포본이 각각 byte-identical |
| tracker | workspace root에서 `bd where`가 ops repository로 resolve |
| spawn | seat empty, exactly one new master, placement `MATCH` 또는 valid `MATCH_REISSUED` |
| boot smoke | Role Lock enabled, lineage append, placement evidence, `worker_done` |
## 실패 처리
Founding 실패는 “대체 경로로 계속 진행”하지 않는다. 특히 seat selector가 실패할 때 filesystem path나 `path:` selector로 바꾸지 않는다. spawn 중 실패하면 같은 installer에서 master를 대신 boot하지 않고, 두 번째 session을 만들지 않는다.
이미 founded된 workspace에서 문제가 발견되면 Founding을 반복하지 않는다. template drift는 Upgrade로, 살아 있는 master 건강 확인은 Reverify로, master 부재 또는 half-finished boot는 `docs/runbooks/succession-boot-card.md`로 보낸다.
## Provider-neutral boundary
Founding의 source of truth는 repository files, local CLI, Orca object metadata, Beads tracker, JSON config다. skill pack이나 agent runtime은 실행 표면을 제공할 수 있지만, workspace inventory, placeholder allowlist, seat selector, tracker resolution, spawn verification은 특정 model provider나 hosted connector에 묶이지 않는다.
## Related pages
Founding, Reverify, Upgrade, Template improve의 진입 조건과 금지 경로를 구분한다.
ops 저장소, 제품 저장소, sibling checkout 모델의 경계를 확인한다.
Project, workspace, worktree, terminal, selector 형식을 확인한다.
Founding 이후 worker dispatch와 acceptance 전 재검증 흐름을 연결한다.
---
## 10. 작업자 위임
> contract 파일, `dispatch-gate check`, Orca task-create와 dispatch, register probe, completion channel, acceptance 전 재검증 흐름을 설명합니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/10-page-10.md
- Generated: 2026-08-10T07:39:44.788Z
### Source Files
- `local-mogui-ade-orchestrator:docs/public/delegation-and-review.md`
- `local-mogui-ade-orchestrator:src/master_runtime/core/dispatch_gate.py`
- `local-mogui-ade-orchestrator:scripts/dispatch-gate`
- `local-master-ops:scripts/dispatch`
- `local-master-ops:docs/charter/05-dispatch-gate.md`
- `local-mogui-ade-orchestrator:tests/test_dispatch_gate.py`
---
title: "작업자 위임"
description: "contract 파일, `dispatch-gate check`, Orca task-create와 dispatch, register probe, completion channel, acceptance 전 재검증 흐름을 설명합니다."
---
작업자 위임의 구현 표면은 `local-master-ops/scripts/dispatch`와 `local-mogui-ade-orchestrator/scripts/dispatch-gate`가 나눠 가진다. `dispatch-gate`는 contract 파일을 읽어 정책 verdict와 `contract_sha`를 ledger에 남기고, `dispatch`는 그 verdict를 받은 뒤 Orca Task와 Dispatch를 만들고, 실제 Dispatch artifact가 확인된 뒤에만 `register`를 호출한다.
## 위임 경계
감독 위임은 다음 순서를 기준으로 한다.
```text
contract 작성
-> dispatch-gate check
-> orca orchestration task-create
-> orca orchestration dispatch --inject
-> dispatch-gate register
-> delivery classification
-> worker_done 수신
-> master acceptance 재검증
```
`check`는 실행 허가가 아니라 dispatch 전 정책 결정이다. `register`는 worker job id가 실제 artifact에 나타났는지 확인하는 등록 단계다. `worker_done`은 작업자 완료 주장이고, acceptance는 master가 contract와 산출물을 다시 대조한 뒤 내리는 별도 판단이다.
worker self-report는 acceptance evidence가 아니다. acceptance 전에는 diff, 테스트, 로그, deterministic probe, authoritative document 중 contract가 요구한 근거를 master가 직접 확인해야 한다.
## Contract 파일
Contract는 작업자가 추측하지 않도록 작업 범위를 고정하는 파일이다. 저장 위치는 ops 저장소의 `contracts/`가 기준이며, 위임 스크립트는 `--contract FILE`로 파일 존재 여부를 먼저 검사한다.
Contract에는 최소한 다음 사실을 명시한다.
| 항목 | 목적 |
| --- | --- |
| 대상 저장소와 checkout | worker가 들어갈 위치와 금지된 master checkout을 구분한다. |
| 허용 작업 표면 | 수정 가능한 파일, 금지 파일, 읽기 전용 자료를 구분한다. |
| acceptance criteria | 완료 보고가 아니라 acceptance 판단 기준을 고정한다. |
| required evidence | 테스트, 로그, diff, probe, 문서 확인 항목을 지정한다. |
| commit/push 규칙 | local commit, push, deploy 권한을 추측하지 않게 한다. |
| 제외 범위 | 비슷해 보이지만 이번 lease에 포함되지 않는 일을 차단한다. |
Placement evidence는 공개 보고에 절대경로를 올리지 않는 형태가 기본이다.
```text
FIRST ACTION:
- in_expected_worktree: yes|no
- is_master_checkout: yes|no
- branch: `git branch --show-current`
```
`is_master_checkout: yes`이면 worker는 즉시 중단해야 한다. 정확한 절대경로는 worker에게 내려가는 contract 안에서는 필요할 수 있지만, 완료 보고나 PR 본문 같은 공개 표면으로 올라오면 안 된다.
## `dispatch-gate check`
`check`는 contract를 읽고, 정책을 평가하고, 허용 시 dispatch ticket을 발급한다. 기본 ledger는 gate 설정의 `.dispatch-gate-ledger.jsonl`이지만, 운영 wrapper는 `~/.mogui/dispatch-ledger.jsonl`을 사용한다.
```bash
scripts/dispatch-gate \
--ledger ~/.mogui/dispatch-ledger.jsonl \
check \
--runtime codex \
--model gpt-5.6-luna \
--tier-policy ./config/model-tier-policy.json \
--contract ./contracts/job.md \
--agents 1 \
--est-chars 3000 \
--completion-channel orchestration
```
응답은 stdout의 단일 JSON 객체다. 사람용 진단은 stderr의 `dispatch-gate:` 접두 메시지로 분리된다. JSON 파서에 넘길 때는 stderr를 합치지 않는다.
```json
{"allow":true,"contract_sha":"...","cost_proxy":3000,"reason":"OK","warnings":[]}
```
### 주요 입력
작업자를 실행할 runtime 이름이다. 소문자, 숫자, `_`, `-` 패턴의 runtime만 유효하다.
선언한 worker model id다. 현재 gate는 model 누락을 `NO_MODEL`로 거부한다.
`orchestration` 또는 `sentinel-log`만 허용된다. supervised Orca dispatch는 `orchestration`을 사용한다.
현재 ledger와 정책으로 평가만 수행한다. ledger row와 dispatch ticket을 만들지 않으므로 `scripts/dispatch --check-only`에서 사용된다.
## Tier policy와 모델 검증
Tier policy 선택 순서는 명시적 `--tier-policy`, `DISPATCH_TIER_POLICY`, instance `config/model-tier-policy.json`, template `master-ops/model-tier-policy.json`이다. policy 파일을 읽을 수 없거나 malformed이면 `TIER_POLICY_UNAVAILABLE`로 fail closed 한다.
Version 2 policy는 model identity 자체보다 tier와 fan-out을 평가한다. unlisted model은 자동으로 top tier가 되지 않고 `unknown` tier로 기록되며, `unknown` tier에 cap이 있으면 그 cap을 따른다. cap 초과는 `--tier-override ""`이 없으면 `TIER_FANOUT_CAP`이다.
`local-master-ops/scripts/dispatch`는 top tier model에 대해 gate 이전에 `--top-approved ""`을 요구한다. 이 값은 인증 경계가 아니라 운영 절차 evidence로 run log에 남는 값이다.
## Orca dispatch wrapper
ops 저장소의 `scripts/dispatch`는 한 번에 supervised dispatch를 수행하는 wrapper다.
```bash
local-master-ops/scripts/dispatch \
--contract ./contracts/job.md \
--spec "작업자에게 전달할 작업 지시" \
--worktree path:/absolute/worktree \
--runtime codex \
--model gpt-5.6-luna
```
Wrapper의 실행 순서는 고정되어 있다.
`dispatch-gate check --no-record`로 dry-run을 수행한다. 여기서 거부되면 ledger budget이나 ticket을 소비하지 않고 중단한다.
실행 직전에 같은 인자로 `dispatch-gate check`를 다시 수행한다. 이 단계가 허용되어야 ledger row와 ticket이 생긴다.
`orca orchestration task-create --spec "$SPEC" --json`으로 Task id를 만든다.
`--terminal`이 없으면 `orca terminal create --worktree "$WORKTREE" --command "" --json`으로 worker terminal을 만든다.
`orca orchestration dispatch --task "$TASK" --to "$TERMINAL" --inject --json`으로 Dispatch id를 만든다.
`dispatch-gate register`가 `dispatch-show` 기반 probe와 `orchestration_task`를 확인한 뒤 ledger에 job id를 남긴다.
Wrapper는 provider-neutral한 Orca orchestration 표면을 기준으로 동작한다. Runtime별 CLI는 worker 실행 명령에만 사용되고, Task, Dispatch, completion authority는 Orca artifact와 ledger가 가진다.
## `dispatch-gate register`
`register`는 dispatch가 실제로 생성된 뒤 호출한다. `--probe-cmd`는 exit code 0이어야 하고 stdout에 `--job-id` 값을 출력해야 한다.
```bash
scripts/dispatch-gate \
--ledger ~/.mogui/dispatch-ledger.jsonl \
register \
--job-id dispatch_123 \
--contract-sha abc123abc123 \
--runtime codex \
--probe-cmd "orca orchestration dispatch-show --task task_123 --json | grep -o dispatch_123 | head -1" \
--orchestration-task task_123 \
--declared-model gpt-5.6-luna \
--model-probe-cmd "scripts/model-identity-probe --transcript ./worker.jsonl"
```
`completion_channel`이 `orchestration`이면 `--orchestration-task`가 필요하다. CLI는 해당 task에 대해 `orca orchestration dispatch-show --task --json`을 실행해 dispatch artifact를 확인한다. task가 없거나 Orca가 없거나 JSON이 파싱되지 않으면 `ORCHESTRATION_UNVERIFIED`로 거부하고 ledger에 probe failure를 남긴다.
`register`가 성공하면 ledger row에는 `job_id`, `completion_channel`, 선택적으로 `orchestration_task`, `model_declared`, `model_measured`, `model_verified`, `attempt`가 기록된다.
## Completion channel
| Channel | 의미 | Register 조건 |
| --- | --- | --- |
| `orchestration` | Orca Task와 Dispatch artifact가 completion authority다. | `--orchestration-task`를 제공하고 `dispatch-show` probe가 통과해야 한다. |
| `sentinel-log` | 별도 sentinel log를 completion channel로 둔다. | orchestration task probe를 생략할 수 있지만 `--probe-cmd`의 job id 확인은 여전히 필요하다. |
Completion channel mismatch는 `INVALID_REQUEST`다. 예를 들어 `check`가 `orchestration`으로 기록한 pending dispatch를 `sentinel-log`로 기대하며 등록하면 register는 ledger에 job row를 쓰지 않고 ticket도 유지한다.
## Delivery 확인
`register`는 dispatch artifact 등록이지 실제 지시문 소비 증거가 아니다. Wrapper는 inject 전후 terminal 상태를 읽어 delivery class를 판단한다.
| 상태 | 의미 | 처리 |
| --- | --- | --- |
| `agent-started` | prepared prompt가 inject 뒤 사라졌다. | worker가 처리를 시작한 것으로 보고 pane을 읽어 contract 진행을 확인한다. |
| `hook-trust` | trust 또는 hook gate가 보인다. | spec이 소비되지 않은 실패로 보고 재dispatch 전 gate를 해소한다. |
| `limit` | rate limit 또는 quota marker가 보인다. | spec이 소비되지 않은 실패로 보고 runtime 교체나 대기를 선택한다. |
| `unknown` | 인식 가능한 delivery evidence가 없다. | 완료로 보지 않고 `orca terminal read`로 수동 확인한다. |
Output byte 변화나 idle 상태만으로 delivery를 통과시키지 않는다. start screen과 준비된 prompt는 모두 idle로 보일 수 있기 때문이다.
## Acceptance 전 재검증
`worker_done`을 받으면 master는 바로 accept하지 않는다. 다음 순서로 contract와 산출물을 다시 연결한다.
Ledger의 `contract_sha`, `job_id`, `orchestration_task`, `attempt`를 확인해 어떤 contract 실행인지 고정한다.
Worker가 수정한 파일, branch, commit 상태가 contract의 allowed surface와 commit/push 규칙을 벗어나지 않았는지 확인한다.
Contract가 요구한 테스트, redaction scan, link check, 로그 확인, deterministic probe를 master가 직접 실행하거나 산출물을 읽는다.
`model_verified: false`, `MODEL_UNVERIFIED`, `MODEL_PROBE_FAILED`가 있으면 모델 선언은 측정 사실이 아니라 미검증 상태로 취급한다.
통과 항목, 실행하지 못한 항목, 남은 risk를 분리해 기록한다. 검증할 수 없는 결과는 아직 accepted가 아니다.
## 실패 신호
| 신호 | 원인 | 조치 |
| --- | --- | --- |
| `CONTRACT_UNREADABLE` | contract 파일을 읽을 수 없거나 `est_chars` 산정이 실패했다. | contract 경로와 권한을 고친 뒤 다시 `check`한다. |
| `NO_COMPLETION_CHANNEL` | `check` 요청에 completion channel이 없다. | `--completion-channel orchestration` 또는 `sentinel-log`를 명시한다. |
| `NO_MODEL` | worker model id가 없다. | runtime이 실행할 실제 model id를 contract와 command에 명시한다. |
| `UNVERIFIED_JOB` | `--probe-cmd`가 job id를 stdout에 출력하지 않았다. | artifact 내용을 읽는 probe로 교체한다. |
| `ORCHESTRATION_UNVERIFIED` | Orca task/dispatch artifact를 확인하지 못했다. | `--orchestration-task`와 `dispatch-show` 결과를 확인한다. |
| `MODEL_TIER_ESCALATION` | 측정된 모델이 선언 모델보다 더 엄격한 tier다. | 해당 worker 결과를 accept하지 말고 재dispatch 또는 owner 판단을 받는다. |
| `MODEL_PROBE_FAILED` | model probe가 실패했지만 register 자체는 완료됐다. | declared model을 측정 사실로 쓰지 말고 별도 확인한다. |
| `delivery UNVERIFIED` | terminal transition이 delivery pass가 아니다. | pane을 직접 읽고 worker가 contract를 받았는지 확인한다. |
## 관련 페이지
Acceptance suite, scorecard, regression log로 acceptance 판단을 반복 실행하는 흐름.
Accepted 또는 settled dispatch 이후 terminal과 worktree를 정리하는 절차.
Dispatch gate, model verification, placement, redaction 등 방어 표면의 실패 모드.
`scripts/dispatch-gate`, `scripts/dispatch` 등 공개 command surface와 exit code.
---
## 11. 마스터 승계
> trigger 감지, role freeze, thin handoff, successor verify, predecessor retirement, lineage append, revival check의 실행 순서를 설명합니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/11-page-11.md
- Generated: 2026-08-10T07:39:21.371Z
### Source Files
- `local-mogui-ade-orchestrator:docs/public/master-lifecycle.md`
- `local-mogui-ade-orchestrator:src/master_runtime/core/succession.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/lineage.py`
- `local-mogui-ade-orchestrator:scripts/master-succeed`
- `local-master-ops:docs/runbooks/succession-boot-card.md`
- `local-master-ops:docs/lineage/MASTER-LINEAGE.md`
- `local-mogui-ade-orchestrator:tests/test_succession_scenario.py`
---
title: "마스터 승계"
description: "trigger 감지, role freeze, thin handoff, successor verify, predecessor retirement, lineage append, revival check의 실행 순서를 설명합니다."
---
`scripts/master-succeed`가 마스터 승계의 실행 표면이다. 승계는 자동 교체가 아니라 명시적 지시 또는 측정된 advisory 신호를 분류한 뒤, 현재 마스터가 얇은 handoff를 만들고, successor가 recovery를 검증하고, predecessor를 측정 기반으로 retirement 처리한 뒤 lineage에 관측값을 append하는 절차다.
## 실행 순서
`master-succeed detect`는 텍스트와 선택적 `--context-ratio`를 받아 `IMMEDIATE`, `ADVISORY`, `NONE` 중 하나를 반환한다. `succession now`, `handoff to successor`, `승계해줘`, `다음 마스터로 넘기자`, `승계 진행해`는 즉시 승계 지시로 분류된다.
```bash
scripts/master-succeed detect \
"승계 진행해" \
--context-ratio 0.65 \
--json
```
`context_ratio >= 0.60`은 `ADVISORY`다. advisory는 승계 제안 신호일 뿐 successor를 자동 spawn하지 않는다.
승계 handoff는 `Role State`를 먼저 고정한다. `freeze_roles`는 현재 role만 유지하고 `lock_enabled=true`, `frozen=all other roles`, `unlock=explicit user instruction only` 형태로 잠근다. 현재 role이 없으면 승계 오류로 중단된다.
현재 마스터는 구조화된 JSON spec으로 handoff를 생성한다. handoff는 장문 회고가 아니라 successor가 복구해야 할 최소 운영 상태다.
```bash
scripts/master-succeed handoff \
--spec ./ops/handoff-spec.json \
--json
```
Spec에는 다음 항목을 넣는다.
| 항목 | 의미 |
| --- | --- |
| `current_role` 또는 `role_state` | 승계 후 유지할 현재 role |
| `current_objective` | 현재 목표 |
| `active_tracks`, `open_tracks` | 이어받을 작업 트랙 |
| `accepted_artifacts` | 이미 승인된 산출물 |
| `deferred_work` | 미룬 작업 |
| `open_questions` | 미해결 질문 |
| `recommended_next_role` | successor가 시작할 role |
| `observed_baseline` | handoff 시점의 관측 기준선 |
Successor spawn은 workspace selector, kickoff, root, model, title을 명시한다. 먼저 dry-run으로 실제 host command를 확인할 수 있다.
```bash
scripts/master-succeed spawn \
--workspace-selector "id:folder:" \
--kickoff-file ./ops/successor-kickoff.md \
--root . \
--model "" \
--agent codex \
--title "Gen N successor" \
--expected-placement "id:folder:" \
--json
```
Spawn은 생성 전 terminal 목록을 snapshot하고, 생성 후 반환된 `worktreeId`가 요청 selector와 일치하는지 확인한다. `--expected-placement`가 있으면 독립 기대 placement와도 다시 비교한다. 불일치하면 fail-closed로 terminal close를 시도하고 `SPAWN_PLACEMENT_MISMATCH` 계열 오류로 중단한다.
Successor는 recovery report를 만들고 `verify-successor`로 검증한다.
```bash
scripts/master-succeed verify-successor \
--report ./ops/recovery-report.json \
--json
```
검증 규칙은 단순하다. recovery step에 `MISS`가 있으면 `FAILED`다. step `6`이 `OK`이면 open tracks recited, step `2-3`이 `OK` 또는 없음이면 baseline matched, step `5`가 `OK`이면 monitors rearmed로 계산한다. 세 체크가 모두 있으면 `PASS`, 일부만 있으면 `PARTIAL`, 없으면 `FAILED`다.
Freezing은 retirement가 아니다. Predecessor 종료는 successor가 successor 자신과 predecessor를 구분한 뒤 실행한다. 기본은 dry-run이며, 실제 close에는 `--execute`가 필요하다.
```bash
scripts/master-succeed retire \
--self-handle \
--target-handle \
--target-pid \
--target-tty \
--json \
--execute
```
`retire`는 정확히 하나의 predecessor candidate만 허용한다. self handle 매치, candidate 없음, ambiguous candidate는 모두 `REFUSED`다. `--target-handle`, `--target-pty-id`, `--target-session-id`는 해당 필드에 exact match로 적용되고, selector 기반 fallback은 handle, pty, session id, worktree id, path, branch, title에 substring match를 수행한다.
Successor verification과 predecessor retirement 측정 후 `docs/lineage/MASTER-LINEAGE.md`에 concise entry를 append한다. Lineage는 append-only observability metadata이며 bootstrap source, priority source, model-evaluation source가 아니다.
Runtime의 `append_entry` 스키마는 `generation`, `parent_session`, `successor_session`, `timestamp`, `inherited_role`, `succession_reason`, `recovery_sources`, `inherited_open_tracks`, `verification`, `repeated_question_count`, `reopened_decision_count`, `context_loss_summary`, `predecessor_retirement_verified`를 요구한다. `verification` 값은 `PASS`, `PARTIAL`, `FAILED`만 허용한다.
Retired 또는 frozen session은 다른 terminal, remote machine, mobile resume 경로에서 되살아날 수 있다. Boot 시점과 stray session 보고 시점에는 lineage에 기록된 session id를 running agent process argv에서 찾는다. Hit가 있으면 revived session 기록에서 freeze 이후 활동과 unanswered owner instruction을 확인하고, 해당 process와 tty chain을 같은 retirement 기준으로 제거한다.
## 상태와 판정값
| 단계 | 주요 상태 | 의미 |
| --- | --- | --- |
| Trigger | `IMMEDIATE` | 명시적 승계 지시 |
| Trigger | `ADVISORY` | context pressure 또는 milestone 신호. 자동 승계 금지 |
| Trigger | `NONE` | 승계 신호 없음 |
| Successor verify | `PASS` | open tracks, baseline, monitors 체크가 모두 충족됨 |
| Successor verify | `PARTIAL` | 일부 recovery evidence만 충족됨 |
| Successor verify | `FAILED` | `MISS`가 있거나 검증 체크가 없음 |
| Retirement | `DRY_RUN` | candidate만 확인하고 close하지 않음 |
| Retirement | `CLOSED` | pane, process, tty 세 소멸이 모두 측정됨 |
| Retirement | `CLOSED_PARTIAL` | pane은 사라졌지만 pid 또는 tty 측정이 skip됨 |
| Retirement | `REFUSED` | candidate, self-match, survivor, close 실패 등으로 종료 불가 |
`CLOSED_PARTIAL`은 성공적인 전체 retirement가 아니다. pid 또는 tty를 측정하지 못한 상태에서 pane만 사라진 경우이며, lineage에는 partial measurement로 기록해야 한다.
## Retirement handshake
`master-succeed retire --execute`는 predecessor pane을 닫는 host-level close다. 그 자체는 agent 내부에 flush를 요청하지 않는다. 운영 절차에서는 close 전에 predecessor에게 새 dispatch 중단, 미커밋 상태 flush, live worker와 unfinished track 보고, 최종 FIN line 출력을 요구한다.
| 단계 | Actor | 요구 사항 |
| --- | --- | --- |
| Freeze notice | Successor | predecessor에게 새 작업 수락 중단과 flush를 지시 |
| ACK | Predecessor | 중단 상태를 확인하고 남은 송신만 유지 |
| Flush | Predecessor | 커밋 가능한 상태를 저장하거나 저장 실패 경로를 보고 |
| FIN | Predecessor | 합의한 final line을 출력하고 이후 발화 중단 |
| TIME_WAIT | Successor | pane read와 host last-output 기준으로 quiet window 측정 |
| Close | Successor | `retire --execute` 후 pane/process/tty 소멸 측정 |
## Placement와 duplicate 방어
Successor spawn은 selector와 실제 `worktreeId`를 비교한다. Folder workspace selector는 `id:folder:` 형태가 정상이며, bare `folder:`는 terminal list 호출에서 `id:`가 붙어 처리된다. `path:` selector는 repository worktree path 비교에만 사용된다.
```bash
scripts/master-succeed check-duplicates \
--self-handle \
--marker \
--json
```
Duplicate check는 현재 handle을 제외하고 marker와 일치하는 Orca terminal session을 찾는다. 결과가 비어 있지 않으면 같은 lineage 또는 workspace를 잡은 다른 master가 있다는 신호다.
## Lineage 작성 기준
Lineage entry는 successor가 boot comparison을 끝낸 뒤 append한다. 기록에는 최소한 generation, parent/successor reference, inherited role, open tracks, verification result, measured comparison values, context-loss 또는 repeated-question metric을 포함한다. 측정하지 못한 값은 narrative로 채우지 않고 `미확인` 또는 tool이 실제 반환한 `unconfigured`로 남긴다.
Lineage는 관측 로그다. Handoff와 fresh measurement가 충돌하면 handoff를 덮어쓰지 말고, 충돌 사실과 fresh measurement의 범위를 함께 기록한다.
## 실패 처리
| 증상 | 처리 |
| --- | --- |
| `detect`가 `ADVISORY`를 반환 | 승계를 제안할 수 있지만 자동 spawn하지 않는다 |
| successor spawn placement mismatch | 생성된 terminal close를 시도하고 fail-closed로 중단 |
| 반환 handle이 stale 또는 재발급됨 | 새 terminal 목록에서 같은 workspace와 title의 유일한 candidate만 adopt한다 |
| predecessor candidate가 0개 또는 여러 개 | `REFUSED`; title drift와 match attempts를 확인한다 |
| close 후 pane이 남아 있음 | `REFUSED`; close 반환값보다 측정 결과가 우선한다 |
| pid 또는 tty 미제공 | `CLOSED_PARTIAL`; full close로 기록하지 않는다 |
| process death, host restart, stale UI handle | succession이 아니라 accident recovery로 다루고 같은 session resume 가능성을 먼저 확인한다 |
## Related pages
Succession이 bootstrap, recovery, lineage, adapter layer와 어떻게 분리되는지 확인합니다.
Workspace selector, folder workspace, worktree placement 판정 기준을 확인합니다.
Duplicate master, placement mismatch, revival check가 어떤 실패를 막는지 표로 확인합니다.
`scripts/master-succeed` 하위 명령과 option surface를 빠르게 확인합니다.
---
## 12. Acceptance loop 실행
> acceptance suite 구조, train과 holdout 분리, proposer runtime, 반복 실행, scorecard, regression log를 다룹니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/12-acceptance-loop.md
- Generated: 2026-08-10T07:39:55.808Z
### Source Files
- `local-mogui-ade-orchestrator:src/master_runtime/core/acceptance/config.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/acceptance/casebook.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/acceptance/loop.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/acceptance/report.py`
- `local-mogui-ade-orchestrator:scripts/acceptance-loop`
- `local-mogui-ade-orchestrator:tests/test_acceptance_loop.py`
---
title: "Acceptance loop 실행"
description: "acceptance suite 구조, train과 holdout 분리, proposer runtime, 반복 실행, scorecard, regression log를 다룹니다."
---
`local-mogui-ade-orchestrator:scripts/acceptance-loop`는 JSON acceptance config를 읽어 `train`과 `holdout` casebook을 검증하고, proposer CLI가 만든 후보를 반복 평가한 뒤 `run_dir`에 split manifest, per-split result, iteration decision, 최종 report를 기록한다. 구현은 `local-mogui-ade-orchestrator:src/master_runtime/core/acceptance/`에 있으며, `local-master-ops`에는 동일한 acceptance loop 실행 파일이 없다.
## 실행 surface
| 작업 | 명령 | 결과 |
| --- | --- | --- |
| config 검증 | `scripts/acceptance-loop validate --config acceptance.json` | config와 casebook을 로드하고 split 개수, proposer runtime, run 경로를 JSON으로 출력한다. |
| split manifest 생성 | `scripts/acceptance-loop split --config acceptance.json [--output-dir runs/demo]` | `split.json`, `split.md`, `manifest.json`을 쓴다. |
| loop 실행 | `scripts/acceptance-loop run --config acceptance.json [--max-iterations N] [--baseline-ref REF] [--restore-cmd CMD]` | 후보 proposer를 호출하고 acceptance report를 출력한다. 모든 gated case가 통과하면 exit `0`, 미완료면 exit `1`이다. |
| report 확인 | `scripts/acceptance-loop inspect --run-dir runs/demo` | `report.json`을 그대로 출력한다. 파일이 없으면 exit `2`이다. |
`inspect`는 완료된 run directory의 `report.json`을 읽는 cold audit 경로다. acceptance suite를 다시 계산하거나 holdout 내용을 proposer workspace로 복사하지 않는다.
## Acceptance config
Config는 JSON object여야 하며, 상대 경로는 config 파일 위치를 기준으로 해석된다.
```json title="acceptance.json"
{
"name": "dz-bwh-demo",
"workspace_root": "workspace",
"run_dir": "runs/dz-bwh-demo",
"max_iterations": 2,
"proposer": {
"runtime": "codex",
"model": "gpt-5-codex",
"timeout_seconds": 60
},
"regression_log": "state/regressions.jsonl",
"cases": [
{
"case_id": "t1",
"split": "train",
"stratum": "unit",
"command": ["python3", "-m", "pytest", "tests/test_unit.py"]
},
{
"case_id": "h1",
"split": "holdout",
"stratum": "unit",
"command": ["python3", "-m", "pytest", "tests/test_holdout.py"]
}
]
}
```
비어 있지 않은 suite 이름이다.
평가 command와 proposer CLI가 실행되는 작업 디렉터리다. 기본값은 `"."`이다.
manifest, history, report가 기록되는 디렉터리다. 기본값은 `runs/{name}`이다.
양의 정수여야 한다. 기본값은 `3`이다.
동기 CLI profile 이름이다. 현재 profile은 `claude`, `codex`, `cursor-agent`이다.
CLI profile에 전달할 model 이름이다. 없으면 profile 기본값을 사용한다.
proposer CLI timeout이다. 기본값은 `1800`초이다.
선택적 JSONL 파일이다. 관측된 실패 case를 append-only로 고정하고 이후 run에 재투입한다.
## Casebook 구조
`cases` 항목은 `VerificationCase`로 로드된다. 각 case는 `case_id`, `split`, `stratum`, `command`, `origin`을 가진다.
| 필드 | 규칙 |
| --- | --- |
| `case_id` | 필수 문자열이다. 중복되면 config validation이 실패한다. |
| `split` | 필수 값이다. `train`, `holdout`, `scorecard`를 사용한다. alias로 `visible`은 `train`, `private`은 `holdout`, `acceptance`는 `scorecard`로 정규화된다. |
| `stratum` | 필수 문자열이다. seed `train`과 seed `holdout`은 동일한 stratum 집합을 가져야 한다. |
| `command` | 문자열 배열이다. `command_evaluator`에서 비어 있으면 해당 case는 fail-closed 처리된다. |
| `origin` | `seed` 또는 `regression`이다. 생략하면 `seed`이다. |
`train`과 `holdout`은 gated split이다. acceptance 결정은 두 split의 combined pass count만 비교한다. `scorecard` split은 gated pass count에 포함되지 않으며, 최종 보고용으로 baseline과 final candidate에 대해서만 실행된다.
## Train과 holdout 분리
`train`만 proposer-visible split이다. `holdout`과 `scorecard`는 private artifact 경로에 기록되며 proposer workspace에 들어가지 않는다.
```text
run_dir/
├── manifest.json
├── split.json
├── split.md
├── report.json
├── report.md
└── history/
├── visible/
│ ├── train//result.json
│ └── iterations/001/
│ ├── decision.json
│ ├── decision.md
│ └── proposer_workspace/
│ ├── task.md
│ ├── casebook_visible.json
│ ├── visible_failures.json
│ ├── history.json
│ ├── proposer_result.json
│ ├── proposer_stdout.log
│ └── proposer_stderr.log
└── private/
├── holdout//result.json
└── scorecard/-scorecard/result.json
```
Visibility는 `is_visible_split()` predicate 하나로 결정된다. layout routing, visible manifest, visible failure list가 같은 predicate를 사용하므로 `holdout` case id가 proposer workspace에 노출되는 경로를 분리한다.
## Proposer runtime
CLI proposer는 `ProposerRequest`를 만들고 `invoke_cli_proposer()`를 통해 subscription CLI subprocess를 실행한다. core loop는 vendor SDK나 API key를 직접 다루지 않는다. Runtime별 argv 조립은 `local-mogui-ade-orchestrator:src/master_runtime/core/adapter/profile.py`의 `SyncCliProfile` 구현이 담당한다.
| runtime | argv 형태 |
| --- | --- |
| `claude` | `claude -p [--model ]` |
| `codex` | `codex exec [--model ] ` |
| `cursor-agent` | `cursor-agent -p --trust --force [--model ] ` |
Proposer prompt는 `task.md`에 기록된 visible failure, visible casebook, 현재 candidate label, visible train score를 기반으로 한다. Proposer는 `candidate.json`을 써야 하며, 없거나 읽을 수 없으면 해당 iteration은 “no candidate produced”로 끝난다.
```json title="candidate.json"
{
"surfaces": ["src/target.py"],
"summary": "widened the guard",
"ref": "refs/candidates/iter-001"
}
```
`surfaces`가 비어 있으면 후보는 변경 없음으로 기록되고 `NO_CANDIDATE_CHANGE`로 거절된다. `summary`가 없으면 `proposal.md` 내용이 fallback summary로 사용된다.
## 반복 실행과 restore guard
Loop는 baseline을 먼저 gated cases에 대해 평가한다. 이미 모든 gated case가 통과하면 proposer iteration을 실행하지 않는다. 그렇지 않으면 `1..max_iterations` 범위에서 visible-only workspace를 만들고 proposer를 호출한다.
`train`과 `holdout` case를 평가하고 baseline score를 기록한다. 실패 case가 있으면 optional regression log에 promote한다.
`casebook_visible.json`, `visible_failures.json`, `history.json`, `task.md`를 `history/visible/iterations//proposer_workspace/`에 쓴다.
선택한 `proposer.runtime` CLI를 `workspace_root`에서 실행한다. CLI 결과는 `proposer_result.json`, `proposer_stdout.log`, `proposer_stderr.log`로 남는다.
`candidate.json`이 있고 `surfaces`가 비어 있지 않으면 gated cases를 다시 평가한다. 평가 결과는 split visibility에 따라 visible/private 경로에 분리 저장된다.
후보의 combined pass count가 현재 후보보다 엄격히 증가할 때만 accept한다. accept되면 current candidate가 갱신된다.
proposer 또는 evaluator가 workspace를 in-place로 바꾸는 경우, `max_iterations > 1`에서 rejection 이후 반복하려면 `--restore-cmd`가 필요하다.
`cli_proposer()`와 `command_evaluator()`는 in-place mutation으로 표시된다. 따라서 여러 iteration을 실행하면서 rejected tree를 평가하지 않으려면 restore hook을 명시해야 한다.
```bash
scripts/acceptance-loop run \
--config acceptance.json \
--max-iterations 3 \
--restore-cmd "git restore ."
```
## Scorecard와 결정 규칙
`Scorecard`는 case-level `CaseResult`와 split aggregate `SplitScore`를 분리한다. Evaluator가 case 결과를 누락하면 `missing result` 실패로 채운다. Evaluator가 split이나 stratum을 다르게 보고해도 casebook의 split과 stratum으로 덮어쓴다.
| reason | 조건 | decision |
| --- | --- | --- |
| `PASS_COUNT_INCREASED` | candidate combined pass count가 current보다 크다. | accepted |
| `NO_PASS_COUNT_INCREASE` | candidate가 바뀌었지만 combined pass count가 증가하지 않았다. | rejected |
| `NO_CANDIDATE_CHANGE` | candidate가 변경 surface를 선언하지 않았다. | rejected |
`scorecard` split이 있으면 baseline과 final candidate에 대해 별도로 실행된다. 아무 후보도 accept되지 않았으면 final tree가 baseline과 같으므로 final scorecard는 baseline scorecard를 재사용한다.
## Regression log
`regression_log`가 설정되면 매 평가에서 실패한 gated case가 JSONL에 append된다. 이미 기록된 `case_id`는 다시 promote하지 않는다. 이후 run에서 config가 해당 case를 여전히 포함하면 원래 config split을 유지한다. Config에서 빠진 regression case는 `holdout` split으로 재등록되어 proposer-visible set에 들어가지 않는다.
```json title="regressions.jsonl entry"
{"case_id":"t2","command":["true"],"iteration":1,"observed_split":"train","origin":"regression","split":"train","stratum":"io","ts":1000.0}
```
이 동작은 과거 실패 case가 suite 축소로 조용히 사라지는 것을 막는다. 단, unreadable JSONL line은 무시되므로 regression log 자체의 파일 무결성은 별도 운영 절차에서 관리해야 한다.
## 출력과 검증 신호
| 파일 | 의미 |
| --- | --- |
| `manifest.json` | 로드된 `AcceptanceConfig` 직렬화 결과다. |
| `split.json` | master-side 전체 split manifest다. private split도 포함한다. |
| `split.md` | split별 visibility label이 붙은 사람이 읽는 manifest다. |
| `history/visible/train/*/result.json` | proposer-visible train 결과다. |
| `history/private/holdout/*/result.json` | proposer에게 숨기는 holdout 결과다. |
| `history/visible/iterations/*/decision.json` | iteration별 audit record다. |
| `report.json` | 최종 machine-readable report다. |
| `report.md` | baseline/final split 점수와 iteration 요약이다. |
`validate`는 config 구조 오류, unsupported runtime, invalid JSON, casebook validation 실패를 stderr와 exit `2`로 보고한다. `run`은 config load 오류도 exit `2`로 반환하고, loop가 정상 종료되더라도 final score가 complete가 아니면 exit `1`을 반환한다.
## Provider-neutral 운영 경계
Acceptance loop의 core는 proposer를 `Proposer` callable로, evaluator를 `Evaluator` callable로 받는다. 기본 CLI proposer도 `SyncCliProfile` adapter를 통해 argv를 만들 뿐 특정 hosted provider SDK에 연결하지 않는다. 따라서 새 runtime을 추가할 때는 core acceptance decision을 바꾸지 않고 profile 또는 callable 주입 경계를 확장한다.
BYOC/BYOK 환경에서는 config의 `proposer.runtime`, `proposer.model`, local CLI authentication, `workspace_root`만 운영자가 소유한다. Acceptance 결정은 local command 결과와 casebook pass count로 계산되며, natural-language rationale이나 provider별 score는 gate에 참여하지 않는다.
## Related pages
`acceptance-loop` subcommand와 exit code를 다른 공개 script surface와 함께 확인한다.
Acceptance report, split result, regression log를 운영 증거로 해석할 때의 라벨 기준을 맞춘다.
런타임 설정, 환경 변수 override, fail-closed 설정 해석 규칙을 함께 확인한다.
Worker deliverable을 acceptance 전 재검증 흐름과 연결한다.
---
## 13. 작업자 정리
> settled dispatch 확인, terminal close, worktree clean과 merge 포함 여부 검사, dry-run, reap ledger 기록을 설명합니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/13-page-13.md
- Generated: 2026-08-10T07:39:47.794Z
### Source Files
- `local-mogui-ade-orchestrator:src/master_runtime/core/worker_reap.py`
- `local-mogui-ade-orchestrator:scripts/worker-reap`
- `local-mogui-ade-orchestrator:docs/runbooks/worker-reap.md`
- `local-mogui-ade-orchestrator:tests/test_worker_reap.py`
- `local-master-ops:scripts/worker-pane-sweep`
---
title: "작업자 정리"
description: "settled dispatch 확인, terminal close, worktree clean과 merge 포함 여부 검사, dry-run, reap ledger 기록을 설명합니다."
---
`local-mogui-ade-orchestrator:scripts/worker-reap`는 Orca dispatch 상태를 조회한 뒤, settled 상태인 작업자 terminal을 닫고 안전하다고 판정된 worktree만 제거하는 명시 실행 CLI입니다. `local-master-ops:scripts/worker-pane-sweep`는 같은 수명주기에서 live Orca pane을 분류하는 보조 검사기이며, terminal close나 worktree 제거를 직접 수행하지 않습니다.
## 실행 표면
| 표면 | 역할 |
| --- | --- |
| `local-mogui-ade-orchestrator:scripts/worker-reap` | settled dispatch 정리 실행기 |
| `master_runtime.core.worker_reap.WorkerReaper` | dispatch 조회, terminal close, worktree 안전성 검사, ledger append 구현 |
| `master_runtime.core.work_ledger.ReapObservability` | ledger에서 settled지만 reap 기록이 없는 dispatch 탐지 |
| `local-master-ops:scripts/worker-pane-sweep` | live Orca terminal 상태 분류기 |
```bash
local-mogui-ade-orchestrator/scripts/worker-reap \
--task-id \
--ledger ~/.mogui/dispatch-ledger.jsonl
```
`--task-id`와 `--dispatch-id`는 상호 배타이며 둘 중 하나가 필수입니다. `--ledger`를 넘기면 실제 실행 시 reap 이벤트가 JSONL로 append됩니다.
## 정리 가능 상태
`worker-reap`는 `orca orchestration dispatch-show --json`으로 dispatch를 읽습니다. 상태 문자열은 대문자로 정규화되며, 다음 상태만 settled로 취급합니다.
| 상태 | reap 허용 |
| --- | --- |
| `COMPLETED` | 예 |
| `ACCEPTED` | 예 |
| `FAILED` | 예 |
| `ABANDONED` | 예 |
| `RUNNING` | 아니요 |
| `REGISTERED` | 아니요 |
열린 dispatch는 정리하지 않습니다. `RUNNING` 또는 `REGISTERED`처럼 settled가 아닌 상태는 exit code `3`으로 거부됩니다.
`FAILED`와 `ABANDONED`도 settled입니다. 이 구현은 성공 여부가 아니라 dispatch가 더 이상 열린 작업이 아닌지를 기준으로 terminal 회수를 허용합니다.
## 실행 순서
`--task-id`가 있으면 `orca orchestration dispatch-show --json --task `를 호출하고, `--dispatch-id`가 있으면 `--dispatch `를 사용합니다. JSON 파싱 실패는 exit code `4`입니다.
상태가 `COMPLETED`, `ACCEPTED`, `FAILED`, `ABANDONED` 중 하나가 아니면 실행을 중단합니다. 이 단계 전에는 terminal close나 worktree 제거를 하지 않습니다.
dispatch payload에 `terminal_id`가 있으면 실제 실행 모드에서 `orca terminal close `를 호출합니다. close 실패는 reap 실패로 처리됩니다.
`worktree_path`가 있으면 git 상태와 merge 포함 여부를 검사합니다. clean하고 `origin/main`에 포함된 worktree만 `git worktree remove `로 제거합니다.
실제 실행이고 `--ledger`가 제공된 경우에만 `event: "reap"` JSONL 행을 append합니다. `--dry-run`은 ledger를 쓰지 않습니다.
## Worktree 제거 조건
worktree 제거는 보수적으로 동작합니다. 아래 조건을 모두 만족해야 제거됩니다.
| 검사 | 명령 또는 판정 |
| --- | --- |
| 경로 존재 | `worktree_path.exists()` |
| git 상태 clean | `git -C status --porcelain` 출력이 비어 있어야 함 |
| 현재 branch 확인 | `git -C branch --show-current` |
| 일반 merge 포함 | 현재 branch가 `git -C branch -a --merged origin/main` 결과에 포함 |
| squash merge 포함 | `git merge-tree --write-tree origin/main HEAD` 결과 tree가 `origin/main^{tree}`와 동일 |
일반 ancestry merge가 아니어도, squash merge 후 branch 변경분이 이미 `origin/main` tree에 포함되어 있으면 제거 가능합니다. 반대로 dirty 상태, detached HEAD, git 오류, `origin/main` 해석 실패, virtual merge 충돌, tree 변경이 남는 경우는 제거하지 않습니다.
```text
dispatch settled
-> terminal close
-> worktree exists?
no -> worktree_left::Worktree path does not exist
yes -> clean?
no -> worktree_left::Worktree has uncommitted changes
yes -> included in origin/main?
yes -> worktree_removed:
no -> worktree_left::Current branch ... is not merged to origin/main (...)
```
## Dry-run 동작
`--dry-run`은 `execute=False`로 실행됩니다. dispatch 조회와 안전성 검사는 수행하지만, terminal close, worktree remove, ledger append는 수행하지 않습니다.
```bash
local-mogui-ade-orchestrator/scripts/worker-reap \
--dispatch-id dispatch_xyz \
--ledger ~/.mogui/dispatch-ledger.jsonl \
--dry-run
```
출력의 `record.actions_taken`에는 실제 실행 시 수행될 action 문자열이 들어갑니다. 따라서 dry-run 출력의 `terminal_closed:`나 `worktree_removed:`는 실행 결과가 아니라 계획된 결과로 읽어야 합니다. JSON 최상위의 `dry_run: true`가 실행 여부를 구분합니다.
## 출력과 ledger 형식
기본 출력은 pretty JSON이며, `--json`을 주면 compact JSON입니다.
```json
{
"record": {
"task_id": "task_abc123",
"dispatch_id": "dispatch_xyz",
"terminal_id": "term_123",
"worktree_path": "/path/to/worktree",
"actions_taken": "terminal_closed:term_123;worktree_removed:/path/to/worktree",
"timestamp": 1722787200.0
},
"dry_run": false
}
```
ledger append 행은 `event`, `ts`, 그리고 record 필드를 함께 담습니다.
```json
{"actions_taken":"terminal_closed:term_123;worktree_removed:/path/to/worktree","dispatch_id":"dispatch_xyz","event":"reap","task_id":"task_abc123","terminal_id":"term_123","timestamp":1722787200.0,"ts":1722787200.0,"worktree_path":"/path/to/worktree"}
```
`actions_taken`은 세미콜론으로 연결된 문자열입니다. 대표 action은 다음과 같습니다.
| action | 의미 |
| --- | --- |
| `terminal_closed:` | dispatch terminal close가 계획 또는 실행됨 |
| `worktree_removed:` | clean하고 포함된 worktree가 제거됨 |
| `worktree_left::` | worktree를 남겼고 reason을 기록함 |
## Unreaped dispatch 탐지
`ReapObservability`는 dispatch ledger를 읽어 settled 상태지만 `reap` 이벤트가 없는 dispatch를 반환합니다.
```python
from master_runtime.core.work_ledger import ReapObservability
obs = ReapObservability("~/.mogui/dispatch-ledger.jsonl")
unreaped = obs.unreaped_settled_leases()
```
이 탐지는 `dispatch_submitted`, `dispatch_completed`, `reap` 이벤트를 재생합니다. 유효하지 않은 JSON 행이나 dispatch id가 없는 행은 건너뜁니다.
## Pane sweep과의 관계
`local-master-ops:scripts/worker-pane-sweep`는 정리 전후에 live terminal 상태를 읽는 분류 도구입니다. `orca terminal list`로 terminal handle을 찾고, 각 handle의 최근 frame을 `orca terminal read --terminal `로 읽어 verdict를 출력합니다.
| verdict | 의미 | exit 영향 |
| --- | --- | --- |
| `working` | TUI가 작업 중 | `ok` |
| `idle` | ready prompt 상태 | `ok` |
| `approval` | 승인 또는 확인 prompt 대기 | exit `1` |
| `start-screen` | launch/resume 화면 | exit `1` |
| `update` | runtime restart 필요 | exit `1` |
| `limit` | quota 또는 rate limit | exit `1` |
| `shell` | agent가 종료되고 shell만 남음 | `note` |
| `unknown` | 분류 불가 | exit `1` |
`scripts/worker-pane-sweep`는 action을 수행하지 않습니다. 출력이 `ACTION` 또는 `UNREAD`이면 pane을 직접 읽고 coordinator 결정을 내려야 합니다.
## 실패와 보류 신호
| 신호 | 원인 | 조치 |
| --- | --- | --- |
| exit `2` | `--task-id`와 `--dispatch-id`가 모두 없음 | 둘 중 하나만 지정 |
| exit `3` | dispatch가 settled 상태가 아님 | completion, acceptance, failure, abandon 상태를 먼저 확인 |
| exit `4` | dispatch JSON 파싱 실패 | Orca 출력과 CLI 버전 확인 |
| `Worktree has uncommitted changes` | worktree dirty | 변경분을 검토, commit 또는 수동 정리 |
| `detached HEAD` | 현재 branch를 확인할 수 없음 | branch 상태를 수동 확인 |
| `not merged to origin/main` | ancestry 또는 squash 포함을 증명하지 못함 | merge 여부를 확인하고 필요 시 남겨 둠 |
| `Check failed: ...` | git 검사 또는 remove 중 예외 | worktree를 남긴 상태로 reason 확인 |
## 운영 원칙
정리는 자동 sweep이 아니라 명시 호출입니다. completion report 처리는 검증, merge 판단, reap ledger 기록까지 끝나야 닫힌 것으로 취급합니다. 애매한 worktree는 제거하지 않고 reason을 남깁니다. terminal close는 worker 세션 자원을 회수하는 단계이고, worktree remove는 git 상태와 `origin/main` 포함 여부가 별도로 증명될 때만 수행하는 단계입니다.
## Related pages
dispatch 생성, register, completion channel, acceptance 전 재검증 흐름.
작업 결과를 수락하기 전 반복 검증과 scorecard 처리.
`scripts/worker-reap` 옵션, exit code, 공개 command surface.
열린 dispatch, unavailable worktree, model probe, redaction 실패 신호별 대응.
---
## 14. 방어 인벤토리
> dispatch gate, ledgered decisions, model verification, placement, duplicate master, redaction, revival, progressive onboarding guard를 표로 정리합니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/14-page-14.md
- Generated: 2026-08-10T07:40:02.084Z
### Source Files
- `local-mogui-ade-orchestrator:docs/public/defense-inventory.md`
- `local-mogui-ade-orchestrator:src/master_runtime/core/dispatch_gate.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/succession.py`
- `local-mogui-ade-orchestrator:scripts/redaction-scan.sh`
- `local-master-ops:docs/runbooks/succession-boot-card.md`
- `local-master-ops:docs/MASTER-OPERATIONS.md`
---
title: "방어 인벤토리"
description: "dispatch gate, ledgered decisions, model verification, placement, duplicate master, redaction, revival, progressive onboarding guard를 표로 정리합니다."
---
`mogui-ADE-orchestrator`의 방어 표면은 `scripts/dispatch-gate`, `scripts/master-succeed`, `scripts/model-identity-probe`, `scripts/model-drift-audit`, `scripts/redaction-scan.sh`, `scripts/redaction-inventory`와 `master-ops` 템플릿 runbook에 나뉘어 있다. 각 방어는 허용/거부 verdict, JSONL ledger, Orca terminal metadata, transcript, 또는 scan coverage처럼 다시 읽을 수 있는 측정값을 남기는 경우에만 운영 규칙으로 취급된다.
## 방어 항목
| 방어 | 막는 실패 | 실행 표면 | 통과 신호 | 실패 신호 |
| --- | --- | --- | --- | --- |
| Dispatch gate | contract 없이 worker를 만들거나, budget·tier·completion channel 검사를 우회하는 dispatch | `scripts/dispatch-gate check`, `src/master_runtime/core/dispatch_gate.py` | JSON verdict `allow: true`, `reason: OK`, dispatch ticket 발급 | `CONTRACT_UNREADABLE`, `INVALID_REQUEST`, `BUDGET_EXCEEDED`, `ROUTING_VIOLATION`, `TIER_POLICY_UNAVAILABLE`, `TIER_FANOUT_CAP` |
| Ledgered decisions | “gate가 허용했다”는 사후 주장만 있고 어떤 정책이 판단했는지 모르는 상태 | `.dispatch-gate-ledger.jsonl` 또는 `--ledger`, `dispatch-gate report` | row에 `tier_policy_path`, `tier_policy_sha256`, `tier`, `contract_sha`, `attempt` 기록 | ledger가 없거나 읽을 수 없음, JSON decode 실패, 같은 span에 여러 정책 digest가 섞임 |
| Model verification | 선언한 model id와 실제 worker session model이 다른 상태 | `dispatch-gate register --declared-model --model-probe-cmd`, `model-identity-probe`, `model-drift-audit` | ledger에 `model_declared`, `model_measured`, `model_verified: true` 기록 | `MODEL_TIER_ESCALATION` deny, `MODEL_MISMATCH`, `MODEL_UNVERIFIED`, `MODEL_PROBE_FAILED` warning |
| Placement guard | master가 workspace folder seat가 아니라 product repository worktree에 앉는 misplacement | `master-succeed spawn --workspace-selector --expected-placement`, onboarding `04-seat.md`, `09-spawn.md` | spawn verification `MATCH` 또는 `MATCH_REISSUED`; selector, cwd, session namespace 3종 증거 | exit 26 `SPAWN_PLACEMENT_MISMATCH`, stale handle, wrong worktree, path selector 대체 |
| Empty-seat gate | Founding 재진입으로 같은 seat에 두 번째 master를 만드는 상태 | `orca terminal list --worktree --json`, onboarding `09-spawn.md` | spawn 전 seat terminal 수 0 | 기존 terminal이 하나라도 있으면 hard stop |
| Duplicate master detection | succession·resume 후 master session이 둘 이상 살아 있는 상태 | `master-succeed check-duplicates --self-handle --marker` | `duplicates: []` | self handle 제외 후 같은 marker session이 반환됨 |
| Redaction scan | generic secret scan만 돌고 조직 식별자 rule 누락을 green으로 오해하는 상태 | `scripts/redaction-scan.sh`, `REDACTION_EXTRA_PATTERNS`, `REDACTION_REQUIRE_EXTRA=1` | `OK — 0 findings`와 mode, files, commit-messages, org-rules count 출력 | exit 1 findings, exit 2 missing tool/rules/config/range/engine failure |
| Redaction inventory | rule이 실제 tree token blind spot을 덮는지 모르는 상태 | `scripts/redaction-inventory` | exit 0 uncovered candidate 없음 | exit 1 uncovered candidates, exit 2 rules 없음 또는 git tree 측정 불가 |
| Revival check | retired master가 다른 device나 terminal에서 다시 resume되는 상태 | `docs/runbooks/succession-boot-card.md`, lineage session id, process/tty 측정 | process, pane, tty 세 disappearance 측정 후 `CLOSED` | `CLOSED_PARTIAL`, `REFUSED`, session id 누락, process/tty 측정 불가 |
| Progressive onboarding guard | installer가 전체 onboarding 문서를 한 번에 읽고 mode를 섞거나 spawn 금지를 우회하는 상태 | `ONBOARDING.md`, `onboarding/*.md`, `reverify.md`, `upgrade.md` | 한 turn에 한 step file만 load, Verify 통과 후 다음 step | Reverify/Upgrade에서 spawn 시도, Founding guard와 기존 ops/lineage 충돌 |
## Dispatch gate와 tier 정책
`dispatch-gate check`는 contract, runtime, model, agent 수, estimated chars, completion channel을 받아 verdict를 만든다. 기본 completion channel은 암묵적으로 허용되지 않으며, 허용 가능한 값은 `orchestration`과 `sentinel-log`이다.
```bash
scripts/dispatch-gate --ledger ~/.mogui/dispatch-ledger.jsonl check \
--runtime claude \
--model claude-haiku-4-5-20251001 \
--contract contracts/example.md \
--agents 1 \
--est-chars 3000 \
--completion-channel orchestration
```
Tier policy 해석 순서는 명시적 `--tier-policy`, `DISPATCH_TIER_POLICY`, instance `config/model-tier-policy.json`, template `master-ops/model-tier-policy.json`이다. 현재 template policy는 `version: 2`이며 `unknown` tier에 `fanout_caps.unknown: 8`, `window_seconds: 86400`을 둔다. `top` tier는 template policy에서 cap이 제거되어 있고, ops wrapper인 `master-ops/scripts/dispatch`가 top-tier model에 대해 `--top-approved ""`을 요구한다.
`--top-approved`는 인증 경계가 아니라 운영 승인 이유를 run log에 남기는 절차 방어다. gate ledger에는 policy path와 digest가 남고, wrapper stdout에는 top-tier 승인 이유가 남는다.
`--no-record`는 dry run 전용이다. 이 옵션은 ledger row와 dispatch ticket을 만들지 않으므로, 검사 자체가 fan-out window를 소비하지 않는다.
## Register-time 검증
`register`는 worker job id가 실제 artifact에 나타나는지 `--probe-cmd`로 확인한 뒤 pending dispatch와 연결한다. completion channel이 `sentinel-log`가 아니면 orchestration task 검증도 요구된다.
```bash
scripts/dispatch-gate --ledger ~/.mogui/dispatch-ledger.jsonl register \
--job-id \
--contract-sha \
--runtime claude \
--orchestration-task \
--probe-cmd "orca orchestration dispatch-show --task --json | grep -o | head -1" \
--declared-model claude-haiku-4-5-20251001 \
--model-probe-cmd "scripts/model-identity-probe --transcript "
```
| 상태 | 처리 |
| --- | --- |
| declared model과 measured model이 같음 | register allow, model verification 기록 |
| measured model이 declared model보다 더 엄격한 tier | `MODEL_TIER_ESCALATION` deny |
| measured model이 다르지만 더 느슨하거나 rank 불가 | `MODEL_MISMATCH` warning |
| declared model 없음 | `MODEL_UNVERIFIED` warning |
| model probe 실패 또는 빈 결과 | `MODEL_PROBE_FAILED` warning |
`model-identity-probe`는 최근 assistant event의 model field를 읽는다. `--expect` 또는 `MODEL_IDENTITY_EXPECT`가 없으면 exit 0이어도 “정보 출력”일 뿐 pass assertion이 아니다. `model-drift-audit`는 transcript 전체 assistant turn을 걷고 model transition을 보고한다. exit 2는 두 스크립트 모두 “판정 불가” 계열로 취급해야 하며 clean pass로 읽으면 안 된다.
## Placement와 master 중복 방어
Master seat는 multi-repository workspace에서 folder workspace여야 한다. product repository worktree에 앉은 master는 cwd와 hook이 맞아도 worker seat에 앉은 것이므로 misplacement다.
Founding spawn 전에 durable seat selector를 다시 확인한다.
```bash
orca terminal list --worktree --json
```
이 목록이 0 terminal이어야 spawn을 진행한다. 이후 `master-succeed spawn`은 requested worktree와 Orca가 반환한 `worktreeId`를 비교하고, 별도의 `--expected-placement`가 있으면 그 값과도 다시 비교한다.
```bash
scripts/master-succeed spawn \
--workspace-selector \
--expected-placement \
--kickoff-file \
--root \
--model \
--title "Gen-1 founding boot" \
--json
```
중복 master는 runtime check로도 확인한다.
```bash
scripts/master-succeed check-duplicates \
--self-handle \
--marker \
--json
```
결과의 `duplicates`가 비어 있지 않으면 soft warning이 아니라 중복 master finding이다.
## Redaction 방어
`redaction-scan.sh`는 tracked file, staged file, range file, commit message를 gitleaks로 검사하고 scan scope를 출력한다. 조직별 rule은 repository에 commit하지 않고 `REDACTION_EXTRA_PATTERNS` 파일로 공급한다.
```bash
REDACTION_EXTRA_PATTERNS=~/.config/mogui/redaction-extra.txt \
REDACTION_REQUIRE_EXTRA=1 \
scripts/redaction-scan.sh --staged
```
| exit | 의미 |
| --- | --- |
| 0 | clean |
| 1 | finding 있음 |
| 2 | 판정 불가: gitleaks 없음, base config 없음, required extra rule 없음, range 불가, engine self-test 실패, retired allowlist 사용 등 |
`redaction-inventory`는 scan의 역방향 질문을 한다. rule이 덮지 못한 후보 token을 보고하며, candidate는 secret 판정이 아니다.
```bash
REDACTION_EXTRA_PATTERNS=~/.config/mogui/redaction-extra.txt \
scripts/redaction-inventory --baseline .redaction-inventory-baseline
```
## Revival과 retirement
Succession retirement는 close command 성공으로 끝나지 않는다. `succession-boot-card.md`는 process, pane, tty 세 disappearance가 모두 측정될 때만 retirement를 완료로 본다.
| retirement 상태 | 의미 |
| --- | --- |
| `CLOSED` | pane, process, tty disappearance 모두 측정 |
| `CLOSED_PARTIAL` | pane은 사라졌지만 process 또는 tty 측정이 skipped |
| `REFUSED` | 대상이 여전히 present이거나 self close 위험, ambiguous target 등 |
| `DRY_RUN` | close 실행 없이 대상만 해석 |
부팅 시 또는 owner가 stray session을 보고하면 lineage에 기록된 session id를 process argv에서 찾는다. revived session이 발견되면 해당 session record를 읽어 미처리 owner instruction을 회수하고, agent process와 hosting tty chain을 종료한 뒤 gone 상태를 다시 측정한다.
## Progressive onboarding guard
`ONBOARDING.md`는 router이고, step 파일은 한 번에 하나만 읽는 운영 단위다. Founding은 `00`부터 `10`까지 진행하지만, Reverify와 Upgrade는 각각 전용 파일만 읽고 spawn을 금지한다.
| mode | 허용 경로 | spawn |
| --- | --- | --- |
| Founding | `00-orientation.md` → `10-card-and-retire.md` | Step 8에서만 가능 |
| Reverify | `onboarding/reverify.md` | 금지 |
| Upgrade | `onboarding/upgrade.md` | 금지 |
| Template improve | installer flow 중단 후 일반 작업으로 routing | 금지 |
기존 ops repository나 lineage file이 있으면 Founding이 아니다. master가 죽었거나 half-finished install이어도 Founding 재실행으로 복구하지 않고, ops repository의 succession/recovery 절차로 넘긴다.
## Related pages
`check -> dispatch -> register` 흐름과 acceptance 전 재검증 절차.
transcript 기반 model probe, drift audit, undecidable 상태.
scan scope, 조직 rule, commit message scan, release gate.
misplacement, duplicate master, model probe undecidable, redaction cannot decide 대응.
---
## 15. 모델 식별과 drift 감사
> `model-identity-probe`, `model-drift-audit`, transcript glob 해석, expected model, undecidable 상태와 register-time 검증을 설명합니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/15-drift.md
- Generated: 2026-08-10T07:39:43.199Z
### Source Files
- `local-mogui-ade-orchestrator:scripts/model-identity-probe`
- `local-mogui-ade-orchestrator:scripts/model-drift-audit`
- `local-mogui-ade-orchestrator:src/master_runtime/core/instance_runtime_config.py`
- `local-mogui-ade-orchestrator:config/instance-runtime.example.json`
- `local-mogui-ade-orchestrator:tests/test_model_identity_probe.py`
- `local-mogui-ade-orchestrator:tests/test_model_drift_audit.py`
- `local-master-ops:scripts/dispatch`
---
title: "모델 식별과 drift 감사"
description: "`model-identity-probe`, `model-drift-audit`, transcript glob 해석, expected model, undecidable 상태와 register-time 검증을 설명합니다."
---
`local-mogui-ade-orchestrator:scripts/model-identity-probe`는 세션 JSONL에서 최근 assistant turn의 `model` 필드를 측정하고, `local-mogui-ade-orchestrator:scripts/model-drift-audit`는 같은 transcript 전체를 걸어 모델 전이를 판정한다. `local-master-ops:scripts/dispatch`는 작업자 `register` 전에 worker transcript를 읽을 수 있을 때만 `model-identity-probe`를 register-time 검증 명령으로 연결하며, 범위를 특정 worker로 좁힐 수 없으면 검증 불가 상태를 명시한다.
## 명령 표면
| 명령 | 질문 | 기본 판정 단위 | 성공 의미 |
| --- | --- | --- | --- |
| `scripts/model-identity-probe` | 지금 최근 turn이 기대 모델인가 | 최근 assistant model 샘플, 기본 `--limit 10` | `--expect`가 있을 때 모든 샘플이 기대 모델과 일치 |
| `scripts/model-drift-audit` | 세션 중간에 모델이 바뀐 적이 있는가 | transcript 전체 assistant turn 순서 | 전이가 없고, `--expect`가 있으면 모든 실제 모델이 기대 모델과 일치 |
| `scripts/dispatch` register 단계 | 선언한 worker model이 실제 worker artifact와 맞는가 | worker-scoped transcript probe 또는 명시 glob | ledger에 `model_verified=true` 기록 |
`model-identity-probe`의 `0`은 항상 같은 의미가 아니다. `--expect` 또는 `MODEL_IDENTITY_EXPECT`가 없으면 정보 출력만 하고 아무 것도 단정하지 않는다.
## transcript 위치 해석
`model-identity-probe`에서 `--transcript`를 생략하면 위치는 다음 순서로 해석된다.
`--transcript `이 있으면 해당 파일을 그대로 사용한다.
`MOGUI_TRANSCRIPT_GLOB`이 있으면 runtime 이름이나 instance config 없이도 이 glob의 최신 파일을 선택한다.
`--config`, `INSTANCE_RUNTIME_CONFIG`, 기본 `config/instance-runtime.json` 순서로 설정 파일을 찾고, `--runtime` 또는 `master_host_runtime`에 대응하는 `transcript_globs.`을 읽는다.
경로를 결정할 수 없으면 기본 transcript 위치를 추측하지 않고 exit `2`로 종료한다.
설정 예시는 다음 구조를 갖는다.
```json title="config/instance-runtime.example.json"
{
"master_host_runtime": "claude",
"transcript_globs": {
"claude": "~/.claude/projects/-Users-example-workspace/*.jsonl",
"codex": "~/.codex/sessions/**/*.jsonl",
"grok": "~/.grok/sessions/**/*.jsonl"
},
"product_repo": "/absolute/path/to/primary-product-repo"
}
```
`transcript_globs`의 key는 host nickname이 아니라 agent CLI runtime 이름이다. `_docs`와 `_note`처럼 `_`로 시작하는 key는 문서용으로 무시된다. 잘못된 JSON, 빈 runtime key, 빈 glob 문자열은 구성 오류로 취급된다.
## expected model
두 스크립트 모두 기대 모델을 코드에 고정하지 않는다. 기대 모델은 workspace, host, dispatch lane마다 달라질 수 있으므로 호출자가 명시해야 한다.
```bash title="최근 model identity 확인"
scripts/model-identity-probe \
--transcript ./sessions/session.jsonl \
--expect claude-fable-5
```
```bash title="세션 전체 drift 감사"
scripts/model-drift-audit \
--transcript ./sessions/session.jsonl \
--expect claude-fable-5
```
`model-drift-audit --expect`는 전이가 없어도 실제 모델 중 하나가 기대 모델과 다르면 exit `1`을 반환한다. `--json`을 함께 쓰면 `expect`, `expect_mismatch`, `counts`, `transitions`, `transitions_including_synthetic`를 포함한 JSON을 출력한다.
## transcript event 해석
두 도구는 transcript shape 차이를 줄이기 위해 top-level event와 중첩 object를 함께 본다.
```text
event
├─ role/type/model
├─ message.role/type/model
├─ item.role/type/model
├─ payload.role/type/model
└─ response.role/type/model
```
assistant turn 판정은 `role == "assistant"` 또는 `type == "assistant"`이다. assistant turn인데 model 문자열을 읽을 수 없으면 `model-identity-probe`와 `model-drift-audit` 모두 ``을 모델 값으로 보존한다. 이 turn을 버리면 실제 drift가 `` 구간 안에 숨어도 “clean”으로 보일 수 있기 때문이다.
## exit code와 undecidable
| 명령 | `0` | `1` | `2` |
| --- | --- | --- | --- |
| `model-identity-probe` | 기대 모델 일치, 또는 기대 모델 없이 정보 출력 | 사용하지 않음 | drift, invalid limit, transcript/config 오류, unconfigured |
| `model-drift-audit` | 전이 없음, 기대 모델도 일치 | 전이 있음 또는 기대 모델 mismatch | transcript 없음, 읽기 실패, assistant turn 없음, 실제 모델 없음 |
`model-drift-audit`의 undecidable은 pass가 아니다. 예를 들어 transcript가 없거나, assistant turn이 0개이거나, 모든 assistant turn이 `` 또는 ``이면 실제 모델을 관측하지 못한 상태로 exit `2`를 반환한다.
`model-identity-probe`의 exit `2`는 drift와 undecidable을 같은 code로 보고한다. 자동화는 stdout의 `MODEL-PROBE DRIFT:` 또는 `unconfigured` 메시지를 함께 읽어야 한다.
## synthetic turn 처리
`model-drift-audit`는 synthetic turn을 ``으로 취급한다. `--ignore-synthetic`을 사용하면 synthetic turn 자체는 전이 계산에서 제외하지만, 양쪽 실제 모델 사이의 변화는 유지한다.
```text
claude-fable-5 -> -> claude-opus-5
```
`--ignore-synthetic` 후에는 위 sequence가 `claude-fable-5 -> claude-opus-5` 전이로 남는다. synthetic turn을 제거하면서 양쪽 모델 변화까지 지우는 동작은 drift를 놓치는 실패 모드다.
## register-time 검증
`local-master-ops:scripts/dispatch`는 `check -> task-create -> terminal -> dispatch --inject -> register` 순서에서 register 직전에 model probe 대상을 결정한다.
| 상태 | 조건 | register 출력 의미 |
| --- | --- | --- |
| `explicit-glob` | 호출자가 `--transcript-glob`을 제공 | caller가 확인한 glob으로 model probe 수행 |
| `scoped-to-worktree` | runtime이 worker worktree 경로로 transcript glob을 만들 수 있음 | worker-scoped transcript로 model probe 수행 |
| `unavailable` | glob을 worker 하나로 좁힐 수 없음 | `declared_model`은 측정값이 아니며 수동 확인 필요 |
현재 wrapper는 Claude transcript 경로만 worktree에서 파생한다. 다른 runtime은 working directory가 transcript path가 아니라 JSONL 내부에 저장될 수 있어, 단순 glob으로 특정 worker를 식별할 수 없으면 probe를 붙이지 않는다. 넓은 glob으로 최신 파일을 고르면 다른 세션이나 master transcript를 “검증”할 수 있으므로, 검증 실패보다 나쁜 false pass가 된다.
`dispatch-gate register`는 job id probe가 실패하면 등록을 거부한다. model probe는 graded verdict다.
| register 결과 | 조건 | ledger 의미 |
| --- | --- | --- |
| verified | `model_declared`와 `model_measured`가 case-insensitive 일치 | `model_verified=true` |
| `MODEL_UNVERIFIED` | 선언 모델 또는 측정 모델이 없음 | 등록은 허용, `model_verified=false` |
| `MODEL_PROBE_FAILED` | probe command가 실패하거나 출력이 없음 | 등록은 허용, 실패 상태 기록 |
| `MODEL_MISMATCH` | 측정 모델이 선언 모델과 다르지만 더 엄격한 tier가 아님 | 등록은 허용, warning 기록 |
| `MODEL_TIER_ESCALATION` | 측정 모델이 선언 모델보다 더 엄격한 tier | 등록 거부 |
## 운영 기준
부팅 시 측정한 모델은 세션 전체의 속성이 아니라 한 시점의 snapshot이다. resume, continue, compaction, succession audit, session close처럼 세션 상태가 바뀐 뒤에는 다시 측정한다. 최근 turn 샘플은 “지금 무엇으로 보이는가”를 답하고, 중간 drift 여부는 전체 transcript 감사로만 답한다.
TUI status line은 model 증거로 쓰지 않는다. register-time model probe는 agent가 만든 artifact, 예를 들어 session transcript를 읽어야 한다. provider나 agent CLI마다 transcript 위치와 shape가 다르므로 이 설계는 특정 vendor API를 전제하지 않고, 파일 artifact를 읽을 수 없을 때는 unavailable 또는 undecidable을 기록한다.
## 문제 해결 신호
| 증상 | 확인할 것 | 처리 |
| --- | --- | --- |
| `MODEL-PROBE INFO ... nothing asserted` | `--expect` 또는 `MODEL_IDENTITY_EXPECT` 누락 | 기대 모델을 명시해 assertion으로 실행 |
| `MODEL-PROBE DRIFT: ` | assistant model turn을 읽지 못함 | transcript path와 event shape 확인 |
| `model-drift-audit: FAIL. zero assistant turns` | transcript는 있으나 assistant turn 없음 | 올바른 session file인지 재확인 |
| `no real model observed` | 모든 assistant turn이 `` 또는 `` | clean으로 처리하지 말고 다른 artifact로 확인 |
| dispatch 출력의 `model=unavailable` | worker-scoped transcript glob 없음 | 수동 확인하거나 검증된 `--transcript-glob` 제공 |
| ledger warning `MODEL_PROBE_FAILED` | model probe command 실패 또는 빈 출력 | probe command가 exit `0`이고 실제 model id를 stdout에 출력하는지 확인 |
## Related pages
`check -> dispatch -> register` 흐름과 worker contract, completion channel 검증을 함께 봅니다.
model verification이 다른 guard와 어떤 증거 강도로 연결되는지 확인합니다.
공개 scripts surface, option, exit code 차이를 빠르게 대조합니다.
model probe undecidable, register warning, transcript 위치 문제를 증상별로 확인합니다.
---
## 16. Redaction 게이트
> `redaction-scan.sh`, `redaction-inventory`, 조직 규칙 파일, commit message scan, pre-push hook, release gate의 범위와 exit code를 정리합니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/16-redaction.md
- Generated: 2026-08-10T07:43:37.604Z
### Source Files
- `local-mogui-ade-orchestrator:scripts/redaction-scan.sh`
- `local-mogui-ade-orchestrator:scripts/redaction-inventory`
- `local-mogui-ade-orchestrator:hooks/pre-push`
- `local-mogui-ade-orchestrator:config/gitleaks.toml`
- `local-mogui-ade-orchestrator:tests/test_redaction_scan_commit_messages.py`
- `local-mogui-ade-orchestrator:tests/test_redaction_inventory.py`
---
title: "Redaction 게이트"
description: "`redaction-scan.sh`, `redaction-inventory`, 조직 규칙 파일, commit message scan, pre-push hook, release gate의 범위와 exit code를 정리합니다."
---
`redaction-scan.sh`는 `gitleaks`를 매칭 엔진으로 사용하되, 저장소가 실제로 내보내는 tracked content, staged index, git range, commit message 범위를 명시적으로 고정하고 결과 줄에 범위를 출력하는 fail-closed 래퍼다. 조직 고유 식별자 규칙은 저장소에 커밋하지 않고 `REDACTION_EXTRA_PATTERNS`가 가리키는 로컬 파일에서 읽으며, release gate는 `redaction-scan.sh`와 `redaction-inventory`를 함께 실행해 “탐지된 비밀”과 “규칙이 덮지 못하는 후보”를 분리한다.
## 실행 표면
| 명령 | 스캔 범위 | commit message | 기본 결과 의미 |
| --- | --- | --- | --- |
| `scripts/redaction-scan.sh` | `git ls-files`의 tracked 파일 | `not-scanned` | tracked 파일에서 finding 없음 |
| `scripts/redaction-scan.sh --staged` | index에 staged 된 `ACMR` 파일 | `not-scanned` | staged 파일에서 finding 없음 |
| `scripts/redaction-scan.sh --range A..B` | `git diff --name-only --diff-filter=ACMR A..B` | 자동 스캔 | range의 파일 변경과 해당 commit message를 함께 검사 |
| `scripts/redaction-scan.sh --commit-messages A..B` | 현재 파일 모드와 별개 | 명시 스캔 | 지정 range의 commit message를 추가 검사 |
| `scripts/redaction-inventory` | 현재 commit의 tracked 텍스트 파일과 파일명 | 해당 없음 | 규칙이 덮지 못하는 후보 토큰을 보고 |
`redaction-scan.sh`의 clean 출력은 항상 `mode`, `files`, `commit-messages`, `org-rules`를 포함한다. `commit-messages=not-scanned` 또는 `org-rules=0`은 실패가 아닐 수 있지만, 전체 감사가 아니라는 사실을 그대로 드러내는 신호다.
## `redaction-scan.sh`
`redaction-scan.sh`는 다음 조건에서 실행을 시작하지 않고 exit `2`를 반환한다.
| 조건 | exit code | 의미 |
| --- | ---: | --- |
| `gitleaks`가 `PATH`에 없음 | `2` | 매칭 엔진 부재로 판단 불가 |
| `config/gitleaks.toml` 없음 | `2` | 기본 규칙 부재 |
| 알 수 없는 인자 또는 잘못된 range 인자 | `2` | 사용법 오류 |
| `--range` 또는 `--commit-messages` range가 현재 저장소에서 resolve 불가 | `2` | 빈 스캔으로 오인하지 않도록 차단 |
| retired `scripts/redaction-allowlist.txt`에 실질 entry 존재 | `2` | 이전 allowlist 형식을 조용히 무시하지 않음 |
| `--require-extra` 또는 `REDACTION_REQUIRE_EXTRA=1`인데 조직 규칙이 없음 | `2` | generic rule만으로 publish 판단 금지 |
| finding 존재 | `1` | 수정 또는 gitleaks exemption 필요 |
| finding 없음 | `0` | 실행된 범위 안에서 finding 없음 |
finding 출력은 matched value를 그대로 노출하지 않도록 AWS key, GitHub token, Slack token, `sk-`, `sk-ant-`, `Bearer`, assignment secret 형태를 masking한다. exemption은 retired allowlist가 아니라 `.gitleaksignore` fingerprint 또는 `config/gitleaks.toml`의 allowlist로 처리한다.
### 기본 gitleaks config
`config/gitleaks.toml`은 gitleaks default rule set을 확장하고, 저장소가 추가로 막아야 하는 generic class를 담는다.
| rule id | 탐지 class |
| --- | --- |
| `private_key` | PEM 또는 OpenSSH private key header |
| `aws_access_key` | AWS access key id |
| `github_token` | GitHub token prefix |
| `slack_token` | Slack API token |
| `openai_sk`, `anthropic_key` | OpenAI/Anthropic 형태 secret key |
| `bearer_token` | 긴 bearer credential literal |
| `assignment_secret`, `dotenv_export` | 코드 또는 shell export의 secret assignment |
| `home_path` | `/Users/` 형태의 로컬 사용자 경로 |
| `internal_ip` | RFC1918 private IP |
| `jira_hf` | `HF-` 내부 ticket identifier |
| `slack_url` | Slack workspace/archive URL |
| `internal_host` | `.internal`, `.corp`, `.local` hostname |
placeholder, test secret, synthetic home path, scanner/config 파일 자체, bytecode, `.orca/` 같은 build/runtime 산출물은 config allowlist로 제외된다.
## 조직 규칙 파일
조직 고유 회사명, 제품명, 개인명, handle은 public repository에 커밋하지 않는다. 로컬 파일을 `REDACTION_EXTRA_PATTERNS`로 지정한다.
```bash
export REDACTION_EXTRA_PATTERNS="$HOME/.config/redaction-extra.txt"
export REDACTION_REQUIRE_EXTRA=1
scripts/redaction-scan.sh
```
규칙 파일 형식은 한 줄에 하나의 rule이다.
```text
id|description|regex
```
처리 규칙은 다음과 같다.
| 항목 | 동작 |
| --- | --- |
| 빈 줄, `#` comment | 무시 |
| separator | 처음 두 개의 `|`만 field separator로 사용하므로 regex 안의 `|`는 허용 |
| Python `re` compile 실패 | unusable line으로 count하고 skip |
| gitleaks RE2 compile 실패 | merged config canary 실패로 exit `2` |
| rule id 출력 | engine 실패 시 id만 출력하고 regex 본문은 출력하지 않음 |
| native script 부재 | 조직 규칙이 로드됐지만 비 ASCII literal이 없으면 native spelling 누락 가능성을 warning |
`org-rules=0`인 clean scan은 generic pattern만 통과했다는 뜻이다. 공개 push, release, owner review 직전에는 `REDACTION_REQUIRE_EXTRA=1` 또는 `--require-extra`를 사용해 조직 규칙 부재를 exit `2`로 승격한다.
## commit message scan
`gitleaks dir`는 commit message를 읽지 않는다. `redaction-scan.sh`는 range 모드에서 `git log --format=%H A..B`로 commit을 순회하고, 각 commit message를 `gitleaks stdin`으로 별도 검사한다. message finding은 파일명 대신 `commit:` label로 보고된다.
```bash
# 파일 변경과 commit message를 함께 검사
scripts/redaction-scan.sh --range origin/main..HEAD
# 파일 모드는 유지하고 message만 추가 검사
scripts/redaction-scan.sh --commit-messages origin/main..HEAD
```
`--commit-messages`는 range 인자가 없으면 exit `2`다. clean range scan은 `commit-messages=`를 출력하므로 “message를 검사하지 않은 clean”과 “message까지 검사한 clean”을 구분할 수 있다.
## pre-push hook
저장소에는 opt-in `hooks/pre-push`가 있다. clone마다 다음 설정으로 활성화한다.
```bash
git config core.hooksPath hooks
```
hook은 git이 stdin으로 전달하는 ` ` 행을 읽고, push되는 ref마다 스캔 범위를 만든다.
| push 형태 | hook 동작 |
| --- | --- |
| remote ref 삭제 | 스캔할 내용이 없으므로 skip |
| 기존 remote ref 업데이트 | `remote_sha..local_sha` range scan |
| 새 ref | `origin/main`과 merge-base를 찾아 `base..local_sha` range scan |
| remote tip object가 로컬에 없음 | `origin/main` merge-base로 fallback |
| usable range가 하나도 없음 | tracked tree scan으로 fallback |
hook은 caller environment를 그대로 사용한다. 즉 `REDACTION_EXTRA_PATTERNS`와 `REDACTION_REQUIRE_EXTRA`를 설정한 checkout에서는 조직 규칙까지 강제하고, 설정하지 않은 public contributor checkout에서는 generic rule scan으로 동작한다.
## `redaction-inventory`
`redaction-inventory`는 scan의 반대 질문을 다룬다. “규칙이 이름 붙인 패턴”을 찾는 대신, 현재 tracked tree에 있는 후보 token 중 어떤 것이 로컬 조직 규칙으로 덮이지 않는지 보고한다.
```bash
REDACTION_EXTRA_PATTERNS="$HOME/.config/redaction-extra.txt" scripts/redaction-inventory
scripts/redaction-inventory --baseline .redaction-inventory-baseline
scripts/redaction-inventory --min-count 2
scripts/redaction-inventory --json
```
| 후보 bucket | 수집 기준 |
| --- | --- |
| `kebab` | kebab-case repository/product/organization 형태 token |
| `word_in_korean` | 한글 주변 40자 안의 Latin word |
| `home_user` | `/Users/`에서 추출한 user name |
| `email_domain` | email address의 domain |
binary 파일은 첫 8KB 안의 NUL byte로 제외한다. tracked 파일 본문뿐 아니라 tracked 파일명도 후보 harvest에 포함한다. baseline 파일에 들어 있는 token은 검토된 후보로 간주해 출력하지 않는다.
### inventory exit code
| exit code | 의미 | release gate 처리 |
| ---: | --- | --- |
| `0` | uncovered candidate 없음 | 통과 |
| `1` | uncovered candidate 있음 | 정상 triage 상태. candidate는 secret 판정이 아니며 검토 대상 |
| `2` | 판단 불가 | release 차단 |
exit `2` 사례는 `REDACTION_EXTRA_PATTERNS` 미설정, usable rule 없음, git repository 아님, tracked file 없음이다. JSON 출력은 `rules`, `rules_unusable`, `rules_considered`, `tracked_files`, `baseline`, `uncovered_total`, `uncovered`를 포함한다.
## release gate
release runbook은 새 파일이 scanner에 보이도록 먼저 `git add -A`를 요구한다. 그 뒤 테스트, tool naming gate, redaction scan, inventory를 순서대로 실행한다.
```bash
set -e
PYTHONPATH=src uv run pytest tests -q
bash master-ops/scripts/test-tool-naming.sh
./scripts/redaction-scan.sh
rc=0
./scripts/redaction-inventory || rc=$?
if [ "$rc" -ne 0 ]; then [ "$rc" -eq 1 ] || exit "$rc"; fi
```
이 release gate에서 `redaction-scan.sh`의 exit `1`은 `set -e` 때문에 즉시 차단된다. `redaction-inventory`의 exit `1`은 “후보가 있다”는 triage 상태로 허용되지만, exit `2`는 판단 불가이므로 release cut을 막는다.
`master-ops/scripts/pr-steward-status`가 제시하는 PR 검증 명령은 더 엄격하게 다음 두 gate를 조직 규칙 필수 모드로 실행한다.
```bash
REDACTION_REQUIRE_EXTRA=1 REDACTION_EXTRA_PATTERNS=~/.config/redaction-extra.txt ./scripts/redaction-scan.sh
REDACTION_REQUIRE_EXTRA=1 REDACTION_EXTRA_PATTERNS=~/.config/redaction-extra.txt ./scripts/redaction-inventory
```
## 범위 밖 표면
repository gate는 repository content와 commit message를 읽는다. 다음 표면은 파일 tree에 없으므로 `redaction-scan.sh`가 보지 않는다.
| 표면 | 담당 guard |
| --- | --- |
| PR body | `master-ops/scripts/pr-body-check`의 body redaction scan |
| PR comment, review body, issue body | `master-ops/scripts/conversation-redaction-scan` |
| release note 초안, forge web UI 입력 | 게시 전 별도 grep 또는 conversation-surface scan |
| 이미 push된 과거 history 전체 | 선택한 range 밖은 보지 않음. history rewrite 검증은 별도 절차 |
`conversation-redaction-scan`은 GitHub `gh` CLI를 사용해 PR body, PR comment, review body, issue body를 가져오고 absolute home path class를 matched value 없이 `surface|number|author|locator|pattern_class`로 출력한다. 이 guard는 repository redaction gate를 대체하지 않고, repository gate가 구조적으로 읽을 수 없는 forge 대화 표면을 보완한다.
## 운영 체크
`~/.config/redaction-extra.txt` 같은 version control 밖 경로에 `id|description|regex` 형식의 조직 규칙을 둔다. rule 본문은 scanner 출력이나 문서에 붙이지 않는다.
clone마다 `git config core.hooksPath hooks`를 설정한다. 조직 규칙이 필요한 host는 shell profile 또는 작업 세션에서 `REDACTION_EXTRA_PATTERNS`와 `REDACTION_REQUIRE_EXTRA=1`을 함께 설정한다.
새 파일을 `git add -A`로 tracked/staged 상태에 올린 뒤 release runbook의 gate 명령을 실행한다. `redaction-scan.sh` exit `1` 또는 `2`, `redaction-inventory` exit `2`는 release 차단으로 처리한다.
`redaction-inventory` exit `1`은 즉시 secret 판정이 아니다. 실제 조직 식별자는 규칙으로 추가하고, 의도적으로 허용된 token은 baseline에 기록한다.
## Related pages
Redaction scan과 inventory가 어떤 failure mode를 막는지 다른 runtime guard와 함께 비교한다.
`redaction-scan.sh`, `redaction-inventory`, preflight, release 관련 command surface와 exit code를 빠르게 확인한다.
릴리스 전 테스트, redaction gate, changelog, tag owner approval 흐름을 함께 실행한다.
`redaction cannot decide`, missing `gitleaks`, 조직 규칙 부재, range resolve 실패를 증상별로 처리한다.
---
## 17. 문제 해결
> preflight BLOCKED, Orca CLI 미등록, misplacement, duplicate master, Unavailable worktree, model probe undecidable, redaction cannot decide를 증상별로 다룹니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/17-page-17.md
- Generated: 2026-08-10T07:41:21.657Z
### Source Files
- `local-mogui-ade-orchestrator:docs/public/getting-started.md`
- `local-mogui-ade-orchestrator:docs/public/orca-concepts.md`
- `local-mogui-ade-orchestrator:docs/public/master-lifecycle.md`
- `local-mogui-ade-orchestrator:docs/public/defense-inventory.md`
- `local-master-ops:docs/runbooks/orca-wait.md`
- `local-master-ops:docs/runbooks/error-and-logging.md`
- `local-master-ops:docs/blame/BLAME-2026-08-04-succession-misseat.md`
---
title: "문제 해결"
description: "preflight BLOCKED, Orca CLI 미등록, misplacement, duplicate master, Unavailable worktree, model probe undecidable, redaction cannot decide를 증상별로 다룹니다."
---
`scripts/onboarding-preflight.sh`, `scripts/master-succeed`, `scripts/model-identity-probe`, `scripts/model-drift-audit`, `scripts/redaction-scan.sh`는 성공 여부를 추론하지 않고 측정값과 exit code로 분리한다. 문제 해결의 기본 순서는 증상 문자열을 먼저 확인하고, 해당 스크립트가 요구하는 입력을 다시 측정한 뒤, 실패가 배치·모델·redaction 범위 중 어느 계층에서 난 것인지 좁히는 것이다.
## 빠른 판별표
| 증상 | 먼저 볼 신호 | 정상 해석 | 다음 조치 |
| --- | --- | --- | --- |
| `Preflight summary` 아래 `BLOCKED` | `FAIL` 행과 essential block | 필수 체크가 만족되지 않음 | 각 `FAIL`을 고치고 preflight 재실행 |
| Orca CLI 미등록 | `orca is not available`, `orca status --json failed` | 앱은 있어도 shell command가 없음 | Orca 설정에서 CLI shell command 활성화 |
| misplacement | master가 제품 repo worktree 아래에 보임 | multi-repo master seat가 아님 | 새 founding 금지, selector와 seat 재측정 |
| duplicate master | 같은 workspace에 master 세션 2개 | 런타임 사고 | `check-duplicates` 결과를 기준으로 정리 |
| `Unavailable worktree` | folder workspace master | 보통 정상 | `worktreeId`가 `folder:`인지 확인 |
| model probe undecidable | probe/audit exit `2` | 검증 불가 또는 drift 계열 | 통과로 읽지 말고 transcript 설정 또는 succession 검토 |
| redaction cannot decide | redaction exit `2` | scan 범위가 확정되지 않음 | `gitleaks`, org rules, allowlist, usage를 고침 |
exit `2`는 “깨끗함”이 아니다. 이 런타임에서 `2`는 주로 `cannot decide`, `undecidable`, usage/runtime error를 뜻한다.
## preflight가 `BLOCKED`로 끝남
`BLOCKED`는 `scripts/onboarding-preflight.sh`가 하나 이상의 required check를 `FAIL`로 판정했다는 뜻이다. WARN만 있으면 exit 1로 막지 않지만, essential component는 요약에서 다시 출력된다.
```bash
ORCA_AGENT_CLI="" bash scripts/onboarding-preflight.sh
```
확인 순서:
`PASS`, `WARN`, `FAIL`, `WAIVED`가 라벨별로 출력된다. `BLOCKED`가 있으면 `FAIL` 라벨이 원인이다.
`orca`, `orchestration`, `skills`, `agent-cli`, `worker-runtime`, `bd`, `python3`, `git`, `gh`, `redaction-extra` 같은 라벨은 later spawn과 dispatch의 실제 전제다.
`PREFLIGHT_WAIVE=`은 해당 check를 `WAIVED`로 낮춘다. 이 값은 결핍을 해결하지 않고, 받아들인 동작을 출력에 남긴다.
```bash
PREFLIGHT_WAIVE=ctx ORCA_AGENT_CLI=claude bash scripts/onboarding-preflight.sh
```
`orchestration` 실패는 단순 reachability 문제가 아닐 수 있다. `legacy_read_only`, `run_required`, `run:null` 계열 메시지가 나오면 `orca orchestration run-create`로 현재 terminal에 non-legacy Run을 다시 묶고 preflight를 재실행한다.
## Orca CLI가 등록되지 않음
preflight의 Orca 해석 순서는 `ORCA_CLI_COMMAND`, `ORCA_DEV_REPO_ROOT`, 기본 `orca`다. 지원 basename은 `orca`, `orca-dev`, `orca-ide`다.
```bash
command -v orca
orca status --json
```
실패 메시지가 `follow-up: enable Settings > Orca CLI > Shell command`를 가리키면 Orca 앱의 CLI launcher가 shell에 노출되지 않은 상태다. 앱을 열고 **Settings → Orca CLI → Shell command**를 켠 뒤 다시 측정한다.
macOS에서 설치 자체가 없으면 preflight는 Homebrew cask 경로를 안내한다.
```bash
brew install --cask stablyai/orca/orca
```
Linux와 Windows는 공식 다운로드 경로를 사용한다. 설치 후에도 성공 기준은 동일하다: `command -v orca`와 `orca status --json`의 `ok:true`.
## misplacement: master가 잘못된 자리에 앉음
multi-repository workspace에서 master seat는 workspace root의 folder workspace다. 제품 저장소나 ops 저장소의 repository worktree에 앉은 master는 cwd가 맞아 보여도 misplacement다.
정상 selector 형태:
```text
id:folder:
```
repository worktree selector는 worker seat에 사용한다.
```text
id:::
```
피해야 할 패턴:
| 입력 | 문제 |
| --- | --- |
| `path:/abs/dir` | Orca가 내부 id로 resolve해도 spawn placement 비교에서 mismatch가 날 수 있음 |
| bare `folder:` | 일부 subcommand에서는 통과하고 일부 list 계열에서는 거부되는 비대칭이 있음 |
| ops repo worktree fallback | workspace master가 owner sidebar와 lineage seat 밖으로 이동함 |
승계나 founding spawn 직후에는 생존만 보지 말고 placement evidence를 본다.
```bash
orca terminal list --worktree "id:folder:" --json
scripts/master-succeed spawn \
--workspace-selector "id:folder:" \
--expected-placement "id:folder:" \
--kickoff-text "Founding master boot" \
--root . \
--model "" \
--title "Founding master boot" \
--json
```
`SPAWN_PLACEMENT_MISMATCH` 또는 exit `26`은 fail-closed다. 새 terminal을 계속 진행하지 말고 selector, expected placement, workspace root 등록 상태를 다시 확인한다.
## duplicate master
duplicate master는 reverify 대신 founding을 다시 돌리거나, succession/resume 뒤 이전 master가 살아 있을 때 생긴다. 기존 ops repository와 lineage가 있으면 Founding으로 다시 들어가지 않는다.
```bash
scripts/master-succeed check-duplicates \
--session-marker "" \
--self-handle "" \
--json
```
결과가 비어 있지 않으면 soft warning이 아니라 finding이다. 현재 master를 기준으로 predecessor 또는 revived session을 분류하고, retirement 절차는 pane close만으로 끝내지 않는다. 완전 종료는 process, host pane, tty의 소멸을 각각 측정해야 한다.
duplicate가 의심될 때 새 master를 하나 더 만들지 않는다. 먼저 live terminal 목록, lineage session id, role-state를 대조한다.
## `Unavailable worktree`
folder workspace에 앉은 master는 Git worktree가 아니므로 Orca UI나 session history에서 `Unavailable worktree`처럼 보일 수 있다. 이 자체는 crash가 아니다.
정상 확인 기준은 path가 아니라 `worktreeId`다.
```bash
orca terminal list --json
```
folder workspace master의 전형적 신호:
```json
{
"worktreeId": "folder:",
"worktreePath": ""
}
```
multi-repo workspace에서 이 상태는 master seat와 맞다. 반대로 master가 특정 제품 repository의 worktree 아래에 보이면 `Unavailable worktree`가 없더라도 misplacement일 수 있다.
## model probe undecidable
`model-identity-probe`는 최근 assistant turn의 model field를 본다. `--transcript`가 없으면 `MOGUI_TRANSCRIPT_GLOB` 또는 `config/instance-runtime.json`의 `transcript_globs.`로 newest match를 찾는다.
```bash
scripts/model-identity-probe \
--transcript ./sessions/example.jsonl \
--expect ""
```
출력 해석:
| 출력 | exit | 의미 |
| --- | --- | --- |
| `MODEL-PROBE OK ...` | `0` | 최근 sample이 기대 model과 일치 |
| `MODEL-PROBE INFO ... nothing asserted` | `0` | 기대값이 없어 측정만 했고 검증 주장은 없음 |
| `MODEL-PROBE DRIFT: ...` | `2` | mismatch, unreadable, unconfigured, invalid limit 등으로 통과 판정 불가 |
중간 drift는 최근 sample만으로 놓칠 수 있다. succession audit이나 session close에서는 전체 transcript를 걷는 audit을 사용한다.
```bash
scripts/model-drift-audit \
--transcript ./sessions/example.jsonl \
--expect ""
```
`model-drift-audit`의 exit code는 `0` no transition, `1` transition 또는 expectation mismatch, `2` undecidable이다. `2`는 transcript 없음, unreadable, assistant turn 없음, real model 미관측 같은 상태다.
## redaction cannot decide
`scripts/redaction-scan.sh`는 gitleaks를 engine으로 사용하고, repository content와 선택된 commit message 범위를 스캔한다. exit code는 `0` clean, `1` findings, `2` cannot decide다.
```bash
scripts/redaction-scan.sh
scripts/redaction-scan.sh --staged
scripts/redaction-scan.sh --range "$remote_sha..$local_sha"
scripts/redaction-scan.sh --commit-messages "$remote_sha..$local_sha"
```
`cannot decide`의 대표 원인:
| 원인 | 신호 | 조치 |
| --- | --- | --- |
| `gitleaks` 없음 | `gitleaks is not on PATH` | `gitleaks` 설치 후 재실행 |
| base config 없음 | `missing config/gitleaks.toml` | checkout과 repo root 확인 |
| organization rules 없음 | `required organization rules were not loaded` | `REDACTION_EXTRA_PATTERNS` 파일 지정 |
| retired allowlist 존재 | `redaction-allowlist.txt has entries in the retired format` | `.gitleaksignore` fingerprint 또는 `config/gitleaks.toml` allowlist로 이전 |
| range 오류 | `--range requires A..B`, `range does not resolve` | push range 또는 commit range 수정 |
| RE2 미지원 regex | `merged config crashes the engine` | 해당 rule id의 regex를 RE2 호환으로 수정 |
organization-specific rule 파일 형식:
```text
id|description|regex
```
public release나 push 전에는 generic-only green을 허용하지 않도록 강제한다.
```bash
REDACTION_REQUIRE_EXTRA=1 \
REDACTION_EXTRA_PATTERNS=~/.config/redaction-extra.txt \
scripts/redaction-scan.sh --range "$remote_sha..$local_sha"
```
정상 green은 scope를 포함한다.
```text
redaction-scan: OK — 0 findings (mode=tracked, files=144, commit-messages=not-scanned, org-rules=10)
```
`org-rules=0`인 green은 organization identifier까지 검증했다는 뜻이 아니다.
## 관련 페이지
preflight가 측정하는 도구, redaction rules, Orca CLI 등록 전제.
Project, folder workspace, worktree, terminal, selector 형식과 misplacement 조건.
placement, duplicate master, model verification, redaction gate의 fail-closed 표면.
model probe, drift audit, undecidable 상태, transcript glob 설정.
repository scan, organization rules, commit message scan, exit code 기준.
---
## 18. CLI 참조
> 공개 `scripts/` 명령, subcommand, 주요 option, exit code 차이, 문서 표와 실제 실행 파일 surface를 검증하는 테스트를 정리합니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/18-cli.md
- Generated: 2026-08-10T07:43:39.420Z
### Source Files
- `local-mogui-ade-orchestrator:docs/public/reference.md`
- `local-mogui-ade-orchestrator:scripts/dispatch-gate`
- `local-mogui-ade-orchestrator:scripts/master-succeed`
- `local-mogui-ade-orchestrator:scripts/master-bootstrap-live`
- `local-mogui-ade-orchestrator:scripts/workspace-descriptor-check`
- `local-mogui-ade-orchestrator:tests/test_reference_command_table.py`
---
title: "CLI 참조"
description: "공개 `scripts/` 명령, subcommand, 주요 option, exit code 차이, 문서 표와 실제 실행 파일 surface를 검증하는 테스트를 정리합니다."
---
`local-mogui-ade-orchestrator`의 공개 CLI surface는 실행 가능한 `scripts/` 파일과 `docs/public/reference.md`의 명령 표로 관리된다. 표는 자동 생성물이 아니며, `tests/test_reference_command_table.py`가 각 실행 파일의 `--help` 출력에서 subcommand 집합을 측정해 문서 row와 비교한다. `local-master-ops`는 설치된 ops 레이어용 래퍼와 운영 가드를 별도로 노출하며, 일부 스크립트는 placeholder 치환 후 실제 ops 저장소에서 실행되는 형태다.
## 저장소별 실행 위치
| 저장소 | 용도 | 대표 실행 경로 |
| --- | --- | --- |
| `local-mogui-ade-orchestrator` | 런타임 코어, bootstrap, succession, dispatch gate, redaction, model audit | `local-mogui-ade-orchestrator:scripts/` |
| `local-master-ops` | 설치된 ops 레이어, 작업자 dispatch 래퍼, Orca 대기/스윕, 템플릿 적용/검사, PR/대화면 가드 | `local-master-ops:scripts/` |
두 저장소의 `scripts/`는 같은 역할이 아니다. `local-mogui-ade-orchestrator:scripts/dispatch-gate`는 gate 판정 엔진이고, `local-master-ops:scripts/dispatch`는 gate, Orca task 생성, terminal dispatch, register probe를 묶는 ops-side 래퍼다.
## 런타임 저장소 CLI
### Acceptance loop
| 명령 | 주요 option | 성공/실패 의미 |
| --- | --- | --- |
| `acceptance-loop validate` | `--config` | suite 구조를 JSON 요약으로 출력한다. 설정 오류는 `2`다. |
| `acceptance-loop split` | `--config`, `--output-dir` | train/holdout 분리 manifest를 쓴다. |
| `acceptance-loop run` | `--config`, `--max-iterations`, `--baseline-ref`, `--restore-cmd` | 최종 score가 complete이면 `0`, incomplete이면 `1`, 잘못된 입력은 `2`다. |
| `acceptance-loop inspect` | `--run-dir` | 기존 run report를 출력한다. report가 없으면 `2`다. |
```bash
local-mogui-ade-orchestrator/scripts/acceptance-loop validate --config path/to/suite.json
local-mogui-ade-orchestrator/scripts/acceptance-loop run --config path/to/suite.json --max-iterations 3
```
### Dispatch gate
| 명령 | 주요 option | 출력/exit |
| --- | --- | --- |
| `dispatch-gate check` | 전역 `--ledger`; `--runtime`, `--model`, `--tier-policy`, `--tier-override`, `--no-record`, `--contract`, `--agents`, `--est-chars`, `--completion-channel` | JSON decision을 출력한다. allow면 `0`, deny면 `2`다. |
| `dispatch-gate register` | `--job-id`, `--probe-cmd`, `--contract-sha`, `--runtime`, `--orchestration-task`, `--tier-policy`, `--declared-model`, `--model-probe-cmd` | probe가 job id를 확인하고 orchestration completion channel이 검증되면 allow. 실패는 `2`다. |
| `dispatch-gate watch` | `--log`, `--max-idle` | log 상태 JSON을 출력한다. 정상 `0`, log missing `2`, stalled `3`이다. |
| `dispatch-gate report` | `--today` | ledger의 모델, denial, tier, policy, override 통계를 출력한다. ledger를 읽을 수 없으면 `2`다. |
`check`에서 `--completion-channel`이 있고 `--est-chars`가 없으면 contract 파일 길이를 추정값으로 사용한다. completion channel이 없으면 추정값을 `0`으로 두고 별도 gate 판정에 맡긴다.
### Master bootstrap, recovery, succession
| 명령 | 주요 option | 동작 |
| --- | --- | --- |
| `master-bootstrap` | `--charter`, `--handoff`, `--budget`, `--session-id`, `--strict-lease`, `--json` | charter/handoff 기반 bootstrap payload를 만든다. `BootstrapError`는 `2`다. |
| `master-bootstrap-live` | `--handoff-dir`, `--role-state-file`, `--budget`, `--bd`, `--charter-pointer` | SessionStart hook용 live bootstrap block을 출력한다. 내부 오류도 `[BOOTSTRAP-FALLBACK]`로 줄이고 항상 `0`을 반환한다. |
| `master-recover` | `--charter`, `--handoff`, `--ledger`, 반복 `--repo`, 반복 `--monitor-pattern`, `--session-id`, `--json` | recovery step report를 출력한다. |
| `master-succeed detect` | `text`, `--context-ratio`, `--json` | succession trigger를 분류한다. |
| `master-succeed handoff` | `--spec`, `--json` | JSON spec에서 thin handoff를 만든다. |
| `master-succeed verify-successor` | `--report`, `--json` | successor recovery report를 검증한다. |
| `master-succeed check-duplicates` | `--self-handle`, `--marker`, `--json` | 중복 master marker를 탐지한다. |
| `master-succeed retire` | `--self-handle`, `--expected`, `--target-handle`, `--target-pty-id`, `--target-session-id`, `--target-pid`, `--target-tty`, `--execute`, `--json` | predecessor terminal/session을 dry-run 또는 실제 close한다. |
| `master-succeed spawn` | `--workspace-selector`, `--expected-placement`, `--kickoff-text` 또는 `--kickoff-file`, `--root`, `--model`, `--agent`, `--title`, `--dry-run`, `--json` | successor terminal을 생성하거나 dry-run한다. agent별 기본 model이 없으면 `--model`이 필수다. placement mismatch는 fail-closed 계열 오류다. |
### 모델 식별과 drift 감사
| 명령 | 주요 option | exit code |
| --- | --- | --- |
| `model-identity-probe` | `--transcript`, `--runtime`, `--config`, `--expect`, `--limit` | 기대 model이 없으면 정보 출력 후 `0`이고 아무 것도 assert하지 않는다. 기대 model과 최근 assistant turn이 모두 맞으면 `0`, drift/undecidable/설정 불가면 `2`다. |
| `model-drift-audit` | `--transcript`, `--session`, `--projects-dir`, `--workspace-dir`, `--expect`, `--ignore-synthetic`, `--json` | 단일 real model이면 `0`, transition 또는 기대값 mismatch면 `1`, transcript 없음/zero assistant turn/all synthetic이면 `2`다. |
`model-identity-probe`는 최근 tail sample을 본다. `model-drift-audit`는 세션 전체 assistant turn을 순회하므로 중간 model 전환을 잡는 용도다.
### 설정, redaction, template support
| 명령 | 주요 option | exit code |
| --- | --- | --- |
| `workspace-descriptor-check` | `--path`, `--action`, `--config`, `--allow-unknown-repo`, `--json` | 허용 `0`, 금지 `1`, descriptor 미설정/invalid `2`다. config 해석은 명시 `--config`가 env보다 우선한다. |
| `redaction-scan.sh` | `--staged`, `--range A..B`, `--commit-messages A..B`, `--require-extra`, `--help` | clean `0`, findings `1`, missing tool/필수 rule 없음/usage/판단 불가 `2`다. |
| `redaction-inventory` | `--baseline`, `--min-count`, `--json` | uncovered 없음 `0`, uncovered 후보 있음 `1`, pattern file 없음 또는 git repo 아님 `2`다. |
| `generate-manifest` | `--skeleton`, `--out`, `--check`, `--stdout` | manifest 생성 또는 drift 검사. `--check`에서 stale이면 `1`, skeleton 미존재 등은 `2`다. |
| `codex-worker-pretrust` | worktree path, `--accounts-dir` | Codex 계정 설정에 worktree trust를 기록한다. TOML-capable interpreter가 없으면 skip을 출력하고 config를 건드리지 않는다. |
| `cursor-worker-pretrust` | worktree path, `--projects-dir` | Cursor Agent trust marker를 기록한다. JSON interpreter 검증 실패 시 marker를 쓰지 않는다. |
| `adapter doctor` | 없음 | adapter tool 존재 여부와 probe command를 JSON으로 출력한다. |
| `l1-digest tick` | `--config` | L1 digest 관찰 tick을 실행한다. |
| `next-version` | 없음 | 현재 release version 산출값을 출력한다. |
| `onboarding-preflight.sh` | `--fix`, env `PREFLIGHT_WAIVE` | onboarding 필수 도구를 측정한다. ready `0`, blocked `1`이다. |
| `worker-reap` | `--task-id` 또는 `--dispatch-id`, `--ledger`, `--dry-run`, `--json` | 성공 `0`; 누락 인자 `2`, dispatch 미종료 `3`, parse error `4`, 기타 실패 `1`이다. |
## Ops 저장소 CLI
### 작업자 dispatch와 Orca 운영
| 명령 | 주요 option | 동작 |
| --- | --- | --- |
| `dispatch` | `--contract`, `--spec`, `--terminal` 또는 `--worktree`, `--model`, `--runtime`, `--same-host-reason`, `--top-approved`, `--tier-policy`, `--est-chars`, `--transcript-glob`, `--check-only` | ops-side one-command dispatch 래퍼다. gate check, task create, terminal create/dispatch, register를 연결한다. |
| `orca-wait` | `--once`, `--timeout-ms`, `--types` | unread backlog를 ack-chain으로 drain한 뒤 `orca orchestration check`를 block wait한다. `orca`가 없으면 `127`이다. |
| `worker-pane-sweep` | 없음 | live Orca pane을 `working`, `idle`, `approval`, `start-screen`, `update`, `limit`, `shell`, `unknown`으로 분류한다. 조치가 필요한 pane이 있으면 non-zero다. |
| `dispatch-collision-check` | script 내부 parser | dispatch 중 terminal/worktree collision을 확인하는 보조 가드다. |
| `pr-steward-status` | PR 관련 인자 | PR steward 상태 확인용 래퍼다. |
`dispatch`는 master host runtime을 `MOGUI_MASTER_HOST_RUNTIME`, instance runtime config, fallback 순서로 해석한다. worker transcript glob은 runtime별로 다르며, `claude`는 worktree path에서 per-worker glob을 유도하고 다른 runtime은 불확실한 glob을 추정하지 않는다.
### 측정과 검증 보조 명령
| 명령 | 주요 option | 동작 |
| --- | --- | --- |
| `measure` | ` [args...]` | 실행한 명령의 `exit=`를 첫 줄에 출력하고, 비어 있는 출력은 `(no output)`으로 표시한다. exit status는 원래 명령과 같다. 인자 없음은 `2`, `--help`는 `0`이다. |
| `spawn-test` | `[SCENARIO]`, env `SPAWN_TEST_RUNTIMES`, `SPAWN_TEST_BLOCKED`, `SPAWN_TEST_COORDINATOR_TERMINAL`, `SPAWN_TEST_COORDINATOR_RUN` | fresh install E2E harness다. `claude`와 `codex`는 must-pass floor이고, 실패 sandbox는 보존한다. |
| `harness-selfcheck.sh` | 없음 | harness 자체 점검용 shell script다. |
| `orca-surface-check.sh` | 없음 | Orca CLI surface drift를 확인한다. unchanged `0`, drift `1`, unmeasurable `2`다. |
| `compaction-probe.sh` | 없음 | compaction 관련 probe를 실행한다. |
| `hook-coverage-report` | 없음 | hook coverage report를 생성한다. |
### 템플릿 적용과 설치 drift
| 명령 | 주요 option | exit code |
| --- | --- | --- |
| `template-check` | `--ops`, `--template`, `--json` | installed ops와 template manifest를 비교한다. current `0`, drift/behind/manifest absent로 비교 가능하지만 current가 아니면 `1`, 입력 누락/manifest malformed는 `2`다. |
| `template-apply` | `--ops`, `--template`, 반복 `--placeholder KEY=VALUE`, `--write`, `--json` | 항상 dry-run plan을 먼저 출력한다. 실제 write는 확인 문구 `apply`가 필요하며 `--yes`는 없다. manifest 미소유 path, instance-owned path, symlink escape를 거부한다. |
| `onboarding-rehearsal` | script parser | onboarding rehearsal 실행용 ops command다. |
| `workstream-render.sh` | script parser | workstream 문서/상태 렌더링 보조 명령이다. |
### PR과 대화 surface redaction
| 명령 | 주요 option | exit code |
| --- | --- | --- |
| `pr-body-check` | ``, `--repo`, `--body-file`, `--template-file` | PR body의 필수 narrative section과 redaction pattern을 검사한다. 통과 `0`, section/redaction 실패 `1`, usage/runtime 오류 `2`다. |
| `conversation-redaction-scan` | `--repo`, `--limit` | GitHub PR body, PR comment, review body, issue body에서 home path 계열 redaction 위반을 찾는다. clean `0`, findings `1`, API/usage 오류 `2`다. |
| `test-tool-naming.sh` | 없음 | tool naming regression check다. clean `0`, findings `1`, usage/self-test failure `2`다. |
## 공개 surface 검증
### 문서 표와 실행 파일 surface 비교
`local-mogui-ade-orchestrator`의 표 검증은 실행 파일 인벤토리를 직접 측정한다.
```bash
cd local-mogui-ade-orchestrator
pytest -q tests/test_reference_command_table.py
```
검증 방식은 다음과 같다.
1. `scripts/` 바로 아래 실행 가능한 파일만 수집한다.
2. 각 script에 `--help`를 실행한다.
3. argparse usage에 `{a,b,c}` subcommand group이 있으면 `script subcommand`를 공개 surface로 기록한다.
4. subcommand group이 없으면 `script` 단일 명령으로 기록한다.
5. `docs/public/reference.md`의 command table row와 비교한다.
6. 실행 파일에는 있는데 문서 row가 없으면 `missing`, 문서에는 있는데 실행 파일이 없으면 `stale`로 실패한다.
7. fabricated gap canary로 `dispatch-gate check` row를 제거한 비교가 실제로 실패하는지도 테스트한다.
현재 측정되는 런타임 저장소 공개 surface는 `acceptance-loop` 4개 subcommand, `dispatch-gate` 4개 subcommand, `master-succeed` 6개 subcommand, 그리고 단일 command script들을 포함한다.
### Ops-side regression checks
`local-master-ops`는 제품 저장소처럼 중앙 reference table test를 갖지 않는다. 대신 script별 regression shell이 특정 운영 결함을 고정한다.
```bash
cd local-master-ops
./scripts/test-spawn-test.sh
./scripts/test-dispatch-runtime.sh
./scripts/test-measure.sh
./scripts/test-product-path-guard.sh
./scripts/test-seat-check.sh
./scripts/test-tool-naming.sh
```
| 테스트 | 고정하는 surface |
| --- | --- |
| `test-spawn-test.sh` | `spawn-test`의 runtime launch command와 report status 분류 |
| `test-dispatch-runtime.sh` | `dispatch`의 `agy` capability mapping과 approval flag |
| `test-measure.sh` | `measure`가 exit status를 첫 줄에 출력하고 원래 status를 보존하는 계약 |
| `test-product-path-guard.sh` | product path guard hook 동작 |
| `test-seat-check.sh` | seat check 동작 |
| `test-tool-naming.sh` | tool naming 규칙 위반 탐지 |
prepared workspace에서 `local-master-ops`가 독립 git checkout으로 제공되지 않으면 `spawn-test` 계열 테스트는 `git rev-parse --show-toplevel` 단계에서 실행 환경 의존적으로 실패할 수 있다. 이 경우 script surface 문서화에는 영향을 주지 않지만, 실제 ops 저장소 checkout에서 다시 실행해야 한다.
## Exit code 차이
| 범주 | `0` | `1` | `2` | 추가 code |
| --- | --- | --- | --- | --- |
| `dispatch-gate check/register` | allow | 사용하지 않음 | deny 또는 검증 실패 | `watch`는 stalled `3` |
| `acceptance-loop run` | final score complete | final score incomplete | config/value/report 오류 | 없음 |
| `workspace-descriptor-check` | allowed | prohibited | unconfigured/invalid/bad usage | 없음 |
| `model-identity-probe` | match 또는 no-expect informational | 사용하지 않음 | drift/undecidable/unconfigured | 없음 |
| `model-drift-audit` | no transition, expectation match | transition 또는 expectation mismatch | undecidable | 없음 |
| `redaction-scan.sh` | clean | findings | cannot decide | 없음 |
| `redaction-inventory` | uncovered 없음 | uncovered 후보 있음 | cannot decide | 없음 |
| `template-check` | current | drift/behind/checkable undetermined | malformed/unreadable input | 없음 |
| `template-apply` | dry-run clean 또는 write success | plan error/refused attempt | confirmation/input/write 판단 불가 | 없음 |
| `worker-reap` | success | other failure | missing args | dispatch not settled `3`, parse error `4` |
| `measure` | 원래 명령이 `0` | 원래 명령이 `1` | 인자 없음 또는 원래 명령이 `2` | 원래 명령 status 그대로 |
| `orca-wait` | wait 처리 성공 | unknown flag 또는 Orca wait 실패 status | Orca wait 실패 status | `orca` 없음 `127` |
## 문서 갱신 규칙
`local-mogui-ade-orchestrator:docs/public/reference.md`에 새 row를 추가할 때는 목적과 주요 option을 사람이 작성한다. command inventory는 generator가 아니라 테스트가 지킨다. 새 공개 script를 추가하면 같은 변경에서 다음 중 하나를 해야 한다.
새 script가 실행 가능 bit를 갖고 `--help`를 제공하는지 확인한다. argparse subparser를 쓰면 usage의 `{subcommand,...}`가 문서 surface로 잡힌다.
`docs/public/reference.md`의 command table에 `scripts/`과 실제 command 문자열을 추가한다. subcommand가 있으면 row를 subcommand별로 나눈다.
`pytest -q tests/test_reference_command_table.py`를 실행한다. `missing`은 실행 파일이 문서에 없다는 뜻이고, `stale`은 문서 row가 실제 script surface와 맞지 않는다는 뜻이다.
## Related pages
`dispatch-gate check`, Orca task 생성, register probe, acceptance 전 재검증 흐름을 연결해 본다.
`master-succeed` subcommand가 succession trigger, handoff, successor verify, retire, spawn 단계에서 쓰이는 위치를 본다.
`redaction-scan.sh`, `redaction-inventory`, conversation surface scan의 범위와 실패 의미를 본다.
`instance-runtime.json`, `workspace-descriptor.json`, model tier policy와 CLI override 해석 순서를 확인한다.
---
## 19. 설정 참조
> `instance-runtime.json`, `workspace-descriptor.json`, `model-tier-policy.json`, 환경 변수 override, schema field, default, fail-closed 동작을 정리합니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/19-page-19.md
- Generated: 2026-08-10T07:42:19.502Z
### Source Files
- `local-mogui-ade-orchestrator:config/instance-runtime.example.json`
- `local-mogui-ade-orchestrator:config/workspace-descriptor.example.json`
- `local-mogui-ade-orchestrator:config/model-tier-policy.example.json`
- `local-mogui-ade-orchestrator:src/master_runtime/core/instance_runtime_config.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/workspace_descriptor.py`
- `local-mogui-ade-orchestrator:src/master_runtime/core/dispatch_gate.py`
- `local-mogui-ade-orchestrator:tests/test_instance_runtime_config.py`
- `local-mogui-ade-orchestrator:tests/test_workspace_descriptor.py`
---
title: "설정 참조"
description: "`instance-runtime.json`, `workspace-descriptor.json`, `model-tier-policy.json`, 환경 변수 override, schema field, default, fail-closed 동작을 정리합니다."
---
런타임 설정은 인스턴스 소유 JSON 파일과 환경 변수 override로 해석된다. 템플릿은 `*.example.json`만 제공하고, 실제 설치 값은 `config/instance-runtime.json`, `config/workspace-descriptor.json`, `config/model-tier-policy.json`에 기록한다.
## 설정 파일
| 파일 | 소유 주체 | 주요 소비자 | 기본 경로 동작 |
| --- | --- | --- | --- |
| `config/instance-runtime.json` | 설치 인스턴스 | `model-identity-probe`, master-ops dispatch wrapper | 없으면 값별 `require_*` 호출에서 `unconfigured` 오류 |
| `config/workspace-descriptor.json` | 설치 인스턴스 | `workspace-descriptor-check`, 작업 라우팅 guard | 없으면 descriptor는 비어 있고 판단 API는 exit `2` |
| `config/model-tier-policy.json` | 설치 인스턴스 | `dispatch-gate`, `master-ops/scripts/dispatch` | 있으면 템플릿 정책보다 우선 |
| `master-ops/model-tier-policy.json` | 템플릿/ops 저장소 | tier policy fallback | 인스턴스 정책이 없을 때 fallback |
채워진 인스턴스 설정 파일은 이 머신의 절대 경로, transcript glob, owner consent 상태를 담을 수 있다. 예제 파일은 버전 관리 대상이지만 채워진 인스턴스 파일은 커밋하지 않는 전제다.
## `instance-runtime.json`
`instance-runtime.json`은 마스터가 어떤 agent CLI 위에서 실행되는지, 각 runtime의 transcript JSONL을 어디서 찾는지, 선택적 primary product repo가 무엇인지 기록한다.
### 필드
| 필드 | 타입 | 기본값 | 필수성 | 동작 |
| --- | --- | --- | --- | --- |
| `master_host_runtime` | `string \| null` | 없음 | 필요한 소비자에서 필수 | 비어 있으면 `require_master_host_runtime()`이 오류 |
| `transcript_globs` | `object` | `{}` | model probe에서 필요 | runtime 이름별 glob. `_`로 시작하는 키는 문서 키로 무시 |
| `product_repo` | `string \| null` | 없음 | product-path guard 등에서 필요 | 비어 있으면 `require_product_repo()`가 오류 |
| `_docs` | `object` | 없음 | 선택 | parser가 무시하는 문서용 키 |
```json title="config/instance-runtime.json"
{
"master_host_runtime": "claude",
"transcript_globs": {
"claude": "~/.claude/projects/-Users-example-workspace/*.jsonl",
"codex": "~/.codex/sessions/**/*.jsonl"
},
"product_repo": "/absolute/path/to/primary-product-repo"
}
```
### 해석 순서
1. 명시적 config path 인자
2. `INSTANCE_RUNTIME_CONFIG`
3. `/config/instance-runtime.json`
값 자체는 환경 변수가 파일보다 우선한다.
| 값 | 환경 변수 우선순위 | 파일 fallback | 미설정 동작 |
| --- | --- | --- | --- |
| 마스터 runtime | `MOGUI_MASTER_HOST_RUNTIME`, 그 다음 `MASTER_HOST_RUNTIME` | `master_host_runtime` | `InstanceRuntimeConfigError` |
| transcript glob | `MOGUI_TRANSCRIPT_GLOB` | `transcript_globs.` | `InstanceRuntimeConfigError` |
| product repo | `MOGUI_PRODUCT_REPO` | `product_repo` | `InstanceRuntimeConfigError` |
`MOGUI_TRANSCRIPT_GLOB`는 runtime별 변수가 아니라 현재 probe에 적용되는 단일 override다. `model-identity-probe --transcript`가 있으면 이 모든 해석보다 우선한다.
## `workspace-descriptor.json`
`workspace-descriptor.json`은 plain folder workspace 아래 sibling repository 목록을 선언한다. 이 런타임은 `workspace_root_is_plain_folder: true`만 허용하며 submodule parent나 non-plain workspace root를 거부한다.
### workspace 필드
| 필드 | 타입 | 기본값 | 제약 |
| --- | --- | --- | --- |
| `workspace_root_is_plain_folder` | `boolean` | `true` | 반드시 `true` |
| `workspace_root` | `string \| null` | `null` | 절대 경로 lookup을 쓰려면 설정 |
| `master_seat` | `string` | `""` | null은 빈 문자열로 처리 |
| `repositories` | `array` | `[]` | 필요한 소비자에서는 비어 있으면 unconfigured |
| `_docs` | `object` | 없음 | parser가 무시 |
### repository 필드
| 필드 | 타입 | 기본값 | 제약 |
| --- | --- | --- | --- |
| `name` | `string` | 없음 | non-empty, 중복 불가 |
| `path` | `string` | 없음 | workspace-root-relative, 단일 repo 예외는 `.` |
| `remote` | `string` | `""` | null이면 빈 문자열 |
| `role` | `string` | 없음 | `product` 또는 `ops` |
| `capabilities` | `array` | `[]` | open set. 예: `pr`, `dispatch-target` |
| `prohibited` | `array` | 없음 | 반드시 존재. 빈 배열은 owner-confirmed no prohibition 의미 |
```json title="config/workspace-descriptor.json"
{
"workspace_root_is_plain_folder": true,
"workspace_root": "/absolute/path/to/workspace-root",
"master_seat": "folder-workspace-of-workspace-root",
"repositories": [
{
"name": "product-app",
"path": "product-app",
"remote": "https://github.com/example/product-app.git",
"role": "product",
"capabilities": ["pr", "dispatch-target"],
"prohibited": ["direct-main-commit", "force-push"]
},
{
"name": "workspace-ops",
"path": "workspace-ops",
"remote": "",
"role": "ops",
"capabilities": ["pr", "dispatch-target"],
"prohibited": ["force-push"]
}
]
}
```
### prohibition 판단
`workspace-descriptor-check`는 repository path와 action을 받아 허용 여부를 판단한다.
```bash
scripts/workspace-descriptor-check \
--path product-app \
--action direct-main-commit \
--json
```
| exit code | 의미 |
| --- | --- |
| `0` | action 허용 |
| `1` | action 금지 |
| `2` | descriptor 미설정, invalid, bad usage. 판단 불가이므로 fail-closed |
경로 매칭은 선언된 `path`, 단일 segment `name`, 또는 `workspace_root` 아래의 절대 경로를 사용한다. 같은 basename이 다른 부모 아래에 있는 상대 경로는 suffix match하지 않는다. 알 수 없는 repo는 기본적으로 금지로 취급하며, CLI에서만 `--allow-unknown-repo`로 이 기본값을 바꿀 수 있다.
## `model-tier-policy.json`
현재 예제와 템플릿 정책은 version `2` 형식이다. dispatch gate는 version `1`도 legacy로 읽지만, tier와 fan-out cap을 문서화할 때 기준은 version `2`다.
### v2 필드
| 필드 | 타입 | 기본값 | 제약 |
| --- | --- | --- | --- |
| `version` | `integer` | 없음 | `2` |
| `tiers` | `object>` | 없음 | non-empty object. `unknown` tier 이름은 예약어라 선언 불가 |
| `fanout_caps` | `object` | 없음 | 반드시 object. tier 이름 또는 `unknown`만 허용. 값은 0 이상 정수 |
| `window_seconds` | `integer` | `86400` | 양의 정수 |
| `agents` | `array` | 없음 | gate parser가 소비하지 않는 설치 inventory |
| `consent` | `string` | 없음 | gate parser가 소비하지 않는 owner consent 기록 |
| `_docs`, `_notes` | `object/string` | 없음 | gate parser가 소비하지 않는 문서 메타데이터 |
```json title="config/model-tier-policy.json"
{
"version": 2,
"consent": "no",
"agents": [
{
"runtime": "claude",
"version": "unknown",
"model_ids": ["unknown"]
}
],
"tiers": {
"top": [],
"efficient": ["claude-sonnet-5"]
},
"fanout_caps": {
"unknown": 8
},
"window_seconds": 86400
}
```
### tier 해석
| 상태 | 결과 |
| --- | --- |
| model id가 `tiers.` 목록에 있음 | 해당 tier로 기록 |
| model id가 어떤 tier에도 없음 | 예약 tier `unknown`으로 기록하고 `TIER_UNKNOWN_MODEL` warning |
| `fanout_caps.`가 있음 | window 안의 allowed dispatch agent 수가 cap을 넘으면 deny |
| `fanout_caps.`가 없음 | uncapped |
| policy 파일이 없거나 invalid | `TIER_POLICY_UNAVAILABLE` deny |
`unknown`도 일반 tier처럼 cap을 갖는다. `fanout_caps.unknown`이 없으면 `unknown`도 uncapped이며, 템플릿 정책은 `unknown: 8`을 둔다. 템플릿의 `top`과 `efficient`는 cap이 없어 gate 차원에서는 uncapped다.
top-tier 제어는 gate의 `fanout_caps.top`보다 `master-ops/scripts/dispatch --top-approved ""`에서 처리한다. wrapper는 top tier 요청에 owner approval 문자열이 없으면 gate check 전에 exit `2`로 중단한다.
## 환경 변수 override
| 변수 | 적용 범위 | 우선순위/효과 |
| --- | --- | --- |
| `INSTANCE_RUNTIME_CONFIG` | runtime core, `model-identity-probe` | `instance-runtime.json` 경로 override |
| `MOGUI_MASTER_HOST_RUNTIME` | runtime core, master-ops dispatch wrapper | master host runtime 값 override |
| `MASTER_HOST_RUNTIME` | runtime core | `MOGUI_MASTER_HOST_RUNTIME` 다음 fallback |
| `MOGUI_TRANSCRIPT_GLOB` | runtime core, `model-identity-probe` | transcript glob 값 override |
| `MOGUI_PRODUCT_REPO` | runtime core, 일부 ops script | primary product repo 값 override |
| `WORKSPACE_DESCRIPTOR` | workspace descriptor loader | descriptor 경로 override |
| `MOGUI_WORKSPACE_DESCRIPTOR` | workspace descriptor loader | `WORKSPACE_DESCRIPTOR` 다음 경로 override |
| `DISPATCH_TIER_POLICY` | dispatch gate, master-ops dispatch wrapper | tier policy 경로 override |
| `DISPATCH_GATE_LEDGER` | dispatch gate 기본 config | ledger path override |
| `MOGUI_INSTANCE_RUNTIME_CONFIG` | master-ops dispatch wrapper, hooks | ops wrapper가 읽을 instance runtime config 경로. wrapper가 이후 `INSTANCE_RUNTIME_CONFIG`로 export |
## Fail-closed 동작
| 표면 | 조건 | 결과 |
| --- | --- | --- |
| `instance-runtime.json` | 파일 없음 | load는 성공하지만 필요한 값의 `require_*`에서 unconfigured 오류 |
| `instance-runtime.json` | invalid JSON, root non-object, 잘못된 필드 타입 | `InstanceRuntimeConfigError` |
| `transcript_globs` | object가 아니거나 key/value가 빈 문자열 | `InstanceRuntimeConfigError` |
| `model-identity-probe` | transcript 위치 미설정, glob match 없음, invalid transcript, drift | exit `2` |
| `workspace-descriptor.json` | 파일 없음 | `workspace-descriptor-check` exit `2` |
| `workspace-descriptor.json` | invalid UTF-8/JSON, root non-object, non-plain flag, invalid role, duplicate identity | `WorkspaceDescriptorError` |
| repository lookup | 알 수 없는 repo | 기본 금지. CLI `--allow-unknown-repo` 사용 시에만 허용 취급 |
| `model-tier-policy.json` | 파일 없음, invalid JSON, invalid schema | dispatch gate deny `TIER_POLICY_UNAVAILABLE` |
| dispatch request | `model` 없음 | deny `NO_MODEL` |
| dispatch request | `completion_channel` 없음 또는 허용값 아님 | deny `NO_COMPLETION_CHANNEL` |
| contract | 크기 측정 실패 또는 파일 없음 | deny `CONTRACT_UNREADABLE` |
| model verification | 측정 model이 선언 model보다 더 엄격한 tier | register deny `MODEL_TIER_ESCALATION` |
| model verification | 측정 불가 또는 probe 실패 | allow + `MODEL_UNVERIFIED` 또는 `MODEL_PROBE_FAILED` warning |
## 검증 명령
```bash
python3 -m pytest \
tests/test_instance_runtime_config.py \
tests/test_workspace_descriptor.py \
tests/test_dispatch_gate.py
```
```bash
scripts/model-identity-probe \
--config config/instance-runtime.json \
--runtime claude \
--expect claude-fable-5
```
```bash
scripts/workspace-descriptor-check \
--config config/workspace-descriptor.json \
--path product-app \
--action force-push \
--json
```
```bash
scripts/dispatch-gate \
--ledger ~/.mogui/dispatch-ledger.jsonl \
check \
--runtime codex \
--model gpt-5.6-luna \
--tier-policy config/model-tier-policy.json \
--contract /path/to/contract.md \
--agents 1 \
--est-chars 3000 \
--completion-channel orchestration
```
## Related pages
인스턴스 설정 파일을 생성하고 검증하는 설치 전후 절차.
dispatch gate, contract, register probe, completion channel의 실행 흐름.
transcript glob과 expected model을 사용한 모델 검증 경로.
`dispatch-gate`, `model-identity-probe`, `workspace-descriptor-check`의 옵션과 exit code.
---
## 20. master-ops 템플릿 참조
> 템플릿 manifest, template version, placeholder, workspace card, charter, runbook, hook, upgrade와 template-check surface를 정리합니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/20-master-ops.md
- Generated: 2026-08-10T07:42:54.341Z
### Source Files
- `local-master-ops:MANIFEST.json`
- `local-master-ops:TEMPLATE-VERSION`
- `local-master-ops:ONBOARDING.md`
- `local-master-ops:workspace-card/README.md`
- `local-master-ops:scripts/template-check`
- `local-master-ops:scripts/template-apply`
- `local-mogui-ade-orchestrator:scripts/generate-manifest`
- `local-mogui-ade-orchestrator:tests/test_template_check_apply.py`
---
title: "master-ops 템플릿 참조"
description: "템플릿 manifest, template version, placeholder, workspace card, charter, runbook, hook, upgrade와 template-check surface를 정리합니다."
---
`master-ops` 템플릿은 `local-mogui-ade-orchestrator:master-ops/`의 Stage 1 skeleton을 설치 가능한 ops 저장소로 복사하고, 설치된 복사본은 `local-master-ops:MANIFEST.json`의 `template_version`과 `files` 목록으로 자기 템플릿 계층을 판정한다. Founding은 manifest 목록을 복사하고 placeholder를 채우며, Reverify는 읽기 전용으로 상태를 보고하고, Upgrade는 `template-check`와 `template-apply`로 manifest가 주장하는 템플릿 파일만 앞으로 가져온다.
## 템플릿 계층
| 표면 | 위치 | 역할 | 설치 여부 |
| --- | --- | --- | --- |
| Manifest | `local-master-ops:MANIFEST.json` | 설치된 템플릿 버전과 필수 파일 목록 | 설치됨 |
| Template version stamp | `local-master-ops:TEMPLATE-VERSION` | 템플릿 릴리스 문자열 | 템플릿 측 파일, 생성 ops 저장소에는 제외 |
| Onboarding router | `local-master-ops:ONBOARDING.md` | Founding, Reverify, Upgrade, Template improve 모드 라우팅 | 템플릿 측 파일, 생성 ops 저장소에는 제외 |
| Step files | `local-master-ops:onboarding/` | Founding 단계별 절차와 검증 | 템플릿 측 파일, 생성 ops 저장소에는 제외 |
| Workspace card | `local-master-ops:workspace-card/` | 워크스페이스 루트에 배포할 canonical session card | 설치됨 |
| Charter index | `local-master-ops:docs/MASTER-OPERATIONS.md` | 운영 SSOT와 charter section index | 설치됨 |
| Charter sections | `local-master-ops:docs/charter/` | 역할, dispatch, succession, record, hook 규칙 | 설치됨 |
| Runbooks | `local-master-ops:docs/runbooks/` | 현장 절차와 운영 card | 대부분 설치됨 |
| Hooks | `local-master-ops:scripts/hooks/` | host hook에서 호출되는 guard/warn/inject 스크립트 | 설치됨 |
| Check/apply scripts | `local-master-ops:scripts/template-check`, `local-master-ops:scripts/template-apply` | 템플릿 drift 보고와 적용 | 설치됨 |
```text
local-mogui-ade-orchestrator:master-ops/ 템플릿 skeleton
TEMPLATE-VERSION 릴리스 stamp
MANIFEST.json 설치 대상 목록
onboarding/ 설치 절차, 템플릿 측 전용
generate-manifest / Founding / Upgrade
local-master-ops/ 설치된 ops 저장소
MANIFEST.json 설치 버전과 required paths
docs/MASTER-OPERATIONS.md 운영 SSOT index
workspace-card/CLAUDE.md, AGENTS.md canonical session card
scripts/template-check, template-apply drift 확인과 적용
onboarding step 05 deploy
/CLAUDE.md, AGENTS.md host가 읽는 배포본
```
## Manifest 생성 규칙
`local-mogui-ade-orchestrator:scripts/generate-manifest`가 `master-ops/` skeleton을 walk해서 `MANIFEST.json`을 만든다. `files`는 POSIX 상대 경로 문자열로 정렬되며, `MANIFEST.json` 자체도 설치 목록에 포함된다.
설치 목록에서 제외되는 템플릿 측 파일과 디렉터리는 코드에 고정되어 있다.
| 제외 범주 | 항목 |
| --- | --- |
| 파일 | `TEMPLATE-VERSION`, `CHANGELOG.md`, `ONBOARDING.md`, `.coverage` |
| 디렉터리 | `onboarding`, `docs/lineage`, `.git`, `.beads`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache`, `build`, `dist`, `htmlcov` |
| 로컬 산출물 | `__pycache__`, `.pyc`, `.pyo`, `*.egg-info`, symlink |
Generator는 설치될 파일에서 authoring frame 누수를 검사한다. `master-ops/` 경로 문자열과 `mogui-master-ops` authoring repository 이름은 설치 파일에 남으면 실패한다. 단, `docs/blame/` 아래 incident record는 측정 증거 보존을 위해 hygiene 검사에서 제외된다.
`local-mogui-ade-orchestrator`에서 `python3 scripts/generate-manifest --check`가 0으로 종료하면 committed `MANIFEST.json`이 현재 skeleton, `TEMPLATE-VERSION`, 정렬 규칙과 일치한다.
## Template version
현재 설치 manifest와 stamp는 `v0.5.187`이다. `MANIFEST.json.template_version`은 `TEMPLATE-VERSION`의 한 줄 값을 복사한다. Changelog는 설치 파일이 아니라 템플릿 측 파일이며, 기존 설치본이 자동으로 업데이트되지 않는다는 전제를 둔다.
Version skew는 숫자 크기 비교가 아니라 문자열 equality로 판정한다. 설치된 값과 템플릿 값이 다르면 `template-check --template`은 drift로 보고한다. `CHANGELOG.md`는 설치 버전보다 최신인 adoption note를 보고서에 붙여 Upgrade 판단을 돕는다.
## Placeholder 계약
허용 placeholder는 다음 8개뿐이다.
| Placeholder | 값의 출처 |
| --- | --- |
| `{{WORKSPACE_NAME}}` | 기존 install 또는 Founding 중 확인한 워크스페이스 이름 |
| `{{WORKSPACE_ROOT}}` | owner가 선택한 워크스페이스 루트 |
| `{{OPS_REPO}}` | 승인된 ops 저장소 경로 |
| `{{MONITOR_NS}}` | 확인된 monitor namespace |
| `{{MODEL_ID}}` | 확인된 master model id |
| `{{REPO_LIST}}` | 확인된 workspace repository inventory |
| `{{RUNTIME_ROOT}}` | 템플릿 clone의 root, 측정값 |
| `{{TEMPLATE_VERSION}}` | 템플릿 `TEMPLATE-VERSION`, 측정값 |
Founding step 05는 ops 저장소 전체에서 `{{...}}` 토큰이 남지 않아야 통과한다. `workspace-card/`도 예외가 아니며, undecided 값은 deferral로 남기지 않는다. Upgrade에서 `template-apply --placeholder KEY=VALUE`는 같은 placeholder set만 받으며, 알 수 없는 key는 controlled error로 거절된다. `TEMPLATE_VERSION`을 넘기지 않으면 `template-apply`가 템플릿 측 `TEMPLATE-VERSION`에서 기본값을 읽는다.
## Workspace card
`local-master-ops:workspace-card/CLAUDE.md`와 `local-master-ops:workspace-card/AGENTS.md`는 byte-identical canonical session card이다. 설치 후 워크스페이스 루트의 `CLAUDE.md`와 `AGENTS.md`는 이 canonical pair의 배포본이다.
이 pair는 ops 저장소 루트의 `CLAUDE.md` / `AGENTS.md`와 다른 문서다. Ops 루트 pair는 ops 저장소 안에서 agent가 어떻게 동작하는지 설명하고, workspace card는 host가 워크스페이스 루트에서 읽는 master session card다. Owner-facing operating card도 별도 산출물이다.
배포 명령은 placeholder가 채워진 뒤 실행한다.
```console
$ cp "{{OPS_REPO}}/workspace-card/CLAUDE.md" "{{WORKSPACE_ROOT}}/CLAUDE.md"
$ cp "{{OPS_REPO}}/workspace-card/AGENTS.md" "{{WORKSPACE_ROOT}}/AGENTS.md"
```
Workspace card 내부 링크는 저장 위치인 `workspace-card/`가 아니라 배포 위치인 `{{WORKSPACE_ROOT}}` 기준으로 해석한다. Reverify는 canonical pair와 root 배포본 drift를 보고만 하며, 자동으로 재배포하지 않는다.
## Charter와 runbook 표면
`local-master-ops:docs/MASTER-OPERATIONS.md`는 active operating rule의 index다. 문서 자체는 `{{WORKSPACE_NAME}}` workspace의 master operations SSOT이며, 변경 시 관련 issue-tracker memory pointer와 hook path를 함께 확인하라는 change rule을 가진다.
Charter는 10개 section으로 분리되어 있다.
| Section | 파일 | 담당 범위 |
| --- | --- | --- |
| §1 | `docs/charter/01-document-map.md` | 상태와 문서 ownership |
| §2 | `docs/charter/02-role-constitution.md` | master role, role state format |
| §3 | `docs/charter/03-execution-principles.md` | proposal, approval, execution, recovery |
| §4 | `docs/charter/04-worker-routing-review.md` | worker dispatch와 review |
| §5 | `docs/charter/05-dispatch-gate.md` | supervised dispatch gate |
| §6 | `docs/charter/06-succession.md` | succession과 recovery |
| §7 | `docs/charter/07-records.md` | record separation |
| §8 | `docs/charter/08-boot-hooks-observability.md` | boot config, hook wiring, observability |
| §9 | `docs/charter/09-incident-derived-rules.md` | incident-derived rule |
| §10 | `docs/charter/10-closed-principles-pointer.md` | closed decision pointer |
Runbook은 operational procedure를 담는다. 예를 들어 `docs/runbooks/hook-fire-observability.md`는 hook fire log를 `${MOGUI_HOOK_FIRE_LOG:-$HOME/.mogui/hook-fire-log.jsonl}`에 JSONL로 남기는 schema와 `scripts/hook-coverage-report` 확인 경로를 정의한다.
## Hook과 host 설정
Template은 hook script와 문서화된 wiring spec을 제공하지만, host별 settings 파일, credential, secret path, 조직별 보안 구현을 함께 배포하지 않는다. Step 08은 shipped hook과 skill layer를 default-on harness로 취급하되, host settings와 plugin configuration 변경에는 별도 host-edit approval을 요구한다.
주요 hook 표면은 다음과 같다.
| Hook surface | 대표 파일 | 동작 |
| --- | --- | --- |
| Role-state injection | `scripts/hooks/role-state-inject.sh` | `UserPromptSubmit`에서 active role과 실행 원칙을 재주입 |
| Product path guard | `scripts/hooks/product-path-guard.sh` | product repository write를 차단하거나, 측정된 Bash allowlist 기반으로 fail-closed |
| Tracker reachability | `scripts/hooks/tracker-check.sh` | session start에서 tracker 접근성 경고 |
| Inbox warning | `scripts/hooks/orch-inbox-warn.sh` | unread orchestration inbox item 표면화 |
| Worker bypass warning | `scripts/hooks/worker-block-warn.sh` | supervised dispatch 우회 경고 |
| Output/poll warning | `scripts/hooks/bash-output-trim-warn.sh`, `scripts/hooks/bash-poll-warn.sh` | Bash 출력과 poll 사용 경고 |
Product path guard의 Bash fail-closed 측정 모드는 `MOGUI_PRODUCT_GUARD_FAIL_CLOSED=1`일 때 opt-in이다. 기본값은 off이며, 측정되지 않은 allowlist를 기본 policy로 쓰지 않는다. Multi-product workspace거나 primary product path가 확정되지 않았으면 guard wiring은 보류해야 한다.
이 템플릿의 hook/skill 구조는 파일과 저장소에 기반한 portable surface다. 특정 model provider, hosted connector, proprietary runtime을 전제로 하지 않는다. Host별 agent와 plugin ecosystem은 다를 수 있지만, manifest, placeholder, check/apply 계약은 파일 경로와 CLI exit code로 검증된다.
## `template-check`
`local-master-ops:scripts/template-check`는 ops 설치본을 manifest 기준으로 검사한다. `--template`이 없으면 installed manifest만 보고, `--template`을 주면 현재 템플릿과 비교한다.
```console title="설치본 자체 검사"
$ python3 scripts/template-check --ops "{{OPS_REPO}}" --json
```
```console title="템플릿 clone과 비교"
$ "{{RUNTIME_ROOT}}/master-ops/scripts/template-check" \
--ops "{{OPS_REPO}}" \
--template "{{RUNTIME_ROOT}}/master-ops" \
--json
```
Exit code 계약은 fail-closed다.
| Exit code | 의미 |
| --- | --- |
| `0` | 검사했고 current 또는 drift 없음 |
| `1` | 검사했고 drift, behind, absent required, unknown present, invalid path 중 하나가 있음 |
| `2` | 입력을 검사할 수 없음. 예: malformed manifest, unreadable template version, unreadable changelog |
Report set은 두 가지다.
| `report_set` | 생성 조건 | 포함 정보 |
| --- | --- | --- |
| `install-manifest` | `--template` 없음 | `installed_version`, `manifest_status`, `absent_required`, `unknown_present`, `invalid_paths` |
| `template-compare` | `--template` 있음 | install-manifest 필드 + `template_version`, `adoption_notes` |
JSON report의 주요 field는 다음과 같다.
| Field | 의미 |
| --- | --- |
| `ops_root` | 검사 대상 ops root |
| `installed_version` | 설치 manifest의 `template_version`; manifest가 없으면 `null` |
| `manifest_status` | `ok`, `absent`, `malformed` |
| `absent_required` | manifest 또는 template manifest가 요구하지만 ops에 없는 경로 |
| `unknown_present` | manifest가 주장하지 않고 instance-owned/template-side 예외도 아닌 경로 |
| `invalid_paths` | symlink 등 regular file로 판정할 수 없는 경로 |
| `template_version` | 비교 대상 템플릿 version |
| `adoption_notes` | 설치 버전 이후 changelog section preview |
| `questions_unanswered` | undecidable 또는 unreadable 원인 |
`template-check`는 `.git/`과 `.beads/`를 unknown-path noise에서 제외한다. 그 외 local cache나 산출물이 ops tree 안에 있으면 manifest가 주장하지 않는 경로로 보고될 수 있다.
## `template-apply`
`local-master-ops:scripts/template-apply`는 템플릿 manifest가 claim한 template-layer file만 ops 저장소에 적용한다. 항상 dry-run plan을 먼저 출력하며, write pass에는 confirmation phrase `apply`가 필요하다. 일반 사용자용 `--yes`는 없다.
```console
$ "{{RUNTIME_ROOT}}/master-ops/scripts/template-apply" \
--ops "{{OPS_REPO}}" \
--template "{{RUNTIME_ROOT}}/master-ops"
```
쓰기 pass는 같은 명령에 `--write`와 placeholder 값을 추가한다.
```console
$ "{{RUNTIME_ROOT}}/master-ops/scripts/template-apply" \
--ops "{{OPS_REPO}}" \
--template "{{RUNTIME_ROOT}}/master-ops" \
--write \
--placeholder WORKSPACE_NAME="{{WORKSPACE_NAME}}" \
--placeholder WORKSPACE_ROOT="{{WORKSPACE_ROOT}}" \
--placeholder OPS_REPO="{{OPS_REPO}}" \
--placeholder MONITOR_NS="{{MONITOR_NS}}" \
--placeholder MODEL_ID="{{MODEL_ID}}" \
--placeholder REPO_LIST="{{REPO_LIST}}" \
--placeholder RUNTIME_ROOT="{{RUNTIME_ROOT}}" \
--placeholder TEMPLATE_VERSION="{{TEMPLATE_VERSION}}"
```
Per-file outcome은 다음 값 중 하나다.
| Outcome | 의미 |
| --- | --- |
| `planned` | manifest가 claim한 template-layer path이며 dry-run에서 create 또는 overwrite 예정 |
| `written` | write pass에서 atomic replace 완료 |
| `skipped-as-instance-owned` | instance-owned path라서 이름으로 거절 |
| `refused-not-in-manifest` | manifest가 claim하지 않는 path라서 거절 |
| `error-invalid-path` | 절대 경로, path escape, symlink, directory target, root 밖 resolution 등 |
| `error-missing-template-file` | manifest에는 있지만 템플릿 tree에 파일이 없음 |
쓰기 전 preflight는 모든 planned source와 destination을 다시 확인한다. Destination은 ops root 아래 regular file이어야 하며, symlink를 통과하거나 root 밖으로 resolve되면 쓰지 않는다. 실제 쓰기는 destination directory 안 temporary file을 만든 뒤 mode를 보존하고 atomic replace한다. Batch 중 OS error가 나면 앞선 파일은 이미 written일 수 있으므로 문제를 고친 뒤 재실행한다.
## Instance-owned refusals
Template apply는 instance-owned record를 이름으로 거절한다. 이 경계는 `local-master-ops:scripts/template_common.py`에서 `template-check`와 `template-apply`가 공유한다.
| Instance-owned path | 처리 |
| --- | --- |
| `docs/lineage/` | lineage record로 보존, apply 거절 |
| `docs/runbooks/role-state.md` | role state SSOT로 보존, apply 거절 |
| `.beads/` | tracker database/export로 보존, apply 거절 |
| `config/` | local runtime config로 보존, apply 거절 |
| `contracts/` | dispatch/worker contract로 보존, apply 거절 |
| manifest가 claim하지 않는 모든 path | `refused-not-in-manifest` 또는 `unknown_present` |
Upgrade는 local edits를 삭제하지 않는다. `unknown_present`는 남아 있는 local additions를 보여주는 보고 field이며, apply 대상 목록이 아니다.
## Founding, Reverify, Upgrade의 차이
| Mode | 진입 조건 | 쓰기 범위 | Spawn |
| --- | --- | --- | --- |
| Founding | 새 workspace, ops repository가 없거나 승인된 새 skeleton 생성 | manifest listed skeleton copy, placeholder fill, workspace card deploy, tracker/config/hook setup | Gen-1 master spawn |
| Reverify | 이미 founded workspace와 master가 있음 | 기본 read-only. operating card lost reprint만 예외 | 금지 |
| Upgrade | founded ops repository가 현재 템플릿보다 뒤처짐 | `template-apply`가 dry-run 후 확인받은 template-layer files만 write | 금지 |
| Template improve | orchestrator repository 자체 문서/코드 변경 | 일반 개발 task로 처리 | 설치 flow 아님 |
Existing ops repository나 lineage file이 보이면 Founding을 다시 실행하지 않는다. Template layer가 오래됐으면 Upgrade로 라우팅하고, master가 죽었거나 half-finished install이면 `docs/runbooks/succession-boot-card.md`가 소유한 succession/recovery 문제로 다룬다.
## 검증 표면
| 검증 | 명령 또는 판정 |
| --- | --- |
| Manifest 최신성 | `local-mogui-ade-orchestrator`에서 `python3 scripts/generate-manifest --check` |
| 설치 shape | `python3 scripts/template-check --ops "{{OPS_REPO}}" --json` |
| upstream currency | `template-check --ops "{{OPS_REPO}}" --template "{{RUNTIME_ROOT}}/master-ops"` |
| apply dry-run | `template-apply --ops "{{OPS_REPO}}" --template "{{RUNTIME_ROOT}}/master-ops"` |
| apply write | dry-run 확인 후 `--write`, confirmation phrase `apply` |
| placeholder clean | `rg --hidden -g '!.git/**' -g '!.beads/**' '\{\{[^}]+\}\}' "{{OPS_REPO}}"`가 hit 없음 |
| ops instruction pair | `cmp "{{OPS_REPO}}/CLAUDE.md" "{{OPS_REPO}}/AGENTS.md"` |
| workspace card pair와 배포본 | canonical pair `cmp`, root 배포본과 canonical file `cmp` |
| hook fire 관측 | `scripts/hook-coverage-report`, fire-log JSONL |
## 오류와 대응
| 증상 | 의미 | 대응 |
| --- | --- | --- |
| `manifest_status=absent` | pre-manifest install 또는 손상된 install | version을 추측하지 말고 content presence로 보고한 뒤 Upgrade 후보로 둔다 |
| `manifest_status=malformed` | `MANIFEST.json` JSON 또는 shape가 깨짐 | exit 2로 실패. manifest를 복구한 뒤 재검사한다 |
| `template VERSION unreadable` | `TEMPLATE-VERSION`을 읽을 수 없거나 UTF-8이 아님 | exit 2. 템플릿 clone 상태를 먼저 고친다 |
| `unknown_present` 존재 | manifest가 claim하지 않는 local path | 삭제하지 않는다. local addition인지 cache인지 owner/master가 판정한다 |
| `invalid_paths` 존재 | symlink 또는 regular file이 아닌 target | root escape와 symlink overwrite 위험을 제거한 뒤 재검사한다 |
| `error-missing-template-file` | manifest와 template tree가 불일치 | 템플릿 manifest를 재생성하거나 missing file을 복구한다 |
| confirmation declined | write pass 미승인 | 아무 파일도 쓰지 않고 중단한다 |
| card drift | canonical pair 또는 root 배포본 불일치 | Reverify에서는 보고만 한다. 재배포는 별도 rescue task로 처리한다 |
## Related pages
Founding, Reverify, Upgrade, Template improve의 진입 조건과 금지된 spawn 경로를 확인합니다.
새 workspace에서 skeleton copy, placeholder fill, card deploy, Gen-1 spawn까지의 설치 흐름을 봅니다.
`scripts/` 명령, option, exit code와 테스트된 command surface를 확인합니다.
`instance-runtime.json`, `workspace-descriptor.json`, model policy, 환경 변수 override를 확인합니다.
---
## 21. 기여와 릴리스
> stdlib-only runtime, pytest gate, redaction scan, pre-push hook, version 산출, changelog, tag owner approval, Conventional Commits를 설명합니다.
- Page Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/pages/21-page-21.md
- Generated: 2026-08-10T07:42:00.847Z
### Source Files
- `local-mogui-ade-orchestrator:CONTRIBUTING.md`
- `local-mogui-ade-orchestrator:docs/internal/release-runbook.md`
- `local-mogui-ade-orchestrator:CHANGELOG.md`
- `local-mogui-ade-orchestrator:scripts/next-version`
- `local-mogui-ade-orchestrator:hooks/pre-push`
- `local-mogui-ade-orchestrator:tests/test_reference_command_table.py`
- `local-master-ops:CHANGELOG.md`
---
title: "기여와 릴리스"
description: "stdlib-only runtime, pytest gate, redaction scan, pre-push hook, version 산출, changelog, tag owner approval, Conventional Commits를 설명합니다."
---
`local-mogui-ade-orchestrator`의 릴리스 표면은 stdlib-only 런타임, `pytest` 테스트 게이트, `gitleaks` 기반 redaction 래퍼, opt-in `pre-push` hook, `MAJOR.MINOR.BUILD` 버전 산출 스크립트, 수동 태그 승인 절차로 구성된다. `local-master-ops`는 설치 템플릿으로 별도 `TEMPLATE-VERSION`과 `CHANGELOG.md`를 가진다.
## 기여 기준
런타임 코드는 Python 표준 라이브러리만 전제로 한다. 테스트 실행에는 `pytest`가 필요하며, 기여자는 변경 전후를 설명할 수 있는 실패 테스트를 우선 둔다.
```console
PYTHONPATH=src python3 -m pytest tests -q
```
문서 변경은 테스트가 없어도 된다. 이 경우 pull request에는 기존 문구가 무엇을 잘못 설명했는지 적는다.
### 커밋 형식
커밋 메시지는 영어 Conventional Commits를 사용한다.
```text
feat(scope): add dispatch report
fix(scope): close undecidable gate path
docs(scope): clarify redaction scope
```
커밋에는 무엇이 바뀌었는지와 왜 필요했는지를 함께 적는다. PR은 squash merge를 전제로 한다. AI agent가 작성한 커밋에는 해당 모델을 명시하는 `Co-Authored-By` trailer를 붙이는 관례가 있다.
## 테스트와 게이트
| 표면 | 명령 | 판정 |
| --- | --- | --- |
| 테스트 게이트 | `PYTHONPATH=src python3 -m pytest tests -q` 또는 릴리스 런북의 `PYTHONPATH=src uv run pytest tests -q` | 실패 시 merge 또는 release 중단 |
| 공개 CLI 표면 | `local-mogui-ade-orchestrator:tests/test_reference_command_table.py` | `scripts/` 실행 파일과 `docs/public/reference.md` 표가 어긋나면 실패 |
| 템플릿 도구명 게이트 | `bash master-ops/scripts/test-tool-naming.sh` | `ctx.` 같은 호출 불가능한 도구명이 문서/skill에 남으면 실패 |
| redaction scan | `./scripts/redaction-scan.sh` | exit `0` clean, `1` finding, `2` cannot decide |
| redaction inventory | `./scripts/redaction-inventory` | exit `0` uncovered 후보 없음, `1` 후보 발견, `2` 판단 불가 |
여러 스크립트는 exit code `2`를 “판단 불가”로 사용한다. crash나 사용법 오류를 finding처럼 보이게 만들면 호출자가 실패 원인을 잘못 해석한다. 새 failure path를 추가할 때는 각 스크립트의 header와 reference row를 먼저 확인한다.
## Redaction 게이트
`local-mogui-ade-orchestrator:scripts/redaction-scan.sh`는 `gitleaks`를 matching engine으로 사용한다. 래퍼가 담당하는 부분은 scan scope 제한, commit message scan, 조직별 rule 병합, coverage 출력이다.
```console
./scripts/redaction-scan.sh
./scripts/redaction-scan.sh --staged
./scripts/redaction-scan.sh --range A..B
./scripts/redaction-scan.sh --commit-messages A..B
```
조직별 rule은 repository에 commit하지 않는다. checkout별 파일을 `REDACTION_EXTRA_PATTERNS`로 지정한다.
```text
id|description|regex
```
`REDACTION_REQUIRE_EXTRA=1` 또는 `--require-extra`를 사용하면 조직별 rule이 없거나 비어 있을 때 exit `2`로 중단한다. 기본 scan은 organization rule 없이도 generic pattern만으로 실행될 수 있으므로, green output의 `org-rules=` 값을 확인해야 한다.
```console
REDACTION_REQUIRE_EXTRA=1 \
REDACTION_EXTRA_PATTERNS=~/.config/redaction-extra.txt \
./scripts/redaction-scan.sh
```
`redaction-inventory`는 scan의 반대 질문을 묻는다. “rule이 잡은 것”이 아니라 “tracked tree에 있지만 어떤 rule도 덮지 않는 token 후보”를 보고한다. 후보 발견 exit `1`은 정상 triage 상태이며, secret 판정 자체가 아니다. 릴리스에서는 exit `2`만 판단 불가로 보고 차단한다.
redaction 도구는 repository content를 읽는다. PR title, PR body, review comment, release note, issue text, forge UI에 직접 입력한 문장은 repository scan 범위가 아니다. `local-master-ops:scripts/conversation-redaction-scan`은 PR/issue 대화 표면을 별도로 검사하는 템플릿 도구다.
## Pre-push hook
`local-mogui-ade-orchestrator:hooks/pre-push`는 clone별 opt-in hook이다.
```console
git config core.hooksPath hooks
```
hook은 Git이 stdin으로 전달한 pushed ref range를 읽고, 가능한 경우 각 range에 대해 다음 scan을 실행한다.
```console
scripts/redaction-scan.sh --range "$base..$local_sha"
```
새 ref나 fetch되지 않은 remote tip처럼 range 기준점을 직접 사용할 수 없는 경우에는 `origin/main`과의 merge-base를 시도한다. 어떤 range도 확정되지 않으면 tracked tree scan으로 fallback한다. hook은 테스트 suite를 실행하지 않는다. 빠른 redaction check만 담당한다.
## 릴리스 절차
릴리스 런북은 orchestrator release를 `MAJOR.MINOR.BUILD` 형식으로 자른다. `MAJOR.MINOR`은 owner-managed milestone이며 자동화가 올리지 않는다. `BUILD`는 `refs/remotes/origin/main`의 commit count에서 산출한다.
```console
git fetch origin main --tags
```
shallow clone이면 먼저 unshallow를 수행한다.
```console
git fetch --unshallow origin main --tags
```
```console
version="$(./scripts/next-version)"
printf '%s\n' "$version"
```
`origin/main` ref가 없거나 shallow repository이면 `scripts/next-version`은 exit `2`로 중단한다.
```console
git add -A
```
redaction scanner는 tracked content를 읽는다. 새 파일이 unstaged 상태이면 scan 대상에서 빠질 수 있다.
```console
set -e
PYTHONPATH=src uv run pytest tests -q
bash master-ops/scripts/test-tool-naming.sh
./scripts/redaction-scan.sh
rc=0
./scripts/redaction-inventory || rc=$?
if [ "$rc" -ne 0 ]; then [ "$rc" -eq 1 ] || exit "$rc"; fi
```
`CHANGELOG.md`에 `v${version}` 릴리스 노트가 있고, 링크와 날짜 문구가 맞는지 확인한다.
```console
[ -n "${version:-}" ] || exit 1
git tag "v${version}"
```
태그 생성과 tag push는 owner의 명시적 승인 뒤에만 수행한다. 자동화가 tag를 만들거나 push하지 않는다.
## 버전과 changelog 경계
`local-mogui-ade-orchestrator:CHANGELOG.md`는 orchestrator release history를 기록한다. 형식은 Keep a Changelog 계열이며, release versioning은 `MAJOR.MINOR.BUILD`다. major version이 `0`인 동안 CLI flag, file format, module interface는 minor release에서 바뀔 수 있다. 이 표면 위에 통합을 만들면 version pinning이 필요하다.
`local-master-ops` 템플릿은 별도 version stream을 가진다. `local-master-ops:TEMPLATE-VERSION`은 현재 템플릿 tag string을 담고, `local-master-ops:CHANGELOG.md`는 템플릿 변경 내역을 기록한다. onboarding이 생성한 operations repository는 템플릿의 copy이므로 기존 설치가 자동 갱신되지 않는다.
| 구분 | 위치 | 갱신 시점 | 의미 |
| --- | --- | --- | --- |
| Orchestrator release | `local-mogui-ade-orchestrator:CHANGELOG.md` | orchestrator release cut | runtime, scripts, public docs의 변경 |
| Template version | `local-master-ops:TEMPLATE-VERSION` | template release cut | 새 ops repository가 복사할 template stamp |
| Template changelog | `local-master-ops:CHANGELOG.md` | `master-ops/` 변경과 release | 설치 템플릿 변경, upgrade 판단 근거 |
| Installed manifest | `local-master-ops:MANIFEST.json` | manifest regeneration 또는 release | 설치 대상 file set과 template version stamp |
`master-ops/`를 바꾸는 변경은 같은 변경 안에서 `local-master-ops:CHANGELOG.md`의 `## Unreleased`에 항목을 추가한다. `TEMPLATE-VERSION`은 merge 때가 아니라 release cut 때 이동한다.
## CI 범위
`local-mogui-ade-orchestrator:.github/workflows/gates.yml`은 PR과 `main` push에서 테스트 job과 redaction job을 실행한다. Ubuntu와 macOS 테스트는 blocking이고, Windows leg는 measurement-only로 유지된다. CI redaction은 repository에 committed된 rule set만 사용한다. 조직별 `REDACTION_EXTRA_PATTERNS` 파일은 repository에 없으므로 전체 publish scan은 local gate에서 수행한다.
## 실패 신호
| 증상 | 의미 | 조치 |
| --- | --- | --- |
| `next-version: origin/main is unavailable` | build 산출 기준 ref가 없음 | `git fetch origin main --tags` 후 재실행 |
| `next-version: shallow clone detected` | commit count가 release 기준으로 불완전함 | `git fetch --unshallow origin main --tags` |
| `redaction-scan: WARNING ... org-rules=0` | generic rule만 적용됨 | release/publish 전 `REDACTION_EXTRA_PATTERNS`와 require flag 확인 |
| `redaction-scan` exit `1` | finding 존재 | 수정하거나 `.gitleaksignore` fingerprint 또는 `config/gitleaks.toml` allowlist로 명시적 예외 처리 |
| `redaction-scan` exit `2` | 판단 불가 | tool, config, rule compile, range resolve 문제를 먼저 해결 |
| `redaction-inventory` exit `1` | uncovered 후보 존재 | 후보를 triage하고 필요한 token은 조직 rule 또는 baseline에 반영 |
| `test-tool-naming.sh` exit `1` | 문서/skill이 호출 불가능한 tool name을 노출함 | `mcp__ctx__` 형식으로 고침 |
## Related pages
`redaction-scan.sh`, `redaction-inventory`, 조직 rule, commit message scan, pre-push hook 범위를 더 자세히 정리합니다.
공개 `scripts/` 명령, option, exit code, reference table 검증 방식을 확인합니다.
`master-ops` template version, manifest, upgrade, template-check surface를 확인합니다.
preflight, redaction 판단 불가, placement, model probe 실패 신호를 증상별로 확인합니다.
---