surfaces/.planning/phases/05-mvp-deployment/05-02-PLAN.md

phase	plan	type	wave	depends_on	files_modified	autonomous	requirements	must_haves
05-mvp-deployment	02	execute	2	05-01	adapter/matrix/handlers/__init__.py adapter/matrix/handlers/context_commands.py adapter/matrix/routed_platform.py tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py	true	PH05-02	truths artifacts key_links Each working Matrix room uses its own durable `platform_chat_id` as the real agent context boundary. `!clear` resets only the current room by rotating its `platform_chat_id` and disconnecting the old upstream chat. Save, load, context, and routed send paths resolve through room-local platform context, not shared user state. Strict room routing assumes startup reconciliation has already repaired legacy rooms missing `platform_chat_id`. path provides adapter/matrix/handlers/context_commands.py Room-local `!clear`, save/load/context resolution, and upstream disconnect behavior path provides adapter/matrix/routed_platform.py Strict room -> agent_id + platform_chat_id routing path provides tests/adapter/matrix/test_context_commands.py Regression coverage for `!clear` and room-local context commands from to via pattern adapter/matrix/handlers/__init__.py adapter/matrix/handlers/context_commands.py IncomingCommand registration for `clear` "clear" from to via pattern adapter/matrix/routed_platform.py adapter/matrix/store.py room metadata lookup platform_chat_id

Make room-local platform context explicit and user-facing by shipping real `!clear` semantics and strict per-room routing.

Purpose: Phase 05 must preserve Space+rooms UX while giving each room a true upstream context boundary. Output: Updated command wiring, room-local context reset behavior, and routing regressions tied to platform_chat_id.

<execution_context> @/Users/a/.codex/get-shit-done/workflows/execute-plan.md @/Users/a/.codex/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/05-mvp-deployment/05-RESEARCH.md @.planning/phases/05-mvp-deployment/05-VALIDATION.md @.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-02-SUMMARY.md @adapter/matrix/handlers/__init__.py @adapter/matrix/handlers/context_commands.py @adapter/matrix/routed_platform.py @tests/adapter/matrix/test_context_commands.py @tests/adapter/matrix/test_routed_platform.py From `adapter/matrix/handlers/__init__.py`:

dispatcher.register(
    IncomingCommand,
    "reset",
    make_handle_reset(store, prototype_state)
    if prototype_state is not None
    else handle_settings,
)

From adapter/matrix/handlers/context_commands.py:

async def _resolve_context_scope(
    event: IncomingCommand,
    store: StateStore,
    chat_mgr,
) -> tuple[str, str | None]: ...

From adapter/matrix/routed_platform.py:

async def _resolve_delegate(self, user_id: str, local_chat_id: str) -> tuple[PlatformClient, str]:
    ...

Task 1: Expand room-local context and clear-command tests tests/adapter/matrix/test_context_commands.py, tests/adapter/matrix/test_routed_platform.py tests/adapter/matrix/test_context_commands.py, tests/adapter/matrix/test_routed_platform.py, adapter/matrix/handlers/__init__.py, adapter/matrix/handlers/context_commands.py, adapter/matrix/routed_platform.py, .planning/phases/05-mvp-deployment/05-VALIDATION.md - Test 1: `!clear` rotates only the current room's `platform_chat_id` and disconnects only the old upstream chat (per PH05-02). - Test 2: `!clear` is the supported command name; `!reset` may remain as a compatibility alias but must not be the only registered path. - Test 3: routed send/stream paths fail fast when room metadata lacks `agent_id` or `platform_chat_id` instead of silently sharing context. - Test 4: routed behavior uses startup-repaired room metadata and does not introduce a second fallback path that invents `platform_chat_id` during message handling. - Tests explicitly mention `clear` in command registration or command invocation. - The context-command tests assert old and new `platform_chat_id` values and upstream disconnect behavior. - The routed-platform tests assert room-local IDs are passed to delegates unchanged. Extend the current Matrix context-command and routed-platform regressions so Phase 05 has direct coverage for `!clear`, room-local `platform_chat_id` rotation, and fail-fast routing when room bindings are incomplete. Treat startup reconciliation from `05-01` as the only supported repair path for legacy rooms missing `platform_chat_id`; the routed path must consume repaired metadata, not synthesize new room identities on demand. Preserve the Phase 04 prototype-state behavior where it still fits, but anchor new checks on per-room context isolation rather than shared session assumptions. pytest tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py -v The tests define the Phase 05 room-local contract for reset/clear and for routed upstream calls. Task 2: Ship real room-local `!clear` semantics and strict routing adapter/matrix/handlers/__init__.py, adapter/matrix/handlers/context_commands.py, adapter/matrix/routed_platform.py adapter/matrix/handlers/__init__.py, adapter/matrix/handlers/context_commands.py, adapter/matrix/routed_platform.py, tests/adapter/matrix/test_context_commands.py, tests/adapter/matrix/test_routed_platform.py, .planning/phases/05-mvp-deployment/05-RESEARCH.md - Test 1: command registration exposes `!clear` as the real context-reset entrypoint for Matrix rooms. - Test 2: only the active room's `platform_chat_id` rotates, and only the old upstream chat session is disconnected. - Test 3: all room-local context commands resolve through recovered room metadata instead of falling back to shared user scope. - Test 4: strict routing stays strict at runtime because legacy-room repair was already handled at startup by `05-01`, not by hidden message-path fallbacks. - `adapter/matrix/handlers/__init__.py` registers `clear`; if `reset` remains, it is clearly a compatibility alias. - `adapter/matrix/handlers/context_commands.py` resolves and rotates room-local platform context without touching other rooms. - `adapter/matrix/routed_platform.py` keeps explicit `MATRIX_ROUTE_INCOMPLETE` behavior when bindings are missing. Update the Matrix context command surface to match the Phase 05 contract: real `!clear`, room-local `platform_chat_id` rotation, and upstream disconnect scoped to the old room context. Keep `save`, `load`, and `context` anchored to the same room-local identity. Tighten routed-platform behavior only where needed to preserve fail-fast semantics after startup reconciliation has repaired legacy rooms; do not reintroduce shared chat state, user-level reset behavior, or message-time backfill of missing `platform_chat_id`. pytest tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py tests/adapter/matrix/test_dispatcher.py -v Users can clear one working room without affecting others, and all routed upstream calls stay bound to room-local platform context. Run the context and routed-platform slices plus Matrix dispatcher smoke coverage to confirm the exposed command name and room-local routing behavior are consistent.

<success_criteria> Every working Matrix room has an independent upstream context boundary, and !clear resets only the room where it is invoked. </success_criteria>

After completion, create `.planning/phases/05-mvp-deployment/05-02-SUMMARY.md`