uctm 1.5.4 → 2.0.0

package/lib/update.mjs

@@ -44,5 +44,5 @@ export function update(isGlobal) {
   console.log(`\n  Updating ${dim(label)} ...`);
   console.log(`    ${green('✓')} ${agentCount} agent files updated`);
   console.log(`    ${green('✓')} ${refCount} reference files updated`);
-  console.log(`    ${dim('-')} CLAUDE.md, router_rule_config.json untouched\n`);
+  console.log(`    ${dim('-')} CLAUDE.md untouched\n`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uctm",
-  "version": "1.5.4",
+  "version": "2.0.0",
   "description": "Universal Claude Task Manager — SDD-based task pipeline subagent system for Claude Code CLI",
   "type": "module",
   "bin": {
@@ -11,7 +11,6 @@
     "lib/",
     "agents/",
     "references/",
-    ".agent/",
     ".claude-plugin/",
     "skills/"
   ],
@@ -34,8 +33,5 @@
     "type": "git",
     "url": "git+https://github.com/UCJung/uc-taskmanager-claude-agent.git"
   },
-  "homepage": "https://github.com/UCJung/uc-taskmanager-claude-agent#readme",
-  "dependencies": {
-    "uctm": "^1.5.0"
-  }
+  "homepage": "https://github.com/UCJung/uc-taskmanager-claude-agent#readme"
 }

package/references/agent-flow.md

@@ -1,179 +1,179 @@
 # Agent Flow — Main Claude 역할 가이드
 
-> Main Claude는 실행흐름에 따라 agent를 실행하세요.
-> Agent들이 승인 요청을 하면 사용자에게 질문하고 승인하면 흐름에 따라 진행하세요.
-> agent가 종료되면 흐름에 따라 다음 Agent를 실행하세요.
-> 다음 Agent를 실행할때 반환값을 전달하세요.
+> Main Claude는 **트리거와 게이트 경계**만 담당합니다.
+> 파이프라인 내부 진행(WORK 생성 → 설계 → TASK 실행 → 완료)은 **orchestrator**가 전담합니다.
+> Main Claude는 orchestrator 외의 다른 에이전트를 **직접 spawn하지 않습니다**.
 
 ---
 
-## 파이프라인 시작
+## 1. Main Claude 역할 (트리거 + 게이트 경계)
 
-Main Claude는 specifier를 호출하고 사용자의 요구사항 받은것을 그대로 전달하세요.
-당신의 역할은 흐름에 따라 실행하는 것이지 
+Main Claude가 직접 수행하는 일은 다음 4가지뿐입니다.
 
-## 파이프라인 흐름
+1. **트리거 감지** — `[tag]` 메시지 또는 WORK 재개 요청(예: "WORK-01 계속실행", "resume WORK-01")을 감지.
+2. **orchestrator 1회 spawn** — 다음을 전달:
+   - `REFERENCES_DIR={절대 경로}`
+   - `mode=gated|auto` — 사용자 메시지에 "auto"/"자동으로"가 포함되면 `auto`, 그 외는 기본값 `gated`
+   - 사용자 요청 원문 (재개 요청이면 대상 `WORK_ID`)
+   - spawn 결과로 받는 **agentId를 보관**한다(재개 시 name이 아니라 **agentId**로 지정 — 이름 재사용 오배달 방지).
+3. **게이트 처리** — orchestrator가 `<gate type="stage">` 또는 `<gate type="decision">`을 반환하고 **yield(파킹)** 하면:
+   1. 게이트 내용을 사용자에게 그대로 제시한다 — `type="stage"`는 완료 요약, `type="decision"`은 배경(`<context>`) + 선택지(`<options>`) + 권고안(`<recommended>`)(`AskUserQuestion` 등으로 선택 요청).
+   2. 사용자의 승인 또는 선택을 기다린다.
+   3. 응답을 받으면 **`SendMessage(agentId, 결정내용)`으로 컨텍스트를 유지한 채 재개**한다.
+   4. `SendMessage`가 실패하면(파킹 핸들 유실 등) **폴백**: `works/{WORK_ID}/work_{WORK_ID}.log` + `DECISIONS.md`를 근거로 orchestrator를 `WORK_ID`와 함께 새로 spawn해 재개시킨다.
+4. **완료 처리** — orchestrator가 최종 WORK 요약을 반환하면 사용자에게 그대로 릴레이하고 **`TaskStop(agentId)`로 파킹 핸들을 해제**한다.
 
