add safety_filter_cbf example

A new navigation example that teaches runtime safety as a separate
layer. The agent is split into two pieces:

- a naive nominal policy that ignores obstacles and points straight at
  the goal
- a runtime safety filter that, at every step, checks the
  control-barrier-function condition dh/dt >= -alpha * h for each
  obstacle and projects the nominal velocity onto the closest safe
  half-space when it would be violated

This is intentionally a different lesson from
02_reactive_obstacle_avoidance (the policy itself avoids obstacles) and
08_interactive_mpc (avoidance is folded into rollout cost). Here the
policy stays naive on purpose; the filter is what keeps the robot safe.

The info dict exposes u_nominal, u_safe, barrier_h_min, closest_approach,
filter_active, filter_active_count, and stuck_count. A recoverable
Failure(kind='safety_filter_stuck') fires when the projected velocity
falls below the stuck threshold for a step. Smoke test asserts that the
filter actually engages (filter_active_count >= 5), that u_nominal and
u_safe differ on at least one step, and that the goal is reached with
zero stuck steps under seed=0.

Counts move to 32 examples / 31 GIFs / 80 tests / 12 navigation
examples. The follow-up consultation with GPT Pro that produced this
example, the 22 removal, and the 04/09 keep-both decision is recorded
in docs/implementation_gap_audit.md.

Author: rsasaki0109

README.md

@@ -11,10 +11,10 @@ robotics loops rather than standalone algorithms.
 
 ## Current Status
 
-- 31 runnable examples
+- 32 runnable examples
 - 20 learning-path roadmap examples
-- 30 README GIFs generated from runnable examples
-- 79 smoke and regression tests
+- 31 README GIFs generated from runnable examples
+- 80 smoke and regression tests
 - Core dependencies only: `numpy` and `matplotlib`
 
 See `docs/status.md` for the implementation snapshot and `docs/plan.md` for
@@ -134,6 +134,10 @@ These GIFs are generated from the runnable examples, not separate animations.
 | --- | --- |
 | ![A grid robot scouts an observation point to reveal an unknown gate state, then runs A* with full information to either the short route or the long detour.](docs/assets/gifs/information_gain_navigation.gif) | ![A grid robot shares the grid with two goal-seeking other agents, predicts each agent's next step, and A* around the predicted cells to reach its own goal.](docs/assets/gifs/multi_agent_avoidance.gif) |
 
+| Safety filter (CBF) |
+| --- |
+| ![A point robot's naive go-to-goal nominal velocity is projected at each step onto a control-barrier-function half-space for each obstacle, sliding around them without the policy itself ever knowing they exist.](docs/assets/gifs/safety_filter_cbf.gif) |
+
 ### Embodied AI
 
 | Goal command pick | Door search POMDP |

docs/assets/gifs/safety_filter_cbf.gif

@@ -6,10 +6,10 @@ continuous-control Gymnasium adapter, and the curiosity exploration example.
 
 ## Current Stable Surface
 
-- 31 runnable examples
-- 20 numbered learning-path examples plus 11 extras
-- 30 generated README GIFs with nonblank checks
-- 79 smoke, adapter, and regression tests
+- 32 runnable examples
+- 20 numbered learning-path examples plus 12 extras
+- 31 generated README GIFs with nonblank checks
+- 80 smoke, adapter, and regression tests
 - CI green on Python 3.10, 3.11, and 3.12
 - Gymnasium-style adapters for `GridWorld2D`, `DynamicObstacleGridWorld`,
   `BlockedPathWorld`, `MovingObstacleWorld`, and `Tabletop2D`

docs/implementation_gap_audit.md

@@ -8,11 +8,11 @@ first-run experience small, fast, and failure-aware.
 
 The repository currently has:
 
-- 31 runnable examples
+- 32 runnable examples
 - 20 numbered learning-path examples
-- 11 extra examples outside the original learning-path roadmap
-- 30 generated README GIFs
-- 79 smoke and regression tests
+- 12 extra examples outside the original learning-path roadmap
+- 31 generated README GIFs
+- 80 smoke and regression tests
 - GitHub Actions CI for Python 3.10, 3.11, and 3.12
 - core dependencies limited to `numpy` and `matplotlib`
 - optional Gymnasium-style adapters for `GridWorld2D`,
@@ -104,6 +104,15 @@ Recent completed work:
   `21_object_permanence_toy.py` without adding a clearly different lesson.
   The remaining cognitive-robotics example for memory under loss of
   observation is `21_object_permanence_toy.py`.
+- `examples/navigation/29_safety_filter_cbf.py` was added. A naive
+  go-to-goal nominal policy is paired with a separate runtime safety
+  filter that, at every step, projects the nominal velocity onto the
+  closest CBF-style safe half-space for each obstacle. The example
+  exposes `u_nominal`, `u_safe`, `barrier_h_min`, `closest_approach`,
+  `filter_active_count`, and `stuck_count` in `info`, and surfaces a
+  recoverable `safety_filter_stuck` Failure when the projection clips
+  the velocity below the stuck threshold. GIF and smoke test cover the
+  loop.
 - `examples/world_models/23_model_error_recovery.py` was added. The agent
   starts with an identity dynamics model, detects a regime shift when
   prediction error spikes, runs a short system-identification probe phase,

docs/plan.md

@@ -5,10 +5,10 @@ see what exists, what is verified, and what should come next.
 
 ## Snapshot
 
-- Runnable examples: 31
+- Runnable examples: 32
 - Learning-path roadmap examples: 20
-- README GIFs: 30
-- Smoke and regression tests: 79
+- README GIFs: 31
+- Smoke and regression tests: 80
 - Core dependencies: `numpy`, `matplotlib`
 - Contributor extra: `pip install -e ".[dev]"`
 - CI: Python 3.10, 3.11, 3.12
@@ -29,7 +29,7 @@ goal-command example. The numbered 20-example roadmap is tracked in
 | Area | Examples | Main concepts |
 | --- | ---: | --- |
 | Runtime | 2 | smallest observe-act-observe loop, trace replay |
-| Navigation | 11 | reactive avoidance, dynamic obstacles, replanning, exploration, belief, active SLAM, MPC, recovery, localization recovery, information-gain detour, multi-agent avoidance |
+| Navigation | 12 | reactive avoidance, dynamic obstacles, replanning, exploration, belief, active SLAM, MPC, recovery, localization recovery, information-gain detour, multi-agent avoidance, CBF safety filter |
 | Manipulation | 10 | retry, reactive grasping, IK servo, moving target reaching, search, push recovery, suction sorting, belief grasp selection, active viewpoint grasp, clear path before pick |
 | Embodied AI | 6 | controlled goals, memory, POMDP search, tiny VLA loop, object permanence, curiosity exploration |
 | World models | 2 | action-conditioned dynamics, prediction error, model update, replanning, regime-shift detection, system identification |

docs/status.md

@@ -27,6 +27,7 @@ Run any example headless with its `--no-render` flag when available.
 | `navigation/10_localization_uncertainty_recovery.py` | `python examples/navigation/10_localization_uncertainty_recovery.py` | ambiguous pose -> information action -> resume goal |
 | `navigation/24_information_gain_navigation.py` | `python examples/navigation/24_information_gain_navigation.py` | scout observation -> reveal gate -> A* with full info |
 | `navigation/27_multi_agent_avoidance.py` | `python examples/navigation/27_multi_agent_avoidance.py` | observe agents -> predict next -> A* around predictions |
+| `navigation/29_safety_filter_cbf.py` | `python examples/navigation/29_safety_filter_cbf.py` | nominal u -> CBF projection -> safe u |
 
 ## Manipulation