# CLI 레퍼런스

> scripts/ 공개 명령 표, 하위 명령 목적, 주요 옵션, --help 동기화 테스트 계약과 비공개 표면 경계.

- Repository: local/mogui-ADE-orchestrator

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

## Source Files

- `docs/public/reference.md`
- `tests/test_reference_command_table.py`
- `scripts/dispatch-gate`
- `scripts/master-succeed`
- `scripts/acceptance-loop`
- `scripts/adapter`
- `scripts/worker-reap`
- `scripts/l1-digest`

---

---
title: "CLI 레퍼런스"
description: "scripts/ 공개 명령 표, 하위 명령 목적, 주요 옵션, --help 동기화 테스트 계약과 비공개 표면 경계."
---

공개 CLI는 저장소 루트의 `scripts/` 아래 **실행 비트 있는 파일**이다. 각 엔트리는 `src/`를 자체 `sys.path`에 넣은 뒤 `master_runtime.core.*`를 호출하거나, bash로 측정을 수행한다. 네트워크 모듈·API 키 의존성은 없다. 명령 인벤토리는 `docs/public/reference.md` 표와 `tests/test_reference_command_table.py`가 `--help` 출력으로 동기화한다.

## 호출 모델

```console
$ scripts/<name> [--global-flags] <subcommand> [options]
$ scripts/<name> --help
```

| 규칙 | 동작 |
| --- | --- |
| 경로 | 저장소 루트에서 `scripts/...` 상대 경로로 실행. PATH 설치 패키지가 아님. |
| 런타임 | 대부분 `#!/usr/bin/env python3` (stdlib only). shell 스크립트: `onboarding-preflight.sh`, `redaction-scan.sh`, `next-version`, `codex-worker-pretrust`, `cursor-worker-pretrust`. |
| 소스 로딩 | Python 엔트리는 `REPO_ROOT/src`를 `sys.path`에 삽입. 별도 `PYTHONPATH` 불필요. |
| 하위 명령 | argparse subparsers. `--help` usage의 `{a,b,c}` 그룹이 공개 하위 명령 집합. |
| 하위 명령 없음 | 단일 명령으로 표에 한 행. |
| JSON | 여러 도구가 `--json`으로 기계 판독 출력을 지원. |
| Windows | `tests/windows_exec_surface.py`의 skip 마크; 실행 표면 동기화 테스트는 Unix 실행 비트를 전제로 함. |

:::files
scripts/                    # 공개 CLI 엔트리 (이 페이지 범위)
src/master_runtime/core/    # 라이브러리 구현 (직접 CLI 아님)
master-ops/scripts/         # 템플릿/인스턴스 운영 스크립트 (비공개 표면)
hooks/pre-push              # git hooksPath용; scripts/ 표 밖
docs/public/reference.md    # 손으로 쓴 명령 표 (동기화 대상)
tests/test_reference_command_table.py
:::

## 공개 명령 표

표 행 형식은 `| \`scripts/x\` | \`x sub\` | purpose | key options |`이며, 마커 `COMMAND TABLE` … `END COMMAND TABLE` 사이만 인벤토리 계약에 포함된다. 현재 측정 표면: **실행 파일 19개 · 명령 행 30개**(누락/스테이 0).

