Round 3 — Deep Excavation Execution Plan

Date: 2026-07-30
Basis: Three parallel deep audits of codebase, deployment readiness, and activation flow
Status: Ready to execute

---

Deep Excavation Findings

What's REAL (verified)

Component	Status	Evidence
19 MCP tools defined	✅ REAL	packages/spine-network/src/index.ts TOOLS array (19 declarations)
Gateway routing	✅ REAL	15+ service bindings, all routes mounted and proxying
Spine D1 routes	✅ REAL	EntityStore with real SQL queries
Spine Neon routes	✅ REAL	neon-workbench.ts queries real PostgreSQL tables
Intelligence service	✅ REAL	~134KB, think/act/govern/agents sub-modules all wired
65+ connectors	✅ REAL	14 categories in packages/connectors/src/
OAuth auth server	✅ REAL	oauth-auth-server.ts with authorization_code, client_credentials, refresh_token grants
OAuth client registry	✅ REAL	D1-backed oauth_clients.ts
Context boundary	✅ REAL	context-boundary.ts with purpose/scope/authority/expiry
MCP server dispatch	✅ REAL	mcp-server.ts with tool filtering by scope
Frontend pages	✅ REAL	15+ pages: app, marketplace, onboarding, governance, settings, etc.
GitHub Actions CI	✅ EXISTS	ci.yml, deploy-cloudflare.yml, deploy-workers.yml
wrangler.toml	✅ EXISTS	Gateway, Spine, Pipeline, Hermes all configured
.env.example	✅ EXISTS	Comprehensive config template

What's MISSING (gaps found)

Component	Status	Impact
governance-state service	❌ MISSING	Directory exists but no index.ts; code is in intelligence/govern/
marketplace-installation service	❌ EMPTY	Directory exists, no .ts files; contract exists in packages/contracts/
WorkspaceDiscoveryResponse endpoint	❌ MISSING	Contract exists but no dedicated endpoint generating it
DNS records	❌ 5 subdomains missing	gateway, api, workbench, marketplace, status
Clerk production keys	❌ NOT SET	CLERK_SECRET_KEY not in .env
D1/KV/Queue/R2 provisioning	❌ NOT DONE	No wrangler d1 create etc.
.env file	❌ MISSING	Only .env.example exists

What's STUBBED (partial implementations)

Component	Status	Detail
MCP tool implementations	⚠️ PARTIAL	7 handler cases in handleToolCall; 12 tools have declarations but may lack full implementation
Marketplace activation	⚠️ CONTRACT ONLY	MarketplaceInstallation state machine defined; no runtime service implementing it
Workspace discovery	⚠️ CONTRACT ONLY	WorkspaceDiscoveryResponse type exists; no endpoint returning it
Customer Zero detection	⚠️ PARTIAL	isCustomerZeroEmail() exists; runtime isolation not proven end-to-end

---

Execution Plan

Phase 1: Wire the 19-Tool MCP Contract (immediate)

Goal: Make all 19 tools callable end-to-end through Gateway → MCP Connector

1. Verify all 19 tools have implementations in continuity-bridge.ts
2. Add missing tool handlers for any stubbed tools
3. Wire Gateway route /api/v1/spine-network/* → MCP_CONNECTOR (already done)
4. Test each tool via MCP protocol through Gateway
5. Verify tool count in list_tools response = 19

Phase 2: Build Marketplace Installation Runtime

Goal: Complete the activation flow from "user clicks install" to "19 tools available"

1. Create services/marketplace-installation/src/index.ts implementing:
   • POST /api/v1/marketplace/installations — start installation
   • GET /api/v1/marketplace/installations/:id — check status
   • POST /api/v1/marketplace/installations/:id/activate — activate
   • State machine: initiated → identity_required → workspace_required → consent_required → binding → hydrating → active
2. Wire Gateway route /api/v1/marketplace/* → MARKETPLACE_INSTALLATION
3. Implement tenant provisioning in the activation flow
4. Implement connector binding in the activation flow

Phase 3: Build Workspace Discovery Endpoint

Goal: Return WorkspaceDiscoveryResponse from real Neon queries

1. Implement GET /api/v1/workspace/discovery in Spine
2. Query real Neon tables: connectors, entities, proposals, memories
3. Wire Gateway route /api/v1/workspace/discovery → SPINE
4. Frontend calls this endpoint first after activation

Phase 4: Prove End-to-End for Customer Zero

Goal: Clean install → 19 tools → governed action cycle

1. Provision Customer Zero resources: D1, KV, Queue, R2
2. Set Clerk production keys in Cloudflare Workers
3. Apply migrations to D1
4. Deploy Workers via wrangler deploy
5. Test activation flow end-to-end
6. Test each of the 19 tools through Gateway
7. Test governed action cycle: Proposal → approval → execution → outcome

---

Commit Strategy

Each phase gets its own commit:

Phase 1: feat(mcp-connector): wire 19-tool MCP contract end-to-end
Phase 2: feat(marketplace): implement installation runtime service
Phase 3: feat(spine): implement workspace discovery endpoint
Phase 4: chore(deploy): provision Customer Zero resources and verify

---

Priority Order

Phase 1 (19-tool wiring) — can start NOW, no external deps
Phase 3 (workspace discovery) — can start NOW, no external deps
Phase 2 (marketplace installation) — can start NOW, no external deps
Phase 4 (Customer Zero proof) — BLOCKED on DNS/Clerk/provisioning

Phases 1-3 are executable immediately. Phase 4 requires external provisioning.