docs(specs): spec 039 - example pipeline fidelity

[danko-nobre]

Spec for the three systemic defects the mixed-feature fixture (spec 035 / PR #113) surfaced. They are present across every synced example, not unique to that fixture - inspecting the new fixture just made them visible.

The three defects

1. Wrapper script paths - every examples/*/godot/<Name>.tscn references res://examples/<name>/godot/<Name>.gd, but sync_fixtures.py flattens godot/ to the root (its own docstring documents the flat convention). So every wrapper scene fails to load its script.
2. Blank textures - opening any imported example shows white Polygon2D / Sprite2D. The .proscenio data is correct (a headless build with the atlas applies every texture); the editor-import path bakes the .scn before the sibling image is imported, so the baked scene carries no texture.
3. Bone orientation - bones authored tail -Y project to angle 0, so Godot rests every Bone2D at +X (edge-on). This matches the hand-authored skinned_dummy oracle, so it is the current convention, not a bug - but it reads as a flattened rig, and pointing bones anatomically collides with the documented +Z "collapses polygons" limitation. A convention decision, gated.

Verdict

2 now (wrapper paths, texture ordering - what makes examples openable and visible), 1 gate (bone orientation, pending a decision among three options laid out in the STUDY).

Docs only (STUDY + TODO). No code in this PR; the work lands spec-by-spec after.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Added Spec 039 study detailing issues affecting synced example fidelity and a verdict with recommended resolution paths.
  • Added a sequenced TODO roadmap outlining immediate and deferred work: wrapper/script path fixes, import-ordering and texture rendering diagnostics/fixes, expanded end-to-end testing against baked goldens, and a plan for a bone-orientation convention decision.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: c7a21628-776a-4ca0-b3ef-54c7250337ff

📥 Commits

Reviewing files that changed from the base of the PR and between a02890a and 5ec11c1.

📒 Files selected for processing (2)

• specs/039-example-fidelity/STUDY.md
• specs/039-example-fidelity/TODO.md

✅ Files skipped from review due to trivial changes (2)

• specs/039-example-fidelity/STUDY.md
• specs/039-example-fidelity/TODO.md

📜 Recent review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Analyze (javascript-typescript)
• GitHub Check: Analyze (python)

---

📝 Walkthrough

Walkthrough

Adds Spec 039 materials: a STUDY documenting four systemic Godot example fidelity issues (wrapper script paths, editor import texture ordering, exported bone orientation, test/golden coverage) and a TODO with three PR tracks plus a deferred bone-orientation decision gate.

Changes

Spec 039: Example Pipeline Fidelity

Layer / File(s)	Summary
Problem analysis and assessment specs/039-example-fidelity/STUDY.md	Spec document describing four systemic issues (wrapper script path references after fixture flattening, editor import-time texture ordering causing blank sprites, exported bone orientation convention, and Godot test coverage consuming only hand-authored inputs). Contains assessment table, verdict “3 now, 1 gate, 0 drop,” and bone-orientation decision options.
Work plan and TODO roadmap specs/039-example-fidelity/TODO.md	Sequenced TODO: PR 1 rewrite ext_resource wrapper script paths + headless verification; PR 2 diagnose/fix importer texture dependency/order and editor verification; PR 3 CI smoke tests using Blender-baked goldens and fixture audit/retirement; Deferred gate for bone-screen-orientation sequencing.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• firebound/proscenio#38: Adds a concrete examples/mouth_drive/mouth_drive.expected.proscenio fixture and related build/wrapper pieces relevant to validating baked golden fixtures in CI.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs(specs): spec 039 - example pipeline fidelity' accurately and specifically describes the main change: adding documentation for Spec 039 covering example pipeline fidelity issues.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/spec-039-example-fidelity

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch docs/spec-039-example-fidelity

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@specs/039-example-fidelity/STUDY.md`:
- Around line 17-18: The wrapper scenes (e.g., SlotCycle.tscn, AtlasPack.tscn,
MixedFeature.tscn) have incorrect ext_resource script paths pointing to
res://examples/<name>/godot/<Name>.gd which the sync flattens away; update only
the .gd ext_resource entries in each wrapper scene to reference the flattened
path res://examples/<name>/<Name>.gd (leave the .tscn/proscenio instanced-scene
paths unchanged) so the wrappers match the documented flat-sync convention and
no longer load missing-dependency errors.

In `@specs/039-example-fidelity/TODO.md`:
- Line 10: Update the verification step so it explicitly loads each synced
wrapper scene instead of only starting Godot headless: modify the process that
runs python scripts/godot/sync_fixtures.py to, after syncing, iterate the synced
wrapper paths (res://examples/<name>/<Name>.tscn) and attempt to open/load each
scene (e.g., via a Godot headless CLI call or a small Godot script invoked per
scene) and fail the check if any scene reports "Load failed due to missing
dependencies" or ext_resource load errors; reference sync_fixtures.py and the
wrapper scene paths to implement the per-scene load and clear error reporting.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a67169cf-bcb8-4a96-a288-a91624fb6dfe

📥 Commits

Reviewing files that changed from the base of the PR and between 34aec4a and 8a5c5f7.

📒 Files selected for processing (2)

• specs/039-example-fidelity/STUDY.md
• specs/039-example-fidelity/TODO.md

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Analyze (python)