공개 문서
operator-runbook (canonical)
아래는 learn/canonical/operator-runbook.md 와 동일한 원문입니다. Markdown과 HTML 변환 결과를 각각 복사할 수 있습니다.
공개 문서 원문 (Markdown)
# End-to-End Operator Runbook
> **정본**: Phase 86+ 운영 절차 (2026-06-10)
> **Tag**: `baseline-realignment-2026-06-10` @ **`8c2a2f8`** · **Status**: **`BASELINE_OPERATIONAL`** · **GitHub Release**: **PUBLISHED**
> **Release URL**: https://github.com/SkoolChef/MultiAgentSystem/releases/tag/baseline-realignment-2026-06-10
> **Baseline closure**: [`runs/run-077-phase95-baseline-closure/BASELINE-CLOSURE.md`](../runs/run-077-phase95-baseline-closure/BASELINE-CLOSURE.md) — Codex read-only E2E complete (run-076); Release published (Phase 102R)
> **Historical (Phase 98)**: [`runs/run-080-phase98-release-pending-and-superseded-policy/FINAL-BASELINE-STATUS.md`](../runs/run-080-phase98-release-pending-and-superseded-policy/FINAL-BASELINE-STATUS.md) — was `BASELINE_OPERATIONAL_WITH_RELEASE_PENDING` until Phase 102R
> **Post-baseline PRD (Phase 99)**: [`runs/run-081-phase99-post-baseline-prd/POST-BASELINE-PRD.md`](../runs/run-081-phase99-post-baseline-prd/POST-BASELINE-PRD.md) — Phases 100–102R doc-only; Release Pending resolved at 102R
> **대상**: MultiAgentSystem **운영자** (Orchestrator 세션을 여는 사람)
> **host**: `orchestrator_host: cursor` 기준 (다른 host는 `_shared/orchestrator-rules.md` §1)
이 문서는 Phase 79-R ~ 85-B까지 확정된 운영 기준을 **한 번에 따라 할 수 있는** 절차서다. 세부 규칙·설계 근거는 링크된 정본을 따른다.
---
## 0. 한눈에 보기
### 아키텍처
```text
Orchestrator (host-variable — worker 아님)
└── Worker pool (승인 필요)
├── claude 메인 구현 · 설계 · critique
├── codex 보조 구현 · 분석 · critique
└── gemini 멀티모달 · 장문 · 제3자 시각
```
### Verified runtime routes (Phase 83 · 3/3 PASS)
```text
claude = call_worker.sh claude (Cursor agent shell OK)
codex = MCP primary / CLI fallback (Orchestrator direct)
gemini = Mac Terminal + agy primary (agent shell 금지)
```
상세 matrix: [`_shared/runtime-route-matrix.md`](../_shared/runtime-route-matrix.md)
### 절대 금지 (운영자)
| 금지 | 이유 |
|------|------|
| `workers_approved` 없이 worker 호출 | 승인 게이트 |
| Cursor agent shell에서 `call_worker.sh gemini` | Phase 83 실패 재현 |
| worker 출력으로 자동 commit/patch (`safe_to_apply`) | 기본 `false` |
| secret·OAuth URL·API key 평문 기록 | 보안 |
| 신규 task에 legacy worker명 (`codex-main` 등) | canonical만 |
| `runs/` historical 수정·삭제 | provenance |
---
## 1. 세션 시작 체크리스트
Orchestrator 세션을 열 때 **작업 전** 확인한다.
### 1.1 환경
```bash
export MULTIAGENT_ROOT="/path/to/multi-agent-system" # 본 설치본 루트
cd "$MULTIAGENT_ROOT/.." # 또는 워크스페이스 루트
```
| # | 확인 | 기대 |
|---|------|------|
| 1 | `MULTIAGENT_ROOT` 존재 | `AGENTS.md`, `_shared/backends.json` |
| 2 | Interactive Cursor Agent | 백그라운드·worktree 격리 **아님** |
| 3 | `.cursor/rules/multi-agent-harness.mdc` | `multi-agent-system/**` 적용 |
| 4 | validate (구조 변경 후) | 11/11 PASS |
```bash
python3 <multi-agent-starter>/.../validate.py --flavor cursor --target multi-agent-system
```
### 1.2 CLI PATH (worker 호출 예정 시)
| binary | 용도 | dry-check |
|--------|------|-----------|
| `claude` | claude worker | `command -v claude` |
| `codex` | codex CLI fallback | `command -v codex` |
| `agy` | gemini (Terminal) | `command -v agy` |
| `jq` | envelope | `jq --version` |
```bash
bash "$MULTIAGENT_ROOT/_shared/adapters/call_worker.sh" --dry-resolve claude
bash "$MULTIAGENT_ROOT/_shared/adapters/call_worker.sh" --dry-resolve codex
bash "$MULTIAGENT_ROOT/_shared/adapters/call_worker.sh" --dry-resolve gemini
```
`worker_called: false` — live 호출 없음.
### 1.3 codex MCP (cursor host)
- Cursor **Settings → MCP**: codex server **Connected** (초록)
- Orchestrator가 `mcp__codex__codex` 도구 사용 가능한지 확인
- 실패 시: `call_worker.sh codex` CLI fallback (`backends.json`)
### 1.4 gemini (cursor host)
- **agy는 Mac Terminal에서만** live 호출
- agent shell에서 `agy models` / `call_worker.sh gemini` 사전 점검 **하지 말 것** (hang 위험)
- Terminal runbook: `runs/run-034-.../TERMINAL-RUNBOOK.md`
---
## 2. 새 작업 시작 (E2E)
### Step 1 — task 폴더 생성
가이드: [`_templates/task-folder.md`](../_templates/task-folder.md)
```bash
TASK=my-feature-name
ROOT="$MULTIAGENT_ROOT"
mkdir -p "$ROOT/tasks/$TASK"
cp "$ROOT/_templates/task.md" "$ROOT/tasks/$TASK/task.md"
cp "$ROOT/_templates/log.md" "$ROOT/tasks/$TASK/log.md"
cp "$ROOT/_templates/context.md" "$ROOT/tasks/$TASK/context.md"
```
### Step 2 — task.md · context.md
| 필드 | 내용 |
|------|------|
| `status` | `pending` |
| `orchestrator_host` | `cursor` |
| `goal` / `constraints` / acceptance | 작업 범위 |
| `planned_workers` | 최소 set (`routing.md`) |
| `workers_approved` | **비움** — 승인 후 채움 |
`context.md`: **현재 스냅샷만** — ≤1500자(한글) / 300단어(영문). 긴 자료는 `sources/`.
### Step 3 — worker 선택
[`_shared/routing.md`](../_shared/routing.md) decision tree:
| 작업 | 최소 set |
|------|----------|
| 단순 편집·기획 | Orchestrator만 |
| 메인 구현 | `claude` implement |
| 보조 구현·분석 | `codex` implement |
| 교차 리뷰 | `claude` or `codex` **critique** (orch ≠ worker vendor) |
| 장문·멀티모달 | `gemini` |
### Step 4 — 승인 게이트
[`_shared/approval-policy.md`](../_shared/approval-policy.md)
1. 사용자에게 worker·mode·목적·예상 횟수 설명
2. 승인 받으면 `task.md` `workers_approved` 갱신
3. `log.md`에 `[APPROVAL]` 기록
```text
[APPROVAL] worker=claude mode=implement purpose=메인 구현 approved_by=user
```
### Step 5 — brief 작성
```bash
WORKER=claude # claude | codex | gemini
mkdir -p "$ROOT/tasks/$TASK/workers/$WORKER"
cp "$ROOT/_templates/worker-brief.md" "$ROOT/tasks/$TASK/workers/$WORKER/brief.md"
```
frontmatter 예 (claude/codex):
```yaml
worker: claude
mode: implement
orchestrator_host: cursor
target_repo: /absolute/path/or-tasks-artifacts
write_scope: tasks-only
```
| 제한 | 값 |
|------|-----|
| brief | ≤1200자 / 240단어 |
| context | ≤1500자 / 300단어 |
```bash
wc -m "$ROOT/tasks/$TASK/workers/$WORKER/brief.md"
```
---
## 3. Worker 실행 (route별)
호출 **전** `log.md`:
```text
[WORKER_CALL] worker=claude brief=tasks/.../brief.md route=call_worker.sh
```
### 3.1 claude — `call_worker.sh` (agent shell OK)
```bash
export MULTIAGENT_ROOT="$ROOT"
ENVELOPE="$ROOT/tasks/$TASK/artifacts/envelope/claude-envelope.json"
mkdir -p "$(dirname "$ENVELOPE")"
bash "$ROOT/_shared/adapters/call_worker.sh" claude \
"$ROOT/tasks/$TASK/workers/claude/brief.md" > "$ENVELOPE"
```
- stdout/envelope → Orchestrator가 `workers/claude/result.md` 작성
- 외부 repo 쓰기: `AGENTS.md` 4조건 + 별도 `[APPROVAL]`
### 3.2 codex — MCP primary (Orchestrator)
**Primary (cursor host)**:
- 도구: `mcp__codex__codex`
- 인자: `prompt` = brief 본문, `sandbox: read-only`, `approval-policy: never` (smoke/정책 시)
- 응답 → Orchestrator가 `workers/codex/result.md` 기록
**CLI fallback** (MCP 불가 시):
```bash
bash "$ROOT/_shared/adapters/call_worker.sh" codex \
"$ROOT/tasks/$TASK/workers/codex/brief.md" > "$ROOT/tasks/$TASK/artifacts/envelope/codex-envelope.json"
```
- critique: `mode: critique`, `write_scope: none`, read-only sandbox
### 3.3 gemini — Mac Terminal only
**Orchestrator (cursor host)는 agent shell에서 gemini를 실행하지 않는다.**
운영자가 **Mac Terminal.app**에서:
#### A. Preflight (권장)
```bash
export MULTIAGENT_ROOT="/path/to/multi-agent-system"
which agy
agy models # 모델 목록 — OAuth 재요청 없어야 함
test -f "$MULTIAGENT_ROOT/tasks/$TASK/workers/gemini/brief.md" && echo "brief OK"
```
#### B. 본 호출 (1회 승인 범위 내)
```bash
export MULTIAGENT_ROOT="/path/to/multi-agent-system"
BRIEF="$MULTIAGENT_ROOT/tasks/$TASK/workers/gemini/brief.md"
OUT="$MULTIAGENT_ROOT/tasks/$TASK/artifacts/envelope/gemini-envelope.json"
mkdir -p "$(dirname "$OUT")"
bash "$MULTIAGENT_ROOT/_shared/adapters/call_worker.sh" gemini "$BRIEF" > "$OUT"
jq '{status, model, duration_s, fallback_used, stdout_len: (.stdout|length)}' "$OUT"
```
- 예상: 최대 ~5분 (`print_timeout` 240s, outer 300s)
- `cwd_policy: isolated_tmp` — tmp `result.md` 무시; **envelope stdout**이 정본
- Orchestrator(Cursor)가 stdout을 `workers/gemini/result.md`에 반영
참고 runbook: `runs/run-034-phase52-terminal-call-worker-verification/TERMINAL-RUNBOOK.md`
---
## 4. 결과 캡처 · envelope
| 산출물 | 위치 |
|--------|------|
| worker 응답 정본 | `tasks/<task>/workers/<worker>/result.md` |
| envelope JSON | `tasks/<task>/artifacts/envelope/` (권장) |
| 큰 파일 | `tasks/<task>/artifacts/` — result에는 경로만 |
envelope schema v2 필드 (기록용):
| 필드 | 의미 |
|------|------|
| `canonical_worker` | claude / codex / gemini |
| `mode` | implement / critique / analysis |
| `worker_called` | true |
| `safe_to_apply` | **false** (기본) |
| `fallback_used` | primary 실패 시 |
**Never trust upstream**: worker 출력은 Orchestrator가 검증 후 채택.
---
## 5. 검증 · 완료
### 5.1 Verification Checklist
`_templates/worker-result.md` 체크리스트 실행 → `log.md`:
```text
[VERIFICATION] worker=claude result=tasks/.../result.md status=ok
```
### 5.2 완료
```text
[COMPLETE] task=my-feature-name status=done
```
- `task.md` `status: done`
- 재사용 교훈(시스템 일반): `_shared/learnings.md` append
- 프로젝트 특화: `_local/learnings.md` (git 미추적)
---
## 6. 작업 재진입
이미 `tasks/<task>/`가 있을 때: [`_shared/orchestrator-rules.md`](../_shared/orchestrator-rules.md) §3
1. **재정박**: `task.md` → `context.md` → `log.md` tail → 관련 brief/result
2. **status↔log 불일치**: log가 정본 → `[DECISION]`으로 status 정정
3. **부분 재실행**: 미흡한 worker만 재호출 (승인 범위 내)
4. **실패**: 1회 재시도 → 재실패 시 `[ERROR]` 기록 후 가능한 범위 진행
---
## 7. 일반 워크플로 (예시)
### 7.1 구현 + 교차 critique
```text
1. Orchestrator: task/context 작성, planned_workers=[claude, codex]
2. [APPROVAL] claude implement, codex critique
3. claude brief → call_worker.sh → result.md
4. codex critique brief (리뷰 대상 경로 명시) → MCP read-only → result.md
5. Orchestrator: critique 반영, [VERIFICATION], [COMPLETE]
```
### 7.2 장문 문서 제3자 검토
```text
1. [APPROVAL] gemini
2. gemini brief (sources/ 경로 참조)
3. 운영자: Mac Terminal → call_worker.sh gemini
4. Orchestrator: envelope → result.md, [VERIFICATION]
```
### 7.3 Smoke (3-worker, 승인된 경우만)
| worker | 경로 | 기대 신호 |
|--------|------|-----------|
| claude | agent shell `call_worker.sh` | `CLAUDE_SMOKE_OK` |
| codex | MCP read-only | `CODEX_SMOKE_OK` |
| gemini | **Terminal** `call_worker.sh` | `GEMINI_SMOKE_OK` |
근거: `runs/run-068-*`, `runs/run-069-phase83c-gemini-retry-terminal/`
### 7.4 MultiAgent Tracker (`mat`) — read-only TUI
**이름**: **MultiAgent Tracker** · CLI: `mat` · [upstream](https://github.com/netwaif/mat)
멀티에이전트 harness를 터미널에서 **지켜보는 창**이다. `tasks/` 아래 파일을 **읽기만** 하며 harness·worker를 **고치지 않는다**.
| 담당 | 하는 일 | 하지 않는 일 |
|------|---------|--------------|
| **Orchestrator** | 작업 생성 · `[APPROVAL]` · worker 호출 · synthesis | — |
| **MultiAgent Tracker** | status/goal/workers/log/artifacts **표시** (2s 폴링) | 작업 생성 · 승인 · worker 호출 · 파일 쓰기 |
정본 repo에 mat 소스를 넣지 않는다. [`tools/mat/`](../../../tools/mat/README.md)
**설치** (택1):
```bash
brew install netwaif/tap/mat
# 또는: git clone https://github.com/netwaif/mat.git && cd mat && go build -o mat .
```
**실행**:
```bash
export MAT_ROOT="/absolute/path/to/multi-agent-system" # 또는 LAB install
mat # 활성 task 자동 선택
mat manual-core-flow-e2e # 특정 task 고정
```
활성 task 순서: ① CLI 인자 → ② `in_progress` / `reviewing` / `waiting_*` 중 최근 수정 → ③ 작업 목록 모달 (`t`).
| 키 | 동작 |
|----|------|
| `r` | 즉시 새로고침 |
| `t` | task 전환 |
| `L` / `l` | log.md 전체 모달 |
| `q` | 종료 |
**호환 (MULTIAGENT-CURSOR)**:
| 항목 | mat 동작 |
|------|----------|
| `tasks/<task>/workers/<role>/` | 디렉터리 이름으로 워커 표시 (`claude` · `codex` · legacy `codex-main` 등) |
| `planned_workers` canonical `worker:` | mat는 `role:` 만 파싱 — **폴더 없는 planned-only 행**은 생략될 수 있음 |
| brief 한 줄 목적 | 표준 brief가 ` ```yaml ` 로 시작하면 목적란 오표시 가능 (KI-1, 표시만) |
오프라인 점검: [`runs/run-093-phase121-mat-integration/mat-compat-check.py`](../runs/run-093-phase121-mat-integration/mat-compat-check.py)
**Live 확인 (2026-06-10)**: `mat manual-core-flow-e2e` — status `done`, workers `claude`/`codex`, log 태그·artifacts 표시 PASS ([`LIVE-TUI-EVIDENCE.md`](../runs/run-093-phase121-mat-integration/LIVE-TUI-EVIDENCE.md)).
---
## 8. 트러블슈팅
| 증상 | 조치 |
|------|------|
| gemini agent shell timeout/hang | **정상 정책 위반** — Terminal로 이동 |
| gemini Terminal 실패 | `agy models` preflight; OAuth·네트워크 확인 |
| codex MCP 미연결 | Cursor MCP UI Connected 확인; CLI fallback |
| `call_worker.sh` exit 124 | timeout — brief 축소 또는 print_timeout 검토 (별도 Phase) |
| API fallback blocked | `GEMINI_API_KEY` unset — primary agy(Terminal) 우선 |
| validate FAIL | `design-basis.md` / `system-invariants.md` 대조 후 수정 |
| mat 워커 목적이 `` ```yaml `` | KI-1 — brief 표시 이슈; 호출 무관. `planned_workers.purpose` 또는 mat upstream |
---
## 9. 문서 맵 (권위 순)
| 순위 | 문서 | 용도 |
|------|------|------|
| 1 | 사용자 직접 지시 | Phase 지시문 |
| 2 | 매뉴얼 PDF v2.0 | 충돌 시 정본 |
| 3 | `multi-agent-starter` templates | generator |
| 4 | **`AGENTS.md`** + **`_shared/*`** | 일상 운영 |
| 5 | **`docs/operator-runbook.md`** | **본 E2E 절차서** |
| 6 | `STRUCTURE-DESIGN.md` | 폴더 구조 |
| 7 | `runs/` | historical (읽기 전용) |
### 핵심 `_shared` 링크
| 문서 | 내용 |
|------|------|
| [`runtime-route-matrix.md`](../_shared/runtime-route-matrix.md) | verified routes + operating rules |
| [`routing.md`](../_shared/routing.md) | worker 선택 |
| [`approval-policy.md`](../_shared/approval-policy.md) | 승인 |
| [`orchestrator-rules.md`](../_shared/orchestrator-rules.md) | host·재진입·시스템 수정 |
| [`backends.json`](../_shared/backends.json) | 호출 스펙 |
| [`design-basis.md`](../_shared/design-basis.md) | D4, D8, D12 (시스템 수정 시) |
### UX 보조
| 문서 | 내용 |
|------|------|
| [`docs/ux/routing-backends-diagram.md`](./ux/routing-backends-diagram.md) | 다이어그램 |
| [`docs/ux/envelope-preview-guide.md`](./ux/envelope-preview-guide.md) | envelope 미리보기 |
---
## 10. Phase 이력 (운영 기준 확정)
| Phase | 내용 |
|-------|------|
| 79-R ~ 81 | canonical 3-worker, host-variable orchestrator |
| 82 | alias layer, template sync |
| 83 | live smoke 3/3 PASS (gemini Terminal) |
| 85 | runtime route matrix 정본 |
| **86** | **본 operator runbook** |
| 100 | baseline doc consistency polish (`25ec486`) |
| **101** | **Release publish prep** — manual UI checklist |
| **102R** | **Release URL captured** — **PUBLISHED**; **`BASELINE_OPERATIONAL`** recorded |
| **103** | **Superseded folder decision spec** — no archive/delete |
| **104** | **Superseded run archived** — moved to `runs/_archive/run-076-phase91-release-publish-and-codex-e2e/` |
---
## 11. GitHub Release — baseline (Phase 102R)
Baseline realignment GitHub Release is **PUBLISHED**. Baseline status: **`BASELINE_OPERATIONAL`**.
| Item | Value |
|------|-------|
| Tag | `baseline-realignment-2026-06-10` |
| Target commit | **`8c2a2f8`** |
| GitHub Release | **PUBLISHED** |
| Release URL | https://github.com/SkoolChef/MultiAgentSystem/releases/tag/baseline-realignment-2026-06-10 |
| Published source | manual GitHub UI publish (user-reported URL, Phase 102R) |
| Body source | [`docs/releases/baseline-realignment-2026-06-10.md`](./releases/baseline-realignment-2026-06-10.md) |
**Release Pending resolved** at Phase 102R. Cursor/automation did not publish.
### Superseded run folder (Phase 104 — archived)
**Archived** at [`runs/_archive/run-076-phase91-release-publish-and-codex-e2e/`](../runs/_archive/run-076-phase91-release-publish-and-codex-e2e/) per user `[APPROVAL] Phase 104 superseded run archive`. Original active path removed; **not deleted**.
| Item | Value |
|------|-------|
| Canonical run-076 | [`run-076-phase91-codex-e2e-approval-gate/`](../runs/run-076-phase91-codex-e2e-approval-gate/) |
| Archive notice | [`ARCHIVE-NOTICE.md`](../runs/_archive/run-076-phase91-release-publish-and-codex-e2e/ARCHIVE-NOTICE.md) |
| Decision spec | [`SUPERSEDED-RUN-FOLDER-DECISION.md`](../runs/run-081-phase99-post-baseline-prd/SUPERSEDED-RUN-FOLDER-DECISION.md) |
Delete of archived contents still requires separate explicit approval.
### Historical — manual publish prep (Phase 101)
Create-page URL (pre-publish): https://github.com/SkoolChef/MultiAgentSystem/releases/new?tag=baseline-realignment-2026-06-10
---
## 12. Phase C — 운영·품질 (Phase 111)
Post-baseline **운영·품질** 절차 (legacy alias, learnings, init 재동기화):
| topic | 정본 |
|-------|------|
| legacy → canonical `tasks/` | [`phase-c-operations-guide.md`](./phase-c-operations-guide.md) §2 |
| learnings / `_local` append-only | §3 |
| starter diff · `init.py` policy | §4 |
| **Appendix A** 체크리스트 | § Appendix A |
Evidence: [`runs/run-085-phase111-phase-c-operations/`](../runs/run-085-phase111-phase-c-operations/)
---
## 플래그 (본 문서 작성 시)
| flag | value |
|------|-------|
| `worker_called` | false |
| `live_api_called` | false |
| `safe_to_apply` | false |
공개 문서 변환 코드 (HTML)
<h1>End-to-End Operator Runbook</h1>
<blockquote>
<p><strong>정본</strong>: Phase 86+ 운영 절차 (2026-06-10)<br><strong>Tag</strong>: <code>baseline-realignment-2026-06-10</code> @ <strong><code>8c2a2f8</code></strong> · <strong>Status</strong>: <strong><code>BASELINE_OPERATIONAL</code></strong> · <strong>GitHub Release</strong>: <strong>PUBLISHED</strong><br><strong>Release URL</strong>: <a href="https://github.com/SkoolChef/MultiAgentSystem/releases/tag/baseline-realignment-2026-06-10">https://github.com/SkoolChef/MultiAgentSystem/releases/tag/baseline-realignment-2026-06-10</a><br><strong>Baseline closure</strong>: <a href="../runs/run-077-phase95-baseline-closure/BASELINE-CLOSURE.md"><code>runs/run-077-phase95-baseline-closure/BASELINE-CLOSURE.md</code></a> — Codex read-only E2E complete (run-076); Release published (Phase 102R)<br><strong>Historical (Phase 98)</strong>: <a href="../runs/run-080-phase98-release-pending-and-superseded-policy/FINAL-BASELINE-STATUS.md"><code>runs/run-080-phase98-release-pending-and-superseded-policy/FINAL-BASELINE-STATUS.md</code></a> — was <code>BASELINE_OPERATIONAL_WITH_RELEASE_PENDING</code> until Phase 102R<br><strong>Post-baseline PRD (Phase 99)</strong>: <a href="../runs/run-081-phase99-post-baseline-prd/POST-BASELINE-PRD.md"><code>runs/run-081-phase99-post-baseline-prd/POST-BASELINE-PRD.md</code></a> — Phases 100–102R doc-only; Release Pending resolved at 102R<br><strong>대상</strong>: MultiAgentSystem <strong>운영자</strong> (Orchestrator 세션을 여는 사람)<br><strong>host</strong>: <code>orchestrator_host: cursor</code> 기준 (다른 host는 <code>_shared/orchestrator-rules.md</code> §1)</p>
</blockquote>
<p>이 문서는 Phase 79-R ~ 85-B까지 확정된 운영 기준을 <strong>한 번에 따라 할 수 있는</strong> 절차서다. 세부 규칙·설계 근거는 링크된 정본을 따른다.</p>
<hr>
<h2>0. 한눈에 보기</h2>
<h3>아키텍처</h3>
<pre><code class="language-text">Orchestrator (host-variable — worker 아님)
└── Worker pool (승인 필요)
├── claude 메인 구현 · 설계 · critique
├── codex 보조 구현 · 분석 · critique
└── gemini 멀티모달 · 장문 · 제3자 시각
</code></pre>
<h3>Verified runtime routes (Phase 83 · 3/3 PASS)</h3>
<pre><code class="language-text">claude = call_worker.sh claude (Cursor agent shell OK)
codex = MCP primary / CLI fallback (Orchestrator direct)
gemini = Mac Terminal + agy primary (agent shell 금지)
</code></pre>
<p>상세 matrix: <a href="../_shared/runtime-route-matrix.md"><code>_shared/runtime-route-matrix.md</code></a></p>
<h3>절대 금지 (운영자)</h3>
<table>
<thead>
<tr>
<th>금지</th>
<th>이유</th>
</tr>
</thead>
<tbody><tr>
<td><code>workers_approved</code> 없이 worker 호출</td>
<td>승인 게이트</td>
</tr>
<tr>
<td>Cursor agent shell에서 <code>call_worker.sh gemini</code></td>
<td>Phase 83 실패 재현</td>
</tr>
<tr>
<td>worker 출력으로 자동 commit/patch (<code>safe_to_apply</code>)</td>
<td>기본 <code>false</code></td>
</tr>
<tr>
<td>secret·OAuth URL·API key 평문 기록</td>
<td>보안</td>
</tr>
<tr>
<td>신규 task에 legacy worker명 (<code>codex-main</code> 등)</td>
<td>canonical만</td>
</tr>
<tr>
<td><code>runs/</code> historical 수정·삭제</td>
<td>provenance</td>
</tr>
</tbody></table>
<hr>
<h2>1. 세션 시작 체크리스트</h2>
<p>Orchestrator 세션을 열 때 <strong>작업 전</strong> 확인한다.</p>
<h3>1.1 환경</h3>
<pre><code class="language-bash">export MULTIAGENT_ROOT="/path/to/multi-agent-system" # 본 설치본 루트
cd "$MULTIAGENT_ROOT/.." # 또는 워크스페이스 루트
</code></pre>
<table>
<thead>
<tr>
<th>#</th>
<th>확인</th>
<th>기대</th>
</tr>
</thead>
<tbody><tr>
<td>1</td>
<td><code>MULTIAGENT_ROOT</code> 존재</td>
<td><code>AGENTS.md</code>, <code>_shared/backends.json</code></td>
</tr>
<tr>
<td>2</td>
<td>Interactive Cursor Agent</td>
<td>백그라운드·worktree 격리 <strong>아님</strong></td>
</tr>
<tr>
<td>3</td>
<td><code>.cursor/rules/multi-agent-harness.mdc</code></td>
<td><code>multi-agent-system/**</code> 적용</td>
</tr>
<tr>
<td>4</td>
<td>validate (구조 변경 후)</td>
<td>11/11 PASS</td>
</tr>
</tbody></table>
<pre><code class="language-bash">python3 <multi-agent-starter>/.../validate.py --flavor cursor --target multi-agent-system
</code></pre>
<h3>1.2 CLI PATH (worker 호출 예정 시)</h3>
<table>
<thead>
<tr>
<th>binary</th>
<th>용도</th>
<th>dry-check</th>
</tr>
</thead>
<tbody><tr>
<td><code>claude</code></td>
<td>claude worker</td>
<td><code>command -v claude</code></td>
</tr>
<tr>
<td><code>codex</code></td>
<td>codex CLI fallback</td>
<td><code>command -v codex</code></td>
</tr>
<tr>
<td><code>agy</code></td>
<td>gemini (Terminal)</td>
<td><code>command -v agy</code></td>
</tr>
<tr>
<td><code>jq</code></td>
<td>envelope</td>
<td><code>jq --version</code></td>
</tr>
</tbody></table>
<pre><code class="language-bash">bash "$MULTIAGENT_ROOT/_shared/adapters/call_worker.sh" --dry-resolve claude
bash "$MULTIAGENT_ROOT/_shared/adapters/call_worker.sh" --dry-resolve codex
bash "$MULTIAGENT_ROOT/_shared/adapters/call_worker.sh" --dry-resolve gemini
</code></pre>
<p><code>worker_called: false</code> — live 호출 없음.</p>
<h3>1.3 codex MCP (cursor host)</h3>
<ul>
<li>Cursor <strong>Settings → MCP</strong>: codex server <strong>Connected</strong> (초록)</li>
<li>Orchestrator가 <code>mcp__codex__codex</code> 도구 사용 가능한지 확인</li>
<li>실패 시: <code>call_worker.sh codex</code> CLI fallback (<code>backends.json</code>)</li>
</ul>
<h3>1.4 gemini (cursor host)</h3>
<ul>
<li><strong>agy는 Mac Terminal에서만</strong> live 호출</li>
<li>agent shell에서 <code>agy models</code> / <code>call_worker.sh gemini</code> 사전 점검 <strong>하지 말 것</strong> (hang 위험)</li>
<li>Terminal runbook: <code>runs/run-034-.../TERMINAL-RUNBOOK.md</code></li>
</ul>
<hr>
<h2>2. 새 작업 시작 (E2E)</h2>
<h3>Step 1 — task 폴더 생성</h3>
<p>가이드: <a href="../_templates/task-folder.md"><code>_templates/task-folder.md</code></a></p>
<pre><code class="language-bash">TASK=my-feature-name
ROOT="$MULTIAGENT_ROOT"
mkdir -p "$ROOT/tasks/$TASK"
cp "$ROOT/_templates/task.md" "$ROOT/tasks/$TASK/task.md"
cp "$ROOT/_templates/log.md" "$ROOT/tasks/$TASK/log.md"
cp "$ROOT/_templates/context.md" "$ROOT/tasks/$TASK/context.md"
</code></pre>
<h3>Step 2 — task.md · context.md</h3>
<table>
<thead>
<tr>
<th>필드</th>
<th>내용</th>
</tr>
</thead>
<tbody><tr>
<td><code>status</code></td>
<td><code>pending</code></td>
</tr>
<tr>
<td><code>orchestrator_host</code></td>
<td><code>cursor</code></td>
</tr>
<tr>
<td><code>goal</code> / <code>constraints</code> / acceptance</td>
<td>작업 범위</td>
</tr>
<tr>
<td><code>planned_workers</code></td>
<td>최소 set (<code>routing.md</code>)</td>
</tr>
<tr>
<td><code>workers_approved</code></td>
<td><strong>비움</strong> — 승인 후 채움</td>
</tr>
</tbody></table>
<p><code>context.md</code>: <strong>현재 스냅샷만</strong> — ≤1500자(한글) / 300단어(영문). 긴 자료는 <code>sources/</code>.</p>
<h3>Step 3 — worker 선택</h3>
<p><a href="../_shared/routing.md"><code>_shared/routing.md</code></a> decision tree:</p>
<table>
<thead>
<tr>
<th>작업</th>
<th>최소 set</th>
</tr>
</thead>
<tbody><tr>
<td>단순 편집·기획</td>
<td>Orchestrator만</td>
</tr>
<tr>
<td>메인 구현</td>
<td><code>claude</code> implement</td>
</tr>
<tr>
<td>보조 구현·분석</td>
<td><code>codex</code> implement</td>
</tr>
<tr>
<td>교차 리뷰</td>
<td><code>claude</code> or <code>codex</code> <strong>critique</strong> (orch ≠ worker vendor)</td>
</tr>
<tr>
<td>장문·멀티모달</td>
<td><code>gemini</code></td>
</tr>
</tbody></table>
<h3>Step 4 — 승인 게이트</h3>
<p><a href="../_shared/approval-policy.md"><code>_shared/approval-policy.md</code></a></p>
<ol>
<li>사용자에게 worker·mode·목적·예상 횟수 설명</li>
<li>승인 받으면 <code>task.md</code> <code>workers_approved</code> 갱신</li>
<li><code>log.md</code>에 <code>[APPROVAL]</code> 기록</li>
</ol>
<pre><code class="language-text">[APPROVAL] worker=claude mode=implement purpose=메인 구현 approved_by=user
</code></pre>
<h3>Step 5 — brief 작성</h3>
<pre><code class="language-bash">WORKER=claude # claude | codex | gemini
mkdir -p "$ROOT/tasks/$TASK/workers/$WORKER"
cp "$ROOT/_templates/worker-brief.md" "$ROOT/tasks/$TASK/workers/$WORKER/brief.md"
</code></pre>
<p>frontmatter 예 (claude/codex):</p>
<pre><code class="language-yaml">worker: claude
mode: implement
orchestrator_host: cursor
target_repo: /absolute/path/or-tasks-artifacts
write_scope: tasks-only
</code></pre>
<table>
<thead>
<tr>
<th>제한</th>
<th>값</th>
</tr>
</thead>
<tbody><tr>
<td>brief</td>
<td>≤1200자 / 240단어</td>
</tr>
<tr>
<td>context</td>
<td>≤1500자 / 300단어</td>
</tr>
</tbody></table>
<pre><code class="language-bash">wc -m "$ROOT/tasks/$TASK/workers/$WORKER/brief.md"
</code></pre>
<hr>
<h2>3. Worker 실행 (route별)</h2>
<p>호출 <strong>전</strong> <code>log.md</code>:</p>
<pre><code class="language-text">[WORKER_CALL] worker=claude brief=tasks/.../brief.md route=call_worker.sh
</code></pre>
<h3>3.1 claude — <code>call_worker.sh</code> (agent shell OK)</h3>
<pre><code class="language-bash">export MULTIAGENT_ROOT="$ROOT"
ENVELOPE="$ROOT/tasks/$TASK/artifacts/envelope/claude-envelope.json"
mkdir -p "$(dirname "$ENVELOPE")"
bash "$ROOT/_shared/adapters/call_worker.sh" claude \
"$ROOT/tasks/$TASK/workers/claude/brief.md" > "$ENVELOPE"
</code></pre>
<ul>
<li>stdout/envelope → Orchestrator가 <code>workers/claude/result.md</code> 작성</li>
<li>외부 repo 쓰기: <code>AGENTS.md</code> 4조건 + 별도 <code>[APPROVAL]</code></li>
</ul>
<h3>3.2 codex — MCP primary (Orchestrator)</h3>
<p><strong>Primary (cursor host)</strong>:</p>
<ul>
<li>도구: <code>mcp__codex__codex</code></li>
<li>인자: <code>prompt</code> = brief 본문, <code>sandbox: read-only</code>, <code>approval-policy: never</code> (smoke/정책 시)</li>
<li>응답 → Orchestrator가 <code>workers/codex/result.md</code> 기록</li>
</ul>
<p><strong>CLI fallback</strong> (MCP 불가 시):</p>
<pre><code class="language-bash">bash "$ROOT/_shared/adapters/call_worker.sh" codex \
"$ROOT/tasks/$TASK/workers/codex/brief.md" > "$ROOT/tasks/$TASK/artifacts/envelope/codex-envelope.json"
</code></pre>
<ul>
<li>critique: <code>mode: critique</code>, <code>write_scope: none</code>, read-only sandbox</li>
</ul>
<h3>3.3 gemini — Mac Terminal only</h3>
<p><strong>Orchestrator (cursor host)는 agent shell에서 gemini를 실행하지 않는다.</strong></p>
<p>운영자가 <strong>Mac Terminal.app</strong>에서:</p>
<h4>A. Preflight (권장)</h4>
<pre><code class="language-bash">export MULTIAGENT_ROOT="/path/to/multi-agent-system"
which agy
agy models # 모델 목록 — OAuth 재요청 없어야 함
test -f "$MULTIAGENT_ROOT/tasks/$TASK/workers/gemini/brief.md" && echo "brief OK"
</code></pre>
<h4>B. 본 호출 (1회 승인 범위 내)</h4>
<pre><code class="language-bash">export MULTIAGENT_ROOT="/path/to/multi-agent-system"
BRIEF="$MULTIAGENT_ROOT/tasks/$TASK/workers/gemini/brief.md"
OUT="$MULTIAGENT_ROOT/tasks/$TASK/artifacts/envelope/gemini-envelope.json"
mkdir -p "$(dirname "$OUT")"
bash "$MULTIAGENT_ROOT/_shared/adapters/call_worker.sh" gemini "$BRIEF" > "$OUT"
jq '{status, model, duration_s, fallback_used, stdout_len: (.stdout|length)}' "$OUT"
</code></pre>
<ul>
<li>예상: 최대 ~5분 (<code>print_timeout</code> 240s, outer 300s)</li>
<li><code>cwd_policy: isolated_tmp</code> — tmp <code>result.md</code> 무시; <strong>envelope stdout</strong>이 정본</li>
<li>Orchestrator(Cursor)가 stdout을 <code>workers/gemini/result.md</code>에 반영</li>
</ul>
<p>참고 runbook: <code>runs/run-034-phase52-terminal-call-worker-verification/TERMINAL-RUNBOOK.md</code></p>
<hr>
<h2>4. 결과 캡처 · envelope</h2>
<table>
<thead>
<tr>
<th>산출물</th>
<th>위치</th>
</tr>
</thead>
<tbody><tr>
<td>worker 응답 정본</td>
<td><code>tasks/<task>/workers/<worker>/result.md</code></td>
</tr>
<tr>
<td>envelope JSON</td>
<td><code>tasks/<task>/artifacts/envelope/</code> (권장)</td>
</tr>
<tr>
<td>큰 파일</td>
<td><code>tasks/<task>/artifacts/</code> — result에는 경로만</td>
</tr>
</tbody></table>
<p>envelope schema v2 필드 (기록용):</p>
<table>
<thead>
<tr>
<th>필드</th>
<th>의미</th>
</tr>
</thead>
<tbody><tr>
<td><code>canonical_worker</code></td>
<td>claude / codex / gemini</td>
</tr>
<tr>
<td><code>mode</code></td>
<td>implement / critique / analysis</td>
</tr>
<tr>
<td><code>worker_called</code></td>
<td>true</td>
</tr>
<tr>
<td><code>safe_to_apply</code></td>
<td><strong>false</strong> (기본)</td>
</tr>
<tr>
<td><code>fallback_used</code></td>
<td>primary 실패 시</td>
</tr>
</tbody></table>
<p><strong>Never trust upstream</strong>: worker 출력은 Orchestrator가 검증 후 채택.</p>
<hr>
<h2>5. 검증 · 완료</h2>
<h3>5.1 Verification Checklist</h3>
<p><code>_templates/worker-result.md</code> 체크리스트 실행 → <code>log.md</code>:</p>
<pre><code class="language-text">[VERIFICATION] worker=claude result=tasks/.../result.md status=ok
</code></pre>
<h3>5.2 완료</h3>
<pre><code class="language-text">[COMPLETE] task=my-feature-name status=done
</code></pre>
<ul>
<li><code>task.md</code> <code>status: done</code></li>
<li>재사용 교훈(시스템 일반): <code>_shared/learnings.md</code> append</li>
<li>프로젝트 특화: <code>_local/learnings.md</code> (git 미추적)</li>
</ul>
<hr>
<h2>6. 작업 재진입</h2>
<p>이미 <code>tasks/<task>/</code>가 있을 때: <a href="../_shared/orchestrator-rules.md"><code>_shared/orchestrator-rules.md</code></a> §3</p>
<ol>
<li><strong>재정박</strong>: <code>task.md</code> → <code>context.md</code> → <code>log.md</code> tail → 관련 brief/result</li>
<li><strong>status↔log 불일치</strong>: log가 정본 → <code>[DECISION]</code>으로 status 정정</li>
<li><strong>부분 재실행</strong>: 미흡한 worker만 재호출 (승인 범위 내)</li>
<li><strong>실패</strong>: 1회 재시도 → 재실패 시 <code>[ERROR]</code> 기록 후 가능한 범위 진행</li>
</ol>
<hr>
<h2>7. 일반 워크플로 (예시)</h2>
<h3>7.1 구현 + 교차 critique</h3>
<pre><code class="language-text">1. Orchestrator: task/context 작성, planned_workers=[claude, codex]
2. [APPROVAL] claude implement, codex critique
3. claude brief → call_worker.sh → result.md
4. codex critique brief (리뷰 대상 경로 명시) → MCP read-only → result.md
5. Orchestrator: critique 반영, [VERIFICATION], [COMPLETE]
</code></pre>
<h3>7.2 장문 문서 제3자 검토</h3>
<pre><code class="language-text">1. [APPROVAL] gemini
2. gemini brief (sources/ 경로 참조)
3. 운영자: Mac Terminal → call_worker.sh gemini
4. Orchestrator: envelope → result.md, [VERIFICATION]
</code></pre>
<h3>7.3 Smoke (3-worker, 승인된 경우만)</h3>
<table>
<thead>
<tr>
<th>worker</th>
<th>경로</th>
<th>기대 신호</th>
</tr>
</thead>
<tbody><tr>
<td>claude</td>
<td>agent shell <code>call_worker.sh</code></td>
<td><code>CLAUDE_SMOKE_OK</code></td>
</tr>
<tr>
<td>codex</td>
<td>MCP read-only</td>
<td><code>CODEX_SMOKE_OK</code></td>
</tr>
<tr>
<td>gemini</td>
<td><strong>Terminal</strong> <code>call_worker.sh</code></td>
<td><code>GEMINI_SMOKE_OK</code></td>
</tr>
</tbody></table>
<p>근거: <code>runs/run-068-*</code>, <code>runs/run-069-phase83c-gemini-retry-terminal/</code></p>
<h3>7.4 MultiAgent Tracker (<code>mat</code>) — read-only TUI</h3>
<p><strong>이름</strong>: <strong>MultiAgent Tracker</strong> · CLI: <code>mat</code> · <a href="https://github.com/netwaif/mat">upstream</a></p>
<p>멀티에이전트 harness를 터미널에서 <strong>지켜보는 창</strong>이다. <code>tasks/</code> 아래 파일을 <strong>읽기만</strong> 하며 harness·worker를 <strong>고치지 않는다</strong>.</p>
<table>
<thead>
<tr>
<th>담당</th>
<th>하는 일</th>
<th>하지 않는 일</th>
</tr>
</thead>
<tbody><tr>
<td><strong>Orchestrator</strong></td>
<td>작업 생성 · <code>[APPROVAL]</code> · worker 호출 · synthesis</td>
<td>—</td>
</tr>
<tr>
<td><strong>MultiAgent Tracker</strong></td>
<td>status/goal/workers/log/artifacts <strong>표시</strong> (2s 폴링)</td>
<td>작업 생성 · 승인 · worker 호출 · 파일 쓰기</td>
</tr>
</tbody></table>
<p>정본 repo에 mat 소스를 넣지 않는다. <a href="../../../tools/mat/README.md"><code>tools/mat/</code></a></p>
<p><strong>설치</strong> (택1):</p>
<pre><code class="language-bash">brew install netwaif/tap/mat
# 또는: git clone https://github.com/netwaif/mat.git && cd mat && go build -o mat .
</code></pre>
<p><strong>실행</strong>:</p>
<pre><code class="language-bash">export MAT_ROOT="/absolute/path/to/multi-agent-system" # 또는 LAB install
mat # 활성 task 자동 선택
mat manual-core-flow-e2e # 특정 task 고정
</code></pre>
<p>활성 task 순서: ① CLI 인자 → ② <code>in_progress</code> / <code>reviewing</code> / <code>waiting_*</code> 중 최근 수정 → ③ 작업 목록 모달 (<code>t</code>).</p>
<table>
<thead>
<tr>
<th>키</th>
<th>동작</th>
</tr>
</thead>
<tbody><tr>
<td><code>r</code></td>
<td>즉시 새로고침</td>
</tr>
<tr>
<td><code>t</code></td>
<td>task 전환</td>
</tr>
<tr>
<td><code>L</code> / <code>l</code></td>
<td>log.md 전체 모달</td>
</tr>
<tr>
<td><code>q</code></td>
<td>종료</td>
</tr>
</tbody></table>
<p><strong>호환 (MULTIAGENT-CURSOR)</strong>:</p>
<table>
<thead>
<tr>
<th>항목</th>
<th>mat 동작</th>
</tr>
</thead>
<tbody><tr>
<td><code>tasks/<task>/workers/<role>/</code></td>
<td>디렉터리 이름으로 워커 표시 (<code>claude</code> · <code>codex</code> · legacy <code>codex-main</code> 등)</td>
</tr>
<tr>
<td><code>planned_workers</code> canonical <code>worker:</code></td>
<td>mat는 <code>role:</code> 만 파싱 — <strong>폴더 없는 planned-only 행</strong>은 생략될 수 있음</td>
</tr>
<tr>
<td>brief 한 줄 목적</td>
<td>표준 brief가 <code>```yaml</code> 로 시작하면 목적란 오표시 가능 (KI-1, 표시만)</td>
</tr>
</tbody></table>
<p>오프라인 점검: <a href="../runs/run-093-phase121-mat-integration/mat-compat-check.py"><code>runs/run-093-phase121-mat-integration/mat-compat-check.py</code></a></p>
<p><strong>Live 확인 (2026-06-10)</strong>: <code>mat manual-core-flow-e2e</code> — status <code>done</code>, workers <code>claude</code>/<code>codex</code>, log 태그·artifacts 표시 PASS (<a href="../runs/run-093-phase121-mat-integration/LIVE-TUI-EVIDENCE.md"><code>LIVE-TUI-EVIDENCE.md</code></a>).</p>
<hr>
<h2>8. 트러블슈팅</h2>
<table>
<thead>
<tr>
<th>증상</th>
<th>조치</th>
</tr>
</thead>
<tbody><tr>
<td>gemini agent shell timeout/hang</td>
<td><strong>정상 정책 위반</strong> — Terminal로 이동</td>
</tr>
<tr>
<td>gemini Terminal 실패</td>
<td><code>agy models</code> preflight; OAuth·네트워크 확인</td>
</tr>
<tr>
<td>codex MCP 미연결</td>
<td>Cursor MCP UI Connected 확인; CLI fallback</td>
</tr>
<tr>
<td><code>call_worker.sh</code> exit 124</td>
<td>timeout — brief 축소 또는 print_timeout 검토 (별도 Phase)</td>
</tr>
<tr>
<td>API fallback blocked</td>
<td><code>GEMINI_API_KEY</code> unset — primary agy(Terminal) 우선</td>
</tr>
<tr>
<td>validate FAIL</td>
<td><code>design-basis.md</code> / <code>system-invariants.md</code> 대조 후 수정</td>
</tr>
<tr>
<td>mat 워커 목적이 <code>```yaml</code></td>
<td>KI-1 — brief 표시 이슈; 호출 무관. <code>planned_workers.purpose</code> 또는 mat upstream</td>
</tr>
</tbody></table>
<hr>
<h2>9. 문서 맵 (권위 순)</h2>
<table>
<thead>
<tr>
<th>순위</th>
<th>문서</th>
<th>용도</th>
</tr>
</thead>
<tbody><tr>
<td>1</td>
<td>사용자 직접 지시</td>
<td>Phase 지시문</td>
</tr>
<tr>
<td>2</td>
<td>매뉴얼 PDF v2.0</td>
<td>충돌 시 정본</td>
</tr>
<tr>
<td>3</td>
<td><code>multi-agent-starter</code> templates</td>
<td>generator</td>
</tr>
<tr>
<td>4</td>
<td><strong><code>AGENTS.md</code></strong> + <strong><code>_shared/*</code></strong></td>
<td>일상 운영</td>
</tr>
<tr>
<td>5</td>
<td><strong><code>docs/operator-runbook.md</code></strong></td>
<td><strong>본 E2E 절차서</strong></td>
</tr>
<tr>
<td>6</td>
<td><code>STRUCTURE-DESIGN.md</code></td>
<td>폴더 구조</td>
</tr>
<tr>
<td>7</td>
<td><code>runs/</code></td>
<td>historical (읽기 전용)</td>
</tr>
</tbody></table>
<h3>핵심 <code>_shared</code> 링크</h3>
<table>
<thead>
<tr>
<th>문서</th>
<th>내용</th>
</tr>
</thead>
<tbody><tr>
<td><a href="../_shared/runtime-route-matrix.md"><code>runtime-route-matrix.md</code></a></td>
<td>verified routes + operating rules</td>
</tr>
<tr>
<td><a href="../_shared/routing.md"><code>routing.md</code></a></td>
<td>worker 선택</td>
</tr>
<tr>
<td><a href="../_shared/approval-policy.md"><code>approval-policy.md</code></a></td>
<td>승인</td>
</tr>
<tr>
<td><a href="../_shared/orchestrator-rules.md"><code>orchestrator-rules.md</code></a></td>
<td>host·재진입·시스템 수정</td>
</tr>
<tr>
<td><a href="../_shared/backends.json"><code>backends.json</code></a></td>
<td>호출 스펙</td>
</tr>
<tr>
<td><a href="../_shared/design-basis.md"><code>design-basis.md</code></a></td>
<td>D4, D8, D12 (시스템 수정 시)</td>
</tr>
</tbody></table>
<h3>UX 보조</h3>
<table>
<thead>
<tr>
<th>문서</th>
<th>내용</th>
</tr>
</thead>
<tbody><tr>
<td><a href="./ux/routing-backends-diagram.md"><code>docs/ux/routing-backends-diagram.md</code></a></td>
<td>다이어그램</td>
</tr>
<tr>
<td><a href="./ux/envelope-preview-guide.md"><code>docs/ux/envelope-preview-guide.md</code></a></td>
<td>envelope 미리보기</td>
</tr>
</tbody></table>
<hr>
<h2>10. Phase 이력 (운영 기준 확정)</h2>
<table>
<thead>
<tr>
<th>Phase</th>
<th>내용</th>
</tr>
</thead>
<tbody><tr>
<td>79-R ~ 81</td>
<td>canonical 3-worker, host-variable orchestrator</td>
</tr>
<tr>
<td>82</td>
<td>alias layer, template sync</td>
</tr>
<tr>
<td>83</td>
<td>live smoke 3/3 PASS (gemini Terminal)</td>
</tr>
<tr>
<td>85</td>
<td>runtime route matrix 정본</td>
</tr>
<tr>
<td><strong>86</strong></td>
<td><strong>본 operator runbook</strong></td>
</tr>
<tr>
<td>100</td>
<td>baseline doc consistency polish (<code>25ec486</code>)</td>
</tr>
<tr>
<td><strong>101</strong></td>
<td><strong>Release publish prep</strong> — manual UI checklist</td>
</tr>
<tr>
<td><strong>102R</strong></td>
<td><strong>Release URL captured</strong> — <strong>PUBLISHED</strong>; <strong><code>BASELINE_OPERATIONAL</code></strong> recorded</td>
</tr>
<tr>
<td><strong>103</strong></td>
<td><strong>Superseded folder decision spec</strong> — no archive/delete</td>
</tr>
<tr>
<td><strong>104</strong></td>
<td><strong>Superseded run archived</strong> — moved to <code>runs/_archive/run-076-phase91-release-publish-and-codex-e2e/</code></td>
</tr>
</tbody></table>
<hr>
<h2>11. GitHub Release — baseline (Phase 102R)</h2>
<p>Baseline realignment GitHub Release is <strong>PUBLISHED</strong>. Baseline status: <strong><code>BASELINE_OPERATIONAL</code></strong>.</p>
<table>
<thead>
<tr>
<th>Item</th>
<th>Value</th>
</tr>
</thead>
<tbody><tr>
<td>Tag</td>
<td><code>baseline-realignment-2026-06-10</code></td>
</tr>
<tr>
<td>Target commit</td>
<td><strong><code>8c2a2f8</code></strong></td>
</tr>
<tr>
<td>GitHub Release</td>
<td><strong>PUBLISHED</strong></td>
</tr>
<tr>
<td>Release URL</td>
<td><a href="https://github.com/SkoolChef/MultiAgentSystem/releases/tag/baseline-realignment-2026-06-10">https://github.com/SkoolChef/MultiAgentSystem/releases/tag/baseline-realignment-2026-06-10</a></td>
</tr>
<tr>
<td>Published source</td>
<td>manual GitHub UI publish (user-reported URL, Phase 102R)</td>
</tr>
<tr>
<td>Body source</td>
<td><a href="./releases/baseline-realignment-2026-06-10.md"><code>docs/releases/baseline-realignment-2026-06-10.md</code></a></td>
</tr>
</tbody></table>
<p><strong>Release Pending resolved</strong> at Phase 102R. Cursor/automation did not publish.</p>
<h3>Superseded run folder (Phase 104 — archived)</h3>
<p><strong>Archived</strong> at <a href="../runs/_archive/run-076-phase91-release-publish-and-codex-e2e/"><code>runs/_archive/run-076-phase91-release-publish-and-codex-e2e/</code></a> per user <code>[APPROVAL] Phase 104 superseded run archive</code>. Original active path removed; <strong>not deleted</strong>.</p>
<table>
<thead>
<tr>
<th>Item</th>
<th>Value</th>
</tr>
</thead>
<tbody><tr>
<td>Canonical run-076</td>
<td><a href="../runs/run-076-phase91-codex-e2e-approval-gate/"><code>run-076-phase91-codex-e2e-approval-gate/</code></a></td>
</tr>
<tr>
<td>Archive notice</td>
<td><a href="../runs/_archive/run-076-phase91-release-publish-and-codex-e2e/ARCHIVE-NOTICE.md"><code>ARCHIVE-NOTICE.md</code></a></td>
</tr>
<tr>
<td>Decision spec</td>
<td><a href="../runs/run-081-phase99-post-baseline-prd/SUPERSEDED-RUN-FOLDER-DECISION.md"><code>SUPERSEDED-RUN-FOLDER-DECISION.md</code></a></td>
</tr>
</tbody></table>
<p>Delete of archived contents still requires separate explicit approval.</p>
<h3>Historical — manual publish prep (Phase 101)</h3>
<p>Create-page URL (pre-publish): <a href="https://github.com/SkoolChef/MultiAgentSystem/releases/new?tag=baseline-realignment-2026-06-10">https://github.com/SkoolChef/MultiAgentSystem/releases/new?tag=baseline-realignment-2026-06-10</a></p>
<hr>
<h2>12. Phase C — 운영·품질 (Phase 111)</h2>
<p>Post-baseline <strong>운영·품질</strong> 절차 (legacy alias, learnings, init 재동기화):</p>
<table>
<thead>
<tr>
<th>topic</th>
<th>정본</th>
</tr>
</thead>
<tbody><tr>
<td>legacy → canonical <code>tasks/</code></td>
<td><a href="./phase-c-operations-guide.md"><code>phase-c-operations-guide.md</code></a> §2</td>
</tr>
<tr>
<td>learnings / <code>_local</code> append-only</td>
<td>§3</td>
</tr>
<tr>
<td>starter diff · <code>init.py</code> policy</td>
<td>§4</td>
</tr>
<tr>
<td><strong>Appendix A</strong> 체크리스트</td>
<td>§ Appendix A</td>
</tr>
</tbody></table>
<p>Evidence: <a href="../runs/run-085-phase111-phase-c-operations/"><code>runs/run-085-phase111-phase-c-operations/</code></a></p>
<hr>
<h2>플래그 (본 문서 작성 시)</h2>
<table>
<thead>
<tr>
<th>flag</th>
<th>value</th>
</tr>
</thead>
<tbody><tr>
<td><code>worker_called</code></td>
<td>false</td>
</tr>
<tr>
<td><code>live_api_called</code></td>
<td>false</td>
</tr>
<tr>
<td><code>safe_to_apply</code></td>
<td>false</td>
</tr>
</tbody></table>