feat: register isphere group search tool

docs/current-status-card.md

@@ -14,21 +14,22 @@ Remote base before local roadmap commits: `b2d839e Merge branch 'codex/n15-repor
 ## Current completed state
 
 - Go MCP foundation exists: `cmd/isphere-mcp`, `internal/mcpserver`, `internal/helperclient`, and `internal/tools` build a stdio MCP server.
-- The current MCP surface exposes six read-oriented tools:
+- The current MCP surface exposes seven read-oriented tools:
   - `win_helper_version`
   - `win_helper_self_check`
   - `win_helper_scan_windows`
   - `win_helper_dump_uia`
   - `isphere_receive_messages`
   - `isphere_search_contacts`
+  - `isphere_search_groups`
 - C# `ISphereWinHelper` exists under `native/ISphereWinHelper` and uses the `isphere.helper.v1` stdin/stdout JSON contract.
-- `scripts/verify-win-helper.ps1` and `scripts/verify-go-mcp.ps1` provide repeatable local checks for the helper, six-tool MCP surface, default empty-source receive/contact calls, and synthetic configured-source receive/contact smoke.
+- `scripts/verify-win-helper.ps1` and `scripts/verify-go-mcp.ps1` provide repeatable local checks for the helper, seven-tool MCP surface, default empty-source receive/contact/group calls, and synthetic configured-source receive/contact/group smoke.
 - N12-pre and N12R documents define safe offline evidence intake and internal-sandbox live UIA capture procedures.
 - N13/N14/N15 produced selector catalog/report validation infrastructure, but those are supporting validation assets only.
 
 ## What cannot be claimed externally
 
-- The project has not yet implemented business MCP tools for group search, message sending, file receiving, or file sending; `isphere_receive_messages` and `isphere_search_contacts` have operator-local encrypted log-file support but not a production ingestion path.
+- The project has not yet implemented business MCP tools for message sending, file receiving, or file sending; `isphere_receive_messages`, `isphere_search_contacts`, and `isphere_search_groups` have operator-local encrypted log-file support but not a production ingestion path.
 - The project has not completed production iSphere integration.
 - The project has not proven a stable real message source for the full business workflow beyond decrypted PacketReader log evidence and synthetic/redacted tests.
 - The project has not implemented real message sending or real file upload.
@@ -41,7 +42,7 @@ Remote base before local roadmap commits: `b2d839e Merge branch 'codex/n15-repor
 - The helper protocol boundary is explicit and keeps Windows/UIA work separate from the Go MCP service layer.
 - The current code can support future MCP business tools by routing low-level Windows/UIA fallback work through a bounded helper layer.
 - The project has repeatable verification scripts for the helper/MCP foundation and the current five-tool surface.
-- The project now has a corrected business contract and plan for core MCP communication tools, plus registered receive/contact read tools that can use `ISPHERE_PACKET_LOG_FILE` for operator-local encrypted PacketReader log lines.
+- The project now has a corrected business contract and plan for core MCP communication tools, plus registered receive/contact/group read tools that can use `ISPHERE_PACKET_LOG_FILE` for operator-local encrypted PacketReader log lines.
 
 ## N13/N14/N15 positioning
 
@@ -49,7 +50,7 @@ N13/N14/N15 are pre-business validation results. They can help identify UI eleme
 
 ## Current loop
 
-Current loop: `Stage C / Loop C10 - log-backed group candidate extraction`.
+Current loop: `Stage C / Loop C12 - file receive source evidence precheck`.
 
 Plan file: `docs/superpowers/plans/2026-07-09-stage-c-log-backed-receive-messages-loop.md`.
 
@@ -71,11 +72,12 @@ Current loop output so far:
 7. C7: log-backed contact candidate extraction from sender/receiver JIDs.
 8. C8: `isphere_search_contacts` MCP registration and six-tool verification.
 9. C9: group source evidence precheck confirmed groupchat/conference/MUC hits in ignored decrypted logs.
+10. C10: log-backed group candidate extraction from groupchat/conference JIDs.
+11. C11: `isphere_search_groups` MCP registration and seven-tool verification.
 
 ## Next business mainline
 
-1. Implement Stage C Loop C10: extract group candidates from log-backed groupchat/conference JIDs.
-2. Register `isphere_search_groups` after group source tests pass.
-3. Add file read tools after their source decisions are recorded.
-4. Add `isphere_send_message` and `isphere_send_file` after source discovery and connector selection.
-5. Keep UIA selector/report work as fallback support, not as the primary roadmap.
+1. Run Stage C Loop C12: verify current evidence for `isphere_receive_files` before implementation.
+2. Implement file metadata extraction only after file-transfer/cache evidence is recorded.
+3. Add `isphere_send_message` and `isphere_send_file` after source discovery and connector selection.
+4. Keep UIA selector/report work as fallback support, not as the primary roadmap.

