admin/isphere-ai-bridge
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: replan core business capabilities

Browse Source
This commit is contained in:
zhaoyilun
2026-07-10 09:22:28 +08:00
parent 5a1b85906b
commit d78152cbfa
3 changed files with 387 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
docs/current-status-card.md
View File

@@ -56,9 +56,9 @@ N13/N14/N15 are pre-business validation results. They can help identify UI eleme
## Current loop ## Current loop
Current loop: `Stage C / Loop C42 - MsgLib receive operator hardening and reconciliation precheck`. Current loop: `Business Roadmap / R1 - Receive-message source reconciliation precheck`.
Plan file: `docs/superpowers/plans/2026-07-09-stage-c-log-backed-receive-messages-loop.md`. Plan file: `docs/superpowers/plans/2026-07-10-core-business-capabilities-roadmap.md`.
Loop rule: Loop rule:
@@ -111,9 +111,13 @@ Current loop output so far:
40. C40: added tool-level explicit receive source selection: empty/`auto`/`local_readonly` still use the primary PacketReader/log-backed source, while `source_preference="msglib_readonly"` uses a configured MsgLib receive source and is rejected when not configured. 40. C40: added tool-level explicit receive source selection: empty/`auto`/`local_readonly` still use the primary PacketReader/log-backed source, while `source_preference="msglib_readonly"` uses a configured MsgLib receive source and is rejected when not configured.
41. C41: wired env-configured MsgLib client into both display enrichment and explicit receive selection; optional copied-DB MCP smoke now proves `source_preference="msglib_readonly"` returns sanitized count/source evidence while standard `verify-go-mcp.ps1` remains deterministic. 41. C41: wired env-configured MsgLib client into both display enrichment and explicit receive selection; optional copied-DB MCP smoke now proves `source_preference="msglib_readonly"` returns sanitized count/source evidence while standard `verify-go-mcp.ps1` remains deterministic.
## Next business mainline ## Recompiled business roadmap
1. Run Stage C Loop C42: harden operator-facing MsgLib receive behavior and start reconciliation precheck between PacketReader and MsgLib rows without changing the default route. The active plan is now organized around the four business goals rather than the old technology-led C-loop:
2. Leave `isphere_send_message` blocked until bridge/API, UIA action-chain, or protocol connector evidence is validated.
3. Leave actual file download/cache mapping as a later connector node until a message-to-cache hash or client download source is validated. 1. Search contacts and search groups: harden result quality, ranking, de-duplication, and richer fields.
2. Receive/send messages: reconcile PacketReader and MsgLib receive sources first; then discover and validate a send-message connector.
3. Receive/send files: map received file metadata to cache/download behavior first; send-file remains behind the send connector plus upload evidence.
4. Keep UIA selector/report work as fallback support, not as the primary roadmap. 4. Keep UIA selector/report work as fallback support, not as the primary roadmap.
Next node: R1 receive-message source reconciliation precheck.

16
docs/source-discovery/capability-source-matrix.md
View File