-```
-[] 태그 감지 → specifier 호출
-    │
-    specifier 실행 mode 판단
-    │
-    ├─ direct mode → specifier 수행 → planner 역할 수행
-    │
-    └─ pipeline/full → specifier 수행 → planner dispatch XML 반환
-
-```
+`mode=auto`인 경우 orchestrator가 게이트/의사결정 정지 없이 1회 spawn으로 완주하므로, 3단계(게이트 처리)는 발생하지 않는다 — Main Claude는 spawn 후 최종 결과만 수신·릴레이하고 `TaskStop`으로 마무리한다.
 
 ---
 
-## Direct 모드 (Specifier가 Planner 겸임)
+## 2. Orchestrator 내부 흐름
 
-```
-1. specifier 호출 → planner 역할 수행 + builder dispatch XML 반환
-2. ⛔ 정지 — 요약을 사용자에게 제시하고 승인 대기
-3. builder 호출
-4. verifier 호출
-5. committer 호출
-```
+Main Claude가 관여하지 않는 orchestrator 내부 진행이다. 상세 절차와 로그 규칙은 `develop/agents/orchestrator.md`를 정본으로 하며, 아래는 Main Claude가 게이트 신호를 올바르게 해석하기 위한 요약이다.
 
----
+### STEP A. Specifier spawn (WORK 생성)
 
-## Pipeline 모드
+- orchestrator가 specifier를 중첩 spawn → `Requirement.md` + WORK 폴더 생성, 복잡도 판정(단순/복잡).
+- `mode=gated`: 활동 로그에 `GATE_WAIT — stage=specifier` 기록 → `<gate type="stage" work="{WORK}" stage="specifier">` 반환 후 **yield**.
+- `mode=auto`: 게이트 생략, `STAGE_DONE — stage=specifier` 즉시 기록 후 STEP B로 진행.
 
-```
-1. specifier 호출 
-2. planner 호출
-3. ⛔ 정지 — Requirement.md + PLAN.md + TASK 목록을 제시하고 승인 대기
-4. 각 TASK에 대해 (오름차순):
-   a. builder 호출 TASK별
-   b. verifier 호출 TASK별
-   c. committer 호출 TASK별
-   d. 미완료 TASK가 남아있으면 다음 TASK로 계속
-```
+### STEP B. Planner spawn
 
----
+- planner를 중첩 spawn → `PLAN.md` + TASK DAG 생성.
+- `mode=gated`: `GATE_WAIT — stage=planner` 기록 → `<gate type="stage" work="{WORK}" stage="planner">` 반환 후 **yield**.
+- `mode=auto`: 게이트 생략, `STAGE_DONE — stage=planner` 즉시 기록 후 STEP C로 진행.
 
-## Full 모드 (Scheduler 포함)
+### STEP C. TASK DAG 실행 — 게이트 없음
 
-```
-1. specifier 호출
-2. planner 호출
-3. ⛔ 정지 — Requirement.md + PLAN.md + TASK 목록을 제시하고 승인 대기
-4. scheduler 호출
-5. builder 호출
-6. verifier 호출
-7. committer 호출
-8. 미완료 TASK가 남아있으면 4.scheduler 호출
-```
+- `work_{WORK}.log` + `PLAN.md`로 DAG를 해석해 READY TASK를 오름차순으로 판정한다. 복수 READY면 builder를 병렬로 중첩 spawn한다.
+- TASK별로 builder → verifier → committer를 순차 spawn한다. 이 단계는 사용자 승인 대상이 아니므로 고정 게이트가 없다.
+- verifier/committer가 FAIL을 반환하면 builder에 최대 2회 재디스패치(총 3회 시도)한다. 3회 모두 실패하면 자식이 `<needs-decision>`으로 orchestrator에 상향하고, `mode=gated`면 게이트로 승격, `mode=auto`면 권고안 자동결정 후 계속한다.
 
-병렬 실행: scheduler가 여러 READY TASK를 반환하면 builder를 동시에 호출.
+### STEP D. 로그 일괄 기록
 
----
+- 활동 로그를 기록하는 주체는 **orchestrator뿐**이다.
+- 이벤트 순서: `ORCHESTRATOR_START` → (`STAGE_START` → [`GATE_WAIT`/`DECISION_WAIT` → `DECISION`] → `STAGE_DONE`)를 단계마다 반복 → `ORCHESTRATOR_DONE`.
 
