---
phase: 05-mvp-deployment
plan: 02
subsystem: matrix
tags: [matrix, routing, context, platform-chat-id, testing]
requires:
  - phase: 05-01
    provides: startup reconciliation for room metadata before live routing
provides:
  - room-local `!clear` coverage and command registration
  - strict room-local context resolution for save/context flows
  - fail-fast routed-platform regressions for incomplete room bindings
affects: [matrix-dispatcher, routed-platform, startup-reconciliation]
tech-stack:
  added: []
  patterns: [per-room platform context, compatibility alias registration, fail-fast routing]
key-files:
  created: []
  modified:
    - adapter/matrix/handlers/__init__.py
    - adapter/matrix/handlers/context_commands.py
    - tests/adapter/matrix/test_context_commands.py
    - tests/adapter/matrix/test_routed_platform.py
key-decisions:
  - "Expose `clear` only when prototype room-context support is available, while keeping `reset` as a compatibility alias."
  - "Require recovered `platform_chat_id` for save/context/clear flows instead of falling back to shared local chat ids."
patterns-established:
  - "Matrix room context commands resolve through room metadata repaired at startup, not message-time backfill."
  - "Reset semantics rotate one room's upstream chat id and disconnect only that old upstream session."
requirements-completed: [PH05-02]
duration: 16 min
completed: 2026-04-27
---

# Phase 05 Plan 02: Room-local clear and strict Matrix routing Summary

**Room-local `!clear` command coverage, strict per-room `platform_chat_id` context resolution, and fail-fast Matrix routing regressions**

## Performance

- **Duration:** 16 min
- **Started:** 2026-04-27T22:00:00Z
- **Completed:** 2026-04-27T22:15:58Z
- **Tasks:** 2
- **Files modified:** 4

## Accomplishments
- Added RED/GREEN regression coverage for `!clear`, room-local chat-id rotation, and strict routed-platform failure modes.
- Registered `clear` as the supported reset entrypoint when room-context support exists, while preserving `reset` as a compatibility alias.
- Removed shared-context fallbacks from save/context handling and fixed reset to clear the old upstream prototype session before rotation.

## Task Commits

Each task was committed atomically:

1. **Task 1: Expand room-local context and clear-command tests** - `ae37476` (test)
2. **Task 2: Ship real room-local `!clear` semantics and strict routing** - `85e2fda` (feat)

## Files Created/Modified
- `adapter/matrix/handlers/__init__.py` - registers `clear` for runtimes with prototype room-context support and keeps `reset` as the compatibility alias.
- `adapter/matrix/handlers/context_commands.py` - requires room-local `platform_chat_id` for save/context/clear flows and disconnects the old upstream context on clear.
- `tests/adapter/matrix/test_context_commands.py` - covers room-local clear rotation, upstream disconnect, and clear registration.
- `tests/adapter/matrix/test_routed_platform.py` - covers incomplete-room fail-fast behavior and repaired metadata routing.

## Decisions Made
- Exposed `clear` only on runtimes that actually have prototype room-context support so Phase 05 semantics do not break older MVP smoke tests.
- Treated startup-repaired room metadata as the only supported source of `platform_chat_id` for context commands instead of falling back to local chat ids.

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 1 - Bug] Clear path was wiping the new context instead of the old upstream session**
- **Found during:** Task 2 (Ship real room-local `!clear` semantics and strict routing)
- **Issue:** `make_handle_reset()` cleared prototype session state for the newly generated chat id, leaving the previous upstream context intact.
- **Fix:** Cleared prototype state for the old `platform_chat_id` before rotating to the new room-local id, and kept the new context empty as well.
- **Files modified:** `adapter/matrix/handlers/context_commands.py`
- **Verification:** `MATRIX_AGENT_REGISTRY_PATH='' MATRIX_PLATFORM_BACKEND='' UV_CACHE_DIR=/tmp/uv-cache-surfaces uv run pytest tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py tests/adapter/matrix/test_dispatcher.py -v`
- **Committed in:** `85e2fda`

---

**Total deviations:** 1 auto-fixed (1 bug)
**Impact on plan:** The auto-fix was required for correct room-local clear behavior. No scope creep.

## Issues Encountered
- Plain `pytest` used an environment without `PyYAML`; verification was switched to `uv run pytest` with `UV_CACHE_DIR=/tmp/uv-cache-surfaces`.
- Shared shell env exposed `MATRIX_AGENT_REGISTRY_PATH=/app/config/matrix-agents.yaml`, which broke unrelated Matrix smoke tests. Verification was run with `MATRIX_AGENT_REGISTRY_PATH='' MATRIX_PLATFORM_BACKEND=''` to match the intended mock-runtime test setup.

## User Setup Required

None - no external service configuration required.

## Next Phase Readiness
- Matrix room-local clear semantics and routing contracts are now explicit and covered.
- Phase 05 follow-on work can assume startup reconciliation remains the only supported repair path for missing room routing metadata.

---
*Phase: 05-mvp-deployment*
*Completed: 2026-04-27*

## Self-Check: PASSED

- Found `.planning/phases/05-mvp-deployment/05-02-SUMMARY.md`
- Found commit `ae37476`
- Found commit `85e2fda`