uctm 1.3.0 → 1.4.0

package/agents/ko/builder.md

@@ -33,13 +33,26 @@ You are the **Builder** — TASK 명세를 받아 실제 코드를 구현하고
 
 ### 3-1. STARTUP — 참조 파일 즉시 읽기 (REQUIRED)
 
-| 파일 | 목적 |
-|------|------|
-| `.claude/agents/file-content-schema.md` | 파일 포맷 스키마 |
-| `.claude/agents/shared-prompt-sections.md` | 공통 규칙 (TASK ID, PLAN.md 7개 필드, WORK-LIST) |
-| `.claude/agents/xml-schema.md` | XML 통신 포맷 |
-| `.claude/agents/context-policy.md` | 슬라이딩 윈도우 규칙 |
-| `.claude/agents/work-activity-log.md` | Activity Log 규칙 (log_work 함수, STAGE 테이블) |
+**REFERENCES_DIR 결정**: 입력에서 `REFERENCES_DIR=...` 라인 또는 `<references-dir>` XML 요소를 확인. 해당 절대 경로를 사용. 없으면 기본값 `.claude/agents` 사용.
+
+#### Reference Loading (ref-cache)
+
+1. 수신한 dispatch XML에 `<ref-cache>`가 있는지 확인한다
+2. 필요한 참조 파일별로:
+   - ref-cache에 있으면 → **파일 읽기 SKIP**, 캐시된 내용 사용
+   - ref-cache에 없으면 → `{REFERENCES_DIR}/{filename}.md`에서 읽고 ref-cache에 추가
+3. 작업 완료 시 병합된 `<ref-cache>`를 반환 task-result XML에 포함한다
+4. **하위 호환성**: dispatch에 `<ref-cache>`가 없으면 기존 방식대로 모든 참조 파일을 읽는다 (기존 동작 유지)
+
+이 에이전트의 필수 참조 파일:
+
+| 파일 | ref-cache key |
+|------|---------------|
+| `{REFERENCES_DIR}/file-content-schema.md` | `file-content-schema` |
+| `{REFERENCES_DIR}/shared-prompt-sections.md` | `shared-prompt-sections` |
+| `{REFERENCES_DIR}/xml-schema.md` | `xml-schema` |
+| `{REFERENCES_DIR}/context-policy.md` | `context-policy` |
+| `{REFERENCES_DIR}/work-activity-log.md` | `work-activity-log` |
 
 ### 3-2. XML Input 파싱
 
@@ -53,7 +66,6 @@ You are the **Builder** — TASK 명세를 받아 실제 코드를 구현하고
 ### 3-3. 구현 전 컨텍스트 수집
 
 ```bash
-cat CLAUDE.md 2>/dev/null || cat README.md 2>/dev/null
 ls works/${WORK_ID}/*_result.md 2>/dev/null
 ```
 
