uctm 1.5.4 → 2.0.1

package/references/work-activity-log.md

@@ -1,26 +1,50 @@
 # 작업 활동 로그
 
-`works/{WORK_ID}/work_{WORK_ID}.log`에 에이전트 시작/종료 이벤트를 기록.
+`works/{WORK_ID}/work_{WORK_ID}.log`에 실행 이벤트를 기록.
 
-## 규칙
+---
 
-1. **타임스탬프**: Bash로 `date -u +"%Y-%m-%dT%H:%M:%SZ"` 실행하여 실제 UTC 시간 획득. 더미 값 사용 금지.
-2. **기록 방법**: Bash `echo` 로 추가. 
-3. **항목**: 에이전트 역할별 START와 DONE만. 중간 단계 없음.
+## 섹션 소비 매트릭스
 
-## 형식
+orchestrator가 자식 spawn 시 `<ref-cache>`에 담을 섹션을 결정하는 기준표 → `xml-schema.md` § 4.
+
+| § | 내용 | orch | spec | plan | build | verif | commit |
+|---|------|:----:|:----:|:----:|:-----:|:-----:|:------:|
+| 1 | 규칙 | ✅ | | | | | |
+| 2 | 형식 | ✅ | | | | | ✅ |
+| 3 | 이벤트 체계 | ✅ | | | | | ✅ |
+
+> committer는 마지막 TASK 판정을 위해 로그를 **읽기만** 한다 — 기록 주체는 orchestrator뿐(§ 1).
+
+---
+
+## § 1. 규칙
+
+1. **기록 주체**: **orchestrator 역할을 수행하는 주체**. 정상 경로에서는 orchestrator 에이전트이고, 축퇴 모드(→ `xml-schema.md` § 8)에서는 그 역할을 넘겨받은 Main Claude다. 어느 쪽이든 자식의 spawn/완료를 `STAGE_START`/`STAGE_DONE`으로 기록한다.
+2. **타임스탬프**: Bash로 `date -u +"%Y-%m-%dT%H:%M:%SZ"` 실행하여 실제 UTC 시간 획득. 더미 값 사용 금지.
+3. **기록 방법**: Bash `echo` 로 추가.
+4. **`STAGE_DONE`은 게이트 통과 후에 기록한다.** 해당 단계에 게이트(`<gate type="stage">` 또는 `<gate type="decision">`)가 있는 경우, Main Claude/사용자의 승인·결정으로 게이트가 해소(RESOLVED)된 시점에만 `STAGE_DONE`을 남긴다. 게이트 대기 중에는 `GATE_WAIT`/`DECISION_WAIT`만 기록되고, `STAGE_DONE`은 아직 기록되지 않은 상태로 남는다.
+   - **근거(재개 판정)**: 파이프라인이 중단 후 재개(resume)될 때 orchestrator는 로그의 마지막 이벤트로 재개 지점을 판정한다. 특정 단계에 `STAGE_START`만 있고 `STAGE_DONE`이 없다면 "그 단계의 게이트가 아직 승인/결정되지 않았다"는 뜻이므로, orchestrator는 다음 단계로 건너뛰지 않고 동일 게이트를 다시 제시해야 한다. `STAGE_DONE`을 게이트 통과 이전에 기록하면 재개 시 미승인 게이트를 건너뛰는 사고로 이어진다.
+
+## § 2. 형식
 
 ```
-[YYYY-MM-DDTHH:MM:SSZ] AGENT_EVENT — description
+[YYYY-MM-DDTHH:MM:SSZ] EVENT — description
 ```
 
-## 필수 항목
+## § 3. 이벤트 체계 (orchestrator 기록)
+
+| 이벤트 | 기록 시점 | 예시 |
+|--------|----------|------|
+| `ORCHESTRATOR_START` | orchestrator 실행 시작 | `ORCHESTRATOR_START — WORK-NN orchestrator started` |
+| `ORCHESTRATOR_DEGRADED` | 축퇴 모드 진입 — Main Claude가 orchestrator 역할을 넘겨받음. `ORCHESTRATOR_START` 직후 1회 기록 | `ORCHESTRATOR_DEGRADED — reason=no-agent-tool` |
+| `STAGE_START` | 자식 에이전트(specifier/planner/builder/verifier/committer) spawn 직전 | `STAGE_START — stage=specifier` |
+| `GATE_WAIT` | `<gate type="stage">`에서 정지, Main Claude 승인 대기 | `GATE_WAIT — stage=specifier` |
+| `DECISION_WAIT` | `<gate type="decision">` 또는 자식의 `<needs-decision>` 수신 후 결정 대기 | `DECISION_WAIT — stage=planner` |
+| `DECISION` | 결정 확정 — 주체는 `user`(사용자 승인) 또는 `auto`(orchestrator 자동결정) | `DECISION — stage=planner by=user` / `DECISION — task=TASK-03 by=auto` |
+| `STAGE_DONE` | 게이트 해소(RESOLVED) 후, 또는 게이트가 없는 단계는 완료 즉시 | `STAGE_DONE — stage=specifier` |
+| `ORCHESTRATOR_DONE` | orchestrator 실행 종료 (WORK 완료) | `ORCHESTRATOR_DONE — WORK-NN orchestrator completed` |
 
