Unclassified

IntegrateWise System-Gap Execution Roadmap

Objective

Convert the existing architecture into a demonstrably reliable governed-continuity platform: every user-visible action must be authorized, durable, reconciled, auditable, and readable back through the Workbench.

Completion Definition

The program is complete when a production-like environment proves this golden path end to end:

Authenticate → resolve tenant and authority → ingest provider event → normalize → promote canonical context to Spine → refresh projection → render Workbench → propose governed action → approve or deny → execute provider action → reconcile outcome → persist evidence/audit → read verified state back in UI.

No action may display durable success before authoritative readback confirms the expected terminal or observing state.

Workstreams

1. Stabilize Runtime Truth

Goal: Remove every known placeholder, fake completion path, and unimplemented production route.

Actions

  • Inventory all TODO, FIXME, stub, mock-only, “not implemented,” and placeholder execution paths across apps, packages, and services.
  • Classify each item as: release blocker, feature-flagged beta, internal-only, or dead code slated for removal.
  • Implement the Spine timeline persistence path, including durable write, idempotency, provenance, and readback.
  • Complete Sales Workbench Twin query, assignment, and approval-flow handlers; otherwise hide them behind feature flags with explanatory disabled states.
  • Remove or safely gate every generic “Section not implemented” route.
  • Validate all hostnames, Gateway endpoints, routes, environment bindings, and service contracts in a deployable environment.

Exit criteria

  • No production route exposes an unfinished implementation.
  • No material mutation uses local-only or placeholder persistence.
  • All live routes resolve against deployed service endpoints.

2. Establish Canonical Command Lifecycle

Goal: Make every material command follow one authoritative, observable lifecycle.

Actions

  • Standardize command states: DRAFT, PROPOSED, PENDING_APPROVAL, APPROVED, DENIED, DISPATCHED, OBSERVING, VERIFIED, FAILED, COMPENSATION_REQUIRED, COMPENSATED.
  • Define command contracts for correlation ID, tenant ID, actor/delegation, capability grant, idempotency key, policy decision, evidence references, and reconciliation record.
  • Enforce server-derived tenant, authority, and policy context for every mutation.
  • Block completion UI until reconciliation produces durable readback.
  • Ensure failed evidence/audit writes fail closed for material operations.

Exit criteria

  • Every material command is traceable across UI, Gateway, policy, execution, reconciliation, Spine, and audit.
  • A command cannot become “complete” without verifiable terminal-state evidence.

3. Complete Provider and MCP Resilience

Goal: Ensure the product is safe and usable when integrations degrade.

Actions

  • Add designed degraded states for MCP Pool outage, provider outage, connector authentication failure, slow hydration, and partial data availability.
  • Implement safe read-only cache fallback only where freshness and authorization rules permit it.
  • Add retry actions with bounded backoff, correlation IDs, user-visible status, and idempotency protection.
  • Expose connector health, freshness, last successful sync, last error, and recommended remediation in Workbench views.
  • Ensure unavailable execution controls are disabled rather than optimistically invoked.

Exit criteria

  • Every MCP-backed or connector-backed view has loading, empty, error, degraded, recovery, and permission-denied states.
  • Provider/MCP failures cannot create false-success UI outcomes.

4. Harden Frontend State and UX

Goal: Make the Workbench a truthful projection of platform state.

Actions

  • Define a shared frontend state model for command, approval, reconciliation, hydration, connector-health, and evidence states.
  • Replace unbounded optimistic updates with authoritative post-mutation readback for all governed actions.
  • Add visible provenance, freshness, audit/evidence links, policy reason, approval status, and reconciliation status to material Workbench actions.
  • Create a route-readiness matrix: route owner, API/service, data source, fallback behavior, mutations, audit visibility, reconciliation visibility, automated test, and release status.
  • Clarify ownership between web, workspace, platform, platform-console, one-access, and one-access-console.

Exit criteria

  • Each production route declares its source of truth and failure behavior.
  • UI states accurately distinguish queued, observing, verified, failed, and compensated actions.

5. Repair Monorepo Governance

Goal: Ensure every runnable production component is included in standard engineering controls.

Actions

  • Verify that apps, packages, services, mcp, marketplace, and all deployable subprojects are deliberately included or excluded from workspace orchestration.
  • Create a machine-readable component catalog covering owner, maturity, deployment unit, interfaces, inbound dependencies, outbound dependencies, data stores, and retirement status.
  • Enforce dependency direction: apps → packages/contracts; services → packages/contracts; prohibit packages from importing services; prohibit UI from direct provider calls.
  • Remove or quarantine backup/reference directories from build, import, deployment, and documentation discovery paths.
  • Make architecture checks, contract checks, and governed-chain checks required CI gates.

Exit criteria

  • Every production component is covered by install, build, typecheck, lint, test, security, and release policy.
  • Dependency violations fail CI.

6. Build Real End-to-End Proof

Goal: Replace visibility-only tests with deployed, durable workflow verification.