docs/go-mcp-runbook.md

@@ -90,11 +90,12 @@ The verification confirms:
 - C# helper can be built.
 - Go MCP binary can be built.
 - MCP initialize/list/call flow works through the SDK harness.
-- Exactly six tools are exposed: four WinHelper observation tools plus `isphere_receive_messages` and `isphere_search_contacts`.
+- Exactly seven tools are exposed: four WinHelper observation tools plus `isphere_receive_messages`, `isphere_search_contacts`, and `isphere_search_groups`.
 - `win_helper_version` returns `ISphereWinHelper`.
 - `isphere_receive_messages` is callable and returns an empty `messages` array from the default empty source.
 - A synthetic configured-source smoke check proves `ISPHERE_PACKET_LOG_FILE` can drive `isphere_receive_messages` end-to-end with one redacted fixture message.
 - `isphere_search_contacts` is callable and returns JID-derived contact candidates from the same configured synthetic message fixture.
+- `isphere_search_groups` is callable and returns JID-derived group candidates from the configured synthetic groupchat fixture.
 - Verification uses synthetic/local helper checks and does not load raw N12-pre evidence.
 - Contact/group/file/search/send business tools remain later-stage work.
 
@@ -153,7 +154,7 @@ E:\coding\codex\isphere-ai-bridge\isphere-mcp.exe
 
 ## 8. Allowed tools
 
-These six tools are currently allowed:
+These seven tools are currently allowed:
 
 | Tool | Source/op | Purpose |
 | --- | --- | --- |
@@ -163,6 +164,7 @@ These six tools are currently allowed:
 | `win_helper_dump_uia` | helper `dump_uia` | Read a UI Automation tree for a specified window handle. |
 | `isphere_receive_messages` | log-backed `EncryptedPacketLogSource` | Read normalized messages from the configured PacketReader log source. The default server source is empty until a loader is wired. |
 | `isphere_search_contacts` | log-backed message JIDs | Search contact candidates extracted from sender/receiver bare JIDs in the configured message source. |
+| `isphere_search_groups` | log-backed groupchat JIDs | Search group candidates extracted from groupchat/conference/MUC bare JIDs in the configured message source. |
 
 Allowed parameters:
 
@@ -172,10 +174,11 @@ Allowed parameters:
 - `win_helper_dump_uia`: `hwnd`, `max_depth`, `include_text`, `max_children` only.
 - `isphere_receive_messages`: `limit` only.
 - `isphere_search_contacts`: `query`, `limit` only.
+- `isphere_search_groups`: `query`, `limit` only.
 
 ## 9. Current tool surface and next-stage route
 
-The current runbook verifies six tools:
+The current runbook verifies seven tools:
 
 - `win_helper_version`
 - `win_helper_self_check`

docs/source-discovery/capability-source-matrix.md

@@ -19,7 +19,7 @@ Schema notes: `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md`
 | --- | --- | --- | --- | --- | --- |
 | `isphere_receive_messages` | decrypted `PacketReader.ProcessPacket` XMPP `<message>` stanzas via `internal/isphere.EncryptedPacketLogSource` | decrypted `Smark.SendReceive` transport stanzas; decrypted `SaveToDB` `Chat_OnMessageArrived` traces; wrapped `MsgLib.db` after DB wrapper is solved | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#field-mapping-evidence` | C5 env loader wired through ISPHERE_PACKET_LOG_FILE; default source remains empty when unset | fixture-backed configured-source operator smoke |
 | `isphere_search_contacts` | bare sender/receiver JIDs extracted from normalized log-backed messages | decrypted roster/contact stanzas from `Smark.SendReceive`; `MsgLib.db` contact/conversation tables after DB wrapper is solved; UIA helper source if display names are missing | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#log-decryption-result` | C8 MCP tool registered and verify-go-mcp covers default/configured contact smoke; JID-only display/account fallback | enrich display names from roster/db/uia evidence |
