Mikhail Putilovskij
e73e13e758
- add execution summary for room-local clear and strict routing - update roadmap and state with plan 05-02 completion metadata
106 lines
5.2 KiB
Markdown
106 lines
5.2 KiB
Markdown
---
|
|
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`
|