-## 기존 WORK 재개
+### 재개 규칙 (마지막 로그 이벤트 기준)
 
-PLAN.md + TASK가 이미 있는 WORK의 파이프라인 재개:
+| 마지막 로그 이벤트 | 판정 | 처리 |
+|---|---|---|
+| 로그 없음 | 신규 WORK | STEP A부터 시작 |
+| `{STAGE}_START`만 있고 대응하는 `STAGE_DONE`/`GATE_WAIT`/`DECISION_WAIT` 없음 | 자식 실행 중 중단됨 | 자식 재실행 |
+| `GATE_WAIT — stage=X` | 게이트 미승인 | 자식 재실행 없이 디스크 산출물 재사용, **동일 게이트를 재제시** |
+| `DECISION_WAIT — stage=X` | 결정 미확정 | `DECISIONS.md`의 `상태: PENDING` 항목을 동일 배경/선택지/권고안으로 재제시 |
+| `DECISION — ... by=...` | 결정 확정, 후속 `STAGE_DONE` 없음 | 결정을 반영해 해당 단계 이어서 진행 |
+| `STAGE_DONE — stage=X` | 해당 단계 완료(게이트 통과됨) | 다음 단계로 진행 |
+| `ORCHESTRATOR_DONE` | WORK 이미 완료 | 재개 불필요 — 완료 상태 보고 |
 
-```
-1. works/{WORK_ID}/work_{WORK_ID}.log의 마지막 줄을 읽어 현재 상태 판단
-   핵심 규칙: *_START = 중단됨 (해당 단계 재수행), *_DONE = 완료됨 (다음으로 이동)
-
-   - COMMITTER_DONE — TASK-NN  → TASK-NN 완료, 다음 TASK부터 재개
-   - COMMITTER_START — TASK-NN → 중단됨, TASK-NN committer 재수행
-   - VERIFIER_DONE — TASK-NN   → 검증됨, TASK-NN committer부터 재개
-   - VERIFIER_START — TASK-NN  → 중단됨, TASK-NN verifier 재수행
-   - BUILDER_DONE — TASK-NN    → 빌드됨, TASK-NN verifier부터 재개
-   - BUILDER_START — TASK-NN   → 중단됨, TASK-NN builder 재수행
-   - PLANNER_DONE              → 계획 완료, 첫 TASK 시작
-   - PLANNER_START             → 중단됨, planner 재수행
-   - SPECIFIER_DONE            → specifier 완료, planner 호출
-   - SPECIFIER_START           → 중단됨, specifier 재수행
-   - 로그 파일 없음            → 처음부터 시작
-
-2. 남은 각 TASK에 대해:
-   a. builder 호출 → 구현
-   b. verifier 호출 → 검증
-   c. committer 호출 → 커밋
-```
+> **핵심 불변식**: `STAGE_DONE`은 게이트가 있는 단계에서는 게이트가 해소(RESOLVED)된 이후에만 기록된다. 따라서 **미승인 게이트는 로그에 `STAGE_DONE`이 남지 않아 재개 시 절대 스킵되지 않는다.**
+
+### 슬라이딩 윈도우 (컨텍스트 핸드오프)
+
+orchestrator가 자식 프롬프트를 구성할 때 이전 단계 결과를 다음 기준으로 압축해 전달한다.
+
+| 단계 거리 | 상세 레벨 | 포함 필드 |
+|---|---|---|
+| 직전 (1단계) | `FULL` | what + why + caution + incomplete |
+| 2단계 전 | `SUMMARY` | what만 (1-3줄) |
+| 3단계+ | `DROP` | 전달하지 않음 |
 
 ---
 
-## 에이전트 역할 요약
+## 3. 승인 게이트 (CRITICAL)
 
