Orchestration Loop

---
name: orchestration-loop
description: 사용자가 작업을 "오케스트레이션으로/병렬로/멀티에이전트로/체계적으로 굴려서" 처리하라고 지시할 때 사용 — 작업 크기 불문(1파일 픽스부터 에픽까지; 루프는 첫 단계에서 작업에 맞게 사이징된다). Orca CLI 명령 정본은 `orchestration` 스킬(orca skills get orchestration)이 담당하므로 두 스킬을 함께 로드해 사용.
---

# 오케스트레이션 루프 플레이북

2026-08-13 실제 제품 화면 재구축 1차 런(워커 7기·검증 6회)과 **2026-08-14 2차 런**(전면 재구축 5구역 + 후속 라운드 9회·검증 12회·계약 패치 5회·핸드오프 1회)에서 실증된 루프. 명령 문법은 `orca skills get orchestration`이 정본 — 여기 담는 것은 **구조·규칙·지뢰**다.

## 0. Phase -1 — 루프 사이징 (항상 첫 단계)

**사용자가 오케스트레이션을 지시했으면 "이 작업엔 과하다"라는 판정은 존재하지 않는다.** 이 스킬은 대형 전용이 아니다 — 작업 성격에 맞게 루프를 조립하는 설계 단계가 스킬의 일부다(2026-08-14 사용자 지시). 단일 세션 권장으로 우회하거나 일반 작업 라우팅("1파일이면 직접 처리")으로 반려하지 마라 — 명시 지시가 일반 라우팅을 오버라이드한다. 요구가 모호하면(무엇이 어색한지 미정 등) 사이징 전에 짧게 확인한다 — 이는 루프 회피가 아니라 브리프 재료 수집이다.

착수 전 수 분 내 판정 (관찰 가능한 기준만):

| 판정 | 구성 |
|---|---|
| 서로소 구역 K=1 | **S** — 구현 워커 1 + 검증자 1. Phase 0·2 생략(계약·인터페이스는 브리프에 인라인). 목표: 실작업 시간 + 오버헤드 15분 내 |
| K=2~3, 신규 공유 계약 소형·없음 | **M** — 구역 워커 병렬 + 검증자 1(도착순 처리). 신규 공유 계약 없으면 Phase 0 생략. 통합 워커 생략 — 마지막 합류 후 코디네이터 스모크로 대체. 목표 1~2시간 |
| K≥4 또는 신규 기반층 필요 | **L** — §1 풀 파이프라인(codex critic·통합 워커 포함). 화면급 구역엔 리드(§1) |

- **불변식 (규모 불문)**: 생산≠검증(최소 1검증) · 합류 동등성 검증(지뢰 8) · 오너십 대장(§2 — S는 1줄) · Phase 3 수용 기간 · 디스패치 기동 확인(지뢰 1) · 보고=주장(검증자가 대조) · **관제 레인(§6 — S는 상황판만)**.
- **가변부**: 워커 수 · Phase 0/2 유무 · 검증자 수 · codex · 리드. §1~§5는 L형 기준 서술이다 — S/M은 위 표대로 부품을 뺀 **같은 루프**다.
- **동시 활성 세션 상한 (기기 메모리가 정한다)**: 세션 1개 ≈ 0.5~0.7GB(에이전트 본체 + 세션마다 새로 뜨는 MCP 서버)로 계산해, 다른 앱 몫을 뺀 여유 램 안에서 상한을 정한다(램 18GB 기기 실측 상한 8~10). 셈은 장부가 아니라 **실제 살아 있는 세션 프로세스** 기준이며 다른 작업의 세션·같은 워크트리의 추가 세션까지 포함한다. 증설은 OS 메모리 압박 지표가 정상일 때만 2~4기씩 — 스왑 사용량은 회수가 느려 기준으로 쓰지 않는다(2026-08-22·2026-09-15 실사례: 상한 없이 20세션+ → 스왑 포화·다른 세션 테스트가 평소 5분에서 20분+).
- **사이징은 시작점이지 감옥이 아니다**: 진행 중 구역이 불어나면 승급한다(통합 브랜치에서 추가 분기 — 구조 변경 비용 없음). 속도·안전 요구가 강하면 워크트리 격리·검증 수위를 사용자와 명시 합의해 조정한다(2026-08-14 사례: "1시간 내" 요구 → 검증 간소화하되 워크트리 격리·파이프라인 검증 1기는 안전 사유로 유지 제안·합의).
- 사이징 결과(등급·세션 수·예상 소요)를 1문단으로 보고하고 착수한다 — **루프 그림(선택 등급으로 축약한 ASCII 다이어그램: 레인·노드·흐름)을 곁들이면** 구성을 한눈에 승인받을 수 있다(2026-08-14 실증 — 터미널에서 깨지지 않는 ASCII가 정답).
- 실증 사례들은 **L형의 실증**이다. "이 작업은 그 스케일이 아니니 스킬 부적용"은 오독이다 — S/M은 같은 불변식의 축소 조립.

