# task-123.1 보고서: '하기로 한 일을 잊어버리는 문제' 3계층 방어 구조 구현

**작성자**: 헤르메스 (개발1팀장)
**작성일**: 2026-03-02
**선행 분석**: task-119.1 보고서 (memory/reports/task-119.1.md)

---

## 1. 작업 내용

task-119.1 분석 보고서에서 권고한 3계층 방어 구조를 코드로 구현하였다.

- **계층 1 (예방)**: `pending_actions.py` 모듈 신설 + `dispatch.py`에 `followup_action` 파라미터 추가
  - 아누가 dispatch 시 `--followup "후속 작업 설명"`으로 약속을 시스템에 영속화
  - pending-actions.json에 약속이 기록되어 세션 종료 후에도 소실되지 않음

- **계층 2 (전달)**: `team_prompts.py`의 완료 통보 프롬프트 강화
  - 팀장이 아누에게 완료 통보할 때, cron 프롬프트에 `pending_actions.py pending` 실행 지시 자동 삽입
  - 세션B(통보 세션)가 미이행 약속을 자동으로 인지하고 처리하도록 유도

- **계층 3 (확인)**: `user-prompt-submit.sh` 아누 hook 강화
  - 아누의 모든 세션 시작 시 미이행 약속이 있으면 경고 메시지 자동 주입
  - "약속을 안 지키려면 의도적으로 무시해야 함" — 기본값을 이행으로 설정

---

## 2. 생성/수정 파일 목록

- **신규 생성**:
  - `memory/pending_actions.py` — Pending Actions Manager (CRUD + CLI)
  - `memory/pending-actions.json` — 약속 데이터 저장소 (자동 생성)
  - `teams/dev1/plan-task-123.1.md` — 작업 계획서
  - `teams/dev1/test_task_123_1.py` — 통합 테스트 (17개 케이스)
  - `memory/reports/task-123.1.md` — 본 보고서

- **수정**:
  - `dispatch.py` — followup_action 파라미터 추가 + PendingActions import + CLI --followup 옵션
  - `prompts/team_prompts.py` — _build_direct_prompt() 209행, _build_glm_prompt() 283행의 cron 통보 프롬프트에 pending-actions 확인 지시 삽입
  - `~/.claude/hooks/user-prompt-submit.sh` — anu) 케이스에 pending-actions 체크 블록 추가 (70~80행)

---

## 3. 변경 사유 및 대안 검토

- **pending_actions.py 신설**: event-queue.json에 followup 필드 추가하는 대안 검토 → 기각. 이유: event-queue는 FIFO 이벤트 큐이고, pending-actions는 약속 추적 레지스트리. 관심사 분리 원칙에 따라 별도 파일/모듈로 구현.
- **dispatch.py import 방식**: importlib.import_module("memory.pending_actions") 초기 시도 → memory/__init__.py 부재로 실패 → importlib.util.spec_from_file_location으로 변경. memory/ 디렉토리는 패키지가 아닌 데이터/스크립트 디렉토리이므로 __init__.py를 추가하지 않고 파일 경로 기반 import 사용.
- **hook에서 PENDING_LIST 직접 출력**: jq로 파싱하여 깔끔하게 출력하는 대안 검토 → 기각. 이유: jq 의존성 최소화 + python3 CLI 출력만으로 충분히 가독성 확보.

---

## 4. 테스트 결과

```
======= 17 passed in 0.13s =======
```

17개 테스트 전부 PASS:
- PendingActions 단위 테스트 10개: init, add, id_increment, resolve, resolve_nonexistent, count, list_with_resolved, list_without_resolved, backup_recovery, empty_description
- dispatch.py 연동 테스트 3개: import 확인, followup_action 파라미터 확인, CLI --followup 옵션 확인
- team_prompts.py 프롬프트 검증 2개: direct/glm 프롬프트에 pending-actions 문구 포함 확인
- Hook 구문 검증 2개: bash -n 통과, pending-actions 관련 문자열 포함 확인

