---
task_id: task-2364
type: plan
scope: task
created: 2026-05-02
updated: 2026-05-02
status: completed
---

# 계획서: task-2364 — 봇 Capability Matrix + Scope Guard (P0)

**task**: task-2364
**목표**: 봇이 task scope 밖 파일/리소스를 수정하지 못하도록 시스템 레벨 가드 도입 (`allowed_resources` 표준화 + dispatch 사전 차단 + finish-task 사후 검증).
**승인**: 제이회장 2026-05-02 "옵션 A — 미팅 재진행 후 합의안 진행"
**근거**: `memory/meetings/2026-05-02-bot-anu-automation-safety.md` (8 페르소나 만장일치)

---

## 목표

task-2360 사고(codegraph cron `CC712188` scope-out 삭제) 시뮬레이션을 **시스템 레벨에서 차단**한다.
- task 파일 inline YAML `allowed_resources` 스펙 표준화
- dispatch.py가 capability 미명시 task 거부 (점진적 호환: `--allow-no-scope` 플래그)
- dispatch.py가 task 파일 파싱 직후 **immutable capability snapshot**을 `memory/capabilities/{task_id}.json`에 저장 (Codex 지적 반영: mutable task 파일 self-bypass 차단)
- task-scope-guard.sh가 **snapshot 파일** vs git diff 매칭 → 위반 시 exit 1 + `.scope-violation.json`
- finish-task.sh가 **머지 직전** scope-guard 호출 (Codex 지적 반영: post-merge 검증은 이미 늦음) → 위반 시 머지 차단 + .escalate + exit 1
- P0 범위는 **paths + forbidden_paths 강제만** (Codex 지적 반영: commands enforcement는 P1으로 이연. 스키마는 표시만)

## 범위

### 포함 (P0 본 task)
1. capability schema (paths/forbidden_paths/commands/merge_policy/ttl_hours) — task 파일 inline YAML 결정
2. `scripts/task-scope-guard.sh` PoC (1주 운영 후 본 운영 결정)
3. `dispatch.py` capability 검증 함수 추가 (검증 1개 함수만, 기존 흐름 보존)
4. `scripts/finish-task.sh` scope-check 훅 추가 (.done 생성 직전, QC 게이트 직후)
5. 시스템 3문서: `memory/plans/bot-capability-system/{plan,context-notes,checklist}.md`
6. 스펙 문서: `memory/specs/bot-capability-model.md`
7. `CLAUDE.md`에 위임 완결성 5대 규칙 항목 추가
8. `memory/capabilities/.gitkeep` 디렉토리 마커

### 제외 (P1+ 후속 task)
- Tiered Auto-Merge / Audit Log / Health Probe (P1)
- Telegram inline button + Daily Digest (P2)
- Dashboard 권한/사고 시각화 (P3)
- branch protection / 머지 큐 (인프라 별도)

## 위임 계획

- Phase 1 (설계 + 3문서): **팀장(이참나)** 직접 — 설계 정합성 책임
- Phase 2-A (task-scope-guard.sh PoC): **쿠쿨칸(백엔드)** — bash 스크립트 + Python glob 매칭
- Phase 2-B (dispatch.py capability 검증 함수): **쿠쿨칸(백엔드)** — argparse + parse 함수 1개 추가
- Phase 2-C (finish-task.sh 훅 + memory/capabilities 디렉토리): **쿠쿨칸(백엔드)** — 기존 훅 패턴 차용
- Phase 3 (테스트 + 시뮬레이션): **카마소츠(테스터)** — task-2360 사고 재현 + 정상 흐름 + legacy 호환
- Phase 4 (CLAUDE.md + 통합 검증): **팀장 직접** + 마아트 독립 검증

## 검증 기준

- 시뮬레이션 차단: `bash scripts/task-scope-guard.sh task-fixture-violation /tmp/diff.txt` → exit 1 + `.scope-violation.json` 존재
- 정상 흐름: `bash scripts/task-scope-guard.sh task-fixture-ok /tmp/diff.txt` → exit 0
- legacy 호환: capability 없는 task → `--allow-no-scope` 플래그 시 통과 + 경고 로그
- dispatch 거부: 신규 task 파일 capability 미명시 → 거부 + 명확한 에러
- 회귀 안전: 기존 task-2360/2361/2362 흐름 영향 없음 (pytest PASS)
- finish-task 통합: scope 위반 task → .done 생성 차단 + .escalate 발생 확인

## 3 Step Why

- **1st Why**: 왜 capability matrix가 필요한가? → CLAUDE.md 텍스트 룰만으로는 봇의 자율 판단 오작동(task-2360)을 막을 수 없음. **시스템 레벨 hard wall** 필요.
- **2nd Why**: 왜 task 파일 inline YAML이 최선인가? → 단순성. 별도 `memory/capabilities/{task_id}.json` 유지 시 task 파일과 capability 동기화 비용 발생. inline YAML은 task 정의와 capability를 단일 source of truth로 통합. (대안: 별도 JSON → 동기화 부담 / 다른 대안: 환경변수 → ttl/glob 표현 한계)
- **3rd Why**: 왜 dispatch + finish 이중 검증인가? → 사전 차단(dispatch 거부)은 작업 시작 자체를 막고, 사후 검증(finish-task scope-check)은 supply-chain attack 또는 sub-agent 변조 케이스 방어. 단일 게이트는 우회 가능 (예: task 파일 직접 편집). 다층 방어가 표준.

A→B→C 일관성: 텍스트 룰 한계 → 단일 source 우선 → 다층 방어 (정합성 OK)