docs(01.1): capture matrix restart and reset phase context

.planning/phases/01.1-matrix-restart-reconciliation-and-dev-reset-workflow/01.1-CONTEXT.md

@@ -0,0 +1,121 @@
+# Phase 01.1: Matrix restart reconciliation and dev reset workflow - Context
+
+**Gathered:** 2026-04-03
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Сделать Matrix-адаптер пригодным для повторяемой локальной разработки и ручного QA без ручного “ритуала” удаления БД, выхода из всех комнат и пересоздания пользователя.
+
+В scope этой фазы:
+- безопасный restart flow для Matrix-бота после потери локального state
+- reconciliation локального store с уже существующими Matrix rooms / Space
+- отдельный dev reset workflow для controlled clean-room QA
+- диагностируемое поведение при несогласованности local state и server-side Matrix state
+
+Вне scope:
+- реальный Lambda SDK
+- новые пользовательские Matrix features
+- E2EE
+- production-grade multi-user migration framework
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Matrix state lifecycle
+
+- **D-01:** Локальный SQLite store больше не должен считаться единственной точкой истины для Matrix runtime в dev workflow.
+- **D-02:** При старте бот должен пытаться восстановить минимально необходимое локальное состояние из уже существующих Matrix rooms / Space, а не требовать full reset.
+- **D-03:** Reconciliation должен восстанавливать как минимум `matrix_user:*`, `matrix_room:*` и missing `chat:{user}:{chat_id}` записи, если серверные комнаты уже существуют.
+- **D-04:** Reconciliation не должен создавать новые Space/rooms, если задача — именно восстановление локального state после рестарта.
+
+### Dev restart behavior
+
+- **D-05:** Обычный restart бота должен быть основным путём для разработки; удаление `lambda_matrix.db` и `matrix_store` не должно быть обязательным для проверки workflow.
+- **D-06:** Если local state неполон, бот должен либо восстановить его, либо логировать понятную причину, а не падать на командах вроде `!rename`.
+- **D-07:** Несогласованность между `room_meta` и `ChatManager` должна обнаруживаться и устраняться автоматически на startup или при первом обращении.
+
+### Dev reset workflow
+
+- **D-08:** Нужен отдельный dev-only reset tool/script для controlled QA, вместо ручного набора shell-команд.
+- **D-09:** Reset workflow должен как минимум поддерживать `local-only` reset: удаление `lambda_matrix.db` и `matrix_store` с понятной инструкцией, что делать с server-side Matrix rooms.
+- **D-10:** Если full server-side cleanup не автоматизируется в этой фазе, tool должен явно печатать, какие ручные шаги обязательны в Matrix client.
+
+### The agent's Discretion
+
+- Точное место вызова reconciliation в startup flow
+- Внутренняя структура helper-модуля (`bootstrap.py`, `reconcile.py` или аналог)
+- Формат dev reset script и уровень автоматизации server-side cleanup
+- Детали debug-logging и dry-run режима, если они помогают без раздувания scope
+
+</decisions>
+
+<specifics>
+## Specific Ideas
+
+- Главный критерий: после обычного restart бот не должен ломаться только потому, что local DB была сброшена или частично потеряна.
+- Reset workflow должен быть явным и repeatable, а не завязанным на память разработчика.
+- Нужно различать две ситуации:
+  - broken because code is wrong
+  - broken because local dev state was deliberately reset and requires reconciliation
+
+</specifics>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### Matrix phase artifacts
+- `.planning/phases/01-matrix-qa-polish/01-CONTEXT.md` — locked Matrix decisions from Phase 1
+- `.planning/phases/01-matrix-qa-polish/01-VERIFICATION.md` — what Phase 1 already validated and what manual QA still expects
+- `.planning/phases/01-matrix-qa-polish/01-HUMAN-UAT.md` — remaining real-client Matrix checks
+
+### Current Matrix runtime
+- `adapter/matrix/bot.py` — startup flow, sync loop, runtime wiring, DB/store env vars
+- `adapter/matrix/store.py` — persisted Matrix metadata and pending confirmation keys
+- `adapter/matrix/room_router.py` — room_id to chat_id resolution and current unregistered fallback
+- `adapter/matrix/handlers/auth.py` — invite bootstrap that creates Space and first chat room
+- `core/chat.py` — `ChatManager` persistence contract that currently breaks when local state is missing
+
+### Supporting docs
+- `docs/matrix-prototype.md` — intended Matrix UX and architecture direction
+- `README.md` — current run instructions and existing manual QA/reset habits
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `adapter/matrix/store.py` already persists room/user metadata and is the obvious place to anchor reconciliation inputs.
+- `adapter/matrix/room_router.py` already detects unknown rooms via `unregistered:{room_id}` fallback; this is a useful reconciliation trigger point.
+- `core/chat.py` already has `get_or_create`, `rename`, `archive`, `list_active`; missing chat records can be rebuilt through this API instead of inventing a parallel format.
+
+### Established Patterns
+- Matrix runtime uses `SQLiteStore` for adapter-local metadata and `matrix-nio` room callbacks for transport events.
+- Phase 1 already moved Matrix to Space+rooms and command-only confirmations, so this phase must preserve that model rather than reverting to DM-first simplifications.
+
+### Integration Points
+- Startup path in `adapter/matrix/bot.py:main()` is the natural place to run reconciliation before `sync_forever`.
+- Invite/bootstrap path in `adapter/matrix/handlers/auth.py` is the existing source of truth for what metadata a healthy first room should have.
+- `ChatManager` records and `matrix_room:*` metadata must stay consistent enough that commands like `!rename`, `!archive`, and `!chats` work after restart.
+
+</code_context>
+
+<deferred>
+## Deferred Ideas
+
+- Full production-grade migration of historical Matrix state across schema versions
+- Automatic server-side deletion/leave for all Matrix rooms and Space during reset, if it requires broader admin semantics
+- Any Phase 2 SDK integration work
+
+</deferred>
+
+---
+
+*Phase: 01.1-matrix-restart-reconciliation-and-dev-reset-workflow*
+*Context gathered: 2026-04-03*