surfaces/.planning/STATE.md

gsd_state_version	milestone	milestone_name	status	last_updated	progress
1.0	v1.0	— Production-ready surfaces	Phase 05 Complete	2026-04-27T22:17:10.233Z	total_phases completed_phases total_plans completed_plans 6 3 16 13

State

Project Reference

See: .planning/PROJECT.md (updated 2026-04-02)

Core value: Пользователь ведёт диалог с Lambda через любой мессенджер без изменения ядра Current focus: Phase 05 complete — MVP deployment handoff is ready

Current Phase

Phase 05 complete: MVP deployment hardening

Plan 05-01 is complete. Matrix startup now reconciles managed Space rooms from synced topology before live traffic, restoring local metadata and deterministic legacy platform_chat_id bindings on restart.

• a75b26a — failing restart reconciliation regressions for recovery, idempotence, startup ordering, and legacy backfill
• 8a80d00 — startup reconciliation module and pre-sync wiring in the Matrix runtime

Verified with MATRIX_AGENT_REGISTRY_PATH='' MATRIX_PLATFORM_BACKEND='' UV_CACHE_DIR=/tmp/uv-cache-surfaces uv run pytest tests/adapter/matrix/test_invite_space.py tests/adapter/matrix/test_chat_space.py tests/adapter/matrix/test_reconciliation.py tests/adapter/matrix/test_restart_persistence.py tests/adapter/matrix/test_dispatcher.py -v.

Plan 05-02 is complete. Matrix room-local context commands now rely on repaired per-room platform_chat_id bindings, and !clear rotates only the active room's upstream context when prototype room state is available.

• ae37476 — failing regressions for clear registration, room-local rotation, and strict routed-platform metadata requirements
• 85e2fda — room-local clear semantics, compatibility alias wiring, and strict context resolution without shared chat fallbacks

Verified with MATRIX_AGENT_REGISTRY_PATH='' MATRIX_PLATFORM_BACKEND='' UV_CACHE_DIR=/tmp/uv-cache-surfaces uv run pytest tests/adapter/matrix/test_context_commands.py tests/adapter/matrix/test_routed_platform.py tests/adapter/matrix/test_dispatcher.py -v.

Plan 05-03 is complete. Shared-volume attachment handling now preserves relative agent paths while tolerating both /workspace and /agents absolute prefixes during normalization and Matrix file rendering.

• 7a12a71 — failing regressions for shared-volume path normalization and room-safe attachment handling
• 5eddf16 — /agents deployment path hardening for Matrix files and routed platform attachments

Verified with uv run pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v.

Plan 05-04 is complete. Production handoff now uses docker-compose.prod.yml for a bot-only runtime, while internal end-to-end verification uses docker-compose.fullstack.yml with shared /agents volume guidance and health-gated startup.

• df6d8bf — split prod and full-stack compose artifacts with the shared /agents contract
• 22a3a2b — operator and deployment docs aligned to the split compose artifacts

