docs(05-03): complete shared-volume attachment hardening plan

- add 05-03 summary with task commits and verification details
- update roadmap and state for completed Phase 05 plan 03

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

@@ -0,0 +1,103 @@
+---
+phase: 05-mvp-deployment
+plan: 03
+subsystem: infra
+tags: [matrix, attachments, shared-volume, agents, pytest]
+requires:
+  - phase: 04-matrix-mvp-shared-agent-context-and-context-management-comma
+    provides: direct AgentApi integration and Matrix outgoing file rendering
+provides:
+  - shared-volume attachment path regressions for /agents deployment
+  - relative workspace-path normalization for upstream attachment transport
+  - send-file event normalization for Matrix outbound file rendering
+affects: [matrix, deployment, shared-volume, file-transfer]
+tech-stack:
+  added: []
+  patterns: [relative workspace_path transport, shared-volume root normalization]
+key-files:
+  created: []
+  modified:
+    - tests/adapter/matrix/test_files.py
+    - tests/platform/test_real.py
+    - sdk/real.py
+key-decisions:
+  - "Keep adapter/matrix/files.py as the only path-construction source; sdk/real.py only normalizes attachment references crossing the shared-volume boundary."
+  - "Normalize both /workspace and /agents absolute paths back to relative workspace paths before forwarding to the agent API or rendering Matrix send-file events."
+patterns-established:
+  - "Matrix attachment transport stays relative even when the bot sees absolute shared-volume paths."
+  - "Agent-emitted file paths are rendered back to Matrix without HTTP proxy shims or inline blobs."
+requirements-completed: [PH05-04]
+duration: 3 min
+completed: 2026-04-27
+---
+
+# Phase 05 Plan 03: Shared-volume attachment path hardening Summary
+
+**Room-safe Matrix inbox paths and relative shared-volume attachment normalization for `/agents` deployment**
+
+## Performance
+
+- **Duration:** 3 min
+- **Started:** 2026-04-27T22:02:34Z
+- **Completed:** 2026-04-27T22:05:41Z
+- **Tasks:** 2
+- **Files modified:** 3
+
+## Accomplishments
+- Added regression coverage for room-safe `surfaces/matrix/.../inbox/...` attachment layout under `/agents` workspaces.
+- Added explicit tests for `/workspace/...` and `/agents/...` attachment-path normalization on both upstream send and downstream send-file rendering.
+- Tightened `RealPlatformClient` so only relative `workspace_path` values are forwarded to the agent API.
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Add shared-volume file contract tests for `/agents` deployment** - `cafb0ec` (test)
+2. **Task 2: Tighten attachment path handling for the shared volume contract** - `9a03160` (fix)
+
+## Files Created/Modified
+- `tests/adapter/matrix/test_files.py` - covers room-safe shared-volume inbox paths under an `/agents` workspace root.
+- `tests/platform/test_real.py` - covers relative attachment forwarding and send-file normalization for `/workspace` and `/agents` paths.
+- `sdk/real.py` - normalizes shared-volume roots before attachments cross the upstream or Matrix rendering boundary.
+
+## Decisions Made
+- Kept `adapter/matrix/files.py` unchanged so path construction remains centralized there.
+- Reused one normalization helper in `sdk/real.py` for both `_attachment_paths()` and `_attachment_from_send_file_event()` to keep inbound and outbound behavior aligned.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Adjusted verification to use the project uv environment**
+- **Found during:** Task 2 (Tighten attachment path handling for the shared volume contract)
+- **Issue:** The plan's raw `pytest` command collected with an interpreter missing `PyYAML`, which blocked `tests/adapter/matrix/test_send_outgoing.py` before runtime assertions could execute.
+- **Fix:** Re-ran verification with `UV_CACHE_DIR=/tmp/uv-cache uv run pytest ...`, matching the repo's `CLAUDE.md` guidance and the project `.venv`.
+- **Files modified:** None
+- **Verification:** `UV_CACHE_DIR=/tmp/uv-cache uv run pytest tests/adapter/matrix/test_files.py tests/platform/test_real.py tests/adapter/matrix/test_send_outgoing.py -v`
+- **Committed in:** None (verification-environment adjustment only)
+
+---
+
+**Total deviations:** 1 auto-fixed (1 blocking)
+**Impact on plan:** No scope creep. The deviation only changed the verification entrypoint so the planned test slice could run in the correct environment.
+
+## Issues Encountered
+- The ambient `pytest` resolved to a different virtualenv than the project `.venv`, so direct verification was unreliable for dependency-backed Matrix tests.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Shared-volume file references now stay relative across inbound bot downloads, agent API attachment transport, and outbound Matrix send-file rendering.
+- Phase 05 compose and deployment work can assume the `/agents` contract without adding file proxy infrastructure.
+
+## Self-Check: PASSED
+
+- Found `.planning/phases/05-mvp-deployment/05-03-SUMMARY.md`
+- Verified commit `cafb0ec` exists in git history
+- Verified commit `9a03160` exists in git history
+
+---
+*Phase: 05-mvp-deployment*
+*Completed: 2026-04-27*