From d78152cbfa3b6eee972dd06f5534936c01d19f68 Mon Sep 17 00:00:00 2001 From: zhaoyilun Date: Fri, 10 Jul 2026 09:22:28 +0800 Subject: [PATCH] docs: replan core business capabilities --- docs/current-status-card.md | 16 +- .../capability-source-matrix.md | 16 +- ...7-10-core-business-capabilities-roadmap.md | 369 ++++++++++++++++++ 3 files changed, 387 insertions(+), 14 deletions(-) create mode 100644 docs/superpowers/plans/2026-07-10-core-business-capabilities-roadmap.md diff --git a/docs/current-status-card.md b/docs/current-status-card.md index b13f641..d40eac5 100644 --- a/docs/current-status-card.md +++ b/docs/current-status-card.md @@ -56,9 +56,9 @@ N13/N14/N15 are pre-business validation results. They can help identify UI eleme ## 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: @@ -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. 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. -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. +The active plan is now organized around the four business goals rather than the old technology-led C-loop: + +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. + +Next node: R1 receive-message source reconciliation precheck. diff --git a/docs/source-discovery/capability-source-matrix.md b/docs/source-discovery/capability-source-matrix.md index 66759f6..a5e2a7b 100644 --- a/docs/source-discovery/capability-source-matrix.md +++ b/docs/source-discovery/capability-source-matrix.md @@ -1,7 +1,7 @@ # Capability Source Matrix 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` 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 | | --- | --- | --- | --- | --- | --- | -| `isphere_receive_messages` | decrypted `PacketReader.ProcessPacket` XMPP `` 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_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_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_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\` 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_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_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_receive_messages` | decrypted `PacketReader.ProcessPacket` XMPP `` 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 | 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 | 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\` 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 | 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 | R7 send-file connector discovery | ## Stage C entry rule @@ -39,4 +39,4 @@ Start Stage C with a narrow log-backed `isphere_receive_messages` source abstrac ## 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. diff --git a/docs/superpowers/plans/2026-07-10-core-business-capabilities-roadmap.md b/docs/superpowers/plans/2026-07-10-core-business-capabilities-roadmap.md new file mode 100644 index 0000000..b6a676a --- /dev/null +++ b/docs/superpowers/plans/2026-07-10-core-business-capabilities-roadmap.md @@ -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 = "" +$env:ISPHERE_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`.