AX-Copilot-Codex/docs/CLAW_CODE_PARITY_PLAN.md

CLAW-CODE 품질 동등화 계획 (전면 재작성)

1. 기준

• 레퍼런스: E:\AX Copilot - Codex\claw-code\claw-code-f5a40b86dede580f6543bf8926c9af017eea9409\src
• 동등화 범위: 명령 처리 흐름, 권한/훅 체계, plan/run 내구성, 세션/로그 관리.

2. 보존 이력 (요약만 유지)

• 루프 가드(반복 실패/정체 감지)와 검증 게이트는 이미 AX에 부분 반영.
• 병렬 도구 실행, Plan Mode, Unknown-tool 복구 로직은 반영 완료.
• 세션/이력 안정화는 진행 중.

3. 현재 갭

• Hook 출력의 구조화 계약 적용 범위가 제한적.
• 세션 재개/이벤트 replay 품질이 시나리오별 편차 존재.
• 도구 선택 실패 후 재시도 전략의 일관성 부족.

4. 단계별 실행

P1 Hook 계약 고도화

• updatedInput, updatedPermissions, additionalContext를 AX 실행 루프에 반영.
• 설정 토글로 위험 기능 제어.

P2 세션/이벤트 내구성

• run 상태 영속화와 resume 기준 고정.
• jsonl 이벤트 필드 표준화 및 재생 가능성 확보.

P3 실패 복구 표준화

• unknown-tool/권한거부/파라미터 오류를 유형화.
• 유형별 복구 프롬프트와 다음 액션 우선순위 고정.

P4 완료 품질 정렬

• 코드/문서 작업별 완료 체크리스트 표준화.
• 증거 없는 완료 응답 방지.

5. 완료 판정

• 내부 벤치마크 시나리오에서 목표 성공률 충족.
• 세션 재개/이벤트 재생 오류 0건.
• 빌드 경고 0/오류 0 유지.

6. 2026-04-03 점검 스냅샷

• 기준 시점: 2026-04-03.
• 계획 대비 현재 수준: 약 92~95%.
• 테스트 상태: dotnet test 371/371 통과.
• P1 Hook 계약: 구현 완료 수준.
• P2 세션/이벤트 내구성: 구현 완료 수준(복원/재생 경계 케이스 테스트 반영).
• P3 실패 복구 표준화: 구현 완료 수준(unknown-tool/권한/정체/fork 강제 흐름 반영).
• P4 완료 품질 정렬: 구현 완료 수준(게이트 로직 + 벤치마크 기준 문서화 완료).

7. 스킬/도구 운영 점검 (2026-04-03)

