Plan the Blender NPC head and hands overhaul

TODO.md

@@ -3,15 +3,116 @@
 Work is grouped by theme. Each item should be small enough to complete and verify on its own;
 see `AGENTS.md` for the workflow and `MEMORY.md` for the decisions behind these plans.
 
-**Priority order (2026-11-04, owner):** 1) release the finished procedural character development
-as the **0.9.7 patch**, 2) finish the MakeHuman character + the 3D model and map improvements,
-3) re-evaluate the 3D models, 4) ship all of it together in the **0.10.0 minor**. See `AGENTS.md`
-§Priority and Versioning and §Local Blender skills.
+**Priority order (2026-11-04, owner):** 1) **Blender NPC model overhaul** — head, face and hands
+with a local part pipeline; 2) finish the MakeHuman character + the 3D model and map improvements;
+3) ship it together in the **0.10.0 minor**. The 0.9.7/0.9.8 character patches are published. See
+`AGENTS.md` §Priority and Versioning and §Local Blender skills.
 
 The MIT Blender skill pack lives locally at `.agents/skills/blender-skills/` (gitignored). Every
 3D workstream below names the skills to load; they are guidance only, and the project contract,
 `blender_assets.py audit`/`fit`/`inspect` and the capture gates stay authoritative.
 
+## Blender NPC model overhaul (top priority)
+
+Goal: replace the sphere-and-primitive face and hand construction with a local, part-based
+development pipeline that can build, inspect and compare the **head/face** and **hands** separately
+before assembling them into the shipped character. Prioritise face readability at portrait
+distance, then hand silhouette and gear contact. Preserve the `npc_base` contract, the 13-bone rig,
+five tint slots, 8,000/8,000 character cap and Compatibility/Web path.
+
+*Skill route: `character-artist`, `retopology`, `sculpting`, `rigging`, `uv-workflow`,
+`texture-workflow`, `materials`, `lookdev`, `asset-optimization`, `qa-review`.*
+
+**Current state:** `assets/models/npc/` contains the tracked frozen `npc_base.blend` and its
+gitignored `.blend1`; the 12 production characters are assembled procedurally by
+`tools/blender_assets.py` from `_shape_head_mesh`, `_face`, `_hair` and `_hands_and_shoes`.
+There is no per-part source asset library yet. The MakeHuman body prototype and its temporary
+head/hand swap live under `tmp/npc-research/` and are not the shipped path. This overhaul supplies
+the reusable head/face and hand parts that both the procedural characters and the MakeHuman body
+can consume.
+
+This workstream supersedes the face/head and hands items in §C until the prototypes are approved;
+the rest of §C remains the broad review checklist.
+
+### 1. Baseline and acceptance
+
+- [ ] Inventory the real starting point: the frozen `assets/models/npc/npc_base.blend`, the 12
+      generated character GLBs/AO maps, the current `_face`/`_hands_and_shoes` builders and the
+      temporary MakeHuman head/hand swap. Record tris/verts, head subdivision, material slots,
+      UV layout and the exact locations of eye/mouth/finger geometry.
+- [ ] Define measurable acceptance: face front/three-quarter/profile at 1.5 m and 1.85 m; hands
+      open and gripping at 0.8 m; silhouette, eye/mouth readability, ear/nose/jaw planes, finger
+      separation and gear contact. Keep the 8,000/8,000 cap; no contract or renderer change.
+- [ ] Confirm the identity boundary: `npc_base.blend` is the frozen fallback and must not absorb
+      prototype detail unless a separate contract decision approves it.
+- [ ] Choose a local working-set layout: `tmp/npc-parts/<variant>/` (gitignored) for part `.blend`
+      and preview GLBs; only the assembled character GLBs, AO/maps, manifest and review sheets are
+      committed. Do not add a new committed `.blend` source tree without a docs/ADR decision.
+
+### 2. Local part pipeline
+
+- [ ] Add `tools/npc_parts.py` with a small, documented CLI:
+      `extract` (pull the current head/hands for comparison), `build --part head|face|hand_l|hand_r`,
+      `assemble --variant <name>`, `inspect`, `compare` and `sheet`. It should reuse the existing
+      builder helpers where possible and emit deterministic local files; do not fork a second
+      face/hand implementation.
+- [ ] Keep the part pipeline local-only and headless: flatpak Blender for authoring, stdlib/Pillow
+      for inspection and sheets. No Blender MCP, no new runtime dependency, no CI Blender step.
+- [ ] Add tests for deterministic part assembly, contract output (mesh root, bones, slots, budgets)
+      and the non-Blender failure path. Verify one assembled prototype with `audit`/`fit`/`inspect`
+      before touching production variants.
+- [ ] Document the commands, working-set paths and “part source is not a shipped asset” rule in
+      `docs/asset-tooling.md`, `docs/blender-assets.md` and
+      `.agents/skills/gig-line-blender-asset-contract/references/verification.md`.
+
+### 3. Head and face prototype
+
+- [ ] Build one `npc_casual` head/face prototype as a connected head shell plus intentional feature
+      geometry — not a sphere with floating facial balls. Use loop-based eye sockets/lids, a
+      readable nose bridge/tip/ala, a mouth with upper/lower lip volumes, ears with concha depth,
+      and brow/cheek/jaw planes that survive the 256² AO bake.
+- [ ] Compare two or three subdivision/loop variants at 1.85 m front/three-quarter/profile and a
+      1.5 m portrait. Pick the variant that reads best before changing all 12 characters; keep the
+      rejected variants local.
+- [ ] Verify head weights stay on the Head bone, headgear clearance still passes `fit`, and the
+      face does not bake recessed creases into dark AO patches.
+- [ ] Get owner sign-off on the one-variant prototype, then roll the approved head/face into the
+      other 11 variants one asset family at a time, with a before/after sheet per batch.
+
+### 4. Hands and grip prototype
+
+- [ ] Build separate left/right hand parts with a connected palm, four multi-segment fingers, a
+      thumb, knuckles and rounded tips. Support an open palm and a relaxed grip; preserve the
+      current `HAND_ITEM_FORWARD` behaviour for phone/cup/clipboard/camera/flashlight/wand/radio.
+- [ ] Decide finger articulation explicitly: the 13-bone contract has no finger bones, so keep the
+      open/relaxed-palm approach unless an ADR approves extra bones and the budget/weight path.
+- [ ] Verify all hand gear at 0.8 m (contact, clipping, direction) and capture open/grip hand
+      close-ups for the review sheet.
+- [ ] Roll the approved hands into all 12 variants only after the one-variant hand sheet passes.
+
+### 5. Assembly and rollout
+
+- [ ] Integrate the approved parts into `build_character` with deterministic joins, weights, UVs and
+      AO. The final output remains one `npc_base` skinned mesh under the existing 13-bone armature;
+      no second rig, no material-slot rename.
+- [ ] Keep the MakeHuman body prototype consumable with the same approved head/hands; do not let it
+      grow a second face/hand implementation while the part pipeline is being proven.
+- [ ] Rebuild only the changed character GLBs, AO maps and manifest entries; never run a no-op full
+      library rebuild. Commit one asset family per change.
+- [ ] Re-run `blender_assets.py audit`/`fit`/`inspect`, `npc_proportions.py`, the 24-NPC budget,
+      Godot and Python tests, the 48-frame baseline and the 96-frame final-context review.
+
+### 6. QA, docs and exit
+
+- [ ] Capture front/three-quarter/profile head comparisons and open/grip hand comparisons; add
+      durable sheets to `docs/blender_previews/` and link them from the review docs.
+- [ ] Update `docs/3d-model-review.md`, `docs/npc-visual-review.md`,
+      `docs/known-limitations.md`, `MEMORY.md` and the project skills with the accepted limits and
+      the new part workflow.
+- [ ] Exit: head/face and hands are approved on one prototype, rolled out across all 12 variants,
+      all contract/budget/capture gates pass, the local part pipeline is documented, and no
+      runtime dependency or skeleton contract changed.
+
 ## Fix the Rig pose harness
 
 Goal: `src/test/capture_npc_pose.gd` reports a pose but saves rest frames; the root cause is