Draft: V0 Animation Correction — Loops 1–6 (do not merge)

.gitignore

@@ -86,3 +86,7 @@ Thumbs.db
 # NOTE: evidence intentionally committed under reports/visual/v0/ is NOT ignored.
 # (*.png screenshots, *.mp4 / *.gif recordings, *.csv / *.md performance & reports)
 # The audio/binary-art ignores above (*.wav/*.mp3/*.ogg/*.fbx/*.glb/...) do not match them.
+
+# python bytecode
+tools/blender/__pycache__/
+*.pyc

docs/art/V0-ANIMATION-CORRECTION-BRIEF.md

@@ -0,0 +1,6 @@
+# V0 Animation-Led Visual Correction — Brief
+Combined, animation-led correction (Art PM option C) on the PR #6 environment. Make the service
+read through MOTION, not static poses/meters/close-ups. This branch is a **Loops 1–3 checkpoint**
+of a min-10 / target-12 phase; NOT shipped. Not M1, no backend, no production nav/AI.
+Re-authored a deformation-ready rig (per the PM ruling) rather than rigging PR #6's pose-baked meshes.
+See V0-ANIMATION-CORRECTION-REPORT.md for the checkpoint gate (Incomplete checkpoint / Continue).

docs/art/V0-ANIMATION-CURRENT-STATE.md

@@ -0,0 +1,11 @@
+# V0 Animation Correction — Current State (living handoff)
+Re-confirm against git log before trusting. Branch fix/v0-animation-led-visual-correction from
+2ef1bb1. DRAFT PR → fix/v0-visual-baseline-correction (unmerged). Blender 5.2 / Godot 4.7.1.
+COMPLETE: rig pipeline PROVEN (skeleton/skin/anim → Godot playback deforming); 19-bone base + 3
+profiles; 7 clips; locomotion (walk+facing+grounding); animated healthy+kitchen integration (35
+rigs); GPU-counter perf; loops 1-3 archived.
+PARTIAL/DEFERRED (loops 4-12): manual shoulder/hip/wrist weights + Sit corrective (~8-14 h);
+AnimationTree blending; BoneAttachment3D props; LOD (11.8k tris/char); FOH+host motion
+choreography; at-overview bottleneck-via-motion; full passes. Deformation & operational-
+storytelling self-scored 3 (< the 4 bar). Independent critique queued (not run this session).
+Latest Art PM decision: option C authorized; awaiting decision on the manual deformation pass.

docs/art/V0-ANIMATION-DECISION-LOG.md