-| 에이전트 | START | DONE |
-|----------|-------|------|
-| specifier | `SPECIFIER_START — WORK-NN specifier started` | `SPECIFIER_DONE — WORK-NN specifier completed` |
-| planner | `PLANNER_START — WORK-NN planner started` | `PLANNER_DONE — WORK-NN planner completed` |
-| scheduler | `SCHEDULER_START — WORK-NN scheduler started` | `SCHEDULER_DONE — WORK-NN scheduler completed` |
-| builder | `BUILDER_START — TASK-NN implement` | `BUILDER_DONE — TASK-NN complete` |
-| verifier | `VERIFIER_START — TASK-NN verification` | `VERIFIER_DONE — TASK-NN verified` |
-| committer | `COMMITTER_START — TASK-NN commit` | `COMMITTER_DONE — TASK-NN committed` |
+- `stage` 값: `specifier`/`planner`/`builder`/`verifier`/`committer`.
+- `by` 값: `user`/`auto`. `<decision>`(§ 7, `xml-schema.md`)의 `by` 속성과 동일한 값 체계를 사용.
+- 확정된 결정의 상세 내용(배경/선택지/권고안/확정값)은 로그가 아니라 `works/{WORK_ID}/DECISIONS.md`에 orchestrator가 기록한다. 로그의 `DECISION` 이벤트는 "언제·누가 결정했는지"만 남긴다.

package/references/xml-schema.md

@@ -4,18 +4,36 @@ uc-taskmanager 에이전트용 XML 통신 형식 정의.
 
 ---
 
-## 1. Dispatch 형식 (디스패처 → 수신자)
+## 섹션 소비 매트릭스
+
+orchestrator가 자식 spawn 시 `<ref-cache>`에 담을 섹션을 결정하는 기준표 → § 4.
+
+| § | 내용 | orch | spec | plan | build | verif | commit |
+|---|------|:----:|:----:|:----:|:-----:|:-----:|:------:|
+| 1 | Dispatch 형식 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 2 | Task Result 형식 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 3 | Context-Handoff 요소 | ✅ | | | ✅ | ✅ | ✅ |
+| 4 | ref-cache 프로토콜 | ✅ | | | | | |
+| 5 | Gate 요소 | ✅ | | | | | |
+| 6 | needs-decision 요소 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 7 | decision 요소 | ✅ | | | | | |
+| 8 | capability-degraded 요소 | ✅ | | | | | |
+
+> § 4·§ 5·§ 7·§ 8은 **orchestrator 전용**이다. ref-cache 생성(§ 4), 게이트 발행(§ 5), 결정 확정(§ 7)은 모두 orchestrator의 책임이며 자식 에이전트는 수행하지 않는다. 자식에게 필요한 ref-cache 소비 규칙은 각 에이전트 정의의 STARTUP 절에 인라인으로 기술되어 있다.
+
+---
+
+> **디스패처 라벨**: dispatch를 발신하고 task-result를 수신하는 디스패처 역할은 **orchestrator**가 수행한다. 아래 §1/§2의 "디스패처"는 모두 orchestrator를 가리킨다.
+
+## § 1. Dispatch 형식 (orchestrator → 수신자)
 
 ```xml
-<dispatch to="{receiver}" work="{WORK_ID}" task="{TASK_ID}" execution-mode="{direct|pipeline|full}">
-  <ref-cache>                                        <!-- 선택사항 -->
-    <ref key="shared-prompt-sections">{파일 내용}</ref>
-    <ref key="file-content-schema">{파일 내용}</ref>
-    <ref key="xml-schema">{파일 내용}</ref>
-    <ref key="context-policy">{파일 내용}</ref>
-    <ref key="work-activity-log">{파일 내용}</ref>
+<dispatch to="{receiver}" work="{WORK_ID}" task="{TASK_ID}">
+  <ref-cache>                                        <!-- 필수 — § 4 참조 -->
+    <ref key="shared-prompt-sections" sections="1,3,12">{해당 섹션 원문}</ref>
+    <ref key="xml-schema" sections="1,2,6">{해당 섹션 원문}</ref>
+    <!-- 수신자에게 필요한 섹션만 (§ 4 조립 절차 참조) -->
   </ref-cache>
-  <references-dir>{references 디렉토리 절대 경로}</references-dir>
   <context>
     <project>{프로젝트 이름}</project>
     <language>{lang_code}</language>
@@ -30,19 +48,19 @@ uc-taskmanager 에이전트용 XML 통신 형식 정의.
   <previous-results>
     <result task="{TASK_ID}" status="{PASS|FAIL|SKIP}">{요약}</result>
   </previous-results>
-  <cache-hint sections="{section1},{section2}"/>
 </dispatch>
 ```
 
 | 속성 | 값 |
 |------|-----|
