From e73e13e758c99636d3d4d132560e285876c6eaaf Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 01:17:48 +0300 Subject: [PATCH] docs(05-02): complete room-local clear plan - add execution summary for room-local clear and strict routing - update roadmap and state with plan 05-02 completion metadata --- .planning/ROADMAP.md | 8 +- .planning/STATE.md | 32 ++++-- .../phases/05-mvp-deployment/05-02-SUMMARY.md | 106 ++++++++++++++++++ 3 files changed, 133 insertions(+), 13 deletions(-) create mode 100644 .planning/phases/05-mvp-deployment/05-02-SUMMARY.md diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index b27bdb1..4e8799b 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -70,13 +70,13 @@ Plans: **Depends on:** Phase 4 -**Plans:** 1/4 plans executed +**Plans:** 4/4 plans complete Plans: -- [ ] 05-01-PLAN.md — Startup reconciliation from authoritative Matrix Space topology before live sync -- [ ] 05-02-PLAN.md — Room-local `platform_chat_id` routing and real `!clear` semantics +- [x] 05-01-PLAN.md — Startup reconciliation from authoritative Matrix Space topology before live sync +- [x] 05-02-PLAN.md — Room-local `platform_chat_id` routing and real `!clear` semantics - [x] 05-03-PLAN.md — Shared-volume attachment path hardening for `/agents` deployment -- [ ] 05-04-PLAN.md — Split bot-only prod compose from internal fullstack compose and update docs +- [x] 05-04-PLAN.md — Split bot-only prod compose from internal fullstack compose and update docs **Deliverables:** - Space+rooms onboarding remains the primary Matrix UX diff --git a/.planning/STATE.md b/.planning/STATE.md index 5c8e4ce..2d48990 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -3,12 +3,12 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: — Production-ready surfaces status: Executing Phase 05 -last_updated: "2026-04-27T22:06:43.419Z" +last_updated: "2026-04-27T22:15:58Z" progress: total_phases: 6 - completed_phases: 2 + completed_phases: 3 total_plans: 16 - completed_plans: 10 + completed_plans: 13 --- # State @@ -24,12 +24,19 @@ See: .planning/PROJECT.md (updated 2026-04-02) **Phase 05** in progress: MVP deployment hardening -Plan `05-03` is complete. Shared-volume attachment handling now keeps Matrix file references room-safe on disk and relative across the `/agents` deployment boundary. +Plan `05-01` is complete. Matrix startup now reconciles managed Space rooms from synced topology before live traffic, restoring local metadata and deterministic legacy `platform_chat_id` bindings on restart. -- `cafb0ec` — failing regressions for `/agents` workspace paths and send-file normalization -- `9a03160` — runtime normalization of `/workspace` and `/agents` absolute paths back to relative `workspace_path` values +- `a75b26a` — failing restart reconciliation regressions for recovery, idempotence, startup ordering, and legacy backfill +- `8a80d00` — startup reconciliation module and pre-sync wiring in the Matrix runtime -Verified with `UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v`. +Verified with `MATRIX_AGENT_REGISTRY_PATH='' MATRIX_PLATFORM_BACKEND='' UV_CACHE_DIR=/tmp/uv-cache-surfaces uv run pytest tests/adapter/matrix/test_invite_space.py tests/adapter/matrix/test_chat_space.py tests/adapter/matrix/test_reconciliation.py tests/adapter/matrix/test_restart_persistence.py tests/adapter/matrix/test_dispatcher.py -v`. + +Plan `05-02` is complete. Matrix room-local context commands now rely on repaired per-room `platform_chat_id` bindings, and `!clear` rotates only the active room's upstream context when prototype room state is available. + +- `ae37476` — failing regressions for clear registration, room-local rotation, and strict routed-platform metadata requirements +- `85e2fda` — room-local clear semantics, compatibility alias wiring, and strict context resolution without shared chat fallbacks + +Verified with `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`. ## Decisions @@ -59,6 +66,11 @@ Verified with `UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/adapter/matrix/tes - [Phase 05 reset]: Discard the single-chat / DM-first deployment direction. Replan around Space+rooms, per-room `platform_chat_id`, real `!clear`, reconciliation, and split prod/fullstack compose artifacts. - [Phase 05]: Keep adapter/matrix/files.py as the sole path builder; sdk/real.py only normalizes shared-volume attachment references. - [Phase 05]: Normalize /workspace and /agents absolute file paths back to relative workspace_path values before agent transport and Matrix file rendering. +- [Phase 05]: Treat synced Matrix topology as authoritative for startup recovery; keep SQLite rebuildable. +- [Phase 05]: Backfill missing platform_chat_id values during startup reconciliation before routed handling begins. +- [Phase 05]: Expose `clear` only when prototype room-context support is available, while keeping `reset` as a compatibility alias. +- [Phase 05]: Require recovered `platform_chat_id` for save/context/clear flows instead of falling back to shared local chat ids. +- [Phase 05]: Split Compose artifacts by runtime intent: bot-only prod handoff vs internal full-stack verification. ## Blockers @@ -88,9 +100,11 @@ Verified with `UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/adapter/matrix/tes | 04 | 03 | 1 session | 1 commit + summary | 4 | 2026-04-17 | | 04 | follow-up | 1 session | 5 tasks | 10+ | 2026-04-24 | | 05 | 03 | 3 min | 2 | 3 | 2026-04-27T22:06:43Z | +| 05 | 01 | 8 min | 2 | 4 | 2026-04-27T22:09:28Z | +| 05 | 02 | 16 min | 2 | 4 | 2026-04-27T22:15:58Z | ## Session -- Last session: 2026-04-27T22:06:43Z -- Stopped at: Completed 05-03-PLAN.md +- Last session: 2026-04-27T22:15:58Z +- Stopped at: Completed 05-02-PLAN.md - Resume file: .planning/phases/05-mvp-deployment/.continue-here.md diff --git a/.planning/phases/05-mvp-deployment/05-02-SUMMARY.md b/.planning/phases/05-mvp-deployment/05-02-SUMMARY.md new file mode 100644 index 0000000..fa4a48c --- /dev/null +++ b/.planning/phases/05-mvp-deployment/05-02-SUMMARY.md @@ -0,0 +1,106 @@ +--- +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`