-| 에이전트 | 역할 | 모델 |
-|----------|------|------|
-| specifier | 요구사항 분석 | opus |
-| planner | 실행계획 수립 + TASK 분해 | opus |
-| scheduler | DAG 관리 + 디스패치 | haiku |
-| builder | 코드 구현 | sonnet |
-| verifier | 빌드/린트/테스트 검증 | haiku |
-| committer | 결과 보고서 + git commit | haiku |
+게이트는 orchestrator가 자율 실행을 멈추고 반환하는 정지 신호다. 중첩 sub-agent는 사용자에게 직접 질문할 수 없으므로, **승인/결정의 실제 처리(사용자에게 묻고 응답을 받는 것)는 항상 Main Claude 경계에서 이뤄진다.**
+
+> **반드시 정지하고 명시적 사용자 승인/결정을 기다려야 합니다.**
+> 유일한 예외는 auto 모드 — 사용자의 원본 메시지에 "auto" 또는 "자동으로"가 포함된 경우뿐이다.
+
+게이트는 두 종류이며 Main Claude의 처리 방식은 동일하다(§1-3 참조).
+
+### 고정 게이트 (2개, `type="stage"`)
+
+| 게이트 | 발생 지점 | `stage` 값 | 승인 후 다음 |
+|---|---|---|---|
+| GATE-1 | specifier 완료 후 | `specifier` | planner spawn |
+| GATE-2 | planner 완료 후 | `planner` | STEP C(builder) |
+
+### 동적 게이트 (`type="decision"`)
+
+- 고정 게이트 사이 **어느 단계에서든**(설계·구현·검증 포함) orchestrator 또는 자식이 사용자 결정이 필요하다고 판단하면 즉시 발생한다.
+- 판단 기준 예: 요구 해석의 다의성, 설계 트레이드오프, 명시된 범위 초과, 파괴적/비가역적 변경, 재시도 3회 실패.
+- 자식은 `<needs-decision>`으로 orchestrator에 먼저 상향하며, orchestrator가 자동 결정 가능 여부를 판단한 뒤 불가능하면 `<gate type="decision">`으로 승격해 Main Claude에 전달한다.
+- `<gate type="decision">`은 `<context>`(배경)·`<options>`(선택지)·`<recommended>`(권고안)를 반드시 포함한다.
+
+### auto 모드
+
+| 모드 | 정지 횟수 | 처리 |
+|---|:---:|---|
+| gated (기본값) | 고정 게이트 1~2회 + 동적 게이트 발생 시마다 | Main Claude가 매번 승인/선택 후 재개 |
+| auto ("auto"/"자동으로") | 0 | orchestrator 1회 spawn으로 완주. 모든 판단 지점은 권고안으로 자동결정되어 최종 보고서 `## 자동 결정 사항`과 `DECISIONS.md`에 기록 |
+
+### 승인 요청 방법 (Main Claude)
+
+1. `<gate>` 내용을 그대로 사용자에게 제시(요약 또는 배경+선택지+권고안).
+2. "진행할까요?" 또는 동등한 질문(`type="decision"`이면 선택 요청).
+3. **사용자 응답 대기** — 응답 전까지 `SendMessage`로 재개하지 말 것.
 
 ---
 
-## 모드별 서브에이전트 Spawn 수
+## 4. 모드/스폰 수
 
-| 모드 | Specifier | Planner | Scheduler | Builder | Verifier | Committer | 합계 |
-|------|:---------:|:-------:|:---------:|:-------:|:--------:|:---------:|:----:|
-| direct | 1 (겸임) | — | — | 1 | 1 | 1 | **4** |
-| pipeline (N TASK) | 1 | 1 | — | N | N | N | **2 + 3N** |
-| full (N TASK) | 1 | 1 | 1 | N | N | N | **3 + 3N** |
+| Main → Orchestrator | Orchestrator → Specifier | → Planner | → Builder | → Verifier | → Committer | 합계 |
+|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| 1 | 1 | 1 | N | N | N | **3 + 3N** |
+
+- `gated`/`auto` 여부는 spawn 수에 영향을 주지 않는다 — 게이트 정지 발생 여부만 다르다(§3).
+- 위 표는 orchestrator 내부 자식 spawn만 집계한다. Main Claude가 spawn하는 대상은 오직 orchestrator 1개다.
 
 ---
 
-## 승인 게이트 (CRITICAL)
+## 5. 기존 WORK 재개
+
+Main Claude는 재개 요청을 감지하면 대상 `WORK_ID`를 orchestrator에 전달하는 것으로 끝난다. 재개 지점 판정(§2 "재개 규칙")은 orchestrator가 로그를 읽어 스스로 수행한다.
 