## 1. 루프 구조 (L형 기준 · 인터페이스 우선)

**직렬화하는 것은 "공유 계약의 명세" 단 하나다.** 계약의 구현조차 구역들과 병렬로 돈다 (2026-08-14 회고 반영 — 초판은 계약 명세+구현+검증을 한 덩어리(W0)로 직렬화해 직렬 헤드가 과대했다).

```
Phase 0  계약 명세만 (짧은 직렬) — 타입 시그니처·slot 경로·문구 키 목록·
          목 시나리오 목록을 문서·타입 파일로. 검증은 리뷰(+착수 전 codex critic 1회)
          ★계약 확정점 — 이후 동결, 변경은 ask→코디네이터 패치→broadcast
Phase 1  확정점에서 [계약 구현 워커]와 [구역 워커 N기]가 동시 분기
          구역 워커는 계약 스펙+스텁 기반으로 시작, 계약 구현 합류 시 rebase
          각 구역 태스크는 2단: ⓐ 설계 노트(결정·해석·계약 요구를 리포트에
            선기록, 계약 요구는 조기 ask) → 코디네이터 빠른 검토 → ⓑ 구현
          구현 레인: 구역마다 자식 워크트리 + 작업 브랜치
          검증 레인: 완료 도착순으로 검증자 배정 (구현과 동시 진행)
          픽스 루프: findings → 그 워커에 반송(터미널 재사용·컨텍스트 보존)
                     → scoped 재검증 — 구역 안에서만 돈다
          합류 레인: 코디네이터 직렬 — rebase → 구역 테스트 →
                     **스쿼시 머지(구역당 1커밋)** → diff 공검사 → push
          관제 레인(§6): 워치독 스크립트 + 타임아웃 전수 스윕 + 사용자 상황판
Phase 2  통합 워커(전역 수정 허용) — 종단 조립 테스트·상태 전수 대조·
          이월 체크리스트·풀스위트 1회 → 최상위 검증(opus+codex 병행) → 합류
Phase 3  ★수용 기간 (2026-08-14 사용자 피드백 — 루프는 단발성이 아니다)
          파이프라인 종료 ≠ 루프 종료. **사용자 수용 선언까지**가 한 사이클:
          · 보존하는 것 = 워크트리·브랜치·대화 기록·오너십 대장 행.
            세션 프로세스는 합류 뒤 내린다 — 유휴 세션은 토큰 0이어도
            메모리는 0이 아니다(지뢰 10). 하네스가 세션 재개 가능한
            워크스페이스 절전을 주면 그것으로 내린다
          · 검증자 세션은 검증 대기열이 비면 종료 — 재검증은 새로 띄운다
          · 이슈 재보고 → 코디네이터는 디버깅하지 않는다 — 오너십 대장으로
            구역 판별 → 보존된 그 구역 워크트리에 세션 재기동(이전 대화
            이어받기, 안 되면 §2 강등 경로) → 에픽 기반 새 픽스 브랜치에서
            수정 → scoped 재검증 → 스쿼시 재합류
          · 정리(워크트리 제거)는 수용 선언 후 + 범위 확인 질문을 거쳐
```

