From 7fce4c9b3e65b06ca83a161dd78a35bf31485b73 Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Sat, 4 Apr 2026 13:14:53 +0300 Subject: [PATCH] wip: 01.1-matrix-restart-reconciliation-and-dev-reset-workflow paused at task 1/2 --- .planning/HANDOFF.json | 87 +++++++++++++++++++ .../.continue-here.md | 48 ++++++++++ 2 files changed, 135 insertions(+) create mode 100644 .planning/HANDOFF.json create mode 100644 .planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.continue-here.md diff --git a/.planning/HANDOFF.json b/.planning/HANDOFF.json new file mode 100644 index 0000000..75fcb6b --- /dev/null +++ b/.planning/HANDOFF.json @@ -0,0 +1,87 @@ +{ + "version": "1.0", + "timestamp": "2026-04-04T10:13:58.720Z", + "phase": "01.1", + "phase_name": "matrix-restart-reconciliation-and-dev-reset-workflow", + "phase_dir": ".planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow", + "plan": 3, + "task": 1, + "total_tasks": 2, + "status": "paused", + "completed_tasks": [], + "remaining_tasks": [ + { + "id": 1, + "name": "Add a dev-only Matrix reset CLI with explicit modes", + "status": "not_started" + }, + { + "id": 2, + "name": "Replace the README reset ritual with the new restart and reset workflow", + "status": "not_started" + } + ], + "blockers": [ + { + "description": "Phase 02 SDK integration remains blocked because platform control-plane contract is not stable yet; current platform repos only clearly expose the direct agent WebSocket layer.", + "type": "external", + "workaround": "Keep the current consumer-facing bot flows and mock-backed facade for now; use Matrix as the internal testing surface and revisit integration once master user/chat/session access is clarified." + } + ], + "human_actions_pending": [ + { + "action": "Confirm with the platform team the minimal control-plane contract for user/chat/session access and whether settings/attachments will exist in master.", + "context": "Current evidence shows agent_api is usable, but master is not yet a stable consumer-facing API.", + "blocking": true + } + ], + "decisions": [ + { + "decision": "Do not start a full rewrite of the consumer-facing bot integration yet.", + "rationale": "Platform direction is visible, but too many pieces outside the direct agent WebSocket protocol are still undefined or inconsistent.", + "phase": "02" + }, + { + "decision": "Treat sdk/mock.py as a temporary local integration facade rather than a near-drop-in replacement for the real platform.", + "rationale": "The current mock assumes a unified platform API, while the real platform is split between control plane and direct agent session.", + "phase": "02" + }, + { + "decision": "Use Matrix as the internal testing surface while waiting for the platform contract to stabilize.", + "rationale": "This preserves product iteration without coupling the bot too early to a moving platform backend.", + "phase": "02" + } + ], + "uncommitted_files": [ + ".planning/config.json", + "adapter/matrix/bot.py", + "adapter/matrix/handlers/__init__.py", + "adapter/matrix/handlers/auth.py", + "adapter/matrix/handlers/chat.py", + "adapter/matrix/handlers/settings.py", + "adapter/telegram/bot.py", + "sdk/mock.py", + "tests/adapter/matrix/test_chat_space.py", + "tests/adapter/matrix/test_dispatcher.py", + "tests/adapter/matrix/test_invite_space.py", + "tests/platform/test_mock.py", + ".planning/phases/01-matrix-qa-polish/01-01-SUMMARY.md", + ".planning/phases/01-matrix-qa-polish/01-04-SUMMARY.md", + ".planning/phases/01-matrix-qa-polish/01-05-PLAN.md", + ".planning/phases/01-matrix-qa-polish/01-06-PLAN.md", + ".planning/phases/01-matrix-qa-polish/01-VERIFICATION.md", + ".planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.gitkeep", + "bot-examples/", + "docs/reports/2026-04-01-surfaces-progress-report.md", + "docs/superpowers/plans/2026-03-31-matrix-adapter.md", + "docs/workflow-backup-2026-04-01.md", + "forum_topics_research.md", + "image copy 2.png", + "image copy.png", + "image.png", + "lambda_bot.db", + "lambda_matrix.db" + ], + "next_action": "When resuming, either execute Phase 01.1 Plan 03 Task 1 (Matrix reset CLI) or continue the platform-integration design by defining a split MasterClient/AgentSession boundary without changing consumer adapters yet.", + "context_notes": "This session was research-heavy rather than implementation-heavy. The key conclusion is that the real platform currently exposes a direct agent WebSocket SDK plus an unfinished master control plane; our mock models a richer unified platform than what exists today. That means future work should isolate the integration boundary, not rush a full rewrite." +} diff --git a/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.continue-here.md b/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.continue-here.md new file mode 100644 index 0000000..218d478 --- /dev/null +++ b/.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/.continue-here.md @@ -0,0 +1,48 @@ +--- +phase: 01.1-matrix-restart-reconciliation-and-dev-reset-workflow +task: 1 +total_tasks: 2 +status: paused +last_updated: 2026-04-04T10:13:58.720Z +--- + + +Formally, the most recently active GSD artifact is `01.1-03-PLAN.md`, which has not been executed yet. In parallel, an out-of-band research pass compared the local mock SDK against platform repos and concluded that Phase 02 SDK integration is still blocked on an unstable control-plane contract. + + + + +- Session research: inspected local `sdk/interface.py`, `sdk/mock.py`, core message/settings usage, and platform repos `agent_api`, `agent`, `master`, `docs`. +- Established that the real platform currently provides a direct WebSocket `agent_api` for talking to the agent, while `master` is still mostly a control-plane skeleton rather than a stable consumer-facing API. +- Confirmed that the current local mock assumes a richer unified platform API than what is actually implemented today. +- Concluded that consumer adapters should not be deeply rewritten yet; Matrix remains the right internal testing surface for now. + + + + +- Task 1: Implement `adapter.matrix.reset` with `local-only`, `server-leave-forget`, and `--dry-run`, plus tests. +- Task 2: Update `README.md` so restart vs explicit reset workflow is documented and the old manual reset ritual is removed. +- Phase 02 follow-up, once platform stabilizes: split the current platform boundary into control-plane and direct-agent-session abstractions instead of keeping a single `PlatformClient`. + + + + +- Keep the current consumer-facing bot logic largely intact for now; do not force an early rewrite around the incomplete platform backend. +- Treat `sdk/mock.py` as a temporary local integration facade, not as a near-drop-in simulation of the real platform. +- Use Matrix for internal testing while waiting for the platform team to finalize the minimal control-plane contract. + + + +- Platform contract blocker: `agent_api` is concrete enough to study, but `master` still does not expose a stable user/chat/session/settings API for surfaces. +- Product contract blocker: attachments, settings, webhook-style long task events, and exact session bootstrap flow are still unclear on the platform side. + + + +The key mental model from this session: our mock pretends the platform is already a complete backend, but the real platform today is split. There is a usable direct agent WebSocket protocol, and there is a developing master control plane, but they have not converged into the unified SDK shape that the bot currently assumes. Because of that, the right near-term move is not to rush integration, but to preserve momentum with Matrix/internal testing and keep the future integration boundary explicit. + + + +Start with one of these, depending on priority: +1. Execute `01.1-03-PLAN.md` Task 1 and build the Matrix reset CLI. +2. If returning to platform research, write a concrete draft interface for `MasterClient` + `AgentSession` while leaving consumer adapters unchanged. +