docs: spec for food resources + scripted memory policies + LLM-spectate fix

docs/superpowers/specs/2026-06-02-food-resources-and-memory-policies-design.md

@@ -0,0 +1,103 @@
+# Food resources, prompt fixes, scripted memory policies, LLM-spectate fix — design
+
+Date: 2026-06-02
+Status: approved (extends 2026-06-02-memory-replay-and-pack-evade-walls)
+
+## Scope (this batch)
+
+A. **Food/resource system** for `pack_evade` — observational only (rendered + named
+   in the prompt; collecting does nothing, survival stays the only scored objective).
+B. **Prompt fixes** — `rules_text`/`memory_brief` no longer say "no walls"; add a
+   food (먹이) description. Keep self (3×3) + caught=eaten. No "bear" framing.
+C. **Memory length** — generation runs 100 turns (was 8).
+D. **Web UI** — hide the memory text block (the replay is enough). The model still
+   receives `render_memory_block` text (an LLM can only read text).
+E. **LLM-spectate bug** — install provider SDKs; return a clear 400 (not a 500) when
+   a provider cannot be built (missing SDK or key).
+F. **Three scripted 100-turn memory policies** — survival-dynamic, survival-refuge,
+   food-rush — selectable as handover memory in the web UI.
+
+## A. Food system
+
+- New palette `FOOD_IDX = 14` (#4FCC30 green); legend `"F"`.
+- `self._food_cells: list[tuple[int,int]]` built in `build_level` (seeded, deterministic):
+  - **mandatory** one near focal spawn (free cell within radius 3–10 of focal center),
+  - **mandatory** one "behind" the predator (beyond predator center along the
+    focal→predator direction, nearest free cell),
+  - plus difficulty-scaled extras (EASY 1 / MED 2 / HARD 3) on random free cells.
+  - free = on-grid, not a wall, not a spawn footprint, not another food cell.
+- Food sprites are 1×1, `BlockingMode.NOT_BLOCKED` (movement/scoring unaffected); added
+  to the Level so they appear in `current_grid()`/live renders. Focal/predator draw on top.
+- `render_frame` prose appends `Food (1x1 edible cells): (x,y); …` (one near you, one
+  behind the predator).
+- `legend()` adds `FOOD_IDX: "F"`.
+- `Scenario.food_cells() -> list[tuple[int,int]]` (base `[]`; pack_evade returns
+  `self._food_cells`). Stored on the checkpoint (`food_cells`) like `wall_rects`.
+- `memory_frames` paints food (under predator/focal, over walls/bg) from
+  `checkpoint.food_cells` for prose scenarios; grid scenarios get food from ASCII
+  inversion (legend has `F`).
+
+## B. Prompt fixes (pack_evade)
+
+`rules_text` / `memory_brief`: replace "open field (no walls)" with a wall-aware
+description ("a field laced with impassable wall blocks; your 3×3 body cannot overlap
+them"), and add the food line ("Food cells (1×1) are scattered — one near you and one
+behind the predator — they are edible context"). Keep "You are A, a 3×3 block" and
+"you are eaten if the predator's block overlaps yours".
+
+## C. Memory length → 100
+
+`memory_turns=100` in: pack_evade `default_memory`, web `_resolve_web_memory` default,
+and the new policy-generation path. (Offline persona/policy generation is fast; the
+episode still stops early on terminal.)
+
+## D. Web UI: drop the memory text block
+
+Hide `#memoryBlock` (`<pre>`) — keep the step-through replay only. `render_memory_block`
+remains in the model's observation pipeline (unchanged); only the human-facing panel
+text is removed.
+
+## E. LLM-spectate fix
+
+- Install the `providers` extra (`uv pip install -e ".[providers]"`): httpx, openai,
+  anthropic, google-genai. (Done in the environment; pyproject already declares them.)
+- Broaden provider-construction error handling: in `_create_spectate` and the
+  generate/latest branch of `_resolve_web_memory`, catch `Exception` (not only
+  `ValueError`) and return a 400 with the message, so a missing SDK/key surfaces as a
+  clear client error instead of a 500.
+
+## F. Scripted memory policies
+
+New module `proteus/runtime/memory_policies.py` — each `policy(scenario, game) -> str`:
+- **`survival_dynamic`**: `scenario.optimal_action(game)` (greedy max-distance from the
+  predator, wall-legal). Keeps moving and evading.
+- **`survival_refuge`**: step (focal-wall-aware BFS) toward the nearest *refuge* cell —
+  a cell where the 3×3 focal fits but the 5×5 predator cannot reach the 1-ring around it
+  — then `stay` once inside. Refuge set is computed once per episode (walls static),
+  cached on the scenario.
+- **`food_rush`**: step (focal BFS, predator ignored) toward the nearest
+  `scenario.food_cells()`; `stay` when no food remains/reachable.
+
+`generate_memory` gains a `policy: Callable | None` path (parallel to agent/persona):
+when set, `action = policy(scenario, game)`, `reasoning=""`, `model_name="policy:<name>"`.
+
+Web `_resolve_web_memory` adds `policy:<name>` mode → `generate_memory(..., policy=...,
+memory_turns=100)`. UI memory dropdown gains `policy:survival_dynamic`,
+`policy:survival_refuge`, `policy:food_rush`.
+
+## Testing
+- Food generation: deterministic per seed; mandatory near-focal + behind-predator cells
+  present, all free; extras count by difficulty; food never on walls/spawns.
+- Food in observation + checkpoint + memory_frames (green index painted at recorded
+  cells for prose; legend `F` round-trips for grid).
+- Prompt: no "no walls"; mentions walls + food; keeps self + eaten.
+- memory length: generated checkpoints have up to 100 turns.
+- Policies: survival_refuge ends in a stay-stable refuge; food_rush reduces distance to
+  nearest food over turns; survival_dynamic increases predator distance vs a passive baseline.
+- Web: `policy:*` modes attach a memory; bad provider → 400 (not 500); `frames` present;
+  served HTML no longer shows the text block but keeps the replay controls.
+- Full suite green; merge to master.
+
+## Out of scope
+- Food scoring/collection, respawning, or win-condition changes (observational only).
+- Predator awareness of food. Bear/persona narrative framing.