# 프로그레시브 온보딩

> ONBOARDING 라우터, 단계 파일 1회 1로드·Verify 후 진행, Stage 1/2, founding spawn, 템플릿 치환 경계.

- 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

- `master-ops/ONBOARDING.md`
- `master-ops/onboarding/00-orientation.md`
- `master-ops/onboarding/01-preflight.md`
- `master-ops/onboarding/09-spawn.md`
- `master-ops/onboarding/10-card-and-retire.md`
- `scripts/onboarding-preflight.sh`
- `scripts/generate-manifest`
- `tests/test_onboarding_structure.py`

---

---
title: "프로그레시브 온보딩"
description: "ONBOARDING 라우터, 단계 파일 1회 1로드·Verify 후 진행, Stage 1/2, founding spawn, 템플릿 치환 경계."
---

프로그레시브 온보딩은 `master-ops/ONBOARDING.md` 라우터와 `master-ops/onboarding/` 단계 파일, `scripts/onboarding-preflight.sh` 게이트, `scripts/generate-manifest` / `MANIFEST.json` 설치 목록, founding spawn 경로(`scripts/dispatch-gate` · `scripts/master-succeed spawn` · Orca orchestration)로 구성된다. 라우터만 전체 설치 동안 유지 로드되고, 단계 파일은 **한 턴에 하나**만 읽으며 현재 단계의 **Verify**가 통과하기 전에는 다음 파일을 열지 않는다.

## 구현 표면

| 경로 | 역할 |
| --- | --- |
| `master-ops/ONBOARDING.md` | 세션 모드 분류, 에이전트 로드 규칙, 플레이스홀더 allowlist, 단계 인덱스 |
| `master-ops/onboarding/00`–`10-*.md` | Founding 경로 단계 (Owner script + Verify; 일부에 If fail) |
| `master-ops/onboarding/reverify.md` | 이미 설립된 워크스페이스 헬스 체크; **spawn 금지** |
| `master-ops/onboarding/upgrade.md` | 템플릿 레이어 드리프트 감지·적용; **spawn 금지** |
| `scripts/onboarding-preflight.sh` | Step 0 호스트 측정; exit 0 ready / 1 blocked |
| `scripts/generate-manifest` | Stage 1 스켈레톤 → `master-ops/MANIFEST.json` 생성; 설치 제외 목록 SSOT |
| `master-ops/MANIFEST.json` | 설치 파일 목록 + `template_version` (현재 스탬프 `v0.4.4`) |
| `master-ops/scripts/template-check` · `template-apply` | Upgrade/Reverify 템플릿 비교·적용 |
| `config/instance-runtime.example.json` · `config/model-tier-policy.example.json` | 인스턴스 설정 예제; 채워진 복사본은 커밋하지 않음 |
| `tests/test_onboarding_structure.py` | 인덱스·next 포인터·Verify/Owner script·플레이스홀더 allowlist 고정 |

```text
[installer session / Herald]
        |
        v
 master-ops/ONBOARDING.md  (router, stays loaded)
        |
   mode? ---- Founding ----> 00..10 one file per turn
        |                      |
        |                      +-- preflight (scripts/onboarding-preflight.sh)
        |                      +-- ops repo from MANIFEST.json (Stage 1 skeleton)
        |                      +-- founding spawn (dispatch-gate + master-succeed + orchestration)
        |                      +-- master closes installer terminal
        |
        +---- Reverify ----> reverify.md only (no spawn)
        +---- Upgrade  ----> upgrade.md only (template layer; no spawn)
        +---- Template improve -> stop onboarding; ordinary task
```

## 세션 모드 (라우터 첫 질문)

온보딩·orientation·측정 **이전**에 모드를 분류한다. 모드를 섞지 않는다. 증거가 선택과 모순되면 중단하고 증거와 함께 다시 묻는다.

| 모드 | 경로 | spawn | 요약 |
| --- | --- | --- | --- |
| **Founding** | `00` → `10` | 예 (Step 8–9) | 신규 워크스페이스: ops 저장소 구축 + Generation 1 마스터 |
| **Reverify** | `reverify.md` 단독 | **차단** | 이미 ops + 마스터가 있는 환경 헬스만 |
| **Upgrade** | `upgrade.md` 단독 | **차단** | 설립된 ops가 템플릿보다 뒤처짐; 템플릿 레이어만, 소유자 확인 후 적용 |
| **Template improve** | 온보딩 중단 | — | 이 오케스트레이터 저장소 자체 작업; 일반 작업으로 라우트 |

