# fireauto 통합 프로젝트 — Definition of Done 체크리스트

> 버전: v1.0
> 작성일: 2026-04-11
> 작성자: 프레이야 (프론트엔드 엔지니어)
> 참조 PRD: `/home/jay/workspace/memory/specs/prd-fireauto-integration.md`
> 상태: Draft — 제이회장님 승인 대기

---

## Sprint 0 (0.5일) — 준비 작업

Sprint 0는 이후 모든 Phase의 선행 조건이므로, 체크리스트 완료 전 Phase 1 착수 금지.

### 완료 조건 (Definition of Done)

- [ ] PRD 템플릿 표준화 완료 — `## Tasks` 섹션 + bullet list 형식 확정
- [ ] settings.json 타임스탬프 백업 절차 수립 (`settings.json.bak.YYYYMMDD_HHMMSS` 형식)
- [ ] settings.json JSON 유효성 검증 스크립트 준비
- [ ] DIRECT-WORKFLOW/QC-RULES 내 텍스트 재시도 규칙 deprecated 처리 완료
- [ ] 각 Phase DoD 체크리스트 (본 문서) 스테이크홀더 검토 완료

### 테스트 항목

| 입력 | 기대 결과 |
|------|----------|
| 기존 PRD 파일을 신규 템플릿 기준으로 열기 | `## Tasks` 섹션 + bullet list 형식 확인 |
| settings.json 변경 시뮬레이션 실행 | 백업 파일 생성 + JSON 유효성 검증 통과 |
| DIRECT-WORKFLOW 파일 열기 | 재시도 텍스트 규칙에 deprecated 주석 존재 |

### 롤백 기준

- settings.json 수정 중 JSON 유효성 오류 발생 시 → 즉시 백업 파일로 복원
- PRD 템플릿 변경으로 기존 dispatch.py 파싱이 깨지는 경우 → 템플릿 롤백 후 재설계

---

## Phase 1 (2일) — CEO 즉시 체감 [F4, F5, F6]

### 완료 조건 (Definition of Done)

**F4 — 진행률 자동 계산**

- [ ] `task-timer.py progress` 서브커맨드 구현 완료
- [ ] `task-timer.py end {task_id}` 실행 시 `active-projects.json`의 `progress` 필드 자동 갱신
- [ ] 대시보드 프로젝트뷰 API 응답에 실시간 진행률 포함 확인
- [ ] 대시보드 JS 5분 자동 새로고침 동작 확인 (SSE 미사용)
- [ ] `dispatch.py`의 `project_id` 파라미터 사용 일관성 80% 이상 검증

**F5 — whisper-briefing 강화**

- [ ] `whisper-compile.py` 확장 완료 — 진행률 + 최근 실수 + 미착수 목록 포함
- [ ] whisper 출력에 최근 실수 3건 이상 포함 확인
- [ ] 미착수 태스크 목록 표시 (마지막 수정 3일 이상 경과 기준)
- [ ] "다음 추천" 기능 미포함 확인 (6개월 보류 정책 준수)

**F6 — CLAUDE.md 비대화 경고**

- [ ] QC 셀프 체크리스트 항목 10에 "CLAUDE.md 100줄 미만 확인" 항목 추가
- [ ] `qc_verify.py`에 `claude_md_check` verifier 추가 (WARN 전용, FAIL 아님)
- [ ] 100줄 기준이 팀 고유 규칙 줄 수(team_prompts.py 공통 섹션 제외) 기준임을 코드에 주석 명시
- [ ] 자동 트리밍 로직 미포함 확인

**Phase 1 통합 완료 기준**

- [ ] 대시보드에서 프로젝트 진행률 자동 표시 (수동 "업데이트해" 요청 없이)
- [ ] whisper 실행 결과에 실수 3건 이상 포함 (실측)

### 테스트 항목

**F4 진행률 자동 계산**

| 시나리오 | 입력 | 기대 결과 |
|---------|------|----------|
| progress 서브커맨드 기본 동작 | `python task-timer.py progress {project_id}` | 해당 프로젝트 completed/total 출력 |
| task 완료 시 자동 갱신 | `python task-timer.py end {task_id}` | `active-projects.json`의 progress 필드 갱신 확인 |
| 대시보드 자동 새로고침 | 브라우저에서 대시보드 열기 후 5분 대기 | 페이지 데이터 자동 갱신, 콘솔 오류 없음 |
| project_id 누락 케이스 | project_id 없는 task end 실행 | 경고 메시지 출력, active-projects.json 미갱신 (graceful skip) |

