tighten example authoring guide

Expand the contract for new examples so contributors do not need to
read three existing examples to learn the conventions:

- pin the docstring header shape: loop, success condition, and each
  Failure kind (recoverable or terminal)
- add a 'New Failure Kind Checklist' and an expanded list of canonical
  kinds, including invalid_action and precondition_blocked
- add a 'Loop Counters' section that documents the _count suffix
  convention so Trace.summary() picks them up
- pin the README section headings (already consistent across the five
  category READMEs)
- add a 'Package Boundary' section pointing at
  pir/worlds/blocked_path.py and pir/worlds/moving_obstacle.py as the
  reference for environment extraction
- add a final 'Contributor Checklist' that maps each rule to a PR-level
  acceptance criterion

No code or example was changed; existing examples are grandfathered.

Author: rsasaki0109

docs/example_authoring.md

@@ -7,14 +7,14 @@ Examples should feel like readable experiment notes, not framework plugins.
 
 Each user-facing example should provide:
 
-- a short module docstring explaining the loop
+- a short module docstring that names the loop and declares success / failure
 - a tiny world or environment
 - a tiny agent or policy
 - a `run(...)` function that returns `Trace`
 - a `main()` function for script execution
 - a `--no-render` flag for headless tests
-- a focused smoke test
-- a README section explaining what is simplified
+- a focused smoke test in `tests/test_examples_smoke.py`
+- a README section in the matching `examples/<category>/README.md`
 
 The core loop should be visible:
 
@@ -37,6 +37,34 @@ for _ in range(max_steps):
         break
 ```
 
+## Docstring Header
+
+The first thing a reader sees should be enough to understand the loop without
+reading code. Every example module docstring should answer three questions:
+
+1. **What is the loop?** One paragraph naming the perception-action cycle.
+2. **What counts as success?** Concrete condition that flips
+   `info["success"]` to `True`.
+3. **What counts as failure?** Each `Failure.kind` the example can emit,
+   labelled `(recoverable)` or `(terminal)`.
+
+Example:
+
+```python
+"""Reactive obstacle avoidance with a fake lidar.
+
+The agent reads a discrete lidar reading at every step, picks a direction
+that keeps the closest obstacle outside the safety radius, and moves.
+
+Success: robot reaches the goal cell before max_steps.
+Failure: collision (recoverable - the agent retries from a safe cell) or
+timeout (terminal).
+"""
+```
+
+A short success/failure block lets `Trace.summary()` and the README captions
+stay aligned with the runnable example.
+
 ## Failure Contract
 
 Failures are part of the API. Do not hide them in print output.
@@ -61,12 +89,47 @@ Common failure kinds:
 - `blocked_grasp`
 - `suction_miss`
 - `container_closed`
+- `precondition_blocked`
 - `model_error`
 - `timeout`
+- `invalid_action`
+
+Recoverable failures should leave `done=False`. Terminal failures should
+leave `done=True` and have `recoverable=False`. Use `timeout` as the
+canonical terminal failure when the agent runs out of steps without
+success.
 
 The agent should usually update memory, belief, state, or plan after a
-recoverable failure. A retry should be different from repeating the same action
-blindly.
+recoverable failure. A retry should be different from repeating the same
+action blindly.
+
+### New Failure Kind Checklist
+
+When introducing a new `Failure.kind`:
+
+- pick a snake_case name that names the *cause*, not the symptom
+- check it does not duplicate an existing kind in the list above
+- decide `recoverable=True` or `recoverable=False` and stay consistent
+  across the example
+- add a regression assertion in
+  `tests/test_failure_contracts.py` if the kind has nontrivial recovery
+  semantics
+- document the kind in the example's docstring header and category README
+
+## Loop Counters
+
+Counters surfaced through `info` should:
+
+- end with `_count` so `Trace.summary()` picks them up automatically
+- be monotonic over the run
+- represent a teaching event (retries, replans, recoveries, persistences),
+  not raw step ticks
+
+Conventional names already in the repo: `retry_count`, `replan_count`,
+`recovery_count`, `miss_count`, `servo_steps`, `belief_updates`,
+`avoidance_count`, `target_switches`, `info_gain_step_count`,
+`recovery_count`, `memory_persistence_count`. Reuse these when the concept
+matches.
 
 ## Visualization Checklist
 
@@ -86,19 +149,26 @@ Useful visual elements:
 - state machine state
 - reward, cost, entropy, or model error when relevant
 
-Every major README GIF should be generated by `scripts/make_gifs.py` from the
-same runnable example.
+Every major README GIF should be generated by `scripts/make_gifs.py` from
+the same runnable example. The GIF caption in the root README should name
+the *internal* state that is being shown (belief, novelty, predicted
+rollout, ...), not just the visible motion.
 
 ## Example README Section
 
-Use this shape in `examples/<category>/README.md`:
+Use this shape in `examples/<category>/README.md`. The section headings
+are fixed so contributors can scan the file consistently:
 
 ````markdown
 ## `NN_example_name.py`
 
 ### What this teaches
 
-One short paragraph.
+One short paragraph naming the loop and the lesson. Mention the closest
+existing example and how this one differs.
+
+Success: ...
+Failure: kind_a (recoverable), kind_b (terminal).
 
 ### Run
 
@@ -121,6 +191,10 @@ observe -> update belief -> act -> observe failure -> retry
 - concrete modification ideas
 ````
 
+The `Success:` and `Failure:` lines under "What this teaches" mirror the
+docstring header so the README block stays in sync with the runnable
+example.
+
 ## Smoke Test Pattern
 
 Add a focused test in `tests/test_examples_smoke.py`:
@@ -131,29 +205,65 @@ def test_new_example_runs_headless() -> None:
 
     trace = module.run(seed=0, render=False, max_steps=40)
 
-    assert trace.infos[-1]["success"] is True
-    assert len(trace.actions) > 0
+    final = trace.infos[-1]
+    assert final["success"] is True
+    assert final["replan_count"] >= 1
+    assert any(failure.kind == "blocked_path" for failure in trace.failures())
 ```
 
