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

phase	plan	subsystem	tags	requires	provides	affects	tech-stack	key-files	key-decisions	patterns-established	requirements-completed	duration	completed
05-mvp-deployment	02	matrix	matrix routing context platform-chat-id testing	phase provides 05-01 startup reconciliation for room metadata before live routing	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	matrix-dispatcher routed-platform startup-reconciliation	added patterns per-room platform context compatibility alias registration fail-fast routing	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	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.	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.	PH05-02	16 min	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