---

## 5. 버그 유무

버그 없음.

---

## 6. 셀프 QC

**1. 이 변경이 다른 파일에 영향을 미치는가?**
dispatch.py의 dispatch() 시그니처에 followup_action 파라미터가 추가되었으나, 기본값이 None이므로 기존 호출자에 영향 없음. team_prompts.py의 프롬프트 변경은 문자열 끝에 추가만 하므로 기존 구조 유지. hook의 새 블록은 기존 블록 사이에 독립적으로 삽입되어 기존 기능에 영향 없음.

**2. 이 로직의 엣지 케이스는 무엇인가?**
- pending-actions.json이 깨진 경우: .bak 백업 복구 로직으로 처리 (테스트 통과)
- pending-actions.json이 삭제된 경우: _ensure_actions_file()에서 자동 재생성
- hook에서 python3 실행 실패: `|| echo "0"` 폴백으로 기존 기능 영향 없음
- 빈 followup_action ("") 전달: 빈 문자열이면 falsy로 평가되어 기록되지 않음

**3. 이 구현이 작업 지시와 정확히 일치하는가?**
작업 지시: "3계층 방어 구조 문서화+코드화. 수정 대상: dispatch.py, team_prompts.py, user-prompt-submit.sh + 신규 pending-actions.py, pending-actions.json"
→ 모든 수정 대상 파일을 수정하고, 신규 파일 2개를 생성함. 일치.

**4. 에러 처리와 보안은 확인했는가?**
- 에러 처리: fcntl 파일 락, atomic write, .bak 백업/복구 모두 구현. hook 실패 시 폴백 처리.
- 보안: pending-actions.json에 민감 정보 없음 (약속 설명 + task ID만). 파일 권한은 기본 umask 적용.

**5. 테스트가 모든 경로를 커버하는가?**
PendingActions의 모든 공개 API (add, resolve, get_pending, count_pending, list_all), 에러 경로 (nonexistent resolve, backup recovery), dispatch 연동 (import, 파라미터, CLI), 프롬프트 검증 (direct/glm), hook 검증 (구문/내용) 모두 커버. count = 0일 때 hook이 경고를 출력하지 않는 경로는 bash의 조건문 구조상 자명하므로 별도 테스트 불필요.

---

## 7. 팀장 검토 결과

- **불칸 (백엔드)**: 1차 검토 통과, 수정 사항 1건. dispatch.py의 importlib.import_module 방식이 memory/__init__.py 부재로 실패하여 importlib.util.spec_from_file_location 방식으로 팀장이 직접 수정함. pending_actions.py 모듈은 event-queue.py 패턴을 정확히 준수하여 품질 양호.
- **이리스 (프론트엔드)**: 1차 검토 통과, 수정 사항 없음. team_prompts.py의 cron 프롬프트와 user-prompt-submit.sh의 hook 블록 모두 기존 구조를 유지하면서 최소한의 변경만 적용. 기존 기능에 영향 없음 확인.
- **아르고스 (테스터)**: 1차 검토 통과, 수정 사항 없음. 17개 테스트 전부 PASS. PendingActions CRUD, dispatch 연동, 프롬프트 검증, hook 검증 모두 포괄.

---

## 8. 비고

- task-119.1의 방안 3 (dispatch 체이닝 / 자동 연쇄 실행)은 중기 과제로 남겨둠. 현재 구현은 계층 1~3의 "기록 + 전달 + 확인" 방어선으로 구성.
- pending-actions.json에 resolved 목록이 무한히 쌓이는 문제는 향후 정리 스크립트로 대응 가능 (당장은 규모 미미).
- 아누가 dispatch 시 --followup 옵션을 사용하는 습관을 형성하는 것이 이 시스템의 핵심. 계층 3(hook 경고)이 이를 상기시키는 역할을 수행.