| Script | Command | Purpose | Key options |
| --- | --- | --- | --- |
| `scripts/acceptance-loop` | `acceptance-loop validate` | acceptance suite 구조 검증 | `--config` (required) |
| `scripts/acceptance-loop` | `acceptance-loop split` | suite를 visible / holdout으로 분할 | `--config`, `--output-dir` |
| `scripts/acceptance-loop` | `acceptance-loop run` | proposer에 대해 결정적 acceptance loop 실행 | `--config`, `--max-iterations`, `--baseline-ref`, `--restore-cmd` |
| `scripts/acceptance-loop` | `acceptance-loop inspect` | 실행 산출물 구성 보고(루프 미실행) | `--run-dir` (required) |
| `scripts/adapter` | `adapter doctor` | 어댑터 도구 가시성·로컬 의존성 존재 보고 | (플래그 없음; JSON stdout) |
| `scripts/codex-worker-pretrust` | `codex-worker-pretrust` | Orca-managed Codex account config에 worktree trust 기록 | positional 절대 worktree 경로; `--accounts-dir` |
| `scripts/cursor-worker-pretrust` | `cursor-worker-pretrust` | Cursor Agent trust storage에 worktree trust 기록 | positional 절대 worktree 경로; `--projects-dir` |
| `scripts/dispatch-gate` | `dispatch-gate check` | worker 계약 평가, allow/deny를 ledger에 기록 | 전역 `--ledger`; `--runtime`, `--model`, `--tier-policy`, `--tier-override`, `--no-record`, `--contract`, `--agents`, `--est-chars`, `--completion-channel` |
| `scripts/dispatch-gate` | `dispatch-gate register` | probe 성공 후 job 등록 | 전역 `--ledger`; `--job-id`, `--probe-cmd`, `--contract-sha`, `--runtime`, `--orchestration-task`, `--tier-policy`, `--declared-model`, `--model-probe-cmd` |
| `scripts/dispatch-gate` | `dispatch-gate watch` | worker 로그 stall 조건 검사 | 전역 `--ledger`; `--log`, `--max-idle` (default 360) |
| `scripts/dispatch-gate` | `dispatch-gate report` | ledger 집계(denial·override·tier·model) | 전역 `--ledger`; `--today` (UTC 당일) |
| `scripts/generate-manifest` | `generate-manifest` | Stage 1 skeleton walk → `master-ops/MANIFEST.json` | `--skeleton`, `--out`, `--check`, `--stdout` |
| `scripts/l1-digest` | `l1-digest tick` | 읽기 전용 L1 digest 1 tick | `--config` |
| `scripts/master-bootstrap` | `master-bootstrap` | charter·handoff·budget으로 bounded bootstrap 블록 생성 | `--charter`, `--handoff`, `--budget`, `--session-id`, `--strict-lease`, `--json` |
| `scripts/master-bootstrap-live` | `master-bootstrap-live` | live session-start bootstrap 블록 방출 | `--handoff-dir`, `--role-state-file`, `--budget`, `--bd`, `--charter-pointer` |
| `scripts/master-recover` | `master-recover` | recovery 입력 검사·리포트 | `--charter`, `--handoff`, `--ledger`, `--repo`, `--monitor-pattern`, `--session-id`, `--json` |
| `scripts/master-succeed` | `master-succeed detect` | succession trigger 텍스트·context pressure 분류 | `text`, `--context-ratio`, `--json` |
| `scripts/master-succeed` | `master-succeed handoff` | JSON spec에서 thin handoff 생성 | `--spec`, `--json` |
| `scripts/master-succeed` | `master-succeed verify-successor` | successor recovery report 검증 | `--report`, `--json` |
| `scripts/master-succeed` | `master-succeed check-duplicates` | marker 기준 중복 master 검출(self handle 제외) | `--self-handle`, `--marker`, `--json` |
| `scripts/master-succeed` | `master-succeed retire` | predecessor terminal/session 1개 resolve·optional close | `--self-handle`, `--expected`, `--target-*`, `--execute`, `--json` |
| `scripts/master-succeed` | `master-succeed spawn` | clean successor terminal spawn/dry-run | `--workspace-selector`, `--expected-placement`, kickoff, `--root`, `--model`, `--agent`, `--title`, `--dry-run`, `--json` |
| `scripts/model-identity-probe` | `model-identity-probe` | transcript assistant 이벤트에서 측정 model vs expect 비교 | `--transcript`, `--runtime`, `--config`, `--expect`, `--limit` |
| `scripts/model-drift-audit` | `model-drift-audit` | transcript 전 assistant turn 모델 전이 보고 | `--transcript`, `--session`, `--expect`, `--projects-dir`, `--workspace-dir`, `--ignore-synthetic`, `--json` |
| `scripts/next-version` | `next-version` | owner-managed MAJOR.MINOR + 파생 build count 출력 | `--help` only |
| `scripts/onboarding-preflight.sh` | `onboarding-preflight.sh` | 온보딩 전제 도구 측정; required 누락 시 block | `--fix`; env `PREFLIGHT_WAIVE` |
| `scripts/workspace-descriptor-check` | `workspace-descriptor-check` | path+action에 대한 descriptor 금지 여부 | `--path`, `--action`, `--config`, `--allow-unknown-repo`, `--json` |
| `scripts/redaction-inventory` | `redaction-inventory` | redaction rule이 덮지 않는 토큰(역검사) | `--baseline`, `--min-count`, `--json` |
| `scripts/redaction-scan.sh` | `redaction-scan.sh` | tracked 범위 gitleaks + 커밋 메시지 스캔 | default all tracked; `--staged`, `--range A..B`, `--commit-messages A..B` |
| `scripts/worker-reap` | `worker-reap` | settled worker terminal close + included worktree 정리 | `--task-id` \| `--dispatch-id`, `--ledger`, `--dry-run`, `--json` |