-> **반드시 정지하고 명시적 사용자 승인을 기다려야 합니다.**
-> "approve", "승인", "proceed", "진행" 등의 응답이 올 때까지 다음 에이전트를 호출하지 말 것.
-> 유일한 예외는 auto 모드 — 사용자의 원본 메시지에 "auto" 또는 "자동으로"가 포함된 경우.
+1. 파킹된 agentId를 보관하고 있으면 → `SendMessage(agentId, "WORK-{NN} 계속")`으로 컨텍스트를 유지한 채 재개.
+2. 세션이 끊겨 핸들이 없으면(예: 새 세션에서 "WORK-01 계속실행") → orchestrator를 `WORK_ID` + `REFERENCES_DIR` + (승계된) `mode`와 함께 새로 spawn → orchestrator가 `work_{WORK_ID}.log`의 마지막 이벤트로 재개 지점을 판정한다.
+3. 단순/복잡 분기는 다시 묻지 않는다 — orchestrator가 `PLAN.md`와 TASK 구성에서 판정한다.
 
-| 모드 | 승인 횟수 | 시점 | 사용자에게 보여줄 내용 |
-|------|:---------:|------|------------------------|
-| direct | 1 | Specifier 완료 및 Planner 역할 수행 완료 후 | Requirement.md + PLAN.md + TASK-00.md 요약 |
-| pipeline/full | 2 | Specifier 완료 후, Planner 완료 후 | Requirement.md 요약, PLAN.md + TASK-00.md 요약|
-| auto-approve | 0 | — | 모든 승인 게이트 생략 |
+---
 
-**승인 요청 방법:**
-1. 생성된 내용 요약 제시 (파일, 범위, execution-mode)
-2. "진행할까요?" 또는 동등한 질문
-3. **사용자 응답 대기** — 승인 전까지 builder를 호출하지 말 것
+## 6. 에이전트 역할 요약
+
+| 에이전트 | 역할 | 모델 |
+|---|---|---|
+| orchestrator | 파이프라인 전체 조정 + TASK DAG 스케줄링 + 게이트/의사결정 중재 + 로그 일괄 기록 | opus |
+| specifier | 요구사항 분석 | opus |
+| planner | 실행계획 수립 + TASK 분해 | opus |
+| builder | 코드 구현 | sonnet |
+| verifier | 빌드/린트/테스트 검증 | haiku |
+| committer | 결과 보고서 + git commit | haiku |
 
 ---
 
 ## References Directory 전달 (필수)
 
-Main Claude는 모든 서브에이전트 호출 시 references 디렉토리 경로를 전달해야 합니다.
-설치 방법(npm 또는 plugin)에 관계없이 서브에이전트가 레퍼런스 파일을 찾을 수 있도록 합니다.
+Main Claude는 orchestrator spawn 시(신규/재개 모두) references 디렉토리 경로를 전달해야 합니다.
+설치 방법(npm 또는 plugin)에 관계없이 orchestrator와 그 자식이 레퍼런스 파일을 찾을 수 있도록 합니다.
 
 **전달 방법:**
-- 모든 Task tool 호출의 프롬프트 상단에 `REFERENCES_DIR={absolute_path}` 추가
+- orchestrator spawn 프롬프트 상단에 `REFERENCES_DIR={absolute_path}` 추가
 - npm 설치: `.claude/references` 사용 (프로젝트 루트 기준 기본값)
 - plugin 설치: 스킬의 "Base directory"에서 유도 (`{base_dir}/../../references`)
 
 **예시:**
 ```
 REFERENCES_DIR=C:/Users/me/.claude/plugins/cache/uc-taskmanager/abc123/references
+mode=gated
 
-<dispatch to="builder" ...>
-  ...
-</dispatch>
+[WORK] 사용자 요청 원문...
 ```
 
-REFERENCES_DIR를 사용할 수 없는 경우 (예: plugin 없는 npm 설치), 서브에이전트는 `.claude/references/`를 폴백으로 사용.
-
----
-
-## Context Handoff (슬라이딩 윈도우)
-
-| 거리 | 레벨 | 내용 |
-|------|------|------|
-| 직전 | FULL | what + why + caution + incomplete |
-| 2단계 전 | SUMMARY | what 1-2줄 |
-| 3단계+ | DROP | 전달하지 않음 |
+REFERENCES_DIR를 사용할 수 없는 경우(예: plugin 없는 npm 설치), orchestrator는 `.claude/references/`를 폴백으로 사용합니다. orchestrator는 자신이 읽은 레퍼런스 내용을 `<ref-cache>`(`xml-schema.md` § 4)로 자식에게 재전달할 수 있습니다.
 
 ---
 
 ## 레퍼런스 로딩
 