**병목 제거 원칙**: ① 코디네이터는 긴 작업 금지 — 라우팅·합류·계약 패치·판정만(전부 분 단위) ② 검증은 전담 레인 ③ 픽스는 구역 내부 폐쇄 ④ 직렬은 [계약 명세]와 [합류] 두 지점뿐(의도적·짧음) ⑤ 구역 설계는 병렬이되 **명시적으로**(설계 노트 단계) — 암묵 설계는 사후 보고·사후 결함으로 돌아온다 ⑥ **사용자 결정 대기와 파이프라인을 겹친다** — 판단 항목은 배치로 모아 묻되, 이미 승인된 작업은 대기 중에도 계속 돌린다(2026-08-14 실증: 재설계 논의 중 승인분 라운드 병행).

**대형 에픽 확장 — 리드 구조**: 구역 하나가 화면·서브시스템급이면 구역마다 **리드 세션**을 둔다 — [구역 설계 → 하위 구현 브리프 생산 → 자기 구역 픽스 판정]까지 위임. 단 **스폰·worker_done 수집·합류·라이프사이클은 코디네이터 중앙 유지**(스폰의 스폰 금지 — 가시성·정리 책임이 지수적으로 붕괴한다). 리드는 "브리프 공장 + 구역 검수권자"이지 프로세스 소유자가 아니다. 소형 작업(구역당 컴포넌트 1~2개)엔 리드 없이 2단 태스크로 충분.

## 2. 설계 규칙

