---
task_id: task-43.0
type: plan
scope: system
project: anu-guide-system
created: 2026-03-02
updated: 2026-04-24
status: active
---

# 계획서: 아누 가이드 시스템 구축

**task**: task-43.0
**목표**: 아누 가이드 v1.1을 실현하는 시스템 인프라 구축 (즉시조치 ~ Phase 4)
**승인**: 제이회장님 2026-03-02 "시작!" 승인 / Phase 4: 2026-04-24 승인
**근거**: 
- Phase 0~3: Agent 미팅 (`memory/meetings/2026-03-02-anu-guide-gap-analysis.md`)
- Phase 4: Agent 미팅 13명 전원합의 (`memory/meetings/2026-04-24-dispatch-quality-automation.md`)

---

## 범위

### 즉시조치 — 보안
A. dispatch.py BOT_KEYS 하드코딩 폴백 제거 → 환경변수 전용
B. 핵심 파일 권한 640 강화 (dispatch.py, task-timer.py, bot_settings.json 등)

### Phase 0 — hooks 인프라
A. ~/.claude/hooks/ 디렉토리 생성
B. ~/.claude/settings.json에 hooks 설정 추가
C. hooks/user-prompt-submit.sh — 매뉴얼 자동 주입 (키워드/의도 감지 → 스킬 로드)
D. hooks/post-tool-use.sh — Audit Trail (Write/Edit 감지 → JSONL 로그)
E. hooks/lib/detect-bot.sh — cwd 기반 봇 식별
F. /tmp/ 서버 로그 → memory/logs/ 영구 경로 이전

### Phase 1 — 작업 기억 + skills
A. 3문서 스키마 확정 (YAML 프론트매터 규약)
B. .claude/skills/agent-meeting.md — 미팅 진행 스킬
C. .claude/skills/3docs-create.md — 3문서 자동 생성 스킬
D. .claude/skills/nuclear-approval.md — 핵미사일 승인 스킬

### 제외 (Phase 2 이후)
- 마아트 독립 봇 구성
- QC 자동 트리거
- 런타임 검증
- 전체 6단계 파이프라인

### Phase 4 — 위임 작업 품질 자동화 (2026-04-24 추가)

> **제이회장님 지시**: "아누가 잊어먹어도 실제로 코드가 자동으로 진행할 수 있게 해야함"
> **미팅**: 13명 전원합의 5사이클 (`memory/meetings/2026-04-24-dispatch-quality-automation.md`)

3대 루트 원인 해결:
- RC-1: 영향 범위 전수조사 누락 (task-2142 사례)
- RC-2: 연쇄 이슈 직렬 발견 (task-2143/2144 사례)
- RC-3: 실동작 미검증 (task-2140 사례)

#### Phase 4-1A: 즉시 FAIL 게이트 (신규 파일 + 수정)
- `teams/shared/verifiers/l1_smoketest_check.py` 수정 — "확인 불가" 패턴 FAIL + EXEMPT 조건
- `dispatch.py` 수정 — `_auto_inject_affected_files()` + `_auto_generate_goal_assertions()` 추가
- `scripts/finish-task.sh` 수정 — Step 2.12 Goal Assertions Gate 추가

#### Phase 4-1B: WARN 모드 데이터 수집 (신규 파일)
- `scripts/impact_scanner.py` 신규 — 수정 파일 기반 역방향 영향 범위 스캔 (~200줄)
- `scripts/ci_preflight.sh` 신규 — 멀티 러너 CI 게이트 (~80줄)
- `config/gate-config.json` 신규 — 게이트 설정 중앙 관리 (~40줄)
- `scripts/finish-task.sh` 수정 — Step 2.6(Impact), 2.6.5(CI), 2.11(Unresolved) 추가

#### Phase 4-2: WARN → FAIL 승격 (2주 후)
- false positive < 10% 확인 후 Phase 1B 게이트를 FAIL로 전환
- gate-config.json의 mode: "warn" → "fail" 변경

### 제외 (향후)
- Container-per-Session (장기 과제)
- SQLite 상태 이관 (별도 프로젝트)
- NLP 기반 spec_conformance (연구 필요)
- Visual Regression (baseline 관리 시스템 필요)

