docs: replan core business capabilities
This commit is contained in:
zhaoyilun
@@ -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`.
|
||||
Reference in New Issue
Block a user