**F5 whisper-briefing 강화**

| 시나리오 | 입력 | 기대 결과 |
|---------|------|----------|
| 기본 whisper 실행 | `python whisper-compile.py` | 진행률 블록 + 실수 블록 + 미착수 목록 모두 출력 |
| 실수 데이터 부족 케이스 | 최근 피드백 메모리 1건만 있을 때 | "실수 N건 확인됨 (3건 미만)" 표시, 오류 없음 |
| 미착수 목록 확인 | 마지막 수정 4일 전 태스크 존재 시 | 해당 태스크 미착수 목록에 포함 |
| 미착수 목록 미포함 케이스 | 모든 태스크 최근 2일 내 활동 시 | 미착수 목록 섹션 빈 값 또는 "없음" 출력, 오류 없음 |

**F6 CLAUDE.md 비대화 경고**

| 시나리오 | 입력 | 기대 결과 |
|---------|------|----------|
| CLAUDE.md 100줄 미만 | 팀 CLAUDE.md 90줄 상태에서 qc_verify.py 실행 | claude_md_check PASS (경고 없음) |
| CLAUDE.md 100줄 초과 | 팀 CLAUDE.md 120줄 상태에서 qc_verify.py 실행 | claude_md_check WARN 출력 (FAIL 아님, 전체 QC는 통과) |
| QC 셀프 체크리스트 확인 | CLAUDE.md 항목 10 내용 열기 | "CLAUDE.md 100줄 미만 확인" 항목 존재 |

### 롤백 기준

**롤백 트리거**

- `task-timer.py progress` 실행 시 기존 `task-timers.json` 데이터 손상 발생
- `active-projects.json` 자동 갱신 중 파일 유실 또는 스키마 불일치
- 대시보드 5분 자동 새로고침이 무한 루프 또는 브라우저 크래시 유발
- `qc_verify.py` claude_md_check가 WARN이 아닌 FAIL을 반환하여 정상 QC 흐름 차단

**롤백 절차**

1. `task-timer.py`는 이전 버전으로 되돌리고 progress 서브커맨드만 제거
2. `active-projects.json`은 최근 백업본으로 복원 (daily backup 기준)
3. 대시보드 JS는 자동 새로고침 코드 블록을 주석 처리
4. `qc_verify.py`에서 `claude_md_check` verifier 함수를 비활성화 (호출 제거)
5. 롤백 후 아누에게 즉시 보고 + 원인 분석 착수

---

## Phase 2 (2일) — Hook 인프라 + 자동 기록 [F1, F2, F7]

### 완료 조건 (Definition of Done)

**F1 — audit-trail.jsonl 강화**

- [ ] `audit-trail.jsonl` 레코드에 `task_id` 필드 의무화 완료
- [ ] `audit-trail.jsonl` 레코드에 `schema_version: 2` 필드 추가
- [ ] 기존 schema_version 1 레코드와의 하위 호환성 검증 완료
- [ ] `dispatch.py`에서 `COKACDIR_TASK_ID` 환경변수 주입 구현
- [ ] task_id 누락 시 `session_id` fallback + stderr 경고 로직 동작 확인
- [ ] `post-tool-use.sh` Hook에 BOT_ID 가드 삽입 확인 (`detect-bot.sh` 기반)
- [ ] Hook 스크립트에 `timeout 5 ... || true` 래퍼 적용 확인
- [ ] Hook 실행 시간 50ms 이하 목표 — pyright 등 무거운 연산 미포함 확인
- [ ] `flock` 기반 동시 write 보호 적용 확인

**F2 — 세션 통계 자동 생성**

- [ ] `finish-task.sh` 말미에 세션 통계 생성 로직 추가
- [ ] `qc_verify.py` PASS 이후에만 보고서에 세션 통계 섹션 append 확인
- [ ] 보고서 `reports/{task_id}.md`에 `## 세션 통계` 섹션 생성 확인
  - [ ] 수정 파일 목록 + 각 파일 Edit/Write 횟수 포함
  - [ ] 총 도구 호출 횟수 포함
  - [ ] 세션 시작~종료 시간 포함 (task-timers.json 참조)