---

## 위임 계획

### Phase 0~3 (완료)
- 즉시조치: **1팀 (헤르메스)** — 보안 패치 ✅
- Phase 0: **1팀 (헤르메스)** — hooks 구현 ✅
- Phase 1: **2팀 (오딘)** — skills 설계 ✅
- Phase 3: **2팀 (오딘)** — 파이프라인 통합 ✅

### Phase 4 (신규 — 병렬 위임)

| 항목 | 담당 팀 | 파일 | 예상 변경량 | 우선순위 |
|------|---------|------|------------|----------|
| C-FINAL-3 l1_smoketest 강화 | 7팀 (이잠나) | l1_smoketest_check.py | +30줄 | P1 (Phase 4-1A) |
| C-FINAL-1 impact_scanner | 1팀 (헤르메스) | scripts/impact_scanner.py | ~200줄 신규 | P1 (Phase 4-1B) |
| C-FINAL-4 dispatch.py 확장 | 2팀 (오딘) | dispatch.py | +80줄 (2함수) | P1 |
| C-FINAL-5 finish-task.sh 게이트 | 3팀 (다그다) | scripts/finish-task.sh | +100줄 (4 step) | P1 |
| C-FINAL-2 ci_preflight | 4팀 (비슈누) | scripts/ci_preflight.sh | ~80줄 신규 | P2 (Phase 4-1B) |
| C-FINAL-6 gate-config | 5팀 (엔키) | config/gate-config.json | ~40줄 신규 | P2 |
| C-FINAL-7 .done 포맷 | 3팀 (다그다) | finish-task.sh Step 3 | +10줄 | P2 |
| 통합 테스트 | composite (로키+마아트) | tests/ | 8 케이스 | P1 |

## 검증 기준

### Phase 0~3
- 즉시조치: `grep -r "BOT_KEYS" dispatch.py` → 하드코딩 없음 ✅
- Phase 0: hooks 실제 동작 확인 ✅
- Phase 1: skills/ 파일 존재 + 실제 로드 ✅
- Phase 3: 파이프라인 6단계 정의 ✅

### Phase 4
- l1_smoketest: "UI 직접 확인 불가" 포함 보고서 → QC FAIL 반환
- impact_scanner: 수정 파일의 심볼 역추적 → 누락 파일 WARNING
- ci_preflight: pytest + tsc + vitest 멀티 러너 → 전체 PASS/FAIL
- goal_assertions: task 파일 완료 기준 자동 실행 → 전부 통과 시 .done
- dispatch.py: 백틱 코드 토큰 자동 grep → affected_files 자동 주입
- gate-config.json: 게이트 ON/OFF + mode(warn/fail) + 임계치 중앙 관리
- 통합: 8개 핵심 시나리오 테스트 전체 PASS

## Phase 6 — 완전자동 머지 enforcement 시스템 (2026-05-04~05 추가, **task-2452에서 정정**)

> 출처: `memory/reports/task-2440.md`, `task-2449.md`, `task-2451.md` + GitHub raw API 직접 확인.
> 외부 조언자용 문서: `memory/specs/anu-system-spec-for-external-advisor.md` **V3** §0/9.1 (task-2452 정정 반영).
>
> **[정정 2026-05-05 task-2452]** Phase 6 본문에 `auto_merge.py classify_tier()` 자동 머지 표현이 있으나, 회장 직접 진단 + raw 검증 결과 **사실상 폐기** (logs/auto_merge.log 24MB 중 머지 0건, 모두 BLOCKED). 머지의 진짜 경로는:
>  - **A) `finish-task.sh` Step 2** → `worktree_manager.py finish --action auto` (현재 hot path).
>  - **B) `taskctl.py merge`** → `gh pr merge` 직접 호출.
>  - **C) GitHub `merge_group` + Ruleset(active, id=15896715)** → 7개 required checks + server-side 직렬 머지.
> Phase 7 (task-2452)에서 auto_merge.py 공식 폐기 처리 (cron 제거 + DEPRECATED 마커, 30일 유예 후 삭제).

### 범위 (Phase 6)