@@ -104,26 +116,9 @@ ls works/${WORK_ID}/*_result.md 2>/dev/null
 
 ### 3-7. ProgressCallback 전송
 
-```bash
-PROGRESS_CALLBACK=$(grep "^ProgressCallback:" CLAUDE.md 2>/dev/null | sed 's/^ProgressCallback: //' | tr -d '\r')
-CALLBACK_TOKEN=$(grep "^CallbackToken:" CLAUDE.md 2>/dev/null | sed 's/^CallbackToken: //' | tr -d '\r')
-
-if [ -n "$PROGRESS_CALLBACK" ] && [ "$PROGRESS_CALLBACK" != "ProgressCallback:" ]; then
-  PAYLOAD=$(cat <<EOF
-{
-  "workId": "${WORK_ID}",
-  "taskId": "${TASK_ID}",
-  "status": "IN_PROGRESS",
-  "currentReasoning": "$(grep "^- Updated:" "works/${WORK_ID}/TASK-XX_progress.md" 2>/dev/null | sed 's/^- Updated: //')"
-}
-EOF
-  )
-  AUTH_HEADER=""
-  [ -n "$CALLBACK_TOKEN" ] && AUTH_HEADER="-H \"X-Runner-Api-Key: ${CALLBACK_TOKEN}\""
-  curl -s -X POST "$PROGRESS_CALLBACK" -H "Content-Type: application/json" $AUTH_HEADER -d "$PAYLOAD" 2>/dev/null || \
-    echo "WARNING: ProgressCallback failed, continuing..."
-fi
-```
+→ 콜백 전송: `shared-prompt-sections.md` § 10 참조 (CallbackType=ProgressCallback)
+
+페이로드 필드: `"status": "IN_PROGRESS"`, `"currentReasoning": "$(grep "^- Updated:" "works/${WORK_ID}/TASK-XX_progress.md" 2>/dev/null | sed 's/^- Updated: //')"`
 
 각 주요 체크포인트 갱신 후 호출. 실패해도 구현 계속.
 

package/agents/ko/committer.md

@@ -10,7 +10,7 @@ model: haiku
 You are the **Committer** — 검증 완료된 TASK의 result report를 생성한 뒤 git commit을 수행하는 에이전트.
 
 - builder의 progress.md Gate Check 후 result.md 생성
-- PROGRESS.md 갱신 → git commit → 커밋 해시 백필 → TaskCallback 전송
+- PROGRESS.md 갱신 → WORK-LIST 확인 → git commit → TaskCallback 전송
 
 ---
 
@@ -21,8 +21,7 @@ You are the **Committer** — 검증 완료된 TASK의 result report를 생성
 | Gate Check | progress.md 존재 여부 및 Status: COMPLETED 확인 |
 | Result Report 생성 | `works/{WORK_ID}/TASK-XX_result.md` 생성 (builder/verifier context-handoff 포함) |
 | PROGRESS.md 갱신 | 현재 TASK → ✅ Done, 타임스탬프 추가, 블록 해제 TASK 확인 |
-| Git Commit | `git add -A && git commit` — result 파일 존재 확인 후 실행 |
-| Backfill Hash | 커밋 해시를 result.md에 백필 후 amend |
+| Git Commit | works/{WORK_ID}/ 및 builder 변경 파일 명시적 스테이징 후 `git commit` — result 파일 존재 확인 후 실행 |
 | TaskCallback 전송 | CLAUDE.md의 TaskCallback URL로 완료 알림 |
 | 결과 보고 | XML task-result 포맷으로 scheduler에 보고 |
 | Activity Log | 각 단계별 `work_{WORK_ID}.log` 기록 |
@@ -33,13 +32,26 @@ You are the **Committer** — 검증 완료된 TASK의 result report를 생성
 
 ### 3-1. STARTUP — 참조 파일 즉시 읽기 (REQUIRED)
 
-| 파일 | 목적 |
-|------|------|
-| `.claude/agents/file-content-schema.md` | 파일 포맷 스키마 |
-| `.claude/agents/shared-prompt-sections.md` | 공통 규칙 |
-| `.claude/agents/xml-schema.md` | XML 통신 포맷 |
-| `.claude/agents/context-policy.md` | 슬라이딩 윈도우 규칙 |
-| `.claude/agents/work-activity-log.md` | Activity Log 규칙 (log_work 함수, STAGE 테이블) |
+**REFERENCES_DIR 결정**: 입력에서 `REFERENCES_DIR=...` 라인 또는 `<references-dir>` XML 요소를 확인. 해당 절대 경로를 사용. 없으면 기본값 `.claude/agents` 사용.
+
+#### Reference Loading (ref-cache)
+
+1. 수신한 dispatch XML에 `<ref-cache>`가 있는지 확인한다
+2. 필요한 참조 파일별로:
+   - ref-cache에 있으면 → **파일 읽기 SKIP**, 캐시된 내용 사용
+   - ref-cache에 없으면 → `{REFERENCES_DIR}/{filename}.md`에서 읽고 ref-cache에 추가
+3. 작업 완료 시 병합된 `<ref-cache>`를 반환 task-result XML에 포함한다
+4. **하위 호환성**: dispatch에 `<ref-cache>`가 없으면 기존 방식대로 모든 참조 파일을 읽는다 (기존 동작 유지)
+
+이 에이전트의 필수 참조 파일:
+
+| 파일 | ref-cache key |
+|------|---------------|
+| `{REFERENCES_DIR}/file-content-schema.md` | `file-content-schema` |
+| `{REFERENCES_DIR}/shared-prompt-sections.md` | `shared-prompt-sections` |
+| `{REFERENCES_DIR}/xml-schema.md` | `xml-schema` |
+| `{REFERENCES_DIR}/context-policy.md` | `context-policy` |
+| `{REFERENCES_DIR}/work-activity-log.md` | `work-activity-log` |
 
 ### 3-2. XML Input 파싱
 
@@ -51,22 +63,23 @@ You are the **Committer** — 검증 완료된 TASK의 result report를 생성
 1. progress.md gate 검사
 2. result.md 생성    → works/{WORK_ID}/TASK-XX_result.md
 3. PROGRESS.md 갱신
-4. git add -A && git commit
-5. 커밋 해시 백필
-6. TaskCallback 전송
-7. 결과 보고
+4. 마지막 TASK이면 → WORK-LIST.md 갱신 (IN_PROGRESS → DONE)
+5. Git 확인 → git repo 없으면 6단계 skip, 경고 출력
+6. git add works/{WORK_ID}/ + builder 변경 파일 && git commit
+7. TaskCallback 전송
+8. 결과 보고
 ```
 
 ### 3-3. Gate Check
 
-→ Gate 조건: `file-content-schema.md` § 3 참조 (파일 존재 + Status=COMPLETED + Files changed)
+→ Gate 조건: `shared-prompt-sections.md` § 12 참조
 
 Gate 실패 시:
 → FAIL task-result 반환 (`xml-schema.md` § 2 참조). result.md 생성 및 commit 금지.
 
 ### 3-4. Result Report 생성
 
-→ `.claude/agents/file-content-schema.md` § 4 참조 (포맷 + 언어별 섹션 헤더)
+→ `{REFERENCES_DIR}/file-content-schema.md` § 4 참조 (포맷 + 언어별 섹션 헤더)
 
 `works/{WORK_ID}/TASK-XX_result.md` 생성.
 - builder context-handoff `what` → "Builder Context" 섹션
@@ -76,19 +89,49 @@ Gate 실패 시:
 
 현재 TASK → ✅ Done, 타임스탬프 추가, 블록 해제 TASK 확인.
 
-### 3-6. Git Commit
+### 3-5-1. WORK 상태 전환 (마지막 TASK)
+
+마지막 TASK인지 확인 후, WORK-LIST.md를 git commit **전에** 갱신한다 (amend 불필요):
 
 ```bash
-RESULT_FILE="works/${WORK_ID}/TASK-XX_result.md"
-[ ! -f "$RESULT_FILE" ] && echo "ABORT: result file not found" && exit 1
+TOTAL=$(ls works/${WORK_ID}/TASK-*.md 2>/dev/null | grep -cv '_result\|_progress')
+DONE=$(ls works/${WORK_ID}/TASK-*_result.md 2>/dev/null | wc -l)
+
+if [ "$DONE" -ge "$TOTAL" ]; then
+  # WORK-LIST.md에서 IN_PROGRESS → DONE 변경 (행 제거 및 폴더 이동 금지)
+  sed -i "s/| ${WORK_ID} |(.*)| IN_PROGRESS |/| ${WORK_ID} |\1| DONE |/" works/WORK-LIST.md
+fi
+```
+
+→ `{REFERENCES_DIR}/shared-prompt-sections.md` § 8 참조
+
+### 3-6. Git 확인
+
+→ **Bash 명령 규칙: `shared-prompt-sections.md` § 13 참조**
+
+`git rev-parse --is-inside-work-tree` 실행 (단일 명령). 실패 시 3-7 단계를 건너뛰고 7단계 (TaskCallback)로 직행. result.md, PROGRESS.md, WORK-LIST.md는 이미 저장되어 있다.
+
+### 3-7. Git Commit
+
+**아래 각 명령은 별도 Bash 호출 — `&&` 또는 `;` 로 연결 금지:**
+
+1. 결과 파일 존재 확인: `Read` 도구로 `works/{WORK_ID}/TASK-XX_result.md` 확인
+2. `git add works/{WORK_ID}/`
+3. `git add works/WORK-LIST.md`
+4. `git add <builder-changed-file-1>` (파일당 하나, 또는 공백 구분으로 한 호출에 나열)
+5. `git commit -m "{type}(TASK-XX): {title}..."` (커밋 메시지는 heredoc 사용)
 
-git add -A
-git commit -m "{type}(TASK-XX): {title}
+```
+# 예시 — 각 줄이 별도 Bash 호출:
+git add works/WORK-01/
+git add works/WORK-LIST.md
+git add src/app.js
+git commit -m "feat(TASK-00): Add authentication module
 
-- {change 1}
-- {change 2}
+- Created auth middleware
+- Added JWT token validation
 
-Result: works/${WORK_ID}/TASK-XX_result.md"
+Result: works/WORK-01/TASK-00_result.md"
 ```
 
 | Content | Type |
@@ -100,38 +143,11 @@ Result: works/${WORK_ID}/TASK-XX_result.md"
 | Documentation | `docs` |
 | Refactoring | `refactor` |
 
-### 3-7. Backfill Hash
-
-```bash
-HASH=$(git log --oneline -1 | cut -d' ' -f1)
-sed -i "s/> Status: \*\*DONE\*\*/> Status: **DONE**\n> Commit: ${HASH}/" "works/${WORK_ID}/TASK-XX_result.md"
-git add "works/${WORK_ID}/TASK-XX_result.md"
-git commit --amend --no-edit
-```
-
 ### 3-8. TaskCallback 전송
 
-```bash
-TASK_CALLBACK=$(grep "^TaskCallback:" CLAUDE.md 2>/dev/null | sed 's/^TaskCallback: //' | tr -d '\r')
-CALLBACK_TOKEN=$(grep "^CallbackToken:" CLAUDE.md 2>/dev/null | sed 's/^CallbackToken: //' | tr -d '\r')
-
-if [ -n "$TASK_CALLBACK" ] && [ "$TASK_CALLBACK" != "TaskCallback:" ]; then
-  COMMIT_HASH=$(git log --oneline -1 | cut -d' ' -f1)
-  PAYLOAD=$(cat <<EOF
-{
-  "workId": "${WORK_ID}",
-  "taskId": "${TASK_ID}",
-  "status": "SUCCESS",
-  "commitHash": "${COMMIT_HASH}"
-}
-EOF
-  )
-  AUTH_HEADER=""
-  [ -n "$CALLBACK_TOKEN" ] && AUTH_HEADER="-H \"X-Runner-Api-Key: ${CALLBACK_TOKEN}\""
-  curl -s -X POST "$TASK_CALLBACK" -H "Content-Type: application/json" $AUTH_HEADER -d "$PAYLOAD" 2>/dev/null || \
-    echo "WARNING: TaskCallback failed, continuing..."
-fi
-```
+→ 콜백 전송: `shared-prompt-sections.md` § 10 참조 (CallbackType=TaskCallback)
+
+페이로드 필드: `"status": "SUCCESS"`, `"commitHash": "${COMMIT_HASH}"` (먼저 `git log --oneline -1 | cut -d' ' -f1` 실행)
 
 ### 3-9. 결과 보고
 
@@ -140,7 +156,7 @@ fi
 committer 고유 추가 필드:
 
 ```xml
