Draft ADR-0018 (Stage 2 runtime rig) and mark the remaining contract-bake items blocked

docs/adr/0018-quaternius-stage2-runtime-rig.md

@@ -0,0 +1,80 @@
+# ADR-0018: Quaternius Stage 2 — adopt source proportions at runtime
+
+- **Status:** Proposed
+- **Date:** 2026-11-05
+- **Supersedes:** ADR-0017 decision 2 (Stage 1 keeps the 13-core contract)
+
+## Context
+
+ADR-0017 made Quaternius the NPC base and staged the migration: Stage 1 bakes a
+proportion-warped mesh onto the existing 13-core contract; Stage 2 adopts the
+62-joint rig at runtime only if the warp fails.
+
+The Stage 1 proportion warp was executed and measured (`docs/npc-model-sourcing.md`
+§Rest-pose and proportion-warp measurement). The arm-down rest pose bakes cleanly, but the
+warp to the contract proportions does not:
+
+| Joint | Quaternius | Contract | Delta |
+| --- | --- | --- | --- |
+| Hips height | 0.869 | 0.62 | −0.249 |
+| Shoulder x | 0.148 | 0.27 | +0.122 |
+| Arm (shoulder→hand tip) | 0.429 | 0.70 | ×1.63 |
+| Leg (hip→ankle) | 0.835 | 0.62 | ×0.74 |
+| Torso (hip→head) | 0.745 | 1.20 | ×1.61 |
+
+The vision judge reads the warped mesh as distorted: paddle/claw hands, forearms lost into the
+torso, stretched shins, "long legs + short torso". The arm either stays short (a shortened arm
+against the contract hand) or stretches 1.63× (a distorted deltoid + hand). Both are the gate's
+rejection conditions.
+
+## Decision
+
+Stop the Stage 1 rollout. Adopt the **Quaternius source proportions** as the runtime character
+scale, rather than warping them to the old contract numbers. Two sub-options are open and must
+be chosen by the owner:
+
+1. **Keep the 13-core bone names, change their rest positions to the Quaternius joints.**
+   The contract armature keeps 14 bones, but the rest positions and gear attach points are
+   re-derived from the Quaternius skeleton (hip ≈0.87, shoulder ≈0.148/1.39, wrist ≈0.99,
+   knee ≈0.52). `NpcAvatar`'s bone count and pose composition stay; gear offsets and the
+   contract tests are re-baked. This is the smallest runtime change that keeps the Quaternius
+   silhouette.
+2. **Adopt the 62-joint rig at runtime.** Ship the Quaternius skeleton (including the optional
+   30 finger + 2 foot bones) and retarget Idle/Walk onto it. `NpcAvatar` bone mapping, gear
+   attach points and the pose composition change together. Largest change, closest to the
+   source.
+
+Whichever is chosen, the mesh is **not** proportion-warped: it keeps its source LOD (3,199 welded
+verts / 6,206 tris) and only the arm-down rest pose is baked.
+
+## Consequences
+
+### Positive
+
+- The Quaternius silhouette, deltoid, hand and leg proportions are preserved — no paddle hands,
+  no shortened arm, no torso/leg distortion.
+- The mesh stays at source LOD (far under the 24,000 cap), so no decimation is needed.
+
+### Negative
+
+- The runtime contract numbers (hip 0.62, shoulder 0.27, hand 0.78) change; every gear attach
+  point, `npc_proportions` guide, fit measurement and pose-composition constant must be
+  re-derived and re-tested.
+- Option 2 additionally rewrites `NpcAvatar`'s bone mapping and animation retarget, which is a
+  larger, riskier change than the mesh swap.
+- The 12-variant rollout and the 12×6 baseline are still blocked until the new rest positions
+  and gear fit are owner-approved.
+
+## Alternatives
+
+- **Ship the warped mesh.** Rejected by the gate: the 1.63× arm / 0.74× leg warp visibly
+  distorts and the owner directed keeping the Quaternius as close to source as possible.
+- **Keep the old contract and accept a short arm.** Rejected for the same reason: the hand ends
+  at ≈0.99 instead of 0.78, so handheld gear floats unless attach points move — which is option 1.
+- **Abandon Quaternius and keep the procedural generator.** Rejected in ADR-0017.
+
+## Open question
+
+Choose option 1 (13-core names, Quaternius rest positions) or option 2 (62-joint runtime).
+Recommendation: **option 1** first — it preserves the silhouette, keeps `NpcAvatar`'s bone count
+and pose composition, and only re-derives gear offsets and contract tests.

docs/adr/README.md

@@ -21,3 +21,4 @@ Each ADR records the context, decision, consequences and alternatives for a dura
 - [0015-npc-model-variety-sourcing](0015-npc-model-variety-sourcing.md)
 - [0016-npc-character-budget-24k](0016-npc-character-budget-24k.md)
 - [0017-quaternius-npc-base](0017-quaternius-npc-base.md)
+- [0018-quaternius-stage2-runtime-rig](0018-quaternius-stage2-runtime-rig.md)