<Note>
`scripts/redaction-allowlist.txt`는 디렉터리에 남아 있으나 **실행 파일이 아니며** 명령 표에 포함되지 않는다. 허용 목록 형식은 폐기됨: 항목이 남아 있으면 `redaction-scan.sh`가 exit 2.
</Note>

## 도메인별 엔트리

### Dispatch · 등록 · 감시

`scripts/dispatch-gate` — 전역 `--ledger` (JSONL 경로).

| Subcommand | 필수 | 선택 | 성공/거부 exit (요약) |
| --- | --- | --- | --- |
| `check` | `--runtime`, `--contract`, `--agents` | `--model`, `--tier-policy`, `--tier-override`, `--no-record`, `--est-chars`, `--completion-channel {orchestration,sentinel-log}` | allow → 0; deny → 2 |
| `register` | `--job-id`, `--probe-cmd` | `--contract-sha`, `--runtime`, `--orchestration-task`, `--tier-policy`, `--declared-model`, `--model-probe-cmd` | decision JSON; orchestration 미검증 시 deny 경로 |
| `watch` | `--log` | `--max-idle` (default **360**) | stall 상태 보고 |
| `report` | — | `--today` | ledger 카운트 집계 |

<ParamField body="--no-record" type="flag">
`check`만. ledger 행 append·ticket 발급 없이 평가.
</ParamField>

<ParamField body="--completion-channel" type="orchestration | sentinel-log">
`check`에서 완료 채널 선언. `est-chars` 생략 시 channel이 있으면 contract 파일 길이로 추정.
</ParamField>

<ParamField body="--model-probe-cmd" type="string">
`register`에서 실제 worker model 측정. 프로브 timeout 상수: orchestration·model 각각 30초.
</ParamField>

<RequestExample>
```console
# Dispatch gate check (safe dry path with --no-record)
$ scripts/dispatch-gate --ledger ./gate-ledger.jsonl check \
  --runtime codex --model grok-4.5 --contract ./job-contract.md \
  --agents 1 --est-chars 1000 --completion-channel orchestration
```
</RequestExample>

세부 플래그·reason code·ledger 스키마는 [dispatch-gate 레퍼런스](/dispatch-gate-reference). 흐름 문맥은 [Supervised dispatch](/supervised-dispatch).

### Succession · recover · bootstrap

`scripts/master-succeed` 하위 명령: `detect`, `handoff`, `verify-successor`, `check-duplicates`, `retire`, `spawn`. 공통 `--json`.

| Subcommand | 핵심 입력 | 비고 |
| --- | --- | --- |
| `detect` | positional `text`; `--context-ratio` | pure 분류; 시도 안전 |
| `handoff` | `--spec` JSON 파일 | thin handoff 객체 |
| `verify-successor` | `--report` | recovery report 검증 |
| `check-duplicates` | `--self-handle`, `--marker` | 현재 핸들 제외 중복 |
| `retire` | `--self-handle`; optional targets; `--execute` | 기본은 resolve/preview; 실행은 `--execute` |
| `spawn` | `--workspace-selector`, `--root`, `--title`, kickoff one-of | `--expected-placement` 불일치 시 **exit 26** (`SPAWN_PLACEMENT_MISMATCH`) |

`spawn` 기본 model 맵(에이전트 소문자 키): `claude`/`claude-code` → `claude-fable-5`, `grok`/`grok-build` → `grok-4.5`, `codex` → `gpt-5.6-sol`. 맵에 없는 agent는 `--model` 필수(없으면 exit 2).

인접 단일 명령:

| Script | 역할 |
| --- | --- |
| `master-bootstrap` | offline bounded bootstrap (`--charter` 필수) |
| `master-bootstrap-live` | session-start 훅용 live 블록 (`--handoff-dir` 필수); 내부 오류 시 fallback 라인·exit 0 설계 |
| `master-recover` | 비정상 종료 후 charter+handoff recovery report |

세부 옵션·exit는 [master-succeed 레퍼런스](/succession-cli-reference). 루프 문맥은 [Clean succession](/succession), [마스터 라이프사이클](/master-lifecycle).

### Acceptance loop

