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