-| `to` | builder, verifier, committer, planner, scheduler, specifier |
+| `to` | builder, verifier, committer, planner, specifier |
 | `task` | `TASK-NN` — WORK 접두사 포함 금지 |
-| `execution-mode` | direct / pipeline / full (생략 시 full 기본값) |
+
+> `<ref-cache>`는 **필수**다. orchestrator는 이것 없이 자식을 spawn하지 않는다 — 자식이 레퍼런스를 디스크에서 다시 읽게 되어 ref-cache가 무력화된다.
 
 ---
 
-## 2. Task Result 형식 (수신자 → 디스패처)
+## § 2. Task Result 형식 (수신자 → orchestrator)
 
 ```xml
 <task-result work="{WORK_ID}" task="{TASK_ID}" agent="{agent}" status="{PASS|FAIL}">
@@ -54,19 +72,14 @@ uc-taskmanager 에이전트용 XML 통신 형식 정의.
     <check name="{type}" status="{PASS|FAIL|N/A}">{출력}</check>
   </verification>
   <notes>{메모}</notes>
-  <ref-cache>                                        <!-- 선택사항 -->
-    <ref key="shared-prompt-sections">{파일 내용}</ref>
-    <ref key="file-content-schema">{파일 내용}</ref>
-    <ref key="xml-schema">{파일 내용}</ref>
-    <ref key="context-policy">{파일 내용}</ref>
-    <ref key="work-activity-log">{파일 내용}</ref>
-  </ref-cache>
 </task-result>
 ```
 
+> task-result에는 `<ref-cache>`를 **포함하지 않는다**. 캐시의 단일 소스는 orchestrator이며(§ 4), 자식이 전달받은 내용을 되돌려주는 것은 순수한 토큰 낭비다.
+
 ---
 
-## 3. Context-Handoff 요소
+## § 3. Context-Handoff 요소
 
 ```xml
 <context-handoff from="{agent}" detail-level="{FULL|SUMMARY|DROP}">
@@ -85,36 +98,195 @@ uc-taskmanager 에이전트용 XML 통신 형식 정의.
 
 ---
 
-## 4. ref-cache 요소 정의
+## § 4. ref-cache 프로토콜 (orchestrator 전용)
 
-`<ref-cache>`는 dispatch 및 task-result XML 내에서 미리 로딩된 레퍼런스 파일 내용을 전달하는 선택적 컨테이너 요소입니다. 존재할 경우, 수신 에이전트는 디스크에서 파일을 읽는 대신 반드시 이 내용을 사용해야 합니다.
+### 원칙
+
+레퍼런스 파일을 읽는 주체는 **orchestrator 하나뿐**이다. orchestrator는 기동 시 1회 읽고, 자식을 중첩 spawn할 때마다 **그 자식에게 필요한 섹션만** 잘라 `<ref-cache>`로 전달한다. 자식은 디스크를 읽지 않는다.
+
+| 주체 | 행위 |
+|------|------|
+| orchestrator | 레퍼런스 5종 읽기(1회) → 각 파일의 **섹션 소비 매트릭스** 파싱 → 자식별 `<ref-cache>` 조립 → dispatch에 필수 포함 |
+| 자식 에이전트 | `<ref-cache>` 내용만 사용. `{REFERENCES_DIR}` 하위 파일에 대한 `Read`/`Glob`/`Grep` **금지** |
 
 ### 구조
 
 ```xml
 <ref-cache>
-  <ref key="{확장자 없는 파일명}">{전체 파일 내용}</ref>
+  <ref key="{확장자 없는 파일명}" sections="{쉼표 구분 § 번호}">{해당 섹션 원문}</ref>
   ...
 </ref-cache>
 ```
 
-| 요소 | 필수 | 설명 |
-|------|------|------|
-| `<ref-cache>` | 선택 | 캐시된 레퍼런스 파일 컨테이너. 캐시가 없으면 전체 생략. |
-| `<ref key="...">` | — | 개별 레퍼런스 파일. `key`는 확장자 없는 파일명 (예: `shared-prompt-sections`). |
+| 요소/속성 | 필수 | 설명 |
+|-----------|:----:|------|
+| `<ref-cache>` | ✅ | dispatch에 항상 포함. 생략 금지. |
+| `<ref key="...">` | — | 레퍼런스 파일 1개당 1개. `key`는 확장자 없는 파일명. |
+| `sections="..."` | ✅ | 이 `<ref>`에 담긴 § 번호 목록 (예: `"1,3,12"`). 자식의 자기검증용. |
+
+- `<ref>` 본문에는 **`## § N.` 헤딩을 그대로 보존**한 원문을 넣는다 — 문서 내 "→ `xml-schema.md` § 6 참조" 같은 상호참조가 그대로 해소되어야 한다.
+- § 번호가 없는 도입부 표(예: `file-content-schema.md`의 "준수사항")는 해당 파일 전달 시 항상 함께 싣고 `sections`에는 표기하지 않는다.
 
 ### 인식되는 키
 