```console
$ scripts/acceptance-loop validate --config suite.json
$ scripts/acceptance-loop split   --config suite.json --output-dir ./splits
$ scripts/acceptance-loop run     --config suite.json --max-iterations 3 \
    --baseline-ref HEAD --restore-cmd 'git checkout -- .'
$ scripts/acceptance-loop inspect --run-dir /path/to/run
```

| Subcommand | 필수 | 선택 |
| --- | --- | --- |
| `validate` | `--config` | — |
| `split` | `--config` | `--output-dir` |
| `run` | `--config` | `--max-iterations`, `--baseline-ref`, `--restore-cmd` |
| `inspect` | `--run-dir` | — |

config 로드 실패 → exit **2**. restore 타임아웃 상수 5분. 스위트·holdout 상세는 [acceptance-loop 레퍼런스](/acceptance-loop-reference).

### Model identity · drift

| Script | Exit 0 | Exit 1 | Exit 2 |
| --- | --- | --- | --- |
| `model-identity-probe` | expect 일치, 또는 expect 없이 정보만 | — | drift, undecidable, transcript 미설정 |
| `model-drift-audit` | 전이 없음 | 전이 또는 expectation 불일치 | undecidable |

`model-identity-probe` transcript 해석 순서 (`--transcript` 생략 시):

1. env `MOGUI_TRANSCRIPT_GLOB`
2. `config/instance-runtime.json` (`INSTANCE_RUNTIME_CONFIG`가 경로 override)
3. honest unconfigured (baked default path 없음) → exit 2

`model-drift-audit`의 `--projects-dir`은 호스트별 layout이라 기본값이 없다.

### Worker reap · pretrust · descriptor

**`worker-reap`**

| Flag | 의미 |
| --- | --- |
| `--task-id` \| `--dispatch-id` | 상호 배타, 하나 필수 |
| `--ledger` | reap 감사 레코드 append 경로 |
| `--dry-run` | close/remove 없이 계획만 |
| `--json` | compact JSON |

| Exit | 의미 |
| --- | --- |
| 0 | 성공 |
| 2 | task/dispatch 인자 누락 |
| 3 | dispatch not settled |
| 4 | dispatch JSON parse 실패 |
| 1 | 기타 실패 |

**Pretrust** (dispatch 전 trust prompt 회피): absolute worktree path 필수. `tomllib`/JSON 인터프리터 없으면 **설정 파일을 건드리지 않고** loud skip.

**`workspace-descriptor-check`**: exit 0 allowed, 1 prohibited, 2 unconfigured/invalid. config 해석: `--config` → `WORKSPACE_DESCRIPTOR` / `MOGUI_WORKSPACE_DESCRIPTOR` → `config/workspace-descriptor.json` → unconfigured.

### Redaction · preflight · release 유틸

| Script | Exit 0 | Exit 1 | Exit 2 |
| --- | --- | --- | --- |
| `redaction-scan.sh` | clean | findings (및 일부 도구/usage 오류 — 헤더 선언 예외) | cannot decide; `REDACTION_REQUIRE_EXTRA=1`인데 extra 비어 있음; retired allowlist 잔존 |
| `redaction-inventory` | uncovered 없음 | candidates 발견 | cannot decide |
| `onboarding-preflight.sh` | ready | blocked | — |
| `generate-manifest --check` | 일치 | drift | — |
| `next-version` | 버전 문자열 stdout | — | — |

`redaction-scan.sh` 조직 규칙: env `REDACTION_EXTRA_PATTERNS` 파일, 줄 형식 `id|description|regex`. 스테이징 전제: unstaged 신규 파일은 스캔 범위 밖.

### Adapter · L1 digest

```console
$ scripts/adapter doctor
# → {"results":[...],"present":[...],"missing":[...], ...}

$ scripts/l1-digest tick --config digest.json
```

`adapter doctor`는 결과 JSON만 출력하고 정상 시 0. `l1-digest tick`은 읽기 전용 관찰 1회.

## `--help` 동기화 계약

기계가 고정하는 것은 **인벤토리**뿐이다. purpose·key options 산문은 사람이 쓴다(`--help`에 purpose 문자열이 없음).

```text
measured_surface()  = scripts/ 실행 파일 × (--help 의 {sub,...} 또는 단일 이름)
documented_surface() = docs/public/reference.md 표 행 (Script, Command 열)
assert measured - documented == ∅   # missing rows
assert documented - measured == ∅   # stale rows
```

