feat: align receive messages response contract

docs/superpowers/plans/2026-07-09-stage-c-log-backed-receive-messages-loop.md

@@ -1517,15 +1517,15 @@ Implemented and verified in this loop:
 - Do not change send-message or send-file behavior in this loop.
 - If output-shape changes are backward-compatible and small, implement them with tests; if they are breaking or broad, document the compatibility decision and write the next implementation loop.
 
-- [ ] **Step 1: Run contract/output precheck**
+- [x] **Step 1: Run contract/output precheck**
 
 Inspect current tool registration code and tests, then record exact gaps against `docs/mcp-core-tools-contract.md`.
 
-- [ ] **Step 2: Choose one small fix or defer**
+- [x] **Step 2: Choose one small fix or defer**
 
 If a small non-breaking fix is available, write the failing test first. Otherwise update docs with the contract gap and rewrite C18 as the implementation node.
 
-- [ ] **Step 3: Verify and commit**
+- [x] **Step 3: Verify and commit**
 
 Run:
 
@@ -1540,6 +1540,66 @@ Expected: all exit 0. Remove any generated root `isphere-mcp.exe` after build. C
 
 ---
 
+## Loop C17 Result
+
+Implemented and verified in this loop:
+
+- `isphere_receive_messages` now returns a contract-shaped top-level object with `ok`, `conversation`, `messages`, `next_cursor`, and `audit`.
+- Each returned message now includes contract-facing fields: `message_id`, `sender_name`, `content_type`, `content_text`, `attachments`, `created_at`, `received_at`, `source`, and `raw_ref`.
+- The implementation keeps the legacy parser-native fields (`id`, `conversation_id`, `conversation_type`, `receiver_id`, `text`, `timestamp`, `subject`, `receipt_id`, `read`) to avoid breaking current tests/scripts and operator consumers.
+- File-transfer messages now expose attachment metadata derived from the same log-backed file-candidate extraction used by `isphere_receive_files`; download refs remain null until cache/download mapping is validated.
+- `scripts/verify-go-mcp.ps1` now asserts the receive-message contract fields for configured file and configured directory source smoke tests.
+
+---
+
+## Loop C18: Receive-message query/filter contract slice
+
+**Goal:** Add the first safe query/filter slice for `isphere_receive_messages` so a digital employee can read a specific conversation or keyword match from the configured local readonly source instead of only using `limit`.
+
+**Planned files:**
+- Modify: `internal/isphere/source.go`
+- Modify: `internal/isphere/source_test.go`
+- Modify: `internal/tools/isphere_read.go`
+- Modify: `internal/tools/isphere_read_test.go`
+- Modify: `scripts/verify-go-mcp.ps1`
+- Modify: `docs/go-mcp-runbook.md`
+- Modify: `docs/current-status-card.md`
+- Modify: `docs/superpowers/plans/2026-07-09-stage-c-log-backed-receive-messages-loop.md`
+
+**Planned behavior:**
+- Extend `ReceiveMessagesQuery` and `ReceiveMessagesArgs` with `conversation_id` and `query` first; keep `since`, `cursor`, and `source_preference` deferred unless a small test proves they are safe.
+- Filter normalized messages by exact `conversation_id` when supplied.
+- Filter by case-insensitive keyword match over message text, subject, sender id, receiver id, and conversation id when `query` is supplied.
+- Preserve current empty-source behavior and current `limit` behavior.
+- Do not add write/send/file-download behavior.
+
+- [ ] **Step 1: Write failing source/query test**
+
+Extend `internal/isphere/source_test.go` with redacted fixtures proving `conversation_id` and keyword filtering.
+
+- [ ] **Step 2: Implement source query filtering**
+
+Apply filters after decrypt/parse/normalize and before limit truncation, keeping deterministic source order.
+
+- [ ] **Step 3: Wire MCP args and verification**
+
+Expose `conversation_id` and `query` on `isphere_receive_messages`, update tool tests and `verify-go-mcp.ps1` synthetic smoke.
+
+- [ ] **Step 4: Run full verification and commit**
+
+Run:
+
+```powershell
+git diff --check
+go test ./...
+go build ./cmd/isphere-mcp
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/verify-go-mcp.ps1
+```
+
+Expected: all exit 0. Remove any generated root `isphere-mcp.exe` after build. Commit exact C18 paths only and rewrite the next loop from actual results.
+
+---
+
 ## Self-Review
 
 - Spec coverage: the plan follows the user's cyclic requirement: plan first, implement one loop at a time, update the next loop after each result, and ask only on blockers.