# task-2028: finish-task.sh 일원화 MVP — QC→머지→.done 순차 강제

## 배경
에이전트 미팅 3사이클 합의. 현재 .done/QC/머지 순서 불일치로 워크트리 소실 + QC 헛돌기 문제.
C안 채택: finish-task.sh가 유일한 작업 완료 경로.

## ★ 반드시 먼저 읽을 파일 ★
1. `scripts/finish-task.sh` — 현재 코드
2. `teams/shared/qc_verify.py` — --gate 모드의 .done 생성 로직 (539-602행)
3. `prompts/DIRECT-WORKFLOW.md` — Step 4.5~7
4. `memory/research/agent-meeting-quality-crisis.md` — 에이전트 미팅 합의

## MVP 구현 4건

### 1. finish-task.sh에 팀ID + project_path 인자 확장
- 현재: `finish-task.sh <task_id>`
- 변경: `finish-task.sh <task_id> [team_short] [project_path]`
- team_short: qc_verify.py 호출 시 팀별 경로 resolve에 사용
- project_path: worktree_manager.py finish 호출 시 프로젝트 경로
- 미지정 시: task-timers.json 또는 task 파일에서 자동 추출 (fallback)

### 2. QC → 머지 → .done → timer end 순차 로직
- finish-task.sh 내부 실행 순서:
  1. qc_verify.py --gate 호출 → .qc-result 생성 (★ .done은 생성하지 않음)
  2. QC PASS/WARN이면 → worktree_manager.py finish --action auto 호출 (머지)
  3. 머지 성공이면 → .done 생성 (qc_result 필드 포함)
  4. task-timer.py end 호출
  5. notify-completion.py 호출
  6. QC FAIL이면 → .failed 생성 + exit 1 (머지/타이머/알림 전부 스킵)

### 3. QC FAIL 시 .failed 이벤트 생성
- 파일: `memory/events/{task_id}.failed`
- 내용: task_id, team, fail_reason, timestamp
- done-watcher.py에 .failed 패턴 추가 (아누에게 FAIL 알림)

### 4. 단계별 상태 파일 멱등성
- 각 단계 완료 시 상태 파일 생성:
  - `.qc-done` — QC PASS 완료
  - `.merge-done` — 머지 완료
- 재실행 시 완료된 단계 스킵
- 중간 크래시 복구 보장

## 연동 수정

### 5. qc_verify.py --gate에서 .done 생성 제거
- `_handle_gate()` 함수: PASS/WARN 시 .done 생성 로직 제거
- .qc-result 파일만 생성
- --gate 플래그 자체는 유지 (의미: "QC 실행 + .qc-result 생성")

### 6. DIRECT-WORKFLOW.md Step 수정
- Step 4.5(worktree finish) 제거 또는 "finish-task.sh에서 자동 수행" 안내
- Step 6(QC): "finish-task.sh가 자동 수행" 안내
- Step 7: `bash finish-task.sh {task_id} {team_short} {project_path}`
- 봇 프롬프트에 **"finish-task.sh FAIL → 수정 → finish-task.sh 재실행"** 루프 명시

### 7. team_prompts.py 프롬프트 수정
- 기존 Step 6/7 텍스트를 통합된 Step으로 변경

## ★★★ 절대 규칙 ★★★
- 기존 봇 동작을 깨지 않도록 하위 호환 유지
- 신규 dispatch부터 적용, 진행 중 작업은 구버전으로 완료
- 기존 pytest 전체 PASS 필수

## 완료 시그니처
- [grep] `qc_verify.*--gate\|qc-done\|merge-done` @ `scripts/finish-task.sh`
- [grep] `\.failed` @ `scripts/finish-task.sh`
- [grep] `finish-task.sh.*team_short\|project_path` @ `prompts/DIRECT-WORKFLOW.md`
- [pytest] `tests/test_dispatch.py`

## 검증 시나리오
1. finish-task.sh 실행 → QC PASS → 머지 → .done 생성 (순차 확인)
2. finish-task.sh 실행 → QC FAIL → .failed 생성 + .done 미생성
3. 중간에 중단 후 재실행 → 완료 단계 스킵 (멱등성)
4. qc_verify.py --gate 실행 → .qc-result만 생성 (.done 미생성)
5. pytest 전체 PASS

## 레벨
- critical (시스템 핵심 인프라)

## 프로젝트
- dev-system