surfaces/.planning/phases/01-matrix-qa-polish/01-CONTEXT.md

Phase 1: Matrix QA & Polish — Context

Gathered: 2026-04-02 Status: Ready for planning

## Phase Boundary

Переработать и довести Matrix адаптер до уровня "приемлемо работает" как Telegram:

• Переход с DM-first на Space+rooms архитектуру
• Убрать реакции как механизм подтверждения — заменить текстовыми командами
• Реализовать все команды управления (!new, !chats, !rename, !archive, !skills, !soul, !safety, !settings)
• Подтвердить работу ручным тестированием (бот уже запускался)

Новые возможности (коннекторы, E2EE, Space discovery) — вне scope.

## Implementation Decisions

Архитектура: Space + rooms

• D-01: Space+rooms — единственная поддерживаемая модель. DM-first убрать.
• D-02: При первом invite бот создаёт Space Lambda — {display_name}, внутри — первую комнату Чат 1. Приглашает пользователя.
• D-03: !new [name] создаёт новую комнату внутри Space пользователя, приглашает его туда.
• D-04: !archive выводит комнату из Space (не удаляет).
• D-05: Маппинг room_id → space_id + room_id → chat_id хранится в SQLite через adapter/matrix/store.py.

Подтверждение действий

• D-06: Реакции (👍/❌) — убрать полностью. OutgoingUI с кнопками рендерится как текст + !yes / !no.
• D-07: Когда агент запрашивает подтверждение, бот пишет текстовое сообщение с описанием и подсказкой: Ответьте !yes для подтверждения или !no для отмены.
• D-08: !yes / !no работают в текущей комнате. Состояние ожидания подтверждения хранится per (user_id, room_id).

Команды

• D-09: Все команды работают из любой комнаты Space — нет выделенной комнаты «Настройки».
• D-10: Команды: !new [name], !chats, !rename <name>, !archive, !skills, !soul, !safety, !settings, !yes, !no.
• D-11: !start — не нужен, онбординг через invite flow.

Настройки (Вариант D)

• D-12: !settings — read-only дашборд: одно сообщение со статусом всего (скиллы, soul, safety, активные чаты). Ничего не меняет.
• D-13: Изменения через субкоманды:
  • !skills — показать список; !skill on/off <name> — переключить
  • !soul — показать профиль; !soul name/style/priority/reset <value> — изменить
  • !safety — показать статус; !safety on/off <action> — переключить
• D-14: Каждая команда без аргументов (!skills, !soul, !safety) выводит текущее состояние + подсказку как менять.

Claude's Discretion

• Формат текста в Matrix (plain text vs markdown) — на усмотрение, Matrix клиенты рендерят markdown
• Структура invite-сообщения в новом Space — на усмотрение, главное: приветствие + список команд
• Обработка ошибок matrix-nio (room_create fail, join fail) — логировать + ответить пользователю

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Архитектурные документы

• docs/matrix-prototype.md — описание Space+rooms структуры, FSM состояний, команд (ВНИМАНИЕ: секция "Реакции как действия" устарела — заменена D-06..D-08)
• bot-examples/matrix_bot_rooms.py — reference реализация Space+rooms на matrix-nio (другая архитектура поверх, но паттерны работы с Space/rooms актуальны)

Текущая реализация (требует переработки)

• adapter/matrix/bot.py — точка входа, send_outgoing (реакции убрать), MatrixBot, MatrixRuntime
• adapter/matrix/handlers/auth.py — handle_invite (сейчас создаёт DM без Space — переписать)
• adapter/matrix/handlers/chat.py — make_handle_new_chat (сейчас не добавляет комнату в Space — переписать)
• adapter/matrix/store.py — хранилище метаданных комнат (расширить для space_id)
• adapter/matrix/room_router.py — маршрутизация room_id → chat_id

Протокол

• core/protocol.py — IncomingCommand, OutgoingUI, OutgoingMessage — типы не менять
• adapter/matrix/converter.py — маппинг nio events → IncomingEvent

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• adapter/matrix/store.py: get_room_meta / set_room_meta — переиспользовать, добавить поля space_id
• adapter/matrix/room_router.py: resolve_chat_id — переиспользовать, возможно расширить
• core/handlers/: все обработчики команд уже зарегистрированы через register_all
• adapter/matrix/handlers/settings.py, confirm.py — проверить, возможно переиспользовать/обновить

Known Bugs (из анализа кода)

• auth.py:27: "chat_id": "C1" захардкожен — у каждого нового пользователя будет коллизия
• bot.py:167: _button_action_to_reaction — убрать целиком
• handlers/chat.py:50: room_create не добавляет комнату в Space (space_id не указан)

Integration Points

• AsyncClient.room_create(space=True) — создание Space через matrix-nio
• AsyncClient.room_put_state(room_id, "m.space.child", ...) — добавление комнаты в Space
• Оба метода есть в bot-examples/matrix_bot_rooms.py

</code_context>

## Specific Ideas

• Подтверждение: бот пишет Ответьте !yes для подтверждения или !no для отмены. — явно, без двусмысленности
• !settings — один дашборд-блок, не несколько сообщений

## Deferred Ideas

• Комната «Настройки» как отдельная закреплённая комната — решили не делать в Phase 1
• E2EE / python-olm — инфраструктурный трек, вне scope
• Space discovery (бот находит существующий Space при повторном invite) — Phase 2+
• Attachment handling (m.file, m.image, m.audio) — Phase 2+

---

Phase: 01-matrix-qa-polish Context gathered: 2026-04-02