animation/.agents/plans/lena-handmorph-track-2026-08-18.md

# Handover: Lena hand MORPH track (blend-shape lane) — 2026-08-18

You own the **morph lane**. A parallel agent owns the **bone lane** (finger weights +
`HandPoseLayer`). Read the scope fence before touching anything — the two lanes share a
git branch and one serialized test bed.

## Goal

Lena can hold **fist** and **grip** in-game, on the **shipped** body. Flat already works
via the bone lane, so flat is not your problem — the two poses that never made it are
fist and grip, and this lane is the one that can carry them, because it does not depend
on finger weights at all.

The blocking bug is known and localized: **coincident (unwelded) duplicate vertices in
the scan mesh are invisible to the solver's convergence gate**, so the right hand's
fist/grip still tear. Fix that, re-solve, get a bed visual, then make the ship-body call.

## Why this lane exists (do not re-litigate)

Lena's mesh is a Tripo scan with ~2.6k inter-digit bridge edges (web remnants). Bone
weights only choose *which bone drags a shared vertex* — when adjacent digits curl apart
in a fist, those bridges MUST tear. Five weight-rebake iterations (exp01–exp05) never
converged; the verdict from that lane is that weights alone cannot clear the bar on this
mesh. A morph target IS the final vertex positions, so tearing is impossible by
construction and the residual web stretch becomes one smoothable, *converging* geometric
problem. Morphs also work on the shipped **rigid-mitt** bodies (zero finger weights) and
on Mako, with no rest-space compatibility hacks and no body denylist.

## What already works (verified, not aspirational)

- **Runtime driver committed** in ariki-game: `src/Animation/HandMorphLayer.cs`
  (commit `40b995e21`). Discovers `hand_<pose>_<l|r>` blend shapes on the body's meshes,
  per-hand 0..1 blend, `CyclePose()`, logs once and goes inert on bodies without shapes.
  `PoseOrder = { flat, relaxed, fist, grip }`.
- **Shape preservation**: `src/Character/BodyMeshShaper.Deform()` carries the shapes
  through muscle/fat rebuilds.
- **Solver + verifier** (animation repo, **untracked** — committing them is your job):
  `tools/handshape_solve.py` (723 lines), `tools/handshape_verify.py` (109 lines),
  plus `hand-shapes/README.md`.
- **In-engine verification happened once** (2026-08-17): fist and grip read as real
  fists/grips mid-dance at hand-cam range on the demo body, no fins/shards/spikes
  (agent-API screenshots 181806/181808).
- **Two beds can drive it**: `dance_test_bed` (hotkey **K** cycles poses, **J** hand cam,
  **1** frames the team) and the newer `anim_hand_test_bed` (commit `d1e6fb0a5`, Lena +
  Mako side by side as game-model rigs, button panels for both hand lanes + hand-follow
  cams). Prefer `anim_hand_test_bed` — it is the exact colonist build path the game uses.

## Solver pipeline (so you can navigate 723 lines fast)

`tools/handshape_solve.py`, all offline pure numpy over **raw GLB bytes** — Blender is
only the interpreter host (numpy), no `bpy`, no scene import. The
"Blender-importer-draws-false-shards" trap therefore does not apply to the solver, but
see the render warning below.

1. parse GLB, rest skeleton (node globals × IBM = skinning space) — `read_glb`, `Skeleton`
2. hand ROI: verts within 1.8 cm of finger/hand bone segments, grown 3 edge rings — `build_roi:188`
3. ROI graph (CSR adjacency + unique edge list) — `roi_graph:208`
4. per-bone geodesic fields: multi-source Dijkstra over the ROI subgraph — `dijkstra_multi:226`
5. weights: gaussian kernels on geodesic distance, top-4, renormalized, smoothed — `solve_weights:250`
6. pose: parametric curl/spread/thumb-opposition per joint, pivoted at each joint head,
   LBS with the solver's OWN weights (the GLB's rigid-mitt weights are irrelevant and
   that is fine) — `pose_globals:336`, `lbs:398`; pose parameters live in `DEFAULT_PARAMS`
7. relax: stretch-gated Laplacian diffusion of the DELTA field until the bars pass — `relax:448`
8. gates: `stretch_stats:434` → `handmorph_report.json` + per-pose OBJ dumps
9. emit: splice morph accessors into the GLB (deltas added to base — exactly Godot's
   `w = target + base`) with `extras.targetNames = hand_<pose>_<l|r>` — `emit_morph_glb:552`.
   POSITION **and** NORMAL deltas are emitted (position-only morphs leave lighting on the
   rest shape and read as "torn texture").

