# 데이터 전달 · 에러 핸들링 (ubisam-deliverable-rebuild)

`SKILL.md` 본문에서 분리한 상세 규약이다. 오케스트레이터가 Phase 1~3 실행 중 참조한다.

## 데이터 전달 프로토콜

| 대상 | 방식 |
|---|---|
| 진행 추적 | `docs/[Ubisam산출물]/_workspace/_progress.md` (진실원) + `TaskCreate`/`TaskUpdate`(가용 시 보조) |
| 산출물 전달 | 파일 — `docs/[Ubisam산출물]/_workspace/{phase}_{agent}_{artifact}.{ext}` (예: `01_analyst_sw점검결과.md`) |
| 실시간 조율 | `SendMessage` — `to`(이름) + `summary`(5~10단어, **필수**) + `message`. 문서가 여러 건이면 **같은 이름의 에이전트가 여러 개** 뜬다. 그때는 이름 대신 **에이전트 ID**로 지정하고, ID를 `_progress.md` 행에 기록해 둔다 |
| 결과 수집 | `Agent` 반환값 |

> 서브에이전트가 오케스트레이터(메인 대화)에 회신할 때는 `to: "main"` 이며,
> 이는 **백그라운드로 기동된 서브에이전트만** 쓸 수 있다.

## 에러 핸들링

재시도 횟수는 **`docs/[Ubisam산출물]/_workspace/_progress.md`의 `시도` 칸**에 기록한다(없으면 0회).
저장소 루트의 `_workspace/`(PTOP 하네스)와 **다른 곳이다** — 베어 경로로 쓰지 않는다.
`TaskUpdate`가 가용하면 병행 기록해도 되나 판정 근거는 파일이다.

**실패 판정 기준(관측 가능해야 한다):** ① 에이전트가 에러로 종료 ② 지정 산출 파일이 생성되지 않음
③ 산출 파일이 비었거나 헤더만 있음 — 셋 중 하나면 실패로 본다. **지연은 실패가 아니다.**
재시도는 같은 `Agent` 호출을 다시 하는 것을 뜻한다(`SendMessage`로 독촉하는 것이 아니다).

| 상황 | 처리 |
|---|---|
| **analyst** 실패 (2회) | 매핑표가 없으면 재생산 기준이 없다 → **하네스를 중단**한다. 중단 **전에** `00_rebuild_summary.md`를 "중단 — analyst 2회 실패" 1섹션만으로 먼저 작성해 흔적을 파일에 남기고, 사용자에게 보고한다. 이 경우만 "진행" 규칙의 예외다 |
| **producer/qa** 실패 | 1회 재시도. 재실패 시 해당 문서만 건너뛰고 나머지를 계속 진행, **보고서에 누락을 명시** |
| **산출물** 파일 잠금 | 작업 사본으로 진행, "산출물 미갱신" 표시 후 사용자에게 파일 닫기 요청. (입력 원본은 읽기 전용이므로 애초에 쓰지 않는다) |
| 에이전트 타입 미등록 | Phase 0 가드에서 중단 → "세션 재시작 필요" 보고 |
| 슬롯 전용 xlsx 스크립트 부재 | producer가 `xlsxfill.py` 기반으로 신규 작성 (`ubisam-producer.md` 참조). 수작업 셀 편집은 금지 |
| 데이터 상충 | 삭제하지 않고 출처를 병기 |
| 결함 2회 재작업 후 잔존 | "미해결" 확정, 사용자 판단 항목으로 상신 |

> 표의 행을 늘리거나 줄이면 `SKILL.md` 본문의 요약 3줄도 **같은 편집에서** 확인한다
> (`docs/harness-ptop.md` §소비처 확인 의무).