docs(05-04): complete split deployment artifacts plan

- add phase summary for split deployment artifacts
- update state with phase 05 completion context

.planning/STATE.md

@@ -2,8 +2,8 @@
 gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: — Production-ready surfaces
-status: Executing Phase 05
+status: Phase 05 Complete
-last_updated: "2026-04-27T22:15:58Z"
+last_updated: "2026-04-27T22:17:10.233Z"
 progress:
   total_phases: 6
   completed_phases: 3
@@ -18,11 +18,11 @@ progress:
 See: .planning/PROJECT.md (updated 2026-04-02)
 
 **Core value:** Пользователь ведёт диалог с Lambda через любой мессенджер без изменения ядра
-**Current focus:** Phase 05 — mvp-deployment
+**Current focus:** Phase 05 complete — MVP deployment handoff is ready
 
 ## Current Phase
 
-**Phase 05** in progress: MVP deployment hardening
+**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.
 
@@ -38,6 +38,20 @@ Plan `05-02` is complete. Matrix room-local context commands now rely on repaire
 
 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)
@@ -71,6 +85,7 @@ Verified with `MATRIX_AGENT_REGISTRY_PATH='' MATRIX_PLATFORM_BACKEND='' UV_CACHE
 - [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
 
@@ -102,9 +117,10 @@ Verified with `MATRIX_AGENT_REGISTRY_PATH='' MATRIX_PLATFORM_BACKEND='' UV_CACHE
 | 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:15:58Z
+- Last session: 2026-04-27T22:17:10Z
-- Stopped at: Completed 05-02-PLAN.md
+- Stopped at: Completed 05-04-PLAN.md
 - Resume file: .planning/phases/05-mvp-deployment/.continue-here.md

.planning/phases/05-mvp-deployment/05-04-SUMMARY.md

@@ -0,0 +1,93 @@
+---
+phase: 05-mvp-deployment
+plan: 04
+subsystem: infra
+tags: [docker-compose, matrix, deployment, agents, docs]
+requires:
+  - phase: 05-03
+    provides: "Shared /agents attachment contract and path normalization for Matrix runtime"
+provides:
+  - "docker-compose.prod.yml bot-only deployment handoff artifact"
+  - "docker-compose.fullstack.yml internal E2E harness with health-gated platform-agent startup"
+  - "README and deploy architecture docs aligned to the split compose contract"
+affects: [mvp-deployment, operator-handoff, internal-e2e]
+tech-stack:
+  added: [Docker Compose]
+  patterns: [split-compose-by-operational-intent, shared-agents-volume-contract]
+key-files:
+  created: [docker-compose.prod.yml, docker-compose.fullstack.yml]
+  modified: [.env.example, README.md, docs/deploy-architecture.md]
+key-decisions:
+  - "Split Compose artifacts by runtime intent: bot-only prod handoff vs internal full-stack verification."
+  - "Document /agents as the bot-side shared volume root while internal platform-agent keeps /workspace on the same volume."
+patterns-established:
+  - "Production operators use docker-compose.prod.yml and provide an external AGENT_BASE_URL."
+  - "Internal verification uses docker-compose.fullstack.yml with service_healthy gating instead of sleep-based startup."
+requirements-completed: [PH05-05]
+duration: 3 min
+completed: 2026-04-27
+---
+
+# Phase 05 Plan 04: Split deployment artifacts Summary
+
+**Bot-only production compose handoff plus a separate health-gated full-stack harness aligned to the shared `/agents` volume contract**
+
+## Performance
+
+- **Duration:** 3 min
+- **Started:** 2026-04-27T22:12:42Z
+- **Completed:** 2026-04-27T22:16:09Z
+- **Tasks:** 2
+- **Files modified:** 5
+
+## Accomplishments
+- Added `docker-compose.prod.yml` as the operator-facing bot-only runtime artifact.
+- Added `docker-compose.fullstack.yml` for internal E2E runs with `platform-agent` health-gated startup.
+- Updated env and deployment docs so `/agents` and the split compose flow are explicit without relying on the old root compose file.
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Create split prod and fullstack compose artifacts** - `df6d8bf` (feat)
+2. **Task 2: Update deployment docs and operator guidance for the split artifacts** - `22a3a2b` (docs)
+
+**Plan metadata:** pending final docs commit after state updates
+
+## Files Created/Modified
+- `docker-compose.prod.yml` - bot-only deployment handoff with `/agents` volume contract
+- `docker-compose.fullstack.yml` - internal harness extending the bot service and adding health-checked `platform-agent`
+- `.env.example` - Phase 05 runtime variables for prod handoff and internal full-stack defaults
+- `README.md` - operator-facing instructions for choosing the correct compose artifact
+- `docs/deploy-architecture.md` - deployment topology and shared-volume guidance aligned to the split artifacts
+
+## Decisions Made
+- Split deployment packaging by operational intent instead of overloading one compose file for both prod handoff and internal testing.
+- Kept the bot’s absolute shared path rooted at `/agents` in docs and env examples while letting the internal `platform-agent` consume the same named volume at `/workspace`.
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+- The docs verification grep treated `deploy` inside the filename `docs/deploy-architecture.md` as a false positive when root compose was still named explicitly. The fix was to remove the literal root compose filename from deploy-path wording while keeping the deprecation clear.
+
+## User Setup Required
+
+None - no external service configuration required beyond populating `.env` from `.env.example`.
+
+## Next Phase Readiness
+
+- Operators now have a bot-only compose artifact for handoff, and developers have a separate internal E2E harness.
+- Remaining Phase 05 work can rely on the split runtime contract without reinterpreting deployment docs.
+
+## Self-Check: PASSED
+
+- Summary file exists at `.planning/phases/05-mvp-deployment/05-04-SUMMARY.md`
+- Commit `df6d8bf` found in git history
+- Commit `22a3a2b` found in git history
+
+---
+*Phase: 05-mvp-deployment*
+*Completed: 2026-04-27*