- [ ] 비정상 종료 시 trap 핸들러로 최소 통계(시작/종료 시각) 기록 확인

**F7 — 에러 감지 + Hook 강제 재시도**

- [ ] PostToolUse Hook에 에러 카운터 관리 구현 (`/tmp/{task_id}_retry.count`)
- [ ] 카운터 3회 초과 시 하드 스톱 경고 동작 확인
- [ ] task 재시작 시 카운터 자동 리셋 확인
- [ ] Hook은 카운터 증가만 담당, pyright 직접 실행 미포함 확인

**Phase 2 배포 절차**

- [ ] 1개 팀 시범 운영 완료 (최소 1 세션 이상)
- [ ] 시범 운영 중 기존 팀 작업 무중단 확인
- [ ] 시범 운영 결과 이상 없음 확인 후 전 팀 확대 적용

**Phase 2 통합 완료 기준**

- [ ] 1개 팀의 실제 세션에서 `task_id` 포함 audit-trail 레코드 생성 확인
- [ ] 해당 세션 완료 후 보고서에 `## 세션 통계` 섹션 자동 생성 확인

### 테스트 항목

**F1 audit-trail.jsonl 강화**

| 시나리오 | 입력 | 기대 결과 |
|---------|------|----------|
| task_id 정상 주입 | dispatch.py로 태스크 시작 후 파일 Edit | audit-trail.jsonl에 `{"task_id": "...", "schema_version": 2, ...}` 레코드 생성 |
| task_id 누락 케이스 | COKACDIR_TASK_ID 미설정 상태에서 파일 Edit | stderr에 경고 출력 + session_id fallback으로 기록 |
| 아누 세션 BOT_ID 가드 | 아누 세션에서 파일 Edit | Hook 실행 즉시 exit 0, audit-trail에 기록 없음 |
| 하위 호환성 검증 | 기존 schema_version 1 레코드 조회 | 파싱 오류 없음, `schema_version` 필드 없으면 1로 간주 |
| 동시 write 충돌 | 2개 팀 봇이 동시에 Edit 실행 | flock으로 순차 처리, audit-trail.jsonl 레코드 유실 없음 |
| Hook 성능 측정 | post-tool-use.sh 실행 시간 측정 | 50ms 이하 (평균값 기준) |

**F2 세션 통계 자동 생성**

| 시나리오 | 입력 | 기대 결과 |
|---------|------|----------|
| 정상 세션 완료 | finish-task.sh 실행 (qc_verify.py PASS 상태) | reports/{task_id}.md에 `## 세션 통계` 섹션 append |
| QC FAIL 케이스 | finish-task.sh 실행 (qc_verify.py FAIL 상태) | 세션 통계 섹션 미생성, 보고서에 FAIL 상태만 기록 |
| 비정상 종료 케이스 | 세션 중 강제 종료 | trap 핸들러 작동, 보고서에 시작/종료 시각 최소 기록 |
| 통계 내용 검증 | 10개 파일 수정 세션 완료 | 파일 목록 10개 + 각 파일별 횟수 + 총 호출수 정확히 기록 |

**F7 에러 카운터**

| 시나리오 | 입력 | 기대 결과 |
|---------|------|----------|
| 카운터 증가 | Edit 후 에러 발생 1회 | `/tmp/{task_id}_retry.count` 값 1 |
| 하드 스톱 트리거 | 에러 3회 초과 | Hook이 경고 메시지 출력 |
| 카운터 리셋 | task 재시작 | `/tmp/{task_id}_retry.count` 파일 삭제 또는 0으로 초기화 |
| pyright 미실행 확인 | post-tool-use.sh 코드 리뷰 | pyright 직접 호출 코드 없음 |

### 롤백 기준

**롤백 트리거**

- PostToolUse Hook 오류로 팀 봇 세션이 블로킹되는 현상 발생
- audit-trail.jsonl 파일 손상 또는 flock 데드락 발생
- Hook 실행 시간이 평균 200ms 초과하여 세션 속도 저하 체감
- 시범 운영 팀에서 비정상 보고서 생성 (중복 섹션, 내용 누락 등)
- 하위 호환성 위반으로 기존 레코드 파싱 오류 발생

