# 계획서: Zero-Error Dispatch 시스템

**프로젝트**: Lovable 수준 무결성 달성 (dispatch 1회 완료율 95%+)
**작성일**: 2026-03-09
**작업 레벨**: Lv.4
**미팅 기록**: `memory/meetings/2026-03-09-zero-error-dispatch.md`

---

## 목표

dispatch 1회에 오류 없이 완료되는 비율을 **현재 ~80% → 95% 이상**으로 향상.
Lovable의 실질 오류율 1.7%에 근접.

## 범위

### 포함
- dispatch.py 파이프라인 개선
- QC 강제 메커니즘
- DIRECT-WORKFLOW.md 워크플로우 개선
- team_prompts.py 프롬프트 개선
- chain.py 버그 수정
- 좀비 태스크 감지/복구

### 제외
- Container-per-Session (장기 과제)
- SQLite 상태 이관 (별도 프로젝트)
- NLP 기반 spec_conformance (연구 필요)
- cokacdir 자체 변경

---

## Phase 1: 확정 버그 + QC 게이트 (1팀, 1세션)

### 1-1. chain.py `--task` → `--task-file` 변경
- **파일**: `/home/jay/workspace/chain.py` 193-199행
- **내용**: `_dispatch_phase()`에서 task description을 파일에 쓰고 `--task-file`로 전달
- **테스트**: chain.py 기존 테스트 + 특수문자 포함 description 테스트

### 1-2. subprocess.run() timeout 추가
- **파일**: `dispatch.py` 350행, `chain.py` 202행, `notify-completion.py` 46행
- **내용**: `timeout=60` 추가, `TimeoutExpired` 예외 처리
- **테스트**: timeout 시 적절한 에러 메시지 반환 확인

### 1-3. QC 타이밍 수정
- **파일**: `/home/jay/workspace/prompts/DIRECT-WORKFLOW.md`
- **내용**: Step 순서 변경 — 보고서 작성 → .done 생성 → QC 실행 → QC FAIL시 수정(최대 3회)
- **테스트**: 워크플로우 문서 파싱 테스트 (순서 검증)

### 1-4. qc_verify.py --gate 플래그
- **파일**: `teams/dev1/qc/qc_verify.py`, `teams/dev2/qc/qc_verify.py`
- **내용**: `--gate` 플래그 추가. PASS/WARN이면 .done 자동 생성, FAIL이면 거부
- **테스트**: PASS→.done 생성, FAIL→.done 미생성, WARN→.done 생성+경고

### 1-5. orphan task watchdog
- **파일**: `/home/jay/workspace/scripts/orphan-watchdog.py` (신규)
- **내용**: task-timers.json에서 running 60분 초과 태스크 감지 → 아누에게 알림
- **테스트**: 좀비 태스크 시뮬레이션 + 알림 발송 확인

---

## Phase 2: Structured Spec + Retry Loop (1팀, 1세션)

### 2-1. Structured Spec Format
- **파일**: `/home/jay/workspace/prompts/spec_template.yaml` (신규), dispatch 문서 업데이트
- **내용**: YAML frontmatter 스펙 포맷 정의 (target_files, edge_cases, test_method)

### 2-2. validate_spec() 게이트
- **파일**: `/home/jay/workspace/prompts/spec_validator.py` (신규), dispatch.py 수정
- **내용**: dispatch 전 스펙 완전성 검증. 레벨별 차등 적용.

### 2-3. Inner Retry Loop
- **파일**: DIRECT-WORKFLOW.md, `team_prompts.py` (_build_cowork_section)
- **내용**: 서브에이전트 코딩 후 즉시 pyright→pytest→수정 루프 (최대 3회)

### 2-4. ANU_KEY 하드코딩 제거
- **대상**: 29개 파일에서 `c119085addb0f8b7` 제거
- **내용**: fallback 제거, 환경변수 미설정 시 즉시 에러

### 2-5. QC 결과 아카이빙
- **파일**: qc_verify.py, DIRECT-WORKFLOW.md
- **내용**: `--output memory/qc-results/{task_id}.json` 강제

---

## Phase 3: Heartbeat + Resume + Advanced QC (1팀, 1세션)

### 3-1~3-4: 상세는 Phase 2 완료 후 재설계

---

## 위임 계획
- **Phase 1**: 1팀(헤르메스) — 5개 항목, 예상 복잡도 Lv.2
- **Phase 2**: Phase 1 오류율 측정 후 결정 (1팀 또는 2팀)
- **Phase 3**: Phase 2 결과에 따라 필요성 재판단

## 검증 기준
- Phase 1 완료 후: 다음 10건 dispatch에서 오류 횟수 측정
- 목표: 10건 중 9건 이상 1회 완료 (90%+)
- Phase 2까지 완료: 95%+ 목표