chore(agents): migrate to agents.md protocol — .agents/ wiki/plans/rules/skills

Root AGENTS.md is now a thin entry point + knowledge map; the batch-workflow detail it duplicated already lived in .claude/skills/animation/SKILL.md. Folded docs/ (dances registry + iclone-bridge stub), root plans/, and devops-reports/ into .agents/wiki/ and .agents/plans/ per the per-repo .agents/ convention. Added .agents/SOUL.md, .agents/AGENTS.md, wiki/ARCHITECTURE.md, wiki/architecture/, and wiki/master-plan.md (derived from the closed plans + the dance registry's live ceremony-slot table). Fixed doc-path references in exchange/GUIDE.md, the animation skill, and the iclone-bridge stub. All moves via mv (git detected as renames) — no content deleted. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-24 15:02:47 -07:00
parent 28fdf940f7
commit 854dbb5ce4
25 changed files with 275 additions and 111 deletions
@@ -0,0 +1,95 @@
+# Dance registry — single source of truth for names
+
+Every dance clip in the pipeline is tracked here. **Numbers are never reused.**
+
+## Naming system
+
+Names follow the **game's item-id convention: lowercase snake_case** (like
+`ceremonial_garb`, `dance_platform`, `war_challenge`).
+
+**Stage 1 — provisional (new dances).** Every new take gets the next free `nd_##`
+number at conversion time, regardless of what the PC-side export was called:
+pack/file `nd_08`, clip `ND08`, dance JSON `nd_08.json`. Variants keep the base id +
+suffix: `nd_08_pp` / `ND08PP`. The `nd` prefix means "not yet adopted — subject to
+rename or archive". Never name a new dance after its content (a take called
+"firedance1" turned out to be dance1's choreography — content-guessed names lie).
+
+**Stage 2 — adopted (chosen for a specific dance ceremony).** Dance codes are the
+**game ceremony** the dance belongs to — snake_case of the sim's `DanceType` enum
+(`sim/arena/src/GameSystems.cs`) + a two-digit index for multiple takes per ceremony:
+pack `war_dance_01`, clip `WarDance01` (PascalCase, matching the enum), dance JSON
+`war_dance_01.json`, variants `war_dance_01_pp` / `WarDance01PP`. A take is only
+renamed once Jeremy says which ceremony it corresponds to. Rename with:
+
+```bash
+/Applications/Blender.app/Contents/MacOS/Blender --background --python tools/rename_clip.py -- \
+  --src exchange/<dir>/nd08.glb --out exchange/<dir>/haka01.glb --name Haka01
+```
+…then rename the dance JSON (+ its `name` and `clip` fields) in ariki-game, re-run
+`game.sh import`, and `git mv` the old files out. Update the row below.
+
+**Loop rule.** Every adopted dance ships as a PAIR: the base clip (`war_dance_01`) plus its ping-pong loop variant (`war_dance_01_pp` / `WarDance01PP`, baked with `tools/pingpong_bake.py`, must pass `loop_qc.py`). No adoption is complete without the loop.
+
+**Archive.** Rejected/superseded takes move to `archive/` (this repo) and
+`archive/dances/` (ariki-game, `.gdignore`d) — never deleted, never renamed.
+
+## Ceremony slots (from the sim's `DanceType` enum + tech tree)
+
+| ceremony code | Age | status | take |
+|---|---|---|---|
+| `water_dance_01` | 1 | awaiting take | — |
+| `fire_dance_01` | 1 | awaiting take | — (the old "firedance1" was mislabeled dance1 choreography) |
+| `tide_dance_01` | 1 | ⚠ **no enum entry** | — (no `TideDance` in the sim `DanceType` enum as of 2026-07-23 — confirm with Ozan whether the slot is real before filming a take) |
+| `fertility_dance_01` | 1 | **adopted** 2026-07-16 | aloha1 (hula) — shipped with `_pp` loop |
+| `food_dance_01` | 1 | awaiting take | — |
+| `taming_dance_01` | 1 | **adopted** 2026-07-16 | dance1 — shipped with `_pp` loop |
+| `sailing_dance_01` | 2 | awaiting take | — |
+| `war_dance_01` | 2 | **adopted** 2026-07-16 | hakadance1 (haka) — shipped with `_pp` loop |
+| `building_dance_01` | 2 | awaiting take | — |
+| `colony_shield_dance_01` | 2 | awaiting take | — |
+| `age_progression_dance_01` | 3 | awaiting take | — (gates Age advancement) |
+| `star_watching_dance_01` | 3 | awaiting take | — |
+| `rain_dance_01` | 1 | awaiting take | — (tech-tree "Rain Maker"; `RainDance` **is** in the DanceType enum, Age 1 — earlier "not in enum yet" note was wrong, corrected 2026-07-23) |
+
+## Register
+
+| id | status | pack(s) | clip | origin take | notes |
+|---|---|---|---|---|---|
+| nd_01 | **provisional** | `nd_01`, `nd_01_pp` | `ND01`, `ND01PP` | baraka1 (iClone, 2026-07-21) | 1800f@60; `_pp` loop passes QC (0.00 seam); awaiting ceremony assignment |
+| fertility_dance_01 | **adopted** | `fertility_dance_01`, `fertility_dance_01_pp` | `FertilityDance01`, `FertilityDance01PP` | aloha1 (iClone, 2026-07-15) | hula |
+| taming_dance_01 | **adopted** | `taming_dance_01`, `taming_dance_01_pp` | `TamingDance01`, `TamingDance01PP` | dance1 (iClone, 2026-07-15) | |
+| war_dance_01 | **adopted** | `war_dance_01`, `war_dance_01_pp` | `WarDance01`, `WarDance01PP` | hakadance1 (iClone, 2026-07-15) | haka |
+| — | archived | `hakadance2` | `HakaDance2` | hakadance2 | near-duplicate of hakadance1 take family |
+| — | archived | `alohaOG` | `AlohaOG` | alohaOG | superseded by aloha1 |
+| — | archived | `firedance1` | `FireDance1` | firedance1 | **same choreography as dance1** — mislabeled export |
+| — | archived | `hakaOG` | `HakaOG` | hakaOG | near-identical to hakadance1 |
+| — | archived | `haka_mocap` | `HakaFull` | MediaPipe video mocap (2026-07-13) | pre-iClone experiment |
+
+Next free provisional number: **nd_02** (nd_01 = baraka1, issued 2026-07-21).
+
+## Boat actions (avatar action clips — direct names, no provisional stage)
+
+Staging prop: `exchange/outgoing-props/boat/boat_prop.fbx` (built by
+`tools/export_boat_prop.py`; see its README for iClone import + filming notes).
+Cyclic clips (`*_loop`, `*_idle`) must pass `loop_qc.py` before shipping; one-shots
+(dive/climb/collect) keep their pelvis translation (game moves the avatar).
+
+| action code | clip | status | notes |
+|---|---|---|---|
+| `boat_dive` | `BoatDive` | awaiting take | airborne — hand-key/ActorCore or takeoff-only filming |
+| `boat_climb` | `BoatClimb` | awaiting take | film over ~0.65 m proxy; Reach-target cleanup |
+| `boat_collect` | `BoatCollect` | awaiting take | kneel over gunwale, flotsam grab |
+| `boat_row_loop` | `BoatRowLoop` | awaiting take | helm, stern-oar sweep ±18° |
+| `boat_fish_loop` | `BoatFishLoop` | awaiting take | Seat_Fisher; coexists with kevin Fishing01_Loop |
+| `boat_sail_idle` | `BoatSailIdle` | awaiting take | sway/line-hauling loop |
+| *(unregistered)* | `CanoeDismount`, `CanoeSitIdle` | **live in-game** since 2026-07-21 | shipped as `ariki-game/assets/quaternius/dancegen/canoedismount1.glb` (content-guessed name, predates this table) — register under a `boat_*` code at next adoption pass |
+| *(unregistered)* | `run_to_dive` | **live in-game** | Mixamo one-off at `ariki-game/assets/quaternius/mixamo/run_to_dive.glb` — outside this pipeline, listed for completeness |
+
+## QC tool split (audit 2026-07-23)
+
+Two QC tools exist and gate different stages — both stay:
+- **`tools/loop_qc.py` (this repo)** — the **pre-commit loop gate**: local-rotation pose gap,
+  velocity gap, root drift; exit 0/1. Every `_pp` (and `*_loop`/`*_idle` boat clip) must pass
+  it before adoption — this is the "must pass loop_qc" rule above.
+- **`ariki-game/tools/anim_qc.py`** — **post-ingest QC** on the game side: world-space seam
+  position/velocity, mid-clip stutter scan, seam-cross video render for eye review.
@@ -0,0 +1,58 @@
+# dance1 — motion description
+
+Kinematic description of the `dance1` clip (`dancegen/dance1.glb`, clip `Dance1`),
+derived by sampling world-space bone positions across the whole clip in Blender —
+not a subjective guess. Duration **30.0 s**, retargeted onto the Quaternius rig.
+
+## One-line read
+An energetic, **arm-forward** full-body dance: big symmetric sweeping arm gestures
+carry the performance, over busy footwork and pronounced level changes, while the
+whole body ranges around a ~1.2 × 1.7 m footprint. It never settles — continuous,
+flowing motion for the full 30 seconds.
+
+## What actually moves (path length over 30 s = how much a joint travels)
+
+| Rank | Body part | Travel | Read |
+|---|---|---|---|
+| 1 | **Both hands** | ~49–50 m each | The stars of the dance — huge, near-constant sweeps |
+| 2 | Forearms | ~32–33 m | Big arcs from the elbow reinforce the hand work |
+| 3 | Shins | ~25–26 m | Busy legs — steps, lifts, direction changes |
+| 4 | Upper arms / feet | ~18–21 m | Full-shoulder arm swings; active but grounded feet |
+| 5 | Head / spine / pelvis | ~16–17 m | Whole torso rides along — leans and level changes, not stiff |
+
+Hands move at roughly **1.7 m/s average** with constant direction changes, and each
+hand's reach spans ~1.7–2.5 m per axis — meaning full-wingspan sweeps that go both
+**high** (≈1.5–1.7 m vertical range) and **wide**. This is expansive, expressive
+upper-body choreography, not tight or contained.
+
+## Character traits
+- **Highly symmetric arms** — left/right hand travel matches at a **0.99 ratio**. The
+  arm choreography is mirrored/synchronized, the hallmark of a choreographed or
+  group-style routine (consistent with Polynesian dance vocabulary).
+- **Slight left-foot bias** — feet symmetry is 0.89 (left foot a bit busier), so the
+  legwork isn't perfectly mirrored; there's a lead side.
+- **Big level changes** — pelvis vertical range is **0.94 m**. The dancer drops and
+  rises a lot (deep bends / crouches into extensions), which gives the dance its
+  dynamic, punchy feel rather than staying at one height.
+- **Travels the space** — pelvis moves over a **1.2 × 1.7 m** horizontal area (16 m of
+  total travel), so it's not planted-in-place; expect stepping and repositioning.
+
+## Rhythm / tempo (caveat)
+Autocorrelation of the most-active joint's vertical motion peaks around **~205 bpm**,
+which is almost certainly the **double-time harmonic** of the real musical pulse —
+halving it gives **~100–103 bpm**, a lively mid-tempo. Treat this as approximate: the
+trustworthy tempo comes from the **source reference video's** music, not the retargeted
+motion. The `bpm: 100` in `dance1.json` is a hand-set placeholder that happens to land
+in the same neighborhood.
+
+## If scoring a song to it
+Aim for a **~100 bpm** groove with a strong backbeat and room for **sweeping,
+sustained phrases** (to match the long arm arcs) punctuated by **accents on the level
+drops** (the pelvis dips). Symmetric, repeating 4- or 8-bar structures will sit well
+against the mirrored, cyclic choreography. Confirm the real tempo against the source
+footage before locking it in.
+
+---
+*Generated 2026-07-15 from `exchange/converted-glb/dance1.glb` via Blender headless
+motion sampling. Method: per-frame world-space bone positions → path length, bounding
+range, L/R symmetry, and vertical-signal autocorrelation for tempo.*
@@ -0,0 +1,193 @@
+{
+  "name": "fertility_dance_01",
+  "glb": "exchange/converted-glb/fertility_dance_01.glb",
+  "duration_s": 30.0,
+  "fps": 24,
+  "frames": 720,
+  "bpm": 100,
+  "beats": 50,
+  "energy_per_beat": [
+    0.0671,
+    0.1187,
+    0.066,
+    0.0813,
+    0.1161,
+    0.234,
+    0.3293,
+    0.4352,
+    0.4132,
+    0.3849,
+    0.4206,
+    0.4606,
+    0.4989,
+    0.4251,
+    0.4806,
+    0.4737,
+    0.5986,
+    0.5101,
+    0.2858,
+    0.6089,
+    0.5596,
+    0.6887,
+    0.8083,
+    0.5382,
+    0.4154,
+    0.9773,
+    1.034,
+    0.5643,
+    1.1262,
+    0.4652,
+    0.4643,
+    0.9822,
+    1.2955,
+    0.6826,
+    0.9628,
+    1.3345,
+    0.9006,
+    0.5145,
+    0.6956,
+    0.6763,
+    0.3807,
+    0.4143,
+    0.4418,
+    0.489,
+    0.5304,
+    0.6733,
+    0.5457,
+    0.7964,
+    0.5111,
+    0.3799
+  ],
+  "energy_norm": [
+    0.0009,
+    0.0415,
+    0.0,
+    0.012,
+    0.0395,
+    0.1325,
+    0.2075,
+    0.2911,
+    0.2737,
+    0.2514,
+    0.2795,
+    0.3111,
+    0.3413,
+    0.2831,
+    0.3269,
+    0.3214,
+    0.4199,
+    0.3501,
+    0.1733,
+    0.428,
+    0.3891,
+    0.4909,
+    0.5852,
+    0.3722,
+    0.2755,
+    0.7184,
+    0.7631,
+    0.3928,
+    0.8358,
+    0.3147,
+    0.314,
+    0.7223,
+    0.9693,
+    0.4861,
+    0.707,
+    1.0,
+    0.6579,
+    0.3535,
+    0.4963,
+    0.4811,
+    0.248,
+    0.2745,
+    0.2962,
+    0.3335,
+    0.3661,
+    0.4788,
+    0.3782,
+    0.5758,
+    0.3509,
+    0.2475
+  ],
+  "accent_beats": [
+    6,
+    10,
+    11,
+    19,
+    20,
+    22,
+    23,
+    24,
+    25,
+    26,
+    28,
+    29,
+    30,
+    31,
+    32,
+    33,
+    34,
+    35,
+    36,
+    38,
+    39,
+    40,
+    44,
+    45,
+    47
+  ],
+  "pelvis_drop_beats": [
+    6,
+    10,
+    11,
+    23,
+    24,
+    25,
+    26,
+    28,
+    29,
+    30,
+    31,
+    34,
+    39,
+    40,
+    44,
+    47
+  ],
+  "hand_peak_beats": [
+    19,
+    20,
+    22,
+    25,
+    26,
+    28,
+    32,
+    33,
+    34,
+    35,
+    36,
+    38,
+    39,
+    45,
+    47
+  ],
+  "phrase_beats": 3,
+  "totals": {
+    "hands_m": 26.653432767023645,
+    "forearms_m": 21.23157808829689,
+    "upper_arms_m": 13.863015059740327,
+    "feet_m": 9.769735456958077,
+    "shins_m": 13.50568795659558,
+    "pelvis_m": 10.606148213798214,
+    "head_m": 11.129225506410268,
+    "lr_symmetry_hands": 0.9986419895043533,
+    "lr_symmetry_feet": 0.9833129850891342,
+    "pelvis_vertical_range_m": 0.41678035259246826,
+    "footprint_m": [
+      0.536299467086792,
+      0.8529399633407593
+    ]
+  },
+  "warnings": []
+}
@@ -0,0 +1,200 @@
+{
+  "name": "taming_dance_01",
+  "glb": "exchange/converted-glb/taming_dance_01.glb",
+  "duration_s": 30.0,
+  "fps": 24,
+  "frames": 720,
+  "bpm": 100,
+  "beats": 50,
+  "energy_per_beat": [
+    0.9916,
+    0.7155,
+    0.7886,
+    1.0957,
+    2.4134,
+    1.3599,
+    1.4711,
+    0.5712,
+    0.885,
+    0.9835,
+    2.12,
+    0.73,
+    0.3254,
+    0.9716,
+    1.4584,
+    0.8395,
+    0.368,
+    1.2858,
+    0.6909,
+    1.0359,
+    1.7734,
+    0.7137,
+    0.976,
+    1.7173,
+    1.3732,
+    0.6937,
+    0.444,
+    0.9441,
+    0.9548,
+    0.8954,
+    1.6452,
+    0.5804,
+    0.2176,
+    0.3835,
+    0.9297,
+    0.45,
+    0.4495,
+    1.0133,
+    0.8501,
+    0.9266,
+    1.2257,
+    1.0999,
+    0.338,
+    0.7127,
+    1.1935,
+    0.3326,
+    0.7522,
+    1.4484,
+    2.0448,
+    2.5482
+  ],
+  "energy_norm": [
+    0.3321,
+    0.2137,
+    0.245,
+    0.3768,
+    0.9422,
+    0.4901,
+    0.5378,
+    0.1517,
+    0.2864,
+    0.3287,
+    0.8162,
+    0.2199,
+    0.0463,
+    0.3235,
+    0.5324,
+    0.2669,
+    0.0646,
+    0.4584,
+    0.2031,
+    0.3511,
+    0.6676,
+    0.2129,
+    0.3254,
+    0.6435,
+    0.4959,
+    0.2043,
+    0.0972,
+    0.3117,
+    0.3163,
+    0.2908,
+    0.6126,
+    0.1557,
+    0.0,
+    0.0712,
+    0.3055,
+    0.0998,
+    0.0995,
+    0.3414,
+    0.2714,
+    0.3042,
+    0.4326,
+    0.3786,
+    0.0517,
+    0.2124,
+    0.4187,
+    0.0494,
+    0.2294,
+    0.5281,
+    0.784,
+    1.0
+  ],
+  "accent_beats": [
+    0,
+    1,
+    3,
+    4,
+    6,
+    9,
+    10,
+    11,
+    13,
+    14,
+    15,
+    17,
+    19,
+    20,
+    22,
+    23,
+    24,
+    27,
+    34,
+    36,
+    37,
+    40,
+    41,
+    43,
+    44,
+    47,
+    48,
+    49
+  ],
+  "pelvis_drop_beats": [
+    1,
+    11,
+    14,
+    15,
+    22,
+    34,
+    36,
+    37,
+    48,
+    49
+  ],
+  "hand_peak_beats": [
+    0,
+    1,
+    3,
+    4,
+    6,
+    9,
+    10,
+    13,
+    15,
+    17,
+    19,
+    20,
+    22,
+    23,
+    24,
+    27,
+    34,
+    37,
+    40,
+    41,
+    43,
+    44,
+    47,
+    48,
+    49
+  ],
+  "phrase_beats": 10,
+  "totals": {
+    "hands_m": 49.32286386602802,
+    "forearms_m": 32.85868643786276,
+    "upper_arms_m": 20.531188024591692,
+    "feet_m": 18.62118179928407,
+    "shins_m": 25.7590113640975,
+    "pelvis_m": 16.053067387300725,
+    "head_m": 17.234514413654498,
+    "lr_symmetry_hands": 0.9871641314548004,
+    "lr_symmetry_feet": 0.8839844668246384,
+    "pelvis_vertical_range_m": 0.9356732368469238,
+    "footprint_m": [
+      1.2194406312191859,
+      1.6680276617407799
+    ]
+  },
+  "warnings": []
+}
@@ -0,0 +1,208 @@
+{
+  "name": "war_dance_01",
+  "glb": "exchange/converted-glb/war_dance_01.glb",
+  "duration_s": 30.0,
+  "fps": 24,
+  "frames": 720,
+  "bpm": 100,
+  "beats": 50,
+  "energy_per_beat": [
+    0.1161,
+    0.0602,
+    0.0763,
+    0.0628,
+    0.6339,
+    0.7965,
+    0.8297,
+    0.6782,
+    0.1496,
+    0.0932,
+    0.1334,
+    0.8858,
+    0.9878,
+    0.8822,
+    0.2595,
+    0.1081,
+    0.1336,
+    0.2622,
+    0.2088,
+    0.232,
+    0.1623,
+    0.1525,
+    0.1841,
+    0.4061,
+    0.4191,
+    0.4014,
+    0.3346,
+    0.3014,
+    0.6334,
+    0.4097,
+    0.6412,
+    0.3384,
+    0.1109,
+    0.5587,
+    0.2789,
+    0.132,
+    0.588,
+    0.2621,
+    0.5738,
+    0.399,
+    0.4924,
+    0.4509,
+    0.6284,
+    0.3405,
+    0.0878,
+    0.0258,
+    0.026,
+    0.0,
+    0.0,
+    0.0
+  ],
+  "energy_norm": [
+    0.1176,
+    0.0609,
+    0.0772,
+    0.0635,
+    0.6418,
+    0.8063,
+    0.84,
+    0.6866,
+    0.1514,
+    0.0944,
+    0.1351,
+    0.8967,
+    1.0,
+    0.8931,
+    0.2627,
+    0.1094,
+    0.1352,
+    0.2654,
+    0.2114,
+    0.2348,
+    0.1643,
+    0.1544,
+    0.1863,
+    0.4111,
+    0.4242,
+    0.4064,
+    0.3387,
+    0.3051,
+    0.6413,
+    0.4147,
+    0.6491,
+    0.3426,
+    0.1122,
+    0.5656,
+    0.2823,
+    0.1336,
+    0.5952,
+    0.2654,
+    0.5809,
+    0.404,
+    0.4985,
+    0.4564,
+    0.6361,
+    0.3447,
+    0.0889,
+    0.0261,
+    0.0263,
+    0.0,
+    0.0,
+    0.0
+  ],
+  "accent_beats": [
+    4,
+    5,
+    6,
+    7,
+    11,
+    12,
+    13,
+    17,
+    20,
+    22,
+    23,
+    25,
+    26,
+    28,
+    29,
+    30,
+    31,
+    32,
+    33,
+    34,
+    35,
+    36,
+    37,
+    38,
+    39,
+    40,
+    41,
+    42,
+    44,
+    46,
+    48,
+    49
+  ],
+  "pelvis_drop_beats": [
+    6,
+    11,
+    13,
+    17,
+    20,
+    22,
+    23,
+    25,
+    26,
+    28,
+    29,
+    31,
+    32,
+    34,
+    35,
+    37,
+    38,
+    40,
+    41,
+    42,
+    44,
+    46,
+    48,
+    49
+  ],
+  "hand_peak_beats": [
+    4,
+    5,
+    6,
+    7,
+    11,
+    12,
+    13,
+    28,
+    30,
+    33,
+    36,
+    38,
+    39,
+    40,
+    42
+  ],
+  "phrase_beats": null,
+  "totals": {
+    "hands_m": 21.006407802644276,
+    "forearms_m": 12.905461711283007,
+    "upper_arms_m": 6.91306398100012,
+    "feet_m": 1.521721729225423,
+    "shins_m": 5.302736997519221,
+    "pelvis_m": 5.633388137876223,
+    "head_m": 6.2322590229562564,
+    "lr_symmetry_hands": 0.9744965493013217,
+    "lr_symmetry_feet": 0.6518710884905415,
+    "pelvis_vertical_range_m": 0.19754374027252197,
+    "footprint_m": [
+      0.2731027752161026,
+      0.1643172651529312
+    ]
+  },
+  "warnings": []
+}