# task-414.1 보고서: Zero-Error Dispatch Phase 1

**task_id**: task-414.1
**팀**: dev1-team (헤르메스)
**레벨**: Lv.2
**작업일**: 2026-03-09

---

## 작업 요약

5개 서브태스크로 구성된 Zero-Error Dispatch 시스템 안정성 개선 작업.

---

## 서브태스크별 결과

### 1-1. chain.py `--task` → `--task-file` 변경
- **파일**: `chain.py` (`_dispatch_phase()` 함수)
- **변경**: task description을 `memory/tasks/chain-{chain_id}-phase{idx}-{team}.md` 파일에 저장 후 `--task-file` 플래그로 전달
- **기존 `--task '{description}'` 방식 완전 제거** → 특수문자(`'`, `"`, `$`, 백틱) 안전 처리
- **테스트**: 3개 추가 (파일 생성 확인, --task-file 플래그 사용, 특수문자 테스트)

### 1-2. subprocess.run() timeout 추가
- **대상**: dispatch.py, chain.py, notify-completion.py
- **변경**: 모든 subprocess.run()에 timeout 추가
  - 외부 호출(cokacdir): timeout=60
  - 로컬 호출(python3): timeout=30
- **TimeoutExpired 예외 처리**: 에러 로깅 + cleanup + 에러 반환
- **테스트**: 5개 추가

### 1-3. DIRECT-WORKFLOW.md QC 타이밍 수정
- **파일**: `prompts/DIRECT-WORKFLOW.md`
- **변경**: Step 순서 재구성
  - Step 4: 테스트 (pytest + pyright)
  - Step 5: 보고서 작성
  - Step 6: QC 자동 검증 (`--gate` 플래그, .done 파일 자동 생성)
  - Step 7: task-timer end
  - Step 8: 아누 완료 통보
  - Step 9: 체인 Phase 완료 알림
- **핵심**: .done 생성을 qc_verify.py `--gate`가 제어 → file_check 오탐 해소

### 1-4. qc_verify.py --gate 플래그
- **대상**: `teams/dev1/qc/qc_verify.py` (dev2 디렉토리 미존재, 1개만 수정)
- **변경**:
  - `--gate` CLI 플래그 추가
  - `--team` CLI 인자 추가 (기본값: dev1-team)
  - `_handle_gate()` 함수 신규: PASS/WARN → .done 자동 생성, FAIL → 미생성
  - .done 파일 JSON 형식: task_id, team, qc_result, timestamp, status, merge_needed, merge_branch
- **테스트**: 8개 추가 (PASS/WARN/FAIL 분기, 하위호환, 내용 검증, 디렉토리 자동 생성)

### 1-5. orphan-watchdog.py
- **파일**: `scripts/orphan-watchdog.py` (신규)
- **기능**: task-timers.json에서 status=started/running이고 60분+ 경과한 좀비 태스크 감지
- **출력**: JSON (zombies 배열, checked_at, total)
- **exit code**: 좀비 없으면 0, 있으면 1
- **테스트**: 6개 추가

---

## 생성/수정 파일 목록

### 수정 파일
- `chain.py` — _dispatch_phase() --task-file 전환 + timeout 추가
- `dispatch.py` — subprocess.run() timeout 추가 (외부 60s, 로컬 30s)
- `scripts/notify-completion.py` — subprocess.run() timeout 추가
- `prompts/DIRECT-WORKFLOW.md` — QC 타이밍 수정 (Step 5-9 재구성)
- `teams/dev1/qc/qc_verify.py` — --gate, --team 플래그 + _handle_gate()

### 신규 파일
- `scripts/orphan-watchdog.py` — 좀비 태스크 워치독
- `tests/test_qc_gate.py` — qc_verify --gate 테스트 (8개)
- `tests/test_orphan_watchdog.py` — orphan-watchdog 테스트 (6개)

### 수정 테스트 파일
- `tests/test_chain.py` — TestDispatchPhaseTaskFile 클래스 추가 (3개)
- `tests/test_dispatch.py` — TestSubprocessTimeout 클래스 추가 (5개)

---

## 테스트 결과

- **전체 테스트**: 719 passed, 0 failed
- **신규 테스트**: 22개 추가 (3 + 5 + 8 + 6)
- **pyright**: 0 errors, 0 warnings
- **black + isort**: 포매팅 적용됨 (변경 없음)

---

## 크론 등록 명령어 (아누가 등록)

```bash
cokacdir --cron "좀비 태스크 감지 실행: python3 /home/jay/workspace/scripts/orphan-watchdog.py" --at "*/30 * * * *" --chat 6937032012 --key c119085addb0f8b7
```

---

## 비고

- dev2 QC 디렉토리(`teams/dev2/qc/`)가 존재하지 않아 1-4 작업은 dev1만 적용
- task-413.1 → task-414.1로 task_id 수정 (작업 파일의 task_id 참조값과 실제 배정 ID가 다름)