# 온보딩 모드

> Founding, Reverify, Upgrade, Template improve 모드의 진입 조건, 금지된 spawn 경로, 단계별 파일 라우팅을 설명합니다.

- Repository: local/master-ops-with-local-mogui-ADE-orchestrator

- Human docs: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3
- Complete Markdown: https://grok-wiki.com/public/docs/local-master-ops-with-local-mogui-ade-orches-0ac7093355f3/llms-full.txt

## 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 아님 |

<Warning>
기존 ops repository 또는 `docs/lineage/MASTER-LINEAGE.md`가 보이면 Founding으로 계속 진행하지 않는다. master가 죽었거나 Gen-1 boot가 반쯤 끝난 상태도 Founding이 아니며, recovery는 설치 재실행이 아니라 ops repository의 `docs/runbooks/succession-boot-card.md`가 소유한다.
</Warning>

## 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 <runtime> \
  --model "{{MODEL_ID}}" \
  --contract <contract file> \
  --agents 1 \
  --est-chars <estimated input 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 <durable placement selector from the seat step, id: prefixed> \
  --kickoff-file <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를 추측하지 않는다.

<Steps>
<Step title="기초 사실을 확정한다">
`{{WORKSPACE_ROOT}}`, `{{OPS_REPO}}`, durable placement selector를 기존 ops repository에서 읽는다. 이 모드는 workspace facts 단계 파일을 로드하지 않는다.
</Step>

<Step title="seat와 tracker를 확인한다">
`orca terminal list --worktree <selector> --json` 결과에 live master terminal이 정확히 하나 있어야 한다. `{{WORKSPACE_ROOT}}`에서 `bd where`가 ops repository로 resolve되어야 하며, 상위 directory의 tracker database가 shadowing하면 실패다.
</Step>

<Step title="role state와 lineage를 대조한다">
`docs/runbooks/role-state.md`에는 active role이 하나여야 하고 Role Lock state가 있어야 한다. Generation은 `docs/lineage/MASTER-LINEAGE.md`의 마지막 entry와 맞아야 한다.
</Step>

<Step title="template currency를 보고한다">
template path가 있으면 `template-check --ops ... --template ...`를 실행한다. 없으면 installed `template-check --ops ...`만 실행하고 `report_set: install-manifest`로 기록한다. Reverify는 behind 상태를 고치지 않고 Upgrade로 라우팅한다.
</Step>
</Steps>

허용되는 유일한 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

<CardGroup>
<Card title="워크스페이스 Founding" href="/found-workspace">
새 workspace root 선택부터 Gen-1 spawn과 boot smoke까지의 Founding 절차.
</Card>
<Card title="마스터 승계" href="/run-succession">
dead master, long session, successor spawn은 Founding이 아니라 succession 경로에서 처리한다.
</Card>
<Card title="템플릿 참조" href="/template-reference">
`MANIFEST.json`, template version, placeholder, `template-check`, `template-apply`의 template-layer surface.
</Card>
<Card title="문제 해결" href="/troubleshooting">
misplacement, duplicate master, unavailable worktree, model probe undecidable 같은 실패 신호별 대응.
</Card>
</CardGroup>