-| 키 | 대응 파일 |
-|-----|-----------|
-| `shared-prompt-sections` | `{REFERENCES_DIR}/shared-prompt-sections.md` |
-| `file-content-schema` | `{REFERENCES_DIR}/file-content-schema.md` |
-| `xml-schema` | `{REFERENCES_DIR}/xml-schema.md` |
-| `context-policy` | `{REFERENCES_DIR}/context-policy.md` |
-| `work-activity-log` | `{REFERENCES_DIR}/work-activity-log.md` |
+| 키 | 대응 파일 | 섹션 범위 |
+|-----|-----------|----------|
+| `shared-prompt-sections` | `{REFERENCES_DIR}/shared-prompt-sections.md` | § 1~9, § 12 |
+| `file-content-schema` | `{REFERENCES_DIR}/file-content-schema.md` | 준수사항, § 0~5 |
+| `xml-schema` | `{REFERENCES_DIR}/xml-schema.md` | § 1~7 |
+| `context-policy` | `{REFERENCES_DIR}/context-policy.md` | § 1~6 |
+| `work-activity-log` | `{REFERENCES_DIR}/work-activity-log.md` | § 1~3 |
+
+### 조립 절차 (orchestrator)
+
+```
+1. 대상 자식(specifier/planner/builder/verifier/committer)을 확정한다.
+2. 읽어둔 레퍼런스 5종 각각의 "섹션 소비 매트릭스" 표에서 해당 자식 열이 ✅인 행을 모은다.
+   표를 끝까지 훑어 ✅ 행을 하나도 빠뜨리지 않는다.
+3. ✅ 행이 하나도 없는 파일은 <ref> 자체를 생성하지 않는다.
+4. ✅ 행이 있는 파일마다 <ref>를 정확히 1개씩만 만든다.
+   같은 key로 두 번 넣지 않으며, sections에 ✅ 번호를 빠짐없이 나열한다.
+   본문은 해당 § 원문을 헤딩째 발췌한다.
+5. 조립된 <ref-cache>를 dispatch XML 최상단에 넣어 자식 spawn 프롬프트에 포함한다.
+6. spawn 직전 자체 점검: key 중복이 없고, key 구성·sections 값이 매트릭스와 일치하는지 대조한다.
+```
+
+### 조립 불변식
+
+| 규칙 | 위반 시 |
+|------|---------|
+| 파일 1개당 `<ref>` 1개 | 같은 내용이 두 번 실려 토큰 낭비 |
+| `sections`에 매트릭스 ✅ 를 빠짐없이 | 자식이 필요한 내용을 받지 못함 |
+| `sections` 값 = 실제 담긴 § 목록 | 자식의 자기검증이 무의미해짐 |
+
+### 내용 부족 시 처리 (엄격 모드)
+
+- 자식은 어떤 경우에도 레퍼런스 파일을 디스크에서 읽지 않는다. **폴백 경로는 없다.**
+- 작업에 필요한 내용이 `<ref-cache>`에 없으면 `<needs-decision>`(§ 6)으로 부족한 `key`·내용을 명시해 orchestrator에 상향하고 종료한다.
+- orchestrator는 누락분을 보충한 `<ref-cache>`로 해당 자식을 재spawn한다. 이는 매트릭스 배분이 실제 필요와 어긋났다는 신호이므로, 반복되면 해당 파일의 섹션 소비 매트릭스를 수정한다.
+
+---
+
+## § 5. Gate 요소 (orchestrator → Main Claude)
+
+`<gate>`는 orchestrator가 자율 실행을 일시 정지하고 Main Claude(및 사용자)의 승인 또는 결정을 요청할 때 반환하는 정지 신호입니다. orchestrator는 `<gate>`를 반환한 뒤 Main Claude의 응답(승인 또는 `<decision>`)이 돌아올 때까지 재개하지 않습니다.
+
+### type="stage" — 단계 완료 승인 게이트
+
+```xml
+<gate type="stage" work="WORK-12" stage="specifier">
+  <summary>Requirement.md 작성 완료. FR 6건, NFR 2건 도출.</summary>
+  <next-stage>planner</next-stage>
+</gate>
+```
+
+### type="decision" — 결정 필요 게이트
+
+```xml
+<gate type="decision" work="WORK-12" stage="planner">
+  <context>인증 방식으로 세션 기반과 JWT 중 선택이 필요합니다. 기존 코드베이스는 세션 기반이나 신규 마이크로서비스 확장 계획이 있습니다.</context>
+  <options>
+    <option id="1">세션 기반 유지 (기존 컨벤션 일치)</option>
+    <option id="2">JWT 전환 (확장성 우선)</option>
+  </options>
+  <recommended>option 1 — 현재 스코프에서는 확장 계획이 확정되지 않아 리스크가 낮은 세션 기반 유지를 권고</recommended>
+</gate>
+```
+
+| 속성 | 값 |
+|------|-----|
+| `type` | `stage`(단계 완료 승인 요청) / `decision`(선택 필요) |
+| `work` | `WORK_ID` |
+| `stage` | 현재 정지된 단계: `specifier`/`planner`/`builder`/`verifier`/`committer` |
+
+- `type="decision"`은 `<context>`(배경 — 왜 결정이 필요한가), `<options>`(선택지 목록), `<recommended>`(권고안)을 하위 요소로 반드시 포함한다.
+- Main Claude는 `<gate>` 수신 시 사용자에게 승인/선택을 구하고, 결과를 `<decision>`(§ 7)으로 orchestrator에 재전달하여 재개시킨다.
+- 게이트 정지는 활동 로그의 `GATE_WAIT`(stage 게이트) 또는 `DECISION_WAIT`(decision 게이트) 이벤트와 짝을 이룬다 → `work-activity-log.md` 참조.
+
+---
+
+## § 6. needs-decision 요소 (자식 에이전트 → orchestrator)
+
+`<needs-decision>`은 자식 에이전트(builder/verifier 등)가 구현 중 스스로 결정할 수 없는 사항을 발견했을 때, task-result와 함께(또는 대신) orchestrator에 상향 보고하는 신호입니다. Main Claude로 직접 올라가지 않고 먼저 orchestrator가 받는다는 점에서 `<gate type="decision">`과 구분됩니다.
+
+```xml
+<needs-decision work="WORK-12" task="TASK-03" agent="builder">
+  <context>TASK 스펙에 명시되지 않은 에러 응답 포맷이 필요합니다. 기존 엔드포인트는 두 가지 포맷이 혼재합니다.</context>
+  <options>
+    <option id="1">엔드포인트 A 방식(`{error: string}`)에 통일</option>
+    <option id="2">엔드포인트 B 방식(`{code, message}`)에 통일</option>
+  </options>
+  <recommended>option 2 — 신규 API 표준에 부합</recommended>
+</needs-decision>
+```
+
+| 속성 | 값 |
+|------|-----|
+| `work` | `WORK_ID` |
+| `task` | `TASK_ID` |
+| `agent` | 신호를 발생시킨 자식 에이전트 |
+
+- orchestrator는 `<needs-decision>` 수신 시 자동 결정 가능 여부를 판단한다.
+  - 자동 결정 가능 → `<decision by="auto">`(§ 7)로 확정하고 자식 작업을 재개시킴.
+  - 자동 결정 불가 → `<gate type="decision">`(§ 5)으로 승격하여 Main Claude에 전달.
+- 어느 경로든 결정 내용은 **orchestrator가** `works/{WORK_ID}/DECISIONS.md`에 기록한다. 자식 에이전트는 DECISIONS.md를 직접 쓰지 않으므로 그 포맷을 알 필요가 없다.
+
+---
+
+## § 7. decision 요소 (확정 결정 기록)
+
+`<decision>`은 게이트(§ 5) 또는 needs-decision(§ 6)에 대해 내려진 확정 결정을 기록하는 요소입니다. 사용자 승인분(`by="user"`)과 orchestrator 자동결정분(`by="auto"`)이 동일한 형식을 공유합니다.
+
+```xml
+<decision work="WORK-12" stage="planner" by="user">
+  <context>인증 방식으로 세션 기반과 JWT 중 선택이 필요했음.</context>
+  <chosen>세션 기반 유지</chosen>
+  <rationale>기존 컨벤션과의 일치를 우선함</rationale>
+</decision>
+```
+
+```xml
+<decision work="WORK-12" task="TASK-03" by="auto">
+  <context>에러 응답 포맷 불일치 — builder의 needs-decision.</context>
+  <chosen>엔드포인트 B 방식(`{code, message}`)에 통일</chosen>
+  <rationale>신규 API 표준과 일치, 리스크 낮음</rationale>
+</decision>
+```
+
+| 속성 | 값 |
+|------|-----|
+| `work` | `WORK_ID` |
+| `stage` / `task` | 결정이 발생한 단계 또는 TASK (해당하는 것 사용) |
+| `by` | `user`(사용자 승인) / `auto`(orchestrator 자동결정) |
+
+- orchestrator는 `<decision>` 확정 즉시 `works/{WORK_ID}/DECISIONS.md`의 해당 항목을 `PENDING → RESOLVED`로 갱신하고, 활동 로그에 `DECISION` 이벤트를 기록한다 → `work-activity-log.md` 참조.
+
+---
+
+## § 8. capability-degraded 요소 (orchestrator → Main Claude)
+
+`<capability-degraded>`는 orchestrator가 **자신의 실행 환경이 파이프라인을 수행할 수 없음**을 감지했을 때, 아무 작업도 하지 않고 즉시 반환하는 신호입니다.
+
+```xml
+<capability-degraded reason="no-agent-tool">
+  <detail>서브에이전트에 Agent 도구가 주입되지 않아 중첩 spawn 불가</detail>
+</capability-degraded>
+```
+
+| 속성/요소 | 값 |
+|-----------|-----|
+| `reason` | `no-agent-tool` — 중첩 spawn용 `Agent` 도구 부재 |
+| `<detail>` | 사람이 읽을 수 있는 사유 1줄 |
+
+### 발생 조건
+
+일부 CLI 버전·환경에서 서브에이전트에 `Agent` 도구가 주입되지 않아 자식 중첩 spawn이 불가능한 경우. orchestrator는 기동 직후(STEP 0, 레퍼런스를 읽기 전) 이를 판정한다.
+
+### 불변식
+
+- orchestrator는 이 신호를 반환하기 전에 **어떤 산출물도 만들지 않는다** — WORK 폴더, Requirement.md, 활동 로그 모두 생성 금지.
+- orchestrator는 자식 역할을 **인라인으로 대행하지 않는다.** 대행하면 WORK가 완료된 것처럼 보이지만 역할 분리와 검증 독립성이 사라진 채로 끝나며, 오류가 나지 않아 발견되지 않는다.
 