<Warning>
Founding 가드는 **라이브 마스터 유무만**이 아니라 **기존 ops 저장소 또는 lineage 파일**에도 걸린다. 마스터가 죽었거나 설치가 반쯤 끝난 상태는 Founding이 아니다. 트리가 있고 템플릿만 올려야 하면 **Upgrade**로 보내고, 죽은/미완 Gen-1 또는 살아있는 마스터 승계는 ops의 `docs/runbooks/succession-boot-card.md`가 소유한다. Founding을 다시 돌리면 lineage·거버넌스 기록을 오염시킨다.
</Warning>

## 프로그레시브 로드 규칙

라우터의 에이전트 규칙 (모든 호스트·모델 강제):

1. **한 턴에 단계 파일 하나** — 현재 단계 파일만. 전부 한 번에 읽지 않는다.
2. **Verify 통과 전 다음 파일 금지** — 다음 파일은 Verify 리스트가 통과한 뒤에만.
3. **Owner script** — 각 번호 단계의 소유자 대면 오프닝 템플릿. 친절·비급함 ELI5; 명령 블록·차터 전문을 소유자에게 덤프하지 않는다.
4. **If fail** — 단계에 있으면 디스크에서 다시 읽고 따른다. 없으면 즉흥 복구 금지; 중단하고 묻는다.
5. **질문** — 측정 후보가 있으면 번호 옵션 + 추천 1개(이유) + free-form. 측정 가능한데 “값만 달라”고 하지 않는다. **예외:** 워크스페이스 루트는 소유자가 선택·붙여넣기; 디스크 스캔·순위 단축 목록 금지 (`02-workspace-facts.md`).
6. **모델 강도 예외 없음** — 강한 모델도 모놀리스 읽기 권한 없음. 요약이 잘 되어도 단계 파일 스킵 권한 없음. 2026-08-03: 모놀리스 과부하·단계 생략 즉흥이 관측됨.

`tests/test_onboarding_structure.py`는 인덱스↔디스크 일치, 번호 단계 next 포인터 순서, 마지막 단계에 next 없음, 번호 단계의 `Verify`/`Owner script`, `reverify`/`upgrade`의 `Checklist`/`Report`, 플레이스홀더 allowlist, founding kill-switch 문구를 고정한다. **에이전트 읽기 순서 자체는 런타임이 강제하지 않는다** — 방어 인벤토리의 progressive-load 가드와 동일.

### 소유자 대면 언어 (라우터 standing rules)

| 기술 라벨 (에이전트/파일) | 소유자 대면 표현 |
| --- | --- |
| probe / 탐침 | 임시 터미널 또는 seat-check 터미널 |
| placement | 마스터가 Orca에서 앉는 자리 |
| selector | 기록하는 내구성 seat id |
| dispatch (첫 사용) | 워커 세션에 일을 넘김 |
| Role Lock (첫 사용) | 활성 역할 하나; 다른 역할은 소유자 잠금 해제까지 동결 |

기술 값·경로·id·명령·모델 이름·이슈 id·파일 이름은 그대로 둔다. 한 턴에 질문 도구 화면이 3개 결정을 넘으면 턴을 나눈다.

## Stage 1 / Stage 2

| 레이어 | 의미 | 위치 |
| --- | --- | --- |
| **Stage 1 skeleton** | 설치되는 ops 스켈레톤 (차터, 런북, 스크립트, `workspace-card/` 등) | `master-ops/` 중 `MANIFEST.json` `files` 목록 |
| **Stage 2 온보딩** | 스켈레톤을 동작하는 워크스페이스/오케스트레이터 ops로 만드는 설치 흐름 | 라우터 + `onboarding/` |

`scripts/generate-manifest`가 설치 제외 목록의 실행 SSOT다. 제외 예:

- **파일:** `TEMPLATE-VERSION`, `CHANGELOG.md`, `ONBOARDING.md`, …
- **디렉터리:** `onboarding/`, `docs/lineage/`, `.beads/`, 캐시 디렉터리 등

생성된 ops에는 `TEMPLATE-VERSION` · `CHANGELOG.md` · `ONBOARDING.md` · `onboarding/`이 **없어야** 한다. `MANIFEST.json` 자체는 설치되며 `template_version` 스탬프를 담는다. 프레임 위생: 설치 파일에 ADE 프레임 경로 `master-ops/` 또는 authoring 이름 `mogui-master-ops` 누출 금지 (`docs/blame/` 예외).

