feat: validate contact and group search args

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

@@ -1755,19 +1755,19 @@ Implemented and verified in this loop:
 - Treat include flags as accepted no-op on local readonly JID-derived candidates because active/archive state is not available in current source.
 - Do not add write/send/file-download behavior.
 
-- [ ] **Step 1: Write failing contact/group MCP arg tests**
+- [x] **Step 1: Write failing contact/group MCP arg tests**
 
 Extend contact/group tool tests with accepted safe args plus rejected unsupported source/cursor cases.
 
-- [ ] **Step 2: Implement validation helpers**
+- [x] **Step 2: Implement validation helpers**
 
 Add minimal validation to contact and group tool handlers.
 
-- [ ] **Step 3: Update verification and docs**
+- [x] **Step 3: Update verification and docs**
 
 Update `scripts/verify-go-mcp.ps1`, runbook, status card, and this plan.
 
-- [ ] **Step 4: Run full verification and commit**
+- [x] **Step 4: Run full verification and commit**
 
 Run:
 
@@ -1782,6 +1782,67 @@ Expected: all exit 0. Remove any generated root `isphere-mcp.exe` after build. C
 
 ---
 
+## Loop C21 Result
+
+Implemented and verified in this loop:
+
+- `isphere_search_contacts` now accepts safe contract args `cursor`, `source_preference`, and `include_inactive`.
+- `isphere_search_groups` now accepts safe contract args `cursor`, `source_preference`, and `include_archived`.
+- Both tools accept empty/`auto`/`local_readonly` source preference and reject unsupported connector selections until those sources exist.
+- Both tools accept empty cursor and reject non-empty cursor until pagination exists.
+- Include flags are accepted no-ops for the current local-readonly JID-derived source because inactive/archive state is not available.
+- `scripts/verify-go-mcp.ps1` now exercises these contact/group safe args in default and configured source smokes.
+
+---
+
+## Loop C22: File receive remaining contract argument validation
+
+**Goal:** Apply the same safe-argument validation pattern to `isphere_receive_files` list mode, while continuing to reject download mode until cache/download mapping is validated.
+
+**Planned files:**
+- Modify: `internal/tools/isphere_files.go`
+- Modify: `internal/tools/isphere_files_test.go`
+- Modify: `scripts/verify-go-mcp.ps1`
+- Modify: `docs/go-mcp-runbook.md`
+- Modify: `docs/current-status-card.md`
+- Modify: `docs/source-discovery/capability-source-matrix.md`
+- Modify: `docs/superpowers/plans/2026-07-09-stage-c-log-backed-receive-messages-loop.md`
+
+**Planned behavior:**
+- Add/validate safe args: `cursor`, `source_preference`, `preview`, and `output_dir`.
+- Accept `source_preference` empty, `auto`, or `local_readonly`; reject bridge/uia/network until those connectors exist.
+- Accept empty cursor only; reject non-empty cursor until pagination exists.
+- Accept `preview` in list mode as a no-op because list mode is read-only.
+- Accept empty `output_dir` in list mode; reject non-empty `output_dir` unless/until download mode is implemented to avoid implying files were written.
+- Keep mode empty/`list` only; continue rejecting `download`.
+
+- [ ] **Step 1: Write failing file MCP arg tests**
+
+Extend `internal/tools/isphere_files_test.go` with accepted safe args and rejected unsupported source/cursor/output/download cases.
+
+- [ ] **Step 2: Implement file arg validation**
+
+Reuse local-readonly source/cursor validation and add output/download list-mode checks.
+
+- [ ] **Step 3: Update verification and docs**
+
+Update `scripts/verify-go-mcp.ps1`, runbook, status card, matrix, and this plan.
+
+- [ ] **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 C22 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.