uctm 1.5.3 → 2.0.0

package/references/context-policy.md

@@ -1,69 +1,71 @@
-# Context Handoff Policy
+# Context Handoff 정책
 
-Sliding window context transfer rules between agents.
+에이전트 간 슬라이딩 윈도우 컨텍스트 전달 규칙.
 
-## Sliding Window
+## 슬라이딩 윈도우
 
-| Step Distance | Detail Level | Rule |
-|---------------|-------------|------|
-| Immediate (1 step) | `FULL` | All 4 fields transmitted |
-| 2 steps back | `SUMMARY` | `what` field only, 1-3 lines |
-| 3+ steps back | `DROP` | Omitted |
+| 단계 거리 | 상세 레벨 | 규칙 |
+|-----------|----------|------|
+| 직전 (1단계) | `FULL` | 4개 필드 모두 전달 |
+| 2단계 전 | `SUMMARY` | `what` 필드만, 1-3줄 |
+| 3단계+ | `DROP` | 생략 |
 
-## Context-Handoff 4 Fields
+## Context-Handoff 4개 필드
 
-| Field | FULL | SUMMARY | Content |
-|-------|:----:|:-------:|---------|
-| `what` | ✅ | ✅ | Summary of changes/verification (2-5 lines) |
-| `why` | ✅ | ❌ | Decision rationale (2-4 lines) |
-| `caution` | ✅ | ❌ | Caveats, conditional completion (1-3 lines) |
-| `incomplete` | ✅ | ❌ | Incomplete items (1-2 lines, "None" if empty) |
+| 필드 | FULL | SUMMARY | 내용 |
+|------|:----:|:-------:|------|
+| `what` | ✅ | ✅ | 변경/검증 요약 (2-5줄) |
+| `why` | ✅ | ❌ | 결정 근거 (2-4줄) |
+| `caution` | ✅ | ❌ | 주의사항, 조건부 완료 (1-3줄) |
+| `incomplete` | ✅ | ❌ | 미완료 항목 (1-2줄, 없으면 "None") |
 
-## Pipeline Stage Input/Output
+## 파이프라인 단계별 입출력
 
 ### Builder
 
-Input: TASK spec + dependent TASK result.md context-handoff (sliding window)
+입력: TASK 스펙 + 의존 TASK result.md context-handoff (슬라이딩 윈도우)
 
-Output:
+출력:
 ```xml
 <task-result status="PASS|FAIL">
   <context-handoff from="builder" detail-level="FULL">
-    <what>Changes made</what><why>Rationale</why><caution>Caveats</caution><incomplete>Incomplete items</incomplete>
+    <what>변경 내용</what><why>근거</why><caution>주의사항</caution><incomplete>미완료 항목</incomplete>
   </context-handoff>
 </task-result>
 ```
 
 ### Verifier
 
-Input: TASK spec + Builder context-handoff (FULL)
+입력: TASK 스펙 + Builder context-handoff (FULL)
 
-Output:
+출력:
 ```xml
 <task-result status="PASS|FAIL">
   <context-handoff from="verifier" detail-level="FULL">
-    <what>Verification results</what><why>Judgment rationale</why><caution>Manual checks needed</caution><incomplete>Items that could not be verified</incomplete>
+    <what>검증 결과</what><why>판단 근거</why><caution>수동 확인 필요 항목</caution><incomplete>검증할 수 없었던 항목</incomplete>
   </context-handoff>
 </task-result>
 ```
 
 ### Committer
 
-Input: Verifier context-handoff (FULL) + Builder context-handoff (SUMMARY)
+입력: Verifier context-handoff (FULL) + Builder context-handoff (SUMMARY)
 
-Processing:
-1. Verify builder completed successfully (check context-handoff status)
-2. Write result.md + git commit
+처리:
+1. builder 성공 여부 확인 (context-handoff 상태 확인)
+2. result.md 작성 + git commit
 
-Output: → `{REFERENCES_DIR}/file-content-schema.md` § 4 reference
+출력: → `{REFERENCES_DIR}/file-content-schema.md` § 3 참조
 
-## Inter-TASK Dependency Transfer
+## TASK 간 의존성 전달
 
-- Immediate dependent TASK: context-handoff **FULL** (all 4 fields)
-- 2 steps back: **SUMMARY** (what only)
-- 3+ steps back: **DROP**
+- 직전 의존 TASK: context-handoff **FULL** (4개 필드 모두)
+- 2단계 전: **SUMMARY** (what만)
+- 3단계+: **DROP**
 
