{"slug":"internal/architecture/ROUND_3_DEEP_EXCAVATION_PLAN","title":"Round 3 — Deep Excavation Execution Plan","section":"internal","sectionLabel":"Internal","status":"unclassified","type":"document","path":"internal/architecture/ROUND_3_DEEP_EXCAVATION_PLAN.mdx","bytes":7526,"description":null,"updated":null,"source":"integratewise/Integratewise-docs-wiki","content":"\n**Date:** 2026-07-30  \n**Basis:** Three parallel deep audits of codebase, deployment readiness, and activation flow  \n**Status:** Ready to execute\n\n---\n\n## Deep Excavation Findings\n\n### What's REAL (verified)\n\n| Component                 | Status    | Evidence                                                                                 |\n| ------------------------- | --------- | ---------------------------------------------------------------------------------------- |\n| **19 MCP tools defined**  | ✅ REAL   | `packages/spine-network/src/index.ts` TOOLS array (19 declarations)                      |\n| **Gateway routing**       | ✅ REAL   | 15+ service bindings, all routes mounted and proxying                                    |\n| **Spine D1 routes**       | ✅ REAL   | EntityStore with real SQL queries                                                        |\n| **Spine Neon routes**     | ✅ REAL   | `neon-workbench.ts` queries real PostgreSQL tables                                       |\n| **Intelligence service**  | ✅ REAL   | ~134KB, think/act/govern/agents sub-modules all wired                                    |\n| **65+ connectors**        | ✅ REAL   | 14 categories in `packages/connectors/src/`                                              |\n| **OAuth auth server**     | ✅ REAL   | `oauth-auth-server.ts` with authorization_code, client_credentials, refresh_token grants |\n| **OAuth client registry** | ✅ REAL   | D1-backed `oauth_clients.ts`                                                             |\n| **Context boundary**      | ✅ REAL   | `context-boundary.ts` with purpose/scope/authority/expiry                                |\n| **MCP server dispatch**   | ✅ REAL   | `mcp-server.ts` with tool filtering by scope                                             |\n| **Frontend pages**        | ✅ REAL   | 15+ pages: app, marketplace, onboarding, governance, settings, etc.                      |\n| **GitHub Actions CI**     | ✅ EXISTS | `ci.yml`, `deploy-cloudflare.yml`, `deploy-workers.yml`                                  |\n| **wrangler.toml**         | ✅ EXISTS | Gateway, Spine, Pipeline, Hermes all configured                                          |\n| **.env.example**          | ✅ EXISTS | Comprehensive config template                                                            |\n\n### What's MISSING (gaps found)\n\n| Component                               | Status                  | Impact                                                                   |\n| --------------------------------------- | ----------------------- | ------------------------------------------------------------------------ |\n| **governance-state service**            | ❌ MISSING              | Directory exists but no `index.ts`; code is in `intelligence/govern/`    |\n| **marketplace-installation service**    | ❌ EMPTY                | Directory exists, no .ts files; contract exists in `packages/contracts/` |\n| **WorkspaceDiscoveryResponse endpoint** | ❌ MISSING              | Contract exists but no dedicated endpoint generating it                  |\n| **DNS records**                         | ❌ 5 subdomains missing | gateway, api, workbench, marketplace, status                             |\n| **Clerk production keys**               | ❌ NOT SET              | `CLERK_SECRET_KEY` not in `.env`                                         |\n| **D1/KV/Queue/R2 provisioning**         | ❌ NOT DONE             | No `wrangler d1 create` etc.                                             |\n| **.env file**                           | ❌ MISSING              | Only `.env.example` exists                                               |\n\n### What's STUBBED (partial implementations)\n\n| Component                    | Status           | Detail                                                                                           |\n| ---------------------------- | ---------------- | ------------------------------------------------------------------------------------------------ |\n| **MCP tool implementations** | ⚠️ PARTIAL       | 7 handler cases in `handleToolCall`; 12 tools have declarations but may lack full implementation |\n| **Marketplace activation**   | ⚠️ CONTRACT ONLY | `MarketplaceInstallation` state machine defined; no runtime service implementing it              |\n| **Workspace discovery**      | ⚠️ CONTRACT ONLY | `WorkspaceDiscoveryResponse` type exists; no endpoint returning it                               |\n| **Customer Zero detection**  | ⚠️ PARTIAL       | `isCustomerZeroEmail()` exists; runtime isolation not proven end-to-end                          |\n\n---\n\n## Execution Plan\n\n### Phase 1: Wire the 19-Tool MCP Contract (immediate)\n\n**Goal:** Make all 19 tools callable end-to-end through Gateway → MCP Connector\n\n1. **Verify all 19 tools have implementations** in `continuity-bridge.ts`\n2. **Add missing tool handlers** for any stubbed tools\n3. **Wire Gateway route** `/api/v1/spine-network/*` → MCP_CONNECTOR (already done)\n4. **Test each tool** via MCP protocol through Gateway\n5. **Verify tool count** in list_tools response = 19\n\n### Phase 2: Build Marketplace Installation Runtime\n\n**Goal:** Complete the activation flow from \"user clicks install\" to \"19 tools available\"\n\n1. **Create `services/marketplace-installation/src/index.ts`** implementing:\n   - `POST /api/v1/marketplace/installations` — start installation\n   - `GET /api/v1/marketplace/installations/:id` — check status\n   - `POST /api/v1/marketplace/installations/:id/activate` — activate\n   - State machine: `initiated → identity_required → workspace_required → consent_required → binding → hydrating → active`\n2. **Wire Gateway route** `/api/v1/marketplace/*` → MARKETPLACE_INSTALLATION\n3. **Implement tenant provisioning** in the activation flow\n4. **Implement connector binding** in the activation flow\n\n### Phase 3: Build Workspace Discovery Endpoint\n\n**Goal:** Return `WorkspaceDiscoveryResponse` from real Neon queries\n\n1. **Implement `GET /api/v1/workspace/discovery`** in Spine\n2. **Query real Neon tables**: connectors, entities, proposals, memories\n3. **Wire Gateway route** `/api/v1/workspace/discovery` → SPINE\n4. **Frontend calls** this endpoint first after activation\n\n### Phase 4: Prove End-to-End for Customer Zero\n\n**Goal:** Clean install → 19 tools → governed action cycle\n\n1. **Provision Customer Zero resources**: D1, KV, Queue, R2\n2. **Set Clerk production keys** in Cloudflare Workers\n3. **Apply migrations** to D1\n4. **Deploy Workers** via `wrangler deploy`\n5. **Test activation flow** end-to-end\n6. **Test each of the 19 tools** through Gateway\n7. **Test governed action cycle**: Proposal → approval → execution → outcome\n\n---\n\n## Commit Strategy\n\nEach phase gets its own commit:\n\n```\nPhase 1: feat(mcp-connector): wire 19-tool MCP contract end-to-end\nPhase 2: feat(marketplace): implement installation runtime service\nPhase 3: feat(spine): implement workspace discovery endpoint\nPhase 4: chore(deploy): provision Customer Zero resources and verify\n```\n\n---\n\n## Priority Order\n\n```\nPhase 1 (19-tool wiring) — can start NOW, no external deps\nPhase 3 (workspace discovery) — can start NOW, no external deps\nPhase 2 (marketplace installation) — can start NOW, no external deps\nPhase 4 (Customer Zero proof) — BLOCKED on DNS/Clerk/provisioning\n```\n\n**Phases 1-3 are executable immediately.** Phase 4 requires external provisioning.\n"}