---
project: bot-capability-system
type: plan
scope: system
created: 2026-05-02
updated: 2026-05-02
status: P0-completed (P1-P3 pending)
owner: anu (의사결정자) / dev7 (이참나, P0 위임)
---

# 봇 Capability 시스템 — 전체 설계

## 목표

봇(개발팀 8개 + 마케팅/디자인 등)이 task scope 밖 리소스를 변경하지 못하도록
**시스템 레벨 다층 방어**를 구축한다.

CLAUDE.md "Surgical Changes" 텍스트 룰만으로는 봇 자율 판단 오작동을 막지 못함이
task-2360 사고(codegraph cron `CC712188` scope-out 삭제)에서 입증됨.

## 핵심 원칙

1. **Hard Wall**: capability matrix 미명시 → 작업 거부 (텍스트 룰 → 코드 가드 승격)
2. **Tiered Auto-Merge**: Lv 기반 + scope/diff 크기 + 보호 경로 미포함 차등 적용
3. **Post-Merge Safety Net**: auto revert + audit log + circuit breaker
4. **다층 방어 (5단계)**: dispatch → task-scope-guard → finish-task → branch protection → audit

## 아키텍처 — 다층 방어

```
┌─────────────────────────────────────────────────────────────┐
│ Layer 1 — dispatch.py 사전 차단 + Capability Snapshot        │
│   * task 파일에 allowed_resources 미명시 → 거부             │
│   * --allow-no-scope 플래그로만 우회 (legacy)               │
│   * dispatch 시점 immutable snapshot:                        │
│     memory/capabilities/{task_id}.json (sha256 hash 포함)   │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ Layer 2 — task-scope-guard.sh 런타임 검증 (선택)            │
│   * 봇이 파일 수정 직전 호출 (1주 PoC, 향후 wrapper)        │
│   * snapshot 파일을 진실의 원본으로 사용 (mutable task 미사용)│
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ Layer 3 — finish-task.sh 사전 검증 (머지 직전)              │
│   * QC 통과 → scope-guard 검증 → 머지 (Codex 지적 반영)     │
│   * git diff main..HEAD (worktree 브랜치, 머지 전)          │
│   * 위반 시 머지 차단 + .escalate + 회장 알림 + exit 1      │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ Layer 4 — GitHub Branch Protection (P1+)                     │
│   * 필수 리뷰어, 상태 체크, force-push 차단                 │
└─────────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────────┐
│ Layer 5 — Audit Log + Daily Digest (P1+)                     │
│   * memory/audit/auto-merge.log append-only                  │
│   * 매일 09:00 회장 다이제스트 카드                          │
└─────────────────────────────────────────────────────────────┘
```

## Capability 스키마

```yaml
allowed_resources:
  paths:           # glob 화이트리스트 (작업 가능 파일)
    - "scripts/finish-task.sh"
    - "memory/plans/bot-capability-system/**"
  forbidden_paths: # 보호 경로 블랙리스트 (paths에 일치해도 차단)
    - "memory/events/*.cron-*"
    - ".github/**"
  commands:        # 실행 가능 명령 (선택, P1 시점에서 enforce)
    - "pytest"
    - "python3 -m py_compile"
  merge_policy: "auto" | "tiered" | "manual"
  ttl_hours: 48    # capability 만료 (긴 task 안전판)
```

## Tiered Auto-Merge (P1)

| Tier | 조건 | 처리 |
|------|------|------|
| Tier 1 (자동) | Lv.0-1 + 빌드 PASS + 보호 경로 미포함 + 단일 task + diff < 300 LOC + scope 일치 | 즉시 머지, 일일 다이제스트만 |
| Tier 2 (1-tap) | Lv.2 / 다중 파일 / 의존성 변경 | Telegram inline button (5분 TTL) |
| Tier 3 (필수 승인) | Lv.3+ / CLAUDE.md, bot_settings, memory, .github / 프로덕션 / 외부 키 | 회장 명시 승인 |

## Phase 분할 (P0 → P3)

- **P0 (task-2364, 본 task)**: capability schema 표준화 + scope guard + 시스템 3문서
- **P1 (task-XXX)**: Tiered auto-merge + audit log + post-merge health probe + circuit breaker
- **P2 (task-XXX)**: Telegram inline button + Daily Digest + 랜덤 10% 인간 검토
- **P3 (task-XXX)**: Dashboard 권한/사고 시각화

## 검증 시나리오

1. **task-2360 재현 시뮬레이션**: 가상 task `allowed_resources.paths: ["scripts/finish-task.sh"]` + 봇이 `cron_settings.json` 수정 → scope-guard exit 1 + .escalate
2. **정상 흐름**: scope 내 변경 → 통과
3. **legacy 호환**: capability 미명시 task → `--allow-no-scope` 통과 + 경고
4. **dispatch 거부**: 신규 task capability 미명시 → 거부 + 명확한 에러
5. **회귀 안전**: 기존 task 흐름 무영향