-## Scheduler Dispatch
+## Orchestrator 디스패치
+
+TASK DAG 실행 중 다음 자식(중첩 spawn)의 프롬프트를 구성하는 주체는 **orchestrator**다 — dispatch XML을 만들어 자식 spawn 프롬프트에 포함한다.
 
 ```xml
 <!-- Verifier: Builder FULL -->
@@ -77,7 +79,7 @@ Output: → `{REFERENCES_DIR}/file-content-schema.md` § 4 reference
   <context-handoff from="builder" detail-level="SUMMARY"><what>...</what></context-handoff>
 </dispatch>
 
-<!-- Next TASK Builder: dependency distance applied -->
+<!-- 다음 TASK Builder: 의존성 거리 적용 -->
 <dispatch to="builder" task="TASK-YY">
   <previous-results>
     <context-handoff from="prev-task" task="TASK-XX" detail-level="FULL">...</context-handoff>
@@ -86,8 +88,8 @@ Output: → `{REFERENCES_DIR}/file-content-schema.md` § 4 reference
 </dispatch>
 ```
 
-## Committer Retry
+## Committer 재시도
 
-1. Failure cause: verification FAIL / No files changed
-2. Re-dispatch to builder
-3. Maximum 2 retries (3 attempts total). 3 failures → TASK FAILED, pipeline halted
+1. 실패 원인: 검증 FAIL / 변경 파일 없음
+2. builder에 재디스패치
+3. 최대 2회 재시도 (총 3회 시도). 3회 실패 → TASK FAILED, 파이프라인 중단

package/references/file-content-schema.md

@@ -1,27 +1,28 @@
-# File Content Schema
+# 파일 내용 스키마
 
-Single source of truth for pipeline artifact file formats.
+파이프라인 산출물 파일 형식의 단일 정의 소스.
 
-## COMPLIANCE
+## 준수사항
 
-| Generated File | Reference Section | Violation Consequence |
-|----------------|-------------------|----------------------|
-| `PLAN.md` | § 1 | `parsePlanMd()` parsing failure, scheduler inoperable |
-| `TASK-XX.md` | § 2 | `parseTaskFilename()` DB registration missed |
-| `TASK-XX_result.md` | § 3 | context-handoff missing |
-| `TASK-XX_result.md` (direct) | § 4 | result.md recognition failure |
+| 생성 파일 | 참조 섹션 | 위반 시 결과 |
+|-----------|----------|-------------|
+| `Requirement.md` | § 0 |  |
+| `PLAN.md` | § 1 | `parsePlanMd()` 파싱 실패, orchestrator 파이프라인 작동 불가 |
+| `TASK-XX.md` | § 2 | `parseTaskFilename()` DB 등록 누락 |
+| `TASK-XX_result.md` | § 3 | context-handoff 누락 |
+| `DECISIONS.md` | § 4 | 재개(resume) 시 PENDING 결정 재제시 불가 |
 
 ---
 
 ## § 0. Requirement.md
 
-Path: `works/{WORK_ID}/Requirement.md`
+경로: `works/{WORK_ID}/Requirement.md`
 
 ```markdown
 # Requirement — WORK-NN
 
 ## Original Request
-> User's exact input
+> 사용자의 정확한 입력
 
 ## Functional Requirements
 - FR-01: ...
@@ -31,100 +32,167 @@ Path: `works/{WORK_ID}/Requirement.md`
 - NFR-01: ...
 
 ## Acceptance Criteria
-- [ ] Verifiable criteria
+- [ ] 검증 가능한 기준
 ```
 
-Created by: Specifier (mandatory for all requests)
+생성 주체: Specifier (모든 요청에 필수)
 
 ---
 
 ## § 1. PLAN.md
 