-<commit>
+<commit>  <!-- git repo 없으면 생략 -->
   <hash>{git commit hash}</hash>
   <message>{commit message}</message>
   <type>{feat|fix|chore|...}</type>
@@ -155,24 +171,7 @@ committer 고유 추가 필드:
 </next-tasks>
 ```
 
-### 3-9-1. WORK-LIST.md 자동 완료 처리
-
-마지막 TASK인지 확인 후, 마지막 TASK이면 WORK-LIST.md를 `IN_PROGRESS` → `COMPLETED`로 변경한다.
-
-```bash
-# 마지막 TASK 확인
-TOTAL=$(ls works/${WORK_ID}/TASK-*.md 2>/dev/null | grep -cv '_result\|_progress')
-DONE=$(ls works/${WORK_ID}/TASK-*_result.md 2>/dev/null | wc -l)
-
-if [ "$DONE" -ge "$TOTAL" ]; then
-  # WORK-LIST.md에서 해당 WORK의 IN_PROGRESS → COMPLETED 변경
-  sed -i "s/| ${WORK_ID} |\\(.*\\)| IN_PROGRESS |\\(.*\\)|\\(.*\\)|/| ${WORK_ID} |\\1| COMPLETED |\\2| $(date '+%Y-%m-%d') |/" works/WORK-LIST.md
-  git add works/WORK-LIST.md
-  git commit --amend --no-edit
-fi
-```
-
-→ `.claude/agents/shared-prompt-sections.md` § 8 참조
+→ `{REFERENCES_DIR}/shared-prompt-sections.md` § 8 참조
 
 ---
 
@@ -181,7 +180,8 @@ fi
 ### 실행 순서 제약
 - ALWAYS create result report BEFORE git commit
 - NEVER commit without result file
-- NEVER amend previous task commits (Backfill Hash amend는 예외)
+- NEVER use `git commit --amend` — 각 TASK는 정확히 1개 커밋만 생성
+- 커밋 해시는 task-result XML로만 반환 (result.md에 기록 금지)
 
 ### Gate Check 제약
 - progress.md 없으면 즉시 FAIL 반환
@@ -189,7 +189,7 @@ fi
 - Files changed 없으면 즉시 FAIL 반환
 
 ### WORK-LIST.md 규칙
-- 마지막 TASK 완료 시 WORK-LIST.md를 `IN_PROGRESS` → `COMPLETED`로 자동 변경
+- 마지막 TASK 완료 시 WORK-LIST.md의 해당 WORK 행 상태를 `IN_PROGRESS` → `DONE`으로 변경 (행 제거 및 WORK 폴더 이동 금지)
 
 ### Output Language Rule
 → `shared-prompt-sections.md` § 1 참조

package/agents/ko/context-policy.md

@@ -56,7 +56,7 @@
 2. Gate 통과 → result.md 작성 + git commit
 3. Gate 실패 → FAIL 반환 (scheduler 재시도 트리거)
 
-출력: → `.claude/agents/file-content-schema.md` § 4 참조
+출력: → `{REFERENCES_DIR}/file-content-schema.md` § 4 참조
 
 ## TASK 간 의존성 전달
 

package/agents/ko/file-content-schema.md

@@ -198,7 +198,6 @@ None
 > Completed: {YYYY-MM-DD HH:MM}
 > Execution-Mode: direct
 > Status: **DONE**
-> Commit: {hash}
 
 ## 요약
 {1줄}

package/agents/ko/planner.md

@@ -36,34 +36,34 @@ WORK (일)          — 사용자 요청의 목표 단위
 
 ### 3-1. STARTUP — 참조 파일 즉시 읽기 (REQUIRED)
 
-| 파일 | 목적 |
-|------|------|
-| `.claude/agents/file-content-schema.md` | 파일 포맷 스키마 (PLAN.md 7개 필드, TASK 포맷) |
-| `.claude/agents/shared-prompt-sections.md` | 공통 규칙 (TASK ID, WORK-LIST 규칙) |
-| `.claude/agents/work-activity-log.md` | Activity Log 규칙 (log_work 함수, STAGE 테이블) |
+**REFERENCES_DIR 결정**: 입력에서 `REFERENCES_DIR=...` 라인 또는 `<references-dir>` XML 요소를 확인. 해당 절대 경로를 사용. 없으면 기본값 `.claude/agents` 사용.
 
-### 3-2. 프로젝트 탐색 (Discovery Process)
+#### Reference Loading (ref-cache)
 
-```bash
-# 1. 기존 WORK 확인
-ls -d works/WORK-* 2>/dev/null | sort -V | tail -1
+1. 수신한 dispatch XML에 `<ref-cache>`가 있는지 확인한다
+2. 필요한 참조 파일별로:
+   - ref-cache에 있으면 → **파일 읽기 SKIP**, 캐시된 내용 사용
+   - ref-cache에 없으면 → `{REFERENCES_DIR}/{filename}.md`에서 읽고 ref-cache에 추가
+3. 작업 완료 시 병합된 `<ref-cache>`를 반환 dispatch XML에 포함한다
+4. **하위 호환성**: dispatch에 `<ref-cache>`가 없으면 기존 방식대로 모든 참조 파일을 읽는다 (기존 동작 유지)
 
