AX-Copilot-Codex/docs/NEXT_ROADMAP.md

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

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

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

## 3. 마일스톤

| 마일스톤 | 참조 대상 (`OpenCode`) | AX 적용 위치 | 완료 조건 | 품질 판정 시나리오 |
|---|---|---|---|---|
| M1 (v0.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 (v0.7.4~v0.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 (v0.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 (v0.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` | 증거 기반 완료 판정 고정. 내부 벤치마크에서 OpenCode 동급 품질 달성. | 코드수정/문서생성/권한거부/복구 혼합 시나리오에서 조기완료 없이 근거 기반 종료 확인. |

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

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

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

## 7. 2026-04-03 실행 증적 동기화 (M4 포함)
- 기준 시점: 2026-04-03.
- 테스트: `dotnet test` 379/379 통과.
- 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/OPENCODE_PARITY_PLAN.md` 12절.
- 고정 시나리오: 기본 loop / unknown-tool 복구 / plan 연결 / 권한 거부 / hook 입력 변형 / allowed-tools 강제 / hook filter.
- 합격 게이트: 빌드 경고·오류 0 + 전체 테스트 통과 + 고정 시나리오 회귀 통과.

## 10. Replay 안정성 검증 연동
- 기준 문서: `docs/OPENCODE_PARITY_PLAN.md` 13절.
- 테스트 태그: `Suite=ReplayStability`.
- 운영 기준: 릴리즈 전 `ReplayStability` 시나리오 전건 통과 시 replay 불일치 0건으로 판정.
- 최신 실행 증적(2026-04-03): `ParityBenchmark 13/13`, `ReplayStability 14/14`, 전체 `379/379`.
- 실행 자동화: `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`는 가능한 경로에서 실행 메시지 컨텍스트에 병합.




## 2026-04-04 추가 계획 (Codex/Claude 추격 로드맵 재정렬)

업데이트: 2026-04-04 13:24 (KST)

### 기준 소스
- OpenCode/src/commands.ts
- OpenCode/src/utils/permissions/PermissionMode.ts
- OpenCode/src/components/PromptInput/PromptInput.tsx

### 현재 AX 격차 요약
1. 입력/슬래시/권한 처리 로직이 ChatWindow 단일 파일에 상대적으로 집중되어 변경 파급도가 큼.
2. 설정-런타임-UI 동기화는 기능은 많지만 구조적 분리가 부족해 회귀 리스크가 높음.
3. Agent loop 품질 게이트는 확보됐으나, UI 상호작용 회귀 시나리오와 결합된 자동 검증이 더 필요함.

### 연속 실행 목표 (L1~L5)
- **L1. 입력 계층 모듈화**
  - 목표: slash 명령 카탈로그/매칭/선택 상태를 분리해 ChatWindow 결합도 축소
  - 완료 기준: slash 관련 핵심 로직을 독립 파일로 분리하고 기존 slash 테스트 통과
- **L2. 권한 UX/로직 단일 카탈로그화**
  - 목표: 권한 모드 명칭/설명/색/정렬 순서를 단일 소스에서 제공
  - 완료 기준: 팝업/상태 배너/슬래시 출력에서 동일 용어·동일 순서 유지
- **L3. 설정 동기화 강화**
  - 목표: Cowork/Code 설정 분기를 실행 코드 경로까지 일치시켜 회귀 감소
  - 완료 기준: 설정 변경 즉시 반영 시나리오 체크리스트 전건 통과
- **L4. Agentic loop + UI 결합 회귀 테스트 보강**
  - 목표: internal/external, permission deny/recover, mcp reconnect, compact 수동/자동 흐름을 통합 검증
  - 완료 기준: 릴리즈 게이트용 통합 테스트 세트 추가 및 통과
- **L5. Codex/Claude형 UI 마감**
  - 목표: 좌측 패널/컴포저/권한 팝업 밀도와 탐색 동작을 단순·일관 패턴으로 정리
  - 완료 기준: UI 체크리스트 주요 항목 100% 충족 + 빌드 경고/오류 0

### 이번 턴 즉시 반영 (L1 시작)
- ChatWindow의 대형 slash 명령 사전을 SlashCommandCatalog로 분리.
- ChatWindow는 카탈로그 API(MatchBuiltinCommands, TryGetEntry)를 통해 조회하도록 전환.
- 결과: 입력 계층 결합도 감소 + 향후 slash 확장/정리 시 변경 범위 축소.

## 2026-04-04 실행 프레임 고정 (중기 계획)

업데이트: 2026-04-04 14:47 (KST)

### 3축 고정 운영
1. 로직 안정화: 권한/운영모드/compact/모델 연결 경로를 테스트 우선으로 보강.
2. 기능 동등성: OpenCode 기준 주요 명령(/compact, /permissions, /mcp, /chrome)을 실행 시나리오로 검증.
3. UX 정렬: 상단/컴포저/팝업 밀도는 로직 안정화 완료 범위 내에서만 단계 반영.

### 이번 사이클 기준 완료 조건
- 빌드: `dotnet build` 경고 0 / 오류 0.
- 핵심 회귀: 운영모드, 권한, slash, 모델연결, compact 관련 필터 테스트 통과.
- 문서: `README.md`, `docs/DEVELOPMENT.md`에 시간 포함 이력 동기화 후 커밋/푸시.

### 이번 사이클 실제 보강 항목
- `ContextCondenserTests` 추가:
  - proactive 비활성 시 무변경 확인
  - 대용량 tool_result 축약 동작 확인
- `LlmRuntimeOverrideTests` 보강:
  - vLLM 암호화 API키 런타임 복호화 검증
  - 등록모델/전역 TLS 우회 플래그 합성 규칙 검증
업데이트: 2026-04-15 08:32 (KST)

### 이번 배치 마감 상태
- 에이전틱 루프는 우선순위 큐, tool_result preview 복원, 슬래시 합성 일원화까지 반영되어 `claw-code` 대비 남은 격차가 `루프 세분화/장기 상태 고정` 중심으로 축소됐습니다.
- 문서 포맷은 PPTX/DOCX/XLSX/HTML 모두 실무형 상급 수준까지 올라왔고, 이후 남은 작업은 `slide/workbook/document-level critic`과 `golden regression` 확대 같은 마감 단계입니다.
- 개발언어 지원은 `빠른 선택 + LSP 심화 지원 + 정적 fallback` 구조로 정리됐습니다. 다음 단계는 언어별 실행 힌트 활용 범위를 더 넓히고, no-LSP 환경에서도 분석 품질을 더 끌어올리는 것입니다.

### 다음 우선순위
1. `AgentLoopService` 실행 상태 분해와 장기 세션 replacement state 고정
2. PPTX/XLSX/DOCX/HTML critic/repair loop 최종 마감
3. 언어별 build/test/lint 힌트의 실제 도구 활용 경로 확대
4. 릴리즈 게이트와 로드맵 문서 최종 정합화

업데이트: 2026-04-15 09:49 (KST)

### 추가 진행 메모
1. 개발언어 고도화는 `지원 언어 표시`를 넘어서 `Language Workflow`를 실제 컨텍스트에 주입하는 단계로 넘어갔습니다.
2. 다음 구현 배치는 `AgentLoopService` 세분화, `tool_result replacement state` 장기 세션 고정, 문서 포맷 공통 quality formatter 확장 순으로 진행합니다.
3. 문서 포맷은 PPTX가 가장 앞서 있고, DOCX/XLSX/HTML은 공통 critic/repair와 golden 회귀를 같은 수준으로 끌어올리는 마감 단계에 들어갑니다.

업데이트: 2026-04-15 10:05 (KST)

### 추가 진행 메모
1. 에이전틱 루프는 이제 `queued command projector + run lifecycle helper` 구조까지 들어와 시작/종료 책임이 분리됐습니다. 다음 마감 단계는 `RunAsync` 본체의 iteration pipeline을 더 잘게 나누는 작업입니다.
2. `tool_result replacement state`는 synthetic preview를 넘어 fingerprint 재바인딩까지 들어갔습니다. 남은 방향은 compact/branch 이후의 replacement policy를 세션 단위 상태로 더 오래 유지하는 것입니다.
3. 문서 포맷은 `ArtifactQualityOutputFormatter`가 HTML/XLSX뿐 아니라 DOCX/PPTX까지 확장되었습니다. 다음 마감은 포맷별 critic/repair 자체를 더 깊게 하고, golden fixture 샘플을 확대하는 단계입니다.