@@ -1,7 +1,7 @@
# Capability Source Matrix # Capability Source Matrix
Date: 2026-07-10 Date: 2026-07-10
Stage: C log-backed receive implementation Stage: Core business capability roadmap
Evidence index: `docs/source-discovery/2026-07-09-n12-pre-zyl-index.md` Evidence index: `docs/source-discovery/2026-07-09-n12-pre-zyl-index.md`
Schema notes: `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md` Schema notes: `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md`
@@ -17,12 +17,12 @@ Schema notes: `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md`
| MCP tool | Primary source | Fallback source | Evidence file | Decision status | Next implementation slice | | MCP tool | Primary source | Fallback source | Evidence file | Decision status | Next implementation slice |
| --- | --- | --- | --- | --- | --- | | --- | --- | --- | --- | --- | --- |
| `isphere_receive_messages` | decrypted `PacketReader.ProcessPacket` XMPP `<message>` stanzas via `internal/isphere.EncryptedPacketLogSource`; configured by `ISPHERE_PACKET_LOG_FILE` or `ISPHERE_PACKET_LOG_DIR` | copied `MsgLib.db` message tables through x86 read-only sidecar `list_messages` selected explicitly by `source_preference="msglib_readonly"`; decrypted `Smark.SendReceive` transport stanzas; decrypted `SaveToDB` `Chat_OnMessageArrived` traces | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#field-mapping-evidence`; `docs/source-discovery/2026-07-10-dotnet-wrapper-static-analysis.md`; `docs/source-discovery/2026-07-10-db-backed-receive-source-design.md` | C20 supports and validates the current safe receive-message contract args; C32 wires optional MsgLib display metadata into receive-message `sender_name` and `conversation.display_name`; C33 proves this path through a real copied-DB MCP smoke; C35 maps MsgLib message tables; C36 adds metadata-only `message_sources`; C37 defines bounded `list_messages` design; C38 implements sidecar/Go-wrapper `list_messages` with sanitized copied-DB verification; C39 adds a Go adapter from `ListMessages` to the receive-message domain model; C40 adds tool-level explicit `msglib_readonly` source selection; C41 wires env-configured MsgLib receive source and optional copied-DB smoke while `auto` remains PacketReader/log-backed | C42 operator hardening and PacketReader-vs-MsgLib reconciliation precheck | | `isphere_receive_messages` | decrypted `PacketReader.ProcessPacket` XMPP `<message>` stanzas via `internal/isphere.EncryptedPacketLogSource`; configured by `ISPHERE_PACKET_LOG_FILE` or `ISPHERE_PACKET_LOG_DIR` | copied `MsgLib.db` message tables through x86 read-only sidecar `list_messages` selected explicitly by `source_preference="msglib_readonly"`; decrypted `Smark.SendReceive` transport stanzas; decrypted `SaveToDB` `Chat_OnMessageArrived` traces | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#field-mapping-evidence`; `docs/source-discovery/2026-07-10-dotnet-wrapper-static-analysis.md`; `docs/source-discovery/2026-07-10-db-backed-receive-source-design.md` | C20 supports and validates the current safe receive-message contract args; C32 wires optional MsgLib display metadata into receive-message `sender_name` and `conversation.display_name`; C33 proves this path through a real copied-DB MCP smoke; C35 maps MsgLib message tables; C36 adds metadata-only `message_sources`; C37 defines bounded `list_messages` design; C38 implements sidecar/Go-wrapper `list_messages` with sanitized copied-DB verification; C39 adds a Go adapter from `ListMessages` to the receive-message domain model; C40 adds tool-level explicit `msglib_readonly` source selection; C41 wires env-configured MsgLib receive source and optional copied-DB smoke while `auto` remains PacketReader/log-backed | R1 receive-message source reconciliation precheck |
| `isphere_search_contacts` | bare sender/receiver JIDs extracted from normalized log-backed messages loaded from configured PacketReader file or directory source | validated copied `MsgLib.db` tables: `TD_Roster`, `TD_CustomEffigy`, `tblRecent`, `tblChatLevel`, `tblPersonMsg`; decrypted roster/contact stanzas from `Smark.SendReceive`; UIA helper source if display names are still missing | `docs/source-discovery/2026-07-10-msglib-readonly-schema-extraction.md` | C34 documents how to enable optional MsgLib contact display enrichment and verify sanitized MCP output; search enrichment remains available | C37 bounded DB-backed receive-source design | | `isphere_search_contacts` | bare sender/receiver JIDs extracted from normalized log-backed messages loaded from configured PacketReader file or directory source | validated copied `MsgLib.db` tables: `TD_Roster`, `TD_CustomEffigy`, `tblRecent`, `tblChatLevel`, `tblPersonMsg`; decrypted roster/contact stanzas from `Smark.SendReceive`; UIA helper source if display names are still missing | `docs/source-discovery/2026-07-10-msglib-readonly-schema-extraction.md` | C34 documents how to enable optional MsgLib contact display enrichment and verify sanitized MCP output; search enrichment remains available | R2 contact search quality hardening |
| `isphere_search_groups` | decrypted `PacketReader.ProcessPacket` `type="groupchat"` stanzas and conference/MUC JIDs loaded from configured PacketReader file or directory source | validated copied `MsgLib.db` tables: `tblMsgGroupPersonMsg`, `TD_WorkGroupAuth`, `tblRecent`; UIA helper source if group display names are still missing | `docs/source-discovery/2026-07-10-msglib-readonly-schema-extraction.md`; C9 ignored-log scan: PacketReader 86 groupchat/86 conference hits; Smark 24 groupchat/658 conference/631 muc hits | C34 documents how to enable optional MsgLib group display enrichment and verify sanitized MCP output; search enrichment remains available | C37 bounded DB-backed receive-source design | | `isphere_search_groups` | decrypted `PacketReader.ProcessPacket` `type="groupchat"` stanzas and conference/MUC JIDs loaded from configured PacketReader file or directory source | validated copied `MsgLib.db` tables: `tblMsgGroupPersonMsg`, `TD_WorkGroupAuth`, `tblRecent`; UIA helper source if group display names are still missing | `docs/source-discovery/2026-07-10-msglib-readonly-schema-extraction.md`; C9 ignored-log scan: PacketReader 86 groupchat/86 conference hits; Smark 24 groupchat/658 conference/631 muc hits | C34 documents how to enable optional MsgLib group display enrichment and verify sanitized MCP output; search enrichment remains available | R2 group search quality hardening |
| `isphere_receive_files` | decrypted `PacketReader.ProcessPacket` file-transfer message stanzas via `internal/isphere.ListFilesFromMessages` and `isphere_receive_files` list mode; configured PacketReader file or directory source; `zyl\importal\<hash>` cache entries remain unlinked | decrypted `Smark.SendReceive` and `SaveToDB` traces for file-reference reconciliation; future UIA/client connector for download | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#c12-file-transfer-evidence-precheck` | C22 verifies safe file-list contract args; no log-to-cache/download mapping yet | defer download mapping; precheck contact/group display-name evidence | | `isphere_receive_files` | decrypted `PacketReader.ProcessPacket` file-transfer message stanzas via `internal/isphere.ListFilesFromMessages` and `isphere_receive_files` list mode; configured PacketReader file or directory source; `zyl\importal\<hash>` cache entries remain unlinked | decrypted `Smark.SendReceive` and `SaveToDB` traces for file-reference reconciliation; future UIA/client connector for download | `docs/source-discovery/2026-07-09-n12-pre-zyl-schema-notes.md#c12-file-transfer-evidence-precheck` | C22 verifies safe file-list contract args; no log-to-cache/download mapping yet | R3 receive-file download mapping precheck |
| `isphere_send_message` | none validated yet | existing bridge/API/local service preferred; UIA write connector only after internal-sandbox action evidence; network/protocol connector only after protocol discovery | `docs/source-discovery/2026-07-10-send-message-source-precheck.md` | C15 blocked: contract exists, but no committed bridge/API/local service, helper write op, UIA action chain, or protocol connector is validated | do not implement write behavior; harden existing read source configuration | | `isphere_send_message` | none validated yet | existing bridge/API/local service preferred; UIA write connector only after internal-sandbox action evidence; network/protocol connector only after protocol discovery | `docs/source-discovery/2026-07-10-send-message-source-precheck.md` | C15 blocked: contract exists, but no committed bridge/API/local service, helper write op, UIA action chain, or protocol connector is validated | R5 send-message connector discovery |
| `isphere_send_file` | none validated yet | depends on send-message connector plus outbound file/upload evidence | `docs/source-discovery/2026-07-10-send-message-source-precheck.md` | blocked behind `isphere_send_message` connector selection and file upload/source policy | defer until send-message connector is validated | | `isphere_send_file` | none validated yet | depends on send-message connector plus outbound file/upload evidence | `docs/source-discovery/2026-07-10-send-message-source-precheck.md` | blocked behind `isphere_send_message` connector selection and file upload/source policy | R7 send-file connector discovery |
## Stage C entry rule ## Stage C entry rule
@@ -39,4 +39,4 @@ Start Stage C with a narrow log-backed `isphere_receive_messages` source abstrac
## Deferred source work ## Deferred source work
`MsgLib.db` has a validated copied read-only open path through the bundled 32-bit `System.Data.SQLite.dll` and password `123`. C27 adds `MsgLibReadSidecar` as the bounded x86 .NET reader boundary, C28 adds the Go `internal/msglib` process client, C29 adds bounded `display_entities` extraction, C30 wires it as optional contact/group MCP enrichment, C31 proves real copied-DB MCP enrichment with sanitized output, C32 reuses it for receive-message display fields, C33 proves that receive display path through a real copied-DB MCP smoke without printing entity values, C34 documents the operator setup/verification path, C35 maps MsgLib message tables to receive-message contract fields without reading row values, C36 adds metadata-only `message_sources` readiness, C37 defines the bounded DB-backed receive-source design, C38 implements sidecar/Go-wrapper `list_messages` with sanitized verification, C39 adds a Go adapter from MsgLib list results to the receive-message domain model, C40 adds explicit tool-level `msglib_readonly` source selection, and C41 wires env-configured explicit MsgLib receive with optional sanitized smoke. The next step is operator hardening and reconciliation precheck; do not silently merge MsgLib rows into the MCP default. `MsgLib.db` has a validated copied read-only open path through the bundled 32-bit `System.Data.SQLite.dll` and password `123`. C27 adds `MsgLibReadSidecar` as the bounded x86 .NET reader boundary, C28 adds the Go `internal/msglib` process client, C29 adds bounded `display_entities` extraction, C30 wires it as optional contact/group MCP enrichment, C31 proves real copied-DB MCP enrichment with sanitized output, C32 reuses it for receive-message display fields, C33 proves that receive display path through a real copied-DB MCP smoke without printing entity values, C34 documents the operator setup/verification path, C35 maps MsgLib message tables to receive-message contract fields without reading row values, C36 adds metadata-only `message_sources` readiness, C37 defines the bounded DB-backed receive-source design, C38 implements sidecar/Go-wrapper `list_messages` with sanitized verification, C39 adds a Go adapter from MsgLib list results to the receive-message domain model, C40 adds explicit tool-level `msglib_readonly` source selection, and C41 wires env-configured explicit MsgLib receive with optional sanitized smoke. The active roadmap is now `docs/superpowers/plans/2026-07-10-core-business-capabilities-roadmap.md`; next step is R1 receive-source reconciliation.

