Incident cause-inference (spin/wall/contact-partner) spec + plan

docs/INCIDENT-SCORECARD-TEST-PLAN.md

@@ -124,8 +124,12 @@ detected-vs-expected counts match for every driver, not just you?
   *other* cars, which is the harder, less-tested half of the system.
 
 **Open questions this run should answer (not yet known):**
-- Does `live_incident_totals_resolved` (today's new live-totals backfill) ever fire in a practice
-  session, or only in races? (Phase 9)
+- ~~Does `live_incident_totals_resolved` ever fire in a practice session, or only in races?~~
+  **ANSWERED 2026-07-19, outside this plan's own run** — confirmed live during an actual hosted
+  session (subsession 87331584, Spa-Francorchamps): fired the moment `session_num` rolled `0→1`
+  (practice segment ending, race/quali segment starting), not tied to the whole event finishing.
+  18 drivers, 7 total points, correctly broadcast. Results go official per-*segment*, not just
+  per-event.
 - Does pit-lane speeding produce any SDK-visible signal at all via the fields we already read? (Phase 7)
 - Does a genuinely light wall touch register as 0x (silently, correctly) or does our detector
   currently over-report it? (Phase 4.1)

docs/IRACING-CROSSWALK.md

@@ -56,7 +56,7 @@
 | LatAccel | float | P | Lateral acceleration (DamageReporting.cs — impact G classification) | not yet used | Player-only; future severity classification |
 | LongAccel | float | P | Longitudinal acceleration (DamageReporting.cs — braking/impact) | not yet used | Player-only; future severity classification. Named LonAccel in some SDK versions |
 | VertAccel | float | P | Vertical acceleration (DamageReporting.cs — airborne detection) | not yet used | Useful for flip/airborne |
-| YawRate | float | P | Yaw rotation rate (DamageReporting.cs — spin detection) | not yet used | Player-only; future severity classification |
+| YawRate | float | P | **Not present in CrewChief** — verified via GitHub code search across the full repo, 0 hits. `DamageReporting.cs` has no yaw/spin logic (confirmed by direct source read); it does airborne/rollover detection off `Rotation` plus impact-severity off Lat/Long/VertAccel only. Prior entry attributing this to "DamageReporting.cs — spin detection" was wrong. | not yet used | Player-only even if we build our own; no `CarIdxYawRate` array exists |
 | CarIdxGear | int[64] | B | Gear per car (iRacingGameStateMapper) | Incident index — gear context (0=neutral, -1=reverse) | 0 during incidents suggests loss of control |
 
 ---
@@ -259,7 +259,7 @@ All `CarIdx*` arrays are indexed 0-63 (max 64 cars). Index corresponds to `CarId
 | LatAccel | float | P | Lateral G (DamageReporting.cs) | not yet used | Player-only; future severity classification |
 | LongAccel | float | P | Longitudinal G (DamageReporting.cs) | not yet used | Player-only; future severity classification |
 | VertAccel | float | P | Vertical G (DamageReporting.cs) | not yet used | m/s^2 |
-| YawRate | float | P | Spin rate (DamageReporting.cs) | not yet used | Player-only; future severity classification |
+| YawRate | float | P | **Not present in CrewChief** (see Section 2 entry for verification detail) | not yet used | Player-only; no per-car equivalent |
 | Pitch | float | P | Car pitch angle (iRacingData.cs) | not yet used | Radians |
 | Yaw | float | P | Car yaw angle (iRacingData.cs) | not yet used | Radians |
 | Roll | float | P | Car roll angle (iRacingData.cs) | not yet used | Radians |

docs/REVIEW-incident-points-implementation.md

@@ -185,4 +185,34 @@ on-track / any-car material scan.
 7. **IMPROVEMENT 11** — self-contained escalation rows (location on the final-state row).
 8. **IMPROVEMENT 8** — board growth cap / delta broadcast.
 9. **TEST-GAP 9** — cover items 2, 3, 5, and board concurrency.
+
+---
+
+## GAP 12 — No spin / loss-of-control detector exists (2026-07-25)
+
+- **What's missing:** none of the current detection sources (`repair_flag`, `furled_flag`, `black_flag`,
+  `disqualify`, `player_incident_count`, `track_surface`, `yaml_incident_delta`, `fast_repair` — see
+  `ReplayIncidentIndexDetection.cs`) directly detect a spin. `IncidentCauseMapping.CauseSpin` ("spin") only
+  ever gets assigned as a side effect of a *resolved* points value of exactly 2 — which in practice means
+  only the player's own live `PlayerCarMyIncidentCount` delta, since no other car's points resolve live
+  (Group 1, `docs/IRACING-DATA-AVAILABILITY.md`). For every other car, a spin is invisible unless it happens
+  to also trip off-track, a flag, or a fast repair.
+- **Confirmed no prior art in CrewChief:** GitHub code search across the full `mrbelowski/CrewChiefV4` repo
+  found zero occurrences of `YawRate` anywhere, and `Yaw` only as an unused raw struct field in
+  `iRacingData.cs`. `DamageReporting.cs` and `iRacingSpotter.cs`/`NoisyCartesianCoordinateSpotter.cs` were
+  read directly — no yaw-rate, angular-velocity, or heading-change logic anywhere. `docs/IRACING-CROSSWALK.md`
+  previously miscited `DamageReporting.cs` for this and has been corrected.
+- **Confirmed no SDK-level event either:** iRacing's `SessionFlags` bitfield (all 32 bits enumerated in
+  `docs/IRACING-CROSSWALK.md` Appendix A) has no spin/loss-of-control bit. There is no dedicated "car X
+  spun" signal anywhere in the SDK, live or replay, for any car.
+- **What a from-scratch heuristic could use (any car, no admin):** `CarIdxLapDistPct` (position, 60Hz),
+  `CarIdxRPM` (direct), `CarIdxGear` (0/neutral during an incident is already flagged as a loose hint in
+  `IRACING-CROSSWALK.md`'s Section 2 notes, never acted on). Speed has no direct per-car field — it would
+  need to be derived by differentiating `CarIdxLapDistPct × track length` over time, same derivation noted
+  as a general SDK limitation in `docs/IRACING-DATA-AVAILABILITY.md` Group 2. A real yaw signal
+  (`Yaw`/`YawRate`) would be needed for a confident spin read and is player-only — no `CarIdxYaw` array
+  exists — so any heuristic built from position/speed/RPM/gear would be an approximation, not a confirmed
+  spin detection, exactly like the existing off-track/contact detectors already are for point values.
+- **Status:** not scheduled — flagged for a future planning pass, not part of the priority order above
+  (items 1-9 are fixes to the shipped feature; this is a net-new detector that doesn't exist yet).
 10. **UX residual** — "these tabs count differently" note (live merged vs. replay unmerged).