add clear path before pick example

Author: rsasaki0109

README.md

@@ -11,10 +11,10 @@ robotics loops rather than standalone algorithms.
 
 ## Current Status
 
-- 29 runnable examples
+- 30 runnable examples
 - 20 learning-path roadmap examples
-- 28 README GIFs generated from runnable examples
-- 72 smoke and regression tests
+- 29 README GIFs generated from runnable examples
+- 73 smoke and regression tests
 - Core dependencies only: `numpy` and `matplotlib`
 
 See `docs/status.md` for the implementation snapshot and `docs/plan.md` for
@@ -104,6 +104,10 @@ These GIFs are generated from the runnable examples, not separate animations.
 | --- | --- |
 | ![A grasp agent keeps a belief over three pose hypotheses, picks the grasp with highest expected success, misses, runs a Bayes update, and tries a different grasp.](docs/assets/gifs/belief_grasp_selection.gif) | ![A grasp agent looks from the viewpoint that maximally reduces occlusion under its pose belief, updates the belief from each observation, then grasps with the type that maximizes expected success.](docs/assets/gifs/active_viewpoint_for_grasp.gif) |
 
+| Clear path before pick |
+| --- |
+| ![A tabletop agent tries to pick the target, gets a precondition failure because an obstacle blocks the gripper path, picks the obstacle, places it in the clear zone, and retries the original pick.](docs/assets/gifs/clear_path_before_pick.gif) |
+
 ### Navigation and recovery
 
 | Reactive obstacle avoidance | Dynamic obstacle avoidance |

docs/assets/gifs/clear_path_before_pick.gif

@@ -30,6 +30,7 @@
 7. `examples/manipulation/07_probabilistic_suction_sorting.py`
 8. `examples/manipulation/08_belief_grasp_selection.py`
 9. `examples/manipulation/09_active_viewpoint_for_grasp.py`
+10. `examples/manipulation/25_clear_path_before_pick.py`
 
 ## Embodied AI
 

docs/learning_paths.md

@@ -8,11 +8,11 @@ first-run experience small, fast, and failure-aware.
 
 The repository currently has:
 
-- 29 runnable examples
+- 30 runnable examples
 - 20 numbered learning-path examples
-- 9 extra examples outside the original learning-path roadmap
-- 28 generated README GIFs
-- 72 smoke and regression tests
+- 10 extra examples outside the original learning-path roadmap
+- 29 generated README GIFs
+- 73 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`,
@@ -112,6 +112,10 @@ Recent completed work:
   then runs A* with full information to either a short route through the
   gate or a longer detour through the bottom opening. GIF and two smoke
   tests (open and closed gate) cover the loop.
+- `examples/manipulation/25_clear_path_before_pick.py` was added. The
+  agent tries to pick the target, hits a `precondition_blocked` failure,
+  picks the obstacle, places it in a known clear zone, and retries the
+  original pick. GIF and smoke test cover the loop.
 
 The next agent should not redo those items. If any of them seem missing, first
 check the current branch and latest pulled commit.
@@ -276,13 +280,14 @@ Already done from the previous tier:
   detection -> system_id probe -> model update -> resume.
 - `examples/navigation/24_information_gain_navigation.py` — scout the
   gate -> reveal candidate state -> A* with full information.
+- `examples/manipulation/25_clear_path_before_pick.py` — try target ->
+  precondition fails -> pick obstacle -> place in clear zone -> retry.
 
 Recommended next examples:
 
 | Priority | Example | Area | Loop |
 | --- | --- | --- | --- |
-| 1 | `examples/manipulation/25_clear_path_before_pick.py` | manipulation | precondition failure -> clear obstacle -> pick |
-| 2 | `examples/navigation/27_multi_agent_avoidance.py` | navigation | observe agents -> avoid -> replan |
+| 1 | `examples/navigation/27_multi_agent_avoidance.py` | navigation | observe agents -> avoid -> replan |
 
 Selection rule:
 

docs/plan.md

@@ -5,10 +5,10 @@ see what exists, what is verified, and what should come next.
 
 ## Snapshot
 
-- Runnable examples: 29
+- Runnable examples: 30
 - Learning-path roadmap examples: 20
-- README GIFs: 28
-- Smoke and regression tests: 72
+- README GIFs: 29
+- Smoke and regression tests: 73
 - Core dependencies: `numpy`, `matplotlib`
 - Contributor extra: `pip install -e ".[dev]"`
 - CI: Python 3.10, 3.11, 3.12
@@ -30,7 +30,7 @@ goal-command example. The numbered 20-example roadmap is tracked in
 | --- | ---: | --- |
 | Runtime | 2 | smallest observe-act-observe loop, trace replay |
 | Navigation | 10 | reactive avoidance, dynamic obstacles, replanning, exploration, belief, active SLAM, MPC, recovery, localization recovery, information-gain detour |
-| Manipulation | 9 | retry, reactive grasping, IK servo, moving target reaching, search, push recovery, suction sorting, belief grasp selection, active viewpoint grasp |
+| 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, memory query revisit |
 | World models | 2 | action-conditioned dynamics, prediction error, model update, replanning, regime-shift detection, system identification |
 

docs/status.md

@@ -40,6 +40,7 @@ Run any example headless with its `--no-render` flag when available.
 | `manipulation/07_probabilistic_suction_sorting.py` | `python examples/manipulation/07_probabilistic_suction_sorting.py` | suction miss -> update probability -> prepare -> sort |
 | `manipulation/08_belief_grasp_selection.py` | `python examples/manipulation/08_belief_grasp_selection.py` | pose belief -> grasp choice -> miss -> update -> retry |
 | `manipulation/09_active_viewpoint_for_grasp.py` | `python examples/manipulation/09_active_viewpoint_for_grasp.py` | choose view -> reduce occlusion -> grasp |
+| `manipulation/25_clear_path_before_pick.py` | `python examples/manipulation/25_clear_path_before_pick.py` | try pick -> precondition fails -> clear obstacle -> retry |
 
 ## Embodied AI