# Phase 9 Round 7 — Feature: Draggable Torso & Head IK Targets in the Test Harness

## Overview

User request (test harness):
1. **Draggable torso target** — so the user can drag the whole stickman around.
2. **Draggable head target** — so the user can test the LookAt IK for the head.

The rig already provides both targets:
- `IK_Targets/Torso` (Marker2D at the hips) with a child `RemoteTransform2D` whose
  `remote_path` is `../../../Skeleton2D/Torso` — moving the marker moves the hip bone, and
  every other bone (Head/arms/legs) and `Body/*` visual follows.
- `IK_Targets/Head` (Marker2D at `(0, −624)`) — the `SkeletonModification2DLookAt` aim point
  for the Head bone (`bone_index = 1`, constrained, `constraint_in_localspace = true`).

The harness (`scripts/test_harness.gd`) already has generic handle dragging
(`IK_HANDLE_PATHS` → `_hit_test_handle` → `_dragging_handle` → `_handle_mouse_motion` sets
`global_position`; `_draw_ik_handles` draws markers). Only the two new handles need wiring,
plus torso-follow semantics.

## 1. Fix specification — `scripts/test_harness.gd`

### 1a. Register the new handles

Add to `IK_HANDLE_PATHS`:

```gdscript
"Head":  "IK_Targets/Head",
"Torso": "IK_Targets/Torso",
```

(Note: `LEAF_BONE_IK_PATHS` stays unchanged — the head's LookAt aim point is not a bone tip,
and the Torso is not a leaf bone.)

### 1b. Torso drag (resolved: bones only)

The Torso handle behaves like every other handle: dragging it moves only the marker (the
`IK_Targets/Torso` RemoteTransform2D then moves the hip bone, and the bone hierarchy follows).
The other IK targets (hands/legs/head) **stay put**, so dragging the figure away from them
stretches the limbs toward the stationary targets — per user decision.

### 1c. Marker colors

`_draw_ik_handles` currently colors hands green, everything else blue. Add distinct colors:
- `HANDLE_COLOR_HEAD := Color(1.0, 1.0, 0.0)` (yellow) for `"Head"`.
- `HANDLE_COLOR_TORSO := Color(1.0, 0.0, 1.0)` (magenta) for `"Torso"`.

### 1d. Head aim line (visual aid for the LookAt test)

In `_draw_ik_handles`, when both the head bone and the head marker exist, draw a thin
semi-transparent line from the head bone origin (`Skeleton2D/Torso/Head` global position) to
the head marker so the user can see what the head is aiming at. (Optional but helpful; use the
existing overlay draw style, e.g. width 1.5/zoom, alpha ~0.5.)

## 2. Files modified

| File | Changes |
|---|---|
| `scripts/test_harness.gd` | `IK_HANDLE_PATHS` + 2 entries (Head, Torso); head/torso marker colors; head aim line. |
| `docs/phase9_round7_feature_spec.md` | This file. |

## 3. Edge cases

- **Missing nodes** (foreign rig): `_ik_handles` lookups are already null-guarded; the aim
  line needs a null guard for the head bone.
- **Dragging the Torso** moves the markers only (the `RayCast_*` helpers under `IK_Targets`
  stay put — they are not handles).
- **Head LookAt constraints** — the head bone rotates within its authored constraint range;
  dragging the head marker far away clamps the rotation (expected rig behavior).
- **Camera** — does not follow the dragged figure (unchanged).

## 4. Test plan

1. Parse check: `..\Godot_v4.7.1-stable_win64_console.exe . --headless --check-only --quit`.
2. Headless rig-level verification (SceneTree script, spawn `break.stk`):
   - Move `IK_Targets/Torso` by `(50, −30)` → await a frame → assert `Skeleton2D/Torso`
     global position moved by ≈ the delta, and every `Body/*` visual node's global position
     moved by ≈ the same delta (rigid translation via the Torso RemoteTransform2D).
   - Move `IK_Targets/Head` from `(0, −624)` to `(300, −624)` → await a frame → assert the
     Head bone `global_rotation` changed, and `Body/Head.global_rotation` changed with it
     (rotation push) — LookAt works.
3. Harness code review: `IK_HANDLE_PATHS` has 6 entries (incl. Head, Torso); marker colors
   per §1c (yellow head, magenta torso); the head aim line is null-guarded and drawn in the
   IK overlay; the generic drag flow needs no changes (the Torso marker's RemoteTransform2D
   moves the hip bone on drag). (Mouse-drag flow is UI-side; the same `_handle_mouse_motion`
   math is covered by the review.)
4. Manual F6 check: drag the magenta torso marker — whole figure moves; drag the yellow head
   marker — the head turns to look at it.
5. Cleanup temp files.

## 5. Design decisions

| # | Decision | Justification |
|---|---|---|
| D1 | Torso drag = bones only (no target following) | User decision: dragging the figure away from the stationary limb/head targets stretches the limbs — useful for testing IK reach. |
| D2 | Head/torso get distinct marker colors | 6 markers need visual separation; matches the existing color-coded style. |
| D3 | Head aim line drawn in the IK overlay | Makes the LookAt target relationship visible. |

## 6. Implementation order

1. `test_harness.gd` — new handles + colors + aim line + torso-follow.
2. Headless verification + parse check.
3. Docs (BUGS.md Round 7 note, AGENTS.md, README.md).