uctm 1.5.2 → 1.5.4

package/references/file-content-schema.md

@@ -0,0 +1,267 @@
+# 파일 내용 스키마
+
+파이프라인 산출물 파일 형식의 단일 정의 소스.
+
+## 준수사항
+
+| 생성 파일 | 참조 섹션 | 위반 시 결과 |
+|-----------|----------|-------------|
+| `Requirement.md` | § 0 |  |
+| `PLAN.md` | § 1 | `parsePlanMd()` 파싱 실패, scheduler 작동 불가 |
+| `TASK-XX.md` | § 2 | `parseTaskFilename()` DB 등록 누락 |
+| `TASK-XX_result.md` | § 3 | context-handoff 누락 |
+| `TASK-XX_result.md` (direct) | § 4 | result.md 인식 실패 |
+
+---
+
+## § 0. Requirement.md
+
+경로: `works/{WORK_ID}/Requirement.md`
+
+```markdown
+# Requirement — WORK-NN
+
+## Original Request
+> 사용자의 정확한 입력
+
+## Functional Requirements
+- FR-01: ...
+- FR-02: ...
+
+## Non-Functional Requirements
+- NFR-01: ...
+
+## Acceptance Criteria
+- [ ] 검증 가능한 기준
+```
+
+생성 주체: Specifier (모든 요청에 필수)
+
+---
+
+## § 1. PLAN.md
+
+경로: `works/{WORK_ID}/PLAN.md`
+
+> 요구사항 수준에 따라 ## 설계 이하 간략화 가능
+
+```markdown
+# WORK-01: {제목}
+
+> Created: {YYYY-MM-DD}
+> Requirement: {REQ-XXX | 사용자 요청 텍스트}
+> Execution-Mode: {direct | pipeline | full}
+> Project: {프로젝트 이름}
+> Tech Stack: {스택}
+> Language: {lang_code}
+> Status: PLANNED
+
+## 목표
+{1-2문장}
+
+## 설계
+
+### 1. 아키텍처 방향
+
+- **접근 방식**: 신규 구축 / 기존 수정 / 확장
+- **구조**: (계층형, 이벤트 기반, 마이크로서비스 등)
+- **데이터 흐름**: (입력 → 처리 → 출력 경로 요약)
+
+### 2. 데이터 설계
+
+| 항목 | 내용 |
+|------|------|
+| 스키마 변경 | 있음 / 없음 |
+| 마이그레이션 필요 | 있음 / 없음 |
+| 변경 내용 | |
+
+### 3. 인터페이스 설계
+
+| 인터페이스 | 방식 | 엔드포인트/형식 | 관련 FR |
+|-----------|------|---------------|--------|
+| | REST / GraphQL / gRPC / 파일 | | |
+
+### 4. NFR 대응 설계
+
+| NFR ID | 요구사항 | 대응 방안 |
+|--------|---------|----------|
+| NFR-01 | | |
+| NFR-02 | | |
+
+## 작업 목록 
+
+| Task ID | 제목 | 의존관계 | Phase | 우선순위 | 매핑 FR/NFR | 예상 규모 |
+|---------|------|---------|-------|---------|------------|----------|
+| TASK-01 | | 없음 | 1 | Must | FR-01 | S/M/L |
+| TASK-02 | | TASK-01 | 2 | Must | FR-02, NFR-01 | S/M/L |
+| TASK-03 | | 없음 | 1 | Should | FR-03 | S/M/L |
+| | | | | | | |
+
+
+## Task 의존성 그래프
+{ASCII 다이어그램}
+
+## 리스크 및 대응
+
+| # | 리스크 | 발생 가능성 | 영향도 | 대응 전략 | 비고 |
+|---|--------|-----------|-------|----------|------|
+| R-01 | | 높/중/낮 | 높/중/낮 | 회피 / 완화 / 수용 | |
+| R-02 | | | | | |
+
+---
+
+## 추적성 매트릭스
+
+| 원본 요청 | FR/NFR | Task | 인수 기준 | 검증 방법 |
+|----------|--------|------|----------|----------|
+| | FR-01 | TASK-01 | AC-01 | 단위테스트 / 수동확인 / 자동화 |
+| | FR-02 | TASK-02 | AC-02 | |
+| | NFR-01 | TASK-02 | AC-03 | |
+
+---
+
+## 자체 검증 체크리스트
+
+- [ ] 모든 FR이 최소 1개 Task에 매핑됨
+- [ ] 모든 NFR이 설계 또는 Task에 반영됨
+- [ ] Task 간 순환 의존 없음
+- [ ] 제약조건 내 실현 가능
+- [ ] 각 Task에 완료 조건이 있음
+- [ ] 리스크가 식별되고 대응 전략이 있음
+- [ ] 실행 순서가 의존관계와 일치함
+
+---
+```
+
+제목 형식: `# WORK-NN: title` — `# PLAN WORK-NN:` 금지 (`parsePlanMd()` 오류)
+
+---
+
+## § 2. TASK-XX.md
+
+경로: `works/{WORK_ID}/TASK-XX.md`
+
+> `parseTaskFilename()` regex: `/^TASK-(\d+)\.md$/` — WORK 접두사 금지
+
+```markdown
+# TASK-XX: {제목}
+
+## WORK
+{WORK_ID}: {WORK 제목}
+
+## Task 개요
+
+| 항목 | 내용 |
+|------|------|
+| 목적 | (이 Task가 완료되면 무엇이 달라지는가) |
+| 매핑 요구사항 | FR-{NN}, NFR-{NN} |
+| 우선순위 | Must / Should / Could |
+| 예상 규모 | S / M / L |
+| 의존관계 | 없음 / TASK-{NN} 완료 후 |
+| Phase | Phase {N} |
+
+## Scope
+{설명}
+
+## Files
+| Path | Action | Description |
+|------|--------|-------------|
+| `src/file.ts` | CREATE | 설명 |
+
+## Acceptance Criteria
+- [ ] {기준}
+
+## Verify
+```bash
+{검증 명령}
+```
+
+---
+
+## § 3. TASK-XX_result.md (full / pipeline)
+
+경로: `works/{WORK_ID}/TASK-XX_result.md`
+
+```markdown
+# TASK-XX Result
+
+> WORK: {WORK_ID} — {제목}
+> Completed: {YYYY-MM-DD HH:MM}
+> Status: **DONE**
+
+{## Summary | ## 요약 | ## サマリー}
+{1-2줄}
+
+{## Completed Checklist | ## 완료 체크리스트 | ## 完了チェックリスト}
+- [x] {항목}
+
+{## Verification Results | ## 검증 결과 | ## 検証結果}
+- Build: ✅
+- Lint: ✅
+- Tests: ✅ (N passed)
+
+{## Files Changed | ## 변경 파일 | ## 変更ファイル}
+### Created
+- `path` — {설명}
+
+{## Issues Encountered | ## 발생 이슈 | ## 発生した問題}
+None
+
+{## Notes for Subsequent Tasks | ## 후속 TASK 참고사항 | ## 後続タスクへの注記}
+None
+
+{## Context Handoff | ## 컨텍스트 핸드오프 | ## コンテキスト引き継ぎ}
+
+### Builder Context (SUMMARY)
+{builder what 필드 1-3줄}
+
+### Verifier Context (FULL)
+{verifier context-handoff 4개 필드}
+```
+
+| 섹션 | en | ko | ja |
+|------|----|----|-----|
+| Summary | `## Summary` | `## 요약` | `## サマリー` |
+| Completed Checklist | `## Completed Checklist` | `## 완료 체크리스트` | `## 完了チェックリスト` |
+| Verification Results | `## Verification Results` | `## 검증 결과` | `## 検証結果` |
+| Files Changed | `## Files Changed` | `## 변경 파일` | `## 変更ファイル` |
+| Issues Encountered | `## Issues Encountered` | `## 발생 이슈` | `## 発生した問題` |
+| Notes for Subsequent Tasks | `## Notes for Subsequent Tasks` | `## 후속 TASK 참고사항` | `## 後続タスクへの注記` |
+| Context Handoff | `## Context Handoff` | `## 컨텍스트 핸드오프` | `## コンテキスト引き継ぎ` |
+
+---
+
+## § 4. TASK-XX_result.md (direct 모드)
+
+```markdown
+# TASK-00 Result
+
+> WORK: WORK-NN — {제목}
+> Completed: {YYYY-MM-DD HH:MM}
+> Execution-Mode: direct
+> Status: **DONE**
+
+## 요약
+{1줄}
+
+## 변경 파일
+- `{path}` — {설명}
+
+## 검증
+- Build: PASS (self-check)
+- Lint: PASS (self-check)
+```
+
+---
+
+## § 5. 파일 이름 규칙
+
+| 유형 | 형식 | 생성 주체 |
+|------|------|-----------|
+| 요구사항 | `Requirement.md` | specifier |
+| WORK 계획 | `PLAN.md` | planner / specifier |
+| TASK 계획 | `TASK-NN.md` | planner / specifier |
+| TASK 결과 | `TASK-NN_result.md` | committer |
+| 활동 로그 | `work_WORK-NN.log` | 모든 에이전트 (추가) |
+
+`WORK-NN-TASK-NN.md` 형식 금지 → `parseTaskFilename()`이 인식할 수 없음.

package/references/ref-cache-protocol.md

@@ -0,0 +1,31 @@
+# ref-cache 프로토콜
+
+## 개요
+
+ref-cache는 파이프라인 내 서브에이전트 호출 간 중복 파일 읽기를 방지하는 메커니즘입니다.
+레퍼런스 파일이 매번 디스크에서 다시 읽히는 대신 `<ref-cache>` XML 요소를 통해 에이전트 간에 전달됩니다.
+
+## 프로토콜 (4단계)
+
+1. 수신한 dispatch XML에 `<ref-cache>`가 있는지 **확인**
+2. 각 필수 레퍼런스 파일에 대해:
+   - ref-cache에 있으면 → **파일 읽기 건너뛰기**, 캐시된 내용 사용
+   - ref-cache에 없으면 → `{REFERENCES_DIR}/{filename}.md`에서 읽고 ref-cache에 추가
+3. 작업 완료 시, 반환하는 task-result XML에 병합된 `<ref-cache>` 포함
+4. **하위 호환성**: dispatch에 `<ref-cache>`가 없으면 모든 레퍼런스 파일을 정상적으로 읽기 (기존 동작)
+
+## ref-cache XML 형식
+
+전체 스키마는 `xml-schema.md` § 4 참조.
+
+```xml
+<ref-cache>
+  <ref key="file-content-schema">...내용...</ref>
+  <ref key="shared-prompt-sections">...내용...</ref>
+  <!-- 로딩된 레퍼런스 파일당 하나의 <ref> -->
+</ref-cache>
+```
+
+## 체인 전파
+
+파이프라인에서 ref-cache가 에이전트 간에 어떻게 흐르는지는 `agent-flow.md` § ref-cache Chain Propagation 참조.

package/references/shared-prompt-sections.md

@@ -0,0 +1,206 @@
+# 공유 프롬프트 섹션
+
+각 에이전트가 `cache_control` 마커를 통해 참조하는 공통 재사용 섹션.
+
+---
+
+## § 1. 출력 언어 규칙
+
+```
+우선순위: PLAN.md > Language: → CLAUDE.md ## Language → en (기본값)
+
+디스패치 시: <context><language> 필드에 결정된 언어 코드 전달
+섹션 헤더(##)도 결정된 언어로 작성 (언어 매핑 표 참조)
+```
+
+---
+
+## § 2. 빌드 및 린트 명령
+
+```bash
+# 빌드 자동 감지 (스크립트가 있을 때만 실행)
+if [ -f "package.json" ]; then
+  if node -e "const p=JSON.parse(require('fs').readFileSync('package.json','utf8')); process.exit(p.scripts&&p.scripts.build?0:1)" 2>/dev/null; then
+    npm run build 2>&1 || bun run build 2>&1 || yarn build 2>&1
+  fi
+elif [ -f "Cargo.toml" ]; then
+  cargo build 2>&1
+elif [ -f "go.mod" ]; then
+  go build ./... 2>&1
+elif [ -f "pyproject.toml" ] || [ -f "setup.py" ]; then
+  python -m py_compile $(find . -maxdepth 3 -name "*.py" -not -path "*/venv/*" 2>/dev/null) 2>&1
+elif [ -f "Makefile" ]; then
+  make build 2>&1 || make 2>&1
+fi
+
+# 린트 자동 감지 (스크립트가 있을 때만 실행)
+if [ -f "package.json" ]; then
+  if node -e "const p=JSON.parse(require('fs').readFileSync('package.json','utf8')); process.exit(p.scripts&&p.scripts.lint?0:1)" 2>/dev/null; then
+    npm run lint 2>&1 || bun run lint 2>&1 || true
+  fi
+elif [ -f "pyproject.toml" ]; then
+  ruff check . 2>&1 || python -m flake8 . 2>&1 || true
+fi
+```
+
+- 빌드/린트 스크립트가 없으면 → **생략 (N/A로 처리)**.
+- 빌드/린트 실패 시 보고 전에 항상 수정.
+
+---
+
+## § 3. WORK 및 TASK 파일 경로 패턴
+
+```
+works/{WORK_ID}/
+  ├─ Requirement.md                 # Specifier가 생성 (필수)
+  ├─ PLAN.md
+  ├─ TASK-00.md               # WORK 접두사 없음
+  ├─ TASK-00_result.md        # 구분자: 언더스코어
+  └─ TASK-01.md ...
+```
+
+- WORK ID: `WORK-NN` (예: `WORK-03`)
+- TASK ID: `TASK-NN` (예: `TASK-00`) — WORK 접두사 포함 금지
+
+---
+
+## § 4. 파일 시스템 Discovery 스크립트
+
+```
+# 미완료 TASK가 있는 최신 WORK 찾기
+# Glob 도구 사용: pattern "works/WORK-*/" → 모든 WORK 디렉토리 목록 (정렬)
+# 각 WORK (내림차순)에 대해 works/WORK-NN/work_WORK-NN.log 마지막 줄 읽기
+#   - 로그 파일 없음 → 시작 안 됨
+#   - 마지막 줄에 마지막 TASK 번호의 "COMMITTER_DONE" 포함 → 남은 TASK 확인
+# 완전히 완료되지 않은 첫 번째 WORK가 활성 WORK
+
+# 모든 WORK 목록
+# Glob 도구 사용: pattern "works/WORK-*/"
+
+# 활동 로그의 마지막 줄로 WORK/TASK 상태 파악
+# works/${WORK_ID}/work_${WORK_ID}.log 마지막 줄 읽기
+#   형식: [timestamp] EVENT — description
+#
+#   핵심 규칙: *_START에 대응하는 *_DONE이 없으면 = 중단됨, 해당 단계 재수행 필요
+#
+#   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 재수행
+#   로그 파일 없음           → 처음부터 시작
+```
+
+---
+
+## § 5. Task Result XML 형식
+
+```xml
+<task-result work="{WORK_ID}" task="{TASK_ID}" agent="{agent}" status="{PASS|FAIL}">
+  <summary>{1-2줄 요약}</summary>
+  <files-changed>
+    <file action="{created|modified|deleted}" path="{path}">{설명}</file>
+  </files-changed>
+  <verification>
+    <check name="{type}" status="{PASS|FAIL|N/A}">{상세}</check>
+  </verification>
+  <notes>{다음 단계를 위한 메모}</notes>
+</task-result>
+```
+
+---
+
+## § 7. PLAN.md 필수 메타 정보 — 7개 필드
+
+→ `{REFERENCES_DIR}/file-content-schema.md` § 1 참조
+
+| 필드 | 필수 | 설명 |
+|------|------|------|
+| `> Created:` | ✅ | YYYY-MM-DD |
+| `> Requirement:` | ✅ | `REQ-XXX` 또는 사용자 요청 텍스트 |
+| `> Execution-Mode:` | ✅ | `direct` / `pipeline` / `full` |
+| `> Project:` | ✅ | 프로젝트 이름 |
+| `> Tech Stack:` | ✅ | 감지된 기술 스택 |
+| `> Language:` | ✅ | 언어 코드 (`ko`, `en` 등) |
+| `> Status:` | ✅ | 항상 `PLANNED`로 시작 |
+
+---
+
+## § 8. WORK-LIST.md 업데이트 규칙
+
+파일: `works/WORK-LIST.md`
+
+**형식:**
+```
+LAST_WORK_ID: WORK-XX
+
+| WORK | 제목 | 상태 | 생성일 | 완료일 |
+|------|------|------|--------|--------|
+| WORK-NN | ... | IN_PROGRESS | YYYY-MM-DD | |
+| WORK-MM | ... | DONE | YYYY-MM-DD | YYYY-MM-DD |
+```
+
+| 상태 | 의미 | 트리거 |
+|------|------|--------|
+| `IN_PROGRESS` | WORK 실행 중 | specifier가 WORK 생성 |
+| `DONE` | 모든 TASK 완료, 리뷰/push 대기 | committer가 마지막 TASK 완료 |
+| `COMPLETED` | _COMPLETED/로 아카이빙됨 | push 머지 (Main Claude가 모든 DONE 일괄 처리) |
+
+규칙:
+- `LAST_WORK_ID` 헤더는 지금까지 생성된 가장 높은 WORK ID를 추적
+- **specifier**: WORK 생성 시 IN_PROGRESS 행 추가 + `LAST_WORK_ID` 업데이트
+- **committer**: 마지막 TASK 완료 시 `IN_PROGRESS` → `DONE`으로 변경하고 완료일 기입 (폴더 이동이나 행 제거 금지)
+- **Main Claude** (push 절차): 모든 DONE WORK를 `works/_COMPLETED/`로 이동, WORK-LIST.md에서 해당 행 제거
+
+---
+
+## § 9. 로케일 감지
+
+```
+1. Grep 도구 사용: pattern "Language:\s*[a-z]{2}" path="CLAUDE.md" → 언어 코드 추출
+2. 없으면 사용자에게 언어 확인
+3. 없으면 Bash로 시스템 로케일 자동 감지:
+   - Windows: powershell -c "[CultureInfo]::CurrentCulture.TwoLetterISOLanguageName"
+   - Linux/Mac: locale | grep LANG
+   - 폴백: "en"
+```
+
+---
+
+## § 12. Bash 명령 규칙
+
+Bash 명령은 권한 호환성을 위해 다음 규칙을 반드시 따라야 합니다.
+
+**필수:**
+- Bash 호출당 단순 명령 하나 — 복합 명령 금지 (`&&`, `||`, `;`, `|`)
+- `cd` 금지 — Bash 도구의 cwd는 항상 프로젝트 루트. `cd dir &&`, `cd dir ;`, `cd dir` 어떤 형태든 사용 금지. 프로젝트 루트 기준 상대 경로 사용
+- 멀티라인 스크립트 금지 — 별도 Bash 호출로 분할
+- 인수 내 서브셸 확장 금지 — 예: `printf` 안의 `$(date ...)`
+- 프로젝트 루트 기준 상대 경로 사용 (예: `works/WORK-01/`) — 절대 경로 금지
+- `git add file`, `git commit -m "msg"` 사용 — `git -C path` 플래그 금지
+
+**파일 작업에는 Bash 대신 전용 도구를 우선 사용:**
+- 파일 읽기 → `Read` 도구 (`cat` 아님)
+- 파일 쓰기/추가 → `Write` 도구 (`echo >>` 또는 `printf >>` 아님)
+- 파일 편집 → `Edit` 도구 (`sed -i` 아님)
+- 파일 검색 → `Grep` 도구 (`grep` 아님)
+- 파일 찾기 → `Glob` 도구 (`find` 아님)
+
+**Git 예시:**
+```
+잘못됨: cd /path/to/project && git add file && git commit -m "msg"
+올바름: git add file        (한 번의 호출)
+       git commit -m "msg"  (다음 호출)
+```
+
+---
+
+## Version
+
+- Created: 2026-03-10
+- Updated: 2026-03-31

package/references/work-activity-log.md

@@ -0,0 +1,26 @@
+# 작업 활동 로그
+
+`works/{WORK_ID}/work_{WORK_ID}.log`에 에이전트 시작/종료 이벤트를 기록.
+
+## 규칙
+
+1. **타임스탬프**: Bash로 `date -u +"%Y-%m-%dT%H:%M:%SZ"` 실행하여 실제 UTC 시간 획득. 더미 값 사용 금지.
+2. **기록 방법**: Bash `echo` 로 추가. 
+3. **항목**: 에이전트 역할별 START와 DONE만. 중간 단계 없음.
+
+## 형식
+
+```
+[YYYY-MM-DDTHH:MM:SSZ] AGENT_EVENT — description
+```
+
+## 필수 항목
+
+| 에이전트 | 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` |

package/references/xml-schema.md

@@ -0,0 +1,120 @@
+# 에이전트 통신 XML 스키마
+
+uc-taskmanager 에이전트용 XML 통신 형식 정의.
+
+---
+
+## 1. Dispatch 형식 (디스패처 → 수신자)
+
+```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>
+  </ref-cache>
+  <references-dir>{references 디렉토리 절대 경로}</references-dir>
+  <context>
+    <project>{프로젝트 이름}</project>
+    <language>{lang_code}</language>
+    <plan-file>works/{WORK_ID}/PLAN.md</plan-file>
+  </context>
+  <task-spec>
+    <file>works/{WORK_ID}/TASK-XX.md</file>
+    <title>{제목}</title>
+    <action>{implement|verify|commit|plan|route}</action>
+    <description>{선택사항}</description>
+  </task-spec>
+  <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 |
+| `task` | `TASK-NN` — WORK 접두사 포함 금지 |
+| `execution-mode` | direct / pipeline / full (생략 시 full 기본값) |
+
+---
+
+## 2. Task Result 형식 (수신자 → 디스패처)
+
+```xml
+<task-result work="{WORK_ID}" task="{TASK_ID}" agent="{agent}" status="{PASS|FAIL}">
+  <summary>{1-2줄 요약}</summary>
+  <files-changed>
+    <file action="{created|modified|deleted}" path="{path}">{설명}</file>
+  </files-changed>
+  <verification>
+    <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>
+```
+
+---
+
+## 3. Context-Handoff 요소
+
+```xml
+<context-handoff from="{agent}" detail-level="{FULL|SUMMARY|DROP}">
+  <what>{변경/검증 상세}</what>
+  <why>{결정 근거}</why>       <!-- FULL만 -->
+  <caution>{주의사항}</caution>          <!-- FULL만 -->
+  <incomplete>{미완료 항목}</incomplete>  <!-- FULL만 -->
+</context-handoff>
+```
+
+| detail-level | 포함 필드 |
+|:---:|---|
+| `FULL` | what, why, caution, incomplete |
+| `SUMMARY` | what만 (1-3줄) |
+| `DROP` | 요소 생략 |
+
+---
+
+## 4. ref-cache 요소 정의
+
+`<ref-cache>`는 dispatch 및 task-result XML 내에서 미리 로딩된 레퍼런스 파일 내용을 전달하는 선택적 컨테이너 요소입니다. 존재할 경우, 수신 에이전트는 디스크에서 파일을 읽는 대신 반드시 이 내용을 사용해야 합니다.
+
+### 구조
+
+```xml
+<ref-cache>
+  <ref key="{확장자 없는 파일명}">{전체 파일 내용}</ref>
+  ...
+</ref-cache>
+```
+
+| 요소 | 필수 | 설명 |
+|------|------|------|
+| `<ref-cache>` | 선택 | 캐시된 레퍼런스 파일 컨테이너. 캐시가 없으면 전체 생략. |
+| `<ref key="...">` | — | 개별 레퍼런스 파일. `key`는 확장자 없는 파일명 (예: `shared-prompt-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` |
+
+### 하위 호환성
+
+- `<ref-cache>` 없는 dispatch 또는 task-result XML은 완전히 유효 — 에이전트는 `REFERENCES_DIR`에서 파일을 읽는 것으로 폴백.
+- ref-cache를 아직 지원하지 않는 에이전트는 해당 요소를 무시하고 정상적으로 파일을 읽음.
+- 부분적 ref-cache (일부 키만 존재)도 허용 — 없는 키는 디스크에서 읽음.