# Integration Notes — Opus Review Feedback

## INTEGRATING (Critical/High priority)

### 1. Raw transform values (CRITICAL)
**Issue:** Parser's `decompose_transform3d()` discards raw 12 floats. Plan's "preferred approach" of reading raw basis columns from properties is impossible.
**Decision:** Modify the Sprint 1A parser to store raw values alongside the decomposition. Add a `"raw"` key to the transform dict: `{"position": ..., "rotation": ..., "scale": ..., "raw": (12 floats)}`. This is a backward-compatible addition, not a breaking change. Relaxing the "do not modify Sprint 1A" constraint for this minimal addition.

### 2. ExtResource ID collision between files (CRITICAL)
**Issue:** ExtResource IDs are local to each .tscn file. Property overrides containing ExtResource references need resolution against the parent file's ext_resources, not the instanced scene's.
**Decision:** During resolution, after applying property overrides, resolve any ExtResource references in override properties against the parent scene's ext_resources dict. Add explicit note about which ext_resources dict to use at each recursion level.

### 3. Circular reference detection (HIGH)
**Issue:** Stack-based cycle detection vs max_depth not clearly prioritized.
**Decision:** Implement both. Stack-based set of active res:// paths is the primary check (prevents any circular expansion). max_depth is the secondary safety net (prevents excessively deep but non-circular chains).

### 4. Deep copy strategy (HIGH)
**Issue:** Plan conflates parent-root copy with per-instance copy.
**Decision:** Clarify two distinct copy operations:
1. Do NOT deep-copy the parent root upfront. Work on the original tree.
2. Deep-copy each instanced scene's root when inserting its children into the parent tree.
Also recommend a custom `_clone_node()` function instead of generic `deepcopy()` for performance.

### 5. full_path construction (HIGH)
**Issue:** Algorithm not specified.
**Decision:** Root's full_path = root.name. Children: `parent_full_path + "/" + child.name`. Root name excluded from descendants' paths (matching Godot's NodePath convention). Instance-expanded children: their paths start from the instance node, not the instanced scene's root.

### 6. Instance node type resolution (MEDIUM)
**Issue:** Instance nodes have `type=""` — need to copy type from instanced scene root.
**Decision:** Add explicit step: if instance node's type is empty after resolution, copy from instanced scene's root.

### 7. FileCache key mapping (MEDIUM)
**Issue:** FileCache uses filesystem paths, ProjectIndex uses res:// paths.
**Decision:** Cache keys are always filesystem paths (required by `os.path.getmtime()`). ProjectIndex.scenes uses res:// keys. The mapping is: `fs_path = project_root / res_path[6:]`.

### 8. `is_instance_root` population (MEDIUM)
**Issue:** `calculate_world_transforms()` needs instance metadata but tree nodes don't carry it.
**Decision:** Use `ResolvedScene.instance_sources` dict during tree walk. Compute full_path for each node and check against instance_sources.

### 9. Error handling for malformed instanced scenes (MEDIUM)
**Issue:** Only FileNotFoundError addressed, but parse errors could occur.
**Decision:** Wrap `parse_tscn()` calls in try/except, log errors, add to unresolved.

## NOT INTEGRATING

### 2D node support
**Reason:** GodotIQ spec explicitly targets 3D (Godot 4 3D game analysis). Adding 2D transform support is out of scope for this sprint. Will note as known limitation.

### [editable] child overrides
**Reason:** Not present in our test fixtures. Uncommon in typical Godot projects. Will note as known limitation/future enhancement.

### `addons/` skip configurability
**Reason:** Over-engineering for MVP. Default skip is correct for most analysis use cases. Can be parameterized later if needed.

### `rescan_changed()` return semantics
**Reason:** Will return a new ProjectIndex (immutable pattern). Clear enough from the function signature.

### `find_unused_assets` redundancy
**Reason:** `used_by` in assets dict is populated from `resource_usage` — it's a convenience field, not redundant computation. Will clarify this is a derived field.

### Thread safety
**Reason:** MCP servers are single-threaded by design. Not a concern.

### `index` property for child ordering
**Reason:** Minor edge case. Default child ordering from parsing is sufficient for analysis use cases.

### Windows path compatibility
**Reason:** Good note, but `pathlib.Path` handles this. Will use res:// strings as dict keys consistently.