## Founding 단계 인덱스

시작 경로는 `00-orientation.md` → `01-preflight.md`만. 이후 파일은 해당 단계 시작 시까지 연기.

| # | 파일 | 단계 | 결정 / 산출 |
| --- | --- | --- | --- |
| 00 | `00-orientation.md` | Orientation | 시스템·3계층·종료 상태 전달 |
| 01 | `01-preflight.md` | Step 0 | preflight 통과; agent CLI 확정 |
| 02 | `02-workspace-facts.md` | Step 1 | 목적, root, 인벤토리, 이름 / monitor ns / model |
| 03 | `03-ops-repo.md` | Steps 2–3 | ops 저장소 선택·생성 (MANIFEST 복사) |
| 04 | `04-seat.md` | Step 3.5 | ops Orca 등록; durable workspace seat |
| 05 | `05-placeholders.md` | Step 4 | 플레이스홀더 치환; 세션 카드 root 배포 |
| 06 | `06-tracker.md` | Step 5 | 워크스페이스 root에서 tracker 해석 |
| 07 | `07-user-rules.md` | Step 6 | 소유자 규칙·마스터 callsign |
| 08 | `08-settings-and-skills.md` | Steps 7–7.6 | 훅·스킬 스택·publish-gate 범위 (기본 on) |
| 09 | `09-spawn.md` | Steps 8–9 | Gen-1 orchestration spawn + boot smoke |
| 10 | `10-card-and-retire.md` | Step 10 | operating card; 마스터가 installer 종료 |

### Orientation (00)

설치 세션(Herald)만 묶는 Orca Context Charter: 스냅샷 인덱스 우선, 최소 페이지 로드, 프로바이더 가정 금지. 3계층:

1. **Orchestrator** — 이 저장소 (런타임·템플릿·온보딩)
2. **Ops** — 생성되는 운영 저장소 (거버넌스)
3. **Session** — Orca 호스트 마스터 1개

종료 상태: 채워진 ops + 워크스페이스 root에서 닿는 tracker + 소유자 규칙 + **검증된 Generation 1 마스터 정확히 하나**.

### Preflight (01 / Step 0)

```console
$ cd "{{RUNTIME_ROOT}}"
$ ORCA_AGENT_CLI="<agent CLI>" bash scripts/onboarding-preflight.sh
```

`--fix`는 승인 후에만; 글로벌 Orca 스킬 추가/갱신 가능, 앱 설치는 수동.

| 결과 | 의미 |
| --- | --- |
| `READY` | 필수 체크 전부 통과, exit 0 |
| `READY WITH WAIVERS` | `PREFLIGHT_WAIVE`로 강등된 필수 있음 (만족이 아님), exit 0 |
| `BLOCKED` | FAIL 존재, exit 1 — founding 진행 금지 |

주요 라벨 (스크립트 기준):

| 라벨 | 대략 심각도 | 메모 |
| --- | --- | --- |
| `orca` | FAIL | `status --json` `ok:true`; basename `orca` / `orca-dev` / `orca-ide` |
| `orchestration` | FAIL | non-legacy Run이 이 터미널에 바인딩. legacy_read_only / run null / legacy=1 거부 |
| `skills` | FAIL | `orca-cli` + `orchestration` 아티팩트 또는 글로벌 목록 |
| `agent-cli` | FAIL | `ORCA_AGENT_CLI` 설정 + PATH |
| `worker-runtime` | FAIL/WARN | `codex` 또는 `cursor-agent` 최소 1개; 하나만 있으면 나머지는 WARN |
| `bd` · `python3` · `git` · `gh` | FAIL | 바이너리 필수 |
| `gitleaks` · `ctx` | WARN | 발행/히스토리 실무에 필요; 마스터 기동 자체는 비차단 |
| `gh-auth` | WARN | 미인증 또는 `workflow` 스코프 없음 |
| `redaction-extra` | FAIL | 조직 규칙 파일 사용 가능해야 함 |

통과 후 인스턴스 파일 (커밋 금지):

- `config/instance-runtime.json` — `master_host_runtime` = 확정 agent CLI; 해석 순서 env → 파일 → unconfigured
- `config/model-tier-policy.json` — `version: 2`; agent 인벤토리 동의 후 측정 또는 소유자 지정 목록; 게이트 해석: `DISPATCH_TIER_POLICY` → 인스턴스 파일 → `master-ops/model-tier-policy.json`

