# SPRINT-004 — 4자매 핸드오프 엔진 + 디스코드 알림

> **목표**: F3 / F4 해결. 자매 간 통신을 상태 전이로 강제하고, 디스코드는 사용자 알림 전용으로 분리한다.

## Type
`feature`

## Prerequisites
- Sprint 001 (FSM)
- Sprint 003 (Contract)
- `.plans/design/handoff.md`, `state-machine.md` 확정
- Discord bot token / guild id (`.env`)

## Scope

- `src/handoff/message.ts` — `HandoffMessage` Zod schema
- `src/handoff/spawn.ts` — `spawnSister(opts)` — execa + AbortController + JSON 파싱 + Zod 검증
- `src/orchestrator/actors/harang.ts` — planner actor
- `src/orchestrator/actors/narang.ts` — generator actor
- `src/orchestrator/actors/darang.ts` — evaluator actor (Sprint 006 에서 QA runtime 상세 완성)
- `src/orchestrator/actors/erang.ts` — deploy actor
- `src/bridge/discord.ts` — discord.js v14 bridge (알림 전용)
- `src/bridge/events.ts` — FSM state transition → discord event mapping
- Spawn 계약 프로토콜 — OpenClaw 측에서 structured JSON 출력을 보장하는 방식 결정 (자매 system prompt 에 "반드시 JSON 형식으로 출력" 강제)
- `rails run <project>` 커맨드 — planning → implementing → reviewing → deploying → done 전체 동작
- Mock 자매 (`rails:mock` 모드) — 실제 OpenClaw 없이 로컬 테스트

## Non-Goals

- 재시도 로직 (Sprint 005)
- QA 체크리스트 실제 실행 (Sprint 006)
- 실배포 로직 (erang actor 는 mock)

## Tasks

| # | 내용 | DoD | Status |
|---|---|---|---|
| 4.1 | `HandoffMessage` discriminated union Zod schema | 4가지 actor 전부 커버 | cc:TODO |
| 4.2 | `spawnSister` — execa + timeout + structured output 파싱 | 시나리오 테스트 | cc:TODO |
| 4.3 | harang actor — plan 생성 호출 + stub 응답 | mock 시나리오 pass | cc:TODO |
| 4.4 | narang actor — impl 호출 + stub 응답 | mock 시나리오 pass | cc:TODO |
| 4.5 | darang actor — review 호출 (stub QA) | mock 시나리오 pass | cc:TODO |
| 4.6 | erang actor — deploy 호출 (stub) | mock 시나리오 pass | cc:TODO |
| 4.7 | XState 머신의 actor invoke 연결 | FSM test pass | cc:TODO |
| 4.8 | discord.js bridge 초기화 (login, guild 선택) | 봇 online | cc:TODO |
| 4.9 | state transition → discord message mapping | 포럼 포스트 동작 | cc:TODO |
| 4.10 | escalated / done 시 사용자 멘션 | 멘션 동작 확인 | cc:TODO |
| 4.11 | `rails run --mock <project>` 서브커맨드 | end-to-end mock pass | cc:TODO |
| 4.12 | OpenClaw spawn 커맨드 결정 + 문서화 | `docs/openclaw-integration.md` | cc:TODO |
| 4.13 | 자매 system prompt 에 structured output 강제 | 프롬프트 파일 존재 | cc:TODO |

## Definition of Done

### 자동
- `rails run --mock test-project` 이 `planning → implementing → reviewing → deploying → done` 전이 완주
- `state_transitions` 테이블에 전이 5건 이상
- discord bridge 가 전이마다 메시지 전송
- `HandoffMessage` Zod 위반 시 ERROR event 로 전이
- Timeout 시나리오는 일단 ERROR (Sprint 005 에서 retry 추가)

### 수동
- [ ] 실제 OpenClaw agent 호스트 1회 연결 테스트 (환경 허용 시)
- [ ] 디스코드 포럼 포스트 한 번 수동 확인
- [ ] 멘션 스킵/실행 시나리오 수동 검증

## Exit Criteria

F3 / F4 재현 불가. 자매가 호출 안 되는 상황 없음. 멘션 기반 라우팅 제거 완료.