---
phase: 05-mvp-deployment
plan: 02
type: execute
wave: 2
depends_on:
  - 05-01
files_modified:
  - 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
autonomous: true
requirements:
  - PH05-02
must_haves:
  truths:
    - "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`."
  artifacts:
    - path: "adapter/matrix/handlers/context_commands.py"
      provides: "Room-local `!clear`, save/load/context resolution, and upstream disconnect behavior"
    - path: "adapter/matrix/routed_platform.py"
      provides: "Strict room -> agent_id + platform_chat_id routing"
    - path: "tests/adapter/matrix/test_context_commands.py"
      provides: "Regression coverage for `!clear` and room-local context commands"
  key_links:
    - from: "adapter/matrix/handlers/__init__.py"
      to: "adapter/matrix/handlers/context_commands.py"
      via: "IncomingCommand registration for `clear`"
      pattern: "\"clear\""
    - from: "adapter/matrix/routed_platform.py"
      to: "adapter/matrix/store.py"
      via: "room metadata lookup"
      pattern: "platform_chat_id"
---

<objective>
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`.
</objective>

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

<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

<interfaces>
From `adapter/matrix/handlers/__init__.py`:

```python
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`:

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

From `adapter/matrix/routed_platform.py`:

```python
async def _resolve_delegate(self, user_id: str, local_chat_id: str) -> tuple[PlatformClient, str]:
    ...
```
</interfaces>
</context>

<tasks>

<task type="auto" tdd="true">
  <name>Task 1: Expand room-local context and clear-command tests</name>
  <files>tests/adapter/matrix/test_context_commands.py, tests/adapter/matrix/test_routed_platform.py</files>
  <read_first>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</read_first>
  <behavior>
    - 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.
  </behavior>
  <acceptance_criteria>
    - 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.
  </acceptance_criteria>
  <action>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.</action>
  <verify>
    <automated>pytest tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py -v</automated>
  </verify>
  <done>The tests define the Phase 05 room-local contract for reset/clear and for routed upstream calls.</done>
</task>

<task type="auto" tdd="true">
  <name>Task 2: Ship real room-local `!clear` semantics and strict routing</name>
  <files>adapter/matrix/handlers/__init__.py, adapter/matrix/handlers/context_commands.py, adapter/matrix/routed_platform.py</files>
  <read_first>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</read_first>
  <behavior>
    - 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.
  </behavior>
  <acceptance_criteria>
    - `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.
  </acceptance_criteria>
  <action>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`.</action>
  <verify>
    <automated>pytest tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py tests/adapter/matrix/test_dispatcher.py -v</automated>
  </verify>
  <done>Users can clear one working room without affecting others, and all routed upstream calls stay bound to room-local platform context.</done>
</task>

</tasks>

<verification>
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.
</verification>

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

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