1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
//! `gait-group` — clips in a declared directional blend ring must share
//! a gait phase (the stride anchor from the L−R foot-height
//! fundamental). If their cycles don't align, runtime blends between
//! them skate the feet. Members with too little L/R alternation are
//! excluded from the spread (their phase is noise); a member whose gait
//! cannot be measured at all is an error, so the group's coherence is
//! never silently unverified.
use crate::check::{Check, CheckCtx, Readiness};
use crate::checks::gait_readiness;
use crate::finding::{Finding, Severity};
use crate::metrics::{MIN_STRIDE_STEP_M, circular_phase_spread, foot_cycle_metrics};
pub struct GaitGroup;
impl Check for GaitGroup {
fn id(&self) -> &'static str {
"gait-group"
}
// gait-group is always Ready when groups exist: member existence is
// config validation that needs no rig roles, so it must run even on
// an unresolved rig. The role-dependent metric work inside `run` is
// gated separately, emitting one exempt skip-note.
fn readiness(&self, ctx: &CheckCtx) -> Readiness {
if ctx.config.gait_groups.is_empty() {
Readiness::Idle
} else {
Readiness::Ready
}
}
fn run(&self, ctx: &CheckCtx, out: &mut Vec<Finding>) {
// Roles gate the metric work only. `Some(reason)` means the rig
// did not resolve — measurable coherence is skipped with one
// exempt diagnostic, but member existence is still validated.
let roles_skip_reason = match gait_readiness(ctx.roles) {
Readiness::Ready => None,
Readiness::Skipped(reason) => Some(reason),
Readiness::Idle => None,
};
let mut roles_noted = false;
for (group_name, group) in &ctx.config.gait_groups {
let mut measured: Vec<(&str, f64)> = Vec::new();
for clip_name in &group.clips {
let Some(index) = ctx.doc.clips.iter().position(|c| &c.name == clip_name) else {
out.push(
Finding::new(
self.id(),
Severity::Error,
format!("gait group '{group_name}' member not found in file"),
)
.clip(clip_name.clone()),
);
continue;
};
if let Some(reason) = &roles_skip_reason {
// Member exists but the rig does not resolve: emit
// one exempt skip-note for the whole check, then
// stop measuring (member existence is already done).
if !roles_noted {
roles_noted = true;
out.push(
Finding::new(self.id(), Severity::Note, format!("skipped: {reason}"))
.as_diagnostic(),
);
}
continue;
}
// Roles resolved; `None` here means the member clip is
// too short to carry a cycle — a real problem for a
// declared ring member.
let gait = ctx
.grid(index)
.and_then(|grid| foot_cycle_metrics(&grid, ctx.roles, MIN_STRIDE_STEP_M));
let Some(metrics) = gait else {
out.push(
Finding::new(
self.id(),
Severity::Error,
format!(
"gait group '{group_name}' member has no measurable gait \
(clip too short) — the group's coherence is unverified"
),
)
.clip(clip_name.clone()),
);
continue;
};
if metrics.lr_amplitude_m < group.min_lr_amplitude_m {
continue; // phase-confidence floor: too little alternation
}
if let Some(phase) = metrics.gait_phase {
measured.push((clip_name, phase));
}
}
if measured.len() < 2 {
continue;
}
let phases: Vec<f64> = measured.iter().map(|(_, p)| *p).collect();
let spread = circular_phase_spread(&phases);
if spread > group.max_gait_phase_spread {
let listing = measured
.iter()
.map(|(n, p)| format!("{n}={p:.2}"))
.collect::<Vec<_>>()
.join(", ");
out.push(
Finding::new(
self.id(),
Severity::Error,
format!(
"gait group '{group_name}': stride-anchor phases spread by \
{spread:.2} cycle (cap {cap:.2}) — directional blends \
between these clips will skate or pop. Measured: [{listing}]",
cap = group.max_gait_phase_spread,
),
)
.measured(spread)
.expected(group.max_gait_phase_spread),
);
}
}
}
}