-### 하위 호환성
+### Main Claude의 처리
 
-- `<ref-cache>` 없는 dispatch 또는 task-result XML은 완전히 유효 — 에이전트는 `REFERENCES_DIR`에서 파일을 읽는 것으로 폴백.
-- ref-cache를 아직 지원하지 않는 에이전트는 해당 요소를 무시하고 정상적으로 파일을 읽음.
-- 부분적 ref-cache (일부 키만 존재)도 허용 — 없는 키는 디스크에서 읽음.
+Main Claude는 이 신호를 받으면 축퇴 모드로 전환해 **자신이 orchestrator 역할을 수행**한다. 절차의 정본은 `orchestrator.md` 그대로이며, 자식이 depth=1로 뜨는 것만 다르다 → `agent-flow.md` 축퇴 모드 절 참조.

package/skills/sdd-pipeline/SKILL.md

@@ -1,6 +1,6 @@
 # sdd-pipeline references
 
-파이프라인 에이전트(specifier, planner, scheduler, builder, verifier, committer)가 참조하는 규칙/스키마 문서 모음.
+파이프라인 에이전트(orchestrator, specifier, planner, builder, verifier, committer)가 참조하는 규칙/스키마 문서 모음.
 
 직접 사용자 호출용이 아니라 에이전트 내부 참조용입니다.
 

