'why' + extend max_allowed_time_to_collision_up_to_carrot context (#882)

Signed-off-by: EricoMeger <ericomeger9@gmail.com>

Author: EricoMeger

configuration/packages/configuring-regulated-pp.rst

@@ -239,7 +239,7 @@ Regulated Pure Pursuit Parameters
   ============== =============================
 
   Description
-    The time (s) to project a velocity command forward to check for collisions when ``use_collision_detection`` is ``true``. Pre-``Humble``, this was ``max_allowed_time_to_collision``.
+    The time (s) to forward-simulate the current velocity command to check for collisions when ``use_collision_detection`` is ``true``. At each simulation step, the robot's footprint is projected forward by the costmap resolution. The simulation stops at whichever limit is reached first: this time limit or the carrot distance. If a collision is detected at any projected pose, the robot will stop. When ``min_distance_to_obstacle`` is set, this time limit may be automatically extended to ensure the minimum obstacle distance can be checked at the current velocity. Pre-``Humble``, this was ``max_allowed_time_to_collision``.
 
 :use_regulated_linear_velocity_scaling:
 
@@ -444,6 +444,17 @@ Regulated Pure Pursuit Parameters
     Whether to use the Dynamic Window Pure Pursuit (DWPP) Algorithm. This algorithm computes command velocities that track the path as accurately as possible while respecting velocity and acceleration constraints. It automatically slows down in sharp turns without manual tuning, reducing path tracking errors.
     Fumiya Ohnishi and Masaki Takahashi, "Dynamic Window Pure Pursuit for Robot Path Tracking Considering Velocity and Acceleration Constraints", the 19th International Conference on Intelligent Autonomous Systems (IAS-19), 2025.
 
+:allow_obstacle_checking_beyond_goal:
+
+  ============== =============================
+  Type           Default
+  -------------- -----------------------------
+  bool           false
+  ============== =============================
+
+  Description
+    Whether to continue obstacle checking past the goal position up to ``min_distance_to_obstacle``. When enabled, obstacles located beyond the goal along the projected trajectory may prevent motion. This can be useful when the goal pose is close to obstacles or when a safety margin must be enforced beyond the final path pose. For example, in constrained environments, users may prefer to ensure that obstacle checking continues slightly past the goal to avoid approaching obstacles that lie immediately beyond it. Requires ``use_velocity_scaled_lookahead_dist`` to be enabled and ``min_distance_to_obstacle`` > 0.0.
+
 
 Example
 *******
@@ -502,3 +513,4 @@ Example
         min_distance_to_obstacle: 0.0
         stateful: true
         use_dynamic_window: false
+        allow_obstacle_checking_beyond_goal: false

migration/Kilted.rst

@@ -813,3 +813,15 @@ New IsWithinPathTrackingBounds Node
 -----------------------------------
 
 In `PR 5983 <https://github.com/ros-navigation/navigation2/pull/5983>`_, a new behavior tree node, ``IsWithinPathTrackingBounds``, was added to check if the robot is within specified bounds of the path for tracking purposes. See the `demo <https://github.com/ros-navigation/navigation2/blob/main/nav2_bt_navigator/behavior_trees/navigate_to_pose_w_bounds_check.xml>`_ for an example of how to use this node in a behavior tree.
+
+RPP: min_distance_to_obstacle fix and new allow_obstacle_checking_beyond_goal parameter
+---------------------------------------------------------------------------------------
+
+`PR #5677 <https://github.com/ros-navigation/navigation2/pull/5677>`_ resolves an issue where ``min_distance_to_obstacle`` was not properly enforced when ``use_velocity_scaled_lookahead_dist`` was enabled. Previously, collision checking was limited to the carrot distance, which at low speeds could be shorter than ``min_distance_to_obstacle``. For example, with ``min_lookahead_dist: 0.3``, ``min_distance_to_obstacle: 0.9``, and ``max_lookahead_dist: 1.5``, if the robot had not accelerated enough for the lookahead to reach 0.9m, obstacle checking would only cover up to the carrot position rather than the configured 0.9m. The collision checker now correctly extends the simulation distance to ``min_distance_to_obstacle`` (capped by ``max_lookahead_dist``) regardless of the current carrot distance.
+
+Additionally, warnings have been added to the parameter handler to alert users of configurations where ``min_distance_to_obstacle`` cannot be fully enforced:
+
+- When using ``use_velocity_scaled_lookahead_dist``, a warning is emitted if ``min_distance_to_obstacle`` exceeds ``max_lookahead_dist``.
+- When using a constant ``lookahead_dist``, a warning is emitted if ``min_distance_to_obstacle`` exceeds ``lookahead_dist``.
+
+A new parameter ``allow_obstacle_checking_beyond_goal`` (default: false) has also been added. By default, obstacle checking along the projected trajectory stops at the goal position (end of the path). When enabled, collision checking continues past the goal up to ``min_distance_to_obstacle``, regardless of the remaining path length. This parameter requires ``use_velocity_scaled_lookahead_dist`` to be enabled and ``min_distance_to_obstacle`` > 0.0.