-Path: `works/{WORK_ID}/PLAN.md`
+경로: `works/{WORK_ID}/PLAN.md`
+
+> 요구사항 수준에 따라 ## 설계 이하 간략화 가능
 
 ```markdown
-# WORK-01: {title}
+# WORK-01: {제목}
 
 > Created: {YYYY-MM-DD}
-> Requirement: {REQ-XXX | user request text}
-> Execution-Mode: {direct | pipeline | full}
-> Project: {project name}
-> Tech Stack: {stack}
+> Requirement: {REQ-XXX | 사용자 요청 텍스트}
+> Project: {프로젝트 이름}
+> Tech Stack: {스택}
 > Language: {lang_code}
 > Status: PLANNED
 
-## Goal
-{1-2 sentences}
+## 목표
+{1-2문장}
+
+## 설계
+
+### 1. 아키텍처 방향
+
+- **접근 방식**: 신규 구축 / 기존 수정 / 확장
+- **구조**: (계층형, 이벤트 기반, 마이크로서비스 등)
+- **데이터 흐름**: (입력 → 처리 → 출력 경로 요약)
+
+### 2. 데이터 설계
+
+| 항목 | 내용 |
+|------|------|
+| 스키마 변경 | 있음 / 없음 |
+| 마이그레이션 필요 | 있음 / 없음 |
+| 변경 내용 | |
+
+### 3. 인터페이스 설계
+
+| 인터페이스 | 방식 | 엔드포인트/형식 | 관련 FR |
+|-----------|------|---------------|--------|
+| | REST / GraphQL / gRPC / 파일 | | |
+
+### 4. NFR 대응 설계
 
-## Task Dependency Graph
-{ASCII diagram}
+| 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 | | | | | |
+
+---
 
-## Tasks
+## 추적성 매트릭스
 
-### TASK-00: {title}
-- **Depends on**: (none)
-- **Scope**: {description}
-- **Files**:
-  - `path/to/file` — {description}
+| 원본 요청 | FR/NFR | Task | 인수 기준 | 검증 방법 |
+|----------|--------|------|----------|----------|
+| | FR-01 | TASK-01 | AC-01 | 단위테스트 / 수동확인 / 자동화 |
+| | FR-02 | TASK-02 | AC-02 | |
+| | NFR-01 | TASK-02 | AC-03 | |
 
-### TASK-01: {title}
-- **Depends on**: TASK-00
+---
+
+## 자체 검증 체크리스트
+
+- [ ] 모든 FR이 최소 1개 Task에 매핑됨
+- [ ] 모든 NFR이 설계 또는 Task에 반영됨
+- [ ] Task 간 순환 의존 없음
+- [ ] 제약조건 내 실현 가능
+- [ ] 각 Task에 완료 조건이 있음
+- [ ] 리스크가 식별되고 대응 전략이 있음
+- [ ] 실행 순서가 의존관계와 일치함
+
+---
 ```
 
-Title format: `# WORK-NN: title` — `# PLAN WORK-NN:` is prohibited (`parsePlanMd()` error)
+제목 형식: `# WORK-NN: title` — `# PLAN WORK-NN:` 금지 (`parsePlanMd()` 오류)
 
 ---
 
 ## § 2. TASK-XX.md
 
-Path: `works/{WORK_ID}/TASK-XX.md`
+경로: `works/{WORK_ID}/TASK-XX.md`
 
-> `parseTaskFilename()` regex: `/^TASK-(\d+)\.md$/` — WORK prefix prohibited
+> `parseTaskFilename()` regex: `/^TASK-(\d+)\.md$/` — WORK 접두사 금지
 
 ```markdown
-# TASK-XX: {title}
+# TASK-XX: {제목}
 
 ## WORK
-{WORK_ID}: {WORK title}
+{WORK_ID}: {WORK 제목}
+
+## Task 개요
 
-## Dependencies
-- TASK-YY (required)
+| 항목 | 내용 |
+|------|------|
+| 목적 | (이 Task가 완료되면 무엇이 달라지는가) |
+| 매핑 요구사항 | FR-{NN}, NFR-{NN} |
+| 우선순위 | Must / Should / Could |
+| 예상 규모 | S / M / L |
+| 의존관계 | 없음 / TASK-{NN} 완료 후 |
+| Phase | Phase {N} |
 
 ## Scope
-{description}
+{설명}
 
 ## Files
 | Path | Action | Description |
 |------|--------|-------------|
-| `src/file.ts` | CREATE | description |
+| `src/file.ts` | CREATE | 설명 |
 
 ## Acceptance Criteria
-- [ ] {criterion}
+- [ ] {기준}
 
 ## Verify
 ```bash
-{verification commands}
-```
+{검증 명령}
 ```
 
 ---
 
-## § 3. TASK-XX_result.md (full / pipeline)
+## § 3. TASK-XX_result.md
 