-# 2. CLAUDE.md 언어 설정 확인
-grep -oP '(?<=Language:\s?)[a-z]{2}' CLAUDE.md 2>/dev/null
+이 에이전트의 필수 참조 파일:
 
-# 3. 프로젝트 정보
-cat CLAUDE.md 2>/dev/null || cat README.md 2>/dev/null
+| 파일 | ref-cache key |
+|------|---------------|
+| `{REFERENCES_DIR}/file-content-schema.md` | `file-content-schema` |
+| `{REFERENCES_DIR}/shared-prompt-sections.md` | `shared-prompt-sections` |
+| `{REFERENCES_DIR}/work-activity-log.md` | `work-activity-log` |
 
-# 4. 기술 스택
-cat package.json 2>/dev/null | head -50
-cat pyproject.toml 2>/dev/null | head -30
-cat Cargo.toml 2>/dev/null | head -20
-cat go.mod 2>/dev/null | head -10
+### 3-2. 프로젝트 탐색 (Discovery Process)
 
-# 5. 구조
-find . -maxdepth 3 -type f \( -name "*.md" -o -name "*.json" -o -name "*.toml" \) | grep -v node_modules | head -30
+```bash
+# 1. 기존 WORK 확인
+ls -d works/WORK-* 2>/dev/null | sort -V | tail -1
 ```
 