-Add assertions for the concept being taught. For example, if the example is
-about recovery, assert that a relevant `Failure` appears in `trace.failures()`.
-Use `trace.summary()` when a test or README needs compact run-level statistics
-such as total reward, failure counts, or maximum `*_count` loop counters.
+Smoke tests should assert the concept being taught, not the implementation.
+Useful patterns:
+
+- assert `info["success"] is True` for the golden seed
+- assert a counter is at least the expected lower bound (use `>=`, not `==`)
+- assert a recoverable `Failure.kind` appears in `trace.failures()`
+- assert the loop terminates (`len(trace.actions) <= max_steps`)
+- use `trace.summary()` when a test or README needs compact run-level
+  statistics such as total reward, failure counts, or maximum `*_count`
+  loop counters
 
 ## GIF Addition Pattern
 
 If the example should appear in the root README:
 
-1. Add a `make_<name>()` function to `scripts/make_gifs.py`.
-2. Register it in `MAKERS`.
-3. Add the generated GIF to `README.md`.
+1. Add a `make_<name>()` function to `scripts/make_gifs.py` that imports
+   the example via `load_example(...)` and renders frames using the same
+   draw code the example uses.
+2. Register the maker in `MAKERS` with a short key.
+3. Add the generated GIF to the matching category README **and** the root
+   `README.md`.
 4. Install contributor dependencies and run:
 
 ```bash
 pip install -e ".[dev]"
 python scripts/run_all_smoke_tests.py --gifs --check-gifs
 ```
 
+The check verifies frame count and nonblank pixels for every generated
+GIF, and the Markdown asset check verifies that every linked image
+exists.
+
+## Package Boundary
+
+Keep agent code in the example. Keep environment code in the example *or*
+in `pir/worlds/`. The package boundary should make examples easier to
+read, not turn the repo into a framework.
+
+Move a world from an example into `pir/worlds/` when:
+
+- another example or adapter needs to import it
+- the world has a clean `reset()` / `observe()` / `step()` surface
+- moving it does not require lifting agent code
+
+Patterns to follow: `pir/worlds/blocked_path.py` and
+`pir/worlds/moving_obstacle.py`. Both expose `reset()`, `observe()`, and
+a `step()` that returns `StepResult`, and both keep their `draw_*_scene`
+helper next to the world so example modules stay focused on the agent.
+
+`step()` should return `StepResult` so the unwrap pattern
+`obs, reward, done, info = result.as_tuple()` works the same way across
+the codebase.
+
 ## When To Add Shared Code
 
 Keep logic local to the example first. Move code into `pir/` only when:
@@ -162,4 +272,22 @@ Keep logic local to the example first. Move code into `pir/` only when:
 - the shared code makes examples easier to read
 - the abstraction does not hide the interaction loop
 
-Small duplication is acceptable when it keeps examples readable.
+Small duplication is acceptable when it keeps examples readable. Three
+examples that each inline an A* routine is fine; refactoring them into a
+shared planner that hides the heuristic is not.
+
+## Contributor Checklist
+
+Before opening a PR with a new example:
+
+- [ ] docstring header declares loop, success condition, and each failure
+      kind
+- [ ] `run(seed, render, max_steps)` returns `Trace`
+- [ ] `--no-render` flag exists on the CLI entry point
+- [ ] `env.step(...)` returns `StepResult`
+- [ ] new `Failure.kind`s (if any) follow the snake_case cause-naming rule
+- [ ] new counters end with `_count`
+- [ ] smoke test asserts the concept being taught
+- [ ] category README block uses the fixed headings above
+- [ ] root README and category README link the GIF if one was added
+- [ ] `python scripts/run_all_smoke_tests.py --check-gifs` is green