#### Phase 6-1: 봇 권한 내 enforcement 자산 (→ task-2440, dev1팀 헤르메스, 완료)
- `scripts/lock_in_verify.py` (AST 기반 First-line 가드)
- `scripts/gemini_review_gate.py` (Gemini Review를 GitHub check run으로 강제)
- `scripts/gemini_feedback_loop.py` (3회 초과 시 `human_review_required` 라벨)
- `.github/workflows/ci.yml` 7-step required checks: cancel-kill-switch, qc-check, hidden-path-audit, lock-in-check, merge-safety-check, gemini-review-gate, ci/guard
- `merge_group` 트리거 (GitHub Merge Queue 직렬 처리)
- 회귀 테스트 21건 PASS

#### Phase 6-2: server-side enforcement (→ 회장 직접 처리, 2026-05-04 09:18 완료)
- 저장소 소유권: `JonghyukJeon` (개인, free) → `Jeon-Jonghyuk` Organization (team plan, private_repos 999,999)
- Ruleset 등록: id=15896715, name="main-protection", target=branch, **enforcement=active**
- 결과: 7개 required checks를 GitHub 서버 측에서 강제

#### Phase 6-3: 침투 테스트 (→ task-2449, 완료)
9 케이스 모두 차단/검증:
1. CANCELLED state 머지 시도
2. HUMAN_APPROVED 미달 머지
3. state 파일 checksum 변조
4. auto_merge.py 직접 호출 (TASKCTL_INVOKED 미설정)
5. 비정상 상태 전이 (CREATED → MERGED 직행)
6. `gh pr merge` 직접 호출 코드 검색 (0건)
7. pre-push hook의 main 거부
8. refspec 우회 (다른 브랜치 → origin/main)
9. bypass evidence 강제 기록 (회장 override)

#### Phase 6-4: 합격 매트릭스 검증 (→ task-2451, .done 미처리)
- 9 케이스 매트릭스 + 합격 A~G 판정
- gate_results: impact_scanner / ci_preflight / l1_smoketest / goal_assertions / unresolved_gate 모두 PASS
- 회장 추가 검증 대기 중

### 위임 계획 (Phase 6)