**롤백 절차**

1. settings.json을 타임스탬프 백업본으로 즉시 복원 (새 세션부터 Hook 비활성화)
2. 진행 중인 세션은 완료까지 유지 (강제 종료 금지)
3. audit-trail.jsonl의 손상된 레코드 격리 (파일 분리 보관)
4. `post-tool-use.sh`에서 신규 추가 로직 주석 처리 (BOT_ID 가드는 유지)
5. `finish-task.sh`에서 세션 통계 섹션 append 로직 비활성화
6. 전 팀 확대 전이라면 시범 팀에만 적용된 변경 원복
7. 아누에게 즉시 보고 + hook-debug.log 첨부 분석

---

## Phase 3 (2일) — 학습 + 검색 + PRD 분해 [F3, F8, F10]

### 완료 조건 (Definition of Done)

**F3 — 자기 학습 루프 (v1)**

- [ ] `/retro` 스킬 확장 완료 — audit-trail.jsonl + reports/*.md 분석 로직 추가
- [ ] `config/learning-whitelist.yaml` 파일 생성 (인프라 파일 제외 목록 외부화)
- [ ] `config/learning-thresholds.yaml` 파일 생성 (비율 임계값 + 절대값 기준 외부화)
- [ ] 핫스팟 파일 감지 로직 동작 확인 (주간 태스크 중 N% 이상 AND 3건 이상)
- [ ] 학습 리포트 저장 경로 확인: `memory/learnings/weekly-{date}.md`
- [ ] 각 피드백 레코드에 `status` 필드 포함 확인 (pending / applied / skipped_whitelist / deferred_v2)
- [ ] whisper 출력에 "미처리 학습 피드백 N건" 자동 표시 확인
- [ ] 학습 리포트/whisper 출력에 "학습 기능 v1 — 에러 유사도 미지원(v2 예정)" 문구 포함 확인
- [ ] 실시간 스킬 자동 생성 미포함 확인 (주간 배치만)

**F8 — 메모리 통합 검색**

- [ ] `memory-search.py` 구현 완료 (grep 기반 + 파일명/날짜/팀 필터링)
- [ ] 검색 대상 경로 포함 확인: reports/*.md + research/*.md + learnings/*.md
- [ ] 대시보드 기록 탭에 통합 검색 UI 추가
- [ ] 검색 응답 시간 500ms 이하 확인 (현재 ~1,600건 기준)
- [ ] SQLite 미사용 확인 (파일 수 3,000건 미도달 — 파일 기반 유지)

**F10 — dispatch.py PRD 자동 분해**

- [ ] `dispatch.py --prd` 옵션 구현 완료
- [ ] 정규식 파싱 우선 동작 확인 (`## Tasks` 섹션 bullet list 파싱)
- [ ] 정규식 파싱 실패 시 LLM 폴백 동작 확인
- [ ] PRD 템플릿 외 형식에서 적절한 오류 메시지 출력 확인

**Phase 3 통합 완료 기준**

- [ ] 주간 학습 리포트 샘플 파일 생성 확인 (`memory/learnings/weekly-{date}.md`)
- [ ] 대시보드 검색 기능 동작 확인 (실제 검색어 입력 테스트)
- [ ] `dispatch.py --prd {prd_path}` PRD 분해 테스트 완료

### 테스트 항목

**F3 자기 학습 루프**

| 시나리오 | 입력 | 기대 결과 |
|---------|------|----------|
| 핫스팟 파일 감지 | server.py가 주간 10개 task 중 8개에서 수정된 경우 | server.py 핫스팟 파일로 학습 리포트에 포함 |
| 화이트리스트 제외 | task-timer.py가 다수 수정된 경우 | learning-whitelist.yaml에 의해 리포트 제외 |
| 절대값 기준 미달 | 특정 파일이 비율은 높으나 2건만 수정된 경우 | AND 조건 미충족으로 핫스팟 미포함 |
| v1 한계 문구 확인 | /retro 실행 후 리포트 내용 확인 | "학습 기능 v1 — 에러 유사도 미지원(v2 예정)" 문구 존재 |
| whisper 피드백 카운트 | 미처리 피드백 3건 있는 상태에서 whisper 실행 | "미처리 학습 피드백 3건" 표시 |

**F8 메모리 통합 검색**

| 시나리오 | 입력 | 기대 결과 |
|---------|------|----------|
| 키워드 검색 | `python memory-search.py --query "server.py"` | 해당 키워드 포함 파일 목록 반환 |
| 날짜 필터 | `--date 2026-04-01` 옵션 추가 | 해당 날짜 이후 파일만 반환 |
| 팀 필터 | `--team dev` 옵션 추가 | dev 팀 관련 파일만 반환 |
| 대시보드 검색 UI | 브라우저에서 검색어 입력 후 Enter | 검색 결과 목록 렌더링, 500ms 이내 응답 |
| 결과 없음 케이스 | 존재하지 않는 키워드 검색 | "결과 없음" 메시지 출력, 오류 없음 |

**F10 dispatch.py PRD 분해**

| 시나리오 | 입력 | 기대 결과 |
|---------|------|----------|
| 표준 형식 PRD | `dispatch.py --prd prd-sample.md` | `## Tasks` 섹션 bullet list 파싱 성공, 태스크 목록 출력 |
| 비표준 형식 PRD | 표준 `## Tasks` 섹션 없는 PRD 파일 | 정규식 실패 → LLM 폴백 실행 + 폴백 사용 안내 출력 |
| 존재하지 않는 파일 | `dispatch.py --prd nonexistent.md` | 파일 없음 오류 메시지 + 비정상 종료 코드 반환 |
| 파싱 결과 검증 | 10개 태스크 포함 PRD 분해 | 태스크 10개 정확히 추출 (순서 보존) |

### 롤백 기준

**롤백 트리거**

- `/retro` 실행이 기존 보고서 파일을 덮어쓰거나 손상시키는 경우
- `memory-search.py`가 검색 중 대용량 파일을 읽어 메모리 부족 발생
- 대시보드 검색 UI 추가로 기존 대시보드 기능(프로젝트뷰 등) 깨짐
- `dispatch.py --prd` 옵션이 기존 dispatch 동작에 영향 (옵션 없는 기존 호출 오작동)
- 학습 리포트에 화이트리스트 미적용으로 인프라 파일이 핫스팟으로 오감지

**롤백 절차**

1. `/retro` 스킬을 이전 버전으로 롤백 (확장 로직만 제거, 기본 retro 기능 유지)
2. `memory-search.py` 파일 삭제 + 대시보드에서 검색 UI 컴포넌트 비활성화
3. `dispatch.py`에서 `--prd` 옵션 분기 제거 (기존 dispatch 로직 무변경 유지)
4. `config/learning-*.yaml` 파일은 보존 (재구현 시 재사용)
5. 잘못 생성된 학습 리포트 파일 격리 (`memory/learnings/quarantine/` 이동)
6. 아누에게 즉시 보고 + 원인 파악 후 재설계

---

## Phase 4 (2일) — 고도화 (조건부) [F12, F11]

> **주의**: Phase 4는 조건부 진행. Phase 3 완료 후 2일 이내 F11 포함/제외 결정 필요.
> F11 진입 조건 미충족 시 Phase 4 = F12만 구현 (1일로 단축).
> F9는 F3에 흡수 완료, 별도 구현 없음.

### 완료 조건 (Definition of Done)

**F12 — completion-promise (루프 반복 고도화)**

- [ ] `chain_manager.py`에 retry phase 삽입 완료 (dispatch.py 새 옵션 아님)
- [ ] 최대 재위임 횟수 상수 `MAX_RETRY = 2` 코드에 명시
- [ ] 2회 실패 시 circuit breaker 동작 확인
  - [ ] `escalations/{task_id}_escalation.json` 파일 생성 확인
  - [ ] 이후 자동 작업 완전 중단 확인
- [ ] 완료 조건이 `qc_verify.py` PASS 필수임을 확인 (self-certification 금지)
- [ ] 재위임 발생 시마다 audit-trail.jsonl에 기록 확인
- [ ] 점층적 재시도 전략 구현 확인:
  - [ ] 1회차: 에러 메시지 직접 수정
  - [ ] 2회차: 관련 import/타입 힌트 전체 점검
  - [ ] 3회차: escalation (아누 보고)

**F11 — 수요 조사 자동 수집 (조건부)**

- [ ] (진입 조건 충족 시) 네이버 API 제한/차단 리스크 사전 평가 완료
- [ ] (진입 조건 충족 시) advanced-crawling 스킬(Scrapling) 활용 방안 결정
- [ ] (진입 조건 미충족 시) F11 미구현 결정 공식 기록

**Phase 4 통합 완료 기준**

- [ ] completion-promise 시나리오에서 2회 재위임 동작 확인
- [ ] 3회차 circuit breaker 발동 + `escalations/` 파일 생성 확인
- [ ] circuit breaker 이후 자동 작업 중단 확인

### 테스트 항목

**F12 completion-promise**

| 시나리오 | 입력 | 기대 결과 |
|---------|------|----------|
| 정상 완료 케이스 | chain_manager.py 실행, qc_verify.py 1회차 PASS | 재위임 없이 정상 완료 |
| 1회 재위임 | qc_verify.py 1회차 FAIL → 2회차 PASS | 1회 재위임 후 완료, audit-trail에 재위임 기록 1건 |
| 2회 재위임 | qc_verify.py 1,2회차 FAIL → 3회차 PASS | 2회 재위임 후 완료, audit-trail에 재위임 기록 2건 |
| circuit breaker 발동 | qc_verify.py 3회 연속 FAIL | `escalations/{task_id}_escalation.json` 생성 + 자동 작업 중단 |
| MAX_RETRY 상수 확인 | chain_manager.py 코드 리뷰 | `MAX_RETRY = 2` 상수 명시 확인 |
| 재위임 이력 기록 | 재위임 발생 시 audit-trail.jsonl 확인 | 재위임 진입점 레코드 존재, task_id + schema_version 포함 |
| self-certification 방지 | chain_manager.py에서 자체 완료 처리 시도 | qc_verify.py 호출 없이 완료 처리 불가 확인 |

**F11 수요 조사 자동 수집 (진입 조건 충족 시)**

| 시나리오 | 입력 | 기대 결과 |
|---------|------|----------|
| 리스크 평가 완료 | 네이버 API 사용 테스트 | 차단 여부 및 제한 조건 문서화 |
| Scrapling 연동 | advanced-crawling 스킬 호출 | 네이버 카페/블로그 수집 동작 확인 |

### 롤백 기준

**롤백 트리거**

- circuit breaker 로직 버그로 MAX_RETRY 초과하여 무한 재위임 발생
- `escalations/` 파일 생성 실패로 escalation 유실
- `chain_manager.py` 변경이 기존 dispatch/task 흐름에 영향
- qc_verify.py PASS 없이 완료 처리되는 self-certification 버그 발생
- F11: 네이버 API 차단으로 크롤링 IP 블랙리스트 등재 위험 감지

**롤백 절차**

1. `chain_manager.py`에서 retry phase 코드 블록 제거 (기존 단순 위임 로직 복원)
2. 생성된 `escalations/` 파일은 보존 (증거 자료)
3. audit-trail.jsonl의 재위임 기록도 보존 (삭제 금지)
4. F11 활성화 상태였다면 즉시 크롤링 중단 + 네이버 API 관련 설정 비활성화
5. 아누에게 즉시 보고 + 재설계 협의

---

## 공통 기준

### 모든 Phase 적용 원칙

- **Graceful Degradation**: 신규 기능 파일 누락 시 오류 없이 skip (기존 기능 보호)
- **Hook 안전 패턴**: 모든 Hook에 `trap 'exit 0' ERR` 적용
- **단일 소스 원칙**: 새 파일/DB 생성 전 기존 파일 확장 우선 검토
- **배포 안전**: settings.json 변경 전 반드시 타임스탬프 백업

### Phase 간 의존성

```
Sprint 0 → Phase 1 → Phase 2 → Phase 3 → Phase 4 (조건부)
              |           |
          F10 선행     F7 deprecated
          (PRD 템플릿)  (선행 Sprint 0)
```

### 스테이크홀더 체크포인트

각 Phase 완료 후 간략 데모/상태 보고 1회 실시:
- Phase 1 완료: 대시보드 진행률 자동 표시 데모
- Phase 2 완료: audit-trail 기록 + 보고서 통계 섹션 데모
- Phase 3 완료: 학습 리포트 + 검색 + PRD 분해 데모
- Phase 4 완료: circuit breaker 동작 데모 (F11 포함/제외 결과 공유)