name: headtracking-companion-runtime description: Validate and harden LocusQ companion runtime behavior for head-tracking readiness, sync/center gating, frame mapping, axis sanity, and deterministic operator diagnostics.

Title: Headtracking Companion Runtime Skill Document Type: Skill Author: APC Codex Created Date: 2026-03-01 Last Modified Date: 2026-03-01

Headtracking Companion Runtime

Use this skill for companion runtime stability and diagnostics work tied to BL-053/BL-058 class issues.

Readiness state machine behavior:
- disabled_disconnected
- active_not_ready
- active_ready
Sync/center gating and startup baseline behavior.
Axis/frame sanity (yaw/pitch/roll), sensor-location transitions, and forward-vector correctness.
Companion-to-plugin observability checks (packet freshness, sequence continuity, active pose age).

Confirm readiness contract first.
- Verify the companion starts in a safe, non-streaming state when devices are not ready.
- Verify send gate remains closed until explicit sync/center action in ready state.
Validate frame contract and axis semantics.
- Canonical frame: +X right, +Y up, -Z ahead.
- Ensure principal-axis sweeps show dominant expected movement.
Validate pose freshness behavior.
- Stale packets must not keep driving orientation visuals.
- Explicit stale fallback orientation should be observable.
Validate relaunch and sensor transitions.
- Confirm reconnection does not silently preserve bad startup offsets.
- Confirm sensor-location switch is visible and deterministic.
Capture deterministic evidence packet.

Pair with threejs for visualization/render-loop issues.
Pair with juce-webview-runtime for bridge/startup hydration ordering faults.
Pair with spatial-audio-engineering when plugin-side orientation math must be validated in parallel.
Pair with skill_troubleshooting for unresolved regressions or inversion/drift loops.