-각 서브에이전트는 시작 시 `{REFERENCES_DIR}/`에서 자체 레퍼런스 파일을 읽습니다. Main Claude는 레퍼런스 파일을 읽지 않으며 — `agent-flow.md`만 읽습니다.
+Main Claude는 레퍼런스 파일을 읽지 않으며 — `agent-flow.md`만 읽습니다. orchestrator와 그 자식들이 `{REFERENCES_DIR}/`에서 각자(또는 ref-cache로 전달받아) 필요한 레퍼런스 파일을 읽습니다.

package/references/context-policy.md

@@ -55,7 +55,7 @@
 1. builder 성공 여부 확인 (context-handoff 상태 확인)
 2. result.md 작성 + git commit
 
-출력: → `{REFERENCES_DIR}/file-content-schema.md` § 4 참조
+출력: → `{REFERENCES_DIR}/file-content-schema.md` § 3 참조
 
 ## TASK 간 의존성 전달
 
@@ -63,7 +63,9 @@
 - 2단계 전: **SUMMARY** (what만)
 - 3단계+: **DROP**
 
-## Scheduler 디스패치
+## Orchestrator 디스패치
+
+TASK DAG 실행 중 다음 자식(중첩 spawn)의 프롬프트를 구성하는 주체는 **orchestrator**다 — dispatch XML을 만들어 자식 spawn 프롬프트에 포함한다.
 
 ```xml
 <!-- Verifier: Builder FULL -->

package/references/file-content-schema.md

@@ -7,10 +7,10 @@
 | 생성 파일 | 참조 섹션 | 위반 시 결과 |
 |-----------|----------|-------------|
 | `Requirement.md` | § 0 |  |
-| `PLAN.md` | § 1 | `parsePlanMd()` 파싱 실패, scheduler 작동 불가 |
+| `PLAN.md` | § 1 | `parsePlanMd()` 파싱 실패, orchestrator 파이프라인 작동 불가 |
 | `TASK-XX.md` | § 2 | `parseTaskFilename()` DB 등록 누락 |
 | `TASK-XX_result.md` | § 3 | context-handoff 누락 |
-| `TASK-XX_result.md` (direct) | § 4 | result.md 인식 실패 |
+| `DECISIONS.md` | § 4 | 재개(resume) 시 PENDING 결정 재제시 불가 |
 
 ---
 
@@ -50,7 +50,6 @@
 
 > Created: {YYYY-MM-DD}
 > Requirement: {REQ-XXX | 사용자 요청 텍스트}
-> Execution-Mode: {direct | pipeline | full}
 > Project: {프로젝트 이름}
 > Tech Stack: {스택}
 > Language: {lang_code}
@@ -178,7 +177,7 @@
 
 ---
 
-## § 3. TASK-XX_result.md (full / pipeline)
+## § 3. TASK-XX_result.md
 
 경로: `works/{WORK_ID}/TASK-XX_result.md`
 
@@ -231,27 +230,47 @@ None
 
 ---
 
-## § 4. TASK-XX_result.md (direct 모드)
+## § 4. DECISIONS.md
+
+경로: `works/{WORK_ID}/DECISIONS.md`
+
+orchestrator가 `<gate type="decision">` 또는 자식 에이전트의 `<needs-decision>`(→ `xml-schema.md` § 5, § 6)을 수신할 때마다 항목을 추가하는 결정 로그. 게이트가 yield된 시점에는 항목을 **PENDING**으로 먼저 기록하고, 승인/자동결정으로 해소되면 같은 항목을 **RESOLVED**로 갱신한다.
 
 ```markdown
-# TASK-00 Result
+# DECISIONS — WORK-NN
 
-> WORK: WORK-NN — {제목}
-> Completed: {YYYY-MM-DD HH:MM}
-> Execution-Mode: direct
-> Status: **DONE**
+## D-01
+> 시각: {YYYY-MM-DDTHH:MM:SSZ}
+> 단계: {specifier|planner|builder|verifier|committer}
+> 상태: {PENDING|RESOLVED}
+
+### 배경
+{결정이 필요한 이유}
 
-## 요약
-{1줄}
+### 선택지
+1. {선택지 1}
+2. {선택지 2}
 
-## 변경 파일
-- `{path}` — {설명}
+### 권고안
+{orchestrator/자식 에이전트가 제시한 권고}
 