-Path: `works/{WORK_ID}/TASK-XX_result.md`
+경로: `works/{WORK_ID}/TASK-XX_result.md`
 
 ```markdown
 # TASK-XX Result
 
-> WORK: {WORK_ID} — {title}
+> WORK: {WORK_ID} — {제목}
 > Completed: {YYYY-MM-DD HH:MM}
 > Status: **DONE**
 
 {## Summary | ## 요약 | ## サマリー}
-{1-2 lines}
+{1-2줄}
 
 {## Completed Checklist | ## 완료 체크리스트 | ## 完了チェックリスト}
-- [x] {item}
+- [x] {항목}
 
 {## Verification Results | ## 검증 결과 | ## 検証結果}
 - Build: ✅
@@ -133,7 +201,7 @@ Path: `works/{WORK_ID}/TASK-XX_result.md`
 
 {## Files Changed | ## 변경 파일 | ## 変更ファイル}
 ### Created
-- `path` — {description}
+- `path` — {설명}
 
 {## Issues Encountered | ## 발생 이슈 | ## 発生した問題}
 None
@@ -144,14 +212,14 @@ None
 {## Context Handoff | ## 컨텍스트 핸드오프 | ## コンテキスト引き継ぎ}
 
 ### Builder Context (SUMMARY)
-{builder what field 1-3 lines}
+{builder what 필드 1-3줄}
 
 ### Verifier Context (FULL)
-{verifier context-handoff 4 fields}
+{verifier context-handoff 4개 필드}
 ```
 
-| Section | en | ko | ja |
-|---------|----|----|-----|
+| 섹션 | en | ko | ja |
+|------|----|----|-----|
 | Summary | `## Summary` | `## 요약` | `## サマリー` |
 | Completed Checklist | `## Completed Checklist` | `## 완료 체크리스트` | `## 完了チェックリスト` |
 | Verification Results | `## Verification Results` | `## 검증 결과` | `## 検証結果` |
@@ -162,37 +230,58 @@ None
 
 ---
 
-## § 4. TASK-XX_result.md (direct mode)
+## § 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 — {title}
-> 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}
+
+### 배경
+{결정이 필요한 이유}
 
-## Summary
-{1 line}
+### 선택지
+1. {선택지 1}
+2. {선택지 2}
 
-## Files Changed
-- `{path}` — {description}
+### 권고안
+{orchestrator/자식 에이전트가 제시한 권고}
 
-## Verification
-- 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. File Naming Rules
+## § 5. 파일 이름 규칙
 
-| Type | Format | Created By |
-|------|--------|------------|
-| Requirement | `Requirement.md` | specifier |
-| WORK plan | `PLAN.md` | planner / specifier |
-| TASK plan | `TASK-NN.md` | planner / specifier |
-| TASK result | `TASK-NN_result.md` | committer |
-| Activity log | `work_WORK-NN.log` | all agents (append) |
+| 유형 | 형식 | 생성 주체 |
+|------|------|-----------|
+| 요구사항 | `Requirement.md` | specifier |
+| WORK 계획 | `PLAN.md` | planner / specifier |
+| TASK 계획 | `TASK-NN.md` | planner / specifier |
+| TASK 결과 | `TASK-NN_result.md` | committer |
+| 결정 로그 | `DECISIONS.md` | orchestrator |
+| 활동 로그 | `work_WORK-NN.log` | orchestrator (추가) |
 
-`WORK-NN-TASK-NN.md` format prohibited → `parseTaskFilename()` cannot recognize it.
+`WORK-NN-TASK-NN.md` 형식 금지 → `parseTaskFilename()`이 인식할 수 없음.

package/references/ref-cache-protocol.md

@@ -1,31 +1,31 @@
-# ref-cache Protocol
-
-## Overview
-
-ref-cache is a mechanism to avoid redundant file reads across sub-agent invocations within a pipeline.
-Reference files are passed between agents via `<ref-cache>` XML elements instead of being re-read from disk each time.
-
-## Protocol (4 Steps)
-
-1. **Check** if `<ref-cache>` exists in the received dispatch XML
-2. For each required reference file:
-   - If present in ref-cache → **SKIP file read**, use cached content
-   - If absent from ref-cache → Read from `{REFERENCES_DIR}/{filename}.md` and add to ref-cache
-3. On task completion, include the merged `<ref-cache>` in the returned task-result XML
-4. **Backward compatibility**: If dispatch contains no `<ref-cache>`, read all reference files normally (existing behavior)
-
-## ref-cache XML Format
-
-See `xml-schema.md` § 4 for the full schema.
-
-```xml
-<ref-cache>
-  <ref key="file-content-schema">...content...</ref>
-  <ref key="shared-prompt-sections">...content...</ref>
-  <!-- one <ref> per loaded reference file -->
-</ref-cache>
-```
-
-## Chain Propagation
-
-See `agent-flow.md` § ref-cache Chain Propagation for how ref-cache flows between agents in the pipeline.
+# 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 참조.