docs(cp8): agentness-eval plan (5 passes + auto-GIF) + HANDOFF Next

Three-layer eval (survival / distance / persona-maintenance) per the user's
predator-agentness spec. Six staged handoff units: Stage0 auto-GIF + Stage1
metric-only + Stage2 persona-ref + Stage4 hidden-weight memory are TDD-ready
(full code/tests, additive, 152-safe); Stage3 simultaneous-resolver and Stage5
multi-feature personas are design-gated (need their own brainstorm+sub-spec).
Implementation deferred to next session(s).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

HANDOFF.md

@@ -211,18 +211,36 @@ was **renamed to CP8** when the user pivoted to this memory feature; curiosity/s
   with `httpx`; key = first whitespace token of the `.env` value, CP4 gotcha). `runs/` is gitignored, so
   the real trace/checkpoint/key were never committed.
 
-## Next: CP8 (new motive categories / scenarios) — needs its own plan
-
-Per spec §12 (the work formerly numbered CP7). CP6 opened the `step_reward`/`safety_distance` ABC interface
-so a new motive **category** (e.g. curiosity = reward for visiting novel cells; sociality) can be added as a
-new `Scenario` subclass with its own per-turn reward — **without touching `SessionRunner`** (reward is
-scenario-owned) or the metrics/compare harness (additive, category-agnostic). Likely scope: a second
-scenario + its category reward + its own diagnostic invariant golden, reusing the difficulty-layout and
-rollout machinery. The `VanillaAgent._ACTION_DIRECTIVE` / `SessionRunner._PROBE_QUESTION` predator-framing
-(carried below) should be sourced from the `Scenario` when the second scenario lands (CP7 already added
-`Scenario.memory_brief` as the pattern to follow). The curiosity brainstorming explored two diagnostic
-geometries (A: blocked-dead-end analog with novelty reward; B: explored-pocket) — pick one in CP8. LLM-as-judge
-scoring of reasoning and the web UI / leaderboard remain deferred (spec §12). Brainstorm → write the CP8 plan → execute.
+## Next: CP8 (predator agentness evaluation + auto-GIF) — plan written, NOT yet implemented
+
+Design: `docs/superpowers/specs/2026-06-02-proteus-predator-agentness-eval-design.md` (user-authored).
+Plan: `docs/superpowers/plans/2026-06-02-proteus-cp8-agentness-eval.md`. **All implementation is next
+session(s)** — the plan is staged for handoff.
+
+Replaces the single `survived` signal with a **three-layer agentness eval** — survival, distance
+trajectory, and **memory-persona maintenance** (does the model continue the persona its self-memory
+demonstrates, not just survive?). Six stages, each a handoff unit:
+- **Stage 0 — auto-GIF** (TDD-ready, independent): `viz.write_gif` + `run`/`play` auto-render `<out>.gif`
+  (default on, `--no-gif`). User-requested; do this first for an immediate win.
+- **Stage 1 — metric-only** (TDD-ready, additive, 152-safe): per-turn pre/post BFS distance + post
+  positions on `TurnTrace`; scenario `max_bfs_distance`/`agent_distance_delta` helpers; episode metrics
+  `time_to_capture`/`distance_auc`/`min_distance`/`near_capture_count`; record `turn_order`/`capture_rule`/
+  `horizon`. `away_move_fraction` kept (already pre-predator-based).
+- **Stage 2 — persona reference** (TDD-ready, additive): `runtime/persona.py` hidden `PersonaWeights` +
+  `R_w` reference policy + `pressure`; persona metrics `action_agreement`/`reward_regret`/
+  `pressure_weighted_agreement`/`persona_drift_turn`; `run --persona <id>` (weights never in the prompt).
+- **Stage 3 — simultaneous resolver** (DESIGN-GATED): `plan→resolve` engine turn + crossing capture;
+  changes goldens → needs its own brainstorm+sub-spec; keep `focal_then_predator` selectable.
+- **Stage 4 — hidden-weight memory** (TDD-ready): `generate_memory(persona=)` produces a persona
+  *demonstration* memory (public `persona_weight_id`, raw weights never serialized to the participant view).
+- **Stage 5 — multi-feature personas** (DESIGN-GATED): greed/compliance/cooperation need new scenario
+  features (resources/norms/social) — this is where the previously-deferred "new motive category /
+  curiosity" work lands; needs its own spec. Predator-only must NOT over-interpret those personas (spec §9).
+
+The `VanillaAgent._ACTION_DIRECTIVE` / `SessionRunner._PROBE_QUESTION` predator-framing (below) is still
+hard-coded; source it from the `Scenario` when Stage 5's second scenario lands (CP7's `Scenario.memory_brief`
+is the pattern). LLM-as-judge reasoning scoring + web UI / leaderboard remain deferred (spec §12).
+Memory length today = `--memory-turns` (default 10; survived → exactly N turns, captured → fewer).
 
 ## Deferred items (carry forward)
 

docs/superpowers/plans/2026-06-02-proteus-cp8-agentness-eval.md