- **구역 = 폴더.** 파일이 서로소가 되도록 자른다. 공유 부품(셸 UI·타입·목·문구)은 전부 W0로 끌어올린다 — W0가 무거워지는 건 의도된 트레이드오프. 조립 지점은 W0가 slot(플레이스홀더 파일)으로 선점해 경로·export가 곧 계약이 되게 한다. **같은 파일·구역을 속도 명목으로 병렬로 쪼개지 않는다** — 충돌 정리 비용이 병렬 이득을 잡아먹는다(같은 흐름의 원자 변경은 한 워커에 한시 권한을 넓혀 주는 쪽이 낫다).
- **계약 동결**: 병렬 중 W0 산출물(model/api/shared/문구)은 워커 수정 금지. 결함·공백은 `ask` → 코디네이터가 통합 브랜치에 패치·커밋 → 필요한 워커에 broadcast(`send --to dispatch:` — 워커는 다음 check에서 수신하므로 즉시성 없음을 감안, 합류 시 rebase가 최종 안전망). **계약 값 변경 패치는 그 값을 단언하는 테스트와 원자 커밋**으로 — 통합 브랜치를 한 커밋도 RED로 두지 않는다(2026-08-14 실증). 소범위 예외(키 1개 추가 등)는 해당 워커에 한시 권한을 명시 부여하고, 같은 파일의 다른 소유자에게 충돌 방지 공지를 보낸다.
- **문구·카피는 상수 파일 하나로**: 워커가 지어내면 반드시 어긋난다. "정본 확정 단어 수준(레이블)은 직접 t() 허용, 문장형은 상수 필수" 예외를 명문화해 패치 왕복을 줄인다.
- **브리프 구조**: 공통 1장(읽기 순서·절대 규칙·테스트 규칙·보고 계약) + 구역별 1장(산출물·정본 절 지정·검증 포인트). 파일 참조는 **절대 경로**(워커 워크트리에 없는 파일 대비). 스펙·정본 문서는 대상 레포 트리에 미리 합류시켜 두면(에픽 rebase) 워커가 자동으로 읽는다.
- **★인벤토리→브리프 전달 손실 방지 (2026-08-14 내보내기 사건)**: 사전 조사 리포트가 있는 기능을 구현으로 올릴 때, 브리프에 ① 원 조사 리포트 **절대 경로 링크** ② **기능의 본질 요약**(교환 단위·모든 경로·권한 시맨틱)을 화면 스펙보다 먼저 싣는다. 화면 요소 목록만 옮기면 본질(예: "교환 단위는 파일이 아니라 코드 문자열")이 소실돼 잘못된 화면을 만든다 — 인벤토리에 있던 사실이 브리프에서 빠진 것이 사고의 전부였다.
- **시각 전사 작업은 대조표 의무**: 정본 소스(CSS·디자인 파일)를 **직독**해 「속성 | 정본 값+라인 | 현행 | 조치」 표를 리포트에 남긴다 — 캡쳐·기억·현행 코드로 판단 금지. 이 표가 검증 레인의 입력물이다(검증자는 표를 원본과 전수 재대조 + 표에 없는 속성 누락 스캔).
- **리포트 경로는 코디네이터가 통제**: 워커가 경로를 오타 내 형제 디렉토리를 만든 실사례 2회 — 리포트 디렉토리를 사전 생성해 두고 브리프에 그대로 복붙시키거나, worker_done 수신 시 경로 실존을 즉시 확인한다. 리포트에 **"deltas/판단 후보" 섹션 의무** — 침묵 채택 금지 원칙의 착지점.
- **모델 배정 — 기준은 "브리프의 완결도"** (2026-08-14 사용자 합의): 전사·조립형 구역(계약·정본·검증 포인트가 브리프에 완결) = 중간 모델(sonnet), **명세가 안 다루는 해석·판단이 많은 구역 = 상위 모델(opus)** — 구역 분할 시점에 코디네이터가 판정. 계약 명세·최종 검증 = 항상 상위 모델. 사용자가 퀄리티 우선이면 전 워커 상위 모델로 올려도 구조 동일(픽스 라운드 감소 기대). 실측: 검증 레인이 있으면 sonnet↔opus 격차는 작다(1·2차 런 공통 — 픽스 라운드 전부 1회 클린).
- **codex(이종 모델) 배치** (2026-08-14 사용자 합의 — 가치는 동종 편향 제거): ① **계약·최종 검증 = claude opus + codex 병행**, findings는 코디네이터가 합집합 처리 ② **착수 전 계약 설계 critic으로 codex 1회**(P1/P2 처분표 관례) ③ 픽스 루프 교착(3라운드 초과) 시 이종 세컨드 오피니언 ④ **구현 워커로는 당분간 비투입** — 가드레일(CLAUDE.md 체계)을 자동 상속 못 하고 쓰기 권한의 파괴 반경이 크다. 속도 우선 합의 시 codex 생략 가능 — 합의를 기록으로.
- **워커 보고 계약**: 상세는 리포트 파일(절대 경로 지정), worker_done은 요약만. 리포트는 "주장"으로 취급 — 검증자가 재실행·대조한다.
- **오너십 대장** (`<플랜 워크스페이스>/ownership.md`): 구역 → [브리프·리포트·워크트리·세션 터미널·대화 ID·담당 커밋 범위] 매핑을 **합류 때마다 1줄 갱신**. 수용 기간 이슈 반송의 라우팅 테이블이며, 코디네이터 핸드오프·컴팩션에도 생존하는 유일한 라우팅 기억이다.
- **수용 기간 픽스 절차**: 보존된 그 구역 워크트리에서 **에픽 기반 새 브랜치**로 작업(스쿼시 합류 후 옛 구역 브랜치는 에픽 조상이 아니라 rebase 시 자기 변경과 충돌 — 구역 브랜치는 스쿼시 직후 삭제해도 잃는 것 없음, 이력은 리포트가 대신). 세션 컨텍스트가 고갈됐으면 강등 경로: 같은 워크트리에 새 세션을 [브리프+자기 리포트+검증 리포트] 로드로 재기동.
- **정본이 런 도중 갱신되면 — 핀 승격 프로토콜** (2026-08-14 실증: 디자이너 "2차 확정"을 검증자가 발견): ① 스코프 diff 전체 정독 ② 변경 요지를 제품 언어로 사용자 보고 + 반영안 제안 ③ 승인 후 핀 승격 커밋(문서) + 구역별 재전사 라운드 ④ 장부 등재. 낡은 핀으로 계속 전사하는 것도, 무단 승격도 둘 다 결함.
- **합류는 스쿼시가 기본** (1차 런에서 ff 합류로 에픽이 34커밋까지 불어난 교훈): PR 불필요 — `git merge --squash <작업브랜치>` 후 구역 요약 1커밋(`✨ feat: [티켓] W<n> <구역> — 요약 (검증 통과·픽스 R<n> 포함)`). 워커의 커밋 분할은 워커 브랜치·리포트에 남고, 통합 브랜치에는 구역당 1커밋 + 계약 패치만 쌓인다. 예외: 커밋 분할 자체가 후속 작업에 의미 있으면 코디네이터 재량으로 ff 유지.

