---
task_id: task-2031
type: context
scope: task
created: 2026-04-20
updated: 2026-04-20
status: in-progress
---

# 맥락 노트: task-2031

**task**: task-2031

---

## 결정 근거

### 3 Step Why 자문

**1st Why: "왜 이 설계가 필요한가?"**
- task-2030에서 봇이 코드 커밋 없이 .done 파일을 생성하여, 아무 실질적 변경 없이 작업 완료로 처리된 문제가 발생했다.
- 이를 방지하기 위해 .done 생성 직전에 git 커밋 존재를 검증하는 게이트가 필요하다.

**2nd Why: "왜 finish-task.sh에 직접 추가하는 것이 최선인가?"**
- finish-task.sh는 .done 생성의 유일한 경로(L1 3-Layer Defense)이므로, 여기에 게이트를 두면 우회가 불가능하다.
- qc_verify.py에도 추가하면 이중 검증(QC 단계 + .done 직전)으로 더욱 안전하다.
- 대안: qc_verify.py에만 추가 → 기각 이유: QC가 PASS 후 finish-task.sh에서 .done 생성까지 간에 다른 문제 가능

**3rd Why: "왜 qc_verify.py에도 추가하고 finish-task.sh에도 추가하는 이중 검증이 나은가?"**
- QC 단계에서 먼저 감지하면 팀원이 즉시 수정 가능 (빠른 피드백)
- finish-task.sh에서 최종 차단하면 QC를 우회하더라도 방어 (최후 방어선)
- 비용이 낮음: git log/diff 명령은 밀리초 단위로 실행되며, 추가 외부 의존성 없음

### non-code task SKIP 판별 설계
- task 파일에서 "코드 수정 없음", "문서만", "문서 업데이트만", "리서치만" 키워드를 grep으로 판별
- 매치 시 git 게이트를 SKIP하여 문서/리서치 작업이 불필요하게 차단되지 않도록 함

## 참조 자료

- 현재 finish-task.sh: `scripts/finish-task.sh`
- qc_verify.py: `teams/shared/qc_verify.py`
- verifiers 디렉토리: `teams/shared/verifiers/`
- task-2030 (원인 사건): `memory/tasks/task-2030.md`

## 주의사항

- finish-task.sh의 기존 멱등성 구조(qc-done, merge-done)를 훼손하지 않을 것
- git 게이트는 QC(Step 1) 이후, .done 생성(Step 3) 직전에 위치시킬 것
- PROJ_DIR 결정 시 worktree에서도 올바르게 동작하도록 git rev-parse --show-toplevel 사용