@@ -0,0 +1,9 @@
+# V0 Animation Correction — Decision Log (2026-07-30)
+| # | Decision | State | Rationale |
+|---|---|---|---|
+| AD1 | Re-author deformation-ready rig (not rig PR#6 pose-baked meshes) | Locked (PM) | pose-baked meshes have no skin/joints; would create weak shoulders/hips |
+| AD2 | Procedural rig: continuous mesh + subsurf-pre-skin + ARMATURE_AUTO | Provisional | best headless deformation; clean joints still need manual paint |
+| AD3 | In-place clips + scripted path movement (no root motion, no nav) | Locked (V0) | keeps mock/visual boundary; readable choreography |
+| AD4 | Stop at 3 genuine archived loops this session | Locked | honest scope; PM authorized 3-loop checkpoint; no faked loops |
+| AD5 | Perf via RenderingServer counters, not 1/process_delta | Locked | fixes PR#6 review E1; GPU-measured-time unavailable offscreen (flagged) |
+| AD6 | Manual deformation pass (~8-14 h) required before loops 4-12 | Proposed | clean shoulders/hips/wrists unreachable procedurally; gates downstream |

docs/art/V0-ANIMATION-ITERATION-LOG.md

@@ -0,0 +1,8 @@
+# V0 Animation Iteration Log
+| Loop | Hypothesis | Outcome | Decision | Commit |
+|---|---|---|---|---|
+| 01 base | subsurf+auto-weight continuous mesh deforms > boxes | 19-bone skinned base, 3 profiles, Idle; skeleton/skin PROVEN | Accept; shoulders/hips need manual | iter 01 |
+| 02 locomotion | walk+path-follow reads at mgmt camera | walks, faces, grounded; mild foot slide, no blend | Accept | iter 02 |
+| 03 task language | task clips + animated actors read as service | populated animated healthy+kitchen; 35 rigs; storytelling@overview unproven | Accept; stop at 3 (no budget for L4) | iter 03 |
+Evidence: reports/visual/v0-animation-correction/iteration-01..03/ (hypothesis/critique/scores/
+decision + screenshots + recordings). 3 of min 10; target 12 NOT complete. No evidence reconstructed.

docs/art/V0-ANIMATION-NAMING-STANDARD.md

@@ -0,0 +1,5 @@
+# V0 Animation Naming Standard
+Clip names (glTF actions, stable): Idle, Walk, WalkStop, Carry, Cook, Sit, Wipe.
+Planned (loops 4-12): TakeOrder, Serve, Plate, Grill, WipeReset, QueueWait, Impatient, SitDown,
+StandUp, Greet, Escort. Bones: lowercase role_side (upperarm_L). One shared skeleton across all
+roles/variants; roles differ by material + prop + clip, not by skeleton.

docs/art/V0-ANIMATION-NEXT-ACTION.md

@@ -0,0 +1,9 @@
+# V0 Animation Correction — Next Authorized Action (living handoff)
+Re-confirm the repository's actual state before trusting this document.
+ONE next action: review this DRAFT Loops-1-3 checkpoint PR, and approve the ~8-14 h MANUAL
+Blender deformation pass (weight-paint shoulders/hips/wrists + shoulder & Sit corrective shapes +
+a decimated LOD1) as the start of Loop 4 — because clean deformation gates loops 4-12 and cannot
+be reached by procedural auto-weights. Then continue loops 4-12 (blending, bone-props, FOH/host
+motion choreography, at-overview storytelling, full passes).
+NOT authorized: merge, human test, backend/M1, production nav/AI, final art.
+Reproduce: blender --background --python tools/blender/build_rig.py -- --out visual/RestaurantVisualSandbox/assets/generated --clips Idle,Walk,WalkStop,Carry,Cook,Sit,Wipe ; then open res://scenes/diagnostics/AnimatedService.tscn.

docs/art/V0-ANIMATION-PERFORMANCE-STANDARD.md

@@ -0,0 +1,8 @@
+# V0 Animation Performance Standard
+DO NOT report 1/get_process_delta_time() as GPU perf (the PR #6 review's E1). Use RenderingServer
+counters + measured render time. Checkpoint (animated-performance.csv, M3 Max, 1920x1080):
+35 skeletons/35 AnimationPlayers, 118 mesh instances, 475 draw calls, 541k primitives, ~291 MB
+VRAM, CPU render ~0.25 ms. NOTE: viewport_get_measured_render_time_gpu returned 0.00 offscreen
+(context limit) — a true GPU-ms number needs an interactive window / GPU timer query. Perf task:
+LOD the 11.8k-tri characters (~541k prims is the main cost driver). Target 60 FPS on the M3 Max
+(not min-spec). Draw calls & VRAM are already low.

docs/art/V0-CHARACTER-RIG-STANDARD.md

@@ -0,0 +1,8 @@
+# V0 Character Rig Standard
+Source: tools/blender/build_rig.py (procedural, deterministic). 1 m = 1 unit.
+Mesh: continuous cylinder body + Subdivision-Surface level applied BEFORE skinning (smoother
+auto-weights than disjoint boxes). Skeleton (19 bones): pelvis, spine, chest, neck, head;
+clavicle/upperarm/lowerarm/hand ×L/R; upperleg/lowerleg/foot ×L/R. Skin via ARMATURE_AUTO.
+Body profiles: slim/average/broad (torso/limb scale). ~11,800 tris/char (subsurf-1) — LOD needed.
+KNOWN CEILING (needs manual weight painting, see report §I): shoulders, hips (Sit), wrists.
+Export: GLB, export_skins=True, export_animations=True, export_animation_mode='ACTIONS'.

docs/art/V0-PROP-SOCKET-STANDARD.md

@@ -0,0 +1,5 @@
+# V0 Prop Socket Standard (checkpoint status)
+Target sockets: hand_L, hand_R, both-hands (tray), head (toque). STATUS: props are currently
+child-offset approximations (toque on head, tray in front), NOT bone-attached. Loop-4+ task:
+add BoneAttachment3D to hand_R/hand_L/head so tray/plate/pad/cloth/tub/utensil/toque track the
+clip. Avoid floating/embedded props, vertical plates, detached tools.

docs/art/V0-SERVICE-CHOREOGRAPHY-STANDARD.md

@@ -0,0 +1,7 @@
+# V0 Service Choreography Standard (checkpoint status)
+Actors are placed from the frozen Mock snapshot (owns no gameplay truth): seated customers (Sit),
+cooks at active stations (Cook; cluster at congested grill), servers (Walk in aisle + Carry/Idle
+at pass), busser (Wipe/Walk), host (Idle). STATUS: healthy + kitchen staged (loop 3). DEFERRED
+(loops 7-10): FOH "food piling + overloaded servers" in motion, host entrance-queue in motion,
+congestion buildup, table turns, and proving the bottleneck reads at the default overview via
+behaviour. Movement = scripted paths only (no production navigation).

reports/visual/v0-animation-correction/V0-ANIMATION-CORRECTION-REPORT.md

@@ -0,0 +1,95 @@
+# V0 Animation-Led Visual Correction — Loops 1–3 Checkpoint Report
+
+> **CHECKPOINT, NOT A SHIPPED PHASE.** 3 of a minimum 10 loops complete; target 12 **not**
+> complete. Human testing **not** authorized. **Do not merge.** Backend / M1 **not** authorized.
+> Manual deformation refinement still required.
+>
+> ```
+> Verdict: Incomplete checkpoint
+> Action:  Continue animation phase
+> ```
+
+## A. Repository
+- Base `2ef1bb1` (reviewed PR #6 head). Branch `fix/v0-animation-led-visual-correction`,
+  worktree `../Restaurant-AnimationCorrection`. Target: **DRAFT** PR → `fix/v0-visual-baseline-correction`.
+- Commits: `iter 01 base` → `iter 02 locomotion` → `iter 03 task language + integration` (one per loop).
+- PR #6, PR #4, and the M0 branches are untouched; nothing merged.
+
+## B. Tools
+Blender **5.2.0 LTS** (`/Applications/Blender.app/…`) · Godot **4.7.1-stable** (`~/.local/opt/godot/…`).
+Pipeline: `tools/blender/build_rig.py` → rigged GLB (`export_skins`, `export_animations`,
+`export_animation_mode=ACTIONS`) → Godot Skeleton3D + AnimationPlayer. Reproduce:
+`blender --background --python tools/blender/build_rig.py -- --out visual/RestaurantVisualSandbox/assets/generated --clips Idle,Walk,WalkStop,Carry,Cook,Sit,Wipe`.
+
+## C. What was proven (the review's Blocker resolved)
+The PR #6 review's **Blocker** was `skins=0, animations=0` — no skeleton. **Resolved:**
+`CHAR_Base_Average.glb` has `skins=1`, **19 joints**, `JOINTS_0 + WEIGHTS_0`, **7 clips**
+(Idle/Walk/WalkStop/Carry/Cook/Sit/Wipe). Godot imports `Skeleton3D(19)` + `AnimationPlayer`;
+**characters visibly deform** on playback (not rigid). 35 rigged actors animate simultaneously
+in the restaurant.
+
+## D. Loops completed (genuinely archived — see `iteration-01..03/`)
+| Loop | Result | Self-scored weak point |
+|---|---|---|
+| 1 base | 19-bone skeleton, subsurf-smoothed skin, 3 body profiles, Idle | Deformation **3** (shoulder crease) |
+| 2 locomotion | Walk + WalkStop, path-follow + facing + grounding at mgmt camera | mild foot slide; no blend |
+| 3 task language | Carry/Cook/Sit/Wipe; animated actors in healthy + kitchen | Operational-storytelling **3**, Sit hip crease |
+
+Each iteration folder has HYPOTHESIS/CRITIQUE/SCORES/DECISION + screenshots + (loops 2-3) recordings.
+**No iteration evidence was reconstructed after the fact; no folders are empty.**
+
+## E. Character base
+Continuous cylinder body + Subdivision-Surface (applied pre-skin) + `ARMATURE_AUTO` weights;
+19 bones (pelvis/spine/chest/neck/head, clavicle/upperarm/lowerarm/hand ×2, upperleg/lowerleg/foot ×2).
+3 body profiles (slim/average/broad). **~11,800 tris/char** (subsurf-1) — needs a LOD/decimated variant.
+
+## F. Animation library (7 clips)
+Idle, Walk, WalkStop, Carry, Cook, Sit, Wipe — procedural keyframed, looped where appropriate.
+Known: no AnimationTree blending yet (hard-switch); props child-offset, not bone-attached.
+
+## G. Scenario results (motion)
+Healthy and kitchen-bottleneck are **populated with animated actors** and recorded
+(`recordings/loop03-*.mp4`). They differ by animated staffing (cook cluster at the congested
+grill, walker count). **Honest:** reading the *specific* bottleneck at the default overview
+through behaviour alone is **not yet proven** — that is the loop 7–10 choreography work; FOH and
+host motion tells are not yet staged.
+
+## H. Performance (honest; fixes the review's E1)
+`performance/animated-performance.csv` — measured via `RenderingServer` (not `1/process_delta`):
+**35 skeletons / 35 AnimationPlayers, 118 mesh instances, 475 draw calls, 541k primitives,
+~291 MB VRAM, CPU render ~0.25 ms.** The `viewport_get_measured_render_time_gpu` returned **0.00**
+in the offscreen capture context (a measurement-context limitation) — a true GPU-ms number needs
+an interactive windowed session / GPU timer query. Draw-call & VRAM cost is low; the ~541k
+primitives (11.8k-tri chars ×35) is the main increase → **LOD is the perf task**.
+
+## I. Deformation ceiling (procedural vs manual — the core honesty)
+| Joint / case | Current defect | Solvable procedurally? | Needs manual work |
+|---|---|---|---|
+| Shoulder → torso | creases/pinches | partial | **manual weight paint + corrective shape** |
+| Hips under Sit | compression crease | no | **manual hip weights + Sit corrective** |
+| Wrists / prop grip | approximate, no fingers | partial (mitten) | **manual for clean grip + BoneAttachment3D** |
+| Elbows / knees | segment volume loss | partial (more loops) | corrective shapes for ≥4 |
+**Estimated manual Blender hours to reach rubric Deformation ≥4:** ~**8–14 h** (shoulders ~3,
+hips/sit ~3, wrists/hands ~2, correctives ~2–4) + ~2 h LOD. **Recommended next-session workflow:**
+open the generated base in Blender, weight-paint shoulders/hips/wrists, add shoulder + sit
+corrective shape keys, build a decimated LOD1 (~2–3k tris), then re-export and re-run loops 4+.
+
+## J. Regression & isolation
+PR #6 preserved; backend/`main`/M0 untouched; no M1; no production navigation (scripted paths
+only); no authoritative gameplay (reuses the pure Mock snapshot); no restricted assets
+(all original procedural). Confirmed by diff.
+
+## K. Gate
+```
+Verdict: Incomplete checkpoint
+Action:  Continue animation phase
+```
+Not Pass / Pass-with-notes. The authorized 12-loop phase is **not** shipped. This checkpoint
+proves the rig pipeline and delivers 3 genuine loops; loops 4–12 (blending, bone-props, manual
+deformation, LOD, FOH/host motion choreography, at-overview storytelling, full passes) remain.
+
+## L. Required Art PM decision
+> **Approve the ~8–14 h manual Blender deformation pass (shoulders/hips/wrists + correctives +
+> LOD) as the start of Loop 4, before continuing loops 4–12** — since clean deformation is the
+> gate on everything downstream and cannot be reached by procedural auto-weights alone. Keep the
+> DRAFT PR open/unmerged; human test still deferred.

reports/visual/v0-animation-correction/iteration-01/CRITIQUE.md

@@ -0,0 +1,27 @@
+# Loop 1 — Critique (lead self-review; independent critique queued per §21)
+
+## Confirmed working
+- **Real skeleton + skin:** `CHAR_Base_Average.glb` has `skins=1`, **19 joints**, `JOINTS_0 + WEIGHTS_0`
+  attributes, `animations=[Idle]`. Godot imports a `Skeleton3D` (19 bones) + `AnimationPlayer`
+  playing `Idle` with visible deformation. **The PR #6 "no skeleton" blocker is resolved.**
+- Three distinct body profiles (slim/average/broad) from one rig; ~1.8 m scale; smooth stylized
+  silhouette that clearly beats both capsules and the static boxes.
+
+## Observed deformation defects (honest)
+1. **Shoulder → torso junction creases** — the clavicle/upperarm weights pinch where the arm
+   meets the chest (visible in `joint-closeup.png`). The weakest joint. **Auto-weight limit.**
+2. **Elbows / knees are "segment" joints** — upper/lower capsules meet with slight volume loss
+   under bend; acceptable at idle, will show more under Walk (Loop 2).
+3. **Hands are spheres, no fingers** — fine at management distance, but prop grip (tray/plate)
+   will be approximate (prop-hand contact = Loop 3 risk).
+4. **Feet are simple blocks** — acceptable; toe articulation absent.
+5. **Tri budget high: ~11,800 tris/char** (subsurf-1). ~25 characters ≈ 295k tris — OK on M3 Max
+   but wants a LOD / lower-subsurf pass before crowding the scene.
+6. Hip/pelvis deformation untested until Sit (Loop 3) and Walk (Loop 2).
+
+## Procedural vs manual (deformation ceiling)
+- **Solvable procedurally:** overall silhouette, body profiles, elbow/knee acceptable-for-early,
+  lower tri budget (decimate/LOD or subsurf-0 variant).
+- **Needs manual weight painting / corrective shapes (next-session Blender work):** clean
+  **shoulders**, **hips/pelvis under sit**, **wrists** for prop contact. Auto-weights will not
+  reach rubric Deformation ≥4 at these joints on this topology.

reports/visual/v0-animation-correction/iteration-01/DECISION.md

@@ -0,0 +1,13 @@
+# Loop 1 — Decision
+
+**ACCEPT as the working base** and proceed to Loop 2 (locomotion). The base meets Loop 1
+acceptance (real skeleton/skin/weights, deforms without major collapse, correct scale, better
+than PR #6). 
+
+**Carried forward as required next-session manual work (not attempted procedurally):**
+- Manual weight-paint the shoulders + hips; add corrective shape keys for shoulder and sit compression.
+- Add a subsurf-0 / decimated LOD1 for crowd use (drop from ~11.8k toward ~2-3k tris).
+- Better hands (at least a mitten/thumb split) for prop grip.
+
+**Estimated manual Blender hours to reach Deformation ≥4:** ~8-14 h (shoulders ~3, hips/sit ~3,
+wrists/hands ~2, corrective shapes ~2-4), plus ~2 h LOD. Out of scope for this automated session.

reports/visual/v0-animation-correction/iteration-01/HYPOTHESIS.md

@@ -0,0 +1,18 @@
+# Loop 1 — Deformation-ready character base
+
+**Hypothesis:** A continuous body (overlapping tapered cylinders + a Subdivision-Surface level
+applied *before* skinning) auto-weighted to a full 19-bone humanoid skeleton will deform
+markedly better than the PR #6 static pose-baked boxes, and will import into Godot as a real
+`Skeleton3D` + `AnimationPlayer` playing an Idle clip.
+
+**Target defect (from the PR #6 review):** characters had `skins=0, animations=0` — no skeleton,
+no deformation. Loop 1 must produce actual skeleton + skin + weights + a playing clip.
+
+**Method:** `tools/blender/build_rig.py` — build mesh, apply subsurf, build skeleton, parent with
+`ARMATURE_AUTO` weights, keyframe Idle, export GLB (`export_skins=True`, `export_animations=True`,
+`export_animation_mode='ACTIONS'`). Three body profiles (slim/average/broad) from the same rig.
+
+**Acceptance (§15 Loop 1):** skeleton+skin+weights exist; deforms without major collapse; scale
+matches the restaurant (~1.8 m); at least as appealing as the PR #6 static version.
+
+**Evidence:** `idle-lineup.png` (3 profiles), `joint-closeup.png` (Average, joint inspection).

reports/visual/v0-animation-correction/iteration-01/SCORES.md

@@ -0,0 +1,15 @@
+# Loop 1 — Rubric scores (lead self-assessment, 1-5; independent critique queued)
+
+Scoring only the dimensions Loop 1 addresses (the base in isolation, not the full scene):
+
+| Category | Score | Note |
+|---|---|---|
+| Role readability | n/a | roles come in Loop 3 (clothing/props) |
+| Deformation | 3 | functional; shoulders crease, elbows/knees segment-y (needs manual weights for ≥4) |
+| Character appeal (vs PR#6 static) | 4 | smooth mannequin, 3 profiles, clearly better than boxes |
+| Technical integrity | 4 | real skeleton(19)+skin+weights+clip; imports+plays clean; deterministic build |
+| Environment integration | n/a | Loop 3 |
+| Performance (asset) | 3 | 11.8k tris/char is high; LOD/decimate needed |
+
+Base average (scored dims): ~3.5. **Deformation 3 < the required final bar of 4** — this is the
+known ceiling; recorded, not hidden. Not a final-gate score (Loop 1 is a foundation).

reports/visual/v0-animation-correction/iteration-02/CRITIQUE.md

@@ -0,0 +1,16 @@
+# Loop 2 — Critique (lead; independent queued)
+
+## Working
+- Walk reads clearly as walking at the management camera; legs swing, arms counter-swing, torso bob.
+- **Facing works** (character turns to face each path segment); **grounding works** (feet at y=0,
+  contact shadow present; no float/sink). Runtime path movement is smooth. Walk loops cleanly.
+- WalkStop settle clip exists.
+
+## Defects (honest)
+1. **Mild–moderate foot sliding** — node speed (1.4 m/s) is not stride-matched to the clip, so feet
+   skate somewhat. Acceptable at management distance; needs speed↔stride tuning or root-motion-aware
+   speed. Not "severe," but not locked.
+2. **No blend between Idle↔Walk↔WalkStop** — clips hard-switch (no Godot AnimationTree yet). Start/stop
+   pops. AnimationTree blending is a later loop.
+3. **Knee/hip deformation under swing is segment-y** (Loop-1 ceiling) — reads fine small, shows at close range.
+4. Turns are instant (rotation snaps per segment) — fine for a demo; a turn clip/lerp would smooth it.

reports/visual/v0-animation-correction/iteration-02/DECISION.md

@@ -0,0 +1,6 @@
+# Loop 2 — Decision
+ACCEPT locomotion as functional; proceed to Loop 3 (task language + scene integration).
+Carried forward (next-session): stride↔speed matching to kill foot slide (~1-2 h); a Godot
+AnimationTree for Idle/Walk/Stop blending (~2-3 h); optional turn clip; hip/knee weight-paint
+(folded into the Loop-1 manual deformation pass). PERF: recording ran at movie-maker cadence;
+real GPU-timed scene perf is measured in Loop 3 integration.