docs: document abort_velocity_threshold interaction with the stop threshold

Per review feedback: the velocity abort is evaluated on the same filtered
velocity signal as stop detection (IsStopped = velocity < StopVelocityThreshold),
so the two gates partition one velocity axis in opposite directions. Document that
abort_velocity_threshold must stay >= the operative StopVelocityThreshold (else a
locked stop instantly aborts), and that because StopVelocityThreshold is shaped
(60->8 via the GAIN updater) while the abort is a fixed absolute, the abort may
only be enabled where the stop gate is already floored below it. Add the matching
rationale where the grid stages set 15 against their static stop threshold of 8.

Docstring only; schema/*.json and Generated.cs must be regenerated on the rig.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: galenlynch

src/packages/aind_behavior_vr_foraging/src/aind_behavior_vr_foraging/task_logic.py

@@ -205,8 +205,20 @@ class OperantLogic(BaseModel):
         ge=0,
         description="Velocity (cm/s) above which an in-progress operant choice is aborted. This is an ADDITIONAL "
         "abort source: the choice aborts if velocity exceeds this OR displacement exceeds grace_distance_threshold "
-        "OR the animal leaves the reward site. None disables only the velocity source (grace + leave-site still apply).",
-    )  # NOTE: in InstantiateSite.bonsai, add a velocity-abort branch ALONGSIDE the grace/leave-site sources (do not replace them).
+        "OR the animal leaves the reward site. None disables only the velocity source (grace + leave-site still apply). "
+        "Interaction with the stop threshold: this is evaluated on the SAME filtered velocity signal as stop "
+        "detection, which locks a choice when velocity falls BELOW StopVelocityThreshold "
+        "(UpdaterTarget.STOP_VELOCITY_THRESHOLD, seeded from the position-control velocity_threshold and shaped "
+        "within/across sessions). The two gates partition the same velocity axis in opposite directions, so this "
+        "value must be >= the operative StopVelocityThreshold: if it is lower, the band "
+        "(abort_velocity_threshold, StopVelocityThreshold) lets the animal lock a stop while already too fast to "
+        "hold it, forfeiting every such choice. Because StopVelocityThreshold is dynamic (e.g. shaped 60 -> 8 cm/s "
+        "by a GAIN updater) whereas this is a fixed absolute, only enable the velocity abort on stages where the "
+        "stop threshold is already floored below it (e.g. a static stop threshold of 8 with this set to 15); never "
+        "pair a low fixed abort with an actively-shaped, still-high stop threshold.",
+    )  # Implemented in InstantiateSite.bonsai as a third input merged ALONGSIDE the grace-distance and leave-site
+    # sources (the CheckDistanceFromEntry groups under WaitDelay and WaitForLick), comparing
+    # FilteredCurrentVelocity.Item1 -- the same signal used for stop detection -- against this value.
 
 
 class _PatchUpdateFunction(BaseModel):

src/packages/aind_behavior_vr_foraging_curricula/src/aind_behavior_vr_foraging_curricula/single_site/stages.py

@@ -151,6 +151,11 @@ def _probability_grid_blocks(
     # grace_distance_threshold raised to 50 cm (a full reward-site length, vs the 10 cm
     # default) so the spatial source does not also clip that creep -- here velocity and
     # leaving the site do the work, with grace only a far backstop.
+    # The 15 sits safely above this stage's stop velocity threshold (a static 8 -- the grid
+    # stages carry no STOP_VELOCITY_THRESHOLD updater, so the gate does not shape up into it).
+    # abort_velocity_threshold must stay >= the stop threshold or a locked stop would instantly
+    # abort; that is why the abort is off on learn_to_stop, where the gate is still shaping 60->8.
+    # See OperantLogic.abort_velocity_threshold for the full interaction.
     make_patch_kwargs = {
         **_POST_STOP_PATCH_KWARGS,
         "delay": delay,