# 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; deterministic exact-match ranking and case-insensitive de-duplication across log/JID candidates and optional copied-DB MsgLib display enrichment. | Optional richer fields such as department/title remain future enrichment, not a core search blocker. | complete for core search; optional enrichment later | | Search groups | Registered MCP tool; deterministic exact-match ranking and case-insensitive de-duplication across groupchat/conference candidates and optional copied-DB MsgLib display enrichment. | Optional member count, owner refs, and nested/group hierarchy remain future enrichment, not a core search blocker. | complete for core search; optional enrichment later | | Receive messages | PacketReader source works; copied `MsgLib.db` explicit receive works with `source_preference="msglib_readonly"`; R1 precheck says default should remain PacketReader until a future reconciliation helper is implemented. | Future reconciliation helper, source confidence scoring, pagination policy. | future receive helper after R2/R3 | | Send messages | `isphere_send_message` preview/dry-run is registered; R6a confirms B-route entrypoint metadata and A-route UIA/offline-state classifier support. | Need dynamic observation and one approved sandbox send before production. | next R6c online sandbox-send evidence gate | | Receive files | List mode exists from message-derived file metadata; R3/R3b confirm DB file metadata exists but current cache/archive evidence does not map to local files. | R4 download is blocked until better cache evidence or a UI/client download connector is available. | blocked; continue R5 | | Send files | Contract exists; R6a/C31 metadata confirms file-upload/offline-file/file-message candidates and A-route file menu classifier support. | Blocked behind send-message sandbox evidence plus upload/file-transfer dry-run. | wait for R6c, then file-send upload preflight | ## 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:** - [x] **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 ``` - [x] **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 ``` - [x] **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. **R1 Result:** - Created `docs/source-discovery/2026-07-10-receive-message-reconciliation-precheck.md`. - Candidate match keys are defined as strong/medium/weak using message id, conversation/sender ids, timestamp windows, body-present booleans, and safe file metadata. - Default routing remains unchanged: empty/`auto`/`local_readonly` use PacketReader; `msglib_readonly` is explicit only. - Decision: next business node is R2 contact/group search quality hardening. A receive-specific reconciliation helper can be added later before any `auto` merge. --- ### 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:** - [x] **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. - [x] **Step 2: Implement contact ranking/dedup** Implement minimal deterministic ranking in `internal/isphere/contacts.go`. - [x] **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. - [x] **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. **R2 Result:** - Added failing-then-passing tests for contact and group exact-match ranking and case-insensitive de-duplication in `internal/isphere`. - Added failing-then-passing MCP tool tests proving optional MsgLib display entities and log-derived fallback entries merge into one de-duplicated result while preserving `source` and `raw_ref`. - Implemented deterministic ranking: exact ID/display/account match first, prefix match second, substring match after that, then stable case-insensitive ID ordering. - No send-message, send-file, file-download, hook, DB-write, or production side-effect behavior was introduced. - Decision: next business node is R3 receive-file download mapping precheck. --- ### 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. **R3 Result:** - Created `docs/source-discovery/2026-07-10-file-download-mapping-precheck.md`. - PacketReader remains sufficient for file metadata list mode, but has 0 cache path and 0 download keyword hits in the C12 safe count evidence. - MsgLib `TD_ReceiveFileRecord` provides safe attachment metadata (`ReceiveMsgGuid`, filename, size, source id), but current sidecar intentionally returns empty `download_ref` and `file_paths_returned=false`. - Ignored cache evidence shows 11 importal hash-shape files under 32-character hash directories, but no validated message/file-record-to-cache-file mapping. - Decision: do not start R4 yet; insert R3b file cache mapping diagnostic as the next node. --- ### R3b: File cache mapping diagnostic **Purpose:** Prove or reject a safe mapping from MsgLib received-file metadata to local cache files before implementing download mode. **Files:** - Create or modify: `scripts/verify-file-cache-mapping.ps1` or an equivalent local-only diagnostic. - Modify docs: this roadmap, `docs/current-status-card.md`, and `docs/source-discovery/capability-source-matrix.md`. **Diagnostic policy:** - Read copied DB/cache metadata only; do not read attachment contents. - Do not print local paths, raw rows, real message bodies, or unredacted file names. - Output counts, extension groups, hash-directory shape, match strategy counts, and safety booleans only. **Acceptance gate:** - Diagnostic output includes `raw_paths_printed=false`, `file_contents_read=false`, and `file_paths_returned=false`. - Diagnostic chooses one route: R4 cache-file resolver, UI/client download connector, or additional evidence request. **Stop condition:** - If no unique/repeatable cache mapping exists, do not implement R4 download mode. **R3b Result:** - Added `scripts/verify-file-cache-mapping.ps1` and `scripts/test-verify-file-cache-mapping.ps1`. - Created `docs/source-discovery/2026-07-10-file-cache-mapping-diagnostic.md`. - Real sanitized diagnostic checked 166 `TD_ReceiveFileRecord` rows and 11 ignored cache/archive candidates. - Match counts were all zero: filename-only, filename+size, unique filename+size, and source-id-to-hash-dir. - Safety booleans stayed false for raw paths, file contents, file paths returned, raw rows, and message body printing. - Decision: R4 remains blocked; continue the broader roadmap at R5 send-message connector discovery. --- ### 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. **R5 Result:** - Created `docs/source-discovery/2026-07-10-send-message-connector-selection.md`. - No existing bridge/API/local service was found in committed code or docs. - Current WinHelper supports only `version`, `self_check`, `scan_windows`, and `dump_uia`; no click/type/draft/send helper op exists. - Current UIA selector catalog is read-only locate only and does not prove conversation-open, editor, send-button, or post-send confirmation selectors. - Current network/log evidence supports receive/transport analysis, but not an authorized sent-message request/ack contract. - Decision: no connector selected; R6/R7/R8 write-side implementation is blocked pending an exact bridge/API, UIA action-chain, or network/protocol evidence package. --- ### R5b: Returned live-probe evidence intake **Purpose:** Consume the returned `ISphereLiveProbeRecorder` package and decide whether the send connector has enough runtime evidence to move from generic blocked status to a non-mutating preflight node. **Files:** - Create: `docs/source-discovery/2026-07-10-returned-live-probe-analysis.md` - Modify: `docs/source-discovery/capability-source-matrix.md` - Modify: this roadmap and `docs/current-status-card.md` **Evidence checked:** - `probe_client_runtime.json` - `filesystem_inventory.json` - `network_inventory.json` - `scan_windows.json` - `uia/*.json` - `services_registry_shortcuts.json` **Acceptance gate:** - The note states B1/B2/A-route status separately. - Production `isphere_send_message` and `isphere_send_file` remain blocked unless runtime send entrypoint reachability and success/ack evidence are proven. - The next node is either B-route entrypoint preflight, A-route fallback preflight, or another evidence request. **R5b Result:** - Created `docs/source-discovery/2026-07-10-returned-live-probe-analysis.md`. - B1 runtime discovery passes: one x86 `IMPlatformClient.exe` `4.1.2.6842` process, install path family, .NET/WPF/CEF evidence, and live TCP endpoint were observed. - B2 file presence partially passes: live install contains `IMPlatformClient.exe`, `smack.dll`, `IMPP.Interface.dll`, `IMPP.Service*.dll`, `IMPP.UI.dll`, `TcpFileTransfer.dll`, `INetwork.dll`, and `IOClientNetwork.dll`. - B2 runtime entrypoint reachability remains unproven: the process module list did not show `IMPP.*`, `smack.dll`, or file-transfer assemblies as currently loaded. - A-route fallback evidence improved: UIA finds main search edit `skinAlphaTxt`, chat send document `rtbSendMessage`, send button `btnSend`, and `发送文件` menu controls. - Production send remains blocked: the chat captures explicitly show an offline-send blocker and no send success/ack or idempotency evidence. - Decision: next node is R6a/C31 non-mutating send connector preflight. --- ### R6a: Non-mutating send connector preflight **Purpose:** Prove whether B route can continue through a read-only entrypoint probe and whether A route can reliably classify search/edit/send/file controls and offline-state blockers. **Files:** - Modify: `native/ISphereWinHelper/*` if adding helper op `probe_send_entrypoints` or a UIA send-control classifier. - Modify: `internal/helperclient/*` and tests only if Go needs to call the new helper op. - Modify: `docs/go-csharp-helper-boundary.md`, this roadmap, `docs/current-status-card.md`, and `docs/source-discovery/capability-source-matrix.md`. **Execution policy:** - No message send. - No file upload. - No UI click/type. - No process injection/hook. - No network capture. - Reflection/metadata inspection is allowed against copied or installed binaries. - UIA inspection is allowed only for locating controls and reading offline/disabled state. **Acceptance gate:** - `probe_send_entrypoints` or equivalent metadata evidence reports availability for: - `AppContextManager.SendTxtMessageByJid`; - `MessageScheduling.SendChatMessage`; - `com.vision.smack.Chat.SendMessage`; - file-upload/file-message candidates such as `FileTransfer.FileUpload` and `OffLineFileSend`. - UIA preflight reports whether `skinAlphaTxt`, `rtbSendMessage`, `btnSend`, and `发送文件` controls are present and whether an offline-send blocker is visible. - The result chooses one next node: B-route dry-run, A-route draft-only preflight, or another live evidence request. **Stop condition:** - If entrypoints cannot be confirmed or the live client remains offline, do not start R6 production send. **R6a Result:** - Created `docs/source-discovery/2026-07-10-send-connector-preflight.md`. - Added C# WinHelper `0.4.0` read-only op `probe_send_entrypoints`. - Added C# WinHelper `0.4.0` read-only op `probe_send_uia_controls`. - Updated `ISphereLiveProbeRecorder` to include `send_entrypoints_preflight.json` and `send_uia_controls_preflight.json`. - Manual copied-install metadata probe reports `required_available_count=5`, `all_required_available=true`, and `b_route_entrypoint_preflight="pass"`. - Synthetic UIA classifier smoke reports `A_ROUTE_OFFLINE_BLOCKED`, matching the R5b live evidence pattern where offline-send blockers must stop production send. - Decision: next node is R6b B-route preview/dry-run contract. Production `isphere_send_message` and `isphere_send_file` remain blocked. --- ### R6b: B-route preview/dry-run contract **Purpose:** Add only the non-sending contract layer needed before any real send attempt: target ref input, content/hash/idempotency validation, connector metadata, and local audit for preview/dry-run. **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"` or equivalent dry-run returns `send_status="planned"` and never invokes helper send, UI click/type, network capture, upload, or hook. - `execution_mode="production"` remains rejected until a later sandbox-send gate passes. - `idempotency_key` and `content_sha256` are validated even in preview so the final production shape does not drift. - Audit stores target ref, connector, connector stage, content hash, idempotency key hash/ref, and status; it must not store raw message body. **Acceptance gate:** - MCP tool list can include `isphere_send_message` only if it is preview/dry-run blocked from production. - Preview test passes and proves no connector side effects. - Production request is rejected with a clear blocked status. - Standard verification still passes with deterministic no-send behavior. **Stop condition:** - If target refs cannot be represented without raw local evidence values, stop and add a target-ref design note before coding production-facing arguments. **R6b Result:** - Added preview-only `isphere_send_message` in `internal/tools/isphere_send_message.go`. - Registered the tool in `internal/mcpserver/server.go`. - Added TDD tests proving preview returns `send_status="planned"` with no raw content leak, production returns `send_status="blocked"` with no side effects, and content hash mismatch is rejected. - Updated `scripts/verify-go-mcp.ps1` to verify the 9-tool MCP surface, send preview behavior, and `production_send_enabled=false`. - Preview audit appends JSONL through `ISPHERE_SEND_AUDIT_PATH` or the default ignored `runs/send-audit/send-message-preview.jsonl` path. Audit stores content hash and idempotency-key hash, not raw body or raw key. - Decision: next node is R6c online sandbox-send evidence gate. Production send and send-file remain blocked. --- ### R6c: Online sandbox-send evidence gate **Purpose:** Collect or prepare the minimum online sandbox evidence needed before enabling any production send path. **Files:** - Create or modify: `docs/source-discovery/2026-07-10-send-sandbox-gate.md` - Modify optional recorder/helper scripts only if a non-mutating or operator-approved sandbox-send evidence package is required. - Modify docs: this roadmap, `docs/current-status-card.md`, and `docs/source-discovery/capability-source-matrix.md`. **Evidence required:** - One explicit sandbox target only. - One content hash only. - One idempotency key only. - Observed success/ack or local sent-record evidence. - Duplicate retry with the same idempotency key is rejected locally. - Captured evidence contains method names, argument shape, IDs/hashes, status booleans, and refs only; no raw message body needs to be committed. **Acceptance gate:** - A clear decision says whether production `isphere_send_message` can start, remains blocked, or needs a new online package. - No production send behavior is enabled by this node unless the evidence gate has passed. **Stop condition:** - If the environment cannot log in or cannot use a sandbox target, stop and request a returned sandbox evidence package rather than implementing production send. --- ### R6: Send-message preview and production path **Purpose:** Implement production `isphere_send_message` after R6c proves success/ack behavior. **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`.