### Workspace facts → seat (02–04)

- **Root:** 소유자 붙여넣기 absolute path만 검증. 스캔·단축 목록 금지.
- **Inventory:** root 직하 Git 자식 측정 후 기본 전부 `{{REPO_LIST}}`; 외부 레인은 명시 opt-in.
- **Ops 생성:** `MANIFEST.json` 경로만 복사. 기존 ops면 Founding 중단 → Upgrade 또는 succession-boot-card.
- **Seat:** 워크스페이스 레벨 folder seat (`id:folder:<uuid>`). bare `folder:` / `path:` 는 소비자 비대칭·placement 거부. seat-check 임시 터미널 측정 후 **반드시 닫아** empty-seat 확보.

### 플레이스홀더 (05) 및 allowlist

허용 토큰만 (라우터 + structure 테스트):

`{{WORKSPACE_NAME}}` · `{{WORKSPACE_ROOT}}` · `{{OPS_REPO}}` · `{{MONITOR_NS}}` · `{{MODEL_ID}}` · `{{REPO_LIST}}` · `{{RUNTIME_ROOT}}` · `{{TEMPLATE_VERSION}}`

- `{{RUNTIME_ROOT}}` · `{{TEMPLATE_VERSION}}`은 측정; 사용자에게 묻지 않음.
- ops 아래 **남은 `{{...}}` 없음** (deferral 없음; 삭제해서 검사 통과 금지).
- `workspace-card/` 채운 뒤 root `CLAUDE.md` / `AGENTS.md`에 배포; ops root 쌍과 workspace-card 쌍은 **교차 비교하지 않음**.

### Tracker · rules · settings (06–08)

- Beads: `bd init` (승인 후), root → ops `.beads` 링크, `bd where`가 ops를 가리킴.
- 사용자 규칙·callsign 시드.
- 훅/스킬 **기본 on** (opt-out 메뉴 없음). `product-path-guard`는 `product_repo` 설정 후에 의미 있음; Bash fail-closed는 `MOGUI_PRODUCT_GUARD_FAIL_CLOSED=1` opt-in.

## Founding spawn (09) 과 installer 종료 (10)

Supervised dispatch = **Orca orchestration only**. 파일시스템 path selector 재시도, installer 안 마스터 부팅, 두 번째 세션 생성 금지.

### Step 8 게이트

1. `ORCA terminal list --worktree <selector> --json` → seat **터미널 0개**
2. `dispatch-gate check` → `allow: true` (`--completion-channel orchestration`)
3. `orchestration run-create` / `task-create`
4. `master-succeed spawn` — placement `MATCH` 또는 유효 `MATCH_REISSUED` (`handle_reissued: true`)
5. Dispatch attach + `dispatch-gate register` (동일 Task ID)
6. `orchestration check --wait` → `worker_done` / escalation / question

Kickoff 파일 (바이트 동일 전달): Gen-1, Herald 기원, callsign, 부트 시퀀스, **warm resume note**, **installer retirement switch** (`ORCA terminal close --terminal <installer handle> --json`). 측정 불가 필드는 `unavailable`; 발명 금지. Codex 워커 전 `scripts/codex-worker-pretrust`.

### Step 9 (새 마스터 세션 내부)

Role State + Role Lock, 모델 measured/unavailable/unsupported, placement 3세트, lineage Gen-1 append, `worker_done` 1회. Installer가 대신 부팅하지 않음.

### Step 10

1. 대화 검증 (파일만 있고 답 없으면 추측 설치)
2. Operating card 전문 인쇄 (플레이스홀더 치환; declined 라인 명시 또는 `none`)
3. 마스터가 identity recheck 후 installer 터미널 close + process/Orca terminal/tty 소멸 검증
4. 마스터 터미널은 유지

Installer가 스스로 닫지 않는다. “please close this installer terminal” 소유자 요청 문구는 테스트로 금지.

## Reverify / Upgrade

### Reverify

읽기 전용 (예외: 분실 operating card 재인쇄만 `10-card-and-retire.md` read-only 오픈). 체크: seat 1 마스터, tracker, role-state↔lineage, placeholders 없음, workspace-card `cmp`, `template-check` **보고만**. Spawn 금지.

### Upgrade

