# AX Copilot 통합 로드맵 (전면 재작성)

## 1. 보존 이력 (요약만 유지)
- v1.5.x: 에이전트/런처 핵심 기능 확장, MCP/스킬/검증 체계 도입.
- v1.6.0: 문서 생성 및 업무 자동화 도구군 확장.
- v1.7.0~v1.7.2: Plan Mode, 병렬 도구, 검증 게이트 및 안정화 강화.

## 2. 재작성 목표
- claw-code 수준의 실행 신뢰성, 세션 내구성, 결과 품질 확보.
- AX Copilot 고유 제약(사내 운영모드, WPF UX, 로컬 우선)을 유지한 동등 품질 구현.

## 3. 마일스톤

| 마일스톤 | 참조 대상 (`claw-code`) | AX 적용 위치 | 완료 조건 | 품질 판정 시나리오 |
|---|---|---|---|---|
| M1 (v1.7.3) Hook 계약 정식화 | `src/utils/hooks.ts`, `src/utils/hooks/hookEvents.ts`, `src/utils/permissions/PermissionUpdate.ts` | `src/AxCopilot/Services/Agent/AgentHookRunner.cs`, `src/AxCopilot/Services/Agent/AgentLoopService.cs`, `src/AxCopilot/Models/AppSettings.cs`, `src/AxCopilot/ViewModels/SettingsViewModel.cs`, `src/AxCopilot/Views/SettingsWindow.xaml` | Hook 출력 계약(`updatedInput`, `updatedPermissions`, `additionalContext`) 반영. 설정값-실행코드-UI 동시 반영. | JSON 훅/텍스트 훅 혼합 환경에서 실행 품질과 하위호환 유지 확인. |
| M2 (v1.7.4~v1.7.5) 세션/로그 내구성 | `src/utils/plans.ts`, `src/utils/sessionStorage.ts` | `src/AxCopilot/Services/ChatSessionStateService.cs`, `src/AxCopilot/Services/TaskRunService.cs`, `src/AxCopilot/Services/TaskRunStore.cs`, `src/AxCopilot/Views/ChatWindow.xaml.cs`, `src/AxCopilot/Models/ChatModels.cs` | Plan/Run 상태 영속화. 이벤트 로그 표준화 및 replay 안정성 확보. | 앱 재시작/강제종료 후 동일 세션 재개 시 상태/이력 불일치 0건. |
| M3 (v1.7.6) 도구 선택/복구 안정화 | `src/commands.ts`, `src/Tool.ts`, `src/query.ts` | `src/AxCopilot/Services/Agent/AgentLoopService.cs`, `src/AxCopilot/Services/Agent/AgentLoopParallelExecution.cs`, `src/AxCopilot/Services/LlmService.ToolUse.cs` | 도구 선택 실패 루프 억제. 실패 유형별 복구 흐름 정형화. | 오타/비활성/별칭 도구 요청이 반복 실패 없이 정상 경로로 수렴하는지 확인. |
| M4 (v1.8.0) 품질 게이트 최종 정렬 | `src/query.ts`, `src/QueryEngine.ts`, `src/utils/sessionStorage.ts` | `src/AxCopilot/Services/Agent/AgentLoopService.cs`, `src/AxCopilot/Services/Agent/AgentLoopTransitions.Execution.cs`, `src/AxCopilot/Services/Agent/AgentLoopTransitions.cs` | 증거 기반 완료 판정 고정. 내부 벤치마크에서 claw-code 동급 품질 달성. | 코드수정/문서생성/권한거부/복구 혼합 시나리오에서 조기완료 없이 근거 기반 종료 확인. |

## 4. 측정 지표
- 반복 실패 루프 발생률.
- 세션 재개 성공률.
- 완료 응답 근거 누락률.
- 빌드/테스트 통과율.

## 5. 운영 원칙
- `internal` 모드: 외부 유출 경로 차단 우선.
- 신규 기능은 반드시 설정값 연결 + 실제 동작 반영.
- 문서 마스터는 `.md`, HTML은 요청 시만 갱신.

## 6. 즉시 실행 백로그
1. Hook 계약 확장 마무리 및 회귀 테스트.
2. 세션 복원 경계조건 테스트 세트 추가.
3. 이벤트 로그 스키마 고정 및 분석 리포트 템플릿 정리.

## 7. 2026-04-03 실행 증적 동기화 (M4 포함)
- 기준 시점: 2026-04-03.
- 테스트: `dotnet test` 371/371 통과.
- M1 증적: Hook 계약 필드(`updatedInput`, `updatedPermissions`, `additionalContext`) 반영 경로 구현 완료.
- M2 증적: run 복원/이력 재구성(`RestoreRecentFromExecutionEvents`, `RestoreCurrentAgentRun`, plan 이력 조회) 구현 및 테스트 존재.
- M3 증적: unknown-tool 복구 루프/결정 이벤트 처리 경로 구현 및 테스트 존재.
- M4 증적: 실행 종료 품질 게이트(`CodeQualityGate`, `ExecutionSuccessGate`, `TerminalEvidenceGate`) 반영 및 관련 테스트 존재.
- 스킬/도구 운영 정렬: 40개 스킬 모두 `allowed-tools` 명시 완료, Python 의존 10개는 fallback 분기 적용, 레거시 도구명(`process_run`, `grep_tool`) 참조 제거.

## 8. 남은 마감 항목 (M4 종료 조건)
1. 세션 replay 불일치 0건을 재현 시나리오별 수치로 기록.
2. 위 결과를 배포 전 체크리스트로 고정하고 매 릴리즈마다 수치 동기화.

## 9. 벤치마크 고정 기준 (CLAW 패리티 동기화)
- 기준 문서: `docs/CLAW_CODE_PARITY_PLAN.md` 12절.
- 고정 시나리오: 기본 loop / unknown-tool 복구 / plan 연결 / 권한 거부 / hook 입력 변형 / allowed-tools 강제 / hook filter.
- 합격 게이트: 빌드 경고·오류 0 + 전체 테스트 통과 + 고정 시나리오 회귀 통과.

## 10. Replay 안정성 검증 연동
- 기준 문서: `docs/CLAW_CODE_PARITY_PLAN.md` 13절.
- 테스트 태그: `Suite=ReplayStability`.
- 운영 기준: 릴리즈 전 `ReplayStability` 시나리오 전건 통과 시 replay 불일치 0건으로 판정.
- 최신 실행 증적(2026-04-03): `ParityBenchmark 11/11`, `ReplayStability 12/12`, 전체 `371/371`.
- 실행 자동화: `scripts/release-gate.ps1`로 빌드/벤치마크/리플레이/전체 테스트를 일괄 점검.

## 11. 권한 Hook 계약 고정 (M1 완료 기준)
- lifecycle hook 키:
  - `__permission_request__` (pre)
  - `__permission_granted__` (post)
  - `__permission_denied__` (post)
- payload 기준 필드: `runId`, `tool`, `target`, `permission`, `granted`, `reason`.
- 실행 우선순위:
  1. Hook의 `updatedPermissions`를 현재 run 권한 컨텍스트에 즉시 반영.
  2. 반영 후 `CheckToolPermissionAsync()`로 최종 권한 판정 수행.
  3. hook 예외/실패는 non-blocking으로 처리하고 권한 흐름은 지속.
  4. `additionalContext`는 가능한 경로에서 실행 메시지 컨텍스트에 병합.