docs(01-02): complete matrix chat handlers plan

- record the 01-02 execution summary and self-check
- update roadmap progress for completed phase 01 plans
- persist state decisions, metrics, and next-plan focus

.planning/ROADMAP.md

@@ -11,8 +11,8 @@
 **Plans:** 4 plans
 
 Plans:
-- [ ] 01-01-PLAN.md — Space+rooms infrastructure (store helpers, handle_invite rewrite, room_router)
-- [ ] 01-02-PLAN.md — Chat command handlers (!new, !archive, !rename) Space-aware
+- [x] 01-01-PLAN.md — Space+rooms infrastructure (store helpers, handle_invite rewrite, room_router)
+- [x] 01-02-PLAN.md — Chat command handlers (!new, !archive, !rename) Space-aware
 - [ ] 01-03-PLAN.md — Reaction removal + !yes/!no confirmation + settings dashboard
 - [ ] 01-04-PLAN.md — Test suite (fix 4 broken + 12 new MAT-01..MAT-12)
 

.planning/STATE.md

@@ -1,3 +1,16 @@
+---
+gsd_state_version: 1.0
+milestone: v1.0
+milestone_name: — Production-ready surfaces
+status: in_progress
+last_updated: "2026-04-02T19:52:40.867Z"
+progress:
+  total_phases: 3
+  completed_phases: 0
+  total_plans: 4
+  completed_plans: 2
+---
+
 # State
 
 ## Project Reference
@@ -5,7 +18,7 @@
 See: .planning/PROJECT.md (updated 2026-04-02)
 
 **Core value:** Пользователь ведёт диалог с Lambda через любой мессенджер без изменения ядра
-**Current focus:** Phase 1 — Matrix QA & Polish
+**Current focus:** Phase 01 — matrix-qa-polish (next: 01-03)
 
 ## Current Phase
 
@@ -14,7 +27,22 @@ See: .planning/PROJECT.md (updated 2026-04-02)
 ## Decisions
 
 - Продолжаем с Threaded Mode несмотря на баги Mac клиента (2026-04-02)
+- Invite flow Matrix переведён на idempotent-проверку через `user_meta.space_id`, а не через invite-room metadata (2026-04-02)
+- Неизвестные Matrix rooms больше не auto-register в роутере; используется явный fallback `unregistered:{room_id}` с warning-логом (2026-04-02)
+- [Phase 01]: Use ChatContext.surface_ref as the Matrix room identifier for !rename updates.
+- [Phase 01]: Keep !archive limited to core archive state in Phase 1; Space child removal remains deferred.
 
 ## Blockers
 
 - Lambda platform SDK не готов — Phase 2 заблокирована до готовности платформы
+
+## Performance Metrics
+
+| Phase | Plan | Duration | Tasks | Files | Recorded |
+| --- | --- | --- | --- | --- | --- |
+| 01 | 02 | 1 min | 2 | 2 | 2026-04-02 |
+
+## Session
+
+- Last session: 2026-04-02T19:52:40Z
+- Stopped at: Completed 01-02-PLAN.md

.planning/phases/01-matrix-qa-polish/01-02-SUMMARY.md

@@ -0,0 +1,83 @@
+---
+phase: 01-matrix-qa-polish
+plan: 02
+subsystem: api
+tags: [matrix, nio, handlers, spaces]
+requires:
+  - phase: 01-matrix-qa-polish
+    provides: space-aware invite flow and room metadata
+provides:
+  - Matrix `!new` creates chat rooms inside a user's Space
+  - Matrix `!rename` updates both core chat metadata and Matrix room names
+  - Matrix `!archive` uses closure-based handlers aligned with client/store injection
+affects: [matrix handlers, matrix bot, phase-01-04-tests]
+tech-stack:
+  added: []
+  patterns: [closure-based Matrix command handlers, Space child linking via `m.space.child`]
+key-files:
+  created: [.planning/phases/01-matrix-qa-polish/01-02-SUMMARY.md]
+  modified: [adapter/matrix/handlers/chat.py, adapter/matrix/handlers/__init__.py]
+key-decisions:
+  - "Use `ChatContext.surface_ref` as the Matrix room identifier for `!rename` updates."
+  - "Keep `!archive` limited to core archive state in Phase 1; Space child removal remains deferred."
+patterns-established:
+  - "Matrix handlers that need transport dependencies are registered as closure factories."
+  - "`!new` creates rooms by linking the child room into the user's Space before inviting the user."
+requirements-completed: []
+duration: 1min
+completed: 2026-04-02
+---
+
+# Phase 1 Plan 02: Chat command handlers Summary
+
+**Matrix chat commands now create Space-linked rooms, rename underlying Matrix rooms through stored surface refs, and archive chats through client-aware handler factories.**
+
+## Performance
+
+- **Duration:** 1 min
+- **Started:** 2026-04-02T19:51:20Z
+- **Completed:** 2026-04-02T19:51:30Z
+- **Tasks:** 2
+- **Files modified:** 2
+
+## Accomplishments
+- Rewrote `make_handle_new_chat` to require a stored `space_id`, allocate chat IDs via `next_chat_id`, create Matrix rooms, attach them to the Space, and invite the user.
+- Added graceful `RoomCreateError` handling with user-facing messages and structured logging in the Matrix chat handler.
+- Converted `!archive` and `!rename` into closure factories and updated registration to inject `client`/`store`.
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Rewrite make_handle_new_chat for Space** - `84111ca` (feat)
+2. **Task 2: Convert handle_archive and handle_rename to Space-aware closures** - `b7a04b6` (feat)
+
+## Files Created/Modified
+- `adapter/matrix/handlers/chat.py` - Space-aware `!new` flow plus closure-based `!archive` and `!rename`.
+- `adapter/matrix/handlers/__init__.py` - Registers Matrix archive and rename handlers through factory calls.
+- `.planning/phases/01-matrix-qa-polish/01-02-SUMMARY.md` - Execution summary for plan 01-02.
+
+## Decisions Made
+
+- Used `get_user_meta(...).space_id` as the gate for Matrix `!new`, returning a user-facing error instead of crashing when invite setup is incomplete.
+- Used `ChatManager.rename(...).surface_ref` to call `client.room_set_name(...)` without adding a new reverse room lookup mechanism.
+- Kept Space child removal out of `!archive` for Phase 1 because the plan explicitly defers reverse lookup work.
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+
+Matrix chat command handlers are aligned with the Space+rooms model and ready for the Phase 1 test plan.
+`!archive` still defers Space child removal by design; Phase 2 or later will need reverse room lookup if that behavior is required.
+
+## Self-Check: PASSED