369
docs/superpowers/plans/2026-07-10-core-business-capabilities-roadmap.md Normal file
View File

@@ -0,0 +1,369 @@
# Core Business Capabilities Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Deliver the four business-facing iSphere MCP goals: search contacts, search groups, receive/send messages, and receive/send files.
**Architecture:** The product API is the Go MCP server. Read-side local evidence sources are PacketReader encrypted logs and copied `MsgLib.db` through the bounded x86 `MsgLibReadSidecar`. Write-side capabilities must use a validated connector before production execution: bridge/API/local service first, then UIA helper, then network/protocol only after discovery.
**Tech Stack:** Go 1.23.4, `github.com/modelcontextprotocol/go-sdk`, PowerShell verification scripts, x86 .NET Framework sidecar for `MsgLib.db`, C# WinHelper for UIA fallback.
## Global Constraints
- Repository root: `E:\coding\codex\isphere-ai-bridge`.
- Remote name: `gitea`; active branch: `main`.
- Code search rule from `AGENTS.md`: use `git ls-files`, `ag`, or `grep -R`; do not use `rg`.
- Do not commit raw DB/log files, decrypted message content, local file paths from copied evidence, or operator credentials.
- Standard deterministic verification must keep MsgLib env cleared unless a script is explicitly named as optional MsgLib verification.
- `auto` for `isphere_receive_messages` remains PacketReader/log-backed until reconciliation is complete; copied DB receive requires `source_preference="msglib_readonly"`.
- Do not implement send-message, file-download, or send-file production behavior until the selected connector has a focused evidence note and passing preview/dry-run tests.
- Each implementation node must end with `git diff --check`, `go test ./...`, `go build ./cmd/isphere-mcp`, and the relevant PowerShell smoke.
---
## Business Goal Status
| Business goal | Current capability | Remaining blockers | Next node |
| --- | --- | --- | --- |
| Search contacts | Registered MCP tool; log/JID candidates; optional copied-DB MsgLib display enrichment. | Result quality hardening: de-duplication, ranking, stable IDs, optional richer fields. | R2 |
| Search groups | Registered MCP tool; groupchat/conference candidates; optional copied-DB MsgLib display enrichment. | Group member count, owner refs, nested/group hierarchy quality. | R2 |
| Receive messages | PacketReader source works; copied `MsgLib.db` explicit receive works with `source_preference="msglib_readonly"`. | Reconciliation between PacketReader and MsgLib, source confidence, pagination policy. | R1 |
| Send messages | Contract exists; no validated write connector. | Need connector discovery, preview-only path, idempotency and audit before production send. | R5 then R6 |
| Receive files | List mode exists from message-derived file metadata. | Need message-to-cache/download mapping and output-dir download behavior. | R3 then R4 |
| Send files | Contract exists; no validated upload/send connector. | Depends on send-message connector plus upload/file-transfer evidence. | R7 then R8 |
## Node Sequence
### R0: Business roadmap rebaseline
**Purpose:** Replace the previous technology-led loop with this four-goal business roadmap.
**Files:**
- Create: `docs/superpowers/plans/2026-07-10-core-business-capabilities-roadmap.md`
- Modify: `docs/current-status-card.md`
- Modify: `docs/source-discovery/capability-source-matrix.md`
**Acceptance gate:**
```powershell
git diff --check
go test ./...
```
**Done when:**
- Current status points to this roadmap.
- The next implementation node is R1.
- No code behavior changes are included in R0.
---
### R1: Receive-message source reconciliation precheck
**Purpose:** Decide how PacketReader messages and MsgLib DB messages relate, without changing default routing.
**Files:**
- Create: `docs/source-discovery/2026-07-10-receive-message-reconciliation-precheck.md`
- Modify: `scripts/verify-msglib-mcp-enrichment.ps1` only if an additional sanitized count/ref is required.
- Modify: this roadmap and `docs/current-status-card.md`.
**Evidence to compare:**
- PacketReader: message id, sender id, receiver/group id, message type, body-present boolean, subject, timestamp.
- MsgLib: `message_id`, `conversation_id`, `conversation_type`, sender/receiver ids, body-present boolean, subject, timestamp, `raw_ref`.
- File metadata: filename/size/download-ref-present boolean only.
**Steps:**
- [ ] **Step 1: Write the precheck note skeleton**
Create `docs/source-discovery/2026-07-10-receive-message-reconciliation-precheck.md` with these headings:
```markdown
# Receive Message Reconciliation Precheck
Date: 2026-07-10
## Goal
Compare PacketReader and MsgLib receive-message sources using sanitized identifiers, counts, source refs, and booleans only.
## Sources
## Candidate match keys
## Known mismatches
## Safe evidence allowed in logs
## Decision for default routing
## Next implementation node
```
- [ ] **Step 2: Fill candidate match keys**
Record these exact candidate keys:
```text
strong: message_id exact match when both sources expose the same id
medium: same conversation id, same sender id, timestamp within a small window
medium: same group id, same sender id, same subject/body-present flag
weak: filename plus nearby timestamp for file-transfer messages
not allowed in committed evidence: message body values, local file paths, raw rows
```
- [ ] **Step 3: Run verification**
```powershell
git diff --check
go test ./...
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1
$env:ISPHERE_MSGLIB_SQLITE_DLL = "<path-to-copied-System.Data.SQLite.dll>"
$env:ISPHERE_MSGLIB_DB = "<path-to-copied-MsgLib.db>"
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-msglib-mcp-enrichment.ps1
```
**Acceptance gate:**
- The note states whether C43 should implement a reconciliation helper, pagination, or file mapping first.
- Default MCP receive still uses PacketReader for empty/`auto`.
**Stop condition:**
- If safe sanitized keys are not enough to compare sources, stop and request either more evidence or permission for a focused local-only diagnostic script.
---
### R2: Contact and group search quality hardening
**Purpose:** Make search results business-usable before relying on them for send targets.
**Files:**
- Modify: `internal/isphere/contacts.go`, `internal/isphere/groups.go`
- Modify tests: `internal/isphere/contacts_test.go`, `internal/isphere/groups_test.go`
- Modify optional display mapping if needed: `internal/tools/display_entities.go`
- Modify docs: `docs/go-mcp-runbook.md`, this roadmap, `docs/current-status-card.md`
**Steps:**
- [ ] **Step 1: Add failing contact ranking test**
Target behavior:
```text
exact display-name/id match ranks before substring match;
duplicates from log and MsgLib collapse into one result;
source remains visible through raw_ref/source.
```
Run:
```powershell
go test ./internal/isphere -run TestSearchContactsRanksExactAndDeduplicates -v
```
Expected before implementation: FAIL because ranking/dedup behavior is not implemented.
- [ ] **Step 2: Implement contact ranking/dedup**
Implement minimal deterministic ranking in `internal/isphere/contacts.go`.
- [ ] **Step 3: Add failing group ranking test**
Run:
```powershell
go test ./internal/isphere -run TestSearchGroupsRanksExactAndDeduplicates -v
```
Expected before implementation: FAIL because ranking/dedup behavior is not implemented.
- [ ] **Step 4: Implement group ranking/dedup**
Implement minimal deterministic ranking in `internal/isphere/groups.go`.
- [ ] **Step 5: Verify**
```powershell
git diff --check
go test ./...
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1
```
**Acceptance gate:**
- Search contacts and search groups produce deterministic ranked results.
- No send behavior is introduced.
---
### R3: Receive-file download mapping precheck
**Purpose:** Determine how file metadata maps to an existing local cache file or a client-triggered download.
**Files:**
- Create: `docs/source-discovery/2026-07-10-file-download-mapping-precheck.md`
- Modify: `docs/source-discovery/capability-source-matrix.md`
- Modify: this roadmap and `docs/current-status-card.md`
**Evidence to inspect:**
- PacketReader file-transfer stanza fields.
- MsgLib `TD_ReceiveFileRecord` safe metadata: message id ref, filename, size, source id, send time.
- Existing ignored `importal`/cache directory names only as sanitized path-shape evidence.
**Acceptance gate:**
- The note chooses one next node:
1. cache-file resolver,
2. UI/client download connector,
3. additional evidence request.
- No file content or local file path values are committed.
---
### R4: Receive-file download implementation
**Purpose:** Implement `isphere_receive_files` download mode only after R3 identifies a validated mapping.
**Files:**
- Modify: `internal/isphere/file_source.go`, `internal/isphere/files.go`
- Modify tests: `internal/isphere/file_source_test.go`, `internal/isphere/files_test.go`
- Modify tool: `internal/tools/isphere_files.go`, `internal/tools/isphere_files_test.go`
- Modify verification: `scripts/verify-go-mcp.ps1`
**Execution policy:**
- Preview remains the default for download.
- Production download requires `output_dir`.
- Saved path must be under the requested output directory.
- Response includes `sha256` and `saved_path`; audit includes `file_sha256`.
**Acceptance gate:**
```powershell
git diff --check
go test ./...
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1
```
**Stop condition:**
- If no validated mapping exists, do not implement download mode.
---
### R5: Send-message connector discovery
**Purpose:** Select the first safe write connector for sending text messages.
**Files:**
- Create: `docs/source-discovery/2026-07-10-send-message-connector-selection.md`
- Modify: `docs/source-discovery/capability-source-matrix.md`
- Modify: this roadmap and `docs/current-status-card.md`
**Connector priority:**
1. Existing bridge/API/local service.
2. UIA helper action chain in a logged-in internal sandbox.
3. Network/protocol connector after protocol discovery.
**Required evidence per connector candidate:**
- How to resolve a target contact/group id.
- How to preview the target and content.
- How to execute exactly once.
- How to confirm success.
- What failure states look like.
**Acceptance gate:**
- One connector is selected for R6, or send remains blocked with an exact evidence request.
**Stop condition:**
- Do not implement a production sender without connector evidence.
---
### R6: Send-message preview and production path
**Purpose:** Implement `isphere_send_message` after R5 validates a connector.
**Files:**
- Create or modify: `internal/tools/isphere_send_message.go`
- Create or modify tests: `internal/tools/isphere_send_message_test.go`
- Modify: `internal/mcpserver/server.go`, `internal/mcpserver/server_test.go`
- Modify: `scripts/verify-go-mcp.ps1`
- Modify docs: `docs/go-mcp-runbook.md`, this roadmap, `docs/current-status-card.md`
**Execution policy:**
- `execution_mode="preview"` returns `send_status="planned"` and does not send.
- `execution_mode="production"` requires `idempotency_key`.
- Audit includes `content_sha256`, target ref, execution mode, and result.
**Acceptance gate:**
- Preview test passes with no connector side effects.
- Production test passes only against a fake or validated sandbox connector.
- No production send is exposed unless connector evidence is complete.
---
### R7: Send-file connector discovery
**Purpose:** Determine whether file sending can reuse the send-message connector or needs a separate upload/file-transfer path.
**Files:**
- Create: `docs/source-discovery/2026-07-10-send-file-connector-selection.md`
- Modify: this roadmap and `docs/current-status-card.md`
**Required evidence:**
- File selection/upload entry point.
- Size/type limits.
- Target resolution.
- Preview metadata.
- Success confirmation.
**Acceptance gate:**
- One connector path is selected for R8, or send-file remains blocked behind an exact evidence request.
---
### R8: Send-file preview and production path
**Purpose:** Implement `isphere_send_file` after R7 validates the connector.
**Files:**
- Create or modify: `internal/tools/isphere_send_file.go`
- Create or modify tests: `internal/tools/isphere_send_file_test.go`
- Modify: `internal/mcpserver/server.go`, `internal/mcpserver/server_test.go`
- Modify verification and docs.
**Execution policy:**
- Preview computes `file_sha256`, `file_size_bytes`, target display, and `send_status="planned"`.
- Production requires `idempotency_key` and a validated connector.
- File path must be inside an allowed outbound directory.
**Acceptance gate:**
- Preview and fake/sandbox production tests pass.
- No arbitrary local file exfiltration behavior is introduced.
---
### R9: End-to-end digital employee acceptance
**Purpose:** Prove the four business goals together in one operator scenario.
**Scenario:**
1. Search contact.
2. Search group.
3. Receive recent messages.
4. List/download a received file if download is available.
5. Preview sending a message.
6. Preview sending a file if send-file is available.
**Acceptance gate:**
```powershell
git diff --check
go test ./...
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\verify-go-mcp.ps1
```
Optional sandbox verification may be added only when the connector evidence is validated.
---
## Self-Review
- Spec coverage: all four user goals are represented: search contacts, search groups, receive/send messages, and receive/send files.
- Placeholder scan: no node uses placeholder markers; blocked work has exact evidence requests and stop conditions.
- Type consistency: current implemented tool names match `docs/mcp-core-tools-contract.md`: `isphere_search_contacts`, `isphere_search_groups`, `isphere_receive_messages`, `isphere_receive_files`, `isphere_send_message`, and `isphere_send_file`.