Actions

  • Provision an isolated, production-like E2E environment with real service bindings, tenant-scoped stores, and provider sandbox/test doubles.
  • Build one Playwright golden-path spec covering authentication, ingestion, normalization, Spine promotion, projection, governed action, approval, dispatch, reconciliation, audit, and UI readback.
  • Seed test data only through real ingestion or supported setup APIs; do not directly seed final UI projections.
  • Add independent assertions against provider test double, reconciliation record, Spine entity/timeline, projection API, audit API, and browser UI.
  • Replace fixed sleeps with polling on correlation IDs and terminal-state predicates.
  • Add negative-path suites for denial, expired delegation, duplicate webhook, retry, provider timeout, provider rejection, compensation, MCP outage, and cross-tenant access attempts.

Exit criteria

  • E2E tests prove the golden path and each critical failure path in CI.
  • Browser success assertions are backed by durable service and data-store readback.

7. Operationalize Observability

Goal: Make failures diagnosable across distributed workflows.

Actions

  • Require a correlation ID from browser intent through Gateway, capability, governance, provider dispatch, reconciliation, Spine update, and audit.
  • Publish a trace view for operators showing state transitions, policy decisions, retries, provider responses, and evidence links.
  • Define SLOs for API availability, ingestion latency, projection freshness, command completion, reconciliation delay, and provider error rate.
  • Add alerts for failed reconciliation, audit-write failure, endpoint contract drift, connector degradation, and E2E regression.

Exit criteria

  • An operator can explain any material command outcome without manual log archaeology.

Phased Plan

Phase 0: Baseline and Freeze — Week 1

  • Appoint accountable owners for runtime, frontend, data/Spine, integrations, test platform, and release.
  • Run a repository-wide implementation inventory and mark release blockers.
  • Freeze new user-facing workflow features until known placeholder paths are classified.
  • Produce the component catalog and route-readiness matrix.

Deliverables: gap register, ownership map, route matrix, component catalog, release-blocker list.

Phase 1: Correctness Foundation — Weeks 2–4

  • Implement timeline persistence and mutation readback.
  • Resolve broken routes/endpoints and environment bindings.
  • Finish or feature-gate unfinished Sales Workbench actions and generic routes.
  • Standardize command and reconciliation contracts.
  • Make audit/evidence failure behavior explicit and fail closed for material operations.

Deliverables: no-placeholder release candidate, canonical command lifecycle, verified persistence tests.

Phase 2: Resilient Product Experience — Weeks 3–6

  • Ship MCP/connector degraded modes, fallback rules, and connector-health surfaces.
  • Add frontend lifecycle state components and authoritative mutation refresh.
  • Add provenance, approval, reconciliation, and evidence presentation for key workflows.
  • Complete product-surface ownership definitions.

Deliverables: resilient Workbench UX, route readiness enforced, truthful state presentation.

Phase 3: E2E and CI Enforcement — Weeks 5–8

  • Stand up the isolated E2E environment.
  • Implement golden-path Playwright and service-readback tests.
  • Add failure/compensation/isolation suites.
  • Require architecture, governed-chain, contract, deployment-policy, and E2E gates before promotion.

Deliverables: CI-enforced golden path, failure-path coverage, release evidence package.

Phase 4: Operability and Scale — Weeks 8–10

  • Add correlation/trace view, SLO dashboards, and alerting.
  • Tune test parallelism and resource limits for deterministic CI.
  • Conduct a production-readiness review using evidence from real deployments and E2E runs.

Deliverables: operator traceability, SLOs, alerting, production-go decision record.

Prioritized Backlog

P0 — Release blockers

  • Replace timeline placeholder with durable Supabase persistence and readback.
  • Complete or disable unfinished Workbench actions and unimplemented routes.
  • Fix unresolved hostnames, API routes, and deployment bindings.
  • Add MCP Pool and connector outage UX.
  • Create the deployed golden-path E2E suite.
  • Make governance, architecture, and E2E checks mandatory CI gates.

P1 — Required for trustworthy operations

  • Add command lifecycle contract and universal correlation IDs.
  • Surface approval, policy, reconciliation, provenance, and audit states in UI.
  • Add duplicate-event, failed-provider, retry, compensation, and cross-tenant tests.
  • Publish component ownership and dependency catalog.

P2 — Scale and maintainability

  • Consolidate or formally separate overlapping apps/services/packages.
  • Build operator trace explorer and SLO dashboards.
  • Standardize Product Package templates and automated contract scaffolding.
  • Remove legacy backups/reference artifacts from active engineering paths.

Metrics

  • 100% of production routes have an owner, readiness status, data source, and automated test.
  • 100% of material mutations have correlation ID, audit evidence, reconciliation state, and verified readback.
  • 0 exposed placeholder routes or ungated TODO actions in production.
  • 100% of deployable components are covered by monorepo checks and release policy.
  • Golden-path E2E pass rate: at least 99% over the last 50 CI runs before production promotion.
  • Cross-tenant isolation suite: 100% pass, zero tolerated exceptions.
  • False-success rate for governed mutations: 0.

Governance Cadence

  • Daily: P0 blocker review with named owners and evidence links.
  • Twice weekly: golden-path walkthrough in the E2E environment.
  • Weekly: architecture boundary, package dependency, and route-readiness review.
  • Before release: evidence-based go/no-go review; no self-attestation without deployed test and readback evidence.