[ryangswe]

This closes Week 1. It runs eb_jepa's Two Rooms example and drafts the planning protocol that latent-plan will build on, checked against that model. The protocol is experimental: it has been checked against one model, and its interface stays provisional until a second model's adapter reproduces that model's native rollouts.

What changes

• A draft planning protocol in src/jepa_scope/planning/. A world model implements encode, a one-step stateless predict and energy over a fixed-shape planning state (state_shape). rollout keeps a trajectory, and plan_cost scores one with a "sum" or "last" objective, keeping only the current state. cem.py is a reference Cross-Entropy Method planner that mirrors eb_jepa's CEMPlanner; it validates its settings and inputs and fails loudly on NaN or infinite costs. The package depends only on torch.
• An adapter for eb_jepa's Two Rooms model (eb_jepa_two_rooms.py). eb_jepa is imported only when an adapter is built, and it is never a dependency. Weights load with weights_only=True and strict key matching.
• The spec, docs/planning-protocol.md, for people writing adapters for their own models. It covers the interface, the rules every adapter follows, what an action must document, what the reference planner supports, the Two Rooms adapter, the results with where each number came from and how to reproduce it, what is not yet checked, and the open points (including how V-JEPA 2-AC would fit).
• Tests. tests/test_planning_protocol.py (35 tests, in CI) covers the protocol and planner on a point-mass model and on a model whose state packs a history buffer, plus the planner's validation. tests/test_eb_jepa_two_rooms.py is opt-in (it needs eb_jepa and a trained run) and is skipped in CI.
• Docs. The roadmap marks Week 1 done, with Weeks 3 and 4 next. Four decision entries record the protocol's shape, where it lives, the milestone order and a rule for cloud GPU spend, which CLAUDE.md also carries. The plan is closed with its completion summary.
• A build fix. scripts/build.sh reported a wheel without the viewer about half the time on bash, although the viewer was there: under pipefail, piping unzip -l into grep -q fails when grep exits early. It now reads the listing first.

Results

The model was trained with eb_jepa's own script (one NVIDIA L40S, about 1.6 hours). eb_jepa's own CEM evaluation then reached the goal in 18 of 20 episodes.

On the tested CPU cases, the adapter reproduces eb_jepa's rollouts (difference 0.0) and costs (9e-8 relative), and given the same noise the reference CEM reproduces eb_jepa's plans (6e-7). All 20 replayed start frames match eb_jepa's evaluation. In a separate closed-loop check on a different device, planning through the protocol solved 16 of 20 episodes against 18 of 20 natively and passed a threshold fixed before the run. That rule is a net-count engineering threshold, and the result does not establish that the protocol loses no planning quality. A greedy policy solved 9 of 20 and an untrained model 0 of 10.

Reviews

• A fresh-context reviewer passed the branch twice, and its minor findings are fixed.
• A Fable architect reviewed the protocol's design before it was recorded; its recommended changes were approved and applied.
• An outside reviewer found no Critical issues and five Major ones about the contract and the claims. All eleven findings were addressed: the state_shape rename, the adapter rules and their tests, step-by-step cost, input validation, the action contract, and the more careful wording of the results. Four checks it suggested are listed in the spec as not yet done.

Checks

• uv run ruff check src tests, uv run ruff format --check src tests and uv run pytest -q pass (62 passed; the opt-in tests skip).
• ./scripts/build.sh and python3 .claude/workflow/check.py pass.
• The full opt-in test passed earlier (5 tests, 82 minutes, on the code at 00e6919). The short opt-in checks were rerun on the final planner code:

jepa-scope revision: 3ac29ff8bc686e66a62fff9d819117f48152c3e3
eb_jepa revision: 966e61e9285b3a876f49b9774e9720d9a99a7925
machine: Apple M3 Max, CPU, float32
torch: 2.6.0
checkpoint sha256: 9dc746586ba996590e13186cfc72bf76d45d25f038d99266ece59ce01eb13bb4
Parity: max |protocol rollout - eb_jepa unroll| = 0.00e+00
Cost: max relative difference = 8.95e-08
Same-noise CEM, steps_left=None: max |protocol plan - eb_jepa plan| = 5.96e-07
Same-noise CEM, steps_left=7: max |protocol plan - eb_jepa plan| = 0.00e+00
======================= 4 passed, 3 deselected in 8.79s ========================

A planted deviation (a biased standard deviation in the CEM's elite update) makes the same-noise check fail by 0.45 and 0.16.