package/skills/uctm-init/SKILL.md

@@ -61,8 +61,7 @@ works/가 없으면:
   "Bash(python:*)",
   "Bash(ruff:*)",
   "Bash(make:*)",
-  "Bash(git:*)",
-  "Bash(curl:*)"
+  "Bash(git:*)"
 ]
 ```
 

package/skills/work-pipeline/SKILL.md

@@ -13,12 +13,11 @@ description: Triggers the WORK-PIPELINE. Use this skill when
 - `[new-feature]`, `[enhancement]`, `[bugfix]`, `[new-work]`, `[WORK start]`
 - 또는 대괄호 안의 커스텀 태그
 
-`../../references/agent-flow.md`를 읽고 오케스트레이션 흐름을 따릅니다.
-
 **WORK 재개** — 메시지에 기존 WORK-ID와 실행 의도가 있을 때:
 - "WORK-XX 계속실행", "WORK-XX 실행", "resume WORK-XX", "continue WORK-XX"
 - "파이프라인 재개", "WORK 계속"
-- → agent-flow.md § 기존 WORK 재개 따르기
+
+두 경우 모두 아래 "오케스트레이션 흐름"을 따릅니다.
 
 ## References Directory (CRITICAL)
 
@@ -29,34 +28,51 @@ description: Triggers the WORK-PIPELINE. Use this skill when
 REFERENCES_DIR = {Base directory}/../../references
 ```
 
-**모든 서브에이전트 호출**(specifier, planner, scheduler, builder, verifier, committer)에 이 절대 경로를 반드시 전달해야 합니다.
-프롬프트 텍스트 상단에 포함:
+`orchestrator` spawn 시 이 절대 경로를 반드시 전달해야 합니다. orchestrator가 레퍼런스 파일을 찾기 위해 이 경로가 필요합니다. 없으면 파일을 찾지 못하고 루프에 빠집니다.
 
-```
-REFERENCES_DIR={absolute_path}
-```
+## Auto 모드 감지
 