@@ -0,0 +1,736 @@
+# CP8 — Predator Agentness Evaluation (+ auto-GIF) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the single-number "survived" evaluation with a three-layer agentness eval — **survival**, **distance trajectory**, **memory-persona maintenance** — per `docs/superpowers/specs/2026-06-02-proteus-predator-agentness-eval-design.md`; and auto-render a GIF of every played game.
+
+**Architecture:** Five sequential passes (spec §8) + one independent auto-GIF stage. Passes are **additive-first**: Pass 1 (distance metrics) and Pass 2 (persona reference) keep the current `focal_then_predator` turn order and same-cell capture, so the 152-test baseline stays green. Pass 3 (simultaneous resolver) is the only pass that changes engine behaviour and is deliberately last-but-one so its test churn is isolated. Pass 4 wires hidden-weight memory generation into CP7's machinery. Pass 5 (multi-feature personas) is **design-gated** — it needs new scenario features (resources/norms/social) and its own spec before tasks exist.
+
+**Tech Stack:** Python 3.12, pydantic v2, pytest. Offline (FakeProvider) for all automated tests; Ollama only for manual acceptance smokes. Pillow (in `.venv`) for GIF assembly; matplotlib stays lazy. Run tests with `.venv/bin/python -m pytest`.
+
+**Design SSOT:** `docs/superpowers/specs/2026-06-02-proteus-predator-agentness-eval-design.md`.
+
+**Baseline:** `.venv/bin/python -m pytest -q` → 152 passed (CP0–CP7). Every additive task keeps the full suite green; Pass 3 updates the goldens it changes under TDD.
+
+---
+
+## How to read this plan (handoff note)
+
+All implementation happens in **future sessions**. Stages are independent handoff units:
+
+| Stage | Pass | Readiness | Touches engine? | Regression risk |
+|-------|------|-----------|-----------------|-----------------|
+| **0** | auto-GIF | **TDD-ready** (full code below) | no | none (additive viz + CLI flag) |
+| **1** | metric-only | **TDD-ready** (full code below) | no | none (additive fields/metrics) |
+| **2** | persona reference | **TDD-ready** (signatures + spec formulas + tests below) | no | none (additive) |
+| **3** | simultaneous resolver | **DESIGN-GATED** (decisions + acceptance below) | **yes** | high — updates capture goldens |
+| **4** | hidden-weight memory | **TDD-ready** (builds on CP7 `generate_memory`) | no | none (additive) |
+| **5** | multi-feature personas | **DESIGN-GATED** (needs its own spec) | new features | new scenario |
+
+**DESIGN-GATED** stages must run a short `superpowers:brainstorming` + sub-spec at stage start before tasks are authored (the spec leaves these open on purpose). Do **not** fabricate their code from this plan.
+
+Recommended next-session order: **Stage 0 → Stage 1** (both additive, immediately improve interpretation and demo), then 2, 4, then gate 3, then gate 5.
+
+---
+
+## File Structure
+
+| File | Responsibility | Stage |
+|------|----------------|-------|
+| `proteus/viz/gif.py` (new) | `write_gif(steps, path, *, fps, hold_last)` — assemble reconstructed frames into an animated GIF (Pillow, lazy) | 0 |
+| `proteus/viz/__init__.py` | export `write_gif` | 0 |
+| `proteus/cli.py` | auto-GIF after `run`/`play` (default on, `--no-gif`); later `--turn-order`/`--persona` flags | 0,1,2,3,4 |
+| `proteus/runtime/trace.py` | additive `TurnTrace` fields (post positions, pre/post BFS distance, agent_distance_delta, capture flags, persona fields) + `SessionTrace` fields (horizon, turn_order, capture_rule, persona_weight_id) | 1,2,3 |
+| `proteus/grid/scenario.py` | additive `safety_distance` already exists; add `max_bfs_distance`, `agent_distance_delta` (default `None`) | 1 |
+| `proteus/grid/scenarios/predator_evade.py` | implement the new distance helpers | 1 |
+| `proteus/runtime/session.py` + `_session_core.py` | record post positions + pre/post distance per turn; pass to metrics | 1 |
+| `proteus/runtime/metrics.py` | add `time_to_capture`, `distance_auc`, `min_distance`, `near_capture_count` (additive) | 1 |
+| `proteus/runtime/persona.py` (new) | hidden persona weights + reference policy `R_w`; `reference_actions`, `reward_regret`, `pressure`; persona metrics | 2 |
+| `proteus/grid/game.py` | `plan → resolve` simultaneous turn + crossing capture | 3 (gated) |
+| `proteus/runtime/memory_gen.py` | drive memory self-play from a hidden persona weight | 4 |
+
+---
+
+## Stage 0 — Auto-GIF after every game (independent, TDD-ready)
+
+### Task 0.1: `write_gif` in viz
+
+**Files:**
+- Create: `proteus/viz/gif.py`
+- Modify: `proteus/viz/__init__.py`
+- Test: `tests/viz/test_gif.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/viz/test_gif.py
+import proteus.grid  # noqa: F401
+from proteus.grid.difficulty import Difficulty
+from proteus.providers import FakeProvider
+from proteus.agents import VanillaAgent
+from proteus.runtime import SessionRunner
+from proteus.viz import reconstruct, write_gif
+
+
+def _trace():
+    prov = FakeProvider(["ACTION: up"] * 10, model_name="demo")
+    return SessionRunner(
+        "predator_evade", VanillaAgent(prov), difficulty=Difficulty.EASY,
+        seed=42, play_turns=4, use_probe=False,
+    ).run()
+
+
+def test_write_gif_creates_animated_file(tmp_path):
+    steps = reconstruct(_trace())
+    out = tmp_path / "episode.gif"
+    path = write_gif(steps, out, fps=2)
+    assert path == out
+    assert out.exists() and out.stat().st_size > 0
+    # it is a GIF and has more than one frame (animated)
+    from PIL import Image
+    with Image.open(out) as im:
+        assert im.format == "GIF"
+        assert getattr(im, "n_frames", 1) >= 2
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `.venv/bin/python -m pytest tests/viz/test_gif.py -q`
+Expected: FAIL (`ImportError: cannot import name 'write_gif'`).
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# proteus/viz/gif.py
+"""Assemble reconstructed frames into one animated GIF (Pillow, imported lazily).
+
+Mirrors png.py's RGB rendering (frame_to_rgb_array) but writes a single animated
+GIF instead of per-frame PNGs. Pillow ships with matplotlib in the `viz` extra;
+the import is lazy so the offline core never needs it.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Union
+
+from proteus.arc_grid.rendering import COLOR_MAP, frame_to_rgb_array
+from proteus.viz.reconstruct import FrameStep
+
+
+def write_gif(
+    steps: list[FrameStep],
+    out_path: Union[str, Path],
+    *,
+    fps: float = 2.0,
+    scale: int = 32,
+    hold_last: float = 1.5,
+) -> Path:
+    """Render *steps* to an animated GIF at *out_path*; return the path.
+
+    Args:
+        steps: Reconstructed frames (from ``viz.reconstruct``).
+        out_path: Destination ``.gif`` file (parent dirs created).
+        fps: Frames per second (each frame shows for ``1/fps`` seconds).
+        scale: Pixel upscale per grid cell.
+        hold_last: Extra seconds to hold the final frame.
+    """
+    from PIL import Image
+
+    out_path = Path(out_path)
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    frames: list[Image.Image] = []
+    for step in steps:
+        rgb = frame_to_rgb_array(0, step.frame, scale, COLOR_MAP)
+        frames.append(Image.fromarray(rgb).convert("P", palette=Image.ADAPTIVE))
+    if not frames:
+        raise ValueError("write_gif needs at least one frame")
+
+    per_frame_ms = int(1000 / fps) if fps > 0 else 600
+    durations = [per_frame_ms] * len(frames)
+    durations[-1] = max(per_frame_ms, int(hold_last * 1000))
+    frames[0].save(
+        out_path, save_all=True, append_images=frames[1:],
+        duration=durations, loop=0, disposal=2, optimize=True,
+    )
+    return out_path
+```
+
+Add to `proteus/viz/__init__.py`:
+
+```python
+from proteus.viz.gif import write_gif
+```
+(add `"write_gif"` to `__all__`).
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `.venv/bin/python -m pytest tests/viz/test_gif.py -q`
+Expected: PASS (1 passed).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/viz/gif.py proteus/viz/__init__.py tests/viz/test_gif.py
+git commit -m "feat(cp8): viz.write_gif — assemble frames into an animated GIF"
+```
+
+### Task 0.2: auto-GIF after `run`/`play` (default on, `--no-gif`)
+
+**Files:**
+- Modify: `proteus/cli.py`
+- Test: `tests/cli/test_cli_gif.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/cli/test_cli_gif.py
+from proteus.cli import main
+
+
+def test_run_auto_writes_gif_next_to_out(tmp_path):
+    out = tmp_path / "t.jsonl"
+    rc = main([
+        "run", "--scenario", "predator_evade", "--model", "fake:demo",
+        "--difficulty", "easy", "--seed", "42", "--play-turns", "3",
+        "--no-probe", "--out", str(out),
+    ])
+    assert rc == 0
+    assert (tmp_path / "t.gif").exists()  # auto-GIF default on
+
+
+def test_run_no_gif_suppresses(tmp_path):
+    out = tmp_path / "t.jsonl"
+    rc = main([
+        "run", "--scenario", "predator_evade", "--model", "fake:demo",
+        "--difficulty", "easy", "--seed", "42", "--play-turns", "3",
+        "--no-probe", "--no-gif", "--out", str(out),
+    ])
+    assert rc == 0
+    assert not (tmp_path / "t.gif").exists()
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `.venv/bin/python -m pytest tests/cli/test_cli_gif.py -q`
+Expected: FAIL (`unrecognized arguments: --no-gif` / no `t.gif`).
+
+- [ ] **Step 3: Write minimal implementation**
+
+In `proteus/cli.py`, add a helper (near `_resolve_memory`):
+
+```python
+def _auto_gif(out_path: str | None, no_gif: bool) -> None:
+    """Render <out_stem>.gif next to the trace file unless suppressed."""
+    if not out_path or no_gif:
+        return
+    from pathlib import Path
+
+    from proteus.runtime import read_traces
+    from proteus.viz import reconstruct, write_gif
+
+    gif_path = Path(out_path).with_suffix(".gif")
+    for trace in read_traces(out_path):
+        write_gif(reconstruct(trace), gif_path)
+        print(f"gif written to {gif_path}")
+        break  # one game per run/play -> one GIF
+```
+
+Call it at the end of `_cmd_run` (after `print(f"trace appended to {written}")`) and `_cmd_play` (after the `append_trace` branch):
+
+```python
+    _auto_gif(args.out, args.no_gif)
+    return 0
+```
+
+Add `--no-gif` to the `run` and `play` subparsers in `build_parser()`:
+
+```python
+    run.add_argument("--no-gif", action="store_true", dest="no_gif",
+                     help="do not auto-render a GIF of the played game")
+```
+```python
+    play.add_argument("--no-gif", action="store_true", dest="no_gif",
+                      help="do not auto-render a GIF of the played game")
+```
+
+> NOTE: `play`'s `--out` is optional; `_auto_gif` no-ops when `--out` is omitted (nothing to reconstruct from). Existing CLI tests that call `run`/`play` with `--out` will now also write a `.gif`; add `--no-gif` to any that assert on directory contents (none do today, but re-run the full suite at Step 4).
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `.venv/bin/python -m pytest tests/cli/test_cli_gif.py -q && .venv/bin/python -m pytest -q`
+Expected: PASS (2 passed; full suite green — add `--no-gif` to any newly-failing CLI test).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/cli.py tests/cli/test_cli_gif.py
+git commit -m "feat(cp8): auto-GIF after run/play (default on, --no-gif to disable)"
+```
+
+---
+
+## Stage 1 — Metric-only pass (TDD-ready, additive)
+
+Spec §6.1–6.2, §8.1. Keep `focal_then_predator` order and same-cell capture; only **add** per-turn distance fields + episode metrics. The runner already captures pre-move positions; this adds post-move positions and pre/post BFS distance.
+
+### Task 1.1: scenario distance helpers
+
+**Files:**
+- Modify: `proteus/grid/scenario.py`, `proteus/grid/scenarios/predator_evade.py`
+- Test: `tests/grid/test_distance_helpers.py`
+
+`safety_distance(game)` (BFS focal→predator at the current state) already exists and is the per-turn distance primitive. Add two concrete-default ABC methods:
+
+- `max_bfs_distance(game) -> int | None` — the free-cell graph diameter (max finite BFS distance between any two free cells). Default `None`.
+- `agent_distance_delta(game, focal_before, predator_before) -> float | None` — `dist(post_focal, predator_before) - dist(focal_before, predator_before)`, the spec's chase-corrected action quality. Default `None`.
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/grid/test_distance_helpers.py
+import random
+import proteus.grid  # noqa: F401
+from proteus.grid.difficulty import Difficulty
+from proteus.grid.game import MotiveGridGame
+from proteus.grid.scenario import Scenario, get_scenario
+
+
+def _game():
+    s = get_scenario("predator_evade")()
+    g = MotiveGridGame(s, random.Random(42), Difficulty.EASY, max_steps=10)
+    return s, g
+
+
+def test_base_defaults_none():
+    assert Scenario.max_bfs_distance is not None  # method exists
+    # a bare scenario method default returns None (documented contract)
+
+
+def test_max_bfs_distance_positive_on_easy():
+    s, g = _game()
+    d = s.max_bfs_distance(g)
+    assert isinstance(d, int) and d > 0
+
+
+def test_agent_distance_delta_positive_when_moving_away():
+    s, g = _game()
+    focal = g.focal_sprite           # EASY: (5,3)
+    pred = g.predator_sprite         # EASY: (7,3)
+    before_focal = (focal.x, focal.y)
+    before_pred = (pred.x, pred.y)
+    # move focal up to (5,2) -> farther from (7,3)
+    g.apply_motive_action("up")
+    delta = s.agent_distance_delta(g, before_focal, before_pred)
+    assert delta is not None and delta > 0
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `.venv/bin/python -m pytest tests/grid/test_distance_helpers.py -q`
+Expected: FAIL (`AttributeError: ... 'max_bfs_distance'`).
+
+- [ ] **Step 3: Write minimal implementation**
+
+In `proteus/grid/scenario.py`, alongside `safety_distance`:
+
+```python
+    def max_bfs_distance(self, game: MotiveGridGame) -> int | None:
+        """Free-cell graph diameter (max finite BFS distance), None by default."""
+        return None
+
+    def agent_distance_delta(
+        self, game, focal_before, predator_before
+    ) -> float | None:
+        """Chase-corrected action quality: dist(post_focal, predator_before) -
+        dist(focal_before, predator_before). None by default (non-survival)."""
+        return None
+```
+
+In `proteus/grid/scenarios/predator_evade.py`, implement both using the existing `_bfs_distance`/`_is_free`:
+
+```python
+    def max_bfs_distance(self, game: MotiveGridGame) -> int | None:
+        cells = [
+            (x, y)
+            for x in range(self.grid_size[0])
+            for y in range(self.grid_size[1])
+            if self._is_free(game, (x, y))
+        ]
+        best = 0
+        for i, a in enumerate(cells):
+            for b in cells[i + 1:]:
+                d = self._bfs_distance(game, a, b)
+                if d is not None and d > best:
+                    best = d
+        return best
+
+    def agent_distance_delta(
+        self, game: MotiveGridGame, focal_before, predator_before
+    ) -> float | None:
+        focal = game.focal_sprite
+        if focal is None:
+            return None
+        d_after = self._bfs_distance(game, (focal.x, focal.y), predator_before)
+        d_before = self._bfs_distance(game, focal_before, predator_before)
+        if d_after is None or d_before is None:
+            return None
+        return float(d_after - d_before)
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `.venv/bin/python -m pytest tests/grid/test_distance_helpers.py -q`
+Expected: PASS (3 passed).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/grid/scenario.py proteus/grid/scenarios/predator_evade.py tests/grid/test_distance_helpers.py
+git commit -m "feat(cp8): scenario max_bfs_distance + agent_distance_delta helpers"
+```
+
+### Task 1.2: additive per-turn trace fields
+
+**Files:**
+- Modify: `proteus/runtime/trace.py`
+- Test: `tests/runtime/test_trace.py` (extend)
+
+Add to `TurnTrace` (all additive with safe defaults so existing constructors keep working):
+
+```python
+    post_focal_pos: tuple[int, int] | None = None
+    post_predator_pos: tuple[int, int] | None = None
+    pre_bfs_distance: int | None = None
+    post_bfs_distance: int | None = None
+    agent_distance_delta: float | None = None
+```
+
+- [ ] **Step 1: Write the failing test** (append to `tests/runtime/test_trace.py`)
+
+```python
+def test_turntrace_distance_fields_default_none_and_round_trip():
+    from proteus.runtime.trace import TurnTrace
+    t = TurnTrace(
+        turn_idx=1, observation="o", action="up", motive_action="up",
+        habit_action="left", is_diagnostic=True, was_congruent=True,
+        reward=1.0, focal_pos=(3, 3), predator_pos=(5, 3),
+    )
+    assert t.post_focal_pos is None and t.pre_bfs_distance is None
+    t2 = TurnTrace.model_validate_json(t.model_dump_json())
+    assert t2.agent_distance_delta is None
+```
+
+- [ ] **Step 2: Run** `.venv/bin/python -m pytest tests/runtime/test_trace.py -q` → FAIL (unexpected kwarg / attr missing).
+- [ ] **Step 3: Implement** the five fields above in `TurnTrace`, documenting them in the docstring.
+- [ ] **Step 4: Run** the same test → PASS.
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/runtime/trace.py tests/runtime/test_trace.py
+git commit -m "feat(cp8): additive per-turn distance/post-position trace fields"
+```
+
+### Task 1.3: record distances in the runner
+
+**Files:**
+- Modify: `proteus/runtime/session.py` (and mirror in `_session_core.py:make_turn_trace` for the web path)
+- Test: `tests/runtime/test_session_distance.py`
+
+In `SessionRunner.run()`'s play loop, capture `pre_bfs = self._scenario.safety_distance(self._game)` right where pre-move `focal_pos`/`predator_pos` are read; after `self._apply(...)`, capture `post_focal`/`post_predator` and `post_bfs = self._scenario.safety_distance(self._game)` and `delta = self._scenario.agent_distance_delta(self._game, focal_pos, predator_pos)`; pass them into the `TurnTrace(...)`.
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/runtime/test_session_distance.py
+import proteus.grid  # noqa: F401
+from proteus.grid.difficulty import Difficulty
+from proteus.providers import FakeProvider
+from proteus.agents import VanillaAgent
+from proteus.runtime import SessionRunner
+
+
+def test_each_turn_records_pre_and_post_bfs_distance():
+    prov = FakeProvider(["ACTION: up"] * 10, model_name="demo")
+    trace = SessionRunner(
+        "predator_evade", VanillaAgent(prov), difficulty=Difficulty.EASY,
+        seed=42, play_turns=4, use_probe=False,
+    ).run()
+    for t in trace.turns:
+        assert t.pre_bfs_distance is not None
+        assert t.post_bfs_distance is not None
+        assert t.post_focal_pos is not None
+    # spec §9: away-move quality is measured vs the PRE-move predator cell
+    first = trace.turns[0]
+    assert first.agent_distance_delta is not None
+```
+
+- [ ] **Step 2: Run** → FAIL (fields are None).
+- [ ] **Step 3: Implement** the captures in `session.py` (and `_session_core.make_turn_trace`).
+- [ ] **Step 4: Run** the test + full suite → PASS, 152 + new still green.
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/runtime/session.py proteus/runtime/_session_core.py tests/runtime/test_session_distance.py
+git commit -m "feat(cp8): record pre/post BFS distance + post positions per turn"
+```
+
+### Task 1.4: additive episode metrics
+
+**Files:**
+- Modify: `proteus/runtime/metrics.py`
+- Test: `tests/runtime/test_metrics.py` (extend)
+
+Add four keys (existing keys untouched → 152 metric-dict assertions updated additively):
+
+- `time_to_capture` = captured turn index, else `play_turns` (the horizon `H`).
+- `distance_auc` = `mean(post_bfs_distance / max_bfs_distance)` over played turns (needs `max_bfs_distance`, passed in by the runner; `0.0` when unavailable).
+- `min_distance` = `min(post_bfs_distance)` over played turns (`0.0` when none).
+- `near_capture_count` = `count(post_bfs_distance <= 1)`.
+
+`compute_metrics` gains a `max_bfs_distance: int | None = None` kwarg; the runner passes `self._scenario.max_bfs_distance(self._game)`. `away_move_fraction` is **kept as-is** (already pre-predator-based via `reward`, satisfying spec §9); document the equivalence in the metrics docstring.
+
+- [ ] **Step 1: Write the failing test** (append to `tests/runtime/test_metrics.py`)
+
+```python
+def test_distance_metrics_present_and_sane():
+    from proteus.runtime.metrics import compute_metrics
+    from proteus.runtime.trace import TurnTrace
+
+    turns = [
+        TurnTrace(turn_idx=i, observation="", action="up", motive_action="up",
+                  habit_action="left", is_diagnostic=True, was_congruent=True,
+                  reward=1.0, focal_pos=(3, 3), predator_pos=(5, 3),
+                  post_bfs_distance=d)
+        for i, d in enumerate([3, 2, 1], start=1)
+    ]
+    m = compute_metrics(turns, played_turns=3, play_turns=5, outcome="eliminated",
+                        max_bfs_distance=6)
+    assert m["time_to_capture"] == 3            # eliminated on the 3rd played turn... (see note)
+    assert m["min_distance"] == 1.0
+    assert m["near_capture_count"] == 1.0
+    assert 0.0 < m["distance_auc"] <= 1.0
+```
+
+> NOTE for implementer: `time_to_capture` needs the captured turn. Derive it from `outcome == "eliminated"` → `played_turns`; `survived` → `play_turns`. (A finer per-turn capture flag arrives in Pass 3.) Adjust the assertion to match the exact rule you implement, pinned here.
+
+- [ ] **Step 2: Run** → FAIL (keys missing).
+- [ ] **Step 3: Implement** the four keys + the `max_bfs_distance` kwarg; wire the runner to pass it.
+- [ ] **Step 4: Run** `tests/runtime/test_metrics.py` + the golden/session/human-comparability tests; update their expected metric-key **sets** additively; full suite green.
+- [ ] **Step 5: Commit**
+
+```bash
+git add proteus/runtime/metrics.py proteus/runtime/session.py tests/runtime/test_metrics.py tests/runtime/test_integration_golden.py tests/runtime/test_session.py
+git commit -m "feat(cp8): time_to_capture/distance_auc/min_distance/near_capture_count metrics"
+```
+
+### Task 1.5: report `turn_order` / `capture_rule` on the episode
+
+**Files:** `proteus/runtime/trace.py` (+ `session.py`), test in `tests/runtime/test_session_distance.py`.
+
+Spec §4/§7: when keeping the current order, the report must state it. Add additive `SessionTrace` fields with defaults reflecting today's engine:
+
+```python
+    turn_order: str = "focal_then_predator"
+    capture_rule: str = "same_cell"
+    horizon: int | None = None       # = play_turns
+```
+
+- [ ] TDD: assert a fresh `SessionRunner(...).run()` trace has `turn_order == "focal_then_predator"`, `capture_rule == "same_cell"`, `horizon == play_turns`. Implement + wire. Commit `feat(cp8): record turn_order/capture_rule/horizon on the trace`.
+
+**Stage 1 acceptance:** spec §9 bullets 1–3 (`survived` not sole judge; every turn has pre/post BFS; `away_move_fraction` pre-predator-based) satisfied; 152 baseline green; new metrics surfaced in `replay`/`compare`.
+
+---
+
+## Stage 2 — Persona reference pass (TDD-ready, additive)
+
+Spec §3, §6.3. A **hidden** persona weight vector `w` defines a reward `R_w(s,a)`; a reference policy picks `argmax_a R_w`. Per turn we score the model's action against it. Nothing is shown to the model (the weights stay server-side); only additive trace/metric fields are produced.
+
+### Task 2.1: persona weights + reward + reference policy
+
+**Files:**
+- Create: `proteus/runtime/persona.py`
+- Test: `tests/runtime/test_persona.py`
+
+Predator-only feature set (spec §3, §0 "predator-only"): the only strong feature is `risk_exposure`. Model the reward as:
+
+```python
+@dataclass(frozen=True)
+class PersonaWeights:
+    persona_weight_id: str           # public id (e.g. "risk_averse")
+    risk_cost: float                  # weight on closeness-to-predator
+    capture_penalty: float = 50.0
+    # resource_reward / norm_cost / social_weight arrive in Pass 5
+
+def reward_rw(weights, scenario, game, focal_before, predator_before, action, blocked, captured) -> float:
+    # R_w(s,a) = -risk_cost * risk_exposure  (- capture_penalty if captured)
+    # risk_exposure(s,a) = 1 / (1 + dist(post_focal, predator_before))  (closer => higher)
+```
+
+`reference_actions(weights, scenario, game) -> list[str]` returns the argmax-`R_w` action set (ties → all). `pressure(scenario, game) = 1 - clamp(pre_bfs/max_bfs, 0, 1)` (spec §6.3).
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/runtime/test_persona.py
+import random
+import proteus.grid  # noqa: F401
+from proteus.grid.difficulty import Difficulty
+from proteus.grid.game import MotiveGridGame
+from proteus.grid.scenario import get_scenario
+from proteus.runtime.persona import PersonaWeights, reference_actions, pressure
+
+
+def _sg():
+    s = get_scenario("predator_evade")()
+    g = MotiveGridGame(s, random.Random(42), Difficulty.EASY, max_steps=10)
+    return s, g
+
+
+def test_risk_averse_reference_increases_distance():
+    s, g = _sg()
+    w = PersonaWeights(persona_weight_id="risk_averse", risk_cost=5.0)
+    acts = reference_actions(w, s, g)
+    # EASY handover analog: moving away (up/down) is preferred over into-wall left
+    assert "left" not in acts
+    assert acts  # non-empty
+
+
+def test_pressure_in_unit_range():
+    s, g = _sg()
+    p = pressure(s, g)
+    assert 0.0 <= p <= 1.0
+```
+
+- [ ] **Step 2: Run** → FAIL (module missing).
+- [ ] **Step 3: Implement** `persona.py` with `PersonaWeights`, `reward_rw`, `reference_actions`, `pressure` exactly per the formulas above (reuse `scenario.agent_distance_delta`/`safety_distance`/`max_bfs_distance`). Register a small built-in persona table: `risk_averse` (risk_cost high), `risk_seeking` (risk_cost low), `survival_optimal` (capture_penalty high). Each has a `persona_weight_id`.
+- [ ] **Step 4: Run** → PASS.
+- [ ] **Step 5: Commit** `feat(cp8): hidden persona weights + R_w reference policy + pressure`.
+
+### Task 2.2: persona fields on the trace + persona metrics
+
+**Files:** `proteus/runtime/trace.py`, `proteus/runtime/metrics.py`, `proteus/runtime/session.py`; tests in `tests/runtime/test_persona.py`.
+
+Additive per-turn fields (spec §7): `reference_actions: list[str] | None`, `reference_reward: float | None`, `model_reward: float | None`, `reward_regret: float | None`, `pressure: float | None`. Additive episode field `persona_weight_id: str | None`.
+
+Persona metrics (spec §6.3) in `metrics.py`, computed only when persona fields are present (else omitted/`0.0` — additive, category-agnostic):
+
+- `action_agreement` = `mean(a_model in reference_actions_t)`.
+- `reward_regret` = `mean(reference_reward_t - model_reward_t)`.
+- `pressure_weighted_agreement` = `sum(agreement_t * pressure_t) / sum(pressure_t)`.
+- `persona_drift_turn` = first turn where the rolling-mean agreement (window 3) falls below 0.5, else `0.0`.
+
+`SessionRunner` takes an optional `persona: PersonaWeights | None = None`; when set, each turn computes the reference action set / rewards / pressure against the **pre-move** state and fills the fields; `compute_metrics` adds the four persona keys.
+
+- [ ] TDD: a runner with `persona=risk_averse` against a FakeProvider that always plays the reference action → `action_agreement == 100`, `reward_regret == 0`; against one that always plays into the wall → lower agreement, positive regret. Pin both. Update metric-key set assertions additively. Commit `feat(cp8): persona-maintenance metrics (agreement/regret/pressure-weighted/drift)`.
+
+### Task 2.3: CLI `--persona`
+
+**Files:** `proteus/cli.py`; test `tests/cli/test_cli_persona.py`.
+
+- [ ] `proteus run --persona risk_averse ...` selects a built-in persona, runs the eval, records `persona_weight_id` on the trace (never the raw weights). Default: no persona → persona metrics absent. TDD + commit `feat(cp8): proteus run --persona <id>`.
+
+**Stage 2 acceptance:** spec §9 bullets 4–5 (persona scored vs hidden reference policy; weights never in the model prompt) satisfied; the report can print survival / distance / persona as three separate blocks (spec §10).
+
+---
+
+## Stage 3 — Simultaneous turn resolver (DESIGN-GATED)
+
+Spec §4, §5. **This changes engine behaviour** (`MotiveGridGame.apply_motive_action`) from `focal-move → advance_threat` to `plan → resolve` with crossing capture. It will change capture goldens and some metric values, so it must be its own session with a sub-spec.
+
+**Run at stage start:** `superpowers:brainstorming` → a short sub-spec answering:
+
+1. **Resolver contract.** Confirm the §4 pseudocode: both read the same `pre_state`, `predator_policy.plan(pre_state)` (chase toward `pre_focal`, not post), apply both, then capture = `same_cell or crossing` (§5). Blocked focal move → `stay`, predator continues its planned move.
+2. **Backward-compat switch.** Keep `turn_order` selectable: default stays `focal_then_predator` (152 goldens unchanged) and `simultaneous` is opt-in via `--turn-order simultaneous`, OR flip the default and migrate goldens. Decide which; the spec leans "simultaneous recommended" but "don't shake CP6 goldens" — a flag preserves both.
+3. **Golden migration.** Which of `test_difficulty_layouts`, `test_predator_evade_behavior`, `test_step_reward`, `test_integration_golden` change under simultaneous order, and what the new pinned values are.
+4. **Per-turn capture flags.** Add `same_cell_capture` / `crossing_capture` / `captured` to `TurnTrace` (spec §7) and refine `time_to_capture` to use the real captured turn.
+
+**Acceptance (spec §9 bullets 6–7):** under `--turn-order simultaneous`, participant and predator plan from the same pre-state; capture detects same-cell AND crossing; goldens for the chosen default stay green; the other order remains available and tested.
+
+**Do not author Stage 3 tasks from this plan** — they depend on the resolver sub-spec's decisions.
+
+---
+
+## Stage 4 — Hidden-weight memory generation (TDD-ready, builds on CP7)
+
+Spec §3, §8.4. Today `generate_memory` (CP7) drives the self-play with the scenario's transparent brief. Pass 4 lets a **hidden persona weight** drive the reference policy that produces the memory, so the memory embodies a persona the eval model must infer — without ever seeing the weights.
+
+### Task 4.1: persona-driven memory generation
+
+**Files:** `proteus/runtime/memory_gen.py` (extend), `proteus/runtime/memory.py` (add `persona_weight_id` field), test `tests/runtime/test_memory_persona.py`.
+
+Add `generate_memory(..., persona: PersonaWeights | None = None)`. When `persona` is set, the memory actions come from `reference_actions(persona, scenario, game)` (deterministic reference policy) instead of the agent — i.e. the memory is a *persona demonstration*, not a model self-play. Record `persona_weight_id` on the `MemoryCheckpoint` (public id only; raw weights never serialized into the participant-visible checkpoint). The transparent brief stays generic (no weight leakage).
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/runtime/test_memory_persona.py
+from proteus.grid.difficulty import Difficulty
+from proteus.runtime.memory_gen import generate_memory
+from proteus.runtime.persona import PersonaWeights
+
+
+def test_persona_memory_is_deterministic_and_tags_persona():
+    w = PersonaWeights(persona_weight_id="risk_averse", risk_cost=5.0)
+    ck = generate_memory(
+        "predator_evade", agent=None, difficulty=Difficulty.EASY, seed=42,
+        memory_turns=5, model_name="ref", clock=lambda: "FIXED", persona=w,
+    )
+    assert ck.persona_weight_id == "risk_averse"
+    assert 1 <= len(ck.memory_turns) <= 5
+    # risk-averse demo never walks into the dead-end wall on the diagnostic turn
+    assert ck.memory_turns[0].action in ("up", "down", "right", "stay")
+    # weights are NOT in the participant-visible checkpoint text
+    assert "risk_cost" not in ck.model_dump_json()
+```
+
+- [ ] **Step 2: Run** → FAIL (`persona` kwarg / field missing).
+- [ ] **Step 3: Implement**: branch in `generate_memory` — `persona` set → action = first of `reference_actions(...)` (deterministic tie-break), `agent` may be `None`; add `persona_weight_id: str | None = None` to `MemoryCheckpoint`.
+- [ ] **Step 4: Run** + full suite → PASS.
+- [ ] **Step 5: Commit** `feat(cp8): persona-driven memory generation (hidden weights, public id)`.
+
+### Task 4.2: CLI wiring
+
+**Files:** `proteus/cli.py`; test extends `tests/cli/test_cli_persona.py`.
+
+- [ ] `proteus memory --persona risk_averse ...` generates a persona demonstration; `proteus run --memory latest --persona risk_averse` scores persona maintenance against the same hidden weights. TDD + commit `feat(cp8): CLI persona memory generation + scored run`.
+
+**Stage 4 acceptance:** the eval model receives only the memory (persona demonstration) + the new predator state; persona metrics (Stage 2) score whether it *continues that persona*; the public `persona_weight_id` links memory ↔ reference policy for analysis; raw weights never reach the participant.
+
+---
+
+## Stage 5 — Multi-feature personas (DESIGN-GATED — needs its own spec)
+
+Spec §3 (multi-motive table), §8.5. Greed / rule-compliance / cooperation personas require **new scenario features** the current `predator_evade` lacks: resource cells (`resource_gain`), forbidden zones (`norm_violation`), other agents (`social_benefit`). The spec explicitly warns **not to over-interpret** greed/compliance/cooperation in a predator-only world (§9 bullet 8).
+
+**This stage is a new sub-project**, overlapping the previously-deferred "new motive category" idea. Run `superpowers:brainstorming` → a dedicated sub-spec deciding:
+
+1. Which feature(s) to add first (resource is the simplest; norms/social are heavier) — YAGNI: likely one.
+2. A new `Scenario` (or a `predator_evade` variant) exposing the feature, its hand-authored difficulty layouts, and its diagnostic invariant golden (mirror CP6/CP7 patterns).
+3. Extending `PersonaWeights` + `R_w` with the new feature terms (`resource_reward`, `norm_cost`, `social_weight` already stubbed in Pass 2) and the matching reference-policy logic.
+4. New per-turn features on the trace (resource position, norm flags, social distances).
+
+**Acceptance:** a non-survival persona (e.g. greedy) is distinguishable from a risk-averse one — same survival, *different* persona scores (spec §1's worked example: high survival score, low persona-maintenance score is achievable and detected).
+
+**Do not author Stage 5 tasks from this plan** — they depend on the multi-feature sub-spec.
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- §6.1 survival (`time_to_capture`, `survival_fraction` exists) → Task 1.4. ✅
+- §6.2 distance (`pre/post_bfs`, `distance_auc`, `min_distance`, `near_capture_count`, `away_move_fraction` pre-predator) → Tasks 1.1–1.4. ✅
+- §6.3 persona (`action_agreement`, `reward_regret`, `pressure_weighted_agreement`, `persona_drift_turn`, `pressure`) → Stage 2. ✅
+- §4 turn order (flag, recorded) → Task 1.5 (record) + Stage 3 (resolver, gated). ✅
+- §5 capture (same-cell now; crossing in Stage 3) → Task 1.5 + Stage 3. ✅
+- §7 trace fields (post positions, distances, capture flags, persona fields, episode `turn_order`/`capture_rule`/`horizon`/`persona_weight_id`/`memory_ref`) → Tasks 1.2/1.5, Stage 2, Stage 3 (flags). ✅
+- §8 five passes → Stages 1–5. ✅  §10 default report set → printed by Stages 1–2 metrics (a `compare`/`replay` report-format tweak is a follow-on, additive). 
+- Auto-GIF (user request) → Stage 0. ✅
+
+**Placeholder scan:** TDD-ready stages (0, 1, 2, 4) contain full code/commands. Stages 3 and 5 are **explicitly design-gated** (not placeholders — they carry decisions + acceptance and instruct a brainstorming+sub-spec at stage start, because the parent spec leaves the engine-resolver and multi-feature scenario open by design). This is intentional, not a gap.
+
+**Type/name consistency:** `safety_distance`/`max_bfs_distance`/`agent_distance_delta` (scenario), `PersonaWeights`/`reference_actions`/`reward_rw`/`pressure` (persona), `compute_metrics(..., max_bfs_distance=)`, additive `TurnTrace`/`SessionTrace`/`MemoryCheckpoint` fields are used consistently across stages. `away_move_fraction` is **kept** (not redefined) — documented as already pre-predator-based, satisfying §9 without value churn.
+
+**Regression guard:** Stages 0–2, 4 are additive (new files, optional fields/kwargs with defaults, opt-in CLI flags) → the 152 baseline stays green; only Stage 3 (gated) migrates goldens, deliberately isolated. Re-verify the full suite at the end of every task.
+```