feat: finalize matrix platform audit and docs

.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.continue-here.md

@@ -3,11 +3,11 @@ phase: 01.1-matrix-restart-reconciliation-and-dev-reset-workflow
 task: 1
 total_tasks: 2
 status: paused
-last_updated: 2026-04-07T15:11:42.203Z
+last_updated: 2026-04-07T21:29:48.982Z
 ---
 
 <current_state>
-Formally, the most recently active execution artifact is still `01.1-03-PLAN.md`, which has not been implemented yet. Since the earlier checkpoint, a fresh live review of the platform repos confirmed that `master` still does not provide a usable consumer-facing control-plane API, but a working Matrix prototype is now feasible by talking directly to the `agent` WebSocket through a new `sdk/real.py` compatibility shim.
+Formally, the most recently active execution artifact inside the roadmap is still `01.1-03-PLAN.md`, which has not been implemented yet. In parallel, the platform-integration track has moved forward: the direct-agent Matrix prototype design is now approved, the implementation plan is written, and the next useful session should evaluate that spec/plan pair against the live platform repos before starting execution.
 </current_state>
 
 <completed_work>
@@ -16,16 +16,19 @@ Formally, the most recently active execution artifact is still `01.1-03-PLAN.md`
 - Confirmed `master` is still only a thin HTTP skeleton with `/health` and `/users/{user_id}`, not a chat/session/settings backend for surfaces.
 - Confirmed `agent` exposes a working `/agent_ws/` WebSocket and `agent_api` provides enough protocol/client code to stream model output.
 - Identified the real technical gap for a prototype: `agent` currently uses a singleton service with a fixed `thread_id="default"`, so all conversations would share memory unless that is parameterized.
-- Derived the recommended prototype path: keep Matrix adapter logic largely intact, add a new `sdk/real.py` shim for direct agent communication, and ask the platform team for a minimal agent-side change to support per-chat thread identity.
-- Started a product/architecture discussion about where that prototype should live: in this repo as the first real backend path, or in a separate repo as a Matrix-only spike. The user asked to save the session before answering that design question.
+- Derived and got approval for the prototype path: keep Matrix adapter logic largely intact, add `sdk/agent_session.py`, `sdk/prototype_state.py`, and `sdk/real.py`, keep settings local, and use the direct `agent` WebSocket for real messaging.
+- Resolved the repo-placement question: the prototype stays in this repo on its own branch, not in a separate prototype repo.
+- Resolved the platform-change minimization question: prefer patching only `platform/agent`, not `platform/agent_api`, and use a tiny local WebSocket client in this repo.
+- Wrote and committed the approved design spec: `docs/superpowers/specs/2026-04-08-matrix-direct-agent-prototype-design.md`.
+- Wrote the implementation plan: `docs/superpowers/plans/2026-04-08-matrix-direct-agent-prototype.md`.
 </completed_work>
 
 <remaining_work>
 
 - Task 1: Implement `adapter.matrix.reset` with `local-only`, `server-leave-forget`, and `--dry-run`, plus tests.
 - Task 2: Update `README.md` so restart vs explicit reset workflow is documented and the old manual reset ritual is removed.
-- Design follow-up: decide whether the direct-agent prototype belongs in this repo or a separate repo.
-- Future prototype work, once design is approved: introduce `sdk/real.py` plus a narrow compatibility boundary that keeps Matrix adapter logic stable while allowing later expansion toward a fuller platform split.
+- Prototype evaluation follow-up: review the approved spec and plan against the platform repos before starting execution.
+- Future prototype work: introduce `sdk/real.py` plus a narrow compatibility boundary that keeps Matrix adapter logic stable while allowing later expansion toward a fuller platform split.
 </remaining_work>
 
 <decisions_made>
@@ -34,6 +37,8 @@ Formally, the most recently active execution artifact is still `01.1-03-PLAN.md`
 - Use the direct `agent` WebSocket as the only realistic path for a working prototype right now.
 - Keep consumer-facing Matrix logic as intact as possible and absorb backend differences inside a shim under `sdk/`.
 - Treat future platform evolution as likely to split into at least two concerns: control-plane access and direct agent session streaming.
+- Keep the prototype in this repo on its own branch.
+- Minimize platform-side changes by patching only `platform/agent` if possible.
 </decisions_made>
 
 <blockers>
@@ -43,12 +48,16 @@ Formally, the most recently active execution artifact is still `01.1-03-PLAN.md`
 </blockers>
 
 <context>
-The important mental model changed slightly since the earlier checkpoint. Before, the conclusion was mainly “Phase 02 is blocked because the platform contract is unstable.” That is still true for full SDK integration through `master`, but it is no longer the whole story. There is now a practical bridge strategy: use the existing `agent` WebSocket directly for message generation, keep settings/user mapping local for the prototype, and preserve adapter stability by hiding all of this behind a new `sdk/real.py` implementation. The open architecture decision is repo placement: short-lived prototype repo versus building the first durable real-backend path here.
+The important mental model is now stable enough to execute. Full SDK integration through `master` is still premature, but a working Matrix prototype can be built now by talking directly to the `agent` WebSocket and hiding the split backend reality behind `sdk/real.py`. The approved design keeps the prototype in this repo, keeps settings local, and minimizes platform changes by preferring a tiny `platform/agent` patch over broader protocol churn. For evaluation and implementation context, inspect:
+- local spec: `docs/superpowers/specs/2026-04-08-matrix-direct-agent-prototype-design.md`
+- local plan: `docs/superpowers/plans/2026-04-08-matrix-direct-agent-prototype.md`
+- remote repos: `https://git.lambda.coredump.ru/platform/agent`, `https://git.lambda.coredump.ru/platform/master`, `https://git.lambda.coredump.ru/platform/agent_api`
+- local clones: `/tmp/platform-agent`, `/tmp/platform-master`, `/tmp/platform-agent_api`
 </context>
 
 <next_action>
 Resume with one of these depending on priority:
-1. If continuing phase execution, implement `01.1-03-PLAN.md` Task 1 (`adapter.matrix.reset`) first.
-2. If continuing platform design, answer the pending repo-placement question: keep the prototype in this repo or create a separate repo for a Matrix-only spike.
-3. After that decision, write the design for the direct-agent shim path before touching code.
+1. Evaluate the approved prototype spec and implementation plan against the live platform repos and decide whether to start in this repo or patch `platform/agent` first.
+2. If staying on roadmap execution, implement `01.1-03-PLAN.md` Task 1 (`adapter.matrix.reset`) first.
+3. If starting prototype execution immediately, begin with Task 1 of `docs/superpowers/plans/2026-04-08-matrix-direct-agent-prototype.md`.
 </next_action>