Verified with docker compose -f docker-compose.prod.yml config, docker compose -f docker-compose.fullstack.yml config, and docs grep checks for docker-compose.prod.yml, docker-compose.fullstack.yml, and /agents.

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.
• [Phase 01]: Matrix OutgoingUI no longer emits reactions; confirmation state is persisted and resumed via !yes / !no.
• [Phase 01]: !settings now renders a dashboard snapshot instead of advertising mutable subcommands.
• [Phase 01]: Split Matrix regression coverage into dedicated invite/chat/send_outgoing/confirm test modules.
• [Phase 01]: Kept 01-04 scoped to test coverage without widening into production-code changes.
• [Phase 01]: Matrix command callbacks now include room_id in payload for !yes and !no so confirm handlers can resolve runtime state without changing core protocol types.
• [Phase 01]: Pending confirmations are stored under the D-08 composite key of matrix user id plus room id, with a narrow legacy fallback only for callers that omit room context.
• [Phase 01]: Removed Matrix reaction conversion entirely and kept command callbacks limited to !yes/!no.
• [Phase 01]: Kept !settings as a pure snapshot surface while preserving mutable subcommands outside the dashboard.
• [Phase 01]: Seeded invite and dispatcher tests with explicit next_chat_index and room ids instead of treating C1 as Matrix transport identity.
• [Phase 04]: Replaced AgentSessionClient with AgentApiWrapper and persistent agent connection lifecycle in Matrix runtime.
• [Phase 04]: Added !save, !load, !reset, and !context commands with pending-state interception and local prototype session metadata.
• [Phase 04]: Added Matrix-only Docker packaging for MVP deployment; platform services remain external to this compose setup.
• [Phase 04]: Replaced the Matrix prod path again with direct upstream AgentApi per request; removed the local runtime wrapper from the prod flow.
• [Phase 04]: Adopted AGENT_BASE_URL as the primary runtime contract and kept AGENT_WS_URL only as backward-compatible env fallback.
• [Phase 04 follow-up]: Kept shared PlatformClient unchanged; introduced Matrix-specific RoutedPlatformClient to avoid breaking Telegram adapter.
• [Phase 04 follow-up]: agent_routing_enabled flag on MatrixRuntime activates stale-room check only in real multi-agent mode (RoutedPlatformClient).
• [Phase 04 follow-up]: !new binds agent_id at room creation time using selected_agent_id from user metadata.
• [Phase 04 follow-up]: platform_chat_seq (PLATFORM_CHAT_SEQ_KEY) is stored in SQLiteStore and survives restart — confirmed by test.
• [Phase 05 reset]: Discard the single-chat / DM-first deployment direction. Replan around Space+rooms, per-room platform_chat_id, real !clear, reconciliation, and split prod/fullstack compose artifacts.
• [Phase 05]: Keep adapter/matrix/files.py as the sole path builder; sdk/real.py only normalizes shared-volume attachment references.
• [Phase 05]: Normalize /workspace and /agents absolute file paths back to relative workspace_path values before agent transport and Matrix file rendering.
• [Phase 05]: Treat synced Matrix topology as authoritative for startup recovery; keep SQLite rebuildable.
• [Phase 05]: Backfill missing platform_chat_id values during startup reconciliation before routed handling begins.
• [Phase 05]: Expose clear only when prototype room-context support is available, while keeping reset as a compatibility alias.
• [Phase 05]: Require recovered platform_chat_id for save/context/clear flows instead of falling back to shared local chat ids.
• [Phase 05]: Split Compose artifacts by runtime intent: bot-only prod handoff vs internal full-stack verification.
• [Phase 05]: Document /agents as the bot-side shared volume root while internal platform-agent keeps /workspace on the same named volume.

Blockers

• Lambda platform SDK не готов — Phase 2 заблокирована до готовности платформы

Accumulated Context

Roadmap Evolution

• Phase 01.1 inserted after Phase 01: Matrix restart reconciliation and dev reset workflow (URGENT)
• Phase 4 added: Matrix MVP: shared agent context and context management command
• Phase 04 follow-up added inline: multi-agent routing (RoutedPlatformClient, !agent, stale room blocking, restart persistence)
• Phase 05 reset on 2026-04-28: erroneous single-chat deployment artifacts were removed before fresh planning.

Performance Metrics

Phase	Plan	Duration	Tasks	Files	Recorded
01	01	1 min	3	3	2026-04-02T19:50:50Z
01	02	1 min	2	2	2026-04-02
01	03	3 min	2	5	2026-04-02T19:57:34Z
01	04	3 min	2	7	2026-04-02T20:03:38Z
01	05	2 min	2	7	2026-04-03T09:28:47Z
01	06	4 min	2	7	2026-04-03T09:35:47Z
04	01	1 session	1 wave	8	2026-04-17
04	02	1 session	2 commits + summary	8	2026-04-17
04	03	1 session	1 commit + summary	4	2026-04-17
04	follow-up	1 session	5 tasks	10+	2026-04-24
05	03	3 min	2	3	2026-04-27T22:06:43Z
05	01	8 min	2	4	2026-04-27T22:09:28Z
05	02	16 min	2	4	2026-04-27T22:15:58Z
05	04	3 min	2	5	2026-04-27T22:17:10Z

Session

• Last session: 2026-04-27T22:17:10Z
• Stopped at: Completed 05-04-PLAN.md
• Resume file: .planning/phases/05-mvp-deployment/.continue-here.md