-서브에이전트가 레퍼런스 파일을 찾기 위해 이 경로가 필요합니다. 없으면 파일을 찾지 못하고 루프에 빠집니다.
+사용자의 메시지에 "auto" 또는 "자동으로"가 포함되면 **auto 모드**로 spawn합니다. 그 외에는 **gated 모드**(기본값)로 spawn합니다.
 
-## 파이프라인 흐름
+## 오케스트레이션 흐름
 
-1. **specifier 에이전트 spawn** (Agent 도구 사용) — 요구사항 분석, `works/WORK-NN/Requirement.md` 생성, execution-mode 결정 (direct/pipeline/full)
-2. **⛔ 정지 — specifier의 출력 요약을 사용자에게 제시하고 명시적 승인 대기.** 사용자가 승인할 때까지 다음 에이전트를 호출하지 말 것. 생성된 내용(Requirement.md, direct 모드면 PLAN.md, TASK 파일)을 보여주고 "진행할까요?" 질문
-3. **specifier가 반환한 execution-mode에 따라 진행:**
-   - `direct`: builder spawn → verifier spawn → committer spawn
-   - `pipeline`: planner spawn → 각 TASK에 대해 → builder spawn → verifier spawn → committer spawn
-   - `full`: planner spawn → **⛔ 2차 승인 정지** → scheduler spawn → 각 TASK에 대해 → builder spawn → verifier spawn → committer spawn
+Main Claude는 `orchestrator` 에이전트 하나만 spawn합니다. specifier/planner/builder/verifier/committer는 orchestrator가 내부에서 중첩 spawn(TASK DAG 스케줄링 포함)하므로 Main Claude가 직접 호출하지 않습니다.
 
-## ⚠️ CRITICAL: 에이전트 Spawn 규칙
+### Gated 모드 (기본값 — "auto"/"자동으로" 없음)
+
+1. **최초 spawn**: `orchestrator`를 `mode=gated`로 spawn. 프롬프트 상단에 `REFERENCES_DIR=...`와 `mode=gated`를 포함하고, 사용자 요청 원문(및 재개 시 `WORK_ID`)을 전달. 반환된 **agentId를 보관**한다(다음 재개에 사용).
+2. **`<gate>` 수신 시 정지**: orchestrator가 `<gate type="stage">`(고정 게이트: specifier 완료 후 / planner 완료 후) 또는 `<gate type="decision">`(동적 의사결정)을 반환하면 orchestrator는 그 자리에서 yield(파킹)한 상태다.
+   - `type="stage"`: `<summary>`를 사용자에게 제시하고 진행 승인을 요청.
+   - `type="decision"`: `<context>`/`<options>`/`<recommended>`를 **AskUserQuestion**으로 제시해 사용자 선택을 받는다.
+3. **재개**: 사용자의 승인 또는 결정을 **`SendMessage(agentId, 결정내용)`으로 orchestrator에 전달해 재개**한다(컨텍스트 유지). agentId가 유실되었거나 SendMessage가 실패하면(세션 종료, 크로스세션 등) 로그(`work_{WORK}.log`) 기반으로 orchestrator를 **re-spawn**하는 폴백을 사용한다 — 이 경우도 재개 지정은 name이 아니라 **agentId**(또는 재-spawn 결과의 새 agentId)로 한다.
+4. **반복**: 2~3을 orchestrator가 최종 WORK 요약을 반환할 때까지 반복한다.
+5. **종료**: orchestrator가 최종 요약(`## 자동 결정 사항` 포함)을 반환하면 사용자에게 제시하고, **`TaskStop(agentId)`으로 orchestrator를 종료**한다.
 
-- **모든 에이전트는 Agent 도구를 통해 spawn해야 합니다.** Main Claude가 직접 코드 구현, 파일 생성, git 명령 실행 또는 에이전트의 작업을 수행하면 안 됩니다.
-- specifier가 builder dispatch XML을 반환하면 builder 에이전트에 전달할 것 — 직접 실행하지 말 것.
+### Auto 모드 ("auto"/"자동으로" 포함)
 
-## Auto 모드
+1. `orchestrator`를 `mode=auto`로 **1회만 spawn**. 프롬프트 상단에 `REFERENCES_DIR=...`와 `mode=auto`를 포함.
+2. 게이트/의사결정 정지 없이 orchestrator가 전체 파이프라인을 완주하고 최종 요약(`## 자동 결정 사항` 포함)을 반환한다.
+3. 반환된 최종 요약을 사용자에게 제시한다. (파킹 상태가 아니므로 TaskStop 불필요.)
 