## 3. 검증 레인 규칙

- 검증자는 **해당 워커의 워크트리에서 읽기 전용 + 구역 테스트 실행**만. 코디네이터 워크트리 상주 세션이 각 워크트리로 cd해 검증하는 방식도 실증됨(2차 런) — 터미널 재사용(`worker-start --terminal`)으로 검증 태스크를 연쇄 디스패치한다.
- 검증 태스크에 **코디네이터 룰링을 사전 전달**("이건 결함 아님" 목록) + **사전 식별 결함(F0)을 findings에 동봉** — 이미 룰링된 교정 대상을 검증 findings와 한 픽스 라운드로 합쳐 왕복을 1회 절약한다(실증). 단 룰링과 어긋난 구현을 발견하면 findings로 올리게 한다 — 검증자가 룰링 자체의 오류를 잡아 코디네이터가 번복한 사례 있음(룰링은 무오류가 아니다).
- **반박은 양방향이다**: 워커도 검증자 지적을 원본 근거로 반박할 수 있고, 판정은 원본 재확인으로 한다. 실증: 워커가 V의 라인 지적 2건을 반박해 성립, 다른 워커가 V의 정정 제안 오류를 역검증해 정확값 채택. 이 문화가 실오류를 양쪽에서 잡는다.
- **scoped 재검증**: 픽스 커밋 diff + findings 해소 여부만. 전체 재검증 아님.
- **검증 꼬리가 병목이면 검증자를 증설한다**(구역이 파일 서로소라 안전 — 2차 런 1→2 증설로 꼬리 절반). 반대로 **docs-only 산출은 검증 라운드 대신 코디네이터 스팟 대조**로 갈음 가능(비례 원칙 — 정정 행을 원본과 직접 대조).
- 검증자 산출 중 "정본 문서 내부 불일치" 발견은 사용자행 질문으로 승격(구현 차단 없이).

## 4. 지뢰 목록 (증상 → 처치)

