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` 361/361 통과.
- 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` 361/361 통과.

## 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는 미실행 |

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

### 실행 증적 (2026-04-03)
- `dotnet test --filter "Suite=ParityBenchmark"`: 7/7 통과.
- `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`는 가능한 경로에서 메시지 컨텍스트로 반영.