isphere-ai-bridge/docs/superpowers/plans/2026-07-10-core-business-capabilities-roadmap.md

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	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; 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; 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:

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:

# 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:

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

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.

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:

• Step 1: Add failing contact ranking test

Target behavior:

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:

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:

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

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:

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:

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.