From 380961d6e92c5d14fc82f6ec1fbf2eee7d269cab Mon Sep 17 00:00:00 2001 From: Mikhail Putilovskij Date: Tue, 28 Apr 2026 01:18:47 +0300 Subject: [PATCH] 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 | 28 ++++-- .../phases/05-mvp-deployment/05-04-SUMMARY.md | 93 +++++++++++++++++++ 2 files changed, 115 insertions(+), 6 deletions(-) create mode 100644 .planning/phases/05-mvp-deployment/05-04-SUMMARY.md diff --git a/.planning/STATE.md b/.planning/STATE.md index 2d48990..818b085 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -2,8 +2,8 @@ gsd_state_version: 1.0 milestone: v1.0 milestone_name: — Production-ready surfaces -status: Executing Phase 05 -last_updated: "2026-04-27T22:15:58Z" +status: Phase 05 Complete +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 -- Stopped at: Completed 05-02-PLAN.md +- Last session: 2026-04-27T22:17:10Z +- Stopped at: Completed 05-04-PLAN.md - Resume file: .planning/phases/05-mvp-deployment/.continue-here.md diff --git a/.planning/phases/05-mvp-deployment/05-04-SUMMARY.md b/.planning/phases/05-mvp-deployment/05-04-SUMMARY.md new file mode 100644 index 0000000..68a62c6 --- /dev/null +++ b/.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*