Surfaces_team/surfaces
4
0
Fork 0
Code Issues 5 Pull requests Projects Releases Packages Wiki Activity Actions

docs(05-02): complete room-local clear plan

Browse source 
- add execution summary for room-local clear and strict routing
- update roadmap and state with plan 05-02 completion metadata
This commit is contained in:
Mikhail Putilovskij 2026-04-28 01:17:48 +03:00
parent 22a3a2b60a
commit e73e13e758
3 changed files with 133 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

8
.planning/ROADMAP.md
View file

@ -70,13 +70,13 @@ Plans:
**Depends on:** Phase 4 **Depends on:** Phase 4
**Plans:** 1/4 plans executed **Plans:** 4/4 plans complete
Plans: Plans:
- [ ] 05-01-PLAN.md — Startup reconciliation from authoritative Matrix Space topology before live sync - [x] 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-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 - [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:** **Deliverables:**
- Space+rooms onboarding remains the primary Matrix UX - Space+rooms onboarding remains the primary Matrix UX

32
.planning/STATE.md
View file

@ -3,12 +3,12 @@ gsd_state_version: 1.0
milestone: v1.0 milestone: v1.0
milestone_name: — Production-ready surfaces milestone_name: — Production-ready surfaces
status: Executing Phase 05 status: Executing Phase 05
last_updated: "2026-04-27T22:06:43.419Z" last_updated: "2026-04-27T22:15:58Z"
progress: progress:
total_phases: 6 total_phases: 6
completed_phases: 2 completed_phases: 3
total_plans: 16 total_plans: 16
completed_plans: 10 completed_plans: 13
--- ---
# State # State
@ -24,12 +24,19 @@ See: .planning/PROJECT.md (updated 2026-04-02)
**Phase 05** in progress: MVP deployment hardening **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 - `a75b26a` — failing restart reconciliation regressions for recovery, idempotence, startup ordering, and legacy backfill
- `9a03160` — runtime normalization of `/workspace` and `/agents` absolute paths back to relative `workspace_path` values - `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 ## 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 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]: 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]: 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 ## 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 | 03 | 1 session | 1 commit + summary | 4 | 2026-04-17 |
| 04 | follow-up | 1 session | 5 tasks | 10+ | 2026-04-24 | | 04 | follow-up | 1 session | 5 tasks | 10+ | 2026-04-24 |
| 05 | 03 | 3 min | 2 | 3 | 2026-04-27T22:06:43Z | | 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 ## Session
- Last session: 2026-04-27T22:06:43Z - Last session: 2026-04-27T22:15:58Z
- Stopped at: Completed 05-03-PLAN.md - Stopped at: Completed 05-02-PLAN.md
- Resume file: .planning/phases/05-mvp-deployment/.continue-here.md - Resume file: .planning/phases/05-mvp-deployment/.continue-here.md

106
.planning/phases/05-mvp-deployment/05-02-SUMMARY.md Normal file
View file

@ -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`