-사용자의 메시지가 "auto" 또는 "자동으로"로 끝나면, 모든 승인 단계를 건너뛰고 전체 파이프라인을 자동 실행합니다. 승인 게이트를 건너뛸 수 있는 유일한 경우입니다.
+## 축퇴 모드 (중첩 spawn 미지원 환경)
+
+orchestrator가 `<capability-degraded reason="no-agent-tool">`을 반환하면, 그 환경은 서브에이전트에 `Agent` 도구를 주지 않아 중첩 spawn이 불가능한 상태입니다(CLI 버전에 따라 발생). orchestrator는 아무 산출물도 만들지 않고 즉시 반환하므로 디스크에는 아무것도 없습니다.
+
+이때 Main Claude가 **orchestrator 역할을 넘겨받습니다**:
+
+1. 사용자에게 1줄 알린다 — "중첩 spawn 미지원 환경 — Main Claude가 직접 오케스트레이션합니다". 승인을 기다리지 않고 진행.
+2. `{REFERENCES_DIR}/orchestrator.md`와 레퍼런스 5종을 읽는다.
+3. `orchestrator.md` 절차를 그대로 수행한다 — specifier/planner/builder/verifier/committer를 **직접 spawn**(depth=1)하고, ref-cache 조립·활동 로그·TASK DAG·재시도 규칙을 동일하게 적용한다.
+4. 활동 로그에 `ORCHESTRATOR_DEGRADED — reason=no-agent-tool`을 기록한다.
+5. 게이트는 `<gate>` XML/`SendMessage` 없이 사용자에게 **직접** 질의한다.
+
+→ 상세: `agent-flow.md` § 7
+
+## ⚠️ CRITICAL: 에이전트 Spawn 규칙
 
-Auto 모드 감지 시, 모든 서브에이전트 프롬프트에 "auto"를 포함합니다.
+- **정상 경로**에서 Main Claude가 spawn하는 에이전트는 **orchestrator 하나뿐**이다. Main Claude가 직접 코드 구현, 파일 생성, git 명령 실행 또는 orchestrator의 작업을 수행하면 안 된다.
+- **축퇴 모드**에서는 Main Claude가 자식 5종을 직접 spawn한다. 단 이 경우에도 **자식 역할을 스스로 대행하지는 않는다** — 반드시 각 에이전트를 spawn해야 한다.
+- 게이트 재개는 항상 **agentId** 기준(SendMessage/TaskStop 모두)으로 한다 — name 재사용에 의한 오배달을 방지한다.
 
 ## Arguments
 

package/.agent/router_rule_config.json

@@ -1,47 +0,0 @@
-{
-  "$schema": "http://uc-taskmanager.local/schemas/router-rules/v1.0.json",
-  "version": "1.1.0",
-  "description": "Router execution-mode 판정 기준 설정. 프로젝트별로 이 파일을 수정하여 라우팅 기준을 커스터마이즈한다.",
-  "decision_flow": [
-    "1. build_test_required 여부 판단 → false이면 direct",
-    "2. single_domain + sequential DAG → pipeline",
-    "3. 아래 full_conditions 중 하나라도 해당 → full"
-  ],
-  "rules": {
-    "direct": {
-      "description": "Router 단독 처리 — 빌드/테스트 검증 불필요, 서브에이전트 0",
-      "criteria": {
-        "build_test_required": false,
-        "note": "파일 수·줄 수 무관. 검증 없이 끝나는 작업이면 direct (텍스트 편집, 설정 변경, 단순 치환 등)"
-      }
-    },
-    "pipeline": {
-      "description": "Builder → Verifier → Committer 단일 흐름 — Builder 1회 호출",
-      "criteria": {
-        "build_test_required": true,
-        "single_domain_only": true,
-        "max_tasks": 5,
-        "dag_complexity": "sequential",
-        "note": "빌드/테스트 필요하지만 단일 도메인(BE만 또는 FE만)이고 한 흐름으로 처리 가능한 경우"
-      }
-    },
-    "full": {
-      "description": "Planner → Scheduler → [Builder → Verifier → Committer] × N",
-      "criteria": {
-        "any_of": [
-          "task_count > 5",
-          "dag_complexity == complex (TASK 간 의존성이 2레벨 이상)",
-          "multi_domain == true (BE + FE 동시 변경)",
-          "new_module == true (신규 모듈/기능 — 설계→구현→검증 다단계)",
-          "partial_rollback_needed == true (TASK 실패 시 부분 롤백 필요)"
-        ],
-        "note": "Builder를 여러 번 독립 호출해야 안전한 규모"
-      }
-    }
-  },
-  "customization_guide": {
-    "uc-taskmanager형 프로젝트 (md 편집 중심)": "direct 범위를 넓게. build_test_required=false인 경우 대부분 direct 처리",
-    "uc-teamspace형 프로젝트 (코드 개발 중심)": "pipeline/full 중심. 단순 버그 수정은 pipeline, 멀티도메인 기능은 full",
-    "max_tasks 조정": "팀 규모나 컨텍스트 한계에 따라 pipeline의 max_tasks를 3~7 사이로 조정 가능"
-  }
-}