1. **Enter 미제출 레이스 — 상습(2차 런 5회+)** — dispatch --inject/worker-start 후 프롬프트가 입력창에 걸린 채 방치(수십 분 유실). 신호: 비용 $0.00, worker-read `source: terminal`. 처치: **모든 디스패치(구현·검증·재검증·재사용 불문) 직후 기동 확인 루프를 표준 절차로** — `worker-read source == "transcript"`가 될 때까지 `terminal send --enter` 재전송. 매번 같은 패턴이므로 셸 스니펫으로 만들어 디스패치 명령 꼬리에 상시 붙인다.
2. **크로스 레포 가시성** — 워커는 **대상 레포 그룹**에 생긴다(코디네이터가 있는 워크스페이스가 아니라). 처치: 생성 즉시 ① 표시명 `[티켓] 역할` 지정 ② 대상 레포 본체 클론을 `--parent-worktree`로 중첩(부모-자식은 같은 레포만 가능) ③ 사용자에게 "어느 레포 쪽에 생겼는지" 먼저 알림 ④ "보인다" 보고는 `terminal focus` + `computer get-app-state` 스크린샷 검증 후에만.
3. **deps 태스크 pending 고착** — 선행 태스크 완료 후에도 ready로 자동 전환 안 됨. 처치: `task-update --status ready` 수동 전환을 디스패치 직전 무조건 실행.
4. **`worker-start --terminal` 재사용** — `--worktree` 병기 필수(누락 시 현재 워크트리로 추정해 mismatch 에러).
5. **check --wait 대기자는 1개** — 중복 재장전은 `waiter_exists`로 반려(정상). 기존 대기자가 살아있으면 그대로 둔다 — 고아 waiter가 delivery를 받아도 ack 전까지 재전달되므로 유실 없음(실증).
6. **백그라운드는 하네스 기능으로만** — 셸 `&`는 완료 알림이 없어 고아가 된다. **특히 `check --ack --wait`를 foreground 명령 꼬리에 `&`로 붙이는 습관 금지** — 코디네이터 자신이 2회 위반한 상습 패턴이다(ack와 재장전은 별도 호출로).
7. **heartbeat는 소음** — ack만 하고 서사하지 않는다. done/question/escalation만 행동 트리거. 단 ack에도 상황판을 동봉하되 **하트비트 ack는 압축 1줄**(진행 중 작업·경과·ETA), **상태 전이(done·합류·라운드 전환) 때는 전체 표**(§6)로 수위를 가른다.
8. **합류 성공 주장은 동등성 검증 후에만** — `git merge` 성공 출력·echo 체인은 거짓 성공을 찍는다(브랜치명 오타 실사례). 처치: 스쿼시 합류면 `git diff <작업브랜치>..HEAD -- <구역경로>`가 **공(空)** 임을, ff 합류면 `에픽 HEAD == 브랜치 HEAD`를 게이트로.
9. **병렬 부하 플레이키** — 워커 여럿이 풀스위트를 돌리면 타임아웃 경계 테스트가 거짓 실패. 처치: 워커는 자기 구역 테스트만, 풀스위트는 통합 단계 1회(`--no-file-parallelism` 고려). 실패 시 단독 재실행으로 플레이키 판별.
10. **릴리스 타이밍 — 주인 보존 ≠ 프로세스 유지** — 작업 중인 디스패치를 timeout·heartbeat·idle로 끊지 않는다(행 걸림은 §5 처치). 합류 뒤 **사용자 수용 선언까지 보존하는 것은 반송의 주인 정보**(워크트리·브랜치·대화 ID·오너십 대장 행)이지 살아 있는 세션이 아니다 — 반송은 그 워크트리에 세션을 재기동해 복원한다(Phase 3). 실사례 ① 합류 직후 워크트리까지 정리했다가 "이슈 나오면 누가 고치나"를 사용자가 지적(2026-08-14) ② 반대로 수용 대기 명목으로 구현·검증 세션 16개를 18시간+ 유지했다가 기기 스왑이 포화돼 다른 세션의 테스트가 끝나지 않음(2026-09-15).
11. **워커 브랜치명·base — 오분기 상습(2차 런 3/5회가 main 계열 오분기)** — Orca 자동 생성 워크트리가 의도한 통합 브랜치가 아닌 곳에서 갈라질 수 있다. 브리프의 "base 확인+개명" 지시가 전부 잡았지만 워커 자가 교정 의존은 취약 — **코디네이터가 워크트리 생성 직후 base를 직접 검증**한다(`--base-branch` 명시 + `git worktree list`/`git log`로 확인). 레포별 워크트리 준비물(.env·의존성 재설치 등)은 프로젝트 메모리가 정본 — 있으면 브리프에 옮겨 싣는다.
12. **거짓 완료 보고 방지** — "완료"는 검증 가능한 산출(HEAD·테스트 출력·스크린샷) 대조 후에만 쓴다.
13. **종료 정리 게이트** — 정리 트리거는 "최종 합류"가 아니라 **사용자 수용 선언**이다(Phase 3). 수용 전 워크트리 제거는 이슈 반송 경로를 끊는다(세션 프로세스 종료는 Phase 3에 따라 합류 뒤 허용). 정리 시엔 **범위 확인 질문 필수** — 특히 "브랜치 정리는 체크아웃 워크트리 제거를 수반한다"를 고지하고 진행(지시 범위를 수단의 제약으로 조용히 넓히지 마라 — 실사례 2026-08-14). 절차: ① 전수 안전 확인 — `status --short` 0건 + 포함 검증(ff면 `merge-base --is-ancestor`, 스쿼시면 `git diff <브랜치>..<통합브랜치> -- <구역경로>` 공검사) ② `orca worktree rm --force`(브랜치 동반 삭제; 수동이면 스쿼시 브랜치는 `-D`) ③ 잔존 0 확인. 예외: 스쿼시 합류된 구역 브랜치는 가치가 소멸하므로 수용 전에도 삭제 가능(워크트리·대화 기록은 보존). 무관한 기존 워크트리 불가침. **무기한 방지**: 다음 에픽 착수 전, 이전 건의 수용·정리 여부를 사용자에게 확인한다.
14. **★verdict 수신 ≠ 합류 완료** — 여러 worker_done을 한 배치로 처리하다 검증 통과 1건의 합류를 빠뜨린 실사례(발견은 한참 뒤 우연한 grep). 처치: **verdict 통과 확인과 합류(rebase→구역 테스트→스쿼시→동등성 공검사)를 한 원자 절차로** — verdict를 읽었으면 그 턴 안에 합류까지 끝내거나, 불가하면 오너십 대장에 "합류 대기"를 명시 기록한다. 배치에 verdict와 신규 done이 섞여 있으면 **① verdict 합류(원자) → ② 신규 done 검증 배정** 순 — 합류가 늦을수록 다른 브랜치의 rebase 지점이 낡는다.
15. **★index.lock 경합** — 여러 세션(워커·관제·코디네이터)이 한 레포를 공유하면 커밋이 `Unable to create index.lock`으로 상습 실패. 처치: `ps`로 실행 중 git 프로세스 없음 확인 후 `rm -f .git/index.lock` + 커밋 재시도 루프(수 회). 예방: 보조·관제 세션에는 index를 만지는 git 명령(status·diff 등) 금지 — `git log`만 허용.
16. **★worker_done capability 반려** — 같은 터미널에 태스크를 연쇄 디스패치하면 워커가 옛 능력 토큰으로 보고해 "Dispatch capability is missing"으로 반려될 수 있다(작업 자체는 완료). 처치: 실산출(커밋 SHA·리포트 실존)을 직접 검증한 뒤 `task-update --status completed --result`로 수동 정산 — 반려됐다고 재작업 시키지 말 것. 릴리스 금지 규칙은 그대로.
17. **★LLM 폴링 관제 세션 금지** — 주기 감시·대시보드 게시를 전담 LLM 세션에 위임했더니 루프 실행 대신 레포 탐색으로 방황(10분 게시 0회, 실측 후 정지). 기계적 판정(스톨 검출·주기 게시)은 **스크립트**(§6 워치독)로, LLM은 판단(룰링·반송·처치)에만 쓴다.