| 단계 | 담당 | 대상 | 상태 |
|------|------|------|------|
| 6-1 enforcement 자산 | dev1팀 헤르메스 | task-2440 | 완료 (PR #14 머지) |
| 6-2 org 전환 + Ruleset | 회장 직접 | GitHub Settings | 완료 (2026-05-04 09:18) |
| 6-3 침투 테스트 | composite (로키+마아트) | task-2449 | 완료 |
| 6-4 합격 매트릭스 | composite | task-2451 | .done (회장 검증 대기) |

### 검증 기준 (Phase 6)
- Ruleset enforcement=active 상태 유지 (`gh api repos/Jeon-Jonghyuk/dev_workspace/rulesets`)
- 7개 CI required checks 모두 GitHub Actions에 등록 + Ruleset에서 required로 지정
- merge_group 트리거 동작 (race 0건, GitHub API 직렬화 확인)
- ~~`auto_merge.py` Tier 분류: Tier 1 자동 머지 / Tier 2 1-tap 승인 / Tier 3 manual~~ → **[정정 task-2452]** auto_merge.py 폐기. 머지 hot path는 `finish-task.sh` → `worktree_manager.py finish --action auto`.
- 침투 테스트 9 케이스 raw 로그 보존
- task-2440 이전(`merge_policy=manual` 단일 표현)의 V1 문서 정정 → V2 외부 조언자용 문서 → **V3** (task-2452) 외부 조언자용 문서에 반영 완료

## Phase 7 — 신호등 sync 정정 + auto_merge.py 공식 폐기 (2026-05-05 task-2452)

> 출처: `memory/tasks/task-2452.md` (374줄), `memory/specs/traffic-light-sync-analysis-2026-05-05.md` (318줄)
> 회장 직접 진단 (2026-05-05): "오토 머지까지 다 되어야 작업이 정말 완성된 거고, 그 이후 finish-task.sh가 진행되니, 마지막에 신호등이 꺼지는 로직이어야 정상." + "실제 workflow 따라가보면 merge는 git을 통해 하는 걸로 되어있다."
> 한정승인: 회장 → 아누 → dev1팀 (4 Phase 일괄)

### 범위 (Phase 7)

#### Phase 7-1: auto_merge.py 공식 폐기 (Lv.1, dev1팀 헤르메스)
- crontab 매분 실행 라인 제거
- `scripts/auto_merge.py` 헤더 DEPRECATED 마커 + 30일 유예 안내
- `logs/auto_merge.log` (24MB) → `logs/auto_merge.log.archive-2026-05-05` rename + 빈 로그 새로 생성
- 30일 유예 후 (2026-06-04) 코드 자체 삭제 예정 (의존 테스트/lock_in_verify First-line guard 정리 후)

#### Phase 7-2: finish-task.sh 끝부분 신호등 통합 (Lv.2, dev1팀 헤르메스)
- Step 2.7 (`member-status.json idle 복원`)을 끝부분 마지막 Step (Step 2.99, .done 생성 직전)으로 이동
- 동일 Step에 `bot-activity.json idle 전환` 통합 (두 source 동시·동일 시점)
- composite 작업 `team_id=""` 케이스: `task-timers.json` `affected_teams` / `composite_teams` fallback

#### Phase 7-3: done-watcher.py fallback only로 강등 (Lv.2, dev1팀 헤르메스)
- `process_done_files()`: 30분 grace + `.merge-done` 마커 부재 조건일 때만 fallback idle (`[FALLBACK-IDLE]` 로그)
- `extract_team_from_done_file()`: `team_id=""` 빈 문자열 case에 `team` / `composite_teams[0]` fallback 보강

#### Phase 7-4: 4개 문서 일괄 정정 + 신호등 스펙 v2 (Lv.1, dev1팀 헤르메스)
- `memory/specs/anu-system-spec-for-external-advisor.md` V2 → **V3** (auto_merge 폐기 + 신호등 통합 + 부록 B 17번 마커 미상)
- `memory/specs/traffic-light-sync-analysis-2026-05-05.md` (auto_merge 마커 표현 정정 + 결함 3 원인 정정)
- `memory/specs/anu-system-spec.md` §6.10 정정 + 1.1.0 → **1.1.1** bump + changelog 추가
- `memory/specs/traffic-light-spec.md` v1 → **v2** (단일 책임 + 다단계 마커 시점 정의)
- `memory/plans/anu-guide-system/{plan,context-notes,checklist}.md` Phase 6 정정 + Phase 7 추가 (본 작업)

### 위임 계획 (Phase 7)

| 단계 | 담당 | 대상 | 상태 |
|------|------|------|------|
| 7-1 auto_merge 폐기 | dev1팀 헤르메스 | task-2452 | 완료 (cron 제거 + DEPRECATED + 로그 archive) |
| 7-2 finish-task.sh 통합 | dev1팀 헤르메스 | task-2452 | 완료 (Step 2.99 신규) |
| 7-3 done-watcher fallback | dev1팀 헤르메스 | task-2452 | 완료 (30분 grace + .merge-done 부재) |
| 7-4 4개 문서 정정 | dev1팀 헤르메스 | task-2452 | 완료 (V3 / 1.1.1 / v2 / Phase 7 추가) |

### 검증 기준 (Phase 7)
- `crontab -l | grep auto_merge` → 0건
- `head -15 scripts/auto_merge.py` → "DEPRECATED" 마커 첫 docstring
- `ls -lh logs/auto_merge.log` → 0~수 byte (cron 미실행 후)
- `bash -n scripts/finish-task.sh` → syntax OK + Step 2.99 (Phase 2 마커) 존재
- `python3 -m py_compile scripts/done-watcher.py` → exit 0 + `[FALLBACK-IDLE]` / `TRAFFIC_LIGHT_FALLBACK_GRACE_SECONDS` 마커 존재
- 4개 spec 문서에서 `[V3 정정]` / `[정정 2026-05-05 task-2452]` / `1.1.1` / `v2` 마커 grep 확인
- 시나리오 5.1 (정상 흐름): dummy task가 finish-task.sh 통과 → bot-activity.json `dev1` status=idle
- 시나리오 5.3 (auto_merge 폐기): crontab 0건 + 로그 0byte + DEPRECATED 마커