-## 검증
-- Build: PASS (self-check)
-- Lint: PASS (self-check)
+### 확정값
+{확정된 선택 — PENDING 상태에서는 공란 또는 "(대기 중)"}
+
+### 결정주체
+{user 승인 | auto}
 ```
 
+| 필드 | PENDING (게이트 yield 시) | RESOLVED (해소 후) |
+|------|---------------------------|---------------------|
+| 확정값 | 공란 / `(대기 중)` | 채움 |
+| 결정주체 | 공란 | `user 승인` 또는 `auto` |
+
+- **재개(resume) 근거**: orchestrator가 중단 후 재개할 때 DECISIONS.md에서 `상태: PENDING` 항목을 찾아 동일한 배경·선택지·권고안으로 게이트를 다시 제시한다. 이 상태 필드가 없으면 재개 시 이미 물었던 결정인지 판단할 수 없어, 미승인 결정을 건너뛰거나 사용자에게 같은 질문을 중복 제시하는 오류가 발생한다.
+- 활동 로그의 `DECISION_WAIT`/`DECISION` 이벤트와 1:1로 대응한다 → `work-activity-log.md` 참조.
+
+생성 주체: orchestrator
+
 ---
 
 ## § 5. 파일 이름 규칙
@@ -262,6 +281,7 @@ None
 | WORK 계획 | `PLAN.md` | planner / specifier |
 | TASK 계획 | `TASK-NN.md` | planner / specifier |
 | TASK 결과 | `TASK-NN_result.md` | committer |
-| 활동 로그 | `work_WORK-NN.log` | 모든 에이전트 (추가) |
+| 결정 로그 | `DECISIONS.md` | orchestrator |
+| 활동 로그 | `work_WORK-NN.log` | orchestrator (추가) |
 
 `WORK-NN-TASK-NN.md` 형식 금지 → `parseTaskFilename()`이 인식할 수 없음.

package/references/shared-prompt-sections.md

@@ -71,29 +71,26 @@ works/{WORK_ID}/
 # Glob 도구 사용: pattern "works/WORK-*/" → 모든 WORK 디렉토리 목록 (정렬)
 # 각 WORK (내림차순)에 대해 works/WORK-NN/work_WORK-NN.log 마지막 줄 읽기
 #   - 로그 파일 없음 → 시작 안 됨
-#   - 마지막 줄에 마지막 TASK 번호의 "COMMITTER_DONE" 포함 → 남은 TASK 확인
+#   - 마지막 줄이 "ORCHESTRATOR_DONE" → 완료됨
 # 완전히 완료되지 않은 첫 번째 WORK가 활성 WORK
 
 # 모든 WORK 목록
 # Glob 도구 사용: pattern "works/WORK-*/"
 
-# 활동 로그의 마지막 줄로 WORK/TASK 상태 파악
+# 활동 로그의 마지막 줄로 WORK/TASK 상태 파악 (orchestrator가 일괄 기록 → work-activity-log.md 참조)
 # works/${WORK_ID}/work_${WORK_ID}.log 마지막 줄 읽기
 #   형식: [timestamp] EVENT — description
 #
-#   핵심 규칙: *_START에 대응하는 *_DONE이 없으면 = 중단됨, 해당 단계 재수행 필요
+#   핵심 규칙: STAGE_START에 대응하는 STAGE_DONE/GATE_WAIT/DECISION_WAIT가 없으면 = 자식 실행 중 중단됨, 해당 단계 재수행 필요
 #
-#   COMMITTER_DONE — TASK-NN → TASK-NN 완료, 다음은 TASK-(NN+1)
-#   COMMITTER_START — TASK-NN → committer 중단됨, TASK-NN committer 재수행
-#   VERIFIER_DONE — TASK-NN  → TASK-NN 검증됨, committer 필요
-#   VERIFIER_START — TASK-NN → verifier 중단됨, TASK-NN verifier 재수행
-#   BUILDER_DONE — TASK-NN   → TASK-NN builder 완료, verifier 필요
-#   BUILDER_START — TASK-NN  → builder 중단됨, TASK-NN builder 재수행
-#   PLANNER_DONE             → 계획 완료, 첫 TASK 시작
-#   PLANNER_START            → planner 중단됨, planner 재수행
-#   SPECIFIER_DONE           → specifier 완료, planner 필요
-#   SPECIFIER_START          → specifier 중단됨, specifier 재수행
-#   로그 파일 없음           → 처음부터 시작
+#   ORCHESTRATOR_DONE                        → WORK 전체 완료
+#   STAGE_DONE — stage=X[ task=TASK-NN]      → 해당 단계 완료(게이트 통과됨), 다음 단계로
+#   GATE_WAIT — stage=X                      → 게이트 미승인, 자식 재실행 없이 동일 게이트 재제시
+#   DECISION_WAIT — stage=X[ task=TASK-NN]   → 결정 미확정, DECISIONS.md의 PENDING 항목 재제시
+#   DECISION — stage=X by=user|auto          → 결정 확정됨, 후속 STAGE_DONE 없으면 해당 단계 이어서 진행
+#   STAGE_START — stage=X[ task=TASK-NN]     → (대응 DONE/WAIT 없으면) 자식 실행 중 중단됨, 재실행
+#   ORCHESTRATOR_START                       → orchestrator 시작됨, 하위 이벤트로 세부 판정
+#   로그 파일 없음                           → 처음부터 시작 (신규 WORK)
 ```
 
 ---
