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 샘플을 확대하는 단계입니다.

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

추가 진행 메모

1. 개발언어 fallback은 이제 Language Workflow를 .ax-context.md와 코드 시스템 프롬프트에 모두 주입하는 단계까지 올라왔습니다. 남은 마감은 no-LSP 환경에서 이 힌트를 실제 도구 사용/검증 흐름과 더 촘촘히 묶는 것입니다.
2. 에이전틱 루프는 run lifecycle, queued command projection, iteration preparation, LLM request preparation helper까지 분리됐습니다. 다음 큰 축은 RunAsync의 tool dispatch/finalize 분리를 더 진행해 본체 책임을 더 줄이는 것입니다.
3. 명령/스킬 합성은 우선순위 충돌 해소가 대부분 정리됐고, 이후 작업은 릴리즈 게이트와 체크리스트를 최종 상태에 맞춰 닫는 단계입니다.

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

통합 마감 계획

1. 문서 포맷 최종 마감
   • 참조 대상: claw-code/src/query.ts, claw-code/src/utils/toolResultStorage.ts, claw-code/src/commands/init-verifiers.ts
   • AX 적용 위치: PptxSkill, DeckPlanningService, DeckQualityReviewService, DocxSkill, DocumentAssemblerTool, ExcelSkill, HtmlSkill, ArtifactQualityReviewService
   • 완료 조건: PPTX/DOCX/XLSX/HTML golden fixture 확대, critic/repair loop 최종 보강
   • 품질 판정 기준: strong fixture Needs work: none, weak fixture는 포맷별 정확한 repair guide 반환
2. AgentLoop/Queue/Context 최종 분리
   • 참조 대상: claw-code/src/QueryEngine.ts, claw-code/src/query.ts, claw-code/src/utils/messageQueueManager.ts, claw-code/src/utils/toolResultStorage.ts
   • AX 적용 위치: AgentLoopService, AgentLoopRunLifecycle, AgentQueuedCommandProjector, AgentMessageInvariantHelper, AgentToolResultBudget, AgentQueryContextBuilder, ContextCondenser
   • 완료 조건: RunAsync iteration pipeline 분리, replacement state 장기 세션 고정
   • 품질 판정 기준: 중단/재개/권한/branch/replay 회귀 전건 통과
3. 개발언어 fallback 심화
   • 참조 대상: claw-code/src/query.ts, claw-code/src/context.ts
   • AX 적용 위치: CodeLanguageCatalog, LspTool, WorkspaceContextGenerator, SystemPromptBuilder, 설정 도움말
   • 완료 조건: no-LSP 환경에서도 manifest/build/test/lint 힌트와 영향 범위 설명 강화
   • 품질 판정 기준: Auto 모드가 LSP 없는 주요 언어 저장소에서도 안정적으로 안내
4. 명령/스킬 합성 및 릴리즈 게이트
   • 참조 대상: claw-code/src/commands.ts, claw-code/src/skills/loadSkillsDir.ts
   • AX 적용 위치: SlashCommandCatalog, SkillService, README, DEVELOPMENT, NEXT_ROADMAP
   • 완료 조건: builtin/skill/plugin/workflow 충돌 해소와 릴리즈 체크리스트 최신화
   • 품질 판정 기준: 토큰 충돌 시 팔레트와 실제 실행이 완전 일치

실행 순서

1. 문서 포맷 마감
2. 루프/큐/컨텍스트 분리
3. 개발언어 fallback 심화
4. 명령/스킬 합성 및 릴리즈 게이트 업데이트: 2026-04-15 10:57 (KST)

• Agent loop 마감 작업으로 도구 미호출 복구 규칙을 서비스화했습니다. 남은 우선순위는 iteration/tool dispatch 추가 분리, 장기 세션 replacement state 완전 고정, 문서 golden fixture 확대, 릴리즈 체크리스트 닫기 정도의 마감 품질 중심입니다.

업데이트: 2026-04-15 11:17 (KST)

추가 진행 메모

1. SQL은 별도 정적 분석 계층까지 올라왔습니다. 현재도 no-LSP 환경에서 dialect/statement/risk/next checks를 직접 설명할 수 있고, 다음 단계로 더 간다면 dialect별 migration lint나 schema dependency graph 정도가 후보입니다.
2. PPT는 구조화된 슬라이드를 더 적극적으로 comparison/roadmap/kpi_dashboard/chart로 승격하고, KPI/evidence/verdict/owner 같은 컨설팅형 품질 기준을 slide critic에 반영했습니다. 큰 기능보다 golden fixture 확대 성격의 마감 작업이 남아 있습니다.
3. HTML은 kpi_panel이 새 핵심 블록으로 들어오면서 board/strategy 문서의 decision/evidence/KPI 연결성이 더 중요해졌습니다. 이후 작업은 목적형 bundled skill 확장과 print/export polish 쪽이 중심입니다.

업데이트: 2026-04-15 11:36 (KST)

추가 진행 메모

1. SQL fallback은 dialect/statement/risk 수준을 넘어 script intent/dependency/review focus까지 확장됐습니다. 다음 선택지는 dialect별 migration lint, schema dependency graph, rollback 시뮬레이션처럼 더 깊은 전용 리뷰 계층입니다.
2. HTML 문서는 decision_matrix와 metric_strip이 들어오면서 board/strategy 보고서의 의사결정 구조를 더 직접적으로 표현할 수 있게 됐습니다. 남은 작업은 bundled skill을 목적형으로 더 쪼개고 print/export polish를 마감하는 수준입니다.
3. PPT critic은 headline, trade-off, phase milestone, chart takeaway, KPI context를 세밀하게 보기 시작했습니다. 이후 남는 작업은 finance/sales/board fixture 확대와 slide-level auto-repair 정교화처럼 golden 마감 중심입니다.

업데이트: 2026-04-15 11:50 (KST)

추가 진행 메모

1. SQL은 이제 fallback 요약에 별도 review severity / findings / checklist가 붙는 수준까지 올라왔습니다. 남은 고도화는 dialect별 migration lint, schema dependency graph, rollback simulation 같은 더 깊은 검증 계층입니다.
2. Agent loop는 응답 분해 helper가 추가되어 RunAsync 본체가 한 단계 더 얇아졌습니다. 이후 분리 후보는 tool dispatch와 finalize 쪽이라, 구조적 마감은 거의 끝나가고 있습니다.
3. 문서 쪽은 기능 확장보다 golden fixture 확대, 목적형 bundled skill, print/export polish처럼 완성도 마감 항목이 중심으로 남았습니다.

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

추가 진행 메모

1. Cowork/Code의 사용자 체감 진행 문구는 AgentStatusNarrativeCatalog 기준으로 정리됐습니다. 같은 agent event를 status bar, idle 힌트, readable process feed가 함께 재사용하게 되어 작업 분석 -> 읽기 -> 수정 -> 검증 -> 정리 흐름이 더 선명하게 드러납니다.
2. 남은 AX Agent UX 마감 항목은 상태 문구 자체보다 카드 밀도, 표현 수준(풍부하게/적절하게/간단하게)별 정보량 차등, 목적형 이벤트 배지 polish 쪽입니다.
3. 구조적 우선순위는 여전히 tool dispatch/finalize 추가 분리, 장기 세션 replacement state 고정, PPT/HTML golden 확대가 가장 높습니다.