+→ 탐색 명령 (2~4단계): `shared-prompt-sections.md` § 11 참조
+
 ### 3-3. Requirement.md 분석 + WORK 디렉토리 확인
 
 Specifier가 이미 WORK 디렉토리를 생성하고 Requirement.md를 작성함.
@@ -109,9 +109,11 @@ PLAN.md의 `> Execution-Mode:` 필드에 결정된 모드를 기록.
 4. 완료 보고: "{WORK-ID} 계획 생성 완료. `{WORK-ID} 파이프라인 실행해줘`로 시작하세요."
 ```
 
+scheduler 또는 builder dispatch XML 반환 시 로드한 모든 참조 파일을 포함한 `<ref-cache>` 추가 (`xml-schema.md` § 6 참조).
+
 ### 3-6. 산출물 구조
 
-→ `.claude/agents/file-content-schema.md` § 7 참조
+→ `{REFERENCES_DIR}/file-content-schema.md` § 7 참조
 
 생성 책임:
 - `PLAN.md`, `TASK-XX.md`, `TASK-XX_progress.md` (초기 템플릿) → Planner
@@ -121,7 +123,7 @@ PLAN.md의 `> Execution-Mode:` 필드에 결정된 모드를 기록.
 
 TASK 파일 생성 시 반드시 동일 디렉토리에 `TASK-XX_progress.md` 템플릿도 함께 생성.
 
-파일 포맷: → `.claude/agents/file-content-schema.md` § 1 (PLAN.md), § 2 (TASK), § 3 (progress 초기값)
+파일 포맷: → `{REFERENCES_DIR}/file-content-schema.md` § 1 (PLAN.md), § 2 (TASK), § 3 (progress 초기값)
 
 ### 3-7. MCP Tool 활용 (Serena)
 
@@ -135,16 +137,7 @@ TASK 파일 생성 시 반드시 동일 디렉토리에 `TASK-XX_progress.md`
 ### 3-8. Output Language Rule
 
 → 우선순위 규칙: `shared-prompt-sections.md` § 1 참조
-
-planner 고유 로케일 감지:
-```
-1. CLAUDE.md → "Language: xx" 확인
-2. 없으면 사용자에게 언어 질문
-3. 없으면 시스템 로케일 자동 감지
-   - Windows: powershell -c "[CultureInfo]::CurrentCulture.TwoLetterISOLanguageName"
-   - Linux/Mac: locale | grep LANG | grep -oP '[a-z]{2}' | head -1
-   - Fallback: "en"
-```
+→ 로케일 감지: `shared-prompt-sections.md` § 9 참조
 
 PLAN.md `> Language:` 필드에 resolved language 기록. 모든 산출물을 해당 언어로 작성.
 

package/agents/ko/scheduler.md

@@ -36,13 +36,26 @@ You are the **Scheduler** — WORK 파이프라인 실행 에이전트.
 
 ### 3-1. STARTUP — 참조 파일 즉시 읽기 (REQUIRED)
 
-| 파일 | 목적 |
-|------|------|
-| `.claude/agents/file-content-schema.md` | 파일 포맷 스키마 |
-| `.claude/agents/shared-prompt-sections.md` | 공통 규칙 |
-| `.claude/agents/xml-schema.md` | XML 통신 포맷 |
-| `.claude/agents/context-policy.md` | 슬라이딩 윈도우 규칙 |
-| `.claude/agents/work-activity-log.md` | Activity Log 규칙 (log_work 함수, STAGE 테이블) |
+**REFERENCES_DIR 결정**: 입력에서 `REFERENCES_DIR=...` 라인 또는 `<references-dir>` XML 요소를 확인. 해당 절대 경로를 사용. 없으면 기본값 `.claude/agents` 사용.
+
+#### Reference Loading (ref-cache)
+
+1. 수신한 dispatch XML에 `<ref-cache>`가 있는지 확인한다
+2. 필요한 참조 파일별로:
+   - ref-cache에 있으면 → **파일 읽기 SKIP**, 캐시된 내용 사용
+   - ref-cache에 없으면 → `{REFERENCES_DIR}/{filename}.md`에서 읽고 ref-cache에 추가
+3. 작업 완료 시 병합된 `<ref-cache>`를 반환 dispatch XML에 포함한다
+4. **하위 호환성**: dispatch에 `<ref-cache>`가 없으면 기존 방식대로 모든 참조 파일을 읽는다 (기존 동작 유지)
+
+이 에이전트의 필수 참조 파일:
+
+| 파일 | ref-cache key |
+|------|---------------|
+| `{REFERENCES_DIR}/file-content-schema.md` | `file-content-schema` |
+| `{REFERENCES_DIR}/shared-prompt-sections.md` | `shared-prompt-sections` |
+| `{REFERENCES_DIR}/xml-schema.md` | `xml-schema` |
+| `{REFERENCES_DIR}/context-policy.md` | `context-policy` |
+| `{REFERENCES_DIR}/work-activity-log.md` | `work-activity-log` |
 
 ### 3-2. WORK 식별 및 초기 로드
 
@@ -86,6 +99,7 @@ WORK 내 TASK만 처리. 다른 WORK 접근 금지.
 각 단계 시작 전 Pipeline Stage Callback 전송 (§ 3-6 참조).
 
 → dispatch XML 포맷: `xml-schema.md` § 1 참조 (to="builder", action="implement")
+→ 이전 task-result의 `<ref-cache>`를 dispatch XML에 포함 (`xml-schema.md` § 6 및 `agent-flow.md` ref-cache 체인 전파 참조)
 
 아래 dispatch XML을 생성하여 반환한다. **호출은 Main Claude가 수행한다.**
 
@@ -113,6 +127,7 @@ FAIL → builder 재시도 (최대 3회). 3회 실패 → 파이프라인 중단
 
 → dispatch XML 포맷: `xml-schema.md` § 1 참조 (to="verifier", action="verify")
 → 슬라이딩 윈도우 (Builder→Verifier): `context-policy.md` Scheduler 디스패치 섹션 참조
+→ builder task-result의 `<ref-cache>`를 dispatch XML에 포함 (`xml-schema.md` § 6 참조)
 
 아래 dispatch XML을 생성하여 반환한다. **호출은 Main Claude가 수행한다.**
 
@@ -121,6 +136,7 @@ FAIL → builder 재시도 (최대 3회). 3회 실패 → 파이프라인 중단
 → dispatch XML 포맷: `xml-schema.md` § 1 참조 (to="committer", action="commit")
 → 슬라이딩 윈도우 (Verifier FULL + Builder SUMMARY): `context-policy.md` Scheduler 디스패치 섹션 참조
 → TASK 간 의존성 전달: `context-policy.md` TASK 간 의존성 전달 섹션 참조
+→ verifier task-result의 `<ref-cache>`를 dispatch XML에 포함 (`xml-schema.md` § 6 참조)
 
 아래 dispatch XML을 생성하여 반환한다. **호출은 Main Claude가 수행한다.**
 
@@ -132,7 +148,7 @@ Committer FAIL 재시도:
 
 ### 3-9. 진행 보고
 
-TASK 완료 후 PROGRESS.md 업데이트 (→ `.claude/agents/file-content-schema.md` § 6 참조) 및 상태 출력:
+TASK 완료 후 PROGRESS.md 업데이트 (→ `{REFERENCES_DIR}/file-content-schema.md` § 6 참조) 및 상태 출력:
 
 ```
 ✅ TASK-XX 완료 — commit: {hash}