@@ -115,6 +112,18 @@ works/{WORK_ID}/
 
 ---
 
+## § 6. 자동결정 기록 관례
+
+권고안을 자동결정(결정주체 `auto`)한 경우, 판단 근거를 남겨 추적 가능하게 한다.
+
+- **기록 위치**: `works/{WORK_ID}/DECISIONS.md`(항목별 배경/선택지/권고안/확정값/결정주체/상태) + 최종 결과보고서 `## 자동 결정 사항` 목록.
+- **기록 시점**: 결정 확정 즉시 `RESOLVED`로 기록. `mode=auto`뿐 아니라 `mode=gated`에서 orchestrator가 경미한 사항으로 판단해 게이트 없이 자체 확정(`by=auto`)한 경우도 동일하게 기록.
+- **최소 기재 항목**: 대상(stage 또는 task) · 확정값 · 근거 1줄.
+
+→ 상세 포맷: `file-content-schema.md` § 4 참조. 기록 주체·이벤트: `work-activity-log.md`의 `DECISION` 이벤트 참조.
+
+---
+
 ## § 7. PLAN.md 필수 메타 정보 — 7개 필드
 
 → `{REFERENCES_DIR}/file-content-schema.md` § 1 참조
@@ -123,7 +132,6 @@ works/{WORK_ID}/
 |------|------|------|
 | `> Created:` | ✅ | YYYY-MM-DD |
 | `> Requirement:` | ✅ | `REQ-XXX` 또는 사용자 요청 텍스트 |
-| `> Execution-Mode:` | ✅ | `direct` / `pipeline` / `full` |
 | `> Project:` | ✅ | 프로젝트 이름 |
 | `> Tech Stack:` | ✅ | 감지된 기술 스택 |
 | `> Language:` | ✅ | 언어 코드 (`ko`, `en` 등) |

package/references/work-activity-log.md

@@ -1,26 +1,33 @@
 # 작업 활동 로그
 
-`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만. 중간 단계 없음.
+1. **기록 주체**: **orchestrator**. 자식의 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`을 게이트 통과 이전에 기록하면 재개 시 미승인 게이트를 건너뛰는 사고로 이어진다.
 
 ## 형식
 
 ```
-[YYYY-MM-DDTHH:MM:SSZ] AGENT_EVENT — description
+[YYYY-MM-DDTHH:MM:SSZ] EVENT — description
 ```
 
-## 필수 항목
+## 이벤트 체계 (orchestrator 기록)
 
-| 에이전트 | 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` |
+| 이벤트 | 기록 시점 | 예시 |
+|--------|----------|------|
+| `ORCHESTRATOR_START` | orchestrator 실행 시작 | `ORCHESTRATOR_START — WORK-NN orchestrator started` |
+| `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` |
+
+- `stage` 값: `specifier`/`planner`/`builder`/`verifier`/`committer`.
+- `by` 값: `user`/`auto`. `<decision>`(§ 7, `xml-schema.md`)의 `by` 속성과 동일한 값 체계를 사용.
+- 확정된 결정의 상세 내용(배경/선택지/권고안/확정값)은 로그가 아니라 `works/{WORK_ID}/DECISIONS.md`에 기록한다 → `file-content-schema.md` § 4 참조. 로그의 `DECISION` 이벤트는 "언제·누가 결정했는지"만 남긴다.