• 도구 레지스트리 등록 수: 65개 (ToolRegistry.CreateDefault() 기준).
• IAgentTool 구현 수: 65개. 동적 MCP 래퍼(McpTool)는 런타임 등록 구조로 정상.
• 내장 스킬 파일 수: 40개 (src/AxCopilot/skills/*.skill.md).
• allowed-tools 적용 스킬: 40/40.
• requires: python 고정 의존 스킬: 0개(기존 10개에 Python 가능/불가 분기 fallback 경로 반영).
• 레거시 도구명 process_run 참조: 0건 (process로 정규화).
• 레거시 도구명 grep_tool 참조: 0건 (grep로 정규화).
• 내부 모드 차단 정책: http_tool 전면 차단, open_external의 외부 URL 차단.
• 테스트 상태: dotnet test 371/371 통과.

8. claw-code 소스 직접 비교 결과 (2026-04-03)

• 비교 기준 소스: claw-code/.../src/tools.ts, src/Tool.ts, src/skills/loadSkillsDir.ts, src/skills/bundled/*.ts.
• claw-code 도구 상수명: 41개 (*_TOOL_NAME 기준).
• AX 도구명: 65개 (IAgentTool.Name 기준).
• claw-code 도구명 중 AX alias로 직접 해석되는 항목: 8개 (Bash/Read/Write/Edit/Glob/Grep/WebFetch/WebSearch).
• 미해석 항목(33개)은 대부분 제품 철학 차이 영역(예: EnterPlanMode, ExitWorktree, TeamCreate, TodoWrite, ToolSearch, REPL, Cron*).
• claw-code 번들 스킬은 코드 등록형 14개(registerBundledSkill)이며, AX는 파일 기반 스킬 40개(*.skill.md) 중심 구성.
• 번들 스킬 이름 교집합은 0개이며(의도된 차별화), 품질 기준은 "이름 일치"가 아니라 "동작 등가(계획/복구/검증/권한/세션 내구성)"로 판단해야 함.
• claw-code 스킬 메타데이터는 allowedTools, whenToUse, model, disableModelInvocation, userInvocable, hooks, context, agent, paths, effort, shell까지 지원.
• AX 스킬 메타데이터는 allowed-tools, when_to_use, argument-hint, model, disable-model-invocation, user-invocable, context, agent, effort, paths, shell, hooks, hook_filters까지 런타임 연계 확장 완료.

9. claw-code 비교 기반 즉시 보완 항목 (반영 상태)

1. 스킬 frontmatter 확장: when_to_use, argument-hint, model, disable-model-invocation, user-invocable, context, agent, effort, paths, shell 반영 완료.
2. 스킬 실행 범위 제어: paths 기반 조건부 활성화 반영 완료(첨부 파일 경로 매칭 시 동적 활성화).
3. 도구 별칭 정규화: claw-code 기본 도구명군(WebFetch, WebSearch, AskUserQuestion, LSP, ListMcpResourcesTool 등) AX 내부 도구명으로 매핑 반영 완료.
4. 반영 완료(2026-04-03): hooks/hook_filters 계약 확장 및 runtime hook 필터링(도구/타이밍 기준) 적용.
5. 반영 완료(2026-04-03): 슬래시 스킬 실행 시 context/agent/effort/model/disable-model-invocation/allowed-tools/hooks/hook_filters 메타데이터를 런타임 정책 지시문으로 합성 적용.

10. 전체 영역 동시 비교 기준 (누락 방지)

1. 도구 계층: 도구 목록, 별칭 정규화, unknown-tool 복구, tool search/선택 정책.
2. 스킬 계층: 로더, frontmatter, 번들/파일 기반 동시 운영, 조건부 활성화.
3. 훅/권한: pre/post hook 계약, permission update 반영, ask/auto/deny 일관성.
4. 세션/상태: run 복원, 이벤트 replay, 중복 이벤트 억제, resume 신뢰성.
5. 계획/실행: plan 승인/수정 이력, 실행 게이트, 조기 완료 방지.
6. MCP/외부도구: 연결/리소스 조회/읽기, 실패 복구, internal 모드 정책.
7. 서브에이전트: spawn/wait 제약, read-only 모드, 결과 회수 구조.
8. 운영/설정/UI 연동: 설정값-실행코드-UI 동기화, 탭별 분기(Cowork/Code) 일치.

11. 다음 적용 순서 (전체 영역 병렬 보정)

1. 기본 Agentic loop E2E 시나리오(도구 실행/unknown-tool 복구)를 회귀 테스트로 고정.
2. 벤치마크 합격 기준(시나리오/통과조건/증적)을 문서화하고 배포 체크리스트에 연결. (완료)
3. 최종 마감 시 패리티 문서(수치/상태)와 로드맵 문서를 동기화. (진행 중)

12. 내부 벤치마크 기준 (고정)

시나리오	기준 테스트	합격 기준
기본 Agentic loop (도구 호출 → 완료)	AgentLoopE2ETests.RunAsync_ExecutesToolCall_AndCompletesWithFinalText	ToolCall/ToolResult/Complete 이벤트가 순서상 유효하고 최종 응답에 계산 결과 포함
unknown-tool 복구	AgentLoopE2ETests.RunAsync_UnknownTool_RecoversAndCompletes	unknown 도구 오류 이벤트 후 완료까지 수렴, 반복 실패 루프 없음
Plan Mode 실행 연결	AgentLoopE2ETests.RunAsync_PlanModeAlways_EmitsPlanningThenExecutesTool	계획 응답 후 실제 도구 호출이 이어지고 최종 결과 생성
권한 Ask 거부 처리	AgentLoopE2ETests.RunAsync_AskPermissionDenied_EmitsPermissionEvents_AndCompletes	PermissionRequest/PermissionDenied 이벤트가 기록되고 안전 종료
Hook 입력 변형 반영	AgentLoopE2ETests.RunAsync_PreHookInputMutation_ChangesToolArguments	pre-hook updatedInput이 실제 도구 입력에 적용됨
Runtime 정책(allowed_tools) 강제	AgentLoopE2ETests.RunAsync_DisallowedTool_ByRuntimePolicy_EmitsPolicyRecoveryError	비허용 도구 차단 + 정책 복구 경고 후 종료
Hook filter 정합성	AgentLoopE2ETests.RunAsync_HookFilters_ExecuteOnlyMatchingHookForToolAndTiming	지정된 hook만 실행되고 비매칭 hook는 미실행
claw-code alias(EnterPlanMode) 정규화	AgentLoopE2ETests.RunAsync_EnterPlanModeAlias_ResolvesAndExecutes	CamelCase 도구명이 AX 내부 snake_case 도구로 매핑되어 정상 실행

벤치마크 배포 체크리스트 연결

1. dotnet build 경고 0/오류 0.
2. dotnet test 전체 통과 (371/371 기준, 증가 시 최신 값으로 동기화).
3. 위 8개 시나리오의 회귀 테스트가 모두 통과.
4. 패리티 수치/상태를 NEXT_ROADMAP.md와 동일 문구로 동기화.
5. 릴리즈 전 게이트 스크립트 실행: powershell -ExecutionPolicy Bypass -File .\scripts\release-gate.ps1

실행 증적 (2026-04-03)

• dotnet test --filter "Suite=ParityBenchmark": 11/11 통과.
• powershell -ExecutionPolicy Bypass -File .\scripts\release-gate.ps1: build/replay/full gate 통과.

13. 세션 Replay 안정성 기준 (고정)

시나리오	기준 테스트	합격 기준
실행 이벤트 정렬/압축 복원	ChatSessionStateServiceTests.LoadOrCreateConversation_NormalizesHistoryOrderAndCompactsSize	ExecutionEvents 400개 상한 유지 + 시간순 정렬 유지
run 이력 중복 정규화	ChatSessionStateServiceTests.LoadOrCreateConversation_NormalizesAgentRunDuplicatesByRunId	동일 RunId 중복이 최신 상태 1건으로 축약
동시각 이벤트 종결 우선 판정	TaskRunServiceTests.RestoreRecentFromExecutionEvents_PrefersTerminalEventsWhenTimestampsEqual	Tool/Permission 상태가 terminal 이벤트 기준으로 복원
비종결 이벤트 active 복원	TaskRunServiceTests.RestoreRecentFromExecutionEvents_RebuildsActiveTasksFromNonTerminalEvents	중단 후 재개 시 active task 3종(agent/tool/permission) 재구성
run 종료 시 dangling 정리	TaskRunServiceTests.RestoreRecentFromExecutionEvents_CompleteClearsDanglingRunScopedActiveTasks	Complete 이후 run 스코프 active task 잔존 0건
현재 run 복원 우선순위	AppStateServiceTests.RestoreCurrentAgentRun_PrefersRunningExecutionEventOverHistory	실행 중 이벤트가 history보다 우선되어 현재 run 복원
recent timeline 재구성	AppStateServiceTests.RestoreRecentTasks_RebuildsRecentTaskTimelineFromExecutionEvents	도구/권한/에이전트 최근 이력 순서 복원
권한 거부 후 active 권한 상태 정리	AppStateServiceTests.RestoreRecentTasks_PermissionDeniedLeavesNoActivePermissionAfterResume	PermissionDenied 이후 run 재개 시 active permission 잔존 0건
Hook 타임라인 역순 병합 정합성	AppStateServiceTests.ApplyAgentEvent_ReplaysHookTimelineInReverseChronologicalOrder	Hook 이벤트가 역순 타임라인에서도 시간/의미 순서 보존
완료 이벤트 우선 정리(병렬 도구)	TaskRunServiceTests.RestoreRecentFromExecutionEvents_CompleteClearsParallelToolCallsForSameRun	Complete 도착 시 동일 run의 병렬 도구 active task 즉시 정리

운영 규칙

1. 위 시나리오는 Suite=ReplayStability 테스트 태그로 관리.
2. 릴리즈 전 Suite=ReplayStability 전건 통과를 replay 불일치 0건의 최소 조건으로 사용.

실행 증적 (2026-04-03)

• dotnet test --filter "Suite=ReplayStability": 12/12 통과.
• powershell -ExecutionPolicy Bypass -File .\scripts\release-gate.ps1: ReplayStability 포함 게이트 통과.

14. 권한 Hook 계약 (P2 마감 기준)

• lifecycle hook 키:
  • __permission_request__ (pre)
  • __permission_granted__ (post)
  • __permission_denied__ (post)
• payload 기준 필드: runId, tool, target, permission, granted, reason.
• 우선순위:
  1. Hook updatedPermissions가 현재 run의 AgentContext.ToolPermissions를 즉시 갱신.
  2. 갱신 후 context.CheckToolPermissionAsync()로 최종 판정.
  3. hook 실패/예외는 non-blocking(권한 흐름 지속).
  4. additionalContext는 가능한 경로에서 메시지 컨텍스트로 반영.