## 5. 코디네이터 이벤트 루프

`check --wait --types worker_done,escalation,question --timeout-ms 540000`을 백그라운드(하네스)로 상시 재장전. **타임아웃(count 0)은 체크포인트** — 활성 디스패치 전수의 `worker-read` **최종 활동 timestamp를 스윕**한다. source 확인·state 확인만으론 스톨을 못 잡는다 — 마지막 tool-call에 결과가 없는 채 오래 지났으면 행 걸림이다(vitest 무응답을 1시간 방치한 실사례; 워치독 §6이 1차 방어, 이 스윕이 2차). 질문은 즉시 룰링·회신(reply)하고, 계약 패치는 [패치 커밋 → 질문자 회신(rebase 지점 포함) → 영향 워커 broadcast] 순서로. 행 걸림 처치 단계: `terminal send --enter` → `terminal read` 실화면 정독 → `worker-stop` + `worker-start --retry-of`(가용 터미널로 재기동 — 실증: 행 걸린 검증을 다른 검증 터미널로 넘겨 복구).

## 6. 관제 레인 (Observability — 2026-08-14 신설, 사용자 지시 "PM 역할")

**검출·게시 = 스크립트, 판단·처치 = 코디네이터** (지뢰 17). 세 부품:

- **워치독 스크립트**: 워커 기동 시 함께 부착 — 루프: 활성 디스패치의 `worker-read` 최종 timestamp가 임계(480s) 초과면 알림 후 종료, 태스크 정산 시 자동 종료, 주기 120s, 하네스 백그라운드로 실행(완료 알림이 코디네이터를 깨움). 스톨을 8분 내 검출한다 — 워치독 없던 구간의 실측은 1시간 방치였다.
- **사용자 상황판**: 모든 신호 처리에 동봉 — 상태 전이 때는 **표 형식**(단계 | 상태 ✅🔄⏳ | 소요/예상) + 전체 ETA·블로커·미해결 질문 요약줄, 하트비트 ack 때는 압축 1줄(지뢰 7과 짝). 마일스톤마다 갱신된 ETA 명시, 지연은 사유와 함께 선제 보고 — 사용자가 묻기 전에 보이게(단순 텍스트 나열 금지 — 사용자 지시).
- **아티팩트 대시보드 (옵트인)**: 채팅 상황판이 기본(추가 비용 0). 대시보드 페이지는 ① 런 2시간+ ② 사용자가 터미널을 떠나 있음 ③ 팀 공유 필요 — 일 때만. 규율: 갱신은 **상태 전이 시만·외과적 Edit**(실측 0.7~1k 토큰/회·~10초; 전체 재작성 금지), 갱신 주체는 코디네이터(전담 LLM 세션 금지 — 지뢰 17), **생명주기를 끝까지 설계** — 라이브용 auto-refresh는 마감 게시에서 제거하고 "관제 종료"를 명시한다(정적 페이지가 계속 깜빡이면 사용자가 원인 모를 갱신을 의심한다 — 실사례). 내용: 상황판 표 + 루프 토폴로지(인라인 SVG — 활성 노드 강조) + 이벤트 타임라인.