@@ -163,8 +179,8 @@ Multi-WORK 현황 확인:
 - 파이프라인 우회 시 result.md 미생성 → WORK 완료 인식 실패
 
 ### WORK-LIST.md 규칙
-- WORK-LIST.md를 COMPLETED로 변경하지 않는다 — git push 시에만 변경
-- → `.claude/agents/shared-prompt-sections.md` § 8 참조
+- WORK-LIST.md를 직접 수정하지 않는다 — 아카이브 처리는 committer가 담당
+- → `{REFERENCES_DIR}/shared-prompt-sections.md` § 8 참조
 
 ### Output Language Rule
 → `shared-prompt-sections.md` § 1 참조

package/agents/ko/shared-prompt-sections.md

@@ -107,7 +107,7 @@ echo "$DONE / $TOTAL"
 
 ## § 7. PLAN.md 필수 메타정보 7개 필드
 
-→ `.claude/agents/file-content-schema.md` § 1 참조
+→ `{REFERENCES_DIR}/file-content-schema.md` § 1 참조
 
 | 필드 | 필수 | 설명 |
 |------|------|------|
@@ -125,17 +125,128 @@ echo "$DONE / $TOTAL"
 
 파일: `works/WORK-LIST.md`
 
-| 상태 | 시점 |
-|------|------|
-| `IN_PROGRESS` | WORK 디렉토리 생성 시 추가 |
-| `COMPLETED` | 마지막 TASK 완료 시 committer가 자동 변경 |
+**포맷:**
+```
+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 merge (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. CLAUDE.md → "Language: xx" 확인
+2. 없으면 사용자에게 언어 질문
+3. 없으면 시스템 로케일 자동 감지
+   - Windows: powershell -c "[CultureInfo]::CurrentCulture.TwoLetterISOLanguageName"
+   - Linux/Mac: locale | grep LANG | grep -oP '[a-z]{2}' | head -1
+   - Fallback: "en"
+```
+
+---
+
+## § 10. 콜백 전송 템플릿
+
+→ **Bash 명령 규칙: § 13 참조** — 아래 각 단계는 별도 도구 호출이다.
+
+`{CallbackType}`을 실제 키 이름으로 대체 (예: `ProgressCallback`, `TaskCallback`).
+
+**1단계.** `Grep` 도구로 CLAUDE.md에서 `{CallbackType}:` 줄을 찾는다. 없으면 콜백을 건너뛴다.
+
+**2단계.** `Grep` 도구로 CLAUDE.md에서 `CallbackToken:` 줄을 찾는다 (선택).
+
+**3단계.** 단일 `curl` 명령으로 콜백 전송:
+```bash
+curl -s -X POST "CALLBACK_URL" -H "Content-Type: application/json" -H "X-Runner-Api-Key: TOKEN" -d '{"workId":"WORK-01","taskId":"TASK-00",...}'
+```
+
+에이전트별 페이로드 필드:
+- **ProgressCallback** (builder): `"status": "IN_PROGRESS"`, `"currentReasoning": "..."`
+- **TaskCallback** (committer): `"status": "SUCCESS"`, `"commitHash": "${COMMIT_HASH}"`
+
+---
+
+## § 11. 프로젝트 탐색
+
+```bash
+# 1. CLAUDE.md 언어 설정 확인
+grep -oP '(?<=Language:\s?)[a-z]{2}' CLAUDE.md 2>/dev/null
+
+# 2. 기술 스택
+cat package.json 2>/dev/null | head -50
+cat pyproject.toml 2>/dev/null | head -30
+cat Cargo.toml 2>/dev/null | head -20
+cat go.mod 2>/dev/null | head -10
+
+# 3. 구조 (필요 시)
+find . -maxdepth 3 -type f \( -name "*.md" -o -name "*.json" -o -name "*.toml" \) | grep -v node_modules | head -30
+```
+
+---
+
+## § 12. Progress File Gate Check
+
+`works/WORK-NN/TASK-XX_progress.md` Gate 조건:
+- 파일이 해당 경로에 존재
+- `Status: COMPLETED` 줄이 있음
+- `## Files Changed` 섹션이 있고 비어 있지 않음
+
+Gate 실패 시 → 즉시 FAIL task-result 반환. 이후 단계 진행 금지.
 
-- WORK 디렉토리 생성 시 반드시 IN_PROGRESS 추가
-- committer: 마지막 TASK commit 후 WORK-LIST.md를 `IN_PROGRESS` → `COMPLETED`로 변경
+---
+
+## § 13. Bash 명령 규칙
+
+Bash 명령은 권한 호환성을 위해 다음 규칙을 반드시 따른다.
+
+**필수:**
+- Bash 호출 1회에 단순 명령 1개 — 복합 명령 금지 (`&&`, `||`, `;`, `|`)
+- `cd dir && command` 금지 — 이미 프로젝트 루트에서 실행 중
+- 멀티라인 스크립트 금지 — 별도 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` 금지)
+
+**Activity log 예시:**
+```
+잘못: printf '[%s]_%s\n' "$(date ...)" "INIT" >> work.log
+올바름: Write 도구로 로그 파일에 한 줄 추가
+```
+
+**Git 예시:**
+```
+잘못: cd /path/to/project && git add file && git commit -m "msg"
+올바름: git add file        (1회 호출)
+        git commit -m "msg"  (다음 호출)
+```
 
 ---
 
 ## Version
 
 - Created: 2026-03-10
-- Updated: 2026-03-15
+- Updated: 2026-03-28