headtracking-companion-runtime

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.

Scope

• 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).

Workflow

1. 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.
2. Validate frame contract and axis semantics.
   • Canonical frame: +X right, +Y up, -Z ahead.
   • Ensure principal-axis sweeps show dominant expected movement.
3. Validate pose freshness behavior.
   • Stale packets must not keep driving orientation visuals.
   • Explicit stale fallback orientation should be observable.
4. Validate relaunch and sensor transitions.
   • Confirm reconnection does not silently preserve bad startup offsets.
   • Confirm sensor-location switch is visible and deterministic.
5. Capture deterministic evidence packet.

Mandatory Evidence Packet

• status.tsv
• results.tsv
• axis_sweeps.md
• readiness_gate.md
• runtime_snapshot.md (if runtime telemetry capture is part of the run)

Cross-Skill Routing

• 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.

References

• references/state-machine-and-gating.md
• references/axis-sweep-and-frame-contract.md
• references/evidence-packet-contract.md

Deliverables

• Changed files with rationale.
• Explicit statement of which readiness/axis checks passed or failed.
• Validation status: tested, partially tested, or not tested.