## 7. 핸드오프·온보딩 (세션 간 품질 이전 — 2026-08-14 신설)

핸드오프의 실패 모드는 사실 누락이 아니라 **협업 계약 소실**이다 — 새 세션이 상태는 알아도 "이 사용자와 어떻게 일하기로 했는지"를 몰라 품질이 무너진다(사용자 원문: "핸드오프하면 열심히 정제했던 사항을 못 지키고 실망하는 경우가 대부분").

- **문서 형식의 정본은 같은 라이브러리의 `orca-handoff` 스킬이 가진 `handoff-doc.md`(그 스킬의 references 폴더)다** — 규칙 5·필수 슬롯 10·대화 참조 금지·콜드 리더 검증 5문이 거기 있다. 여기서는 오케스트레이션 런이 특히 놓치는 둘만 못 박는다: 슬롯 1 «수용»의 정의(무엇이 선언돼야 다음 단계로 넘어가는지)와 슬롯 7 세션·워크트리 지도(릴리스용 dispatch id 까지).
- 콜드 리더 검증은 생략하지 않는다 — 실측: 1차 문서에서 [중]갭 4건 검출(스모크 목록이 «대화 참조»로 남아 있던 것 포함).
- 프로젝트 메모리(자동 로드)에 핸드오프 문서 좌표를 1줄 남겨, 새 세션이 어떤 경로로 뜨든 문서를 찾게 한다. 전달 확인(프롬프트 제출·토큰 소비 시작)까지가 핸드오프다 — 이후 감시하지 않는다.