| 테스트 | 역할 |
| --- | --- |
| `test_reference_table_matches_the_script_surface` | 누락·스테이 행 실패 |
| `test_the_check_can_fail` | 비교가 항상 통과하지 않음을 보장(가상 gap 탐지) |

새 공개 명령을 추가할 때:

1. `scripts/`에 실행 비트 있는 엔트리 추가
2. `--help`가 subparsers면 usage에 `{...}` 노출
3. `docs/public/reference.md` 표에 행 추가
4. `PYTHONPATH=src python3 -m pytest tests/test_reference_command_table.py -q`

## 비공개 표면 경계

이 페이지·`docs/public/reference.md`가 다루는 것은 **`scripts/` 공개 명령만**이다.

| 경계 밖 | 이유 |
| --- | --- |
| `master-ops/scripts/*` (`dispatch`, `orca-wait`, `spawn-test`, hooks, …) | 온보딩이 복사하는 **템플릿** 운영 스크립트. 설치본마다 분기; 공개 인벤토리 계약 밖. |
| `src/master_runtime/**` | 라이브러리. CLI wrapper 없이 import 전제. |
| `hooks/pre-push` | `git config core.hooksPath hooks`로 활성화; `scripts/` 표 행 아님. |
| Host routing / sensitive-lane / private paths | 워크스페이스 로컬 정책. public docs가 명시적으로 제외. |
| Vendor-internal transcript layout | probe가 실패·undecidable로 **기록**할 뿐 계약 API가 아님. |

<Warning>
`master-ops/` 변경은 신규 설치에만 도달한다. 이미 복사된 operations repository는 자동 갱신되지 않는다.
</Warning>

## Exit 코드 규약 (공유 어휘 아님)

| 패턴 | 사용처 예 | 의미 |
| --- | --- | --- |
| 0 / 1 / 2 | redaction-inventory, model-drift-audit, workspace-descriptor-check | clean / finding / undecidable |
| 0 / 2 | model-identity-probe, dispatch-gate check deny | match·allow / drift·deny·undecidable 혼합 가능 |
| 0 / 1 | onboarding-preflight, generate-manifest --check | ready·일치 / blocked·drift |
| 26 | master-succeed spawn | `SPAWN_PLACEMENT_MISMATCH` |
| 0 / 2 / 3 / 4 / 1 | worker-reap | success / missing args / not settled / parse / other |

CONTRIBUTING 규칙: 새 failure path는 가능하면 **2 = could not decide**로 보내고, 처리되지 않은 예외(exit 1)가 finding처럼 보이지 않게 한다. `redaction-scan.sh`는 usage/tool 오류를 1로 접는 자체 예외를 헤더에 선언한다. **스크립트마다 행·`--help`·소스를 읽을 것.**

## 검증 신호

```console
# 인벤토리 동기화
$ PYTHONPATH=src python3 -m pytest tests/test_reference_command_table.py -q

# 단일 명령 help (동기화 테스트가 읽는 것과 동일)
$ scripts/dispatch-gate --help
$ scripts/master-succeed spawn --help

# 어댑터 존재 여부
$ scripts/adapter doctor
```

성공: reference 테스트 통과, `--help`가 표 하위 명령과 일치, doctor JSON에 기대 도구 `present`.

## Related pages

<CardGroup>
  <Card title="dispatch-gate 레퍼런스" href="/dispatch-gate-reference">
    check·register·watch·report 플래그, ledger, reason code, 티어 정책.
  </Card>
  <Card title="master-succeed 레퍼런스" href="/succession-cli-reference">
    succession 하위 명령, exit 26, JSON 출력.
  </Card>
  <Card title="acceptance-loop 레퍼런스" href="/acceptance-loop-reference">
    validate·split·run·inspect, holdout, baseline/restore.
  </Card>
  <Card title="Worker reap" href="/worker-reap">
    issued→reaped, settled 검증, dry-run, 거부 exit.
  </Card>
  <Card title="Configuration reference" href="/configuration-reference">
    INSTANCE_RUNTIME_CONFIG, DISPATCH_TIER_POLICY, WORKSPACE_DESCRIPTOR, MOGUI_* env.
  </Card>
  <Card title="Troubleshooting" href="/troubleshooting">
    preflight BLOCKED, placement mismatch, MODEL_PROBE_FAILED, undecidable.
  </Card>
  <Card title="Contributing" href="/contributing">
    pytest, exit 규약, redaction 게이트, master-ops 템플릿 경계.
  </Card>
</CardGroup>