```console
"{{RUNTIME_ROOT}}/master-ops/scripts/template-check" --ops "{{OPS_REPO}}" --template "{{RUNTIME_ROOT}}/master-ops"
"{{RUNTIME_ROOT}}/master-ops/scripts/template-apply" --ops "{{OPS_REPO}}" --template "{{RUNTIME_ROOT}}/master-ops"
# 확인 후 --write + 확인 문구 + --placeholder KEY=VALUE ...
```

**이름 거부 (instance-owned):** `docs/lineage/`, `docs/runbooks/role-state.md`, `.beads/`, `config/`, `contracts/`, manifest 미포함 경로. Dry-run `planned` / write 후 recheck `template-compare`. Spawn 금지.

## 검증 신호

| 신호 | 기대 |
| --- | --- |
| Preflight summary | `READY` 또는 의도된 `READY WITH WAIVERS`; `BLOCKED`면 stop |
| Ops 생성 후 | 제외 디렉터리/파일 부재; `MANIFEST.json` `template_version` 일치 |
| Placeholder scan | `rg '\{\{[^}]+\}\}' "{{OPS_REPO}}"` 무히트 |
| Seat | durable `id:` selector; spawn 직전 empty seat |
| Spawn | placement MATCH/MATCH_REISSUED; 마스터 1; kickoff 바이트 일치; `worker_done` |
| Step 10 | card 인쇄; 마스터가 installer close 검증; 마스터 세션 생존 |
| Structure tests | `pytest tests/test_onboarding_structure.py` 등 |

## 트러블슈팅

| 증상 | 조치 |
| --- | --- |
| Preflight `BLOCKED` | `FAIL` 라인 수정. 합법적 예외만 `PREFLIGHT_WAIVE=<label>` (요약에 명시; 오타는 미매칭 NOTE) |
| `legacy_read_only` / unbound Run | `orca orchestration run-create` 후 preflight 재실행; 앱 재시작만으로 legacy 제거 안 됨 |
| Founding 가드 (ops 이미 존재) | Upgrade 또는 succession-boot-card; Founding 재실행 금지 |
| Seat에 기존 터미널 | 닫고 empty 재측정; 재진입 세션이 이전 spawn 실패를 가정하지 않음 |
| `SPAWN_PLACEMENT_MISMATCH` | path selector 금지; seat 단계 selector 재측정; 새 세션 |
| Residual `{{...}}` | 값 채우기 또는 중단; deferral/삭제 금지 |
| Installer close 실패 | 다른 터미널 추측 금지; 소유자에게 보고; idle |
| Template improve 혼동 | 온보딩 중단; 이 저장소 작업을 일반 작업으로 처리 |

## 관련 제약 (요약)

- Orca 필수. non-Orca 폴백 제안 금지.
- 네트워크·API 키를 이 흐름이 요구하지 않음; 프로바이더 중립 (로컬 측정·파일·셸).
- 채워진 `instance-runtime.json` / `model-tier-policy.json`은 인스턴스 소유, 예제만 템플릿에 커밋.
- Progressive load 가드: 라우터 규칙 + structure 테스트 인벤토리; 에이전트 순서는 정책 준수에 의존.

## Next

<CardGroup>
  <Card title="Quickstart" href="/quickstart">
    클론 → Orca 준비 → wake-up 온보딩 → Gen-1 → 첫 supervised worker 최단 경로.
  </Card>
  <Card title="Installation" href="/installation">
    전제조건, preflight FAIL/WARN, 셸 명령 등록, 측정 신호.
  </Card>
  <Card title="마스터 라이프사이클" href="/master-lifecycle">
    founding spawn 이후 steady state · succession · lineage.
  </Card>
  <Card title="Supervised dispatch" href="/supervised-dispatch">
    check → dispatch → register, 계약 해시, model probe, pretrust.
  </Card>
  <Card title="Clean succession" href="/succession">
    handoff, placement spawn, retire, revival — Founding 재실행 대체 경로.
  </Card>
  <Card title="방어 인벤토리" href="/defense-inventory">
    empty-seat, placement, progressive onboarding load 가드 표.
  </Card>
  <Card title="Troubleshooting" href="/troubleshooting">
    BLOCKED, placement mismatch, seat 중복, revival.
  </Card>
  <Card title="인스턴스 설정" href="/configure-instance">
    instance-runtime · model-tier-policy · env 우선순위.
  </Card>
</CardGroup>