# Section 04: Tool D02 — godotiq_animation_audit

## Dependencies
- Section 02 (extraction helpers) — all `_extract_*` and `_build_animation_summary` functions

## File Modified
- `src/godotiq/tools/animation/__init__.py` — added `_build_animation_audit` and `godotiq_animation_audit`

## What Was Built

### `_build_animation_audit(session, scope, scene_filter) -> dict`
Scans scenes for animation problems using 7 check types:

1. **broken_track** (CRITICAL) — track targets non-existent node in scene tree
2. **orphan_animation** (WARNING) — animation defined but never referenced in code or AnimationTree
3. **missing_animation** (WARNING/INFO) — code .play()s a name not found in scene (INFO for GLB-sourced)
4. **no_loop_suspect** (INFO) — short animation (<3s) with idle/walk/run name but no looping
5. **empty_player** (WARNING) — AnimationPlayer with no animations
6. **code_only_animations** (INFO) — animation only referenced in code, deduplicated with missing_animation
7. **orphan_tree_state** (WARNING) — AnimationTree state references animation not in linked AnimationPlayer

### `godotiq_animation_audit` MCP Tool
`@mcp.tool()` async wrapper with signature:
- `scope: str = "all"` — "all" or "scene"
- `scene: str | None = None` — required when scope="scene"
- Returns dict with: scope, scenes_scanned, animated_scenes, total_animations, total_issues, by_severity, issues

### Scope Logic
- `scope="all"` — iterates all scenes in session._index.scenes
- `scope="scene"` — single scene (errors if no scene parameter)

### Output Structure
Issues sorted by severity (critical > warning > info), capped at 50 with critical preserved.

## Code Review Fixes Applied
- Fix 1: Added travel_calls to referenced sets for orphan/missing detection
- Fix 2: Error on scope='scene' without scene parameter
- Fix 3: Link orphan_tree_state to specific AnimationPlayer via anim_player_path
- Fix 4: Deduplicate code_only_animations with missing_animation

## Tests
Tests defined in Section 07 (10 tests covering all check types, scopes, severity ordering, cap).
