# Hermes Agent 학습 도입 — 최종 Phase (한정승인)

## 배경
- task-856.1 (Phase 1): 40개 항목 설계서 + 난이도 하 9개 + 중 8개 = 17개 모듈 구현
- task-860.1 (Phase 2): QC 수정 + 리팩터링 + 기존 코드 통합 + 고난이도 7개 = 추가 16개 모듈
- 현재: utils/ 37개 모듈, 634+ 테스트 PASS
- 남은 미구현 15개 중 가치 높은 것만 선별 구현 → 전체 통합 검증

## 한정승인 — 자율 체이닝으로 Phase A → Phase B 순차 수행

---

### Phase A: 미구현 15개 중 가치 높은 7개 선별 구현

**선별 기준**: 우리 시스템(dispatch.py, orchestrator.py, chain_manager.py)에 실질적 가치가 있는 것

#### 구현 대상 (7개)

**1. M-03. 스마트 모델 라우팅**
- 설계서 위치: `memory/specs/hermes-adoption-plan.md` M-03 섹션
- 핵심: 작업 복잡도에 따라 haiku/sonnet/opus 자동 선택
- 우리 시스템 가치: dispatch 시 팀별 최적 모델 자동 배정. 토큰 비용 절감.

**2. M-05. @ 참조 시스템**
- 설계서: M-05 섹션
- 핵심: `@파일경로`로 컨텍스트에 파일 포함
- 가치: dispatch 지시서에서 `@memory/specs/xxx.md` 식으로 참조 가능

**3. M-08. 체크포인트 관리**
- 설계서: M-08 섹션
- 핵심: 긴 작업의 중간 상태 저장/복원
- 가치: 팀 세션이 죽어도 이어갈 수 있음. Phase 분리 원칙 강화.

**4. M-18. 패치 파서 (unified diff)**
- 설계서: M-18 섹션
- 핵심: unified diff 형식의 패치를 파싱하여 적용
- 가치: 코드 리뷰/머지 자동화에 활용

**5. M-21. Persistent Shell (상태 유지 셸)**
- 설계서: M-21 섹션
- 핵심: 셸 세션의 환경변수/cwd 상태 유지
- 가치: 팀 작업 시 venv 활성화 등 환경 유지

**6. M-24. Fake 테스트 패턴**
- 설계서: M-24 섹션
- 핵심: 외부 API 의존 테스트를 위한 Fake/Mock 패턴
- 가치: API 호출 없이 안정적 테스트 가능. 비용 절감.

**7. M-25. 선택적 의존성 그룹 패턴**
- 설계서: M-25 섹션
- 핵심: extras_require 패턴으로 선택적 의존성 관리
- 가치: 모듈화 원칙 강화. 불필요한 의존성 제거.

#### 미선별 (8개 — 현재 우리 시스템에 불필요하거나 과도)
- M-09 Honcho: 외부 SaaS 의존, 현재 불필요
- M-10 MoA 앙상블: 우리는 dispatch로 이미 멀티에이전트 운영
- M-11 스킬 허브: agentskills.io 외부 의존
- M-12 도구 레지스트리: MCP로 이미 커버
- M-13 터미널 다중 환경: Docker/SSH 현재 불필요
- M-14 코드 실행 샌드박스: 보안팀(로키) 영역
- M-15 STT: 음성 입력 현재 불필요
- M-23 CI/CD: 별도 프로젝트로 진행 예정

#### 구현 원칙
- 설계서(`memory/specs/hermes-adoption-plan.md`)의 각 항목 상세 설계를 참조
- 200줄 이하, 초과 시 분할
- pytest 테스트 필수 (각 모듈당 최소 15개)
- pyright 에러 0건
- 기존 모듈과 충돌 없이 독립 구현

---

### Phase B: 전체 통합 검증 + 실전 적용

Phase A 완료 후 수행.

#### B-1. 전체 모듈 통합 테스트
- `pytest` 전체 실행 → 0 failures 확인
- pyright 전체 실행 → 0 errors 확인
- 모듈 간 의존성 체크 (순환 참조 없는지)

#### B-2. 기존 코드 통합 (Phase A 신규 모듈)
- M-03 스마트 모델 라우팅 → dispatch.py에 통합
- M-08 체크포인트 → orchestrator.py에 통합
- M-18 패치 파서 → 코드 리뷰 워크플로우에 연결
- M-21 Persistent Shell → 팀 워크플로우에 연결
- 모든 통합은 try/except ImportError (backward compatible)

#### B-3. 실전 시뮬레이션
- dispatch.py로 테스트 작업 위임 시 모든 보안 모듈 동작 확인:
  - redact → 로그에서 API 키 마스킹 확인
  - injection_guard → 악성 프롬프트 탐지 확인
  - approval → 위험 명령 경고 확인
  - audit_logger → audit-trail.jsonl 기록 확인
- orchestrator.py 실행 시:
  - config_loader → system.yaml 로드 확인
  - interrupt → 안전 종료 확인
  - memory_manager → 상태 스냅샷 확인

#### B-4. 최종 보고서
- 전체 모듈 목록 (구현 완료 / 미선별)
- Health Score 최종 측정
- 통합 테스트 결과
- 실전 시뮬레이션 결과
- 남은 미선별 8개에 대한 향후 검토 의견

## 산출물
- Phase A: 7개 신규 모듈 + 테스트
- Phase B: 통합 테스트 결과 + 실전 시뮬레이션 로그
- 최종 보고서: `/home/jay/workspace/memory/reports/task-{task_id}.md`

## 주의사항
- dispatch.py, orchestrator.py, chain_manager.py 수정 시 기존 테스트 반드시 통과 확인
- 다른 팀 파일 건드리지 말 것
- 200줄 제한 준수
- git checkout은 해당 파일만 (전체 stash/reset 금지)