docs(04-03): add execution summary

- record containerization decisions and verification
- document scoped deviation for uv runtime install

.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-03-SUMMARY.md

@@ -0,0 +1,106 @@
+---
+phase: 04-matrix-mvp-shared-agent-context-and-context-management-comma
+plan: 03
+subsystem: infra
+tags: [docker, docker-compose, matrix, uv, lambda-agent-api]
+requires:
+  - phase: 04-01
+    provides: Matrix MVP runtime and environment model
+provides:
+  - Matrix bot Docker image definition
+  - Single-service docker-compose setup for matrix-bot
+  - Env template entries for Agent API base URLs and real backend selection
+affects: [deployment, matrix, local-dev]
+tech-stack:
+  added: [Dockerfile, docker-compose]
+  patterns: [uv-managed container install with system Python runtime, local path install for lambda_agent_api]
+key-files:
+  created: [Dockerfile, docker-compose.yml]
+  modified: [.env.example]
+key-decisions:
+  - "Kept compose scoped to matrix-bot only; platform-agent remains external to this stack."
+  - "Set UV_PROJECT_ENVIRONMENT=/usr/local so uv-installed dependencies are available to CMD [\"python\", \"-m\", \"adapter.matrix.bot\"]."
+patterns-established:
+  - "Install project dependencies with uv inside the container, then install lambda_agent_api from external/platform-agent_api via pip --ignore-requires-python."
+requirements-completed: [Dockerfile for Matrix bot, docker-compose.yml with matrix-bot service, .env.example updated with AGENT_BASE_URL and MATRIX_PLATFORM_BACKEND]
+duration: 6min
+completed: 2026-04-17
+---
+
+# Phase 4 Plan 03: Matrix Bot Containerization Summary
+
+**Python 3.11 Matrix bot container with uv-managed app dependencies, local lambda_agent_api install bypass, and a single-service compose entrypoint**
+
+## Performance
+
+- **Duration:** 6 min
+- **Started:** 2026-04-17T13:01:00Z
+- **Completed:** 2026-04-17T13:07:04Z
+- **Tasks:** 1
+- **Files modified:** 4
+
+## Accomplishments
+
+- Added a root `Dockerfile` for the Matrix bot using `python:3.11-slim`.
+- Added `docker-compose.yml` with a single `matrix-bot` service using `env_file: .env`.
+- Extended `.env.example` with `AGENT_WS_URL`, `AGENT_BASE_URL`, and `MATRIX_PLATFORM_BACKEND=real`.
+
+## Files Created/Modified
+
+- `Dockerfile` - Builds the Matrix bot image, installs project dependencies with `uv`, and installs `lambda_agent_api` from the local `external/` tree.
+- `docker-compose.yml` - Defines the `matrix-bot` service with restart policy and `.env` loading.
+- `.env.example` - Documents the agent WebSocket URL, agent HTTP base URL, and real backend selector.
+
+## Decisions Made
+
+- Kept the compose scope limited to the Matrix bot, matching the phase boundary and excluding platform services.
+- Added `UV_PROJECT_ENVIRONMENT=/usr/local` as a correctness fix so `uv sync` installs are visible to the final `python` runtime.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 2 - Missing Critical] Ensured uv installs are available to the container runtime**
+- **Found during:** Task 1 (Create Dockerfile and docker-compose.yml)
+- **Issue:** The plan sketch used `uv sync` plus `CMD ["python", ...]`; by default, `uv sync` would install into a virtual environment that system `python` would not use.
+- **Fix:** Set `UV_PROJECT_ENVIRONMENT=/usr/local` in the Dockerfile before running `uv sync`.
+- **Files modified:** `Dockerfile`
+- **Verification:** Required grep checks passed and the generated compose config remained valid.
+
+---
+
+**Total deviations:** 1 auto-fixed (1 missing critical)
+**Impact on plan:** Narrow correctness fix only. No scope expansion.
+
+## Issues Encountered
+
+- `docker compose config` resolved values from the local `.env`, so verification was kept to config rendering and grep-style checks rather than a full image build.
+
+## User Setup Required
+
+- Create `.env` from `.env.example` with real Matrix and agent values before running `docker compose up`.
+
+## Next Phase Readiness
+
+- Matrix bot container packaging is in place and ready for operator-supplied secrets plus an external platform-agent deployment.
+- No code changes were made outside the allowed containerization files.
+
+## Verification
+
+- `grep 'python:3.11-slim' Dockerfile`
+- `grep 'ignore-requires-python' Dockerfile`
+- `grep 'PYTHONPATH=/app' Dockerfile`
+- `grep 'adapter.matrix.bot' Dockerfile`
+- `grep 'matrix-bot' docker-compose.yml`
+- `grep 'env_file' docker-compose.yml`
+- `grep 'AGENT_BASE_URL' .env.example`
+- `grep 'AGENT_WS_URL' .env.example`
+- `grep 'MATRIX_PLATFORM_BACKEND' .env.example`
+- `docker compose -f docker-compose.yml config`
+
+## Self-Check: PASSED
+
+- Found `Dockerfile`
+- Found `docker-compose.yml`
+- Found updated `.env.example`
+- Found `.planning/phases/04-matrix-mvp-shared-agent-context-and-context-management-comma/04-03-SUMMARY.md`