`--selftest-bump` splices one synthetic 3 cm palm bump with no solve — use it to prove the
import + drive path end-to-end on any new body before trusting solver output.

## THE BUG — weld before solve

`stretch_stats` (line 434) and the `relax` gate (line 448, `s[lr < 0.001] = 1.0`) both
apply a **1 mm rest-length floor**. The reasoning was sound for decimation slivers, but
this mesh is unwelded chart soup: it carries *coincident duplicate* verts whose rest edge
length is ~0. Those edges are excluded from the stats AND from the convergence gate, so
**the relaxation never even tries to fix them**. Measured 2026-08-18: a population of
sub-mm edges stretches to **4–20 cm** in fist/grip on BOTH hands (~25–60 per hand over 5×)
— hairline needles, sub-pixel in the screenshots that "passed", but really there.

`grep -niE "weld|coincid|dedup" tools/handshape_solve.py` returns **zero hits** — no weld
pass exists.

**The fix, and the shape it has to take.** Weld at the *graph* level, not by rewriting the
mesh: build a representative map over coincident positions (hash/round positions to ~1e-6,
or a KD-tree at ~10 µm), solve on the welded ROI, then **scatter each welded vertex's delta
back to every duplicate in its weld group** before `full[idx] = relaxed`. Morph deltas must
stay indexed by *original* vertex id (the GLB's own attribute order) or the splice breaks.
Because all members of a group then receive an identical delta, coincident edges keep
length exactly and the entire failure class dies by construction rather than by tuning.

Insert the weld between `build_roi` (called in `main`, ~line 228) and `roi_graph`, and make
sure the Dijkstra/adjacency also runs on the welded graph — otherwise geodesic distances
still leak across seams and the weight field stays fragmented.

**Hypothesis worth testing while you are in there** (state it as a hypothesis, do not
assume): the right hand's tracked ≥1 mm failures may be the same disease. If duplicates
split the delta field across a chart seam, welding should collapse a good share of those
too. Measure before and after; report both.

## Current numbers — the baseline you must beat

Body: `Ariki_Female_QuatSkin_LowPoly_40.glb` (restored `lena_leafbikini_base_v01` mesh, so
no yellow-material defect). ROI = **5,548 verts**. From
`characters/work/lena_leafbikini/handmorph/handmorph_report.json` (2026-08-18 08:49),
post-relax, ≥1 mm edges only:

| shape | max | p99.9 | n>2× | n>5× | iters |
|---|---|---|---|---|---|
| flat_l | 1.94 | 1.60 | 0 | 0 | 11 |
| relaxed_l | 3.60 | 1.49 | 3 | 0 | 60 |
| fist_l | 4.23 | 1.99 | 15 | 0 | 60 |
| grip_l | 4.38 | 1.97 | 13 | 0 | 60 |
| flat_r | 2.41 | 1.59 | 1 | 0 | 8 |
| relaxed_r | 4.08 | 3.22 | 81 | 0 | 60 |
| **fist_r** | **29.78** | **18.94** | 214 | **37** | 60 (hit cap) |
| **grip_r** | **20.38** | **12.10** | 372 | **35** | 60 (hit cap) |

Left hand is fully clean — *better* than the earlier LENA_rig_v1 body. Right fist/grip are
the failures, and both burn all 60 relax iterations without converging.

Fingertip travel is healthy and should stay so: fist_l tips 9.0–10.3 cm (thumb 15.3),
relaxed_l 1.7–2.0 cm (thumb 6.1).

**Gate bars** (per shape, ≥1 mm edges — and after your fix, the sliver population too):
edge stretch p99.9 ≤ 1.6×, **zero** edges > 5×; fingertip travel fist ≥ 2.5 cm/finger,
grip ~2 cm, relaxed 0.5–2 cm; cross-hand independence 0 cm on the other hand's verts.

## How to run

Solve (Blender is just the numpy host):

```
"C:/Program Files/Blender Foundation/Blender 5.1/blender.exe" --background \
  --factory-startup --python tools/handshape_solve.py -- \
  --body C:/Users/Jeremy/tinqs/ariki-game/assets/quaternius/derived-bodies/Ariki_Female_QuatSkin_LowPoly_40.glb \
  --poses flat,relaxed,fist,grip \
  --out C:/Users/Jeremy/tinqs/ariki-game/scratchpad/lowpoly40_handmorph.glb \
  --workdir characters/work/lena_leafbikini/handmorph/
```

Verify in-engine — **the only honest gate**:

```
HANDMORPH_BODY_F=res://scratchpad/lowpoly40_handmorph.glb \
  SCENE=anim_hand_test_bed MOCK_ONLY=1 AGENT_OWNED=1 WAIT=1 bash tools/game.sh spawn
```

(`HANDMORPH_BODY` applies to both rigs, `_F`/`_M` per rig — see `DancerRig.cs:40`.
In `dance_test_bed` instead: **1** frames the team, **J** hand cam, **K** cycles
None→flat→relaxed→fist→grip→None.)

## Two traps that have already cost time

- **Do not judge the solver's OBJ dumps by clay render.** The un-welded chart soup renders
  as black-gap confetti even at REST (flipped per-chart normals). It is dishonest in both
  directions. Judge morphs **in-engine only**. The numeric report + the bed are the gates.
- **`handshape_verify.py` reports `own-delta = -1` sentinels on this body** — a mesh/bone
  space mismatch in the verifier, not in the solve. Don't trust it here; either fix the
  verifier or ignore it and rely on the report + bed.

## Open decisions you own

1. **Ship-body decision** — nothing shipped carries the shapes yet, so the layer is a
   silent no-op on the real Lena. `LowPoly_40` costs ~**+41 MB** for 8 shapes; full-res
   ~**+98 MB**, not shippable as-is. Options: fewer shapes (drop `flat`/`relaxed` — the
   bone lane already does flat on finger-weighted bodies, but the *shipped* Lena is a
   rigid mitt, so think it through), hand-region remesh, LOD1-only, or quantized deltas.
   Bring Jeremy the numbers and a recommendation; do not ship a 128 MB body silently.
2. **Mako male + full-res female** via the same one-command solve — untried.
3. **Pose authoring** is currently "edit `DEFAULT_PARAMS`". Could become JSON + a tuning
   scene. Low priority — only if pose tuning becomes the bottleneck.
4. **Commit the tooling.** `tools/handshape_solve.py`, `tools/handshape_verify.py`,
   `hand-shapes/README.md` and the `handmorph/` workdir are all untracked in the animation
   repo. Commit the tools and README; keep the demo GLB out of git (128 MB, `scratchpad/`).

## Scope fence — the parallel bone agent

**Yours** (edit freely): `tools/handshape_solve.py`, `tools/handshape_verify.py`,
`hand-shapes/`, `characters/work/lena_leafbikini/handmorph/`, ariki-game
`src/Animation/HandMorphLayer.cs`, `scratchpad/lowpoly40_handmorph.glb`.

**Not yours** (the bone agent is actively editing these): `tools/handpose_*.py`,
`tools/edge_stretch.py`, `tools/fin_bones.py`, `hand-poses/`,
`characters/work/lena_leafbikini/08_finger_weights.py` and the `v02/` weight-experiment
bakes, ariki-game `src/Animation/HandPoseLayer.cs`.

**Shared, coordinate before touching:**
- `src/Testing/AnimHandTestBed.cs` and `src/Testing/Dance/DanceTestBed.cs` — both lanes'
  controls live in these files. Announce edits.
- **Only ONE `--agent-api` game instance may run at a time.** The bed is a serialized
  resource; check whether the other agent is mid-run before you spawn.
- ariki-game branch **`handpose-flat-runtime`**, currently 4 local commits ahead and
  **not pushed** (`40b995e21`, `518b72ac6`, `fa5e8e8de`, `d1e6fb0a5`). Both agents commit
  here. Pull/rebase before committing, and never squash across the other lane's work.

**Hard rules (unchanged):**
- Do not re-export or swap any shipped body outside the registry process;
  `characters/female/lena_leafbikini_base_v01/` is frozen.
- Do not touch `ariki-game/tools/make_lena_fullres_quatskin.py`; `LENA_RIGID_FINGERS`
  default stays `"1"`.
- **Never commit `csproj` / `project.godot` engine-version lines**, and don't sweep the
  repo-wide `.import` churn into your commits — the working tree has hundreds of modified
  `.import` sidecars that are not yours. Commit explicit paths only.
- Do not enable the **bone** lane on Mako (corrupt cross-hand finger weights, verts fly
  metres). The morph lane on Mako is safe in principle — but prove it with
  `--selftest-bump` first.

## Acceptance for this track

1. Weld pass lands in `handshape_solve.py`; a fresh solve reports **zero** edges > 5× on
   all 8 shapes with the sliver floor removed (report the sliver population before/after).
2. Fingertip travel bars still met (fist ≥ 2.5 cm/finger), cross-hand independence 0 cm.
3. `anim_hand_test_bed` screenshots at hand-cam range: fist and grip read as a real fist
   and grip on Lena mid-dance, both hands, no needles/shards/spikes.
4. A written ship-body recommendation with MB costs, for Jeremy's decision.
5. Tools + README committed in the animation repo; no shipped asset or engine-version
   line changed.