-| `isphere_search_groups` | decrypted `PacketReader.ProcessPacket` `type="groupchat"` stanzas and conference/MUC JIDs | `MsgLib.db` group/conversation tables after DB wrapper is solved; UIA helper source if group display names are missing | C9 ignored-log scan: PacketReader 86 groupchat/86 conference hits; Smark 24 groupchat/658 conference/631 muc hits | C10 source extraction unit-verified with JID-only display fallback | register MCP tool from C10 source |
+| `isphere_search_groups` | decrypted `PacketReader.ProcessPacket` `type="groupchat"` stanzas and conference/MUC JIDs | `MsgLib.db` group/conversation tables after DB wrapper is solved; UIA helper source if group display names are missing | C9 ignored-log scan: PacketReader 86 groupchat/86 conference hits; Smark 24 groupchat/658 conference/631 muc hits | C11 MCP tool registered and verify-go-mcp covers default/configured group smoke; JID-only display fallback | enrich group display/member data from roster/db/uia evidence |
 | `isphere_receive_files` | decrypted `PacketReader.ProcessPacket` file-transfer message stanzas plus `zyl\importal\<hash>` cache mapping | decrypted `Smark.SendReceive` and `SaveToDB` traces for file-reference reconciliation | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#field-mapping-evidence` | candidate pending cache-reference mapping | fourth |
 
 ## Stage C entry rule

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

@@ -1164,7 +1164,7 @@ Implemented and verified in this loop:
 - Output shape: `ok`, `groups`, `next_cursor`, `audit` minimal fields aligned with `docs/mcp-core-tools-contract.md`.
 - Default empty source returns `ok: true`, `groups: []`.
 
-- [ ] **Step 1: Write failing tool test**
+- [x] **Step 1: Write failing tool test**
 
 Create `internal/tools/isphere_groups_test.go` and run:
 
@@ -1174,15 +1174,15 @@ go test ./internal/tools -run TestISphereSearchGroupsToolReturnsJIDGroups -v
 
 Expected initial failure: group tool registration does not exist.
 
-- [ ] **Step 2: Implement group tool registration**
+- [x] **Step 2: Implement group tool registration**
 
 Register `isphere_search_groups` with source injection for tests. Use C10 source behavior and return a contract-shaped map with minimal audit metadata.
 
-- [ ] **Step 3: Wire server and verification**
+- [x] **Step 3: Wire server and verification**
 
 Register group search in server construction. Update server tool-count tests and `scripts/verify-go-mcp.ps1` to expect seven tools and call `isphere_search_groups` against default empty source and synthetic configured groupchat fixture.
 
-- [ ] **Step 4: Run full verification and commit**
+- [x] **Step 4: Run full verification and commit**
 
 Run:
 
@@ -1197,6 +1197,54 @@ Expected: all exit 0. Remove any generated root `isphere-mcp.exe` after build. C
 
 ---
 
+## Loop C11 Result
+
+Implemented and verified in this loop:
+
+- `internal/tools.RegisterISphereGroupTools(server, source)` registers `isphere_search_groups` over the same receive-message source used by receive/contact tools.
+- `internal/mcpserver.NewServerWithReceiveSource` now exposes seven tools: four WinHelper tools, `isphere_receive_messages`, `isphere_search_contacts`, and `isphere_search_groups`.
+- `scripts/verify-go-mcp.ps1` now expects seven tools, verifies default empty group results, and verifies configured synthetic groupchat extraction.
+- `isphere_search_groups` currently returns JID-derived `local_readonly` groups with unknown member/owner fields and minimal audit metadata.
+- Verification completed for C11 with affected package tests and `powershell -NoProfile -ExecutionPolicy Bypass -File scripts/verify-go-mcp.ps1`; full verification is run again before commit.
+
+---
+
+## Loop C12: File receive source evidence precheck
+
+**Goal:** Before implementing `isphere_receive_files`, verify whether current decrypted PacketReader/Smark/SaveToDB evidence and extracted cache paths contain enough file-transfer metadata to support a real read-only file listing/download-reference source.
+
+**Planned files:**
+- Modify: `docs/source-discovery/capability-source-matrix.md`
+- Modify: `docs/superpowers/plans/2026-07-09-stage-c-log-backed-receive-messages-loop.md`
+- Optionally create ignored metadata under `runs/`; do not commit raw evidence.
+
+**Planned behavior:**
+- Inspect committed schema notes and ignored N12-pre metadata/log summaries for file-transfer subjects, file names, cache/hash paths, download refs, or attachment-like fields.
+- If evidence exists, write C13 around file metadata extraction from normalized messages/cache references.
+- If evidence is insufficient, mark `isphere_receive_files` blocked on additional file-transfer/cache mapping evidence and move to source hardening/docs instead.
+
+- [ ] **Step 1: Inspect current source evidence for file-transfer identifiers**
+
+Use committed schema notes and ignored summaries/log scans. Do not commit raw logs or decrypted content.
+
+- [ ] **Step 2: Update matrix and next loop**
+
+Record whether file receive implementation can proceed from current evidence. Rewrite C13 accordingly.
+
+- [ ] **Step 3: Verify docs-only change and commit**
+
+Run:
+
+```powershell
+git diff --check
+go test ./...
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/verify-go-mcp.ps1
+```
+
+Expected: all exit 0. Commit exact C12 paths only.
+
+---
+
 ## 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.